diff --git a/README.md b/README.md
index a305056..5b2ccef 100644
--- a/README.md
+++ b/README.md
@@ -3,17 +3,88 @@
 
 A photo bucket management suite.
 
+## `admin`
+
+Create new buckets. Standalone tool.
+
 ## `control`
 
 Implement access controls by signing or proxying requests.
 
+### Operations
+
+#### `GET /list?bucket=BUCKET&auth=TOKEN`
+
+1. Consult the bucket for metadata.json
+2. Get read access method for the bucket
+3. Validate the token against the access method
+4. Return ListObjectsV2 for prefix `photo/`
+   - Can also 307 redirect to the bucket read URL, if is public readable
+
+#### `GET /read?bucket=BUCKET&auth=TOKEN&object=OBJECTNAME`
+
+1. Consult the bucket for metadata.json
+2. Get read access method for the bucket
+3. Validate the token against the access method
+4. Validate that OBJECTNAME starts with `photo/`
+5. If necessary, presign an object URL for 4 days
+   - Cache presigned URLs for 2 days in memory/Redis
+6. 307 redirect to presigned URL
+
+#### `PUT /write?bucket=BUCKET&auth=TOKEN&object=OBJECTNAME`
+
+1. Consult the bucket for metadata.json
+2. Get write access method for the bucket
+3. Validate the token against the access method
+4. Validate that OBJECTNAME starts with `photo/`
+5. If necessary, presign an object URL for 1 day
+6. 307 redirect to presigned URL
+
+### Authentication
+
+#### Token
+
+The read/write token is checked against a simple string defined in the bucket.
+
+#### OpenID Connect
+
+Recommended IDP: [dex](https://github.com/dexidp/dex)
+
+The read/write operation is gated by a signed key corresponding to allowed 
+users defined in the bucket.
+
 ## `web`
 
-Generates web interfaces from photo buckets.
+Generates the web interface for a photo bucket. Also updates the shared asset bucket on start.
+
+### Operations
+
+#### `POST /webhook`
+#### `POST /update?bucket=BUCKET`
+
+Regenerate and upload `index.html` and `manage/index.html` to bucket.
+
+## `indexer`
+
+Pointed to by a reverse proxy to handle the following paths on all buckets:
+
+- `/`
+- `/manage/`
+
+#### `GET /*`
+
+A proxy for all buckets, treats the URL as a directory and serves up directory + `index.html`.
 
 ## `thumbnails`
 
-Generate thumbnails from photo buckets.
+Generate thumbnails from photo buckets. Registers webhooks.
+
+### Operations
+
+#### `POST /webhook`
+#### `POST /update?bucket=BUCKET&object=OBJECT`
+
+1. Perform thumbnail generation using libvips in a pool queue. 
+2. Block until done
 
 <!-- vim: set conceallevel=2 et ts=2 sw=2: -->
-
diff --git a/main.go b/main.go
new file mode 100644
index 0000000..1fdaac2
--- /dev/null
+++ b/main.go
@@ -0,0 +1 @@
+package photos // import "git.makerforce.io/photos/photos"