[improve-docs] Explain what the root package is, refs #500

doc/02-libraries.md

@@ -151,11 +151,11 @@ packagist is available automatically through composer. Since monolog
 [is on packagist](http://packagist.org/packages/monolog/monolog), we can depend
 on it without having to specify any additional repositories.
 
-Assuming we want to share `hello-world` with the world, we would want to
-publish it on packagist as well. And this is really easy.
+If we wanted to share `hello-world` with the world, we would publish it on
+packagist as well. Doing so is really easy.
 
 You simply hit the big "Submit Package" button and sign up. Then you submit
 the URL to your VCS repository, at which point packagist will start crawling
 it. Once it is done, your package will be available to anyone.
 
-← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →
+← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →

doc/03-cli.md

@@ -218,4 +218,4 @@ some tools like git or curl will only use the lower-cased `http_proxy` version.
 Alternatively you can also define the git proxy using
 `git config --global http.proxy <proxy url>`.
 
-&larr; [Libraries](02-libraries.md)  |  [Schema](04-schema.md) &rarr;
+&larr; [Libraries](02-libraries.md)  |  [Schema](04-schema.md) &rarr;

doc/04-schema.md

@@ -1,13 +1,27 @@
 # composer.json
 
-This chapter will explain all of the options available in `composer.json`.
+This chapter will explain all of the fields available in `composer.json`.
 
 ## JSON schema
 
 We have a [JSON schema](http://json-schema.org) that documents the format and
 can also be used to validate your `composer.json`. In fact, it is used by the
 `validate` command. You can find it at:
-[`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json).
+[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json).
+
+## Root Package
+
+The root package is the package defined by the `composer.json` at the root of
+your project. It is the main `composer.json` that defines your project
+requirements.
+
+Certain fields only apply when in the root package context. One example of
+this is the `config` field. Only the root package can define configuration.
+The config of dependencies is ignored. This makes the `config` field
+`root-only`.
+
+If you clone one of those dependencies to work on it, then that package is the
+root package. The `composer.json` is identical, but the context is different.
 
 ## Properties
 
@@ -346,7 +360,7 @@ Example:
         }
     }
 
-### scripts
+### scripts <span>(root-only)</span>
 
 Composer allows you to hook into various parts of the installation process
 through the use of scripts.

doc/05-repositories.md

@@ -274,4 +274,4 @@ You can disable the default Packagist repository by adding this to your
     }
 
 
-← [Schema](04-schema.md)  |  [Community](06-community.md) →
+← [Schema](04-schema.md)  |  [Community](06-community.md) →

doc/06-community.md

@@ -27,4 +27,4 @@ IRC channels are available for discussion as well, on
 irc.freenode.org [#composer](irc://irc.freenode.org/composer) for users and
 [#composer-dev](irc://irc.freenode.org/composer-dev) for development.
 
-← [Repositories](05-repositories.md)
+← [Repositories](05-repositories.md)