diff --git a/README.md b/README.md
index 9b6bfcb..427cc4d 100644
--- a/README.md
+++ b/README.md
@@ -2,29 +2,33 @@
[`npm-registry-fetch`](https://github.com/npm/npm-registry-fetch) is a Node.js
library that implements a `fetch`-like API for accessing npm registry APIs
-consistently.
+consistently. It's able to consume npm-style configuration values and has all
+the necessary logic for picking registries, handling scopes, and dealing with
+authentication details built-in.
-## Install
+## Example
-`$ npm install npm-registry-fetch`
+```javascript
+const npmFetch = require('npm-registry-fetch')
+
+console.log(
+ await npmFetch.json('/-/ping')
+)
+```
## Table of Contents
+* [Installing](#install)
* [Example](#example)
* [Contributing](#contributing)
* [API](#api)
* [`fetch`](#fetch)
* [`fetch.json`](#fetch-json)
+ * [`fetch` options](#fetch-opts)
-### Example
-
-```javascript
-const npmFetch = require('npm-registry-fetch')
+### Install
-console.log(
- await npmFetch.json('https://registry.npmjs.org/-/ping')
-)
-```
+`$ npm install npm-registry-fetch`
### Contributing
@@ -45,27 +49,497 @@ Happy hacking!
#### `> fetch(url, [opts]) -> Promise`
-Performs a request to a given registry URL.
+Performs a request to a given URL.
+
+The URL can be either a full URL, or a path to one. The appropriate registry
+will be automatically picked if only a URL path is given.
+
+For available options, please see the section on [`fetch` options](#fetch-opts).
##### Example
```javascript
-const fetch = require('npm-registry-fetch')
-const res = await fetch('https://registry.npmjs.org/-/ping')
+const res = await fetch('/-/ping')
console.log(res.headers)
res.on('data', d => console.log(d.toString('utf8')))
```
-#### `> fetch.json(url, [opts]) -> Promise`
+#### `> fetch.json(url, [opts]) -> Promise`
Performs a request to a given registry URL, parses the body of the response as
JSON, and returns it as its final value. This is a utility shorthand for
`fetch(url).then(res => res.json())`.
+For available options, please see the section on [`fetch` options](#fetch-opts).
+
##### Example
```javascript
-const fetch = require('npm-registry-fetch')
-const res = await fetch.json('https://registry.npmjs.org/-/ping')
-console.log(res)
+const res = await fetch.json('/-/ping')
+console.log(res) // Body parsed as JSON
```
+
+#### `fetch` Options
+
+Fetch options are optional, and can be passed in as either a Map-like object
+(one with a `.get()` method), a plain javascript object, or a
+[`figgy-pudding`](https://npm.im/figgy-pudding) instance.
+
+##### `opts._authToken`
+
+* Type: String
+* Default: null
+
+Authentication token string.
+
+Can be scoped to a registry by using a "nerf dart" for that registry. That is:
+
+```
+{
+ '//registry.npmjs.org/:_authToken': 't0k3nH34r'
+}
+```
+
+##### `opts.agent`
+
+* Type: http.Agent
+* Default: an appropriate agent based on URL protocol and proxy settings
+
+An [`Agent`](https://nodejs.org/api/http.html#http_class_http_agent) instance to
+be shared across requests. This allows multiple concurrent `fetch` requests to
+happen on the same socket.
+
+You do _not_ need to provide this option unless you want something particularly
+specialized, since proxy configurations and http/https agents are already
+automatically managed internally when this option is not passed through.
+
+##### `opts.body`
+
+* Type: Buffer | Stream | Object
+* Default: null
+
+Request body to send through the outgoing request. Buffers and Streams will be
+passed through as-is, with a default `content-type` of
+`application/octet-stream`. Plain JavaScript objects will be `JSON.stringify`ed
+and the `content-type` will default to `application/json`.
+
+Use [`opts.headers`](#opts-headers) to set the content-type to something else.
+
+##### `opts.ca`
+
+* Type: String, Array, or null
+* Default: null
+
+The Certificate Authority signing certificate that is trusted for SSL
+connections to the registry. Values should be in PEM format (Windows calls it
+"Base-64 encoded X.509 (.CER)") with newlines replaced by the string `'\n'`. For
+example:
+
+```
+{
+ ca: '-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----'
+}
+```
+
+Set to `null` to only allow "known" registrars, or to a specific CA cert
+to trust only that specific signing authority.
+
+Multiple CAs can be trusted by specifying an array of certificates instead of a
+single string.
+
+See also [`opts.strict-ssl`](#opts-strict-ssl), [`opts.ca`](#opts-ca) and
+[`opts.key`](#opts-key)
+
+##### `opts.cache`
+
+* Type: path
+* Default: null
+
+The location of the http cache directory. If provided, certain cachable requests
+will be cached according to [IETF RFC 7234](https://tools.ietf.org/html/rfc7234)
+rules. This will speed up future requests, as well as make the cached data
+available offline if necessary/requested.
+
+See also [`offline`](#opts-offline), [`prefer-offline`](#opts-prefer-offline),
+and [`prefer-online`](#opts-prefer-online).
+
+##### `opts.cert`
+
+* Type: String
+* Default: null
+
+A client certificate to pass when accessing the registry. Values should be in
+PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines
+replaced by the string `'\n'`. For example:
+
+```
+{
+ cert: '-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----'
+}
+```
+
+It is _not_ the path to a certificate file (and there is no "certfile" option).
+
+See also: [`opts.ca`](#opts-ca) and [`opts.key`](#opts-key)
+
+##### `opts.fetch-retries`
+
+* Type: Number
+* Default: 2
+
+The "retries" config for [`retry`](https://npm.im/retry) to use when fetching
+packages from the registry.
+
+See also [`opts.retry`](#opts-retry) to provide all retry options as a single
+object.
+
+##### `opts.fetch-retry-factor`
+
+* Type: Number
+* Default: 10
+
+The "factor" config for [`retry`](https://npm.im/retry) to use when fetching
+packages.
+
+See also [`opts.retry`](#opts-retry) to provide all retry options as a single
+object.
+
+##### `opts.fetch-retry-mintimeout`
+
+* Type: Number
+* Default: 10000 (10 seconds)
+
+The "minTimeout" config for [`retry`](https://npm.im/retry) to use when fetching
+packages.
+
+See also [`opts.retry`](#opts-retry) to provide all retry options as a single
+object.
+
+##### `opts.fetch-retry-maxtimeout`
+
+* Type: Number
+* Default: 60000 (1 minute)
+
+The "maxTimeout" config for [`retry`](https://npm.im/retry) to use when fetching
+packages.
+
+See also [`opts.retry`](#opts-retry) to provide all retry options as a single
+object.
+
+##### `opts.headers`
+
+* Type: Object
+* Default: null
+
+Additional headers for the outgoing request. This option can also be used to
+override headers automatically generated by `npm-registry-fetch`, such as
+`Content-Type`.
+
+##### `opts.integrity`
+
+* Type: String | [SRI object](https://npm.im/ssri)
+* Default: null
+
+If provided, the response body's will be verified against this integrity string,
+using [`ssri`](https://npm.im/ssri). If verification succeeds, the response will
+complete as normal. If verification fails, the response body will error with an
+`EINTEGRITY` error.
+
+Body integrity is only verified if the body is actually consumed to completion --
+that is, if you use `res.json()`/`res.buffer()`, or if you consume the default
+`res` stream data to its end.
+
+Cached data will have its integrity automatically verified using the
+previously-generated integrity hash for the saved request information, so
+`EINTEGRITY` errors can happen if [`opts.cache`](#opts-cache) is used, even if
+`opts.integrity` is not passed in.
+
+##### `opts.is-from-ci`
+
+* Alias: `opts.isFromCI`
+* Type: Boolean
+* Default: Based on environment variables
+
+This is used to populate the `npm-in-ci` request header sent to the registry.
+
+##### `opts.key`
+
+* Type: String
+* Default: null
+
+A client key to pass when accessing the registry. Values should be in PEM
+format with newlines replaced by the string `'\n'`. For example:
+
+```
+{
+ key: '-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----'
+}
+```
+
+It is _not_ the path to a key file (and there is no "keyfile" option).
+
+See also: [`opts.ca`](#opts-ca) and [`opts.cert`](#opts-cert)
+
+##### `opts.local-address`
+
+* Type: IP Address String
+* Default: null
+
+The IP address of the local interface to use when making connections
+to the registry.
+
+See also [`opts.proxy`](#opts-proxy)
+
+##### `opts.log`
+
+* Type: [`npmlog`](https://npm.im/npmlog)-like
+* Default: null
+
+Logger object to use for logging operation details. Must have the same methods
+as `npmlog`.
+
+##### `opts.maxsockets`
+
+* Alias: `opts.max-sockets`
+* Type: Integer
+* Default: 12
+
+Maximum number of sockets to keep open during requests. Has no effect if
+[`opts.agent`](#opts-agent) is used.
+
+##### `opts.method`
+
+* Type: String
+* Default: 'GET'
+
+HTTP method to use for the outgoing request. Case-insensitive.
+
+##### `opts.noproxy`
+
+* Type: Boolean
+* Default: process.env.NOPROXY
+
+If true, proxying will be disabled even if [`opts.proxy`](#opts-proxy) is used.
+
+##### `opts.npm-session`
+
+* Alias: `opts.npmSession`
+* Type: String
+* Default: null
+
+If provided, will be sent in the `npm-session` header. This header is used by
+the npm registry to identify individual user sessions (usually individual
+invocations of the CLI).
+
+##### `opts.offline`
+
+* Type: Boolean
+* Default: false
+
+Force offline mode: no network requests will be done during install. To allow
+`npm-registry-fetch` to fill in missing cache data, see
+[`opts.prefer-offline`](#opts-prefer-offline).
+
+This option is only really useful if you're also using
+[`opts.cache`](#opts-cache).
+
+##### `opts.otp`
+
+* Type: Number | String
+* Default: null
+
+This is a one-time password from a two-factor authenticator. It is required for
+certain registry interactions when two-factor auth is enabled for a user
+account.
+
+##### `opts.password`
+
+* Alias: _password
+* Type: String
+* Default: null
+
+Password used for basic authentication. For the more modern authentication
+method, please use the (more secure) [`opts._authToken`](#opts-auth-token)
+
+Can optionally be scoped to a registry by using a "nerf dart" for that registry.
+That is:
+
+```
+{
+ '//registry.npmjs.org/:password': 't0k3nH34r'
+}
+```
+
+See also [`opts.username`](#opts-username)
+
+##### `opts.prefer-offline`
+
+* Type: Boolean
+* Default: false
+
+If true, staleness checks for cached data will be bypassed, but missing data
+will be requested from the server. To force full offline mode, use
+[`opts.offline`](#opts-offline).
+
+This option is generally only useful if you're also using
+[`opts.cache`](#opts-cache).
+
+##### `opts.prefer-online`
+
+* Type: Boolean
+* Default: false
+
+If true, staleness checks for cached data will be forced, making the CLI look
+for updates immediately even for fresh package data.
+
+This option is generally only useful if you're also using
+[`opts.cache`](#opts-cache).
+
+
+##### `opts.project-scope`
+
+* Alias: `opts.projectScope`
+* Type: String
+* Default: null
+
+If provided, will be sent in the `npm-scope` header. This header is used by the
+npm registry to identify the toplevel package scope that a particular project
+installation is using.
+
+##### `opts.proxy`
+
+* Type: url
+* Default: null
+
+A proxy to use for outgoing http requests. If not passed in, the `HTTP(S)_PROXY`
+environment variable will be used.
+
+##### `opts.query`
+
+* Type: String | Object
+* Default: null
+
+If provided, the request URI will have a query string appended to it using this
+query. If `opts.query` is an object, it will be converted to a query string
+using
+[`querystring.stringify()`](https://nodejs.org/api/querystring.html#querystring_querystring_stringify_obj_sep_eq_options).
+
+If the request URI already has a query string, it will be merged with
+`opts.query`, preferring `opts.query` values.
+
+##### `opts.refer`
+
+* Alias: `opts.referer`
+* Type: String
+* Default: null
+
+Value to use for the `Referer` header. The npm CLI itself uses this to serialize
+the npm command line using the given request.
+
+##### `opts.registry`
+
+* Type: URL
+* Default: `'https://registry.npmjs.org'`
+
+Registry configuration for a request. If a request URL only includes the URL
+path, this registry setting will be prepended. This configuration is also used
+to determine authentication details, so even if the request URL references a
+completely different host, `opts.registry` will be used to find the auth details
+for that request.
+
+See also [`opts.scope`](#opts-scope), [`opts.spec`](#opts-spec), and
+[`opts.:registry`](#opts-scope-registry) which can all affect the actual
+registry URL used by the outgoing request.
+
+##### `opts.retry`
+
+* Type: Object
+* Default: null
+
+Single-object configuration for request retry settings. If passed in, will
+override individually-passed `fetch-retry-*` settings.
+
+##### `opts.scope`
+
+* Type: String
+* Default: null
+
+Associate an operation with a scope for a scoped registry. This option can force
+lookup of scope-specific registries and authentication.
+
+See also [`opts.:registry`](#opts-scope-registry) and
+[`opts.spec`](#opts-spec) for interactions with this option.
+
+##### `opts.:registry`
+
+* Type: String
+* Default: null
+
+This option type can be used to configure the registry used for requests
+involving a particular scope. For example, `opts['@myscope:registry'] =
+'https://scope-specific.registry/'` will make it so requests go out to this
+registry instead of [`opts.registry`](#opts-registry) when
+[`opts.scope`](#opts-scope) is used, or when [`opts.spec`](#opts-spec) is a
+scoped package spec.
+
+The `@` before the scope name is optional, but recommended.
+
+##### `opts.spec`
+
+* Type: String | [`npm-registry-arg`](https://npm.im/npm-registry-arg) object.
+* Default: null
+
+If provided, can be used to automatically configure [`opts.scope`](#opts-scope)
+based on a specific package name. Non-registry package specs will throw an
+error.
+
+##### `opts.strict-ssl`
+
+* Type: Boolean
+* Default: true
+
+Whether or not to do SSL key validation when making requests to the
+registry via https.
+
+See also [`opts.ca`](#opts-ca).
+
+##### `opts.timeout`
+
+* Type: Milliseconds
+* Default: 30000 (30 seconds)
+
+Time before a hanging request times out.
+
+##### `opts.user-agent`
+
+* Type: String
+* Default: `'npm-registry-fetch@/node@+ ()'`
+
+User agent string to send in the `User-Agent` header.
+
+##### `opts.username`
+
+* Type: String
+* Default: null
+
+Username used for basic authentication. For the more modern authentication
+method, please use the (more secure) [`opts._authToken`](#opts-auth-token)
+
+Can optionally be scoped to a registry by using a "nerf dart" for that registry.
+That is:
+
+```
+{
+ '//registry.npmjs.org/:username': 't0k3nH34r'
+}
+```
+
+See also [`opts.password`](#opts-password)
+
+##### `opts._auth`
+
+* Type: String
+* Default: null
+
+** DEPRECATED ** This is a legacy authentication token supported only for
+*compatibility. Please us [`opts._authToken`](#opts-auth-token) instead.