Additions to the intro document

Documentation/intro-to-cli.md

@@ -47,7 +47,41 @@ You can get a sense of using the tools from the examples below.
 Design
 ======
 
-More content here.
+There are couple of moving pieces that you make up the general design of the .NET Core CLI:
+
+* The `dotnet` driver
+* Specific commands that are part of the package
+
+The `dotnet` driver is very simple and its primary role is to run the commands and give users basic information about usage. 
+
+The way `dotnet` driver finds the command it is instructed to run using `dotnet {command}` is via convention; any exectuable that is placed in the PATH and is named `dotnet-{command}` will be available to the driver. For example, when you install the CLI toolchain there will be a command called `dotnet-compile` in your PATH; when you run `dotnet compile`, the driver will run `dotnet-compile`. All of the arguments are passed to the command being invoked. 
+
+This is also the basics of the current extensibility model of the toolchain. Any executable found in the PATH named in this way will be invoked by the `dotnet` driver. 
+
+There are some principles that we are using when adding new commands:
+
+* Each command is represented by a verb (`run`, `compile`, `publish`, `restore` etc.)
+* We support the short and the long form of switches for most commands
+* The switches have the same format on all supported platforms (so, no /-style switches on Windows for example)
+* Each command has a help that can be viewed
+
+Adding a new command to the .NET Core CLI 
+=========================================
+
+If you want to contribute to the actual .NET Core CLI by adding a new command that you think would be useful, please refer to the [developer guide](developer-guide.md) in this directory. It contains all of the guidance on both the process as well as the infrastructure that is provided in t
+
+Adding a new command locally
+============================ 
+Given the extensibility model described above, it is very easy to add a command that can be invoked with the `dotnet` driver. Just add any executable in a PATH and name it appropriatelly. 
+
+Guidances on how to write a command 
+===================================
+How do you write a given command depends largely on whether you are trying to add it to the CLI project or are writing an addition outside of it. 
+
+In the first case, the [developer guide](developer-guide.md) has all of the details on the styles and the infrastructure that is provided and that you can (and need) to use to implement new commands. 
+
+If you are adding a command on your own machine(s), then any model of doing things is available to you. However, since your users will be using the local commands through `dotnet` driver, it would be preferable to keep the style consistent to the one described in the deisgn section above. 
+
 
 
 

README.md

@@ -67,10 +67,16 @@ On Mac OSX, we currently support the C++ Codegenerator (as shown below) and supp
 
     dotnet compile --native --cpp
 
-This will drop a native single binary in `./bin/[configuration]/[framework]/native/[binary name]` that you can run.  
+This will drop a native single binary in `./bin/[configuration]/[framework]/native/[binary name]` that you can run.
 
 For more details, please refer to the [documentation](https://github.com/dotnet/corert/tree/master/Documentation).
 
+Building from source
+--------------------
+
+If you are building from source, take note that the build depends on NuGet packages hosted on Myget, so if it is down, the build may fail. If that happens, you can always see the [Myget status page](http://status.myget.org/) for more info.  
+
+
 Questions & Comments
 --------------------