diff --git a/.gitignore b/.gitignore
index 63ea713..34be5e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,5 @@ coverage/
 .claude/
 lastchat.txt
 AGENTS.md
+EDITORS-REPORT
+EDITORS-REPORT.*
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e9f2f86..ee32eca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.3.3] — Unreleased
 
 ### Added
+
+- **`git cas agent recipient ...`** — added machine-facing recipient inspection and mutation commands so Relay can list recipients and perform add/remove flows through structured protocol data instead of human CLI text.
+- **`git cas agent rotate`** — added a machine-facing rotation flow so Relay can rotate recipient keys by slug or detached tree OID and expose the resulting tree and vault side effects explicitly.
+- **`git cas agent vault rotate`** — added a machine-facing vault passphrase rotation flow so Relay can rotate encrypted vault state with explicit commit, KDF, and rotated/skipped-entry results.
+- **`git cas agent vault init|remove`** — added machine-facing vault lifecycle commands so Relay can initialize encrypted or plaintext vaults and remove entries without scraping human CLI output.
+- **Workflow model** — added [WORKFLOW.md](./WORKFLOW.md), explicit legends/backlog/invariants directories, and a cycle-first planning model for fresh work.
 - **Review automation baseline** — added `.github/CODEOWNERS` with repo-wide ownership for `@git-stunts`.
 - **Release runbook** — added `docs/RELEASE.md` and linked it from `CONTRIBUTING.md` as the canonical patch-release workflow.
 - **`pnpm release:verify`** — new maintainer-facing release helper runs the full release checklist, captures observed test counts, and prints a Markdown summary that can be pasted into release notes or changelog prep.
@@ -16,11 +22,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Deterministic property-based envelope coverage** — added a `fast-check`-backed property suite for envelope-encrypted store/restore round-trips and tamper rejection across empty, boundary-adjacent, and multi-chunk payload sizes.
 
 ### Changed
+
 - **GitHub Actions runtime maintenance** — CI and release workflows now run on `actions/checkout@v6` and `actions/setup-node@v6`, clearing the Node 20 deprecation warnings from GitHub-hosted runners.
 - **Ubuntu-based Docker test stages** — the local/CI Node, Bun, and Deno test images now build on `ubuntu:24.04`, copying runtime binaries from the official upstream images instead of inheriting Debian-based runtime images directly, and the final test commands now run as an unprivileged `gitstunts` user.
 - **Test conventions expanded** — `test/CONVENTIONS.md` now documents Git tree filename ordering, Docker-only integration policy, pinned integration `fileParallelism: false`, and direct-argv subprocess helpers.
 
 ### Fixed
+
+- **CLI credential edge cases** — `store --recipient` now ignores ambient `GIT_CAS_PASSPHRASE` state when no explicit vault passphrase flag/file was provided, store/restore/init now reject ambiguous explicit credential combinations consistently, `vault init --algorithm` no longer silently falls back to plaintext without a passphrase source, and `vault rotate` now rejects whitespace-only old/new passphrase inputs instead of treating them as valid credentials.
 - **Bun blob writes in Git persistence** — `GitPersistenceAdapter.writeBlob()` now hashes temp files instead of piping large buffers through `git hash-object --stdin` under Bun, avoiding unhandled `EPIPE` failures during real Git-backed stores.
 - **Release verification runner failures** — `runReleaseVerify()` now converts thrown step-runner errors into structured step failures with a `ReleaseVerifyError` summary instead of letting raw exceptions escape.
 - **Machine-readable release verification** — `pnpm release:verify --json` now emits structured JSON on both success and failure paths, making CI automation and release-note tooling consume the same verification source of truth.
@@ -29,15 +38,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.3.2] — 2026-03-15
 
 ### Changed
+
 - **Vitest workspace split** — unit, integration, and benchmark suites now live in explicit workspace projects so the integration suite always runs with `fileParallelism: false`, regardless of the exact CLI invocation shape.
 - **Status semantics** — `STATUS.md` now distinguishes the last released version (`v5.3.1`) from the current branch version (`v5.3.2`).
 
 ### Fixed
+
 - **CLI version drift** — `bin/git-cas.js` now reads the package version instead of carrying a stale hardcoded literal, so `git-cas --version` tracks the in-repo release line correctly.
 
 ## [5.3.1] — 2026-03-15
 
 ### Fixed
+
 - **Repeated chunk tree emission** — `createTree()` and `_createMerkleTree()` now emit one chunk blob tree entry per unique digest, preserving first-seen order at write time while leaving the manifest unchanged as the authoritative ordered index of chunk occurrences.
 - **Invalid Git trees for repetitive content** — repetitive files no longer produce duplicate tree entry names, so emitted trees pass `git fsck --full` without `duplicateEntries` failures.
 - **Regression coverage for tree reachability** — added unit tests for first-seen dedupe behavior and integration tests that store repetitive content, verify restore correctness, and assert clean `git fsck` results on a real Git repository.
@@ -45,6 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.3.0] — 2026-03-08
 
 ### Added
+
 - **Vault rotate passphrase-file support** — `vault rotate` now accepts `--old-passphrase-file` and `--new-passphrase-file` flags, bringing it to parity with the store/restore passphrase-file support.
 - **CLI store flags** — `--gzip`, `--strategy <fixed|cdc>`, `--chunk-size <n>`, `--concurrency <n>`, `--codec <json|cbor>`, `--merkle-threshold <n>`, `--target-chunk-size <n>`, `--min-chunk-size <n>`, `--max-chunk-size <n>`. All library-level chunking, compression, codec, and concurrency options are now accessible from the CLI.
 - **CLI restore flags** — `--concurrency <n>`, `--max-restore-buffer <n>`. Parallel I/O and restore buffer limit now configurable from CLI.
@@ -63,6 +76,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **16.7 — Lifecycle method naming** — Added `inspectAsset()` (replaces `deleteAsset()`) and `collectReferencedChunks()` (replaces `findOrphanedChunks()`) as canonical names on both `CasService` and the facade. Old names are preserved as deprecated aliases that emit observability warnings. Type definitions updated with `@deprecated` JSDoc.
 
 ### Changed
+
 - **`runAction` injectable delay** — `runAction()` now accepts an optional `{ delay }` dependency, replacing the hardcoded `setTimeout` call. Tests inject a spy instead of using `vi.useFakeTimers()`, making INTEGRITY_ERROR rate-limit tests deterministic across Node, Bun, and Deno.
 - **Test conventions** — Added `test/CONVENTIONS.md` documenting rules for deterministic, cross-runtime tests: inject time dependencies, use `chmod()` instead of `writeFile({ mode })`, avoid global state patching.
 - **VaultService test observability wiring** — `VaultService.test.js` now passes a `mockObservability()` port to all tests instead of relying on the silent no-op default. `rotateVaultPassphrase.test.js` now passes `SilentObserver` explicitly. If observability wiring breaks, the test suite will catch it.
@@ -73,6 +87,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **16.4 — FixedChunker pre-allocated buffer** — Replaced `Buffer.concat()` loop with a pre-allocated `Buffer.allocUnsafe(chunkSize)` working buffer, eliminating O(n²) copies for many small input buffers. Matches the allocation strategy used by `CdcChunker`.
 
 ### Fixed
+
 - **Post-decompression size guard** — `_restoreBuffered` now enforces `maxRestoreBufferSize` after decompression, not just before. Compressed payloads that inflate beyond the configured limit now throw `RESTORE_TOO_LARGE` instead of silently allocating unbounded memory.
 - **CLI passphrase prompt deferral** — `resolveEncryptionKey` now checks vault metadata before calling `resolvePassphrase`, avoiding unnecessary TTY prompts for unencrypted vaults. Store action recipient-conflict check inspects flags/env without consuming stdin.
 - **CRLF passphrase normalization** — `readPassphraseFile` now strips trailing `\r\n` (Windows line endings) in addition to `\n`, preventing passphrase mismatches from Windows-edited files.
@@ -95,6 +110,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.2.4] — Prism polish (2026-03-03)
 
 ### Fixed
+
 - **`CryptoPortBase.sha256()` type** — `index.d.ts` declaration corrected from `string | Promise<string>` to `Promise<string>`, matching the async implementation since v5.2.3.
 - **`keyLength` passthrough** — `KeyResolver.#resolveKeyFromPassphrase` and `deriveKekFromKdf` now forward `kdf.keyLength` to `deriveKey()`, fixing a latent bug for vaults configured with non-default key lengths.
 - **Deno test compatibility** — `createCryptoAdapter.test.js` no longer crashes on Deno by guarding immutable `globalThis.Deno` restoration with try/catch and skipping Node-only tests on non-Node runtimes.
@@ -103,6 +119,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Vestigial `lastchat.txt`** removed from `jsr.json` exclude list.
 
 ### Changed
+
 - **`keyResolver` is now private** — `CasService.keyResolver` changed to `#keyResolver`, preventing external access to an internal implementation detail.
 - **`VaultPassphraseRotator.js` → `rotateVaultPassphrase.js`** — renamed to follow camelCase convention for files that export a function (PascalCase is reserved for classes).
 - **`resolveChunker` validation** — `chunkSize` now validated as a finite positive number before constructing `FixedChunker`; invalid values fall through to CasService default.
@@ -114,6 +131,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.2.3] — Prism refactor (2026-03-03)
 
 ### Changed
+
 - **Async `sha256()` across all adapters** — `NodeCryptoAdapter.sha256()` now returns `Promise<string>` (was sync `string`), matching Bun and Web adapters. Fixes Liskov Substitution violation; all callers already `await`. `CryptoPort` JSDoc and `CasService.d.ts` updated to `Promise<string>`.
 - **Extract `KeyResolver`** — ~170 lines of key resolution logic (`wrapDek`, `unwrapDek`, `resolveForDecryption`, `resolveForStore`, `resolveRecipients`, `resolveKeyForRecipients`, passphrase derivation, mutual-exclusion validation) extracted from `CasService` into `src/domain/services/KeyResolver.js`. CasService delegates via `this.keyResolver`. No public API changes. 24 new unit tests.
 - **Move `createCryptoAdapter`** — runtime crypto detection moved from `index.js` to `src/infrastructure/adapters/createCryptoAdapter.js`; test helper now delegates instead of duplicating.
@@ -130,12 +148,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.2.2] — JSDoc total coverage (2026-02-28)
 
 ### Added
+
 - `tsconfig.checkjs.json` — strict `checkJs` configuration; `tsc --noEmit` passes with zero errors.
 - `src/types/ambient.d.ts` — ambient type declarations for `@git-stunts/plumbing` and `bun` modules.
 - `@types/node` dev dependency for typecheck support.
 - JSDoc `@typedef` types: `EncryptionMeta`, `KdfParamSet`, `DeriveKeyParams` (CryptoPort); `VaultMetadata`, `VaultState`, `VaultEncryptionMeta` (VaultService).
 
 ### Changed
+
 - Every exported and internal function, class method, and callback across all 32 source files now has complete JSDoc `@param`/`@returns` annotations.
 - CryptoPort return types widened to `string | Promise<string>` (sha256), `Buffer | Uint8Array` (randomBytes), sync-or-async for encrypt/decrypt — accurately reflecting adapter implementations.
 - Port `@param` names corrected to match underscore-prefixed abstract parameters (fixes TS8024).
@@ -145,19 +165,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.2.1] — Carousel polish (2026-02-28)
 
 ### Added
+
 - CLI reference in `docs/API.md` for `git cas rotate` and `git cas vault rotate` flags.
 
 ### Changed
+
 - Rotation helpers in `CasService` use native `#private` methods, matching the facade's style.
 - `VAULT_CONFLICT` and `VAULT_METADATA_INVALID` error code docs now list `rotateVaultPassphrase()`.
 
 ### Fixed
+
 - `rotateVaultPassphrase` now honours `kdfOptions.algorithm` instead of silently using the old algorithm.
 - Rotation integration test no longer flaps under CI load (reduced test-only KDF iterations).
 
 ## [5.2.0] — Carousel (2026-02-28)
 
 ### Added
+
 - **Key rotation without re-encrypting data** — `CasService.rotateKey()` re-wraps the DEK with a new KEK, leaving data blobs untouched. Enables key compromise response without re-storing assets.
 - **`keyVersion` tracking** — manifest-level and per-recipient `keyVersion` counters track rotation history for audit compliance. Optional field, backward-compatible with existing manifests.
 - **`git cas rotate` CLI command** — rotate a recipient's key via `--slug` (vault round-trip) or `--oid` (manifest-only). Supports `--label` for targeted single-recipient rotation.
@@ -169,6 +193,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.1.0] — Locksmith (2026-02-28)
 
 ### Added
+
 - **Envelope encryption (DEK/KEK)** — multi-recipient model where a random DEK encrypts content and per-recipient KEKs wrap the DEK. Recipients can be added/removed without re-encrypting data.
 - **`RecipientSchema`** — Zod schema for validating recipient entries in manifests.
 - **`recipients` field on `EncryptionSchema`** — optional array of `{ label, wrappedDek, nonce, tag }` entries.
@@ -179,6 +204,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 48 new unit tests covering envelope store/restore, recipient management, edge cases, and fuzz round-trips.
 
 ### Fixed
+
 - **`_wrapDek` / `_unwrapDek` missing `await`** — these called async `encryptBuffer()` / `decryptBuffer()` without `await`, silently producing garbage on Bun/Deno runtimes where crypto is async.
 - **`--recipient` + `--vault-passphrase` not guarded** — CLI now rejects combining `--recipient` with `--key-file` or `--vault-passphrase`.
 - **Dead `_resolveEncryptionKey` method removed** — superseded by `_resolveDecryptionKey` but left behind.
@@ -194,10 +220,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [5.0.0] — Hydra (2026-02-28)
 
 ### Breaking Changes
+
 - **`CasService` constructor accepts `chunker` port** — a new optional `ChunkingPort` parameter controls chunking strategy. Existing code that does not pass `chunker` is unaffected (defaults to `FixedChunker`).
 - **Major version bump** — new hexagonal port (`ChunkingPort`) and manifest schema extension warrant a semver-major release for downstream tooling awareness.
 
 ### Added
+
 - **Content-defined chunking (CDC)** — Buzhash rolling-hash engine with configurable `minChunkSize` (64 KiB), `maxChunkSize` (1 MiB), and `targetChunkSize` (256 KiB). CDC limits the dedup blast radius to 1–2 chunks on incremental edits vs. total invalidation with fixed-size chunking. Benchmarked at 265 MB/s and 98.4% chunk reuse on small edits.
 - **`ChunkingPort`** — new hexagonal port (`src/ports/ChunkingPort.js`) with `async *chunk(source)`, `strategy`, and `params`. Abstracts chunking behind a pluggable interface.
 - **`FixedChunker`** — adapter wrapping existing fixed-size buffer slicing behind `ChunkingPort`.
@@ -210,12 +238,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 90 new unit tests (709 total).
 
 ### Changed
+
 - `CasService._chunkAndStore()` refactored to delegate to `ChunkingPort` instead of inline buffer slicing.
 - `ChunkingPort`, `FixedChunker`, `CdcChunker` exported from the main entry point.
 
 ## [4.0.1] — M8 Spit Shine + M9 Cockpit (2026-02-28)
 
 ### Added
+
 - **`git cas verify`** command — verify stored asset integrity from the CLI (checks blob hashes; no key needed).
 - **`--json` global flag** — structured JSON output for all commands (`store`, `restore`, `verify`, `inspect`, `vault list/init/remove/info/history`).
 - **`runAction` error handler** (`bin/actions.js`) — centralized `try`/`catch` with CasError code display and actionable hints for 5 common errors.
@@ -227,6 +257,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `WebCryptoAdapter.finalize()` guard — throws `STREAM_NOT_CONSUMED` if called before encrypt stream is fully consumed.
 
 ### Fixed
+
 - `verify` command uses `process.exitCode = 1` instead of `process.exit(1)` to allow stdout to drain on pipes.
 - `runAction` uses `process.exitCode = 1` for consistent exit behavior across all commands.
 - `vault info --json --encryption` now includes encryption metadata in JSON output.
@@ -240,16 +271,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `_doDeriveKey` in `NodeCryptoAdapter` now properly `await`s promisified calls.
 
 ### Changed
+
 - `CryptoPort` is now the single source of truth for key validation, metadata building, and KDF parameter normalization. All three adapters override only `_doDeriveKey()`.
 - ROADMAP.md pruned: completed M1–M7 task cards moved to COMPLETED_TASKS.md.
 
 ## [4.0.0] — Conduit (2026-02-27)
 
 ### Breaking Changes
+
 - **`CasService` no longer extends `EventEmitter`** — event subscriptions must use the new `ObservabilityPort` adapters instead of `service.on()`. The `EventEmitterObserver` adapter provides full backward compatibility for existing event-based code.
 - **`observability` is a required constructor port** for `CasService`. The facade (`ContentAddressableStore`) defaults to `SilentObserver` when omitted.
 
 ### Added
+
 - **ObservabilityPort** — new hexagonal port (`src/ports/ObservabilityPort.js`) with `metric(channel, data)`, `log(level, msg, meta?)`, and `span(name)` methods. Decouples the domain layer from Node's event infrastructure.
 - **SilentObserver** — no-op adapter (default). Zero overhead when observability is not needed.
 - **EventEmitterObserver** — bridges `metric()` calls to EventEmitter events (`chunk:stored`, `file:restored`, etc.) for backward-compatible progress tracking. Exposes `.on()`, `.removeListener()`, `.listenerCount()`.
@@ -261,6 +295,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 43 new unit tests (567 total).
 
 ### Changed
+
 - CLI `store` and `restore` commands now create an `EventEmitterObserver` and pass it to the CAS instance, attaching progress tracking to the observer instead of the service.
 - `restore()` reimplemented as a collector over `restoreStream()`.
 - `_chunkAndStore()` refactored to use semaphore-gated parallel writes with `Promise.all`, sorting results by index after completion.
@@ -269,6 +304,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [3.1.0] — Bijou (2026-02-27)
 
 ### Added
+
 - **Interactive vault dashboard** (`git cas vault dashboard`) — TEA-based TUI with split-pane layout, manifest detail view, keyboard navigation (`j`/`k`/`Enter`/`/`), and real-time filtering.
 - **Manifest inspector** (`git cas inspect <tree-oid>`) — renders manifest details with chunk table, encryption info, and compression badges.
 - **Progress bars** for `store` and `restore` operations — animated progress with throughput reporting, auto-disabled in non-TTY environments.
@@ -280,6 +316,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New runtime dependencies: `@flyingrobots/bijou`, `@flyingrobots/bijou-node`, `@flyingrobots/bijou-tui`.
 
 ### Fixed
+
 - CLI `restore` now uses the canonical `readManifest` path instead of duplicating manifest resolution logic.
 - Progress trackers wrapped in `try`/`finally` to prevent event listener leaks when `storeFile` or `restoreFile` throws.
 - Dashboard filter and error lines clamped to pane width to prevent wrapping artifacts in narrow terminals.
@@ -293,6 +330,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [3.0.0] — Vault (2026-02-08)
 
 ### Added
+
 - **Vault** — GC-safe ref-based storage via `refs/cas/vault`. A single Git ref pointing to a commit chain indexes all stored assets by slug. `git gc` can no longer silently discard stored data.
   - `initVault()` — initialize the vault, optionally with passphrase-based encryption (vault-level KDF policy).
   - `addToVault()` — add or update an entry by slug + tree OID, with `force` flag for overwrites.
@@ -316,6 +354,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 46 vault unit tests + facade delegation smoke test.
 
 ### Fixed
+
 - `#validateMetadata` now requires `kdf.keyLength` in encryption metadata, preventing downstream KDF failures from manually edited `.vault.json` files.
 - `#casUpdateRef` now preserves the original error in `VAULT_CONFLICT` meta for better diagnostics.
 - CLI `--vault-passphrase` now emits a stderr warning when the vault is not encrypted, instead of silently ignoring the passphrase.
@@ -329,6 +368,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLI uses `program.parseAsync()` instead of `program.parse()` to prevent Bun from hanging on async action handlers.
 
 ### Changed
+
 - **Vault promoted to domain layer** — all vault logic extracted from facade (`index.js`) into `VaultService` (`src/domain/services/VaultService.js`) with `GitRefPort`/`GitRefAdapter` for ref operations. Facade now delegates to VaultService.
 - CLI `restore` command no longer takes a positional `<tree-oid>` argument. Use `--oid <tree-oid>` or `--slug <slug>` instead.
 - Purged completed milestones (M1–M7) and their task cards from ROADMAP.md, reducing it from 3,153 to 1,675 lines.
@@ -336,6 +376,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [2.0.0] — M7 Horizon (2026-02-08)
 
 ### Added
+
 - **Compression support** (Task 7.1): Optional gzip compression pipeline via `compression: { algorithm: 'gzip' }` option on `store()`. Compression is applied before encryption when both are enabled. Manifests include a new optional `compression` field. Decompression on `restore()` is automatic.
 - **KDF support** (Task 7.2): Passphrase-based encryption using PBKDF2 or scrypt via `deriveKey()` method and `passphrase` option on `store()`/`restore()`. KDF parameters are stored in `manifest.encryption.kdf` for deterministic re-derivation. All three crypto adapters (Node, Bun, Web) implement `deriveKey()`.
 - **Merkle tree manifests** (Task 7.3): Large manifests (chunk count exceeding `merkleThreshold`, default 1000) are automatically split into sub-manifests stored as separate blobs. Root manifest uses `version: 2` with `subManifests` references. `readManifest()` transparently reconstitutes v2 manifests into flat chunk lists. Full backward compatibility with v1 manifests.
@@ -345,6 +386,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated API reference (`docs/API.md`), guide (`GUIDE.md`), and README with v2.0.0 feature documentation.
 
 ### Changed
+
 - **BREAKING**: Manifest schema now includes `version` field (defaults to 1). Existing v1 manifests are fully backward-compatible.
 - `CasService` constructor accepts new `merkleThreshold` option (must be a positive integer).
 - `ContentAddressableStore` constructor now accepts and forwards `merkleThreshold` to `CasService`.
@@ -353,6 +395,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Static imports for `createGzip` and `Readable` in `CasService` (previously dynamic imports on every call).
 
 ### Fixed
+
 - **Sub-manifest blobs are now included as tree entries** (`sub-manifest-N.json`), preventing them from being garbage-collected by `git gc`.
 - `storeFile()` now forwards `passphrase`, `kdfOptions`, and `compression` options to `store()` (previously silently dropped).
 - `store()` and `restore()` reject when both `passphrase` and `encryptionKey` are provided (`INVALID_OPTIONS`).
@@ -369,19 +412,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.6.2] — OIDC publishing + JSR docs coverage (2026-02-07)
 
 ### Added
+
 - JSDoc comments on all exported TypeScript interfaces (`CryptoPort`, `CodecPort`, `GitPersistencePort`, `CasServiceOptions`, `EncryptionMeta`, `ManifestData`, `ContentAddressableStoreOptions`) to reach 100% JSR symbol documentation coverage.
 
 ### Fixed
+
 - npm publish workflow now uses OIDC trusted publishing (no stored token). Upgrades npm to >=11.5.1 at publish time since pnpm does not yet support OIDC natively.
 
 ## [1.6.1] — JSR quality fixes (2026-02-07)
 
 ### Added
+
 - TypeScript declaration files (`.d.ts`) for all three entrypoints and shared value objects, resolving JSR "slow types" scoring penalty.
 - `@ts-self-types` directives in `index.js`, `CasService.js`, and `ManifestSchema.js`.
 - `@fileoverview` module doc to `CasService.js` (required by JSR for module docs scoring).
 
 ### Fixed
+
 - JSR package name corrected to `@git-stunts/git-cas`.
 - JSR publication now excludes tests, docs, CI configs, and other non-distribution files via `jsr.json` exclude list.
 - `index.d.ts` added to `package.json` files array for npm distribution.
@@ -389,6 +436,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.6.0] — M4 Compass + M5 Sonar + M6 Cartographer (2026-02-06)
 
 ### Added
+
 - `CasService.readManifest({ treeOid })` — reads a Git tree, locates and decodes the manifest, returns a validated `Manifest` value object.
 - `CasService.deleteAsset({ treeOid })` — returns logical deletion metadata (`{ slug, chunksOrphaned }`) without performing destructive Git operations.
 - `CasService.findOrphanedChunks({ treeOids })` — aggregates referenced chunk blob OIDs across multiple assets, returning `{ referenced: Set<string>, total: number }`.
@@ -411,18 +459,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.3.0] — M3 Launchpad (2026-02-06)
 
 ### Added
+
 - Native Bun support via `BunCryptoAdapter` (uses `Bun.CryptoHasher`).
 - Native Deno/Web standard support via `WebCryptoAdapter` (uses `crypto.subtle`).
 - Automated, secure release workflow (`.github/workflows/release.yml`) with:
-    - **NPM OIDC support** including build provenance.
-    - **JSR support** via `jsr.json` and automated publishing.
-    - **GitHub Releases** with automated release notes.
-    - **Idempotency & Version Checks** to prevent failed partial releases.
+  - **NPM OIDC support** including build provenance.
+  - **JSR support** via `jsr.json` and automated publishing.
+  - **GitHub Releases** with automated release notes.
+  - **Idempotency & Version Checks** to prevent failed partial releases.
 - Dynamic runtime detection in `ContentAddressableStore` to pick the best adapter automatically.
 - Hardened `package.json` with repository metadata, engine constraints, and explicit file inclusion.
 - Local quality gates via `pre-push` git hook and `scripts/install-hooks.sh`.
 
 ### Changed
+
 - **Breaking Change:** `CasService` cryptographic methods (`sha256`, `encrypt`, `decrypt`, `verifyIntegrity`) are now asynchronous to support Web Crypto and native optimizations.
 - `ContentAddressableStore` facade methods are now asynchronous to accommodate lazy service initialization and async crypto.
 - Project migrated from `npm` to `pnpm` for faster, more reliable dependency management.
