ashlr-plugin 1.36.4

package/docs/session-log-schema.md

@@ -0,0 +1,68 @@
+# Session log schema
+
+The ashlr session log is a JSONL file at `~/.ashlr/session-log.jsonl`. One
+JSON object per line, one line per tool invocation, append-only, size-
+capped at 10 MB with a cascading backup (`.jsonl.1` → `.jsonl.2`). The
+format is designed to be stable across agents (Codex, Claude Code, Cursor,
+Goose and any future consumer) so downstream tooling can parse it without
+special-casing per-agent quirks.
+
+## Line format
+
+Each line is a single JSON object with the following fields:
+
+```json
+{
+  "ts": "2026-04-18T22:14:03.127Z",
+  "agent": "codex-cli",
+  "event": "tool_call",
+  "tool": "ashlr__read",
+  "cwd": "/Users/me/code/project",
+  "session": "sess_abc123",
+  "input_size": 240,
+  "output_size": 8210
+}
+```
+
+| Field          | Type    | Notes |
+|----------------|---------|-------|
+| `ts`           | string  | ISO 8601 UTC timestamp with millisecond precision |
+| `agent`        | string  | Agent name, such as `"codex-cli"`, `"claude-code"`, `"cursor"`, `"goose"`, or `"generic"` |
+| `event`        | string  | One of `tool_call`, `tool_fallback`, `tool_error`, `tool_escalate` |
+| `tool`         | string  | MCP tool name (e.g. `ashlr__read`), or `"unknown"` when the hook can't parse it |
+| `cwd`          | string  | Absolute path of the agent's working directory at the time of the call |
+| `session`      | string  | Host session ID when available, or a hashed PPID fallback starting with `h` |
+| `input_size`   | number  | Byte size of the tool's input payload (JSON-stringified when not already bytes) |
+| `output_size`  | number  | Byte size of the tool's output payload |
+
+### Event vocabulary
+
+- `tool_call` — the default. Tool ran to completion.
+- `tool_fallback` — tool took the fallback path (e.g. genome empty, fell through to raw ripgrep; summarizer unavailable, fell through to head+tail bytes).
+- `tool_error` — tool threw or returned non-zero.
+- `tool_escalate` — tool returned a bypassSummary-style hint that the caller should retry with more context.
+
+Consumers that don't know an `event` value should treat it as `tool_call`.
+
+## Rotation
+
+- Active file: `~/.ashlr/session-log.jsonl`.
+- Once the active file crosses 10 MB, the next write:
+  1. Renames `.jsonl.1` → `.jsonl.2` if a prior rotation exists (cascade keeps one generation of backup).
+  2. Renames the active file → `.jsonl.1`.
+  3. Starts a fresh active file.
+- Maximum on-disk footprint is therefore ~20 MB (active ≤ 10 MB + one 10 MB backup). `.jsonl.2` is overwritten on the next rotation.
+
+## Reading the log
+
+- `bun run scripts/session-log-report.ts` produces a human-readable report covering the active file + any rotated backups.
+- `/ashlr-usage` wraps that report as a Claude Code skill.
+- `ashlr-plugin stats --json` (new in v1.11.0) prints the stats ledger at `~/.ashlr/stats.json` as JSON on stdout — the session log is the raw feed, stats.json is the aggregated view.
+
+## Schema stability
+
+This is schema version **1**. Breaking changes add a `schema_version` field at the top of the file (not per-line) and bump the number. Non-breaking additions (new `event` values, new optional fields) don't change the version. Consumers should tolerate unknown fields silently.
+
+## Disabling
+
+Set `ASHLR_SESSION_LOG=0` at shell startup to suppress the log entirely. The tools still work; they just don't record.

package/docs/social.md

