diff --git a/doc-src/02-docstyle.css b/doc-src/02-docstyle.css
index b3d55e1a..4eb0c101 100644
--- a/doc-src/02-docstyle.css
+++ b/doc-src/02-docstyle.css
@@ -31,31 +31,29 @@ a {
     color: #444444;
 }
 
-#bd h1, #bd h2 {
+#bd h1, #bd h2, #bd h3 {
     font-family: "Georgia","Times New Roman",Helvetica,Arial,sans-serif;
     font-weight: normal;
+    color: #181818;
 }
 
 #bd h1 {
-    font-size: 1.8em;
+    font-size: 1.9em;
     border-bottom: 2px solid #ff7033;
     margin-top: 5px;
     margin-bottom: 5px;
-    color: #181818;
 }
 
 #bd h2 {
-    font-size: 1.3em;
+    font-size: 1.4em;
     border-bottom: 1px solid #cccccc;
     margin-top: 5px;
     margin-bottom: 5px;
-    color: #181818;
 }
 
 
 #bd h3 {
     margin-bottom: 0px;
-
 }
 
 #bd p {
@@ -125,19 +123,13 @@ li a {
     font-size: 14px;
 }
 .example_legend{
-    float: right;
     line-height: 1;
-    margin-left: 20px;
     font-size: 12px;
 }
 .example pre {
     margin: 0;
-
 }
 
-
-
-
 .kvtable th {
     text-align: left;
     white-space: nowrap;
diff --git a/doc-src/index.html b/doc-src/index.html
index cb331ab9..ae776b15 100644
--- a/doc-src/index.html
+++ b/doc-src/index.html
@@ -14,7 +14,6 @@
     <li><a href="@!urlTo("scripts.html")!@">Scripts</a></li>
         <ul>
             <li><a href="@!urlTo("scripts/examples.html")!@">Examples</a></li>
-            <li><a href="@!urlTo("scripts/api.html")!@">API</a></li>
         </ul>
     <li><a href="@!urlTo("ssl.html")!@">SSL interception</a></li>
         <ul>
diff --git a/doc-src/mitmdump.html b/doc-src/mitmdump.html
index 1ca5a020..4dc0a519 100644
--- a/doc-src/mitmdump.html
+++ b/doc-src/mitmdump.html
@@ -9,7 +9,7 @@ documentation.
 ## Example: saving traffic
 
 <pre class="terminal">
-mitmdump -w outfile
+> mitmdump -w outfile
 </pre>
 
 Start up mitmdump in proxy mode, and write all traffic to __outfile__. 
@@ -18,7 +18,7 @@ Start up mitmdump in proxy mode, and write all traffic to __outfile__.
 ## Example: client replay
 
 <pre class="terminal">
-mitmdump -nc outfile
+> mitmdump -nc outfile
 </pre>
 
 Start mitmdump without binding to the proxy port (_-n_), then replay all
@@ -27,7 +27,7 @@ you can replay requests from one file, and write the resulting flows to
 another:
 
 <pre class="terminal">
-mitmdump -nc srcfile -w dstfile
+> mitmdump -nc srcfile -w dstfile
 </pre>
 
 See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information.
@@ -36,7 +36,7 @@ See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more in
 ## Example: running a script
 
 <pre class="terminal">
-mitmdump -s examples/add_header.py
+> mitmdump -s examples/add_header.py
 </pre>
 
 This runs the __add_header.py__ example script, which simply adds a new header
@@ -46,7 +46,7 @@ to all responses.
 ## Example: scripted data transformation
 
 <pre class="terminal">
-mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+> mitmdump -ns examples/add_header.py -r srcfile -w dstfile
 </pre>
 
 This command loads flows from __srcfile__, transforms it according to the
diff --git a/doc-src/scripts.html b/doc-src/scripts.html
index af140901..f3df489d 100644
--- a/doc-src/scripts.html
+++ b/doc-src/scripts.html
@@ -57,15 +57,65 @@ Called when a client disconnects from the proxy.
 Called once on script shutdown, after any other events.
 
 
-## Scripts on saved flows
+## API
 
-There are a few circumstances in which a script may run on Flows that are
-already complete. For example, you could start a script, and then load a saved
-set of flows from a file (see the scripted data transformation example on the
-[mitmdump](@!urlTo("mitmdump.html")!@) page). This also happens when you run a
+The main classes you will deal with in writing mitmproxy scripts are:
+
+<table class="kvtable">
+    <tr>
+        <th>libmproxy.flow.ScriptContext</th>
+        <td>A handle for interacting with mitmproxy's global state.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Flow</th>
+        <td>A collection of objects representing a single HTTP transaction.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Request</th>
+        <td>An HTTP request.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Response</th>
+        <td>An HTTP response.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Error</th>
+        <td>A communications error.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.ClientConnection</th>
+        <td>Describes a client connection.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.ClientDisconnection</th>
+        <td>Describes a client disconnection.</td>
+    </tr>
+    <tr>
+        <th>libmproxy.flow.Headers</th>
+        <td>HTTP headers for a request or response.</td>
+    </tr>
+</table>
+
+
+The canonical API documentation is the code. You can view the API documentation
+using pydoc (which is installed with Python by default), like this:
+
+<pre class="terminal">
+> pydoc libmproxy.flow.Request
+</pre>
+
+
+## Running scripts on saved flows
+
+Sometimes, we want to run a script on __Flow__ objects that are already
+complete.  This happens when you start a script, and then load a saved set of
+flows from a file (see the "scripted data transformation" example on the
+[mitmdump](@!urlTo("mitmdump.html")!@) page). It also happens when you run a
 one-shot script on a single flow through the _|_ (pipe) shortcut in mitmproxy.
 
 In this case, there are no client connections, and the events are run in the
 following order: __start__, __request__, __response__, __error__, __done__.  If
 the flow doesn't have a __response__ or __error__ associated with it, the
-matching event will be skipped.
+matching event will be skipped. 
+
+
diff --git a/doc-src/scripts/api.html b/doc-src/scripts/api.html
deleted file mode 100644
index e69de29b..00000000
diff --git a/doc-src/scripts/index.py b/doc-src/scripts/index.py
index 987cf840..a520fdff 100644
--- a/doc-src/scripts/index.py
+++ b/doc-src/scripts/index.py
@@ -2,5 +2,4 @@ from countershape import Page
 
 pages = [
     Page("examples.html", "Examples"),
-    Page("api.html", "API"),
 ]
diff --git a/examples/README b/examples/README
new file mode 100644
index 00000000..edb70c51
--- /dev/null
+++ b/examples/README
@@ -0,0 +1,5 @@
+
+add_header.py   Simple script that just adds a header to every request.
+stub.py         Script stub with a method definition for every event. 
+stickycookies   An example of writing a custom proxy with libmproxy
+