@@ -430,6 +480,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Dockerfile` now uses `corepack` for pnpm management.
 
 ### Fixed
+
 - Fixed recursion bug in `BunCryptoAdapter` where `randomBytes` shadowed the imported function.
 - Resolved lazy-initialization race condition in `ContentAddressableStore` via promise caching.
 - Fixed state leak in `WebCryptoAdapter` streaming encryption.
@@ -439,6 +490,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.2.0] — M2 Boomerang (v1.2.0)
 
 ### Added
+
 - `CryptoPort` interface and `NodeCryptoAdapter` — extracted all `node:crypto` usage from the domain layer.
 - `CasService.store()` — accepts `AsyncIterable<Buffer>` sources (renamed from `storeFile`).
 - Multi-stage Dockerfile (Node 22, Bun, Deno) with `docker-compose.yml` for per-runtime testing.
@@ -451,14 +503,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Deterministic test digest helper (`digestOf`).
 
 ### Changed
+
 - `CasService` domain layer has zero `node:*` imports — all platform dependencies injected via ports.
 - Constructor requires `crypto` and `codec` params (no defaults); facade supplies them.
 - Facade `storeFile()` now opens the file and delegates to `CasService.store()`.
 
 ### Fixed
+
 - None.
 
 ### Security
+
 - None.
 
 ## [1.0.0] - 2025-05-30
@@ -475,10 +530,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Docker-based test runner for reproducible CI builds.
 
 ### Changed
+
 - None.
 
 ### Fixed
+
 - None.
 
 ### Security
+
 - None.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e45ed12..cbafa78 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,27 +1,335 @@
-# Contributing to @git-stunts/cas
-
-## Philosophy
-- **Domain Purity**: Keep crypto and chunking logic independent of Git implementation details.
-- **Portability**: The `GitPersistencePort` allows swapping the storage backend.
-
-## Development Workflow
-
-1. **Install Dependencies**: Use `pnpm install` to ensure consistent dependency management.
-2. **Install Git Hooks**: Run `bash scripts/install-hooks.sh` to set up local quality gates. This will ensure that linting and unit tests pass before every push.
-3. **Run Tests Locally**:
-   - `pnpm test` for unit tests.
-   - `pnpm run test:integration:node` for Node integration tests (requires Docker).
-   - `pnpm run test:integration:bun` for Bun integration tests.
-   - `pnpm run test:integration:deno` for Deno integration tests.
-4. **Prepare Releases**:
-   - `pnpm release:verify` for the full release checklist and release-note summary output.
-   - Follow [docs/RELEASE.md](./docs/RELEASE.md) for the canonical patch-release flow.
-
-## Quality Gates
-We enforce high standards for code quality:
-- **Linting**: Must pass `pnpm run lint`.
-- **Unit Tests**: All unit tests must pass.
-- **Integration Tests**: Must pass across Node, Bun, and Deno runtimes.
-- **Release Prep**: `pnpm release:verify` must pass before a tag is created.
-
-These gates are enforced both locally via git hooks and in CI/CD.
+# Contributing to @git-stunts/git-cas
+
+`git-cas` is not just a bag of Git tricks.
+
+It is a deterministic artifact system built on Git's object database, with two
+product surfaces over one shared core:
+
+- a human CLI/TUI
+- a machine-facing agent surface
+
+If you contribute here, the job is not just to make code pass. The job is to
+protect that product shape while making the system more capable.
+
+## Core Product Philosophy
+
+- Git is the substrate, not the product.
+- Integrity is sacred.
+- Restore must be deterministic.
+- Provenance matters.
+- Verification matters.
+- GC-safe storage is non-negotiable.
+- Human and agent surfaces are separate products over one domain core.
+- The substrate may be sophisticated; the default UX must still feel boring,
+  trustworthy, and legible.
+
+The highest-level rule is simple:
+
+If a change makes storage less trustworthy, restore less deterministic,
+automation less explicit, or the normal operator flow more demanding, it is
+probably the wrong change.
+
+## Development Philosophy
+
+This project prefers:
+
+- DX over ceremony
+- behavior over architecture theater
+- explicit boundaries over clever coupling
+- local-first, self-contained operation over service dependency
+- boring human defaults over impressive internals
+- machine contracts over scraped text
+
+In practice, that means:
+
+- keep commands small and obvious
+- keep the default human UX boring and legible
+- keep Git internals out of normal UX unless they are operationally necessary
+- keep future automation concerns out of the human path until they are earned
+- keep every human CLI command machine-readable through `--json`
+- keep the `git cas agent` surface JSONL-first and non-interactive
+
+## Architectural Principles
+
+### Hexagonal Architecture
+
+The product should keep clear boundaries between:
+
+- domain behavior
+- application/use-case orchestration
+- ingress adapters such as the human CLI/TUI and the agent CLI
+- infrastructure such as Git persistence, refs, codecs, crypto, and filesystem
+
+Do not let UI concerns leak into persistence.
+Do not let storage details leak into normal UX.
+Do not let terminal behavior define the application boundary.
+
+### SOLID, Pragmatically Applied
+
+Use SOLID as boundary discipline, not as a pretext for abstraction sprawl.
+
+Good:
+
+- narrow modules
+- explicit seams
+- dependency inversion around important adapters
+- shared application behavior consumed by multiple surfaces
+
+Bad:
+
+- abstraction for its own sake
+- indirection before there is pressure for it
+- architecture rituals that slow delivery without protecting behavior
+
+## Planning And Delivery Model
+
+This project now plans fresh work through:
+
+- legends
+- cycles
+- backlog items
+- invariants
+
+The working source of truth is [WORKFLOW.md](./WORKFLOW.md).
+
+That means:
+
+- legends carry broad thematic efforts
+- cycles are the implementation and design loop
+- backlog items are cheap, single-file work candidates
+- invariants are explicit project truths that work cannot violate
+
+This project still uses IBM Design Thinking framing, but it is now applied at
+the cycle level with both human and agent passes:
+
+- human users, jobs, and hills
+- agent users, jobs, and hills
+- human playback
+- agent playback
+- explicit non-goals
+
+Fresh work should be grounded in human or agent value, not backend vanity.
+
+Before promoting a new direction, ask:
+
+- which legend does this support?
+- which cycle hill does this support?
+- what human or agent behavior does this improve?
+- what trust does this increase?
+- what invariant does this depend on or risk violating?
+
+If the answer is unclear, the work probably belongs in
+[`docs/BACKLOG/`](./docs/BACKLOG/), not in an active cycle doc.
+
+## Directory Model
+
+New planning work uses:
+
+- [`docs/legends/`](./docs/legends/)
+- [`docs/BACKLOG/`](./docs/BACKLOG/)
+- [`docs/design/`](./docs/design/)
+- [`docs/invariants/`](./docs/invariants/)
+- [`test/cycles/`](./test/cycles/)
+
+`ROADMAP.md` and `STATUS.md` remain useful sequence and snapshot documents, but
+they are now migration surfaces for planning, not the primary place where fresh
+cycle planning starts.
+
+## Build Order
+
+The expected order of work is:
+
+1. Write or revise design docs first.
+2. Encode behavior as executable tests second.
+3. Implement third.
+
+Tests are the spec.
+
+Do not insert a second prose-spec layer between design and tests.
+Do not treat implementation details as the primary unit of correctness.
+
+## Cycle Development Loop
+
+Each cycle should follow the same explicit loop:
+
+1. design docs first
+2. tests as spec second
+3. implementation third
+4. human and agent playbacks
+5. retrospective after delivery
+6. update `docs/BACKLOG/` with debt and follow-on work
+7. update the root [CHANGELOG.md](./CHANGELOG.md)
+8. rewrite the root README when reality changed materially
+
+This loop is part of the process, not optional cleanup.
+
+The point is to keep the repo honest about:
+
+- what is planned
+- what is specified
+- what is actually implemented
+- what was learned
+
+## Release Discipline
+
+Cycle closure and release discipline are coupled when a landed cycle materially
+changes the product.
+
+Rules:
+
+- keep the root [CHANGELOG.md](./CHANGELOG.md)
+- keep `package.json` and `jsr.json` versioned to reality, not aspiration
+- when a release-worthy cycle or grouped set of cycles is closed, bump the
+  in-flight version on the release commit
+- create a Git tag on the commit that lands on `main` for that release
+- follow [docs/RELEASE.md](./docs/RELEASE.md) instead of improvising release flow
+
+The version and tag should reflect shipped reality, not hopeful scope.
+
+## Testing Rules
+
+Tests must be deterministic.
+
+That means:
+
+- no real network dependency
+- no ambient home-directory state
+- no ambient Git config assumptions
+- no interactive shell expectations in the core suite
+- no timing-based flakes
+- no shared mutable repository state between tests
+
+Every test that touches storage should use isolated temp state.
+
+Prefer:
+
+- throwaway local repos
+- throwaway bare remotes when needed
+- fixed env and fixed IDs where practical
+- direct argv subprocess execution instead of shell-wrapped commands
+
+Tests should pin:
+
+- user-visible behavior
+- integrity and restore correctness
+- provenance and verification behavior
+- immutability boundaries
+- honest backup/storage semantics
+- `--json` output contracts for the human CLI
+- JSONL protocol contracts for the agent CLI as it lands
+
+Tests should not overfit:
+
+- class layout
+- file-private helpers
+- incidental implementation structure
+
+Local testing policy:
+
+- `npm test` is the default fast suite
+- `npx eslint .` must stay clean
+- integration tests run through Docker-backed runtime targets
+- `pnpm release:verify` is the release truth source
+- install hooks with `bash scripts/install-hooks.sh`
+
+## Human Surface Guardrails
+
+Do not introduce any of the following into the normal operator path unless
+explicitly re-approved:
+
+- hidden side effects
+- smart guessing in place of explicit state
+- TUI-only access to essential behavior
+- substrate jargon when plain language will do
+- prompts where flags or files should be accepted
+
+The human path should feel trustworthy and boring, not magical.
+
+## Agent Surface Guardrails
+
+The `git cas agent` surface is the automation contract.
+
+That implies:
+
+- no TTY branching
+- no implicit prompts
+- stdout carries only protocol data
+- stderr carries structured warnings and errors
+- side effects must be explicit
+- failure modes must be actionable without scraping prose
+- binary payloads do not share protocol stdout
+
+Do not let the agent surface become “human CLI plus `--json`.”
+
+## UX Language Rules
+
+Default human-facing language should prefer artifact and storage language over
+Git internals.
+
+Prefer:
+
+- `stored`
+- `verified`
+- `restored`
+- `encrypted`
+- `vault`
+- `backup pending` or `not yet backed up`, when such language is accurate
+
+Avoid leading with:
+
+- raw object-database trivia
+- refs, trees, blobs, and OIDs unless the operator actually needs them
+
+Every human CLI command must also support `--json`.
+
+In `--json` mode:
+
+- human-readable text should be suppressed
+- stdout should carry only the structured result payload
+- stderr should carry warnings and errors
+
+For the agent CLI, the automation contract is JSONL-first and should stay
+separate from the human `--json` surface.
+
+## Git Workflow
+
+Prefer small, honest commits.
+
+Do not rewrite shared history casually.
+Prefer additive commits over history surgery.
+Prefer merges over rebases for shared collaboration unless there is a compelling,
+explicitly discussed reason otherwise.
+
+The point is not aesthetic Git history. The point is trustworthy collaboration.
+
+## What To Read First
+
+Before making non-trivial changes, read:
+
+- [README.md](./README.md)
+- [WORKFLOW.md](./WORKFLOW.md)
+- [STATUS.md](./STATUS.md)
+- [ROADMAP.md](./ROADMAP.md)
+- [docs/legends/README.md](./docs/legends/README.md)
+- [docs/invariants/README.md](./docs/invariants/README.md)
+- [docs/BACKLOG/README.md](./docs/BACKLOG/README.md)
+- [docs/design/README.md](./docs/design/README.md)
+- [docs/design/0001-m18-relay-agent-cli.md](./docs/design/0001-m18-relay-agent-cli.md)
+- [docs/API.md](./docs/API.md)
+- [docs/RELEASE.md](./docs/RELEASE.md)
+- [COMPLETED_TASKS.md](./COMPLETED_TASKS.md)
+- [CODE-EVAL.md](./CODE-EVAL.md)
+
+## Decision Rule
+
+When in doubt:
+
+- choose more trustworthy behavior
+- choose clearer boundaries
+- choose lower ceremony
+- choose fewer hidden behaviors
+- choose deterministic outputs
+- choose main as the playback truth
+- choose behavior over architecture theater
+- protect the human path from unnecessary sophistication
+- protect the agent path from ambiguity
diff --git a/ROADMAP.md b/ROADMAP.md
index 8c8a5d5..97efbf5 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,19 +1,64 @@
-# @git-stunts/cas — ROADMAP
+# @git-stunts/git-cas — ROADMAP
 
-This document tracks the real current state of `git-cas` and the sequenced work that remains.
-Completed milestone detail lives in [COMPLETED_TASKS.md](./COMPLETED_TASKS.md). Superseded work
-lives in [GRAVEYARD.md](./GRAVEYARD.md).
+This document tracks the real current state of `git-cas` and the sequenced work
+that remains.
 
-## Current Reality
+Fresh planning now follows [WORKFLOW.md](./WORKFLOW.md), not roadmap-first
+milestone writing.
 
-- **Current release:** `v5.3.2` (2026-03-15)
-- **Current line:** M16 Capstone shipped in `v5.3.0`; `v5.3.1` fixed repeated-chunk tree emission for repetitive content; `v5.3.2` stabilized test/runtime tooling; `v5.3.3` is the remaining M17 Ledger closeout in flight.
-- **Supported runtimes:** Node.js 22.x (primary), Bun, Deno
-- **Current operator experience:** the human-facing CLI/TUI is shipped now; the machine-facing agent CLI is planned next.
+That means this file is now:
+
+- sequence context
+- release-line context
+- migration context
+
+It is not the primary source of truth for new cycle planning.
 
-## Interface Strategy
+It now follows the workflow defined in [CONTRIBUTING.md](./CONTRIBUTING.md):
 
-`git-cas` now has an explicit two-surface direction:
+- sponsor user
+- sponsor agent
+- hills
+- playback questions
+- explicit non-goals
+- design docs first, tests second, implementation third
+
+`main` is the playback truth. If code lands out of order, the roadmap adjusts to
+match reality instead of pretending the original sequence still happened.
+
+Completed milestone detail lives in [COMPLETED_TASKS.md](./COMPLETED_TASKS.md).
+Superseded work lives in [GRAVEYARD.md](./GRAVEYARD.md).
+
+## Current Reality
+
+- **Last tagged release:** `v5.3.2` (`2026-03-15`)
+- **Current package version on `main`:** `v5.3.3`
+- **Supported runtimes:** Node.js 22.x (primary), Bun, Deno
+- **Human surface reality:** the human CLI/TUI is already substantial and now
+  includes early repo-explorer work that belongs closer to the later UX line
+  than to M17 closeout.
+- **Agent surface reality:** there is still no first-class `git cas agent`
+  contract. The main product gap is machine-facing determinism, not human
+  surface richness.
+- **M17 reality:** the M17 closeout work is materially present on `main`
+  (`CODEOWNERS`, release verification, test conventions, property coverage),
+  even though release bookkeeping and docs drifted.
+- **Next deliberate focus:** the next few cycles are agent-first. The human
+  surface should now follow the application boundaries that fall out of the
+  machine surface, not the other way around.
+
+## Product Doctrine
+
+- Git is the substrate, not the product.
+- Integrity is sacred.
+- Restore must be deterministic.
+- Provenance matters.
+- Verification matters.
+- Human CLI/TUI and agent CLI are separate surfaces over one shared domain core.
+- The default human UX should stay boring and trustworthy.
+- The default machine UX should stay deterministic and replayable.
+
+## Two-Surface Strategy
 
 ### Human CLI/TUI
 
@@ -21,233 +66,282 @@ This is the current public operator surface.
 
 - Existing `git cas ...` commands remain the stable human workflow.
 - Bijou formatting, prompts, dashboards, and TTY-aware behavior stay here.
-- `--json` remains supported as convenience structured output for humans and simple scripts.
-- Human-facing improvements continue under the Bijou/TUI roadmap.
+- The human `--json` flag remains convenience structured output for humans and
+  simple scripts.
+- Future human-surface work should reuse shared app-layer behavior instead of
+  inventing parallel logic in the TUI.
 
 ### Agent CLI
 
-This is planned work starting in **M18 Relay**.
+This is now the priority surface.
 
 - Namespace: `git cas agent`
-- Output: JSONL on `stdout` only, one record per line
-- No Bijou formatting, no TTY-mode branching, no implicit prompts
-- Stable event envelope: `protocol`, `command`, `type`, `seq`, `ts`, `data`
-- Reserved record types: `start`, `progress`, `warning`, `needs-input`, `result`, `error`, `end`
-- One-shot commands in v1: stream records during execution, then exit
-- Non-interactive secret/input handling:
-  - missing required input -> emit `needs-input`, exit `2`
-  - fatal execution failure -> emit `error`, exit `1`
-  - integrity/verification failure -> exit `3`
-  - success -> exit `0`
-- Request input supports normal flags plus `--request -` and `--request @file.json`
-
-The agent CLI is a first-class workflow, not an extension of the human `--json` mode.
-
-## Shipped Summary
-
-| Version | Milestone | Codename | Theme | Status |
-|---------|-----------|----------|-------|--------|
-| v3.1.0 | M13 | Bijou | TUI dashboard and animated progress | ✅ Shipped |
-| v4.0.0 | M14 | Conduit | Streaming restore, observability, parallel chunk I/O | ✅ Shipped |
-| v4.0.1 | M8 + M9 | Spit Shine + Cockpit | Review hardening, `verify`, `--json`, CLI polish | ✅ Shipped |
-| v5.0.0 | M10 | Hydra | Content-defined chunking | ✅ Shipped |
-| v5.1.0 | M11 | Locksmith | Envelope encryption and recipient management | ✅ Shipped |
-| v5.2.0 | M12 | Carousel | Key rotation without re-encrypting data | ✅ Shipped |
-| v5.3.0 | M16 | Capstone | Audit remediation and security hardening | ✅ Shipped |
-| v5.3.1 | — | Maintenance | Repeated-chunk tree integrity fix | ✅ Shipped |
-| v5.3.2 | — | Maintenance | Vitest workspace split, CLI version sync, and runtime/tooling stabilization | ✅ Shipped |
+- Output: JSONL on `stdout`, one protocol record per line
+- `stderr`: structured warnings and errors only
+- No TTY branching, no implicit prompts, no Bijou rendering
+- Stable record envelope: `protocol`, `command`, `type`, `seq`, `ts`, `data`
+- Reserved record types: `start`, `progress`, `warning`, `needs-input`,
+  `result`, `error`, `end`
+- Missing required input emits `needs-input` and exits with a distinct code
+- Integrity and verification failures get their own exit-code semantics
+- The agent CLI is a first-class workflow, not an extension of the human
+  `--json` path
+
+## Honest State of `main`
+
+### Human Surface
+
+What is already true on `main`:
+
+- chunked Git-backed storage, restore, verify, encryption, recipients, and
+  rotation are already shipped in the domain/library
+- the vault workflow is real and GC-safe
+- diagnostics and release verification already exist
+- the TUI has already moved beyond a simple vault inspector into a richer
+  repository explorer with refs browsing, source inspection, treemap views, and
+  a stronger theme layer
+
+This means the human surface is no longer the thing waiting to become real. It
+is already real and ahead of the planning docs.
+
+### Agent Surface
+
+What is still missing:
+
+- a first-class machine runner
+- a JSONL protocol contract
+- exact machine-facing exit-code semantics
+- non-interactive input handling as a core design constraint
+- parity for the operational command set without scraping human CLI output
+
+This is the current product bottleneck.
+
+## Tagged Releases
+
+| Version  | Milestone     | Theme                                                                   | Status    |
+| -------- | ------------- | ----------------------------------------------------------------------- | --------- |
+| `v5.3.2` | Maintenance   | Vitest workspace split, CLI version sync, runtime/tooling stabilization | ✅ Tagged |
+| `v5.3.1` | Maintenance   | Repeated-chunk tree integrity fix                                       | ✅ Tagged |
+| `v5.3.0` | M16 Capstone  | Audit remediation and security hardening                                | ✅ Tagged |
+| `v5.2.0` | M12 Carousel  | Key rotation without re-encrypting data                                 | ✅ Tagged |
+| `v5.1.0` | M11 Locksmith | Envelope encryption and recipient management                            | ✅ Tagged |
+| `v5.0.0` | M10 Hydra     | Content-defined chunking                                                | ✅ Tagged |
+| `v4.0.1` | M8 + M9       | Review hardening, `verify`, `--json`, CLI polish                        | ✅ Tagged |
+| `v4.0.0` | M14 Conduit   | Streaming restore, observability, parallel chunk I/O                    | ✅ Tagged |
+| `v3.1.0` | M13 Bijou     | TUI dashboard and animated progress                                     | ✅ Tagged |
 
 Older history remains in [CHANGELOG.md](./CHANGELOG.md).
 
-## Planned Release Sequence
-
-| Version | Milestone | Codename | Theme | Status |
-|---------|-----------|----------|-------|--------|
-| v5.3.3 | M17 | Ledger | Planning and ops reset | 📝 Planned |
-| v5.4.0 | M18 | Relay | LLM-native CLI foundation | 📝 Planned |
-| v5.5.0 | M19 | Nouveau | Bijou v3 human UX refresh | 📝 Planned |
-| v5.6.0 | M20 | Sentinel | Vault health and safety | 📝 Planned |
-| v5.7.0 | M21 | Atelier | Vault ergonomics and publishing | 📝 Planned |
-| v5.8.0 | M22 | Cartographer | Repo intelligence and change analysis | 📝 Planned |
-| v5.9.0 | M23 | Courier | Artifact sets and transfer | 📝 Planned |
-| v5.10.0 | M24 | Spectrum | Storage and observability extensibility | 📝 Planned |
-| v5.11.0 | M25 | Bastion | Enterprise key management research | 📝 Planned |
-
-## Dependency Sequence
-
-```text
-M16 Capstone + v5.3.1/v5.3.2 maintenance ✅
-                |
-            M17 Ledger
-                |
-            M18 Relay
-                |
-           M19 Nouveau
-                |
-           M20 Sentinel
-                |
-            M21 Atelier
-                |
-         M22 Cartographer
-                |
-           M23 Courier
-                |
-          M24 Spectrum
-                |
-           M25 Bastion
-```
-
-This sequence is intentionally linear. It forces the docs/ops reset first, then the machine
-interface split, then the human TUI refresh, and only then the broader feature expansion.
+## Untagged `main` Line
+
+The current `main` branch is ahead of the last tagged release.
+
+It currently includes:
+
+- the M17 closeout work that was previously tracked as pending
+- package version `5.3.3`
+- early human-surface repo-explorer work that landed ahead of the old planned
+  sequence
+
+The roadmap therefore treats the next planning cycle as a recentering cycle,
+not as a continuation of stale milestone fiction.
+
+## Near-Term Priority Stack
+
+1. **M18 Relay foundation**
+   Build the first credible agent contract.
+2. **Relay follow-through**
+   Stay agent-first until the machine surface can handle core workflows without
+   scraping or prompting.
+3. **M19 Nouveau**
+   Resume major human-surface work only after the agent surface has forced
+   cleaner application boundaries.
 
 ## Open Milestones
 
-### M17 — Ledger (`v5.3.3`)
+### M18 — Relay (`v5.4.0` target)
+
+**Theme:** first-class agent CLI foundation.
+
+**Sponsor user**
+
+- A maintainer or release engineer who wants to automate `git-cas` operations
+  without scraping terminal text.
+
+**Sponsor agent**
+
+- A coding agent, CI job, release bot, or backup workflow that needs exact,
+  replayable outcomes and explicit side effects.
+
+**Hills**
+
+- A sponsor agent can inspect, verify, and query `git-cas` state through a
+  stable JSONL protocol without depending on TTY behavior or human-readable
+  formatting.
+- A sponsor user can trust automation built on `git-cas` because failures,
+  warnings, and requested inputs are explicit and machine-actionable.
+
+**Playback questions**
+
+- Can an agent complete `inspect`, `verify`, `vault list`, `vault info`,
+  `vault history`, `doctor`, and `vault stats` without scraping prose?
+- Are protocol records ordered, typed, and stable across Node, Bun, and Deno?
+- Does `stdout` remain pure protocol output after the first record?
+- Are missing inputs and integrity failures distinguished cleanly by both record
+  type and exit code?
+
+**Explicit non-goals**
 
-**Theme:** planning and operational reset after Capstone.
+- No long-lived session protocol.
+- No TUI redesign.
+- No attempt to turn the human `--json` path into the automation contract.
+- No binary restore payload over protocol `stdout`.
 
-Deliverables:
+**Work order**
 
-- Close M16 in docs and reconcile [ROADMAP.md](./ROADMAP.md), [STATUS.md](./STATUS.md), and the shipped version history.
-- Add `CODEOWNERS` or equivalent review-assignment automation.
-- Document Git tree filename ordering semantics in test conventions to prevent future false positives.
-- Define a release-prep workflow for `CHANGELOG` updates and version bump timing.
-- Automate test-count injection into release notes or changelog prep.
-- Add property-based fuzz coverage for envelope-encryption round-trips.
+1. Write the agent protocol design doc.
+2. Write contract tests for record order, shapes, `stdout` purity, `stderr`
+   behavior, and exit codes.
+3. Implement a dedicated machine runner.
+4. Ship read-heavy parity first:
+   `agent inspect`, `agent verify`, `agent vault list`, `agent vault info`,
+   `agent vault history`, `agent doctor`, `agent vault stats`.
 
-### M18 — Relay (`v5.4.0`)
+**Acceptance**
 
-**Theme:** first-class LLM-native CLI.
+- The protocol contract is documented in-repo.
+- The read-heavy agent commands are JSONL-first and non-interactive.
+- Contract tests pass on Node, Bun, and Deno.
+- The human CLI continues to work unchanged outside explicitly shared internals.
 
-Deliverables:
+### Relay Follow-through (`v5.5.0` target)
 
-- Introduce `git cas agent` as a separate machine-facing namespace.
-- Add a dedicated machine command runner instead of extending the current human `runAction()` path.
-- Define and implement the JSONL envelope contract:
-  `protocol`, `command`, `type`, `seq`, `ts`, `data`.
-- Implement reserved record types:
-  `start`, `progress`, `warning`, `needs-input`, `result`, `error`, `end`.
-- Enforce non-interactive behavior for secrets and missing inputs.
-- Support flags plus `--request -` / `--request @file.json`.
-- Deliver parity for:
-  `agent store`, `agent tree`, `agent inspect`, `agent restore`, `agent verify`,
-  `agent vault list`, `agent vault info`, `agent vault history`.
-- Publish contract docs with exact exit-code behavior.
+**Theme:** bring the agent surface to operational parity before more large
+human-surface pushes.
 
-Acceptance:
+**Sponsor user**
 
-- JSONL contract tests must verify record order, record shapes, `stdout` purity, `stderr` silence after protocol start, and exit codes on Node, Bun, and Deno.
+- A maintainer who wants to wire `git-cas` into repeatable backup, restore,
+  publish, or release flows.
 
-### M19 — Nouveau (`v5.5.0`)
+**Sponsor agent**
 
-**Theme:** Bijou v3 refresh for the human-facing experience.
+- An autonomous system that must perform state-changing workflows end-to-end
+  with explicit inputs and replayable outcomes.
 
-Deliverables:
+**Hills**
 
-- Upgrade `@flyingrobots/bijou`, `@flyingrobots/bijou-node`, and `@flyingrobots/bijou-tui` to `3.0.0`.
-- Add `@flyingrobots/bijou-tui-app` for the refreshed shell.
-- Move inspector/dashboard rendering onto the v3 `ViewOutput` contract.
-- Split the current inspector into sub-apps for list, detail, history, and health panes.
-- Add BCSS-driven responsive styling and layout presets.
-- Add motion for focus shifts, pane changes, and shell transitions where it improves legibility.
-- Add session restore for the human TUI layout.
-- Replace the current low-fidelity heatmap/detail composition with a higher-fidelity surface-native view.
+- A sponsor agent can complete the core `git-cas` operational loop
+  non-interactively: store, restore, rotate, recipient management, and vault
+  administration.
+- A sponsor user can build automation on top of `git-cas` without needing a
+  human escape hatch for normal success paths.
 
-Acceptance:
+**Playback questions**
 
-- Existing human CLI behavior stays stable outside the refreshed TUI.
-- PTY smoke coverage must exercise inspect/dashboard navigation, filtering, resize, pane composition, and non-TTY fallback.
+- Can an agent complete encrypted store and restore flows without prompting?
+- Are passphrase files, request payloads, and missing-input branches explicit?
+- Are state-changing side effects obvious in protocol output?
+- Can agents reason about failures without parsing human error text?
 
-### M20 — Sentinel (`v5.6.0`)
+**Explicit non-goals**
 
-**Theme:** vault health, crypto hygiene, and safety workflows.
+- No long-lived interactive agent session.
+- No human-surface expansion that bypasses the shared command/model layer.
+- No hidden convenience prompting in the machine path.
 
-Deliverables:
+**Work order**
 
-- `git cas vault status`
-- `git cas gc`
-- `encryptionCount` auto-rotation policy
-- `.casrc` KDF parameter tuning with safe validation
-- Human CLI warnings for nonce budget and KDF health
-- Agent CLI warnings/results for the same health signals
+1. Extend the design doc to cover write flows and input request semantics.
+2. Extend contract tests to state-changing commands and failure branches.
+3. Implement:
+   `agent store`, `agent tree`, `agent restore`, `agent rotate`,
+   `agent recipient ...`, and the vault write flows that belong in the machine
+   surface.
+4. Add structured warnings for safety and policy signals that agents can act on.
 
-### M21 — Atelier (`v5.7.0`)
+**Acceptance**
 
-**Theme:** vault ergonomics and publishing workflows.
+- Core state-changing workflows are machine-accessible without prompting.
+- Input request behavior is explicit and documented.
+- Cross-runtime contract tests cover both read and write paths.
+- The machine surface is credible enough to become the app-layer reference for
+  later human-surface work.
 
-Deliverables:
+### M19 — Nouveau (after Relay is credible)
 
-- Named vaults
-- `git cas vault add` to adopt existing trees
-- Vault export flows:
-  - whole vault export
-  - single-entry export
-  - bulk export
-- Publish flows:
-  - publish to working tree
-  - publish to branch
-  - auto-publish hook support
-- File-level `--passphrase` CLI for standalone encrypted store flows
+**Theme:** human UX refresh on top of agent-native application boundaries.
 
-### M22 — Cartographer (`v5.8.0`)
+Some groundwork has already landed on `main`:
 
-**Theme:** repo intelligence and artifact comparison.
+- repo explorer shell
+- refs browser
+- source inspection
+- treemap atlas and drilldown
+- stronger theme and motion work
 
-Deliverables:
+That work should now be treated as input, not as permission to keep pushing the
+human surface ahead of the machine surface.
 
-- Duplicate-detection warnings during store
-- `git cas scan` / dedup advisor
-- Manifest diff engine
-- Machine diff stream for the agent CLI
-- Human compare view layered on the M19 shell
+**Sponsor user**
 
-### M23 — Courier (`v5.9.0`)
+- An operator who wants to inspect, understand, and recover artifact state with
+  less uncertainty and less CLI memorization.
 
-**Theme:** artifact sets and transport.
+**Sponsor agent**
 
-Deliverables:
+- An agent that benefits when the human surface reuses the same shared
+  application operations instead of bespoke TUI behavior.
 
-- Snapshot trees for directory-level store and restore
-- Portable bundles for air-gap transfer
-- Watch mode built on snapshot-root semantics rather than ad hoc per-file state
+**Hill**
 
-### M24 — Spectrum (`v5.10.0`)
+- The human surface becomes easier to trust because it sits on top of cleaner,
+  explicit app-layer behavior that was first forced into shape by the agent CLI.
 
-**Theme:** storage and observability extensibility.
+**Explicit non-goals**
 
-Deliverables:
+- No bespoke TUI-only behavior that bypasses shared command/model boundaries.
+- No large human-surface push before Relay and Relay follow-through are credible.
 
-- `CompressionPort`
-- Additional codecs: `zstd`, `brotli`, `lz4`
-- Prometheus/OpenTelemetry adapter for `ObservabilityPort`
+## Later Lines
 
-### M25 — Bastion (`v5.11.0`)
+The later roadmap remains directionally the same, but detailed scoping stays
+light until the agent-first line is delivered.
 
-**Theme:** enterprise key-management research with hard exit criteria.
+| Line         | Theme                                              |
+| ------------ | -------------------------------------------------- |
+| Sentinel     | Vault health, crypto hygiene, and safety workflows |
+| Atelier      | Vault ergonomics and publishing workflows          |
+| Cartographer | Repo intelligence and artifact comparison          |
+| Courier      | Artifact sets and transport                        |
+| Spectrum     | Storage and observability extensibility            |
+| Bastion      | Enterprise key-management research                 |
 
-Deliverables:
+## Cycle Delivery Rules
 
-- ADR for external key-management support
-- Threat model for HSM/Vault-backed key flows
-- Proof-of-concept `KeyManagementPort` adapter
-- Decision memo on whether enterprise key management should become a product milestone
+Every cycle follows the repository workflow discipline:
 
-## Delivery Standards
+1. design docs first
+2. tests as spec second
+3. implementation third
+4. retrospective after delivery
+5. update `docs/BACKLOG/` with follow-on work and debt
+6. rewrite the root README to reflect reality when needed
+7. update the root changelog
 
-Every planned milestone follows the repository release discipline:
+Additional release discipline:
 
-- Human CLI/TUI behavior remains backward compatible unless a release explicitly declares otherwise.
-- The human `--json` flag remains convenience output, not the automation contract.
-- The first machine interface release is JSONL-only and one-shot; no session protocol is planned before the contract proves useful.
-- `agent restore` writes to the filesystem in v1; binary payloads do not share protocol `stdout`.
-- Any user-visible feature added after M18 must include:
-  - at least one human CLI/TUI test, and
-  - at least one agent-protocol test when the feature is exposed to the machine surface.
+- tagged releases reflect reality, not aspiration
+- the human `--json` flag remains convenience output, not the automation
+  contract
+- the machine surface stays JSONL-first and one-shot until a stronger protocol
+  is justified by playback
 
 ## Document Boundaries
 
 - [ROADMAP.md](./ROADMAP.md): current reality plus future sequence
 - [STATUS.md](./STATUS.md): compact project snapshot
+- [WORKFLOW.md](./WORKFLOW.md): planning and delivery source of truth for fresh work
 - [COMPLETED_TASKS.md](./COMPLETED_TASKS.md): shipped milestone details
 - [GRAVEYARD.md](./GRAVEYARD.md): superseded or merged-away work
 - [CHANGELOG.md](./CHANGELOG.md): release-by-release history
diff --git a/STATUS.md b/STATUS.md
index a545122..fe23c33 100644
--- a/STATUS.md
+++ b/STATUS.md
@@ -1,85 +1,96 @@
-# @git-stunts/cas — Project Status
+# @git-stunts/git-cas — Project Status
 
-**Current release:** `v5.3.2`
-**Current branch version:** `v5.3.3`
-**Last release:** `2026-03-15`
-**Current line:** M16 Capstone shipped in `v5.3.0`; `v5.3.1` fixed repeated-chunk tree emission; `v5.3.2` stabilized test/runtime tooling; `v5.3.3` is the remaining M17 closeout in flight.
+**Last tagged release:** `v5.3.2` (`2026-03-15`)
+**Current package version on `main`:** `v5.3.3`
+**Playback truth:** `main`
 **Runtimes:** Node.js 22.x, Bun, Deno
+**Current strategic focus:** agent-first for the next few cycles
+**Fresh planning workflow:** [WORKFLOW.md](./WORKFLOW.md)
 
 ---
 
-## Interface Strategy
+`STATUS.md` remains a compact snapshot, but new planning now starts from
+`WORKFLOW.md`, legends, backlog items, invariants, and cycle docs.
 
-- **Human CLI/TUI:** the current public operator surface. Existing `git cas ...` commands, Bijou formatting, prompts, dashboards, and `--json` convenience output stay here.
-- **Agent CLI:** planned next as `git cas agent`. It will be JSONL-first, non-interactive by default, and independent from Bijou rendering or TTY-only behavior.
+## Honest State
+
+- The human CLI/TUI is already real and ahead of the old planning docs.
+- M17 closeout work is materially on `main`, even though the release/docs
+  bookkeeping drifted.
+- Early repo-explorer and TUI refresh work also landed on `main` ahead of the
+  old sequence.
+- The biggest product gap is now the missing first-class agent CLI.
+
+---
+
+## Two Surfaces
+
+- **Human CLI/TUI:** stable operator surface, boring by default, `--json` kept
+  as convenience structured output for humans and simple scripts.
+- **Agent CLI:** next priority surface, JSONL-first, non-interactive, and
+  separate from the human `--json` path.
 
 ---
 
-## Recently Shipped
+## Current Hills
+
+### Human Hill
 
-| Version | Milestone | Highlights |
-|---------|-----------|------------|
-| `v5.3.2` | Maintenance | Vitest workspace split for deterministic integration runs; CLI version sync; test/runtime tooling stabilization |
-| `v5.3.1` | Maintenance | Repeated-chunk tree integrity fix; unique chunk tree entries; `git fsck` regression coverage |
-| `v5.3.0` | M16 Capstone | Audit remediation, `.casrc`, passphrase-file support, restore guards, `encryptionCount`, lifecycle rename |
-| `v5.2.0` | M12 Carousel | Key rotation without re-encrypting data |
-| `v5.1.0` | M11 Locksmith | Envelope encryption and recipient management |
-| `v5.0.0` | M10 Hydra | Content-defined chunking |
-| `v4.0.1` | M8 + M9 | Review hardening, `verify`, `--json`, CLI polish |
-| `v4.0.0` | M14 Conduit | Streaming restore, observability, parallel chunk I/O |
-| `v3.1.0` | M13 Bijou | Interactive dashboard and animated progress |
+A human operator can store, inspect, verify, restore, and manage artifacts with
+confidence and without memorizing Git plumbing.
 
-Milestone labels are thematic and non-sequential; the versions above are listed in release order.
+### Agent Hill
+
+A coding agent, CI job, or release bot can execute core `git-cas` workflows
+through a stable machine contract without scraping prose or depending on TTY
+behavior.
 
 ---
 
 ## Next Up
 
-### M17 — Ledger (`v5.3.3`)
+### M18 — Relay (`v5.4.0` target)
+
+**Sponsor user**
+
+- Maintainer or release engineer building automation around `git-cas`
+
+**Sponsor agent**
+
+- Coding agent, CI job, release bot, or backup workflow
 
-Planning and ops reset:
+**Hill**
 
-- Reconcile `ROADMAP.md`, `STATUS.md`, and release messaging
-- Add review automation (`CODEOWNERS` or equivalent)
-- Document Git tree ordering test conventions
-- Define release-prep workflow for changelog/version timing
-- Automate test-count injection into release notes or changelog prep
-- Add property-based fuzz coverage for envelope encryption
+- Read-heavy `git-cas` operations become available through a first-class
+  JSONL-first machine protocol with explicit exit-code semantics.
 
-### M18 — Relay (`v5.4.0`)
+**Immediate work order**
 
-LLM-native CLI foundation:
+1. protocol design doc
+2. contract tests
+3. dedicated machine runner
+4. read-heavy command parity
 
-- Introduce `git cas agent`
-- Define the JSONL protocol envelope and exit codes
-- Add machine-facing parity for the current operational command set
-- Enforce strict non-interactive input handling
+### Relay Follow-through (`v5.5.0` target)
 
-### M19 — Nouveau (`v5.5.0`)
+- Stay agent-first until state-changing flows are also credible for automation.
 
-Human UX refresh:
+### M19 — Nouveau (after Relay is credible)
 
-- Upgrade Bijou packages to `3.0.0`
-- Move the inspector shell to the v3 `ViewOutput` model
-- Split the dashboard into sub-apps
-- Add better styling, motion, layout persistence, and richer heatmap/detail rendering
+- Resume major human-surface work only after the agent surface has forced
+  cleaner app-layer boundaries.
 
 ---
 
-## Sequenced Roadmap
+## Sequence Snapshot
 
-| Version | Milestone | Theme |
-|---------|-----------|-------|
-| `v5.3.3` | M17 Ledger | Planning and ops reset |
-| `v5.4.0` | M18 Relay | LLM-native CLI foundation |
-| `v5.5.0` | M19 Nouveau | Bijou v3 human UX refresh |
-| `v5.6.0` | M20 Sentinel | Vault health and safety |
-| `v5.7.0` | M21 Atelier | Vault ergonomics and publishing |
-| `v5.8.0` | M22 Cartographer | Repo intelligence and change analysis |
-| `v5.9.0` | M23 Courier | Artifact sets and transfer |
-| `v5.10.0` | M24 Spectrum | Storage and observability extensibility |
-| `v5.11.0` | M25 Bastion | Enterprise key-management research |
+| Order | Focus                                                       |
+| ----- | ----------------------------------------------------------- |
+| Now   | Relay foundation                                            |
+| Next  | Relay follow-through                                        |
+| Then  | Nouveau                                                     |
+| Later | Sentinel, Atelier, Cartographer, Courier, Spectrum, Bastion |
 
 ---
 
-*Future details: [ROADMAP.md](./ROADMAP.md) | Shipped detail: [COMPLETED_TASKS.md](./COMPLETED_TASKS.md) | Superseded: [GRAVEYARD.md](./GRAVEYARD.md)*
+_Future detail: [ROADMAP.md](./ROADMAP.md) | Shipped detail: [COMPLETED_TASKS.md](./COMPLETED_TASKS.md) | Release history: [CHANGELOG.md](./CHANGELOG.md)_
diff --git a/WORKFLOW.md b/WORKFLOW.md
new file mode 100644
index 0000000..424caaf
--- /dev/null
+++ b/WORKFLOW.md
@@ -0,0 +1,137 @@
+# Git-CAS Workflow
+
+_The planning and delivery model for `git-cas`_
+
+## Planning Model
+
+`git-cas` now plans new work through:
+
+- **Legends**
+  - broad thematic efforts such as Relay, Nouveau, Sentinel, or Atelier
+- **Cycles**
+  - short design and implementation loops focused on one deliverable
+- **Backlog items**
+  - single-file work items that can be rough, partial, or speculative
+- **Invariants**
+  - project-wide truths that design and implementation are not allowed to
+    violate
+
+This is a forward-looking workflow change.
+
+Older milestone language can remain in historical docs where useful for release
+history, but new planning should start from legends, cycles, backlog items, and
+invariants instead.
+
+## Directory Model
+
+- `docs/legends/`
+  - one document per legend
+- `docs/BACKLOG/`
+  - one file per backlog item
+- `docs/design/`
+  - active and landed cycle design docs
+- `docs/invariants/`
+  - explicit project-wide invariants
+- `test/cycles/<cycle>/`
+  - cycle-owned playback, regression, and spec tests
+
+This repo uses `test/`, not `tests/`, so cycle-owned tests live under
+`test/cycles/`.
+
+## Naming Conventions
+
+### Backlog Items
+
+Backlog items are named:
+
+`<Legend code>-<numerical identifier>-<name>.md`
+
+Example:
+
+`RL-001-recipient-lifecycle.md`
+
+### Cycle Docs
+
+Cycle docs use the same code and live in `docs/design/`.
+
+When a cycle begins:
+
+1. pick a backlog item
+2. move or copy that file into `docs/design/`
+3. enrich it with the information required to implement the cycle
+
+### Cycle Tests
+
+Cycle-owned tests live under:
+
+`test/cycles/<cycle>/`
+
+Package-local unit and integration tests can still live in the normal test
+locations when that is the better fit.
+
+## Required Design Sections
+
+Every active cycle design doc should include:
+
+- linked legend
+- human users, jobs, and hills
+- agent users, jobs, and hills
+- human playback
+- agent playback
+- linked invariants
+- implementation outline
+- tests to write first
+- risks and unknowns
+- retrospective
+
+Design here follows IBM Design Thinking twice:
+
+- once for humans
+- once for agents
+
+Agents are first-class users of `git-cas`, not a derived audience.
+
+## Cycle Workflow
+
+1. Design docs first, using the human and agent IBM Design Thinking passes.
+2. Tests are the spec. Write failing tests first.
+3. Green the tests.
+4. Run human and agent playbacks.
+5. Write a retrospective and assess drift.
+6. Update `docs/BACKLOG/` with debt, follow-on work, and new questions.
+7. Update [CHANGELOG.md](./CHANGELOG.md).
+8. Iterate through review until accepted.
+9. Merge and sync.
+10. Bump version or cut a release if needed.
+11. Triage the backlog and pick the next cycle.
+
+## Process Rules
+
+- No new milestone planning for fresh work.
+- No new roadmap-first planning artifacts for fresh work.
+- Legends deserve their own docs and should be linked when referenced.
+- Important project-wide invariants must be documented explicitly and linked
+  when referenced.
+- `main` is the playback truth when docs and branches drift.
+- Human CLI/TUI and agent CLI are separate surfaces over one shared core.
+- The human `--json` surface and the agent JSONL surface are not the same
+  contract.
+
+## Relationship To Existing Docs
+
+Some older documents still reflect the previous planning model:
+
+- [ROADMAP.md](./ROADMAP.md)
+- [STATUS.md](./STATUS.md)
+- legacy numeric cycle docs in `docs/design/`
+
+Those remain migration surfaces and historical context, not the source of truth
+for new planning work.
+
+The source of truth for new planning is:
+
+- this file
+- `docs/legends/`
+- `docs/BACKLOG/`
+- `docs/design/`
+- `docs/invariants/`
diff --git a/bin/actions.js b/bin/actions.js
index 35dea70..4745863 100644
--- a/bin/actions.js
+++ b/bin/actions.js
@@ -6,6 +6,7 @@
 
 /** @type {Readonly<Record<string, string>>} */
 const HINTS = {
+  INVALID_INPUT: 'Check the agent command name and required input fields',
   MISSING_KEY: 'Provide --key-file or --vault-passphrase',
   MANIFEST_NOT_FOUND: 'Verify the tree OID contains a manifest',
   VAULT_ENTRY_NOT_FOUND: "Run 'git cas vault list' to see available entries",
@@ -16,7 +17,10 @@ const HINTS = {
   RECIPIENT_NOT_FOUND: 'No recipient with that label exists in the manifest',
   RECIPIENT_ALREADY_EXISTS: 'A recipient with that label already exists',
   CANNOT_REMOVE_LAST_RECIPIENT: 'At least one recipient must remain in the manifest',
-  ROTATION_NOT_SUPPORTED: 'Key rotation requires envelope encryption — store with --recipient first',
+  ROTATION_NOT_SUPPORTED:
+    'Key rotation requires envelope encryption — store with --recipient first',
+  VAULT_METADATA_INVALID: 'Initialize an encrypted vault before rotating its passphrase',
+  VAULT_CONFLICT: 'Retry the vault rotation after concurrent vault updates settle',
 };
 
 /**
@@ -31,7 +35,9 @@ function writeError(err, json) {
   if (json) {
     /** @type {{ error: string, code?: string }} */
     const obj = { error: message };
-    if (code) { obj.code = code; }
+    if (code) {
+      obj.code = code;
+    }
     process.stderr.write(`${JSON.stringify(obj)}\n`);
   } else {
     const prefix = code ? `error [${code}]: ` : 'error: ';
@@ -62,7 +68,9 @@ function getHint(code) {
  * @returns {Promise<void>}
  */
 function defaultDelay(ms) {
-  return new Promise((resolve) => { setTimeout(resolve, ms); });
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
 }
 
 /**
@@ -73,10 +81,16 @@ function defaultDelay(ms) {
  * @param {{ delay?: (ms: number) => Promise<void>, setExitCode?: (code: number) => void }} [options] - Injectable dependencies.
  * @returns {(...args: any[]) => Promise<void>} Wrapped action.
  */
-export function runAction(fn, getJson, {
-  delay = defaultDelay,
-  setExitCode = (code) => { process.exitCode = code; },
-} = {}) {
+export function runAction(
+  fn,
+  getJson,
+  {
+    delay = defaultDelay,
+    setExitCode = (code) => {
+      process.exitCode = code;
+    },
+  } = {}
+) {
   return async (/** @type {any[]} */ ...args) => {
     try {
       await fn(...args);
diff --git a/bin/agent/cli.js b/bin/agent/cli.js
new file mode 100644
index 0000000..848c39d
--- /dev/null
+++ b/bin/agent/cli.js
@@ -0,0 +1,2087 @@
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import ContentAddressableStore from '../../index.js';
+import Manifest from '../../src/domain/value-objects/Manifest.js';
+import { createGitPlumbing } from '../../src/infrastructure/createGitPlumbing.js';
+import { buildVaultStats, inspectVaultHealth } from '../ui/vault-report.js';
+import { filterEntries } from '../ui/vault-list.js';
+import { AGENT_EXIT_CODES, createAgentSession, getAgentExitCode } from './protocol.js';
+
+const AVAILABLE_COMMANDS = Object.freeze([
+  'store',
+  'tree',
+  'restore',
+  'rotate',
+  'inspect',
+  'verify',
+  'doctor',
+  'recipient add',
+  'recipient remove',
+  'recipient list',
+  'vault init',
+  'vault list',
+  'vault info',
+  'vault history',
+  'vault remove',
+  'vault rotate',
+  'vault stats',
+]);
+
+const REQUEST_OPTION = { request: { type: 'string' } };
+const INPUT_ALIAS_MAP = Object.freeze({
+  passphrase: 'passphrase',
+  passphraseFile: 'passphrase-file',
+  keyFile: 'key-file',
+  oldKeyFile: 'old-key-file',
+  newKeyFile: 'new-key-file',
+  existingKeyFile: 'existing-key-file',
+  oldPassphrase: 'old-passphrase',
+  newPassphrase: 'new-passphrase',
+  oldPassphraseFile: 'old-passphrase-file',
+  newPassphraseFile: 'new-passphrase-file',
+  vaultPassphrase: 'vault-passphrase',
+  vaultPassphraseFile: 'vault-passphrase-file',
+});
+
+const START_REDACTED_FIELDS = new Set([
+  'passphrase',
+  'passphraseFile',
+  'keyFile',
+  'oldKeyFile',
+  'newKeyFile',
+  'existingKeyFile',
+  'oldPassphrase',
+  'newPassphrase',
+  'oldPassphraseFile',
+  'newPassphraseFile',
+  'vaultPassphrase',
+  'vaultPassphraseFile',
+]);
+
+const LOCAL_INPUT_ERROR_CODES = new Set(['ENOENT', 'EISDIR', 'ENOTDIR', 'EACCES', 'EPERM']);
+
+/**
+ * @param {string | undefined} requestSource
+ * @returns {'inline' | 'file' | 'stdin' | undefined}
+ */
+function normalizeRequestSourceKind(requestSource) {
+  if (!requestSource) {
+    return undefined;
+  }
+  if (requestSource === '-') {
+    return 'stdin';
+  }
+  if (requestSource.startsWith('@')) {
+    return 'file';
+  }
+  return 'inline';
+}
+
+/**
+ * @param {string | undefined} key
+ * @param {unknown} value
+ * @returns {{ handled: boolean, value?: unknown }}
+ */
+function sanitizeSpecialStartValue(key, value) {
+  if (!key) {
+    return { handled: false };
+  }
+
+  if (key.includes('-')) {
+    return { handled: true };
+  }
+
+  if (key === 'requestSource') {
+    return {
+      handled: true,
+      value: normalizeRequestSourceKind(/** @type {string | undefined} */ (value)),
+    };
+  }
+
+  if (key === 'manifest') {
+    return {
+      handled: true,
+      value: {
+        provided: true,
+        source: typeof value === 'string' ? 'file' : 'inline',
+      },
+    };
+  }
+
+  if (START_REDACTED_FIELDS.has(key)) {
+    return { handled: true, value: true };
+  }
+
+  return { handled: false };
+}
+
+/**
+ * @param {Record<string, unknown>} value
+ * @returns {Record<string, unknown>}
+ */
+function sanitizeStartObject(value) {
+  /** @type {Record<string, unknown>} */
+  const sanitized = {};
+  for (const [nestedKey, nestedValue] of Object.entries(value)) {
+    const safeValue = sanitizeStartValue(nestedKey, nestedValue);
+    if (safeValue !== undefined) {
+      sanitized[nestedKey] = safeValue;
+    }
+  }
+  return sanitized;
+}
+
+/**
+ * @param {unknown[]} value
+ * @returns {unknown[]}
+ */
+function sanitizeStartArray(value) {
+  return value
+    .map((entry) => sanitizeStartValue(undefined, entry))
+    .filter((entry) => entry !== undefined);
+}
+
+/**
+ * @param {string | undefined} key
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function sanitizeStartValue(key, value) {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const special = sanitizeSpecialStartValue(key, value);
+  if (special.handled) {
+    return special.value;
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return sanitizeStartArray(value);
+  }
+
+  if (value && typeof value === 'object') {
+    return sanitizeStartObject(/** @type {Record<string, unknown>} */ (value));
+  }
+
+  return value;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {string[]} fields
+ * @returns {Record<string, any>}
+ */
+function selectStartInput(input, fields) {
+  /** @type {Record<string, any>} */
+  const selected = {};
+  for (const field of fields) {
+    if (input[field] !== undefined) {
+      selected[field] = input[field];
+    }
+  }
+  return selected;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {Record<string, any>}
+ */
+function buildAgentStartData(input) {
+  const sanitized = sanitizeStartValue(undefined, input);
+  if (
+    sanitized &&
+    typeof sanitized === 'object' &&
+    !Array.isArray(sanitized) &&
+    Object.keys(sanitized).length > 0
+  ) {
+    return { input: sanitized };
+  }
+  return {};
+}
+
+/**
+ * @param {ReturnType<typeof createAgentSession>} session
+ * @param {Record<string, any>} input
+ */
+function writeAgentStart(session, input) {
+  session.writeStart(buildAgentStartData(input));
+}
+
+/**
+ * @param {unknown} err
+ * @param {string} label
+ * @param {string} filePath
+ * @returns {Error}
+ */
+function normalizeLocalInputError(err, label, filePath) {
+  const resolvedPath = path.resolve(filePath);
+
+  if (err instanceof SyntaxError) {
+    return invalidInput(`Invalid ${label}: ${resolvedPath}: ${err.message}`, {
+      filePath: resolvedPath,
+    });
+  }
+
+  if (typeof err === 'object' && err && typeof err.code === 'string') {
+    if (LOCAL_INPUT_ERROR_CODES.has(err.code)) {
+      return invalidInput(`Unable to read ${label}: ${resolvedPath}`, {
+        filePath: resolvedPath,
+        errorCode: err.code,
+      });
+    }
+  }
+
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} label
+ * @returns {Buffer}
+ */
+function readBinaryInputFile(filePath, label) {
+  try {
+    return readFileSync(filePath);
+  } catch (err) {
+    throw normalizeLocalInputError(err, label, filePath);
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} label
+ * @returns {string}
+ */
+function readTextInputFile(filePath, label) {
+  try {
+    return readFileSync(path.resolve(filePath), 'utf8');
+  } catch (err) {
+    throw normalizeLocalInputError(err, label, filePath);
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @returns {ContentAddressableStore}
+ */
+function createCas(cwd) {
+  const plumbing = createGitPlumbing({ cwd });
+  return new ContentAddressableStore({ plumbing });
+}
+
+/**
+ * @param {string} message
+ * @param {Record<string, any>} [meta]
+ * @returns {Error & { code: string, meta?: Record<string, any> }}
+ */
+function invalidInput(message, meta) {
+  const err = /** @type {Error & { code: string, meta?: Record<string, any> }} */ (
+    new Error(message)
+  );
+  err.code = 'INVALID_INPUT';
+  if (meta) {
+    err.meta = meta;
+  }
+  return err;
+}
+
+/**
+ * @param {string} message
+ * @param {Record<string, any>} [meta]
+ * @returns {Error & { code: string, meta?: Record<string, any> }}
+ */
+function needsInput(message, meta) {
+  const err = /** @type {Error & { code: string, meta?: Record<string, any> }} */ (
+    new Error(message)
+  );
+  err.code = 'NEEDS_INPUT';
+  if (meta) {
+    err.meta = meta;
+  }
+  return err;
+}
+
+/**
+ * @param {string | undefined} request
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function readRequestPayload(request, stdin) {
+  if (!request) {
+    return {};
+  }
+
+  let raw;
+  if (request === '-') {
+    raw = await readStream(stdin);
+  } else if (request.startsWith('@')) {
+    raw = readTextInputFile(request.slice(1), 'request payload file');
+  } else {
+    raw = request;
+  }
+
+  if (!raw.trim()) {
+    throw invalidInput('Agent request payload must not be empty');
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw invalidInput(
+      `Invalid JSON request payload: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw invalidInput('Agent request payload must be a JSON object');
+  }
+
+  return parsed;
+}
+
+/**
+ * @param {string} key
+ * @param {Record<string, { type: 'string' | 'boolean' }>} options
+ * @returns {{ type: 'string' | 'boolean' } | undefined}
+ */
+function resolveRequestOptionSpec(key, options) {
+  if (options[key]) {
+    return options[key];
+  }
+
+  const alias = INPUT_ALIAS_MAP[key];
+  if (alias && options[alias]) {
+    return options[alias];
+  }
+
+  return undefined;
+}
+
+/**
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function allowsStructuredRequestValue(key, value) {
+  return key === 'manifest' && Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * @param {string} key
+ * @param {unknown} value
+ * @param {{ type: 'string' | 'boolean' } | undefined} spec
+ */
+function validateRequestFieldType(key, value, spec) {
+  if (spec?.type === 'boolean' && typeof value !== 'boolean') {
+    throw invalidInput(`Request field "${key}" must be a boolean`);
+  }
+  if (spec?.type === 'string' && typeof value !== 'string' && !allowsStructuredRequestValue(key, value)) {
+    throw invalidInput(`Request field "${key}" must be a string`);
+  }
+}
+
+/**
+ * @param {Record<string, any>} request
+ * @param {Record<string, { type: 'string' | 'boolean' }>} options
+ * @returns {Record<string, any>}
+ */
+function normalizeRequestValues(request, options) {
+  /** @type {Record<string, any>} */
+  const normalized = {};
+
+  for (const [key, value] of Object.entries(request)) {
+    const spec = resolveRequestOptionSpec(key, options);
+    validateRequestFieldType(key, value, spec);
+    normalized[key] = value;
+  }
+
+  return normalized;
+}
+
+/**
+ * @param {NodeJS.ReadStream} stream
+ * @returns {Promise<string>}
+ */
+async function readStream(stream) {
+  if (typeof stream.setEncoding === 'function') {
+    stream.setEncoding('utf8');
+  }
+
+  let raw = '';
+  for await (const chunk of stream) {
+    raw += String(chunk);
+  }
+  return raw;
+}
+
+/**
+ * @param {string[]} args
+ * @param {Record<string, { type: 'string' | 'boolean' }>} options
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ values: Record<string, any>, positionals: string[], requestSource?: string }>}
+ */
+async function parseAgentInput(args, options, stdin) {
+  const optionSpec = {
+    ...options,
+    ...REQUEST_OPTION,
+  };
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      allowPositionals: true,
+      strict: true,
+      options: optionSpec,
+    });
+  } catch (err) {
+    throw invalidInput(err instanceof Error ? err.message : String(err));
+  }
+
+  const request = normalizeRequestValues(
+    await readRequestPayload(parsed.values.request, stdin),
+    optionSpec
+  );
+  const values = { ...request, ...parsed.values };
+  delete values.request;
+
+  return {
+    values,
+    positionals: parsed.positionals,
+    requestSource: parsed.values.request,
+  };
+}
+
+/**
+ * @param {string[]} positionals
+ * @param {string[]} names
+ * @returns {Record<string, string>}
+ */
+function assignPositionals(positionals, names) {
+  if (positionals.length > names.length) {
+    throw invalidInput(
+      `Unexpected positional arguments: ${positionals.slice(names.length).join(' ')}`
+    );
+  }
+
+  /** @type {Record<string, string>} */
+  const assigned = {};
+  names.forEach((name, index) => {
+    if (positionals[index] !== undefined) {
+      assigned[name] = positionals[index];
+    }
+  });
+  return assigned;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {Record<string, any>}
+ */
+function normalizeInputAliases(input) {
+  const normalized = { ...input };
+  for (const [key, alias] of Object.entries(INPUT_ALIAS_MAP)) {
+    normalized[key] = input[key] ?? input[alias];
+  }
+  return normalized;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {{ cwd: string, slug?: string, oid?: string }}
+ */
+function resolveTarget(input) {
+  if (input.slug && input.oid) {
+    throw invalidInput('Provide --slug or --oid, not both');
+  }
+  if (!input.slug && !input.oid) {
+    throw invalidInput('Provide --slug <slug> or --oid <tree-oid>');
+  }
+  return {
+    cwd: input.cwd || '.',
+    ...(input.slug ? { slug: input.slug } : {}),
+    ...(input.oid ? { oid: input.oid } : {}),
+  };
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {{ cwd: string, slug: string }}
+ */
+function resolveSlugTarget(input) {
+  if (!input.slug) {
+    throw invalidInput('Provide --slug <slug>');
+  }
+
+  return {
+    cwd: input.cwd || '.',
+    slug: input.slug,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function parsePositiveInteger(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) {
+    return value;
+  }
+
+  if (typeof value === 'string' && /^\d+$/.test(value)) {
+    const parsed = Number(value);
+    if (Number.isSafeInteger(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+
+  throw invalidInput('Expected a positive integer');
+}
+
+/**
+ * @param {{ cwd: string, slug?: string, oid?: string }} input
+ * @returns {Promise<{ cas: ContentAddressableStore, treeOid: string }>}
+ */
+async function resolveTree(input) {
+  const cas = createCas(input.cwd);
+  const treeOid = input.oid || (await cas.resolveVaultEntry({ slug: input.slug }));
+  return { cas, treeOid };
+}
+
+/**
+ * @param {string} keyFilePath
+ * @returns {Buffer}
+ */
+function readKeyFile(keyFilePath) {
+  const key = readBinaryInputFile(keyFilePath, 'key file');
+  if (key.length !== 32) {
+    throw invalidInput(`Invalid key length: expected 32 bytes, got ${key.length} (${keyFilePath})`);
+  }
+  return key;
+}
+
+/**
+ * @param {string} filePath
+ * @param {{ stdin?: NodeJS.ReadStream, onWarning?: (warning: Record<string, any>) => void }} [options]
+ * @returns {Promise<string>}
+ */
+async function readAgentPassphraseFile(filePath, { stdin, onWarning } = {}) {
+  if (filePath === '-') {
+    const raw = await readStream(stdin || process.stdin);
+    const trimmed = raw.replace(/\r?\n$/, '');
+    if (!trimmed) {
+      throw invalidInput('Passphrase must not be empty');
+    }
+    return trimmed;
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  try {
+    const stats = statSync(resolvedPath);
+    if (stats.mode & 0o077) {
+      onWarning?.({
+        code: 'INSECURE_FILE_PERMISSIONS',
+        message: `${resolvedPath} has insecure permissions`,
+        filePath: resolvedPath,
+        recommendation: 'chmod 600',
+      });
+    }
+  } catch {
+    // Let the file read raise the real error.
+  }
+
+  const trimmed = readTextInputFile(resolvedPath, 'passphrase file').replace(/\r?\n$/, '');
+  if (!trimmed) {
+    throw invalidInput('Passphrase must not be empty');
+  }
+
+  return trimmed;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {boolean}
+ */
+function hasVaultPassphraseSource(input) {
+  return input.vaultPassphraseFile !== undefined || input.vaultPassphrase !== undefined;
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateCredentialSources(input) {
+  if (input.vaultPassphrase !== undefined && input.vaultPassphraseFile) {
+    throw invalidInput('Provide --vault-passphrase or --vault-passphrase-file, not both');
+  }
+  if (input.keyFile && hasVaultPassphraseSource(input)) {
+    throw invalidInput('Provide --key-file or a vault passphrase source, not both');
+  }
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {string | undefined} requestSource
+ * @returns {Promise<string | undefined>}
+ */
+async function resolveVaultPassphrase(input, requestSource, options = {}) {
+  if (input.vaultPassphraseFile === '-' && requestSource === '-') {
+    throw invalidInput('Cannot read both request payload and vault passphrase from stdin');
+  }
+  if (input.vaultPassphraseFile) {
+    return await readAgentPassphraseFile(input.vaultPassphraseFile, options);
+  }
+  if (input.vaultPassphrase !== undefined) {
+    if (!String(input.vaultPassphrase).trim()) {
+      throw invalidInput('Passphrase must not be empty');
+    }
+    return input.vaultPassphrase;
+  }
+  return undefined;
+}
+
+/**
+ * @param {ContentAddressableStore} cas
+ * @param {NonNullable<Awaited<ReturnType<ContentAddressableStore['getVaultMetadata']>>>} metadata
+ * @param {string} passphrase
+ * @returns {Promise<Buffer>}
+ */
+async function deriveVaultKey(cas, metadata, passphrase) {
+  const { kdf } = metadata.encryption;
+  const { key } = await cas.deriveKey({
+    passphrase,
+    salt: Buffer.from(kdf.salt, 'base64'),
+    algorithm: kdf.algorithm,
+    iterations: kdf.iterations,
+    cost: kdf.cost,
+    blockSize: kdf.blockSize,
+    parallelization: kdf.parallelization,
+    keyLength: kdf.keyLength,
+  });
+  return key;
+}
+
+/**
+ * @param {import('../../index.js').default} cas
+ * @param {Record<string, any>} input
+ * @returns {Promise<Buffer | undefined>}
+ */
+async function resolveStoreEncryptionKey(cas, input, options = {}) {
+  validateCredentialSources(input);
+  if (input.keyFile) {
+    return readKeyFile(input.keyFile);
+  }
+  const passphrase = await resolveVaultPassphrase(input, input.requestSource, options);
+  if (!passphrase) {
+    return undefined;
+  }
+  const metadata = await cas.getVaultMetadata();
+  if (!metadata?.encryption?.kdf) {
+    throw invalidInput('Vault passphrase source is only valid for encrypted vaults');
+  }
+  return await deriveVaultKey(cas, metadata, passphrase);
+}
+
+/**
+ * @param {import('../../src/domain/value-objects/Manifest.js').default} manifest
+ * @returns {boolean}
+ */
+function hasEnvelopeRecipients(manifest) {
+  return (
+    Array.isArray(manifest.encryption?.recipients) && manifest.encryption.recipients.length > 0
+  );
+}
+
+/**
+ * @param {import('../../src/domain/value-objects/Manifest.js').default} manifest
+ * @param {Awaited<ReturnType<ContentAddressableStore['getVaultMetadata']>>} metadata
+ * @returns {string[]}
+ */
+function getRestoreRequiredInputs(manifest, metadata) {
+  if (hasEnvelopeRecipients(manifest)) {
+    return ['keyFile'];
+  }
+  if (metadata?.encryption?.kdf) {
+    return ['keyFile', 'vaultPassphrase', 'vaultPassphraseFile'];
+  }
+  return ['keyFile'];
+}
+
+/**
+ * @param {{
+ *   cas: ContentAddressableStore,
+ *   manifest: import('../../src/domain/value-objects/Manifest.js').default,
+ *   input: Record<string, any>,
+ *   requestSource?: string,
+ *   treeOid: string,
+ * }} options
+ * @returns {Promise<Buffer | undefined>}
+ */
+async function resolveRestoreEncryptionKey({ cas, manifest, input, requestSource, treeOid }) {
+  validateCredentialSources(input);
+  if (input.keyFile) {
+    return readKeyFile(input.keyFile);
+  }
+
+  const metadata = await cas.getVaultMetadata();
+  const passphrase = await resolveVaultPassphrase(input, requestSource, {
+    stdin: input.stdin,
+    onWarning: input.onWarning,
+  });
+
+  if (passphrase) {
+    if (hasEnvelopeRecipients(manifest)) {
+      throw invalidInput(
+        'Vault passphrase source cannot decrypt recipient-encrypted assets; provide --key-file'
+      );
+    }
+    if (!metadata?.encryption?.kdf) {
+      throw invalidInput('Vault passphrase source is only valid for encrypted vaults');
+    }
+    return await deriveVaultKey(cas, metadata, passphrase);
+  }
+
+  if (!manifest.encryption?.encrypted) {
+    return undefined;
+  }
+
+  throw needsInput('Encrypted restore requires --key-file or a vault passphrase source', {
+    requiredInputs: getRestoreRequiredInputs(manifest, metadata),
+    slug: input.slug || manifest.slug,
+    treeOid,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseStoreInput(args, stdin) {
+  const { values, positionals, requestSource } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      tree: { type: 'boolean' },
+      force: { type: 'boolean' },
+      gzip: { type: 'boolean' },
+      cwd: { type: 'string' },
+      'key-file': { type: 'string' },
+      'vault-passphrase': { type: 'string' },
+      'vault-passphrase-file': { type: 'string' },
+    },
+    stdin
+  );
+  return normalizeInputAliases({
+    ...values,
+    ...assignPositionals(positionals, ['file']),
+    requestSource,
+  });
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateStoreInput(input) {
+  if (input.file !== undefined && typeof input.file !== 'string') {
+    throw invalidInput('Request field "file" must be a string');
+  }
+  if (!input.file) {
+    throw invalidInput('Provide a file path');
+  }
+  if (!input.slug) {
+    throw invalidInput('Provide --slug <slug>');
+  }
+  if (input.force && !input.tree) {
+    throw invalidInput('--force requires --tree');
+  }
+}
+
+/**
+ * @param {{
+ *   input: Record<string, any>,
+ *   manifest: import('../../src/domain/value-objects/Manifest.js').default,
+ *   treeOid?: string,
+ *   commitOid?: string,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildStoreOutcome({ input, manifest, treeOid, commitOid }) {
+  return {
+    data: {
+      slug: input.slug,
+      manifest: manifest.toJSON(),
+      ...(treeOid ? { treeOid } : {}),
+      ...(commitOid ? { commitOid } : {}),
+      addedToVault: Boolean(commitOid),
+      chunkCount: manifest.chunks.length,
+      encrypted: Boolean(manifest.encryption?.encrypted),
+      compressed: Boolean(manifest.compression),
+    },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseVaultInitInput(args, stdin) {
+  const { values, positionals, requestSource } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+      algorithm: { type: 'string' },
+      passphrase: { type: 'string' },
+      'passphrase-file': { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  return normalizeInputAliases({
+    ...values,
+    requestSource,
+  });
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateVaultInitInput(input) {
+  if (input.passphrase !== undefined && input.passphraseFile !== undefined) {
+    throw invalidInput('Provide --passphrase or --passphrase-file, not both');
+  }
+
+  const algorithm = parseKdfAlgorithm(input.algorithm);
+  if (algorithm && input.passphrase === undefined && input.passphraseFile === undefined) {
+    throw invalidInput(
+      'Provide --passphrase <pass> or --passphrase-file <path> when using --algorithm'
+    );
+  }
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {string | undefined} requestSource
+ * @returns {Promise<string | undefined>}
+ */
+async function resolveVaultInitPassphrase(input, requestSource, options = {}) {
+  if (input.passphraseFile === '-' && requestSource === '-') {
+    throw invalidInput('Cannot read both request payload and vault init passphrase from stdin');
+  }
+  if (input.passphraseFile) {
+    return await readAgentPassphraseFile(input.passphraseFile, options);
+  }
+  if (input.passphrase !== undefined) {
+    return resolveInlinePassphrase('Passphrase', input.passphrase);
+  }
+  return undefined;
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseRotateInput(args, stdin) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      oid: { type: 'string' },
+      label: { type: 'string' },
+      cwd: { type: 'string' },
+      'old-key-file': { type: 'string' },
+      'new-key-file': { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  return normalizeInputAliases(values);
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateRotateInput(input) {
+  if (!input.oldKeyFile) {
+    throw invalidInput('Provide --old-key-file <path>');
+  }
+  if (!input.newKeyFile) {
+    throw invalidInput('Provide --new-key-file <path>');
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {'pbkdf2' | 'scrypt' | undefined}
+ */
+function parseKdfAlgorithm(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === 'pbkdf2' || value === 'scrypt') {
+    return value;
+  }
+  throw invalidInput('Provide --algorithm <pbkdf2|scrypt>');
+}
+
+/**
+ * @param {string} label
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function resolveInlinePassphrase(label, value) {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const passphrase = String(value);
+  if (!passphrase.trim()) {
+    throw invalidInput(`${label} must not be empty`);
+  }
+
+  return passphrase;
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseVaultRotateInput(args, stdin) {
+  const { values, positionals, requestSource } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+      algorithm: { type: 'string' },
+      'old-passphrase': { type: 'string' },
+      'new-passphrase': { type: 'string' },
+      'old-passphrase-file': { type: 'string' },
+      'new-passphrase-file': { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  return normalizeInputAliases({
+    ...values,
+    requestSource,
+  });
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateVaultRotateInput(input) {
+  if (input.oldPassphrase !== undefined && input.oldPassphraseFile !== undefined) {
+    throw invalidInput('Provide --old-passphrase or --old-passphrase-file, not both');
+  }
+  if (input.newPassphrase !== undefined && input.newPassphraseFile !== undefined) {
+    throw invalidInput('Provide --new-passphrase or --new-passphrase-file, not both');
+  }
+  if (input.oldPassphrase === undefined && input.oldPassphraseFile === undefined) {
+    throw invalidInput('Provide --old-passphrase <pass> or --old-passphrase-file <path>');
+  }
+  if (input.newPassphrase === undefined && input.newPassphraseFile === undefined) {
+    throw invalidInput('Provide --new-passphrase <pass> or --new-passphrase-file <path>');
+  }
+
+  parseKdfAlgorithm(input.algorithm);
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {string | undefined} requestSource
+ * @returns {Promise<{ oldPassphrase: string, newPassphrase: string }>}
+ */
+async function resolveVaultRotatePassphrases(input, requestSource, options = {}) {
+  validateVaultRotateStdinSources(input, requestSource);
+
+  return {
+    oldPassphrase: await readVaultRotatePassphrase({
+      label: 'Old passphrase',
+      inlineValue: input.oldPassphrase,
+      fileValue: input.oldPassphraseFile,
+      ...options,
+    }),
+    newPassphrase: await readVaultRotatePassphrase({
+      label: 'New passphrase',
+      inlineValue: input.newPassphrase,
+      fileValue: input.newPassphraseFile,
+      ...options,
+    }),
+  };
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @param {string | undefined} requestSource
+ */
+function validateVaultRotateStdinSources(input, requestSource) {
+  if (input.oldPassphraseFile === '-' && input.newPassphraseFile === '-') {
+    throw invalidInput('Cannot read both old and new passphrase from stdin');
+  }
+  if (
+    requestSource === '-' &&
+    (input.oldPassphraseFile === '-' || input.newPassphraseFile === '-')
+  ) {
+    throw invalidInput('Cannot read both request payload and vault rotation passphrase from stdin');
+  }
+}
+
+/**
+ * @param {{
+ *   label: string,
+ *   inlineValue: unknown,
+ *   fileValue?: string,
+ *   stdin?: NodeJS.ReadStream,
+ *   onWarning?: (warning: Record<string, any>) => void,
+ * }} options
+ * @returns {Promise<string>}
+ */
+async function readVaultRotatePassphrase({ label, inlineValue, fileValue, ...options }) {
+  const passphrase = fileValue
+    ? await readAgentPassphraseFile(fileValue, options)
+    : resolveInlinePassphrase(label, inlineValue);
+
+  if (!passphrase?.trim()) {
+    throw invalidInput(`${label} must not be empty`);
+  }
+
+  return passphrase;
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseRecipientAddInput(args, stdin) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      label: { type: 'string' },
+      cwd: { type: 'string' },
+      'key-file': { type: 'string' },
+      'existing-key-file': { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  return normalizeInputAliases(values);
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateRecipientAddInput(input) {
+  if (!input.slug) {
+    throw invalidInput('Provide --slug <slug>');
+  }
+  if (!input.label) {
+    throw invalidInput('Provide --label <label>');
+  }
+  if (!input.keyFile) {
+    throw invalidInput('Provide --key-file <path>');
+  }
+  if (!input.existingKeyFile) {
+    throw invalidInput('Provide --existing-key-file <path>');
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseRecipientRemoveInput(args, stdin) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      label: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  return values;
+}
+
+/**
+ * @param {Record<string, any>} input
+ */
+function validateRecipientRemoveInput(input) {
+  if (!input.slug) {
+    throw invalidInput('Provide --slug <slug>');
+  }
+  if (!input.label) {
+    throw invalidInput('Provide --label <label>');
+  }
+}
+
+/**
+ * @param {{ cwd: string, slug: string }} input
+ * @returns {Promise<{
+ *   cas: ContentAddressableStore,
+ *   treeOid: string,
+ *   manifest: import('../../src/domain/value-objects/Manifest.js').default,
+ * }>}
+ */
+async function resolveVaultManifestBySlug(input) {
+  const cas = createCas(input.cwd);
+  const treeOid = await cas.resolveVaultEntry({ slug: input.slug });
+  const manifest = await cas.readManifest({ treeOid });
+  return { cas, treeOid, manifest };
+}
+
+/**
+ * @param {{
+ *   action: 'add' | 'remove',
+ *   slug: string,
+ *   label: string,
+ *   previousTreeOid: string,
+ *   treeOid: string,
+ *   commitOid: string,
+ *   manifest: import('../../src/domain/value-objects/Manifest.js').default,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildRecipientMutationOutcome({
+  action,
+  slug,
+  label,
+  previousTreeOid,
+  treeOid,
+  commitOid,
+  manifest,
+}) {
+  const recipients = buildRecipientRows(manifest);
+
+  return {
+    data: {
+      action,
+      slug,
+      label,
+      previousTreeOid,
+      treeOid,
+      commitOid,
+      recipientCount: recipients.length,
+      recipients,
+    },
+  };
+}
+
+/**
+ * @param {{
+ *   previousTreeOid: string,
+ *   treeOid: string,
+ *   commitOid?: string,
+ *   manifest: import('../../src/domain/value-objects/Manifest.js').default,
+ *   label?: string,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildRotateOutcome({ previousTreeOid, treeOid, commitOid, manifest, label }) {
+  const recipients = buildRecipientRows(manifest);
+
+  return {
+    data: {
+      action: 'rotate',
+      slug: manifest.slug,
+      ...(label ? { label } : {}),
+      previousTreeOid,
+      treeOid,
+      ...(commitOid ? { commitOid } : {}),
+      updatedVault: Boolean(commitOid),
+      keyVersion: manifest.encryption?.keyVersion,
+      recipientCount: recipients.length,
+      recipients,
+    },
+  };
+}
+
+/**
+ * @param {{
+ *   commitOid: string,
+ *   rotatedSlugs: string[],
+ *   skippedSlugs: string[],
+ *   kdfAlgorithm?: string,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildVaultRotateOutcome({ commitOid, rotatedSlugs, skippedSlugs, kdfAlgorithm }) {
+  return {
+    data: {
+      commitOid,
+      updatedVault: true,
+      rotatedSlugs,
+      skippedSlugs,
+      rotatedCount: rotatedSlugs.length,
+      skippedCount: skippedSlugs.length,
+      entryCount: rotatedSlugs.length + skippedSlugs.length,
+      ...(kdfAlgorithm ? { kdfAlgorithm } : {}),
+    },
+  };
+}
+
+/**
+ * @param {{
+ *   commitOid: string,
+ *   encrypted: boolean,
+ *   kdfAlgorithm?: string,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildVaultInitOutcome({ commitOid, encrypted, kdfAlgorithm }) {
+  return {
+    data: {
+      commitOid,
+      initializedVault: true,
+      encrypted,
+      ...(kdfAlgorithm ? { kdfAlgorithm } : {}),
+    },
+  };
+}
+
+/**
+ * @param {{
+ *   slug: string,
+ *   commitOid: string,
+ *   removedTreeOid: string,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildVaultRemoveOutcome({ slug, commitOid, removedTreeOid }) {
+  return {
+    data: {
+      slug,
+      commitOid,
+      removedTreeOid,
+      updatedVault: true,
+    },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<Record<string, any>>}
+ */
+async function parseTreeInput(args, stdin) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      manifest: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  return values;
+}
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {Manifest}
+ */
+function resolveManifestInput(input) {
+  if (typeof input.manifest === 'string') {
+    const manifestPath = input.manifest;
+    const raw = readTextInputFile(manifestPath, 'manifest file');
+    try {
+      return new Manifest(JSON.parse(raw));
+    } catch (err) {
+      throw normalizeLocalInputError(err, 'manifest file', manifestPath);
+    }
+  }
+
+  if (input.manifest && typeof input.manifest === 'object' && !Array.isArray(input.manifest)) {
+    try {
+      return new Manifest(input.manifest);
+    } catch (err) {
+      throw invalidInput(
+        `Invalid manifest object: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  throw invalidInput('Provide --manifest <path> or request.manifest');
+}
+
+/**
+ * @param {Manifest} manifest
+ * @param {string} treeOid
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildTreeOutcome(manifest, treeOid) {
+  return {
+    data: {
+      treeOid,
+      slug: manifest.slug,
+      chunkCount: manifest.chunks.length,
+      encrypted: Boolean(manifest.encryption?.encrypted),
+      compressed: Boolean(manifest.compression),
+    },
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ command: string, args: string[] }}
+ */
+function resolveCommand(argv) {
+  if (argv.length === 0) {
+    return { command: 'agent', args: [] };
+  }
+
+  if (argv[0] === 'vault' || argv[0] === 'recipient') {
+    if (!argv[1]) {
+      return { command: argv[0], args: [] };
+    }
+    return { command: `${argv[0]}.${argv[1]}`, args: argv.slice(2) };
+  }
+
+  return { command: argv[0], args: argv.slice(1) };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ stdout?: Pick<NodeJS.WriteStream, 'write'>, stderr?: Pick<NodeJS.WriteStream, 'write'>, stdin?: NodeJS.ReadStream }} [deps]
+ * @returns {Promise<void>}
+ */
+export async function runAgentCli(
+  argv,
+  { stdout = process.stdout, stderr = process.stderr, stdin = process.stdin } = {}
+) {
+  const { command, args } = resolveCommand(argv);
+  const session = createAgentSession({ command, stdout, stderr });
+
+  try {
+    const outcome = await executeAgentCommand(command, args, { stdin, session });
+    const exitCode = outcome.exitCode ?? AGENT_EXIT_CODES.SUCCESS;
+    process.exitCode = exitCode;
+    session.writeResult(outcome.data);
+    session.writeEnd({ ok: exitCode === AGENT_EXIT_CODES.SUCCESS, exitCode });
+  } catch (err) {
+    const exitCode = getAgentExitCode(err);
+    process.exitCode = exitCode;
+    if (err instanceof Error && err.code === 'NEEDS_INPUT') {
+      session.writeNeedsInput(err);
+    } else {
+      session.writeError(err);
+    }
+    session.writeEnd({ ok: false, exitCode });
+  }
+}
+
+const COMMAND_HANDLERS = Object.freeze({
+  store: storeCommand,
+  tree: treeCommand,
+  restore: restoreCommand,
+  rotate: rotateCommand,
+  inspect: inspectCommand,
+  verify: verifyCommand,
+  doctor: doctorCommand,
+  'recipient.add': recipientAddCommand,
+  'recipient.remove': recipientRemoveCommand,
+  'recipient.list': recipientListCommand,
+  'vault.init': vaultInitCommand,
+  'vault.list': vaultListCommand,
+  'vault.info': vaultInfoCommand,
+  'vault.history': vaultHistoryCommand,
+  'vault.remove': vaultRemoveCommand,
+  'vault.rotate': vaultRotateCommand,
+  'vault.stats': vaultStatsCommand,
+});
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ stdin: NodeJS.ReadStream, session: ReturnType<typeof createAgentSession> }} context
+ * @returns {Promise<{ exitCode?: number, data: Record<string, any> }>}
+ */
+async function executeAgentCommand(command, args, context) {
+  const handler = COMMAND_HANDLERS[command];
+
+  if (!handler) {
+    throw invalidInput('Unknown agent command', {
+      command,
+      availableCommands: AVAILABLE_COMMANDS,
+    });
+  }
+
+  return handler(args, context.stdin, context.session);
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ input: Record<string, any>, requestSource?: string }>}
+ */
+async function parseRestoreInput(args, stdin) {
+  const { values, positionals, requestSource } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      oid: { type: 'string' },
+      out: { type: 'string' },
+      cwd: { type: 'string' },
+      'key-file': { type: 'string' },
+      'vault-passphrase': { type: 'string' },
+      'vault-passphrase-file': { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+
+  return {
+    input: normalizeInputAliases(values),
+    requestSource,
+  };
+}
+
+/**
+ * @param {{
+ *   manifest: import('../../src/domain/value-objects/Manifest.js').default,
+ *   treeOid: string,
+ *   outputPath: string,
+ *   bytesWritten: number,
+ * }} options
+ * @returns {{ data: Record<string, any> }}
+ */
+function buildRestoreOutcome({ manifest, treeOid, outputPath, bytesWritten }) {
+  return {
+    data: {
+      slug: manifest.slug,
+      treeOid,
+      outputPath,
+      bytesWritten,
+      encrypted: Boolean(manifest.encryption?.encrypted),
+    },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function storeCommand(args, stdin, session) {
+  const input = await parseStoreInput(args, stdin);
+  validateStoreInput(input);
+  validateCredentialSources(input);
+  writeAgentStart(
+    session,
+    selectStartInput(input, [
+      'cwd',
+      'file',
+      'slug',
+      'tree',
+      'force',
+      'gzip',
+      'keyFile',
+      'vaultPassphrase',
+      'vaultPassphraseFile',
+      'requestSource',
+    ])
+  );
+
+  const cas = createCas(input.cwd || '.');
+  const encryptionKey = await resolveStoreEncryptionKey(cas, input, {
+    stdin,
+    onWarning: (warning) => session.writeWarning(warning),
+  });
+  const manifest = await cas.storeFile({
+    filePath: input.file,
+    slug: input.slug,
+    ...(encryptionKey ? { encryptionKey } : {}),
+    ...(input.gzip ? { compression: { algorithm: 'gzip' } } : {}),
+  });
+
+  let treeOid;
+  let commitOid;
+  if (input.tree) {
+    treeOid = await cas.createTree({ manifest });
+    ({ commitOid } = await cas.addToVault({
+      slug: input.slug,
+      treeOid,
+      force: Boolean(input.force),
+    }));
+  }
+
+  return buildStoreOutcome({ input, manifest, treeOid, commitOid });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function treeCommand(args, stdin, session) {
+  const input = await parseTreeInput(args, stdin);
+  const manifest = resolveManifestInput(input);
+  writeAgentStart(session, selectStartInput(input, ['cwd', 'manifest', 'requestSource']));
+  const cas = createCas(input.cwd || '.');
+  const treeOid = await cas.createTree({ manifest });
+
+  return buildTreeOutcome(manifest, treeOid);
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function restoreCommand(args, stdin, session) {
+  const { input, requestSource } = await parseRestoreInput(args, stdin);
+  if (!input.out) {
+    throw invalidInput('Provide --out <path>');
+  }
+  validateCredentialSources(input);
+  const target = resolveTarget(input);
+  writeAgentStart(
+    session,
+    selectStartInput(input, [
+      'cwd',
+      'slug',
+      'oid',
+      'out',
+      'keyFile',
+      'vaultPassphrase',
+      'vaultPassphraseFile',
+      'requestSource',
+    ])
+  );
+  const { cas, treeOid } = await resolveTree(target);
+  const manifest = await cas.readManifest({ treeOid });
+  const encryptionKey = await resolveRestoreEncryptionKey({
+    cas,
+    manifest,
+    input: {
+      ...input,
+      stdin,
+      onWarning: (warning) => session.writeWarning(warning),
+    },
+    requestSource,
+    treeOid,
+  });
+  const { bytesWritten } = await cas.restoreFile({
+    manifest,
+    ...(encryptionKey ? { encryptionKey } : {}),
+    outputPath: input.out,
+  });
+
+  return buildRestoreOutcome({
+    manifest,
+    treeOid,
+    outputPath: input.out,
+    bytesWritten,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function rotateCommand(args, stdin, session) {
+  const input = await parseRotateInput(args, stdin);
+  const target = resolveTarget(input);
+  validateRotateInput(input);
+  writeAgentStart(
+    session,
+    selectStartInput(input, ['cwd', 'slug', 'oid', 'label', 'oldKeyFile', 'newKeyFile'])
+  );
+
+  const { cas, treeOid: previousTreeOid } = await resolveTree(target);
+  const manifest = await cas.readManifest({ treeOid: previousTreeOid });
+  const updated = await cas.rotateKey({
+    manifest,
+    oldKey: readKeyFile(input.oldKeyFile),
+    newKey: readKeyFile(input.newKeyFile),
+    ...(input.label ? { label: input.label } : {}),
+  });
+
+  const treeOid = await cas.createTree({ manifest: updated });
+  let commitOid;
+  if (input.slug) {
+    ({ commitOid } = await cas.addToVault({
+      slug: input.slug,
+      treeOid,
+      force: true,
+    }));
+  }
+
+  return buildRotateOutcome({
+    previousTreeOid,
+    treeOid,
+    commitOid,
+    manifest: updated,
+    label: input.label,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function inspectCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      oid: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  const positionalInput = assignPositionals(positionals, []);
+  const input = resolveTarget({ ...values, ...positionalInput });
+  writeAgentStart(session, selectStartInput(input, ['cwd', 'slug', 'oid']));
+  const { cas, treeOid } = await resolveTree(input);
+  const manifest = await cas.readManifest({ treeOid });
+  return {
+    data: {
+      treeOid,
+      manifest: manifest.toJSON(),
+    },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ exitCode: number, data: Record<string, any> }>}
+ */
+async function verifyCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      oid: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  const positionalInput = assignPositionals(positionals, []);
+  const input = resolveTarget({ ...values, ...positionalInput });
+  writeAgentStart(session, selectStartInput(input, ['cwd', 'slug', 'oid']));
+  const { cas, treeOid } = await resolveTree(input);
+  const manifest = await cas.readManifest({ treeOid });
+  const ok = await cas.verifyIntegrity(manifest);
+
+  return {
+    exitCode: ok ? AGENT_EXIT_CODES.SUCCESS : AGENT_EXIT_CODES.VERIFICATION_FAILED,
+    data: {
+      ok,
+      slug: manifest.slug,
+      treeOid,
+      chunks: manifest.chunks.length,
+    },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ exitCode: number, data: Record<string, any> }>}
+ */
+async function doctorCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  writeAgentStart(session, selectStartInput(values, ['cwd']));
+
+  const cas = createCas(values.cwd || '.');
+  const report = await inspectVaultHealth(cas);
+  const exitCode =
+    report.status === 'ok' ? AGENT_EXIT_CODES.SUCCESS : AGENT_EXIT_CODES.VERIFICATION_FAILED;
+
+  return {
+    exitCode,
+    data: { report },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function recipientAddCommand(args, stdin, session) {
+  const input = await parseRecipientAddInput(args, stdin);
+  validateRecipientAddInput(input);
+  writeAgentStart(
+    session,
+    selectStartInput(input, ['cwd', 'slug', 'label', 'keyFile', 'existingKeyFile'])
+  );
+
+  const target = resolveSlugTarget(input);
+  const { cas, treeOid: previousTreeOid, manifest } = await resolveVaultManifestBySlug(target);
+  const updated = await cas.addRecipient({
+    manifest,
+    existingKey: readKeyFile(input.existingKeyFile),
+    newRecipientKey: readKeyFile(input.keyFile),
+    label: input.label,
+  });
+  const treeOid = await cas.createTree({ manifest: updated });
+  const { commitOid } = await cas.addToVault({
+    slug: input.slug,
+    treeOid,
+    force: true,
+  });
+
+  return buildRecipientMutationOutcome({
+    action: 'add',
+    slug: input.slug,
+    label: input.label,
+    previousTreeOid,
+    treeOid,
+    commitOid,
+    manifest: updated,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function recipientRemoveCommand(args, stdin, session) {
+  const input = await parseRecipientRemoveInput(args, stdin);
+  validateRecipientRemoveInput(input);
+  writeAgentStart(session, selectStartInput(input, ['cwd', 'slug', 'label']));
+
+  const target = resolveSlugTarget(input);
+  const { cas, treeOid: previousTreeOid, manifest } = await resolveVaultManifestBySlug(target);
+  const updated = await cas.removeRecipient({
+    manifest,
+    label: input.label,
+  });
+  const treeOid = await cas.createTree({ manifest: updated });
+  const { commitOid } = await cas.addToVault({
+    slug: input.slug,
+    treeOid,
+    force: true,
+  });
+
+  return buildRecipientMutationOutcome({
+    action: 'remove',
+    slug: input.slug,
+    label: input.label,
+    previousTreeOid,
+    treeOid,
+    commitOid,
+    manifest: updated,
+  });
+}
+
+/**
+ * @param {import('../../src/domain/value-objects/Manifest.js').default} manifest
+ * @returns {Array<{ label: string, keyVersion?: number }>}
+ */
+function buildRecipientRows(manifest) {
+  return (manifest.encryption?.recipients || []).map((recipient) => ({
+    label: recipient.label,
+    ...(recipient.keyVersion !== undefined ? { keyVersion: recipient.keyVersion } : {}),
+  }));
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function recipientListCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      oid: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+
+  const input = resolveTarget(values);
+  writeAgentStart(session, selectStartInput(input, ['cwd', 'slug', 'oid']));
+  const { cas, treeOid } = await resolveTree(input);
+  const manifest = await cas.readManifest({ treeOid });
+  const recipients = buildRecipientRows(manifest);
+
+  return {
+    data: {
+      slug: manifest.slug,
+      treeOid,
+      envelope: recipients.length > 0,
+      recipientCount: recipients.length,
+      recipients,
+    },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultInitCommand(args, stdin, session) {
+  const input = await parseVaultInitInput(args, stdin);
+  validateVaultInitInput(input);
+  writeAgentStart(
+    session,
+    selectStartInput(input, ['cwd', 'algorithm', 'passphrase', 'passphraseFile', 'requestSource'])
+  );
+
+  const passphrase = await resolveVaultInitPassphrase(input, input.requestSource, {
+    stdin,
+    onWarning: (warning) => session.writeWarning(warning),
+  });
+  const algorithm = parseKdfAlgorithm(input.algorithm);
+  const cas = createCas(input.cwd || '.');
+  const { commitOid } = await cas.initVault({
+    ...(passphrase ? { passphrase } : {}),
+    ...(passphrase && algorithm ? { kdfOptions: { algorithm } } : {}),
+  });
+  const metadata = await cas.getVaultMetadata();
+
+  return buildVaultInitOutcome({
+    commitOid,
+    encrypted: Boolean(metadata?.encryption),
+    kdfAlgorithm: metadata?.encryption?.kdf?.algorithm,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultRemoveCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      slug: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+
+  if (!values.slug) {
+    throw invalidInput('Provide --slug <slug>');
+  }
+  writeAgentStart(session, selectStartInput(values, ['cwd', 'slug']));
+
+  const cas = createCas(values.cwd || '.');
+  const { commitOid, removedTreeOid } = await cas.removeFromVault({ slug: values.slug });
+
+  return buildVaultRemoveOutcome({
+    slug: values.slug,
+    commitOid,
+    removedTreeOid,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultRotateCommand(args, stdin, session) {
+  const input = await parseVaultRotateInput(args, stdin);
+  validateVaultRotateInput(input);
+  writeAgentStart(
+    session,
+    selectStartInput(input, [
+      'cwd',
+      'algorithm',
+      'oldPassphrase',
+      'oldPassphraseFile',
+      'newPassphrase',
+      'newPassphraseFile',
+      'requestSource',
+    ])
+  );
+
+  const { oldPassphrase, newPassphrase } = await resolveVaultRotatePassphrases(
+    input,
+    input.requestSource,
+    {
+      stdin,
+      onWarning: (warning) => session.writeWarning(warning),
+    }
+  );
+  const cas = createCas(input.cwd || '.');
+  const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase({
+    oldPassphrase,
+    newPassphrase,
+    ...(input.algorithm ? { kdfOptions: { algorithm: parseKdfAlgorithm(input.algorithm) } } : {}),
+  });
+  const metadata = await cas.getVaultMetadata();
+
+  return buildVaultRotateOutcome({
+    commitOid,
+    rotatedSlugs,
+    skippedSlugs,
+    kdfAlgorithm: metadata?.encryption?.kdf?.algorithm,
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultListCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+      filter: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  writeAgentStart(session, selectStartInput(values, ['cwd', 'filter']));
+
+  const cas = createCas(values.cwd || '.');
+  const all = await cas.listVault();
+  const entries = filterEntries(all, values.filter);
+
+  return {
+    data: { entries },
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultInfoCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+      encryption: { type: 'boolean' },
+    },
+    stdin
+  );
+  const input = { ...values, ...assignPositionals(positionals, ['slug']) };
+
+  if (!input.slug) {
+    throw invalidInput('Provide a vault slug');
+  }
+  writeAgentStart(session, selectStartInput(input, ['cwd', 'slug', 'encryption']));
+
+  const cas = createCas(input.cwd || '.');
+  const treeOid = await cas.resolveVaultEntry({ slug: input.slug });
+  /** @type {Record<string, any>} */
+  const result = {
+    slug: input.slug,
+    treeOid,
+  };
+
+  if (input.encryption) {
+    const metadata = await cas.getVaultMetadata();
+    if (metadata?.encryption) {
+      result.encryption = metadata.encryption;
+    }
+  }
+
+  return { data: result };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultHistoryCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+      'max-count': { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  const plumbing = createGitPlumbing({ cwd: values.cwd || '.' });
+  const argsForGit = ['log', '--oneline', ContentAddressableStore.VAULT_REF];
+  const maxCount = parsePositiveInteger(values['max-count']);
+  writeAgentStart(
+    session,
+    selectStartInput({
+      cwd: values.cwd,
+      maxCount,
+    }, ['cwd', 'maxCount'])
+  );
+  if (maxCount !== undefined) {
+    argsForGit.push(`-${maxCount}`);
+  }
+
+  const output = await plumbing.execute({ args: argsForGit });
+  const history = output
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [commitOid, ...messageParts] = line.trim().split(/\s+/);
+      return { commitOid, message: messageParts.join(' ') };
+    });
+
+  return { data: { history } };
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ReadStream} stdin
+ * @returns {Promise<{ data: Record<string, any> }>}
+ */
+async function vaultStatsCommand(args, stdin, session) {
+  const { values, positionals } = await parseAgentInput(
+    args,
+    {
+      cwd: { type: 'string' },
+      filter: { type: 'string' },
+    },
+    stdin
+  );
+  assignPositionals(positionals, []);
+  writeAgentStart(session, selectStartInput(values, ['cwd', 'filter']));
+
+  const cas = createCas(values.cwd || '.');
+  const all = await cas.listVault();
+  const entries = filterEntries(all, values.filter);
+  const records = [];
+  for (const entry of entries) {
+    const manifest = await cas.readManifest({ treeOid: entry.treeOid });
+    records.push({ ...entry, manifest });
+  }
+
+  return {
+    data: {
+      stats: buildVaultStats(records),
+    },
+  };
+}
diff --git a/bin/agent/protocol.js b/bin/agent/protocol.js
new file mode 100644
index 0000000..3b82d3a
--- /dev/null
+++ b/bin/agent/protocol.js
@@ -0,0 +1,178 @@
+import { HINTS } from '../actions.js';
+
+export const AGENT_PROTOCOL = 'git-cas-agent/v1';
+
+export const AGENT_EXIT_CODES = Object.freeze({
+  SUCCESS: 0,
+  FAILURE: 1,
+  INVALID_INPUT: 2,
+  VERIFICATION_FAILED: 3,
+});
+
+/**
+ * Map an operational error to an agent exit code.
+ *
+ * @param {unknown} err
+ * @returns {number}
+ */
+export function getAgentExitCode(err) {
+  const code = getErrorCode(err);
+
+  if (code === 'INVALID_INPUT' || code === 'NEEDS_INPUT') {
+    return AGENT_EXIT_CODES.INVALID_INPUT;
+  }
+
+  if (code === 'INTEGRITY_ERROR') {
+    return AGENT_EXIT_CODES.VERIFICATION_FAILED;
+  }
+
+  return AGENT_EXIT_CODES.FAILURE;
+}
+
+/**
+ * Normalize an error into the JSONL protocol shape.
+ *
+ * @param {unknown} err
+ * @returns {{ code: string, message: string, retryable: boolean, hint?: string, meta?: Record<string, any> }}
+ */
+export function normalizeAgentError(err) {
+  const code = getErrorCode(err) || 'ERROR';
+  const message = getErrorMessage(err);
+  const retryable = getErrorRetryable(err);
+
+  /** @type {{ code: string, message: string, retryable: boolean, hint?: string, meta?: Record<string, any> }} */
+  const data = { code, message, retryable };
+
+  if (Object.prototype.hasOwnProperty.call(HINTS, code)) {
+    data.hint = HINTS[code];
+  }
+
+  const meta = getErrorMeta(err);
+  if (meta) {
+    data.meta = meta;
+  }
+
+  return data;
+}
+
+/**
+ * Normalize a needs-input branch into the JSONL protocol shape.
+ *
+ * @param {unknown} err
+ * @returns {{ code: string, message: string } & Record<string, any>}
+ */
+export function normalizeAgentNeedsInput(err) {
+  const code = getErrorCode(err) || 'NEEDS_INPUT';
+  const message = getErrorMessage(err);
+  const meta = getErrorMeta(err);
+
+  return meta ? { code, message, ...meta } : { code, message };
+}
+
+/**
+ * @param {unknown} err
+ * @returns {string | undefined}
+ */
+function getErrorCode(err) {
+  if (typeof err === 'object' && err && typeof err.code === 'string') {
+    return err.code;
+  }
+  return undefined;
+}
+
+/**
+ * @param {unknown} err
+ * @returns {string}
+ */
+function getErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function getErrorRetryable(err) {
+  if (typeof err === 'object' && err && typeof err.retryable === 'boolean') {
+    return err.retryable;
+  }
+  return false;
+}
+
+/**
+ * @param {unknown} err
+ * @returns {Record<string, any> | undefined}
+ */
+function getErrorMeta(err) {
+  if (
+    typeof err === 'object' &&
+    err &&
+    err.meta &&
+    typeof err.meta === 'object' &&
+    !Array.isArray(err.meta)
+  ) {
+    return err.meta;
+  }
+  return undefined;
+}
+
+/**
+ * Create a JSONL session writer for the agent protocol.
+ *
+ * @param {{
+ *   command: string,
+ *   stdout?: Pick<NodeJS.WriteStream, 'write'>,
+ *   stderr?: Pick<NodeJS.WriteStream, 'write'>,
+ *   now?: () => Date,
+ * }} options
+ */
+export function createAgentSession({
+  command,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  now = () => new Date(),
+}) {
+  let seq = 0;
+
+  /**
+   * @param {Pick<NodeJS.WriteStream, 'write'>} stream
+   * @param {string} type
+   * @param {Record<string, any>} data
+   */
+  function write(stream, type, data) {
+    seq += 1;
+    const row = {
+      protocol: AGENT_PROTOCOL,
+      command,
+      type,
+      seq,
+      ts: now().toISOString(),
+      data,
+    };
+    stream.write(`${JSON.stringify(row)}\n`);
+  }
+
+  return {
+    writeStart(data = {}) {
+      write(stdout, 'start', data);
+    },
+    writeProgress(data) {
+      write(stdout, 'progress', data);
+    },
+    writeResult(data) {
+      write(stdout, 'result', data);
+    },
+    writeEnd(data) {
+      write(stdout, 'end', data);
+    },
+    writeWarning(data) {
+      write(stderr, 'warning', data);
+    },
+    writeNeedsInput(err) {
+      write(stderr, 'needs-input', normalizeAgentNeedsInput(err));
+    },
+    writeError(err) {
+      write(stderr, 'error', normalizeAgentError(err));
+    },
+  };
+}
diff --git a/bin/git-cas.js b/bin/git-cas.js
index 80b56fd..1a9db10 100755
--- a/bin/git-cas.js
+++ b/bin/git-cas.js
@@ -12,8 +12,14 @@ import { renderEncryptionCard } from './ui/encryption-card.js';
 import { renderHistoryTimeline } from './ui/history-timeline.js';
 import { renderManifestView } from './ui/manifest-view.js';
 import { renderHeatmap } from './ui/heatmap.js';
-import { buildVaultStats, inspectVaultHealth, renderDoctorReport, renderVaultStats } from './ui/vault-report.js';
+import {
+  buildVaultStats,
+  inspectVaultHealth,
+  renderDoctorReport,
+  renderVaultStats,
+} from './ui/vault-report.js';
 import { runAction } from './actions.js';
+import { runAgentCli } from './agent/cli.js';
 import { flushStdioAndExit, installBrokenPipeHandlers } from './io.js';
 import { filterEntries, formatTable, formatTabSeparated } from './ui/vault-list.js';
 import { readPassphraseFile, promptPassphrase } from './ui/passphrase-prompt.js';
@@ -21,12 +27,17 @@ import { loadConfig, mergeConfig } from './config.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const { version: CLI_VERSION } = JSON.parse(
-  readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'),
+  readFileSync(path.resolve(__dirname, '../package.json'), 'utf8')
 );
 
 const getJson = () => program.opts().json;
 installBrokenPipeHandlers();
 
+if (process.argv[2] === 'agent') {
+  await runAgentCli(process.argv.slice(3));
+  await flushStdioAndExit();
+}
+
 program
   .name('git-cas')
   .description('Content Addressable Storage backed by Git')
@@ -98,7 +109,34 @@ async function deriveVaultKey(cas, metadata, passphrase) {
  * @returns {boolean}
  */
 function hasPassphraseSource(opts) {
-  return Boolean(opts.vaultPassphraseFile || opts.vaultPassphrase || process.env.GIT_CAS_PASSPHRASE);
+  return Boolean(
+    opts.vaultPassphraseFile || opts.vaultPassphrase || process.env.GIT_CAS_PASSPHRASE
+  );
+}
+
+/**
+ * Returns true when an explicit non-interactive passphrase source exists on the CLI.
+ * Does not consider ambient environment variables.
+ *
+ * @param {Record<string, any>} opts
+ * @returns {boolean}
+ */
+function hasExplicitPassphraseSource(opts) {
+  return opts.vaultPassphraseFile !== undefined || opts.vaultPassphrase !== undefined;
+}
+
+/**
+ * Validate human CLI credential sources so explicit-but-empty values still count as provided.
+ *
+ * @param {Record<string, any>} opts
+ */
+function validateCredentialSources(opts) {
+  if (opts.vaultPassphrase !== undefined && opts.vaultPassphraseFile !== undefined) {
+    throw new Error('Provide --vault-passphrase or --vault-passphrase-file, not both');
+  }
+  if (opts.keyFile !== undefined && hasExplicitPassphraseSource(opts)) {
+    throw new Error('Provide --key-file or a vault passphrase source, not both');
+  }
 }
 
 /**
@@ -113,15 +151,19 @@ function hasPassphraseSource(opts) {
  * @returns {Promise<string | undefined>}
  */
 async function resolvePassphrase(opts, extra = {}) {
-  if (opts.vaultPassphraseFile) {
+  if (opts.vaultPassphraseFile !== undefined) {
     return await readPassphraseFile(opts.vaultPassphraseFile);
   }
-  if (opts.vaultPassphrase) {
-    if (!opts.vaultPassphrase.trim()) { throw new Error('Passphrase must not be empty'); }
+  if (opts.vaultPassphrase !== undefined) {
+    if (!opts.vaultPassphrase.trim()) {
+      throw new Error('Passphrase must not be empty');
+    }
     return opts.vaultPassphrase;
   }
   if (process.env.GIT_CAS_PASSPHRASE) {
-    if (!process.env.GIT_CAS_PASSPHRASE.trim()) { throw new Error('Passphrase must not be empty'); }
+    if (!process.env.GIT_CAS_PASSPHRASE.trim()) {
+      throw new Error('Passphrase must not be empty');
+    }
     return process.env.GIT_CAS_PASSPHRASE;
   }
   if (process.stdin.isTTY) {
@@ -196,7 +238,9 @@ async function buildStoreOpts(cas, file, opts) {
     storeOpts.recipients = opts.recipient;
   } else {
     const encryptionKey = await resolveEncryptionKey(cas, opts);
-    if (encryptionKey) { storeOpts.encryptionKey = encryptionKey; }
+    if (encryptionKey) {
+      storeOpts.encryptionKey = encryptionKey;
+    }
   }
   return storeOpts;
 }
@@ -227,9 +271,13 @@ function parseRecipient(value, previous) {
 
 /** @param {string} v */
 const parseIntFlag = (v) => {
-  if (!/^-?\d+$/.test(v)) { throw new Error(`Expected an integer, got "${v}"`); }
+  if (!/^-?\d+$/.test(v)) {
+    throw new Error(`Expected an integer, got "${v}"`);
+  }
   const n = Number(v);
-  if (!Number.isSafeInteger(n)) { throw new Error(`Expected a safe integer, got "${v}"`); }
+  if (!Number.isSafeInteger(n)) {
+    throw new Error(`Expected a safe integer, got "${v}"`);
+  }
   return n;
 };
 
@@ -241,7 +289,10 @@ program
   .option('--recipient <label:keyfile>', 'Envelope recipient (repeatable)', parseRecipient)
   .option('--tree', 'Also create a Git tree and print its OID')
   .option('--force', 'Overwrite existing vault entry')
-  .option('--vault-passphrase <pass>', 'Vault-level passphrase for encryption (prefer GIT_CAS_PASSPHRASE env var)')
+  .option(
+    '--vault-passphrase <pass>',
+    'Vault-level passphrase for encryption (prefer GIT_CAS_PASSPHRASE env var)'
+  )
   .option('--vault-passphrase-file <path>', 'Read vault passphrase from file (use - for stdin)')
   .option('--gzip', 'Enable gzip compression')
   .addOption(new Option('--strategy <type>', 'Chunking strategy').choices(['fixed', 'cdc']))
@@ -253,37 +304,48 @@ program
   .option('--max-chunk-size <n>', 'CDC maximum chunk size', parseIntFlag)
   .option('--merkle-threshold <n>', 'Chunk count threshold for Merkle sub-manifests', parseIntFlag)
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {string} */ file, /** @type {Record<string, any>} */ opts) => {
-    if (opts.recipient && (opts.keyFile || hasPassphraseSource(opts))) {
-      throw new Error('Provide --key-file or a vault passphrase source (--vault-passphrase, --vault-passphrase-file, GIT_CAS_PASSPHRASE), or --recipient — not both');
-    }
-    if (opts.force && !opts.tree) {
-      throw new Error('--force requires --tree');
-    }
-    const json = program.opts().json;
-    const quiet = program.opts().quiet || json;
-    const observer = new EventEmitterObserver();
-
-    const config = loadConfig(opts.cwd);
-    const { casConfig, storeExtras } = mergeConfig(opts, config);
-    const cas = createCas(opts.cwd, { observability: observer, ...casConfig });
-
-    const storeOpts = await buildStoreOpts(cas, file, opts);
-    Object.assign(storeOpts, storeExtras);
-    const progress = createStoreProgress({ filePath: file, chunkSize: cas.chunkSize, quiet });
-    progress.attach(observer);
-    let manifest;
-    try { manifest = await cas.storeFile(storeOpts); } finally { progress.detach(); }
-
-    if (opts.tree) {
-      const treeOid = await cas.createTree({ manifest });
-      await cas.addToVault({ slug: opts.slug, treeOid, force: !!opts.force });
-      process.stdout.write(json ? `${JSON.stringify({ treeOid })}\n` : `${treeOid}\n`);
-    } else {
-      const output = json ? JSON.stringify({ manifest: manifest.toJSON() }) : JSON.stringify(manifest.toJSON(), null, 2);
-      process.stdout.write(`${output}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {string} */ file, /** @type {Record<string, any>} */ opts) => {
+      validateCredentialSources(opts);
+      if (opts.recipient && (opts.keyFile || hasExplicitPassphraseSource(opts))) {
+        throw new Error(
+          'Provide --key-file or a vault passphrase source (--vault-passphrase, --vault-passphrase-file, GIT_CAS_PASSPHRASE), or --recipient — not both'
+        );
+      }
+      if (opts.force && !opts.tree) {
+        throw new Error('--force requires --tree');
+      }
+      const json = program.opts().json;
+      const quiet = program.opts().quiet || json;
+      const observer = new EventEmitterObserver();
+
+      const config = loadConfig(opts.cwd);
+      const { casConfig, storeExtras } = mergeConfig(opts, config);
+      const cas = createCas(opts.cwd, { observability: observer, ...casConfig });
+
+      const storeOpts = await buildStoreOpts(cas, file, opts);
+      Object.assign(storeOpts, storeExtras);
+      const progress = createStoreProgress({ filePath: file, chunkSize: cas.chunkSize, quiet });
+      progress.attach(observer);
+      let manifest;
+      try {
+        manifest = await cas.storeFile(storeOpts);
+      } finally {
+        progress.detach();
+      }
+
+      if (opts.tree) {
+        const treeOid = await cas.createTree({ manifest });
+        await cas.addToVault({ slug: opts.slug, treeOid, force: !!opts.force });
+        process.stdout.write(json ? `${JSON.stringify({ treeOid })}\n` : `${treeOid}\n`);
+      } else {
+        const output = json
+          ? JSON.stringify({ manifest: manifest.toJSON() })
+          : JSON.stringify(manifest.toJSON(), null, 2);
+        process.stdout.write(`${output}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // tree
@@ -293,18 +355,20 @@ program
   .description('Create a Git tree from a manifest')
   .requiredOption('--manifest <path>', 'Path to manifest JSON file')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const raw = readFileSync(opts.manifest, 'utf8');
-    const manifest = new Manifest(JSON.parse(raw));
-    const treeOid = await cas.createTree({ manifest });
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ treeOid })}\n`);
-    } else {
-      process.stdout.write(`${treeOid}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const raw = readFileSync(opts.manifest, 'utf8');
+      const manifest = new Manifest(JSON.parse(raw));
+      const treeOid = await cas.createTree({ manifest });
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ treeOid })}\n`);
+      } else {
+        process.stdout.write(`${treeOid}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // inspect
@@ -316,23 +380,25 @@ program
   .option('--oid <tree-oid>', 'Direct tree OID')
   .option('--heatmap', 'Show chunk heatmap visualization')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    validateRestoreFlags(opts);
-    const cas = createCas(opts.cwd);
-    const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
-    const manifest = await cas.readManifest({ treeOid });
-    const json = program.opts().json;
-
-    if (json) {
-      process.stdout.write(`${JSON.stringify(manifest.toJSON())}\n`);
-    } else if (opts.heatmap) {
-      process.stdout.write(renderHeatmap({ manifest }));
-    } else if (process.stdout.isTTY) {
-      process.stdout.write(renderManifestView({ manifest }));
-    } else {
-      process.stdout.write(`${JSON.stringify(manifest.toJSON(), null, 2)}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      validateRestoreFlags(opts);
+      const cas = createCas(opts.cwd);
+      const treeOid = opts.oid || (await cas.resolveVaultEntry({ slug: opts.slug }));
+      const manifest = await cas.readManifest({ treeOid });
+      const json = program.opts().json;
+
+      if (json) {
+        process.stdout.write(`${JSON.stringify(manifest.toJSON())}\n`);
+      } else if (opts.heatmap) {
+        process.stdout.write(renderHeatmap({ manifest }));
+      } else if (process.stdout.isTTY) {
+        process.stdout.write(renderManifestView({ manifest }));
+      } else {
+        process.stdout.write(`${JSON.stringify(manifest.toJSON(), null, 2)}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // restore
@@ -344,51 +410,66 @@ program
   .option('--slug <slug>', 'Resolve tree OID from vault slug')
   .option('--oid <tree-oid>', 'Direct tree OID')
   .option('--key-file <path>', 'Path to 32-byte raw encryption key file')
-  .option('--vault-passphrase <pass>', 'Vault-level passphrase for decryption (prefer GIT_CAS_PASSPHRASE env var)')
+  .option(
+    '--vault-passphrase <pass>',
+    'Vault-level passphrase for decryption (prefer GIT_CAS_PASSPHRASE env var)'
+  )
   .option('--vault-passphrase-file <path>', 'Read vault passphrase from file (use - for stdin)')
   .option('--concurrency <n>', 'Parallel chunk I/O operations', parseIntFlag)
-  .option('--max-restore-buffer <n>', 'Max bytes for buffered encrypted/compressed restore', parseIntFlag)
+  .option(
+    '--max-restore-buffer <n>',
+    'Max bytes for buffered encrypted/compressed restore',
+    parseIntFlag
+  )
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    validateRestoreFlags(opts);
-    const quiet = program.opts().quiet || program.opts().json;
-    const observer = new EventEmitterObserver();
-
-    const config = loadConfig(opts.cwd);
-    /** @type {Record<string, any>} */
-    const casConfig = {};
-    const concurrency = opts.concurrency ?? config.concurrency;
-    const maxRestoreBufferSize = opts.maxRestoreBuffer ?? config.maxRestoreBufferSize;
-    if (concurrency !== undefined) { casConfig.concurrency = concurrency; }
-    if (maxRestoreBufferSize !== undefined) { casConfig.maxRestoreBufferSize = maxRestoreBufferSize; }
-
-    const cas = createCas(opts.cwd, { observability: observer, ...casConfig });
-    const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
-    const manifest = await cas.readManifest({ treeOid });
-
-    const encryptionKey = await resolveEncryptionKey(cas, opts);
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      validateCredentialSources(opts);
+      validateRestoreFlags(opts);
+      const quiet = program.opts().quiet || program.opts().json;
+      const observer = new EventEmitterObserver();
+
+      const config = loadConfig(opts.cwd);
+      /** @type {Record<string, any>} */
+      const casConfig = {};
+      const concurrency = opts.concurrency ?? config.concurrency;
+      const maxRestoreBufferSize = opts.maxRestoreBuffer ?? config.maxRestoreBufferSize;
+      if (concurrency !== undefined) {
+        casConfig.concurrency = concurrency;
+      }
+      if (maxRestoreBufferSize !== undefined) {
+        casConfig.maxRestoreBufferSize = maxRestoreBufferSize;
+      }
 
-    const progress = createRestoreProgress({
-      totalChunks: manifest.chunks.length, quiet,
-    });
-    progress.attach(observer);
-    let bytesWritten;
-    try {
-      ({ bytesWritten } = await cas.restoreFile({
-        manifest,
-        ...(encryptionKey ? { encryptionKey } : {}),
-        outputPath: opts.out,
-      }));
-    } finally {
-      progress.detach();
-    }
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ bytesWritten })}\n`);
-    } else {
-      process.stdout.write(`${bytesWritten}\n`);
-    }
-  }, getJson));
+      const cas = createCas(opts.cwd, { observability: observer, ...casConfig });
+      const treeOid = opts.oid || (await cas.resolveVaultEntry({ slug: opts.slug }));
+      const manifest = await cas.readManifest({ treeOid });
+
+      const encryptionKey = await resolveEncryptionKey(cas, opts);
+
+      const progress = createRestoreProgress({
+        totalChunks: manifest.chunks.length,
+        quiet,
+      });
+      progress.attach(observer);
+      let bytesWritten;
+      try {
+        ({ bytesWritten } = await cas.restoreFile({
+          manifest,
+          ...(encryptionKey ? { encryptionKey } : {}),
+          outputPath: opts.out,
+        }));
+      } finally {
+        progress.detach();
+      }
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ bytesWritten })}\n`);
+      } else {
+        process.stdout.write(`${bytesWritten}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // verify
@@ -399,22 +480,26 @@ program
   .option('--slug <slug>', 'Resolve tree OID from vault slug')
   .option('--oid <tree-oid>', 'Direct tree OID')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    validateRestoreFlags(opts);
-    const cas = createCas(opts.cwd);
-    const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
-    const manifest = await cas.readManifest({ treeOid });
-    const ok = await cas.verifyIntegrity(manifest);
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ ok, slug: manifest.slug, chunks: manifest.chunks.length })}\n`);
-    } else {
-      process.stdout.write(ok ? 'ok\n' : `fail: ${manifest.slug}\n`);
-    }
-    if (!ok) {
-      process.exitCode = 1;
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      validateRestoreFlags(opts);
+      const cas = createCas(opts.cwd);
+      const treeOid = opts.oid || (await cas.resolveVaultEntry({ slug: opts.slug }));
+      const manifest = await cas.readManifest({ treeOid });
+      const ok = await cas.verifyIntegrity(manifest);
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(
+          `${JSON.stringify({ ok, slug: manifest.slug, chunks: manifest.chunks.length })}\n`
+        );
+      } else {
+        process.stdout.write(ok ? 'ok\n' : `fail: ${manifest.slug}\n`);
+      }
+      if (!ok) {
+        process.exitCode = 1;
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // doctor
@@ -423,53 +508,66 @@ program
   .command('doctor')
   .description('Inspect vault health and surface integrity issues')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const report = await inspectVaultHealth(cas);
-    const json = program.opts().json;
-
-    if (json) {
-      process.stdout.write(`${JSON.stringify(report)}\n`);
-    } else {
-      process.stdout.write(renderDoctorReport(report));
-    }
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const report = await inspectVaultHealth(cas);
+      const json = program.opts().json;
 
-    if (report.status !== 'ok') {
-      process.exitCode = 1;
-    }
-  }, getJson));
+      if (json) {
+        process.stdout.write(`${JSON.stringify(report)}\n`);
+      } else {
+        process.stdout.write(renderDoctorReport(report));
+      }
+
+      if (report.status !== 'ok') {
+        process.exitCode = 1;
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault init
 // ---------------------------------------------------------------------------
-const vault = program
-  .command('vault')
-  .description('Manage the CAS vault');
+const vault = program.command('vault').description('Manage the CAS vault');
 
 vault
   .command('init')
   .description('Initialize the vault')
-  .option('--vault-passphrase <pass>', 'Passphrase for vault-level encryption (prefer GIT_CAS_PASSPHRASE env var)')
+  .option(
+    '--vault-passphrase <pass>',
+    'Passphrase for vault-level encryption (prefer GIT_CAS_PASSPHRASE env var)'
+  )
   .option('--vault-passphrase-file <path>', 'Read vault passphrase from file (use - for stdin)')
-  .addOption(new Option('--algorithm <alg>', 'KDF algorithm').choices(['pbkdf2', 'scrypt']).default('pbkdf2'))
+  .addOption(new Option('--algorithm <alg>', 'KDF algorithm').choices(['pbkdf2', 'scrypt']))
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    /** @type {{ passphrase?: string, kdfOptions?: { algorithm: 'pbkdf2' | 'scrypt' } }} */
-    const initOpts = {};
-    const passphrase = await resolvePassphrase(opts, { confirm: true });
-    if (passphrase) {
-      initOpts.passphrase = passphrase;
-      initOpts.kdfOptions = { algorithm: /** @type {'pbkdf2' | 'scrypt'} */ (opts.algorithm) };
-    }
-    const { commitOid } = await cas.initVault(initOpts);
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ commitOid })}\n`);
-    } else {
-      process.stdout.write(`${commitOid}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      validateCredentialSources(opts);
+      const cas = createCas(opts.cwd);
+      /** @type {{ passphrase?: string, kdfOptions?: { algorithm: 'pbkdf2' | 'scrypt' } }} */
+      const initOpts = {};
+      const passphrase = await resolvePassphrase(opts, { confirm: true });
+      if (!passphrase && opts.algorithm !== undefined) {
+        throw new Error(
+          'Provide --vault-passphrase or --vault-passphrase-file when using --algorithm'
+        );
+      }
+      if (passphrase) {
+        initOpts.passphrase = passphrase;
+        initOpts.kdfOptions = {
+          algorithm: /** @type {'pbkdf2' | 'scrypt'} */ (opts.algorithm || 'pbkdf2'),
+        };
+      }
+      const { commitOid } = await cas.initVault(initOpts);
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ commitOid })}\n`);
+      } else {
+        process.stdout.write(`${commitOid}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault list
@@ -479,19 +577,21 @@ vault
   .description('List vault entries')
   .option('--filter <pattern>', 'Filter entries by glob pattern')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const all = await cas.listVault();
-    const entries = filterEntries(all, opts.filter);
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify(entries)}\n`);
-    } else if (process.stdout.isTTY) {
-      process.stdout.write(formatTable(entries));
-    } else {
-      process.stdout.write(formatTabSeparated(entries));
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const all = await cas.listVault();
+      const entries = filterEntries(all, opts.filter);
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify(entries)}\n`);
+      } else if (process.stdout.isTTY) {
+        process.stdout.write(formatTable(entries));
+      } else {
+        process.stdout.write(formatTabSeparated(entries));
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault stats
@@ -501,23 +601,25 @@ vault
   .description('Summarize vault size, dedupe, and encryption coverage')
   .option('--filter <pattern>', 'Filter entries by glob pattern')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const all = await cas.listVault();
-    const entries = filterEntries(all, opts.filter);
-    const records = [];
-    for (const entry of entries) {
-      const manifest = await cas.readManifest({ treeOid: entry.treeOid });
-      records.push({ ...entry, manifest });
-    }
-    const stats = buildVaultStats(records);
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify(stats)}\n`);
-    } else {
-      process.stdout.write(renderVaultStats(stats));
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const all = await cas.listVault();
+      const entries = filterEntries(all, opts.filter);
+      const records = [];
+      for (const entry of entries) {
+        const manifest = await cas.readManifest({ treeOid: entry.treeOid });
+        records.push({ ...entry, manifest });
+      }
+      const stats = buildVaultStats(records);
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify(stats)}\n`);
+      } else {
+        process.stdout.write(renderVaultStats(stats));
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault remove
@@ -526,16 +628,18 @@ vault
   .command('remove <slug>')
   .description('Remove an entry from the vault')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const { commitOid, removedTreeOid } = await cas.removeFromVault({ slug });
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ commitOid, removedTreeOid })}\n`);
-    } else {
-      process.stdout.write(`${removedTreeOid}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const { commitOid, removedTreeOid } = await cas.removeFromVault({ slug });
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ commitOid, removedTreeOid })}\n`);
+      } else {
+        process.stdout.write(`${removedTreeOid}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault info
@@ -545,29 +649,31 @@ vault
   .description('Show info for a vault entry')
   .option('--encryption', 'Show vault encryption details')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const treeOid = await cas.resolveVaultEntry({ slug });
-    const json = program.opts().json;
-    if (json) {
-      /** @type {Record<string, any>} */
-      const result = { slug, treeOid };
-      if (opts.encryption) {
-        const metadata = await cas.getVaultMetadata();
-        if (metadata?.encryption) {
-          result.encryption = metadata.encryption;
+  .action(
+    runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const treeOid = await cas.resolveVaultEntry({ slug });
+      const json = program.opts().json;
+      if (json) {
+        /** @type {Record<string, any>} */
+        const result = { slug, treeOid };
+        if (opts.encryption) {
+          const metadata = await cas.getVaultMetadata();
+          if (metadata?.encryption) {
+            result.encryption = metadata.encryption;
+          }
+        }
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+      } else {
+        process.stdout.write(`slug\t${slug}\n`);
+        process.stdout.write(`tree\t${treeOid}\n`);
+        if (opts.encryption) {
+          const metadata = await cas.getVaultMetadata();
+          process.stdout.write(`\n${renderEncryptionCard({ metadata })}\n`);
         }
       }
-      process.stdout.write(`${JSON.stringify(result)}\n`);
-    } else {
-      process.stdout.write(`slug\t${slug}\n`);
-      process.stdout.write(`tree\t${treeOid}\n`);
-      if (opts.encryption) {
-        const metadata = await cas.getVaultMetadata();
-        process.stdout.write(`\n${renderEncryptionCard({ metadata })}\n`);
-      }
-    }
-  }, getJson));
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault history
@@ -578,33 +684,35 @@ vault
   .option('--cwd <dir>', 'Git working directory', '.')
   .option('-n, --max-count <n>', 'Limit number of commits')
   .option('--pretty', 'Render as color-coded timeline')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const plumbing = createGitPlumbing({ cwd: opts.cwd || '.' });
-    const args = ['log', '--oneline', ContentAddressableStore.VAULT_REF];
-    if (opts.maxCount) {
-      const n = parseInt(opts.maxCount, 10);
-      if (Number.isNaN(n) || n <= 0) {
-        throw new Error('--max-count must be a positive integer');
-      }
-      args.push(`-${n}`);
-    }
-    const output = await plumbing.execute({ args });
-    const json = program.opts().json;
-    if (json) {
-      const history = output
-        .split('\n')
-        .filter(Boolean)
-        .map((/** @type {string} */ line) => {
-          const [commitOid, ...messageParts] = line.trim().split(/\s+/);
-          return { commitOid, message: messageParts.join(' ') };
-        });
-      process.stdout.write(`${JSON.stringify(history)}\n`);
-    } else if (opts.pretty && process.stdout.isTTY) {
-      process.stdout.write(`${renderHistoryTimeline(output)}\n`);
-    } else {
-      process.stdout.write(`${output}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      const plumbing = createGitPlumbing({ cwd: opts.cwd || '.' });
+      const args = ['log', '--oneline', ContentAddressableStore.VAULT_REF];
+      if (opts.maxCount) {
+        const n = parseInt(opts.maxCount, 10);
+        if (Number.isNaN(n) || n <= 0) {
+          throw new Error('--max-count must be a positive integer');
+        }
+        args.push(`-${n}`);
+      }
+      const output = await plumbing.execute({ args });
+      const json = program.opts().json;
+      if (json) {
+        const history = output
+          .split('\n')
+          .filter(Boolean)
+          .map((/** @type {string} */ line) => {
+            const [commitOid, ...messageParts] = line.trim().split(/\s+/);
+            return { commitOid, message: messageParts.join(' ') };
+          });
+        process.stdout.write(`${JSON.stringify(history)}\n`);
+      } else if (opts.pretty && process.stdout.isTTY) {
+        process.stdout.write(`${renderHistoryTimeline(output)}\n`);
+      } else {
+        process.stdout.write(`${output}\n`);
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault rotate
@@ -625,8 +733,12 @@ async function resolveRotatePassphrases(opts) {
   const newPassphrase = opts.newPassphraseFile
     ? await readPassphraseFile(opts.newPassphraseFile)
     : opts.newPassphrase;
-  if (!oldPassphrase) { throw new Error('Old passphrase required (--old-passphrase or --old-passphrase-file)'); }
-  if (!newPassphrase) { throw new Error('New passphrase required (--new-passphrase or --new-passphrase-file)'); }
+  if (!oldPassphrase || !oldPassphrase.trim()) {
+    throw new Error('Old passphrase required (--old-passphrase or --old-passphrase-file)');
+  }
+  if (!newPassphrase || !newPassphrase.trim()) {
+    throw new Error('New passphrase required (--new-passphrase or --new-passphrase-file)');
+  }
   return { oldPassphrase, newPassphrase };
 }
 
@@ -639,31 +751,33 @@ vault
   .option('--new-passphrase-file <path>', 'Read new passphrase from file (- for stdin)')
   .addOption(new Option('--algorithm <alg>', 'KDF algorithm').choices(['pbkdf2', 'scrypt']))
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    const { oldPassphrase, newPassphrase } = await resolveRotatePassphrases(opts);
-    const cas = createCas(opts.cwd);
-    /** @type {{ oldPassphrase: string, newPassphrase: string, kdfOptions?: { algorithm: 'pbkdf2' | 'scrypt' } }} */
-    const rotateOpts = {
-      oldPassphrase,
-      newPassphrase,
-    };
-    if (opts.algorithm) {
-      rotateOpts.kdfOptions = { algorithm: /** @type {'pbkdf2' | 'scrypt'} */ (opts.algorithm) };
-    }
-    const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase(rotateOpts);
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ commitOid, rotatedSlugs, skippedSlugs })}\n`);
-    } else {
-      process.stdout.write(`${commitOid}\n`);
-      if (rotatedSlugs.length) {
-        process.stderr.write(`rotated: ${rotatedSlugs.join(', ')}\n`);
-      }
-      if (skippedSlugs.length) {
-        process.stderr.write(`skipped: ${skippedSlugs.join(', ')}\n`);
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      const { oldPassphrase, newPassphrase } = await resolveRotatePassphrases(opts);
+      const cas = createCas(opts.cwd);
+      /** @type {{ oldPassphrase: string, newPassphrase: string, kdfOptions?: { algorithm: 'pbkdf2' | 'scrypt' } }} */
+      const rotateOpts = {
+        oldPassphrase,
+        newPassphrase,
+      };
+      if (opts.algorithm) {
+        rotateOpts.kdfOptions = { algorithm: /** @type {'pbkdf2' | 'scrypt'} */ (opts.algorithm) };
       }
-    }
-  }, getJson));
+      const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase(rotateOpts);
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ commitOid, rotatedSlugs, skippedSlugs })}\n`);
+      } else {
+        process.stdout.write(`${commitOid}\n`);
+        if (rotatedSlugs.length) {
+          process.stderr.write(`rotated: ${rotatedSlugs.join(', ')}\n`);
+        }
+        if (skippedSlugs.length) {
+          process.stderr.write(`skipped: ${skippedSlugs.join(', ')}\n`);
+        }
+      }
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // vault dashboard
@@ -672,21 +786,26 @@ vault
   .command('dashboard')
   .description('Interactive CAS explorer')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .option('--ref <gitRef>', 'Inspect a git ref that points to a CAS tree, CAS index blob, or commit with a manifest hint')
+  .option(
+    '--ref <gitRef>',
+    'Inspect a git ref that points to a CAS tree, CAS index blob, or commit with a manifest hint'
+  )
   .option('--oid <treeOid>', 'Inspect a direct CAS tree OID')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    if (opts.ref && opts.oid) {
-      throw new Error('Choose either --ref or --oid, not both');
-    }
-    const cas = createCas(opts.cwd);
-    const { launchDashboard } = await import('./ui/dashboard.js');
-    const source = opts.ref
-      ? { type: 'ref', ref: opts.ref }
-      : opts.oid
-        ? { type: 'oid', treeOid: opts.oid }
-        : { type: 'vault' };
-    await launchDashboard(cas, { cwd: path.resolve(opts.cwd), source });
-  }, getJson));
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      if (opts.ref && opts.oid) {
+        throw new Error('Choose either --ref or --oid, not both');
+      }
+      const cas = createCas(opts.cwd);
+      const { launchDashboard } = await import('./ui/dashboard.js');
+      const source = opts.ref
+        ? { type: 'ref', ref: opts.ref }
+        : opts.oid
+          ? { type: 'oid', treeOid: opts.oid }
+          : { type: 'vault' };
+      await launchDashboard(cas, { cwd: path.resolve(opts.cwd), source });
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // rotate
@@ -700,43 +819,47 @@ program
   .requiredOption('--new-key-file <path>', 'Path to new 32-byte key file')
   .option('--label <label>', 'Rotate only the named recipient')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
-    validateRestoreFlags(opts);
-    const cas = createCas(opts.cwd);
-    const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
-    const manifest = await cas.readManifest({ treeOid });
-
-    const oldKey = readKeyFile(opts.oldKeyFile);
-    const newKey = readKeyFile(opts.newKeyFile);
-
-    /** @type {{ manifest: Manifest, oldKey: Buffer, newKey: Buffer, label?: string }} */
-    const rotateOpts = { manifest, oldKey, newKey };
-    if (opts.label) { rotateOpts.label = opts.label; }
-
-    const updated = await cas.rotateKey(rotateOpts);
-    const json = program.opts().json;
+  .action(
+    runAction(async (/** @type {Record<string, any>} */ opts) => {
+      validateRestoreFlags(opts);
+      const cas = createCas(opts.cwd);
+      const treeOid = opts.oid || (await cas.resolveVaultEntry({ slug: opts.slug }));
+      const manifest = await cas.readManifest({ treeOid });
+
+      const oldKey = readKeyFile(opts.oldKeyFile);
+      const newKey = readKeyFile(opts.newKeyFile);
+
+      /** @type {{ manifest: Manifest, oldKey: Buffer, newKey: Buffer, label?: string }} */
+      const rotateOpts = { manifest, oldKey, newKey };
+      if (opts.label) {
+        rotateOpts.label = opts.label;
+      }
 
-    if (opts.slug) {
-      const newTreeOid = await cas.createTree({ manifest: updated });
-      await cas.addToVault({ slug: opts.slug, treeOid: newTreeOid, force: true });
-      if (json) {
-        process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid, keyVersion: updated.encryption?.keyVersion })}\n`);
+      const updated = await cas.rotateKey(rotateOpts);
+      const json = program.opts().json;
+
+      if (opts.slug) {
+        const newTreeOid = await cas.createTree({ manifest: updated });
+        await cas.addToVault({ slug: opts.slug, treeOid: newTreeOid, force: true });
+        if (json) {
+          process.stdout.write(
+            `${JSON.stringify({ treeOid: newTreeOid, keyVersion: updated.encryption?.keyVersion })}\n`
+          );
+        } else {
+          process.stdout.write(`${newTreeOid}\n`);
+        }
+      } else if (json) {
+        process.stdout.write(`${JSON.stringify(updated.toJSON())}\n`);
       } else {
-        process.stdout.write(`${newTreeOid}\n`);
+        process.stdout.write(`${JSON.stringify(updated.toJSON(), null, 2)}\n`);
       }
-    } else if (json) {
-      process.stdout.write(`${JSON.stringify(updated.toJSON())}\n`);
-    } else {
-      process.stdout.write(`${JSON.stringify(updated.toJSON(), null, 2)}\n`);
-    }
-  }, getJson));
+    }, getJson)
+  );
 
 // ---------------------------------------------------------------------------
 // recipient add / remove / list
 // ---------------------------------------------------------------------------
-const recipient = program
-  .command('recipient')
-  .description('Manage envelope encryption recipients');
+const recipient = program.command('recipient').description('Manage envelope encryption recipients');
 
 recipient
   .command('add <slug>')
@@ -745,74 +868,80 @@ recipient
   .requiredOption('--key-file <path>', 'Path to 32-byte key file for the new recipient')
   .requiredOption('--existing-key-file <path>', 'Path to key file of an existing recipient')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const treeOid = await cas.resolveVaultEntry({ slug });
-    const manifest = await cas.readManifest({ treeOid });
-
-    const existingKey = readKeyFile(opts.existingKeyFile);
-    const newRecipientKey = readKeyFile(opts.keyFile);
-
-    const updated = await cas.addRecipient({
-      manifest,
-      existingKey,
-      newRecipientKey,
-      label: opts.label,
-    });
-
-    const newTreeOid = await cas.createTree({ manifest: updated });
-    await cas.addToVault({ slug, treeOid: newTreeOid, force: true });
-
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid })}\n`);
-    } else {
-      process.stdout.write(`${newTreeOid}\n`);
-    }
-  }, getJson));
+  .action(
+    runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const treeOid = await cas.resolveVaultEntry({ slug });
+      const manifest = await cas.readManifest({ treeOid });
+
+      const existingKey = readKeyFile(opts.existingKeyFile);
+      const newRecipientKey = readKeyFile(opts.keyFile);
+
+      const updated = await cas.addRecipient({
+        manifest,
+        existingKey,
+        newRecipientKey,
+        label: opts.label,
+      });
+
+      const newTreeOid = await cas.createTree({ manifest: updated });
+      await cas.addToVault({ slug, treeOid: newTreeOid, force: true });
+
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid })}\n`);
+      } else {
+        process.stdout.write(`${newTreeOid}\n`);
+      }
+    }, getJson)
+  );
 
 recipient
   .command('remove <slug>')
   .description('Remove a recipient from an envelope-encrypted asset')
   .requiredOption('--label <label>', 'Label of the recipient to remove')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const treeOid = await cas.resolveVaultEntry({ slug });
-    const manifest = await cas.readManifest({ treeOid });
+  .action(
+    runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const treeOid = await cas.resolveVaultEntry({ slug });
+      const manifest = await cas.readManifest({ treeOid });
 
-    const updated = await cas.removeRecipient({ manifest, label: opts.label });
+      const updated = await cas.removeRecipient({ manifest, label: opts.label });
 
-    const newTreeOid = await cas.createTree({ manifest: updated });
-    await cas.addToVault({ slug, treeOid: newTreeOid, force: true });
+      const newTreeOid = await cas.createTree({ manifest: updated });
+      await cas.addToVault({ slug, treeOid: newTreeOid, force: true });
 
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid })}\n`);
-    } else {
-      process.stdout.write(`${newTreeOid}\n`);
-    }
-  }, getJson));
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid })}\n`);
+      } else {
+        process.stdout.write(`${newTreeOid}\n`);
+      }
+    }, getJson)
+  );
 
 recipient
   .command('list <slug>')
   .description('List recipients of an envelope-encrypted asset')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
-    const cas = createCas(opts.cwd);
-    const treeOid = await cas.resolveVaultEntry({ slug });
-    const manifest = await cas.readManifest({ treeOid });
-
-    const labels = await cas.listRecipients(manifest);
-    const json = program.opts().json;
-    if (json) {
-      process.stdout.write(`${JSON.stringify(labels)}\n`);
-    } else {
-      for (const label of labels) {
-        process.stdout.write(`${label}\n`);
+  .action(
+    runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
+      const cas = createCas(opts.cwd);
+      const treeOid = await cas.resolveVaultEntry({ slug });
+      const manifest = await cas.readManifest({ treeOid });
+
+      const labels = await cas.listRecipients(manifest);
+      const json = program.opts().json;
+      if (json) {
+        process.stdout.write(`${JSON.stringify(labels)}\n`);
+      } else {
+        for (const label of labels) {
+          process.stdout.write(`${label}\n`);
+        }
       }
-    }
-  }, getJson));
+    }, getJson)
+  );
 
 await program.parseAsync();
 
diff --git a/docs/BACKLOG/README.md b/docs/BACKLOG/README.md
new file mode 100644
index 0000000..bd58536
--- /dev/null
+++ b/docs/BACKLOG/README.md
@@ -0,0 +1,32 @@
+# Backlog
+
+Backlog items are single-file work items.
+
+They can be:
+
+- rough
+- partial
+- speculative
+- implementation-biased
+- design-biased
+
+That is fine. The backlog is allowed to be cheaper than a cycle doc.
+
+Naming convention:
+
+`<Legend code>-<numerical identifier>-<name>.md`
+
+Example:
+
+`RL-001-recipient-lifecycle.md`
+
+When work begins, the chosen backlog item should move or be copied into
+`docs/design/` and expanded into a full cycle doc.
+
+Current backlog items:
+
+- [RL-001 — Agent Recipient List](./RL-001-agent-recipient-list.md)
+- [RL-002 — Agent Recipient Mutations](./RL-002-agent-recipient-mutations.md)
+- [RL-003 — Agent Rotate](./RL-003-agent-rotate.md)
+- [RL-004 — Agent Vault Rotate](./RL-004-agent-vault-rotate.md)
+- [RL-005 — Agent Vault Lifecycle](./RL-005-agent-vault-lifecycle.md)
diff --git a/docs/BACKLOG/RL-001-agent-recipient-list.md b/docs/BACKLOG/RL-001-agent-recipient-list.md
new file mode 100644
index 0000000..1653531
--- /dev/null
+++ b/docs/BACKLOG/RL-001-agent-recipient-list.md
@@ -0,0 +1,44 @@
+# RL-001 — Agent Recipient List
+
+## Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Why This Exists
+
+Relay can now inspect, verify, store, restore, and create trees, but agents
+still cannot inspect envelope recipient state through a first-class contract.
+
+That is a real gap because recipient and rotation work comes next. Agents need a
+stable read path before they can mutate that lifecycle safely.
+
+## Target Outcome
+
+Add a machine-facing `git cas agent recipient list` command that reports
+recipient state without scraping human CLI output.
+
+## Human Value
+
+Operators building automation should be able to inspect recipient state
+confidently before attempting recipient mutation or key rotation.
+
+## Agent Value
+
+Agents should be able to determine:
+
+- whether an asset uses envelope recipients
+- which recipient labels exist
+- which tree was inspected
+
+without inferring from prose or TTY behavior.
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- keep the command read-only
+- support the normal Relay target model (`--slug` or `--oid`)
+- return structured recipient rows, not bare terminal text
+- leave add/remove/rotate for follow-on cycles
diff --git a/docs/BACKLOG/RL-002-agent-recipient-mutations.md b/docs/BACKLOG/RL-002-agent-recipient-mutations.md
new file mode 100644
index 0000000..86208ba
--- /dev/null
+++ b/docs/BACKLOG/RL-002-agent-recipient-mutations.md
@@ -0,0 +1,47 @@
+# RL-002 — Agent Recipient Mutations
+
+## Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Why This Exists
+
+Relay can now inspect recipient state, but an agent still cannot mutate the
+recipient lifecycle through a first-class contract.
+
+That blocks a real automation loop:
+
+- inspect recipients
+- add or remove recipients safely
+- later rotate recipient keys
+
+## Target Outcome
+
+Add machine-facing `git cas agent recipient add` and
+`git cas agent recipient remove` commands that make vault-updating side effects
+explicit.
+
+## Human Value
+
+Operators should be able to build recipient-management automation without
+falling back to the human CLI or scraping its output.
+
+## Agent Value
+
+Agents should be able to:
+
+- add a new recipient using an existing recipient key
+- remove a recipient by label
+- detect duplicate labels, missing labels, and last-recipient violations through
+  structured failures
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- keep the slice focused on `recipient add` and `recipient remove`
+- require explicit slug-based targeting because these commands update the vault
+- make the updated tree and commit side effects explicit in the result payload
+- leave `agent rotate` for the next cycle
diff --git a/docs/BACKLOG/RL-003-agent-rotate.md b/docs/BACKLOG/RL-003-agent-rotate.md
new file mode 100644
index 0000000..2c1fbe8
--- /dev/null
+++ b/docs/BACKLOG/RL-003-agent-rotate.md
@@ -0,0 +1,46 @@
+# RL-003 — Agent Rotate
+
+## Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Why This Exists
+
+Relay can now inspect recipients and mutate recipient membership, but an agent
+still cannot rotate a recipient key through a first-class contract.
+
+That leaves a hole in the machine-facing key lifecycle:
+
+- inspect recipient state
+- add or remove recipients
+- rotate a recipient key without falling back to the human CLI
+
+## Target Outcome
+
+Add machine-facing `git cas agent rotate` support that makes new trees and
+vault-updating side effects explicit.
+
+## Human Value
+
+Operators should be able to automate key rollover without scraping human CLI
+output or guessing whether the vault entry was updated.
+
+## Agent Value
+
+Agents should be able to:
+
+- rotate a recipient key for a vault entry by slug
+- rotate a detached tree by OID and receive the new tree directly
+- branch on recipient mismatch and unsupported-manifest failures through
+  structured protocol errors
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- accept either `--slug` or `--oid`
+- require explicit `--old-key-file` and `--new-key-file`
+- allow optional `--label` for targeted rotation
+- make detached-tree rotation explicit instead of pretending it updated the vault
diff --git a/docs/BACKLOG/RL-004-agent-vault-rotate.md b/docs/BACKLOG/RL-004-agent-vault-rotate.md
new file mode 100644
index 0000000..0485005
--- /dev/null
+++ b/docs/BACKLOG/RL-004-agent-vault-rotate.md
@@ -0,0 +1,44 @@
+# RL-004 — Agent Vault Rotate
+
+## Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Why This Exists
+
+Relay can now rotate recipient keys, but vault passphrase rotation is still
+human-CLI-only.
+
+That keeps the machine-facing key lifecycle incomplete:
+
+- rotate recipient keys for one asset
+- rotate vault passphrase for all envelope-backed vault entries
+
+## Target Outcome
+
+Add machine-facing `git cas agent vault rotate` support that makes commit-side
+effects, rotated/skipped entries, and resulting KDF state explicit.
+
+## Human Value
+
+Operators should be able to automate vault passphrase rotation without scraping
+human CLI text or guessing whether the vault metadata actually changed.
+
+## Agent Value
+
+Agents should be able to:
+
+- rotate an encrypted vault with explicit old/new passphrase sources
+- read rotated and skipped slug lists directly
+- branch on invalid input, wrong passphrase, and unencrypted-vault failures
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- keep the command under `agent vault ...`
+- support direct passphrase fields and passphrase-file sources
+- make the resulting KDF algorithm explicit in the result payload
+- do not add prompts or TTY-dependent fallback behavior
diff --git a/docs/BACKLOG/RL-005-agent-vault-lifecycle.md b/docs/BACKLOG/RL-005-agent-vault-lifecycle.md
new file mode 100644
index 0000000..58fa915
--- /dev/null
+++ b/docs/BACKLOG/RL-005-agent-vault-lifecycle.md
@@ -0,0 +1,46 @@
+# RL-005 — Agent Vault Lifecycle
+
+## Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Why This Exists
+
+Relay can now read vault state and rotate vault passphrases, but the machine
+surface still cannot create a vault or remove an entry directly.
+
+That leaves the basic vault lifecycle split across human and agent surfaces:
+
+- initialize a vault
+- inspect and mutate its entries
+- rotate its passphrase
+- remove entries from the vault
+
+## Target Outcome
+
+Add machine-facing `git cas agent vault init` and `git cas agent vault remove`
+commands with explicit commit-side effects.
+
+## Human Value
+
+Operators should be able to bootstrap and prune vault state through automation
+without scraping CLI text or falling back to human-only flows.
+
+## Agent Value
+
+Agents should be able to:
+
+- initialize plaintext or encrypted vaults
+- remove entries by slug
+- branch on missing inputs and missing entries through structured errors
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- keep both commands under `agent vault ...`
+- preserve strict non-interactive passphrase handling for `vault init`
+- make commit-side effects explicit in success rows
+- keep the slice bounded to init and remove, not list/info/history
diff --git a/docs/design/0001-m18-relay-agent-cli.md b/docs/design/0001-m18-relay-agent-cli.md
new file mode 100644
index 0000000..af874ee
--- /dev/null
+++ b/docs/design/0001-m18-relay-agent-cli.md
@@ -0,0 +1,324 @@
+# 0001 — M18 Relay: Agent CLI Foundation
+
+## Status
+
+Proposed
+
+## Context
+
+`git-cas` now has a real human surface and a missing machine surface.
+
+What is already true:
+
+- the human CLI/TUI can store, inspect, verify, restore, rotate, manage vault
+  entries, and explore repository-backed CAS state
+- `--json` exists on the human CLI, but it is convenience structured output, not
+  a first-class automation contract
+- `main` already contains early human-surface explorer work beyond the old docs
+
+What is still missing:
+
+- a machine-native entrypoint
+- stable protocol semantics
+- explicit non-interactive input handling
+- exact exit-code behavior
+- a clean app-layer boundary that the human surface can later reuse
+
+The product gap is now protocol, not raw capability.
+
+## Sponsor User
+
+A maintainer or release engineer who wants to automate `git-cas` workflows
+without scraping human terminal text.
+
+## Sponsor Agent
+
+A coding agent, CI job, release bot, or backup workflow that needs exact,
+replayable outcomes and explicit side effects.
+
+## Hills
+
+- A sponsor agent can inspect, verify, and query `git-cas` state through a
+  stable machine protocol without depending on TTY behavior or human-readable
+  formatting.
+- A sponsor user can trust automation built on `git-cas` because failures,
+  warnings, and requested inputs are explicit and machine-actionable.
+
+## Explicit Non-Goals
+
+- No long-lived interactive session protocol.
+- No attempt to redefine the human `--json` path as the automation contract.
+- No Bijou rendering or TTY-aware formatting in the agent path.
+- No binary restore payload over protocol `stdout`.
+- No large human-surface feature push before the machine surface is credible.
+
+## Decision
+
+Introduce a dedicated `git cas agent` namespace with a JSONL-first contract.
+
+The agent CLI will:
+
+- use a dedicated machine runner rather than the current human `runAction()` path
+- treat every invocation as a one-shot command
+- accept explicit flags plus `--request -` and `--request @file.json`
+- avoid implicit prompts entirely
+- produce protocol rows instead of human terminal text
+- separate human convenience output from machine contract design
+
+## Protocol Principles
+
+- Deterministic enough to be tested across Node, Bun, and Deno.
+- Explicit about side effects.
+- Explicit about missing inputs.
+- Explicit about failure class.
+- Replayable from captured rows.
+- Safe to consume without parsing prose.
+
+## Stream Contract
+
+The agent CLI uses JSONL on both streams, with different responsibilities:
+
+- `stdout`: lifecycle and ordinary command data
+- `stderr`: structured warnings, `needs-input`, and structured errors
+
+After the first protocol row is emitted, both streams are protocol-only.
+
+Human-readable text is suppressed.
+
+## Record Envelope
+
+Every row is one JSON object with this envelope:
+
+```json
+{
+  "protocol": "git-cas-agent/v1",
+  "command": "inspect",
+  "type": "result",
+  "seq": 3,
+  "ts": "2026-03-26T01:23:45.678Z",
+  "data": {}
+}
+```
+
+Required fields:
+
+- `protocol`: string version identifier
+- `command`: command name without the `git cas agent` prefix
+- `type`: record type
+- `seq`: monotonically increasing integer per invocation
+- `ts`: RFC 3339 UTC timestamp
+- `data`: record payload object
+
+## Record Types
+
+### `start`
+
+Emitted on `stdout` once the command has validated argv and normalized its input.
+
+Purpose:
+
+- confirm the resolved command
+- expose normalized request shape
+- expose side-effect intent before work begins
+
+### `progress`
+
+Emitted on `stdout` zero or more times.
+
+Purpose:
+
+- communicate bounded work-state changes without forcing humans to scrape TUI
+- carry stable progress semantics for long-running reads and writes
+
+### `warning`
+
+Emitted on `stderr` zero or more times.
+
+Purpose:
+
+- communicate non-fatal issues
+- surface policy and safety signals without poisoning `stdout`
+
+Examples:
+
+- encryption-policy warnings
+- ignored optional input
+- degraded fallback behavior
+
+### `needs-input`
+
+Emitted on `stderr` when required input is missing or must be supplied through a
+request object instead of an interactive prompt.
+
+Purpose:
+
+- replace prompting
+- allow agents to branch cleanly
+
+Examples:
+
+- missing passphrase file
+- missing encryption key source
+- missing request payload for a required machine-only field
+
+### `result`
+
+Emitted on `stdout` one or more times with ordinary command data.
+
+Purpose:
+
+- carry the machine-usable result payload
+- avoid trace noise in ordinary data rows
+
+### `error`
+
+Emitted on `stderr` for fatal failures.
+
+Purpose:
+
+- expose a stable machine-readable failure record
+- preserve error code, message, and optional metadata
+
+### `end`
+
+Emitted on `stdout` exactly once for successful or protocol-complete invocations.
+
+Purpose:
+
+- mark normal protocol completion
+- summarize exit status and row counts
+
+## Exit Codes
+
+Initial exit-code policy:
+
+- `0`: success
+- `1`: fatal execution failure
+- `2`: required input missing, invalid request payload, or `needs-input`
+- `3`: integrity or verification failure
+
+This must be consistent across Node, Bun, and Deno.
+
+## Request Handling
+
+The agent CLI supports three input shapes:
+
+1. normal explicit flags
+2. `--request @file.json`
+3. `--request -` for JSON request payload on stdin
+
+Rules:
+
+- request payloads augment flags; they do not silently reinterpret them
+- conflicts between flags and request payload must fail explicitly
+- secrets are passed by explicit source, never by prompt
+- the normalized request shape should be visible in the `start` payload when it
+  is safe to expose
+
+## Command Rollout
+
+### Foundation Wave
+
+These commands come first because they are read-heavy and define the contract
+shape without forcing the full write-path problem on day one:
+
+- `agent inspect`
+- `agent verify`
+- `agent vault list`
+- `agent vault info`
+- `agent vault history`
+- `agent doctor`
+- `agent vault stats`
+
+### Follow-through Wave
+
+These commands follow once the protocol and request semantics are proven:
+
+- `agent store`
+- `agent tree`
+- `agent restore`
+- `agent rotate`
+- `agent recipient add`
+- `agent recipient remove`
+- `agent recipient list`
+- the relevant vault write flows
+
+## Data Shape Principles
+
+Command payloads should:
+
+- expose real command data, not just trace metadata
+- preserve domain terms where they are materially useful
+- avoid TUI-specific or Bijou-specific concepts
+- avoid requiring agents to infer state from absent fields
+
+Examples:
+
+- `inspect` should expose manifest/tree information
+- `verify` should expose integrity result and chunk counts
+- `vault list` should expose entry rows, not formatted tables
+- `doctor` should expose issue rows, not prose reports
+
+## Error Shape
+
+Structured error payloads should include:
+
+- `code`
+- `message`
+- `hint` when useful
+- `meta` when stable and actionable
+- `retryable` when the caller can safely branch on it
+
+The agent CLI should reuse existing domain error codes where they are already
+good enough instead of inventing parallel code vocabularies.
+
+## Human Surface Consequence
+
+The human CLI and TUI should eventually consume the same application-layer
+operations and normalized result models that fall out of the agent CLI.
+
+That does not mean the human surface becomes JSONL-first.
+It means the agent CLI should force the shared boundary to become explicit.
+
+The TUI should become a client of that boundary, not its substitute.
+
+## Testing Plan
+
+The protocol contract must be test-first.
+
+Contract tests should pin:
+
+- record order
+- record shape
+- stream purity
+- exact exit codes
+- missing-input behavior
+- integrity-failure behavior
+- non-interactive behavior across Node, Bun, and Deno
+
+Tests should avoid:
+
+- timing assertions
+- TTY assumptions
+- shell-wrapped subprocesses
+- human-text snapshots as protocol truth
+
+## Acceptance
+
+M18 is complete when:
+
+- the protocol is documented in-repo
+- read-heavy `git cas agent` commands exist
+- protocol contract tests pass on Node, Bun, and Deno
+- `stdout` and `stderr` roles are explicit and stable
+- missing-input flows are machine-actionable instead of interactive
+- the agent surface is clearly no longer “human CLI plus `--json`”
+
+## Open Questions
+
+- Should `end` always emit on failure, or only on successful protocol completion?
+- Which warnings deserve protocol rows versus result metadata?
+- How much normalized request data is safe to echo in `start` when secrets are
+  involved?
+- Which state-changing flows belong in the first follow-through wave versus a
+  later parity wave?
diff --git a/docs/design/0002-m18-relay-write-flows.md b/docs/design/0002-m18-relay-write-flows.md
new file mode 100644
index 0000000..3348a63
--- /dev/null
+++ b/docs/design/0002-m18-relay-write-flows.md
@@ -0,0 +1,161 @@
+# 0002 — M18 Relay: Write Flows and Input Semantics
+
+## Status
+
+Proposed
+
+## Context
+
+`0001` established the Relay foundation for read-heavy commands and the JSONL
+record envelope.
+
+The next gap is not protocol shape. It is write behavior:
+
+- `store` must report side effects explicitly
+- `restore` must write files without polluting protocol `stdout`
+- encrypted flows must never fall back to prompting
+- missing credentials must be distinguishable from generic failures
+
+This is the boundary-forcing step for the agent surface.
+
+## Sponsor User
+
+A maintainer who wants to automate storage and restore workflows without human
+escape hatches in the normal success path.
+
+## Sponsor Agent
+
+An agent or CI workflow that must perform state-changing `git-cas` operations
+with exact inputs, explicit side effects, and deterministic recovery branches.
+
+## Hills
+
+- A sponsor agent can `store` and `restore` through Relay without scraping
+  human text, and can reason about what changed from protocol output alone.
+- A sponsor user can trust encrypted automation because missing credentials are
+  surfaced as `needs-input`, not hidden prompts or ambiguous failures.
+
+## Explicit Non-Goals
+
+- No long-lived interactive session.
+- No binary payload on protocol `stdout`.
+- No implicit prompting for passphrases or key material.
+- No attempt to redesign the human `store` and `restore` UX in this slice.
+- No full write-surface parity beyond `store` and `restore` yet.
+
+## Decisions
+
+### `agent store`
+
+Initial Relay write support for `store` will mirror the human CLI shape closely
+enough to preserve product behavior:
+
+- input file may be supplied positionally or via request payload
+- `slug` remains required
+- `--tree` creates a CAS tree and updates the vault
+- `--force` is valid only with `--tree`
+- plaintext store is valid when no encryption source is supplied
+- vault-level encryption may be supplied by:
+  - `--key-file <path>`
+  - `--vault-passphrase <pass>`
+  - `--vault-passphrase-file <path|->`
+
+`result` for a successful `store` must expose:
+
+- `slug`
+- `manifest`
+- `treeOid` when created
+- `commitOid` when the vault changed
+- `addedToVault`
+- `chunkCount`
+- `encrypted`
+- `compressed`
+
+### `agent restore`
+
+Relay restore remains file-output only. It never emits restored bytes to
+protocol `stdout`.
+
+Required input:
+
+- `--out <path>`
+- exactly one of `--slug` or `--oid`
+
+Credential sources:
+
+- `--key-file <path>`
+- `--vault-passphrase <pass>`
+- `--vault-passphrase-file <path|->`
+
+`result` for a successful `restore` must expose:
+
+- `slug`
+- `treeOid`
+- `outputPath`
+- `bytesWritten`
+- `encrypted`
+
+## `needs-input` Semantics
+
+Relay uses `needs-input` when the command is otherwise valid but cannot proceed
+because required credentials are missing.
+
+Initial cases in scope:
+
+- encrypted restore with no key source
+- restore branches where the command can identify the accepted credential
+  sources before attempting work
+
+`needs-input` data should include:
+
+- `code`
+- `message`
+- `requiredInputs`
+- command-specific context that helps an agent retry correctly
+
+This is not a generic validation bucket. Bad flags, conflicting sources, or
+impossible stdin combinations remain ordinary `error` / invalid-input failures.
+
+## Request Handling
+
+Write flows continue to accept:
+
+1. explicit flags
+2. `--request @file.json`
+3. `--request -`
+
+Rules:
+
+- flags override request-object fields
+- request objects may provide ordinary command fields like `file`, `slug`, and
+  `out`
+- secrets may be passed explicitly, but Relay must not silently consume the same
+  stdin stream for both the request object and a passphrase file
+- `--request -` combined with `--vault-passphrase-file -` is invalid
+
+## Protocol Consequences
+
+- `stdout` stays protocol-only for both commands
+- `stderr` carries `needs-input` or fatal `error` rows when applicable
+- `end` still closes the invocation on both success and failure
+- side effects are communicated through structured `result` payloads rather than
+  human summaries
+
+## Testing Plan
+
+Contract coverage for this slice must pin:
+
+- successful plaintext `agent store`
+- successful plaintext `agent restore`
+- successful encrypted `agent store`
+- successful encrypted `agent restore`
+- encrypted restore with missing credentials emits `needs-input` and exits `2`
+- `stdout` remains JSONL-only throughout write flows
+- behavior is consistent across Node, Bun, and Deno
+
+## Acceptance
+
+- `agent store` and `agent restore` are implemented and documented
+- side effects are explicit in `result` rows
+- encrypted missing-credential branches emit `needs-input`
+- the supported runtime matrix passes for unit and integration suites
diff --git a/docs/design/0003-m18-relay-tree-creation.md b/docs/design/0003-m18-relay-tree-creation.md
new file mode 100644
index 0000000..edb6b98
--- /dev/null
+++ b/docs/design/0003-m18-relay-tree-creation.md
@@ -0,0 +1,88 @@
+# 0003 — M18 Relay: Tree Creation Primitive
+
+## Status
+
+Proposed
+
+## Context
+
+Relay now supports read commands plus the `store` and `restore` write boundary.
+
+The next useful primitive is `agent tree`:
+
+- it lets an agent materialize a Git tree from a manifest without scraping the
+  human CLI
+- it is a shared building block for later repo automation and TUI follow-on
+  work
+- it adds machine-native manifest input without dragging vault mutation into the
+  same slice
+
+## Sponsor User
+
+A maintainer who wants machine-driven manifest workflows to use the same core
+tree-creation behavior as the human CLI.
+
+## Sponsor Agent
+
+An agent that already has manifest data and needs a stable way to create a Git
+tree from it without writing terminal-oriented glue code.
+
+## Hills
+
+- A sponsor agent can create a CAS tree from either a manifest file or an
+  inline request-object manifest and receive the resulting `treeOid` as
+  protocol data.
+- A sponsor user can trust that Relay tree creation uses the same manifest
+  validation rules as the existing domain model.
+
+## Explicit Non-Goals
+
+- No vault mutation in this slice.
+- No manifest editing workflow.
+- No binary input or output path handling.
+- No attempt to redesign the human `tree` command.
+
+## Decisions
+
+### Input shape
+
+`agent tree` accepts manifest input in two forms:
+
+- `--manifest <path>` for parity with the human CLI
+- `request.manifest` as an inline JSON object for agent-native use
+
+If both exist, flags win because Relay flags override request-object fields.
+
+### Validation
+
+Both input forms are validated through the existing `Manifest` value object.
+Relay should not create a second manifest schema or parallel validation path.
+
+### Result shape
+
+Successful `result` rows should expose:
+
+- `treeOid`
+- `slug`
+- `chunkCount`
+- `encrypted`
+- `compressed`
+
+This is enough for an agent to branch on tree creation without re-reading the
+manifest immediately.
+
+## Testing Plan
+
+Contract coverage for this slice must pin:
+
+- successful `agent tree --manifest <path>`
+- successful `agent tree` with `request.manifest`
+- invalid input when no manifest source is supplied
+- JSONL-only protocol behavior on `stdout`
+
+## Acceptance
+
+- `agent tree` is implemented in Relay
+- manifest file and inline request-object inputs both work
+- invalid-input behavior stays structured
+- the supported runtime matrix passes
diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 0000000..a199a51
--- /dev/null
+++ b/docs/design/README.md
@@ -0,0 +1,29 @@
+# Design Docs
+
+This directory holds pre-implementation design docs for `git-cas`.
+
+The working rules are simple:
+
+- design docs come first
+- executable tests come second
+- implementation comes third
+- `main` is the playback truth
+
+New cycle docs should follow the workflow in [WORKFLOW.md](../../WORKFLOW.md)
+and use legend-code naming:
+
+`<Legend code>-<numerical identifier>-<name>.md`
+
+The existing `0001`/`0002`/`0003` docs are legacy cycle docs from before that
+naming migration and can remain until they are touched.
+
+Current design docs:
+
+- [0001 — M18 Relay: Agent CLI Foundation](./0001-m18-relay-agent-cli.md)
+- [0002 — M18 Relay: Write Flows and Input Semantics](./0002-m18-relay-write-flows.md)
+- [0003 — M18 Relay: Tree Creation Primitive](./0003-m18-relay-tree-creation.md)
+- [RL-001 — Relay: Agent Recipient List](./RL-001-agent-recipient-list.md)
+- [RL-002 — Relay: Agent Recipient Mutations](./RL-002-agent-recipient-mutations.md)
+- [RL-003 — Relay: Agent Rotate](./RL-003-agent-rotate.md)
+- [RL-004 — Relay: Agent Vault Rotate](./RL-004-agent-vault-rotate.md)
+- [RL-005 — Relay: Agent Vault Lifecycle](./RL-005-agent-vault-lifecycle.md)
diff --git a/docs/design/RL-001-agent-recipient-list.md b/docs/design/RL-001-agent-recipient-list.md
new file mode 100644
index 0000000..ad94497
--- /dev/null
+++ b/docs/design/RL-001-agent-recipient-list.md
@@ -0,0 +1,153 @@
+# RL-001 — Relay: Agent Recipient List
+
+## Status
+
+Active
+
+## Linked Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Context
+
+Relay now has the first read-heavy commands plus initial write primitives.
+
+The next bounded gap is recipient inspection. Before an agent can safely add,
+remove, or rotate recipients, it needs a stable way to inspect the current
+recipient state.
+
+This cycle keeps the slice read-only on purpose.
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- release engineers
+- operators preparing recipient or rotation changes
+
+### Jobs
+
+- inspect envelope recipient state before mutation
+- confirm that automation is pointed at the right asset
+
+### Hill
+
+A human operator can trust automation around recipient lifecycle work because
+recipient inspection is explicit and structured before any write path lands.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- CI jobs
+- release workflows
+
+### Jobs
+
+- resolve recipient state from a stable command
+- branch on envelope vs non-envelope assets
+- prepare for add, remove, and rotate operations
+
+### Hill
+
+An agent can inspect recipient state through `git cas agent recipient list`
+without scraping human CLI output and without guessing whether the asset is
+envelope-encrypted.
+
+## Human Playback
+
+- Can an operator ask Relay for recipient state and get an obviously structured
+  answer?
+- Does the result clearly identify which asset and tree were inspected?
+
+## Agent Playback
+
+- Can an agent call one command and learn whether the asset uses recipients?
+- Can it get recipient labels in stable order without parsing prose?
+- Can it target by slug or OID like the other Relay inspection commands?
+
+## Explicit Non-Goals
+
+- no recipient mutation in this cycle
+- no key rotation in this cycle
+- no long-lived session behavior
+- no attempt to unify the human and agent command syntax beyond useful target
+  parity
+
+## Decisions
+
+### Command Shape
+
+Relay adds:
+
+- `git cas agent recipient list --slug <slug>`
+- `git cas agent recipient list --oid <tree-oid>`
+
+It also accepts request payloads that provide `slug` or `oid`, following the
+existing Relay target pattern.
+
+### Result Shape
+
+Successful `result` rows should expose:
+
+- `slug`
+- `treeOid`
+- `envelope`
+- `recipientCount`
+- `recipients`
+
+`recipients` should be a stable array of structured rows containing:
+
+- `label`
+- `keyVersion` when present
+
+### Non-Envelope Behavior
+
+This command remains successful for non-envelope assets.
+
+Instead of throwing, it should return:
+
+- `envelope: false`
+- `recipientCount: 0`
+- `recipients: []`
+
+That keeps inspection composable and avoids turning an expected state into an
+exception path.
+
+## Implementation Outline
+
+1. Add the new command to the Relay command registry.
+2. Extend namespace resolution to support `recipient ...` in the agent path.
+3. Reuse the existing target resolution flow (`--slug` or `--oid`).
+4. Read the manifest and normalize recipient rows for machine use.
+5. Keep the command read-only and protocol-only.
+
+## Tests To Write First
+
+- recipient list succeeds for an envelope-encrypted asset targeted by slug
+- recipient list succeeds for an envelope-encrypted asset targeted by request
+  payload or OID
+- recipient list returns `envelope: false` and an empty array for a non-envelope
+  asset
+- recipient list emits structured invalid-input when no target is provided
+
+These tests belong in the existing agent CLI integration suite because this
+slice extends the shared Relay protocol contract rather than introducing a new
+test namespace.
+
+## Risks And Unknowns
+
+- result shape should stay useful without leaking noisy recipient ciphertext
+  fields
+- future add/remove/rotate cycles will need to build on this shape without
+  breaking callers
+
+## Retrospective
+
+Pending.
diff --git a/docs/design/RL-002-agent-recipient-mutations.md b/docs/design/RL-002-agent-recipient-mutations.md
new file mode 100644
index 0000000..3f52e9f
--- /dev/null
+++ b/docs/design/RL-002-agent-recipient-mutations.md
@@ -0,0 +1,153 @@
+# RL-002 — Relay: Agent Recipient Mutations
+
+## Status
+
+Active
+
+## Linked Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Context
+
+Relay can now inspect recipient state with `agent recipient list`.
+
+The next bounded step is mutation parity for the envelope recipient lifecycle:
+
+- `agent recipient add`
+- `agent recipient remove`
+
+This is the first recipient-management write slice for the machine contract.
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- release engineers
+- operators automating envelope access changes
+
+### Jobs
+
+- grant a new recipient access using an existing trusted recipient key
+- remove a recipient explicitly and know what changed in the vault
+
+### Hill
+
+A human operator can trust recipient-management automation because the machine
+path makes vault-updating side effects explicit instead of hiding them behind
+human CLI text.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- CI jobs
+- release and access-management workflows
+
+### Jobs
+
+- add a recipient deterministically
+- remove a recipient deterministically
+- branch on duplicate-label, missing-label, and last-recipient failures without
+  parsing prose
+
+### Hill
+
+An agent can mutate envelope recipients through a stable Relay contract and
+learn exactly which tree and vault commit were produced.
+
+## Human Playback
+
+- Can an operator inspect the result and see what changed without additional
+  lookup commands?
+- Are failure modes specific enough to act on without opening the human CLI?
+
+## Agent Playback
+
+- Can an agent add a recipient using explicit key files and a slug target?
+- Can it remove a recipient and observe the new tree and commit directly?
+- Do expected domain failures surface as structured protocol errors?
+
+## Explicit Non-Goals
+
+- no recipient key rotation in this cycle
+- no OID-only mutation path
+- no implicit prompting for key material
+- no long-lived session behavior
+
+## Decisions
+
+### Command Shape
+
+Relay adds:
+
+- `git cas agent recipient add --slug <slug> --label <label> --key-file <path> --existing-key-file <path>`
+- `git cas agent recipient remove --slug <slug> --label <label>`
+
+Request payloads may also provide these fields.
+
+These commands stay slug-based because they update the vault entry, not just an
+arbitrary detached tree.
+
+### Result Shape
+
+Successful mutation `result` rows should expose:
+
+- `action`
+- `slug`
+- `label`
+- `previousTreeOid`
+- `treeOid`
+- `commitOid`
+- `recipientCount`
+- `recipients`
+
+`recipients` uses the same structured row shape as `recipient list`.
+
+### Error Behavior
+
+The command should preserve existing domain error codes where they already say
+the right thing:
+
+- `RECIPIENT_ALREADY_EXISTS`
+- `RECIPIENT_NOT_FOUND`
+- `CANNOT_REMOVE_LAST_RECIPIENT`
+- `DEK_UNWRAP_FAILED`
+
+Missing required flags remain `INVALID_INPUT`.
+
+## Implementation Outline
+
+1. Add `recipient add` and `recipient remove` to the Relay command registry.
+2. Parse explicit slug, label, and key-file inputs from flags or request
+   objects.
+3. Resolve the current vault tree and manifest by slug.
+4. Apply the existing domain recipient mutation methods.
+5. Create the new tree, update the vault, and return explicit side-effect data.
+
+## Tests To Write First
+
+- recipient add succeeds and reports the new tree, commit, and recipient rows
+- recipient add supports request-payload input
+- recipient remove succeeds and reports the new tree, commit, and recipient rows
+- duplicate recipient label surfaces as `RECIPIENT_ALREADY_EXISTS`
+- removing the last recipient surfaces as `CANNOT_REMOVE_LAST_RECIPIENT`
+
+These tests belong in the existing agent CLI integration suite because they are
+protocol contract tests over the Relay boundary.
+
+## Risks And Unknowns
+
+- the result shape must stay stable enough for later rotation work
+- slug-only targeting is deliberate here, but future detached-tree workflows may
+  want a different mutation path
+
+## Retrospective
+
+Pending.
diff --git a/docs/design/RL-003-agent-rotate.md b/docs/design/RL-003-agent-rotate.md
new file mode 100644
index 0000000..071ca23
--- /dev/null
+++ b/docs/design/RL-003-agent-rotate.md
@@ -0,0 +1,186 @@
+# RL-003 — Relay: Agent Rotate
+
+## Status
+
+Active
+
+## Linked Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Context
+
+Relay can now:
+
+- inspect recipient state
+- add recipients
+- remove recipients
+
+The next bounded gap is key rotation through the machine-facing contract.
+
+The human CLI already supports rotation. The Relay job here is not to invent a
+new domain behavior. It is to make the rotate workflow deterministic,
+non-interactive, and explicit about what changed.
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- release engineers
+- operators managing recipient rollover
+
+### Jobs
+
+- rotate an envelope recipient key without re-encrypting blob data
+- know whether the vault entry changed or whether the result is only a detached
+  tree
+
+### Hill
+
+A human operator can trust agent-driven key rotation because the resulting tree
+and vault side effects are explicit in the machine contract.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- CI jobs
+- access-management workflows
+
+### Jobs
+
+- rotate a recipient key by slug
+- rotate a detached manifest tree by OID
+- branch on no-match, unsupported-manifest, and recipient-label failures
+  without parsing prose
+
+### Hill
+
+An agent can rotate keys through Relay and learn exactly which tree was created
+and whether the vault was updated.
+
+## Human Playback
+
+- Can an operator see the new tree and vault update directly from the result
+  row?
+- Does the machine path make detached-tree behavior obvious instead of implying
+  a vault mutation that never happened?
+
+## Agent Playback
+
+- Can an agent rotate a slug-targeted vault entry and then restore via the new
+  key?
+- Can it rotate a detached tree by OID and receive a new tree without a vault
+  commit?
+- Do domain failures surface as structured protocol errors with stable codes?
+
+## Explicit Non-Goals
+
+- no vault passphrase rotation in this cycle
+- no recipient add/remove behavior in this cycle
+- no interactive key prompts
+- no long-lived session or streaming progress protocol
+
+## Decisions
+
+### Command Shape
+
+Relay adds:
+
+- `git cas agent rotate --slug <slug> --old-key-file <path> --new-key-file <path>`
+- `git cas agent rotate --oid <tree-oid> --old-key-file <path> --new-key-file <path>`
+
+Optional:
+
+- `--label <label>`
+
+Request payloads may also provide the same fields.
+
+### Target Semantics
+
+`--slug` means:
+
+- resolve the current vault entry
+- rotate the manifest
+- create a new tree
+- update the vault entry with `force: true`
+- return the new tree and the new vault commit
+
+`--oid` means:
+
+- read the detached manifest tree directly
+- rotate the manifest
+- create a new tree
+- do not update the vault
+- return the new tree and explicitly report that the vault was not updated
+
+Relay chooses explicit detached-tree persistence here because a machine-facing
+rotate result is more useful when it returns a real follow-on tree OID instead
+of an in-memory manifest dump.
+
+### Result Shape
+
+Successful rotation `result` rows should expose:
+
+- `action`
+- `slug`
+- `label` when explicitly provided
+- `previousTreeOid`
+- `treeOid`
+- `commitOid` when the vault was updated
+- `updatedVault`
+- `keyVersion`
+- `recipientCount`
+- `recipients`
+
+`recipients` uses the same structured row shape as `recipient list` and
+recipient mutation results.
+
+### Error Behavior
+
+Relay should preserve existing domain error codes where they already describe
+the failure correctly:
+
+- `NO_MATCHING_RECIPIENT`
+- `DEK_UNWRAP_FAILED`
+- `RECIPIENT_NOT_FOUND`
+- `ROTATION_NOT_SUPPORTED`
+
+Missing required inputs remain `INVALID_INPUT`.
+
+## Implementation Outline
+
+1. Add `rotate` to the Relay command registry.
+2. Parse slug/OID targeting plus explicit old/new key file inputs.
+3. Reuse the existing manifest-resolution helpers.
+4. Apply the existing `cas.rotateKey()` domain operation.
+5. Persist the rotated manifest as a new tree.
+6. Update the vault only when the target came from `--slug`.
+7. Return explicit tree/vault side-effect data.
+
+## Tests To Write First
+
+- slug-targeted rotate succeeds and reports new tree plus vault commit
+- detached-tree rotate succeeds and reports a new tree without a vault commit
+- rotated content restores with the new key
+- missing slug/OID target surfaces as `INVALID_INPUT`
+- wrong old key with an explicit label surfaces as `DEK_UNWRAP_FAILED`
+
+These are Relay contract tests and belong in the agent CLI integration suite.
+
+## Risks And Unknowns
+
+- detached-tree rotation is useful for agents, but it is a semantic choice that
+  differs from the human CLI's plain manifest output path
+- the result shape should stay stable enough that future vault-wide rotation or
+  session-based Relay work can build on it cleanly
+
+## Retrospective
+
+Pending.
diff --git a/docs/design/RL-004-agent-vault-rotate.md b/docs/design/RL-004-agent-vault-rotate.md
new file mode 100644
index 0000000..2466ad4
--- /dev/null
+++ b/docs/design/RL-004-agent-vault-rotate.md
@@ -0,0 +1,165 @@
+# RL-004 — Relay: Agent Vault Rotate
+
+## Status
+
+Active
+
+## Linked Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Context
+
+Relay can now:
+
+- inspect vault state
+- store and restore encrypted assets
+- rotate recipient keys for individual assets
+
+The next key-lifecycle gap is vault passphrase rotation.
+
+The human CLI already supports it. Relay needs a machine-facing contract that is
+explicit about secret sources and vault-wide side effects.
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- release engineers
+- operators rotating encrypted vault credentials
+
+### Jobs
+
+- rotate a vault passphrase without opening an interactive prompt
+- know exactly which entries were rotated, which were skipped, and which commit
+  recorded the change
+
+### Hill
+
+A human operator can trust agent-driven vault passphrase rotation because the
+command reports the vault commit and the rotated/skipped entry set directly.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- CI jobs
+- operations workflows
+
+### Jobs
+
+- rotate an encrypted vault with explicit old/new passphrase sources
+- verify that the resulting KDF algorithm is what was requested
+- branch on wrong-passphrase and unencrypted-vault failures without parsing prose
+
+### Hill
+
+An agent can rotate vault passphrases through Relay and learn exactly what the
+vault commit changed.
+
+## Human Playback
+
+- Can an operator inspect the result row and immediately know whether the vault
+  was updated successfully?
+- Are rotated and skipped entries visible without follow-up commands?
+
+## Agent Playback
+
+- Can an agent rotate a vault using direct passphrase input?
+- Can it rotate using request-payload file sources for secrets?
+- Can it override the KDF algorithm and observe the resulting metadata?
+- Do invalid-input and wrong-passphrase failures surface as structured protocol
+  errors?
+
+## Explicit Non-Goals
+
+- no asset-level recipient mutation in this cycle
+- no recipient-key rotation in this cycle
+- no interactive prompts
+- no attempt to read both request JSON and passphrases from stdin at once
+
+## Decisions
+
+### Command Shape
+
+Relay adds:
+
+- `git cas agent vault rotate --old-passphrase <pass> --new-passphrase <pass>`
+
+Optional:
+
+- `--old-passphrase-file <path>`
+- `--new-passphrase-file <path>`
+- `--algorithm <pbkdf2|scrypt>`
+
+Request payloads may also provide the same fields.
+
+### Secret Source Rules
+
+- provide either direct passphrase values or passphrase-file paths
+- reading both old and new passphrases from stdin is invalid
+- reading request payload JSON from stdin and any passphrase from stdin is invalid
+- empty passphrases are invalid
+
+Relay must stay non-interactive. There is no prompt fallback.
+
+### Result Shape
+
+Successful `result` rows should expose:
+
+- `commitOid`
+- `updatedVault`
+- `rotatedSlugs`
+- `skippedSlugs`
+- `rotatedCount`
+- `skippedCount`
+- `entryCount`
+- `kdfAlgorithm`
+
+This keeps both the vault side effect and the resulting metadata explicit.
+
+### Error Behavior
+
+Relay should preserve existing domain error codes where they already describe
+the failure correctly:
+
+- `NO_MATCHING_RECIPIENT`
+- `VAULT_METADATA_INVALID`
+- `VAULT_CONFLICT`
+
+Missing or contradictory passphrase inputs remain `INVALID_INPUT`.
+
+## Implementation Outline
+
+1. Add `vault rotate` to the Relay command registry.
+2. Parse passphrase sources from flags or request payloads.
+3. Enforce stdin and empty-secret constraints explicitly.
+4. Call the existing `cas.rotateVaultPassphrase()` operation.
+5. Read updated vault metadata and return explicit commit/KDF/result data.
+
+## Tests To Write First
+
+- vault rotate succeeds and reports commit, rotated slugs, skipped slugs, and KDF algorithm
+- vault rotate supports request payloads plus passphrase-file inputs
+- vault rotate applies an algorithm override and exposes the resulting KDF algorithm
+- missing old or new passphrase surfaces as `INVALID_INPUT`
+- wrong old passphrase surfaces as a structured protocol error
+
+These are Relay contract tests and belong in the agent CLI integration suite.
+
+## Risks And Unknowns
+
+- vault-wide rotation is a more sensitive operation than asset-level rotation,
+  so the input contract must stay strict and unsurprising
+- direct-key encrypted entries are intentionally skipped, and that distinction
+  needs to remain explicit in the result payload
+
+## Retrospective
+
+Pending.
diff --git a/docs/design/RL-005-agent-vault-lifecycle.md b/docs/design/RL-005-agent-vault-lifecycle.md
new file mode 100644
index 0000000..033c54e
--- /dev/null
+++ b/docs/design/RL-005-agent-vault-lifecycle.md
@@ -0,0 +1,171 @@
+# RL-005 — Relay: Agent Vault Lifecycle
+
+## Status
+
+Active
+
+## Linked Legend
+
+- [RL — Relay](../legends/RL-relay.md)
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Context
+
+Relay already covers:
+
+- read-only vault inspection
+- asset store and restore
+- recipient mutation
+- recipient key rotation
+- vault passphrase rotation
+
+The next missing bounded step is vault lifecycle mutation:
+
+- initialize a vault
+- remove an entry from the vault
+
+These already exist in the human CLI. Relay needs the same behavior through a
+machine-facing contract.
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- release engineers
+- operators bootstrapping or pruning vault state
+
+### Jobs
+
+- initialize a vault through automation with or without encryption
+- remove an entry and know exactly what was deleted and what commit recorded it
+
+### Hill
+
+A human operator can automate the basic vault lifecycle without leaving the
+Relay surface or guessing at hidden side effects.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- CI jobs
+- repository automation workflows
+
+### Jobs
+
+- initialize plaintext or encrypted vaults deterministically
+- remove entries by slug and observe the resulting commit and removed tree
+- branch on invalid input and missing entry failures without parsing prose
+
+### Hill
+
+An agent can manage the basic vault lifecycle entirely through the Relay
+contract.
+
+## Human Playback
+
+- Can an operator see whether vault initialization was encrypted directly from
+  the result row?
+- Can an operator see which tree was removed and which commit recorded the
+  removal?
+
+## Agent Playback
+
+- Can an agent initialize a plaintext vault?
+- Can it initialize an encrypted vault using request-payload passphrase-file
+  inputs and observe the resulting KDF algorithm?
+- Can it remove an entry by slug and get the removed tree plus commit directly?
+- Do missing-passphrase and missing-entry failures stay structured?
+
+## Explicit Non-Goals
+
+- no asset store workflow in this cycle
+- no vault passphrase rotation in this cycle
+- no interactive passphrase prompts
+- no vault entry add/update flow in this cycle
+
+## Decisions
+
+### Command Shape
+
+Relay adds:
+
+- `git cas agent vault init`
+- `git cas agent vault remove --slug <slug>`
+
+Optional `vault init` inputs:
+
+- `--passphrase <pass>`
+- `--passphrase-file <path>`
+- `--algorithm <pbkdf2|scrypt>`
+
+Request payloads may also provide the same fields.
+
+### Secret Source Rules
+
+- `vault init` remains non-interactive
+- provide either inline passphrase or passphrase-file, not both
+- if the request payload comes from stdin, the passphrase file cannot also be `-`
+- `--algorithm` is only valid when vault encryption is requested
+- empty passphrases are invalid
+
+### Result Shape
+
+Successful `vault init` `result` rows should expose:
+
+- `commitOid`
+- `initializedVault`
+- `encrypted`
+- `kdfAlgorithm` when encrypted
+
+Successful `vault remove` `result` rows should expose:
+
+- `slug`
+- `commitOid`
+- `removedTreeOid`
+- `updatedVault`
+
+### Error Behavior
+
+Relay should preserve existing domain error codes where they already describe
+the failure correctly:
+
+- `VAULT_ENTRY_NOT_FOUND`
+
+Missing or contradictory inputs remain `INVALID_INPUT`.
+
+## Implementation Outline
+
+1. Add `vault init` and `vault remove` to the Relay command registry.
+2. Parse explicit slug and passphrase-source inputs from flags or request
+   payloads.
+3. Reuse the existing passphrase-file safety rules from the Relay surface.
+4. Call the existing `cas.initVault()` and `cas.removeFromVault()` operations.
+5. Return explicit result rows with commit-side effects.
+
+## Tests To Write First
+
+- vault init succeeds without encryption and reports a commit
+- vault init succeeds with encrypted request-payload passphrase-file input and
+  reports the resulting KDF algorithm
+- vault init rejects `--algorithm` without an encryption source
+- vault remove succeeds and reports the removed tree plus commit
+- vault remove surfaces missing-entry failures as structured protocol errors
+
+These are Relay contract tests and belong in the agent CLI integration suite.
+
+## Risks And Unknowns
+
+- `vault init` is foundational, so the passphrase contract must remain strict
+  and unsurprising
+- the result shapes should stay stable enough that future session-oriented
+  Relay work can build on them without compatibility churn
+
+## Retrospective
+
+Pending.
diff --git a/docs/invariants/I-001-determinism-trust-and-explicit-surfaces.md b/docs/invariants/I-001-determinism-trust-and-explicit-surfaces.md
new file mode 100644
index 0000000..bb9cf21
--- /dev/null
+++ b/docs/invariants/I-001-determinism-trust-and-explicit-surfaces.md
@@ -0,0 +1,30 @@
+# I-001 — Determinism, Trust, And Explicit Surfaces
+
+## Statement
+
+The following truths are non-negotiable for `git-cas`:
+
+- Git is the substrate, not the product.
+- Integrity is sacred.
+- Restore must be deterministic.
+- Provenance and verification matter.
+- Human CLI/TUI and agent CLI are separate surfaces over one shared core.
+- The default human UX must stay boring, legible, and trustworthy.
+- The agent UX must stay non-interactive, explicit, and replayable.
+
+## Implications
+
+- no hidden side effects in normal operator or agent flows
+- no TTY branching in the agent contract
+- no implicit prompts in the agent contract
+- no human-only access path for essential system behavior
+- no storage or Git-internal trivia leaking into ordinary UX without cause
+- no test design that depends on ambient user state, timing luck, or shell
+  interaction
+
+## Why This Matters
+
+`git-cas` is only useful if people and agents can trust it.
+
+Fancy internals are allowed.
+Unclear behavior is not.
diff --git a/docs/invariants/README.md b/docs/invariants/README.md
new file mode 100644
index 0000000..ed2c120
--- /dev/null
+++ b/docs/invariants/README.md
@@ -0,0 +1,12 @@
+# Invariants
+
+Invariants are explicit truths that design and implementation are not allowed
+to violate.
+
+They are stronger than preferences and more durable than cycle goals.
+
+Every important cycle doc should link the invariants it depends on.
+
+Current invariants:
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](./I-001-determinism-trust-and-explicit-surfaces.md)
diff --git a/docs/legends/README.md b/docs/legends/README.md
new file mode 100644
index 0000000..d52fcba
--- /dev/null
+++ b/docs/legends/README.md
@@ -0,0 +1,18 @@
+# Legends
+
+Legends are broad thematic efforts that shape multiple cycles.
+
+They are larger than a single implementation slice, but smaller and more useful
+than vague long-range milestone fiction.
+
+Each legend should define:
+
+- why the line matters
+- the human and agent hills it supports
+- what it is explicitly not trying to do
+- which invariants it depends on
+- which cycles currently belong to it
+
+Current legend docs:
+
+- [RL — Relay](./RL-relay.md)
diff --git a/docs/legends/RL-relay.md b/docs/legends/RL-relay.md
new file mode 100644
index 0000000..368f6b2
--- /dev/null
+++ b/docs/legends/RL-relay.md
@@ -0,0 +1,87 @@
+# RL — Relay
+
+## Status
+
+Active
+
+## Theme
+
+Build a first-class machine-facing `git cas agent` contract and force the
+application boundary to become explicit enough that later human-surface work
+can reuse it honestly.
+
+## Why This Legend Exists
+
+The human CLI and TUI are already ahead of the planning docs.
+
+The current product gap is not “can `git-cas` do useful things?”
+It is “can agents perform those useful things deterministically without
+scraping, prompting, or depending on terminal behavior?”
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- release engineers
+- operators who need trustworthy restore, verify, and vault workflows
+
+### Jobs
+
+- automate storage and restore without building brittle wrappers
+- trust that machine-facing behavior is explicit and replayable
+
+### Hill
+
+A human operator can build reliable automation on top of `git-cas` without
+needing a human escape hatch for ordinary success paths.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- CI jobs
+- release bots
+- backup and verification workflows
+
+### Jobs
+
+- inspect state
+- verify integrity
+- store and restore artifacts
+- manage keys and recipients
+- branch on failures using structured outputs instead of prose
+
+### Hill
+
+An agent can complete core `git-cas` workflows through a stable, non-interactive,
+JSONL-first contract.
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Current Cycle Surface
+
+The currently landed Relay cycle docs still use legacy numeric naming:
+
+- [0001 — M18 Relay: Agent CLI Foundation](../design/0001-m18-relay-agent-cli.md)
+- [0002 — M18 Relay: Write Flows and Input Semantics](../design/0002-m18-relay-write-flows.md)
+- [0003 — M18 Relay: Tree Creation Primitive](../design/0003-m18-relay-tree-creation.md)
+
+Future Relay cycle docs should use the `RL-...` naming model.
+
+Active Relay cycle docs now using that model:
+
+- [RL-001 — Relay: Agent Recipient List](../design/RL-001-agent-recipient-list.md)
+- [RL-002 — Relay: Agent Recipient Mutations](../design/RL-002-agent-recipient-mutations.md)
+- [RL-003 — Relay: Agent Rotate](../design/RL-003-agent-rotate.md)
+- [RL-004 — Relay: Agent Vault Rotate](../design/RL-004-agent-vault-rotate.md)
+- [RL-005 — Relay: Agent Vault Lifecycle](../design/RL-005-agent-vault-lifecycle.md)
+
+## Explicit Non-Goals
+
+- no attempt to collapse the human and agent surfaces into one contract
+- no long-lived session protocol until playbacks demand it
+- no TUI-first expansion that bypasses the shared app-layer boundary
diff --git a/test/cycles/README.md b/test/cycles/README.md
new file mode 100644
index 0000000..1a068c3
--- /dev/null
+++ b/test/cycles/README.md
@@ -0,0 +1,13 @@
+# Cycle Tests
+
+Cycle-owned playback, regression, and spec tests live here when the cycle
+benefits from a dedicated test namespace.
+
+This does not replace the normal unit and integration suite.
+
+Use this directory when a cycle has:
+
+- a clear protocol or playback contract
+- a bounded regression surface worth naming directly
+- test fixtures or helper structure that belong to the cycle more than to a
+  package
diff --git a/test/integration/agent-cli.test.js b/test/integration/agent-cli.test.js
new file mode 100644
index 0000000..4de4abc
--- /dev/null
+++ b/test/integration/agent-cli.test.js
@@ -0,0 +1,2115 @@
+/**
+ * Integration tests — agent CLI protocol workflow via bin/git-cas.js.
+ *
+ * MUST run inside Docker (GIT_STUNTS_DOCKER=1). Refuses to run on the host.
+ * Uses the current runtime (node/bun/deno) to invoke the CLI.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import ContentAddressableStore from '../../index.js';
+import { createGitPlumbing } from '../../src/infrastructure/createGitPlumbing.js';
+
+if (process.env.GIT_STUNTS_DOCKER !== '1') {
+  throw new Error(
+    'Integration tests MUST run inside Docker (GIT_STUNTS_DOCKER=1). ' +
+      'Use: docker compose run --build --rm test-<runtime>'
+  );
+}
+
+vi.setConfig({
+  testTimeout: 30000,
+  hookTimeout: 60000,
+});
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, '../../bin/git-cas.js');
+const RUNTIME_CMD = globalThis.Bun
+  ? ['bun', 'run', BIN]
+  : globalThis.Deno
+    ? ['deno', 'run', '-A', BIN]
+    : ['node', BIN];
+
+/**
+ * @param {string} cwd
+ * @returns {ContentAddressableStore}
+ */
+function createCas(cwd) {
+  return new ContentAddressableStore({
+    plumbing: createGitPlumbing({ cwd }),
+  });
+}
+
+/**
+ * @param {string} cwd
+ */
+function initBareRepo(cwd) {
+  const result = spawnSync('git', ['init', '--bare'], { cwd, encoding: 'utf8' });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`${result.stderr ?? result.stdout ?? 'git init --bare failed'}`.trim());
+  }
+}
+
+/**
+ * @param {Buffer} content
+ * @returns {{ filePath: string, dir: string }}
+ */
+function tempFile(content) {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-cli-'));
+  const filePath = path.join(dir, 'input.bin');
+  writeFileSync(filePath, content);
+  return { filePath, dir };
+}
+
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ * @param {{ input?: string }} [options]
+ */
+function runAgentCli(args, cwd, options = {}) {
+  return spawnSync(RUNTIME_CMD[0], [...RUNTIME_CMD.slice(1), 'agent', ...args], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 90_000,
+    ...(options.input !== undefined ? { input: options.input } : {}),
+  });
+}
+
+/**
+ * @param {string | undefined} output
+ * @returns {Array<Record<string, any>>}
+ */
+function parseJsonl(output) {
+  return `${output ?? ''}`
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+let repoDir;
+let inputDir;
+let requestDir;
+let treeOid;
+let encRepoDir;
+let encInputDir;
+let encTreeOid;
+let recipientRepoDir;
+let recipientInputDir;
+let recipientTreeOid;
+const original = randomBytes(4096);
+const encryptedOriginal = randomBytes(3072);
+const envelopeOriginal = randomBytes(2048);
+const vaultRotateEnvelopeOriginal = randomBytes(1536);
+const vaultRotateDirectOriginal = randomBytes(1024);
+const vaultPassphrase = 'relay-agent-passphrase';
+
+beforeAll(async () => {
+  ({ repoDir, inputDir, treeOid } = await setupPlainRepo());
+  ({
+    repoDir: encRepoDir,
+    inputDir: encInputDir,
+    treeOid: encTreeOid,
+  } = await setupEncryptedRepo());
+  ({
+    repoDir: recipientRepoDir,
+    inputDir: recipientInputDir,
+    treeOid: recipientTreeOid,
+  } = await setupRecipientRepo());
+  requestDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-request-'));
+});
+
+afterAll(() => {
+  if (repoDir) {
+    rmSync(repoDir, { recursive: true, force: true });
+  }
+  if (encRepoDir) {
+    rmSync(encRepoDir, { recursive: true, force: true });
+  }
+  if (recipientRepoDir) {
+    rmSync(recipientRepoDir, { recursive: true, force: true });
+  }
+  if (inputDir) {
+    rmSync(inputDir, { recursive: true, force: true });
+  }
+  if (encInputDir) {
+    rmSync(encInputDir, { recursive: true, force: true });
+  }
+  if (recipientInputDir) {
+    rmSync(recipientInputDir, { recursive: true, force: true });
+  }
+  if (requestDir) {
+    rmSync(requestDir, { recursive: true, force: true });
+  }
+});
+
+async function setupPlainRepo() {
+  const plainRepoDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-integ-'));
+  initBareRepo(plainRepoDir);
+
+  const cas = createCas(plainRepoDir);
+  await cas.initVault();
+
+  const input = tempFile(original);
+  const manifest = await cas.storeFile({
+    filePath: input.filePath,
+    slug: 'demo/hello',
+  });
+  const plainTreeOid = await cas.createTree({ manifest });
+  await cas.addToVault({ slug: 'demo/hello', treeOid: plainTreeOid });
+
+  return { repoDir: plainRepoDir, inputDir: input.dir, treeOid: plainTreeOid };
+}
+
+async function setupEncryptedRepo() {
+  const encryptedRepoDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-enc-integ-'));
+  initBareRepo(encryptedRepoDir);
+
+  const cas = createCas(encryptedRepoDir);
+  await cas.initVault({ passphrase: vaultPassphrase });
+
+  const input = tempFile(encryptedOriginal);
+  const manifest = await cas.storeFile({
+    filePath: input.filePath,
+    slug: 'enc/hello',
+    encryptionKey: await deriveVaultKey(cas, vaultPassphrase),
+  });
+  const encryptedTreeOid = await cas.createTree({ manifest });
+  await cas.addToVault({ slug: 'enc/hello', treeOid: encryptedTreeOid });
+
+  return {
+    repoDir: encryptedRepoDir,
+    inputDir: input.dir,
+    treeOid: encryptedTreeOid,
+  };
+}
+
+async function setupRecipientRepo() {
+  const envelopeRepoDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-recipient-integ-'));
+  initBareRepo(envelopeRepoDir);
+
+  const cas = createCas(envelopeRepoDir);
+  await cas.initVault();
+
+  const input = tempFile(envelopeOriginal);
+  const manifest = await cas.storeFile({
+    filePath: input.filePath,
+    slug: 'env/hello',
+    recipients: [
+      { label: 'alice', key: randomBytes(32) },
+      { label: 'bob', key: randomBytes(32) },
+    ],
+  });
+  const envelopeTreeOid = await cas.createTree({ manifest });
+  await cas.addToVault({ slug: 'env/hello', treeOid: envelopeTreeOid });
+
+  return {
+    repoDir: envelopeRepoDir,
+    inputDir: input.dir,
+    treeOid: envelopeTreeOid,
+  };
+}
+
+async function createEnvelopeVaultEntry(
+  repoPath,
+  { slug, recipients, content = envelopeOriginal }
+) {
+  const cas = createCas(repoPath);
+  const input = tempFile(content);
+  const manifest = await cas.storeFile({
+    filePath: input.filePath,
+    slug,
+    recipients,
+  });
+  const createdTreeOid = await cas.createTree({ manifest });
+  await cas.addToVault({ slug, treeOid: createdTreeOid });
+
+  return { treeOid: createdTreeOid, inputDir: input.dir };
+}
+
+async function deriveVaultKey(cas, passphrase) {
+  const metadata = await cas.getVaultMetadata();
+  if (!metadata?.encryption?.kdf) {
+    throw new Error('Encrypted vault metadata missing KDF configuration');
+  }
+  const { key } = await cas.deriveKey({
+    passphrase,
+    salt: Buffer.from(metadata.encryption.kdf.salt, 'base64'),
+    algorithm: metadata.encryption.kdf.algorithm,
+    iterations: metadata.encryption.kdf.iterations,
+    cost: metadata.encryption.kdf.cost,
+    blockSize: metadata.encryption.kdf.blockSize,
+    parallelization: metadata.encryption.kdf.parallelization,
+    keyLength: metadata.encryption.kdf.keyLength,
+  });
+  return key;
+}
+
+async function setupVaultRotateRepo() {
+  const rotateRepoDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-vault-rotate-'));
+  initBareRepo(rotateRepoDir);
+
+  const oldPassphrase = 'relay-old-passphrase';
+  const newPassphrase = 'relay-new-passphrase';
+  const cas = createCas(rotateRepoDir);
+  await cas.initVault({ passphrase: oldPassphrase });
+
+  const oldKek = await deriveVaultKey(cas, oldPassphrase);
+  const oldKeyFile = tempFile(oldKek);
+
+  const envelopeInput = tempFile(vaultRotateEnvelopeOriginal);
+  const envelopeManifest = await cas.storeFile({
+    filePath: envelopeInput.filePath,
+    slug: 'vault/env',
+    recipients: [{ label: 'vault', key: oldKek }],
+  });
+  const envelopeTreeOid = await cas.createTree({ manifest: envelopeManifest });
+  await cas.addToVault({ slug: 'vault/env', treeOid: envelopeTreeOid });
+
+  const directInput = tempFile(vaultRotateDirectOriginal);
+  const directManifest = await cas.storeFile({
+    filePath: directInput.filePath,
+    slug: 'vault/direct',
+    encryptionKey: oldKek,
+  });
+  const directTreeOid = await cas.createTree({ manifest: directManifest });
+  await cas.addToVault({ slug: 'vault/direct', treeOid: directTreeOid });
+
+  return {
+    repoDir: rotateRepoDir,
+    oldPassphrase,
+    newPassphrase,
+    oldKeyFile,
+    envelopeInput,
+    directInput,
+  };
+}
+
+function createEmptyAgentRepo() {
+  const vaultRepoDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-empty-vault-'));
+  initBareRepo(vaultRepoDir);
+  return vaultRepoDir;
+}
+
+function defineReadOnlyProtocolTests() {
+  it('inspect emits start, result, and end rows on stdout', () => {
+    const result = runAgentCli(['inspect', '--slug', 'demo/hello'], repoDir);
+    expect(result.error).toBeUndefined();
+    expect(result.signal).toBeNull();
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    expect(rows.map((row) => row.command)).toEqual(['inspect', 'inspect', 'inspect']);
+    assertStartRow(rows, {
+      cwd: '.',
+      slug: 'demo/hello',
+    });
+    expect(rows[1].data).toMatchObject({
+      treeOid,
+      manifest: { slug: 'demo/hello' },
+    });
+    expect(rows[2].data).toEqual({ ok: true, exitCode: 0 });
+  });
+
+  it('verify reports success as protocol data', () => {
+    const result = runAgentCli(['verify', '--slug', 'demo/hello'], repoDir);
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data).toMatchObject({
+      ok: true,
+      slug: 'demo/hello',
+      treeOid,
+      chunks: 1,
+    });
+    expect(rows[2].data).toEqual({ ok: true, exitCode: 0 });
+  });
+
+  it('doctor reports health through the protocol', () => {
+    const result = runAgentCli(['doctor'], repoDir);
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data.report).toMatchObject({
+      status: 'ok',
+      hasVault: true,
+      entryCount: 1,
+    });
+  });
+}
+
+function defineVaultProtocolTests() {
+  it('vault list returns entries in a result row', () => {
+    const result = runAgentCli(['vault', 'list'], repoDir);
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data.entries).toEqual([{ slug: 'demo/hello', treeOid }]);
+  });
+
+  it('vault info, history, and stats expose structured data', () => {
+    const info = runAgentCli(['vault', 'info', 'demo/hello'], repoDir);
+    const history = runAgentCli(['vault', 'history', '--max-count', '1'], repoDir);
+    const stats = runAgentCli(['vault', 'stats'], repoDir);
+
+    expect(info.status).toBe(0);
+    expect(history.status).toBe(0);
+    expect(stats.status).toBe(0);
+
+    const infoRows = parseJsonl(info.stdout);
+    const historyRows = parseJsonl(history.stdout);
+    const statsRows = parseJsonl(stats.stdout);
+
+    expect(infoRows[1].data).toEqual({ slug: 'demo/hello', treeOid });
+    expect(historyRows[1].data.history).toHaveLength(1);
+    expect(historyRows[1].data.history[0].message).toContain('vault: add');
+    expect(statsRows[1].data.stats).toMatchObject({
+      entries: 1,
+      totalLogicalSize: original.length,
+      uniqueChunks: 1,
+    });
+  });
+}
+
+function defineRecipientListSlugTest() {
+  it('recipient list returns structured recipient rows for an envelope asset', () => {
+    const result = runAgentCli(['recipient', 'list', '--slug', 'env/hello'], recipientRepoDir);
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    expect(rows[1].data).toEqual({
+      slug: 'env/hello',
+      treeOid: recipientTreeOid,
+      envelope: true,
+      recipientCount: 2,
+      recipients: [{ label: 'alice' }, { label: 'bob' }],
+    });
+  });
+}
+
+function defineRecipientListRequestPayloadTest() {
+  it('recipient list accepts request payloads that target an asset by oid', () => {
+    const requestPath = path.join(requestDir, 'recipient-list.json');
+    writeFileSync(requestPath, JSON.stringify({ oid: recipientTreeOid }));
+
+    const result = runAgentCli(
+      ['recipient', 'list', '--request', `@${requestPath}`],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data).toEqual({
+      slug: 'env/hello',
+      treeOid: recipientTreeOid,
+      envelope: true,
+      recipientCount: 2,
+      recipients: [{ label: 'alice' }, { label: 'bob' }],
+    });
+  });
+}
+
+function defineRecipientListPlaintextTest() {
+  it('recipient list returns a non-envelope result for plaintext assets', () => {
+    const result = runAgentCli(['recipient', 'list', '--slug', 'demo/hello'], repoDir);
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data).toEqual({
+      slug: 'demo/hello',
+      treeOid,
+      envelope: false,
+      recipientCount: 0,
+      recipients: [],
+    });
+  });
+}
+
+function defineRecipientListValidationTest() {
+  it('recipient list emits structured invalid-input errors when no target is provided', () => {
+    const result = runAgentCli(['recipient', 'list'], recipientRepoDir);
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'recipient.list',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --slug <slug> or --oid <tree-oid>',
+      },
+    });
+  });
+}
+
+async function prepareRecipientAddRequestFixture() {
+  const alice = randomBytes(32);
+  const bob = randomBytes(32);
+  const carol = randomBytes(32);
+  const slug = 'env/add-target';
+  const { treeOid: previousTreeOid, inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(
+    recipientRepoDir,
+    {
+      slug,
+      recipients: [
+        { label: 'alice', key: alice },
+        { label: 'bob', key: bob },
+      ],
+    }
+  );
+  const existingKeyFile = tempFile(alice);
+  const newKeyFile = tempFile(carol);
+  const requestPath = path.join(requestDir, 'recipient-add.json');
+  writeFileSync(
+    requestPath,
+    JSON.stringify({
+      slug,
+      label: 'carol',
+      existingKeyFile: existingKeyFile.filePath,
+      keyFile: newKeyFile.filePath,
+    })
+  );
+
+  return {
+    slug,
+    previousTreeOid,
+    fixtureInputDir,
+    existingKeyFile,
+    newKeyFile,
+    requestPath,
+  };
+}
+
+function defineRecipientAddRequestPayloadTest() {
+  it('recipient add supports request payloads and reports vault side effects', async () => {
+    const { slug, previousTreeOid, fixtureInputDir, existingKeyFile, newKeyFile, requestPath } =
+      await prepareRecipientAddRequestFixture();
+
+    const result = runAgentCli(
+      ['recipient', 'add', '--request', `@${requestPath}`],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    expect(rows[1].data).toMatchObject({
+      action: 'add',
+      slug,
+      label: 'carol',
+      previousTreeOid,
+      recipientCount: 3,
+      recipients: [{ label: 'alice' }, { label: 'bob' }, { label: 'carol' }],
+    });
+    expect(rows[1].data.treeOid).toMatch(/^[0-9a-f]{40}$/);
+    expect(rows[1].data.treeOid).not.toBe(previousTreeOid);
+    expect(rows[1].data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+
+    rmSync(fixtureInputDir, { recursive: true, force: true });
+    rmSync(existingKeyFile.dir, { recursive: true, force: true });
+    rmSync(newKeyFile.dir, { recursive: true, force: true });
+  });
+}
+
+function defineRecipientRemoveSuccessTest() {
+  it('recipient remove reports the new tree, commit, and remaining recipients', async () => {
+    const alice = randomBytes(32);
+    const bob = randomBytes(32);
+    const slug = 'env/remove-target';
+    const { treeOid: previousTreeOid, inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(
+      recipientRepoDir,
+      {
+        slug,
+        recipients: [
+          { label: 'alice', key: alice },
+          { label: 'bob', key: bob },
+        ],
+      }
+    );
+
+    const result = runAgentCli(
+      ['recipient', 'remove', '--slug', slug, '--label', 'bob'],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data).toMatchObject({
+      action: 'remove',
+      slug,
+      label: 'bob',
+      previousTreeOid,
+      recipientCount: 1,
+      recipients: [{ label: 'alice' }],
+    });
+    expect(rows[1].data.treeOid).toMatch(/^[0-9a-f]{40}$/);
+    expect(rows[1].data.treeOid).not.toBe(previousTreeOid);
+    expect(rows[1].data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+
+    rmSync(fixtureInputDir, { recursive: true, force: true });
+  });
+}
+
+function defineRecipientAddDuplicateLabelTest() {
+  it('recipient add surfaces duplicate-label failures as structured protocol errors', async () => {
+    const alice = randomBytes(32);
+    const slug = 'env/add-duplicate';
+    const { inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(recipientRepoDir, {
+      slug,
+      recipients: [{ label: 'alice', key: alice }],
+    });
+    const existingKeyFile = tempFile(alice);
+    const newKeyFile = tempFile(randomBytes(32));
+
+    const result = runAgentCli(
+      [
+        'recipient',
+        'add',
+        '--slug',
+        slug,
+        '--label',
+        'alice',
+        '--existing-key-file',
+        existingKeyFile.filePath,
+        '--key-file',
+        newKeyFile.filePath,
+      ],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(1);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'recipient.add',
+      type: 'error',
+      data: {
+        code: 'RECIPIENT_ALREADY_EXISTS',
+        message: 'Recipient "alice" already exists',
+      },
+    });
+
+    rmSync(fixtureInputDir, { recursive: true, force: true });
+    rmSync(existingKeyFile.dir, { recursive: true, force: true });
+    rmSync(newKeyFile.dir, { recursive: true, force: true });
+  });
+}
+
+function defineRecipientRemoveLastRecipientTest() {
+  it('recipient remove surfaces last-recipient protection as a structured protocol error', async () => {
+    const alice = randomBytes(32);
+    const slug = 'env/remove-last';
+    const { inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(recipientRepoDir, {
+      slug,
+      recipients: [{ label: 'alice', key: alice }],
+    });
+
+    const result = runAgentCli(
+      ['recipient', 'remove', '--slug', slug, '--label', 'alice'],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(1);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'recipient.remove',
+      type: 'error',
+      data: {
+        code: 'CANNOT_REMOVE_LAST_RECIPIENT',
+        message: 'Cannot remove the last recipient',
+      },
+    });
+
+    rmSync(fixtureInputDir, { recursive: true, force: true });
+  });
+}
+
+async function prepareRotateSlugFixture() {
+  const alice = randomBytes(32);
+  const bob = randomBytes(32);
+  const aliceNew = randomBytes(32);
+  const slug = 'env/rotate-target';
+  const { treeOid: previousTreeOid, inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(
+    recipientRepoDir,
+    {
+      slug,
+      recipients: [
+        { label: 'alice', key: alice },
+        { label: 'bob', key: bob },
+      ],
+    }
+  );
+  const oldKeyFile = tempFile(alice);
+  const newKeyFile = tempFile(aliceNew);
+
+  return {
+    slug,
+    previousTreeOid,
+    fixtureInputDir,
+    oldKeyFile,
+    newKeyFile,
+  };
+}
+
+async function prepareRotateRequestFixture() {
+  const alice = randomBytes(32);
+  const aliceNew = randomBytes(32);
+  const slug = 'env/rotate-detached';
+  const { treeOid: previousTreeOid, inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(
+    recipientRepoDir,
+    {
+      slug,
+      recipients: [{ label: 'alice', key: alice }],
+    }
+  );
+  const oldKeyFile = tempFile(alice);
+  const newKeyFile = tempFile(aliceNew);
+  const requestPath = path.join(requestDir, 'rotate-request.json');
+  writeFileSync(
+    requestPath,
+    JSON.stringify({
+      oid: previousTreeOid,
+      oldKeyFile: oldKeyFile.filePath,
+      newKeyFile: newKeyFile.filePath,
+    })
+  );
+
+  return {
+    slug,
+    previousTreeOid,
+    fixtureInputDir,
+    oldKeyFile,
+    newKeyFile,
+    requestPath,
+  };
+}
+
+function assertRotateResult(data, expected) {
+  expect(data).toMatchObject(expected);
+  expect(data.treeOid).toMatch(/^[0-9a-f]{40}$/);
+  expect(data.treeOid).not.toBe(expected.previousTreeOid);
+}
+
+function assertRestoreResult(result, outputPath, expectedBuffer) {
+  expect(result.status).toBe(0);
+  expect(readFileSync(outputPath).equals(expectedBuffer)).toBe(true);
+}
+
+function cleanupTempDirs(...dirs) {
+  dirs.forEach((dir) => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+}
+
+function assertStartRow(rows, expectedInput) {
+  expect(rows[0]).toMatchObject({
+    type: 'start',
+    data: {
+      input: expectedInput,
+    },
+  });
+  expect(rows[0].data).not.toHaveProperty('argv');
+}
+
+function assertExactStartRow(rows, expectedInput) {
+  assertStartRow(rows, expectedInput);
+  expect(rows[0].data.input).toEqual(expectedInput);
+}
+
+function assertRotateOldKeyFailure(result) {
+  expect(result.status).toBe(1);
+
+  const oldKeyErrors = parseJsonl(result.stderr);
+  expect(oldKeyErrors[0]).toMatchObject({
+    command: 'restore',
+    type: 'error',
+    data: {
+      code: 'NO_MATCHING_RECIPIENT',
+    },
+  });
+}
+
+function assertVaultRotateResult(data, expected) {
+  expect(data).toMatchObject(expected);
+  expect(data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+}
+
+function assertVaultInitResult(data, expected) {
+  expect(data).toMatchObject(expected);
+  expect(data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+}
+
+function assertVaultRemoveResult(data, expected) {
+  expect(data).toMatchObject(expected);
+  expect(data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+}
+
+function assertSlugRotateRestore(slug, newKeyFilePath, oldKeyFilePath) {
+  const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-rotate-restore-'));
+  const outputPath = path.join(outputDir, 'restored.bin');
+  const restoreNew = runAgentCli(
+    ['restore', '--slug', slug, '--out', outputPath, '--key-file', newKeyFilePath],
+    recipientRepoDir
+  );
+  assertRestoreResult(restoreNew, outputPath, envelopeOriginal);
+
+  const failedOutputPath = path.join(outputDir, 'restored-old.bin');
+  const restoreOld = runAgentCli(
+    ['restore', '--slug', slug, '--out', failedOutputPath, '--key-file', oldKeyFilePath],
+    recipientRepoDir
+  );
+  assertRotateOldKeyFailure(restoreOld);
+  cleanupTempDirs(outputDir);
+}
+
+async function assertVaultRotateRestore(repoPath, newPassphrase, oldKeyFilePath) {
+  const newKeyFile = tempFile(await deriveVaultKey(createCas(repoPath), newPassphrase));
+  const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-vault-rotate-restore-'));
+  const outputPath = path.join(outputDir, 'restored.bin');
+  const restoreNew = runAgentCli(
+    ['restore', '--slug', 'vault/env', '--out', outputPath, '--key-file', newKeyFile.filePath],
+    repoPath
+  );
+  assertRestoreResult(restoreNew, outputPath, vaultRotateEnvelopeOriginal);
+
+  const failedOutputPath = path.join(outputDir, 'restored-old.bin');
+  const restoreOld = runAgentCli(
+    ['restore', '--slug', 'vault/env', '--out', failedOutputPath, '--key-file', oldKeyFilePath],
+    repoPath
+  );
+  assertRotateOldKeyFailure(restoreOld);
+  cleanupTempDirs(outputDir, newKeyFile.dir);
+}
+
+function defineRotateSlugSuccessTest() {
+  it('rotate updates a slug-targeted vault entry and reports explicit side effects', async () => {
+    const { slug, previousTreeOid, fixtureInputDir, oldKeyFile, newKeyFile } =
+      await prepareRotateSlugFixture();
+    const rotateResult = runAgentCli(
+      [
+        'rotate',
+        '--slug',
+        slug,
+        '--label',
+        'alice',
+        '--old-key-file',
+        oldKeyFile.filePath,
+        '--new-key-file',
+        newKeyFile.filePath,
+      ],
+      recipientRepoDir
+    );
+
+    expect(rotateResult.status).toBe(0);
+    expect(`${rotateResult.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(rotateResult.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    assertRotateResult(rows[1].data, {
+      action: 'rotate',
+      slug,
+      label: 'alice',
+      previousTreeOid,
+      updatedVault: true,
+      keyVersion: 1,
+      recipientCount: 2,
+      recipients: [{ label: 'alice', keyVersion: 1 }, { label: 'bob' }],
+    });
+    expect(rows[1].data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+
+    assertSlugRotateRestore(slug, newKeyFile.filePath, oldKeyFile.filePath);
+    cleanupTempDirs(fixtureInputDir, oldKeyFile.dir, newKeyFile.dir);
+  });
+}
+
+function defineRotateRequestPayloadTest() {
+  it('rotate accepts request payloads for detached-tree rotation without updating the vault', async () => {
+    const { slug, previousTreeOid, fixtureInputDir, oldKeyFile, newKeyFile, requestPath } =
+      await prepareRotateRequestFixture();
+    const result = runAgentCli(['rotate', '--request', `@${requestPath}`], recipientRepoDir);
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    assertRotateResult(rows[1].data, {
+      action: 'rotate',
+      slug,
+      previousTreeOid,
+      updatedVault: false,
+      keyVersion: 1,
+      recipientCount: 1,
+      recipients: [{ label: 'alice', keyVersion: 1 }],
+    });
+    expect(rows[1].data).not.toHaveProperty('commitOid');
+
+    const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-rotate-detached-'));
+    const outputPath = path.join(outputDir, 'restored.bin');
+    const restoreResult = runAgentCli(
+      [
+        'restore',
+        '--oid',
+        rows[1].data.treeOid,
+        '--out',
+        outputPath,
+        '--key-file',
+        newKeyFile.filePath,
+      ],
+      recipientRepoDir
+    );
+    assertRestoreResult(restoreResult, outputPath, envelopeOriginal);
+
+    const infoResult = runAgentCli(['vault', 'info', slug], recipientRepoDir);
+    expect(infoResult.status).toBe(0);
+
+    const infoRows = parseJsonl(infoResult.stdout);
+    expect(infoRows[1].data).toEqual({ slug, treeOid: previousTreeOid });
+
+    cleanupTempDirs(outputDir, fixtureInputDir, oldKeyFile.dir, newKeyFile.dir);
+  });
+}
+
+function defineRotateValidationTest() {
+  it('rotate emits structured invalid-input errors when no target is provided', () => {
+    const oldKeyFile = tempFile(randomBytes(32));
+    const newKeyFile = tempFile(randomBytes(32));
+    const result = runAgentCli(
+      ['rotate', '--old-key-file', oldKeyFile.filePath, '--new-key-file', newKeyFile.filePath],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'rotate',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --slug <slug> or --oid <tree-oid>',
+      },
+    });
+
+    cleanupTempDirs(oldKeyFile.dir, newKeyFile.dir);
+  });
+}
+
+function defineRotateWrongOldKeyTest() {
+  it('rotate surfaces wrong-key failures as structured protocol errors', async () => {
+    const alice = randomBytes(32);
+    const slug = 'env/rotate-wrong-key';
+    const { inputDir: fixtureInputDir } = await createEnvelopeVaultEntry(recipientRepoDir, {
+      slug,
+      recipients: [{ label: 'alice', key: alice }],
+    });
+    const oldKeyFile = tempFile(randomBytes(32));
+    const newKeyFile = tempFile(randomBytes(32));
+
+    const result = runAgentCli(
+      [
+        'rotate',
+        '--slug',
+        slug,
+        '--label',
+        'alice',
+        '--old-key-file',
+        oldKeyFile.filePath,
+        '--new-key-file',
+        newKeyFile.filePath,
+      ],
+      recipientRepoDir
+    );
+    expect(result.status).toBe(1);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'rotate',
+      type: 'error',
+      data: {
+        code: 'DEK_UNWRAP_FAILED',
+        message: 'Failed to unwrap DEK: authentication failed',
+      },
+    });
+
+    cleanupTempDirs(fixtureInputDir, oldKeyFile.dir, newKeyFile.dir);
+  });
+}
+
+function defineVaultRotateSuccessTest() {
+  it('vault rotate reports commit, rotated entries, and resulting KDF state', async () => {
+    const fixture = await setupVaultRotateRepo();
+    const result = runAgentCli(
+      [
+        'vault',
+        'rotate',
+        '--old-passphrase',
+        fixture.oldPassphrase,
+        '--new-passphrase',
+        fixture.newPassphrase,
+      ],
+      fixture.repoDir
+    );
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    assertVaultRotateResult(rows[1].data, {
+      updatedVault: true,
+      rotatedSlugs: ['vault/env'],
+      skippedSlugs: ['vault/direct'],
+      rotatedCount: 1,
+      skippedCount: 1,
+      entryCount: 2,
+      kdfAlgorithm: 'pbkdf2',
+    });
+
+    await assertVaultRotateRestore(
+      fixture.repoDir,
+      fixture.newPassphrase,
+      fixture.oldKeyFile.filePath
+    );
+    cleanupTempDirs(
+      fixture.repoDir,
+      fixture.oldKeyFile.dir,
+      fixture.envelopeInput.dir,
+      fixture.directInput.dir
+    );
+  });
+}
+
+function defineVaultRotateRequestPayloadTest() {
+  it('vault rotate accepts request payload file sources and algorithm override', async () => {
+    const fixture = await setupVaultRotateRepo();
+    const oldPassphraseFile = tempFile(Buffer.from(fixture.oldPassphrase));
+    const newPassphraseFile = tempFile(Buffer.from(fixture.newPassphrase));
+    const requestPath = path.join(requestDir, 'vault-rotate-request.json');
+    writeFileSync(
+      requestPath,
+      JSON.stringify({
+        oldPassphraseFile: oldPassphraseFile.filePath,
+        newPassphraseFile: newPassphraseFile.filePath,
+        algorithm: 'scrypt',
+      })
+    );
+
+    const result = runAgentCli(
+      ['vault', 'rotate', '--request', `@${requestPath}`],
+      fixture.repoDir
+    );
+
+    expect(result.status).toBe(0);
+
+    const rows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+    assertVaultRotateResult(rows[1].data, {
+      updatedVault: true,
+      rotatedCount: 1,
+      skippedCount: 1,
+      kdfAlgorithm: 'scrypt',
+    });
+    expect(stderrRows).toHaveLength(2);
+    expect(stderrRows.every((row) => row.type === 'warning')).toBe(true);
+    expect(stderrRows.every((row) => row.data.code === 'INSECURE_FILE_PERMISSIONS')).toBe(true);
+
+    const metadata = await createCas(fixture.repoDir).getVaultMetadata();
+    expect(metadata?.encryption?.kdf?.algorithm).toBe('scrypt');
+
+    cleanupTempDirs(
+      fixture.repoDir,
+      fixture.oldKeyFile.dir,
+      fixture.envelopeInput.dir,
+      fixture.directInput.dir,
+      oldPassphraseFile.dir,
+      newPassphraseFile.dir
+    );
+  });
+}
+
+function defineVaultRotateValidationTest() {
+  it('vault rotate emits structured invalid-input errors when the old passphrase is missing', () => {
+    const result = runAgentCli(['vault', 'rotate', '--new-passphrase', 'next'], encRepoDir);
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.rotate',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --old-passphrase <pass> or --old-passphrase-file <path>',
+      },
+    });
+  });
+}
+
+function defineVaultRotateWrongPassphraseTest() {
+  it('vault rotate surfaces wrong-passphrase failures as structured protocol errors', async () => {
+    const fixture = await setupVaultRotateRepo();
+    const result = runAgentCli(
+      [
+        'vault',
+        'rotate',
+        '--old-passphrase',
+        'wrong-passphrase',
+        '--new-passphrase',
+        fixture.newPassphrase,
+      ],
+      fixture.repoDir
+    );
+    expect(result.status).toBe(1);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.rotate',
+      type: 'error',
+      data: {
+        code: 'NO_MATCHING_RECIPIENT',
+        message: 'No recipient entry could be unwrapped with the provided key',
+      },
+    });
+
+    cleanupTempDirs(
+      fixture.repoDir,
+      fixture.oldKeyFile.dir,
+      fixture.envelopeInput.dir,
+      fixture.directInput.dir
+    );
+  });
+}
+
+function defineVaultInitPlaintextTest() {
+  it('vault init initializes a plaintext vault and reports commit side effects', async () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const result = runAgentCli(['vault', 'init'], vaultRepoDir);
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    assertVaultInitResult(rows[1].data, {
+      initializedVault: true,
+      encrypted: false,
+    });
+
+    const metadata = await createCas(vaultRepoDir).getVaultMetadata();
+    expect(metadata?.encryption).toBeUndefined();
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultInitEncryptedRequestPayloadTest() {
+  it('vault init accepts encrypted request payload input and reports the resulting KDF algorithm', async () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const passphraseFile = tempFile(Buffer.from('relay-init-passphrase'));
+    const requestPath = path.join(requestDir, 'vault-init-request.json');
+    writeFileSync(
+      requestPath,
+      JSON.stringify({
+        passphraseFile: passphraseFile.filePath,
+        algorithm: 'scrypt',
+      })
+    );
+
+    const result = runAgentCli(['vault', 'init', '--request', `@${requestPath}`], vaultRepoDir);
+
+    expect(result.status).toBe(0);
+
+    const rows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+    assertVaultInitResult(rows[1].data, {
+      initializedVault: true,
+      encrypted: true,
+      kdfAlgorithm: 'scrypt',
+    });
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.init',
+      type: 'warning',
+      data: {
+        code: 'INSECURE_FILE_PERMISSIONS',
+      },
+    });
+
+    const metadata = await createCas(vaultRepoDir).getVaultMetadata();
+    expect(metadata?.encryption?.kdf?.algorithm).toBe('scrypt');
+
+    cleanupTempDirs(vaultRepoDir, passphraseFile.dir);
+  });
+}
+
+function defineVaultInitValidationTest() {
+  it('vault init rejects algorithm selection without an encryption source', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const result = runAgentCli(['vault', 'init', '--algorithm', 'scrypt'], vaultRepoDir);
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.init',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --passphrase <pass> or --passphrase-file <path> when using --algorithm',
+      },
+    });
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultRemoveSuccessTest() {
+  it('vault remove reports the removed tree and vault commit explicitly', async () => {
+    const fixture = await setupPlainRepo();
+    const result = runAgentCli(['vault', 'remove', '--slug', 'demo/hello'], fixture.repoDir);
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    assertVaultRemoveResult(rows[1].data, {
+      slug: 'demo/hello',
+      removedTreeOid: fixture.treeOid,
+      updatedVault: true,
+    });
+
+    const entries = await createCas(fixture.repoDir).listVault();
+    expect(entries).toEqual([]);
+
+    cleanupTempDirs(fixture.repoDir, fixture.inputDir);
+  });
+}
+
+function defineVaultRemoveMissingEntryTest() {
+  it('vault remove surfaces missing-entry failures as structured protocol errors', async () => {
+    const fixture = await setupPlainRepo();
+    const result = runAgentCli(['vault', 'remove', '--slug', 'missing'], fixture.repoDir);
+    expect(result.status).toBe(1);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.remove',
+      type: 'error',
+      data: {
+        code: 'VAULT_ENTRY_NOT_FOUND',
+        message: 'Vault entry "missing" not found',
+      },
+    });
+
+    cleanupTempDirs(fixture.repoDir, fixture.inputDir);
+  });
+}
+
+function defineRequestAndValidationTests() {
+  it('inspect supports request payloads from a file', () => {
+    const requestPath = path.join(requestDir, 'inspect.json');
+    writeFileSync(requestPath, JSON.stringify({ slug: 'demo/hello' }));
+
+    const result = runAgentCli(['inspect', '--request', `@${requestPath}`], repoDir);
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    assertStartRow(rows, {
+      slug: 'demo/hello',
+    });
+    expect(rows[1].data).toMatchObject({
+      treeOid,
+      manifest: { slug: 'demo/hello' },
+    });
+    expect(result.stdout).not.toContain(requestPath);
+  });
+
+  it('inspect emits structured invalid-input errors without human help text', () => {
+    const result = runAgentCli(['inspect'], repoDir);
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'inspect',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --slug <slug> or --oid <tree-oid>',
+      },
+    });
+    expect(`${result.stderr ?? ''}`).not.toContain('Usage:');
+  });
+}
+
+function definePlainWriteFlowTests() {
+  it('store reports explicit side effects when creating a vault entry', () => {
+    const input = tempFile(Buffer.from('relay plain store\n'));
+    const result = runAgentCli(
+      ['store', input.filePath, '--slug', 'demo/new-store', '--tree'],
+      repoDir
+    );
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    assertStartRow(rows, {
+      file: input.filePath,
+      slug: 'demo/new-store',
+      tree: true,
+    });
+    expect(rows[1].data).toMatchObject({
+      slug: 'demo/new-store',
+      addedToVault: true,
+      chunkCount: 1,
+      encrypted: false,
+      compressed: false,
+    });
+    expect(rows[1].data.treeOid).toMatch(/^[0-9a-f]{40}$/);
+    expect(rows[1].data.commitOid).toMatch(/^[0-9a-f]{40}$/);
+    expect(rows[1].data.manifest.slug).toBe('demo/new-store');
+
+    rmSync(input.dir, { recursive: true, force: true });
+  });
+}
+
+function defineTreeCommandFilePathTest() {
+  it('tree creates a tree from a manifest file without human formatting', async () => {
+    const manifestDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-manifest-'));
+    const manifestPath = path.join(manifestDir, 'manifest.json');
+    const manifest = await createCas(repoDir).readManifest({ treeOid });
+    writeFileSync(manifestPath, JSON.stringify(manifest.toJSON()));
+
+    const result = runAgentCli(['tree', '--manifest', manifestPath], repoDir);
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    assertStartRow(rows, {
+      manifest: {
+        provided: true,
+        source: 'file',
+      },
+    });
+    expect(rows[1].data).toEqual({
+      treeOid,
+      slug: 'demo/hello',
+      chunkCount: 1,
+      encrypted: false,
+      compressed: false,
+    });
+
+    rmSync(manifestDir, { recursive: true, force: true });
+  });
+}
+
+function defineTreeCommandRequestPayloadTest() {
+  it('tree accepts an inline manifest object through the request payload', async () => {
+    const manifest = await createCas(repoDir).readManifest({ treeOid });
+    const requestPath = path.join(requestDir, 'tree-request.json');
+    writeFileSync(requestPath, JSON.stringify({ manifest: manifest.toJSON() }));
+
+    const result = runAgentCli(['tree', '--request', `@${requestPath}`], repoDir);
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    assertStartRow(rows, {
+      manifest: {
+        provided: true,
+        source: 'inline',
+      },
+    });
+    expect(rows[1].data).toEqual({
+      treeOid,
+      slug: 'demo/hello',
+      chunkCount: 1,
+      encrypted: false,
+      compressed: false,
+    });
+  });
+}
+
+function defineTreeCommandValidationTest() {
+  it('tree emits structured invalid-input errors when no manifest source is provided', () => {
+    const result = runAgentCli(['tree'], repoDir);
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'tree',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --manifest <path> or request.manifest',
+      },
+    });
+  });
+}
+
+function defineRestoreWriteFlowTests() {
+  it('restore reports output path and bytes written without leaking file bytes', () => {
+    const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-restore-'));
+    const outputPath = path.join(outputDir, 'restored.bin');
+    const result = runAgentCli(['restore', '--slug', 'demo/hello', '--out', outputPath], repoDir);
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    expect(rows[1].data).toMatchObject({
+      slug: 'demo/hello',
+      treeOid,
+      outputPath,
+      bytesWritten: original.length,
+      encrypted: false,
+    });
+    expect(rows[1].data.outputPath).not.toContain('hello world');
+
+    rmSync(outputDir, { recursive: true, force: true });
+  });
+}
+
+function storeEncryptedAsset() {
+  const input = tempFile(Buffer.from('relay encrypted store\n'));
+  const result = runAgentCli(
+    [
+      'store',
+      input.filePath,
+      '--slug',
+      'enc/new-store',
+      '--tree',
+      '--vault-passphrase',
+      vaultPassphrase,
+    ],
+    encRepoDir
+  );
+
+  return { result, inputDir: input.dir };
+}
+
+function restoreEncryptedAsset(outputPath) {
+  return runAgentCli(
+    [
+      'restore',
+      '--slug',
+      'enc/new-store',
+      '--out',
+      outputPath,
+      '--vault-passphrase',
+      vaultPassphrase,
+    ],
+    encRepoDir
+  );
+}
+
+function defineEncryptedStoreWithPassphraseTest() {
+  it('encrypted store works with an explicit vault passphrase', () => {
+    const { result, inputDir: storeInputDir } = storeEncryptedAsset();
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const storeRows = parseJsonl(result.stdout);
+    assertStartRow(storeRows, {
+      file: path.join(storeInputDir, 'input.bin'),
+      slug: 'enc/new-store',
+      tree: true,
+      vaultPassphrase: true,
+    });
+    expect(storeRows[1].data).toMatchObject({
+      slug: 'enc/new-store',
+      addedToVault: true,
+      encrypted: true,
+    });
+    expect(result.stdout).not.toContain(vaultPassphrase);
+
+    rmSync(storeInputDir, { recursive: true, force: true });
+  });
+}
+
+function defineEncryptedRestoreWithPassphraseTest() {
+  it('encrypted restore works with an explicit vault passphrase', () => {
+    const { inputDir: storeInputDir } = storeEncryptedAsset();
+    const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-enc-restore-'));
+    const outputPath = path.join(outputDir, 'restored.bin');
+    const restoreResult = restoreEncryptedAsset(outputPath);
+
+    expect(restoreResult.status).toBe(0);
+    expect(`${restoreResult.stderr ?? ''}`).toBe('');
+
+    const restoreRows = parseJsonl(restoreResult.stdout);
+    assertStartRow(restoreRows, {
+      out: outputPath,
+      slug: 'enc/new-store',
+      vaultPassphrase: true,
+    });
+    expect(restoreRows[1].data).toMatchObject({
+      slug: 'enc/new-store',
+      outputPath,
+      encrypted: true,
+    });
+
+    rmSync(outputDir, { recursive: true, force: true });
+    rmSync(storeInputDir, { recursive: true, force: true });
+  });
+}
+
+function defineEncryptedStoreConflictingPassphraseSourcesTest() {
+  it('encrypted store rejects conflicting vault passphrase sources', () => {
+    const storeInput = tempFile(Buffer.from('conflicting passphrase sources\n'));
+    const passphraseFile = tempFile(Buffer.from(`${vaultPassphrase}\n`));
+    const result = runAgentCli(
+      [
+        'store',
+        storeInput.filePath,
+        '--slug',
+        'enc/conflict',
+        '--vault-passphrase',
+        'wrong-passphrase',
+        '--vault-passphrase-file',
+        passphraseFile.filePath,
+      ],
+      encRepoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'store',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --vault-passphrase or --vault-passphrase-file, not both',
+      },
+    });
+
+    cleanupTempDirs(storeInput.dir, passphraseFile.dir);
+  });
+}
+
+function defineStoreEmptyVaultPassphraseKeyConflictTest() {
+  it('store rejects key-file plus an explicitly empty vault passphrase', () => {
+    const storeInput = tempFile(Buffer.from('empty vault passphrase conflict\n'));
+    const keyFile = tempFile(randomBytes(32));
+    const result = runAgentCli(
+      [
+        'store',
+        storeInput.filePath,
+        '--slug',
+        'demo/empty-passphrase-conflict',
+        '--key-file',
+        keyFile.filePath,
+        '--vault-passphrase',
+        '',
+      ],
+      repoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'store',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --key-file or a vault passphrase source, not both',
+      },
+    });
+
+    cleanupTempDirs(storeInput.dir, keyFile.dir);
+  });
+}
+
+function defineStoreRequestBooleanTypeValidationTest() {
+  it('store rejects string boolean fields in request payloads', () => {
+    const storeInput = tempFile(Buffer.from('request boolean validation\n'));
+    const result = runAgentCli(
+      [
+        'store',
+        '--request',
+        JSON.stringify({
+          file: storeInput.filePath,
+          slug: 'demo/request-boolean-validation',
+          tree: 'false',
+          force: 'false',
+        }),
+      ],
+      repoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'store',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Request field "tree" must be a boolean',
+      },
+    });
+
+    cleanupTempDirs(storeInput.dir);
+  });
+}
+
+function defineStoreRequestFileTypeValidationTest() {
+  it('store rejects non-string file fields in request payloads', () => {
+    const result = runAgentCli(
+      [
+        'store',
+        '--request',
+        JSON.stringify({
+          file: 123,
+          slug: 'demo/request-file-validation',
+        }),
+      ],
+      repoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'store',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Request field "file" must be a string',
+      },
+    });
+  });
+}
+
+function defineVaultInitInlinePassphraseRedactionTest() {
+  it('vault init redacts inline passphrases in the start row', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const result = runAgentCli(
+      ['vault', 'init', '--cwd', vaultRepoDir, '--passphrase', 'supersecret'],
+      vaultRepoDir
+    );
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    assertStartRow(rows, {
+      cwd: vaultRepoDir,
+      passphrase: true,
+    });
+    expect(result.stdout).not.toContain('supersecret');
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultInitInlineRequestWhitelistTest() {
+  it('vault init omits unknown request fields from the start row', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const result = runAgentCli(
+      [
+        'vault',
+        'init',
+        '--cwd',
+        vaultRepoDir,
+        '--request',
+        '{"passphrase":"supersecret","token":"supersecret-token"}',
+      ],
+      vaultRepoDir
+    );
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    assertExactStartRow(rows, {
+      cwd: vaultRepoDir,
+      passphrase: true,
+      requestSource: 'inline',
+    });
+    expect(result.stdout).not.toContain('supersecret');
+    expect(result.stdout).not.toContain('supersecret-token');
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultInitPermissionWarningTest() {
+  it('vault init emits structured warnings for insecure passphrase files', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const passphraseFile = tempFile(Buffer.from('relay-warning-passphrase\n'));
+    chmodSync(passphraseFile.filePath, 0o644);
+
+    const result = runAgentCli(
+      ['vault', 'init', '--cwd', vaultRepoDir, '--passphrase-file', passphraseFile.filePath],
+      vaultRepoDir
+    );
+
+    expect(result.status).toBe(0);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    assertStartRow(stdoutRows, {
+      cwd: vaultRepoDir,
+      passphraseFile: true,
+    });
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.init',
+      type: 'warning',
+      data: {
+        code: 'INSECURE_FILE_PERMISSIONS',
+        filePath: path.resolve(passphraseFile.filePath),
+        recommendation: 'chmod 600',
+      },
+    });
+
+    cleanupTempDirs(vaultRepoDir, passphraseFile.dir);
+  });
+}
+
+function defineVaultInitEmptyInlineAndFileConflictTest() {
+  it('vault init rejects an explicitly empty inline passphrase plus a passphrase file', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const passphraseFile = tempFile(Buffer.from('relay-init-passphrase\n'));
+    const result = runAgentCli(
+      [
+        'vault',
+        'init',
+        '--cwd',
+        vaultRepoDir,
+        '--passphrase',
+        '',
+        '--passphrase-file',
+        passphraseFile.filePath,
+      ],
+      vaultRepoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.init',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --passphrase or --passphrase-file, not both',
+      },
+    });
+
+    cleanupTempDirs(vaultRepoDir, passphraseFile.dir);
+  });
+}
+
+function defineVaultInitEmptyStdinPassphraseTest() {
+  it('vault init classifies empty stdin passphrase sources as invalid input', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const result = runAgentCli(
+      ['vault', 'init', '--cwd', vaultRepoDir, '--passphrase-file', '-'],
+      vaultRepoDir,
+      { input: '' }
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    assertStartRow(stdoutRows, {
+      cwd: vaultRepoDir,
+      passphraseFile: true,
+    });
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.init',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Passphrase must not be empty',
+      },
+    });
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultInitMissingPassphraseFileTest() {
+  it('vault init classifies a missing passphrase file as invalid input', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const missingPath = path.join(vaultRepoDir, 'missing-passphrase.txt');
+    const result = runAgentCli(
+      ['vault', 'init', '--cwd', vaultRepoDir, '--passphrase-file', missingPath],
+      vaultRepoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.init',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+      },
+    });
+    expect(stderrRows[0].data.message).toContain('passphrase file');
+    expect(stderrRows[0].data.message).toContain('missing-passphrase.txt');
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultInitInlineRequestRedactionTest() {
+  it('vault init redacts inline request payload secrets in the start row', () => {
+    const vaultRepoDir = createEmptyAgentRepo();
+    const result = runAgentCli(
+      ['vault', 'init', '--cwd', vaultRepoDir, '--request', '{"passphrase":"supersecret"}'],
+      vaultRepoDir
+    );
+
+    expect(result.status).toBe(0);
+    expect(`${result.stderr ?? ''}`).toBe('');
+
+    const rows = parseJsonl(result.stdout);
+    assertStartRow(rows, {
+      cwd: vaultRepoDir,
+      passphrase: true,
+      requestSource: 'inline',
+    });
+    expect(result.stdout).not.toContain('supersecret');
+
+    cleanupTempDirs(vaultRepoDir);
+  });
+}
+
+function defineVaultRotateEmptyInlineAndFileConflictTest() {
+  it('vault rotate rejects an explicitly empty old passphrase plus a file source', async () => {
+    const fixture = await setupVaultRotateRepo();
+    const oldPassphraseFile = tempFile(Buffer.from(`${fixture.oldPassphrase}\n`));
+    const result = runAgentCli(
+      [
+        'vault',
+        'rotate',
+        '--old-passphrase',
+        '',
+        '--old-passphrase-file',
+        oldPassphraseFile.filePath,
+        '--new-passphrase',
+        fixture.newPassphrase,
+      ],
+      fixture.repoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'vault.rotate',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --old-passphrase or --old-passphrase-file, not both',
+      },
+    });
+
+    cleanupTempDirs(
+      fixture.repoDir,
+      fixture.oldKeyFile.dir,
+      fixture.envelopeInput.dir,
+      fixture.directInput.dir,
+      oldPassphraseFile.dir
+    );
+  });
+}
+
+function defineRestoreMissingKeyFileTest() {
+  it('restore classifies a missing key file as invalid input', () => {
+    const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-missing-key-'));
+    const outputPath = path.join(outputDir, 'restored.bin');
+    const missingKeyPath = path.join(outputDir, 'missing.key');
+    const result = runAgentCli(
+      ['restore', '--slug', 'demo/hello', '--out', outputPath, '--key-file', missingKeyPath],
+      repoDir
+    );
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'restore',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+      },
+    });
+    expect(stderrRows[0].data.message).toContain('key file');
+    expect(stderrRows[0].data.message).toContain('missing.key');
+
+    cleanupTempDirs(outputDir);
+  });
+}
+
+function defineTreeMissingManifestFileTest() {
+  it('tree classifies a missing manifest file as invalid input', () => {
+    const missingManifestPath = path.join(repoDir, 'missing-manifest.json');
+    const result = runAgentCli(['tree', '--manifest', missingManifestPath], repoDir);
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['end']);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'tree',
+      type: 'error',
+      data: {
+        code: 'INVALID_INPUT',
+      },
+    });
+    expect(stderrRows[0].data.message).toContain('manifest file');
+    expect(stderrRows[0].data.message).toContain('missing-manifest.json');
+  });
+}
+
+function defineNeedsInputTests() {
+  it('encrypted restore emits needs-input when no key source is provided', () => {
+    const outputDir = mkdtempSync(path.join(os.tmpdir(), 'cas-agent-needs-input-'));
+    const outputPath = path.join(outputDir, 'restored.bin');
+    const result = runAgentCli(['restore', '--slug', 'enc/hello', '--out', outputPath], encRepoDir);
+
+    expect(result.status).toBe(2);
+
+    const stdoutRows = parseJsonl(result.stdout);
+    const stderrRows = parseJsonl(result.stderr);
+
+    expect(stdoutRows.map((row) => row.type)).toEqual(['start', 'end']);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      command: 'restore',
+      type: 'needs-input',
+      data: {
+        code: 'NEEDS_INPUT',
+        message: 'Encrypted restore requires --key-file or a vault passphrase source',
+        requiredInputs: ['keyFile', 'vaultPassphrase', 'vaultPassphraseFile'],
+        slug: 'enc/hello',
+        treeOid: encTreeOid,
+      },
+    });
+
+    rmSync(outputDir, { recursive: true, force: true });
+  });
+}
+
+describe('agent CLI protocol — read commands', defineReadOnlyProtocolTests);
+describe('agent CLI protocol — vault commands', defineVaultProtocolTests);
+describe('agent CLI protocol — recipient list (slug)', defineRecipientListSlugTest);
+describe(
+  'agent CLI protocol — recipient list (request payload)',
+  defineRecipientListRequestPayloadTest
+);
+describe('agent CLI protocol — recipient list (plaintext)', defineRecipientListPlaintextTest);
+describe('agent CLI protocol — recipient list (validation)', defineRecipientListValidationTest);
+describe(
+  'agent CLI protocol — recipient add (request payload)',
+  defineRecipientAddRequestPayloadTest
+);
+describe('agent CLI protocol — recipient remove (success)', defineRecipientRemoveSuccessTest);
+describe(
+  'agent CLI protocol — recipient add (duplicate label)',
+  defineRecipientAddDuplicateLabelTest
+);
+describe(
+  'agent CLI protocol — recipient remove (last recipient)',
+  defineRecipientRemoveLastRecipientTest
+);
+describe('agent CLI protocol — rotate (slug)', defineRotateSlugSuccessTest);
+describe('agent CLI protocol — rotate (request payload)', defineRotateRequestPayloadTest);
+describe('agent CLI protocol — rotate (validation)', defineRotateValidationTest);
+describe('agent CLI protocol — rotate (wrong old key)', defineRotateWrongOldKeyTest);
+describe('agent CLI protocol — vault rotate (success)', defineVaultRotateSuccessTest);
+describe(
+  'agent CLI protocol — vault rotate (request payload)',
+  defineVaultRotateRequestPayloadTest
+);
+describe('agent CLI protocol — vault rotate (validation)', defineVaultRotateValidationTest);
+describe(
+  'agent CLI protocol — vault rotate (wrong passphrase)',
+  defineVaultRotateWrongPassphraseTest
+);
+describe('agent CLI protocol — vault init (plaintext)', defineVaultInitPlaintextTest);
+describe(
+  'agent CLI protocol — vault init (encrypted request payload)',
+  defineVaultInitEncryptedRequestPayloadTest
+);
+describe('agent CLI protocol — vault init (validation)', defineVaultInitValidationTest);
+describe(
+  'agent CLI protocol — vault init (inline passphrase redaction)',
+  defineVaultInitInlinePassphraseRedactionTest
+);
+describe(
+  'agent CLI protocol — vault init (inline request whitelist)',
+  defineVaultInitInlineRequestWhitelistTest
+);
+describe(
+  'agent CLI protocol — vault init (permission warning)',
+  defineVaultInitPermissionWarningTest
+);
+describe(
+  'agent CLI protocol — vault init (empty inline and file conflict)',
+  defineVaultInitEmptyInlineAndFileConflictTest
+);
+describe(
+  'agent CLI protocol — vault init (empty stdin passphrase)',
+  defineVaultInitEmptyStdinPassphraseTest
+);
+describe(
+  'agent CLI protocol — vault init (missing passphrase file)',
+  defineVaultInitMissingPassphraseFileTest
+);
+describe(
+  'agent CLI protocol — vault init (inline request redaction)',
+  defineVaultInitInlineRequestRedactionTest
+);
+describe('agent CLI protocol — vault remove (success)', defineVaultRemoveSuccessTest);
+describe('agent CLI protocol — vault remove (missing entry)', defineVaultRemoveMissingEntryTest);
+describe('agent CLI protocol — request and validation', defineRequestAndValidationTests);
+describe('agent CLI protocol — store write flow', definePlainWriteFlowTests);
+describe('agent CLI protocol — tree command (file path)', defineTreeCommandFilePathTest);
+describe(
+  'agent CLI protocol — tree command (request payload)',
+  defineTreeCommandRequestPayloadTest
+);
+describe('agent CLI protocol — tree command (validation)', defineTreeCommandValidationTest);
+describe('agent CLI protocol — restore write flow', defineRestoreWriteFlowTests);
+describe(
+  'agent CLI protocol — encrypted store (vault passphrase)',
+  defineEncryptedStoreWithPassphraseTest
+);
+describe(
+  'agent CLI protocol — encrypted restore (vault passphrase)',
+  defineEncryptedRestoreWithPassphraseTest
+);
+describe(
+  'agent CLI protocol — encrypted store (conflicting vault passphrase sources)',
+  defineEncryptedStoreConflictingPassphraseSourcesTest
+);
+describe(
+  'agent CLI protocol — store (empty vault passphrase plus key conflict)',
+  defineStoreEmptyVaultPassphraseKeyConflictTest
+);
+describe(
+  'agent CLI protocol — store (request boolean type validation)',
+  defineStoreRequestBooleanTypeValidationTest
+);
+describe(
+  'agent CLI protocol — store (request file type validation)',
+  defineStoreRequestFileTypeValidationTest
+);
+describe(
+  'agent CLI protocol — vault rotate (empty inline and file conflict)',
+  defineVaultRotateEmptyInlineAndFileConflictTest
+);
+describe(
+  'agent CLI protocol — restore (missing key file)',
+  defineRestoreMissingKeyFileTest
+);
+describe(
+  'agent CLI protocol — tree command (missing manifest file)',
+  defineTreeMissingManifestFileTest
+);
+describe('agent CLI protocol — needs-input', defineNeedsInputTests);
diff --git a/test/integration/vault-cli.test.js b/test/integration/vault-cli.test.js
index d068fae..5a24fb1 100644
--- a/test/integration/vault-cli.test.js
+++ b/test/integration/vault-cli.test.js
@@ -43,19 +43,28 @@ const RUNTIME_CMD = globalThis.Bun
 
 /**
  * Run a CLI command and capture stdout/stderr without routing through /bin/sh.
+ *
+ * @param {string[]} args
+ * @param {string} cwd
+ * @param {{ env?: Record<string, string | undefined> }} [options]
  */