@@ -0,0 +1,95 @@
+# Social copy — current ashlr positioning
+
+---
+
+## Twitter (3 variants, 280 char each)
+
+**Variant A — lead with the number**
+```
+−57% token savings on real codebases, measured and reproducible.
+
+ashlr is an open-source Codex and Claude Code plugin: 40 MCP tools that replace native Read/Grep/Edit/Bash workflows with compressed alternatives.
+
+curl -fsSL https://plugin.ashlr.ai/install.sh | bash
+
+Full post: [LINK]
+```
+(253 chars)
+
+**Variant B — lead with the cost angle**
+```
+Codex and Claude Code token bills add up. ashlr cuts them by 57% on average — open source, MIT, no account.
+
+40 MCP tools. Measured benchmark. Install in 30 seconds.
+
+curl -fsSL https://plugin.ashlr.ai/install.sh | bash
+
+[LINK]
+```
+(214 chars)
+
+**Variant C — lead with the specific example**
+```
+Reading a 10,846-byte file in Claude Code costs 2,709 tokens natively.
+ashlr__read returns the same file for 406 tokens. That's an 85% drop.
+
+40 tools. Reproducible benchmark. MIT free.
+
+plugin.ashlr.ai
+```
+(208 chars)
+
+---
+
+## LinkedIn (~1,200 chars)
+
+```
+I shipped the Codex-native ashlr release today — an open-source token-efficiency layer for Codex and Claude Code.
+
+The background: Claude Code's native Read, Grep, and Edit tools transmit full file contents and full match output to the model on every call. On a real codebase this adds up fast. A single grep for a common pattern can cost 85,000 tokens of output the model skims and discards. A 15KB file opened to change three lines sends all 15KB.
+
+ashlr replaces those tools with compressed alternatives. ashlr__read returns a head+tail snip. ashlr__grep routes through a genome-aware retrieval index. ashlr__edit returns a diff summary instead of echoing the before+after.
+
+The numbers from the reproducible multi-repo benchmark:
+
+- TypeScript (`vercel/ai`): −62%
+- Python (`pandas`): −65%
+- Rust (`tokio`): −44%
+- Cross-language mean: −57%
+
+The plugin is MIT-licensed. The free tier ships 40 MCP tools, 34 Claude Code slash commands, Codex workflow skills, per-session token accounting, and a reproducible benchmark against your own codebase. No account required; telemetry is off by default. Pro adds cloud genome sync and a hosted LLM summarizer for developers who don't want to run Ollama locally.
+
+Install: curl -fsSL https://plugin.ashlr.ai/install.sh | bash
+
+Full write-up with methodology and the three bugs that surprised me: [LINK]
+```
+
+---
+
+## Hacker News
+
+**Title:**
+```
+Ashlr – open-source Codex and Claude Code plugin, −57% token savings measured on real codebases
+```
+
+**First comment (from the author):**
+
+```
+Author here.
+
+The motivation is straightforward: Claude Code's native Read/Grep/Edit tools ship full payloads — entire file contents, complete grep output — into model context on every call. On a codebase of any real size this wastes a meaningful fraction of every context window.
+
+ashlr replaces those three tools with MCP server alternatives that return compressed views: head+tail snip for reads, truncated/genome-aware retrieval for grep, diff summary for edit. The model gets enough context to do the work; the rest doesn't go over the wire.
+
+The −57% number is from a reproducible benchmark in scripts/run-benchmark.ts across TypeScript, Python, and Rust reference repos. The full methodology is in docs/benchmarks.md and docs/benchmarks-v2.json. The benchmark is honest about cases where ashlr is worse than native — small edits are guarded in real use because the diff-summary overhead can exceed the edit payload. Medium and large edits compress substantially.
+
+A few things worth noting for HN:
+
+- The free tier is complete. 40 MCP tools, 34 Claude Code slash commands, Codex workflow skills, MIT license, no account required, telemetry off by default, no feature gates. Pro adds hosted infrastructure (cloud genome sync, hosted LLM summarizer). Nothing in free degrades to push upgrades.
+- Codex packaging is in `.codex-plugin/` and `.mcp.json`; Cursor and Goose ports are in `ports/`. MCP tools run under any compatible host. Claude-only extras remain status line, slash commands, auto redirects, and OAuth bootstrap.
+- Two tests are skipped: a no-genome grep flake that's an environment-leak in the full parallel suite (passes in isolation) and a benchmark ratio assertion with the same root cause. Both documented in-line.
+- The $-interpolation bug in v0.9.2 is worth reading about if you do any string replace work: JavaScript's String.replace(string, string) interprets $& and $` in the replacement. It corrupted multi-edits silently for a while.
+
+Happy to answer questions about the genome format, the stats accounting architecture, or the benchmark methodology.
+```

package/docs/team-genome.md

@@ -0,0 +1,528 @@
+# Team Genome: Sharing a Genome Across a Development Team
+
+A single `.ashlrcode/genome/` directory can be committed to your repository and
+shared by every developer on the team. This guide explains how it works, when to
+use it, and how to keep it healthy as the codebase evolves.
+
+---
+
+## What a shared genome does
+
+The genome is a pre-summarized retrieval index of your codebase. When the
+ashlr-efficiency server receives a `grep` or `read` call, it first checks whether
+the genome has a relevant section and returns that instead of scanning raw files.
+This cuts token usage by 40-80% on well-indexed repos.
+
+When you commit the genome to the repository:
+
+- Every developer gets the same index on `git clone` or `git pull`.
+- `ashlr__grep` returns consistent answers regardless of whose machine runs it.
+- Token savings are deterministic per project — the genome ships with cost
+  estimates in `manifest.json` that the savings accounting uses.
+- New contributors start saving tokens immediately, without running
+  `ashlr-genome-init` themselves.
+
+A committed genome also serves as a living architectural digest: reviewers can
+read `sections/*.md` to understand how subsystems fit together before touching
+code.
+
+---
+
+## Repository layout
+
+After initialization the genome lives entirely inside `.ashlrcode/`:
+
+```
+.ashlrcode/
+  genome/
+    manifest.json          # index metadata, section checksums, cost estimates
+    sections/
+      architecture.md
+      api-surface.md
+      data-models.md
+      ...                  # one file per logical section
+  genome-ignore            # optional exclusion list (see below)
+```
+
+`proposals.jsonl` is written locally by the scribe hook during a session. It is
+not shared.
+
+---
+
+## Git workflow
+
+### Initial commit
+
+After running `/ashlr-genome-init` (or `ashlr__genome_propose` + consolidate) on
+the base branch:
+
+```bash
+git add .ashlrcode/genome/
+git commit -m "chore: add ashlr genome index"
+```
+
+Add this to your project `.gitignore`:
+
+```gitignore
+# ashlr genome — commit the genome itself, ignore local proposals
+.ashlrcode/proposals.jsonl
+.ashlrcode/genome/proposals.jsonl
+```
+
+The `sections/` directory and `manifest.json` should be tracked. They are plain
+markdown and JSON — readable in any diff tool, no binary blobs.
+
+### Keeping it up to date
+
+The genome does not auto-update itself in CI. Designate one developer per sprint
+(or add a `make genome-sync` target) to regenerate it when the codebase drifts:
+
+```makefile
+# Makefile
+genome-sync:
+	git pull --rebase
+	bun run $(ASHLR_PLUGIN_ROOT)/scripts/genome-auto-consolidate.ts
+	git add .ashlrcode/genome/
+	git commit -m "chore: refresh ashlr genome" || true
+	git push
+```
+
+The consolidation script reads accumulated proposals and merges them into
+`sections/*.md`. Run it on a clean working tree so the diff is easy to review.
+
+A practical cadence: run `make genome-sync` after any large refactor, and at
+least once per two-week sprint. The genome degrades gracefully — stale sections
+return slightly less precise results but never break tool calls.
+
+---
+
+## Conflict resolution
+
+### How conflicts arise
+
+`hooks/genome-scribe-hook.ts` appends to `proposals.jsonl` after each session.
+`scripts/genome-auto-consolidate.ts` applies those proposals to `sections/*.md`
+at session end. Both operations are local-only.
+
+If two developers run consolidation on diverged branches and both commit updated
+sections, a standard merge conflict appears in `sections/<name>.md`.
+
+### Resolution strategy
+
+Genome sections are prose documents. The last consolidator's version wins — there
+is no semantic merge logic. Resolve conflicts by accepting one side or
+hand-editing to combine the relevant changes, then re-commit.
+
+Recommended approach:
+
+1. Pull the remote genome into your branch before consolidating locally.
+2. Run `genome-auto-consolidate.ts`.
+3. Commit and push.
+
+```bash
+git pull --rebase origin main
+bun run /path/to/ashlr-plugin/scripts/genome-auto-consolidate.ts
+git add .ashlrcode/genome/
+git commit -m "chore: merge genome"
+git push
+```
+
+If you encounter a conflict during `git pull`:
+
+```bash
+# Accept the remote version (safe default — theirs was already reviewed)
+git checkout --theirs .ashlrcode/genome/sections/architecture.md
+git add .ashlrcode/genome/sections/architecture.md
+
+# Then consolidate your local proposals on top
+bun run /path/to/ashlr-plugin/scripts/genome-auto-consolidate.ts
+```
+
+Conflicts in `manifest.json` should always be resolved by regenerating the file
+via consolidation — do not hand-edit checksums.
+
+---
+
+## genome-ignore: excluding files from the index
+
+Create `.ashlrcode/genome-ignore` at the repository root. One glob pattern per
+line. The scribe hook skips any source file whose path matches a listed pattern.
+
+Example `.ashlrcode/genome-ignore`:
+
+```
+# Never include secrets or credentials
+.env
+.env.*
+secrets/**
+config/credentials.*
+**/*.pem
+**/*.key
+
+# Generated files add noise
+dist/**
+build/**
+coverage/**
+*.min.js
+```
+
+Patterns follow the same syntax as `.gitignore`. The ignore file itself should be
+committed so every developer's scribe respects the same exclusions.
+
+---
+
+## When not to share a genome
+
+**Small throwaway repositories.** If the project will be deleted or archived
+within a few weeks, the overhead of maintaining a genome is not worth it. Skip
+the commit — developers can generate a local genome on demand.
+
+**Secrets risk.** The genome embeds excerpts from source files. Any file that
+contains secrets — API keys, passwords, private keys — must be excluded via
+`genome-ignore` before running the first propose. If a secret is accidentally
+indexed, rotate the secret immediately, remove the section from `sections/`,
+and force-push or use `git filter-repo` to scrub the history.
+
+Rule of thumb: if a file would be dangerous to share in a public pull request,
+add it to `genome-ignore` before running `/ashlr-genome-init`.
+
+**High-churn monorepos.** If hundreds of files change every day, the genome will
+be stale by the time it lands on other machines. Prefer per-package genomes
+scoped to stable subdirectories, or run `genome-sync` in CI on a nightly schedule
+rather than per-commit.
+
+---
+
+## Bootstrapping a new team member
+
+No extra steps are needed beyond the standard clone:
+
+```bash
+git clone https://github.com/your-org/your-repo
+cd your-repo
+bun install   # if ashlr-plugin is a dev dependency
+```
+
+The plugin auto-detects `.ashlrcode/genome/` in the current working directory on
+startup. If the genome exists, it is used immediately — no initialization
+required.
+
+If the new developer's session generates proposals that improve on the committed
+genome, they can run `genome-auto-consolidate.ts` locally and open a PR with the
+updated sections.
+
+---
+
+## Size considerations
+
+A typical genome for a 50,000-line codebase is 200-500 KB. Sections are Markdown
+and compress well in git's object store.
+
+Recommended upper bound: **5 MB total** for the `sections/` directory. Beyond
+that, `git clone` and `git pull` times degrade noticeably on slow connections, and
+the retrieval index itself becomes slower to scan.
+
+If the genome approaches 5 MB:
+
+- Audit `sections/` for redundant or overly verbose entries.
+- Tighten `genome-ignore` to exclude large generated directories.
+- Consider splitting the repo into smaller packages, each with its own genome.
+
+Check current size:
+
+```bash
+du -sh .ashlrcode/genome/sections/
+```
+
+---
+
+## Example: full team workflow end-to-end
+
+```bash
+# Tech lead initializes the genome on main
+cd /path/to/your-repo
+# (in Claude Code with ashlr active)
+# /ashlr-genome-init
+git add .ashlrcode/genome/
+git commit -m "chore: add ashlr genome index"
+git push
+
+# Developer clones repo — genome is immediately active
+git clone https://github.com/your-org/your-repo
+cd your-repo
+# ashlr__grep and ashlr__read now use the genome automatically
+
+# After a sprint of changes, refresh the genome
+make genome-sync
+# opens a PR with updated sections/*.md
+```
+
+---
+
+## See also
+
+- `docs/architecture.md` — system architecture overview used as a source for the
+  genome's architecture section.
+- `/ashlr-genome-init` skill — interactive setup wizard that runs propose +
+  consolidate and writes the initial genome.
+
+---
+
+## Backend-hosted genome sync (Pro team tier)
+
+Teams on the `team` plan can host the authoritative genome on the ashlr backend
+instead of (or alongside) the git-committed copy. Every developer pulls the
+latest sections at session start and pushes their edits back automatically.
+
+### How to opt in
+
+1. Obtain a `ASHLR_PRO_TOKEN` for your org (set in the team billing dashboard).
+2. Create a hosted genome:
+   ```bash
+   curl -X POST https://api.ashlr.ai/genome/init \
+     -H "Authorization: Bearer $ASHLR_PRO_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"orgId":"your-org","repoUrl":"https://github.com/your-org/repo"}'
+   # → {"genomeId":"...","cloneToken":"gclone_..."}
+   ```
+3. Export the genome ID in every developer's shell profile or `.env`:
+   ```bash
+   export ASHLR_TEAM_GENOME_ID=<genomeId>
+   export ASHLR_PRO_TOKEN=<token>
+   ```
+
+From that point on, `session-start.ts` pulls updates automatically and
+`_genome-live.ts` pushes section changes after each `ashlr__edit`.
+
+### Sync flow
+
+```
+Session start
+  └─ GET /genome/:id/pull?since=<localSeq>
+       └─ returns sections modified since last pull
+       └─ writes each section to .ashlrcode/genome/sections/<name>.md
+       └─ persists new serverSeqNum to ~/.ashlr/genome-seq.json
+
+After ashlr__edit on a genome section
+  └─ POST /genome/:id/push { sections:[{path,content,vclock}], clientId }
+       └─ server merges vclocks, detects conflicts
+       └─ responds { applied:[paths], conflicts:[paths] }
+```
+
+### Vector-clock merge algorithm
+
+Each section carries a vector clock `{ [clientId]: count }`.
+
+```
+mergeVClocks(a, b)  →  component-wise max of every key in a ∪ b
+
+compareVClocks(incoming, stored):
+  if incoming[k] >= stored[k] for all k  →  "dominates"  (safe update)
+  if stored[k] >  incoming[k] for any k
+     and incoming[k] < stored[k] for any k  →  "concurrent"  (conflict)
+  if stored[k] > incoming[k] for all k  →  "dominated"  (stale push)
+```
+
+Push semantics by relation:
+- **dominates** — section updated, any prior conflict cleared.
+- **concurrent** — both variants stored; conflict surfaced via `GET /conflicts`.
+- **dominated** — incoming is stale; stored value kept, conflict recorded so
+  neither version is lost.
+
+### Conflict example
+
+Developer A and B both edit `sections/auth.md` from the same base:
+
+| Event | Client | vclock stored | vclock incoming | Result |
+|-------|--------|---------------|-----------------|--------|
+| Push A | `ca`  | `{}`          | `{ca:1}`        | applied, stored = `{ca:1}` |
+| Push B | `cb`  | `{ca:1}`      | `{cb:1}`        | concurrent — conflict recorded |
+
+B's push has `cb:1` (new to server) but is missing `ca:1` (server has it). Neither
+dominates. Both variants are stored and `GET /genome/:id/conflicts` returns them
+with an `authorHint` so the team can choose the winner via
+`POST /genome/:id/resolve`.
+
+### Conflict resolution
+
+```bash
+# List conflicts
+curl https://api.ashlr.ai/genome/$GENOME_ID/conflicts \
+  -H "Authorization: Bearer $ASHLR_PRO_TOKEN"
+
+# Resolve — pick the winning content
+curl -X POST https://api.ashlr.ai/genome/$GENOME_ID/resolve \
+  -H "Authorization: Bearer $ASHLR_PRO_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"path":"sections/auth.md","winning":{"content":"...","vclock":{"ca":1,"cb":1}}}'
+```
+
+The `/ashlr-genome-conflicts` skill shows unresolved conflicts with a short diff
+view inside Claude Code. A full CLI resolver is planned for v2.
+
+### Private vs shared genome trade-offs
+
+| | Git-committed genome | Backend-hosted genome |
+|--|----------------------|-----------------------|
+| Conflict resolution | Manual merge / PR | CRDT auto-merge |
+| Latency to teammates | Next `git pull` | Next session start (~instant) |
+| Offline support | Full | Pull/push silently skipped |
+| Visibility | Full git history | Push audit log only |
+| Setup complexity | None | Requires `ASHLR_TEAM_GENOME_ID` |
+
+For small teams with short PR cycles, the git-committed genome is usually
+sufficient. The hosted sync shines when multiple developers are in active Claude
+Code sessions simultaneously on the same repo.
+
+### Security
+
+- All requests are authenticated with a bearer token (`ASHLR_PRO_TOKEN`).
+- Section paths are sanitized server-side: `..`, absolute paths, and `//`
+  patterns are rejected with HTTP 400.
+- Content is capped at 1 MB per section.
+- Push calls are rate-limited to 10 sections per minute per client.
+- Every push is written to an audit log (`genome_push_log`) for Phase 4 audit
+  trail integration.
+- **Client-side AES-256-GCM encryption is available.** When a team key is
+  present at `~/.ashlr/team-keys/<genomeId>.key`, section content is encrypted
+  before upload and decrypted after pull. The server stores only ciphertext and
+  cannot read section content. See the encryption section below.
+
+---
+
+## Client-side encryption (v1)
+
+### Threat model
+
+| Threat | Mitigation |
+|--------|-----------|
+| Server operator reads section content | Ciphertext only on server; key never leaves client machines |
+| Network observer | TLS + client-side encryption (defence-in-depth) |
+| Compromised Redis / S3 / Postgres | Only ciphertext stored; useless without the key |
+| User leaves team | Rotate the key; ex-member cannot decrypt new sections |
+| Tampered ciphertext | AES-256-GCM auth tag — decryption throws on any modification |
+
+Vector clock (vclock) metadata is transmitted in plaintext so the server can
+perform conflict detection without decrypting content.
+
+### Algorithm
+
+- **AES-256-GCM** with a 256-bit key and a 96-bit (12-byte) random nonce per section push.
+- The 128-bit GCM authentication tag is verified on every decrypt — any tampering throws.
+- Wire format (base64url): `[ version(1 byte) | nonce(12 bytes) | authTag(16 bytes) | ciphertext ]`
+
+### Key setup
+
+Generate a team key once and save it locally:
+
+```bash
+bun run scripts/genome-key.ts generate <genomeId>
+# Key saved to ~/.ashlr/team-keys/<genomeId>.key (mode 0600)
+```
+
+Share it with each team member over a secure channel (Signal, 1Password, etc.):
+
+```bash
+# On machine with key:
+bun run scripts/genome-key.ts export <genomeId>
+# Prints base32-encoded key after confirmation prompt
+
+# On each team member's machine:
+bun run scripts/genome-key.ts import <genomeId> <BASE32_KEY>
+```
+
+Once the key file exists at `~/.ashlr/team-keys/<genomeId>.key`, every push is
+automatically encrypted and every pull automatically decrypted. No other
+configuration is needed.
+
+### Key file location and permissions
+
+```
+~/.ashlr/team-keys/<genomeId>.key   — 32 raw bytes, mode 0600 (owner read/write only)
+```
+
+The file is never logged, never included in git, and never transmitted to the
+server. It lives only on developer machines.
+
+### Key rotation
+
+When a team member leaves or a key may be compromised, rotate the key. This
+re-encrypts all sections on the server with a new key:
+
+```bash
+bun run scripts/genome-key.ts rotate <genomeId>
+```
+
+The rotate command:
+1. Pulls all sections from the remote.
+2. Decrypts each with the current key.
+3. Generates a new 32-byte key.
+4. Re-encrypts all sections with the new key and pushes them.
+5. Saves the new key file locally.
+
+After rotation, distribute the new key to all remaining team members:
+
+```bash
+bun run scripts/genome-key.ts export <genomeId>
+```
+
+Members who do not receive the new key will see a warning on pull and their
+local copy of those sections will not be updated until they import the new key.
+
+### Enforcing encryption org-wide
+
+Org admins can mark a genome as requiring encryption. Pushes from clients
+without a key (plaintext content) will be rejected with HTTP 422:
+
+```bash
+curl -X PATCH https://api.ashlr.ai/genome/$GENOME_ID/settings \
+  -H "Authorization: Bearer $ASHLR_PRO_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"encryption_required": true}'
+```
+
+### Backward compatibility
+
+The server stores a `content_encrypted` boolean per section. Existing plaintext
+sections remain readable by old clients without keys. Mixed teams (some members
+with keys, some without) are supported — members without a key simply cannot
+read encrypted sections. `encryption_required=true` enforces a clean cutover.
+
+### Migration from plaintext to encrypted
+
+For an existing team genome that has been syncing in plaintext:
+
+1. Generate and distribute a key to all team members (see Key setup above).
+2. Run `bun run scripts/genome-key.ts rotate <genomeId>` — this re-encrypts
+   all existing plaintext sections on the server.
+3. Optionally set `encryption_required: true` to prevent future plaintext pushes.
+
+---
+
+## Multi-user encryption model (v2, not yet shipped)
+
+The v1 model uses a single shared symmetric key. This is simple but requires
+out-of-band key distribution and a full rotate when any member leaves.
+
+The v2 model uses asymmetric key wrapping (X25519 / HKDF):
+
+1. **Each member** generates an X25519 keypair. The public key is registered
+   with the genome on the server.
+2. **The genome** has one symmetric data-encryption key (DEK), the same
+   AES-256-GCM key used in v1.
+3. **Key envelopes**: the DEK is encrypted once per member using that member's
+   X25519 public key (via ECDH + HKDF). The server stores the envelope set:
+   `{ memberId → encrypt(memberPublicKey, DEK) }`.
+4. **Adding a member**: admin fetches the DEK (decrypts with their own
+   envelope), re-wraps it to the new member's public key, pushes a new
+   envelope. No re-encryption of section content needed.
+5. **Removing a member**: admin removes the member's envelope and rotates the
+   DEK (same as v1 rotate, but the new DEK is then wrapped for all remaining
+   members). The removed member's envelope is gone; they cannot decrypt the
+   new DEK.
+6. **Decryption on pull**: client fetches its envelope, decrypts the DEK, then
+   decrypts sections exactly as in v1.
+
+Migration from v1 to v2 is non-breaking: the section wire format and
+`serializeBlob` encoding are unchanged. Only key delivery changes.
+