Merge branch 'manliness'

108 files changed, 951 insertions, 935 deletions

diff --git a/.gitignore b/.gitignore
index d06592186..5aedfd851 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,7 +12,7 @@ npm-debug.log
 /html/api/
 /html/doc/
 /man/
-/doc/*/index.md
+/doc/*/npm-index.md
 /npmrc
 /release/
 /npm-*.tgz
diff --git a/Makefile b/Makefile
index 61251fbb2..01228c1cd 100644
--- a/Makefile
+++ b/Makefile
@@ -1,31 +1,57 @@
+# vim: set softtabstop=2 shiftwidth=2:
 SHELL = bash
 
 markdowns = $(shell find doc -name '*.md' | grep -v 'index') README.md
 
+html_docdeps = html/dochead.html \
+               html/docfoot.html \
+               html/docfoot-script.html \
+               scripts/doc-build.sh \
+               package.json
+
 cli_mandocs = $(shell find doc/cli -name '*.md' \
                |sed 's|.md|.1|g' \
                |sed 's|doc/cli/|man/man1/|g' ) \
-               man/man1/README.1 \
-               man/man1/index.1
+               man/man1/npm-README.1
 
 api_mandocs = $(shell find doc/api -name '*.md' \
                |sed 's|.md|.3|g' \
                |sed 's|doc/api/|man/man3/|g' )
 
+files_mandocs = $(shell find doc/files -name '*.md' \
+               |sed 's|.md|.5|g' \
+               |sed 's|doc/files/|man/man5/|g' ) \
+               man/man5/npm-json.5 \
+               man/man5/npm-global.5
+
+misc_mandocs = $(shell find doc/misc -name '*.md' \
+               |sed 's|.md|.7|g' \
+               |sed 's|doc/misc/|man/man7/|g' ) \
+               man/man7/index.7
+
 cli_htmldocs = $(shell find doc/cli -name '*.md' \
-                |grep -v 'index.md' \
                 |sed 's|.md|.html|g' \
-                |sed 's|doc/cli/|html/doc/|g' ) \
-                html/doc/README.html \
-                html/doc/index.html
+                |sed 's|doc/cli/|html/doc/cli/|g' ) \
+                html/doc/README.html
 
 api_htmldocs = $(shell find doc/api -name '*.md' \
                 |sed 's|.md|.html|g' \
-                |sed 's|doc/api/|html/api/|g' )
+                |sed 's|doc/api/|html/doc/api/|g' )
+
+files_htmldocs = $(shell find doc/files -name '*.md' \
+                  |sed 's|.md|.html|g' \
+                  |sed 's|doc/files/|html/doc/files/|g' ) \
+                  html/doc/files/npm-json.html \
+                  html/doc/files/npm-global.html
 
-mandocs = $(api_mandocs) $(cli_mandocs)
+misc_htmldocs = $(shell find doc/misc -name '*.md' \
+                 |sed 's|.md|.html|g' \
+                 |sed 's|doc/misc/|html/doc/misc/|g' ) \
+                 html/doc/index.html
 
-htmldocs = $(api_htmldocs) $(cli_htmldocs)
+mandocs = $(api_mandocs) $(cli_mandocs) $(files_mandocs) $(misc_mandocs)
+
+htmldocs = $(api_htmldocs) $(cli_htmldocs) $(files_htmldocs) $(misc_htmldocs)
 
 all: doc
 
@@ -58,17 +84,14 @@ doc-clean:
 	rm -rf \
     node_modules/ronn \
     node_modules/.bin/ronn \
-		.building_ronn \
-    doc/cli/index.md \
-    doc/api/index.md \
-    $(api_mandocs) \
-    $(cli_mandocs) \
-    $(api_htmldocs) \
-    $(cli_htmldocs) \
-		&>/dev/null || true
+    .building_ronn \
+    html/doc \
+    html/api \
+    man/man*
 
 # use `npm install ronn` for this to work.
-man/man1/README.1: README.md scripts/doc-build.sh package.json
+man/man1/npm-README.1: README.md scripts/doc-build.sh package.json
+	@[ -d man/man1 ] || mkdir -p man/man1
 	scripts/doc-build.sh $< $@
 
 man/man1/%.1: doc/cli/%.md scripts/doc-build.sh package.json
@@ -79,17 +102,54 @@ man/man3/%.3: doc/api/%.md scripts/doc-build.sh package.json
 	@[ -d man/man3 ] || mkdir -p man/man3
 	scripts/doc-build.sh $< $@
 
-html/doc/README.html: README.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
+man/man5/npm-json.5: man/man5/package.json.5
+	cp $< $@
+
+man/man5/npm-global.5: man/man5/npm-folders.5
+	cp $< $@
+
+man/man5/%.5: doc/files/%.md scripts/doc-build.sh package.json
+	@[ -d man/man5 ] || mkdir -p man/man5
 	scripts/doc-build.sh $< $@
 
-html/doc/%.html: doc/cli/%.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
+doc/misc/npm-index.md: scripts/index-build.js package.json
+	node scripts/index-build.js > $@
+
+html/doc/index.html: doc/misc/npm-index.md $(html_docdeps)
+	@[ -d html/doc ] || mkdir -p html/doc
 	scripts/doc-build.sh $< $@
 
-html/api/%.html: doc/api/%.md html/dochead.html html/docfoot.html scripts/doc-build.sh package.json
+man/man7/%.7: doc/misc/%.md scripts/doc-build.sh package.json
+	@[ -d man/man7 ] || mkdir -p man/man7
 	scripts/doc-build.sh $< $@
 
-doc/cli/index.md: $(markdowns) scripts/index-build.js scripts/doc-build.sh package.json
-	node scripts/index-build.js > $@
+html/doc/README.html: README.md $(html_docdeps)
+	@[ -d html/doc ] || mkdir -p html/doc
+	scripts/doc-build.sh $< $@
+
+html/doc/cli/%.html: doc/cli/%.md $(html_docdeps)
+	@[ -d html/doc/cli ] || mkdir -p html/doc/cli
+	scripts/doc-build.sh $< $@
+
+html/doc/api/%.html: doc/api/%.md $(html_docdeps)
+	@[ -d html/doc/api ] || mkdir -p html/doc/api
+	scripts/doc-build.sh $< $@
+
+html/doc/files/npm-json.html: html/doc/files/package.json.html
+	cp $< $@
+html/doc/files/npm-global.html: html/doc/files/npm-folders.html
+	cp $< $@
+
+html/doc/files/%.html: doc/files/%.md $(html_docdeps)
+	@[ -d html/doc/files ] || mkdir -p html/doc/files
+	scripts/doc-build.sh $< $@
+
+html/doc/misc/%.html: doc/misc/%.md $(html_docdeps)
+	@[ -d html/doc/misc ] || mkdir -p html/doc/misc
+	scripts/doc-build.sh $< $@
+
+
+
 
 node_modules/.bin/ronn:
 	node cli.js install ronn
@@ -114,18 +174,36 @@ publish: link doc
 
 docpublish: doc-publish
 doc-publish: doc
+	# legacy urls
+	for f in $$(find html/doc/{cli,files,misc}/ -name '*.html'); do \
+    j=$$(basename $$f | sed 's|^npm-||g'); \
+    if ! [ -f html/doc/$$j ] && [ $$j != README.html ] && [ $$j != index.html ]; then \
+      perl -pi -e 's/ href="\.\.\// href="/g' <$$f >html/doc/$$j; \
+    fi; \
+  done
+	mkdir -p html/api
+	for f in $$(find html/doc/api/ -name '*.html'); do \
+    j=$$(basename $$f | sed 's|^npm-||g'); \
+    perl -pi -e 's/ href="\.\.\// href="/g' <$$f >html/api/$$j; \
+  done
 	rsync -vazu --stats --no-implied-dirs --delete \
