Documentation for 1.0

doc/adduser.md

@@ -10,34 +10,20 @@ npm-adduser(1) -- Add a registry user account
 Create or verify a user named `<username>` in the npm registry, and
 save the credentials to the `.npmrc` file.
 
-The username, password, and email are read in from prompts.  This command
-cannot be scripted.  If you think you need to script the creation of new
-users, or the authorization of existing ones, without human intervention,
-please rethink your use case.  That's a very bad idea.
+The username, password, and email are read in from prompts.
 
 You may use this command to change your email address, but not username
 or password.
 
+To reset your password, go to <http://admin.npmjs.org/>
+
 You may use this command multiple times with the same user account to
 authorize on a new machine.
 
 ## CONFIGURATION
 
-### _auth
-
-A base-64 encoded "user:pass" pair.  This is created by npm-adduser(1).
-
-If your config file is ever corrupted, you can set this manually by doing:
-
-    npm adduser
-
 ### registry
 
-Default: https://registry.npmjs.org/
+Default: http://registry.npmjs.org/
 
 The base URL of the npm package registry.
-
-### username, _password
-
-Once the configuration is parsed, the `_auth` config is split into
-`username` and `_password`.  This is the part before the ":"

doc/author.md

@@ -0,0 +1 @@
+owner.md

doc/build.md

@@ -10,15 +10,9 @@ npm-build(1) -- Build a package
 
 ## DESCRIPTION
 
-This command should almost never need to be run directly.  It is an abstraction
-of the functionality shared by both npm-install(1) and npm-link(1).
-
-This command creates the various interwoven links that ensure a package's contents
-are available in the root appropriately, and that its dependencies are linked
-appropriately.
-
-## CONFIGURATION
+This is the plumbing command called by `npm link` and `npm install`.
 
+It should generally not be called directly.
 
 ## SEE ALSO
 

doc/cache.md

@@ -10,48 +10,51 @@ npm-cache(1) -- install a package
 
     npm cache ls [<path>]
 
-    npm cache clean [<name>[@<version>]]
+    npm cache clean [<path>]
 
 ## DESCRIPTION
 
 * add:
-  Access the local cache of package data.  This command is primarily
+  Add the specified package to the local cache.  This command is primarily
   intended to be used internally by npm, but it can provide a way to
   add data to the local installation cache explicitly.
 
-  If two arguments are provided, then npm will fetch the data from the
-  registry.  This allows npm to use the filesystem as a local proxy to
-  the registry.
-
 * ls:
-  Show the data in the cache.  Additional arguments are joined together
-  in a path-like fashion, but something like `npm cache ls npm/0.1.5` is
-  acceptable as well.
+  Show the data in the cache.  Argument is a path to show in the cache
+  folder.  Works a bit like the `find` program, but limited by the
+  `depth` config.
 
 * clean:
-  Delete data out of the cache for a specific package and version, all
-  versions of a package, or all data for all packages, depending on the
-  arguments supplied.
-
-  This can be used if invalid data gets into the cache.
+  Delete data out of the cache folder.  If an argument is provided, then
+  it specifies a subpath to delete.  If no argument is provided, then
+  the entire cache is cleared.
 
 ## DETAILS
 
-npm stores data for a version of a package in
-`$ROOT/.npm/.cache/<name>/<version>`.  Three pieces of data are stored
-in this folder:
+npm stores cache data in `$HOME/.npm`.  For each package that is added
+to the cache, three pieces of information are stored in
+`{cache}/{name}/{version}`:
 
-* package/:
+* .../package/:
   A folder containing the package contents as they appear in the tarball.
-* package.json:
+* .../package.json:
   The package.json file, as npm sees it, with overlays applied and a _id attribute.
-* package.tgz:
+* .../package.tgz:
   The tarball for that version.
 
+Additionally, whenever a registry request is made, a `.cache.json` file
+is placed at the corresponding URI, to store the ETag and the requested
+data.
+
+Commands that make non-essential registry requests (such as `search` and
+`view`, or the completion scripts) generally specify a minimum timeout.
+If the `.cache.json` file is younger than the specified timeout, then
+they do not make an HTTP request to the registry.
+
 ## CONFIGURATION
 
-### root
+### cache
 
-Default: `$INSTALL_PREFIX/lib/node`
+Default: `$HOME/.npm` on Posix, or `$HOME/npm-cache` on Windows.
 
-The root folder where packages are installed and npm keeps its data.
+The root cache folder.