docs: explain through run-script

PR-URL: https://github.com/npm/cli/pull/2330
Credit: @isaacs
Close: #2330

18 files changed, 351 insertions, 234 deletions

diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md
index fe7485d61..ec63ec34f 100644
--- a/docs/content/commands/npm-explain.md
+++ b/docs/content/commands/npm-explain.md
@@ -8,6 +8,8 @@ description: Explain installed packages
 
 ```bash
 npm explain <folder | specifier>
+
+alias: why
 ```
 
 ### Description
diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md
index 7c55f18c5..1a835001f 100644
--- a/docs/content/commands/npm-link.md
+++ b/docs/content/commands/npm-link.md
@@ -15,41 +15,44 @@ alias: npm ln
 
 ### Description
 
+This is handy for installing your own stuff, so that you can work on it and
+test iteratively without having to continually rebuild.
+
 Package linking is a two-step process.
 
-First, `npm link` in a package folder will create a symlink in the global folder
-`{prefix}/lib/node_modules/<package>` that links to the package where the `npm
-link` command was executed. It will also link any bins in the package to `{prefix}/bin/{name}`.
-Note that `npm link` uses the global prefix (see `npm prefix -g` for its value).
+First, `npm link` in a package folder will create a symlink in the global
+folder `{prefix}/lib/node_modules/<package>` that links to the package
+where the `npm link` command was executed. It will also link any bins in
+the package to `{prefix}/bin/{name}`.  Note that `npm link` uses the global
+prefix (see `npm prefix -g` for its value).
 
 Next, in some other location, `npm link package-name` will create a
-symbolic link from globally-installed `package-name` to `node_modules/`
-of the current folder.
+symbolic link from globally-installed `package-name` to `node_modules/` of
+the current folder.
 
-Note that `package-name` is taken from `package.json`,
-not from directory name.
+Note that `package-name` is taken from `package.json`, _not_ from the
+directory name.
 
-The package name can be optionally prefixed with a scope. See [`scope`](/using-npm/scope).
-The scope must be preceded by an @-symbol and followed by a slash.
+The package name can be optionally prefixed with a scope. See
+[`scope`](/using-npm/scope).  The scope must be preceded by an @-symbol and
+followed by a slash.
 
 When creating tarballs for `npm publish`, the linked packages are
-"snapshotted" to their current state by resolving the symbolic links.
-
-This is handy for installing your own stuff, so that you can work on it and
-test it iteratively without having to continually rebuild.
+"snapshotted" to their current state by resolving the symbolic links, if
+they are included in `bundleDependencies`.
 
 For example:
 
 ```bash
-    cd ~/projects/node-redis    # go into the package directory
-    npm link                    # creates global link
-    cd ~/projects/node-bloggy   # go into some other package directory.
-    npm link redis              # link-install the package
+cd ~/projects/node-redis    # go into the package directory
+npm link                    # creates global link
+cd ~/projects/node-bloggy   # go into some other package directory.
+npm link redis              # link-install the package
 ```
 
-Now, any changes to ~/projects/node-redis will be reflected in
-~/projects/node-bloggy/node_modules/node-redis/. Note that the link should
-be to the package name, not the directory name for that package.
+Now, any changes to `~/projects/node-redis` will be reflected in
+`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link
+should be to the package name, not the directory name for that package.
 
 You may also shortcut the two steps in one.  For example, to do the
 above use-case in a shorter way:
@@ -69,15 +72,33 @@ npm link redis
 That is, it first creates a global link, and then links the global
 installation target into your project's `node_modules` folder.
 
-Note that in this case, you are referring to the directory name, `node-redis`,
-rather than the package name `redis`.
+Note that in this case, you are referring to the directory name,
+`node-redis`, rather than the package name `redis`.
 
-If your linked package is scoped (see [`scope`](/using-npm/scope)) your link command must include that scope, e.g.
+If your linked package is scoped (see [`scope`](/using-npm/scope)) your
+link command must include that scope, e.g.
 
 ```bash
 npm link @myorg/privatepackage
 ```
 
+### Caveat
+
+Note that package dependencies linked in this way are _not_ saved to
+`package.json` by default, on the assumption that the intention is to have
+a link stand in for a regular non-link dependency.  Otherwise, for example,
+if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace
+the `^3.0.1` dependency with `file:../path/to/node-redis`, which you
+probably don't want!  Additionally, other users or developers on your
+project would run into issues if they do not have their folders set up
+exactly the same as yours.
+
+If you are adding a _new_ dependency as a link, you should add it to the
+relevant metadata by running `npm install <dep> --package-lock-only`.
+
+If you _want_ to save the `file:` reference in your `package.json` and
+`package-lock.json` files, you can use `npm link <dep> --save` to do so.
+
 ### See Also
 
 * [npm developers](/using-npm/developers)
diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md
index b1f344af5..7fa858a99 100644
--- a/docs/content/commands/npm-logout.md
+++ b/docs/content/commands/npm-logout.md
@@ -12,13 +12,13 @@ npm logout [--registry=<url>] [--scope=<@scope>]
 
 ### Description
 
-When logged into a registry that supports token-based authentication, tell the
-server to end this token's session. This will invalidate the token everywhere
-you're using it, not just for the current environment.
+When logged into a registry that supports token-based authentication, tell
+the server to end this token's session. This will invalidate the token
+everywhere you're using it, not just for the current environment.
 
-When logged into a legacy registry that uses username and password authentication, this will
-clear the credentials in your user configuration. In this case, it will _only_ affect
-the current environment.
+When logged into a legacy registry that uses username and password
+authentication, this will clear the credentials in your user configuration.
+In this case, it will _only_ affect the current environment.
 
 If `--scope` is provided, this will find the credentials for the registry
 connected to that scope, if set.
diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md
index c6e2af331..54787bd63 100644
--- a/docs/content/commands/npm-ls.md
+++ b/docs/content/commands/npm-ls.md
@@ -15,17 +15,21 @@ aliases: list, la, ll
 ### Description
 
 This command will print to stdout all the versions of packages that are
-installed, as well as their dependencies, in a tree-structure.
+installed, as well as their dependencies when `--all` is specified, in a
+tree structure.
 
-Positional arguments are `name@version-range` identifiers, which will
-limit the results to only the paths to the packages named.  Note that
-nested packages will *also* show the paths to the specified packages.
-For example, running `npm ls promzard` in npm's source tree will show:
+Note: to get a "bottoms up" view of why a given package is included in the
+tree at all, use [`npm explain`](/commands/npm-explain).
+
+Positional arguments are `name@version-range` identifiers, which will limit
+the results to only the paths to the packages named.  Note that nested
+packages will *also* show the paths to the specified packages.  For
+example, running `npm ls promzard` in npm's source tree will show:
 
 ```bash
