6 files changed, 48 insertions, 12 deletions
diff --git a/doc-src/index.html b/doc-src/index.html
index 4638b091..cb331ab9 100644
--- a/doc-src/index.html
+++ b/doc-src/index.html
@@ -11,9 +11,9 @@
         <li><a href="@!urlTo("anticache.html")!@">Anticache</a></li>
         <li><a href="@!urlTo("filters.html")!@">Filter expressions</a></li>
     </ul>
-    <li><a href="@!urlTo("scripts.html")!@">Scripting API</a></li>
+    <li><a href="@!urlTo("scripts.html")!@">Scripts</a></li>
         <ul>
-            <li><a href="@!urlTo("scripts/flows.html")!@">Introduction to flows</a></li>
+            <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>
diff --git a/doc-src/index.py b/doc-src/index.py
index 05254234..34704f7e 100644
--- a/doc-src/index.py
+++ b/doc-src/index.py
@@ -75,7 +75,7 @@ pages = [
     Page("sticky.html", "Sticky cookies and auth"),
     Page("anticache.html", "Anticache"),
     Page("filters.html", "Filter expressions"),
-    Page("scripts.html", "External scripts"),
+    Page("scripts.html", "Scripts"),
     Directory("scripts"),
     Page("ssl.html", "SSL interception"),
     Directory("certinstall"),
diff --git a/doc-src/scripts.html b/doc-src/scripts.html
index 2514923e..990ca070 100644
--- a/doc-src/scripts.html
+++ b/doc-src/scripts.html
@@ -1,14 +1,46 @@
 
-Both __mitmproxy__ and __mitmdump__ allow you to modify requests and responses
-with external scripts. This is often done through the __--reqscript__ and
-__--respscript__ options
+__mitmproxy__ has a powerful event-drive scripting API, that allows you to
+modify flows on-the-fly or rewrite previously saved flows locally. 
+
+
+## Events
+
+<table>
+    <tr>
+        <td>start(ctx)</td>
+        <td>Called once on startup, before any other events.</td>
+    </tr>
+    <tr>
+        <td>clientconnect(ctx, ClientConnect)</td>
+        <td>Called when a client initiates a connection to the proxy. Note that
+        a connection can correspond to multiple HTTP requests.</td>
+    </tr>
+    <tr>
+        <td>request(ctx, Flow)</td>
+        <td>Called when a client request has been received.</td>
+    </tr>
+    <tr>
+        <td>response(ctx, Flow)</td>
+        <td>Called when a server response has been received.</td>
+    </tr>
+    <tr>
+        <td>error(ctx, Flow)</td>
+        <td>Called when a flow error has occured, e.g. invalid server
+        responses, or interrupted connections. This is distinct from a valid
+        server HTTP error response, which is simply a response with an HTTP
+        error code. </td>
+    </tr>
+    <tr>
+        <td>clientdisconnect(ctx, ClientDisconnect)</td>
+        <td>Called when a client disconnects from the proxy.</td>
+    </tr>
+    <tr>
+        <td>done(ctx)</td>
+        <td>Called once on script shutdown, after any other events.</td>
+    </tr>
+</table>
 
 
-The script interface is simple - scripts simply read,
-modify and return a single __libmproxy.flow.Flow__ object, using the methods
-defined in the __libmproxy.script__ module. Scripts must be executable.
-
-!example("examples/simple_script")!$
 
 
 
diff --git a/doc-src/scripts/examples.html b/doc-src/scripts/examples.html
new file mode 100644
index 00000000..bfa1f8d7
--- /dev/null
+++ b/doc-src/scripts/examples.html
@@ -0,0 +1,4 @@
+
+## Stub script
+
+$!example("examples/stub.py")!$
diff --git a/doc-src/scripts/flows.html b/doc-src/scripts/flows.html
deleted file mode 100644
index e69de29b..00000000
--- a/doc-src/scripts/flows.html
+++ /dev/null
diff --git a/doc-src/scripts/index.py b/doc-src/scripts/index.py
index 805a17d9..987cf840 100644
--- a/doc-src/scripts/index.py
+++ b/doc-src/scripts/index.py
@@ -1,6 +1,6 @@
 from countershape import Page
 
 pages = [
-    Page("flows.html", "Introduction to flows"),
+    Page("examples.html", "Examples"),
     Page("api.html", "API"),
 ]