-function runCli(args, cwd) {
+function runCli(args, cwd, options = {}) {
   return spawnSync(RUNTIME_CMD[0], [...RUNTIME_CMD.slice(1), ...args, '--cwd', cwd], {
     encoding: 'utf8',
+    env: { ...process.env, ...(options.env || {}) },
     timeout: 90_000,
   });
 }
 
 /**
  * Run a CLI command, returning trimmed stdout.
+ *
+ * @param {string[]} args
+ * @param {string} cwd
+ * @param {{ env?: Record<string, string | undefined> }} [options]
  */
-function cli(args, cwd) {
-  const result = runCli(args, cwd);
+function cli(args, cwd, options = {}) {
+  const result = runCli(args, cwd, options);
 
   if (result.error) {
     throw result.error;
@@ -100,6 +109,15 @@ function tempFile(content) {
   return { filePath: fp, dir };
 }
 
+/**
+ * Helper: create a throwaway bare repo for isolated validation tests.
+ */
+function tempRepo(prefix = 'cas-cli-repo-') {
+  const dir = mkdtempSync(path.join(os.tmpdir(), prefix));
+  initBareRepo(dir);
+  return dir;
+}
+
 // Shared state for the plaintext workflow describes
 let repoDir;
 const original = randomBytes(4096);
@@ -189,6 +207,137 @@ describe('vault CLI — diagnostics', () => {
   });
 });
 
+describe('vault CLI — validation', () => { // eslint-disable-line max-lines-per-function
+  it('vault init rejects --algorithm without a passphrase source', () => {
+    const validationRepoDir = tempRepo('cas-cli-init-validation-');
+
+    try {
+      const result = runCli(
+        ['vault', 'init', '--algorithm', 'scrypt'],
+        validationRepoDir,
+        { env: { GIT_CAS_PASSPHRASE: undefined } },
+      );
+
+      expect(result.status).toBe(1);
+      expect(`${result.stderr ?? ''}`).toContain(
+        'Provide --vault-passphrase or --vault-passphrase-file when using --algorithm',
+      );
+    } finally {
+      rmSync(validationRepoDir, { recursive: true, force: true });
+    }
+  });
+
+  it('vault init rejects an explicitly empty inline passphrase plus a passphrase file', () => {
+    const validationRepoDir = tempRepo('cas-cli-init-passphrase-conflict-');
+    const passphraseFile = tempFile(Buffer.from('passphrase-from-file\n'));
+
+    try {
+      const result = runCli(
+        [
+          'vault',
+          'init',
+          '--vault-passphrase',
+          '',
+          '--vault-passphrase-file',
+          passphraseFile.filePath,
+        ],
+        validationRepoDir,
+      );
+
+      expect(result.status).toBe(1);
+      expect(`${result.stderr ?? ''}`).toContain(
+        'Provide --vault-passphrase or --vault-passphrase-file, not both',
+      );
+    } finally {
+      rmSync(validationRepoDir, { recursive: true, force: true });
+      rmSync(passphraseFile.dir, { recursive: true, force: true });
+    }
+  });
+
+  it('store rejects key-file plus an explicitly empty vault passphrase', () => {
+    const validationRepoDir = tempRepo('cas-cli-store-validation-');
+    const input = tempFile(Buffer.from('store validation payload\n'));
+    const keyFile = tempFile(randomBytes(32));
+
+    try {
+      cli(['vault', 'init'], validationRepoDir);
+
+      const result = runCli(
+        [
+          'store',
+          input.filePath,
+          '--tree',
+          '--slug',
+          'validation/store-conflict',
+          '--key-file',
+          keyFile.filePath,
+          '--vault-passphrase',
+          '',
+        ],
+        validationRepoDir,
+      );
+
+      expect(result.status).toBe(1);
+      expect(`${result.stderr ?? ''}`).toContain(
+        'Provide --key-file or a vault passphrase source, not both',
+      );
+    } finally {
+      rmSync(validationRepoDir, { recursive: true, force: true });
+      rmSync(input.dir, { recursive: true, force: true });
+      rmSync(keyFile.dir, { recursive: true, force: true });
+    }
+  });
+
+  it('restore rejects key-file plus an explicitly empty vault passphrase', () => {
+    const validationRepoDir = tempRepo('cas-cli-restore-validation-');
+    const input = tempFile(Buffer.from('restore validation payload\n'));
+    const keyFile = tempFile(randomBytes(32));
+    const outDir = mkdtempSync(path.join(os.tmpdir(), 'cas-cli-restore-validation-out-'));
+    const outPath = path.join(outDir, 'restored.bin');
+
+    try {
+      cli(['vault', 'init'], validationRepoDir);
+      cli(
+        [
+          'store',
+          input.filePath,
+          '--tree',
+          '--slug',
+          'validation/restore-conflict',
+          '--key-file',
+          keyFile.filePath,
+        ],
+        validationRepoDir,
+      );
+
+      const result = runCli(
+        [
+          'restore',
+          '--slug',
+          'validation/restore-conflict',
+          '--out',
+          outPath,
+          '--key-file',
+          keyFile.filePath,
+          '--vault-passphrase',
+          '',
+        ],
+        validationRepoDir,
+      );
+
+      expect(result.status).toBe(1);
+      expect(`${result.stderr ?? ''}`).toContain(
+        'Provide --key-file or a vault passphrase source, not both',
+      );
+    } finally {
+      rmSync(validationRepoDir, { recursive: true, force: true });
+      rmSync(input.dir, { recursive: true, force: true });
+      rmSync(keyFile.dir, { recursive: true, force: true });
+      rmSync(outDir, { recursive: true, force: true });
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // vault restore + remove + re-add
 // ---------------------------------------------------------------------------
@@ -221,7 +370,7 @@ describe('vault CLI — restore, remove, re-add', () => {
 // ---------------------------------------------------------------------------
 // Encrypted vault CLI workflow
 // ---------------------------------------------------------------------------
-describe('vault CLI — encrypted workflow', () => {
+describe('vault CLI — encrypted workflow', () => { // eslint-disable-line max-lines-per-function
   let encRepoDir;
   const encOriginal = randomBytes(2048);
   let encInputFile;
@@ -244,6 +393,30 @@ describe('vault CLI — encrypted workflow', () => {
     expect(out).toMatch(/^[0-9a-f]{40}$/);
   });
 
+  it('vault rotate rejects whitespace-only old passphrases', () => {
+    const result = runCli(
+      ['vault', 'rotate', '--old-passphrase', '   ', '--new-passphrase', 'next-passphrase'],
+      encRepoDir,
+    );
+
+    expect(result.status).toBe(1);
+    expect(`${result.stderr ?? ''}`).toContain(
+      'Old passphrase required (--old-passphrase or --old-passphrase-file)',
+    );
+  });
+
+  it('vault rotate rejects whitespace-only new passphrases', () => {
+    const result = runCli(
+      ['vault', 'rotate', '--old-passphrase', passphrase, '--new-passphrase', '   '],
+      encRepoDir,
+    );
+
+    expect(result.status).toBe(1);
+    expect(`${result.stderr ?? ''}`).toContain(
+      'New passphrase required (--new-passphrase or --new-passphrase-file)',
+    );
+  });
+
   it('encrypted store --tree --vault-passphrase prints tree OID', () => {
     const out = cli(
       ['store', encInputFile, '--tree', '--slug', 'enc/asset', '--vault-passphrase', passphrase],
@@ -306,6 +479,16 @@ describe('vault CLI — rotate', () => { // eslint-disable-line max-lines-per-fu
     expect(oid).toMatch(/^[0-9a-f]{40}$/);
   });
 
+  it('store --recipient ignores ambient vault passphrase env state', () => {
+    const oid = cli(
+      ['store', rotateInputFile, '--tree', '--slug', 'rotate/env-asset', '--recipient', `bob:${oldKeyFile}`],
+      rotateRepoDir,
+      { env: { GIT_CAS_PASSPHRASE: 'ambient-secret' } },
+    );
+
+    expect(oid).toMatch(/^[0-9a-f]{40}$/);
+  });
+
   it('rotate --slug rotates key and updates vault', () => {
     const oid = cli(
       ['rotate', '--slug', 'rotate/asset', '--old-key-file', oldKeyFile, '--new-key-file', newKeyFile],
diff --git a/test/integration/vault.test.js b/test/integration/vault.test.js
index 9be4232..5f774cc 100644
--- a/test/integration/vault.test.js
+++ b/test/integration/vault.test.js
@@ -7,7 +7,7 @@
  * MUST run inside Docker (GIT_STUNTS_DOCKER=1). Refuses to run on the host.
  */
 
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
@@ -22,10 +22,15 @@ import { createGitPlumbing } from '../../src/infrastructure/createGitPlumbing.js
 if (process.env.GIT_STUNTS_DOCKER !== '1') {
   throw new Error(
     'Integration tests MUST run inside Docker (GIT_STUNTS_DOCKER=1). ' +
-    'Use: npm run test:integration:node',
+      'Use: npm run test:integration:node'
   );
 }
 
+vi.setConfig({
+  testTimeout: 15000,
+  hookTimeout: 30000,
+});
+
 let repoDir;
 let cas;
 
@@ -152,7 +157,7 @@ describe('vault remove', () => {
 
   it('throws VAULT_ENTRY_NOT_FOUND for missing slug', async () => {
     await expect(cas.removeFromVault({ slug: 'nonexistent' })).rejects.toSatisfy(
-      (e) => e instanceof CasError && e.code === 'VAULT_ENTRY_NOT_FOUND',
+      (e) => e instanceof CasError && e.code === 'VAULT_ENTRY_NOT_FOUND'
     );
   });
 });
@@ -167,10 +172,8 @@ describe('vault add with force overwrite', () => {
     const newTree = await cas.createTree({ manifest });
     rmSync(dir, { recursive: true, force: true });
 
-    await expect(
-      cas.addToVault({ slug: 'integ/asset-1', treeOid: newTree }),
-    ).rejects.toSatisfy(
-      (e) => e instanceof CasError && e.code === 'VAULT_ENTRY_EXISTS',
+    await expect(cas.addToVault({ slug: 'integ/asset-1', treeOid: newTree })).rejects.toSatisfy(
+      (e) => e instanceof CasError && e.code === 'VAULT_ENTRY_EXISTS'
     );
   });
 
@@ -221,10 +224,8 @@ describe('encrypted vault', () => {
   });
 
   it('throws VAULT_ENCRYPTION_ALREADY_CONFIGURED on re-init', async () => {
-    await expect(
-      encCas.initVault({ passphrase: 'different' }),
-    ).rejects.toSatisfy(
-      (e) => e instanceof CasError && e.code === 'VAULT_ENCRYPTION_ALREADY_CONFIGURED',
+    await expect(encCas.initVault({ passphrase: 'different' })).rejects.toSatisfy(
+      (e) => e instanceof CasError && e.code === 'VAULT_ENCRYPTION_ALREADY_CONFIGURED'
     );
   });
 });
diff --git a/test/unit/cli/agent-protocol.test.js b/test/unit/cli/agent-protocol.test.js
new file mode 100644
index 0000000..5c4d0a3
--- /dev/null
+++ b/test/unit/cli/agent-protocol.test.js
@@ -0,0 +1,107 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  AGENT_EXIT_CODES,
+  AGENT_PROTOCOL,
+  createAgentSession,
+  getAgentExitCode,
+} from '../../../bin/agent/protocol.js';
+
+function createFakeStream() {
+  const writes = [];
+  return {
+    writes,
+    write: vi.fn((chunk) => {
+      writes.push(String(chunk));
+      return true;
+    }),
+  };
+}
+
+function defineAgentSessionStdoutTests() {
+  it('writes ordered protocol rows to stdout', () => {
+    const stdout = createFakeStream();
+    const stderr = createFakeStream();
+    const session = createAgentSession({
+      command: 'inspect',
+      stdout,
+      stderr,
+      now: () => new Date('2026-03-25T19:15:00.000Z'),
+    });
+
+    session.writeStart({ argv: ['inspect', '--slug', 'demo/hello'] });
+    session.writeResult({ treeOid: 'abc123' });
+    session.writeEnd({ ok: true, exitCode: 0 });
+
+    const rows = stdout.writes.map((line) => JSON.parse(line));
+    expect(rows).toHaveLength(3);
+    expect(rows.map((row) => row.type)).toEqual(['start', 'result', 'end']);
+    expect(rows.map((row) => row.seq)).toEqual([1, 2, 3]);
+    expect(rows.every((row) => row.protocol === AGENT_PROTOCOL)).toBe(true);
+    expect(rows.every((row) => row.command === 'inspect')).toBe(true);
+    expect(rows[1].data).toEqual({ treeOid: 'abc123' });
+    expect(stderr.write).not.toHaveBeenCalled();
+  });
+}
+
+function defineAgentSessionErrorTests() {
+  it('writes structured errors to stderr with the shared sequence', () => {
+    const stdout = createFakeStream();
+    const stderr = createFakeStream();
+    const session = createAgentSession({
+      command: 'inspect',
+      stdout,
+      stderr,
+      now: () => new Date('2026-03-25T19:15:00.000Z'),
+    });
+
+    session.writeStart({ argv: ['inspect'] });
+    session.writeError(
+      Object.assign(new Error('Provide --slug <slug> or --oid <tree-oid>'), {
+        code: 'INVALID_INPUT',
+        meta: { command: 'inspect' },
+      })
+    );
+    session.writeEnd({ ok: false, exitCode: 2 });
+
+    const stdoutRows = stdout.writes.map((line) => JSON.parse(line));
+    const stderrRows = stderr.writes.map((line) => JSON.parse(line));
+
+    expect(stdoutRows.map((row) => row.seq)).toEqual([1, 3]);
+    expect(stderrRows).toHaveLength(1);
+    expect(stderrRows[0]).toMatchObject({
+      protocol: AGENT_PROTOCOL,
+      command: 'inspect',
+      type: 'error',
+      seq: 2,
+      data: {
+        code: 'INVALID_INPUT',
+        message: 'Provide --slug <slug> or --oid <tree-oid>',
+        retryable: false,
+        hint: 'Check the agent command name and required input fields',
+        meta: { command: 'inspect' },
+      },
+    });
+  });
+}
+
+function defineAgentExitCodeTests() {
+  it('maps invalid input to exit code 2', () => {
+    expect(getAgentExitCode(Object.assign(new Error('bad args'), { code: 'INVALID_INPUT' }))).toBe(
+      AGENT_EXIT_CODES.INVALID_INPUT
+    );
+  });
+
+  it('maps integrity errors to exit code 3', () => {
+    expect(
+      getAgentExitCode(Object.assign(new Error('bad hash'), { code: 'INTEGRITY_ERROR' }))
+    ).toBe(AGENT_EXIT_CODES.VERIFICATION_FAILED);
+  });
+
+  it('maps unknown failures to exit code 1', () => {
+    expect(getAgentExitCode(new Error('boom'))).toBe(AGENT_EXIT_CODES.FAILURE);
+  });
+}
+
+describe('agent protocol session — stdout', defineAgentSessionStdoutTests);
+describe('agent protocol session — stderr', defineAgentSessionErrorTests);
+describe('getAgentExitCode', defineAgentExitCodeTests);