-    npm@@VERSION@ /path/to/npm
-    └─┬ init-package-json@0.0.4
-      └── promzard@0.1.5
+npm@@VERSION@ /path/to/npm
+└─┬ init-package-json@0.0.4
+  └── promzard@0.1.5
 ```
 
 It will print out extraneous, missing, and invalid packages.
@@ -35,12 +39,49 @@ in parentheses after the name@version to make it easier for users to
 recognize potential forks of a project.
 
 The tree shown is the logical dependency tree, based on package
-dependencies, not the physical layout of your node_modules folder.
+dependencies, not the physical layout of your `node_modules` folder.
 
 When run as `ll` or `la`, it shows extended information by default.
 
+### Note: Design Changes Pending
+
+The `npm ls` command's output and behavior made a _ton_ of sense when npm
+created a `node_modules` folder that naively nested every dependency.  In
+such a case, the logical dependency graph and physical tree of packages on
+disk would be roughly identical.
+
+With the advent of automatic install-time deduplication of dependencies in
+npm v3, the `ls` output was modified to display the logical dependency
+graph as a tree structure, since this was more useful to most users.
+However, without using `npm ls -l`, it became impossible show _where_ a
+package was actually installed much of the time!
+
+With the advent of automatic installation of `peerDependencies` in npm v7,
+this gets even more curious, as `peerDependencies` are logically
+"underneath" their dependents in the dependency graph, but are always
+physically at or above their location on disk.
+
+Also, in the years since npm got an `ls` command (in version 0.0.2!),
+dependency graphs have gotten much larger as a general rule.  Therefor, in
+order to avoid dumping an excessive amount of content to the terminal, `npm
+ls` now only shows the _top_ level dependencies, unless `--all` is
+provided.
+
+A thorough re-examination of the use cases, intention, behavior, and output
+of this command, is currently underway.  Expect significant changes to at
+least the default human-readable `npm ls` output in npm v8.
+
 ### Configuration
 
+#### all
+
+* Default: `false`
+* Type: Boolean
+
+When running `npm outdated` and `npm ls`, setting `--all` will show all
+outdated or installed packages, rather than only those directly depended
+upon by the current project.
+
 #### json
 
 * Default: false
@@ -115,6 +156,7 @@ Set it to false in order to use all-ansi output.
 
 ### See Also
 
+* [npm explain](/commands/npm-explain)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
 * [npm folders](/configuring-npm/folders)
diff --git a/docs/content/commands/npm-org.md b/docs/content/commands/npm-org.md
index 2f3c6b480..18047d109 100644
--- a/docs/content/commands/npm-org.md
+++ b/docs/content/commands/npm-org.md
@@ -52,10 +52,11 @@ $ npm org ls my-org @mx-santos
 
 ### Description
 
-You can use the `npm org` commands to manage and view users of an organization.
-It supports adding and removing users, changing their roles, listing them, and
-finding specific ones and their roles.
+You can use the `npm org` commands to manage and view users of an
+organization.  It supports adding and removing users, changing their roles,
+listing them, and finding specific ones and their roles.
 
 ### See Also
 
+* [using orgs](/using-npm/orgs)
 * [Documentation on npm Orgs](https://docs.npmjs.com/orgs/)
diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md
index 01ad78086..ee1157f33 100644
--- a/docs/content/commands/npm-outdated.md
+++ b/docs/content/commands/npm-outdated.md
@@ -15,25 +15,34 @@ npm outdated [[<@scope>/]<pkg> ...]
 This command will check the registry to see if any (or, specific) installed
 packages are currently outdated.
 
+By default, only the direct dependencies of the root project are shown.
+Use `--all` to find all outdated meta-dependencies as well.
+
 In the output:
 
 * `wanted` is the maximum version of the package that satisfies the semver
-  range specified in `package.json`. If there's no available semver range (i.e.
-  you're running `npm outdated --global`, or the package isn't included in
-  `package.json`), then `wanted` shows the currently-installed version.
+  range specified in `package.json`. If there's no available semver range
+  (i.e.  you're running `npm outdated --global`, or the package isn't
+  included in `package.json`), then `wanted` shows the currently-installed
+  version.
 * `latest` is the version of the package tagged as latest in the registry.
-  Running `npm publish` with no special configuration will publish the package
-  with a dist-tag of `latest`. This may or may not be the maximum version of
-  the package, or the most-recently published version of the package, depending
-  on how the package's developer manages the latest [dist-tag](npm-dist-tag).
+  Running `npm publish` with no special configuration will publish the
+  package with a dist-tag of `latest`. This may or may not be the maximum
+  version of the package, or the most-recently published version of the
+  package, depending on how the package's developer manages the latest
+  [dist-tag](/commands/npm-dist-tag).
 * `location` is where in the physical tree the package is located.
 * `depended by` shows which package depends on the displayed dependency
-* `package type` (when using `--long` / `-l`) tells you whether this package is
-  a `dependency` or a dev/peer/optional dependency. Packages not included in `package.json`
-  are always marked `dependencies`.
-* `homepage` (when using `--long` / `-l`) is the `homepage` value contained in the package's packument
-* Red means there's a newer version matching your semver requirements, so you should update now.
-* Yellow indicates that there's a newer version above your semver requirements (usually new major, or new 0.x minor) so proceed with caution.
+* `package type` (when using `--long` / `-l`) tells you whether this
+  package is a `dependency` or a dev/peer/optional dependency. Packages not
+  included in `package.json` are always marked `dependencies`.
+* `homepage` (when using `--long` / `-l`) is the `homepage` value contained
+  in the package's packument
+* Red means there's a newer version matching your semver requirements, so
+  you should update now.
+* Yellow indicates that there's a newer version _above_ your semver
+  requirements (usually new major, or new 0.x minor) so proceed with
+  caution.
 
 ### An example
 
@@ -59,19 +68,20 @@ With these `dependencies`:
 
 A few things to note:
 
-* `glob` requires `^5`, which prevents npm from installing `glob@6`, which is
-  outside the semver range.
-* Git dependencies will always be reinstalled, because of how they're specified.
-  The installed committish might satisfy the dependency specifier (if it's
-  something immutable, like a commit SHA), or it might not, so `npm outdated` and
-  `npm update` have to fetch Git repos to check. This is why currently doing a
-  reinstall of a Git dependency always forces a new clone and install.
-* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because npm
-  uses dist-tags to manage its `latest` and `next` release channels. `npm update`
-  will install the _newest_ version, but `npm install npm` (with no semver range)
-  will install whatever's tagged as `latest`.
-* `once` is just plain out of date. Reinstalling `node_modules` from scratch or
-  running `npm update` will bring it up to spec.
+* `glob` requires `^5`, which prevents npm from installing `glob@6`, which
+  is outside the semver range.
+* Git dependencies will always be reinstalled, because of how they're
+  specified.  The installed committish might satisfy the dependency
+  specifier (if it's something immutable, like a commit SHA), or it might
+  not, so `npm outdated` and `npm update` have to fetch Git repos to check.
+  This is why currently doing a reinstall of a Git dependency always forces
+  a new clone and install.
+* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because
+  npm uses dist-tags to manage its `latest` and `next` release channels.
+  `npm update` will install the _newest_ version, but `npm install npm`
+  (with no semver range) will install whatever's tagged as `latest`.
+* `once` is just plain out of date. Reinstalling `node_modules` from
+  scratch or running `npm update` will bring it up to spec.
 
 ### Configuration
 
diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md
index 3c984ebd8..6479f3bdd 100644
--- a/docs/content/commands/npm-owner.md
+++ b/docs/content/commands/npm-owner.md
@@ -18,26 +18,24 @@ aliases: author
 
 Manage ownership of published packages.
 
-* ls:
-  List all the users who have access to modify a package and push new versions.
-  Handy when you need to know who to bug for help.
-* add:
-  Add a new user as a maintainer of a package.  This user is enabled to modify
-  metadata, publish new versions, and add other owners.
-* rm:
-  Remove a user from the package owner list.  This immediately revokes their
-  privileges.
+* ls: List all the users who have access to modify a package and push new
+  versions.  Handy when you need to know who to bug for help.
+* add: Add a new user as a maintainer of a package.  This user is enabled
+  to modify metadata, publish new versions, and add other owners.
+* rm: Remove a user from the package owner list.  This immediately revokes
+  their privileges.
 
 Note that there is only one level of access.  Either you can modify a package,
 or you can't.  Future versions may contain more fine-grained access levels, but
 that is not implemented at this time.
 
-If you have two-factor authentication enabled with `auth-and-writes` then
-you'll need to include an otp on the command line when changing ownership
-with `--otp`.
+If you have two-factor authentication enabled with `auth-and-writes` (see
+[`npm-profile`](/commands/npm-profile)) then you'll need to include an otp
+on the command line when changing ownership with `--otp`.
 
 ### See Also
 
+* [npm profile](/commands/npm-profile)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)
 * [npm adduser](/commands/npm-adduser)
diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md
index adb5d3083..cc6b669ef 100644
--- a/docs/content/commands/npm-pack.md
+++ b/docs/content/commands/npm-pack.md
@@ -13,10 +13,10 @@ npm pack [[<@scope>/]<pkg>...] [--dry-run]
 ### Description
 
 For anything that's installable (that is, a package folder, tarball,
-tarball url, name@tag, name@version, name, or scoped name), this
-command will fetch it to the cache, and then copy the tarball to the
-current working directory as `<name>-<version>.tgz`, and then write
-the filenames out to stdout.
+tarball url, git url, name@tag, name@version, name, or scoped name), this
+command will fetch it to the cache, copy the tarball to the current working
+directory as `<name>-<version>.tgz`, and then write the filenames out to
+stdout.
 
 If the same package is specified multiple times, then the file will be
 overwritten the second time.
@@ -24,10 +24,12 @@ overwritten the second time.
 If no arguments are supplied, then npm packs the current package folder.
 
 The `--dry-run` argument will do everything that pack usually does without
-actually packing anything. Reports on what would have gone into the tarball.
+actually packing anything.  That is, it reports on what would have gone
+into the tarball, but nothing else.
 
 ### See Also
 
+* [npm-packlist package](http://npm.im/npm-packlist)
 * [npm cache](/commands/npm-cache)
 * [npm publish](/commands/npm-publish)
 * [npm config](/commands/npm-config)
diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md
index bc2233da7..8de06aa18 100644
--- a/docs/content/commands/npm-ping.md
+++ b/docs/content/commands/npm-ping.md
@@ -25,5 +25,6 @@ Ping error: {*Detail about error}
 
 ### See Also
 
+* [npm doctor](/commands/npm-doctor)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
diff --git a/docs/content/commands/npm-profile.md b/docs/content/commands/npm-profile.md
index d44c99416..88edf26d8 100644
--- a/docs/content/commands/npm-profile.md
+++ b/docs/content/commands/npm-profile.md
@@ -16,12 +16,12 @@ npm profile disable-2fa
 
 ### Description
 
-Change your profile information on the registry.  This not be available if
-you're using a non-npmjs registry.
+Change your profile information on the registry.  Note that this command
+depends on the registry implementation, so third-party registries may not
+support this interface.
 
-* `npm profile get [<property>]`:
-  Display all of the properties of your profile, or one or more specific
-  properties.  It looks like:
+* `npm profile get [<property>]`: Display all of the properties of your
+  profile, or one or more specific properties.  It looks like:
 
 ```bash
 +-----------------+---------------------------+
