README.md in ftw-0.0.4 vs README.md in ftw-0.0.5

@@ -1,48 +1,67 @@
 # For The Web
 
-net/http is pretty much not good. dns behavior in ruby changes quite frequently.
+## Getting Started
 
-Above all else, I want a consistent API and behavior that I can rely on. Ruby stdlib is not that thing.
+For doing client stuff (http requests, etc), you'll want {FTW::Agent}.
 
-I want:
+For doing server stuff (http serving, etc), you'll want {FTW::Server}. (not implemented yet)
 
+## Overview
+
+net/http is pretty much not good. Additionally, DNS behavior in ruby changes quite frequently.
+
+I primarily want two things in both client and server operations:
+
+* A consistent API with good documentation and tests
+* Modern web features: websockets, spdy, etc.
+
+Desired features:
+
 * A HTTP client that acts as a full user agent, not just a single connections. (With connection reuse)
 * HTTP and SPDY support.
 * WebSockets support.
 * SSL/TLS support.
 * An API that lets me do what I need.
 * Server and Client modes.
 * Support for both normal operation and EventMachine would be nice.
 
-## TODO
+For reference:
 
-* Tests, yo.
-* Logging, yo. With cabin, obviously.
-* [DNS in Ruby stdlib is broken](https://github.com/jordansissel/experiments/tree/master/ruby/dns-resolving-bug), I need to write my own
+* [DNS in Ruby stdlib is broken](https://github.com/jordansissel/experiments/tree/master/ruby/dns-resolving-bug), so I need to provide my own DNS api.
 
-## API Scratch
+## Agent API
 
 ### Common case
 
     agent = FTW::Agent.new
+
     request = agent.get("http://www.google.com/")
     response = request.execute
+    puts response.body.read
 
     # Simpler
-    response = agent.get!("http://www.google.com/")
+    response = agent.get!("http://www.google.com/").read
+    puts response.body.read
 
 ### SPDY
 
-    # SPDY should automatically be attempted. The caller should be unaware.
+SPDY should automatically be attempted. The caller should be unaware.
 
+I do not plan on exposing any direct means for invoking SPDY.
+
 ### WebSockets
 
     # 'http(s)' or 'ws(s)' urls are valid here. They will mean the same thing.
-    request = agent.websocket("http://somehost/endpoint")
-    # Set auth header
-    request["Authorization"] = ...
-    request["Cookie"] = ...
+    websocket = agent.websocket!("http://somehost/endpoint")
 
-    websocket, error = request.execute
-    # Now websocket.read receives a message, websocket.write sends a message.
+    websocket.publish("Hello world")
+    websocket.each do |message|
+      puts :received => message
+    end
 
+## Server API
+
+TBD. Will likely surround 'rack' somehow.
+
+It's possible the 'cramp' gem supports all the server-side features we need
+(except for SPDY, I suppose, which I might be able to contribute upstream)