diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26ab5467..fef9e0fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,33 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- **v0.3 alpha — local file ingest + run chains.** `stacy brain create --file`
+  and `--dir`/`--glob`/`--ext` turn local text/markdown/json files into signed
+  Knowledge Objects with **no connector and no credentials** (leak-safe
+  cwd-relative source labels; dotfiles/`node_modules`/`.git`/symlinks/binary/
+  oversized files skipped). `stacy run --chain <spec.json>` composes multi-step
+  runs where a later step consumes an earlier step's `agent_output` via an
+  `@<stepId>` reference (validated before egress, gated once, one-hop
+  provenance, abort-on-step-failure). Together they make the whole ingest → run
+  → synthesize loop runnable offline. See
+  `docs/v0.3-files-and-chains-quickstart.md`.
+
+### Fixed
+- **Run-result caching now composes across chain steps** (verified live). Two
+  changes: (1) `agent_output` content no longer embeds a wall-clock
+  `generatedAt`; (2) the run cache keys inputs on their **content**, not on the
+  KO `contentHash` (which folds in `createdAt`, so it changes every time a KO is
+  created even for identical content). Without (2) a chain's downstream step —
+  whose input is the prior step's freshly-created output KO — missed the cache
+  on every run. Now an identical chain re-run makes **zero adapter calls**. KO
+  `contentHash` is still used for provenance; generation time still lives on the
+  KO record and the `run` receipt.
+
+### Changed
+- Extracted a reusable `runOnce` run executor (single-run verb and run chains
+  share it); single-run behavior is unchanged.
+
+### Added (v0.2 alpha)
 - **v0.2 alpha — connectors + AI runs.** GitHub connector (OAuth device-code
   flow, encrypted-at-rest token storage, sliding-window rate limiting), the
   `stacy connect` / `connectors list|status|disconnect` / `ingest` verbs that