@@ -46,27 +46,26 @@ you're using a non-npmjs registry.
 | updated         | 2017-10-02T21:29:45.922Z  |
 +-----------------+---------------------------+
 ```
-  
-* `npm profile set <property> <value>`:
-  Set the value of a profile property. You can set the following properties this way:
-    email, fullname, homepage, freenode, twitter, github
 
-* `npm profile set password`:
-  Change your password.  This is interactive, you'll be prompted for your
-  current password and a new password.  You'll also be prompted for an OTP
-  if you have two-factor authentication enabled.
+* `npm profile set <property> <value>`: Set the value of a profile
+  property. You can set the following properties this way: email, fullname,
+  homepage, freenode, twitter, github
 
-* `npm profile enable-2fa [auth-and-writes|auth-only]`:
-  Enables two-factor authentication. Defaults to `auth-and-writes` mode. Modes are:
+* `npm profile set password`: Change your password.  This is interactive,
+  you'll be prompted for your current password and a new password.  You'll
+  also be prompted for an OTP if you have two-factor authentication
+  enabled.
+
+* `npm profile enable-2fa [auth-and-writes|auth-only]`: Enables two-factor
+  authentication. Defaults to `auth-and-writes` mode. Modes are:
   * `auth-only`: Require an OTP when logging in or making changes to your
     account's authentication.  The OTP will be required on both the website
     and the command line.
-  * `auth-and-writes`: Requires an OTP at all the times `auth-only` does, and also requires one when
-    publishing a module, setting the `latest` dist-tag, or changing access
-    via `npm access` and `npm owner`.
+  * `auth-and-writes`: Requires an OTP at all the times `auth-only` does,
+    and also requires one when publishing a module, setting the `latest`
+    dist-tag, or changing access via `npm access` and `npm owner`.
 
-* `npm profile disable-2fa`:
-  Disables two-factor authentication.
+* `npm profile disable-2fa`: Disables two-factor authentication.
 
 ### Details
 
@@ -76,4 +75,6 @@ available on non npmjs.com registries.
 
 ### See Also
 
+* [npm adduser](/commands/npm-adduser)
+* [npm logout](/commands/npm-logout)
 * [npm config](/commands/npm-config)
diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md
index 1a100e9d8..088c1c347 100644
--- a/docs/content/commands/npm-prune.md
+++ b/docs/content/commands/npm-prune.md
@@ -12,29 +12,26 @@ npm prune [[<@scope>/]<pkg>...] [--production] [--dry-run] [--json]
 
 ### Description
 
-This command removes "extraneous" packages.  If a package name is
-provided, then only packages matching one of the supplied names are
-removed.
+This command removes "extraneous" packages.  If a package name is provided,
+then only packages matching one of the supplied names are removed.
 
-Extraneous packages are packages that are not listed on the parent
-package's dependencies list.
+Extraneous packages are those present in the `node_modules` folder that are
+not listed as any package's dependency list.
 
 If the `--production` flag is specified or the `NODE_ENV` environment
 variable is set to `production`, this command will remove the packages
-specified in your `devDependencies`. Setting `--no-production` will
-negate `NODE_ENV` being set to `production`.
+specified in your `devDependencies`. Setting `--no-production` will negate
+`NODE_ENV` being set to `production`.
 
 If the `--dry-run` flag is used then no changes will actually be made.
 
-If the `--json` flag is used then the changes `npm prune` made (or would
+If the `--json` flag is used, then the changes `npm prune` made (or would
 have made with `--dry-run`) are printed as a JSON object.
 
-In normal operation with package-locks enabled, extraneous modules are
-pruned automatically when modules are installed and you'll only need
-this command with the `--production` flag.
-
-If you've disabled package-locks then extraneous modules will not be removed
-and it's up to you to run `npm prune` from time-to-time to remove them.
+In normal operation, extraneous modules are pruned automatically, so you'll
+only need this command with the `--production` flag.  However, in the real
+world, operation is not always "normal".  When crashes or mistakes happen,
+this command can help clean up any resulting garbage.
 
 ### See Also
 
diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md
index 3dcdc6f30..fc13e6722 100644
--- a/docs/content/commands/npm-publish.md
+++ b/docs/content/commands/npm-publish.md
@@ -15,59 +15,91 @@ Sets tag 'latest' if no --tag specified
 
 ### Description
 
-Publishes a package to the registry so that it can be installed by name. All
-files in the package directory are included if no local `.gitignore` or
-`.npmignore` file exists. If both files exist and a file is ignored by
-`.gitignore` but not by `.npmignore` then it will be included.  See
-[`developers`](/using-npm/developers) for full details on what's included in the published package, as well as details on how the package is built.
+Publishes a package to the registry so that it can be installed by name.
 
-By default npm will publish to the public registry. This can be overridden by
-specifying a different default registry or using a [`scope`](/using-npm/scope) in the name (see [`package.json`](/configuring-npm/package-json)).
+By default npm will publish to the public registry. This can be overridden
+by specifying a different default registry or using a
+[`scope`](/using-npm/scope) in the name (see
+[`package.json`](/configuring-npm/package-json)).
 
-* `<folder>`:
-  A folder containing a package.json file
+* `<folder>`: A folder containing a package.json file
 
-* `<tarball>`:
-  A url or file path to a gzipped tar archive containing a single folder
-  with a package.json file inside.
+* `<tarball>`: A url or file path to a gzipped tar archive containing a
+  single folder with a package.json file inside.
 
-* `[--tag <tag>]`
-  Registers the published package with the given tag, such that
-  `npm install <name>@<tag>` will install this version.  By default,
+* `[--tag <tag>]`: Registers the published package with the given tag, such
+  that `npm install <name>@<tag>` will install this version.  By default,
   `npm publish` updates and `npm install` installs the `latest` tag. See
   [`npm-dist-tag`](npm-dist-tag) for details about tags.
 
-* `[--access <public|restricted>]`
-  Tells the registry whether this package should be published as public or
-  restricted. Only applies to scoped packages, which default to `restricted`.
-  If you don't have a paid account, you must publish with `--access public`
-  to publish scoped packages.
+* `[--access <public|restricted>]`: Tells the registry whether this package
+  should be published as public or restricted. Only applies to scoped
+  packages, which default to `restricted`.  If you don't have a paid
+  account, you must publish with `--access public` to publish scoped
+  packages.
 
-* `[--otp <otpcode>]`
-  If you have two-factor authentication enabled in `auth-and-writes` mode
-  then you can provide a code from your authenticator with this. If you
-  don't include this and you're running from a TTY then you'll be prompted.
+* `[--otp <otpcode>]`: If you have two-factor authentication enabled in
+  `auth-and-writes` mode then you can provide a code from your
+  authenticator with this. If you don't include this and you're running
+  from a TTY then you'll be prompted.
 
-* `[--dry-run]`
-  As of `npm@6`, does everything publish would do except actually publishing
-  to the registry. Reports the details of what would have been published.
+* `[--dry-run]`: As of `npm@6`, does everything publish would do except
+  actually publishing to the registry. Reports the details of what would
+  have been published.
 
-Fails if the package name and version combination already exists in
-the specified registry.
+The publish will fail if the package name and version combination already
+exists in the specified registry.
 
-Once a package is published with a given name and version, that
-specific name and version combination can never be used again, even if
-it is removed with [`npm unpublish`](/commands/npm-unpublish).
+Once a package is published with a given name and version, that specific
+name and version combination can never be used again, even if it is removed
+with [`npm unpublish`](/commands/npm-unpublish).
 
 As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the
 tarball will be submitted to the registry during publication. Subsequent
 installs will use the strongest supported algorithm to verify downloads.
 
-Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures out the files to be
-included and packs them into a tarball to be uploaded to the registry.
+Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures
+out the files to be included and packs them into a tarball to be uploaded
+to the registry.
+
+### Files included in package
+
+To see what will be included in your package, run `npx npm-packlist`.  All
+files are included by default, with the following exceptions:
+
+- Certain files that are relevant to package installation and distribution
+  are always included.  For example, `package.json`, `README.md`,
+  `LICENSE`, and so on.
+
+- If there is a "files" list in
+  [`package.json`](/configuring-npm/package-json), then only the files
+  specified will be included.  (If directories are specified, then they
+  will be walked recursively and their contents included, subject to the
+  same ignore rules.)
+
+- If there is a `.gitignore` or `.npmignore` file, then ignored files in
+  that and all child directories will be excluded from the package.  If
+  _both_ files exist, then the `.gitignore` is ignored, and only the
+  `.npmignore` is used.
+
+  `.npmignore` files follow the [same pattern
+  rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
+  as `.gitignore` files
+
+- If the file matches certain patterns, then it will _never_ be included,
+  unless explicitly added to the `"files"` list in `package.json`, or
+  un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file.
+
+- Symbolic links are never included in npm packages.
+
+
+See [`developers`](/using-npm/developers) for full details on what's
+included in the published package, as well as details on how the package is
+built.
 
 ### See Also
 
+* [npm-packlist package](http://npm.im/npm-packlist)
 * [npm registry](/using-npm/registry)
 * [npm scope](/using-npm/scope)
 * [npm adduser](/commands/npm-adduser)
diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md
index 5b6b816f6..0a7ade6b1 100644
--- a/docs/content/commands/npm-rebuild.md
+++ b/docs/content/commands/npm-rebuild.md
@@ -7,16 +7,23 @@ description: Rebuild a package
 ### Synopsis
 
 ```bash
