diff --git a/README.md b/README.md
index 8dadb5c..9e4a71d 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,42 @@
 # Cistern
 
-Cistern is an attempt at implementing a private, personal quick-capture system
-on AT Protocol. Cistern "items" are encrypted, so that they are only readable by
-the holder of the correct secret key—stored off-protocol. These items are
-intended to be ephemeral, and to be deleted after they've been read.
-
-The intention is for Cistern to bridge the gap between where ideas are had and
-where they can be stored long-term. For example, let's say you have an idea
-while at a restaurant. You create an item using your phone, and once you're back
-at your desk and you open Obsidian, that item is automatically pulled from your
-PDS, decrypted, and deleted from your PDS. If your notebook was open at the time
-you created your item, the Cistern Obsidian plugin would have been notified of
-the new item via the Jetstream, and so you would find your memo waiting for you
-once you got home.
+Cistern is a private, end-to-end encrypted quick-capture system built on AT Protocol. Items are encrypted using post-quantum cryptography and stored temporarily in your Personal Data Server (PDS), then automatically retrieved and deleted after consumption.
+
+The system bridges the gap between where ideas are captured and where they are stored long-term. Create an encrypted item on your phone, and it automatically appears in your desktop application, decrypted and ready to use.
+
+## Architecture
+
+Cistern is a Deno monorepo consisting of five packages:
+
+### `@cistern/crypto`
+Core cryptographic operations using post-quantum algorithms. Implements X-Wing key encapsulation with XChaCha20-Poly1305 authenticated encryption and SHA3-512 integrity verification. Handles keypair generation, encryption, and decryption.
+
+### `@cistern/lexicon`
+AT Protocol schema definitions for Cistern record types. Defines `app.cistern.lexicon.pubkey` (public key records) and `app.cistern.lexicon.item` (encrypted item records). Includes code generation from JSON schemas.
+
+### `@cistern/shared`
+Common utilities and authentication logic. Handles DID resolution via Slingshot service and creates authenticated RPC clients using app passwords.
+
+### `@cistern/producer`
+Creates and encrypts items for storage. Manages public key selection, encrypts plaintext content, and uploads encrypted items to the PDS as AT Protocol records.
+
+### `@cistern/consumer`
+Retrieves, decrypts, and deletes items. Generates keypairs, manages private keys locally, retrieves items via polling or real-time streaming (Jetstream), and handles item deletion after consumption.
+
+## Security Model
+
+Private keys never leave the consumer device. Public keys are stored in the PDS as records, while private keys remain off-protocol. Only the holder of the matching private key can decrypt items encrypted with the corresponding public key.
+
+## Testing
+
+Run all unit tests:
+```bash
+deno test --allow-env
+```
+
+Run end-to-end tests (requires AT Protocol credentials):
+```bash
+CISTERN_HANDLE="your.bsky.social" \
+CISTERN_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
+deno test --allow-env --allow-net e2e.test.ts
+```