-		html/doc/ \
-		node@npmjs.org:/home/node/npm-www/doc
-	rsync -vazu --stats --no-implied-dirs --delete \
-		html/api/ \
-		node@npmjs.org:/home/node/npm-www/api
+    html/doc/* \
+    node@npmjs.org:/home/node/npm-www/doc
 	rsync -vazu --stats --no-implied-dirs --delete \
-		html/static/webfonts/ \
-		node@npmjs.org:/home/node/npm-www/static/webfonts
+    html/static/webfonts/ \
+    node@npmjs.org:/home/node/npm-www/static/webfonts
 	rsync -vazu --stats --no-implied-dirs --delete \
-		html/static/style.css \
-		node@npmjs.org:/home/node/npm-www/static/
+    html/static/style.css \
+    node@npmjs.org:/home/node/npm-www/static/
+	#cleanup
+	rm -rf html/api
+	for f in html/doc/*.html; do \
+    case $$f in \
+      html/doc/README.html) continue ;; \
+      html/doc/index.html) continue ;; \
+      *) rm $$f ;; \
+    esac; \
+  done
 
 zip-publish: release
 	scp release/* node@nodejs.org:dist/npm/
diff --git a/doc/api/bin.md b/doc/api/npm-bin.md
index f3dc48286..f3dc48286 100644
--- a/doc/api/bin.md
+++ b/doc/api/npm-bin.md
diff --git a/doc/api/bugs.md b/doc/api/npm-bugs.md
index cc4db8f9e..cc4db8f9e 100644
--- a/doc/api/bugs.md
+++ b/doc/api/npm-bugs.md
diff --git a/doc/api/commands.md b/doc/api/npm-commands.md
index eb7545639..36dcfd8d6 100644
--- a/doc/api/commands.md
+++ b/doc/api/npm-commands.md
@@ -19,4 +19,4 @@ usage, or `man 3 npm-<command>` for programmatic usage.
 
 ## SEE ALSO
 
-* npm-index(1)
+* npm-index(7)
diff --git a/doc/api/config.md b/doc/api/npm-config.md
index 7ae227428..7ae227428 100644
--- a/doc/api/config.md
+++ b/doc/api/npm-config.md
diff --git a/doc/api/deprecate.md b/doc/api/npm-deprecate.md
index 0608d3864..200fb9c30 100644
--- a/doc/api/deprecate.md
+++ b/doc/api/npm-deprecate.md
@@ -31,4 +31,4 @@ To un-deprecate a package, specify an empty string (`""`) for the `message` argu
 
 * npm-publish(3)
 * npm-unpublish(3)
-* npm-registry(1)
+* npm-registry(7)
diff --git a/doc/api/docs.md b/doc/api/npm-docs.md
index 2c5fc5e63..2c5fc5e63 100644
--- a/doc/api/docs.md
+++ b/doc/api/npm-docs.md
diff --git a/doc/api/edit.md b/doc/api/npm-edit.md
index b13fbb857..b13fbb857 100644
--- a/doc/api/edit.md
+++ b/doc/api/npm-edit.md
diff --git a/doc/api/explore.md b/doc/api/npm-explore.md
index a239f3df3..a239f3df3 100644
--- a/doc/api/explore.md
+++ b/doc/api/npm-explore.md
diff --git a/doc/api/help-search.md b/doc/api/npm-help-search.md
index 5c00cfc17..5c00cfc17 100644
--- a/doc/api/help-search.md
+++ b/doc/api/npm-help-search.md
diff --git a/doc/api/init.md b/doc/api/npm-init.md
index 5afc11b3b..9b75bf791 100644
--- a/doc/api/init.md
+++ b/doc/api/npm-init.md
@@ -26,4 +26,4 @@ then go ahead and use this programmatically.
 
 ## SEE ALSO
 
-npm-json(1)
+package.json(5)
diff --git a/doc/api/install.md b/doc/api/npm-install.md
index 12f665a76..12f665a76 100644
--- a/doc/api/install.md
+++ b/doc/api/npm-install.md
diff --git a/doc/api/link.md b/doc/api/npm-link.md
index ad8cefcab..ad8cefcab 100644
--- a/doc/api/link.md
+++ b/doc/api/npm-link.md
diff --git a/doc/api/load.md b/doc/api/npm-load.md
index a95a6b295..a95a6b295 100644
--- a/doc/api/load.md
+++ b/doc/api/npm-load.md
diff --git a/doc/api/ls.md b/doc/api/npm-ls.md
index ed890ff14..ed890ff14 100644
--- a/doc/api/ls.md
+++ b/doc/api/npm-ls.md
diff --git a/doc/api/outdated.md b/doc/api/npm-outdated.md
index 89f4cf6fa..89f4cf6fa 100644
--- a/doc/api/outdated.md
+++ b/doc/api/npm-outdated.md
diff --git a/doc/api/owner.md b/doc/api/npm-owner.md
index de203c072..71fcccff5 100644
--- a/doc/api/owner.md
+++ b/doc/api/npm-owner.md
@@ -28,4 +28,4 @@ that is not implemented at this time.
 ## SEE ALSO
 
 * npm-publish(3)
-* npm-registry(1)
+* npm-registry(7)
diff --git a/doc/api/pack.md b/doc/api/npm-pack.md
index cb339c0c4..cb339c0c4 100644
--- a/doc/api/pack.md
+++ b/doc/api/npm-pack.md
diff --git a/doc/api/prefix.md b/doc/api/npm-prefix.md
index 806dd4b6c..806dd4b6c 100644
--- a/doc/api/prefix.md
+++ b/doc/api/npm-prefix.md
diff --git a/doc/api/prune.md b/doc/api/npm-prune.md
index 2a4f17748..2a4f17748 100644
--- a/doc/api/prune.md
+++ b/doc/api/npm-prune.md
diff --git a/doc/api/publish.md b/doc/api/npm-publish.md
index a743303f8..6871dafb8 100644
--- a/doc/api/publish.md
+++ b/doc/api/npm-publish.md
@@ -25,6 +25,6 @@ the registry.  Overwrites when the "force" environment variable is set.
 
 ## SEE ALSO
 
-* npm-registry(1)
+* npm-registry(7)
 * npm-adduser(1)
 * npm-owner(3)
diff --git a/doc/api/rebuild.md b/doc/api/npm-rebuild.md
index 8b8989806..8b8989806 100644
--- a/doc/api/rebuild.md
+++ b/doc/api/npm-rebuild.md
diff --git a/doc/api/restart.md b/doc/api/npm-restart.md
index c40704438..c40704438 100644
--- a/doc/api/restart.md
+++ b/doc/api/npm-restart.md
diff --git a/doc/api/root.md b/doc/api/npm-root.md
index 1c3ab5640..1c3ab5640 100644
--- a/doc/api/root.md
+++ b/doc/api/npm-root.md
diff --git a/doc/api/run-script.md b/doc/api/npm-run-script.md
index f15900ecb..91ad95351 100644
--- a/doc/api/run-script.md
+++ b/doc/api/npm-run-script.md
@@ -20,7 +20,7 @@ assumed to be the command to run. All other elements are ignored.
 
 ## SEE ALSO
 
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-test(3)
 * npm-start(3)
 * npm-restart(3)
diff --git a/doc/api/search.md b/doc/api/npm-search.md
index 30651d76a..30651d76a 100644
--- a/doc/api/search.md
+++ b/doc/api/npm-search.md
diff --git a/doc/api/shrinkwrap.md b/doc/api/npm-shrinkwrap.md
index 6584d6a0d..6584d6a0d 100644
--- a/doc/api/shrinkwrap.md
+++ b/doc/api/npm-shrinkwrap.md
diff --git a/doc/api/start.md b/doc/api/npm-start.md
index 74491146a..74491146a 100644
--- a/doc/api/start.md
+++ b/doc/api/npm-start.md
diff --git a/doc/api/stop.md b/doc/api/npm-stop.md
index 0f8333d35..0f8333d35 100644
--- a/doc/api/stop.md
+++ b/doc/api/npm-stop.md
diff --git a/doc/api/submodule.md b/doc/api/npm-submodule.md
index 2d8bafaa3..2d8bafaa3 100644
--- a/doc/api/submodule.md
+++ b/doc/api/npm-submodule.md
diff --git a/doc/api/tag.md b/doc/api/npm-tag.md
index b5a3d7faa..b5a3d7faa 100644
--- a/doc/api/tag.md
+++ b/doc/api/npm-tag.md
diff --git a/doc/api/test.md b/doc/api/npm-test.md
index bc48dcc35..bc48dcc35 100644
--- a/doc/api/test.md
+++ b/doc/api/npm-test.md
diff --git a/doc/api/uninstall.md b/doc/api/npm-uninstall.md
index 4505295b3..4505295b3 100644
--- a/doc/api/uninstall.md
+++ b/doc/api/npm-uninstall.md
diff --git a/doc/api/unpublish.md b/doc/api/npm-unpublish.md
index 6cbc5c1f3..6cbc5c1f3 100644
--- a/doc/api/unpublish.md
+++ b/doc/api/npm-unpublish.md
diff --git a/doc/api/update.md b/doc/api/npm-update.md
index bf02fd3c8..bf02fd3c8 100644
--- a/doc/api/update.md
+++ b/doc/api/npm-update.md
diff --git a/doc/api/version.md b/doc/api/npm-version.md
index bd40102c4..bd40102c4 100644
--- a/doc/api/version.md
+++ b/doc/api/npm-version.md
diff --git a/doc/api/view.md b/doc/api/npm-view.md
index fd0076c96..fd0076c96 100644
--- a/doc/api/view.md
+++ b/doc/api/npm-view.md
diff --git a/doc/api/whoami.md b/doc/api/npm-whoami.md
index 598a1ab1a..598a1ab1a 100644
--- a/doc/api/whoami.md
+++ b/doc/api/npm-whoami.md
diff --git a/doc/api/npm.md b/doc/api/npm.md
index 8c7a8168e..e099320f4 100644
--- a/doc/api/npm.md
+++ b/doc/api/npm.md
@@ -30,11 +30,11 @@ If you provide `configObject` as an object hash of top-level
 configs, they override the values stored in the various config
 locations. In the npm command line client, this set of configs
 is parsed from the command line options. Additional configuration
-params are loaded from two configuration files. See `npm-config(1)`
-for more information.
+params are loaded from two configuration files. See `npm-config(1)`,
+`npm-config(7)`, and `npmrc(5)` for more information.
 
 After that, each of the functions are accessible in the
-commands object: `npm.commands.<cmd>`.  See `npm-index(1)` for a list of
+commands object: `npm.commands.<cmd>`.  See `npm-index(7)` for a list of
 all possible commands.
 
 All commands on the command object take an **array** of positional argument
diff --git a/doc/cli/changelog.md b/doc/cli/changelog.md
deleted file mode 100644
index 64feeacda..000000000
--- a/doc/cli/changelog.md
+++ /dev/null
@@ -1,80 +0,0 @@
-npm-changelog(1) -- Changes
-===========================
-
-## HISTORY
-
-### 1.1.3, 1.1.4
-
-* Update request to support HTTPS-over-HTTP proxy tunneling
-* Throw on undefined envs in config settings
-* Update which to 1.0.5
-* Fix windows UNC busyloop in findPrefix
-* Bundle nested bundleDependencies properly
-* Alias adduser to add-user
-* Doc updates  (Christian Howe, Henrik Hodne, Andrew Lunny)
-* ignore logfd/outfd streams in makeEnv() (Rod Vagg)
-* shrinkwrap: Behave properly with url-installed deps
-* install: Support --save with url install targets
-* Support installing naked tars or single-file modules from urls etc.
-* init: Don't add engines section
-* Don't run make clean on rebuild
-* Added missing unicode replacement (atomizer)
-
-### 1.1.2
-
-Dave Pacheco (2):
-      add "npm shrinkwrap"
-
-Martin Cooper (1):
-      Fix #1753 Make a copy of the cached objects we'll modify.
-
-Tim Oxley (1):
-      correctly remove readme from default npm view command.
-
-Tyler Green (1):
-      fix #2187 set terminal columns to Infinity if 0
-
-isaacs (19):
-      update minimatch
-      update request
-      Experimental: single-file modules
-      Fix #2172 Don't remove global mans uninstalling local pkgs
-      Add --versions flag to show the version of node as well
-      Support --json flag for ls output
-      update request to 2.9.151
-
-### 1.1  
-* Replace system tar dependency with a JS tar
-* Continue to refine
-
-### 1.0  
-* Greatly simplified folder structure 
-* Install locally (bundle by default) 
-* Drastic rearchitecture
-
-### 0.3  
-* More correct permission/uid handling when running as root  
-* Require node 0.4.0  
-* Reduce featureset  
-* Packages without "main" modules don't export modules
-* Remove support for invalid JSON (since node doesn't support it)
-
-### 0.2  
-* First allegedly "stable" release
-* Most functionality implemented 
-* Used shim files and `name@version` symlinks
-* Feature explosion
-* Kind of a mess
-
-### 0.1  
-* push to beta, and announce  
-* Solaris and Cygwin support
-
-### 0.0  
-* Lots of sketches and false starts; abandoned a few times
-* Core functionality established
-
-## SEE ALSO
-
-* npm(1)
-* npm-faq(1)
diff --git a/doc/cli/global.md b/doc/cli/global.md
deleted file mode 100644
index 20358612a..000000000
--- a/doc/cli/global.md
+++ /dev/null
@@ -1,209 +0,0 @@
-npm-folders(1) -- Folder Structures Used by npm
-===============================================
-
-## DESCRIPTION
-
-npm puts various things on your computer.  That's its job.
-
-This document will tell you what it puts where.
-
-### tl;dr
-
-* Local install (default): puts stuff in `./node_modules` of the current
-  package root.
-* Global install (with `-g`): puts stuff in /usr/local or wherever node
-  is installed.
-* Install it **locally** if you're going to `require()` it.
-* Install it **globally** if you're going to run it on the command line.
-* If you need both, then install it in both places, or use `npm link`.
-
-### prefix Configuration
-
-The `prefix` config defaults to the location where node is installed.
-On most systems, this is `/usr/local`, and most of the time is the same
-as node's `process.installPrefix`.
-
-On windows, this is the exact location of the node.exe binary.  On Unix
-systems, it's one level up, since node is typically installed at
-`{prefix}/bin/node` rather than `{prefix}/node.exe`.
-
-When the `global` flag is set, npm installs things into this prefix.
-When it is not set, it uses the root of the current package, or the
-current working directory if not in a package already.
-
-### Node Modules
-
-Packages are dropped into the `node_modules` folder under the `prefix`.
-When installing locally, this means that you can
-`require("packagename")` to load its main module, or
-`require("packagename/lib/path/to/sub/module")` to load other modules.
-
-Global installs on Unix systems go to `{prefix}/lib/node_modules`.
-Global installs on Windows go to `{prefix}/node_modules` (that is, no
-`lib` folder.)
-
-If you wish to `require()` a package, then install it locally.
-
-### Executables
-
-When in global mode, executables are linked into `{prefix}/bin` on Unix,
-or directly into `{prefix}` on Windows.
-
-When in local mode, executables are linked into
-`./node_modules/.bin` so that they can be made available to scripts run
-through npm.  (For example, so that a test runner will be in the path
-when you run `npm test`.)
-
-### Man Pages
-
-When in global mode, man pages are linked into `{prefix}/share/man`.
-
-When in local mode, man pages are not installed.
-
-Man pages are not installed on Windows systems.
-
-### Cache
-
-See `npm-cache(1)`.  Cache files are stored in `~/.npm` on Posix, or
-`~/npm-cache` on Windows.
-
-This is controlled by the `cache` configuration param.
-
-### Temp Files
-
-Temporary files are stored by default in the folder specified by the
-`tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment
-variables, or `/tmp` on Unix and `c:\windows\temp` on Windows.
-
-Temp files are given a unique folder under this root for each run of the
-program, and are deleted upon successful exit.
-
-## More Information
-
-When installing locally, npm first tries to find an appropriate
-`prefix` folder.  This is so that `npm install foo@1.2.3` will install
-to the sensible root of your package, even if you happen to have `cd`ed
-into some other folder.
-
-Starting at the $PWD, npm will walk up the folder tree checking for a
-folder that contains either a `package.json` file, or a `node_modules`
-folder.  If such a thing is found, then that is treated as the effective
-"current directory" for the purpose of running npm commands.  (This
-behavior is inspired by and similar to git's .git-folder seeking
-logic when running git commands in a working dir.)
-
-If no package root is found, then the current folder is used.
-
-When you run `npm install foo@1.2.3`, then the package is loaded into
-the cache, and then unpacked into `./node_modules/foo`.  Then, any of
-foo's dependencies are similarly unpacked into
-`./node_modules/foo/node_modules/...`.
-
-Any bin files are symlinked to `./node_modules/.bin/`, so that they may
-be found by npm scripts when necessary.
-
-### Global Installation
-
-If the `global` configuration is set to true, then npm will
-install packages "globally".
-
-For global installation, packages are installed roughly the same way,
-but using the folders described above.
-
-### Cycles, Conflicts, and Folder Parsimony
-
-Cycles are handled using the property of node's module system that it
-walks up the directories looking for `node_modules` folders.  So, at every
-stage, if a package is already installed in an ancestor `node_modules`
-folder, then it is not installed at the current location.
-
-Consider the case above, where `foo -> bar -> baz`.  Imagine if, in
-addition to that, baz depended on bar, so you'd have:
-`foo -> bar -> baz -> bar -> baz ...`.  However, since the folder
-structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to
-put another copy of bar into `.../baz/node_modules`, since when it calls
-require("bar"), it will get the copy that is installed in
-`foo/node_modules/bar`.
-
-This shortcut is only used if the exact same
-version would be installed in multiple nested `node_modules` folders.  It
-is still possible to have `a/node_modules/b/node_modules/a` if the two
-"a" packages are different versions.  However, without repeating the
-exact same package multiple times, an infinite regress will always be
-prevented.
-
-Another optimization can be made by installing dependencies at the
-highest level possible, below the localized "target" folder.
-
-#### Example
-
-Consider this dependency graph:
-
-    foo
-    +-- blerg@1.2.5
-    +-- bar@1.2.3
-    |   +-- blerg@1.x (latest=1.3.7)
-    |   +-- baz@2.x
-    |   |   `-- quux@3.x
-    |   |       `-- bar@1.2.3 (cycle)
-    |   `-- asdf@*
-    `-- baz@1.2.3
-        `-- quux@3.x
-            `-- bar
-
-In this case, we might expect a folder structure like this:
-
-    foo
-    +-- node_modules
-        +-- blerg (1.2.5) <---[A]
-        +-- bar (1.2.3) <---[B]
-        |   +-- node_modules
-        |   |   `-- baz (2.0.2) <---[C]
-        |   |       `-- node_modules
-        |   |           `-- quux (3.2.0)
-        |   `-- asdf (2.3.4)
-        `-- baz (1.2.3) <---[D]
-            `-- node_modules
-                `-- quux (3.2.0) <---[E]
-
-Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are
-installed in foo's `node_modules` folder.
-
-Even though the latest copy of blerg is 1.3.7, foo has a specific
-dependency on version 1.2.5.  So, that gets installed at [A].  Since the
-parent installation of blerg satisfie's bar's dependency on blerg@1.x,
-it does not install another copy under [B].
-
-Bar [B] also has dependencies on baz and asdf, so those are installed in
-bar's `node_modules` folder.  Because it depends on `baz@2.x`, it cannot
-re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D],
-and must install its own copy [C].
-
-Underneath bar, the `baz->quux->bar` dependency creates a cycle.
-However, because `bar` is already in `quux`'s ancestry [B], it does not
-unpack another copy of bar into that folder.
-
-Underneath `foo->baz` [D], quux's [E] folder tree is empty, because its
-dependency on bar is satisfied by the parent folder copy installed at [B].
-
-For a graphical breakdown of what is installed where, use `npm ls`.
-
-### Publishing
-
-Upon publishing, npm will look in the `node_modules` folder.  If any of
-the items there are not in the `bundledDependencies` array, then they will
-not be included in the package tarball.
-
-This allows a package maintainer to install all of their dependencies
-(and dev dependencies) locally, but only re-publish those items that
-cannot be found elsewhere.  See `npm-json(1)` for more information.
-
-## SEE ALSO
-
-* npm-faq(1)
-* npm-json(1)
-* npm-install(1)
-* npm-pack(1)
-* npm-cache(1)
-* npm-config(1)
-* npm-publish(1)
diff --git a/doc/cli/adduser.md b/doc/cli/npm-adduser.md
index 51aa6f6a3..ee5c3bd27 100644
--- a/doc/cli/adduser.md
+++ b/doc/cli/npm-adduser.md
@@ -30,7 +30,9 @@ The base URL of the npm package registry.
 
 ## SEE ALSO
 
-* npm-registry(1)
+* npm-registry(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
 * npm-owner(1)
 * npm-whoami(1)
diff --git a/doc/cli/bin.md b/doc/cli/npm-bin.md
index 2c2e7c477..49d209d7f 100644
--- a/doc/cli/bin.md
+++ b/doc/cli/npm-bin.md
@@ -13,5 +13,7 @@ Print the folder where npm will install executables.
 
 * npm-prefix(1)
 * npm-root(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/bugs.md b/doc/cli/npm-bugs.md
index 45ee84b58..2a7dae98d 100644
--- a/doc/cli/bugs.md
+++ b/doc/cli/npm-bugs.md
@@ -33,6 +33,8 @@ The base URL of the npm package registry.
 * npm-docs(1)
 * npm-view(1)
 * npm-publish(1)
-* npm-registry(1)
+* npm-registry(7)
 * npm-config(1)
-* npm-json(1)
+* npm-config(7)
+* npmrc(5)
+* package.json(5)
diff --git a/doc/cli/build.md b/doc/cli/npm-build.md
index 978f4a6d6..53813c1fd 100644
--- a/doc/cli/build.md
+++ b/doc/cli/npm-build.md
@@ -18,5 +18,5 @@ It should generally not be called directly.
 
 * npm-install(1)
 * npm-link(1)
-* npm-scripts(1)
-* npm-json(1)
+* npm-scripts(7)
+* package.json(5)
diff --git a/doc/cli/bundle.md b/doc/cli/npm-bundle.md
index 69b3d83e4..69b3d83e4 100644
--- a/doc/cli/bundle.md
+++ b/doc/cli/npm-bundle.md
diff --git a/doc/cli/cache.md b/doc/cli/npm-cache.md
index 1fa128ad4..195c4aa20 100644
--- a/doc/cli/cache.md
+++ b/doc/cli/npm-cache.md
@@ -63,8 +63,10 @@ The root cache folder.
 
 ## SEE ALSO
 
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
 * npm-install(1)
 * npm-publish(1)
 * npm-pack(1)
diff --git a/doc/cli/completion.md b/doc/cli/npm-completion.md
index 48bc50fd8..bec0f6086 100644
--- a/doc/cli/completion.md
+++ b/doc/cli/npm-completion.md
@@ -24,6 +24,6 @@ completions based on the arguments.
 
 ## SEE ALSO
 
-* npm-developers(1)
-* npm-faq(1)
+* npm-developers(7)
+* npm-faq(7)
 * npm(1)
diff --git a/doc/cli/npm-config.md b/doc/cli/npm-config.md
new file mode 100644
index 000000000..119840ef0
--- /dev/null
+++ b/doc/cli/npm-config.md
@@ -0,0 +1,70 @@
+npm-config(1) -- Manage the npm configuration files
+===================================================
+
+## SYNOPSIS
+
+    npm config set <key> <value> [--global]
+    npm config get <key>
+    npm config delete <key>
+    npm config list
+    npm config edit
+    npm get <key>
+    npm set <key> <value> [--global]
+
+## DESCRIPTION
+
+npm gets its config settings from the command line, environment
+variables, `npmrc` files, and in some cases, the `package.json` file.
+
+See npmrc(5) for more information about the npmrc files.
+
+See `npm-config(7)` for a more thorough discussion of the mechanisms
+involved.
+
+The `npm config` command can be used to update and edit the contents
+of the user and global npmrc files.
+
+## Sub-commands
+
+Config supports the following sub-commands:
+
+### set
+
+    npm config set key value
+
+Sets the config key to the value.
+
+If value is omitted, then it sets it to "true".
+
+### get
+
+    npm config get key
+
+Echo the config value to stdout.
+
+### list
+
+    npm config list
+
+Show all the config settings.
+
+### delete
+
+    npm config delete key
+
+Deletes the key from all configuration files.
+
+### edit
+
+    npm config edit
+
+Opens the config file in an editor.  Use the `--global` flag to edit the
+global config.
+
+## SEE ALSO
+
+* npm-folders(5)
+* npm-config(7)
+* package.json(5)
+* npmrc(5)
+* npm(1)
diff --git a/doc/cli/dedupe.md b/doc/cli/npm-dedupe.md
index 220329acb..220329acb 100644
--- a/doc/cli/dedupe.md
+++ b/doc/cli/npm-dedupe.md
diff --git a/doc/cli/deprecate.md b/doc/cli/npm-deprecate.md
index c45245f09..e62579349 100644
--- a/doc/cli/deprecate.md
+++ b/doc/cli/npm-deprecate.md
@@ -23,4 +23,4 @@ To un-deprecate a package, specify an empty string (`""`) for the `message` argu
 ## SEE ALSO
 
 * npm-publish(1)
-* npm-registry(1)
+* npm-registry(7)
diff --git a/doc/cli/docs.md b/doc/cli/npm-docs.md
index 28fa49193..cc39e82c4 100644
--- a/doc/cli/docs.md
+++ b/doc/cli/npm-docs.md
@@ -33,6 +33,8 @@ The base URL of the npm package registry.
 
 * npm-view(1)
 * npm-publish(1)
-* npm-registry(1)
+* npm-registry(7)
 * npm-config(1)
-* npm-json(1)
+* npm-config(7)
+* npmrc(5)
+* package.json(5)
diff --git a/doc/cli/edit.md b/doc/cli/npm-edit.md
index 9eaccfc54..d833bc06f 100644
--- a/doc/cli/edit.md
+++ b/doc/cli/npm-edit.md
@@ -8,7 +8,7 @@ npm-edit(1) -- Edit an installed package
 ## DESCRIPTION
 
 Opens the package folder in the default editor (or whatever you've
-configured as the npm `editor` config -- see `npm-config(1)`.)
+configured as the npm `editor` config -- see `npm-config(7)`.)
 
 After it has been edited, the package is rebuilt so as to pick up any
 changes in compiled packages.
@@ -29,7 +29,9 @@ The command to run for `npm edit` or `npm config edit`.
 
 ## SEE ALSO
 
-* npm-folders(1)
+* npm-folders(7)
 * npm-explore(1)
 * npm-install(1)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/explore.md b/doc/cli/npm-explore.md
index 00701b392..51846f531 100644
--- a/doc/cli/explore.md
+++ b/doc/cli/npm-explore.md
@@ -33,7 +33,7 @@ The shell to run for the `npm explore` command.
 ## SEE ALSO
 
 * npm-submodule(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-edit(1)
 * npm-rebuild(1)
 * npm-build(1)
diff --git a/doc/cli/help-search.md b/doc/cli/npm-help-search.md
index 9c16901eb..7bf7401ba 100644
--- a/doc/cli/help-search.md
+++ b/doc/cli/npm-help-search.md
@@ -31,5 +31,5 @@ If false, then help-search will just list out the help topics found.
 ## SEE ALSO
 
 * npm(1)
-* npm-faq(1)
+* npm-faq(7)
 * npm-help(1)
diff --git a/doc/cli/help.md b/doc/cli/npm-help.md
index b51b0f164..7a7eadf1f 100644
--- a/doc/cli/help.md
+++ b/doc/cli/npm-help.md
@@ -30,9 +30,11 @@ Set to `"browser"` to view html help content in the default web browser.
 
 * npm(1)
 * README
-* npm-faq(1)
-* npm-folders(1)
+* npm-faq(7)
+* npm-folders(7)
 * npm-config(1)
-* npm-json(1)
+* npm-config(7)
+* npmrc(5)
+* package.json(5)
 * npm-help-search(1)
-* npm-index(1)
+* npm-index(7)
diff --git a/doc/cli/init.md b/doc/cli/npm-init.md
index d036f924d..bd63a8879 100644
--- a/doc/cli/init.md
+++ b/doc/cli/npm-init.md
@@ -21,5 +21,5 @@ without a really good reason to do so.
 ## SEE ALSO
 
 * <https://github.com/isaacs/init-package-json>
-* npm-json(1)
+* package.json(5)
 * npm-version(1)
diff --git a/doc/cli/install.md b/doc/cli/npm-install.md
index 44885f318..f460f2c96 100644
--- a/doc/cli/install.md
+++ b/doc/cli/npm-install.md
@@ -70,7 +70,7 @@ after packing it up into a tarball (b).
 * `npm install <name> [--save|--save-dev|--save-optional]`:
 
     Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
-    `npm-config(1)`.)
+    `npm-config(7)`.)
 
     In most cases, this will install the latest version
     of the module published on npm.
@@ -121,7 +121,7 @@ after packing it up into a tarball (b).
 * `npm install <name>@<version range>`:
 
     Install a version of the package matching the specified version range.  This
-    will follow the same rules for resolving dependencies described in `npm-json(1)`.
+    will follow the same rules for resolving dependencies described in `package.json(5)`.
 
     Note that most version ranges must be put in quotes so that your shell will
     treat it as a single argument.
@@ -160,7 +160,7 @@ local copy exists on disk.
     npm install sax --force
 
 The `--global` argument will cause npm to install the package globally
-rather than locally.  See `npm-folders(1)`.
+rather than locally.  See `npm-folders(7)`.
 
 The `--link` argument will cause npm to link global installs into the
 local space in some cases.
@@ -174,7 +174,7 @@ shrinkwrap file and use the package.json instead.
 The `--nodedir=/path/to/node/source` argument will allow npm to find the
 node source code so that npm can compile native modules.
 
-See `npm-config(1)`.  Many of the configuration params have some
+See `npm-config(7)`.  Many of the configuration params have some
 effect on installation, since that's most of what npm does.
 
 ## ALGORITHM
@@ -202,7 +202,7 @@ this algorithm produces:
 That is, the dependency from B to C is satisfied by the fact that A
 already caused C to be installed at a higher level.
 
-See npm-folders(1) for a more detailed description of the specific
+See npm-folders(7) for a more detailed description of the specific
 folder structures that npm creates.
 
 ### Limitations of npm's Install Algorithm
@@ -228,15 +228,17 @@ affects a real use-case, it will be investigated.
 
 ## SEE ALSO
 
-* npm-folders(1)
+* npm-folders(7)
 * npm-update(1)
 * npm-link(1)
 * npm-rebuild(1)
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-build(1)
 * npm-config(1)
-* npm-registry(1)
-* npm-folders(1)
+* npm-config(7)
+* npmrc(5)
+* npm-registry(7)
+* npm-folders(7)
 * npm-tag(1)
 * npm-rm(1)
 * npm-shrinkwrap(1)
diff --git a/doc/cli/link.md b/doc/cli/npm-link.md
index 4e4ef799b..65476d5c1 100644
--- a/doc/cli/link.md
+++ b/doc/cli/npm-link.md
@@ -52,9 +52,11 @@ installation target into your project's `node_modules` folder.
 
 ## SEE ALSO
 
-* npm-developers(1)
-* npm-faq(1)
-* npm-json(1)
+* npm-developers(7)
+* npm-faq(7)
+* package.json(5)
 * npm-install(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/ls.md b/doc/cli/npm-ls.md
index 9b69b8585..7f1fda669 100644
--- a/doc/cli/ls.md
+++ b/doc/cli/npm-ls.md
@@ -64,7 +64,9 @@ project.
 ## SEE ALSO
 
 * npm-config(1)
-* npm-folders(1)
+* npm-config(7)
+* npmrc(5)
+* npm-folders(7)
 * npm-install(1)
 * npm-link(1)
 * npm-prune(1)
diff --git a/doc/cli/outdated.md b/doc/cli/npm-outdated.md
index 78df4a8b3..b82b666fd 100644
--- a/doc/cli/outdated.md
+++ b/doc/cli/npm-outdated.md
@@ -13,5 +13,5 @@ packages are currently outdated.
 ## SEE ALSO
 
 * npm-update(1)
-* npm-registry(1)
-* npm-folders(1)
+* npm-registry(7)
+* npm-folders(7)
diff --git a/doc/cli/owner.md b/doc/cli/npm-owner.md
index 902e083fc..b400f7637 100644
--- a/doc/cli/owner.md
+++ b/doc/cli/npm-owner.md
@@ -28,6 +28,6 @@ that is not implemented at this time.
 ## SEE ALSO
 
 * npm-publish(1)
-* npm-registry(1)
+* npm-registry(7)
 * npm-adduser(1)
-* npm-disputes(1)
+* npm-disputes(7)
diff --git a/doc/cli/pack.md b/doc/cli/npm-pack.md
index 98d8c81c5..42bc1564b 100644
--- a/doc/cli/pack.md
+++ b/doc/cli/npm-pack.md
@@ -23,3 +23,5 @@ If no arguments are supplied, then npm packs the current package folder.
 * npm-cache(1)
 * npm-publish(1)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/prefix.md b/doc/cli/npm-prefix.md
index f6247cab1..8d88737a9 100644
--- a/doc/cli/prefix.md
+++ b/doc/cli/npm-prefix.md
@@ -13,5 +13,7 @@ Print the prefix to standard out.
 
 * npm-root(1)
 * npm-bin(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/prune.md b/doc/cli/npm-prune.md
index 8c4b957e6..292bacc91 100644
--- a/doc/cli/prune.md
+++ b/doc/cli/npm-prune.md
@@ -17,5 +17,5 @@ package's dependencies list.
 ## SEE ALSO
 
 * npm-rm(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-list(1)
diff --git a/doc/cli/publish.md b/doc/cli/npm-publish.md
index 621932f07..d849c2860 100644
--- a/doc/cli/publish.md
+++ b/doc/cli/npm-publish.md
@@ -23,7 +23,7 @@ the registry.  Overwrites when the "--force" flag is set.
 
 ## SEE ALSO
 
-* npm-registry(1)
+* npm-registry(7)
 * npm-adduser(1)
 * npm-owner(1)
 * npm-deprecate(1)
diff --git a/doc/cli/rebuild.md b/doc/cli/npm-rebuild.md
index 6985a7bdd..6985a7bdd 100644
--- a/doc/cli/rebuild.md
+++ b/doc/cli/npm-rebuild.md
diff --git a/doc/cli/restart.md b/doc/cli/npm-restart.md
index 6139dbeef..4661d6b23 100644
--- a/doc/cli/restart.md
+++ b/doc/cli/npm-restart.md
@@ -16,7 +16,7 @@ If no version is specified, then it restarts the "active" version.
 ## SEE ALSO
 
 * npm-run-script(1)
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-test(1)
 * npm-start(1)
 * npm-stop(1)
diff --git a/doc/cli/rm.md b/doc/cli/npm-rm.md
index f7f743fae..7839d9ddd 100644
--- a/doc/cli/rm.md
+++ b/doc/cli/npm-rm.md
@@ -15,5 +15,7 @@ on its behalf.
 
 * npm-prune(1)
 * npm-install(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/root.md b/doc/cli/npm-root.md
index 3e4199541..346733160 100644
--- a/doc/cli/root.md
+++ b/doc/cli/npm-root.md
@@ -13,5 +13,7 @@ Print the effective `node_modules` folder to standard out.
 
 * npm-prefix(1)
 * npm-bin(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/run-script.md b/doc/cli/npm-run-script.md
index 41ef5e787..6c3c2b7a9 100644
--- a/doc/cli/run-script.md
+++ b/doc/cli/npm-run-script.md
@@ -14,7 +14,7 @@ called directly, as well.
 
 ## SEE ALSO
 
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-test(1)
 * npm-start(1)
 * npm-restart(1)
diff --git a/doc/cli/search.md b/doc/cli/npm-search.md
index e9e408c67..ae7195970 100644
--- a/doc/cli/search.md
+++ b/doc/cli/npm-search.md
@@ -15,6 +15,8 @@ expression characters must be escaped or quoted in most shells.)
 
 ## SEE ALSO
 
-* npm-registry(1)
+* npm-registry(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
 * npm-view(1)
diff --git a/doc/cli/shrinkwrap.md b/doc/cli/npm-shrinkwrap.md
index f0b83d50d..0ecf64466 100644
--- a/doc/cli/shrinkwrap.md
+++ b/doc/cli/npm-shrinkwrap.md
@@ -181,5 +181,5 @@ contents rather than versions.
 ## SEE ALSO
 
 * npm-install(1)
-* npm-json(1)
+* package.json(5)
 * npm-list(1)
diff --git a/doc/cli/star.md b/doc/cli/npm-star.md
index 5c076b3c3..5c076b3c3 100644
--- a/doc/cli/star.md
+++ b/doc/cli/npm-star.md
diff --git a/doc/cli/stars.md b/doc/cli/npm-stars.md
index 7c28f5b2a..7c28f5b2a 100644
--- a/doc/cli/stars.md
+++ b/doc/cli/npm-stars.md
diff --git a/doc/cli/start.md b/doc/cli/npm-start.md
index cc897bbc0..01347d2e4 100644
--- a/doc/cli/start.md
+++ b/doc/cli/npm-start.md
@@ -12,7 +12,7 @@ This runs a package's "start" script, if one was provided.
 ## SEE ALSO
 
 * npm-run-script(1)
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-test(1)
 * npm-restart(1)
 * npm-stop(1)
diff --git a/doc/cli/stop.md b/doc/cli/npm-stop.md
index 1ab3e9975..bda5cc8f4 100644
--- a/doc/cli/stop.md
+++ b/doc/cli/npm-stop.md
@@ -12,7 +12,7 @@ This runs a package's "stop" script, if one was provided.
 ## SEE ALSO
 
 * npm-run-script(1)
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-test(1)
 * npm-start(1)
 * npm-restart(1)
diff --git a/doc/cli/submodule.md b/doc/cli/npm-submodule.md
index 13ab1edd9..7f0fbfc9f 100644
--- a/doc/cli/submodule.md
+++ b/doc/cli/npm-submodule.md
@@ -24,5 +24,5 @@ dependencies into the submodule folder.
 
 ## SEE ALSO
 
-* npm-json(1)
+* package.json(5)
 * git help submodule
diff --git a/doc/cli/tag.md b/doc/cli/npm-tag.md
index 2f1ca4373..597c42f27 100644
--- a/doc/cli/tag.md
+++ b/doc/cli/npm-tag.md
@@ -13,5 +13,7 @@ Tags the specified version of the package with the specified tag, or the
 ## SEE ALSO
 
 * npm-publish(1)
-* npm-registry(1)
+* npm-registry(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/test.md b/doc/cli/npm-test.md
index bc634efbf..159914cb0 100644
--- a/doc/cli/test.md
+++ b/doc/cli/npm-test.md
@@ -15,7 +15,7 @@ true.
 ## SEE ALSO
 
 * npm-run-script(1)
-* npm-scripts(1)
+* npm-scripts(7)
 * npm-start(1)
 * npm-restart(1)
 * npm-stop(1)
diff --git a/doc/cli/uninstall.md b/doc/cli/npm-uninstall.md
index f7f743fae..7839d9ddd 100644
--- a/doc/cli/uninstall.md
+++ b/doc/cli/npm-uninstall.md
@@ -15,5 +15,7 @@ on its behalf.
 
 * npm-prune(1)
 * npm-install(1)
-* npm-folders(1)
+* npm-folders(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
diff --git a/doc/cli/unpublish.md b/doc/cli/npm-unpublish.md
index 0f4446c4e..f749ab7a6 100644
--- a/doc/cli/unpublish.md
+++ b/doc/cli/npm-unpublish.md
@@ -27,6 +27,6 @@ the root package entry is removed from the registry entirely.
 
 * npm-deprecate(1)
 * npm-publish(1)
-* npm-registry(1)
+* npm-registry(7)
 * npm-adduser(1)
 * npm-owner(1)
diff --git a/doc/cli/update.md b/doc/cli/npm-update.md
index 302e2efff..9ebdda72a 100644
--- a/doc/cli/update.md
+++ b/doc/cli/npm-update.md
@@ -19,6 +19,6 @@ If no package name is specified, all packages in the specified location (global
 
 * npm-install(1)
 * npm-outdated(1)
-* npm-registry(1)
-* npm-folders(1)
+* npm-registry(7)
+* npm-folders(7)
 * npm-list(1)
diff --git a/doc/cli/version.md b/doc/cli/npm-version.md
index 74d938d6b..1cacd8d00 100644
--- a/doc/cli/version.md
+++ b/doc/cli/npm-version.md
@@ -41,5 +41,5 @@ in your git config for this to work properly.  For example:
 ## SEE ALSO
 
 * npm-init(1)
-* npm-json(1)
-* npm-semver(1)
+* package.json(5)
+* npm-semver(7)
diff --git a/doc/cli/view.md b/doc/cli/npm-view.md
index 07836a5ef..5f25afa65 100644
--- a/doc/cli/view.md
+++ b/doc/cli/npm-view.md
@@ -55,7 +55,7 @@ can do this:
 
 "Person" fields are shown as a string if they would be shown as an
 object.  So, for example, this will show the list of npm contributors in
-the shortened string format.  (See `npm-json(1)` for more on this.)
+the shortened string format.  (See `package.json(5)` for more on this.)
 
     npm view npm contributors
 
@@ -82,6 +82,8 @@ the field name.
 ## SEE ALSO
 
 * npm-search(1)
-* npm-registry(1)
+* npm-registry(7)
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
 * npm-docs(1)
diff --git a/doc/cli/whoami.md b/doc/cli/npm-whoami.md
index 7c39b1624..3ff8837ff 100644
--- a/doc/cli/whoami.md
+++ b/doc/cli/npm-whoami.md
@@ -12,4 +12,6 @@ Print the `username` config to standard output.
 ## SEE ALSO
 
 * npm-config(1)
+* npm-config(7)
+* npmrc(5)
 * npm-adduser(1)
diff --git a/doc/cli/npm.md b/doc/cli/npm.md
index a325fdf2e..5c935af84 100644
--- a/doc/cli/npm.md
+++ b/doc/cli/npm.md
@@ -33,7 +33,7 @@ Use `npm ls` to show everything you've installed.
 
 ## DIRECTORIES
 
-See `npm-folders(1)` to learn about where npm puts stuff.
+See `npm-folders(7)` to learn about where npm puts stuff.
 
 In particular, npm has two modes of operation:
 
@@ -54,7 +54,7 @@ If you're using npm to develop and publish your code, check out the
 following help topics:
 
 * json:
-  Make a package.json file.  See `npm-json(1)`.
+  Make a package.json file.  See `package.json(5)`.
 * link:
   For linking your current working code into Node's path, so that you
   don't have to reinstall every time you make a change.  Use
@@ -95,14 +95,14 @@ npm is extremely configurable.  It reads its configuration options from
   npm's default configuration options are defined in
   lib/utils/config-defs.js.  These must not be changed.
 
-See `npm-config(1)` for much much more information.
+See `npm-config(7)` for much much more information.
 
 ## CONTRIBUTIONS
 
 Patches welcome!
 
 * code:
-  Read through `npm-coding-style(1)` if you plan to submit code.
+  Read through `npm-coding-style(7)` if you plan to submit code.
   You don't have to agree with it, but you do have to follow it.
 * docs:
   If you find an error in the documentation, edit the appropriate markdown
@@ -146,10 +146,12 @@ See npm-changelog(1)
 ## SEE ALSO
 
 * npm-help(1)
-* npm-faq(1)
+* npm-faq(7)
 * README
-* npm-json(1)
+* package.json(5)
 * npm-install(1)
 * npm-config(1)
-* npm-index(1)
+* npm-config(7)
+* npmrc(5)
+* npm-index(7)
 * npm(3)
diff --git a/doc/cli/folders.md b/doc/files/npm-folders.md
index 04fc13cfb..1b1485d5e 100644
--- a/doc/cli/folders.md
+++ b/doc/files/npm-folders.md
@@ -1,4 +1,4 @@
-npm-folders(1) -- Folder Structures Used by npm
+npm-folders(5) -- Folder Structures Used by npm
 ===============================================
 
 ## DESCRIPTION
@@ -196,14 +196,16 @@ not be included in the package tarball.
 
 This allows a package maintainer to install all of their dependencies
 (and dev dependencies) locally, but only re-publish those items that
-cannot be found elsewhere.  See `npm-json(1)` for more information.
+cannot be found elsewhere.  See `package.json(5)` for more information.
 
 ## SEE ALSO
 
-* npm-faq(1)
-* npm-json(1)
+* npm-faq(7)
+* package.json(5)
 * npm-install(1)
 * npm-pack(1)
 * npm-cache(1)
 * npm-config(1)
+* npmrc(5)
+* npm-config(7)
 * npm-publish(1)
diff --git a/doc/files/npmrc.md b/doc/files/npmrc.md
new file mode 100644
index 000000000..e65f722fd
--- /dev/null
+++ b/doc/files/npmrc.md
@@ -0,0 +1,59 @@
+npmrc(5) -- The npm config files
+================================
+
+## DESCRIPTION
+
+npm gets its config settings from the command line, environment
+variables, and `npmrc` files.
+
+The `npm config` command can be used to update and edit the contents
+of the user and global npmrc files.
+
+For a list of available configuration options, see npm-config(7).
+
+## FILES
+
+The three relevant files are:
+
+* per-user config file (~/.npmrc)
+* global config file ($PREFIX/npmrc)
+* npm builtin config file (/path/to/npm/npmrc)
+
+All npm config files are an ini-formatted list of `key = value`
+parameters.  Environment variables can be replaced using
+`${VARIABLE_NAME}`. For example:
+
+    prefix = ${HOME}/.npm-packages
+
+Each of these files is loaded, and config options are resolved in
+priority order.  For example, a setting in the userconfig file would
+override the setting in the globalconfig file.
+
+### Per-user config file
+
+`$HOME/.npmrc` (or the `userconfig` param, if set in the environment
+or on the command line)
+
+### Global config file
+
+`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above):
+This file is an ini-file formatted list of `key = value` parameters.
+Environment variables can be replaced as above.
+
+### Built-in config file
+
+`path/to/npm/itself/npmrc`
+
+This is an unchangeable "builtin" configuration file that npm keeps
+consistent across updates.  Set fields in here using the `./configure`
+script that comes with npm.  This is primarily for distribution
+maintainers to override default configs in a standard and consistent
+manner.
+
+## SEE ALSO
+
+* npm-folders(5)
+* npm-config(1)
+* npm-config(7)
+* package.json(5)
+* npm(1)
diff --git a/doc/cli/json.md b/doc/files/package.json.md
index 403f7f856..8155a3e9b 100644
--- a/doc/cli/json.md
+++ b/doc/files/package.json.md
@@ -1,5 +1,5 @@
-npm-json(1) -- Specifics of npm's package.json handling
-=======================================================
+package.json(5) -- Specifics of npm's package.json handling
+===========================================================
 
 ## DESCRIPTION
 
@@ -7,7 +7,7 @@ This document is all you need to know about what's required in your package.json
 file.  It must be actual JSON, not just a JavaScript object literal.
 
 A lot of the behavior described in this document is affected by the config
-settings described in `npm-config(1)`.
+settings described in `npm-config(7)`.
 
 ## DEFAULT VALUES
 
@@ -315,7 +315,7 @@ The "scripts" member is an object hash of script commands that are run
 at various times in the lifecycle of your package.  The key is the lifecycle
 event, and the value is the command to run at that point.
 
-See `npm-scripts(1)` to find out more about writing package scripts.
+See `npm-scripts(7)` to find out more about writing package scripts.
 
 ## config
 
@@ -330,7 +330,7 @@ and then had a "start" command that then referenced the
 `npm_package_config_port` environment variable, then the user could
 override that by doing `npm config set foo:port 8001`.
 
-See `npm-config(1)` and `npm-scripts(1)` for more on package
+See `npm-config(7)` and `npm-scripts(7)` for more on package
 configs.
 
 ## dependencies
@@ -439,7 +439,7 @@ In this case, it's best to list these additional items in a
 These things will be installed whenever the `--dev` configuration flag
 is set.  This flag is set automatically when doing `npm link` or when doing
 `npm install` from the root of a package, and can be managed like any other npm
-configuration param.  See `npm-config(1)` for more on the topic.
+configuration param.  See `npm-config(7)` for more on the topic.
 
 ## bundledDependencies
 
@@ -571,17 +571,18 @@ the global public registry by default.
 Any config values can be overridden, but of course only "tag" and
 "registry" probably matter for the purposes of publishing.
 
-See `npm-config(1)` to see the list of config options that can be
+See `npm-config(7)` to see the list of config options that can be
 overridden.
 
 ## SEE ALSO
 
-* npm-semver(1)
+* npm-semver(7)
 * npm-init(1)
 * npm-version(1)
 * npm-config(1)
+* npm-config(7)
 * npm-help(1)
-* npm-faq(1)
+* npm-faq(7)
 * npm-install(1)
 * npm-publish(1)
 * npm-rm(1)
diff --git a/doc/cli/coding-style.md b/doc/misc/npm-coding-style.md
index 1aa3e80e2..e9333d0ec 100644
--- a/doc/cli/coding-style.md
+++ b/doc/misc/npm-coding-style.md
@@ -1,4 +1,4 @@
-npm-coding-style(1) -- npm's "funny" coding style
+npm-coding-style(7) -- npm's "funny" coding style
 =================================================
 
 ## DESCRIPTION
@@ -141,7 +141,7 @@ logging the same object over and over again is not helpful.  Logs should
 report what's happening so that it's easier to track down where a fault
 occurs.
 
-Use appropriate log levels.  See `npm-config(1)` and search for
+Use appropriate log levels.  See `npm-config(7)` and search for
 "loglevel".
 
 ## Case, naming, etc.
@@ -176,6 +176,6 @@ Boolean objects are verboten.
 
 ## SEE ALSO
 
-* npm-developers(1)
-* npm-faq(1)
+* npm-developers(7)
+* npm-faq(7)
 * npm(1)
diff --git a/doc/cli/config.md b/doc/misc/npm-config.md
index 54133bec3..d622f07e1 100644
--- a/doc/cli/config.md
+++ b/doc/misc/npm-config.md
@@ -1,15 +1,5 @@
-npm-config(1) -- Manage the npm configuration file
-==================================================
-
-## SYNOPSIS
-
-    npm config set <key> <value> [--global]
-    npm config get <key>
-    npm config delete <key>
-    npm config list
-    npm config edit
-    npm get <key>
-    npm set <key> <value> [--global]
+npm-config(7) -- More than you probably want to know about npm configuration
+============================================================================
 
 ## DESCRIPTION
 
@@ -17,87 +7,36 @@ npm gets its configuration values from 6 sources, in this priority:
 
 ### Command Line Flags
 
-Putting `--foo bar` on the command line sets the
-`foo` configuration parameter to `"bar"`.  A `--` argument tells the cli
-parser to stop reading flags.  A `--flag` parameter that is at the *end* of
-the command will be given the value of `true`.
+Putting `--foo bar` on the command line sets the `foo` configuration
+parameter to `"bar"`.  A `--` argument tells the cli parser to stop
+reading flags.  A `--flag` parameter that is at the *end* of the
+command will be given the value of `true`.
 
 ### Environment Variables
 
-Any environment variables that start with `npm_config_` will be interpreted
-as a configuration parameter.  For example, putting `npm_config_foo=bar` in
-your environment will set the `foo` configuration parameter to `bar`.  Any
-environment configurations that are not given a value will be given the value
-of `true`.  Config values are case-insensitive, so `NPM_CONFIG_FOO=bar` will
-work the same.
-
-### Per-user config file
-
-`$HOME/.npmrc` (or the `userconfig` param, if set above)
-
-This file is an ini-file formatted list of `key = value` parameters.
-Environment variables can be replaced using `${VARIABLE_NAME}`. For example:
-
-    prefix = ${HOME}/.npm-packages
-
-### Global config file
+Any environment variables that start with `npm_config_` will be
+interpreted as a configuration parameter.  For example, putting
+`npm_config_foo=bar` in your environment will set the `foo`
+configuration parameter to `bar`.  Any environment configurations that
+are not given a value will be given the value of `true`.  Config
+values are case-insensitive, so `NPM_CONFIG_FOO=bar` will work the
+same.
 
-`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above):
-This file is an ini-file formatted list of `key = value` parameters.
-Environment variables can be replaced as above.
+### npmrc Files
 
-### Built-in config file
+The three relevant files are:
 
-`path/to/npm/itself/npmrc`
+* per-user config file (~/.npmrc)
+* global config file ($PREFIX/npmrc)
+* npm builtin config file (/path/to/npm/npmrc)
 
-This is an unchangeable "builtin"
-configuration file that npm keeps consistent across updates.  Set
-fields in here using the `./configure` script that comes with npm.
-This is primarily for distribution maintainers to override default
-configs in a standard and consistent manner.
+See npmrc(5) for more details.
 
 ### Default Configs
 
 A set of configuration parameters that are internal to npm, and are
 defaults if nothing else is specified.
 
-## Sub-commands
-
-Config supports the following sub-commands:
-
-### set
-
-    npm config set key value
-
-Sets the config key to the value.
-
-If value is omitted, then it sets it to "true".
-
-### get
-
-    npm config get key
-
-Echo the config value to stdout.
-
-### list
-
-    npm config list
-
-Show all the config settings.
-
-### delete
-
-    npm config delete key
-
-Deletes the key from all configuration files.
-
-### edit
-
-    npm config edit
-
-Opens the config file in an editor.  Use the `--global` flag to edit the
-global config.
-
 ## Shorthands and Other CLI Niceties
 
 The following shorthands are parsed on the command-line:
@@ -144,10 +83,10 @@ example:
 
 ## Per-Package Config Settings
 
-When running scripts (see `npm-scripts(1)`)
-the package.json "config" keys are overwritten in the environment if
-there is a config param of `<name>[@<version>]:<key>`.  For example, if
-the package.json has this:
+When running scripts (see `npm-scripts(7)`) the package.json "config"
+keys are overwritten in the environment if there is a config param of
+`<name>[@<version>]:<key>`.  For example, if the package.json has
+this:
 
     { "name" : "foo"
     , "config" : { "port" : "8080" }
@@ -161,6 +100,8 @@ then the user could change the behavior by doing:
 
     npm config set foo:port 80
 
+See package.json(5) for more information.
+
 ## Config Settings
 
 ### always-auth
@@ -371,7 +312,7 @@ the git binary.
 
 Operates in "global" mode, so that packages are installed into the
 `prefix` folder instead of the current working directory.  See
-`npm-folders(1)` for more on the differences in behavior.
+`npm-folders(7)` for more on the differences in behavior.
 
 * packages are installed into the `{prefix}/lib/node_modules` folder, instead of the
   current working directory.
@@ -584,7 +525,7 @@ standard output.
 
 ### prefix
 
-* Default: see npm-folders(1)
+* Default: see npm-folders(7)
 * Type: path
 
 The location to install global items.  If set on the command line, then
@@ -878,5 +819,9 @@ then answer "no" to any prompt.
 
 ## SEE ALSO
 
-* npm-folders(1)
+* npm-config(1)
+* npm-config(7)
+* npmrc(5)
+* npm-scripts(7)
+* npm-folders(5)
 * npm(1)
diff --git a/doc/cli/developers.md b/doc/misc/npm-developers.md
index d1ffd5aa8..5e53301f3 100644
--- a/doc/cli/developers.md
+++ b/doc/misc/npm-developers.md
@@ -1,4 +1,4 @@
-npm-developers(1) -- Developer Guide
+npm-developers(7) -- Developer Guide
 ====================================
 
 ## DESCRIPTION
@@ -49,7 +49,7 @@ an argument to `git checkout`.  The default is `master`.
 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 `npm-json(1)` for details about what goes in that file.  At the very
+See `package.json(5)` for details about what goes in that file.  At the very
 least, you need:
 
 * name:
@@ -78,7 +78,7 @@ least, you need:
   If you have a special compilation or installation script, then you
   should put it in the `scripts` hash.  You should definitely have at
   least a basic smoke-test command as the "scripts.test" field.
-  See npm-scripts(1).
+  See npm-scripts(7).
 
 * main:
   If you have a single module that serves as the entry point to your
@@ -197,11 +197,11 @@ Tell the world how easy it is to install your program!
 
 ## SEE ALSO
 
-* npm-faq(1)
+* npm-faq(7)
 * npm(1)
 * npm-init(1)
-* npm-json(1)
-* npm-scripts(1)
+* package.json(5)
+* npm-scripts(7)
 * npm-publish(1)
 * npm-adduser(1)
-* npm-registry(1)
+* npm-registry(7)
diff --git a/doc/cli/disputes.md b/doc/misc/npm-disputes.md
index 52d2a2e56..6e9f4bfcd 100644
--- a/doc/cli/disputes.md
+++ b/doc/misc/npm-disputes.md
@@ -1,4 +1,4 @@
-npm-disputes(1) -- Handling Module Name Disputes
+npm-disputes(7) -- Handling Module Name Disputes
 ================================================
 
 ## SYNOPSIS
@@ -94,5 +94,5 @@ If you see bad behavior like this, please report it right away.
 
 ## SEE ALSO
 
-* npm-registry(1)
+* npm-registry(7)
 * npm-owner(1)
diff --git a/doc/cli/faq.md b/doc/misc/npm-faq.md
index e00fec61d..32493d36e 100644
--- a/doc/cli/faq.md
+++ b/doc/misc/npm-faq.md
@@ -1,4 +1,4 @@
-npm-faq(1) -- Frequently Asked Questions
+npm-faq(7) -- Frequently Asked Questions
 ========================================
 
 ## Where can I find these docs in HTML?
@@ -22,7 +22,7 @@ do what it says and post a bug with all the information it asks for.
 
 ## Where does npm put stuff?
 
-See `npm-folders(1)`
+See `npm-folders(5)`
 
 tl;dr:
 
@@ -58,7 +58,7 @@ problems than it solves.
 
 It is much harder to avoid dependency conflicts without nesting
 dependencies.  This is fundamental to the way that npm works, and has
-proven to be an extremely successful approach.  See `npm-folders(1)` for
+proven to be an extremely successful approach.  See `npm-folders(5)` for
 more details.
 
 If you want a package to be installed in one place, and have all your
@@ -280,12 +280,12 @@ Windows:
 
 ## How can I use npm for development?
 
-See `npm-developers(1)` and `npm-json(1)`.
+See `npm-developers(7)` and `package.json(5)`.
 
 You'll most likely want to `npm link` your development folder.  That's
 awesomely handy.
 
-To set up your own private registry, check out `npm-registry(1)`.
+To set up your own private registry, check out `npm-registry(7)`.
 
 ## Can I list a url as a dependency?
 
@@ -299,7 +299,7 @@ See `npm-link(1)`
 
 ## The package registry website.  What is that exactly?
 
-See `npm-registry(1)`.
+See `npm-registry(7)`.
 
 ## I forgot my password, and can't publish.  How do I reset it?
 
@@ -346,7 +346,10 @@ npm is not capable of hatred.  It loves everyone, especially you.
 ## SEE ALSO
 
 * npm(1)
-* npm-developers(1)
-* npm-json(1)
+* npm-developers(7)
+* package.json(5)
 * npm-config(1)
-* npm-folders(1)
+* npm-config(7)
+* npmrc(5)
+* npm-config(7)
+* npm-folders(5)
diff --git a/doc/cli/registry.md b/doc/misc/npm-registry.md
index 9173defef..0081984f7 100644
--- a/doc/cli/registry.md
+++ b/doc/misc/npm-registry.md
@@ -1,4 +1,4 @@
-npm-registry(1) -- The JavaScript Package Registry
+npm-registry(7) -- The JavaScript Package Registry
 ==================================================
 
 ## DESCRIPTION
@@ -19,7 +19,8 @@ are CouchDB users, stored in the <http://isaacs.iriscouch.com/_users>
 database.
 
 The registry URL is supplied by the `registry` config parameter.  See
-`npm-config(1)` for more on managing npm's configuration.
+`npm-config(1)`, `npmrc(5)`, and `npm-config(7)` for more on managing
+npm's configuration.
 
 ## Can I run my own private registry?
 
@@ -42,7 +43,7 @@ published at all, or
 `"publishConfig":{"registry":"http://my-internal-registry.local"}`
 to force it to be published only to your internal registry.
 
-See `npm-json(1)` for more info on what goes in the package.json file.
+See `package.json(5)` for more info on what goes in the package.json file.
 
 ## Will you replicate from my registry into the public one?
 
@@ -87,5 +88,7 @@ Yes, head over to <https://npmjs.org/>
 ## SEE ALSO
 
 * npm-config(1)
-* npm-developers(1)
-* npm-disputes(1)
+* npm-config(7)
+* npmrc(5)
+* npm-developers(7)
+* npm-disputes(7)
diff --git a/doc/cli/scripts.md b/doc/misc/npm-scripts.md
index 0eba5f7b1..b3f47699a 100644
--- a/doc/cli/scripts.md
+++ b/doc/misc/npm-scripts.md
@@ -1,4 +1,4 @@
-npm-scripts(1) -- How npm handles the "scripts" field
+npm-scripts(7) -- How npm handles the "scripts" field
 =====================================================
 
 ## DESCRIPTION
@@ -96,49 +96,50 @@ npm will default some script values based on package contents.
 
 ## USER
 
-If npm was invoked with root privileges, then it will change the uid to
-the user account or uid specified by the `user` config, which defaults
-to `nobody`.  Set the `unsafe-perm` flag to run scripts with root
-privileges.
+If npm was invoked with root privileges, then it will change the uid
+to the user account or uid specified by the `user` config, which
+defaults to `nobody`.  Set the `unsafe-perm` flag to run scripts with
+root privileges.
 
 ## ENVIRONMENT
 
-Package scripts run in an environment where many pieces of information are
-made available regarding the setup of npm and the current state of the
-process.
+Package scripts run in an environment where many pieces of information
+are made available regarding the setup of npm and the current state of
+the process.
 
 
 ### path
 
-If you depend on modules that define executable scripts, like test suites,
-then those executables will be added to the `PATH` for executing the scripts.
-So, if your package.json has this:
+If you depend on modules that define executable scripts, like test
+suites, then those executables will be added to the `PATH` for
+executing the scripts.  So, if your package.json has this:
 
     { "name" : "foo"
     , "dependencies" : { "bar" : "0.1.x" }
     , "scripts": { "start" : "bar ./test" } }
 
-then you could run `npm start` to execute the `bar` script, which is exported
-into the `node_modules/.bin` directory on `npm install`.
+then you could run `npm start` to execute the `bar` script, which is
+exported into the `node_modules/.bin` directory on `npm install`.
 
 ### package.json vars
 
-The package.json fields are tacked onto the `npm_package_` prefix. So, for
-instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json
-file, then your package scripts would have the `npm_package_name` environment
-variable set to "foo", and the `npm_package_version` set to "1.2.5"
+The package.json fields are tacked onto the `npm_package_` prefix. So,
+for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your
+package.json file, then your package scripts would have the
+`npm_package_name` environment variable set to "foo", and the
+`npm_package_version` set to "1.2.5"
 
 ### configuration
 
-Configuration parameters are put in the environment with the `npm_config_`
-prefix. For instance, you can view the effective `root` config by checking the
-`npm_config_root` environment variable.
+Configuration parameters are put in the environment with the
+`npm_config_` prefix. For instance, you can view the effective `root`
+config by checking the `npm_config_root` environment variable.
 
 ### Special: package.json "config" hash
 
 The package.json "config" keys are overwritten in the environment if
-there is a config param of `<name>[@<version>]:<key>`.  For example, if
-the package.json has this:
+there is a config param of `<name>[@<version>]:<key>`.  For example,
+if the package.json has this:
 
     { "name" : "foo"
     , "config" : { "port" : "8080" }
@@ -154,15 +155,14 @@ then the user could change the behavior by doing:
 
 ### current lifecycle event
 
-Lastly, the `npm_lifecycle_event` environment variable is set to whichever
-stage of the cycle is being executed. So, you could have a single script used
-for different parts of the process which switches based on what's currently
-happening.
-
+Lastly, the `npm_lifecycle_event` environment variable is set to
+whichever stage of the cycle is being executed. So, you could have a
+single script used for different parts of the process which switches
+based on what's currently happening.
 
 Objects are flattened following this format, so if you had
-`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this
-in the script:
+`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd
+see this in the script:
 
     process.env.npm_package_scripts_install === "foo.js"
 
@@ -177,13 +177,15 @@ For example, if your package.json contains this:
       }
     }
 
-then the `scripts/install.js` will be called for the install, post-install,
-stages of the lifecycle, and the `scripts/uninstall.js` would be
-called when the package is uninstalled.  Since `scripts/install.js` is running
-for three different phases, it would be wise in this case to look at the
-`npm_lifecycle_event` environment variable.
+then the `scripts/install.js` will be called for the install,
+post-install, stages of the lifecycle, and the `scripts/uninstall.js`
+would be called when the package is uninstalled.  Since
+`scripts/install.js` is running for three different phases, it would
+be wise in this case to look at the `npm_lifecycle_event` environment
+variable.
 
-If you want to run a make command, you can do so.  This works just fine:
+If you want to run a make command, you can do so.  This works just
+fine:
 
     { "scripts" :
       { "preinstall" : "./configure"
@@ -199,43 +201,45 @@ Scripts are run by passing the line as a script argument to `sh`.
 If the script exits with a code other than 0, then this will abort the
 process.
 
-Note that these script files don't have to be nodejs or even javascript
-programs. They just have to be some kind of executable file.
+Note that these script files don't have to be nodejs or even
+javascript programs. They just have to be some kind of executable
+file.
 
 ## HOOK SCRIPTS
 
-If you want to run a specific script at a specific lifecycle event for ALL
-packages, then you can use a hook script.
+If you want to run a specific script at a specific lifecycle event for
+ALL packages, then you can use a hook script.
 
-Place an executable file at `node_modules/.hooks/{eventname}`, and it'll get
-run for all packages when they are going through that point in the package
-lifecycle for any packages installed in that root.
+Place an executable file at `node_modules/.hooks/{eventname}`, and
+it'll get run for all packages when they are going through that point
+in the package lifecycle for any packages installed in that root.
 
-Hook scripts are run exactly the same way as package.json scripts.  That is,
-they are in a separate child process, with the env described above.
+Hook scripts are run exactly the same way as package.json scripts.
+That is, they are in a separate child process, with the env described
+above.
 
 ## BEST PRACTICES
 
 * Don't exit with a non-zero error code unless you *really* mean it.
-  Except for uninstall scripts, this will cause the npm action
-  to fail, and potentially be rolled back.  If the failure is minor or
+  Except for uninstall scripts, this will cause the npm action to
+  fail, and potentially be rolled back.  If the failure is minor or
   only will prevent some optional features, then it's better to just
   print a warning and exit successfully.
 * Try not to use scripts to do what npm can do for you.  Read through
-  `npm-json(1)` to see all the things that you can specify and enable
-  by simply describing your package appropriately.  In general, this will
-  lead to a more robust and consistent state.
+  `package.json(5)` to see all the things that you can specify and enable
+  by simply describing your package appropriately.  In general, this
+  will lead to a more robust and consistent state.
 * Inspect the env to determine where to put things.  For instance, if
-  the `npm_config_binroot` environ is set to `/home/user/bin`, then don't
-  try to install executables into `/usr/local/bin`.  The user probably
-  set it up that way for a reason.
-* Don't prefix your script commands with "sudo".  If root permissions are
-  required for some reason, then it'll fail with that error, and the user
-  will sudo the npm command in question.
+  the `npm_config_binroot` environ is set to `/home/user/bin`, then
+  don't try to install executables into `/usr/local/bin`.  The user
+  probably set it up that way for a reason.
+* Don't prefix your script commands with "sudo".  If root permissions
+  are required for some reason, then it'll fail with that error, and
+  the user will sudo the npm command in question.
 
 ## SEE ALSO
 
 * npm-run-script(1)
-* npm-json(1)
-* npm-developers(1)
+* package.json(5)
+* npm-developers(7)
 * npm-install(1)
diff --git a/doc/cli/removing-npm.md b/doc/misc/removing-npm.md
index bedd28a2f..bedd28a2f 100644
--- a/doc/cli/removing-npm.md
+++ b/doc/misc/removing-npm.md
diff --git a/doc/cli/semver.md b/doc/misc/semver.md
index 2c499a984..b8e193948 100644
--- a/doc/cli/semver.md
+++ b/doc/misc/semver.md
@@ -1,4 +1,4 @@
-semver(1) -- The semantic versioner for npm
+semver(7) -- The semantic versioner for npm
 ===========================================
 
 ## Usage
diff --git a/html/docfoot-script.html b/html/docfoot-script.html
new file mode 100644
index 000000000..c0fea672a
--- /dev/null
+++ b/html/docfoot-script.html
@@ -0,0 +1,31 @@
+<script>
+;(function () {
+var wrapper = document.getElementById("wrapper")
+var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0)
+  .filter(function (el) {
+    return el.parentNode === wrapper
+        && el.tagName.match(/H[1-6]/)
+        && el.id
+  })
+var l = 2
+  , toc = document.createElement("ul")
+toc.innerHTML = els.map(function (el) {
+  var i = el.tagName.charAt(1)
+    , out = ""
+  while (i > l) {
+    out += "<ul>"
+    l ++
+  }
+  while (i < l) {
+    out += "</ul>"
+    l --
+  }
+  out += "<li><a href='#" + el.id + "'>" +
+    ( el.innerText || el.text || el.innerHTML)
+    + "</a>"
+  return out
+}).join("\n")
+toc.id = "toc"
+document.body.appendChild(toc)
+})()
+</script>
diff --git a/html/docfoot.html b/html/docfoot.html
index 3e35341cc..237b89718 100644
--- a/html/docfoot.html
+++ b/html/docfoot.html
@@ -1,34 +1,2 @@
 </div>
 <p id="footer">@NAME@ &mdash; npm@@VERSION@</p>
-<script>
-;(function () {
-var wrapper = document.getElementById("wrapper")
-var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0)
-  .filter(function (el) {
-    return el.parentNode === wrapper
-        && el.tagName.match(/H[1-6]/)
-        && el.id
-  })
-var l = 2
-  , toc = document.createElement("ul")
-toc.innerHTML = els.map(function (el) {
-  var i = el.tagName.charAt(1)
-    , out = ""
-  while (i > l) {
-    out += "<ul>"
-    l ++
-  }
-  while (i < l) {
-    out += "</ul>"
-    l --
-  }
-  out += "<li><a href='#" + el.id + "'>" +
-    ( el.innerText || el.text || el.innerHTML)
-    + "</a>"
-  return out
-}).join("\n")
-toc.id = "toc"
-document.body.appendChild(toc)
-})()
-</script>
-</body></html>
diff --git a/html/dochead.html b/html/dochead.html
index 1526e1b7b..01f4d2f05 100644
--- a/html/dochead.html
+++ b/html/dochead.html
@@ -2,7 +2,7 @@
 <html>
   <title>@NAME@</title>
   <meta http-equiv="content-type" value="text/html;utf-8">
-  <link rel="stylesheet" type="text/css" href="../static/style.css">
+  <link rel="stylesheet" type="text/css" href="../../static/style.css">
 
   <body>
     <div id="wrapper">
diff --git a/lib/build.js b/lib/build.js
index fdbae722c..176022559 100644
--- a/lib/build.js
+++ b/lib/build.js
@@ -202,17 +202,12 @@ function linkMans (pkg, folder, parent, gtop, cb) {
   var manRoot = path.resolve(npm.config.get("prefix"), "share", "man")
   asyncMap(pkg.man, function (man, cb) {
     if (typeof man !== "string") return cb()
-    var parseMan = man.match(/(.*)\.([0-9]+)(\.gz)?$/)
+    var parseMan = man.match(/(.*\.([0-9]+)(\.gz)?)$/)
       , stem = parseMan[1]
       , sxn = parseMan[2]
       , gz = parseMan[3] || ""
       , bn = path.basename(stem)
-      , manDest = path.join( manRoot
-                           , "man"+sxn
-                           , (bn.indexOf(pkg.name) === 0 ? bn
-                             : pkg.name + "-" + bn)
-                             + "." + sxn + gz
-                           )
+      , manDest = path.join(manRoot, "man" + sxn, bn)
 
     linkIfExists(man, manDest, gtop && folder, cb)
   }, cb)
diff --git a/lib/help-search.js b/lib/help-search.js
index b0b15baca..590fe270b 100644
--- a/lib/help-search.js
+++ b/lib/help-search.js
@@ -8,6 +8,7 @@ var fs = require("graceful-fs")
   , apiDocsPath = path.join(__dirname, "..", "doc", "api")
   , log = require("npmlog")
   , npm = require("./npm.js")
+  , glob = require("glob")
 
 helpSearch.usage = "npm help-search <text>"
 
@@ -17,177 +18,199 @@ function helpSearch (args, silent, cb) {
 
   // see if we're actually searching the api docs.
   var argv = npm.config.get("argv").cooked
-    , docsPath = cliDocsPath
-    , cmd = "help"
-  if (argv.length && argv[0].indexOf("api") !== -1) {
-    docsPath = apiDocsPath
-    cmd = "apihelp"
-  }
 
-  fs.readdir(docsPath, function(er, files) {
-    if (er) {
-      log.error("helpSearch", "Could not load documentation")
+  var docPath = path.resolve(__dirname, "..", "doc")
+  return glob(docPath + "/*/*.md", function (er, files) {
+    if (er)
       return cb(er)