-npm rebuild [[<@scope>/<name>]...]
+npm rebuild [[<@scope>/]<name>[@<version>] ...]
 
-alias: npm rb
+alias: rb
 ```
 
 ### Description
 
-This command runs the `npm build` command on the matched folders.  This is useful when you install a new version of node, and must recompile all your C++ addons with the new binary.
+This command runs the `npm build` command on the matched folders.  This is
+useful when you install a new version of node, and must recompile all your
+C++ addons with the new binary.  It is also useful when installing with
+`--ignore-scripts` and `--no-bin-links`, to explicitly choose which
+packages to build and/or link bins.
+
+If one or more package names (and optionally version ranges) are provided,
+then only packages with a name and version matching one of the specifiers
+will be rebuilt.
 
 ### See Also
 
-* [npm build](/commands/npm-build)
 * [npm install](/commands/npm-install)
diff --git a/docs/content/commands/npm-repo.md b/docs/content/commands/npm-repo.md
index c6fdf36f1..670345bec 100644
--- a/docs/content/commands/npm-repo.md
+++ b/docs/content/commands/npm-repo.md
@@ -13,9 +13,9 @@ npm repo [<pkgname> [<pkgname> ...]]
 ### Description
 
 This command tries to guess at the likely location of a package's
-repository URL, and then tries to open it using the `--browser`
-config param. If no package name is provided, it will search for
-a `package.json` in the current folder and use the `name` property.
+repository URL, and then tries to open it using the `--browser` config
+param. If no package name is provided, it will search for a `package.json`
+in the current folder and use the `repository` property.
 
 ### Configuration
 
diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md
index a80c54273..097c9fee7 100644
--- a/docs/content/commands/npm-restart.md
+++ b/docs/content/commands/npm-restart.md
@@ -12,29 +12,28 @@ npm restart [-- <args>]
 
 ### Description
 
-This restarts a package.
+This restarts a project.  It is equivalent to running `npm run-script
+restart`.
 
-This runs a package's "stop", "restart", and "start" scripts, and associated
-pre- and post- scripts, in the order given below:
+If the current project has a `"restart"` script specified in
+`package.json`, then the following scripts will be run:
+
+1. prerestart
+2. restart
+3. postrestart
+
+If it does _not_ have a `"restart"` script specified, but it does have
+`stop` and/or `start` scripts, then the following scripts will be run:
 
 1. prerestart
 2. prestop
 3. stop
 4. poststop
-5. restart
 6. prestart
 7. start
 8. poststart
 9. postrestart
 
-### Note
-
-Note that the "restart" script is run **in addition to** the "stop"
-and "start" scripts, not instead of them.
-
-This is the behavior as of `npm` major version 2.  A change in this
-behavior will be accompanied by an increase in major version number
-
 ### See Also
 
 * [npm run-script](/commands/npm-run-script)
diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md
index 317ef9d85..0d694ac87 100644
--- a/docs/content/commands/npm-root.md
+++ b/docs/content/commands/npm-root.md
@@ -5,6 +5,7 @@ description: Display npm root
 ---
 
 ### Synopsis
+
 ```bash
 npm root [-g]
 ```
@@ -13,6 +14,15 @@ npm root [-g]
 
 Print the effective `node_modules` folder to standard out.
 
+Useful for using npm in shell scripts that do things with the
+`node_modules` folder.  For example:
+
+```bash
+#!/bin/bash
+global_node_modules="$(npm root --global)"
+echo "Global packages installed in: ${global_node_modules}"
+```
+
 ### See Also
 
 * [npm prefix](/commands/npm-prefix)
diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md
index 06b6e9383..05f6380c2 100644
--- a/docs/content/commands/npm-run-script.md
+++ b/docs/content/commands/npm-run-script.md
@@ -7,23 +7,25 @@ description: Run arbitrary package scripts
 ### Synopsis
 
 ```bash