diff --git a/TODOS.md b/TODOS.md
new file mode 100644
index 00000000..c784d7a9
--- /dev/null
+++ b/TODOS.md
@@ -0,0 +1,93 @@
+# TODOS
+
+Deferred work, captured so it is not silently lost. Each item has enough context
+to pick up cold.
+
+## Later — Generic ingest refactor + `fs`/Linear as real Connectors
+
+- **What:** Refactor `verbs/ingest.ts` (currently `ingestGithubCommand`, GitHub-
+  specific) into a generic registry-driven `ingestCommand(connectorId, params)`,
+  and implement `fs` as a real `Connector` (with `authType: "none"`).
+- **Why deferred:** Eng review (Codex outside voice #12) showed this is premature
+  for the alpha. `brain create --file` (v0.3 W1) unblocks the zero-credential loop
+  without touching connector auth/registry/connect/status. The framework refactor
+  only pays off once a second OAuth connector (Linear) justifies it.
+- **Scope when revisited (holes the review found):** `authType: "none"` is a core
+  interface change — `Connector.authenticate/status/ingest` and
+  `IngestOptions.token` all currently require `TokenBundle`
+  (`connectors/types.ts:44,77`). `connectors list/status` derive "connected" from
+  keychain entries, so a no-auth connector needs a status story. The confirmation
+  count currently forces full enumeration before storing — reconcile with
+  streaming. Command registration lives in `packages/federation/verbs/index.ts`,
+  not just `cli/src/index.ts`.
+- **Depends on:** a concrete second connector (Linear) to justify the work.
+
+## ~~Bug — Postgres NOTICE lines pollute `--json` stdout~~ — FIXED 2026-06-03
+
+- **What:** Federation commands self-create tables/indexes with
+  `CREATE INDEX IF NOT EXISTS`; on an existing DB Postgres emitted a `NOTICE`
+  ("relation ... already exists, skipping") that the `postgres` driver printed to
+  **stdout**, ahead of the JSON, breaking `--json` for strict parsers.
+- **Fix:** `createDb` in `packages/db/src/client.ts` now passes
+  `onnotice: () => {}` (matching the existing `createUtilitySql` factory).
+  Verified live before/after: `brain create --file --json` against an
+  initialized DB now emits only the JSON object on stdout (`python3 -m
+  json.tool` parses it cleanly; before, three NOTICE objects preceded it).
+
+## Observation — KO content hash folds in `createdAt`
+
+- Not a bug (the v0.3 run cache now keys on content, so chain caching works), but
+  worth recording: `knowledge-object.ts:57,60` includes `createdAt` in the
+  hashed payload, so identical content created at different times yields
+  different KO ids/hashes. If true content-addressing is ever wanted
+  (re-creating identical content → same id), that is a core-model change needing
+  its own review (federation/consent/dedup implications). Deferred.
+
+## Later — `brain lineage <ko>` graph-walk command
+
+- **What:** A command/visualizer that walks `provenance.inputKoIds` edges to show
+  a KO's full lineage back to its original inputs.
+- **Why:** v0.3 uses one-hop provenance (each KO lists direct inputs only). Full
+  lineage is *derivable* by walking edges but there's no tool to do it. Eng
+  review (#9) flagged that a graph-walk exit criterion needs a real walker.
+- **Where:** new `brain lineage` verb over `agent-output` content `inputKoIds` +
+  run receipts.
+
+## v0.3.1 — Linear connector (deferred from Phase 3 / W2)
+
+- **What:** Add a Linear connector (issues → signed `document`/`issue` KOs) on
+  the W0 generic ingest path.
+- **Why:** Second real connector — proves the framework against a non-GitHub
+  OAuth + GraphQL shape and gives the run/chain loop a second real source.
+- **Blocker to resolve first:** Linear has **no OAuth device-code flow** (the
+  affordance GitHub's `connect` UX is built on). Decide: localhost-redirect
+  OAuth listener vs. **personal access token** (`authType: "api-key"`). PAT is
+  the leaning for alpha speed.
+- **Where to start:** `packages/federation/src/connectors/linear/`
+  (`connector.ts`, `api.ts` GraphQL client, `normalize.ts`); register in
+  `connectors/registry.ts`; CLI flag→params mapping in `cli/src/index.ts`
+  (`--team`, `--state`, `--label`, `--since`). Env `STACY_LINEAR_CLIENT_ID` or a
+  PAT entry in the keychain.
+- **Depends on:** Phase 3 W0 (generic `ingestCommand`) landing first.
+
+## v0.3.1 — Real-API robustness (deferred from Phase 3 / W4)
+
+- **What:** Rate-limit backoff/retry + resumable ingest cursor.
+- **Why:** Repeated dogfooding against real APIs hits 429s and transient
+  failures; today an interrupted `ingest` restarts from scratch.
+- **Where to start:** centralize retry/backoff in `connectors/http.ts` (honor
+  `Retry-After` / `X-RateLimit-Reset`; `rate-limiter.ts` already models the
+  window). Add a per-(connector, source) cursor file under
+  `<instance>/connectors/` so `ingest` resumes. Optional: a provider-agnostic
+  second reference adapter in `scripts/` to prove the adapter contract.
+- **Depends on:** best done once ≥2 connectors exist (after W2) so there is real
+  load to harden against.
+
+## Post-v0.2 — Independent validation gate (carryover)
+
+- **What:** Independent engineer validates the live GitHub + Anthropic paths
+  with their own credentials; meet design-partner metrics (15 alpha users, ≥10
+  real ingests, ≥5 `agent_output` KOs).
+- **Why:** `releases/v2026.602.0.md` is **Draft** until this clears; it also
+  gates tagging public v0.3.
+- **Where:** `PHASE-2-HANDOFF.md` §4 test plan.
diff --git a/cli/src/index.ts b/cli/src/index.ts
index 4d9fb106..4675bd18 100644
--- a/cli/src/index.ts
+++ b/cli/src/index.ts
@@ -27,7 +27,7 @@ import { registerPluginCommands } from "./commands/client/plugin.js";
 import { registerClientAuthCommands } from "./commands/client/auth.js";
 import { cliVersion } from "./version.js";
 import { applyStacyEnvAliases } from "./config/env-aliases.js";
-import { agentRunCommand, registerFederationCommands, runTaskCommand } from "@arpanstacy/stacy-federation/verbs";
+import { agentRunCommand, registerFederationCommands, runChainCommand, runTaskCommand } from "@arpanstacy/stacy-federation/verbs";
 
 const program = new Command();
 applyStacyEnvAliases();
@@ -148,6 +148,7 @@ program
   .option("--repair", "Attempt automatic repairs during doctor", true)
   .option("--no-repair", "Disable automatic repairs during doctor")
   .option("--use <ko_id>", "Input Knowledge Object for an AI run; repeat for multiple", collectOption, [])
+  .option("--chain <path>", "Run a multi-step chain from a JSON spec file (steps[] with @stepId refs)")
   .option("--model <name>", "Model identifier passed to the run adapter")
   .option("--adapter <name>", "Run adapter to use: anthropic (default) or deterministic")
   .option("--input <path>", "Input file for a public federation demo task")
@@ -164,6 +165,10 @@ program
   .option("--db-url <url>", "Database connection string")
   .option("--json", "Print raw JSON output", false)
   .action(async (task, opts) => {
+    if (typeof opts.chain === "string" && opts.chain.trim()) {
+      await runChainCommand({ ...opts, noCache: opts.cache === false });
+      return;
+    }
     if (typeof task === "string" && task.trim()) {
       if (Array.isArray(opts.use) && opts.use.length > 0) {
         await agentRunCommand(task, { ...opts, noCache: opts.cache === false });
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 4f87a44a..bd05f88e 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -36,14 +36,30 @@ Operations on locally stored signed Knowledge Objects (KOs).
 ### `stacy brain create`
 Create and store a local signed Knowledge Object.
 
+Provide content one of four ways: inline JSON, a prompt, a single local file, or
+a directory of files. The file/directory modes are credential-free.
+
 | Option | Description |
 | --- | --- |
 | `--content-json <json>` | KO content as inline JSON. |
 | `--prompt <text>` | Generate KO content from a prompt. |
+| `--file <path>` | Create a KO from a local text/markdown/json file (no credentials). Wraps it in a `{ kind: "document", source, mediaType, text\|data }` envelope. |
+| `--dir <path>` | Create one KO per file under a directory (no credentials). |
+| `--glob <pattern>` | Glob pattern for `--dir`, e.g. `'**/*.md'` (relative to `--dir` or cwd). |
+| `--ext <list>` | Comma-separated extension allowlist for directory ingest, e.g. `md,txt,json`. |
+| `--source-label <label>` | Override the `--file` provenance label (default: cwd-relative path, basename if outside cwd). |
+| `--max-bytes <n>` | Max file size for `--file`/`--dir` in bytes (default `1048576`). |
+| `--yes` | Skip the directory-ingest confirmation prompt (for scripting). |
 | `--adapter-command <command>` | Adapter-like command that reads the prompt on stdin and writes output. |
 | `--adapter-arg <arg>` | Argument passed to `--adapter-command`; repeat for multiple. |
 | `--content-type <type>` | KO content type (default `application/json`). |
-| `--ko-id <id>` | Deterministic KO id (for harness runs). |
+| `--ko-id <id>` | Deterministic KO id (single-object modes only). |
+
+Exactly one of `--content-json`, `--prompt`, or `--file` may be given. Directory
+mode (`--dir`/`--glob`/`--ext`) skips dotfiles, `node_modules`, `.git`, and
+symlinks; binary and oversized files are skipped with a warning rather than
+aborting the batch. Source labels are always cwd-relative (or a bare filename
+when the file sits outside cwd), so absolute paths never leak into shareable KOs.
 
 ### `stacy brain list`
 List locally stored signed Knowledge Objects.
@@ -153,11 +169,12 @@ instead.
 
 | Option | Description |
 | --- | --- |
-| `--use <ko_id>` | Input Knowledge Object for the run; repeat for multiple. At least one is required. |
+| `--use <ko_id>` | Input Knowledge Object for the run; repeat for multiple. At least one is required (single-run mode). |
+| `--chain <path>` | Run a multi-step chain from a JSON spec file instead of a single run. Mutually exclusive with `--use`. |
 | `--model <name>` | Model identifier passed to the adapter (default `claude-sonnet-4-5`). |
 | `--adapter <name>` | `anthropic` (default) or `deterministic`. |
 | `--ack-egress` | Acknowledge that a non-deterministic adapter may send input KO content outside this install. |
-| `--ko-id <id>` | Deterministic output KO id (for harness runs). |
+| `--ko-id <id>` | Deterministic output KO id (single-run mode only). |
 | `--no-cache` | Skip the run-result cache and force a fresh adapter call. |
 
 **Adapters.** The `deterministic` adapter is offline, makes no network call, and
@@ -173,6 +190,32 @@ The cache key is independent of `--use` ordering.
 Every run loads and verifies each input KO, then emits `create`, `sign`, and
 `run` receipts for the new `agent_output` KO.
 
+### Run chains — `stacy run --chain <spec.json>`
+
+Compose runs: a later step consumes an earlier step's `agent_output` KO via an
+`@<stepId>` reference. The spec is an ordered `steps[]` array:
+
+```jsonc
+{
+  "steps": [
+    { "id": "per_doc",   "task": "Summarize each document", "use": ["ko_a", "ko_b"] },
+    { "id": "synthesis", "task": "Synthesize one report",   "use": ["@per_doc"] }
+  ]
+}
+```
+
+```bash
+stacy run --chain ./chain.json --adapter deterministic
+```
+
+Each step is a full run (`--model`/`--adapter`/`--ack-egress`/`--no-cache` apply
+to the whole chain; a step may override `model`). The spec is validated and all
+`@ref`s resolved **before** the egress gate or any KO read — a forward, unknown,
+or self reference fails immediately. Egress is acknowledged once for the whole
+chain. Provenance is one-hop (each step lists its direct inputs). A step failure
+aborts the chain and names the failed step; already-produced step KOs stay
+durable. See [Concept: AI Runs](concepts/ai-runs.md#run-chains-v03).
+
 ---
 
 ## Sharing & revocation
diff --git a/docs/concepts/ai-runs.md b/docs/concepts/ai-runs.md
index 271e3071..f45305dd 100644
--- a/docs/concepts/ai-runs.md
+++ b/docs/concepts/ai-runs.md
@@ -91,3 +91,47 @@ acknowledgement.
 
 See the [v0.2 quickstart](../v0.2-connectors-and-runs-quickstart.md) for the
 end-to-end flow.
+
+## Run chains (v0.3)
+
+A single run is one task over a flat list of inputs. A **run chain** composes
+several runs, where a later step consumes an earlier step's `agent_output` KO as
+input. This expresses "summarize each source, then synthesize one report" as a
+single command.
+
+A chain is a JSON file with an ordered `steps[]` array. A step references a prior
+step's output with `@<stepId>`:
+
+```jsonc
+{
+  "steps": [
+    { "id": "per_doc",   "task": "Summarize each document", "use": ["ko_a", "ko_b"] },
+    { "id": "synthesis", "task": "Synthesize one report",   "use": ["@per_doc"] }
+  ]
+}
+```
+
+```bash
+stacy run --chain ./chain.json --adapter deterministic
+```
+
+```text
+per_doc   use: [ko_a, ko_b] ──run──► ko_out1
+synthesis use: [@per_doc]   ──run──► ko_final   (@per_doc resolves to ko_out1)
+```
+
+Guarantees:
+
+- **Validated up front.** The spec is parsed and every `@ref` is checked
+  *before* the egress gate and before any KO is read. A forward, unknown, or
+  self reference fails immediately — no partial run, no egress.
+- **Egress gated once.** A non-deterministic adapter still requires
+  `--ack-egress`, checked a single time before the first step.
+- **One-hop provenance.** Each step's `agent_output` lists only its direct
+  inputs (`synthesis → [per_doc output] → [ko_a, ko_b]`). Full lineage is the
+  graph walk across those edges; nothing is flattened or duplicated.
+- **Caching composes.** Each step is cached by `(task, model, adapter, input
+  content hashes)`. Because `agent_output` content is timestamp-free, an
+  identical chain re-run reuses every step and makes zero adapter calls.
+- **Abort on failure.** If a step fails, the chain stops and names the failed
+  step. Already-produced step KOs remain durable (no rollback).
diff --git a/docs/stacy/PHASE-3-FEDERATION.md b/docs/stacy/PHASE-3-FEDERATION.md
new file mode 100644
index 00000000..90c80079
--- /dev/null
+++ b/docs/stacy/PHASE-3-FEDERATION.md
@@ -0,0 +1,246 @@
+# Phase 3 (v0.3 alpha) — Local file ingest + run chains
+
+**Track:** Federation CLI customer-facing alpha
+(`v0.1` local KOs → `v0.2` connectors + AI runs → **`v0.3` this doc**).
+**Theme:** Close the credential-free loop. Get local files into signed KOs with
+zero external setup, and let AI runs compose into multi-step chains.
+
+> Eng-reviewed 2026-06-02 (Claude + Codex outside voice). The original draft
+> proposed a generic-ingest refactor + an `fs` *connector*; the review showed
+> that was premature for the alpha goal. v0.3 takes the smaller path: a
+> `brain create --file` command (reusing existing KO signing) plus run chains.
+> The connector-framework work (generic ingest, `fs`/Linear connectors) is real
+> but deferred until a second OAuth source justifies it — see `TODOS.md`.
+
+> Not to be confused with `docs/stacy/PHASE-3.md` (heartbeat dispatch in the
+> StacyVM control plane) or `packages/federation/PHASE3_GATE.md` (the shipped
+> two-install consent gate). This is the v0.3 alpha of the federation CLI.
+
+---
+
+## 1. Why this, why now
+
+v0.2 shipped a real loop — GitHub → signed KO → AI run → signed `agent_output`
+KO — but with two limits that block dogfooding:
+
+1. **Every path needs external credentials.** `connect github` needs an OAuth
+   app; the live `anthropic` run needs an API key. A brand-new user cannot
+   exercise the loop end-to-end with zero setup. This is what holds
+   `releases/v2026.602.0.md` in *Draft / awaiting validation*.
+2. **Runs are single-shot.** `stacy run "task" --use <ko>` is one task, one
+   adapter, one output. "Summarize each input, then synthesize one report" is
+   not expressible as a single command.
+
+v0.3 removes both with the **smallest diff that delivers the unlock**:
+
+- **Local files → signed KOs with no credentials** via `brain create --file`.
+  Combined with the existing `--adapter deterministic` run path, a new user runs
+  the *entire* ingest → run loop offline, today.
+- **Run chains** so an `agent_output` KO feeds the next run as input.
+
+### Dependency on v0.2
+
+v0.2 external validation (independent engineer + design-partner metrics, per
+`PHASE-2-HANDOFF.md`) is **not** required to *build* v0.3, but *is* required to
+tag a public v0.3. The `brain create --file` path is what makes the
+zero-credential loop demonstrable, which directly unblocks that validation.
+
+---
+
+## 2. Goals & non-goals
+
+**Goals**
+- `brain create --file <path>` (+ `--glob`/`--ext` for directories): turn local
+  text/markdown/JSON files into signed KOs, **no connector, no credential**.
+- **Run chains**: a multi-step run where later steps consume earlier steps'
+  `agent_output` KOs, expressed as a single command + spec file.
+- Fix the two correctness gaps the review surfaced in the existing run path
+  (content-hash determinism for caching; a reusable run executor).
+
+**Non-goals (explicitly deferred — see `TODOS.md`)**
+- Generic registry-driven `ingest` refactor + `fs` as a real `Connector`
+  (`authType: "none"`, connect/status story). Real work, but only pays off with
+  a second OAuth connector. Deferred.
+- **Linear connector** — no OAuth device-code flow; needs a PAT-vs-OAuth
+  decision. Deferred to v0.3.1.
+- **Rate-limit/retry + resumable ingest** — hardening for real-API load.
+  Deferred.
+- **`brain lineage` graph-walk command** — one-hop provenance already exists in
+  the KO content; a walker/visualizer is a separate feature. Deferred.
+- KO retrieval/selection, output-schema validation, in-output citations, eval
+  harness, cost governance → Phase 4 "Run depth & trust."
+
+---
+
+## 3. Workstreams
+
+### W1 — `brain create --file` (no-credential file ingest)
+
+Add a file → signed KO path to the existing `brain create` verb. Reuses the
+current signing/storage pipeline (`verbs/brain-create.ts`); **no connector
+framework changes**.
+
+- New options on `brain create` (`BrainCreateOptions`):
+  - `--file <path>` — read one file; content becomes the KO body. Content type
+    inferred from extension (`.md`/`.txt` → `text/markdown` or `text/plain`,
+    `.json` → `application/json` and parsed/validated).
+  - `--glob <pattern>` / `--ext md,txt,json` — ingest a directory; create one
+    signed KO per matching file. Reuses the same per-file path in a loop.
+- **Provenance (no path leak — review #10):** store the **relative path from
+  cwd** (or basename) as the source label, never an absolute `file://…` URL.
+  Absolute paths leak usernames and directory layout, and KOs can later be
+  exported/shared. Decision: relative path; add `--source-label` to override.
+- **Traversal safety (review #11):** when walking a directory, by default skip
+  dotfiles, `node_modules`, `.git`, and symlinks; detect and skip binary/non-UTF8
+  files (warn); enforce a max-file-size guard (skip + warn, default e.g. 1 MB,
+  `--max-bytes` override); on a permission error, warn + skip, never abort the
+  whole batch.
+- **Confirmation:** for a directory ingest, print a count + the file list before
+  creating KOs; `--yes` to skip (mirrors the `ingest` UX so it's familiar).
+
+*Exit:* `stacy brain create --file ./notes.md` and `stacy brain create --glob
+'docs/**/*.md'` create verifying signed KOs with `create`/`sign` receipts,
+**no env vars set**, source label is a relative path, oversized/binary files are
+skipped with a warning.
+
+### W3 — Run chains
+
+Compose runs: an `agent_output` KO from one step becomes a `--use` input to the
+next. Mechanically possible today (`run.ts:90` reads any KO); W3 makes it a
+single declared command and fixes two correctness gaps the review found.
+
+- New module `packages/federation/src/runs/chain.ts` + verb path
+  `stacy run --chain <spec.json> [--adapter …] [--ack-egress] [--no-cache]`.
+- **Spec:** JSON, ordered `steps[]`, `@<id>` references to a prior step's output:
+  ```jsonc
+  {
+    "steps": [
+      { "id": "per_doc",   "task": "Summarize each document", "use": ["ko_a", "ko_b"] },
+      { "id": "synthesis", "task": "Synthesize one report",   "use": ["@per_doc"] }
+    ]
+  }
+  ```
+- **Reusable run executor (review #8).** `agentRunCommand` currently returns
+  `void`; the real run logic (adapter resolution, egress gate, KO load+verify,
+  cache, sign) lives inside it. Extract a `runOnce(...) → { koId, … }` executor
+  that both the single-run verb and the chain call. Without this, chains would
+  parse stdout or duplicate the logic — neither acceptable.
+- **Content-hash determinism for caching (review #7 — REAL BUG).** Today
+  `agent-output.ts:59` writes `generatedAt` into the hashed content envelope, so
+  two identical runs produce **different** content hashes. In a chain this means
+  a downstream step's input hash changes every run → the "re-bill only changed
+  steps" claim is false. Fix: **exclude volatile fields (`generatedAt`) from the
+  content used to derive the KO content hash / chain cache key** (keep them as
+  metadata, not hashed body), or key downstream steps on the upstream adapter
+  result hash. Add a test asserting two identical chain runs are fully cached.
+- **Provenance: one-hop.** Each step's `agent_output` lists only its *direct*
+  inputs (synthesis → [per_doc output]; per_doc → [file KOs]). No transitive
+  flattening, no schema change. A lineage walker is deferred (non-goal).
+- **Egress + validation up front.** Spec parse + `@ref` resolution + egress gate
+  all happen before any adapter call (consistent with `run.ts:77`). A bad
+  `@ref` fails before egress.
+- **Failure semantics.** A step failure aborts the chain; already-produced step
+  KOs are durable (no rollback); the chain reports which step failed.
+
+*Exit:* a 2-step chain (per-file summaries → synthesis) produces a final signed
+`agent_output` KO with correct one-hop provenance; **re-running the identical
+chain is fully cached (zero adapter calls)** — the determinism fix is verified
+by test.
+
+### Deferred (tracked in `TODOS.md`)
+
+- **Generic ingest refactor + `fs`/Linear connectors** — the connector-framework
+  path. Revisit when a second OAuth source exists.
+- **W4 robustness** (rate-limit backoff, resumable cursor).
+- **`brain lineage <ko>`** — graph-walk lineage command/visualizer.
+
+---
+
+## 4. Sequencing
+
+W1 and W3 are genuinely independent (W1 touches `verbs/brain-create.ts`; W3
+touches `verbs/run.ts` + `runs/`). They share only `verbs/index.ts` for command
+registration, so the *registration edits* must be coordinated, but the feature
+work parallelizes.
+
+```text
+Lane A: W1  (verbs/brain-create.ts, file walk)        -- independent
+Lane B: W3  (runs/chain.ts, runOnce refactor, #7 fix) -- independent
+Shared: verbs/index.ts + cli/src/index.ts registration -- coordinate merge
+```
+
+Recommended order: **W3's #7/#8 fixes first** (they correct existing behavior
+and de-risk the run path), then W1, then chain syntax on top.
+
+## 5. Exit criteria (v0.3 alpha gate)
+
+- [x] `brain create --file` and `--glob` create verifying signed KOs with
+      **zero external credentials**; source label is a relative path (no
+      absolute-path leak); binary/oversized files skipped with a warning.
+- [x] Full loop runnable credential-free: `brain create --file` → `run --adapter
+      deterministic --use` → `run --chain`.
+- [x] **Content-hash determinism fix (review #7):** two identical runs produce
+      the same hashed content; an identical chain re-run makes **zero adapter
+      calls**. Verified by test (`agent-output.test.ts`, `run.test.ts`).
+- [x] **Reusable `runOnce` executor (review #8)** extracted; single-run verb and
+      chain both use it; single-run behavior unchanged (6 existing tests pass).
+- [x] Run chain of ≥2 steps: correct one-hop provenance, `@ref` resolution,
+      egress fires once, bad `@ref` fails before egress, step-failure aborts with
+      prior KOs durable (`run.test.ts`, `chain.test.ts`).
+- [x] Tests green: file ingest (single/glob/ext/empty/binary/oversized),
+      chain resolver (valid/@ref-missing/step-failure/egress-once/full-cache-hit),
+      determinism + executor regressions. Full suite 318 passed / 11 skipped.
+- [x] Docs: `brain create --file`/`--dir`/`--chain` in `docs/cli-reference.md`,
+      run-chains section in `docs/concepts/ai-runs.md`,
+      `docs/v0.3-files-and-chains-quickstart.md`.
+- [x] CHANGELOG `[Unreleased]` → v0.3 entry.
+- [ ] **Gate (carryover):** do not tag public v0.3 until v0.2 external validation
+      (`PHASE-2-HANDOFF.md`) clears. A draft `releases/` note will be cut at tag
+      time (held with v0.2).
+
+## 6. Decisions (resolved in eng review 2026-06-02)
+
+1. **Approach** → `brain create --file` + run chains. Connector-framework
+   refactor (generic ingest, `fs`/Linear) deferred (Codex outside-voice #12). ✅
+2. **File provenance** → relative path / basename, never absolute `file://`
+   (path-leak, review #10). ✅
+3. **Chain spec** → JSON, ordered `steps[]`, `@<id>` refs; no workflow engine. ✅
+4. **Chain provenance** → one-hop; lineage walker deferred. ✅
+5. **Caching** → fix content-hash determinism by excluding `generatedAt` from the
+   hashed body (review #7). ✅
+6. **Run reuse** → extract `runOnce` returning the KO id (review #8). ✅
+7. **Chain failure** → abort-on-step-failure, prior KOs durable, report step. ✅
+
+## 7. Failure modes (new code paths)
+
+| Path | Realistic failure | Test? | Error handling | Silent? |
+|---|---|---|---|---|
+| `--file` read | file missing / no perm | yes | warn + skip (dir) or clear error (single) | no |
+| `--glob` walk | huge/binary file | yes | size-guard + binary skip, warn | no |
+| chain `@ref` | references unknown step | yes | fail before egress, clear error | no |
+| chain step | step N adapter fails | yes | abort, prior KOs durable, name step | no |
+| chain cache | `generatedAt` non-determinism (#7) | yes | excluded from hash; identical re-run fully cached | **was silent — now fixed** |
+
+No critical gaps (no failure mode left untested + unhandled + silent) once the
+#7 determinism test lands.
+
+---
+
+*Status: Eng-reviewed 2026-06-02 (Claude + Codex). Scope: W1 (`brain create
+--file`) + W3 (run chains, with #7/#8 fixes). Connector refactor, Linear, and
+robustness deferred to `TODOS.md`. Ready to implement.*
+
+## GSTACK REVIEW REPORT
+
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |
+| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | scope reduced; 2 arch + 1 regression resolved |
+| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | (CLI-only, n/a) |
+| Outside Voice | `codex-plan-review` | Independent 2nd opinion | 1 | ISSUES FOUND | 12 findings; #12 reshaped the approach |
+| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — |
+
+- **CODEX:** 12 findings; 4 contradicted the Claude review (caching #7, count-vs-stream #4, parallelism #6, run-service reuse #8). #12 (simpler `brain create --file` over a connector refactor) was accepted and reshaped v0.3.
+- **CROSS-MODEL:** the two reviews diverged on whether to refactor the connector framework now. Codex's narrower path won; plan rewritten.
+- **UNRESOLVED:** 0.
+- **VERDICT:** ENG CLEARED — ready to implement. Public v0.3 tag still gated on v0.2 external validation (`PHASE-2-HANDOFF.md`).
diff --git a/docs/v0.3-files-and-chains-quickstart.md b/docs/v0.3-files-and-chains-quickstart.md
new file mode 100644
index 00000000..f412dc31
--- /dev/null
+++ b/docs/v0.3-files-and-chains-quickstart.md
@@ -0,0 +1,118 @@
+# StacyOS v0.3 Quickstart: Local Files + Run Chains
+
+The v0.3 alpha closes the **credential-free loop**. On top of the
+[v0.2 connectors + AI runs](v0.2-connectors-and-runs-quickstart.md) layer it adds:
+
+- **`brain create --file` / `--dir`** — turn local text/markdown/json files into
+  signed Knowledge Objects with **no connector and no credentials**.
+- **`run --chain`** — compose several runs, where a later step consumes an
+  earlier step's `agent_output` KO.
+
+Together these let you run the whole ingest → run → synthesize loop **offline**,
+with zero external setup, using the built-in `deterministic` adapter.
+
+A Knowledge Object (KO) is Ed25519-signed by your install identity and addressed
+by its content hash, so every object below is independently verifiable.
+
+## 0. Prerequisites
+
+```bash
+pnpm install
+```
+
+Commands run through the `stacy` CLI. In a fresh checkout use
+`pnpm --filter @arpanstacy/stacy exec tsx src/index.ts <args>`; a published
+install exposes `stacy <args>` directly. You need a Postgres connection (set
+`STACY_FEDERATION_DB_URL`/`DATABASE_URL`, pass `--db-url`, or use the embedded
+Postgres from `stacy init`). **No API key or OAuth app is required for this
+quickstart.**
+
+## 1. Create KOs from local files (no credentials)
+
+A single file:
+
+```bash
+stacy brain create --file ./notes.md
+```
+
+The file is wrapped in a `{ kind: "document", source, mediaType, text }`
+envelope and signed. The `source` is a cwd-relative path (a bare filename if the
+file is outside cwd), so absolute paths never leak into a KO you might later
+share or export. `.json` files are parsed into a structured `data` body.
+
+A whole directory, one KO per file:
+
+```bash
+stacy brain create --dir ./docs --ext md,txt
+# or with a glob:
+stacy brain create --dir . --glob 'docs/**/*.md'
+```
+
+Directory mode shows a confirmation summary before writing (`--yes` to skip). It
+skips dotfiles, `node_modules`, `.git`, and symlinks; binary and oversized files
+(default 1 MiB, `--max-bytes` to change) are skipped with a warning instead of
+aborting the batch.
+
+List what you created:
+
+```bash
+stacy brain list
+```
+
+## 2. Run over them — offline
+
+The `deterministic` adapter needs no network and no egress acknowledgement:
+
+```bash
+stacy brain create --file ./docs/pr-231.md --json   # note the KO id
+stacy run "Summarize the release risk" --use <ko_id> --adapter deterministic
+```
+
+This produces a new signed `agent_output` KO whose provenance lists the input.
+
+## 3. Chain runs together
+
+A chain is a JSON file with an ordered `steps[]` array. A later step references
+an earlier step's output with `@<stepId>`:
+
+```jsonc
+// chain.json
+{
+  "steps": [
+    { "id": "per_doc",   "task": "Summarize each document", "use": ["<ko_a>", "<ko_b>"] },
+    { "id": "synthesis", "task": "Synthesize one report",   "use": ["@per_doc"] }
+  ]
+}
+```
+
+```bash
+stacy run --chain ./chain.json --adapter deterministic
+```
+
+```text
+per_doc   use: [ko_a, ko_b] ──► ko_out1
+synthesis use: [@per_doc]   ──► ko_final   (@per_doc resolves to ko_out1)
+```
+
+The spec is validated and every `@ref` resolved before anything runs, so a bad
+reference fails immediately. Re-running an identical chain is fully cached
+(zero adapter calls). A step failure aborts the chain and names the failed step;
+KOs produced by earlier steps remain durable.
+
+## 4. Verify the lineage
+
+```bash
+stacy brain show <ko_final>          # provenance.inputKoIds = [per_doc output]
+stacy receipts list --ko <ko_final>  # create, sign, run
+```
+
+Provenance is **one-hop**: the synthesis KO points at the `per_doc` output,
+which points at the original file KOs. Walking those edges reconstructs the full
+lineage — nothing is flattened or duplicated.
+
+## Going further
+
+- Real model runs (Anthropic) and the GitHub connector: see the
+  [v0.2 quickstart](v0.2-connectors-and-runs-quickstart.md).
+- Full command surface: [CLI reference](cli-reference.md).
+- Concepts: [AI Runs](concepts/ai-runs.md) (including run chains).
diff --git a/packages/db/src/client.ts b/packages/db/src/client.ts
index 2b1949ab..9fe629de 100644
--- a/packages/db/src/client.ts
+++ b/packages/db/src/client.ts
@@ -46,7 +46,12 @@ export type MigrationState =
     };
 
 export function createDb(url: string) {
-  const sql = postgres(url);
+  // Silence server NOTICEs (e.g. "relation ... already exists, skipping" from the
+  // idempotent CREATE TABLE/INDEX IF NOT EXISTS self-bootstrap). The `postgres`
+  // driver otherwise prints them to stdout, which corrupts `--json` output for
+  // any command run against an already-initialized database. Matches the
+  // `createUtilitySql` factory above.
+  const sql = postgres(url, { onnotice: () => {} });
   return drizzlePg(sql, { schema });
 }
 
diff --git a/packages/federation/src/brain/file-document.test.ts b/packages/federation/src/brain/file-document.test.ts
new file mode 100644
index 00000000..22fd8353
--- /dev/null
+++ b/packages/federation/src/brain/file-document.test.ts
@@ -0,0 +1,126 @@
+import { Buffer } from "node:buffer";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_MAX_FILE_BYTES,
+  FileDocumentError,
+  buildFileDocumentContent,
+  inferMediaType,
+  safeSourceLabel,
+} from "./file-document.js";
+
+describe("inferMediaType", () => {
+  it("maps known extensions", () => {
+    expect(inferMediaType("a.md")).toBe("text/markdown");
+    expect(inferMediaType("a.MARKDOWN")).toBe("text/markdown");
+    expect(inferMediaType("a.txt")).toBe("text/plain");
+    expect(inferMediaType("a.json")).toBe("application/json");
+  });
+
+  it("defaults unknown extensions to text/plain", () => {
+    expect(inferMediaType("LICENSE")).toBe("text/plain");
+    expect(inferMediaType("a.rst")).toBe("text/plain");
+  });
+});
+
+describe("safeSourceLabel", () => {
+  it("keeps in-cwd relative paths", () => {
+    expect(safeSourceLabel("docs/notes.md")).toBe("docs/notes.md");
+  });
+
+  it("falls back to basename for escaping or absolute paths (no leak)", () => {
+    expect(safeSourceLabel("../secret/notes.md")).toBe("notes.md");
+    expect(safeSourceLabel("/Users/alice/secret/notes.md")).toBe("notes.md");
+    expect(safeSourceLabel("C:/Users/alice/notes.md")).toBe("notes.md");
+  });
+
+  it("normalizes windows separators", () => {
+    expect(safeSourceLabel("docs\\sub\\notes.md")).toBe("docs/sub/notes.md");
+  });
+});
+
+describe("buildFileDocumentContent", () => {
+  it("wraps markdown as a document envelope with text body", () => {
+    const result = buildFileDocumentContent({
+      path: "docs/notes.md",
+      bytes: Buffer.from("# Title\n\nbody", "utf8"),
+      sourceLabel: "docs/notes.md",
+    });
+    expect(result.contentType).toBe("application/json");
+    expect(result.mediaType).toBe("text/markdown");
+    expect(result.content).toEqual({
+      kind: "document",
+      source: "docs/notes.md",
+      mediaType: "text/markdown",
+      text: "# Title\n\nbody",
+    });
+  });
+
+  it("parses json files into a structured data body", () => {
+    const result = buildFileDocumentContent({
+      path: "data/x.json",
+      bytes: Buffer.from('{"a":1,"b":[2,3]}', "utf8"),
+      sourceLabel: "data/x.json",
+    });
+    expect(result.mediaType).toBe("application/json");
+    expect(result.content).toEqual({
+      kind: "document",
+      source: "data/x.json",
+      mediaType: "application/json",
+      data: { a: 1, b: [2, 3] },
+    });
+  });
+
+  it("rejects a .json file that is not valid JSON", () => {
+    expect(() =>
+      buildFileDocumentContent({
+        path: "data/x.json",
+        bytes: Buffer.from("not json", "utf8"),
+        sourceLabel: "data/x.json",
+      }),
+    ).toThrow(FileDocumentError);
+  });
+
+  it("rejects binary content (NUL byte)", () => {
+    expect(() =>
+      buildFileDocumentContent({
+        path: "blob.txt",
+        bytes: Buffer.from([0x66, 0x00, 0x6f]),
+        sourceLabel: "blob.txt",
+      }),
+    ).toThrow(/binary/);
+  });
+
+  it("rejects invalid UTF-8", () => {
+    expect(() =>
+      buildFileDocumentContent({
+        path: "bad.txt",
+        bytes: Buffer.from([0xff, 0xfe, 0xfd]),
+        sourceLabel: "bad.txt",
+      }),
+    ).toThrow(/UTF-8/);
+  });
+
+  it("enforces the max-bytes guard", () => {
+    expect(() =>
+      buildFileDocumentContent({
+        path: "big.txt",
+        bytes: Buffer.alloc(11, 0x61),
+        sourceLabel: "big.txt",
+        maxBytes: 10,
+      }),
+    ).toThrow(/over the 10-byte limit/);
+  });
+
+  it("uses a 1 MiB default limit", () => {
+    expect(DEFAULT_MAX_FILE_BYTES).toBe(1_048_576);
+    expect(() =>
+      buildFileDocumentContent({
+        path: "ok.txt",
+        bytes: Buffer.alloc(DEFAULT_MAX_FILE_BYTES, 0x61),
+        sourceLabel: "ok.txt",
+      }),
+    ).not.toThrow();
+  });
+});
diff --git a/packages/federation/src/brain/file-document.ts b/packages/federation/src/brain/file-document.ts
new file mode 100644
index 00000000..fbfdc836
--- /dev/null
+++ b/packages/federation/src/brain/file-document.ts
@@ -0,0 +1,160 @@
+import { Buffer } from "node:buffer";
+import { basename, extname } from "node:path";
+
+import type { CanonicalJsonValue } from "../crypto/canonical.js";
+
+/**
+ * Builds a signed-KO content envelope from a local file's bytes. Pure: it does
+ * NOT touch the filesystem — the caller reads the bytes and computes the
+ * source label, this function only validates + wraps. That keeps media-type
+ * inference, binary detection, and JSON parsing unit-testable without disk.
+ *
+ *   file bytes ──► buildFileDocumentContent ──► { content, contentType, ... }
+ *                       │
+ *                       ├─ infer mediaType from extension
+ *                       ├─ reject binary / non-UTF8 (NUL byte or bad decode)
+ *                       ├─ enforce maxBytes guard
+ *                       └─ wrap in { kind:"document", source, mediaType, text|data }
+ *
+ * The envelope is a uniform `kind: "document"` shape so it matches what a future
+ * filesystem *connector* would emit, and so AI runs can consume it the same way
+ * they consume connector-ingested KOs.
+ */
+
+export const FILE_DOCUMENT_KIND = "document";
+export const DEFAULT_MAX_FILE_BYTES = 1_048_576; // 1 MiB
+
+export interface BuildFileDocumentOptions {
+  /** Path as the user supplied it — used for extension inference only. */
+  readonly path: string;
+  /** Raw file bytes. */
+  readonly bytes: Buffer | Uint8Array;
+  /**
+   * Provenance label stored in the KO. MUST already be safe to persist/share —
+   * the caller is responsible for using a relative path or basename, never a
+   * leak-prone absolute path. See `safeSourceLabel`.
+   */
+  readonly sourceLabel: string;
+  /** Skip files larger than this (bytes). Default {@link DEFAULT_MAX_FILE_BYTES}. */
+  readonly maxBytes?: number;
+}
+
+export interface FileDocumentResult {
+  /** KO content envelope. */
+  readonly content: CanonicalJsonValue;
+  /** KO content type — always `application/json` (the envelope is JSON). */
+  readonly contentType: string;
+  /** Inferred original media type (e.g. `text/markdown`). */
+  readonly mediaType: string;
+  /** Provenance source label echoed back. */
+  readonly source: string;
+}
+
+/** Raised when a file cannot become a document KO (binary, too big, bad JSON). */
+export class FileDocumentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FileDocumentError";
+  }
+}
+
+const MEDIA_TYPE_BY_EXT: Record<string, string> = {
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".txt": "text/plain",
+  ".text": "text/plain",
+  ".json": "application/json",
+};
+
+export function inferMediaType(path: string): string {
+  return MEDIA_TYPE_BY_EXT[extname(path).toLowerCase()] ?? "text/plain";
+}
+
+/**
+ * Derives a provenance label that will not leak local machine context. Prefers
+ * a relative path under `cwd`; if the file sits outside `cwd` (relative path
+ * escapes with `..`) or is absolute, falls back to the bare filename.
+ */
+export function safeSourceLabel(relativePath: string): string {
+  const normalized = relativePath.replaceAll("\\", "/");
+  if (
+    normalized.length === 0 ||
+    normalized.startsWith("..") ||
+    normalized.startsWith("/") ||
+    /^[a-zA-Z]:\//.test(normalized) // windows drive-absolute
+  ) {
+    return basename(normalized) || normalized;
+  }
+  return normalized;
+}
+
+function looksBinary(bytes: Buffer): boolean {
+  // A NUL byte is the cheapest, most reliable binary signal for text formats.
+  return bytes.includes(0x00);
+}
+
+function decodeUtf8(bytes: Buffer): string {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  return decoder.decode(bytes);
+}
+
+export function buildFileDocumentContent(
+  options: BuildFileDocumentOptions,
+): FileDocumentResult {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_FILE_BYTES;
+  const buffer = Buffer.isBuffer(options.bytes)
+    ? options.bytes
+    : Buffer.from(options.bytes);
+
+  if (buffer.byteLength > maxBytes) {
+    throw new FileDocumentError(
+      `File ${options.sourceLabel} is ${buffer.byteLength} bytes, over the ${maxBytes}-byte limit. Pass --max-bytes to raise it.`,
+    );
+  }
+
+  if (looksBinary(buffer)) {
+    throw new FileDocumentError(
+      `File ${options.sourceLabel} looks binary (contains NUL bytes); only UTF-8 text/markdown/json files can become Knowledge Objects.`,
+    );
+  }
+
+  let text: string;
+  try {
+    text = decodeUtf8(buffer);
+  } catch {
+    throw new FileDocumentError(
+      `File ${options.sourceLabel} is not valid UTF-8 text.`,
+    );
+  }
+
+  const mediaType = inferMediaType(options.path);
+
+  let body: { readonly text: string } | { readonly data: CanonicalJsonValue };
+  if (mediaType === "application/json") {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw new FileDocumentError(
+        `File ${options.sourceLabel} has a .json extension but is not valid JSON: ${(error as Error).message}`,
+      );
+    }
+    body = { data: parsed as CanonicalJsonValue };
+  } else {
+    body = { text };
+  }
+
+  const content: CanonicalJsonValue = {
+    kind: FILE_DOCUMENT_KIND,
+    source: options.sourceLabel,
+    mediaType,
+    ...body,
+  };
+
+  return {
+    content,
+    contentType: "application/json",
+    mediaType,
+    source: options.sourceLabel,
+  };
+}
diff --git a/packages/federation/src/brain/file-walk.test.ts b/packages/federation/src/brain/file-walk.test.ts
new file mode 100644
index 00000000..b460e63b
--- /dev/null
+++ b/packages/federation/src/brain/file-walk.test.ts
@@ -0,0 +1,88 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { collectFiles, excludeReason, normalizeExtAllowlist } from "./file-walk.js";
+
+describe("excludeReason", () => {
+  it("skips hidden segments and excluded dirs", () => {
+    expect(excludeReason(".env")).toMatch(/hidden/);
+    expect(excludeReason("docs/.secret/x.md")).toMatch(/hidden/);
+    expect(excludeReason("node_modules/a/b.js")).toMatch(/excluded directory/);
+    expect(excludeReason(".git/config")).toMatch(/hidden|excluded/);
+  });
+
+  it("keeps normal paths", () => {
+    expect(excludeReason("docs/a.md")).toBeUndefined();
+  });
+
+  it("applies the ext allowlist", () => {
+    const allow = normalizeExtAllowlist(["md", ".txt"]);
+    expect(excludeReason("a.md", allow)).toBeUndefined();
+    expect(excludeReason("a.txt", allow)).toBeUndefined();
+    expect(excludeReason("a.json", allow)).toMatch(/not in --ext/);
+  });
+});
+
+describe("collectFiles", () => {
+  const roots: string[] = [];
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
+  });
+
+  async function fixture(): Promise<string> {
+    const root = await mkdtemp(join(tmpdir(), "stacy-file-walk-"));
+    roots.push(root);
+    await writeFile(join(root, "a.md"), "# a", "utf8");
+    await writeFile(join(root, "b.txt"), "b", "utf8");
+    await writeFile(join(root, "c.json"), "{}", "utf8");
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "sub", "d.md"), "# d", "utf8");
+    await mkdir(join(root, "node_modules", "pkg"), { recursive: true });
+    await writeFile(join(root, "node_modules", "pkg", "index.js"), "x", "utf8");
+    await writeFile(join(root, ".hidden.md"), "secret", "utf8");
+    return root;
+  }
+
+  it("recursively collects files, excluding node_modules and dotfiles", async () => {
+    const root = await fixture();
+    const { files, skipped } = collectFiles({ root });
+    // root is under tmpdir (outside cwd) so labels collapse to leak-safe
+    // basenames — assert on basenames, not the original subdir path.
+    const names = files.map((f) => f.label.split("/").pop()).sort();
+    expect(names).toContain("a.md");
+    expect(names).toContain("d.md"); // from sub/, recursively walked
+    expect(files.every((f) => !f.label.includes("node_modules"))).toBe(true);
+    expect(files.every((f) => !f.label.includes(".hidden"))).toBe(true);
+    expect(skipped.some((s) => s.reason.includes("excluded directory"))).toBe(true);
+  });
+
+  it("honors a glob pattern", async () => {
+    const root = await fixture();
+    const { files } = collectFiles({ root, glob: "**/*.md" });
+    expect(files.every((f) => f.label.endsWith(".md"))).toBe(true);
+    expect(files.length).toBe(2); // a.md + sub/d.md
+  });
+
+  it("honors the ext allowlist", async () => {
+    const root = await fixture();
+    const { files } = collectFiles({ root, ext: ["json"] });
+    expect(files.map((f) => f.label.split("/").pop())).toEqual(["c.json"]);
+  });
+
+  it("skips symlinks", async () => {
+    const root = await fixture();
+    await symlink(join(root, "a.md"), join(root, "link.md"));
+    const { files, skipped } = collectFiles({ root, glob: "*.md" });
+    expect(files.some((f) => f.label.endsWith("link.md"))).toBe(false);
+    expect(skipped.some((s) => s.reason === "symlink")).toBe(true);
+  });
+
+  it("returns empty for a directory with no matches", async () => {
+    const root = await fixture();
+    const { files } = collectFiles({ root, ext: ["rst"] });
+    expect(files).toEqual([]);
+  });
+});
diff --git a/packages/federation/src/brain/file-walk.ts b/packages/federation/src/brain/file-walk.ts
new file mode 100644
index 00000000..55c22cdf
--- /dev/null
+++ b/packages/federation/src/brain/file-walk.ts
@@ -0,0 +1,115 @@
+import { globSync, lstatSync } from "node:fs";
+import { extname, relative, resolve } from "node:path";
+
+import { safeSourceLabel } from "./file-document.js";
+
+/**
+ * Enumerates local files to ingest as Knowledge Objects. Uses Node's native
+ * `fs.globSync` (no dependency) so patterns like `docs/**​/*.md` work.
+ *
+ *   root + glob/ext ──► globSync ──► per-path filter ──► CollectedFile[]
+ *                                        │
+ *                                        ├─ skip dotfiles / dotdirs
+ *                                        ├─ skip node_modules, .git
+ *                                        ├─ skip symlinks (lstat)
+ *                                        ├─ skip non-files (dirs)
+ *                                        └─ ext allowlist (if given)
+ *
+ * Binary detection and the size guard happen later, per-file, in
+ * `buildFileDocumentContent` — a file that passes here can still be skipped at
+ * read time. Labels are leak-safe (cwd-relative or basename).
+ */
+
+const DEFAULT_EXCLUDED_DIRS = new Set(["node_modules", ".git"]);
+
+export interface CollectedFile {
+  readonly absolutePath: string;
+  /** Leak-safe provenance label (cwd-relative path or basename). */
+  readonly label: string;
+}
+
+export interface SkippedFile {
+  readonly path: string;
+  readonly reason: string;
+}
+
+export interface CollectFilesOptions {
+  /** Base directory (cwd-relative or absolute). Defaults to cwd. */
+  readonly root?: string;
+  /** Glob pattern relative to `root`. Defaults to `**​/*`. */
+  readonly glob?: string;
+  /** Extension allowlist, with or without leading dots (e.g. `md`, `.txt`). */
+  readonly ext?: readonly string[];
+}
+
+export interface CollectFilesResult {
+  readonly files: readonly CollectedFile[];
+  readonly skipped: readonly SkippedFile[];
+}
+
+/**
+ * Pure path-rule check. Returns a skip reason, or `undefined` to keep the path.
+ * Separated from the filesystem walk so the rules are unit-testable.
+ */
+export function excludeReason(
+  relPath: string,
+  extAllow?: ReadonlySet<string>,
+): string | undefined {
+  const segments = relPath.replaceAll("\\", "/").split("/").filter(Boolean);
+  for (const segment of segments) {
+    if (segment.startsWith(".")) return `hidden path segment "${segment}"`;
+    if (DEFAULT_EXCLUDED_DIRS.has(segment)) return `excluded directory "${segment}"`;
+  }
+  if (extAllow && extAllow.size > 0) {
+    const ext = extname(relPath).toLowerCase().replace(/^\./, "");
+    if (!extAllow.has(ext)) return `extension ".${ext}" not in --ext allowlist`;
+  }
+  return undefined;
+}
+
+export function normalizeExtAllowlist(
+  ext: readonly string[] | undefined,
+): ReadonlySet<string> | undefined {
+  if (!ext || ext.length === 0) return undefined;
+  return new Set(ext.map((entry) => entry.trim().toLowerCase().replace(/^\./, "")).filter(Boolean));
+}
+
+export function collectFiles(options: CollectFilesOptions): CollectFilesResult {
+  const root = resolve(process.cwd(), options.root?.trim() || ".");
+  const pattern = options.glob?.trim() || "**/*";
+  const extAllow = normalizeExtAllowlist(options.ext);
+
+  const files: CollectedFile[] = [];
+  const skipped: SkippedFile[] = [];
+
+  const matches = globSync(pattern, { cwd: root }).sort();
+  for (const relPath of matches) {
+    const absolutePath = resolve(root, relPath);
+
+    const reason = excludeReason(relPath, extAllow);
+    if (reason) {
+      skipped.push({ path: relPath, reason });
+      continue;
+    }
+
+    let stats;
+    try {
+      stats = lstatSync(absolutePath);
+    } catch {
+      skipped.push({ path: relPath, reason: "could not stat (permission?)" });
+      continue;
+    }
+    if (stats.isSymbolicLink()) {
+      skipped.push({ path: relPath, reason: "symlink" });
+      continue;
+    }
+    if (!stats.isFile()) continue; // directories and other non-files
+
+    files.push({
+      absolutePath,
+      label: safeSourceLabel(relative(process.cwd(), absolutePath)),
+    });
+  }
+
+  return { files, skipped };
+}
diff --git a/packages/federation/src/runs/agent-output.test.ts b/packages/federation/src/runs/agent-output.test.ts
index df20fc0a..655b46ef 100644
--- a/packages/federation/src/runs/agent-output.test.ts
+++ b/packages/federation/src/runs/agent-output.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import { canonicalize } from "../crypto/canonical.js";
 import {
   AGENT_OUTPUT_KIND,
   assertValidAdapterOutput,
@@ -12,7 +13,6 @@ describe("buildAgentOutputContent", () => {
       task: "Summarize",
       model: "claude-sonnet-4-5",
       adapter: "deterministic",
-      generatedAt: new Date("2026-05-22T00:00:00.000Z"),
       inputs: [
         { koId: "ko_a", contentHash: "sha256:aa", contentType: "application/json" },
         { koId: "ko_b", contentHash: "sha256:bb", contentType: "application/json" },
@@ -23,7 +23,6 @@ describe("buildAgentOutputContent", () => {
 
     expect(content.kind).toBe(AGENT_OUTPUT_KIND);
     expect(content.provenance.inputKoIds).toEqual(["ko_a", "ko_b"]);
-    expect(content.generatedAt).toBe("2026-05-22T00:00:00.000Z");
     expect(content.notes).toEqual(["note"]);
   });
 
@@ -32,13 +31,31 @@ describe("buildAgentOutputContent", () => {
       task: "Summarize",
       model: "m",
       adapter: "deterministic",
-      generatedAt: new Date("2026-05-22T00:00:00.000Z"),
       inputs: [],
       output: { kind: "report" },
     });
     expect(content.notes).toBeUndefined();
   });
 
+  it("is timestamp-free and deterministic for identical inputs (chain caching #7)", () => {
+    const build = () =>
+      buildAgentOutputContent({
+        task: "Summarize",
+        model: "m",
+        adapter: "deterministic",
+        inputs: [{ koId: "ko_a", contentHash: "sha256:aa", contentType: "application/json" }],
+        output: { kind: "report", title: "Done" },
+      });
+
+    const first = build();
+    const second = build();
+    // No wall-clock field leaks into the hashed content.
+    expect("generatedAt" in first).toBe(false);
+    // Two identical builds produce byte-identical canonical content, so the KO
+    // content hash is stable across runs and chain steps re-cache correctly.
+    expect(canonicalize(first)).toBe(canonicalize(second));
+  });
+
   it("rejects non-object adapter output", () => {
     expect(() => assertValidAdapterOutput("string")).toThrow("must be a JSON object");
     expect(() => assertValidAdapterOutput(undefined)).toThrow("no output");
diff --git a/packages/federation/src/runs/agent-output.ts b/packages/federation/src/runs/agent-output.ts
index bd2ff2a5..95ef8281 100644
--- a/packages/federation/src/runs/agent-output.ts
+++ b/packages/federation/src/runs/agent-output.ts
@@ -15,7 +15,6 @@ export interface AgentOutputContent {
   readonly task: string;
   readonly model: string;
   readonly adapter: string;
-  readonly generatedAt: string;
   readonly provenance: {
     readonly inputKoIds: readonly string[];
     readonly inputs: readonly AgentRunInputReference[];
@@ -28,7 +27,6 @@ export interface BuildAgentOutputContentOptions {
   readonly task: string;
   readonly model: string;
   readonly adapter: string;
-  readonly generatedAt: Date;
   readonly inputs: readonly AgentRunInputReference[];
   readonly output: CanonicalJsonValue;
   readonly notes?: readonly string[];
@@ -38,6 +36,15 @@ export interface BuildAgentOutputContentOptions {
  * Validates an adapter's raw output and wraps it in the canonical
  * `agent_output` Knowledge Object content envelope. Provenance records every
  * input Knowledge Object id so the run is verifiably reproducible.
+ *
+ * The envelope is intentionally FREE of wall-clock timestamps: a Knowledge
+ * Object is content-addressed, so identical (task, model, adapter, inputs,
+ * output) must hash identically. The generation time lives on the KO record
+ * (`createdAt`/`storedAt`) and the `run` receipt instead. This determinism is
+ * what lets run *chains* reuse a cached step output without the downstream
+ * step's input hash drifting every run. (Matches the existing
+ * `dashboard-content` / `prompt-output` convention of keeping hashed content
+ * timestamp-free.)
  */
 export function buildAgentOutputContent(
   options: BuildAgentOutputContentOptions,
@@ -56,7 +63,6 @@ export function buildAgentOutputContent(
     task: options.task,
     model: options.model,
     adapter: options.adapter,
-    generatedAt: options.generatedAt.toISOString(),
     provenance: {
       inputKoIds: inputs.map((input) => input.koId),
       inputs,
diff --git a/packages/federation/src/runs/anthropic-adapter.live.test.ts b/packages/federation/src/runs/anthropic-adapter.live.test.ts
index da2f732e..73c5aeb2 100644
--- a/packages/federation/src/runs/anthropic-adapter.live.test.ts
+++ b/packages/federation/src/runs/anthropic-adapter.live.test.ts
@@ -41,7 +41,6 @@ describe.skipIf(!adapterCommand)("anthropic adapter (live)", () => {
       task: "Summarize the linked pull request in two sentences.",
       model: DEFAULT_ANTHROPIC_MODEL,
       adapter: adapter.id,
-      generatedAt: new Date("2026-06-01T00:00:00.000Z"),
       inputs: [
         { koId: "ko_live_input", contentHash: "sha256:live", contentType: "application/json" },
       ],
diff --git a/packages/federation/src/runs/chain.test.ts b/packages/federation/src/runs/chain.test.ts
new file mode 100644
index 00000000..7d6de4fe
--- /dev/null
+++ b/packages/federation/src/runs/chain.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  ChainSpecError,
+  parseChainSpec,
+  resolveStepInputs,
+  validateChainSpec,
+} from "./chain.js";
+
+describe("parseChainSpec / validateChainSpec", () => {
+  it("accepts a valid two-step chain with a forward-resolved @ref", () => {
+    const spec = parseChainSpec(
+      JSON.stringify({
+        steps: [
+          { id: "per_doc", task: "Summarize each", use: ["ko_a", "ko_b"] },
+          { id: "synthesis", task: "Synthesize", use: ["@per_doc"], model: "claude-sonnet-4-5" },
+        ],
+      }),
+    );
+    expect(spec.steps).toHaveLength(2);
+    expect(spec.steps[1]?.use).toEqual(["@per_doc"]);
+    expect(spec.steps[1]?.model).toBe("claude-sonnet-4-5");
+  });
+
+  it("rejects invalid JSON", () => {
+    expect(() => parseChainSpec("{not json")).toThrow(ChainSpecError);
+  });
+
+  it("requires a non-empty steps array", () => {
+    expect(() => validateChainSpec({})).toThrow(/non-empty array/);
+    expect(() => validateChainSpec({ steps: [] })).toThrow(/non-empty array/);
+  });
+
+  it("requires id, task, and non-empty use on each step", () => {
+    expect(() => validateChainSpec({ steps: [{ task: "t", use: ["k"] }] })).toThrow(/id is required/);
+    expect(() => validateChainSpec({ steps: [{ id: "a", use: ["k"] }] })).toThrow(/task is required/);
+    expect(() => validateChainSpec({ steps: [{ id: "a", task: "t", use: [] }] })).toThrow(/non-empty array/);
+  });
+
+  it("rejects duplicate step ids", () => {
+    expect(() =>
+      validateChainSpec({
+        steps: [
+          { id: "a", task: "t", use: ["k"] },
+          { id: "a", task: "t2", use: ["k"] },
+        ],
+      }),
+    ).toThrow(/duplicated/);
+  });
+
+  it("rejects an @ref to an unknown or forward step (before any run)", () => {
+    expect(() =>
+      validateChainSpec({
+        steps: [{ id: "a", task: "t", use: ["@missing"] }],
+      }),
+    ).toThrow(/not a prior step/);
+
+    expect(() =>
+      validateChainSpec({
+        steps: [
+          { id: "a", task: "t", use: ["@b"] }, // forward ref
+          { id: "b", task: "t2", use: ["k"] },
+        ],
+      }),
+    ).toThrow(/not a prior step/);
+  });
+
+  it("rejects a self-reference", () => {
+    expect(() =>
+      validateChainSpec({ steps: [{ id: "a", task: "t", use: ["@a"] }] }),
+    ).toThrow(/its own step/);
+  });
+});
+
+describe("resolveStepInputs", () => {
+  it("substitutes @refs with prior step output KO ids and passes literals through", () => {
+    const step = { id: "synthesis", task: "t", use: ["ko_literal", "@per_doc"] };
+    const outputs = new Map([["per_doc", "ko_out_1"]]);
+    expect(resolveStepInputs(step, outputs)).toEqual(["ko_literal", "ko_out_1"]);
+  });
+
+  it("throws when a referenced step has no output", () => {
+    const step = { id: "synthesis", task: "t", use: ["@per_doc"] };
+    expect(() => resolveStepInputs(step, new Map())).toThrow(ChainSpecError);
+  });
+});
diff --git a/packages/federation/src/runs/chain.ts b/packages/federation/src/runs/chain.ts
new file mode 100644
index 00000000..198d2b56
--- /dev/null
+++ b/packages/federation/src/runs/chain.ts
@@ -0,0 +1,146 @@
+/**
+ * Run-chain spec: an ordered list of run steps where a later step can consume
+ * an earlier step's `agent_output` KO as input via an `@<stepId>` reference.
+ *
+ *   { "steps": [
+ *       { "id": "per_doc",   "task": "Summarize each doc", "use": ["ko_a","ko_b"] },
+ *       { "id": "synthesis", "task": "Synthesize",         "use": ["@per_doc"]  }
+ *   ]}
+ *
+ *   per_doc ──run──► ko_out1 ─┐
+ *                              ├─ @per_doc resolves to ko_out1
+ *   synthesis(use:[@per_doc]) ─┘──run──► ko_final
+ *
+ * This module is PURE — JSON parsing + structural validation + `@ref`
+ * resolution only. No filesystem, no database, no adapter. Validation rejects
+ * forward/unknown references up front so a malformed chain fails BEFORE the
+ * egress gate or any KO read. Orchestration (calling `runOnce` per step) lives
+ * in the verb layer.
+ */
+
+export const STEP_REF_PREFIX = "@";
+
+export interface ChainStepSpec {
+  readonly id: string;
+  readonly task: string;
+  /** Input refs: a literal KO id, or `@<priorStepId>` for a prior step output. */
+  readonly use: readonly string[];
+  /** Optional per-step model override. */
+  readonly model?: string;
+}
+
+export interface ChainSpec {
+  readonly steps: readonly ChainStepSpec[];
+}
+
+export class ChainSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ChainSpecError";
+  }
+}
+
+export function isStepRef(use: string): boolean {
+  return use.startsWith(STEP_REF_PREFIX);
+}
+
+export function stepRefId(use: string): string {
+  return use.slice(STEP_REF_PREFIX.length);
+}
+
+/**
+ * Parses and fully validates a chain spec from raw JSON. Throws
+ * {@link ChainSpecError} on any structural problem or dangling `@ref`.
+ */
+export function parseChainSpec(raw: string): ChainSpec {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ChainSpecError(`Chain spec is not valid JSON: ${(error as Error).message}`);
+  }
+  return validateChainSpec(parsed);
+}
+
+export function validateChainSpec(value: unknown): ChainSpec {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ChainSpecError('Chain spec must be a JSON object with a "steps" array.');
+  }
+  const steps = (value as Record<string, unknown>).steps;
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw new ChainSpecError('Chain spec "steps" must be a non-empty array.');
+  }
+
+  const seenIds = new Set<string>();
+  const validated: ChainStepSpec[] = [];
+
+  steps.forEach((rawStep, index) => {
+    const where = `steps[${index}]`;
+    if (typeof rawStep !== "object" || rawStep === null || Array.isArray(rawStep)) {
+      throw new ChainSpecError(`${where} must be an object.`);
+    }
+    const step = rawStep as Record<string, unknown>;
+
+    const id = typeof step.id === "string" ? step.id.trim() : "";
+    if (!id) throw new ChainSpecError(`${where}.id is required and must be a non-empty string.`);
+    if (seenIds.has(id)) throw new ChainSpecError(`${where}.id "${id}" is duplicated; step ids must be unique.`);
+
+    const task = typeof step.task === "string" ? step.task.trim() : "";
+    if (!task) throw new ChainSpecError(`${where}.task is required and must be a non-empty string.`);
+
+    if (!Array.isArray(step.use) || step.use.length === 0) {
+      throw new ChainSpecError(`${where}.use must be a non-empty array of KO ids or @stepId references.`);
+    }
+    const use: string[] = [];
+    step.use.forEach((rawRef, refIndex) => {
+      if (typeof rawRef !== "string" || rawRef.trim().length === 0) {
+        throw new ChainSpecError(`${where}.use[${refIndex}] must be a non-empty string.`);
+      }
+      const ref = rawRef.trim();
+      if (isStepRef(ref)) {
+        const refId = stepRefId(ref);
+        if (!refId) throw new ChainSpecError(`${where}.use[${refIndex}] "${ref}" is an empty step reference.`);
+        if (refId === id) throw new ChainSpecError(`${where}.use[${refIndex}] "${ref}" refers to its own step.`);
+        if (!seenIds.has(refId)) {
+          throw new ChainSpecError(
+            `${where}.use[${refIndex}] references "@${refId}", which is not a prior step. Steps run in order; a step can only use outputs declared before it.`,
+          );
+        }
+      }
+      use.push(ref);
+    });
+
+    let model: string | undefined;
+    if (step.model !== undefined) {
+      if (typeof step.model !== "string" || step.model.trim().length === 0) {
+        throw new ChainSpecError(`${where}.model, when present, must be a non-empty string.`);
+      }
+      model = step.model.trim();
+    }
+
+    seenIds.add(id);
+    validated.push({ id, task, use, ...(model ? { model } : {}) });
+  });
+
+  return { steps: validated };
+}
+
+/**
+ * Resolves a step's `use[]` into concrete KO ids, substituting `@<stepId>`
+ * references with the output KO id produced by that prior step. Assumes the
+ * spec already passed {@link validateChainSpec}, so every ref is known.
+ */
+export function resolveStepInputs(
+  step: ChainStepSpec,
+  outputs: ReadonlyMap<string, string>,
+): readonly string[] {
+  return step.use.map((ref) => {
+    if (!isStepRef(ref)) return ref;
+    const refId = stepRefId(ref);
+    const koId = outputs.get(refId);
+    if (!koId) {
+      throw new ChainSpecError(`Step "${step.id}" references "@${refId}" but that step produced no output.`);
+    }
+    return koId;
+  });
+}
diff --git a/packages/federation/verbs/brain-create.test.ts b/packages/federation/verbs/brain-create.test.ts
index c28f2896..1c6f01c5 100644
--- a/packages/federation/verbs/brain-create.test.ts
+++ b/packages/federation/verbs/brain-create.test.ts
@@ -49,6 +49,142 @@ describe("brainCreateCommand", () => {
     });
   });
 
+  it("creates a document KO from a local markdown file with a leak-safe source label", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-brain-create-file-"));
+    tempRoots.push(root);
+    const configPath = await writeConfig(root, 55446);
+    const docPath = join(root, "notes.md");
+    await writeFile(docPath, "# Release notes\n\nShip it.", "utf8");
+
+    const lines: string[] = [];
+    let storedContent: unknown;
+
+    await brainCreateCommand(
+      {
+        config: configPath,
+        dbUrl: "postgres://example",
+        file: docPath,
+        sourceLabel: "notes.md",
+        koId: "ko_file_doc",
+        json: true,
+      },
+      {
+        createDb: () => ({
+          execute: async (query: unknown) => {
+            const text = JSON.stringify(query);
+            if (text.includes("# Release notes")) storedContent = query;
+            return [];
+          },
+        }),
+        stdout: { log: (line) => lines.push(line) },
+        now: () => new Date("2026-06-02T00:00:00.000Z"),
+      },
+    );
+
+    expect(JSON.parse(lines[0] ?? "{}")).toMatchObject({
+      id: "ko_file_doc",
+      contentType: "application/json",
+      contentHash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+    });
+    // The stored content is a document envelope with a relative (non-absolute)
+    // source label — no leaked absolute path.
+    const serialized = JSON.stringify(storedContent ?? "");
+    expect(serialized).toContain("document"); // document envelope kind
+    expect(serialized).toContain("notes.md"); // relative source label
+    expect(serialized).not.toContain(root); // absolute path must not leak
+  });
+
+  it("creates one KO per file for directory ingest, excluding hidden/node_modules", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-brain-create-dir-"));
+    tempRoots.push(root);
+    const configPath = await writeConfig(root, 55447);
+    const docs = join(root, "docs");
+    await mkdir(join(docs, "node_modules"), { recursive: true });
+    await writeFile(join(docs, "a.md"), "# a", "utf8");
+    await writeFile(join(docs, "b.md"), "# b", "utf8");
+    await writeFile(join(docs, "c.txt"), "c", "utf8");
+    await writeFile(join(docs, ".secret.md"), "leak", "utf8");
+    await writeFile(join(docs, "node_modules", "d.md"), "# d", "utf8");
+
+    const lines: string[] = [];
+    const summaries: string[] = [];
+
+    await brainCreateCommand(
+      {
+        config: configPath,
+        dbUrl: "postgres://example",
+        dir: docs,
+        ext: "md",
+        json: true,
+      },
+      {
+        createDb: () => ({ execute: async () => [] }),
+        stdout: { log: (line) => lines.push(line) },
+        confirm: async (summary) => {
+          summaries.push(summary);
+          return true;
+        },
+        now: () => new Date("2026-06-02T00:00:00.000Z"),
+      },
+    );
+
+    const out = JSON.parse(lines[0] ?? "{}");
+    // a.md + b.md only (.secret.md hidden, node_modules excluded, c.txt wrong ext)
+    expect(out.created).toHaveLength(2);
+    const sources = out.created.map((c: { source: string }) => c.source).sort();
+    expect(sources.every((s: string) => s.endsWith(".md"))).toBe(true);
+    expect(JSON.stringify(out)).not.toContain(".secret");
+    expect(JSON.stringify(out)).not.toContain("node_modules");
+  });
+
+  it("skips unreadable (binary) files in a directory batch without aborting", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-brain-create-dir-skip-"));
+    tempRoots.push(root);
+    const configPath = await writeConfig(root, 55448);
+    const docs = join(root, "docs");
+    await mkdir(docs, { recursive: true });
+    await writeFile(join(docs, "good.md"), "# good", "utf8");
+    await writeFile(join(docs, "bin.md"), Buffer.from([0x68, 0x00, 0x69])); // NUL = binary
+
+    const lines: string[] = [];
+    await brainCreateCommand(
+      {
+        config: configPath,
+        dbUrl: "postgres://example",
+        dir: docs,
+        yes: true,
+        json: true,
+      },
+      {
+        createDb: () => ({ execute: async () => [] }),
+        stdout: { log: (line) => lines.push(line) },
+        now: () => new Date("2026-06-02T00:00:00.000Z"),
+      },
+    );
+
+    const out = JSON.parse(lines[0] ?? "{}");
+    expect(out.created).toHaveLength(1);
+    expect(out.created[0].source).toContain("good.md");
+    expect(out.failed).toHaveLength(1);
+    expect(out.failed[0].reason).toMatch(/binary/);
+  });
+
+  it("rejects passing more than one content source", async () => {
+    await expect(
+      brainCreateCommand(
+        {
+          dbUrl: "postgres://example",
+          contentJson: "{}",
+          file: "/tmp/x.md",
+        },
+        {
+          createDb: () => ({ execute: async () => [] }),
+          stdout: { log: () => undefined },
+        },
+      ),
+    ).rejects.toThrow(/exactly one of/);
+  });
+
   it("rejects invalid JSON content before opening the database", async () => {
     const openedConnections: string[] = [];
 
diff --git a/packages/federation/verbs/brain-create.ts b/packages/federation/verbs/brain-create.ts
index 608ffa08..70e8ed1b 100644
--- a/packages/federation/verbs/brain-create.ts
+++ b/packages/federation/verbs/brain-create.ts
@@ -1,3 +1,7 @@
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+
 import { createDb } from "@arpanstacy/stacy-db";
 
 import { type CanonicalJsonValue } from "../src/crypto/canonical.js";
@@ -6,8 +10,16 @@ import {
   type CreateLocalKnowledgeObjectResult,
 } from "../src/brain/local-brain.js";
 import { type BrainDb } from "../src/brain/brain-store.js";
+import {
+  FileDocumentError,
+  buildFileDocumentContent,
+  safeSourceLabel,
+  type FileDocumentResult,
+} from "../src/brain/file-document.js";
+import { collectFiles, type CollectedFile } from "../src/brain/file-walk.js";
 import {
   resolveLocalRuntime,
+  type LocalRuntime,
   type LocalRuntimeDependencies,
   type LocalRuntimeOptions,
 } from "./local-runtime.js";
@@ -16,6 +28,13 @@ import { generatePromptKnowledgeContent } from "./prompt-output.js";
 export interface BrainCreateOptions extends LocalRuntimeOptions {
   readonly contentJson?: string;
   readonly prompt?: string;
+  readonly file?: string;
+  readonly dir?: string;
+  readonly glob?: string;
+  readonly ext?: string;
+  readonly yes?: boolean;
+  readonly sourceLabel?: string;
+  readonly maxBytes?: number;
   readonly adapterCommand?: string;
   readonly adapterArg?: string[];
   readonly contentType?: string;
@@ -23,10 +42,18 @@ export interface BrainCreateOptions extends LocalRuntimeOptions {
   readonly json?: boolean;
 }
 
+/** Resolved content plus the content type to sign it under. */
+interface ResolvedContent {
+  readonly content: CanonicalJsonValue;
+  readonly contentType: string;
+}
+
 export interface BrainCreateDependencies extends LocalRuntimeDependencies {
   readonly createDb?: (connectionString: string) => BrainDb;
   readonly stdout?: Pick<typeof console, "log">;
   readonly now?: () => Date;
+  /** Confirmation hook for directory ingest; defaults to a TTY prompt. */
+  readonly confirm?: (summary: string) => Promise<boolean>;
 }
 
 export async function brainCreateCommand(
@@ -35,7 +62,13 @@ export async function brainCreateCommand(
 ): Promise<void> {
   const stdout = dependencies.stdout ?? console;
   const runtime = resolveLocalRuntime(options, dependencies);
-  const content = await resolveContent(options);
+
+  if (isDirectoryMode(options)) {
+    await brainCreateFromDirectory(options, dependencies, runtime, stdout);
+    return;
+  }
+
+  const resolved = await resolveContent(options);
   const ownsDb = dependencies.createDb === undefined;
   const db = dependencies.createDb?.(runtime.connectionString) ?? createDb(runtime.connectionString);
   const createdAt = dependencies.now?.() ?? new Date();
@@ -43,8 +76,8 @@ export async function brainCreateCommand(
     const result = await createLocalKnowledgeObject({
       db,
       identityPath: runtime.identityPath,
-      contentType: options.contentType?.trim() || "application/json",
-      content,
+      contentType: resolved.contentType,
+      content: resolved.content,
       createdAt,
       storedAt: createdAt,
       idGenerator: options.koId ? () => options.koId! : undefined,
@@ -63,16 +96,26 @@ export async function brainCreateCommand(
   }
 }
 
-async function resolveContent(options: BrainCreateOptions): Promise<CanonicalJsonValue> {
+async function resolveContent(options: BrainCreateOptions): Promise<ResolvedContent> {
   const hasContentJson = typeof options.contentJson === "string" && options.contentJson.trim().length > 0;
   const hasPrompt = typeof options.prompt === "string" && options.prompt.trim().length > 0;
+  const hasFile = typeof options.file === "string" && options.file.trim().length > 0;
+
+  const sources = [hasContentJson, hasPrompt, hasFile].filter(Boolean).length;
+  if (sources > 1) {
+    throw new Error("Pass exactly one of --content-json, --prompt, or --file.");
+  }
 
-  if (hasContentJson && hasPrompt) {
-    throw new Error("Pass either --content-json or --prompt, not both.");
+  if (hasFile) {
+    const fileResult = await readFileDocument(options);
+    return { content: fileResult.content, contentType: fileResult.contentType };
   }
 
   if (hasContentJson) {
-    return parseContentJson(options.contentJson!);
+    return {
+      content: parseContentJson(options.contentJson!),
+      contentType: options.contentType?.trim() || "application/json",
+    };
   }
 
   if (hasPrompt) {
@@ -81,10 +124,164 @@ async function resolveContent(options: BrainCreateOptions): Promise<CanonicalJso
       adapterCommand: options.adapterCommand,
       adapterArgs: options.adapterArg,
     });
-    return generated.content;
+    return {
+      content: generated.content,
+      contentType: options.contentType?.trim() || "application/json",
+    };
+  }
+
+  throw new Error("Pass --content-json, --prompt, or --file to create a Knowledge Object.");
+}
+
+/**
+ * Reads a single local file and wraps it in a signed-KO document envelope.
+ * The source label stored in the KO is a cwd-relative path (or basename if the
+ * file sits outside cwd) so absolute paths never leak into shareable KOs.
+ */
+async function readFileDocument(
+  options: BrainCreateOptions,
+  reader: (path: string) => Promise<Buffer> = (path) => readFile(path),
+): Promise<FileDocumentResult> {
+  const filePath = options.file!.trim();
+  const bytes = await reader(filePath);
+  const sourceLabel = options.sourceLabel?.trim() || relativeSourceLabel(filePath);
+  return buildFileDocumentContent({
+    path: filePath,
+    bytes,
+    sourceLabel,
+    maxBytes: options.maxBytes,
+  });
+}
+
+/** Leak-safe cwd-relative label (basename if the file sits outside cwd). */
+function relativeSourceLabel(filePath: string): string {
+  const absolute = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+  return safeSourceLabel(relative(process.cwd(), absolute));
+}
+
+// ---------------------------------------------------------------------------
+// Directory ingest (--dir / --glob / --ext): one signed KO per matching file.
+//
+//   collectFiles ──► confirm summary ──► per-file: read → wrap → sign+store
+//                          │                          │
+//                          └─ --yes / --json skip     └─ binary/oversize ⇒ warn+skip
+// ---------------------------------------------------------------------------
+
+function isDirectoryMode(options: BrainCreateOptions): boolean {
+  const has = (v: string | undefined): boolean => typeof v === "string" && v.trim().length > 0;
+  return has(options.dir) || has(options.glob) || has(options.ext);
+}
+
+async function brainCreateFromDirectory(
+  options: BrainCreateOptions,
+  dependencies: BrainCreateDependencies,
+  runtime: LocalRuntime,
+  stdout: Pick<typeof console, "log">,
+): Promise<void> {
+  if (options.file || options.contentJson || options.prompt) {
+    throw new Error("--dir/--glob/--ext cannot be combined with --file, --content-json, or --prompt.");
   }
+  if (options.koId) {
+    throw new Error("--ko-id is only valid for single-object creation, not directory ingest.");
+  }
+
+  const ext = options.ext
+    ?.split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const { files, skipped } = collectFiles({ root: options.dir, glob: options.glob, ext });
 
-  throw new Error("Pass --content-json or --prompt to create a Knowledge Object.");
+  if (files.length === 0) {
+    stdout.log(options.json ? JSON.stringify({ created: [], skipped: skipped.length }) : "No matching files found.");
+    return;
+  }
+
+  const approved = options.yes === true || options.json === true
+    ? true
+    : await confirmDirectory(buildDirectorySummary(files, skipped.length), dependencies, stdout);
+  if (!approved) {
+    stdout.log("Aborted. No Knowledge Objects were created.");
+    return;
+  }
+
+  const maxBytes = options.maxBytes;
+  const ownsDb = dependencies.createDb === undefined;
+  const db = dependencies.createDb?.(runtime.connectionString) ?? createDb(runtime.connectionString);
+  const createdAt = dependencies.now?.() ?? new Date();
+
+  const created: { id: string; source: string; contentHash: string }[] = [];
+  const failures: { source: string; reason: string }[] = [];
+
+  try {
+    for (const file of files) {
+      let document: FileDocumentResult;
+      try {
+        const bytes = await readFile(file.absolutePath);
+        document = buildFileDocumentContent({ path: file.absolutePath, bytes, sourceLabel: file.label, maxBytes });
+      } catch (error) {
+        const reason = error instanceof FileDocumentError ? error.message : (error as Error).message;
+        failures.push({ source: file.label, reason });
+        if (!options.json) stdout.log(`  skip ${file.label}: ${reason}`);
+        continue;
+      }
+
+      const result = await createLocalKnowledgeObject({
+        db,
+        identityPath: runtime.identityPath,
+        contentType: document.contentType,
+        content: document.content,
+        createdAt,
+        storedAt: createdAt,
+      });
+      created.push({ id: result.ko.id, source: document.source, contentHash: result.contentHash });
+    }
+  } finally {
+    if (ownsDb) await closeDb(db);
+  }
+
+  if (options.json) {
+    stdout.log(JSON.stringify({ created, skipped: skipped.length, failed: failures }, null, 2));
+    return;
+  }
+  stdout.log(
+    [
+      `Created ${created.length} Knowledge Object(s).`,
+      ...created.map((c) => `  ${c.id}  ${c.source}`),
+      ...(failures.length > 0 ? [`Skipped ${failures.length} unreadable file(s).`] : []),
+    ].join("\n"),
+  );
+}
+
+function buildDirectorySummary(files: readonly CollectedFile[], skippedCount: number): string {
+  const preview = files.slice(0, 20).map((f) => `  ${f.label}`);
+  const more = files.length > 20 ? [`  …and ${files.length - 20} more`] : [];
+  const skipNote = skippedCount > 0 ? [`(${skippedCount} path(s) excluded: hidden/node_modules/.git/symlinks)`] : [];
+  return [
+    `About to create ${files.length} signed Knowledge Object(s) from local files:`,
+    ...preview,
+    ...more,
+    ...skipNote,
+  ].join("\n");
+}
+
+async function confirmDirectory(
+  summary: string,
+  dependencies: BrainCreateDependencies,
+  stdout: Pick<typeof console, "log">,
+): Promise<boolean> {
+  if (dependencies.confirm) return dependencies.confirm(summary);
+
+  stdout.log(summary);
+  if (!process.stdin.isTTY) {
+    throw new Error("Directory ingest needs confirmation. Re-run with --yes for non-interactive use.");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Continue? [y/N] ");
+    return answer.trim().toLowerCase() === "y";
+  } finally {
+    rl.close();
+  }
 }
 
 function parseContentJson(raw: string): CanonicalJsonValue {
diff --git a/packages/federation/verbs/index.ts b/packages/federation/verbs/index.ts
index 47212ebd..3a78b305 100644
--- a/packages/federation/verbs/index.ts
+++ b/packages/federation/verbs/index.ts
@@ -32,7 +32,7 @@ import {
   type IdentityDependencies,
 } from "./identity.js";
 import { revokeCommand, type RevokeDependencies } from "./revoke.js";
-import { agentRunCommand, type AgentRunDependencies } from "./run.js";
+import { agentRunCommand, runChainCommand, type AgentRunDependencies } from "./run.js";
 import { runTaskCommand, type RunTaskDependencies } from "./run-task.js";
 import { shareCommand, type ShareDependencies } from "./share.js";
 
@@ -90,6 +90,13 @@ export function registerFederationCommands(
     .description("Create and store a local signed Knowledge Object")
     .option("--content-json <json>", "Knowledge Object content as JSON")
     .option("--prompt <text>", "Generate Knowledge Object content from a prompt")
+    .option("--file <path>", "Create a Knowledge Object from a local text/markdown/json file (no credentials)")
+    .option("--dir <path>", "Create one KO per file under a directory (no credentials)")
+    .option("--glob <pattern>", "Glob pattern for --dir ingest, e.g. '**/*.md' (relative to --dir or cwd)")
+    .option("--ext <list>", "Comma-separated extension allowlist for directory ingest, e.g. md,txt,json")
+    .option("--source-label <label>", "Override the provenance source label for --file (default: cwd-relative path)")
+    .option("--max-bytes <n>", "Max file size for --file/--dir in bytes (default 1048576)", (v: string) => Number.parseInt(v, 10))
+    .option("--yes", "Skip the directory-ingest confirmation prompt", false)
     .option("--adapter-command <command>", "Optional adapter-like command that reads the prompt on stdin and writes output")
     .option("--adapter-arg <arg>", "Argument passed to --adapter-command; repeat for multiple args", collectOption, [])
     .option("--content-type <type>", "Knowledge Object content type", "application/json")
@@ -495,6 +502,7 @@ export {
   identityShowCommand,
   identityVerifyChainCommand,
   agentRunCommand,
+  runChainCommand,
   runTaskCommand,
   type BrainExportDependencies,
   type BrainImportDependencies,
diff --git a/packages/federation/verbs/run.test.ts b/packages/federation/verbs/run.test.ts
index 524e7cc1..e5799c02 100644
--- a/packages/federation/verbs/run.test.ts
+++ b/packages/federation/verbs/run.test.ts
@@ -13,18 +13,23 @@ import type { CanonicalJsonValue } from "../src/crypto/canonical.js";
 import type { ReadKnowledgeObjectResult } from "../src/brain/brain-store.js";
 import { deterministicAdapter, type AdapterRunResult, type RunAdapter } from "../src/runs/adapters.js";
 import type { RunCache } from "../src/runs/run-cache.js";
-import { agentRunCommand } from "./run.js";
+import { agentRunCommand, runChainCommand, runOnce } from "./run.js";
+import { resolveLocalRuntime } from "./local-runtime.js";
 
 const tempRoots: string[] = [];
 const identity = createInstallIdentity(new Date("2026-05-22T00:00:00.000Z"));
 
 function inputKo(id: string, content: CanonicalJsonValue): SignedKnowledgeObject {
+  return inputKoAt(id, content, new Date("2026-05-21T00:00:00.000Z"));
+}
+
+function inputKoAt(id: string, content: CanonicalJsonValue, createdAt: Date): SignedKnowledgeObject {
   return createKnowledgeObject({
     tenant: "stacy/acme",
     contentType: "application/json",
     content,
     identity,
-    createdAt: new Date("2026-05-21T00:00:00.000Z"),
+    createdAt,
     idGenerator: () => id,
   });
 }
@@ -150,6 +155,57 @@ describe("agentRunCommand", () => {
     expect(second.cached).toBe(true);
   });
 
+  it("caches on identical CONTENT even when the input KO id/timestamp differ (chain caching)", async () => {
+    // Two KOs with identical content but different createdAt => different KO
+    // ids and contentHashes (the KO hash folds in createdAt). A chain's
+    // downstream step sees a freshly-created upstream output KO each run, so
+    // keying the run cache on the KO hash would miss every time. The cache must
+    // key on content instead.
+    const content = { kind: "doc", body: "same content" };
+    const objects = new Map<string, SignedKnowledgeObject>([
+      ["ko_v1", inputKoAt("ko_v1", content, new Date("2026-05-21T00:00:00.000Z"))],
+      ["ko_v2", inputKoAt("ko_v2", content, new Date("2026-05-22T12:34:56.000Z"))],
+    ]);
+    expect(objects.get("ko_v1")!.signedPayload.contentHash).not.toBe(
+      objects.get("ko_v2")!.signedPayload.contentHash,
+    ); // sanity: different KO content hashes (createdAt differs)
+
+    let adapterRuns = 0;
+    const countingAdapter: RunAdapter = {
+      id: "deterministic",
+      deterministic: true,
+      run: async () => {
+        adapterRuns += 1;
+        return { output: { kind: "report" } };
+      },
+    };
+    const store = new Map<string, AdapterRunResult>();
+    const cache: RunCache = {
+      get: async (key) => store.get(key),
+      set: async (key, value) => {
+        store.set(key, value);
+      },
+    };
+    const runWith = (koId: string) =>
+      agentRunCommand(
+        "Summarize",
+        { dbUrl: "postgres://example", use: [koId], adapter: "deterministic", json: true },
+        {
+          adapters: new Map([["deterministic", countingAdapter]]),
+          createDb: () => ({ execute: async () => [] }),
+          readKnowledgeObject: fakeRead(objects),
+          cache,
+          stdout: { log: () => undefined },
+          now: () => new Date("2026-05-22T00:00:00.000Z"),
+        },
+      );
+
+    await runWith("ko_v1");
+    await runWith("ko_v2"); // different KO id, same content => must hit cache
+
+    expect(adapterRuns).toBe(1);
+  });
+
   it("skips the cache when noCache is set", async () => {
     const objects = new Map<string, SignedKnowledgeObject>([
       ["ko_pr_231", inputKo("ko_pr_231", { kind: "github_pull_request", number: 231 })],
@@ -233,6 +289,180 @@ describe("agentRunCommand", () => {
     ).rejects.toThrow("ko_missing could not be read");
   });
 
+  it("runOnce returns the stored KO id and flips fromCache across calls (chain contract)", async () => {
+    const configPath = await writeConfig();
+    const runtime = resolveLocalRuntime({ config: configPath, dbUrl: "postgres://example" }, {});
+    const objects = new Map<string, SignedKnowledgeObject>([
+      ["ko_in", inputKo("ko_in", { kind: "doc", n: 1 })],
+    ]);
+    const store = new Map<string, AdapterRunResult>();
+    const cache: RunCache = {
+      get: async (key) => store.get(key),
+      set: async (key, value) => {
+        store.set(key, value);
+      },
+    };
+    const ctx = {
+      db: { execute: async () => [] } as never,
+      read: fakeRead(objects),
+      cache,
+      identityPath: runtime.identityPath,
+      now: new Date("2026-05-22T00:00:00.000Z"),
+    };
+    const params = {
+      task: "Summarize",
+      model: "claude-sonnet-4-5",
+      adapter: deterministicAdapter,
+      inputKoIds: ["ko_in"],
+    };
+
+    const first = await runOnce(params, ctx);
+    const second = await runOnce(params, ctx);
+
+    expect(first.koId).toMatch(/^ko_/);
+    expect(first.contentHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+    expect(first.fromCache).toBe(false);
+    expect(second.fromCache).toBe(true);
+    // #7: deterministic content => identical KO id and hash across runs.
+    expect(second.koId).toBe(first.koId);
+    expect(second.contentHash).toBe(first.contentHash);
+  });
+
+  it("runs a 2-step chain, threading @ref from step 1's output into step 2", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-chain-"));
+    tempRoots.push(root);
+    const configPath = await writeConfig();
+    const specPath = join(root, "chain.json");
+    await writeFile(
+      specPath,
+      JSON.stringify({
+        steps: [
+          { id: "per_doc", task: "Summarize each", use: ["ko_a", "ko_b"] },
+          { id: "synthesis", task: "Synthesize one report", use: ["@per_doc"] },
+        ],
+      }),
+      "utf8",
+    );
+
+    const seeded = new Map<string, SignedKnowledgeObject>([
+      ["ko_a", inputKo("ko_a", { kind: "doc", n: 1 })],
+      ["ko_b", inputKo("ko_b", { kind: "doc", n: 2 })],
+    ]);
+    // Serve seeded inputs; synthesize a valid signed KO for produced step
+    // outputs so a later step's @ref read resolves and verifies.
+    const read = async ({ koId }: { koId: string }): Promise<ReadKnowledgeObjectResult> => {
+      const ko = seeded.get(koId) ?? inputKo(koId, { kind: "produced", id: koId });
+      return {
+        ok: true,
+        ko,
+        provenance: { source: "local", creatorInstallId: ko.signedPayload.creatorInstallId, storedAt: "2026-05-21T00:00:00.000Z" },
+        verification: { contentHash: ko.signedPayload.contentHash },
+      };
+    };
+
+    const lines: string[] = [];
+    await runChainCommand(
+      { config: configPath, dbUrl: "postgres://example", chain: specPath, adapter: "deterministic", json: true },
+      {
+        createDb: () => ({ execute: async () => [] }),
+        readKnowledgeObject: read,
+        stdout: { log: (line) => lines.push(line) },
+        now: () => new Date("2026-05-22T00:00:00.000Z"),
+      },
+    );
+
+    const out = JSON.parse(lines[0] ?? "{}") as {
+      steps: { id: string; koId: string; inputKoIds: string[] }[];
+      finalKoId: string;
+    };
+    expect(out.steps).toHaveLength(2);
+    expect(out.steps[0]?.inputKoIds).toEqual(["ko_a", "ko_b"]);
+    // step 2's @per_doc resolved to step 1's produced KO id.
+    expect(out.steps[1]?.inputKoIds).toEqual([out.steps[0]?.koId]);
+    expect(out.finalKoId).toBe(out.steps[1]?.koId);
+  });
+
+  it("gates egress once before any read for a non-deterministic chain", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-chain-egress-"));
+    tempRoots.push(root);
+    const specPath = join(root, "chain.json");
+    await writeFile(specPath, JSON.stringify({ steps: [{ id: "a", task: "t", use: ["ko_a"] }] }), "utf8");
+
+    let dbCreated = false;
+    const networkAdapter: RunAdapter = { id: "anthropic", deterministic: false, run: async () => ({ output: {} }) };
+
+    await expect(
+      runChainCommand(
+        { dbUrl: "postgres://example", chain: specPath, adapter: "anthropic" },
+        {
+          adapters: new Map([["anthropic", networkAdapter]]),
+          createDb: () => {
+            dbCreated = true;
+            return { execute: async () => [] };
+          },
+          stdout: { log: () => undefined },
+        },
+      ),
+    ).rejects.toThrow("--ack-egress");
+    expect(dbCreated).toBe(false);
+  });
+
+  it("aborts the chain on a step failure and names the failed step", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-chain-fail-"));
+    tempRoots.push(root);
+    const configPath = await writeConfig();
+    const specPath = join(root, "chain.json");
+    await writeFile(specPath, JSON.stringify({ steps: [{ id: "boom", task: "t", use: ["ko_a"] }] }), "utf8");
+
+    const seeded = new Map<string, SignedKnowledgeObject>([["ko_a", inputKo("ko_a", { kind: "doc" })]]);
+    const failingAdapter: RunAdapter = {
+      id: "deterministic",
+      deterministic: true,
+      run: async () => {
+        throw new Error("adapter exploded");
+      },
+    };
+
+    await expect(
+      runChainCommand(
+        { config: configPath, dbUrl: "postgres://example", chain: specPath, adapter: "deterministic" },
+        {
+          adapters: new Map([["deterministic", failingAdapter]]),
+          createDb: () => ({ execute: async () => [] }),
+          readKnowledgeObject: fakeRead(seeded),
+          stdout: { log: () => undefined },
+          now: () => new Date("2026-05-22T00:00:00.000Z"),
+        },
+      ),
+    ).rejects.toThrow(/Chain step "boom" failed: adapter exploded/);
+  });
+
+  it("rejects a chain spec with a forward @ref before any run", async () => {
+    const root = await mkdtemp(join(tmpdir(), "stacy-federation-chain-badref-"));
+    tempRoots.push(root);
+    const specPath = join(root, "chain.json");
+    await writeFile(
+      specPath,
+      JSON.stringify({ steps: [{ id: "a", task: "t", use: ["@later"] }, { id: "later", task: "t2", use: ["ko_a"] }] }),
+      "utf8",
+    );
+
+    let dbCreated = false;
+    await expect(
+      runChainCommand(
+        { dbUrl: "postgres://example", chain: specPath, adapter: "deterministic" },
+        {
+          createDb: () => {
+            dbCreated = true;
+            return { execute: async () => [] };
+          },
+          stdout: { log: () => undefined },
+        },
+      ),
+    ).rejects.toThrow(/not a prior step/);
+    expect(dbCreated).toBe(false);
+  });
+
   it("requires at least one --use input", async () => {
     await expect(
       agentRunCommand(
diff --git a/packages/federation/verbs/run.ts b/packages/federation/verbs/run.ts
index 8198e3ce..45a88e28 100644
--- a/packages/federation/verbs/run.ts
+++ b/packages/federation/verbs/run.ts
@@ -1,9 +1,13 @@
+import { readFile } from "node:fs/promises";
+
 import { createDb } from "@arpanstacy/stacy-db";
 
 import {
   readKnowledgeObject,
   type BrainDb,
 } from "../src/brain/brain-store.js";
+import { canonicalBytes } from "../src/crypto/canonical.js";
+import { sha256Hex } from "../src/util/hash.js";
 import { verifyKnowledgeObject } from "../src/ko/knowledge-object.js";
 import {
   buildAgentOutputContent,
@@ -17,6 +21,10 @@ import {
   type AdapterRunInput,
   type RunAdapter,
 } from "../src/runs/adapters.js";
+import {
+  parseChainSpec,
+  resolveStepInputs,
+} from "../src/runs/chain.js";
 import { storeAgentRunOutput } from "../src/runs/run-service.js";
 import {
   FileRunCache,
@@ -41,6 +49,16 @@ export interface AgentRunOptions extends LocalRuntimeOptions {
   readonly json?: boolean;
 }
 
+export interface ChainRunOptions extends LocalRuntimeOptions {
+  /** Path to the chain spec JSON file. */
+  readonly chain: string;
+  readonly model?: string;
+  readonly adapter?: string;
+  readonly ackEgress?: boolean;
+  readonly noCache?: boolean;
+  readonly json?: boolean;
+}
+
 export interface AgentRunDependencies extends LocalRuntimeDependencies {
   readonly createDb?: (connectionString: string) => BrainDb;
   readonly readKnowledgeObject?: typeof readKnowledgeObject;
@@ -70,87 +88,33 @@ export async function agentRunCommand(
   const model = options.model?.trim() || DEFAULT_ANTHROPIC_MODEL;
   const registry = dependencies.adapters ?? buildAdapterRegistry({ env });
   const adapterName = options.adapter?.trim() || resolveDefaultAdapterId(env);
-  const adapter = resolveRunAdapter(adapterName, registry);
-
-  // Egress gate must fire before any Knowledge Object is read or any network
-  // call is made, exactly like the existing demo runner.
-  if (!adapter.deterministic && options.ackEgress !== true) {
-    throw new Error(
-      `The ${adapter.id} adapter may send Knowledge Object content outside this install. Re-run with --ack-egress to confirm, or use --adapter deterministic.`,
-    );
-  }
+  const adapter = resolveAdapterWithEgressGate(adapterName, registry, options.ackEgress === true);
 
   const runtime = resolveLocalRuntime(options, dependencies);
   const ownsDb = dependencies.createDb === undefined;
   const db = dependencies.createDb?.(runtime.connectionString) ?? createDb(runtime.connectionString);
   const read = dependencies.readKnowledgeObject ?? readKnowledgeObject;
   const now = dependencies.now?.() ?? new Date();
+  const cache = options.noCache === true
+    ? undefined
+    : dependencies.cache ?? new FileRunCache(resolveRunCacheDir(runtime.instanceRoot));
 
   try {
-    const inputs = await loadAndVerifyInputs({ db, read, koIds: inputKoIds });
-
-    const cache = options.noCache === true
-      ? undefined
-      : dependencies.cache ?? new FileRunCache(resolveRunCacheDir(runtime.instanceRoot));
-    const cacheKey = computeRunCacheKey({
-      task: trimmedTask,
-      model,
-      adapter: adapter.id,
-      inputContentHashes: inputs.map((input) => input.reference.contentHash),
-    });
-
-    let fromCache = false;
-    let adapterResult: AdapterRunResult | undefined = await cache?.get(cacheKey);
-    if (adapterResult) {
-      fromCache = true;
-    } else {
-      adapterResult = await adapter.run({
-        task: trimmedTask,
-        model,
-        inputs: inputs.map(
-          (input): AdapterRunInput => ({
-            koId: input.reference.koId,
-            contentHash: input.reference.contentHash,
-            contentType: input.reference.contentType,
-            content: input.content,
-          }),
-        ),
-      });
-      await cache?.set(cacheKey, adapterResult);
-    }
-
-    const content = buildAgentOutputContent({
-      task: trimmedTask,
-      model,
-      adapter: adapter.id,
-      generatedAt: now,
-      inputs: inputs.map((input) => input.reference),
-      output: adapterResult.output,
-      notes: adapterResult.notes,
-    });
-
-    const stored = await storeAgentRunOutput({
-      db,
-      identityPath: runtime.identityPath,
-      content,
-      adapter: adapter.id,
-      model,
-      inputKoIds,
-      createdAt: now,
-      storedAt: now,
-      idGenerator: options.koId ? () => options.koId! : undefined,
-    });
+    const result = await runOnce(
+      { task: trimmedTask, model, adapter, inputKoIds, koId: options.koId },
+      { db, read, cache, identityPath: runtime.identityPath, now },
+    );
 
     const summary = {
-      id: stored.ko.id,
-      tenant: stored.ko.signedPayload.tenant,
+      id: result.koId,
+      tenant: result.tenant,
       task: trimmedTask,
       model,
       adapter: adapter.id,
       inputKoIds,
-      contentHash: stored.contentHash,
-      creatorInstallId: stored.creatorInstallId,
-      cached: fromCache,
+      contentHash: result.contentHash,
+      creatorInstallId: result.creatorInstallId,
+      cached: result.fromCache,
     };
 
     stdout.log(options.json ? JSON.stringify(summary, null, 2) : formatRunText(summary, adapter.deterministic, options.ackEgress === true));
@@ -159,9 +123,245 @@ export async function agentRunCommand(
   }
 }
 
+/**
+ * Resolves a run adapter and enforces the egress gate. For a non-deterministic
+ * adapter, this throws BEFORE any KO is read or network call is made unless the
+ * caller acknowledged egress. A chain calls this ONCE, up front, so the whole
+ * chain is gated before its first step reads anything.
+ */
+function resolveAdapterWithEgressGate(
+  adapterName: string,
+  registry: ReadonlyMap<string, RunAdapter>,
+  ackEgress: boolean,
+): RunAdapter {
+  const adapter = resolveRunAdapter(adapterName, registry);
+  if (!adapter.deterministic && !ackEgress) {
+    throw new Error(
+      `The ${adapter.id} adapter may send Knowledge Object content outside this install. Re-run with --ack-egress to confirm, or use --adapter deterministic.`,
+    );
+  }
+  return adapter;
+}
+
+/**
+ * Runs a multi-step chain: each step is a {@link runOnce}, and a later step can
+ * consume an earlier step's output KO via an `@<stepId>` reference. The spec is
+ * parsed and fully validated (including `@ref` resolution) before the egress
+ * gate and before any KO is read, so a malformed chain never egresses. A step
+ * failure aborts the chain; already-produced step KOs are durable (no rollback)
+ * and the error names the failed step.
+ */
+export async function runChainCommand(
+  options: ChainRunOptions,
+  dependencies: AgentRunDependencies = {},
+): Promise<void> {
+  const stdout = dependencies.stdout ?? console;
+  const env = dependencies.env ?? process.env;
+
+  const specPath = options.chain?.trim();
+  if (!specPath) {
+    throw new Error("`stacy run --chain` requires a path to a chain spec JSON file.");
+  }
+  const spec = parseChainSpec(await readFile(specPath, "utf8"));
+
+  const model = options.model?.trim() || DEFAULT_ANTHROPIC_MODEL;
+  const registry = dependencies.adapters ?? buildAdapterRegistry({ env });
+  const adapterName = options.adapter?.trim() || resolveDefaultAdapterId(env);
+  // Gate ONCE, up front, before any KO read.
+  const adapter = resolveAdapterWithEgressGate(adapterName, registry, options.ackEgress === true);
+
+  const runtime = resolveLocalRuntime(options, dependencies);
+  const ownsDb = dependencies.createDb === undefined;
+  const db = dependencies.createDb?.(runtime.connectionString) ?? createDb(runtime.connectionString);
+  const read = dependencies.readKnowledgeObject ?? readKnowledgeObject;
+  const now = dependencies.now?.() ?? new Date();
+  const cache = options.noCache === true
+    ? undefined
+    : dependencies.cache ?? new FileRunCache(resolveRunCacheDir(runtime.instanceRoot));
+  const context = { db, read, cache, identityPath: runtime.identityPath, now };
+
+  const outputs = new Map<string, string>();
+  const stepSummaries: {
+    id: string;
+    koId: string;
+    inputKoIds: readonly string[];
+    cached: boolean;
+  }[] = [];
+
+  try {
+    for (const step of spec.steps) {
+      const inputKoIds = resolveStepInputs(step, outputs);
+      let result;
+      try {
+        result = await runOnce(
+          { task: step.task, model: step.model?.trim() || model, adapter, inputKoIds },
+          context,
+        );
+      } catch (error) {
+        throw new Error(`Chain step "${step.id}" failed: ${(error as Error).message}`);
+      }
+      outputs.set(step.id, result.koId);
+      stepSummaries.push({ id: step.id, koId: result.koId, inputKoIds, cached: result.fromCache });
+    }
+  } finally {
+    if (ownsDb) await closeDb(db);
+  }
+
+  const finalStep = stepSummaries[stepSummaries.length - 1];
+  const summary = {
+    steps: stepSummaries,
+    finalKoId: finalStep?.koId,
+    adapter: adapter.id,
+    model,
+  };
+
+  stdout.log(options.json ? JSON.stringify(summary, null, 2) : formatChainText(summary, adapter.deterministic, options.ackEgress === true));
+}
+
+function formatChainText(
+  summary: {
+    readonly steps: readonly { id: string; koId: string; inputKoIds: readonly string[]; cached: boolean }[];
+    readonly finalKoId?: string;
+    readonly adapter: string;
+    readonly model: string;
+  },
+  deterministic: boolean,
+  ackEgress: boolean,
+): string {
+  const lines = [
+    `Egress acknowledgement: ${deterministic ? "not required (deterministic adapter)" : ackEgress ? "✓ (--ack-egress provided)" : "n/a"}`,
+    `Adapter: ${summary.adapter}   Model: ${summary.model}`,
+    `Chain steps: ${summary.steps.length}`,
+  ];
+  for (const step of summary.steps) {
+    lines.push(
+      `  ${step.id}: ${step.koId}${step.cached ? " (cached)" : ""}  ← ${step.inputKoIds.join(", ")}`,
+    );
+  }
+  lines.push("", `Final output KO: ${summary.finalKoId}`, `Inspect it with \`stacy brain show ${summary.finalKoId}\`.`);
+  return lines.join("\n");
+}
+
+/** Inputs to a single run step. The adapter is already resolved and the egress
+ * gate already cleared by the caller (so chains gate once, up front). */
+export interface RunOnceParams {
+  readonly task: string;
+  readonly model: string;
+  readonly adapter: RunAdapter;
+  readonly inputKoIds: readonly string[];
+  readonly koId?: string;
+}
+
+/** Shared run dependencies. One `cache` instance is reused across chain steps. */
+export interface RunOnceContext {
+  readonly db: BrainDb;
+  readonly read: typeof readKnowledgeObject;
+  readonly cache?: RunCache;
+  readonly identityPath: string;
+  readonly now: Date;
+}
+
+export interface RunOnceResult {
+  readonly koId: string;
+  readonly contentHash: string;
+  readonly creatorInstallId: string;
+  readonly tenant: string;
+  readonly fromCache: boolean;
+}
+
+/**
+ * Executes ONE run: load + verify inputs, consult the run-result cache, invoke
+ * the adapter on a miss, then sign + store the `agent_output` KO. Returns the
+ * stored KO id so callers can chain steps. The single-run verb and the run
+ * chain both go through here — no duplicated run logic, no stdout parsing.
+ */
+export async function runOnce(
+  params: RunOnceParams,
+  context: RunOnceContext,
+): Promise<RunOnceResult> {
+  const inputs = await loadAndVerifyInputs({
+    db: context.db,
+    read: context.read,
+    koIds: params.inputKoIds,
+  });
+
+  const cacheKey = computeRunCacheKey({
+    task: params.task,
+    model: params.model,
+    adapter: params.adapter.id,
+    inputContentHashes: inputs.map((input) => input.cacheHash),
+  });
+
+  let fromCache = false;
+  let adapterResult: AdapterRunResult | undefined = await context.cache?.get(cacheKey);
+  if (adapterResult) {
+    fromCache = true;
+  } else {
+    adapterResult = await params.adapter.run({
+      task: params.task,
+      model: params.model,
+      inputs: inputs.map(
+        (input): AdapterRunInput => ({
+          koId: input.reference.koId,
+          contentHash: input.reference.contentHash,
+          contentType: input.reference.contentType,
+          content: input.content,
+        }),
+      ),
+    });
+    await context.cache?.set(cacheKey, adapterResult);
+  }
+
+  const content = buildAgentOutputContent({
+    task: params.task,
+    model: params.model,
+    adapter: params.adapter.id,
+    inputs: inputs.map((input) => input.reference),
+    output: adapterResult.output,
+    notes: adapterResult.notes,
+  });
+
+  const stored = await storeAgentRunOutput({
+    db: context.db,
+    identityPath: context.identityPath,
+    content,
+    adapter: params.adapter.id,
+    model: params.model,
+    inputKoIds: params.inputKoIds,
+    createdAt: context.now,
+    storedAt: context.now,
+    idGenerator: params.koId ? () => params.koId! : undefined,
+  });
+
+  return {
+    koId: stored.ko.id,
+    contentHash: stored.contentHash,
+    creatorInstallId: stored.creatorInstallId,
+    tenant: stored.ko.signedPayload.tenant,
+    fromCache,
+  };
+}
+
 interface LoadedInput {
   readonly reference: AgentRunInputReference;
   readonly content: AdapterRunInput["content"];
+  /**
+   * Hash of the input's CONTENT (+ content type) only — independent of the KO's
+   * `createdAt`. The KO's own `contentHash` folds in a wall-clock `createdAt`
+   * (knowledge-object.ts), so it changes every time a KO is created even for
+   * identical content. Using it as a run-cache key would make a chain's
+   * downstream step (whose input is the prior step's freshly-created output KO)
+   * miss the cache on every run. Keying on content instead means identical
+   * inputs reuse the cached adapter result, so an identical chain re-run makes
+   * zero adapter calls. The KO `contentHash` is still used for provenance.
+   */
+  readonly cacheHash: string;
+}
+
+/** Content-addressed cache hash: stable across runs and installs for identical
+ * content, unlike the KO id/contentHash which embed `createdAt`. */
+function computeInputCacheHash(contentType: string, content: AdapterRunInput["content"]): string {
+  return sha256Hex(canonicalBytes({ contentType, content }));
 }
 
 async function loadAndVerifyInputs(options: {
@@ -179,13 +379,16 @@ async function loadAndVerifyInputs(options: {
     if (!verification.ok) {
       throw new Error(`Input Knowledge Object ${koId} failed verification: ${verification.reason}`);
     }
+    const contentType = result.ko.signedPayload.contentType;
+    const content = result.ko.signedPayload.content;
     loaded.push({
       reference: {
         koId: result.ko.id,
         contentHash: verification.contentHash,
-        contentType: result.ko.signedPayload.contentType,
+        contentType,
       },
-      content: result.ko.signedPayload.content,
+      content,
+      cacheHash: computeInputCacheHash(contentType, content),
     });
   }
   return loaded;