From 804583d7a9c428eb2aefd908c6eaa52d057a1989 Mon Sep 17 00:00:00 2001
From: Graham Barber <green.cheese8030@fastmail.com>
Date: Tue, 11 Nov 2025 22:46:14 +0000
Subject: [PATCH] docs: add package READMEs

---
 packages/consumer/README.md | 57 +++++++++++++++++++++++++++++++++----
 packages/crypto/README.md   | 11 +++++++
 packages/lexicon/README.md  | 10 +++++++
 packages/producer/README.md | 34 ++++++++++++++++++++++
 packages/shared/README.md   |  6 ++++
 5 files changed, 113 insertions(+), 5 deletions(-)
 create mode 100644 packages/crypto/README.md
 create mode 100644 packages/lexicon/README.md
 create mode 100644 packages/producer/README.md
 create mode 100644 packages/shared/README.md

diff --git a/packages/consumer/README.md b/packages/consumer/README.md
index c41d62b..3cff732 100644
--- a/packages/consumer/README.md
+++ b/packages/consumer/README.md
@@ -1,7 +1,54 @@
-# `@cistern/consumer`
+# @cistern/consumer
 
-The Consumer module is responsible for the following:
+Consumer client for retrieving, decrypting, and deleting Cistern items.
 
-- Generating key pairs
-- Retrieving and decrypting items
-- Subscribing to Jetstream to monitor for items
+## Usage
+
+### Generate Keypair
+
+```typescript
+import { createConsumer, serializeKey } from "@cistern/consumer";
+
+const consumer = await createConsumer({
+  handle: "user.bsky.social",
+  appPassword: "xxxx-xxxx-xxxx-xxxx",
+});
+
+const keypair = await consumer.generateKeyPair();
+
+console.log(`Public key URI: ${keypair.publicKey}`);
+console.log(`Private key: ${serializeKey(keypair.privateKey)}`);
+```
+
+### Use Existing Keypair
+
+```typescript
+import { createConsumer } from "@cistern/consumer";
+
+const consumer = await createConsumer({
+  handle: "user.bsky.social",
+  appPassword: "xxxx-xxxx-xxxx-xxxx",
+  keypair: {
+    publicKey: "at://did:plc:abc123/app.cistern.lexicon.pubkey/3jzfcijpj2z",
+    privateKey: "base64-encoded-private-key",
+  },
+});
+```
+
+### List Items (Polling)
+
+```typescript
+for await (const item of consumer.listItems()) {
+  console.log(`[${item.tid}] ${item.text}`);
+  await consumer.deleteItem(item.tid);
+}
+```
+
+### Subscribe to Items (Real-time)
+
+```typescript
+for await (const item of consumer.subscribeToItems()) {
+  console.log(`[${item.tid}] ${item.text}`);
+  await consumer.deleteItem(item.tid);
+}
+```
diff --git a/packages/crypto/README.md b/packages/crypto/README.md
new file mode 100644
index 0000000..e3711a2
--- /dev/null
+++ b/packages/crypto/README.md
@@ -0,0 +1,11 @@
+# @cistern/crypto
+
+Post-quantum cryptographic primitives for Cistern.
+
+## Algorithm
+
+**`x_wing-xchacha20_poly1305-sha3_512`**
+
+- **X-Wing KEM**: Post-quantum hybrid key encapsulation (ML-KEM-768 + X25519)
+- **XChaCha20-Poly1305**: Authenticated encryption
+- **SHA3-512**: Content integrity verification
diff --git a/packages/lexicon/README.md b/packages/lexicon/README.md
new file mode 100644
index 0000000..560bb33
--- /dev/null
+++ b/packages/lexicon/README.md
@@ -0,0 +1,10 @@
+# @cistern/lexicon
+
+AT Protocol lexicon definitions and TypeScript types for Cistern records.
+
+## Record Types
+
+| Collection | Description |
+|------------|-------------|
+| `app.cistern.lexicon.pubkey` | Public key records with human-readable names, referenced by items via AT-URI |
+| `app.cistern.lexicon.item` | Encrypted item records containing ciphertext, nonce, algorithm metadata, and public key reference |
diff --git a/packages/producer/README.md b/packages/producer/README.md
new file mode 100644
index 0000000..feb5e01
--- /dev/null
+++ b/packages/producer/README.md
@@ -0,0 +1,34 @@
+# @cistern/producer
+
+Producer client for creating and encrypting Cistern items.
+
+## Usage
+
+```typescript
+import { createProducer } from "@cistern/producer";
+
+const producer = await createProducer({
+  handle: "user.bsky.social",
+  appPassword: "xxxx-xxxx-xxxx-xxxx",
+});
+
+for await (const pubkey of producer.listPublicKeys()) {
+  console.log(`${pubkey.name}: ${pubkey.uri}`);
+}
+
+producer.selectPublicKey(pubkey);
+
+const itemUri = await producer.createItem("Hello, world!");
+```
+
+Or, if you already have a public key record ID:
+
+```typescript
+const producer = await createProducer({
+  handle: "user.bsky.social",
+  appPassword: "xxxx-xxxx-xxxx-xxxx",
+  publicKey: "3jzfcijpj2z",
+});
+
+const itemUri = await producer.createItem("Hello, world!");
+```
diff --git a/packages/shared/README.md b/packages/shared/README.md
new file mode 100644
index 0000000..179da8e
--- /dev/null
+++ b/packages/shared/README.md
@@ -0,0 +1,6 @@
+# @cistern/shared
+
+Shared authentication utilities for Cistern producer and consumer packages.
+
+Provides DID resolution via Slingshot and authenticated RPC client creation for
+AT Protocol operations.
-- 
2.51.2