-npm run-script <command> [--silent] [-- <args>...]
+npm run-script <command> [--if-present] [--silent] [-- <args>]
 
-alias: npm run
+aliases: run, rum, urn
 ```
 
 ### Description
 
 This runs an arbitrary command from a package's `"scripts"` object.  If no
-`"command"` is provided, it will list the available scripts.  `run[-script]` is
-used by the test, start, restart, and stop commands, but can be called
-directly, as well. When the scripts in the package are printed out, they're
-separated into lifecycle (test, start, restart) and directly-run scripts.
+`"command"` is provided, it will list the available scripts.
 
-As of [`npm@2.0.0`](https://blog.npmjs.org/post/98131109725/npm-2-0-0), you can
-use custom arguments when executing scripts. The special option `--` is used by
-[getopt](https://goo.gl/KxMmtG) to delimit the end of the options. npm will pass
-all the arguments after the `--` directly to your script:
+`run[-script]` is used by the test, start, restart, and stop commands, but
+can be called directly, as well. When the scripts in the package are
+printed out, they're separated into lifecycle (test, start, restart) and
+directly-run scripts.
+
+Any positional arguments are passed to the specified script.  Use `--` to
+pass `-`-prefixed flags and options which would otherwise be parsed by npm.
+
+For example:
 
 ```bash
 npm run test -- --grep="pattern"
