README: Reorganization and new "Using programmatically" section

CONTRIBUTING.md

@@ -1,6 +1,16 @@
-# How to become a contributor and submit your own code
+# For Contributors
 
-## Contributor License Agreements
+We'd love your help! This doc covers how to become a contributor and submit code to the project.
+
+## Follow the coding style
+
+The `.eslintrc` defines all. We use [JSDoc](http://usejsdoc.org/) along with [closure annotations](https://developers.google.com/closure/compiler/docs/js-for-compiler). Annotations encouraged for all contributions.
+
+## Learn about the architecture
+
+See [Lighthouse Architecture](./docs/architecture.md), our overview and tour of the codebase.
+
+## Sign the Contributor License Agreement
 
 We'd love to accept your sample apps and patches! Before we can take them, we have to jump a couple of legal hurdles.
 
@@ -12,7 +22,7 @@ Please fill out either the individual or corporate Contributor License Agreement
 Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to
 accept your pull requests.
 
-## Contributing A Patch
+## Contributing a patch
 
 1. Submit an issue describing your proposed change to the repo in question.
 1. The repo owner will respond to your issue promptly.
@@ -21,6 +31,21 @@ accept your pull requests.
 1. Ensure that your code adheres to the existing style in the sample to which you are contributing.
 1. Submit a pull request.
 
+# For Maintainers
+
+## Updating traceviewer source
+
+```sh
+cd lighthouse-core
+# if not already there, clone catapult and copy license over
+git clone --depth=1 https://github.com/catapult-project/catapult.git third_party/src/catapult
+cp third_party/src/catapult/LICENSE third_party/traceviewer-js/
+# pull for latest
+git -C "./third_party/src/catapult/" pull
+# run our conversion script
+node scripts/build-traceviewer-module.js
+```
+
 ## Release guide
 
 ```sh

docs/architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+_Some incomplete notes_
+
+## Components
+
+* **Driver** - Interfaces with [Chrome Debugging Protocol](https://developer.chrome.com/devtools/docs/debugger-protocol)  ([API viewer](https://chromedevtools.github.io/debugger-protocol-viewer/))
+* **Gatherers** - Requesting data from the browser (and maybe post-processing)
+* **Artifacts** - The output of gatherers
+* **Audits** - Non-performance evaluations of capabilities and issues. Includes a raw value and score of that value.
+* **Metrics** - Performance metrics summarizing the UX
+* **Aggregations** - Pulling audit results, grouping into user-facing components (eg. `install_to_homescreen`) and applying weighting and overall scoring.
+
+### Internal module graph
+
+![graph of lighthouse-core module dependencies](https://cloud.githubusercontent.com/assets/39191/19367685/04d4336a-9151-11e6-9ebb-3b87bdb09a4c.png)
+
+`npm install -g js-vd; vd --exclude "node_modules|third_party|fs|path|url|log" lighthouse-core/ > graph.html`
+
+## Protocol
+
+* _Interacting with Chrome:_ The Chrome protocol connection maintained via [WebSocket](https://github.com/websockets/ws) for the CLI [`chrome.debuggger` API](https://developer.chrome.com/extensions/debugger) when in the Chrome extension.
+* _Event binding & domains_: Some domains must be `enable()`d so they issue events. Once enabled, they flush any events that represent state. As such, network events will only issue after the domain is enabled. All the protocol agents resolve their `Domain.enable()` callback _after_ they have flushed any pending events. See example:
+
+```js
+// will NOT work
+driver.sendCommand('Security.enable').then(_ => {
+  driver.on('Security.securityStateChanged', state => { /* ... */ });
+})
+
+// WILL work! happy happy. :)
+driver.on('Security.securityStateChanged', state => { /* ... */ }); // event binding is synchronous
+driver.sendCommand('Security.enable');
+```
+
+* _Debugging the protocol_: Read [Better debugging of the Protocol](https://github.com/GoogleChrome/lighthouse/issues/184).
+
+## Gatherers
+
+* _Reading the DOM:_ We prefer reading the DOM right from the browser (See #77). The driver exposes a `querySelector` method that can be used along with a `getAttribute` method to read values.
+
+## Audits
+
+The return value of each audit takes this shape:
+
+```js
+Promise.resolve({
+  name: 'audit-name',
+  description: 'whatnot',
+  // value: The score. Typically a boolean, but can be number 0-100
+  value: 0,
+  // rawValue: Could be anything, as long as it can easily be stringified and displayed,
+  //   e.g. 'your score is bad because you wrote ${rawValue}'
+  rawValue: {},
+  // debugString: Some *specific* error string for helping the user figure out why they failed here.
+  //   The reporter can handle *general* feedback on how to fix, e.g. links to the docs
+  debugString: 'Your manifest 404ed',
+});
+```

API-and-internals.md → docs/headless-chrome.md

@@ -1,6 +1,4 @@
-# Lighthouse objects & options
-
-## Running headless Chrome for Lighthouse
+# Running headless Chrome for Lighthouse
 
 The headless_shell still has a few bugs to work out. Until then, Chrome + xvfb is a stable solution.
 These steps mostly worked on Debian Jessie. Also, worth a look: both `.travis.yml` and `launch-chrome.sh`.