docs: edit and expand command docs

Author: jbogarthyde

packages/angular/cli/commands/build-long.md

@@ -1,3 +1,13 @@
+Uses the Webpack build tool, with default target environment and build options specified in the workspace configuration file, `angular.json`.
+
+You can override the configuration defaults by specifying an option on the command line. 
+The command can accept option names given in either dash-case or camelCase.
+Note that in the configuration file, you must specify names in camelCase.
+
+The configuration options generally correspond to the command options.
+Some additional options can only be set through the configuration file,
+either by direct editing or with the `ng config` command.
+These include `assets`, `styles`, and `scripts` objects that provide runtime-global resources to include in the project. 
 Resources in CSS, such as images and fonts, are automatically written and fingerprinted at the root of the output folder.
 
-Uses the Webpack build tool, with environment and build options specified in the CLI configuration file.
+For further details, see Workspace Configuration.

packages/angular/cli/commands/config.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/schema",
   "$id": "ng-cli://commands/config.json",
-  "description": "Retrieves or sets Angular configuration values.",
+  "description": "Retrieves or sets Angular configuration values in the angular.json file for the workspace.",
   "$longDescription": "",
 
   "$aliases": [],

packages/angular/cli/commands/definitions.json

@@ -14,14 +14,14 @@
           }
         },
         "configuration": {
-          "description": "A named configuration environment, as specified in the \"configurations\" section of angular.json.",
+          "description": "A named build target, as specified in the \"configurations\" section of angular.json.\nEach named target is accompanied by a configuration of option defaults for that target.",
           "type": "string",
           "aliases": [
             "c"
           ]
         },
         "prod": {
-          "description": "When true, sets the build configuration to the production environment.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination using UglifyJS.",
+          "description": "When true, sets the build configuration to the production target.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination using UglifyJS.",
           "type": "boolean"
         }
       }
@@ -42,13 +42,13 @@
           "type": "boolean",
           "default": false,
           "aliases": [ "d" ],
-          "description": "When true, run through and report activity without writing out results."
+          "description": "When true, runs through and reports activity without writing out results."
         },
         "force": {
           "type": "boolean",
           "default": false,
           "aliases": [ "f" ],
-          "description": "When true, force overwriting of existing files."
+          "description": "When true, forces overwriting of existing files."
         },
         "interactive": {
           "type": "boolean",

packages/angular/cli/commands/lint-long.md

@@ -1,2 +1,4 @@
 Takes the name of the project, as specified in the  `projects` section of the `angular.json` workspace configuration file.
-When a project name is not supplied, uses the configured `defaultProject` of the workspace.
+When a project name is not supplied, uses the configured `defaultProject` of the workspace.
+
+The default linting tool is [TSLint](https://palantir.github.io/tslint/), and the default configuration is specified in the project's `tslint.json` file.

packages/angular/cli/commands/lint.json

@@ -22,7 +22,7 @@
           }
         },
         "configuration": {
-          "description": "Specify the configuration to use.",
+          "description": "The linting configuration to use.",
           "type": "string",
           "aliases": [
             "c"

packages/angular/cli/commands/new.json

@@ -16,13 +16,13 @@
         "collection": {
           "type": "string",
           "aliases": [ "c" ],
-          "description": "Schematics collection to use."
+          "description": "A collection of schematics to use in generating the initial app."
         },
         "verbose": {
           "type": "boolean",
           "default": false,
           "aliases": [ "v" ],
-          "description": "Adds more details to output logging."
+          "description": "When true, adds more details to output logging."
         }
       },
       "required": []

packages/angular/cli/commands/run-long.md

@@ -0,0 +1,8 @@
+Architect is the tool that the CLI uses to perform complex tasks such as compilation, according to provided configurations.
+The CLI commands run Architect targets such as `build`, `serve`, `test` and `lint`. 
+Each named target has a default configuration, specified by an "options" object, and an optional set of named alternate configurations in the "configurations" object. 
+For example, the "build" target for a newly generated app has a predefined alternate configuration named "production". 
+
+You can define new targets and their configuration options in the "architect" section of the `angular.json` file.
+If you do so, you can run them from the command line using the `ng run` command.
+

packages/angular/cli/commands/run.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/schema",
   "$id": "ng-cli://commands/run.json",
-  "description": "Runs a custom target defined in your project.",
+  "description": "Runs an architect target with a custom build configuration defined in your project.",
   "$longDescription": "",
 
   "$aliases": [],
@@ -15,14 +15,14 @@
       "properties": {
         "target": {
           "type": "string",
-          "description": "The target to run.",
+          "description": "The command to run.",
           "$default": {
             "$source": "argv",
             "index": 0
           }
         },
         "configuration": {
-          "description": "Specify the configuration to use.",
+          "description": "A named build configuration, defined in the \"configurations\" section of angular.json.\nThe build uses the configuration associated with the given target.",
           "type": "string",
           "aliases": [ "c" ]
         }