@@ -38,31 +40,28 @@ environment variables that will be available to the script at runtime. If an
 built-in.
 
 In addition to the shell's pre-existing `PATH`, `npm run` adds
-`node_modules/.bin` to the `PATH` provided to scripts. Any binaries provided by
-locally-installed dependencies can be used without the `node_modules/.bin`
-prefix. For example, if there is a `devDependency` on `tap` in your package,
-you should write:
+`node_modules/.bin` to the `PATH` provided to scripts. Any binaries
+provided by locally-installed dependencies can be used without the
+`node_modules/.bin` prefix. For example, if there is a `devDependency` on
+`tap` in your package, you should write:
 
 ```bash
-"scripts": {"test": "tap test/\*.js"}
+"scripts": {"test": "tap test/*.js"}
 ```
 
 instead of
 
 ```bash
-"scripts": {"test": "node_modules/.bin/tap test/\*.js"}
+"scripts": {"test": "node_modules/.bin/tap test/*.js"}
 ```
 
-to run your tests.
-
 The actual shell your script is run within is platform dependent. By default,
 on Unix-like systems it is the `/bin/sh` command, on Windows it is the `cmd.exe`.
 The actual shell referred to by `/bin/sh` also depends on the system.
-As of [`npm@5.1.0`](https://github.com/npm/npm/releases/tag/v5.1.0) you can
-customize the shell with the `script-shell` configuration.
+You can customize the shell with the `script-shell` configuration.
 
-Scripts are run from the root of the module, regardless of what your current
-working directory is when you call `npm run`. If you want your script to
+Scripts are run from the root of the module, regardless of what the current
+working directory is when `npm run` is called. If you want your script to
 use different behavior based on what subdirectory you're in, you can use the
 `INIT_CWD` environment variable, which holds the full path you were in when
 you ran `npm run`.
diff --git a/docs/content/using-npm/developers.md b/docs/content/using-npm/developers.md
index 7e47b76f6..bce615cfe 100644
--- a/docs/content/using-npm/developers.md
+++ b/docs/content/using-npm/developers.md
@@ -47,69 +47,64 @@ git+https://user@hostname/project/blah.git#commit-ish
 ```
 
 The `commit-ish` can be any tag, sha, or branch which can be supplied as
-an argument to `git checkout`.  The default is `master`.
+an argument to `git checkout`.  The default is whatever the repository uses
+as its default branch.
 
 ### The package.json File
 
 You need to have a `package.json` file in the root of your project to do
 much of anything with npm.  That is basically the whole interface.
 
-See [`package.json`](/configuring-npm/package-json) for details about what goes in that file.  At the very
-least, you need:
+See [`package.json`](/configuring-npm/package-json) for details about what
+goes in that file.  At the very least, you need:
 
-* name:
-  This should be a string that identifies your project.  Please do not
-  use the name to specify that it runs on node, or is in JavaScript.
-  You can use the "engines" field to explicitly state the versions of
-  node (or whatever else) that your program requires, and it's pretty
-  well assumed that it's JavaScript.
+* name: This should be a string that identifies your project.  Please do
+  not use the name to specify that it runs on node, or is in JavaScript.
+  You can use the "engines" field to explicitly state the versions of node
+  (or whatever else) that your program requires, and it's pretty well
+  assumed that it's JavaScript.
 
   It does not necessarily need to match your github repository name.
 
   So, `node-foo` and `bar-js` are bad names.  `foo` or `bar` are better.
 
-* version:
-  A semver-compatible version.
+* version: A semver-compatible version.
 
-* engines:
-  Specify the versions of node (or whatever else) that your program
-  runs on.  The node API changes a lot, and there may be bugs or new
-  functionality that you depend on.  Be explicit.
+* engines: Specify the versions of node (or whatever else) that your
+  program runs on.  The node API changes a lot, and there may be bugs or
+  new functionality that you depend on.  Be explicit.
 
-* author:
-  Take some credit.
+* author: Take some credit.
 
-* scripts:
-  If you have a special compilation or installation script, then you
-  should put it in the `scripts` object.  You should definitely have at
-  least a basic smoke-test command as the "scripts.test" field.
-  See [scripts](/using-npm/scripts).
+* scripts: If you have a special compilation or installation script, then
+  you should put it in the `scripts` object.  You should definitely have at
+  least a basic smoke-test command as the "scripts.test" field.  See
+  [scripts](/using-npm/scripts).
 
-* main:
-  If you have a single module that serves as the entry point to your
-  program (like what the "foo" package gives you at require("foo")),
-  then you need to specify that in the "main" field.
+* main: If you have a single module that serves as the entry point to your
+  program (like what the "foo" package gives you at require("foo")), then
+  you need to specify that in the "main" field.
 
-* directories:
-  This is an object mapping names to folders.  The best ones to include are
-  "lib" and "doc", but if you use "man" to specify a folder full of man pages,
-  they'll get installed just like these ones.
+* directories: This is an object mapping names to folders.  The best ones
+  to include are "lib" and "doc", but if you use "man" to specify a folder
+  full of man pages, they'll get installed just like these ones.
 
 You can use `npm init` in the root of your package in order to get you
-started with a pretty basic package.json file.  See
-[`npm init`](/commands/npm-init) for more info.
+started with a pretty basic package.json file.  See [`npm
+init`](/commands/npm-init) for more info.
 
 ### Keeping files *out* of your package
 
-Use a `.npmignore` file to keep stuff out of your package.  If there's
-no `.npmignore` file, but there *is* a `.gitignore` file, then npm will
-ignore the stuff matched by the `.gitignore` file.  If you *want* to
-include something that is excluded by your `.gitignore` file, you can
-create an empty `.npmignore` file to override it. Like `git`, `npm` looks
-for `.npmignore` and `.gitignore` files in all subdirectories of your
-package, not only the root directory.
+Use a `.npmignore` file to keep stuff out of your package.  If there's no
+`.npmignore` file, but there *is* a `.gitignore` file, then npm will ignore
+the stuff matched by the `.gitignore` file.  If you *want* to include
+something that is excluded by your `.gitignore` file, you can create an
+empty `.npmignore` file to override it. Like `git`, `npm` looks for
+`.npmignore` and `.gitignore` files in all subdirectories of your package,
+not only the root directory.
 
-`.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
+`.npmignore` files follow the [same pattern
+rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
 as `.gitignore` files:
 
 * Blank lines or lines starting with `#` are ignored.