-    }
-
-    var search = args.join(" ")
-      , results = []
-    asyncMap(files, function (file, cb) {
-      fs.lstat(path.resolve(docsPath, file), function (er, st) {
-        if (er) return cb(er)
-        if (!st.isFile()) return cb(null, [])
-
-        fs.readFile(path.resolve(docsPath, file), "utf8", function (er, data) {
-          if (er) return cb(er)
-
-          var match = false
-          for (var a = 0, l = args.length; a < l && !match; a ++) {
-            match = data.toLowerCase().indexOf(args[a].toLowerCase()) !== -1
-          }
-          if (!match) return cb(null, [])
-
-          var lines = data.split(/\n+/)
-            , context = []
-
-          // if a line has a search term, then skip it and the next line.
-          // if the next line has a search term, then skip all 3
-          // otherwise, set the line to null.
-          for (var i = 0, l = lines.length; i < l; i ++) {
-            var line = lines[i]
-              , nextLine = lines[i + 1]
-              , match = false
-            if (nextLine) {
-              for (var a = 0, ll = args.length; a < ll && !match; a ++) {
-                match = nextLine.toLowerCase()
-                        .indexOf(args[a].toLowerCase()) !== -1
-              }
-              if (match) {
-                // skip over the next line, and the line after it.
-                i += 2
-                continue
-              }
-            }
-
-            match = false
-            for (var a = 0, ll = args.length; a < ll && !match; a ++) {
-              match = line.toLowerCase().indexOf(args[a].toLowerCase()) !== -1
-            }
-            if (match) {
-              // skip over the next line
-              i ++
-              continue
-            }
-
-            lines[i] = null
-          }
-
-          // now squish any string of nulls into a single null
-          lines = lines.reduce(function (l, r) {
-            if (!(r === null && l[l.length-1] === null)) l.push(r)
-            return l
-          }, [])
-
-          if (lines[lines.length - 1] === null) lines.pop()
-          if (lines[0] === null) lines.shift()
-
-          // now see how many args were found at all.
-          var found = {}
-            , totalHits = 0
-          lines.forEach(function (line) {
-            args.forEach(function (arg) {
-              var hit = (line || "").toLowerCase()
-                        .split(arg.toLowerCase()).length - 1
-              if (hit > 0) {
-                found[arg] = (found[arg] || 0) + hit
-                totalHits += hit
-              }
-            })
-          })
-
-          return cb(null, { file: file, lines: lines, found: Object.keys(found)
-                          , hits: found, totalHits: totalHits })
-        })
+    readFiles(files, function (er, data) {
+      if (er)
+        return cb(er)
+      searchFiles(args, data, function (er, results) {
+        if (er)
+          return cb(er)
+        formatResults(args, results, cb)
       })
-    }, function (er, results) {
-      if (er) return cb(er)
+    })
+  })
+}
 
-      // if only one result, then just show that help section.
-      if (results.length === 1) {
-        return npm.commands.help([results[0].file.replace(/\.md$/, "")], cb)
+function readFiles (files, cb) {
+  var res = {}
+  asyncMap(files, function (file, cb) {
+    fs.readFile(file, 'utf8', function (er, data) {
+      res[file] = data
+      return cb(er)
+    })
+  }, function (er) {
+    return cb(er, res)
+  })
+}
+
+function searchFiles (args, files, cb) {
+  var results = []
+  Object.keys(files).forEach(function (file) {
+    var data = files[file]
+
+    // skip if no matches at all
+    for (var a = 0, l = args.length; a < l && !match; a++) {
+      var match = data.toLowerCase().indexOf(args[a].toLowerCase()) !== -1
+    }
+    if (!match)
+      return
+
+    var lines = data.split(/\n+/)
+    var context = []
+
+    // if a line has a search term, then skip it and the next line.
+    // if the next line has a search term, then skip all 3
+    // otherwise, set the line to null.  then remove the nulls.
+    for (var i = 0, l = lines.length; i < l; i ++) {
+      var line = lines[i]
+        , nextLine = lines[i + 1]
+        , match = false
+      if (nextLine) {
+        for (var a = 0, ll = args.length; a < ll && !match; a ++) {
+          match = nextLine.toLowerCase()
+                  .indexOf(args[a].toLowerCase()) !== -1
+        }
+        if (match) {
+          // skip over the next line, and the line after it.
+          i += 2
+          continue
+        }
       }
 
-      if (results.length === 0) {
-        console.log("No results for " + args.map(JSON.stringify).join(" "))
-        return cb()
+      match = false
+      for (var a = 0, ll = args.length; a < ll && !match; a ++) {
+        match = line.toLowerCase().indexOf(args[a].toLowerCase()) !== -1
+      }
+      if (match) {
+        // skip over the next line
+        i ++
+        continue
       }
 
-      // sort results by number of results found, then by number of hits
-      // then by number of matching lines
-      results = results.sort(function (a, b) {
-        return a.found.length > b.found.length ? -1
-             : a.found.length < b.found.length ? 1
-             : a.totalHits > b.totalHits ? -1
-             : a.totalHits < b.totalHits ? 1
-             : a.lines.length > b.lines.length ? -1
-             : a.lines.length < b.lines.length ? 1
-             : 0
+      lines[i] = null
+    }
+
+    // now squish any string of nulls into a single null
+    lines = lines.reduce(function (l, r) {
+      if (!(r === null && l[l.length-1] === null)) l.push(r)
+      return l
+    }, [])
+
+    if (lines[lines.length - 1] === null) lines.pop()
+    if (lines[0] === null) lines.shift()
+
+    // now see how many args were found at all.
+    var found = {}
+      , totalHits = 0
+    lines.forEach(function (line) {
+      args.forEach(function (arg) {
+        var hit = (line || "").toLowerCase()
+                  .split(arg.toLowerCase()).length - 1
+        if (hit > 0) {
+          found[arg] = (found[arg] || 0) + hit
+          totalHits += hit
+        }
       })
+    })
 
-      var out = results.map(function (res, i, results) {
-        var out = "npm " + cmd + " "+res.file.replace(/\.md$/, "")
-          , r = Object.keys(res.hits).map(function (k) {
-              return k + ":" + res.hits[k]
-            }).sort(function (a, b) {
-              return a > b ? 1 : -1
-            }).join(" ")
-
-        out += ((new Array(Math.max(1, 81 - out.length - r.length)))
-                 .join (" ")) + r
-
-        if (!npm.config.get("long")) return out
-
-        var out = "\n\n" + out
-             + "\n" + (new Array(81)).join("—") + "\n"
-             + res.lines.map(function (line, i) {
-          if (line === null || i > 3) return ""
-          for (var out = line, a = 0, l = args.length; a < l; a ++) {
-            var finder = out.toLowerCase().split(args[a].toLowerCase())
-              , newOut = []
-              , p = 0
-            finder.forEach(function (f) {
-              newOut.push( out.substr(p, f.length)
-                         , "\1"
-                         , out.substr(p + f.length, args[a].length)
-                         , "\2" )
-              p += f.length + args[a].length
-            })
-            out = newOut.join("")
-          }
-          if (npm.color) {
-            var color = "\033[31;40m"
-              , reset = "\033[0m"
-          } else {
-            var color = ""
-              , reset = ""
-          }
-          out = out.split("\1").join(color)
-                   .split("\2").join(reset)
-          return out
-        }).join("\n").trim()
-        return out
-      }).join("\n")
-
-      if (results.length && !npm.config.get("long")) {
-        out = "Top hits for "+(args.map(JSON.stringify).join(" "))
-            + "\n" + (new Array(81)).join("—") + "\n"
-            + out
-            + "\n" + (new Array(81)).join("—") + "\n"
-            + "(run with -l or --long to see more context)"
-      }
+    var cmd = "npm help "
+    if (path.basename(path.dirname(file)) === "api") {
+      cmd = "npm apihelp "
+    }
+    cmd += path.basename(file, ".md").replace(/^npm-/, "")
+    results.push({ file: file
+                 , cmd: cmd
+                 , lines: lines
+                 , found: Object.keys(found)
+                 , hits: found
+                 , totalHits: totalHits
+                 })
+  })
 
-      console.log(out.trim())
-      cb(null, results)
-    })
+  // if only one result, then just show that help section.
+  if (results.length === 1) {
+    return npm.commands.help([results[0].file.replace(/\.md$/, "")], cb)
+  }
+
+  if (results.length === 0) {
+    console.log("No results for " + args.map(JSON.stringify).join(" "))
+    return cb()
+  }
 
+  // sort results by number of results found, then by number of hits
+  // then by number of matching lines
+  results = results.sort(function (a, b) {
+    return a.found.length > b.found.length ? -1
+         : a.found.length < b.found.length ? 1
+         : a.totalHits > b.totalHits ? -1
+         : a.totalHits < b.totalHits ? 1
+         : a.lines.length > b.lines.length ? -1
+         : a.lines.length < b.lines.length ? 1
+         : 0
   })
+
+  cb(null, results)
+}
+
+function formatResults (args, results, cb) {
+  var cols = Math.min(process.stdout.columns || Infinity, 80) + 1
+
+  var out = results.map(function (res, i, results) {
+    var out = res.cmd
+      , r = Object.keys(res.hits).map(function (k) {
+          return k + ":" + res.hits[k]
+        }).sort(function (a, b) {
+          return a > b ? 1 : -1
+        }).join(" ")
+
+    out += ((new Array(Math.max(1, cols - out.length - r.length)))
+             .join (" ")) + r
+
+    if (!npm.config.get("long")) return out
+
+    var out = "\n\n" + out
+         + "\n" + (new Array(cols)).join("—") + "\n"
+         + res.lines.map(function (line, i) {
+      if (line === null || i > 3) return ""
+      for (var out = line, a = 0, l = args.length; a < l; a ++) {
+        var finder = out.toLowerCase().split(args[a].toLowerCase())
+          , newOut = []
+          , p = 0
+        finder.forEach(function (f) {
+          newOut.push( out.substr(p, f.length)
+                     , "\1"
+                     , out.substr(p + f.length, args[a].length)
+                     , "\2" )
+          p += f.length + args[a].length
+        })
+        out = newOut.join("")
+      }
+      if (npm.color) {
+        var color = "\033[31;40m"
+          , reset = "\033[0m"
+      } else {
+        var color = ""
+          , reset = ""
+      }
+      out = out.split("\1").join(color)
+               .split("\2").join(reset)
+      return out
+    }).join("\n").trim()
+    return out
+  }).join("\n")
+
+  if (results.length && !npm.config.get("long")) {
+    out = "Top hits for "+(args.map(JSON.stringify).join(" "))
+        + "\n" + (new Array(cols)).join("—") + "\n"
+        + out
+        + "\n" + (new Array(cols)).join("—") + "\n"
+        + "(run with -l or --long to see more context)"
+  }
+
+  console.log(out.trim())
+  cb(null, results)
 }
diff --git a/lib/help.js b/lib/help.js
index 8faef1c2c..f522763db 100644
--- a/lib/help.js
+++ b/lib/help.js
@@ -3,9 +3,7 @@ module.exports = help
 
 help.completion = function (opts, cb) {
   if (opts.conf.argv.remain.length > 2) return cb(null, [])
-  var num = 1
-  if (-1 !== opts.conf.argv.remain[1].indexOf("api")) num = 3
-  getSections(num, cb)
+  getSections(cb)
 }
 
 var fs = require("graceful-fs")
@@ -14,94 +12,165 @@ var fs = require("graceful-fs")
   , npm = require("./npm.js")
   , log = require("npmlog")
   , opener = require("opener")
+  , glob = require("glob")
 
 function help (args, cb) {
-  var num = 1
-    , argv = npm.config.get("argv").cooked
-  if (argv.length && -1 !== argv[0].indexOf("api")) {
-    num = 3
+  var argv = npm.config.get("argv").cooked
+
+  var argnum = 0
+  if (args.length === 2 && ~~args[0]) {
+    argnum = ~~args.shift()
   }
 
+  // npm help foo bar baz: search topics
   if (args.length > 1 && args[0]) {
     return npm.commands["help-search"](args, num, cb)
   }
 
   var section = npm.deref(args[0]) || args[0]
 
-  if (section) {
-    if ( npm.config.get("usage")
-      && npm.commands[section]
-      && npm.commands[section].usage
-    ) {
-      npm.config.set("loglevel", "silent")
-      log.level = "silent"
-      console.log(npm.commands[section].usage)
-      return cb()
-    }
-
-    var sectionPath = path.join( __dirname, "..", "man", "man" + num
-                               , section + "." + num)
-      , htmlPath = path.resolve( __dirname, "..", "html"
-                               , num === 3 ? "api" : "doc"
-                               , section+".html" )
-    return fs.stat
-      ( sectionPath
-      , function (e, o) {
-          if (e) return npm.commands["help-search"](args, cb)
-
-          var manpath = path.join(__dirname, "..", "man")
-            , env = {}
-          Object.keys(process.env).forEach(function (i) {
-            env[i] = process.env[i]
-          })
-          env.MANPATH = manpath
-          var viewer = npm.config.get("viewer")
-
-          switch (viewer) {
-            case "woman":
-              var a = ["-e", "(woman-find-file \"" + sectionPath + "\")"]
-              var conf = { env: env, customFds: [ 0, 1, 2] }
-              var woman = spawn("emacsclient", a, conf)
-              woman.on("close", cb)
-              break
-
-            case "browser":
-              opener(htmlPath, { command: npm.config.get("browser") }, cb)
-              break
-
-            default:
-              var conf = { env: env, customFds: [ 0, 1, 2] }
-              var man = spawn("man", [num, section], conf)
-              man.on("close", cb)
-          }
-        }
-      )
-  } else getSections(function (er, sections) {
-    if (er) return cb(er)
+  // npm help <noargs>:  show basic usage
+  if (!section)
+    return npmUsage(cb)
+
+  // npm <cmd> -h: show command usage
+  if ( npm.config.get("usage")
+    && npm.commands[section]
+    && npm.commands[section].usage
+  ) {
     npm.config.set("loglevel", "silent")
     log.level = "silent"
-    console.log
-      ( ["\nUsage: npm <command>"
-        , ""
-        , "where <command> is one of:"
-        , npm.config.get("long") ? usages()
-          : "    " + wrap(Object.keys(npm.commands))
-        , ""
-        , "npm <cmd> -h     quick help on <cmd>"
-        , "npm -l           display full usage info"
-        , "npm faq          commonly asked questions"
-        , "npm help <term>  search for help on <term>"
-        , "npm help npm     involved overview"
-        , ""
-        , "Specify configs in the ini-formatted file:"
-        , "    " + npm.config.get("userconfig")
-        , "or on the command line via: npm <command> --key value"
-        , "Config info can be viewed via: npm help config"
-        , ""
-        , "npm@" + npm.version + " " + path.dirname(__dirname)
-        ].join("\n"))
-    cb(er)
+    console.log(npm.commands[section].usage)
+    return cb()
+  }
+
+  // npm apihelp <section>: Prefer section 3 over section 1
+  var apihelp = argv.length && -1 !== argv[0].indexOf("api")
+  var pref = apihelp ? [3, 1, 5, 7] : [1, 3, 5, 7]
+  if (argnum)
+    pref = [ argnum ].concat(pref.filter(function (n) {
+      return n !== argnum
+    }))
+
+  // npm help <section>: Try to find the path
+  var manroot = path.resolve(__dirname, "..", "man")
+  var htmlroot = path.resolve(__dirname, "..", "html", "doc")
+
+  // legacy
+  if (section === "global")
+    section = "folders"
+  else if (section === "json")
+    section = "package.json"
+
+  // find either /section.n or /npm-section.n
+  var f = "+(npm-" + section + "|" + section + ").[0-9]"
+  return glob(manroot + "/*/" + f, function (er, mans) {
+    if (er)
+      return cb(er)
+
+    if (!mans.length)
+      return npm.commands["help-search"](args, cb)
+
+    viewMan(pickMan(mans, pref), cb)
+  })
+}
+
+function pickMan (mans, pref_) {
+  var nre = /([0-9]+)$/
+  var pref = {}
+  pref_.forEach(function (sect, i) {
+    pref[sect] = i
+  })
+  mans = mans.sort(function (a, b) {
+    var an = a.match(nre)[1]
+    var bn = b.match(nre)[1]
+    return an === bn ? (a > b ? -1 : 1)
+         : pref[an] < pref[bn] ? -1
+         : 1
+  })
+  return mans[0]
+}
+
+function viewMan (man, cb) {
+  var nre = /([0-9]+)$/
+  var num = man.match(nre)[1]
+  var section = path.basename(man, "." + num)
+
+  // at this point, we know that the specified man page exists
+  var manpath = path.join(__dirname, "..", "man")
+    , env = {}
+  Object.keys(process.env).forEach(function (i) {
+    env[i] = process.env[i]
   })
+  env.MANPATH = manpath
+  var viewer = npm.config.get("viewer")
+
+  switch (viewer) {
+    case "woman":
+      var a = ["-e", "(woman-find-file \"" + man + "\")"]
+      var conf = { env: env, customFds: [ 0, 1, 2] }
+      var woman = spawn("emacsclient", a, conf)
+      woman.on("close", cb)
+      break
+
+    case "browser":
+      opener(htmlMan(man), { command: npm.config.get("browser") }, cb)
+      break
+
+    default:
+      var conf = { env: env, customFds: [ 0, 1, 2] }
+      var man = spawn("man", [num, section], conf)
+      man.on("close", cb)
+      break
+  }
+}
+
+function htmlMan (man) {
+  var sect = +man.match(/([0-9]+)$/)[1]
+  var f = path.basename(man).replace(/([0-9]+)$/, "html")
+  switch (sect) {
+    case 1:
+      sect = "cli"
+      break
+    case 3:
+      sect = "api"
+      break
+    case 5:
+      sect = "files"
+      break
+    case 7:
+      sect = "misc"
+      break
+    default:
+      throw new Error("invalid man section: " + sect)
+  }
+  return path.resolve(__dirname, "..", "html", "doc", sect, f)
+}
+
+function npmUsage (cb) {
+  npm.config.set("loglevel", "silent")
+  log.level = "silent"
+  console.log
+    ( ["\nUsage: npm <command>"
+      , ""
+      , "where <command> is one of:"
+      , npm.config.get("long") ? usages()
+        : "    " + wrap(Object.keys(npm.commands))
+      , ""
+      , "npm <cmd> -h     quick help on <cmd>"
+      , "npm -l           display full usage info"
+      , "npm faq          commonly asked questions"
+      , "npm help <term>  search for help on <term>"
+      , "npm help npm     involved overview"
+      , ""
+      , "Specify configs in the ini-formatted file:"
+      , "    " + npm.config.get("userconfig")
+      , "or on the command line via: npm <command> --key value"
+      , "Config info can be viewed via: npm help config"
+      , ""
+      , "npm@" + npm.version + " " + path.dirname(__dirname)
+      ].join("\n"))
+  cb()
 }
 
 function usages () {
@@ -127,9 +196,17 @@ function usages () {
 function wrap (arr) {
   var out = ['']
     , l = 0
+    , line
+
+  line = process.stdout.columns
+  if (!line)
+    line = 60
+  else
+    line = Math.min(60, Math.max(line - 16, 24))
+
   arr.sort(function (a,b) { return a<b?-1:1 })
     .forEach(function (c) {
-      if (out[l].length + c.length + 2 < 60) {
+      if (out[l].length + c.length + 2 < line) {
         out[l] += ', '+c
       } else {
         out[l++] += ','
@@ -139,16 +216,16 @@ function wrap (arr) {
   return out.join("\n    ").substr(2)
 }
 
-function getSections (num, cb) {
-  if (typeof cb !== "function") cb = num, num = 1
-
-  var mp = path.join(__dirname, "../man/man" + num + "/")
-    , cleaner = new RegExp("\\." + num + "$")
-  fs.readdir(mp, function (er, files) {
-    if (er) return cb(er)
-    var sectionList = files.concat("help." + num)
-      .filter(function (s) { return s.match(cleaner) })
-      .map(function (s) { return s.replace(cleaner, "")})
-    cb(null, sectionList)
+function getSections (cb) {
+  var g = path.resolve(__dirname, "../man/man[0-9]/*.[0-9]")
+  glob(g, function (er, files) {
+    if (er)
+      return cb(er)
+    cb(null, Object.keys(files.reduce(function (acc, file) {
+      file = path.basename(file).replace(/\.[0-9]+$/, "")
+      file = file.replace(/^npm-/, "")
+      acc[file] = true
+      return acc
+    }, { help: true })))
   })
 }
diff --git a/scripts/doc-build.sh b/scripts/doc-build.sh
index 750c48d00..4ca97322e 100755
--- a/scripts/doc-build.sh
+++ b/scripts/doc-build.sh
@@ -41,11 +41,12 @@ version=$(node cli.js -v)
 mkdir -p $(dirname $dest)
 
 case $dest in
-  *.[13])
+  *.[1357])
     ./node_modules/.bin/ronn --roff $src \
     | sed "s|@VERSION@|$version|g" \
-    | perl -pi -e 's/npm\\-([^\(]*)\(1\)/npm help \1/g' \
-    | perl -pi -e 's/npm\\-([^\(]*)\(3\)/npm apihelp \1/g' \
+    | perl -pi -e 's/(npm\\-)?([^\(]*)\(1\)/npm help \2/g' \
+    | perl -pi -e 's/(npm\\-)?([^\(]*)\([57]\)/npm help \3 \2/g' \
+    | perl -pi -e 's/(npm\\-)?([^\(]*)\(3\)/npm apihelp \2/g' \
     | perl -pi -e 's/npm\(1\)/npm help npm/g' \
     | perl -pi -e 's/npm\(3\)/npm apihelp npm/g' \
     > $dest
@@ -53,21 +54,27 @@ case $dest in
     ;;
   *.html)
     (cat html/dochead.html && \
-     ./node_modules/.bin/ronn -f $src && \
-     cat html/docfoot.html )\
+     ./node_modules/.bin/ronn -f $src &&
+     cat html/docfoot.html)\
     | sed "s|@NAME@|$name|g" \
     | sed "s|@DATE@|$date|g" \
     | sed "s|@VERSION@|$version|g" \
-    | perl -pi -e 's/<h1>npm(-?[^\(]*\([0-9]\)) -- (.*?)<\/h1>/<h1>npm\1<\/h1> <p>\2<\/p>/g' \
+    | perl -pi -e 's/<h1>([^\(]*\([0-9]\)) -- (.*?)<\/h1>/<h1>\1<\/h1> <p>\2<\/p>/g' \
     | perl -pi -e 's/npm-npm/npm/g' \
-    | perl -pi -e 's/([^"-])(npm-)?README(\(1\))?/\1<a href="..\/doc\/README.html">README<\/a>/g' \
-    | perl -pi -e 's/<title><a href="..\/doc\/README.html">README<\/a><\/title>/<title>README<\/title>/g' \
-    | perl -pi -e 's/([^"-])npm-([^\(]+)(\(1\))/\1<a href="..\/doc\/\2.html">\2\3<\/a>/g' \
-    | perl -pi -e 's/([^"-])npm-([^\(]+)(\(3\))/\1<a href="..\/api\/\2.html">\2\3<\/a>/g' \
-    | perl -pi -e 's/([^"-])npm\(1\)/\1<a href="..\/doc\/npm.html">npm(1)<\/a>/g' \
-    | perl -pi -e 's/([^"-])npm\(3\)/\1<a href="..\/api\/npm.html">npm(3)<\/a>/g' \
-    | perl -pi -e 's/\([13]\)<\/a><\/h1>/<\/a><\/h1>/g' \
-    > $dest
+    | perl -pi -e 's/([^"-])(npm-)?README(\(1\))?/\1<a href="..\/..\/doc\/README.html">README<\/a>/g' \
+    | perl -pi -e 's/<title><a href="[^"]+README.html">README<\/a><\/title>/<title>README<\/title>/g' \
+    | perl -pi -e 's/([^"-])([^\(> ]+)(\(1\))/\1<a href="..\/cli\/\2.html">\2\3<\/a>/g' \
+    | perl -pi -e 's/([^"-])([^\(> ]+)(\(3\))/\1<a href="..\/api\/\2.html">\2\3<\/a>/g' \
+    | perl -pi -e 's/([^"-])([^\(> ]+)(\(5\))/\1<a href="..\/files\/\2.html">\2\3<\/a>/g' \
+    | perl -pi -e 's/([^"-])([^\(> ]+)(\(7\))/\1<a href="..\/misc\/\2.html">\2\3<\/a>/g' \
+    | perl -pi -e 's/\([1357]\)<\/a><\/h1>/<\/a><\/h1>/g' \
+    | (if [ $(basename $(dirname $dest)) == "doc" ]; then
+        perl -pi -e 's/ href="\.\.\// href="/g'
+      else
+        cat
+      fi) \
+    > $dest \
+    && cat html/docfoot-script.html >> $dest
     exit $?
     ;;
   *)
diff --git a/scripts/index-build.js b/scripts/index-build.js
index 551bb1d56..8031fe727 100755
--- a/scripts/index-build.js
+++ b/scripts/index-build.js
@@ -1,63 +1,62 @@
 #!/usr/bin/env node
 var fs = require("fs")
   , path = require("path")
-  , cli = path.resolve(__dirname, "..", "doc", "cli")
-  , clidocs = null
-  , api = path.resolve(__dirname, "..", "doc", "api")
-  , apidocs = null
-  , readme = path.resolve(__dirname, "..", "README.md")
-
-fs.readdir(cli, done("cli"))
-fs.readdir(api, done("api"))
-
-function done (which) { return function (er, docs) {
-  if (er) throw er
-  docs.sort()
-  if (which === "api") apidocs = docs
-  else clidocs = docs
-
-  if (apidocs && clidocs) next()
-}}
-
-function filter (d) {
-  return d !== "index.md"
-       && d.charAt(0) !== "."
-       && d.match(/\.md$/)
-}
-
-function next () {
+  , root = path.resolve(__dirname, "..")
+  , glob = require("glob")
+  , conversion = { "cli": 1, "api": 3, "files": 5, "misc": 7 }
+
+glob(root + "/{README.md,doc/*/*.md}", function (er, files) {
+  if (er)
+    throw er
+  output(files.map(function (f) {
+    var b = path.basename(f)
+    if (b === "README.md")
+      return [0, b]
+    if (b === "index.md")
+      return null
+    var s = conversion[path.basename(path.dirname(f))]
+    return [s, f]
+  }).filter(function (f) {
+    return f
+  }).sort(function (a, b) {
+    return (a[0] === b[0])
+           ? ( path.basename(a[1]) === "npm.md" ? -1
+             : path.basename(b[1]) === "npm.md" ? 1
+             : a[1] > b[1] ? 1 : -1 )
+           : a[0] - b[0]
+  }))
+})
+
+return
+
+function output (files) {
   console.log(
-    "npm-index(1) -- Index of all npm documentation\n" +
+    "npm-index(7) -- Index of all npm documentation\n" +
     "==============================================\n")
 
-  apidocs = apidocs.filter(filter).map(function (d) {
-    return [3, path.resolve(api, d)]
-  })
-
-  clidocs = clidocs.filter(filter).map(function (d) {
-    return [1, path.resolve(cli, d)]
-  })
-
-  writeLine([1, readme])
-
-  console.log("# Command Line Documentation")
-
-  clidocs.forEach(writeLine)
+  writeLines(files, 0)
+  writeLines(files, 1, "Command Line Documentation")
+  writeLines(files, 3, "API Documentation")
+  writeLines(files, 5, "Files")
+  writeLines(files, 7, "Misc")
+}
 
-  console.log("# API Documentation")
-  apidocs.forEach(writeLine)
+function writeLines (files, sxn, heading) {
+  if (heading)
+    console.log("# %s\n", heading)
+  files.filter(function (f) {
+    return f[0] === sxn
+  }).forEach(writeLine)
 }
 
+
 function writeLine (sd) {
-  var sxn = sd[0]
+  var sxn = sd[0] || 1
     , doc = sd[1]
     , d = path.basename(doc, ".md")
-    , s = fs.lstatSync(doc)
-
-  if (s.isSymbolicLink()) return
 
-  var content = fs.readFileSync(doc, "utf8").split("\n")[0].split("--")[1]
+  var content = fs.readFileSync(doc, "utf8").split("\n")[0].split("-- ")[1]
 
-  console.log("## npm-%s(%d)\n", d, sxn)
+  console.log("## %s(%d)\n", d, sxn)
   console.log(content + "\n")
 }