diff --git a/Documentation/known-issues.md b/Documentation/known-issues.md
new file mode 100644
index 000000000..f8d250bc7
--- /dev/null
+++ b/Documentation/known-issues.md
@@ -0,0 +1,62 @@
+Known issues & workarounds
+==========================
+
+## El Capitan support
+If you try to use the `dotnet` commands on El Capitan (OS X 10.11), you will encounter errors as it is not currently 
+fully supported for all scenarios.  
+
+**Issues tracking this:** 
+
+* [#498](https://github.com/dotnet/cli/issues/498)
+* [#291](https://github.com/dotnet/cli/issues/291)
+
+**Affects:** most of the commands, but more than likely you will not be able to 
+use `dotnet compile` and `dotnet-run` on El Capitan. For others, there is a 
+workaround.
+
+**Workaround:** use the --runtime switch with the value of `osx.10.11-x64` in 
+`dotnet restore` and `dotnet publish` and you will be able to run your app from 
+the published directory. 
+
+## Resolving the Standard library packages
+The StdLib package is on a MyGet feed. In order to restore it, a MyGet feed needs to be added 
+to the NuGet feeds, either locally per application or in a central location. 
+
+**Issues tracking this:** 
+
+* [#535](https://github.com/dotnet/cli/issues/535)
+
+**Affects:** `dotnet restore`
+
+**Workaround:** update to the latest bits and run `dotnet new` in an empty directory. This will 
+now drop a `nuget.config` file that you can use in other applications. 
+
+If you cannot update, you can use the following `nuget.config`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <!--To inherit the global NuGet package sources remove the <clear/> line below -->
+    <clear />
+    <add key="dotnet-core" value="https://www.myget.org/F/dotnet-core/api/v3/index.json" />
+    <add key="api.nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+</configuration>
+```
+
+## Uninstalling/reinstalling the PKG on OS X
+OS X doesn't really have an uninstall capacity for PKGs like Windows has for 
+MSIs. There is, however, a way to remove the bits as well as the "recipe" for 
+dotnet. More information can be found on [this SuperUser question](http://superuser.com/questions/36567/how-do-i-uninstall-any-apple-pkg-package-file).
+
+# What is this document about? 
+This document outlines the known issues and workarounds for the current state of 
+the CLI tools. Issues will also have a workaround and affects sections if necessary. You can use this page to 
+get information and get unblocked.
+
+# What is a "known issue"?
+A "known issue" is a major issue that block users in doing their everyday tasks and that affect all or 
+most of the commands in the CLI tools. If you want to report or see minor issues, you can use the [issues list](https://github.com/dotnet/cli/issues). 
+
+  
diff --git a/README.md b/README.md
index 725f271da..6ae0d70c6 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,11 @@ If you are building from source, take note that the build depends on NuGet packa
 
 Also, when building from source, you need to set up the `DOTNET_HOME` environment variable. It needs to point to the parent directory of where `bin` and `runtime` directories are. 
 
+Known issues
+------------
+
+You can also consult the [known issues page](Documentation/known-issues.md) to find out the current issues and 
+to see the workarounds.  
 
 Questions & Comments
 --------------------