diff --git a/.agents/skills/filigree-workflow/SKILL.md b/.agents/skills/filigree-workflow/SKILL.md
index f0c02a27..1c2414df 100644
--- a/.agents/skills/filigree-workflow/SKILL.md
+++ b/.agents/skills/filigree-workflow/SKILL.md
@@ -23,12 +23,22 @@ Every task follows this lifecycle:
 filigree ready                                      → find available work (no blockers)
 filigree show <issue-id>                            → read requirements and context
 filigree transitions <issue-id>                     → check valid status transitions
-filigree start-work <issue-id> --assignee <name>    → atomically claim + transition to in_progress
+filigree start-work <issue-id> --assignee <name>    → atomically claim + transition into its working status
 [do the work, commit code]
 filigree close <issue-id> --reason="summary of what was done"
 ```
 
-Or skip steps 1–3 entirely with `filigree start-next-work --assignee <name>` to grab the highest-priority ready issue.
+Or skip steps 1–3 entirely with `filigree start-next-work --assignee <name>` to grab the highest-priority **startable** issue.
+
+> **Ready ≠ startable.** The working status is type-specific (tasks →
+> `in_progress`, features → `building`). Bugs start at `triage`, which has no
+> single-hop transition into work — they walk `triage → confirmed → fixing`. So
+> a triage bug is *ready* but not directly *startable*: `start-work` on one
+> returns `INVALID_TRANSITION` naming the next status to move through, and
+> `start-next-work` skips it. `ready` items carry a `startable` flag (and a
+> `next_action` hint when false). Pass `--advance` to either command to walk the
+> soft transitions automatically (`triage → confirmed → fixing`) instead of
+> being blocked or skipped.
 
 Always close with a `--reason` — it becomes audit trail for the next agent.
 
@@ -49,18 +59,26 @@ When triaging, use `filigree batch-update <ids...> --priority=N` for bulk change
 ### Solo or Swarm — Same Tool
 
 Use `start-work` (or `start-next-work`) for the usual case. Both atomically
-claim the issue *and* transition it to `in_progress` in one DB transaction —
-optimistic-locking on the assignee, so concurrent callers can't both think
-they own the issue.
+claim the issue *and* transition it into its working status in one DB
+transaction — optimistic-locking on the assignee, so concurrent callers can't
+both think they own the issue. The working status is type-specific (tasks →
+`in_progress`, features → `building`, bugs → `fixing`).
 
 ```bash
-filigree start-work <issue-id> --assignee <agent-name>     # specific issue
-filigree start-next-work --assignee <agent-name>           # highest-priority ready
+filigree start-work <issue-id> --assignee <agent-name>              # specific issue
+filigree start-next-work --assignee <agent-name>                    # highest-priority startable
+filigree start-work <bug-id> --assignee <agent-name> --advance      # walk triage → confirmed → fixing
 ```
 
 If another agent already owns the claim, the call fails with `code: CONFLICT`
 (CLI exit 4). Safe to retry against a different issue.
 
+`start-work` on a `triage` bug (or any type with no single-hop working status)
+returns `INVALID_TRANSITION` naming the intermediate status to move through
+first; `start-next-work` skips such issues. Pass `--advance` to walk the soft
+transitions to the nearest working status automatically (missing required
+fields become warnings, not blocks; hard edges are never auto-walked).
+
 ### Niche: Claim Without Transitioning
 
 `claim` and `claim-next` still exist for the rare case where you want to
@@ -170,13 +188,15 @@ When parsing `--json` output or MCP responses, expect these unified envelopes:
 
 - **Batch ops** → `{succeeded: [...], failed: [{id, error, code}, ...], newly_unblocked?: [...]}`.
   `failed` is always present (empty list if none); `newly_unblocked` is
-  omitted when the op cannot unblock. Pass `--detail=full` (CLI) or
+  present only when non-empty (omitted when the op unblocked nothing). Pass `--detail=full` (CLI) or
   `response_detail="full"` (MCP) to get full records back.
 - **List ops** → `{items: [...], has_more: bool, next_offset?: int}`.
   `next_offset` only appears when there is a next page.
 - **Errors** → `{error: str, code: ErrorCode, details?: dict}`. `code` is
   one of: `VALIDATION`, `NOT_FOUND`, `CONFLICT`, `INVALID_TRANSITION`,
-  `PERMISSION`, `NOT_INITIALIZED`, `IO`, `INVALID_API_URL`, `STOP_FAILED`,
+  `PERMISSION`, `NOT_INITIALIZED`, `IO`, `INVALID_API_URL`,
+  `FILE_REGISTRY_DISPLACED`, `REGISTRY_UNAVAILABLE`,
+  `CLARION_REGISTRY_VERSION_MISMATCH`, `BRIEFING_BLOCKED`, `STOP_FAILED`,
   `SCHEMA_MISMATCH`, `INTERNAL`. Branch on `code` for retry policy
   (`CONFLICT` → exit 4, retryable; everything at exit 1 needs operator
   intervention).
diff --git a/.agents/skills/filigree-workflow/references/team-coordination.md b/.agents/skills/filigree-workflow/references/team-coordination.md
index 9f5c24a4..8f2102e9 100644
--- a/.agents/skills/filigree-workflow/references/team-coordination.md
+++ b/.agents/skills/filigree-workflow/references/team-coordination.md
@@ -7,10 +7,11 @@ work across multiple agents.
 
 ### The Race Condition Problem
 
-When multiple agents call `filigree update <issue-id> --status=in_progress`
+When multiple agents call `filigree update <issue-id> --status=<wip>`
 simultaneously, both think they own the issue. Filigree 2.0 solves this with
-`start-work`, which atomically claims the issue *and* transitions it to
-`in_progress` in a single DB transaction with optimistic locking on the
+`start-work`, which atomically claims the issue *and* transitions it to its
+type-specific working status (tasks → `in_progress`, features → `building`,
+bugs → `fixing`) in a single DB transaction with optimistic locking on the
 assignee.
 
 ### Start Protocol
@@ -27,9 +28,12 @@ If another agent already claimed the issue, the call fails with
 `code: CONFLICT` (CLI exit 4). No silent overwrite, no half-claimed state —
 either both the claim and the transition land, or neither does.
 
-`start-next-work` accepts the same filters as `claim-next`
-(`--type`, `--priority-min`, `--priority-max`, `--target-status`) so
-specialised agents can scope their work.
+`start-next-work` accepts the work-scoping filters `claim-next` also
+takes (`--type`, `--priority-min`, `--priority-max`) so specialised agents
+can scope their work. Because `start-next-work` *transitions* (not just
+reserves), it additionally accepts `--target-status` to override the wip
+target and `--advance` to walk soft transitions to wip — neither of which
+`claim-next` has, since `claim-next` only reserves and never changes status.
 
 ### Niche: Claim Without Transitioning
 
@@ -62,7 +66,8 @@ When passing work between agents, follow this sequence:
 
 1. **Document state**: Add a comment with current progress, decisions made,
    and remaining work
-2. **Update status**: Leave at `in_progress` if partially done, or close if complete
+2. **Update status**: Leave in its working status (`in_progress` / `building` /
+   `fixing`) if partially done, or close if complete
 3. **Flag blockers**: Create blocker issues and add dependencies if needed
 
 ```bash
diff --git a/.agents/skills/filigree-workflow/references/workflow-patterns.md b/.agents/skills/filigree-workflow/references/workflow-patterns.md
index 14fb10ff..3758ce59 100644
--- a/.agents/skills/filigree-workflow/references/workflow-patterns.md
+++ b/.agents/skills/filigree-workflow/references/workflow-patterns.md
@@ -95,23 +95,33 @@ filigree remove-dep <blocked> <blocker>
 
 ### Standard Flow
 
+Bugs in the core pack do **not** start in a directly-startable state. They
+open at `triage` and walk soft transitions toward work (run
+`filigree type-info bug` for the authoritative graph):
+
 ```
-create (open) → in_progress → closed
+create (triage) → confirmed → fixing → verifying → closed
 ```
 
-Use `filigree start-work <issue-id> --assignee <name>` to make the
-`open → in_progress` transition atomically.
+`triage` has no single-hop transition into a `wip` status, so a fresh bug is
+*ready* but not *startable*. Pass `--advance` to walk the soft transitions to
+the nearest working status automatically:
 
-### With Verification
+```bash
+filigree start-work <bug-id> --assignee <name> --advance   # triage → confirmed → fixing
+```
 
-For types that support it (check `filigree type-info bug`):
+Without `--advance`, `start-work` on a `triage` bug returns
+`INVALID_TRANSITION` naming the next status (`confirmed`), and
+`start-next-work` skips it.
 
-```
-open → fixing → verifying → closed
-```
+### Disambiguating the wip target
 
-Pass `--target-status fixing` to `start-work` if the workflow has multiple
-`wip`-category targets and the resolver needs disambiguation.
+If the workflow has multiple `wip`-category targets reachable from the
+current status and the resolver needs disambiguation, pass
+`--target-status fixing` to `start-work` / `start-next-work`. (`claim` /
+`claim-next` only reserve and never transition, so they do not take
+`--target-status` or `--advance`.)
 
 ### Bug Report Template
 
diff --git a/.clarion/.gitignore b/.clarion/.gitignore
new file mode 100644
index 00000000..1ad40f6c
--- /dev/null
+++ b/.clarion/.gitignore
@@ -0,0 +1,22 @@
+# Clarion .gitignore — ADR-005 tracked-vs-excluded list.
+# Tracked (committed): clarion.db, config.json, .gitignore itself.
+# Excluded (ignored): WAL sidecars, shadow DB, per-run logs, tmp scratch.
+
+# SQLite write-ahead files never belong in the repo.
+*-wal
+*-shm
+*.db-wal
+*.db-shm
+
+# Shadow DB intermediate (ADR-011 --shadow-db).
+*.shadow.db
+*.db.new
+
+# Scratch / temp space.
+tmp/
+
+# Per-run log directories (see detailed-design §File layout). The run dir
+# metadata (config.yaml, stats.json, partial.json) is tracked; only the
+# raw LLM request/response log is excluded.
+logs/
+runs/*/log.jsonl
diff --git a/.clarion/clarion.db b/.clarion/clarion.db
new file mode 100644
index 00000000..55bf13f4
Binary files /dev/null and b/.clarion/clarion.db differ
diff --git a/.clarion/config.json b/.clarion/config.json
new file mode 100644
index 00000000..d7ef3efe
--- /dev/null
+++ b/.clarion/config.json
@@ -0,0 +1,4 @@
+{
+    "schema_version": 1,
+    "last_run_id": null
+}
diff --git a/.clarion/instance_id b/.clarion/instance_id
new file mode 100644
index 00000000..0b987625
--- /dev/null
+++ b/.clarion/instance_id
@@ -0,0 +1 @@
+07196666-c132-4bff-b9fb-1d0eeff64fdf
diff --git a/.codex b/.codex
deleted file mode 100644
index e69de29b..00000000
diff --git a/.codex/config.toml b/.codex/config.toml
new file mode 100644
index 00000000..4214a24b
--- /dev/null
+++ b/.codex/config.toml
@@ -0,0 +1,11 @@
+# Project-local Codex MCP configuration.
+# Codex does not read .mcp.json, so mirror this project's stdio MCP servers here.
+
+[mcp_servers.filigree]
+command = "/home/john/.local/bin/filigree-mcp"
+args = ["--project", "/home/john/clarion"]
+
+[mcp_servers.clarion-dogfood]
+command = "/home/john/clarion/target/release/clarion"
+args = ["serve", "--path", "/home/john/clarion"]
+env = { PATH = "/home/john/clarion/plugins/python/.venv/bin:/home/john/.local/bin:/home/john/elspeth/.venv/bin:/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/home/john/.cargo/bin:/home/john/.nvm/versions/node/v20.19.3/bin:/home/john/miniconda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
diff --git a/.filigree.conf b/.filigree.conf
new file mode 100644
index 00000000..f3d9ffca
--- /dev/null
+++ b/.filigree.conf
@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "project_name": "clarion",
+  "prefix": "clarion",
+  "db": ".filigree/filigree.db"
+}
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 8dd0916e..1fac7524 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,5 +1,10 @@
 version: 2
 updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
   - package-ecosystem: "pip"
     directory: "/plugins/python"
     schedule:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e4cd32b3..a8cff089 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -11,6 +11,7 @@ concurrency:
 
 env:
   CARGO_TERM_COLOR: always
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
   RUSTFLAGS: "-D warnings"
 
 jobs:
@@ -18,13 +19,22 @@ jobs:
     name: Rust
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
         with:
+          toolchain: stable
           components: clippy, rustfmt, llvm-tools-preview
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
+
+      # Python is used by the migration-retirement guard and the
+      # workspace-version-lockstep guard below. Pin >= 3.11 explicitly so the
+      # stdlib `tomllib` is available regardless of which Python the runner
+      # image happens to preinstall.
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
 
       - name: fmt
         run: cargo fmt --all -- --check
@@ -34,11 +44,34 @@ jobs:
           python scripts/check-migration-retirement.py --self-test
           python scripts/check-migration-retirement.py
 
+      - name: release governance static guard
+        run: |
+          python scripts/check-github-release-governance.py --self-test
+          python scripts/check-github-release-governance.py --static-only
+
+      - name: cross-workspace version lockstep
+        run: python scripts/check-workspace-version-lockstep.py
+
+      - name: pyright pin lockstep
+        run: |
+          python scripts/check-pyright-pin-lockstep.py --self-test
+          python scripts/check-pyright-pin-lockstep.py
+
+      - name: wardline version bounds
+        run: |
+          python scripts/check-wardline-version-bounds.py --self-test
+          python scripts/check-wardline-version-bounds.py
+
+      - name: entity-cap ADR/code lockstep
+        run: |
+          python scripts/check-entity-cap-lockstep.py --self-test
+          python scripts/check-entity-cap-lockstep.py
+
       - name: clippy
         run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
       - name: install cargo-nextest
-        uses: taiki-e/install-action@cargo-nextest
+        uses: taiki-e/install-action@e310bff3ef77234d477d6bb655da153a5c49d1db
 
       # Ensure all workspace binaries (notably clarion-plugin-fixture) are built
       # before nextest runs. wp2_e2e tests need the fixture binary on disk and
@@ -52,9 +85,11 @@ jobs:
 
       - name: doc
         run: cargo doc --workspace --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: "-D warnings"
 
       - name: install cargo-deny
-        uses: taiki-e/install-action@cargo-deny
+        uses: taiki-e/install-action@2e721ffcfc34740897fc3130e2dd782b1c136896
 
       - name: deny
         run: cargo deny check
@@ -63,16 +98,16 @@ jobs:
     name: Python plugin
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: "3.11"
           cache: pip
           cache-dependency-path: plugins/python/pyproject.toml
 
       - name: cache pyright runtime
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
         with:
           path: ~/.cache/pyright-python/
           key: pyright-python-1.1.409-${{ runner.os }}
@@ -105,20 +140,22 @@ jobs:
     runs-on: ubuntu-latest
     needs: [rust, python-plugin]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: "3.11"
           cache: pip
           cache-dependency-path: plugins/python/pyproject.toml
 
       - name: cache pyright runtime
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
         with:
           path: ~/.cache/pyright-python/
           key: pyright-python-1.1.409-${{ runner.os }}
@@ -128,3 +165,12 @@ jobs:
 
       - name: run walking skeleton
         run: bash tests/e2e/sprint_1_walking_skeleton.sh
+
+      - name: run WP5 secret scanner smoke
+        run: CARGO_BUILD=0 bash tests/e2e/wp5_secret_scan.sh
+
+      - name: Sprint 2 MCP surface
+        run: CARGO_BUILD=0 bash tests/e2e/sprint_2_mcp_surface.sh
+
+      - name: Phase 3 subsystems
+        run: CARGO_BUILD=0 bash tests/e2e/phase3_subsystems.sh
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 00000000..04b66a40
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,489 @@
+name: Release
+
+# Per ADR-033 — pushed tags matching v* trigger a multi-platform binary build
+# plus Python plugin sdist, attached to a GitHub Release. Build jobs run only
+# after the `verify` gate (mirroring ci.yml) is green, so a broken commit
+# cannot publish a Release with `draft: false`.
+on:
+  push:
+    tags:
+      - "v*"
+  # Manual dispatch produces build artifacts on the workflow run for inspection.
+  # The `release` job is gated on event_name == 'push', so workflow_dispatch
+  # never publishes a public Release — it only validates that the build/verify
+  # plumbing is healthy before a tag push.
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  RUSTFLAGS: "-D warnings"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    # Pre-release gate: must mirror ci.yml so a broken commit cannot reach the
+    # build/publish jobs. Duplicated rather than refactored into a reusable
+    # workflow on the eve of 1.0; that refactor is post-release scope.
+    name: Verify (pre-release gates)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - name: Assert tagged commit is on main
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main || \
+            { echo "::error::tag does not point to a commit on main"; exit 1; }
+
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+          components: clippy, rustfmt
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
+        with:
+          key: release-verify
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+
+      - name: cache pyright runtime
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
+        with:
+          path: ~/.cache/pyright-python/
+          key: pyright-python-1.1.409-${{ runner.os }}
+
+      - name: rust fmt
+        run: cargo fmt --all -- --check
+
+      - name: migration retirement guard
+        run: |
+          python scripts/check-migration-retirement.py --self-test
+          python scripts/check-migration-retirement.py
+
+      - name: cross-workspace version lockstep
+        run: python scripts/check-workspace-version-lockstep.py
+
+      - name: rust clippy
+        run: cargo clippy --workspace --all-targets --all-features -- -D warnings
+
+      - name: install cargo-nextest
+        uses: taiki-e/install-action@e310bff3ef77234d477d6bb655da153a5c49d1db
+
+      - name: rust build workspace bins
+        run: cargo build --workspace --bins
+
+      - name: rust nextest
+        run: cargo nextest run --workspace --all-features --no-tests=pass
+
+      - name: rust doc
+        run: cargo doc --workspace --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+
+      - name: install cargo-deny
+        uses: taiki-e/install-action@2e721ffcfc34740897fc3130e2dd782b1c136896
+
+      - name: cargo deny
+        run: cargo deny check
+
+      - name: check B.4* gate result freshness
+        run: python scripts/check-b4-gate-result.py
+
+      - name: check Python ontology version lockstep
+        run: |
+          python scripts/check-python-ontology-version.py --self-test
+          python scripts/check-python-ontology-version.py
+
+      - name: install plugin (dev extras)
+        run: python -m pip install -e 'plugins/python[dev]'
+
+      - name: ruff check
+        run: ruff check plugins/python
+
+      - name: ruff format check
+        run: ruff format --check plugins/python
+
+      - name: mypy
+        run: mypy --strict plugins/python
+
+      - name: pytest
+        run: pytest plugins/python
+
+      - name: install sqlite3 cli
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends sqlite3
+
+      - name: walking skeleton (end-to-end)
+        run: bash tests/e2e/sprint_1_walking_skeleton.sh
+
+      - name: WP5 secret scanner smoke
+        run: CARGO_BUILD=0 bash tests/e2e/wp5_secret_scan.sh
+
+      - name: Sprint 2 MCP surface
+        run: CARGO_BUILD=0 bash tests/e2e/sprint_2_mcp_surface.sh
+
+      - name: Phase 3 subsystems
+        run: CARGO_BUILD=0 bash tests/e2e/phase3_subsystems.sh
+
+  release-governance:
+    name: GitHub release governance
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - name: enforce repository release controls
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_GOVERNANCE_TOKEN }}
+        run: |
+          set -euo pipefail
+          python scripts/check-github-release-governance.py \
+            --repository "${GITHUB_REPOSITORY}" \
+            --branch main
+
+  build-rust:
+    needs: [verify, release-governance]
+    name: Build clarion (${{ matrix.target }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: ubuntu-latest
+          - target: x86_64-apple-darwin
+            runner: macos-13
+          - target: aarch64-apple-darwin
+            runner: macos-14
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8
+        with:
+          toolchain: stable
+          targets: ${{ matrix.target }}
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
+        with:
+          key: release-${{ matrix.target }}
+
+      - name: build release
+        run: |
+          set -euo pipefail
+          cargo build --release --locked --bin clarion --target ${{ matrix.target }}
+
+      - name: package
+        id: package
+        run: |
+          set -euo pipefail
+          STAGE="clarion-${{ matrix.target }}"
+          mkdir -p "$STAGE"
+          cp "target/${{ matrix.target }}/release/clarion" "$STAGE/"
+          cp README.md "$STAGE/"
+          if [ -f LICENSE ]; then cp LICENSE "$STAGE/"; fi
+          ARCHIVE="$STAGE.tar.gz"
+          tar czf "$ARCHIVE" "$STAGE"
+          # Portable across the runner matrix: macOS images ship `shasum`, not
+          # GNU `sha256sum`. Both emit the same `<hex>  <filename>` line.
+          if command -v sha256sum >/dev/null 2>&1; then
+            sha256sum "$ARCHIVE" > "$ARCHIVE.sha256"
+          else
+            shasum -a 256 "$ARCHIVE" > "$ARCHIVE.sha256"
+          fi
+          SMOKE_DIR="$(mktemp -d)"
+          tar xzf "$ARCHIVE" -C "$SMOKE_DIR"
+          "$SMOKE_DIR/$STAGE/clarion" --version
+          "$SMOKE_DIR/$STAGE/clarion" --help >/dev/null
+          echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: clarion-${{ matrix.target }}
+          path: |
+            ${{ steps.package.outputs.archive }}
+            ${{ steps.package.outputs.archive }}.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  release-subjects:
+    name: Derive release artifact subjects
+    runs-on: ubuntu-latest
+    needs: [build-rust, build-plugin]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      actions: read
+      contents: read
+    outputs:
+      rust-subjects: ${{ steps.subjects.outputs.rust-subjects }}
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          path: artifacts
+
+      - name: compute Rust archive subjects
+        id: subjects
+        run: |
+          set -euo pipefail
+          while IFS= read -r -d '' asset; do
+            digest=$(sha256sum "$asset" | cut -d' ' -f1)
+            printf '%s  %s\n' "$digest" "$(basename "$asset")"
+          done < <(find artifacts \( -name 'clarion-*.tar.gz' -o -name 'clarion_plugin_python*.tar.gz' \) -print0 | sort -z) > rust-subjects.txt
+          test -s rust-subjects.txt
+          echo "rust-subjects=$(base64 -w0 rust-subjects.txt)" >> "$GITHUB_OUTPUT"
+
+  build-plugin:
+    needs: [verify, release-governance]
+    name: Build Python plugin sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+
+      - name: install build
+        run: python -m pip install --upgrade build
+
+      - name: build sdist
+        run: python -m build --sdist --outdir dist plugins/python
+
+      - name: smoke install sdist
+        run: |
+          set -euo pipefail
+          python -m venv .venv-smoke
+          . .venv-smoke/bin/activate
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.tar.gz
+          python -c "import clarion_plugin_python; assert clarion_plugin_python.__version__ == '1.0.0'"
+          command -v clarion-plugin-python
+
+      - name: checksum
+        run: |
+          set -euo pipefail
+          cd dist
+          for f in *.tar.gz; do
+            sha256sum "$f" > "$f.sha256"
+          done
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: clarion-plugin-python-sdist
+          path: |
+            dist/*.tar.gz
+            dist/*.tar.gz.sha256
+          if-no-files-found: error
+          retention-days: 7
+
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [build-rust, build-plugin]
+    # Only publish to a Release when a real tag pushed; workflow_dispatch leaves
+    # artifacts on the workflow run for inspection without creating a public Release.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          path: artifacts
+
+      - name: stage release assets
+        run: |
+          set -euo pipefail
+          mkdir -p release
+          find artifacts -name '*.tar.gz' -o -name '*.tar.gz.sha256' \
+            | xargs -I{} cp {} release/
+          ls -la release/
+
+      - name: install cosign
+        uses: sigstore/cosign-installer@398d4b0eeef1380460a10c8013a76f728fb906ac
+
+      - name: sign release archives
+        run: |
+          set -euo pipefail
+          for asset in release/*.tar.gz; do
+            cosign sign-blob --yes \
+              --output-signature "$asset.sig" \
+              --output-certificate "$asset.pem" \
+              "$asset"
+          done
+          ls -la release/
+
+      - name: smoke-verify release archive signatures
+        run: |
+          set -euo pipefail
+          for asset in release/*.tar.gz; do
+            cosign verify-blob \
+              --certificate "$asset.pem" \
+              --signature "$asset.sig" \
+              --certificate-identity-regexp "https://github.com/${GITHUB_REPOSITORY}/.github/workflows/release.yml@refs/tags/v.*" \
+              --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+              "$asset"
+          done
+
+      - name: derive previous tag
+        id: prev
+        run: |
+          set -euo pipefail
+          PREV=$(git tag --sort=-v:refname | grep -v "^${GITHUB_REF_NAME}\$" | head -n1 || true)
+          if [ -z "$PREV" ]; then
+            echo "previous=" >> "$GITHUB_OUTPUT"
+            echo "No previous tag found (first release)."
+          else
+            echo "previous=$PREV" >> "$GITHUB_OUTPUT"
+            echo "Previous tag: $PREV"
+          fi
+
+      - name: generate notes
+        id: notes
+        run: |
+          set -euo pipefail
+          PREV="${{ steps.prev.outputs.previous }}"
+          # Derive the actual sdist filename from the staged artifact rather
+          # than hard-coding it: PEP 625 (and the hatchling build backend)
+          # normalize the project name and embed the version, so any version
+          # bump or normalization-rule change would invalidate a literal URL.
+          # `|| true` so `set -e` does not abort the script when the glob
+          # is empty — we want to fall through to the explicit error below.
+          SDIST_PATH=$(ls release/clarion[-_]plugin[-_]python*.tar.gz 2>/dev/null | head -n1 || true)
+          if [ -z "$SDIST_PATH" ]; then
+            echo "::error::no Python plugin sdist found in release/ — refusing to publish notes with a broken install link" >&2
+            exit 1
+          fi
+          SDIST_NAME=$(basename "$SDIST_PATH")
+          {
+            echo "## Clarion ${GITHUB_REF_NAME}"
+            echo ""
+            echo "### Install"
+            echo ""
+            echo "Pick the archive for your platform from the Assets list below."
+            echo "Verify the SHA256, extract, and place \`clarion\` on your \`\$PATH\`."
+            echo ""
+            echo "\`\`\`bash"
+            echo "curl -L -o clarion.tar.gz \\"
+            echo "  https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/clarion-x86_64-unknown-linux-gnu.tar.gz"
+            echo "tar xzf clarion.tar.gz"
+            echo "install clarion-x86_64-unknown-linux-gnu/clarion ~/.local/bin/"
+            echo ""
+            echo "pipx install \\"
+            echo "  https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/${SDIST_NAME}"
+            echo "\`\`\`"
+            echo ""
+            echo "Full walkthrough: [docs/operator/getting-started.md](https://github.com/${GITHUB_REPOSITORY}/blob/${GITHUB_REF_NAME}/docs/operator/getting-started.md)."
+            echo ""
+            echo "### Changes"
+            echo ""
+            if [ -n "$PREV" ]; then
+              git log --merges --pretty='- %s (%h)' "${PREV}..${GITHUB_REF_NAME}" || true
+            else
+              echo "First release — see git history."
+            fi
+          } > NOTES.md
+          echo "notes-file=NOTES.md" >> "$GITHUB_OUTPUT"
+
+      - name: create release
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Clarion ${{ github.ref_name }}
+          body_path: ${{ steps.notes.outputs.notes-file }}
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-alpha') || contains(github.ref_name, '-beta') }}
+          files: release/*
+          fail_on_unmatched_files: true
+
+  provenance:
+    name: Generate SLSA provenance
+    needs: [release, release-subjects]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@f7dd8c54c2067bafc12ca7a55595d5ee9b75204a
+    with:
+      base64-subjects: ${{ needs.release-subjects.outputs.rust-subjects }}
+      upload-assets: true
+      upload-tag-name: ${{ github.ref_name }}
+      provenance-name: clarion-rust-binaries.intoto.jsonl
+
+  verify-published-release:
+    name: Verify published release assets
+    needs: [release]
+    runs-on: ubuntu-latest
+    # Post-publish gate: prove the assets actually served from the public
+    # GitHub Release match the signed local copies. The in-`release`-job
+    # `cosign verify-blob` only proves signing worked on the build runner; it
+    # does not prove the published download matches. This job downloads the
+    # public assets, recomputes SHA256 against the published `.sha256`
+    # sidecars, and re-verifies the cosign signatures against the public Rekor
+    # entries.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+    steps:
+      - name: install cosign
+        uses: sigstore/cosign-installer@398d4b0eeef1380460a10c8013a76f728fb906ac
+
+      - name: download published assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          mkdir -p published
+          cd published
+          gh release download "${GITHUB_REF_NAME}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --pattern '*.tar.gz' \
+            --pattern '*.tar.gz.sha256' \
+            --pattern '*.tar.gz.sig' \
+            --pattern '*.tar.gz.pem'
+          ls -la
+
+      - name: recompute SHA256 against published checksums
+        run: |
+          set -euo pipefail
+          cd published
+          shopt -s nullglob
+          checksums=(*.tar.gz.sha256)
+          if [ ${#checksums[@]} -eq 0 ]; then
+            echo "::error::no .sha256 sidecars found in the published release" >&2
+            exit 1
+          fi
+          for sum in "${checksums[@]}"; do
+            sha256sum -c "$sum"
+          done
+
+      - name: cosign verify published archives against Rekor
+        run: |
+          set -euo pipefail
+          cd published
+          shopt -s nullglob
+          archives=(*.tar.gz)
+          if [ ${#archives[@]} -eq 0 ]; then
+            echo "::error::no .tar.gz archives found in the published release" >&2
+            exit 1
+          fi
+          for asset in "${archives[@]}"; do
+            cosign verify-blob \
+              --certificate "$asset.pem" \
+              --signature "$asset.sig" \
+              --certificate-identity-regexp "https://github.com/${GITHUB_REPOSITORY}/.github/workflows/release.yml@refs/tags/v.*" \
+              --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+              "$asset"
+          done
diff --git a/.gitignore b/.gitignore
index 17baed25..a65b5291 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,4 +22,7 @@ __pycache__/
 htmlcov/
 .claude/
 
-.env
\ No newline at end of file
+.env
+
+# Smoke-test result artifacts (per-run; archived separately at tag-cut)
+tests/e2e/external-operator-smoke-results-*.md
\ No newline at end of file
diff --git a/.mcp.json b/.mcp.json
index 24a20674..3a1531be 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -3,18 +3,17 @@
     "filigree": {
       "type": "stdio",
       "command": "/home/john/.local/bin/filigree-mcp",
-      "args": [],
-      "env": {}
+      "args": []
     },
     "clarion": {
       "type": "stdio",
       "command": "/home/john/clarion/target/release/clarion",
       "args": [
         "serve",
-        "--path", "/tmp/clarion-b8-elspeth-full-20260518T0016Z",
-        "--config", "/tmp/clarion-b8-elspeth-full-20260518T0016Z/clarion-b8-live.yaml"
+        "--path",
+        "/home/john/clarion"
       ],
       "env": {}
     }
   }
-}
\ No newline at end of file
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..ad0186b5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,351 @@
+# AGENTS.md
+
+This file is the operating contract for coding agents working in this
+repository. It is intentionally practical: start here, then follow the linked
+source-of-truth docs when the task touches design, release, or federation
+semantics.
+
+## First Principles
+
+Clarion is a local-first code-archaeology tool. It ingests a repository,
+extracts entities and relationships, stores the graph in SQLite, and serves
+that graph to consult-mode agents over MCP and the federation HTTP read API.
+The v1.0 product is a Rust workspace plus a Python language plugin.
+
+Clarion is part of the Loom suite with Filigree and Wardline. The governing
+doctrine is the Loom federation rule:
+
+1. Each product must remain useful alone.
+2. Each pair of products must compose meaningfully.
+3. Integration must enrich a product's view, not become required for that
+   product's semantics to make sense.
+
+Before accepting any design that adds a shared runtime, shared registry,
+cross-product mediator, mandatory sibling dependency, or "small glue layer,"
+read [docs/suite/loom.md](docs/suite/loom.md) and apply its failure test.
+Centralization is usually the thing trying to sneak in wearing a helpful hat.
+
+## Start Every Session
+
+Run a live project-state check before substantive work:
+
+```bash
+filigree session-context
+git status --short --branch
+```
+
+Use the tracker state, current branch, and dirty tree you actually see. Do not
+assume a previous handoff, memory entry, or branch name is current.
+
+If the tree is dirty, treat existing changes as user work unless you made them
+in this session. Read affected files before editing near them, and do not
+revert unrelated changes.
+
+## Source Of Truth
+
+When documents disagree, use this precedence:
+
+1. Accepted ADRs under [docs/clarion/adr/](docs/clarion/adr/).
+2. [docs/clarion/1.0/requirements.md](docs/clarion/1.0/requirements.md).
+3. [docs/clarion/1.0/system-design.md](docs/clarion/1.0/system-design.md).
+4. [docs/clarion/1.0/detailed-design.md](docs/clarion/1.0/detailed-design.md).
+5. Implementation and review history under [docs/implementation/](docs/implementation/).
+
+ADRs are decision records, not suggestions. Accepted ADRs are immutable except
+for status changes and supersession links. If an accepted ADR is wrong, write or
+propose a successor ADR rather than silently rewriting the old decision.
+
+Requirement IDs, ADR IDs, and federation contract names are load-bearing. Keep
+them stable and cite them in Filigree issues, commits, and review notes when
+they explain the work.
+
+## Reading Map
+
+Use the smallest set that grounds the task:
+
+- New orientation: [README.md](README.md), then
+  [docs/suite/briefing.md](docs/suite/briefing.md), then
+  [docs/suite/loom.md](docs/suite/loom.md).
+- Product design: [docs/clarion/1.0/README.md](docs/clarion/1.0/README.md),
+  then requirements, system design, and detailed design in that order.
+- Federation work: [docs/federation/contracts.md](docs/federation/contracts.md)
+  and the fixtures under [docs/federation/fixtures/](docs/federation/fixtures/).
+- Release work:
+  [docs/operator/v1.0-release-governance.md](docs/operator/v1.0-release-governance.md),
+  [.github/workflows/ci.yml](.github/workflows/ci.yml), and
+  [.github/workflows/release.yml](.github/workflows/release.yml).
+- Historical sprint context:
+  [docs/implementation/README.md](docs/implementation/README.md). Treat this
+  as supporting context, not as a normative source.
+
+## Repository Shape
+
+- [Cargo.toml](Cargo.toml) defines the Rust 2024 workspace and shared
+  dependency/lint policy.
+- [crates/clarion-core/](crates/clarion-core/) owns entity IDs, plugin hosting,
+  manifests, process limits, discovery, and core protocols.
+- [crates/clarion-storage/](crates/clarion-storage/) owns SQLite storage,
+  writer-actor behavior, and reader-pool access.
+- [crates/clarion-cli/](crates/clarion-cli/) owns the `clarion` binary and user
+  commands such as `install`, `analyze`, and `serve`.
+- [crates/clarion-mcp/](crates/clarion-mcp/) owns the MCP consult surface.
+- [crates/clarion-scanner/](crates/clarion-scanner/) owns pre-ingest secret
+  scanning.
+- [crates/clarion-plugin-fixture/](crates/clarion-plugin-fixture/) is a test
+  fixture crate.
+- [plugins/python/](plugins/python/) is the v1.0 Python language plugin.
+
+Prefer existing boundaries. If a change crosses crate, plugin, CLI, MCP,
+storage, or federation boundaries, name the contract being changed and add a
+test at the boundary.
+
+## Engineering Rules
+
+Do not guess. Read the source, reproduce behavior when useful, and make claims
+only as strong as the evidence you have.
+
+Prefer the earliest boundary that can enforce an invariant. Configuration,
+manifest parsing, protocol decoding, storage writes, and public response types
+are better places for hard failures than downstream call sites.
+
+For bug fixes, add or identify a focused failing regression before the fix when
+the behavior is testable. Keep fixes small enough that the regression proves the
+point.
+
+Use structured parsers and APIs where the repo already has them. Avoid ad hoc
+string surgery for TOML, JSON, YAML, SQL, or protocol payloads unless the local
+code already uses that pattern for the same reason.
+
+Do not introduce new cross-product coupling to make an implementation easier.
+If a sibling integration becomes necessary for semantics, stop and reconcile the
+design with the Loom doctrine before coding.
+
+Use focused subagents when they materially improve confidence or throughput.
+For release reviews, broad audits, multi-surface debugging, and independent
+implementation slices, split the work by boundary and dispatch subagents without
+asking for another permission round. Keep each subagent prompt self-contained,
+give it a narrow scope, avoid overlapping write sets, and integrate its findings
+against the live tree before reporting or closing work.
+
+## Verification Gates
+
+ADR-023 sets the CI floor. Run the narrowest useful gate while iterating, then
+run the relevant full gate before claiming completion.
+
+Rust gates:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --workspace --bins
+cargo nextest run --workspace --all-features
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
+cargo deny check
+```
+
+Python plugin gates, from the repo root:
+
+```bash
+plugins/python/.venv/bin/ruff check plugins/python
+plugins/python/.venv/bin/ruff format --check plugins/python
+plugins/python/.venv/bin/mypy --strict plugins/python
+plugins/python/.venv/bin/pytest plugins/python
+```
+
+End-to-end gates:
+
+```bash
+bash tests/e2e/sprint_1_walking_skeleton.sh
+bash tests/e2e/sprint_2_mcp_surface.sh
+bash tests/e2e/phase3_subsystems.sh
+```
+
+For release work, also run the governance guard described in
+[docs/operator/v1.0-release-governance.md](docs/operator/v1.0-release-governance.md).
+Live GitHub checks need a token with repository administration and Actions
+policy read access.
+
+## Filigree Workflow
+
+Filigree is the project tracker. Prefer MCP tools when available; use the CLI
+otherwise. Start from live state:
+
+```bash
+filigree session-context
+```
+
+Use atomic claim-and-transition verbs:
+
+```bash
+filigree start-next-work --assignee <name>
+filigree start-work <id> --assignee <name>
+```
+
+Do not chain `filigree claim` with a later status update. The combined verbs
+exist to avoid racing other agents.
+
+Close tracker work only after the implementation, verification, and comments
+match reality. If a discovered defect belongs to the active task, own it: fix
+it, broaden the task, file a proper dependent issue, or raise the blocker. Do
+not hide in-scope work in an expiring observation.
+
+Use observations only for incidental findings outside the current task. At
+session end, check accumulated observations and either promote or dismiss what
+is ready to triage.
+
+## Release Work
+
+Clarion v1.0 publishes from GitHub Releases. Do not cut tags or treat a commit
+as release-ready until:
+
+- Filigree shows no unresolved release blockers.
+- The full CI floor has passed on the release commit or PR.
+- The GitHub release governance guard passes for `main`.
+- The release workflow dry run from `main` passes.
+- The public artifact smoke test has been run from the GitHub Release artifacts.
+
+Release notes and status summaries must distinguish local commits, pushed
+branches, open PRs, merged PRs, and published tags. A local green branch is not
+a shipped release.
+
+## Git And Commit Hygiene
+
+Keep commits scoped to the work requested. Do not stage unrelated dirty files.
+If the user asks for a broad commit, re-check `git status --short` immediately
+before staging so the scope is explicit.
+
+Prefer normal, reviewable history. Do not force-push, reset hard, delete
+branches, or discard work unless the user explicitly asks and the destructive
+scope is clear.
+
+If hooks fail, fix the blocker rather than bypassing hooks unless the user
+explicitly authorizes a checkpoint with failing gates.
+
+## Communication
+
+Keep status updates short and concrete: what you checked, what changed, what is
+blocked, and which verification ran. When reporting failures, include the exact
+command and the first useful error, not a vague "tests failed."
+
+When you are unsure, say what evidence is missing and go get it if it is cheap.
+When evidence is expensive or requires credentials, explain the limitation and
+the next command a maintainer can run.
+
+<!-- filigree:instructions:v2.1.0:9dff6e6d -->
+## Filigree Issue Tracker
+
+`filigree` tracks tasks for this project. Data lives in `.filigree/`. Prefer
+the MCP tools (`mcp__filigree__*`) when available; fall back to the `filigree`
+CLI otherwise.
+
+### Workflow
+
+```bash
+# At session start
+filigree session-context                            # ready / in-progress / critical path
+
+# Pick up the next startable issue (atomic claim + transition into its working status)
+filigree start-next-work --assignee <name>
+# ...or claim a specific issue
+filigree start-work <id> --assignee <name>
+
+# Do the work, commit, then
+filigree close <id>
+```
+
+Use the atomic claim+transition verbs — `start_work` / `start_next_work`
+(MCP) or `start-work` / `start-next-work` (CLI). Do **not** chain
+`claim_issue` (MCP) or `filigree claim` (CLI) with a subsequent status
+update — the two-step form races against other agents; the combined verb is
+atomic.
+
+**Ready ≠ startable.** The working status is type-specific (tasks →
+`in_progress`, features → `building`). Bugs start at `triage`, which has no
+single-hop transition into work (`triage → confirmed → fixing`), so a triage
+bug is *ready* but not directly *startable*: `start_work` on one returns
+`INVALID_TRANSITION` naming the next status, and `start_next_work` skips it.
+`get_ready` items carry a `startable` flag (plus a `next_action` hint when
+false). Pass `advance=true` (MCP) / `--advance` (CLI) to walk the soft
+transitions to the nearest working status automatically.
+
+### Observations: when (and when not) to use them
+
+`observe` is a fire-and-forget scratchpad for *incidental* defects — things
+you notice *outside the scope of your current task* (a code smell in a
+neighbouring file, a stale TODO, a missing test for an edge case you happened
+to spot). Notes expire after 14 days unless promoted. Include `file_path` and
+`line` when relevant. At session end, skim `list_observations` and either
+`dismiss_observation` or `promote_observation` for what has accumulated.
+
+**You fix bugs in your currently defined scope. You do NOT use observations
+to finish work prematurely.** If a defect, gap, or follow-up belongs to your
+current task, you own it — handle it as part of that task: fix it now, expand
+the task's scope, file a proper issue with a dependency, or surface it to the
+user. Filing it as an observation and closing the task is *not* completing
+the task; it is shipping known-broken work and hiding the debt in a 14-day
+expiring scratchpad. The test is "would I have noticed this even if I weren't
+working on this task?" If no, it's task scope, not an observation.
+
+### Priority scale
+
+- P0: Critical (drop everything)
+- P1: High (do next)
+- P2: Medium (default)
+- P3: Low
+- P4: Backlog
+
+### Reaching for tools
+
+MCP tool schemas describe each tool; `filigree --help` and `filigree <verb>
+--help` are the authoritative CLI reference. You do not need to memorise
+either catalogue. The verbs you will reach for most:
+
+- **Find work:** `get_ready`, `get_blocked`, `list_issues`, `search_issues`
+- **Claim work:** `start_work`, `start_next_work`
+- **Update:** `add_comment`, `add_label`, `update_issue`, `close_issue`
+- **Admin (irreversible):** `delete_issue` (MCP) / `delete-issue` (CLI) —
+  hard-deletes a terminal issue and its rows; `undo_last` cannot reverse it.
+- **Scratchpad:** `observe`, `list_observations`, `promote_observation`, `dismiss_observation`
+- **Cross-product entity bindings (ADR-029):** `add_entity_association`,
+  `remove_entity_association`, `list_entity_associations`,
+  `list_associations_by_entity`. Used when a sibling tool (e.g.
+  Clarion) needs to bind a Filigree issue to a function, class, or
+  module identifier it owns. The `entity_id` is an opaque string
+  from Filigree's perspective; the consumer (the sibling tool's read
+  path) does drift detection against the stored
+  `content_hash_at_attach`. `list_associations_by_entity` is the
+  reverse-lookup surface — given a Clarion entity ID, return every
+  Filigree issue bound to it (project isolation is by DB file). Also
+  reachable over HTTP as
+  `GET/POST /api/issue/{issue_id}/entity-associations`,
+  `DELETE /api/issue/{issue_id}/entity-associations?entity_id=…`,
+  and `GET /api/entity-associations?entity_id=…`.
+- **Health:** `get_stats`, `get_metrics`, `get_mcp_status`
+
+Pass `--actor <name>` (CLI) so events attribute to your agent identity. It
+works in either position — before the verb (`filigree --actor X update …`) or
+after it (`filigree update … --actor X`); the post-verb value overrides the
+group-level one.
+
+### Error handling
+
+Errors return `{error: str, code: ErrorCode, details?: dict}`. Switch on
+`code`, not on message text. Codes: `VALIDATION`, `NOT_FOUND`, `CONFLICT`,
+`INVALID_TRANSITION`, `PERMISSION`, `NOT_INITIALIZED`, `IO`,
+`INVALID_API_URL`, `FILE_REGISTRY_DISPLACED`, `REGISTRY_UNAVAILABLE`,
+`CLARION_REGISTRY_VERSION_MISMATCH`, `BRIEFING_BLOCKED`, `STOP_FAILED`,
+`SCHEMA_MISMATCH`, `INTERNAL`.
+
+On `INVALID_TRANSITION`, call `get_valid_transitions` (MCP) or
+`filigree transitions <id>` to see what the workflow allows from here.
+
+Two failure modes deserve a specific response:
+
+- **`SCHEMA_MISMATCH`** — the installed `filigree` is older than the project
+  database. The error message contains upgrade guidance. Surface it to the
+  user; do not retry.
+- **`ForeignDatabaseError`** — filigree found a parent project's database
+  but no local `.filigree.conf`. Run `filigree init` in the current
+  directory. Do **not** `cd` upward to a different project unless that was
+  the actual intent.
+<!-- /filigree:instructions -->
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..05323e26
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes to Clarion are documented here. The format is loosely based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and Clarion
+follows [Semantic Versioning](https://semver.org/) for the `clarion` binary,
+the workspace crates, and the Python plugin.
+
+API versioning for the federation HTTP read API (`/api/v1/...`) is independent
+of product semver: `api_version: 1` is the wire-contract version, and bumps
+only when an incompatible change is made to that surface. See
+[`docs/federation/contracts.md`](docs/federation/contracts.md).
+
+## [Unreleased]
+
+### Added
+
+- `clarion db backup <output>` — a consistent, WAL-safe online backup of
+  `.clarion/clarion.db` via `rusqlite::backup::Backup`. Safe to run during a
+  live `clarion analyze` (captures outstanding WAL frames into a standalone
+  single-file copy, unlike `cp`), writes atomically (temp sibling + rename),
+  refuses to clobber without `--force`, and verifies the copy with
+  `PRAGMA integrity_check` before promoting it. Closes gap-register STO-04
+  (clarion-6d433b61ba).
+- `source_for_entity(id, context_lines=10)` MCP tool — returns an entity's
+  exact indexed source span (decorators/signature/docstring included as
+  captured) plus a bounded window of line-numbered context, each line flagged
+  `in_entity`. No LLM call. Reports an explicit `source_status`
+  (`missing`/`no_range`/`binary`/`drifted`) rather than a misleading stale
+  snippet when the on-disk source no longer matches the indexed `content_hash`.
+  The MCP surface now exposes twelve tools (clarion-6077738f1c).
+- `call_sites(id, role=caller|callee, kind?, confidence?, path?)` MCP tool —
+  shows the actual source sites behind `calls`/`references` edges (file, line,
+  byte column, line text, edge kind, confidence) so an agent can see *why*
+  Clarion believes an edge exists. Statically-unbindable calls are returned in
+  a separate `unresolved_sites` list, never mixed with resolved evidence.
+  Filterable by edge kind and a documented best-effort production/test path
+  heuristic. No LLM call. The MCP surface now exposes thirteen tools
+  (clarion-9392f74881).
+- **Filigree finding emission (WP9-B core, REQ-FINDING-03).** `clarion analyze`
+  Phase 8 POSTs the run's persisted findings to Filigree's
+  `POST /api/v1/scan-results` intake, with Clarion's richer fields nested under
+  `metadata.clarion.*` (wire contract pinned in
+  [`docs/federation/contracts.md`](docs/federation/contracts.md)). Emission is
+  enrich-only — gated behind `integrations.filigree.{enabled,emit_findings}`
+  (now **both default `false`**, so enabling Filigree for `issues_for` reads
+  never silently starts outbound emission — clarion-a26de2f368), and any
+  Filigree-side failure is recorded in `stats.json`
+  (`CLA-INFRA-FILIGREE-UNREACHABLE`) instead of failing the run. Findings
+  anchored to a `briefing_blocked` entity are excluded, matching the fail-closed
+  read posture (clarion-8b32ba0d02). Resolves the 1.0 "finding emission
+  deferred" limitation below.
+- **`clarion analyze --resume RUN_ID` (WP9-B, REQ-FINDING-05).** Reopens a prior
+  run's `runs` row (a new `WriterCmd::ResumeRun` `UPDATE`s it back to `running`
+  instead of `INSERT`ing, which conflicted on the existing run PK), re-walks the
+  tree, and emits findings to Filigree with `mark_unseen=false` so the re-emit
+  does not flip the prior run's findings to `unseen_in_latest`. The re-walk is
+  idempotent: entities and run-scoped findings now both UPSERT on `id`
+  (previously only entities did), so a resumed run reproduces the same durable
+  graph as the original. The emitted `mark_unseen` value is recorded in
+  `stats.json`. Tracked under clarion-dd29e69e0e.
+- **`clarion analyze --prune-unseen` (WP9-B, REQ-FINDING-06).** After emission
+  (Phase 8b), POSTs Filigree's `POST /api/loom/findings/clean-stale` retention
+  route, scoped to `scan_source=clarion`, asking it to soft-archive its own
+  `unseen_in_latest` Clarion findings older than
+  `integrations.filigree.prune_unseen_days` (default 30). Soft-archive, not
+  delete: Filigree moves them to `fixed` and auto-reopens on reappearance
+  (Filigree ADR-015). Enrich-only — a Filigree outage or the integration being
+  disabled is recorded in `stats.json` (`filigree_prune`) and never fails the
+  run; the `scan_source` scoping is enforced server-side so the sweep can only
+  touch Clarion's findings. (Closes the REQ-FINDING-06 piece of
+  clarion-dd29e69e0e; the route was found to already exist in Filigree, so the
+  earlier "file a request" memo is superseded — see its withdrawal banner.) The
+  remaining Phase-0 scan-run-create handshake is an open contract question with
+  Filigree (Clarion relies on the peer tolerating an unknown `scan_run_id`),
+  tracked separately under `release:1.1`.
+
+### Changed
+
+- `entities` gains a `briefing_blocked` VIRTUAL generated column
+  (`json_extract(properties, '$.briefing_blocked')`) plus a partial index
+  (`ix_entities_briefing_blocked WHERE briefing_blocked IS NOT NULL`), so the
+  federation read-API hot path can filter entities withheld from briefings in
+  SQL instead of parsing every row's properties JSON. `project_status` now
+  reports a `counts.briefing_blocked` diagnostic (how many entities are
+  withheld), served by the new index. Edit-in-place in migration `0001` per
+  ADR-024 (no published build). Closes gap-register STO-04 / V11-STO-04
+  (clarion-bdabfd6bca).
+- The writer actor now opens its batch transactions with `BEGIN IMMEDIATE`
+  (via a new `clarion_storage::retry::begin_immediate` helper with bounded
+  `SQLITE_BUSY`/`SQLITE_LOCKED` retry + exponential backoff) instead of a
+  deferred `BEGIN`. Taking the write lock up front resolves cross-process
+  write contention at lock-acquire — where `busy_timeout` is honored — rather
+  than failing mid-statement on a deferred-lock upgrade the busy handler
+  cannot serve. Closes gap-register STO-05 (clarion-bbb3365920).
+
+## [1.0.0] — 2026-05-19
+
+First publishable release. Clarion ships as a Rust core (`clarion` binary, five
+workspace crates) plus an editable-install Python language plugin
+(`clarion-plugin-python`). Released under the [MIT License](LICENSE).
+
+Targets the `v1.0.0` tag (cut by the operator once all release blockers are
+green); supersedes the pre-release `v0.1-sprint-1` and `v0.1-sprint-2`
+working tags, which remain in the repo as historical anchors.
+
+### Core
+
+- `clarion install --path` initialises a project's `.clarion/` directory
+  (instance ID, SQLite DB, migrations).
+- `clarion analyze` walks a Python corpus and persists the structural graph
+  (entities + `contains`, `calls`, `references`, `imports` edges) to a local
+  SQLite store via the writer-actor pattern (ADR-011).
+- `clarion serve` exposes the MCP stdio surface for consult-mode agents:
+  `entity_at`, `find_entity`, `callers_of`, `execution_paths_from`,
+  `summary`, `issues_for`, `neighborhood`, `subsystem_members`.
+
+### Python plugin (`clarion-plugin-python` 1.0.0)
+
+- Pyright-backed entity extraction for functions, classes, and modules; resolved
+  / ambiguous / inferred call edges per ADR-022.
+- `wardline` runtime probe with version-range pinning (`>=1.0.0,<2.0.0`).
+- Module-level `imports` candidate edges (Phase 3 Task 3).
+- Strict-typed L4 JSON-RPC handshake with declared `entity_kinds`,
+  `edge_kinds`, `ontology_version`, and `rule_id_prefix` (ADR-022).
+
+### Federation HTTP read API (ADR-014)
+
+The publisher-side of Clarion's federation contract with Filigree's
+`ClarionRegistry`. Pinned in [`docs/federation/contracts.md`](docs/federation/contracts.md);
+fixtures under [`docs/federation/fixtures/`](docs/federation/fixtures/) are
+normative.
+
+- `GET /api/v1/_capabilities` — registry-backend probe, returns `instance_id`,
+  `api_version: 1`, and feature flags. Always unauthenticated so siblings can
+  discover the surface pre-auth.
+- `GET /api/v1/files?path=&language=` — single-file identity resolution.
+  Closed error envelope `{error, code}` with codes `INVALID_PATH`,
+  `PATH_OUTSIDE_PROJECT`, `NOT_FOUND`, `BRIEFING_BLOCKED`, `UNAUTHENTICATED`,
+  `BATCH_TOO_LARGE`, `STORAGE_ERROR`, `INTERNAL`. ETag / `If-None-Match` supported.
+- `POST /api/v1/files/batch` — bulk resolution, up to 256 queries per
+  request, single pooled `ReaderPool` checkout per batch. Four-way
+  partitioning: `resolved` / `not_found` / `briefing_blocked` / `errors`.
+- **Bearer authentication.** `serve.http.token_env` (default
+  `CLARION_LOOM_TOKEN`) names the env var holding the inbound bearer
+  token. Loopback-without-token stays unauthenticated for the v0.1 trust
+  model; non-loopback-without-token is refused at startup with
+  `CLA-CONFIG-HTTP-NO-AUTH`.
+- **Briefing-blocked propagation.** Files flagged by the pre-ingest secret
+  scanner return `403 BRIEFING_BLOCKED` on the single-file endpoint and
+  surface in the `briefing_blocked[]` partition on the batch endpoint.
+  Identity fields (`entity_id`, `content_hash`, `canonical_path`,
+  `language`) are deliberately omitted from blocked responses so siblings
+  cannot infer file identity from a refusal.
+
+### Secret scanner (WP5, ADR-013)
+
+- Pre-ingest scan annotates entities with `briefing_blocked` when a file
+  contains high-entropy or pattern-matched secrets; ingest proceeds, but
+  every federation read path refuses to surface the entity.
+
+### Subsystem clustering (WP4 Phase 3)
+
+- Storage-side queries for subsystem membership and inverse lookup.
+- Analyze-time clustering writes subsystem entities and `in_subsystem` edges.
+- `subsystem_members(id)` MCP tool surfaces cluster members to consult agents.
+
+### LLM providers
+
+- OpenRouter (default, requires `OPENROUTER_API_KEY`).
+- Codex CLI and Claude CLI as local-login providers — no API key surface,
+  the user's OS-level auth carries.
+- `recording` provider for deterministic test fixtures.
+
+### Operational
+
+- ADR-023 tooling baseline: `cargo fmt --check`, `cargo clippy -D warnings`,
+  `cargo nextest`, `cargo doc -D warnings`, `cargo deny`, `ruff`,
+  `ruff format --check`, `mypy --strict`, `pytest`, end-to-end walking-skeleton
+  script — all enforced in CI.
+- Pre-commit hooks wire the Python gates.
+- `.env` loaded from CWD or ancestor before tracing setup.
+
+### Known v1.0 limitations
+
+- **Python only.** Other-language plugins (`NG-15`) are v2.0+ scope.
+- **Filigree finding emission deferred to a future release (tracked under
+  `release:v1.1`).** Cross-product POSTing of Clarion-generated findings into
+  Filigree's intake (WP9-B) is deferred per the [Sprint 2 scope amendment](docs/implementation/sprint-2/scope-amendment-2026-05.md).
+  `issues_for(id)` (the WP9-A binding for reading from Filigree) ships in 1.0.
+  *(WP9-B core shipped post-1.0 — see the Filigree-finding-emission entry under
+  [Unreleased]; only the REQ-FINDING-05/-06 lifecycle tail remains deferred.)*
+- **HTTP file language inference** uses persisted plugin manifest language when
+  available, with a narrow core-extension fallback for files that predate
+  manifest capture.
+- **Cooperative HMAC inbound auth** ships for the HTTP read API via
+  `serve.http.identity_token_env` and `X-Loom-Component: clarion:<hmac>`.
+  The older bearer-token path remains available for compatibility.
+- **Python plugin imports `wardline.core.registry.REGISTRY` at startup**
+  (loom.md §5 asterisk 2). Initialization coupling scoped to the
+  Wardline-aware plugin only; Clarion core and non-Wardline-aware plugins are
+  unaffected. *Retirement condition*: Wardline ships a stable runtime probe
+  API.
+- **Wardline state-file ingest deferred to a future release (tracked under
+  `release:v1.1`).** Only the `wardline.core.registry.REGISTRY` version-pin
+  probe ships in v1.0; the state-file readers for `wardline.yaml` + overlays,
+  `wardline.fingerprint.json`, `wardline.exceptions.json`, the
+  `wardline.sarif.baseline.json` translator baseline, and the three-scheme
+  identity-reconciliation oracle (REQ-INTEG-WARDLINE-02 through -06) all land
+  with WP9-B / WP10.
+- **Pre-WP5 catalogue upgrade requirement.** Briefing-blocked annotations
+  are stored as a JSON property on file entities at v1.0 (v1.1 promotes
+  the field to a typed column). A v1.0 binary opening a `.clarion/clarion.db`
+  produced by a pre-WP5 binary finds no `briefing_blocked` properties —
+  pre-WP5 analyzers never wrote them — and will serve the entire catalogue
+  without refusal. Operators upgrading from a pre-WP5 install MUST run
+  `clarion analyze` (scanner active by default) against the project root
+  before exposing the HTTP read API or calling the `summary` MCP tool. See
+  [`docs/operator/secret-scanning.md`](docs/operator/secret-scanning.md#pre-wp5-catalogue-upgrade-requirement).
+
+### Documentation
+
+- Design ladder under [`docs/clarion/1.0/`](docs/clarion/1.0/) — `requirements.md`,
+  `system-design.md`, `detailed-design.md`.
+- ADRs under [`docs/clarion/adr/`](docs/clarion/adr/) — 28 Accepted at 1.0
+  (ADR-001…ADR-034 with the documented Backlog/Superseded subset excluded).
+  ADR-012 is superseded by ADR-014, whose Security
+  Posture and Error Envelope are in turn partially extended by ADR-034
+  for the Sprint 3 federation hardening. Four ADRs (ADR-009, ADR-010,
+  ADR-019, ADR-020) remain Backlog and are tracked inside
+  `system-design.md` §12 / `detailed-design.md` §11 until promoted.
+- Loom-suite doctrine at [`docs/suite/loom.md`](docs/suite/loom.md).
+- Federation contract surface at [`docs/federation/contracts.md`](docs/federation/contracts.md).
+- Operator guides under [`docs/operator/`](docs/operator/) — getting-started,
+  OpenRouter setup, HTTP read API.
+
+[Unreleased]: https://github.com/tachyon-beep/clarion/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/tachyon-beep/clarion/releases/tag/v1.0.0
diff --git a/CLAUDE.md b/CLAUDE.md
index edec3c26..24053847 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,9 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository state
 
-**Sprint 1 is closed.** The walking skeleton is tagged at `v0.1-sprint-1` (merge commit `48b9bb0` on `main`). All nine Sprint-1 lock-ins (L1–L9) are ratified; `clarion analyze` end-to-end persists `python:function:demo.hello|function` against a fixture project. See `docs/implementation/sprint-1/signoffs.md` for the closed Tier-A ladder.
+**v1.0.0 — first publishable release.** Targets the `v1.0.0` tag (cut once release blockers are green; pre-release working tags `v0.1-sprint-1` and `v0.1-sprint-2` remain in the repo as historical anchors). Workspace + Python plugin are at 1.0.0; ADR-014 federation HTTP read API ships with bearer auth, batch resolution, briefing-blocked propagation, and stable per-project `instance_id`. See [`CHANGELOG.md`](CHANGELOG.md) for the full 1.0 scope and [`docs/implementation/`](docs/implementation/) for sprint-closure artifacts.
 
-### Layout (post-Sprint-1)
+### Layout (post-1.0)
 
 - **Rust workspace** at repo root (`Cargo.toml`, `crates/`):
   - `crates/clarion-core/` — entity-ID assembler, plugin host (`plugin/host.rs`), JSON-RPC transport, manifest parser, jail + limits, discovery, breaker.
@@ -61,7 +61,7 @@ The Loom federation axiom in `docs/suite/loom.md` (especially §3–§5) is **lo
 
 Before proposing or accepting any change that adds a new dependency, "lightweight glue layer," shared registry, or cross-product mediator, run it against the §5 failure test (semantic / initialization / pipeline coupling). Centralisation creeps back in naturally; treat any "wouldn't it be easier if we just..." proposal as suspicious.
 
-Two named v0.1 asterisks (Wardline→Filigree pipeline coupling via Clarion; Python plugin's `wardline.core.registry.REGISTRY` import) have written retirement conditions in `loom.md` §5. Do not add new asterisks without the same.
+Two named asterisks (Wardline→Filigree pipeline coupling via Clarion; Python plugin's `wardline.core.registry.REGISTRY` import) have written retirement conditions in `loom.md` §5. Both persist into v1.0 and retire post-release per the conditions named there. Do not add new asterisks without the same discipline.
 
 ## Documentation map
 
@@ -71,21 +71,25 @@ docs/
 │   ├── briefing.md                5-minute introduction
 │   └── loom.md                    Founding doctrine, federation axiom, go/no-go test
 ├── clarion/
-│   ├── v0.1/                      Canonical product docset for the current version
+│   ├── 1.0/                       Canonical product docset for the 1.0 release
+│   │   ├── README.md              Reading-order map for the design ladder
 │   │   ├── requirements.md        The WHAT — REQ-/NFR-/CON-/NG- IDs, baselined
 │   │   ├── system-design.md       The HOW — architecture, mechanisms, §2–§11 with `Addresses:` headers
-│   │   ├── detailed-design.md     Implementation reference — schemas, rule catalogs, appendices
-│   │   ├── plans/                 Scope memo (v0.1-scope-commitments.md)
-│   │   └── reviews/               Retained historical reviews (supporting context, not normative)
-│   └── adr/                       Authored architecture decision records (ADR-001 … ADR-022)
-└── implementation/                Work-package sequencing (lives ABOVE v0.1/ because WPs span siblings)
+│   │   └── detailed-design.md     Implementation reference — schemas, rule catalogs, appendices
+│   └── adr/                       Authored architecture decision records (ADR-001 … ADR-031)
+├── federation/                    Cross-product wire contracts + normative fixtures
+│   ├── contracts.md               Pinned HTTP read API + auth + path-normalization
+│   └── fixtures/                  Normative request/response fixtures
+└── implementation/                Work-package sequencing (lives ABOVE the docset because WPs span siblings)
     ├── v0.1-plan.md               11 WPs in dependency order, with anchoring docs/ADRs per WP
-    └── sprint-1/                  Per-sprint execution plan (walking-skeleton: WP1+WP2+WP3)
+    ├── sprint-1/                  Walking-skeleton sprint (WP1+WP2+WP3)
+    ├── sprint-2/                  B-track + scanner sprint
+    └── sprint-3/                  Loom federation hardening sprint (ADR-014)
 ```
 
 ### Reading order by intent
 
-- **New to the project**: `docs/suite/briefing.md` → `docs/suite/loom.md` → `docs/clarion/v0.1/README.md`.
+- **New to the project**: `docs/suite/briefing.md` → `docs/suite/loom.md` → `docs/clarion/1.0/README.md`.
 - **Implementing**: `requirements.md` → `system-design.md` → `detailed-design.md` → relevant ADRs → the WP doc under `docs/implementation/`.
 - **Reviewing a design proposal**: read the requirement IDs it cites, then the system-design section listed in those requirements' `See` lines, then check whether any Accepted ADR already constrains the answer.
 
@@ -93,11 +97,11 @@ docs/
 
 When the same fact appears in multiple files, this is the precedence:
 
-1. **Accepted ADRs** in `docs/clarion/adr/` — the locked decisions. 16 are Accepted at v0.1; six remain Backlog and are tracked inside `system-design.md` §12 / `detailed-design.md` §11 until promoted.
+1. **Accepted ADRs** in `docs/clarion/adr/` — the locked decisions. 28 are Accepted at 1.0 (ADR-001…ADR-007, ADR-011, ADR-013…ADR-018, ADR-021…ADR-034); four remain Backlog (ADR-009, ADR-010, ADR-019, ADR-020) and are tracked inside `system-design.md` §12 / `detailed-design.md` §11 until promoted. ADR-012 was superseded by ADR-014 (which is in turn partially extended by ADR-034 for the federation read-API security posture and error envelope).
 2. **`requirements.md`** — REQ-/NFR-/CON-/NG- IDs are stable and load-bearing (filigree issues and commit messages cite them by ID; never reuse a retired ID).
 3. **`system-design.md`** — `Addresses:` headers on each §2–§11 section define the requirement acceptance surface for that subsystem.
 4. **`detailed-design.md`** — exact schemas, rule catalogues, appendices.
-5. Reviews under `docs/clarion/v0.1/reviews/` are supporting context only, not normative. Do not cite a review as the source of a current decision; cite the ADR or design doc that absorbed it.
+5. Reviews under `docs/clarion/1.0/reviews/` are supporting context only, not normative. Do not cite a review as the source of a current decision; cite the ADR or design doc that absorbed it.
 
 If `requirements.md` and `system-design.md` disagree, the requirement wins and the design doc is the bug. If an ADR exists, it overrides both.
 
@@ -128,18 +132,23 @@ Avoid: "Loom platform," "Loom runtime," "Loom broker," "Loom store" — Loom is
 
 `filigree` is the issue tracker for this project (config in `.filigree/`, MCP server registered in `.mcp.json`). The global `~/CLAUDE.md` file describes the workflow and CLI/MCP commands; do not duplicate that here. Project-specific notes:
 
-- Sprint 1 issues (`WP1`, `WP2`, `WP3`, Sprint-1-close) are all `delivered`/`closed`. Sprint 2 issues should follow the same `release:v0.1`, `sprint:N`, `wp:N`, `adr:NNN` label scheme.
+- Sprint 1 / Sprint 2 / Sprint 3 issues are all `delivered`/`closed` at 1.0. Post-1.0 issues should follow the same `release:1.0`-style label scheme using whatever release tag (`release:1.1`, `release:2.0`) the work targets.
 - Filigree issue bodies should cite `REQ-*` / `NFR-*` / ADR IDs verbatim — those IDs are how design docs and tracker stay linked.
 
-### Live carryover from Sprint 1
+### Post-1.0 follow-up tracking
 
-These were filed during Sprint 1 with explicit deferral rationale and are ready for Sprint 2 triage:
+Open issues for the v1.0 known limitations and any post-release follow-ups live in `filigree` under the `release:1.1` (and beyond) label. `filigree get-ready` / `filigree session-context` are authoritative for what's currently actionable. Notable themes:
 
-- `clarion-889200006a` (P3, sprint:2 / wp:9) — ADR-018 amendment: L7 qualname divergence with Wardline `FingerprintEntry`. Triggers when WP9 attempts the first cross-product join.
-- WP2 deferred items: `clarion-48c5d06578` (supervisor drain/discard), `clarion-928349b60f` (jail TOCTOU on briefing read), `clarion-35688034f0` (read_frame deadline), `clarion-c0977ac293` (RLIMIT_AS observed end-to-end), `clarion-adeff0916d` (fixture-binary self-build).
-- WP1 review-2 P2 bugs: `clarion-5e03cfdd21`, `clarion-ed5017139f`, `clarion-b5b1029f5a`, `clarion-4cd11905e2` — good Sprint-2 warm-up before Tier-B feature work.
+- **WP9-B (Filigree finding emission)** — deferred from 1.0 per the [Sprint 2 scope amendment](docs/implementation/sprint-2/scope-amendment-2026-05.md#4-v01-planmd-resequencing).
+- **HTTP file language manifest registry** — narrow core-extension fallback at 1.0; persistent registry is a post-1.0 task.
+- **HMAC inbound auth (C-4)** — HMAC (`X-Loom-Component: clarion:<hmac>`) is the
+  preferred non-loopback authentication mechanism in v1.0 per ADR-034,
+  configured via `serve.http.identity_token_env`. The legacy bearer-token path
+  (`serve.http.token_env`) remains supported for compatibility. Replay
+  protection (timestamp + nonce window) is ADR-034 forward-work tracked for
+  post-1.0 hardening.
 
-<!-- filigree:instructions:v2.0.3:d454f2c2 -->
+<!-- filigree:instructions:v2.1.0:9dff6e6d -->
 ## Filigree Issue Tracker
 
 `filigree` tracks tasks for this project. Data lives in `.filigree/`. Prefer
@@ -152,7 +161,7 @@ CLI otherwise.
 # At session start
 filigree session-context                            # ready / in-progress / critical path
 
-# Pick up the next ready issue (atomic claim + transition to in_progress)
+# Pick up the next startable issue (atomic claim + transition into its working status)
 filigree start-next-work --assignee <name>
 # ...or claim a specific issue
 filigree start-work <id> --assignee <name>
@@ -167,6 +176,15 @@ Use the atomic claim+transition verbs — `start_work` / `start_next_work`
 update — the two-step form races against other agents; the combined verb is
 atomic.
 
+**Ready ≠ startable.** The working status is type-specific (tasks →
+`in_progress`, features → `building`). Bugs start at `triage`, which has no
+single-hop transition into work (`triage → confirmed → fixing`), so a triage
+bug is *ready* but not directly *startable*: `start_work` on one returns
+`INVALID_TRANSITION` naming the next status, and `start_next_work` skips it.
+`get_ready` items carry a `startable` flag (plus a `next_action` hint when
+false). Pass `advance=true` (MCP) / `--advance` (CLI) to walk the soft
+transitions to the nearest working status automatically.
+
 ### Observations: when (and when not) to use them
 
 `observe` is a fire-and-forget scratchpad for *incidental* defects — things
@@ -202,6 +220,8 @@ either catalogue. The verbs you will reach for most:
 - **Find work:** `get_ready`, `get_blocked`, `list_issues`, `search_issues`
 - **Claim work:** `start_work`, `start_next_work`
 - **Update:** `add_comment`, `add_label`, `update_issue`, `close_issue`
+- **Admin (irreversible):** `delete_issue` (MCP) / `delete-issue` (CLI) —
+  hard-deletes a terminal issue and its rows; `undo_last` cannot reverse it.
 - **Scratchpad:** `observe`, `list_observations`, `promote_observation`, `dismiss_observation`
 - **Cross-product entity bindings (ADR-029):** `add_entity_association`,
   `remove_entity_association`, `list_entity_associations`,
@@ -219,14 +239,19 @@ either catalogue. The verbs you will reach for most:
   and `GET /api/entity-associations?entity_id=…`.
 - **Health:** `get_stats`, `get_metrics`, `get_mcp_status`
 
-Pass `--actor <name>` (CLI) so events attribute to your agent identity.
+Pass `--actor <name>` (CLI) so events attribute to your agent identity. It
+works in either position — before the verb (`filigree --actor X update …`) or
+after it (`filigree update … --actor X`); the post-verb value overrides the
+group-level one.
 
 ### Error handling
 
 Errors return `{error: str, code: ErrorCode, details?: dict}`. Switch on
 `code`, not on message text. Codes: `VALIDATION`, `NOT_FOUND`, `CONFLICT`,
 `INVALID_TRANSITION`, `PERMISSION`, `NOT_INITIALIZED`, `IO`,
-`INVALID_API_URL`, `STOP_FAILED`, `SCHEMA_MISMATCH`, `INTERNAL`.
+`INVALID_API_URL`, `FILE_REGISTRY_DISPLACED`, `REGISTRY_UNAVAILABLE`,
+`CLARION_REGISTRY_VERSION_MISMATCH`, `BRIEFING_BLOCKED`, `STOP_FAILED`,
+`SCHEMA_MISMATCH`, `INTERNAL`.
 
 On `INVALID_TRANSITION`, call `get_valid_transitions` (MCP) or
 `filigree transitions <id>` to see what the workflow allows from here.
diff --git a/Cargo.lock b/Cargo.lock
index 2a433f0e..7f47e6d7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -106,6 +106,17 @@ dependencies = [
  "wait-timeout",
 ]
 
+[[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -118,6 +129,61 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
+[[package]]
+name = "axum"
+version = "0.7.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edca88bc138befd0323b20752846e6587272d3b03b0343c8ea28a6f819e6e71f"
+dependencies = [
+ "async-trait",
+ "axum-core",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "rustversion",
+ "serde",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09f2bd6146b97ae3359fa0cc6d6b376d9539582c7b4220f041a33ec24c226199"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "rustversion",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
 [[package]]
 name = "base64"
 version = "0.22.1"
@@ -246,26 +312,32 @@ checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
 
 [[package]]
 name = "clarion-cli"
-version = "0.1.0-dev"
+version = "1.0.0"
 dependencies = [
  "anyhow",
  "assert_cmd",
+ "axum",
  "blake3",
  "clap",
  "clarion-core",
  "clarion-mcp",
  "clarion-plugin-fixture",
+ "clarion-scanner",
  "clarion-storage",
  "dotenvy",
+ "fs2",
  "ignore",
  "rusqlite",
  "serde",
  "serde_json",
  "serde_norway",
+ "sha1",
  "sha2",
  "tempfile",
  "time",
  "tokio",
+ "tower",
+ "tower-http",
  "tracing",
  "tracing-subscriber",
  "uuid",
@@ -274,7 +346,7 @@ dependencies = [
 
 [[package]]
 name = "clarion-core"
-version = "0.1.0-dev"
+version = "1.0.0"
 dependencies = [
  "nix",
  "reqwest",
@@ -284,15 +356,17 @@ dependencies = [
  "thiserror 1.0.69",
  "toml",
  "tracing",
+ "which",
 ]
 
 [[package]]
 name = "clarion-mcp"
-version = "0.1.0-dev"
+version = "1.0.0"
 dependencies = [
  "blake3",
  "clarion-core",
  "clarion-storage",
+ "nix",
  "reqwest",
  "rusqlite",
  "serde",
@@ -302,24 +376,40 @@ dependencies = [
  "thiserror 1.0.69",
  "time",
  "tokio",
+ "tracing",
+ "uuid",
 ]
 
 [[package]]
 name = "clarion-plugin-fixture"
-version = "0.1.0-dev"
+version = "1.0.0"
 dependencies = [
  "clarion-core",
  "nix",
  "serde_json",
 ]
 
+[[package]]
+name = "clarion-scanner"
+version = "1.0.0"
+dependencies = [
+ "regex",
+ "serde",
+ "serde_norway",
+ "sha1",
+ "tempfile",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "clarion-storage"
-version = "0.1.0-dev"
+version = "1.0.0"
 dependencies = [
+ "blake3",
  "clarion-core",
  "deadpool-sqlite",
  "rusqlite",
+ "serde",
  "serde_json",
  "tempfile",
  "thiserror 1.0.69",
@@ -491,6 +581,12 @@ version = "0.15.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b"
 
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -555,6 +651,16 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fs2"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "futures-channel"
 version = "0.3.32"
@@ -712,6 +818,15 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
 
+[[package]]
+name = "home"
+version = "0.5.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "http"
 version = "1.4.0"
@@ -751,6 +866,12 @@ version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
 [[package]]
 name = "hyper"
 version = "1.9.0"
@@ -764,6 +885,7 @@ dependencies = [
  "http",
  "http-body",
  "httparse",
+ "httpdate",
  "itoa",
  "pin-project-lite",
  "smallvec",
@@ -1005,6 +1127,12 @@ dependencies = [
  "vcpkg",
 ]
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -1038,12 +1166,24 @@ dependencies = [
  "regex-automata",
 ]
 
+[[package]]
+name = "matchit"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e7465ac9959cc2b1404e8e2367b43684a6d13790fe23056cc8c6c5a6b7bcb94"
+
 [[package]]
 name = "memchr"
 version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
+[[package]]
+name = "mime"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
+
 [[package]]
 name = "mio"
 version = "1.2.0"
@@ -1312,6 +1452,18 @@ dependencies = [
  "getrandom 0.3.4",
 ]
 
+[[package]]
+name = "regex"
+version = "1.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "regex-automata"
 version = "0.4.14"
@@ -1403,6 +1555,19 @@ version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
 
+[[package]]
+name = "rustix"
+version = "0.38.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.4.15",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -1412,7 +1577,7 @@ dependencies = [
  "bitflags",
  "errno",
  "libc",
- "linux-raw-sys",
+ "linux-raw-sys 0.12.1",
  "windows-sys 0.61.2",
 ]
 
@@ -1578,6 +1743,17 @@ dependencies = [
  "unsafe-libyaml-norway",
 ]
 
+[[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+
 [[package]]
 name = "serde_spanned"
 version = "0.6.9"
@@ -1599,6 +1775,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "sha1"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -1705,7 +1892,7 @@ dependencies = [
  "fastrand",
  "getrandom 0.4.2",
  "once_cell",
- "rustix",
+ "rustix 1.1.4",
  "windows-sys 0.61.2",
 ]
 
@@ -1856,6 +2043,19 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-util"
+version = "0.7.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "pin-project-lite",
+ "tokio",
+]
+
 [[package]]
 name = "toml"
 version = "0.8.23"
@@ -1908,8 +2108,10 @@ dependencies = [
  "pin-project-lite",
  "sync_wrapper",
  "tokio",
+ "tokio-util",
  "tower-layer",
  "tower-service",
+ "tracing",
 ]
 
 [[package]]
@@ -1923,10 +2125,12 @@ dependencies = [
  "futures-util",
  "http",
  "http-body",
+ "http-body-util",
  "pin-project-lite",
  "tower",
  "tower-layer",
  "tower-service",
+ "tracing",
  "url",
 ]
 
@@ -1948,6 +2152,7 @@ version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
+ "log",
  "pin-project-lite",
  "tracing-attributes",
  "tracing-core",
@@ -2253,6 +2458,34 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "which"
+version = "6.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ee928febd44d98f2f459a4a79bd4d928591333a494a10a868418ac1b39cf1f"
+dependencies = [
+ "either",
+ "home",
+ "rustix 0.38.44",
+ "winsafe",
+]
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -2262,6 +2495,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
@@ -2433,6 +2672,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "winsafe"
+version = "0.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d135d17ab770252ad95e9a872d365cf3090e3be864a34ab46f48555993efc904"
+
 [[package]]
 name = "wit-bindgen"
 version = "0.46.0"
diff --git a/Cargo.toml b/Cargo.toml
index 4e6faf8e..97033673 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -6,13 +6,14 @@ members = [
     "crates/clarion-cli",
     "crates/clarion-mcp",
     "crates/clarion-plugin-fixture",
+    "crates/clarion-scanner",
 ]
 
 [workspace.package]
-version = "0.1.0-dev"
+version = "1.0.0"
 edition = "2024"
-license = "MIT OR Apache-2.0"
-repository = "https://github.com/qacona/clarion"
+license = "MIT"
+repository = "https://github.com/tachyon-beep/clarion"
 rust-version = "1.88"
 
 [workspace.lints.rust]
@@ -31,24 +32,31 @@ missing_errors_doc = "allow"
 
 [workspace.dependencies]
 anyhow = "1"
+axum = "0.7"
 blake3 = "1.8.5"
 clap = { version = "4", features = ["derive"] }
 deadpool-sqlite = { version = "0.8", features = ["rt_tokio_1"] }
 dotenvy = "0.15"
+fs2 = "0.4"
 ignore = "0.4"
-rusqlite = { version = "0.31", features = ["bundled"] }
+rusqlite = { version = "0.31", features = ["bundled", "backup"] }
 reqwest = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls-native-roots"] }
+regex = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_norway = "0.9.42"
+sha1 = "0.10"
 sha2 = "0.10"
 thiserror = "1"
 time = { version = "0.3", features = ["formatting", "macros", "parsing"] }
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "sync", "time"] }
+tower = { version = "0.5", features = ["limit", "load-shed", "timeout"] }
+tower-http = { version = "0.6", features = ["catch-panic", "limit", "trace"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 uuid = { version = "1", features = ["v4"] }
 toml = "0.8"
+which = "6"
 xgraph = "2.0.0"
 assert_cmd = "2"
 tempfile = "3"
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000..0b875485
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morrissey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..d872f828
--- /dev/null
+++ b/README.md
@@ -0,0 +1,145 @@
+# Clarion
+
+Clarion is a code-archaeology tool. It ingests a codebase, extracts entities
+(functions, classes, modules) and their relationships (`contains`, `calls`,
+`references`), persists the structural graph to a local SQLite store, and serves
+the result to consult-mode LLM agents over MCP. A coding agent that would
+otherwise re-explore the tree on every question reaches Clarion first and asks a
+graph-aware tool. v1.0 ships a Rust core plus a Python language plugin; other
+languages land in v2.0+.
+
+Part of the [Loom suite](docs/suite/loom.md) of code-archaeology, issue-tracking,
+and trust-topology tools.
+
+## Status
+
+**v1.0 — first publishable release.** Scope:
+
+- **Python only.** Other-language plugins (`NG-15`) are v2.0+ scope.
+- **Structural extraction + on-demand LLM summarisation.** `clarion analyze`
+  walks the corpus and persists entities + edges; `summary(id)` over MCP
+  dispatches the LLM lazily, one entity at a time.
+- **Local-first.** No mandatory cloud component; the only required network
+  egress is the LLM provider during `summary` calls.
+- **Filigree finding emission deferred to v0.2.** Clarion v1.0 surfaces issues
+  attached to entities via its own `issues_for` MCP tool (the WP9-A binding);
+  cross-product POSTing of Clarion-generated findings into Filigree's intake is
+  WP9-B, deferred per the
+  [Sprint 2 scope amendment](docs/implementation/sprint-2/scope-amendment-2026-05.md#4-v01-planmd-resequencing).
+
+**Known v1.0 limitations:**
+
+- **HTTP file language inference uses stored plugin identity plus a narrow
+  core-extension fallback.** Plugin manifests already declare language and
+  extensions, but v1.0 does not persist a manifest language registry for the
+  `/api/v1/files` read path. This is tracked as post-v1.0 hardening.
+
+## What it does today
+
+`clarion serve` exposes eight MCP tools that a consult-mode agent calls instead
+of grep-and-read:
+
+| Tool | What it answers |
+|---|---|
+| `entity_at(file, line)` | "Which entity covers this source location?" |
+| `find_entity(pattern)` | "Find entities whose name or summary text matches X." |
+| `callers_of(id)` | "Who calls this function?" |
+| `execution_paths_from(id, max_depth)` | "Show me up to N hops of call paths starting here." |
+| `summary(id)` | "Give me a one-paragraph summary of this entity." (lazy LLM dispatch + cached) |
+| `issues_for(id)` | "What Filigree issues are attached to this entity?" |
+| `neighborhood(id)` | "Show callers, callees, container, contained entities, and references in one hop." |
+| `subsystem_members(id)` | "Which entities belong to this subsystem?" (clustering output) |
+
+## Quick start
+
+```bash
+# 1. Install from the v1.0 GitHub Release
+TAG=v1.0.0
+curl -L -o clarion-x86_64-unknown-linux-gnu.tar.gz \
+  "https://github.com/tachyon-beep/clarion/releases/download/${TAG}/clarion-x86_64-unknown-linux-gnu.tar.gz"
+tar xzf clarion-x86_64-unknown-linux-gnu.tar.gz
+install clarion-x86_64-unknown-linux-gnu/clarion ~/.local/bin/
+pipx install \
+  "https://github.com/tachyon-beep/clarion/releases/download/${TAG}/clarion-plugin-python-1.0.0.tar.gz"
+
+# 2. Initialise a project
+cd /path/to/your/python/repo
+clarion install --path .
+
+# 3. Walk the corpus and persist the structural graph
+clarion analyze
+
+# 4. Serve the graph over MCP for consult-mode agents
+clarion serve
+```
+
+`clarion analyze` works without any LLM credentials and is the fastest way to
+verify the install. `summary(id)` calls require `OPENROUTER_API_KEY` to be set
+(see [docs/operator/openrouter.md](docs/operator/openrouter.md)).
+
+A full walkthrough — installing on a fresh machine, running against a small
+public Python project, connecting an MCP client, and asking three questions — is
+in [docs/operator/getting-started.md](docs/operator/getting-started.md).
+
+## Project layout
+
+```
+crates/                 Rust workspace
+├── clarion-core/       Entity-ID assembler, plugin host, manifest parser
+├── clarion-storage/    Writer-actor + reader-pool over SQLite (ADR-011)
+├── clarion-scanner/    Pre-ingest secret scanner (ADR-013, WP5)
+├── clarion-cli/        The `clarion` binary (install, analyze, serve)
+└── clarion-mcp/        MCP server exposing the eight consult tools
+plugins/python/         Python language plugin (pyright-backed)
+docs/clarion/1.0/      Design ladder — requirements → system-design → detailed-design
+docs/clarion/adr/       Authored architecture decision records
+```
+
+For the design ladder start at
+[docs/clarion/1.0/README.md](docs/clarion/1.0/README.md). The full ADR index
+is at [docs/clarion/adr/README.md](docs/clarion/adr/README.md). The Loom
+federation doctrine that anchors every cross-product decision is in
+[docs/suite/loom.md](docs/suite/loom.md).
+
+## Storage and operations
+
+Clarion v1.0 keeps all state in a project-local `.clarion/` directory.
+The local-first storage model, the no-NFS constraint, the no-double-analyze
+constraint (fs2 advisory lock), and the v1.0 backup/restore procedure are
+documented in
+[docs/clarion/1.0/operations.md](docs/clarion/1.0/operations.md).
+
+## Contributing
+
+Read [CLAUDE.md](CLAUDE.md) for repository conventions, work-package
+vocabulary, and where canonical truth lives. The CI floor every PR must clear
+is fixed by [ADR-023](docs/clarion/adr/ADR-023-tooling-baseline.md):
+
+```bash
+# Rust gates
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --workspace --bins
+cargo nextest run --workspace --all-features
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
+cargo deny check
+
+# Python gates (run from repo root)
+plugins/python/.venv/bin/ruff check plugins/python
+plugins/python/.venv/bin/ruff format --check plugins/python
+plugins/python/.venv/bin/mypy --strict plugins/python
+plugins/python/.venv/bin/pytest plugins/python
+
+# End-to-end
+bash tests/e2e/sprint_1_walking_skeleton.sh
+```
+
+Pre-commit hooks at [.pre-commit-config.yaml](.pre-commit-config.yaml) wire
+ruff + ruff-format + mypy on every `git commit`. Install with
+`plugins/python/.venv/bin/pre-commit install`.
+
+## License
+
+[MIT](LICENSE). Matches the `license = "MIT"` declaration in
+[`Cargo.toml`](Cargo.toml). Contributions are accepted under the same terms
+unless explicitly stated otherwise by the contributor.
diff --git a/clarion.yaml b/clarion.yaml
new file mode 100644
index 00000000..c32a210b
--- /dev/null
+++ b/clarion.yaml
@@ -0,0 +1,44 @@
+# clarion.yaml — user-edited config.
+# Do not delete this file: clarion serve reads MCP, LLM, and integration
+# settings from here when present.
+version: 1
+llm_policy:
+  enabled: false
+  provider: openrouter
+  allow_live_provider: false
+  openrouter:
+    endpoint_url: https://openrouter.ai/api/v1
+    api_key_env: OPENROUTER_API_KEY
+    attribution:
+      referer: https://github.com/tachyon-beep/clarion
+      title: Clarion
+  codex_cli:
+    executable: codex
+    model: null
+    profile: null
+    sandbox: read-only
+    timeout_seconds: 300
+  claude_cli:
+    executable: claude
+    model: null
+    permission_mode: plan
+    tools: []
+    timeout_seconds: 300
+    max_turns: 2
+    no_session_persistence: true
+    exclude_dynamic_system_prompt_sections: true
+  model_id: anthropic/claude-sonnet-4.6
+  session_token_ceiling: 1000000
+  max_inferred_edges_per_caller: 8
+  cache_max_age_days: 180
+integrations:
+  filigree:
+    enabled: false
+    base_url: http://127.0.0.1:8766
+    actor: clarion-mcp
+    token_env: FILIGREE_API_TOKEN
+    timeout_seconds: 5
+serve:
+  http:
+    enabled: false
+    bind: 127.0.0.1:9111
diff --git a/crates/clarion-cli/Cargo.toml b/crates/clarion-cli/Cargo.toml
index 2bd97d1c..cc0e6419 100644
--- a/crates/clarion-cli/Cargo.toml
+++ b/crates/clarion-cli/Cargo.toml
@@ -15,12 +15,15 @@ path = "src/main.rs"
 
 [dependencies]
 anyhow.workspace = true
+axum.workspace = true
 blake3.workspace = true
 clap.workspace = true
-clarion-core = { path = "../clarion-core", version = "0.1.0-dev" }
-clarion-mcp = { path = "../clarion-mcp", version = "0.1.0-dev" }
-clarion-storage = { path = "../clarion-storage", version = "0.1.0-dev" }
+clarion-core = { path = "../clarion-core", version = "1.0.0" }
+clarion-mcp = { path = "../clarion-mcp", version = "1.0.0" }
+clarion-scanner = { path = "../clarion-scanner", version = "1.0.0" }
+clarion-storage = { path = "../clarion-storage", version = "1.0.0" }
 dotenvy.workspace = true
+fs2.workspace = true
 ignore.workspace = true
 rusqlite.workspace = true
 serde.workspace = true
@@ -29,6 +32,8 @@ serde_norway.workspace = true
 sha2.workspace = true
 time.workspace = true
 tokio.workspace = true
+tower.workspace = true
+tower-http.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true
 uuid.workspace = true
@@ -36,7 +41,8 @@ xgraph.workspace = true
 
 [dev-dependencies]
 assert_cmd.workspace = true
-clarion-plugin-fixture = { path = "../clarion-plugin-fixture", version = "0.1.0-dev" }
+clarion-plugin-fixture = { path = "../clarion-plugin-fixture", version = "1.0.0" }
 rusqlite.workspace = true
 serde_json.workspace = true
+sha1.workspace = true
 tempfile.workspace = true
diff --git a/crates/clarion-cli/src/analyze.rs b/crates/clarion-cli/src/analyze.rs
index 21d44329..4397e25c 100644
--- a/crates/clarion-cli/src/analyze.rs
+++ b/crates/clarion-cli/src/analyze.rs
@@ -12,6 +12,8 @@
 use std::collections::{BTreeMap, BTreeSet};
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
 
 use anyhow::{Context, Result, bail};
 use ignore::{DirEntry, WalkBuilder};
@@ -30,27 +32,128 @@ use clarion_storage::{
     module_dependency_edges,
 };
 
+use clarion_mcp::config::McpConfig;
+use clarion_mcp::filigree::FiligreeHttpClient;
+use clarion_mcp::filigree_url::resolve_filigree_url;
+use clarion_mcp::scan_results::{
+    CLARION_SCAN_SOURCE, CleanStaleRequest, CleanStaleResponse, EmitOptions, ScanResultsResponse,
+    clean_stale_url, prepare_batch, scan_results_url,
+};
+
 use crate::clustering::{ClusterConfig, ModuleEdge, ModuleGraph, cluster_hash, cluster_modules};
 use crate::config::{AnalyzeConfig, ClusteringConfig};
 use crate::stats::P95Accumulator;
 
 const WEAK_MODULARITY_RULE_ID: &str = "CLA-FACT-CLUSTERING-WEAK-MODULARITY";
 
+/// Writes structured run progress to a JSON file for the MCP `analyze_status`
+/// tool (clarion-7e0c21558a). A no-op unless `analyze_start` passed a
+/// `--progress-file` path, so the normal CLI path pays nothing. Each write
+/// stamps a fresh `heartbeat_at`, letting a reader tell "still making progress"
+/// from "stalled" without scraping logs. Writes are best-effort and
+/// last-write-wins via an atomic temp-file rename; a failed write is logged and
+/// dropped (progress is advisory, never run-fatal).
+struct ProgressReporter {
+    inner: Option<ProgressInner>,
+}
+
+struct ProgressInner {
+    path: PathBuf,
+    run_id: String,
+    pid: u32,
+    total_files: AtomicU64,
+    processed_files: AtomicU64,
+}
+
+impl ProgressReporter {
+    fn new(progress_file: Option<PathBuf>, run_id: String) -> Self {
+        Self {
+            inner: progress_file.map(|path| ProgressInner {
+                path,
+                run_id,
+                pid: std::process::id(),
+                total_files: AtomicU64::new(0),
+                processed_files: AtomicU64::new(0),
+            }),
+        }
+    }
+
+    /// Record the total file count discovered for the run (denominator for
+    /// `processed_files`).
+    fn set_total(&self, total: u64) {
+        if let Some(inner) = &self.inner {
+            inner.total_files.store(total, Ordering::Relaxed);
+        }
+    }
+
+    /// Write a snapshot for a phase boundary (`discovering`, `analyzing`,
+    /// `clustering`). `current_plugin`/`current_file` are `None` between
+    /// plugins.
+    fn phase(&self, phase: &str, current_plugin: Option<&str>, current_file: Option<&str>) {
+        let Some(inner) = &self.inner else {
+            return;
+        };
+        let snapshot = serde_json::json!({
+            "run_id": inner.run_id,
+            "pid": inner.pid,
+            "phase": phase,
+            "current_plugin": current_plugin,
+            "current_file": current_file,
+            "processed_files": inner.processed_files.load(Ordering::Relaxed),
+            "total_files": inner.total_files.load(Ordering::Relaxed),
+            "heartbeat_at": iso8601_now(),
+        });
+        self.write_atomic(&snapshot);
+    }
+
+    /// Snapshot at the start of a file (so `current_file` reflects in-flight
+    /// work); the file is counted as processed by [`Self::file_completed`].
+    fn file_started(&self, plugin_id: &str, file: &str) {
+        self.phase("analyzing", Some(plugin_id), Some(file));
+    }
+
+    /// Increment the processed-file counter after a file finishes.
+    fn file_completed(&self) {
+        if let Some(inner) = &self.inner {
+            inner.processed_files.fetch_add(1, Ordering::Relaxed);
+        }
+    }
+
+    fn write_atomic(&self, snapshot: &serde_json::Value) {
+        let Some(inner) = &self.inner else {
+            return;
+        };
+        let body = snapshot.to_string();
+        let tmp = inner.path.with_extension("json.tmp");
+        if let Err(err) = fs::write(&tmp, &body).and_then(|()| fs::rename(&tmp, &inner.path)) {
+            tracing::debug!(
+                error = %err,
+                path = %inner.path.display(),
+                "failed to write analyze progress snapshot (advisory; ignored)",
+            );
+        }
+    }
+}
+
 // ── Public entry point ────────────────────────────────────────────────────────
 
 #[derive(Debug, Clone, Default)]
 pub(crate) struct AnalyzeOptions {
     pub(crate) config_path: Option<PathBuf>,
-}
-
-/// Run the analyze command against `project_path`.
-///
-/// # Errors
-///
-/// Returns an error if the target directory does not exist, has no `.clarion/`
-/// directory, or if the writer actor fails to start or process commands.
-pub async fn run(project_path: PathBuf) -> Result<()> {
-    run_with_options(project_path, AnalyzeOptions::default()).await
+    pub(crate) secret_scan: crate::secret_scan::SecretScanOptions,
+    /// Caller-supplied run id (MCP `analyze_start`); `None` generates one.
+    pub(crate) run_id: Option<String>,
+    /// `--resume RUN_ID` (REQ-FINDING-05): reopen this prior run's row instead
+    /// of opening a fresh one, and emit findings with `mark_unseen=false` so a
+    /// re-emit does not flip the prior run's findings to `unseen_in_latest` on
+    /// the Filigree peer. Takes precedence over `run_id` as the run identifier.
+    pub(crate) resume_run_id: Option<String>,
+    /// `--prune-unseen` (REQ-FINDING-06): after emission, ask Filigree to
+    /// soft-archive its stale `unseen_in_latest` Clarion findings. Enrich-only:
+    /// a failure or a disabled integration never fails the run.
+    pub(crate) prune_unseen: bool,
+    /// When set, structured progress is written here as the run proceeds.
+    pub(crate) progress_file: Option<PathBuf>,
 }
 
 /// Run the analyze command against `project_path` with resolved CLI options.
@@ -79,6 +182,12 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
         );
     }
     let db_path = clarion_dir.join("clarion.db");
+
+    // Cross-process advisory lock (STO-01). Must outlive the writer-actor's
+    // `handle.await` at the bottom of this function — see the drop-order
+    // note on `AnalyzeLockGuard`. Drop on function exit releases the lock.
+    let _analyze_lock = crate::analyze_lock::acquire_analyze_lock(&clarion_dir)?;
+
     let analyze_config = AnalyzeConfig::load(&project_root, options.config_path.as_deref())?;
     let analyze_config_json = analyze_config.to_json_string()?;
 
@@ -90,19 +199,22 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
     )
     .map_err(|e| anyhow::anyhow!("{e}"))
     .context("spawn writer actor")?;
-    let run_id = Uuid::new_v4().to_string();
+    // `--resume RUN_ID` reuses the prior run's id (and reopens its row below);
+    // absent that, the hidden MCP `--run-id` is honoured, else a fresh id.
+    let resume = options.resume_run_id.is_some();
+    let run_id = options
+        .resume_run_id
+        .clone()
+        .or_else(|| options.run_id.clone())
+        .unwrap_or_else(|| Uuid::new_v4().to_string());
     let started_at = iso8601_now();
-
-    writer
-        .send_wait(|ack| WriterCmd::BeginRun {
-            run_id: run_id.clone(),
-            config_json: analyze_config_json.clone(),
-            started_at: started_at.clone(),
-            ack,
-        })
-        .await
-        .map_err(|e| anyhow::anyhow!("{e}"))
-        .context("BeginRun")?;
+    // Structured progress sink (MCP `analyze_start` sets `progress_file`); a
+    // no-op when absent so the normal CLI path is unchanged.
+    let progress = Arc::new(ProgressReporter::new(
+        options.progress_file.clone(),
+        run_id.clone(),
+    ));
+    progress.phase("discovering", None, None);
 
     // ── Discover plugins ──────────────────────────────────────────────────────
     let discovery_results = discover();
@@ -138,6 +250,14 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
                 discovery_errors.join("; ")
             );
             tracing::error!(run_id = %run_id, reason = %reason, "failing run: discovery errors");
+            crate::run_lifecycle::open_run(
+                &writer,
+                resume,
+                &run_id,
+                &analyze_config_json,
+                &started_at,
+            )
+            .await?;
             let completed_at = iso8601_now();
             writer
                 .send_wait(|ack| WriterCmd::FailRun {
@@ -164,6 +284,8 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
         }
 
         tracing::warn!(run_id = %run_id, "no plugins discovered");
+        crate::run_lifecycle::open_run(&writer, resume, &run_id, &analyze_config_json, &started_at)
+            .await?;
         let completed_at = iso8601_now();
         writer
             .send_wait(|ack| WriterCmd::CommitRun {
@@ -214,6 +336,18 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
     // ── Walk the source tree (once, union of all extensions) ─────────────────
     let source_files = collect_source_files(&project_root, &wanted_extensions);
     tracing::info!(file_count = source_files.len(), "source tree walk complete");
+    progress.set_total(source_files.len() as u64);
+    progress.phase("analyzing", None, None);
+
+    let secret_scan_files = crate::secret_scan::collect_scan_files(&project_root, &source_files);
+    tracing::info!(
+        file_count = secret_scan_files.len(),
+        "secret scan file walk complete"
+    );
+    let mut secret_scan_outcome =
+        crate::secret_scan::pre_ingest(&project_root, &secret_scan_files, &options.secret_scan)?;
+    crate::run_lifecycle::open_run(&writer, resume, &run_id, &analyze_config_json, &started_at)
+        .await?;
 
     // ── Per-plugin processing ─────────────────────────────────────────────────
     //
@@ -242,7 +376,8 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
     let mut run_outcome: RunOutcome = RunOutcome::Completed;
     let mut breaker = CrashLoopBreaker::default();
     let mut crash_reasons: Vec<String> = Vec::new();
-
+    let briefing_blocks = secret_scan_outcome.briefing_blocks_shared();
+    let scanned_files = secret_scan_outcome.scanned_files_shared();
     'plugins: for plugin in plugins {
         let plugin_id = plugin.manifest.plugin.plugin_id.clone();
         let plugin_extensions: BTreeSet<String> = plugin
@@ -282,6 +417,9 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
         let pid_clone = plugin_id.clone();
         let exec_clone = plugin.executable.clone();
         let files_clone = plugin_files.clone();
+        let briefing_blocks_clone = Arc::clone(&briefing_blocks);
+        let scanned_files_clone = Arc::clone(&scanned_files);
+        let progress_clone = Arc::clone(&progress);
 
         // A JoinError here means the blocking task panicked (OOM, stack
         // overflow, internal unwrap, abort — anything that unwinds past the
@@ -299,6 +437,9 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
                     &pid_clone,
                     &exec_clone,
                     &files_clone,
+                    &briefing_blocks_clone,
+                    &scanned_files_clone,
+                    &progress_clone,
                 )
             })
             .await,
@@ -361,6 +502,7 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
                 // edge FK references resolve at insert time (B.3 §5).
                 let entity_count = entities.len() as u64;
                 let edge_count = edges.len() as u64;
+                secret_scan_outcome.remember_finding_anchors(&entities);
                 let mut insert_err: Option<anyhow::Error> = None;
                 for (id_str, record) in entities {
                     let res = writer
@@ -435,6 +577,17 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
         }
     }
 
+    if !matches!(run_outcome, RunOutcome::HardFailed { .. })
+        && let Err(e) = secret_scan_outcome
+            .persist_findings(&writer, &run_id, &project_root, &started_at)
+            .await
+    {
+        tracing::error!(run_id = %run_id, error = %e, "secret finding persistence failed");
+        run_outcome = RunOutcome::HardFailed {
+            reason: format!("secret finding persistence failed: {e:#}"),
+        };
+    }
+
     // ── Commit or fail the run ────────────────────────────────────────────────
     //
     // Writer-actor failures set `run_outcome = HardFailed` above (and break).
@@ -452,6 +605,7 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
         };
     }
 
+    progress.phase("clustering", None, None);
     let phase3_output = if matches!(run_outcome, RunOutcome::HardFailed { .. }) {
         Phase3Output::not_run()
     } else {
@@ -474,6 +628,48 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
         }
     };
 
+    // Phase 8 (WP9-B): emit findings to Filigree for non-hard-failed runs,
+    // before CommitRun so the emission outcome rides along in `stats.json`.
+    // Best-effort: a Filigree outage never changes the run's own outcome.
+    let filigree_emission = if matches!(
+        run_outcome,
+        RunOutcome::Completed | RunOutcome::SoftFailed { .. }
+    ) {
+        emit_findings_to_filigree(
+            &writer,
+            &db_path,
+            &project_root,
+            &run_id,
+            // `--resume` re-emits without marking the prior run's findings
+            // unseen (REQ-FINDING-05); a fresh run marks them unseen so a
+            // dropped finding transitions to `unseen_in_latest` on the peer.
+            !resume,
+            options.config_path.as_deref(),
+        )
+        .await
+    } else {
+        serde_json::Value::Null
+    };
+
+    // Phase 8b (WP9-B, REQ-FINDING-06): `--prune-unseen` retention sweep. Runs
+    // after emission for the same non-hard-failed outcomes, so a fresh run's
+    // `mark_unseen=true` has just (re)established the unseen set the sweep
+    // archives. Best-effort and enrich-only, exactly like emission.
+    let filigree_prune = if matches!(
+        run_outcome,
+        RunOutcome::Completed | RunOutcome::SoftFailed { .. }
+    ) {
+        prune_unseen_findings_in_filigree(
+            &project_root,
+            &run_id,
+            options.prune_unseen,
+            options.config_path.as_deref(),
+        )
+        .await
+    } else {
+        serde_json::Value::Null
+    };
+
     let completed_at = iso8601_now();
     // Snapshot the writer's process-lifetime dropped-edges counter so the
     // run's durable stats record the dedupe count (B.3 §6). Read BEFORE
@@ -497,7 +693,7 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
 
     match run_outcome {
         RunOutcome::Completed => {
-            let stats_json = serde_json::json!({
+            let mut stats_json = serde_json::json!({
                 "entities_inserted": total_entity_count,
                 "edges_inserted": total_edge_count,
                 "dropped_edges_total": dropped_edges_total,
@@ -513,8 +709,15 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
                 "pyright_index_parse_latency_p95_ms": pyright_index_parse_latency_p95_ms,
                 "extractor_parse_latency_p95_ms": extractor_parse_latency_p95_ms,
                 "clustering": phase3_output.clustering_stats.clone(),
-            })
-            .to_string();
+            });
+            secret_scan_outcome.augment_stats(&mut stats_json);
+            if !filigree_emission.is_null() {
+                stats_json["filigree_emission"] = filigree_emission;
+            }
+            if !filigree_prune.is_null() {
+                stats_json["filigree_prune"] = filigree_prune;
+            }
+            let stats_json = stats_json.to_string();
             writer
                 .send_wait(|ack| WriterCmd::CommitRun {
                     run_id: run_id.clone(),
@@ -532,7 +735,7 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
             // failed, atomically (writer folds the UPDATE into the open tx).
             // The stats JSON carries both fields so operators can see what
             // was persisted alongside the failure reason.
-            let stats_json = serde_json::json!({
+            let mut stats_json = serde_json::json!({
                 "entities_inserted": total_entity_count,
                 "edges_inserted": total_edge_count,
                 "dropped_edges_total": dropped_edges_total,
@@ -549,8 +752,15 @@ pub(crate) async fn run_with_options(project_path: PathBuf, options: AnalyzeOpti
                 "extractor_parse_latency_p95_ms": extractor_parse_latency_p95_ms,
                 "clustering": phase3_output.clustering_stats.clone(),
                 "failure_reason": reason,
-            })
-            .to_string();
+            });
+            secret_scan_outcome.augment_stats(&mut stats_json);
+            if !filigree_emission.is_null() {
+                stats_json["filigree_emission"] = filigree_emission;
+            }
+            if !filigree_prune.is_null() {
+                stats_json["filigree_prune"] = filigree_prune;
+            }
+            let stats_json = stats_json.to_string();
             writer
                 .send_wait(|ack| WriterCmd::CommitRun {
                     run_id: run_id.clone(),
@@ -966,6 +1176,307 @@ async fn insert_weak_modularity_finding(
     Ok(true)
 }
 
+/// Load the MCP-side config (Filigree integration) from the same `clarion.yaml`
+/// `clarion serve` reads. A missing or unparseable file falls back to the
+/// default (Filigree disabled), so a config problem never fails the run — it
+/// just means no emission.
+fn load_mcp_config(project_root: &Path, config_path: Option<&Path>) -> McpConfig {
+    let path = config_path.map_or_else(|| project_root.join("clarion.yaml"), Path::to_path_buf);
+    if !path.exists() {
+        return McpConfig::default();
+    }
+    McpConfig::from_path(&path).unwrap_or_else(|err| {
+        tracing::warn!(
+            path = %path.display(),
+            error = %err,
+            "load MCP config for finding emission failed; emission disabled",
+        );
+        McpConfig::default()
+    })
+}
+
+/// Phase 8 (WP9-B, REQ-FINDING-03): POST this run's persisted findings to
+/// Filigree's native `POST /api/v1/scan-results` intake.
+///
+/// Best-effort and enrich-only: gated behind
+/// `integrations.filigree.{enabled,emit_findings}`, and any failure (Filigree
+/// down, transport error, build error) is recorded in the returned stats blob
+/// and logged as `CLA-INFRA-FILIGREE-UNREACHABLE` rather than propagated — the
+/// analyze run never fails because a sibling tool is unreachable. Returns
+/// [`serde_json::Value::Null`] when emission is disabled; otherwise a
+/// `filigree_emission` stats object folded into `stats.json`.
+///
+/// Findings written during the run (including the phase-3 weak-modularity fact)
+/// are flushed before reading so the emission batch is complete.
+async fn emit_findings_to_filigree(
+    writer: &Writer,
+    db_path: &Path,
+    project_root: &Path,
+    run_id: &str,
+    mark_unseen: bool,
+    config_path: Option<&Path>,
+) -> serde_json::Value {
+    let mcp_config = load_mcp_config(project_root, config_path);
+    let filigree_cfg = &mcp_config.integrations.filigree;
+    if !filigree_cfg.enabled || !filigree_cfg.emit_findings {
+        return serde_json::Value::Null;
+    }
+
+    // Make findings durable so a fresh read connection observes them.
+    if let Err(err) = writer
+        .send_wait(|ack| WriterCmd::FlushRunBatch { ack })
+        .await
+    {
+        tracing::warn!(run_id, error = %err, "flush before finding emission failed; skipping emission");
+        return serde_json::json!({"status": "skipped", "reason": "flush_failed"});
+    }
+
+    let rows = match Connection::open(db_path) {
+        Ok(conn) => match clarion_storage::findings_for_emit(&conn, run_id) {
+            Ok(rows) => rows,
+            Err(err) => {
+                tracing::warn!(run_id, error = %err, "read findings for emission failed; skipping emission");
+                return serde_json::json!({"status": "skipped", "reason": "read_failed"});
+            }
+        },
+        Err(err) => {
+            tracing::warn!(run_id, error = %err, "open read conn for emission failed; skipping emission");
+            return serde_json::json!({"status": "skipped", "reason": "read_open_failed"});
+        }
+    };
+    let total_findings = rows.len();
+
+    let batch = prepare_batch(
+        &rows,
+        &EmitOptions {
+            scan_run_id: Some(run_id.to_owned()),
+            mark_unseen,
+            complete_scan_run: true,
+        },
+    );
+    let emitted = batch.emitted;
+    let skipped_no_path = batch.skipped_no_path;
+
+    // Resolve the live Filigree URL (ephemeral port over stale config), the same
+    // resolution `clarion serve` and `project_status` use.
+    let resolution = resolve_filigree_url(filigree_cfg, project_root);
+    let mut resolved_cfg = filigree_cfg.clone();
+    if let Some(url) = resolution.resolved_url {
+        resolved_cfg.base_url = url;
+    }
+    let endpoint = scan_results_url(&resolved_cfg.base_url);
+
+    // `reqwest::blocking` builds and drops its own inner tokio runtime; doing
+    // that on a tokio worker — even inside `spawn_blocking`, which still carries
+    // an ambient runtime handle — panics on drop. Run the whole client
+    // lifecycle (build → POST → drop) on a plain OS thread with no ambient
+    // runtime, and join it off the async executor.
+    let request = batch.request;
+    let thread_cfg = resolved_cfg;
+    let worker = std::thread::spawn(move || -> Result<ScanResultsResponse, String> {
+        let client = FiligreeHttpClient::from_config(&thread_cfg, |name| std::env::var(name).ok())
+            .map_err(|err| format!("build Filigree client: {err}"))?
+            .ok_or_else(|| "Filigree integration disabled".to_owned())?;
+        client
+            .post_scan_results(&request)
+            .map_err(|err| err.to_string())
+    });
+    let joined = tokio::task::spawn_blocking(move || worker.join()).await;
+
+    match joined {
+        Ok(Ok(Ok(response))) => {
+            for warning in &response.warnings {
+                tracing::warn!(run_id, warning = %warning, "Filigree scan-results intake warning");
+            }
+            tracing::info!(
+                run_id,
+                endpoint = %endpoint,
+                emitted,
+                skipped_no_path,
+                created = response.findings_created,
+                updated = response.findings_updated,
+                warnings = response.warnings.len(),
+                "posted findings to Filigree",
+            );
+            serde_json::json!({
+                "status": "emitted",
+                "endpoint": endpoint,
+                "findings_total": total_findings,
+                "emitted": emitted,
+                "skipped_no_path": skipped_no_path,
+                "mark_unseen": mark_unseen,
+                "findings_created": response.findings_created,
+                "findings_updated": response.findings_updated,
+                "warnings": response.warnings,
+            })
+        }
+        Ok(Ok(Err(err))) => unreachable_stats(
+            run_id,
+            &endpoint,
+            total_findings,
+            emitted,
+            skipped_no_path,
+            &err,
+        ),
+        Ok(Err(_panic)) => unreachable_stats(
+            run_id,
+            &endpoint,
+            total_findings,
+            emitted,
+            skipped_no_path,
+            "emission thread panicked",
+        ),
+        Err(err) => unreachable_stats(
+            run_id,
+            &endpoint,
+            total_findings,
+            emitted,
+            skipped_no_path,
+            &format!("emission task: {err}"),
+        ),
+    }
+}
+
+/// Build the `filigree_emission` stats blob for a failed POST and log it as
+/// `CLA-INFRA-FILIGREE-UNREACHABLE`. The infra finding is recorded in
+/// `stats.json` and the log (two of the three surfaces REQ-ANALYZE-06 names);
+/// the local `findings` table is not used because its `entity_id` is a
+/// non-null FK to `entities` and an infra finding has no anchor entity — the
+/// same reason every other `CLA-INFRA-*` finding is log-only today.
+fn unreachable_stats(
+    run_id: &str,
+    endpoint: &str,
+    total_findings: usize,
+    emitted: usize,
+    skipped_no_path: usize,
+    error: &str,
+) -> serde_json::Value {
+    tracing::warn!(
+        run_id,
+        endpoint,
+        rule_id = "CLA-INFRA-FILIGREE-UNREACHABLE",
+        error,
+        "could not post findings to Filigree; continuing (enrich-only)",
+    );
+    serde_json::json!({
+        "status": "unreachable",
+        "rule_id": "CLA-INFRA-FILIGREE-UNREACHABLE",
+        "endpoint": endpoint,
+        "findings_total": total_findings,
+        "emitted_attempted": emitted,
+        "skipped_no_path": skipped_no_path,
+        "error": error,
+    })
+}
+
+/// `--prune-unseen` retention sweep (WP9-B, REQ-FINDING-06): asks Filigree to
+/// soft-archive its own `unseen_in_latest` Clarion findings older than the
+/// configured age. Returns [`serde_json::Value::Null`] when not requested;
+/// otherwise a `filigree_prune` stats object folded into `stats.json`. Like
+/// emission, this is enrich-only — a disabled integration or a Filigree outage
+/// is recorded in stats, never fails the run. `scan_source` scoping is enforced
+/// by Filigree, so the sweep can only touch Clarion's findings.
+async fn prune_unseen_findings_in_filigree(
+    project_root: &Path,
+    run_id: &str,
+    prune_unseen: bool,
+    config_path: Option<&Path>,
+) -> serde_json::Value {
+    if !prune_unseen {
+        return serde_json::Value::Null;
+    }
+    let mcp_config = load_mcp_config(project_root, config_path);
+    let filigree_cfg = &mcp_config.integrations.filigree;
+    if !filigree_cfg.enabled {
+        tracing::info!(
+            run_id,
+            "--prune-unseen requested but Filigree integration disabled; skipping"
+        );
+        return serde_json::json!({"status": "skipped", "reason": "filigree_disabled"});
+    }
+    let older_than_days = filigree_cfg.prune_unseen_days;
+
+    // Resolve the live Filigree URL (ephemeral port over stale config), the
+    // same resolution emission uses.
+    let resolution = resolve_filigree_url(filigree_cfg, project_root);
+    let mut resolved_cfg = filigree_cfg.clone();
+    if let Some(url) = resolution.resolved_url {
+        resolved_cfg.base_url = url;
+    }
+    let endpoint = clean_stale_url(&resolved_cfg.base_url);
+    let request = CleanStaleRequest {
+        scan_source: CLARION_SCAN_SOURCE.to_owned(),
+        older_than_days,
+        actor: resolved_cfg.actor.clone(),
+    };
+
+    // Same blocking-reqwest-on-a-plain-OS-thread dance as emission: build → POST
+    // → drop the client off the tokio executor so the inner runtime drop is safe.
+    let thread_cfg = resolved_cfg;
+    let worker = std::thread::spawn(move || -> Result<CleanStaleResponse, String> {
+        let client = FiligreeHttpClient::from_config(&thread_cfg, |name| std::env::var(name).ok())
+            .map_err(|err| format!("build Filigree client: {err}"))?
+            .ok_or_else(|| "Filigree integration disabled".to_owned())?;
+        client
+            .post_clean_stale(&request)
+            .map_err(|err| err.to_string())
+    });
+    let joined = tokio::task::spawn_blocking(move || worker.join()).await;
+
+    match joined {
+        Ok(Ok(Ok(response))) => {
+            tracing::info!(
+                run_id,
+                endpoint = %endpoint,
+                findings_fixed = response.findings_fixed,
+                older_than_days,
+                "pruned unseen findings in Filigree",
+            );
+            serde_json::json!({
+                "status": "pruned",
+                "endpoint": endpoint,
+                "findings_fixed": response.findings_fixed,
+                "older_than_days": older_than_days,
+            })
+        }
+        Ok(Ok(Err(err))) => prune_unreachable_stats(run_id, &endpoint, older_than_days, &err),
+        Ok(Err(_panic)) => {
+            prune_unreachable_stats(run_id, &endpoint, older_than_days, "prune thread panicked")
+        }
+        Err(err) => prune_unreachable_stats(
+            run_id,
+            &endpoint,
+            older_than_days,
+            &format!("prune task: {err}"),
+        ),
+    }
+}
+
+/// Build the `filigree_prune` stats blob for a failed sweep and log it as
+/// `CLA-INFRA-FILIGREE-UNREACHABLE` — the enrich-only degrade, identical in
+/// spirit to [`unreachable_stats`] for emission.
+fn prune_unreachable_stats(
+    run_id: &str,
+    endpoint: &str,
+    older_than_days: u32,
+    error: &str,
+) -> serde_json::Value {
+    tracing::warn!(
+        run_id,
+        endpoint,
+        rule_id = "CLA-INFRA-FILIGREE-UNREACHABLE",
+        error,
+        "could not prune unseen findings in Filigree; continuing (enrich-only)",
+    );
+    serde_json::json!({
+        "status": "unreachable",
+        "rule_id": "CLA-INFRA-FILIGREE-UNREACHABLE",
+        "endpoint": endpoint,
+        "older_than_days": older_than_days,
+        "error": error,
+    })
+}
+
 fn module_entity_ids(conn: &Connection) -> Result<Vec<String>> {
     let mut stmt = conn
         .prepare("SELECT id FROM entities WHERE kind = 'module' ORDER BY id")
@@ -1164,15 +1675,20 @@ type Collected = (
 /// via `child.kill()` + `child.wait()`. `std::process::Child::Drop` does NOT
 /// kill or reap on Unix, so discarding `child` without `wait()` would leak a
 /// zombie into the kernel process table per spawn.
+#[allow(clippy::too_many_lines)]
 fn run_plugin_blocking(
     manifest: clarion_core::Manifest,
     project_root: &Path,
     plugin_id: &str,
     executable: &Path,
     files: &[PathBuf],
+    briefing_blocks: &Arc<BTreeMap<PathBuf, clarion_core::BriefingBlockReason>>,
+    scanned_source_files: &Arc<BTreeSet<PathBuf>>,
+    progress: &ProgressReporter,
 ) -> Result<BatchResult, PluginRunError> {
     use clarion_core::PluginHost;
 
+    let manifest_language = manifest.plugin.language.clone();
     let (mut host, mut child) =
         PluginHost::spawn(manifest, project_root, executable).map_err(|e| match e {
             HostError::Spawn(msg) => {
@@ -1185,6 +1701,8 @@ fn run_plugin_blocking(
                 PluginRunError::new(format!("plugin {plugin_id} spawn/handshake error: {other}"))
             }
         })?;
+    host.set_briefing_blocks(Arc::clone(briefing_blocks));
+    host.set_scanned_source_files(Arc::clone(scanned_source_files));
 
     let work_result: Result<Collected, String> = (|| {
         let mut collected_entities: Vec<(String, EntityRecord)> = Vec::new();
@@ -1192,6 +1710,7 @@ fn run_plugin_blocking(
         let mut collected_unresolved_call_sites: Vec<PendingUnresolvedCallSites> = Vec::new();
         let mut collected_stats = BatchStats::default();
         for file in files {
+            progress.file_started(plugin_id, &file.to_string_lossy());
             let AnalyzeFileOutcome {
                 entities,
                 edges,
@@ -1199,6 +1718,7 @@ fn run_plugin_blocking(
             } = host
                 .analyze_file(file)
                 .map_err(|e| classify_host_error(plugin_id, e))?;
+            progress.file_completed();
             collected_stats.unresolved_call_sites_total += stats.unresolved_call_sites_total;
             collected_stats.reference_sites_total += stats.reference_sites_total;
             collected_stats.references_resolved_total += stats.references_resolved_total;
@@ -1223,6 +1743,16 @@ fn run_plugin_blocking(
                 .find(|entity| entity.kind == "module")
                 .map(|entity| entity.id.to_string());
             let mut file_entities: Vec<(String, EntityRecord)> = Vec::new();
+            let (file_entity_id, file_record) = core_file_entity_record(
+                project_root,
+                file,
+                &manifest_language,
+                briefing_blocks,
+                scanned_source_files,
+            )
+            .map_err(|e| format!("core file entity for {}: {e:#}", file.display()))?;
+            file_entities.push((file_entity_id.clone(), file_record.clone()));
+            collected_entities.push((file_entity_id, file_record));
             for entity in &entities {
                 let id_str = entity.id.to_string();
                 let record = map_entity_to_record(entity, plugin_id, source_file_id.clone());
@@ -1496,6 +2026,118 @@ fn absolute_from_import_submodule_target(
         .then_some(candidate)
 }
 
+fn core_file_entity_record(
+    project_root: &Path,
+    file: &Path,
+    manifest_language: &str,
+    briefing_blocks: &BTreeMap<PathBuf, clarion_core::BriefingBlockReason>,
+    scanned_source_files: &BTreeSet<PathBuf>,
+) -> Result<(String, EntityRecord)> {
+    let canonical_root = project_root
+        .canonicalize()
+        .with_context(|| format!("canonicalize project root {}", project_root.display()))?;
+    let canonical_file = file
+        .canonicalize()
+        .with_context(|| format!("canonicalize source file {}", file.display()))?;
+    let relative = canonical_file
+        .strip_prefix(&canonical_root)
+        .with_context(|| {
+            format!(
+                "source file {} is outside project root {}",
+                canonical_file.display(),
+                canonical_root.display()
+            )
+        })?;
+    let qualified_name = project_relative_posix(relative)?;
+    let id = clarion_core::entity_id::entity_id("core", "file", &qualified_name)?.to_string();
+    let briefing_blocked = briefing_blocks.get(&canonical_file).copied().or_else(|| {
+        (!scanned_source_files.contains(&canonical_file))
+            .then_some(clarion_core::BriefingBlockReason::UnscannedSource)
+    });
+    let source_file_path = canonical_file
+        .into_os_string()
+        .into_string()
+        .map_err(|path| {
+            anyhow::anyhow!("source file path is not valid UTF-8: {}", path.display())
+        })?;
+    let short_name = Path::new(&source_file_path)
+        .file_name()
+        .and_then(|name| name.to_str())
+        .unwrap_or(&qualified_name)
+        .to_owned();
+    let content_hash = fs::read(&source_file_path)
+        .with_context(|| format!("read source file {source_file_path}"))
+        .map(|bytes| blake3::hash(&bytes).to_hex().to_string())?;
+    let mut properties = serde_json::Map::new();
+    properties.insert(
+        "language".to_owned(),
+        serde_json::Value::String(manifest_language.to_owned()),
+    );
+    if let Some(reason) = briefing_blocked {
+        properties.insert(
+            "briefing_blocked".to_owned(),
+            serde_json::Value::String(reason.as_str().to_owned()),
+        );
+    }
+    let properties_json = serde_json::Value::Object(properties).to_string();
+    let now = iso8601_now();
+
+    Ok((
+        id.clone(),
+        EntityRecord {
+            id,
+            plugin_id: "core".to_owned(),
+            kind: "file".to_owned(),
+            name: qualified_name,
+            short_name,
+            parent_id: None,
+            source_file_id: None,
+            source_file_path: Some(source_file_path),
+            source_byte_start: None,
+            source_byte_end: None,
+            source_line_start: None,
+            source_line_end: None,
+            properties_json,
+            content_hash: Some(content_hash),
+            summary_json: None,
+            wardline_json: None,
+            first_seen_commit: None,
+            last_seen_commit: None,
+            created_at: now.clone(),
+            updated_at: now,
+        },
+    ))
+}
+
+fn project_relative_posix(path: &Path) -> Result<String> {
+    let mut parts = Vec::new();
+    for component in path.components() {
+        match component {
+            std::path::Component::Normal(part) => {
+                let part = part.to_str().ok_or_else(|| {
+                    anyhow::anyhow!(
+                        "source file path component is not valid UTF-8: {}",
+                        part.display()
+                    )
+                })?;
+                parts.push(part);
+            }
+            std::path::Component::CurDir => {}
+            _ => {
+                bail!(
+                    "source file path is not project-relative: {}",
+                    path.display()
+                );
+            }
+        }
+    }
+    let relative = parts.join("/");
+    if relative.is_empty() {
+        bail!("source file path must not resolve to the project root");
+    }
+    Ok(relative)
+}
+
 /// Map an `AcceptedEntity` to an `EntityRecord` for the writer-actor.
 fn map_entity_to_record(
     entity: &AcceptedEntity,
@@ -1822,6 +2464,51 @@ mod tests {
     use std::collections::BTreeSet;
     use std::fs;
 
+    #[test]
+    fn progress_reporter_is_noop_without_a_path() {
+        // No progress file → no panics, no writes; the normal CLI path.
+        let reporter = ProgressReporter::new(None, "run-x".to_owned());
+        reporter.set_total(10);
+        reporter.phase("analyzing", Some("python"), Some("a.py"));
+        reporter.file_started("python", "a.py");
+        reporter.file_completed();
+    }
+
+    #[test]
+    fn progress_reporter_writes_phase_and_counters_with_heartbeat() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let path = dir.path().join("runs").join("run-1.progress.json");
+        fs::create_dir_all(path.parent().unwrap()).unwrap();
+        let reporter = ProgressReporter::new(Some(path.clone()), "run-1".to_owned());
+
+        reporter.set_total(3);
+        reporter.file_started("python", "src/a.py");
+        reporter.file_completed();
+        reporter.file_started("python", "src/b.py");
+
+        let snapshot: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(&path).expect("progress file")).unwrap();
+        assert_eq!(snapshot["run_id"], "run-1");
+        assert_eq!(snapshot["phase"], "analyzing");
+        assert_eq!(snapshot["current_plugin"], "python");
+        assert_eq!(snapshot["current_file"], "src/b.py");
+        assert_eq!(snapshot["processed_files"], 1);
+        assert_eq!(snapshot["total_files"], 3);
+        assert!(
+            snapshot["heartbeat_at"]
+                .as_str()
+                .is_some_and(|s| !s.is_empty()),
+            "heartbeat_at must be a non-empty timestamp"
+        );
+
+        // A later phase write overwrites with the new phase (last-write-wins).
+        reporter.phase("clustering", None, None);
+        let snapshot: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(&path).expect("progress file")).unwrap();
+        assert_eq!(snapshot["phase"], "clustering");
+        assert!(snapshot["current_plugin"].is_null());
+    }
+
     #[test]
     fn subsystem_entity_id_rejects_invalid_hash_segment() {
         let err = subsystem_entity_id("bad:hash").expect_err("colon must be rejected");
diff --git a/crates/clarion-cli/src/analyze_lock.rs b/crates/clarion-cli/src/analyze_lock.rs
new file mode 100644
index 00000000..9108768d
--- /dev/null
+++ b/crates/clarion-cli/src/analyze_lock.rs
@@ -0,0 +1,148 @@
+//! Cross-process advisory lock for `clarion analyze`.
+//!
+//! Two concurrent `clarion analyze` processes against the same project
+//! corrupt the run-attribution graph: each opens its own writer-actor,
+//! each calls `BeginRun` (insert a fresh `runs` row in `status='running'`),
+//! and each races on entity/edge inserts under `SQLite` WAL. The in-process
+//! `ActorState::current_run` guard (clarion-storage `writer.rs`) prevents
+//! a single writer from issuing two `BeginRun`s; it does nothing across
+//! processes.
+//!
+//! This module acquires an exclusive `fs2`-advisory lock on a dedicated
+//! sentinel file `.clarion/clarion.lock` for the duration of the analyze
+//! run. The lock file is separate from `clarion.db` so `SQLite`'s own
+//! locking (per-connection, transaction-scoped) is independent. The
+//! guard's `Drop` releases the OS-level lock.
+
+use std::fs::{File, OpenOptions};
+use std::path::Path;
+
+use anyhow::{Context, Result, bail};
+use fs2::FileExt;
+
+const LOCK_FILE_NAME: &str = "clarion.lock";
+
+/// RAII guard holding the analyze lock. Drop releases the OS lock.
+///
+/// **Drop order is load-bearing.** The guard must outlive the writer-actor's
+/// `JoinHandle::await` in `analyze::run_with_options`; otherwise a second
+/// `clarion analyze` can grab the lock while writer-actor 1's final
+/// transaction is still landing through WAL. `fs2`'s `File` impl unlocks
+/// on file close, so dropping the `File` releases the OS lock; we rely on
+/// Drop rather than an explicit unlock so panic and happy paths behave
+/// identically.
+#[must_use = "Drop releases the analyze lock — bind to a named variable"]
+#[derive(Debug)]
+pub(crate) struct AnalyzeLockGuard {
+    _file: File,
+}
+
+/// Acquire an exclusive cross-process lock on `<clarion_dir>/clarion.lock`.
+///
+/// `clarion_dir` is the `.clarion/` directory inside the project root. The
+/// lock file is created on first use (0-byte sentinel) and kept across
+/// runs. The returned guard holds the lock for its lifetime.
+///
+/// # Errors
+///
+/// - The lock file cannot be opened (missing `.clarion/` directory,
+///   permission denied, filesystem read-only).
+/// - Another `clarion analyze` process already holds the lock. Returns
+///   an error containing the lock-file path so the operator can identify
+///   the conflict.
+pub(crate) fn acquire_analyze_lock(clarion_dir: &Path) -> Result<AnalyzeLockGuard> {
+    let lock_path = clarion_dir.join(LOCK_FILE_NAME);
+    let file = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .open(&lock_path)
+        .with_context(|| format!("open analyze lock file {}", lock_path.display()))?;
+
+    match file.try_lock_exclusive() {
+        Ok(()) => Ok(AnalyzeLockGuard { _file: file }),
+        Err(err) => {
+            // fs2 returns ErrorKind::WouldBlock when another process holds
+            // the lock; anything else is a real IO failure (e.g. NFS
+            // without lockd). Surface both with the path so operators can
+            // identify the conflict.
+            let kind = err.kind();
+            if kind == std::io::ErrorKind::WouldBlock {
+                bail!(
+                    "another `clarion analyze` is already in progress against this project \
+                     (lock held on {}). Wait for it to finish, or remove the lock file if \
+                     no other process is running.",
+                    lock_path.display()
+                );
+            }
+            Err(err).with_context(|| {
+                format!(
+                    "acquire exclusive lock on {} (filesystem may not support advisory locks)",
+                    lock_path.display()
+                )
+            })
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Two concurrent `acquire_analyze_lock` calls on the same `.clarion/`
+    /// directory must fail the second call. This is the core STO-01
+    /// invariant: a second analyze cannot start while the first holds
+    /// the writer.
+    #[test]
+    fn second_acquire_fails_while_first_held() {
+        let tmp = tempfile::tempdir().unwrap();
+        let clarion_dir = tmp.path();
+
+        let first = acquire_analyze_lock(clarion_dir).expect("first acquire");
+        assert!(
+            clarion_dir.join(LOCK_FILE_NAME).exists(),
+            "lock file created on first acquire"
+        );
+
+        let err = acquire_analyze_lock(clarion_dir)
+            .expect_err("second acquire must fail while first guard is held");
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("another `clarion analyze`"),
+            "error must name the conflict explicitly: {msg}"
+        );
+        drop(first);
+    }
+
+    /// Releasing the first lock (dropping the guard) must let the second
+    /// acquire succeed. Guards the "we forgot to unlock on Drop" bug.
+    #[test]
+    fn second_acquire_succeeds_after_first_drops() {
+        let tmp = tempfile::tempdir().unwrap();
+        let clarion_dir = tmp.path();
+
+        {
+            let first = acquire_analyze_lock(clarion_dir).expect("first acquire");
+            drop(first);
+        } // lock released on drop
+
+        let second = acquire_analyze_lock(clarion_dir)
+            .expect("second acquire must succeed after first drops");
+        drop(second);
+    }
+
+    /// Missing `.clarion/` directory must surface as an IO error, not a
+    /// `WouldBlock` masquerade. (Operator may have skipped `clarion install`.)
+    #[test]
+    fn missing_clarion_dir_errors() {
+        let tmp = tempfile::tempdir().unwrap();
+        let nonexistent = tmp.path().join("missing-clarion-dir");
+        let err = acquire_analyze_lock(&nonexistent).expect_err("missing dir must error");
+        let msg = format!("{err:#}");
+        assert!(
+            msg.contains("open analyze lock file"),
+            "error must mention lock file open path: {msg}"
+        );
+    }
+}
diff --git a/crates/clarion-cli/src/cli.rs b/crates/clarion-cli/src/cli.rs
index 859631e8..60d725a2 100644
--- a/crates/clarion-cli/src/cli.rs
+++ b/crates/clarion-cli/src/cli.rs
@@ -11,7 +11,12 @@ pub struct Cli {
 
 #[derive(Subcommand)]
 pub enum Command {
-    /// Initialise .clarion/ in the current directory.
+    /// Initialise .clarion/ and/or install agent-orientation assets.
+    ///
+    /// Bare `clarion install` initialises .clarion/ only (refuses if it
+    /// already exists). `--skills` and `--hooks` install the orientation
+    /// assets and do NOT initialise .clarion/. `--all` does init + skills +
+    /// hooks.
     Install {
         /// Overwrite an existing .clarion/ directory.
         #[arg(long)]
@@ -20,10 +25,26 @@ pub enum Command {
         /// Directory to install into (default: current directory).
         #[arg(long, default_value = ".")]
         path: PathBuf,
+
+        /// Install the bundled clarion-workflow skill pack into
+        /// .claude/skills/ and .agents/skills/.
+        #[arg(long)]
+        skills: bool,
+
+        /// Merge a `SessionStart` hook into .claude/settings.json.
+        #[arg(long)]
+        hooks: bool,
+
+        /// Do everything: .clarion/ init + --skills + --hooks.
+        #[arg(long)]
+        all: bool,
     },
 
-    /// Run an analysis pass. Sprint 1: no plugins are loaded; run status is
-    /// `skipped_no_plugins`. WP2 wires plugin spawning.
+    /// Run an analysis pass: walk the source tree, dispatch discovered plugins
+    /// to extract entities/edges, and persist results to `.clarion/clarion.db`.
+    /// Re-runs are idempotent (UPSERT on `entities.id`). If no plugins are on
+    /// `$PATH`, exits 0 with a WARN and status `skipped_no_plugins` — see
+    /// `docs/operator/getting-started.md` Troubleshooting.
     Analyze {
         /// Path to analyse (default: current directory).
         #[arg(default_value = ".")]
@@ -32,6 +53,49 @@ pub enum Command {
         /// Path to clarion.yaml (default: project-root/clarion.yaml if present).
         #[arg(long)]
         config: Option<PathBuf>,
+
+        /// Allow analysis of files containing unredacted secrets. Requires a
+        /// confirmation step when detections are present.
+        #[arg(long)]
+        allow_unredacted_secrets: bool,
+
+        /// Non-TTY confirmation token for --allow-unredacted-secrets.
+        #[arg(long, value_name = "TOKEN", requires = "allow_unredacted_secrets")]
+        confirm_allow_unredacted_secrets: Option<String>,
+
+        /// Use this run id instead of generating one. Internal: set by the MCP
+        /// `analyze_start` tool so it can return the handle before the run
+        /// records its `runs` row. Hidden from `--help`.
+        #[arg(long, hide = true)]
+        run_id: Option<String>,
+
+        /// Resume a prior run: reuse `RUN_ID` (reopening its `runs` row instead
+        /// of starting fresh) and emit findings to Filigree with
+        /// `mark_unseen=false`, so re-emitting does not flip the prior run's
+        /// findings to `unseen_in_latest` on the peer (REQ-FINDING-05). The
+        /// run id is the UUID a normal `clarion analyze` reports on completion.
+        /// This re-walks the tree from scratch (it is not incremental recovery)
+        /// and assumes the corpus is unchanged; findings that no longer fire are
+        /// not pruned from the resumed run.
+        #[arg(long, value_name = "RUN_ID", conflicts_with = "run_id")]
+        resume: Option<String>,
+
+        /// After emitting findings, ask Filigree to soft-archive its own
+        /// `unseen_in_latest` Clarion findings older than
+        /// `integrations.filigree.prune_unseen_days` (default 30)
+        /// (REQ-FINDING-06). Opt-in retention sweep; enrich-only — a Filigree
+        /// outage or the integration being disabled never fails the run. The
+        /// sweep is `scan_source`-scoped server-side, so it only touches
+        /// Clarion's findings.
+        #[arg(long)]
+        prune_unseen: bool,
+
+        /// Write structured progress (phase, current plugin, processed/total
+        /// files, current file, heartbeat) to this path as the run proceeds,
+        /// so `analyze_status` can report progress without log scraping.
+        /// Internal: set by the MCP `analyze_start` tool. Hidden from `--help`.
+        #[arg(long, hide = true)]
+        progress_file: Option<PathBuf>,
     },
 
     /// Run the MCP stdio server.
@@ -44,4 +108,47 @@ pub enum Command {
         #[arg(long)]
         config: Option<PathBuf>,
     },
+
+    /// Agent-lifecycle hook entrypoints. Always exit 0 (fail-soft) so a
+    /// misbehaving hook never blocks session start.
+    Hook {
+        #[command(subcommand)]
+        command: HookCommand,
+    },
+
+    /// Local database maintenance.
+    Db {
+        #[command(subcommand)]
+        command: DbCommand,
+    },
+}
+
+#[derive(Subcommand)]
+pub enum DbCommand {
+    /// Take a consistent, WAL-safe online backup of `.clarion/clarion.db`.
+    ///
+    /// Unlike `cp`, this captures outstanding WAL frames into a standalone
+    /// single-file copy, so it is safe to run during a live `clarion analyze`.
+    Backup {
+        /// Destination file for the backup copy.
+        output: PathBuf,
+
+        /// Project directory containing .clarion/clarion.db (default: current).
+        #[arg(long, default_value = ".")]
+        path: PathBuf,
+
+        /// Overwrite the output file if it already exists.
+        #[arg(long)]
+        force: bool,
+    },
+}
+
+#[derive(Subcommand)]
+pub enum HookCommand {
+    /// Print a project snapshot and re-sync the skill pack on drift.
+    SessionStart {
+        /// Project directory containing .clarion/clarion.db.
+        #[arg(long, default_value = ".")]
+        path: PathBuf,
+    },
 }
diff --git a/crates/clarion-cli/src/db.rs b/crates/clarion-cli/src/db.rs
new file mode 100644
index 00000000..54bce6db
--- /dev/null
+++ b/crates/clarion-cli/src/db.rs
@@ -0,0 +1,135 @@
+//! `clarion db` maintenance subcommands.
+//!
+//! Currently a single verb: `backup`, an online, WAL-safe copy of
+//! `.clarion/clarion.db` (gap-register STO-04 / clarion-6d433b61ba).
+//!
+//! Why an online backup rather than `cp`: the live database runs in WAL mode,
+//! so committed pages live in `clarion.db-wal` separately from the main file.
+//! A naive file copy taken during a `clarion analyze` produces a *torn* copy —
+//! the main file without its outstanding WAL frames. `rusqlite::backup::Backup`
+//! reads through a real connection, so it captures a transactionally consistent
+//! snapshot and writes it into a fresh single-file database (no WAL sidecar to
+//! ship alongside).
+
+use std::path::Path;
+use std::time::Duration;
+
+use anyhow::{Context, Result, anyhow, bail, ensure};
+use rusqlite::{Connection, OpenFlags};
+
+/// Back up the project's `.clarion/clarion.db` to `output`.
+///
+/// The copy is taken with `rusqlite::backup::Backup` (a consistent online
+/// snapshot) and staged into a sibling temp file that is renamed over `output`
+/// only after the snapshot completes and passes `PRAGMA integrity_check`, so an
+/// interrupted backup never leaves a half-written file at the destination.
+///
+/// # Errors
+///
+/// Returns an error if the source database is missing, if `output` already
+/// exists and `force` is not set, if `output` resolves to the source database
+/// itself, or if the backup / integrity check fails.
+pub fn backup(project_root: &Path, output: &Path, force: bool) -> Result<()> {
+    let db_path = project_root.join(".clarion").join("clarion.db");
+    ensure!(
+        db_path.exists(),
+        "Clarion database not found at {}; run `clarion analyze` first",
+        db_path.display()
+    );
+
+    // Refuse to overwrite the live database — both the obvious same-path case
+    // and the canonicalized-alias case (symlink / `./` games).
+    if paths_are_same(&db_path, output) {
+        bail!("refusing to back up {} onto itself", db_path.display());
+    }
+
+    if output.exists() {
+        ensure!(
+            force,
+            "{} already exists; pass --force to overwrite",
+            output.display()
+        );
+    }
+
+    // Stage into a sibling temp file so a crash mid-copy can never leave a
+    // truncated file sitting at `output`. Renaming is atomic on the same
+    // filesystem; staging as a sibling keeps us on it.
+    let parent = output.parent().filter(|p| !p.as_os_str().is_empty());
+    if let Some(parent) = parent {
+        std::fs::create_dir_all(parent)
+            .with_context(|| format!("create backup output directory {}", parent.display()))?;
+    }
+    let staging = staging_path(output);
+    // Clear any stale staging file from a previous interrupted run.
+    if staging.exists() {
+        std::fs::remove_file(&staging)
+            .with_context(|| format!("clear stale staging file {}", staging.display()))?;
+    }
+
+    let result = run_backup(&db_path, &staging);
+    match result {
+        Ok(()) => {
+            std::fs::rename(&staging, output).with_context(|| {
+                format!(
+                    "rename backup {} -> {}",
+                    staging.display(),
+                    output.display()
+                )
+            })?;
+            println!("Backed up {} -> {}", db_path.display(), output.display());
+            Ok(())
+        }
+        Err(err) => {
+            // Best-effort cleanup so a failed run leaves no debris behind.
+            let _ = std::fs::remove_file(&staging);
+            Err(err)
+        }
+    }
+}
+
+/// Run the online backup into `staging`, then verify the copy is intact.
+fn run_backup(db_path: &Path, staging: &Path) -> Result<()> {
+    let src = Connection::open_with_flags(
+        db_path,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_URI,
+    )
+    .with_context(|| format!("open source database {}", db_path.display()))?;
+    let mut dst = Connection::open(staging)
+        .with_context(|| format!("open staging database {}", staging.display()))?;
+
+    {
+        let backup =
+            rusqlite::backup::Backup::new(&src, &mut dst).context("initialise online backup")?;
+        // Copy the whole database in steps of 256 pages with no pause between
+        // steps; the source is read-only so there is no writer to yield to.
+        backup
+            .run_to_completion(256, Duration::from_millis(0), None)
+            .context("run online backup to completion")?;
+    }
+
+    // Prove the copy is a structurally valid SQLite database before we promote
+    // it over `output`. integrity_check returns the single row "ok" on success.
+    let status: String = dst
+        .query_row("PRAGMA integrity_check", [], |row| row.get(0))
+        .context("integrity_check on backup copy")?;
+    if status != "ok" {
+        return Err(anyhow!("backup integrity_check failed: {status}"));
+    }
+    Ok(())
+}
+
+/// Sibling staging path for the atomic write (`<output>.clarion-backup.tmp-<pid>`).
+fn staging_path(output: &Path) -> std::path::PathBuf {
+    let mut name = output.as_os_str().to_os_string();
+    name.push(format!(".clarion-backup.tmp-{}", std::process::id()));
+    std::path::PathBuf::from(name)
+}
+
+/// True if both paths denote the same on-disk file. Falls back to a lexical
+/// comparison when a path does not yet exist (so it cannot be canonicalized).
+fn paths_are_same(a: &Path, b: &Path) -> bool {
+    match (a.canonicalize(), b.canonicalize()) {
+        (Ok(ca), Ok(cb)) => ca == cb,
+        _ => a == b,
+    }
+}
diff --git a/crates/clarion-cli/src/hook.rs b/crates/clarion-cli/src/hook.rs
new file mode 100644
index 00000000..0ebd114e
--- /dev/null
+++ b/crates/clarion-cli/src/hook.rs
@@ -0,0 +1,171 @@
+//! `clarion hook session-start` — fail-soft session-start orientation.
+//!
+//! Never returns an error to the caller: the `SessionStart` hook must never
+//! block an agent's session start. All failures degrade to a printed note.
+
+use std::path::Path;
+
+use clarion_mcp::snapshot::{ProjectSnapshot, Staleness, missing_db_snapshot, project_snapshot};
+use rusqlite::{Connection, OpenFlags};
+
+/// Run `clarion hook session-start`. Always returns `Ok(())`.
+///
+/// The `anyhow::Result` return type is intentional even though no `Err` is
+/// ever produced: it keeps the `main.rs` dispatch arm uniform with the other
+/// subcommands and documents the fail-soft contract at the type level.
+#[allow(clippy::unnecessary_wraps)]
+pub fn session_start(path: &Path) -> anyhow::Result<()> {
+    // (1) Re-sync the skill pack ONLY if it's already installed in at least one
+    //     skill root, and drifted. A bare session-start never bootstraps a
+    //     never-installed project — that's `clarion install --skills`'s job. Note
+    //     the resync normalises BOTH roots once triggered: if a project installed
+    //     only `.claude/skills`, a drift repair also (re)creates
+    //     `.agents/skills`, keeping the two roots in lock-step. A drift repair
+    //     keeps installed copies honest across upgrades.
+    resync_skill_if_present(path);
+
+    // (2) Snapshot.
+    let outcome = load_snapshot(path);
+    print_snapshot(path, &outcome);
+    Ok(())
+}
+
+/// What [`load_snapshot`] could establish about the `.clarion/` index.
+///
+/// A *missing* db and a *present-but-unreadable* db are deliberately distinct:
+/// the missing case nudges toward `install` + `analyze`, but that advice is
+/// wrong for a present-but-corrupt/locked db (`install` refuses while `.clarion/`
+/// exists; `analyze` cannot repair corruption). See [`print_snapshot`].
+enum SnapshotOutcome {
+    /// Either the db file is absent (a `missing_db_snapshot()`) or it opened and
+    /// read cleanly (a real [`project_snapshot`]).
+    Ready(ProjectSnapshot),
+    /// The db file is present but could not be opened or read back — corrupt,
+    /// locked by another process, or otherwise unreadable.
+    DbUnreadable,
+}
+
+fn resync_skill_if_present(project_root: &Path) {
+    let installed = project_root
+        .join(".claude/skills/clarion-workflow/SKILL.md")
+        .exists()
+        || project_root
+            .join(".agents/skills/clarion-workflow/SKILL.md")
+            .exists();
+    if !installed {
+        return;
+    }
+    if let Err(err) = crate::skill_pack::install_skill_pack(project_root) {
+        tracing::warn!(error = %err, "clarion-workflow skill resync failed");
+    }
+}
+
+fn load_snapshot(project_root: &Path) -> SnapshotOutcome {
+    let db_path = project_root.join(".clarion").join("clarion.db");
+    if !db_path.exists() {
+        return SnapshotOutcome::Ready(missing_db_snapshot());
+    }
+    let conn = match Connection::open_with_flags(&db_path, OpenFlags::SQLITE_OPEN_READ_ONLY) {
+        Ok(conn) => conn,
+        Err(err) => {
+            tracing::warn!(error = %err, "open .clarion/clarion.db read-only failed");
+            return SnapshotOutcome::DbUnreadable;
+        }
+    };
+    // `Connection::open_with_flags(.. READ_ONLY)` lazily succeeds even on a
+    // non-SQLite file ("NOT A SQLITE DB" opens fine); the corruption only
+    // surfaces at first read. Probe with a cheap query so a present-but-corrupt
+    // db is classified as unreadable rather than silently reported as 0 counts
+    // (which would otherwise print the wrong "no analysis yet" nudge).
+    if let Err(err) = conn.query_row("PRAGMA schema_version", [], |row| row.get::<_, i64>(0)) {
+        tracing::warn!(error = %err, "probe read of .clarion/clarion.db failed");
+        return SnapshotOutcome::DbUnreadable;
+    }
+    let root = project_root
+        .canonicalize()
+        .unwrap_or_else(|_| project_root.to_path_buf());
+    SnapshotOutcome::Ready(project_snapshot(&conn, &root))
+}
+
+fn print_snapshot(project_root: &Path, outcome: &SnapshotOutcome) {
+    let snapshot = match outcome {
+        SnapshotOutcome::Ready(snapshot) => snapshot,
+        SnapshotOutcome::DbUnreadable => {
+            let db_path = project_root.join(".clarion").join("clarion.db");
+            println!(
+                "Clarion: an index exists at {} but could not be opened (it may be \
+                 corrupt, locked by another process, or unreadable). Check permissions, \
+                 ensure no other clarion process holds it, or remove .clarion/ and re-run \
+                 `clarion install` + `clarion analyze`. (Run with RUST_LOG=warn for the \
+                 open error.)",
+                db_path.display()
+            );
+            return;
+        }
+    };
+    if !snapshot.db_present() {
+        println!(
+            "Clarion: no index at {}/.clarion/clarion.db. \
+             Run `clarion install --path {}` then `clarion analyze {}`.",
+            project_root.display(),
+            project_root.display(),
+            project_root.display()
+        );
+        return;
+    }
+    // Subsystems ARE entities (kind = 'subsystem'), so subsystem_count is a
+    // subset of entity_count, not a parallel category — say so, or the two read
+    // as disjoint (clarion-e4e80eff3f).
+    println!(
+        "Clarion index: {} entities (incl. {} subsystems), {} findings.",
+        snapshot.entity_count(),
+        snapshot.subsystem_count(),
+        snapshot.finding_count()
+    );
+    if snapshot.degraded() {
+        // A backing query folded to a safe default, so the counts above may
+        // understate a populated index. Distinct from the present-but-empty
+        // case (which is not degraded). Operator detail is in the warn log.
+        println!(
+            "Clarion: ⚠ snapshot is degraded — at least one index query failed and \
+             the counts above may be incomplete. (Run with RUST_LOG=warn for details.)"
+        );
+    }
+    match snapshot.staleness() {
+        Staleness::Fresh => {
+            println!(
+                "Index is fresh (last analyzed {}). Ask Clarion before re-exploring \
+                 the tree; see the clarion-workflow skill.",
+                snapshot.last_analyzed_at().unwrap_or("unknown")
+            );
+        }
+        Staleness::Stale => {
+            println!(
+                "Index may be stale: source files changed since the last run. \
+                 Run `clarion analyze {}` to refresh.",
+                project_root.display()
+            );
+        }
+        Staleness::NeverAnalyzed => {
+            println!(
+                "No analysis recorded yet. Run `clarion analyze {}` to build the index.",
+                project_root.display()
+            );
+        }
+        Staleness::NoSourcePaths => {
+            println!(
+                "Index freshness not checked: no ingested entity has a recorded \
+                 source path to compare against (last analyzed {}). The index is \
+                 present and queryable.",
+                snapshot.last_analyzed_at().unwrap_or("unknown")
+            );
+        }
+        Staleness::Unknown => {
+            println!(
+                "Index freshness unknown (a freshness check failed). If briefings \
+                 look empty, run `clarion analyze {}`.",
+                project_root.display()
+            );
+        }
+    }
+}
diff --git a/crates/clarion-cli/src/hooks_settings.rs b/crates/clarion-cli/src/hooks_settings.rs
new file mode 100644
index 00000000..f9ec62a3
--- /dev/null
+++ b/crates/clarion-cli/src/hooks_settings.rs
@@ -0,0 +1,546 @@
+//! `.claude/settings.json` SessionStart-hook merge.
+//!
+//! Merge semantics (never clobber): parse existing JSON and ensure a
+//! `SessionStart` matcher-group runs `clarion hook session-start --path
+//! <project>` (the project path POSIX-single-quote-escaped for the shell). If a
+//! Clarion-owned hook already runs the exact command, it is left untouched; a
+//! stale one (the old path-less form, or one pinned to a different project) is
+//! refreshed in place. Every other key is preserved.
+//!
+//! Verified against the Claude Code settings schema: `hooks.SessionStart` is an
+//! array of matcher-groups, each `{ "matcher"?, "hooks": [ {type,command} ] }`.
+
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, Result, bail};
+use serde_json::{Map, Value, json};
+
+/// Substring that identifies Clarion's own `SessionStart` hook command.
+pub const HOOK_COMMAND: &str = "clarion hook session-start";
+
+/// POSIX single-quote escaping for a value embedded in a shell command string.
+///
+/// Claude Code runs hook commands through a shell, so an embedded project path
+/// must be a single literal argument — never word-split or subject to `$`,
+/// backtick, or `\` expansion. Single quotes suppress all shell processing; the
+/// only character that can't appear inside them is `'` itself, which we close
+/// the quote for, emit an escaped `\'`, and reopen: `a'b` → `'a'\''b'`.
+fn shell_single_quote(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 2);
+    out.push('\'');
+    for ch in s.chars() {
+        if ch == '\'' {
+            out.push_str("'\\''");
+        } else {
+            out.push(ch);
+        }
+    }
+    out.push('\'');
+    out
+}
+
+/// Merge Clarion's `SessionStart` hook into a parsed settings `Value` in place,
+/// inserting the supplied `command` (which must contain [`HOOK_COMMAND`] so it
+/// is recognised as Clarion-owned). Returns `true` if a change was made.
+///
+/// Clarion-owned entries are keyed on the [`HOOK_COMMAND`] substring. If one
+/// already runs the exact `command`, this is a no-op (`false`). If a Clarion
+/// hook exists but differs (the old path-less form, or one pinned to a
+/// different project), it is refreshed in place to `command` (`true`) rather
+/// than no-oping forever or appending a duplicate. If none exists, the hook is
+/// appended (`true`).
+#[must_use]
+pub fn merge_session_start_hook(settings: &mut Value, command: &str) -> bool {
+    // Coercion-after-parse: a successfully-parsed but malformed shape (a wrong
+    // JSON type where we expect object/object/array) is rewritten to the
+    // default shape rather than erroring. This is correct, but surface it so a
+    // clobbered hand-authored shape is observable.
+    let mut coerced = false;
+
+    if !settings.is_object() {
+        *settings = Value::Object(Map::new());
+        coerced = true;
+    }
+    let obj = settings.as_object_mut().expect("settings is object");
+
+    let hooks = obj
+        .entry("hooks")
+        .or_insert_with(|| Value::Object(Map::new()));
+    if !hooks.is_object() {
+        *hooks = Value::Object(Map::new());
+        coerced = true;
+    }
+    let hooks = hooks.as_object_mut().expect("hooks is object");
+
+    let groups = hooks
+        .entry("SessionStart")
+        .or_insert_with(|| Value::Array(Vec::new()));
+    if !groups.is_array() {
+        *groups = Value::Array(Vec::new());
+        coerced = true;
+    }
+    let groups = groups.as_array_mut().expect("SessionStart is array");
+
+    if coerced {
+        tracing::warn!(
+            "malformed .claude/settings.json shape (non-object settings/hooks or \
+             non-array SessionStart) was rewritten to the expected shape before \
+             merging the clarion SessionStart hook"
+        );
+    }
+
+    // Classify existing Clarion-owned hooks (command contains HOOK_COMMAND).
+    // If one already equals `command`, we're current — no-op. Otherwise, if a
+    // stale Clarion hook exists (the old path-less form, or one pinned to a
+    // different project), refresh it in place rather than no-oping forever or
+    // appending a duplicate. Two passes keep the borrow checker happy and avoid
+    // mutating before we know whether a current entry exists elsewhere.
+    let mut found_current = false;
+    let mut stale_loc: Option<(usize, usize)> = None;
+    for (gi, group) in groups.iter().enumerate() {
+        let Some(inner) = group.get("hooks").and_then(Value::as_array) else {
+            continue;
+        };
+        for (hi, h) in inner.iter().enumerate() {
+            let Some(c) = h.get("command").and_then(Value::as_str) else {
+                continue;
+            };
+            if !c.contains(HOOK_COMMAND) {
+                continue;
+            }
+            if c == command {
+                found_current = true;
+            } else if stale_loc.is_none() {
+                stale_loc = Some((gi, hi));
+            }
+        }
+    }
+    if found_current {
+        return false;
+    }
+    if let Some((gi, hi)) = stale_loc {
+        groups[gi]["hooks"][hi]["command"] = Value::String(command.to_string());
+        return true;
+    }
+
+    groups.push(json!({
+        "hooks": [
+            {
+                "type": "command",
+                "command": command
+            }
+        ]
+    }));
+    true
+}
+
+/// Read `.claude/settings.json` under `project_root` (creating an empty object
+/// if absent), merge Clarion's `SessionStart` hook, and write it back
+/// pretty-printed. Returns `true` if the file changed.
+///
+/// # Errors
+///
+/// Returns an error if the existing file is present but unparseable, or if any
+/// directory create / read / write fails.
+pub fn install_session_start_hook(project_root: &Path) -> Result<bool> {
+    let claude_dir = project_root.join(".claude");
+    let settings_path = claude_dir.join("settings.json");
+
+    let mut settings: Value = if settings_path.exists() {
+        let raw = fs::read_to_string(&settings_path)
+            .with_context(|| format!("read {}", settings_path.display()))?;
+        if raw.trim().is_empty() {
+            Value::Object(Map::new())
+        } else {
+            serde_json::from_str(&raw)
+                .with_context(|| format!("parse {}", settings_path.display()))?
+        }
+    } else {
+        Value::Object(Map::new())
+    };
+
+    // Never-clobber on the write path. `merge_session_start_hook` will happily
+    // coerce a parseable-but-wrong-type shape (a top-level array, a non-object
+    // `hooks`, a non-array `SessionStart`) to the default shape — fine for the
+    // in-memory/unit-test callers, but on disk that would silently overwrite
+    // hand-authored user content. Refuse to rewrite such a file; preserve it.
+    if !settings.is_object() {
+        bail!(
+            "refusing to rewrite {}: top-level JSON is not an object (the file is \
+             preserved unchanged). Fix or remove it, then re-run.",
+            settings_path.display()
+        );
+    }
+    if let Some(hooks) = settings.get("hooks") {
+        if !hooks.is_object() {
+            bail!(
+                "refusing to rewrite {}: `hooks` is present but is not an object \
+                 (the file is preserved unchanged). Fix or remove it, then re-run.",
+                settings_path.display()
+            );
+        }
+        if let Some(session_start) = hooks.get("SessionStart")
+            && !session_start.is_array()
+        {
+            bail!(
+                "refusing to rewrite {}: `hooks.SessionStart` is present but is not \
+                 an array (the file is preserved unchanged). Fix or remove it, then \
+                 re-run.",
+                settings_path.display()
+            );
+        }
+    }
+
+    // Embed the resolved project path so the installed hook orients THIS
+    // project no matter what working directory Claude Code runs it from.
+    // `install::run` canonicalizes before calling, so `project_root` is already
+    // absolute; canonicalize defensively in case another caller is not. The
+    // path is POSIX-single-quote-escaped (not merely double-quoted) because
+    // Claude runs hook commands via a shell and the path may contain `$`,
+    // backticks, quotes, or backslashes.
+    let canonical = project_root
+        .canonicalize()
+        .unwrap_or_else(|_| project_root.to_path_buf());
+    let command = format!(
+        "clarion hook session-start --path {}",
+        shell_single_quote(&canonical.display().to_string())
+    );
+
+    let changed = merge_session_start_hook(&mut settings, &command);
+    if !changed {
+        return Ok(false);
+    }
+
+    fs::create_dir_all(&claude_dir).with_context(|| format!("mkdir {}", claude_dir.display()))?;
+    let serialized =
+        serde_json::to_string_pretty(&settings).context("serialize .claude/settings.json")?;
+
+    // Atomic write: stage into a sibling temp file in the same directory, then
+    // rename over the destination (same-filesystem atomic swap). This protects
+    // the user's hand-authored settings.json from truncation/corruption on a
+    // crash or concurrent install mid-write. Mirrors skill_pack::stage_and_swap.
+    let tmp = claude_dir.join(format!(".settings.json.tmp-{}", std::process::id()));
+    if let Err(err) = write_and_swap(&tmp, &settings_path, &serialized) {
+        let _ = fs::remove_file(&tmp);
+        return Err(err);
+    }
+    Ok(true)
+}
+
+fn write_and_swap(tmp: &Path, dest: &Path, serialized: &str) -> Result<()> {
+    fs::write(tmp, format!("{serialized}\n"))
+        .with_context(|| format!("write staging {}", tmp.display()))?;
+    fs::rename(tmp, dest)
+        .with_context(|| format!("rename {} -> {}", tmp.display(), dest.display()))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs;
+
+    use serde_json::json;
+
+    use super::{HOOK_COMMAND, install_session_start_hook, merge_session_start_hook};
+
+    const TEST_COMMAND: &str = "clarion hook session-start --path \"/some/project\"";
+
+    #[cfg(unix)]
+    fn sh_roundtrip(quoted: &str) -> String {
+        let out = std::process::Command::new("sh")
+            .arg("-c")
+            .arg(format!("printf %s {quoted}"))
+            .output()
+            .expect("run sh");
+        String::from_utf8(out.stdout).expect("utf8")
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn shell_quote_round_trips_metacharacters_through_a_real_shell() {
+        // The installed hook command is run by Claude through a shell. A path
+        // with shell metacharacters must survive as a single literal argument,
+        // never expanded or split. Double-quote wrapping (the prior form) lets
+        // $, backtick, and \ act; single-quote escaping does not. Prove the
+        // helper round-trips through `sh` exactly. (clarion review #5)
+        for s in [
+            "/plain/path",
+            "/with space/x",
+            "/we'ird/x",
+            "/$(touch pwned)/x",
+            "/back`tick`/x",
+            "/back\\slash/x",
+            "/dquote\"here/x",
+            "/a'b\"c$d`e/x",
+        ] {
+            assert_eq!(
+                sh_roundtrip(&super::shell_single_quote(s)),
+                s,
+                "shell_single_quote did not round-trip {s:?} through sh"
+            );
+        }
+    }
+
+    #[test]
+    fn adds_hook_to_empty_settings() {
+        let mut settings = json!({});
+        let changed = merge_session_start_hook(&mut settings, TEST_COMMAND);
+        assert!(changed, "should report a change");
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(groups.len(), 1);
+        let cmd = groups[0]["hooks"][0]["command"].as_str().unwrap();
+        assert!(cmd.contains(HOOK_COMMAND), "command was: {cmd}");
+        assert!(cmd.contains("--path"), "command should pin --path: {cmd}");
+        assert_eq!(groups[0]["hooks"][0]["type"], "command");
+    }
+
+    #[test]
+    fn is_idempotent_when_hook_already_present() {
+        let mut settings = json!({});
+        assert!(merge_session_start_hook(&mut settings, TEST_COMMAND));
+        // Second merge must be a no-op.
+        assert!(!merge_session_start_hook(&mut settings, TEST_COMMAND));
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(groups.len(), 1, "must not duplicate the hook");
+    }
+
+    #[test]
+    fn refreshes_a_stale_clarion_hook_in_place() {
+        // A previously-installed Clarion hook (e.g. the old path-less form, or
+        // one pinned to a different project) must be refreshed to the desired
+        // command on re-install, not left stale. The idempotency check keys on
+        // the HOOK_COMMAND substring, so a stale entry used to no-op forever.
+        // (clarion review #10)
+        let mut settings = json!({
+            "hooks": {"SessionStart": [
+                {"hooks": [{"type": "command", "command": "clarion hook session-start"}]}
+            ]}
+        });
+        let desired = "clarion hook session-start --path '/proj'";
+        let changed = merge_session_start_hook(&mut settings, desired);
+        assert!(changed, "a stale Clarion hook must be refreshed");
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(
+            groups.len(),
+            1,
+            "must refresh in place, not append a duplicate"
+        );
+        assert_eq!(
+            groups[0]["hooks"][0]["command"].as_str().unwrap(),
+            desired,
+            "stale hook command must be updated to the desired command"
+        );
+        // And a second merge with the now-current command is a no-op.
+        assert!(
+            !merge_session_start_hook(&mut settings, desired),
+            "re-merging the current command must be a no-op"
+        );
+    }
+
+    #[test]
+    fn preserves_unrelated_hooks_and_top_level_keys() {
+        let mut settings = json!({
+            "model": "opus",
+            "hooks": {
+                "Stop": [
+                    {"hooks": [{"type": "command", "command": "echo bye"}]}
+                ],
+                "SessionStart": [
+                    {"hooks": [{"type": "command", "command": "echo unrelated-greeting"}]}
+                ]
+            }
+        });
+
+        let changed = merge_session_start_hook(&mut settings, TEST_COMMAND);
+        assert!(changed);
+
+        assert_eq!(settings["model"], "opus");
+        assert_eq!(
+            settings["hooks"]["Stop"][0]["hooks"][0]["command"],
+            "echo bye"
+        );
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(groups.len(), 2, "must append, not replace");
+        let cmds: Vec<&str> = groups
+            .iter()
+            .flat_map(|g| g["hooks"].as_array().unwrap())
+            .map(|h| h["command"].as_str().unwrap())
+            .collect();
+        assert!(cmds.iter().any(|c| c.contains("unrelated-greeting")));
+        assert!(cmds.iter().any(|c| c.contains(HOOK_COMMAND)));
+    }
+
+    #[test]
+    fn install_errors_on_unparseable_existing_settings() {
+        let dir = tempfile::tempdir().unwrap();
+        let claude = dir.path().join(".claude");
+        fs::create_dir_all(&claude).unwrap();
+        fs::write(claude.join("settings.json"), "{not json").unwrap();
+
+        let result = install_session_start_hook(dir.path());
+        assert!(result.is_err(), "expected parse error, got {result:?}");
+    }
+
+    #[test]
+    fn install_refuses_to_rewrite_top_level_non_object_settings() {
+        let dir = tempfile::tempdir().unwrap();
+        let claude = dir.path().join(".claude");
+        std::fs::create_dir_all(&claude).unwrap();
+        // Parseable JSON, but a top-level array — hand-authored user content we must not clobber.
+        std::fs::write(claude.join("settings.json"), "[1, 2, 3]").unwrap();
+        let result = super::install_session_start_hook(dir.path());
+        assert!(
+            result.is_err(),
+            "should refuse to clobber a non-object settings.json"
+        );
+        // File must be untouched.
+        let raw = std::fs::read_to_string(claude.join("settings.json")).unwrap();
+        assert_eq!(raw.trim(), "[1, 2, 3]");
+    }
+
+    #[test]
+    fn install_refuses_to_rewrite_wrong_type_hooks() {
+        let dir = tempfile::tempdir().unwrap();
+        let claude = dir.path().join(".claude");
+        std::fs::create_dir_all(&claude).unwrap();
+        std::fs::write(
+            claude.join("settings.json"),
+            r#"{"hooks": "not-an-object"}"#,
+        )
+        .unwrap();
+        let result = super::install_session_start_hook(dir.path());
+        assert!(
+            result.is_err(),
+            "should refuse to clobber a wrong-type hooks value"
+        );
+    }
+
+    #[test]
+    fn install_refuses_to_rewrite_non_array_session_start() {
+        let dir = tempfile::tempdir().unwrap();
+        let claude = dir.path().join(".claude");
+        std::fs::create_dir_all(&claude).unwrap();
+        std::fs::write(
+            claude.join("settings.json"),
+            r#"{"hooks": {"SessionStart": "nope"}}"#,
+        )
+        .unwrap();
+        let result = super::install_session_start_hook(dir.path());
+        assert!(
+            result.is_err(),
+            "should refuse to clobber a non-array SessionStart value"
+        );
+        // File must be untouched.
+        let raw = std::fs::read_to_string(claude.join("settings.json")).unwrap();
+        assert_eq!(raw.trim(), r#"{"hooks": {"SessionStart": "nope"}}"#);
+    }
+
+    #[test]
+    fn installed_hook_command_embeds_resolved_project_path() {
+        let dir = tempfile::tempdir().unwrap();
+        super::install_session_start_hook(dir.path()).unwrap();
+        let raw = std::fs::read_to_string(dir.path().join(".claude/settings.json")).unwrap();
+        let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap();
+        let cmd = parsed["hooks"]["SessionStart"][0]["hooks"][0]["command"]
+            .as_str()
+            .unwrap();
+        assert!(cmd.contains("clarion hook session-start"), "cmd: {cmd}");
+        assert!(
+            cmd.contains("--path"),
+            "installed hook must pin --path: {cmd}"
+        );
+        // The path must reference this project's directory, not be path-less.
+        let canon = dir.path().canonicalize().unwrap();
+        assert!(
+            cmd.contains(&canon.display().to_string()),
+            "cmd should contain {} : {cmd}",
+            canon.display()
+        );
+    }
+
+    #[test]
+    fn install_is_idempotent_on_disk() {
+        let dir = tempfile::tempdir().unwrap();
+
+        // First install writes and reports a change.
+        assert!(install_session_start_hook(dir.path()).unwrap());
+        // Second install is a no-op (no write, no change).
+        assert!(!install_session_start_hook(dir.path()).unwrap());
+
+        let raw = fs::read_to_string(dir.path().join(".claude/settings.json")).unwrap();
+        assert_eq!(
+            raw.matches(HOOK_COMMAND).count(),
+            1,
+            "must contain exactly one hook entry; file was: {raw}"
+        );
+    }
+
+    /// True when the filesystem enforces directory write permissions for this
+    /// process (false as root, where DAC is bypassed). (clarion-86f4614c0b)
+    #[cfg(unix)]
+    fn perms_enforced() -> bool {
+        use std::os::unix::fs::PermissionsExt;
+        let probe = tempfile::tempdir().unwrap();
+        let ro = probe.path().join("ro");
+        fs::create_dir(&ro).unwrap();
+        fs::set_permissions(&ro, fs::Permissions::from_mode(0o555)).unwrap();
+        fs::write(ro.join("probe"), b"x").is_err()
+    }
+
+    /// The atomic-write cleanup guard: when the staged write fails, the install
+    /// must (a) surface the error, (b) leave the user's existing settings.json
+    /// untouched, and (c) leak no `.settings.json.tmp-*` sibling. Triggered
+    /// portably by making `.claude` read-only so the staged write fails with
+    /// EACCES. (clarion-86f4614c0b)
+    #[cfg(unix)]
+    #[test]
+    fn failed_install_preserves_settings_and_leaks_no_temp() {
+        use std::os::unix::fs::PermissionsExt;
+
+        if !perms_enforced() {
+            eprintln!("skipping: directory permissions not enforced (running as root?)");
+            return;
+        }
+
+        let dir = tempfile::tempdir().unwrap();
+        let claude_dir = dir.path().join(".claude");
+        fs::create_dir_all(&claude_dir).unwrap();
+        // Hand-authored settings WITHOUT the clarion hook, so the install will
+        // try to add it (changed = true) and reach the staged write.
+        let settings_path = claude_dir.join("settings.json");
+        let original = "{\n  \"model\": \"opus\"\n}\n";
+        fs::write(&settings_path, original).unwrap();
+
+        // Make .claude read-only: the existing settings still reads (r-x), but
+        // staging a temp file inside it fails.
+        fs::set_permissions(&claude_dir, fs::Permissions::from_mode(0o555)).unwrap();
+
+        let result = install_session_start_hook(dir.path());
+
+        // Inspect before restoring perms only where needed.
+        let leaked: Vec<String> = fs::read_dir(&claude_dir)
+            .unwrap()
+            .filter_map(Result::ok)
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|name| name.starts_with(".settings.json.tmp-"))
+            .collect();
+
+        // Restore perms so tempdir cleanup succeeds.
+        fs::set_permissions(&claude_dir, fs::Permissions::from_mode(0o755)).unwrap();
+
+        assert!(
+            result.is_err(),
+            "install into a read-only .claude must fail, not silently no-op"
+        );
+        assert!(
+            leaked.is_empty(),
+            "cleanup guard must leave no staging temp behind, found: {leaked:?}"
+        );
+        let after = fs::read_to_string(&settings_path).unwrap();
+        assert_eq!(
+            after, original,
+            "a failed install must leave the user's settings.json byte-for-byte intact"
+        );
+    }
+}
diff --git a/crates/clarion-cli/src/http_read.rs b/crates/clarion-cli/src/http_read.rs
new file mode 100644
index 00000000..2ebc7757
--- /dev/null
+++ b/crates/clarion-cli/src/http_read.rs
@@ -0,0 +1,1736 @@
+use std::error::Error as StdError;
+use std::path::PathBuf;
+use std::sync::{Arc, LazyLock, mpsc};
+use std::thread;
+use std::time::Duration;
+
+use std::future::IntoFuture;
+
+use anyhow::{Context, Result, anyhow};
+use axum::body::{Body, to_bytes};
+use axum::error_handling::HandleErrorLayer;
+use axum::extract::rejection::QueryRejection;
+use axum::extract::{Query, State};
+use axum::http::{HeaderMap, HeaderValue, Request, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use axum::{Json, Router};
+use clarion_mcp::config::HttpReadConfig;
+use clarion_storage::{CanonicalProjectPath, ReaderPool, StorageError, resolve_file_catalog_entry};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use tokio::sync::oneshot;
+use tower::limit::ConcurrencyLimitLayer;
+use tower::load_shed;
+use tower::timeout;
+use tower::{BoxError, ServiceBuilder};
+use tower_http::catch_panic::CatchPanicLayer;
+use tower_http::limit::RequestBodyLimitLayer;
+use tower_http::trace::TraceLayer;
+
+static HTTP_ERROR_DISPATCH: LazyLock<tracing::Dispatch> = LazyLock::new(|| {
+    let subscriber = tracing_subscriber::fmt()
+        .with_writer(std::io::stderr)
+        .with_target(false)
+        .with_ansi(false)
+        .finish();
+    tracing::Dispatch::new(subscriber)
+});
+
+#[derive(Debug)]
+pub struct HttpReadServer {
+    shutdown: Option<oneshot::Sender<()>>,
+    failure_rx: mpsc::Receiver<String>,
+    join: Option<thread::JoinHandle<Result<()>>>,
+    /// `ReaderPool::identity()` captured **inside the HTTP thread**, after
+    /// the pool that the runtime actually uses has been moved into place.
+    /// Callers can `Arc::ptr_eq` this against their own `ReaderPool` to
+    /// catch a refactor that re-opens the pool inside this module.
+    readers_identity: Arc<()>,
+}
+
+impl HttpReadServer {
+    /// Borrow the in-thread `ReaderPool` identity tag. See the field comment.
+    #[must_use]
+    pub fn readers_identity(&self) -> &Arc<()> {
+        &self.readers_identity
+    }
+}
+
+impl HttpReadServer {
+    pub fn check_running(&mut self) -> Result<()> {
+        match self.failure_rx.try_recv() {
+            Ok(error) => {
+                let join_result = self.join_finished();
+                if let Some(Err(join_error)) = join_result {
+                    return Err(join_error.context(error));
+                }
+                return Err(anyhow!(error).context("HTTP read API server failed"));
+            }
+            Err(mpsc::TryRecvError::Empty) => {}
+            Err(mpsc::TryRecvError::Disconnected) => {
+                if self
+                    .join
+                    .as_ref()
+                    .is_some_and(thread::JoinHandle::is_finished)
+                {
+                    match self.join_finished() {
+                        Some(Ok(())) => {
+                            return Err(anyhow!("HTTP read API server exited unexpectedly"));
+                        }
+                        Some(Err(err)) => return Err(err),
+                        None => {}
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    pub fn shutdown(mut self) -> Result<()> {
+        if let Some(shutdown) = self.shutdown.take() {
+            let _ = shutdown.send(());
+        }
+        if let Some(join) = self.join.take() {
+            join.join()
+                .map_err(|_| anyhow!("HTTP read server thread panicked"))??;
+        }
+        Ok(())
+    }
+
+    fn join_finished(&mut self) -> Option<Result<()>> {
+        let finished = self
+            .join
+            .as_ref()
+            .is_some_and(thread::JoinHandle::is_finished);
+        if !finished {
+            return None;
+        }
+        let join = self.join.take()?;
+        Some(
+            join.join()
+                .map_err(|_| anyhow!("HTTP read server thread panicked"))
+                .and_then(|result| result),
+        )
+    }
+}
+
+#[derive(Clone)]
+struct AppState {
+    project_root: PathBuf,
+    readers: ReaderPool,
+    instance_id: crate::instance::InstanceId,
+    /// Resolved inbound auth token. `Some` when the configured `token_env`
+    /// was set at spawn time, `None` when it was unset (loopback v0.1 trust
+    /// mode). All `/api/v1/files`-family requests require
+    /// `Authorization: Bearer <this>` when `Some`. `/api/v1/_capabilities`
+    /// is always unauthenticated so siblings can probe pre-auth.
+    auth_token: Option<Arc<String>>,
+    /// Resolved Loom component identity HMAC secret. When present, protected
+    /// routes require `X-Loom-Component: clarion:<hmac>`.
+    identity_secret: Option<Arc<String>>,
+}
+
+/// Ready-signal payload returned from the HTTP thread back to `spawn`.
+///
+/// `readers_identity` is captured **inside** `run_http_read_server`, after
+/// `readers` has been moved into the runtime. A refactor that re-opens the
+/// pool inside the thread ships the new pool's identity back, and the
+/// caller-side `Arc::ptr_eq` check fires. Capturing on the caller side
+/// (before the move into the thread) would silently miss that refactor.
+struct HttpReadReady {
+    local_addr: std::net::SocketAddr,
+    readers_identity: Arc<()>,
+}
+
+pub fn spawn(
+    project_root: PathBuf,
+    readers: ReaderPool,
+    instance_id: crate::instance::InstanceId,
+    config: &HttpReadConfig,
+) -> Result<Option<HttpReadServer>> {
+    spawn_with_env(project_root, readers, instance_id, config, |name| {
+        std::env::var(name).ok()
+    })
+}
+
+/// Spawn variant that takes an explicit env lookup so tests can drive the
+/// auth-trust gate (and the resolved-bearer-token plumbing) without
+/// mutating process environment.
+pub fn spawn_with_env<F>(
+    project_root: PathBuf,
+    readers: ReaderPool,
+    instance_id: crate::instance::InstanceId,
+    config: &HttpReadConfig,
+    env_lookup: F,
+) -> Result<Option<HttpReadServer>>
+where
+    F: Fn(&str) -> Option<String>,
+{
+    if !config.enabled {
+        return Ok(None);
+    }
+    config
+        .validate_loopback_trust()
+        .context("validate HTTP read API trust model")?;
+    config
+        .validate_auth_trust(&env_lookup)
+        .context("validate HTTP read API auth trust model")?;
+    let auth_token = env_lookup(&config.token_env)
+        .map(|raw| raw.trim().to_owned())
+        .filter(|trimmed| !trimmed.is_empty())
+        .map(Arc::new);
+    let identity_secret = config
+        .identity_token_env
+        .as_deref()
+        .and_then(&env_lookup)
+        .map(|raw| raw.trim().to_owned())
+        .filter(|trimmed| !trimmed.is_empty())
+        .map(Arc::new);
+    let bind = config.bind;
+    let warn_unauthenticated_non_loopback = config.allow_non_loopback
+        && !config.is_loopback_bind()
+        && auth_token.is_none()
+        && identity_secret.is_none();
+    // SEC-02: operator-visible signal that the HTTP API will admit any
+    // local request because both auth knobs are unset and the bind is
+    // loopback. On a shared developer host or CI runner this means any
+    // local process can read the (non-blocked) catalogue.
+    let warn_unauthenticated_loopback =
+        config.is_loopback_bind() && auth_token.is_none() && identity_secret.is_none();
+    let (shutdown_tx, shutdown_rx) = oneshot::channel();
+    let (ready_tx, ready_rx) = std::sync::mpsc::channel::<Result<HttpReadReady>>();
+    let (failure_tx, failure_rx) = mpsc::channel();
+    let auth_token_thread = auth_token.clone();
+    let identity_secret_thread = identity_secret.clone();
+    let join = thread::Builder::new()
+        .name("clarion-http-read".to_owned())
+        .spawn(move || -> Result<()> {
+            let result = run_http_read_server(
+                project_root,
+                readers,
+                instance_id,
+                auth_token_thread,
+                identity_secret_thread,
+                bind,
+                shutdown_rx,
+                ready_tx,
+            );
+            if let Err(err) = &result {
+                let _ = failure_tx.send(format!("{err:#}"));
+            }
+            result
+        })
+        .context("spawn HTTP read server thread")?;
+    let ready = ready_rx
+        .recv()
+        .context("wait for HTTP read API bind result")??;
+    let local_addr = ready.local_addr;
+    let auth = if identity_secret.is_some() {
+        "hmac"
+    } else if auth_token.is_some() {
+        "bearer"
+    } else {
+        "none"
+    };
+    if warn_unauthenticated_non_loopback {
+        tracing::warn!(
+            bind = %local_addr,
+            auth = %auth,
+            "Clarion HTTP read API listening on non-loopback interface without authentication"
+        );
+    }
+    if warn_unauthenticated_loopback {
+        tracing::warn!(
+            bind = %local_addr,
+            auth = %auth,
+            "[TRUST] HTTP API serving on loopback without authentication; any \
+             local process on this host can read the catalogue. Set \
+             identity_token_env or token_env for multi-tenant safety."
+        );
+    }
+    tracing::info!(bind = %local_addr, auth = %auth, "Clarion HTTP read API listening");
+    Ok(Some(HttpReadServer {
+        shutdown: Some(shutdown_tx),
+        failure_rx,
+        join: Some(join),
+        readers_identity: ready.readers_identity,
+    }))
+}
+
+fn run_http_read_server(
+    project_root: PathBuf,
+    readers: ReaderPool,
+    instance_id: crate::instance::InstanceId,
+    auth_token: Option<Arc<String>>,
+    identity_secret: Option<Arc<String>>,
+    bind: std::net::SocketAddr,
+    shutdown_rx: oneshot::Receiver<()>,
+    ready_tx: mpsc::Sender<Result<HttpReadReady>>,
+) -> Result<()> {
+    // Capture identity here, after `readers` has been moved in. A refactor
+    // that opens a fresh pool inside this function would ship its new
+    // identity back to the caller, who will `Arc::ptr_eq`-fail. Capturing
+    // before the move (in `spawn`) would silently miss that refactor.
+    let readers_identity = readers.identity().clone();
+    let runtime = build_http_runtime()?;
+    runtime.block_on(async move {
+        let listener = match tokio::net::TcpListener::bind(bind).await {
+            Ok(listener) => listener,
+            Err(err) => {
+                let _ = ready_tx.send(Err(anyhow!("bind HTTP read API on {bind}: {err}")));
+                return Err(anyhow!("bind HTTP read API on {bind}: {err}"));
+            }
+        };
+        let local_addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(err) => {
+                let _ = ready_tx.send(Err(anyhow!("read HTTP read API local addr: {err}")));
+                return Err(anyhow!("read HTTP read API local addr: {err}"));
+            }
+        };
+        let _ = ready_tx.send(Ok(HttpReadReady {
+            local_addr,
+            readers_identity,
+        }));
+        let state = AppState {
+            project_root,
+            readers,
+            instance_id,
+            auth_token,
+            identity_secret,
+        };
+        let serve_future = axum::serve(listener, router(state))
+            .with_graceful_shutdown(async {
+                let _ = shutdown_rx.await;
+            })
+            .into_future();
+        run_serve_future(serve_future).await
+    })
+}
+
+#[cfg(not(test))]
+async fn run_serve_future<F>(serve_future: F) -> Result<()>
+where
+    F: std::future::Future<Output = std::io::Result<()>>,
+{
+    serve_future.await.context("serve HTTP read API")
+}
+
+/// Test-only cooperative panic hook. Setting [`HTTP_THREAD_PANIC_TRIGGER`]
+/// to `true` causes the HTTP thread's `block_on` future to panic on its
+/// next 5 ms tick. The panic propagates up through `block_on`, the thread's
+/// `JoinHandle::join()` returns `Err(panic_payload)`, and
+/// `HttpReadServer::check_running` then surfaces `"HTTP read server thread
+/// panicked"` to the supervisor. This is the only path that still exercises
+/// the supervisor's runtime-internal-panic arm after `CatchPanicLayer` was
+/// introduced (which absorbs per-request handler panics into 500 envelopes).
+#[cfg(test)]
+pub(crate) static HTTP_THREAD_PANIC_TRIGGER: std::sync::atomic::AtomicBool =
+    std::sync::atomic::AtomicBool::new(false);
+
+#[cfg(test)]
+async fn run_serve_future<F>(serve_future: F) -> Result<()>
+where
+    F: std::future::Future<Output = std::io::Result<()>>,
+{
+    tokio::select! {
+        () = panic_trigger_watcher() => unreachable!("panic_trigger_watcher must panic, not return"),
+        result = serve_future => result.context("serve HTTP read API"),
+    }
+}
+
+#[cfg(test)]
+async fn panic_trigger_watcher() {
+    loop {
+        assert!(
+            !HTTP_THREAD_PANIC_TRIGGER.swap(false, std::sync::atomic::Ordering::SeqCst),
+            "synthetic HTTP runtime panic for supervisor test"
+        );
+        tokio::time::sleep(Duration::from_millis(5)).await;
+    }
+}
+
+fn build_http_runtime() -> Result<tokio::runtime::Runtime> {
+    tokio::runtime::Builder::new_multi_thread()
+        .thread_name("clarion-http-worker")
+        .enable_all()
+        .build()
+        .context("create HTTP read runtime")
+}
+
+fn router(state: AppState) -> Router {
+    let protected = Router::new()
+        .route("/api/v1/files", get(get_file))
+        .route("/api/v1/files:resolve", post(post_files_resolve))
+        .route("/api/v1/files/batch", post(post_files_batch))
+        .route_layer(axum::middleware::from_fn_with_state(
+            state.clone(),
+            require_http_identity,
+        ));
+    let unprotected = Router::new().route("/api/v1/_capabilities", get(get_capabilities));
+    protected.merge(unprotected).with_state(state).layer(
+        ServiceBuilder::new()
+            .layer(CatchPanicLayer::custom(catch_panic_response))
+            .layer(HandleErrorLayer::new(handle_middleware_error))
+            .layer(
+                TraceLayer::new_for_http()
+                    .make_span_with(http_request_span)
+                    .on_failure(()),
+            )
+            .layer(timeout::TimeoutLayer::new(Duration::from_secs(10)))
+            .layer(RequestBodyLimitLayer::new(HTTP_BODY_LIMIT_BYTES))
+            .layer(load_shed::LoadShedLayer::new())
+            .layer(ConcurrencyLimitLayer::new(64)),
+    )
+}
+
+/// Enforce configured identity on protected routes. Prefer the Loom HMAC
+/// identity when `identity_token_env` is configured; otherwise preserve the
+/// legacy bearer-token path for existing deployments.
+async fn require_http_identity(
+    State(state): State<AppState>,
+    request: Request<Body>,
+    next: axum::middleware::Next,
+) -> Response {
+    if let Some(secret) = state.identity_secret.as_ref() {
+        return require_hmac_identity(secret, request, next).await;
+    }
+    let Some(expected) = state.auth_token.as_ref() else {
+        return next.run(request).await;
+    };
+    let presented = request
+        .headers()
+        .get(axum::http::header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.strip_prefix("Bearer "))
+        .map(str::trim)
+        .filter(|token| !token.is_empty());
+    let Some(presented) = presented else {
+        return unauthenticated_response();
+    };
+    // Constant-time compare so a wrong-length-token client can't trivially
+    // distinguish "header absent" from "token mismatch" via timing.
+    if !constant_time_eq(presented.as_bytes(), expected.as_bytes()) {
+        return unauthenticated_response();
+    }
+    next.run(request).await
+}
+
+async fn require_hmac_identity(
+    secret: &str,
+    request: Request<Body>,
+    next: axum::middleware::Next,
+) -> Response {
+    let (parts, body) = request.into_parts();
+    let method = parts.method.as_str().to_owned();
+    let path_and_query = parts.uri.path_and_query().map_or_else(
+        || parts.uri.path().to_owned(),
+        |value| value.as_str().to_owned(),
+    );
+    let presented = parts
+        .headers
+        .get("x-loom-component")
+        .and_then(|value| value.to_str().ok())
+        .and_then(|value| value.trim().strip_prefix("clarion:"))
+        .filter(|signature| !signature.is_empty())
+        .map(str::to_owned);
+    let Some(presented) = presented else {
+        return unauthenticated_response();
+    };
+    let Ok(body_bytes) = to_bytes(body, HTTP_BODY_LIMIT_BYTES).await else {
+        // CI-02 fix: a body read failure here is not a path-validation
+        // problem. The outer `RequestBodyLimitLayer` already rejects
+        // oversized bodies with the framework's 413; reaching this branch
+        // means a transport-layer IO failure or a body that could not be
+        // collected. Surface as Internal (500) so federation clients
+        // routing on `code` do not mis-classify it as a path defect.
+        return json_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            ErrorCode::Internal,
+            "request body could not be read",
+        );
+    };
+    let expected = component_hmac_hex(secret.as_bytes(), &method, &path_and_query, &body_bytes);
+    if !constant_time_eq(presented.as_bytes(), expected.as_bytes()) {
+        return unauthenticated_response();
+    }
+    next.run(Request::from_parts(parts, Body::from(body_bytes)))
+        .await
+}
+
+fn unauthenticated_response() -> Response {
+    json_error(
+        StatusCode::UNAUTHORIZED,
+        ErrorCode::Unauthenticated,
+        "authentication required",
+    )
+}
+
+fn component_hmac_hex(secret: &[u8], method: &str, path_and_query: &str, body: &[u8]) -> String {
+    hmac_sha256_hex(
+        secret,
+        canonical_hmac_message(method, path_and_query, body).as_bytes(),
+    )
+}
+
+fn canonical_hmac_message(method: &str, path_and_query: &str, body: &[u8]) -> String {
+    format!(
+        "{}\n{}\n{}",
+        method,
+        path_and_query,
+        hex_lower(&Sha256::digest(body))
+    )
+}
+
+fn hmac_sha256_hex(secret: &[u8], message: &[u8]) -> String {
+    const BLOCK_SIZE: usize = 64;
+    let mut key = [0_u8; BLOCK_SIZE];
+    if secret.len() > BLOCK_SIZE {
+        key[..32].copy_from_slice(&Sha256::digest(secret));
+    } else {
+        key[..secret.len()].copy_from_slice(secret);
+    }
+    let mut ipad = [0x36_u8; BLOCK_SIZE];
+    let mut opad = [0x5c_u8; BLOCK_SIZE];
+    for index in 0..BLOCK_SIZE {
+        ipad[index] ^= key[index];
+        opad[index] ^= key[index];
+    }
+    let mut inner = Sha256::new();
+    inner.update(ipad);
+    inner.update(message);
+    let inner = inner.finalize();
+    let mut outer = Sha256::new();
+    outer.update(opad);
+    outer.update(inner);
+    hex_lower(&outer.finalize())
+}
+
+fn hex_lower(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for byte in bytes {
+        out.push(HEX[(byte >> 4) as usize] as char);
+        out.push(HEX[(byte & 0x0f) as usize] as char);
+    }
+    out
+}
+
+fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut diff = 0_u8;
+    for (left, right) in a.iter().zip(b.iter()) {
+        diff |= left ^ right;
+    }
+    diff == 0
+}
+
+async fn handle_middleware_error(err: BoxError) -> Response {
+    if err.is::<timeout::error::Elapsed>() {
+        return json_error(
+            StatusCode::REQUEST_TIMEOUT,
+            ErrorCode::Internal,
+            "HTTP request timed out",
+        );
+    }
+    if err.is::<load_shed::error::Overloaded>() {
+        return json_error(
+            StatusCode::SERVICE_UNAVAILABLE,
+            ErrorCode::StorageError,
+            "HTTP read API is overloaded",
+        );
+    }
+    // Refuse the wildcard: any middleware BoxError that is not enumerated above
+    // is a programming defect, not a recoverable condition. We panic with the
+    // full source chain in the payload; the outer `CatchPanicLayer` translates
+    // the panic into the standard 500 INTERNAL envelope so clients still get a
+    // structured response, while CI / tests surface the missing enumeration as
+    // a hard failure rather than a silent 500.
+    let error_chain = format_dyn_error_chain(&*err);
+    panic!(
+        "HTTP read API middleware produced an unhandled error type — enumerate it explicitly: {error_chain}"
+    );
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct FileQuery {
+    #[serde(default)]
+    path: String,
+    #[serde(default)]
+    language: String,
+}
+
+#[derive(Debug, Serialize)]
+struct FileResponse {
+    entity_id: String,
+    content_hash: String,
+    canonical_path: CanonicalProjectPath,
+    language: String,
+}
+
+#[derive(Debug, Serialize)]
+struct CapabilitiesResponse {
+    registry_backend: bool,
+    file_registry: bool,
+    api_version: u8,
+    instance_id: crate::instance::InstanceId,
+}
+
+#[derive(Debug, Serialize)]
+struct ErrorResponse {
+    error: String,
+    code: ErrorCode,
+}
+
+#[derive(Debug, Copy, Clone, Serialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+enum ErrorCode {
+    InvalidPath,
+    PathOutsideProject,
+    NotFound,
+    BriefingBlocked,
+    Unauthenticated,
+    StorageError,
+    BatchTooLarge,
+    Internal,
+}
+
+/// Maximum number of `BatchFileQuery` entries a single
+/// `POST /api/v1/files/batch` request may carry. Pinned in the federation
+/// contract; Filigree splits oversize lookup sets client-side. Lifted to a
+/// constant so the contract docs, the validator, and tests all point at
+/// the same number.
+const BATCH_MAX_QUERIES: usize = 256;
+const RESOLVE_MAX_PATHS: usize = 1000;
+const HTTP_BODY_LIMIT_BYTES: usize = 16 * 1024;
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct BatchFileQuery {
+    #[serde(default)]
+    path: String,
+    #[serde(default)]
+    language: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct BatchFileRequest {
+    queries: Vec<BatchFileQuery>,
+}
+
+#[derive(Debug, Serialize)]
+struct BatchResolvedItem {
+    requested_path: String,
+    entity_id: String,
+    content_hash: String,
+    canonical_path: CanonicalProjectPath,
+    language: String,
+}
+
+#[derive(Debug, Serialize)]
+struct BatchErrorItem {
+    requested_path: String,
+    code: ErrorCode,
+    message: String,
+}
+
+#[derive(Debug, Serialize)]
+struct BatchFileResponse {
+    resolved: Vec<BatchResolvedItem>,
+    not_found: Vec<String>,
+    briefing_blocked: Vec<String>,
+    errors: Vec<BatchErrorItem>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ResolveFileQuery {
+    #[serde(default)]
+    path: String,
+    #[serde(default)]
+    language: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct ResolveFilesRequest {
+    paths: Vec<ResolveFileQuery>,
+}
+
+#[derive(Debug, Serialize)]
+struct ResolveFilesResponse {
+    results: Vec<ResolveFileResult>,
+}
+
+#[derive(Debug, Serialize)]
+struct ResolveFileResult {
+    path: String,
+    response: ResolveFileItemResponse,
+}
+
+#[derive(Debug, Serialize)]
+struct ResolveFileItemResponse {
+    status: ResolveFileStatus,
+    body: serde_json::Value,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "snake_case")]
+enum ResolveFileStatus {
+    Resolved,
+    NotFound,
+    Blocked,
+    Error,
+}
+
+async fn get_file(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+    query: Result<Query<FileQuery>, QueryRejection>,
+) -> Response {
+    let Ok(Query(query)) = query else {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            ErrorCode::InvalidPath,
+            "query parameters are invalid",
+        );
+    };
+    if query.path.trim().is_empty() {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            ErrorCode::InvalidPath,
+            "path query parameter must not be blank",
+        );
+    }
+    let project_root = state.project_root.clone();
+    let file_path = query.path;
+    let language = query.language;
+    let catalog_result = state
+        .readers
+        .with_reader(move |conn| {
+            resolve_file_catalog_entry(conn, &project_root, &file_path, &language)
+        })
+        .await;
+    let result = match catalog_result {
+        Ok(Some(entry)) => entry.into_resolved_file().map(Some),
+        Ok(None) => Ok(None),
+        Err(err) => Err(err),
+    };
+    match result {
+        Ok(Some(file)) => {
+            if let Some(reason) = file.briefing_blocked.as_deref() {
+                log_briefing_blocked_refusal(file.canonical_path.as_str(), reason);
+                return json_error(
+                    StatusCode::FORBIDDEN,
+                    ErrorCode::BriefingBlocked,
+                    "entity is briefing-blocked and cannot be exposed",
+                );
+            }
+            let etag = file_etag(&file.content_hash);
+            if if_none_match_matches(headers.get(header::IF_NONE_MATCH), &etag) {
+                let mut response = StatusCode::NOT_MODIFIED.into_response();
+                insert_etag(&mut response, &etag);
+                return response;
+            }
+            let mut response = (
+                StatusCode::OK,
+                Json(FileResponse {
+                    entity_id: file.entity_id,
+                    content_hash: file.content_hash,
+                    canonical_path: file.canonical_path,
+                    language: file.language,
+                }),
+            )
+                .into_response();
+            insert_etag(&mut response, &etag);
+            response
+        }
+        Ok(None) => json_error(
+            StatusCode::NOT_FOUND,
+            ErrorCode::NotFound,
+            "file is not known to Clarion",
+        ),
+        Err(err) => json_read_error(&err),
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+struct RequestLogContext {
+    loom_component: Option<String>,
+    filigree_actor: Option<String>,
+}
+
+fn request_log_context(headers: &HeaderMap) -> RequestLogContext {
+    RequestLogContext {
+        loom_component: log_header_value(headers, "x-loom-component"),
+        filigree_actor: log_header_value(headers, "x-filigree-actor"),
+    }
+}
+
+fn log_header_value(headers: &HeaderMap, name: &'static str) -> Option<String> {
+    let value = headers.get(name)?.to_str().ok()?.trim();
+    (!value.is_empty()).then(|| value.to_owned())
+}
+
+fn http_request_span<B>(request: &Request<B>) -> tracing::Span {
+    let context = request_log_context(request.headers());
+    let span = tracing::info_span!(
+        "http_read_request",
+        method = %request.method(),
+        path = %request.uri().path(),
+        loom_component = tracing::field::Empty,
+        filigree_actor = tracing::field::Empty,
+    );
+    if let Some(loom_component) = context.loom_component {
+        span.record("loom_component", tracing::field::display(loom_component));
+    }
+    if let Some(filigree_actor) = context.filigree_actor {
+        span.record("filigree_actor", tracing::field::display(filigree_actor));
+    }
+    span
+}
+
+fn file_etag(content_hash: &str) -> String {
+    format!("\"{content_hash}\"")
+}
+
+fn if_none_match_matches(value: Option<&HeaderValue>, etag: &str) -> bool {
+    let Some(value) = value else {
+        return false;
+    };
+    let Ok(value) = value.to_str() else {
+        return false;
+    };
+    value.split(',').map(str::trim).any(|candidate| {
+        candidate == "*" || candidate == etag || candidate.strip_prefix("W/") == Some(etag)
+    })
+}
+
+fn insert_etag(response: &mut Response, etag: &str) {
+    if let Ok(value) = HeaderValue::from_str(etag) {
+        response.headers_mut().insert(header::ETAG, value);
+    }
+}
+
+/// Batch resolution endpoint. Resolves up to `BATCH_MAX_QUERIES` paths in a
+/// single request, partitioning results into four lists:
+///
+/// - `resolved`        — paths that mapped to a file-kind entity.
+/// - `not_found`       — paths Clarion does not have a catalog row for.
+/// - `briefing_blocked` — paths whose entity carries a `briefing_blocked`
+///   property (the partition equivalent of the single-file 403 surface).
+/// - `errors`          — per-path resolution errors (`INVALID_PATH`,
+///   `PATH_OUTSIDE_PROJECT`, `STORAGE_ERROR`, `INTERNAL`).
+///
+/// The whole batch runs inside **one** `with_reader` closure so we
+/// check out one pooled connection per request, not one per query —
+/// this is the perf win Filigree's `ClarionRegistry` needs for cold-
+/// start hydration. `ETag` is intentionally not applied to the batch
+/// surface; clients should `ETag` the single-file endpoint when they
+/// want conditional fetch semantics.
+async fn post_files_batch(
+    State(state): State<AppState>,
+    body: Result<Json<BatchFileRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Ok(Json(request)) = body else {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            ErrorCode::InvalidPath,
+            "request body must be a JSON object {\"queries\": [...]}",
+        );
+    };
+    if request.queries.len() > BATCH_MAX_QUERIES {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            ErrorCode::BatchTooLarge,
+            "queries[] exceeds the per-batch maximum of 256 entries",
+        );
+    }
+    let project_root = state.project_root.clone();
+    let queries = request.queries;
+    let catalog_result = state
+        .readers
+        .with_reader(move |conn| {
+            let mut resolved = Vec::new();
+            let mut not_found = Vec::new();
+            let mut briefing_blocked = Vec::new();
+            let mut errors = Vec::new();
+            for query in queries {
+                if query.path.trim().is_empty() {
+                    errors.push(BatchErrorItem {
+                        requested_path: query.path.clone(),
+                        code: ErrorCode::InvalidPath,
+                        message: "path must not be blank".to_owned(),
+                    });
+                    continue;
+                }
+                match resolve_file_catalog_entry(conn, &project_root, &query.path, &query.language)
+                {
+                    Ok(Some(entry)) => match entry.into_resolved_file() {
+                        Ok(file) => {
+                            if file.briefing_blocked.is_some() {
+                                briefing_blocked.push(query.path);
+                            } else {
+                                resolved.push(BatchResolvedItem {
+                                    requested_path: query.path,
+                                    entity_id: file.entity_id,
+                                    content_hash: file.content_hash,
+                                    canonical_path: file.canonical_path,
+                                    language: file.language,
+                                });
+                            }
+                        }
+                        Err(err) => errors.push(classify_batch_error(query.path, &err)),
+                    },
+                    Ok(None) => not_found.push(query.path),
+                    Err(err) => errors.push(classify_batch_error(query.path, &err)),
+                }
+            }
+            Ok::<_, StorageError>(BatchFileResponse {
+                resolved,
+                not_found,
+                briefing_blocked,
+                errors,
+            })
+        })
+        .await;
+    match catalog_result {
+        Ok(response) => (StatusCode::OK, Json(response)).into_response(),
+        Err(err) => json_read_error(&err),
+    }
+}
+
+async fn post_files_resolve(
+    State(state): State<AppState>,
+    body: Result<Json<ResolveFilesRequest>, axum::extract::rejection::JsonRejection>,
+) -> Response {
+    let Ok(Json(request)) = body else {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            ErrorCode::InvalidPath,
+            "request body must be a JSON object {\"paths\": [...]}",
+        );
+    };
+    if request.paths.len() > RESOLVE_MAX_PATHS {
+        return json_error(
+            StatusCode::BAD_REQUEST,
+            ErrorCode::InvalidPath,
+            "paths[] exceeds the per-batch maximum of 1000 entries",
+        );
+    }
+    let project_root = state.project_root.clone();
+    let paths = request.paths;
+    let catalog_result = state
+        .readers
+        .with_reader(move |conn| {
+            let results = paths
+                .into_iter()
+                .map(|query| {
+                    let response =
+                        resolve_file_query_item(conn, &project_root, &query.path, &query.language);
+                    ResolveFileResult {
+                        path: query.path,
+                        response,
+                    }
+                })
+                .collect();
+            Ok::<_, StorageError>(ResolveFilesResponse { results })
+        })
+        .await;
+    match catalog_result {
+        Ok(response) => (StatusCode::OK, Json(response)).into_response(),
+        Err(err) => json_read_error(&err),
+    }
+}
+
+fn resolve_file_query_item(
+    conn: &rusqlite::Connection,
+    project_root: &std::path::Path,
+    path: &str,
+    language: &str,
+) -> ResolveFileItemResponse {
+    if path.trim().is_empty() {
+        return resolve_error_response(
+            ResolveFileStatus::Error,
+            ErrorCode::InvalidPath,
+            "path must not be blank",
+        );
+    }
+    match resolve_file_catalog_entry(conn, project_root, path, language) {
+        Ok(Some(entry)) => match entry.into_resolved_file() {
+            Ok(file) => {
+                if file.briefing_blocked.is_some() {
+                    resolve_error_response(
+                        ResolveFileStatus::Blocked,
+                        ErrorCode::BriefingBlocked,
+                        "entity is briefing-blocked and cannot be exposed",
+                    )
+                } else {
+                    ResolveFileItemResponse {
+                        status: ResolveFileStatus::Resolved,
+                        body: serde_json::to_value(FileResponse {
+                            entity_id: file.entity_id,
+                            content_hash: file.content_hash,
+                            canonical_path: file.canonical_path,
+                            language: file.language,
+                        })
+                        .expect("FileResponse serializes"),
+                    }
+                }
+            }
+            Err(err) => resolve_read_error_response(&err),
+        },
+        Ok(None) => resolve_error_response(
+            ResolveFileStatus::NotFound,
+            ErrorCode::NotFound,
+            "file is not known to Clarion",
+        ),
+        Err(err) => resolve_read_error_response(&err),
+    }
+}
+
+fn resolve_read_error_response(err: &StorageError) -> ResolveFileItemResponse {
+    let error = classify_read_error(err);
+    resolve_error_response(ResolveFileStatus::Error, error.code, error.message)
+}
+
+fn resolve_error_response(
+    status: ResolveFileStatus,
+    code: ErrorCode,
+    message: &str,
+) -> ResolveFileItemResponse {
+    ResolveFileItemResponse {
+        status,
+        body: serde_json::to_value(ErrorResponse {
+            error: message.to_owned(),
+            code,
+        })
+        .expect("ErrorResponse serializes"),
+    }
+}
+
+fn classify_batch_error(requested_path: String, err: &StorageError) -> BatchErrorItem {
+    let classified = classify_read_error(err);
+    BatchErrorItem {
+        requested_path,
+        code: classified.code,
+        message: classified.message.to_owned(),
+    }
+}
+
+async fn get_capabilities(State(state): State<AppState>) -> Json<CapabilitiesResponse> {
+    Json(CapabilitiesResponse {
+        registry_backend: true,
+        file_registry: true,
+        api_version: 1,
+        instance_id: state.instance_id,
+    })
+}
+
+fn json_read_error(err: &StorageError) -> Response {
+    let error = classify_read_error(err);
+    if error.status.is_server_error() {
+        log_read_server_error(error.code, error.status, err);
+    }
+    json_error(error.status, error.code, error.message)
+}
+
+struct ReadError {
+    status: StatusCode,
+    code: ErrorCode,
+    message: &'static str,
+}
+
+fn classify_read_error(err: &StorageError) -> ReadError {
+    match err {
+        StorageError::InvalidQuery(_) => ReadError {
+            status: StatusCode::BAD_REQUEST,
+            code: ErrorCode::InvalidPath,
+            message: "path query parameter is invalid",
+        },
+        StorageError::InvalidSourcePath(_) => ReadError {
+            status: StatusCode::BAD_REQUEST,
+            code: ErrorCode::PathOutsideProject,
+            message: "path is outside project root",
+        },
+        StorageError::Pool(_) => ReadError {
+            status: StatusCode::SERVICE_UNAVAILABLE,
+            code: ErrorCode::StorageError,
+            message: "file lookup storage is unavailable",
+        },
+        StorageError::Sqlite(_)
+        | StorageError::PoolBuild(_)
+        | StorageError::PragmaInvariant(_)
+        | StorageError::Migration { .. }
+        | StorageError::Io(_) => ReadError {
+            status: StatusCode::INTERNAL_SERVER_ERROR,
+            code: ErrorCode::StorageError,
+            message: "file lookup failed",
+        },
+        // STO-02 (ADR-035): the on-disk file is not a Clarion database, or
+        // was written by a newer build. Either condition is fatal for the
+        // server; the writer-actor refuses to spawn against it. Surfacing
+        // 500 here is defensive — in practice the HTTP API does not open
+        // its own writer, but the reader pool can encounter the same file
+        // header mismatches and we want a clear distinct response code.
+        StorageError::ForeignDatabase { .. } | StorageError::FutureUserVersion { .. } => {
+            ReadError {
+                status: StatusCode::INTERNAL_SERVER_ERROR,
+                code: ErrorCode::StorageError,
+                message: "file lookup storage rejected database header",
+            }
+        }
+        StorageError::PoolInteract(_)
+        | StorageError::WriterGone
+        | StorageError::WriterProtocol(_)
+        | StorageError::WriterNoResponse => ReadError {
+            status: StatusCode::INTERNAL_SERVER_ERROR,
+            code: ErrorCode::Internal,
+            message: "internal file lookup failure",
+        },
+    }
+}
+
+fn format_error_chain(err: &StorageError) -> String {
+    format_dyn_error_chain(err)
+}
+
+fn format_dyn_error_chain(err: &(dyn StdError + 'static)) -> String {
+    let mut chain = vec![err.to_string()];
+    let mut source = err.source();
+    let mut depth = 0;
+    while let Some(err) = source {
+        if depth >= 8 {
+            chain.push("additional sources omitted".to_owned());
+            break;
+        }
+        chain.push(err.to_string());
+        source = err.source();
+        depth += 1;
+    }
+    chain.join(": caused by: ")
+}
+
+fn log_briefing_blocked_refusal(canonical_path: &str, reason: &str) {
+    tracing::dispatcher::with_default(&HTTP_ERROR_DISPATCH, || {
+        tracing::warn!(
+            path = %canonical_path,
+            reason = %reason,
+            "HTTP /api/v1/files refusing to expose briefing-blocked entity"
+        );
+    });
+}
+
+fn log_read_server_error(code: ErrorCode, status: StatusCode, err: &StorageError) {
+    let error_chain = format_error_chain(err);
+    tracing::dispatcher::with_default(&HTTP_ERROR_DISPATCH, || {
+        tracing::error!(
+            code = ?code,
+            status = status.as_u16(),
+            error_chain = %error_chain,
+            "HTTP /api/v1/files lookup failed"
+        );
+    });
+}
+
+#[allow(clippy::needless_pass_by_value)] // `ResponseForPanic` requires owned payload
+fn catch_panic_response(payload: Box<dyn std::any::Any + Send + 'static>) -> Response {
+    let detail = if let Some(s) = payload.downcast_ref::<&'static str>() {
+        (*s).to_owned()
+    } else if let Some(s) = payload.downcast_ref::<String>() {
+        s.clone()
+    } else {
+        "<non-string panic payload>".to_owned()
+    };
+    tracing::dispatcher::with_default(&HTTP_ERROR_DISPATCH, || {
+        tracing::error!(panic = %detail, "HTTP read API handler panicked");
+    });
+    json_error(
+        StatusCode::INTERNAL_SERVER_ERROR,
+        ErrorCode::Internal,
+        "internal panic",
+    )
+}
+
+fn json_error(status: StatusCode, code: ErrorCode, message: &str) -> Response {
+    (
+        status,
+        Json(ErrorResponse {
+            error: message.to_owned(),
+            code,
+        }),
+    )
+        .into_response()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::future::{Future, Pending, pending};
+    use std::sync::mpsc;
+    use std::task::{Context, Poll};
+
+    use super::*;
+    use axum::http::{HeaderMap, HeaderValue};
+    use tower::Service;
+
+    #[test]
+    fn check_running_surfaces_completed_http_thread_failure_before_shutdown() {
+        let (shutdown_tx, _shutdown_rx) = oneshot::channel();
+        let (failure_tx, failure_rx) = mpsc::channel();
+        failure_tx
+            .send("simulated HTTP server failure".to_owned())
+            .expect("send simulated failure");
+        let join = thread::spawn(|| Err(anyhow!("simulated HTTP server failure")));
+        let mut server = HttpReadServer {
+            shutdown: Some(shutdown_tx),
+            failure_rx,
+            join: Some(join),
+            readers_identity: Arc::new(()),
+        };
+
+        let err = server
+            .check_running()
+            .expect_err("HTTP failure should surface before shutdown");
+        let message = format!("{err:#}");
+
+        assert!(
+            message.contains("simulated HTTP server failure"),
+            "unexpected error: {message}"
+        );
+    }
+
+    #[test]
+    fn load_shed_converts_concurrency_backpressure_to_overload_response() {
+        #[derive(Clone)]
+        struct PendingService;
+
+        impl Service<()> for PendingService {
+            type Response = ();
+            type Error = BoxError;
+            type Future = Pending<Result<(), BoxError>>;
+
+            fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+                Poll::Ready(Ok(()))
+            }
+
+            fn call(&mut self, _request: ()) -> Self::Future {
+                pending()
+            }
+        }
+
+        let mut service = ServiceBuilder::new()
+            .layer(load_shed::LoadShedLayer::new())
+            .layer(ConcurrencyLimitLayer::new(1))
+            .service(PendingService);
+        let waker = std::task::Waker::noop();
+        let mut cx = Context::from_waker(waker);
+
+        assert!(
+            service.poll_ready(&mut cx).is_ready(),
+            "first request should acquire the only concurrency permit"
+        );
+        let _held_permit = service.call(());
+
+        assert!(
+            service.poll_ready(&mut cx).is_ready(),
+            "load-shed should stay ready when the concurrency limiter is saturated"
+        );
+        let mut overloaded = std::pin::pin!(service.call(()));
+        let err = match Future::poll(overloaded.as_mut(), &mut cx) {
+            Poll::Ready(Err(err)) => err,
+            other => panic!("expected immediate overload error, got {other:?}"),
+        };
+        assert!(
+            err.is::<load_shed::error::Overloaded>(),
+            "expected load-shed overload error, got {err}"
+        );
+
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+        let response = runtime.block_on(handle_middleware_error(err));
+        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+    }
+
+    #[test]
+    fn request_log_context_reads_optional_actor_headers() {
+        let mut headers = HeaderMap::new();
+        headers.insert("X-Loom-Component", HeaderValue::from_static("loom"));
+        headers.insert("X-Filigree-Actor", HeaderValue::from_static("worker-f"));
+
+        let context = request_log_context(&headers);
+
+        assert_eq!(context.loom_component.as_deref(), Some("loom"));
+        assert_eq!(context.filigree_actor.as_deref(), Some("worker-f"));
+    }
+
+    #[test]
+    fn http_runtime_names_worker_threads() {
+        let runtime = build_http_runtime().expect("HTTP runtime");
+        let worker_name = runtime.block_on(async {
+            tokio::spawn(async { std::thread::current().name().map(str::to_owned) })
+                .await
+                .expect("worker task")
+        });
+
+        assert_eq!(worker_name.as_deref(), Some("clarion-http-worker"));
+    }
+
+    #[test]
+    fn format_dyn_error_chain_walks_box_error_sources() {
+        #[derive(Debug)]
+        struct Inner;
+        impl std::fmt::Display for Inner {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("inner cause")
+            }
+        }
+        impl StdError for Inner {}
+
+        #[derive(Debug)]
+        struct Outer(Inner);
+        impl std::fmt::Display for Outer {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("outer failure")
+            }
+        }
+        impl StdError for Outer {
+            fn source(&self) -> Option<&(dyn StdError + 'static)> {
+                Some(&self.0)
+            }
+        }
+
+        let err: BoxError = Box::new(Outer(Inner));
+        let chain = format_dyn_error_chain(&*err);
+
+        assert_eq!(chain, "outer failure: caused by: inner cause");
+    }
+
+    #[test]
+    #[should_panic(expected = "unhandled error type")]
+    fn handle_middleware_error_refuses_unenumerated_box_error() {
+        #[derive(Debug)]
+        struct UnknownInner;
+        impl std::fmt::Display for UnknownInner {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("inner unknown")
+            }
+        }
+        impl StdError for UnknownInner {}
+
+        #[derive(Debug)]
+        struct UnknownMiddlewareError(UnknownInner);
+        impl std::fmt::Display for UnknownMiddlewareError {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("synthetic unknown middleware failure")
+            }
+        }
+        impl StdError for UnknownMiddlewareError {
+            fn source(&self) -> Option<&(dyn StdError + 'static)> {
+                Some(&self.0)
+            }
+        }
+
+        let err: BoxError = Box::new(UnknownMiddlewareError(UnknownInner));
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+        runtime.block_on(handle_middleware_error(err));
+    }
+
+    #[test]
+    fn unknown_middleware_error_translated_to_internal_envelope_via_catch_panic() {
+        use axum::body::{Body, to_bytes};
+        use axum::http::Request;
+        use std::convert::Infallible;
+        use std::pin::Pin;
+        use tower::{Layer, Service, ServiceExt};
+
+        #[derive(Debug)]
+        struct UnknownInjected;
+        impl std::fmt::Display for UnknownInjected {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("injected unknown middleware error")
+            }
+        }
+        impl StdError for UnknownInjected {}
+
+        #[derive(Clone)]
+        struct InjectUnknownErrorLayer;
+
+        impl<S> Layer<S> for InjectUnknownErrorLayer {
+            type Service = InjectUnknownErrorService<S>;
+            fn layer(&self, inner: S) -> Self::Service {
+                InjectUnknownErrorService { inner }
+            }
+        }
+
+        #[derive(Clone)]
+        #[allow(dead_code)] // `inner` is held to satisfy Layer wiring; this service short-circuits.
+        struct InjectUnknownErrorService<S> {
+            inner: S,
+        }
+
+        impl<S, B> Service<Request<B>> for InjectUnknownErrorService<S>
+        where
+            S: Service<Request<B>, Error = Infallible> + Send + 'static,
+            S::Future: Send + 'static,
+            B: Send + 'static,
+        {
+            type Response = S::Response;
+            type Error = BoxError;
+            type Future =
+                Pin<Box<dyn std::future::Future<Output = Result<Self::Response, BoxError>> + Send>>;
+
+            fn poll_ready(
+                &mut self,
+                _cx: &mut std::task::Context<'_>,
+            ) -> std::task::Poll<Result<(), Self::Error>> {
+                std::task::Poll::Ready(Ok(()))
+            }
+
+            fn call(&mut self, _req: Request<B>) -> Self::Future {
+                Box::pin(async { Err(BoxError::from(Box::new(UnknownInjected))) })
+            }
+        }
+
+        async fn never_called() -> Response {
+            unreachable!("inner handler must not run when middleware short-circuits")
+        }
+
+        let app: Router<()> = Router::new().route("/x", get(never_called)).layer(
+            ServiceBuilder::new()
+                .layer(CatchPanicLayer::custom(catch_panic_response))
+                .layer(HandleErrorLayer::new(handle_middleware_error))
+                .layer(InjectUnknownErrorLayer),
+        );
+
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+        let (status, body) = runtime.block_on(async move {
+            let response = app
+                .oneshot(
+                    Request::builder()
+                        .uri("/x")
+                        .body(Body::empty())
+                        .expect("request"),
+                )
+                .await
+                .expect("oneshot response");
+            let status = response.status();
+            let bytes = to_bytes(response.into_body(), 4096)
+                .await
+                .expect("read response body");
+            (status, bytes)
+        });
+
+        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
+        let parsed: serde_json::Value =
+            serde_json::from_slice(&body).expect("response body is JSON");
+        assert_eq!(parsed["error"], "internal panic");
+        assert_eq!(parsed["code"], "INTERNAL");
+    }
+
+    #[test]
+    fn catch_panic_response_returns_internal_envelope() {
+        let payload: Box<dyn std::any::Any + Send + 'static> =
+            Box::new("handler exploded".to_owned());
+
+        let response = catch_panic_response(payload);
+
+        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
+    }
+
+    #[test]
+    fn catch_panic_layer_translates_handler_panic_to_internal_envelope() {
+        use axum::body::{Body, to_bytes};
+        use axum::http::Request;
+        use tower::ServiceExt;
+
+        async fn boom() -> Response {
+            panic!("synthetic handler panic");
+        }
+
+        let app: Router<()> = Router::new().route("/boom", get(boom)).layer(
+            ServiceBuilder::new()
+                .layer(CatchPanicLayer::custom(catch_panic_response))
+                .layer(HandleErrorLayer::new(handle_middleware_error))
+                .layer(timeout::TimeoutLayer::new(Duration::from_secs(1))),
+        );
+
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        let (status, body) = runtime.block_on(async move {
+            let response = app
+                .oneshot(
+                    Request::builder()
+                        .uri("/boom")
+                        .body(Body::empty())
+                        .expect("request"),
+                )
+                .await
+                .expect("oneshot response");
+            let status = response.status();
+            let bytes = to_bytes(response.into_body(), 4096)
+                .await
+                .expect("read response body");
+            (status, bytes)
+        });
+
+        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
+        let parsed: serde_json::Value =
+            serde_json::from_slice(&body).expect("response body is JSON");
+        assert_eq!(parsed["error"], "internal panic");
+        assert_eq!(parsed["code"], "INTERNAL");
+    }
+
+    /// CI-02 fix: a body-read failure inside HMAC verification must not
+    /// surface as `INVALID_PATH`. Federation clients switch on `code`; a
+    /// transport/IO failure mis-routed as a path-validation defect would
+    /// be a contract bug.
+    #[test]
+    fn hmac_middleware_body_read_failure_is_not_invalid_path() {
+        use axum::Router;
+        use axum::body::{Body, to_bytes};
+        use axum::http::Request;
+        use axum::routing::post;
+        use tower::ServiceExt;
+
+        async fn never_called(_request: Request<Body>) -> Response {
+            unreachable!("inner handler must not run when body read fails")
+        }
+
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        let (status, body) = runtime.block_on(async {
+            // Body that exceeds HTTP_BODY_LIMIT_BYTES so `to_bytes(body, HTTP_BODY_LIMIT_BYTES)`
+            // returns Err with a LengthLimitError. This is the same Err path
+            // a transport-level body-read failure would take.
+            let oversize = vec![b'x'; HTTP_BODY_LIMIT_BYTES + 16];
+            let request = Request::builder()
+                .method("POST")
+                .uri("/api/v1/files/batch")
+                .header("X-Loom-Component", "clarion:deadbeef")
+                .body(Body::from(oversize))
+                .expect("request");
+
+            // Drive `require_hmac_identity` directly. axum's `Next` is not
+            // publicly constructible from outside middleware composition, so
+            // we exercise the function via a single-route Router with the
+            // middleware layered on top.
+            let app: Router<()> = Router::new()
+                .route("/api/v1/files/batch", post(never_called))
+                .layer(axum::middleware::from_fn(|request, next| async move {
+                    require_hmac_identity("test-secret", request, next).await
+                }));
+
+            let response = app.oneshot(request).await.expect("oneshot response");
+            let status = response.status();
+            let bytes = to_bytes(response.into_body(), 4096)
+                .await
+                .expect("read response body");
+            (status, bytes)
+        });
+
+        let parsed: serde_json::Value =
+            serde_json::from_slice(&body).expect("response body is JSON");
+        // The exact code is `INTERNAL` (the CI-02 fix); the load-bearing
+        // assertion is that it is NOT `INVALID_PATH`.
+        assert_ne!(
+            parsed["code"], "INVALID_PATH",
+            "body-read failure must not surface as INVALID_PATH (CI-02): got status={status}, body={parsed}"
+        );
+        assert_eq!(
+            parsed["code"], "INTERNAL",
+            "expected INTERNAL on body-read failure inside HMAC middleware"
+        );
+        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
+    }
+
+    /// SEC-02: when the HTTP API binds to loopback and neither
+    /// `identity_token_env` nor `token_env` resolves to a non-empty
+    /// secret, the surface admits any local request. The operator must
+    /// see an unmissable startup warning that names "loopback" and
+    /// "without authentication".
+    #[test]
+    fn spawn_emits_loopback_no_token_trust_warning() {
+        use clarion_mcp::config::HttpReadConfig;
+        use clarion_storage::ReaderPool;
+        use std::io;
+        use std::net::{SocketAddr, TcpListener};
+        use std::sync::Mutex;
+        use tracing_subscriber::fmt::MakeWriter;
+
+        #[derive(Clone)]
+        struct CaptureWriter {
+            buffer: Arc<Mutex<Vec<u8>>>,
+        }
+
+        impl io::Write for CaptureWriter {
+            fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+                self.buffer
+                    .lock()
+                    .expect("capture lock")
+                    .extend_from_slice(buf);
+                Ok(buf.len())
+            }
+            fn flush(&mut self) -> io::Result<()> {
+                Ok(())
+            }
+        }
+
+        impl<'a> MakeWriter<'a> for CaptureWriter {
+            type Writer = CaptureWriter;
+            fn make_writer(&'a self) -> Self::Writer {
+                self.clone()
+            }
+        }
+
+        let buffer = Arc::new(Mutex::new(Vec::<u8>::new()));
+        let writer = CaptureWriter {
+            buffer: buffer.clone(),
+        };
+        let subscriber = tracing_subscriber::fmt()
+            .with_writer(writer)
+            .with_target(false)
+            .with_ansi(false)
+            .with_max_level(tracing::Level::TRACE)
+            .finish();
+
+        // Drive `spawn_with_env` under the capturing subscriber so the
+        // startup warning lands in `buffer`. Use `with_default` so the
+        // capture is scoped to this test and does not leak into peers.
+        tracing::subscriber::with_default(subscriber, || {
+            let probe = TcpListener::bind(("127.0.0.1", 0)).expect("probe bind");
+            let bind: SocketAddr = probe.local_addr().expect("probe local addr");
+            drop(probe);
+
+            let tempdir = tempfile::tempdir().expect("temp project root");
+            let db_path = tempdir.path().join("clarion.db");
+            let readers = ReaderPool::open(&db_path, 4).expect("open reader pool");
+
+            let config = HttpReadConfig {
+                enabled: true,
+                bind,
+                allow_non_loopback: false,
+                token_env: "CLARION_LOOPBACK_NO_TOKEN_TEST_UNSET".to_owned(),
+                identity_token_env: None,
+            };
+            let instance_id =
+                crate::instance::parse_instance_id_for_test("00000000-0000-4000-8000-000000000002")
+                    .expect("parse synthetic instance id");
+
+            // Env lookup that returns None for every variable — emulates
+            // the operator running `clarion serve` on loopback with no
+            // tokens configured.
+            let env_lookup = |_: &str| -> Option<String> { None };
+
+            let server = spawn_with_env(
+                tempdir.path().to_path_buf(),
+                readers,
+                instance_id,
+                &config,
+                env_lookup,
+            )
+            .expect("spawn HTTP read API")
+            .expect("config.enabled = true implies Some(server)");
+            // Shut down so the test thread does not leak the HTTP server.
+            server.shutdown().expect("shutdown HTTP read API");
+        });
+
+        let captured = String::from_utf8(buffer.lock().expect("capture lock").clone())
+            .expect("captured tracing output is UTF-8");
+
+        assert!(
+            captured.contains("loopback"),
+            "expected loopback-no-token warning to mention 'loopback'; captured: {captured}"
+        );
+        assert!(
+            captured.contains("without authentication"),
+            "expected loopback-no-token warning to mention 'without authentication'; captured: {captured}"
+        );
+    }
+
+    /// C8 supervisor end-to-end. Trips the test-only
+    /// [`HTTP_THREAD_PANIC_TRIGGER`] after the HTTP thread has reported a
+    /// successful bind. The trigger fires a panic inside the runtime's
+    /// `block_on`, the thread's `JoinHandle::join()` reports
+    /// `Err(panic_payload)`, and `check_running` surfaces "HTTP read server
+    /// thread panicked" — the path that runs when `CatchPanicLayer` cannot
+    /// absorb the panic (i.e. anything outside per-request middleware).
+    #[test]
+    fn check_running_surfaces_supervisor_signal_after_runtime_panic() {
+        use clarion_mcp::config::HttpReadConfig;
+        use clarion_storage::ReaderPool;
+        use std::net::{SocketAddr, TcpListener};
+
+        // Hold-and-drop: bind to ephemeral 0 to discover a free port, then
+        // drop so the HTTP server can re-bind it. The micro-race is fine
+        // here — if the port is stolen we surface a different error.
+        let probe = TcpListener::bind(("127.0.0.1", 0)).expect("probe bind");
+        let bind: SocketAddr = probe.local_addr().expect("probe local addr");
+        drop(probe);
+
+        let tempdir = tempfile::tempdir().expect("temp project root");
+        let db_path = tempdir.path().join("clarion.db");
+        // ReaderPool::open is lazy; no connection is acquired before the
+        // panic trigger fires, so the absent SQLite file is irrelevant.
+        let readers = ReaderPool::open(&db_path, 4).expect("open reader pool");
+
+        let config = HttpReadConfig {
+            enabled: true,
+            bind,
+            allow_non_loopback: false,
+            ..HttpReadConfig::default()
+        };
+        let instance_id =
+            crate::instance::parse_instance_id_for_test("00000000-0000-4000-8000-000000000001")
+                .expect("parse synthetic instance id");
+
+        // Defensive: clear any stale trigger from a prior test.
+        HTTP_THREAD_PANIC_TRIGGER.store(false, std::sync::atomic::Ordering::SeqCst);
+
+        let mut server = spawn(tempdir.path().to_path_buf(), readers, instance_id, &config)
+            .expect("spawn HTTP read API")
+            .expect("config.enabled = true implies Some(server)");
+
+        // Trip the panic. The watcher polls every 5 ms.
+        HTTP_THREAD_PANIC_TRIGGER.store(true, std::sync::atomic::Ordering::SeqCst);
+
+        // Poll check_running until it reports a failure; cap at 5 s so a
+        // regression in the trigger path doesn't hang CI.
+        let deadline = std::time::Instant::now() + Duration::from_secs(5);
+        let err = loop {
+            if let Err(err) = server.check_running() {
+                break err;
+            }
+            assert!(
+                std::time::Instant::now() < deadline,
+                "supervisor did not surface a runtime panic within 5s — \
+                 the test panic hook may not be wired correctly"
+            );
+            std::thread::sleep(Duration::from_millis(20));
+        };
+
+        let message = format!("{err:#}");
+        assert!(
+            message.contains("HTTP read server thread panicked"),
+            "supervisor must report the thread panic; got: {message}"
+        );
+    }
+}
diff --git a/crates/clarion-cli/src/install.rs b/crates/clarion-cli/src/install.rs
index a0d83b36..352429d2 100644
--- a/crates/clarion-cli/src/install.rs
+++ b/crates/clarion-cli/src/install.rs
@@ -7,7 +7,10 @@
 //! - `<path>/clarion.yaml`        (user-edited config stub at project root;
 //!   see detailed-design.md §File layout)
 //!
-//! Refuses if `.clarion/` already exists unless `--force` is passed.
+//! A bare `clarion install` refuses if `.clarion/` already exists unless
+//! `--force` is passed. Under `--skills`/`--hooks`/`--all`, an existing
+//! `.clarion/` is left in place (init is skipped) rather than treated as an
+//! error, so the requested idempotent components can still be applied.
 
 use std::fs;
 use std::path::Path;
@@ -23,31 +26,54 @@ const CONFIG_JSON_STUB: &str = r#"{
 }
 "#;
 
-const CLARION_YAML_STUB: &str = "# clarion.yaml — user-edited config.\n\
-# Do not delete this file: clarion serve reads MCP, LLM, and integration\n\
-# settings from here when present.\n\
-version: 1\n\
-llm_policy:\n\
-  enabled: false\n\
-  provider: openrouter\n\
-  allow_live_provider: false\n\
-  openrouter:\n\
-    endpoint_url: https://openrouter.ai/api/v1\n\
-    api_key_env: OPENROUTER_API_KEY\n\
-    attribution:\n\
-      referer: https://github.com/qacona/clarion\n\
-      title: Clarion\n\
-  model_id: anthropic/claude-sonnet-4.6\n\
-  session_token_ceiling: 1000000\n\
-  max_inferred_edges_per_caller: 8\n\
-  cache_max_age_days: 180\n\
-integrations:\n\
-  filigree:\n\
-    enabled: false\n\
-    base_url: http://127.0.0.1:8766\n\
-    actor: clarion-mcp\n\
-    token_env: FILIGREE_API_TOKEN\n\
-    timeout_seconds: 5\n";
+// NOTE: Do not use `\` line-continuation here — Rust strips both the newline
+// AND all leading whitespace on the continuation line, producing flat (and
+// therefore broken) YAML. Use raw newlines + explicit indentation.
+const CLARION_YAML_STUB: &str = "# clarion.yaml — user-edited config.
+# Do not delete this file: clarion serve reads MCP, LLM, and integration
+# settings from here when present.
+version: 1
+llm_policy:
+  enabled: false
+  provider: openrouter
+  allow_live_provider: false
+  openrouter:
+    endpoint_url: https://openrouter.ai/api/v1
+    api_key_env: OPENROUTER_API_KEY
+    attribution:
+      referer: https://github.com/tachyon-beep/clarion
+      title: Clarion
+  codex_cli:
+    executable: codex
+    model: null
+    profile: null
+    sandbox: read-only
+    timeout_seconds: 300
+  claude_cli:
+    executable: claude
+    model: null
+    permission_mode: plan
+    tools: []
+    timeout_seconds: 300
+    max_turns: 2
+    no_session_persistence: true
+    exclude_dynamic_system_prompt_sections: true
+  model_id: anthropic/claude-sonnet-4.6
+  session_token_ceiling: 1000000
+  max_inferred_edges_per_caller: 8
+  cache_max_age_days: 180
+integrations:
+  filigree:
+    enabled: false
+    base_url: http://127.0.0.1:8766
+    actor: clarion-mcp
+    token_env: FILIGREE_API_TOKEN
+    timeout_seconds: 5
+serve:
+  http:
+    enabled: false
+    bind: 127.0.0.1:9111
+";
 
 const GITIGNORE_CONTENTS: &str = "\
 # Clarion .gitignore — ADR-005 tracked-vs-excluded list.
@@ -74,6 +100,64 @@ logs/
 runs/*/log.jsonl
 ";
 
+/// What `clarion install` should do, resolved from the CLI flags per the agent-
+/// orientation plan: bare install = init only; `--skills`/`--hooks` are
+/// independent and do NOT init; `--all` = init + skills + hooks.
+///
+/// Modeled as an enum rather than three independent bools so the derived and
+/// illegal states the bool form allowed are unrepresentable: `init_clarion` is
+/// no longer a peer field that can contradict an explicit component request,
+/// and the do-nothing `{false, false, false}` state (which PR #21 had to guard
+/// against at the `run()` entry) cannot be produced by [`InstallPlan::from_flags`]
+/// at all (clarion-c6b8dc27f3). The three booleans are derived on demand via
+/// [`init_clarion`](Self::init_clarion) / [`skills`](Self::skills) /
+/// [`hooks`](Self::hooks).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InstallPlan {
+    /// Bare `clarion install`: initialise `.clarion/` only.
+    Bare,
+    /// `--skills` and/or `--hooks` without `--all`: apply the named components
+    /// and do NOT initialise `.clarion/`. `from_flags` only constructs this
+    /// when at least one field is `true`.
+    Components { skills: bool, hooks: bool },
+    /// `--all`: initialise `.clarion/` + skills + hooks.
+    All,
+}
+
+impl InstallPlan {
+    /// Resolve the CLI flags into a plan. `--all` wins; otherwise any of
+    /// `--skills`/`--hooks` selects [`Components`](Self::Components); no flag
+    /// selects [`Bare`](Self::Bare). Never yields a do-nothing plan.
+    #[must_use]
+    pub fn from_flags(skills: bool, hooks: bool, all: bool) -> Self {
+        if all {
+            Self::All
+        } else if skills || hooks {
+            Self::Components { skills, hooks }
+        } else {
+            Self::Bare
+        }
+    }
+
+    /// Whether to initialise `.clarion/` (the index). True for `Bare` and `All`.
+    #[must_use]
+    pub fn init_clarion(self) -> bool {
+        matches!(self, Self::Bare | Self::All)
+    }
+
+    /// Whether to install the `clarion-workflow` skill pack.
+    #[must_use]
+    pub fn skills(self) -> bool {
+        matches!(self, Self::All | Self::Components { skills: true, .. })
+    }
+
+    /// Whether to install the `SessionStart` hook.
+    #[must_use]
+    pub fn hooks(self) -> bool {
+        matches!(self, Self::All | Self::Components { hooks: true, .. })
+    }
+}
+
 /// Run the `install` subcommand.
 ///
 /// # Errors
@@ -81,7 +165,7 @@ runs/*/log.jsonl
 /// Returns an error if `.clarion/` already exists without `--force`, if the
 /// target directory cannot be canonicalised, or if any filesystem or database
 /// operation fails.
-pub fn run(path: &Path, force: bool) -> Result<()> {
+pub fn run(path: &Path, force: bool, plan: InstallPlan) -> Result<()> {
     if !path.exists() {
         bail!(
             "target directory does not exist: {}. Create it first or pass a valid --path.",
@@ -91,47 +175,114 @@ pub fn run(path: &Path, force: bool) -> Result<()> {
     let project_root = path
         .canonicalize()
         .with_context(|| format!("cannot canonicalise --path {}", path.display()))?;
-    let clarion_dir = project_root.join(".clarion");
-    if clarion_dir.exists() {
-        if !force {
-            bail!(
-                ".clarion/ already exists at {}. Delete it or pass --force to overwrite it.",
+
+    // `from_flags` cannot produce a do-nothing plan, but a hand-built
+    // `Components { skills: false, hooks: false }` still could, so keep a
+    // defensive guard rather than silently succeeding.
+    if !plan.init_clarion() && !plan.skills() && !plan.hooks() {
+        bail!(
+            "nothing to install: pass --skills, --hooks, or --all, \
+             or run bare `clarion install` to initialise .clarion/."
+        );
+    }
+
+    if plan.init_clarion() {
+        let clarion_dir = project_root.join(".clarion");
+        let exists = clarion_dir.exists();
+        // A bare `clarion install` (no other components requested) refuses to
+        // clobber an existing .clarion/. Under `--all` (other idempotent
+        // components requested) an already-initialised project is not an error:
+        // we keep the existing index and apply the remaining components.
+        let bare_init = !plan.skills() && !plan.hooks();
+        if exists && !force {
+            if bare_init {
+                bail!(
+                    ".clarion/ already exists at {}. Delete it or pass --force to overwrite it.",
+                    clarion_dir.display()
+                );
+            }
+            // A non-bare init (--all / --skills / --hooks) treats an existing
+            // .clarion/ as already-initialised and keeps it. But a non-directory
+            // .clarion is not a usable index — refuse rather than "succeed" with
+            // skills/hooks installed atop a project that has no clarion.db.
+            if !clarion_dir.is_dir() {
+                bail!(
+                    "found a non-directory at {}; expected an initialised .clarion/ \
+                     directory. Remove it (or pass --force) and re-run.",
+                    clarion_dir.display()
+                );
+            }
+            println!(
+                "{} already initialised; skipping .clarion/ init (pass --force to recreate).",
                 clarion_dir.display()
             );
-        }
-        if !clarion_dir.is_dir() {
-            bail!(
-                "--force can only overwrite an existing .clarion/ directory; \
-                 found non-directory at {}.",
-                clarion_dir.display()
+        } else {
+            if exists {
+                // --force overwrite path.
+                if !clarion_dir.is_dir() {
+                    bail!(
+                        "--force can only overwrite an existing .clarion/ directory; \
+                         found non-directory at {}.",
+                        clarion_dir.display()
+                    );
+                }
+                fs::remove_dir_all(&clarion_dir)
+                    .with_context(|| format!("remove existing {}", clarion_dir.display()))?;
+            }
+
+            fs::create_dir_all(&clarion_dir)
+                .with_context(|| format!("mkdir {}", clarion_dir.display()))?;
+
+            // Cleanup guard: if any post-mkdir step fails, remove .clarion/ before
+            // bubbling the error so the next install attempt isn't blocked by the
+            // "already exists" check (clarion-ed5017139f).
+            if let Err(err) = populate_after_mkdir(&clarion_dir, &project_root) {
+                if let Err(cleanup_err) = fs::remove_dir_all(&clarion_dir) {
+                    tracing::warn!(
+                        clarion_dir = %clarion_dir.display(),
+                        error = %cleanup_err,
+                        "install failed and cleanup of partial .clarion/ also failed; \
+                         manual rm -rf may be required"
+                    );
+                }
+                return Err(err);
+            }
+
+            tracing::info!(
+                clarion_dir = %clarion_dir.display(),
+                "clarion install complete"
             );
+            println!("Initialised {}", clarion_dir.display());
         }
-        fs::remove_dir_all(&clarion_dir)
-            .with_context(|| format!("remove existing {}", clarion_dir.display()))?;
     }
 
-    fs::create_dir_all(&clarion_dir).with_context(|| format!("mkdir {}", clarion_dir.display()))?;
+    if plan.skills() {
+        let report = crate::skill_pack::install_skill_pack(&project_root)
+            .context("install clarion-workflow skill pack")?;
+        if report.copied {
+            println!(
+                "Installed clarion-workflow skill into {}/.claude/skills and {}/.agents/skills",
+                project_root.display(),
+                project_root.display()
+            );
+        } else {
+            println!("clarion-workflow skill already up to date");
+        }
+    }
 
-    // Cleanup guard: if any post-mkdir step fails, remove .clarion/ before
-    // bubbling the error so the next install attempt isn't blocked by the
-    // "already exists" check (clarion-ed5017139f).
-    if let Err(err) = populate_after_mkdir(&clarion_dir, &project_root) {
-        if let Err(cleanup_err) = fs::remove_dir_all(&clarion_dir) {
-            tracing::warn!(
-                clarion_dir = %clarion_dir.display(),
-                error = %cleanup_err,
-                "install failed and cleanup of partial .clarion/ also failed; \
-                 manual rm -rf may be required"
+    if plan.hooks() {
+        let changed = crate::hooks_settings::install_session_start_hook(&project_root)
+            .context("merge SessionStart hook into .claude/settings.json")?;
+        if changed {
+            println!(
+                "Added clarion SessionStart hook to {}/.claude/settings.json",
+                project_root.display()
             );
+        } else {
+            println!("clarion SessionStart hook already present");
         }
-        return Err(err);
     }
 
-    tracing::info!(
-        clarion_dir = %clarion_dir.display(),
-        "clarion install complete"
-    );
-    println!("Initialised {}", clarion_dir.display());
     Ok(())
 }
 
@@ -167,3 +318,83 @@ fn initialise_db(path: &Path) -> Result<()> {
     schema::apply_migrations(&mut conn).map_err(|e| anyhow::anyhow!("{e}"))?;
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::InstallPlan;
+
+    #[test]
+    fn from_flags_truth_table() {
+        // Bare install: no component flags -> init only.
+        let bare = InstallPlan::from_flags(false, false, false);
+        assert_eq!(bare, InstallPlan::Bare);
+        assert!(bare.init_clarion());
+        assert!(!bare.skills());
+        assert!(!bare.hooks());
+
+        // --skills: skills only, no init.
+        let skills = InstallPlan::from_flags(true, false, false);
+        assert_eq!(
+            skills,
+            InstallPlan::Components {
+                skills: true,
+                hooks: false
+            }
+        );
+        assert!(!skills.init_clarion());
+        assert!(skills.skills());
+        assert!(!skills.hooks());
+
+        // --hooks: hooks only, no init.
+        let hooks = InstallPlan::from_flags(false, true, false);
+        assert_eq!(
+            hooks,
+            InstallPlan::Components {
+                skills: false,
+                hooks: true
+            }
+        );
+        assert!(!hooks.init_clarion());
+        assert!(!hooks.skills());
+        assert!(hooks.hooks());
+
+        // --all: everything (component flags ignored).
+        let all = InstallPlan::from_flags(false, false, true);
+        assert_eq!(all, InstallPlan::All);
+        assert!(all.init_clarion());
+        assert!(all.skills());
+        assert!(all.hooks());
+
+        // --skills --hooks: both components, still no init.
+        let both = InstallPlan::from_flags(true, true, false);
+        assert_eq!(
+            both,
+            InstallPlan::Components {
+                skills: true,
+                hooks: true
+            }
+        );
+        assert!(!both.init_clarion());
+        assert!(both.skills());
+        assert!(both.hooks());
+    }
+
+    #[test]
+    fn from_flags_never_yields_a_do_nothing_plan() {
+        // The do-nothing {false,false,false} state that PR #21 guarded against
+        // at run() entry is now unreachable through the only public constructor
+        // (clarion-c6b8dc27f3): every flag combination resolves to a plan that
+        // does at least one thing.
+        for skills in [false, true] {
+            for hooks in [false, true] {
+                for all in [false, true] {
+                    let plan = InstallPlan::from_flags(skills, hooks, all);
+                    assert!(
+                        plan.init_clarion() || plan.skills() || plan.hooks(),
+                        "from_flags({skills},{hooks},{all}) produced a do-nothing plan: {plan:?}"
+                    );
+                }
+            }
+        }
+    }
+}
diff --git a/crates/clarion-cli/src/instance.rs b/crates/clarion-cli/src/instance.rs
new file mode 100644
index 00000000..075cfdf4
--- /dev/null
+++ b/crates/clarion-cli/src/instance.rs
@@ -0,0 +1,148 @@
+use std::fmt;
+use std::fs::{self, OpenOptions};
+use std::io::{self, Write};
+use std::path::Path;
+
+use anyhow::{Context, Result, anyhow};
+use serde::{Serialize, Serializer};
+use uuid::Uuid;
+
+const INSTANCE_ID_FILE: &str = "instance_id";
+
+/// A validated Clarion project instance ID — guaranteed to be a UUID at the
+/// type level. The inner `Uuid` is private and the only ways to construct
+/// one are [`load_or_create`] (reads/creates the persisted file) and
+/// [`parse_instance_id`] (parses a candidate string, used by tests).
+/// Display and Serialize emit the canonical hyphenated UUID form so the
+/// wire format matches the pre-newtype `String` representation byte-for-byte.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct InstanceId(Uuid);
+
+impl InstanceId {
+    /// Fresh random instance ID (`UUIDv4`). Used when no persisted file exists.
+    fn new_random() -> Self {
+        Self(Uuid::new_v4())
+    }
+}
+
+impl fmt::Display for InstanceId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl Serialize for InstanceId {
+    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
+        // Emit the canonical hyphenated UUID string so the federation wire
+        // format matches the pre-newtype `String` representation byte-for-byte.
+        // `uuid::Uuid::serialize` requires the `serde` feature on the `uuid`
+        // crate; doing it manually here keeps the dependency surface unchanged.
+        serializer.collect_str(&self.0)
+    }
+}
+
+pub fn load_or_create(project_root: &Path) -> Result<InstanceId> {
+    let path = project_root.join(".clarion").join(INSTANCE_ID_FILE);
+    match fs::read_to_string(&path) {
+        Ok(raw) => read_existing_instance_id(&path, &raw),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => create_instance_id(&path),
+        Err(err) => Err(err).with_context(|| format!("read {}", path.display())),
+    }
+}
+
+fn create_instance_id(path: &Path) -> Result<InstanceId> {
+    let instance_id = InstanceId::new_random();
+    let temp_path = path.with_file_name(format!(".{INSTANCE_ID_FILE}.{instance_id}.tmp"));
+    let mut file = create_new_private_file(&temp_path)
+        .with_context(|| format!("create temporary {}", temp_path.display()))?;
+    writeln!(file, "{instance_id}").with_context(|| format!("write {}", temp_path.display()))?;
+    file.sync_all()
+        .with_context(|| format!("sync {}", temp_path.display()))?;
+    drop(file);
+
+    match fs::hard_link(&temp_path, path) {
+        Ok(()) => {}
+        Err(err) if err.kind() == io::ErrorKind::AlreadyExists => {
+            let _ = fs::remove_file(&temp_path);
+            let raw = fs::read_to_string(path)
+                .with_context(|| format!("read concurrently-created {}", path.display()))?;
+            return read_existing_instance_id(path, &raw);
+        }
+        Err(err) => {
+            let _ = fs::remove_file(&temp_path);
+            return Err(err).with_context(|| {
+                format!(
+                    "publish temporary {} to {}",
+                    temp_path.display(),
+                    path.display()
+                )
+            });
+        }
+    }
+    fs::remove_file(&temp_path).with_context(|| format!("remove {}", temp_path.display()))?;
+    #[cfg(unix)]
+    set_private_mode(path)?;
+    Ok(instance_id)
+}
+
+#[cfg(unix)]
+fn create_new_private_file(path: &Path) -> io::Result<fs::File> {
+    use std::os::unix::fs::OpenOptionsExt;
+
+    OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(path)
+}
+
+#[cfg(not(unix))]
+fn create_new_private_file(path: &Path) -> io::Result<fs::File> {
+    OpenOptions::new().write(true).create_new(true).open(path)
+}
+
+#[cfg(unix)]
+fn set_private_mode(path: &Path) -> Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+
+    let mut permissions = fs::metadata(path)
+        .with_context(|| format!("stat {}", path.display()))?
+        .permissions();
+    permissions.set_mode(0o600);
+    fs::set_permissions(path, permissions)
+        .with_context(|| format!("set private mode on {}", path.display()))
+}
+
+#[cfg(not(unix))]
+fn set_private_mode(_path: &Path) -> Result<()> {
+    Ok(())
+}
+
+fn read_existing_instance_id(path: &Path, raw: &str) -> Result<InstanceId> {
+    let instance_id = parse_instance_id(path, raw)?;
+    set_private_mode(path)?;
+    Ok(instance_id)
+}
+
+fn parse_instance_id(path: &Path, raw: &str) -> Result<InstanceId> {
+    let trimmed = raw.trim();
+    let id = Uuid::parse_str(trimmed).map_err(|err| invalid_instance_id(path, &err))?;
+    Ok(InstanceId(id))
+}
+
+/// Test-only constructor: parse a candidate UUID into an `InstanceId`
+/// without touching the filesystem. Used by `http_read::tests` to drive
+/// `spawn` synthetically.
+#[cfg(test)]
+pub(crate) fn parse_instance_id_for_test(raw: &str) -> Result<InstanceId> {
+    let id = Uuid::parse_str(raw.trim())
+        .map_err(|err| anyhow!("invalid synthetic instance id: {err}"))?;
+    Ok(InstanceId(id))
+}
+
+fn invalid_instance_id(path: &Path, source: &uuid::Error) -> anyhow::Error {
+    anyhow!(
+        "invalid Clarion instance ID in {}: {source}; expected a UUID",
+        path.display()
+    )
+}
diff --git a/crates/clarion-cli/src/main.rs b/crates/clarion-cli/src/main.rs
index 048d96c5..f4efbab8 100644
--- a/crates/clarion-cli/src/main.rs
+++ b/crates/clarion-cli/src/main.rs
@@ -1,41 +1,92 @@
 mod analyze;
+mod analyze_lock;
 mod cli;
 mod clustering;
 mod config;
+mod db;
+mod hook;
+mod hooks_settings;
+mod http_read;
 mod install;
+mod instance;
+mod run_lifecycle;
+mod secret_scan;
 mod serve;
+mod skill_pack;
 mod stats;
 
 use anyhow::Result;
 use clap::Parser;
 
 fn main() -> Result<()> {
-    // Load .env from CWD or any ancestor directory, before tracing setup so a
+    let cli = cli::Cli::parse();
+    // Load .env before tracing setup for operator-facing commands so a
     // .env-supplied RUST_LOG is in effect by the time the filter is built.
-    // Existing process env vars win over .env values (dotenvy default), so an
-    // explicit `OPENROUTER_API_KEY=… clarion serve` still beats a checked-in
-    // dev .env. Missing .env is not an error — silently skip.
-    let _ = dotenvy::dotenv();
+    // `analyze` is deliberately excluded: project .env contents are scanned
+    // as source sidecars by the pre-ingest secret scanner and must not be
+    // imported into plugin subprocess environments before that gate runs.
+    if !matches!(&cli.command, cli::Command::Analyze { .. }) {
+        let _ = dotenvy::dotenv();
+    }
     init_tracing();
-    let cli = cli::Cli::parse();
     match cli.command {
-        cli::Command::Install { force, path } => install::run(&path, force),
-        cli::Command::Analyze { path, config } => {
+        cli::Command::Install {
+            force,
+            path,
+            skills,
+            hooks,
+            all,
+        } => install::run(
+            &path,
+            force,
+            install::InstallPlan::from_flags(skills, hooks, all),
+        ),
+        cli::Command::Analyze {
+            path,
+            config,
+            allow_unredacted_secrets,
+            confirm_allow_unredacted_secrets,
+            run_id,
+            resume,
+            prune_unseen,
+            progress_file,
+        } => {
             let rt = tokio::runtime::Builder::new_multi_thread()
                 .enable_all()
                 .build()?;
-            if let Some(config_path) = config {
-                rt.block_on(analyze::run_with_options(
-                    path,
-                    analyze::AnalyzeOptions {
-                        config_path: Some(config_path),
-                    },
-                ))
-            } else {
-                rt.block_on(analyze::run(path))
-            }
+            let secret_scan = match secret_scan::SecretScanOptions::from_cli(
+                allow_unredacted_secrets,
+                confirm_allow_unredacted_secrets,
+            ) {
+                Ok(options) => options,
+                Err(err) => {
+                    eprintln!("{err}");
+                    std::process::exit(78);
+                }
+            };
+            rt.block_on(analyze::run_with_options(
+                path,
+                analyze::AnalyzeOptions {
+                    config_path: config,
+                    secret_scan,
+                    run_id,
+                    resume_run_id: resume,
+                    prune_unseen,
+                    progress_file,
+                },
+            ))
         }
         cli::Command::Serve { path, config } => serve::run(&path, config.as_deref()),
+        cli::Command::Hook { command } => match command {
+            cli::HookCommand::SessionStart { path } => hook::session_start(&path),
+        },
+        cli::Command::Db { command } => match command {
+            cli::DbCommand::Backup {
+                output,
+                path,
+                force,
+            } => db::backup(&path, &output, force),
+        },
     }
 }
 
diff --git a/crates/clarion-cli/src/run_lifecycle.rs b/crates/clarion-cli/src/run_lifecycle.rs
new file mode 100644
index 00000000..b4eff398
--- /dev/null
+++ b/crates/clarion-cli/src/run_lifecycle.rs
@@ -0,0 +1,52 @@
+use anyhow::{Context, Result};
+use clarion_storage::{Writer, commands::WriterCmd};
+
+pub(crate) async fn begin_run(
+    writer: &Writer,
+    run_id: &str,
+    analyze_config_json: &str,
+    started_at: &str,
+) -> Result<()> {
+    writer
+        .send_wait(|ack| WriterCmd::BeginRun {
+            run_id: run_id.to_owned(),
+            config_json: analyze_config_json.to_owned(),
+            started_at: started_at.to_owned(),
+            ack,
+        })
+        .await
+        .map_err(|e| anyhow::anyhow!("{e}"))
+        .context("BeginRun")
+}
+
+/// Reopen an existing run for `--resume` (REQ-FINDING-05): the writer reuses
+/// the prior run's row instead of inserting a fresh one (which would conflict
+/// on the run PK). See [`WriterCmd::ResumeRun`].
+pub(crate) async fn resume_run(writer: &Writer, run_id: &str) -> Result<()> {
+    writer
+        .send_wait(|ack| WriterCmd::ResumeRun {
+            run_id: run_id.to_owned(),
+            ack,
+        })
+        .await
+        .map_err(|e| anyhow::anyhow!("{e}"))
+        .context("ResumeRun")
+}
+
+/// Open the analyze run: reopen an existing row when `resume` is set, else
+/// begin a fresh run. Centralises the begin-vs-resume choice so every
+/// run-opening call site (including the discovery-error and no-plugins early
+/// exits) honours `--resume` uniformly.
+pub(crate) async fn open_run(
+    writer: &Writer,
+    resume: bool,
+    run_id: &str,
+    analyze_config_json: &str,
+    started_at: &str,
+) -> Result<()> {
+    if resume {
+        resume_run(writer, run_id).await
+    } else {
+        begin_run(writer, run_id, analyze_config_json, started_at).await
+    }
+}
diff --git a/crates/clarion-cli/src/secret_scan.rs b/crates/clarion-cli/src/secret_scan.rs
new file mode 100644
index 00000000..41042a2a
--- /dev/null
+++ b/crates/clarion-cli/src/secret_scan.rs
@@ -0,0 +1,574 @@
+//! Pre-ingest secret scanning for `clarion analyze`.
+//!
+//! Exit codes used by this module:
+//! - 0: analysis may continue, with or without an explicit secret override.
+//! - 1: ordinary hard failure reported through the caller's `anyhow::Result`.
+//! - 78 (`EX_CONFIG`): `--allow-unredacted-secrets` was misconfigured or not
+//!   confirmed; the caller must abort before `BeginRun`.
+
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs,
+    io::{self, IsTerminal, Write},
+    path::{Path, PathBuf},
+    sync::{
+        Arc, Mutex,
+        atomic::{AtomicUsize, Ordering},
+    },
+    thread,
+};
+
+mod anchors;
+mod baseline;
+mod files;
+mod findings;
+
+use anyhow::{Context, Result};
+use clarion_core::BriefingBlockReason;
+use clarion_scanner::{Detection, Scanner, SuppressionResult};
+use clarion_storage::{Writer, commands::EntityRecord};
+pub(crate) use files::collect_scan_files;
+use findings::{
+    FindingConfidence, FindingKind, FindingSeverity, PendingFinding, secret_detected_finding,
+};
+use serde_json::json;
+
+const SECRET_OVERRIDE_ALLOWED: &str = "CLA-SEC-UNREDACTED-SECRETS-ALLOWED";
+const OVERRIDE_UNCONFIRMED: &str = "CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED";
+const CONFIRM_TOKEN: &str = "yes-i-understand";
+
+#[derive(Debug, Clone, Default)]
+pub(crate) struct SecretScanOptions {
+    pub(crate) override_policy: OverridePolicy,
+}
+
+impl SecretScanOptions {
+    pub(crate) fn from_cli(
+        allow_unredacted_secrets: bool,
+        confirm_allow_unredacted_secrets: Option<String>,
+    ) -> std::result::Result<Self, OverrideConfirmationError> {
+        let override_policy = match (allow_unredacted_secrets, confirm_allow_unredacted_secrets) {
+            (false, None) => OverridePolicy::Forbid,
+            (true, None) => OverridePolicy::RequireInteractive,
+            (true, Some(token)) if token == CONFIRM_TOKEN => {
+                OverridePolicy::Preconfirmed(ConfirmToken)
+            }
+            (true | false, Some(_)) => {
+                return Err(OverrideConfirmationError);
+            }
+        };
+        Ok(Self { override_policy })
+    }
+}
+
+#[derive(Debug, Clone, Default)]
+pub(crate) enum OverridePolicy {
+    #[default]
+    Forbid,
+    RequireInteractive,
+    Preconfirmed(ConfirmToken),
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct ConfirmToken;
+
+#[derive(Debug, Clone)]
+pub(crate) struct OverrideConfirmationError;
+
+impl std::fmt::Display for OverrideConfirmationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{OVERRIDE_UNCONFIRMED}: --allow-unredacted-secrets requires confirmation token {CONFIRM_TOKEN:?}"
+        )
+    }
+}
+
+#[derive(Debug, Clone, Default)]
+pub(crate) struct SecretScanOutcome {
+    per_file_outcomes: Vec<PerFileOutcome>,
+    findings: Vec<PendingFinding>,
+    finding_anchors: BTreeMap<PathBuf, String>,
+    scanned_files: Arc<BTreeSet<PathBuf>>,
+    // Subset of `scanned_files` restricted to paths matched by
+    // `files::is_secret_scan_sidecar` (e.g. `.env`, `.env.*`, `*.env`).
+    // These paths have no plugin coverage by design, so their `core:file`
+    // anchor is the only catalog row tracking briefing_blocked + content_hash
+    // for that path. The anchor-reconciliation pass in `anchors.rs` iterates
+    // this set on every run to clear stale blocks once secrets are removed.
+    scanned_sidecars: BTreeSet<PathBuf>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum PerFileOutcome {
+    Clean {
+        file: PathBuf,
+    },
+    Blocked {
+        file: PathBuf,
+        reason: BriefingBlockReason,
+        findings: Vec<Detection>,
+    },
+    Overridden {
+        file: PathBuf,
+        findings: Vec<Detection>,
+    },
+}
+
+impl SecretScanOutcome {
+    #[cfg(test)]
+    pub(crate) fn per_file_outcomes(&self) -> &[PerFileOutcome] {
+        &self.per_file_outcomes
+    }
+
+    pub(crate) fn briefing_blocks_shared(&self) -> Arc<BTreeMap<PathBuf, BriefingBlockReason>> {
+        Arc::new(
+            self.per_file_outcomes
+                .iter()
+                .filter_map(|outcome| match outcome {
+                    PerFileOutcome::Blocked { file, reason, .. } => Some((file.clone(), *reason)),
+                    PerFileOutcome::Clean { .. } | PerFileOutcome::Overridden { .. } => None,
+                })
+                .collect(),
+        )
+    }
+
+    pub(crate) fn briefing_block_for(&self, file: &Path) -> Option<BriefingBlockReason> {
+        self.per_file_outcomes
+            .iter()
+            .find_map(|outcome| match outcome {
+                PerFileOutcome::Blocked {
+                    file: blocked_file,
+                    reason,
+                    ..
+                } if blocked_file == file => Some(*reason),
+                PerFileOutcome::Clean { .. }
+                | PerFileOutcome::Blocked { .. }
+                | PerFileOutcome::Overridden { .. } => None,
+            })
+    }
+
+    pub(crate) fn scanned_files_shared(&self) -> Arc<BTreeSet<PathBuf>> {
+        Arc::clone(&self.scanned_files)
+    }
+
+    pub(crate) fn scanned_sidecars(&self) -> &BTreeSet<PathBuf> {
+        &self.scanned_sidecars
+    }
+
+    pub(crate) fn finding_files(&self) -> BTreeSet<PathBuf> {
+        self.findings
+            .iter()
+            .map(|finding| finding.file_path.clone())
+            .collect()
+    }
+
+    pub(crate) fn augment_stats(&self, stats: &mut serde_json::Value) {
+        let override_files = self
+            .per_file_outcomes
+            .iter()
+            .filter_map(|outcome| match outcome {
+                PerFileOutcome::Overridden { file, .. } => Some(file),
+                PerFileOutcome::Clean { .. } | PerFileOutcome::Blocked { .. } => None,
+            })
+            .collect::<Vec<_>>();
+        if override_files.is_empty() {
+            return;
+        }
+        stats["secret_override_used"] = json!(true);
+        stats["secret_override_files_affected"] = json!(
+            override_files
+                .iter()
+                .map(|path| path.display().to_string())
+                .collect::<Vec<_>>()
+        );
+    }
+
+    pub(crate) fn remember_finding_anchors(&mut self, entities: &[(String, EntityRecord)]) {
+        anchors::remember_finding_anchors(self, entities);
+    }
+
+    pub(crate) async fn persist_findings(
+        &mut self,
+        writer: &Writer,
+        run_id: &str,
+        project_root: &Path,
+        started_at: &str,
+    ) -> Result<()> {
+        anchors::ensure_and_emit_findings(self, writer, run_id, project_root, started_at).await
+    }
+}
+
+pub(crate) fn pre_ingest(
+    project_root: &Path,
+    source_files: &[PathBuf],
+    options: &SecretScanOptions,
+) -> Result<SecretScanOutcome> {
+    let project_root = project_root
+        .canonicalize()
+        .with_context(|| format!("canonicalize project root {}", project_root.display()))?;
+    let project_root = project_root.as_path();
+    let scanner = Scanner::new();
+    let (baseline, mut findings) = baseline::load_for_scan(project_root)?;
+    let mut per_file = Vec::new();
+    let mut all_allowed = Vec::new();
+    let mut baseline_matches = Vec::new();
+    let mut scanned_files = BTreeSet::new();
+    let mut scanned_sidecars = BTreeSet::new();
+    let scans = scan_source_files_parallel(source_files, |buf| scanner.scan_bytes(buf))?;
+
+    for scan in scans {
+        let canonical_file = scan.canonical_file;
+        scanned_files.insert(canonical_file.clone());
+        if files::is_secret_scan_sidecar(&canonical_file) {
+            scanned_sidecars.insert(canonical_file.clone());
+        }
+        let baseline_file = project_relative_path(project_root, &canonical_file);
+        let SuppressionResult {
+            allowed,
+            fired_entries,
+            ..
+        } = baseline.suppress(scan.detections, &baseline_file);
+        if !allowed.is_empty() {
+            all_allowed.extend(
+                allowed
+                    .iter()
+                    .cloned()
+                    .map(|detection| (canonical_file.clone(), detection)),
+            );
+        }
+        baseline_matches.extend(fired_entries.into_iter().map(|entry| PendingFinding {
+            file_path: normalize_project_path(project_root, &entry.file_path),
+            rule_id: baseline::baseline_match_rule_id(),
+            kind: FindingKind::Fact,
+            severity: FindingSeverity::Info,
+            confidence: FindingConfidence::Baseline,
+            message: format!(
+                "Secret baseline entry matched {}:{}",
+                entry.file_path.display(),
+                entry.entry.line_number
+            ),
+            evidence: json!({
+                "file_path": entry.file_path,
+                "line_number": entry.entry.line_number,
+                "rule": entry.entry.rule_type.as_str(),
+            }),
+        }));
+        per_file.push((canonical_file, allowed));
+    }
+
+    let override_confirmed = confirm_override_if_needed(project_root, &all_allowed, options);
+    let mut per_file_outcomes = Vec::new();
+    let mut override_detections = BTreeMap::<PathBuf, Vec<Detection>>::new();
+    findings.extend(baseline_matches);
+
+    for (file, allowed) in per_file {
+        if allowed.is_empty() {
+            per_file_outcomes.push(PerFileOutcome::Clean { file });
+            continue;
+        }
+        // ADR-013 §"Override — --allow-unredacted-secrets": each detection
+        // emits its own `CLA-SEC-SECRET-DETECTED` finding regardless of
+        // whether the operator subsequently overrode the block. The override
+        // finding (`CLA-SEC-UNREDACTED-SECRETS-ALLOWED`) is additive — it
+        // records the operator decision but does not replace the
+        // per-(rule,file,line) audit row, so a security review running
+        // `filigree list --rule-id=CLA-SEC-SECRET-DETECTED` enumerates the
+        // full detection population.
+        findings.extend(
+            allowed
+                .iter()
+                .map(|detection| secret_detected_finding(&file, detection)),
+        );
+        if override_confirmed {
+            override_detections.insert(file.clone(), allowed.clone());
+            per_file_outcomes.push(PerFileOutcome::Overridden {
+                file,
+                findings: allowed,
+            });
+        } else {
+            per_file_outcomes.push(PerFileOutcome::Blocked {
+                file,
+                reason: BriefingBlockReason::SecretPresent,
+                findings: allowed,
+            });
+        }
+    }
+
+    for file in override_detections.keys() {
+        let detections = override_detections.get(file).map_or(&[][..], Vec::as_slice);
+        findings.push(PendingFinding {
+            file_path: file.clone(),
+            rule_id: SECRET_OVERRIDE_ALLOWED,
+            kind: FindingKind::Defect,
+            severity: FindingSeverity::Error,
+            confidence: FindingConfidence::OperatorOverride,
+            message: format!(
+                "Operator allowed unredacted secrets in {}",
+                display_relative(project_root, file)
+            ),
+            evidence: json!({
+                "file_path": display_relative(project_root, file),
+                "override_used": true,
+                "detections": detections.iter().map(detection_audit_json).collect::<Vec<_>>(),
+            }),
+        });
+    }
+
+    Ok(SecretScanOutcome {
+        per_file_outcomes,
+        findings,
+        finding_anchors: BTreeMap::new(),
+        scanned_files: Arc::new(scanned_files),
+        scanned_sidecars,
+    })
+}
+
+#[derive(Debug)]
+struct SourceFileScan {
+    canonical_file: PathBuf,
+    detections: Vec<Detection>,
+}
+
+fn scan_source_files_parallel<F>(
+    source_files: &[PathBuf],
+    scan_bytes: F,
+) -> Result<Vec<SourceFileScan>>
+where
+    F: Fn(&[u8]) -> Vec<Detection> + Sync,
+{
+    if source_files.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let worker_count = source_files.len().min(
+        thread::available_parallelism()
+            .map_or(1, usize::from)
+            .max(1),
+    );
+    let next_file = AtomicUsize::new(0);
+    let results = (0..source_files.len())
+        .map(|_| Mutex::new(None))
+        .collect::<Vec<_>>();
+
+    thread::scope(|scope| {
+        for _ in 0..worker_count {
+            let next_file = &next_file;
+            let results = &results;
+            let scan_bytes = &scan_bytes;
+            scope.spawn(move || {
+                loop {
+                    let idx = next_file.fetch_add(1, Ordering::Relaxed);
+                    let Some(file) = source_files.get(idx) else {
+                        break;
+                    };
+                    let result = scan_one_source_file(file, scan_bytes);
+                    *results[idx]
+                        .lock()
+                        .expect("parallel secret-scan result lock poisoned") = Some(result);
+                }
+            });
+        }
+    });
+
+    results
+        .into_iter()
+        .map(|slot| {
+            slot.into_inner()
+                .expect("parallel secret-scan result lock poisoned")
+                .expect("parallel secret-scan worker did not fill result")
+        })
+        .collect()
+}
+
+fn scan_one_source_file<F>(file: &Path, scan_bytes: &F) -> Result<SourceFileScan>
+where
+    F: Fn(&[u8]) -> Vec<Detection> + Sync + ?Sized,
+{
+    let canonical_file = canonical_or_original(file);
+    let buf = fs::read(file).with_context(|| format!("read {}", file.display()))?;
+    let detections = scan_bytes(&buf);
+    Ok(SourceFileScan {
+        canonical_file,
+        detections,
+    })
+}
+
+fn confirm_override_if_needed(
+    project_root: &Path,
+    allowed: &[(PathBuf, Detection)],
+    options: &SecretScanOptions,
+) -> bool {
+    if allowed.is_empty() {
+        return false;
+    }
+    match options.override_policy {
+        OverridePolicy::Forbid => false,
+        OverridePolicy::Preconfirmed(_) => true,
+        OverridePolicy::RequireInteractive => {
+            print_detection_list(project_root, allowed);
+            if io::stdin().is_terminal() {
+                eprint!("Type '{CONFIRM_TOKEN}' to proceed: ");
+                let _ = io::stderr().flush();
+                let mut input = String::new();
+                if io::stdin().read_line(&mut input).is_ok() && input.trim() == CONFIRM_TOKEN {
+                    return true;
+                }
+            }
+            abort_unconfirmed_override();
+        }
+    }
+}
+
+fn print_detection_list(project_root: &Path, allowed: &[(PathBuf, Detection)]) {
+    for (file, detection) in allowed {
+        eprintln!(
+            "{}:{} {}",
+            display_relative(project_root, file),
+            detection.line_number,
+            detection.rule_id
+        );
+    }
+}
+
+fn detection_audit_json(detection: &Detection) -> serde_json::Value {
+    json!({
+        "rule_id": detection.rule_id,
+        "rule": detection.detect_secrets_type.as_str(),
+        "line_number": detection.line_number,
+        "hashed_secret_hex": detection.hashed_secret.to_string(),
+    })
+}
+
+fn abort_unconfirmed_override() -> ! {
+    eprintln!("{OVERRIDE_UNCONFIRMED}: --allow-unredacted-secrets requires confirmation");
+    std::process::exit(78);
+}
+
+pub(super) fn canonical_or_original(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|err| {
+        tracing::warn!(
+            path = %path.display(),
+            error = %err,
+            "using non-canonical secret-scan path after canonicalization failed"
+        );
+        path.to_path_buf()
+    })
+}
+
+fn normalize_project_path(root: &Path, path: &Path) -> PathBuf {
+    canonical_or_original(&root.join(path))
+}
+
+fn project_relative_path(root: &Path, path: &Path) -> PathBuf {
+    relative_path(root, path).unwrap_or_else(|| path.to_path_buf())
+}
+
+pub(super) fn display_relative(root: &Path, path: &Path) -> String {
+    relative_path(root, path)
+        .unwrap_or_else(|| path.to_path_buf())
+        .display()
+        .to_string()
+}
+
+fn relative_path(root: &Path, path: &Path) -> Option<PathBuf> {
+    let root = canonical_or_original(root);
+    let path = canonical_or_original(path);
+    path.strip_prefix(root).ok().map(Path::to_path_buf)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        ConfirmToken, OverridePolicy, PerFileOutcome, SecretScanOptions, display_relative,
+        pre_ingest, scan_source_files_parallel,
+    };
+    use std::sync::{Arc, Mutex};
+
+    #[cfg(unix)]
+    #[test]
+    fn display_relative_handles_noncanonical_root_with_canonical_file() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let real_root = tmp.path().join("real");
+        let link_root = tmp.path().join("link");
+        std::fs::create_dir(&real_root).expect("create real root");
+        std::os::unix::fs::symlink(&real_root, &link_root).expect("symlink project root");
+        let file = real_root.join(".env");
+        std::fs::write(&file, b"token=example\n").expect("write fixture");
+        let canonical_file = file.canonicalize().expect("canonical file");
+
+        assert_eq!(display_relative(&link_root, &canonical_file), ".env");
+    }
+
+    #[test]
+    fn scan_source_files_parallel_scans_on_workers_and_preserves_input_order() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let files = (0..8)
+            .map(|idx| {
+                let path = tmp.path().join(format!("{idx}.txt"));
+                std::fs::write(&path, format!("file-{idx}\n")).expect("write scan file");
+                path
+            })
+            .collect::<Vec<_>>();
+        let caller_thread = std::thread::current().id();
+        let scan_threads = Arc::new(Mutex::new(Vec::new()));
+        let seen = Arc::clone(&scan_threads);
+
+        let scans = scan_source_files_parallel(&files, |buf| {
+            seen.lock()
+                .expect("record thread")
+                .push(std::thread::current().id());
+            assert!(buf.starts_with(b"file-"));
+            Vec::new()
+        })
+        .expect("parallel scan");
+
+        assert_eq!(
+            scans
+                .iter()
+                .map(|scan| scan.canonical_file.clone())
+                .collect::<Vec<_>>(),
+            files
+                .iter()
+                .map(|file| file.canonicalize().expect("canonical test file"))
+                .collect::<Vec<_>>()
+        );
+        assert!(
+            scan_threads
+                .lock()
+                .expect("scan threads")
+                .iter()
+                .any(|thread_id| *thread_id != caller_thread),
+            "expected at least one scan to run on a worker thread"
+        );
+    }
+
+    #[test]
+    fn pre_ingest_records_file_outcomes_without_side_channel_state() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let clean = tmp.path().join("clean.txt");
+        let secret = tmp.path().join("secret.txt");
+        std::fs::write(&clean, b"hello\n").expect("write clean");
+        std::fs::write(&secret, b"key = 'AKIAIOSFODNN7EXAMPLE'\n").expect("write secret");
+
+        let outcome = pre_ingest(
+            tmp.path(),
+            &[clean.clone(), secret.clone()],
+            &SecretScanOptions {
+                override_policy: OverridePolicy::Preconfirmed(ConfirmToken),
+            },
+        )
+        .expect("pre-ingest");
+
+        assert!(matches!(
+            outcome.per_file_outcomes()[0],
+            PerFileOutcome::Clean { .. }
+        ));
+        let PerFileOutcome::Overridden { file, findings } = &outcome.per_file_outcomes()[1] else {
+            panic!("secret file should be recorded as overridden");
+        };
+        assert_eq!(file, &secret.canonicalize().expect("canonical secret"));
+        assert_eq!(findings.len(), 1);
+        assert!(outcome.briefing_blocks_shared().is_empty());
+    }
+}
diff --git a/crates/clarion-cli/src/secret_scan/anchors.rs b/crates/clarion-cli/src/secret_scan/anchors.rs
new file mode 100644
index 00000000..c83fb7a1
--- /dev/null
+++ b/crates/clarion-cli/src/secret_scan/anchors.rs
@@ -0,0 +1,165 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+};
+
+use anyhow::{Context, Result};
+use clarion_storage::{
+    Writer,
+    commands::{EntityRecord, WriterCmd},
+};
+
+use super::{SecretScanOutcome, canonical_or_original, display_relative};
+use crate::secret_scan::findings::emit_findings;
+
+pub(super) fn remember_finding_anchors(
+    outcome: &mut SecretScanOutcome,
+    entities: &[(String, EntityRecord)],
+) {
+    for (id, record) in entities {
+        let Some(path) = record.source_file_path.as_deref() else {
+            continue;
+        };
+        let key = canonical_or_original(Path::new(path));
+        if record.kind == "module" || !outcome.finding_anchors.contains_key(&key) {
+            outcome.finding_anchors.insert(key, id.clone());
+        }
+    }
+}
+
+pub(super) async fn ensure_and_emit_findings(
+    outcome: &mut SecretScanOutcome,
+    writer: &Writer,
+    run_id: &str,
+    project_root: &Path,
+    started_at: &str,
+) -> Result<()> {
+    ensure_finding_anchors(outcome, writer, project_root, started_at).await?;
+    emit_findings(
+        writer,
+        run_id,
+        started_at,
+        outcome,
+        &outcome.finding_anchors,
+    )
+    .await
+}
+
+async fn ensure_finding_anchors(
+    outcome: &mut SecretScanOutcome,
+    writer: &Writer,
+    project_root: &Path,
+    started_at: &str,
+) -> Result<()> {
+    // Pass 1: paths with active findings this run get anchored with whatever
+    // briefing_blocks reason applies (or none, if an override cleared it).
+    for file in outcome.finding_files() {
+        let key = canonical_or_original(&file);
+        if outcome.finding_anchors.contains_key(&key) {
+            continue;
+        }
+        upsert_finding_anchor(outcome, writer, project_root, started_at, key).await?;
+    }
+    // Pass 2: every sidecar path scanned this run that pass 1 did not anchor
+    // (i.e. no current finding). The upsert refreshes properties + content_hash
+    // on a sidecar whose secret was cleaned between runs (the old anchor row
+    // would otherwise keep briefing_blocked=secret_present and a stale hash
+    // forever, since pass 1 only sees current findings). Always-clean sidecars
+    // also get a first-time anchor here. Scope is intentionally narrowed to
+    // sidecars: source files have plugin entities (registered by
+    // `remember_finding_anchors` before this function runs), so their
+    // `finding_anchors` entry already points at the plugin entity and pass 1's
+    // `contains_key` guard skips them. Removed files (no longer in
+    // scanned_sidecars) keep their stale anchor — a separate concern tracked
+    // outside this fix.
+    for file in outcome.scanned_sidecars().clone() {
+        let key = canonical_or_original(&file);
+        if outcome.finding_anchors.contains_key(&key) {
+            continue;
+        }
+        upsert_finding_anchor(outcome, writer, project_root, started_at, key).await?;
+    }
+    Ok(())
+}
+
+async fn upsert_finding_anchor(
+    outcome: &mut SecretScanOutcome,
+    writer: &Writer,
+    project_root: &Path,
+    started_at: &str,
+    key: PathBuf,
+) -> Result<()> {
+    let id = secret_finding_anchor_id(project_root, &key);
+    let relative = display_relative(project_root, &key);
+    let short_name = key
+        .file_name()
+        .and_then(|name| name.to_str())
+        .unwrap_or(&relative)
+        .to_owned();
+    let mut properties = serde_json::Map::new();
+    properties.insert("finding_anchor".to_owned(), serde_json::json!(true));
+    if let Some(reason) = outcome.briefing_block_for(&key) {
+        properties.insert(
+            "briefing_blocked".to_owned(),
+            serde_json::Value::String(reason.as_str().to_owned()),
+        );
+    }
+    let record = EntityRecord {
+        id: id.clone(),
+        plugin_id: "core".to_owned(),
+        kind: "file".to_owned(),
+        name: relative,
+        short_name,
+        parent_id: None,
+        source_file_id: None,
+        source_file_path: Some(key.display().to_string()),
+        source_byte_start: None,
+        source_byte_end: None,
+        source_line_start: None,
+        source_line_end: None,
+        properties_json: serde_json::Value::Object(properties).to_string(),
+        content_hash: file_content_hash(&key),
+        summary_json: None,
+        wardline_json: None,
+        first_seen_commit: None,
+        last_seen_commit: None,
+        created_at: started_at.to_owned(),
+        updated_at: started_at.to_owned(),
+    };
+    writer
+        .send_wait(|ack| WriterCmd::InsertEntity {
+            entity: Box::new(record),
+            ack,
+        })
+        .await
+        .map_err(|e| anyhow::anyhow!("{e}"))
+        .with_context(|| format!("InsertEntity for secret finding anchor {id}"))?;
+    outcome.finding_anchors.insert(key, id);
+    Ok(())
+}
+
+fn secret_finding_anchor_id(project_root: &Path, file: &Path) -> String {
+    // ADR-003 grammar: file-kind entity IDs are `core:file:{qualified_name}`
+    // where the qualified name is the canonical project-relative path. Earlier
+    // revisions hashed the path with blake3, which embedded drift state into
+    // the primary ID and was explicitly called out as non-conforming in
+    // ADR-003. The path itself is the canonical identity.
+    let relative = display_relative(project_root, file);
+    format!("core:file:{relative}")
+}
+
+fn file_content_hash(path: &Path) -> Option<String> {
+    match fs::read(path) {
+        Ok(bytes) => Some(blake3::hash(&bytes).to_hex().to_string()),
+        Err(err) => {
+            tracing::warn!(
+                path = %path.display(),
+                error = %err,
+                "secret-scan finding-anchor: content-hash read failed; entity briefing-block \
+                 lookups may fail for this path because the finding anchor will land without a \
+                 content_hash"
+            );
+            None
+        }
+    }
+}
diff --git a/crates/clarion-cli/src/secret_scan/baseline.rs b/crates/clarion-cli/src/secret_scan/baseline.rs
new file mode 100644
index 00000000..268038a8
--- /dev/null
+++ b/crates/clarion-cli/src/secret_scan/baseline.rs
@@ -0,0 +1,44 @@
+use std::path::Path;
+
+use anyhow::{Context, Result};
+use clarion_scanner::{Baseline, BaselineError};
+use serde_json::json;
+
+use super::normalize_project_path;
+use crate::secret_scan::findings::{
+    FindingConfidence, FindingKind, FindingSeverity, PendingFinding,
+};
+
+const BASELINE_NO_JUSTIFICATION: &str = "CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION";
+const BASELINE_MATCH: &str = "CLA-INFRA-SECRET-BASELINE-MATCH";
+
+pub(super) fn load_for_scan(project_root: &Path) -> Result<(Baseline, Vec<PendingFinding>)> {
+    let path = project_root.join(".clarion/secrets-baseline.yaml");
+    match clarion_scanner::load_baseline(&path) {
+        Ok(baseline) => Ok((baseline, Vec::new())),
+        Err(BaselineError::MissingJustifications { entries }) => Ok((
+            Baseline::empty(),
+            entries
+                .into_iter()
+                .map(|entry| PendingFinding {
+                    file_path: normalize_project_path(project_root, &entry.file),
+                    rule_id: BASELINE_NO_JUSTIFICATION,
+                    kind: FindingKind::Defect,
+                    severity: FindingSeverity::Error,
+                    confidence: FindingConfidence::Schema,
+                    message: format!(
+                        "Secret baseline entry missing justification at {}:{}",
+                        entry.file.display(),
+                        entry.line
+                    ),
+                    evidence: json!({"file_path": entry.file, "line_number": entry.line}),
+                })
+                .collect(),
+        )),
+        Err(err) => Err(err).context("load secret baseline"),
+    }
+}
+
+pub(super) fn baseline_match_rule_id() -> &'static str {
+    BASELINE_MATCH
+}
diff --git a/crates/clarion-cli/src/secret_scan/files.rs b/crates/clarion-cli/src/secret_scan/files.rs
new file mode 100644
index 00000000..b4cc74fd
--- /dev/null
+++ b/crates/clarion-cli/src/secret_scan/files.rs
@@ -0,0 +1,169 @@
+use std::{
+    collections::BTreeSet,
+    path::{Path, PathBuf},
+};
+
+use ignore::{DirEntry, WalkBuilder};
+
+use super::canonical_or_original;
+
+const SKIP_DIRS: &[&str] = &[
+    ".clarion",
+    ".git",
+    ".hg",
+    ".svn",
+    ".jj",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+];
+
+pub(crate) fn collect_scan_files(root: &Path, source_files: &[PathBuf]) -> Vec<PathBuf> {
+    let mut out: BTreeSet<PathBuf> = source_files
+        .iter()
+        .map(|path| canonical_or_original(path))
+        .collect();
+    for path in collect_secret_scan_sidecars(root) {
+        out.insert(canonical_or_original(&path));
+    }
+    out.into_iter().collect()
+}
+
+fn collect_secret_scan_sidecars(root: &Path) -> Vec<PathBuf> {
+    let mut out = Vec::new();
+    let mut skipped: u64 = 0;
+    let mut builder = WalkBuilder::new(root);
+    builder
+        .follow_links(false)
+        .hidden(false)
+        .ignore(false)
+        .git_ignore(false)
+        .git_global(false)
+        .git_exclude(false)
+        .parents(false)
+        .require_git(false)
+        .filter_entry(|entry| !is_skipped_dir(entry));
+
+    for result in builder.build() {
+        match result {
+            Ok(entry) => {
+                let Some(file_type) = entry.file_type() else {
+                    continue;
+                };
+                let path = entry.into_path();
+                if file_type.is_file() && is_secret_scan_sidecar(&path) {
+                    out.push(path);
+                }
+            }
+            Err(err) => {
+                tracing::warn!(
+                    error = %err,
+                    "sidecar walk: skipping unreadable entry; secret-scan coverage is incomplete \
+                     for this path",
+                );
+                skipped += 1;
+            }
+        }
+    }
+
+    if skipped > 0 {
+        tracing::warn!(
+            skipped = skipped,
+            root = %root.display(),
+            "sidecar walk skipped {skipped} unreadable entr{suffix}; secret-scan gate is \
+             incomplete for those paths",
+            suffix = if skipped == 1 { "y" } else { "ies" },
+        );
+    }
+    out
+}
+
+pub(super) fn is_secret_scan_sidecar(path: &Path) -> bool {
+    let file_name = path.file_name().and_then(|name| name.to_str());
+    file_name.is_some_and(|name| name == ".env" || name.starts_with(".env."))
+        || path
+            .extension()
+            .and_then(|extension| extension.to_str())
+            .is_some_and(|extension| extension.eq_ignore_ascii_case("env"))
+}
+
+fn is_skipped_dir(entry: &DirEntry) -> bool {
+    entry
+        .file_type()
+        .is_some_and(|file_type| file_type.is_dir())
+        && entry
+            .file_name()
+            .to_str()
+            .is_some_and(|name| SKIP_DIRS.contains(&name))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::collect_scan_files;
+    use std::path::{Path, PathBuf};
+
+    #[test]
+    fn sidecar_walk_collects_dotenv_variants_and_skips_known_dirs() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let root = tmp.path();
+        write(root.join("src/app.py"), "print('ok')\n");
+        write(root.join(".env"), "TOKEN=one\n");
+        write(root.join(".env.local"), "TOKEN=two\n");
+        write(root.join(".env.production"), "TOKEN=three\n");
+        write(root.join("nested/service.env"), "TOKEN=four\n");
+        write(root.join("nested/.env"), "TOKEN=five\n");
+        write(root.join("nested/not-env.txt"), "TOKEN=six\n");
+        write(root.join(".clarion/.env"), "TOKEN=skip\n");
+        write(root.join("node_modules/.env"), "TOKEN=skip\n");
+
+        let files = collect_scan_files(root, &[root.join("src/app.py")]);
+        let rel = relative_names(root, files);
+
+        assert!(rel.contains(&".env".to_owned()));
+        assert!(rel.contains(&".env.local".to_owned()));
+        assert!(rel.contains(&".env.production".to_owned()));
+        assert!(rel.contains(&"nested/service.env".to_owned()));
+        assert!(rel.contains(&"nested/.env".to_owned()));
+        assert!(rel.contains(&"src/app.py".to_owned()));
+        assert!(!rel.contains(&"nested/not-env.txt".to_owned()));
+        assert!(!rel.contains(&".clarion/.env".to_owned()));
+        assert!(!rel.contains(&"node_modules/.env".to_owned()));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn sidecar_walk_does_not_follow_directory_symlinks() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let root = tmp.path().join("root");
+        let outside = tmp.path().join("outside");
+        std::fs::create_dir(&root).expect("create root");
+        std::fs::create_dir(&outside).expect("create outside");
+        write(outside.join(".env"), "TOKEN=outside\n");
+        std::os::unix::fs::symlink(&outside, root.join("linked")).expect("symlink");
+
+        let files = collect_scan_files(&root, &[]);
+        let rel = relative_names(&root, files);
+
+        assert!(!rel.contains(&"linked/.env".to_owned()));
+    }
+
+    fn write(path: PathBuf, content: &str) {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).expect("create parent");
+        }
+        std::fs::write(path, content).expect("write fixture");
+    }
+
+    fn relative_names(root: &Path, files: Vec<PathBuf>) -> Vec<String> {
+        let root = root.canonicalize().expect("canonical root");
+        files
+            .into_iter()
+            .map(|path| {
+                path.strip_prefix(&root)
+                    .expect("scan path under root")
+                    .display()
+                    .to_string()
+            })
+            .collect()
+    }
+}
diff --git a/crates/clarion-cli/src/secret_scan/findings.rs b/crates/clarion-cli/src/secret_scan/findings.rs
new file mode 100644
index 00000000..74539014
--- /dev/null
+++ b/crates/clarion-cli/src/secret_scan/findings.rs
@@ -0,0 +1,229 @@
+use std::{
+    collections::BTreeMap,
+    path::{Path, PathBuf},
+};
+
+use anyhow::{Context, Result};
+use clarion_scanner::{Detection, SecretCategory};
+use clarion_storage::{
+    Writer,
+    commands::{FindingRecord, WriterCmd},
+};
+use serde_json::json;
+
+use super::SecretScanOutcome;
+
+const SECRET_DETECTED: &str = "CLA-SEC-SECRET-DETECTED";
+
+#[derive(Debug, Clone)]
+pub(super) struct PendingFinding {
+    pub(super) file_path: PathBuf,
+    pub(super) rule_id: &'static str,
+    pub(super) kind: FindingKind,
+    pub(super) severity: FindingSeverity,
+    pub(super) confidence: FindingConfidence,
+    pub(super) message: String,
+    pub(super) evidence: serde_json::Value,
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum FindingKind {
+    Defect,
+    Fact,
+    Classification,
+    Metric,
+    Suggestion,
+}
+
+impl FindingKind {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Defect => "defect",
+            Self::Fact => "fact",
+            Self::Classification => "classification",
+            Self::Metric => "metric",
+            Self::Suggestion => "suggestion",
+        }
+    }
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum FindingSeverity {
+    Info,
+    Warn,
+    Error,
+    Critical,
+    None,
+}
+
+impl FindingSeverity {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Info => "INFO",
+            Self::Warn => "WARN",
+            Self::Error => "ERROR",
+            Self::Critical => "CRITICAL",
+            Self::None => "NONE",
+        }
+    }
+}
+
+#[allow(dead_code)]
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub(super) enum FindingConfidence {
+    ScoredPattern(f64),
+    ScoredEntropy(f64),
+    Baseline,
+    OperatorOverride,
+    Schema,
+    Unknown,
+}
+
+impl FindingConfidence {
+    fn value(self) -> Option<f64> {
+        match self {
+            Self::ScoredPattern(value) | Self::ScoredEntropy(value) => Some(value),
+            Self::Baseline | Self::OperatorOverride | Self::Schema => Some(1.0),
+            Self::Unknown => None,
+        }
+    }
+
+    fn basis(self) -> Option<&'static str> {
+        match self {
+            Self::ScoredPattern(_) => Some("pattern"),
+            Self::ScoredEntropy(_) => Some("entropy"),
+            Self::Baseline => Some("baseline"),
+            Self::OperatorOverride => Some("operator_override"),
+            Self::Schema => Some("baseline_schema"),
+            Self::Unknown => None,
+        }
+    }
+}
+
+pub(crate) async fn emit_findings(
+    writer: &Writer,
+    run_id: &str,
+    started_at: &str,
+    outcome: &SecretScanOutcome,
+    entity_anchors: &BTreeMap<PathBuf, String>,
+) -> Result<()> {
+    for pending in &outcome.findings {
+        let entity_id =
+            finding_entity_id(&pending.file_path, entity_anchors).with_context(|| {
+                format!("anchor secret finding for {}", pending.file_path.display())
+            })?;
+        // Deterministic, run-scoped id so a `--resume` re-walk regenerates the
+        // SAME id and `InsertFinding`'s upsert is idempotent (REQ-FINDING-05).
+        // A random UUID would instead create a duplicate finding row on every
+        // resume (the id never collides, so the upsert never fires). The digest
+        // covers the anchor entity, rule, and evidence (file + line + hashed
+        // secret), which uniquely identify a detection within a run.
+        let discriminator = blake3::hash(
+            format!(
+                "{entity_id}\u{0}{}\u{0}{}",
+                pending.rule_id, pending.evidence
+            )
+            .as_bytes(),
+        )
+        .to_hex();
+        let finding_id = format!("core:finding:{run_id}:secret:{discriminator}");
+        writer
+            .send_wait(|ack| WriterCmd::InsertFinding {
+                finding: Box::new(FindingRecord {
+                    id: finding_id.clone(),
+                    tool: "clarion".to_owned(),
+                    tool_version: env!("CARGO_PKG_VERSION").to_owned(),
+                    run_id: run_id.to_owned(),
+                    rule_id: pending.rule_id.to_owned(),
+                    kind: pending.kind.as_str().to_owned(),
+                    severity: pending.severity.as_str().to_owned(),
+                    confidence: pending.confidence.value(),
+                    confidence_basis: pending.confidence.basis().map(str::to_owned),
+                    entity_id,
+                    related_entities_json: "[]".to_owned(),
+                    message: pending.message.clone(),
+                    evidence_json: pending.evidence.to_string(),
+                    properties_json: "{}".to_owned(),
+                    supports_json: "[]".to_owned(),
+                    supported_by_json: "[]".to_owned(),
+                    created_at: started_at.to_owned(),
+                    updated_at: started_at.to_owned(),
+                }),
+                ack,
+            })
+            .await
+            .map_err(|e| anyhow::anyhow!("{e}"))
+            .with_context(|| format!("InsertFinding {finding_id}"))?;
+    }
+    Ok(())
+}
+
+pub(super) fn secret_detected_finding(file: &Path, detection: &Detection) -> PendingFinding {
+    PendingFinding {
+        file_path: file.to_path_buf(),
+        rule_id: SECRET_DETECTED,
+        kind: FindingKind::Defect,
+        severity: FindingSeverity::Error,
+        confidence: if detection.category == SecretCategory::HighEntropy {
+            FindingConfidence::ScoredEntropy(0.6)
+        } else {
+            FindingConfidence::ScoredPattern(1.0)
+        },
+        message: format!(
+            "{} detected in {}:{}",
+            detection.rule_id,
+            file.display(),
+            detection.line_number
+        ),
+        evidence: json!({
+            "file_path": file,
+            "line_number": detection.line_number,
+            "rule": detection.rule_id,
+            "hashed_secret_hex": detection.hashed_secret.to_string(),
+        }),
+    }
+}
+
+fn finding_entity_id(file_path: &Path, anchors: &BTreeMap<PathBuf, String>) -> Option<String> {
+    anchors.get(file_path).cloned()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{FindingConfidence, finding_entity_id, secret_detected_finding};
+    use clarion_scanner::{DetectSecretsRule, Detection, HashedSecret, SecretCategory};
+    use std::{collections::BTreeMap, path::PathBuf};
+
+    #[test]
+    fn finding_entity_id_requires_exact_anchor_path() {
+        let mut anchors = BTreeMap::new();
+        anchors.insert(
+            PathBuf::from("/repo/vendor/lib/.env"),
+            "core:file:vendor".to_owned(),
+        );
+
+        assert_eq!(
+            finding_entity_id(PathBuf::from("lib/.env").as_path(), &anchors),
+            None
+        );
+    }
+
+    #[test]
+    fn confidence_basis_uses_detection_category_not_rule_id_prefix() {
+        let detection = Detection {
+            rule_id: "HighEntropyNamedPattern",
+            detect_secrets_type: DetectSecretsRule::AwsAccessKey,
+            category: SecretCategory::CloudCredential,
+            byte_offset: 0,
+            line_number: 7,
+            matched_len: 20,
+            hashed_secret: HashedSecret::from_bytes([1u8; 20]),
+        };
+
+        let finding = secret_detected_finding(PathBuf::from("demo.sec").as_path(), &detection);
+
+        assert_eq!(finding.confidence, FindingConfidence::ScoredPattern(1.0));
+    }
+}
diff --git a/crates/clarion-cli/src/serve.rs b/crates/clarion-cli/src/serve.rs
index 20820488..b74093d9 100644
--- a/crates/clarion-cli/src/serve.rs
+++ b/crates/clarion-cli/src/serve.rs
@@ -1,13 +1,16 @@
 use std::fs;
 use std::io::BufReader;
-use std::path::Path;
-use std::sync::Arc;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, mpsc};
+use std::thread;
+use std::time::Duration;
 
 use anyhow::{Context, Result, anyhow, ensure};
 use clarion_core::{
+    ClaudeCliProvider, ClaudeCliProviderConfig, CodexCliProvider, CodexCliProviderConfig,
     LlmProvider, OpenRouterProvider, OpenRouterProviderConfig, Recording, RecordingProvider,
 };
-use clarion_mcp::config::{McpConfig, ProviderSelection, select_provider_with_env};
+use clarion_mcp::config::{LlmConfig, McpConfig, ProviderSelection, select_provider_with_env};
 use clarion_mcp::filigree::FiligreeHttpClient;
 use clarion_storage::{DEFAULT_BATCH_SIZE, DEFAULT_CHANNEL_CAPACITY, ReaderPool, Writer};
 
@@ -23,6 +26,8 @@ pub fn run(path: &Path, config_path: Option<&Path>) -> Result<()> {
     let project_root = path
         .canonicalize()
         .with_context(|| format!("canonicalize project path {}", path.display()))?;
+    let instance_id = crate::instance::load_or_create(&project_root)
+        .context("load Clarion project instance ID")?;
     let default_config_path = path.join("clarion.yaml");
     let config_path = config_path.unwrap_or(&default_config_path);
     let config = if config_path.exists() {
@@ -32,12 +37,126 @@ pub fn run(path: &Path, config_path: Option<&Path>) -> Result<()> {
         McpConfig::default()
     };
     let provider_selection = select_provider_with_env(&config, |name| std::env::var(name).ok())?;
+    let llm_diagnostics = llm_diagnostics(&provider_selection, &config.llm);
     let llm_provider = build_llm_provider(&config, provider_selection, &project_root)?;
-    let filigree_client = FiligreeHttpClient::from_config(&config.integrations.filigree, |name| {
-        std::env::var(name).ok()
-    })
-    .context("build Filigree HTTP client")?;
 
+    // Resolve where Filigree actually listens — prefer the live ethereal port
+    // published in `.filigree/ephemeral.port` over the static configured port
+    // (which goes stale, the dogfood bug) — then build the client against the
+    // resolved URL so `issues_for` reaches the running dashboard. The same
+    // resolution is surfaced by `project_status`.
+    let filigree_resolution = clarion_mcp::filigree_url::resolve_filigree_url(
+        &config.integrations.filigree,
+        &project_root,
+    );
+    let mut filigree_config = config.integrations.filigree.clone();
+    if let Some(resolved) = &filigree_resolution.resolved_url {
+        filigree_config.base_url.clone_from(resolved);
+    }
+    let filigree_client =
+        FiligreeHttpClient::from_config(&filigree_config, |name| std::env::var(name).ok())
+            .context("build Filigree HTTP client")?;
+
+    let diagnostics = clarion_mcp::DiagnosticsContext {
+        llm: llm_diagnostics,
+        filigree: filigree_resolution,
+    };
+
+    // Eagerly validate the DB at boot so a missing/corrupt index fails fast
+    // here rather than deferring to the first reader (or lazily creating an
+    // empty DB) — clarion-e74b6e69e5.
+    let readers = ReaderPool::open_validated(&db_path, 16)
+        .map_err(|err| anyhow!("open reader pool for {}: {err}", db_path.display()))?;
+    let http_project_root = project_root.clone();
+    let http_server = crate::http_read::spawn(
+        http_project_root,
+        readers.clone(),
+        instance_id,
+        &config.serve.http,
+    )
+    .context("start HTTP read API")?;
+    if let Some(server) = http_server.as_ref() {
+        debug_assert!(
+            std::sync::Arc::ptr_eq(server.readers_identity(), readers.identity()),
+            "HTTP read API and MCP stdio must share a single ReaderPool — the HTTP \
+             thread reported a different pool identity than the MCP-side handle. \
+             A refactor that re-opens the pool inside http_read::spawn would \
+             produce exactly this mismatch."
+        );
+    }
+    let stdio = spawn_mcp_stdio(
+        project_root,
+        db_path,
+        readers,
+        config.llm.clone(),
+        llm_provider,
+        filigree_client,
+        diagnostics,
+    )?;
+    supervise_stdio_with_http(stdio, http_server)
+}
+
+/// Capture the LLM policy posture for `project_status`. `live` means a provider
+/// that actually dispatches (`OpenRouter` / Codex / Claude CLIs); the recording
+/// fixture and the disabled state are not live.
+fn llm_diagnostics(selection: &ProviderSelection, llm: &LlmConfig) -> clarion_mcp::LlmDiagnostics {
+    let (provider, live) = match selection {
+        ProviderSelection::Disabled => ("disabled", false),
+        ProviderSelection::Recording => ("recording", false),
+        ProviderSelection::OpenRouter { .. } => ("openrouter", true),
+        ProviderSelection::CodexCli => ("codex_cli", true),
+        ProviderSelection::ClaudeCli => ("claude_cli", true),
+    };
+    clarion_mcp::LlmDiagnostics {
+        provider: provider.to_owned(),
+        live,
+        allow_live_provider: llm.allow_live_provider,
+        cache_max_age_days: llm.cache_max_age_days,
+    }
+}
+
+struct StdioServe {
+    result_rx: mpsc::Receiver<Result<()>>,
+    join: thread::JoinHandle<()>,
+}
+
+fn spawn_mcp_stdio(
+    project_root: PathBuf,
+    db_path: PathBuf,
+    readers: ReaderPool,
+    llm_config: LlmConfig,
+    llm_provider: Option<Arc<dyn LlmProvider>>,
+    filigree_client: Option<FiligreeHttpClient>,
+    diagnostics: clarion_mcp::DiagnosticsContext,
+) -> Result<StdioServe> {
+    let (result_tx, result_rx) = mpsc::channel();
+    let join = thread::Builder::new()
+        .name("clarion-mcp-stdio".to_owned())
+        .spawn(move || {
+            let result = run_mcp_stdio(
+                project_root,
+                &db_path,
+                readers,
+                llm_config,
+                llm_provider,
+                filigree_client,
+                diagnostics,
+            );
+            let _ = result_tx.send(result);
+        })
+        .context("spawn MCP stdio server thread")?;
+    Ok(StdioServe { result_rx, join })
+}
+
+fn run_mcp_stdio(
+    project_root: PathBuf,
+    db_path: &Path,
+    readers: ReaderPool,
+    llm_config: LlmConfig,
+    llm_provider: Option<Arc<dyn LlmProvider>>,
+    filigree_client: Option<FiligreeHttpClient>,
+    diagnostics: clarion_mcp::DiagnosticsContext,
+) -> Result<()> {
     let stdin = std::io::stdin();
     let stdout = std::io::stdout();
     let mut reader = BufReader::new(stdin.lock());
@@ -47,25 +166,24 @@ pub fn run(path: &Path, config_path: Option<&Path>) -> Result<()> {
         .build()
         .context("create MCP runtime")?;
     let _runtime_guard = runtime.enter();
-    let readers = ReaderPool::open(&db_path, 16)
-        .map_err(|err| anyhow!("open reader pool for {}: {err}", db_path.display()))?;
     let mut state = clarion_mcp::ServerState::new(project_root, readers);
     let mut llm_writer = None;
     let mut llm_writer_join = None;
     if let Some(provider) = llm_provider {
         let (writer, handle) = Writer::spawn(
-            db_path.clone(),
+            db_path.to_owned(),
             DEFAULT_BATCH_SIZE,
             DEFAULT_CHANNEL_CAPACITY,
         )
         .map_err(|err| anyhow!("spawn MCP LLM writer for {}: {err}", db_path.display()))?;
-        state = state.with_summary_llm(writer.sender(), config.llm.clone(), provider);
+        state = state.with_summary_llm(writer.sender(), llm_config, provider);
         llm_writer = Some(writer);
         llm_writer_join = Some(handle);
     }
     if let Some(client) = filigree_client {
         state = state.with_filigree_client(Arc::new(client));
     }
+    state = state.with_diagnostics(diagnostics);
 
     let serve_result =
         clarion_mcp::serve_stdio_with_state_on_runtime(&runtime, &state, &mut reader, &mut writer)
@@ -90,6 +208,63 @@ pub fn run(path: &Path, config_path: Option<&Path>) -> Result<()> {
     Ok(())
 }
 
+fn supervise_stdio_with_http(
+    stdio: StdioServe,
+    mut http_server: Option<crate::http_read::HttpReadServer>,
+) -> Result<()> {
+    let serve_result = loop {
+        match stdio.result_rx.recv_timeout(Duration::from_millis(100)) {
+            Ok(result) => break result,
+            Err(mpsc::RecvTimeoutError::Timeout) => {
+                if let Some(server) = http_server.as_mut()
+                    && let Err(err) = server.check_running()
+                {
+                    if let Some(server) = http_server.take()
+                        && let Err(stop_err) = server.shutdown()
+                    {
+                        tracing::warn!(
+                            error = %stop_err,
+                            "failed to stop HTTP read API after supervised failure"
+                        );
+                    }
+                    return Err(err.context("HTTP read API failed while MCP stdio was running"));
+                }
+            }
+            Err(mpsc::RecvTimeoutError::Disconnected) => {
+                stdio
+                    .join
+                    .join()
+                    .map_err(|_| anyhow!("MCP stdio server thread panicked"))?;
+                return Err(anyhow!("MCP stdio server thread exited without a result"));
+            }
+        }
+    };
+    stdio
+        .join
+        .join()
+        .map_err(|_| anyhow!("MCP stdio server thread panicked"))?;
+    let shutdown_result = match http_server {
+        Some(server) => server.shutdown().context("stop HTTP read API"),
+        None => Ok(()),
+    };
+    finish_supervised_result(serve_result, shutdown_result)
+}
+
+fn finish_supervised_result(serve_result: Result<()>, shutdown_result: Result<()>) -> Result<()> {
+    match (serve_result, shutdown_result) {
+        (Ok(()), Ok(())) => Ok(()),
+        (Ok(()), Err(shutdown_err)) => Err(shutdown_err),
+        (Err(serve_err), Ok(())) => Err(serve_err),
+        (Err(serve_err), Err(shutdown_err)) => {
+            tracing::warn!(
+                error = %shutdown_err,
+                "failed to stop HTTP read API after MCP stdio failure"
+            );
+            Err(serve_err)
+        }
+    }
+}
+
 fn build_llm_provider(
     config: &McpConfig,
     selection: ProviderSelection,
@@ -116,6 +291,38 @@ fn build_llm_provider(
             .context("build OpenRouter LLM provider")?;
             Ok(Some(Arc::new(provider)))
         }
+        ProviderSelection::CodexCli => {
+            let provider = CodexCliProvider::from_config(CodexCliProviderConfig {
+                executable: config.llm.codex_cli.executable.clone(),
+                project_root: project_root.to_owned(),
+                model_id: config.llm.model_id.clone(),
+                model: config.llm.codex_cli.model.clone(),
+                profile: config.llm.codex_cli.profile.clone(),
+                sandbox: config.llm.codex_cli.sandbox.as_str().to_owned(),
+                timeout_seconds: config.llm.codex_cli.timeout_seconds,
+            })
+            .context("build Codex CLI LLM provider")?;
+            Ok(Some(Arc::new(provider)))
+        }
+        ProviderSelection::ClaudeCli => {
+            let provider = ClaudeCliProvider::from_config(ClaudeCliProviderConfig {
+                executable: config.llm.claude_cli.executable.clone(),
+                project_root: project_root.to_owned(),
+                model_id: config.llm.model_id.clone(),
+                model: config.llm.claude_cli.model.clone(),
+                permission_mode: config.llm.claude_cli.permission_mode.as_str().to_owned(),
+                tools: config.llm.claude_cli.tools.clone(),
+                timeout_seconds: config.llm.claude_cli.timeout_seconds,
+                max_turns: config.llm.claude_cli.max_turns,
+                no_session_persistence: config.llm.claude_cli.no_session_persistence,
+                exclude_dynamic_system_prompt_sections: config
+                    .llm
+                    .claude_cli
+                    .exclude_dynamic_system_prompt_sections,
+            })
+            .context("build Claude CLI LLM provider")?;
+            Ok(Some(Arc::new(provider)))
+        }
     }
 }
 
@@ -134,3 +341,22 @@ fn load_recording_fixture(config: &McpConfig, project_root: &Path) -> Result<Vec
     serde_json::from_str(&raw)
         .with_context(|| format!("parse RecordingProvider fixture {}", path.display()))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn finish_supervised_result_preserves_stdio_error_over_shutdown_error() {
+        let err = finish_supervised_result(
+            Err(anyhow!("stdio failed first")),
+            Err(anyhow!("HTTP shutdown also failed")),
+        )
+        .expect_err("stdio failure should win");
+
+        assert!(
+            format!("{err:#}").contains("stdio failed first"),
+            "unexpected error: {err:#}"
+        );
+    }
+}
diff --git a/crates/clarion-cli/src/skill_pack.rs b/crates/clarion-cli/src/skill_pack.rs
new file mode 100644
index 00000000..00820bae
--- /dev/null
+++ b/crates/clarion-cli/src/skill_pack.rs
@@ -0,0 +1,359 @@
+//! Embedded `clarion-workflow` skill pack and its on-disk installer.
+//!
+//! The pack is compiled into the binary with `include_str!` (matching the
+//! `include_str!` migration-embedding convention in
+//! `clarion-storage/src/schema.rs`). The asset itself is owned by
+//! `clarion-mcp` (which this crate depends on), so the embed below reaches
+//! *down* the dependency edge rather than inverting it (clarion-04391392c7).
+//! Each entry is `(relative_path, contents)`;
+//! growing the pack with a `references/` directory is a data change here, not a
+//! logic change. The fingerprint over the pack bytes drives drift-aware
+//! re-copy (Phase 3 hook resync + `--skills` idempotency).
+
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, Result};
+
+/// `(relative_path, contents)` for every file in the bundled skill pack.
+pub const SKILL_PACK: &[(&str, &str)] = &[(
+    "SKILL.md",
+    include_str!("../../clarion-mcp/assets/skills/clarion-workflow/SKILL.md"),
+)];
+
+/// The on-disk subdirectory name the pack installs into.
+pub const PACK_DIR_NAME: &str = "clarion-workflow";
+
+/// Deterministic blake3 hex digest over the pack's `(rel_path, contents)`
+/// entries. Order-stable because `SKILL_PACK` is a fixed slice. This is the
+/// drift sentinel: [`installed_fingerprint`] recomputes the same digest over
+/// the files actually on disk and re-copies when they differ. A `.fingerprint`
+/// file is also written next to the installed pack as a human-readable
+/// provenance marker, but it is informational only — it is not read back as
+/// the drift signal (a stale sidecar cannot mask content corruption).
+#[must_use]
+pub fn pack_fingerprint() -> String {
+    let mut hasher = blake3::Hasher::new();
+    for (rel, contents) in SKILL_PACK {
+        hasher.update(rel.as_bytes());
+        hasher.update(&[0u8]);
+        hasher.update(contents.as_bytes());
+        hasher.update(&[0u8]);
+    }
+    hasher.finalize().to_hex().to_string()
+}
+
+/// The two skill roots Clarion installs into, relative to the project root.
+/// `.claude/skills/` is read by Claude Code; `.agents/skills/` is the
+/// tool-agnostic convention so non-Claude agent harnesses find it too.
+const SKILL_ROOTS: &[&str] = &[".claude/skills", ".agents/skills"];
+
+const FINGERPRINT_FILE: &str = ".fingerprint";
+
+/// Outcome of an [`install_skill_pack`] call.
+#[derive(Debug, Clone, Copy)]
+pub struct SkillInstallReport {
+    /// True if the pack bytes were (re)written this call; false if every
+    /// destination already matched the embedded fingerprint.
+    pub copied: bool,
+}
+
+/// Install (or re-sync on drift) the embedded skill pack into both skill roots
+/// under `project_root`, idempotently.
+///
+/// For each root, the pack lands at `<root>/clarion-workflow/`. A
+/// `.fingerprint` file recording [`pack_fingerprint`] is written alongside the
+/// pack files as a provenance marker. If the digest recomputed from the files
+/// on disk in every root (see [`installed_fingerprint`]) already equals the
+/// embedded fingerprint, the call is a no-op (`copied: false`); any content
+/// drift or missing file triggers a re-copy.
+///
+/// Writes are atomic: each pack is staged into a sibling temp directory in the
+/// same skill root (so `rename` stays on one filesystem), then `rename`d over
+/// the destination.
+///
+/// # Errors
+///
+/// Returns an error if any directory create, temp write, or rename fails.
+pub fn install_skill_pack(project_root: &Path) -> Result<SkillInstallReport> {
+    let fingerprint = pack_fingerprint();
+    let mut copied = false;
+    for root_rel in SKILL_ROOTS {
+        let root = project_root.join(root_rel);
+        let dest = root.join(PACK_DIR_NAME);
+        if installed_fingerprint(&dest).as_deref() == Some(fingerprint.as_str()) {
+            continue;
+        }
+        stage_and_swap(&root, &dest, &fingerprint)
+            .with_context(|| format!("install skill pack into {}", dest.display()))?;
+        copied = true;
+    }
+    Ok(SkillInstallReport { copied })
+}
+
+/// Recompute the fingerprint from the pack files actually on disk under
+/// `dest`, so drift detection catches *content* corruption (a hand-edited or
+/// truncated `SKILL.md`), not merely a stale `.fingerprint` sidecar. Returns
+/// `None` if any pack file is missing or unreadable, which forces a rewrite.
+fn installed_fingerprint(dest: &Path) -> Option<String> {
+    let mut hasher = blake3::Hasher::new();
+    for (rel, _) in SKILL_PACK {
+        let contents = fs::read(dest.join(rel)).ok()?;
+        hasher.update(rel.as_bytes());
+        hasher.update(&[0u8]);
+        hasher.update(&contents);
+        hasher.update(&[0u8]);
+    }
+    Some(hasher.finalize().to_hex().to_string())
+}
+
+fn stage_and_swap(root: &Path, dest: &Path, fingerprint: &str) -> Result<()> {
+    fs::create_dir_all(root).with_context(|| format!("mkdir {}", root.display()))?;
+    // Stage in a sibling temp dir so the final rename is same-filesystem.
+    let staging = root.join(format!(".clarion-workflow.tmp-{}", std::process::id()));
+    if staging.exists() {
+        fs::remove_dir_all(&staging)
+            .with_context(|| format!("clear stale staging {}", staging.display()))?;
+    }
+    fs::create_dir_all(&staging).with_context(|| format!("mkdir {}", staging.display()))?;
+
+    // Cleanup guard: if writing the staged files fails, remove the staging dir
+    // before bubbling the error so we don't leak a `.clarion-workflow.tmp-*`
+    // sibling. Matches the partial-state-cleanup precedent on the `.clarion/`
+    // path in install.rs. The original error is preserved.
+    if let Err(err) = write_staged_pack(&staging, fingerprint) {
+        let _ = fs::remove_dir_all(&staging);
+        return Err(err);
+    }
+
+    // Crash-safe swap: move the existing pack aside, rename the staged pack
+    // into place, then drop the backup. On failure, restore the backup so the
+    // project is never left without an installed skill.
+    //
+    // The only remaining failure window is between the two renames (back up,
+    // then move the staged pack in). If the second rename fails we restore the
+    // backup, so the previously-installed pack is always recoverable; we never
+    // delete `dest` ahead of a rename that might not happen.
+    let had_existing = dest.exists();
+    let backup = root.join(format!(".clarion-workflow.bak-{}", std::process::id()));
+    if had_existing {
+        if backup.exists() {
+            fs::remove_dir_all(&backup)
+                .with_context(|| format!("clear stale backup {}", backup.display()))?;
+        }
+        fs::rename(dest, &backup).with_context(|| {
+            format!(
+                "back up existing {} -> {}",
+                dest.display(),
+                backup.display()
+            )
+        })?;
+    }
+    match fs::rename(&staging, dest) {
+        Ok(()) => {
+            if had_existing {
+                let _ = fs::remove_dir_all(&backup);
+            }
+            Ok(())
+        }
+        Err(err) => {
+            // Restore the previous pack so orientation is never left broken.
+            if had_existing {
+                let _ = fs::rename(&backup, dest);
+            }
+            let _ = fs::remove_dir_all(&staging);
+            Err(anyhow::Error::new(err))
+                .with_context(|| format!("swap staged pack into {}", dest.display()))
+        }
+    }
+}
+
+/// Write every pack file plus the `.fingerprint` sidecar into `staging`. Does
+/// not touch `dest`; the crash-safe swap is performed by the caller.
+fn write_staged_pack(staging: &Path, fingerprint: &str) -> Result<()> {
+    for (rel, contents) in SKILL_PACK {
+        let target = staging.join(rel);
+        if let Some(parent) = target.parent() {
+            fs::create_dir_all(parent).with_context(|| format!("mkdir {}", parent.display()))?;
+        }
+        fs::write(&target, contents).with_context(|| format!("write {}", target.display()))?;
+    }
+    fs::write(staging.join(FINGERPRINT_FILE), fingerprint)
+        .with_context(|| format!("write fingerprint in {}", staging.display()))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{SKILL_PACK, pack_fingerprint};
+
+    #[test]
+    fn pack_contains_skill_md_with_frontmatter() {
+        let (rel, contents) = SKILL_PACK
+            .iter()
+            .find(|(rel, _)| *rel == "SKILL.md")
+            .expect("SKILL.md present in pack");
+        assert_eq!(*rel, "SKILL.md");
+        assert!(
+            contents.contains("name: clarion-workflow"),
+            "SKILL.md is missing its frontmatter name"
+        );
+    }
+
+    #[test]
+    fn fingerprint_is_stable_and_64_hex_chars() {
+        let fp1 = pack_fingerprint();
+        let fp2 = pack_fingerprint();
+        assert_eq!(fp1, fp2, "fingerprint must be deterministic");
+        assert_eq!(fp1.len(), 64, "blake3 hex digest is 64 chars");
+        assert!(fp1.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    #[test]
+    fn install_writes_pack_into_both_skill_roots() {
+        use super::install_skill_pack;
+        let dir = tempfile::tempdir().unwrap();
+        let report = install_skill_pack(dir.path()).expect("install ok");
+        assert!(report.copied, "first install should copy");
+
+        for root in [".claude/skills", ".agents/skills"] {
+            let skill = dir
+                .path()
+                .join(root)
+                .join("clarion-workflow")
+                .join("SKILL.md");
+            assert!(skill.exists(), "missing {}", skill.display());
+            let body = std::fs::read_to_string(&skill).unwrap();
+            assert!(body.contains("name: clarion-workflow"));
+        }
+    }
+
+    #[test]
+    fn install_is_idempotent_when_fingerprint_matches() {
+        use super::install_skill_pack;
+        let dir = tempfile::tempdir().unwrap();
+        let first = install_skill_pack(dir.path()).unwrap();
+        assert!(first.copied);
+        let second = install_skill_pack(dir.path()).unwrap();
+        assert!(!second.copied, "second install should be a no-op on match");
+    }
+
+    #[test]
+    fn install_leaves_no_backup_dir_after_successful_recopy() {
+        use super::install_skill_pack;
+        let dir = tempfile::tempdir().unwrap();
+        install_skill_pack(dir.path()).unwrap();
+        std::fs::write(
+            dir.path().join(".claude/skills/clarion-workflow/SKILL.md"),
+            "STALE",
+        )
+        .unwrap();
+        install_skill_pack(dir.path()).unwrap(); // triggers the swap
+        let root = dir.path().join(".claude/skills");
+        for entry in std::fs::read_dir(&root).unwrap() {
+            let name = entry.unwrap().file_name();
+            assert!(
+                !name.to_string_lossy().contains(".clarion-workflow.bak-"),
+                "leftover backup dir: {name:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn install_recopies_when_installed_pack_drifted() {
+        use super::install_skill_pack;
+        let dir = tempfile::tempdir().unwrap();
+        install_skill_pack(dir.path()).unwrap();
+        // Corrupt one installed copy + its fingerprint to simulate drift.
+        let skill = dir.path().join(".claude/skills/clarion-workflow/SKILL.md");
+        std::fs::write(&skill, "STALE").unwrap();
+        let fp = dir
+            .path()
+            .join(".claude/skills/clarion-workflow/.fingerprint");
+        std::fs::write(&fp, "deadbeef").unwrap();
+
+        let report = install_skill_pack(dir.path()).unwrap();
+        assert!(report.copied, "drift should trigger re-copy");
+        let body = std::fs::read_to_string(&skill).unwrap();
+        assert!(
+            body.contains("name: clarion-workflow"),
+            "drift not repaired"
+        );
+    }
+
+    /// True when the filesystem actually enforces directory write permissions
+    /// for this process. Returns `false` when running as root (DAC checks are
+    /// bypassed), so permission-based failure injection below can be skipped
+    /// rather than misreported as a pass. (clarion-86f4614c0b)
+    #[cfg(unix)]
+    fn perms_enforced() -> bool {
+        use std::os::unix::fs::PermissionsExt;
+        let probe = tempfile::tempdir().unwrap();
+        let ro = probe.path().join("ro");
+        std::fs::create_dir(&ro).unwrap();
+        std::fs::set_permissions(&ro, std::fs::Permissions::from_mode(0o555)).unwrap();
+        // If we can still create a file inside a read-only dir, perms are not
+        // enforced for us (root) and the injection would not actually fail.
+        std::fs::write(ro.join("probe"), b"x").is_err()
+    }
+
+    /// A failed re-install must be crash-safe: it surfaces the error, leaks no
+    /// `.clarion-workflow.tmp-*` / `.bak-*` sibling, and never destroys the
+    /// already-installed pack (the guarantee the stage/backup/restore cleanup
+    /// code exists to protect). The failure is the only portable injection
+    /// point — `stage_and_swap` clears any pre-seeded staging dir on entry — so
+    /// we make the skill root read-only and force a drift re-copy into it.
+    /// (clarion-86f4614c0b)
+    #[cfg(unix)]
+    #[test]
+    fn failed_reinstall_is_crash_safe_and_leaks_no_temp() {
+        use super::install_skill_pack;
+        use std::os::unix::fs::PermissionsExt;
+
+        if !perms_enforced() {
+            eprintln!("skipping: directory permissions not enforced (running as root?)");
+            return;
+        }
+
+        let dir = tempfile::tempdir().unwrap();
+        install_skill_pack(dir.path()).expect("first install ok");
+        let root = dir.path().join(".claude/skills");
+        let skill_md = root.join("clarion-workflow/SKILL.md");
+
+        // Force a drift so the next install attempts a swap, then make the skill
+        // root read-only so staging the new pack into it fails with EACCES.
+        // Drift is detected from pack *content* (installed_fingerprint rehashes
+        // SKILL.md), so corrupt SKILL.md itself; the clarion-workflow child dir
+        // stays writable, so this write succeeds before we lock the root.
+        std::fs::write(&skill_md, "STALE — drifted content").unwrap();
+        std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o555)).unwrap();
+
+        let result = install_skill_pack(dir.path());
+
+        let leaked: Vec<String> = std::fs::read_dir(&root)
+            .unwrap()
+            .filter_map(Result::ok)
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|name| {
+                name.starts_with(".clarion-workflow.tmp-")
+                    || name.starts_with(".clarion-workflow.bak-")
+            })
+            .collect();
+
+        // Restore perms so tempdir cleanup succeeds.
+        std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+        assert!(
+            result.is_err(),
+            "re-install into a read-only skill root must fail, not silently succeed"
+        );
+        assert!(
+            leaked.is_empty(),
+            "a failed re-install must leak no staging/backup sibling, found: {leaked:?}"
+        );
+        assert!(
+            skill_md.exists(),
+            "a failed re-install must not destroy the already-installed pack"
+        );
+    }
+}
diff --git a/crates/clarion-cli/tests/analyze.rs b/crates/clarion-cli/tests/analyze.rs
index f72b910e..4a759cfc 100644
--- a/crates/clarion-cli/tests/analyze.rs
+++ b/crates/clarion-cli/tests/analyze.rs
@@ -1054,6 +1054,47 @@ fn analyze_stats_reports_ambiguous_edges_total() {
     );
 }
 
+#[cfg(unix)]
+#[test]
+fn analyze_mints_core_file_entity_for_registry_resolution() {
+    let project_dir = tempfile::tempdir().unwrap();
+    let plugin_dir = tempfile::tempdir().unwrap();
+    write_ambiguous_calls_plugin(plugin_dir.path());
+
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project_dir.path())
+        .assert()
+        .success();
+    std::fs::write(project_dir.path().join("demo.call"), b"caller callee\n")
+        .expect("write demo.call");
+
+    let plugin_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).unwrap();
+    clarion_bin()
+        .args(["analyze"])
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+    let resolved = clarion_storage::resolve_file(&conn, project_dir.path(), "demo.call", "")
+        .expect("resolve_file should not error")
+        .expect("analyzed ordinary source file should resolve as a core file entity");
+
+    assert_eq!(resolved.entity_id, "core:file:demo.call");
+    assert_eq!(resolved.canonical_path.as_str(), "demo.call");
+    assert_eq!(
+        resolved.language, "callsfixture",
+        "HTTP file resolution must use the plugin manifest language, not a hardcoded extension fallback"
+    );
+    assert_eq!(
+        resolved.content_hash,
+        blake3::hash(b"caller callee\n").to_hex().to_string()
+    );
+}
+
 #[cfg(unix)]
 #[test]
 fn analyze_filters_external_import_edges_before_writer_insert() {
@@ -1143,12 +1184,16 @@ fn analyze_failrun_exits_nonzero_with_run_row_marked_failed() {
     )
     .expect("write malformed plugin.toml");
 
-    let current_path = std::env::var_os("PATH").unwrap_or_default();
-    let new_path = std::env::join_paths(
-        std::iter::once(plugin_dir.path().to_path_buf())
-            .chain(std::env::split_paths(&current_path)),
-    )
-    .expect("join_paths");
+    // Scrub the ambient PATH — build the child's PATH from ONLY the
+    // broken-plugin dir. If we inherited the parent's PATH, a real
+    // `clarion-plugin-*` binary installed on the developer's machine
+    // (e.g. `clarion-plugin-python` under ~/.local/bin) would be
+    // discovered, the run would complete cleanly, and this FailRun test
+    // would fail with "Unexpected success". The sibling tests
+    // (`analyze_resume_*`, `analyze_prune_unseen_*`) build their PATH the
+    // same single-dir way.
+    let new_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).expect("join_paths");
 
     let out = clarion_bin()
         .args(["analyze"])
@@ -1178,3 +1223,599 @@ fn analyze_failrun_exits_nonzero_with_run_row_marked_failed() {
         "run row must be marked 'failed' to stay consistent with exit code"
     );
 }
+
+#[cfg(unix)]
+fn phase3_config_with_filigree(min_cluster_size: u64, base_url: &str) -> String {
+    phase3_config_with_filigree_emit(min_cluster_size, base_url, true)
+}
+
+#[cfg(unix)]
+fn phase3_config_with_filigree_emit(
+    min_cluster_size: u64,
+    base_url: &str,
+    emit_findings: bool,
+) -> String {
+    format!(
+        r"
+analysis:
+  clustering:
+    min_cluster_size: {min_cluster_size}
+integrations:
+  filigree:
+    enabled: true
+    emit_findings: {emit_findings}
+    base_url: {base_url}
+    timeout_seconds: 1
+"
+    )
+}
+
+/// WP9-B: emission is best-effort. With Filigree enabled but unreachable, the
+/// analyze run must still complete (exit 0, run row `completed`) and record the
+/// failure in `stats.json` as `CLA-INFRA-FILIGREE-UNREACHABLE` — the enrich-only
+/// federation contract: a sibling being down never changes Clarion's outcome.
+#[cfg(unix)]
+#[test]
+fn analyze_finding_emission_is_best_effort_when_filigree_unreachable() {
+    // Port 1 is not listening: connection refused, fast.
+    let project_dir = run_phase3_fixture(
+        &["weak_a", "weak_b"],
+        &phase3_config_with_filigree(2, "http://127.0.0.1:1"),
+    );
+
+    // run_phase3_fixture already asserted the analyze invocation `.success()`;
+    // confirm the run row landed `completed` despite the emission failure.
+    let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+    let status: String = conn
+        .query_row(
+            "SELECT status FROM runs ORDER BY started_at DESC LIMIT 1",
+            [],
+            |row| row.get(0),
+        )
+        .expect("query run status");
+    assert_eq!(
+        status, "completed",
+        "Filigree being unreachable must not fail the analyze run",
+    );
+
+    let run_stats = latest_run_stats(project_dir.path());
+    let emission = &run_stats["filigree_emission"];
+    assert_eq!(
+        emission["status"].as_str(),
+        Some("unreachable"),
+        "emission recorded as unreachable: {run_stats}",
+    );
+    assert_eq!(
+        emission["rule_id"].as_str(),
+        Some("CLA-INFRA-FILIGREE-UNREACHABLE"),
+    );
+    assert!(
+        emission["endpoint"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("127.0.0.1:1"),
+        "endpoint records the target: {emission}",
+    );
+    // The weak-modularity finding anchors to a subsystem (no source path), so
+    // it is skipped, not emitted.
+    assert_eq!(
+        emission["skipped_no_path"].as_u64(),
+        Some(1),
+        "path-less finding skipped: {emission}",
+    );
+    assert_eq!(emission["emitted_attempted"].as_u64(), Some(0));
+}
+
+/// WP9-B: the happy path — analyze actually POSTs to a listening Filigree and
+/// records `status: "emitted"` with the parsed response counts in `stats.json`.
+/// A one-shot mock server stands in for Filigree's `/api/v1/scan-results`.
+#[cfg(unix)]
+#[test]
+fn analyze_finding_emission_posts_and_records_emitted_on_success() {
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock filigree");
+    let addr = listener.local_addr().expect("local addr");
+    let server = std::thread::spawn(move || {
+        let (mut stream, _) = listener.accept().expect("accept scan-results POST");
+        let mut buf = [0_u8; 8192];
+        let read = stream.read(&mut buf).expect("read request");
+        let request = String::from_utf8_lossy(&buf[..read]).into_owned();
+        let body = r#"{"files_created":0,"files_updated":0,"findings_created":0,"findings_updated":0,"new_finding_ids":[],"observations_created":0,"observations_failed":0,"warnings":[]}"#;
+        write!(
+            stream,
+            "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        )
+        .expect("write response");
+        request
+    });
+
+    let project_dir = run_phase3_fixture(
+        &["weak_a", "weak_b"],
+        &phase3_config_with_filigree(2, &format!("http://{addr}")),
+    );
+
+    let request = server.join().expect("mock server thread");
+    assert!(
+        request.contains("POST /api/v1/scan-results HTTP/1.1"),
+        "analyze POSTed to the scan-results route: {request}",
+    );
+    assert!(
+        request.contains("\"scan_source\":\"clarion\""),
+        "request body carries scan_source: {request}",
+    );
+
+    let stats = latest_run_stats(project_dir.path());
+    let emission = &stats["filigree_emission"];
+    assert_eq!(
+        emission["status"].as_str(),
+        Some("emitted"),
+        "emission succeeded: {stats}",
+    );
+    assert_eq!(emission["findings_created"].as_u64(), Some(0));
+    // The only persisted finding (weak-modularity) is path-less → skipped.
+    assert_eq!(emission["skipped_no_path"].as_u64(), Some(1), "{emission}");
+    assert_eq!(emission["emitted"].as_u64(), Some(0));
+}
+
+/// REQ-FINDING-05 `--resume`: re-running with `--resume RUN_ID` reuses the
+/// prior run's row (one `runs` row, not two) and emits with `mark_unseen=false`
+/// so the re-emit does not flip the prior run's findings to `unseen_in_latest`
+/// on the peer. A fresh run emits `mark_unseen=true`. End-to-end through a mock
+/// Filigree that captures both POST bodies.
+#[cfg(unix)]
+#[test]
+fn analyze_resume_reuses_run_row_and_emits_mark_unseen_false() {
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock filigree");
+    let addr = listener.local_addr().expect("local addr");
+    // Accept exactly two POSTs — the fresh run, then the resume — and capture
+    // each request body.
+    let server = std::thread::spawn(move || {
+        let body = r#"{"files_created":0,"files_updated":0,"findings_created":0,"findings_updated":0,"new_finding_ids":[],"observations_created":0,"observations_failed":0,"warnings":[]}"#;
+        let mut requests = Vec::new();
+        for _ in 0..2 {
+            let (mut stream, _) = listener.accept().expect("accept scan-results POST");
+            let mut buf = [0_u8; 8192];
+            let read = stream.read(&mut buf).expect("read request");
+            requests.push(String::from_utf8_lossy(&buf[..read]).into_owned());
+            write!(
+                stream,
+                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                body.len(),
+                body
+            )
+            .expect("write response");
+        }
+        requests
+    });
+
+    // Build a project + plugin and run a fresh analyze (POST 1).
+    let project_dir = tempfile::tempdir().unwrap();
+    let plugin_dir = tempfile::tempdir().unwrap();
+    write_phase3_plugin(plugin_dir.path());
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project_dir.path())
+        .assert()
+        .success();
+    for stem in ["weak_a", "weak_b"] {
+        std::fs::write(project_dir.path().join(format!("{stem}.p3")), b"module\n")
+            .expect("write phase3 fixture file");
+    }
+    let config_path = project_dir.path().join("phase3-clarion.yaml");
+    std::fs::write(
+        &config_path,
+        phase3_config_with_filigree(2, &format!("http://{addr}")),
+    )
+    .expect("write phase3 config");
+    let plugin_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).unwrap();
+
+    clarion_bin()
+        .args(["analyze", "--config"])
+        .arg(&config_path)
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    // Capture the fresh run's id, then resume it (POST 2).
+    let run_id: String = {
+        let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+        conn.query_row(
+            "SELECT id FROM runs ORDER BY started_at DESC LIMIT 1",
+            [],
+            |row| row.get(0),
+        )
+        .expect("read fresh run id")
+    };
+    clarion_bin()
+        .args(["analyze", "--config"])
+        .arg(&config_path)
+        .args(["--resume", &run_id])
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    let requests = server.join().expect("mock server thread");
+    assert!(
+        requests[0].contains("\"mark_unseen\":true"),
+        "fresh run marks old-position findings unseen: {}",
+        requests[0],
+    );
+    assert!(
+        requests[1].contains("\"mark_unseen\":false"),
+        "resume must NOT mark the prior run's findings unseen: {}",
+        requests[1],
+    );
+
+    // Resume reused the run row — exactly one row in `runs`, finalized.
+    let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+    let run_rows: i64 = conn
+        .query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))
+        .unwrap();
+    assert_eq!(
+        run_rows, 1,
+        "resume reuses the run row — no second `runs` row inserted",
+    );
+    let run_status: String = conn
+        .query_row("SELECT status FROM runs WHERE id = ?1", [&run_id], |row| {
+            row.get(0)
+        })
+        .unwrap();
+    assert_eq!(
+        run_status, "completed",
+        "the resumed run finalizes to completed"
+    );
+    let stats = latest_run_stats(project_dir.path());
+    assert_eq!(
+        stats["filigree_emission"]["mark_unseen"].as_bool(),
+        Some(false),
+        "stats.json records the resume emit ran with mark_unseen=false: {stats}",
+    );
+}
+
+/// REQ-FINDING-06 `--prune-unseen`: after emission, analyze POSTs a retention
+/// sweep to Filigree's loom `clean-stale` route, scoped to `scan_source=clarion`,
+/// and records the soft-archive count in `stats.json`. End-to-end through a mock
+/// Filigree that accepts both the emission POST and the prune POST.
+#[cfg(unix)]
+#[test]
+fn analyze_prune_unseen_posts_clean_stale_after_emission() {
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock filigree");
+    let addr = listener.local_addr().expect("local addr");
+    // One body satisfies both parsers (serde(default) ignores the other's
+    // fields): scan-results counts + clean-stale counts.
+    let server = std::thread::spawn(move || {
+        let body = r#"{"files_created":0,"files_updated":0,"findings_created":0,"findings_updated":0,"new_finding_ids":[],"observations_created":0,"observations_failed":0,"warnings":[],"findings_fixed":2,"scan_source":"clarion","older_than_days":30}"#;
+        let mut requests = Vec::new();
+        for _ in 0..2 {
+            let (mut stream, _) = listener.accept().expect("accept POST");
+            let mut buf = [0_u8; 8192];
+            let read = stream.read(&mut buf).expect("read request");
+            requests.push(String::from_utf8_lossy(&buf[..read]).into_owned());
+            write!(
+                stream,
+                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                body.len(),
+                body
+            )
+            .expect("write response");
+        }
+        requests
+    });
+
+    let project_dir = tempfile::tempdir().unwrap();
+    let plugin_dir = tempfile::tempdir().unwrap();
+    write_phase3_plugin(plugin_dir.path());
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project_dir.path())
+        .assert()
+        .success();
+    for stem in ["weak_a", "weak_b"] {
+        std::fs::write(project_dir.path().join(format!("{stem}.p3")), b"module\n")
+            .expect("write phase3 fixture file");
+    }
+    let config_path = project_dir.path().join("phase3-clarion.yaml");
+    std::fs::write(
+        &config_path,
+        phase3_config_with_filigree(2, &format!("http://{addr}")),
+    )
+    .expect("write phase3 config");
+    let plugin_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).unwrap();
+
+    clarion_bin()
+        .args(["analyze", "--config"])
+        .arg(&config_path)
+        .arg("--prune-unseen")
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    let requests = server.join().expect("mock server thread");
+    assert!(
+        requests[0].contains("POST /api/v1/scan-results HTTP/1.1"),
+        "first POST is the emission intake: {}",
+        requests[0],
+    );
+    assert!(
+        requests[1].contains("POST /api/loom/findings/clean-stale HTTP/1.1"),
+        "second POST is the loom clean-stale sweep: {}",
+        requests[1],
+    );
+    assert!(
+        requests[1].contains("\"scan_source\":\"clarion\""),
+        "prune is scoped to scan_source=clarion: {}",
+        requests[1],
+    );
+    // Guard the wire field name: the live Filigree clean-stale route silently
+    // ignores a `days` field — only `older_than_days` takes effect. Assert the
+    // request carries the correct key (default 30) so a serde rename can't
+    // regress the retention window to a no-op.
+    assert!(
+        requests[1].contains("\"older_than_days\":30"),
+        "prune sends older_than_days (not `days`): {}",
+        requests[1],
+    );
+
+    let stats = latest_run_stats(project_dir.path());
+    assert_eq!(
+        stats["filigree_prune"]["status"].as_str(),
+        Some("pruned"),
+        "stats.json records the prune sweep: {stats}",
+    );
+    assert_eq!(
+        stats["filigree_prune"]["findings_fixed"].as_u64(),
+        Some(2),
+        "prune records Filigree's soft-archive count: {stats}",
+    );
+}
+
+/// REQ-FINDING-06 `--prune-unseen` is enrich-only: with Filigree unreachable the
+/// analyze run still completes and the sweep failure is recorded in `stats.json`
+/// as `CLA-INFRA-FILIGREE-UNREACHABLE` — never failing the run.
+#[cfg(unix)]
+#[test]
+fn analyze_prune_unseen_is_best_effort_when_filigree_unreachable() {
+    let project_dir = run_phase3_fixture(
+        &["weak_a", "weak_b"],
+        &phase3_config_with_filigree(2, "http://127.0.0.1:1"),
+    );
+
+    // run_phase3_fixture does not pass --prune-unseen; re-run analyze with it.
+    // (A second run is fine — analyze is idempotent.) Filigree is unreachable
+    // (port 1), so both emission and prune fail soft.
+    let plugin = tempfile::tempdir().unwrap();
+    write_phase3_plugin(plugin.path());
+    let config_path = project_dir.path().join("phase3-clarion.yaml");
+    let plugin_path = std::env::join_paths(std::iter::once(plugin.path().to_path_buf())).unwrap();
+    clarion_bin()
+        .args(["analyze", "--config"])
+        .arg(&config_path)
+        .arg("--prune-unseen")
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+    let run_status: String = conn
+        .query_row(
+            "SELECT status FROM runs ORDER BY started_at DESC LIMIT 1",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(
+        run_status, "completed",
+        "Filigree being unreachable must not fail the prune run",
+    );
+    let stats = latest_run_stats(project_dir.path());
+    assert_eq!(
+        stats["filigree_prune"]["status"].as_str(),
+        Some("unreachable"),
+        "prune failure recorded, not propagated: {stats}",
+    );
+    assert_eq!(
+        stats["filigree_prune"]["rule_id"].as_str(),
+        Some("CLA-INFRA-FILIGREE-UNREACHABLE"),
+    );
+}
+
+/// WP9-B: with Filigree `enabled: true` but `emit_findings: false`, analyze
+/// makes ZERO scan-results POST. The emission gate short-circuits before any
+/// network I/O (no finding flush, no client build), so a listening mock must
+/// see no connection at all. `stats.json` carries no `filigree_emission` blob
+/// (the emit helper returns null, which is not folded in).
+#[cfg(unix)]
+#[test]
+fn analyze_does_not_emit_when_emit_findings_false() {
+    use std::net::TcpListener;
+
+    // Bind a listener but never accept on a thread — analyze must not connect.
+    // Set non-blocking so the post-run `accept()` returns `WouldBlock`
+    // immediately rather than hanging, and inspect the accept queue directly.
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock filigree");
+    listener
+        .set_nonblocking(true)
+        .expect("set listener non-blocking");
+    let addr = listener.local_addr().expect("local addr");
+
+    let project_dir = run_phase3_fixture(
+        &["weak_a", "weak_b"],
+        &phase3_config_with_filigree_emit(2, &format!("http://{addr}"), false),
+    );
+
+    // No client ever connected — a completed connection would sit in the accept
+    // queue even if closed, so `WouldBlock` proves zero POSTs were made.
+    match listener.accept() {
+        Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {}
+        other => panic!("emit_findings=false must make no POST, but got: {other:?}"),
+    }
+
+    // The emission helper returns null when `emit_findings` is off, and a null
+    // emission is never folded into `stats.json`.
+    let stats = latest_run_stats(project_dir.path());
+    assert!(
+        stats["filigree_emission"].is_null(),
+        "no emission blob recorded when emit_findings=false: {stats}",
+    );
+}
+
+/// REQ-FINDING-06 `--prune-unseen` is enrich-only against a non-2xx response,
+/// not just connection refusal: when Filigree answers the clean-stale POST with
+/// HTTP 500, analyze still exits 0 with the run row `completed`, and the sweep
+/// failure is recorded in `stats.json` as `CLA-INFRA-FILIGREE-UNREACHABLE`. The
+/// 500 is well-formed (content-length present) so it exercises the client's
+/// `!status.is_success()` branch rather than a torn-connection error.
+#[cfg(unix)]
+#[test]
+fn analyze_prune_unseen_is_best_effort_on_non_2xx() {
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock filigree");
+    let addr = listener.local_addr().expect("local addr");
+    // Accept both POSTs: 200 to the emission intake (POST 1), then 500 to the
+    // clean-stale sweep (POST 2).
+    let server = std::thread::spawn(move || {
+        let ok_body = r#"{"files_created":0,"files_updated":0,"findings_created":0,"findings_updated":0,"new_finding_ids":[],"observations_created":0,"observations_failed":0,"warnings":[]}"#;
+        let err_body = r#"{"error":"boom"}"#;
+        for i in 0..2 {
+            let (mut stream, _) = listener.accept().expect("accept POST");
+            let mut buf = [0_u8; 8192];
+            let _ = stream.read(&mut buf).expect("read request");
+            if i == 0 {
+                write!(
+                    stream,
+                    "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                    ok_body.len(),
+                    ok_body
+                )
+                .expect("write emission response");
+            } else {
+                write!(
+                    stream,
+                    "HTTP/1.1 500 Internal Server Error\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                    err_body.len(),
+                    err_body
+                )
+                .expect("write clean-stale 500");
+            }
+        }
+    });
+
+    let project_dir = tempfile::tempdir().unwrap();
+    let plugin_dir = tempfile::tempdir().unwrap();
+    write_phase3_plugin(plugin_dir.path());
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project_dir.path())
+        .assert()
+        .success();
+    for stem in ["weak_a", "weak_b"] {
+        std::fs::write(project_dir.path().join(format!("{stem}.p3")), b"module\n")
+            .expect("write phase3 fixture file");
+    }
+    let config_path = project_dir.path().join("phase3-clarion.yaml");
+    std::fs::write(
+        &config_path,
+        phase3_config_with_filigree(2, &format!("http://{addr}")),
+    )
+    .expect("write phase3 config");
+    let plugin_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).unwrap();
+
+    clarion_bin()
+        .args(["analyze", "--config"])
+        .arg(&config_path)
+        .arg("--prune-unseen")
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    server.join().expect("mock server thread");
+
+    // A non-2xx clean-stale response must never fail the run.
+    let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+    let run_status: String = conn
+        .query_row(
+            "SELECT status FROM runs ORDER BY started_at DESC LIMIT 1",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(
+        run_status, "completed",
+        "a 500 from the clean-stale route must not fail the prune run",
+    );
+    let stats = latest_run_stats(project_dir.path());
+    assert_eq!(
+        stats["filigree_prune"]["status"].as_str(),
+        Some("unreachable"),
+        "non-2xx prune failure recorded, not propagated: {stats}",
+    );
+    assert_eq!(
+        stats["filigree_prune"]["rule_id"].as_str(),
+        Some("CLA-INFRA-FILIGREE-UNREACHABLE"),
+    );
+}
+
+/// `--prune-unseen` with the Filigree integration disabled is a logged no-op,
+/// not an error: the run completes and `stats.json` records the skip.
+#[cfg(unix)]
+#[test]
+fn analyze_prune_unseen_noops_when_filigree_disabled() {
+    // phase3_config (no `integrations.filigree`) leaves the integration
+    // disabled by default.
+    let project_dir = tempfile::tempdir().unwrap();
+    let plugin_dir = tempfile::tempdir().unwrap();
+    write_phase3_plugin(plugin_dir.path());
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project_dir.path())
+        .assert()
+        .success();
+    for stem in ["weak_a", "weak_b"] {
+        std::fs::write(project_dir.path().join(format!("{stem}.p3")), b"module\n")
+            .expect("write phase3 fixture file");
+    }
+    let config_path = project_dir.path().join("phase3-clarion.yaml");
+    std::fs::write(&config_path, phase3_config(2)).expect("write phase3 config");
+    let plugin_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).unwrap();
+
+    clarion_bin()
+        .args(["analyze", "--config"])
+        .arg(&config_path)
+        .arg("--prune-unseen")
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .success();
+
+    let stats = latest_run_stats(project_dir.path());
+    assert_eq!(
+        stats["filigree_prune"]["status"].as_str(),
+        Some("skipped"),
+        "prune is a no-op when Filigree is disabled: {stats}",
+    );
+    assert_eq!(
+        stats["filigree_prune"]["reason"].as_str(),
+        Some("filigree_disabled"),
+    );
+}
diff --git a/crates/clarion-cli/tests/analyze_failure_modes.rs b/crates/clarion-cli/tests/analyze_failure_modes.rs
new file mode 100644
index 00000000..1760db75
--- /dev/null
+++ b/crates/clarion-cli/tests/analyze_failure_modes.rs
@@ -0,0 +1,295 @@
+//! Failure-mode integration tests for `clarion analyze`.
+//!
+//! These exercise the run-outcome promotion logic in
+//! `crates/clarion-cli/src/analyze.rs::run_with_options` — specifically the
+//! branch where the writer-actor rejects an `InsertEdge` mid-run and
+//! `RunOutcome` must be set to `HardFailed` (→ `FailRun`) rather than
+//! `SoftFailed` (→ `CommitRun(Failed)` with the full stats blob).
+//!
+//! The two paths differ in what the writer persists into `runs.stats`:
+//!
+//! - `HardFailed` (`FailRun`): stats is `{"failure_reason": "..."}` only —
+//!   no `entities_inserted` / `edges_inserted` keys.
+//! - `SoftFailed` (`CommitRun(Failed)`): stats carries the full schema
+//!   (`entities_inserted`, `edges_inserted`, clustering, ...) plus a
+//!   `failure_reason` naming the plugin crash.
+//!
+//! Both end with `runs.status = 'failed'`, so the discriminator is the
+//! *shape* of the stats blob, not the status column.
+
+#![cfg(unix)]
+
+use std::os::unix::fs::PermissionsExt;
+
+use assert_cmd::Command;
+use rusqlite::Connection;
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+/// Tiny Python fixture plugin that declares an edge kind which the writer
+/// does not know about (`bogus_edge`). The host accepts it (it appears in
+/// `[ontology].edge_kinds`); the writer's `enforce_edge_contract` rejects
+/// it with `CLA-INFRA-EDGE-UNKNOWN-KIND` — a `StorageError::WriterProtocol`
+/// surfaced from `Writer::send_wait` on the first `InsertEdge`.
+///
+/// This is the most realistic deterministic trigger for a mid-run
+/// writer-actor failure: passes core's validation, fails at the writer.
+const BOGUS_EDGE_PLUGIN_SCRIPT: &str = r#"#!/usr/bin/python3
+import json
+import pathlib
+import sys
+
+
+def read_frame():
+    headers = {}
+    while True:
+        line = sys.stdin.buffer.readline()
+        if line in (b"", b"\r\n"):
+            break
+        name, value = line.decode("ascii").strip().split(":", 1)
+        headers[name.lower()] = value.strip()
+    length = int(headers["content-length"])
+    return json.loads(sys.stdin.buffer.read(length))
+
+
+def write_frame(message):
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    sys.stdout.buffer.write(b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n")
+    sys.stdout.buffer.write(body)
+    sys.stdout.buffer.flush()
+
+
+while True:
+    msg = read_frame()
+    method = msg.get("method")
+    if method == "initialized":
+        continue
+    if method == "exit":
+        raise SystemExit(0)
+    ident = msg["id"]
+    if method == "initialize":
+        write_frame({
+            "jsonrpc": "2.0",
+            "id": ident,
+            "result": {
+                "name": "clarion-plugin-bogus",
+                "version": "0.1.0",
+                "ontology_version": "0.6.0",
+                "capabilities": {},
+            },
+        })
+    elif method == "analyze_file":
+        path = msg["params"]["file_path"]
+        stem = pathlib.Path(path).stem
+        module_id = f"bogusfixture:module:{stem}"
+        other_id = f"bogusfixture:module:{stem}_partner"
+        write_frame({
+            "jsonrpc": "2.0",
+            "id": ident,
+            "result": {
+                "entities": [
+                    {
+                        "id": module_id,
+                        "kind": "module",
+                        "qualified_name": stem,
+                        "source": {"file_path": path},
+                    },
+                    {
+                        "id": other_id,
+                        "kind": "module",
+                        "qualified_name": f"{stem}_partner",
+                        "source": {"file_path": path},
+                    },
+                ],
+                # `bogus_edge` is declared in the manifest's ontology, so
+                # `PluginHost::process_edges` accepts it; the writer's
+                # `enforce_edge_contract` rejects it with
+                # `CLA-INFRA-EDGE-UNKNOWN-KIND`. That is the mid-run
+                # writer-actor failure under test.
+                "edges": [
+                    {
+                        "kind": "bogus_edge",
+                        "from_id": module_id,
+                        "to_id": other_id,
+                        "source_byte_start": 0,
+                        "source_byte_end": 4,
+                        "confidence": "resolved",
+                    },
+                ],
+                "stats": {},
+            },
+        })
+    elif method == "shutdown":
+        write_frame({"jsonrpc": "2.0", "id": ident, "result": {}})
+    else:
+        raise SystemExit(1)
+"#;
+
+const BOGUS_EDGE_PLUGIN_MANIFEST: &str = r#"
+[plugin]
+name = "clarion-plugin-bogus"
+plugin_id = "bogusfixture"
+version = "0.1.0"
+protocol_version = "1.0"
+executable = "clarion-plugin-bogus"
+language = "bogusfixture"
+extensions = ["bog"]
+
+[capabilities.runtime]
+expected_max_rss_mb = 256
+expected_entities_per_file = 100
+wardline_aware = false
+reads_outside_project_root = false
+
+[ontology]
+entity_kinds = ["module"]
+edge_kinds = ["bogus_edge"]
+rule_id_prefix = "CLA-BOGUS-"
+ontology_version = "0.6.0"
+"#;
+
+fn write_bogus_edge_plugin(plugin_dir: &std::path::Path) {
+    let plugin_script = plugin_dir.join("clarion-plugin-bogus");
+    std::fs::write(&plugin_script, BOGUS_EDGE_PLUGIN_SCRIPT)
+        .expect("write bogus edge plugin script");
+    let mut perms = std::fs::metadata(&plugin_script)
+        .expect("stat bogus edge plugin")
+        .permissions();
+    perms.set_mode(0o755);
+    std::fs::set_permissions(&plugin_script, perms).expect("chmod bogus edge plugin");
+
+    std::fs::write(plugin_dir.join("plugin.toml"), BOGUS_EDGE_PLUGIN_MANIFEST)
+        .expect("write bogus edge plugin manifest");
+}
+
+/// Seam test for the `SoftFailed` vs `HardFailed` branch in
+/// `run_with_options` (analyze.rs ~lines 426-475, 519-601).
+///
+/// A writer-actor `InsertEdge` rejection mid-run must promote the run to
+/// `HardFailed` → `FailRun`. The run row must:
+///
+/// 1. End with `status = 'failed'`.
+/// 2. Carry a `stats.failure_reason` naming the writer-actor failure
+///    (`CLA-INFRA-EDGE-UNKNOWN-KIND` from `enforce_edge_contract`), not a
+///    plugin-crash reason.
+/// 3. Have the minimal `FailRun` stats shape — no `entities_inserted`
+///    key, distinguishing this from the `SoftFailed` path which writes the
+///    full `CommitRun(Failed)` stats blob.
+/// 4. Have NO `findings` rows tagged with the crash-loop `rule_id` — the
+///    failure here is writer-side, not plugin-side.
+///
+/// The process must exit non-zero so `analyze && next` chains and CI
+/// gating work (regression for the same surface as
+/// `analyze_failrun_exits_nonzero_with_run_row_marked_failed`).
+#[test]
+fn analyze_promotes_run_to_hard_failed_when_writer_actor_fails_mid_run() {
+    let project_dir = tempfile::tempdir().unwrap();
+    let plugin_dir = tempfile::tempdir().unwrap();
+    write_bogus_edge_plugin(plugin_dir.path());
+
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project_dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    std::fs::write(project_dir.path().join("demo.bog"), b"module\n").expect("write demo.bog");
+
+    // Scrub PATH so only the bogus plugin is discovered. A second
+    // discovered plugin would muddy the assertion: a healthy plugin
+    // *after* the bogus one cannot run (writer-actor failure breaks the
+    // 'plugins loop), but a healthy plugin *before* would insert
+    // entities and edges first, changing the stats-shape discriminator.
+    let plugin_path =
+        std::env::join_paths(std::iter::once(plugin_dir.path().to_path_buf())).unwrap();
+    let out = clarion_bin()
+        .args(["analyze"])
+        .arg(project_dir.path())
+        .env("PATH", &plugin_path)
+        .assert()
+        .failure();
+    let stderr = String::from_utf8(out.get_output().stderr.clone()).unwrap();
+    assert!(
+        stderr.contains("failed"),
+        "stderr should mention failure; got: {stderr}"
+    );
+
+    let conn = Connection::open(project_dir.path().join(".clarion/clarion.db")).unwrap();
+
+    // (1) Run row marked failed.
+    let (run_status, run_stats_raw): (String, String) = conn
+        .query_row(
+            "SELECT status, stats FROM runs ORDER BY started_at DESC LIMIT 1",
+            [],
+            |row| Ok((row.get(0)?, row.get(1)?)),
+        )
+        .expect("query latest run row");
+    assert_eq!(
+        run_status, "failed",
+        "writer-actor mid-run failure must mark the run row failed"
+    );
+
+    let stats: serde_json::Value =
+        serde_json::from_str(&run_stats_raw).expect("parse runs.stats JSON");
+
+    // (2) failure_reason names the writer-actor rejection, not a plugin crash.
+    let failure_reason = stats["failure_reason"]
+        .as_str()
+        .expect("HardFailed stats must contain failure_reason");
+    assert!(
+        failure_reason.contains("CLA-INFRA-EDGE-UNKNOWN-KIND"),
+        "failure_reason should cite the writer's edge-contract code; \
+         got: {failure_reason}"
+    );
+    assert!(
+        failure_reason.contains("InsertEdge"),
+        "failure_reason should name the InsertEdge surface; got: {failure_reason}"
+    );
+    assert!(
+        !failure_reason.contains("plugin(s) crashed") && !failure_reason.contains("panicked"),
+        "writer-actor failure must not be reported as a plugin crash; \
+         got: {failure_reason}"
+    );
+
+    // (3) Stats shape is the minimal FailRun blob — no SoftFailed keys.
+    // SoftFailed's `CommitRun(Failed)` writes the full stats schema with
+    // `entities_inserted`, `edges_inserted`, clustering, etc.; FailRun
+    // writes only `{"failure_reason": ...}`. Asserting the absence of
+    // SoftFailed-only keys is the load-bearing discriminator between the
+    // two branches.
+    assert!(
+        stats.get("entities_inserted").is_none(),
+        "FailRun stats must not contain entities_inserted (SoftFailed key); \
+         got: {run_stats_raw}"
+    );
+    assert!(
+        stats.get("edges_inserted").is_none(),
+        "FailRun stats must not contain edges_inserted (SoftFailed key); \
+         got: {run_stats_raw}"
+    );
+    assert!(
+        stats.get("clustering").is_none(),
+        "FailRun stats must not contain clustering (SoftFailed key); \
+         got: {run_stats_raw}"
+    );
+
+    // (4) No crash-loop finding rows — the failure here is writer-side.
+    // The crash-loop breaker only ticks on plugin crashes; it must not
+    // have tripped, and no row tagged with the crash-loop `rule_id` may
+    // appear.
+    let crash_loop_findings: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM findings \
+             WHERE rule_id = 'CLA-INFRA-PLUGIN-DISABLED-CRASH-LOOP'",
+            [],
+            |row| row.get(0),
+        )
+        .expect("query crash-loop findings count");
+    assert_eq!(
+        crash_loop_findings, 0,
+        "no FINDING_DISABLED_CRASH_LOOP rows should exist; \
+         writer-actor failure must not tick the crash-loop breaker"
+    );
+}
diff --git a/crates/clarion-cli/tests/db.rs b/crates/clarion-cli/tests/db.rs
new file mode 100644
index 00000000..fc0b7a49
--- /dev/null
+++ b/crates/clarion-cli/tests/db.rs
@@ -0,0 +1,129 @@
+//! `clarion db backup` integration tests (clarion-6d433b61ba / STO-04).
+
+use assert_cmd::Command;
+use rusqlite::{Connection, OpenFlags};
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+/// Seed a real `.clarion/clarion.db` under `root` with one identifiable row,
+/// left in WAL mode (the state a live analyze leaves behind).
+fn seed_db(root: &std::path::Path) {
+    let clarion_dir = root.join(".clarion");
+    std::fs::create_dir_all(&clarion_dir).expect("mkdir .clarion");
+    let db_path = clarion_dir.join("clarion.db");
+    let mut conn = Connection::open(&db_path).expect("open db");
+    clarion_storage::pragma::apply_write_pragmas(&conn).expect("write pragmas");
+    clarion_storage::schema::apply_migrations(&mut conn).expect("migrate");
+    conn.execute(
+        "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+         VALUES (?1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), NULL, '{}', '{}', 'running')",
+        rusqlite::params!["run-backup-test"],
+    )
+    .expect("seed runs row");
+}
+
+/// A backup of a seeded DB is a standalone, single-file copy that opens
+/// read-only and contains the source rows (no WAL sidecar required).
+#[test]
+fn backup_produces_a_readable_standalone_copy() {
+    let dir = tempfile::tempdir().unwrap();
+    seed_db(dir.path());
+    let output = dir.path().join("snapshot.db");
+
+    clarion_bin()
+        .args(["db", "backup"])
+        .arg(&output)
+        .arg("--path")
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    assert!(output.exists(), "backup file was not created");
+    // No WAL sidecar should be shipped alongside the standalone copy.
+    assert!(
+        !output.with_extension("db-wal").exists(),
+        "backup should be a single-file copy with no -wal sidecar"
+    );
+
+    // Open the copy read-only and confirm the seeded row survived.
+    let copy = Connection::open_with_flags(&output, OpenFlags::SQLITE_OPEN_READ_ONLY)
+        .expect("open backup read-only");
+    let status: String = copy
+        .query_row(
+            "SELECT status FROM runs WHERE id = 'run-backup-test'",
+            [],
+            |row| row.get(0),
+        )
+        .expect("seeded row present in backup");
+    assert_eq!(status, "running");
+    drop(copy);
+
+    // integrity_check on the FTS5 tables needs to write scratch state, so it
+    // must run on a read-write handle (the backup command runs the same check
+    // internally before promoting the file).
+    let rw = Connection::open(&output).expect("open backup read-write");
+    let integrity: String = rw
+        .query_row("PRAGMA integrity_check", [], |row| row.get(0))
+        .expect("integrity_check");
+    assert_eq!(integrity, "ok");
+}
+
+/// An existing output is protected: refused without --force, overwritten with.
+#[test]
+fn backup_refuses_to_clobber_without_force() {
+    let dir = tempfile::tempdir().unwrap();
+    seed_db(dir.path());
+    let output = dir.path().join("snapshot.db");
+    std::fs::write(&output, b"pre-existing precious file").unwrap();
+
+    clarion_bin()
+        .args(["db", "backup"])
+        .arg(&output)
+        .arg("--path")
+        .arg(dir.path())
+        .assert()
+        .failure();
+
+    // The pre-existing file must be untouched by the refused run.
+    assert_eq!(
+        std::fs::read(&output).unwrap(),
+        b"pre-existing precious file"
+    );
+
+    // --force replaces it with a real backup.
+    clarion_bin()
+        .args(["db", "backup"])
+        .arg(&output)
+        .arg("--path")
+        .arg(dir.path())
+        .arg("--force")
+        .assert()
+        .success();
+    let copy = Connection::open_with_flags(&output, OpenFlags::SQLITE_OPEN_READ_ONLY)
+        .expect("open overwritten backup");
+    let n: i64 = copy
+        .query_row("SELECT count(*) FROM runs", [], |row| row.get(0))
+        .expect("count rows");
+    assert_eq!(n, 1);
+}
+
+/// A missing source database is rejected with a clear error and leaves no
+/// debris (no output file, no staging temp).
+#[test]
+fn backup_rejects_missing_source_db() {
+    let dir = tempfile::tempdir().unwrap();
+    // No seed_db: .clarion/clarion.db does not exist.
+    let output = dir.path().join("snapshot.db");
+
+    clarion_bin()
+        .args(["db", "backup"])
+        .arg(&output)
+        .arg("--path")
+        .arg(dir.path())
+        .assert()
+        .failure();
+
+    assert!(!output.exists(), "no output should be written on failure");
+}
diff --git a/crates/clarion-cli/tests/hook.rs b/crates/clarion-cli/tests/hook.rs
new file mode 100644
index 00000000..858f7873
--- /dev/null
+++ b/crates/clarion-cli/tests/hook.rs
@@ -0,0 +1,96 @@
+//! `clarion hook session-start` integration tests.
+
+use assert_cmd::Command;
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+#[test]
+fn hook_session_start_exits_zero_without_clarion_db() {
+    // Fail-soft: no .clarion/ at all must still exit 0 and nudge.
+    let dir = tempfile::tempdir().unwrap();
+    let assert = clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let out = String::from_utf8(assert.get_output().stdout.clone()).unwrap();
+    assert!(
+        out.contains("clarion analyze"),
+        "missing analyze nudge in: {out}"
+    );
+    // Installing a skill into a project that never had one is `clarion install
+    // --skills`'s job, NOT the hook's. The hook only re-syncs a skill that is
+    // already present, so a bare project must come away with no skill roots
+    // created (clarion-ac0fc3bd86).
+    assert!(
+        !dir.path().join(".claude/skills").exists(),
+        "hook must not create .claude/skills when no skill is present"
+    );
+    assert!(
+        !dir.path().join(".agents/skills").exists(),
+        "hook must not create .agents/skills when no skill is present"
+    );
+}
+
+#[test]
+fn hook_session_start_prints_counts_for_installed_project() {
+    let dir = tempfile::tempdir().unwrap();
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    let assert = clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let out = String::from_utf8(assert.get_output().stdout.clone()).unwrap();
+    assert!(out.contains("entities"), "missing entity count line: {out}");
+    assert!(out.contains("clarion analyze"), "missing nudge: {out}");
+}
+
+#[test]
+fn hook_session_start_exits_zero_with_corrupt_db() {
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::create_dir_all(dir.path().join(".clarion")).unwrap();
+    // Garbage where clarion.db should be — not a valid SQLite file.
+    std::fs::write(dir.path().join(".clarion/clarion.db"), b"NOT A SQLITE DB").unwrap();
+    let assert = clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success(); // fail-soft: must exit 0
+    let out = String::from_utf8(assert.get_output().stdout.clone()).unwrap();
+    assert!(
+        out.contains("could not be opened") || out.contains("corrupt"),
+        "expected a present-but-unreadable nudge, got: {out}"
+    );
+}
+
+#[test]
+fn hook_session_start_resyncs_skill_when_present_and_drifted() {
+    let dir = tempfile::tempdir().unwrap();
+    clarion_bin()
+        .args(["install", "--skills", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let skill = dir.path().join(".claude/skills/clarion-workflow/SKILL.md");
+    std::fs::write(&skill, "STALE").unwrap();
+
+    clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    let body = std::fs::read_to_string(&skill).unwrap();
+    assert!(
+        body.contains("name: clarion-workflow"),
+        "hook did not repair drifted skill: {body}"
+    );
+}
diff --git a/crates/clarion-cli/tests/install.rs b/crates/clarion-cli/tests/install.rs
index e6a02d88..4befc41a 100644
--- a/crates/clarion-cli/tests/install.rs
+++ b/crates/clarion-cli/tests/install.rs
@@ -49,7 +49,7 @@ fn install_creates_clarion_dir_with_expected_contents() {
 }
 
 #[test]
-fn install_applies_migration_0001_exactly_once() {
+fn install_applies_each_migration_exactly_once() {
     let dir = tempfile::tempdir().unwrap();
     clarion_bin()
         .args(["install", "--path"])
@@ -63,13 +63,38 @@ fn install_applies_migration_0001_exactly_once() {
             row.get(0)
         })
         .unwrap();
-    assert_eq!(count, 1);
-    let version: i64 = conn
-        .query_row("SELECT version FROM schema_migrations", [], |row| {
-            row.get(0)
-        })
-        .unwrap();
-    assert_eq!(version, 1);
+    assert_eq!(count, 2);
+    let versions: Vec<i64> = {
+        let mut stmt = conn
+            .prepare("SELECT version FROM schema_migrations ORDER BY version")
+            .unwrap();
+        let rows = stmt.query_map([], |row| row.get(0)).unwrap();
+        rows.map(std::result::Result::unwrap).collect()
+    };
+    assert_eq!(versions, vec![1, 2]);
+}
+
+#[test]
+fn install_all_rejects_non_directory_clarion() {
+    // Bug (PR#21 review #6): when `.clarion` already exists as a regular file
+    // and `--all` (a non-bare init) is run without `--force`, install treated
+    // it as "already initialised" and skipped DB creation, then proceeded to
+    // install skills/hooks atop a project with no usable `.clarion/clarion.db`.
+    // It must instead refuse with a clear non-directory error.
+    let dir = tempfile::tempdir().unwrap();
+    std::fs::write(dir.path().join(".clarion"), "i am a file, not a dir").unwrap();
+
+    let out = clarion_bin()
+        .args(["install", "--all", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .failure();
+    let stderr = String::from_utf8(out.get_output().stderr.clone()).unwrap();
+    assert!(
+        stderr.contains("non-directory"),
+        "error did not mention the non-directory .clarion: {stderr}"
+    );
 }
 
 #[test]
diff --git a/crates/clarion-cli/tests/secret_scan.rs b/crates/clarion-cli/tests/secret_scan.rs
new file mode 100644
index 00000000..553674ee
--- /dev/null
+++ b/crates/clarion-cli/tests/secret_scan.rs
@@ -0,0 +1,996 @@
+#![cfg(unix)]
+
+use assert_cmd::Command;
+use rusqlite::Connection;
+use sha1::{Digest, Sha1};
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+const PLUGIN_SCRIPT: &str = r#"#!/usr/bin/python3
+import json
+import os
+import pathlib
+import re
+import sys
+
+
+def read_frame():
+    headers = {}
+    while True:
+        line = sys.stdin.buffer.readline()
+        if line in (b"", b"\r\n"):
+            break
+        name, value = line.decode("ascii").strip().split(":", 1)
+        headers[name.lower()] = value.strip()
+    length = int(headers["content-length"])
+    return json.loads(sys.stdin.buffer.read(length))
+
+
+def write_frame(message):
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    sys.stdout.buffer.write(b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n")
+    sys.stdout.buffer.write(body)
+    sys.stdout.buffer.flush()
+
+
+while True:
+    msg = read_frame()
+    method = msg.get("method")
+    if method == "initialized":
+        continue
+    if method == "exit":
+        raise SystemExit(0)
+    ident = msg["id"]
+    if method == "initialize":
+        write_frame({
+            "jsonrpc": "2.0",
+            "id": ident,
+            "result": {
+                "name": "clarion-plugin-secretfixture",
+                "version": "0.1.0",
+                "ontology_version": "0.1.0",
+                "capabilities": {},
+            },
+        })
+    elif method == "analyze_file":
+        if (
+            os.environ.get("SECRETFIXTURE_ASSERT_ENV_ABSENT")
+            and os.environ.get("CLARION_DOTENV_SENTINEL") is not None
+        ):
+            raise SystemExit(42)
+        path = msg["params"]["file_path"]
+        source_path = os.environ.get("SECRETFIXTURE_SOURCE_OVERRIDE", path)
+        name = "file_" + re.sub(r"[^A-Za-z0-9_]", "_", pathlib.Path(path).name)
+        write_frame({
+            "jsonrpc": "2.0",
+            "id": ident,
+            "result": {
+                "entities": [
+                    {
+                        "id": "secretfixture:module:" + name,
+                        "kind": "module",
+                        "qualified_name": name,
+                        "source": {"file_path": source_path},
+                    }
+                ],
+                "edges": [],
+            },
+        })
+    elif method == "shutdown":
+        write_frame({"jsonrpc": "2.0", "id": ident, "result": {}})
+    else:
+        raise SystemExit(1)
+"#;
+
+const PLUGIN_MANIFEST: &str = r#"
+[plugin]
+name = "clarion-plugin-secretfixture"
+plugin_id = "secretfixture"
+version = "0.1.0"
+protocol_version = "1.0"
+executable = "clarion-plugin-secretfixture"
+language = "secretfixture"
+extensions = ["sec"]
+
+[capabilities.runtime]
+expected_max_rss_mb = 256
+expected_entities_per_file = 100
+wardline_aware = false
+reads_outside_project_root = false
+
+[ontology]
+entity_kinds = ["module"]
+edge_kinds = []
+rule_id_prefix = "CLA-SECRET-FIXTURE-"
+ontology_version = "0.1.0"
+"#;
+
+fn write_secret_fixture_plugin(plugin_dir: &std::path::Path) {
+    use std::os::unix::fs::PermissionsExt;
+
+    let plugin_script = plugin_dir.join("clarion-plugin-secretfixture");
+    std::fs::write(&plugin_script, PLUGIN_SCRIPT).expect("write plugin script");
+    let mut perms = std::fs::metadata(&plugin_script)
+        .expect("stat plugin")
+        .permissions();
+    perms.set_mode(0o755);
+    std::fs::set_permissions(&plugin_script, perms).expect("chmod plugin");
+
+    std::fs::write(plugin_dir.join("plugin.toml"), PLUGIN_MANIFEST).expect("write plugin manifest");
+}
+
+fn install_project(project: &std::path::Path) {
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(project)
+        .assert()
+        .success();
+}
+
+fn plugin_path(plugin_dir: &std::path::Path) -> std::ffi::OsString {
+    std::env::join_paths(std::iter::once(plugin_dir.to_path_buf())).unwrap()
+}
+
+fn conn(project: &std::path::Path) -> Connection {
+    Connection::open(project.join(".clarion/clarion.db")).expect("open clarion db")
+}
+
+fn sha1_hex(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut hasher = Sha1::new();
+    hasher.update(bytes);
+    let digest = hasher.finalize();
+    let mut out = String::with_capacity(40);
+    for byte in digest {
+        out.push(char::from(HEX[usize::from(byte >> 4)]));
+        out.push(char::from(HEX[usize::from(byte & 0x0f)]));
+    }
+    out
+}
+
+#[test]
+fn clean_project_has_no_secret_findings() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let count: i64 = conn(project.path())
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id LIKE 'CLA-SEC-%'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(count, 0);
+}
+
+#[test]
+fn secret_file_persists_finding_and_briefing_block() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let blocked: String = db
+        .query_row(
+            "SELECT json_extract(properties, '$.briefing_blocked') FROM entities",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(blocked, "secret_present");
+    let count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(count, 1);
+}
+
+#[test]
+fn resume_does_not_duplicate_secret_findings() {
+    // REQ-FINDING-05 `--resume`: secret-finding ids are deterministic and
+    // run-scoped, so re-walking under the same run_id upserts the same row
+    // rather than inserting a duplicate (a random-UUID id would duplicate on
+    // every resume). Regression for the gap that the phase3 weak-modularity
+    // finding alone did not cover.
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+
+    // Fresh run.
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let (run_id, first_id): (String, String) = {
+        let db = conn(project.path());
+        let run_id = db
+            .query_row(
+                "SELECT id FROM runs ORDER BY started_at DESC LIMIT 1",
+                [],
+                |r| r.get(0),
+            )
+            .unwrap();
+        let first_id = db
+            .query_row(
+                "SELECT id FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+                [],
+                |r| r.get(0),
+            )
+            .unwrap();
+        (run_id, first_id)
+    };
+
+    // Resume the same run.
+    clarion_bin()
+        .arg("analyze")
+        .args(["--resume", &run_id])
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(count, 1, "resume must not duplicate the secret finding");
+    let after_id: String = db
+        .query_row(
+            "SELECT id FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |r| r.get(0),
+        )
+        .unwrap();
+    assert_eq!(
+        after_id, first_id,
+        "the resumed secret finding keeps its deterministic run-scoped id",
+    );
+    let run_rows: i64 = db
+        .query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))
+        .unwrap();
+    assert_eq!(run_rows, 1, "resume reuses the run row");
+}
+
+#[test]
+fn dotenv_sidecar_persists_finding_with_core_file_anchor() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+    std::fs::write(
+        project.path().join(".env"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let finding_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let anchor_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM entities \
+             WHERE plugin_id = 'core' \
+               AND kind = 'file' \
+               AND source_file_path LIKE '%.env' \
+               AND json_extract(properties, '$.briefing_blocked') = 'secret_present'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(finding_count, 1);
+    assert_eq!(anchor_count, 1);
+}
+
+#[test]
+fn analyze_does_not_load_dotenv_into_plugin_environment() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+    std::fs::write(
+        project.path().join(".env"),
+        b"CLARION_DOTENV_SENTINEL=ordinaryvalue\n",
+    )
+    .unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(".")
+        .current_dir(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .env("SECRETFIXTURE_ASSERT_ENV_ABSENT", "1")
+        .assert()
+        .success();
+}
+
+#[test]
+fn plugin_entity_for_unscanned_source_is_briefing_blocked() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+    let unscanned = project.path().join("notes.txt");
+    std::fs::write(&unscanned, b"ordinary notes\n").unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .env("SECRETFIXTURE_SOURCE_OVERRIDE", &unscanned)
+        .assert()
+        .success();
+
+    let blocked: String = conn(project.path())
+        .query_row(
+            "SELECT json_extract(properties, '$.briefing_blocked') FROM entities \
+             WHERE plugin_id = 'secretfixture'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(blocked, "unscanned_source");
+}
+
+#[test]
+fn baseline_suppresses_secret_and_emits_audit_match() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+    let hashed_secret = sha1_hex(b"AKIAIOSFODNN7EXAMPLE");
+    std::fs::write(
+        project.path().join(".clarion/secrets-baseline.yaml"),
+        format!(
+            r#"
+version: "1.0"
+results:
+  "leaky.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "{hashed_secret}"
+      line_number: 1
+      is_secret: false
+      justification: "AWS documentation example key."
+"#
+        ),
+    )
+    .unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let secret_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let match_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-INFRA-SECRET-BASELINE-MATCH'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let blocked_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE json_extract(properties, '$.briefing_blocked') IS NOT NULL",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(secret_count, 0);
+    assert_eq!(match_count, 1);
+    assert_eq!(blocked_count, 0);
+}
+
+#[test]
+fn missing_baseline_justification_degrades_to_finding() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+    let hashed_secret = sha1_hex(b"AKIAIOSFODNN7EXAMPLE");
+    std::fs::write(
+        project.path().join(".clarion/secrets-baseline.yaml"),
+        format!(
+            r#"
+version: "1.0"
+results:
+  "leaky.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "{hashed_secret}"
+      line_number: 1
+      is_secret: false
+  "stale.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "{hashed_secret}"
+      line_number: 9
+      is_secret: false
+"#
+        ),
+    )
+    .unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let count: i64 = conn(project.path())
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(count, 2);
+}
+
+#[test]
+fn non_tty_override_confirmed_allows_briefing_and_records_stats() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+
+    clarion_bin()
+        .args([
+            "analyze",
+            "--allow-unredacted-secrets",
+            "--confirm-allow-unredacted-secrets=yes-i-understand",
+        ])
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let blocked_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE json_extract(properties, '$.briefing_blocked') IS NOT NULL",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let override_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-UNREDACTED-SECRETS-ALLOWED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let override_used: i64 = db
+        .query_row(
+            "SELECT json_extract(stats, '$.secret_override_used') FROM runs",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let evidence_json: String = db
+        .query_row(
+            "SELECT evidence FROM findings WHERE rule_id = 'CLA-SEC-UNREDACTED-SECRETS-ALLOWED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let evidence: serde_json::Value =
+        serde_json::from_str(&evidence_json).expect("override evidence JSON");
+    // ADR-013: override is additive — per-(rule,file,line) SECRET_DETECTED
+    // still lands so `filigree list --rule-id=CLA-SEC-SECRET-DETECTED`
+    // enumerates the full audited population, not just the unoverridden tail.
+    let secret_detected_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(blocked_count, 0);
+    assert_eq!(override_count, 1);
+    assert_eq!(override_used, 1);
+    assert_eq!(
+        secret_detected_count, 1,
+        "ADR-013 audit-trail fidelity: SECRET_DETECTED must be emitted even \
+         under override so audit queries by rule_id are complete"
+    );
+    assert_eq!(evidence["detections"][0]["rule_id"], "AwsAccessKeyId");
+    assert_eq!(evidence["detections"][0]["line_number"], 1);
+    assert_eq!(
+        evidence["detections"][0]["hashed_secret_hex"],
+        sha1_hex(b"AKIAIOSFODNN7EXAMPLE")
+    );
+}
+
+#[test]
+fn non_tty_override_without_confirmation_exits_78_before_run_start() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+
+    let assert = clarion_bin()
+        .args(["analyze", "--allow-unredacted-secrets"])
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .code(78);
+    let stderr = String::from_utf8_lossy(&assert.get_output().stderr);
+    assert!(stderr.contains("CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED"));
+    assert!(stderr.contains("leaky.sec:1 AwsAccessKeyId"));
+    let run_count: i64 = conn(project.path())
+        .query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))
+        .unwrap();
+    assert_eq!(run_count, 0);
+}
+
+#[test]
+fn non_tty_override_with_wrong_confirmation_exits_78_before_run_start() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+
+    let assert = clarion_bin()
+        .args([
+            "analyze",
+            "--allow-unredacted-secrets",
+            "--confirm-allow-unredacted-secrets=oops",
+        ])
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .code(78);
+    let stderr = String::from_utf8_lossy(&assert.get_output().stderr);
+    assert!(stderr.contains("CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED"));
+    let run_count: i64 = conn(project.path())
+        .query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))
+        .unwrap();
+    assert_eq!(run_count, 0);
+}
+
+#[test]
+fn baseline_suppression_and_override_admission_are_audited_together() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(
+        project.path().join("fixture.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+    std::fs::write(
+        project.path().join("live.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+    let hashed_secret = sha1_hex(b"AKIAIOSFODNN7EXAMPLE");
+    std::fs::write(
+        project.path().join(".clarion/secrets-baseline.yaml"),
+        format!(
+            r#"
+version: "1.0"
+results:
+  "fixture.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "{hashed_secret}"
+      line_number: 1
+      is_secret: false
+      justification: "AWS documentation example key."
+"#
+        ),
+    )
+    .unwrap();
+
+    clarion_bin()
+        .args([
+            "analyze",
+            "--allow-unredacted-secrets",
+            "--confirm-allow-unredacted-secrets=yes-i-understand",
+        ])
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let baseline_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-INFRA-SECRET-BASELINE-MATCH'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let override_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-UNREDACTED-SECRETS-ALLOWED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let secret_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let blocked_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE json_extract(properties, '$.briefing_blocked') IS NOT NULL",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(baseline_count, 1);
+    assert_eq!(override_count, 1);
+    // ADR-013: SECRET_DETECTED emits on detection regardless of override.
+    // Baseline-suppressed `fixture.sec` contributes 0 detections; the live
+    // overridden `live.sec` contributes 1.
+    assert_eq!(
+        secret_count, 1,
+        "override is additive: live.sec's detection still lands as \
+         SECRET_DETECTED so audit-by-rule_id is complete"
+    );
+    assert_eq!(blocked_count, 0);
+}
+
+fn assert_invalid_baseline_aborts(raw_baseline: &str, expected_stderr: &str) {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("leaky.sec"), b"nothing to see\n").unwrap();
+    std::fs::write(
+        project.path().join(".clarion/secrets-baseline.yaml"),
+        raw_baseline,
+    )
+    .unwrap();
+
+    let assert = clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .failure();
+    let stderr = String::from_utf8_lossy(&assert.get_output().stderr);
+    assert!(
+        stderr.contains("load secret baseline"),
+        "stderr did not include baseline context: {stderr}"
+    );
+    assert!(
+        stderr.contains(expected_stderr),
+        "stderr did not include {expected_stderr:?}: {stderr}"
+    );
+    let run_count: i64 = conn(project.path())
+        .query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))
+        .unwrap();
+    assert_eq!(run_count, 0);
+}
+
+#[test]
+fn invalid_baseline_path_aborts_analyze_with_context() {
+    assert_invalid_baseline_aborts(
+        r#"
+version: "1.0"
+results:
+  "../leaky.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 1
+      is_secret: false
+      justification: "Invalid path."
+"#,
+        "repository-relative",
+    );
+}
+
+#[test]
+fn invalid_baseline_hash_aborts_analyze_with_context() {
+    assert_invalid_baseline_aborts(
+        r#"
+version: "1.0"
+results:
+  "leaky.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "not-a-sha1"
+      line_number: 1
+      is_secret: false
+      justification: "Invalid hash."
+"#,
+        "invalid hashed_secret",
+    );
+}
+
+#[test]
+fn unsupported_baseline_version_aborts_analyze_with_context() {
+    assert_invalid_baseline_aborts(
+        r#"
+version: "2.0"
+results: {}
+"#,
+        "baseline version mismatch",
+    );
+}
+
+#[test]
+fn malformed_baseline_yaml_aborts_analyze_with_context() {
+    assert_invalid_baseline_aborts(
+        r#"
+version: "1.0"
+results:
+  "leaky.sec": [
+"#,
+        "baseline parse error",
+    );
+}
+
+#[test]
+#[ignore = "TTY override confirmation needs an interactive terminal; WS-D owns the manual smoke."]
+fn tty_override_confirmation_manual_smoke() {}
+
+#[test]
+fn override_flag_is_noop_without_detections() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+
+    clarion_bin()
+        .args(["analyze", "--allow-unredacted-secrets"])
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let override_count: i64 = db
+        .query_row(
+            "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-UNREDACTED-SECRETS-ALLOWED'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    let stats_value: Option<i64> = db
+        .query_row(
+            "SELECT json_extract(stats, '$.secret_override_used') FROM runs",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(override_count, 0);
+    assert_eq!(stats_value, None);
+}
+
+#[test]
+fn only_secret_bearing_file_is_blocked_in_multi_file_project() {
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean_a.sec"), b"nothing to see\n").unwrap();
+    std::fs::write(
+        project.path().join("leaky.sec"),
+        b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n",
+    )
+    .unwrap();
+    std::fs::write(project.path().join("clean_b.sec"), b"still clean\n").unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let blocked_count: i64 = conn(project.path())
+        .query_row(
+            "SELECT COUNT(DISTINCT source_file_path) FROM entities \
+             WHERE json_extract(properties, '$.briefing_blocked') = 'secret_present'",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(blocked_count, 1);
+}
+
+#[test]
+fn cleared_sidecar_clears_stale_briefing_block() {
+    // Regression for clarion-2e34dbbdec: a sidecar-only path (.env) whose
+    // secret is cleaned must have its anchor's briefing_blocked dropped and
+    // content_hash refreshed on the next run, even though no finding is
+    // emitted for it in run N+1.
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+    let dotenv = project.path().join(".env");
+    std::fs::write(&dotenv, b"aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n").unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let (blocked, hash_before): (String, String) = db
+        .query_row(
+            "SELECT json_extract(properties, '$.briefing_blocked'), content_hash \
+               FROM entities \
+              WHERE plugin_id = 'core' AND kind = 'file' \
+                AND source_file_path LIKE '%.env'",
+            [],
+            |row| Ok((row.get(0)?, row.get(1)?)),
+        )
+        .unwrap();
+    assert_eq!(blocked, "secret_present");
+    drop(db);
+
+    std::fs::write(&dotenv, b"NO_SECRET_HERE=ordinary_value\n").unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let (blocked_after, hash_after): (Option<String>, String) = db
+        .query_row(
+            "SELECT json_extract(properties, '$.briefing_blocked'), content_hash \
+               FROM entities \
+              WHERE plugin_id = 'core' AND kind = 'file' \
+                AND source_file_path LIKE '%.env'",
+            [],
+            |row| Ok((row.get(0)?, row.get(1)?)),
+        )
+        .unwrap();
+    assert_eq!(
+        blocked_after, None,
+        "briefing_blocked must be cleared after the secret is removed"
+    );
+    assert_ne!(
+        hash_before, hash_after,
+        "content_hash must reflect the cleaned file, not the secret-bearing run"
+    );
+}
+
+#[test]
+fn clean_sidecar_creates_anchor_without_block() {
+    // Standalone regression: an always-clean sidecar (no secret ever) still
+    // gets a core:file anchor on first scan, with no briefing_blocked. This
+    // exercises the cleared-anchor path independent of the transition test
+    // above, so future breakage is localised even when the two-run
+    // choreography is not exercised.
+    let project = tempfile::tempdir().unwrap();
+    let plugin = tempfile::tempdir().unwrap();
+    write_secret_fixture_plugin(plugin.path());
+    install_project(project.path());
+    std::fs::write(project.path().join("clean.sec"), b"nothing to see\n").unwrap();
+    std::fs::write(
+        project.path().join(".env"),
+        b"NO_SECRET_HERE=ordinary_value\n",
+    )
+    .unwrap();
+
+    clarion_bin()
+        .arg("analyze")
+        .arg(project.path())
+        .env("PATH", plugin_path(plugin.path()))
+        .assert()
+        .success();
+
+    let db = conn(project.path());
+    let (anchor_count, blocked): (i64, Option<String>) = db
+        .query_row(
+            "SELECT COUNT(*), MAX(json_extract(properties, '$.briefing_blocked')) \
+               FROM entities \
+              WHERE plugin_id = 'core' AND kind = 'file' \
+                AND source_file_path LIKE '%.env'",
+            [],
+            |row| Ok((row.get(0)?, row.get(1)?)),
+        )
+        .unwrap();
+    assert_eq!(
+        anchor_count, 1,
+        "clean sidecar must have a core:file anchor"
+    );
+    assert_eq!(
+        blocked, None,
+        "anchor on an always-clean sidecar must have no briefing_blocked"
+    );
+}
diff --git a/crates/clarion-cli/tests/serve.rs b/crates/clarion-cli/tests/serve.rs
index 11670f26..9762ed0f 100644
--- a/crates/clarion-cli/tests/serve.rs
+++ b/crates/clarion-cli/tests/serve.rs
@@ -1,6 +1,12 @@
 use std::fs;
-use std::io::Write;
-use std::process::{Command as StdCommand, Stdio};
+use std::io::{BufRead, Read, Write};
+use std::net::{TcpListener, TcpStream};
+use std::os::unix::fs::PermissionsExt;
+use std::path::Path;
+use std::process::{Child, Command as StdCommand, Stdio};
+use std::sync::mpsc;
+use std::thread;
+use std::time::{Duration, Instant};
 
 use assert_cmd::Command;
 use clarion_core::{
@@ -8,6 +14,33 @@ use clarion_core::{
     plugin::{ContentLengthCeiling, Frame, read_frame, write_frame},
 };
 use rusqlite::{Connection, params};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use uuid::Uuid;
+
+const STABLE_INSTANCE_ID: &str = "9bd7234e-6d44-4a38-9ae4-76f912a10221";
+
+#[derive(Debug)]
+struct HttpJsonResponse {
+    status_code: u16,
+    body: Value,
+}
+
+#[derive(Debug)]
+struct HttpRawResponse {
+    status_code: u16,
+    headers: Vec<(String, String)>,
+    body: String,
+}
+
+impl HttpRawResponse {
+    fn header(&self, name: &str) -> Option<&str> {
+        self.headers
+            .iter()
+            .find(|(candidate, _)| candidate.eq_ignore_ascii_case(name))
+            .map(|(_, value)| value.as_str())
+    }
+}
 
 fn clarion_bin() -> Command {
     Command::cargo_bin("clarion").expect("clarion binary")
@@ -82,7 +115,97 @@ fn serve_stdio_initialize_round_trip() {
 }
 
 #[test]
-fn serve_rejects_invalid_project_config() {
+fn serve_stdio_accepts_mcp_json_line_initialize_without_stdin_eof() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+
+    let mut child = StdCommand::new(assert_cmd::cargo::cargo_bin("clarion"))
+        .args(["serve", "--path"])
+        .arg(dir.path())
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn clarion serve");
+
+    let mut stdin = child.stdin.take().expect("child stdin");
+    let stdout = child.stdout.take().expect("child stdout");
+    let (response_tx, response_rx) = mpsc::channel();
+    let reader = thread::spawn(move || {
+        let mut stdout = std::io::BufReader::new(stdout);
+        let mut line = String::new();
+        let result = stdout.read_line(&mut line).map(|_| line);
+        let _ = response_tx.send(result);
+    });
+
+    let request = serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": 7,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-11-25",
+            "capabilities": {},
+            "clientInfo": {"name": "codex-rmcp-smoke", "version": "0.0.0"}
+        }
+    });
+    writeln!(
+        stdin,
+        "{}",
+        serde_json::to_string(&request).expect("serialize request")
+    )
+    .expect("write initialize json line");
+    stdin.flush().expect("flush initialize json line");
+
+    let line = match response_rx.recv_timeout(Duration::from_secs(2)) {
+        Ok(result) => result.expect("read initialize response line"),
+        Err(err) => {
+            let _ = child.kill();
+            let _ = child.wait();
+            panic!("clarion serve did not answer newline-delimited MCP initialize: {err}");
+        }
+    };
+    let response: Value = serde_json::from_str(line.trim_end()).expect("response line is json");
+
+    drop(stdin);
+    let status = child.wait().expect("wait for clarion serve");
+    reader.join().expect("stdout reader thread");
+
+    assert!(
+        status.success(),
+        "serve failed with status {status}: {}",
+        read_child_stderr(&mut child)
+    );
+    assert_eq!(response["id"], 7);
+    assert_eq!(response["result"]["serverInfo"]["name"], "clarion");
+}
+
+fn read_child_stderr(child: &mut Child) -> String {
+    let mut stderr = String::new();
+    if let Some(mut stream) = child.stderr.take() {
+        let _ = stream.read_to_string(&mut stderr);
+    }
+    stderr
+}
+
+#[test]
+fn serve_http_responses_match_federation_fixture_contracts() {
+    let files_fixture = load_contract_fixture(
+        "get-api-v1-files.demo-python.json",
+        include_str!("../../../docs/federation/fixtures/get-api-v1-files.demo-python.json"),
+    );
+    let capabilities_fixture = load_contract_fixture(
+        "get-api-v1-capabilities.json",
+        include_str!("../../../docs/federation/fixtures/get-api-v1-capabilities.json"),
+    );
+    let files_resolve_fixture = load_contract_fixture(
+        "post-api-v1-files-resolve.batch.json",
+        include_str!("../../../docs/federation/fixtures/post-api-v1-files-resolve.batch.json"),
+    );
     let dir = tempfile::tempdir().expect("temp project");
     clarion_bin()
         .args(["install", "--path"])
@@ -91,23 +214,66 @@ fn serve_rejects_invalid_project_config() {
         .assert()
         .success();
     fs::write(
-        dir.path().join("clarion.yaml"),
-        "llm: [not valid for this schema]\n",
+        dir.path().join(".clarion/instance_id"),
+        format!("{STABLE_INSTANCE_ID}\n"),
     )
-    .expect("write invalid config");
+    .expect("seed stable instance ID");
+    seed_file_entity(dir.path());
+    seed_storage_failure_file_entity(dir.path());
+    seed_briefing_blocked_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
 
-    let assert = clarion_bin()
-        .args(["serve", "--path"])
+    let mut child = spawn_serve(dir.path());
+    validate_fixture_examples(&bind, &files_fixture, "get-api-v1-files.demo-python.json");
+    validate_fixture_examples(
+        &bind,
+        &files_resolve_fixture,
+        "post-api-v1-files-resolve.batch.json",
+    );
+    validate_fixture_examples(&bind, &capabilities_fixture, "get-api-v1-capabilities.json");
+    stop_serve(&mut child);
+}
+
+#[test]
+fn serve_http_files_endpoint_returns_briefing_blocked_for_blocked_entity() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
         .arg(dir.path())
+        .env("PATH", "")
         .assert()
-        .failure();
-    let stderr = String::from_utf8(assert.get_output().stderr.clone()).expect("stderr is utf8");
+        .success();
+    seed_briefing_blocked_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
 
-    assert!(stderr.contains("invalid MCP config"));
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_response(&bind, "/api/v1/files?path=blocked.py&language=python");
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files briefing-blocked response");
+
+    assert_eq!(response.status_code, 403);
+    assert_eq!(response.body["code"], "BRIEFING_BLOCKED");
+    let error = response.body["error"]
+        .as_str()
+        .expect("briefing-blocked error has string message");
+    assert!(
+        error.to_ascii_lowercase().contains("briefing-blocked"),
+        "briefing-blocked message must mention the block: {error}"
+    );
+    assert!(
+        response.body.get("entity_id").is_none(),
+        "blocked responses must not leak the entity_id: {response:?}"
+    );
+    assert!(
+        response.body.get("content_hash").is_none(),
+        "blocked responses must not leak the content hash: {response:?}"
+    );
 }
 
 #[test]
-fn serve_wires_recording_llm_provider_and_writer_for_cached_summary_touches() {
+fn serve_http_files_endpoint_resolves_known_file_on_configured_port() {
     let dir = tempfile::tempdir().expect("temp project");
     clarion_bin()
         .args(["install", "--path"])
@@ -115,99 +281,2403 @@ fn serve_wires_recording_llm_provider_and_writer_for_cached_summary_touches() {
         .env("PATH", "")
         .assert()
         .success();
-    let source_path = dir.path().join("demo.py");
-    fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let (file_id, content_hash, canonical_path) = seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_json(&bind, "/api/v1/files?path=demo.py&language=python");
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files response");
+    let fixture: Value = serde_json::from_str(include_str!(
+        "../../../docs/federation/fixtures/get-api-v1-files.demo-python.json"
+    ))
+    .expect("parse files fixture");
+
+    assert_eq!(response["entity_id"], file_id);
+    assert_eq!(response["content_hash"], content_hash);
+    assert_eq!(response["canonical_path"], canonical_path);
+    assert_eq!(response["language"], "python");
+    assert_eq!(&response, fixture_example_body(&fixture, "happy_path_200"));
+}
+
+#[test]
+fn serve_http_files_endpoint_prefers_stored_manifest_language() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_custom_language_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_json(&bind, "/api/v1/files?path=demo.custom&language=requested");
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files response");
+
+    assert_eq!(response["entity_id"], "core:file:demo.custom");
+    assert_eq!(response["language"], "manifestlang");
+}
+
+#[test]
+fn serve_http_files_etag_round_trip_and_if_none_match_returns_304() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let (_file_id, content_hash, _canonical_path) = seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response =
+        wait_for_http_raw_response(&bind, "/api/v1/files?path=demo.py&language=python", &[]);
+    let not_modified = wait_for_http_raw_response(
+        &bind,
+        "/api/v1/files?path=demo.py&language=python",
+        &[("If-None-Match", "\"hash-demo-file\"")],
+    );
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files response");
+    let not_modified = not_modified.expect("HTTP /api/v1/files conditional response");
+
+    let expected_etag = format!("\"{content_hash}\"");
+    assert_eq!(response.status_code, 200);
+    assert_eq!(response.header("etag"), Some(expected_etag.as_str()));
+    assert_eq!(not_modified.status_code, 304);
+    assert_eq!(not_modified.header("etag"), Some(expected_etag.as_str()));
+    assert!(
+        not_modified.body.is_empty(),
+        "304 response must not include a body: {not_modified:?}"
+    );
+}
+
+#[test]
+fn serve_http_files_blank_path_returns_invalid_path_envelope() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_response(&bind, "/api/v1/files?path=&language=python");
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files error response");
+
+    assert_eq!(response.status_code, 400);
+    assert_eq!(response.body["code"], "INVALID_PATH");
+    assert!(
+        response.body["error"].as_str().is_some(),
+        "error envelope must include a string message: {response:?}"
+    );
+}
+
+#[test]
+fn serve_http_files_rejects_unknown_query_fields() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_response(
+        &bind,
+        "/api/v1/files?path=demo.py&language=python&surprise=1",
+    );
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files query rejection");
+
+    assert_eq!(response.status_code, 400);
+    assert_eq!(response.body["code"], "INVALID_PATH");
+    assert!(
+        response.body["error"].as_str().is_some(),
+        "error envelope must include a string message: {response:?}"
+    );
+}
+
+#[test]
+fn serve_http_rejects_oversized_get_body_before_handler() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let status_code =
+        wait_for_http_get_with_body_status(&bind, "/api/v1/_capabilities", 16 * 1024 + 1);
+    stop_serve(&mut child);
+    let status_code = status_code.expect("HTTP response to oversized body");
+
+    assert_eq!(status_code, 413);
+}
+
+#[test]
+fn serve_http_files_path_traversal_returns_outside_project_envelope() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response =
+        wait_for_http_response(&bind, "/api/v1/files?path=../outside.py&language=python");
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files error response");
+
+    assert_eq!(response.status_code, 400);
+    assert_eq!(response.body["code"], "PATH_OUTSIDE_PROJECT");
+    assert!(
+        response.body["error"].as_str().is_some(),
+        "error envelope must include a string message: {response:?}"
+    );
+}
+
+#[test]
+fn serve_http_files_unknown_catalog_file_returns_not_found_envelope() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_response(&bind, "/api/v1/files?path=missing.py&language=python");
+    stop_serve(&mut child);
+    let response = response.expect("HTTP /api/v1/files error response");
+
+    assert_eq!(response.status_code, 404);
+    assert_eq!(response.body["code"], "NOT_FOUND");
+    assert!(
+        response.body["error"].as_str().is_some(),
+        "error envelope must include a string message: {response:?}"
+    );
+}
+
+#[test]
+fn serve_http_files_storage_failure_returns_closed_error_without_raw_detail() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+    let source_path = dir.path().join("missing-on-disk.py");
+    fs::write(&source_path, "def missing():\n    return 1\n").expect("write source");
+    let canonical_path = source_path
+        .canonicalize()
+        .expect("canonical source path")
+        .display()
+        .to_string();
     let db_path = dir.path().join(".clarion/clarion.db");
     let conn = Connection::open(&db_path).expect("open sqlite");
     conn.execute(
         "INSERT INTO entities (
             id, plugin_id, kind, name, short_name, source_file_path,
-            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
-         ) VALUES (
-            'python:function:demo.entry', 'python', 'function',
-            'python:function:demo.entry', 'entry', ?1,
-            1, 2, '{}', 'hash-entry',
-            '2026-05-17T00:00:00.000Z', '2026-05-17T00:00:00.000Z'
-         )",
-        params![source_path.display().to_string()],
-    )
-    .expect("insert entity");
-    conn.execute(
-        "INSERT INTO summary_cache (
-            entity_id, content_hash, prompt_template_id, model_tier,
-            guidance_fingerprint, summary_json, cost_usd, tokens_input,
-            tokens_output, created_at, last_accessed_at, caller_count,
-            fan_out, stale_semantic
+            source_line_start, source_line_end, properties, created_at, updated_at
          ) VALUES (
-            'python:function:demo.entry', 'hash-entry', ?1, 'anthropic/claude-sonnet-4.6',
-            'guidance-empty', '{\"purpose\":\"cached\"}', 0.001, 10,
-            5, '2026-05-17T00:00:00.000Z', 'old-touch', 0, 0, 0
+            'core:file:missing-on-disk.py', 'core', 'file',
+            'missing-on-disk.py', 'missing-on-disk.py', ?1,
+            1, 2, '{}',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
          )",
-        params![LEAF_SUMMARY_PROMPT_TEMPLATE_ID],
+        params![canonical_path],
     )
-    .expect("insert summary cache");
+    .expect("insert file entity without cached hash");
     drop(conn);
+    fs::remove_file(&source_path).expect("remove cataloged file to force storage failure");
+
+    let mut child = spawn_serve(dir.path());
+    let capabilities = wait_for_http_response(&bind, "/api/v1/_capabilities");
+    let response = wait_for_http_response(
+        &bind,
+        "/api/v1/files?path=missing-on-disk.py&language=python",
+    );
+    stop_serve(&mut child);
+    let capabilities = capabilities.expect("HTTP /api/v1/_capabilities response");
+    assert_eq!(capabilities.status_code, 200);
+    let response = response.expect("HTTP /api/v1/files storage error response");
+
+    assert!(
+        response.status_code == 500 || response.status_code == 503,
+        "storage failures must be 500-class: {response:?}"
+    );
+    // The fixture pins this code: the deleted-file-on-disk path runs
+    // through `StorageError::Io` in `into_resolved_file`, which the HTTP
+    // surface classifies as `STORAGE_ERROR`. The historical `|| INTERNAL`
+    // fallback masked silent drift in the classifier; tighten it so any
+    // future re-categorisation surfaces here rather than at a federation
+    // consumer.
+    assert_eq!(
+        response.body["code"], "STORAGE_ERROR",
+        "unexpected storage failure code: {response:?}"
+    );
+    let body = response.body.to_string();
+    assert!(!body.to_ascii_lowercase().contains("sqlite"));
+    assert!(!body.contains("not a database"));
+    assert!(!body.contains("No such file"));
+    assert!(!body.contains("no such column"));
+    assert!(!body.contains("no such table"));
+    assert!(!body.contains(&dir.path().display().to_string()));
+}
+
+#[test]
+fn serve_http_capabilities_and_mcp_stdio_coexist() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
     fs::write(
-        dir.path().join("clarion.yaml"),
-        "llm:\n  enabled: true\n  provider: recording\n",
+        dir.path().join(".clarion/instance_id"),
+        format!("{STABLE_INSTANCE_ID}\n"),
     )
-    .expect("write config");
+    .expect("seed stable instance ID");
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let capabilities = wait_for_http_json(&bind, "/api/v1/_capabilities")
+        .expect("HTTP /api/v1/_capabilities response");
+
+    assert_eq!(capabilities["registry_backend"], true);
+    assert_eq!(capabilities["file_registry"], true);
+    assert_eq!(capabilities["api_version"], 1);
+    assert!(capabilities.get("version").is_none());
+    let instance_id = capabilities["instance_id"]
+        .as_str()
+        .expect("instance_id is a string");
+    Uuid::parse_str(instance_id).expect("instance_id is a UUID");
+    let fixture: Value = serde_json::from_str(include_str!(
+        "../../../docs/federation/fixtures/get-api-v1-capabilities.json"
+    ))
+    .expect("parse capabilities fixture");
+    assert_eq!(
+        &capabilities,
+        fixture_example_body(&fixture, "capabilities_200")
+    );
 
-    let mut child = StdCommand::new(assert_cmd::cargo::cargo_bin("clarion"))
-        .args(["serve", "--path"])
-        .arg(dir.path())
-        .stdin(Stdio::piped())
-        .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
-        .spawn()
-        .expect("spawn clarion serve");
     {
-        let mut stdin = child.stdin.take().expect("child stdin");
+        let stdin = child.stdin.as_mut().expect("child stdin");
         write_frame(
-            &mut stdin,
+            stdin,
             &Frame {
                 body: serde_json::to_vec(&serde_json::json!({
                     "jsonrpc": "2.0",
-                    "id": 7,
-                    "method": "tools/call",
+                    "id": 42,
+                    "method": "initialize",
                     "params": {
-                        "name": "summary",
-                        "arguments": {"id": "python:function:demo.entry"}
+                        "protocolVersion": "2025-11-25",
+                        "capabilities": {},
+                        "clientInfo": {"name": "test-client", "version": "0.0.0"}
                     }
                 }))
                 .expect("serialize request"),
             },
         )
-        .expect("write summary frame");
-        stdin.flush().expect("flush summary frame");
+        .expect("write initialize frame");
+        stdin.flush().expect("flush initialize frame");
     }
-
+    drop(child.stdin.take());
     let output = child.wait_with_output().expect("wait for clarion serve");
+
     assert!(
         output.status.success(),
         "serve failed: {}",
         String::from_utf8_lossy(&output.stderr)
     );
     let mut reader = std::io::BufReader::new(std::io::Cursor::new(output.stdout));
-    let frame =
-        read_frame(&mut reader, ContentLengthCeiling::new(usize::MAX)).expect("read response");
+    let frame = read_frame(&mut reader, ContentLengthCeiling::new(usize::MAX))
+        .expect("read initialize response");
     let response: serde_json::Value =
         serde_json::from_slice(&frame.body).expect("response body is json");
-    let tool_text = response["result"]["content"][0]["text"]
-        .as_str()
-        .expect("tool text");
-    let envelope: serde_json::Value = serde_json::from_str(tool_text).expect("tool envelope");
 
-    assert_eq!(envelope["ok"], true);
+    assert_eq!(response["id"], 42);
+    assert_eq!(response["result"]["serverInfo"]["name"], "clarion");
+}
+
+#[test]
+fn serve_http_capabilities_reuses_persisted_instance_id_across_restarts() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let instance_id_path = dir.path().join(".clarion/instance_id");
+
+    let first_bind = free_loopback_bind();
+    write_http_config(dir.path(), &first_bind);
+    let mut first_child = spawn_serve(dir.path());
+    let first = wait_for_http_json(&first_bind, "/api/v1/_capabilities")
+        .expect("first capabilities response");
+    stop_serve(&mut first_child);
+    let first_instance_id = first["instance_id"]
+        .as_str()
+        .expect("first instance_id")
+        .to_owned();
+    assert_eq!(
+        fs::read_to_string(&instance_id_path)
+            .expect("read first persisted instance_id")
+            .trim(),
+        first_instance_id
+    );
+
+    let second_bind = free_loopback_bind();
+    write_http_config(dir.path(), &second_bind);
+    let mut second_child = spawn_serve(dir.path());
+    let second = wait_for_http_json(&second_bind, "/api/v1/_capabilities")
+        .expect("second capabilities response");
+    stop_serve(&mut second_child);
+
+    assert_eq!(second["instance_id"], first["instance_id"]);
+    assert_eq!(
+        fs::read_to_string(&instance_id_path)
+            .expect("read second persisted instance_id")
+            .trim(),
+        first_instance_id
+    );
+}
+
+/// C12 rotation positive case. The sibling
+/// `_reuses_persisted_instance_id_across_restarts` test proves *stability*
+/// (the same persisted file produces the same `instance_id`), which silently
+/// passes a regression that ignores the file and re-mints on every boot.
+/// This test proves the *rotation* direction: overwriting the persisted
+/// file between restarts causes `/api/v1/_capabilities` to surface the new
+/// UUID. Without it, a future refactor could hard-code a per-process UUID
+/// and pass every existing capabilities test.
+#[test]
+fn serve_http_capabilities_returns_new_instance_id_after_rotation() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let instance_id_path = dir.path().join(".clarion/instance_id");
+
+    let first_bind = free_loopback_bind();
+    write_http_config(dir.path(), &first_bind);
+    let mut first_child = spawn_serve(dir.path());
+    let first = wait_for_http_json(&first_bind, "/api/v1/_capabilities")
+        .expect("first capabilities response");
+    stop_serve(&mut first_child);
+    let first_instance_id = first["instance_id"]
+        .as_str()
+        .expect("first instance_id")
+        .to_owned();
+
+    // Rotate: overwrite the persisted file with a different valid UUID.
+    let rotated_uuid = Uuid::new_v4().to_string();
+    assert_ne!(
+        rotated_uuid, first_instance_id,
+        "rotated UUID must differ from the first to make the test meaningful"
+    );
+    fs::write(&instance_id_path, format!("{rotated_uuid}\n")).expect("rotate instance_id file");
+
+    let second_bind = free_loopback_bind();
+    write_http_config(dir.path(), &second_bind);
+    let mut second_child = spawn_serve(dir.path());
+    let second = wait_for_http_json(&second_bind, "/api/v1/_capabilities")
+        .expect("second capabilities response");
+    stop_serve(&mut second_child);
+
+    assert_eq!(
+        second["instance_id"], rotated_uuid,
+        "after rotation, /_capabilities must surface the new persisted UUID"
+    );
+    assert_ne!(
+        second["instance_id"], first["instance_id"],
+        "rotated response must differ from the pre-rotation response"
+    );
+    assert_eq!(
+        fs::read_to_string(&instance_id_path)
+            .expect("read post-rotation persisted instance_id")
+            .trim(),
+        rotated_uuid,
+        "post-rotation file content must remain the rotated UUID"
+    );
+}
+
+#[test]
+fn serve_http_capabilities_creates_instance_id_with_private_unix_mode() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let capabilities = wait_for_http_json(&bind, "/api/v1/_capabilities")
+        .expect("HTTP /api/v1/_capabilities response");
+    stop_serve(&mut child);
+
+    let instance_id_path = dir.path().join(".clarion/instance_id");
+    assert_eq!(
+        fs::read_to_string(&instance_id_path)
+            .expect("read persisted instance_id")
+            .trim(),
+        capabilities["instance_id"].as_str().expect("instance_id")
+    );
+    let mode = fs::metadata(instance_id_path)
+        .expect("instance_id metadata")
+        .permissions()
+        .mode()
+        & 0o777;
+    assert_eq!(mode, 0o600);
+}
+
+#[test]
+fn serve_http_capabilities_repairs_existing_instance_id_mode() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let instance_id_path = dir.path().join(".clarion/instance_id");
+    let seeded_id = "9bd7234e-6d44-4a38-9ae4-76f912a10221";
+    fs::write(&instance_id_path, format!("{seeded_id}\n")).expect("seed instance ID");
+    fs::set_permissions(&instance_id_path, fs::Permissions::from_mode(0o644))
+        .expect("seed permissive instance ID mode");
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let capabilities = wait_for_http_json(&bind, "/api/v1/_capabilities");
+    stop_serve(&mut child);
+    let capabilities = capabilities.expect("HTTP /api/v1/_capabilities response");
+
+    assert_eq!(capabilities["instance_id"], seeded_id);
+    let mode = fs::metadata(instance_id_path)
+        .expect("instance_id metadata")
+        .permissions()
+        .mode()
+        & 0o777;
+    assert_eq!(mode, 0o600);
+}
+
+#[test]
+fn serve_rejects_invalid_instance_id_before_serving_http() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    fs::write(dir.path().join(".clarion/instance_id"), "not-a-uuid\n")
+        .expect("write invalid instance ID");
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let child = spawn_serve(dir.path());
+    let output = wait_for_child_exit(child, Duration::from_secs(2))
+        .expect("serve should fail before accepting HTTP requests");
+
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("invalid Clarion instance ID"),
+        "unexpected stderr: {stderr}"
+    );
+}
+
+#[test]
+fn serve_http_batch_endpoint_resolves_mixed_paths() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    seed_briefing_blocked_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let body = serde_json::json!({
+        "queries": [
+            {"path": "demo.py", "language": "python"},
+            {"path": "missing.py", "language": ""},
+            {"path": "blocked.py", "language": "python"},
+            {"path": "../escapes.py", "language": "python"},
+            {"path": "  ", "language": ""}
+        ]
+    })
+    .to_string();
+    let response = wait_for_http_post_json(&bind, "/api/v1/files/batch", &body, &[]);
+    stop_serve(&mut child);
+    let response = response.expect("batch response");
+
+    assert_eq!(response.status_code, 200);
+    let resolved = response.body["resolved"]
+        .as_array()
+        .expect("resolved array");
+    assert_eq!(resolved.len(), 1, "{response:?}");
+    assert_eq!(resolved[0]["requested_path"], "demo.py");
+    assert_eq!(resolved[0]["entity_id"], "core:file:demo.py");
+    assert_eq!(resolved[0]["content_hash"], "hash-demo-file");
+    assert_eq!(resolved[0]["canonical_path"], "demo.py");
+    assert_eq!(resolved[0]["language"], "python");
+
+    let not_found = response.body["not_found"].as_array().expect("not_found");
+    assert_eq!(not_found.len(), 1);
+    assert_eq!(not_found[0], "missing.py");
+
+    let blocked = response.body["briefing_blocked"]
+        .as_array()
+        .expect("briefing_blocked");
+    assert_eq!(blocked.len(), 1);
+    assert_eq!(blocked[0], "blocked.py");
+
+    let errors = response.body["errors"].as_array().expect("errors");
+    assert_eq!(errors.len(), 2);
+    let by_path: std::collections::HashMap<&str, &Value> = errors
+        .iter()
+        .filter_map(|err| err["requested_path"].as_str().map(|p| (p, err)))
+        .collect();
+    let outside = by_path
+        .get("../escapes.py")
+        .expect("outside-root error entry");
+    assert_eq!(outside["code"], "PATH_OUTSIDE_PROJECT");
+    let blank = by_path.get("  ").expect("blank-path error entry");
+    assert_eq!(blank["code"], "INVALID_PATH");
+}
+
+#[test]
+fn serve_http_files_resolve_endpoint_returns_per_path_results() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    seed_briefing_blocked_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let mut child = spawn_serve(dir.path());
+    let body = serde_json::json!({
+        "paths": [
+            {"path": "demo.py", "language": "python"},
+            {"path": "missing.py"},
+            {"path": "blocked.py", "language": "python"},
+            {"path": "../escapes.py", "language": "python"},
+            {"path": "  "}
+        ]
+    })
+    .to_string();
+    let response = wait_for_http_post_json(&bind, "/api/v1/files:resolve", &body, &[]);
+    stop_serve(&mut child);
+    let response = response.expect("files:resolve response");
+
+    assert_eq!(response.status_code, 200);
+    let results = response.body["results"].as_array().expect("results array");
+    assert_eq!(results.len(), 5, "{response:?}");
+
+    assert_eq!(results[0]["path"], "demo.py");
+    assert_eq!(results[0]["response"]["status"], "resolved");
+    assert_eq!(
+        results[0]["response"]["body"]["entity_id"],
+        "core:file:demo.py"
+    );
+    assert_eq!(
+        results[0]["response"]["body"]["content_hash"],
+        "hash-demo-file"
+    );
+    assert_eq!(results[0]["response"]["body"]["canonical_path"], "demo.py");
+    assert_eq!(results[0]["response"]["body"]["language"], "python");
+
+    assert_eq!(results[1]["path"], "missing.py");
+    assert_eq!(results[1]["response"]["status"], "not_found");
+    assert_eq!(results[1]["response"]["body"]["code"], "NOT_FOUND");
+
+    assert_eq!(results[2]["path"], "blocked.py");
+    assert_eq!(results[2]["response"]["status"], "blocked");
+    assert_eq!(results[2]["response"]["body"]["code"], "BRIEFING_BLOCKED");
+
+    assert_eq!(results[3]["path"], "../escapes.py");
+    assert_eq!(results[3]["response"]["status"], "error");
+    assert_eq!(
+        results[3]["response"]["body"]["code"],
+        "PATH_OUTSIDE_PROJECT"
+    );
+
+    assert_eq!(results[4]["path"], "  ");
+    assert_eq!(results[4]["response"]["status"], "error");
+    assert_eq!(results[4]["response"]["body"]["code"], "INVALID_PATH");
+}
+
+#[test]
+fn serve_http_files_resolve_rejects_over_1000_paths() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let paths: Vec<Value> = (0..1001).map(|_| serde_json::json!({"path": ""})).collect();
+    let body = serde_json::json!({"paths": paths}).to_string();
+    assert!(
+        body.len() <= 16 * 1024,
+        "test body should fit under the transport cap: {} bytes",
+        body.len()
+    );
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_post_json(&bind, "/api/v1/files:resolve", &body, &[]);
+    stop_serve(&mut child);
+    let response = response.expect("files:resolve over-limit response");
+
+    assert_eq!(response.status_code, 400);
+    assert_eq!(response.body["code"], "INVALID_PATH");
+    assert!(
+        response.body["error"]
+            .as_str()
+            .is_some_and(|msg| msg.contains("1000")),
+        "error message should cite the 1000-path ceiling: {response:?}"
+    );
+}
+
+#[test]
+fn serve_http_batch_rejects_over_256_queries() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config(dir.path(), &bind);
+
+    let queries: Vec<Value> = (0..257)
+        .map(|i| serde_json::json!({"path": format!("p{i}.py"), "language": ""}))
+        .collect();
+    let body = serde_json::json!({"queries": queries}).to_string();
+    assert!(
+        body.len() <= 16 * 1024,
+        "test body should fit under the 16 KB body cap to exercise the AFTER-parse 256 limit: {} bytes",
+        body.len()
+    );
+
+    let mut child = spawn_serve(dir.path());
+    let response = wait_for_http_post_json(&bind, "/api/v1/files/batch", &body, &[]);
+    stop_serve(&mut child);
+    let response = response.expect("batch over-limit response");
+
+    assert_eq!(response.status_code, 400);
+    assert_eq!(response.body["code"], "BATCH_TOO_LARGE");
+    assert!(
+        response.body["error"]
+            .as_str()
+            .is_some_and(|msg| msg.contains("256")),
+        "error message should cite the 256-query ceiling: {response:?}"
+    );
+}
+
+#[test]
+fn serve_http_batch_requires_auth_when_configured() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config_with_token_env(dir.path(), &bind, "CLARION_TEST_LOOM_TOKEN_BATCH");
+
+    let mut child = spawn_serve_with_env(
+        dir.path(),
+        &[("CLARION_TEST_LOOM_TOKEN_BATCH", "batch-secret")],
+    );
+    let body = serde_json::json!({
+        "queries": [{"path": "demo.py", "language": "python"}]
+    })
+    .to_string();
+    let unauthenticated = wait_for_http_post_json(&bind, "/api/v1/files/batch", &body, &[]);
+    let authenticated = wait_for_http_post_json(
+        &bind,
+        "/api/v1/files/batch",
+        &body,
+        &[("Authorization", "Bearer batch-secret")],
+    );
+    stop_serve(&mut child);
+    let unauthenticated = unauthenticated.expect("unauthenticated batch");
+    let authenticated = authenticated.expect("authenticated batch");
+
+    assert_eq!(unauthenticated.status_code, 401);
+    assert_eq!(unauthenticated.body["code"], "UNAUTHENTICATED");
+    assert_eq!(authenticated.status_code, 200);
+    let resolved = authenticated.body["resolved"]
+        .as_array()
+        .expect("authenticated batch resolved");
+    assert_eq!(resolved.len(), 1);
+    assert_eq!(resolved[0]["entity_id"], "core:file:demo.py");
+}
+
+#[test]
+fn serve_http_files_endpoint_requires_bearer_token_when_configured() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config_with_token_env(dir.path(), &bind, "CLARION_TEST_LOOM_TOKEN_REQ");
+
+    let mut child = spawn_serve_with_env(
+        dir.path(),
+        &[("CLARION_TEST_LOOM_TOKEN_REQ", "shh-its-a-secret")],
+    );
+    let unauthenticated =
+        wait_for_http_response(&bind, "/api/v1/files?path=demo.py&language=python");
+    let authenticated = wait_for_http_raw_response(
+        &bind,
+        "/api/v1/files?path=demo.py&language=python",
+        &[("Authorization", "Bearer shh-its-a-secret")],
+    );
+    stop_serve(&mut child);
+    let unauthenticated = unauthenticated.expect("unauthenticated probe response");
+    let authenticated = authenticated.expect("authenticated probe response");
+
+    assert_eq!(unauthenticated.status_code, 401);
+    assert_eq!(unauthenticated.body["code"], "UNAUTHENTICATED");
+    assert_eq!(authenticated.status_code, 200);
+    let body: Value =
+        serde_json::from_str(&authenticated.body).expect("authenticated body is JSON");
+    assert_eq!(body["entity_id"], "core:file:demo.py");
+}
+
+#[test]
+fn serve_http_files_endpoint_rejects_wrong_token() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config_with_token_env(dir.path(), &bind, "CLARION_TEST_LOOM_TOKEN_WRONG");
+
+    let mut child = spawn_serve_with_env(
+        dir.path(),
+        &[("CLARION_TEST_LOOM_TOKEN_WRONG", "correct-horse")],
+    );
+    let wrong = wait_for_http_raw_response(
+        &bind,
+        "/api/v1/files?path=demo.py&language=python",
+        &[("Authorization", "Bearer battery-staple")],
+    );
+    let blank = wait_for_http_raw_response(
+        &bind,
+        "/api/v1/files?path=demo.py&language=python",
+        &[("Authorization", "Bearer ")],
+    );
+    let wrong_scheme = wait_for_http_raw_response(
+        &bind,
+        "/api/v1/files?path=demo.py&language=python",
+        &[("Authorization", "Basic correct-horse")],
+    );
+    stop_serve(&mut child);
+    let wrong = wrong.expect("wrong-token response");
+    let blank = blank.expect("blank-token response");
+    let wrong_scheme = wrong_scheme.expect("wrong-scheme response");
+
+    for (name, response) in [
+        ("wrong", &wrong),
+        ("blank", &blank),
+        ("wrong-scheme", &wrong_scheme),
+    ] {
+        assert_eq!(response.status_code, 401, "{name}: {response:?}");
+        let body: Value = serde_json::from_str(&response.body)
+            .unwrap_or_else(|err| panic!("{name} body parse: {err}; raw={:?}", response.body));
+        assert_eq!(body["code"], "UNAUTHENTICATED", "{name}");
+    }
+}
+
+#[test]
+fn serve_http_files_endpoint_requires_hmac_identity_when_configured() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config_with_identity_token_env(dir.path(), &bind, "CLARION_TEST_LOOM_IDENTITY_REQ");
+
+    let mut child = spawn_serve_with_env(
+        dir.path(),
+        &[("CLARION_TEST_LOOM_IDENTITY_REQ", "shared-secret")],
+    );
+    let path = "/api/v1/files?path=demo.py&language=python";
+    let missing = wait_for_http_raw_response(&bind, path, &[]);
+    let signed_header = hmac_component_header("shared-secret", "GET", path, b"");
+    let signed = wait_for_http_raw_response(&bind, path, &[("X-Loom-Component", &signed_header)]);
+    stop_serve(&mut child);
+    let missing = missing.expect("missing identity response");
+    let signed = signed.expect("signed identity response");
+
+    assert_eq!(missing.status_code, 401);
+    let missing_body: Value =
+        serde_json::from_str(&missing.body).expect("missing identity body is JSON");
+    assert_eq!(missing_body["code"], "UNAUTHENTICATED");
+    assert_eq!(signed.status_code, 200);
+    let signed_body: Value = serde_json::from_str(&signed.body).expect("signed body is JSON");
+    assert_eq!(signed_body["entity_id"], "core:file:demo.py");
+}
+
+#[test]
+fn serve_http_files_endpoint_rejects_wrong_hmac_identity() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_file_entity(dir.path());
+    let bind = free_loopback_bind();
+    write_http_config_with_identity_token_env(
+        dir.path(),
+        &bind,
+        "CLARION_TEST_LOOM_IDENTITY_WRONG",
+    );
+
+    let mut child = spawn_serve_with_env(
+        dir.path(),
+        &[("CLARION_TEST_LOOM_IDENTITY_WRONG", "shared-secret")],
+    );
+    let path = "/api/v1/files?path=demo.py&language=python";
+    let wrong_header = hmac_component_header("other-secret", "GET", path, b"");
+    let response = wait_for_http_raw_response(&bind, path, &[("X-Loom-Component", &wrong_header)]);
+    stop_serve(&mut child);
+    let response = response.expect("wrong identity response");
+    let body: Value = serde_json::from_str(&response.body).expect("wrong identity body is JSON");
+
+    assert_eq!(response.status_code, 401);
+    assert_eq!(body["code"], "UNAUTHENTICATED");
+}
+
+#[test]
+fn serve_http_capabilities_does_not_require_token() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config_with_token_env(dir.path(), &bind, "CLARION_TEST_LOOM_TOKEN_CAPS");
+
+    let mut child = spawn_serve_with_env(
+        dir.path(),
+        &[("CLARION_TEST_LOOM_TOKEN_CAPS", "any-token-value")],
+    );
+    let response = wait_for_http_response(&bind, "/api/v1/_capabilities");
+    stop_serve(&mut child);
+    let response = response.expect("capabilities probe response");
+
+    assert_eq!(response.status_code, 200);
+    assert_eq!(response.body["registry_backend"], true);
+    assert_eq!(response.body["api_version"], 1);
+}
+
+#[test]
+fn serve_http_refuses_startup_on_non_loopback_without_token() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    // Non-loopback bind + allow_non_loopback opt-in + token_env unset
+    // should refuse to start with CLA-CONFIG-HTTP-NO-AUTH.
+    fs::write(
+        dir.path().join("clarion.yaml"),
+        "version: 1\nserve:\n  http:\n    enabled: true\n    bind: \"0.0.0.0:0\"\n    \
+         allow_non_loopback: true\n    token_env: \"CLARION_TEST_LOOM_TOKEN_REFUSE\"\n",
+    )
+    .expect("write non-loopback HTTP config without token env");
+
+    let child = spawn_serve_with_env(dir.path(), &[]);
+    let output = wait_for_child_exit(child, Duration::from_secs(2))
+        .expect("serve should refuse to start without auth on non-loopback");
+
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("CLA-CONFIG-HTTP-NO-AUTH"),
+        "error should cite CLA-CONFIG-HTTP-NO-AUTH: {stderr}"
+    );
+    assert!(
+        stderr.contains("CLARION_TEST_LOOM_TOKEN_REFUSE"),
+        "error should name the configured token_env: {stderr}"
+    );
+}
+
+#[test]
+fn serve_http_refuses_startup_when_identity_env_is_missing() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let bind = free_loopback_bind();
+    write_http_config_with_identity_token_env(
+        dir.path(),
+        &bind,
+        "CLARION_TEST_LOOM_IDENTITY_MISSING",
+    );
+
+    let child = spawn_serve_with_env(dir.path(), &[]);
+    let output = wait_for_child_exit(child, Duration::from_secs(2))
+        .expect("serve should refuse to start when identity env is missing");
+
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("CLA-CONFIG-HTTP-IDENTITY-MISSING"),
+        "error should cite CLA-CONFIG-HTTP-IDENTITY-MISSING: {stderr}"
+    );
+    assert!(
+        stderr.contains("CLARION_TEST_LOOM_IDENTITY_MISSING"),
+        "error should name the configured identity_token_env: {stderr}"
+    );
+}
+
+#[test]
+fn serve_rejects_non_loopback_http_bind_before_binding_without_opt_in() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    fs::write(
+        dir.path().join("clarion.yaml"),
+        "version: 1\nserve:\n  http:\n    enabled: true\n    bind: \"0.0.0.0:0\"\n",
+    )
+    .expect("write non-loopback HTTP config");
+
+    let child = spawn_serve(dir.path());
+    let output = wait_for_child_exit(child, Duration::from_secs(2))
+        .expect("serve should reject non-loopback HTTP bind before binding");
+
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("unauthenticated non-loopback"),
+        "error should explain non-loopback unauthenticated risk: {stderr}"
+    );
+    assert!(
+        stderr.contains("allow_non_loopback"),
+        "error should name the explicit opt-in: {stderr}"
+    );
+}
+
+#[test]
+fn serve_rejects_invalid_project_config() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    fs::write(
+        dir.path().join("clarion.yaml"),
+        "llm: [not valid for this schema]\n",
+    )
+    .expect("write invalid config");
+
+    let assert = clarion_bin()
+        .args(["serve", "--path"])
+        .arg(dir.path())
+        .assert()
+        .failure();
+    let stderr = String::from_utf8(assert.get_output().stderr.clone()).expect("stderr is utf8");
+
+    assert!(stderr.contains("invalid MCP config"));
+}
+
+#[test]
+fn serve_wires_recording_llm_provider_and_writer_for_cached_summary_touches() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    let source_path = dir.path().join("demo.py");
+    fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let db_path = dir.path().join(".clarion/clarion.db");
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:function:demo.entry', 'python', 'function',
+            'python:function:demo.entry', 'entry', ?1,
+            1, 2, '{}', 'hash-entry',
+            '2026-05-17T00:00:00.000Z', '2026-05-17T00:00:00.000Z'
+         )",
+        params![source_path.display().to_string()],
+    )
+    .expect("insert entity");
+    conn.execute(
+        "INSERT INTO summary_cache (
+            entity_id, content_hash, prompt_template_id, model_tier,
+            guidance_fingerprint, summary_json, cost_usd, tokens_input,
+            tokens_output, created_at, last_accessed_at, caller_count,
+            fan_out, stale_semantic
+         ) VALUES (
+            'python:function:demo.entry', 'hash-entry', ?1, 'anthropic/claude-sonnet-4.6',
+            'guidance-empty', '{\"purpose\":\"cached\"}', 0.001, 10,
+            5, '2026-05-17T00:00:00.000Z', 'old-touch', 0, 0, 0
+         )",
+        params![LEAF_SUMMARY_PROMPT_TEMPLATE_ID],
+    )
+    .expect("insert summary cache");
+    drop(conn);
+    fs::write(
+        dir.path().join("clarion.yaml"),
+        "llm:\n  enabled: true\n  provider: recording\n",
+    )
+    .expect("write config");
+
+    let mut child = StdCommand::new(assert_cmd::cargo::cargo_bin("clarion"))
+        .args(["serve", "--path"])
+        .arg(dir.path())
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn clarion serve");
+    {
+        let mut stdin = child.stdin.take().expect("child stdin");
+        write_frame(
+            &mut stdin,
+            &Frame {
+                body: serde_json::to_vec(&serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 7,
+                    "method": "tools/call",
+                    "params": {
+                        "name": "summary",
+                        "arguments": {"id": "python:function:demo.entry"}
+                    }
+                }))
+                .expect("serialize request"),
+            },
+        )
+        .expect("write summary frame");
+        stdin.flush().expect("flush summary frame");
+    }
+
+    let output = child.wait_with_output().expect("wait for clarion serve");
+    assert!(
+        output.status.success(),
+        "serve failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let mut reader = std::io::BufReader::new(std::io::Cursor::new(output.stdout));
+    let frame =
+        read_frame(&mut reader, ContentLengthCeiling::new(usize::MAX)).expect("read response");
+    let response: serde_json::Value =
+        serde_json::from_slice(&frame.body).expect("response body is json");
+    let tool_text = response["result"]["content"][0]["text"]
+        .as_str()
+        .expect("tool text");
+    let envelope: serde_json::Value = serde_json::from_str(tool_text).expect("tool envelope");
+
+    assert_eq!(envelope["ok"], true);
     assert_eq!(envelope["result"]["cache"]["hit"], true);
 
-    let conn = Connection::open(&db_path).expect("reopen sqlite");
-    let touched: String = conn
-        .query_row(
-            "SELECT last_accessed_at FROM summary_cache WHERE entity_id = ?1",
-            params!["python:function:demo.entry"],
-            |row| row.get(0),
+    let conn = Connection::open(&db_path).expect("reopen sqlite");
+    let touched: String = conn
+        .query_row(
+            "SELECT last_accessed_at FROM summary_cache WHERE entity_id = ?1",
+            params!["python:function:demo.entry"],
+            |row| row.get(0),
+        )
+        .expect("read touched cache row");
+    assert_ne!(touched, "old-touch");
+}
+
+#[test]
+fn serve_routes_summary_miss_through_codex_cli_provider() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_summary_entity(dir.path());
+
+    let fake_codex = dir.path().join("fake-codex");
+    let prompt_log = dir.path().join("codex-prompt.log");
+    fs::write(
+        &fake_codex,
+        format!(
+            r#"#!/usr/bin/env bash
+set -euo pipefail
+out=""
+schema=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    exec|--json|-)
+      shift
+      ;;
+    --output-last-message)
+      out="$2"
+      shift 2
+      ;;
+    --output-schema)
+      schema="$2"
+      shift 2
+      ;;
+    --sandbox|--cd|-c|--model|--profile)
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+stdin_prompt="$(cat)"
+printf '%s' "$stdin_prompt" > "{prompt_log}"
+case "$stdin_prompt" in
+  *"Prompt contract: clarion-agent-provider-v1"*"Do not inspect additional files"*"Source excerpt:"*) ;;
+  *) echo "missing Clarion agent prompt contract" >&2; exit 32 ;;
+esac
+grep -q '"purpose"' "$schema"
+printf '%s\n' '{{"usage":{{"input_tokens":31,"cached_input_tokens":9,"output_tokens":7,"total_tokens":38}}}}'
+printf '%s' '{{"purpose":"via codex serve","behavior":"served through fake Codex CLI","relationships":"","risks":""}}' > "$out"
+"#,
+            prompt_log = prompt_log.display()
+        ),
+    )
+    .expect("write fake codex");
+    make_executable(&fake_codex);
+    write_provider_config(
+        dir.path(),
+        "codex_cli",
+        r#"
+  codex_cli:
+    executable: "__EXECUTABLE__"
+    model: null
+    profile: null
+    sandbox: read-only
+    timeout_seconds: 5
+"#,
+        &fake_codex,
+    );
+
+    let envelope = call_summary_through_serve(dir.path());
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["cache"]["hit"], false);
+    assert_eq!(envelope["result"]["summary"]["purpose"], "via codex serve");
+    assert_eq!(envelope["result"]["usage"]["tokens_cached_input"], 9);
+    assert_eq!(envelope["stats_delta"]["summary_tokens_cached_input"], 9);
+    assert!(
+        fs::read_to_string(prompt_log)
+            .expect("read Codex prompt log")
+            .contains("Prompt contract: clarion-agent-provider-v1")
+    );
+}
+
+#[test]
+fn serve_routes_summary_miss_through_claude_cli_provider() {
+    let dir = tempfile::tempdir().expect("temp project");
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .env("PATH", "")
+        .assert()
+        .success();
+    seed_summary_entity(dir.path());
+
+    let fake_claude = dir.path().join("fake-claude");
+    let prompt_log = dir.path().join("claude-prompt.log");
+    fs::write(
+        &fake_claude,
+        format!(
+            r#"#!/usr/bin/env bash
+set -euo pipefail
+schema=""
+print_prompt=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -p|--print)
+      print_prompt="$2"
+      shift 2
+      ;;
+    --json-schema)
+      schema="$2"
+      shift 2
+      ;;
+    --output-format|--permission-mode|--max-turns|--model|--tools)
+      shift 2
+      ;;
+    --no-session-persistence|--exclude-dynamic-system-prompt-sections)
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+stdin_prompt="$(cat)"
+printf '%s\n%s' "$print_prompt" "$stdin_prompt" > "{prompt_log}"
+case "$print_prompt" in
+  *"Clarion's local Claude Code LLM provider"*) ;;
+  *) echo "missing Claude print prompt" >&2; exit 41 ;;
+esac
+case "$stdin_prompt" in
+  *"Prompt contract: clarion-agent-provider-v1"*"Do not inspect additional files"*"Source excerpt:"*) ;;
+  *) echo "missing Clarion agent prompt contract" >&2; exit 42 ;;
+esac
+case "$schema" in
+  *'"purpose"'*'"behavior"'*) ;;
+  *) echo "schema missing summary fields" >&2; exit 43 ;;
+esac
+printf '%s\n' '{{"type":"result","subtype":"success","structured_output":{{"purpose":"via claude serve","behavior":"served through fake Claude CLI","relationships":"","risks":""}},"usage":{{"input_tokens":33,"cached_input_tokens":12,"output_tokens":8,"total_tokens":41}},"total_cost_usd":0.0}}'
+"#,
+            prompt_log = prompt_log.display()
+        ),
+    )
+    .expect("write fake claude");
+    make_executable(&fake_claude);
+    write_provider_config(
+        dir.path(),
+        "claude_cli",
+        r#"
+  claude_cli:
+    executable: "__EXECUTABLE__"
+    model: null
+    permission_mode: plan
+    tools: []
+    timeout_seconds: 5
+    max_turns: 2
+    no_session_persistence: true
+    exclude_dynamic_system_prompt_sections: true
+"#,
+        &fake_claude,
+    );
+
+    let envelope = call_summary_through_serve(dir.path());
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["cache"]["hit"], false);
+    assert_eq!(envelope["result"]["summary"]["purpose"], "via claude serve");
+    assert_eq!(envelope["result"]["usage"]["tokens_cached_input"], 12);
+    assert_eq!(envelope["stats_delta"]["summary_tokens_cached_input"], 12);
+    assert!(
+        fs::read_to_string(prompt_log)
+            .expect("read Claude prompt log")
+            .contains("Clarion's local Claude Code LLM provider")
+    );
+}
+
+fn make_executable(path: &Path) {
+    let mut permissions = fs::metadata(path).expect("metadata").permissions();
+    permissions.set_mode(0o755);
+    fs::set_permissions(path, permissions).expect("chmod executable");
+}
+
+fn seed_summary_entity(project_root: &Path) {
+    let source = "def entry():\n    return 1\n";
+    let source_path = project_root.join("demo.py");
+    fs::write(&source_path, source).expect("write source");
+    let content_hash = line_range_content_hash(source, 1, 2);
+    let db_path = project_root.join(".clarion/clarion.db");
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:function:demo.entry', 'python', 'function',
+            'python:function:demo.entry', 'entry', ?1,
+            1, 2, '{}', ?2,
+            '2026-05-17T00:00:00.000Z', '2026-05-17T00:00:00.000Z'
+         )",
+        params![source_path.display().to_string(), content_hash],
+    )
+    .expect("insert summary entity");
+}
+
+fn line_range_content_hash(source: &str, start_line: usize, end_line: usize) -> String {
+    let lines = source.lines().collect::<Vec<_>>();
+    let start = start_line.saturating_sub(1);
+    let end = end_line.min(lines.len());
+    blake3::hash(lines[start..end].join("\n").as_bytes())
+        .to_hex()
+        .to_string()
+}
+
+fn write_provider_config(
+    project_root: &Path,
+    provider: &str,
+    provider_block: &str,
+    executable: &Path,
+) {
+    let executable_yaml =
+        serde_json::to_string(&executable.display().to_string()).expect("quote executable path");
+    let provider_block = provider_block
+        .trim_start_matches('\n')
+        .replace("\"__EXECUTABLE__\"", &executable_yaml);
+    fs::write(
+        project_root.join("clarion.yaml"),
+        format!(
+            concat!(
+                "version: 1\n",
+                "llm:\n",
+                "  enabled: true\n",
+                "  provider: {provider}\n",
+                "  allow_live_provider: true\n",
+                "{provider_block}",
+                "  model_id: {provider}-test\n",
+                "  session_token_ceiling: 1000000\n",
+                "  max_inferred_edges_per_caller: 8\n",
+                "  cache_max_age_days: 180\n",
+            ),
+            provider = provider,
+            provider_block = provider_block,
+        ),
+    )
+    .expect("write provider config");
+}
+
+fn call_summary_through_serve(project_root: &Path) -> Value {
+    let mut child = StdCommand::new(assert_cmd::cargo::cargo_bin("clarion"))
+        .args(["serve", "--path"])
+        .arg(project_root)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn clarion serve");
+    {
+        let mut stdin = child.stdin.take().expect("child stdin");
+        write_frame(
+            &mut stdin,
+            &Frame {
+                body: serde_json::to_vec(&serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": "summary",
+                    "method": "tools/call",
+                    "params": {
+                        "name": "summary",
+                        "arguments": {"id": "python:function:demo.entry"}
+                    }
+                }))
+                .expect("serialize request"),
+            },
         )
-        .expect("read touched cache row");
-    assert_ne!(touched, "old-touch");
+        .expect("write summary frame");
+        stdin.flush().expect("flush summary frame");
+    }
+
+    let output = child.wait_with_output().expect("wait for clarion serve");
+    let config_debug = fs::read_to_string(project_root.join("clarion.yaml"))
+        .unwrap_or_else(|err| format!("failed to read clarion.yaml: {err}"));
+    assert!(
+        output.status.success(),
+        "serve failed: {}\nclarion.yaml:\n{}",
+        String::from_utf8_lossy(&output.stderr),
+        config_debug
+    );
+    let mut reader = std::io::BufReader::new(std::io::Cursor::new(output.stdout));
+    let frame =
+        read_frame(&mut reader, ContentLengthCeiling::new(usize::MAX)).expect("read response");
+    let response: serde_json::Value =
+        serde_json::from_slice(&frame.body).expect("response body is json");
+    let tool_text = response["result"]["content"][0]["text"]
+        .as_str()
+        .expect("tool text");
+    serde_json::from_str(tool_text).expect("tool envelope")
+}
+
+fn load_contract_fixture(fixture_name: &str, source: &str) -> Value {
+    let fixture: Value = serde_json::from_str(source).expect("parse contract fixture");
+    assert!(
+        fixture.get("_meta").and_then(Value::as_object).is_some(),
+        "{fixture_name} missing top-level _meta object"
+    );
+    for field in [
+        "contract",
+        "stability",
+        "authority",
+        "verification",
+        "updated",
+    ] {
+        assert!(
+            fixture.pointer(&format!("/_meta/{field}")).is_some(),
+            "{fixture_name} missing required _meta.{field}"
+        );
+    }
+    assert!(
+        fixture
+            .pointer("/shape_decl/shapes")
+            .and_then(Value::as_object)
+            .is_some(),
+        "{fixture_name} missing top-level shape_decl.shapes object"
+    );
+    let examples = fixture
+        .get("examples")
+        .and_then(Value::as_array)
+        .unwrap_or_else(|| panic!("{fixture_name} missing top-level examples array"));
+    assert!(
+        !examples.is_empty(),
+        "{fixture_name} must declare at least one example"
+    );
+    fixture
+}
+
+fn fixture_example_body<'a>(fixture: &'a Value, example_name: &str) -> &'a Value {
+    let examples = fixture
+        .get("examples")
+        .and_then(Value::as_array)
+        .expect("examples array");
+    examples
+        .iter()
+        .find(|example| example.get("name").and_then(Value::as_str) == Some(example_name))
+        .and_then(|example| example.pointer("/response/body"))
+        .unwrap_or_else(|| panic!("missing fixture example body {example_name}"))
+}
+
+fn validate_fixture_examples(bind: &str, fixture: &Value, fixture_name: &str) {
+    let shapes = fixture
+        .pointer("/shape_decl/shapes")
+        .and_then(Value::as_object)
+        .expect("shape_decl.shapes object");
+    let examples = fixture
+        .get("examples")
+        .and_then(Value::as_array)
+        .expect("examples array");
+    for example in examples {
+        let example_name = example
+            .get("name")
+            .and_then(Value::as_str)
+            .expect("example name");
+        let method = example
+            .pointer("/request/method")
+            .and_then(Value::as_str)
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing request.method"));
+        let path = example
+            .pointer("/request/path")
+            .and_then(Value::as_str)
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing request.path"));
+        let expected_status = example
+            .pointer("/response/status")
+            .and_then(Value::as_u64)
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing response.status"));
+        let expected_body = example
+            .pointer("/response/body")
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing response.body"));
+        let shape_name = example
+            .pointer("/response/shape")
+            .and_then(Value::as_str)
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing response.shape"));
+
+        let response = match method {
+            "GET" => wait_for_http_response(bind, path).unwrap_or_else(|err| {
+                panic!("{fixture_name}:{example_name} HTTP request failed: {err}")
+            }),
+            "POST" => {
+                let body = example
+                    .pointer("/request/body")
+                    .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing request.body"))
+                    .to_string();
+                wait_for_http_post_json(bind, path, &body, &[]).unwrap_or_else(|err| {
+                    panic!("{fixture_name}:{example_name} HTTP POST request failed: {err}")
+                })
+            }
+            other => panic!("{fixture_name}:{example_name} unsupported method {other}"),
+        };
+
+        assert_eq!(
+            u64::from(response.status_code),
+            expected_status,
+            "{fixture_name}:{example_name} status mismatch"
+        );
+        let shape = shapes
+            .get(shape_name)
+            .and_then(Value::as_object)
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing shape {shape_name}"));
+        assert_status_allowed(shape, response.status_code, fixture_name, example_name);
+        assert_body_matches_shape(
+            shape,
+            &response.body,
+            fixture_name,
+            example_name,
+            shape_name,
+        );
+        assert_normative_example_fields(
+            &response.body,
+            expected_body,
+            shape_name,
+            fixture_name,
+            example_name,
+        );
+    }
+}
+
+fn assert_normative_example_fields(
+    actual: &Value,
+    expected: &Value,
+    shape_name: &str,
+    fixture_name: &str,
+    example_name: &str,
+) {
+    if shape_name == "error_envelope" {
+        assert_eq!(
+            actual.get("code"),
+            expected.get("code"),
+            "{fixture_name}:{example_name} error code mismatch"
+        );
+        return;
+    }
+    assert_eq!(
+        actual, expected,
+        "{fixture_name}:{example_name} body mismatch"
+    );
+}
+
+fn assert_status_allowed(
+    shape: &serde_json::Map<String, Value>,
+    status_code: u16,
+    fixture_name: &str,
+    example_name: &str,
+) {
+    if let Some(status) = shape.get("status").and_then(Value::as_u64) {
+        assert_eq!(
+            status,
+            u64::from(status_code),
+            "{fixture_name}:{example_name} status is not allowed by shape"
+        );
+        return;
+    }
+    let allowed = shape
+        .get("status_any")
+        .and_then(Value::as_array)
+        .unwrap_or_else(|| panic!("{fixture_name}:{example_name} shape missing status/status_any"));
+    assert!(
+        allowed
+            .iter()
+            .any(|candidate| candidate.as_u64() == Some(u64::from(status_code))),
+        "{fixture_name}:{example_name} status {status_code} is not in status_any {allowed:?}"
+    );
+}
+
+fn assert_body_matches_shape(
+    shape: &serde_json::Map<String, Value>,
+    body: &Value,
+    fixture_name: &str,
+    example_name: &str,
+    shape_name: &str,
+) {
+    let body = body
+        .as_object()
+        .unwrap_or_else(|| panic!("{fixture_name}:{example_name} body is not an object"));
+    let required_fields = shape
+        .get("required_fields")
+        .and_then(Value::as_object)
+        .unwrap_or_else(|| {
+            panic!("{fixture_name}:{example_name} shape {shape_name} missing required_fields")
+        });
+    for (field, field_decl) in required_fields {
+        let value = body
+            .get(field)
+            .unwrap_or_else(|| panic!("{fixture_name}:{example_name} missing field {field}"));
+        assert_value_matches_decl(value, field_decl, fixture_name, example_name, field);
+    }
+    if let Some(forbidden_fields) = shape.get("forbidden_fields").and_then(Value::as_array) {
+        for field in forbidden_fields {
+            let field = field.as_str().unwrap_or_else(|| {
+                panic!("{fixture_name}:{example_name} forbidden field entry is not a string")
+            });
+            assert!(
+                !body.contains_key(field),
+                "{fixture_name}:{example_name} field {field} is forbidden by {shape_name}"
+            );
+        }
+    }
+    let allow_extra_fields = shape
+        .get("allow_extra_fields")
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    if !allow_extra_fields {
+        for field in body.keys() {
+            assert!(
+                required_fields.contains_key(field),
+                "{fixture_name}:{example_name} unexpected field {field}"
+            );
+        }
+    }
+}
+
+fn assert_value_matches_decl(
+    value: &Value,
+    field_decl: &Value,
+    fixture_name: &str,
+    example_name: &str,
+    field: &str,
+) {
+    if let Some(expected) = field_decl.get("const") {
+        assert_eq!(
+            value, expected,
+            "{fixture_name}:{example_name} field {field} const mismatch"
+        );
+    }
+    if let Some(allowed) = field_decl.get("enum").and_then(Value::as_array) {
+        assert!(
+            allowed.iter().any(|candidate| candidate == value),
+            "{fixture_name}:{example_name} field {field} value {value:?} not in {allowed:?}"
+        );
+    }
+    let type_name = field_decl
+        .get("type")
+        .and_then(Value::as_str)
+        .unwrap_or_else(|| panic!("{fixture_name}:{example_name} field {field} missing type"));
+    match type_name {
+        "boolean" => {
+            assert!(
+                value.as_bool().is_some(),
+                "{fixture_name}:{example_name} field {field} is not a boolean"
+            );
+        }
+        "integer" => {
+            assert!(
+                value.as_i64().is_some() || value.as_u64().is_some(),
+                "{fixture_name}:{example_name} field {field} is not an integer"
+            );
+        }
+        "array" => {
+            assert!(
+                value.as_array().is_some(),
+                "{fixture_name}:{example_name} field {field} is not an array"
+            );
+        }
+        "non_empty_string" => {
+            let value = value.as_str().unwrap_or_else(|| {
+                panic!("{fixture_name}:{example_name} field {field} is not a string")
+            });
+            assert!(
+                !value.is_empty(),
+                "{fixture_name}:{example_name} field {field} is empty"
+            );
+        }
+        "uuid" => {
+            let value = value.as_str().unwrap_or_else(|| {
+                panic!("{fixture_name}:{example_name} field {field} is not a string")
+            });
+            Uuid::parse_str(value)
+                .unwrap_or_else(|err| panic!("{fixture_name}:{example_name} invalid UUID: {err}"));
+        }
+        "adr003_file_entity_id" => {
+            let value = value.as_str().unwrap_or_else(|| {
+                panic!("{fixture_name}:{example_name} field {field} is not a string")
+            });
+            assert!(
+                value
+                    .strip_prefix("core:file:")
+                    .is_some_and(|qualified_name| {
+                        !qualified_name.is_empty()
+                            && !qualified_name.contains('@')
+                            && !qualified_name.contains('\\')
+                    }),
+                "{fixture_name}:{example_name} field {field} is not an ADR-003 file ID"
+            );
+        }
+        "project_relative_path" => {
+            let value = value.as_str().unwrap_or_else(|| {
+                panic!("{fixture_name}:{example_name} field {field} is not a string")
+            });
+            assert!(
+                !value.is_empty()
+                    && !value.starts_with('/')
+                    && !value.starts_with("./")
+                    && !value.contains('\\'),
+                "{fixture_name}:{example_name} field {field} is not a project-relative path"
+            );
+        }
+        other => panic!("{fixture_name}:{example_name} unknown field type {other} for {field}"),
+    }
+}
+
+fn seed_file_entity(project_root: &Path) -> (String, String, String) {
+    let source_path = project_root.join("demo.py");
+    fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let canonical_path = source_path
+        .canonicalize()
+        .expect("canonical source path")
+        .display()
+        .to_string();
+    let content_hash = "hash-demo-file".to_owned();
+    let file_id = "core:file:demo.py".to_owned();
+    let db_path = project_root.join(".clarion/clarion.db");
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            ?1, 'core', 'file', 'demo.py', 'demo.py', ?2,
+            1, 2, '{}', ?3,
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![file_id, canonical_path, content_hash],
+    )
+    .expect("insert file entity");
+    (file_id, content_hash, "demo.py".to_owned())
+}
+
+fn seed_custom_language_file_entity(project_root: &Path) {
+    let source_path = project_root.join("demo.custom");
+    fs::write(&source_path, "custom source\n").expect("write custom source");
+    let canonical_path = source_path
+        .canonicalize()
+        .expect("canonical source path")
+        .display()
+        .to_string();
+    let db_path = project_root.join(".clarion/clarion.db");
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'core:file:demo.custom', 'core', 'file', 'demo.custom', 'demo.custom', ?1,
+            1, 1, '{\"language\":\"manifestlang\"}', 'hash-demo-custom',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical_path],
+    )
+    .expect("insert custom language file entity");
+}
+
+fn seed_briefing_blocked_file_entity(project_root: &Path) {
+    let source_path = project_root.join("blocked.py");
+    fs::write(&source_path, "secret = \"redacted\"\n").expect("write blocked source");
+    let canonical_path = source_path
+        .canonicalize()
+        .expect("canonical blocked path")
+        .display()
+        .to_string();
+    let db_path = project_root.join(".clarion/clarion.db");
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'core:file:blocked.py', 'core', 'file',
+            'blocked.py', 'blocked.py', ?1,
+            1, 2,
+            '{\"briefing_blocked\":\"pre-ingest secret scan flagged this file\"}',
+            'hash-blocked',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical_path],
+    )
+    .expect("insert briefing-blocked file entity");
+}
+
+fn seed_storage_failure_file_entity(project_root: &Path) {
+    let source_path = project_root.join("missing-on-disk.py");
+    fs::write(&source_path, "def missing():\n    return 1\n").expect("write source");
+    let canonical_path = source_path
+        .canonicalize()
+        .expect("canonical source path")
+        .display()
+        .to_string();
+    let db_path = project_root.join(".clarion/clarion.db");
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, created_at, updated_at
+         ) VALUES (
+            'core:file:missing-on-disk.py', 'core', 'file',
+            'missing-on-disk.py', 'missing-on-disk.py', ?1,
+            1, 2, '{}',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical_path],
+    )
+    .expect("insert file entity without cached hash");
+    drop(conn);
+    fs::remove_file(&source_path).expect("remove cataloged file to force storage failure");
+}
+
+fn free_loopback_bind() -> String {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind free loopback port");
+    listener.local_addr().expect("local addr").to_string()
+}
+
+fn write_http_config(project_root: &Path, bind: &str) {
+    fs::write(
+        project_root.join("clarion.yaml"),
+        format!("version: 1\nserve:\n  http:\n    enabled: true\n    bind: \"{bind}\"\n"),
+    )
+    .expect("write HTTP serve config");
+}
+
+fn write_http_config_with_token_env(project_root: &Path, bind: &str, token_env: &str) {
+    fs::write(
+        project_root.join("clarion.yaml"),
+        format!(
+            "version: 1\nserve:\n  http:\n    enabled: true\n    bind: \"{bind}\"\n    token_env: \"{token_env}\"\n"
+        ),
+    )
+    .expect("write HTTP serve config with token_env");
+}
+
+fn write_http_config_with_identity_token_env(project_root: &Path, bind: &str, token_env: &str) {
+    fs::write(
+        project_root.join("clarion.yaml"),
+        format!(
+            "version: 1\nserve:\n  http:\n    enabled: true\n    bind: \"{bind}\"\n    identity_token_env: \"{token_env}\"\n"
+        ),
+    )
+    .expect("write HTTP serve config with identity_token_env");
+}
+
+fn hmac_component_header(secret: &str, method: &str, path_and_query: &str, body: &[u8]) -> String {
+    format!(
+        "clarion:{}",
+        hmac_sha256_hex(
+            secret.as_bytes(),
+            canonical_hmac_message(method, path_and_query, body).as_bytes()
+        )
+    )
+}
+
+fn canonical_hmac_message(method: &str, path_and_query: &str, body: &[u8]) -> String {
+    format!(
+        "{}\n{}\n{}",
+        method,
+        path_and_query,
+        hex_lower(&Sha256::digest(body))
+    )
+}
+
+fn hmac_sha256_hex(secret: &[u8], message: &[u8]) -> String {
+    const BLOCK_SIZE: usize = 64;
+    let mut key = [0_u8; BLOCK_SIZE];
+    if secret.len() > BLOCK_SIZE {
+        key[..32].copy_from_slice(&Sha256::digest(secret));
+    } else {
+        key[..secret.len()].copy_from_slice(secret);
+    }
+    let mut ipad = [0x36_u8; BLOCK_SIZE];
+    let mut opad = [0x5c_u8; BLOCK_SIZE];
+    for index in 0..BLOCK_SIZE {
+        ipad[index] ^= key[index];
+        opad[index] ^= key[index];
+    }
+    let mut inner = Sha256::new();
+    inner.update(ipad);
+    inner.update(message);
+    let inner = inner.finalize();
+    let mut outer = Sha256::new();
+    outer.update(opad);
+    outer.update(inner);
+    hex_lower(&outer.finalize())
+}
+
+fn hex_lower(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for byte in bytes {
+        out.push(HEX[(byte >> 4) as usize] as char);
+        out.push(HEX[(byte & 0x0f) as usize] as char);
+    }
+    out
+}
+
+struct ServeChild {
+    child: Option<Child>,
+}
+
+impl ServeChild {
+    fn new(child: Child) -> Self {
+        Self { child: Some(child) }
+    }
+
+    fn stop(&mut self) {
+        if let Some(mut child) = self.child.take() {
+            stop_child(&mut child);
+        }
+    }
+
+    fn wait_with_output(mut self) -> std::io::Result<std::process::Output> {
+        self.child
+            .take()
+            .expect("serve child was already stopped")
+            .wait_with_output()
+    }
+}
+
+impl std::ops::Deref for ServeChild {
+    type Target = Child;
+
+    fn deref(&self) -> &Self::Target {
+        self.child.as_ref().expect("serve child was stopped")
+    }
+}
+
+impl std::ops::DerefMut for ServeChild {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        self.child.as_mut().expect("serve child was stopped")
+    }
+}
+
+impl Drop for ServeChild {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+fn spawn_serve(project_root: &Path) -> ServeChild {
+    spawn_serve_with_env(project_root, &[])
+}
+
+fn spawn_serve_with_env(project_root: &Path, env: &[(&str, &str)]) -> ServeChild {
+    let mut command = StdCommand::new(assert_cmd::cargo::cargo_bin("clarion"));
+    command
+        .args(["serve", "--path"])
+        .arg(project_root)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    for (key, value) in env {
+        command.env(key, value);
+    }
+    ServeChild::new(command.spawn().expect("spawn clarion serve"))
+}
+
+fn stop_serve(child: &mut ServeChild) {
+    child.stop();
+}
+
+fn stop_child(child: &mut Child) {
+    drop(child.stdin.take());
+    if let Ok(Some(_)) = child.try_wait() {
+        return;
+    }
+    let _ = child.kill();
+    let _ = child.wait();
+}
+
+fn wait_for_child_exit(mut child: ServeChild, timeout: Duration) -> Option<std::process::Output> {
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        if child.try_wait().expect("poll child").is_some() {
+            return Some(child.wait_with_output().expect("collect child output"));
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    child.stop();
+    None
+}
+
+fn wait_for_http_json(bind: &str, path: &str) -> Result<Value, String> {
+    let response = wait_for_http_response(bind, path)?;
+    if response.status_code != 200 {
+        return Err(format!(
+            "unexpected HTTP status {}; body: {}",
+            response.status_code, response.body
+        ));
+    }
+    Ok(response.body)
+}
+
+fn wait_for_http_response(bind: &str, path: &str) -> Result<HttpJsonResponse, String> {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    let mut last_error = String::new();
+    while Instant::now() < deadline {
+        match http_get_response(bind, path) {
+            Ok(response) => return Ok(response),
+            Err(err) => last_error = err,
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    Err(last_error)
+}
+
+fn wait_for_http_raw_response(
+    bind: &str,
+    path: &str,
+    headers: &[(&str, &str)],
+) -> Result<HttpRawResponse, String> {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    let mut last_error = String::new();
+    while Instant::now() < deadline {
+        match http_raw_response(bind, path, headers) {
+            Ok(response) => return Ok(response),
+            Err(err) => last_error = err,
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    Err(last_error)
+}
+
+fn wait_for_http_post_json(
+    bind: &str,
+    path: &str,
+    body: &str,
+    headers: &[(&str, &str)],
+) -> Result<HttpJsonResponse, String> {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    let mut last_error = String::new();
+    while Instant::now() < deadline {
+        match http_post_json(bind, path, body, headers) {
+            Ok(response) => return Ok(response),
+            Err(err) => last_error = err,
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    Err(last_error)
+}
+
+fn http_post_json(
+    bind: &str,
+    path: &str,
+    body: &str,
+    request_headers: &[(&str, &str)],
+) -> Result<HttpJsonResponse, String> {
+    let addr = bind
+        .parse()
+        .map_err(|err| format!("parse bind address {bind}: {err}"))?;
+    let mut stream = TcpStream::connect_timeout(&addr, Duration::from_millis(100))
+        .map_err(|err| format!("connect to {bind}: {err}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(2)))
+        .map_err(|err| format!("set read timeout: {err}"))?;
+    write!(
+        stream,
+        "POST {path} HTTP/1.1\r\nHost: {bind}\r\nContent-Type: application/json\r\nContent-Length: {}\r\n",
+        body.len()
+    )
+    .map_err(|err| format!("write request head: {err}"))?;
+    for (name, value) in request_headers {
+        write!(stream, "{name}: {value}\r\n")
+            .map_err(|err| format!("write request header {name}: {err}"))?;
+    }
+    write!(stream, "Connection: close\r\n\r\n")
+        .map_err(|err| format!("write request terminator: {err}"))?;
+    stream
+        .write_all(body.as_bytes())
+        .map_err(|err| format!("write request body: {err}"))?;
+    let mut reader = std::io::BufReader::new(stream);
+    let mut status_line = String::new();
+    reader
+        .read_line(&mut status_line)
+        .map_err(|err| format!("read status line: {err}"))?;
+    let status_code = status_line
+        .split_whitespace()
+        .nth(1)
+        .ok_or_else(|| format!("malformed HTTP status line: {status_line}"))?
+        .parse::<u16>()
+        .map_err(|err| format!("parse HTTP status from {status_line:?}: {err}"))?;
+    let mut content_length = None;
+    let mut header = String::new();
+    loop {
+        header.clear();
+        reader
+            .read_line(&mut header)
+            .map_err(|err| format!("read header: {err}"))?;
+        if header == "\r\n" || header == "\n" || header.is_empty() {
+            break;
+        }
+        if let Some((name, value)) = header.split_once(':')
+            && name.eq_ignore_ascii_case("content-length")
+        {
+            content_length = Some(
+                value
+                    .trim()
+                    .parse::<usize>()
+                    .map_err(|err| format!("parse content-length from {header:?}: {err}"))?,
+            );
+        }
+    }
+    let mut body = String::new();
+    if let Some(content_length) = content_length {
+        let mut bytes = vec![0_u8; content_length];
+        reader
+            .read_exact(&mut bytes)
+            .map_err(|err| format!("read response body: {err}"))?;
+        body = String::from_utf8(bytes).map_err(|err| format!("response body is utf8: {err}"))?;
+    } else {
+        reader
+            .read_to_string(&mut body)
+            .map_err(|err| format!("read response body: {err}"))?;
+    }
+    let body =
+        serde_json::from_str(&body).map_err(|err| format!("parse json body {body:?}: {err}"))?;
+    Ok(HttpJsonResponse { status_code, body })
+}
+
+fn wait_for_http_get_with_body_status(
+    bind: &str,
+    path: &str,
+    body_len: usize,
+) -> Result<u16, String> {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    let body = vec![b'x'; body_len];
+    let mut last_error = String::new();
+    while Instant::now() < deadline {
+        match http_get_with_body_status(bind, path, &body) {
+            Ok(status_code) => return Ok(status_code),
+            Err(err) => last_error = err,
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    Err(last_error)
+}
+
+fn http_get_with_body_status(bind: &str, path: &str, body: &[u8]) -> Result<u16, String> {
+    let addr = bind
+        .parse()
+        .map_err(|err| format!("parse bind address {bind}: {err}"))?;
+    let mut stream = TcpStream::connect_timeout(&addr, Duration::from_millis(100))
+        .map_err(|err| format!("connect to {bind}: {err}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(2)))
+        .map_err(|err| format!("set read timeout: {err}"))?;
+    write!(
+        stream,
+        "GET {path} HTTP/1.1\r\nHost: {bind}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+        body.len()
+    )
+    .map_err(|err| format!("write request head: {err}"))?;
+    stream
+        .write_all(body)
+        .map_err(|err| format!("write request body: {err}"))?;
+    let mut reader = std::io::BufReader::new(stream);
+    let mut status_line = String::new();
+    reader
+        .read_line(&mut status_line)
+        .map_err(|err| format!("read status line: {err}"))?;
+    status_line
+        .split_whitespace()
+        .nth(1)
+        .ok_or_else(|| format!("malformed HTTP status line: {status_line}"))?
+        .parse::<u16>()
+        .map_err(|err| format!("parse HTTP status from {status_line:?}: {err}"))
+}
+
+fn http_raw_response(
+    bind: &str,
+    path: &str,
+    request_headers: &[(&str, &str)],
+) -> Result<HttpRawResponse, String> {
+    let addr = bind
+        .parse()
+        .map_err(|err| format!("parse bind address {bind}: {err}"))?;
+    let mut stream = TcpStream::connect_timeout(&addr, Duration::from_millis(100))
+        .map_err(|err| format!("connect to {bind}: {err}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(2)))
+        .map_err(|err| format!("set read timeout: {err}"))?;
+    write!(stream, "GET {path} HTTP/1.1\r\nHost: {bind}\r\n")
+        .map_err(|err| format!("write request line: {err}"))?;
+    for (name, value) in request_headers {
+        write!(stream, "{name}: {value}\r\n")
+            .map_err(|err| format!("write request header {name}: {err}"))?;
+    }
+    write!(stream, "Connection: close\r\n\r\n")
+        .map_err(|err| format!("write request terminator: {err}"))?;
+
+    let mut reader = std::io::BufReader::new(stream);
+    let mut status_line = String::new();
+    reader
+        .read_line(&mut status_line)
+        .map_err(|err| format!("read status line: {err}"))?;
+    let status_code = status_line
+        .split_whitespace()
+        .nth(1)
+        .ok_or_else(|| format!("malformed HTTP status line: {status_line}"))?
+        .parse::<u16>()
+        .map_err(|err| format!("parse HTTP status from {status_line:?}: {err}"))?;
+    let mut content_length = None;
+    let mut response_headers = Vec::new();
+    let mut header = String::new();
+    loop {
+        header.clear();
+        reader
+            .read_line(&mut header)
+            .map_err(|err| format!("read header: {err}"))?;
+        if header == "\r\n" || header == "\n" || header.is_empty() {
+            break;
+        }
+        if let Some((name, value)) = header.split_once(':') {
+            let name = name.trim().to_owned();
+            let value = value.trim().to_owned();
+            if name.eq_ignore_ascii_case("content-length") {
+                content_length = Some(
+                    value
+                        .parse::<usize>()
+                        .map_err(|err| format!("parse content-length from {header:?}: {err}"))?,
+                );
+            }
+            response_headers.push((name, value));
+        }
+    }
+    let mut body = String::new();
+    if let Some(content_length) = content_length {
+        let mut bytes = vec![0_u8; content_length];
+        reader
+            .read_exact(&mut bytes)
+            .map_err(|err| format!("read response body: {err}"))?;
+        body = String::from_utf8(bytes).map_err(|err| format!("response body is utf8: {err}"))?;
+    } else {
+        reader
+            .read_to_string(&mut body)
+            .map_err(|err| format!("read response body: {err}"))?;
+    }
+    Ok(HttpRawResponse {
+        status_code,
+        headers: response_headers,
+        body,
+    })
+}
+
+fn http_get_response(bind: &str, path: &str) -> Result<HttpJsonResponse, String> {
+    let addr = bind
+        .parse()
+        .map_err(|err| format!("parse bind address {bind}: {err}"))?;
+    let mut stream = TcpStream::connect_timeout(&addr, Duration::from_millis(100))
+        .map_err(|err| format!("connect to {bind}: {err}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(2)))
+        .map_err(|err| format!("set read timeout: {err}"))?;
+    write!(
+        stream,
+        "GET {path} HTTP/1.1\r\nHost: {bind}\r\nConnection: close\r\n\r\n"
+    )
+    .map_err(|err| format!("write request: {err}"))?;
+    let mut reader = std::io::BufReader::new(stream);
+    let mut status_line = String::new();
+    reader
+        .read_line(&mut status_line)
+        .map_err(|err| format!("read status line: {err}"))?;
+    let status_code = status_line
+        .split_whitespace()
+        .nth(1)
+        .ok_or_else(|| format!("malformed HTTP status line: {status_line}"))?
+        .parse::<u16>()
+        .map_err(|err| format!("parse HTTP status from {status_line:?}: {err}"))?;
+    let mut content_length = None;
+    let mut header = String::new();
+    loop {
+        header.clear();
+        reader
+            .read_line(&mut header)
+            .map_err(|err| format!("read header: {err}"))?;
+        if header == "\r\n" || header == "\n" || header.is_empty() {
+            break;
+        }
+        if let Some((name, value)) = header.split_once(':')
+            && name.eq_ignore_ascii_case("content-length")
+        {
+            content_length = Some(
+                value
+                    .trim()
+                    .parse::<usize>()
+                    .map_err(|err| format!("parse content-length from {header:?}: {err}"))?,
+            );
+        }
+    }
+    let mut body = String::new();
+    if let Some(content_length) = content_length {
+        let mut bytes = vec![0_u8; content_length];
+        reader
+            .read_exact(&mut bytes)
+            .map_err(|err| format!("read response body: {err}"))?;
+        body = String::from_utf8(bytes).map_err(|err| format!("response body is utf8: {err}"))?;
+    } else {
+        reader
+            .read_to_string(&mut body)
+            .map_err(|err| format!("read response body: {err}"))?;
+    }
+    let body =
+        serde_json::from_str(&body).map_err(|err| format!("parse json body {body:?}: {err}"))?;
+    Ok(HttpJsonResponse { status_code, body })
 }
diff --git a/crates/clarion-cli/tests/skills.rs b/crates/clarion-cli/tests/skills.rs
new file mode 100644
index 00000000..d9e0397c
--- /dev/null
+++ b/crates/clarion-cli/tests/skills.rs
@@ -0,0 +1,149 @@
+//! `clarion install --skills/--hooks/--all` integration tests.
+
+use std::fs;
+
+use assert_cmd::Command;
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+#[test]
+fn install_skills_writes_pack_without_initialising_clarion_dir() {
+    let dir = tempfile::tempdir().unwrap();
+    clarion_bin()
+        .args(["install", "--skills", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    assert!(
+        dir.path()
+            .join(".claude/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "skill not installed under .claude"
+    );
+    assert!(
+        dir.path()
+            .join(".agents/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "skill not installed under .agents"
+    );
+    // --skills MUST NOT init .clarion/.
+    assert!(
+        !dir.path().join(".clarion").exists(),
+        "--skills should not create .clarion/"
+    );
+}
+
+#[test]
+fn install_skills_is_idempotent() {
+    let dir = tempfile::tempdir().unwrap();
+    for _ in 0..2 {
+        clarion_bin()
+            .args(["install", "--skills", "--path"])
+            .arg(dir.path())
+            .assert()
+            .success();
+    }
+    let body =
+        fs::read_to_string(dir.path().join(".claude/skills/clarion-workflow/SKILL.md")).unwrap();
+    assert!(body.contains("name: clarion-workflow"));
+}
+
+#[test]
+fn install_hooks_merges_session_start_without_clobbering() {
+    let dir = tempfile::tempdir().unwrap();
+    let claude = dir.path().join(".claude");
+    fs::create_dir_all(&claude).unwrap();
+    fs::write(
+        claude.join("settings.json"),
+        r#"{"model":"opus","hooks":{"Stop":[{"hooks":[{"type":"command","command":"echo bye"}]}]}}"#,
+    )
+    .unwrap();
+
+    clarion_bin()
+        .args(["install", "--hooks", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    let raw = fs::read_to_string(claude.join("settings.json")).unwrap();
+    let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap();
+    assert_eq!(parsed["model"], "opus");
+    assert_eq!(
+        parsed["hooks"]["Stop"][0]["hooks"][0]["command"],
+        "echo bye"
+    );
+    let cmds: Vec<String> = parsed["hooks"]["SessionStart"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .flat_map(|g| g["hooks"].as_array().unwrap())
+        .map(|h| h["command"].as_str().unwrap().to_string())
+        .collect();
+    assert!(
+        cmds.iter()
+            .any(|c| c.contains("clarion hook session-start"))
+    );
+    assert!(!dir.path().join(".clarion").exists());
+}
+
+#[test]
+fn install_all_does_init_skills_and_hooks() {
+    let dir = tempfile::tempdir().unwrap();
+    clarion_bin()
+        .args(["install", "--all", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    assert!(dir.path().join(".clarion/clarion.db").exists(), "no db");
+    assert!(
+        dir.path()
+            .join(".claude/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "no skill"
+    );
+    let raw = fs::read_to_string(dir.path().join(".claude/settings.json")).unwrap();
+    assert!(raw.contains("clarion hook session-start"), "no hook: {raw}");
+}
+
+#[test]
+fn install_all_is_rerunnable_and_preserves_index() {
+    let dir = tempfile::tempdir().unwrap();
+    // First --all: full setup.
+    clarion_bin()
+        .args(["install", "--all", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let db = dir.path().join(".clarion/clarion.db");
+    assert!(db.exists(), "first --all did not create db");
+    // Mark the db so we can prove the second run did NOT recreate it.
+    let before = std::fs::metadata(&db).unwrap().modified().unwrap();
+
+    // Second --all: must succeed (not bail), keep the index, re-apply skills/hooks.
+    clarion_bin()
+        .args(["install", "--all", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    assert!(db.exists(), "second --all destroyed the db");
+    let after = std::fs::metadata(&db).unwrap().modified().unwrap();
+    assert_eq!(
+        before, after,
+        "second --all recreated the db (index not preserved)"
+    );
+    assert!(
+        dir.path()
+            .join(".claude/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "skill missing after rerun"
+    );
+    let raw = std::fs::read_to_string(dir.path().join(".claude/settings.json")).unwrap();
+    assert!(
+        raw.contains("clarion hook session-start"),
+        "hook missing after rerun"
+    );
+}
diff --git a/crates/clarion-cli/tests/wp1_e2e.rs b/crates/clarion-cli/tests/wp1_e2e.rs
index 5633e1f7..b03451a6 100644
--- a/crates/clarion-cli/tests/wp1_e2e.rs
+++ b/crates/clarion-cli/tests/wp1_e2e.rs
@@ -52,7 +52,7 @@ fn wp1_walking_skeleton_end_to_end() {
             row.get(0)
         })
         .unwrap();
-    assert_eq!(migration_version, 1, "schema not on migration 1");
+    assert_eq!(migration_version, 2, "schema not on the latest migration");
 
     let runs_count: i64 = conn
         .query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))
diff --git a/crates/clarion-cli/tests/wp2_e2e.rs b/crates/clarion-cli/tests/wp2_e2e.rs
index 1b3fa1ad..de048c25 100644
--- a/crates/clarion-cli/tests/wp2_e2e.rs
+++ b/crates/clarion-cli/tests/wp2_e2e.rs
@@ -194,7 +194,7 @@ fn wp2_e2e_smoke_fixture_plugin_round_trip() {
         "run status must be 'completed'; got {run_status:?}"
     );
 
-    // Assert 3: stats JSON reports entities_inserted = 1.
+    // Assert 3: stats JSON reports the fixture entity plus the core file identity.
     let stats_raw: String = conn
         .query_row("SELECT stats FROM runs LIMIT 1", [], |row| row.get(0))
         .expect("query runs.stats");
@@ -202,24 +202,35 @@ fn wp2_e2e_smoke_fixture_plugin_round_trip() {
         serde_json::from_str(&stats_raw).expect("stats column must be valid JSON");
     assert_eq!(
         stats["entities_inserted"],
-        serde_json::Value::Number(1.into()),
-        "stats must report entities_inserted = 1; got {stats_raw:?}"
+        serde_json::Value::Number(2.into()),
+        "stats must report entities_inserted = 2; got {stats_raw:?}"
     );
 
-    // Assert 4: exactly one entity row.
+    // Assert 4: exactly one fixture entity and one core file identity row.
     let entity_count: i64 = conn
         .query_row("SELECT COUNT(*) FROM entities", [], |row| row.get(0))
         .expect("query entities count");
 
     assert_eq!(
-        entity_count, 1,
-        "expected exactly one entity row; got {entity_count}"
+        entity_count, 2,
+        "expected exactly two entity rows; got {entity_count}"
+    );
+    let file_entity_count: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE plugin_id = 'core' AND kind = 'file'",
+            [],
+            |row| row.get(0),
+        )
+        .expect("query core file entity count");
+    assert_eq!(
+        file_entity_count, 1,
+        "expected exactly one core file identity row; got {file_entity_count}"
     );
 
     // Asserts 5–8: the persisted row matches the fixture's declared emission.
     let (entity_id, entity_kind, entity_plugin_id, entity_name): (String, String, String, String) =
         conn.query_row(
-            "SELECT id, kind, plugin_id, name FROM entities LIMIT 1",
+            "SELECT id, kind, plugin_id, name FROM entities WHERE plugin_id = 'fixture'",
             [],
             |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),
         )
@@ -409,17 +420,34 @@ ontology_version = "0.1.0"
 
     // This is the behavioural assertion that matters: the fixture plugin's
     // entity is persisted even though `broken` crashed earlier in the run.
-    let entity_count: i64 = conn
-        .query_row("SELECT COUNT(*) FROM entities", [], |row| row.get(0))
-        .expect("query entities count");
+    let fixture_entity_count: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE plugin_id = 'fixture'",
+            [],
+            |row| row.get(0),
+        )
+        .expect("query fixture entities count");
+    assert_eq!(
+        fixture_entity_count, 1,
+        "fixture plugin's entity must still be persisted despite broken plugin's crash; got {fixture_entity_count}",
+    );
+    let file_entity_count: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE plugin_id = 'core' AND kind = 'file'",
+            [],
+            |row| row.get(0),
+        )
+        .expect("query core file entity count");
     assert_eq!(
-        entity_count, 1,
-        "fixture plugin's entity must still be persisted despite broken plugin's crash; got {entity_count}",
+        file_entity_count, 1,
+        "core file identity must be persisted for the surviving source file; got {file_entity_count}",
     );
     let entity_plugin_id: String = conn
-        .query_row("SELECT plugin_id FROM entities LIMIT 1", [], |row| {
-            row.get(0)
-        })
+        .query_row(
+            "SELECT plugin_id FROM entities WHERE plugin_id = 'fixture'",
+            [],
+            |row| row.get(0),
+        )
         .expect("query entity plugin_id");
     assert_eq!(
         entity_plugin_id, "fixture",
diff --git a/crates/clarion-core/Cargo.toml b/crates/clarion-core/Cargo.toml
index b1c4fa6c..1d128a94 100644
--- a/crates/clarion-core/Cargo.toml
+++ b/crates/clarion-core/Cargo.toml
@@ -13,10 +13,12 @@ workspace = true
 reqwest.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+tempfile.workspace = true
 thiserror.workspace = true
 toml.workspace = true
 tracing.workspace = true
 nix = { workspace = true }
+which = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }
diff --git a/crates/clarion-core/src/lib.rs b/crates/clarion-core/src/lib.rs
index 1cd67d1f..4294ae85 100644
--- a/crates/clarion-core/src/lib.rs
+++ b/crates/clarion-core/src/lib.rs
@@ -12,11 +12,12 @@ pub mod plugin;
 
 pub use entity_id::{EntityId, EntityIdError, entity_id};
 pub use llm_provider::{
-    CachingModel, INFERRED_CALLS_PROMPT_VERSION, InferredCallsPromptInput,
+    CachingModel, ClaudeCliProvider, ClaudeCliProviderConfig, CodexCliProvider,
+    CodexCliProviderConfig, INFERRED_CALLS_PROMPT_VERSION, InferredCallsPromptInput,
     LEAF_SUMMARY_PROMPT_TEMPLATE_ID, LeafSummaryPromptInput, LlmProvider, LlmProviderError,
     LlmPurpose, LlmRequest, LlmResponse, OpenRouterProvider, OpenRouterProviderConfig,
-    PromptTemplate, Recording, RecordingProvider, build_inferred_calls_prompt,
-    build_leaf_summary_prompt,
+    PromptTemplate, Recording, RecordingProvider, build_coding_agent_provider_prompt,
+    build_inferred_calls_prompt, build_leaf_summary_prompt,
 };
 pub use plugin::{
     // host (Task 6) — facade for callers that spawn/connect plugins
@@ -24,6 +25,7 @@ pub use plugin::{
     AcceptedEntity,
     AnalyzeFileOutcome,
     AnalyzeFileStats,
+    BriefingBlockReason,
     CapExceeded,
     // breaker (Task 7) — callers drive crash-loop accounting
     CrashLoopBreaker,
diff --git a/crates/clarion-core/src/llm_provider.rs b/crates/clarion-core/src/llm_provider.rs
index 2ddfdeb5..4f9b6b57 100644
--- a/crates/clarion-core/src/llm_provider.rs
+++ b/crates/clarion-core/src/llm_provider.rs
@@ -1,7 +1,12 @@
 //! LLM provider surface for WP6 and MCP on-demand tools.
 
+use std::fs;
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, ExitStatus, Stdio};
 use std::sync::Mutex;
-use std::time::Duration;
+use std::thread;
+use std::time::{Duration, Instant};
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
@@ -9,6 +14,8 @@ use thiserror::Error;
 
 pub const LEAF_SUMMARY_PROMPT_TEMPLATE_ID: &str = "leaf-v1";
 pub const INFERRED_CALLS_PROMPT_VERSION: &str = "inferred-calls-v1";
+const AGENT_PROVIDER_PROMPT_VERSION: &str = "clarion-agent-provider-v1";
+const CLAUDE_CLI_PRINT_PROMPT: &str = "You are Clarion's local Claude Code LLM provider. Read the Clarion provider prompt from stdin, complete that exact task, and return only the validated JSON object.";
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum LlmPurpose {
@@ -30,6 +37,8 @@ pub struct LlmResponse {
     pub model_id: String,
     pub output_json: String,
     pub input_tokens: u32,
+    #[serde(default)]
+    pub cached_input_tokens: u32,
     pub output_tokens: u32,
     pub total_tokens: u32,
     pub cost_usd: f64,
@@ -45,7 +54,7 @@ pub enum LlmProviderError {
     #[error("recording fixture has no response for prompt {prompt_id:?} on model {model_id:?}")]
     MissingRecording { prompt_id: String, model_id: String },
 
-    #[error("live OpenRouter provider requires explicit opt-in")]
+    #[error("live LLM provider requires explicit opt-in")]
     LiveProviderNotAllowed,
 
     #[error("live OpenRouter provider requires an API key")]
@@ -64,7 +73,13 @@ pub enum LlmProviderError {
         retry_after_seconds: Option<u64>,
     },
 
-    #[error("invalid live OpenRouter response: {message}")]
+    #[error("LLM CLI invocation failed: {message}")]
+    Cli { message: String, retryable: bool },
+
+    #[error("LLM CLI invocation timed out after {timeout_seconds} seconds")]
+    Timeout { timeout_seconds: u64 },
+
+    #[error("invalid live LLM provider response: {message}")]
     InvalidResponse { message: String, retryable: bool },
 }
 
@@ -76,7 +91,9 @@ impl LlmProviderError {
             }
             Self::Http { retryable, .. }
             | Self::Provider { retryable, .. }
+            | Self::Cli { retryable, .. }
             | Self::InvalidResponse { retryable, .. } => *retryable,
+            Self::Timeout { .. } => true,
         }
     }
 }
@@ -89,6 +106,32 @@ pub trait LlmProvider: Send + Sync {
     fn caching_model(&self) -> CachingModel;
 }
 
+pub fn build_coding_agent_provider_prompt(request: &LlmRequest) -> String {
+    format!(
+        "Prompt contract: {prompt_version}\n\
+         You are Clarion's coding-agent LLM provider for repository graph enrichment.\n\
+         Clarion has already selected the source excerpt, entity metadata, unresolved call sites, and candidate graph context needed for this task.\n\
+         Follow these rules exactly:\n\
+         1. Use only the evidence inside <clarion_request>. Do not inspect additional files, browse, run commands, edit files, or ask follow-up questions.\n\
+         2. Return exactly one JSON object matching the structured-output schema supplied by the caller. Do not wrap it in Markdown or prose.\n\
+         3. Reason privately if needed, but do not expose hidden reasoning. Put only concise evidence summaries in output fields that ask for rationale or relationships.\n\
+         4. When evidence is absent, prefer empty strings for optional prose fields and empty arrays for collection fields instead of guessing.\n\
+         5. Keep stable field names and JSON types; downstream Clarion storage parses the response mechanically.\n\
+         Task type: {task_type}\n\
+         Prompt template: {prompt_id}\n\
+         Task guidance:\n\
+         {task_guidance}\n\
+         <clarion_request>\n\
+         {prompt}\n\
+         </clarion_request>\n",
+        prompt_version = AGENT_PROVIDER_PROMPT_VERSION,
+        task_type = agent_task_type(&request.purpose),
+        prompt_id = request.prompt_id,
+        task_guidance = agent_task_guidance(&request.purpose),
+        prompt = request.prompt
+    )
+}
+
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Recording {
     pub request: LlmRequest,
@@ -272,6 +315,10 @@ impl LlmProvider for OpenRouterProvider {
             model_id: completion.model,
             output_json,
             input_tokens: usage.prompt,
+            cached_input_tokens: usage
+                .prompt_tokens_details
+                .as_ref()
+                .map_or(0, |details| details.cached_tokens),
             output_tokens: usage.completion,
             total_tokens: usage.total,
             cost_usd: usage.cost.unwrap_or(0.0),
@@ -294,6 +341,424 @@ impl LlmProvider for OpenRouterProvider {
     }
 }
 
+/// Resolve `executable` via `which::which` and return a typed CLI error if
+/// it is missing on PATH or at the configured absolute path. Called from each
+/// CLI provider's `from_config` so a typo in `clarion.yaml` aborts at
+/// `clarion serve` startup rather than exploding on the first MCP request.
+fn validate_cli_executable(label: &str, executable: &str) -> Result<(), LlmProviderError> {
+    which::which(executable).map_err(|err| LlmProviderError::Cli {
+        message: format!("{label} executable {executable:?} not resolvable: {err}"),
+        retryable: false,
+    })?;
+    Ok(())
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CodexCliProviderConfig {
+    pub executable: String,
+    pub project_root: PathBuf,
+    pub model_id: String,
+    pub model: Option<String>,
+    pub profile: Option<String>,
+    pub sandbox: String,
+    pub timeout_seconds: u64,
+}
+
+#[derive(Debug, Clone)]
+pub struct CodexCliProvider {
+    executable: String,
+    project_root: PathBuf,
+    model_id: String,
+    model: Option<String>,
+    profile: Option<String>,
+    sandbox: String,
+    timeout: Duration,
+    timeout_seconds: u64,
+}
+
+impl CodexCliProvider {
+    pub fn from_config(config: CodexCliProviderConfig) -> Result<Self, LlmProviderError> {
+        if config.executable.trim().is_empty() {
+            return Err(LlmProviderError::Cli {
+                message: "Codex CLI executable must not be blank".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.model_id.trim().is_empty() {
+            return Err(LlmProviderError::Cli {
+                message: "Codex CLI model_id must not be blank".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.sandbox.trim().is_empty() {
+            return Err(LlmProviderError::Cli {
+                message: "Codex CLI sandbox must not be blank".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.timeout_seconds == 0 {
+            return Err(LlmProviderError::Cli {
+                message: "Codex CLI timeout_seconds must be greater than zero".to_owned(),
+                retryable: false,
+            });
+        }
+        validate_cli_executable("Codex CLI", &config.executable)?;
+
+        Ok(Self {
+            executable: config.executable,
+            project_root: config.project_root,
+            model_id: config.model_id,
+            model: config.model.filter(|model| !model.trim().is_empty()),
+            profile: config.profile.filter(|profile| !profile.trim().is_empty()),
+            sandbox: config.sandbox,
+            timeout: Duration::from_secs(config.timeout_seconds),
+            timeout_seconds: config.timeout_seconds,
+        })
+    }
+
+    fn invoke_with_temp_files(
+        &self,
+        request: LlmRequest,
+        output_path: &Path,
+        schema_path: &Path,
+    ) -> Result<LlmResponse, LlmProviderError> {
+        let schema = codex_output_schema_for_purpose(&request.purpose);
+        let schema_json = serde_json::to_vec_pretty(&schema).map_err(|err| {
+            LlmProviderError::InvalidResponse {
+                message: format!("serialize Codex output schema: {err}"),
+                retryable: false,
+            }
+        })?;
+        fs::write(schema_path, schema_json).map_err(|err| LlmProviderError::Cli {
+            message: format!("write Codex output schema {}: {err}", schema_path.display()),
+            retryable: false,
+        })?;
+        let provider_prompt = build_coding_agent_provider_prompt(&request);
+
+        let mut command = Command::new(&self.executable);
+        command
+            .arg("exec")
+            .arg("--sandbox")
+            .arg(&self.sandbox)
+            .arg("-c")
+            .arg("approval_policy=\"never\"")
+            .arg("--json")
+            .arg("--cd")
+            .arg(&self.project_root)
+            .arg("--output-last-message")
+            .arg(output_path)
+            .arg("--output-schema")
+            .arg(schema_path);
+        if let Some(profile) = &self.profile {
+            command.arg("--profile").arg(profile);
+        }
+        if let Some(model) = &self.model {
+            command.arg("--model").arg(model);
+        }
+        command
+            .arg("-")
+            .current_dir(&self.project_root)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+
+        let mut child = command.spawn().map_err(|err| LlmProviderError::Cli {
+            message: format!("spawn Codex CLI {}: {err}", self.executable),
+            retryable: false,
+        })?;
+
+        let stdout_reader = take_reader(&mut child.stdout, "stdout")?;
+        let stderr_reader = take_reader(&mut child.stderr, "stderr")?;
+        if let Err(err) = write_child_stdin(&mut child, &provider_prompt) {
+            let _ = child.kill();
+            return Err(err);
+        }
+
+        let status = wait_for_child(&mut child, self.timeout, self.timeout_seconds)?;
+        let stdout = join_reader(stdout_reader, "stdout")?;
+        let stderr = join_reader(stderr_reader, "stderr")?;
+
+        if !status.success() {
+            return Err(LlmProviderError::Cli {
+                message: format!(
+                    "codex exec exited with {status}: {}",
+                    truncate_for_error(&String::from_utf8_lossy(&stderr))
+                ),
+                retryable: codex_status_retryable(status),
+            });
+        }
+
+        let output_json =
+            fs::read_to_string(output_path).map_err(|err| LlmProviderError::InvalidResponse {
+                message: format!(
+                    "read Codex output-last-message {}: {err}",
+                    output_path.display()
+                ),
+                retryable: true,
+            })?;
+        let output_json = output_json.trim().to_owned();
+        if output_json.is_empty() {
+            return Err(LlmProviderError::InvalidResponse {
+                message: "Codex output-last-message was empty".to_owned(),
+                retryable: true,
+            });
+        }
+        serde_json::from_str::<Value>(&output_json).map_err(|err| {
+            LlmProviderError::InvalidResponse {
+                message: format!("Codex output was not valid JSON: {err}"),
+                retryable: true,
+            }
+        })?;
+
+        let usage = parse_codex_jsonl_usage(&stdout);
+        let input_tokens = usage
+            .input_tokens
+            .unwrap_or_else(|| estimate_text_tokens(&provider_prompt));
+        let output_tokens = usage
+            .output_tokens
+            .unwrap_or_else(|| estimate_text_tokens(&output_json));
+        let total_tokens = usage
+            .total_tokens
+            .unwrap_or_else(|| input_tokens.saturating_add(output_tokens));
+        let cached_input_tokens = usage.cached_input_tokens.unwrap_or(0);
+
+        Ok(LlmResponse {
+            model_id: request.model_id,
+            output_json,
+            input_tokens,
+            cached_input_tokens,
+            output_tokens,
+            total_tokens,
+            cost_usd: 0.0,
+        })
+    }
+}
+
+impl LlmProvider for CodexCliProvider {
+    fn name(&self) -> &'static str {
+        "codex_cli"
+    }
+
+    fn invoke(&self, request: LlmRequest) -> Result<LlmResponse, LlmProviderError> {
+        let output_file = codex_temp_file("clarion-codex-output", ".json")?;
+        let schema_file = codex_temp_file("clarion-codex-schema", ".json")?;
+        self.invoke_with_temp_files(request, output_file.path(), schema_file.path())
+    }
+
+    fn estimate_tokens(&self, request: &LlmRequest) -> u64 {
+        u64::from(estimate_text_tokens(&build_coding_agent_provider_prompt(
+            request,
+        ))) + u64::from(request.max_output_tokens)
+    }
+
+    fn tier_to_model(&self, tier: &str) -> Option<&str> {
+        match tier {
+            "summary" | "inferred_edges" => Some(self.model_id.as_str()),
+            _ => None,
+        }
+    }
+
+    fn caching_model(&self) -> CachingModel {
+        CachingModel::OpenAiChatCompletions
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClaudeCliProviderConfig {
+    pub executable: String,
+    pub project_root: PathBuf,
+    pub model_id: String,
+    pub model: Option<String>,
+    pub permission_mode: String,
+    pub tools: Vec<String>,
+    pub timeout_seconds: u64,
+    pub max_turns: u32,
+    pub no_session_persistence: bool,
+    pub exclude_dynamic_system_prompt_sections: bool,
+}
+
+#[derive(Debug, Clone)]
+pub struct ClaudeCliProvider {
+    executable: String,
+    project_root: PathBuf,
+    model_id: String,
+    model: Option<String>,
+    permission_mode: String,
+    tools: Vec<String>,
+    timeout: Duration,
+    timeout_seconds: u64,
+    max_turns: u32,
+    no_session_persistence: bool,
+    exclude_dynamic_system_prompt_sections: bool,
+}
+
+impl ClaudeCliProvider {
+    pub fn from_config(config: ClaudeCliProviderConfig) -> Result<Self, LlmProviderError> {
+        if config.executable.trim().is_empty() {
+            return Err(LlmProviderError::Cli {
+                message: "Claude CLI executable must not be blank".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.model_id.trim().is_empty() {
+            return Err(LlmProviderError::Cli {
+                message: "Claude CLI model_id must not be blank".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.permission_mode.trim().is_empty() {
+            return Err(LlmProviderError::Cli {
+                message: "Claude CLI permission_mode must not be blank".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.timeout_seconds == 0 {
+            return Err(LlmProviderError::Cli {
+                message: "Claude CLI timeout_seconds must be greater than zero".to_owned(),
+                retryable: false,
+            });
+        }
+        if config.max_turns == 0 {
+            return Err(LlmProviderError::Cli {
+                message: "Claude CLI max_turns must be greater than zero".to_owned(),
+                retryable: false,
+            });
+        }
+        validate_cli_executable("Claude CLI", &config.executable)?;
+
+        Ok(Self {
+            executable: config.executable,
+            project_root: config.project_root,
+            model_id: config.model_id,
+            model: config.model.filter(|model| !model.trim().is_empty()),
+            permission_mode: config.permission_mode,
+            tools: config
+                .tools
+                .into_iter()
+                .filter(|tool| !tool.trim().is_empty())
+                .collect(),
+            timeout: Duration::from_secs(config.timeout_seconds),
+            timeout_seconds: config.timeout_seconds,
+            max_turns: config.max_turns,
+            no_session_persistence: config.no_session_persistence,
+            exclude_dynamic_system_prompt_sections: config.exclude_dynamic_system_prompt_sections,
+        })
+    }
+}
+
+impl LlmProvider for ClaudeCliProvider {
+    fn name(&self) -> &'static str {
+        "claude_cli"
+    }
+
+    fn invoke(&self, request: LlmRequest) -> Result<LlmResponse, LlmProviderError> {
+        let schema = codex_output_schema_for_purpose(&request.purpose);
+        let schema_json =
+            serde_json::to_string(&schema).map_err(|err| LlmProviderError::InvalidResponse {
+                message: format!("serialize Claude output schema: {err}"),
+                retryable: false,
+            })?;
+        let provider_prompt = build_coding_agent_provider_prompt(&request);
+        let mut command = Command::new(&self.executable);
+        command
+            .arg("-p")
+            .arg(CLAUDE_CLI_PRINT_PROMPT)
+            .arg("--output-format")
+            .arg("json")
+            .arg("--json-schema")
+            .arg(schema_json)
+            .arg("--permission-mode")
+            .arg(&self.permission_mode)
+            .arg("--max-turns")
+            .arg(self.max_turns.to_string())
+            .arg("--mcp-config")
+            .arg(r#"{"mcpServers":{}}"#)
+            .arg("--strict-mcp-config")
+            .arg("--disable-slash-commands");
+        if self.no_session_persistence {
+            command.arg("--no-session-persistence");
+        }
+        if self.exclude_dynamic_system_prompt_sections {
+            command.arg("--exclude-dynamic-system-prompt-sections");
+        }
+        if let Some(model) = &self.model {
+            command.arg("--model").arg(model);
+        }
+        command.arg("--tools").arg(self.tools.join(","));
+        command
+            .current_dir(&self.project_root)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+
+        let mut child = command.spawn().map_err(|err| LlmProviderError::Cli {
+            message: format!("spawn Claude CLI {}: {err}", self.executable),
+            retryable: false,
+        })?;
+        let stdout_reader = take_reader(&mut child.stdout, "stdout")?;
+        let stderr_reader = take_reader(&mut child.stderr, "stderr")?;
+        if let Err(err) = write_child_stdin(&mut child, &provider_prompt) {
+            let _ = child.kill();
+            return Err(err);
+        }
+
+        let status = wait_for_child(&mut child, self.timeout, self.timeout_seconds)?;
+        let stdout = join_reader(stdout_reader, "stdout")?;
+        let stderr = join_reader(stderr_reader, "stderr")?;
+        if !status.success() {
+            return Err(LlmProviderError::Cli {
+                message: format!(
+                    "claude -p exited with {status}: {}",
+                    truncate_for_error(&String::from_utf8_lossy(&stderr))
+                ),
+                retryable: cli_status_retryable(status),
+            });
+        }
+
+        let parsed = parse_claude_cli_json_output(&stdout)?;
+        let input_tokens = parsed
+            .usage
+            .input_tokens
+            .unwrap_or_else(|| estimate_text_tokens(&provider_prompt));
+        let output_tokens = parsed
+            .usage
+            .output_tokens
+            .unwrap_or_else(|| estimate_text_tokens(&parsed.output_json));
+        let total_tokens = parsed
+            .usage
+            .total_tokens
+            .unwrap_or_else(|| input_tokens.saturating_add(output_tokens));
+        let cached_input_tokens = parsed.usage.cached_input_tokens.unwrap_or(0);
+
+        Ok(LlmResponse {
+            model_id: request.model_id,
+            output_json: parsed.output_json,
+            input_tokens,
+            cached_input_tokens,
+            output_tokens,
+            total_tokens,
+            cost_usd: parsed.cost_usd.unwrap_or(0.0),
+        })
+    }
+
+    fn estimate_tokens(&self, request: &LlmRequest) -> u64 {
+        u64::from(estimate_text_tokens(&build_coding_agent_provider_prompt(
+            request,
+        ))) + u64::from(request.max_output_tokens)
+    }
+
+    fn tier_to_model(&self, tier: &str) -> Option<&str> {
+        match tier {
+            "summary" | "inferred_edges" => Some(self.model_id.as_str()),
+            _ => None,
+        }
+    }
+
+    fn caching_model(&self) -> CachingModel {
+        CachingModel::OpenAiChatCompletions
+    }
+}
+
 fn response_format_for_purpose(purpose: &LlmPurpose) -> Value {
     match purpose {
         LlmPurpose::Summary => serde_json::json!({
@@ -369,6 +834,378 @@ fn response_format_for_purpose(purpose: &LlmPurpose) -> Value {
     }
 }
 
+fn codex_output_schema_for_purpose(purpose: &LlmPurpose) -> Value {
+    response_format_for_purpose(purpose)["json_schema"]["schema"].clone()
+}
+
+fn agent_task_type(purpose: &LlmPurpose) -> &'static str {
+    match purpose {
+        LlmPurpose::Summary => "leaf_summary",
+        LlmPurpose::InferredEdges => "inferred_edges",
+    }
+}
+
+fn agent_task_guidance(purpose: &LlmPurpose) -> &'static str {
+    match purpose {
+        LlmPurpose::Summary => {
+            "- Produce a leaf-scope summary only for the requested entity.\n\
+             - `purpose`, `behavior`, `relationships`, and `risks` must be strings.\n\
+             - Do not summarize sibling entities except where direct caller/callee/ownership context is visible in the supplied excerpt.\n\
+             - Use an empty `risks` string when no concrete implementation risk is visible."
+        }
+        LlmPurpose::InferredEdges => {
+            "- Resolve only unresolved call sites listed in the request.\n\
+             - Choose targets only from the supplied candidate entities JSON.\n\
+             - Return no more edges than the request's max_edges instruction allows.\n\
+             - Use confidence from 0.0 to 1.0 and include brief evidence in `rationale`.\n\
+             - Return `{\"edges\":[]}` when the supplied evidence is insufficient."
+        }
+    }
+}
+
+type PipeReader = thread::JoinHandle<std::io::Result<Vec<u8>>>;
+
+fn take_reader<R>(
+    pipe: &mut Option<R>,
+    pipe_name: &'static str,
+) -> Result<PipeReader, LlmProviderError>
+where
+    R: Read + Send + 'static,
+{
+    let mut reader = pipe.take().ok_or_else(|| LlmProviderError::Cli {
+        message: format!("child {pipe_name} was not captured"),
+        retryable: false,
+    })?;
+    Ok(thread::spawn(move || {
+        let mut bytes = Vec::new();
+        reader.read_to_end(&mut bytes)?;
+        Ok(bytes)
+    }))
+}
+
+fn write_child_stdin(child: &mut Child, prompt: &str) -> Result<(), LlmProviderError> {
+    let mut stdin = child.stdin.take().ok_or_else(|| LlmProviderError::Cli {
+        message: "child stdin was not captured".to_owned(),
+        retryable: false,
+    })?;
+    stdin
+        .write_all(prompt.as_bytes())
+        .map_err(|err| LlmProviderError::Cli {
+            message: format!("write provider prompt to stdin: {err}"),
+            retryable: true,
+        })?;
+    Ok(())
+}
+
+fn wait_for_child(
+    child: &mut Child,
+    timeout: Duration,
+    timeout_seconds: u64,
+) -> Result<ExitStatus, LlmProviderError> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        match child.try_wait() {
+            Ok(Some(status)) => return Ok(status),
+            Ok(None) if Instant::now() >= deadline => {
+                let _ = child.kill();
+                let _ = child.wait();
+                return Err(LlmProviderError::Timeout { timeout_seconds });
+            }
+            Ok(None) => thread::sleep(Duration::from_millis(25)),
+            Err(err) => {
+                return Err(LlmProviderError::Cli {
+                    message: format!("poll provider process status: {err}"),
+                    retryable: true,
+                });
+            }
+        }
+    }
+}
+
+fn join_reader(handle: PipeReader, pipe_name: &'static str) -> Result<Vec<u8>, LlmProviderError> {
+    match handle.join() {
+        Ok(Ok(bytes)) => Ok(bytes),
+        Ok(Err(err)) => Err(LlmProviderError::Cli {
+            message: format!("read provider {pipe_name}: {err}"),
+            retryable: true,
+        }),
+        Err(_) => Err(LlmProviderError::Cli {
+            message: format!("read provider {pipe_name}: reader thread panicked"),
+            retryable: true,
+        }),
+    }
+}
+
+fn cli_status_retryable(status: ExitStatus) -> bool {
+    status.code().is_none()
+}
+
+fn truncate_for_error(message: &str) -> String {
+    const MAX_ERROR_CHARS: usize = 4096;
+    if message.chars().count() <= MAX_ERROR_CHARS {
+        return message.to_owned();
+    }
+    let mut truncated: String = message.chars().take(MAX_ERROR_CHARS).collect();
+    truncated.push_str("... (truncated)");
+    truncated
+}
+
+fn codex_status_retryable(status: ExitStatus) -> bool {
+    cli_status_retryable(status)
+}
+
+fn codex_temp_file(
+    prefix: &str,
+    suffix: &str,
+) -> Result<tempfile::NamedTempFile, LlmProviderError> {
+    tempfile::Builder::new()
+        .prefix(prefix)
+        .suffix(suffix)
+        .tempfile()
+        .map_err(|err| LlmProviderError::Cli {
+            message: format!("create Codex CLI temp file {prefix}: {err}"),
+            retryable: true,
+        })
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq)]
+struct LlmUsageSummary {
+    input_tokens: Option<u32>,
+    cached_input_tokens: Option<u32>,
+    output_tokens: Option<u32>,
+    total_tokens: Option<u32>,
+    cost_usd: Option<f64>,
+}
+
+impl LlmUsageSummary {
+    fn add(&mut self, other: Self) {
+        self.input_tokens = add_optional_u32(self.input_tokens, other.input_tokens);
+        self.cached_input_tokens =
+            add_optional_u32(self.cached_input_tokens, other.cached_input_tokens);
+        self.output_tokens = add_optional_u32(self.output_tokens, other.output_tokens);
+        self.total_tokens = add_optional_u32(self.total_tokens, other.total_tokens);
+        self.cost_usd = add_optional_f64(self.cost_usd, other.cost_usd);
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct ClaudeCliOutput {
+    output_json: String,
+    usage: LlmUsageSummary,
+    cost_usd: Option<f64>,
+}
+
+fn add_optional_u32(left: Option<u32>, right: Option<u32>) -> Option<u32> {
+    match (left, right) {
+        (Some(left), Some(right)) => Some(left.saturating_add(right)),
+        (Some(value), None) | (None, Some(value)) => Some(value),
+        (None, None) => None,
+    }
+}
+
+fn add_optional_f64(left: Option<f64>, right: Option<f64>) -> Option<f64> {
+    match (left, right) {
+        (Some(left), Some(right)) => Some(left + right),
+        (Some(value), None) | (None, Some(value)) => Some(value),
+        (None, None) => None,
+    }
+}
+
+fn parse_codex_jsonl_usage(stdout: &[u8]) -> LlmUsageSummary {
+    let mut summary = LlmUsageSummary::default();
+    let stdout_text = String::from_utf8_lossy(stdout);
+    let mut malformed: u64 = 0;
+    for line in stdout_text
+        .lines()
+        .map(str::trim)
+        .filter(|line| !line.is_empty())
+    {
+        match serde_json::from_str::<Value>(line) {
+            Ok(event) => summary.add(usage_from_event(&event)),
+            Err(err) => {
+                malformed += 1;
+                tracing::warn!(
+                    error = %err,
+                    snippet = %line.chars().take(80).collect::<String>(),
+                    "Codex JSONL usage parser: skipping malformed line; token totals will be \
+                     under-reported and `session_token_ceiling` enforcement may diverge from \
+                     true accounting"
+                );
+            }
+        }
+    }
+    if malformed > 0 {
+        tracing::warn!(
+            malformed = malformed,
+            "Codex JSONL usage parser skipped {malformed} malformed line{suffix}; token totals \
+             below are a lower bound only",
+            suffix = if malformed == 1 { "" } else { "s" },
+        );
+    }
+    summary
+}
+
+fn parse_claude_cli_json_output(stdout: &[u8]) -> Result<ClaudeCliOutput, LlmProviderError> {
+    let stdout_text = String::from_utf8_lossy(stdout);
+    let trimmed = stdout_text.trim();
+    if trimmed.is_empty() {
+        return Err(LlmProviderError::InvalidResponse {
+            message: "Claude CLI returned empty stdout".to_owned(),
+            retryable: true,
+        });
+    }
+    let value = serde_json::from_str::<Value>(trimmed).map_err(|err| {
+        LlmProviderError::InvalidResponse {
+            message: format!("Claude CLI stdout was not JSON: {err}"),
+            retryable: true,
+        }
+    })?;
+    let events = match &value {
+        Value::Array(events) => events.as_slice(),
+        _ => std::slice::from_ref(&value),
+    };
+    let result_event = events
+        .iter()
+        .rev()
+        .find(|event| event.get("type").and_then(Value::as_str) == Some("result"))
+        .or_else(|| {
+            events
+                .iter()
+                .rev()
+                .find(|event| has_claude_structured_output(event))
+        })
+        .ok_or_else(|| LlmProviderError::InvalidResponse {
+            message: "Claude CLI stdout had no `result` event or `structured_output`/\
+                      `structuredOutput`/`result` payload; refusing to persist raw stdout \
+                      as structured output"
+                .to_owned(),
+            retryable: true,
+        })?;
+    let usage = if result_event.get("usage").is_some() {
+        usage_from_event(result_event)
+    } else {
+        let mut summary = LlmUsageSummary::default();
+        for event in events {
+            summary.add(usage_from_event(event));
+        }
+        summary
+    };
+    let cost_usd = result_event
+        .get("total_cost_usd")
+        .or_else(|| result_event.get("cost_usd"))
+        .and_then(Value::as_f64)
+        .or(usage.cost_usd);
+    let output_json = claude_structured_output_json(result_event)?;
+    Ok(ClaudeCliOutput {
+        output_json,
+        usage,
+        cost_usd,
+    })
+}
+
+fn has_claude_structured_output(value: &Value) -> bool {
+    value.get("structured_output").is_some()
+        || value.get("structuredOutput").is_some()
+        || value.get("result").is_some()
+}
+
+fn claude_structured_output_json(value: &Value) -> Result<String, LlmProviderError> {
+    let output = value
+        .get("structured_output")
+        .or_else(|| value.get("structuredOutput"))
+        .or_else(|| value.get("result"))
+        .ok_or_else(|| LlmProviderError::InvalidResponse {
+            message: "Claude CLI event lacked `structured_output`/`structuredOutput`/`result` \
+                      field; refusing to persist raw event as structured output"
+                .to_owned(),
+            retryable: true,
+        })?;
+    json_value_to_output_json(output, "Claude CLI structured output")
+}
+
+fn json_value_to_output_json(value: &Value, label: &str) -> Result<String, LlmProviderError> {
+    match value {
+        Value::String(text) => {
+            let trimmed = text.trim();
+            if trimmed.is_empty() {
+                return Err(LlmProviderError::InvalidResponse {
+                    message: format!("{label} was empty"),
+                    retryable: true,
+                });
+            }
+            serde_json::from_str::<Value>(trimmed).map_err(|err| {
+                LlmProviderError::InvalidResponse {
+                    message: format!("{label} string was not JSON: {err}"),
+                    retryable: true,
+                }
+            })?;
+            Ok(trimmed.to_owned())
+        }
+        Value::Object(_) | Value::Array(_) => {
+            serde_json::to_string(value).map_err(|err| LlmProviderError::InvalidResponse {
+                message: format!("serialize {label}: {err}"),
+                retryable: false,
+            })
+        }
+        _ => Err(LlmProviderError::InvalidResponse {
+            message: format!("{label} was not an object, array, or JSON string"),
+            retryable: true,
+        }),
+    }
+}
+
+fn usage_from_event(event: &Value) -> LlmUsageSummary {
+    let raw_usage = event
+        .get("usage")
+        .or_else(|| event.get("msg").and_then(|msg| msg.get("usage")))
+        .or_else(|| {
+            event
+                .get("message")
+                .and_then(|message| message.get("usage"))
+        });
+    let Some(raw_usage) = raw_usage else {
+        return LlmUsageSummary::default();
+    };
+    usage_from_usage_value(raw_usage)
+}
+
+fn usage_from_usage_value(raw_usage: &Value) -> LlmUsageSummary {
+    let input_tokens = u32_from_value(raw_usage.get("input_tokens"))
+        .or_else(|| u32_from_value(raw_usage.get("prompt_tokens")));
+    let output_tokens = u32_from_value(raw_usage.get("output_tokens"))
+        .or_else(|| u32_from_value(raw_usage.get("completion_tokens")));
+    let total_tokens = u32_from_value(raw_usage.get("total_tokens")).or_else(|| {
+        match (input_tokens, output_tokens) {
+            (Some(input), Some(output)) => Some(input.saturating_add(output)),
+            _ => None,
+        }
+    });
+    let cached_from_details = raw_usage
+        .get("prompt_tokens_details")
+        .and_then(|details| u32_from_value(details.get("cached_tokens")));
+    let cached_input_tokens = u32_from_value(raw_usage.get("cached_input_tokens"))
+        .or_else(|| u32_from_value(raw_usage.get("cache_read_input_tokens")))
+        .or(cached_from_details);
+    LlmUsageSummary {
+        input_tokens,
+        cached_input_tokens,
+        output_tokens,
+        total_tokens,
+        cost_usd: raw_usage
+            .get("cost_usd")
+            .or_else(|| raw_usage.get("cost"))
+            .and_then(Value::as_f64),
+    }
+}
+
+fn u32_from_value(value: Option<&Value>) -> Option<u32> {
+    let value = value?;
+    match value {
+        Value::Number(number) => number.as_u64().and_then(|value| u32::try_from(value).ok()),
+        _ => None,
+    }
+}
+
 #[derive(Debug, Deserialize)]
 struct OpenRouterChatResponse {
     model: String,
@@ -422,9 +1259,15 @@ struct OpenRouterUsage {
     completion: u32,
     #[serde(rename = "total_tokens")]
     total: u32,
+    prompt_tokens_details: Option<OpenRouterPromptTokensDetails>,
     cost: Option<f64>,
 }
 
+#[derive(Debug, Deserialize)]
+struct OpenRouterPromptTokensDetails {
+    cached_tokens: u32,
+}
+
 #[derive(Debug, Deserialize)]
 struct OpenRouterErrorEnvelope {
     error: OpenRouterErrorBody,
@@ -577,6 +1420,7 @@ mod tests {
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             output_json: r#"{"purpose":"demo"}"#.to_owned(),
             input_tokens: 120,
+            cached_input_tokens: 0,
             output_tokens: 24,
             total_tokens: 144,
             cost_usd: 0.0,
@@ -623,6 +1467,27 @@ mod tests {
         assert!(inferred.body.contains("no more than 8 entries"));
     }
 
+    #[test]
+    fn coding_agent_provider_prompt_wraps_request_with_shared_contract() {
+        let request = LlmRequest {
+            purpose: LlmPurpose::InferredEdges,
+            model_id: "agent-default".to_owned(),
+            prompt_id: INFERRED_CALLS_PROMPT_VERSION.to_owned(),
+            prompt: "Resolve call-site a from the supplied candidates".to_owned(),
+            max_output_tokens: 2048,
+        };
+
+        let prompt = build_coding_agent_provider_prompt(&request);
+
+        assert!(prompt.contains("Prompt contract: clarion-agent-provider-v1"));
+        assert!(prompt.contains("Task type: inferred_edges"));
+        assert!(prompt.contains("Do not inspect additional files"));
+        assert!(prompt.contains("Return exactly one JSON object"));
+        assert!(prompt.contains("Choose targets only from the supplied candidate entities JSON"));
+        assert!(prompt.contains("<clarion_request>"));
+        assert!(prompt.contains("Resolve call-site a from the supplied candidates"));
+    }
+
     #[test]
     fn openrouter_provider_requires_explicit_live_opt_in_and_api_key() {
         let denied = OpenRouterProvider::from_config(OpenRouterProviderConfig {
@@ -630,7 +1495,7 @@ mod tests {
             allow_live_provider: false,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: "https://openrouter.ai/api/v1".to_owned(),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect_err("api key alone must not enable live calls");
@@ -641,7 +1506,7 @@ mod tests {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: "https://openrouter.ai/api/v1".to_owned(),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect_err("live opt-in without key should fail");
@@ -652,7 +1517,7 @@ mod tests {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: "https://openrouter.ai/api/v1".to_owned(),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect("live opt-in and key should construct provider");
@@ -686,7 +1551,7 @@ mod tests {
             let request = String::from_utf8_lossy(&request[..read]);
             assert!(request.contains("POST /api/v1/chat/completions HTTP/1.1"));
             assert!(request.contains("authorization: Bearer secret"));
-            assert!(request.contains("http-referer: https://github.com/qacona/clarion"));
+            assert!(request.contains("http-referer: https://github.com/tachyon-beep/clarion"));
             assert!(request.contains("x-openrouter-title: Clarion"));
             assert!(request.contains(r#""model":"anthropic/claude-sonnet-4.6""#));
             assert!(request.contains(r#""max_tokens":512"#));
@@ -726,7 +1591,7 @@ mod tests {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: format!("http://{addr}/api/v1"),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect("test provider");
@@ -847,7 +1712,7 @@ mod tests {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: format!("http://{addr}/api/v1"),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect("test provider");
@@ -878,7 +1743,7 @@ mod tests {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: format!("http://{addr}/api/v1"),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect("test provider");
@@ -895,6 +1760,660 @@ mod tests {
         ));
     }
 
+    #[test]
+    #[allow(clippy::too_many_lines)]
+    fn codex_cli_provider_invokes_exec_with_schema_stdin_and_usage() {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+
+        let temp = tempfile::tempdir().expect("tempdir");
+        let project_root = temp.path().join("project");
+        fs::create_dir(&project_root).expect("project root");
+        let fake_codex = temp.path().join("codex");
+        let log_path = temp.path().join("codex.log");
+        let script = format!(
+            r#"#!/usr/bin/env bash
+set -euo pipefail
+log="{log}"
+out=""
+schema=""
+cd_arg=""
+sandbox=""
+model=""
+profile=""
+json=0
+stdin_prompt=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    exec)
+      echo "subcommand=exec" >> "$log"
+      shift
+      ;;
+    --sandbox)
+      sandbox="$2"
+      shift 2
+      ;;
+    --cd)
+      cd_arg="$2"
+      shift 2
+      ;;
+    --output-last-message)
+      out="$2"
+      shift 2
+      ;;
+    --output-schema)
+      schema="$2"
+      shift 2
+      ;;
+    --model)
+      model="$2"
+      shift 2
+      ;;
+    --profile)
+      profile="$2"
+      shift 2
+      ;;
+    --json)
+      json=1
+      shift
+      ;;
+    -c)
+      echo "config=$2" >> "$log"
+      shift 2
+      ;;
+    -)
+      stdin_prompt="$(cat)"
+      shift
+      ;;
+    *)
+      echo "arg=$1" >> "$log"
+      shift
+      ;;
+  esac
+done
+
+test "$json" = "1"
+test -n "$out"
+test -s "$schema"
+grep -q '"purpose"' "$schema"
+grep -q '"behavior"' "$schema"
+case "$stdin_prompt" in
+  *"Summarize this function"*) ;;
+  *) echo "missing prompt" >&2; exit 31 ;;
+esac
+case "$stdin_prompt" in
+  *"Prompt contract: clarion-agent-provider-v1"*"Do not inspect additional files"*) ;;
+  *) echo "missing Clarion agent prompt contract" >&2; exit 32 ;;
+esac
+
+echo "sandbox=$sandbox" >> "$log"
+echo "cd=$cd_arg" >> "$log"
+echo "model=$model" >> "$log"
+echo "profile=$profile" >> "$log"
+printf '%s\n' '{{"usage":{{"input_tokens":11,"cached_input_tokens":4,"output_tokens":7,"total_tokens":18}}}}'
+printf '%s' '{{"purpose":"via codex","behavior":"ran fake CLI","relationships":"","risks":""}}' > "$out"
+"#,
+            log = log_path.display()
+        );
+        fs::write(&fake_codex, script).expect("write fake codex");
+        let mut permissions = fs::metadata(&fake_codex).expect("metadata").permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&fake_codex, permissions).expect("chmod fake codex");
+
+        let provider = CodexCliProvider::from_config(CodexCliProviderConfig {
+            executable: fake_codex.display().to_string(),
+            project_root: project_root.clone(),
+            model_id: "codex-cli-default".to_owned(),
+            model: Some("gpt-5.5".to_owned()),
+            profile: Some("clarion".to_owned()),
+            sandbox: "read-only".to_owned(),
+            timeout_seconds: 5,
+        })
+        .expect("construct Codex CLI provider");
+
+        let response = provider
+            .invoke(LlmRequest {
+                purpose: LlmPurpose::Summary,
+                model_id: "codex-cli-default".to_owned(),
+                prompt_id: LEAF_SUMMARY_PROMPT_TEMPLATE_ID.to_owned(),
+                prompt: "Summarize this function".to_owned(),
+                max_output_tokens: 512,
+            })
+            .expect("invoke fake Codex CLI");
+
+        assert_eq!(provider.name(), "codex_cli");
+        assert_eq!(provider.tier_to_model("summary"), Some("codex-cli-default"));
+        assert_eq!(response.model_id, "codex-cli-default");
+        assert_eq!(
+            response.output_json,
+            r#"{"purpose":"via codex","behavior":"ran fake CLI","relationships":"","risks":""}"#
+        );
+        assert_eq!(response.input_tokens, 11);
+        assert_eq!(response.cached_input_tokens, 4);
+        assert_eq!(response.output_tokens, 7);
+        assert_eq!(response.total_tokens, 18);
+        assert!(response.cost_usd.abs() < f64::EPSILON);
+
+        let log = fs::read_to_string(log_path).expect("read fake codex log");
+        assert!(log.contains("subcommand=exec"));
+        assert!(log.contains("config=approval_policy=\"never\""));
+        assert!(log.contains("sandbox=read-only"));
+        assert!(log.contains(&format!("cd={}", project_root.display())));
+        assert!(log.contains("model=gpt-5.5"));
+        assert!(log.contains("profile=clarion"));
+    }
+
+    #[test]
+    fn codex_cli_provider_fallback_usage_counts_wrapped_prompt() {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+
+        let temp = tempfile::tempdir().expect("tempdir");
+        let project_root = temp.path().join("project");
+        fs::create_dir(&project_root).expect("project root");
+        let fake_codex = temp.path().join("codex");
+        let script = r#"#!/usr/bin/env bash
+set -euo pipefail
+out=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --output-last-message)
+      out="$2"
+      shift 2
+      ;;
+    --sandbox|--cd|--output-schema|--model|--profile|-c)
+      shift 2
+      ;;
+    -)
+      cat >/dev/null
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+printf '%s' '{"purpose":"via codex","behavior":"ran fake CLI","relationships":"","risks":""}' > "$out"
+"#;
+        fs::write(&fake_codex, script).expect("write fake codex");
+        let mut permissions = fs::metadata(&fake_codex).expect("metadata").permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&fake_codex, permissions).expect("chmod fake codex");
+
+        let provider = CodexCliProvider::from_config(CodexCliProviderConfig {
+            executable: fake_codex.display().to_string(),
+            project_root,
+            model_id: "codex-cli-default".to_owned(),
+            model: None,
+            profile: None,
+            sandbox: "read-only".to_owned(),
+            timeout_seconds: 5,
+        })
+        .expect("construct Codex CLI provider");
+        let request = LlmRequest {
+            purpose: LlmPurpose::Summary,
+            model_id: "codex-cli-default".to_owned(),
+            prompt_id: LEAF_SUMMARY_PROMPT_TEMPLATE_ID.to_owned(),
+            prompt: "short raw prompt".to_owned(),
+            max_output_tokens: 512,
+        };
+        let expected_input_tokens =
+            estimate_text_tokens(&build_coding_agent_provider_prompt(&request));
+
+        let response = provider.invoke(request).expect("invoke fake Codex CLI");
+
+        assert_eq!(response.input_tokens, expected_input_tokens);
+    }
+
+    #[test]
+    #[allow(clippy::too_many_lines)]
+    fn claude_cli_provider_invokes_print_mode_with_schema_and_usage() {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+
+        let temp = tempfile::tempdir().expect("tempdir");
+        let project_root = temp.path().join("project");
+        fs::create_dir(&project_root).expect("project root");
+        let fake_claude = temp.path().join("claude");
+        let log_path = temp.path().join("claude.log");
+        let script = format!(
+            r#"#!/usr/bin/env bash
+set -euo pipefail
+log="{log}"
+schema=""
+format=""
+model=""
+permission_mode=""
+tools="unset"
+max_turns=""
+no_session_persistence=0
+exclude_dynamic=0
+mcp_config=""
+strict_mcp=0
+slash_disabled=0
+print_prompt=""
+stdin_prompt=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -p|--print)
+      print_prompt="$2"
+      shift 2
+      ;;
+    --output-format)
+      format="$2"
+      shift 2
+      ;;
+    --json-schema)
+      schema="$2"
+      shift 2
+      ;;
+    --model)
+      model="$2"
+      shift 2
+      ;;
+    --permission-mode)
+      permission_mode="$2"
+      shift 2
+      ;;
+    --tools)
+      tools="$2"
+      shift 2
+      ;;
+    --max-turns)
+      max_turns="$2"
+      shift 2
+      ;;
+    --mcp-config)
+      mcp_config="$2"
+      shift 2
+      ;;
+    --strict-mcp-config)
+      strict_mcp=1
+      shift
+      ;;
+    --disable-slash-commands)
+      slash_disabled=1
+      shift
+      ;;
+    --no-session-persistence)
+      no_session_persistence=1
+      shift
+      ;;
+    --exclude-dynamic-system-prompt-sections)
+      exclude_dynamic=1
+      shift
+      ;;
+    *)
+      echo "arg=$1" >> "$log"
+      shift
+      ;;
+  esac
+done
+stdin_prompt="$(cat)"
+
+test "$format" = "json"
+case "$schema" in
+  *'"purpose"'*'"behavior"'*) ;;
+  *) echo "schema missing summary fields" >&2; exit 41 ;;
+esac
+case "$stdin_prompt" in
+  *"Summarize this function"*) ;;
+  *) echo "missing prompt" >&2; exit 42 ;;
+esac
+case "$stdin_prompt" in
+  *"Prompt contract: clarion-agent-provider-v1"*"Do not inspect additional files"*) ;;
+  *) echo "missing Clarion agent prompt contract" >&2; exit 43 ;;
+esac
+
+echo "print_prompt=$print_prompt" >> "$log"
+echo "model=$model" >> "$log"
+echo "permission_mode=$permission_mode" >> "$log"
+echo "tools=$tools" >> "$log"
+echo "max_turns=$max_turns" >> "$log"
+echo "mcp_config=$mcp_config" >> "$log"
+echo "strict_mcp=$strict_mcp" >> "$log"
+echo "slash_disabled=$slash_disabled" >> "$log"
+echo "no_session_persistence=$no_session_persistence" >> "$log"
+echo "exclude_dynamic=$exclude_dynamic" >> "$log"
+printf '%s\n' '{{"type":"result","subtype":"success","structured_output":{{"purpose":"via claude","behavior":"ran fake CLI","relationships":"","risks":""}},"usage":{{"input_tokens":13,"cached_input_tokens":5,"output_tokens":6,"total_tokens":19}},"total_cost_usd":0.25}}'
+"#,
+            log = log_path.display()
+        );
+        fs::write(&fake_claude, script).expect("write fake claude");
+        let mut permissions = fs::metadata(&fake_claude).expect("metadata").permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&fake_claude, permissions).expect("chmod fake claude");
+
+        let provider = ClaudeCliProvider::from_config(ClaudeCliProviderConfig {
+            executable: fake_claude.display().to_string(),
+            project_root,
+            model_id: "claude-code-default".to_owned(),
+            model: Some("claude-sonnet-4-6".to_owned()),
+            permission_mode: "plan".to_owned(),
+            tools: vec!["Read".to_owned(), "Grep".to_owned()],
+            timeout_seconds: 5,
+            max_turns: 2,
+            no_session_persistence: true,
+            exclude_dynamic_system_prompt_sections: true,
+        })
+        .expect("construct Claude CLI provider");
+
+        let response = provider
+            .invoke(LlmRequest {
+                purpose: LlmPurpose::Summary,
+                model_id: "claude-code-default".to_owned(),
+                prompt_id: LEAF_SUMMARY_PROMPT_TEMPLATE_ID.to_owned(),
+                prompt: "Summarize this function".to_owned(),
+                max_output_tokens: 512,
+            })
+            .expect("invoke fake Claude CLI");
+
+        assert_eq!(provider.name(), "claude_cli");
+        assert_eq!(
+            provider.tier_to_model("summary"),
+            Some("claude-code-default")
+        );
+        assert_eq!(response.model_id, "claude-code-default");
+        assert_eq!(response.input_tokens, 13);
+        assert_eq!(response.cached_input_tokens, 5);
+        assert_eq!(response.output_tokens, 6);
+        assert_eq!(response.total_tokens, 19);
+        assert!((response.cost_usd - 0.25).abs() < f64::EPSILON);
+        assert_eq!(
+            serde_json::from_str::<Value>(&response.output_json).expect("response JSON"),
+            serde_json::json!({
+                "purpose": "via claude",
+                "behavior": "ran fake CLI",
+                "relationships": "",
+                "risks": ""
+            })
+        );
+
+        let log = fs::read_to_string(log_path).expect("read fake claude log");
+        assert!(log.contains("print_prompt=You are Clarion's local Claude Code LLM provider"));
+        assert!(log.contains("model=claude-sonnet-4-6"));
+        assert!(log.contains("permission_mode=plan"));
+        assert!(log.contains("tools=Read,Grep"));
+        assert!(log.contains("max_turns=2"));
+        assert!(log.contains(r#"mcp_config={"mcpServers":{}}"#));
+        assert!(log.contains("strict_mcp=1"));
+        assert!(log.contains("slash_disabled=1"));
+        assert!(log.contains("no_session_persistence=1"));
+        assert!(log.contains("exclude_dynamic=1"));
+    }
+
+    #[test]
+    fn claude_cli_provider_fallback_usage_counts_wrapped_prompt() {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+
+        let temp = tempfile::tempdir().expect("tempdir");
+        let project_root = temp.path().join("project");
+        fs::create_dir(&project_root).expect("project root");
+        let fake_claude = temp.path().join("claude");
+        let script = r#"#!/usr/bin/env bash
+set -euo pipefail
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -p|--print|--output-format|--json-schema|--permission-mode|--max-turns|--mcp-config|--tools|--model)
+      shift 2
+      ;;
+    --strict-mcp-config|--disable-slash-commands|--no-session-persistence|--exclude-dynamic-system-prompt-sections)
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+cat >/dev/null
+printf '%s\n' '{"type":"result","subtype":"success","structured_output":{"purpose":"via claude","behavior":"ran fake CLI","relationships":"","risks":""},"total_cost_usd":0.0}'
+"#;
+        fs::write(&fake_claude, script).expect("write fake claude");
+        let mut permissions = fs::metadata(&fake_claude).expect("metadata").permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&fake_claude, permissions).expect("chmod fake claude");
+
+        let provider = ClaudeCliProvider::from_config(ClaudeCliProviderConfig {
+            executable: fake_claude.display().to_string(),
+            project_root,
+            model_id: "claude-code-default".to_owned(),
+            model: None,
+            permission_mode: "plan".to_owned(),
+            tools: Vec::new(),
+            timeout_seconds: 5,
+            max_turns: 2,
+            no_session_persistence: true,
+            exclude_dynamic_system_prompt_sections: true,
+        })
+        .expect("construct Claude CLI provider");
+        let request = LlmRequest {
+            purpose: LlmPurpose::Summary,
+            model_id: "claude-code-default".to_owned(),
+            prompt_id: LEAF_SUMMARY_PROMPT_TEMPLATE_ID.to_owned(),
+            prompt: "short raw prompt".to_owned(),
+            max_output_tokens: 512,
+        };
+        let expected_input_tokens =
+            estimate_text_tokens(&build_coding_agent_provider_prompt(&request));
+
+        let response = provider.invoke(request).expect("invoke fake Claude CLI");
+
+        assert_eq!(response.input_tokens, expected_input_tokens);
+    }
+
+    #[test]
+    fn claude_cli_provider_passes_empty_tools_arg_when_no_tools_are_configured() {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+
+        let temp = tempfile::tempdir().expect("tempdir");
+        let project_root = temp.path().join("project");
+        fs::create_dir(&project_root).expect("project root");
+        let fake_claude = temp.path().join("claude");
+        let log_path = temp.path().join("claude.log");
+        let script = format!(
+            r#"#!/usr/bin/env bash
+set -euo pipefail
+log="{log}"
+saw_tools=0
+tools_value="<unset>"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --tools)
+      saw_tools=1
+      tools_value="${{2-<missing>}}"
+      shift 2
+      ;;
+    -p|--print|--output-format|--json-schema|--permission-mode|--max-turns|--mcp-config)
+      shift 2
+      ;;
+    --strict-mcp-config|--disable-slash-commands|--no-session-persistence|--exclude-dynamic-system-prompt-sections)
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+cat >/dev/null
+echo "saw_tools=$saw_tools" >> "$log"
+echo "tools_value=[$tools_value]" >> "$log"
+printf '%s\n' '{{"type":"result","subtype":"success","structured_output":{{"purpose":"via claude","behavior":"ran fake CLI","relationships":"","risks":""}},"usage":{{"input_tokens":1,"output_tokens":1,"total_tokens":2}},"total_cost_usd":0.0}}'
+"#,
+            log = log_path.display()
+        );
+        fs::write(&fake_claude, script).expect("write fake claude");
+        let mut permissions = fs::metadata(&fake_claude).expect("metadata").permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&fake_claude, permissions).expect("chmod fake claude");
+
+        let provider = ClaudeCliProvider::from_config(ClaudeCliProviderConfig {
+            executable: fake_claude.display().to_string(),
+            project_root,
+            model_id: "claude-code-default".to_owned(),
+            model: None,
+            permission_mode: "plan".to_owned(),
+            tools: Vec::new(),
+            timeout_seconds: 5,
+            max_turns: 2,
+            no_session_persistence: true,
+            exclude_dynamic_system_prompt_sections: true,
+        })
+        .expect("construct Claude CLI provider");
+
+        provider
+            .invoke(LlmRequest {
+                purpose: LlmPurpose::Summary,
+                model_id: "claude-code-default".to_owned(),
+                prompt_id: LEAF_SUMMARY_PROMPT_TEMPLATE_ID.to_owned(),
+                prompt: "Summarize this function".to_owned(),
+                max_output_tokens: 512,
+            })
+            .expect("invoke fake Claude CLI");
+
+        let log = fs::read_to_string(log_path).expect("read fake claude log");
+        assert!(
+            log.contains("saw_tools=1"),
+            "Claude CLI must always receive --tools so the default no-tools posture is mechanically enforced (ADR-013). log: {log}"
+        );
+        assert!(
+            log.contains("tools_value=[]"),
+            "Empty tools list must be passed as an explicit empty --tools value, not omitted. log: {log}"
+        );
+    }
+
+    #[test]
+    fn claude_cli_output_parser_accepts_event_array_and_cache_reads() {
+        let stdout = br#"[
+          {"type":"system","subtype":"init"},
+          {"type":"assistant","message":{"usage":{"input_tokens":4,"output_tokens":3}}},
+          {"type":"result","subtype":"success","structured_output":{"purpose":"array","behavior":"ok","relationships":"","risks":""},"total_cost_usd":0.75,"usage":{"input_tokens":7,"cache_read_input_tokens":25,"output_tokens":11,"total_tokens":43}}
+        ]"#;
+
+        let parsed = parse_claude_cli_json_output(stdout).expect("parse Claude event array");
+
+        assert_eq!(
+            serde_json::from_str::<Value>(&parsed.output_json).expect("output json"),
+            serde_json::json!({
+                "purpose": "array",
+                "behavior": "ok",
+                "relationships": "",
+                "risks": ""
+            })
+        );
+        assert_eq!(parsed.usage.input_tokens, Some(7));
+        assert_eq!(parsed.usage.cached_input_tokens, Some(25));
+        assert_eq!(parsed.usage.output_tokens, Some(11));
+        assert_eq!(parsed.usage.total_tokens, Some(43));
+        assert_eq!(parsed.cost_usd, Some(0.75));
+    }
+
+    #[test]
+    fn claude_cli_parser_rejects_empty_stdout_as_retryable_invalid_response() {
+        let err = parse_claude_cli_json_output(b"")
+            .expect_err("empty stdout must surface a typed InvalidResponse");
+        match err {
+            LlmProviderError::InvalidResponse { message, retryable } => {
+                assert!(retryable, "empty stdout should be retryable (transient)");
+                assert!(
+                    message.contains("empty stdout"),
+                    "error message must name the failure mode: {message}"
+                );
+            }
+            other => panic!("expected InvalidResponse for empty stdout, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn claude_cli_parser_rejects_non_json_stdout() {
+        let err = parse_claude_cli_json_output(b"not json")
+            .expect_err("non-JSON stdout must surface a typed InvalidResponse");
+        match err {
+            LlmProviderError::InvalidResponse { message, retryable } => {
+                assert!(retryable);
+                assert!(
+                    message.contains("not JSON"),
+                    "error message must reference JSON parse failure: {message}"
+                );
+            }
+            other => panic!("expected InvalidResponse for non-JSON stdout, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn claude_cli_parser_refuses_raw_stdout_when_no_structured_output_or_result_event() {
+        // Single event with neither `type=result` nor any of the structured
+        // output fields. Pre-fix, the parser fell back to the raw event
+        // payload and downstream consumers persisted it as a summary.
+        // Post-fix (clarion-55fc5aa885 §C3), this must be a typed
+        // InvalidResponse rather than silent garbage.
+        let stdout =
+            br#"{"type":"assistant","message":{"usage":{"input_tokens":1,"output_tokens":1}}}"#;
+        let err = parse_claude_cli_json_output(stdout).expect_err(
+            "stdout without a `result` event or `structured_output` field must \
+             surface InvalidResponse, not be persisted as a summary",
+        );
+        match err {
+            LlmProviderError::InvalidResponse { message, retryable } => {
+                assert!(retryable);
+                assert!(
+                    message.contains("no `result` event"),
+                    "error must explain the missing-structured-output failure: {message}"
+                );
+            }
+            other => {
+                panic!("expected InvalidResponse for missing structured output, got: {other:?}")
+            }
+        }
+    }
+
+    #[test]
+    fn claude_cli_parser_accepts_result_event_with_string_result_payload() {
+        // The other arm `result_event.get("result")` selects a `result`
+        // event that has a JSON-string `result` field. Exercise it to pin
+        // the contract.
+        let stdout = br#"{"type":"result","result":"{\"purpose\":\"string\",\"behavior\":\"ok\",\"relationships\":\"\",\"risks\":\"\"}"}"#;
+        let parsed = parse_claude_cli_json_output(stdout).expect("parse result event");
+        assert_eq!(
+            serde_json::from_str::<Value>(&parsed.output_json).expect("output json"),
+            serde_json::json!({
+                "purpose": "string",
+                "behavior": "ok",
+                "relationships": "",
+                "risks": ""
+            })
+        );
+    }
+
+    #[test]
+    fn cli_status_retryable_treats_signal_kill_as_retryable() {
+        use std::os::unix::process::ExitStatusExt;
+        // ExitStatus::from_raw with a non-exit signal code yields code()=None.
+        let killed = ExitStatus::from_raw(9);
+        assert!(
+            cli_status_retryable(killed),
+            "child killed by signal must be treated as retryable so the orchestrator can retry"
+        );
+        assert!(
+            codex_status_retryable(killed),
+            "codex retryable check must agree with the CLI floor"
+        );
+    }
+
+    #[test]
+    fn cli_status_retryable_treats_clean_nonzero_exit_as_non_retryable() {
+        use std::os::unix::process::ExitStatusExt;
+        // raw status 0x100 → exit code 1, code()=Some(1)
+        let exit_one = ExitStatus::from_raw(0x100);
+        assert!(
+            !cli_status_retryable(exit_one),
+            "clean process exit must be treated as non-retryable: the CLI \
+             rejected the request deterministically"
+        );
+        assert!(!codex_status_retryable(exit_one));
+    }
+
     #[test]
     fn provider_trait_exposes_wp6_methods() {
         fn assert_trait<T: LlmProvider>(_: &T) {}
@@ -937,7 +2456,7 @@ mod tests {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: format!("http://{addr}/api/v1"),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         })
         .expect("test provider");
diff --git a/crates/clarion-core/src/plugin/discovery.rs b/crates/clarion-core/src/plugin/discovery.rs
index 63b83b59..3a7829dc 100644
--- a/crates/clarion-core/src/plugin/discovery.rs
+++ b/crates/clarion-core/src/plugin/discovery.rs
@@ -17,7 +17,14 @@
 //! 1. **Neighbor first**: `<dir>/plugin.toml`.
 //! 2. **Install-prefix fallback** (only when `<dir>` has basename `bin`):
 //!    `<dir>/../share/clarion/plugins/<suffix>/plugin.toml`.
-//! 3. Neither found → [`DiscoveryError::ManifestNotFound`].
+//! 3. **Symlink-resolved install-prefix fallback** (only when `<dir>` has
+//!    basename `bin` and the executable is a symlink, e.g. pipx layout):
+//!    canonicalise the executable, then try
+//!    `<canonical-dir>/../share/clarion/plugins/<suffix>/plugin.toml`.
+//!    This catches `pipx install` (which puts a symlink in `~/.local/bin/`
+//!    pointing into `~/.local/share/pipx/venvs/<pkg>/bin/`, with the
+//!    manifest under that venv's `share/`).
+//! 4. None found → [`DiscoveryError::ManifestNotFound`].
 //!
 //! **Limitation**: when multiple `clarion-plugin-*` binaries share the same
 //! directory (e.g. `/usr/local/bin`), they all resolve to the *same*
@@ -358,16 +365,26 @@ fn find_manifest(exec_path: &std::path::Path, suffix: &str) -> Result<PathBuf, D
 
         // 2. Install-prefix fallback: only when parent dir basename is "bin".
         let parent_name = parent.file_name().and_then(|n| n.to_str());
-        if parent_name == Some("bin")
-            && let Some(grandparent) = parent.parent()
-        {
-            let share_path = grandparent
-                .join("share")
-                .join("clarion")
-                .join("plugins")
-                .join(suffix)
-                .join("plugin.toml");
-            if let Some(found) = probe_manifest(&share_path)? {
+        if parent_name == Some("bin") {
+            if let Some(grandparent) = parent.parent()
+                && let Some(found) = probe_install_prefix_manifest(grandparent, suffix)?
+            {
+                return Ok(found);
+            }
+
+            // 3. Symlink-resolved install-prefix fallback for pipx-style
+            //    layouts: ~/.local/bin/clarion-plugin-<x> is a symlink into
+            //    ~/.local/share/pipx/venvs/<pkg>/bin/clarion-plugin-<x>, and
+            //    the manifest lives under that venv's share/. Canonicalise
+            //    the executable and re-try the install-prefix layout from
+            //    the resolved location.
+            if let Ok(canonical) = exec_path.canonicalize()
+                && canonical != exec_path
+                && let Some(canon_parent) = canonical.parent()
+                && canon_parent.file_name().and_then(|n| n.to_str()) == Some("bin")
+                && let Some(canon_grandparent) = canon_parent.parent()
+                && let Some(found) = probe_install_prefix_manifest(canon_grandparent, suffix)?
+            {
                 return Ok(found);
             }
         }
@@ -378,6 +395,19 @@ fn find_manifest(exec_path: &std::path::Path, suffix: &str) -> Result<PathBuf, D
     })
 }
 
+fn probe_install_prefix_manifest(
+    prefix: &std::path::Path,
+    suffix: &str,
+) -> Result<Option<PathBuf>, DiscoveryError> {
+    let share_path = prefix
+        .join("share")
+        .join("clarion")
+        .join("plugins")
+        .join(suffix)
+        .join("plugin.toml");
+    probe_manifest(&share_path)
+}
+
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(all(test, unix))]
diff --git a/crates/clarion-core/src/plugin/host.rs b/crates/clarion-core/src/plugin/host.rs
index d084ebee..d495bced 100644
--- a/crates/clarion-core/src/plugin/host.rs
+++ b/crates/clarion-core/src/plugin/host.rs
@@ -27,9 +27,10 @@
 //! only calls `setrlimit(2)`, which is async-signal-safe per POSIX.1-2017
 //! §2.4.3. The `unsafe` block is the minimum required by the `pre_exec` API.
 
-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};
 use std::io::{BufRead, Write};
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 
 use thiserror::Error;
 
@@ -413,7 +414,28 @@ where
     /// `None`. Capacity is [`STDERR_TAIL_BYTES`]; oldest bytes are
     /// discarded on overflow so the plugin cannot back-pressure the host
     /// via stderr writes.
-    stderr_tail: Option<std::sync::Arc<std::sync::Mutex<std::collections::VecDeque<u8>>>>,
+    stderr_tail: Option<Arc<std::sync::Mutex<std::collections::VecDeque<u8>>>>,
+    /// Canonical source paths whose entities must not be sent for LLM briefing.
+    briefing_blocks: Arc<BTreeMap<PathBuf, BriefingBlockReason>>,
+    /// Canonical source paths that were covered by the core pre-ingest scanner.
+    scanned_source_files: Arc<BTreeSet<PathBuf>>,
+}
+
+/// File-level reason an entity must not be dispatched for LLM briefing.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum BriefingBlockReason {
+    SecretPresent,
+    UnscannedSource,
+}
+
+impl BriefingBlockReason {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SecretPresent => "secret_present",
+            Self::UnscannedSource => "unscanned_source",
+        }
+    }
 }
 
 /// Size of the stderr ring buffer kept for diagnostics. 64 KiB holds
@@ -428,7 +450,7 @@ pub const STDERR_TAIL_BYTES: usize = 64 * 1024;
 #[cfg(unix)]
 fn drain_stderr_into_ring(
     mut stderr: std::process::ChildStderr,
-    ring: &std::sync::Arc<std::sync::Mutex<std::collections::VecDeque<u8>>>,
+    ring: &Arc<std::sync::Mutex<std::collections::VecDeque<u8>>>,
 ) {
     use std::io::Read;
     let mut buf = [0u8; 4096];
@@ -661,6 +683,8 @@ impl<R: BufRead, W: Write> PluginHost<R, W> {
             terminated: false,
             ontology_version: None,
             stderr_tail: None,
+            briefing_blocks: Arc::new(BTreeMap::new()),
+            scanned_source_files: Arc::new(BTreeSet::new()),
         }
     }
 
@@ -688,6 +712,22 @@ impl<R: BufRead, W: Write> PluginHost<R, W> {
         self.ontology_version.as_deref()
     }
 
+    /// Install file-level briefing blocks produced by the core pre-ingest
+    /// scanner. Keys are canonical source paths and values are typed policy
+    /// reasons rendered into `properties_json` by [`BriefingBlockReason::as_str`].
+    pub fn set_briefing_blocks(&mut self, blocks: Arc<BTreeMap<PathBuf, BriefingBlockReason>>) {
+        self.briefing_blocks = blocks;
+    }
+
+    /// Install canonical source paths covered by the pre-ingest scanner.
+    ///
+    /// If a plugin returns an entity for a jailed in-project path that is not in
+    /// this set, the entity is policy-blocked from LLM briefing because its file
+    /// bytes have not passed the scanner.
+    pub fn set_scanned_source_files(&mut self, files: Arc<BTreeSet<PathBuf>>) {
+        self.scanned_source_files = files;
+    }
+
     /// Perform the `initialize` → `initialized` handshake.
     ///
     /// Steps:
@@ -824,7 +864,7 @@ impl<R: BufRead, W: Write> PluginHost<R, W> {
         let mut accepted = Vec::new();
 
         for raw_val in afr.entities {
-            let raw: RawEntity = match serde_json::from_value(raw_val) {
+            let mut raw: RawEntity = match serde_json::from_value(raw_val) {
                 Ok(e) => e,
                 Err(e) => {
                     // Drop the entity, but record the serde error so operators
@@ -923,6 +963,8 @@ impl<R: BufRead, W: Write> PluginHost<R, W> {
                 return Err(HostError::EntityCapExceeded(e));
             }
 
+            self.apply_briefing_block(&mut raw, &jailed);
+
             accepted.push(AcceptedEntity {
                 id: expected_id,
                 kind: raw.kind.clone(),
@@ -942,6 +984,25 @@ impl<R: BufRead, W: Write> PluginHost<R, W> {
         })
     }
 
+    fn apply_briefing_block(&self, raw: &mut RawEntity, jailed: &str) {
+        let jailed_path = Path::new(jailed);
+        let reason = self.briefing_blocks.get(jailed_path).copied().or_else(|| {
+            (!self.scanned_source_files.contains(jailed_path))
+                .then_some(BriefingBlockReason::UnscannedSource)
+        });
+        // Scanner is the sole authority over `briefing_blocked`. Strip any
+        // plugin-supplied value first so a malicious or buggy plugin cannot
+        // unblock an entity by emitting `"briefing_blocked": <anything>`, and
+        // cannot over-block by injecting a reason the scanner did not assign.
+        raw.extra.remove("briefing_blocked");
+        if let Some(reason) = reason {
+            raw.extra.insert(
+                "briefing_blocked".to_owned(),
+                serde_json::Value::String(reason.as_str().to_owned()),
+            );
+        }
+    }
+
     /// B.3: per-edge validation pipeline. Mirrors the entity loop's
     /// drop-on-violation/emit-finding posture but without the kill paths —
     /// edges do not participate in the path-escape breaker or entity cap
diff --git a/crates/clarion-core/src/plugin/mod.rs b/crates/clarion-core/src/plugin/mod.rs
index 954d527c..83426955 100644
--- a/crates/clarion-core/src/plugin/mod.rs
+++ b/crates/clarion-core/src/plugin/mod.rs
@@ -26,8 +26,8 @@ pub mod transport;
 pub use breaker::{CrashLoopBreaker, CrashLoopState, FINDING_DISABLED_CRASH_LOOP};
 pub use discovery::{DiscoveredPlugin, DiscoveryError, discover, discover_on_path};
 pub use host::{
-    AcceptedEdge, AcceptedEntity, AnalyzeFileOutcome, HostError, HostFinding, PluginHost, RawEdge,
-    RawEntity,
+    AcceptedEdge, AcceptedEntity, AnalyzeFileOutcome, BriefingBlockReason, HostError, HostFinding,
+    PluginHost, RawEdge, RawEntity,
 };
 pub use jail::{JailError, jail, jail_to_string};
 pub use limits::{
diff --git a/crates/clarion-mcp/Cargo.toml b/crates/clarion-mcp/Cargo.toml
index 6e17c2eb..8baaf92c 100644
--- a/crates/clarion-mcp/Cargo.toml
+++ b/crates/clarion-mcp/Cargo.toml
@@ -11,8 +11,8 @@ workspace = true
 
 [dependencies]
 blake3.workspace = true
-clarion-core = { path = "../clarion-core", version = "0.1.0-dev" }
-clarion-storage = { path = "../clarion-storage", version = "0.1.0-dev" }
+clarion-core = { path = "../clarion-core", version = "1.0.0" }
+clarion-storage = { path = "../clarion-storage", version = "1.0.0" }
 reqwest.workspace = true
 rusqlite.workspace = true
 serde.workspace = true
@@ -21,6 +21,11 @@ serde_norway.workspace = true
 thiserror.workspace = true
 time.workspace = true
 tokio.workspace = true
+tracing.workspace = true
+uuid.workspace = true
+
+[target.'cfg(unix)'.dependencies]
+nix = { workspace = true, features = ["signal"] }
 
 [dev-dependencies]
 tempfile.workspace = true
diff --git a/crates/clarion-mcp/assets/skills/clarion-workflow/SKILL.md b/crates/clarion-mcp/assets/skills/clarion-workflow/SKILL.md
new file mode 100644
index 00000000..567d5fff
--- /dev/null
+++ b/crates/clarion-mcp/assets/skills/clarion-workflow/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: clarion-workflow
+description: >
+  Use when orienting in an unfamiliar or large codebase and you want to avoid
+  re-reading or grepping the whole source tree: answering "what calls X",
+  "where is X defined", "what does X depend on", "what subsystem is X in", or
+  "find the function/class/module that does Y". Applies whenever a Clarion
+  code-archaeology MCP server (clarion serve / mcp__clarion__* tools) is
+  available for the project.
+---
+
+# Clarion Workflow
+
+## Overview
+
+Clarion pre-extracts a codebase into a queryable map — entities (functions,
+classes, modules, files), the call/reference/import edges between them, and
+subsystem clusters — and serves it over MCP. **Ask Clarion instead of
+re-exploring the tree.** One `find_entity` + one `callers_of` answers "what
+calls this?" without reading a single file.
+
+## When to use
+
+- You're dropped into a codebase and need to locate a symbol or trace its callers/callees.
+- You'd otherwise `grep`/read many files to answer a structural question.
+- You need a function's neighborhood, execution paths, or which subsystem it belongs to.
+
+**Not for:** editing code, reading exact implementation bodies (use `summary` or
+read the file once you have its path), or codebases with no `.clarion/` index.
+
+## Entity IDs — the model
+
+Every entity has an ID: `{plugin}:{kind}:{qualified_name}`
+(e.g. `python:function:pkg.mod.func`, `python:class:pkg.mod.Cls`,
+`python:module:pkg.mod`). Subsystems are `core:subsystem:{hash}`.
+
+**You almost never type IDs.** Get one from `find_entity` / `entity_at`, then
+**copy it verbatim** into the next tool. Don't hand-construct or guess IDs.
+
+## Tools
+
+| Tool | Use when | Args |
+|------|----------|------|
+| `find_entity` | locate an entity by name/text | `{"pattern": "<name>"}` |
+| `entity_at` | what's at a file:line | `{"file": "rel/path.py", "line": 42}` |
+| `callers_of` | what calls this entity | `{"id": "<id>"}` |
+| `neighborhood` | one-hop callers+callees+container+contained+references+imports | `{"id": "<id>"}` |
+| `execution_paths_from` | bounded call paths out of an entity | `{"id": "<id>", "max_depth": 5}` |
+| `subsystem_members` | modules in a subsystem | `{"id": "core:subsystem:<hash>"}` |
+| `subsystem_of` | the subsystem an entity belongs to (reverse of `subsystem_members`) | `{"id": "<id>"}` |
+| `summary` | on-demand prose summary of one entity | `{"id": "<id>"}` |
+| `summary_preview_cost` | preview a `summary` call's cache status / cost before spending | `{"id": "<id>"}` |
+| `issues_for` | Filigree issues attached to an entity | `{"id": "<id>"}` |
+| `source_for_entity` | an entity's exact indexed source span + bounded context | `{"id": "<id>", "context_lines": 10}` |
+| `call_sites` | the source line(s) behind a calls/references edge | `{"id": "<id>", "role": "caller"}` |
+| `orientation_pack` | one deterministic orientation packet for an entity or file:line (entity + context + neighbors + paths + issues + freshness) | `{"file": "rel/path.py", "line": 42}` |
+| `index_diff` | index freshness / drift vs. the current working tree | `{}` |
+| `analyze_start` | launch a background re-index, return its `run_id` | `{}` |
+| `analyze_status` | poll a started analyze (queued/running/terminal + progress) | `{"run_id": "<id>"}` |
+| `analyze_cancel` | stop a running analyze (group-kills plugin + Pyright) | `{"run_id": "<id>"}` |
+| `project_status` | index freshness, counts, LLM + Filigree status | `{}` |
+
+`callers_of` / `neighborhood` / `execution_paths_from` take a `confidence`
+tier — one of `"resolved"` (default; only high-confidence edges),
+`"ambiguous"`, or `"inferred"`. There is no `"all"` value. When you suspect an
+edge is missing (e.g. dynamic dispatch), re-query at `"ambiguous"` and
+`"inferred"` and union the results — a default `resolved` count can understate
+the true caller set.
+
+These three tools also return a `scope_excludes` array listing static blind
+spots the query did **not** search (e.g. `"attribute-receiver-calls"` like
+`ctx.svc.run()`). A non-empty
+`scope_excludes` means an empty/short result is **not** a guaranteed true
+negative — re-query at `"inferred"` (which searches those categories and returns
+`scope_excludes: []`) before concluding "nothing calls this."
+
+`execution_paths_from` returns a compact shape: `root`, a deduplicated `nodes`
+table (id + short_name + location, each node once), and `paths` as arrays of
+node-id strings ranked longest-first. Resolve a path id against `nodes`, not by
+re-reading each path element. `truncated`/`truncation_reason` report `edge-cap`
+(traversal stopped early) or `path-cap` (ranked output trimmed for size).
+
+## Workflow: orient, then navigate
+
+1. **Anchor.** `find_entity` by name (or `entity_at` for a file:line) to get the
+   entity and its `id`. For a code location you're about to dig into, prefer
+   `orientation_pack` — it returns the entity, its context, one-hop neighbors,
+   execution paths, attached issues, and index freshness in one deterministic
+   call, instead of hand-composing those queries.
+2. **Navigate.** Feed that `id` into `callers_of`, `neighborhood`,
+   `execution_paths_from`, or `summary`. Chain results' IDs to keep walking.
+
+## Gotchas (read before hunting for a subsystem)
+
+- **To find a package's subsystem, search the package NAME with `kind`.**
+  Subsystems are *named after* their dominant package (e.g. `mypkg`), so
+  `find_entity {"pattern":"subsystem"}` returns nothing. Search the package name
+  and pass `{"kind":"subsystem"}` to return only subsystem entities, then call
+  `subsystem_members`. (`find_entity` accepts an optional `kind` filter —
+  `"subsystem"`, `"function"`, `"class"`, `"module"`, …; omit it for no filter.)
+- **To go from an entity to its subsystem, use `subsystem_of`.**
+  `neighborhood` does **not** return the entity's subsystem. Call
+  `subsystem_of {"id": "<entity-id>"}` — it accepts any entity (a function/class
+  resolves through its containing module) and returns the subsystem plus the
+  module it resolved through. `subsystem_members` is the forward direction.
+- **`find_entity` is paginated** (~20/page, `next_cursor`); narrow the pattern
+  rather than paging if you can.
+
+## Launch
+
+`clarion serve --path <dir>` where `<dir>` contains `.clarion/clarion.db`
+(built by `clarion analyze <dir>`). In an MCP client the tools appear as
+`mcp__clarion__find_entity`, etc.
+
+Besides the tools, the server exposes a `clarion://context` **resource** — live
+entity/subsystem/finding counts and index freshness as JSON, a lightweight read
+when you only want the numbers (`project_status` is the fuller tool-based view).
diff --git a/crates/clarion-mcp/src/analyze_runs.rs b/crates/clarion-mcp/src/analyze_runs.rs
new file mode 100644
index 00000000..d29b89ab
--- /dev/null
+++ b/crates/clarion-mcp/src/analyze_runs.rs
@@ -0,0 +1,254 @@
+//! In-memory registry of `clarion analyze` subprocesses launched over MCP
+//! (`analyze_start` / `analyze_status` / `analyze_cancel`, clarion-7e0c21558a).
+//!
+//! Decomposition decision: the MCP owns the subprocess and the cancel kill +
+//! terminal write; the `analyze` CLI stays unaware it is being supervised (no
+//! signal handler, no cancel flag). On cancel the MCP SIGKILLs the run's
+//! process group — which reaches the plugin and its `pyright-langserver`
+//! grandchild, since neither detaches into a new session — then writes the
+//! run's terminal state directly. Discard-on-cancel is acceptable for a cancel.
+//!
+//! This bends the ADR-011 single-writer posture for exactly one narrow write
+//! (the guarded cancel UPDATE), and only after the analyze process — the
+//! normal writer — is dead, so there is no concurrent writer. Stale-`running`
+//! reconciliation for a crash of the *supervising* process is explicitly out of
+//! scope here; that is what the deferred `owner_pid`/`heartbeat_at` work
+//! (clarion-f9027d2187) closes.
+
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::process::Child;
+use std::process::Stdio;
+use std::sync::{Arc, Mutex};
+
+/// One supervised analyze subprocess.
+pub(crate) struct RunHandle {
+    /// The `clarion analyze` child. `try_wait`/`wait` reap it; held by value so
+    /// the registry owns the process.
+    pub child: Child,
+    /// Process-group id (== child pid; the child is spawned as a group leader)
+    /// so a single `killpg` reaches the plugin and pyright grandchildren.
+    pub pgid: i32,
+    /// ISO-8601 start time, for elapsed reporting.
+    pub started_at: String,
+    /// Where the run writes its structured progress snapshot.
+    pub progress_path: PathBuf,
+    /// Set by `analyze_cancel`; makes `analyze_status` report `cancelled` even
+    /// before the terminal DB write is observed.
+    pub cancelled: bool,
+}
+
+/// Shared map of run id → handle. A plain `std::sync::Mutex`: the critical
+/// sections are short (`try_wait`, a SIGKILL, a brief reap) and the tool
+/// surface is low-volume.
+pub(crate) type RunRegistry = Arc<Mutex<HashMap<String, RunHandle>>>;
+
+/// Spawn `clarion analyze` for `project_root` as a new process-group leader so
+/// the whole subtree (plugin + pyright) can be group-killed on cancel.
+///
+/// `program` is the launcher (`current_exe()` in production; a stub in tests).
+/// The run id and progress path are passed in so the caller can return the
+/// handle without racing the run's first DB write or progress write.
+pub(crate) fn spawn_analyze(
+    program: &std::path::Path,
+    project_root: &std::path::Path,
+    run_id: &str,
+    progress_path: &std::path::Path,
+    started_at: String,
+) -> std::io::Result<RunHandle> {
+    let mut command = std::process::Command::new(program);
+    command
+        .arg("analyze")
+        .arg(project_root)
+        .arg("--run-id")
+        .arg(run_id)
+        .arg("--progress-file")
+        .arg(progress_path)
+        // Isolate the child's stdio. When analyze_start is driven from the
+        // stdio MCP server, the child would otherwise inherit the server's
+        // stdout — and `clarion analyze` initializes tracing at `info`, so its
+        // non-framed progress bytes would interleave with the MCP JSON-RPC
+        // responses on the same stream and corrupt the client connection.
+        // Progress is reported via --progress-file, not stdout.
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        // 0 → the child becomes leader of a new group whose id is its own pid.
+        command.process_group(0);
+    }
+
+    let child = command.spawn()?;
+    // A pid always fits in i32 on the platforms we target; the group id is the
+    // child's pid because it was spawned as a new group leader.
+    #[allow(clippy::cast_possible_wrap)]
+    let pgid = child.id() as i32;
+    Ok(RunHandle {
+        child,
+        pgid,
+        started_at,
+        progress_path: progress_path.to_path_buf(),
+        cancelled: false,
+    })
+}
+
+/// SIGKILL the run's whole process group, then reap the analyze child.
+///
+/// On Unix this terminates the plugin and `pyright-langserver` grandchildren
+/// too (acceptance: "terminates child plugin/Pyright processes"). The orphaned
+/// grandchildren are re-parented to init and reaped there. Non-Unix falls back
+/// to killing just the analyze process.
+pub(crate) fn kill_run(handle: &mut RunHandle) {
+    #[cfg(unix)]
+    {
+        use nix::sys::signal::{Signal, killpg};
+        use nix::unistd::Pid;
+        // Negative-pid group kill; ignore ESRCH (already dead).
+        let _ = killpg(Pid::from_raw(handle.pgid), Signal::SIGKILL);
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = handle.child.kill();
+    }
+    // Reap the analyze child so it does not linger as a zombie. After SIGKILL
+    // this returns promptly.
+    let _ = handle.child.wait();
+    handle.cancelled = true;
+}
+
+/// Best-effort delete a finished run's progress file as its handle is evicted
+/// from the registry. A missing file is success — a run may exit before writing
+/// one. Keeps `.clarion/runs/*.progress.json` from accumulating across a
+/// long-lived `clarion serve` (clarion-7e0c21558a).
+pub(crate) fn reap_progress_file(path: &std::path::Path) {
+    match std::fs::remove_file(path) {
+        Ok(()) => {}
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+        Err(err) => {
+            tracing::debug!(
+                error = %err,
+                path = %path.display(),
+                "reap analyze progress file failed (left on disk)",
+            );
+        }
+    }
+}
+
+/// Evict every terminal handle from the registry and reap its progress file,
+/// returning the number removed. A still-running handle (`try_wait` ==
+/// `Ok(None)`) is retained; an exited or already-cancelled handle is dropped.
+///
+/// Called at the head of `analyze_start`: since every run begins with a start,
+/// sweeping there bounds the registry (and the `runs/` progress directory) to
+/// the live run plus the one about to spawn, however many analyses a
+/// long-lived `serve` runs over its lifetime (clarion-7e0c21558a).
+pub(crate) fn reap_terminal_runs(registry: &mut HashMap<String, RunHandle>) -> usize {
+    let dead: Vec<String> = registry
+        .iter_mut()
+        .filter_map(|(id, handle)| match handle.child.try_wait() {
+            // Still running — keep it.
+            Ok(None) => None,
+            // Exited, or `try_wait` errored (already reaped after a cancel) —
+            // evict it.
+            Ok(Some(_)) | Err(_) => Some(id.clone()),
+        })
+        .collect();
+    for id in &dead {
+        if let Some(handle) = registry.remove(id) {
+            reap_progress_file(&handle.progress_path);
+        }
+    }
+    dead.len()
+}
+
+/// Mark a cancelled run terminal in the database. The narrow single write this
+/// module owns (see the module note): a guarded UPDATE that only touches a row
+/// still in `running` — so a run that finished a beat before the cancel keeps
+/// its real terminal state, and a run cancelled before it recorded a `runs` row
+/// updates nothing. `stats.terminal_reason="cancelled"` is how `analyze_status`
+/// tells a cancel from an ordinary failure. Best-effort: the analyze writer is
+/// already dead, so there is no contention, but a failure here is logged and
+/// dropped (the in-memory registry still reports `cancelled`).
+pub(crate) fn mark_run_cancelled_in_db(db_path: &std::path::Path, run_id: &str, now: &str) {
+    let stats = serde_json::json!({
+        "terminal_reason": "cancelled",
+        "failure_reason": "cancelled via MCP analyze_cancel",
+    })
+    .to_string();
+    let conn = match rusqlite::Connection::open(db_path) {
+        Ok(conn) => conn,
+        Err(err) => {
+            tracing::warn!(error = %err, run_id, "cancel: open db for terminal write failed");
+            return;
+        }
+    };
+    if let Err(err) = clarion_storage::pragma::apply_write_pragmas(&conn) {
+        tracing::warn!(error = %err, run_id, "cancel: write pragmas failed");
+        return;
+    }
+    if let Err(err) = conn.execute(
+        "UPDATE runs SET status = 'failed', completed_at = ?1, stats = ?2 \
+         WHERE id = ?3 AND status = 'running'",
+        rusqlite::params![now, stats, run_id],
+    ) {
+        tracing::warn!(
+            error = %err,
+            run_id,
+            "failed to persist cancelled run terminal state (registry still reports cancelled)",
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The stdio MCP server speaks JSON-RPC framing on its own stdout. A
+    /// spawned `clarion analyze` that inherited that stdout and emitted `info`
+    /// tracing would interleave non-framed bytes onto the wire and corrupt the
+    /// client connection. The child's stdout must be isolated. We prove it by
+    /// having a stub record where its fd 1 actually points: `/dev/null` when
+    /// isolated, a `pipe:`/file path when inherited.
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn spawn_analyze_isolates_child_stdout_from_parent() {
+        use std::io::Write as _;
+        use std::os::unix::fs::PermissionsExt as _;
+
+        let dir = tempfile::tempdir().unwrap();
+        let script = dir.path().join("stub.sh");
+        let progress = dir.path().join("fd1.txt");
+        // spawn_analyze appends `analyze <root> --run-id <id> --progress-file
+        // <path>`, so the stub's $6 is the progress-file path.
+        let mut file = std::fs::File::create(&script).unwrap();
+        // Capture where the SHELL's fd 1 points via command substitution (so
+        // readlink's own redirected fd 1 doesn't taint the answer), then write
+        // it to "$6". `/dev/null` means the child stdout was isolated.
+        writeln!(
+            file,
+            "#!/bin/sh\nt=$(readlink /proc/$$/fd/1)\nprintf '%s' \"$t\" > \"$6\"\n"
+        )
+        .unwrap();
+        std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+        drop(file);
+
+        let mut handle = spawn_analyze(
+            &script,
+            dir.path(),
+            "run-x",
+            &progress,
+            "2026-05-30T00:00:00Z".to_owned(),
+        )
+        .expect("spawn stub");
+        handle.child.wait().expect("reap stub");
+
+        let where_fd1 = std::fs::read_to_string(&progress).expect("stub wrote fd1 target");
+        assert_eq!(
+            where_fd1.trim(),
+            "/dev/null",
+            "child stdout was not isolated from the parent: {where_fd1:?}"
+        );
+    }
+}
diff --git a/crates/clarion-mcp/src/config.rs b/crates/clarion-mcp/src/config.rs
index 11ab7e29..25ce5d81 100644
--- a/crates/clarion-mcp/src/config.rs
+++ b/crates/clarion-mcp/src/config.rs
@@ -1,5 +1,5 @@
-use std::fs;
 use std::path::Path;
+use std::{fs, net::SocketAddr};
 
 use serde::Deserialize;
 use thiserror::Error;
@@ -10,6 +10,7 @@ pub struct McpConfig {
     #[serde(alias = "llm_policy")]
     pub llm: LlmConfig,
     pub integrations: IntegrationsConfig,
+    pub serve: ServeConfig,
 }
 
 impl McpConfig {
@@ -25,6 +26,7 @@ impl McpConfig {
         if raw.trim().is_empty() {
             return Ok(Self::default());
         }
+        reject_llm_policy_alias_collision(raw)?;
         let config: Self =
             serde_norway::from_str(raw).map_err(|err| ConfigError::Yaml(err.to_string()))?;
         config.validate()?;
@@ -45,6 +47,7 @@ impl McpConfig {
                 code: "CLA-CONFIG-FILIGREE-ACTOR-BLANK",
             });
         }
+        self.serve.http.validate_loopback_trust()?;
         Ok(())
     }
 }
@@ -58,6 +61,8 @@ pub struct LlmConfig {
     pub session_token_ceiling: u64,
     pub model_id: String,
     pub openrouter: OpenRouterConfig,
+    pub codex_cli: CodexCliConfig,
+    pub claude_cli: ClaudeCliConfig,
     pub recording_fixture_path: Option<String>,
     pub max_inferred_edges_per_caller: u32,
     pub cache_max_age_days: u32,
@@ -73,6 +78,8 @@ impl Default for LlmConfig {
             session_token_ceiling: 1_000_000,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             openrouter: OpenRouterConfig::default(),
+            codex_cli: CodexCliConfig::default(),
+            claude_cli: ClaudeCliConfig::default(),
             recording_fixture_path: None,
             max_inferred_edges_per_caller: 8,
             cache_max_age_days: 180,
@@ -86,6 +93,10 @@ impl Default for LlmConfig {
 pub enum LlmProviderKind {
     #[serde(rename = "openrouter", alias = "open_router")]
     OpenRouter,
+    #[serde(rename = "codex_cli", alias = "codex")]
+    CodexCli,
+    #[serde(rename = "claude_cli", alias = "claude_code")]
+    ClaudeCli,
     Anthropic,
     Recording,
 }
@@ -118,18 +129,223 @@ pub struct OpenRouterAttributionConfig {
 impl Default for OpenRouterAttributionConfig {
     fn default() -> Self {
         Self {
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion".to_owned(),
         }
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(default)]
+pub struct CodexCliConfig {
+    pub executable: String,
+    pub model: Option<String>,
+    pub profile: Option<String>,
+    pub sandbox: CodexSandboxMode,
+    pub timeout_seconds: u64,
+}
+
+impl Default for CodexCliConfig {
+    fn default() -> Self {
+        Self {
+            executable: "codex".to_owned(),
+            model: None,
+            profile: None,
+            sandbox: CodexSandboxMode::ReadOnly,
+            timeout_seconds: 300,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum CodexSandboxMode {
+    ReadOnly,
+    WorkspaceWrite,
+    DangerFullAccess,
+}
+
+impl CodexSandboxMode {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::ReadOnly => "read-only",
+            Self::WorkspaceWrite => "workspace-write",
+            Self::DangerFullAccess => "danger-full-access",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(default)]
+pub struct ClaudeCliConfig {
+    pub executable: String,
+    pub model: Option<String>,
+    pub permission_mode: ClaudePermissionMode,
+    pub tools: Vec<String>,
+    pub timeout_seconds: u64,
+    pub max_turns: u32,
+    pub no_session_persistence: bool,
+    pub exclude_dynamic_system_prompt_sections: bool,
+}
+
+impl Default for ClaudeCliConfig {
+    fn default() -> Self {
+        Self {
+            executable: "claude".to_owned(),
+            model: None,
+            permission_mode: ClaudePermissionMode::Plan,
+            tools: Vec::new(),
+            timeout_seconds: 300,
+            max_turns: 2,
+            no_session_persistence: true,
+            exclude_dynamic_system_prompt_sections: true,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+pub enum ClaudePermissionMode {
+    #[serde(rename = "plan")]
+    Plan,
+    #[serde(rename = "default")]
+    Default,
+    #[serde(rename = "acceptEdits")]
+    AcceptEdits,
+    #[serde(rename = "bypassPermissions")]
+    BypassPermissions,
+}
+
+impl ClaudePermissionMode {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Plan => "plan",
+            Self::Default => "default",
+            Self::AcceptEdits => "acceptEdits",
+            Self::BypassPermissions => "bypassPermissions",
+        }
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Default, Deserialize)]
 #[serde(default)]
 pub struct IntegrationsConfig {
     pub filigree: FiligreeConfig,
 }
 
+#[derive(Debug, Clone, PartialEq, Default, Deserialize)]
+#[serde(default)]
+pub struct ServeConfig {
+    pub http: HttpReadConfig,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(default)]
+pub struct HttpReadConfig {
+    pub enabled: bool,
+    #[serde(deserialize_with = "deserialize_socket_addr")]
+    pub bind: SocketAddr,
+    pub allow_non_loopback: bool,
+    /// Name of the env var holding the inbound bearer token. When the env
+    /// var is set, every `/api/v1/files`-family request must carry
+    /// `Authorization: Bearer <that-value>`; the capabilities probe is
+    /// always unauthenticated. When the env var is unset on a loopback
+    /// bind, the surface stays unauthenticated (the v0.1 trust model).
+    /// When the env var is unset on a non-loopback bind, `clarion serve`
+    /// refuses to start (`CLA-CONFIG-HTTP-NO-AUTH`). Default
+    /// `CLARION_LOOM_TOKEN` matches Filigree's pinned client default.
+    pub token_env: String,
+    /// Optional env var holding the Loom component identity HMAC secret.
+    /// When configured, `clarion serve` refuses to start unless the env var
+    /// exists and protected HTTP read routes require
+    /// `X-Loom-Component: clarion:<hmac>`.
+    pub identity_token_env: Option<String>,
+}
+
+impl Default for HttpReadConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            bind: SocketAddr::from(([127, 0, 0, 1], 9111)),
+            allow_non_loopback: false,
+            token_env: "CLARION_LOOM_TOKEN".to_owned(),
+            identity_token_env: None,
+        }
+    }
+}
+
+impl HttpReadConfig {
+    pub fn validate_loopback_trust(&self) -> Result<(), ConfigError> {
+        if self.enabled && !self.allow_non_loopback && !self.is_loopback_bind() {
+            return Err(ConfigError::NonLoopbackHttpBind {
+                code: "CLA-CONFIG-HTTP-NON-LOOPBACK",
+                bind: self.bind,
+            });
+        }
+        Ok(())
+    }
+
+    /// Refuse to start a non-loopback HTTP read API when the inbound bearer
+    /// token env var is unset. Loopback binds with the env var unset stay
+    /// unauthenticated (v0.1 trust matrix); the failure case is the explicit
+    /// `allow_non_loopback: true` opt-in plus an unset `token_env`.
+    pub fn validate_auth_trust<F>(&self, env_lookup: F) -> Result<(), ConfigError>
+    where
+        F: Fn(&str) -> Option<String>,
+    {
+        if !self.enabled {
+            return Ok(());
+        }
+        let has_identity_secret = match self.identity_token_env.as_deref() {
+            Some(env_var) => {
+                let has_secret = env_lookup(env_var)
+                    .as_deref()
+                    .is_some_and(|value| !value.trim().is_empty());
+                if !has_secret {
+                    return Err(ConfigError::MissingHttpIdentitySecret {
+                        code: "CLA-CONFIG-HTTP-IDENTITY-MISSING",
+                        token_env: env_var.to_owned(),
+                    });
+                }
+                true
+            }
+            None => false,
+        };
+        if self.is_loopback_bind() {
+            return Ok(());
+        }
+        if has_identity_secret {
+            return Ok(());
+        }
+        let has_token = env_lookup(&self.token_env)
+            .as_deref()
+            .is_some_and(|value| !value.trim().is_empty());
+        if has_token {
+            return Ok(());
+        }
+        Err(ConfigError::NonLoopbackHttpNoAuth {
+            code: "CLA-CONFIG-HTTP-NO-AUTH",
+            bind: self.bind,
+            token_env: self.token_env.clone(),
+        })
+    }
+
+    #[must_use]
+    pub fn is_loopback_bind(&self) -> bool {
+        self.bind.ip().is_loopback()
+    }
+}
+
+fn deserialize_socket_addr<'de, D>(deserializer: D) -> Result<SocketAddr, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let raw = String::deserialize(deserializer)?;
+    raw.parse()
+        .map_err(|err| serde::de::Error::custom(format!("invalid serve.http.bind {raw:?}: {err}")))
+}
+
 #[derive(Debug, Clone, PartialEq, Deserialize)]
 #[serde(default)]
 pub struct FiligreeConfig {
@@ -138,6 +354,21 @@ pub struct FiligreeConfig {
     pub actor: String,
     pub token_env: String,
     pub timeout_seconds: u64,
+    /// Whether `clarion analyze` POSTs its findings to Filigree's
+    /// `POST /api/v1/scan-results` intake on completion (WP9-B,
+    /// REQ-FINDING-03). Emission is a one-way Clarion→Filigree data egress, so
+    /// it is its own explicit opt-in: it requires both `enabled` *and* this
+    /// flag, and **both default `false`**. Enabling the integration for the
+    /// read side (`issues_for` reverse-lookup) therefore does not silently
+    /// start outbound emission — the operator opts into the write direction
+    /// separately by setting `emit_findings: true`.
+    pub emit_findings: bool,
+    /// Age threshold (days) for `clarion analyze --prune-unseen` (REQ-FINDING-06):
+    /// findings Filigree has marked `unseen_in_latest` and that are older than
+    /// this are soft-archived (`fixed`) by the retention sweep. Default 30.
+    /// Only consulted when `--prune-unseen` is passed; the sweep itself is
+    /// opt-in per invocation, not on by default.
+    pub prune_unseen_days: u32,
 }
 
 impl Default for FiligreeConfig {
@@ -148,6 +379,8 @@ impl Default for FiligreeConfig {
             actor: "clarion-mcp".to_owned(),
             token_env: "FILIGREE_API_TOKEN".to_owned(),
             timeout_seconds: 5,
+            emit_findings: false,
+            prune_unseen_days: 30,
         }
     }
 }
@@ -157,6 +390,8 @@ pub enum ProviderSelection {
     Disabled,
     Recording,
     OpenRouter { api_key_env: String },
+    CodexCli,
+    ClaudeCli,
 }
 
 pub fn select_provider_with_env<F>(
@@ -193,6 +428,20 @@ where
                 api_key_env: env_var,
             })
         }
+        LlmProviderKind::CodexCli => {
+            let live_env_opt_in = env_lookup("CLARION_LLM_LIVE").as_deref() == Some("1");
+            if !config.llm.allow_live_provider && !live_env_opt_in {
+                return Ok(ProviderSelection::Disabled);
+            }
+            Ok(ProviderSelection::CodexCli)
+        }
+        LlmProviderKind::ClaudeCli => {
+            let live_env_opt_in = env_lookup("CLARION_LLM_LIVE").as_deref() == Some("1");
+            if !config.llm.allow_live_provider && !live_env_opt_in {
+                return Ok(ProviderSelection::Disabled);
+            }
+            Ok(ProviderSelection::ClaudeCli)
+        }
     }
 }
 
@@ -218,6 +467,67 @@ pub enum ConfigError {
 
     #[error("{code}: integrations.filigree.actor must not be blank when Filigree is enabled")]
     InvalidFiligreeActor { code: &'static str },
+
+    #[error(
+        "{code}: serve.http.bind {bind} exposes the unauthenticated non-loopback Clarion HTTP read API; \
+         bind to loopback (127.0.0.1 or ::1) or set serve.http.allow_non_loopback: true only on a trusted network"
+    )]
+    NonLoopbackHttpBind {
+        code: &'static str,
+        bind: SocketAddr,
+    },
+
+    #[error(
+        "{code}: serve.http.bind {bind} is non-loopback and serve.http.allow_non_loopback is true, \
+         but the inbound auth env var ${token_env} is unset; refusing to start an unauthenticated \
+         HTTP read API on a routable interface. Set ${token_env} to a non-empty bearer token, \
+         or bind to loopback."
+    )]
+    NonLoopbackHttpNoAuth {
+        code: &'static str,
+        bind: SocketAddr,
+        token_env: String,
+    },
+
+    #[error(
+        "{code}: serve.http.identity_token_env names ${token_env}, but that env var is unset; \
+         refusing to start an HTTP read API with incomplete Loom component identity configuration."
+    )]
+    MissingHttpIdentitySecret {
+        code: &'static str,
+        token_env: String,
+    },
+
+    #[error(
+        "{code}: clarion.yaml contains both `llm` and `llm_policy` top-level keys; \
+         `llm_policy` is a serde alias for `llm` and serde silently discards one. \
+         Pick one and remove the other."
+    )]
+    AmbiguousLlmKey { code: &'static str },
+}
+
+/// Reject configs that name both `llm` and `llm_policy` at the top level.
+/// They alias the same field; serde-norway silently picks one and discards
+/// the other, which is the classic copy-paste-migration pitfall. Detecting
+/// the collision pre-parse turns a silent override into a typed error.
+fn reject_llm_policy_alias_collision(raw: &str) -> Result<(), ConfigError> {
+    let value: serde_norway::Value = match serde_norway::from_str(raw) {
+        Ok(value) => value,
+        // If the YAML doesn't even parse as a generic Value, let the typed
+        // parse below produce the canonical Yaml error.
+        Err(_) => return Ok(()),
+    };
+    let Some(mapping) = value.as_mapping() else {
+        return Ok(());
+    };
+    let has_llm = mapping.contains_key("llm");
+    let has_llm_policy = mapping.contains_key("llm_policy");
+    if has_llm && has_llm_policy {
+        return Err(ConfigError::AmbiguousLlmKey {
+            code: "CLA-CONFIG-AMBIGUOUS-LLM-KEY",
+        });
+    }
+    Ok(())
 }
 
 #[cfg(test)]
@@ -275,6 +585,35 @@ integrations:
         assert_eq!(cfg.integrations.filigree.timeout_seconds, 2);
     }
 
+    #[test]
+    fn filigree_emission_is_opt_in_independent_of_enabled() {
+        // clarion-a26de2f368: outbound finding emission is a one-way egress and
+        // must not piggyback on enabling Filigree for read enrichment. Both
+        // knobs default false so flipping `enabled` for `issues_for` never
+        // silently starts POSTing findings.
+        let defaults = FiligreeConfig::default();
+        assert!(!defaults.enabled);
+        assert!(
+            !defaults.emit_findings,
+            "emit_findings must default false (explicit write opt-in)"
+        );
+
+        // Turning on the read side alone leaves emission off.
+        let read_only = McpConfig::from_yaml_str(
+            r"
+integrations:
+  filigree:
+    enabled: true
+",
+        )
+        .expect("parse config");
+        assert!(read_only.integrations.filigree.enabled);
+        assert!(
+            !read_only.integrations.filigree.emit_findings,
+            "enabling Filigree for reads must not turn on outbound emission"
+        );
+    }
+
     #[test]
     fn accepts_llm_policy_alias_for_operator_config() {
         let cfg = McpConfig::from_yaml_str(
@@ -292,6 +631,32 @@ llm_policy:
         assert_eq!(cfg.llm.model_id, "openai/gpt-4o-mini");
     }
 
+    #[test]
+    fn rejects_both_llm_and_llm_policy_keys_present_together() {
+        // Realistic migration-doc copy-paste case: operator copies the new
+        // `llm_policy:` block but forgets to delete the old `llm:` block.
+        // Serde-norway would silently pick one and discard the other.
+        let err = McpConfig::from_yaml_str(
+            r"
+llm:
+  enabled: false
+  provider: recording
+llm_policy:
+  enabled: true
+  provider: openrouter
+  model_id: openai/gpt-4o-mini
+",
+        )
+        .expect_err("ambiguous llm key must be rejected");
+
+        match err {
+            ConfigError::AmbiguousLlmKey { code } => {
+                assert_eq!(code, "CLA-CONFIG-AMBIGUOUS-LLM-KEY");
+            }
+            other => panic!("expected AmbiguousLlmKey error, got: {other:?}"),
+        }
+    }
+
     #[test]
     fn api_key_alone_does_not_select_live_provider() {
         let cfg = McpConfig {
@@ -301,6 +666,7 @@ llm_policy:
                 ..LlmConfig::default()
             },
             integrations: IntegrationsConfig::default(),
+            serve: ServeConfig::default(),
         };
 
         let selected = select_provider_with_env(&cfg, |name| {
@@ -321,6 +687,7 @@ llm_policy:
                 ..LlmConfig::default()
             },
             integrations: IntegrationsConfig::default(),
+            serve: ServeConfig::default(),
         };
 
         let missing = select_provider_with_env(&cfg, |_| None).expect_err("missing key");
@@ -342,6 +709,265 @@ llm_policy:
         );
     }
 
+    #[test]
+    fn codex_cli_provider_requires_live_opt_in_but_no_api_key() {
+        let cfg = McpConfig::from_yaml_str(
+            r"
+llm_policy:
+  enabled: true
+  provider: codex_cli
+  allow_live_provider: true
+  model_id: codex-cli-default
+  codex_cli:
+    executable: /tmp/fake-codex
+    model: gpt-5.5
+    profile: clarion
+    sandbox: read-only
+    timeout_seconds: 30
+",
+        )
+        .expect("parse Codex CLI provider config");
+
+        assert_eq!(cfg.llm.provider, LlmProviderKind::CodexCli);
+        assert_eq!(cfg.llm.model_id, "codex-cli-default");
+        assert_eq!(cfg.llm.codex_cli.executable, "/tmp/fake-codex");
+        assert_eq!(cfg.llm.codex_cli.model.as_deref(), Some("gpt-5.5"));
+        assert_eq!(cfg.llm.codex_cli.profile.as_deref(), Some("clarion"));
+        assert_eq!(cfg.llm.codex_cli.sandbox, CodexSandboxMode::ReadOnly);
+        assert_eq!(cfg.llm.codex_cli.timeout_seconds, 30);
+
+        let selected = select_provider_with_env(&cfg, |_| None).expect("provider selection");
+        assert_eq!(selected, ProviderSelection::CodexCli);
+    }
+
+    #[test]
+    fn codex_cli_provider_stays_disabled_without_live_opt_in() {
+        let cfg = McpConfig {
+            llm: LlmConfig {
+                enabled: true,
+                provider: LlmProviderKind::CodexCli,
+                ..LlmConfig::default()
+            },
+            integrations: IntegrationsConfig::default(),
+            serve: ServeConfig::default(),
+        };
+
+        let selected = select_provider_with_env(&cfg, |_| None).expect("provider selection");
+        assert_eq!(selected, ProviderSelection::Disabled);
+
+        let env_selected = select_provider_with_env(&cfg, |name| {
+            (name == "CLARION_LLM_LIVE").then(|| "1".to_owned())
+        })
+        .expect("provider selection via env opt-in");
+        assert_eq!(env_selected, ProviderSelection::CodexCli);
+    }
+
+    #[test]
+    fn claude_cli_provider_requires_live_opt_in_but_no_api_key() {
+        let cfg = McpConfig::from_yaml_str(
+            r#"
+llm_policy:
+  enabled: true
+  provider: claude_cli
+  allow_live_provider: true
+  model_id: claude-code-default
+  claude_cli:
+    executable: /tmp/fake-claude
+    model: claude-sonnet-4-6
+    permission_mode: plan
+    tools: ["Read", "Glob", "Grep"]
+    timeout_seconds: 45
+    max_turns: 2
+    no_session_persistence: true
+"#,
+        )
+        .expect("parse Claude CLI provider config");
+
+        assert_eq!(cfg.llm.provider, LlmProviderKind::ClaudeCli);
+        assert_eq!(cfg.llm.model_id, "claude-code-default");
+        assert_eq!(cfg.llm.claude_cli.executable, "/tmp/fake-claude");
+        assert_eq!(
+            cfg.llm.claude_cli.model.as_deref(),
+            Some("claude-sonnet-4-6")
+        );
+        assert_eq!(
+            cfg.llm.claude_cli.permission_mode,
+            ClaudePermissionMode::Plan
+        );
+        assert_eq!(cfg.llm.claude_cli.tools, vec!["Read", "Glob", "Grep"]);
+        assert_eq!(cfg.llm.claude_cli.timeout_seconds, 45);
+        assert_eq!(cfg.llm.claude_cli.max_turns, 2);
+        assert!(cfg.llm.claude_cli.no_session_persistence);
+
+        let selected = select_provider_with_env(&cfg, |_| None).expect("provider selection");
+        assert_eq!(selected, ProviderSelection::ClaudeCli);
+    }
+
+    #[test]
+    fn claude_cli_provider_stays_disabled_without_live_opt_in() {
+        let cfg = McpConfig {
+            llm: LlmConfig {
+                enabled: true,
+                provider: LlmProviderKind::ClaudeCli,
+                ..LlmConfig::default()
+            },
+            integrations: IntegrationsConfig::default(),
+            serve: ServeConfig::default(),
+        };
+
+        let selected = select_provider_with_env(&cfg, |_| None).expect("provider selection");
+        assert_eq!(selected, ProviderSelection::Disabled);
+
+        let env_selected = select_provider_with_env(&cfg, |name| {
+            (name == "CLARION_LLM_LIVE").then(|| "1".to_owned())
+        })
+        .expect("provider selection via env opt-in");
+        assert_eq!(env_selected, ProviderSelection::ClaudeCli);
+    }
+
+    #[test]
+    fn http_bind_is_parsed_when_config_loads() {
+        let cfg = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "127.0.0.1:0"
+"#,
+        )
+        .expect("parse HTTP bind");
+
+        assert_eq!(cfg.serve.http.bind, SocketAddr::from(([127, 0, 0, 1], 0)));
+    }
+
+    #[test]
+    fn http_allow_non_loopback_defaults_false() {
+        assert!(!McpConfig::default().serve.http.allow_non_loopback);
+    }
+
+    #[test]
+    fn http_allow_non_loopback_is_parsed_when_config_loads() {
+        let cfg = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "127.0.0.1:0"
+    allow_non_loopback: true
+"#,
+        )
+        .expect("parse HTTP allow_non_loopback");
+
+        assert!(cfg.serve.http.allow_non_loopback);
+    }
+
+    #[test]
+    fn http_identity_token_env_is_parsed_when_config_loads() {
+        let cfg = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "127.0.0.1:0"
+    identity_token_env: CLARION_TEST_IDENTITY
+"#,
+        )
+        .expect("parse HTTP identity_token_env");
+
+        assert_eq!(
+            cfg.serve.http.identity_token_env.as_deref(),
+            Some("CLARION_TEST_IDENTITY")
+        );
+    }
+
+    #[test]
+    fn enabled_non_loopback_http_bind_requires_allow_non_loopback() {
+        let err = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "0.0.0.0:0"
+"#,
+        )
+        .expect_err("enabled wildcard HTTP bind should require explicit opt-in");
+
+        let message = err.to_string();
+        assert!(
+            message.contains("unauthenticated non-loopback"),
+            "error should explain the unauthenticated non-loopback risk: {message}"
+        );
+        assert!(
+            message.contains("allow_non_loopback"),
+            "error should name the explicit opt-in: {message}"
+        );
+    }
+
+    #[test]
+    fn enabled_lan_http_bind_requires_allow_non_loopback() {
+        let err = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "192.168.1.10:0"
+"#,
+        )
+        .expect_err("enabled LAN HTTP bind should require explicit opt-in");
+
+        assert!(matches!(err, ConfigError::NonLoopbackHttpBind { .. }));
+    }
+
+    #[test]
+    fn enabled_ipv6_loopback_http_bind_is_allowed_by_default() {
+        let cfg = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "[::1]:0"
+"#,
+        )
+        .expect("IPv6 loopback HTTP bind should not require non-loopback opt-in");
+
+        assert!(!cfg.serve.http.allow_non_loopback);
+        assert!(cfg.serve.http.is_loopback_bind());
+    }
+
+    #[test]
+    fn enabled_non_loopback_http_bind_allows_explicit_opt_in() {
+        let cfg = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "0.0.0.0:0"
+    allow_non_loopback: true
+"#,
+        )
+        .expect("explicit opt-in should allow non-loopback HTTP bind");
+
+        assert!(cfg.serve.http.allow_non_loopback);
+    }
+
+    #[test]
+    fn invalid_http_bind_fails_config_load() {
+        let err = McpConfig::from_yaml_str(
+            r#"
+serve:
+  http:
+    enabled: true
+    bind: "not-a-socket"
+"#,
+        )
+        .expect_err("invalid bind should fail");
+
+        assert!(
+            err.to_string().contains("invalid serve.http.bind"),
+            "unexpected error: {err}"
+        );
+    }
+
     #[test]
     fn old_anthropic_provider_shape_reports_deprecated_provider() {
         let err = McpConfig::from_yaml_str(
diff --git a/crates/clarion-mcp/src/filigree.rs b/crates/clarion-mcp/src/filigree.rs
index a246072e..3a5b3691 100644
--- a/crates/clarion-mcp/src/filigree.rs
+++ b/crates/clarion-mcp/src/filigree.rs
@@ -2,16 +2,32 @@
 
 use std::time::Duration;
 
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 use thiserror::Error;
 
 use crate::config::FiligreeConfig;
+use crate::scan_results::{
+    CleanStaleRequest, CleanStaleResponse, ScanResultsRequest, ScanResultsResponse,
+    clean_stale_url, parse_clean_stale_response, parse_scan_results_response, scan_results_url,
+};
 
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
 pub struct EntityAssociationsResponse {
     pub associations: Vec<EntityAssociation>,
 }
 
+/// The subset of a Filigree issue Clarion surfaces alongside an
+/// entity-association match: enough to render the match without an agent
+/// having to call back into Filigree. Sourced from `GET /api/loom/issues/{id}`.
+/// Unknown fields in the response are ignored, so Filigree can grow the route
+/// without breaking this read.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+pub struct IssueDetail {
+    pub title: String,
+    pub status: String,
+    pub priority: i64,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
 pub struct EntityAssociation {
     pub issue_id: String,
@@ -38,6 +54,18 @@ pub enum FiligreeClientError {
     #[error("Filigree returned HTTP {status}: {body}")]
     HttpStatus { status: u16, body: String },
 
+    #[error("POST Filigree scan-results: {0}")]
+    ScanResultsRequest(#[source] reqwest::Error),
+
+    #[error("invalid Filigree scan-results response: {0}")]
+    InvalidScanResultsResponse(#[source] serde_json::Error),
+
+    #[error("POST Filigree clean-stale: {0}")]
+    CleanStaleRequest(#[source] reqwest::Error),
+
+    #[error("invalid Filigree clean-stale response: {0}")]
+    InvalidCleanStaleResponse(#[source] serde_json::Error),
+
     #[error(transparent)]
     Contract(#[from] FiligreeContractError),
 }
@@ -47,6 +75,17 @@ pub trait FiligreeLookup: Send + Sync {
         &self,
         entity_id: &str,
     ) -> Result<EntityAssociationsResponse, FiligreeClientError>;
+
+    /// Fetch an issue's title/status/priority to enrich an association match.
+    /// Returns `Ok(None)` when the issue (or the detail route itself) is
+    /// unavailable — a `404` — so callers degrade to issue-id-only rather than
+    /// failing the whole `issues_for` call, per the enrich-only federation
+    /// axiom. The default reports the route as unavailable; the HTTP client
+    /// overrides it. A transport / non-404 HTTP failure is surfaced as `Err`
+    /// so the caller can stop hammering a down endpoint.
+    fn issue_detail(&self, _issue_id: &str) -> Result<Option<IssueDetail>, FiligreeClientError> {
+        Ok(None)
+    }
 }
 
 #[derive(Debug, Clone)]
@@ -80,6 +119,92 @@ impl FiligreeHttpClient {
             client,
         }))
     }
+
+    /// POST a scan-results batch to Filigree's native intake (WP9-B,
+    /// REQ-FINDING-03). One-way Clarion→Filigree push; the caller is expected to
+    /// inspect [`ScanResultsResponse::warnings`] (severity coercion, unknown
+    /// `scan_run_id`, etc.) rather than just the counts.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`FiligreeClientError::ScanResultsRequest`] on transport failure,
+    /// [`FiligreeClientError::HttpStatus`] on a non-success response (e.g. a
+    /// `400 VALIDATION` for a malformed batch), or
+    /// [`FiligreeClientError::InvalidScanResultsResponse`] when the body is not
+    /// the expected shape.
+    pub fn post_scan_results(
+        &self,
+        request: &ScanResultsRequest,
+    ) -> Result<ScanResultsResponse, FiligreeClientError> {
+        let mut http_request = self
+            .client
+            .post(scan_results_url(&self.base_url))
+            .header("accept", "application/json")
+            .json(request);
+        if !self.actor.trim().is_empty() {
+            http_request = http_request.header("x-filigree-actor", self.actor.as_str());
+        }
+        if let Some(token) = &self.token {
+            http_request = http_request.bearer_auth(token);
+        }
+        let response = http_request
+            .send()
+            .map_err(FiligreeClientError::ScanResultsRequest)?;
+        let status = response.status();
+        let body = response
+            .text()
+            .map_err(FiligreeClientError::ScanResultsRequest)?;
+        if !status.is_success() {
+            return Err(FiligreeClientError::HttpStatus {
+                status: status.as_u16(),
+                body,
+            });
+        }
+        parse_scan_results_response(&body).map_err(FiligreeClientError::InvalidScanResultsResponse)
+    }
+
+    /// POST a retention sweep to Filigree's `clean-stale` route (REQ-FINDING-06,
+    /// `--prune-unseen`). One-way Clarion→Filigree call; Filigree soft-archives
+    /// its own `unseen_in_latest` findings for the given `scan_source`. The
+    /// `scan_source` scoping is enforced server-side, so this can only sweep
+    /// Clarion's findings.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`FiligreeClientError::CleanStaleRequest`] on transport failure,
+    /// [`FiligreeClientError::HttpStatus`] on a non-success response, or
+    /// [`FiligreeClientError::InvalidCleanStaleResponse`] when the body is not
+    /// the expected shape.
+    pub fn post_clean_stale(
+        &self,
+        request: &CleanStaleRequest,
+    ) -> Result<CleanStaleResponse, FiligreeClientError> {
+        let mut http_request = self
+            .client
+            .post(clean_stale_url(&self.base_url))
+            .header("accept", "application/json")
+            .json(request);
+        if !self.actor.trim().is_empty() {
+            http_request = http_request.header("x-filigree-actor", self.actor.as_str());
+        }
+        if let Some(token) = &self.token {
+            http_request = http_request.bearer_auth(token);
+        }
+        let response = http_request
+            .send()
+            .map_err(FiligreeClientError::CleanStaleRequest)?;
+        let status = response.status();
+        let body = response
+            .text()
+            .map_err(FiligreeClientError::CleanStaleRequest)?;
+        if !status.is_success() {
+            return Err(FiligreeClientError::HttpStatus {
+                status: status.as_u16(),
+                body,
+            });
+        }
+        parse_clean_stale_response(&body).map_err(FiligreeClientError::InvalidCleanStaleResponse)
+    }
 }
 
 impl FiligreeLookup for FiligreeHttpClient {
@@ -108,6 +233,36 @@ impl FiligreeLookup for FiligreeHttpClient {
         }
         parse_entity_associations_response(&body).map_err(FiligreeClientError::from)
     }
+
+    fn issue_detail(&self, issue_id: &str) -> Result<Option<IssueDetail>, FiligreeClientError> {
+        let mut request = self
+            .client
+            .get(issue_detail_url(&self.base_url, issue_id))
+            .header("accept", "application/json");
+        if !self.actor.trim().is_empty() {
+            request = request.header("x-filigree-actor", self.actor.as_str());
+        }
+        if let Some(token) = &self.token {
+            request = request.bearer_auth(token);
+        }
+        let response = request.send().map_err(FiligreeClientError::Request)?;
+        let status = response.status();
+        // A 404 means the issue (or the whole detail route) is absent — the
+        // enrich-only degrade signal, not an error.
+        if status == reqwest::StatusCode::NOT_FOUND {
+            return Ok(None);
+        }
+        let body = response.text().map_err(FiligreeClientError::Request)?;
+        if !status.is_success() {
+            return Err(FiligreeClientError::HttpStatus {
+                status: status.as_u16(),
+                body,
+            });
+        }
+        parse_issue_detail_response(&body)
+            .map(Some)
+            .map_err(FiligreeClientError::from)
+    }
 }
 
 pub fn parse_entity_associations_response(
@@ -116,6 +271,18 @@ pub fn parse_entity_associations_response(
     serde_json::from_str(body).map_err(FiligreeContractError::from)
 }
 
+pub fn parse_issue_detail_response(body: &str) -> Result<IssueDetail, FiligreeContractError> {
+    serde_json::from_str(body).map_err(FiligreeContractError::from)
+}
+
+pub fn issue_detail_url(base_url: &str, issue_id: &str) -> String {
+    format!(
+        "{}/api/loom/issues/{}",
+        base_url.trim_end_matches('/'),
+        percent_encode_query_value(issue_id)
+    )
+}
+
 pub fn entity_associations_url(base_url: &str, entity_id: &str) -> String {
     format!(
         "{}/api/entity-associations?entity_id={}",
@@ -221,6 +388,8 @@ mod tests {
             actor: "clarion-test".to_owned(),
             token_env: "TEST_FILIGREE_TOKEN".to_owned(),
             timeout_seconds: 1,
+            emit_findings: true,
+            prune_unseen_days: 30,
         };
         let client = FiligreeHttpClient::from_config(&config, |name| {
             (name == "TEST_FILIGREE_TOKEN").then(|| "secret-token".to_owned())
@@ -235,4 +404,226 @@ mod tests {
         assert_eq!(response.associations[0].issue_id, "filigree-1234567890");
         handle.join().expect("server thread");
     }
+
+    #[test]
+    fn parses_issue_detail_response_shape() {
+        let parsed = parse_issue_detail_response(
+            r#"{
+                "issue_id": "clarion-51a2868c86",
+                "title": "issues_for: enrich matches",
+                "status": "proposed",
+                "status_category": "open",
+                "priority": 3,
+                "type": "feature"
+            }"#,
+        )
+        .expect("parse issue detail");
+        assert_eq!(parsed.title, "issues_for: enrich matches");
+        assert_eq!(parsed.status, "proposed");
+        assert_eq!(parsed.priority, 3);
+    }
+
+    #[test]
+    fn builds_issue_detail_url_with_encoded_id() {
+        let url = issue_detail_url("http://127.0.0.1:8542/", "clarion-51a2868c86");
+        assert_eq!(
+            url,
+            "http://127.0.0.1:8542/api/loom/issues/clarion-51a2868c86"
+        );
+    }
+
+    #[test]
+    fn issue_detail_http_client_parses_200() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
+        let addr = listener.local_addr().expect("local addr");
+        let handle = std::thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("accept request");
+            let mut request = [0_u8; 4096];
+            let read = stream.read(&mut request).expect("read request");
+            let request = String::from_utf8_lossy(&request[..read]);
+            assert!(request.contains("GET /api/loom/issues/clarion-51a2868c86 HTTP/1.1"));
+
+            let body = r#"{"issue_id":"clarion-51a2868c86","title":"enrich","status":"proposed","priority":3}"#;
+            write!(
+                stream,
+                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                body.len(),
+                body
+            )
+            .expect("write response");
+        });
+        let client = detail_test_client(addr);
+        let detail = client
+            .issue_detail("clarion-51a2868c86")
+            .expect("issue detail request")
+            .expect("issue present");
+        assert_eq!(detail.title, "enrich");
+        assert_eq!(detail.status, "proposed");
+        assert_eq!(detail.priority, 3);
+        handle.join().expect("server thread");
+    }
+
+    #[test]
+    fn issue_detail_http_client_maps_404_to_none() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
+        let addr = listener.local_addr().expect("local addr");
+        let handle = std::thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("accept request");
+            let mut request = [0_u8; 4096];
+            let _ = stream.read(&mut request).expect("read request");
+            let body = r#"{"error":"Not Found","code":"NOT_FOUND"}"#;
+            write!(
+                stream,
+                "HTTP/1.1 404 Not Found\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                body.len(),
+                body
+            )
+            .expect("write response");
+        });
+        let client = detail_test_client(addr);
+        let detail = client
+            .issue_detail("clarion-missing")
+            .expect("404 is Ok(None), not an error");
+        assert!(detail.is_none(), "404 degrades to None: {detail:?}");
+        handle.join().expect("server thread");
+    }
+
+    #[test]
+    fn post_scan_results_sends_batch_and_parses_response() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
+        let addr = listener.local_addr().expect("local addr");
+        let handle = std::thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("accept request");
+            let mut request = [0_u8; 8192];
+            let read = stream.read(&mut request).expect("read request");
+            let request = String::from_utf8_lossy(&request[..read]);
+            assert!(
+                request.contains("POST /api/v1/scan-results HTTP/1.1"),
+                "request line: {request}"
+            );
+            assert!(request.contains("x-filigree-actor: clarion-test"));
+            assert!(request.contains("authorization: Bearer secret-token"));
+            // The wire body carries the mapped severity, not the internal one.
+            assert!(
+                request.contains("\"scan_source\":\"clarion\""),
+                "body: {request}"
+            );
+            assert!(
+                request.contains("\"severity\":\"medium\""),
+                "body: {request}"
+            );
+            assert!(
+                request.contains("\"internal_severity\":\"WARN\""),
+                "body: {request}"
+            );
+
+            let body = r#"{"files_created":1,"files_updated":0,"findings_created":1,"findings_updated":0,"new_finding_ids":["clarion-sf-abc"],"observations_created":0,"observations_failed":0,"warnings":["Scan run run-1 status not updated to 'completed': not found"]}"#;
+            write!(
+                stream,
+                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                body.len(),
+                body
+            )
+            .expect("write response");
+        });
+        let config = FiligreeConfig {
+            enabled: true,
+            base_url: format!("http://{addr}"),
+            actor: "clarion-test".to_owned(),
+            token_env: "TEST_FILIGREE_TOKEN".to_owned(),
+            timeout_seconds: 1,
+            emit_findings: true,
+            prune_unseen_days: 30,
+        };
+        let client = FiligreeHttpClient::from_config(&config, |name| {
+            (name == "TEST_FILIGREE_TOKEN").then(|| "secret-token".to_owned())
+        })
+        .expect("build client")
+        .expect("enabled client");
+
+        let row = clarion_storage::FindingForEmitRow {
+            id: "core:finding:run-1:circular".to_owned(),
+            rule_id: "CLA-PY-STRUCTURE-001".to_owned(),
+            kind: "defect".to_owned(),
+            severity: "WARN".to_owned(),
+            confidence: Some(0.9),
+            confidence_basis: None,
+            message: "Circular import".to_owned(),
+            entity_id: "python:class:auth.tokens::TokenManager".to_owned(),
+            related_entities_json: "[]".to_owned(),
+            supports_json: "[]".to_owned(),
+            supported_by_json: "[]".to_owned(),
+            source_file_path: Some("src/auth/tokens.py".to_owned()),
+            source_line_start: Some(12),
+            source_line_end: Some(12),
+        };
+        let batch = crate::scan_results::prepare_batch(
+            &[row],
+            &crate::scan_results::EmitOptions {
+                scan_run_id: Some("run-1".to_owned()),
+                mark_unseen: true,
+                complete_scan_run: true,
+            },
+        );
+
+        let response = client
+            .post_scan_results(&batch.request)
+            .expect("post scan results");
+        assert_eq!(response.findings_created, 1);
+        assert_eq!(response.new_finding_ids, vec!["clarion-sf-abc"]);
+        assert_eq!(response.warnings.len(), 1);
+        handle.join().expect("server thread");
+    }
+
+    #[test]
+    fn post_scan_results_surfaces_validation_error_as_http_status() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
+        let addr = listener.local_addr().expect("local addr");
+        let handle = std::thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("accept request");
+            let mut request = [0_u8; 8192];
+            let _ = stream.read(&mut request).expect("read request");
+            let body =
+                r#"{"error":"findings[0] is missing required key 'path'","code":"VALIDATION"}"#;
+            write!(
+                stream,
+                "HTTP/1.1 400 Bad Request\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+                body.len(),
+                body
+            )
+            .expect("write response");
+        });
+        let client = detail_test_client(addr);
+        let batch = crate::scan_results::prepare_batch(
+            &[],
+            &crate::scan_results::EmitOptions {
+                scan_run_id: None,
+                mark_unseen: true,
+                complete_scan_run: true,
+            },
+        );
+        let err = client
+            .post_scan_results(&batch.request)
+            .expect_err("400 surfaces as error");
+        match err {
+            FiligreeClientError::HttpStatus { status, .. } => assert_eq!(status, 400),
+            other => panic!("expected HttpStatus, got {other:?}"),
+        }
+        handle.join().expect("server thread");
+    }
+
+    fn detail_test_client(addr: std::net::SocketAddr) -> FiligreeHttpClient {
+        let config = FiligreeConfig {
+            enabled: true,
+            base_url: format!("http://{addr}"),
+            actor: "clarion-test".to_owned(),
+            token_env: "TEST_FILIGREE_TOKEN".to_owned(),
+            timeout_seconds: 1,
+            emit_findings: true,
+            prune_unseen_days: 30,
+        };
+        FiligreeHttpClient::from_config(&config, |_| None)
+            .expect("build client")
+            .expect("enabled client")
+    }
 }
diff --git a/crates/clarion-mcp/src/filigree_url.rs b/crates/clarion-mcp/src/filigree_url.rs
new file mode 100644
index 00000000..a8e90cbb
--- /dev/null
+++ b/crates/clarion-mcp/src/filigree_url.rs
@@ -0,0 +1,212 @@
+//! Resolve the live Filigree API base URL.
+//!
+//! Mirrors Filigree's ethereal endpoint-discovery convention: the dashboard
+//! publishes its live port to `<project>/.filigree/ephemeral.port` (a plain
+//! integer, written atomically, present only while the dashboard runs) and
+//! serves the read API on that port. The port is chosen deterministically but
+//! unpredictably (`8400 + sha256(path) % 1000` with fallback), so it must be
+//! *read*, never computed. This mirrors the Filigree sources:
+//!   - `filigree/src/filigree/ephemeral.py::{write,read}_port_file`
+//!   - `filigree/src/filigree/scanner_callback.py::resolve_scanner_api_url_with_source`
+//!
+//! Federation discipline (`docs/suite/loom.md` §5): this is enrich-only
+//! connection discovery. Clarion stays solo-useful — when no live port file is
+//! present (or Filigree is disabled) Clarion falls back to its *own* configured
+//! `base_url`, never to a Filigree-internal default (copying Filigree's
+//! `DEFAULT_PORT` would be a silent cross-product coupling). Reading the port
+//! file is fail-soft: any missing/corrupt/out-of-range content degrades to the
+//! configured URL.
+//!
+//! Scope: ethereal mode only. Filigree's `server` mode resolves through a
+//! home-directory global (`~/.config/filigree/server.json`); that path is not
+//! exercised here and is left as a known gap (clarion-318f1254eb tracks the
+//! issues_for-side resolution diagnostics that build on this resolver).
+
+use std::path::Path;
+
+use serde::Serialize;
+
+use crate::config::FiligreeConfig;
+
+/// Wire-facing `source` labels for a resolved Filigree URL. Reported verbatim
+/// by `project_status` (and, per clarion-318f1254eb, `issues_for`) so an agent
+/// can tell *where* the URL came from without shelling out to probe ports.
+pub const SOURCE_DISABLED: &str = "disabled";
+/// The live ethereal port published by Filigree's running dashboard.
+pub const SOURCE_EPHEMERAL_PORT: &str = ".filigree/ephemeral.port";
+/// Clarion's own configured `integrations.filigree.base_url`.
+pub const SOURCE_CONFIG: &str = "config";
+
+/// The outcome of resolving where Clarion should reach Filigree's read API.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct FiligreeUrlResolution {
+    /// Whether the Filigree integration is enabled in config at all.
+    pub enabled: bool,
+    /// The statically configured base URL (`integrations.filigree.base_url`).
+    pub configured_url: String,
+    /// The URL Clarion will actually call. `None` only when disabled.
+    pub resolved_url: Option<String>,
+    /// Which input produced [`Self::resolved_url`]; one of the `SOURCE_*` labels.
+    pub source: &'static str,
+}
+
+/// Resolve the Filigree read-API base URL, preferring the live ethereal port.
+///
+/// - Disabled → no resolved URL, `source = "disabled"`.
+/// - A valid `<project_root>/.filigree/ephemeral.port` → the configured URL
+///   with its port overridden by the live port, `source = ".filigree/ephemeral.port"`.
+/// - Otherwise → the configured URL unchanged, `source = "config"`.
+#[must_use]
+pub fn resolve_filigree_url(config: &FiligreeConfig, project_root: &Path) -> FiligreeUrlResolution {
+    let configured_url = config.base_url.clone();
+    if !config.enabled {
+        return FiligreeUrlResolution {
+            enabled: false,
+            configured_url,
+            resolved_url: None,
+            source: SOURCE_DISABLED,
+        };
+    }
+    match read_ephemeral_port(project_root) {
+        Some(port) => {
+            let resolved = override_port(&configured_url, port);
+            FiligreeUrlResolution {
+                enabled: true,
+                configured_url,
+                resolved_url: Some(resolved),
+                source: SOURCE_EPHEMERAL_PORT,
+            }
+        }
+        None => FiligreeUrlResolution {
+            enabled: true,
+            resolved_url: Some(configured_url.clone()),
+            configured_url,
+            source: SOURCE_CONFIG,
+        },
+    }
+}
+
+/// Read `<project_root>/.filigree/ephemeral.port` as a TCP port.
+///
+/// Mirrors Filigree's `read_port_file`: a plain trimmed integer. Any
+/// missing/corrupt/out-of-range/zero content folds to `None` (fail-soft).
+fn read_ephemeral_port(project_root: &Path) -> Option<u16> {
+    let path = project_root.join(".filigree").join("ephemeral.port");
+    let raw = std::fs::read_to_string(&path).ok()?;
+    raw.trim().parse::<u16>().ok().filter(|port| *port != 0)
+}
+
+/// Replace the port in a `scheme://host[:port][/path]` URL, preserving the
+/// scheme, host, and any trailing path. Returns the input unchanged when it
+/// has no recognizable `scheme://` authority. IPv6 literal hosts are out of
+/// scope — Filigree binds `127.0.0.1`.
+fn override_port(base_url: &str, port: u16) -> String {
+    let Some((scheme, rest)) = base_url.split_once("://") else {
+        return base_url.to_owned();
+    };
+    let (authority, path) = match rest.find('/') {
+        Some(slash) => (&rest[..slash], &rest[slash..]),
+        None => (rest, ""),
+    };
+    // Strip an existing `:port` suffix, but only when it is genuinely a numeric
+    // port (so a bare `host` with no port is preserved intact).
+    let host = match authority.rsplit_once(':') {
+        Some((host, maybe_port))
+            if !maybe_port.is_empty() && maybe_port.bytes().all(|b| b.is_ascii_digit()) =>
+        {
+            host
+        }
+        _ => authority,
+    };
+    format!("{scheme}://{host}:{port}{path}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn enabled_config() -> FiligreeConfig {
+        FiligreeConfig {
+            enabled: true,
+            ..FiligreeConfig::default()
+        }
+    }
+
+    fn write_port_file(root: &Path, contents: &str) {
+        let dir = root.join(".filigree");
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(dir.join("ephemeral.port"), contents).unwrap();
+    }
+
+    #[test]
+    fn disabled_integration_resolves_nothing() {
+        let dir = tempfile::tempdir().unwrap();
+        let config = FiligreeConfig::default(); // enabled: false
+        let res = resolve_filigree_url(&config, dir.path());
+        assert!(!res.enabled);
+        assert_eq!(res.resolved_url, None);
+        assert_eq!(res.source, SOURCE_DISABLED);
+        assert_eq!(res.configured_url, "http://127.0.0.1:8766");
+    }
+
+    #[test]
+    fn live_ephemeral_port_overrides_the_stale_configured_port() {
+        // The dogfood bug: configured 8766 is dead; the live dashboard is on
+        // 8542 per .filigree/ephemeral.port.
+        let dir = tempfile::tempdir().unwrap();
+        write_port_file(dir.path(), "8542\n");
+        let res = resolve_filigree_url(&enabled_config(), dir.path());
+        assert!(res.enabled);
+        assert_eq!(res.resolved_url.as_deref(), Some("http://127.0.0.1:8542"));
+        assert_eq!(res.source, SOURCE_EPHEMERAL_PORT);
+        // The configured URL is still reported verbatim alongside the resolved one.
+        assert_eq!(res.configured_url, "http://127.0.0.1:8766");
+    }
+
+    #[test]
+    fn falls_back_to_configured_url_when_no_port_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let res = resolve_filigree_url(&enabled_config(), dir.path());
+        assert!(res.enabled);
+        assert_eq!(res.resolved_url.as_deref(), Some("http://127.0.0.1:8766"));
+        assert_eq!(res.source, SOURCE_CONFIG);
+    }
+
+    #[test]
+    fn corrupt_port_file_folds_to_configured_url() {
+        let dir = tempfile::tempdir().unwrap();
+        write_port_file(dir.path(), "not-a-port");
+        let res = resolve_filigree_url(&enabled_config(), dir.path());
+        assert_eq!(res.source, SOURCE_CONFIG);
+        assert_eq!(res.resolved_url.as_deref(), Some("http://127.0.0.1:8766"));
+    }
+
+    #[test]
+    fn zero_port_is_rejected_as_corrupt() {
+        let dir = tempfile::tempdir().unwrap();
+        write_port_file(dir.path(), "0");
+        let res = resolve_filigree_url(&enabled_config(), dir.path());
+        assert_eq!(res.source, SOURCE_CONFIG);
+    }
+
+    #[test]
+    fn override_port_preserves_scheme_host_and_path() {
+        assert_eq!(
+            override_port("http://127.0.0.1:8766", 8542),
+            "http://127.0.0.1:8542"
+        );
+        assert_eq!(
+            override_port("http://localhost", 8542),
+            "http://localhost:8542"
+        );
+        assert_eq!(
+            override_port("https://example.test:1/api", 8542),
+            "https://example.test:8542/api"
+        );
+    }
+
+    #[test]
+    fn override_port_returns_input_without_scheme() {
+        assert_eq!(override_port("127.0.0.1:8766", 8542), "127.0.0.1:8766");
+    }
+}
diff --git a/crates/clarion-mcp/src/index_diff.rs b/crates/clarion-mcp/src/index_diff.rs
new file mode 100644
index 00000000..89483daa
--- /dev/null
+++ b/crates/clarion-mcp/src/index_diff.rs
@@ -0,0 +1,697 @@
+//! `index_diff`: deterministic index freshness / drift report (clarion-326b01ffd0).
+//!
+//! Answers "what changed since the last analyze, and is this checkout newer
+//! than the graph?" without an agent hand-rolling git + mtime checks.
+//!
+//! **Git posture (per the issue's design fork).** Clarion persists no
+//! analyze-time commit SHA — `project_status` reports `git_sha: null` and the
+//! analyze write path never captures HEAD. Rather than reverse that stance to
+//! populate one side of a comparison, `index_diff` reads git *at query time*,
+//! *read-only*, and *fail-soft*: a missing git binary or a non-repo working
+//! directory degrades to `git.available=false` with a reason, never an error.
+//! `analyzed_commit` is reported `null` (honest, matching `project_status`),
+//! and the HEAD-vs-analyze staleness signal compares HEAD's committer date
+//! against the run's completion time — which holds even when source mtimes are
+//! ambiguous.
+
+use std::collections::BTreeSet;
+use std::path::Path;
+use std::process::Command;
+use std::time::SystemTime;
+
+use serde_json::{Value, json};
+use time::OffsetDateTime;
+use time::format_description::well_known::Rfc3339;
+
+use clarion_storage::{StorageError, normalize_source_path};
+
+/// Default per-list cap so a pathological repo cannot produce an unbounded
+/// packet. Overridable via the `limit` argument.
+pub(crate) const DEFAULT_MAX_ENTRIES: usize = 200;
+
+/// Git facts gathered at query time, outside the reader. Every field is
+/// best-effort; see the module docstring for the fail-soft contract.
+pub(crate) struct GitFacts {
+    available: bool,
+    is_repo: bool,
+    head_commit: Option<String>,
+    head_committed_at: Option<String>,
+    dirty: Vec<DirtyEntry>,
+    reason: Option<String>,
+}
+
+struct DirtyEntry {
+    status: String,
+    rel_path: String,
+}
+
+/// Run `git` read-only against `project_root` and collect HEAD + dirty-tree
+/// facts. Blocking; call from a `spawn_blocking` context.
+pub(crate) fn gather_git_facts(project_root: &Path) -> GitFacts {
+    let inside = Command::new("git")
+        .arg("-C")
+        .arg(project_root)
+        .args(["rev-parse", "--is-inside-work-tree"])
+        .output();
+    let (available, is_repo, reason) = match inside {
+        Ok(out) if out.status.success() => {
+            let is_repo = String::from_utf8_lossy(&out.stdout).trim() == "true";
+            let reason = (!is_repo).then(|| "not inside a git work tree".to_owned());
+            (true, is_repo, reason)
+        }
+        Ok(_) => (true, false, Some("not a git repository".to_owned())),
+        Err(err) => (false, false, Some(format!("git unavailable: {err}"))),
+    };
+    if !is_repo {
+        return GitFacts {
+            available,
+            is_repo: false,
+            head_commit: None,
+            head_committed_at: None,
+            dirty: Vec::new(),
+            reason,
+        };
+    }
+
+    let run = |args: &[&str]| -> Option<String> {
+        let out = Command::new("git")
+            .arg("-C")
+            .arg(project_root)
+            .args(args)
+            .output()
+            .ok()?;
+        out.status
+            .success()
+            .then(|| String::from_utf8_lossy(&out.stdout).trim().to_owned())
+            .filter(|s| !s.is_empty())
+    };
+
+    let head_commit = run(&["rev-parse", "HEAD"]);
+    // `%cI` is strict ISO-8601 (RFC3339) with the committer's UTC offset.
+    let head_committed_at = run(&["log", "-1", "--format=%cI", "HEAD"]);
+    // Read status raw: porcelain's leading X-column space is significant, so it
+    // must NOT be trimmed off the front (the `run` closure trims the whole
+    // blob, which would shift every column left and corrupt the path).
+    let dirty = Command::new("git")
+        .arg("-C")
+        .arg(project_root)
+        .args(["status", "--porcelain=v1"])
+        .output()
+        .ok()
+        .filter(|out| out.status.success())
+        .map(|out| parse_porcelain(&String::from_utf8_lossy(&out.stdout)))
+        .unwrap_or_default();
+
+    GitFacts {
+        available,
+        is_repo: true,
+        head_commit,
+        head_committed_at,
+        dirty,
+        reason: None,
+    }
+}
+
+/// Parse `git status --porcelain=v1` output into per-path entries. Renames
+/// (`R  old -> new`) collapse to the new path; git's C-style quoting of paths
+/// with special bytes is decoded (see [`unquote_c_path`]).
+fn parse_porcelain(out: &str) -> Vec<DirtyEntry> {
+    out.lines()
+        .filter_map(|line| {
+            if line.len() <= 3 {
+                return None;
+            }
+            let status = line[..2].trim().to_owned();
+            let rest = line[3..].trim();
+            let path = rest.rsplit(" -> ").next().unwrap_or(rest);
+            Some(DirtyEntry {
+                status,
+                rel_path: unquote_c_path(path),
+            })
+        })
+        .collect()
+}
+
+/// Decode git's C-style path quoting back to a real path. With the default
+/// `core.quotePath=true`, git renders any path containing a control byte, a
+/// backslash, a double-quote, or a non-ASCII byte as a double-quoted string
+/// with C escapes: `\\`, `\"`, `\t`/`\n`/`\r`/`\a`/`\b`/`\f`/`\v`, and `\NNN`
+/// octal *byte* escapes (e.g. `"\303\251.py"` for `é.py`). Octal escapes are
+/// emitted one per UTF-8 byte, so they must be reassembled into bytes before
+/// the result is decoded — `trim_matches('"')` alone would leave
+/// `\303\251.py` literal and never correlate against an indexed path.
+///
+/// A path with no special bytes is emitted bare (no surrounding quotes) and is
+/// returned unchanged. Best-effort and panic-free: an unrecognised escape keeps
+/// its literal `\x`, a dangling trailing backslash is preserved, and invalid
+/// UTF-8 decodes lossily.
+fn unquote_c_path(raw: &str) -> String {
+    let bytes = raw.as_bytes();
+    // Bare (unquoted) paths pass through untouched.
+    if bytes.len() < 2 || bytes[0] != b'"' || bytes[bytes.len() - 1] != b'"' {
+        return raw.to_owned();
+    }
+    let inner = &bytes[1..bytes.len() - 1];
+    let mut out: Vec<u8> = Vec::with_capacity(inner.len());
+    let mut i = 0;
+    while i < inner.len() {
+        if inner[i] != b'\\' {
+            out.push(inner[i]);
+            i += 1;
+            continue;
+        }
+        // Consume the backslash; decode the escape that follows.
+        i += 1;
+        let Some(&escape) = inner.get(i) else {
+            // Dangling trailing backslash — keep it verbatim.
+            out.push(b'\\');
+            break;
+        };
+        match escape {
+            b'a' => out.push(0x07),
+            b'b' => out.push(0x08),
+            b't' => out.push(b'\t'),
+            b'n' => out.push(b'\n'),
+            b'v' => out.push(0x0b),
+            b'f' => out.push(0x0c),
+            b'r' => out.push(b'\r'),
+            b'"' => out.push(b'"'),
+            b'\\' => out.push(b'\\'),
+            b'0'..=b'7' => {
+                // Up to three octal digits → one byte (git emits \000..\377).
+                let mut value: u8 = 0;
+                let mut digits = 0;
+                while digits < 3 && inner.get(i).is_some_and(|b| (b'0'..=b'7').contains(b)) {
+                    value = value.wrapping_mul(8).wrapping_add(inner[i] - b'0');
+                    i += 1;
+                    digits += 1;
+                }
+                out.push(value);
+                continue; // `i` already advanced past the octal run.
+            }
+            other => {
+                // Unrecognised escape: preserve `\` + the char.
+                out.push(b'\\');
+                out.push(other);
+            }
+        }
+        i += 1;
+    }
+    String::from_utf8_lossy(&out).into_owned()
+}
+
+/// Index state read from the DB inside the reader.
+pub(crate) struct IndexState {
+    pub analyzed_at: Option<String>,
+    pub latest_run: Option<Value>,
+    pub files: Vec<IndexedFile>,
+    pub plugin_stats: Value,
+}
+
+pub(crate) struct IndexedFile {
+    pub source_file_path: String,
+    pub entity_count: i64,
+}
+
+/// Read the freshness-relevant index state: the latest *completed* run, the
+/// distinct indexed source files with their entity counts, and the aggregate
+/// plugin skip/drop counters from that run's stats.
+pub(crate) fn read_index_state(conn: &rusqlite::Connection) -> Result<IndexState, StorageError> {
+    let latest = conn
+        .query_row(
+            "SELECT id, started_at, completed_at, status, stats FROM runs \
+             WHERE status = 'completed' AND completed_at IS NOT NULL \
+             ORDER BY completed_at DESC LIMIT 1",
+            [],
+            |row| {
+                Ok((
+                    row.get::<_, String>(0)?,
+                    row.get::<_, String>(1)?,
+                    row.get::<_, Option<String>>(2)?,
+                    row.get::<_, String>(3)?,
+                    row.get::<_, String>(4)?,
+                ))
+            },
+        )
+        .ok();
+
+    let (analyzed_at, latest_run, plugin_stats) = match latest {
+        Some((id, started_at, completed_at, run_status, stats_json)) => {
+            let parsed_stats = serde_json::from_str::<Value>(&stats_json).unwrap_or(Value::Null);
+            let run = json!({
+                "id": id,
+                "started_at": started_at,
+                "completed_at": completed_at,
+                "status": run_status,
+            });
+            (completed_at, Some(run), plugin_stats_subset(&parsed_stats))
+        }
+        None => (None, None, Value::Null),
+    };
+
+    let mut stmt = conn.prepare(
+        "SELECT source_file_path, COUNT(*) FROM entities \
+         WHERE source_file_path IS NOT NULL \
+         GROUP BY source_file_path ORDER BY source_file_path",
+    )?;
+    let files = stmt
+        .query_map([], |row| {
+            Ok(IndexedFile {
+                source_file_path: row.get(0)?,
+                entity_count: row.get(1)?,
+            })
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+
+    Ok(IndexState {
+        analyzed_at,
+        latest_run,
+        files,
+        plugin_stats,
+    })
+}
+
+/// Pull just the per-run aggregate skip/drop/unresolved counters that bear on
+/// "what did the plugins fail to fully resolve?". Per-file failure lists are
+/// not retained in v0.1 (wipe-and-rerun model), so this is the honest surface.
+fn plugin_stats_subset(stats: &Value) -> Value {
+    let pick = |key: &str| stats.get(key).cloned().unwrap_or(Value::Null);
+    json!({
+        "dropped_edges_total": pick("dropped_edges_total"),
+        "imports_skipped_external_total": pick("imports_skipped_external_total"),
+        "references_skipped_external_total": pick("references_skipped_external_total"),
+        "references_skipped_cap_total": pick("references_skipped_cap_total"),
+        "unresolved_call_sites_total": pick("unresolved_call_sites_total"),
+        "unresolved_reference_sites_total": pick("unresolved_reference_sites_total"),
+    })
+}
+
+fn parse_rfc3339(s: &str) -> Option<SystemTime> {
+    OffsetDateTime::parse(s, &Rfc3339)
+        .ok()
+        .map(SystemTime::from)
+}
+
+#[derive(Default)]
+struct FileDrift {
+    modified: Vec<Value>,
+    missing: Vec<Value>,
+    statted: usize,
+    stat_failures: usize,
+}
+
+/// Stat each indexed file once: classify as modified (mtime newer than the
+/// analyze time), missing (gone from disk), or fresh. `analyzed_time` is `None`
+/// when the run timestamp could not be parsed — files are still statted for
+/// existence, but none are flagged modified (the mtime channel is blind).
+fn compute_file_drift(
+    project_root: &Path,
+    state: &IndexState,
+    analyzed_time: Option<SystemTime>,
+) -> FileDrift {
+    let mut drift = FileDrift::default();
+    for file in &state.files {
+        let abs = absolute(project_root, &file.source_file_path);
+        match std::fs::metadata(&abs) {
+            Ok(meta) => {
+                drift.statted += 1;
+                let mtime = meta.modified().ok();
+                if let (Some(mtime), Some(analyzed)) = (mtime, analyzed_time)
+                    && mtime > analyzed
+                {
+                    drift.modified.push(json!({
+                        "path": file.source_file_path,
+                        "indexed_entities": file.entity_count,
+                    }));
+                }
+            }
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+                drift.missing.push(json!({
+                    "path": file.source_file_path,
+                    "indexed_entities": file.entity_count,
+                }));
+            }
+            Err(_) => drift.stat_failures += 1,
+        }
+    }
+    drift
+}
+
+/// Assemble the `index_diff` report from index state + git facts. Stats the
+/// indexed files (cheap IO); correlates git dirty paths against indexed paths.
+pub(crate) fn build_report(
+    project_root: &Path,
+    state: &IndexState,
+    git: &GitFacts,
+    cap: usize,
+) -> Value {
+    let git_json = json!({
+        "available": git.available,
+        "is_repo": git.is_repo,
+        "current_commit": git.head_commit,
+        "head_committed_at": git.head_committed_at,
+        "reason": git.reason,
+    });
+
+    // No completed run: nothing to diff against.
+    let Some(analyzed_at) = state.analyzed_at.as_deref() else {
+        return json!({
+            "overall": "never_analyzed",
+            "drift_detected": false,
+            "analyzed_at": Value::Null,
+            "analyzed_commit": Value::Null,
+            "git": git_json,
+            "notes": ["no completed analyze run; run `clarion analyze` first"],
+        });
+    };
+    let analyzed_time = parse_rfc3339(analyzed_at);
+
+    // HEAD-vs-analyze by committer date — independent of source mtimes.
+    let head_newer_than_analyze = match (
+        git.head_committed_at.as_deref().and_then(parse_rfc3339),
+        analyzed_time,
+    ) {
+        (Some(head), Some(analyzed)) => Some(head > analyzed),
+        _ => None,
+    };
+
+    // Per-file drift: stat each indexed file once.
+    let file_drift = compute_file_drift(project_root, state, analyzed_time);
+
+    // Indexed source paths (absolute) normalized to canonical project-relative
+    // form, so a git-relative dirty path matches regardless of the project_root
+    // shape (`.` vs absolute) or symlinks. A raw join + string-eq would never
+    // match (clarion-326b01ffd0 review).
+    let indexed_rel: BTreeSet<String> = state
+        .files
+        .iter()
+        .filter_map(|f| normalize_source_path(project_root, &f.source_file_path).ok())
+        .collect();
+
+    // Dirty working-tree files, flagged when they touch an indexed path.
+    let mut dirty = Vec::new();
+    let mut dirty_indexed_count = 0usize;
+    for entry in &git.dirty {
+        let indexed = normalize_source_path(project_root, &entry.rel_path)
+            .ok()
+            .is_some_and(|rel| indexed_rel.contains(&rel));
+        if indexed {
+            dirty_indexed_count += 1;
+        }
+        dirty.push(json!({
+            "path": entry.rel_path,
+            "status": entry.status,
+            "indexed": indexed,
+        }));
+    }
+
+    let drift_detected = head_newer_than_analyze == Some(true)
+        || !file_drift.modified.is_empty()
+        || !file_drift.missing.is_empty()
+        || dirty_indexed_count > 0;
+
+    // Verdict: drift if any signal fired; fresh if we could observe state and
+    // nothing fired; unknown only when every observation channel was blind
+    // (no files statted AND git gave us no HEAD comparison).
+    let could_observe = file_drift.statted > 0 || head_newer_than_analyze.is_some();
+    let overall = if drift_detected {
+        "drift"
+    } else if could_observe {
+        "fresh"
+    } else {
+        "unknown"
+    };
+
+    let (modified, modified_omitted) = cap_list(file_drift.modified, cap);
+    let (missing, missing_omitted) = cap_list(file_drift.missing, cap);
+    let (dirty, dirty_omitted) = cap_list(dirty, cap);
+
+    let mut notes = vec![
+        "analyzed_commit is null: Clarion does not persist an analyze-time SHA; \
+         HEAD-vs-analyze staleness uses HEAD committer date vs run completion time"
+            .to_owned(),
+        "added (never-indexed) source files are not enumerated here beyond the \
+         git dirty set; a new commit still flips head_newer_than_analyze"
+            .to_owned(),
+    ];
+    if file_drift.stat_failures > 0 {
+        notes.push(format!(
+            "{} indexed file(s) could not be stat-ed (permission/IO); \
+             excluded from the modified/missing sets",
+            file_drift.stat_failures
+        ));
+    }
+
+    json!({
+        "overall": overall,
+        "drift_detected": drift_detected,
+        "analyzed_at": analyzed_at,
+        "analyzed_commit": Value::Null,
+        "latest_run": state.latest_run,
+        "git": git_json,
+        "head_newer_than_analyze": head_newer_than_analyze,
+        "indexed_files": state.files.len(),
+        "modified_since_analyze": modified,
+        "missing_files": missing,
+        "dirty_files": dirty,
+        "dirty_indexed_count": dirty_indexed_count,
+        // Per-run aggregate plugin skip/drop counters; per-file failure lists
+        // are not retained in v0.1 (wipe-and-rerun).
+        "plugin_resolution": state.plugin_stats,
+        // Entity-level add/remove/change diff needs a retained prior-run
+        // snapshot; v0.1 keeps only the current graph (wipe-and-rerun).
+        "entity_diff": {
+            "available": false,
+            "reason": "v0.1 retains only the current run's graph; no prior-run snapshot to diff against",
+        },
+        "omitted": {
+            "modified_since_analyze": modified_omitted,
+            "missing_files": missing_omitted,
+            "dirty_files": dirty_omitted,
+        },
+        "notes": notes,
+    })
+}
+
+fn absolute(project_root: &Path, path: &str) -> String {
+    if Path::new(path).is_absolute() {
+        path.to_owned()
+    } else {
+        project_root.join(path).to_string_lossy().into_owned()
+    }
+}
+
+fn cap_list(mut list: Vec<Value>, cap: usize) -> (Vec<Value>, usize) {
+    if list.len() > cap {
+        let omitted = list.len() - cap;
+        list.truncate(cap);
+        (list, omitted)
+    } else {
+        (list, 0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_porcelain_handles_modified_and_rename() {
+        let out = " M src/lib.rs\nR  old.rs -> new.rs\n?? untracked.py\n";
+        let entries = parse_porcelain(out);
+        assert_eq!(entries.len(), 3);
+        assert_eq!(entries[0].status, "M");
+        assert_eq!(entries[0].rel_path, "src/lib.rs");
+        assert_eq!(entries[1].status, "R");
+        assert_eq!(entries[1].rel_path, "new.rs");
+        assert_eq!(entries[2].status, "??");
+        assert_eq!(entries[2].rel_path, "untracked.py");
+    }
+
+    #[test]
+    fn parse_porcelain_skips_blank_and_short_lines() {
+        assert!(parse_porcelain("\n \nM\n").is_empty());
+    }
+
+    #[test]
+    fn parse_porcelain_decodes_c_quoted_non_ascii_path() {
+        // git quotes `café.py` (and emits its UTF-8 bytes as octal escapes)
+        // under the default core.quotePath=true.
+        let out = " M \"caf\\303\\251.py\"\n";
+        let entries = parse_porcelain(out);
+        assert_eq!(entries.len(), 1);
+        assert_eq!(entries[0].status, "M");
+        assert_eq!(
+            entries[0].rel_path, "café.py",
+            "octal-escaped UTF-8 bytes must decode to the real path"
+        );
+    }
+
+    #[test]
+    fn unquote_c_path_handles_escapes_quotes_and_bare_paths() {
+        // Bare path: returned untouched.
+        assert_eq!(unquote_c_path("src/lib.rs"), "src/lib.rs");
+        // Quoted with an escaped quote and backslash.
+        assert_eq!(unquote_c_path(r#""a\"b\\c.py""#), "a\"b\\c.py");
+        // Quoted with a tab escape.
+        assert_eq!(unquote_c_path(r#""a\tb.py""#), "a\tb.py");
+        // Octal byte escapes reassemble into a multi-byte UTF-8 char.
+        assert_eq!(unquote_c_path(r#""\360\237\232\200.py""#), "🚀.py");
+        // A leading-quote-only string is not a valid quoted path → unchanged.
+        assert_eq!(unquote_c_path("\"unterminated"), "\"unterminated");
+    }
+
+    fn git_facts(head_committed_at: Option<&str>, dirty: &[(&str, &str)]) -> GitFacts {
+        GitFacts {
+            available: true,
+            is_repo: true,
+            head_commit: Some("deadbeef".to_owned()),
+            head_committed_at: head_committed_at.map(str::to_owned),
+            dirty: dirty
+                .iter()
+                .map(|(status, path)| DirtyEntry {
+                    status: (*status).to_owned(),
+                    rel_path: (*path).to_owned(),
+                })
+                .collect(),
+            reason: None,
+        }
+    }
+
+    fn state_with_file(path: &str, entity_count: i64, analyzed_at: &str) -> IndexState {
+        IndexState {
+            analyzed_at: Some(analyzed_at.to_owned()),
+            latest_run: Some(json!({"id": "run-1", "status": "completed"})),
+            files: vec![IndexedFile {
+                source_file_path: path.to_owned(),
+                entity_count,
+            }],
+            plugin_stats: json!({}),
+        }
+    }
+
+    #[test]
+    fn never_analyzed_when_no_completed_run() {
+        let dir = tempfile::tempdir().unwrap();
+        let state = IndexState {
+            analyzed_at: None,
+            latest_run: None,
+            files: Vec::new(),
+            plugin_stats: Value::Null,
+        };
+        let report = build_report(
+            dir.path(),
+            &state,
+            &git_facts(None, &[]),
+            DEFAULT_MAX_ENTRIES,
+        );
+        assert_eq!(report["overall"], "never_analyzed");
+        assert_eq!(report["drift_detected"], false);
+    }
+
+    #[test]
+    fn clean_fresh_graph_reports_no_drift() {
+        // AC: clean repo + fresh graph → no drift. The file's mtime is "now";
+        // an analyze timestamp far in the future keeps it un-modified.
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("a.py"), "x = 1\n").unwrap();
+        let abs = dir.path().join("a.py").to_string_lossy().into_owned();
+        let state = state_with_file(&abs, 3, "2999-01-01T00:00:00.000Z");
+        let report = build_report(
+            dir.path(),
+            &state,
+            &git_facts(None, &[]),
+            DEFAULT_MAX_ENTRIES,
+        );
+        assert_eq!(report["overall"], "fresh");
+        assert_eq!(report["drift_detected"], false);
+        assert_eq!(report["modified_since_analyze"], json!([]));
+        assert_eq!(report["analyzed_commit"], Value::Null);
+    }
+
+    #[test]
+    fn modified_source_file_is_flagged_with_path_and_entity_impact() {
+        // AC: a modified source file is flagged with path + indexed entity impact.
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("a.py"), "x = 1\n").unwrap();
+        let abs = dir.path().join("a.py").to_string_lossy().into_owned();
+        let state = state_with_file(&abs, 5, "2000-01-01T00:00:00.000Z");
+        let report = build_report(
+            dir.path(),
+            &state,
+            &git_facts(None, &[]),
+            DEFAULT_MAX_ENTRIES,
+        );
+        assert_eq!(report["overall"], "drift");
+        assert_eq!(report["drift_detected"], true);
+        let modified = report["modified_since_analyze"].as_array().unwrap();
+        assert_eq!(modified.len(), 1);
+        assert_eq!(modified[0]["path"], abs);
+        assert_eq!(modified[0]["indexed_entities"], 5);
+    }
+
+    #[test]
+    fn head_newer_than_analyze_is_stale_even_when_mtimes_are_not() {
+        // AC: a HEAD newer than the last analyze is reported stale even if source
+        // mtimes are ambiguous. analyzed_at is in 2500 (so the just-written file's
+        // 2026 mtime does NOT flag it modified), but HEAD committed in 2600.
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("a.py"), "x = 1\n").unwrap();
+        let abs = dir.path().join("a.py").to_string_lossy().into_owned();
+        let state = state_with_file(&abs, 2, "2500-01-01T00:00:00.000Z");
+        let report = build_report(
+            dir.path(),
+            &state,
+            &git_facts(Some("2600-01-01T00:00:00+00:00"), &[]),
+            DEFAULT_MAX_ENTRIES,
+        );
+        assert_eq!(report["head_newer_than_analyze"], true);
+        assert_eq!(report["overall"], "drift");
+        assert_eq!(
+            report["modified_since_analyze"],
+            json!([]),
+            "the drift signal comes from the commit clock, not mtime"
+        );
+    }
+
+    #[test]
+    fn dirty_file_touching_indexed_path_drives_drift() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("a.py"), "x = 1\n").unwrap();
+        let abs = dir.path().join("a.py").to_string_lossy().into_owned();
+        let state = state_with_file(&abs, 1, "2999-01-01T00:00:00.000Z");
+        // Git reports a.py dirty (project-relative); it joins to the indexed abs.
+        let report = build_report(
+            dir.path(),
+            &state,
+            &git_facts(None, &[("M", "a.py"), ("??", "untracked.txt")]),
+            DEFAULT_MAX_ENTRIES,
+        );
+        assert_eq!(report["drift_detected"], true);
+        assert_eq!(report["dirty_indexed_count"], 1);
+        let dirty = report["dirty_files"].as_array().unwrap();
+        assert_eq!(dirty.len(), 2);
+        let a = dirty.iter().find(|d| d["path"] == "a.py").unwrap();
+        assert_eq!(a["indexed"], true);
+        let u = dirty.iter().find(|d| d["path"] == "untracked.txt").unwrap();
+        assert_eq!(u["indexed"], false);
+    }
+
+    #[test]
+    fn missing_indexed_file_is_reported() {
+        let dir = tempfile::tempdir().unwrap();
+        let abs = dir.path().join("gone.py").to_string_lossy().into_owned();
+        let state = state_with_file(&abs, 4, "2999-01-01T00:00:00.000Z");
+        let report = build_report(
+            dir.path(),
+            &state,
+            &git_facts(None, &[]),
+            DEFAULT_MAX_ENTRIES,
+        );
+        assert_eq!(report["drift_detected"], true);
+        let missing = report["missing_files"].as_array().unwrap();
+        assert_eq!(missing.len(), 1);
+        assert_eq!(missing[0]["path"], abs);
+        assert_eq!(missing[0]["indexed_entities"], 4);
+    }
+}
diff --git a/crates/clarion-mcp/src/lib.rs b/crates/clarion-mcp/src/lib.rs
index d44f06e3..e2f751a7 100644
--- a/crates/clarion-mcp/src/lib.rs
+++ b/crates/clarion-mcp/src/lib.rs
@@ -1,7 +1,12 @@
 //! MCP protocol surface for Clarion.
 
+mod analyze_runs;
 pub mod config;
 pub mod filigree;
+pub mod filigree_url;
+mod index_diff;
+pub mod scan_results;
+pub mod snapshot;
 
 use std::collections::{BTreeSet, HashMap, HashSet};
 use std::path::PathBuf;
@@ -21,22 +26,64 @@ use tokio::sync::{Mutex as AsyncMutex, broadcast, mpsc, oneshot};
 use clarion_core::plugin::{ContentLengthCeiling, Frame, TransportError};
 use clarion_storage::{
     CallEdgeMatch, EntityRow, InferredCallEdgeRecord, InferredEdgeCacheEntry, InferredEdgeCacheKey,
-    InferredEdgeWriteStats, ReaderPool, ReferenceDirection, StorageError, SummaryCacheEntry,
-    SummaryCacheKey, UnresolvedCallSiteRow, WriterCmd, call_edges_from, call_edges_targeting,
+    InferredEdgeWriteStats, ReaderPool, ReferenceDirection, ReferenceEdgeMatch,
+    RolledUpReferenceEdge, StorageError, SummaryCacheEntry, SummaryCacheKey, UnresolvedCallSiteRow,
+    WriterCmd, ancestor_chain, call_edges_from, call_edges_targeting,
     candidate_entities_for_unresolved_sites, child_entity_ids, contained_entity_ids,
-    entity_at_line, entity_by_id, existing_entity_ids, find_entities, inferred_edge_cache_key_id,
-    inferred_edge_cache_lookup, normalize_source_path, reference_edges_for_entity,
-    subsystem_members, summary_cache_lookup, unresolved_call_sites_for_caller,
+    containing_module_id, entities_containing_line, entity_by_id, existing_entity_ids,
+    find_entities, import_edges_for_entity, inferred_edge_cache_key_id, inferred_edge_cache_lookup,
+    module_reference_rollup, normalize_source_path, reference_edges_for_entity, subsystem_members,
+    subsystem_of_entity, summary_cache_lookup, unresolved_call_sites_for_caller,
     unresolved_callers_for_target,
 };
 
 use crate::config::LlmConfig;
-use crate::filigree::{EntityAssociation, EntityAssociationsResponse, FiligreeLookup};
+use crate::filigree::{EntityAssociation, EntityAssociationsResponse, FiligreeLookup, IssueDetail};
 
 /// MCP protocol revision supported by the B.6 stdio server.
 pub const MCP_PROTOCOL_VERSION: &str = "2025-11-25";
 const EMPTY_GUIDANCE_FINGERPRINT: &str = "guidance-empty";
 
+/// The bundled clarion-workflow skill text, embedded for the `prompts/get`
+/// surface and reused as the canonical orientation reference. The asset lives
+/// in this crate's own tree; the CLI (which depends on clarion-mcp) reaches
+/// down into it to embed the same bytes for its on-disk `install --skills`
+/// copy (clarion-04391392c7).
+pub const CLARION_WORKFLOW_SKILL: &str = include_str!("../assets/skills/clarion-workflow/SKILL.md");
+
+/// Orientation text returned in the MCP `initialize` result's `instructions`
+/// field. The `Tools:` enumeration is derived from [`list_tools`] (the single
+/// source of truth) so it can never drift from the advertised tool set as tools
+/// are added or removed; the surrounding prose is static. Kept consistent with
+/// the clarion-workflow skill.
+fn server_instructions() -> String {
+    let tool_names = list_tools()
+        .iter()
+        .map(|tool| tool.name)
+        .collect::<Vec<_>>()
+        .join(", ");
+    format!(
+        "Clarion is a code-archaeology server: it has pre-extracted this project \
+into a queryable map of entities (functions, classes, modules, files), the call \
+/ reference / import edges between them, and subsystem clusters. Ask Clarion \
+instead of re-reading or grepping the tree.
+
+Entity IDs are `{{plugin}}:{{kind}}:{{qualified_name}}` (e.g. \
+`python:function:pkg.mod.func`); subsystems are `core:subsystem:{{hash}}`. You \
+almost never type IDs — get one from `find_entity` or `entity_at`, then copy it \
+verbatim into the next tool.
+
+Tools: {tool_names}. `callers_of` / `neighborhood` / `execution_paths_from` \
+take a `confidence` tier (resolved | ambiguous | inferred; default resolved). \
+`project_status` reports index freshness, counts, LLM policy, and the resolved \
+Filigree endpoint.
+
+For the full workflow see the clarion-workflow skill (installed by \
+`clarion install --skills`), or read the `clarion-workflow` prompt. Live \
+project counts and index freshness are in the `clarion://context` resource."
+    )
+}
+
 type InferredInflight =
     Arc<AsyncMutex<HashMap<InferredEdgeCacheKey, broadcast::Sender<InferredDispatchOutcome>>>>;
 
@@ -49,11 +96,13 @@ pub struct ToolDefinition {
 }
 
 #[must_use]
+// A flat registry of tool definitions; length tracks the tool count by design.
+#[allow(clippy::too_many_lines)]
 pub fn list_tools() -> Vec<ToolDefinition> {
     vec![
         ToolDefinition {
             name: "entity_at",
-            description: "Return the innermost Clarion entity whose source range contains a file and line. Paths are normalized relative to the project root. Returns no match rather than guessing when ranges are absent.",
+            description: "Return the innermost Clarion entity whose source range contains a file and line, plus an `entity_context` evidence block: match_reason (decorator_range / declaration / body_range / containing_range / no_match) explaining why the line matched, the module→entity containing stack, the matched entity's decl/body/decorator sub-ranges, any same-granularity ambiguity alternatives, and index freshness. Paths are normalized relative to the project root. A blank or comment line that only a module spans reports containing_range — never a fabricated exact match.",
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -66,13 +115,14 @@ pub fn list_tools() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "find_entity",
-            description: "Search Clarion entities by id, name, short name, and summary text stored on entity rows. Results are paginated and ranked by FTS match where possible. This does not traverse the graph and does not search on-demand summary_cache entries.",
+            description: "Search Clarion entities by id, name, short name, and summary text stored on entity rows. Results are paginated and ranked by FTS match where possible. This does not traverse the graph and does not search on-demand summary_cache entries. Pass an optional `kind` (e.g. \"subsystem\", \"function\", \"class\", \"module\") to return only entities of that kind — the way to locate a subsystem without visually filtering results.",
             input_schema: json!({
                 "type": "object",
                 "properties": {
                     "pattern": {"type": "string", "minLength": 1},
                     "limit": {"type": "integer", "minimum": 1, "maximum": 100},
-                    "cursor": {"type": ["string", "null"]}
+                    "cursor": {"type": ["string", "null"]},
+                    "kind": {"type": "string", "minLength": 1}
                 },
                 "required": ["pattern"],
                 "additionalProperties": false
@@ -80,12 +130,12 @@ pub fn list_tools() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "callers_of",
-            description: "Return entities that call the given entity. Default confidence is resolved, so ambiguous static candidates and LLM-inferred edges are excluded unless explicitly requested. Ambiguous edges expand all candidates; inferred edges may trigger bounded LLM dispatch.",
+            description: "Return entities that call the given entity. Default confidence is resolved, so ambiguous static candidates and LLM-inferred edges are excluded unless explicitly requested. Ambiguous edges expand all candidates; inferred edges may trigger bounded LLM dispatch. The result carries scope_excludes naming static blind spots not searched (e.g. attribute-receiver-calls) so an empty callers list is never read as a guaranteed true negative.",
             input_schema: id_confidence_schema(),
         },
         ToolDefinition {
             name: "execution_paths_from",
-            description: "Return bounded calls-only execution paths starting at an entity. Default confidence is resolved. max_depth defaults to 3 and traversal also stops at the server edge cap; responses say when they are truncated.",
+            description: "Return bounded calls-only execution paths starting at an entity. Default confidence is resolved. max_depth defaults to 3. Results are compact: a deduplicated nodes table plus paths as arrays of node ids (under a root), ranked longest-first. Traversal stops at the server edge cap and the response is capped at a maximum number of ranked paths; truncated/truncation_reason report edge-cap or path-cap when either trims. The result carries scope_excludes naming static blind spots not searched (e.g. attribute-receiver-calls).",
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -99,12 +149,12 @@ pub fn list_tools() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "summary",
-            description: "Return an on-demand cached summary for one entity. In v0.1 this is leaf scope only: module summaries describe the module docstring and top-level members, not an aggregation of contained function/class summaries.",
+            description: "Return an on-demand cached summary for one entity. In v0.1 this is leaf scope only: module summaries describe the module docstring and top-level members, not an aggregation of contained function/class summaries. If the LLM returns non-JSON the response degrades to a deterministic structural summary (kind: structural-fallback) built from the entity source, and that fallback is cached so a retry is a free cache hit rather than a re-billed failure.",
             input_schema: id_schema(),
         },
         ToolDefinition {
             name: "issues_for",
-            description: "Return Filigree issues attached to this Clarion entity, optionally including issues attached to contained entities. Filigree is an enrichment source; if unavailable, the tool returns an unavailable envelope instead of failing Clarion.",
+            description: "Return Filigree issues attached to this Clarion entity, optionally including issues attached to contained entities. Filigree is an enrichment source; if unavailable, the tool returns an unavailable envelope instead of failing Clarion. The result carries a result_kind (matched | no_matches | unavailable) so a reachable-but-empty Filigree is distinct from an unreachable one, and a filigree_endpoint block (configured vs resolved URL + resolution_source) so you can see which endpoint — e.g. a live ethereal port — the answer came from. Each matched/drifted entry carries an `issue` object with the issue's title, status, and priority (fetched once per distinct issue, no N+1); `issue` is null when the issue-detail route is unavailable, so the match still resolves without a second hop into Filigree.",
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -117,7 +167,7 @@ pub fn list_tools() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "neighborhood",
-            description: "Return the one-hop Clarion neighborhood around an entity: callers, callees, container, contained entities, and references. Default confidence is resolved; ambiguous and inferred calls are opt-in. References are not execution flow.",
+            description: "Return the one-hop Clarion neighborhood around an entity: callers, callees, container, contained entities, references, and imports (imports_in = who imports this module, imports_out = what it imports; module-to-module). Default confidence is resolved; ambiguous and inferred calls are opt-in. References and imports are not execution flow. When the entity is a module, references_in/references_out are rolled up over the symbols it contains (references_rolled_up=true) — each neighbor carries a `via` naming the contained symbol the edge touches, so \"who imports this module/contract\" is answered at module altitude rather than reading empty. On references_in each rolled-up neighbor also carries `importer_module` — the importing symbol's containing module — so reverse-import names importing modules, not just symbols. The result carries scope_excludes naming blind spots not searched (e.g. attribute-receiver-calls) so empty sections are never read as guaranteed true negatives.",
             input_schema: id_confidence_schema(),
         },
         ToolDefinition {
@@ -125,6 +175,111 @@ pub fn list_tools() -> Vec<ToolDefinition> {
             description: "List module entities assigned to a subsystem entity.",
             input_schema: id_schema(),
         },
+        ToolDefinition {
+            name: "subsystem_of",
+            description: "Return the subsystem an entity belongs to — the reverse of subsystem_members. Accepts any entity id: a module resolves directly, while a function/class resolves through its nearest containing module. Returns the subsystem id/name and the module the membership was resolved through, or a no-subsystem result when the entity has no subsystem-assigned module ancestor.",
+            input_schema: id_schema(),
+        },
+        ToolDefinition {
+            name: "project_status",
+            description: "Return deterministic Clarion diagnostics: repo root, db path, latest run (id/status/started/completed), entity/subsystem/edge/finding/briefing-blocked counts, index staleness, per-plugin entity counts from the current index, LLM policy (provider/live/cache), and the resolved Filigree endpoint (configured vs resolved URL + resolution source). Answers \"is the graph fresh, plugin-less, LLM-live, Filigree-reachable?\" without shelling out. No LLM call.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "summary_preview_cost",
+            description: "Preview what calling summary(id) would cost BEFORE spending. Reports cache_status (hit | expired | miss), the cached row's real tokens/cost/age on a hit, an input-token estimate on a miss, the configured model, the LLM policy (provider/live/allow_live_provider/cache horizon), and live_spend_would_occur — true only when no fresh cache row exists AND a live provider is wired. A disabled/unconfigured LLM is reported distinctly from a cache miss. Never invokes the LLM provider.",
+            input_schema: id_schema(),
+        },
+        ToolDefinition {
+            name: "source_for_entity",
+            description: "Return the exact indexed source span for one entity (its source_line_start..source_line_end, which includes any decorators/signature/docstring the plugin captured) plus a bounded window of surrounding context, as line-numbered lines each flagged in_entity true/false. No LLM call. Lets an agent read and trust the entity without shelling out. source_status reports `ok`, or — instead of a misleading stale snippet — `missing` (file gone), `no_range`/`no_source_path` (entity has no anchor), `binary` (non-UTF-8), or `drifted` (the file no longer matches the indexed content_hash; rerun `clarion analyze`). context_lines defaults to 10.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "minLength": 1},
+                    "context_lines": {"type": "integer", "minimum": 0, "maximum": 200}
+                },
+                "required": ["id"],
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "call_sites",
+            description: "Show the actual source sites behind calls/references edges, so an agent can see WHY Clarion believes an edge exists rather than trusting it blind. role=caller (default) returns this entity's outgoing sites (what it calls/references); role=callee returns incoming sites (who calls/references it). Each site carries the file path, 1-based line, byte column, the source line text, edge kind, confidence, and a resolution of resolved | ambiguous (with candidate ids) | unresolved (a static call Clarion could not bind, kept separate so it is never mixed with resolved evidence). Filter by edge kind (`calls`/`references`) and by a best-effort production/test path heuristic (`all`/`production`/`test`; path partitioning is not indexed — the heuristic matches conventional test paths). Output is bounded; truncated flags when the site cap trims. No LLM call.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "minLength": 1},
+                    "role": {"type": "string", "enum": ["caller", "callee"], "default": "caller"},
+                    "kind": {"type": "string", "enum": ["calls", "references"]},
+                    "confidence": confidence_schema(),
+                    "path": {"type": "string", "enum": ["all", "production", "test"], "default": "all"}
+                },
+                "required": ["id"],
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "orientation_pack",
+            description: "Assemble one deterministic orientation packet for a code location — the replacement for hand-composing find_entity + entity_at + source reads + neighborhood + issues_for + freshness on every question. Resolve EITHER by `entity` id OR by `file`+`line` (exactly one form). The packet bundles: the primary entity, the entity_context evidence (match_reason / containing stack / decl-body-decorator ranges — so a decorator-line query is explained, not guessed), a compact source-span summary, one-hop neighbors (callers, callees, container, contained, references, imports — for a module, references_in/out are rolled up over contained symbols with references_rolled_up=true), compact resolved execution paths, related Filigree issues, index/Filigree/LLM health, warnings, and suggested next reads. No LLM summary is invoked. Every list is bounded; an `omitted` block reports per-section truncation counts and `degraded` sections name surfaces that were unavailable (e.g. Filigree down) so an empty section is never read as a guaranteed negative.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "entity": {"type": "string", "minLength": 1},
+                    "file": {"type": "string", "minLength": 1},
+                    "line": {"type": "integer", "minimum": 1}
+                },
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "analyze_start",
+            description: "Start a `clarion analyze` run over this project in the background and return its run handle immediately — do not block on the (possibly many-minute) run. Re-indexes the source tree and refreshes entities/edges/subsystems. Returns run_id, status (`started`), and the progress-file path. Only one analyze may run per project at a time (a cross-process lock enforces it); a second start while one is active is rejected. Poll analyze_status for progress; analyze_cancel to stop. No arguments.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "analyze_status",
+            description: "Report the live status of an analyze run started via analyze_start. status is one of queued (spawned, not yet recording) | running | completed | failed | cancelled | skipped_no_plugins. While running it exposes phase (discovering / analyzing / clustering), current_plugin, processed_files / total_files, current_file, the latest heartbeat_at, elapsed_seconds, and progress_observed (false when the heartbeat has gone stale — the run may be wedged). On a terminal status it carries the recorded run stats. Reads structured progress, never logs.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "run_id": {"type": "string", "minLength": 1}
+                },
+                "required": ["run_id"],
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "analyze_cancel",
+            description: "Cancel a running analyze. SIGKILLs the run's whole process group — terminating the language plugin and its pyright-langserver child — then marks the run terminal (status `cancelled`) so it is never left dangling as `running`. Idempotent: cancelling an already-terminal run reports its current state. Partial work already written is kept (cancel discards in-flight work, not the index).",
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "run_id": {"type": "string", "minLength": 1}
+                },
+                "required": ["run_id"],
+                "additionalProperties": false
+            }),
+        },
+        ToolDefinition {
+            name: "index_diff",
+            description: "Report what changed since the last analyze and whether this checkout is newer than the graph — so an agent need not hand-roll git + mtime freshness checks. Compares: analyzed_at (last completed run) vs current git HEAD (with head_newer_than_analyze derived from HEAD's committer date vs run completion, true even when source mtimes are ambiguous); indexed source files modified or now-missing since analyze; dirty working-tree files flagged when they touch an indexed path; and per-run aggregate plugin skip/drop counters. Git is read at query time, read-only, and fail-soft: a missing git binary or non-repo dir degrades to git.available=false with a reason rather than failing. analyzed_commit is null by design (Clarion persists no analyze-time SHA). overall is fresh | drift | unknown | never_analyzed; lists are bounded with an `omitted` block. entity-level add/remove/change diff is unavailable in v0.1 (only the current graph is retained). No LLM call.",
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 2000}
+                },
+                "additionalProperties": false
+            }),
+        },
     ]
 }
 
@@ -161,16 +316,23 @@ fn id_confidence_schema() -> Value {
 
 /// Handle state-free MCP requests such as `initialize` and `tools/list`.
 ///
-/// Storage-backed tool calls require [`ServerState::handle_json_rpc`].
+/// Storage-backed tool calls require [`ServerState::handle_json_rpc`]. The
+/// `resources/*` and `prompts/*` RPCs are likewise served ONLY by
+/// [`ServerState::handle_json_rpc`] (the production `clarion serve` path); a
+/// caller using this free function gets a deliberately narrower server, and its
+/// `initialize` advertises only the `tools` capability it actually serves.
 #[must_use]
-pub fn handle_json_rpc(request: &Value) -> Value {
+pub fn handle_json_rpc(request: &Value) -> Option<Value> {
+    if is_json_rpc_notification(request) {
+        return None;
+    }
     let id = request.get("id").cloned().unwrap_or(Value::Null);
     let Some(method) = request.get("method").and_then(Value::as_str) else {
-        return error_response(&id, -32600, "invalid request");
+        return Some(error_response(&id, -32600, "invalid request"));
     };
 
-    match method {
-        "initialize" => result_response(&id, &initialize_result()),
+    Some(match method {
+        "initialize" => result_response(&id, &initialize_result(false)),
         "tools/list" => result_response(&id, &json!({"tools": list_tools()})),
         "tools/call" => error_response(
             &id,
@@ -178,18 +340,51 @@ pub fn handle_json_rpc(request: &Value) -> Value {
             "tools/call requires ServerState::handle_json_rpc",
         ),
         _ => error_response(&id, -32601, "method not found"),
-    }
+    })
+}
+
+/// Deterministic, non-storage diagnostics threaded in at server construction so
+/// `project_status` can report the LLM policy and the resolved Filigree
+/// endpoint without re-reading config or re-running URL resolution. Optional:
+/// servers built via [`ServerState::new`] (e.g. storage-only tests) omit it and
+/// `project_status` reports those blocks as unconfigured.
+#[derive(Debug, Clone)]
+pub struct DiagnosticsContext {
+    pub llm: LlmDiagnostics,
+    pub filigree: crate::filigree_url::FiligreeUrlResolution,
+}
+
+/// The LLM policy posture, captured at construction. `live` reflects whether a
+/// provider is actually wired (vs. merely permitted by config).
+#[derive(Debug, Clone)]
+pub struct LlmDiagnostics {
+    /// Provider label, e.g. `"openrouter"`, `"codex_cli"`, `"recording"`, or
+    /// `"disabled"` when no provider is wired.
+    pub provider: String,
+    /// A live provider is wired and summaries will dispatch to it.
+    pub live: bool,
+    /// Whether config permits a live provider at all (`llm.allow_live_provider`).
+    pub allow_live_provider: bool,
+    /// Summary-cache freshness horizon in days (`llm.cache_max_age_days`).
+    pub cache_max_age_days: u32,
 }
 
 pub struct ServerState {
     project_root: PathBuf,
     readers: ReaderPool,
     execution_edge_cap: usize,
+    execution_path_cap: usize,
     summary_llm: Option<SummaryLlmState>,
     clock: Arc<dyn Fn() -> String + Send + Sync>,
     budget: Arc<Mutex<BudgetLedger>>,
     inferred_inflight: InferredInflight,
     filigree_client: Option<Arc<dyn FiligreeLookup>>,
+    diagnostics: Option<DiagnosticsContext>,
+    /// Supervised `clarion analyze` runs launched via `analyze_start`.
+    analyze_runs: crate::analyze_runs::RunRegistry,
+    /// Launcher for `analyze_start` to spawn. `None` → `current_exe()`; tests
+    /// inject a stub via [`ServerState::with_analyze_command`].
+    analyze_program: Option<PathBuf>,
 }
 
 impl ServerState {
@@ -199,20 +394,51 @@ impl ServerState {
             project_root,
             readers,
             execution_edge_cap: 500,
+            execution_path_cap: 200,
             summary_llm: None,
             clock: Arc::new(default_now_string),
             budget: Arc::new(Mutex::new(BudgetLedger::default())),
             inferred_inflight: Arc::new(AsyncMutex::new(HashMap::new())),
             filigree_client: None,
+            diagnostics: None,
+            analyze_runs: Arc::new(Mutex::new(HashMap::new())),
+            analyze_program: None,
         }
     }
 
+    /// Override the program `analyze_start` launches (default: `current_exe()`).
+    /// Tests inject a stub binary so the lifecycle can be exercised without a
+    /// full analyze run.
+    #[must_use]
+    pub fn with_analyze_command(mut self, program: PathBuf) -> Self {
+        self.analyze_program = Some(program);
+        self
+    }
+
+    /// Test-only: number of analyze run handles currently held in the registry.
+    /// Lets a test assert that finished runs are evicted (clarion-7e0c21558a)
+    /// rather than accumulating across a long-lived `serve`.
+    #[doc(hidden)]
+    #[must_use]
+    pub fn tracked_analyze_runs(&self) -> usize {
+        self.analyze_runs
+            .lock()
+            .expect("analyze run registry mutex")
+            .len()
+    }
+
     #[must_use]
     pub fn with_edge_cap(mut self, execution_edge_cap: usize) -> Self {
         self.execution_edge_cap = execution_edge_cap;
         self
     }
 
+    #[must_use]
+    pub fn with_path_cap(mut self, execution_path_cap: usize) -> Self {
+        self.execution_path_cap = execution_path_cap;
+        self
+    }
+
     #[must_use]
     pub fn with_summary_llm(
         mut self,
@@ -240,18 +466,31 @@ impl ServerState {
         self
     }
 
-    pub async fn handle_json_rpc(&self, request: &Value) -> Value {
+    #[must_use]
+    pub fn with_diagnostics(mut self, diagnostics: DiagnosticsContext) -> Self {
+        self.diagnostics = Some(diagnostics);
+        self
+    }
+
+    pub async fn handle_json_rpc(&self, request: &Value) -> Option<Value> {
+        if is_json_rpc_notification(request) {
+            return None;
+        }
         let id = request.get("id").cloned().unwrap_or(Value::Null);
         let Some(method) = request.get("method").and_then(Value::as_str) else {
-            return error_response(&id, -32600, "invalid request");
+            return Some(error_response(&id, -32600, "invalid request"));
         };
 
-        match method {
-            "initialize" => result_response(&id, &initialize_result()),
+        Some(match method {
+            "initialize" => result_response(&id, &initialize_result(true)),
             "tools/list" => result_response(&id, &json!({"tools": list_tools()})),
             "tools/call" => self.handle_tool_call(&id, request.get("params")).await,
+            "resources/list" => result_response(&id, &resources_list()),
+            "resources/read" => self.handle_resources_read(&id, request.get("params")).await,
+            "prompts/list" => result_response(&id, &prompts_list()),
+            "prompts/get" => prompts_get(&id, request.get("params")),
             _ => error_response(&id, -32601, "method not found"),
-        }
+        })
     }
 
     async fn handle_tool_call(&self, id: &Value, params: Option<&Value>) -> Value {
@@ -306,12 +545,104 @@ impl ServerState {
                 Ok(value) => value,
                 Err(response) => return response.to_json_rpc(id),
             },
+            "subsystem_of" => match self.tool_subsystem_of(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "project_status" => match self.tool_project_status(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "summary_preview_cost" => match self.tool_summary_preview_cost(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "source_for_entity" => match self.tool_source_for_entity(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "call_sites" => match self.tool_call_sites(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "orientation_pack" => match self.tool_orientation_pack(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "analyze_start" => match self.tool_analyze_start(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "analyze_status" => match self.tool_analyze_status(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "analyze_cancel" => match self.tool_analyze_cancel(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
+            "index_diff" => match self.tool_index_diff(arguments).await {
+                Ok(value) => value,
+                Err(response) => return response.to_json_rpc(id),
+            },
             _ => unreachable!("known tools checked above"),
         };
 
         tool_json_rpc_response(id, &envelope)
     }
 
+    async fn handle_resources_read(&self, id: &Value, params: Option<&Value>) -> Value {
+        let Some(uri) = params
+            .and_then(Value::as_object)
+            .and_then(|p| p.get("uri"))
+            .and_then(Value::as_str)
+        else {
+            return error_response(id, -32602, "invalid resources/read params: missing uri");
+        };
+        if uri != "clarion://context" {
+            return error_response(id, -32602, &format!("unknown resource: {uri}"));
+        }
+        let snapshot_json = self.context_snapshot_json().await;
+        result_response(
+            id,
+            &json!({
+                "contents": [
+                    {
+                        "uri": "clarion://context",
+                        "mimeType": "application/json",
+                        "text": snapshot_json
+                    }
+                ]
+            }),
+        )
+    }
+
+    async fn context_snapshot_json(&self) -> String {
+        // Single fallback used by both the reader-error and serialize-error
+        // branches: serialize a real `ProjectSnapshot` so the shape stays in
+        // lock-step with the type as it gains fields. `degraded: true` — this
+        // path is only reached when the reader pool errored or a healthy
+        // snapshot failed to serialize, so the consumer must not read the zero
+        // counts as a genuinely empty index.
+        let fallback = || {
+            let snap = crate::snapshot::unreadable_db_snapshot();
+            serde_json::to_string(&snap).unwrap_or_default()
+        };
+
+        let project_root = self.project_root.clone();
+        let snapshot = self
+            .readers
+            .with_reader(move |conn| Ok(crate::snapshot::project_snapshot(conn, &project_root)))
+            .await;
+        match snapshot {
+            Ok(snap) => serde_json::to_string(&snap).unwrap_or_else(|_| fallback()),
+            Err(err) => {
+                tracing::warn!(error = %err, "clarion://context snapshot failed");
+                fallback()
+            }
+        }
+    }
+
     async fn tool_entity_at(
         &self,
         arguments: &serde_json::Map<String, Value>,
@@ -327,11 +658,29 @@ impl ServerState {
                 return Ok(tool_error_envelope("invalid-path", &err.to_string(), false));
             }
         };
+        let project_root = self.project_root.clone();
         let result = self
             .readers
             .with_reader(move |conn| {
-                let entity = entity_at_line(conn, &normalized, line)?;
-                Ok(json!({"entity": entity.as_ref().map(entity_json)}))
+                // Every entity whose span contains the line, innermost first
+                // (same ordering as the legacy single-row `entity_at_line`).
+                let candidates = entities_containing_line(conn, &normalized, line)?;
+                let matched = candidates.first().cloned();
+                let stack = match &matched {
+                    Some(entity) => ancestor_chain(conn, &entity.id)?,
+                    None => Vec::new(),
+                };
+                let snapshot = crate::snapshot::project_snapshot(conn, &project_root);
+                Ok(json!({
+                    "entity": matched.as_ref().map(entity_json),
+                    "entity_context": entity_context_json(
+                        Some(line),
+                        matched.as_ref(),
+                        &candidates,
+                        &stack,
+                        &snapshot,
+                    ),
+                }))
             })
             .await;
         Ok(envelope_from_storage_result(result))
@@ -352,10 +701,27 @@ impl ServerState {
                 .map_err(|_| ParamError::new("cursor must be a numeric offset"))?,
             _ => return Err(ParamError::new("cursor must be a string or null")),
         };
+        // Optional exact-match entity-kind filter (e.g. "subsystem"). Omitting it
+        // preserves the unfiltered search. Validated as a non-blank string here;
+        // unknown kinds simply match nothing (kinds are plugin-owned).
+        let kind = match arguments.get("kind") {
+            None | Some(Value::Null) => None,
+            Some(Value::String(kind)) if !kind.trim().is_empty() => Some(kind.clone()),
+            Some(Value::String(_)) => {
+                return Err(ParamError::new("kind must be a non-empty string"));
+            }
+            _ => return Err(ParamError::new("kind must be a string or null")),
+        };
         let result = self
             .readers
             .with_reader(move |conn| {
-                let mut rows = find_entities(conn, &pattern, limit.saturating_add(1), offset)?;
+                let mut rows = find_entities(
+                    conn,
+                    &pattern,
+                    limit.saturating_add(1),
+                    offset,
+                    kind.as_deref(),
+                )?;
                 let has_more = rows.len() > limit;
                 rows.truncate(limit);
                 let next_cursor = if has_more {
@@ -401,7 +767,10 @@ impl ServerState {
                     .filter_map(|edge| caller_json(conn, &edge).transpose())
                     .collect::<Result<Vec<_>, StorageError>>()?;
                 Ok(success_envelope_with_stats(
-                    json!({"callers": callers}),
+                    json!({
+                        "callers": callers,
+                        "scope_excludes": call_graph_scope_excludes(confidence),
+                    }),
                     stats_delta,
                 ))
             })
@@ -422,6 +791,7 @@ impl ServerState {
             return Ok(self.inferred_execution_paths(entity_id, max_depth).await);
         }
         let edge_cap = self.execution_edge_cap;
+        let path_cap = self.execution_path_cap;
         let result = self
             .readers
             .with_reader(move |conn| {
@@ -435,17 +805,18 @@ impl ServerState {
                 let mut traversal = PathTraversal::new(edge_cap);
                 let mut path = vec![entity_id.clone()];
                 traversal.walk(conn, &entity_id, &mut path, max_depth, confidence)?;
-                let paths = traversal
-                    .paths
-                    .iter()
-                    .map(|path| path_json(conn, path))
-                    .collect::<Result<Vec<_>, StorageError>>()?;
+                let edge_truncated = traversal.truncated;
+                let edge_count_visited = traversal.edge_count_visited;
+                let compact = compact_execution_paths(conn, traversal.paths, path_cap)?;
                 Ok(success_envelope_with_truncation(
                     json!({
-                        "paths": paths,
-                        "edge_count_visited": traversal.edge_count_visited
+                        "root": entity_id,
+                        "nodes": compact.nodes,
+                        "paths": compact.paths,
+                        "edge_count_visited": edge_count_visited,
+                        "scope_excludes": call_graph_scope_excludes(confidence),
                     }),
-                    traversal.truncated.then_some("edge-cap"),
+                    path_truncation_reason(edge_truncated, compact.path_cap_truncated),
                 ))
             })
             .await;
@@ -478,6 +849,7 @@ impl ServerState {
             }
         }
 
+        let root = entity_id.clone();
         let mut stats = InferredDispatchStats::default();
         let mut dispatched_callers = BTreeSet::new();
         let mut stack = vec![(entity_id.clone(), vec![entity_id], max_depth)];
@@ -528,22 +900,21 @@ impl ServerState {
             }
         }
 
-        let resolved_paths = self
+        let path_cap = self.execution_path_cap;
+        let compacted = self
             .readers
-            .with_reader(move |conn| {
-                paths
-                    .iter()
-                    .map(|path| path_json(conn, path))
-                    .collect::<Result<Vec<_>, StorageError>>()
-            })
+            .with_reader(move |conn| compact_execution_paths(conn, paths, path_cap))
             .await;
-        match resolved_paths {
-            Ok(paths) => success_envelope_with_truncation_and_stats(
+        match compacted {
+            Ok(compact) => success_envelope_with_truncation_and_stats(
                 json!({
-                    "paths": paths,
-                    "edge_count_visited": edge_count_visited
+                    "root": root,
+                    "nodes": compact.nodes,
+                    "paths": compact.paths,
+                    "edge_count_visited": edge_count_visited,
+                    "scope_excludes": call_graph_scope_excludes(EdgeConfidence::Inferred),
                 }),
-                truncated.then_some("edge-cap"),
+                path_truncation_reason(truncated, compact.path_cap_truncated),
                 stats.to_json(),
             ),
             Err(err) => {
@@ -596,9 +967,21 @@ impl ServerState {
                     .filter_map(|child_id| entity_by_id(conn, child_id).transpose())
                     .map(|row| row.map(|entity| entity_json(&entity)))
                     .collect::<Result<Vec<_>, StorageError>>()?;
-                let references_in = reference_neighbors(conn, &entity_id, ReferenceDirection::In)?;
-                let references_out =
-                    reference_neighbors(conn, &entity_id, ReferenceDirection::Out)?;
+                let (references_in, references_rolled_up) = reference_neighbors_for(
+                    conn,
+                    &entity_id,
+                    &entity.kind,
+                    ReferenceDirection::In,
+                )?;
+                let (references_out, _) = reference_neighbors_for(
+                    conn,
+                    &entity_id,
+                    &entity.kind,
+                    ReferenceDirection::Out,
+                )?;
+                let imports_in = import_neighbors(conn, &entity_id, ReferenceDirection::In)?;
+                let imports_out = import_neighbors(conn, &entity_id, ReferenceDirection::Out)?;
+                let scope_excludes = call_graph_scope_excludes(confidence);
                 Ok(success_envelope(json!({
                     "entity": entity_json(&entity),
                     "callers": inbound_callers,
@@ -606,7 +989,15 @@ impl ServerState {
                     "container": container_entity,
                     "contained": contained_entities,
                     "references_in": references_in,
-                    "references_out": references_out
+                    "references_out": references_out,
+                    // True when the entity is a module and references_in/out
+                    // aggregate contained symbols' edges (each neighbor tagged
+                    // with a `via` symbol); false for symbol-level entities
+                    // whose references are direct (clarion-79d0ff6e14).
+                    "references_rolled_up": references_rolled_up,
+                    "imports_in": imports_in,
+                    "imports_out": imports_out,
+                    "scope_excludes": scope_excludes,
                 })))
             })
             .await;
@@ -619,8 +1010,15 @@ impl ServerState {
     ) -> std::result::Result<Value, ParamError> {
         let entity_id = required_str(arguments, "id")?.to_owned();
         let include_contained = optional_bool(arguments, "include_contained")?.unwrap_or(true);
+        // Surface the same configured-vs-resolved Filigree endpoint block that
+        // `project_status` reports, so an agent can see WHICH endpoint a result
+        // came from (e.g. an ethereal port resolved from
+        // `.filigree/ephemeral.port`) instead of curling ports by hand. Null on
+        // storage-only servers built without a diagnostics context.
+        let endpoint = self.filigree_diagnostics_json();
         let Some(client) = self.filigree_client.clone() else {
             return Ok(issues_unavailable(
+                &endpoint,
                 "filigree-disabled",
                 "Filigree integration is disabled",
             ));
@@ -632,6 +1030,7 @@ impl ServerState {
             Ok(Some(read)) => read,
             Ok(None) => {
                 return Ok(issues_unavailable(
+                    &endpoint,
                     "entity-not-found",
                     "Clarion entity was not found",
                 ));
@@ -656,10 +1055,15 @@ impl ServerState {
             {
                 Ok(Ok(response)) => response,
                 Ok(Err(err)) => {
-                    return Ok(issues_unavailable("filigree-unreachable", &err.to_string()));
+                    return Ok(issues_unavailable(
+                        &endpoint,
+                        "filigree-unreachable",
+                        &err.to_string(),
+                    ));
                 }
                 Err(err) => {
                     return Ok(issues_unavailable(
+                        &endpoint,
                         "filigree-client-error",
                         &format!("Filigree client task failed: {err}"),
                     ));
@@ -675,7 +1079,50 @@ impl ServerState {
                 break;
             }
         }
-        Ok(accumulator.into_envelope(read.entity_cap_truncated, requests_total))
+        // Enrich matched/drifted entries with each issue's title/status/priority.
+        // Every unique issue is fetched exactly once (the accumulator already
+        // dedupes issue_ids, so this is N requests for N distinct issues, never
+        // per-entity N+1). Enrichment is best-effort and enrich-only: a 404
+        // (issue/route absent) leaves that entry's `issue` null, and the first
+        // transport/HTTP failure trips `route_down` so we stop hammering an
+        // endpoint that has gone away rather than failing the whole call.
+        let detail_ids = accumulator.enrichable_issue_ids();
+        let mut details: HashMap<String, Option<IssueDetail>> = HashMap::new();
+        let mut detail_requests_total = 0_usize;
+        let mut route_down = false;
+        for issue_id in detail_ids {
+            if route_down {
+                details.insert(issue_id, None);
+                continue;
+            }
+            let client = client.clone();
+            let id_for_task = issue_id.clone();
+            let fetched =
+                tokio::task::spawn_blocking(move || client.issue_detail(&id_for_task)).await;
+            detail_requests_total += 1;
+            match fetched {
+                Ok(Ok(detail)) => {
+                    details.insert(issue_id, detail);
+                }
+                Ok(Err(err)) => {
+                    tracing::warn!(error = %err, "clarion issues_for detail fetch failed; degrading to issue-id-only");
+                    route_down = true;
+                    details.insert(issue_id, None);
+                }
+                Err(err) => {
+                    tracing::warn!(error = %err, "clarion issues_for detail task failed; degrading to issue-id-only");
+                    route_down = true;
+                    details.insert(issue_id, None);
+                }
+            }
+        }
+        accumulator.apply_issue_details(&details);
+        Ok(accumulator.into_envelope(
+            read.entity_cap_truncated,
+            requests_total,
+            detail_requests_total,
+            &endpoint,
+        ))
     }
 
     async fn tool_subsystem_members(
@@ -724,69 +1171,1121 @@ impl ServerState {
         Ok(flatten_storage_envelope_result(result))
     }
 
-    async fn read_issues_for_entities(
+    async fn tool_subsystem_of(
         &self,
-        entity_id: String,
-        include_contained: bool,
-    ) -> Result<Option<IssuesForRead>, StorageError> {
-        self.readers
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let entity_id = required_str(arguments, "id")?.to_owned();
+        let result = self
+            .readers
             .with_reader(move |conn| {
-                let Some(root) = entity_by_id(conn, &entity_id)? else {
-                    return Ok(None);
+                let Some(entity) = entity_by_id(conn, &entity_id)? else {
+                    return Ok(tool_error_envelope(
+                        "entity-not-found",
+                        &format!("entity {entity_id} was not found"),
+                        false,
+                    ));
                 };
-                let mut ids = vec![root.id.clone()];
-                let mut entity_cap_truncated = false;
-                if include_contained {
-                    let contained = contained_entity_ids(conn, &entity_id, 1_000)?;
-                    entity_cap_truncated = contained.truncated;
-                    ids.extend(contained.entity_ids);
-                }
-                let mut entities = Vec::with_capacity(ids.len());
-                for id in ids {
-                    if let Some(entity) = entity_by_id(conn, &id)? {
-                        entities.push(entity);
-                    }
-                }
-                Ok(Some(IssuesForRead {
-                    entities,
-                    entity_cap_truncated,
-                }))
+                let Some(found) = subsystem_of_entity(conn, &entity.id)? else {
+                    // Entity exists but has no subsystem-assigned module ancestor.
+                    // A structural fact, not an error — return a success envelope
+                    // with subsystem: null so an agent can distinguish it from a
+                    // missing entity.
+                    return Ok(success_envelope(json!({
+                        "entity": {"id": entity.id, "kind": entity.kind},
+                        "subsystem": Value::Null,
+                        "via_module_id": Value::Null
+                    })));
+                };
+                let subsystem = entity_by_id(conn, &found.subsystem_id)?;
+                Ok(success_envelope(json!({
+                    "entity": {"id": entity.id, "kind": entity.kind},
+                    "subsystem": subsystem.as_ref().map(|s| json!({
+                        "id": s.id,
+                        "name": s.name,
+                        "short_name": s.short_name,
+                        "properties": entity_properties_json(s)
+                    })),
+                    "via_module_id": found.via_module_id
+                })))
             })
-            .await
+            .await;
+        Ok(flatten_storage_envelope_result(result))
     }
 
-    async fn tool_summary(
+    async fn tool_call_sites(
         &self,
         arguments: &serde_json::Map<String, Value>,
     ) -> std::result::Result<Value, ParamError> {
         let entity_id = required_str(arguments, "id")?.to_owned();
-        let now = (self.clock)();
-        let read = match self
-            .read_summary_inputs(entity_id, self.summary_model_id())
-            .await
-        {
-            Ok(read) => read,
-            Err(err) => {
-                return Ok(tool_error_envelope(
-                    "storage-error",
-                    &err.to_string(),
-                    storage_retryable(&err),
+        let role = match arguments.get("role") {
+            None | Some(Value::Null) => CallSiteRole::Caller,
+            Some(Value::String(s)) if s == "caller" => CallSiteRole::Caller,
+            Some(Value::String(s)) if s == "callee" => CallSiteRole::Callee,
+            _ => return Err(ParamError::new("role must be \"caller\" or \"callee\"")),
+        };
+        let kind = match arguments.get("kind") {
+            None | Some(Value::Null) => CallSiteKind::Both,
+            Some(Value::String(s)) if s == "calls" => CallSiteKind::Calls,
+            Some(Value::String(s)) if s == "references" => CallSiteKind::References,
+            _ => return Err(ParamError::new("kind must be \"calls\" or \"references\"")),
+        };
+        let path = match arguments.get("path") {
+            None | Some(Value::Null) => PathScope::All,
+            Some(Value::String(s)) if s == "all" => PathScope::All,
+            Some(Value::String(s)) if s == "production" => PathScope::Production,
+            Some(Value::String(s)) if s == "test" => PathScope::Test,
+            _ => {
+                return Err(ParamError::new(
+                    "path must be \"all\", \"production\", or \"test\"",
                 ));
             }
         };
-
-        let SummaryRead::Ready(ready) = read else {
-            return Ok(summary_read_error(read));
-        };
-
-        if let Some(envelope) = self.cached_summary_envelope(&ready, &now).await {
-            return Ok(envelope);
+        let confidence = optional_confidence(arguments)?;
+        let result = self
+            .readers
+            .with_reader(move |conn| {
+                build_call_sites(conn, &entity_id, role, kind, confidence, path)
+            })
+            .await;
+        match result {
+            Ok(Some(value)) => Ok(success_envelope(value)),
+            Ok(None) => Ok(tool_error_envelope(
+                "not-found",
+                "no entity with the given id",
+                false,
+            )),
+            Err(err) => Ok(tool_error_envelope(
+                "storage-error",
+                &err.to_string(),
+                storage_retryable(&err),
+            )),
         }
+    }
 
-        if self.summary_budget_blocked() {
-            return Ok(token_ceiling_envelope(
-                "LLM session token ceiling has been reached",
-            ));
+    #[allow(clippy::too_many_lines, clippy::similar_names)]
+    async fn tool_orientation_pack(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        // Exactly one resolution form: an `entity` id, or a `file` + `line`.
+        let entity_arg = arguments
+            .get("entity")
+            .and_then(Value::as_str)
+            .filter(|value| !value.is_empty());
+        let file_arg = arguments
+            .get("file")
+            .and_then(Value::as_str)
+            .filter(|value| !value.is_empty());
+        let has_line = arguments.get("line").is_some();
+
+        // `query_line == Some` selects the file/line form; `None` the entity form.
+        let (query_line, normalized_path, entity_id_arg) = match (entity_arg, file_arg, has_line) {
+            (Some(id), None, false) => (None, None, Some(id.to_owned())),
+            (None, Some(file), true) => {
+                let line = required_i64(arguments, "line")?;
+                if line <= 0 {
+                    return Err(ParamError::new("line must be a positive integer"));
+                }
+                match normalize_source_path(&self.project_root, file) {
+                    Ok(path) => (Some(line), Some(path), None),
+                    Err(err) => {
+                        return Ok(tool_error_envelope("invalid-path", &err.to_string(), false));
+                    }
+                }
+            }
+            _ => {
+                return Err(ParamError::new(
+                    "provide exactly one of: `entity` (id), or `file` + `line`",
+                ));
+            }
+        };
+
+        let project_root = self.project_root.clone();
+        let edge_cap = self.execution_edge_cap;
+        let path_cap = self.execution_path_cap;
+
+        let core = self
+            .readers
+            .with_reader(move |conn| {
+                // Resolve the primary entity. The file/line form additionally
+                // yields the containing candidate set for ambiguity reporting.
+                let (matched, candidates) = if let Some(line) = query_line {
+                    let path = normalized_path.as_deref().unwrap_or_default();
+                    let candidates = entities_containing_line(conn, path, line)?;
+                    (candidates.first().cloned(), candidates)
+                } else {
+                    let id = entity_id_arg.as_deref().unwrap_or_default();
+                    match entity_by_id(conn, id)? {
+                        Some(entity) => (Some(entity.clone()), vec![entity]),
+                        None => (None, Vec::new()),
+                    }
+                };
+
+                let snapshot = crate::snapshot::project_snapshot(conn, &project_root);
+                let freshness = json!({
+                    "staleness": snapshot.staleness(),
+                    "last_analyzed_at": snapshot.last_analyzed_at(),
+                    "degraded": snapshot.degraded(),
+                    "scan_truncated": snapshot.scan_truncated(),
+                });
+                let staleness_stale =
+                    matches!(snapshot.staleness(), crate::snapshot::Staleness::Stale);
+
+                let Some(entity) = matched else {
+                    return Ok(OrientationCore {
+                        primary_id: None,
+                        primary_kind: None,
+                        lookup_was_id: query_line.is_none(),
+                        packet: json!({
+                            "primary_entity": Value::Null,
+                            "entity_context":
+                                entity_context_json(query_line, None, &[], &[], &snapshot),
+                            "source": Value::Null,
+                            "neighbors": Value::Null,
+                            "execution_paths": Value::Null,
+                        }),
+                        freshness,
+                        staleness_stale,
+                        neighbors_omitted: serde_json::Map::new(),
+                        paths_truncation_reason: None,
+                    });
+                };
+
+                let ancestors = ancestor_chain(conn, &entity.id)?;
+                let entity_context = entity_context_json(
+                    query_line,
+                    Some(&entity),
+                    &candidates,
+                    &ancestors,
+                    &snapshot,
+                );
+
+                let source = json!({
+                    "source_file_path": entity.source_file_path,
+                    "source_line_start": entity.source_line_start,
+                    "source_line_end": entity.source_line_end,
+                    "line_count": match (entity.source_line_start, entity.source_line_end) {
+                        (Some(start), Some(end)) if end >= start => Some(end - start + 1),
+                        _ => None,
+                    },
+                    "content_hash": entity.content_hash,
+                });
+
+                // One-hop neighbors at resolved confidence, each bounded.
+                let confidence = EdgeConfidence::Resolved;
+                let callers_all = call_edges_targeting(conn, &entity.id, confidence)?
+                    .into_iter()
+                    .filter_map(|edge| caller_json(conn, &edge).transpose())
+                    .collect::<Result<Vec<_>, StorageError>>()?;
+                let callees_all = call_edges_from(conn, &entity.id, confidence)?
+                    .into_iter()
+                    .filter_map(|edge| callee_json(conn, &edge).transpose())
+                    .collect::<Result<Vec<_>, StorageError>>()?;
+                let container = entity
+                    .parent_id
+                    .as_deref()
+                    .and_then(|parent_id| entity_by_id(conn, parent_id).transpose())
+                    .transpose()?
+                    .as_ref()
+                    .map(entity_json);
+                let contained_all = child_entity_ids(conn, &entity.id)?
+                    .iter()
+                    .filter_map(|child_id| entity_by_id(conn, child_id).transpose())
+                    .map(|row| row.map(|entity| entity_json(&entity)))
+                    .collect::<Result<Vec<_>, StorageError>>()?;
+                let (refs_in, references_rolled_up) = reference_neighbors_for(
+                    conn,
+                    &entity.id,
+                    &entity.kind,
+                    ReferenceDirection::In,
+                )?;
+                let (refs_out, _) = reference_neighbors_for(
+                    conn,
+                    &entity.id,
+                    &entity.kind,
+                    ReferenceDirection::Out,
+                )?;
+                let imports_in = import_neighbors(conn, &entity.id, ReferenceDirection::In)?;
+                let imports_out = import_neighbors(conn, &entity.id, ReferenceDirection::Out)?;
+
+                let cap = ORIENTATION_PACK_MAX_NEIGHBORS;
+                let (callers, callers_omitted) = cap_neighbor_list(callers_all, cap);
+                let (callees, callees_omitted) = cap_neighbor_list(callees_all, cap);
+                let (contained, contained_omitted) = cap_neighbor_list(contained_all, cap);
+                let (references_in, refs_in_omitted) = cap_neighbor_list(refs_in, cap);
+                let (references_out, refs_out_omitted) = cap_neighbor_list(refs_out, cap);
+                let (imports_in, imports_in_omitted) = cap_neighbor_list(imports_in, cap);
+                let (imports_out, imports_out_omitted) = cap_neighbor_list(imports_out, cap);
+
+                let scope_excludes = call_graph_scope_excludes(confidence);
+
+                let neighbors = json!({
+                    "callers": callers,
+                    "callees": callees,
+                    "container": container,
+                    "contained": contained,
+                    "references_in": references_in,
+                    "references_out": references_out,
+                    // See `tool_neighborhood`: module references_in/out are
+                    // rolled up over contained symbols (clarion-79d0ff6e14).
+                    "references_rolled_up": references_rolled_up,
+                    "imports_in": imports_in,
+                    "imports_out": imports_out,
+                    "scope_excludes": scope_excludes,
+                });
+
+                // Compact resolved execution paths.
+                let mut traversal = PathTraversal::new(edge_cap);
+                let mut path = vec![entity.id.clone()];
+                traversal.walk(
+                    conn,
+                    &entity.id,
+                    &mut path,
+                    ORIENTATION_PACK_PATH_DEPTH,
+                    confidence,
+                )?;
+                let edge_truncated = traversal.truncated;
+                let edge_count_visited = traversal.edge_count_visited;
+                let compact = compact_execution_paths(conn, traversal.paths, path_cap)?;
+                let paths_truncation_reason =
+                    path_truncation_reason(edge_truncated, compact.path_cap_truncated);
+                let execution_paths = json!({
+                    "root": entity.id,
+                    "nodes": compact.nodes,
+                    "paths": compact.paths,
+                    "edge_count_visited": edge_count_visited,
+                    "truncated": paths_truncation_reason.is_some(),
+                    "truncation_reason": paths_truncation_reason,
+                });
+
+                let mut neighbors_omitted = serde_json::Map::new();
+                for (key, omitted) in [
+                    ("callers", callers_omitted),
+                    ("callees", callees_omitted),
+                    ("contained", contained_omitted),
+                    ("references_in", refs_in_omitted),
+                    ("references_out", refs_out_omitted),
+                    ("imports_in", imports_in_omitted),
+                    ("imports_out", imports_out_omitted),
+                ] {
+                    neighbors_omitted.insert(key.to_owned(), json!(omitted));
+                }
+
+                Ok(OrientationCore {
+                    primary_id: Some(entity.id.clone()),
+                    primary_kind: Some(entity.kind.clone()),
+                    lookup_was_id: query_line.is_none(),
+                    packet: json!({
+                        "primary_entity": entity_json(&entity),
+                        "entity_context": entity_context,
+                        "source": source,
+                        "neighbors": neighbors,
+                        "execution_paths": execution_paths,
+                    }),
+                    freshness,
+                    staleness_stale,
+                    neighbors_omitted,
+                    paths_truncation_reason: paths_truncation_reason.map(str::to_owned),
+                })
+            })
+            .await;
+
+        let core = match core {
+            Ok(core) => core,
+            Err(err) => {
+                return Ok(tool_error_envelope(
+                    "storage-error",
+                    &err.to_string(),
+                    storage_retryable(&err),
+                ));
+            }
+        };
+
+        // An `entity`-id lookup that resolved to nothing is a hard error; a
+        // file/line lookup that spans nothing degrades to a no_match packet.
+        if core.primary_id.is_none() && core.lookup_was_id {
+            return Ok(tool_error_envelope(
+                "entity-not-found",
+                "no entity with the given id",
+                false,
+            ));
+        }
+
+        // Related Filigree issues — reuse `issues_for` so its disabled /
+        // unreachable degradation paths are shared. Bounded to the primary
+        // entity (no contained fan-out) to keep the packet small.
+        let issues = if let Some(primary_id) = &core.primary_id {
+            let mut issue_args = serde_json::Map::new();
+            issue_args.insert("id".to_owned(), json!(primary_id));
+            issue_args.insert("include_contained".to_owned(), json!(false));
+            match self.tool_issues_for(&issue_args).await {
+                Ok(envelope) => envelope.get("result").cloned().unwrap_or(Value::Null),
+                Err(_) => json!({"available": false, "reason": "issues lookup failed"}),
+            }
+        } else {
+            json!({"available": false, "reason": "no primary entity at this location"})
+        };
+
+        let health = json!({
+            "index": core.freshness,
+            "filigree": self.filigree_diagnostics_json(),
+            "llm": self.llm_diagnostics_json(),
+        });
+
+        let neighbors_truncated = core
+            .neighbors_omitted
+            .values()
+            .any(|value| value.as_u64().unwrap_or(0) > 0);
+        let paths_truncated = core.paths_truncation_reason.is_some();
+
+        let mut warnings: Vec<String> = Vec::new();
+        if core.primary_id.is_none() {
+            warnings.push(
+                "No entity spans this location; only the enclosing scope (if any) is reported — \
+                 not a guaranteed absence of code."
+                    .to_owned(),
+            );
+        }
+        if core.staleness_stale {
+            warnings.push(
+                "Index is stale: at least one ingested source file is newer than the last \
+                 analyze run. Re-run `clarion analyze`."
+                    .to_owned(),
+            );
+        }
+        if issues.get("available") == Some(&Value::Bool(false)) {
+            let reason = issues
+                .get("reason")
+                .and_then(Value::as_str)
+                .unwrap_or("unavailable");
+            warnings.push(format!(
+                "Filigree issues unavailable ({reason}); the related-issues section is empty for \
+                 lack of data, not lack of issues."
+            ));
+        }
+        if neighbors_truncated {
+            warnings
+                .push("Some neighbor lists were truncated; see `omitted` for counts.".to_owned());
+        }
+        if paths_truncated {
+            warnings.push(
+                "Execution paths were truncated; see `omitted.execution_paths_truncation_reason`."
+                    .to_owned(),
+            );
+        }
+
+        let suggested = orientation_suggested_reads(
+            &core.packet,
+            core.primary_id.as_deref(),
+            core.primary_kind.as_deref(),
+        );
+
+        let mut omitted = core.neighbors_omitted.clone();
+        omitted.insert(
+            "execution_paths_truncated".to_owned(),
+            json!(paths_truncated),
+        );
+        omitted.insert(
+            "execution_paths_truncation_reason".to_owned(),
+            json!(core.paths_truncation_reason),
+        );
+
+        let truncated = neighbors_truncated || paths_truncated;
+
+        let mut packet = core.packet;
+        let object = packet
+            .as_object_mut()
+            .expect("orientation packet is an object");
+        object.insert("issues".to_owned(), issues);
+        object.insert("health".to_owned(), health);
+        object.insert("warnings".to_owned(), json!(warnings));
+        object.insert("suggested_next_reads".to_owned(), json!(suggested));
+        object.insert("omitted".to_owned(), Value::Object(omitted));
+
+        Ok(success_envelope_with_truncation(
+            packet,
+            truncated.then_some("orientation-pack-bounds"),
+        ))
+    }
+
+    // Uniform async dispatch with the other tools; the body is sync (spawn +
+    // registry insert), hence no await.
+    #[allow(clippy::unused_async)]
+    async fn tool_analyze_start(
+        &self,
+        _arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let program = match &self.analyze_program {
+            Some(program) => program.clone(),
+            None => match std::env::current_exe() {
+                Ok(path) => path,
+                Err(err) => {
+                    return Ok(tool_error_envelope(
+                        "spawn-failed",
+                        &format!("cannot resolve the clarion executable to launch analyze: {err}"),
+                        false,
+                    ));
+                }
+            },
+        };
+
+        let run_id = uuid::Uuid::new_v4().to_string();
+        let runs_dir = self.project_root.join(".clarion").join("runs");
+        if let Err(err) = std::fs::create_dir_all(&runs_dir) {
+            return Ok(tool_error_envelope(
+                "io-error",
+                &format!("create runs directory {}: {err}", runs_dir.display()),
+                false,
+            ));
+        }
+        let progress_path = runs_dir.join(format!("{run_id}.progress.json"));
+        let started_at = (self.clock)();
+
+        let mut registry = self
+            .analyze_runs
+            .lock()
+            .expect("analyze run registry mutex");
+        // Evict finished handles (and reap their progress files) before
+        // spawning, so a long-lived `serve` doing many analyses does not
+        // accumulate dead entries / `runs/*.progress.json` files
+        // (clarion-7e0c21558a).
+        crate::analyze_runs::reap_terminal_runs(&mut registry);
+        // Reject a concurrent run: a second `clarion analyze` would fail to
+        // acquire the project's cross-process lock anyway, so surface it as a
+        // clear error rather than spawning a doomed child.
+        let already_active = registry
+            .values_mut()
+            .any(|handle| !handle.cancelled && matches!(handle.child.try_wait(), Ok(None)));
+        if already_active {
+            return Ok(tool_error_envelope(
+                "analyze-already-running",
+                "an analyze run is already active for this project; cancel it or wait for it to finish",
+                true,
+            ));
+        }
+
+        let handle = match crate::analyze_runs::spawn_analyze(
+            &program,
+            &self.project_root,
+            &run_id,
+            &progress_path,
+            started_at,
+        ) {
+            Ok(handle) => handle,
+            Err(err) => {
+                return Ok(tool_error_envelope(
+                    "spawn-failed",
+                    &format!("failed to spawn `clarion analyze`: {err}"),
+                    false,
+                ));
+            }
+        };
+        let pid = handle.child.id();
+        registry.insert(run_id.clone(), handle);
+        drop(registry);
+
+        Ok(success_envelope(json!({
+            "run_id": run_id,
+            "status": "started",
+            "pid": pid,
+            "progress_file": progress_path.display().to_string(),
+        })))
+    }
+
+    async fn tool_analyze_status(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let run_id = required_str(arguments, "run_id")?.to_owned();
+        let now = (self.clock)();
+
+        // Snapshot the live state under the lock; reap on exit.
+        let live = {
+            let mut registry = self
+                .analyze_runs
+                .lock()
+                .expect("analyze run registry mutex");
+            match registry.get_mut(&run_id) {
+                Some(handle) => match handle.child.try_wait() {
+                    Ok(None) => LiveRun::Alive {
+                        started_at: handle.started_at.clone(),
+                        progress_path: handle.progress_path.clone(),
+                    },
+                    Ok(Some(_)) | Err(_) => LiveRun::Exited {
+                        started_at: handle.started_at.clone(),
+                        cancelled: handle.cancelled,
+                    },
+                },
+                None => LiveRun::Absent,
+            }
+        };
+
+        match live {
+            LiveRun::Alive {
+                started_at,
+                progress_path,
+            } => {
+                let elapsed = elapsed_seconds(&started_at, &now);
+                let progress = read_progress_snapshot(&progress_path);
+                let (status, heartbeat_at) = match &progress {
+                    Some(snapshot) => (
+                        "running",
+                        snapshot.get("heartbeat_at").and_then(Value::as_str),
+                    ),
+                    // Spawned but no progress recorded yet (still in discovery /
+                    // before the first write).
+                    None => ("queued", None),
+                };
+                let observed = heartbeat_at
+                    .is_some_and(|hb| progress_observed(hb, &now, ANALYZE_HEARTBEAT_STALE_SECS));
+                Ok(success_envelope(json!({
+                    "run_id": run_id,
+                    "status": status,
+                    "phase": progress.as_ref().and_then(|p| p.get("phase").cloned()),
+                    "current_plugin": progress.as_ref().and_then(|p| p.get("current_plugin").cloned()),
+                    "processed_files": progress.as_ref().and_then(|p| p.get("processed_files").cloned()),
+                    "total_files": progress.as_ref().and_then(|p| p.get("total_files").cloned()),
+                    "current_file": progress.as_ref().and_then(|p| p.get("current_file").cloned()),
+                    "heartbeat_at": heartbeat_at,
+                    "elapsed_seconds": elapsed,
+                    "progress_observed": observed,
+                })))
+            }
+            LiveRun::Exited {
+                started_at,
+                cancelled,
+            } => {
+                let row = self.read_run_row(&run_id).await;
+                Ok(self.terminal_status_envelope(&run_id, cancelled, Some(&started_at), &now, row))
+            }
+            LiveRun::Absent => {
+                // Not in the registry — may be a run from a prior session.
+                let row = self.read_run_row(&run_id).await;
+                match &row {
+                    Ok(Some(_)) => {
+                        Ok(self.terminal_status_envelope(&run_id, false, None, &now, row))
+                    }
+                    Ok(None) => Ok(tool_error_envelope(
+                        "run-not-found",
+                        &format!("no analyze run with id {run_id}"),
+                        false,
+                    )),
+                    Err(err) => Ok(tool_error_envelope(
+                        "storage-error",
+                        &err.to_string(),
+                        storage_retryable(err),
+                    )),
+                }
+            }
+        }
+    }
+
+    async fn tool_analyze_cancel(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let run_id = required_str(arguments, "run_id")?.to_owned();
+        let now = (self.clock)();
+
+        let outcome = {
+            let mut registry = self
+                .analyze_runs
+                .lock()
+                .expect("analyze run registry mutex");
+            match registry.get_mut(&run_id) {
+                Some(handle) => match handle.child.try_wait() {
+                    Ok(None) => {
+                        crate::analyze_runs::kill_run(handle);
+                        CancelOutcome::Cancelled
+                    }
+                    Ok(Some(_)) | Err(_) => CancelOutcome::AlreadyExited {
+                        cancelled: handle.cancelled,
+                    },
+                },
+                None => CancelOutcome::Absent,
+            }
+        };
+
+        match outcome {
+            CancelOutcome::Cancelled => {
+                let db_path = self.project_root.join(".clarion").join("clarion.db");
+                crate::analyze_runs::mark_run_cancelled_in_db(&db_path, &run_id, &now);
+                Ok(success_envelope(json!({
+                    "run_id": run_id,
+                    "status": "cancelled",
+                })))
+            }
+            // Idempotent: the run already finished — report its real terminal
+            // state rather than pretending we cancelled it.
+            CancelOutcome::AlreadyExited { cancelled } => {
+                let row = self.read_run_row(&run_id).await;
+                Ok(self.terminal_status_envelope(&run_id, cancelled, None, &now, row))
+            }
+            CancelOutcome::Absent => {
+                let row = self.read_run_row(&run_id).await;
+                match &row {
+                    Ok(Some(_)) => {
+                        Ok(self.terminal_status_envelope(&run_id, false, None, &now, row))
+                    }
+                    Ok(None) => Ok(tool_error_envelope(
+                        "run-not-found",
+                        &format!("no analyze run with id {run_id}"),
+                        false,
+                    )),
+                    Err(err) => Ok(tool_error_envelope(
+                        "storage-error",
+                        &err.to_string(),
+                        storage_retryable(err),
+                    )),
+                }
+            }
+        }
+    }
+
+    /// Read a run's `(status, stats)` from the `runs` table via the reader pool.
+    async fn read_run_row(
+        &self,
+        run_id: &str,
+    ) -> std::result::Result<Option<(String, String)>, StorageError> {
+        let run_id = run_id.to_owned();
+        self.readers
+            .with_reader(move |conn| {
+                match conn.query_row(
+                    "SELECT status, stats FROM runs WHERE id = ?1",
+                    rusqlite::params![run_id],
+                    |row| Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?)),
+                ) {
+                    Ok(tuple) => Ok(Some(tuple)),
+                    Err(rusqlite::Error::QueryReturnedNoRows) => Ok(None),
+                    Err(err) => Err(StorageError::from(err)),
+                }
+            })
+            .await
+    }
+
+    /// Build a terminal `analyze_status` envelope from the DB row, honoring a
+    /// registry cancel flag and surfacing recorded stats.
+    #[allow(clippy::unused_self)]
+    fn terminal_status_envelope(
+        &self,
+        run_id: &str,
+        cancelled: bool,
+        started_at: Option<&str>,
+        now: &str,
+        row: std::result::Result<Option<(String, String)>, StorageError>,
+    ) -> Value {
+        let (db_status, stats) = match row {
+            Ok(Some((db_status, stats))) => (Some(db_status), stats),
+            Ok(None) => (None, "{}".to_owned()),
+            Err(err) => {
+                return tool_error_envelope(
+                    "storage-error",
+                    &err.to_string(),
+                    storage_retryable(&err),
+                );
+            }
+        };
+        let mapped_status = if cancelled || run_stats_is_cancelled(&stats) {
+            "cancelled"
+        } else {
+            match &db_status {
+                Some(value) => map_run_status(value, &stats),
+                // Process exited but never recorded a run row.
+                None => "failed",
+            }
+        };
+        let stats_value = serde_json::from_str::<Value>(&stats).unwrap_or(Value::Null);
+        json!({
+            "ok": true,
+            "result": {
+                "run_id": run_id,
+                "status": mapped_status,
+                "elapsed_seconds": started_at.and_then(|start| elapsed_seconds(start, now)),
+                "stats": stats_value,
+            },
+            "error": null,
+            "diagnostics": [],
+            "truncated": false,
+            "truncation_reason": null,
+            "stats_delta": {}
+        })
+    }
+
+    async fn tool_source_for_entity(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let entity_id = required_str(arguments, "id")?.to_owned();
+        // Bounded context window; the schema caps at 200 but clamp defensively.
+        let context_lines = optional_usize(arguments, "context_lines")?
+            .unwrap_or(10)
+            .min(200);
+        let id_for_reader = entity_id.clone();
+        let entity = self
+            .readers
+            .with_reader(move |conn| entity_by_id(conn, &id_for_reader))
+            .await;
+        let entity = match entity {
+            Ok(Some(entity)) => entity,
+            Ok(None) => {
+                return Ok(tool_error_envelope(
+                    "not-found",
+                    &format!("no entity with id {entity_id}"),
+                    false,
+                ));
+            }
+            Err(err) => {
+                return Ok(tool_error_envelope(
+                    "storage-error",
+                    &err.to_string(),
+                    storage_retryable(&err),
+                ));
+            }
+        };
+        Ok(success_envelope(source_for_entity_json(
+            &entity,
+            context_lines,
+        )))
+    }
+
+    async fn tool_summary_preview_cost(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let entity_id = required_str(arguments, "id")?.to_owned();
+        let now = (self.clock)();
+        let read = match self
+            .read_summary_inputs(entity_id, self.summary_model_id())
+            .await
+        {
+            Ok(read) => read,
+            Err(err) => {
+                return Ok(tool_error_envelope(
+                    "storage-error",
+                    &err.to_string(),
+                    storage_retryable(&err),
+                ));
+            }
+        };
+        // Non-summarizable entities (missing, subsystem, briefing-blocked,
+        // no-content-hash) reuse the same reasons summary() reports.
+        let SummaryRead::Ready(ready) = read else {
+            return Ok(summary_read_error(read));
+        };
+
+        // LLM policy posture (no provider call). `live` means a provider is
+        // wired AND config permits it; that is what makes a miss spend. A
+        // disabled/unconfigured LLM is therefore distinct from a cache miss.
+        let llm_enabled = self
+            .summary_llm
+            .as_ref()
+            .is_some_and(|llm| llm.config.enabled);
+        let live = self.summary_llm.is_some() && llm_enabled;
+        let allow_live_provider = self
+            .summary_llm
+            .as_ref()
+            .is_some_and(|llm| llm.config.allow_live_provider);
+        let provider = self.diagnostics.as_ref().map_or_else(
+            || if live { "configured" } else { "disabled" }.to_owned(),
+            |diag| diag.llm.provider.clone(),
+        );
+
+        // Cache status without spending: a fresh row is a hit; a present-but-
+        // expired row would be re-billed; absence is a miss.
+        let (cache_status, cached_json) = match ready.cached.as_ref() {
+            Some(cached) => {
+                let expired = summary_cache_expired(
+                    &cached.created_at,
+                    &now,
+                    self.summary_cache_max_age_days(),
+                );
+                let age_days = timestamp_day_index(&now)
+                    .zip(timestamp_day_index(&cached.created_at))
+                    .map(|(current, created)| current.saturating_sub(created));
+                let json = json!({
+                    "created_at": cached.created_at,
+                    "last_accessed_at": cached.last_accessed_at,
+                    "age_days": age_days,
+                    "model_id": cached.key.model_tier,
+                    "tokens_input": cached.tokens_input,
+                    "tokens_output": cached.tokens_output,
+                    "cost_usd": cached.cost_usd,
+                    "stale_semantic": cached.stale_semantic,
+                });
+                (if expired { "expired" } else { "hit" }, json)
+            }
+            None => ("miss", Value::Null),
+        };
+
+        // On a miss/expired row a fresh call estimates input tokens from the
+        // leaf prompt (chars/4 heuristic — no provider, no spend). A hit needs
+        // no estimate: the cached row already carries the real token counts.
+        let estimated_input_tokens = if cache_status == "hit" {
+            None
+        } else {
+            verified_source_excerpt(&ready.entity)
+                .ok()
+                .map(|source_excerpt| {
+                    let prompt = build_leaf_summary_prompt(&LeafSummaryPromptInput {
+                        entity_id: ready.entity.id.clone(),
+                        kind: ready.entity.kind.clone(),
+                        name: ready.entity.name.clone(),
+                        source_excerpt,
+                    });
+                    estimate_tokens_from_chars(&prompt.body)
+                })
+        };
+
+        let live_spend_would_occur = cache_status != "hit" && live;
+
+        Ok(success_envelope(json!({
+            "entity": {"id": ready.entity.id, "kind": ready.entity.kind},
+            "cache_status": cache_status,
+            "cached": cached_json,
+            "model_id": self.summary_model_id(),
+            "estimated_input_tokens": estimated_input_tokens,
+            // summary() caps output at 512 tokens; report it as the ceiling, not
+            // a prediction of actual output length.
+            "estimated_output_tokens": SUMMARY_MAX_OUTPUT_TOKENS,
+            // No per-model pricing table at v1.0 — cost is reported only for
+            // cache hits/expired rows (the cached row carries a real cost_usd).
+            "estimated_cost_usd": Value::Null,
+            "policy": {
+                "enabled": llm_enabled,
+                "live": live,
+                "allow_live_provider": allow_live_provider,
+                "provider": provider,
+                "cache_max_age_days": self.summary_cache_max_age_days(),
+            },
+            "live_spend_would_occur": live_spend_would_occur,
+        })))
+    }
+
+    async fn tool_project_status(
+        &self,
+        _arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let db_path = self.project_root.join(".clarion").join("clarion.db");
+        let root_display = self.project_root.display().to_string();
+
+        let project_root = self.project_root.clone();
+        let storage = self
+            .readers
+            .with_reader(move |conn| {
+                let snapshot = crate::snapshot::project_snapshot(conn, &project_root);
+                let edge_count = scalar_count_fail_soft(conn, "SELECT COUNT(*) FROM edges");
+                // Entities withheld from briefings/federation exposure (secret
+                // scan set `briefing_blocked`). Served by the partial index
+                // ix_entities_briefing_blocked over the generated column
+                // (clarion-bdabfd6bca) — no per-row JSON parse.
+                let briefing_blocked = scalar_count_fail_soft(
+                    conn,
+                    "SELECT COUNT(*) FROM entities WHERE briefing_blocked IS NOT NULL",
+                );
+                let plugins = plugin_entity_counts(conn);
+                let latest_run = latest_run_row(conn);
+                // SQLite's data_version increments when another connection commits
+                // to the DB, so a consult agent can detect that the index changed
+                // under it across calls (clarion-22c18fdb34).
+                let data_version = scalar_count_fail_soft(conn, "PRAGMA data_version");
+                Ok((
+                    snapshot,
+                    edge_count,
+                    briefing_blocked,
+                    plugins,
+                    latest_run,
+                    data_version,
+                ))
+            })
+            .await;
+
+        let (snapshot, edge_count, briefing_blocked, plugins, latest_run, data_version) =
+            match storage {
+                Ok(tuple) => tuple,
+                Err(err) => {
+                    return Ok(tool_error_envelope(
+                        "storage-error",
+                        &err.to_string(),
+                        storage_retryable(&err),
+                    ));
+                }
+            };
+
+        // The on-disk size, paired with data_version, exposes a swapped or
+        // truncated DB the server may still be serving from a stale handle.
+        let db_size_bytes = std::fs::metadata(&db_path).map(|meta| meta.len()).ok();
+
+        // A served index that has a completed run but no entities is almost
+        // always a wrong/empty/swapped corpus — surface it in the log so an
+        // operator notices even without reading the diagnostics (clarion-22c18fdb34).
+        if snapshot.db_present()
+            && snapshot.entity_count() == 0
+            && snapshot.last_analyzed_at().is_some()
+        {
+            tracing::warn!(
+                db_path = %db_path.display(),
+                "project_status: served index has a completed run but zero entities (possible empty or swapped DB)"
+            );
+        }
+
+        let result = json!({
+            "project_root": root_display,
+            "db_path": db_path.display().to_string(),
+            "db_present": snapshot.db_present(),
+            "db_identity": {
+                "db_size_bytes": db_size_bytes,
+                "data_version": data_version,
+            },
+            "latest_run": latest_run,
+            "counts": {
+                "entities": snapshot.entity_count(),
+                "subsystems": snapshot.subsystem_count(),
+                "edges": edge_count,
+                "findings": snapshot.finding_count(),
+                "briefing_blocked": briefing_blocked,
+            },
+            "staleness": serde_json::to_value(snapshot.staleness()).unwrap_or(Value::Null),
+            "scan_truncated": snapshot.scan_truncated(),
+            "last_analyzed_at": snapshot.last_analyzed_at(),
+            // No analyze-time git SHA is persisted and Clarion has no git
+            // integration; report null rather than fabricate one.
+            "git_sha": Value::Null,
+            "plugins": plugins,
+            "llm": self.llm_diagnostics_json(),
+            "filigree": self.filigree_diagnostics_json(),
+        });
+
+        Ok(success_envelope(result))
+    }
+
+    async fn tool_index_diff(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let cap = optional_usize(arguments, "limit")?
+            .filter(|n| *n > 0)
+            .unwrap_or(index_diff::DEFAULT_MAX_ENTRIES);
+
+        // Git is read read-only and fail-soft, off the async runtime since it
+        // shells out.
+        let git_root = self.project_root.clone();
+        let git = match tokio::task::spawn_blocking(move || index_diff::gather_git_facts(&git_root))
+            .await
+        {
+            Ok(facts) => facts,
+            Err(err) => {
+                return Ok(tool_error_envelope(
+                    "internal",
+                    &format!("git fact-gathering task failed: {err}"),
+                    true,
+                ));
+            }
+        };
+
+        let project_root = self.project_root.clone();
+        let result = self
+            .readers
+            .with_reader(move |conn| {
+                let state = index_diff::read_index_state(conn)?;
+                Ok(success_envelope(index_diff::build_report(
+                    &project_root,
+                    &state,
+                    &git,
+                    cap,
+                )))
+            })
+            .await;
+        Ok(flatten_storage_envelope_result(result))
+    }
+
+    fn llm_diagnostics_json(&self) -> Value {
+        match &self.diagnostics {
+            Some(diag) => json!({
+                "provider": diag.llm.provider,
+                "live": diag.llm.live,
+                "allow_live_provider": diag.llm.allow_live_provider,
+                "cache_max_age_days": diag.llm.cache_max_age_days,
+            }),
+            None => Value::Null,
+        }
+    }
+
+    fn filigree_diagnostics_json(&self) -> Value {
+        match &self.diagnostics {
+            Some(diag) => json!({
+                "enabled": diag.filigree.enabled,
+                "configured_url": diag.filigree.configured_url,
+                "resolved_url": diag.filigree.resolved_url,
+                "resolution_source": diag.filigree.source,
+            }),
+            None => Value::Null,
+        }
+    }
+
+    async fn read_issues_for_entities(
+        &self,
+        entity_id: String,
+        include_contained: bool,
+    ) -> Result<Option<IssuesForRead>, StorageError> {
+        self.readers
+            .with_reader(move |conn| {
+                let Some(root) = entity_by_id(conn, &entity_id)? else {
+                    return Ok(None);
+                };
+                let mut ids = vec![root.id.clone()];
+                let mut entity_cap_truncated = false;
+                if include_contained {
+                    let contained = contained_entity_ids(conn, &entity_id, 1_000)?;
+                    entity_cap_truncated = contained.truncated;
+                    ids.extend(contained.entity_ids);
+                }
+                let mut entities = Vec::with_capacity(ids.len());
+                for id in ids {
+                    if let Some(entity) = entity_by_id(conn, &id)? {
+                        entities.push(entity);
+                    }
+                }
+                Ok(Some(IssuesForRead {
+                    entities,
+                    entity_cap_truncated,
+                }))
+            })
+            .await
+    }
+
+    async fn tool_summary(
+        &self,
+        arguments: &serde_json::Map<String, Value>,
+    ) -> std::result::Result<Value, ParamError> {
+        let entity_id = required_str(arguments, "id")?.to_owned();
+        let now = (self.clock)();
+        let read = match self
+            .read_summary_inputs(entity_id, self.summary_model_id())
+            .await
+        {
+            Ok(read) => read,
+            Err(err) => {
+                return Ok(tool_error_envelope(
+                    "storage-error",
+                    &err.to_string(),
+                    storage_retryable(&err),
+                ));
+            }
+        };
+
+        let SummaryRead::Ready(ready) = read else {
+            return Ok(summary_read_error(read));
+        };
+
+        if let Some(envelope) = self.cached_summary_envelope(&ready, &now).await {
+            return Ok(envelope);
+        }
+
+        if self.summary_budget_blocked() {
+            return Ok(token_ceiling_envelope(
+                "LLM session token ceiling has been reached",
+            ));
         }
 
         let Some(summary_llm) = &self.summary_llm else {
@@ -856,6 +2355,15 @@ impl ServerState {
             return Ok(InferredDispatchStats::default());
         };
 
+        if let Some(reason) = briefing_block_reason(&read.caller) {
+            tracing::warn!(
+                caller_id = %caller_id,
+                briefing_blocked = %reason,
+                "skipping inferred-edge dispatch for briefing-blocked caller"
+            );
+            return Ok(InferredDispatchStats::briefing_blocked());
+        }
+
         if let Some(cached) = read.cached.clone() {
             return self.materialize_cached_inferred(read, cached).await;
         }
@@ -1146,6 +2654,9 @@ impl ServerState {
                 if entity.kind == "subsystem" {
                     return Ok(SummaryRead::ScopeDeferred(Box::new(entity)));
                 }
+                if let Some(reason) = briefing_block_reason(&entity) {
+                    return Ok(SummaryRead::BriefingBlocked(Box::new(entity), reason));
+                }
                 let Some(content_hash) = entity.content_hash.clone() else {
                     return Ok(SummaryRead::MissingContentHash(entity.id));
                 };
@@ -1201,6 +2712,7 @@ impl ServerState {
             cached,
             true,
             stale_semantic(cached, ready.caller_count, ready.fan_out),
+            None,
             json!({"summary_cache_hits_total": 1}),
         ))
     }
@@ -1220,7 +2732,7 @@ impl ServerState {
             entity_id: ready.entity.id.clone(),
             kind: ready.entity.kind.clone(),
             name: ready.entity.name.clone(),
-            source_excerpt,
+            source_excerpt: source_excerpt.clone(),
         });
         let request = LlmRequest {
             purpose: LlmPurpose::Summary,
@@ -1254,19 +2766,53 @@ impl ServerState {
         }
 
         if serde_json::from_str::<Value>(&response.output_json).is_err() {
-            return tool_error_envelope_with_diagnostics(
-                "llm-invalid-json",
-                "summary provider returned non-JSON output",
-                true,
-                summary_usage_stats(&response, true),
-                vec![json!({
-                    "code": "CLA-LLM-INVALID-JSON",
-                    "message": "summary provider returned non-JSON output",
-                    "usage": llm_usage_json(&response)
-                })],
+            // The provider returned non-JSON — a deterministic failure for this
+            // input. Rather than bill the caller for an error and force the same
+            // paid failure on every retry, fall back to a structural summary
+            // built from the entity's own source and cache it, so the next
+            // request is a free cache hit (clarion-ed246ca3aa).
+            let mut stats_delta = summary_usage_stats(&response, true);
+            if let Some(object) = stats_delta.as_object_mut() {
+                object.insert("summary_structural_fallback_total".to_owned(), json!(1));
+            }
+            let cached_input_tokens = i64::from(response.cached_input_tokens);
+            let entry = SummaryCacheEntry {
+                key: ready.key,
+                summary_json: structural_summary_json(&ready.entity, &source_excerpt),
+                cost_usd: response.cost_usd,
+                tokens_input: i64::from(response.input_tokens),
+                tokens_output: i64::from(response.output_tokens),
+                caller_count: ready.caller_count,
+                fan_out: ready.fan_out,
+                stale_semantic: false,
+                created_at: now.clone(),
+                last_accessed_at: now,
+            };
+            if let Err(err) = self
+                .send_writer(&summary_llm.writer, |ack| WriterCmd::UpsertSummaryCache {
+                    entry: Box::new(entry.clone()),
+                    ack,
+                })
+                .await
+            {
+                return tool_error_envelope(
+                    "storage-error",
+                    &err.to_string(),
+                    storage_retryable(&err),
+                );
+            }
+            return summary_success_envelope(
+                &ready.entity,
+                &entry,
+                false,
+                false,
+                Some(cached_input_tokens),
+                stats_delta,
             );
         }
 
+        let cached_input_tokens = i64::from(response.cached_input_tokens);
+        let stats_delta = summary_usage_stats(&response, false);
         let entry = SummaryCacheEntry {
             key: ready.key,
             summary_json: response.output_json,
@@ -1294,13 +2840,8 @@ impl ServerState {
             &entry,
             false,
             false,
-            json!({
-                "summary_cache_misses_total": 1,
-                "summary_tokens_input": entry.tokens_input,
-                "summary_tokens_output": entry.tokens_output,
-                "summary_tokens_total": entry.tokens_input + entry.tokens_output,
-                "summary_cost_usd": entry.cost_usd
-            }),
+            Some(cached_input_tokens),
+            stats_delta,
         )
     }
 
@@ -1473,6 +3014,7 @@ enum SummaryRead {
     EntityNotFound(String),
     MissingContentHash(String),
     ScopeDeferred(Box<EntityRow>),
+    BriefingBlocked(Box<EntityRow>, String),
 }
 
 struct SummaryReady {
@@ -1564,15 +3106,69 @@ impl IssuesForAccumulator {
         }
     }
 
-    fn into_envelope(self, entity_cap_truncated: bool, requests_total: usize) -> Value {
+    /// Unique `issue_id`s across matched + drifted entries, in first-seen
+    /// order. `add_response` already dedupes `issue_id`s globally, so this is
+    /// the set of distinct issues to fetch detail for — one request each (no
+    /// N+1).
+    fn enrichable_issue_ids(&self) -> Vec<String> {
+        let mut seen = BTreeSet::new();
+        let mut ids = Vec::new();
+        for entry in self.matched.iter().chain(self.drifted.iter()) {
+            if let Some(id) = entry.get("issue_id").and_then(Value::as_str)
+                && seen.insert(id.to_owned())
+            {
+                ids.push(id.to_owned());
+            }
+        }
+        ids
+    }
+
+    /// Attach an `issue` field (title/status/priority) to every matched and
+    /// drifted entry. The value is the fetched [`IssueDetail`] when available,
+    /// else `null` — a stable shape that signals "enrichment attempted, no
+    /// detail" without forcing the consumer to probe for a missing key.
+    fn apply_issue_details(&mut self, details: &HashMap<String, Option<IssueDetail>>) {
+        for entry in self.matched.iter_mut().chain(self.drifted.iter_mut()) {
+            let issue_value = entry
+                .get("issue_id")
+                .and_then(Value::as_str)
+                .and_then(|id| details.get(id))
+                .and_then(Option::as_ref)
+                .and_then(|detail| serde_json::to_value(detail).ok())
+                .unwrap_or(Value::Null);
+            if let Some(object) = entry.as_object_mut() {
+                object.insert("issue".to_owned(), issue_value);
+            }
+        }
+    }
+
+    fn into_envelope(
+        self,
+        entity_cap_truncated: bool,
+        requests_total: usize,
+        detail_requests_total: usize,
+        filigree_endpoint: &Value,
+    ) -> Value {
         let truncation_reason = if self.issue_cap_truncated {
             Some("issue-cap")
         } else {
             entity_cap_truncated.then_some("entity-cap")
         };
+        // result_kind lets a consumer act on the outcome without re-deriving it
+        // from array lengths, and — paired with `available: false` from
+        // `issues_unavailable` — distinguishes "Filigree reachable but no issues
+        // are attached" (no_matches) from "Filigree unreachable/disabled"
+        // (unavailable).
+        let result_kind = if self.matched.is_empty() && self.drifted.is_empty() {
+            "no_matches"
+        } else {
+            "matched"
+        };
         let mut envelope = success_envelope_with_truncation_and_stats(
             json!({
                 "available": true,
+                "result_kind": result_kind,
+                "filigree_endpoint": filigree_endpoint,
                 "matched": self.matched,
                 "drifted": self.drifted,
                 "not_found": self.not_found
@@ -1580,7 +3176,8 @@ impl IssuesForAccumulator {
             truncation_reason,
             json!({
                 "filigree_requests_total": requests_total,
-                "filigree_issues_returned_total": self.emitted
+                "filigree_issues_returned_total": self.emitted,
+                "filigree_detail_requests_total": detail_requests_total
             }),
         );
         if let Some(object) = envelope.as_object_mut()
@@ -1684,9 +3281,11 @@ struct InferredDispatchStats {
     /// the persisted edge set to avoid the FK violation that previously
     /// poisoned the cache row and re-burned LLM tokens on retry.
     unresolved_targets_dropped_total: u64,
+    briefing_blocked_total: u64,
     candidate_callers_considered: u64,
     coalesced_waits_total: u64,
     tokens_input: i64,
+    tokens_cached_input: i64,
     tokens_output: i64,
     tokens_total: i64,
     cost_usd: f64,
@@ -1708,6 +3307,7 @@ impl InferredDispatchStats {
             edges_materialized_total: write.inserted_edges,
             edges_skipped_static_duplicates_total: write.skipped_static_duplicates,
             tokens_input: i64::from(response.input_tokens),
+            tokens_cached_input: i64::from(response.cached_input_tokens),
             tokens_output: i64::from(response.output_tokens),
             tokens_total: i64::from(response.total_tokens),
             cost_usd: response.cost_usd,
@@ -1715,15 +3315,24 @@ impl InferredDispatchStats {
         }
     }
 
+    fn briefing_blocked() -> Self {
+        Self {
+            briefing_blocked_total: 1,
+            ..Self::default()
+        }
+    }
+
     fn merge(&mut self, other: &Self) {
         self.cache_hits_total += other.cache_hits_total;
         self.cache_misses_total += other.cache_misses_total;
         self.edges_materialized_total += other.edges_materialized_total;
         self.edges_skipped_static_duplicates_total += other.edges_skipped_static_duplicates_total;
         self.unresolved_targets_dropped_total += other.unresolved_targets_dropped_total;
+        self.briefing_blocked_total += other.briefing_blocked_total;
         self.candidate_callers_considered += other.candidate_callers_considered;
         self.coalesced_waits_total += other.coalesced_waits_total;
         self.tokens_input += other.tokens_input;
+        self.tokens_cached_input += other.tokens_cached_input;
         self.tokens_output += other.tokens_output;
         self.tokens_total += other.tokens_total;
         self.cost_usd += other.cost_usd;
@@ -1736,9 +3345,11 @@ impl InferredDispatchStats {
             "inferred_edges_materialized_total": self.edges_materialized_total,
             "inferred_edges_skipped_static_duplicates_total": self.edges_skipped_static_duplicates_total,
             "inferred_unresolved_targets_dropped_total": self.unresolved_targets_dropped_total,
+            "inferred_dispatch_briefing_blocked_total": self.briefing_blocked_total,
             "inferred_candidate_callers_considered": self.candidate_callers_considered,
             "inferred_dispatch_coalesced_total": self.coalesced_waits_total,
             "inferred_tokens_input": self.tokens_input,
+            "inferred_tokens_cached_input": self.tokens_cached_input,
             "inferred_tokens_output": self.tokens_output,
             "inferred_tokens_total": self.tokens_total,
             "inferred_cost_usd": self.cost_usd
@@ -1851,25 +3462,130 @@ pub enum McpError {
 /// Decode and handle a state-free MCP frame.
 ///
 /// Storage-backed tool calls require [`handle_frame_with_state`].
-pub fn handle_frame(frame: &Frame) -> Result<Frame, McpError> {
+pub fn handle_frame(frame: &Frame) -> Result<Option<Frame>, McpError> {
     let request = serde_json::from_slice(&frame.body)?;
-    let response = handle_json_rpc(&request);
-    Ok(Frame {
-        body: serde_json::to_vec(&response)?,
-    })
+    let Some(response) = handle_json_rpc(&request) else {
+        return Ok(None);
+    };
+    Ok(Some(encode_response_frame(&response)?))
 }
 
 pub async fn handle_frame_with_state(
     state: &ServerState,
     frame: &Frame,
-) -> Result<Frame, McpError> {
+) -> Result<Option<Frame>, McpError> {
     let request = serde_json::from_slice(&frame.body)?;
-    let response = state.handle_json_rpc(&request).await;
+    let Some(response) = state.handle_json_rpc(&request).await else {
+        return Ok(None);
+    };
+    Ok(Some(encode_response_frame(&response)?))
+}
+
+fn handle_stdio_frame(frame: &Frame) -> Result<Option<Frame>, McpError> {
+    handle_frame(frame)
+}
+
+async fn handle_stdio_frame_with_state(
+    state: &ServerState,
+    frame: &Frame,
+) -> Result<Option<Frame>, McpError> {
+    handle_frame_with_state(state, frame).await
+}
+
+fn encode_response_frame(response: &Value) -> Result<Frame, McpError> {
     Ok(Frame {
-        body: serde_json::to_vec(&response)?,
+        body: serde_json::to_vec(response)?,
     })
 }
 
+fn is_json_rpc_notification(request: &Value) -> bool {
+    request
+        .as_object()
+        .is_some_and(|object| object.get("method").is_some() && object.get("id").is_none())
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum StdioFraming {
+    ContentLength,
+    JsonLine,
+}
+
+struct StdioFrame {
+    body: Vec<u8>,
+    framing: StdioFraming,
+}
+
+fn read_stdio_frame(reader: &mut impl std::io::BufRead) -> Result<Option<StdioFrame>, McpError> {
+    let Some(first_byte) = peek_stdio_frame_start(reader)? else {
+        return Ok(None);
+    };
+    if first_byte == b'{' || first_byte == b'[' || first_byte.is_ascii_whitespace() {
+        return Ok(Some(read_json_line_frame(reader)?));
+    }
+    match clarion_core::plugin::read_frame(reader, ContentLengthCeiling::DEFAULT) {
+        Ok(frame) => Ok(Some(StdioFrame {
+            body: frame.body,
+            framing: StdioFraming::ContentLength,
+        })),
+        Err(TransportError::Io(err)) if err.kind() == std::io::ErrorKind::UnexpectedEof => Ok(None),
+        Err(err) => Err(err.into()),
+    }
+}
+
+fn peek_stdio_frame_start(reader: &mut impl std::io::BufRead) -> Result<Option<u8>, McpError> {
+    loop {
+        let buffer = reader.fill_buf()?;
+        if buffer.is_empty() {
+            return Ok(None);
+        }
+        let blank_prefix = buffer
+            .iter()
+            .take_while(|byte| matches!(byte, b'\r' | b'\n'))
+            .count();
+        if blank_prefix == 0 {
+            return Ok(Some(buffer[0]));
+        }
+        reader.consume(blank_prefix);
+    }
+}
+
+fn read_json_line_frame(reader: &mut impl std::io::BufRead) -> Result<StdioFrame, McpError> {
+    let mut body = Vec::new();
+    let read = std::io::BufRead::read_until(reader, b'\n', &mut body)?;
+    if read == 0 {
+        return Err(TransportError::Io(std::io::Error::new(
+            std::io::ErrorKind::UnexpectedEof,
+            "EOF while reading MCP JSON line",
+        ))
+        .into());
+    }
+    while matches!(body.last(), Some(b'\n' | b'\r')) {
+        body.pop();
+    }
+    Ok(StdioFrame {
+        body,
+        framing: StdioFraming::JsonLine,
+    })
+}
+
+fn write_stdio_response(
+    writer: &mut impl std::io::Write,
+    response: &Frame,
+    framing: StdioFraming,
+) -> Result<(), McpError> {
+    match framing {
+        StdioFraming::ContentLength => {
+            clarion_core::plugin::write_frame(writer, response)?;
+        }
+        StdioFraming::JsonLine => {
+            writer.write_all(&response.body)?;
+            writer.write_all(b"\n")?;
+            writer.flush()?;
+        }
+    }
+    Ok(())
+}
+
 /// Serve state-free MCP protocol metadata over stdio.
 ///
 /// Storage-backed tool calls require [`serve_stdio_with_state`].
@@ -1878,15 +3594,13 @@ pub fn serve_stdio(
     writer: &mut impl std::io::Write,
 ) -> Result<(), McpError> {
     loop {
-        let frame = match clarion_core::plugin::read_frame(reader, ContentLengthCeiling::DEFAULT) {
-            Ok(frame) => frame,
-            Err(TransportError::Io(err)) if err.kind() == std::io::ErrorKind::UnexpectedEof => {
-                return Ok(());
-            }
-            Err(err) => return Err(err.into()),
+        let Some(frame) = read_stdio_frame(reader)? else {
+            return Ok(());
         };
-        let response = handle_frame(&frame)?;
-        clarion_core::plugin::write_frame(writer, &response)?;
+        let framing = frame.framing;
+        if let Some(response) = handle_stdio_frame(&Frame { body: frame.body })? {
+            write_stdio_response(writer, &response, framing)?;
+        }
     }
 }
 
@@ -1909,31 +3623,88 @@ pub fn serve_stdio_with_state_on_runtime(
 ) -> Result<(), McpError> {
     let _guard = runtime.enter();
     loop {
-        let frame = match clarion_core::plugin::read_frame(reader, ContentLengthCeiling::DEFAULT) {
-            Ok(frame) => frame,
-            Err(TransportError::Io(err)) if err.kind() == std::io::ErrorKind::UnexpectedEof => {
-                return Ok(());
-            }
-            Err(err) => return Err(err.into()),
+        let Some(frame) = read_stdio_frame(reader)? else {
+            return Ok(());
         };
-        let response = runtime.block_on(handle_frame_with_state(state, &frame))?;
-        clarion_core::plugin::write_frame(writer, &response)?;
+        let framing = frame.framing;
+        if let Some(response) = runtime.block_on(handle_stdio_frame_with_state(
+            state,
+            &Frame { body: frame.body },
+        ))? {
+            write_stdio_response(writer, &response, framing)?;
+        }
     }
 }
 
-fn initialize_result() -> Value {
+/// Build the `initialize` result, advertising only the capabilities the
+/// handling path actually serves. The stateless free [`handle_json_rpc`] serves
+/// `tools` only (it returns method-not-found for `resources/*` and `prompts/*`),
+/// so it passes `stateful = false`; [`ServerState::handle_json_rpc`] serves the
+/// full surface and passes `stateful = true`. The `instructions` field is static
+/// orientation guidance (not a capability) and is included in both.
+fn initialize_result(stateful: bool) -> Value {
+    let capabilities = if stateful {
+        json!({ "tools": {}, "prompts": {}, "resources": {} })
+    } else {
+        json!({ "tools": {} })
+    };
     json!({
         "protocolVersion": MCP_PROTOCOL_VERSION,
-        "capabilities": {
-            "tools": {}
-        },
+        "capabilities": capabilities,
         "serverInfo": {
             "name": "clarion",
             "version": env!("CARGO_PKG_VERSION")
-        }
+        },
+        "instructions": server_instructions()
+    })
+}
+
+fn resources_list() -> Value {
+    json!({
+        "resources": [
+            {
+                "uri": "clarion://context",
+                "name": "Clarion project context",
+                "description": "Live entity / subsystem / finding counts and index freshness for this project.",
+                "mimeType": "application/json"
+            }
+        ]
+    })
+}
+
+fn prompts_list() -> Value {
+    json!({
+        "prompts": [
+            {
+                "name": "clarion-workflow",
+                "description": "How to use Clarion's MCP tools to navigate this codebase."
+            }
+        ]
     })
 }
 
+fn prompts_get(id: &Value, params: Option<&Value>) -> Value {
+    let name = params
+        .and_then(Value::as_object)
+        .and_then(|p| p.get("name"))
+        .and_then(Value::as_str);
+    if name != Some("clarion-workflow") {
+        return error_response(id, -32602, "unknown prompt");
+    }
+    result_response(
+        id,
+        &json!({
+            "description": "How to use Clarion's MCP tools to navigate this codebase.",
+            "messages": [
+                {
+                    "role": "user",
+                    "content": { "type": "text", "text": CLARION_WORKFLOW_SKILL }
+                }
+            ]
+        }),
+    )
+}
+
 #[derive(Debug)]
 struct ParamError {
     message: String,
@@ -2064,6 +3835,18 @@ fn optional_confidence(
     }
 }
 
+/// Call-graph blind spots a query did **not** search, so a consumer never reads
+/// an empty or partial caller/path result as a true negative (clarion-0d204a3f16).
+/// The static resolver cannot bind a call made through an attribute receiver
+/// (e.g. `ctx.orchestrator.resume()`); only `inferred` (LLM) dispatch attempts
+/// those, so `resolved`/`ambiguous` queries exclude them and `inferred` does not.
+fn call_graph_scope_excludes(confidence: EdgeConfidence) -> Vec<&'static str> {
+    match confidence {
+        EdgeConfidence::Resolved | EdgeConfidence::Ambiguous => vec!["attribute-receiver-calls"],
+        EdgeConfidence::Inferred => Vec::new(),
+    }
+}
+
 fn envelope_from_storage_result(result: Result<Value, StorageError>) -> Value {
     match result {
         Ok(result) => success_envelope(result),
@@ -2071,6 +3854,70 @@ fn envelope_from_storage_result(result: Result<Value, StorageError>) -> Value {
     }
 }
 
+/// Fail-soft scalar count for `project_status`: a query hiccup degrades to 0
+/// (logged), never failing the diagnostics tool. Matches `snapshot.rs`'s policy.
+fn scalar_count_fail_soft(conn: &rusqlite::Connection, sql: &str) -> i64 {
+    conn.query_row(sql, [], |row| row.get::<_, i64>(0))
+        .unwrap_or_else(|err| {
+            tracing::warn!(error = %err, sql, "project_status count query failed; reporting 0");
+            0
+        })
+}
+
+/// Per-plugin entity counts from the current index (`entities.plugin_id`), the
+/// queryable proxy for "which plugins produced this graph." Fail-soft: any
+/// query error degrades to an empty array (logged).
+fn plugin_entity_counts(conn: &rusqlite::Connection) -> Value {
+    let mut stmt = match conn
+        .prepare("SELECT plugin_id, COUNT(*) FROM entities GROUP BY plugin_id ORDER BY plugin_id")
+    {
+        Ok(stmt) => stmt,
+        Err(err) => {
+            tracing::warn!(error = %err, "project_status plugin-count prepare failed");
+            return Value::Array(Vec::new());
+        }
+    };
+    let rows = stmt.query_map([], |row| {
+        Ok(json!({
+            "plugin_id": row.get::<_, String>(0)?,
+            "entity_count": row.get::<_, i64>(1)?,
+        }))
+    });
+    match rows {
+        Ok(mapped) => Value::Array(mapped.filter_map(Result::ok).collect()),
+        Err(err) => {
+            tracing::warn!(error = %err, "project_status plugin-count query failed");
+            Value::Array(Vec::new())
+        }
+    }
+}
+
+/// The most-recent run by `started_at`, regardless of terminal status, so a
+/// `skipped_no_plugins` or `failed` run is visible (not just the last
+/// `completed` one). Fail-soft: no rows or a query error → `null`.
+fn latest_run_row(conn: &rusqlite::Connection) -> Value {
+    match conn.query_row(
+        "SELECT id, status, started_at, completed_at FROM runs \
+         ORDER BY started_at DESC LIMIT 1",
+        [],
+        |row| {
+            Ok(json!({
+                "id": row.get::<_, String>(0)?,
+                "status": row.get::<_, String>(1)?,
+                "started_at": row.get::<_, String>(2)?,
+                "completed_at": row.get::<_, Option<String>>(3)?,
+            }))
+        },
+    ) {
+        Ok(value) => value,
+        Err(rusqlite::Error::QueryReturnedNoRows) => Value::Null,
+        Err(err) => {
+            tracing::warn!(error = %err, "project_status latest-run query failed");
+            Value::Null
+        }
+    }
+}
+
 fn flatten_storage_envelope_result(result: Result<Value, StorageError>) -> Value {
     match result {
         Ok(envelope) => envelope,
@@ -2159,6 +4006,7 @@ fn tool_error_envelope_with_diagnostics(
 fn llm_usage_json(response: &LlmResponse) -> Value {
     json!({
         "tokens_input": response.input_tokens,
+        "tokens_cached_input": response.cached_input_tokens,
         "tokens_output": response.output_tokens,
         "tokens_total": response.total_tokens,
         "cost_usd": response.cost_usd
@@ -2172,6 +4020,10 @@ fn summary_usage_stats(response: &LlmResponse, invalid_json: bool) -> Value {
         "summary_tokens_input".to_owned(),
         json!(response.input_tokens),
     );
+    stats.insert(
+        "summary_tokens_cached_input".to_owned(),
+        json!(response.cached_input_tokens),
+    );
     stats.insert(
         "summary_tokens_output".to_owned(),
         json!(response.output_tokens),
@@ -2194,6 +4046,10 @@ fn inferred_usage_stats(response: &LlmResponse, invalid_json: bool) -> Value {
         "inferred_tokens_input".to_owned(),
         json!(response.input_tokens),
     );
+    stats.insert(
+        "inferred_tokens_cached_input".to_owned(),
+        json!(response.cached_input_tokens),
+    );
     stats.insert(
         "inferred_tokens_output".to_owned(),
         json!(response.output_tokens),
@@ -2232,9 +4088,11 @@ fn token_ceiling_envelope(message: &str) -> Value {
     })
 }
 
-fn issues_unavailable(reason: &str, message: &str) -> Value {
+fn issues_unavailable(filigree_endpoint: &Value, reason: &str, message: &str) -> Value {
     success_envelope(json!({
         "available": false,
+        "result_kind": "unavailable",
+        "filigree_endpoint": filigree_endpoint,
         "reason": reason,
         "message": message,
         "matched": [],
@@ -2274,116 +4132,1000 @@ fn summary_read_error(read: SummaryRead) -> Value {
             false,
         ),
         SummaryRead::ScopeDeferred(entity) => summary_scope_deferred(&entity),
+        SummaryRead::BriefingBlocked(entity, reason) => summary_briefing_blocked(&entity, &reason),
         SummaryRead::Ready(_) => unreachable!("ready summary read is not an error"),
     }
 }
 
-#[derive(Debug)]
-struct SourceExcerptError {
-    entity_id: String,
-    stored_content_hash: String,
-    current_content_hash: String,
+#[derive(Debug)]
+struct SourceExcerptError {
+    entity_id: String,
+    stored_content_hash: String,
+    current_content_hash: String,
+}
+
+impl SourceExcerptError {
+    fn message(&self) -> String {
+        format!(
+            "entity {} source content drifted: stored content_hash {} but current file hashes to {}; rerun `clarion analyze` before requesting LLM output",
+            self.entity_id, self.stored_content_hash, self.current_content_hash
+        )
+    }
+
+    fn to_envelope(&self) -> Value {
+        tool_error_envelope("content-drift", &self.message(), false)
+    }
+
+    fn to_inferred_failure(&self) -> InferredDispatchFailure {
+        InferredDispatchFailure::new("content-drift", &self.message(), false)
+    }
+}
+
+/// Deterministic structural summary used when the LLM returns non-JSON
+/// (clarion-ed246ca3aa). Carries the entity's identity plus a bounded head of
+/// its own source (where the signature and docstring live), so the caller gets
+/// usable orientation instead of a billed error. `kind: structural-fallback`
+/// lets consumers distinguish it from a real LLM summary.
+fn structural_summary_json(entity: &EntityRow, source_excerpt: &str) -> String {
+    const STRUCTURAL_SUMMARY_MAX_CHARS: usize = 1200;
+    let mut source_head: String = source_excerpt
+        .chars()
+        .take(STRUCTURAL_SUMMARY_MAX_CHARS)
+        .collect();
+    let source_truncated = source_excerpt.chars().count() > STRUCTURAL_SUMMARY_MAX_CHARS;
+    if source_truncated {
+        source_head.push('…');
+    }
+    serde_json::to_string(&json!({
+        "kind": "structural-fallback",
+        "note": "LLM summary unavailable (provider returned non-JSON); deterministic structural summary derived from the entity source.",
+        "entity_kind": entity.kind,
+        "short_name": entity.short_name,
+        "qualified_name": entity.name,
+        "source_head": source_head,
+        "source_truncated": source_truncated
+    }))
+    .expect("structural summary serializes")
+}
+
+fn summary_success_envelope(
+    entity: &EntityRow,
+    entry: &SummaryCacheEntry,
+    cache_hit: bool,
+    stale_semantic: bool,
+    cached_input_tokens: Option<i64>,
+    stats_delta: Value,
+) -> Value {
+    let summary = serde_json::from_str::<Value>(&entry.summary_json).unwrap_or_else(|_| {
+        json!({
+            "raw": entry.summary_json
+        })
+    });
+    let mut usage = serde_json::Map::new();
+    usage.insert("tokens_input".to_owned(), json!(entry.tokens_input));
+    if let Some(tokens) = cached_input_tokens {
+        usage.insert("tokens_cached_input".to_owned(), json!(tokens));
+    }
+    usage.insert("tokens_output".to_owned(), json!(entry.tokens_output));
+    usage.insert(
+        "tokens_total".to_owned(),
+        json!(entry.tokens_input + entry.tokens_output),
+    );
+    success_envelope_with_stats(
+        json!({
+            "available": true,
+            "entity": entity_json(entity),
+            "summary": summary,
+            "cache": {
+                "hit": cache_hit,
+                "prompt_template_id": entry.key.prompt_template_id,
+                "model_id": entry.key.model_tier,
+                "guidance_fingerprint": entry.key.guidance_fingerprint,
+                "stale_semantic": stale_semantic,
+                "created_at": entry.created_at,
+                "last_accessed_at": entry.last_accessed_at
+            },
+            "usage": Value::Object(usage)
+        }),
+        stats_delta,
+    )
+}
+
+fn summary_scope_deferred(entity: &EntityRow) -> Value {
+    success_envelope(json!({
+        "available": false,
+        "reason": "summary-scope-deferred",
+        "message": "subsystem summaries are deferred to v0.2",
+        "entity": entity_json(entity)
+    }))
+}
+
+fn summary_briefing_blocked(entity: &EntityRow, reason: &str) -> Value {
+    let remediation = if reason == "unscanned_source" {
+        "Entity source file was not covered by the pre-ingest secret scan. Re-run with scanner coverage for that path or fix the plugin source path before requesting a summary."
+    } else {
+        "File flagged by pre-ingest secret scan. Fix the secret or whitelist via .clarion/secrets-baseline.yaml. See ADR-013."
+    };
+    success_envelope(json!({
+        "available": false,
+        "entity_id": entity.id,
+        "entity": entity_json(entity),
+        "summary": null,
+        "briefing_blocked": reason,
+        "remediation": remediation
+    }))
+}
+
+fn briefing_block_reason(entity: &EntityRow) -> Option<String> {
+    entity_properties_json(entity)
+        .get("briefing_blocked")
+        .and_then(Value::as_str)
+        .map(str::to_owned)
+}
+
+fn tool_json_rpc_response(id: &Value, envelope: &Value) -> Value {
+    let is_error = !envelope
+        .get("ok")
+        .and_then(Value::as_bool)
+        .unwrap_or_default();
+    result_response(
+        id,
+        &json!({
+            "content": [
+                {
+                    "type": "text",
+                    "text": serde_json::to_string(&envelope).expect("tool envelope serializes")
+                }
+            ],
+            "isError": is_error
+        }),
+    )
+}
+
+fn entity_json(entity: &EntityRow) -> Value {
+    json!({
+        "id": entity.id,
+        "kind": entity.kind,
+        "name": entity.name,
+        "short_name": entity.short_name,
+        "source_file_path": entity.source_file_path,
+        "source_line_start": entity.source_line_start,
+        "source_line_end": entity.source_line_end,
+        "content_hash": entity.content_hash
+    })
+}
+
+fn entity_properties_json(entity: &EntityRow) -> Value {
+    serde_json::from_str::<Value>(&entity.properties_json)
+        .expect("entity properties_json should be valid JSON")
+}
+
+/// Maximum number of ambiguity alternatives `entity_at` reports. Genuine
+/// same-granularity overlaps are rare; this only bounds a pathological file.
+const ENTITY_CONTEXT_MAX_ALTERNATIVES: usize = 8;
+
+/// The decorator/declaration/body sub-ranges a plugin records for a
+/// function/class entity in `properties_json.definition` (clarion-460def6a51).
+/// All optional: older indexes, modules, and plugins that don't emit the block
+/// leave every field `None`.
+struct DefinitionSpan {
+    decl_line: Option<i64>,
+    body_line_start: Option<i64>,
+    decorator_line_start: Option<i64>,
+    decorator_line_end: Option<i64>,
+}
+
+impl DefinitionSpan {
+    fn from_entity(entity: &EntityRow) -> Self {
+        let def = serde_json::from_str::<Value>(&entity.properties_json)
+            .ok()
+            .and_then(|props| props.get("definition").cloned());
+        let get = |key: &str| -> Option<i64> {
+            def.as_ref()
+                .and_then(|d| d.get(key))
+                .and_then(Value::as_i64)
+        };
+        Self {
+            decl_line: get("decl_line"),
+            body_line_start: get("body_line_start"),
+            decorator_line_start: get("decorator_line_start"),
+            decorator_line_end: get("decorator_line_end"),
+        }
+    }
+}
+
+/// Classify *why* `line` resolved to `entity`: a decorator line, the
+/// declaration/signature, the body, or merely a containing scope (module, or
+/// an entity without recorded sub-ranges). Honest by construction — a blank or
+/// comment line that only the module spans reports `containing_range`, never a
+/// fabricated exact match (clarion-460def6a51 acceptance #3).
+fn match_reason_for(line: i64, entity: &EntityRow) -> &'static str {
+    if entity.kind == "module" {
+        return "containing_range";
+    }
+    let def = DefinitionSpan::from_entity(entity);
+    let Some(decl_line) = def.decl_line else {
+        return "containing_range";
+    };
+    if let Some(decorator_start) = def.decorator_line_start
+        && line >= decorator_start
+        && line < decl_line
+    {
+        return "decorator_range";
+    }
+    if let Some(body_line_start) = def.body_line_start {
+        if line >= body_line_start {
+            return "body_range";
+        }
+        return "declaration";
+    }
+    if line == decl_line {
+        return "declaration";
+    }
+    "containing_range"
+}
+
+/// Span length in lines used to detect same-granularity ambiguity. `None` when
+/// either bound is missing.
+fn span_len(entity: &EntityRow) -> Option<i64> {
+    Some(entity.source_line_end? - entity.source_line_start?)
+}
+
+/// Compact entity descriptor for the containing stack — enough to orient
+/// without the full `entity_json` payload.
+fn stack_entity_json(entity: &EntityRow) -> Value {
+    json!({
+        "id": entity.id,
+        "kind": entity.kind,
+        "short_name": entity.short_name,
+        "name": entity.name,
+        "source_line_start": entity.source_line_start,
+        "source_line_end": entity.source_line_end,
+    })
+}
+
+/// Build the additive `entity_context` evidence block for `entity_at`
+/// (clarion-460def6a51): the match reason, the module→entity containing stack,
+/// the matched entity's sub-ranges, same-granularity ambiguity alternatives,
+/// and index freshness. Returns a `no_match` shell when no entity spans the
+/// line (e.g. an unindexed file).
+fn entity_context_json(
+    line: Option<i64>,
+    matched: Option<&EntityRow>,
+    candidates: &[EntityRow],
+    ancestors: &[EntityRow],
+    snapshot: &crate::snapshot::ProjectSnapshot,
+) -> Value {
+    let freshness = json!({
+        "staleness": snapshot.staleness(),
+        "last_analyzed_at": snapshot.last_analyzed_at(),
+        "degraded": snapshot.degraded(),
+        "scan_truncated": snapshot.scan_truncated(),
+    });
+
+    let Some(matched) = matched else {
+        return json!({
+            "query_line": line,
+            "match_reason": "no_match",
+            "containing_stack": [],
+            "ranges": Value::Null,
+            "alternatives": [],
+            "freshness": freshness,
+        });
+    };
+
+    // Containing stack outermost (module) → matched entity, inclusive.
+    let mut containing_stack: Vec<Value> = ancestors.iter().rev().map(stack_entity_json).collect();
+    containing_stack.push(stack_entity_json(matched));
+
+    let def = DefinitionSpan::from_entity(matched);
+    let ranges = json!({
+        "source_line_start": matched.source_line_start,
+        "source_line_end": matched.source_line_end,
+        "decl_line": def.decl_line,
+        "body_line_start": def.body_line_start,
+        "decorator_line_start": def.decorator_line_start,
+        "decorator_line_end": def.decorator_line_end,
+    });
+
+    // Ambiguity: other candidates sharing the winner's span length are genuine
+    // same-granularity overlaps. Strictly larger spans are the nesting stack
+    // already captured above, so they are not alternatives. Only meaningful for
+    // a line query; an `entity`-id lookup has no line to disambiguate.
+    let matched_len = span_len(matched);
+    let alternatives: Vec<Value> = match line {
+        Some(line) => candidates
+            .iter()
+            .skip(1)
+            .filter(|cand| matched_len.is_some() && span_len(cand) == matched_len)
+            .take(ENTITY_CONTEXT_MAX_ALTERNATIVES)
+            .map(|cand| {
+                json!({
+                    "entity": entity_json(cand),
+                    "match_reason": match_reason_for(line, cand),
+                })
+            })
+            .collect(),
+        None => Vec::new(),
+    };
+
+    // For a line query, explain why that line matched; for a direct `entity`-id
+    // lookup there is no line, so the reason is simply "entity".
+    let match_reason = match line {
+        Some(line) => match_reason_for(line, matched),
+        None => "entity",
+    };
+
+    json!({
+        "query_line": line,
+        "match_reason": match_reason,
+        "containing_stack": containing_stack,
+        "ranges": ranges,
+        "alternatives": alternatives,
+        "freshness": freshness,
+    })
+}
+
+/// Per-section neighbor cap for `orientation_pack` — keeps the packet bounded
+/// while still surfacing the most relevant edges; overflow is reported in
+/// `omitted`.
+const ORIENTATION_PACK_MAX_NEIGHBORS: usize = 10;
+
+/// Call-graph traversal depth for `orientation_pack`'s compact execution paths.
+/// Matches the `execution_paths_from` default so the packet's paths line up
+/// with a follow-up call to that tool.
+const ORIENTATION_PACK_PATH_DEPTH: usize = 3;
+
+/// Sync portion of an `orientation_pack`: everything one reader snapshot can
+/// produce, plus the flags the async assembly stage needs for warnings and the
+/// `omitted` block. Issues + health are layered on afterward.
+struct OrientationCore {
+    primary_id: Option<String>,
+    primary_kind: Option<String>,
+    /// True when the request used the `entity`-id form (so a `None`
+    /// `primary_id` is a hard not-found, not a graceful `no_match`).
+    lookup_was_id: bool,
+    packet: Value,
+    freshness: Value,
+    staleness_stale: bool,
+    neighbors_omitted: serde_json::Map<String, Value>,
+    paths_truncation_reason: Option<String>,
+}
+
+/// Sort a neighbor list by entity id (stable, deterministic) and cap it,
+/// returning the kept list and how many were dropped.
+fn cap_neighbor_list(mut list: Vec<Value>, cap: usize) -> (Vec<Value>, usize) {
+    list.sort_by(|a, b| neighbor_sort_key(a).cmp(neighbor_sort_key(b)));
+    let omitted = list.len().saturating_sub(cap);
+    list.truncate(cap);
+    (list, omitted)
+}
+
+/// Entity id of a neighbor JSON record (`{"entity": {"id": ...}, ...}` or a
+/// bare entity object), used as a deterministic sort key.
+fn neighbor_sort_key(value: &Value) -> &str {
+    value
+        .get("entity")
+        .and_then(|entity| entity.get("id"))
+        .or_else(|| value.get("id"))
+        .and_then(Value::as_str)
+        .unwrap_or("")
+}
+
+/// Deterministic follow-up reads for an `orientation_pack`. Suggests the full
+/// source, a pre-spend cost preview, the owning subsystem, and a drill-down
+/// into the first callee (by sorted id) when one exists. Empty when there is no
+/// primary entity.
+fn orientation_suggested_reads(
+    packet: &Value,
+    primary_id: Option<&str>,
+    primary_kind: Option<&str>,
+) -> Vec<Value> {
+    let Some(primary_id) = primary_id else {
+        return Vec::new();
+    };
+    let mut reads = vec![
+        json!({
+            "tool": "source_for_entity",
+            "args": {"id": primary_id},
+            "why": "read the entity's source with line numbers",
+        }),
+        json!({
+            "tool": "summary_preview_cost",
+            "args": {"id": primary_id},
+            "why": "estimate the cost of an LLM briefing before spending",
+        }),
+    ];
+    // A subsystem's useful drill-down is its members; for any other kind it is
+    // the owning subsystem.
+    if primary_kind == Some("subsystem") {
+        reads.push(json!({
+            "tool": "subsystem_members",
+            "args": {"id": primary_id},
+            "why": "list the entities clustered into this subsystem",
+        }));
+    } else {
+        reads.push(json!({
+            "tool": "subsystem_of",
+            "args": {"id": primary_id},
+            "why": "see which subsystem this entity belongs to",
+        }));
+    }
+    // Drill into the first callee (lists are already id-sorted), if any.
+    if let Some(callee_id) = packet
+        .get("neighbors")
+        .and_then(|neighbors| neighbors.get("callees"))
+        .and_then(Value::as_array)
+        .and_then(|callees| callees.first())
+        .and_then(|callee| callee.get("entity"))
+        .and_then(|entity| entity.get("id"))
+        .and_then(Value::as_str)
+    {
+        reads.push(json!({
+            "tool": "orientation_pack",
+            "args": {"entity": callee_id},
+            "why": "orient on the primary callee",
+        }));
+    }
+    reads
+}
+
+/// How recently the analyze progress file must have been stamped for
+/// `analyze_status` to call progress "observed" rather than possibly stalled.
+const ANALYZE_HEARTBEAT_STALE_SECS: i64 = 30;
+
+/// Live state of a registry-tracked analyze run, captured under the lock.
+enum LiveRun {
+    Alive {
+        started_at: String,
+        progress_path: PathBuf,
+    },
+    Exited {
+        started_at: String,
+        cancelled: bool,
+    },
+    Absent,
+}
+
+/// Result of an `analyze_cancel` attempt against the registry.
+enum CancelOutcome {
+    Cancelled,
+    AlreadyExited { cancelled: bool },
+    Absent,
+}
+
+/// Read and parse the analyze progress snapshot, if present and valid JSON.
+fn read_progress_snapshot(path: &std::path::Path) -> Option<Value> {
+    let body = std::fs::read_to_string(path).ok()?;
+    serde_json::from_str(&body).ok()
+}
+
+/// Parse a timestamp to Unix seconds, accepting both the MCP clock's
+/// `unix:<seconds>` form and the RFC3339 form analyze writes into the progress
+/// file's `heartbeat_at`. `None` if neither parses.
+fn parse_to_unix_seconds(value: &str) -> Option<i64> {
+    use time::OffsetDateTime;
+    use time::format_description::well_known::Rfc3339;
+    if let Some(rest) = value.strip_prefix("unix:") {
+        return rest.trim().parse().ok();
+    }
+    OffsetDateTime::parse(value, &Rfc3339)
+        .ok()
+        .map(OffsetDateTime::unix_timestamp)
+}
+
+/// Whole seconds between two timestamps (`now - start`), or `None` if either
+/// fails to parse. Accepts mixed `unix:`/RFC3339 forms.
+fn elapsed_seconds(start: &str, now: &str) -> Option<i64> {
+    Some(parse_to_unix_seconds(now)? - parse_to_unix_seconds(start)?)
+}
+
+/// Whether the heartbeat is recent enough to treat the run as actively
+/// progressing (heartbeat age within `max_age_secs`).
+fn progress_observed(heartbeat: &str, now: &str, max_age_secs: i64) -> bool {
+    elapsed_seconds(heartbeat, now).is_some_and(|age| (0..=max_age_secs).contains(&age))
+}
+
+/// True when a run's `stats` JSON marks it as cancelled (vs an ordinary
+/// failure) — the MCP writes `terminal_reason="cancelled"` on cancel.
+fn run_stats_is_cancelled(stats_json: &str) -> bool {
+    serde_json::from_str::<Value>(stats_json)
+        .ok()
+        .and_then(|stats| {
+            stats
+                .get("terminal_reason")
+                .and_then(Value::as_str)
+                .map(|reason| reason == "cancelled")
+        })
+        .unwrap_or(false)
+}
+
+/// Map a `runs.status` value to the `analyze_status` vocabulary. A row still
+/// reading `running` after the process exited is abnormal (the process died
+/// without finalizing) and reported as `failed`.
+fn map_run_status(db_status: &str, stats_json: &str) -> &'static str {
+    match db_status {
+        "completed" => "completed",
+        "skipped_no_plugins" => "skipped_no_plugins",
+        "failed" if run_stats_is_cancelled(stats_json) => "cancelled",
+        _ => "failed",
+    }
+}
+
+/// Maximum number of (span + context) lines `source_for_entity` will emit
+/// before truncating, so a pathologically large entity never floods an agent's
+/// context. The span itself is bounded by the entity; this caps the total.
+const SOURCE_FOR_ENTITY_MAX_LINES: usize = 2_000;
+
+/// Direction for `call_sites`: outgoing (this entity is the caller) or incoming
+/// (this entity is the callee).
+#[derive(Clone, Copy)]
+enum CallSiteRole {
+    Caller,
+    Callee,
+}
+
+/// Edge-kind filter for `call_sites`.
+#[derive(Clone, Copy)]
+enum CallSiteKind {
+    Both,
+    Calls,
+    References,
+}
+
+impl CallSiteKind {
+    fn includes_calls(self) -> bool {
+        matches!(self, Self::Both | Self::Calls)
+    }
+    fn includes_references(self) -> bool {
+        matches!(self, Self::Both | Self::References)
+    }
+}
+
+/// Production/test path scope for `call_sites`. Best-effort: source-file
+/// production/test partitioning is not indexed, so this is a heuristic over the
+/// file path (documented as such in the tool description).
+#[derive(Clone, Copy)]
+enum PathScope {
+    All,
+    Production,
+    Test,
 }
 
-impl SourceExcerptError {
-    fn message(&self) -> String {
-        format!(
-            "entity {} source content drifted: stored content_hash {} but current file hashes to {}; rerun `clarion analyze` before requesting LLM output",
-            self.entity_id, self.stored_content_hash, self.current_content_hash
-        )
+impl PathScope {
+    fn admits(self, path: Option<&str>) -> bool {
+        match (self, path) {
+            (Self::All, _) => true,
+            // A site whose owning file can't be resolved is excluded from a
+            // narrowed scope rather than guessed into it.
+            (_, None) => false,
+            (Self::Test, Some(p)) => is_test_path(p),
+            (Self::Production, Some(p)) => !is_test_path(p),
+        }
     }
+}
 
-    fn to_envelope(&self) -> Value {
-        tool_error_envelope("content-drift", &self.message(), false)
-    }
+/// Conventional Python test-path heuristic (pytest/unittest layouts). Not a
+/// substitute for indexed metadata — see `PathScope`.
+fn is_test_path(path: &str) -> bool {
+    let lower = path.replace('\\', "/").to_ascii_lowercase();
+    let file = lower.rsplit('/').next().unwrap_or(lower.as_str());
+    lower.contains("/tests/")
+        || lower.contains("/test/")
+        || file.starts_with("test_")
+        || file.ends_with("_test.py")
+        || file == "conftest.py"
+}
 
-    fn to_inferred_failure(&self) -> InferredDispatchFailure {
-        InferredDispatchFailure::new("content-drift", &self.message(), false)
+/// Per-call cap on each of the resolved and unresolved site lists.
+const CALL_SITES_MAX: usize = 200;
+
+/// 1-based line and 0-based byte column for a byte offset into `content`.
+// The slices are a single source file; a dependency on `bytecount` for the
+// newline count is not warranted here.
+#[allow(clippy::naive_bytecount)]
+fn byte_line_col(content: &str, byte_offset: i64) -> Option<(i64, i64)> {
+    let off = usize::try_from(byte_offset).ok()?;
+    let bytes = content.as_bytes();
+    if off > bytes.len() {
+        return None;
     }
+    let line = bytes[..off].iter().filter(|&&b| b == b'\n').count() + 1;
+    let line_start = bytes[..off]
+        .iter()
+        .rposition(|&b| b == b'\n')
+        .map_or(0, |p| p + 1);
+    Some((
+        i64::try_from(line).ok()?,
+        i64::try_from(off - line_start).ok()?,
+    ))
 }
 
-fn summary_success_envelope(
+/// The text of `line` (1-based) in `content`, or empty if out of range.
+fn line_text_at(content: &str, line: i64) -> String {
+    let idx = usize::try_from(line - 1).unwrap_or(usize::MAX);
+    content.lines().nth(idx).unwrap_or("").to_owned()
+}
+
+/// One resolved call/reference site before file resolution.
+struct ResolvedSite {
+    owner_id: String,
+    edge_kind: &'static str,
+    other_id: String,
+    confidence: EdgeConfidence,
+    byte_start: Option<i64>,
+    byte_end: Option<i64>,
+}
+
+/// One static call Clarion could not bind (kept separate from resolved sites).
+struct UnboundSite {
+    owner_id: String,
+    callee_expr: String,
+    byte_start: i64,
+    byte_end: i64,
+}
+
+/// Gather the resolved and unbound (statically-unbindable) call/reference sites
+/// for `entity` in the requested direction, applying the edge-kind and
+/// confidence filters. File/line resolution happens in [`build_call_sites`].
+fn collect_call_sites(
+    conn: &rusqlite::Connection,
     entity: &EntityRow,
-    entry: &SummaryCacheEntry,
-    cache_hit: bool,
-    stale_semantic: bool,
-    stats_delta: Value,
-) -> Value {
-    let summary = serde_json::from_str::<Value>(&entry.summary_json).unwrap_or_else(|_| {
-        json!({
-            "raw": entry.summary_json
-        })
-    });
-    success_envelope_with_stats(
-        json!({
-            "available": true,
-            "entity": entity_json(entity),
-            "summary": summary,
-            "cache": {
-                "hit": cache_hit,
-                "prompt_template_id": entry.key.prompt_template_id,
-                "model_id": entry.key.model_tier,
-                "guidance_fingerprint": entry.key.guidance_fingerprint,
-                "stale_semantic": stale_semantic,
-                "created_at": entry.created_at,
-                "last_accessed_at": entry.last_accessed_at
+    role: CallSiteRole,
+    kind: CallSiteKind,
+    confidence: EdgeConfidence,
+) -> Result<(Vec<ResolvedSite>, Vec<UnboundSite>), StorageError> {
+    let mut resolved: Vec<ResolvedSite> = Vec::new();
+    let mut unbound: Vec<UnboundSite> = Vec::new();
+
+    match role {
+        CallSiteRole::Caller => {
+            if kind.includes_calls() {
+                for edge in call_edges_from(conn, &entity.id, confidence)? {
+                    resolved.push(ResolvedSite {
+                        owner_id: entity.id.clone(),
+                        edge_kind: "calls",
+                        other_id: edge.to_id,
+                        confidence: edge.confidence,
+                        byte_start: edge.source_byte_start,
+                        byte_end: edge.source_byte_end,
+                    });
+                }
+                for site in unresolved_call_sites_for_caller(conn, &entity.id, CALL_SITES_MAX)? {
+                    unbound.push(UnboundSite {
+                        owner_id: entity.id.clone(),
+                        callee_expr: site.callee_expr,
+                        byte_start: site.source_byte_start,
+                        byte_end: site.source_byte_end,
+                    });
+                }
+            }
+            if kind.includes_references() {
+                for r in reference_edges_for_entity(conn, &entity.id, ReferenceDirection::Out)? {
+                    if r.confidence <= confidence {
+                        resolved.push(ResolvedSite {
+                            owner_id: entity.id.clone(),
+                            edge_kind: "references",
+                            other_id: r.neighbor_id,
+                            confidence: r.confidence,
+                            byte_start: r.source_byte_start,
+                            byte_end: r.source_byte_end,
+                        });
+                    }
+                }
+            }
+        }
+        CallSiteRole::Callee => {
+            if kind.includes_calls() {
+                for edge in call_edges_targeting(conn, &entity.id, confidence)? {
+                    resolved.push(ResolvedSite {
+                        owner_id: edge.from_id.clone(),
+                        edge_kind: "calls",
+                        other_id: edge.from_id,
+                        confidence: edge.confidence,
+                        byte_start: edge.source_byte_start,
+                        byte_end: edge.source_byte_end,
+                    });
+                }
+                for site in unresolved_callers_for_target(conn, entity, CALL_SITES_MAX)? {
+                    unbound.push(UnboundSite {
+                        owner_id: site.caller_entity_id,
+                        callee_expr: site.callee_expr,
+                        byte_start: site.source_byte_start,
+                        byte_end: site.source_byte_end,
+                    });
+                }
+            }
+            if kind.includes_references() {
+                for r in reference_edges_for_entity(conn, &entity.id, ReferenceDirection::In)? {
+                    if r.confidence <= confidence {
+                        resolved.push(ResolvedSite {
+                            owner_id: r.neighbor_id.clone(),
+                            edge_kind: "references",
+                            other_id: r.neighbor_id,
+                            confidence: r.confidence,
+                            byte_start: r.source_byte_start,
+                            byte_end: r.source_byte_end,
+                        });
+                    }
+                }
+            }
+        }
+    }
+
+    Ok((resolved, unbound))
+}
+
+/// Build the `call_sites` payload. Returns `Ok(None)` when the entity does not
+/// exist (so the caller can emit a not-found envelope).
+fn build_call_sites(
+    conn: &rusqlite::Connection,
+    entity_id: &str,
+    role: CallSiteRole,
+    kind: CallSiteKind,
+    confidence: EdgeConfidence,
+    path: PathScope,
+) -> Result<Option<Value>, StorageError> {
+    let Some(entity) = entity_by_id(conn, entity_id)? else {
+        return Ok(None);
+    };
+
+    let (resolved, unbound) = collect_call_sites(conn, &entity, role, kind, confidence)?;
+
+    // Resolve each site's owning file + briefing-blocked state once, mapping
+    // the byte anchor to a line. A blocked owner's bytes are never read.
+    let mut owner_meta: HashMap<String, (Option<String>, bool)> = HashMap::new();
+    let mut file_content: HashMap<String, Option<String>> = HashMap::new();
+    // The queried entity's own path + block state are known without a lookup.
+    owner_meta.insert(
+        entity.id.clone(),
+        (
+            entity.source_file_path.clone(),
+            briefing_block_reason(&entity).is_some(),
+        ),
+    );
+
+    let mut site_values = Vec::new();
+    let mut truncated = false;
+    for site in resolved {
+        if site_values.len() >= CALL_SITES_MAX {
+            truncated = true;
+            break;
+        }
+        let (path_str, blocked) = resolve_owner(conn, &mut owner_meta, &site.owner_id)?;
+        if !path.admits(path_str.as_deref()) {
+            continue;
+        }
+        // Never read a briefing-blocked owner's file; redact line_text.
+        let (line, column, line_text) = if blocked {
+            (Value::Null, Value::Null, String::new())
+        } else {
+            anchor_line(&mut file_content, path_str.as_deref(), site.byte_start)
+        };
+        site_values.push(json!({
+            "edge_kind": site.edge_kind,
+            "other_id": site.other_id,
+            "confidence": site.confidence.as_str(),
+            "file": path_str,
+            "line": line,
+            "column": column,
+            "line_text": line_text,
+            "briefing_blocked": blocked,
+            "byte_start": site.byte_start,
+            "byte_end": site.byte_end
+        }));
+    }
+
+    let mut unresolved_values = Vec::new();
+    for site in unbound {
+        if unresolved_values.len() >= CALL_SITES_MAX {
+            truncated = true;
+            break;
+        }
+        let (path_str, blocked) = resolve_owner(conn, &mut owner_meta, &site.owner_id)?;
+        if !path.admits(path_str.as_deref()) {
+            continue;
+        }
+        // Never read a briefing-blocked owner's file; redact line_text.
+        let (line, column, line_text) = if blocked {
+            (Value::Null, Value::Null, String::new())
+        } else {
+            anchor_line(
+                &mut file_content,
+                path_str.as_deref(),
+                Some(site.byte_start),
+            )
+        };
+        unresolved_values.push(json!({
+            "callee_expr": site.callee_expr,
+            "file": path_str,
+            "line": line,
+            "column": column,
+            "line_text": line_text,
+            "briefing_blocked": blocked,
+            "byte_start": site.byte_start,
+            "byte_end": site.byte_end
+        }));
+    }
+
+    Ok(Some(json!({
+        "entity": entity_json(&entity),
+        "role": match role { CallSiteRole::Caller => "caller", CallSiteRole::Callee => "callee" },
+        "filters": {
+            "kind": match kind {
+                CallSiteKind::Both => "both",
+                CallSiteKind::Calls => "calls",
+                CallSiteKind::References => "references",
             },
-            "usage": {
-                "tokens_input": entry.tokens_input,
-                "tokens_output": entry.tokens_output,
-                "tokens_total": entry.tokens_input + entry.tokens_output
+            "confidence": confidence.as_str(),
+            "path": match path {
+                PathScope::All => "all",
+                PathScope::Production => "production",
+                PathScope::Test => "test",
             }
-        }),
-        stats_delta,
-    )
+        },
+        "sites": site_values,
+        "unresolved_sites": unresolved_values,
+        "truncated": truncated,
+        "scope_excludes": call_graph_scope_excludes(confidence)
+    })))
 }
 
-fn summary_scope_deferred(entity: &EntityRow) -> Value {
-    success_envelope(json!({
-        "available": false,
-        "reason": "summary-scope-deferred",
-        "message": "subsystem summaries are deferred to v0.2",
-        "entity": entity_json(entity)
-    }))
+/// Memoized lookup of an owner entity's `(source_file_path, briefing_blocked)`.
+/// A briefing-blocked owner's source bytes must never be read — the pre-ingest
+/// scanner withholds them — so `call_sites` redacts `line_text` for such owners
+/// rather than disclosing the file content behind an edge.
+fn resolve_owner(
+    conn: &rusqlite::Connection,
+    cache: &mut HashMap<String, (Option<String>, bool)>,
+    owner_id: &str,
+) -> Result<(Option<String>, bool), StorageError> {
+    if let Some(meta) = cache.get(owner_id) {
+        return Ok(meta.clone());
+    }
+    let meta = match entity_by_id(conn, owner_id)? {
+        Some(entity) => (
+            entity.source_file_path.clone(),
+            briefing_block_reason(&entity).is_some(),
+        ),
+        None => (None, false),
+    };
+    cache.insert(owner_id.to_owned(), meta.clone());
+    Ok(meta)
 }
 
-fn tool_json_rpc_response(id: &Value, envelope: &Value) -> Value {
-    let is_error = !envelope
-        .get("ok")
-        .and_then(Value::as_bool)
-        .unwrap_or_default();
-    result_response(
-        id,
-        &json!({
-            "content": [
-                {
-                    "type": "text",
-                    "text": serde_json::to_string(&envelope).expect("tool envelope serializes")
-                }
-            ],
-            "isError": is_error
-        }),
-    )
+/// Map a byte anchor to (line, column, `line_text`), reading + caching the file.
+/// Any piece that can't be resolved degrades to JSON null / empty rather than
+/// failing the whole query.
+fn anchor_line(
+    file_content: &mut HashMap<String, Option<String>>,
+    path: Option<&str>,
+    byte_start: Option<i64>,
+) -> (Value, Value, String) {
+    let (Some(path), Some(byte_start)) = (path, byte_start) else {
+        return (Value::Null, Value::Null, String::new());
+    };
+    let content = file_content
+        .entry(path.to_owned())
+        .or_insert_with(|| std::fs::read_to_string(path).ok());
+    let Some(content) = content.as_deref() else {
+        return (Value::Null, Value::Null, String::new());
+    };
+    match byte_line_col(content, byte_start) {
+        Some((line, column)) => (json!(line), json!(column), line_text_at(content, line)),
+        None => (Value::Null, Value::Null, String::new()),
+    }
 }
 
-fn entity_json(entity: &EntityRow) -> Value {
+/// Build the `source_for_entity` payload: the entity's exact indexed line span
+/// plus `context_lines` of surrounding context, line-numbered and drift-checked.
+///
+/// Returns an explicit `source_status` rather than a stale or misleading
+/// snippet when the source cannot be trusted: `missing` (file gone),
+/// `no_source_path` / `no_range` (no anchor to read), `binary` (non-UTF-8), or
+/// `drifted` (the file no longer hashes to the indexed `content_hash`).
+fn source_for_entity_json(entity: &EntityRow, context_lines: usize) -> Value {
+    let identity = entity_json(entity);
+
+    // Refuse to read or return bytes for an entity whose file the pre-ingest
+    // scanner marked `briefing_blocked`. Without this guard, an agent holding
+    // the id of a function/class in a secret-bearing file could use
+    // source_for_entity to disclose exactly the bytes the scanner policy
+    // withholds (the summary / HTTP read surfaces already refuse these).
+    if let Some(reason) = briefing_block_reason(entity) {
+        return json!({
+            "entity": identity,
+            "source_status": "briefing_blocked",
+            "briefing_blocked": reason
+        });
+    }
+
+    let Some(path) = entity.source_file_path.as_deref() else {
+        return json!({"entity": identity, "source_status": "no_source_path"});
+    };
+    let (Some(start_line), Some(end_line)) = (entity.source_line_start, entity.source_line_end)
+    else {
+        return json!({
+            "entity": identity,
+            "source_file_path": path,
+            "source_status": "no_range"
+        });
+    };
+
+    let Ok(bytes) = std::fs::read(path) else {
+        return json!({
+            "entity": identity,
+            "source_file_path": path,
+            "source_status": "missing"
+        });
+    };
+    let Ok(source) = String::from_utf8(bytes.clone()) else {
+        return json!({
+            "entity": identity,
+            "source_file_path": path,
+            "source_status": "binary"
+        });
+    };
+
+    // Refuse to hand back a snippet that no longer matches what was indexed.
+    if let (Some(stored), Some(current)) = (
+        entity.content_hash.as_deref(),
+        current_source_content_hash(entity, &bytes, Some(&source)),
+    ) && stored != current
+    {
+        return json!({
+            "entity": identity,
+            "source_file_path": path,
+            "source_status": "drifted",
+            "drift": {
+                "stored_content_hash": stored,
+                "current_content_hash": current
+            }
+        });
+    }
+
+    let lines: Vec<&str> = source.lines().collect();
+    let total = i64::try_from(lines.len()).unwrap_or(i64::MAX);
+    // Clamp the span to the file, then widen by the context window. 1-based,
+    // inclusive on both ends.
+    let span_start = start_line.max(1);
+    let span_end = end_line.min(total).max(span_start);
+    let ctx = i64::try_from(context_lines).unwrap_or(i64::MAX);
+    let window_start = (span_start - ctx).max(1);
+    let window_end = (span_end + ctx).min(total);
+
+    let mut emitted = Vec::new();
+    let mut truncated = false;
+    let mut number = window_start;
+    while number <= window_end {
+        if emitted.len() >= SOURCE_FOR_ENTITY_MAX_LINES {
+            truncated = true;
+            break;
+        }
+        let idx = usize::try_from(number - 1).unwrap_or(usize::MAX);
+        let text = lines.get(idx).copied().unwrap_or("");
+        emitted.push(json!({
+            "number": number,
+            "text": text,
+            "in_entity": number >= span_start && number <= span_end
+        }));
+        number += 1;
+    }
+
     json!({
-        "id": entity.id,
-        "kind": entity.kind,
-        "name": entity.name,
-        "short_name": entity.short_name,
-        "source_file_path": entity.source_file_path,
-        "source_line_start": entity.source_line_start,
-        "source_line_end": entity.source_line_end,
-        "content_hash": entity.content_hash
+        "entity": identity,
+        "source_file_path": path,
+        "source_status": "ok",
+        "line_start": span_start,
+        "line_end": span_end,
+        "context_lines": context_lines,
+        "window_start": window_start,
+        "window_end": window_end,
+        "lines": emitted,
+        "truncated": truncated
     })
 }
 
-fn entity_properties_json(entity: &EntityRow) -> Value {
-    serde_json::from_str::<Value>(&entity.properties_json)
-        .expect("entity properties_json should be valid JSON")
-}
-
 fn verified_source_excerpt(entity: &EntityRow) -> Result<String, SourceExcerptError> {
     let Some(path) = entity.source_file_path.as_deref() else {
         return Ok(String::new());
@@ -2579,6 +5321,20 @@ fn timestamp_day_index(raw: &str) -> Option<i64> {
     Some(i64::from(date.to_julian_day() - unix_epoch.to_julian_day()))
 }
 
+/// The `max_output_tokens` ceiling a leaf summary request reserves. Reported by
+/// `summary_preview_cost` as the output ceiling (not a length prediction).
+const SUMMARY_MAX_OUTPUT_TOKENS: i64 = 512;
+
+/// A provider-free, deterministic input-token estimate for `summary_preview_cost`:
+/// roughly four characters per token. Intended only as a pre-spend order-of-
+/// magnitude hint, not an exact count (the real count is recorded on the cache
+/// row once a summary has actually run).
+fn estimate_tokens_from_chars(text: &str) -> i64 {
+    let chars = i64::try_from(text.chars().count()).unwrap_or(i64::MAX);
+    // ceil(chars / 4) without the unstable i64::div_ceil.
+    chars.saturating_add(3) / 4
+}
+
 fn default_now_string() -> String {
     let seconds = OffsetDateTime::now_utc().unix_timestamp();
     format!("unix:{seconds}")
@@ -2615,22 +5371,177 @@ fn callee_json(
     }))
 }
 
-fn path_json(conn: &rusqlite::Connection, path: &[String]) -> Result<Value, StorageError> {
-    let entities = path
+/// Compacted execution-path payload: a deduplicated node table, id-only ranked
+/// paths, and whether the path cap trimmed the ranked set.
+struct CompactPaths {
+    nodes: Vec<Value>,
+    paths: Vec<Vec<String>>,
+    path_cap_truncated: bool,
+}
+
+/// Compact, ranked execution-path payload (clarion-5b3eff9a91). Ranks paths
+/// longest-first (deepest reachable flow) with a lexicographic tie-break for
+/// determinism, applies the server path cap (clarion-23ae24358c), then emits a
+/// deduplicated node table so each entity is serialized once instead of once per
+/// path occurrence — the old per-path re-serialization produced responses that
+/// blew the transport budget.
+fn compact_execution_paths(
+    conn: &rusqlite::Connection,
+    mut paths: Vec<Vec<String>>,
+    path_cap: usize,
+) -> Result<CompactPaths, StorageError> {
+    paths.sort_by(|a, b| b.len().cmp(&a.len()).then_with(|| a.cmp(b)));
+    let path_cap_truncated = paths.len() > path_cap;
+    paths.truncate(path_cap);
+
+    let mut node_ids: BTreeSet<String> = BTreeSet::new();
+    for path in &paths {
+        for id in path {
+            node_ids.insert(id.clone());
+        }
+    }
+    let nodes = node_ids
         .iter()
-        .filter_map(|entity_id| entity_by_id(conn, entity_id).transpose())
-        .map(|row| row.map(|entity| entity_json(&entity)))
+        .filter_map(|id| entity_by_id(conn, id).transpose())
+        .map(|row| row.map(|entity| compact_node_json(&entity)))
         .collect::<Result<Vec<_>, StorageError>>()?;
-    Ok(Value::Array(entities))
+    Ok(CompactPaths {
+        nodes,
+        paths,
+        path_cap_truncated,
+    })
+}
+
+/// Truncation reason for an execution-path response. `edge-cap` (traversal
+/// stopped early, so the graph itself is incomplete) takes precedence over
+/// `path-cap` (traversal finished but the ranked output was trimmed for size,
+/// clarion-23ae24358c).
+fn path_truncation_reason(edge_truncated: bool, path_cap_truncated: bool) -> Option<&'static str> {
+    if edge_truncated {
+        Some("edge-cap")
+    } else if path_cap_truncated {
+        Some("path-cap")
+    } else {
+        None
+    }
+}
+
+/// A path node trimmed for token economy: identity + location only. The full id
+/// already encodes the qualified name; `content_hash` and the redundant `name`
+/// are dropped (clarion-5b3eff9a91).
+fn compact_node_json(entity: &EntityRow) -> Value {
+    json!({
+        "id": entity.id,
+        "kind": entity.kind,
+        "short_name": entity.short_name,
+        "source_file_path": entity.source_file_path,
+        "source_line_start": entity.source_line_start,
+        "source_line_end": entity.source_line_end
+    })
 }
 
 fn reference_neighbors(
     conn: &rusqlite::Connection,
     entity_id: &str,
     direction: ReferenceDirection,
+) -> Result<Vec<Value>, StorageError> {
+    edge_neighbors_json(
+        conn,
+        reference_edges_for_entity(conn, entity_id, direction)?,
+    )
+}
+
+/// `imports`-edge neighbors for a module entity (clarion-79d0ff6e14). Direction
+/// `In` is the reverse-import lookup ("who imports this module").
+fn import_neighbors(
+    conn: &rusqlite::Connection,
+    entity_id: &str,
+    direction: ReferenceDirection,
+) -> Result<Vec<Value>, StorageError> {
+    edge_neighbors_json(conn, import_edges_for_entity(conn, entity_id, direction)?)
+}
+
+/// Reference neighbors for `neighborhood` / `orientation_pack`, rolled up to
+/// module altitude when the entity is a module (clarion-79d0ff6e14).
+///
+/// References are tracked symbol-to-symbol, so a module's OWN reference edges
+/// are almost always empty — "who imports this module / contract?" used to
+/// answer `[]`. For a module we instead aggregate the `references` edges of
+/// every transitively contained symbol (excluding intra-module wiring) and tag
+/// each neighbor with the contained `via` symbol it touches. For any other
+/// kind the direct symbol-level edges are returned unchanged (no `via`).
+///
+/// Returns `(neighbors, rolled_up)`; `rolled_up` is true only for modules.
+fn reference_neighbors_for(
+    conn: &rusqlite::Connection,
+    entity_id: &str,
+    entity_kind: &str,
+    direction: ReferenceDirection,
+) -> Result<(Vec<Value>, bool), StorageError> {
+    if entity_kind == "module" {
+        let edges = module_reference_rollup(conn, entity_id, direction)?;
+        Ok((rolled_up_neighbors_json(conn, edges, direction)?, true))
+    } else {
+        Ok((reference_neighbors(conn, entity_id, direction)?, false))
+    }
+}
+
+fn rolled_up_neighbors_json(
+    conn: &rusqlite::Connection,
+    edges: Vec<RolledUpReferenceEdge>,
+    direction: ReferenceDirection,
+) -> Result<Vec<Value>, StorageError> {
+    let mut neighbors = Vec::new();
+    for edge in edges {
+        if let Some(entity) = entity_by_id(conn, &edge.neighbor_id)? {
+            let via = entity_by_id(conn, &edge.via_id)?;
+            let mut object = serde_json::Map::new();
+            object.insert("entity".to_owned(), entity_json(&entity));
+            object.insert(
+                "edge_confidence".to_owned(),
+                json!(edge.confidence.as_str()),
+            );
+            object.insert(
+                "source_byte_start".to_owned(),
+                json!(edge.source_byte_start),
+            );
+            object.insert("source_byte_end".to_owned(), json!(edge.source_byte_end));
+            // The module-contained symbol this edge actually touches, so a
+            // rolled-up "who imports this module" answer names the importer
+            // (entity) AND the imported symbol (via).
+            object.insert(
+                "via".to_owned(),
+                via.as_ref().map_or(Value::Null, entity_json),
+            );
+            // Reverse-import altitude (clarion-79d0ff6e14): the edge is recorded
+            // against the importing *symbol*, but "who imports this module /
+            // contract" is a module-altitude question, so name the importer's
+            // containing module too. Only meaningful for the `In` direction
+            // (the neighbor is the importer); `Out` neighbors are referenced
+            // symbols, not importers. `null` for an importer with no module
+            // ancestor.
+            if direction == ReferenceDirection::In {
+                let importer_module = match containing_module_id(conn, &edge.neighbor_id)? {
+                    Some(module_id) => entity_by_id(conn, &module_id)?,
+                    None => None,
+                };
+                object.insert(
+                    "importer_module".to_owned(),
+                    importer_module.as_ref().map_or(Value::Null, entity_json),
+                );
+            }
+            neighbors.push(Value::Object(object));
+        }
+    }
+    Ok(neighbors)
+}
+
+fn edge_neighbors_json(
+    conn: &rusqlite::Connection,
+    edges: Vec<ReferenceEdgeMatch>,
 ) -> Result<Vec<Value>, StorageError> {
     let mut neighbors = Vec::new();
-    for edge in reference_edges_for_entity(conn, entity_id, direction)? {
+    for edge in edges {
         if let Some(entity) = entity_by_id(conn, &edge.neighbor_id)? {
             neighbors.push(json!({
                 "entity": entity_json(&entity),
@@ -2680,47 +5591,109 @@ mod tests {
     fn tools_list_exposes_exact_docstrings() {
         let tools = list_tools();
 
-        assert_eq!(tools.len(), 8);
+        assert_eq!(tools.len(), 18);
         assert_eq!(tools[0].name, "entity_at");
         assert_eq!(
             tools[0].description,
-            "Return the innermost Clarion entity whose source range contains a file and line. Paths are normalized relative to the project root. Returns no match rather than guessing when ranges are absent."
+            "Return the innermost Clarion entity whose source range contains a file and line, plus an `entity_context` evidence block: match_reason (decorator_range / declaration / body_range / containing_range / no_match) explaining why the line matched, the module→entity containing stack, the matched entity's decl/body/decorator sub-ranges, any same-granularity ambiguity alternatives, and index freshness. Paths are normalized relative to the project root. A blank or comment line that only a module spans reports containing_range — never a fabricated exact match."
         );
         assert_eq!(tools[1].name, "find_entity");
         assert_eq!(
             tools[1].description,
-            "Search Clarion entities by id, name, short name, and summary text stored on entity rows. Results are paginated and ranked by FTS match where possible. This does not traverse the graph and does not search on-demand summary_cache entries."
+            "Search Clarion entities by id, name, short name, and summary text stored on entity rows. Results are paginated and ranked by FTS match where possible. This does not traverse the graph and does not search on-demand summary_cache entries. Pass an optional `kind` (e.g. \"subsystem\", \"function\", \"class\", \"module\") to return only entities of that kind — the way to locate a subsystem without visually filtering results."
         );
         assert_eq!(tools[2].name, "callers_of");
         assert_eq!(
             tools[2].description,
-            "Return entities that call the given entity. Default confidence is resolved, so ambiguous static candidates and LLM-inferred edges are excluded unless explicitly requested. Ambiguous edges expand all candidates; inferred edges may trigger bounded LLM dispatch."
+            "Return entities that call the given entity. Default confidence is resolved, so ambiguous static candidates and LLM-inferred edges are excluded unless explicitly requested. Ambiguous edges expand all candidates; inferred edges may trigger bounded LLM dispatch. The result carries scope_excludes naming static blind spots not searched (e.g. attribute-receiver-calls) so an empty callers list is never read as a guaranteed true negative."
         );
         assert_eq!(tools[3].name, "execution_paths_from");
         assert_eq!(
-            tools[3].description,
-            "Return bounded calls-only execution paths starting at an entity. Default confidence is resolved. max_depth defaults to 3 and traversal also stops at the server edge cap; responses say when they are truncated."
+            tools[3].description,
+            "Return bounded calls-only execution paths starting at an entity. Default confidence is resolved. max_depth defaults to 3. Results are compact: a deduplicated nodes table plus paths as arrays of node ids (under a root), ranked longest-first. Traversal stops at the server edge cap and the response is capped at a maximum number of ranked paths; truncated/truncation_reason report edge-cap or path-cap when either trims. The result carries scope_excludes naming static blind spots not searched (e.g. attribute-receiver-calls)."
+        );
+        assert_eq!(tools[4].name, "summary");
+        assert_eq!(
+            tools[4].description,
+            "Return an on-demand cached summary for one entity. In v0.1 this is leaf scope only: module summaries describe the module docstring and top-level members, not an aggregation of contained function/class summaries. If the LLM returns non-JSON the response degrades to a deterministic structural summary (kind: structural-fallback) built from the entity source, and that fallback is cached so a retry is a free cache hit rather than a re-billed failure."
+        );
+        assert_eq!(tools[5].name, "issues_for");
+        assert_eq!(
+            tools[5].description,
+            "Return Filigree issues attached to this Clarion entity, optionally including issues attached to contained entities. Filigree is an enrichment source; if unavailable, the tool returns an unavailable envelope instead of failing Clarion. The result carries a result_kind (matched | no_matches | unavailable) so a reachable-but-empty Filigree is distinct from an unreachable one, and a filigree_endpoint block (configured vs resolved URL + resolution_source) so you can see which endpoint — e.g. a live ethereal port — the answer came from. Each matched/drifted entry carries an `issue` object with the issue's title, status, and priority (fetched once per distinct issue, no N+1); `issue` is null when the issue-detail route is unavailable, so the match still resolves without a second hop into Filigree."
+        );
+        assert_eq!(tools[6].name, "neighborhood");
+        assert_eq!(
+            tools[6].description,
+            "Return the one-hop Clarion neighborhood around an entity: callers, callees, container, contained entities, references, and imports (imports_in = who imports this module, imports_out = what it imports; module-to-module). Default confidence is resolved; ambiguous and inferred calls are opt-in. References and imports are not execution flow. When the entity is a module, references_in/references_out are rolled up over the symbols it contains (references_rolled_up=true) — each neighbor carries a `via` naming the contained symbol the edge touches, so \"who imports this module/contract\" is answered at module altitude rather than reading empty. On references_in each rolled-up neighbor also carries `importer_module` — the importing symbol's containing module — so reverse-import names importing modules, not just symbols. The result carries scope_excludes naming blind spots not searched (e.g. attribute-receiver-calls) so empty sections are never read as guaranteed true negatives."
+        );
+        assert_eq!(tools[7].name, "subsystem_members");
+        assert_eq!(
+            tools[7].description,
+            "List module entities assigned to a subsystem entity."
+        );
+        assert_eq!(tools[8].name, "subsystem_of");
+        assert_eq!(
+            tools[8].description,
+            "Return the subsystem an entity belongs to — the reverse of subsystem_members. Accepts any entity id: a module resolves directly, while a function/class resolves through its nearest containing module. Returns the subsystem id/name and the module the membership was resolved through, or a no-subsystem result when the entity has no subsystem-assigned module ancestor."
+        );
+        assert_eq!(tools[9].name, "project_status");
+        assert_eq!(
+            tools[9].description,
+            "Return deterministic Clarion diagnostics: repo root, db path, latest run (id/status/started/completed), entity/subsystem/edge/finding/briefing-blocked counts, index staleness, per-plugin entity counts from the current index, LLM policy (provider/live/cache), and the resolved Filigree endpoint (configured vs resolved URL + resolution source). Answers \"is the graph fresh, plugin-less, LLM-live, Filigree-reachable?\" without shelling out. No LLM call."
+        );
+        assert_eq!(tools[10].name, "summary_preview_cost");
+        assert_eq!(
+            tools[10].description,
+            "Preview what calling summary(id) would cost BEFORE spending. Reports cache_status (hit | expired | miss), the cached row's real tokens/cost/age on a hit, an input-token estimate on a miss, the configured model, the LLM policy (provider/live/allow_live_provider/cache horizon), and live_spend_would_occur — true only when no fresh cache row exists AND a live provider is wired. A disabled/unconfigured LLM is reported distinctly from a cache miss. Never invokes the LLM provider."
+        );
+        assert_eq!(tools[11].name, "source_for_entity");
+        assert_eq!(
+            tools[11].description,
+            "Return the exact indexed source span for one entity (its source_line_start..source_line_end, which includes any decorators/signature/docstring the plugin captured) plus a bounded window of surrounding context, as line-numbered lines each flagged in_entity true/false. No LLM call. Lets an agent read and trust the entity without shelling out. source_status reports `ok`, or — instead of a misleading stale snippet — `missing` (file gone), `no_range`/`no_source_path` (entity has no anchor), `binary` (non-UTF-8), or `drifted` (the file no longer matches the indexed content_hash; rerun `clarion analyze`). context_lines defaults to 10."
+        );
+        assert_eq!(tools[12].name, "call_sites");
+        assert_eq!(
+            tools[12].description,
+            "Show the actual source sites behind calls/references edges, so an agent can see WHY Clarion believes an edge exists rather than trusting it blind. role=caller (default) returns this entity's outgoing sites (what it calls/references); role=callee returns incoming sites (who calls/references it). Each site carries the file path, 1-based line, byte column, the source line text, edge kind, confidence, and a resolution of resolved | ambiguous (with candidate ids) | unresolved (a static call Clarion could not bind, kept separate so it is never mixed with resolved evidence). Filter by edge kind (`calls`/`references`) and by a best-effort production/test path heuristic (`all`/`production`/`test`; path partitioning is not indexed — the heuristic matches conventional test paths). Output is bounded; truncated flags when the site cap trims. No LLM call."
         );
-        assert_eq!(tools[4].name, "summary");
+        assert_eq!(tools[13].name, "orientation_pack");
         assert_eq!(
-            tools[4].description,
-            "Return an on-demand cached summary for one entity. In v0.1 this is leaf scope only: module summaries describe the module docstring and top-level members, not an aggregation of contained function/class summaries."
+            tools[13].description,
+            "Assemble one deterministic orientation packet for a code location — the replacement for hand-composing find_entity + entity_at + source reads + neighborhood + issues_for + freshness on every question. Resolve EITHER by `entity` id OR by `file`+`line` (exactly one form). The packet bundles: the primary entity, the entity_context evidence (match_reason / containing stack / decl-body-decorator ranges — so a decorator-line query is explained, not guessed), a compact source-span summary, one-hop neighbors (callers, callees, container, contained, references, imports — for a module, references_in/out are rolled up over contained symbols with references_rolled_up=true), compact resolved execution paths, related Filigree issues, index/Filigree/LLM health, warnings, and suggested next reads. No LLM summary is invoked. Every list is bounded; an `omitted` block reports per-section truncation counts and `degraded` sections name surfaces that were unavailable (e.g. Filigree down) so an empty section is never read as a guaranteed negative."
         );
-        assert_eq!(tools[5].name, "issues_for");
+        assert_eq!(tools[14].name, "analyze_start");
         assert_eq!(
-            tools[5].description,
-            "Return Filigree issues attached to this Clarion entity, optionally including issues attached to contained entities. Filigree is an enrichment source; if unavailable, the tool returns an unavailable envelope instead of failing Clarion."
+            tools[14].description,
+            "Start a `clarion analyze` run over this project in the background and return its run handle immediately — do not block on the (possibly many-minute) run. Re-indexes the source tree and refreshes entities/edges/subsystems. Returns run_id, status (`started`), and the progress-file path. Only one analyze may run per project at a time (a cross-process lock enforces it); a second start while one is active is rejected. Poll analyze_status for progress; analyze_cancel to stop. No arguments."
         );
-        assert_eq!(tools[6].name, "neighborhood");
+        assert_eq!(tools[15].name, "analyze_status");
         assert_eq!(
-            tools[6].description,
-            "Return the one-hop Clarion neighborhood around an entity: callers, callees, container, contained entities, and references. Default confidence is resolved; ambiguous and inferred calls are opt-in. References are not execution flow."
+            tools[15].description,
+            "Report the live status of an analyze run started via analyze_start. status is one of queued (spawned, not yet recording) | running | completed | failed | cancelled | skipped_no_plugins. While running it exposes phase (discovering / analyzing / clustering), current_plugin, processed_files / total_files, current_file, the latest heartbeat_at, elapsed_seconds, and progress_observed (false when the heartbeat has gone stale — the run may be wedged). On a terminal status it carries the recorded run stats. Reads structured progress, never logs."
         );
-        assert_eq!(tools[7].name, "subsystem_members");
+        assert_eq!(tools[16].name, "analyze_cancel");
         assert_eq!(
-            tools[7].description,
-            "List module entities assigned to a subsystem entity."
+            tools[16].description,
+            "Cancel a running analyze. SIGKILLs the run's whole process group — terminating the language plugin and its pyright-langserver child — then marks the run terminal (status `cancelled`) so it is never left dangling as `running`. Idempotent: cancelling an already-terminal run reports its current state. Partial work already written is kept (cancel discards in-flight work, not the index)."
         );
+        assert_eq!(tools[17].name, "index_diff");
+    }
+
+    #[test]
+    fn server_instructions_enumerate_every_tool() {
+        // Single-source guard (clarion-71f0d6c3dd): the `instructions` tool list
+        // is derived from list_tools(), so every advertised tool must appear in
+        // it. If a tool is added/removed and this drifts, the instructions would
+        // otherwise silently misdescribe the surface.
+        let instructions = super::server_instructions();
+        for tool in super::list_tools() {
+            assert!(
+                instructions.contains(tool.name),
+                "instructions omit tool {:?}; instructions were:\n{instructions}",
+                tool.name
+            );
+        }
     }
 
     #[test]
@@ -2734,7 +5707,8 @@ mod tests {
                 "capabilities": {},
                 "clientInfo": {"name": "test-client", "version": "0.0.0"}
             }
-        }));
+        }))
+        .expect("initialize request returns a response");
 
         assert_eq!(response["jsonrpc"], "2.0");
         assert_eq!(response["id"], 1);
@@ -2744,6 +5718,254 @@ mod tests {
         );
         assert_eq!(response["result"]["serverInfo"]["name"], "clarion");
         assert!(response["result"]["capabilities"]["tools"].is_object());
+        // Orientation instructions present and mention the skill + entity model.
+        let instructions = response["result"]["instructions"]
+            .as_str()
+            .expect("initialize result has instructions");
+        assert!(
+            instructions.contains("clarion-workflow"),
+            "instructions should point at the skill"
+        );
+        assert!(
+            instructions.contains("entity"),
+            "instructions should describe the entity model"
+        );
+        // The stateless free handler does NOT serve resources/* or prompts/*,
+        // so it must not advertise those capabilities (a client enabling those
+        // flows against the stateless server would otherwise fail).
+        assert!(
+            response["result"]["capabilities"]["prompts"].is_null(),
+            "stateless initialize must not advertise prompts: {response:?}"
+        );
+        assert!(
+            response["result"]["capabilities"]["resources"].is_null(),
+            "stateless initialize must not advertise resources: {response:?}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stateful_initialize_advertises_prompts_and_resources() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2025-11-25",
+                    "capabilities": {},
+                    "clientInfo": {"name": "test-client", "version": "0.0.0"}
+                }
+            }))
+            .await
+            .expect("initialize request returns a response");
+
+        // The production (ServerState) path serves prompts/* and resources/*,
+        // so its initialize must advertise the full capability surface.
+        assert!(response["result"]["capabilities"]["tools"].is_object());
+        assert!(
+            response["result"]["capabilities"]["prompts"].is_object(),
+            "stateful initialize must advertise prompts: {response:?}"
+        );
+        assert!(
+            response["result"]["capabilities"]["resources"].is_object(),
+            "stateful initialize must advertise resources: {response:?}"
+        );
+        let instructions = response["result"]["instructions"]
+            .as_str()
+            .expect("initialize result has instructions");
+        assert!(
+            instructions.contains("clarion-workflow"),
+            "instructions should point at the skill"
+        );
+    }
+
+    #[tokio::test]
+    async fn resources_list_includes_clarion_context() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "resources/list",
+                "params": {}
+            }))
+            .await
+            .expect("response");
+
+        let resources = response["result"]["resources"].as_array().unwrap();
+        assert!(
+            resources.iter().any(|r| r["uri"] == "clarion://context"),
+            "clarion://context not listed: {resources:?}"
+        );
+    }
+
+    #[tokio::test]
+    async fn resources_read_returns_context_snapshot_json() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+            conn.execute(
+                "INSERT INTO entities \
+                 (id, plugin_id, kind, name, short_name, properties, created_at, updated_at) \
+                 VALUES ('python:module:m','python','module','m','m','{}', \
+                         '2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')",
+                [],
+            )
+            .unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 7,
+                "method": "resources/read",
+                "params": {"uri": "clarion://context"}
+            }))
+            .await
+            .expect("response");
+
+        let text = response["result"]["contents"][0]["text"]
+            .as_str()
+            .expect("snapshot text");
+        let parsed: serde_json::Value = serde_json::from_str(text).unwrap();
+        assert_eq!(parsed["db_present"], true);
+        assert_eq!(parsed["entity_count"], 1);
+        assert_eq!(parsed["staleness"], "never_analyzed");
+        // A healthy read carries `degraded: false`, distinguishing it from the
+        // reader-error fallback which sets `degraded: true`.
+        assert_eq!(
+            parsed["degraded"], false,
+            "healthy snapshot must not be degraded"
+        );
+    }
+
+    #[tokio::test]
+    async fn resources_read_rejects_unknown_uri() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 8,
+                "method": "resources/read",
+                "params": {"uri": "clarion://nope"}
+            }))
+            .await
+            .expect("response");
+        assert!(response["error"].is_object(), "expected an error envelope");
+        assert_eq!(response["error"]["code"], -32602, "{response:?}");
+    }
+
+    #[tokio::test]
+    async fn prompts_get_rejects_unknown_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 11,
+                "method": "prompts/get",
+                "params": {"name": "nope"}
+            }))
+            .await
+            .expect("response");
+        assert!(response["error"].is_object(), "expected an error envelope");
+        assert_eq!(response["error"]["code"], -32602, "{response:?}");
+    }
+
+    #[tokio::test]
+    async fn prompts_get_returns_skill_text() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 9,
+                "method": "prompts/get",
+                "params": {"name": "clarion-workflow"}
+            }))
+            .await
+            .expect("response");
+        let text = response["result"]["messages"][0]["content"]["text"]
+            .as_str()
+            .unwrap();
+        assert!(
+            text.contains("name: clarion-workflow"),
+            "not the skill text"
+        );
+    }
+
+    #[tokio::test]
+    async fn prompts_list_includes_clarion_workflow() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 10,
+                "method": "prompts/list",
+                "params": {}
+            }))
+            .await
+            .expect("response");
+        let prompts = response["result"]["prompts"].as_array().unwrap();
+        assert!(prompts.iter().any(|p| p["name"] == "clarion-workflow"));
     }
 
     #[test]
@@ -2753,11 +5975,12 @@ mod tests {
             "id": "tools-1",
             "method": "tools/list",
             "params": {}
-        }));
+        }))
+        .expect("tools/list request returns a response");
 
         assert_eq!(response["jsonrpc"], "2.0");
         assert_eq!(response["id"], "tools-1");
-        assert_eq!(response["result"]["tools"].as_array().unwrap().len(), 8);
+        assert_eq!(response["result"]["tools"].as_array().unwrap().len(), 18);
         assert_eq!(response["result"]["tools"][0]["name"], "entity_at");
         assert_eq!(response["result"]["tools"][7]["name"], "subsystem_members");
     }
@@ -2769,11 +5992,23 @@ mod tests {
             "id": 7,
             "method": "not/real",
             "params": {}
-        }));
+        }))
+        .expect("unknown request returns a JSON-RPC error response");
 
         assert_eq!(response["error"]["code"], -32601);
     }
 
+    #[test]
+    fn json_rpc_notification_does_not_return_response() {
+        let response = super::handle_json_rpc(&serde_json::json!({
+            "jsonrpc": "2.0",
+            "method": "notifications/initialized",
+            "params": {}
+        }));
+
+        assert!(response.is_none());
+    }
+
     #[test]
     fn stateless_call_tool_requires_server_state_before_tool_validation() {
         let response = super::handle_json_rpc(&serde_json::json!({
@@ -2781,7 +6016,8 @@ mod tests {
             "id": 8,
             "method": "tools/call",
             "params": {"name": "not_a_tool", "arguments": {}}
-        }));
+        }))
+        .expect("tools/call request returns a response");
 
         assert_eq!(response["error"]["code"], -32601);
         assert_eq!(
@@ -2797,7 +6033,8 @@ mod tests {
             "id": 88,
             "method": "tools/call",
             "params": {"name": "summary", "arguments": {"id": "python:function:demo.entry"}}
-        }));
+        }))
+        .expect("tools/call request returns a response");
 
         assert_eq!(response["error"]["code"], -32601);
         assert!(
@@ -2815,7 +6052,8 @@ mod tests {
             "id": 9,
             "method": "tools/call",
             "params": {"arguments": {}}
-        }));
+        }))
+        .expect("tools/call request returns a response");
 
         assert_eq!(response["error"]["code"], -32601);
         assert_eq!(
@@ -2836,12 +6074,30 @@ mod tests {
             .unwrap(),
         };
 
-        let response = super::handle_frame(&frame).unwrap();
+        let response = super::handle_frame(&frame)
+            .unwrap()
+            .expect("request frame returns a response");
         let decoded: serde_json::Value = serde_json::from_slice(&response.body).unwrap();
 
         assert_eq!(decoded["jsonrpc"], "2.0");
         assert_eq!(decoded["id"], 10);
-        assert_eq!(decoded["result"]["tools"].as_array().unwrap().len(), 8);
+        assert_eq!(decoded["result"]["tools"].as_array().unwrap().len(), 18);
+    }
+
+    #[test]
+    fn frame_dispatch_returns_none_for_json_rpc_notifications() {
+        let frame = clarion_core::plugin::Frame {
+            body: serde_json::to_vec(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "notifications/initialized",
+                "params": {}
+            }))
+            .unwrap(),
+        };
+
+        let response = super::handle_frame(&frame).unwrap();
+
+        assert!(response.is_none());
     }
 
     #[test]
@@ -2900,7 +6156,184 @@ mod tests {
         assert_eq!(first_json["id"], 11);
         assert_eq!(first_json["result"]["serverInfo"]["name"], "clarion");
         assert_eq!(second_json["id"], 12);
-        assert_eq!(second_json["result"]["tools"].as_array().unwrap().len(), 8);
+        assert_eq!(second_json["result"]["tools"].as_array().unwrap().len(), 18);
+    }
+
+    #[test]
+    fn serve_stdio_ignores_json_rpc_notifications() {
+        let input = notification_sequence_input(13, 14);
+        let mut reader = std::io::BufReader::new(std::io::Cursor::new(input));
+        let mut output = Vec::new();
+
+        super::serve_stdio(&mut reader, &mut output).unwrap();
+        assert_notification_sequence_responses(output, 13, 14);
+    }
+
+    #[test]
+    fn serve_stdio_with_state_ignores_json_rpc_notifications() {
+        let project = tempfile::tempdir().expect("temp project");
+        let db_path = project.path().join("clarion.db");
+        let mut conn = Connection::open(&db_path).expect("open sqlite");
+        pragma::apply_write_pragmas(&conn).expect("write pragmas");
+        schema::apply_migrations(&mut conn).expect("apply migrations");
+        drop(conn);
+
+        let readers = ReaderPool::open(&db_path, 1).expect("reader pool");
+        let state = ServerState::new(project.path().to_path_buf(), readers);
+        let input = notification_sequence_input(15, 16);
+        let mut reader = std::io::BufReader::new(std::io::Cursor::new(input));
+        let mut output = Vec::new();
+
+        super::serve_stdio_with_state(&state, &mut reader, &mut output).unwrap();
+        assert_notification_sequence_responses(output, 15, 16);
+    }
+
+    #[test]
+    fn serve_stdio_with_state_uses_json_line_transport_for_json_line_requests() {
+        let project = tempfile::tempdir().expect("temp project");
+        let db_path = project.path().join("clarion.db");
+        let mut conn = Connection::open(&db_path).expect("open sqlite");
+        pragma::apply_write_pragmas(&conn).expect("write pragmas");
+        schema::apply_migrations(&mut conn).expect("apply migrations");
+        drop(conn);
+
+        let readers = ReaderPool::open(&db_path, 1).expect("reader pool");
+        let state = ServerState::new(project.path().to_path_buf(), readers);
+        let input = notification_sequence_json_lines(17, 18);
+        let mut reader = std::io::BufReader::new(std::io::Cursor::new(input));
+        let mut output = Vec::new();
+
+        super::serve_stdio_with_state(&state, &mut reader, &mut output).unwrap();
+        assert_notification_sequence_json_lines(output, 17, 18);
+    }
+
+    fn notification_sequence_input(initialize_id: u64, tools_list_id: u64) -> Vec<u8> {
+        let mut input = Vec::new();
+        clarion_core::plugin::write_frame(
+            &mut input,
+            &clarion_core::plugin::Frame {
+                body: serde_json::to_vec(&serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": initialize_id,
+                    "method": "initialize",
+                    "params": {
+                        "protocolVersion": "2025-11-25",
+                        "capabilities": {},
+                        "clientInfo": {"name": "test-client", "version": "0.0.0"}
+                    }
+                }))
+                .unwrap(),
+            },
+        )
+        .unwrap();
+        clarion_core::plugin::write_frame(
+            &mut input,
+            &clarion_core::plugin::Frame {
+                body: serde_json::to_vec(&serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "method": "notifications/initialized",
+                    "params": {}
+                }))
+                .unwrap(),
+            },
+        )
+        .unwrap();
+        clarion_core::plugin::write_frame(
+            &mut input,
+            &clarion_core::plugin::Frame {
+                body: serde_json::to_vec(&serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": tools_list_id,
+                    "method": "tools/list",
+                    "params": {}
+                }))
+                .unwrap(),
+            },
+        )
+        .unwrap();
+        input
+    }
+
+    fn assert_notification_sequence_responses(
+        output: Vec<u8>,
+        initialize_id: u64,
+        tools_list_id: u64,
+    ) {
+        let mut response_reader = std::io::BufReader::new(std::io::Cursor::new(output));
+        let first = clarion_core::plugin::read_frame(
+            &mut response_reader,
+            clarion_core::plugin::ContentLengthCeiling::new(usize::MAX),
+        )
+        .unwrap();
+        let second = clarion_core::plugin::read_frame(
+            &mut response_reader,
+            clarion_core::plugin::ContentLengthCeiling::new(usize::MAX),
+        )
+        .unwrap();
+        let first_json: serde_json::Value = serde_json::from_slice(&first.body).unwrap();
+        let second_json: serde_json::Value = serde_json::from_slice(&second.body).unwrap();
+
+        assert_eq!(first_json["id"], initialize_id);
+        assert_eq!(second_json["id"], tools_list_id);
+        assert!(
+            clarion_core::plugin::read_frame(
+                &mut response_reader,
+                clarion_core::plugin::ContentLengthCeiling::new(usize::MAX),
+            )
+            .is_err(),
+            "notifications must not produce JSON-RPC response frames"
+        );
+    }
+
+    fn notification_sequence_json_lines(initialize_id: u64, tools_list_id: u64) -> Vec<u8> {
+        let messages = [
+            serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": initialize_id,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2025-11-25",
+                    "capabilities": {},
+                    "clientInfo": {"name": "test-client", "version": "0.0.0"}
+                }
+            }),
+            serde_json::json!({
+                "jsonrpc": "2.0",
+                "method": "notifications/initialized",
+                "params": {}
+            }),
+            serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": tools_list_id,
+                "method": "tools/list",
+                "params": {}
+            }),
+        ];
+        let mut input = Vec::new();
+        for message in messages {
+            serde_json::to_writer(&mut input, &message).expect("serialize json line");
+            input.push(b'\n');
+        }
+        input
+    }
+
+    fn assert_notification_sequence_json_lines(
+        output: Vec<u8>,
+        initialize_id: u64,
+        tools_list_id: u64,
+    ) {
+        let output = String::from_utf8(output).expect("json lines are utf8");
+        let lines: Vec<_> = output.lines().collect();
+        assert_eq!(
+            lines.len(),
+            2,
+            "notifications must not produce JSON-RPC response lines"
+        );
+        let first_json: serde_json::Value = serde_json::from_str(lines[0]).unwrap();
+        let second_json: serde_json::Value = serde_json::from_str(lines[1]).unwrap();
+
+        assert_eq!(first_json["id"], initialize_id);
+        assert_eq!(second_json["id"], tools_list_id);
     }
 
     #[tokio::test]
@@ -3021,6 +6454,39 @@ mod tests {
         }
     }
 
+    #[test]
+    fn source_for_entity_blocks_briefing_blocked_file_without_leaking_bytes() {
+        // An entity whose source file the pre-ingest scanner marked
+        // briefing_blocked must never have its bytes returned by
+        // source_for_entity — that path would otherwise bypass the
+        // secret-redaction policy the scanner enforces.
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("secret.py");
+        std::fs::write(&path, "API_KEY = 'super-secret-value'\n").unwrap();
+        let mut entity = entity_row("python:function:demo.secret", "secret", None);
+        entity.source_file_path = Some(path.to_string_lossy().into_owned());
+        entity.source_line_start = Some(1);
+        entity.source_line_end = Some(1);
+        entity.properties_json =
+            r#"{"briefing_blocked":"secret detected by pre-ingest scanner"}"#.to_owned();
+
+        let out = super::source_for_entity_json(&entity, 10);
+
+        assert_eq!(out["source_status"], "briefing_blocked");
+        assert_eq!(
+            out["briefing_blocked"],
+            "secret detected by pre-ingest scanner"
+        );
+        assert!(
+            out.get("lines").is_none(),
+            "must not return source lines: {out}"
+        );
+        assert!(
+            !out.to_string().contains("super-secret-value"),
+            "leaked briefing-blocked bytes: {out}"
+        );
+    }
+
     struct BlockingProvider {
         release: Mutex<std::sync::mpsc::Receiver<()>>,
     }
@@ -3040,6 +6506,7 @@ mod tests {
                 model_id: "test-model".to_owned(),
                 output_json: r#"{"edges":[]}"#.to_owned(),
                 input_tokens: 1,
+                cached_input_tokens: 0,
                 output_tokens: 1,
                 total_tokens: 2,
                 cost_usd: 0.0,
diff --git a/crates/clarion-mcp/src/scan_results.rs b/crates/clarion-mcp/src/scan_results.rs
new file mode 100644
index 00000000..e09464d6
--- /dev/null
+++ b/crates/clarion-mcp/src/scan_results.rs
@@ -0,0 +1,533 @@
+//! Filigree-native scan-results emission (WP9-B, REQ-FINDING-03).
+//!
+//! Maps Clarion's persisted findings onto Filigree's `POST /api/v1/scan-results`
+//! intake schema (ADR-004 + detailed-design §7) and models the response. This
+//! module is pure — request building and response parsing only; the HTTP POST
+//! lives on [`crate::filigree::FiligreeHttpClient::post_scan_results`].
+//!
+//! Emission is enrich-only: a one-way Clarion→Filigree push that adds no
+//! Filigree-side routes and never gates Clarion's own semantics. Clarion's
+//! richer fields nest under `metadata.clarion.*` so Filigree's silent
+//! top-level-key drop (verified against the live intake) cannot lose them.
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value, json};
+
+use clarion_storage::FindingForEmitRow;
+
+/// The `scan_source` Clarion stamps on every emitted finding. Filigree's dedup
+/// key includes `scan_source`, so this is stable across runs.
+pub const CLARION_SCAN_SOURCE: &str = "clarion";
+
+/// Map Clarion's internal severity vocabulary (`INFO` | `WARN` | `ERROR` |
+/// `CRITICAL` | `NONE`) to Filigree's wire vocabulary (detailed-design §7
+/// table). Anything unrecognised — including `NONE` (facts) and `INFO` — maps
+/// to `info`, mirroring the coercion Filigree applies server-side, except done
+/// here so the original survives in `metadata.clarion.internal_severity`.
+///
+/// This mapping is load-bearing: a live probe confirmed Filigree coerces an
+/// unmapped uppercase `WARN` to `info` (with a response warning), so emitting
+/// the internal vocabulary verbatim would silently flatten every defect to
+/// `info`.
+#[must_use]
+pub fn severity_to_wire(internal: &str) -> &'static str {
+    match internal {
+        "CRITICAL" => "critical",
+        "ERROR" => "high",
+        "WARN" => "medium",
+        _ => "info",
+    }
+}
+
+/// Knobs the emitter sets per `clarion analyze` invocation. `create_observations`
+/// is always `false` (Clarion emits findings, not observations).
+#[derive(Debug, Clone)]
+pub struct EmitOptions {
+    /// Filigree's `scan_run_id`; Clarion passes its `run_id` here. An unknown
+    /// id is tolerated by Filigree (it warns and proceeds), so this carries the
+    /// REQ-FINDING-05 wire shape without a pre-create handshake.
+    pub scan_run_id: Option<String>,
+    /// `mark_unseen`: `true` for a normal full run so old-position findings for
+    /// the same rule/file transition to `unseen_in_latest` (REQ-FINDING-06).
+    pub mark_unseen: bool,
+    /// `complete_scan_run`: `true` on the final (here: only) batch.
+    pub complete_scan_run: bool,
+}
+
+/// The Filigree-native scan-results request body. Serializes to the exact wire
+/// shape Filigree's intake accepts; any field outside its enumerated set is
+/// silently dropped server-side, so the struct carries only known keys.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct ScanResultsRequest {
+    pub scan_source: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub scan_run_id: Option<String>,
+    pub mark_unseen: bool,
+    pub create_observations: bool,
+    pub complete_scan_run: bool,
+    pub findings: Vec<Value>,
+}
+
+/// A prepared batch plus the counts the emitter records in `stats.json`.
+#[derive(Debug, Clone)]
+pub struct PreparedBatch {
+    pub request: ScanResultsRequest,
+    /// Findings rendered into the request body.
+    pub emitted: usize,
+    /// Findings dropped because their anchor entity has no `source_file_path`
+    /// (Filigree requires `path`; emitting a synthetic one would pollute its
+    /// file registry). Surfaced so the skip is never silent.
+    pub skipped_no_path: usize,
+}
+
+/// Build a scan-results batch from persisted findings. Findings whose anchor
+/// entity has no source path are skipped and counted, not emitted.
+#[must_use]
+pub fn prepare_batch(rows: &[FindingForEmitRow], opts: &EmitOptions) -> PreparedBatch {
+    let mut findings = Vec::with_capacity(rows.len());
+    let mut skipped_no_path = 0;
+    for row in rows {
+        match wire_finding(row) {
+            Some(finding) => findings.push(finding),
+            None => skipped_no_path += 1,
+        }
+    }
+    let emitted = findings.len();
+    PreparedBatch {
+        request: ScanResultsRequest {
+            scan_source: CLARION_SCAN_SOURCE.to_owned(),
+            scan_run_id: opts.scan_run_id.clone(),
+            mark_unseen: opts.mark_unseen,
+            create_observations: false,
+            complete_scan_run: opts.complete_scan_run,
+            findings,
+        },
+        emitted,
+        skipped_no_path,
+    }
+}
+
+/// Render one persisted finding as a Filigree-native wire finding, or `None`
+/// when it has no usable `path` (Filigree rejects path-less findings with a
+/// `400 VALIDATION`).
+fn wire_finding(row: &FindingForEmitRow) -> Option<Value> {
+    let path = row
+        .source_file_path
+        .as_deref()
+        .map(str::trim)
+        .filter(|path| !path.is_empty())?;
+    let mut finding = Map::new();
+    finding.insert("path".to_owned(), json!(path));
+    finding.insert("rule_id".to_owned(), json!(row.rule_id));
+    finding.insert("message".to_owned(), json!(row.message));
+    finding.insert(
+        "severity".to_owned(),
+        json!(severity_to_wire(&row.severity)),
+    );
+    if let Some(line_start) = row.source_line_start {
+        finding.insert("line_start".to_owned(), json!(line_start));
+    }
+    if let Some(line_end) = row.source_line_end {
+        finding.insert("line_end".to_owned(), json!(line_end));
+    }
+    finding.insert("metadata".to_owned(), wire_metadata(row));
+    Some(Value::Object(finding))
+}
+
+/// Nest Clarion's richer fields under `metadata` (top level) and
+/// `metadata.clarion` (Clarion-owned slot), per ADR-004 + detailed-design §7.
+fn wire_metadata(row: &FindingForEmitRow) -> Value {
+    let mut meta = Map::new();
+    meta.insert("kind".to_owned(), json!(row.kind));
+    if let Some(confidence) = row.confidence {
+        meta.insert("confidence".to_owned(), json!(confidence));
+    }
+    if let Some(basis) = &row.confidence_basis {
+        meta.insert("confidence_basis".to_owned(), json!(basis));
+    }
+
+    let mut clarion = Map::new();
+    clarion.insert("entity_id".to_owned(), json!(row.entity_id));
+    clarion.insert(
+        "related_entities".to_owned(),
+        json_array_or_empty(&row.related_entities_json),
+    );
+    clarion.insert(
+        "supports".to_owned(),
+        json_array_or_empty(&row.supports_json),
+    );
+    clarion.insert(
+        "supported_by".to_owned(),
+        json_array_or_empty(&row.supported_by_json),
+    );
+    // Lossless round-trip: the wire `severity` is the mapped value, so the
+    // internal vocabulary is preserved here for read-back.
+    clarion.insert("internal_severity".to_owned(), json!(row.severity));
+    clarion.insert("internal_status".to_owned(), json!("open"));
+    meta.insert("clarion".to_owned(), Value::Object(clarion));
+    Value::Object(meta)
+}
+
+/// Parse a stored JSON-array column; fall back to an empty array if the text is
+/// malformed or not an array, so one bad row never derails a batch.
+fn json_array_or_empty(raw: &str) -> Value {
+    match serde_json::from_str::<Value>(raw) {
+        Ok(value @ Value::Array(_)) => value,
+        _ => Value::Array(Vec::new()),
+    }
+}
+
+/// Filigree's scan-results response. `#[serde(default)]` keeps the read
+/// forward-compatible: Filigree may add fields without breaking Clarion.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
+#[serde(default)]
+pub struct ScanResultsResponse {
+    pub files_created: u64,
+    pub files_updated: u64,
+    pub findings_created: u64,
+    pub findings_updated: u64,
+    pub observations_created: u64,
+    pub observations_failed: u64,
+    pub new_finding_ids: Vec<String>,
+    /// Per-finding intake warnings (e.g. coerced severity, unknown
+    /// `scan_run_id`). REQ-FINDING-03 requires the emitter to parse these, not
+    /// just count them.
+    pub warnings: Vec<String>,
+}
+
+/// Parse a scan-results response body.
+///
+/// # Errors
+///
+/// Returns the underlying [`serde_json::Error`] if the body is not the expected
+/// JSON object shape.
+pub fn parse_scan_results_response(body: &str) -> Result<ScanResultsResponse, serde_json::Error> {
+    serde_json::from_str(body)
+}
+
+/// The scan-results intake URL for a Filigree base URL.
+#[must_use]
+pub fn scan_results_url(base_url: &str) -> String {
+    format!("{}/api/v1/scan-results", base_url.trim_end_matches('/'))
+}
+
+/// The retention-sweep URL for a Filigree base URL (REQ-FINDING-06,
+/// `--prune-unseen`). This is a **loom-generation** route (`/api/loom/…`),
+/// unlike the classic `/api/v1/scan-results` emission intake — do not derive it
+/// from [`scan_results_url`]. Verified against Filigree's own route handler and
+/// API tests.
+#[must_use]
+pub fn clean_stale_url(base_url: &str) -> String {
+    format!(
+        "{}/api/loom/findings/clean-stale",
+        base_url.trim_end_matches('/')
+    )
+}
+
+/// The `POST /api/loom/findings/clean-stale` request body (REQ-FINDING-06).
+/// Filigree **soft-archives** `unseen_in_latest` findings older than
+/// `older_than_days`, scoped to `scan_source`, moving them to `fixed` status
+/// (they auto-reopen if a later scan re-detects them — see Filigree ADR-015).
+/// `scan_source` is required server-side as an accident-guard so a caller
+/// cannot sweep every tool's findings; Clarion always sends `"clarion"`.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct CleanStaleRequest {
+    pub scan_source: String,
+    pub older_than_days: u32,
+    pub actor: String,
+}
+
+/// Filigree's clean-stale response. `#[serde(default)]` keeps the read tolerant
+/// of added fields / missing keys so Filigree can grow the route.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
+#[serde(default)]
+pub struct CleanStaleResponse {
+    pub findings_fixed: u64,
+    pub scan_source: String,
+    pub older_than_days: u64,
+}
+
+/// Parse Filigree's clean-stale response body.
+///
+/// # Errors
+///
+/// Returns the underlying [`serde_json::Error`] if the body is not the expected
+/// shape.
+pub fn parse_clean_stale_response(body: &str) -> Result<CleanStaleResponse, serde_json::Error> {
+    serde_json::from_str(body)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn defect_row() -> FindingForEmitRow {
+        FindingForEmitRow {
+            id: "core:finding:run-1:circular".to_owned(),
+            rule_id: "CLA-PY-STRUCTURE-001".to_owned(),
+            kind: "defect".to_owned(),
+            severity: "WARN".to_owned(),
+            confidence: Some(0.95),
+            confidence_basis: Some("ast_match".to_owned()),
+            message: "Circular import detected".to_owned(),
+            entity_id: "python:class:auth.tokens::TokenManager".to_owned(),
+            related_entities_json: r#"["python:class:auth.sessions::SessionStore"]"#.to_owned(),
+            supports_json: "[]".to_owned(),
+            supported_by_json: "[]".to_owned(),
+            source_file_path: Some("src/auth/tokens.py".to_owned()),
+            source_line_start: Some(12),
+            source_line_end: Some(12),
+        }
+    }
+
+    #[test]
+    fn severity_table_matches_detailed_design() {
+        assert_eq!(severity_to_wire("CRITICAL"), "critical");
+        assert_eq!(severity_to_wire("ERROR"), "high");
+        assert_eq!(severity_to_wire("WARN"), "medium");
+        assert_eq!(severity_to_wire("INFO"), "info");
+        assert_eq!(severity_to_wire("NONE"), "info");
+        // Unknown values coerce to info, the same as Filigree's server-side rule.
+        assert_eq!(severity_to_wire("bogus"), "info");
+    }
+
+    #[test]
+    fn wire_finding_carries_mapped_severity_and_nested_clarion_metadata() {
+        let finding = wire_finding(&defect_row()).expect("path present");
+
+        assert_eq!(finding["path"], json!("src/auth/tokens.py"));
+        assert_eq!(finding["rule_id"], json!("CLA-PY-STRUCTURE-001"));
+        assert_eq!(finding["message"], json!("Circular import detected"));
+        // Internal WARN maps to wire medium...
+        assert_eq!(finding["severity"], json!("medium"));
+        assert_eq!(finding["line_start"], json!(12));
+        assert_eq!(finding["line_end"], json!(12));
+
+        let meta = &finding["metadata"];
+        assert_eq!(meta["kind"], json!("defect"));
+        assert_eq!(meta["confidence"], json!(0.95));
+        assert_eq!(meta["confidence_basis"], json!("ast_match"));
+
+        let clarion = &meta["clarion"];
+        assert_eq!(
+            clarion["entity_id"],
+            json!("python:class:auth.tokens::TokenManager")
+        );
+        assert_eq!(
+            clarion["related_entities"],
+            json!(["python:class:auth.sessions::SessionStore"])
+        );
+        assert_eq!(clarion["supports"], json!([]));
+        assert_eq!(clarion["supported_by"], json!([]));
+        // ...while the internal value round-trips under clarion.*.
+        assert_eq!(clarion["internal_severity"], json!("WARN"));
+        assert_eq!(clarion["internal_status"], json!("open"));
+    }
+
+    #[test]
+    fn fact_finding_omits_confidence_basis_when_absent() {
+        let mut row = defect_row();
+        row.kind = "fact".to_owned();
+        row.severity = "NONE".to_owned();
+        row.confidence = None;
+        row.confidence_basis = None;
+
+        let finding = wire_finding(&row).expect("path present");
+        assert_eq!(finding["severity"], json!("info"));
+        let meta = &finding["metadata"];
+        assert_eq!(meta["kind"], json!("fact"));
+        assert!(
+            meta.get("confidence").is_none(),
+            "confidence omitted: {meta}"
+        );
+        assert!(
+            meta.get("confidence_basis").is_none(),
+            "confidence_basis omitted: {meta}"
+        );
+        assert_eq!(meta["clarion"]["internal_severity"], json!("NONE"));
+    }
+
+    #[test]
+    fn path_less_finding_is_skipped_not_emitted() {
+        let mut row = defect_row();
+        row.source_file_path = None;
+        assert!(wire_finding(&row).is_none());
+
+        let mut blank = defect_row();
+        blank.source_file_path = Some("   ".to_owned());
+        assert!(wire_finding(&blank).is_none(), "blank path is skipped too");
+    }
+
+    #[test]
+    fn malformed_related_entities_falls_back_to_empty_array() {
+        let mut row = defect_row();
+        row.related_entities_json = "not json".to_owned();
+        let finding = wire_finding(&row).expect("path present");
+        assert_eq!(
+            finding["metadata"]["clarion"]["related_entities"],
+            json!([])
+        );
+    }
+
+    #[test]
+    fn prepare_batch_counts_emitted_and_skipped() {
+        let emitted = defect_row();
+        let mut skipped = defect_row();
+        skipped.id = "core:finding:run-1:weak-modularity".to_owned();
+        skipped.entity_id = "core:subsystem:abcd".to_owned();
+        skipped.source_file_path = None;
+
+        let batch = prepare_batch(
+            &[emitted, skipped],
+            &EmitOptions {
+                scan_run_id: Some("run-1".to_owned()),
+                mark_unseen: true,
+                complete_scan_run: true,
+            },
+        );
+
+        assert_eq!(batch.emitted, 1);
+        assert_eq!(batch.skipped_no_path, 1);
+        assert_eq!(batch.request.findings.len(), 1);
+        assert_eq!(batch.request.scan_source, "clarion");
+        assert_eq!(batch.request.scan_run_id.as_deref(), Some("run-1"));
+        assert!(batch.request.mark_unseen);
+        assert!(batch.request.complete_scan_run);
+        assert!(!batch.request.create_observations);
+    }
+
+    #[test]
+    fn request_serializes_to_filigree_wire_shape() {
+        let batch = prepare_batch(
+            &[defect_row()],
+            &EmitOptions {
+                scan_run_id: Some("run-1".to_owned()),
+                mark_unseen: true,
+                complete_scan_run: true,
+            },
+        );
+        let value = serde_json::to_value(&batch.request).expect("serialize request");
+
+        assert_eq!(value["scan_source"], json!("clarion"));
+        assert_eq!(value["scan_run_id"], json!("run-1"));
+        assert_eq!(value["mark_unseen"], json!(true));
+        assert_eq!(value["create_observations"], json!(false));
+        assert_eq!(value["complete_scan_run"], json!(true));
+        assert_eq!(
+            value["findings"].as_array().expect("findings array").len(),
+            1
+        );
+    }
+
+    #[test]
+    fn omitted_scan_run_id_is_absent_from_wire() {
+        let batch = prepare_batch(
+            &[defect_row()],
+            &EmitOptions {
+                scan_run_id: None,
+                mark_unseen: true,
+                complete_scan_run: true,
+            },
+        );
+        let value = serde_json::to_value(&batch.request).expect("serialize request");
+        assert!(
+            value.get("scan_run_id").is_none(),
+            "scan_run_id omitted when None: {value}"
+        );
+    }
+
+    #[test]
+    fn parses_live_response_shape() {
+        // Pinned to the real Filigree response captured from a live probe POST.
+        let response = parse_scan_results_response(
+            r#"{
+                "files_created": 1,
+                "files_updated": 0,
+                "findings_created": 1,
+                "findings_updated": 0,
+                "new_finding_ids": ["clarion-sf-2f4cf9ca1b"],
+                "observations_created": 0,
+                "observations_failed": 0,
+                "warnings": ["Unknown severity 'WARN' for finding at probe/sev.py, mapped to 'info'"]
+            }"#,
+        )
+        .expect("parse live response shape");
+
+        assert_eq!(response.findings_created, 1);
+        assert_eq!(response.files_created, 1);
+        assert_eq!(response.new_finding_ids, vec!["clarion-sf-2f4cf9ca1b"]);
+        assert_eq!(response.warnings.len(), 1);
+        assert!(response.warnings[0].contains("Unknown severity"));
+    }
+
+    #[test]
+    fn response_parse_tolerates_missing_and_extra_fields() {
+        // Forward-compat: unknown fields ignored, missing fields default.
+        let response = parse_scan_results_response(
+            r#"{"findings_created": 2, "warnings": [], "some_future_field": 99}"#,
+        )
+        .expect("parse forward-compatible response");
+        assert_eq!(response.findings_created, 2);
+        assert!(response.warnings.is_empty());
+        assert!(response.new_finding_ids.is_empty());
+    }
+
+    #[test]
+    fn builds_scan_results_url() {
+        assert_eq!(
+            scan_results_url("http://127.0.0.1:8542/"),
+            "http://127.0.0.1:8542/api/v1/scan-results"
+        );
+        assert_eq!(
+            scan_results_url("http://127.0.0.1:8542"),
+            "http://127.0.0.1:8542/api/v1/scan-results"
+        );
+    }
+
+    #[test]
+    fn clean_stale_url_targets_the_loom_route() {
+        // Prune is a loom-generation route, distinct from the classic
+        // /api/v1 emission intake.
+        assert_eq!(
+            clean_stale_url("http://127.0.0.1:8542/"),
+            "http://127.0.0.1:8542/api/loom/findings/clean-stale"
+        );
+        assert_eq!(
+            clean_stale_url("http://127.0.0.1:8542"),
+            "http://127.0.0.1:8542/api/loom/findings/clean-stale"
+        );
+    }
+
+    #[test]
+    fn clean_stale_request_serializes_to_filigree_wire_shape() {
+        let request = CleanStaleRequest {
+            scan_source: CLARION_SCAN_SOURCE.to_owned(),
+            older_than_days: 30,
+            actor: "clarion-mcp".to_owned(),
+        };
+        let value = serde_json::to_value(&request).expect("serialize clean-stale request");
+        assert_eq!(value["scan_source"], json!("clarion"));
+        assert_eq!(value["older_than_days"], json!(30));
+        assert_eq!(value["actor"], json!("clarion-mcp"));
+    }
+
+    #[test]
+    fn parses_clean_stale_response_shape() {
+        // Pinned to Filigree's clean-stale handler response.
+        let response = parse_clean_stale_response(
+            r#"{"findings_fixed": 4, "scan_source": "clarion", "older_than_days": 30}"#,
+        )
+        .expect("parse clean-stale response");
+        assert_eq!(response.findings_fixed, 4);
+        assert_eq!(response.scan_source, "clarion");
+        assert_eq!(response.older_than_days, 30);
+    }
+
+    #[test]
+    fn clean_stale_response_tolerates_missing_and_extra_fields() {
+        let response = parse_clean_stale_response(r#"{"findings_fixed": 1, "future_field": true}"#)
+            .expect("parse forward-compatible clean-stale response");
+        assert_eq!(response.findings_fixed, 1);
+        assert_eq!(response.older_than_days, 0);
+    }
+}
diff --git a/crates/clarion-mcp/src/snapshot.rs b/crates/clarion-mcp/src/snapshot.rs
new file mode 100644
index 00000000..9e2de8d2
--- /dev/null
+++ b/crates/clarion-mcp/src/snapshot.rs
@@ -0,0 +1,858 @@
+//! Shared project snapshot: entity/subsystem/finding counts + index staleness.
+//!
+//! One function, two callers: the `clarion hook session-start` subcommand and
+//! the MCP `clarion://context` resource. Infallible by design — every failure
+//! folds into the snapshot (zero counts, `Staleness::Unknown`) so the fail-soft
+//! hook never has to handle an error. Degrade, but don't go quiet: a real query
+//! failure is `tracing::warn!`-logged before it folds, so a populated index
+//! reporting 0 leaves a trace (run with `RUST_LOG=warn`).
+
+use std::collections::BTreeSet;
+use std::io::ErrorKind;
+use std::path::{Path, PathBuf};
+use std::time::SystemTime;
+
+use rusqlite::Connection;
+use serde::Serialize;
+
+/// Freshness of the `.clarion/` index relative to the source files Clarion
+/// ingested. See the plan's Decision Point (b) for the algorithm.
+///
+/// Freshness combines two passes over the files recorded in
+/// `entities.source_file_path` (clarion-e687941a8c):
+///
+/// 1. **Structural drift** — added / removed / renamed source files. Adding or
+///    removing a directory entry bumps the *parent directory's* mtime, so a
+///    watched source directory whose mtime is newer than the latest run means
+///    its file set changed since analyze, even when no ingested file's own
+///    mtime did. This is a conservative nudge: unrelated churn in a source
+///    directory (Python's `__pycache__`, an editor's swap/backup file, a
+///    `.DS_Store`) also bumps its mtime and can therefore report [`Stale`]
+///    when no tracked source actually changed. The watch set is the *direct
+///    parents* of ingested files, so an addition/removal in any directory that
+///    is not such a parent goes undetected — always including the project root
+///    itself, which is deliberately never watched (`analyze` writes `.clarion/`
+///    under it, which would otherwise wedge every check to a permanent Stale).
+/// 2. **In-place modification** — an ingested file edited since the run. This
+///    needs one `stat` per file and is bounded by `MAX_MODIFICATION_STAT_FILES`
+///    so `clarion hook session-start` stays cheap on large repos
+///    (clarion-93465ff89e); the structural pass runs first and short-circuits
+///    the common "repo changed" case before any file is stat-ed.
+///
+/// The verdict is a best-effort nudge, not a guarantee.
+///
+/// [`Fresh`]: Staleness::Fresh
+/// [`Stale`]: Staleness::Stale
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Staleness {
+    /// No completed analyze run has ever been recorded.
+    NeverAnalyzed,
+    /// The index is out of date: a watched source directory's mtime is newer
+    /// than the latest run (a file was added / removed / renamed), an ingested
+    /// file was modified or deleted since the run, or both. See the type-level
+    /// note for the conservative-nudge caveat.
+    Stale,
+    /// No structural drift in a watched directory and no ingested file newer
+    /// than (or missing since) the latest run. Subject to the bounded
+    /// modification scan and the unwatched-project-root caveat in the
+    /// type-level note.
+    Fresh,
+    /// A completed run exists, but no ingested entity has a resolvable
+    /// `source_file_path` to stat — there is *nothing to compare against*, so
+    /// freshness is neither Fresh nor Stale. A normal outcome (e.g. a project
+    /// whose only entities are subsystems), distinct from [`Unknown`]: no query
+    /// or stat failed, so it never sets `degraded`.
+    ///
+    /// [`Unknown`]: Staleness::Unknown
+    NoSourcePaths,
+    /// Could not determine because a query/parse/stat *failed* — degrade, don't
+    /// fail (and log). Strictly the error fold: "nothing to compare" is
+    /// [`NoSourcePaths`], not `Unknown`.
+    ///
+    /// [`NoSourcePaths`]: Staleness::NoSourcePaths
+    Unknown,
+}
+
+/// Counts + freshness for one Clarion project, safe to serialize into the MCP
+/// resource or print from the hook.
+///
+/// Fields are private and read through accessors so the documented invariant —
+/// `db_present == false` implies zero counts and [`Staleness::NeverAnalyzed`] —
+/// cannot be violated: the only ways to build one are the three constructors in
+/// this module ([`project_snapshot`], [`missing_db_snapshot`],
+/// [`unreadable_db_snapshot`]), each of which upholds it. No external caller can
+/// assemble a `db_present: false` snapshot carrying non-zero counts
+/// (clarion-e0a4937d89). Serialization is unaffected — serde uses the field
+/// names regardless of visibility, so the wire shape is identical.
+#[derive(Debug, Clone, Serialize)]
+pub struct ProjectSnapshot {
+    db_present: bool,
+    entity_count: i64,
+    subsystem_count: i64,
+    finding_count: i64,
+    staleness: Staleness,
+    /// Latest run `completed_at` (ISO-8601) if any, else `None`.
+    last_analyzed_at: Option<String>,
+    /// `true` when this snapshot was produced from a *failure* rather than a
+    /// healthy read: at least one backing SQL query failed unexpectedly and was
+    /// folded to a safe default (a count to `0`, the run lookup to `None`, or
+    /// the staleness scan to [`Staleness::Unknown`]), or the snapshot was built
+    /// by a caller's reader-pool fallback. Lets an MCP consumer distinguish
+    /// "machinery broke" from a genuinely empty-but-present index, which
+    /// otherwise serialize byte-identically (`db_present: true`, all counts `0`,
+    /// `staleness: unknown`). Environmental staleness (a missing/unstat-able
+    /// source file folding to `Unknown`) is *not* degradation — that is a normal
+    /// outcome signalled by `staleness` itself, not a DB-machinery failure.
+    degraded: bool,
+    /// `true` when the in-place modification scan stopped at
+    /// [`MAX_MODIFICATION_STAT_FILES`] without finding drift: the index has more
+    /// ingested files than the per-check `stat` cap, so a [`Staleness::Fresh`]
+    /// verdict on this snapshot is only proven for the files that were scanned —
+    /// an edit beyond the cap may go unnoticed until the next analyze. A
+    /// consumer on a very large repo can read this to know a `Fresh` result is
+    /// bounded rather than exhaustive (clarion-e687941a8c). Always `false` for a
+    /// `Stale`/`Unknown`/`NeverAnalyzed`/`NoSourcePaths` verdict.
+    ///
+    /// [`Fresh`]: Staleness::Fresh
+    scan_truncated: bool,
+}
+
+impl ProjectSnapshot {
+    /// Whether a readable `.clarion/clarion.db` was found. When `false`, every
+    /// count is `0` and `staleness` is [`Staleness::NeverAnalyzed`].
+    #[must_use]
+    pub fn db_present(&self) -> bool {
+        self.db_present
+    }
+
+    /// Total entity rows (subsystems included — see [`subsystem_count`]).
+    ///
+    /// [`subsystem_count`]: ProjectSnapshot::subsystem_count
+    #[must_use]
+    pub fn entity_count(&self) -> i64 {
+        self.entity_count
+    }
+
+    /// Entities of kind `subsystem` — a *subset* of [`entity_count`], not a
+    /// disjoint category.
+    ///
+    /// [`entity_count`]: ProjectSnapshot::entity_count
+    #[must_use]
+    pub fn subsystem_count(&self) -> i64 {
+        self.subsystem_count
+    }
+
+    /// Total finding rows.
+    #[must_use]
+    pub fn finding_count(&self) -> i64 {
+        self.finding_count
+    }
+
+    /// Index freshness verdict.
+    #[must_use]
+    pub fn staleness(&self) -> Staleness {
+        self.staleness
+    }
+
+    /// Latest run `completed_at` (ISO-8601) if any.
+    #[must_use]
+    pub fn last_analyzed_at(&self) -> Option<&str> {
+        self.last_analyzed_at.as_deref()
+    }
+
+    /// `true` when this snapshot was folded from a backing-query failure — see
+    /// the field-level note for the precise contract.
+    #[must_use]
+    pub fn degraded(&self) -> bool {
+        self.degraded
+    }
+
+    /// `true` when a [`Staleness::Fresh`] verdict rests on a modification scan
+    /// that hit the per-check `stat` cap — see the field-level note.
+    ///
+    /// [`Fresh`]: Staleness::Fresh
+    #[must_use]
+    pub fn scan_truncated(&self) -> bool {
+        self.scan_truncated
+    }
+}
+
+/// Build a snapshot from an already-open migrated `Connection`.
+///
+/// `db_present` is always `true` here (the caller opened the connection); the
+/// `false` case is produced by the caller when the db file is missing.
+#[must_use]
+pub fn project_snapshot(conn: &Connection, project_root: &Path) -> ProjectSnapshot {
+    // Accumulates any SQL-machinery failure folded below into a wire-visible
+    // `degraded` flag, so the consumer can tell a broken read from an empty one.
+    let mut degraded = false;
+
+    let entity_count = scalar_count(conn, "SELECT COUNT(*) FROM entities", &mut degraded);
+    let subsystem_count = scalar_count(
+        conn,
+        "SELECT COUNT(*) FROM entities WHERE kind = 'subsystem'",
+        &mut degraded,
+    );
+    let finding_count = scalar_count(conn, "SELECT COUNT(*) FROM findings", &mut degraded);
+
+    let last_analyzed_at = latest_completed_run(conn, &mut degraded);
+    let mut scan_truncated = false;
+    let staleness = compute_staleness(
+        conn,
+        project_root,
+        last_analyzed_at.as_deref(),
+        &mut degraded,
+        &mut scan_truncated,
+    );
+
+    ProjectSnapshot {
+        db_present: true,
+        entity_count,
+        subsystem_count,
+        finding_count,
+        staleness,
+        last_analyzed_at,
+        degraded,
+        scan_truncated,
+    }
+}
+
+/// A missing-database snapshot: all zeros, `NeverAnalyzed`, no timestamp.
+#[must_use]
+pub fn missing_db_snapshot() -> ProjectSnapshot {
+    ProjectSnapshot {
+        db_present: false,
+        entity_count: 0,
+        subsystem_count: 0,
+        finding_count: 0,
+        staleness: Staleness::NeverAnalyzed,
+        last_analyzed_at: None,
+        degraded: false,
+        scan_truncated: false,
+    }
+}
+
+/// A degraded snapshot for a database that *is* present but could not be read
+/// or serialized (the MCP `clarion://context` reader-pool / serialize-error
+/// fallback): `db_present: true`, all counts `0`, [`Staleness::Unknown`], no
+/// timestamp, and `degraded: true` so a consumer never mistakes the zero counts
+/// for a genuinely empty index. The single construction site for this case,
+/// replacing the inline struct literal that the private fields now forbid
+/// (clarion-e0a4937d89).
+#[must_use]
+pub fn unreadable_db_snapshot() -> ProjectSnapshot {
+    ProjectSnapshot {
+        db_present: true,
+        entity_count: 0,
+        subsystem_count: 0,
+        finding_count: 0,
+        staleness: Staleness::Unknown,
+        last_analyzed_at: None,
+        degraded: true,
+        scan_truncated: false,
+    }
+}
+
+/// Run a scalar `COUNT(*)` query. On failure, log, fold to `0`, and set
+/// `*degraded` so the caller can mark the whole snapshot as a degraded read.
+fn scalar_count(conn: &Connection, sql: &str, degraded: &mut bool) -> i64 {
+    match conn.query_row(sql, [], |row| row.get::<_, i64>(0)) {
+        Ok(n) => n,
+        Err(err) => {
+            tracing::warn!(error = %err, sql, "clarion snapshot count query failed; reporting 0");
+            *degraded = true;
+            0
+        }
+    }
+}
+
+/// Look up the latest completed run's `completed_at`. `QueryReturnedNoRows` is a
+/// normal "never analyzed" outcome and does *not* degrade; any other error is a
+/// machinery failure that folds to `None` and sets `*degraded`.
+fn latest_completed_run(conn: &Connection, degraded: &mut bool) -> Option<String> {
+    match conn.query_row(
+        "SELECT completed_at FROM runs \
+         WHERE completed_at IS NOT NULL AND status = 'completed' \
+         ORDER BY completed_at DESC LIMIT 1",
+        [],
+        |row| row.get::<_, String>(0),
+    ) {
+        Ok(s) => Some(s),
+        Err(rusqlite::Error::QueryReturnedNoRows) => None,
+        Err(err) => {
+            tracing::warn!(error = %err, "clarion latest-completed-run query failed");
+            *degraded = true;
+            None
+        }
+    }
+}
+
+/// Upper bound on per-file `stat` syscalls in one staleness check — a backstop
+/// against pathological repositories. In-place modification detection
+/// inherently needs one `stat` per ingested file, and `clarion hook
+/// session-start` runs at the top of every agent session, so an unbounded scan
+/// is O(files) syscalls per session start (clarion-93465ff89e). Structural
+/// drift (added / removed / renamed files) is detected first and *exhaustively*
+/// from directory mtimes — O(dirs) ≪ O(files) — which also short-circuits the
+/// common "repo changed since analyze" case before any file is stat-ed. Only a
+/// genuinely-fresh repo falls through to the bounded per-file scan; if it
+/// exceeds this cap the overflow is logged and pure in-place edits to files
+/// past the cap may report [`Staleness::Fresh`] until the next analyze. Sized
+/// well above realistic targets (the elspeth corpus, ~425k LOC, is a few
+/// thousand files) so no real project is sampled — the cap only bites a
+/// pathological monorepo.
+const MAX_MODIFICATION_STAT_FILES: usize = 20_000;
+
+fn compute_staleness(
+    conn: &Connection,
+    project_root: &Path,
+    last_analyzed_at: Option<&str>,
+    degraded: &mut bool,
+    scan_truncated: &mut bool,
+) -> Staleness {
+    let Some(run_iso) = last_analyzed_at else {
+        return Staleness::NeverAnalyzed;
+    };
+    let Some(run_time) = parse_iso8601_to_systemtime(run_iso) else {
+        // A run timestamp we can't parse is a data/machinery fault, not an
+        // environmental one — mark degraded alongside the Unknown verdict.
+        *degraded = true;
+        return Staleness::Unknown;
+    };
+
+    let Some((files, dirs)) = ingested_files_and_dirs(conn, project_root, degraded) else {
+        // A query/prepare failure already set `degraded` and folds to Unknown.
+        return Staleness::Unknown;
+    };
+
+    // (1) Structural drift: any watched source directory newer than the run
+    // means a file was added / removed / renamed in it. Exhaustive over dirs
+    // and far cheaper than the per-file scan, so it runs first.
+    if directory_structural_drift(&dirs, run_time) {
+        return Staleness::Stale;
+    }
+
+    // (2) In-place modification: one stat per ingested file, bounded.
+    match file_modification_drift(&files, run_time, scan_truncated) {
+        Some(staleness) => staleness,
+        None => {
+            if files.is_empty() {
+                // A completed run with no resolvable source file to stat:
+                // nothing to compare, NOT an error. Kept distinct from the
+                // error folds so `Unknown` means strictly "a query/parse/stat
+                // failed" (clarion-22add08e98).
+                Staleness::NoSourcePaths
+            } else {
+                Staleness::Fresh
+            }
+        }
+    }
+}
+
+/// Resolve every distinct ingested `source_file_path` to an absolute path, and
+/// collect the distinct parent directories to watch for structural drift. The
+/// project root itself is deliberately excluded from the watch set: `analyze`
+/// writes `.clarion/clarion.db` under it, so the root's mtime is always newer
+/// than the run and would wedge every check to a permanent false [`Stale`]
+/// (the footgun the type-level note records). Returns `None` only on a
+/// query/prepare failure, having set `*degraded`.
+///
+/// [`Stale`]: Staleness::Stale
+fn ingested_files_and_dirs(
+    conn: &Connection,
+    project_root: &Path,
+    degraded: &mut bool,
+) -> Option<(Vec<PathBuf>, BTreeSet<PathBuf>)> {
+    let mut stmt = match conn.prepare(
+        "SELECT DISTINCT source_file_path FROM entities \
+         WHERE source_file_path IS NOT NULL",
+    ) {
+        Ok(stmt) => stmt,
+        Err(err) => {
+            tracing::warn!(error = %err, "clarion staleness source-path query failed");
+            *degraded = true;
+            return None;
+        }
+    };
+    let Ok(rows) = stmt.query_map([], |row| row.get::<_, String>(0)) else {
+        *degraded = true;
+        return None;
+    };
+
+    let mut files = Vec::new();
+    let mut dirs = BTreeSet::new();
+    for rel in rows.flatten() {
+        let abs = if Path::new(&rel).is_absolute() {
+            PathBuf::from(&rel)
+        } else {
+            project_root.join(&rel)
+        };
+        if let Some(parent) = abs.parent()
+            && parent != project_root
+        {
+            dirs.insert(parent.to_path_buf());
+        }
+        files.push(abs);
+    }
+    Some((files, dirs))
+}
+
+/// `true` if any watched directory's mtime is newer than the run, or a watched
+/// directory is gone (a removed package) — both are structural drift. Other
+/// dir-stat errors are environmental and skipped (best-effort, never degrade).
+fn directory_structural_drift(dirs: &BTreeSet<PathBuf>, run_time: SystemTime) -> bool {
+    dirs.iter()
+        .any(|dir| match dir.metadata().and_then(|m| m.modified()) {
+            Ok(mtime) => mtime > run_time,
+            Err(err) => err.kind() == ErrorKind::NotFound,
+        })
+}
+
+/// Scan up to [`MAX_MODIFICATION_STAT_FILES`] ingested files for in-place
+/// edits. Returns `Some(Stale)` on the first file newer-than or deleted-since
+/// the run, `Some(Unknown)` on a non-`NotFound` stat error (environmental, not
+/// degraded), or `None` when every stat-ed file is older than the run (the
+/// caller decides Fresh vs. `NoSourcePaths`). A deleted ingested file
+/// (`NotFound`) is staleness, not an error (clarion-e687941a8c) — the
+/// structural pass usually catches it via the parent directory first, but a
+/// top-level deletion (parent is the unwatched project root) lands here.
+fn file_modification_drift(
+    files: &[PathBuf],
+    run_time: SystemTime,
+    scan_truncated: &mut bool,
+) -> Option<Staleness> {
+    for abs in files.iter().take(MAX_MODIFICATION_STAT_FILES) {
+        match abs.metadata().and_then(|m| m.modified()) {
+            Ok(mtime) if mtime > run_time => return Some(Staleness::Stale),
+            Ok(_) => {}
+            Err(err) if err.kind() == ErrorKind::NotFound => return Some(Staleness::Stale),
+            Err(_) => return Some(Staleness::Unknown),
+        }
+    }
+    // Reached only when no drift was found in the scanned prefix. If the index
+    // has more files than the cap, the resulting `Fresh` verdict is bounded:
+    // record it on the snapshot (not just the log) so a consumer can tell a
+    // proven-fresh index from a fresh-as-far-as-scanned one (clarion-e687941a8c).
+    if files.len() > MAX_MODIFICATION_STAT_FILES {
+        *scan_truncated = true;
+        tracing::warn!(
+            ingested_files = files.len(),
+            cap = MAX_MODIFICATION_STAT_FILES,
+            "clarion staleness: ingested-file count exceeds the modification-scan cap; \
+             in-place edits beyond the cap may go unnoticed until the next analyze"
+        );
+    }
+    None
+}
+
+/// Parse a strict RFC3339 UTC timestamp (the format
+/// `strftime('%Y-%m-%dT%H:%M:%fZ','now')` writes into `runs.completed_at`) to a
+/// `SystemTime`. Returns `None` on any deviation.
+fn parse_iso8601_to_systemtime(iso: &str) -> Option<SystemTime> {
+    use time::OffsetDateTime;
+    use time::format_description::well_known::Rfc3339;
+    let odt = OffsetDateTime::parse(iso, &Rfc3339).ok()?;
+    Some(SystemTime::from(odt))
+}
+
+#[cfg(test)]
+mod tests {
+    use rusqlite::Connection;
+
+    use clarion_storage::{pragma, schema};
+
+    use std::time::Duration;
+
+    use super::{
+        MAX_MODIFICATION_STAT_FILES, Staleness, file_modification_drift, project_snapshot,
+    };
+
+    // `apply_write_pragmas` enforces ADR-011's WAL journal-mode invariant, which
+    // an in-memory connection cannot satisfy (`journal_mode=memory`). Back the
+    // test db with a file in a `TempDir`, matching the canonical pattern in
+    // `clarion-storage`'s own integration tests. The `TempDir` is returned so the
+    // caller keeps it alive for the connection's lifetime.
+    fn migrated_conn() -> (tempfile::TempDir, Connection) {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("clarion.db");
+        let mut conn = Connection::open(path).unwrap();
+        pragma::apply_write_pragmas(&conn).unwrap();
+        schema::apply_migrations(&mut conn).unwrap();
+        (dir, conn)
+    }
+
+    /// Set a file's or directory's mtime deterministically (no flaky sleeps).
+    /// Opening a directory read-only and calling `set_modified` issues
+    /// `futimens` on the dir fd, which is permitted on Linux.
+    fn set_mtime(path: &std::path::Path, when: std::time::SystemTime) {
+        std::fs::File::options()
+            .read(true)
+            .open(path)
+            .unwrap()
+            .set_modified(when)
+            .unwrap();
+    }
+
+    fn insert_entity(conn: &Connection, id: &str, kind: &str, source_file_path: Option<&str>) {
+        conn.execute(
+            "INSERT INTO entities \
+             (id, plugin_id, kind, name, short_name, properties, source_file_path, created_at, updated_at) \
+             VALUES (?1, 'python', ?2, ?3, ?3, '{}', ?4, '2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z')",
+            rusqlite::params![id, kind, id, source_file_path],
+        )
+        .unwrap();
+    }
+
+    #[test]
+    fn counts_entities_subsystems_and_findings() {
+        let (_dir, conn) = migrated_conn();
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        insert_entity(&conn, "python:function:a.f", "function", Some("a.py"));
+        insert_entity(&conn, "core:subsystem:abc", "subsystem", None);
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('run1', '2026-01-01T00:00:00.000Z', '2026-01-02T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+        conn.execute(
+            "INSERT INTO findings \
+             (id, tool, tool_version, run_id, rule_id, kind, severity, entity_id, \
+              related_entities, message, evidence, properties, supports, supported_by, status, created_at, updated_at) \
+             VALUES ('f1','clarion','1.0','run1','R1','defect','WARN','python:module:a', \
+                     '[]','m','{}','{}','[]','[]','open','2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, std::path::Path::new("/nonexistent-root"));
+        assert!(snap.db_present);
+        assert_eq!(snap.entity_count, 3);
+        assert_eq!(snap.subsystem_count, 1);
+        assert_eq!(snap.finding_count, 1);
+        // The ingested `a.py` does not exist under /nonexistent-root and sits at
+        // the (unwatched) project root, so the per-file scan stats it, gets
+        // NotFound, and reports the file as deleted-since-analyze → Stale
+        // (clarion-e687941a8c).
+        assert_eq!(snap.staleness, Staleness::Stale);
+    }
+
+    #[test]
+    fn never_analyzed_when_no_completed_run() {
+        let (_dir, conn) = migrated_conn();
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+        assert_eq!(snap.staleness, Staleness::NeverAnalyzed);
+        assert!(snap.last_analyzed_at.is_none());
+    }
+
+    #[test]
+    fn fresh_when_all_sources_older_than_run() {
+        let (_dir, conn) = migrated_conn();
+        let dir = tempfile::tempdir().unwrap();
+        let src = dir.path().join("a.py");
+        std::fs::write(&src, "x = 1\n").unwrap();
+
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2099-01-01T00:00:00.000Z', '2099-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, dir.path());
+        assert_eq!(snap.staleness, Staleness::Fresh, "{snap:?}");
+        assert_eq!(
+            snap.last_analyzed_at.as_deref(),
+            Some("2099-01-01T00:00:00.000Z")
+        );
+    }
+
+    #[test]
+    fn stale_when_a_source_is_newer_than_run() {
+        let (_dir, conn) = migrated_conn();
+        let dir = tempfile::tempdir().unwrap();
+        let src = dir.path().join("a.py");
+        std::fs::write(&src, "x = 1\n").unwrap();
+
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2000-01-01T00:00:00.000Z', '2000-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, dir.path());
+        assert_eq!(snap.staleness, Staleness::Stale, "{snap:?}");
+    }
+
+    #[test]
+    fn fresh_within_cap_is_not_scan_truncated() {
+        let (_dir, conn) = migrated_conn();
+        let dir = tempfile::tempdir().unwrap();
+        let src = dir.path().join("a.py");
+        std::fs::write(&src, "x = 1\n").unwrap();
+        set_mtime(&src, std::time::UNIX_EPOCH + Duration::from_secs(1_000_000));
+
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        // Run far after the file mtime → Fresh, and only one file → exhaustive.
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2099-01-01T00:00:00.000Z', '2099-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, dir.path());
+        assert_eq!(snap.staleness, Staleness::Fresh, "{snap:?}");
+        assert!(
+            !snap.scan_truncated,
+            "a within-cap scan is exhaustive, not truncated: {snap:?}"
+        );
+    }
+
+    #[test]
+    fn scan_truncated_set_when_file_count_exceeds_cap_without_drift() {
+        // Drive the bounded modification scan directly: one real, old file
+        // repeated past the cap. The surplus entries are never stat-ed (the
+        // scan stops at the cap), but their presence means the resulting
+        // no-drift verdict is bounded — exactly the false-negative risk the
+        // flag warns about (clarion-e687941a8c). Repeating one path keeps the
+        // test cheap instead of materialising 20k files.
+        let dir = tempfile::tempdir().unwrap();
+        let old = dir.path().join("old.py");
+        std::fs::write(&old, "x = 1\n").unwrap();
+        // A run a year in the future: the file is unambiguously older, so every
+        // scanned stat is Fresh and the loop runs to the cap.
+        let run_time = std::time::SystemTime::now() + Duration::from_secs(60 * 60 * 24 * 365);
+        let files = vec![old; MAX_MODIFICATION_STAT_FILES + 1];
+
+        let mut scan_truncated = false;
+        let verdict = file_modification_drift(&files, run_time, &mut scan_truncated);
+        assert_eq!(verdict, None, "no drift among the scanned prefix");
+        assert!(
+            scan_truncated,
+            "exceeding the per-check stat cap must set scan_truncated"
+        );
+    }
+
+    // `compute_staleness` folds: (a) an unparseable run timestamp → Unknown +
+    // degraded; (b) a completed run with no resolvable source path →
+    // NoSourcePaths (never degraded, clarion-22add08e98); (c) a *non*-NotFound
+    // stat error → Unknown (environmental, never degraded). A deleted ingested
+    // file (NotFound) is no longer (c) — it now reports Stale
+    // (clarion-e687941a8c). `non_notfound_stat_error_folds_to_unknown_not_stale`
+    // covers (c); the tests below lock (a) and (b).
+
+    #[test]
+    fn unknown_and_degraded_when_run_timestamp_unparseable() {
+        // (a) An unparseable `completed_at` is a data/machinery fault: Unknown
+        // staleness AND degraded. (`completed_at` is plain TEXT — no format
+        // CHECK — so a garbage value is insertable.)
+        let (_dir, conn) = migrated_conn();
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2026-01-01T00:00:00.000Z', 'not-a-timestamp', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+        assert_eq!(snap.staleness, Staleness::Unknown, "{snap:?}");
+        assert!(
+            snap.degraded,
+            "an unparseable run timestamp is a machinery fault: {snap:?}"
+        );
+        // The raw (unparseable) value is still surfaced verbatim as last_analyzed_at.
+        assert_eq!(snap.last_analyzed_at.as_deref(), Some("not-a-timestamp"));
+    }
+
+    #[test]
+    fn no_source_paths_when_no_entity_has_a_source_file() {
+        // (b) The realistic case: a completed run exists, but every entity is
+        // subsystem-only (NULL source_file_path), so the DISTINCT scan returns
+        // no rows and `saw_any_file` stays false. That is NOT an error fold to
+        // Unknown — it is its own `NoSourcePaths` verdict, and never degraded.
+        let (_dir, conn) = migrated_conn();
+        insert_entity(&conn, "core:subsystem:abc", "subsystem", None);
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2026-01-01T00:00:00.000Z', '2026-01-02T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+        assert_eq!(snap.staleness, Staleness::NoSourcePaths, "{snap:?}");
+        assert!(
+            !snap.degraded,
+            "no-resolvable-source-files is not a failure, never degraded: {snap:?}"
+        );
+        assert_eq!(
+            snap.last_analyzed_at.as_deref(),
+            Some("2026-01-02T00:00:00.000Z")
+        );
+    }
+
+    #[test]
+    fn no_source_paths_serializes_to_snake_case() {
+        // The new wire value is `"no_source_paths"` (serde rename_all =
+        // "snake_case"); pin it so the clarion://context / project_status
+        // vocabulary can't drift silently.
+        let json = serde_json::to_value(Staleness::NoSourcePaths).unwrap();
+        assert_eq!(json, serde_json::Value::String("no_source_paths".into()));
+    }
+
+    #[test]
+    fn healthy_empty_index_is_not_degraded() {
+        let (_dir, conn) = migrated_conn();
+        let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+        // All counts 0 and staleness NeverAnalyzed, but every query succeeded —
+        // this is a genuinely empty index, NOT a degraded read.
+        assert!(
+            !snap.degraded,
+            "healthy empty index must not be degraded: {snap:?}"
+        );
+        assert!(snap.db_present);
+    }
+
+    #[test]
+    fn healthy_populated_index_is_not_degraded() {
+        let (_dir, conn) = migrated_conn();
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("a.py"), "x = 1\n").unwrap();
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2099-01-01T00:00:00.000Z', '2099-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+        let snap = project_snapshot(&conn, dir.path());
+        assert_eq!(snap.staleness, Staleness::Fresh, "{snap:?}");
+        assert!(
+            !snap.degraded,
+            "fresh healthy read must not be degraded: {snap:?}"
+        );
+    }
+
+    #[test]
+    fn degraded_when_a_count_query_fails() {
+        let (_dir, conn) = migrated_conn();
+        // Simulate machinery failure: drop a table a count query depends on so
+        // the `findings` COUNT(*) errors and folds to 0 via scalar_count.
+        conn.execute("DROP TABLE findings", []).unwrap();
+        let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+        assert!(
+            snap.degraded,
+            "a failed count query must mark the snapshot degraded: {snap:?}"
+        );
+        // The fold itself still produces a safe 0 — degraded is the ONLY signal
+        // that distinguishes this from a real empty index.
+        assert_eq!(snap.finding_count, 0);
+        assert!(snap.db_present);
+    }
+
+    #[test]
+    fn deleted_top_level_source_file_reports_stale() {
+        // A recorded source file that no longer exists on disk was deleted since
+        // the last analyze: that is staleness, not Unknown (clarion-e687941a8c).
+        // `gone.py` sits at the (unwatched) project root, so the structural pass
+        // can't see it and the per-file scan's NotFound drives the verdict. A
+        // deletion is environmental, so `degraded` stays false.
+        let (_dir, conn) = migrated_conn();
+        insert_entity(&conn, "python:module:a", "module", Some("gone.py"));
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2026-01-01T00:00:00.000Z', '2026-01-02T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+        let snap = project_snapshot(&conn, std::path::Path::new("/nonexistent-root"));
+        assert_eq!(snap.staleness, Staleness::Stale, "{snap:?}");
+        assert!(
+            !snap.degraded,
+            "a deleted source file is environmental, not degraded: {snap:?}"
+        );
+    }
+
+    #[test]
+    fn added_file_in_watched_dir_reports_stale_via_directory_mtime() {
+        // A brand-new file the last analyze never ingested is invisible to the
+        // per-file scan (it is absent from `entities`), but adding it bumped its
+        // parent directory's mtime — which the structural pass catches. Pin the
+        // ingested file OLDER than the run and the directory NEWER, so ONLY the
+        // structural pass can produce Stale: if detection regressed to files
+        // alone this would wrongly report Fresh (clarion-e687941a8c).
+        use super::parse_iso8601_to_systemtime;
+        let (_dir, conn) = migrated_conn();
+        let root = tempfile::tempdir().unwrap();
+        let pkg = root.path().join("pkg");
+        std::fs::create_dir(&pkg).unwrap();
+        let a = pkg.join("a.py");
+        std::fs::write(&a, "x = 1\n").unwrap();
+
+        let run_iso = "2026-06-15T00:00:00.000Z";
+        let run_time = parse_iso8601_to_systemtime(run_iso).unwrap();
+        let day = std::time::Duration::from_secs(86_400);
+        set_mtime(&a, run_time - day); // ingested file untouched since the run
+        set_mtime(&pkg, run_time + day); // a sibling file was added after the run
+
+        insert_entity(&conn, "python:module:pkg.a", "module", Some("pkg/a.py"));
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', ?1, ?1, '{}', '{}', 'completed')",
+            rusqlite::params![run_iso],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, root.path());
+        assert_eq!(snap.staleness, Staleness::Stale, "{snap:?}");
+        assert!(
+            !snap.degraded,
+            "structural drift is environmental, not degraded: {snap:?}"
+        );
+    }
+
+    #[test]
+    fn non_notfound_stat_error_folds_to_unknown_not_stale() {
+        // A stat failure that is NOT "file missing" — here ENOTDIR, a path whose
+        // parent component is a regular file — is environmental machinery we
+        // cannot read: it folds to Unknown, never Stale, and never sets
+        // `degraded`. This is the fold a deleted file (NotFound -> Stale) is now
+        // distinguished from.
+        let (_dir, conn) = migrated_conn();
+        let root = tempfile::tempdir().unwrap();
+        // A regular file where a directory is expected: stat("blocker/child.py")
+        // returns ENOTDIR, not NotFound.
+        std::fs::write(root.path().join("blocker"), "not a dir\n").unwrap();
+        insert_entity(&conn, "python:module:x", "module", Some("blocker/child.py"));
+        // Run far in the future so the structural pass (which stats the parent
+        // "blocker", a real file with a ~now mtime) finds nothing newer and falls
+        // through to the per-file scan where the ENOTDIR fold happens.
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('r', '2099-01-01T00:00:00.000Z', '2099-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+        let snap = project_snapshot(&conn, root.path());
+        assert_eq!(snap.staleness, Staleness::Unknown, "{snap:?}");
+        assert!(
+            !snap.degraded,
+            "an environmental stat error is not degraded: {snap:?}"
+        );
+    }
+
+    #[test]
+    fn degraded_field_serializes() {
+        let (_dir, conn) = migrated_conn();
+        let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+        let json = serde_json::to_value(&snap).unwrap();
+        assert_eq!(json["degraded"], serde_json::Value::Bool(false));
+    }
+}
diff --git a/crates/clarion-mcp/tests/analyze_lifecycle.rs b/crates/clarion-mcp/tests/analyze_lifecycle.rs
new file mode 100644
index 00000000..c740d7b6
--- /dev/null
+++ b/crates/clarion-mcp/tests/analyze_lifecycle.rs
@@ -0,0 +1,304 @@
+//! MCP analyze lifecycle tools: `analyze_start` / `analyze_status` /
+//! `analyze_cancel` (clarion-7e0c21558a).
+//!
+//! These drive the tools against a stub launcher injected via
+//! `with_analyze_command`, so the lifecycle (background start, live status,
+//! group-kill cancel) is exercised without a real multi-minute analyze. The
+//! stub spawns a grandchild `sleep` and records its pid, letting the cancel
+//! test assert the whole process group — not just the launcher — is killed.
+
+#![cfg(unix)]
+
+use std::os::unix::fs::PermissionsExt;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use clarion_mcp::ServerState;
+use clarion_storage::{ReaderPool, pragma, schema};
+use rusqlite::Connection;
+use serde_json::{Value, json};
+
+fn open_project() -> (tempfile::TempDir, PathBuf) {
+    let project = tempfile::tempdir().expect("temp project");
+    let clarion_dir = project.path().join(".clarion");
+    std::fs::create_dir(&clarion_dir).expect("create .clarion");
+    let db_path = clarion_dir.join("clarion.db");
+    let mut conn = Connection::open(&db_path).expect("open sqlite");
+    pragma::apply_write_pragmas(&conn).expect("write pragmas");
+    schema::apply_migrations(&mut conn).expect("apply migrations");
+    drop(conn);
+    (project, db_path)
+}
+
+fn state_for(project_root: &Path, db_path: &Path, stub: &Path) -> ServerState {
+    let pool = ReaderPool::open(db_path, 2).expect("reader pool");
+    ServerState::new(project_root.to_path_buf(), pool).with_analyze_command(stub.to_path_buf())
+}
+
+/// Write an executable stub that stands in for `clarion analyze`: it parses
+/// `--progress-file`, spawns a grandchild `sleep` (a stand-in for the plugin /
+/// pyright subtree) and records its pid, writes one progress snapshot, then
+/// blocks on the grandchild until the group is killed.
+fn write_stub(dir: &Path) -> PathBuf {
+    let path = dir.join("analyze-stub.sh");
+    let script = r#"#!/bin/sh
+PF=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --progress-file) PF="$2"; shift 2;;
+    *) shift;;
+  esac
+done
+sleep 600 &
+CHILD=$!
+echo "$CHILD" > "${PF}.child"
+HB=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+printf '{"run_id":"stub","pid":%d,"phase":"analyzing","current_plugin":"slowfix","processed_files":1,"total_files":3,"current_file":"src/a.py","heartbeat_at":"%s"}' "$$" "$HB" > "$PF"
+wait "$CHILD"
+"#;
+    std::fs::write(&path, script).expect("write stub");
+    let mut perms = std::fs::metadata(&path)
+        .expect("stub metadata")
+        .permissions();
+    perms.set_mode(0o755);
+    std::fs::set_permissions(&path, perms).expect("chmod stub");
+    path
+}
+
+/// A stub that writes one progress snapshot and exits immediately (no
+/// grandchild, no blocking) — stands in for an analyze run that finishes on its
+/// own, so the reaping path can be exercised.
+fn write_quick_stub(dir: &Path) -> PathBuf {
+    let path = dir.join("analyze-quick-stub.sh");
+    let script = r#"#!/bin/sh
+PF=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --progress-file) PF="$2"; shift 2;;
+    *) shift;;
+  esac
+done
+printf '{"run_id":"stub","phase":"analyzing","heartbeat_at":"2026-01-01T00:00:00.000Z"}' > "$PF"
+exit 0
+"#;
+    std::fs::write(&path, script).expect("write quick stub");
+    let mut perms = std::fs::metadata(&path)
+        .expect("stub metadata")
+        .permissions();
+    perms.set_mode(0o755);
+    std::fs::set_permissions(&path, perms).expect("chmod quick stub");
+    path
+}
+
+async fn call_tool(state: &ServerState, name: &str, arguments: Value) -> Value {
+    let response = state
+        .handle_json_rpc(&json!({
+            "jsonrpc": "2.0",
+            "id": "tool-test",
+            "method": "tools/call",
+            "params": {"name": name, "arguments": arguments}
+        }))
+        .await
+        .expect("tools/call returns a response");
+    let text = response["result"]["content"][0]["text"]
+        .as_str()
+        .expect("tool content text");
+    serde_json::from_str(text).expect("tool envelope JSON")
+}
+
+/// Poll `analyze_status` until `status` matches `want` or the deadline elapses.
+async fn poll_until_status(state: &ServerState, run_id: &str, want: &str) -> Value {
+    for _ in 0..100 {
+        let resp = call_tool(state, "analyze_status", json!({"run_id": run_id})).await;
+        if resp["result"]["status"] == want {
+            return resp;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+    panic!("analyze_status never reached {want} for {run_id}");
+}
+
+fn pid_alive(pid: i32) -> bool {
+    use nix::sys::signal::kill;
+    use nix::unistd::Pid;
+    // Signal 0 probes existence without delivering a signal.
+    kill(Pid::from_raw(pid), None).is_ok()
+}
+
+#[tokio::test]
+async fn analyze_start_runs_in_background_status_reports_progress_then_cancel_kills_group() {
+    let (project, db_path) = open_project();
+    let stub = write_stub(project.path());
+    let state = state_for(project.path(), &db_path, &stub);
+
+    // Start returns a handle immediately without blocking on the run.
+    let started = call_tool(&state, "analyze_start", json!({})).await;
+    assert_eq!(started["ok"], true, "{started:?}");
+    let run_id = started["result"]["run_id"]
+        .as_str()
+        .expect("run_id")
+        .to_owned();
+    let progress_file = started["result"]["progress_file"]
+        .as_str()
+        .expect("progress_file")
+        .to_owned();
+    assert_eq!(started["result"]["status"], "started");
+
+    // Status flips to running and exposes structured progress (no log scraping).
+    let running = poll_until_status(&state, &run_id, "running").await;
+    let result = &running["result"];
+    assert_eq!(result["phase"], "analyzing");
+    assert_eq!(result["current_plugin"], "slowfix");
+    assert_eq!(result["processed_files"], 1);
+    assert_eq!(result["total_files"], 3);
+    assert_eq!(result["current_file"], "src/a.py");
+    assert!(result["heartbeat_at"].as_str().is_some());
+    assert_eq!(result["progress_observed"], true, "{running:?}");
+
+    // The stub recorded its grandchild (stand-in for plugin/pyright) pid.
+    let child_pid: i32 = std::fs::read_to_string(format!("{progress_file}.child"))
+        .expect("child pid file")
+        .trim()
+        .parse()
+        .expect("child pid");
+    assert!(pid_alive(child_pid), "grandchild should be alive mid-run");
+
+    // Cancel marks the run cancelled and group-kills the subtree.
+    let cancelled = call_tool(&state, "analyze_cancel", json!({"run_id": &run_id})).await;
+    assert_eq!(cancelled["ok"], true, "{cancelled:?}");
+    assert_eq!(cancelled["result"]["status"], "cancelled");
+
+    // The grandchild is terminated by the process-group kill.
+    let mut gone = false;
+    for _ in 0..100 {
+        if !pid_alive(child_pid) {
+            gone = true;
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+    assert!(
+        gone,
+        "cancel must terminate the grandchild process (pid {child_pid})"
+    );
+
+    // Status after cancel is terminal-cancelled.
+    let after = call_tool(&state, "analyze_status", json!({"run_id": &run_id})).await;
+    assert_eq!(after["result"]["status"], "cancelled", "{after:?}");
+}
+
+#[tokio::test]
+async fn analyze_start_rejects_a_second_concurrent_run() {
+    let (project, db_path) = open_project();
+    let stub = write_stub(project.path());
+    let state = state_for(project.path(), &db_path, &stub);
+
+    let first = call_tool(&state, "analyze_start", json!({})).await;
+    let run_id = first["result"]["run_id"].as_str().unwrap().to_owned();
+    poll_until_status(&state, &run_id, "running").await;
+
+    let second = call_tool(&state, "analyze_start", json!({})).await;
+    assert_eq!(second["ok"], false, "{second:?}");
+    assert_eq!(second["error"]["code"], "analyze-already-running");
+
+    // Clean up the background run.
+    call_tool(&state, "analyze_cancel", json!({"run_id": &run_id})).await;
+}
+
+/// Seed a `runs` row directly, bypassing the registry, so `analyze_status`
+/// takes the `Absent → read_run_row → terminal_status_envelope` path.
+fn seed_run(db_path: &Path, id: &str, run_status: &str, stats_json: &str) {
+    let conn = Connection::open(db_path).expect("open db");
+    conn.execute(
+        "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+         VALUES (?1, '2026-01-01T00:00:00.000Z', '2026-01-01T00:01:00.000Z', '{}', ?2, ?3)",
+        rusqlite::params![id, stats_json, run_status],
+    )
+    .expect("insert runs row");
+}
+
+#[tokio::test]
+async fn analyze_status_maps_terminal_run_states_from_the_runs_table() {
+    let (project, db_path) = open_project();
+    let stub = write_stub(project.path());
+    let state = state_for(project.path(), &db_path, &stub);
+
+    seed_run(&db_path, "r-done", "completed", "{}");
+    seed_run(&db_path, "r-fail", "failed", "{}");
+    seed_run(&db_path, "r-skip", "skipped_no_plugins", "{}");
+    // A cancelled run is recorded as `failed` + stats.terminal_reason; the
+    // status tool must surface it as cancelled, not failed (decomposition B).
+    seed_run(
+        &db_path,
+        "r-cancel",
+        "failed",
+        r#"{"terminal_reason":"cancelled"}"#,
+    );
+
+    for (id, expected) in [
+        ("r-done", "completed"),
+        ("r-fail", "failed"),
+        ("r-skip", "skipped_no_plugins"),
+        ("r-cancel", "cancelled"),
+    ] {
+        let resp = call_tool(&state, "analyze_status", json!({"run_id": id})).await;
+        assert_eq!(resp["ok"], true, "{resp:?}");
+        assert_eq!(resp["result"]["status"], expected, "run {id}: {resp:?}");
+    }
+}
+
+#[tokio::test]
+async fn analyze_start_reaps_finished_runs_and_their_progress_files() {
+    let (project, db_path) = open_project();
+    let stub = write_quick_stub(project.path());
+    let state = state_for(project.path(), &db_path, &stub);
+
+    // First run finishes on its own (quick stub exits 0).
+    let first = call_tool(&state, "analyze_start", json!({})).await;
+    let first_id = first["result"]["run_id"].as_str().unwrap().to_owned();
+    let first_progress = PathBuf::from(first["result"]["progress_file"].as_str().unwrap());
+    assert_eq!(
+        state.tracked_analyze_runs(),
+        1,
+        "handle tracked after start"
+    );
+
+    // Wait for it to reach a terminal status (it writes no runs row, so the
+    // terminal mapping is `failed` — what matters here is that it exited).
+    poll_until_status(&state, &first_id, "failed").await;
+    assert_eq!(
+        state.tracked_analyze_runs(),
+        1,
+        "status read does not evict — eviction is swept on the next start"
+    );
+
+    // A second start sweeps the finished first run out of the registry and
+    // reaps its progress file before spawning.
+    let second = call_tool(&state, "analyze_start", json!({})).await;
+    assert_eq!(second["ok"], true, "{second:?}");
+    let second_id = second["result"]["run_id"].as_str().unwrap().to_owned();
+    assert_ne!(first_id, second_id);
+
+    assert_eq!(
+        state.tracked_analyze_runs(),
+        1,
+        "only the second run remains; the finished first was evicted"
+    );
+    assert!(
+        !first_progress.exists(),
+        "the finished run's progress file must be reaped on the next start"
+    );
+
+    poll_until_status(&state, &second_id, "failed").await;
+}
+
+#[tokio::test]
+async fn analyze_status_for_unknown_run_is_not_found() {
+    let (project, db_path) = open_project();
+    let stub = write_stub(project.path());
+    let state = state_for(project.path(), &db_path, &stub);
+
+    let resp = call_tool(&state, "analyze_status", json!({"run_id": "no-such-run"})).await;
+    assert_eq!(resp["ok"], false, "{resp:?}");
+    assert_eq!(resp["error"]["code"], "run-not-found");
+}
diff --git a/crates/clarion-mcp/tests/storage_tools.rs b/crates/clarion-mcp/tests/storage_tools.rs
index 02519070..96431b14 100644
--- a/crates/clarion-mcp/tests/storage_tools.rs
+++ b/crates/clarion-mcp/tests/storage_tools.rs
@@ -12,11 +12,13 @@ use clarion_core::{
     RecordingProvider, build_inferred_calls_prompt, build_leaf_summary_prompt,
 };
 use clarion_mcp::{
-    ServerState,
-    config::{LlmConfig, LlmProviderKind},
+    DiagnosticsContext, LlmDiagnostics, ServerState,
+    config::{FiligreeConfig, LlmConfig, LlmProviderKind},
     filigree::{
         EntityAssociation, EntityAssociationsResponse, FiligreeClientError, FiligreeLookup,
+        IssueDetail,
     },
+    filigree_url::{SOURCE_CONFIG, SOURCE_EPHEMERAL_PORT, resolve_filigree_url},
     list_tools,
 };
 use clarion_storage::{
@@ -191,6 +193,42 @@ fn insert_entity(
     .expect("insert entity");
 }
 
+/// Insert an entity carrying a non-empty `properties` JSON blob (e.g. the
+/// `definition` sub-range evidence the Python plugin records). Mirrors
+/// [`insert_entity`] but lets a test seed `properties_json` directly.
+fn insert_entity_with_properties(
+    conn: &Connection,
+    id: &str,
+    kind: &str,
+    source_path: &std::path::Path,
+    range: Option<(i64, i64)>,
+    parent_id: Option<&str>,
+    properties_json: &str,
+) {
+    let content_hash = fixture_content_hash(kind, source_path, range);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, parent_id, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            ?1, 'python', ?2, ?1, ?1, ?3, ?4, ?5, ?6, ?8, ?7,
+            strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+            strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         )",
+        params![
+            id,
+            kind,
+            parent_id,
+            source_path.display().to_string(),
+            range.map(|(start, _)| start),
+            range.map(|(_, end)| end),
+            content_hash,
+            properties_json,
+        ],
+    )
+    .expect("insert entity with properties");
+}
+
 fn fixture_content_hash(
     kind: &str,
     source_path: &std::path::Path,
@@ -361,6 +399,7 @@ fn summary_recording(project_root: &std::path::Path, entity_id: &str) -> Arc<Rec
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             output_json: r#"{"purpose":"cached demo"}"#.to_owned(),
             input_tokens: 120,
+            cached_input_tokens: 0,
             output_tokens: 24,
             total_tokens: 144,
             cost_usd: 0.0,
@@ -476,6 +515,7 @@ fn inferred_recording(
                 r#"{{"edges":[{{"site_key":"{site_key}","target_id":"{target_id}","confidence":0.91,"rationale":"name match"}}]}}"#
             ),
             input_tokens: 100,
+            cached_input_tokens: 0,
             output_tokens: 20,
             total_tokens: 120,
             cost_usd: 0.0,
@@ -573,6 +613,7 @@ impl LlmProvider for AnySummaryProvider {
             model_id: request.model_id,
             output_json: self.output_json.clone(),
             input_tokens: 100,
+            cached_input_tokens: 0,
             output_tokens: 20,
             total_tokens: self.total_tokens,
             cost_usd: self.cost_usd,
@@ -609,6 +650,7 @@ impl LlmProvider for AnyInferredProvider {
             model_id: request.model_id,
             output_json: self.output_json.clone(),
             input_tokens: 100,
+            cached_input_tokens: 0,
             output_tokens: 20,
             total_tokens: 120,
             cost_usd: 0.0,
@@ -632,6 +674,10 @@ impl LlmProvider for AnyInferredProvider {
 struct FakeFiligreeClient {
     responses: Mutex<std::collections::HashMap<String, EntityAssociationsResponse>>,
     calls: Mutex<Vec<String>>,
+    /// `issue_id` -> detail returned by `issue_detail`; absent ids yield `Ok(None)`.
+    details: Mutex<std::collections::HashMap<String, IssueDetail>>,
+    /// `issue_id`s `issue_detail` was called with, in order — proves dedup/N+1.
+    detail_calls: Mutex<Vec<String>>,
 }
 
 impl FakeFiligreeClient {
@@ -643,12 +689,31 @@ impl FakeFiligreeClient {
         self
     }
 
+    fn with_detail(mut self, issue_id: &str, title: &str, status: &str, priority: i64) -> Self {
+        self.details.get_mut().unwrap().insert(
+            issue_id.to_owned(),
+            IssueDetail {
+                title: title.to_owned(),
+                status: status.to_owned(),
+                priority,
+            },
+        );
+        self
+    }
+
     fn calls(&self) -> Vec<String> {
         self.calls
             .lock()
             .unwrap_or_else(std::sync::PoisonError::into_inner)
             .clone()
     }
+
+    fn detail_calls(&self) -> Vec<String> {
+        self.detail_calls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
 }
 
 impl FiligreeLookup for FakeFiligreeClient {
@@ -670,6 +735,19 @@ impl FiligreeLookup for FakeFiligreeClient {
                 associations: Vec::new(),
             }))
     }
+
+    fn issue_detail(&self, issue_id: &str) -> Result<Option<IssueDetail>, FiligreeClientError> {
+        self.detail_calls
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .push(issue_id.to_owned());
+        Ok(self
+            .details
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .get(issue_id)
+            .cloned())
+    }
 }
 
 fn association(issue_id: &str, entity_id: &str, content_hash: &str) -> EntityAssociation {
@@ -690,7 +768,8 @@ async fn call_tool(state: &ServerState, name: &str, arguments: Value) -> Value {
             "method": "tools/call",
             "params": {"name": name, "arguments": arguments}
         }))
-        .await;
+        .await
+        .expect("tools/call request returns a response");
     assert_eq!(response["jsonrpc"], "2.0");
     assert_eq!(response["id"], "tool-test");
     let text = response["result"]["content"][0]["text"]
@@ -818,6 +897,111 @@ async fn summary_on_subsystem_returns_policy_envelope_without_llm_call() {
     handle.await.unwrap().unwrap();
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn summary_on_secret_blocked_entity_returns_policy_envelope_without_llm_or_cache() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "UPDATE entities SET properties = ?1 WHERE id = 'python:function:demo.entry'",
+        params![json!({"briefing_blocked": "secret_present"}).to_string()],
+    )
+    .expect("mark entity blocked");
+    drop(conn);
+
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(AnySummaryProvider::new_output(
+        r#"{"purpose":"should not run"}"#,
+        120,
+        0.012,
+    ));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    let envelope = call_tool(
+        &state,
+        "summary",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["summary"], Value::Null);
+    assert_eq!(envelope["result"]["briefing_blocked"], "secret_present");
+    assert_eq!(envelope["stats_delta"], json!({}));
+    assert!(provider.invocations().is_empty());
+
+    let entity_at = call_tool(&state, "entity_at", json!({"file": "demo.py", "line": 1})).await;
+    assert_eq!(entity_at["ok"], true);
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    let cache_rows: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM summary_cache WHERE entity_id = 'python:function:demo.entry'",
+            [],
+            |row| row.get(0),
+        )
+        .expect("query summary cache");
+    assert_eq!(cache_rows, 0);
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn summary_on_unscanned_source_returns_policy_envelope_without_llm_or_cache() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "UPDATE entities SET properties = ?1 WHERE id = 'python:function:demo.entry'",
+        params![json!({"briefing_blocked": "unscanned_source"}).to_string()],
+    )
+    .expect("mark entity blocked");
+    drop(conn);
+
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(AnySummaryProvider::new_output(
+        r#"{"purpose":"should not run"}"#,
+        120,
+        0.012,
+    ));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    let envelope = call_tool(
+        &state,
+        "summary",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["summary"], Value::Null);
+    assert_eq!(envelope["result"]["briefing_blocked"], "unscanned_source");
+    assert!(
+        envelope["result"]["remediation"]
+            .as_str()
+            .expect("remediation text")
+            .contains("not covered by the pre-ingest secret scan")
+    );
+    assert_eq!(envelope["stats_delta"], json!({}));
+    assert!(provider.invocations().is_empty());
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
 #[tokio::test]
 async fn issues_for_returns_unavailable_when_filigree_disabled() {
     let (project, db_path) = open_project();
@@ -833,6 +1017,71 @@ async fn issues_for_returns_unavailable_when_filigree_disabled() {
     assert_eq!(envelope["ok"], true);
     assert_eq!(envelope["result"]["available"], false);
     assert_eq!(envelope["result"]["reason"], "filigree-disabled");
+    // Unavailable is now an explicit result_kind, distinct from no_matches.
+    assert_eq!(envelope["result"]["result_kind"], "unavailable");
+}
+
+#[tokio::test]
+async fn issues_for_reports_resolved_endpoint_and_result_kind() {
+    // AC#1/#2: issues_for surfaces the configured vs resolved (ethereal-port)
+    // endpoint, and distinguishes reachable-but-empty (no_matches) from a
+    // populated result (matched) — without the agent curling ports by hand.
+    let (project, db_path) = open_project();
+    let filigree_dir = project.path().join(".filigree");
+    fs::create_dir_all(&filigree_dir).unwrap();
+    fs::write(filigree_dir.join("ephemeral.port"), "8542").unwrap();
+    let config = FiligreeConfig {
+        enabled: true,
+        ..FiligreeConfig::default()
+    };
+    let diagnostics = DiagnosticsContext {
+        llm: LlmDiagnostics {
+            provider: "disabled".to_owned(),
+            live: false,
+            allow_live_provider: false,
+            cache_max_age_days: 180,
+        },
+        filigree: resolve_filigree_url(&config, project.path()),
+    };
+
+    // Reachable but no associations for this entity -> no_matches.
+    let empty_client = Arc::new(FakeFiligreeClient::default());
+    let state = state_for_filigree(project.path(), &db_path, empty_client)
+        .with_diagnostics(diagnostics.clone());
+    let envelope = call_tool(
+        &state,
+        "issues_for",
+        json!({"id": "python:function:demo.entry", "include_contained": false}),
+    )
+    .await;
+    assert_eq!(envelope["result"]["available"], true);
+    assert_eq!(envelope["result"]["result_kind"], "no_matches");
+    let endpoint = &envelope["result"]["filigree_endpoint"];
+    assert_eq!(endpoint["configured_url"], "http://127.0.0.1:8766");
+    assert_eq!(endpoint["resolved_url"], "http://127.0.0.1:8542");
+    assert_eq!(endpoint["resolution_source"], SOURCE_EPHEMERAL_PORT);
+
+    // A populated result -> matched, same endpoint block.
+    let client = Arc::new(FakeFiligreeClient::default().with_response(
+        "python:function:demo.entry",
+        vec![association(
+            "filigree-fresh",
+            "python:function:demo.entry",
+            &expected_content_hash(project.path(), "python:function:demo.entry"),
+        )],
+    ));
+    let state = state_for_filigree(project.path(), &db_path, client).with_diagnostics(diagnostics);
+    let envelope = call_tool(
+        &state,
+        "issues_for",
+        json!({"id": "python:function:demo.entry", "include_contained": false}),
+    )
+    .await;
+    assert_eq!(envelope["result"]["result_kind"], "matched");
+    assert_eq!(
+        envelope["result"]["filigree_endpoint"]["resolved_url"],
+        "http://127.0.0.1:8542"
+    );
 }
 
 #[tokio::test]
@@ -883,6 +1132,62 @@ async fn issues_for_includes_contained_entities_and_flags_drift() {
     );
 }
 
+#[tokio::test]
+async fn issues_for_enriches_matched_and_drifted_with_issue_detail() {
+    // AC: matched/drifted entries carry title/status/priority fetched from
+    // Filigree, batched to one request per distinct issue (no N+1), and degrade
+    // to a null `issue` when the detail route has no entry for that issue
+    // (clarion-51a2868c86).
+    let (project, db_path) = open_project();
+    let client = Arc::new(
+        FakeFiligreeClient::default()
+            .with_response(
+                "python:function:demo.entry",
+                vec![association(
+                    "filigree-fresh",
+                    "python:function:demo.entry",
+                    &expected_content_hash(project.path(), "python:function:demo.entry"),
+                )],
+            )
+            .with_response(
+                "python:function:demo.mid",
+                vec![association(
+                    "filigree-drifted",
+                    "python:function:demo.mid",
+                    "old-hash",
+                )],
+            )
+            // Detail present for the matched issue, absent for the drifted one.
+            .with_detail("filigree-fresh", "Refresh tokens", "building", 1),
+    );
+    let state = state_for_filigree(project.path(), &db_path, client.clone());
+
+    let envelope = call_tool(&state, "issues_for", json!({"id": "python:module:demo"})).await;
+
+    assert_eq!(envelope["ok"], true);
+    // Matched entry carries the fetched detail.
+    let matched = &envelope["result"]["matched"][0];
+    assert_eq!(matched["issue_id"], "filigree-fresh");
+    assert_eq!(matched["issue"]["title"], "Refresh tokens");
+    assert_eq!(matched["issue"]["status"], "building");
+    assert_eq!(matched["issue"]["priority"], 1);
+    // Drifted entry has no configured detail → null, but still resolves.
+    let drifted = &envelope["result"]["drifted"][0];
+    assert_eq!(drifted["issue_id"], "filigree-drifted");
+    assert_eq!(drifted["issue"], Value::Null);
+    // Each distinct issue is fetched exactly once (no N+1).
+    let mut detail_calls = client.detail_calls();
+    detail_calls.sort();
+    assert_eq!(
+        detail_calls,
+        vec!["filigree-drifted".to_owned(), "filigree-fresh".to_owned()]
+    );
+    assert_eq!(
+        envelope["stats_delta"]["filigree_detail_requests_total"], 2,
+        "two distinct issues -> two detail requests: {envelope}"
+    );
+}
+
 #[tokio::test]
 async fn issues_for_respects_include_contained_false() {
     let (project, db_path) = open_project();
@@ -1050,7 +1355,7 @@ async fn summary_cold_miss_records_provider_response_then_hits_cache() {
 }
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn summary_invalid_json_preserves_usage_accounting() {
+async fn summary_invalid_json_falls_back_to_structural_summary() {
     let (project, db_path) = open_project();
     let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
     let provider = Arc::new(AnySummaryProvider::new_output("not-json", 120, 0.012));
@@ -1069,16 +1374,70 @@ async fn summary_invalid_json_preserves_usage_accounting() {
     )
     .await;
 
-    assert_eq!(envelope["ok"], false);
-    assert_eq!(envelope["error"]["code"], "llm-invalid-json");
-    assert_eq!(envelope["stats_delta"]["summary_cache_misses_total"], 1);
-    assert_eq!(envelope["stats_delta"]["summary_tokens_input"], 100);
-    assert_eq!(envelope["stats_delta"]["summary_tokens_output"], 20);
-    assert_eq!(envelope["stats_delta"]["summary_tokens_total"], 120);
+    // Invalid provider JSON degrades to a deterministic structural summary
+    // instead of an error (clarion-ed246ca3aa).
+    assert_eq!(envelope["ok"], true, "{envelope}");
+    assert_eq!(envelope["result"]["available"], true);
+    assert_eq!(envelope["result"]["summary"]["kind"], "structural-fallback");
+    assert!(envelope["result"]["summary"]["source_head"].is_string());
+    // The single real call is still accounted (honest), flagged as a fallback.
     assert_eq!(envelope["stats_delta"]["summary_cost_usd"], 0.012);
     assert_eq!(envelope["stats_delta"]["llm_invalid_json_total"], 1);
+    assert_eq!(
+        envelope["stats_delta"]["summary_structural_fallback_total"],
+        1
+    );
+    assert_eq!(provider.invocations().len(), 1);
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn summary_invalid_json_fallback_is_cached_and_not_rebilled() {
+    let (project, db_path) = open_project();
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(AnySummaryProvider::new_output("not-json", 120, 0.012));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    let first = call_tool(
+        &state,
+        "summary",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+    assert_eq!(first["ok"], true, "{first}");
     assert_eq!(provider.invocations().len(), 1);
 
+    // A repeat request must hit the cached fallback: no second LLM call, no
+    // second bill — the deterministic-failure billing loop is closed.
+    let second = call_tool(
+        &state,
+        "summary",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+    assert_eq!(second["ok"], true, "{second}");
+    assert_eq!(second["result"]["cache"]["hit"], true);
+    assert_eq!(second["result"]["summary"]["kind"], "structural-fallback");
+    assert_eq!(second["stats_delta"]["summary_cache_hits_total"], 1);
+    assert!(
+        second["stats_delta"].get("summary_cost_usd").is_none(),
+        "cache hit must not bill again: {second}"
+    );
+    assert_eq!(
+        provider.invocations().len(),
+        1,
+        "no second provider invocation"
+    );
+
     drop(state);
     drop(writer);
     handle.await.unwrap().unwrap();
@@ -1129,7 +1488,7 @@ async fn summary_openrouter_provider_runs_outside_async_runtime() {
             allow_live_provider: true,
             model_id: "anthropic/claude-sonnet-4.6".to_owned(),
             endpoint_url: format!("http://{addr}/api/v1"),
-            referer: "https://github.com/qacona/clarion".to_owned(),
+            referer: "https://github.com/tachyon-beep/clarion".to_owned(),
             title: "Clarion Test".to_owned(),
         })
         .expect("OpenRouter provider"),
@@ -1290,8 +1649,10 @@ async fn summary_cache_hit_reports_stale_semantic_when_graph_counts_drift() {
     handle.await.unwrap().unwrap();
 }
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn summary_expired_cache_row_is_refreshed_by_recording_provider() {
+#[tokio::test]
+async fn summary_preview_cost_reports_cache_hit_without_llm_call() {
+    // AC: a cached summary reports cache_hit (with the row's real tokens/cost)
+    // and never dispatches to the provider.
     let (project, db_path) = open_project();
     let conn = Connection::open(&db_path).unwrap();
     upsert_summary_cache(
@@ -1304,43 +1665,178 @@ async fn summary_expired_cache_row_is_refreshed_by_recording_provider() {
                 model_tier: "anthropic/claude-sonnet-4.6".to_owned(),
                 guidance_fingerprint: "guidance-empty".to_owned(),
             },
-            summary_json: r#"{"purpose":"old"}"#.to_owned(),
-            cost_usd: 0.001,
-            tokens_input: 100,
-            tokens_output: 20,
+            summary_json: r#"{"purpose":"cached"}"#.to_owned(),
+            cost_usd: 0.0021,
+            tokens_input: 123,
+            tokens_output: 45,
             caller_count: 0,
-            fan_out: 2,
+            fan_out: 0,
             stale_semantic: false,
-            created_at: "2026-05-01T00:00:00.000Z".to_owned(),
-            last_accessed_at: "2026-05-01T00:00:00.000Z".to_owned(),
+            created_at: "2026-05-17T00:00:00.000Z".to_owned(),
+            last_accessed_at: "2026-05-17T00:00:00.000Z".to_owned(),
         },
     )
     .unwrap();
     drop(conn);
     let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
-    let provider = summary_recording(project.path(), "python:function:demo.entry");
+    let provider = Arc::new(RecordingProvider::from_recordings(Vec::new()));
     let state = state_for_summary(
         project.path(),
         &db_path,
         &writer,
         provider.clone(),
-        LlmConfig {
-            cache_max_age_days: 1,
-            ..llm_config()
-        },
+        llm_config(),
     );
 
     let envelope = call_tool(
         &state,
-        "summary",
+        "summary_preview_cost",
         json!({"id": "python:function:demo.entry"}),
     )
     .await;
 
     assert_eq!(envelope["ok"], true);
-    assert_eq!(envelope["result"]["cache"]["hit"], false);
-    assert_eq!(envelope["result"]["summary"]["purpose"], "cached demo");
-    assert_eq!(envelope["stats_delta"]["summary_cache_misses_total"], 1);
+    assert_eq!(envelope["result"]["cache_status"], "hit");
+    assert_eq!(envelope["result"]["cached"]["tokens_input"], 123);
+    assert_eq!(envelope["result"]["cached"]["tokens_output"], 45);
+    assert_eq!(envelope["result"]["cached"]["cost_usd"], 0.0021);
+    assert_eq!(envelope["result"]["cached"]["age_days"], 0);
+    assert_eq!(envelope["result"]["live_spend_would_occur"], false);
+    // No estimate needed on a hit, and crucially: no provider call.
+    assert!(envelope["result"]["estimated_input_tokens"].is_null());
+    assert!(
+        provider.invocations().is_empty(),
+        "preview must never call the LLM provider"
+    );
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
+#[tokio::test]
+async fn summary_preview_cost_reports_miss_estimate_and_live_spend() {
+    // AC: a cache miss reports provider/model + a token estimate, flags that a
+    // live call would spend, and still never calls the provider.
+    let (project, db_path) = open_project();
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(RecordingProvider::from_recordings(Vec::new()));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    let envelope = call_tool(
+        &state,
+        "summary_preview_cost",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["cache_status"], "miss");
+    assert!(envelope["result"]["cached"].is_null());
+    assert_eq!(
+        envelope["result"]["model_id"],
+        "anthropic/claude-sonnet-4.6"
+    );
+    assert!(
+        envelope["result"]["estimated_input_tokens"]
+            .as_i64()
+            .is_some_and(|tokens| tokens > 0),
+        "miss should carry a positive input-token estimate: {envelope:?}"
+    );
+    assert_eq!(envelope["result"]["estimated_output_tokens"], 512);
+    assert_eq!(envelope["result"]["policy"]["live"], true);
+    assert_eq!(envelope["result"]["live_spend_would_occur"], true);
+    assert!(
+        provider.invocations().is_empty(),
+        "preview must never call the LLM provider"
+    );
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
+#[tokio::test]
+async fn summary_preview_cost_disabled_llm_is_distinct_from_miss() {
+    // AC: a disabled/unconfigured LLM is reported distinctly from a cache miss —
+    // a miss with no live provider would NOT spend.
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path); // no LLM wired
+
+    let envelope = call_tool(
+        &state,
+        "summary_preview_cost",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["cache_status"], "miss");
+    assert_eq!(envelope["result"]["policy"]["live"], false);
+    assert_eq!(envelope["result"]["policy"]["enabled"], false);
+    assert_eq!(
+        envelope["result"]["live_spend_would_occur"], false,
+        "a miss with no live provider must not be flagged as spending: {envelope:?}"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn summary_expired_cache_row_is_refreshed_by_recording_provider() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).unwrap();
+    upsert_summary_cache(
+        &conn,
+        &SummaryCacheEntry {
+            key: SummaryCacheKey {
+                entity_id: "python:function:demo.entry".to_owned(),
+                content_hash: expected_content_hash(project.path(), "python:function:demo.entry"),
+                prompt_template_id: LEAF_SUMMARY_PROMPT_TEMPLATE_ID.to_owned(),
+                model_tier: "anthropic/claude-sonnet-4.6".to_owned(),
+                guidance_fingerprint: "guidance-empty".to_owned(),
+            },
+            summary_json: r#"{"purpose":"old"}"#.to_owned(),
+            cost_usd: 0.001,
+            tokens_input: 100,
+            tokens_output: 20,
+            caller_count: 0,
+            fan_out: 2,
+            stale_semantic: false,
+            created_at: "2026-05-01T00:00:00.000Z".to_owned(),
+            last_accessed_at: "2026-05-01T00:00:00.000Z".to_owned(),
+        },
+    )
+    .unwrap();
+    drop(conn);
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = summary_recording(project.path(), "python:function:demo.entry");
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        LlmConfig {
+            cache_max_age_days: 1,
+            ..llm_config()
+        },
+    );
+
+    let envelope = call_tool(
+        &state,
+        "summary",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["cache"]["hit"], false);
+    assert_eq!(envelope["result"]["summary"]["purpose"], "cached demo");
+    assert_eq!(envelope["stats_delta"]["summary_cache_misses_total"], 1);
     assert_eq!(provider.invocations().len(), 1);
 
     drop(state);
@@ -1512,154 +2008,1085 @@ async fn entity_at_returns_innermost_entity_and_empty_match() {
     assert_eq!(hit["ok"], true);
     assert_eq!(hit["result"]["entity"]["id"], "python:function:demo.entry");
 
+    // entity_context evidence: the containing stack runs module → matched
+    // entity, and without recorded sub-ranges the reason is the honest
+    // containing_range (the seed fixture carries no `definition` block).
+    let ctx = &hit["result"]["entity_context"];
+    assert_eq!(ctx["query_line"], 1);
+    assert_eq!(ctx["match_reason"], "containing_range");
+    let stack = ctx["containing_stack"].as_array().expect("stack array");
+    assert_eq!(stack.first().unwrap()["id"], "python:module:demo");
+    assert_eq!(stack.last().unwrap()["id"], "python:function:demo.entry");
+    assert!(ctx["freshness"].is_object());
+
     let miss = call_tool(&state, "entity_at", json!({"file": "demo.py", "line": 99})).await;
     assert_eq!(miss["ok"], true);
     assert!(miss["result"]["entity"].is_null());
+    assert_eq!(miss["result"]["entity_context"]["match_reason"], "no_match");
+    assert!(
+        miss["result"]["entity_context"]["containing_stack"]
+            .as_array()
+            .unwrap()
+            .is_empty()
+    );
 }
 
 #[tokio::test]
-async fn find_entity_paginates_and_searches_punctuation_heavy_ids() {
+async fn entity_at_blank_line_reports_containing_range_not_a_fabricated_match() {
     let (project, db_path) = open_project();
     let state = state_for(project.path(), &db_path);
 
-    let first = call_tool(
-        &state,
-        "find_entity",
-        json!({"pattern": "python:function:demo", "limit": 2}),
-    )
-    .await;
-    assert_eq!(first["ok"], true);
-    assert_eq!(first["result"]["entities"].as_array().unwrap().len(), 2);
-    assert_eq!(first["result"]["next_cursor"], "2");
+    // Line 3 of demo.py is the blank line between demo.entry (1-2) and
+    // demo.mid (4-5). Only the module spans it, so the honest answer is the
+    // module with match_reason=containing_range — never a nearby function
+    // dressed up as an exact match (clarion-460def6a51 acceptance #3).
+    let resp = call_tool(&state, "entity_at", json!({"file": "demo.py", "line": 3})).await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    assert_eq!(resp["result"]["entity"]["id"], "python:module:demo");
+    assert_eq!(resp["result"]["entity"]["kind"], "module");
+    assert_eq!(
+        resp["result"]["entity_context"]["match_reason"],
+        "containing_range"
+    );
+}
 
-    let second = call_tool(
-        &state,
-        "find_entity",
-        json!({"pattern": "python:function:demo", "limit": 2, "cursor": "2"}),
-    )
-    .await;
-    assert_eq!(second["ok"], true);
-    assert!(!second["result"]["entities"].as_array().unwrap().is_empty());
+#[tokio::test]
+async fn entity_at_reports_same_span_ambiguity_alternatives() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // demo.target and demo.alt_target both span lines 7-8 in the seed graph.
+    // The innermost winner is chosen by the id tie-break; the other surfaces
+    // as a same-granularity ambiguity alternative.
+    let resp = call_tool(&state, "entity_at", json!({"file": "demo.py", "line": 7})).await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    assert_eq!(
+        resp["result"]["entity"]["id"],
+        "python:function:demo.alt_target"
+    );
+    let alternatives = resp["result"]["entity_context"]["alternatives"]
+        .as_array()
+        .expect("alternatives array");
+    let alt_ids: Vec<&str> = alternatives
+        .iter()
+        .map(|a| a["entity"]["id"].as_str().unwrap())
+        .collect();
+    assert_eq!(alt_ids, vec!["python:function:demo.target"]);
 }
 
 #[tokio::test]
-async fn callers_of_defaults_to_resolved_and_expands_ambiguous_candidates() {
+async fn entity_at_explains_decorator_declaration_and_body_matches() {
     let (project, db_path) = open_project();
+
+    // A decorated class in runtime.py: `@dataclass` on line 1, `class Config:`
+    // on line 2, the field body on line 3. The plugin expands the span to the
+    // decorator line and records the sub-ranges in `properties.definition`.
+    let source = "@dataclass\nclass Config:\n    retries: int = 3\n";
+    let runtime_path = project.path().join("runtime.py");
+    std::fs::write(&runtime_path, source).expect("write runtime.py");
+    {
+        let conn = Connection::open(&db_path).expect("open db");
+        insert_entity_with_properties(
+            &conn,
+            "python:module:runtime",
+            "module",
+            &runtime_path,
+            Some((1, 3)),
+            None,
+            "{}",
+        );
+        insert_entity_with_properties(
+            &conn,
+            "python:class:runtime.Config",
+            "class",
+            &runtime_path,
+            Some((1, 3)),
+            Some("python:module:runtime"),
+            &json!({
+                "definition": {
+                    "decl_line": 2,
+                    "body_line_start": 3,
+                    "decorator_line_start": 1,
+                    "decorator_line_end": 1
+                }
+            })
+            .to_string(),
+        );
+    }
     let state = state_for(project.path(), &db_path);
 
-    let default_callers = call_tool(
+    // Decorator line resolves to the class, explained as decorator_range.
+    let decorator_hit = call_tool(
         &state,
-        "callers_of",
-        json!({"id": "python:function:demo.alt_target"}),
+        "entity_at",
+        json!({"file": "runtime.py", "line": 1}),
     )
     .await;
-    assert_eq!(default_callers["ok"], true);
+    assert_eq!(decorator_hit["ok"], true, "{decorator_hit:?}");
     assert_eq!(
-        default_callers["result"]["callers"]
-            .as_array()
-            .unwrap()
-            .len(),
-        0
+        decorator_hit["result"]["entity"]["id"],
+        "python:class:runtime.Config"
+    );
+    assert_eq!(
+        decorator_hit["result"]["entity_context"]["match_reason"],
+        "decorator_range"
+    );
+    assert_eq!(
+        decorator_hit["result"]["entity_context"]["ranges"]["decl_line"],
+        2
     );
 
-    let ambiguous_callers = call_tool(
+    // The declaration line resolves to the same class with a distinct reason.
+    let declaration_hit = call_tool(
         &state,
-        "callers_of",
-        json!({"id": "python:function:demo.alt_target", "confidence": "ambiguous"}),
+        "entity_at",
+        json!({"file": "runtime.py", "line": 2}),
     )
     .await;
-    assert_eq!(ambiguous_callers["ok"], true);
     assert_eq!(
-        ambiguous_callers["result"]["callers"][0]["entity"]["id"],
-        "python:function:demo.entry"
+        declaration_hit["result"]["entity"]["id"],
+        "python:class:runtime.Config"
     );
     assert_eq!(
-        ambiguous_callers["result"]["callers"][0]["stored_to_id"],
-        "python:function:demo.target"
+        declaration_hit["result"]["entity_context"]["match_reason"],
+        "declaration"
     );
-}
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn callers_of_inferred_dispatches_and_materializes_recording_result() {
-    let (project, db_path) = open_project();
-    let conn = Connection::open(&db_path).unwrap();
-    add_dynamic_source(project.path());
-    let source_path = project.path().join("demo.py");
-    insert_entity(
-        &conn,
-        "python:function:demo.dynamic",
-        "function",
-        &source_path,
-        Some((9, 10)),
-        Some("python:module:demo"),
+    // The body line is classified as body_range.
+    let body_hit = call_tool(
+        &state,
+        "entity_at",
+        json!({"file": "runtime.py", "line": 3}),
+    )
+    .await;
+    assert_eq!(
+        body_hit["result"]["entity"]["id"],
+        "python:class:runtime.Config"
     );
-    insert_unresolved_call_site(
-        &conn,
-        "python:function:demo.entry",
-        "site-dynamic",
-        "dynamic",
+    assert_eq!(
+        body_hit["result"]["entity_context"]["match_reason"],
+        "body_range"
     );
-    drop(conn);
+}
 
-    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
-    let provider = Arc::new(AnyInferredProvider::new(
-        r#"{"edges":[{"site_key":"site-dynamic","target_id":"python:function:demo.dynamic","confidence":0.91,"rationale":"name match"}]}"#,
-    ));
-    let state = state_for_summary(
-        project.path(),
-        &db_path,
-        &writer,
-        provider.clone(),
-        llm_config(),
-    );
+#[tokio::test]
+async fn orientation_pack_for_entity_bundles_all_sections_deterministically() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
 
-    let envelope = call_tool(
+    let resp = call_tool(
         &state,
-        "callers_of",
-        json!({"id": "python:function:demo.dynamic", "confidence": "inferred"}),
+        "orientation_pack",
+        json!({"entity": "python:function:demo.entry"}),
     )
     .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    let result = &resp["result"];
 
-    assert_eq!(envelope["ok"], true);
-    assert_eq!(
-        envelope["result"]["callers"][0]["entity"]["id"],
-        "python:function:demo.entry"
-    );
-    assert_eq!(
-        envelope["result"]["callers"][0]["edge_confidence"],
-        "inferred"
+    // Primary entity + source location.
+    assert_eq!(result["primary_entity"]["id"], "python:function:demo.entry");
+    assert_eq!(result["source"]["source_line_start"], 1);
+    assert!(
+        result["source"]["source_file_path"]
+            .as_str()
+            .unwrap()
+            .ends_with("demo.py")
     );
-    assert_eq!(envelope["stats_delta"]["inferred_dispatch_misses_total"], 1);
-    assert_eq!(provider.invocations().len(), 1);
-    assert_eq!(provider.invocations()[0].purpose, LlmPurpose::InferredEdges);
-    assert_eq!(
-        provider.invocations()[0].prompt_id,
-        INFERRED_CALLS_PROMPT_VERSION
+
+    // Neighbors: resolved callee demo.mid and the module container.
+    let callee_ids: Vec<&str> = result["neighbors"]["callees"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|c| c["entity"]["id"].as_str().unwrap())
+        .collect();
+    assert!(callee_ids.contains(&"python:function:demo.mid"), "{resp:?}");
+    assert_eq!(result["neighbors"]["container"]["id"], "python:module:demo");
+
+    // Compact execution paths reach downstream of entry.
+    assert!(
+        !result["execution_paths"]["paths"]
+            .as_array()
+            .unwrap()
+            .is_empty()
     );
 
-    let warm = call_tool(
+    // issues_for state, index health, and bounded-output bookkeeping are all
+    // present in the one response.
+    assert!(result["issues"].get("available").is_some());
+    assert!(result["health"]["index"].is_object());
+    assert!(result["omitted"].is_object());
+    let suggested = result["suggested_next_reads"].as_array().unwrap();
+    assert_eq!(suggested[0]["tool"], "source_for_entity");
+
+    // Filigree is disabled in this fixture → a clear degradation warning, not a
+    // silent empty section.
+    let warnings: Vec<&str> = result["warnings"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|w| w.as_str().unwrap())
+        .collect();
+    assert!(warnings.iter().any(|w| w.contains("Filigree")), "{resp:?}");
+
+    // Deterministic: the same request yields a byte-identical packet.
+    let again = call_tool(
         &state,
-        "callers_of",
-        json!({"id": "python:function:demo.dynamic", "confidence": "inferred"}),
+        "orientation_pack",
+        json!({"entity": "python:function:demo.entry"}),
     )
     .await;
-    assert_eq!(warm["ok"], true);
-    assert_eq!(provider.invocations().len(), 1);
-
-    drop(state);
-    drop(writer);
-    handle.await.unwrap().unwrap();
+    assert_eq!(resp, again);
 }
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn inferred_dispatch_prompt_uses_caller_source_range_not_whole_file() {
+#[tokio::test]
+async fn orientation_pack_explains_decorator_line_match() {
     let (project, db_path) = open_project();
-    let conn = Connection::open(&db_path).unwrap();
-    add_dynamic_source(project.path());
-    let source_path = project.path().join("demo.py");
-    insert_entity(
-        &conn,
-        "python:function:demo.dynamic",
+
+    // Decorated class: `@dataclass` on line 1, `class Config:` on line 2.
+    let source = "@dataclass\nclass Config:\n    retries: int = 3\n";
+    let runtime_path = project.path().join("runtime.py");
+    std::fs::write(&runtime_path, source).expect("write runtime.py");
+    {
+        let conn = Connection::open(&db_path).expect("open db");
+        insert_entity_with_properties(
+            &conn,
+            "python:module:runtime",
+            "module",
+            &runtime_path,
+            Some((1, 3)),
+            None,
+            "{}",
+        );
+        insert_entity_with_properties(
+            &conn,
+            "python:class:runtime.Config",
+            "class",
+            &runtime_path,
+            Some((1, 3)),
+            Some("python:module:runtime"),
+            &json!({
+                "definition": {
+                    "decl_line": 2,
+                    "body_line_start": 3,
+                    "decorator_line_start": 1,
+                    "decorator_line_end": 1
+                }
+            })
+            .to_string(),
+        );
+    }
+    let state = state_for(project.path(), &db_path);
+
+    let resp = call_tool(
+        &state,
+        "orientation_pack",
+        json!({"file": "runtime.py", "line": 1}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    assert_eq!(
+        resp["result"]["primary_entity"]["id"],
+        "python:class:runtime.Config"
+    );
+    assert_eq!(
+        resp["result"]["entity_context"]["match_reason"],
+        "decorator_range"
+    );
+}
+
+#[tokio::test]
+async fn orientation_pack_degrades_when_no_entity_spans_the_line() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // demo.py has no entity spanning line 99.
+    let resp = call_tool(
+        &state,
+        "orientation_pack",
+        json!({"file": "demo.py", "line": 99}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    assert!(resp["result"]["primary_entity"].is_null());
+    assert_eq!(resp["result"]["entity_context"]["match_reason"], "no_match");
+    assert!(!resp["result"]["warnings"].as_array().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn orientation_pack_rejects_ambiguous_input_form() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // Supplying both `entity` and `file`+`line` is invalid; the dispatcher
+    // returns a JSON-RPC error rather than a tool envelope.
+    let response = state
+        .handle_json_rpc(&json!({
+            "jsonrpc": "2.0",
+            "id": "ambiguous",
+            "method": "tools/call",
+            "params": {
+                "name": "orientation_pack",
+                "arguments": {"entity": "python:function:demo.entry", "file": "demo.py", "line": 1}
+            }
+        }))
+        .await
+        .expect("response");
+    assert!(response.get("error").is_some(), "{response:?}");
+}
+
+#[tokio::test]
+async fn orientation_pack_for_module_rolls_up_references() {
+    // The packet-assembly path must also roll up module references and surface
+    // `via`, not just `neighborhood` (clarion-79d0ff6e14 review).
+    let (project, db_path) = open_project();
+    {
+        let conn = Connection::open(&db_path).expect("reopen db");
+        let source_path = project.path().join("consumer.py");
+        std::fs::write(
+            &source_path,
+            "import demo\n\ndef use():\n    return demo.target()\n",
+        )
+        .expect("write consumer source");
+        insert_entity(
+            &conn,
+            "python:module:consumer",
+            "module",
+            &source_path,
+            Some((1, 4)),
+            None,
+        );
+        insert_entity(
+            &conn,
+            "python:function:consumer.use",
+            "function",
+            &source_path,
+            Some((3, 4)),
+            Some("python:module:consumer"),
+        );
+        insert_edge(
+            &conn,
+            "contains",
+            "python:module:consumer",
+            "python:function:consumer.use",
+            "resolved",
+            None,
+        );
+        insert_edge(
+            &conn,
+            "references",
+            "python:function:consumer.use",
+            "python:function:demo.target",
+            "resolved",
+            None,
+        );
+    }
+    let state = state_for(project.path(), &db_path);
+
+    let resp = call_tool(
+        &state,
+        "orientation_pack",
+        json!({"entity": "python:module:demo"}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    let neighbors = &resp["result"]["neighbors"];
+    assert_eq!(neighbors["references_rolled_up"], true);
+    let refs_in = neighbors["references_in"]
+        .as_array()
+        .expect("references_in");
+    assert_eq!(
+        refs_in.len(),
+        1,
+        "external referencer rolls up: {refs_in:?}"
+    );
+    assert_eq!(refs_in[0]["entity"]["id"], "python:function:consumer.use");
+    assert_eq!(refs_in[0]["via"]["id"], "python:function:demo.target");
+}
+
+#[tokio::test]
+async fn source_for_entity_returns_span_with_line_numbers_and_context() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // demo.mid is indexed at lines 4-5 of demo.py.
+    let resp = call_tool(
+        &state,
+        "source_for_entity",
+        json!({"id": "python:function:demo.mid", "context_lines": 1}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    let result = &resp["result"];
+    assert_eq!(result["source_status"], "ok");
+    assert_eq!(result["line_start"], 4);
+    assert_eq!(result["line_end"], 5);
+    assert_eq!(result["truncated"], false);
+
+    // context_lines=1 widens the window to lines 3..6.
+    let lines = result["lines"].as_array().expect("lines array");
+    assert_eq!(lines.first().unwrap()["number"], 3);
+    assert_eq!(lines.last().unwrap()["number"], 6);
+
+    // The entity's own lines carry the exact source text and in_entity=true;
+    // the context lines are flagged in_entity=false.
+    let by_number = |n: i64| lines.iter().find(|l| l["number"] == n).unwrap();
+    assert_eq!(by_number(4)["text"], "def mid():");
+    assert_eq!(by_number(4)["in_entity"], true);
+    assert_eq!(by_number(5)["text"], "    return target()");
+    assert_eq!(by_number(5)["in_entity"], true);
+    assert_eq!(by_number(3)["in_entity"], false);
+    assert_eq!(by_number(6)["in_entity"], false);
+}
+
+#[tokio::test]
+async fn source_for_entity_reports_drift_instead_of_stale_snippet() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // Mutate the source after indexing so the file no longer matches the
+    // stored content_hash.
+    std::fs::write(
+        project.path().join("demo.py"),
+        "def entry():\n    return mid()\n\ndef mid():\n    return target()  # changed\n\ndef target():\n    return 1\n",
+    )
+    .expect("rewrite source");
+
+    let resp = call_tool(
+        &state,
+        "source_for_entity",
+        json!({"id": "python:function:demo.mid"}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    assert_eq!(resp["result"]["source_status"], "drifted");
+    assert!(resp["result"]["drift"]["stored_content_hash"].is_string());
+    assert!(resp["result"]["drift"]["current_content_hash"].is_string());
+    // No source lines are handed back when the snippet would be stale.
+    assert!(resp["result"].get("lines").is_none());
+}
+
+#[tokio::test]
+async fn source_for_entity_reports_missing_file_and_unknown_entity() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    std::fs::remove_file(project.path().join("demo.py")).expect("remove source");
+    let missing = call_tool(
+        &state,
+        "source_for_entity",
+        json!({"id": "python:function:demo.mid"}),
+    )
+    .await;
+    assert_eq!(missing["ok"], true, "{missing:?}");
+    assert_eq!(missing["result"]["source_status"], "missing");
+
+    let unknown = call_tool(
+        &state,
+        "source_for_entity",
+        json!({"id": "python:function:does.not.exist"}),
+    )
+    .await;
+    assert_eq!(unknown["ok"], false, "{unknown:?}");
+    assert_eq!(unknown["error"]["code"], "not-found");
+}
+
+#[tokio::test]
+async fn call_sites_caller_shows_calls_and_references_with_line_text() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // demo.entry calls mid (resolved) and target (ambiguous, candidate
+    // alt_target), and references target (resolved).
+    let resp = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry", "confidence": "ambiguous"}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    assert_eq!(resp["result"]["role"], "caller");
+
+    let sites = resp["result"]["sites"].as_array().expect("sites array");
+    assert!(!sites.is_empty(), "{resp:?}");
+    // Every site carries the evidence fields, with a resolved byte->line map.
+    for site in sites {
+        assert!(site["edge_kind"].is_string(), "{site:?}");
+        assert!(site["confidence"].is_string(), "{site:?}");
+        assert!(
+            site["file"].as_str().unwrap().ends_with("demo.py"),
+            "{site:?}"
+        );
+        assert!(site["line"].as_i64().unwrap() >= 1, "{site:?}");
+        assert!(site["line_text"].is_string(), "{site:?}");
+    }
+
+    let kinds: std::collections::BTreeSet<&str> = sites
+        .iter()
+        .map(|s| s["edge_kind"].as_str().unwrap())
+        .collect();
+    assert!(
+        kinds.contains("calls") && kinds.contains("references"),
+        "{kinds:?}"
+    );
+
+    let confidences: std::collections::BTreeSet<&str> = sites
+        .iter()
+        .map(|s| s["confidence"].as_str().unwrap())
+        .collect();
+    assert!(
+        confidences.contains("resolved") && confidences.contains("ambiguous"),
+        "expected both resolved and ambiguous evidence: {confidences:?}"
+    );
+
+    let targets: std::collections::BTreeSet<&str> = sites
+        .iter()
+        .map(|s| s["other_id"].as_str().unwrap())
+        .collect();
+    assert!(targets.contains("python:function:demo.mid"), "{targets:?}");
+}
+
+#[tokio::test]
+async fn call_sites_redacts_line_text_for_briefing_blocked_owner() {
+    // A call/reference site owned by an entity whose file the pre-ingest
+    // scanner marked briefing_blocked must not have its source bytes read into
+    // line_text — that would bypass the secret-redaction policy other read
+    // paths enforce. demo.entry owns its outgoing sites; mark it blocked.
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    conn.execute(
+        "UPDATE entities SET properties = ?1 WHERE id = 'python:function:demo.entry'",
+        params![json!({"briefing_blocked": "secret_present"}).to_string()],
+    )
+    .expect("mark entity blocked");
+    drop(conn);
+    let state = state_for(project.path(), &db_path);
+
+    let resp = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry", "confidence": "ambiguous"}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    let sites = resp["result"]["sites"].as_array().expect("sites array");
+    assert!(!sites.is_empty(), "{resp:?}");
+    for site in sites {
+        assert_eq!(
+            site["line_text"], "",
+            "briefing-blocked owner must redact line_text: {site:?}"
+        );
+        assert_eq!(site["briefing_blocked"], true, "{site:?}");
+    }
+    // The blocked file's source bytes must not leak anywhere in the payload.
+    let blob = resp.to_string();
+    assert!(
+        !blob.contains("return mid"),
+        "leaked blocked source: {blob}"
+    );
+    assert!(
+        !blob.contains("return target"),
+        "leaked blocked source: {blob}"
+    );
+}
+
+#[tokio::test]
+async fn call_sites_kind_filter_limits_to_one_edge_kind() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let resp = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry", "kind": "references"}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    let sites = resp["result"]["sites"].as_array().expect("sites");
+    assert!(!sites.is_empty(), "{resp:?}");
+    assert!(
+        sites.iter().all(|s| s["edge_kind"] == "references"),
+        "kind=references leaked other edge kinds: {resp:?}"
+    );
+}
+
+#[tokio::test]
+async fn call_sites_path_scope_filters_by_test_heuristic() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // The seed lives in demo.py (not a conventional test path), so the unfiltered
+    // and production scopes agree and the test scope filters everything out.
+    let unfiltered = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry", "confidence": "ambiguous"}),
+    )
+    .await;
+    let production = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry", "confidence": "ambiguous", "path": "production"}),
+    )
+    .await;
+    let test = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry", "confidence": "ambiguous", "path": "test"}),
+    )
+    .await;
+    assert_eq!(production["ok"], true, "{production:?}");
+    assert_eq!(test["ok"], true, "{test:?}");
+
+    let n_unfiltered = unfiltered["result"]["sites"].as_array().unwrap().len();
+    let n_production = production["result"]["sites"].as_array().unwrap().len();
+    assert!(n_unfiltered > 0, "{unfiltered:?}");
+    assert_eq!(
+        n_production, n_unfiltered,
+        "production scope should keep all demo.py sites"
+    );
+    assert!(
+        test["result"]["sites"].as_array().unwrap().is_empty(),
+        "test scope should exclude the non-test demo.py sites: {test:?}"
+    );
+}
+
+#[tokio::test]
+async fn call_sites_marks_unresolved_separately_and_rejects_unknown_entity() {
+    let (project, db_path) = open_project();
+    // Seed an unresolved (statically unbindable) call site for demo.entry.
+    {
+        let conn = Connection::open(&db_path).expect("open");
+        insert_unresolved_call_site(
+            &conn,
+            "python:function:demo.entry",
+            "site-dynamic",
+            "ctx.handler.dispatch",
+        );
+    }
+    let state = state_for(project.path(), &db_path);
+
+    let resp = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+    assert_eq!(resp["ok"], true, "{resp:?}");
+    let unresolved = resp["result"]["unresolved_sites"]
+        .as_array()
+        .expect("unresolved_sites");
+    assert_eq!(unresolved.len(), 1, "{resp:?}");
+    assert_eq!(unresolved[0]["callee_expr"], "ctx.handler.dispatch");
+    // Unresolved evidence must not be mixed into the resolved `sites` list.
+    let resolved_exprs: Vec<&str> = resp["result"]["sites"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .filter_map(|s| s["callee_expr"].as_str())
+        .collect();
+    assert!(resolved_exprs.is_empty(), "{resp:?}");
+
+    let unknown = call_tool(
+        &state,
+        "call_sites",
+        json!({"id": "python:function:does.not.exist"}),
+    )
+    .await;
+    assert_eq!(unknown["ok"], false, "{unknown:?}");
+    assert_eq!(unknown["error"]["code"], "not-found");
+}
+
+#[tokio::test]
+async fn find_entity_paginates_and_searches_punctuation_heavy_ids() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let first = call_tool(
+        &state,
+        "find_entity",
+        json!({"pattern": "python:function:demo", "limit": 2}),
+    )
+    .await;
+    assert_eq!(first["ok"], true);
+    assert_eq!(first["result"]["entities"].as_array().unwrap().len(), 2);
+    assert_eq!(first["result"]["next_cursor"], "2");
+
+    let second = call_tool(
+        &state,
+        "find_entity",
+        json!({"pattern": "python:function:demo", "limit": 2, "cursor": "2"}),
+    )
+    .await;
+    assert_eq!(second["ok"], true);
+    assert!(!second["result"]["entities"].as_array().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn find_entity_kind_filter_returns_only_that_kind() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // Unfiltered "demo" search returns the module AND its functions.
+    let unfiltered = call_tool(
+        &state,
+        "find_entity",
+        json!({"pattern": "demo", "limit": 100}),
+    )
+    .await;
+    assert_eq!(unfiltered["ok"], true);
+    let kinds: std::collections::BTreeSet<String> = unfiltered["result"]["entities"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|e| e["kind"].as_str().unwrap().to_owned())
+        .collect();
+    assert!(
+        kinds.contains("module") && kinds.contains("function"),
+        "{kinds:?}"
+    );
+
+    // kind=module returns only modules.
+    let modules = call_tool(
+        &state,
+        "find_entity",
+        json!({"pattern": "demo", "limit": 100, "kind": "module"}),
+    )
+    .await;
+    assert_eq!(modules["ok"], true);
+    let module_entities = modules["result"]["entities"].as_array().unwrap();
+    assert!(!module_entities.is_empty(), "{modules:?}");
+    assert!(
+        module_entities.iter().all(|e| e["kind"] == "module"),
+        "kind filter leaked non-module entities: {modules:?}"
+    );
+
+    // A blank kind is a malformed request — it surfaces as a JSON-RPC error,
+    // not a tool envelope, so drive handle_json_rpc directly here.
+    let blank = state
+        .handle_json_rpc(&json!({
+            "jsonrpc": "2.0",
+            "id": "blank-kind",
+            "method": "tools/call",
+            "params": {"name": "find_entity", "arguments": {"pattern": "demo", "kind": "  "}}
+        }))
+        .await
+        .expect("response");
+    assert!(
+        blank["error"].is_object(),
+        "blank kind should be a param error: {blank:?}"
+    );
+}
+
+#[tokio::test]
+async fn subsystem_of_resolves_module_and_contained_function() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    let subsystem_id = seed_subsystem(&conn, project.path());
+    drop(conn);
+    let state = state_for(project.path(), &db_path);
+
+    // A module resolves directly.
+    let from_module = call_tool(&state, "subsystem_of", json!({"id": "python:module:demo"})).await;
+    assert_eq!(from_module["ok"], true);
+    assert_eq!(from_module["result"]["subsystem"]["id"], subsystem_id);
+    assert_eq!(from_module["result"]["via_module_id"], "python:module:demo");
+
+    // A contained function resolves through its module ancestor.
+    let from_fn = call_tool(
+        &state,
+        "subsystem_of",
+        json!({"id": "python:function:demo.entry"}),
+    )
+    .await;
+    assert_eq!(from_fn["ok"], true);
+    assert_eq!(from_fn["result"]["subsystem"]["id"], subsystem_id);
+    assert_eq!(
+        from_fn["result"]["subsystem"]["name"],
+        "Subsystem abc123def456"
+    );
+    assert_eq!(from_fn["result"]["via_module_id"], "python:module:demo");
+}
+
+#[tokio::test]
+async fn subsystem_of_reports_null_subsystem_and_missing_entity() {
+    // No seed_subsystem: the demo module exists but is in no subsystem.
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    // Entity exists but has no subsystem -> ok with subsystem: null (a fact,
+    // distinguishable from a missing entity).
+    let no_sub = call_tool(&state, "subsystem_of", json!({"id": "python:module:demo"})).await;
+    assert_eq!(no_sub["ok"], true);
+    assert!(no_sub["result"]["subsystem"].is_null(), "{no_sub:?}");
+    assert!(no_sub["result"]["via_module_id"].is_null(), "{no_sub:?}");
+
+    // Missing entity -> ok:false entity-not-found envelope.
+    let missing = call_tool(
+        &state,
+        "subsystem_of",
+        json!({"id": "python:function:does.not.exist"}),
+    )
+    .await;
+    assert_ne!(missing["ok"], true, "{missing:?}");
+}
+
+#[tokio::test]
+async fn callers_of_defaults_to_resolved_and_expands_ambiguous_candidates() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let default_callers = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.alt_target"}),
+    )
+    .await;
+    assert_eq!(default_callers["ok"], true);
+    assert_eq!(
+        default_callers["result"]["callers"]
+            .as_array()
+            .unwrap()
+            .len(),
+        0
+    );
+
+    let ambiguous_callers = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.alt_target", "confidence": "ambiguous"}),
+    )
+    .await;
+    assert_eq!(ambiguous_callers["ok"], true);
+    assert_eq!(
+        ambiguous_callers["result"]["callers"][0]["entity"]["id"],
+        "python:function:demo.entry"
+    );
+    assert_eq!(
+        ambiguous_callers["result"]["callers"][0]["stored_to_id"],
+        "python:function:demo.target"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn callers_of_inferred_dispatches_and_materializes_recording_result() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).unwrap();
+    add_dynamic_source(project.path());
+    let source_path = project.path().join("demo.py");
+    insert_entity(
+        &conn,
+        "python:function:demo.dynamic",
+        "function",
+        &source_path,
+        Some((9, 10)),
+        Some("python:module:demo"),
+    );
+    insert_unresolved_call_site(
+        &conn,
+        "python:function:demo.entry",
+        "site-dynamic",
+        "dynamic",
+    );
+    drop(conn);
+
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(AnyInferredProvider::new(
+        r#"{"edges":[{"site_key":"site-dynamic","target_id":"python:function:demo.dynamic","confidence":0.91,"rationale":"name match"}]}"#,
+    ));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    let envelope = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.dynamic", "confidence": "inferred"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(
+        envelope["result"]["callers"][0]["entity"]["id"],
+        "python:function:demo.entry"
+    );
+    assert_eq!(
+        envelope["result"]["callers"][0]["edge_confidence"],
+        "inferred"
+    );
+    // Inferred (LLM) dispatch attempts the attribute-receiver cases, so nothing
+    // is excluded from the search (clarion-0d204a3f16).
+    assert_eq!(envelope["result"]["scope_excludes"], json!([]));
+    assert_eq!(envelope["stats_delta"]["inferred_dispatch_misses_total"], 1);
+    assert_eq!(provider.invocations().len(), 1);
+    assert_eq!(provider.invocations()[0].purpose, LlmPurpose::InferredEdges);
+    assert_eq!(
+        provider.invocations()[0].prompt_id,
+        INFERRED_CALLS_PROMPT_VERSION
+    );
+
+    let warm = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.dynamic", "confidence": "inferred"}),
+    )
+    .await;
+    assert_eq!(warm["ok"], true);
+    assert_eq!(provider.invocations().len(), 1);
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn attribute_receiver_call_is_excluded_at_resolved_but_attempted_at_inferred() {
+    // Attribute-receiver call `ctx.dynamic()` (callee_expr `ctx.dynamic`): the
+    // static resolver cannot bind the `ctx` receiver, but the site IS recorded as
+    // unresolved, so inferred (LLM) dispatch — which keys off the method name —
+    // can recover it. This mirrors the motivating elspeth case `ctx.orchestrator
+    // .resume()` (callee_expr `orchestrator.resume`, recovered when resolving a
+    // target named `resume`). Resolved/ambiguous must FLAG the blind spot;
+    // inferred must not, because it actually searches the category
+    // (clarion-0d204a3f16).
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).unwrap();
+    add_dynamic_source(project.path());
+    let source_path = project.path().join("demo.py");
+    insert_entity(
+        &conn,
+        "python:function:demo.dynamic",
+        "function",
+        &source_path,
+        Some((9, 10)),
+        Some("python:module:demo"),
+    );
+    insert_unresolved_call_site(
+        &conn,
+        "python:function:demo.entry",
+        "site-attr",
+        "ctx.dynamic",
+    );
+    drop(conn);
+
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(AnyInferredProvider::new(
+        r#"{"edges":[{"site_key":"site-attr","target_id":"python:function:demo.dynamic","confidence":0.9,"rationale":"attribute receiver"}]}"#,
+    ));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    // Resolved: the attribute-receiver caller is not bound, and the blind spot is flagged.
+    let resolved = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.dynamic"}),
+    )
+    .await;
+    assert_eq!(resolved["ok"], true);
+    assert_eq!(resolved["result"]["callers"].as_array().unwrap().len(), 0);
+    assert_eq!(
+        resolved["result"]["scope_excludes"],
+        json!(["attribute-receiver-calls"])
+    );
+
+    // Inferred: LLM dispatch recovers the attribute-receiver caller, so nothing is
+    // excluded — the empty-vs-complete distinction is honest, not wallpaper.
+    let inferred = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.dynamic", "confidence": "inferred"}),
+    )
+    .await;
+    assert_eq!(inferred["ok"], true);
+    assert_eq!(
+        inferred["result"]["callers"][0]["entity"]["id"],
+        "python:function:demo.entry"
+    );
+    assert_eq!(inferred["result"]["scope_excludes"], json!([]));
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn callers_of_inferred_skips_briefing_blocked_callers_without_llm() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).unwrap();
+    add_dynamic_source(project.path());
+    let source_path = project.path().join("demo.py");
+    insert_entity(
+        &conn,
+        "python:function:demo.dynamic",
+        "function",
+        &source_path,
+        Some((9, 10)),
+        Some("python:module:demo"),
+    );
+    insert_unresolved_call_site(
+        &conn,
+        "python:function:demo.entry",
+        "site-dynamic",
+        "dynamic",
+    );
+    conn.execute(
+        "UPDATE entities SET properties = ?1 WHERE id = 'python:function:demo.entry'",
+        params![json!({"briefing_blocked": "secret_present"}).to_string()],
+    )
+    .expect("mark caller briefing-blocked");
+    drop(conn);
+
+    let (writer, handle) = Writer::spawn(db_path.clone(), 50, 256).unwrap();
+    let provider = Arc::new(AnyInferredProvider::new(
+        r#"{"edges":[{"site_key":"site-dynamic","target_id":"python:function:demo.dynamic","confidence":0.91,"rationale":"name match"}]}"#,
+    ));
+    let state = state_for_summary(
+        project.path(),
+        &db_path,
+        &writer,
+        provider.clone(),
+        llm_config(),
+    );
+
+    let envelope = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.dynamic", "confidence": "inferred"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["callers"].as_array().unwrap().len(), 0);
+    assert_eq!(
+        envelope["stats_delta"]["inferred_dispatch_briefing_blocked_total"],
+        1
+    );
+    assert!(provider.invocations().is_empty());
+
+    drop(state);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn inferred_dispatch_prompt_uses_caller_source_range_not_whole_file() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).unwrap();
+    add_dynamic_source(project.path());
+    let source_path = project.path().join("demo.py");
+    insert_entity(
+        &conn,
+        "python:function:demo.dynamic",
         "function",
         &source_path,
         Some((1, 2)),
@@ -1917,6 +3344,102 @@ async fn execution_paths_from_reports_edge_cap_truncation() {
     assert_eq!(envelope["result"]["edge_count_visited"], 2);
 }
 
+// ── compact ranked execution paths (clarion-5b3eff9a91 + clarion-23ae24358c) ──
+
+#[tokio::test]
+async fn execution_paths_from_returns_compact_node_table_and_id_paths() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "execution_paths_from",
+        json!({"id": "python:function:demo.entry", "max_depth": 3}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    let result = &envelope["result"];
+    assert_eq!(result["root"], "python:function:demo.entry");
+
+    // paths are arrays of node-id strings, not re-serialized node objects.
+    let paths = result["paths"].as_array().expect("paths array");
+    assert!(!paths.is_empty());
+    for path in paths {
+        for node in path.as_array().unwrap() {
+            assert!(
+                node.is_string(),
+                "path element must be a node-id string, got {node:?}"
+            );
+        }
+    }
+
+    // nodes is a deduplicated table: each id once, no content_hash bloat,
+    // short_name retained for readability.
+    let nodes = result["nodes"].as_array().expect("nodes array");
+    let ids: Vec<&str> = nodes.iter().map(|n| n["id"].as_str().unwrap()).collect();
+    let mut deduped = ids.clone();
+    deduped.sort_unstable();
+    deduped.dedup();
+    assert_eq!(ids.len(), deduped.len(), "node table must be deduplicated");
+    assert!(
+        nodes.iter().all(|n| n.get("content_hash").is_none()),
+        "compact nodes must drop content_hash"
+    );
+    assert!(nodes.iter().all(|n| n.get("short_name").is_some()));
+
+    // every id referenced by a path resolves in the node table.
+    let node_ids: std::collections::HashSet<&str> = ids.into_iter().collect();
+    for path in paths {
+        for node in path.as_array().unwrap() {
+            assert!(
+                node_ids.contains(node.as_str().unwrap()),
+                "path references node {node:?} absent from the node table"
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn execution_paths_from_ranks_longest_paths_first() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "execution_paths_from",
+        json!({"id": "python:function:demo.entry", "max_depth": 3}),
+    )
+    .await;
+
+    let paths = envelope["result"]["paths"].as_array().unwrap();
+    let lengths: Vec<usize> = paths.iter().map(|p| p.as_array().unwrap().len()).collect();
+    let mut descending = lengths.clone();
+    descending.sort_unstable_by(|a, b| b.cmp(a));
+    assert_eq!(
+        lengths, descending,
+        "paths must be ranked longest-first, got {lengths:?}"
+    );
+}
+
+#[tokio::test]
+async fn execution_paths_from_path_cap_sets_truncated() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path).with_path_cap(1);
+
+    let envelope = call_tool(
+        &state,
+        "execution_paths_from",
+        json!({"id": "python:function:demo.entry", "max_depth": 3, "confidence": "ambiguous"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["truncated"], true);
+    assert_eq!(envelope["truncation_reason"], "path-cap");
+    assert_eq!(envelope["result"]["paths"].as_array().unwrap().len(), 1);
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn execution_paths_from_inferred_dispatches_start_caller() {
     let (project, db_path) = open_project();
@@ -1968,7 +3491,7 @@ async fn execution_paths_from_inferred_dispatches_start_caller() {
                 path.as_array()
                     .unwrap()
                     .iter()
-                    .any(|node| node["id"] == "python:function:demo.dynamic")
+                    .any(|node_id| node_id == "python:function:demo.dynamic")
             })
     );
     assert_eq!(provider.invocations().len(), 1);
@@ -2028,7 +3551,7 @@ async fn execution_paths_from_inferred_dispatches_reached_callers() {
                 path.as_array()
                     .unwrap()
                     .iter()
-                    .any(|node| node["id"] == "python:function:demo.dynamic")
+                    .any(|node_id| node_id == "python:function:demo.dynamic")
             })
     );
     assert_eq!(provider.invocations().len(), 1);
@@ -2062,3 +3585,560 @@ async fn neighborhood_returns_one_hop_graph_sections() {
         "python:function:demo.entry"
     );
 }
+
+#[tokio::test]
+async fn neighborhood_surfaces_import_edges_for_reverse_import_lookup() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).unwrap();
+    // demo imports `other`; `client` imports demo. The reverse-import question
+    // ("who imports demo?") is answerable only if neighborhood surfaces the
+    // distinct `imports` edge kind, not just `references` (clarion-79d0ff6e14).
+    std::fs::write(project.path().join("other.py"), "x = 1\n").unwrap();
+    std::fs::write(project.path().join("client.py"), "import demo\n").unwrap();
+    insert_entity(
+        &conn,
+        "python:module:other",
+        "module",
+        &project.path().join("other.py"),
+        Some((1, 1)),
+        None,
+    );
+    insert_entity(
+        &conn,
+        "python:module:client",
+        "module",
+        &project.path().join("client.py"),
+        Some((1, 1)),
+        None,
+    );
+    insert_edge(
+        &conn,
+        "imports",
+        "python:module:demo",
+        "python:module:other",
+        "resolved",
+        None,
+    );
+    insert_edge(
+        &conn,
+        "imports",
+        "python:module:client",
+        "python:module:demo",
+        "resolved",
+        None,
+    );
+    drop(conn);
+
+    let state = state_for(project.path(), &db_path);
+    let envelope = call_tool(&state, "neighborhood", json!({"id": "python:module:demo"})).await;
+
+    assert_eq!(envelope["ok"], true, "{envelope}");
+    let imports_out: Vec<&str> = envelope["result"]["imports_out"]
+        .as_array()
+        .expect("imports_out array")
+        .iter()
+        .map(|n| n["entity"]["id"].as_str().unwrap())
+        .collect();
+    assert!(
+        imports_out.contains(&"python:module:other"),
+        "imports_out should list what demo imports: {envelope}"
+    );
+    let imports_in: Vec<&str> = envelope["result"]["imports_in"]
+        .as_array()
+        .expect("imports_in array")
+        .iter()
+        .map(|n| n["entity"]["id"].as_str().unwrap())
+        .collect();
+    assert!(
+        imports_in.contains(&"python:module:client"),
+        "imports_in should list who imports demo: {envelope}"
+    );
+}
+
+// ── scope_excludes on graph-query results (clarion-0d204a3f16) ───────────────
+
+#[tokio::test]
+async fn callers_of_resolved_flags_attribute_receiver_scope_exclusion() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "callers_of",
+        json!({"id": "python:function:demo.target"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(
+        envelope["result"]["scope_excludes"],
+        json!(["attribute-receiver-calls"])
+    );
+}
+
+#[tokio::test]
+async fn execution_paths_from_resolved_flags_attribute_receiver_scope_exclusion() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "execution_paths_from",
+        json!({"id": "python:function:demo.entry", "confidence": "ambiguous"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(
+        envelope["result"]["scope_excludes"],
+        json!(["attribute-receiver-calls"])
+    );
+}
+
+#[tokio::test]
+async fn neighborhood_module_rolls_up_references_and_flags_attribute_scope() {
+    // The module now rolls up contained symbols' reference edges instead of
+    // flagging the rollup as a blind spot (clarion-79d0ff6e14). The seeded
+    // graph's only `references` edge (entry -> target) is intra-module, so it
+    // is correctly excluded — references_in/out are empty but the response
+    // signals the rollup happened.
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "neighborhood",
+        json!({"id": "python:module:demo", "confidence": "resolved"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(
+        envelope["result"]["references_rolled_up"], true,
+        "module neighborhood must signal references are rolled up to module altitude"
+    );
+    let excludes = envelope["result"]["scope_excludes"]
+        .as_array()
+        .expect("scope_excludes array");
+    assert!(
+        excludes.iter().any(|v| v == "attribute-receiver-calls"),
+        "module neighborhood must flag attribute-receiver-calls, got {excludes:?}"
+    );
+    assert!(
+        !excludes
+            .iter()
+            .any(|v| v == "module-level-reference-rollup"),
+        "module rollup is now implemented; the blind-spot marker must be gone, got {excludes:?}"
+    );
+    assert_eq!(
+        envelope["result"]["references_in"],
+        json!([]),
+        "the only seeded reference is intra-module and must be excluded from the rollup"
+    );
+}
+
+#[tokio::test]
+async fn neighborhood_function_references_are_not_rolled_up() {
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "neighborhood",
+        json!({"id": "python:function:demo.target", "confidence": "resolved"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(
+        envelope["result"]["references_rolled_up"], false,
+        "symbol-level references are direct, not rolled up"
+    );
+    assert_eq!(
+        envelope["result"]["scope_excludes"],
+        json!(["attribute-receiver-calls"])
+    );
+}
+
+#[tokio::test]
+async fn neighborhood_module_rollup_surfaces_external_reverse_import() {
+    // Seed an external module symbol that references a symbol contained in
+    // `demo`, then confirm the module-altitude rollup answers "who imports this
+    // module / contract?" with the referencer tagged by the `via` symbol
+    // (clarion-79d0ff6e14).
+    let (project, db_path) = open_project();
+    {
+        let conn = Connection::open(&db_path).expect("reopen db");
+        let source_path = project.path().join("consumer.py");
+        std::fs::write(
+            &source_path,
+            "import demo\n\ndef use():\n    return demo.target()\n",
+        )
+        .expect("write consumer source");
+        insert_entity(
+            &conn,
+            "python:module:consumer",
+            "module",
+            &source_path,
+            Some((1, 4)),
+            None,
+        );
+        insert_entity(
+            &conn,
+            "python:function:consumer.use",
+            "function",
+            &source_path,
+            Some((3, 4)),
+            Some("python:module:consumer"),
+        );
+        insert_edge(
+            &conn,
+            "contains",
+            "python:module:consumer",
+            "python:function:consumer.use",
+            "resolved",
+            None,
+        );
+        insert_edge(
+            &conn,
+            "references",
+            "python:function:consumer.use",
+            "python:function:demo.target",
+            "resolved",
+            None,
+        );
+    }
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(
+        &state,
+        "neighborhood",
+        json!({"id": "python:module:demo", "confidence": "resolved"}),
+    )
+    .await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["references_rolled_up"], true);
+    let refs_in = envelope["result"]["references_in"]
+        .as_array()
+        .expect("references_in array");
+    assert_eq!(
+        refs_in.len(),
+        1,
+        "external referencer must roll up: {refs_in:?}"
+    );
+    assert_eq!(
+        refs_in[0]["entity"]["id"], "python:function:consumer.use",
+        "neighbor is the external referencer (who imports)"
+    );
+    assert_eq!(
+        refs_in[0]["via"]["id"], "python:function:demo.target",
+        "via names the contained symbol the import touched"
+    );
+    // Reverse-import names importing MODULES, not just symbols
+    // (clarion-79d0ff6e14 AC): the importing symbol's containing module is
+    // surfaced alongside the symbol, so "who imports this" is answerable at
+    // module altitude.
+    assert_eq!(
+        refs_in[0]["importer_module"]["id"], "python:module:consumer",
+        "importer_module rolls the importing symbol up to its module"
+    );
+}
+
+#[tokio::test]
+async fn index_diff_is_reachable_over_mcp_and_reports_freshness() {
+    // AC: index_diff output is available over MCP. A completed run dated far in
+    // the future keeps the just-written demo.py un-modified, so the verdict is
+    // deterministic regardless of the (non-repo) tempdir's git environment.
+    let (project, db_path) = open_project();
+    {
+        let conn = Connection::open(&db_path).expect("reopen db");
+        insert_run(
+            &conn,
+            "run-fresh",
+            "2999-01-01T00:00:00.000Z",
+            "completed",
+            Some("2999-01-01T00:00:05.000Z"),
+        );
+    }
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(&state, "index_diff", json!({})).await;
+
+    assert_eq!(envelope["ok"], true);
+    let result = &envelope["result"];
+    assert_eq!(result["overall"], "fresh");
+    assert_eq!(result["drift_detected"], false);
+    // analyzed_commit is null by design; the git block is always present.
+    assert_eq!(result["analyzed_commit"], Value::Null);
+    assert!(result["git"]["available"].is_boolean());
+    assert_eq!(result["analyzed_at"], "2999-01-01T00:00:05.000Z");
+    assert_eq!(
+        result["indexed_files"], 1,
+        "the seeded graph has a single source file (demo.py)"
+    );
+    assert_eq!(result["modified_since_analyze"], json!([]));
+}
+
+#[tokio::test]
+async fn index_diff_reports_never_analyzed_without_a_completed_run() {
+    // open_project seeds entities but no run row.
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(&state, "index_diff", json!({})).await;
+
+    assert_eq!(envelope["ok"], true);
+    assert_eq!(envelope["result"]["overall"], "never_analyzed");
+    assert_eq!(envelope["result"]["drift_detected"], false);
+}
+
+// ── project_status diagnostics tool (clarion-084e82250c) ─────────────────────
+
+fn insert_run(
+    conn: &Connection,
+    id: &str,
+    started_at: &str,
+    status: &str,
+    completed: Option<&str>,
+) {
+    conn.execute(
+        "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+         VALUES (?1, ?2, ?3, '{}', '{}', ?4)",
+        params![id, started_at, completed, status],
+    )
+    .expect("insert run");
+}
+
+fn insert_finding(conn: &Connection, id: &str, run_id: &str, entity_id: &str) {
+    conn.execute(
+        "INSERT INTO findings \
+         (id, tool, tool_version, run_id, rule_id, kind, severity, entity_id, \
+          related_entities, message, evidence, properties, supports, supported_by, \
+          status, created_at, updated_at) \
+         VALUES (?1,'clarion','1.0',?2,'R1','defect','WARN',?3,'[]','m','{}','{}','[]','[]', \
+                 'open','2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')",
+        params![id, run_id, entity_id],
+    )
+    .expect("insert finding");
+}
+
+#[test]
+fn tools_list_includes_project_status() {
+    let tools = list_tools();
+    let tool = tools
+        .iter()
+        .find(|tool| tool.name == "project_status")
+        .expect("project_status tool definition");
+    assert_eq!(
+        tool.input_schema,
+        json!({"type": "object", "properties": {}, "additionalProperties": false})
+    );
+}
+
+#[tokio::test]
+async fn project_status_reports_db_identity_for_drift_detection() {
+    // A swapped/stale DB is otherwise invisible to a consult agent. Report a
+    // db_identity block (on-disk size + SQLite data_version) so drift is
+    // detectable across calls (clarion-22c18fdb34).
+    let (project, db_path) = open_project();
+    let state = state_for(project.path(), &db_path);
+
+    let envelope = call_tool(&state, "project_status", json!({})).await;
+
+    assert_eq!(envelope["ok"], true, "{envelope}");
+    let identity = &envelope["result"]["db_identity"];
+    assert!(
+        identity["db_size_bytes"].as_u64().is_some_and(|n| n > 0),
+        "db_size_bytes should reflect the served file: {envelope}"
+    );
+    assert!(
+        identity["data_version"].as_i64().is_some(),
+        "data_version should be reported for drift detection: {envelope}"
+    );
+}
+
+#[tokio::test]
+async fn project_status_reports_counts_latest_run_and_plugins() {
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    seed_subsystem(&conn, project.path());
+    insert_run(
+        &conn,
+        "run-1",
+        "2026-02-02T00:00:00.000Z",
+        "completed",
+        Some("2026-02-02T00:00:00.000Z"),
+    );
+    insert_finding(&conn, "f-1", "run-1", "python:function:demo.entry");
+    // One entity withheld from briefings (secret scan set briefing_blocked).
+    conn.execute(
+        "INSERT INTO entities (id, plugin_id, kind, name, short_name, properties, \
+         created_at, updated_at) \
+         VALUES (?1, 'python', 'function', ?1, ?1, ?2, \
+         strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))",
+        rusqlite::params![
+            "python:function:demo.secret",
+            r#"{"briefing_blocked": "secret_detected"}"#
+        ],
+    )
+    .expect("insert briefing-blocked entity");
+    drop(conn);
+
+    let state = state_for(project.path(), &db_path);
+    let envelope = call_tool(&state, "project_status", json!({})).await;
+    assert_eq!(envelope["ok"], true);
+    let result = &envelope["result"];
+
+    assert!(result["counts"]["entities"].as_i64().unwrap() >= 4);
+    assert_eq!(result["counts"]["subsystems"], 1);
+    assert!(result["counts"]["edges"].as_i64().unwrap() >= 1);
+    assert_eq!(result["counts"]["findings"], 1);
+    // The briefing_blocked count is served by the partial index over the
+    // generated column (clarion-bdabfd6bca).
+    assert_eq!(result["counts"]["briefing_blocked"], 1);
+
+    // AC#1: latest completed run + counts.
+    assert_eq!(result["latest_run"]["id"], "run-1");
+    assert_eq!(result["latest_run"]["status"], "completed");
+    assert_eq!(
+        result["latest_run"]["completed_at"],
+        "2026-02-02T00:00:00.000Z"
+    );
+    assert_eq!(result["last_analyzed_at"], "2026-02-02T00:00:00.000Z");
+
+    let plugin_ids: Vec<&str> = result["plugins"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|plugin| plugin["plugin_id"].as_str().unwrap())
+        .collect();
+    assert!(plugin_ids.contains(&"python"), "plugins: {plugin_ids:?}");
+
+    assert!(
+        result["db_path"]
+            .as_str()
+            .unwrap()
+            .ends_with(".clarion/clarion.db")
+    );
+    // No analyze-time git SHA is persisted; reported as null, not fabricated.
+    assert_eq!(result["git_sha"], Value::Null);
+    // A bare ServerState carries no diagnostics context.
+    assert_eq!(result["llm"], Value::Null);
+    assert_eq!(result["filigree"], Value::Null);
+}
+
+#[tokio::test]
+async fn project_status_marks_skipped_no_plugins_run() {
+    // AC#2: a skipped_no_plugins run is unmistakable as no index refresh.
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    insert_run(
+        &conn,
+        "run-skip",
+        "2026-02-03T00:00:00.000Z",
+        "skipped_no_plugins",
+        Some("2026-02-03T00:00:00.000Z"),
+    );
+    drop(conn);
+    let state = state_for(project.path(), &db_path);
+    let envelope = call_tool(&state, "project_status", json!({})).await;
+    assert_eq!(
+        envelope["result"]["latest_run"]["status"],
+        "skipped_no_plugins"
+    );
+}
+
+#[tokio::test]
+async fn project_status_skipped_run_keeps_prior_completed_index_visible() {
+    // The real dogfood shape: a skipped_no_plugins run AFTER a completed one.
+    // latest_run.status flags the skip, while last_analyzed_at + counts still
+    // describe the older, usable index ("your last attempt skipped — here's the
+    // index from before").
+    let (project, db_path) = open_project();
+    let conn = Connection::open(&db_path).expect("open sqlite");
+    insert_run(
+        &conn,
+        "run-old",
+        "2026-01-01T00:00:00.000Z",
+        "completed",
+        Some("2026-01-15T00:00:00.000Z"),
+    );
+    insert_run(
+        &conn,
+        "run-skip",
+        "2026-02-01T00:00:00.000Z",
+        "skipped_no_plugins",
+        Some("2026-02-01T00:00:00.000Z"),
+    );
+    drop(conn);
+    let state = state_for(project.path(), &db_path);
+    let result = call_tool(&state, "project_status", json!({})).await["result"].clone();
+
+    assert_eq!(result["latest_run"]["id"], "run-skip");
+    assert_eq!(result["latest_run"]["status"], "skipped_no_plugins");
+    // last_analyzed_at tracks the latest *completed* run, not the skip.
+    assert_eq!(result["last_analyzed_at"], "2026-01-15T00:00:00.000Z");
+    assert!(result["counts"]["entities"].as_i64().unwrap() >= 3);
+}
+
+#[tokio::test]
+async fn project_status_resolves_live_filigree_endpoint() {
+    // AC#3: the live ethereal port (.filigree/ephemeral.port) is reported as
+    // the resolution source, overriding the stale configured port.
+    let (project, db_path) = open_project();
+    let filigree_dir = project.path().join(".filigree");
+    fs::create_dir_all(&filigree_dir).unwrap();
+    fs::write(filigree_dir.join("ephemeral.port"), "8542").unwrap();
+
+    let config = FiligreeConfig {
+        enabled: true,
+        ..FiligreeConfig::default()
+    };
+    let diagnostics = DiagnosticsContext {
+        llm: LlmDiagnostics {
+            provider: "disabled".to_owned(),
+            live: false,
+            allow_live_provider: false,
+            cache_max_age_days: 180,
+        },
+        filigree: resolve_filigree_url(&config, project.path()),
+    };
+    let state = state_for(project.path(), &db_path).with_diagnostics(diagnostics);
+
+    let envelope = call_tool(&state, "project_status", json!({})).await;
+    let filigree = &envelope["result"]["filigree"];
+    assert_eq!(filigree["enabled"], true);
+    assert_eq!(filigree["configured_url"], "http://127.0.0.1:8766");
+    assert_eq!(filigree["resolved_url"], "http://127.0.0.1:8542");
+    assert_eq!(filigree["resolution_source"], SOURCE_EPHEMERAL_PORT);
+
+    let llm = &envelope["result"]["llm"];
+    assert_eq!(llm["provider"], "disabled");
+    assert_eq!(llm["live"], false);
+    assert_eq!(llm["cache_max_age_days"], 180);
+}
+
+#[tokio::test]
+async fn project_status_filigree_falls_back_to_config_without_port_file() {
+    let (project, db_path) = open_project();
+    let config = FiligreeConfig {
+        enabled: true,
+        ..FiligreeConfig::default()
+    };
+    let diagnostics = DiagnosticsContext {
+        llm: LlmDiagnostics {
+            provider: "openrouter".to_owned(),
+            live: true,
+            allow_live_provider: true,
+            cache_max_age_days: 7,
+        },
+        filigree: resolve_filigree_url(&config, project.path()),
+    };
+    let state = state_for(project.path(), &db_path).with_diagnostics(diagnostics);
+    let envelope = call_tool(&state, "project_status", json!({})).await;
+    let filigree = &envelope["result"]["filigree"];
+    assert_eq!(filigree["resolved_url"], "http://127.0.0.1:8766");
+    assert_eq!(filigree["resolution_source"], SOURCE_CONFIG);
+    assert_eq!(envelope["result"]["llm"]["live"], true);
+}
diff --git a/crates/clarion-plugin-fixture/Cargo.toml b/crates/clarion-plugin-fixture/Cargo.toml
index 3c46f905..1986f170 100644
--- a/crates/clarion-plugin-fixture/Cargo.toml
+++ b/crates/clarion-plugin-fixture/Cargo.toml
@@ -14,7 +14,7 @@ name = "clarion-plugin-fixture"
 path = "src/main.rs"
 
 [dependencies]
-clarion-core = { path = "../clarion-core", version = "0.1.0-dev" }
+clarion-core = { path = "../clarion-core", version = "1.0.0" }
 serde_json.workspace = true
 
 [target.'cfg(unix)'.dependencies]
diff --git a/crates/clarion-scanner/Cargo.toml b/crates/clarion-scanner/Cargo.toml
new file mode 100644
index 00000000..d64555d6
--- /dev/null
+++ b/crates/clarion-scanner/Cargo.toml
@@ -0,0 +1,20 @@
+[package]
+name = "clarion-scanner"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+regex.workspace = true
+serde.workspace = true
+serde_norway.workspace = true
+sha1.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
diff --git a/crates/clarion-scanner/src/baseline.rs b/crates/clarion-scanner/src/baseline.rs
new file mode 100644
index 00000000..3a1c30ed
--- /dev/null
+++ b/crates/clarion-scanner/src/baseline.rs
@@ -0,0 +1,285 @@
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    fs,
+    path::{Component, Path, PathBuf},
+};
+
+use serde::{Deserialize, Serialize};
+
+use crate::{DetectSecretsRule, Detection, HashedSecret};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Baseline {
+    version: String,
+    entries: BTreeMap<PathBuf, Vec<BaselineEntry>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BaselineEntry {
+    pub rule_type: DetectSecretsRule,
+    pub hashed_secret: HashedSecret,
+    pub line_number: u32,
+    pub is_secret: bool,
+    pub justification: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BaselineMatch {
+    pub file_path: PathBuf,
+    pub entry: BaselineEntry,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BaselineEntryIssue {
+    pub file: PathBuf,
+    pub line: u32,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SuppressionResult {
+    pub allowed: Vec<Detection>,
+    pub suppressed: Vec<Detection>,
+    pub fired_entries: Vec<BaselineMatch>,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum BaselineError {
+    #[error("baseline version mismatch: expected 1.0, got {0}")]
+    UnsupportedVersion(String),
+    #[error("baseline entries missing required field 'justification'")]
+    MissingJustifications { entries: Vec<BaselineEntryIssue> },
+    #[error("baseline path must be repository-relative and stay within the project: {file}")]
+    InvalidPath { file: PathBuf },
+    #[error("baseline entry has invalid hashed_secret at {file}:{line}: {details}")]
+    InvalidHash {
+        file: PathBuf,
+        line: u32,
+        details: String,
+    },
+    #[error("baseline entry has unsupported detector type at {file}:{line}: {rule_type:?}")]
+    UnsupportedRuleType {
+        file: PathBuf,
+        line: u32,
+        rule_type: String,
+    },
+    #[error("baseline parse error: {0}")]
+    Parse(#[from] serde_norway::Error),
+    #[error("baseline I/O error: {0}")]
+    Io(#[from] std::io::Error),
+}
+
+pub fn load_baseline(path: &Path) -> Result<Baseline, BaselineError> {
+    match fs::read_to_string(path) {
+        Ok(raw) => Baseline::from_yaml_str(&raw),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(Baseline::empty()),
+        Err(err) => Err(BaselineError::Io(err)),
+    }
+}
+
+impl Baseline {
+    #[must_use]
+    pub fn empty() -> Self {
+        Self {
+            version: "1.0".to_owned(),
+            entries: BTreeMap::new(),
+        }
+    }
+
+    pub fn from_yaml_str(raw: &str) -> Result<Self, BaselineError> {
+        let parsed: RawBaseline = serde_norway::from_str(raw)?;
+        Self::from_raw(parsed)
+    }
+
+    pub fn to_yaml_string(&self) -> Result<String, BaselineError> {
+        let raw = RawBaseline::from(self);
+        serde_norway::to_string(&raw).map_err(BaselineError::Parse)
+    }
+
+    #[must_use]
+    pub fn entries(&self) -> &BTreeMap<PathBuf, Vec<BaselineEntry>> {
+        &self.entries
+    }
+
+    #[must_use]
+    pub fn suppress(&self, detections: Vec<Detection>, file: &Path) -> SuppressionResult {
+        let entries = self.entries_for(file);
+        let mut allowed = Vec::new();
+        let mut suppressed = Vec::new();
+        let mut fired_entries = Vec::new();
+        let mut fired_keys = BTreeSet::new();
+
+        'detections: for detection in detections {
+            for (baseline_path, entry) in &entries {
+                if entry.is_secret {
+                    continue;
+                }
+                if entry.hashed_secret == detection.hashed_secret
+                    && entry.line_number == detection.line_number
+                    && entry.rule_type == detection.detect_secrets_type
+                {
+                    let key = (
+                        (*baseline_path).clone(),
+                        entry.rule_type,
+                        entry.hashed_secret,
+                        entry.line_number,
+                    );
+                    if fired_keys.insert(key) {
+                        fired_entries.push(BaselineMatch {
+                            file_path: (*baseline_path).clone(),
+                            entry: (*entry).clone(),
+                        });
+                    }
+                    suppressed.push(detection);
+                    continue 'detections;
+                }
+            }
+            allowed.push(detection);
+        }
+
+        SuppressionResult {
+            allowed,
+            suppressed,
+            fired_entries,
+        }
+    }
+
+    fn from_raw(raw: RawBaseline) -> Result<Self, BaselineError> {
+        if raw.version != "1.0" {
+            return Err(BaselineError::UnsupportedVersion(raw.version));
+        }
+        for file in raw.results.keys() {
+            validate_baseline_path(file)?;
+        }
+        let mut missing_justifications = Vec::new();
+        for (file, raw_entries) in &raw.results {
+            for entry in raw_entries {
+                if entry
+                    .justification
+                    .as_ref()
+                    .is_none_or(|value| value.trim().is_empty())
+                {
+                    missing_justifications.push(BaselineEntryIssue {
+                        file: file.clone(),
+                        line: entry.line_number,
+                    });
+                }
+            }
+        }
+        if !missing_justifications.is_empty() {
+            return Err(BaselineError::MissingJustifications {
+                entries: missing_justifications,
+            });
+        }
+
+        let mut entries = BTreeMap::new();
+        for (file, raw_entries) in raw.results {
+            let mut converted = Vec::new();
+            for entry in raw_entries {
+                let justification = entry.justification.unwrap_or_default();
+                let rule_type =
+                    DetectSecretsRule::try_from(entry.rule_type.as_str()).map_err(|_| {
+                        BaselineError::UnsupportedRuleType {
+                            file: file.clone(),
+                            line: entry.line_number,
+                            rule_type: entry.rule_type.clone(),
+                        }
+                    })?;
+                let hashed_secret =
+                    HashedSecret::from_hex(&entry.hashed_secret).map_err(|details| {
+                        BaselineError::InvalidHash {
+                            file: file.clone(),
+                            line: entry.line_number,
+                            details: details.to_string(),
+                        }
+                    })?;
+                converted.push(BaselineEntry {
+                    rule_type,
+                    hashed_secret,
+                    line_number: entry.line_number,
+                    is_secret: entry.is_secret,
+                    justification,
+                });
+            }
+            entries.insert(file, converted);
+        }
+        Ok(Self {
+            version: raw.version,
+            entries,
+        })
+    }
+
+    fn entries_for(&self, file: &Path) -> Vec<(&PathBuf, &BaselineEntry)> {
+        self.entries
+            .get_key_value(file)
+            .map(|(path, entries)| entries.iter().map(move |entry| (path, entry)).collect())
+            .unwrap_or_default()
+    }
+}
+
+fn validate_baseline_path(file: &Path) -> Result<(), BaselineError> {
+    let invalid = file.as_os_str().is_empty()
+        || file.is_absolute()
+        || file.components().any(|component| {
+            matches!(
+                component,
+                Component::ParentDir | Component::RootDir | Component::Prefix(_)
+            )
+        });
+    if invalid {
+        Err(BaselineError::InvalidPath {
+            file: file.to_path_buf(),
+        })
+    } else {
+        Ok(())
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct RawBaseline {
+    version: String,
+    #[serde(default)]
+    results: BTreeMap<PathBuf, Vec<RawBaselineEntry>>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct RawBaselineEntry {
+    #[serde(rename = "type")]
+    rule_type: String,
+    hashed_secret: String,
+    line_number: u32,
+    #[serde(default = "default_is_secret")]
+    is_secret: bool,
+    justification: Option<String>,
+}
+
+fn default_is_secret() -> bool {
+    true
+}
+
+impl From<&Baseline> for RawBaseline {
+    fn from(value: &Baseline) -> Self {
+        let results = value
+            .entries
+            .iter()
+            .map(|(path, entries)| {
+                (
+                    path.clone(),
+                    entries
+                        .iter()
+                        .map(|entry| RawBaselineEntry {
+                            rule_type: entry.rule_type.as_str().to_owned(),
+                            hashed_secret: entry.hashed_secret.to_string(),
+                            line_number: entry.line_number,
+                            is_secret: entry.is_secret,
+                            justification: Some(entry.justification.clone()),
+                        })
+                        .collect(),
+                )
+            })
+            .collect();
+        Self {
+            version: value.version.clone(),
+            results,
+        }
+    }
+}
diff --git a/crates/clarion-scanner/src/entropy.rs b/crates/clarion-scanner/src/entropy.rs
new file mode 100644
index 00000000..0c52d766
--- /dev/null
+++ b/crates/clarion-scanner/src/entropy.rs
@@ -0,0 +1,60 @@
+use std::collections::BTreeMap;
+
+/// Entropy threshold and minimum candidate length for one alphabet.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct EntropyTuning {
+    pub min_len: usize,
+    pub min_entropy: f64,
+}
+
+impl EntropyTuning {
+    pub const BASE64: Self = Self {
+        min_len: 20,
+        min_entropy: 4.5,
+    };
+    pub const HEX: Self = Self {
+        min_len: 40,
+        min_entropy: 3.0,
+    };
+
+    pub(crate) fn accepts(self, candidate: &[u8]) -> bool {
+        candidate.len() >= self.min_len && shannon_entropy(candidate) >= self.min_entropy
+    }
+}
+
+pub(crate) fn shannon_entropy(bytes: &[u8]) -> f64 {
+    if bytes.is_empty() {
+        return 0.0;
+    }
+    let mut counts = BTreeMap::<u8, usize>::new();
+    for byte in bytes {
+        *counts.entry(*byte).or_default() += 1;
+    }
+    let len = usize_to_f64(bytes.len());
+    counts
+        .values()
+        .map(|count| {
+            let p = usize_to_f64(*count) / len;
+            -p * p.log2()
+        })
+        .sum()
+}
+
+fn usize_to_f64(value: usize) -> f64 {
+    f64::from(u32::try_from(value).unwrap_or(u32::MAX))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::shannon_entropy;
+
+    #[test]
+    fn entropy_is_low_for_repetition() {
+        assert!(shannon_entropy(b"aaaaaaaaaaaaaaaaaaaaaaaa") < 0.1);
+    }
+
+    #[test]
+    fn entropy_is_higher_for_varied_alphabet() {
+        assert!(shannon_entropy(b"0123456789abcdefABCDEF+/") > 4.0);
+    }
+}
diff --git a/crates/clarion-scanner/src/lib.rs b/crates/clarion-scanner/src/lib.rs
new file mode 100644
index 00000000..ae87edb8
--- /dev/null
+++ b/crates/clarion-scanner/src/lib.rs
@@ -0,0 +1,233 @@
+//! Core-owned pre-ingest secret scanner.
+//!
+//! The scanner intentionally stores only positions, rule identifiers, and a
+//! detect-secrets-compatible SHA-1 digest of the matched bytes. Literal secret
+//! values do not leave the scanning call.
+
+mod baseline;
+mod entropy;
+mod patterns;
+
+pub use baseline::{
+    Baseline, BaselineEntry, BaselineEntryIssue, BaselineError, BaselineMatch, SuppressionResult,
+    load_baseline,
+};
+pub use entropy::EntropyTuning;
+pub use patterns::{PatternMeta, Scanner};
+use std::{
+    fmt::{self, Write as _},
+    str::FromStr,
+};
+
+/// One secret-like match in one file buffer.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Detection {
+    pub rule_id: &'static str,
+    pub detect_secrets_type: DetectSecretsRule,
+    pub category: SecretCategory,
+    pub byte_offset: usize,
+    pub line_number: u32,
+    pub matched_len: usize,
+    pub hashed_secret: HashedSecret,
+}
+
+/// High-level category used for evidence and future operator grouping.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SecretCategory {
+    CloudCredential,
+    VcsCredential,
+    AiProviderCredential,
+    PaymentsCredential,
+    MessagingCredential,
+    PrivateKey,
+    JwtToken,
+    HighEntropy,
+    ContextualCredential,
+}
+
+/// detect-secrets-compatible SHA-1 digest of the matched secret bytes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct HashedSecret([u8; 20]);
+
+impl HashedSecret {
+    #[must_use]
+    pub fn from_bytes(bytes: [u8; 20]) -> Self {
+        Self(bytes)
+    }
+
+    #[must_use]
+    pub fn as_bytes(&self) -> &[u8; 20] {
+        &self.0
+    }
+
+    pub fn from_hex(input: &str) -> Result<Self, HexDigestError> {
+        let raw = input.trim();
+        if raw.len() != 40 {
+            return Err(HexDigestError {
+                message: format!("expected 40 hex characters, got {}", raw.len()),
+            });
+        }
+        let mut out = [0u8; 20];
+        for (idx, chunk) in raw.as_bytes().chunks_exact(2).enumerate() {
+            let hi = hex_value(chunk[0]).ok_or_else(|| HexDigestError {
+                message: format!("invalid hex at byte {}", idx * 2),
+            })?;
+            let lo = hex_value(chunk[1]).ok_or_else(|| HexDigestError {
+                message: format!("invalid hex at byte {}", idx * 2 + 1),
+            })?;
+            out[idx] = (hi << 4) | lo;
+        }
+        Ok(Self(out))
+    }
+}
+
+impl fmt::Display for HashedSecret {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        const HEX: &[u8; 16] = b"0123456789abcdef";
+        for byte in self.0 {
+            f.write_char(char::from(HEX[usize::from(byte >> 4)]))?;
+            f.write_char(char::from(HEX[usize::from(byte & 0x0f)]))?;
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("{message}")]
+pub struct HexDigestError {
+    message: String,
+}
+
+/// Closed detector type vocabulary supported by Clarion's v0.1 scanner.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum DetectSecretsRule {
+    AwsAccessKey,
+    AwsSecretAccessKey,
+    GitHubToken,
+    GitHubFineGrainedToken,
+    GitHubOAuthToken,
+    AnthropicApiKey,
+    OpenAiApiKey,
+    StripeApiKey,
+    SlackToken,
+    JwtToken,
+    PrivateKey,
+    KeywordDetector,
+    Base64HighEntropyString,
+    HexHighEntropyString,
+}
+
+impl DetectSecretsRule {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::AwsAccessKey => "AWS Access Key",
+            Self::AwsSecretAccessKey => "AWS Secret Access Key",
+            Self::GitHubToken => "GitHub Token",
+            Self::GitHubFineGrainedToken => "GitHub Fine-Grained Token",
+            Self::GitHubOAuthToken => "GitHub OAuth Token",
+            Self::AnthropicApiKey => "Anthropic API Key",
+            Self::OpenAiApiKey => "OpenAI API Key",
+            Self::StripeApiKey => "Stripe API Key",
+            Self::SlackToken => "Slack Token",
+            Self::JwtToken => "JWT Token",
+            Self::PrivateKey => "Private Key",
+            Self::KeywordDetector => "Keyword Detector",
+            Self::Base64HighEntropyString => "Base64 High Entropy String",
+            Self::HexHighEntropyString => "Hex High Entropy String",
+        }
+    }
+
+    #[must_use]
+    pub fn rule_id(self) -> &'static str {
+        match self {
+            Self::AwsAccessKey => "AwsAccessKeyId",
+            Self::AwsSecretAccessKey => "AwsSecretAccessKey",
+            Self::GitHubToken => "GitHubPat",
+            Self::GitHubFineGrainedToken => "GitHubFineGrainedPat",
+            Self::GitHubOAuthToken => "GitHubOAuth",
+            Self::AnthropicApiKey => "AnthropicApiKey",
+            Self::OpenAiApiKey => "OpenAiApiKey",
+            Self::StripeApiKey => "StripeApiKey",
+            Self::SlackToken => "SlackToken",
+            Self::JwtToken => "JwtToken",
+            Self::PrivateKey => "PrivateKeyHeader",
+            Self::KeywordDetector => "ContextualCredential",
+            Self::Base64HighEntropyString => "HighEntropyBase64",
+            Self::HexHighEntropyString => "HighEntropyHex",
+        }
+    }
+}
+
+impl fmt::Display for DetectSecretsRule {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+impl FromStr for DetectSecretsRule {
+    type Err = UnknownDetectSecretsRule;
+
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value {
+            "AWS Access Key" => Ok(Self::AwsAccessKey),
+            "AWS Secret Access Key" => Ok(Self::AwsSecretAccessKey),
+            "GitHub Token" => Ok(Self::GitHubToken),
+            "GitHub Fine-Grained Token" => Ok(Self::GitHubFineGrainedToken),
+            "GitHub OAuth Token" => Ok(Self::GitHubOAuthToken),
+            "Anthropic API Key" => Ok(Self::AnthropicApiKey),
+            "OpenAI API Key" => Ok(Self::OpenAiApiKey),
+            "Stripe API Key" => Ok(Self::StripeApiKey),
+            "Slack Token" => Ok(Self::SlackToken),
+            "JWT Token" => Ok(Self::JwtToken),
+            "Private Key" => Ok(Self::PrivateKey),
+            "Keyword Detector" => Ok(Self::KeywordDetector),
+            "Base64 High Entropy String" => Ok(Self::Base64HighEntropyString),
+            "Hex High Entropy String" => Ok(Self::HexHighEntropyString),
+            _ => Err(UnknownDetectSecretsRule {
+                value: value.to_owned(),
+            }),
+        }
+    }
+}
+
+impl TryFrom<&str> for DetectSecretsRule {
+    type Error = UnknownDetectSecretsRule;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::from_str(value)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("unsupported detector type {value:?}")]
+pub struct UnknownDetectSecretsRule {
+    value: String,
+}
+
+fn sha1_digest(bytes: &[u8]) -> HashedSecret {
+    use sha1::{Digest, Sha1};
+
+    let mut hasher = Sha1::new();
+    hasher.update(bytes);
+    HashedSecret(hasher.finalize().into())
+}
+
+fn line_number_for_offset(buf: &[u8], offset: usize) -> u32 {
+    let line = buf
+        .get(..offset.min(buf.len()))
+        .unwrap_or(buf)
+        .iter()
+        .fold(0usize, |count, byte| count + usize::from(*byte == b'\n'))
+        + 1;
+    u32::try_from(line).unwrap_or(u32::MAX)
+}
+
+fn hex_value(byte: u8) -> Option<u8> {
+    match byte {
+        b'0'..=b'9' => Some(byte - b'0'),
+        b'a'..=b'f' => Some(byte - b'a' + 10),
+        b'A'..=b'F' => Some(byte - b'A' + 10),
+        _ => None,
+    }
+}
diff --git a/crates/clarion-scanner/src/patterns.rs b/crates/clarion-scanner/src/patterns.rs
new file mode 100644
index 00000000..bb4671de
--- /dev/null
+++ b/crates/clarion-scanner/src/patterns.rs
@@ -0,0 +1,303 @@
+use regex::bytes::{Regex, RegexSet};
+
+use crate::{
+    DetectSecretsRule, Detection, SecretCategory, entropy::EntropyTuning, line_number_for_offset,
+    sha1_digest,
+};
+
+/// Metadata for one named secret detector.
+#[derive(Debug, Clone)]
+pub struct PatternMeta {
+    pub detect_secrets_type: DetectSecretsRule,
+    pub category: SecretCategory,
+    pub pattern: &'static str,
+    capture_group: Option<usize>,
+}
+
+#[derive(Debug)]
+struct CompiledPattern {
+    meta: PatternMeta,
+    regex: Regex,
+}
+
+/// Rust-native port of the ADR-013 v0.1 secret rule floor.
+#[derive(Debug)]
+pub struct Scanner {
+    patterns: RegexSet,
+    pattern_meta: Vec<PatternMeta>,
+    compiled_patterns: Vec<CompiledPattern>,
+    entropy_b64: EntropyTuning,
+    entropy_hex: EntropyTuning,
+    entropy_b64_re: Regex,
+    entropy_hex_re: Regex,
+}
+
+impl Default for Scanner {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Scanner {
+    /// Build the default ADR-013 scanner.
+    ///
+    /// # Panics
+    ///
+    /// Panics only if one of the compiled-in regular expressions is invalid.
+    #[must_use]
+    pub fn new() -> Self {
+        let pattern_meta = default_pattern_meta();
+        let patterns = RegexSet::new(pattern_meta.iter().map(|meta| meta.pattern))
+            .expect("default secret patterns compile");
+        let compiled_patterns = pattern_meta
+            .iter()
+            .cloned()
+            .map(|meta| CompiledPattern {
+                regex: Regex::new(meta.pattern).expect("default secret pattern compiles"),
+                meta,
+            })
+            .collect();
+        Self {
+            patterns,
+            pattern_meta,
+            compiled_patterns,
+            entropy_b64: EntropyTuning::BASE64,
+            entropy_hex: EntropyTuning::HEX,
+            entropy_b64_re: Regex::new(r"[A-Za-z0-9+/]{20,}={0,2}")
+                .expect("base64 candidate regex compiles"),
+            entropy_hex_re: Regex::new(r"\b[a-fA-F0-9]{40,}\b")
+                .expect("hex candidate regex compiles"),
+        }
+    }
+
+    #[must_use]
+    pub fn pattern_meta(&self) -> &[PatternMeta] {
+        &self.pattern_meta
+    }
+
+    #[must_use]
+    pub fn scan_bytes(&self, buf: &[u8]) -> Vec<Detection> {
+        let set_matches = self.patterns.matches(buf);
+        let mut detections = Vec::new();
+
+        for (idx, compiled) in self.compiled_patterns.iter().enumerate() {
+            if !set_matches.matched(idx) {
+                continue;
+            }
+            for captures in compiled.regex.captures_iter(buf) {
+                let Some(whole_match) = captures.get(0) else {
+                    continue;
+                };
+                if compiled.meta.category == SecretCategory::ContextualCredential
+                    && line_is_comment(buf, whole_match.start())
+                {
+                    continue;
+                }
+                let Some(secret_match) = compiled
+                    .meta
+                    .capture_group
+                    .and_then(|group| captures.get(group))
+                    .or(Some(whole_match))
+                else {
+                    continue;
+                };
+                detections.push(detection_from_match(
+                    &compiled.meta,
+                    buf,
+                    secret_match.start(),
+                    secret_match.end(),
+                ));
+            }
+        }
+
+        let named_ranges = detections
+            .iter()
+            .map(|detection| {
+                (
+                    detection.byte_offset,
+                    detection.byte_offset + detection.matched_len,
+                )
+            })
+            .collect::<Vec<_>>();
+        self.scan_entropy(buf, &named_ranges, &mut detections);
+
+        detections.sort_by_key(|d| (d.byte_offset, d.rule_id));
+        detections
+    }
+
+    fn scan_entropy(
+        &self,
+        bytes: &[u8],
+        named_ranges: &[(usize, usize)],
+        detections: &mut Vec<Detection>,
+    ) {
+        for candidate in self.entropy_b64_re.find_iter(bytes) {
+            let candidate_bytes = &bytes[candidate.start()..candidate.end()];
+            if base64_candidate_has_boundaries(bytes, candidate.start(), candidate.end())
+                && !range_overlaps(candidate.start(), candidate.end(), named_ranges)
+                && self.entropy_b64.accepts(candidate_bytes)
+            {
+                detections.push(entropy_detection(
+                    DetectSecretsRule::Base64HighEntropyString,
+                    bytes,
+                    candidate.start(),
+                    candidate.end(),
+                ));
+            }
+        }
+        for candidate in self.entropy_hex_re.find_iter(bytes) {
+            let candidate_bytes = &bytes[candidate.start()..candidate.end()];
+            if !range_overlaps(candidate.start(), candidate.end(), named_ranges)
+                && self.entropy_hex.accepts(candidate_bytes)
+            {
+                detections.push(entropy_detection(
+                    DetectSecretsRule::HexHighEntropyString,
+                    bytes,
+                    candidate.start(),
+                    candidate.end(),
+                ));
+            }
+        }
+    }
+}
+
+fn detection_from_match(meta: &PatternMeta, bytes: &[u8], start: usize, end: usize) -> Detection {
+    let matched = &bytes[start..end];
+    Detection {
+        rule_id: meta.detect_secrets_type.rule_id(),
+        detect_secrets_type: meta.detect_secrets_type,
+        category: meta.category,
+        byte_offset: start,
+        line_number: line_number_for_offset(bytes, start),
+        matched_len: end.saturating_sub(start),
+        hashed_secret: sha1_digest(matched),
+    }
+}
+
+fn entropy_detection(
+    detect_secrets_type: DetectSecretsRule,
+    bytes: &[u8],
+    start: usize,
+    end: usize,
+) -> Detection {
+    Detection {
+        rule_id: detect_secrets_type.rule_id(),
+        detect_secrets_type,
+        category: SecretCategory::HighEntropy,
+        byte_offset: start,
+        line_number: line_number_for_offset(bytes, start),
+        matched_len: end.saturating_sub(start),
+        hashed_secret: sha1_digest(&bytes[start..end]),
+    }
+}
+
+fn default_pattern_meta() -> Vec<PatternMeta> {
+    vec![
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::AwsAccessKey,
+            category: SecretCategory::CloudCredential,
+            pattern: r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::AwsSecretAccessKey,
+            category: SecretCategory::CloudCredential,
+            pattern: r#"(?i)\baws[^:=\n]{0,32}(?:secret|access)[^:=\n]{0,32}(?:=|:|:=)\s*["']?([A-Za-z0-9/+=]{40})["']?"#,
+            capture_group: Some(1),
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::GitHubToken,
+            category: SecretCategory::VcsCredential,
+            pattern: r"\bghp_[A-Za-z0-9]{36}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::GitHubFineGrainedToken,
+            category: SecretCategory::VcsCredential,
+            pattern: r"\bgithub_pat_[A-Za-z0-9_]{82,}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::GitHubOAuthToken,
+            category: SecretCategory::VcsCredential,
+            pattern: r"\bgh[ousr]_[A-Za-z0-9]{36}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::AnthropicApiKey,
+            category: SecretCategory::AiProviderCredential,
+            pattern: r"\bsk-ant-[A-Za-z0-9_-]{90,}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::OpenAiApiKey,
+            category: SecretCategory::AiProviderCredential,
+            pattern: r"\bsk-(?:[A-Za-z0-9]{48}|(?:proj|svcacct)-[A-Za-z0-9_-]{20,})\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::StripeApiKey,
+            category: SecretCategory::PaymentsCredential,
+            pattern: r"\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::SlackToken,
+            category: SecretCategory::MessagingCredential,
+            pattern: r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::JwtToken,
+            category: SecretCategory::JwtToken,
+            pattern: r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::PrivateKey,
+            category: SecretCategory::PrivateKey,
+            pattern: r"-----BEGIN (?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED) PRIVATE KEY|PRIVATE KEY|PGP PRIVATE KEY BLOCK)-----",
+            capture_group: None,
+        },
+        PatternMeta {
+            detect_secrets_type: DetectSecretsRule::KeywordDetector,
+            category: SecretCategory::ContextualCredential,
+            pattern: r#"(?i)(?:^|[^A-Za-z0-9_-])(?:password|passwd|secret[_-]?token|secret|token|api[_-]?key)\s*(?:=|:=|:)\s*["']([^"'\s]{8,})["']"#,
+            capture_group: Some(1),
+        },
+    ]
+}
+
+fn range_overlaps(start: usize, end: usize, ranges: &[(usize, usize)]) -> bool {
+    ranges
+        .iter()
+        .any(|(range_start, range_end)| start < *range_end && end > *range_start)
+}
+
+fn base64_candidate_has_boundaries(bytes: &[u8], start: usize, end: usize) -> bool {
+    let before_ok = start == 0 || !is_base64_candidate_byte(bytes[start - 1]);
+    let after_ok = end == bytes.len() || !is_base64_candidate_byte(bytes[end]);
+    before_ok && after_ok
+}
+
+fn is_base64_candidate_byte(byte: u8) -> bool {
+    matches!(
+        byte,
+        b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'+' | b'/' | b'='
+    )
+}
+
+fn line_is_comment(bytes: &[u8], offset: usize) -> bool {
+    // ADR-013's v0.1 rule floor is Python/.env-first, so only shell/Python
+    // `#` comments are ignored here. Other language comment forms should use
+    // an explicit baseline entry until their detector context is added.
+    let line_start = bytes
+        .get(..offset.min(bytes.len()))
+        .and_then(|prefix| prefix.iter().rposition(|byte| *byte == b'\n'))
+        .map_or(0, |pos| pos + 1);
+    bytes[line_start..offset.min(bytes.len())]
+        .iter()
+        .copied()
+        .find(|byte| !byte.is_ascii_whitespace())
+        == Some(b'#')
+}
diff --git a/crates/clarion-scanner/tests/scanner.rs b/crates/clarion-scanner/tests/scanner.rs
new file mode 100644
index 00000000..936a8531
--- /dev/null
+++ b/crates/clarion-scanner/tests/scanner.rs
@@ -0,0 +1,655 @@
+use clarion_scanner::{
+    Baseline, BaselineError, DetectSecretsRule, EntropyTuning, HashedSecret, Scanner, load_baseline,
+};
+use sha1::{Digest, Sha1};
+
+fn rules_for(input: &str) -> Vec<&'static str> {
+    Scanner::new()
+        .scan_bytes(input.as_bytes())
+        .into_iter()
+        .map(|detection| detection.rule_id)
+        .collect()
+}
+
+fn assert_detects(input: &str, rule_id: &str) {
+    let rules = rules_for(input);
+    assert!(rules.contains(&rule_id), "{rule_id} not found in {rules:?}");
+}
+
+fn assert_not_detects(input: &str, rule_id: &str) {
+    let rules = rules_for(input);
+    assert!(
+        !rules.contains(&rule_id),
+        "{rule_id} unexpectedly found in {rules:?}"
+    );
+}
+
+#[test]
+fn detect_secrets_rule_owns_rule_id_strings() {
+    assert_eq!(DetectSecretsRule::AwsAccessKey.rule_id(), "AwsAccessKeyId");
+    assert_eq!(DetectSecretsRule::OpenAiApiKey.rule_id(), "OpenAiApiKey");
+    assert_eq!(
+        DetectSecretsRule::Base64HighEntropyString.rule_id(),
+        "HighEntropyBase64"
+    );
+}
+
+#[test]
+fn named_patterns_detect_expected_credentials() {
+    assert_detects(
+        "aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'",
+        "AwsAccessKeyId",
+    );
+    assert_detects(
+        "aws_secret_access_key = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'",
+        "AwsSecretAccessKey",
+    );
+    assert_detects(
+        "token = 'ghp_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ'",
+        "GitHubPat",
+    );
+    assert_detects(
+        &format!("token = 'github_pat_{}'", "a".repeat(82)),
+        "GitHubFineGrainedPat",
+    );
+    assert_detects(
+        "token = 'gho_abcdefghijklmnopqrstuvwxyzABCDEFGHIJ'",
+        "GitHubOAuth",
+    );
+    assert_detects(
+        &format!("key = 'sk-ant-{}'", "A".repeat(90)),
+        "AnthropicApiKey",
+    );
+    assert_detects(&format!("key = 'sk-{}'", "A".repeat(48)), "OpenAiApiKey");
+    assert_detects(
+        &format!("key = 'sk-proj-{}'", "A_b-".repeat(16)),
+        "OpenAiApiKey",
+    );
+    assert_detects(
+        &format!("key = 'sk-svcacct-{}'", "Z_y-".repeat(16)),
+        "OpenAiApiKey",
+    );
+    assert_detects("stripe = 'sk_live_abcdefghijklmnop'", "StripeApiKey");
+    assert_detects("slack = 'xoxb-123456789012-abcdefghi'", "SlackToken");
+    assert_detects(
+        "jwt = 'eyJabcdef12345.eyJabcdef67890.eyJabcdef99999'",
+        "JwtToken",
+    );
+    assert_detects("-----BEGIN RSA PRIVATE KEY-----", "PrivateKeyHeader");
+    assert_detects("-----BEGIN DSA PRIVATE KEY-----", "PrivateKeyHeader");
+    assert_detects("-----BEGIN OPENSSH PRIVATE KEY-----", "PrivateKeyHeader");
+    assert_detects("-----BEGIN PRIVATE KEY-----", "PrivateKeyHeader");
+    assert_detects("-----BEGIN PGP PRIVATE KEY BLOCK-----", "PrivateKeyHeader");
+}
+
+#[test]
+fn named_patterns_ignore_near_misses() {
+    assert_not_detects("AKIAIOSFODNN7EXAMPL", "AwsAccessKeyId");
+    assert_not_detects("ghp_short", "GitHubPat");
+    assert_not_detects("sk-not-long-enough", "OpenAiApiKey");
+    assert_not_detects("-----BEGIN PUBLIC KEY-----", "PrivateKeyHeader");
+}
+
+#[test]
+fn entropy_detection_has_expected_bounds() {
+    assert_detects(
+        "secret = AbCdEfGhIjKlMnOpQrStUvWxYz123456+/",
+        "HighEntropyBase64",
+    );
+    assert_detects(
+        "digest = 0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdef",
+        "HighEntropyHex",
+    );
+    assert_not_detects(
+        "uuid = 123e4567-e89b-12d3-a456-426614174000",
+        "HighEntropyHex",
+    );
+    assert_detects(
+        "checksum = 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
+        "HighEntropyBase64",
+    );
+}
+
+#[test]
+fn padded_base64_detection_hashes_the_full_literal_for_baselines() {
+    let secret = "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=";
+    let source = format!("checksum = {secret}\n");
+    let detections = Scanner::new().scan_bytes(source.as_bytes());
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "HighEntropyBase64")
+        .expect("padded base64 detection")
+        .clone();
+
+    assert_eq!(detection.matched_len, secret.len());
+    assert_eq!(hex20(detection.hashed_secret), sha1_hex(secret.as_bytes()));
+
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "src/checksums.txt":
+    - type: "Base64 High Entropy String"
+      hashed_secret: "{}"
+      line_number: 1
+      is_secret: false
+      justification: "Known non-secret digest checked into the fixture."
+"#,
+        sha1_hex(secret.as_bytes())
+    ))
+    .expect("baseline parses");
+
+    let result = baseline.suppress(detections, std::path::Path::new("src/checksums.txt"));
+    assert!(result.allowed.is_empty());
+    assert_eq!(result.suppressed.len(), 1);
+}
+
+#[test]
+fn contextual_credentials_detect_assignments_but_not_comments_or_hashes() {
+    assert_detects(
+        "password = \"correct-horse-battery-staple\"",
+        "ContextualCredential",
+    );
+    assert_detects("api_key: \"abcDEF1234567890\"", "ContextualCredential");
+    assert_detects(
+        "SECRET_TOKEN := \"abcDEF1234567890\"",
+        "ContextualCredential",
+    );
+    assert_not_detects(
+        "password_hash = \"abcDEF1234567890\"",
+        "ContextualCredential",
+    );
+    assert_not_detects("# password = \"abcDEF1234567890\"", "ContextualCredential");
+    assert_detects("// password = \"abcDEF1234567890\"", "ContextualCredential");
+    assert_detects(
+        "/* password = \"abcDEF1234567890\" */",
+        "ContextualCredential",
+    );
+}
+
+#[test]
+fn entropy_minimum_lengths_are_pinned() {
+    assert_eq!(EntropyTuning::BASE64.min_len, 20);
+    assert_eq!(EntropyTuning::HEX.min_len, 40);
+}
+
+#[test]
+fn detection_records_line_and_sha1_hash_without_literal() {
+    let detections = Scanner::new().scan_bytes(b"clean\nkey = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS key detection");
+    assert_eq!(detection.line_number, 2);
+    assert_eq!(detection.matched_len, "AKIAIOSFODNN7EXAMPLE".len());
+    assert_ne!(detection.hashed_secret.as_bytes(), &[0u8; 20]);
+}
+
+#[test]
+fn hashed_secret_round_trips_hex_display() {
+    let hash = HashedSecret::from_hex("0123456789abcdef0123456789abcdef01234567")
+        .expect("valid SHA-1 hex");
+
+    assert_eq!(hash.to_string(), "0123456789abcdef0123456789abcdef01234567");
+    assert!(HashedSecret::from_hex("not-a-sha1").is_err());
+}
+
+#[test]
+fn scan_bytes_reports_offsets_in_original_non_utf8_buffer() {
+    let input = b"\xff\xffkey = 'AKIAIOSFODNN7EXAMPLE'\n";
+    let detections = Scanner::new().scan_bytes(input);
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS key detection");
+    let expected_offset = input
+        .windows(b"AKIAIOSFODNN7EXAMPLE".len())
+        .position(|window| window == b"AKIAIOSFODNN7EXAMPLE")
+        .expect("secret literal is in fixture");
+
+    assert_eq!(detection.byte_offset, expected_offset);
+    assert_eq!(
+        hex20(detection.hashed_secret),
+        sha1_hex(b"AKIAIOSFODNN7EXAMPLE")
+    );
+}
+
+#[test]
+fn baseline_suppresses_matching_detection_and_reports_fired_entry() {
+    let scanner = Scanner::new();
+    let detections = scanner.scan_bytes(b"key = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection")
+        .clone();
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "{}"
+      line_number: 1
+      is_secret: false
+      justification: "Documented public AWS example key."
+"#,
+        hex20(detection.hashed_secret)
+    ))
+    .expect("baseline parses");
+
+    let result = baseline.suppress(detections, std::path::Path::new("src/demo.py"));
+    assert!(result.allowed.is_empty());
+    assert_eq!(result.suppressed.len(), 1);
+    assert_eq!(result.fired_entries.len(), 1);
+}
+
+#[test]
+fn baseline_does_not_suppress_when_detector_type_differs() {
+    let scanner = Scanner::new();
+    let detections = scanner.scan_bytes(b"key = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection")
+        .clone();
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "GitHub Token"
+      hashed_secret: "{}"
+      line_number: 1
+      is_secret: false
+      justification: "Different detector type must not suppress this match."
+"#,
+        hex20(detection.hashed_secret)
+    ))
+    .expect("baseline parses");
+
+    let result = baseline.suppress(detections, std::path::Path::new("src/demo.py"));
+    assert_eq!(result.allowed.len(), 1);
+    assert!(result.suppressed.is_empty());
+    assert!(result.fired_entries.is_empty());
+}
+
+#[test]
+fn baseline_rejects_unknown_detector_types() {
+    let err = Baseline::from_yaml_str(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Acceess Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 42
+      is_secret: false
+      justification: "Typo should not silently lose suppression."
+"#,
+    )
+    .expect_err("unknown detector type should fail");
+
+    assert!(
+        err.to_string().contains("unsupported detector type"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn baseline_without_explicit_is_secret_false_does_not_suppress() {
+    let scanner = Scanner::new();
+    let detections = scanner.scan_bytes(b"key = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection")
+        .clone();
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "{}"
+      line_number: 1
+      justification: "The operator did not explicitly mark this as not secret."
+"#,
+        hex20(detection.hashed_secret)
+    ))
+    .expect("baseline parses");
+
+    let result = baseline.suppress(detections, std::path::Path::new("src/demo.py"));
+    assert_eq!(result.allowed.len(), 1);
+    assert!(result.suppressed.is_empty());
+    assert!(result.fired_entries.is_empty());
+}
+
+#[test]
+fn baseline_does_not_suppress_same_suffix_in_sibling_directory() {
+    let scanner = Scanner::new();
+    let detections = scanner.scan_bytes(b"key = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection")
+        .clone();
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "{}"
+      line_number: 1
+      is_secret: false
+      justification: "Only src/demo.py was reviewed."
+"#,
+        hex20(detection.hashed_secret)
+    ))
+    .expect("baseline parses");
+
+    let result = baseline.suppress(detections, std::path::Path::new("vendor/src/demo.py"));
+    assert_eq!(result.allowed.len(), 1);
+    assert!(result.suppressed.is_empty());
+    assert!(result.fired_entries.is_empty());
+}
+
+#[test]
+fn baseline_is_secret_true_does_not_suppress() {
+    let scanner = Scanner::new();
+    let detections = scanner.scan_bytes(b"key = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let detection = detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection")
+        .clone();
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "{}"
+      line_number: 1
+      is_secret: true
+      justification: "Still a real secret."
+"#,
+        hex20(detection.hashed_secret)
+    ))
+    .expect("baseline parses");
+
+    let result = baseline.suppress(detections, std::path::Path::new("demo.py"));
+    assert_eq!(result.allowed.len(), 1);
+    assert!(result.suppressed.is_empty());
+}
+
+#[test]
+fn baseline_missing_justification_errors() {
+    let err = Baseline::from_yaml_str(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 42
+      is_secret: false
+"#,
+    )
+    .expect_err("missing justification should fail");
+    let BaselineError::MissingJustifications { entries } = err else {
+        panic!("expected MissingJustifications, got {err:?}");
+    };
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].line, 42);
+}
+
+#[test]
+fn baseline_missing_justification_reports_all_entries() {
+    let err = Baseline::from_yaml_str(
+        r#"
+version: "1.0"
+results:
+  "src/one.py":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 4
+      is_secret: false
+  "src/two.py":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 8
+      is_secret: false
+"#,
+    )
+    .expect_err("all missing justifications should be reported");
+    let BaselineError::MissingJustifications { entries } = err else {
+        panic!("expected MissingJustifications, got {err:?}");
+    };
+    assert_eq!(entries.len(), 2);
+    assert_eq!(entries[0].line, 4);
+    assert_eq!(entries[1].line, 8);
+}
+
+#[test]
+fn baseline_rejects_absolute_result_paths() {
+    let err = Baseline::from_yaml_str(
+        r#"
+version: "1.0"
+results:
+  "/tmp/secret.py":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 4
+      is_secret: false
+      justification: "Invalid path must not be accepted."
+"#,
+    )
+    .expect_err("absolute baseline path should fail");
+    assert!(
+        err.to_string().contains("repository-relative"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn baseline_rejects_parent_dir_result_paths() {
+    let err = Baseline::from_yaml_str(
+        r#"
+version: "1.0"
+results:
+  "../secret.py":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 4
+      is_secret: false
+      justification: "Invalid path must not be accepted."
+"#,
+    )
+    .expect_err("escaping baseline path should fail");
+    assert!(
+        err.to_string().contains("repository-relative"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn absent_baseline_file_is_empty() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let baseline = load_baseline(&dir.path().join(".clarion/secrets-baseline.yaml"))
+        .expect("missing baseline is accepted");
+    assert!(baseline.entries().is_empty());
+}
+
+#[test]
+fn baseline_round_trips_through_yaml() {
+    let raw = r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "0123456789abcdef0123456789abcdef01234567"
+      line_number: 42
+      is_secret: false
+      justification: "Example key."
+"#;
+    let parsed = Baseline::from_yaml_str(raw).expect("parse baseline");
+    let rendered = parsed.to_yaml_string().expect("serialize baseline");
+    let reparsed = Baseline::from_yaml_str(&rendered).expect("reparse baseline");
+    assert_eq!(parsed, reparsed);
+}
+
+/// Regression net for the gap noted in PR #11 review (clarion-55fc5aa885 §I6):
+/// baseline suppression keys on (`hashed_secret`, `line_number`, `rule_type`).
+/// A baseline entry at line 1 with one hash MUST NOT suppress a *different*
+/// detection at line 1 — that would be a silent regression where a benign
+/// stub gets replaced by a real secret at the same offset and the gate
+/// stops firing.
+#[test]
+fn baseline_does_not_suppress_when_hash_drifts_at_same_line() {
+    let scanner = Scanner::new();
+    // Original benign content the operator baselined.
+    let benign_detections = scanner.scan_bytes(b"key = 'AKIAIOSFODNN7EXAMPLE'\n");
+    let benign = benign_detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection in benign content")
+        .clone();
+    // Operator commits a baseline acknowledging the benign secret on line 1.
+    let baseline = Baseline::from_yaml_str(&format!(
+        r#"
+version: "1.0"
+results:
+  "src/demo.py":
+    - type: "AWS Access Key"
+      hashed_secret: "{}"
+      line_number: 1
+      is_secret: false
+      justification: "Documented public AWS example key."
+"#,
+        hex20(benign.hashed_secret)
+    ))
+    .expect("baseline parses");
+
+    // Later, the file is mutated: same line, same rule, *different* secret.
+    let drifted_detections = scanner.scan_bytes(b"key = 'AKIAJONOTTHESAMEAS18'\n");
+    let drifted = drifted_detections
+        .iter()
+        .find(|detection| detection.rule_id == "AwsAccessKeyId")
+        .expect("AWS detection in drifted content")
+        .clone();
+    assert_ne!(
+        benign.hashed_secret, drifted.hashed_secret,
+        "test premise: drifted content must hash differently",
+    );
+
+    let result = baseline.suppress(vec![drifted], std::path::Path::new("src/demo.py"));
+    assert_eq!(
+        result.allowed.len(),
+        1,
+        "baseline must NOT suppress a drifted hash at the same line — that is \
+         the security regression CLA-SEC-SECRET-DETECTED exists to catch",
+    );
+    assert!(result.suppressed.is_empty());
+    assert!(result.fired_entries.is_empty());
+}
+
+/// Regression net for the gap noted in PR #11 review (clarion-55fc5aa885 §I7):
+/// `HighEntropyHex` at 40 chars / entropy ≥ 3.0 will fire on git SHA-1 hashes,
+/// blake3 hex digests, and lockfile integrity fields. The accepted v0.1 path
+/// is *not* to tighten the rule (which would let real low-entropy secrets
+/// through) but to document the operator-baseline workflow as the
+/// resolution — exactly what this fixture asserts.
+///
+/// Tightening the entropy floor risks missing real secrets that happen to
+/// look hash-like; the baseline path is per-(rule,file,line,hash) and is the
+/// existing escape hatch ADR-013 §"Operator baseline" describes.
+#[test]
+fn high_entropy_hex_fires_on_lockfile_shas_but_baseline_suppresses_them() {
+    // Lockfile integrity hash (npm-style sha512-truncated to hex) and a git
+    // SHA-1. Both are 40-char hex, entropy ≈ log2(16) ≈ 4 — well above the
+    // HighEntropyHex floor.
+    let lockfile_payload = b"\"integrity\": \"a3f5e8c2b1d4f0967e8c2a1b5d3e0f4a6c8b2d1e\"";
+    let git_sha = b"commit a3f5e8c2b1d4f0967e8c2a1b5d3e0f4a6c8b2d1e\n";
+
+    let scanner = Scanner::new();
+    let lockfile_detections = scanner.scan_bytes(lockfile_payload);
+    let git_detections = scanner.scan_bytes(git_sha);
+    let lockfile_hex = lockfile_detections
+        .iter()
+        .find(|detection| detection.rule_id == "HighEntropyHex")
+        .cloned();
+    let git_hex = git_detections
+        .iter()
+        .find(|detection| detection.rule_id == "HighEntropyHex")
+        .cloned();
+
+    let lockfile_hex = lockfile_hex.expect(
+        "HighEntropyHex fires on lockfile integrity hash — the regression \
+         net is the operator-baseline workflow, not a tightened rule",
+    );
+    let git_hex = git_hex.expect(
+        "HighEntropyHex fires on git SHA-1 — the regression net is the \
+         operator-baseline workflow, not a tightened rule",
+    );
+
+    // Operator commits a baseline pinning both the lockfile and git SHA on
+    // their respective files. The same workflow scales to blake3 hex
+    // digests and any other hash-like content.
+    let baseline_yaml = format!(
+        r#"
+version: "1.0"
+results:
+  "package-lock.json":
+    - type: "Hex High Entropy String"
+      hashed_secret: "{lock_hash}"
+      line_number: 1
+      is_secret: false
+      justification: "npm lockfile integrity hash, not a credential."
+  "git-log.txt":
+    - type: "Hex High Entropy String"
+      hashed_secret: "{git_hash}"
+      line_number: 1
+      is_secret: false
+      justification: "Git commit SHA, not a credential."
+"#,
+        lock_hash = hex20(lockfile_hex.hashed_secret),
+        git_hash = hex20(git_hex.hashed_secret),
+    );
+    let baseline = Baseline::from_yaml_str(&baseline_yaml).expect("baseline parses");
+
+    let lockfile_result = baseline.suppress(
+        vec![lockfile_hex],
+        std::path::Path::new("package-lock.json"),
+    );
+    let git_result = baseline.suppress(vec![git_hex], std::path::Path::new("git-log.txt"));
+
+    assert!(
+        lockfile_result.allowed.is_empty(),
+        "operator-baseline must suppress the lockfile integrity-hash false positive",
+    );
+    assert!(
+        git_result.allowed.is_empty(),
+        "operator-baseline must suppress the git SHA false positive",
+    );
+    assert_eq!(lockfile_result.fired_entries.len(), 1);
+    assert_eq!(git_result.fired_entries.len(), 1);
+}
+
+fn hex20(hash: HashedSecret) -> String {
+    hash.to_string()
+}
+
+fn sha1_hex(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut hasher = Sha1::new();
+    hasher.update(bytes);
+    let digest = hasher.finalize();
+    let mut out = String::new();
+    for byte in digest {
+        out.push(char::from(HEX[usize::from(byte >> 4)]));
+        out.push(char::from(HEX[usize::from(byte & 0x0f)]));
+    }
+    out
+}
diff --git a/crates/clarion-storage/Cargo.toml b/crates/clarion-storage/Cargo.toml
index f8626885..69b4d0a5 100644
--- a/crates/clarion-storage/Cargo.toml
+++ b/crates/clarion-storage/Cargo.toml
@@ -10,9 +10,11 @@ rust-version.workspace = true
 workspace = true
 
 [dependencies]
-clarion-core = { path = "../clarion-core", version = "0.1.0-dev" }
+blake3.workspace = true
+clarion-core = { path = "../clarion-core", version = "1.0.0" }
 deadpool-sqlite.workspace = true
 rusqlite.workspace = true
+serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
 tokio.workspace = true
diff --git a/crates/clarion-storage/migrations/0001_initial_schema.sql b/crates/clarion-storage/migrations/0001_initial_schema.sql
index 19727874..49cdeb2c 100644
--- a/crates/clarion-storage/migrations/0001_initial_schema.sql
+++ b/crates/clarion-storage/migrations/0001_initial_schema.sql
@@ -1,7 +1,7 @@
 -- ============================================================================
 -- Clarion migration 0001 — initial schema.
 --
--- Source: docs/clarion/v0.1/detailed-design.md §3 (Storage Implementation).
+-- Source: docs/clarion/1.0/detailed-design.md §3 (Storage Implementation).
 -- Sprint 1 walking skeleton writes only to `entities` and `runs`, but every
 -- table, FTS5 virtual table, trigger, generated column, and view is created
 -- here so the full shape is frozen at L1-lock time. See ADR-011 for the
@@ -11,9 +11,10 @@
 -- as long as no external operator has produced a `.clarion/clarion.db` from
 -- a published Clarion build. The retirement trigger names exactly that
 -- condition; once it fires, all schema changes stack as 0002_*.sql etc.
--- The 2026-05-03 edits (guidance vocabulary rename per ADR-024) and the
+-- The 2026-05-03 edits (guidance vocabulary rename per ADR-024), the
 -- 2026-05-18 edits (CHECK constraints on closed-vocabulary TEXT columns per
--- ADR-031) were both applied under this policy.
+-- ADR-031), and the 2026-05-24 edit (summary_cache.entity_id FK per
+-- V11-STO-03) were all applied under this policy.
 -- ============================================================================
 
 BEGIN;
@@ -140,7 +141,12 @@ CREATE INDEX ix_findings_status    ON findings(status);
 
 -- Summary cache
 CREATE TABLE summary_cache (
-    entity_id             TEXT NOT NULL,
+    -- FK matches the sibling caches (inferred_edge_cache.caller_entity_id,
+    -- entity_unresolved_call_sites.caller_entity_id). Added in-place per
+    -- ADR-024 on 2026-05-24 (V11-STO-03 closure) — the prior absence was a
+    -- bug, not intentional asymmetry. ON DELETE CASCADE so removing an
+    -- entity (re-analyze, rename) clears its cached summaries.
+    entity_id             TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
     content_hash          TEXT NOT NULL,
     prompt_template_id    TEXT NOT NULL,
     model_tier            TEXT NOT NULL,
@@ -261,6 +267,11 @@ ALTER TABLE entities ADD COLUMN git_churn_count INTEGER
     GENERATED ALWAYS AS (json_extract(properties, '$.git_churn_count')) VIRTUAL;
 CREATE INDEX ix_entities_churn ON entities(git_churn_count) WHERE git_churn_count IS NOT NULL;
 
+-- NOTE: the `briefing_blocked` generated column + partial index live in
+-- migration 0002, NOT here. They were briefly added in place to 0001, which
+-- meant existing databases already stamped at schema_migrations.version=1
+-- skipped them; 0002 adds them on upgrade. Do not move them back.
+
 -- View for guidance resolver. detailed-design.md §3 references a bare `tags`
 -- column on `entities` that does not exist under the normalised tag schema;
 -- the view aggregates entity_tags via a correlated subquery to produce the
diff --git a/crates/clarion-storage/migrations/0002_briefing_blocked.sql b/crates/clarion-storage/migrations/0002_briefing_blocked.sql
new file mode 100644
index 00000000..ab14e8b0
--- /dev/null
+++ b/crates/clarion-storage/migrations/0002_briefing_blocked.sql
@@ -0,0 +1,31 @@
+-- Migration 0002: briefing_blocked generated column + partial index (ADR-024).
+--
+-- Originally added in place to 0001, which meant databases already stamped at
+-- schema_migrations.version=1 never received the column — project_status then
+-- hit `no such column: entities.briefing_blocked`. Shipping it as a distinct
+-- migration lets the runner apply it to existing v1 databases on upgrade.
+--
+-- briefing_blocked is a secret-scan-set property that withholds an entity from
+-- briefings / federation exposure. Promoting it to a generated column + partial
+-- index lets the federation read-API hot path filter blocked entities in SQL
+-- instead of parsing every row's properties JSON. NULL when absent (the common
+-- case), so the partial index stays small.
+
+-- Wrapped in a single transaction (mirroring 0001) so the ALTER, the index,
+-- and the migration record commit together. Without this, an interruption
+-- after the ALTER but before the version row is written leaves the column in
+-- place with no schema_migrations.version=2 row; the next startup reruns the
+-- ALTER and dies on a duplicate-column error, blocking upgrade.
+BEGIN;
+
+ALTER TABLE entities ADD COLUMN briefing_blocked TEXT
+    GENERATED ALWAYS AS (json_extract(properties, '$.briefing_blocked')) VIRTUAL;
+CREATE INDEX ix_entities_briefing_blocked ON entities(briefing_blocked)
+    WHERE briefing_blocked IS NOT NULL;
+
+-- Record the migration inside the same transaction (defence-in-depth: the
+-- runner's INSERT OR IGNORE in apply_one then no-ops). Matches 0001.
+INSERT INTO schema_migrations (version, name, applied_at)
+VALUES (2, '0002_briefing_blocked', strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+
+COMMIT;
diff --git a/crates/clarion-storage/src/commands.rs b/crates/clarion-storage/src/commands.rs
index 7e609f16..8566d400 100644
--- a/crates/clarion-storage/src/commands.rs
+++ b/crates/clarion-storage/src/commands.rs
@@ -145,6 +145,14 @@ pub enum WriterCmd {
         started_at: String,
         ack: Ack<()>,
     },
+    /// Reopen an existing run row for the `--resume` path (REQ-FINDING-05).
+    /// `BeginRun` does an `INSERT` that conflicts on the run PK when handed an
+    /// id that already exists; `ResumeRun` instead `UPDATE`s the row back to
+    /// `running` (clearing `completed_at`), then binds it as the active run and
+    /// opens the write transaction exactly as `BeginRun` does. Errors if no row
+    /// with `run_id` exists. A re-walk upserts entities/edges idempotently, so
+    /// a resumed run reproduces the same durable graph as the original.
+    ResumeRun { run_id: String, ack: Ack<()> },
     /// Insert an entity; also advances the per-batch write counter and
     /// commits the in-flight transaction if the batch boundary is crossed.
     InsertEntity {
@@ -158,7 +166,10 @@ pub enum WriterCmd {
     /// write counter — edges and entities share one batch boundary.
     InsertEdge { edge: Box<EdgeRecord>, ack: Ack<()> },
     /// Insert one finding. The writer initializes lifecycle status to `open`
-    /// and leaves suppression / Filigree-link fields empty.
+    /// and leaves suppression / Filigree-link fields empty. Idempotent on
+    /// `id` (ON CONFLICT DO UPDATE): a `--resume` re-walk regenerates the same
+    /// run-scoped finding ids and refreshes the analysis-derived columns while
+    /// preserving `created_at` and the lifecycle columns.
     InsertFinding {
         finding: Box<FindingRecord>,
         ack: Ack<()>,
diff --git a/crates/clarion-storage/src/error.rs b/crates/clarion-storage/src/error.rs
index d9a775dc..c69b337f 100644
--- a/crates/clarion-storage/src/error.rs
+++ b/crates/clarion-storage/src/error.rs
@@ -19,6 +19,20 @@ pub enum StorageError {
     #[error("PRAGMA invariant violated: {0}")]
     PragmaInvariant(String),
 
+    #[error(
+        "CLA-INFRA-STORAGE-FOREIGN-DB: refusing to open SQLite file with \
+         application_id={application_id:#010x}; Clarion databases carry \
+         application_id=0x434C524E (\"CLRN\")"
+    )]
+    ForeignDatabase { application_id: u32 },
+
+    #[error(
+        "CLA-INFRA-STORAGE-FUTURE-DB: refusing to open SQLite file with \
+         user_version={found} (greater than current schema version {current}); \
+         the database was written by a newer Clarion build"
+    )]
+    FutureUserVersion { found: u32, current: u32 },
+
     #[error("migration {version} failed: {source}")]
     Migration {
         version: u32,
diff --git a/crates/clarion-storage/src/lib.rs b/crates/clarion-storage/src/lib.rs
index 62b62589..7dfa328b 100644
--- a/crates/clarion-storage/src/lib.rs
+++ b/crates/clarion-storage/src/lib.rs
@@ -10,6 +10,7 @@ pub mod error;
 pub mod pragma;
 pub mod query;
 pub mod reader;
+pub mod retry;
 pub mod schema;
 pub mod unresolved;
 pub mod writer;
@@ -26,15 +27,19 @@ pub use commands::{
 };
 pub use error::{Result, StorageError};
 pub use query::{
-    CallEdgeMatch, ContainedEntities, EntityRow, ModuleDependencyEdge, ReferenceDirection,
-    ReferenceEdgeMatch, SubsystemMember, UnresolvedCallSiteRow, call_edges_from,
-    call_edges_targeting, candidate_entities_for_unresolved_sites, child_entity_ids,
-    contained_entity_ids, entity_at_line, entity_by_id, existing_entity_ids, find_entities,
-    module_dependency_edges, normalize_source_path, reference_edges_for_entity,
-    subsystem_for_member, subsystem_members, unresolved_call_sites_for_caller,
+    CallEdgeMatch, CanonicalProjectPath, ContainedEntities, EntityRow, EntitySubsystem,
+    FindingForEmitRow, ModuleDependencyEdge, ReferenceDirection, ReferenceEdgeMatch, ResolvedFile,
+    ResolvedFileCatalogEntry, RolledUpReferenceEdge, SubsystemMember, UnresolvedCallSiteRow,
+    ancestor_chain, call_edges_from, call_edges_targeting, candidate_entities_for_unresolved_sites,
+    child_entity_ids, contained_entity_ids, containing_module_id, entities_containing_line,
+    entity_at_line, entity_briefing_block_reason, entity_by_id, existing_entity_ids, find_entities,
+    findings_for_emit, import_edges_for_entity, module_dependency_edges, module_reference_rollup,
+    normalize_source_path, reference_edges_for_entity, resolve_file, resolve_file_catalog_entry,
+    subsystem_for_member, subsystem_members, subsystem_of_entity, unresolved_call_sites_for_caller,
     unresolved_callers_for_target,
 };
 pub use reader::ReaderPool;
+pub use retry::{RetryPolicy, begin_immediate};
 pub use unresolved::{UnresolvedCallSiteRecord, replace_unresolved_call_sites_for_caller};
 pub use writer::{
     DEFAULT_BATCH_SIZE, DEFAULT_CHANNEL_CAPACITY, Writer, known_scan_time_edge_kinds,
diff --git a/crates/clarion-storage/src/pragma.rs b/crates/clarion-storage/src/pragma.rs
index 29f1d2f6..90743b30 100644
--- a/crates/clarion-storage/src/pragma.rs
+++ b/crates/clarion-storage/src/pragma.rs
@@ -1,18 +1,53 @@
 //! PRAGMAs applied at connection open per ADR-011 §`SQLite` PRAGMAs.
+//!
+//! # Operational tuning discipline (per ADR-035, in-flight at v1.0 tag-cut)
+//!
+//! - **Stated basis**: ADR-011 §`SQLite` PRAGMAs fixes the durability +
+//!   concurrency posture (`journal_mode=WAL` + `synchronous=NORMAL` +
+//!   `busy_timeout=5000` + `wal_autocheckpoint=1000` + `foreign_keys=ON`).
+//!   The `application_id=0x434C524E` ("CLRN") and `user_version` PRAGMAs
+//!   close gap STO-02 from `docs/implementation/v1.0-tag-cut/gap-register.md`:
+//!   they give `.clarion/clarion.db` a self-identifying on-disk header so
+//!   `file(1)` / `sqlite3 .dbinfo` / a future migration runner can refuse
+//!   foreign or forward-incompatible files.
+//! - **Override surface**: **recompile-only.** None of these PRAGMAs are
+//!   user-tunable at runtime — they encode the storage contract. Any
+//!   override is a source-code change reviewed against the ADR that
+//!   established the value.
+//! - **Retune trigger**: the on-disk format identifier (`application_id`)
+//!   may only change under a new ADR that supersedes ADR-035; the
+//!   `user_version` is bumped automatically by the migration runner
+//!   (`schema::apply_migrations`) and otherwise treated as immutable.
 
 use rusqlite::Connection;
 
 use crate::error::{Result, StorageError};
 
+/// `SQLite` `application_id` header value identifying Clarion databases.
+///
+/// ASCII "CLRN" — picked so `file(1)` / `sqlite3 .dbinfo` distinguishes a
+/// Clarion DB from any other `SQLite` file. Set lazily on first open of a
+/// fresh (`application_id = 0`) file. Refusing to open a file with any
+/// other non-zero value is how we close STO-02.
+pub const CLARION_APPLICATION_ID: u32 = 0x434C_524E;
+
 /// Apply the write-side PRAGMA set: WAL, `synchronous=NORMAL`, `busy_timeout`,
 /// `wal_autocheckpoint`, `foreign_keys`. Called on the writer's connection once,
 /// immediately after open.
 ///
+/// Also enforces the `application_id` identity check (STO-02): a file whose
+/// `application_id` is neither `0` (fresh / legacy) nor
+/// [`CLARION_APPLICATION_ID`] is rejected with
+/// [`StorageError::ForeignDatabase`]. A zero value is upgraded in place
+/// (`PRAGMA application_id = ...`) so re-opens recognise the file.
+///
 /// # Errors
 ///
-/// Returns [`crate::error::StorageError::Sqlite`] if any PRAGMA statement fails.
-/// Returns [`crate::error::StorageError::PragmaInvariant`] if WAL mode is not
+/// Returns [`StorageError::Sqlite`] if any PRAGMA statement fails.
+/// Returns [`StorageError::PragmaInvariant`] if WAL mode is not
 /// confirmed after the `PRAGMA journal_mode = WAL` command.
+/// Returns [`StorageError::ForeignDatabase`] if the file carries a
+/// non-zero `application_id` that is not Clarion's.
 pub fn apply_write_pragmas(conn: &Connection) -> Result<()> {
     let mode: String = conn.query_row("PRAGMA journal_mode = WAL", [], |row| row.get(0))?;
     if !mode.eq_ignore_ascii_case("wal") {
@@ -21,6 +56,7 @@ pub fn apply_write_pragmas(conn: &Connection) -> Result<()> {
              ADR-011's synchronous=NORMAL durability posture requires WAL"
         )));
     }
+    enforce_application_id(conn)?;
     conn.execute_batch(concat!(
         "PRAGMA synchronous = NORMAL;",
         "PRAGMA busy_timeout = 5000;",
@@ -43,3 +79,31 @@ pub fn apply_read_pragmas(conn: &Connection) -> Result<()> {
     ))?;
     Ok(())
 }
+
+/// Read `application_id`; on `0` set it to [`CLARION_APPLICATION_ID`]; on
+/// [`CLARION_APPLICATION_ID`] continue; on any other value refuse with
+/// [`StorageError::ForeignDatabase`].
+///
+/// `SQLite` stores `application_id` as a signed 32-bit integer; rusqlite
+/// surfaces it as `i64`. We read into `i64` and reinterpret via
+/// `as u32` so values with the high bit set (negative `i32`) still compare
+/// against [`CLARION_APPLICATION_ID`] correctly.
+fn enforce_application_id(conn: &Connection) -> Result<()> {
+    let raw: i64 = conn.query_row("PRAGMA application_id", [], |row| row.get(0))?;
+    // i64 -> u32: SQLite caps application_id at 32 bits. Truncating cast is
+    // the documented round-trip; values outside u32 should not reach us.
+    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+    let current = raw as u32;
+    match current {
+        0 => {
+            conn.execute_batch(&format!(
+                "PRAGMA application_id = {CLARION_APPLICATION_ID};"
+            ))?;
+            Ok(())
+        }
+        id if id == CLARION_APPLICATION_ID => Ok(()),
+        other => Err(StorageError::ForeignDatabase {
+            application_id: other,
+        }),
+    }
+}
diff --git a/crates/clarion-storage/src/query.rs b/crates/clarion-storage/src/query.rs
index 28140237..393ae85e 100644
--- a/crates/clarion-storage/src/query.rs
+++ b/crates/clarion-storage/src/query.rs
@@ -1,13 +1,71 @@
 //! Read-side query helpers used by the MCP navigation surface.
 
 use std::collections::{BTreeMap, BTreeSet, HashSet};
+use std::fmt;
+use std::fs;
 use std::path::{Component, Path, PathBuf};
 
 use clarion_core::EdgeConfidence;
 use rusqlite::{Connection, OptionalExtension, Row, params, params_from_iter};
+use serde::{Serialize, Serializer};
 
 use crate::{Result, StorageError};
 
+/// A path that is *proven* to be:
+///
+/// 1. anchored under the project root (no `..` / `/` / drive prefix),
+/// 2. composed solely of normal UTF-8 path components, and
+/// 3. emitted in POSIX-style (`/`-joined) form.
+///
+/// The inner string is private and `try_new` is the only public constructor,
+/// so a `CanonicalProjectPath` cannot exist without that proof. Serializes
+/// transparently as its inner string so federation wire formats are
+/// unchanged.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CanonicalProjectPath(String);
+
+impl CanonicalProjectPath {
+    /// Construct from a `normalized` absolute path under `project_root`.
+    /// `normalized` is expected to already be lexically + filesystem
+    /// canonicalised by the caller (see [`normalize_source_path`]); this
+    /// constructor proves the residual project-relative-POSIX shape.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`StorageError::InvalidSourcePath`] when the path escapes
+    /// `project_root`, contains any non-`Normal` component, or is not
+    /// valid UTF-8.
+    pub fn try_new(project_root: &Path, normalized: &Path) -> Result<Self> {
+        Ok(Self(project_relative_path(project_root, normalized)?))
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    pub fn into_string(self) -> String {
+        self.0
+    }
+}
+
+impl fmt::Display for CanonicalProjectPath {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl Serialize for CanonicalProjectPath {
+    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
+        self.0.serialize(serializer)
+    }
+}
+
+impl AsRef<str> for CanonicalProjectPath {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct EntityRow {
     pub id: String,
@@ -66,6 +124,23 @@ pub struct ReferenceEdgeMatch {
     pub source_byte_end: Option<i64>,
 }
 
+/// One rolled-up reference edge for a module-altitude query: a `references`
+/// edge into or out of a symbol the module contains, attributed to the
+/// contained `via` symbol it actually touches (clarion-79d0ff6e14).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RolledUpReferenceEdge {
+    /// The entity on the far side of the edge — the referencer for `In`
+    /// (who imports a contained symbol), the referenced symbol for `Out`.
+    pub neighbor_id: String,
+    /// The module-contained symbol whose edge this is. For a module's own
+    /// direct reference edge (rare) this equals the module id.
+    pub via_id: String,
+    pub confidence: EdgeConfidence,
+    pub source_file_id: Option<String>,
+    pub source_byte_start: Option<i64>,
+    pub source_byte_end: Option<i64>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ModuleDependencyEdge {
     pub from_module_id: String,
@@ -74,6 +149,77 @@ pub struct ModuleDependencyEdge {
     pub edge_kinds: Vec<String>,
 }
 
+/// One persisted finding joined to its anchoring entity's source location, in
+/// the shape the cross-product emitter (`clarion-mcp` scan-results POST,
+/// WP9-B) needs: the Clarion-internal severity/kind vocabulary plus the
+/// entity's `source_file_path` / `source_line_*` that become Filigree's wire
+/// `path` / `line_start` / `line_end`. `source_file_path` is `None` for
+/// findings anchored to entities with no source location (e.g. a
+/// `core:subsystem:*` anchor); the emitter skips those because Filigree
+/// requires `path`.
+#[derive(Debug, Clone, PartialEq)]
+pub struct FindingForEmitRow {
+    pub id: String,
+    pub rule_id: String,
+    pub kind: String,
+    /// Clarion-internal severity: `INFO` | `WARN` | `ERROR` | `CRITICAL` |
+    /// `NONE`. Mapped to Filigree's wire vocabulary by the emitter.
+    pub severity: String,
+    pub confidence: Option<f64>,
+    pub confidence_basis: Option<String>,
+    pub message: String,
+    pub entity_id: String,
+    /// JSON array text as stored in `findings.related_entities`.
+    pub related_entities_json: String,
+    /// JSON array text as stored in `findings.supports`.
+    pub supports_json: String,
+    /// JSON array text as stored in `findings.supported_by`.
+    pub supported_by_json: String,
+    pub source_file_path: Option<String>,
+    pub source_line_start: Option<i64>,
+    pub source_line_end: Option<i64>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedFile {
+    pub entity_id: String,
+    pub content_hash: String,
+    pub canonical_path: CanonicalProjectPath,
+    pub language: String,
+    /// `Some(reason)` when the resolved entity carries a `briefing_blocked`
+    /// property (set by the pre-ingest secret scanner or the unscanned-source
+    /// defense-in-depth path). Federation read surfaces must refuse to expose
+    /// blocked entities to siblings; see `http_read::get_file` for the 404
+    /// translation.
+    pub briefing_blocked: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedFileCatalogEntry {
+    pub entity_id: String,
+    pub content_hash: Option<String>,
+    pub canonical_path: CanonicalProjectPath,
+    pub language: String,
+    pub briefing_blocked: Option<String>,
+    content_hash_path: PathBuf,
+}
+
+impl ResolvedFileCatalogEntry {
+    pub fn into_resolved_file(self) -> Result<ResolvedFile> {
+        let content_hash = match self.content_hash {
+            Some(content_hash) => content_hash,
+            None => file_content_hash(&self.content_hash_path)?,
+        };
+        Ok(ResolvedFile {
+            entity_id: self.entity_id,
+            content_hash,
+            canonical_path: self.canonical_path,
+            language: self.language,
+            briefing_blocked: self.briefing_blocked,
+        })
+    }
+}
+
 const MODULE_ANCESTOR_MAX_DEPTH: i64 = 32;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -150,6 +296,182 @@ pub fn entity_by_id(conn: &Connection, entity_id: &str) -> Result<Option<EntityR
         .map_err(StorageError::from)
 }
 
+pub fn resolve_file(
+    conn: &Connection,
+    project_root: &Path,
+    file: &str,
+    language: &str,
+) -> Result<Option<ResolvedFile>> {
+    let Some(entry) = resolve_file_catalog_entry(conn, project_root, file, language)? else {
+        return Ok(None);
+    };
+    entry.into_resolved_file().map(Some)
+}
+
+pub fn resolve_file_catalog_entry(
+    conn: &Connection,
+    project_root: &Path,
+    file: &str,
+    language: &str,
+) -> Result<Option<ResolvedFileCatalogEntry>> {
+    let lookup_path = normalize_lookup_path(project_root, file)?;
+    let normalized = lookup_path
+        .to_str()
+        .ok_or_else(|| StorageError::InvalidSourcePath(format!("{file:?} is not valid UTF-8")))?;
+    let canonical_path = CanonicalProjectPath::try_new(project_root, &lookup_path)?;
+    if let Some(entity) = source_entity_for_path(conn, normalized, Some("file"))? {
+        let briefing_blocked = entity_briefing_block_reason(&entity.properties_json);
+        return Ok(Some(ResolvedFileCatalogEntry {
+            entity_id: entity.id,
+            content_hash: entity.content_hash,
+            canonical_path,
+            language: resolved_language(
+                language,
+                &entity.plugin_id,
+                &entity.properties_json,
+                &lookup_path,
+            ),
+            briefing_blocked,
+            content_hash_path: lookup_path,
+        }));
+    }
+    Ok(None)
+}
+
+/// Extract the `briefing_blocked` reason from an entity's `properties` JSON
+/// column. Shared with `clarion-mcp` (which makes the same call inline) so
+/// federation read surfaces enforce the block uniformly.
+pub fn entity_briefing_block_reason(properties_json: &str) -> Option<String> {
+    // Fail-closed: malformed properties JSON treated as briefing-blocked to prevent secret exposure.
+    let Ok(value) = serde_json::from_str::<serde_json::Value>(properties_json) else {
+        return Some("malformed_properties_json".to_owned());
+    };
+    value.get("briefing_blocked")?.as_str().map(str::to_owned)
+}
+
+fn source_entity_for_path(
+    conn: &Connection,
+    normalized_path: &str,
+    required_kind: Option<&str>,
+) -> Result<Option<EntityRow>> {
+    let kind_filter = required_kind.map_or(String::new(), |_| "AND kind = ?2".to_owned());
+    let sql = format!(
+        "SELECT {ENTITY_COLUMNS} \
+         FROM entities \
+         WHERE source_file_path = ?1 \
+         {kind_filter} \
+         ORDER BY CASE kind \
+                    WHEN 'file' THEN 0 \
+                    WHEN 'module' THEN 1 \
+                    ELSE 2 \
+                  END ASC, \
+                  id ASC \
+         LIMIT 1"
+    );
+    let mut stmt = conn.prepare(&sql)?;
+    let row = if let Some(kind) = required_kind {
+        stmt.query_row(params![normalized_path, kind], map_entity_row)
+            .optional()?
+    } else {
+        stmt.query_row(params![normalized_path], map_entity_row)
+            .optional()?
+    };
+    Ok(row)
+}
+
+fn project_relative_path(project_root: &Path, normalized_path: &Path) -> Result<String> {
+    let root = project_root.canonicalize()?;
+    let relative = normalized_path.strip_prefix(&root).map_err(|_| {
+        StorageError::InvalidSourcePath(format!(
+            "{} is not under project root {}",
+            normalized_path.display(),
+            root.display()
+        ))
+    })?;
+    let mut parts = Vec::new();
+    for component in relative.components() {
+        match component {
+            Component::Normal(part) => {
+                let Some(part) = part.to_str() else {
+                    return Err(StorageError::InvalidSourcePath(
+                        "source path is not valid UTF-8".to_owned(),
+                    ));
+                };
+                parts.push(part);
+            }
+            Component::CurDir => {}
+            Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
+                return Err(StorageError::InvalidSourcePath(format!(
+                    "{} is not a project-relative source path",
+                    normalized_path.display()
+                )));
+            }
+        }
+    }
+    Ok(parts.join("/"))
+}
+
+fn normalize_lookup_path(project_root: &Path, file: &str) -> Result<PathBuf> {
+    let root = project_root.canonicalize()?;
+    let input = Path::new(file);
+    let candidate = if input.is_absolute() {
+        input.to_path_buf()
+    } else {
+        root.join(input)
+    };
+    let lexical = normalize_lexically(&candidate);
+    if !lexical.starts_with(&root) {
+        return Err(StorageError::InvalidSourcePath(format!(
+            "{file:?} escapes project root {}",
+            root.display()
+        )));
+    }
+    Ok(lexical)
+}
+
+fn file_content_hash(path: &Path) -> std::io::Result<String> {
+    fs::read(path).map(|bytes| blake3::hash(&bytes).to_hex().to_string())
+}
+
+fn resolved_language(
+    requested: &str,
+    plugin_id: &str,
+    properties_json: &str,
+    path: &Path,
+) -> String {
+    if let Some(language) = stored_language(properties_json) {
+        return language;
+    }
+    if plugin_id != "core" {
+        return plugin_id.to_owned();
+    }
+    if let Some(inferred) = language_for_extension(path) {
+        return inferred;
+    }
+    requested.trim().to_owned()
+}
+
+fn stored_language(properties_json: &str) -> Option<String> {
+    serde_json::from_str::<serde_json::Value>(properties_json)
+        .ok()?
+        .get("language")?
+        .as_str()
+        .map(str::trim)
+        .filter(|language| !language.is_empty())
+        .map(str::to_owned)
+}
+
+fn language_for_extension(path: &Path) -> Option<String> {
+    match path.extension().and_then(|extension| extension.to_str()) {
+        Some("py") => Some("python".to_owned()),
+        Some("rs") => Some("rust".to_owned()),
+        Some("js") => Some("javascript".to_owned()),
+        Some("ts") => Some("typescript".to_owned()),
+        Some(extension) => Some(extension.to_owned()),
+        None => None,
+    }
+}
+
 /// Return the subset of `candidates` whose `id` appears in `entities`. Used by
 /// the inferred-edge dispatch path to pre-filter LLM-proposed `to_id` values
 /// before they reach the writer-actor's FK-protected INSERT (clarion-df58379de4).
@@ -209,52 +531,164 @@ pub fn entity_at_line(
         .map_err(StorageError::from)
 }
 
+/// Every entity whose source span contains `line` in `source_file_path`,
+/// innermost first.
+///
+/// Same ordering as [`entity_at_line`] (smallest span first, then a stable
+/// kind/id tie-break) but without the `LIMIT 1`, so the caller sees the full
+/// containing set: the winner is the first row, and any later row sharing the
+/// winner's span length is a genuine ambiguity alternative (overlapping
+/// entities at the same granularity), while strictly larger spans are the
+/// nesting stack. Read-only.
+///
+/// # Errors
+///
+/// Returns [`StorageError::InvalidQuery`] for a non-positive `line`, or a
+/// `SQLite` error if the query fails.
+pub fn entities_containing_line(
+    conn: &Connection,
+    source_file_path: &str,
+    line: i64,
+) -> Result<Vec<EntityRow>> {
+    if line <= 0 {
+        return Err(StorageError::InvalidQuery(
+            "line must be a positive one-based integer".to_owned(),
+        ));
+    }
+    let sql = format!(
+        "SELECT {ENTITY_COLUMNS} \
+         FROM entities \
+         WHERE source_file_path = ?1 \
+           AND source_line_start IS NOT NULL \
+           AND source_line_end IS NOT NULL \
+           AND source_line_start <= ?2 \
+           AND source_line_end >= ?2 \
+         ORDER BY (source_line_end - source_line_start) ASC, \
+                  CASE kind \
+                    WHEN 'function' THEN 0 \
+                    WHEN 'class' THEN 1 \
+                    WHEN 'module' THEN 2 \
+                    ELSE 3 \
+                  END ASC, \
+                  id ASC"
+    );
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt
+        .query_map(params![source_file_path, line], map_entity_row)?
+        .collect::<rusqlite::Result<Vec<_>>>()?;
+    Ok(rows)
+}
+
+/// The chain of ancestor entities of `entity_id`, immediate parent first up
+/// to the root (module) entity, following each row's `parent_id`.
+///
+/// Used to render the authoritative containing stack for `entity_at`
+/// (module → class → function) independent of span arithmetic. The walk is
+/// bounded by `MAX_ANCESTOR_DEPTH` so a malformed `parent_id` cycle cannot
+/// loop forever. Read-only.
+///
+/// # Errors
+///
+/// Returns a `SQLite` error if a lookup fails. A dangling `parent_id` (parent
+/// row absent) simply ends the chain.
+pub fn ancestor_chain(conn: &Connection, entity_id: &str) -> Result<Vec<EntityRow>> {
+    let mut chain = Vec::new();
+    let mut current = entity_by_id(conn, entity_id)?;
+    let mut depth = 0;
+    while let Some(row) = current {
+        let Some(parent_id) = row.parent_id.clone() else {
+            break;
+        };
+        depth += 1;
+        if depth > MAX_ANCESTOR_DEPTH {
+            break;
+        }
+        let parent = entity_by_id(conn, &parent_id)?;
+        if let Some(parent_row) = &parent {
+            chain.push(parent_row.clone());
+        }
+        current = parent;
+    }
+    Ok(chain)
+}
+
+/// Upper bound on the parent-id ancestor walk in [`ancestor_chain`]. Real
+/// Python nesting is shallow; this only guards against a malformed cycle.
+const MAX_ANCESTOR_DEPTH: usize = 64;
+
 pub fn find_entities(
     conn: &Connection,
     pattern: &str,
     limit: usize,
     offset: usize,
+    kind: Option<&str>,
 ) -> Result<Vec<EntityRow>> {
     if pattern.trim().is_empty() {
         return Err(StorageError::InvalidQuery(
             "entity search pattern must not be blank".to_owned(),
         ));
     }
+    // The `kind` filter is an optional exact-match on `entities.kind`. Kinds are
+    // plugin-owned (ADR-003/ADR-022), so we don't validate against a hardcoded
+    // allowlist — an unknown kind simply matches no rows. Reject only a blank
+    // string, which is never a real kind and signals a malformed request.
+    if let Some(kind) = kind
+        && kind.trim().is_empty()
+    {
+        return Err(StorageError::InvalidQuery(
+            "entity search kind filter must not be blank".to_owned(),
+        ));
+    }
     let limit = limit.clamp(1, 100);
     let limit_i64 = i64::try_from(limit)
         .map_err(|_| StorageError::InvalidQuery("entity search limit is too large".to_owned()))?;
     let offset_i64 = i64::try_from(offset)
         .map_err(|_| StorageError::InvalidQuery("entity search offset is too large".to_owned()))?;
     if is_fts_safe(pattern) {
+        let kind_clause = if kind.is_some() {
+            "AND e.kind = ?4 "
+        } else {
+            ""
+        };
         let sql = format!(
             "SELECT e.{columns} \
              FROM entity_fts f \
              JOIN entities e ON e.id = f.entity_id \
-             WHERE entity_fts MATCH ?1 \
+             WHERE entity_fts MATCH ?1 {kind_clause}\
              ORDER BY bm25(entity_fts), e.id \
              LIMIT ?2 OFFSET ?3",
             columns = ENTITY_COLUMNS.replace(", ", ", e.")
         );
         let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(params![pattern, limit_i64, offset_i64], map_entity_row)?;
+        let rows = match kind {
+            Some(kind) => stmt.query_map(
+                params![pattern, limit_i64, offset_i64, kind],
+                map_entity_row,
+            )?,
+            None => stmt.query_map(params![pattern, limit_i64, offset_i64], map_entity_row)?,
+        };
         return rows
             .collect::<std::result::Result<Vec<_>, _>>()
             .map_err(StorageError::from);
     }
 
     let like = format!("%{}%", escape_like(pattern));
+    let kind_clause = if kind.is_some() { "AND kind = ?4 " } else { "" };
     let sql = format!(
         "SELECT {ENTITY_COLUMNS} \
          FROM entities \
-         WHERE id LIKE ?1 ESCAPE '\\' \
+         WHERE (id LIKE ?1 ESCAPE '\\' \
             OR name LIKE ?1 ESCAPE '\\' \
             OR short_name LIKE ?1 ESCAPE '\\' \
-            OR COALESCE(summary, '') LIKE ?1 ESCAPE '\\' \
+            OR COALESCE(summary, '') LIKE ?1 ESCAPE '\\') {kind_clause}\
          ORDER BY id \
          LIMIT ?2 OFFSET ?3"
     );
     let mut stmt = conn.prepare(&sql)?;
-    let rows = stmt.query_map(params![like, limit_i64, offset_i64], map_entity_row)?;
+    let rows = match kind {
+        Some(kind) => stmt.query_map(params![like, limit_i64, offset_i64, kind], map_entity_row)?,
+        None => stmt.query_map(params![like, limit_i64, offset_i64], map_entity_row)?,
+    };
     rows.collect::<std::result::Result<Vec<_>, _>>()
         .map_err(StorageError::from)
 }
@@ -401,27 +835,121 @@ pub fn reference_edges_for_entity(
     conn: &Connection,
     entity_id: &str,
     direction: ReferenceDirection,
+) -> Result<Vec<ReferenceEdgeMatch>> {
+    directed_edges_for_entity(conn, entity_id, direction, "references")
+}
+
+/// `imports` edges (module → module). Direction `In` answers "who imports this
+/// module" — the reverse-import lookup neighborhood previously could not serve
+/// because it only read `references` edges (clarion-79d0ff6e14).
+pub fn import_edges_for_entity(
+    conn: &Connection,
+    entity_id: &str,
+    direction: ReferenceDirection,
+) -> Result<Vec<ReferenceEdgeMatch>> {
+    directed_edges_for_entity(conn, entity_id, direction, "imports")
+}
+
+fn directed_edges_for_entity(
+    conn: &Connection,
+    entity_id: &str,
+    direction: ReferenceDirection,
+    kind: &str,
 ) -> Result<Vec<ReferenceEdgeMatch>> {
     let sql = match direction {
         ReferenceDirection::In => {
             "SELECT from_id, confidence, source_file_id, source_byte_start, source_byte_end \
              FROM edges \
-             WHERE kind = 'references' AND to_id = ?1 \
+             WHERE kind = ?1 AND to_id = ?2 \
              ORDER BY from_id, source_byte_start, source_byte_end"
         }
         ReferenceDirection::Out => {
             "SELECT to_id, confidence, source_file_id, source_byte_start, source_byte_end \
              FROM edges \
-             WHERE kind = 'references' AND from_id = ?1 \
+             WHERE kind = ?1 AND from_id = ?2 \
              ORDER BY to_id, source_byte_start, source_byte_end"
         }
     };
     let mut stmt = conn.prepare(sql)?;
-    let rows = stmt.query_map(params![entity_id], map_reference_edge_match)?;
+    let rows = stmt.query_map(params![kind, entity_id], map_reference_edge_match)?;
+    rows.collect::<std::result::Result<Vec<_>, _>>()
+        .map_err(StorageError::from)
+}
+
+/// Aggregate the `references` edges of every entity transitively contained in
+/// `module_id` (via `contains`), for module-altitude reference rollup and the
+/// reverse-import lookup ("who imports this module / contract?").
+///
+/// A Python `from pkg.contracts import RunStatus` is recorded as a `references`
+/// edge to the *class*, not the module — so a module's OWN reference edges are
+/// almost always empty and "who references this module?" answered `[]`
+/// (clarion-79d0ff6e14). This rolls the contained symbols' edges up to the
+/// module: direction `In` lists external referencers (who imports a contained
+/// symbol), `Out` lists what contained symbols reference outside the module.
+///
+/// Intra-module edges (both endpoints contained in the same module) are
+/// excluded — they are internal wiring, not a reverse-import answer. Results
+/// are ordered deterministically. The recursive CTE uses `UNION` (not `UNION
+/// ALL`), so a pathological `contains` cycle terminates instead of looping.
+pub fn module_reference_rollup(
+    conn: &Connection,
+    module_id: &str,
+    direction: ReferenceDirection,
+) -> Result<Vec<RolledUpReferenceEdge>> {
+    // Column 0 is always the far-side neighbor, column 1 the contained `via`
+    // symbol, so `map_rolled_up_reference_edge` is direction-agnostic.
+    let sql = match direction {
+        ReferenceDirection::In => {
+            "WITH RECURSIVE contained(id) AS ( \
+                 SELECT ?1 \
+                 UNION \
+                 SELECT child.to_id FROM edges child \
+                 JOIN contained ON contained.id = child.from_id \
+                 WHERE child.kind = 'contains' \
+             ) \
+             SELECT ed.from_id, ed.to_id, ed.confidence, ed.source_file_id, \
+                    ed.source_byte_start, ed.source_byte_end \
+             FROM edges ed \
+             JOIN contained ON contained.id = ed.to_id \
+             WHERE ed.kind = 'references' \
+               AND ed.from_id NOT IN (SELECT id FROM contained) \
+             ORDER BY ed.from_id, ed.to_id, ed.source_byte_start, ed.source_byte_end"
+        }
+        ReferenceDirection::Out => {
+            "WITH RECURSIVE contained(id) AS ( \
+                 SELECT ?1 \
+                 UNION \
+                 SELECT child.to_id FROM edges child \
+                 JOIN contained ON contained.id = child.from_id \
+                 WHERE child.kind = 'contains' \
+             ) \
+             SELECT ed.to_id, ed.from_id, ed.confidence, ed.source_file_id, \
+                    ed.source_byte_start, ed.source_byte_end \
+             FROM edges ed \
+             JOIN contained ON contained.id = ed.from_id \
+             WHERE ed.kind = 'references' \
+               AND ed.to_id NOT IN (SELECT id FROM contained) \
+             ORDER BY ed.to_id, ed.from_id, ed.source_byte_start, ed.source_byte_end"
+        }
+    };
+    let mut stmt = conn.prepare(sql)?;
+    let rows = stmt.query_map(params![module_id], map_rolled_up_reference_edge)?;
     rows.collect::<std::result::Result<Vec<_>, _>>()
         .map_err(StorageError::from)
 }
 
+fn map_rolled_up_reference_edge(row: &Row<'_>) -> rusqlite::Result<RolledUpReferenceEdge> {
+    let raw_confidence: String = row.get(2)?;
+    Ok(RolledUpReferenceEdge {
+        neighbor_id: row.get(0)?,
+        via_id: row.get(1)?,
+        confidence: parse_confidence(&raw_confidence)?,
+        source_file_id: row.get(3)?,
+        source_byte_start: row.get(4)?,
+        source_byte_end: row.get(5)?,
+    })
+}
+
 pub fn module_dependency_edges(
     conn: &Connection,
     edge_types: &[&str],
@@ -551,6 +1079,83 @@ pub fn subsystem_members(conn: &Connection, subsystem_id: &str) -> Result<Vec<Su
         .map_err(StorageError::from)
 }
 
+/// The subsystem an entity belongs to, plus the module the membership was
+/// resolved through (the entity itself when it is a module).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EntitySubsystem {
+    pub subsystem_id: String,
+    pub via_module_id: String,
+}
+
+/// Resolve the subsystem an arbitrary entity belongs to — the reverse of
+/// [`subsystem_members`].
+///
+/// `in_subsystem` edges connect *modules* to subsystems, so for a non-module
+/// entity (function, class, …) this walks up `contains` edges to the nearest
+/// module ancestor and follows that module's `in_subsystem` edge. A module
+/// entity resolves directly (depth 0). Returns the nearest match, or `None` if
+/// the entity has no module ancestor that is assigned to a subsystem.
+pub fn subsystem_of_entity(conn: &Connection, entity_id: &str) -> Result<Option<EntitySubsystem>> {
+    conn.query_row(
+        "WITH RECURSIVE ancestors(id, depth) AS ( \
+             SELECT ?1, 0 \
+             UNION ALL \
+             SELECT parent.from_id, ancestors.depth + 1 \
+             FROM edges parent \
+             JOIN ancestors ON parent.to_id = ancestors.id \
+             WHERE parent.kind = 'contains' AND ancestors.depth < ?2 \
+         ) \
+         SELECT m.id, sub.to_id \
+         FROM ancestors \
+         JOIN entities m ON m.id = ancestors.id AND m.kind = 'module' \
+         JOIN edges sub ON sub.kind = 'in_subsystem' AND sub.from_id = m.id \
+         JOIN entities s ON s.id = sub.to_id AND s.kind = 'subsystem' \
+         ORDER BY ancestors.depth, sub.to_id \
+         LIMIT 1",
+        params![entity_id, MODULE_ANCESTOR_MAX_DEPTH],
+        |row| {
+            Ok(EntitySubsystem {
+                via_module_id: row.get(0)?,
+                subsystem_id: row.get(1)?,
+            })
+        },
+    )
+    .optional()
+    .map_err(StorageError::from)
+}
+
+/// Resolve the module that contains `entity_id`: the nearest `module`-kind
+/// ancestor reached by walking `contains` edges upward, or the entity itself
+/// when it is already a module (depth 0).
+///
+/// Used to lift a reverse-import (`who imports this`) result to module altitude
+/// (clarion-79d0ff6e14). A `references` edge is recorded against the importing
+/// *symbol* (`from pkg.contracts import X` binds to the class `X`), but the
+/// reverse-import contract names importing *modules* — so a consumer resolves
+/// each importer to its module here. Returns `None` for a symbol with no module
+/// ancestor within `MODULE_ANCESTOR_MAX_DEPTH`.
+pub fn containing_module_id(conn: &Connection, entity_id: &str) -> Result<Option<String>> {
+    conn.query_row(
+        "WITH RECURSIVE ancestors(id, depth) AS ( \
+             SELECT ?1, 0 \
+             UNION ALL \
+             SELECT parent.from_id, ancestors.depth + 1 \
+             FROM edges parent \
+             JOIN ancestors ON parent.to_id = ancestors.id \
+             WHERE parent.kind = 'contains' AND ancestors.depth < ?2 \
+         ) \
+         SELECT m.id \
+         FROM ancestors \
+         JOIN entities m ON m.id = ancestors.id AND m.kind = 'module' \
+         ORDER BY ancestors.depth \
+         LIMIT 1",
+        params![entity_id, MODULE_ANCESTOR_MAX_DEPTH],
+        |row| row.get::<_, String>(0),
+    )
+    .optional()
+    .map_err(StorageError::from)
+}
+
 pub fn subsystem_for_member(conn: &Connection, module_id: &str) -> Result<Option<String>> {
     // Reserved for v0.2 neighborhood / issues_for enrichment. v0.1's MCP
     // surface exposes subsystem_members, but keeping this inverse lookup here
@@ -627,6 +1232,58 @@ pub fn contained_entity_ids(
     })
 }
 
+/// All findings recorded under `run_id`, joined to their anchoring entity's
+/// source location, ordered by finding id for deterministic emission. Used by
+/// the WP9-B cross-product emitter to build a `POST /api/v1/scan-results`
+/// batch. Findings whose anchor entity has no `source_file_path` are returned
+/// with `source_file_path: None`; the emitter skips them (Filigree requires a
+/// `path`).
+///
+/// Findings anchored to a `briefing_blocked` entity are excluded: emission is a
+/// one-way path/line egress to a sibling, and the federation read API
+/// (`GET /api/v1/files`) already refuses briefing-blocked entities and omits
+/// their identity fields. Without this guard the write direction would leak the
+/// very path/line the read direction is engineered to withhold — e.g. a
+/// secret-scanner `CLA-SEC-SECRET-DETECTED` finding on a still-blocked
+/// secret-bearing file. The filter is safe for the ADR-013 audit trail: an
+/// operator override (`--allow-unredacted-secrets`) records the file as
+/// `Overridden`, not `Blocked`, so its anchor entity carries no
+/// `briefing_blocked` reason and the `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` audit
+/// finding still emits.
+pub fn findings_for_emit(conn: &Connection, run_id: &str) -> Result<Vec<FindingForEmitRow>> {
+    let mut stmt = conn.prepare(
+        "SELECT f.id, f.rule_id, f.kind, f.severity, f.confidence, \
+                f.confidence_basis, f.message, f.entity_id, f.related_entities, \
+                f.supports, f.supported_by, \
+                e.source_file_path, e.source_line_start, e.source_line_end \
+         FROM findings f \
+         JOIN entities e ON e.id = f.entity_id \
+         WHERE f.run_id = ?1 \
+           AND e.briefing_blocked IS NULL \
+         ORDER BY f.id",
+    )?;
+    let rows = stmt.query_map(params![run_id], |row| {
+        Ok(FindingForEmitRow {
+            id: row.get(0)?,
+            rule_id: row.get(1)?,
+            kind: row.get(2)?,
+            severity: row.get(3)?,
+            confidence: row.get(4)?,
+            confidence_basis: row.get(5)?,
+            message: row.get(6)?,
+            entity_id: row.get(7)?,
+            related_entities_json: row.get(8)?,
+            supports_json: row.get(9)?,
+            supported_by_json: row.get(10)?,
+            source_file_path: row.get(11)?,
+            source_line_start: row.get(12)?,
+            source_line_end: row.get(13)?,
+        })
+    })?;
+    rows.collect::<std::result::Result<Vec<_>, _>>()
+        .map_err(StorageError::from)
+}
+
 fn map_entity_row(row: &Row<'_>) -> rusqlite::Result<EntityRow> {
     Ok(EntityRow {
         id: row.get(0)?,
diff --git a/crates/clarion-storage/src/reader.rs b/crates/clarion-storage/src/reader.rs
index 8856becc..3bed03ee 100644
--- a/crates/clarion-storage/src/reader.rs
+++ b/crates/clarion-storage/src/reader.rs
@@ -7,6 +7,7 @@
 //! connection.
 
 use std::path::Path;
+use std::sync::Arc;
 
 use deadpool_sqlite::{Config, Pool, Runtime};
 
@@ -14,8 +15,17 @@ use crate::error::Result;
 use crate::pragma;
 
 /// A read-only connection pool backed by `deadpool-sqlite`.
+///
+/// `identity` is a per-`open()` Arc that survives every `Clone` of the
+/// `ReaderPool`. Two `ReaderPool` values share a `ReaderPool::identity`
+/// pointer if-and-only-if they were produced by `Clone`-ing the same
+/// original. Callers that need to *prove at runtime* that two pool handles
+/// are the same pool (rather than coincidentally pointing at the same
+/// file) use [`ReaderPool::shares_pool_with`].
+#[derive(Clone)]
 pub struct ReaderPool {
     pool: Pool,
+    identity: Arc<()>,
 }
 
 impl ReaderPool {
@@ -37,7 +47,64 @@ impl ReaderPool {
         let mut cfg = Config::new(db_path.as_ref());
         cfg.pool = Some(deadpool_sqlite::PoolConfig::new(max_size));
         let pool = cfg.create_pool(Runtime::Tokio1)?;
-        Ok(Self { pool })
+        Ok(Self {
+            pool,
+            identity: Arc::new(()),
+        })
+    }
+
+    /// Open a pool and eagerly validate the backing database at boot.
+    ///
+    /// Like [`Self::open`], but first proves the file exists and is a readable
+    /// `SQLite` database, so `clarion serve` fails fast on a missing, corrupt,
+    /// or unreadable DB instead of deferring the error to the first
+    /// [`Self::with_reader`] call. This matters because `deadpool-sqlite` opens
+    /// pool connections lazily *and with `CREATE`* — without this probe, a
+    /// `serve` pointed at a missing DB would silently materialise an empty one
+    /// and answer every query with zero rows.
+    ///
+    /// The probe is a throwaway read-only connection running
+    /// `PRAGMA schema_version`, the same cheap corruption check
+    /// `clarion hook session-start` uses. It runs *before* the pool is built so
+    /// a bad DB never produces a half-live pool.
+    ///
+    /// It validates file-level openability and readability only; it does not
+    /// prove the pool can acquire a connection under concurrent load (that
+    /// still surfaces in [`Self::with_reader`] as before).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::StorageError::Sqlite`] if the database cannot be opened
+    /// read-only (missing file, permission denied) or the probe read fails
+    /// (corrupt / not a `SQLite` file), and [`crate::StorageError::PoolBuild`]
+    /// if the pool itself cannot be built.
+    pub fn open_validated(db_path: impl AsRef<Path>, max_size: usize) -> Result<Self> {
+        let db_path = db_path.as_ref();
+        let conn = rusqlite::Connection::open_with_flags(
+            db_path,
+            rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
+        )?;
+        // Force a real read of the database header so a present-but-corrupt file
+        // is rejected here rather than reported as an empty index later.
+        conn.query_row("PRAGMA schema_version", [], |row| row.get::<_, i64>(0))?;
+        drop(conn);
+        Self::open(db_path, max_size)
+    }
+
+    /// Borrow the per-pool identity tag. Two `ReaderPool` clones from the
+    /// same original return tags that satisfy `Arc::ptr_eq`; pools opened
+    /// independently do not.
+    #[must_use]
+    pub fn identity(&self) -> &Arc<()> {
+        &self.identity
+    }
+
+    /// Returns `true` iff `self` and `other` were produced by cloning the
+    /// same original `ReaderPool` (i.e. they share the same in-process pool
+    /// instance, not just the same backing file).
+    #[must_use]
+    pub fn shares_pool_with(&self, other: &ReaderPool) -> bool {
+        Arc::ptr_eq(&self.identity, &other.identity)
     }
 
     /// Acquire a reader and run a blocking closure on it.
diff --git a/crates/clarion-storage/src/retry.rs b/crates/clarion-storage/src/retry.rs
new file mode 100644
index 00000000..758cbd36
--- /dev/null
+++ b/crates/clarion-storage/src/retry.rs
@@ -0,0 +1,202 @@
+//! `BEGIN IMMEDIATE` with bounded `SQLITE_BUSY` retry (gap-register STO-05).
+//!
+//! Two distinct concerns motivate this, and `PRAGMA busy_timeout` addresses
+//! neither completely:
+//!
+//! 1. **Deferred vs. immediate.** A plain `BEGIN` starts a *deferred*
+//!    transaction that does not take the write lock until the first write.
+//!    When that write needs to upgrade a read lock to a write lock and another
+//!    connection already holds the write lock, `SQLite` returns `SQLITE_BUSY`
+//!    *immediately* — the busy handler is **not** invoked for lock upgrades,
+//!    because waiting could deadlock. `BEGIN IMMEDIATE` acquires the write lock
+//!    up front, where `busy_timeout` *is* honored, so contention surfaces as a
+//!    clean wait-then-retry at transaction start rather than a mid-statement
+//!    failure that leaves a half-open transaction.
+//!
+//! 2. **Beyond the timeout.** `busy_timeout` caps how long `SQLite` blocks on a
+//!    single lock attempt. Under sustained cross-process contention a writer
+//!    can still see `SQLITE_BUSY` after the timeout elapses; an application
+//!    retry with backoff gives the holder more chances to drain.
+//!
+//! Single-writer, single-process Clarion does not contend today; this helper
+//! exists so the writer is correct the moment cross-process writers land
+//! (STO-01 / V11-STO-01).
+
+use std::time::Duration;
+
+use rusqlite::{Connection, ErrorCode};
+
+use crate::error::Result;
+
+/// Bounded retry schedule for acquiring a write transaction.
+#[derive(Debug, Clone)]
+pub struct RetryPolicy {
+    /// Total number of `BEGIN IMMEDIATE` attempts (>= 1).
+    pub max_attempts: u32,
+    /// Backoff before the second attempt; doubles each subsequent retry.
+    pub initial_backoff: Duration,
+    /// Upper bound the exponential backoff is clamped to.
+    pub max_backoff: Duration,
+}
+
+impl RetryPolicy {
+    /// The policy the writer actor uses: a handful of attempts with short,
+    /// capped backoff. This sits *on top of* `PRAGMA busy_timeout=5000`, so the
+    /// effective tolerance is the timeout plus these retries.
+    #[must_use]
+    pub fn writer_default() -> Self {
+        Self {
+            max_attempts: 5,
+            initial_backoff: Duration::from_millis(20),
+            max_backoff: Duration::from_millis(200),
+        }
+    }
+}
+
+impl Default for RetryPolicy {
+    fn default() -> Self {
+        Self::writer_default()
+    }
+}
+
+/// `true` if `err` is a `SQLite` busy/locked error worth retrying.
+fn is_busy(err: &rusqlite::Error) -> bool {
+    matches!(
+        err,
+        rusqlite::Error::SqliteFailure(e, _)
+            if e.code == ErrorCode::DatabaseBusy || e.code == ErrorCode::DatabaseLocked
+    )
+}
+
+/// Open a write transaction with `BEGIN IMMEDIATE`, retrying on a busy/locked
+/// database according to `policy`.
+///
+/// On success the connection holds an open `IMMEDIATE` transaction; the caller
+/// is responsible for the matching `COMMIT`/`ROLLBACK`. On a non-busy error the
+/// helper returns immediately without retrying. After `policy.max_attempts`
+/// busy results it returns the last busy error.
+///
+/// # Errors
+///
+/// Returns [`crate::StorageError::Sqlite`] with the underlying busy error after
+/// exhausting retries, or the first non-busy error encountered.
+pub fn begin_immediate(conn: &Connection, policy: &RetryPolicy) -> Result<()> {
+    begin_immediate_inner(conn, policy, |_| {})
+}
+
+/// Test seam for [`begin_immediate`]: `on_busy` is invoked with the
+/// 1-based attempt number that just failed, immediately before the backoff
+/// sleep. Tests use it to release a competing lock deterministically (no
+/// wall-clock guessing). Production callers use [`begin_immediate`], whose hook
+/// is a no-op.
+pub(crate) fn begin_immediate_inner(
+    conn: &Connection,
+    policy: &RetryPolicy,
+    mut on_busy: impl FnMut(u32),
+) -> Result<()> {
+    let attempts = policy.max_attempts.max(1);
+    let mut backoff = policy.initial_backoff;
+    for attempt in 1..=attempts {
+        match conn.execute_batch("BEGIN IMMEDIATE") {
+            Ok(()) => return Ok(()),
+            Err(err) if is_busy(&err) && attempt < attempts => {
+                on_busy(attempt);
+                if !backoff.is_zero() {
+                    std::thread::sleep(backoff);
+                }
+                backoff = (backoff * 2).min(policy.max_backoff);
+            }
+            Err(err) => return Err(err.into()),
+        }
+    }
+    // Unreachable: the loop either returns Ok, returns the final Err on the
+    // last attempt, or retries. Kept as a defensive fallback.
+    unreachable!("begin_immediate loop must return within max_attempts")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn busy_conn() -> Connection {
+        let conn = Connection::open_in_memory().expect("open");
+        // Disable SQLite's own busy handler so contention surfaces as an
+        // immediate SQLITE_BUSY and the application retry loop is what we test.
+        conn.busy_timeout(Duration::from_millis(0))
+            .expect("busy_timeout");
+        conn
+    }
+
+    /// Two connections against the same on-disk DB, busy handler disabled.
+    fn shared_pair(path: &std::path::Path) -> (Connection, Connection) {
+        let open = || {
+            let c = Connection::open(path).expect("open");
+            c.busy_timeout(Duration::from_millis(0))
+                .expect("busy_timeout");
+            c
+        };
+        (open(), open())
+    }
+
+    #[test]
+    fn begin_immediate_succeeds_with_no_contention() {
+        let conn = busy_conn();
+        begin_immediate(&conn, &RetryPolicy::writer_default()).expect("begin");
+        // The transaction is open: a write succeeds and commits cleanly.
+        conn.execute_batch("CREATE TABLE t (x); INSERT INTO t VALUES (1); COMMIT")
+            .expect("write inside immediate tx");
+    }
+
+    #[test]
+    fn begin_immediate_exhausts_and_returns_busy() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("contended.db");
+        let (holder, contender) = shared_pair(&path);
+
+        // Holder takes the write lock and never releases it during the call.
+        holder
+            .execute_batch("BEGIN IMMEDIATE; CREATE TABLE t (x)")
+            .expect("holder acquires write lock");
+
+        let policy = RetryPolicy {
+            max_attempts: 3,
+            initial_backoff: Duration::from_millis(1),
+            max_backoff: Duration::from_millis(1),
+        };
+        let err = begin_immediate(&contender, &policy)
+            .expect_err("contender must fail while the lock is held");
+        assert!(
+            matches!(&err, crate::StorageError::Sqlite(e) if is_busy(e)),
+            "expected a busy/locked error, got {err:?}"
+        );
+    }
+
+    #[test]
+    fn begin_immediate_retries_then_succeeds_when_lock_released() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("contended.db");
+        let (holder, contender) = shared_pair(&path);
+
+        holder
+            .execute_batch("BEGIN IMMEDIATE; CREATE TABLE t (x)")
+            .expect("holder acquires write lock");
+
+        // Deterministic, single-threaded: when the first attempt fails busy,
+        // release the holder's lock from inside the retry hook so the next
+        // attempt finds the database free. No threads, no wall-clock races.
+        let mut released = false;
+        let policy = RetryPolicy {
+            max_attempts: 4,
+            initial_backoff: Duration::from_millis(1),
+            max_backoff: Duration::from_millis(1),
+        };
+        begin_immediate_inner(&contender, &policy, |attempt| {
+            if attempt == 1 && !released {
+                holder.execute_batch("COMMIT").expect("release holder lock");
+                released = true;
+            }
+        })
+        .expect("contender should acquire the lock after it is released");
+        assert!(released, "the retry hook should have fired at least once");
+    }
+}
diff --git a/crates/clarion-storage/src/schema.rs b/crates/clarion-storage/src/schema.rs
index 1a0adff6..1ade8f5f 100644
--- a/crates/clarion-storage/src/schema.rs
+++ b/crates/clarion-storage/src/schema.rs
@@ -14,22 +14,52 @@ struct Migration {
     sql: &'static str,
 }
 
-const MIGRATIONS: &[Migration] = &[Migration {
-    version: 1,
-    name: "0001_initial_schema",
-    sql: include_str!("../migrations/0001_initial_schema.sql"),
-}];
+const MIGRATIONS: &[Migration] = &[
+    Migration {
+        version: 1,
+        name: "0001_initial_schema",
+        sql: include_str!("../migrations/0001_initial_schema.sql"),
+    },
+    Migration {
+        version: 2,
+        name: "0002_briefing_blocked",
+        sql: include_str!("../migrations/0002_briefing_blocked.sql"),
+    },
+];
+
+/// Highest migration version known to this build. Mirrored into the
+/// `SQLite` `user_version` header (STO-02) so a future-built database is
+/// refused at open instead of silently corrupting state.
+pub const CURRENT_SCHEMA_VERSION: u32 = 2;
+
+const _CURRENT_SCHEMA_VERSION_MATCHES_LAST_MIGRATION: () = {
+    // Compile-time check: `CURRENT_SCHEMA_VERSION` must equal the highest
+    // version in `MIGRATIONS`. If a new migration is added without bumping
+    // the constant (or vice versa), this assertion fails to compile.
+    assert!(
+        MIGRATIONS[MIGRATIONS.len() - 1].version == CURRENT_SCHEMA_VERSION,
+        "CURRENT_SCHEMA_VERSION must equal the highest MIGRATIONS[].version"
+    );
+};
 
 /// Apply every migration not already recorded in `schema_migrations`.
 ///
 /// The first migration creates the `schema_migrations` table itself, so the
 /// initial lookup tolerates its absence.
 ///
+/// After all pending migrations apply, the `SQLite` header `user_version` is
+/// written to [`CURRENT_SCHEMA_VERSION`]. A `user_version` strictly greater
+/// than [`CURRENT_SCHEMA_VERSION`] at entry is refused via
+/// [`verify_user_version`] (closes STO-02 forward-incompatibility check).
+///
 /// # Errors
 ///
+/// Returns [`StorageError::FutureUserVersion`] if the database was written
+/// by a newer Clarion build.
 /// Returns [`StorageError::Migration`] with the failing version on SQL error
 /// during apply. Returns [`StorageError::Sqlite`] on bookkeeping failures.
 pub fn apply_migrations(conn: &mut Connection) -> Result<()> {
+    verify_user_version(conn)?;
     let applied = read_applied_versions(conn)?;
     for m in MIGRATIONS {
         if applied.contains(&m.version) {
@@ -38,6 +68,49 @@ pub fn apply_migrations(conn: &mut Connection) -> Result<()> {
         }
         apply_one(conn, m)?;
     }
+    apply_user_version(conn)?;
+    Ok(())
+}
+
+/// Refuse to operate on a database whose `user_version` is strictly greater
+/// than [`CURRENT_SCHEMA_VERSION`].
+///
+/// Equal or less is accepted: equal means the schema is current, less means
+/// either a fresh DB (`user_version=0`) or a DB awaiting in-flight migrations
+/// — both are handled by [`apply_migrations`]. The writer-actor calls this
+/// directly (without invoking the migration runner) so a forward-incompatible
+/// file is rejected at `Writer::spawn` time.
+///
+/// # Errors
+///
+/// Returns [`StorageError::FutureUserVersion`] when `user_version >
+/// CURRENT_SCHEMA_VERSION`. Returns [`StorageError::Sqlite`] if the PRAGMA
+/// query fails.
+pub fn verify_user_version(conn: &Connection) -> Result<()> {
+    let raw: i64 = conn.query_row("PRAGMA user_version", [], |row| row.get(0))?;
+    // SQLite stores user_version as a 32-bit integer; rusqlite returns i64.
+    // Negative values are unreachable in normal use (we only set u32 values);
+    // clamp via `try_from` so an out-of-range value surfaces explicitly
+    // rather than silently truncating.
+    let found = u32::try_from(raw).map_err(|_| {
+        StorageError::PragmaInvariant(format!(
+            "PRAGMA user_version returned out-of-range value {raw}; expected 0..=u32::MAX"
+        ))
+    })?;
+    if found > CURRENT_SCHEMA_VERSION {
+        return Err(StorageError::FutureUserVersion {
+            found,
+            current: CURRENT_SCHEMA_VERSION,
+        });
+    }
+    Ok(())
+}
+
+/// Write `PRAGMA user_version = CURRENT_SCHEMA_VERSION`. Idempotent — writing
+/// the same value is cheap (it touches the `SQLite` header page). Called after
+/// the migration runner has applied every pending migration.
+fn apply_user_version(conn: &Connection) -> Result<()> {
+    conn.execute_batch(&format!("PRAGMA user_version = {CURRENT_SCHEMA_VERSION};"))?;
     Ok(())
 }
 
@@ -128,6 +201,67 @@ fn migration_count_to_u32(n: i64) -> Result<u32> {
 mod tests {
     use super::*;
 
+    fn entities_has_briefing_blocked(conn: &Connection) -> bool {
+        conn.prepare("SELECT 1 FROM pragma_table_xinfo('entities') WHERE name = 'briefing_blocked'")
+            .and_then(|mut stmt| stmt.exists([]))
+            .unwrap_or(false)
+    }
+
+    #[test]
+    fn briefing_blocked_is_added_by_an_upgrade_migration_not_the_initial() {
+        // An existing v1 database (created before briefing_blocked) must gain
+        // the column on upgrade. If the column lives in the already-applied
+        // initial migration, existing DBs at schema_migrations.version=1 skip
+        // it forever and project_status hits `no such column`. Reproduce: apply
+        // only the initial migration, confirm the column is absent, then run
+        // the full migration runner and confirm an upgrade migration adds it.
+        let mut conn = Connection::open_in_memory().unwrap();
+        apply_one(&mut conn, &MIGRATIONS[0]).expect("apply initial migration");
+        assert!(
+            !entities_has_briefing_blocked(&conn),
+            "briefing_blocked must not be defined by the initial migration (0001)"
+        );
+
+        apply_migrations(&mut conn).expect("apply pending migrations");
+        assert!(
+            entities_has_briefing_blocked(&conn),
+            "an upgrade migration must add briefing_blocked to an existing v1 DB"
+        );
+        let user_version: i64 = conn
+            .query_row("PRAGMA user_version", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(user_version, i64::from(CURRENT_SCHEMA_VERSION));
+    }
+
+    #[test]
+    fn migration_0002_rolls_back_the_column_when_a_later_statement_fails() {
+        // 0002 must apply its ALTER + CREATE INDEX atomically. If the column is
+        // added under autocommit and a later statement fails, the DB is left
+        // with `briefing_blocked` present but no schema_migrations.version=2
+        // row — the next startup reruns the ALTER and dies on duplicate column,
+        // blocking upgrade. Inject that failure: squat the index name so 0002's
+        // CREATE INDEX fails on its second statement, then prove (on a fresh
+        // connection, reading committed state) that the ALTER did not survive.
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("rollback.db");
+        {
+            let mut conn = Connection::open(&db).unwrap();
+            apply_one(&mut conn, &MIGRATIONS[0]).expect("apply initial migration");
+            // Squat the index name 0002 will try to create.
+            conn.execute_batch("CREATE INDEX ix_entities_briefing_blocked ON entities(id);")
+                .expect("pre-create colliding index");
+            apply_one(&mut conn, &MIGRATIONS[1])
+                .expect_err("0002 must fail when its CREATE INDEX collides");
+            // Drop conn here → any open transaction rolls back on close.
+        }
+        let conn = Connection::open(&db).unwrap();
+        assert!(
+            !entities_has_briefing_blocked(&conn),
+            "0002's ALTER must roll back when a later statement fails; \
+             the column survived, so the migration is not atomic"
+        );
+    }
+
     #[test]
     fn migration_count_conversion_rejects_overflow() {
         let err = migration_count_to_u32(i64::from(u32::MAX) + 1)
diff --git a/crates/clarion-storage/src/writer.rs b/crates/clarion-storage/src/writer.rs
index 73143ea3..455a4535 100644
--- a/crates/clarion-storage/src/writer.rs
+++ b/crates/clarion-storage/src/writer.rs
@@ -29,6 +29,7 @@ use crate::commands::{
 };
 use crate::error::{Result, StorageError};
 use crate::pragma;
+use crate::schema;
 use crate::unresolved::replace_unresolved_call_sites_for_caller;
 
 /// Default transaction batch size per ADR-011.
@@ -86,6 +87,11 @@ impl Writer {
         let handle = tokio::task::spawn_blocking(move || -> Result<()> {
             let mut conn = Connection::open(&db_path)?;
             pragma::apply_write_pragmas(&conn)?;
+            // STO-02: refuse a database whose `user_version` is strictly greater
+            // than CURRENT_SCHEMA_VERSION. Equal/less are normal — equal is the
+            // already-migrated steady state, less is handled by the migration
+            // runner (which `install` calls before the writer ever spawns).
+            schema::verify_user_version(&conn)?;
             run_actor(
                 rx,
                 &mut conn,
@@ -162,6 +168,9 @@ fn run_actor(
                     begin_run(conn, &mut state, &run_id, &config_json, &started_at),
                 );
             }
+            WriterCmd::ResumeRun { run_id, ack } => {
+                reply(ack, resume_run(conn, &mut state, &run_id));
+            }
             WriterCmd::InsertEntity { entity, ack } => {
                 let res = insert_entity(conn, &mut state, &entity, commits_observed);
                 reply(ack, res);
@@ -299,6 +308,11 @@ struct ActorState {
     in_tx: bool,
     /// The run currently in progress, if any.
     current_run: Option<String>,
+    /// Retry schedule for acquiring the write transaction (STO-05). Batch
+    /// transactions open with `BEGIN IMMEDIATE` so cross-process write
+    /// contention is resolved at lock-acquire (where `busy_timeout` is honored)
+    /// rather than failing mid-statement on a deferred-lock upgrade.
+    retry_policy: crate::retry::RetryPolicy,
 }
 
 impl ActorState {
@@ -308,10 +322,22 @@ impl ActorState {
             writes_in_batch: 0,
             in_tx: false,
             current_run: None,
+            retry_policy: crate::retry::RetryPolicy::writer_default(),
         }
     }
 }
 
+/// Open the write transaction for the current batch.
+///
+/// Uses `BEGIN IMMEDIATE` with the actor's retry policy (STO-05) rather than a
+/// deferred `BEGIN`: the actor always writes inside the transaction, so taking
+/// the write lock up front lets cross-process contention be resolved at
+/// lock-acquire (where `busy_timeout` and our retry apply) instead of failing
+/// mid-statement on a deferred-lock upgrade that the busy handler cannot serve.
+fn begin_write_tx(conn: &Connection, state: &ActorState) -> Result<()> {
+    crate::retry::begin_immediate(conn, &state.retry_policy)
+}
+
 fn begin_run(
     conn: &mut Connection,
     state: &mut ActorState,
@@ -329,7 +355,38 @@ fn begin_run(
          VALUES (?1, ?2, NULL, ?3, '{}', 'running')",
         params![run_id, started_at, config_json],
     )?;
-    conn.execute_batch("BEGIN")?;
+    begin_write_tx(conn, state)?;
+    state.in_tx = true;
+    state.writes_in_batch = 0;
+    state.current_run = Some(run_id.to_owned());
+    Ok(())
+}
+
+/// Reopen an existing run row instead of inserting a new one (the `--resume`
+/// path, REQ-FINDING-05). `begin_run` does an `INSERT` that fails on the run
+/// PK when handed an existing id; `resume_run` `UPDATE`s the row back to
+/// `running` and clears `completed_at`, then binds it as the active run and
+/// opens the write transaction exactly as `begin_run` does. The subsequent
+/// re-walk upserts entities/edges idempotently (see
+/// `insert_entity_is_idempotent_across_runs`), so a resumed run reproduces the
+/// same durable graph as the original — `--resume` is a re-emit-without-flip
+/// path, not an incremental checkpoint-recovery one.
+fn resume_run(conn: &mut Connection, state: &mut ActorState, run_id: &str) -> Result<()> {
+    if state.current_run.is_some() {
+        return Err(StorageError::WriterProtocol(
+            "ResumeRun received while a run is already in progress".to_owned(),
+        ));
+    }
+    let reopened = conn.execute(
+        "UPDATE runs SET status = 'running', completed_at = NULL WHERE id = ?1",
+        params![run_id],
+    )?;
+    if reopened == 0 {
+        return Err(StorageError::WriterProtocol(format!(
+            "ResumeRun: no run with id {run_id} to resume"
+        )));
+    }
+    begin_write_tx(conn, state)?;
     state.in_tx = true;
     state.writes_in_batch = 0;
     state.current_run = Some(run_id.to_owned());
@@ -349,10 +406,16 @@ fn insert_entity(
     }
     enforce_entity_kind_contract(entity)?;
     if !state.in_tx {
-        conn.execute_batch("BEGIN")?;
+        begin_write_tx(conn, state)?;
         state.in_tx = true;
     }
     validate_entity_source_file_anchor(conn, entity)?;
+    // ON CONFLICT(id) DO UPDATE makes `clarion analyze` idempotent across runs:
+    // a re-walk that produces the same entity updates the existing row instead
+    // of raising UNIQUE. `created_at` and `first_seen_commit` are preserved
+    // (the entity was first seen on its original run); `updated_at` and
+    // `last_seen_commit` are refreshed from the latest run's record. The
+    // AFTER UPDATE trigger on `entities` keeps `entity_fts` in sync.
     conn.execute(
         "INSERT INTO entities ( \
             id, plugin_id, kind, name, short_name, \
@@ -370,7 +433,25 @@ fn insert_entity(
             ?13, ?14, ?15, ?16, \
             ?17, ?18, \
             ?19, ?20 \
-         )",
+         ) \
+         ON CONFLICT(id) DO UPDATE SET \
+            plugin_id         = excluded.plugin_id, \
+            kind              = excluded.kind, \
+            name              = excluded.name, \
+            short_name        = excluded.short_name, \
+            parent_id         = excluded.parent_id, \
+            source_file_id    = excluded.source_file_id, \
+            source_file_path  = excluded.source_file_path, \
+            source_byte_start = excluded.source_byte_start, \
+            source_byte_end   = excluded.source_byte_end, \
+            source_line_start = excluded.source_line_start, \
+            source_line_end   = excluded.source_line_end, \
+            properties        = excluded.properties, \
+            content_hash      = excluded.content_hash, \
+            summary           = excluded.summary, \
+            wardline          = excluded.wardline, \
+            last_seen_commit  = excluded.last_seen_commit, \
+            updated_at        = excluded.updated_at",
         params![
             entity.id,
             entity.plugin_id,
@@ -575,7 +656,7 @@ fn insert_edge(
         return Err(err);
     }
     if !state.in_tx {
-        conn.execute_batch("BEGIN")?;
+        begin_write_tx(conn, state)?;
         state.in_tx = true;
     }
     validate_source_file_anchor(
@@ -622,9 +703,19 @@ fn insert_finding(
         ));
     }
     if !state.in_tx {
-        conn.execute_batch("BEGIN")?;
+        begin_write_tx(conn, state)?;
         state.in_tx = true;
     }
+    // ON CONFLICT(id) DO UPDATE makes the finding path idempotent under
+    // `--resume`: a finding id embeds its run_id (`core:finding:{run_id}:…`),
+    // so cross-run ids never collide and a fresh run only ever INSERTs. A
+    // resume re-walks under the *same* run_id and re-generates the same ids;
+    // without the upsert it would fail on `UNIQUE constraint: findings.id`.
+    // The conflict clause refreshes analysis-derived columns from the re-walk
+    // but PRESERVES the lifecycle columns (`status`, `suppression_reason`,
+    // `filigree_issue_id`) and `created_at` — the same first-seen-preserving
+    // discipline `insert_entity` applies. (These lifecycle columns are never
+    // mutated locally today; preserving them keeps that invariant if they are.)
     conn.execute(
         "INSERT INTO findings ( \
             id, tool, tool_version, run_id, rule_id, kind, severity, confidence, \
@@ -636,7 +727,24 @@ fn insert_finding(
             ?9, ?10, ?11, ?12, ?13, \
             ?14, ?15, ?16, 'open', NULL, \
             NULL, ?17, ?18 \
-         )",
+         ) \
+         ON CONFLICT(id) DO UPDATE SET \
+            tool = excluded.tool, \
+            tool_version = excluded.tool_version, \
+            run_id = excluded.run_id, \
+            rule_id = excluded.rule_id, \
+            kind = excluded.kind, \
+            severity = excluded.severity, \
+            confidence = excluded.confidence, \
+            confidence_basis = excluded.confidence_basis, \
+            entity_id = excluded.entity_id, \
+            related_entities = excluded.related_entities, \
+            message = excluded.message, \
+            evidence = excluded.evidence, \
+            properties = excluded.properties, \
+            supports = excluded.supports, \
+            supported_by = excluded.supported_by, \
+            updated_at = excluded.updated_at",
         params![
             finding.id,
             finding.tool,
@@ -760,7 +868,7 @@ fn replace_unresolved_call_sites_in_run(
         ));
     }
     if !state.in_tx {
-        conn.execute_batch("BEGIN")?;
+        begin_write_tx(conn, state)?;
         state.in_tx = true;
     }
     for site in sites {
@@ -793,7 +901,7 @@ fn bump_writes_and_maybe_commit(
         commits_observed.fetch_add(1, Ordering::Relaxed);
         // Open the next batch eagerly so the next write doesn't pay
         // another `BEGIN` round-trip.
-        conn.execute_batch("BEGIN")?;
+        begin_write_tx(conn, state)?;
         state.in_tx = true;
     }
     Ok(())
@@ -823,7 +931,7 @@ fn flush_run_batch(
         conn.execute_batch("COMMIT")?;
         commits_observed.fetch_add(1, Ordering::Relaxed);
     }
-    conn.execute_batch("BEGIN")?;
+    begin_write_tx(conn, state)?;
     state.in_tx = true;
     Ok(())
 }
@@ -845,7 +953,7 @@ fn query_time_write<T>(
     let result = write(conn);
 
     if reopen_run_transaction {
-        conn.execute_batch("BEGIN")?;
+        begin_write_tx(conn, state)?;
         state.in_tx = true;
     }
 
diff --git a/crates/clarion-storage/tests/query_helpers.rs b/crates/clarion-storage/tests/query_helpers.rs
index d0c194aa..791b8cab 100644
--- a/crates/clarion-storage/tests/query_helpers.rs
+++ b/crates/clarion-storage/tests/query_helpers.rs
@@ -5,9 +5,11 @@ use std::path::Path;
 use clarion_core::EdgeConfidence;
 use clarion_storage::{
     ModuleDependencyEdge, ReferenceDirection, SubsystemMember, call_edges_from,
-    call_edges_targeting, child_entity_ids, contained_entity_ids, entity_at_line, entity_by_id,
-    find_entities, module_dependency_edges, normalize_source_path, pragma,
-    reference_edges_for_entity, schema, subsystem_for_member, subsystem_members,
+    call_edges_targeting, child_entity_ids, contained_entity_ids, containing_module_id,
+    entity_at_line, entity_briefing_block_reason, entity_by_id, find_entities, findings_for_emit,
+    module_dependency_edges, module_reference_rollup, normalize_source_path, pragma,
+    reference_edges_for_entity, resolve_file, resolve_file_catalog_entry, schema,
+    subsystem_for_member, subsystem_members, subsystem_of_entity,
 };
 use rusqlite::{Connection, params};
 
@@ -512,6 +514,123 @@ fn reference_edges_for_entity_returns_directional_neighbors() {
     assert_eq!(outbound[0].source_byte_end, Some(39));
 }
 
+#[test]
+fn module_reference_rollup_aggregates_contained_symbol_edges_excluding_internal() {
+    // A `from pkg.contracts import RunStatus` records a `references` edge to the
+    // class, not the module — so the module's own edges are empty and the
+    // rollup must aggregate contained symbols' edges (clarion-79d0ff6e14).
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+
+    // Module under query, with two contained classes.
+    insert_entity(&conn, "python:module:pkg.contracts", "module");
+    insert_entity(&conn, "python:class:pkg.contracts.RunStatus", "class");
+    insert_entity(&conn, "python:class:pkg.contracts.Helper", "class");
+    insert_contains_edge(
+        &conn,
+        "python:module:pkg.contracts",
+        "python:class:pkg.contracts.RunStatus",
+    );
+    insert_contains_edge(
+        &conn,
+        "python:module:pkg.contracts",
+        "python:class:pkg.contracts.Helper",
+    );
+
+    // An external module whose function imports RunStatus (reverse-import In).
+    insert_entity(&conn, "python:module:pkg.consumer", "module");
+    insert_entity(&conn, "python:function:pkg.consumer.use", "function");
+    insert_contains_edge(
+        &conn,
+        "python:module:pkg.consumer",
+        "python:function:pkg.consumer.use",
+    );
+    insert_references_edge(
+        &conn,
+        "python:function:pkg.consumer.use",
+        "python:class:pkg.contracts.RunStatus",
+        EdgeConfidence::Resolved,
+        20,
+        25,
+    );
+
+    // A symbol the module's class references outward (rollup Out).
+    insert_entity(&conn, "python:module:pkg.other", "module");
+    insert_entity(&conn, "python:class:pkg.other.Thing", "class");
+    insert_contains_edge(
+        &conn,
+        "python:module:pkg.other",
+        "python:class:pkg.other.Thing",
+    );
+    insert_references_edge(
+        &conn,
+        "python:class:pkg.contracts.RunStatus",
+        "python:class:pkg.other.Thing",
+        EdgeConfidence::Resolved,
+        30,
+        40,
+    );
+
+    // Intra-module reference (RunStatus -> Helper): internal wiring, must be
+    // excluded from BOTH directions of the rollup.
+    insert_references_edge(
+        &conn,
+        "python:class:pkg.contracts.RunStatus",
+        "python:class:pkg.contracts.Helper",
+        EdgeConfidence::Resolved,
+        50,
+        55,
+    );
+
+    let inbound =
+        module_reference_rollup(&conn, "python:module:pkg.contracts", ReferenceDirection::In)
+            .expect("rollup inbound");
+    assert_eq!(
+        inbound.len(),
+        1,
+        "only the external referencer rolls up: {inbound:?}"
+    );
+    assert_eq!(inbound[0].neighbor_id, "python:function:pkg.consumer.use");
+    assert_eq!(inbound[0].via_id, "python:class:pkg.contracts.RunStatus");
+    assert_eq!(inbound[0].confidence, EdgeConfidence::Resolved);
+    assert_eq!(inbound[0].source_byte_start, Some(20));
+
+    let outbound = module_reference_rollup(
+        &conn,
+        "python:module:pkg.contracts",
+        ReferenceDirection::Out,
+    )
+    .expect("rollup outbound");
+    assert_eq!(
+        outbound.len(),
+        1,
+        "only the external reference rolls up: {outbound:?}"
+    );
+    assert_eq!(outbound[0].neighbor_id, "python:class:pkg.other.Thing");
+    assert_eq!(outbound[0].via_id, "python:class:pkg.contracts.RunStatus");
+}
+
+#[test]
+fn module_reference_rollup_returns_empty_for_module_with_no_contained_edges() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+    insert_entity(&conn, "python:module:pkg.lonely", "module");
+    insert_entity(&conn, "python:class:pkg.lonely.Isolated", "class");
+    insert_contains_edge(
+        &conn,
+        "python:module:pkg.lonely",
+        "python:class:pkg.lonely.Isolated",
+    );
+
+    let inbound =
+        module_reference_rollup(&conn, "python:module:pkg.lonely", ReferenceDirection::In)
+            .expect("rollup inbound");
+    assert!(
+        inbound.is_empty(),
+        "no references means an empty rollup, not an error"
+    );
+}
+
 #[test]
 fn call_edges_targeting_expands_candidate_only_ambiguous_targets() {
     let tempdir = tempfile::tempdir().unwrap();
@@ -659,16 +778,119 @@ fn entity_lookup_and_search_cover_id_and_fts_paths() {
         .expect("entity should exist");
     assert_eq!(entity.kind, "function");
 
-    let fts_results = find_entities(&conn, "TokenManager", 20, 0).expect("FTS search");
+    let fts_results = find_entities(&conn, "TokenManager", 20, 0, None).expect("FTS search");
     assert_eq!(fts_results.len(), 1);
     assert_eq!(fts_results[0].id, "python:function:demo.TokenManager");
 
-    let like_results = find_entities(&conn, "python:function:demo.TokenManager", 20, 0)
+    let like_results = find_entities(&conn, "python:function:demo.TokenManager", 20, 0, None)
         .expect("punctuation-heavy ID search");
     assert_eq!(like_results.len(), 1);
     assert_eq!(like_results[0].id, "python:function:demo.TokenManager");
 }
 
+#[test]
+fn subsystem_of_entity_resolves_module_and_nested_entities() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+    insert_entity(&conn, "core:subsystem:abc", "subsystem");
+    insert_entity(&conn, "python:module:pkg.mod", "module");
+    insert_entity(&conn, "python:class:pkg.mod.Cls", "class");
+    insert_entity(&conn, "python:function:pkg.mod.Cls.method", "function");
+    insert_in_subsystem_edge(&conn, "python:module:pkg.mod", "core:subsystem:abc");
+    insert_contains_edge(&conn, "python:module:pkg.mod", "python:class:pkg.mod.Cls");
+    insert_contains_edge(
+        &conn,
+        "python:class:pkg.mod.Cls",
+        "python:function:pkg.mod.Cls.method",
+    );
+
+    // A module resolves directly (depth 0).
+    let from_module = subsystem_of_entity(&conn, "python:module:pkg.mod")
+        .unwrap()
+        .expect("module should resolve");
+    assert_eq!(from_module.subsystem_id, "core:subsystem:abc");
+    assert_eq!(from_module.via_module_id, "python:module:pkg.mod");
+
+    // A method nested module -> class -> function resolves via its module
+    // ancestor (exercises the recursive walk past a non-module container).
+    let from_method = subsystem_of_entity(&conn, "python:function:pkg.mod.Cls.method")
+        .unwrap()
+        .expect("nested method should resolve");
+    assert_eq!(from_method.subsystem_id, "core:subsystem:abc");
+    assert_eq!(from_method.via_module_id, "python:module:pkg.mod");
+
+    // A module not assigned to any subsystem -> None.
+    insert_entity(&conn, "python:module:orphan", "module");
+    assert!(
+        subsystem_of_entity(&conn, "python:module:orphan")
+            .unwrap()
+            .is_none()
+    );
+
+    // An unknown entity id -> None (no error).
+    assert!(
+        subsystem_of_entity(&conn, "python:function:does.not.exist")
+            .unwrap()
+            .is_none()
+    );
+}
+
+#[test]
+fn find_entities_kind_filter_constrains_results() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+    // Two entities sharing a search term but differing in kind, plus a subsystem
+    // named after the same package (the realistic "find the subsystem" case).
+    insert_entity(&conn, "python:module:demo", "module");
+    insert_entity(&conn, "python:function:demo.run", "function");
+    insert_entity(&conn, "core:subsystem:demo", "subsystem");
+
+    // Unfiltered: all three "demo" entities match (FTS or LIKE path).
+    let all = find_entities(&conn, "demo", 20, 0, None).expect("unfiltered search");
+    assert_eq!(all.len(), 3, "{all:?}");
+
+    // kind=subsystem returns only the subsystem entity.
+    let subs = find_entities(&conn, "demo", 20, 0, Some("subsystem")).expect("kind=subsystem");
+    assert_eq!(subs.len(), 1, "{subs:?}");
+    assert_eq!(subs[0].id, "core:subsystem:demo");
+    assert_eq!(subs[0].kind, "subsystem");
+
+    // kind=function returns only the function.
+    let funcs = find_entities(&conn, "demo", 20, 0, Some("function")).expect("kind=function");
+    assert_eq!(funcs.len(), 1, "{funcs:?}");
+    assert_eq!(funcs[0].id, "python:function:demo.run");
+
+    // An unknown (but well-formed) kind simply matches nothing.
+    let none = find_entities(&conn, "demo", 20, 0, Some("nonesuch")).expect("unknown kind");
+    assert!(none.is_empty(), "{none:?}");
+
+    // A blank kind is rejected as a malformed request.
+    assert!(find_entities(&conn, "demo", 20, 0, Some("  ")).is_err());
+}
+
+#[test]
+fn find_entities_kind_filter_applies_on_punctuation_like_path() {
+    // The punctuation-heavy ID search takes the LIKE branch (not FTS); the kind
+    // filter must apply there too, and bind correctly against the OR-group.
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+    insert_entity(&conn, "python:module:pkg.svc", "module");
+    insert_entity(&conn, "python:function:pkg.svc", "function");
+
+    let like_all = find_entities(&conn, "python:module:pkg.svc", 20, 0, None).expect("like search");
+    assert_eq!(like_all.len(), 1);
+
+    let like_module = find_entities(&conn, "pkg.svc", 20, 0, Some("module")).expect("like+kind");
+    assert!(
+        like_module.iter().all(|e| e.kind == "module"),
+        "{like_module:?}"
+    );
+    assert!(
+        like_module.iter().any(|e| e.id == "python:module:pkg.svc"),
+        "{like_module:?}"
+    );
+}
+
 #[test]
 fn contained_entity_ids_is_depth_first_cycle_safe_and_capped() {
     let tempdir = tempfile::tempdir().unwrap();
@@ -751,3 +973,630 @@ fn normalize_source_path_accepts_project_relative_paths_and_rejects_escape() {
         "unexpected error: {escaped}"
     );
 }
+
+#[test]
+fn resolve_file_surfaces_briefing_blocked_reason_from_properties() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("secret.env");
+    std::fs::write(&source_path, "TOKEN=AKIAIOSFODNN7EXAMPLE\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'core:file:hash-secret@secret.env', 'core', 'file', 'secret.env', 'secret.env', ?1,
+            1, 1, '{\"briefing_blocked\":\"secret_present\"}', 'hash-secret-file',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert briefing-blocked entity");
+
+    let resolved = resolve_file(&conn, project_root, "secret.env", "env")
+        .expect("resolve_file")
+        .expect("entity is known");
+
+    assert_eq!(
+        resolved.briefing_blocked.as_deref(),
+        Some("secret_present"),
+        "resolve_file must surface briefing_blocked reason so federation read \
+         surfaces (HTTP /api/v1/files) can refuse to expose blocked entities"
+    );
+}
+
+#[test]
+fn resolve_file_returns_none_when_no_file_kind_entity_exists() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("demo.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:module:demo', 'python', 'module', 'demo', 'demo', ?1,
+            1, 2, '{}', 'hash-demo-module',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert module entity");
+
+    let resolved =
+        resolve_file(&conn, project_root, "src/demo.py", "python").expect("resolve_file");
+
+    assert!(
+        resolved.is_none(),
+        "resolve_file must fail closed instead of synthesizing a file identity from a module row"
+    );
+}
+
+#[test]
+fn resolve_file_returns_none_briefing_blocked_for_clean_entity() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("demo.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:file:demo', 'python', 'file', 'demo.py', 'demo.py', ?1,
+            1, 2, '{}', 'hash-demo',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert clean entity");
+
+    let resolved = resolve_file(&conn, project_root, "src/demo.py", "python")
+        .expect("resolve_file")
+        .expect("entity is known");
+
+    assert_eq!(resolved.canonical_path.as_str(), "src/demo.py");
+    assert!(
+        !resolved.canonical_path.as_str().starts_with('/')
+            && !resolved.canonical_path.as_str().starts_with("./")
+            && !resolved.canonical_path.as_str().starts_with("../"),
+        "canonical path must be project-relative POSIX: {:?}",
+        resolved.canonical_path
+    );
+    assert!(
+        resolved.briefing_blocked.is_none(),
+        "clean entity must not surface a briefing_blocked reason; got {:?}",
+        resolved.briefing_blocked
+    );
+}
+
+#[test]
+fn resolve_file_deleted_on_disk_but_cataloged_row_resolves() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("deleted.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def gone():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:file:deleted', 'python', 'file', 'deleted.py', 'deleted.py', ?1,
+            1, 2, '{}', 'hash-deleted',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert deleted entity");
+    std::fs::remove_file(&source_path).expect("delete source after cataloging");
+
+    let resolved = resolve_file(&conn, project_root, "src/deleted.py", "python")
+        .expect("resolve_file should use catalog row without requiring disk file")
+        .expect("entity is known");
+
+    assert_eq!(resolved.entity_id, "python:file:deleted");
+    assert_eq!(resolved.content_hash, "hash-deleted");
+    assert_eq!(resolved.canonical_path.as_str(), "src/deleted.py");
+    assert!(
+        !resolved.canonical_path.as_str().starts_with('/')
+            && !resolved.canonical_path.as_str().starts_with("./")
+            && !resolved.canonical_path.as_str().starts_with("../"),
+        "canonical path must be project-relative POSIX: {:?}",
+        resolved.canonical_path
+    );
+}
+
+#[test]
+fn resolve_file_catalog_entry_returns_missing_hash_without_reading_disk() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("missing-hash.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def missing_hash():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:file:missing_hash', 'python', 'file', 'missing-hash.py', 'missing-hash.py', ?1,
+            1, 2, '{}', NULL,
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert file entity without cached hash");
+    std::fs::remove_file(&source_path).expect("delete source after cataloging");
+
+    let entry = resolve_file_catalog_entry(&conn, project_root, "src/missing-hash.py", "python")
+        .expect("catalog lookup should not read deleted source")
+        .expect("entity is known");
+
+    assert_eq!(entry.entity_id, "python:file:missing_hash");
+    assert_eq!(entry.content_hash, None);
+    assert_eq!(entry.canonical_path.as_str(), "src/missing-hash.py");
+    assert_eq!(entry.language, "python");
+}
+
+#[test]
+#[cfg(unix)]
+fn resolve_file_unreadable_hash_failure_propagates() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("unreadable.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def unreadable():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:file:unreadable', 'python', 'file', 'unreadable.py', 'unreadable.py', ?1,
+            1, 2, '{}', NULL,
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert unreadable entity");
+    let original_permissions = std::fs::metadata(&source_path)
+        .expect("source metadata")
+        .permissions();
+    std::fs::set_permissions(&source_path, std::fs::Permissions::from_mode(0o000))
+        .expect("make source unreadable");
+
+    if std::fs::read(&source_path).is_ok() {
+        std::fs::set_permissions(&source_path, original_permissions).expect("restore source perms");
+        eprintln!("skipping unreadable-file assertion because this runner can read 0o000 files");
+        return;
+    }
+
+    let result = resolve_file(&conn, project_root, "src/unreadable.py", "python");
+
+    std::fs::set_permissions(&source_path, original_permissions).expect("restore source perms");
+    let error = result.expect_err("missing catalog hash must propagate hash fallback read failure");
+    assert!(
+        error.to_string().contains("io error"),
+        "unexpected error: {error}"
+    );
+}
+
+#[test]
+fn resolve_file_does_not_echo_invalid_requested_language_over_catalog_inference() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("demo.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'python:file:demo-language', 'python', 'file', 'demo.py', 'demo.py', ?1,
+            1, 2, '{}', 'hash-demo-language',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert python entity");
+
+    let resolved = resolve_file(&conn, project_root, "src/demo.py", "javascript")
+        .expect("resolve_file")
+        .expect("entity is known");
+
+    assert_eq!(resolved.language, "python");
+}
+
+#[test]
+fn resolve_file_prefers_core_extension_inference_over_requested_language() {
+    let tempdir = tempfile::tempdir().expect("temp project root");
+    let project_root = tempdir.path();
+    let source_path = project_root.join("src").join("demo.py");
+    std::fs::create_dir_all(source_path.parent().unwrap()).expect("create source dir");
+    std::fs::write(&source_path, "def entry():\n    return 1\n").expect("write source");
+    let canonical = source_path.canonicalize().expect("canonical source");
+
+    let conn = open_fresh(&tempdir);
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'core:file:src/demo.py', 'core', 'file', 'demo.py', 'demo.py', ?1,
+            1, 2, '{}', 'hash-core-demo',
+            '2026-05-19T00:00:00.000Z', '2026-05-19T00:00:00.000Z'
+         )",
+        params![canonical.display().to_string()],
+    )
+    .expect("insert core file entity");
+
+    let resolved = resolve_file(&conn, project_root, "src/demo.py", "javascript")
+        .expect("resolve_file")
+        .expect("entity is known");
+
+    assert_eq!(resolved.language, "python");
+}
+
+#[test]
+fn entity_briefing_block_reason_parses_property_and_tolerates_garbage() {
+    assert_eq!(
+        entity_briefing_block_reason(r#"{"briefing_blocked":"secret_present"}"#),
+        Some("secret_present".to_owned()),
+    );
+    assert_eq!(
+        entity_briefing_block_reason(r#"{"briefing_blocked":"unscanned_source"}"#),
+        Some("unscanned_source".to_owned()),
+    );
+    // No key.
+    assert_eq!(entity_briefing_block_reason("{}"), None);
+    assert_eq!(entity_briefing_block_reason(r#"{"other":"x"}"#), None);
+    // Wrong type — key present but not a string.
+    assert_eq!(
+        entity_briefing_block_reason(r#"{"briefing_blocked":42}"#),
+        None,
+    );
+}
+
+#[test]
+fn entity_briefing_block_reason_fails_closed_on_malformed_json() {
+    // Fail-closed contract (SEC-01): a plugin emitting malformed
+    // properties JSON must not be able to silently unblock the entity
+    // through the federation read paths. Any parse failure returns
+    // Some("malformed_properties_json") so callers treat the row as
+    // briefing-blocked.
+    let expected = Some("malformed_properties_json".to_owned());
+    assert_eq!(entity_briefing_block_reason(""), expected);
+    assert_eq!(entity_briefing_block_reason("not json"), expected);
+    assert_eq!(entity_briefing_block_reason(r#"{"unterminated"#), expected);
+    assert_eq!(entity_briefing_block_reason(r#"{"x":}"#), expected);
+    // Valid JSON whose root is not an object still parses and follows the
+    // non-malformed path (no `briefing_blocked` key on a JSON `null`/array,
+    // so the reason is `None`).
+    assert_eq!(entity_briefing_block_reason("null"), None);
+    assert_eq!(entity_briefing_block_reason("[]"), None);
+}
+
+fn insert_run(conn: &Connection, run_id: &str) {
+    conn.execute(
+        "INSERT INTO runs (id, started_at, config, stats, status) \
+         VALUES (?1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), '{}', '{}', 'running')",
+        params![run_id],
+    )
+    .expect("insert run");
+}
+
+#[allow(clippy::too_many_arguments)]
+fn insert_finding(
+    conn: &Connection,
+    id: &str,
+    run_id: &str,
+    rule_id: &str,
+    kind: &str,
+    severity: &str,
+    entity_id: &str,
+    related_entities: &str,
+) {
+    conn.execute(
+        "INSERT INTO findings (
+            id, tool, tool_version, run_id, rule_id, kind, severity, confidence,
+            confidence_basis, entity_id, related_entities, message, evidence,
+            properties, supports, supported_by, status, created_at, updated_at
+         ) VALUES (
+            ?1, 'clarion', '1.0.0', ?2, ?3, ?4, ?5, 0.9,
+            'ast_match', ?6, ?7, 'msg', '{}',
+            '{}', '[]', '[]', 'open',
+            strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+            strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         )",
+        params![
+            id,
+            run_id,
+            rule_id,
+            kind,
+            severity,
+            entity_id,
+            related_entities
+        ],
+    )
+    .expect("insert finding");
+}
+
+#[test]
+fn findings_for_emit_joins_entity_path_and_preserves_nullable_location() {
+    let tempdir = tempfile::tempdir().expect("tempdir");
+    let conn = open_fresh(&tempdir);
+
+    insert_run(&conn, "run-1");
+    // A defect anchored to a function with a source location.
+    insert_entity_with_range(
+        &conn,
+        "python:function:auth.tokens.refresh",
+        "function",
+        Path::new("src/auth/tokens.py"),
+        12,
+        20,
+    );
+    // A fact anchored to a subsystem entity — no source_file_path.
+    insert_named_entity(
+        &conn,
+        "core:subsystem:abcd",
+        "subsystem",
+        "abcd",
+        "abcd",
+        None,
+    );
+
+    insert_finding(
+        &conn,
+        "core:finding:run-1:defect",
+        "run-1",
+        "CLA-PY-STRUCTURE-001",
+        "defect",
+        "WARN",
+        "python:function:auth.tokens.refresh",
+        r#"["python:class:auth.sessions::SessionStore"]"#,
+    );
+    insert_finding(
+        &conn,
+        "core:finding:run-1:weak-modularity",
+        "run-1",
+        "CLA-FACT-CLUSTERING-WEAK-MODULARITY",
+        "fact",
+        "INFO",
+        "core:subsystem:abcd",
+        "[]",
+    );
+
+    let rows = findings_for_emit(&conn, "run-1").expect("findings_for_emit");
+    assert_eq!(rows.len(), 2, "both findings returned: {rows:?}");
+
+    // Ordered by finding id: "defect" sorts before "weak-modularity".
+    let defect = &rows[0];
+    assert_eq!(defect.id, "core:finding:run-1:defect");
+    assert_eq!(defect.rule_id, "CLA-PY-STRUCTURE-001");
+    assert_eq!(defect.kind, "defect");
+    assert_eq!(defect.severity, "WARN");
+    assert_eq!(defect.entity_id, "python:function:auth.tokens.refresh");
+    assert_eq!(
+        defect.source_file_path.as_deref(),
+        Some("src/auth/tokens.py")
+    );
+    assert_eq!(defect.source_line_start, Some(12));
+    assert_eq!(defect.source_line_end, Some(20));
+    assert_eq!(defect.confidence, Some(0.9));
+    assert_eq!(
+        defect.related_entities_json,
+        r#"["python:class:auth.sessions::SessionStore"]"#
+    );
+
+    // The subsystem-anchored fact has no source path — the emitter will skip it.
+    let fact = &rows[1];
+    assert_eq!(fact.id, "core:finding:run-1:weak-modularity");
+    assert_eq!(fact.entity_id, "core:subsystem:abcd");
+    assert_eq!(fact.source_file_path, None);
+    assert_eq!(fact.source_line_start, None);
+}
+
+#[test]
+fn findings_for_emit_scopes_to_run_id() {
+    let tempdir = tempfile::tempdir().expect("tempdir");
+    let conn = open_fresh(&tempdir);
+
+    insert_run(&conn, "run-1");
+    insert_run(&conn, "run-2");
+    insert_entity_with_range(
+        &conn,
+        "python:function:demo.f",
+        "function",
+        Path::new("demo.py"),
+        1,
+        2,
+    );
+    insert_finding(
+        &conn,
+        "f-run1",
+        "run-1",
+        "CLA-PY-X",
+        "defect",
+        "WARN",
+        "python:function:demo.f",
+        "[]",
+    );
+    insert_finding(
+        &conn,
+        "f-run2",
+        "run-2",
+        "CLA-PY-X",
+        "defect",
+        "WARN",
+        "python:function:demo.f",
+        "[]",
+    );
+
+    let rows = findings_for_emit(&conn, "run-1").expect("findings_for_emit");
+    assert_eq!(rows.len(), 1);
+    assert_eq!(rows[0].id, "f-run1");
+}
+
+/// Regression for clarion-8b32ba0d02: emission must not leak the path/line of a
+/// `briefing_blocked` entity to Filigree (the read API refuses these; the write
+/// direction must match). A finding on a still-blocked secret-bearing file is
+/// excluded, while an ordinary finding — and the ADR-013 override audit finding,
+/// which rides a *non-blocked* `Overridden` anchor — still emit.
+#[test]
+fn findings_for_emit_excludes_briefing_blocked_anchors() {
+    let tempdir = tempfile::tempdir().expect("tempdir");
+    let conn = open_fresh(&tempdir);
+
+    insert_run(&conn, "run-1");
+
+    // A clean function entity — ordinary finding, must emit.
+    insert_entity_with_range(
+        &conn,
+        "python:function:auth.tokens.refresh",
+        "function",
+        Path::new("src/auth/tokens.py"),
+        12,
+        20,
+    );
+
+    // A secret-scanner anchor for a file the operator OVERRODE
+    // (`--allow-unredacted-secrets`): recorded as Overridden, so its anchor
+    // carries no briefing_blocked reason. The CLA-SEC-UNREDACTED-SECRETS-ALLOWED
+    // audit finding on it must still reach Filigree (ADR-013 audit trail).
+    insert_entity_with_range(
+        &conn,
+        "core:file:allowed.env",
+        "file",
+        Path::new("allowed.env"),
+        1,
+        1,
+    );
+
+    // A secret-scanner anchor for a file that is still BLOCKED (no override):
+    // briefing_blocked = secret_present. Its finding points at the secret's
+    // path/line and must be withheld.
+    conn.execute(
+        "INSERT INTO entities (
+            id, plugin_id, kind, name, short_name, source_file_path,
+            source_line_start, source_line_end, properties, content_hash, created_at, updated_at
+         ) VALUES (
+            'core:file:secret.env', 'core', 'file', 'secret.env', 'secret.env', 'secret.env',
+            7, 7, '{\"briefing_blocked\":\"secret_present\"}', 'hash-secret-file',
+            strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         )",
+        [],
+    )
+    .expect("insert briefing-blocked entity");
+
+    insert_finding(
+        &conn,
+        "core:finding:run-1:a-defect",
+        "run-1",
+        "CLA-PY-STRUCTURE-001",
+        "defect",
+        "WARN",
+        "python:function:auth.tokens.refresh",
+        "[]",
+    );
+    insert_finding(
+        &conn,
+        "core:finding:run-1:b-override-allowed",
+        "run-1",
+        "CLA-SEC-UNREDACTED-SECRETS-ALLOWED",
+        "defect",
+        "ERROR",
+        "core:file:allowed.env",
+        "[]",
+    );
+    insert_finding(
+        &conn,
+        "core:finding:run-1:c-secret-detected",
+        "run-1",
+        "CLA-SEC-SECRET-DETECTED",
+        "defect",
+        "ERROR",
+        "core:file:secret.env",
+        "[]",
+    );
+
+    let rows = findings_for_emit(&conn, "run-1").expect("findings_for_emit");
+    let ids: Vec<&str> = rows.iter().map(|row| row.id.as_str()).collect();
+    assert_eq!(
+        ids,
+        vec![
+            "core:finding:run-1:a-defect",
+            "core:finding:run-1:b-override-allowed",
+        ],
+        "non-blocked findings (incl. the ADR-013 override audit) emit; the \
+         briefing_blocked secret finding is excluded: {rows:?}"
+    );
+    assert!(
+        !ids.contains(&"core:finding:run-1:c-secret-detected"),
+        "finding on a briefing_blocked entity must not be emitted"
+    );
+}
+
+#[test]
+fn containing_module_id_walks_up_to_the_nearest_module() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+
+    // module -> class -> method nesting via `contains`.
+    insert_entity(&conn, "python:module:pkg.mod", "module");
+    insert_entity(&conn, "python:class:pkg.mod.Cls", "class");
+    insert_entity(&conn, "python:function:pkg.mod.Cls.method", "function");
+    insert_contains_edge(&conn, "python:module:pkg.mod", "python:class:pkg.mod.Cls");
+    insert_contains_edge(
+        &conn,
+        "python:class:pkg.mod.Cls",
+        "python:function:pkg.mod.Cls.method",
+    );
+
+    // A nested method resolves up through its class to the module.
+    assert_eq!(
+        containing_module_id(&conn, "python:function:pkg.mod.Cls.method")
+            .expect("query")
+            .as_deref(),
+        Some("python:module:pkg.mod"),
+    );
+    // A module resolves to itself (depth 0).
+    assert_eq!(
+        containing_module_id(&conn, "python:module:pkg.mod")
+            .expect("query")
+            .as_deref(),
+        Some("python:module:pkg.mod"),
+    );
+    // A symbol with no module ancestor returns None.
+    insert_entity(&conn, "python:function:orphan", "function");
+    assert_eq!(
+        containing_module_id(&conn, "python:function:orphan").expect("query"),
+        None,
+    );
+}
diff --git a/crates/clarion-storage/tests/reader_pool.rs b/crates/clarion-storage/tests/reader_pool.rs
index 0053161b..d31a6471 100644
--- a/crates/clarion-storage/tests/reader_pool.rs
+++ b/crates/clarion-storage/tests/reader_pool.rs
@@ -246,3 +246,53 @@ async fn reader_panic_is_caught_as_pool_interact_and_pool_remains_usable() {
         .expect("subsequent reader after a panic should succeed");
     assert_eq!(ok, 99);
 }
+
+// ── eager validation (clarion-e74b6e69e5) ────────────────────────────────────
+
+#[tokio::test]
+async fn open_validated_succeeds_and_reads_on_prepared_db() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = prepared_db(&dir);
+
+    let pool = ReaderPool::open_validated(&path, 2).expect("validated pool");
+    let n: i64 = pool
+        .with_reader(|conn| Ok(conn.query_row("SELECT 7", [], |row| row.get(0))?))
+        .await
+        .expect("reader");
+    assert_eq!(n, 7);
+}
+
+#[tokio::test]
+async fn open_validated_fails_fast_on_missing_db() {
+    let dir = tempfile::tempdir().unwrap();
+    let missing = dir.path().join("does-not-exist.db");
+
+    // Eager validation rejects a missing file up front. (ReaderPool is not
+    // Debug, so we match rather than unwrap_err / format the Result.)
+    match ReaderPool::open_validated(&missing, 2) {
+        Err(clarion_storage::StorageError::Sqlite(_)) => {}
+        Err(other) => panic!("expected a Sqlite error for a missing DB, got {other:?}"),
+        Ok(_) => panic!("open_validated must reject a missing DB"),
+    }
+    // ...whereas the lazy open() happily builds a pool against nothing (the
+    // gap this validation closes): pool construction never touches the file.
+    assert!(
+        ReaderPool::open(&missing, 2).is_ok(),
+        "lazy open() is expected to defer the missing-file error"
+    );
+}
+
+#[tokio::test]
+async fn open_validated_fails_on_corrupt_db() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("corrupt.db");
+    // A non-empty, non-SQLite file: open succeeds lazily but the header read
+    // inside the probe fails — the same surface clarion hook session-start hits.
+    std::fs::write(&path, b"this is definitely not a sqlite database").unwrap();
+
+    match ReaderPool::open_validated(&path, 2) {
+        Err(clarion_storage::StorageError::Sqlite(_)) => {}
+        Err(other) => panic!("expected a Sqlite error for a corrupt DB, got {other:?}"),
+        Ok(_) => panic!("open_validated must reject a corrupt DB"),
+    }
+}
diff --git a/crates/clarion-storage/tests/schema_apply.rs b/crates/clarion-storage/tests/schema_apply.rs
index d29f0412..2376cc80 100644
--- a/crates/clarion-storage/tests/schema_apply.rs
+++ b/crates/clarion-storage/tests/schema_apply.rs
@@ -6,7 +6,7 @@
 
 use rusqlite::{Connection, params};
 
-use clarion_storage::{pragma, schema};
+use clarion_storage::{Writer, error::StorageError, pragma, schema};
 
 fn open_fresh(tempdir: &tempfile::TempDir) -> Connection {
     let path = tempdir.path().join("clarion.db");
@@ -209,6 +209,25 @@ fn migration_0001_extends_summary_cache_for_mcp_staleness_tracking() {
         );
     }
 
+    // summary_cache.entity_id has an FK to entities(id) per V11-STO-03;
+    // seed the parent row first so the INSERT below isn't FK-rejected.
+    conn.execute(
+        "INSERT INTO entities (id, plugin_id, kind, name, short_name, properties, \
+         created_at, updated_at) \
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+        params![
+            "python:function:demo.hello",
+            "python",
+            "function",
+            "demo.hello",
+            "hello",
+            "{}",
+            "2026-05-17T00:00:00.000Z",
+            "2026-05-17T00:00:00.000Z",
+        ],
+    )
+    .expect("seed summary_cache parent entity");
+
     conn.execute(
         "INSERT INTO summary_cache ( \
             entity_id, content_hash, prompt_template_id, model_tier, \
@@ -387,7 +406,11 @@ fn migration_0001_creates_partial_indexes() {
     let tempdir = tempfile::tempdir().unwrap();
     let conn = open_fresh(&tempdir);
     let indexes = index_names(&conn);
-    for expected in &["ix_entities_churn", "ix_entities_scope_rank"] {
+    for expected in &[
+        "ix_entities_churn",
+        "ix_entities_scope_rank",
+        "ix_entities_briefing_blocked",
+    ] {
         assert!(
             indexes.iter().any(|i| i == expected),
             "missing index {expected} in {indexes:?}"
@@ -432,6 +455,59 @@ fn entity_generated_columns_extract_from_properties_json() {
     assert_eq!(churn, Some(42));
 }
 
+#[test]
+fn briefing_blocked_generated_column_reflects_property_and_partial_index() {
+    // The briefing_blocked generated column extracts $.briefing_blocked, is NULL
+    // when the property is absent (so the partial index stays small), and the
+    // partial index query counts exactly the blocked entities (clarion-bdabfd6bca).
+    let tempdir = tempfile::tempdir().unwrap();
+    let conn = open_fresh(&tempdir);
+
+    let insert = |id: &str, props: &str| {
+        conn.execute(
+            "INSERT INTO entities (id, plugin_id, kind, name, short_name, properties, \
+             created_at, updated_at) \
+             VALUES (?1, 'python', 'function', ?1, ?1, ?2, \
+             strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))",
+            params![id, props],
+        )
+        .unwrap();
+    };
+    insert(
+        "python:function:demo.blocked",
+        r#"{"briefing_blocked": "secret_detected"}"#,
+    );
+    insert("python:function:demo.clear", "{}");
+
+    let blocked: Option<String> = conn
+        .query_row(
+            "SELECT briefing_blocked FROM entities WHERE id = ?1",
+            params!["python:function:demo.blocked"],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(blocked.as_deref(), Some("secret_detected"));
+
+    let clear: Option<String> = conn
+        .query_row(
+            "SELECT briefing_blocked FROM entities WHERE id = ?1",
+            params!["python:function:demo.clear"],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(clear, None);
+
+    // The partial index serves "how many entities are withheld" in SQL.
+    let count: i64 = conn
+        .query_row(
+            "SELECT COUNT(*) FROM entities WHERE briefing_blocked IS NOT NULL",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(count, 1);
+}
+
 #[test]
 fn scope_rank_case_mapping_covers_all_six_levels() {
     // Asserts the full CASE table in 0001_initial_schema.sql:
@@ -699,13 +775,13 @@ fn migrations_are_idempotent() {
     let tempdir = tempfile::tempdir().unwrap();
     let mut conn = open_fresh(&tempdir);
     schema::apply_migrations(&mut conn).expect("second apply should be a no-op");
-    assert_eq!(schema::applied_count(&conn).unwrap(), 1);
+    assert_eq!(schema::applied_count(&conn).unwrap(), 2);
     let tables_after = table_names(&conn);
     assert!(tables_after.contains(&"entities".to_owned()));
 }
 
 #[test]
-fn schema_migrations_records_one_row() {
+fn schema_migrations_records_each_applied_migration() {
     let tempdir = tempfile::tempdir().unwrap();
     let conn = open_fresh(&tempdir);
     let count: i64 = conn
@@ -713,15 +789,15 @@ fn schema_migrations_records_one_row() {
             row.get(0)
         })
         .unwrap();
-    assert_eq!(count, 1);
-    let name: String = conn
-        .query_row(
-            "SELECT name FROM schema_migrations WHERE version = 1",
-            [],
-            |row| row.get(0),
-        )
-        .unwrap();
-    assert_eq!(name, "0001_initial_schema");
+    assert_eq!(count, 2);
+    let names: Vec<String> = {
+        let mut stmt = conn
+            .prepare("SELECT name FROM schema_migrations ORDER BY version")
+            .unwrap();
+        let rows = stmt.query_map([], |row| row.get(0)).unwrap();
+        rows.map(std::result::Result::unwrap).collect()
+    };
+    assert_eq!(names, vec!["0001_initial_schema", "0002_briefing_blocked"]);
 }
 
 // ----------------------------------------------------------------------------
@@ -899,3 +975,134 @@ fn runs_status_check_accepts_all_documented_values() {
         .unwrap_or_else(|err| panic!("runs.status={status} rejected unexpectedly: {err}"));
     }
 }
+
+// ----------------------------------------------------------------------------
+// STO-02 (gap-register.md): the writer must self-identify Clarion databases
+// via SQLite's `application_id` header and refuse forward-incompatible
+// `user_version` values. These tests pin the open-time contract.
+// ----------------------------------------------------------------------------
+
+/// Spawn a writer, immediately shut it down, and return whatever Result the
+/// blocking task produced. Used to assert refuse-on-open behaviour without
+/// leaking the spawned task.
+fn spawn_writer_and_drain(path: std::path::PathBuf) -> Result<(), StorageError> {
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(2)
+        .enable_all()
+        .build()
+        .expect("tokio runtime");
+    rt.block_on(async move {
+        let (writer, handle) = Writer::spawn(path, 50, 256)?;
+        // Close the command channel so the actor (if it reached the loop)
+        // exits cleanly; the join then surfaces the open-time error if any.
+        drop(writer);
+        handle.await.expect("writer task did not panic")
+    })
+}
+
+#[test]
+fn open_refuses_db_with_foreign_application_id() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let path = tempdir.path().join("foreign.db");
+    {
+        let conn = Connection::open(&path).unwrap();
+        // `PRAGMA application_id` only writes the header page to disk once
+        // the database file has been materialised by some other write. Touch
+        // a temporary table to force the file out of zero-bytes state.
+        conn.execute_batch(
+            "PRAGMA application_id = 0x7AFEBABE; \
+             CREATE TABLE _touch (x INTEGER); DROP TABLE _touch;",
+        )
+        .expect("set foreign application_id");
+    }
+    let err = spawn_writer_and_drain(path).expect_err(
+        "Writer::spawn must refuse a SQLite file carrying a non-Clarion application_id",
+    );
+    assert!(
+        matches!(
+            err,
+            StorageError::ForeignDatabase {
+                application_id: 0x7AFE_BABE,
+            }
+        ),
+        "expected ForeignDatabase {{ application_id: 0x7AFEBABE }}, got {err:?}"
+    );
+}
+
+#[test]
+fn open_refuses_db_from_future_user_version() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let path = tempdir.path().join("future.db");
+    // Open the file via the normal writer path first so it carries the
+    // Clarion application_id and the v1 schema (the migration runner sets
+    // user_version=1 on apply). Then bump user_version past current and
+    // re-open via the writer — must refuse.
+    {
+        let mut conn = Connection::open(&path).unwrap();
+        pragma::apply_write_pragmas(&conn).unwrap();
+        schema::apply_migrations(&mut conn).unwrap();
+    }
+    {
+        let conn = Connection::open(&path).unwrap();
+        conn.execute_batch(&format!(
+            "PRAGMA user_version = {};",
+            schema::CURRENT_SCHEMA_VERSION + 1
+        ))
+        .expect("bump user_version");
+    }
+
+    let err = spawn_writer_and_drain(path)
+        .expect_err("Writer::spawn must refuse a future-versioned database");
+    let expected_found = schema::CURRENT_SCHEMA_VERSION + 1;
+    let expected_current = schema::CURRENT_SCHEMA_VERSION;
+    assert!(
+        matches!(
+            err,
+            StorageError::FutureUserVersion { found, current }
+                if found == expected_found && current == expected_current
+        ),
+        "expected FutureUserVersion {{ found: {expected_found}, current: \
+         {expected_current} }}, got {err:?}"
+    );
+}
+
+#[test]
+fn open_sets_application_id_on_legacy_db() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let path = tempdir.path().join("legacy.db");
+    // Touch a SQLite file with no application_id set (default 0). Open as a
+    // raw connection so we leave the header at its zero default — no
+    // `apply_write_pragmas` here.
+    {
+        let conn = Connection::open(&path).unwrap();
+        let raw: i64 = conn
+            .query_row("PRAGMA application_id", [], |row| row.get(0))
+            .unwrap();
+        assert_eq!(raw, 0, "fresh SQLite files start at application_id=0");
+        // Force the file to materialise on disk by writing a table; this also
+        // guarantees the header page exists.
+        conn.execute_batch("CREATE TABLE _touch (x INTEGER); DROP TABLE _touch;")
+            .unwrap();
+    }
+
+    // First open via the writer should set the Clarion application_id.
+    spawn_writer_and_drain(path.clone())
+        .expect("Writer::spawn must accept a legacy (application_id=0) file");
+    {
+        let conn = Connection::open(&path).unwrap();
+        let raw: i64 = conn
+            .query_row("PRAGMA application_id", [], |row| row.get(0))
+            .unwrap();
+        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
+        let observed = raw as u32;
+        assert_eq!(
+            observed,
+            pragma::CLARION_APPLICATION_ID,
+            "writer must stamp Clarion application_id on a legacy DB"
+        );
+    }
+
+    // Re-open: must not refuse, application_id is now recognised.
+    spawn_writer_and_drain(path)
+        .expect("Writer::spawn must accept a database it has already stamped");
+}
diff --git a/crates/clarion-storage/tests/writer_actor.rs b/crates/clarion-storage/tests/writer_actor.rs
index 9fe9eb56..a6e65b16 100644
--- a/crates/clarion-storage/tests/writer_actor.rs
+++ b/crates/clarion-storage/tests/writer_actor.rs
@@ -22,6 +22,31 @@ fn prepared_db(dir: &tempfile::TempDir) -> std::path::PathBuf {
     path
 }
 
+/// Direct-SQL entity seed for tests that need an `entities` row but must
+/// bypass the writer's `BeginRun → InsertEntity` protocol (e.g. tests
+/// verifying that non-analyze writer commands work without an active run).
+fn seed_entity_row(path: &std::path::Path, id: &str) {
+    let conn = Connection::open(path).unwrap();
+    conn.execute(
+        "INSERT INTO entities ( \
+            id, plugin_id, kind, name, short_name, properties, \
+            content_hash, created_at, updated_at \
+         ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
+        rusqlite::params![
+            id,
+            "python",
+            "function",
+            id,
+            id.rsplit('.').next().unwrap_or(id),
+            "{}",
+            format!("hash-{id}"),
+            now_iso(),
+            now_iso(),
+        ],
+    )
+    .expect("seed entity row");
+}
+
 fn now_iso() -> String {
     "2026-04-18T00:00:00.000Z".to_owned()
 }
@@ -258,6 +283,12 @@ async fn send<T>(
 async fn summary_cache_writer_commands_do_not_require_active_analyze_run() {
     let dir = tempfile::tempdir().unwrap();
     let path = prepared_db(&dir);
+    // summary_cache.entity_id has an FK to entities(id) (V11-STO-03). Seed the
+    // referenced entity directly so the FK is satisfied without going through
+    // the writer's BeginRun → InsertEntity protocol — the whole point of this
+    // test is that summary_cache writer commands work *without* an active
+    // analyze run.
+    seed_entity_row(&path, "python:function:demo.hello");
     let (writer, handle) = Writer::spawn(path.clone(), 50, 256).unwrap();
     let tx = writer.sender();
 
@@ -542,6 +573,258 @@ async fn round_trip_insert_persists_entity() {
     assert_eq!(kind, "function");
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn insert_entity_is_idempotent_across_runs() {
+    // Regression: `clarion analyze` re-runs against an unchanged corpus
+    // must not crash with `UNIQUE constraint failed: entities.id`. The
+    // insert path UPSERTs on `id`, preserving `created_at`/`first_seen_commit`
+    // and updating the rest from the new run. WS-D smoke gate.
+    let dir = tempfile::tempdir().unwrap();
+    let path = prepared_db(&dir);
+    let (writer, handle) = Writer::spawn(path.clone(), 50, 256).unwrap();
+    let tx = writer.sender();
+
+    let entity_id = "python:function:demo.hello";
+    let first_created = "2026-05-01T00:00:00Z".to_owned();
+    let first_updated = "2026-05-01T00:00:00Z".to_owned();
+    let second_updated = "2026-05-02T00:00:00Z".to_owned();
+
+    // Run 1: insert.
+    send::<()>(&tx, |ack| WriterCmd::BeginRun {
+        run_id: "run-1".into(),
+        config_json: "{}".into(),
+        started_at: now_iso(),
+        ack,
+    })
+    .await
+    .unwrap();
+    let mut e = make_entity(entity_id);
+    e.created_at = first_created.clone();
+    e.updated_at = first_updated.clone();
+    e.first_seen_commit = Some("commit-abc".to_owned());
+    e.last_seen_commit = Some("commit-abc".to_owned());
+    send::<()>(&tx, |ack| WriterCmd::InsertEntity {
+        entity: Box::new(e),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::CommitRun {
+        run_id: "run-1".into(),
+        status: RunStatus::Completed,
+        completed_at: now_iso(),
+        stats_json: "{}".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+
+    // Run 2: re-insert same id with refreshed fields. Must not raise UNIQUE.
+    send::<()>(&tx, |ack| WriterCmd::BeginRun {
+        run_id: "run-2".into(),
+        config_json: "{}".into(),
+        started_at: now_iso(),
+        ack,
+    })
+    .await
+    .unwrap();
+    let mut e2 = make_entity(entity_id);
+    e2.short_name = "hello-v2".to_owned();
+    e2.created_at = "2026-12-31T00:00:00Z".to_owned();
+    e2.updated_at = second_updated.clone();
+    e2.first_seen_commit = Some("commit-NEW-should-be-ignored".to_owned());
+    e2.last_seen_commit = Some("commit-xyz".to_owned());
+    send::<()>(&tx, |ack| WriterCmd::InsertEntity {
+        entity: Box::new(e2),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::CommitRun {
+        run_id: "run-2".into(),
+        status: RunStatus::Completed,
+        completed_at: now_iso(),
+        stats_json: "{}".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+
+    drop(tx);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+
+    let pool = ReaderPool::open(&path, 2).unwrap();
+    let (count, short_name, created_at, updated_at, first_commit, last_commit): (
+        i64,
+        String,
+        String,
+        String,
+        String,
+        String,
+    ) = pool
+        .with_reader(move |conn| {
+            let n: i64 = conn.query_row("SELECT COUNT(*) FROM entities", [], |row| row.get(0))?;
+            let row = conn.query_row(
+                "SELECT short_name, created_at, updated_at, first_seen_commit, last_seen_commit \
+                 FROM entities WHERE id = ?1",
+                rusqlite::params![entity_id],
+                |row| {
+                    Ok((
+                        row.get::<_, String>(0)?,
+                        row.get::<_, String>(1)?,
+                        row.get::<_, String>(2)?,
+                        row.get::<_, String>(3)?,
+                        row.get::<_, String>(4)?,
+                    ))
+                },
+            )?;
+            Ok((n, row.0, row.1, row.2, row.3, row.4))
+        })
+        .await
+        .unwrap();
+    assert_eq!(count, 1, "second InsertEntity must not duplicate the row");
+    assert_eq!(
+        short_name, "hello-v2",
+        "mutable fields refresh on re-insert"
+    );
+    assert_eq!(
+        created_at, first_created,
+        "created_at is preserved across re-insert"
+    );
+    assert_eq!(
+        updated_at, second_updated,
+        "updated_at refreshes to latest run's value"
+    );
+    assert_eq!(
+        first_commit, "commit-abc",
+        "first_seen_commit is preserved across re-insert"
+    );
+    assert_eq!(
+        last_commit, "commit-xyz",
+        "last_seen_commit refreshes to latest run's value"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn resume_run_reopens_existing_row_without_pk_conflict() {
+    // REQ-FINDING-05 `--resume`: reopening a prior run must reuse its `runs`
+    // row, not `INSERT` a second one (which would fail on the run PK — the
+    // documented blocker that made `--resume` more than flag-wiring). After a
+    // completed run, `ResumeRun` flips the row back to `running` / clears
+    // `completed_at`, a re-walk upserts entities, and a second `CommitRun`
+    // finalizes the *same* row.
+    let dir = tempfile::tempdir().unwrap();
+    let path = prepared_db(&dir);
+    let (writer, handle) = Writer::spawn(path.clone(), 50, 256).unwrap();
+    let tx = writer.sender();
+
+    // Original run: begin → insert → complete.
+    send::<()>(&tx, |ack| WriterCmd::BeginRun {
+        run_id: "run-1".into(),
+        config_json: "{}".into(),
+        started_at: now_iso(),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::InsertEntity {
+        entity: Box::new(make_entity("python:function:demo.hello")),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::CommitRun {
+        run_id: "run-1".into(),
+        status: RunStatus::Completed,
+        completed_at: now_iso(),
+        stats_json: "{}".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+
+    // Resume the same run id: must NOT raise `UNIQUE constraint failed: runs.id`.
+    send::<()>(&tx, |ack| WriterCmd::ResumeRun {
+        run_id: "run-1".into(),
+        ack,
+    })
+    .await
+    .expect("ResumeRun must reuse the existing run row, not insert a duplicate");
+    send::<()>(&tx, |ack| WriterCmd::InsertEntity {
+        entity: Box::new(make_entity("python:function:demo.world")),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::CommitRun {
+        run_id: "run-1".into(),
+        status: RunStatus::Completed,
+        completed_at: now_iso(),
+        stats_json: "{}".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+
+    drop(tx);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+
+    let pool = ReaderPool::open(&path, 2).unwrap();
+    let (run_rows, status, entity_count): (i64, String, i64) = pool
+        .with_reader(|conn| {
+            let run_rows: i64 =
+                conn.query_row("SELECT COUNT(*) FROM runs", [], |row| row.get(0))?;
+            let status: String =
+                conn.query_row("SELECT status FROM runs WHERE id = 'run-1'", [], |row| {
+                    row.get(0)
+                })?;
+            let entity_count: i64 =
+                conn.query_row("SELECT COUNT(*) FROM entities", [], |row| row.get(0))?;
+            Ok((run_rows, status, entity_count))
+        })
+        .await
+        .unwrap();
+    assert_eq!(
+        run_rows, 1,
+        "resume reuses the run row — no second `runs` row"
+    );
+    assert_eq!(
+        status, "completed",
+        "the resumed run finalizes to completed"
+    );
+    assert_eq!(
+        entity_count, 2,
+        "both walks' entities persist under one run"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn resume_run_errors_when_run_id_unknown() {
+    // Resuming a run id that was never begun is a caller error, not a silent
+    // no-op or an accidental insert.
+    let dir = tempfile::tempdir().unwrap();
+    let path = prepared_db(&dir);
+    let (writer, handle) = Writer::spawn(path.clone(), 50, 256).unwrap();
+    let tx = writer.sender();
+
+    let err = send::<()>(&tx, |ack| WriterCmd::ResumeRun {
+        run_id: "never-begun".into(),
+        ack,
+    })
+    .await
+    .expect_err("resuming an unknown run id must error");
+    assert!(
+        matches!(err, clarion_storage::StorageError::WriterProtocol(ref m) if m.contains("never-begun")),
+        "error names the missing run id: {err}"
+    );
+
+    drop(tx);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn non_core_plugin_cannot_insert_reserved_entity_kind() {
     let dir = tempfile::tempdir().unwrap();
@@ -705,6 +988,134 @@ async fn writer_inserts_fact_findings() {
     );
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn insert_finding_is_idempotent_on_resume() {
+    // REQ-FINDING-05 `--resume`: a finding id embeds its run_id, so a resume
+    // re-walk regenerates the same id. `InsertFinding` must UPSERT (refresh
+    // analysis-derived fields, preserve `created_at` and lifecycle) rather than
+    // fail on `UNIQUE constraint: findings.id`.
+    let dir = tempfile::tempdir().unwrap();
+    let path = prepared_db(&dir);
+    let (writer, handle) = Writer::spawn(path.clone(), 50, 256).unwrap();
+    let tx = writer.sender();
+
+    let finding = |message: &str, created_at: &str, updated_at: &str| FindingRecord {
+        id: "core:finding:run-resume:weak-modularity".to_owned(),
+        tool: "clarion".to_owned(),
+        tool_version: "1.0.0".to_owned(),
+        run_id: "run-resume".to_owned(),
+        rule_id: "CLA-FACT-CLUSTERING-WEAK-MODULARITY".to_owned(),
+        kind: "fact".to_owned(),
+        severity: "INFO".to_owned(),
+        confidence: Some(0.9),
+        confidence_basis: Some("deterministic".to_owned()),
+        entity_id: "python:module:demo".to_owned(),
+        related_entities_json: r#"["python:module:demo"]"#.to_owned(),
+        message: message.to_owned(),
+        evidence_json: r#"{"modularity_score":0.0}"#.to_owned(),
+        properties_json: r#"{"threshold":0.25}"#.to_owned(),
+        supports_json: "[]".to_owned(),
+        supported_by_json: "[]".to_owned(),
+        created_at: created_at.to_owned(),
+        updated_at: updated_at.to_owned(),
+    };
+
+    // Original run: insert the finding.
+    begin_demo_run(&tx, "run-resume").await;
+    send::<()>(&tx, |ack| WriterCmd::InsertEntity {
+        entity: Box::new(make_module_entity("python:module:demo")),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::InsertFinding {
+        finding: Box::new(finding(
+            "first message",
+            "2026-05-01T00:00:00Z",
+            "2026-05-01T00:00:00Z",
+        )),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::CommitRun {
+        run_id: "run-resume".into(),
+        status: RunStatus::Completed,
+        completed_at: now_iso(),
+        stats_json: "{}".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+
+    // Resume: re-insert the same finding id with a refreshed message. Must not
+    // raise UNIQUE; must refresh `message`/`updated_at`, preserve `created_at`.
+    send::<()>(&tx, |ack| WriterCmd::ResumeRun {
+        run_id: "run-resume".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+    send::<()>(&tx, |ack| WriterCmd::InsertFinding {
+        finding: Box::new(finding(
+            "refreshed message",
+            "2099-01-01T00:00:00Z",
+            "2026-05-02T00:00:00Z",
+        )),
+        ack,
+    })
+    .await
+    .expect("re-inserting a run-scoped finding id on resume must upsert, not error");
+    send::<()>(&tx, |ack| WriterCmd::CommitRun {
+        run_id: "run-resume".into(),
+        status: RunStatus::Completed,
+        completed_at: now_iso(),
+        stats_json: "{}".into(),
+        ack,
+    })
+    .await
+    .unwrap();
+
+    drop(tx);
+    drop(writer);
+    handle.await.unwrap().unwrap();
+
+    let conn = Connection::open(path).unwrap();
+    let (count, message, status, created_at, updated_at): (i64, String, String, String, String) =
+        conn.query_row(
+            "SELECT COUNT(*), MAX(message), MAX(status), MAX(created_at), MAX(updated_at) \
+             FROM findings WHERE id = 'core:finding:run-resume:weak-modularity'",
+            [],
+            |row| {
+                Ok((
+                    row.get(0)?,
+                    row.get(1)?,
+                    row.get(2)?,
+                    row.get(3)?,
+                    row.get(4)?,
+                ))
+            },
+        )
+        .unwrap();
+    assert_eq!(count, 1, "resume upserts the finding — no duplicate row");
+    assert_eq!(
+        message, "refreshed message",
+        "analysis-derived fields refresh"
+    );
+    assert_eq!(
+        status, "open",
+        "lifecycle status is preserved across resume"
+    );
+    assert_eq!(
+        created_at, "2026-05-01T00:00:00Z",
+        "created_at (first-seen) is preserved across resume",
+    );
+    assert_eq!(
+        updated_at, "2026-05-02T00:00:00Z",
+        "updated_at refreshes to the resume walk's value",
+    );
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn entity_source_file_id_rejects_non_source_anchor_entity() {
     let dir = tempfile::tempdir().unwrap();
diff --git a/docs/README.md b/docs/README.md
index a7094144..d9c50eec 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,12 +10,12 @@ This `docs/` tree is organized by reader intent:
 
 - New to the suite: [suite/briefing.md](./suite/briefing.md)
 - Evaluating the Loom doctrine: [suite/loom.md](./suite/loom.md)
-- Starting Clarion v0.1: [clarion/v0.1/README.md](./clarion/v0.1/README.md)
+- Starting Clarion v1.0: [clarion/1.0/README.md](./clarion/1.0/README.md)
 - Configuring OpenRouter: [operator/openrouter.md](./operator/openrouter.md)
 
 ## Canonical vs supporting docs
 
 - Canonical suite docs live in [suite/](./suite/README.md).
-- Canonical Clarion v0.1 design docs live in [clarion/v0.1/](./clarion/v0.1/README.md).
-- Supporting reviews and planning history live alongside the relevant version under `reviews/` and `plans/`.
+- Canonical Clarion v0.1 design docs live in [clarion/v0.1/](./clarion/1.0/README.md).
 - Architecture decisions live in [clarion/adr/](./clarion/adr/README.md).
+- Supporting reviews, scope memos, sprint plans, and agent handoffs are archived under [implementation/](./implementation/README.md) — non-normative.
diff --git a/docs/arch-analysis-2026-05-18-1244/00-coordination.md b/docs/arch-analysis-2026-05-18-1244/00-coordination.md
deleted file mode 100644
index cb4fa9b6..00000000
--- a/docs/arch-analysis-2026-05-18-1244/00-coordination.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# Analysis Coordination Plan
-
-## Configuration
-
-- **Scope**: Full repo (`crates/`, `plugins/`, `tests/`, `fixtures/`, `docs/`)
-- **Deliverables**: **Option A — Full Analysis** (auto-selected per user "no clarifying questions" directive; user explicitly asked for a "detailed report")
-  - `01-discovery-findings.md`
-  - `02-subsystem-catalog.md`
-  - `03-diagrams.md`
-  - `04-final-report.md`
-- **Strategy**: **PARALLEL** (6 candidate subsystems, loosely coupled along crate boundaries)
-- **Tier**: MEDIUM (~30k LOC, 6 subsystem candidates, well below ultralarge thresholds)
-- **Time constraint**: None stated
-- **Complexity estimate**: Medium — well-documented codebase with ADRs, REQ IDs, and recent sprint sign-offs to cross-check against findings
-
-## Subsystem candidates (pre-discovery hypothesis)
-
-1. `clarion-core` — entity-ID assembler, plugin host, JSON-RPC transport, jail/limits
-2. `clarion-storage` — writer-actor + reader-pool over SQLite (ADR-011)
-3. `clarion-cli` — `clarion` binary (`install`, `analyze`)
-4. `clarion-mcp` — MCP server (Sprint-2 work, new since Sprint-1 docs were written)
-5. `clarion-plugin-fixture` — test-only fixture plugin
-6. `plugins/python` — Python language plugin (JSON-RPC peer)
-
-`tests/e2e` and `fixtures/` are cross-cutting; will be folded into the relevant subsystems.
-
-## Execution log
-
-- 2026-05-18 12:44 — Created workspace
-- 2026-05-18 12:44 — Auto-selected Option A (no-clarifying-questions directive in force)
-- 2026-05-18 12:44 — Scale assessed: 24 462 Rust + 5 629 Python LOC, 5 crates + 1 plugin → MEDIUM tier, PARALLEL strategy
-- 2026-05-18 12:49 — `01-discovery-findings.md` written by `codebase-explorer` (384 lines)
-- 2026-05-18 12:51 — Dispatched 5 parallel `codebase-explorer` agents (one per subsystem; fixture folded into Python plugin pass)
-- 2026-05-18 12:55 — All 5 section files received (clarion-core, clarion-storage, clarion-mcp, clarion-cli, python plugin + fixture)
-- 2026-05-18 13:00 — `02-subsystem-catalog.md` assembled (648 lines including index + footnotes)
-- 2026-05-18 13:00 — Validation gate spawned (`analysis-validator`) → NEEDS_REVISION (warnings); one factual contradiction (fixture/clarion-core dep) corrected in-place, footnote added for LOC drift
-- 2026-05-18 13:03 — `03-diagrams.md` written by coordinator using Mermaid Chart MCP validator for syntax checks; 5 diagrams (Context, Container, analyze sequence, MCP summary sequence, plugin-host component)
-- 2026-05-18 13:06 — Validation gate spawned for diagrams → APPROVED
-- 2026-05-18 13:10 — `04-final-report.md` written by coordinator (synthesis layer)
-- 2026-05-18 13:13 — Validation gate spawned for final report → NEEDS_REVISION (warnings); 5 stale numeric facts (LOC + commit count + diff stat + one line number + WP count) corrected in-place; commit hash `363bb0a` pinned in report header
-- 2026-05-18 13:14 — Workflow complete; all deliverables in workspace
-
-## Outcomes
-
-| Deliverable | Status |
-|---|---|
-| `01-discovery-findings.md` | Written (single-explorer pass, no validation gate required) |
-| `02-subsystem-catalog.md` | Validated NEEDS_REVISION (warnings) → corrections applied |
-| `03-diagrams.md` | Validated APPROVED |
-| `04-final-report.md` | Validated NEEDS_REVISION (warnings) → corrections applied; commit hash pinned |
diff --git a/docs/arch-analysis-2026-05-18-1244/01-discovery-findings.md b/docs/arch-analysis-2026-05-18-1244/01-discovery-findings.md
deleted file mode 100644
index 30fbca6a..00000000
--- a/docs/arch-analysis-2026-05-18-1244/01-discovery-findings.md
+++ /dev/null
@@ -1,384 +0,0 @@
-# 01 — Discovery Findings
-
-**Repository:** `/home/john/clarion`
-**Branch:** `sprint-2/b8-scale-test` (11 commits ahead of `main`)
-**Tags present:** `v0.1-sprint-1`, `v0.1-sprint-2`
-**Discovery pass run:** 2026-05-18
-**Methodology:** SME Agent Protocol — metadata → structure → routers → sampling → quantitative. No depth-reads on sibling-subsystem files; that's the next pass.
-
----
-
-## 1. Repository organisation
-
-### 1.1 Top-level layout (Confidence: High — `ls /home/john/clarion`)
-
-```
-/home/john/clarion
-├── Cargo.toml          workspace root (5-member virtual workspace)
-├── Cargo.lock
-├── CLAUDE.md           project doctrine + filigree workflow
-├── rust-toolchain.toml
-├── rustfmt.toml
-├── clippy.toml
-├── deny.toml           cargo-deny config (ADR-023 floor)
-├── crates/             5 Rust crates (workspace members)
-├── plugins/python/     Python plugin (installed via `pip install -e plugins/python[dev]`)
-├── tests/              cross-crate e2e + perf harnesses
-│   ├── e2e/            two bash scripts: Sprint-1 walking skeleton + Sprint-2 MCP surface
-│   └── perf/           B.5 reference-scale smoke + B.8 scale-test harness + result snapshots
-├── fixtures/           single file — `entity_id.json` (cross-language L2 parity proof)
-├── scripts/            (not deep-read in this pass)
-├── docs/               doctrine + design + ADRs + implementation plans (79 .md files)
-└── target/             cargo build artifacts (gitignored)
-```
-
-### 1.2 Organisation principle (Confidence: High — `Cargo.toml` workspace + crate-name semantics)
-
-Clarion is organised as a **plugin-extensible monolith with a layered Rust core**:
-
-- **Layer-by-crate**: `clarion-core` (domain types + plugin host) → `clarion-storage` (SQLite persistence) → `clarion-mcp` (read surface) → `clarion-cli` (binary glue). The CLI depends transitively on every other crate; `clarion-mcp` and `clarion-storage` depend on `clarion-core`; `clarion-storage` does not depend on `clarion-mcp`. No circular references at the crate level.
-- **Plugin-extensible**: language plugins are *out-of-process subprocesses* spoken to over Content-Length-framed JSON-RPC. `crates/clarion-plugin-fixture/` is a Rust test plugin; `plugins/python/` is the real Python plugin. This is enforced by ADR-021 (plugin authority — hybrid) and ADR-022 (core/plugin ontology ownership).
-- **Per-product documentation**: `docs/clarion/` is product-scoped; `docs/suite/` is Loom-federation-scoped; `docs/implementation/sprint-{1,2}/` is execution-scoped. No documentation lives next to source modules.
-
-The principle "the core never invents kinds" (ADR-022) is the load-bearing organisational rule: the plugin owns segment 1 (plugin_id) and segment 3 (canonical qualified name) of every entity ID; the core owns segment 2 (kind) only at the schema level.
-
----
-
-## 2. Technology stack
-
-### 2.1 Rust toolchain (Confidence: High — `rust-toolchain.toml` + `Cargo.toml`)
-
-- **Edition**: 2024 (workspace-wide)
-- **MSRV**: 1.85 (`Cargo.toml:8`)
-- **Resolver**: 3
-- **Lint floor** (workspace lints, `Cargo.toml:13–22`):
-  - `unsafe_code = "deny"` (downgraded from `forbid` per documented exception: `CommandExt::pre_exec` calling `setrlimit(2)` in the forked plugin child)
-  - `clippy::pedantic = warn` at `priority = -1`, with three pragmatic allows: `module_name_repetitions`, `must_use_candidate`, `missing_errors_doc`
-
-### 2.2 Workspace dependencies (Confidence: High — `Cargo.toml` `[workspace.dependencies]`)
-
-Heavy hitters by responsibility:
-
-- **Async runtime**: `tokio 1` (`rt-multi-thread, macros, sync, time`)
-- **Storage**: `rusqlite 0.31` (bundled), `deadpool-sqlite 0.8` (reader pool per ADR-011)
-- **HTTP**: `reqwest 0.12` (blocking + JSON + `rustls-tls-native-roots`; no native OpenSSL)
-- **Serialisation**: `serde 1`, `serde_json 1`, `toml 0.8`, `serde_norway 0.9` (YAML — replaces unsound `serde_yaml`, see commit `9ffc5c8`)
-- **CLI / errors**: `clap 4` (derive), `anyhow 1`, `thiserror 1`
-- **Hashing / IDs**: `blake3 1.8.5`, `uuid 1` (v4)
-- **Observability**: `tracing 0.1` + `tracing-subscriber 0.3` (`env-filter`)
-- **POSIX limits**: `nix 0.28` (`resource` feature only) — used by `apply_prlimit_as` / `apply_prlimit_nofile_nproc`
-- **Configuration helper**: `dotenvy 0.15` (loaded in `main.rs` before tracing init)
-- **Test scaffolding**: `assert_cmd 2`, `tempfile 3`
-
-### 2.3 Python plugin toolchain (Confidence: High — `plugins/python/pyproject.toml`)
-
-- **Build backend**: `hatchling`
-- **Python**: `>=3.11`, targets 3.11 + 3.12
-- **Runtime deps** (intentionally tiny — the plugin is a stdlib-first ast walker):
-  - `packaging>=24` — version-range comparison for Wardline pin
-  - `pyright==1.1.409` — pinned exact-version for cross-reference resolution (`pyright_session.py`, the largest Python file at 1251 lines)
-- **Dev deps**: `pytest 8+`, `pytest-cov 5+`, `ruff 0.6+`, `mypy 1.11+`, `pre-commit 3.8+`
-- **Lint/format/typecheck**: `ruff select = ["ALL"]` with pragmatic ignores (D, COM812, ISC001, CPY, ANN401, TRY003); `mypy --strict`; `max-complexity = 15` to match Rust clippy
-- **Script entry**: `clarion-plugin-python = "clarion_plugin_python.__main__:main"`
-- **Manifest packaging**: hatch shared-data routes `plugin.toml` → `share/clarion/plugins/python/plugin.toml` so the core's L9 PATH discovery finds it.
-
-### 2.4 Plugin manifest (`plugins/python/plugin.toml`)
-
-The plugin declares its capabilities at install time (Confidence: High — full file read):
-
-- `plugin_id = "python"`, `protocol_version = "1.0"`
-- `expected_max_rss_mb = 2048` (clamped against core 2 GiB ceiling per ADR-021 §2b)
-- `expected_entities_per_file = 5000`
-- `wardline_aware = true`, `reads_outside_project_root = false`
-- `[ontology] entity_kinds = ["function", "class", "module"]`, `edge_kinds = ["contains", "calls", "references"]`, `ontology_version = "0.5.0"` (B.5* MINOR bump per ADR-027)
-- `rule_id_prefix = "CLA-PY-"` (ADR-022 grammar)
-- Wardline pin: `min_version = "1.0.0", max_version = "2.0.0"`
-
----
-
-## 3. Entry points
-
-### 3.1 Single binary: `clarion` (Confidence: High — `crates/clarion-cli/src/main.rs:1–25`)
-
-```rust
-match cli.command {
-    Command::Install { force, path } => install::run(&path, force),
-    Command::Analyze { path } => block_on(analyze::run(path)),
-    Command::Serve { path, config } => serve::run(&path, config.as_deref()),
-}
-```
-
-Three CLI subcommands (`crates/clarion-cli/src/cli.rs:1–45`):
-
-- `clarion install [--path PATH] [--force]` — initialise `.clarion/clarion.db` against the current schema migration.
-- `clarion analyze [PATH]` — discover plugins via L9 `$PATH` convention, walk source tree, spawn plugin processes, persist entities/edges via writer-actor.
-- `clarion serve [--path PATH] [--config PATH]` — **new in Sprint 2** — run the MCP stdio server (`serve.rs:1–90`). Reads `clarion.yaml`, wires the LLM provider (OpenRouter, Recording, or disabled), wires the optional Filigree HTTP client, and dispatches to `clarion_mcp::serve_stdio_with_state_on_runtime`.
-
-A `.env` file is loaded from CWD or any ancestor *before* tracing init (commit `dc9bf41`); existing process env vars win per dotenvy default.
-
-### 3.2 Plugin process entry: `clarion-plugin-python`
-
-`plugins/python/src/clarion_plugin_python/__main__.py` (15 lines, all of it shown):
-
-```python
-from clarion_plugin_python.server import main
-if __name__ == "__main__":
-    sys.exit(main())
-```
-
-`server.py` (285 lines) speaks the L4 five-method JSON-RPC protocol: `initialize`, `initialized`, `analyze_file`, `shutdown`, `exit`. `MAX_CONTENT_LENGTH = 8 MiB` matches the host's ADR-021 §2b ceiling. `stdout_guard.py` (62 lines) replaces stdout with a strict transport channel so stray `print()` cannot corrupt the wire.
-
-### 3.3 Test fixture plugin: `clarion-plugin-fixture`
-
-`crates/clarion-plugin-fixture/src/main.rs` (128 lines) — Rust binary that speaks the same L4 protocol as the Python plugin; consumed only by `wp2_e2e` integration tests.
-
-### 3.4 Integration-test entry points
-
-- `tests/e2e/sprint_1_walking_skeleton.sh` — runs the README §3 demo verbatim; asserts SQLite returns Python module/function entities, source ranges, content hashes, and resolved+ambiguous call edges and references.
-- `tests/e2e/sprint_2_mcp_surface.sh` — exists (not deep-read this pass); presumably exercises the seven MCP tools.
-- `tests/perf/b8_scale_test/driver.py` — 816-line scale-test harness against the `elspeth` corpus (and `tests/perf/elspeth_mini/`).
-
----
-
-## 4. Subsystem identification
-
-The 6-candidate hypothesis is **confirmed**. Refined per crate evidence below.
-
-### Subsystem A — `clarion-core` (~3 100 LOC actual code, 10 686 LOC including tests)
-
-- **Location**: `crates/clarion-core/src/`
-- **One-sentence responsibility**: Owns the canonical entity-ID format, the plugin host (subprocess supervisor + JSON-RPC peer), the LLM-provider abstraction, and the jail/limits ceilings that all other crates use.
-- **Primary modules** (Confidence: High — `ls` + per-file LOC):
-  - `entity_id.rs` (610 LOC) — three-segment ID assembler (`{plugin_id}:{kind}:{canonical_qualified_name}`); cross-validated against `fixtures/entity_id.json` (L2 parity proof).
-  - `llm_provider.rs` (948 LOC) — `LlmProvider` trait, `OpenRouterProvider`, `RecordingProvider` (test-mode), prompt templates for leaf-summary and inferred-calls (`LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `INFERRED_CALLS_PROMPT_VERSION`).
-  - `plugin/` submodule (~7 400 LOC across 9 files):
-    - `host.rs` (3126 LOC) — supervisor; the single largest file in the codebase
-    - `manifest.rs` (1508 LOC) — `plugin.toml` parser + validator (ADR-021/ADR-022)
-    - `protocol.rs` (846 LOC) — JSON-RPC 2.0 typed envelopes
-    - `mock.rs` (897 LOC, `#[cfg(test)]`) — in-process mock plugin for unit tests
-    - `discovery.rs` (637 LOC) — `$PATH` scanning for `clarion-plugin-*` executables
-    - `transport.rs` (568 LOC) — Content-Length framing
-    - `limits.rs` (552 LOC) — entity-cap, frame-oversize, RSS, prlimit application
-    - `breaker.rs` (360 LOC) — crash-loop circuit breaker (ADR-002 §UQ-WP2-10)
-    - `jail.rs` (253 LOC) — path-jail enforcement (ADR-021 §2a)
-- **External interface**: Rust-only — re-exports a curated facade through `lib.rs` (47 lines; see commit `ticket clarion-29acbcd042` policy note). Implementation types stay accessible via `clarion_core::plugin::transport::*` and siblings.
-
-### Subsystem B — `clarion-storage` (~1 950 LOC actual code, 5 453 LOC with tests)
-
-- **Location**: `crates/clarion-storage/src/`
-- **One-sentence responsibility**: Writer-actor + reader-pool over a single SQLite database at `.clarion/clarion.db`, with all writes funnelled through one `tokio::task` per ADR-011.
-- **Modules**:
-  - `writer.rs` (817 LOC) — writer-actor command loop; owns the sole write `rusqlite::Connection`; enforces edge contract (`enforce_edge_contract`, called out at `writer.rs:411` in ADR-031).
-  - `query.rs` (569 LOC) — read-side helpers for MCP tools (graph navigation: `call_edges_from`, `contained_entity_ids`, `entity_at_line`, `find_entities`, etc.).
-  - `commands.rs` (183 LOC) — `WriterCmd`, `EntityRecord`, `EdgeRecord`, `InferredCallEdgeRecord`, `RunStatus` — typed enums at the command boundary.
-  - `cache.rs` (251 LOC) — `SummaryCacheKey` (5-tuple per ADR-007), `InferredEdgeCacheKey`, `summary_cache_lookup`, `inferred_edge_cache_lookup`.
-  - `unresolved.rs` (50 LOC) — unresolved call-site bookkeeping (B.4*).
-  - `schema.rs` (118 LOC) — migration runner.
-  - `pragma.rs` (45 LOC) — PRAGMA block (WAL, busy_timeout, etc.).
-  - `reader.rs` (88 LOC) — `deadpool-sqlite` pool wrapper.
-  - `error.rs` (48 LOC) — `StorageError` taxonomy.
-- **Schema**: single migration at `crates/clarion-storage/migrations/0001_initial_schema.sql` (289 lines). Per the migration's own comment block, the file is edit-in-place under ADR-024 until an external operator builds a `.clarion/clarion.db` from a published build. The 2026-05-18 edits added `CHECK` constraints on closed core-owned vocabularies (`findings.{kind,severity,status}`, `runs.status`) per ADR-031; `entities.kind` and `edges.kind` deliberately do *not* gain CHECKs because their vocabularies are plugin-extensible.
-- **External interface**: `WriterCmd` enum + `ReaderPool` + query helpers, exposed via `lib.rs` re-exports (40 LOC).
-
-### Subsystem C — `clarion-mcp` (~3 200 LOC actual code, 4 917 LOC with tests) — *Sprint-2 new*
-
-- **Location**: `crates/clarion-mcp/src/`
-- **One-sentence responsibility**: Speaks MCP protocol revision `2025-11-25` over stdio; serves seven storage-backed read tools to consult-mode LLM agents; integrates the LLM provider for on-demand summaries and inferred call edges; integrates Filigree as an enrichment source.
-- **Modules**:
-  - `lib.rs` (2617 LOC) — `ServerState`, tool dispatch, the seven `ToolDefinition`s, dispatch glue to `clarion-storage` query helpers and `clarion-core::LlmProvider`. Massive single file; could plausibly subdivide.
-  - `config.rs` (352 LOC) — `McpConfig`, `LlmConfig`, `ProviderSelection`, `select_provider_with_env`. YAML via `serde_norway` (the safe `serde_yaml` replacement).
-  - `filigree.rs` (238 LOC) — `FiligreeHttpClient`, `EntityAssociation`, `EntityAssociationsResponse`, `FiligreeLookup` trait (allows mocking).
-- **Seven tools** (from `lib.rs::list_tools`):
-  1. `entity_at` — innermost entity containing (file, line)
-  2. `find_entity` — FTS search on id/name/short_name/summary
-  3. `callers_of` — incoming call edges; default confidence `resolved`
-  4. `execution_paths_from` — bounded calls-only paths; max_depth ≤ 8, default 3
-  5. `summary` — on-demand cached leaf summary (ADR-030 narrows to leaf scope for v0.1)
-  6. `issues_for` — Filigree enrichment (enrich-only per Loom doctrine; unavailable envelope on Filigree downtime)
-  7. `neighborhood` — one-hop graph view (callers, callees, container, contained, references)
-- **External interface**: MCP stdio protocol; consumed by LLM agent clients via `clarion serve`.
-
-### Subsystem D — `clarion-cli` (~1 740 LOC actual code, 3 275 LOC with tests)
-
-- **Location**: `crates/clarion-cli/src/`
-- **One-sentence responsibility**: Glue binary; `clap`-driven subcommand dispatch (`install`, `analyze`, `serve`) wiring `clarion-core` (plugin host) + `clarion-storage` (writer-actor + pool) + `clarion-mcp` (server).
-- **Modules**:
-  - `main.rs` (33 LOC) — entrypoint; loads `.env`, parses CLI, dispatches.
-  - `cli.rs` (45 LOC) — `clap` derive structs.
-  - `analyze.rs` (1436 LOC) — orchestrates plugin discovery, source-tree walk, plugin handshake, per-file dispatch, writer-actor flushing, crash-loop accounting, error mapping to `FailRun` vs `SkippedNoPlugins`.
-  - `serve.rs` (136 LOC) — MCP server wiring (LLM provider build, Filigree client build, runtime + reader pool + writer wiring, stdio loop).
-  - `install.rs` (168 LOC) — `.clarion/` bootstrap + migration apply.
-  - `stats.rs` (small) — `P95Accumulator` helper for analyze-time latency reporting.
-- **Integration tests** (`crates/clarion-cli/tests/`):
-  - `install.rs`, `analyze.rs`, `serve.rs` — per-subcommand black-box tests via `assert_cmd`.
-  - `wp1_e2e.rs`, `wp2_e2e.rs` — WP-level walking-skeleton tests; `wp2_e2e` consumes the `clarion-plugin-fixture` binary on disk.
-
-### Subsystem E — `clarion-plugin-fixture` (131 LOC, 2 source files)
-
-- **Location**: `crates/clarion-plugin-fixture/src/`
-- **One-sentence responsibility**: Test-only Rust plugin speaking the L4 protocol; lets WP2 tests verify the host without bringing Python into the loop.
-- **Modules**: `main.rs` (128 LOC) — full process entry; `lib.rs` (3 LOC) — re-export shim.
-- **External interface**: stdin/stdout JSON-RPC, identical to Python plugin.
-
-### Subsystem F — `plugins/python` (Python plugin, 2670 LOC)
-
-- **Location**: `plugins/python/src/clarion_plugin_python/`
-- **One-sentence responsibility**: Python language plugin — extracts module/class/function entities and `contains` + `calls` + `references` edges from a Python source tree; uses `pyright-langserver` for cross-reference resolution; speaks L4 JSON-RPC to the Rust host.
-- **Modules** (by size):
-  - `pyright_session.py` (1251 LOC) — long-running `pyright-langserver` LSP client; the heaviest single file.
-  - `extractor.py` (744 LOC) — AST-based entity extraction; **modified on this branch** (+98 LOC, B.8 `@overload`-stub deduplication fix).
-  - `server.py` (285 LOC) — JSON-RPC dispatch loop.
-  - `entity_id.py` (75 LOC) — cross-language entity-ID assembler (parity-tested against `fixtures/entity_id.json`).
-  - `reference_resolver.py` (69 LOC) — references-edge collection (B.5*).
-  - `call_resolver.py` (64 LOC) — calls-edge resolution (B.4*).
-  - `stdout_guard.py` (62 LOC) — keeps stray prints off the wire.
-  - `wardline_probe.py` (56 LOC) — L8 Wardline-presence probe, reported in handshake `capabilities`.
-  - `qualname.py` (46 LOC) — Python-flavoured canonical qualname per ADR-018.
-  - `__main__.py` (15 LOC) / `__init__.py` (3 LOC).
-- **External interface**: stdin/stdout JSON-RPC, console-script `clarion-plugin-python` on `$PATH`, manifest at `share/clarion/plugins/python/plugin.toml`.
-
----
-
-## 5. Cross-cutting concerns
-
-(Confidence: High where ADRs back the claim; Medium where inferred from imports.)
-
-- **Entity-ID format** — ADR-003 + ADR-022. Three colon-segments. Cross-validated by `fixtures/entity_id.json` against both the Rust `entity_id.rs` (610 LOC) and Python `entity_id.py` (75 LOC). This is the L2 byte-for-byte parity proof.
-- **JSON-RPC L4 protocol** — ADR-002 + commit `b0a12a6`. Content-Length framing, five methods (`initialize`, `initialized`, `analyze_file`, `shutdown`, `exit`), 8 MiB cap on both sides. Speakers: `clarion-core::plugin::transport`, `clarion-plugin-fixture` main, `clarion-plugin-python::server`.
-- **Ontology version semver** — ADR-027. Plugin manifest's `[ontology].ontology_version` follows MAJOR/MINOR/PATCH; B.5* was a MINOR bump (additive `references` edge kind) to `0.5.0`.
-- **Edge confidence tiers** — ADR-028. `resolved` / `ambiguous` / `inferred`. MCP queries default to `>= resolved`; inferred edges are computed lazily at query time via LLM dispatch.
-- **Summary cache key** — ADR-007. 5-tuple: (entity_id, content_hash, prompt_template_id, model_tier, guidance_fingerprint). `ontology_version` is explicitly NOT a cache-key component (it's handshake-validation only).
-- **Loom federation doctrine** — `docs/suite/loom.md` §3–§5. Solo-useful + pairwise-composable + enrich-only. Two named v0.1 asterisks survive: Wardline→Filigree pipeline coupling via Clarion; Python plugin's `wardline.core.registry.REGISTRY` import.
-- **Tooling baseline (ADR-023)** — `cargo fmt`, `cargo clippy -D warnings`, `cargo nextest`, `RUSTDOCFLAGS="-D warnings" cargo doc`, `cargo deny check`; ruff + ruff-format + mypy --strict + pytest. CI at `.github/workflows/ci.yml` has three jobs: `rust`, `python-plugin`, `walking-skeleton` (the last depends on the first two).
-- **Schema-validation policy (ADR-031, NEW 2026-05-18)** — `CHECK` constraints required on closed core-owned TEXT-enum columns, forbidden on plugin-extensible ones. Writer-actor remains the canonical validator; CHECK is defense-in-depth.
-
----
-
-## 6. Documentation surface
-
-(Confidence: High — `find docs -name '*.md'` returned 79 files; full file paths inventoried but not deep-read.)
-
-### 6.1 Suite-level doctrine (`docs/suite/`, 4 files)
-
-- `loom.md` — federation axiom, §3–§5 are load-bearing
-- `briefing.md` — 5-minute intro
-- `glossary.md` — cross-product term registry (gate for ADR acceptance)
-- `README.md`
-
-### 6.2 Clarion product docs (`docs/clarion/`)
-
-- `v0.1/requirements.md` — REQ-/NFR-/CON-/NG- baselined IDs
-- `v0.1/system-design.md` — §2–§11 each with `Addresses:` headers naming requirement IDs
-- `v0.1/detailed-design.md` — schemas, rule catalogues, appendices (modified on this branch, +15 lines)
-- `v0.1/plans/v0.1-scope-commitments.md` — pre-implementation scope memo
-- `v0.1/reviews/` — `panel-2026-04-17/` (4 files) + `pre-restructure/` (2 files). Supporting context, not normative.
-
-### 6.3 ADRs (`docs/clarion/adr/`, 25 Accepted + 1 README)
-
-Authored ADRs span 001–031 with gaps (008–010, 019–020 are tracked as backlog inside system-design §12 / detailed-design §11). All Accepted. ADR-031 was added on this branch (2026-05-18).
-
-### 6.4 Implementation plans (`docs/implementation/`)
-
-- `v0.1-plan.md` — 11 work packages in dependency order
-- `sprint-1/` — `README.md`, `signoffs.md`, `wp1-scaffold.md`, `wp2-plugin-host.md`, `wp3-python-plugin.md` (closed at `v0.1-sprint-1`)
-- `sprint-2/` — 12 files covering B.2, B.3, B.4*, B.5*, B.6, B.7, B.8 design + results + signoffs + OpenRouter swap memo + scope amendment memo. Sprint 2 closed at `v0.1-sprint-2` (initially RED on B.8, now GREEN after repair rerun captured in `b8-results.md`).
-
-### 6.5 Operator docs (`docs/operator/`, 2 files)
-
-- `README.md` + `openrouter.md` (provider-swap operator guide)
-
-### 6.6 Handoffs (`docs/superpowers/`, 11 files)
-
-8 dated handoff memos + 3 sprint plans. The most recent (`2026-05-16-sprint-2-resume.md`, `2026-05-03-skeleton-audit.md`) are the live carryover into the current branch.
-
-### 6.7 Top-level
-
-`docs/README.md` + `docs/clarion/README.md` + `docs/clarion/v0.1/README.md` + `docs/implementation/README.md` form the navigation tree.
-
----
-
-## 7. What's changed since Sprint 1
-
-(Confidence: High — `git log --oneline v0.1-sprint-1..HEAD` + `git diff --stat main..HEAD`.)
-
-### 7.1 Whole-of-sprint-2 deltas (commits since `v0.1-sprint-1`)
-
-A **new top-level crate (`clarion-mcp`)** plus heavy growth in `clarion-cli` (the `serve` subcommand), `clarion-storage` (graph query helpers, LLM cache tables, unresolved call sites, source ranges), and the Python plugin (calls + references edges). Notable commit chains:
-
-- **B.2 (class + module entities)** — `e53191d` merge
-- **B.3 (contains edges, first edge kind)** — `f9bd31e` merge, ontology `0.3.0`
-- **B.4* (calls edges + confidence tiers)** — `837d965` merge, ontology `0.4.0`
-- **B.5* (references edges via pyright)** — `e988a83` merge, ontology `0.5.0`
-- **B.6 (seven-tool MCP surface)** — `ed64a16` merge, including `b0a12a6` (scaffold), `7c13b73` (`clarion serve`), `8b8ecdc` (graph query helpers), `7f6a51f` (storage-backed tools), `e964118` (MCP/LLM config), `5a9f218` (LLM cache tables), `6fba66b` (WP6 LLM provider surface), `5627686` (on-demand summary tool), `5dc6e23` (unresolved call sites), `dcf6a30` (inferred call-edge dispatch), `16634ae` (Filigree association contract test), `29d3865` (`issues_for`), `5588ed8` (full-surface e2e), `d1ebca4` (LLM budget reserve), `9ffc5c8` (replace unsound YAML parser → `serde_norway`), `fa5b7cb` (wire MCP LLM paths)
-- **OpenRouter provider swap** — `35be4db` merge, `4af69fd` (replace Anthropic with OpenRouter), `a53d2e4` (operator docs), `ab6b1dd` (strict-JSON path for B.8 green rerun)
-- **B.8 scale test** — `5a396a5` (plan + harness), `80a6af9` (heavy-sample steady-state), `ad2ef80` (RED results), `b87bc1d` (GREEN rerun on full elspeth), `ffdfd79` (signoff revised to GREEN)
-- **Sprint hygiene** — `a80c31a` (gitignore `.env`), `dc9bf41` (load `.env` before tracing), `29f0426` (skip `@overload` stubs to prevent UNIQUE collision), `c7ec1dd` (ADR-031 CHECK clauses), `0cb61b4` (manifest rule-ID grammar fix)
-
-### 7.2 Current-branch (`sprint-2/b8-scale-test`) deltas against `main` (11 commits)
-
-`git diff --stat main..HEAD` shows 45 files changed, 23 209 insertions, 59 deletions. Substantive non-result-data changes:
-
-- **`crates/clarion-core/src/llm_provider.rs`** — +193 lines (OpenRouter strict-JSON path)
-- **`crates/clarion-core/src/plugin/manifest.rs`** — +10 lines (ADR-022 rule-ID quantifier fix)
-- **`crates/clarion-mcp/src/lib.rs`** — +171 lines (B.8 follow-up)
-- **`crates/clarion-mcp/tests/storage_tools.rs`** — +184 lines
-- **`crates/clarion-storage/migrations/0001_initial_schema.sql`** — +33 lines (ADR-031 CHECK clauses)
-- **`crates/clarion-storage/tests/schema_apply.rs`** — +148 lines (new test verifying CHECK enforcement)
-- **`docs/clarion/adr/ADR-031-schema-validation-policy.md`** — +426 lines (new ADR)
-- **`plugins/python/src/clarion_plugin_python/extractor.py`** — +98 lines (`@overload`-stub skip)
-- **`plugins/python/tests/test_extractor.py`** — +184 lines
-
-The bulk of the +23 209 line delta is **B.8 scale-test result artifacts** (`tests/perf/b8_scale_test/results/*/mcp-driver-output*.json`) — JSON drivers' captured outputs from the elspeth corpus run, plus the 816-line `driver.py` and 227-line `test_driver.py` harness. These are checked-in evidence, not source code.
-
-### 7.3 Working tree (not yet committed)
-
-`git status` shows 7 modified files + 1 new file (`docs/clarion/adr/ADR-031-schema-validation-policy.md`) + the result snapshot `tests/perf/b8_scale_test/results/2026-05-18T0017Z/`. The B.8 GREEN rerun results are partially committed and partially still in the working tree.
-
----
-
-## 8. Open questions for the deeper per-subsystem pass
-
-1. **`clarion-mcp/src/lib.rs` is 2 617 LOC in one file.** Is this a single coherent concern (tool dispatch) or a god-file that subdivides? The subsystem-catalog pass should examine internal structure — is there a `ServerState` impl, a per-tool handler set, and a transport loop, all in one file? If so, refactor candidates may surface.
-2. **`clarion-core/src/plugin/host.rs` is 3 126 LOC.** Same question — supervisor logic vs handshake vs analyze-file orchestration. Sprint-1 lock-ins anchor this; understand which.
-3. **`clarion-mcp` ↔ `clarion-storage` coupling.** `clarion-mcp::lib.rs` imports ~20 symbols from `clarion-storage` (`CallEdgeMatch`, `EntityRow`, `InferredCallEdgeRecord`, `ReaderPool`, etc.). Is the MCP layer a thin dispatch over storage query helpers, or does it also marshal/transform substantially? This affects the catalog's responsibility statement for `clarion-storage::query`.
-4. **LLM-provider dispatch path.** `serve.rs` wires `OpenRouterProvider` | `RecordingProvider` | disabled. `dcf6a30` and `5627686` added inferred-edge and summary dispatch. The catalog pass should confirm what's actually cached vs lazy-computed and where the 5-tuple cache key is materialised (writer.rs vs lib.rs vs cache.rs).
-5. **Filigree integration shape.** `filigree.rs` is 238 LOC; `issues_for` exists; ADR-029 governs the binding contract. The catalog should verify the "enrich-only" axiom is upheld at the code level — does any code path on the Clarion side *require* a Filigree response to succeed?
-6. **Schema migration governance.** Single migration file (289 LOC), edit-in-place per ADR-024 until an external operator ships a published build. Currently three documented edit events (initial, 2026-05-03 ADR-024 rename, 2026-05-18 ADR-031 CHECKs). When does the retirement trigger fire? Catalog should record current state.
-7. **`tests/perf/elspeth_mini/`** is a 3-file corpus checked in for harness self-tests. Confirm this is fixture data (not Clarion source); none of the discovery reads suggest it's wired into the build.
-8. **Sprint-1 deferred items** (per `CLAUDE.md`) — six WP2 items, four WP1 review-2 P2 bugs, one WP9 amendment — are these still open Filigree issues, or has Sprint 2 closed some? The catalog pass may want to map deferred items to current crate state.
-
----
-
-## Confidence summary
-
-| Section | Confidence | Evidence |
-|---|---|---|
-| §1 Repository organisation | High | `ls` + `Cargo.toml` workspace members + ADR-022 |
-| §2 Technology stack | High | `Cargo.toml`, `pyproject.toml`, `plugin.toml` read in full |
-| §3 Entry points | High | `main.rs`, `cli.rs`, `__main__.py`, `serve.rs` read |
-| §4 Subsystem identification | High for crate boundaries, Medium for "responsibility" claims (lib.rs facades read, internal implementations sampled by size only) | per-crate `src/` listings, `lib.rs` heads read, LOC counts per file |
-| §5 Cross-cutting concerns | High where ADR-cited; Medium where inferred | ADR index, ADR-031, ADR-027, ADR-028, ADR-007 read |
-| §6 Documentation surface | High (inventory only; no depth reads) | `find docs -name '*.md'` |
-| §7 Sprint-2 deltas | High | `git log v0.1-sprint-1..HEAD`, `git diff --stat main..HEAD`, `git status` |
-| §8 Open questions | N/A (questions, not findings) | n/a |
-
----
-
-## Risk Assessment
-
-- **Risk: file-size god-files** — Two source files exceed 2 600 LOC (`clarion-core/src/plugin/host.rs` 3126, `clarion-mcp/src/lib.rs` 2617). Catalog pass needs to confirm whether internal structure makes them coherent or whether they should be flagged for refactoring.
-- **Risk: discovery undercounts plugin-side complexity** — `pyright_session.py` is 1 251 LOC of LSP-client logic; this is single-file in the plugin but represents a substantial dependency on an external process. The catalog pass for subsystem F must give this its own treatment.
-- **Risk: Sprint-2 docs not yet fully inventoried** — 12 sprint-2 .md files exist; only `signoffs.md` was read in any depth this pass. The deeper pass should at least skim each B.* design doc for subsystem-level claims.
-
-## Information Gaps
-
-- LLM-provider dispatch internals (how the 5-tuple cache key is constructed and where the LRU/TTL logic lives).
-- Whether `tests/e2e/sprint_2_mcp_surface.sh` actually executes all seven MCP tools or a subset.
-- The `scripts/` directory contents (not enumerated this pass).
-- Wardline / Filigree sibling-repo source — none of this is vendored; cross-product claims rely on doctrine + manifest pins only.
-
-## Caveats
-
-- LOC numbers include test code unless explicitly stated. The "actual code" subtotals exclude `tests/` subdirectories but include `#[cfg(test)]` modules in `src/` (e.g., `mock.rs` 897 LOC counts in `clarion-core`).
-- This pass cited line ranges from file heads only; deeper file scrutiny is deferred to the per-subsystem catalog pass.
-- No assessment of code *quality* is made here. That is a `axiom-system-architect:assess-architecture` concern, not a discovery concern.
diff --git a/docs/arch-analysis-2026-05-18-1244/02-subsystem-catalog.md b/docs/arch-analysis-2026-05-18-1244/02-subsystem-catalog.md
deleted file mode 100644
index efeea122..00000000
--- a/docs/arch-analysis-2026-05-18-1244/02-subsystem-catalog.md
+++ /dev/null
@@ -1,648 +0,0 @@
-# 02 — Subsystem Catalog
-
-**Repository:** `/home/john/clarion`
-**Branch:** `sprint-2/b8-scale-test`
-**Catalog assembled:** 2026-05-18
-
-This catalog documents the six subsystems identified in `01-discovery-findings.md` §4. Each entry was produced by a dedicated `axiom-system-archaeologist:codebase-explorer` subagent reading the crate's source in depth. Entries cite file:line throughout.
-
-## Subsystem index
-
-| # | Subsystem | Location | Production LOC (approx) | Inbound deps | Outbound (workspace) |
-|---|---|---|---|---|---|
-| A | `clarion-core` | `crates/clarion-core/` | ~3 100 | storage, mcp, cli | (none) |
-| B | `clarion-storage` | `crates/clarion-storage/` | ~1 950 | mcp, cli | core (one symbol) |
-| C | `clarion-mcp` | `crates/clarion-mcp/` | ~3 200 | cli | core, storage |
-| D | `clarion-cli` | `crates/clarion-cli/` | ~1 740 | (binary — none) | core, storage, mcp |
-| E | `clarion-plugin-fixture` | `crates/clarion-plugin-fixture/` | 131 | core (test only) | core (types only) |
-| F | Python plugin | `plugins/python/src/clarion_plugin_python/` | ~2 670 | (subprocess of host) | pyright, packaging, wardline (soft) |
-
-Crate-level graph is acyclic (verified by cross-grep of `use clarion_*::` and `Cargo.toml` deps in each subagent's pass). The Python plugin is *not* a Rust crate; the only "dep" relationship is the host-spawns-subprocess contract.
-
-> **Footnotes on the index:** "Inbound deps" lists library-link consumers only — Cargo `[dev-dependencies]` are excluded. `clarion-cli` declares `clarion-plugin-fixture` under `[dev-dependencies]` for its `wp2_e2e` tests but does not link it in the production binary. LOC ranges throughout this catalog reflect the working tree at `sprint-2/b8-scale-test` HEAD on 2026-05-18; `clarion-mcp/src/lib.rs` is 2 623 lines as of this commit (a few entries below quote the immediate-pre-B.8 figure of 2 620 — drift of +3 lines from late-B.8 follow-up).
-
----
-
-## clarion-core
-
-**Location:** `crates/clarion-core/`
-
-**Responsibility:** Owns the canonical entity-ID grammar, plugin-host subprocess supervisor + JSON-RPC peer, LLM-provider trait + OpenRouter implementation, plugin-manifest parser, and the jail / RSS / entity / breaker ceilings that every other crate depends on for safety.
-
-**Public interface:**
-
-`lib.rs` is 47 lines (see `crates/clarion-core/src/lib.rs:1-47`) and is explicit that it is a curated facade per ticket `clarion-29acbcd042`. Re-exports at the crate root, grouped by submodule:
-
-- **From `entity_id`**: `EntityId`, `EntityIdError`, free function `entity_id(plugin, kind, qualname)` — the cross-language assembler.
-- **From `llm_provider`**: trait `LlmProvider`; `OpenRouterProvider` + `OpenRouterProviderConfig`; `RecordingProvider` + `Recording` (test fixture replay); error type `LlmProviderError`; request/response DTOs `LlmRequest` / `LlmResponse` / `LlmPurpose`; `CachingModel`; prompt builders `build_leaf_summary_prompt`, `build_inferred_calls_prompt`, with stable IDs `LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1"` and `INFERRED_CALLS_PROMPT_VERSION = "inferred-calls-v1"`.
-- **From `plugin`**: `PluginHost`, `Manifest` + `parse_manifest`, `AcceptedEntity` / `AcceptedEdge` / `AnalyzeFileOutcome` / `AnalyzeFileStats`, `EdgeConfidence`, `UnresolvedCallSite`, `HostError` + `HostFinding`, `JailError`, `CapExceeded`, `DiscoveredPlugin` + `DiscoveryError` + `discover()`, `CrashLoopBreaker` + `CrashLoopState`, and the finding-ID constants (`FINDING_DISABLED_CRASH_LOOP` re-exported at root, with sibling `FINDING_*` constants reachable through `clarion_core::plugin::*`).
-
-Implementation types deliberately *not* re-exported at the root but still reachable via fully-qualified paths: transport (`Frame`, `read_frame`, `write_frame`, `TransportError`), protocol envelopes (`RequestEnvelope`, `ResponseEnvelope`, `AnalyzeFileParams`, etc.), prlimit helpers, raw entity/edge structs. `make_notification` / `make_request` are `pub(crate)` — `mod.rs:38-42` explains they panic on serde failure and external callers should build envelopes directly.
-
-**Internal structure:**
-
-Top-level modules (`crates/clarion-core/src/`):
-
-- `entity_id.rs` (610 LOC) — `EntityId` newtype + `entity_id()` constructor + `EntityIdError`. Includes the cross-language parity test against `fixtures/entity_id.json` (ADR-003, L2 lock-in).
-- `llm_provider.rs` (948 LOC) — single-file LLM abstraction. See breakdown below.
-- `plugin/` — supervisor + protocol + safety primitives. Submodule roles documented inline at `plugin/mod.rs:1-12`:
-  - `manifest.rs` (1508 LOC) — `Manifest`, `PluginMeta`, `Capabilities`, `CapabilitiesRuntime`, `PyrightRuntime`, `Ontology`, `parse_manifest()`, kind-grammar + rule-ID-prefix validators (ADR-021/ADR-022, L5).
-  - `protocol.rs` (846 LOC) — JSON-RPC 2.0 typed envelopes; `AnalyzeFileParams/Result`, `AnalyzeFileStats`, `UnresolvedCallSite`, `EdgeConfidence`, `InitializeParams/Result`, `Shutdown`, `Exit`, `ProtocolError`.
-  - `transport.rs` (568 LOC) — `Frame`, `read_frame`/`write_frame`, Content-Length framing with `MAX_HEADER_LINE_BYTES = 8 KiB`; surfaces oversize via `TransportError`.
-  - `jail.rs` (253 LOC) — `jail()` / `jail_to_string()` canonicalises and asserts containment under project root; `JailError::{EscapedRoot, NonUtf8Path, Io}`.
-  - `limits.rs` (552 LOC) — `ContentLengthCeiling`, `EntityCountCap`, `PathEscapeBreaker`, `BreakerState`, the finding-ID constants for cap violations, and the Unix `apply_prlimit_as` / `apply_prlimit_nofile_nproc` (no-op stubs on non-Unix). `DEFAULT_MAX_RSS_MIB = 2048` (ADR-021 §2b ceiling).
-  - `breaker.rs` (360 LOC) — `CrashLoopBreaker`, `CrashLoopState`, `FINDING_DISABLED_CRASH_LOOP` (ADR-002 §UQ-WP2-10).
-  - `discovery.rs` (637 LOC) — `DiscoveredPlugin`, `DiscoveryError`, `discover()` (Linux only — non-Unix returns empty), `discover_on_path()`, scans `$PATH` for `clarion-plugin-*` executables and pairs them with a sibling `share/clarion/plugins/<name>/plugin.toml` (cap 64 KiB).
-  - `host.rs` (3126 LOC) — see below.
-  - `mock.rs` (897 LOC, `#[cfg(test)] pub(crate)`) — in-process mock plugin; reachable only from unit tests in this crate.
-
-### Internal organisation of `plugin/host.rs` (3126 LOC)
-
-Despite the line count, the file is **not a god-file** — it is structurally one struct (`PluginHost<R, W>`) with two layers of constructors, an analyse-file pipeline, and a long unit-test suite. Concretely:
-
-- **Lines 1–155: Module-level constants and finding-ID strings** (`FINDING_*` for entity/edge ontology violations, plus byte caps `MAX_ENTITY_FIELD_BYTES = 4 KiB`, `MAX_ENTITY_EXTRA_BYTES = 64 KiB`, `MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512`).
-- **Lines 157–345: Pure validators / decoders** (`effective_max_nproc`, `oversize_edge_field`, `oversize_field`, `invalid_unresolved_call_site_reason`).
-- **Lines 346–438: Public DTOs** — `RawEntity`, `RawEdge`, `RawSource`, `AcceptedEntity`, `AcceptedEdge`, `AnalyzeFileOutcome`, `HostError` (with 17 variants covering Spawn, Handshake, Protocol, EntityCapExceeded, PathEscapeBreakerTripped, OomKilled, Io, etc.).
-- **Lines 450–637: `HostFinding` + ~14 named constructors** (`undeclared_kind`, `entity_id_mismatch`, `path_escape`, `disabled_path_escape`, `entity_cap_exceeded_finding`, `unsupported_capability`, `non_utf8_path`, `malformed_entity`, `malformed_edge`, `undeclared_edge_kind`, `edge_field_oversize`, `malformed_unresolved_call_site`, `entity_field_oversize`, `oom_killed`). One constructor per finding type — the "constructor wall" inflates line count but is mechanical.
-- **Lines 639–710: `PluginHost<R, W>` struct definition + `drain_stderr_into_ring`** — generic over reader/writer so subprocess and in-process mock share one impl; `stderr_tail` is a 64 KiB ring buffer.
-- **Lines 712–882: Subprocess constructor `PluginHost::spawn`** specialised to `BufReader<ChildStdout>` / `BufWriter<ChildStdin>`. This is the heaviest single function — it (1) validates manifest `executable` is a bare basename matching the discovered binary path (anti-redirect defence at host:756–780), (2) applies `RLIMIT_AS` + `nofile` + `nproc` via `pre_exec`, (3) spawns a detached stderr-drain thread, (4) reaps the child on handshake failure (host:864–880 — `Child::Drop` does *not* reap, so failure paths must explicitly wait).
-- **Lines 883–957: `PluginHost::connect` + `new_inner` + accessors** (`stderr_tail`, `ontology_version`).
-- **Lines 959–1028: `handshake()`** — the four documented steps: send `initialize`, validate response id, run `manifest.validate_for_v0_1()`, send `initialized`. On manifest failure the host is best-effort-shut-down without sending `initialized`.
-- **Lines 1031–1198: `analyze_file()`** — the per-file orchestration pipeline. Reads as a numbered validator pipeline:
-  - `0.` field-size cap → oversize finding, drop (host:1103);
-  - `1.` ontology declared-kind check (host:1109);
-  - `2.` entity-id identity check (host:1116);
-  - `3.` path-jail check + path-escape breaker tick → kill-path on `Tripped` (host:1135);
-  - `4.` entity-cap check → kill-path on exceed (host:1166).
-- **Lines 1200–1299: `process_edges()`** — same drop-on-violation posture, no kill paths (edges don't participate in breakers).
-- **Lines 1300–1450: `process_stats`, `shutdown`, `take_findings`, `next_id`, `do_shutdown`, `read_response_matching`** (drain-until-match for stale frames at host:1398; idempotent shutdown via `terminated` flag at host:657).
-- **Lines 1452–end (≈1700 LOC of tests)**: 30+ `#[cfg(test)]` named scenarios `t2_…` through `t9_…` plus B.3/B.4*/B.5* regressions. Tests dominate the line count; *production code in `host.rs` is ~1450 LOC*.
-
-The file is **coherent**: one supervisor type with one validator pipeline. The internal pressure to refactor is mild — splitting findings into a sibling module would shave ~200 LOC, but the drop-on-violation pipeline reads top-to-bottom and benefits from staying co-located.
-
-### Internal organisation of `llm_provider.rs` (948 LOC)
-
-Single-file LLM abstraction, organised top-to-bottom (no submodule because there is no `llm_provider/` directory):
-
-- **Lines 10–11: Stable prompt-ID constants** (`LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1"`, `INFERRED_CALLS_PROMPT_VERSION = "inferred-calls-v1"`). These form two of the five components of the ADR-007 cache key; the other three (`entity_id`, `content_hash`, `model_tier`, `guidance_fingerprint`) are assembled in `clarion-storage::cache::SummaryCacheKey`. **The 5-tuple is *not* materialised inside this file** — the provider is dispatch-only; cache keying happens in `clarion-storage` and `clarion-mcp`.
-- **Lines 13–37: Request / response / purpose DTOs** (`LlmRequest`, `LlmResponse`, `LlmPurpose::{Summary, InferredEdges}`).
-- **Lines 38–82: Error taxonomy** — `LlmProviderError` with six variants; `retryable()` returns the inner retryable flag for `Http`/`Provider`/`InvalidResponse`, false for `MissingRecording`/`LiveProviderNotAllowed`/`MissingApiKey`.
-- **Lines 84–90: The `LlmProvider` trait** — five required methods: `name`, `invoke`, `estimate_tokens`, `tier_to_model`, `caching_model`. Trait is `Send + Sync` so providers can be shared across MCP request handlers behind an `Arc`.
-- **Lines 92–151: `RecordingProvider`** — test-mode provider that replays exact-shape `LlmRequest` matches from a fixed `Vec<Recording>`. Tracks invocations in a `Mutex<Vec<LlmRequest>>` for assertion. Returns `MissingRecording` (non-retryable) on shape drift.
-- **Lines 153–295: `OpenRouterProvider`** — the live provider.
-  - Config gate at `from_config` (lines 173–187): requires both `allow_live_provider == true` AND a non-empty `api_key`; either failure yields `LiveProviderNotAllowed` / `MissingApiKey` (both non-retryable).
-  - `invoke()` (lines 202–279): blocking `reqwest` POST to `{endpoint}/chat/completions`, 60s timeout, `Authorization: Bearer`, `HTTP-Referer`, `X-OpenRouter-Title` headers. Payload includes `"temperature": 0`, `"provider": {"require_parameters": true}`, and `response_format` from `response_format_for_purpose()`.
-  - **The strict-JSON path** (the open question from §8) lives at `response_format_for_purpose` (lines 297–370): two JSON-Schema objects, both with `"strict": true` and `"additionalProperties": false`. `Summary` enforces `{purpose, behavior, relationships, risks}`; `InferredEdges` enforces `edges: [{site_key, target_id, confidence, rationale}]`. This is the B.8 GREEN-rerun fix from commit `ab6b1dd` — without `"strict": true` OpenRouter providers silently produced free-form text.
-  - Error unwrap chain: the response body is first parsed as `OpenRouterErrorEnvelope` (line 250) — even on HTTP 200, choices can carry per-call provider errors at `OpenRouterChatResponse::output_text` (line 379), which surfaces `LlmProviderError::Provider`.
-- **Lines 297–500: HTTP plumbing** — response struct definitions (`OpenRouterChatResponse`, `OpenRouterChoice`, `OpenRouterMessage`, `OpenRouterUsage`, `OpenRouterErrorEnvelope`, `OpenRouterErrorBody`), `provider_error_from_body`, `retryable_status` (true for 408 / 429 / ≥500), `retry_after_seconds` (header parse), `estimate_text_tokens` (chars/4 heuristic).
-- **Lines 502–561: Prompt builders** — `LeafSummaryPromptInput` / `InferredCallsPromptInput` DTOs and the two `build_*_prompt` functions emitting `PromptTemplate { id, body }`. Body is a hand-written `format!` template; no Tera/Handlebars.
-- **Lines 563–end: Unit tests**, including a TCP-listener-based in-process OpenRouter stub at `openrouter_provider_invokes_chat_completions_and_extracts_usage_tokens`.
-
-**Nothing is cached inside `llm_provider.rs`.** The provider is a stateless dispatcher; caching is `clarion-storage::cache` (per discovery §4, Subsystem B) and lookup is performed by callers in `clarion-mcp::lib.rs` and the analyze-file inferred-edges path. Caching is *lazy and lookup-driven*: callers compute `SummaryCacheKey` from the 5-tuple, hit the cache, and only call `LlmProvider::invoke` on miss — then write the response back keyed on the same tuple.
-
-**Key types & traits:**
-
-| Type | Where | Why callers touch it |
-|---|---|---|
-| `EntityId`, `entity_id()` | `entity_id.rs` | Every accepted entity is identified by this; cross-language parity proof. |
-| `LlmProvider` (trait) | `llm_provider.rs:84` | MCP and analyze layers receive `Arc<dyn LlmProvider>` for dispatch. |
-| `OpenRouterProvider`, `RecordingProvider` | `llm_provider.rs:164`, `:99` | Provider construction in `clarion-cli::serve.rs`. |
-| `PluginHost<R, W>` | `host.rs:639` | The per-file supervisor; `spawn` for production, `connect` for in-process tests. |
-| `AcceptedEntity`, `AcceptedEdge`, `AnalyzeFileOutcome` | `host.rs:346–398` | Hand-off shapes from host → analyse orchestrator → writer-actor. |
-| `Manifest` + `parse_manifest` | `manifest.rs:115`, `:281` | `clarion-cli::analyze` reads `plugin.toml` through this; `PluginHost` consumes it. |
-| `CrashLoopBreaker` | `breaker.rs:43` | `clarion-cli::analyze` ticks this per plugin-spawn failure. |
-| `discover()` / `DiscoveredPlugin` | `discovery.rs:133`, `:47` | Plugin discovery on `$PATH`. |
-| `HostError` / `HostFinding` | `host.rs:400`, `:450` | Error matching + finding emission for operator diagnostics + Filigree forwarding. |
-| `LlmProviderError` | `llm_provider.rs:44` | Caller uses `.retryable()` to drive WP6 backoff. |
-
-**Dependencies (workspace + outbound):**
-
-- **Inbound** (per `grep clarion-core` against each Cargo.toml):
-  - `clarion-storage/Cargo.toml:13`
-  - `clarion-mcp/Cargo.toml:13`
-  - `clarion-cli/Cargo.toml:20`
-
-  *Note (corrected by validation pass):* `clarion-plugin-fixture` **does** depend on `clarion-core` for the typed protocol structs only (`use clarion_core::plugin::*` in its `main.rs`; declared at `crates/clarion-plugin-fixture/Cargo.toml:18` as `clarion-core = { path = "../clarion-core", version = "0.1.0-dev" }`). It does not link against the supervisor / writer / MCP paths. The fixture is consumed only via subprocess in `wp2_e2e`.
-
-- **Outbound** (`Cargo.toml`):
-  - `reqwest` (workspace: `rustls-tls-native-roots`, blocking + JSON) — only `llm_provider.rs`.
-  - `serde` + `serde_json` + `toml` — DTO + manifest parsing.
-  - `thiserror` — every error enum here.
-  - `tracing` — host stderr-drain failures + best-effort-shutdown diagnostics.
-  - `nix` (workspace, `resource` feature only) — `apply_prlimit_*` in `limits.rs`. The single `unsafe` allowance in the workspace lives here (`pre_exec` + `setrlimit`); workspace lint floor is `unsafe_code = "deny"` (downgraded from `forbid` per documented exception in workspace `Cargo.toml`).
-  - `tempfile` (dev-dep) — tests only.
-
-- **Notably absent**: no `tokio` dependency. The plugin host is fully synchronous (`BufRead + Write` generic bounds, blocking `reqwest`). Async is introduced one layer up in `clarion-storage::writer` (`tokio::task`) and `clarion-mcp::lib.rs`.
-
-**Patterns observed:**
-
-- **Generic reader/writer typestate-lite** — `PluginHost<R, W>` is generic; `spawn` returns a host parameterised on `BufReader<ChildStdout>` / `BufWriter<ChildStdin>`, while `connect` accepts any `BufRead + Write` pair so the in-process `mock.rs` and the e2e tests share one validator pipeline.
-- **Drop-on-violation pipeline with discrete kill-paths** — `analyze_file` is a numbered five-step validator; steps 0–2 only emit findings and drop the offending record; steps 3–4 escalate to plugin termination if a breaker trips. The kill-paths route through a single `do_shutdown` (host:1352) that handles the idempotent-shutdown flag.
-- **Newtype-with-constructor for safety-critical IDs** — `EntityId(String)` is private-field; the only constructors live in `entity_id.rs` and validate the grammar before producing the newtype. `FromStr` rebuilds via the same constructor.
-- **Trait-object provider dispatch** — `Arc<dyn LlmProvider>` consumed by MCP and analyze; live vs recording vs disabled selected at config time (`clarion-cli::serve.rs`).
-- **Finding-ID constants as first-class API** — every `FINDING_*` is a `pub const &str` exported at module root so callers (and tests) can `assert_eq!` on the stable ID rather than match on free-form messages. The ID grammar (`CLA-INFRA-*`) is asserted at manifest-parse time (`manifest.rs:414`).
-- **Pure-function validators** — `oversize_field`, `oversize_edge_field`, `invalid_unresolved_call_site_reason`, `validate_kind_string`, `validate_rule_id_prefix_grammar` are all stateless and unit-tested in isolation.
-
-**Concerns / risks:**
-
-- **`host.rs` size** (3126 LOC including ~1700 LOC of tests). Production code is ~1450 LOC and is coherent, but the file is the codebase's largest. A future refactor could move the 14 `HostFinding` constructors and the `FINDING_*` constants to a sibling `host_findings.rs` for ~200 LOC saved without altering semantics.
-- **`manifest.rs` size** (1508 LOC) — not deep-read in this pass; the public type surface is small (one `Manifest` + five field-structs + one error enum + parser + two grammar validators). Likely test-dominated like `host.rs`, but worth a separate confirm pass.
-- **Subprocess constructor is Linux-coupled** — `spawn` at `host.rs:739` uses `pre_exec` + `RLIMIT_AS`/`RLIMIT_NOFILE`/`RLIMIT_NPROC`. `limits.rs:330–342` provides no-op stubs for non-Unix targets, but `discover()` at `discovery.rs:139` is also `#[cfg(unix)]` and returns empty on Windows. v0.1 is Linux-only by intent (per Sprint-1 sign-off), but the cross-platform doors are stubs, not implementations.
-- **Reqwest blocking inside a `Send + Sync` trait method** — `LlmProvider::invoke` is sync. Callers from async contexts (`clarion-mcp`) must `spawn_blocking`. Not verified in this pass which side actually does the offloading; if callers run `invoke` on the runtime thread, MCP tool handlers can starve. This belongs as a follow-up question for the `clarion-mcp` catalog pass.
-- **OpenRouter strict-JSON regression risk** — the `"strict": true` JSON-Schema gates were added in commit `ab6b1dd` for B.8 GREEN; the path lives entirely in `response_format_for_purpose` (`llm_provider.rs:297`) and is asserted by a test that pattern-matches the serialised request body. A schema change anywhere in the prompt-output contract must update both the prompt template (`build_*_prompt`) and the strict-JSON schema in lockstep — there is no cross-check between them.
-- **`unsafe` allowance lives here** — `pre_exec` + `setrlimit` is the workspace's sole `unsafe` block (documented in workspace `Cargo.toml`). Any new unsafe in `clarion-core` should require an ADR amendment.
-- **No `tokio` use, but exported types flow into async runtimes** — `AcceptedEntity` / `AcceptedEdge` cross the async boundary via `clarion-storage::WriterCmd`. The DTOs are `Clone + Send` (verified through usage patterns) but this is not enforced by trait bounds at the public boundary; a future field that is not `Send` would silently break downstream.
-- **Test-only `mock.rs` (897 LOC) lives inside `src/` under `#[cfg(test)]`** rather than in `tests/`. Pro: integration tests in `tests/wp2_e2e.rs` cannot link against it — keeping mock scaffolding off the public surface is exactly the goal (`mock.rs` is `pub(crate)`). Con: 897 LOC of test scaffolding inflates `clarion-core` source counts; deferred items include `clarion-adeff0916d` (fixture-binary self-build) which may consolidate this.
-
-**Confidence:** High — read `lib.rs` and `plugin/mod.rs` in full; read `host.rs` structural skeleton + `PluginHost` definition + `spawn` constructor + full `analyze_file` body; read `llm_provider.rs` in full through line 561 (the production code; tests sampled); cross-verified inbound deps via `grep clarion-core` against each crate's `Cargo.toml`. Two claims are Medium-confidence and called out above: (a) `manifest.rs` internal proportions not directly verified beyond signature scan; (b) whether MCP wraps `LlmProvider::invoke` in `spawn_blocking` is out-of-scope for this pass and listed as a follow-up.
-## clarion-storage
-
-**Location:** `crates/clarion-storage/`
-
-**Responsibility:** Persists Clarion's entity/edge graph, run provenance, and LLM caches in a single SQLite database under `.clarion/clarion.db`. All mutations funnel through a single writer-actor task (sole `rusqlite::Connection`); all reads come from a `deadpool-sqlite` pool. The crate also owns the schema migration runner, the PRAGMA discipline, the edge-contract validator, and the typed query helpers consumed by `clarion-mcp` and `clarion-cli`.
-
-### Internal structure
-
-**Module roster** (`src/lib.rs:7–15`, all `pub mod`):
-
-| Module | LOC | Role |
-|---|---|---|
-| `writer.rs` | 817 | Writer-actor: spawn, command loop, edge-contract enforcement, per-N batch commits, parent/contains consistency check at `CommitRun` |
-| `query.rs` | 569 | Read-side helpers (graph navigation, FTS-or-LIKE search, unresolved call-site fan-out) |
-| `cache.rs` | 251 | `SummaryCacheKey` (5-tuple per ADR-007) + `InferredEdgeCacheKey` (4-tuple) and their upsert/lookup/touch helpers |
-| `commands.rs` | 183 | `WriterCmd` enum (9 variants) + POD records + `RunStatus` |
-| `schema.rs` | 118 | Embed-and-apply migration runner (`include_str!` of the single `.sql` file) |
-| `reader.rs` | 88 | `ReaderPool` wrapper around `deadpool-sqlite::Pool` |
-| `unresolved.rs` | 50 | Replace-by-caller bookkeeping for unresolved call sites |
-| `error.rs` | 48 | `StorageError` taxonomy (11 variants, `thiserror`) |
-| `pragma.rs` | 45 | WAL/synchronous=NORMAL/busy_timeout=5000/foreign_keys=ON discipline |
-| `lib.rs` | 35 | Curated `pub use` facade |
-
-**Schema (ER summary)** — single migration `migrations/0001_initial_schema.sql` (289 LOC). Eight base tables, one FTS5 virtual table, three triggers, one view, two generated columns:
-
-```
-                    ┌─────────────────────────────────────────────┐
-                    │  entities  (PK id TEXT)                     │
-                    │  + virtual cols scope_level / scope_rank    │
-                    │  + indexes on kind, plugin_id, parent_id,   │
-                    │    source_file_id, source_file_path,        │
-                    │    content_hash, last_seen_commit,          │
-                    │    scope_rank (partial), git_churn (partial)│
-                    └──┬──────────────────┬────────┬─────────────┘
-                       │self-ref          │FK FK   │FK
-            parent_id  │  source_file_id  │        │
-                       ▼                  ▼        ▼
-   ┌──────────────┐  ┌──────────────────────────────────────┐
-   │ entity_tags  │  │ edges  WITHOUT ROWID                 │
-   │ (entity_id,  │  │ PK (kind, from_id, to_id)            │
-   │  tag) PK     │  │ CHECK confidence IN                  │
-   │ ON DELETE    │  │   (resolved, ambiguous, inferred)    │
-   │ CASCADE      │  │ FKs: from_id, to_id, source_file_id  │
-   └──────────────┘  │   ALL ON DELETE CASCADE              │
-                    └──────────────────────────────────────┘
-                       ▲                  ▲
-                       │entity_id FK      │caller_entity_id FK
-   ┌─────────────────────┐  ┌────────────────────────────────┐
-   │ findings (PK id)    │  │ entity_unresolved_call_sites   │
-   │ CHECK kind ∈ 5      │  │ PK (caller_entity_id,          │
-   │ CHECK severity ∈ 5  │  │     caller_content_hash,       │
-   │ CHECK status ∈ 4    │  │     site_key)                  │
-   │ FK entity_id        │  └────────────────────────────────┘
-   └─────────────────────┘
-                       ▲caller_entity_id FK
-   ┌────────────────────────────┐    ┌──────────────────────────┐
-   │ inferred_edge_cache         │    │ summary_cache            │
-   │ PK (caller_entity_id,       │    │ PK 5-tuple (entity_id,   │
-   │     caller_content_hash,    │    │     content_hash,        │
-   │     model_id,               │    │     prompt_template_id,  │
-   │     prompt_version)         │    │     model_tier,          │
-   │ FK caller_entity_id         │    │     guidance_fingerprint)│
-   └────────────────────────────┘    │ CHECK stale_semantic∈(0,1)│
-                                     └──────────────────────────┘
-
-   ┌──────────────────────────┐   ┌────────────────────────────┐
-   │ runs (PK id)             │   │ schema_migrations          │
-   │ CHECK status ∈ (running, │   │ (version PK, name,         │
-   │   skipped_no_plugins,    │   │  applied_at)               │
-   │   completed, failed)     │   └────────────────────────────┘
-   └──────────────────────────┘
-
-   FTS5 virtual: entity_fts (entity_id UNINDEXED, name, short_name,
-     summary_text, content_text); kept in sync by triggers
-     entities_ai / entities_au / entities_ad.
-
-   View: guidance_sheets — projects entities WHERE kind='guidance'
-     with json_extract of `properties` + json_group_array of tags.
-```
-
-ADR-031 `CHECK` discipline (lines 89, 107–112, 124–125, 153, 200–201): closed core-owned vocabularies receive `CHECK` clauses (`edges.confidence`, `findings.{kind, severity, status}`, `summary_cache.stale_semantic`, `runs.status`). Plugin-extensible vocabularies deliberately omit `CHECK` per ADR-022 — `entities.kind` (`migrations/0001_initial_schema.sql:33–36`) and `edges.kind` (`migrations/0001_initial_schema.sql:77–81`); enforcement at those columns is the writer-actor (`writer.rs::enforce_edge_contract` for edges, manifest acceptance for entity kinds).
-
-**Writer-actor command set** (`commands.rs::WriterCmd`, 9 variants):
-
-| Variant | Lifecycle | Notes |
-|---|---|---|
-| `BeginRun` | analyze-time | `runs` INSERT with `status='running'`, opens `BEGIN` (`writer.rs:308–330`) |
-| `InsertEntity` | analyze-time | Single INSERT into `entities`; counts toward batch boundary (`writer.rs:332–390`) |
-| `InsertEdge` | analyze-time | Calls `enforce_edge_contract` (`writer.rs:411–472`) then `INSERT OR IGNORE`; dedupe increments `dropped_edges_total`, ambiguous accepts bump `ambiguous_edges_total` (`writer.rs:474–520`) |
-| `InsertInferredEdges` | query-time (MCP) | Upserts inferred-edge cache row, GCs stale inferred edges for the caller, inserts new ones; refuses to shadow static resolved/ambiguous calls (`writer.rs:522–599`) |
-| `UpsertSummaryCache` | query-time (MCP) | 5-tuple upsert on `summary_cache` (`cache.rs:48–85`) |
-| `TouchSummaryCache` | query-time (MCP) | `UPDATE summary_cache SET last_accessed_at` (`cache.rs:112–132`) |
-| `ReplaceUnresolvedCallSitesForCaller` | analyze-time | Delete-then-insert pattern; replaces all sites for one caller atomically inside the run transaction (`writer.rs:601–621`, `unresolved.rs:20–50`) |
-| `CommitRun` | analyze-time | Runs the B.3 parent/contains dual-encoding check **inside** the open transaction (`writer.rs:733–796`); on mismatch rolls back the run's writes and marks `runs.status='failed'` with `CLA-INFRA-PARENT-CONTAINS-MISMATCH` in `stats.failure_reason`; on success folds the `runs` UPDATE into the final COMMIT (`writer.rs:671–727`) |
-| `FailRun` | analyze-time | ROLLBACK + `UPDATE runs SET status='failed'` (`writer.rs:798–817`) |
-
-The actor multiplexes analyze-time and query-time mutations on the same connection. `query_time_write` (`writer.rs:647–669`) commits any open analyze-time batch, runs the MCP write, and reopens a `BEGIN` if a run is still active — so analyze-time and MCP traffic cannot deadlock or interleave on the same transaction. Batch cadence is `DEFAULT_BATCH_SIZE = 50` writes (`writer.rs:35`, `bump_writes_and_maybe_commit` at `writer.rs:628–645`); the `INSERT OR IGNORE` edge dedupe is workload-shape-invariant because UNIQUE conflicts still bump the batch counter.
-
-Channel-closed cleanup (`writer.rs:251–273`): if the `Writer` is dropped mid-run, the actor self-heals by issuing `ROLLBACK` and marking the surviving run row `failed` with `failure_reason="writer channel closed unexpectedly"`. This is the durability backstop for the supervisor in `clarion-cli::analyze`.
-
-**Edge contract** (`writer.rs::enforce_edge_contract`, line 411). Ontology is hard-coded as `STRUCTURAL_EDGE_KINDS = ["contains", "in_subsystem", "guides", "emits_finding"]` (`writer.rs:394`) and `ANCHORED_EDGE_KINDS = ["calls", "references", "imports", "decorates", "inherits_from"]` (`writer.rs:395–401`) — nine kinds total per ADR-026/028. Structural edges MUST have `confidence=resolved` and NULL `source_byte_*`; anchored edges MUST have both `source_byte_*` set, and may NOT be `inferred` at scan time (`writer.rs:440–449`) because inferred-tier edges are query-time-only. Violations return `StorageError::WriterProtocol` with one of three CLA codes (`CLA-INFRA-EDGE-CONFIDENCE-CONTRACT`, `CLA-INFRA-EDGE-SOURCE-RANGE-CONTRACT`, `CLA-INFRA-EDGE-UNKNOWN-KIND`) so the surrounding `runs.stats.failure_reason` carries the code (`writer.rs:402–410`).
-
-**Reader pool** (`reader.rs`). `ReaderPool::open` builds a `deadpool_sqlite::Pool` with `Runtime::Tokio1` and a caller-supplied `max_size` (the CLI passes its own value; tests use small caps). `with_reader` acquires from the pool, submits a `'static` closure to deadpool's `interact()` blocking task pool, and applies read-side PRAGMAs (`busy_timeout=5000`, `foreign_keys=ON`) on every acquisition. Retry-on-`SQLITE_BUSY` is delegated to SQLite itself via `busy_timeout` rather than an application-level loop — both writer and readers wait up to 5 s for the lock. WAL mode (set on the writer's first connection, `pragma.rs:16–31`) is what lets readers proceed concurrently without seeing in-flight writes. `waiting_count()` (`reader.rs:85–87`) is exposed `#[doc(hidden)]` for deterministic test polling.
-
-**Cache keys.** `SummaryCacheKey` (`cache.rs:7–14`) materialises ADR-007's 5-tuple exactly: `(entity_id, content_hash, prompt_template_id, model_tier, guidance_fingerprint)`. `ontology_version` is *not* in the key (correct per ADR-007 — that field is handshake validation only). `InferredEdgeCacheKey` (`cache.rs:30–36`) is a 4-tuple `(caller_entity_id, caller_content_hash, model_id, prompt_version)`. **Boundary clarification**: cache lookup/upsert helpers in `cache.rs` are pure storage operations; on a miss, `clarion-mcp::lib.rs` decides whether to call the LLM (via `clarion-core::LlmProvider`), then enqueues the result via `WriterCmd::UpsertSummaryCache` or `WriterCmd::InsertInferredEdges`. This crate does not depend on `clarion-core::LlmProvider`; its only `clarion-core` dependency is `EdgeConfidence` (`commands.rs:14`, `query.rs:6`).
-
-**Query helpers re-exported via `lib.rs`** (`lib.rs:27–32`): `entity_by_id`, `entity_at_line` (innermost-entity-at-line with tie-break by source-range size then kind preference function→class→module), `find_entities` (FTS5 if the pattern is alnum/underscore; LIKE-with-escape otherwise — see `is_fts_safe` at `query.rs:552`), `call_edges_from` / `call_edges_targeting` (apply ADR-028 confidence ceiling; for `ambiguous` edges, expand the `properties.candidates[]` JSON array into multiple match rows — `query.rs:218–235`, `523–534`), `contained_entity_ids` (iterative DFS over `contains` edges with cycle guard and `max_entities` truncation — `query.rs:354–388`), `unresolved_call_sites_for_caller`, `unresolved_callers_for_target` (LIKE-suffix match on `callee_expr` with same-file preference — `query.rs:294–332`), `candidate_entities_for_unresolved_sites`, `child_entity_ids`, `normalize_source_path` (project-root jail; both lexical normalisation and `canonicalize()` are checked — `query.rs:76–104`).
-
-### External interface
-
-`lib.rs` (35 LOC) re-exports a closed surface: the `WriterCmd`/`EdgeRecord`/`EntityRecord`/`RunStatus` typed boundary; `Writer` and the two channel/batch constants; `ReaderPool`; the query helpers; the cache key types and their three pure helpers (`summary_cache_lookup`, `inferred_edge_cache_lookup`, `inferred_edge_cache_key_id`); `StorageError`/`Result`. Internal modules `pragma` and `schema` are `pub mod`, used by `clarion-cli::install` (`crates/clarion-cli/src/install.rs:20`). `clarion-mcp::lib.rs:22–30` consumes 18 named symbols; `clarion-cli::analyze.rs:24–27` consumes 4 (writer/command shapes only).
-
-### Dependencies
-
-- **Inbound** (verified via `use clarion_storage::` grep):
-  - `clarion-mcp` — full read surface + the four query-time `WriterCmd` variants
-  - `clarion-cli` — `analyze.rs` (writer + commands), `install.rs` (`pragma` + `schema`), `serve.rs` (`Writer` + `ReaderPool` + batch constants)
-- **Outbound** (`Cargo.toml`):
-  - `clarion-core` — only for `EdgeConfidence` (used in `commands.rs` + `query.rs`); intentionally minimal
-  - `deadpool-sqlite 0.8` — async-friendly read pool (ADR-011)
-  - `rusqlite 0.31` — bundled SQLite, sole write driver
-  - `tokio` — `mpsc` + `oneshot` channels, `spawn_blocking` for the writer task
-  - `serde_json` — JSON shape validation on `InferredCallEdgeRecord.properties_json` + `ambiguous` `candidates[]` decoding
-  - `thiserror`, `tracing`
-
-No outbound dependency on `clarion-mcp`, `clarion-cli`, or any plugin crate. Crate-level acyclicity holds.
-
-### Patterns observed
-
-- **Actor + pool split (ADR-011).** Single writer task owns the write connection; all multi-row mutations are batched into a transaction sized by writes (entity inserts + edge insert attempts, including dedupes). The pattern is documented as L3 lock-in (`writer.rs:1–13`).
-- **Typed command boundary.** Every mutation is a `WriterCmd` variant carrying its own `oneshot::Sender<Result<T>>` ack — per-command response, no batched fan-in. Adding a new mutation is a single-file append (`commands.rs`) plus a match arm (`writer.rs:152–249`).
-- **Defence in depth on closed vocabularies (ADR-031).** Two enforcement layers: the writer-actor (canonical) and SQL `CHECK` (backstop). The migration's per-column comments name which ADR closes each vocabulary; plugin-extensible columns are explicitly tagged "no CHECK by policy."
-- **Edge-contract failure codes are findings.** When `enforce_edge_contract` rejects, the error message embeds `CLA-INFRA-EDGE-*` codes that surface in `runs.stats.failure_reason` — making writer-rejected edges observable as machine-greppable findings rather than opaque protocol errors.
-- **`query_time_write` interleaves cleanly.** Query-time MCP writes commit the analyze-batch first, then reopen `BEGIN` if a run is still in progress — the actor never holds an MCP cache row open inside an analyze transaction.
-- **Validation depth on path inputs.** `normalize_source_path` does lexical normalisation *and* `canonicalize()`, and checks containment against the canonicalized project root in both forms (`query.rs:76–104`). Prevents symlink/`..` escape against `entity_at_line` and `find_entity`.
-- **B.3 dual-encoding check at commit.** Parent/contains consistency is verified inside the transaction at `CommitRun` time (`writer.rs:733–796`), so an inconsistent run rolls back rather than persisting a half-corrupt graph.
-
-### Concerns
-
-- **Single migration, edit-in-place under ADR-024.** `migrations/0001_initial_schema.sql` has been edited three times (initial; 2026-05-03 ADR-024 vocabulary rename; 2026-05-18 ADR-031 `CHECK` clauses). The retirement trigger is documented in-file (`0001_initial_schema.sql:10–16`) but no automated check fires when the trigger condition (external operator builds `.clarion/clarion.db` from a published Clarion build) is met. Manual discipline only. Mitigated by the migration's own `schema_migrations` row idempotence (`schema.rs:81–89`).
-- **Edge ontology is duplicated.** `STRUCTURAL_EDGE_KINDS` + `ANCHORED_EDGE_KINDS` are hard-coded in `writer.rs:394–401`; ADR-026/028 are the design source; the Python plugin's manifest declares `edge_kinds = ["contains", "calls", "references"]` independently. A new kind requires edits in at least three places (manifest, writer, ADR). No compile-time enforcement that these stay in sync.
-- **Schema-shape FK in `entities.source_file_id` is self-referential** (`migrations/0001_initial_schema.sql:40`). Works because source-file entities are inserted before their contained functions/classes (plugin traversal order), but there is no constraint that enforces insertion order. A plugin emitting children before parents would fail with an FK violation, surfacing as an opaque `rusqlite::Error` rather than a writer-protocol error.
-- **`busy_timeout=5000` is the only `SQLITE_BUSY` mitigation.** Under heavy contention a reader can fail with a SQLite-level busy error rather than being retried at the application layer. The B.8 scale test exercises this path in practice; no per-attempt retry loop exists in `with_reader`.
-- **`InsertEdge` and `InsertEntity` share a single batch counter.** An edge-heavy file (e.g., a module with many `references` edges) can flush the batch boundary mid-file. Documented behaviour (`writer.rs:285–289`) but worth flagging — long transactions are not bounded by file boundary.
-- **No write-side throttling on `WriterCmd` channel.** `DEFAULT_CHANNEL_CAPACITY = 256` (`writer.rs:38`); a faster producer than the actor will block via `Sender::send().await` backpressure, which is correct, but no metric is exposed for "time spent blocked on writer queue."
-
-### Confidence
-
-**Confidence:** High — Read 100% of every `src/*.rs` module (10 files, 1 950 LOC) and the migration in full (289 LOC). Cross-validated dependency direction by grepping `use clarion_storage::` across the workspace: only `clarion-mcp` and `clarion-cli` consume it; no inbound cycles. Confirmed `WriterCmd` variant count (9) matches the actor's match arms one-to-one. Schema CHECK constraints verified at exact line numbers against ADR-031's "closed vs. extensible" decision. Edge-contract code-paths (`enforce_edge_contract` and the three CLA codes it emits) read end-to-end. ADR cross-references are inline in both the migration and the writer source, so the "ADR says X / code does Y" gap is small.
-## clarion-mcp
-
-**Location:** `crates/clarion-mcp/`
-
-**Responsibility:** Speaks MCP protocol revision `2025-11-25` over stdio; serves seven storage-backed read tools (`entity_at`, `find_entity`, `callers_of`, `execution_paths_from`, `summary`, `issues_for`, `neighborhood`) to consult-mode LLM agents, with on-demand LLM dispatch for leaf-scope summaries and inferred call edges, and optional Filigree enrichment for issue attachment.
-
-**Key Components:**
-
-- `src/lib.rs` (2620 LOC) — single-file crate root. Internal organisation, top-to-bottom:
-  - **Protocol surface** (lines 36–166): `MCP_PROTOCOL_VERSION = "2025-11-25"` constant (line 36), `ToolDefinition` struct (40–45), `list_tools()` returning seven hardcoded `ToolDefinition`s with inline JSON-Schema (48–120), schema helpers `confidence_schema` / `id_schema` / `id_confidence_schema` (122–151), stateless `handle_json_rpc` router (154–166) wired to `initialize` / `tools/list` / `tools/call`.
-  - **`ServerState`** (168–1252): the central handler. Fields (168–178): `project_root: PathBuf`, `readers: ReaderPool`, `execution_edge_cap: usize` (default 500), `summary_llm: Option<SummaryLlmState>`, `clock: Arc<dyn Fn() -> String + Send + Sync>`, `budget: Arc<Mutex<BudgetLedger>>`, `inferred_inflight: Arc<AsyncMutex<HashMap<InferredEdgeCacheKey, broadcast::Sender<InferredDispatchOutcome>>>>` (in-flight dispatch coalescing), `filigree_client: Option<Arc<dyn FiligreeLookup>>`. Builder methods (180–226): `new`, `with_edge_cap`, `with_summary_llm`, `with_clock`, `with_filigree_client`.
-  - **Per-tool dispatch** (228–294): instance `handle_json_rpc` + `handle_tool_call` route by name to seven `tool_*` async methods.
-  - **Per-tool handlers** (296–717): `tool_entity_at` (296–319), `tool_find_entity` (321–354), `tool_callers_of` (356–391), `tool_execution_paths_from` (393–434) + `inferred_execution_paths` (436–520), `tool_neighborhood` (522–581), `tool_issues_for` (583–671), `tool_summary` (673–717).
-  - **LLM inferred-edges pipeline** (719–995): `ensure_inferred_for_target` / `ensure_inferred_for_caller` (719–796) — entry points called by `callers_of`/`neighborhood`/`execution_paths_from` when `confidence == Inferred`; `read_inferred_inputs` (798–833) builds an `InferredEdgeCacheKey` from caller content-hash + model_id + prompt_version (ADR-007); `materialize_cached_inferred` (835–863) on cache hit; `coalesced_inferred_dispatch` (865–908) deduplicates concurrent dispatches via a `broadcast` channel with a 60-second timeout; `perform_inferred_dispatch` (910–995) builds the prompt via `clarion_core::build_inferred_calls_prompt`, reserves budget, invokes the provider on a `spawn_blocking` task, then sends `WriterCmd::InsertInferredEdges` to the writer-actor.
-  - **LLM summary pipeline** (997–1155): `read_summary_inputs` (997–1035) keys against `SummaryCacheKey { entity_id, content_hash, prompt_template_id = LEAF_SUMMARY_PROMPT_TEMPLATE_ID, model_tier, guidance_fingerprint = "guidance-empty" }` — five-tuple cache key matching ADR-007; `cached_summary_envelope` (1037–1060) bumps `last_accessed_at` via `WriterCmd::TouchSummaryCache`; `refresh_summary` (1062–1155) on miss invokes provider, then `WriterCmd::UpsertSummaryCache`. ADR-030 leaf-scope is encoded by the single `LEAF_SUMMARY_PROMPT_TEMPLATE_ID` template and the `summary` tool description (line 98).
-  - **Writer-actor helper + budget** (1157–1251): `send_writer` (1157–1171) — oneshot ack roundtrip pattern; `BudgetLedger` accounting with `reserve_budget` / `BudgetReservation::commit` / `Drop` rollback (1180–1316); `summary_model_id` / `inferred_edges_model_id` / `max_inferred_edges_per_caller` (1221–1251) honour `LlmProvider::tier_to_model("summary"|"inferred_edges")`.
-  - **Plain types** (1266–1607): `SummaryLlmState`, `BudgetLedger`, `SummaryRead` enum, `SummaryReady`, `IssuesForRead`, `IssuesForAccumulator` (drift-classifier matching `content_hash_at_attach` against current `entities.content_hash`, lines 1379–1411, with 100-issue cap), `InferenceLlmState`, `InferredRead`, `InferredDispatchStats` (aggregated stats_delta), `InferredDispatchFailure`, `InferredDispatchOutcome`, `InferredCallsResponse` / `InferredCallsResponseEdge`.
-  - **Transport loop** (1609–1686): `McpError` enum, `handle_frame` / `handle_frame_with_state`, `serve_stdio` / `serve_stdio_with_state` / `serve_stdio_with_state_on_runtime` — Content-Length frame loop using `clarion_core::plugin::{read_frame, write_frame, ContentLengthCeiling::DEFAULT, Frame, TransportError}`; treats `UnexpectedEof` as clean shutdown.
-  - **Stateless `handle_tool_call`** (1701–1736): a stub kept for the stateless `handle_json_rpc` router; emits `tool-unimplemented` envelopes for every tool — only reachable from the stateless entry point used by tests and `handle_frame`.
-  - **Envelope/parsing helpers** (1738–2419): `ParamError`, `PathTraversal` (recursive walker for `execution_paths_from`, 1755–1802), `ReferenceDirection`, `required_str` / `required_i64` / `optional_usize` / `optional_bool` / `optional_confidence` argument coercers, envelope builders (`success_envelope`, `tool_error_envelope`, `tool_error_envelope_with_diagnostics`, `success_envelope_with_truncation_and_stats`), `entity_json`, `source_excerpt` + `line_range_excerpt` + `truncate_excerpt`, `inferred_records_from_result` (parses LLM JSON into `InferredCallEdgeRecord`, 2216–2266), `summary_cache_expired` + `timestamp_day_index` + `days_from_civil` (Howard Hinnant civil-from-days algorithm for the 180-day TTL), `caller_json` / `callee_json` / `path_json` / `reference_neighbors`.
-  - **Unit tests** (2421–2620): 8 tests covering tool-list exact docstrings, initialize result, tools/list wrapping, unknown method/tool/params, frame dispatch round-trip, and multi-frame serve-stdio.
-- `src/config.rs` (352 LOC) — `McpConfig` (YAML via `serde_norway`) with `llm` and `integrations.filigree` sections; `LlmConfig` (provider, `enabled`, `allow_live_provider`, `session_token_ceiling: u64` default 1_000_000, `model_id` default `"anthropic/claude-sonnet-4.6"`, `cache_max_age_days` default 180, `max_inferred_edges_per_caller` default 8); `LlmProviderKind::{OpenRouter, Anthropic, Recording}` (with Anthropic actively rejected — `ConfigError::DeprecatedProvider` with code `CLA-CONFIG-DEPRECATED-PROVIDER`, lines 34–43, 169–171); accepts `llm_policy` alias for the `llm` block (line 10, test at 270–284); `select_provider_with_env` (156–191) returns `ProviderSelection::{Disabled, Recording, OpenRouter{api_key_env}}` — opt-in to live OpenRouter is gated by `allow_live_provider` *or* the `CLARION_LLM_LIVE=1` env (173); presence of an API key alone is not enough (test at 287–303); `FiligreeConfig` (127–147) — `enabled` default false, `base_url` default `http://127.0.0.1:8766`, `actor` default `clarion-mcp`, `token_env` default `FILIGREE_API_TOKEN`, `timeout_seconds` default 5. Five unit tests.
-- `src/filigree.rs` (238 LOC) — `EntityAssociationsResponse` / `EntityAssociation` (Filigree ADR-029 contract); `FiligreeLookup` trait (45–50); `FiligreeHttpClient` (52–111) — blocking `reqwest::blocking::Client` with `timeout_seconds.max(1)`, returns `Ok(None)` when `enabled=false` (68–70); `associations_for` GETs `{base_url}/api/entity-associations?entity_id={encoded}` with `x-filigree-actor` and optional `Bearer` token; manual percent-encoding restricted to unreserved chars (127–142); three unit tests including a real TCP-server roundtrip (194–237).
-- `tests/storage_tools.rs` (1710 LOC) — heavyweight integration tests; 11+ `#[tokio::test]` cases exercising each tool against a seeded SQLite database with `RecordingProvider` LLM substitutes and a stub `FiligreeLookup` (`association` builder at line 573).
-
-**Dependencies:**
-
-- Inbound: `clarion-cli` (only — `crates/clarion-cli/src/serve.rs` is the sole consumer of the public API: `McpConfig::from_path`, `select_provider_with_env`, `FiligreeHttpClient::from_config`, `ServerState::new` + builders, `serve_stdio_with_state_on_runtime`).
-- Outbound:
-  - `clarion-core` — `EdgeConfidence`, `INFERRED_CALLS_PROMPT_VERSION`, `InferredCallsPromptInput`, `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `LeafSummaryPromptInput`, `LlmProvider`, `LlmProviderError`, `LlmPurpose`, `LlmRequest`, `LlmResponse`, `build_inferred_calls_prompt`, `build_leaf_summary_prompt`; transport `plugin::{ContentLengthCeiling, Frame, TransportError, read_frame, write_frame}` (`lib.rs:11–21`).
-  - `clarion-storage` — 20 symbols (`lib.rs:22–30`): types `CallEdgeMatch`, `EntityRow`, `InferredCallEdgeRecord`, `InferredEdgeCacheEntry`, `InferredEdgeCacheKey`, `InferredEdgeWriteStats`, `ReaderPool`, `StorageError`, `SummaryCacheEntry`, `SummaryCacheKey`, `UnresolvedCallSiteRow`, `WriterCmd`; functions `call_edges_from`, `call_edges_targeting`, `candidate_entities_for_unresolved_sites`, `child_entity_ids`, `contained_entity_ids`, `entity_at_line`, `entity_by_id`, `find_entities`, `inferred_edge_cache_key_id`, `inferred_edge_cache_lookup`, `normalize_source_path`, `summary_cache_lookup`, `unresolved_call_sites_for_caller`, `unresolved_callers_for_target`.
-  - External crates: `tokio` (mpsc/oneshot/broadcast, current-thread runtime, `spawn_blocking`), `serde` / `serde_json`, `serde_norway` (YAML), `reqwest::blocking` (Filigree HTTP), `rusqlite` (one direct `prepare` for `reference_neighbors` at line 2378 — the only raw SQL in this crate; everything else routes through `clarion-storage` helpers), `thiserror`.
-
-**Patterns Observed:**
-
-- **Read-side dispatch is genuinely thin.** Six of the seven tools (`entity_at`, `find_entity`, `callers_of` non-inferred, `execution_paths_from` non-inferred, `neighborhood` non-inferred, `issues_for`) call a `clarion-storage` helper through `ReaderPool::with_reader`, then envelope the result. Transformation done in `clarion-mcp` is narrow: building tool envelopes (`ok` / `result` / `error` / `diagnostics` / `truncated` / `truncation_reason` / `stats_delta`), shaping `entity_json` / `caller_json` / `callee_json` / `path_json` projections, and the `IssuesForAccumulator` drift classifier. The one substantive in-crate transform is `inferred_records_from_result` (2216–2266) which parses LLM JSON into `InferredCallEdgeRecord` and joins it back against the unresolved-site rows by `site_key`.
-- **LLM dispatch lives in this crate, not in `clarion-core`.** `clarion-core` provides prompt templates, the `LlmProvider` trait, and request/response types. The MCP layer owns: cache lookup (`summary_cache_lookup`, `inferred_edge_cache_lookup`), cache-staleness checks (`stale_semantic`, `summary_cache_expired`, ADR-007 five-tuple key in `read_summary_inputs:1010–1016`), the budget ledger (`BudgetReservation` with RAII rollback on drop), the in-flight dispatch coalescer (`inferred_inflight` keyed by `InferredEdgeCacheKey`, 60s timeout), prompt construction, provider invocation (`spawn_blocking` to bridge to the sync provider trait), and the writeback via `WriterCmd::{UpsertSummaryCache, TouchSummaryCache, InsertInferredEdges}`.
-- **Filigree integration is genuinely enrich-only.** Three independent skip paths route to `issues_unavailable` (lines 589–594, 619–628), which returns `ok=true` with `available=false` and a `reason` enum (`filigree-disabled` / `filigree-unreachable` / `filigree-client-error` / `entity-not-found`). The other six tools have no Filigree dependency. `FiligreeHttpClient::from_config` returns `Ok(None)` when disabled (filigree.rs:68–70) — disabled is the default. No code path makes a Filigree response required for the tool to succeed; this matches Loom federation §3 (`docs/suite/loom.md`).
-- **Confidence-tier opt-in (ADR-028).** `optional_confidence` (1861–1872) defaults to `Resolved`. `inferred` is the only tier that triggers LLM dispatch (via `ensure_inferred_for_target` / `ensure_inferred_for_caller`). `ambiguous` is read-only over existing static-edge rows.
-- **Writer-actor handoff.** All mutating storage operations go through `mpsc::Sender<WriterCmd>` + a `oneshot::Sender<Result<T, StorageError>>` ack (`send_writer`, 1157–1171). Translates `WriterGone` / `WriterNoResponse` storage errors into retryable tool envelopes. ADR-011 compliance.
-- **Stateful and stateless entry points co-exist.** The stateless `handle_json_rpc` (line 154) + `handle_tool_call` (line 1701) pair always emits `tool-unimplemented` envelopes for every tool; the stateful `ServerState::handle_json_rpc` (line 228) is the real dispatcher. The stateless path remains usable for `initialize` / `tools/list` and is exercised by unit tests inside the file.
-- **Truncation contract** — every list-shaped success envelope can carry `truncation_reason: "edge-cap" | "issue-cap" | "entity-cap"`. `execution_paths_from` enforces `execution_edge_cap` (default 500); `issues_for` enforces a hardcoded 100-issue cap (line 631) and a 1000-contained-entity cap (`read_issues_for_entities:655`).
-- **Time normalisation as plain math.** No `chrono` / `time` dependency — `default_now_string` emits `unix:{seconds}`, `timestamp_day_index` accepts either `unix:N` or ISO `YYYY-MM-DD…` prefix, and `days_from_civil` is the Howard Hinnant algorithm inline (2306–2314).
-
-### Tool table
-
-| Tool | Required inputs | Optional inputs | Primary storage helper | LLM dispatch path |
-|------|------------------|------------------|-------------------------|--------------------|
-| `entity_at` | `file: string`, `line: int ≥ 1` | — | `entity_at_line` (after `normalize_source_path`) | No |
-| `find_entity` | `pattern: string` | `limit: 1..=100` (default 20), `cursor: string\|null` (numeric offset) | `find_entities` | No |
-| `callers_of` | `id: string` | `confidence: resolved\|ambiguous\|inferred` (default `resolved`) | `call_edges_targeting` + `entity_by_id` | Only when `confidence=inferred` → `ensure_inferred_for_target` |
-| `execution_paths_from` | `id: string` | `max_depth: 1..=8` (default 3), `confidence` (default `resolved`) | `call_edges_from` + `PathTraversal` (resolved/ambiguous) or `inferred_execution_paths` (inferred) | Only when `confidence=inferred` → bounded BFS of `ensure_inferred_for_caller` per node |
-| `summary` | `id: string` | — | `summary_cache_lookup` then `WriterCmd::TouchSummaryCache` / `UpsertSummaryCache` | **Yes** — leaf-scope (ADR-030), `LlmPurpose::Summary`, max_output_tokens 512 |
-| `issues_for` | `id: string` | `include_contained: bool` (default true) | `entity_by_id` + `contained_entity_ids` (cap 1000) | No — Filigree HTTP per entity via `spawn_blocking` |
-| `neighborhood` | `id: string` | `confidence` (default `resolved`) | `entity_by_id` + `call_edges_targeting` + `call_edges_from` + `child_entity_ids` + `reference_neighbors` | Only when `confidence=inferred` → both `ensure_inferred_for_target` *and* `ensure_inferred_for_caller` (lines 528–534) |
-
-### LLM cache-key dispatch table
-
-| Path | Cache key tuple (ADR-007) | Source line |
-|------|----------------------------|-------------|
-| Summary | `entity_id` + `content_hash` + `prompt_template_id = LEAF_SUMMARY_PROMPT_TEMPLATE_ID` + `model_tier` (from `LlmProvider::tier_to_model("summary")`) + `guidance_fingerprint = "guidance-empty"` | `lib.rs:1010–1016` |
-| Inferred edges | `caller_entity_id` + `caller_content_hash` + `model_id` (from `tier_to_model("inferred_edges")`) + `prompt_version = INFERRED_CALLS_PROMPT_VERSION` | `lib.rs:816–821` |
-
-On miss, both paths reserve via `BudgetLedger` (token-pessimistic, ceiling default 1_000_000 input+output combined), invoke the provider on `spawn_blocking`, commit actual tokens (or flip `blocked=true`), and on success write back via the writer-actor. Subsequent dispatches for the same key short-circuit through the in-flight coalescer (`coalesced_inferred_dispatch`, 865–908) which `broadcast::subscribe`s and waits up to 60 s.
-
-**Concerns:**
-
-- **`lib.rs` is 2620 LOC in one file.** Discovery question #1 — internal structure is *coherent* (clear bands: protocol surface → `ServerState` → per-tool handlers → LLM pipelines → transport loop → helpers), but the file is large enough to warrant subdivision on size grounds alone. The `IssuesForAccumulator`, the LLM inferred-edges pipeline (719–995), the LLM summary pipeline (997–1155), the budget ledger (1180–1316), and the envelope/projection helpers (1874–2400) are each plausible standalone modules. The current single-file layout is not a god-file in the architectural sense — each band has a single responsibility — but the size will degrade code-review velocity and grep ergonomics.
-- **Dead stateless `handle_tool_call` stub** (`lib.rs:1701–1736`): emits `tool-unimplemented` envelopes for every tool name. Reachable only via the stateless `handle_json_rpc` (154) and `handle_frame` (1621) paths. `handle_frame` is exercised by one unit test (2542–2560) and is exported from the crate, so any external consumer that wires the stateless path will get permanently-broken `tools/call` responses. Not a runtime defect inside the CLI (which uses `handle_frame_with_state`), but a footgun in the public API.
-- **`reference_neighbors` (lib.rs:2363–2400)** issues raw SQL against the `edges` table directly, bypassing the `clarion-storage` helper layer. It is the *only* place in this crate that does so. This creates a hidden coupling to the `edges` schema (`kind = 'references'`, `confidence`, `source_byte_start`, `source_byte_end`) outside the storage crate. If the schema changes, `clarion-storage` callers and tests will catch it but this function will not.
-- **`InferredCallsResponseEdge::confidence: Option<f64>` field is parsed but unused for envelope shape** (lib.rs:1601–1607, used in 2247–2255). The model's reported confidence is stored as a property in the inferred-edge row's `properties_json`, but the storage layer does not surface it back through `caller_json`/`callee_json` — the tool envelope only exposes `edge_confidence` (the tier: resolved/ambiguous/inferred). The model's per-edge confidence is therefore preserved on disk but not queryable; consumers needing the score must hand-parse `properties_json`.
-- **Coalesced-dispatch waiters get a generic stats delta when the leader fails.** `InferredDispatchOutcome::from_result` (1574–1595, used at 902–908) broadcasts a clonable outcome; non-leader waiters that receive a failure outcome surface it as their own (line 884–887). Acceptable, but the leader's diagnostics (e.g. `CLA-LLM-INVALID-JSON` usage block) are visible to the leader only; waiters see the failure code/message but lose the per-response diagnostics array. Minor observability gap.
-- **`source_excerpt` (lib.rs:2151)** uses `std::fs::read_to_string` on the *current on-disk file path* to build LLM prompt input. This is *not* the content hash that keyed the cache; the file may have changed between the time the entity was scanned and the time the tool runs. The cache key still uses the stored `content_hash`, so a stale read here produces a cache miss with a fresh-but-misaligned prompt. The `stale_semantic` flag covers structural drift (caller_count / fan_out) but not source-text drift. Documented as a known v0.1 trade-off in the surrounding code? — no comment found.
-- **`BudgetLedger::blocked` is sticky for the lifetime of the `ServerState`**: once any reservation overshoots, `blocked` flips to `true` (1196, 1296) and every subsequent LLM tool returns `token-ceiling-exceeded` until process restart. No reset path; no way to lift the ceiling without dropping the state. Matches a session-token semantic but is undocumented in the public API.
-- **`FiligreeConfig::actor` blank handling**: `FiligreeHttpClient::associations_for` only sets the `x-filigree-actor` header when the actor string is non-blank (filigree.rs:94–96); Filigree currently requires the header for some endpoints. Silent omission rather than rejection at config-load.
-- **No `Drop` cleanup for in-flight broadcast senders on leader cancellation.** If the leader task panics or is dropped *before* reaching the explicit `remove` at line 904, the `inferred_inflight` entry leaks until the next dispatch for the same key. `broadcast::Sender` itself is not a resource leak, but the map entry blocks subsequent dispatches from claiming leadership; subsequent callers will subscribe to a now-dead sender and time out at 60 s. Low-probability but present.
-
-### Confidence Assessment
-
-**Confidence:** High — Read 100% of `config.rs` (352 lines), 100% of `filigree.rs` (238 lines), 100% of the `lib.rs` declarations/dispatch (1–1700) and the helper/test bands (1700–2620). Sampled five handler bodies in full (`tool_entity_at`, `tool_find_entity`, `tool_callers_of`, `inferred_execution_paths`, `tool_issues_for`, `tool_summary`) and the LLM pipelines (`ensure_inferred_for_caller` through `perform_inferred_dispatch`). Cross-verified inbound dependency by reading `clarion-cli/src/serve.rs` (137 lines). Cross-verified outbound dependency claims against the `use` block at `lib.rs:11–34`. Cross-verified ADR alignment by quoting cache-key construction sites (5-tuple at 1010–1016, 4-tuple at 816–821) and ADR-028 default in `optional_confidence` (1864).
-
-### Risk Assessment
-
-- **Size-induced review burden** (lib.rs 2620 LOC) — Medium operational risk; not a correctness risk. The internal banding makes incremental refactors safe.
-- **Dead stateless `handle_tool_call` stub in public API surface** — Low surface but high blast radius for any external consumer. Single fix: either remove from public exports or make it forward to the same handlers as the stateful path.
-- **`reference_neighbors` raw SQL** — Schema-coupling risk; would not be caught by `clarion-storage` integration tests.
-- **`source_excerpt` reads live disk, not the hashed snapshot** — Correctness drift risk under concurrent file modification; affects prompt fidelity but not cache correctness.
-- **Sticky budget ledger** — Operational risk: process restart required after one ceiling breach. Acceptable for v0.1 / session semantics.
-- **Filigree enrich-only contract** — Verified clean. Discovery question #5 answered: no Filigree code path is load-bearing.
-
-### Information Gaps
-
-- The Sprint-2 e2e script `tests/e2e/sprint_2_mcp_surface.sh` was not read in this pass (out of scope per task framing); coverage of the seven tools end-to-end is documented as "presumed" in `01-discovery-findings.md:138`.
-- The integration tests at `tests/storage_tools.rs` (1710 LOC) were enumerated but not read in full; the `RecordingProvider` plumbing and the `state_for_filigree` stub were sampled to confirm they exist (lines 244–252).
-- ADR text for ADR-007/028/029/030 was not re-opened in this pass; alignment claims rely on the cache-key/confidence-tier code matching the documented intent paraphrased in the task brief.
-- The model's per-edge `confidence: Option<f64>` field is parsed from LLM output but not surfaced in tool responses — whether this is intentional (ADR-028 tiers are coarse-grained on purpose) or a documentation gap was not verified against the ADR.
-
-### Caveats
-
-- The "thin dispatch" characterisation is true for the six read-only tools but does not apply to the LLM-dispatch paths (`tool_summary` plus the `confidence=inferred` branches of `callers_of` / `execution_paths_from` / `neighborhood`), which carry substantive in-crate logic: cache-key construction (ADR-007), budget reservation, in-flight coalescing, prompt construction via `clarion-core` helpers, provider invocation on `spawn_blocking`, JSON-shape validation, and writeback via the writer-actor.
-- The LOC band offsets cited in the catalog were computed from the on-disk `lib.rs` and are stable against the working tree at the time of analysis; minor drift (the file grew by 171 lines during B.8 per `01-discovery-findings.md:323`) means line numbers in this section are post-B.8.
-- "MCP protocol revision `2025-11-25`" is sourced from the in-code constant (`lib.rs:36`); whether that matches the upstream MCP spec revision identifier was not independently verified.
-- The Filigree HTTP client uses `reqwest::blocking` despite living in an otherwise async crate — calls are wrapped in `tokio::task::spawn_blocking` at `lib.rs:613`. Not a defect, but worth flagging if the crate is ever migrated to an async Filigree client.
-## clarion-cli
-
-**Location:** `crates/clarion-cli/`
-
-**Responsibility:** Glue binary for the `clarion` executable; `clap`-driven subcommand dispatch (`install`, `analyze`, `serve`) that wires `clarion-core` (plugin host, LLM provider), `clarion-storage` (writer-actor + reader-pool), and `clarion-mcp` (stdio server) into a single end-user tool, and converts the storage layer's `RunStatus` taxonomy into shell exit codes.
-
-**Key Components:**
-
-- `src/main.rs` (33 lines) — process entry. Loads `.env` via `dotenvy::dotenv()` from CWD or any ancestor *before* `init_tracing()` so a `.env`-supplied `RUST_LOG` is in effect by the time the `EnvFilter` is built (commit `dc9bf41`, `main.rs:16–17`). Parses `cli::Cli`, then dispatches: `Install` and `Serve` run synchronously, `Analyze` builds an ad-hoc multi-thread `tokio::runtime::Builder` and `block_on`s `analyze::run(path)` (`main.rs:21–26`). No top-level runtime — each subcommand owns its own concurrency story.
-
-- `src/cli.rs` (43 lines) — `clap` derive structs only. `Install { --force, --path=. }`, `Analyze { path=. }`, `Serve { --path=., --config=Option<PathBuf> }`. `--force` is declared but documented in code as "not implemented in Sprint 1" (`cli.rs:17–18`).
-
-- `src/install.rs` (168 lines) — `.clarion/` bootstrap. Refuses if the dir already exists (`install.rs:104–110`); refuses if `--force` is passed because Sprint-1 never implemented overwrite (`install.rs:87–92`). On `mkdir` success delegates to `populate_after_mkdir`, which (a) opens `clarion.db`, applies `clarion_storage::pragma::apply_write_pragmas` then `clarion_storage::schema::apply_migrations` (`install.rs:162–167`), (b) writes a stub `config.json` (`schema_version: 1, last_run_id: null`, `install.rs:22–26`), (c) writes a `.gitignore` carrying ADR-005's tracked-vs-excluded rules (`install.rs:54–77`), (d) writes a substantive `clarion.yaml` stub at project-root with LLM and Filigree-integration scaffolding (`install.rs:28–52`). Crucially, `clarion.yaml` is left untouched if it already exists (`install.rs:150–158`). Includes a cleanup guard: any failure inside `populate_after_mkdir` triggers `fs::remove_dir_all(.clarion)` before bubbling the error so the next attempt isn't blocked by the existence check (`install.rs:117–127`; references issue `clarion-ed5017139f`).
-
-- `src/serve.rs` (136 lines) — MCP stdio server wiring, in this exact sequence (`serve.rs:14–91`): (1) assert `.clarion/clarion.db` exists or hint the operator to run `install` first (`serve.rs:15–21`); (2) canonicalise the project root; (3) read `clarion.yaml` via `McpConfig::from_path` or default to `McpConfig::default()` (`serve.rs:26–33`); (4) resolve provider selection via `select_provider_with_env` with a `std::env::var` closure (`serve.rs:34`); (5) build the `Arc<dyn LlmProvider>` via local `build_llm_provider` — `Disabled`/`Recording` (loads JSON fixture from `config.llm.recording_fixture_path` relative to project_root, `serve.rs:122–136`) / `OpenRouter` (passes `api_key`, `allow_live_provider: true`, model id, endpoint, and the attribution Referer/Title); (6) build the optional `FiligreeHttpClient::from_config` (`serve.rs:36–39`); (7) lock `stdin`/`stdout` and wrap stdin in `BufReader`; (8) build a **single-thread current-thread** tokio runtime, `runtime.enter()` as a guard so spawned tasks attach; (9) open the `ReaderPool` (size 16, `serve.rs:50`); (10) construct `ServerState::new(project_root, readers)`; (11) if a provider exists, spawn an LLM-only `Writer` against the same db_path with `DEFAULT_BATCH_SIZE`/`DEFAULT_CHANNEL_CAPACITY` and attach it via `state.with_summary_llm(writer.sender(), config.llm.clone(), provider)` (`serve.rs:55–65`); (12) if the Filigree client built, attach via `state.with_filigree_client(Arc::new(client))` (`serve.rs:66–68`); (13) hand off to `clarion_mcp::serve_stdio_with_state_on_runtime` (`serve.rs:70–72`); (14) drop `state`, drop `llm_writer` to close its sender, `runtime.block_on(handle)` to join the writer (`serve.rs:73–84`); (15) propagate `serve_result?` then the writer's `result?` so a clean MCP loop still fails the process if the writer errored.
-
-- `src/analyze.rs` (1436 lines) — the orchestrator. Internal structure, in source order:
-
-  - **Public entry `pub async fn run(project_path: PathBuf)` (`analyze.rs:40–542`)** — single ~500-line function flagged `#[allow(clippy::too_many_lines)]`. Phases (clearly demarcated by `── … ──` banner comments):
-    1. Path validation + `.clarion/` existence check (`:41–56`).
-    2. **Writer actor lifecycle — open**: `Writer::spawn(db_path, DEFAULT_BATCH_SIZE, DEFAULT_CHANNEL_CAPACITY)` returns a `(writer, handle)` pair; mints a `Uuid::new_v4()` run id and `BeginRun` via `writer.send_wait(...)` (`:60–75`).
-    3. **Plugin discovery** via `clarion_core::discover()`; successes pushed into `plugins`, failures collected into `discovery_errors` (`:78–97`).
-    4. **No-plugins branch** (`:99–171`): distinguishes "zero discovered + zero errors" (`SkippedNoPlugins` via `CommitRun`, exits 0 with a "skipped_no_plugins" stdout line) from "zero usable + non-empty errors" (`FailRun` with the concatenated error list, then `bail!` for non-zero exit). The fix for hiding manifest-parse bugs as `SkippedNoPlugins` is explicit in the comment at `:100–103`.
-    5. **Extension union + source walk** — collect_source_files walks once over the union of every plugin's declared extensions (`:174–184`).
-    6. **Per-plugin loop** (`'plugins:` label, `:211–412`): filter the global file list to this plugin's extensions; if empty, `continue`. Otherwise dispatch a `tokio::task::spawn_blocking(move || run_plugin_blocking(...))` and route its `JoinResult` through `handle_plugin_task_join_result` (which normalises a `JoinError` panic into a crash-reason string rather than `?`-propagating, `:259–271`, regression-tested as `clarion-cf17e4e779`). On `Err(reason)`: push into `crash_reasons`, tick `CrashLoopBreaker::record_crash`, and `break 'plugins` if `CrashLoopState::Tripped` (`:274–292`). On `Ok(BatchResult { entities, edges, unresolved_call_sites, stats, findings })`: fold per-batch stats into per-run accumulators; log every `HostFinding` individually (`:312–327`); flush entities then unresolved call-site replacements (`WriterCmd::ReplaceUnresolvedCallSitesForCaller`) then edges to the writer-actor in that exact order (`:341–391`). Any writer `send_wait` error stops the per-plugin loop and sets `run_outcome = HardFailed { reason }` (`:392–402`).
-    7. **`RunOutcome` resolution** (`:421–522`) — `enum RunOutcome { Completed, SoftFailed { reason }, HardFailed { reason } }` at `:558–563`. Promotion rule: `Completed` + non-empty `crash_reasons` → `SoftFailed` so the entity batch still commits *and* the run row marks failed (`:421–429`). Snapshots `writer.dropped_edges_total` and `writer.ambiguous_edges_total` (atomic counters held on the `Writer` handle) and `pyright_latency.p95_ms()` into the stats JSON (`:435–441`). The three terminal branches dispatch:
-       - `Completed` → `WriterCmd::CommitRun { status: RunStatus::Completed, … }`
-       - `SoftFailed { reason }` → `WriterCmd::CommitRun { status: RunStatus::Failed, … }` plus `"failure_reason": reason` in the stats JSON; the writer folds `UPDATE runs SET status='failed'` into the open entity tx so the partial work commits atomically with the failure marker (`:478–509`, comment at `:551–553`).
-       - `HardFailed { reason }` → `WriterCmd::FailRun` — rolls back the open tx (`:510–521`).
-    8. **Writer-actor lifecycle — close**: `drop(writer)` closes the command channel; `handle.await` joins the actor task (`:524–528`); on any `fail_reason`, `bail!` for non-zero exit — the run row is already correctly marked, this is purely about surfacing failure to the shell (`:530–534`).
-
-  - **`run_plugin_blocking` (`:646–759`)** — synchronous worker that `spawn_blocking` runs. Spawns the plugin via `PluginHost::spawn`; loops `host.analyze_file(file)` for each file in the per-plugin extension-filtered list; accumulates entities, edges, per-file `AnalyzeFileStats`, and per-file unresolved call sites; on the happy path tries `host.shutdown()` and falls back to `child.kill()` if shutdown writes to a closed pipe (`:731–742`); always `reap_and_classify_exit(&mut child, ...)` afterwards because `std::process::Child::Drop` does not `wait()` on Unix and would leak zombies (`:746–747`, comment at `:641–645`).
-
-  - **`reap_and_classify_exit` (`:769–815`)** — on `signal() == SIGKILL (9)` or `SIGSEGV (11)` appends `HostFinding::oom_killed(plugin_id, signal)` per ADR-021 §2d; other signals or non-zero exits get a `warn` log but no finding.
-
-  - **`classify_host_error` (`:818–843`)** — the explicit `HostError` → `String` mapping for fail-run reasons. Match arms: `EntityCapExceeded(_)` ("exceeded entity-count cap"), `PathEscapeBreakerTripped` ("tripped path-escape breaker"), `Spawn(msg)`, `Handshake(me)`, `Transport(te)`, `Protocol(pe)` (formats `code` + `message`), wildcard `other`.
-
-  - **Entity/edge mapping** (`:846–946`) — `map_entity_to_record` derives `short_name` by rsplit('.'), serialises `entity.raw.extra` into `properties_json`, computes `content_hash` via local `content_hash_for_entity` (BLAKE3 over full file bytes for `module` kind, over normalised joined source lines `[start_line-1..end_line]` otherwise — `:907–927`). `map_edge_to_record` is a near-direct field-copy. Worth noting: `source_byte_start`/`source_byte_end` are hard-coded to `None` on entities — only the line range is captured. Edges keep byte ranges.
-
-  - **Unresolved call-site bookkeeping (B.4*)** (`:948–1055`) — `map_unresolved_call_sites_for_file` groups sites by caller; checks "authoritative" mode (where `stats.unresolved_call_sites_total == stats.unresolved_call_sites.len()`) and pre-creates empty `PendingUnresolvedCallSites` for every function entity in the batch so the writer's `ReplaceUnresolvedCallSitesForCaller` can clear stale rows for callers that no longer have any unresolved sites. `validate_unresolved_call_site` enforces non-negative ordinal, non-empty/`<=512`-byte callee_expr, monotone byte range. `unresolved_call_site_key` is a BLAKE3 of `caller_entity_id || start_be || end_be || callee_expr`.
-
-  - **Source-tree walk** (`:1063–1170`) — `walk_dir` is hand-rolled `std::fs::read_dir` recursion (no `walkdir` dep), with `SKIP_DIRS = [".clarion",".git",".hg",".svn",".jj",".venv","__pycache__","node_modules"]`, symlink skipping, and per-entry I/O error counting (skipped entries are tallied and surfaced as one summary `warn` line at end of walk to avoid silent partial analysis). **Does not honour `.gitignore`** — flagged P4 at `:1078`.
-
-  - **Time helpers** (`:1180–1220`) — hand-rolled `iso8601_now()` using Howard Hinnant's `civil_from_days`, to avoid bringing in `chrono` for one format string.
-
-- `src/stats.rs` (37 lines) — `pub(crate) struct P95Accumulator { samples_ms: Vec<u64> }` with `record_many` and a nearest-rank `p95_ms()` (`stats.rs:21`). Sole client is the pyright-query-latency rollup in `analyze.rs`.
-
-**Integration tests** (`crates/clarion-cli/tests/`, 1217 LOC total):
-- `install.rs` (247 lines) — black-box `assert_cmd` cases covering `.clarion/` contents, `.gitignore` rule presence, refusal-on-existing, `--force` refusal.
-- `analyze.rs` (389 lines) — black-box analyze coverage.
-- `serve.rs` (213 lines) — runs `clarion serve` as a child process, frames JSON-RPC bodies via `clarion_core::plugin::{Frame, read_frame, write_frame}` (re-exported through the `plugin` facade for test consumers), exercises the MCP `initialize` round-trip and `summary` tool dispatch (it imports `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`).
-- `wp1_e2e.rs` (74 lines) — WP1 walking-skeleton; mostly install/analyze sanity.
-- `wp2_e2e.rs` (494 lines) — WP2 walking-skeleton consuming the on-disk `clarion-plugin-fixture` binary (declared as a `[dev-dependencies]` workspace member in `Cargo.toml:33`).
-
-**Dependencies:**
-
-- Inbound:
-  - End-users / shell / CI (the binary).
-  - `tests/e2e/sprint_1_walking_skeleton.sh` and `tests/e2e/sprint_2_mcp_surface.sh` invoke it as a subprocess.
-  - `tests/perf/b8_scale_test/driver.py` (B.8 scale-test harness) invokes it as a subprocess.
-  - No Rust-level inbound deps — this is a `[[bin]]`-only crate and exposes no library API (`Cargo.toml:12–14`).
-
-- Outbound:
-  - `clarion-core` — `PluginHost`, `discover`, `Manifest`, `DiscoveredPlugin`, `AcceptedEntity`/`AcceptedEdge`, `AnalyzeFileOutcome`, `AnalyzeFileStats`, `UnresolvedCallSite`, `CrashLoopBreaker`/`CrashLoopState`, `HostError`, `HostFinding`, `FINDING_DISABLED_CRASH_LOOP`, `LlmProvider`, `OpenRouterProvider`/`OpenRouterProviderConfig`, `Recording`/`RecordingProvider` (used in `analyze.rs:19–23`, `serve.rs:7–9`).
-  - `clarion-storage` — `Writer`, `ReaderPool`, `WriterCmd`, `EntityRecord`, `EdgeRecord`, `RunStatus`, `UnresolvedCallSiteRecord`, `DEFAULT_BATCH_SIZE`/`DEFAULT_CHANNEL_CAPACITY`, `pragma`, `schema` (used in `analyze.rs:24–27`, `install.rs:20`, `serve.rs:12`).
-  - `clarion-mcp` — `ServerState`, `config::{McpConfig, ProviderSelection, select_provider_with_env}`, `filigree::FiligreeHttpClient`, `serve_stdio_with_state_on_runtime` (used in `serve.rs:10–11, 52, 71`).
-  - Third-party: `clap` (derive CLI), `tokio` (runtime + `spawn_blocking` + `block_on`), `anyhow` (error type), `tracing` + `tracing-subscriber` (with `EnvFilter`), `dotenvy` (env loading), `uuid` (run IDs), `blake3` (content hashes + unresolved-site keys), `rusqlite` (install-time direct connection only — analyze and serve go through `Writer`/`ReaderPool`), `serde_json`.
-
-**Patterns Observed:**
-
-- **Pattern A buffering** (documented at `analyze.rs:7`): plugin work runs synchronously inside `spawn_blocking`, returns a `BatchResult` to the async caller, and only then does the caller emit `WriterCmd::Insert{Entity,Edge}` over the writer-actor channel. The blocking task never touches the writer directly.
-- **Tri-state run outcome** (`Completed` / `SoftFailed` / `HardFailed`): explicitly distinguishes "plugin crashed but other plugins' entities should still persist" (SoftFailed → `CommitRun(Failed)`) from "writer-actor itself is broken" (HardFailed → `FailRun`). Comment at `:543–556` is load-bearing — the chosen WriterCmd differs by branch.
-- **Atomic claim+transition style errors**: `JoinError` is *not* `?`-propagated; it's intercepted by `handle_plugin_task_join_result` and reshaped into a crash reason so the run-row resolution machinery still fires. The bypass regression is named in code (`clarion-cf17e4e779`) at `:1230–1236`.
-- **Best-effort cleanup with auditable fallback**: `install.rs` removes a partial `.clarion/` on bootstrap failure and logs (not bails) if cleanup itself fails; `analyze.rs::run_plugin_blocking` always reaps the child even on the kill path.
-- **Single-thread current-thread runtime for stdio loops, multi-thread for analyze**: `serve.rs:45–48` deliberately uses `Builder::new_current_thread()` (the stdin loop is the only thing actually running); `main.rs:22–25` uses `new_multi_thread` for analyze because `spawn_blocking` needs a worker thread.
-- **Direct schema apply in install, writer-actor everywhere else**: `install.rs` opens its own `rusqlite::Connection` to run pragmas + migrations (the writer-actor doesn't exist yet at install time); after that, every write goes through `WriterCmd::*`.
-- **Stats JSON is structured but stringified**: `CommitRun.stats_json` is built via `serde_json::json!` and then `.to_string()` (`analyze.rs:452–465`), matching `clarion-storage`'s `String` field signature.
-
-**Concerns:**
-
-- **`analyze::run` is a single ~500-line `async fn` with `#[allow(clippy::too_many_lines)]` at `:39`.** It mixes plugin discovery, file walking, per-plugin orchestration, writer-actor lifecycle, crash-loop policy, and three-way outcome resolution. The phase banners (`── Writer actor ──`, `── Discover plugins ──`, etc.) prove the author recognised the seams; extracting at least the per-plugin loop and the outcome-resolution match into named helpers would reduce the cognitive cost and make adding a fourth `RunOutcome` variant safer.
-- **`source_byte_start` / `source_byte_end` are hard-coded `None` on entity records** (`analyze.rs:873–874`). The schema columns exist (`EntityRecord` carries them) and edges do populate them. Either the plugin should emit byte offsets and the CLI should plumb them, or the entity columns are documented dead weight.
-- **Hand-rolled date math** (`civil_from_unix_secs`, `:1197–1220`) was justified for Sprint 1 by avoiding `chrono`. With `dotenvy`, `blake3`, `uuid`, and `tracing-subscriber` already in tree, the "we don't have a date dep" rationale is thinner now; the comment at `:1175–1179` itself anticipates promoting `chrono` "at that point." Worth a follow-up issue.
-- **The source walk does not honour `.gitignore`** (P4 noted in-code at `:1078`). On the `elspeth` corpus this likely means walking generated and vendored code paths the operator considers out-of-scope. `SKIP_DIRS` is a coarse stopgap.
-- **`install.rs::initialise_db` opens a connection, applies pragmas + migrations, and lets it drop without an explicit close.** SQLite handles this safely (the dtor closes the handle and flushes WAL), but the symmetry with the writer-actor's explicit `Drop` and the explicit ordering elsewhere makes this stand out. Not a defect; a stylistic gap.
-- **Serve's LLM writer is independent from the analyze writer.** When `clarion serve` is up *and* `clarion analyze` is run in another process, two `Writer` actors hold connections to the same `clarion.db`. The pragma layer (WAL + `busy_timeout`) is what keeps that safe — this is a `clarion-storage` invariant the CLI relies on but doesn't enforce or test in the cli-tests. Worth verifying in the storage subsystem brief.
-- **`--force` accepted but unimplemented.** `install.rs:87–92` rejects the flag with a `bail!`. Sprint-2+ has not implemented the overwrite path despite the `cli.rs:17` doc-comment hinting at one. If the operator workflow has stabilised, either implement it or remove the flag.
-- **No integration test exercises the `SoftFailed` path end-to-end.** `analyze.rs` tests cover `Completed` and `SkippedNoPlugins`; the soft-fail branch (where one plugin crashes but another succeeds) is the most subtle path — it's the one where an entity batch and a `status='failed'` UPDATE share a single SQLite transaction — and no `tests/analyze.rs` case (per a `grep` of the test file's signatures, not deep-read this pass) targets it. The crash-loop unit tests inside `analyze.rs:tests` cover `handle_plugin_task_join_result` but not the writer side of the soft-fail folding.
-
-**Confidence:** High — read `main.rs`, `cli.rs`, `install.rs`, `serve.rs`, `stats.rs`, and `Cargo.toml` in full; read `analyze.rs:1–542` (the full async `run`), `:559–815` (RunOutcome, JoinError helper, BatchResult/BatchStats/PendingUnresolvedCallSites structs, run_plugin_blocking, reap_and_classify_exit), `:818–843` (classify_host_error), `:846–946` (entity/edge mapping + content hashing), `:948–1055` (unresolved-call-site mapping), `:1057–1170` (source walk), and `:1180–1220` (time helpers). Cross-validated outbound deps by reading the import block at `analyze.rs:19–27`, `serve.rs:7–12`, `install.rs:20`; confirmed against `Cargo.toml:17–29`. Sample of test headers read for `tests/install.rs` and `tests/serve.rs`. Phase-level walkthrough of `analyze::run` annotated with line ranges throughout. The five open questions in the brief are answered in the text above with file:line citations.
-
-**Risk Assessment:**
-
-- **God-function risk on `analyze::run`** (high likelihood, medium impact). Length is already a documented smell. Mitigation: extract the per-plugin loop and outcome resolution; add `SoftFailed` integration coverage before extraction so the refactor has a regression net.
-- **Stale CLI surface risk** (low likelihood, low impact). `--force` advertised but unimplemented; could mislead a CI author. Mitigation: implement or remove.
-- **Multi-process writer correctness** (low likelihood, high impact). Two `Writer` actors against one DB rely on `clarion-storage` pragma discipline (WAL + `busy_timeout`). The CLI is the only place this combination is wired in production. Mitigation: a serve+analyze concurrent integration test would prove the invariant from the CLI side; right now the discipline is owned by `clarion-storage` and trusted by the CLI.
-
-**Information Gaps:**
-
-- `tests/analyze.rs` (389 lines) was not deep-read this pass; the claim that no test exercises the `SoftFailed` path is based on the test file's signature surface and the comments in `analyze.rs`, not on a function-by-function read. A follow-up could promote that claim from "likely" to "verified" or refute it.
-- `select_provider_with_env`'s exact precedence (env-var override of YAML vs YAML wins) is `clarion-mcp::config`'s concern, not visible from CLI source. The CLI passes a `|name| std::env::var(name).ok()` closure (`serve.rs:34`) and trusts the resolver.
-- Whether the LLM `Writer` spawned in `serve.rs` and the `analyze` `Writer` would conflict on the same `clarion.db` was not verified end-to-end — only that pragma discipline in `clarion-storage` is intended to absorb it.
-
-**Caveats:**
-
-- Line counts include `#[cfg(test)]` blocks where present in `src/`. `analyze.rs:1224+` contains an in-source `mod tests` whose contents were not deep-read beyond the `handle_plugin_task_join_result` regression comment.
-- The `clarion.yaml` stub written by `install` (`install.rs:28–52`) commits the CLI to a specific config shape (model id `anthropic/claude-sonnet-4.6`, default Filigree port `8766`, default OpenRouter endpoint). Those defaults belong to the operator config story, not the CLI's responsibility surface — flagged here only as a fact, not a critique.
-- No code-quality assessment is made — that is an `axiom-system-architect:assess-architecture` concern.
-## Test-only Rust fixture plugin (`clarion-plugin-fixture`)
-
-**Location:** `crates/clarion-plugin-fixture/src/`
-
-**Responsibility:** Protocol-compatible stand-in for a real language plugin: a minimal Rust binary speaking the same Content-Length-framed JSON-RPC 2.0 protocol on stdin/stdout as the Python plugin, used by `clarion-core`'s `host_subprocess` integration test to exercise `PluginHost::spawn` end-to-end without bringing a Python interpreter and pyright into the test loop.
-
-**Key Components:**
-
-- `Cargo.toml` (19 lines) — declares a single `[[bin]]` target (`clarion-plugin-fixture`, `src/main.rs`); depends on `clarion-core` (path dep, version `0.1.0-dev`) and `serde_json` from the workspace; inherits workspace `[lints]`. No library is published.
-- `src/main.rs` (128 lines, full code) — the entire plugin. One blocking `loop` over `read_frame(&mut reader, ContentLengthCeiling::DEFAULT)` (`main.rs:33`); per-frame `serde_json::from_slice` to a free-form `Value` so it can branch on `id`-presence (notification vs. request) before typed deserialisation (`main.rs:37-46`). Five method branches matching the L4 protocol surface:
-  - `initialize` (request) → `InitializeResult { name: "clarion-plugin-fixture", version: "0.1.0", ontology_version: "0.1.0", capabilities: {} }` (`main.rs:68-76`).
-  - `initialized` (notification) → state transition only, no reply (`main.rs:50-53`).
-  - `analyze_file` (request) → extracts `params.file_path` (or `""`), echoes it back inside one stub entity `{"id": "fixture:widget:demo.sample", "kind": "widget", "qualified_name": "demo.sample", "source": {"file_path": <echoed>}}`, returns `AnalyzeFileResult { entities: vec![entity], edges: vec![], stats: default }` (`main.rs:77-108`).
-  - `shutdown` (request) → empty `ShutdownResult` (`main.rs:109-112`).
-  - `exit` (notification) → `std::process::exit(0)` (`main.rs:54-56`).
-- `src/lib.rs` (3 lines) — comment-only stub explaining the crate is binary-only; exists so Cargo resolves the workspace member cleanly.
-
-**Dependencies:**
-
-- Inbound: `crates/clarion-core/tests/host_subprocess.rs` is the sole consumer — it locates the binary via `CARGO_BIN_EXE_clarion-plugin-fixture`, falling back to `<target_dir>/{debug,release}/clarion-plugin-fixture`; the manifest `tests/fixtures/plugin.toml` is `include_bytes!`-embedded at compile time (`host_subprocess.rs:16`). CI's `walking-skeleton` job builds this binary as part of `cargo build --workspace --bins` so the test can find it on disk (see `CLAUDE.md` build-commands section: "wp2_e2e tests need clarion-plugin-fixture on disk").
-- Outbound: `clarion-core::plugin::limits::ContentLengthCeiling` (the 8 MiB default), `clarion-core::plugin::transport::{Frame, read_frame, write_frame}` (the shared framing codec), `clarion-core::plugin::{AnalyzeFileParams, AnalyzeFileResult, AnalyzeFileStats, InitializeResult, JsonRpcVersion, ResponseEnvelope, ResponsePayload, ShutdownResult}` (the typed protocol structs); `serde_json` for the free-form `Value` pre-dispatch.
-
-**Patterns Observed:**
-
-- **Protocol-by-shared-types.** The fixture reuses `clarion-core`'s own protocol structs (`InitializeResult`, `AnalyzeFileResult`, `ResponseEnvelope`, …) for response serialisation — there is no parallel schema definition. A breaking change to `protocol.rs` therefore fails compilation of the fixture, not at runtime under test, which is the right ordering.
-- **Same ceiling as production.** Frame reads use `ContentLengthCeiling::DEFAULT` (the ADR-021 §2b 8 MiB cap), with the source comment explicitly noting that `unbounded()` is now `#[cfg(test)]`-only (`main.rs:30-32`). The fixture lives under the same wire-cap discipline as a real plugin.
-- **Fail-fast on protocol violations.** Every recoverable branch in a real plugin is `std::process::exit(1)` here — malformed frame, non-object body, missing/non-string `method`, integer-id parse failure, unknown method, params-deserialise failure (`main.rs:34, 39, 45, 57, 64, 90, 113`). Acceptable because the consumer is exclusively an integration test; the alternative would obscure protocol-violation bugs behind fixture-side error handling.
-- **Notification vs. request branching on `id`-presence.** Reads the raw `Value` first, checks `id.is_some_and(|v| !v.is_null())` to decide whether the frame requires a response (`main.rs:42, 48-60`). This matches the JSON-RPC 2.0 spec and parallels the Python plugin's branching in `server.dispatch` (`server.py:239-261`).
-- **Stable identity for assertions.** `plugin_id = "fixture"`, kind `"widget"`, and the literal entity ID `"fixture:widget:demo.sample"` are baked into the source — `host_subprocess.rs` asserts on this exact string, so the test signal is exact-match rather than parse-and-inspect.
-
-**Concerns:**
-
-- **No request-id sanity on `shutdown`.** Unlike the Python plugin, the fixture doesn't gate `analyze_file` on having received `initialized` — `state.initialized` doesn't exist. This is fine for the single happy-path test it supports, but means the fixture cannot exercise the host's `-32002 NOT_INITIALIZED` error path. If a future test wanted to assert that the host *itself* sequences the handshake correctly, it would have to verify host-side state rather than fixture-side rejection.
-- **`exit(1)` on any malformed frame is observable only as a non-zero process exit.** The host-side test gets no structured signal about which branch failed. For an integration test fixture this is by design; flagging because anyone running the fixture by hand against a non-test client will see opaque exits.
-- **No stderr discipline.** A real plugin (Python's `stdout_guard.py`) reserves stdout strictly for framing; the fixture relies on the absence of any `eprintln!` or `println!` in its own code rather than installing a guard. For a 128-line file with `serde_json` as the only output-side dep this is fine, but worth noting as a delta from the production-plugin pattern.
-
-**Confidence:** High — Read `main.rs` (128 lines, 100% of file), `lib.rs` (3 lines, 100%), `Cargo.toml` (19 lines, 100%); cross-verified consumer via `crates/clarion-core/tests/host_subprocess.rs` lines 3-7, 15-27, and 60-66 (binary-location strategy, fixture identity assertions, manifest constants). Cross-validated against `docs/arch-analysis-2026-05-18-1244/01-discovery-findings.md` §4 Subsystem E framing and `CLAUDE.md` layout summary. Protocol identity confirmed by the matching set of imports from `clarion_core::plugin::*` against the Python plugin's `server.py:7-19` docstring describing the same five methods and response shapes. Content-Length framing parity confirmed via the explicit `ContentLengthCeiling::DEFAULT` (8 MiB) source comment matching the Python `MAX_CONTENT_LENGTH = 8 * 1024 * 1024` at `server.py:48`.
-
-**Information Gaps:**
-
-- Did not read the upstream `clarion_core::plugin::transport` module to verify exactly how `read_frame` / `write_frame` interpret the ceiling; took the source comment at face value.
-- Did not run `cargo build -p clarion-plugin-fixture` on the current branch to confirm the binary still compiles. Treated the unmodified `Cargo.toml` and the recent (b87bc1d) signoff record as sufficient evidence that the walking-skeleton CI job was green at sprint close.
-
-**Caveats:**
-
-- "Protocol-compat" here means *exact wire-shape compatibility* on the five L4 methods. The fixture does not exercise the `capabilities.wardline` probe shape, `parse_status` on module entities, `parent_id`/`contains` edges, calls/references resolution, the `stats` payload's `unresolved_call_sites`, or any of the Sprint-2 ontology surface. It is a *minimum*-shape test stand-in, not a feature-parity one.
-- The fixture's `ontology_version = "0.1.0"` (`main.rs:72`) is deliberately the Sprint-1 baseline; this is the version against which the host's manifest-handshake validator is tested. It does *not* track the Python plugin's `0.5.0` and shouldn't.
-
-**Risk Assessment:**
-
-- *Drift between fixture and real plugins.* The fixture has been stable since Sprint 1 close and the protocol contract is enforced by shared `clarion-core` types, so the drift surface is bounded to behavioural-not-structural divergence (e.g. a real plugin adding handshake side-effects the fixture doesn't model). The host-side test exercises only the structural surface, so this is a known-acceptable gap.
-- *Single-consumer dependency.* The fixture exists exclusively for `host_subprocess.rs`. If that test were retired, the fixture would become dead code; conversely, the test cannot be expanded to cover behaviours the fixture doesn't model without growing the fixture. Pre-existing carryover issue `clarion-adeff0916d` (fixture-binary self-build) tracks one known sharp edge here.
-- *Build-ordering coupling.* The walking-skeleton CI job depends on `cargo build --workspace --bins` running before `cargo nextest run` so the binary is on disk when `host_subprocess.rs` looks for it. This is documented in `CLAUDE.md` and codified in `.github/workflows/ci.yml`'s `walking-skeleton` job, but is an implicit dependency that would break if a future contributor used `cargo nextest run --workspace` without the prior `cargo build`.
-## Python language plugin (`plugins/python`)
-
-**Location:** `plugins/python/src/clarion_plugin_python/`
-
-**Responsibility:** Out-of-process language plugin that ingests a single Python source file at a time, extracts module/class/function entities plus `contains`/`calls`/`references` edges, and serves them to the Rust core over a Content-Length-framed JSON-RPC 2.0 channel on stdin/stdout (the L4 protocol).
-
-**Key Components:**
-
-- `__main__.py` (15 lines) — installs the stdout discipline guard, then delegates to `server.main()`; threads the server's exit code out to the host (`__main__.py:14`).
-- `server.py` (285 lines) — L4 JSON-RPC dispatch loop. Implements the five protocol methods exactly as the Rust host's typed `protocol.rs` expects: `initialize`/`initialized`/`analyze_file`/`shutdown`/`exit` (`server.py:226-261`). Owns `ServerState` (initialized flag, shutdown flag, captured `project_root`, lazy `PyrightSession`) and the `read_frame`/`write_frame` Content-Length codec with an 8 MiB symmetric cap matching ADR-021 §2b (`server.py:48`, `71-126`). `handle_initialize` captures the host-supplied `project_root` and embeds the Wardline probe result in `capabilities.wardline` (`server.py:141-153`). `handle_analyze_file` reads the file off disk, lazily constructs the `PyrightSession`, and calls `extractor.extract_with_stats(...)` (`server.py:177-221`).
-- `extractor.py` (744 lines, +98 on this branch for B.8) — AST → wire-shape extractor. `extract_with_stats` parses the source with `ast.parse`, prepends exactly one `module` entity (B.2 §3 Q1), then recursively walks via `_walk` to emit one `function` per `FunctionDef`/`AsyncFunctionDef` and one `class` per `ClassDef` (`extractor.py:261-344`, `_walk` at `589-668`). `parent_id` and one `contains` edge per non-module entity satisfy ADR-026 decision 2's dual encoding (`extractor.py:107-117`, `671-677`). `_ReferenceSiteCollector` is the separate `ast.NodeVisitor` pass for B.5* reference sites (`extractor.py:358-485`), then `extract_with_stats` hands the function IDs to `call_resolver.resolve_calls` and the reference sites to `reference_resolver.resolve_references` (`extractor.py:338-342`). Same-id collisions are handled at the emit boundary: `_has_overload_decorator` recognises `@overload` / `@typing.overload` / `@typing_extensions.overload` and skips emission *and* recursion entirely (`extractor.py:567-586`, `624`); any other duplicate (aliased overload imports, `@singledispatch.register def _():` runs) is dropped first-wins with a stderr line and a `duplicate_entities_dropped_total` bump (`extractor.py:629-637`).
-- `pyright_session.py` (1251 lines) — long-running `pyright-langserver --stdio` LSP client. See sub-section below.
-- `call_resolver.py` (64 lines) — `CallResolver` `Protocol` plus `CallsRawEdge` / `UnresolvedCallSite` / `Finding` TypedDicts; `NoOpCallResolver` is the test stand-in (`call_resolver.py:49-64`). `PyrightSession` is the production implementation.
-- `reference_resolver.py` (69 lines) — symmetric: `ReferenceResolver` `Protocol`, `ReferenceSite` dataclass, `ReferencesRawEdge` TypedDict, `NoOpReferenceResolver` (`reference_resolver.py:54-69`).
-- `entity_id.py` (75 lines) — Python side of the L2 byte-for-byte ADR-003+ADR-022 entity-ID assembler. Validates `plugin_id` / `kind` against the grammar `[a-z][a-z0-9_]*`, refuses the `:` separator inside any segment, raises typed `EmptySegmentError` / `GrammarViolationError` / `SegmentContainsColonError`. Cross-validated against `fixtures/entity_id.json` row-by-row (`entity_id.py:66-75`).
-- `qualname.py` (46 lines) — ADR-018 L7 canonical qualname. Pure-AST reconstruction of CPython's runtime `__qualname__`: walks the parent chain in reverse, prepending `parent.<locals>.` for function ancestors and `parent.` for class ancestors (`qualname.py:32-46`). Lock-in: this string must equal what Wardline produces for the same definition, otherwise the cross-product join breaks.
-- `wardline_probe.py` (56 lines) — L8 fail-soft Wardline probe. `importlib.import_module("wardline.core.registry")` plus `importlib.import_module("wardline")`, then a `packaging.version` half-open range check against the manifest's `[integrations.wardline].min_version` / `max_version` (`wardline_probe.py:36-56`). Returns one of three dicts: `{"status": "absent"}`, `{"status": "enabled", "version": ...}`, `{"status": "version_out_of_range", "version": ...}`. **Invoked once per session at `initialize`** (`server.py:151`), never per-file. The `wardline.core.registry` import is the named Loom-doctrine asterisk from `docs/suite/loom.md` §5; Sprint 1 only proves the import + version-pin handshake — REGISTRY is not yet consumed.
-- `stdout_guard.py` (62 lines) — replaces `sys.stdout` with a `_GuardedTextStdout` that raises `StdoutGuardError` on any write; captures the real `stdin.buffer` / `stdout.buffer` byte streams for the framing codec to use (`stdout_guard.py:57-62`). Single-shot, called by `__main__` before the dispatch loop starts.
-- `__init__.py` (3 lines) — `__version__ = "0.1.4"`.
-
-**Sub-section: `pyright_session.py` (1251 lines, ~17% of total plugin LOC)**
-
-This file is the entire pyright integration surface. Internal structure:
-
-- *Public class `PyrightSession`* (`:117-758`) — implements both the `CallResolver` and `ReferenceResolver` Protocols. Constructed lazily once per `analyze_file` session by `server.handle_analyze_file` and held on `ServerState.pyright` for the lifetime of the connection (`server.py:193-194`, closed in `shutdown` handler at `server.py:246-248`). Public surface: `__init__`/`__enter__`/`__exit__`/`close`/`resolve_calls`/`resolve_references`/`kill_for_test`/`stderr_thread_alive`. Constructor knobs (`init_timeout_secs=30`, `call_timeout_secs=5`, `max_restarts_per_run=3`, `max_reference_sites_per_file=2000`) are exposed for tests (`pyright_session.py:118-145`).
-- *Process lifecycle* — `_ensure_process` (`:505-516`) lazily spawns; `_start_process` (`:536-599`) does `subprocess.Popen([pyright-langserver, --stdio], cwd=project_root, env=..., stdin/stdout/stderr=PIPE)` and immediately calls `_initialize` with the LSP `initialize` request (`:601-616`). `_resolve_executable` (`:618-625`) walks: absolute-path → `sys.executable`'s sibling directory (i.e. the active venv) → `shutil.which`. A stderr-drain thread (`_start_stderr_drain` `:634-640`, `_drain_stderr` `:642-649`) keeps the 64 KiB `_stderr_tail` ring populated for diagnostics; the thread is daemonised.
-- *Restart / poison handling* — `_record_restart_or_poison` (`:518-534`) increments `_restart_count` and emits a `CLA-PY-PYRIGHT-RESTART` finding; after 3 restarts the session goes `_disabled = True` and emits one `CLA-PY-PYRIGHT-POISON-FRAME`. Five fail-soft `CLA-PY-PYRIGHT-*` finding subcodes are defined at the top of the file (`:34-41`).
-- *LSP transport* — `_request` (`:651-670`) writes Content-Length-framed JSON and busy-loops on `_read_message` skipping mismatched-id frames; `_notify` (`:672-674`) is the no-response variant; `_read_message` (`:693-714`) reads headers + body using `_read_line`/`_read_exact`/`_wait_readable` helpers (`:1218-1247`) that enforce a per-call deadline via `select.select` on the pipe fd.
-- *Call resolution* (`resolve_calls` + `_resolve_with_pyright` `:181-380`) — opens the file via `textDocument/didOpen`, issues `textDocument/prepareCallHierarchy` per function entity, then `callHierarchy/outgoingCalls` per returned item. Edges are grouped by source byte range; multi-target ranges produce one `ambiguous` edge with the candidate list in `properties.candidates` (per ADR-028 confidence tiers, `:359-369`). Two AST-side enrichers — `_ambiguous_dict_dispatches` and `_dunder_call_dispatches` (`:1003-1145`) — fold dict-of-callables and `__call__`-on-instance patterns that pyright doesn't track natively into the same `grouped` map. Always followed by `textDocument/didClose` in `finally:` (`:380`).
-- *Reference resolution* (`resolve_references` + `_resolve_references_with_pyright` `:228-453`) — hard cap of 2 000 sites per file (emits `CLA-PY-PY-REFERENCE-SITE-CAP` and returns early, `:238-250`); per-site `textDocument/references` queries with annotation-fallback retry (`:411-422`); deduplicates by `(from_id, to_id)` accumulator and finalises with `_reference_accumulator_to_edge` (`:922-937`). All exceptions are caught at the boundary and converted to fail-soft results.
-- *AST function-indexing helpers* (`_build_function_index`, `_collect_entities`, `_CallSiteVisitor`, `_DictDispatchVisitor`, `_DunderCallDispatchVisitor` `:760-1145`) — a parallel AST pass independent from `extractor.py`'s walker; necessary because `PyrightSession` needs LSP positions (line/character) for every function and class plus the per-function call-site index, neither of which the wire shape carries.
-
-**Dependencies:**
-
-- Inbound: Rust core's plugin host (`crates/clarion-core/src/plugin/host.rs`) spawns this plugin via the `clarion-plugin-python` console script; the host's typed `protocol.rs` (`InitializeResult`, `AnalyzeFileResult`, `AnalyzeFileStats`, `ShutdownResult`) is the wire contract; the host's writer-actor (`clarion-storage`) consumes the emitted entities and edges; the `walking-skeleton` CI job invokes the full pipeline.
-- Outbound: `pyright==1.1.409` (LSP server subprocess, pinned in both `pyproject.toml:20` and `plugin.toml:29`); `packaging>=24` (version-range parsing in the Wardline probe); Python stdlib only otherwise (`ast`, `json`, `subprocess`, `select`, `threading`, `importlib`, `pathlib`, `urllib.parse`). `wardline` is a **soft** outbound dependency — imported only to probe at `initialize`; absence is not an error. The doctrine asterisk noted in `docs/suite/loom.md` §5 is real: `wardline.core.registry` is imported by name (`wardline_probe.py:38`), and the manifest pins `[integrations.wardline] min_version=1.0.0 max_version=2.0.0` (`plugin.toml:48-55`).
-
-**Patterns Observed:**
-
-- **Protocol-typed wire boundary.** Every method handler returns a TypedDict whose shape mirrors the Rust host's serde structs exactly (`server.py:7-19` docstring enumerates this). The five JSON-RPC error codes used (`-32600`, `-32601`, `-32603`, `-32002`) are LSP-style (`server.py:51-54`). Out-of-spec frames raise `ProtocolError`, which propagates out of the loop and exits with status 1 (`server.py:284-285`).
-- **Fail-soft pyright integration.** Every external failure mode of `pyright-langserver` (not installed, install-check rejection, init timeout, runtime timeout, transport-closed, broken pipe, OSError) is caught at the `resolve_calls` / `resolve_references` boundary, downgraded to a `CLA-PY-PYRIGHT-*` finding, and returned as "unresolved" counts in the result — never raised back into the dispatch loop (`pyright_session.py:202-217`, `265-280`). The 3-restart cap then disables the session entirely for the run.
-- **Two-pass AST.** The extractor pass (`extractor.py`) produces wire entities + structural `contains` edges; a parallel AST pass inside `pyright_session.py` (`_build_function_index`, `_CallSiteVisitor`) builds the position-indexed function index pyright needs. The two never share a tree; this duplicates `ast.parse` work but keeps the extractor a pure function of source bytes.
-- **`Protocol`-typed resolvers with No-Op fallback.** `CallResolver` and `ReferenceResolver` are `typing.Protocol`s with `NoOpCallResolver` / `NoOpReferenceResolver` defaults baked into `extractor.extract`'s kwargs (`extractor.py:83-84`, `247-249`). Tests can construct the extractor without spawning pyright.
-- **Stdout-strictness via guard object.** `_GuardedTextStdout` raises rather than silently swallows; any library print() becomes a `StdoutGuardError`, which the dispatch boundary turns into a `_ERR_INTERNAL` JSON-RPC response (`server.py:259-260`). This is the plugin-side closure of WP2 UQ-WP2-08.
-- **Path-jail-aware path handling.** `_resolve_module_path` relativises only the path used for the dotted qualname prefix; the wire `source.file_path` stays exactly as the host sent it, so the host's path-jail (which canonicalises against `project_root`) sees the original (`server.py:156-174`, `extractor.py:24-32`).
-- **Single source of truth on ontology version.** The manifest declares `ontology_version = "0.5.0"` (`plugin.toml:46`); `server.py:36` redeclares the same constant `ONTOLOGY_VERSION = "0.5.0"`. Two declarations, no shared import — kept matched by hand per ADR-027.
-- **B.8 fix layered defence.** The `@overload`-stub skip in `_has_overload_decorator` is the *fast path* for the named PEP 484 case; the same-id dedup loop in `_walk` is the *belt-and-suspenders* for anything the pattern-based check misses (aliased imports, `@singledispatch.register def _():`). Both feed the same wire-correctness invariant (no two entities with identical IDs) so the host's `UNIQUE(entities.id)` never trips mid-run (`extractor.py:283-294`, `624-637`, `645-652`).
-
-**Concerns:**
-
-- **Doctrine asterisk still live.** `wardline_probe.py:38` imports `wardline.core.registry` by name — exactly the Loom-doctrine asterisk called out in `docs/suite/loom.md` §5. Retirement condition is documented but not yet met. Not a defect; flagged because any architecture-quality review should know this is deliberate.
-- **`ONTOLOGY_VERSION` is duplicated in two files (`server.py:36` and `plugin.toml:46`)** with no compile-time/runtime cross-check that they match. If a future ADR-027 minor bump updates one and forgets the other, the handshake validates the manifest value while the plugin behaves per the constant — silent skew. The comment at `server.py:38-41` acknowledges this and defers the manifest-flow-through.
-- **`PyrightSession.close()` masks errors from the LSP `shutdown`/`exit` exchange** (`pyright_session.py:170`): timeouts, transport-closed, broken pipe, and `OSError` are all swallowed before the kill-and-wait. This is the correct behaviour at process-end, but it means a pyright that hangs on shutdown gives no signal beyond the eventual `process.kill()`.
-- **`_resolve_with_pyright` busy-loops on mismatched `id` responses** (`pyright_session.py:663-666`). If pyright ever sends a stream of id-mismatched frames between request and response (server-initiated notifications, mismatched-cancel ack), the loop just keeps reading until the per-call deadline fires. The deadline upper-bounds it (5 s default), so this is bounded rather than fatal.
-- **`_resolve_module_path`'s fall-through to the raw path on `ValueError`** (`server.py:170-173`) writes the absolute path into `source.file_path` of every emitted entity, which the host's path-jail check will reject. The comment says this is intentional ("fall back to the raw path so the host's logs show the drift"); whether that's the right failure mode versus an explicit per-file error finding is a design call worth noting for axiom-system-architect.
-- **AST re-parse duplication.** `extractor.py` and `pyright_session._build_function_index` each call `ast.parse` on the same source bytes for every `analyze_file`. At elspeth-scale (~425k LOC Python) this is two AST walks per file, not one. Not yet measured; called out because the B.8 scale test on this branch is exactly where this would surface.
-
-**Confidence:** High — Read in full: `plugin.toml`, `pyproject.toml`, `server.py` (285), `extractor.py` (744), `qualname.py` (46), `wardline_probe.py` (56), `entity_id.py` (75), `stdout_guard.py` (62), `call_resolver.py` (64), `reference_resolver.py` (69), `__init__.py`, `__main__.py`. Sampled `pyright_session.py` top-level structure (every `def`/`class` declaration line) plus full reads of `__init__`, `close`, `resolve_calls`, `resolve_references`, `_resolve_with_pyright`, `_ensure_process`, `_record_restart_or_poison`, `_start_process`, `_initialize`, `_resolve_executable`, `_subprocess_env`, `_start_stderr_drain`, `_drain_stderr`, `_request`, `_notify`, `_live_process`, `_write_message`, `_read_message`. Cross-validated: B.8 `@overload` commit `29f0426` body cited verbatim, manifest pyright pin matches `pyproject.toml` pin (`1.1.409` in both `plugin.toml:29` and `pyproject.toml:20`), Wardline probe is initialize-only (single call site at `server.py:151`), the doctrine asterisk import path matches `loom.md` §5's wording. Tests directory inventory matches source-file inventory 1:1 (10 source files, 10 test files including `test_round_trip.py`).
-
-**Information Gaps:**
-
-- Did not exhaustively read `pyright_session.py` lines 715-1247 (the AST function-indexing helpers, dict-dispatch visitor, byte/position translators). Sampled enough to confirm shape but not every branch.
-- Did not read the test files (`tests/test_*.py`); test coverage claims would require that step.
-- Did not verify wire-shape claims by running the e2e script (`tests/e2e/sprint_1_walking_skeleton.sh`); compatibility is asserted from the Python TypedDicts vs. the Rust `protocol.rs` docstring at `server.py:7-19`, not from a live run on this branch.
-- Did not chase `clarion-core/src/plugin/host.rs:132-154` to confirm the `RawEntity` / `RawSource` shape claim cited in `extractor.py:8-22`. Treated as authoritative because the extractor docstring is dated to the same commit family as the host.
-
-**Caveats:**
-
-- LOC counts via `wc -l` include blank lines and docstring lines. The "actual code" share is lower; `extractor.py:1-54` is all docstring, for instance.
-- "B.8 +98 lines on this branch" is taken from the discovery-findings document's framing; I did not run `git diff main...HEAD -- extractor.py | wc -l` to verify exactness, but the commit `29f0426` body matches the behaviour read in `extractor.py:567-668`.
-- The `wardline_probe` integration is described as "fail-soft" based on the three return shapes; whether downstream consult-mode briefings actually do anything different when `status == "enabled"` versus `"absent"` is out of scope for this entry (it would require reading the MCP briefing assembler).
-
-**Risk Assessment:**
-
-- *Doctrine asterisk surface.* The `wardline.core.registry` import (`wardline_probe.py:38`) is a known, ratified asterisk under `loom.md` §5 — risk is bounded by the documented retirement condition, but it remains a point where the federation axiom is consciously bent. Any review must surface it.
-- *Wire-shape skew risk.* The plugin re-declares `ONTOLOGY_VERSION = "0.5.0"` (`server.py:36`) and `entity_kinds`/`edge_kinds`/`rule_id_prefix` (`plugin.toml:35-39`) as parallel sources of truth with the host's `protocol.rs`. Skew here would surface only at the handshake — the host's validator rejects mismatched `ontology_version` per ADR-027, so the risk is detected, not silent.
-- *Pyright-availability dependency.* The walking-skeleton CI job and any `analyze` run that requests `calls` or `references` edges hard-depends on `pyright-langserver` resolvable via PATH, the active venv, or absolute path (`pyright_session.py:618-625`). On hosts without Node, the plugin still ships entities (the no-op fallback path), but every function emits as "unresolved" — observable but not catastrophic.
-- *B.8 scale-test risk.* This branch (`sprint-2/b8-scale-test`) is precisely the change that hardens the extractor against the failure mode it was discovered under (UNIQUE collision on `@overload` stubs at elspeth scale). The fix is layered (semantic skip + safety-net dedup); the residual risk is aliased-overload imports plus identical-qualname intentional redefinitions, both of which now hit the safety-net path and log to stderr rather than crash.
diff --git a/docs/arch-analysis-2026-05-18-1244/03-diagrams.md b/docs/arch-analysis-2026-05-18-1244/03-diagrams.md
deleted file mode 100644
index 181d5681..00000000
--- a/docs/arch-analysis-2026-05-18-1244/03-diagrams.md
+++ /dev/null
@@ -1,281 +0,0 @@
-# 03 — Architecture Diagrams
-
-**Repository:** `/home/john/clarion`
-**Branch:** `sprint-2/b8-scale-test`
-**Generated:** 2026-05-18
-
-All diagrams are Mermaid, validated through the Mermaid Live renderer. They draw from `01-discovery-findings.md` and `02-subsystem-catalog.md`.
-
-Five views, in the C4-inspired order — context, container, then two narrative sequences and one component zoom.
-
----
-
-## 1 — System Context (C4 L1): Clarion in the Loom federation
-
-Clarion-as-a-system, the actors and the external systems it talks to. The two solid blue siblings (Filigree, Wardline) are owned by the same author and explicitly enrich-only / soft-import per `docs/suite/loom.md` §3–§5. The dashed line to Wardline marks the named v0.1 doctrine asterisk.
-
-```mermaid
-flowchart LR
-    classDef person fill:#1168bd,color:#fff,stroke:#0b4884
-    classDef softwareSystem fill:#1168bd,color:#fff,stroke:#0b4884
-    classDef external fill:#999999,color:#fff,stroke:#666666
-    classDef sibling fill:#438dd5,color:#fff,stroke:#2e6295
-
-    OP["Operator<br/>(developer / CI)"]:::person
-    AGENT["Consult-mode LLM agent<br/>(via MCP client)"]:::person
-
-    CLARION["<b>Clarion</b><br/>Code-archaeology service<br/>Rust core + language plugins<br/>SQLite-backed local state"]:::softwareSystem
-
-    PYRIGHT["pyright-langserver<br/>(LSP subprocess)"]:::external
-    OPENROUTER["OpenRouter HTTP API<br/>(LLM provider)"]:::external
-
-    FILIGREE["<b>Filigree</b><br/>Issue tracker<br/>(Loom sibling — enrich only)"]:::sibling
-    WARDLINE["<b>Wardline</b><br/>Static checks + fingerprints<br/>(Loom sibling — soft import)"]:::sibling
-
-    SOURCE[("Source tree<br/>(project_root)")]
-
-    OP -->|"clarion install / analyze / serve"| CLARION
-    AGENT -->|"MCP stdio<br/>2025-11-25"| CLARION
-    CLARION -->|"reads project files<br/>under jail"| SOURCE
-    CLARION -->|"spawns LSP subprocess<br/>(per Python plugin)"| PYRIGHT
-    CLARION -->|"HTTPS chat/completions<br/>strict-JSON, budget-bounded"| OPENROUTER
-    CLARION -->|"GET /api/entity-associations<br/>(enrich-only)"| FILIGREE
-    CLARION -.->|"import probe at handshake<br/>(asterisk: loom.md §5)"| WARDLINE
-```
-
-**Key facts:**
-- One operator + one MCP client are the primary actors.
-- Two outbound HTTP integrations (OpenRouter, Filigree) plus one subprocess (pyright). Wardline is import-only.
-- The MCP wire is stdio, not HTTP — `clarion serve` runs in the foreground of the agent's process tree.
-
----
-
-## 2 — Container view (C4 L2): inside the binary
-
-The `clarion` binary is the only deployment artifact. Five workspace crates inside it; two subprocess-protocol peers (one real Python plugin, one test fixture); three external endpoints; two persistent files under `.clarion/`.
-
-```mermaid
-flowchart TB
-    classDef binary fill:#1168bd,color:#fff,stroke:#0b4884
-    classDef crate fill:#85bbf0,color:#000,stroke:#5d82a8
-    classDef subproc fill:#fff2cc,color:#000,stroke:#d6b656
-    classDef datastore fill:#cccccc,color:#000,stroke:#666
-    classDef external fill:#999999,color:#fff,stroke:#666
-
-    subgraph CLARION_HOST["clarion binary (single executable)"]
-        direction TB
-        CLI["clarion-cli<br/>install / analyze / serve"]:::binary
-        CORE["clarion-core<br/>entity-ID + PluginHost<br/>LlmProvider + manifest<br/>jail / limits / breaker"]:::crate
-        STORAGE["clarion-storage<br/>writer-actor (sole rusqlite)<br/>deadpool reader pool<br/>9 WriterCmd variants"]:::crate
-        MCP["clarion-mcp<br/>MCP 2025-11-25<br/>7 read tools<br/>5-tuple cache + budget"]:::crate
-    end
-
-    PYPLUGIN["plugins/python<br/>clarion-plugin-python<br/>JSON-RPC subprocess"]:::subproc
-    FIXTURE["clarion-plugin-fixture<br/>(test-only)"]:::subproc
-
-    PYRIGHT["pyright-langserver"]:::external
-    OPENROUTER["OpenRouter HTTP"]:::external
-    FILIGREE_HTTP["Filigree HTTP"]:::external
-
-    DB[(".clarion/clarion.db<br/>SQLite WAL")]:::datastore
-    YAML[(".clarion/clarion.yaml<br/>operator config")]:::datastore
-
-    AGENT["LLM agent (MCP client)"]
-    OP["Operator (shell / CI)"]
-
-    OP -->|"argv"| CLI
-    AGENT -->|"stdio JSON-RPC"| CLI
-    CLI --> CORE
-    CLI --> STORAGE
-    CLI --> MCP
-    MCP --> CORE
-    MCP --> STORAGE
-    STORAGE --> CORE
-    CLI -->|"discover + spawn"| PYPLUGIN
-    CLI -.->|"spawn (tests only)"| FIXTURE
-    PYPLUGIN -->|"spawns once<br/>per session"| PYRIGHT
-    MCP -->|"strict-JSON"| OPENROUTER
-    MCP -->|"GET enrich"| FILIGREE_HTTP
-    STORAGE -->|"writer + readers"| DB
-    CLI -->|"writes on install"| DB
-    CLI -->|"reads on serve"| YAML
-```
-
-**Things worth noting:**
-- The Rust crate graph is acyclic: `cli` → {`mcp`, `storage`, `core`}; `mcp` → {`storage`, `core`}; `storage` → `core` (one symbol, `EdgeConfidence`).
-- The Python plugin is *not* a Rust crate; the only "dep" is the host-spawn-subprocess contract.
-- The MCP server speaks a separate stdio session from the analyze run. They can be running concurrently against the same `.clarion/clarion.db`; correctness relies entirely on `clarion-storage`'s WAL + `busy_timeout=5000` pragma discipline.
-
----
-
-## 3 — `clarion analyze` run (sequence)
-
-The happy path and the two named failure modes (`SoftFailed`, `HardFailed`). The `RunOutcome` taxonomy is at `crates/clarion-cli/src/analyze.rs:558–563`; the three terminal branches differ by *which* `WriterCmd` they send.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant OP as Operator
-    participant CLI as clarion-cli<br/>analyze::run
-    participant CORE as clarion-core<br/>PluginHost
-    participant PLUGIN as Plugin subprocess<br/>(Python or fixture)
-    participant WRITER as clarion-storage<br/>writer-actor
-    participant DB as .clarion/clarion.db
-
-    OP->>CLI: clarion analyze [PATH]
-    CLI->>WRITER: Writer::spawn(db_path)
-    CLI->>WRITER: BeginRun(run_id)
-    WRITER->>DB: INSERT runs (status=running) + BEGIN
-    Note over CLI: discover plugins on $PATH<br/>(clarion-plugin-*)
-    CLI->>CORE: discover()
-    loop per plugin
-        CLI->>CORE: PluginHost::spawn (pre_exec setrlimit)
-        CORE->>PLUGIN: stdin/stdout pipes
-        CORE->>PLUGIN: initialize (handshake)
-        PLUGIN-->>CORE: InitializeResult + capabilities
-        CORE->>PLUGIN: initialized
-        loop per file in plugin extensions
-            CLI->>CORE: host.analyze_file(path)
-            CORE->>PLUGIN: analyze_file
-            PLUGIN-->>CORE: entities + edges + stats
-            Note over CORE: 5-step validator pipeline<br/>field-size / kind / id / jail / cap
-            CORE-->>CLI: AcceptedEntity/Edge + HostFinding
-        end
-        CLI->>WRITER: InsertEntity * N
-        CLI->>WRITER: ReplaceUnresolvedCallSitesForCaller * N
-        CLI->>WRITER: InsertEdge * N (enforce_edge_contract)
-        WRITER->>DB: batched INSERTs (cadence=50)
-        CLI->>CORE: host.shutdown / kill / reap
-    end
-    alt all plugins OK
-        CLI->>WRITER: CommitRun(Completed, stats_json)
-        WRITER->>DB: UPDATE runs SET status='completed' + COMMIT
-    else some plugin crashed (SoftFailed)
-        CLI->>WRITER: CommitRun(Failed, failure_reason)
-        WRITER->>DB: UPDATE runs SET status='failed' + COMMIT (partial work kept)
-    else writer error (HardFailed)
-        CLI->>WRITER: FailRun(reason)
-        WRITER->>DB: ROLLBACK + UPDATE runs SET status='failed'
-    end
-    CLI-->>OP: exit code (0 / nonzero)
-```
-
-**Key invariants:**
-- All writes funnel through a single writer-actor task that owns the sole `rusqlite::Connection` (ADR-011).
-- The five-step host validator pipeline is the place where plugin-side guarantees become host-side facts: field-size, kind-declared, entity-id-matches, path-jail, entity-cap. Steps 0–2 only drop offending records; steps 3–4 escalate to plugin termination on breaker trip.
-- The `SoftFailed` branch is the one path where the same SQLite transaction carries both accepted entities *and* a `UPDATE runs SET status='failed'` — a partial-work-with-marker invariant.
-
----
-
-## 4 — MCP `summary` tool with cache miss → LLM dispatch (sequence)
-
-The richest narrative path in the codebase: the ADR-007 5-tuple cache lookup, budget reservation, `spawn_blocking` to the synchronous `LlmProvider`, JSON-shape validation, and writeback via the writer-actor.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant AGENT as MCP client<br/>(LLM agent)
-    participant MCP as clarion-mcp<br/>tool_summary
-    participant READER as clarion-storage<br/>ReaderPool
-    participant CACHE as summary_cache<br/>(SQLite)
-    participant BUDGET as BudgetLedger<br/>(in-memory)
-    participant PROV as OpenRouter<br/>(LlmProvider)
-    participant WRITER as writer-actor
-
-    AGENT->>MCP: tools/call summary { id }
-    MCP->>READER: with_reader → entity_by_id + summary_cache_lookup
-    READER->>CACHE: SELECT by 5-tuple<br/>(entity_id, content_hash, prompt_template_id,<br/> model_tier, guidance_fingerprint)
-    alt cache hit and not stale and not expired
-        CACHE-->>MCP: SummaryCacheEntry
-        MCP->>WRITER: TouchSummaryCache(last_accessed_at)
-        MCP-->>AGENT: summary envelope (cached=true)
-    else cache miss / stale_semantic / >180 days
-        MCP->>BUDGET: reserve_budget (pessimistic token estimate)
-        alt budget exhausted
-            BUDGET-->>MCP: token-ceiling-exceeded (sticky)
-            MCP-->>AGENT: ok=false, retryable=false
-        else budget OK
-            BUDGET-->>MCP: BudgetReservation (RAII)
-            Note over MCP: build_leaf_summary_prompt<br/>(LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1")
-            MCP->>PROV: spawn_blocking → invoke(LlmRequest)<br/>response_format strict-JSON
-            PROV-->>MCP: LlmResponse (text + usage)
-            MCP->>BUDGET: commit(usage.input + output)
-            MCP->>WRITER: UpsertSummaryCache(SummaryCacheKey, payload)
-            WRITER-->>MCP: ack via oneshot
-            MCP-->>AGENT: summary envelope (cached=false)
-        end
-    end
-```
-
-**Notes that don't fit on the diagram:**
-- The 4-tuple `InferredEdgeCacheKey` for the inferred-edges path is structurally identical: `(caller_entity_id, caller_content_hash, model_id, prompt_version)`. The flow looks the same except for an additional **in-flight coalescer** (`inferred_inflight: HashMap<InferredEdgeCacheKey, broadcast::Sender>`) with a 60-second timeout so concurrent identical dispatches share one LLM call.
-- `BudgetLedger.blocked` is sticky for the lifetime of `ServerState` — once one reservation overshoots, every subsequent LLM tool returns `token-ceiling-exceeded` until process restart. No reset path.
-- Filigree's `issues_for` path *also* uses `spawn_blocking` (for `reqwest::blocking`) — same bridging shape, no cache, three independent skip paths route to `issues_unavailable` to honour Loom's enrich-only contract.
-
----
-
-## 5 — Component zoom: `clarion-core::plugin::host` validator pipeline
-
-The internal organisation of `PluginHost::analyze_file` — the per-file dispatch shape inside the plugin host supervisor. Sourced from `crates/clarion-core/src/plugin/host.rs:1031–1198`.
-
-```mermaid
-flowchart TB
-    classDef accept fill:#c9e7c9,color:#000,stroke:#5a8a5a
-    classDef drop fill:#fff2cc,color:#000,stroke:#d6b656
-    classDef kill fill:#f4cccc,color:#000,stroke:#a64d4d
-    classDef entry fill:#85bbf0,color:#000,stroke:#5d82a8
-
-    START["host.analyze_file(path)"]:::entry
-    SEND["Send analyze_file request<br/>over JSON-RPC + read frame"]:::entry
-    OUTCOME["Decoded AnalyzeFileOutcome:<br/>entities, edges, stats"]:::entry
-
-    S0{"0. field-size cap<br/>(4 KiB scalar, 64 KiB extra)"}
-    S1{"1. ontology declared-kind<br/>(manifest entity_kinds)"}
-    S2{"2. entity-id identity<br/>(canonical_qualified_name ≡ id)"}
-    S3{"3. path-jail check<br/>+ PathEscapeBreaker tick"}
-    S4{"4. entity-cap check<br/>(plugin-declared budget)"}
-
-    EDGES["process_edges<br/>(drop-only, no kill paths)"]
-    STATS["process_stats<br/>(record p95 latency)"]
-    OUT_ACCEPT["AcceptedEntity ⇒ caller"]:::accept
-    DROP_F["drop record<br/>+ HostFinding"]:::drop
-    KILL_J["kill plugin<br/>(disabled-path-escape)"]:::kill
-    KILL_C["kill plugin<br/>(entity-cap exceeded)"]:::kill
-
-    START --> SEND --> OUTCOME --> S0
-    S0 -->|"oversize"| DROP_F
-    S0 -->|"OK"| S1
-    S1 -->|"undeclared kind"| DROP_F
-    S1 -->|"OK"| S2
-    S2 -->|"mismatch"| DROP_F
-    S2 -->|"OK"| S3
-    S3 -->|"escape + breaker tripped"| KILL_J
-    S3 -->|"escape (under threshold)"| DROP_F
-    S3 -->|"OK"| S4
-    S4 -->|"exceeded"| KILL_C
-    S4 -->|"OK"| OUT_ACCEPT
-    OUTCOME --> EDGES
-    OUTCOME --> STATS
-```
-
-**Design notes:**
-- Steps 0–2 are **pure-function validators** (`oversize_field`, `oversize_edge_field`, `invalid_unresolved_call_site_reason`, `validate_kind_string`); they emit a `HostFinding` and drop the offending row.
-- Steps 3–4 carry **kill paths** because they involve cross-record state: `PathEscapeBreaker` ticks once per offending entity and trips after a documented threshold, and entity-cap is a per-plugin budget that's only meaningful in aggregate.
-- The same drop-on-violation discipline is applied to edges, but with **no kill paths** — edges do not participate in breakers. Trade-off: an edge-heavy file can spam many findings; an entity-heavy file is bounded by the cap.
-
----
-
-## Coverage notes
-
-| C4 level | Diagram | Subsystems covered |
-|----------|---------|---------------------|
-| L1 Context | #1 | Clarion as a whole, all 5 external dependencies |
-| L2 Container | #2 | All 6 internal subsystems + 5 external |
-| L3 Component | #5 | `clarion-core::plugin::host` (largest production file) |
-| Sequence | #3 | `clarion analyze` lifecycle, all 3 terminal branches |
-| Sequence | #4 | MCP `summary` LLM dispatch, ADR-007 5-tuple cache |
-
-What's deliberately not drawn here (size / clarity vs. info-value tradeoff):
-- A component view of `clarion-mcp::lib.rs` — it has a clean banded structure (protocol surface → `ServerState` → per-tool handlers → LLM pipelines → transport loop → helpers) but the 7 tools × 4 substates each would dominate a single diagram. The catalog entry's tool table is the substitute.
-- A component view of `clarion-storage::writer` — the 9 `WriterCmd` variants are clean and listed in the catalog; visualising the per-variant SQL would obscure rather than illuminate.
-- A schema ER diagram — the catalog's ASCII schema sketch is sufficient for v0.1's 8-table footprint.
diff --git a/docs/arch-analysis-2026-05-18-1244/04-final-report.md b/docs/arch-analysis-2026-05-18-1244/04-final-report.md
deleted file mode 100644
index 5af69cce..00000000
--- a/docs/arch-analysis-2026-05-18-1244/04-final-report.md
+++ /dev/null
@@ -1,270 +0,0 @@
-# Clarion — Architecture Analysis Report
-
-**Repository:** `/home/john/clarion`
-**Branch:** `sprint-2/b8-scale-test` (17 commits ahead of `main`)
-**Commit at validation:** `363bb0a` (working-tree refreshed during validation pass)
-**Tags:** `v0.1-sprint-1`, `v0.1-sprint-2`
-**Date:** 2026-05-18
-**Methodology:** `axiom-system-archaeologist:analyze-codebase` — coordinator + per-subsystem subagents + validation gates
-**Source artifacts:**
-- `01-discovery-findings.md` — holistic scan, 384 lines
-- `02-subsystem-catalog.md` — six subsystem entries, ~650 lines, validation **NEEDS_REVISION (warnings)** → corrections applied inline
-- `03-diagrams.md` — five Mermaid diagrams (C4 Context + Container + 2 sequences + 1 component), validation **APPROVED**
-
----
-
-## 1. Executive summary
-
-Clarion is a **code-archaeology service** — single-binary Rust core + out-of-process language plugins — that ingests a Python codebase, normalises it into a typed entity/edge graph in local SQLite, and serves that graph plus on-demand LLM-generated leaf summaries and inferred call edges to consult-mode LLM agents over MCP. It is one of four products in the Loom suite (Filigree, Wardline, Clarion, Shuttle) authored by a single owner; the federation axiom (solo-useful + pairwise-composable + enrich-only, `docs/suite/loom.md` §3–§5) is the load-bearing constraint on cross-product design.
-
-The codebase is **roughly 30 000 LOC** — 24 727 Rust across 5 workspace crates, 5 629 Python in one plugin — backed by 92 markdown documents (requirements / system design / detailed design / 25 Accepted ADRs / per-sprint work-package docs / sprint sign-offs / handoff memos). Sprint 1 closed with the walking-skeleton end-to-end at `v0.1-sprint-1`; Sprint 2 closed at `v0.1-sprint-2` with seven MCP tools live and the B.8 scale test green against the `elspeth` corpus after a repair rerun. The current branch carries the B.8 fix follow-up (an extractor dedup hardening and an `ADR-031` schema-validation policy that adds `CHECK` constraints to closed core-owned vocabularies).
-
-**Architectural shape.** A clean layered crate graph (acyclic) — `clarion-core` (entity-ID, plugin host, LLM provider abstraction) → `clarion-storage` (writer-actor + reader-pool over a single SQLite database) → `clarion-mcp` (MCP server, ADR-007 5-tuple cache, budget ledger) → `clarion-cli` (glue binary). The Python plugin is a separate process speaking JSON-RPC over Content-Length-framed stdio. Two named v0.1 federation asterisks (Wardline→Filigree pipeline coupling routed through Clarion; Python plugin's soft import of `wardline.core.registry`) are documented and have retirement conditions.
-
-**Standout strengths.**
-- **Boundary discipline is real, not aspirational.** Plugin authority is enforced at the host (5-step validator pipeline at `clarion-core/src/plugin/host.rs:1031–1198`); storage authority is enforced at the writer-actor (edge contract with three `CLA-INFRA-EDGE-*` codes at `writer.rs:411`); cache-key correctness is enforced at the call site (ADR-007 5-tuple at `clarion-mcp/src/lib.rs:1010–1016`). Defence-in-depth between the writer-actor and ADR-031's new SQL `CHECK` clauses is a thoughtful choice, not a copy of one to the other.
-- **Plugin separation is a process boundary, not a trait abstraction.** The wire protocol is the contract; the test fixture is a 131-LOC second implementation that proves the contract by speaking it.
-- **Sprint-1 lock-ins held under Sprint-2 pressure.** L1–L9 from `docs/implementation/sprint-1/README.md` §4 are visible as concrete code shapes: ADR-003 entity-ID parity, ADR-011 actor/pool split, ADR-021 jail+limits, ADR-022 ontology authority, all still visibly load-bearing in Sprint-2 code without rewriting.
-- **No god-files.** The two largest source files (`clarion-core/src/plugin/host.rs` at 3 126 LOC and `clarion-mcp/src/lib.rs` at 2 712 LOC, growing during Sprint-2 follow-up) are coherent, banded, and internally documented. The catalog confirms `host.rs` is roughly 1 450 production LOC plus 1 700 LOC of test scaffolding.
-
-**Notable risks (full list in §5).**
-- One single-file `analyze::run` of ~500 lines orchestrates the analyze lifecycle without coverage for its `SoftFailed` branch (the soft-fail path that commits partial entity work and a `runs.status='failed'` UPDATE inside the same transaction).
-- Two source-of-truth duplications without compile-time enforcement: edge ontology (writer, manifest, ADR) and Python plugin `ONTOLOGY_VERSION` (`server.py` + `plugin.toml`).
-- One MCP raw SQL site (`reference_neighbors` at `clarion-mcp/src/lib.rs:2381`) bypasses the storage layer's typed query helpers and would not be caught by storage-side schema tests.
-- ADR-024's single edit-in-place migration has been edited three times; the retirement trigger ("external operator builds `.clarion/clarion.db` from a published Clarion build") is documented in-file but is on manual discipline only.
-- `BudgetLedger.blocked` is sticky for the lifetime of `ServerState` — one ceiling breach disables LLM tools until process restart, with no documented reset path.
-
-**Recommended next steps (full list in §7).**
-- Add `SoftFailed`-branch integration coverage to `crates/clarion-cli/tests/analyze.rs` before any extraction refactor of `analyze::run`.
-- Extract the per-tool dispatch handlers from `clarion-mcp/src/lib.rs` into a sibling `tools/` submodule once a Sprint-3 surface settles.
-- Audit cross-product vocabulary duplications: one issue per duplication (edge ontology; Python `ONTOLOGY_VERSION`).
-- Surface a Filigree-Linked tracker entry for the ADR-024 migration-retirement trigger so the manual condition is observable.
-
----
-
-## 2. Architecture at a glance
-
-Clarion's deployment model is **single binary + one subprocess per language plugin**. Operators run `clarion install` once to lay down `.clarion/clarion.db` + `.clarion/clarion.yaml` + a `.gitignore`. Then `clarion analyze` does the ingest run, and `clarion serve` (Sprint-2 addition) hosts the MCP stdio server for consult-mode agents. The plugin host spawns each `clarion-plugin-*` binary discovered on `$PATH`, speaks five JSON-RPC methods (`initialize` / `initialized` / `analyze_file` / `shutdown` / `exit`), and validates everything coming back through the five-step pipeline before persisting via the writer-actor.
-
-The federation context, the binary's container view, the analyze lifecycle, the MCP `summary` cache-miss → LLM dispatch flow, and the plugin host validator pipeline are diagrammed in `03-diagrams.md`. They are not duplicated here — refer to that file for the visual reference.
-
-| Layer | Crate(s) | Production LOC | Owns |
-|---|---|---|---|
-| Domain + safety | `clarion-core` | ~3 100 | EntityId grammar; PluginHost supervisor; LlmProvider trait + OpenRouter; manifest parser; jail + RSS + entity + crash-loop breaker |
-| Persistence | `clarion-storage` | ~1 950 | Writer-actor (sole `rusqlite::Connection`); deadpool-sqlite reader pool; schema migration runner; PRAGMA discipline; edge-contract validator; 5-tuple summary cache + 4-tuple inferred-edge cache |
-| Read surface | `clarion-mcp` | ~3 300 (`lib.rs` 2 712) | MCP 2025-11-25 over stdio; 7 read tools; ADR-007 cache lookup; budget ledger; in-flight LLM dispatch coalescer; Filigree enrich-only HTTP client |
-| Glue + UX | `clarion-cli` | ~1 740 | `clap` dispatch; `.clarion/` bootstrap; analyze orchestrator (~500-line async run); MCP server wiring |
-| Test fixture | `clarion-plugin-fixture` | 131 | Protocol-compatible test stand-in for the host's `host_subprocess` integration test |
-| Language plugin | `plugins/python` | ~2 670 | Python AST → entities + edges; `pyright-langserver` LSP client (1 251 LOC); Wardline soft-import probe; ADR-018 canonical qualname |
-
-The Rust workspace lints at `unsafe_code = "deny"` (downgraded from `forbid` with one documented exception: `pre_exec` + `setrlimit` in `clarion-core/src/plugin/limits.rs`, the only `unsafe` block in the codebase). Clippy is `pedantic = warn` with three pragmatic allows. Python is `mypy --strict`, `ruff select = ["ALL"]` with pragmatic ignores, complexity capped at 15 to match clippy. ADR-023 names these and the corresponding CI jobs as the floor; every PR must pass them.
-
----
-
-## 3. Subsystem walkthrough
-
-Each entry below is a 1–2 paragraph synthesis of the corresponding catalog entry. For the full per-subsystem treatment with file:line citations, see `02-subsystem-catalog.md`.
-
-### 3.1 `clarion-core` — domain + safety
-
-`clarion-core` owns the four primitives every other crate depends on: the canonical `EntityId` (a three-segment newtype validated against the cross-language `fixtures/entity_id.json` parity proof); the plugin host (`PluginHost<R, W>` — generic over reader/writer so subprocess and in-process mock share one validator pipeline); the `LlmProvider` trait with `OpenRouterProvider` + `RecordingProvider` implementations and stable prompt-template IDs (`LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1"`, `INFERRED_CALLS_PROMPT_VERSION = "inferred-calls-v1"` at `llm_provider.rs:10–11`); and the safety ceilings (jail, content-length, entity cap, RSS via `setrlimit`, crash-loop breaker).
-
-The crate's two heavy files are coherent: `plugin/host.rs` (3 126 LOC) is one struct + two constructors + a five-step validator pipeline + a 1 700-LOC test suite; `llm_provider.rs` (948 LOC) is request/response DTOs + the trait + `RecordingProvider` + `OpenRouterProvider` with its strict-JSON schema gate (the B.8 GREEN-rerun fix at `response_format_for_purpose:297`). Caching is not done in `clarion-core` — the 5-tuple cache key is materialised inside `clarion-mcp` and `clarion-storage`; the provider is a stateless dispatcher. The crate is fully synchronous (no `tokio` dependency); MCP-side async-from-sync bridging is via `spawn_blocking`.
-
-### 3.2 `clarion-storage` — persistence
-
-A writer-actor (single `tokio::task` owning the sole `rusqlite::Connection`) plus a `deadpool-sqlite` reader pool, both targeting one `.clarion/clarion.db` file. Nine `WriterCmd` variants (`BeginRun` / `InsertEntity` / `InsertEdge` / `InsertInferredEdges` / `UpsertSummaryCache` / `TouchSummaryCache` / `ReplaceUnresolvedCallSitesForCaller` / `CommitRun` / `FailRun`), each with a typed `oneshot` ack. Batch cadence is 50 writes (`DEFAULT_BATCH_SIZE` at `writer.rs:35`); query-time MCP writes interleave with analyze-time runs via `query_time_write` which commits the open batch before reopening `BEGIN` if a run is in progress.
-
-The schema is a single migration (289 lines at `migrations/0001_initial_schema.sql`) covering 8 base tables, 1 FTS5 virtual, 3 triggers, 1 view, 2 generated columns. ADR-031 (new on this branch) adds `CHECK` constraints on closed core-owned vocabularies (`edges.confidence`, `findings.{kind,severity,status}`, `summary_cache.stale_semantic`, `runs.status`) and deliberately omits them from plugin-extensible columns (`entities.kind`, `edges.kind`) — the writer-actor remains the canonical validator; CHECK is defence-in-depth. The migration has been edited three times (initial; 2026-05-03 ADR-024 vocabulary rename; 2026-05-18 ADR-031 CHECKs) under ADR-024's "edit-in-place until external operators build from a published Clarion build" policy.
-
-### 3.3 `clarion-mcp` — read surface
-
-The Sprint-2 addition. One Rust crate, three source files (`lib.rs` 2 712 + `config.rs` 352 + `filigree.rs` 238) plus a 1 710-line integration test file. The `lib.rs` grew through B.8 follow-up commits (`87036b1` reservation-poison fix; `363bb0a` inferred-target pre-filter) — visible growth trajectory, monitored not refactor-blocked. Speaks MCP protocol revision `2025-11-25` over stdio. Seven read tools (`entity_at`, `find_entity`, `callers_of`, `execution_paths_from`, `summary`, `issues_for`, `neighborhood`). Six are thin dispatch over `clarion-storage` helpers; the seventh (`summary`) plus the `confidence=inferred` branches of three others carry substantive LLM logic — cache lookup (ADR-007 5-tuple summary, 4-tuple inferred), budget reservation with RAII rollback, in-flight dispatch coalescing via a `broadcast` channel with a 60-second timeout, prompt construction via `clarion-core` helpers, provider invocation on `spawn_blocking`, JSON-shape validation, writeback via the writer-actor.
-
-Filigree integration is genuinely enrich-only: three independent skip paths route to an `issues_unavailable` envelope (`filigree-disabled` / `filigree-unreachable` / `filigree-client-error` / `entity-not-found`). The other six tools have no Filigree dependency. The single architectural smell is one raw SQL site (`reference_neighbors` at `lib.rs:2381`) that bypasses the storage layer; everything else routes through typed query helpers.
-
-### 3.4 `clarion-cli` — glue binary
-
-The `clarion` binary; `clap`-driven three-subcommand dispatch (`install`, `analyze`, `serve`). Loads `.env` from CWD or ancestor before tracing init. `install.rs` (168 LOC) is the only place that opens SQLite directly — apply PRAGMAs + migrations, write a stub `config.json`, write the ADR-005 `.gitignore`, write the operator `clarion.yaml`. `serve.rs` (136 LOC) wires a single-thread current-thread Tokio runtime, an LLM-only `Writer`, a `ReaderPool` (size 16), and the MCP server.
-
-The orchestrator is `analyze.rs` (1 436 LOC) with `analyze::run` a single ~500-line async function marked `#[allow(clippy::too_many_lines)]`. It owns plugin discovery, source-tree walk, per-plugin `spawn_blocking` dispatch, crash-loop accounting via the breaker from `clarion-core`, and the three-way `RunOutcome` resolution (`Completed` → `CommitRun(Completed)`; `SoftFailed` → `CommitRun(Failed)` with partial work persisted; `HardFailed` → `FailRun` rolling everything back). The phase banners inside `analyze::run` mark the obvious seams; extraction is a worthwhile but currently un-test-covered refactor (see §5).
-
-### 3.5 `clarion-plugin-fixture` — protocol test stand-in
-
-131 LOC across `main.rs` + `lib.rs`. Speaks the same Content-Length-framed JSON-RPC 2.0 protocol as a real plugin, but with hard-coded responses (one stub entity, no edges, fixed `ontology_version = "0.1.0"`). Consumed only by `crates/clarion-core/tests/host_subprocess.rs`. Re-uses `clarion-core`'s typed protocol structs so a breaking change to the wire shape fails compilation rather than at runtime. Same `ContentLengthCeiling::DEFAULT` (8 MiB) as production plugins.
-
-### 3.6 `plugins/python` — Python language plugin
-
-Ten Python files, 2 670 LOC. Speaks the L4 JSON-RPC protocol; uses `pyright-langserver` (pinned to `1.1.409`) for cross-reference resolution. The largest file is `pyright_session.py` at 1 251 LOC — a long-running LSP client with three-restart-then-poison fail-soft semantics, a 5-second per-call deadline, and a 64 KiB stderr-tail ring buffer for diagnostics. `extractor.py` (744 LOC, +98 on this branch for the B.8 fix) is the AST → wire-shape pass; the B.8 fix is layered defence — a semantic skip for `@overload` stubs plus a first-wins safety-net dedup that also catches aliased overload imports and `@singledispatch.register def _():`.
-
-`wardline_probe.py` runs once per session at handshake. The `wardline.core.registry` import (`wardline_probe.py:38`) is the named v0.1 doctrine asterisk — Sprint 1 only proves the import + version pin; consumption is deferred. `ONTOLOGY_VERSION = "0.5.0"` is declared in both `plugin.toml:46` and `server.py:36` without a cross-check; the handshake validates the manifest value, leaving the constant as a maintenance hazard.
-
----
-
-## 4. Cross-cutting concerns
-
-The following spans more than one subsystem and is governed by either an ADR or by `docs/suite/loom.md`. All are visible in catalog citations.
-
-| Concern | Governance | Implementation sites |
-|---|---|---|
-| **Entity-ID format** (3 colon-segments) | ADR-003 + ADR-022 | `clarion-core::entity_id.rs` (Rust); `plugins/python/.../entity_id.py` (Python); `fixtures/entity_id.json` (parity proof) |
-| **JSON-RPC L4 protocol** (Content-Length framing, 5 methods, 8 MiB cap) | ADR-002 | `clarion-core::plugin::transport` + `protocol.rs`; `clarion-plugin-fixture::main`; `plugins/python/.../server.py` |
-| **Plugin authority + jail + RSS** | ADR-021 | `clarion-core::plugin::{jail, limits, breaker, host}` |
-| **Core / plugin ontology ownership** | ADR-022 | Host validator pipeline + manifest validator |
-| **Edge confidence tiers** (`resolved` / `ambiguous` / `inferred`) | ADR-028 | `clarion-storage::writer::enforce_edge_contract`; `clarion-mcp::optional_confidence` |
-| **Edge ontology** (`contains` / `calls` / `references` + 6 anchored / structural kinds) | ADR-026 / ADR-028 | Hard-coded in `clarion-storage::writer.rs:394–401`; declared in `plugin.toml:38`; documented in ADR — **3-place duplication, no cross-check** |
-| **Ontology version semver** (currently `0.5.0` after B.5*) | ADR-027 | Validated at host handshake; declared in `plugin.toml:46` + `server.py:36` |
-| **Summary cache 5-tuple key** | ADR-007 | `clarion-storage::cache::SummaryCacheKey`; lookup in `clarion-mcp::read_summary_inputs:1010–1016` |
-| **Schema migration governance** (edit-in-place until external build) | ADR-024 | `migrations/0001_initial_schema.sql` + `schema.rs`; manual retirement trigger |
-| **Schema-validation policy** (CHECK on closed vocabularies, not on plugin-extensible) | ADR-031 (new) | Six CHECK clauses in the migration; writer-actor remains canonical validator |
-| **Loom federation axiom** (solo-useful + pairwise-composable + enrich-only) | `docs/suite/loom.md` §3–§5 | `clarion-mcp::filigree` (enrich-only); `plugins/python/.../wardline_probe.py` (soft import; the named asterisk) |
-| **Filigree entity bindings** | ADR-029 | `clarion-mcp::filigree::EntityAssociation` + `FiligreeLookup`; `IssuesForAccumulator` drift classifier |
-| **Summary scope (leaf-only for v0.1)** | ADR-030 | `LEAF_SUMMARY_PROMPT_TEMPLATE_ID` is the single template; `summary` tool description encodes leaf scope |
-| **Tooling baseline** (cargo fmt / clippy -D warnings / nextest / doc-D / deny; ruff / mypy / pytest) | ADR-023 | `.github/workflows/ci.yml`: three jobs (`rust`, `python-plugin`, `walking-skeleton`) |
-
----
-
-## 5. Observations & risks (synthesised)
-
-This section folds the per-subsystem "Concerns" sections of the catalog into a prioritised global view. Each entry cites the originating catalog entry (and source line numbers where they sharpen the claim).
-
-### 5.1 High — worth a Sprint-3 thread
-
-**H-1. `analyze::run` is a single ~500-line `async fn` whose `SoftFailed` branch has no end-to-end coverage.**
-Catalog: `clarion-cli` §Concerns. Source: `crates/clarion-cli/src/analyze.rs:40–542` is the function; `:421–429` is the `Completed` → `SoftFailed` promotion (`Completed` + non-empty `crash_reasons`); `:478–509` is the `SoftFailed` branch that folds `UPDATE runs SET status='failed'` into the open entity transaction so partial work commits atomically with the failure marker. `analyze::run` is annotated `#[allow(clippy::too_many_lines)]` — the seams are documented with banner comments, the author clearly sees them. The risk is the unique-to-this-branch invariant: entity inserts and the `failed` marker share a single SQLite transaction. The other two branches (`Completed`, `HardFailed`) are tested; the soft-fail middle is not. **Recommendation:** add `tests/analyze.rs` coverage for `Completed-with-crash → CommitRun(Failed) with partial entity commit` before any extraction refactor.
-
-**H-2. Edge ontology is duplicated across three sites with no compile-time enforcement.**
-Catalog: `clarion-storage` §Concerns. `STRUCTURAL_EDGE_KINDS` + `ANCHORED_EDGE_KINDS` are hard-coded at `writer.rs:394–401`; the Python plugin's manifest declares `edge_kinds = ["contains", "calls", "references"]` independently at `plugin.toml:38`; ADRs 026/028 are the design source. Adding a kind requires edits in all three places; no test fails when only one moves. The host handshake catches manifest/manifest skew but not manifest/writer skew. **Recommendation:** lift `EdgeKindRegistry` to `clarion-core` so both the writer and the manifest validator consume one definition; alternatively, a unit test that builds the manifest's `edge_kinds` set and asserts it is a subset of the writer's hard-coded constants.
-
-**H-3. The ADR-024 single-migration retirement trigger is on manual discipline.**
-Catalog: `clarion-storage` §Concerns. The migration file (`0001_initial_schema.sql:10–16`) documents the trigger ("when an external operator builds `.clarion/clarion.db` from a published Clarion build") but no automated check fires. Three documented edits already (initial; 2026-05-03 ADR-024 vocabulary rename; 2026-05-18 ADR-031 CHECKs). A fourth edit that adds a column when an external Clarion build is in the wild silently breaks downstream operators. **Recommendation:** file a Filigree tracker entry for the trigger condition; ideally surface via a CI guard that fails when the migration file is modified after a published-build marker (a `published_build.txt` or git tag).
-
-### 5.2 Medium — worth a follow-up issue
-
-**M-1. One MCP raw SQL site bypasses `clarion-storage`.**
-Catalog: `clarion-mcp` §Concerns. `clarion-mcp/src/lib.rs:2470` (inside `reference_neighbors` declared at line 2455) is the only `conn.prepare(` site in the crate; everything else routes through typed query helpers in `clarion-storage::query`. A schema change to `edges` (column rename, ADR-026 kind addition) would not surface as a `clarion-storage` test failure. **Recommendation:** push `reference_neighbors` into `clarion-storage::query` with a typed result row; this keeps the storage layer the single point where edge-table SQL evolves.
-
-**M-2. `BudgetLedger.blocked` is sticky for the lifetime of `ServerState`.**
-Catalog: `clarion-mcp` §Concerns (`lib.rs:1180–1316`). Once any reservation overshoots, `blocked` flips true and every subsequent LLM tool returns `token-ceiling-exceeded` until process restart. No documented reset path; no surface to lift the ceiling. Matches a session-token semantic but is undocumented in the public API. **Recommendation:** either document the session semantic in the `clarion.yaml` operator docs OR expose an MCP admin tool `reset_budget` that requires a token-ceiling-exceeded precondition.
-
-**M-3. Python plugin's `ONTOLOGY_VERSION` is duplicated.**
-Catalog: Python plugin §Concerns. `server.py:36` declares `ONTOLOGY_VERSION = "0.5.0"`; `plugin.toml:46` declares the same. No shared import. The handshake validates the manifest value, leaving the constant as silent skew. Same shape of duplication as H-2 but lower blast radius (single language plugin, single ADR). **Recommendation:** import from `tomllib` at startup; assert equality on first use.
-
-**M-4. Dead stateless `handle_tool_call` stub in MCP public API.**
-Catalog: `clarion-mcp` §Concerns. `lib.rs:1701–1736` emits `tool-unimplemented` envelopes for every tool name. Reachable from the stateless `handle_json_rpc` (line 154) and `handle_frame` (line 1621) paths, which are exported. CLI uses `handle_frame_with_state` (the stateful path) so this is not a runtime defect inside Clarion, but it is a footgun in the public API. **Recommendation:** either remove the stateless tool-call surface from public exports, or forward to the stateful handlers behind a `OnceCell`-style state initialiser.
-
-**M-5. `source_excerpt` reads live disk, not the hashed snapshot.**
-Catalog: `clarion-mcp` §Concerns. `lib.rs:2151` uses `std::fs::read_to_string` on the on-disk file path to build LLM prompt input. The cache key still uses the stored `content_hash`, so a stale read produces a cache miss with a fresh-but-misaligned prompt. `stale_semantic` covers structural drift but not source-text drift. **Recommendation:** either persist a hash-keyed snapshot of source excerpts at ingest time, or refuse the summary call when the file's current hash != the stored hash (returning a typed `content-drift` error that callers can act on).
-
-### 5.3 Lower — observed but bounded
-
-**L-1.** `--force` flag declared but unimplemented in `clarion install` (`cli.rs:17–18`; rejected at `install.rs:87–92`). Either implement or drop.
-**L-2.** `clarion-cli` walks the source tree but does not honour `.gitignore` (P4 in-code at `analyze.rs:1078`); `SKIP_DIRS` is a coarse stopgap. At `elspeth` scale this likely means walking generated/vendored paths.
-**L-3.** Hand-rolled date math (`civil_from_unix_secs` in `analyze.rs:1197–1220`; `days_from_civil` in `clarion-mcp/src/lib.rs:2306–2314`). Justified for Sprint 1 by avoiding `chrono`; with `dotenvy`, `blake3`, `uuid`, `tracing-subscriber` already in tree, the rationale is thinner.
-**L-4.** AST is re-parsed once by `extractor.py` and once by `pyright_session._build_function_index` per `analyze_file`. At elspeth scale (~425k LOC Python) this is two AST walks per file. Not yet measured; B.8 is exactly where this would surface.
-**L-5.** `clarion-cli` serve and analyze can run concurrently against the same `.clarion/clarion.db` (two writer-actor processes); correctness depends entirely on `clarion-storage` WAL + `busy_timeout=5000`. The CLI does not test this combination; the discipline is in `clarion-storage` and trusted from above.
-**L-6.** `clarion-core/src/plugin/host.rs` has 14 `HostFinding` constructors at lines 450–637 inflating the file size; moving them to a sibling `host_findings.rs` would shave ~200 LOC without altering semantics.
-**L-7.** Filigree `actor` header silently omitted when blank rather than rejected at config-load (`filigree.rs:94–96`).
-**L-8.** No `Drop` cleanup for in-flight `broadcast::Sender` map entries on leader cancellation in MCP coalesced dispatch; low-probability leak, time-bounded by the 60-second wait.
-
-### 5.4 Risks the doctrine consciously accepts (do not "fix")
-
-**A-1.** Wardline soft-import asterisk (`wardline_probe.py:38`). Documented in `docs/suite/loom.md` §5 with a retirement condition. Sprint-1 lock-in.
-**A-2.** Wardline → Filigree pipeline coupling routed through Clarion. Same §5 register.
-**A-3.** `clarion-core/src/plugin/host.rs` size (3 126 LOC, prod 1 450). Coherent; banded; tests dominate; not a refactor priority.
-**A-4.** `clarion-mcp/src/lib.rs` size (2 623 LOC). Coherent; banded (protocol surface → `ServerState` → per-tool handlers → LLM pipelines → transport loop → helpers). Worth subdivision on size grounds, not correctness grounds. The catalog calls out the five plausible standalone modules.
-
----
-
-## 6. Sprint-2 deltas and working-tree state
-
-(Source: `01-discovery-findings.md` §7; cross-validated by `git log` and `git status` at analysis time.)
-
-**Whole-of-Sprint-2.** Six merged feature work-packages plus the OpenRouter provider swap since `v0.1-sprint-1`:
-- **B.2** — class + module entities (merge `e53191d`)
-- **B.3** — contains edges (merge `f9bd31e`, ontology `0.3.0`)
-- **B.4*** — calls edges + confidence tiers (merge `837d965`, ontology `0.4.0`)
-- **B.5*** — references edges via pyright (merge `e988a83`, ontology `0.5.0`)
-- **B.6** — seven-tool MCP surface (merge `ed64a16`)
-- **B.8** — scale test on the `elspeth` corpus (sign-off `ffdfd79`, GREEN after one repair rerun)
-- **OpenRouter swap** — replace Anthropic with OpenRouter (merge `35be4db`, infrastructure change, not a feature work-package)
-
-**Sprint hygiene** commits worth keeping in cache: `9ffc5c8` replaced `serde_yaml` with `serde_norway` (the safe YAML parser); `dc9bf41` made `.env` loading happen before tracing init; `a80c31a` added `.env` to `.gitignore`; `c7ec1dd` introduced ADR-031 CHECK clauses; `0cb61b4` fixed the manifest rule-ID grammar quantifier.
-
-**Current branch (`sprint-2/b8-scale-test`) vs. `main`** (at analysis-emit time, commit `363bb0a`). 17 commits ahead, 59 files changed, 25 650 insertions, 85 deletions. The bulk of insertions are committed test artifacts (B.8 scale-test result JSON snapshots, including new raw artifacts from `caa6459`); substantive source changes are modest:
-- `crates/clarion-core/src/llm_provider.rs` +193 lines (OpenRouter strict-JSON path)
-- `crates/clarion-mcp/src/lib.rs` +260 lines through `363bb0a` (B.8 follow-up — reservation-poison fix `87036b1` + inferred-target pre-filter `363bb0a`)
-- `crates/clarion-storage/migrations/0001_initial_schema.sql` +33 lines (ADR-031 CHECK clauses)
-- `crates/clarion-storage/tests/schema_apply.rs` +148 lines (new test verifying CHECK enforcement)
-- `docs/clarion/adr/ADR-031-schema-validation-policy.md` +426 lines (new ADR)
-- `plugins/python/src/clarion_plugin_python/extractor.py` +98 lines (B.8 `@overload`-stub skip + safety-net dedup)
-- `plugins/python/tests/test_extractor.py` +184 lines
-
-**Working tree (not yet committed).** `git status` at analysis time shows seven modified files + one new ADR (`ADR-031`) + a B.8 result-snapshot directory (`tests/perf/b8_scale_test/results/2026-05-18T0017Z/`). The GREEN-rerun results are partially committed and partially still in the working tree — this is in-flight work, not stale.
-
----
-
-## 7. Recommended follow-ups (prioritised)
-
-Each item maps to a §5 entry. Recommend filing in Filigree under `release:v0.1`, `sprint:3`.
-
-| # | Priority | Item | Rationale | Effort |
-|---|---|---|---|---|
-| 1 | High | Add `SoftFailed`-branch integration test to `tests/analyze.rs` | H-1 — unique transaction invariant currently uncovered | S |
-| 2 | High | Unify edge-kind registry across writer / manifest / ADR | H-2 — silent skew risk on Sprint-3 ontology additions | M |
-| 3 | High | Filigree tracker for ADR-024 migration retirement condition | H-3 — manual discipline at risk when external operators arrive | XS |
-| 4 | Medium | Push `reference_neighbors` SQL into `clarion-storage::query` | M-1 — schema-coupling outside the storage layer | S |
-| 5 | Medium | Decide on session-budget reset semantic + document | M-2 — operator surprise after one ceiling breach | S |
-| 6 | Medium | Single-source `ONTOLOGY_VERSION` in Python plugin (read `plugin.toml` at startup) | M-3 — same shape as H-2, lower blast radius | XS |
-| 7 | Medium | Remove or fold the stateless `handle_tool_call` MCP stub | M-4 — public-API footgun | XS |
-| 8 | Medium | Decide `source_excerpt` policy: snapshot at ingest, or refuse on drift | M-5 — correctness drift in LLM prompts under file edits | M |
-| 9 | Low | Implement or remove `clarion install --force` | L-1 | XS |
-| 10 | Low | `.gitignore`-aware source walk | L-2 — relevant at elspeth-scale | M |
-| 11 | Low | Decide on `chrono` adoption vs. keep hand-rolled date math | L-3 | XS |
-| 12 | Low | Measure AST re-parse cost at elspeth scale (B.8 telemetry) | L-4 | S |
-| 13 | Low | Document or test concurrent `serve` + `analyze` against one DB | L-5 | M |
-| 14 | Low | Move `HostFinding` constructors to a sibling module | L-6 — cosmetic | XS |
-| 15 | Low | Reject blank Filigree `actor` at config-load | L-7 | XS |
-| 16 | Low | `Drop` cleanup for `inferred_inflight` map entries | L-8 — bounded leak | S |
-
-(Carryover items from Sprint 1, listed in `CLAUDE.md` and not duplicated here: `clarion-48c5d06578` supervisor drain/discard; `clarion-928349b60f` jail TOCTOU; `clarion-35688034f0` read_frame deadline; `clarion-c0977ac293` RLIMIT_AS end-to-end observation; `clarion-adeff0916d` fixture-binary self-build. These should be triaged into Sprint-3 alongside §5's new finds.)
-
----
-
-## 8. Confidence and limitations
-
-### Confidence summary
-
-| Aspect | Confidence | Basis |
-|---|---|---|
-| Crate boundaries + dependency graph | **High** | `Cargo.toml` workspace + `use clarion_*::` grep per crate |
-| File-level structure of every subsystem | **High** | Per-subsystem agent read each crate's `src/*.rs` modules in full or near-full; LOC totals verified by `wc -l` |
-| ADR alignment claims | **High where ADR-cited; Medium where inferred** | ADRs 002/003/007/011/021/022/023/024/026/027/028/029/030/031 read or quoted; ADR text not re-opened in every subsystem pass |
-| LLM dispatch path correctness | **High** | Cache-key construction sites cited in both `clarion-mcp::lib.rs` and `clarion-storage::cache`; ADR-007 5-tuple verified literal-for-literal |
-| Sprint-2 deltas | **High** | `git log v0.1-sprint-1..HEAD` + `git diff --stat main..HEAD` + `git status` |
-| Quality / aesthetic judgments | **Out of scope** | This pass produces description, not assessment; see `axiom-system-architect:assess-architecture` for an opinionated quality review |
-
-### Limitations and information gaps
-
-- **Test coverage is not depth-read.** Test files were enumerated and sampled (signatures, top-level test names); no test was read end-to-end. Claims like "no `SoftFailed` integration coverage" rely on file-signature inspection, not function-by-function reading.
-- **External siblings (Filigree, Wardline) are not vendored.** Cross-product claims rely on manifest pins (`min_version = "1.0.0"`, `max_version = "2.0.0"`) plus the doctrine memos under `docs/suite/`. The actual sibling repo state was not inspected.
-- **The `scripts/` directory** was inventoried by `ls` only (one bash + small helpers per discovery); not deep-read this pass.
-- **B.8 scale-test result data** (~22 000 lines of JSON snapshots in `tests/perf/b8_scale_test/results/`) was not inspected. Only the harness (`driver.py`) was sampled for shape, and the sign-off (`docs/implementation/sprint-2/b8-results.md`) was read.
-- **One catalog contradiction was corrected during validation** (the `clarion-core` entry incorrectly stated `clarion-plugin-fixture` does not depend on `clarion-core`; the actual dep is on `clarion-core` types only and was corrected in-place). One minor LOC drift was footnoted (`clarion-mcp/src/lib.rs` 2 620 → 2 623). No other factual discrepancies survived the validation pass.
-
-### Audit trail
-
-```
-docs/arch-analysis-2026-05-18-1244/
-├── 00-coordination.md          coordination plan + execution log
-├── 01-discovery-findings.md    holistic scan (384 lines, single explorer)
-├── 02-subsystem-catalog.md     6 entries (~650 lines, 5 parallel explorers)
-├── 03-diagrams.md              5 Mermaid diagrams (this coordinator)
-├── 04-final-report.md          this report (this coordinator)
-└── temp/
-    ├── section-*.md             6 raw section files from subsystem agents
-    ├── validation-02-subsystem-catalog.md   NEEDS_REVISION (warnings) → fixed
-    └── validation-03-diagrams.md            APPROVED
-```
-
-Subagent identities used: `axiom-system-archaeologist:codebase-explorer` (6 instances, 5 in parallel + 1 for discovery); `axiom-system-archaeologist:analysis-validator` (2 instances — catalog + diagrams).
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-cli.md b/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-cli.md
deleted file mode 100644
index 926787d7..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-cli.md
+++ /dev/null
@@ -1,108 +0,0 @@
-## clarion-cli
-
-**Location:** `crates/clarion-cli/`
-
-**Responsibility:** Glue binary for the `clarion` executable; `clap`-driven subcommand dispatch (`install`, `analyze`, `serve`) that wires `clarion-core` (plugin host, LLM provider), `clarion-storage` (writer-actor + reader-pool), and `clarion-mcp` (stdio server) into a single end-user tool, and converts the storage layer's `RunStatus` taxonomy into shell exit codes.
-
-**Key Components:**
-
-- `src/main.rs` (33 lines) — process entry. Loads `.env` via `dotenvy::dotenv()` from CWD or any ancestor *before* `init_tracing()` so a `.env`-supplied `RUST_LOG` is in effect by the time the `EnvFilter` is built (commit `dc9bf41`, `main.rs:16–17`). Parses `cli::Cli`, then dispatches: `Install` and `Serve` run synchronously, `Analyze` builds an ad-hoc multi-thread `tokio::runtime::Builder` and `block_on`s `analyze::run(path)` (`main.rs:21–26`). No top-level runtime — each subcommand owns its own concurrency story.
-
-- `src/cli.rs` (43 lines) — `clap` derive structs only. `Install { --force, --path=. }`, `Analyze { path=. }`, `Serve { --path=., --config=Option<PathBuf> }`. `--force` is declared but documented in code as "not implemented in Sprint 1" (`cli.rs:17–18`).
-
-- `src/install.rs` (168 lines) — `.clarion/` bootstrap. Refuses if the dir already exists (`install.rs:104–110`); refuses if `--force` is passed because Sprint-1 never implemented overwrite (`install.rs:87–92`). On `mkdir` success delegates to `populate_after_mkdir`, which (a) opens `clarion.db`, applies `clarion_storage::pragma::apply_write_pragmas` then `clarion_storage::schema::apply_migrations` (`install.rs:162–167`), (b) writes a stub `config.json` (`schema_version: 1, last_run_id: null`, `install.rs:22–26`), (c) writes a `.gitignore` carrying ADR-005's tracked-vs-excluded rules (`install.rs:54–77`), (d) writes a substantive `clarion.yaml` stub at project-root with LLM and Filigree-integration scaffolding (`install.rs:28–52`). Crucially, `clarion.yaml` is left untouched if it already exists (`install.rs:150–158`). Includes a cleanup guard: any failure inside `populate_after_mkdir` triggers `fs::remove_dir_all(.clarion)` before bubbling the error so the next attempt isn't blocked by the existence check (`install.rs:117–127`; references issue `clarion-ed5017139f`).
-
-- `src/serve.rs` (136 lines) — MCP stdio server wiring, in this exact sequence (`serve.rs:14–91`): (1) assert `.clarion/clarion.db` exists or hint the operator to run `install` first (`serve.rs:15–21`); (2) canonicalise the project root; (3) read `clarion.yaml` via `McpConfig::from_path` or default to `McpConfig::default()` (`serve.rs:26–33`); (4) resolve provider selection via `select_provider_with_env` with a `std::env::var` closure (`serve.rs:34`); (5) build the `Arc<dyn LlmProvider>` via local `build_llm_provider` — `Disabled`/`Recording` (loads JSON fixture from `config.llm.recording_fixture_path` relative to project_root, `serve.rs:122–136`) / `OpenRouter` (passes `api_key`, `allow_live_provider: true`, model id, endpoint, and the attribution Referer/Title); (6) build the optional `FiligreeHttpClient::from_config` (`serve.rs:36–39`); (7) lock `stdin`/`stdout` and wrap stdin in `BufReader`; (8) build a **single-thread current-thread** tokio runtime, `runtime.enter()` as a guard so spawned tasks attach; (9) open the `ReaderPool` (size 16, `serve.rs:50`); (10) construct `ServerState::new(project_root, readers)`; (11) if a provider exists, spawn an LLM-only `Writer` against the same db_path with `DEFAULT_BATCH_SIZE`/`DEFAULT_CHANNEL_CAPACITY` and attach it via `state.with_summary_llm(writer.sender(), config.llm.clone(), provider)` (`serve.rs:55–65`); (12) if the Filigree client built, attach via `state.with_filigree_client(Arc::new(client))` (`serve.rs:66–68`); (13) hand off to `clarion_mcp::serve_stdio_with_state_on_runtime` (`serve.rs:70–72`); (14) drop `state`, drop `llm_writer` to close its sender, `runtime.block_on(handle)` to join the writer (`serve.rs:73–84`); (15) propagate `serve_result?` then the writer's `result?` so a clean MCP loop still fails the process if the writer errored.
-
-- `src/analyze.rs` (1436 lines) — the orchestrator. Internal structure, in source order:
-
-  - **Public entry `pub async fn run(project_path: PathBuf)` (`analyze.rs:40–542`)** — single ~500-line function flagged `#[allow(clippy::too_many_lines)]`. Phases (clearly demarcated by `── … ──` banner comments):
-    1. Path validation + `.clarion/` existence check (`:41–56`).
-    2. **Writer actor lifecycle — open**: `Writer::spawn(db_path, DEFAULT_BATCH_SIZE, DEFAULT_CHANNEL_CAPACITY)` returns a `(writer, handle)` pair; mints a `Uuid::new_v4()` run id and `BeginRun` via `writer.send_wait(...)` (`:60–75`).
-    3. **Plugin discovery** via `clarion_core::discover()`; successes pushed into `plugins`, failures collected into `discovery_errors` (`:78–97`).
-    4. **No-plugins branch** (`:99–171`): distinguishes "zero discovered + zero errors" (`SkippedNoPlugins` via `CommitRun`, exits 0 with a "skipped_no_plugins" stdout line) from "zero usable + non-empty errors" (`FailRun` with the concatenated error list, then `bail!` for non-zero exit). The fix for hiding manifest-parse bugs as `SkippedNoPlugins` is explicit in the comment at `:100–103`.
-    5. **Extension union + source walk** — collect_source_files walks once over the union of every plugin's declared extensions (`:174–184`).
-    6. **Per-plugin loop** (`'plugins:` label, `:211–412`): filter the global file list to this plugin's extensions; if empty, `continue`. Otherwise dispatch a `tokio::task::spawn_blocking(move || run_plugin_blocking(...))` and route its `JoinResult` through `handle_plugin_task_join_result` (which normalises a `JoinError` panic into a crash-reason string rather than `?`-propagating, `:259–271`, regression-tested as `clarion-cf17e4e779`). On `Err(reason)`: push into `crash_reasons`, tick `CrashLoopBreaker::record_crash`, and `break 'plugins` if `CrashLoopState::Tripped` (`:274–292`). On `Ok(BatchResult { entities, edges, unresolved_call_sites, stats, findings })`: fold per-batch stats into per-run accumulators; log every `HostFinding` individually (`:312–327`); flush entities then unresolved call-site replacements (`WriterCmd::ReplaceUnresolvedCallSitesForCaller`) then edges to the writer-actor in that exact order (`:341–391`). Any writer `send_wait` error stops the per-plugin loop and sets `run_outcome = HardFailed { reason }` (`:392–402`).
-    7. **`RunOutcome` resolution** (`:421–522`) — `enum RunOutcome { Completed, SoftFailed { reason }, HardFailed { reason } }` at `:558–563`. Promotion rule: `Completed` + non-empty `crash_reasons` → `SoftFailed` so the entity batch still commits *and* the run row marks failed (`:421–429`). Snapshots `writer.dropped_edges_total` and `writer.ambiguous_edges_total` (atomic counters held on the `Writer` handle) and `pyright_latency.p95_ms()` into the stats JSON (`:435–441`). The three terminal branches dispatch:
-       - `Completed` → `WriterCmd::CommitRun { status: RunStatus::Completed, … }`
-       - `SoftFailed { reason }` → `WriterCmd::CommitRun { status: RunStatus::Failed, … }` plus `"failure_reason": reason` in the stats JSON; the writer folds `UPDATE runs SET status='failed'` into the open entity tx so the partial work commits atomically with the failure marker (`:478–509`, comment at `:551–553`).
-       - `HardFailed { reason }` → `WriterCmd::FailRun` — rolls back the open tx (`:510–521`).
-    8. **Writer-actor lifecycle — close**: `drop(writer)` closes the command channel; `handle.await` joins the actor task (`:524–528`); on any `fail_reason`, `bail!` for non-zero exit — the run row is already correctly marked, this is purely about surfacing failure to the shell (`:530–534`).
-
-  - **`run_plugin_blocking` (`:646–759`)** — synchronous worker that `spawn_blocking` runs. Spawns the plugin via `PluginHost::spawn`; loops `host.analyze_file(file)` for each file in the per-plugin extension-filtered list; accumulates entities, edges, per-file `AnalyzeFileStats`, and per-file unresolved call sites; on the happy path tries `host.shutdown()` and falls back to `child.kill()` if shutdown writes to a closed pipe (`:731–742`); always `reap_and_classify_exit(&mut child, ...)` afterwards because `std::process::Child::Drop` does not `wait()` on Unix and would leak zombies (`:746–747`, comment at `:641–645`).
-
-  - **`reap_and_classify_exit` (`:769–815`)** — on `signal() == SIGKILL (9)` or `SIGSEGV (11)` appends `HostFinding::oom_killed(plugin_id, signal)` per ADR-021 §2d; other signals or non-zero exits get a `warn` log but no finding.
-
-  - **`classify_host_error` (`:818–843`)** — the explicit `HostError` → `String` mapping for fail-run reasons. Match arms: `EntityCapExceeded(_)` ("exceeded entity-count cap"), `PathEscapeBreakerTripped` ("tripped path-escape breaker"), `Spawn(msg)`, `Handshake(me)`, `Transport(te)`, `Protocol(pe)` (formats `code` + `message`), wildcard `other`.
-
-  - **Entity/edge mapping** (`:846–946`) — `map_entity_to_record` derives `short_name` by rsplit('.'), serialises `entity.raw.extra` into `properties_json`, computes `content_hash` via local `content_hash_for_entity` (BLAKE3 over full file bytes for `module` kind, over normalised joined source lines `[start_line-1..end_line]` otherwise — `:907–927`). `map_edge_to_record` is a near-direct field-copy. Worth noting: `source_byte_start`/`source_byte_end` are hard-coded to `None` on entities — only the line range is captured. Edges keep byte ranges.
-
-  - **Unresolved call-site bookkeeping (B.4*)** (`:948–1055`) — `map_unresolved_call_sites_for_file` groups sites by caller; checks "authoritative" mode (where `stats.unresolved_call_sites_total == stats.unresolved_call_sites.len()`) and pre-creates empty `PendingUnresolvedCallSites` for every function entity in the batch so the writer's `ReplaceUnresolvedCallSitesForCaller` can clear stale rows for callers that no longer have any unresolved sites. `validate_unresolved_call_site` enforces non-negative ordinal, non-empty/`<=512`-byte callee_expr, monotone byte range. `unresolved_call_site_key` is a BLAKE3 of `caller_entity_id || start_be || end_be || callee_expr`.
-
-  - **Source-tree walk** (`:1063–1170`) — `walk_dir` is hand-rolled `std::fs::read_dir` recursion (no `walkdir` dep), with `SKIP_DIRS = [".clarion",".git",".hg",".svn",".jj",".venv","__pycache__","node_modules"]`, symlink skipping, and per-entry I/O error counting (skipped entries are tallied and surfaced as one summary `warn` line at end of walk to avoid silent partial analysis). **Does not honour `.gitignore`** — flagged P4 at `:1078`.
-
-  - **Time helpers** (`:1180–1220`) — hand-rolled `iso8601_now()` using Howard Hinnant's `civil_from_days`, to avoid bringing in `chrono` for one format string.
-
-- `src/stats.rs` (37 lines) — `pub(crate) struct P95Accumulator { samples_ms: Vec<u64> }` with `record_many` and a nearest-rank `p95_ms()` (`stats.rs:21`). Sole client is the pyright-query-latency rollup in `analyze.rs`.
-
-**Integration tests** (`crates/clarion-cli/tests/`, 1217 LOC total):
-- `install.rs` (247 lines) — black-box `assert_cmd` cases covering `.clarion/` contents, `.gitignore` rule presence, refusal-on-existing, `--force` refusal.
-- `analyze.rs` (389 lines) — black-box analyze coverage.
-- `serve.rs` (213 lines) — runs `clarion serve` as a child process, frames JSON-RPC bodies via `clarion_core::plugin::{Frame, read_frame, write_frame}` (re-exported through the `plugin` facade for test consumers), exercises the MCP `initialize` round-trip and `summary` tool dispatch (it imports `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`).
-- `wp1_e2e.rs` (74 lines) — WP1 walking-skeleton; mostly install/analyze sanity.
-- `wp2_e2e.rs` (494 lines) — WP2 walking-skeleton consuming the on-disk `clarion-plugin-fixture` binary (declared as a `[dev-dependencies]` workspace member in `Cargo.toml:33`).
-
-**Dependencies:**
-
-- Inbound:
-  - End-users / shell / CI (the binary).
-  - `tests/e2e/sprint_1_walking_skeleton.sh` and `tests/e2e/sprint_2_mcp_surface.sh` invoke it as a subprocess.
-  - `tests/perf/b8_scale_test/driver.py` (B.8 scale-test harness) invokes it as a subprocess.
-  - No Rust-level inbound deps — this is a `[[bin]]`-only crate and exposes no library API (`Cargo.toml:12–14`).
-
-- Outbound:
-  - `clarion-core` — `PluginHost`, `discover`, `Manifest`, `DiscoveredPlugin`, `AcceptedEntity`/`AcceptedEdge`, `AnalyzeFileOutcome`, `AnalyzeFileStats`, `UnresolvedCallSite`, `CrashLoopBreaker`/`CrashLoopState`, `HostError`, `HostFinding`, `FINDING_DISABLED_CRASH_LOOP`, `LlmProvider`, `OpenRouterProvider`/`OpenRouterProviderConfig`, `Recording`/`RecordingProvider` (used in `analyze.rs:19–23`, `serve.rs:7–9`).
-  - `clarion-storage` — `Writer`, `ReaderPool`, `WriterCmd`, `EntityRecord`, `EdgeRecord`, `RunStatus`, `UnresolvedCallSiteRecord`, `DEFAULT_BATCH_SIZE`/`DEFAULT_CHANNEL_CAPACITY`, `pragma`, `schema` (used in `analyze.rs:24–27`, `install.rs:20`, `serve.rs:12`).
-  - `clarion-mcp` — `ServerState`, `config::{McpConfig, ProviderSelection, select_provider_with_env}`, `filigree::FiligreeHttpClient`, `serve_stdio_with_state_on_runtime` (used in `serve.rs:10–11, 52, 71`).
-  - Third-party: `clap` (derive CLI), `tokio` (runtime + `spawn_blocking` + `block_on`), `anyhow` (error type), `tracing` + `tracing-subscriber` (with `EnvFilter`), `dotenvy` (env loading), `uuid` (run IDs), `blake3` (content hashes + unresolved-site keys), `rusqlite` (install-time direct connection only — analyze and serve go through `Writer`/`ReaderPool`), `serde_json`.
-
-**Patterns Observed:**
-
-- **Pattern A buffering** (documented at `analyze.rs:7`): plugin work runs synchronously inside `spawn_blocking`, returns a `BatchResult` to the async caller, and only then does the caller emit `WriterCmd::Insert{Entity,Edge}` over the writer-actor channel. The blocking task never touches the writer directly.
-- **Tri-state run outcome** (`Completed` / `SoftFailed` / `HardFailed`): explicitly distinguishes "plugin crashed but other plugins' entities should still persist" (SoftFailed → `CommitRun(Failed)`) from "writer-actor itself is broken" (HardFailed → `FailRun`). Comment at `:543–556` is load-bearing — the chosen WriterCmd differs by branch.
-- **Atomic claim+transition style errors**: `JoinError` is *not* `?`-propagated; it's intercepted by `handle_plugin_task_join_result` and reshaped into a crash reason so the run-row resolution machinery still fires. The bypass regression is named in code (`clarion-cf17e4e779`) at `:1230–1236`.
-- **Best-effort cleanup with auditable fallback**: `install.rs` removes a partial `.clarion/` on bootstrap failure and logs (not bails) if cleanup itself fails; `analyze.rs::run_plugin_blocking` always reaps the child even on the kill path.
-- **Single-thread current-thread runtime for stdio loops, multi-thread for analyze**: `serve.rs:45–48` deliberately uses `Builder::new_current_thread()` (the stdin loop is the only thing actually running); `main.rs:22–25` uses `new_multi_thread` for analyze because `spawn_blocking` needs a worker thread.
-- **Direct schema apply in install, writer-actor everywhere else**: `install.rs` opens its own `rusqlite::Connection` to run pragmas + migrations (the writer-actor doesn't exist yet at install time); after that, every write goes through `WriterCmd::*`.
-- **Stats JSON is structured but stringified**: `CommitRun.stats_json` is built via `serde_json::json!` and then `.to_string()` (`analyze.rs:452–465`), matching `clarion-storage`'s `String` field signature.
-
-**Concerns:**
-
-- **`analyze::run` is a single ~500-line `async fn` with `#[allow(clippy::too_many_lines)]` at `:39`.** It mixes plugin discovery, file walking, per-plugin orchestration, writer-actor lifecycle, crash-loop policy, and three-way outcome resolution. The phase banners (`── Writer actor ──`, `── Discover plugins ──`, etc.) prove the author recognised the seams; extracting at least the per-plugin loop and the outcome-resolution match into named helpers would reduce the cognitive cost and make adding a fourth `RunOutcome` variant safer.
-- **`source_byte_start` / `source_byte_end` are hard-coded `None` on entity records** (`analyze.rs:873–874`). The schema columns exist (`EntityRecord` carries them) and edges do populate them. Either the plugin should emit byte offsets and the CLI should plumb them, or the entity columns are documented dead weight.
-- **Hand-rolled date math** (`civil_from_unix_secs`, `:1197–1220`) was justified for Sprint 1 by avoiding `chrono`. With `dotenvy`, `blake3`, `uuid`, and `tracing-subscriber` already in tree, the "we don't have a date dep" rationale is thinner now; the comment at `:1175–1179` itself anticipates promoting `chrono` "at that point." Worth a follow-up issue.
-- **The source walk does not honour `.gitignore`** (P4 noted in-code at `:1078`). On the `elspeth` corpus this likely means walking generated and vendored code paths the operator considers out-of-scope. `SKIP_DIRS` is a coarse stopgap.
-- **`install.rs::initialise_db` opens a connection, applies pragmas + migrations, and lets it drop without an explicit close.** SQLite handles this safely (the dtor closes the handle and flushes WAL), but the symmetry with the writer-actor's explicit `Drop` and the explicit ordering elsewhere makes this stand out. Not a defect; a stylistic gap.
-- **Serve's LLM writer is independent from the analyze writer.** When `clarion serve` is up *and* `clarion analyze` is run in another process, two `Writer` actors hold connections to the same `clarion.db`. The pragma layer (WAL + `busy_timeout`) is what keeps that safe — this is a `clarion-storage` invariant the CLI relies on but doesn't enforce or test in the cli-tests. Worth verifying in the storage subsystem brief.
-- **`--force` accepted but unimplemented.** `install.rs:87–92` rejects the flag with a `bail!`. Sprint-2+ has not implemented the overwrite path despite the `cli.rs:17` doc-comment hinting at one. If the operator workflow has stabilised, either implement it or remove the flag.
-- **No integration test exercises the `SoftFailed` path end-to-end.** `analyze.rs` tests cover `Completed` and `SkippedNoPlugins`; the soft-fail branch (where one plugin crashes but another succeeds) is the most subtle path — it's the one where an entity batch and a `status='failed'` UPDATE share a single SQLite transaction — and no `tests/analyze.rs` case (per a `grep` of the test file's signatures, not deep-read this pass) targets it. The crash-loop unit tests inside `analyze.rs:tests` cover `handle_plugin_task_join_result` but not the writer side of the soft-fail folding.
-
-**Confidence:** High — read `main.rs`, `cli.rs`, `install.rs`, `serve.rs`, `stats.rs`, and `Cargo.toml` in full; read `analyze.rs:1–542` (the full async `run`), `:559–815` (RunOutcome, JoinError helper, BatchResult/BatchStats/PendingUnresolvedCallSites structs, run_plugin_blocking, reap_and_classify_exit), `:818–843` (classify_host_error), `:846–946` (entity/edge mapping + content hashing), `:948–1055` (unresolved-call-site mapping), `:1057–1170` (source walk), and `:1180–1220` (time helpers). Cross-validated outbound deps by reading the import block at `analyze.rs:19–27`, `serve.rs:7–12`, `install.rs:20`; confirmed against `Cargo.toml:17–29`. Sample of test headers read for `tests/install.rs` and `tests/serve.rs`. Phase-level walkthrough of `analyze::run` annotated with line ranges throughout. The five open questions in the brief are answered in the text above with file:line citations.
-
-**Risk Assessment:**
-
-- **God-function risk on `analyze::run`** (high likelihood, medium impact). Length is already a documented smell. Mitigation: extract the per-plugin loop and outcome resolution; add `SoftFailed` integration coverage before extraction so the refactor has a regression net.
-- **Stale CLI surface risk** (low likelihood, low impact). `--force` advertised but unimplemented; could mislead a CI author. Mitigation: implement or remove.
-- **Multi-process writer correctness** (low likelihood, high impact). Two `Writer` actors against one DB rely on `clarion-storage` pragma discipline (WAL + `busy_timeout`). The CLI is the only place this combination is wired in production. Mitigation: a serve+analyze concurrent integration test would prove the invariant from the CLI side; right now the discipline is owned by `clarion-storage` and trusted by the CLI.
-
-**Information Gaps:**
-
-- `tests/analyze.rs` (389 lines) was not deep-read this pass; the claim that no test exercises the `SoftFailed` path is based on the test file's signature surface and the comments in `analyze.rs`, not on a function-by-function read. A follow-up could promote that claim from "likely" to "verified" or refute it.
-- `select_provider_with_env`'s exact precedence (env-var override of YAML vs YAML wins) is `clarion-mcp::config`'s concern, not visible from CLI source. The CLI passes a `|name| std::env::var(name).ok()` closure (`serve.rs:34`) and trusts the resolver.
-- Whether the LLM `Writer` spawned in `serve.rs` and the `analyze` `Writer` would conflict on the same `clarion.db` was not verified end-to-end — only that pragma discipline in `clarion-storage` is intended to absorb it.
-
-**Caveats:**
-
-- Line counts include `#[cfg(test)]` blocks where present in `src/`. `analyze.rs:1224+` contains an in-source `mod tests` whose contents were not deep-read beyond the `handle_plugin_task_join_result` regression comment.
-- The `clarion.yaml` stub written by `install` (`install.rs:28–52`) commits the CLI to a specific config shape (model id `anthropic/claude-sonnet-4.6`, default Filigree port `8766`, default OpenRouter endpoint). Those defaults belong to the operator config story, not the CLI's responsibility surface — flagged here only as a fact, not a critique.
-- No code-quality assessment is made — that is an `axiom-system-architect:assess-architecture` concern.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-core.md b/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-core.md
deleted file mode 100644
index 482cc433..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-core.md
+++ /dev/null
@@ -1,132 +0,0 @@
-## clarion-core
-
-**Location:** `crates/clarion-core/`
-
-**Responsibility:** Owns the canonical entity-ID grammar, plugin-host subprocess supervisor + JSON-RPC peer, LLM-provider trait + OpenRouter implementation, plugin-manifest parser, and the jail / RSS / entity / breaker ceilings that every other crate depends on for safety.
-
-**Public interface:**
-
-`lib.rs` is 47 lines (see `crates/clarion-core/src/lib.rs:1-47`) and is explicit that it is a curated facade per ticket `clarion-29acbcd042`. Re-exports at the crate root, grouped by submodule:
-
-- **From `entity_id`**: `EntityId`, `EntityIdError`, free function `entity_id(plugin, kind, qualname)` — the cross-language assembler.
-- **From `llm_provider`**: trait `LlmProvider`; `OpenRouterProvider` + `OpenRouterProviderConfig`; `RecordingProvider` + `Recording` (test fixture replay); error type `LlmProviderError`; request/response DTOs `LlmRequest` / `LlmResponse` / `LlmPurpose`; `CachingModel`; prompt builders `build_leaf_summary_prompt`, `build_inferred_calls_prompt`, with stable IDs `LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1"` and `INFERRED_CALLS_PROMPT_VERSION = "inferred-calls-v1"`.
-- **From `plugin`**: `PluginHost`, `Manifest` + `parse_manifest`, `AcceptedEntity` / `AcceptedEdge` / `AnalyzeFileOutcome` / `AnalyzeFileStats`, `EdgeConfidence`, `UnresolvedCallSite`, `HostError` + `HostFinding`, `JailError`, `CapExceeded`, `DiscoveredPlugin` + `DiscoveryError` + `discover()`, `CrashLoopBreaker` + `CrashLoopState`, and the finding-ID constants (`FINDING_DISABLED_CRASH_LOOP` re-exported at root, with sibling `FINDING_*` constants reachable through `clarion_core::plugin::*`).
-
-Implementation types deliberately *not* re-exported at the root but still reachable via fully-qualified paths: transport (`Frame`, `read_frame`, `write_frame`, `TransportError`), protocol envelopes (`RequestEnvelope`, `ResponseEnvelope`, `AnalyzeFileParams`, etc.), prlimit helpers, raw entity/edge structs. `make_notification` / `make_request` are `pub(crate)` — `mod.rs:38-42` explains they panic on serde failure and external callers should build envelopes directly.
-
-**Internal structure:**
-
-Top-level modules (`crates/clarion-core/src/`):
-
-- `entity_id.rs` (610 LOC) — `EntityId` newtype + `entity_id()` constructor + `EntityIdError`. Includes the cross-language parity test against `fixtures/entity_id.json` (ADR-003, L2 lock-in).
-- `llm_provider.rs` (948 LOC) — single-file LLM abstraction. See breakdown below.
-- `plugin/` — supervisor + protocol + safety primitives. Submodule roles documented inline at `plugin/mod.rs:1-12`:
-  - `manifest.rs` (1508 LOC) — `Manifest`, `PluginMeta`, `Capabilities`, `CapabilitiesRuntime`, `PyrightRuntime`, `Ontology`, `parse_manifest()`, kind-grammar + rule-ID-prefix validators (ADR-021/ADR-022, L5).
-  - `protocol.rs` (846 LOC) — JSON-RPC 2.0 typed envelopes; `AnalyzeFileParams/Result`, `AnalyzeFileStats`, `UnresolvedCallSite`, `EdgeConfidence`, `InitializeParams/Result`, `Shutdown`, `Exit`, `ProtocolError`.
-  - `transport.rs` (568 LOC) — `Frame`, `read_frame`/`write_frame`, Content-Length framing with `MAX_HEADER_LINE_BYTES = 8 KiB`; surfaces oversize via `TransportError`.
-  - `jail.rs` (253 LOC) — `jail()` / `jail_to_string()` canonicalises and asserts containment under project root; `JailError::{EscapedRoot, NonUtf8Path, Io}`.
-  - `limits.rs` (552 LOC) — `ContentLengthCeiling`, `EntityCountCap`, `PathEscapeBreaker`, `BreakerState`, the finding-ID constants for cap violations, and the Unix `apply_prlimit_as` / `apply_prlimit_nofile_nproc` (no-op stubs on non-Unix). `DEFAULT_MAX_RSS_MIB = 2048` (ADR-021 §2b ceiling).
-  - `breaker.rs` (360 LOC) — `CrashLoopBreaker`, `CrashLoopState`, `FINDING_DISABLED_CRASH_LOOP` (ADR-002 §UQ-WP2-10).
-  - `discovery.rs` (637 LOC) — `DiscoveredPlugin`, `DiscoveryError`, `discover()` (Linux only — non-Unix returns empty), `discover_on_path()`, scans `$PATH` for `clarion-plugin-*` executables and pairs them with a sibling `share/clarion/plugins/<name>/plugin.toml` (cap 64 KiB).
-  - `host.rs` (3126 LOC) — see below.
-  - `mock.rs` (897 LOC, `#[cfg(test)] pub(crate)`) — in-process mock plugin; reachable only from unit tests in this crate.
-
-### Internal organisation of `plugin/host.rs` (3126 LOC)
-
-Despite the line count, the file is **not a god-file** — it is structurally one struct (`PluginHost<R, W>`) with two layers of constructors, an analyse-file pipeline, and a long unit-test suite. Concretely:
-
-- **Lines 1–155: Module-level constants and finding-ID strings** (`FINDING_*` for entity/edge ontology violations, plus byte caps `MAX_ENTITY_FIELD_BYTES = 4 KiB`, `MAX_ENTITY_EXTRA_BYTES = 64 KiB`, `MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512`).
-- **Lines 157–345: Pure validators / decoders** (`effective_max_nproc`, `oversize_edge_field`, `oversize_field`, `invalid_unresolved_call_site_reason`).
-- **Lines 346–438: Public DTOs** — `RawEntity`, `RawEdge`, `RawSource`, `AcceptedEntity`, `AcceptedEdge`, `AnalyzeFileOutcome`, `HostError` (with 17 variants covering Spawn, Handshake, Protocol, EntityCapExceeded, PathEscapeBreakerTripped, OomKilled, Io, etc.).
-- **Lines 450–637: `HostFinding` + ~14 named constructors** (`undeclared_kind`, `entity_id_mismatch`, `path_escape`, `disabled_path_escape`, `entity_cap_exceeded_finding`, `unsupported_capability`, `non_utf8_path`, `malformed_entity`, `malformed_edge`, `undeclared_edge_kind`, `edge_field_oversize`, `malformed_unresolved_call_site`, `entity_field_oversize`, `oom_killed`). One constructor per finding type — the "constructor wall" inflates line count but is mechanical.
-- **Lines 639–710: `PluginHost<R, W>` struct definition + `drain_stderr_into_ring`** — generic over reader/writer so subprocess and in-process mock share one impl; `stderr_tail` is a 64 KiB ring buffer.
-- **Lines 712–882: Subprocess constructor `PluginHost::spawn`** specialised to `BufReader<ChildStdout>` / `BufWriter<ChildStdin>`. This is the heaviest single function — it (1) validates manifest `executable` is a bare basename matching the discovered binary path (anti-redirect defence at host:756–780), (2) applies `RLIMIT_AS` + `nofile` + `nproc` via `pre_exec`, (3) spawns a detached stderr-drain thread, (4) reaps the child on handshake failure (host:864–880 — `Child::Drop` does *not* reap, so failure paths must explicitly wait).
-- **Lines 883–957: `PluginHost::connect` + `new_inner` + accessors** (`stderr_tail`, `ontology_version`).
-- **Lines 959–1028: `handshake()`** — the four documented steps: send `initialize`, validate response id, run `manifest.validate_for_v0_1()`, send `initialized`. On manifest failure the host is best-effort-shut-down without sending `initialized`.
-- **Lines 1031–1198: `analyze_file()`** — the per-file orchestration pipeline. Reads as a numbered validator pipeline:
-  - `0.` field-size cap → oversize finding, drop (host:1103);
-  - `1.` ontology declared-kind check (host:1109);
-  - `2.` entity-id identity check (host:1116);
-  - `3.` path-jail check + path-escape breaker tick → kill-path on `Tripped` (host:1135);
-  - `4.` entity-cap check → kill-path on exceed (host:1166).
-- **Lines 1200–1299: `process_edges()`** — same drop-on-violation posture, no kill paths (edges don't participate in breakers).
-- **Lines 1300–1450: `process_stats`, `shutdown`, `take_findings`, `next_id`, `do_shutdown`, `read_response_matching`** (drain-until-match for stale frames at host:1398; idempotent shutdown via `terminated` flag at host:657).
-- **Lines 1452–end (≈1700 LOC of tests)**: 30+ `#[cfg(test)]` named scenarios `t2_…` through `t9_…` plus B.3/B.4*/B.5* regressions. Tests dominate the line count; *production code in `host.rs` is ~1450 LOC*.
-
-The file is **coherent**: one supervisor type with one validator pipeline. The internal pressure to refactor is mild — splitting findings into a sibling module would shave ~200 LOC, but the drop-on-violation pipeline reads top-to-bottom and benefits from staying co-located.
-
-### Internal organisation of `llm_provider.rs` (948 LOC)
-
-Single-file LLM abstraction, organised top-to-bottom (no submodule because there is no `llm_provider/` directory):
-
-- **Lines 10–11: Stable prompt-ID constants** (`LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1"`, `INFERRED_CALLS_PROMPT_VERSION = "inferred-calls-v1"`). These form two of the five components of the ADR-007 cache key; the other three (`entity_id`, `content_hash`, `model_tier`, `guidance_fingerprint`) are assembled in `clarion-storage::cache::SummaryCacheKey`. **The 5-tuple is *not* materialised inside this file** — the provider is dispatch-only; cache keying happens in `clarion-storage` and `clarion-mcp`.
-- **Lines 13–37: Request / response / purpose DTOs** (`LlmRequest`, `LlmResponse`, `LlmPurpose::{Summary, InferredEdges}`).
-- **Lines 38–82: Error taxonomy** — `LlmProviderError` with six variants; `retryable()` returns the inner retryable flag for `Http`/`Provider`/`InvalidResponse`, false for `MissingRecording`/`LiveProviderNotAllowed`/`MissingApiKey`.
-- **Lines 84–90: The `LlmProvider` trait** — five required methods: `name`, `invoke`, `estimate_tokens`, `tier_to_model`, `caching_model`. Trait is `Send + Sync` so providers can be shared across MCP request handlers behind an `Arc`.
-- **Lines 92–151: `RecordingProvider`** — test-mode provider that replays exact-shape `LlmRequest` matches from a fixed `Vec<Recording>`. Tracks invocations in a `Mutex<Vec<LlmRequest>>` for assertion. Returns `MissingRecording` (non-retryable) on shape drift.
-- **Lines 153–295: `OpenRouterProvider`** — the live provider.
-  - Config gate at `from_config` (lines 173–187): requires both `allow_live_provider == true` AND a non-empty `api_key`; either failure yields `LiveProviderNotAllowed` / `MissingApiKey` (both non-retryable).
-  - `invoke()` (lines 202–279): blocking `reqwest` POST to `{endpoint}/chat/completions`, 60s timeout, `Authorization: Bearer`, `HTTP-Referer`, `X-OpenRouter-Title` headers. Payload includes `"temperature": 0`, `"provider": {"require_parameters": true}`, and `response_format` from `response_format_for_purpose()`.
-  - **The strict-JSON path** (the open question from §8) lives at `response_format_for_purpose` (lines 297–370): two JSON-Schema objects, both with `"strict": true` and `"additionalProperties": false`. `Summary` enforces `{purpose, behavior, relationships, risks}`; `InferredEdges` enforces `edges: [{site_key, target_id, confidence, rationale}]`. This is the B.8 GREEN-rerun fix from commit `ab6b1dd` — without `"strict": true` OpenRouter providers silently produced free-form text.
-  - Error unwrap chain: the response body is first parsed as `OpenRouterErrorEnvelope` (line 250) — even on HTTP 200, choices can carry per-call provider errors at `OpenRouterChatResponse::output_text` (line 379), which surfaces `LlmProviderError::Provider`.
-- **Lines 297–500: HTTP plumbing** — response struct definitions (`OpenRouterChatResponse`, `OpenRouterChoice`, `OpenRouterMessage`, `OpenRouterUsage`, `OpenRouterErrorEnvelope`, `OpenRouterErrorBody`), `provider_error_from_body`, `retryable_status` (true for 408 / 429 / ≥500), `retry_after_seconds` (header parse), `estimate_text_tokens` (chars/4 heuristic).
-- **Lines 502–561: Prompt builders** — `LeafSummaryPromptInput` / `InferredCallsPromptInput` DTOs and the two `build_*_prompt` functions emitting `PromptTemplate { id, body }`. Body is a hand-written `format!` template; no Tera/Handlebars.
-- **Lines 563–end: Unit tests**, including a TCP-listener-based in-process OpenRouter stub at `openrouter_provider_invokes_chat_completions_and_extracts_usage_tokens`.
-
-**Nothing is cached inside `llm_provider.rs`.** The provider is a stateless dispatcher; caching is `clarion-storage::cache` (per discovery §4, Subsystem B) and lookup is performed by callers in `clarion-mcp::lib.rs` and the analyze-file inferred-edges path. Caching is *lazy and lookup-driven*: callers compute `SummaryCacheKey` from the 5-tuple, hit the cache, and only call `LlmProvider::invoke` on miss — then write the response back keyed on the same tuple.
-
-**Key types & traits:**
-
-| Type | Where | Why callers touch it |
-|---|---|---|
-| `EntityId`, `entity_id()` | `entity_id.rs` | Every accepted entity is identified by this; cross-language parity proof. |
-| `LlmProvider` (trait) | `llm_provider.rs:84` | MCP and analyze layers receive `Arc<dyn LlmProvider>` for dispatch. |
-| `OpenRouterProvider`, `RecordingProvider` | `llm_provider.rs:164`, `:99` | Provider construction in `clarion-cli::serve.rs`. |
-| `PluginHost<R, W>` | `host.rs:639` | The per-file supervisor; `spawn` for production, `connect` for in-process tests. |
-| `AcceptedEntity`, `AcceptedEdge`, `AnalyzeFileOutcome` | `host.rs:346–398` | Hand-off shapes from host → analyse orchestrator → writer-actor. |
-| `Manifest` + `parse_manifest` | `manifest.rs:115`, `:281` | `clarion-cli::analyze` reads `plugin.toml` through this; `PluginHost` consumes it. |
-| `CrashLoopBreaker` | `breaker.rs:43` | `clarion-cli::analyze` ticks this per plugin-spawn failure. |
-| `discover()` / `DiscoveredPlugin` | `discovery.rs:133`, `:47` | Plugin discovery on `$PATH`. |
-| `HostError` / `HostFinding` | `host.rs:400`, `:450` | Error matching + finding emission for operator diagnostics + Filigree forwarding. |
-| `LlmProviderError` | `llm_provider.rs:44` | Caller uses `.retryable()` to drive WP6 backoff. |
-
-**Dependencies (workspace + outbound):**
-
-- **Inbound** (per `grep clarion-core` against each Cargo.toml):
-  - `clarion-storage/Cargo.toml:13`
-  - `clarion-mcp/Cargo.toml:13`
-  - `clarion-cli/Cargo.toml:20`
-
-  *Note*: `clarion-plugin-fixture` does **not** depend on `clarion-core` — the fixture binary speaks the wire protocol directly without sharing types. This is deliberate (the discovery flagged the fixture is consumed only via subprocess in `wp2_e2e`).
-
-- **Outbound** (`Cargo.toml`):
-  - `reqwest` (workspace: `rustls-tls-native-roots`, blocking + JSON) — only `llm_provider.rs`.
-  - `serde` + `serde_json` + `toml` — DTO + manifest parsing.
-  - `thiserror` — every error enum here.
-  - `tracing` — host stderr-drain failures + best-effort-shutdown diagnostics.
-  - `nix` (workspace, `resource` feature only) — `apply_prlimit_*` in `limits.rs`. The single `unsafe` allowance in the workspace lives here (`pre_exec` + `setrlimit`); workspace lint floor is `unsafe_code = "deny"` (downgraded from `forbid` per documented exception in workspace `Cargo.toml`).
-  - `tempfile` (dev-dep) — tests only.
-
-- **Notably absent**: no `tokio` dependency. The plugin host is fully synchronous (`BufRead + Write` generic bounds, blocking `reqwest`). Async is introduced one layer up in `clarion-storage::writer` (`tokio::task`) and `clarion-mcp::lib.rs`.
-
-**Patterns observed:**
-
-- **Generic reader/writer typestate-lite** — `PluginHost<R, W>` is generic; `spawn` returns a host parameterised on `BufReader<ChildStdout>` / `BufWriter<ChildStdin>`, while `connect` accepts any `BufRead + Write` pair so the in-process `mock.rs` and the e2e tests share one validator pipeline.
-- **Drop-on-violation pipeline with discrete kill-paths** — `analyze_file` is a numbered five-step validator; steps 0–2 only emit findings and drop the offending record; steps 3–4 escalate to plugin termination if a breaker trips. The kill-paths route through a single `do_shutdown` (host:1352) that handles the idempotent-shutdown flag.
-- **Newtype-with-constructor for safety-critical IDs** — `EntityId(String)` is private-field; the only constructors live in `entity_id.rs` and validate the grammar before producing the newtype. `FromStr` rebuilds via the same constructor.
-- **Trait-object provider dispatch** — `Arc<dyn LlmProvider>` consumed by MCP and analyze; live vs recording vs disabled selected at config time (`clarion-cli::serve.rs`).
-- **Finding-ID constants as first-class API** — every `FINDING_*` is a `pub const &str` exported at module root so callers (and tests) can `assert_eq!` on the stable ID rather than match on free-form messages. The ID grammar (`CLA-INFRA-*`) is asserted at manifest-parse time (`manifest.rs:414`).
-- **Pure-function validators** — `oversize_field`, `oversize_edge_field`, `invalid_unresolved_call_site_reason`, `validate_kind_string`, `validate_rule_id_prefix_grammar` are all stateless and unit-tested in isolation.
-
-**Concerns / risks:**
-
-- **`host.rs` size** (3126 LOC including ~1700 LOC of tests). Production code is ~1450 LOC and is coherent, but the file is the codebase's largest. A future refactor could move the 14 `HostFinding` constructors and the `FINDING_*` constants to a sibling `host_findings.rs` for ~200 LOC saved without altering semantics.
-- **`manifest.rs` size** (1508 LOC) — not deep-read in this pass; the public type surface is small (one `Manifest` + five field-structs + one error enum + parser + two grammar validators). Likely test-dominated like `host.rs`, but worth a separate confirm pass.
-- **Subprocess constructor is Linux-coupled** — `spawn` at `host.rs:739` uses `pre_exec` + `RLIMIT_AS`/`RLIMIT_NOFILE`/`RLIMIT_NPROC`. `limits.rs:330–342` provides no-op stubs for non-Unix targets, but `discover()` at `discovery.rs:139` is also `#[cfg(unix)]` and returns empty on Windows. v0.1 is Linux-only by intent (per Sprint-1 sign-off), but the cross-platform doors are stubs, not implementations.
-- **Reqwest blocking inside a `Send + Sync` trait method** — `LlmProvider::invoke` is sync. Callers from async contexts (`clarion-mcp`) must `spawn_blocking`. Not verified in this pass which side actually does the offloading; if callers run `invoke` on the runtime thread, MCP tool handlers can starve. This belongs as a follow-up question for the `clarion-mcp` catalog pass.
-- **OpenRouter strict-JSON regression risk** — the `"strict": true` JSON-Schema gates were added in commit `ab6b1dd` for B.8 GREEN; the path lives entirely in `response_format_for_purpose` (`llm_provider.rs:297`) and is asserted by a test that pattern-matches the serialised request body. A schema change anywhere in the prompt-output contract must update both the prompt template (`build_*_prompt`) and the strict-JSON schema in lockstep — there is no cross-check between them.
-- **`unsafe` allowance lives here** — `pre_exec` + `setrlimit` is the workspace's sole `unsafe` block (documented in workspace `Cargo.toml`). Any new unsafe in `clarion-core` should require an ADR amendment.
-- **No `tokio` use, but exported types flow into async runtimes** — `AcceptedEntity` / `AcceptedEdge` cross the async boundary via `clarion-storage::WriterCmd`. The DTOs are `Clone + Send` (verified through usage patterns) but this is not enforced by trait bounds at the public boundary; a future field that is not `Send` would silently break downstream.
-- **Test-only `mock.rs` (897 LOC) lives inside `src/` under `#[cfg(test)]`** rather than in `tests/`. Pro: integration tests in `tests/wp2_e2e.rs` cannot link against it — keeping mock scaffolding off the public surface is exactly the goal (`mock.rs` is `pub(crate)`). Con: 897 LOC of test scaffolding inflates `clarion-core` source counts; deferred items include `clarion-adeff0916d` (fixture-binary self-build) which may consolidate this.
-
-**Confidence:** High — read `lib.rs` and `plugin/mod.rs` in full; read `host.rs` structural skeleton + `PluginHost` definition + `spawn` constructor + full `analyze_file` body; read `llm_provider.rs` in full through line 561 (the production code; tests sampled); cross-verified inbound deps via `grep clarion-core` against each crate's `Cargo.toml`. Two claims are Medium-confidence and called out above: (a) `manifest.rs` internal proportions not directly verified beyond signature scan; (b) whether MCP wraps `LlmProvider::invoke` in `spawn_blocking` is out-of-scope for this pass and listed as a follow-up.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-mcp.md b/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-mcp.md
deleted file mode 100644
index e3f78904..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-mcp.md
+++ /dev/null
@@ -1,103 +0,0 @@
-## clarion-mcp
-
-**Location:** `crates/clarion-mcp/`
-
-**Responsibility:** Speaks MCP protocol revision `2025-11-25` over stdio; serves seven storage-backed read tools (`entity_at`, `find_entity`, `callers_of`, `execution_paths_from`, `summary`, `issues_for`, `neighborhood`) to consult-mode LLM agents, with on-demand LLM dispatch for leaf-scope summaries and inferred call edges, and optional Filigree enrichment for issue attachment.
-
-**Key Components:**
-
-- `src/lib.rs` (2620 LOC) — single-file crate root. Internal organisation, top-to-bottom:
-  - **Protocol surface** (lines 36–166): `MCP_PROTOCOL_VERSION = "2025-11-25"` constant (line 36), `ToolDefinition` struct (40–45), `list_tools()` returning seven hardcoded `ToolDefinition`s with inline JSON-Schema (48–120), schema helpers `confidence_schema` / `id_schema` / `id_confidence_schema` (122–151), stateless `handle_json_rpc` router (154–166) wired to `initialize` / `tools/list` / `tools/call`.
-  - **`ServerState`** (168–1252): the central handler. Fields (168–178): `project_root: PathBuf`, `readers: ReaderPool`, `execution_edge_cap: usize` (default 500), `summary_llm: Option<SummaryLlmState>`, `clock: Arc<dyn Fn() -> String + Send + Sync>`, `budget: Arc<Mutex<BudgetLedger>>`, `inferred_inflight: Arc<AsyncMutex<HashMap<InferredEdgeCacheKey, broadcast::Sender<InferredDispatchOutcome>>>>` (in-flight dispatch coalescing), `filigree_client: Option<Arc<dyn FiligreeLookup>>`. Builder methods (180–226): `new`, `with_edge_cap`, `with_summary_llm`, `with_clock`, `with_filigree_client`.
-  - **Per-tool dispatch** (228–294): instance `handle_json_rpc` + `handle_tool_call` route by name to seven `tool_*` async methods.
-  - **Per-tool handlers** (296–717): `tool_entity_at` (296–319), `tool_find_entity` (321–354), `tool_callers_of` (356–391), `tool_execution_paths_from` (393–434) + `inferred_execution_paths` (436–520), `tool_neighborhood` (522–581), `tool_issues_for` (583–671), `tool_summary` (673–717).
-  - **LLM inferred-edges pipeline** (719–995): `ensure_inferred_for_target` / `ensure_inferred_for_caller` (719–796) — entry points called by `callers_of`/`neighborhood`/`execution_paths_from` when `confidence == Inferred`; `read_inferred_inputs` (798–833) builds an `InferredEdgeCacheKey` from caller content-hash + model_id + prompt_version (ADR-007); `materialize_cached_inferred` (835–863) on cache hit; `coalesced_inferred_dispatch` (865–908) deduplicates concurrent dispatches via a `broadcast` channel with a 60-second timeout; `perform_inferred_dispatch` (910–995) builds the prompt via `clarion_core::build_inferred_calls_prompt`, reserves budget, invokes the provider on a `spawn_blocking` task, then sends `WriterCmd::InsertInferredEdges` to the writer-actor.
-  - **LLM summary pipeline** (997–1155): `read_summary_inputs` (997–1035) keys against `SummaryCacheKey { entity_id, content_hash, prompt_template_id = LEAF_SUMMARY_PROMPT_TEMPLATE_ID, model_tier, guidance_fingerprint = "guidance-empty" }` — five-tuple cache key matching ADR-007; `cached_summary_envelope` (1037–1060) bumps `last_accessed_at` via `WriterCmd::TouchSummaryCache`; `refresh_summary` (1062–1155) on miss invokes provider, then `WriterCmd::UpsertSummaryCache`. ADR-030 leaf-scope is encoded by the single `LEAF_SUMMARY_PROMPT_TEMPLATE_ID` template and the `summary` tool description (line 98).
-  - **Writer-actor helper + budget** (1157–1251): `send_writer` (1157–1171) — oneshot ack roundtrip pattern; `BudgetLedger` accounting with `reserve_budget` / `BudgetReservation::commit` / `Drop` rollback (1180–1316); `summary_model_id` / `inferred_edges_model_id` / `max_inferred_edges_per_caller` (1221–1251) honour `LlmProvider::tier_to_model("summary"|"inferred_edges")`.
-  - **Plain types** (1266–1607): `SummaryLlmState`, `BudgetLedger`, `SummaryRead` enum, `SummaryReady`, `IssuesForRead`, `IssuesForAccumulator` (drift-classifier matching `content_hash_at_attach` against current `entities.content_hash`, lines 1379–1411, with 100-issue cap), `InferenceLlmState`, `InferredRead`, `InferredDispatchStats` (aggregated stats_delta), `InferredDispatchFailure`, `InferredDispatchOutcome`, `InferredCallsResponse` / `InferredCallsResponseEdge`.
-  - **Transport loop** (1609–1686): `McpError` enum, `handle_frame` / `handle_frame_with_state`, `serve_stdio` / `serve_stdio_with_state` / `serve_stdio_with_state_on_runtime` — Content-Length frame loop using `clarion_core::plugin::{read_frame, write_frame, ContentLengthCeiling::DEFAULT, Frame, TransportError}`; treats `UnexpectedEof` as clean shutdown.
-  - **Stateless `handle_tool_call`** (1701–1736): a stub kept for the stateless `handle_json_rpc` router; emits `tool-unimplemented` envelopes for every tool — only reachable from the stateless entry point used by tests and `handle_frame`.
-  - **Envelope/parsing helpers** (1738–2419): `ParamError`, `PathTraversal` (recursive walker for `execution_paths_from`, 1755–1802), `ReferenceDirection`, `required_str` / `required_i64` / `optional_usize` / `optional_bool` / `optional_confidence` argument coercers, envelope builders (`success_envelope`, `tool_error_envelope`, `tool_error_envelope_with_diagnostics`, `success_envelope_with_truncation_and_stats`), `entity_json`, `source_excerpt` + `line_range_excerpt` + `truncate_excerpt`, `inferred_records_from_result` (parses LLM JSON into `InferredCallEdgeRecord`, 2216–2266), `summary_cache_expired` + `timestamp_day_index` + `days_from_civil` (Howard Hinnant civil-from-days algorithm for the 180-day TTL), `caller_json` / `callee_json` / `path_json` / `reference_neighbors`.
-  - **Unit tests** (2421–2620): 8 tests covering tool-list exact docstrings, initialize result, tools/list wrapping, unknown method/tool/params, frame dispatch round-trip, and multi-frame serve-stdio.
-- `src/config.rs` (352 LOC) — `McpConfig` (YAML via `serde_norway`) with `llm` and `integrations.filigree` sections; `LlmConfig` (provider, `enabled`, `allow_live_provider`, `session_token_ceiling: u64` default 1_000_000, `model_id` default `"anthropic/claude-sonnet-4.6"`, `cache_max_age_days` default 180, `max_inferred_edges_per_caller` default 8); `LlmProviderKind::{OpenRouter, Anthropic, Recording}` (with Anthropic actively rejected — `ConfigError::DeprecatedProvider` with code `CLA-CONFIG-DEPRECATED-PROVIDER`, lines 34–43, 169–171); accepts `llm_policy` alias for the `llm` block (line 10, test at 270–284); `select_provider_with_env` (156–191) returns `ProviderSelection::{Disabled, Recording, OpenRouter{api_key_env}}` — opt-in to live OpenRouter is gated by `allow_live_provider` *or* the `CLARION_LLM_LIVE=1` env (173); presence of an API key alone is not enough (test at 287–303); `FiligreeConfig` (127–147) — `enabled` default false, `base_url` default `http://127.0.0.1:8766`, `actor` default `clarion-mcp`, `token_env` default `FILIGREE_API_TOKEN`, `timeout_seconds` default 5. Five unit tests.
-- `src/filigree.rs` (238 LOC) — `EntityAssociationsResponse` / `EntityAssociation` (Filigree ADR-029 contract); `FiligreeLookup` trait (45–50); `FiligreeHttpClient` (52–111) — blocking `reqwest::blocking::Client` with `timeout_seconds.max(1)`, returns `Ok(None)` when `enabled=false` (68–70); `associations_for` GETs `{base_url}/api/entity-associations?entity_id={encoded}` with `x-filigree-actor` and optional `Bearer` token; manual percent-encoding restricted to unreserved chars (127–142); three unit tests including a real TCP-server roundtrip (194–237).
-- `tests/storage_tools.rs` (1710 LOC) — heavyweight integration tests; 11+ `#[tokio::test]` cases exercising each tool against a seeded SQLite database with `RecordingProvider` LLM substitutes and a stub `FiligreeLookup` (`association` builder at line 573).
-
-**Dependencies:**
-
-- Inbound: `clarion-cli` (only — `crates/clarion-cli/src/serve.rs` is the sole consumer of the public API: `McpConfig::from_path`, `select_provider_with_env`, `FiligreeHttpClient::from_config`, `ServerState::new` + builders, `serve_stdio_with_state_on_runtime`).
-- Outbound:
-  - `clarion-core` — `EdgeConfidence`, `INFERRED_CALLS_PROMPT_VERSION`, `InferredCallsPromptInput`, `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `LeafSummaryPromptInput`, `LlmProvider`, `LlmProviderError`, `LlmPurpose`, `LlmRequest`, `LlmResponse`, `build_inferred_calls_prompt`, `build_leaf_summary_prompt`; transport `plugin::{ContentLengthCeiling, Frame, TransportError, read_frame, write_frame}` (`lib.rs:11–21`).
-  - `clarion-storage` — 20 symbols (`lib.rs:22–30`): types `CallEdgeMatch`, `EntityRow`, `InferredCallEdgeRecord`, `InferredEdgeCacheEntry`, `InferredEdgeCacheKey`, `InferredEdgeWriteStats`, `ReaderPool`, `StorageError`, `SummaryCacheEntry`, `SummaryCacheKey`, `UnresolvedCallSiteRow`, `WriterCmd`; functions `call_edges_from`, `call_edges_targeting`, `candidate_entities_for_unresolved_sites`, `child_entity_ids`, `contained_entity_ids`, `entity_at_line`, `entity_by_id`, `find_entities`, `inferred_edge_cache_key_id`, `inferred_edge_cache_lookup`, `normalize_source_path`, `summary_cache_lookup`, `unresolved_call_sites_for_caller`, `unresolved_callers_for_target`.
-  - External crates: `tokio` (mpsc/oneshot/broadcast, current-thread runtime, `spawn_blocking`), `serde` / `serde_json`, `serde_norway` (YAML), `reqwest::blocking` (Filigree HTTP), `rusqlite` (one direct `prepare` for `reference_neighbors` at line 2378 — the only raw SQL in this crate; everything else routes through `clarion-storage` helpers), `thiserror`.
-
-**Patterns Observed:**
-
-- **Read-side dispatch is genuinely thin.** Six of the seven tools (`entity_at`, `find_entity`, `callers_of` non-inferred, `execution_paths_from` non-inferred, `neighborhood` non-inferred, `issues_for`) call a `clarion-storage` helper through `ReaderPool::with_reader`, then envelope the result. Transformation done in `clarion-mcp` is narrow: building tool envelopes (`ok` / `result` / `error` / `diagnostics` / `truncated` / `truncation_reason` / `stats_delta`), shaping `entity_json` / `caller_json` / `callee_json` / `path_json` projections, and the `IssuesForAccumulator` drift classifier. The one substantive in-crate transform is `inferred_records_from_result` (2216–2266) which parses LLM JSON into `InferredCallEdgeRecord` and joins it back against the unresolved-site rows by `site_key`.
-- **LLM dispatch lives in this crate, not in `clarion-core`.** `clarion-core` provides prompt templates, the `LlmProvider` trait, and request/response types. The MCP layer owns: cache lookup (`summary_cache_lookup`, `inferred_edge_cache_lookup`), cache-staleness checks (`stale_semantic`, `summary_cache_expired`, ADR-007 five-tuple key in `read_summary_inputs:1010–1016`), the budget ledger (`BudgetReservation` with RAII rollback on drop), the in-flight dispatch coalescer (`inferred_inflight` keyed by `InferredEdgeCacheKey`, 60s timeout), prompt construction, provider invocation (`spawn_blocking` to bridge to the sync provider trait), and the writeback via `WriterCmd::{UpsertSummaryCache, TouchSummaryCache, InsertInferredEdges}`.
-- **Filigree integration is genuinely enrich-only.** Three independent skip paths route to `issues_unavailable` (lines 589–594, 619–628), which returns `ok=true` with `available=false` and a `reason` enum (`filigree-disabled` / `filigree-unreachable` / `filigree-client-error` / `entity-not-found`). The other six tools have no Filigree dependency. `FiligreeHttpClient::from_config` returns `Ok(None)` when disabled (filigree.rs:68–70) — disabled is the default. No code path makes a Filigree response required for the tool to succeed; this matches Loom federation §3 (`docs/suite/loom.md`).
-- **Confidence-tier opt-in (ADR-028).** `optional_confidence` (1861–1872) defaults to `Resolved`. `inferred` is the only tier that triggers LLM dispatch (via `ensure_inferred_for_target` / `ensure_inferred_for_caller`). `ambiguous` is read-only over existing static-edge rows.
-- **Writer-actor handoff.** All mutating storage operations go through `mpsc::Sender<WriterCmd>` + a `oneshot::Sender<Result<T, StorageError>>` ack (`send_writer`, 1157–1171). Translates `WriterGone` / `WriterNoResponse` storage errors into retryable tool envelopes. ADR-011 compliance.
-- **Stateful and stateless entry points co-exist.** The stateless `handle_json_rpc` (line 154) + `handle_tool_call` (line 1701) pair always emits `tool-unimplemented` envelopes for every tool; the stateful `ServerState::handle_json_rpc` (line 228) is the real dispatcher. The stateless path remains usable for `initialize` / `tools/list` and is exercised by unit tests inside the file.
-- **Truncation contract** — every list-shaped success envelope can carry `truncation_reason: "edge-cap" | "issue-cap" | "entity-cap"`. `execution_paths_from` enforces `execution_edge_cap` (default 500); `issues_for` enforces a hardcoded 100-issue cap (line 631) and a 1000-contained-entity cap (`read_issues_for_entities:655`).
-- **Time normalisation as plain math.** No `chrono` / `time` dependency — `default_now_string` emits `unix:{seconds}`, `timestamp_day_index` accepts either `unix:N` or ISO `YYYY-MM-DD…` prefix, and `days_from_civil` is the Howard Hinnant algorithm inline (2306–2314).
-
-### Tool table
-
-| Tool | Required inputs | Optional inputs | Primary storage helper | LLM dispatch path |
-|------|------------------|------------------|-------------------------|--------------------|
-| `entity_at` | `file: string`, `line: int ≥ 1` | — | `entity_at_line` (after `normalize_source_path`) | No |
-| `find_entity` | `pattern: string` | `limit: 1..=100` (default 20), `cursor: string\|null` (numeric offset) | `find_entities` | No |
-| `callers_of` | `id: string` | `confidence: resolved\|ambiguous\|inferred` (default `resolved`) | `call_edges_targeting` + `entity_by_id` | Only when `confidence=inferred` → `ensure_inferred_for_target` |
-| `execution_paths_from` | `id: string` | `max_depth: 1..=8` (default 3), `confidence` (default `resolved`) | `call_edges_from` + `PathTraversal` (resolved/ambiguous) or `inferred_execution_paths` (inferred) | Only when `confidence=inferred` → bounded BFS of `ensure_inferred_for_caller` per node |
-| `summary` | `id: string` | — | `summary_cache_lookup` then `WriterCmd::TouchSummaryCache` / `UpsertSummaryCache` | **Yes** — leaf-scope (ADR-030), `LlmPurpose::Summary`, max_output_tokens 512 |
-| `issues_for` | `id: string` | `include_contained: bool` (default true) | `entity_by_id` + `contained_entity_ids` (cap 1000) | No — Filigree HTTP per entity via `spawn_blocking` |
-| `neighborhood` | `id: string` | `confidence` (default `resolved`) | `entity_by_id` + `call_edges_targeting` + `call_edges_from` + `child_entity_ids` + `reference_neighbors` | Only when `confidence=inferred` → both `ensure_inferred_for_target` *and* `ensure_inferred_for_caller` (lines 528–534) |
-
-### LLM cache-key dispatch table
-
-| Path | Cache key tuple (ADR-007) | Source line |
-|------|----------------------------|-------------|
-| Summary | `entity_id` + `content_hash` + `prompt_template_id = LEAF_SUMMARY_PROMPT_TEMPLATE_ID` + `model_tier` (from `LlmProvider::tier_to_model("summary")`) + `guidance_fingerprint = "guidance-empty"` | `lib.rs:1010–1016` |
-| Inferred edges | `caller_entity_id` + `caller_content_hash` + `model_id` (from `tier_to_model("inferred_edges")`) + `prompt_version = INFERRED_CALLS_PROMPT_VERSION` | `lib.rs:816–821` |
-
-On miss, both paths reserve via `BudgetLedger` (token-pessimistic, ceiling default 1_000_000 input+output combined), invoke the provider on `spawn_blocking`, commit actual tokens (or flip `blocked=true`), and on success write back via the writer-actor. Subsequent dispatches for the same key short-circuit through the in-flight coalescer (`coalesced_inferred_dispatch`, 865–908) which `broadcast::subscribe`s and waits up to 60 s.
-
-**Concerns:**
-
-- **`lib.rs` is 2620 LOC in one file.** Discovery question #1 — internal structure is *coherent* (clear bands: protocol surface → `ServerState` → per-tool handlers → LLM pipelines → transport loop → helpers), but the file is large enough to warrant subdivision on size grounds alone. The `IssuesForAccumulator`, the LLM inferred-edges pipeline (719–995), the LLM summary pipeline (997–1155), the budget ledger (1180–1316), and the envelope/projection helpers (1874–2400) are each plausible standalone modules. The current single-file layout is not a god-file in the architectural sense — each band has a single responsibility — but the size will degrade code-review velocity and grep ergonomics.
-- **Dead stateless `handle_tool_call` stub** (`lib.rs:1701–1736`): emits `tool-unimplemented` envelopes for every tool name. Reachable only via the stateless `handle_json_rpc` (154) and `handle_frame` (1621) paths. `handle_frame` is exercised by one unit test (2542–2560) and is exported from the crate, so any external consumer that wires the stateless path will get permanently-broken `tools/call` responses. Not a runtime defect inside the CLI (which uses `handle_frame_with_state`), but a footgun in the public API.
-- **`reference_neighbors` (lib.rs:2363–2400)** issues raw SQL against the `edges` table directly, bypassing the `clarion-storage` helper layer. It is the *only* place in this crate that does so. This creates a hidden coupling to the `edges` schema (`kind = 'references'`, `confidence`, `source_byte_start`, `source_byte_end`) outside the storage crate. If the schema changes, `clarion-storage` callers and tests will catch it but this function will not.
-- **`InferredCallsResponseEdge::confidence: Option<f64>` field is parsed but unused for envelope shape** (lib.rs:1601–1607, used in 2247–2255). The model's reported confidence is stored as a property in the inferred-edge row's `properties_json`, but the storage layer does not surface it back through `caller_json`/`callee_json` — the tool envelope only exposes `edge_confidence` (the tier: resolved/ambiguous/inferred). The model's per-edge confidence is therefore preserved on disk but not queryable; consumers needing the score must hand-parse `properties_json`.
-- **Coalesced-dispatch waiters get a generic stats delta when the leader fails.** `InferredDispatchOutcome::from_result` (1574–1595, used at 902–908) broadcasts a clonable outcome; non-leader waiters that receive a failure outcome surface it as their own (line 884–887). Acceptable, but the leader's diagnostics (e.g. `CLA-LLM-INVALID-JSON` usage block) are visible to the leader only; waiters see the failure code/message but lose the per-response diagnostics array. Minor observability gap.
-- **`source_excerpt` (lib.rs:2151)** uses `std::fs::read_to_string` on the *current on-disk file path* to build LLM prompt input. This is *not* the content hash that keyed the cache; the file may have changed between the time the entity was scanned and the time the tool runs. The cache key still uses the stored `content_hash`, so a stale read here produces a cache miss with a fresh-but-misaligned prompt. The `stale_semantic` flag covers structural drift (caller_count / fan_out) but not source-text drift. Documented as a known v0.1 trade-off in the surrounding code? — no comment found.
-- **`BudgetLedger::blocked` is sticky for the lifetime of the `ServerState`**: once any reservation overshoots, `blocked` flips to `true` (1196, 1296) and every subsequent LLM tool returns `token-ceiling-exceeded` until process restart. No reset path; no way to lift the ceiling without dropping the state. Matches a session-token semantic but is undocumented in the public API.
-- **`FiligreeConfig::actor` blank handling**: `FiligreeHttpClient::associations_for` only sets the `x-filigree-actor` header when the actor string is non-blank (filigree.rs:94–96); Filigree currently requires the header for some endpoints. Silent omission rather than rejection at config-load.
-- **No `Drop` cleanup for in-flight broadcast senders on leader cancellation.** If the leader task panics or is dropped *before* reaching the explicit `remove` at line 904, the `inferred_inflight` entry leaks until the next dispatch for the same key. `broadcast::Sender` itself is not a resource leak, but the map entry blocks subsequent dispatches from claiming leadership; subsequent callers will subscribe to a now-dead sender and time out at 60 s. Low-probability but present.
-
-### Confidence Assessment
-
-**Confidence:** High — Read 100% of `config.rs` (352 lines), 100% of `filigree.rs` (238 lines), 100% of the `lib.rs` declarations/dispatch (1–1700) and the helper/test bands (1700–2620). Sampled five handler bodies in full (`tool_entity_at`, `tool_find_entity`, `tool_callers_of`, `inferred_execution_paths`, `tool_issues_for`, `tool_summary`) and the LLM pipelines (`ensure_inferred_for_caller` through `perform_inferred_dispatch`). Cross-verified inbound dependency by reading `clarion-cli/src/serve.rs` (137 lines). Cross-verified outbound dependency claims against the `use` block at `lib.rs:11–34`. Cross-verified ADR alignment by quoting cache-key construction sites (5-tuple at 1010–1016, 4-tuple at 816–821) and ADR-028 default in `optional_confidence` (1864).
-
-### Risk Assessment
-
-- **Size-induced review burden** (lib.rs 2620 LOC) — Medium operational risk; not a correctness risk. The internal banding makes incremental refactors safe.
-- **Dead stateless `handle_tool_call` stub in public API surface** — Low surface but high blast radius for any external consumer. Single fix: either remove from public exports or make it forward to the same handlers as the stateful path.
-- **`reference_neighbors` raw SQL** — Schema-coupling risk; would not be caught by `clarion-storage` integration tests.
-- **`source_excerpt` reads live disk, not the hashed snapshot** — Correctness drift risk under concurrent file modification; affects prompt fidelity but not cache correctness.
-- **Sticky budget ledger** — Operational risk: process restart required after one ceiling breach. Acceptable for v0.1 / session semantics.
-- **Filigree enrich-only contract** — Verified clean. Discovery question #5 answered: no Filigree code path is load-bearing.
-
-### Information Gaps
-
-- The Sprint-2 e2e script `tests/e2e/sprint_2_mcp_surface.sh` was not read in this pass (out of scope per task framing); coverage of the seven tools end-to-end is documented as "presumed" in `01-discovery-findings.md:138`.
-- The integration tests at `tests/storage_tools.rs` (1710 LOC) were enumerated but not read in full; the `RecordingProvider` plumbing and the `state_for_filigree` stub were sampled to confirm they exist (lines 244–252).
-- ADR text for ADR-007/028/029/030 was not re-opened in this pass; alignment claims rely on the cache-key/confidence-tier code matching the documented intent paraphrased in the task brief.
-- The model's per-edge `confidence: Option<f64>` field is parsed from LLM output but not surfaced in tool responses — whether this is intentional (ADR-028 tiers are coarse-grained on purpose) or a documentation gap was not verified against the ADR.
-
-### Caveats
-
-- The "thin dispatch" characterisation is true for the six read-only tools but does not apply to the LLM-dispatch paths (`tool_summary` plus the `confidence=inferred` branches of `callers_of` / `execution_paths_from` / `neighborhood`), which carry substantive in-crate logic: cache-key construction (ADR-007), budget reservation, in-flight coalescing, prompt construction via `clarion-core` helpers, provider invocation on `spawn_blocking`, JSON-shape validation, and writeback via the writer-actor.
-- The LOC band offsets cited in the catalog were computed from the on-disk `lib.rs` and are stable against the working tree at the time of analysis; minor drift (the file grew by 171 lines during B.8 per `01-discovery-findings.md:323`) means line numbers in this section are post-B.8.
-- "MCP protocol revision `2025-11-25`" is sourced from the in-code constant (`lib.rs:36`); whether that matches the upstream MCP spec revision identifier was not independently verified.
-- The Filigree HTTP client uses `reqwest::blocking` despite living in an otherwise async crate — calls are wrapped in `tokio::task::spawn_blocking` at `lib.rs:613`. Not a defect, but worth flagging if the crate is ever migrated to an async Filigree client.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-storage.md b/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-storage.md
deleted file mode 100644
index 68bf215e..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/section-clarion-storage.md
+++ /dev/null
@@ -1,149 +0,0 @@
-## clarion-storage
-
-**Location:** `crates/clarion-storage/`
-
-**Responsibility:** Persists Clarion's entity/edge graph, run provenance, and LLM caches in a single SQLite database under `.clarion/clarion.db`. All mutations funnel through a single writer-actor task (sole `rusqlite::Connection`); all reads come from a `deadpool-sqlite` pool. The crate also owns the schema migration runner, the PRAGMA discipline, the edge-contract validator, and the typed query helpers consumed by `clarion-mcp` and `clarion-cli`.
-
-### Internal structure
-
-**Module roster** (`src/lib.rs:7–15`, all `pub mod`):
-
-| Module | LOC | Role |
-|---|---|---|
-| `writer.rs` | 817 | Writer-actor: spawn, command loop, edge-contract enforcement, per-N batch commits, parent/contains consistency check at `CommitRun` |
-| `query.rs` | 569 | Read-side helpers (graph navigation, FTS-or-LIKE search, unresolved call-site fan-out) |
-| `cache.rs` | 251 | `SummaryCacheKey` (5-tuple per ADR-007) + `InferredEdgeCacheKey` (4-tuple) and their upsert/lookup/touch helpers |
-| `commands.rs` | 183 | `WriterCmd` enum (9 variants) + POD records + `RunStatus` |
-| `schema.rs` | 118 | Embed-and-apply migration runner (`include_str!` of the single `.sql` file) |
-| `reader.rs` | 88 | `ReaderPool` wrapper around `deadpool-sqlite::Pool` |
-| `unresolved.rs` | 50 | Replace-by-caller bookkeeping for unresolved call sites |
-| `error.rs` | 48 | `StorageError` taxonomy (11 variants, `thiserror`) |
-| `pragma.rs` | 45 | WAL/synchronous=NORMAL/busy_timeout=5000/foreign_keys=ON discipline |
-| `lib.rs` | 35 | Curated `pub use` facade |
-
-**Schema (ER summary)** — single migration `migrations/0001_initial_schema.sql` (289 LOC). Eight base tables, one FTS5 virtual table, three triggers, one view, two generated columns:
-
-```
-                    ┌─────────────────────────────────────────────┐
-                    │  entities  (PK id TEXT)                     │
-                    │  + virtual cols scope_level / scope_rank    │
-                    │  + indexes on kind, plugin_id, parent_id,   │
-                    │    source_file_id, source_file_path,        │
-                    │    content_hash, last_seen_commit,          │
-                    │    scope_rank (partial), git_churn (partial)│
-                    └──┬──────────────────┬────────┬─────────────┘
-                       │self-ref          │FK FK   │FK
-            parent_id  │  source_file_id  │        │
-                       ▼                  ▼        ▼
-   ┌──────────────┐  ┌──────────────────────────────────────┐
-   │ entity_tags  │  │ edges  WITHOUT ROWID                 │
-   │ (entity_id,  │  │ PK (kind, from_id, to_id)            │
-   │  tag) PK     │  │ CHECK confidence IN                  │
-   │ ON DELETE    │  │   (resolved, ambiguous, inferred)    │
-   │ CASCADE      │  │ FKs: from_id, to_id, source_file_id  │
-   └──────────────┘  │   ALL ON DELETE CASCADE              │
-                    └──────────────────────────────────────┘
-                       ▲                  ▲
-                       │entity_id FK      │caller_entity_id FK
-   ┌─────────────────────┐  ┌────────────────────────────────┐
-   │ findings (PK id)    │  │ entity_unresolved_call_sites   │
-   │ CHECK kind ∈ 5      │  │ PK (caller_entity_id,          │
-   │ CHECK severity ∈ 5  │  │     caller_content_hash,       │
-   │ CHECK status ∈ 4    │  │     site_key)                  │
-   │ FK entity_id        │  └────────────────────────────────┘
-   └─────────────────────┘
-                       ▲caller_entity_id FK
-   ┌────────────────────────────┐    ┌──────────────────────────┐
-   │ inferred_edge_cache         │    │ summary_cache            │
-   │ PK (caller_entity_id,       │    │ PK 5-tuple (entity_id,   │
-   │     caller_content_hash,    │    │     content_hash,        │
-   │     model_id,               │    │     prompt_template_id,  │
-   │     prompt_version)         │    │     model_tier,          │
-   │ FK caller_entity_id         │    │     guidance_fingerprint)│
-   └────────────────────────────┘    │ CHECK stale_semantic∈(0,1)│
-                                     └──────────────────────────┘
-
-   ┌──────────────────────────┐   ┌────────────────────────────┐
-   │ runs (PK id)             │   │ schema_migrations          │
-   │ CHECK status ∈ (running, │   │ (version PK, name,         │
-   │   skipped_no_plugins,    │   │  applied_at)               │
-   │   completed, failed)     │   └────────────────────────────┘
-   └──────────────────────────┘
-
-   FTS5 virtual: entity_fts (entity_id UNINDEXED, name, short_name,
-     summary_text, content_text); kept in sync by triggers
-     entities_ai / entities_au / entities_ad.
-
-   View: guidance_sheets — projects entities WHERE kind='guidance'
-     with json_extract of `properties` + json_group_array of tags.
-```
-
-ADR-031 `CHECK` discipline (lines 89, 107–112, 124–125, 153, 200–201): closed core-owned vocabularies receive `CHECK` clauses (`edges.confidence`, `findings.{kind, severity, status}`, `summary_cache.stale_semantic`, `runs.status`). Plugin-extensible vocabularies deliberately omit `CHECK` per ADR-022 — `entities.kind` (`migrations/0001_initial_schema.sql:33–36`) and `edges.kind` (`migrations/0001_initial_schema.sql:77–81`); enforcement at those columns is the writer-actor (`writer.rs::enforce_edge_contract` for edges, manifest acceptance for entity kinds).
-
-**Writer-actor command set** (`commands.rs::WriterCmd`, 9 variants):
-
-| Variant | Lifecycle | Notes |
-|---|---|---|
-| `BeginRun` | analyze-time | `runs` INSERT with `status='running'`, opens `BEGIN` (`writer.rs:308–330`) |
-| `InsertEntity` | analyze-time | Single INSERT into `entities`; counts toward batch boundary (`writer.rs:332–390`) |
-| `InsertEdge` | analyze-time | Calls `enforce_edge_contract` (`writer.rs:411–472`) then `INSERT OR IGNORE`; dedupe increments `dropped_edges_total`, ambiguous accepts bump `ambiguous_edges_total` (`writer.rs:474–520`) |
-| `InsertInferredEdges` | query-time (MCP) | Upserts inferred-edge cache row, GCs stale inferred edges for the caller, inserts new ones; refuses to shadow static resolved/ambiguous calls (`writer.rs:522–599`) |
-| `UpsertSummaryCache` | query-time (MCP) | 5-tuple upsert on `summary_cache` (`cache.rs:48–85`) |
-| `TouchSummaryCache` | query-time (MCP) | `UPDATE summary_cache SET last_accessed_at` (`cache.rs:112–132`) |
-| `ReplaceUnresolvedCallSitesForCaller` | analyze-time | Delete-then-insert pattern; replaces all sites for one caller atomically inside the run transaction (`writer.rs:601–621`, `unresolved.rs:20–50`) |
-| `CommitRun` | analyze-time | Runs the B.3 parent/contains dual-encoding check **inside** the open transaction (`writer.rs:733–796`); on mismatch rolls back the run's writes and marks `runs.status='failed'` with `CLA-INFRA-PARENT-CONTAINS-MISMATCH` in `stats.failure_reason`; on success folds the `runs` UPDATE into the final COMMIT (`writer.rs:671–727`) |
-| `FailRun` | analyze-time | ROLLBACK + `UPDATE runs SET status='failed'` (`writer.rs:798–817`) |
-
-The actor multiplexes analyze-time and query-time mutations on the same connection. `query_time_write` (`writer.rs:647–669`) commits any open analyze-time batch, runs the MCP write, and reopens a `BEGIN` if a run is still active — so analyze-time and MCP traffic cannot deadlock or interleave on the same transaction. Batch cadence is `DEFAULT_BATCH_SIZE = 50` writes (`writer.rs:35`, `bump_writes_and_maybe_commit` at `writer.rs:628–645`); the `INSERT OR IGNORE` edge dedupe is workload-shape-invariant because UNIQUE conflicts still bump the batch counter.
-
-Channel-closed cleanup (`writer.rs:251–273`): if the `Writer` is dropped mid-run, the actor self-heals by issuing `ROLLBACK` and marking the surviving run row `failed` with `failure_reason="writer channel closed unexpectedly"`. This is the durability backstop for the supervisor in `clarion-cli::analyze`.
-
-**Edge contract** (`writer.rs::enforce_edge_contract`, line 411). Ontology is hard-coded as `STRUCTURAL_EDGE_KINDS = ["contains", "in_subsystem", "guides", "emits_finding"]` (`writer.rs:394`) and `ANCHORED_EDGE_KINDS = ["calls", "references", "imports", "decorates", "inherits_from"]` (`writer.rs:395–401`) — nine kinds total per ADR-026/028. Structural edges MUST have `confidence=resolved` and NULL `source_byte_*`; anchored edges MUST have both `source_byte_*` set, and may NOT be `inferred` at scan time (`writer.rs:440–449`) because inferred-tier edges are query-time-only. Violations return `StorageError::WriterProtocol` with one of three CLA codes (`CLA-INFRA-EDGE-CONFIDENCE-CONTRACT`, `CLA-INFRA-EDGE-SOURCE-RANGE-CONTRACT`, `CLA-INFRA-EDGE-UNKNOWN-KIND`) so the surrounding `runs.stats.failure_reason` carries the code (`writer.rs:402–410`).
-
-**Reader pool** (`reader.rs`). `ReaderPool::open` builds a `deadpool_sqlite::Pool` with `Runtime::Tokio1` and a caller-supplied `max_size` (the CLI passes its own value; tests use small caps). `with_reader` acquires from the pool, submits a `'static` closure to deadpool's `interact()` blocking task pool, and applies read-side PRAGMAs (`busy_timeout=5000`, `foreign_keys=ON`) on every acquisition. Retry-on-`SQLITE_BUSY` is delegated to SQLite itself via `busy_timeout` rather than an application-level loop — both writer and readers wait up to 5 s for the lock. WAL mode (set on the writer's first connection, `pragma.rs:16–31`) is what lets readers proceed concurrently without seeing in-flight writes. `waiting_count()` (`reader.rs:85–87`) is exposed `#[doc(hidden)]` for deterministic test polling.
-
-**Cache keys.** `SummaryCacheKey` (`cache.rs:7–14`) materialises ADR-007's 5-tuple exactly: `(entity_id, content_hash, prompt_template_id, model_tier, guidance_fingerprint)`. `ontology_version` is *not* in the key (correct per ADR-007 — that field is handshake validation only). `InferredEdgeCacheKey` (`cache.rs:30–36`) is a 4-tuple `(caller_entity_id, caller_content_hash, model_id, prompt_version)`. **Boundary clarification**: cache lookup/upsert helpers in `cache.rs` are pure storage operations; on a miss, `clarion-mcp::lib.rs` decides whether to call the LLM (via `clarion-core::LlmProvider`), then enqueues the result via `WriterCmd::UpsertSummaryCache` or `WriterCmd::InsertInferredEdges`. This crate does not depend on `clarion-core::LlmProvider`; its only `clarion-core` dependency is `EdgeConfidence` (`commands.rs:14`, `query.rs:6`).
-
-**Query helpers re-exported via `lib.rs`** (`lib.rs:27–32`): `entity_by_id`, `entity_at_line` (innermost-entity-at-line with tie-break by source-range size then kind preference function→class→module), `find_entities` (FTS5 if the pattern is alnum/underscore; LIKE-with-escape otherwise — see `is_fts_safe` at `query.rs:552`), `call_edges_from` / `call_edges_targeting` (apply ADR-028 confidence ceiling; for `ambiguous` edges, expand the `properties.candidates[]` JSON array into multiple match rows — `query.rs:218–235`, `523–534`), `contained_entity_ids` (iterative DFS over `contains` edges with cycle guard and `max_entities` truncation — `query.rs:354–388`), `unresolved_call_sites_for_caller`, `unresolved_callers_for_target` (LIKE-suffix match on `callee_expr` with same-file preference — `query.rs:294–332`), `candidate_entities_for_unresolved_sites`, `child_entity_ids`, `normalize_source_path` (project-root jail; both lexical normalisation and `canonicalize()` are checked — `query.rs:76–104`).
-
-### External interface
-
-`lib.rs` (35 LOC) re-exports a closed surface: the `WriterCmd`/`EdgeRecord`/`EntityRecord`/`RunStatus` typed boundary; `Writer` and the two channel/batch constants; `ReaderPool`; the query helpers; the cache key types and their three pure helpers (`summary_cache_lookup`, `inferred_edge_cache_lookup`, `inferred_edge_cache_key_id`); `StorageError`/`Result`. Internal modules `pragma` and `schema` are `pub mod`, used by `clarion-cli::install` (`crates/clarion-cli/src/install.rs:20`). `clarion-mcp::lib.rs:22–30` consumes 18 named symbols; `clarion-cli::analyze.rs:24–27` consumes 4 (writer/command shapes only).
-
-### Dependencies
-
-- **Inbound** (verified via `use clarion_storage::` grep):
-  - `clarion-mcp` — full read surface + the four query-time `WriterCmd` variants
-  - `clarion-cli` — `analyze.rs` (writer + commands), `install.rs` (`pragma` + `schema`), `serve.rs` (`Writer` + `ReaderPool` + batch constants)
-- **Outbound** (`Cargo.toml`):
-  - `clarion-core` — only for `EdgeConfidence` (used in `commands.rs` + `query.rs`); intentionally minimal
-  - `deadpool-sqlite 0.8` — async-friendly read pool (ADR-011)
-  - `rusqlite 0.31` — bundled SQLite, sole write driver
-  - `tokio` — `mpsc` + `oneshot` channels, `spawn_blocking` for the writer task
-  - `serde_json` — JSON shape validation on `InferredCallEdgeRecord.properties_json` + `ambiguous` `candidates[]` decoding
-  - `thiserror`, `tracing`
-
-No outbound dependency on `clarion-mcp`, `clarion-cli`, or any plugin crate. Crate-level acyclicity holds.
-
-### Patterns observed
-
-- **Actor + pool split (ADR-011).** Single writer task owns the write connection; all multi-row mutations are batched into a transaction sized by writes (entity inserts + edge insert attempts, including dedupes). The pattern is documented as L3 lock-in (`writer.rs:1–13`).
-- **Typed command boundary.** Every mutation is a `WriterCmd` variant carrying its own `oneshot::Sender<Result<T>>` ack — per-command response, no batched fan-in. Adding a new mutation is a single-file append (`commands.rs`) plus a match arm (`writer.rs:152–249`).
-- **Defence in depth on closed vocabularies (ADR-031).** Two enforcement layers: the writer-actor (canonical) and SQL `CHECK` (backstop). The migration's per-column comments name which ADR closes each vocabulary; plugin-extensible columns are explicitly tagged "no CHECK by policy."
-- **Edge-contract failure codes are findings.** When `enforce_edge_contract` rejects, the error message embeds `CLA-INFRA-EDGE-*` codes that surface in `runs.stats.failure_reason` — making writer-rejected edges observable as machine-greppable findings rather than opaque protocol errors.
-- **`query_time_write` interleaves cleanly.** Query-time MCP writes commit the analyze-batch first, then reopen `BEGIN` if a run is still in progress — the actor never holds an MCP cache row open inside an analyze transaction.
-- **Validation depth on path inputs.** `normalize_source_path` does lexical normalisation *and* `canonicalize()`, and checks containment against the canonicalized project root in both forms (`query.rs:76–104`). Prevents symlink/`..` escape against `entity_at_line` and `find_entity`.
-- **B.3 dual-encoding check at commit.** Parent/contains consistency is verified inside the transaction at `CommitRun` time (`writer.rs:733–796`), so an inconsistent run rolls back rather than persisting a half-corrupt graph.
-
-### Concerns
-
-- **Single migration, edit-in-place under ADR-024.** `migrations/0001_initial_schema.sql` has been edited three times (initial; 2026-05-03 ADR-024 vocabulary rename; 2026-05-18 ADR-031 `CHECK` clauses). The retirement trigger is documented in-file (`0001_initial_schema.sql:10–16`) but no automated check fires when the trigger condition (external operator builds `.clarion/clarion.db` from a published Clarion build) is met. Manual discipline only. Mitigated by the migration's own `schema_migrations` row idempotence (`schema.rs:81–89`).
-- **Edge ontology is duplicated.** `STRUCTURAL_EDGE_KINDS` + `ANCHORED_EDGE_KINDS` are hard-coded in `writer.rs:394–401`; ADR-026/028 are the design source; the Python plugin's manifest declares `edge_kinds = ["contains", "calls", "references"]` independently. A new kind requires edits in at least three places (manifest, writer, ADR). No compile-time enforcement that these stay in sync.
-- **Schema-shape FK in `entities.source_file_id` is self-referential** (`migrations/0001_initial_schema.sql:40`). Works because source-file entities are inserted before their contained functions/classes (plugin traversal order), but there is no constraint that enforces insertion order. A plugin emitting children before parents would fail with an FK violation, surfacing as an opaque `rusqlite::Error` rather than a writer-protocol error.
-- **`busy_timeout=5000` is the only `SQLITE_BUSY` mitigation.** Under heavy contention a reader can fail with a SQLite-level busy error rather than being retried at the application layer. The B.8 scale test exercises this path in practice; no per-attempt retry loop exists in `with_reader`.
-- **`InsertEdge` and `InsertEntity` share a single batch counter.** An edge-heavy file (e.g., a module with many `references` edges) can flush the batch boundary mid-file. Documented behaviour (`writer.rs:285–289`) but worth flagging — long transactions are not bounded by file boundary.
-- **No write-side throttling on `WriterCmd` channel.** `DEFAULT_CHANNEL_CAPACITY = 256` (`writer.rs:38`); a faster producer than the actor will block via `Sender::send().await` backpressure, which is correct, but no metric is exposed for "time spent blocked on writer queue."
-
-### Confidence
-
-**Confidence:** High — Read 100% of every `src/*.rs` module (10 files, 1 950 LOC) and the migration in full (289 LOC). Cross-validated dependency direction by grepping `use clarion_storage::` across the workspace: only `clarion-mcp` and `clarion-cli` consume it; no inbound cycles. Confirmed `WriterCmd` variant count (9) matches the actor's match arms one-to-one. Schema CHECK constraints verified at exact line numbers against ADR-031's "closed vs. extensible" decision. Edge-contract code-paths (`enforce_edge_contract` and the three CLA codes it emits) read end-to-end. ADR cross-references are inline in both the migration and the writer source, so the "ADR says X / code does Y" gap is small.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/section-fixture-plugin.md b/docs/arch-analysis-2026-05-18-1244/temp/section-fixture-plugin.md
deleted file mode 100644
index 96688133..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/section-fixture-plugin.md
+++ /dev/null
@@ -1,53 +0,0 @@
-## Test-only Rust fixture plugin (`clarion-plugin-fixture`)
-
-**Location:** `crates/clarion-plugin-fixture/src/`
-
-**Responsibility:** Protocol-compatible stand-in for a real language plugin: a minimal Rust binary speaking the same Content-Length-framed JSON-RPC 2.0 protocol on stdin/stdout as the Python plugin, used by `clarion-core`'s `host_subprocess` integration test to exercise `PluginHost::spawn` end-to-end without bringing a Python interpreter and pyright into the test loop.
-
-**Key Components:**
-
-- `Cargo.toml` (19 lines) — declares a single `[[bin]]` target (`clarion-plugin-fixture`, `src/main.rs`); depends on `clarion-core` (path dep, version `0.1.0-dev`) and `serde_json` from the workspace; inherits workspace `[lints]`. No library is published.
-- `src/main.rs` (128 lines, full code) — the entire plugin. One blocking `loop` over `read_frame(&mut reader, ContentLengthCeiling::DEFAULT)` (`main.rs:33`); per-frame `serde_json::from_slice` to a free-form `Value` so it can branch on `id`-presence (notification vs. request) before typed deserialisation (`main.rs:37-46`). Five method branches matching the L4 protocol surface:
-  - `initialize` (request) → `InitializeResult { name: "clarion-plugin-fixture", version: "0.1.0", ontology_version: "0.1.0", capabilities: {} }` (`main.rs:68-76`).
-  - `initialized` (notification) → state transition only, no reply (`main.rs:50-53`).
-  - `analyze_file` (request) → extracts `params.file_path` (or `""`), echoes it back inside one stub entity `{"id": "fixture:widget:demo.sample", "kind": "widget", "qualified_name": "demo.sample", "source": {"file_path": <echoed>}}`, returns `AnalyzeFileResult { entities: vec![entity], edges: vec![], stats: default }` (`main.rs:77-108`).
-  - `shutdown` (request) → empty `ShutdownResult` (`main.rs:109-112`).
-  - `exit` (notification) → `std::process::exit(0)` (`main.rs:54-56`).
-- `src/lib.rs` (3 lines) — comment-only stub explaining the crate is binary-only; exists so Cargo resolves the workspace member cleanly.
-
-**Dependencies:**
-
-- Inbound: `crates/clarion-core/tests/host_subprocess.rs` is the sole consumer — it locates the binary via `CARGO_BIN_EXE_clarion-plugin-fixture`, falling back to `<target_dir>/{debug,release}/clarion-plugin-fixture`; the manifest `tests/fixtures/plugin.toml` is `include_bytes!`-embedded at compile time (`host_subprocess.rs:16`). CI's `walking-skeleton` job builds this binary as part of `cargo build --workspace --bins` so the test can find it on disk (see `CLAUDE.md` build-commands section: "wp2_e2e tests need clarion-plugin-fixture on disk").
-- Outbound: `clarion-core::plugin::limits::ContentLengthCeiling` (the 8 MiB default), `clarion-core::plugin::transport::{Frame, read_frame, write_frame}` (the shared framing codec), `clarion-core::plugin::{AnalyzeFileParams, AnalyzeFileResult, AnalyzeFileStats, InitializeResult, JsonRpcVersion, ResponseEnvelope, ResponsePayload, ShutdownResult}` (the typed protocol structs); `serde_json` for the free-form `Value` pre-dispatch.
-
-**Patterns Observed:**
-
-- **Protocol-by-shared-types.** The fixture reuses `clarion-core`'s own protocol structs (`InitializeResult`, `AnalyzeFileResult`, `ResponseEnvelope`, …) for response serialisation — there is no parallel schema definition. A breaking change to `protocol.rs` therefore fails compilation of the fixture, not at runtime under test, which is the right ordering.
-- **Same ceiling as production.** Frame reads use `ContentLengthCeiling::DEFAULT` (the ADR-021 §2b 8 MiB cap), with the source comment explicitly noting that `unbounded()` is now `#[cfg(test)]`-only (`main.rs:30-32`). The fixture lives under the same wire-cap discipline as a real plugin.
-- **Fail-fast on protocol violations.** Every recoverable branch in a real plugin is `std::process::exit(1)` here — malformed frame, non-object body, missing/non-string `method`, integer-id parse failure, unknown method, params-deserialise failure (`main.rs:34, 39, 45, 57, 64, 90, 113`). Acceptable because the consumer is exclusively an integration test; the alternative would obscure protocol-violation bugs behind fixture-side error handling.
-- **Notification vs. request branching on `id`-presence.** Reads the raw `Value` first, checks `id.is_some_and(|v| !v.is_null())` to decide whether the frame requires a response (`main.rs:42, 48-60`). This matches the JSON-RPC 2.0 spec and parallels the Python plugin's branching in `server.dispatch` (`server.py:239-261`).
-- **Stable identity for assertions.** `plugin_id = "fixture"`, kind `"widget"`, and the literal entity ID `"fixture:widget:demo.sample"` are baked into the source — `host_subprocess.rs` asserts on this exact string, so the test signal is exact-match rather than parse-and-inspect.
-
-**Concerns:**
-
-- **No request-id sanity on `shutdown`.** Unlike the Python plugin, the fixture doesn't gate `analyze_file` on having received `initialized` — `state.initialized` doesn't exist. This is fine for the single happy-path test it supports, but means the fixture cannot exercise the host's `-32002 NOT_INITIALIZED` error path. If a future test wanted to assert that the host *itself* sequences the handshake correctly, it would have to verify host-side state rather than fixture-side rejection.
-- **`exit(1)` on any malformed frame is observable only as a non-zero process exit.** The host-side test gets no structured signal about which branch failed. For an integration test fixture this is by design; flagging because anyone running the fixture by hand against a non-test client will see opaque exits.
-- **No stderr discipline.** A real plugin (Python's `stdout_guard.py`) reserves stdout strictly for framing; the fixture relies on the absence of any `eprintln!` or `println!` in its own code rather than installing a guard. For a 128-line file with `serde_json` as the only output-side dep this is fine, but worth noting as a delta from the production-plugin pattern.
-
-**Confidence:** High — Read `main.rs` (128 lines, 100% of file), `lib.rs` (3 lines, 100%), `Cargo.toml` (19 lines, 100%); cross-verified consumer via `crates/clarion-core/tests/host_subprocess.rs` lines 3-7, 15-27, and 60-66 (binary-location strategy, fixture identity assertions, manifest constants). Cross-validated against `docs/arch-analysis-2026-05-18-1244/01-discovery-findings.md` §4 Subsystem E framing and `CLAUDE.md` layout summary. Protocol identity confirmed by the matching set of imports from `clarion_core::plugin::*` against the Python plugin's `server.py:7-19` docstring describing the same five methods and response shapes. Content-Length framing parity confirmed via the explicit `ContentLengthCeiling::DEFAULT` (8 MiB) source comment matching the Python `MAX_CONTENT_LENGTH = 8 * 1024 * 1024` at `server.py:48`.
-
-**Information Gaps:**
-
-- Did not read the upstream `clarion_core::plugin::transport` module to verify exactly how `read_frame` / `write_frame` interpret the ceiling; took the source comment at face value.
-- Did not run `cargo build -p clarion-plugin-fixture` on the current branch to confirm the binary still compiles. Treated the unmodified `Cargo.toml` and the recent (b87bc1d) signoff record as sufficient evidence that the walking-skeleton CI job was green at sprint close.
-
-**Caveats:**
-
-- "Protocol-compat" here means *exact wire-shape compatibility* on the five L4 methods. The fixture does not exercise the `capabilities.wardline` probe shape, `parse_status` on module entities, `parent_id`/`contains` edges, calls/references resolution, the `stats` payload's `unresolved_call_sites`, or any of the Sprint-2 ontology surface. It is a *minimum*-shape test stand-in, not a feature-parity one.
-- The fixture's `ontology_version = "0.1.0"` (`main.rs:72`) is deliberately the Sprint-1 baseline; this is the version against which the host's manifest-handshake validator is tested. It does *not* track the Python plugin's `0.5.0` and shouldn't.
-
-**Risk Assessment:**
-
-- *Drift between fixture and real plugins.* The fixture has been stable since Sprint 1 close and the protocol contract is enforced by shared `clarion-core` types, so the drift surface is bounded to behavioural-not-structural divergence (e.g. a real plugin adding handshake side-effects the fixture doesn't model). The host-side test exercises only the structural surface, so this is a known-acceptable gap.
-- *Single-consumer dependency.* The fixture exists exclusively for `host_subprocess.rs`. If that test were retired, the fixture would become dead code; conversely, the test cannot be expanded to cover behaviours the fixture doesn't model without growing the fixture. Pre-existing carryover issue `clarion-adeff0916d` (fixture-binary self-build) tracks one known sharp edge here.
-- *Build-ordering coupling.* The walking-skeleton CI job depends on `cargo build --workspace --bins` running before `cargo nextest run` so the binary is on disk when `host_subprocess.rs` looks for it. This is documented in `CLAUDE.md` and codified in `.github/workflows/ci.yml`'s `walking-skeleton` job, but is an implicit dependency that would break if a future contributor used `cargo nextest run --workspace` without the prior `cargo build`.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/section-python-plugin.md b/docs/arch-analysis-2026-05-18-1244/temp/section-python-plugin.md
deleted file mode 100644
index 4e5b52b5..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/section-python-plugin.md
+++ /dev/null
@@ -1,78 +0,0 @@
-## Python language plugin (`plugins/python`)
-
-**Location:** `plugins/python/src/clarion_plugin_python/`
-
-**Responsibility:** Out-of-process language plugin that ingests a single Python source file at a time, extracts module/class/function entities plus `contains`/`calls`/`references` edges, and serves them to the Rust core over a Content-Length-framed JSON-RPC 2.0 channel on stdin/stdout (the L4 protocol).
-
-**Key Components:**
-
-- `__main__.py` (15 lines) — installs the stdout discipline guard, then delegates to `server.main()`; threads the server's exit code out to the host (`__main__.py:14`).
-- `server.py` (285 lines) — L4 JSON-RPC dispatch loop. Implements the five protocol methods exactly as the Rust host's typed `protocol.rs` expects: `initialize`/`initialized`/`analyze_file`/`shutdown`/`exit` (`server.py:226-261`). Owns `ServerState` (initialized flag, shutdown flag, captured `project_root`, lazy `PyrightSession`) and the `read_frame`/`write_frame` Content-Length codec with an 8 MiB symmetric cap matching ADR-021 §2b (`server.py:48`, `71-126`). `handle_initialize` captures the host-supplied `project_root` and embeds the Wardline probe result in `capabilities.wardline` (`server.py:141-153`). `handle_analyze_file` reads the file off disk, lazily constructs the `PyrightSession`, and calls `extractor.extract_with_stats(...)` (`server.py:177-221`).
-- `extractor.py` (744 lines, +98 on this branch for B.8) — AST → wire-shape extractor. `extract_with_stats` parses the source with `ast.parse`, prepends exactly one `module` entity (B.2 §3 Q1), then recursively walks via `_walk` to emit one `function` per `FunctionDef`/`AsyncFunctionDef` and one `class` per `ClassDef` (`extractor.py:261-344`, `_walk` at `589-668`). `parent_id` and one `contains` edge per non-module entity satisfy ADR-026 decision 2's dual encoding (`extractor.py:107-117`, `671-677`). `_ReferenceSiteCollector` is the separate `ast.NodeVisitor` pass for B.5* reference sites (`extractor.py:358-485`), then `extract_with_stats` hands the function IDs to `call_resolver.resolve_calls` and the reference sites to `reference_resolver.resolve_references` (`extractor.py:338-342`). Same-id collisions are handled at the emit boundary: `_has_overload_decorator` recognises `@overload` / `@typing.overload` / `@typing_extensions.overload` and skips emission *and* recursion entirely (`extractor.py:567-586`, `624`); any other duplicate (aliased overload imports, `@singledispatch.register def _():` runs) is dropped first-wins with a stderr line and a `duplicate_entities_dropped_total` bump (`extractor.py:629-637`).
-- `pyright_session.py` (1251 lines) — long-running `pyright-langserver --stdio` LSP client. See sub-section below.
-- `call_resolver.py` (64 lines) — `CallResolver` `Protocol` plus `CallsRawEdge` / `UnresolvedCallSite` / `Finding` TypedDicts; `NoOpCallResolver` is the test stand-in (`call_resolver.py:49-64`). `PyrightSession` is the production implementation.
-- `reference_resolver.py` (69 lines) — symmetric: `ReferenceResolver` `Protocol`, `ReferenceSite` dataclass, `ReferencesRawEdge` TypedDict, `NoOpReferenceResolver` (`reference_resolver.py:54-69`).
-- `entity_id.py` (75 lines) — Python side of the L2 byte-for-byte ADR-003+ADR-022 entity-ID assembler. Validates `plugin_id` / `kind` against the grammar `[a-z][a-z0-9_]*`, refuses the `:` separator inside any segment, raises typed `EmptySegmentError` / `GrammarViolationError` / `SegmentContainsColonError`. Cross-validated against `fixtures/entity_id.json` row-by-row (`entity_id.py:66-75`).
-- `qualname.py` (46 lines) — ADR-018 L7 canonical qualname. Pure-AST reconstruction of CPython's runtime `__qualname__`: walks the parent chain in reverse, prepending `parent.<locals>.` for function ancestors and `parent.` for class ancestors (`qualname.py:32-46`). Lock-in: this string must equal what Wardline produces for the same definition, otherwise the cross-product join breaks.
-- `wardline_probe.py` (56 lines) — L8 fail-soft Wardline probe. `importlib.import_module("wardline.core.registry")` plus `importlib.import_module("wardline")`, then a `packaging.version` half-open range check against the manifest's `[integrations.wardline].min_version` / `max_version` (`wardline_probe.py:36-56`). Returns one of three dicts: `{"status": "absent"}`, `{"status": "enabled", "version": ...}`, `{"status": "version_out_of_range", "version": ...}`. **Invoked once per session at `initialize`** (`server.py:151`), never per-file. The `wardline.core.registry` import is the named Loom-doctrine asterisk from `docs/suite/loom.md` §5; Sprint 1 only proves the import + version-pin handshake — REGISTRY is not yet consumed.
-- `stdout_guard.py` (62 lines) — replaces `sys.stdout` with a `_GuardedTextStdout` that raises `StdoutGuardError` on any write; captures the real `stdin.buffer` / `stdout.buffer` byte streams for the framing codec to use (`stdout_guard.py:57-62`). Single-shot, called by `__main__` before the dispatch loop starts.
-- `__init__.py` (3 lines) — `__version__ = "0.1.4"`.
-
-**Sub-section: `pyright_session.py` (1251 lines, ~17% of total plugin LOC)**
-
-This file is the entire pyright integration surface. Internal structure:
-
-- *Public class `PyrightSession`* (`:117-758`) — implements both the `CallResolver` and `ReferenceResolver` Protocols. Constructed lazily once per `analyze_file` session by `server.handle_analyze_file` and held on `ServerState.pyright` for the lifetime of the connection (`server.py:193-194`, closed in `shutdown` handler at `server.py:246-248`). Public surface: `__init__`/`__enter__`/`__exit__`/`close`/`resolve_calls`/`resolve_references`/`kill_for_test`/`stderr_thread_alive`. Constructor knobs (`init_timeout_secs=30`, `call_timeout_secs=5`, `max_restarts_per_run=3`, `max_reference_sites_per_file=2000`) are exposed for tests (`pyright_session.py:118-145`).
-- *Process lifecycle* — `_ensure_process` (`:505-516`) lazily spawns; `_start_process` (`:536-599`) does `subprocess.Popen([pyright-langserver, --stdio], cwd=project_root, env=..., stdin/stdout/stderr=PIPE)` and immediately calls `_initialize` with the LSP `initialize` request (`:601-616`). `_resolve_executable` (`:618-625`) walks: absolute-path → `sys.executable`'s sibling directory (i.e. the active venv) → `shutil.which`. A stderr-drain thread (`_start_stderr_drain` `:634-640`, `_drain_stderr` `:642-649`) keeps the 64 KiB `_stderr_tail` ring populated for diagnostics; the thread is daemonised.
-- *Restart / poison handling* — `_record_restart_or_poison` (`:518-534`) increments `_restart_count` and emits a `CLA-PY-PYRIGHT-RESTART` finding; after 3 restarts the session goes `_disabled = True` and emits one `CLA-PY-PYRIGHT-POISON-FRAME`. Five fail-soft `CLA-PY-PYRIGHT-*` finding subcodes are defined at the top of the file (`:34-41`).
-- *LSP transport* — `_request` (`:651-670`) writes Content-Length-framed JSON and busy-loops on `_read_message` skipping mismatched-id frames; `_notify` (`:672-674`) is the no-response variant; `_read_message` (`:693-714`) reads headers + body using `_read_line`/`_read_exact`/`_wait_readable` helpers (`:1218-1247`) that enforce a per-call deadline via `select.select` on the pipe fd.
-- *Call resolution* (`resolve_calls` + `_resolve_with_pyright` `:181-380`) — opens the file via `textDocument/didOpen`, issues `textDocument/prepareCallHierarchy` per function entity, then `callHierarchy/outgoingCalls` per returned item. Edges are grouped by source byte range; multi-target ranges produce one `ambiguous` edge with the candidate list in `properties.candidates` (per ADR-028 confidence tiers, `:359-369`). Two AST-side enrichers — `_ambiguous_dict_dispatches` and `_dunder_call_dispatches` (`:1003-1145`) — fold dict-of-callables and `__call__`-on-instance patterns that pyright doesn't track natively into the same `grouped` map. Always followed by `textDocument/didClose` in `finally:` (`:380`).
-- *Reference resolution* (`resolve_references` + `_resolve_references_with_pyright` `:228-453`) — hard cap of 2 000 sites per file (emits `CLA-PY-PY-REFERENCE-SITE-CAP` and returns early, `:238-250`); per-site `textDocument/references` queries with annotation-fallback retry (`:411-422`); deduplicates by `(from_id, to_id)` accumulator and finalises with `_reference_accumulator_to_edge` (`:922-937`). All exceptions are caught at the boundary and converted to fail-soft results.
-- *AST function-indexing helpers* (`_build_function_index`, `_collect_entities`, `_CallSiteVisitor`, `_DictDispatchVisitor`, `_DunderCallDispatchVisitor` `:760-1145`) — a parallel AST pass independent from `extractor.py`'s walker; necessary because `PyrightSession` needs LSP positions (line/character) for every function and class plus the per-function call-site index, neither of which the wire shape carries.
-
-**Dependencies:**
-
-- Inbound: Rust core's plugin host (`crates/clarion-core/src/plugin/host.rs`) spawns this plugin via the `clarion-plugin-python` console script; the host's typed `protocol.rs` (`InitializeResult`, `AnalyzeFileResult`, `AnalyzeFileStats`, `ShutdownResult`) is the wire contract; the host's writer-actor (`clarion-storage`) consumes the emitted entities and edges; the `walking-skeleton` CI job invokes the full pipeline.
-- Outbound: `pyright==1.1.409` (LSP server subprocess, pinned in both `pyproject.toml:20` and `plugin.toml:29`); `packaging>=24` (version-range parsing in the Wardline probe); Python stdlib only otherwise (`ast`, `json`, `subprocess`, `select`, `threading`, `importlib`, `pathlib`, `urllib.parse`). `wardline` is a **soft** outbound dependency — imported only to probe at `initialize`; absence is not an error. The doctrine asterisk noted in `docs/suite/loom.md` §5 is real: `wardline.core.registry` is imported by name (`wardline_probe.py:38`), and the manifest pins `[integrations.wardline] min_version=1.0.0 max_version=2.0.0` (`plugin.toml:48-55`).
-
-**Patterns Observed:**
-
-- **Protocol-typed wire boundary.** Every method handler returns a TypedDict whose shape mirrors the Rust host's serde structs exactly (`server.py:7-19` docstring enumerates this). The five JSON-RPC error codes used (`-32600`, `-32601`, `-32603`, `-32002`) are LSP-style (`server.py:51-54`). Out-of-spec frames raise `ProtocolError`, which propagates out of the loop and exits with status 1 (`server.py:284-285`).
-- **Fail-soft pyright integration.** Every external failure mode of `pyright-langserver` (not installed, install-check rejection, init timeout, runtime timeout, transport-closed, broken pipe, OSError) is caught at the `resolve_calls` / `resolve_references` boundary, downgraded to a `CLA-PY-PYRIGHT-*` finding, and returned as "unresolved" counts in the result — never raised back into the dispatch loop (`pyright_session.py:202-217`, `265-280`). The 3-restart cap then disables the session entirely for the run.
-- **Two-pass AST.** The extractor pass (`extractor.py`) produces wire entities + structural `contains` edges; a parallel AST pass inside `pyright_session.py` (`_build_function_index`, `_CallSiteVisitor`) builds the position-indexed function index pyright needs. The two never share a tree; this duplicates `ast.parse` work but keeps the extractor a pure function of source bytes.
-- **`Protocol`-typed resolvers with No-Op fallback.** `CallResolver` and `ReferenceResolver` are `typing.Protocol`s with `NoOpCallResolver` / `NoOpReferenceResolver` defaults baked into `extractor.extract`'s kwargs (`extractor.py:83-84`, `247-249`). Tests can construct the extractor without spawning pyright.
-- **Stdout-strictness via guard object.** `_GuardedTextStdout` raises rather than silently swallows; any library print() becomes a `StdoutGuardError`, which the dispatch boundary turns into a `_ERR_INTERNAL` JSON-RPC response (`server.py:259-260`). This is the plugin-side closure of WP2 UQ-WP2-08.
-- **Path-jail-aware path handling.** `_resolve_module_path` relativises only the path used for the dotted qualname prefix; the wire `source.file_path` stays exactly as the host sent it, so the host's path-jail (which canonicalises against `project_root`) sees the original (`server.py:156-174`, `extractor.py:24-32`).
-- **Single source of truth on ontology version.** The manifest declares `ontology_version = "0.5.0"` (`plugin.toml:46`); `server.py:36` redeclares the same constant `ONTOLOGY_VERSION = "0.5.0"`. Two declarations, no shared import — kept matched by hand per ADR-027.
-- **B.8 fix layered defence.** The `@overload`-stub skip in `_has_overload_decorator` is the *fast path* for the named PEP 484 case; the same-id dedup loop in `_walk` is the *belt-and-suspenders* for anything the pattern-based check misses (aliased imports, `@singledispatch.register def _():`). Both feed the same wire-correctness invariant (no two entities with identical IDs) so the host's `UNIQUE(entities.id)` never trips mid-run (`extractor.py:283-294`, `624-637`, `645-652`).
-
-**Concerns:**
-
-- **Doctrine asterisk still live.** `wardline_probe.py:38` imports `wardline.core.registry` by name — exactly the Loom-doctrine asterisk called out in `docs/suite/loom.md` §5. Retirement condition is documented but not yet met. Not a defect; flagged because any architecture-quality review should know this is deliberate.
-- **`ONTOLOGY_VERSION` is duplicated in two files (`server.py:36` and `plugin.toml:46`)** with no compile-time/runtime cross-check that they match. If a future ADR-027 minor bump updates one and forgets the other, the handshake validates the manifest value while the plugin behaves per the constant — silent skew. The comment at `server.py:38-41` acknowledges this and defers the manifest-flow-through.
-- **`PyrightSession.close()` masks errors from the LSP `shutdown`/`exit` exchange** (`pyright_session.py:170`): timeouts, transport-closed, broken pipe, and `OSError` are all swallowed before the kill-and-wait. This is the correct behaviour at process-end, but it means a pyright that hangs on shutdown gives no signal beyond the eventual `process.kill()`.
-- **`_resolve_with_pyright` busy-loops on mismatched `id` responses** (`pyright_session.py:663-666`). If pyright ever sends a stream of id-mismatched frames between request and response (server-initiated notifications, mismatched-cancel ack), the loop just keeps reading until the per-call deadline fires. The deadline upper-bounds it (5 s default), so this is bounded rather than fatal.
-- **`_resolve_module_path`'s fall-through to the raw path on `ValueError`** (`server.py:170-173`) writes the absolute path into `source.file_path` of every emitted entity, which the host's path-jail check will reject. The comment says this is intentional ("fall back to the raw path so the host's logs show the drift"); whether that's the right failure mode versus an explicit per-file error finding is a design call worth noting for axiom-system-architect.
-- **AST re-parse duplication.** `extractor.py` and `pyright_session._build_function_index` each call `ast.parse` on the same source bytes for every `analyze_file`. At elspeth-scale (~425k LOC Python) this is two AST walks per file, not one. Not yet measured; called out because the B.8 scale test on this branch is exactly where this would surface.
-
-**Confidence:** High — Read in full: `plugin.toml`, `pyproject.toml`, `server.py` (285), `extractor.py` (744), `qualname.py` (46), `wardline_probe.py` (56), `entity_id.py` (75), `stdout_guard.py` (62), `call_resolver.py` (64), `reference_resolver.py` (69), `__init__.py`, `__main__.py`. Sampled `pyright_session.py` top-level structure (every `def`/`class` declaration line) plus full reads of `__init__`, `close`, `resolve_calls`, `resolve_references`, `_resolve_with_pyright`, `_ensure_process`, `_record_restart_or_poison`, `_start_process`, `_initialize`, `_resolve_executable`, `_subprocess_env`, `_start_stderr_drain`, `_drain_stderr`, `_request`, `_notify`, `_live_process`, `_write_message`, `_read_message`. Cross-validated: B.8 `@overload` commit `29f0426` body cited verbatim, manifest pyright pin matches `pyproject.toml` pin (`1.1.409` in both `plugin.toml:29` and `pyproject.toml:20`), Wardline probe is initialize-only (single call site at `server.py:151`), the doctrine asterisk import path matches `loom.md` §5's wording. Tests directory inventory matches source-file inventory 1:1 (10 source files, 10 test files including `test_round_trip.py`).
-
-**Information Gaps:**
-
-- Did not exhaustively read `pyright_session.py` lines 715-1247 (the AST function-indexing helpers, dict-dispatch visitor, byte/position translators). Sampled enough to confirm shape but not every branch.
-- Did not read the test files (`tests/test_*.py`); test coverage claims would require that step.
-- Did not verify wire-shape claims by running the e2e script (`tests/e2e/sprint_1_walking_skeleton.sh`); compatibility is asserted from the Python TypedDicts vs. the Rust `protocol.rs` docstring at `server.py:7-19`, not from a live run on this branch.
-- Did not chase `clarion-core/src/plugin/host.rs:132-154` to confirm the `RawEntity` / `RawSource` shape claim cited in `extractor.py:8-22`. Treated as authoritative because the extractor docstring is dated to the same commit family as the host.
-
-**Caveats:**
-
-- LOC counts via `wc -l` include blank lines and docstring lines. The "actual code" share is lower; `extractor.py:1-54` is all docstring, for instance.
-- "B.8 +98 lines on this branch" is taken from the discovery-findings document's framing; I did not run `git diff main...HEAD -- extractor.py | wc -l` to verify exactness, but the commit `29f0426` body matches the behaviour read in `extractor.py:567-668`.
-- The `wardline_probe` integration is described as "fail-soft" based on the three return shapes; whether downstream consult-mode briefings actually do anything different when `status == "enabled"` versus `"absent"` is out of scope for this entry (it would require reading the MCP briefing assembler).
-
-**Risk Assessment:**
-
-- *Doctrine asterisk surface.* The `wardline.core.registry` import (`wardline_probe.py:38`) is a known, ratified asterisk under `loom.md` §5 — risk is bounded by the documented retirement condition, but it remains a point where the federation axiom is consciously bent. Any review must surface it.
-- *Wire-shape skew risk.* The plugin re-declares `ONTOLOGY_VERSION = "0.5.0"` (`server.py:36`) and `entity_kinds`/`edge_kinds`/`rule_id_prefix` (`plugin.toml:35-39`) as parallel sources of truth with the host's `protocol.rs`. Skew here would surface only at the handshake — the host's validator rejects mismatched `ontology_version` per ADR-027, so the risk is detected, not silent.
-- *Pyright-availability dependency.* The walking-skeleton CI job and any `analyze` run that requests `calls` or `references` edges hard-depends on `pyright-langserver` resolvable via PATH, the active venv, or absolute path (`pyright_session.py:618-625`). On hosts without Node, the plugin still ships entities (the no-op fallback path), but every function emits as "unresolved" — observable but not catastrophic.
-- *B.8 scale-test risk.* This branch (`sprint-2/b8-scale-test`) is precisely the change that hardens the extractor against the failure mode it was discovered under (UNIQUE collision on `@overload` stubs at elspeth scale). The fix is layered (semantic skip + safety-net dedup); the residual risk is aliased-overload imports plus identical-qualname intentional redefinitions, both of which now hit the safety-net path and log to stderr rather than crash.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/validation-02-subsystem-catalog.md b/docs/arch-analysis-2026-05-18-1244/temp/validation-02-subsystem-catalog.md
deleted file mode 100644
index 0ff48a3f..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/validation-02-subsystem-catalog.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Validation report — 02-subsystem-catalog.md
-
-## Status
-NEEDS_REVISION (warnings)
-
-## Summary
-The catalog substantially meets the contract: all six subsystems are present with the required sections (Location, Responsibility, Key components, Inbound/Outbound dependencies, Patterns, Concerns, Confidence); every entry cites file:line and assigns an explicit, reasoned confidence; cross-cutting concerns from discovery §5 are reflected. One **internal factual contradiction** survived the assembly: the `clarion-core` entry states `clarion-plugin-fixture` does not depend on `clarion-core`, while the index table, the fixture entry, and the actual `Cargo.toml` agree it does. The error is a single sentence and does not propagate elsewhere, so it is a documentation defect, not a structural one. Several minor LOC drifts (e.g. `clarion-mcp/src/lib.rs` documented as 2620, actually 2623) should be reconciled in a sweep but do not invalidate analysis.
-
-## Findings
-
-### Critical (block proceed)
-- None.
-
-### Warnings (document as tech debt, ok to proceed)
-
-1. **Factual contradiction inside the `clarion-core` entry — fixture dependency.**
-   Catalog line 123 (in the `clarion-core` Inbound block) says:
-   > *"`clarion-plugin-fixture` does **not** depend on `clarion-core` — the fixture binary speaks the wire protocol directly without sharing types."*
-   This is false. `crates/clarion-plugin-fixture/Cargo.toml:18` declares `clarion-core = { path = "../clarion-core", version = "0.1.0-dev" }`, and `crates/clarion-plugin-fixture/src/main.rs` opens with three `use clarion_core::plugin::...` lines pulling in `ContentLengthCeiling`, `Frame`, `read_frame`, `write_frame`, plus seven protocol envelope types. The Subsystem Index row E (catalog line 17) correctly shows outbound `core (types only)`, and the fixture entry (catalog lines 524, 536–540) correctly describes the dependency as "Protocol-by-shared-types" via `clarion-core`. The contradiction is local to the one parenthetical in the `clarion-core` entry. Fix: delete or invert the sentence at catalog line 123 to read "`clarion-plugin-fixture` depends on `clarion-core` for the typed protocol structs only (dev-dependency surface); it does not link against the supervisor / writer / MCP paths." This was the contradiction explicitly flagged by the task brief.
-
-2. **LOC drift between discovery, catalog, and on-disk files.**
-   - `clarion-mcp/src/lib.rs`: discovery says 2617, catalog says 2620, file is 2623. Acceptable drift (the file grew during B.8) but the catalog cites specific line ranges (e.g. "lines 296–319 for `tool_entity_at`") that will skew slightly. Recommend the line-range table be re-checked against the post-B.8 file or a commit SHA pinned to the analysis date.
-   - `clarion-core/src/plugin/host.rs`: catalog and discovery both 3126, file is 3126. Clean.
-
-3. **Catalog claims `clarion-mcp` issues exactly one raw SQL query bypassing `clarion-storage` (`reference_neighbors`).** Verified true (`crates/clarion-mcp/src/lib.rs:2381` is the sole `conn.prepare(` site). The catalog's "Concerns" line on schema coupling stands without modification.
-
-4. **The "Subsystem index" header row shows production LOC totals but does not call out that "Inbound deps" for the index excludes dev-dependencies.** The `clarion-cli` row reads inbound = `(binary — none)`, but `clarion-cli/Cargo.toml:[dev-dependencies]` lists `clarion-plugin-fixture`. This is a strict reading of "Rust library inbound" and is internally consistent with the rest of the catalog, but a future reader skimming the table may infer that the fixture is never linked by CLI. Recommend a footnote under the index table clarifying scope.
-
-5. **No "Confidence" header convention drift.** The contract calls for an explicit Confidence section; all six entries provide one (variously called "Confidence" or "Confidence Assessment"). No revision required; flagging for consistency.
-
-### Spot-checks performed
-
-| # | Claim | Verification | Result |
-|---|---|---|---|
-| 1 | `clarion-core/src/plugin/host.rs` is 3126 LOC, production code ~1450 LOC | `wc -l` = 3126; `grep '^#\[cfg(test)\]'` returns line 1451; production = lines 1–1450 | ✓ matches catalog |
-| 2 | `clarion-mcp/src/lib.rs` is 2620 LOC | `wc -l` = 2623 | Drift +3 (B.8 follow-up commits); not material |
-| 3 | `clarion-storage` has 9 `WriterCmd` variants | grepped `commands.rs`: `BeginRun`, `InsertEntity`, `InsertEdge`, `InsertInferredEdges`, `UpsertSummaryCache`, `TouchSummaryCache`, `ReplaceUnresolvedCallSitesForCaller`, `CommitRun`, `FailRun` | ✓ exactly 9 |
-| 4 | Migration is 289 LOC with ADR-031 CHECKs on `edges.confidence`, `findings.{kind, severity, status}`, `runs.status` | `wc -l` = 289; CHECK clauses at lines 90 (`edges.confidence`), 108 (`findings.kind`), 112 (`findings.severity`), 125 (`findings.status`), 153 (`summary_cache.stale_semantic`), 201 (`runs.status`) | ✓ matches; catalog also correctly notes `stale_semantic` (line 236 of catalog) which is the additional one |
-| 5 | `clarion-mcp` has exactly one raw SQL query (`reference_neighbors`) | Only `conn.prepare(` site in the crate is `lib.rs:2381`, inside `fn reference_neighbors` at `lib.rs:2366` | ✓ exactly one; matches catalog claim |
-| 6 | Python plugin's `wardline_probe.py` imports `wardline.core.registry` by name | `wardline_probe.py:38: importlib.import_module("wardline.core.registry")`; `loom.md:70` names this exact asterisk | ✓ verbatim match |
-| 7 | `clarion-plugin-fixture` depends on `clarion-core` (resolving the catalog's internal contradiction) | `Cargo.toml:18` and three `use clarion_core::plugin::*` lines in `main.rs` | ✓ depends on it; **catalog `clarion-core` entry is wrong**; fixture entry and index row are correct |
-| 8 | `llm_provider.rs` is 948 LOC; OpenRouter strict-JSON path lives at `response_format_for_purpose` with `"strict": true` for both purposes | `wc -l` = 948; `response_format_for_purpose` at line 297; `"strict": true` at lines 303 and 333 | ✓ matches catalog |
-| 9 | `pyright_session.py` is 1251 LOC | `wc -l` = 1251 | ✓ matches |
-| 10 | `extractor.py` is 744 LOC; `@overload`-stub skip via `_has_overload_decorator` plus safety-net dedup | `wc -l` = 744; `_has_overload_decorator` at line 567; first-wins dedup via `state.duplicate_entities_dropped` at lines 630, 647 | ✓ matches |
-
-### Cross-document consistency
-- **Bidirectionality of dependency claims.** Spot-checked four directional claims; all consistent.
-  - `clarion-storage` outbound to `clarion-core` (`EdgeConfidence` only) ↔ `clarion-core` is *not* listed as a consumer of `clarion-storage` anywhere ↔ `Cargo.toml` shows `clarion-storage` deps on `clarion-core` but not vice-versa. ✓
-  - `clarion-mcp` outbound to both `clarion-core` and `clarion-storage` ↔ both entries acknowledge inbound from `clarion-mcp`. ✓
-  - `clarion-cli` outbound to all three core/storage/mcp ↔ each of those entries lists `clarion-cli` as inbound. ✓
-  - Python plugin "subprocess of host" ↔ `clarion-core` entry's `host.rs::spawn` description matches; no Rust-link relationship, only stdio + on-disk discovery. ✓
-- **Coverage of cross-cutting concerns from discovery §5.** All seven items (entity-ID format, JSON-RPC L4, ontology version semver, edge confidence tiers, summary-cache 5-tuple, Loom federation doctrine, ADR-031 schema-validation policy) appear in catalog entries:
-  - Entity-ID format: in `clarion-core` (entity_id.rs, 610 LOC, ADR-003 parity).
-  - JSON-RPC L4: in `clarion-core/protocol.rs`, fixture entry "Protocol-by-shared-types", Python plugin `server.py`.
-  - Ontology version: in `clarion-storage` schema discussion and Python plugin's `ONTOLOGY_VERSION` duplication concern.
-  - Edge confidence tiers: in `clarion-storage::enforce_edge_contract` and `clarion-mcp::optional_confidence`.
-  - 5-tuple cache key: in `clarion-storage::cache` and `clarion-mcp::read_summary_inputs`.
-  - Loom doctrine: in Python plugin entry's "Doctrine asterisk still live" concern, and `clarion-mcp::filigree` enrich-only discussion.
-  - ADR-031: in `clarion-storage` (CHECK constraints discussion and edge contract).
-- **Sprint-2 deltas from discovery §7.** All represented:
-  - new `clarion-mcp` crate — full entry C exists.
-  - OpenRouter strict-JSON path — `clarion-core/llm_provider.rs` entry discusses it at lines 92–94 and 150 of catalog.
-  - ADR-031 CHECK clauses — `clarion-storage` entry, lines 236+.
-  - B.8 `@overload`-stub fix — Python plugin entry, lines 579 and 614–615.
-
-### Notes
-- The catalog is well-evidenced: ~80+ file:line citations spot-check as accurate.
-- "Confidence" sections in five of six entries explicitly state what was read in full vs sampled (e.g., `clarion-mcp` entry: "Read 100% of `config.rs`…sampled five handler bodies in full…"). This level of detail is unusually high for the contract and is a strength.
-- The Python plugin entry's "AST re-parse duplication" concern is a genuinely novel observation surfaced by the per-subsystem pass, not echoed in discovery; flagging as a value-add.
-- The dead-stub finding in `clarion-mcp` ("Dead stateless `handle_tool_call` stub", catalog line 373) is also a fresh observation; verified at `lib.rs:1701` as a real footgun.
-- Suggested edit ordering (low cost): (a) fix the fixture/clarion-core sentence at catalog line 123; (b) update mcp lib.rs LOC to 2623 or pin a commit SHA at the head of the catalog; (c) add a footnote under the Subsystem Index that "Inbound deps" excludes `[dev-dependencies]`.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/validation-03-diagrams.md b/docs/arch-analysis-2026-05-18-1244/temp/validation-03-diagrams.md
deleted file mode 100644
index d6af2043..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/validation-03-diagrams.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# Validation Report — 03-diagrams.md
-
-**Document:** `/home/john/clarion/docs/arch-analysis-2026-05-18-1244/03-diagrams.md`
-**Validator:** analysis-validator (independent pass)
-**Date:** 2026-05-18
-**Status:** APPROVED
-
----
-
-## Summary
-
-Five C4-inspired diagrams (Context, Container, two sequences, one component zoom). All Mermaid blocks parse cleanly; captions accurately describe what each diagram shows. Spot-checks against the catalog and source code confirm every substantive claim. All six subsystems from the catalog appear in at least one diagram. Loom-doctrine relationships (Filigree enrich-only, Wardline soft-import asterisk) are represented in the L1 view. ADR-007 5-tuple cache, edge-contract validator, writer-actor, and the host validator pipeline each have visible representation.
-
-No critical issues. Two minor notes recorded as informational; neither blocks progression.
-
----
-
-## Findings
-
-### Critical
-
-None.
-
-### Warnings
-
-None.
-
-### Spot-checks (all PASS)
-
-1. **Storage → Core dependency labelling (Diagram 2).**
-   The user's framing of the question pointed at `STORAGE → CORE` labelled "writer + readers". Re-reading the Mermaid source: the `"writer + readers"` label is actually on `STORAGE -->|"writer + readers"| DB` (line 99), not on `STORAGE --> CORE` (line 93). The latter is unlabelled, which is correct shorthand — the catalog records the dep as `EdgeConfidence` only (`crates/clarion-storage/src/query.rs:6`, `commands.rs:14`), and the diagram's prose at line 105 explicitly states "`storage` → `core` (one symbol, `EdgeConfidence`)". **PASS — no misleading label exists.**
-
-2. **`SoftFailed` "partial work kept" (Diagram 3).**
-   Verified at `crates/clarion-cli/src/analyze.rs:478–509`. The `SoftFailed` branch sends `WriterCmd::CommitRun { status: RunStatus::Failed, stats_json, … }` where `stats_json` includes `entities_inserted`, `edges_inserted`, etc. The writer-actor folds the `UPDATE runs SET status='failed'` into the open entity transaction (per the comment at line 479–482 and the catalog's storage section), so accepted entities from healthy plugins persist alongside the failure marker. The diagram's "partial work kept" caption is accurate. **PASS.**
-
-3. **ADR-007 5-tuple cache key (Diagram 4).**
-   Verified at `crates/clarion-mcp/src/lib.rs:1077–1083`. `SummaryCacheKey` is materialised with exactly the five fields shown: `(entity_id, content_hash, prompt_template_id, model_tier, guidance_fingerprint)`. `prompt_template_id` is set to `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, defined at `crates/clarion-core/src/llm_provider.rs:10` as `"leaf-v1"`. The diagram's annotation `LEAF_SUMMARY_PROMPT_TEMPLATE_ID = "leaf-v1"` matches. (The context-line citation `1010-1016` in the user's request actually points at `InferredEdgeCacheEntry`, not `SummaryCacheKey` — the diagram itself doesn't cite line numbers and shows the correct 5-tuple, so this is irrelevant to the diagram's correctness.) **PASS.**
-
-4. **Five validator steps, kill paths on 3 and 4 only (Diagram 5).**
-   Verified at `crates/clarion-core/src/plugin/host.rs:1031–1198`.
-   - Step 0 field-size (lines 1103–1107): `continue` only — drops record.
-   - Step 1 ontology declared-kind (1110–1114): `continue` only.
-   - Step 2 identity (1117–1133): `continue` only.
-   - Step 3 jail (1135–1164): `continue` on under-threshold escape; `return Err(HostError::PathEscapeBreakerTripped)` at line 1160 after `do_shutdown` — **kill path confirmed**.
-   - Step 4 entity cap (1166–1179): `return Err(HostError::EntityCapExceeded(e))` at line 1178 after `do_shutdown` — **kill path confirmed**.
-   Steps 0–2 have no `return Err` path; only `continue`. The diagram's claim "steps 3 and 4 are the only ones with kill paths" is exact. **PASS.**
-
-5. **60-second in-flight coalescer timeout (Diagram 4 caption).**
-   Verified at `crates/clarion-mcp/src/lib.rs:912` — `tokio::time::timeout(std::time::Duration::from_secs(60), rx.recv())` inside `coalesced_inferred_dispatch` (declared at line 894). The `inferred_inflight: HashMap<InferredEdgeCacheKey, broadcast::Sender<InferredDispatchOutcome>>` field is at lines 175–176. **PASS.**
-
-### Coverage check (PASS)
-
-| Catalog subsystem | Appears in |
-|---|---|
-| A `clarion-core` | Diagrams 2 (CORE), 3 (CORE), 5 (entire diagram) |
-| B `clarion-storage` | Diagrams 2 (STORAGE), 3 (WRITER + DB), 4 (READER, CACHE, WRITER) |
-| C `clarion-mcp` | Diagrams 2 (MCP), 4 (MCP) |
-| D `clarion-cli` | Diagrams 2 (CLI), 3 (CLI) |
-| E `clarion-plugin-fixture` | Diagram 2 (FIXTURE), Diagram 3 (as alternative to PLUGIN) |
-| F Python plugin | Diagrams 1 (PYRIGHT external + implicit), 2 (PYPLUGIN), 3 (PLUGIN) |
-
-Loom doctrine surfaces (Diagram 1): Filigree as solid `sibling`-styled box with "enrich-only" edge label; Wardline as solid sibling with a dashed "import probe at handshake (asterisk: loom.md §5)" edge — matches `docs/suite/loom.md` §5's named v0.1 asterisk treatment.
-
-Architecturally load-bearing concepts (all visible):
-- **ADR-007 5-tuple cache** — Diagram 4, explicit 5-tuple shown in `SELECT by 5-tuple` step.
-- **Edge-contract validator** — Diagram 3, `InsertEdge * N (enforce_edge_contract)` step.
-- **Writer-actor (ADR-011)** — Diagrams 2, 3, 4 (singleton WRITER participant in both sequences).
-- **Host validator pipeline** — Diagram 5 (entire diagram).
-
-### Notes (informational, non-blocking)
-
-1. **Diagram 3 plugin-loop step ordering is slightly idealised.** The diagram shows the `loop per file in plugin extensions` nested inside `loop per plugin`, with `host.shutdown / kill / reap` happening after the inner loop completes. In `clarion-cli/src/analyze.rs` the actual control flow uses a `BatchResult`-returning helper and per-plugin spawn-then-collect pattern; the diagram's nesting reads as a clean conceptual model rather than a literal call-graph. The diagram's caption doesn't claim line-fidelity, so this is acceptable shorthand for an L3 sequence.
-
-2. **Diagram 5 collapses edge/stats post-processing into terminal nodes.** Steps `EDGES` (process_edges, drop-only) and `STATS` (process_stats) are shown as siblings of the entity validator chain, attached to `OUTCOME` rather than to the accepted-entity exit. The host actually invokes `process_edges` and `process_stats` after the per-entity loop completes (`host.rs:1190–1191`). The diagram's edge layout is a fair simplification; the design-notes prose underneath ("same drop-on-violation discipline is applied to edges, but with no kill paths") sets expectations correctly.
-
----
-
-## Confidence Assessment
-
-**High.** All five substantive spot-checks resolved cleanly against source code at the cited locations. Coverage is complete. The diagrams are unusually well-aligned with the catalog and source — captions are accurate, none of the labels overstate what's shown, and the L1/L2/L3 + sequence breakdown is conventionally correct C4 usage.
-
-## Risk Assessment
-
-**Low.** No claims that would mislead a downstream consumer. The minor "notes" above are stylistic — the diagrams are read as conceptual models, not literal call traces, and their captions are consistent with that contract.
-
-## Information Gaps
-
-None blocking. The diagrams deliberately omit a `clarion-mcp::lib.rs` component view and a writer-`WriterCmd` zoom; both omissions are explicitly justified in the "Coverage notes" table at the end of the document and adequately substituted by catalog content.
-
-## Caveats
-
-- This validation checks structural and factual fidelity against the catalog and source spot-checks; it does not re-render the Mermaid blocks. The document attests the blocks were validated through the Mermaid renderer during authoring.
-- Architectural quality of the chosen abstractions (e.g. is a "Container" view the right level for `clarion-mcp`?) is out of scope for structural validation. Refer to `axiom-system-architect:architecture-critic` if such review is desired.
-
----
-
-**Final status: APPROVED** — proceed to next phase.
diff --git a/docs/arch-analysis-2026-05-18-1244/temp/validation-04-final-report.md b/docs/arch-analysis-2026-05-18-1244/temp/validation-04-final-report.md
deleted file mode 100644
index a14ef2ec..00000000
--- a/docs/arch-analysis-2026-05-18-1244/temp/validation-04-final-report.md
+++ /dev/null
@@ -1,116 +0,0 @@
-# Validation — `04-final-report.md`
-
-**Validator:** axiom-system-archaeologist:analysis-validator
-**Date:** 2026-05-18
-**Target:** `docs/arch-analysis-2026-05-18-1244/04-final-report.md`
-**Status:** **NEEDS_REVISION (warnings)** — structurally complete, all required sections present, internally consistent on priority mapping; multiple stale numeric facts at the §1 / §5 / §6 level that drifted between the catalog pass and the report write-up. None of the drifts invalidate the report's architectural conclusions, but the report explicitly bills itself as evidence-anchored, and the numbers cited in the executive summary and the deltas section must match the working tree.
-
----
-
-## Summary
-
-The report covers every contract-required section (executive summary; architecture at a glance; per-subsystem walkthrough for all 6 subsystems; cross-cutting concerns table; prioritised observations & risks; Sprint-2 deltas; recommended follow-ups; confidence + limitations + audit trail). Risk priorities in §5 and recommendation priorities in §7 are mapped one-to-one (3 High → items 1–3; 5 Medium → items 4–8; 8 Low → items 9–16). The §8 audit-trail file list matches the actual workspace contents (1 coordination + 1 discovery + 1 catalog + 1 diagrams + 1 report + 6 section-*.md + 2 validation-*.md). Cross-cutting concerns enumerate 14 entries grounded in ADR or doctrine citations.
-
-The report is fit for an architect handover at the level of structure, narrative, and prioritisation. The blocker is a cluster of stale numbers that the report inherited from the catalog pass and that drifted further before the report was written.
-
----
-
-## Findings
-
-### Critical
-
-None. No claim is contradicted by primary evidence in a way that changes a conclusion. The drifts below are warnings, not blockers.
-
-### Warnings
-
-**W-1. `lib.rs` LOC stale by ~90 lines.**
-Report §1 ("Standout strengths") and §2 ("Read surface") cite `clarion-mcp/src/lib.rs` at **2 623 LOC**. Working tree on `sprint-2/b8-scale-test` HEAD shows **2 712 LOC** (`wc -l crates/clarion-mcp/src/lib.rs`). The catalog footnoted the prior drift (2 620 → 2 623); two further commits on this branch (`7317a91` clippy-explicit Map; `87036b1` reservation-poison fix; `363bb0a` inferred-target pre-filter) appear to have pushed the file past 2 700 since the catalog pass. Recommend re-running `wc -l` against the working tree and updating §1, §2 table, §3.3, and §6 "drift from 2620 to 2623" parenthetical.
-
-**W-2. "11 commits ahead of `main`" is now 17.**
-Report header line 4 and §6 paragraph "Current branch (`sprint-2/b8-scale-test`) vs. `main`". Verified by `git rev-list --count main..HEAD` → **17**. The discovery doc (01) also says 11 — the figure was correct at the start of the analysis and stale by the time the report was written; four additional commits landed on the branch between discovery and report-writing: `caa6459` (B.8 raw artifacts), `f7bb63f` (CLAUDE.md refresh), `7317a91` (clippy), `87036b1` (poison fix), `363bb0a` (pre-filter inferred). Two of those (`87036b1`, `363bb0a`) are substantive MCP source-code changes that should plausibly join the §6 list of "substantive source changes" if the report wants to remain accurate at the commit level.
-
-**W-3. `git diff --stat main..HEAD` numbers are stale.**
-Report §6 reports "45 files changed, 23 209 insertions, 59 deletions". Verified `git diff --stat main..HEAD | tail -1` → **59 files changed, 25 650 insertions, 85 deletions**. Same root cause as W-2 — the same five commits landed after the figures were captured.
-
-**W-4. Spot-check M-1 line-number is wrong.**
-Report §5 M-1 cites `clarion-mcp/src/lib.rs:2381` as the location of `reference_neighbors`'s `conn.prepare(`. Verified: the only `conn.prepare(` site in the crate is at **line 2470**; the `reference_neighbors` fn itself begins at **line 2455**. The *claim* M-1 makes ("the only `conn.prepare(` site in the crate") is correct — only the line number is stale. The catalog also stated `reference_neighbors` is at "lib.rs:2363–2400" / "line 2378", which is also stale by the same +80 lines as W-1. Recommend either re-running grep at report-emit time or footnoting the line-number-as-of-commit. The Concern-level claim survives.
-
-**W-5. Sprint-2 deltas listing presented as 7 items but worth bullet count check.**
-Report §6 paragraph "Whole-of-Sprint-2" lists six bullets B.2–B.8 plus "OpenRouter swap" — actually seven bullets. The narrative claim above the bullets ("Six merged work-package landings since `v0.1-sprint-1`") undercounts by one. Either the narrative count is wrong (should be seven) or "OpenRouter swap" is being mentally excluded (in which case the list should say so explicitly). Trivial to fix.
-
-### Spot-check results
-
-| # | Claim | Source line | Result |
-|---|---|---|---|
-| 1 | §5 H-1: `analyze.rs:478–509` is the `SoftFailed` branch that folds `UPDATE runs SET status='failed'` into the open entity transaction | `crates/clarion-cli/src/analyze.rs:478–509` | **CONFIRMED** — `RunOutcome::SoftFailed { reason }` arm at 478, `CommitRun { status: RunStatus::Failed, ... }` at 499–501, `"CommitRun(Failed) — soft fail"` context at 508. |
-| 2 | §5 M-1: `clarion-mcp/src/lib.rs:2381` is the only `conn.prepare(` site in the crate | `grep -n 'conn.prepare(' crates/clarion-mcp/src/lib.rs` | **PARTIAL** — exactly one `conn.prepare(` site (claim survives); line number is **2470**, not 2381 (W-4). |
-| 3 | §4: ADR-031 added six CHECK clauses | `crates/clarion-storage/migrations/0001_initial_schema.sql` | **CONFIRMED** — `grep -cE 'CHECK\s*\(' ...sql` → **6**: `edges.confidence` (90), `findings.kind` (108), `findings.severity` (112), `findings.status` (125), `summary_cache.stale_semantic` (153), `runs.status` (201). |
-| 4 | §1: no god-files. The two largest source files are coherent, banded, internally documented; `host.rs` ~3 126 LOC, `lib.rs` ~2 623 LOC | `wc -l crates/clarion-core/src/plugin/host.rs crates/clarion-mcp/src/lib.rs` | **PARTIAL** — `host.rs` 3 126 ✓; `lib.rs` actually **2 712** (W-1). The "no god-files" architectural judgment is unaffected. |
-| 5 | §6: 11 commits ahead of main | `git rev-list --count main..HEAD` | **WRONG** — actually **17** (W-2). |
-| 6 | §1: 24 462 Rust LOC across 5 crates; 5 629 Python; 78 markdown docs | `find` + `wc -l` | **PARTIAL** — Rust now **24 727** (drift +265, same root cause as W-1/W-2); Python 5 629 ✓; markdown actually **91** files in `docs/` tree (`find docs -name '*.md' \| wc -l`). The "78 markdown docs" figure in §1 also disagrees with discovery doc 01 §1.1 which says "79 .md files" — the two source documents already disagreed before the report was written. |
-
-### Notes (non-blocking)
-
-**N-1. §3.3 "Three source files" claim.**
-"One Rust crate, three source files (`lib.rs` 2 623 + `config.rs` 352 + `filigree.rs` 238)" — correct count, stale LOC for `lib.rs` (W-1). Same drift, no extra issue.
-
-**N-2. §4 cross-cutting concerns: edge-ontology row labels three sites of duplication.**
-"Hard-coded in `clarion-storage::writer.rs:394–401`; declared in `plugin.toml:38`; documented in ADR — **3-place duplication, no cross-check**." Catalog §clarion-storage §Concerns (per the report's own internal reference) backs this. Not validated against `writer.rs` line numbers in this pass — flagged as a candidate spot-check for any deeper validation.
-
-**N-3. §8 audit-trail listing omits dot-prefix grep-friendliness but otherwise matches.**
-The listing labels `00-coordination.md` "coordination plan + execution log" — workspace `ls` confirms file exists. Sub-tree files (`temp/section-*.md`, `temp/validation-*.md`) all present.
-
-**N-4. §5.4 Doctrine-accepted risks (A-1 … A-4) are present and explicitly mark themselves "do not fix".**
-This is the right framing for the federation asterisks and the file-size acceptances; matches discovery doc §5 and catalog §clarion-core §A-3. Worth keeping.
-
-**N-5. Information gaps section (§8) is candid and matches the actual scope of the pass.**
-"Test coverage is not depth-read", "external siblings are not vendored", "B.8 result data not inspected" — all consistent with what the discovery and catalog passes actually did. Good limitation discipline.
-
-**N-6. Recommendations §7 ordering is risk-priority-first within tier and then by §5 letter.**
-Item 1 = H-1, item 16 = L-8. Consistent. No "high" recommendation without a matching §5 High; no §5 High without a matching item.
-
-**N-7. Coverage check: every subsystem in the catalog has a §3 subsection in the report.**
-A (`clarion-core`) → §3.1; B (`clarion-storage`) → §3.2; C (`clarion-mcp`) → §3.3; D (`clarion-cli`) → §3.4; E (`clarion-plugin-fixture`) → §3.5; F (`plugins/python`) → §3.6. No subsystem from the catalog is silently omitted. Every catalog "Concerns" entry (read at the heading level) is folded into §5 either as a numbered risk or as one of the doctrine-accepted A-* items.
-
-**N-8. No silent omission of cross-cutting concerns from discovery / catalog.**
-The 14-row table in §4 covers entity-ID, JSON-RPC L4, plugin authority, ontology ownership, edge confidence, edge ontology, ontology semver, summary cache key, migration governance, schema-validation policy, federation axiom, Filigree bindings, summary scope, tooling baseline. Discovery §5 has 8 concerns — all 8 are in §4. Catalog cross-references are honoured.
-
----
-
-## Confidence Assessment
-
-- **Structural compliance:** High — every contract-required section is present in the correct order, properly cross-referenced to source artifacts.
-- **Internal consistency:** High — risk-priority ↔ recommendation-priority mapping is one-to-one and complete.
-- **Cross-document coverage:** High — every subsystem in the catalog has a walkthrough entry; every catalog concern entry maps to a §5 risk or §5.4 acceptance.
-- **Numerical accuracy:** Medium — 5 of 6 spot-checks revealed stale figures inherited from the catalog or drifted further before report emit. The drifts are all "snapshot in motion" artefacts (LOC, commit count, diff stats) rather than misreadings of source.
-- **Conclusion durability:** High — none of the stale numbers, if corrected, would change a §5 priority assignment or a §7 recommendation.
-
-## Risk Assessment
-
-- **Risk that downstream readers cite stale figures:** Medium. The report is explicitly the synthesis layer; a Sprint-3 plan citing "11 commits ahead", "lib.rs 2 623 LOC", or "45 files changed" will be wrong on day one of execution.
-- **Risk that the file-size acceptance (A-4) shifts:** Low-Medium. The catalog argued `lib.rs` at 2 620 is coherent; at 2 712 the same argument still holds, but the file is on a measurable growth trajectory (+92 LOC across five commits on this branch alone). If §5.4 A-4 is to remain "do not fix", a "monitored, not accepted indefinitely" footnote would help.
-
-## Information Gaps
-
-- The report's "audit trail" §8 lists `temp/` contents in shape but does not record a hash or modification time. If the report is consumed weeks later, the validator artefacts may have drifted again.
-- Several catalog line-number citations (e.g. `writer.rs:394–401` for `STRUCTURAL_EDGE_KINDS`, `lib.rs:1010–1016` for the 5-tuple cache key, `lib.rs:1180–1316` for `BudgetLedger.blocked`) were not independently re-verified in this validation pass — they may be subject to the same drift as W-1/W-4.
-- The §6 narrative "Six merged work-package landings" / actually seven bullets discrepancy (W-5) suggests the deltas section was edited under time pressure.
-
-## Caveats
-
-- This is a structural-compliance validation, not a technical-accuracy validation. The architectural judgments in the report (e.g. "boundary discipline is real", "plugin separation is a process boundary not a trait abstraction", "no god-files") were not independently re-derived — they were checked for internal coherence with discovery and catalog, not against the source code as a quality assessment. A technical critique should go through `axiom-system-architect:assess-architecture` as the report itself notes.
-- The line-number / LOC drift findings are inherently snapshot-bound; any document of this kind written against a live working tree carries the same risk. Recommend the analysis workspace pin a commit hash in each document's header so future readers can re-execute the spot-checks deterministically.
-
----
-
-## Recommendation
-
-**Status: NEEDS_REVISION (warnings).** Five low-effort edits unblock APPROVED:
-
-1. Re-run `wc -l crates/clarion-mcp/src/lib.rs` and update §1 (Standout strengths), §2 (Read surface table), §3.3 (first sentence), §6 ("from 2620 to 2623" parenthetical).
-2. Re-run `git rev-list --count main..HEAD` and update the header line 4 and §6 first sentence of the "Current branch" paragraph.
-3. Re-run `git diff --stat main..HEAD | tail -1` and update §6 "45 files changed, 23 209 insertions, 59 deletions".
-4. Re-grep `conn.prepare(` and update the §5 M-1 line number (currently `:2381`, should be `:2470`).
-5. Reconcile "Six merged work-package landings" with the seven bullets that follow — either say "Seven" or split the OpenRouter swap out of the merged-WP list explicitly.
-
-Pin a commit hash in the report header (e.g. `Commit: 363bb0a`) so future readers can re-derive every numeric claim deterministically. Then re-validate — expected pass.
diff --git a/docs/arch-analysis-2026-05-22-1924/00-coordination.md b/docs/arch-analysis-2026-05-22-1924/00-coordination.md
new file mode 100644
index 00000000..bbade7e0
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/00-coordination.md
@@ -0,0 +1,38 @@
+# Coordination Plan — Clarion Architecture Analysis
+
+**Workspace:** `docs/arch-analysis-2026-05-22-1924/`
+**Date:** 2026-05-22
+**Operator:** Claude (system-archaeologist skill)
+**Source instruction:** "Full from-scratch analysis, do not read existing documentation."
+
+## Analysis Configuration
+
+- **Scope:** Entire repo source tree — `crates/` (Rust workspace) and `plugins/python/` (Python plugin). Excludes `target/`, `.venv/`, `.git/`, caches.
+- **Deliverables (Option A — Full Analysis):**
+  - `01-discovery-findings.md` — holistic assessment
+  - `02-subsystem-catalog.md` — per-subsystem entries
+  - `03-diagrams.md` — C4 architecture diagrams
+  - `04-final-report.md` — synthesized executive narrative
+- **Strategy:** PARALLEL per-subsystem explorers, then sequential validation + diagrams + report.
+  - Rationale: 7 candidate subsystems are loosely coupled (separate crates + a plugin), well-suited to independent exploration.
+- **Tier:** Standard (not ultralarge). LOC ~50K, file count ~85 source files, subsystems = 7.
+- **Constraint:** **Do not consult existing design docs** (`docs/clarion/**`, `docs/suite/**`, ADRs, sprint READMEs, CLAUDE.md design content). Findings must derive from code only. CLAUDE.md operational sections (tooling, build commands) remain in-scope as orientation; design narrative there is treated as "existing documentation" and avoided.
+- **Complexity:** Medium. Plugin host / RPC transport / federation HTTP API are non-trivial; storage actor model and entity-ID assembly need careful inspection.
+
+## Subsystem Partition (initial candidates)
+
+1. **clarion-core** — Plugin host, transport, manifest, jail/limits, breaker, entity-ID assembler, LLM provider.
+2. **clarion-storage** — Writer-actor + reader-pool over SQLite (schema, pragma, query, cache, unresolved).
+3. **clarion-cli** — `clarion` binary (`install`, `analyze`, `serve`, `secret-scan`), clustering, HTTP read API, run lifecycle, stats.
+4. **clarion-mcp** — MCP server façade (filigree client, config).
+5. **clarion-scanner** — Secret/entropy/pattern scanner with baseline support.
+6. **clarion-plugin-fixture** — Test fixture plugin (also a reference impl of the protocol).
+7. **plugins/python** — Python language plugin (function/class entity extraction, qualname, Wardline probe).
+
+## Execution Log
+
+- 2026-05-22 19:24 — Created workspace `docs/arch-analysis-2026-05-22-1924/`.
+- 2026-05-22 19:24 — Scale check: 6 crates (~44K Rust LOC), Python plugin (~6.5K LOC), 121 md files. Standard tier confirmed.
+- 2026-05-22 19:25 — User selected **Option A — Full Analysis**.
+- 2026-05-22 19:25 — Wrote this coordination plan. Strategy: PARALLEL per-subsystem explorers.
+- Next: holistic discovery sweep (entry points, build graph, dependency edges) → `01-discovery-findings.md`.
diff --git a/docs/arch-analysis-2026-05-22-1924/01-discovery-findings.md b/docs/arch-analysis-2026-05-22-1924/01-discovery-findings.md
new file mode 100644
index 00000000..a0f3c857
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/01-discovery-findings.md
@@ -0,0 +1,586 @@
+# 01 — Discovery Findings (Clarion)
+
+> Methodology note: produced from source (Rust + Python), `Cargo.toml`,
+> `plugin.toml`, `pyproject.toml`, `clarion.yaml`, `.mcp.json`, migration SQL,
+> e2e shell scripts, and per-crate test files only. No design docs, ADRs, or
+> sprint/WP narrative were read while writing this document.
+
+## 1. One-Paragraph Pitch (Inferred From Code)
+
+Clarion is a Rust-implemented code-archaeology toolchain: a `clarion`
+binary (`crates/clarion-cli/src/main.rs`) that (a) installs a per-project
+`.clarion/clarion.db` SQLite store with embedded migrations
+(`install.rs` + `crates/clarion-storage/migrations/0001_initial_schema.sql`),
+(b) walks a source tree, discovers `clarion-plugin-*` executables on `$PATH`,
+spawns each as a JSON-RPC subprocess, ingests entities/edges they extract, and
+persists them through a writer-actor (`analyze.rs`, `clarion-storage/writer.rs`),
+and (c) `clarion serve` runs as a stdio MCP server exposing **19**
+agent-facing tools (`crates/clarion-mcp/src/lib.rs::list_tools`; original
+discovery said "twenty" — corrected during validation against the actual
+`ToolDefinition` registry; see §4 of `02-subsystem-catalog.md`) plus an Axum
+HTTP read API on `/api/v1/files*` (`crates/clarion-cli/src/http_read.rs:347`).
+Out-of-tree language plugins follow the protocol defined in
+`crates/clarion-core/src/plugin/protocol.rs`; the in-repo reference plugin
+(`plugins/python/`) extracts module/class/function entities plus
+`contains`/`calls`/`references`/`imports` edges using a `pyright` language-server
+session for type-resolved call/reference targets. Audience is consult-mode
+LLM agents and developers needing structured navigation of a codebase.
+
+## 2. Repository Layout
+
+```
+clarion/
+├── Cargo.toml                       Rust workspace, resolver "3", 6 members
+├── clarion.yaml                     User-edited runtime config (LLM, integrations, serve.http)
+├── .mcp.json                        Registers clarion + filigree as stdio MCP servers
+├── rust-toolchain.toml              channel = stable, profile = minimal
+├── crates/
+│   ├── clarion-core/      ~11.7k LOC src,  325 LOC tests  — domain types, plugin host
+│   ├── clarion-storage/   ~3.2k  LOC src, 4.86k LOC tests — SQLite layer, writer-actor
+│   ├── clarion-cli/       ~6.8k  LOC src, 6.4k  LOC tests — `clarion` binary
+│   ├── clarion-mcp/       ~6.6k  LOC src, 2.2k  LOC tests — MCP protocol surface
+│   ├── clarion-scanner/   ~880   LOC src, 655   LOC tests — pre-ingest secret scanner
+│   └── clarion-plugin-fixture/ 187 LOC    — test-only Rust plugin
+├── plugins/python/
+│   ├── plugin.toml                  Plugin manifest (plugin_id=python, ontology v0.6.0)
+│   ├── pyproject.toml               name=clarion-plugin-python, requires-python>=3.11
+│   ├── src/clarion_plugin_python/   3028 LOC across 11 modules
+│   └── tests/                       9 pytest files, 3440 LOC
+├── fixtures/entity_id.json          Cross-language byte-for-byte parity fixture
+├── tests/
+│   ├── e2e/                         4 bash scripts (sprint_1, sprint_2_mcp, phase3, wp5_secret_scan)
+│   └── perf/                        b8_scale_test driver + elspeth_mini corpus (~150 Python files)
+├── scripts/                         CI helpers (b4 gate, governance, migration retirement, version lockstep)
+├── .pre-commit-config.yaml          ruff, ruff-format, mypy --strict for plugins/python
+└── .github/workflows/               ci.yml + release.yml
+```
+
+Total Rust source: ~29k LOC across 6 crates (largest single files:
+`clarion-mcp/src/lib.rs` 4703, `clarion-core/src/plugin/host.rs` 2935,
+`clarion-cli/src/analyze.rs` 2549, `clarion-core/src/llm_provider.rs` 2467).
+Total Python source: 3028 LOC, dominated by `pyright_session.py` 1406 and
+`extractor.py` 932.
+
+## 3. Technology Stack
+
+- **Languages:**
+  - Rust: edition `2024`, MSRV `1.88`, toolchain channel `stable`
+    (`Cargo.toml:17`, `rust-toolchain.toml`).
+  - Python: `>=3.11` (`plugins/python/pyproject.toml:10`); ruff target
+    `py311`; mypy `python_version = "3.11"` with `strict = true`.
+
+- **Rust dependencies (key, from root `Cargo.toml` workspace.dependencies):**
+  - `tokio` 1 — multi-thread runtime + sync primitives (`rt-multi-thread`,
+    `macros`, `net`, `sync`, `time`).
+  - `rusqlite` 0.31 with `bundled` SQLite — embedded DB engine.
+  - `deadpool-sqlite` 0.8 (`rt_tokio_1`) — async reader pool.
+  - `axum` 0.7 + `tower` 0.5 + `tower-http` 0.6 — HTTP read API.
+  - `reqwest` 0.12 with `rustls-tls-native-roots`, `blocking`, `json` —
+    outbound HTTP (Filigree, OpenRouter).
+  - `clap` 4 (`derive`) — CLI parser.
+  - `serde`/`serde_json`/`serde_norway` (YAML) — config + wire formats.
+  - `tracing` + `tracing-subscriber` (`env-filter`) — structured logs.
+  - `thiserror` + `anyhow` — typed library errors / binary errors.
+  - `blake3`, `sha1`, `sha2` — content/secret hashing.
+  - `xgraph` 2.0.0 — used by `clarion-cli/src/clustering.rs` for Leiden
+    community detection (`xgraph::graph::algorithms::leiden_clustering`).
+  - `regex` 1, `ignore` 0.4 — secret-scanner patterns and file walking.
+  - `nix` 0.28 (`resource`) — `setrlimit(2)` for plugin sandboxing.
+  - `which` 6 — locate plugins on `$PATH`.
+  - `cargo-deny` policy file (`deny.toml`) checked in CI.
+
+- **Python dependencies (`plugins/python/pyproject.toml`):**
+  - Runtime: `packaging>=24`, `pyright==1.1.409` (pinned exact for the
+    type-resolved call/reference probe).
+  - Dev: `pytest>=8.0`, `pytest-cov>=5.0`, `ruff>=0.6`, `mypy>=1.11`,
+    `pre-commit>=3.8`.
+
+- **External processes / services:**
+  - **SQLite** — single file at `.clarion/clarion.db`; WAL mode forced by
+    `crates/clarion-storage/src/pragma.rs:17`; one migration `0001_initial_schema.sql`.
+  - **Plugin subprocesses** — spawned by `PluginHost::spawn` over
+    stdin/stdout JSON-RPC (`crates/clarion-core/src/plugin/host.rs`),
+    discovered by `discover()` scanning `$PATH` for `clarion-plugin-*`
+    (`crates/clarion-core/src/plugin/discovery.rs`).
+  - **pyright language server** — invoked as a subprocess by the Python
+    plugin (`plugins/python/src/clarion_plugin_python/pyright_session.py:7-9`
+    imports `select`, `subprocess`).
+  - **MCP stdio transport** — `clarion serve` exposes JSON-RPC 2.0 over
+    stdin/stdout with `protocolVersion = "2025-11-25"`
+    (`crates/clarion-mcp/src/lib.rs:40`); reads Content-Length frames via
+    `clarion_core::plugin::transport`.
+  - **HTTP read API** — bound by `serve.http.bind` (default `127.0.0.1:9111`
+    per `clarion.yaml`); Axum router at `http_read.rs:347-369` with
+    `ConcurrencyLimitLayer(64)` + 10s timeout + `LoadShedLayer` +
+    `CatchPanicLayer` + body-size limit. Six routes total.
+  - **Filigree** — outbound HTTP via `reqwest` in
+    `crates/clarion-mcp/src/filigree.rs`; reads entity-association reverse
+    lookups; transport sibling, not vendored.
+  - **LLM providers** — pluggable via `clarion-core/src/llm_provider.rs`:
+    `OpenRouterProvider` (HTTPS to `openrouter.ai/api/v1`),
+    `CodexCliProvider` and `ClaudeCliProvider` (subprocess execution of
+    `codex` / `claude` binaries), `RecordingProvider` (fixture replay).
+  - **Wardline** — Python-side import probe only
+    (`plugins/python/src/clarion_plugin_python/wardline_probe.py`):
+    `importlib.import_module("wardline.core.registry")`, version-pin
+    check against `[1.0.0, 2.0.0)` declared in `plugin.toml:54-56`.
+
+- **Build/test tooling:**
+  - **Pre-commit** (`.pre-commit-config.yaml`): ruff fix, ruff-format,
+    mypy `--strict` on `plugins/python/{src,tests}`.
+  - **Workspace lints** (`Cargo.toml:19-30`): `unsafe_code = "deny"`,
+    clippy `pedantic = "warn"`, with three pragmatic allows.
+  - **cargo-deny** policy at `deny.toml`.
+  - **GitHub Actions** at `.github/workflows/{ci,release}.yml` (not read for
+    contents, only existence).
+  - **Scripts** under `scripts/`: `check-workspace-version-lockstep.py`,
+    `check-python-ontology-version.py`, `check-migration-retirement.py`,
+    `check-github-release-governance.py`, `b4-gate-run.sh`.
+
+## 4. Entry Points
+
+- **`clarion` binary** — `crates/clarion-cli/src/main.rs`; `clap` parser at
+  `src/cli.rs:7`. Three subcommands:
+  - `Install { force, path }` → `install::run(&path, force)`
+    (`install.rs:1-50`) creates `.clarion/clarion.db`, `.clarion/config.json`,
+    `.clarion/.gitignore`, and `<path>/clarion.yaml`.
+  - `Analyze { path, config, allow_unredacted_secrets, … }` → runs on a
+    multi-thread tokio runtime, performs `secret_scan` gate, then
+    `analyze::run_with_options` (`analyze.rs:70`+).
+  - `Serve { path, config }` → `serve::run(&path, config.as_deref())`
+    (`serve.rs:20`).
+- **`clarion serve`** is the MCP server. It supervises *two* concurrent
+  servers in one process: an stdio JSON-RPC loop on a dedicated thread with
+  a per-thread current-thread tokio runtime
+  (`serve.rs:96-110, 126-130`), and the optional Axum HTTP read server on a
+  second thread (`serve.rs:55-71, http_read.rs::spawn`). Both share one
+  `ReaderPool`; identity is asserted via `Arc::ptr_eq` (`serve.rs:63-71`).
+- **`clarion-plugin-fixture`** — `crates/clarion-plugin-fixture/src/main.rs`;
+  test-only binary that speaks the JSON-RPC plugin protocol, returns one
+  hard-coded `fixture:widget:demo.sample` entity per `analyze_file`, and
+  honours an `CLARION_FIXTURE_EXCEED_RLIMIT_AS` env hook to provoke OOM
+  paths (`main.rs:78, 137-178`).
+- **Python plugin** — console script `clarion-plugin-python` defined in
+  `pyproject.toml:33`; `clarion_plugin_python.__main__:main` (15 LOC at
+  `__main__.py`) installs `stdout_guard` and delegates to
+  `clarion_plugin_python.server.main` (`server.py` 296 LOC). Plugin manifest
+  ships via wheel `shared-data` to `share/clarion/plugins/python/plugin.toml`
+  (`pyproject.toml:38-44`) for the host's install-prefix discovery fallback.
+- **Library entry** — `crates/clarion-core/src/lib.rs` re-exports a facade of
+  domain types (`EntityId`, `Manifest`, `PluginHost`, `LlmProvider`,
+  `LeafSummaryPromptInput`, etc.) per its module-doc "Re-export policy".
+- **Storage library entry** — `crates/clarion-storage/src/lib.rs` exposes
+  `Writer`, `ReaderPool`, the `WriterCmd` enum, cache helpers, and twenty-odd
+  query functions.
+
+## 5. Public Wire Surfaces
+
+1. **Plugin JSON-RPC 2.0 protocol** (stdin/stdout per plugin subprocess).
+   - Defined in `crates/clarion-core/src/plugin/protocol.rs` (875 LOC) +
+     `transport.rs` (LSP-style `Content-Length: N\r\n\r\n<body>` framing).
+   - Five methods: `initialize`, `initialized` (notification),
+     `analyze_file`, `shutdown`, `exit` (notification).
+   - `analyze_file` returns `{entities: [...], edges: [...], stats: {…}}`;
+     entity shape carries `id, kind, qualified_name, source.{file_path,
+     source_range, …}`; edges carry `kind, src_id, dst_id, confidence,
+     properties` plus `unresolved_call_sites` for query-time inference.
+   - Frame ceiling: `ContentLengthCeiling::DEFAULT` = 8 MiB
+     (`limits.rs` per the ADR-021 §2b comment, also mirrored on the
+     plugin side in `plugins/python/.../server.py:48`).
+   - `initialize` returns
+     `{name, version, ontology_version, capabilities}`; the host validates
+     the returned ontology against `manifest.ontology.entity_kinds /
+     edge_kinds` (host.rs module docs §Enforcement pipeline step 1).
+
+2. **MCP stdio JSON-RPC server** (`clarion serve`).
+   - Same `Content-Length` framing (`clarion-mcp/src/lib.rs` imports
+     `clarion_core::plugin::{ContentLengthCeiling, Frame, TransportError}`).
+   - `MCP_PROTOCOL_VERSION = "2025-11-25"` (`lib.rs:40`).
+   - **19 tools** registered in `list_tools()` (`lib.rs:56-294` — corrected from this doc's initial "20"; see §4 of `02-subsystem-catalog.md` for the enumerated registry):
+     `entity_at`, `project_status`, `analyze_start`, `analyze_status`,
+     `analyze_cancel`, `find_entity`, `source_for_entity`, `entity_context`,
+     `call_sites`, `callers_of`, `execution_paths_from`,
+     `execution_paths_ranked`, `summary`, `summary_preview_cost`,
+     `issues_for`, `orientation_pack`, `index_diff`, `neighborhood`,
+     `subsystem_members`, plus one I have not independently counted past
+     line 254 (claimed `grep -c 'ToolDefinition {'` = 20).
+   - Backed by `ServerState` (built in `serve.rs:131`) holding a
+     `ReaderPool`, optional summary-LLM `Writer` + `LlmProvider`, optional
+     `FiligreeHttpClient`.
+
+3. **HTTP read API** — Axum router in
+   `crates/clarion-cli/src/http_read.rs:347-369`. Six routes:
+   - `GET  /api/v1/files`          → `get_file` (line 670)
+   - `POST /api/v1/files:resolve`  → `post_files_resolve` (line 887)
+   - `POST /api/v1/files/batch`    → `post_files_batch` (line 815)
+   - `GET  /api/v1/_capabilities`  → `get_capabilities` (line 1005;
+     unprotected — outside the bearer middleware)
+   - Plus two test-only routes inside `#[cfg(test)]` modules (`/x`, `/boom`)
+     that are not part of the public surface.
+   - Bearer-token middleware on the `protected` group
+     (`http_read.rs:376 require_http_identity`); HMAC variant exists
+     (`require_hmac_identity` line 405). Tower stack: `CatchPanic` →
+     `HandleError` → 10s `TimeoutLayer` → `RequestBodyLimitLayer` →
+     `LoadShedLayer` → `ConcurrencyLimitLayer(64)`.
+
+4. **CLI** — `crates/clarion-cli/src/cli.rs` (64 LOC). `clap` derive macros.
+   Flags of note on `analyze`: `--allow-unredacted-secrets` (requires
+   `--confirm-allow-unredacted-secrets <TOKEN>` non-interactively),
+   `--allow-no-plugins` for dry runs.
+
+5. **Outbound HTTP — Filigree reverse-association lookup.**
+   `crates/clarion-mcp/src/filigree.rs::FiligreeHttpClient` (`reqwest`
+   blocking) calls Filigree's HTTP API for entity-association reverse
+   lookup; request shape decoded into `EntityAssociationsResponse`
+   (`filigree.rs:11-22`). Auth via `token_env` (`clarion.yaml:integrations.
+   filigree.token_env`).
+
+6. **Outbound HTTP — OpenRouter LLM** in `clarion-core/src/llm_provider.rs`
+   (`OpenRouterProvider`); URL/attribution from `clarion.yaml:llm_policy.openrouter`.
+
+7. **Subprocess providers** — `CodexCliProvider`, `ClaudeCliProvider` in the
+   same file run external `codex` / `claude` binaries with stdin-piped
+   prompts and structured output.
+
+## 6. Candidate Subsystems
+
+### clarion-core — `crates/clarion-core/`
+- **LOC:** ~11669 src across 13 `.rs` files; 325 LOC integration test.
+- **Source files (one-line roles):**
+  - `src/lib.rs` (50) — facade re-exports per the documented "Re-export policy".
+  - `src/entity_id.rs` (596) — 3-segment ID assembler + grammar (ADR-003/022 per code comment).
+  - `src/llm_provider.rs` (2467) — `LlmProvider` trait, `OpenRouterProvider`, `CodexCliProvider`, `ClaudeCliProvider`, `RecordingProvider`, prompt builders, `CachingModel`.
+  - `src/plugin/mod.rs` (52) — submodule wiring.
+  - `src/plugin/protocol.rs` (875) — JSON-RPC envelopes + typed params/results.
+  - `src/plugin/transport.rs` (569) — Content-Length framing.
+  - `src/plugin/manifest.rs` (1119) — `plugin.toml` parser + validator.
+  - `src/plugin/discovery.rs` (667) — `$PATH` scan + manifest lookup.
+  - `src/plugin/host.rs` (2935) — supervisor, ontology/identity/jail/cap pipeline.
+  - `src/plugin/host_findings.rs` (NOT measured separately) — finding subcodes.
+  - `src/plugin/jail.rs` (~) — path-jail (`canonicalize` + `starts_with`).
+  - `src/plugin/limits.rs` (572) — Content-Length / entity-cap / path-escape breakers + `RLIMIT_AS`/`RLIMIT_NOFILE`/`RLIMIT_NPROC` via `nix`.
+  - `src/plugin/breaker.rs` (360) — crash-loop breaker (>3 crashes / 60s).
+  - `src/plugin/mock.rs` (876) — `#[cfg(test)]` mock plugin for host unit tests.
+- **Outbound deps:** `serde`, `serde_json`, `tempfile`, `thiserror`, `toml`, `tracing`, `nix`, `which`, `reqwest` (LLM HTTP). No internal Clarion crate deps.
+
+### clarion-storage — `crates/clarion-storage/`
+- **LOC:** ~3218 src; 4858 LOC tests.
+- **Source files:**
+  - `src/lib.rs` (43) — re-exports.
+  - `src/writer.rs` (1074) — `Writer` actor, `mpsc::Sender<WriterCmd>` API, batch commits (`DEFAULT_BATCH_SIZE = 50`), `commits_observed` counter (`Arc<AtomicUsize>` per writer.rs:50 docs).
+  - `src/reader.rs` — `ReaderPool` via `deadpool-sqlite`.
+  - `src/query.rs` (1160) — read-side query helpers: `call_edges_from`, `subsystem_members`, `entity_at_line`, `find_entities`, `resolve_file_catalog_entry`, etc.
+  - `src/schema.rs` — migration runner; embedded `0001_initial_schema.sql` (293 LOC SQL).
+  - `src/pragma.rs` — WAL+`synchronous=NORMAL`+`busy_timeout=5000`+`wal_autocheckpoint=1000`+`foreign_keys=ON` PRAGMAs.
+  - `src/commands.rs` — `WriterCmd` enum (`EntityRecord`, `EdgeRecord`, `FindingRecord`, `InferredCallEdgeRecord`, `RunStatus`).
+  - `src/cache.rs` — LLM `SummaryCache`/`InferredEdgeCache` helpers.
+  - `src/unresolved.rs` — `UnresolvedCallSiteRecord` + replace-by-caller.
+  - `src/error.rs` — `StorageError`.
+- **Outbound deps:** `clarion-core` (path dep), `rusqlite`, `deadpool-sqlite`, `tokio`, `serde`, `serde_json`, `blake3`, `tracing`, `thiserror`.
+
+### clarion-cli — `crates/clarion-cli/`
+- **LOC:** ~6790 src; 6394 LOC tests (5 test files + `wp1_e2e.rs` + `wp2_e2e.rs`).
+- **Source files:**
+  - `src/main.rs` (78) — binary entry, runtime construction, .env hygiene exclusion for `analyze`.
+  - `src/cli.rs` (64) — clap definitions.
+  - `src/install.rs` — `.clarion/` initialiser + `clarion.yaml` stub.
+  - `src/analyze.rs` (2549) — analyze pipeline: discovery → spawn → walk → `analyze_file` per file → writer commands → clustering.
+  - `src/serve.rs` (326) — `clarion serve` orchestrator (stdio MCP thread + HTTP thread).
+  - `src/http_read.rs` (1532) — Axum HTTP read API, bearer + HMAC middleware, tower stack.
+  - `src/clustering.rs` (510) — Leiden / weighted-components clustering over `xgraph::Graph`.
+  - `src/config.rs` — `AnalyzeConfig` / `ClusteringConfig` YAML loader.
+  - `src/instance.rs` — `InstanceId` UUID newtype, persisted to `.clarion/instance_id`.
+  - `src/run_lifecycle.rs` — `runs` row lifecycle: `recover_preexisting_running_runs`, `begin_run`.
+  - `src/secret_scan.rs` + `src/secret_scan/{anchors,baseline,files,findings}.rs` — pre-ingest secret-scan gate wrapping `clarion-scanner`.
+  - `src/stats.rs` — `P95Accumulator` and stat helpers.
+- **Outbound deps:** `clarion-core`, `clarion-mcp`, `clarion-scanner`, `clarion-storage` (all path deps); `anyhow`, `axum`, `blake3`, `clap`, `dotenvy`, `ignore`, `rusqlite`, `serde`, `serde_json`, `serde_norway`, `sha2`, `time`, `tokio`, `tower`, `tower-http`, `tracing`, `tracing-subscriber`, `uuid`, `xgraph`. Dev-only: `clarion-plugin-fixture`, `assert_cmd`, `tempfile`, `sha1`.
+
+### clarion-mcp — `crates/clarion-mcp/`
+- **LOC:** ~6595 src across 3 files; 2233 LOC integration test.
+- **Source files:**
+  - `src/lib.rs` (4703) — `ToolDefinition` list, `ServerState`, JSON-RPC dispatch (`handle_json_rpc`, `handle_tool_call`), stdio loop (`serve_stdio*`), in-process analyze supervisor for `analyze_{start,status,cancel}`.
+  - `src/config.rs` (1600) — `McpConfig` YAML loader; LLM/Filigree/serve.http config; provider selection; validation rules (deprecated-provider rejection, Filigree port-conflict, etc.).
+  - `src/filigree.rs` — `FiligreeHttpClient` + reverse-association lookup with `FiligreeLookup` trait; `reqwest::blocking`.
+- **Outbound deps:** `clarion-core`, `clarion-storage` (path deps); `blake3`, `reqwest`, `rusqlite`, `serde`, `serde_json`, `serde_norway`, `thiserror`, `time`, `tokio`, `tracing`.
+
+### clarion-scanner — `crates/clarion-scanner/`
+- **LOC:** ~881 src across 4 files; 655 LOC tests.
+- **Source files:**
+  - `src/lib.rs` — `Detection`, `SecretCategory`, `HashedSecret` (detect-secrets-compatible SHA-1).
+  - `src/patterns.rs` — `Scanner`, `PatternMeta` regex catalogue.
+  - `src/entropy.rs` — `EntropyTuning`, high-entropy filter.
+  - `src/baseline.rs` — `Baseline`, `BaselineEntry`, `SuppressionResult`, `load_baseline`.
+- **Outbound deps:** `regex`, `serde`, `serde_norway`, `sha1`, `thiserror`. **No internal Clarion deps** — this is a pure scanner library.
+
+### clarion-plugin-fixture — `crates/clarion-plugin-fixture/`
+- **LOC:** 187 across 2 files.
+- **Source files:**
+  - `src/main.rs` (185) — minimal JSON-RPC plugin: returns one `fixture:widget:demo.sample` entity per `analyze_file`; honours `CLARION_FIXTURE_EXCEED_RLIMIT_AS` env var to exercise the host's `RLIMIT_AS` OOM-kill path via `nix::sys::mman::mmap_anonymous` (the only `unsafe` block in the crate).
+  - `src/lib.rs` — trivial.
+- **Outbound deps:** `clarion-core` (path); `serde_json`; `nix` (unix-only, with `mman`, `signal` features).
+
+### plugins/python — `plugins/python/`
+- **LOC:** 3028 src across 11 modules; 3440 LOC tests across 9 files.
+- **Source files (`src/clarion_plugin_python/`):**
+  - `__init__.py` (3) — package metadata.
+  - `__main__.py` (15) — entry point, installs `stdout_guard` then calls `server.main()`.
+  - `server.py` (296) — JSON-RPC server loop, dispatch for `initialize`/`initialized`/`analyze_file`/`shutdown`/`exit`; constants `ONTOLOGY_VERSION = "0.6.0"`, `MAX_CONTENT_LENGTH = 8 MiB`, `MAX_FILES_PER_PYRIGHT_SESSION = 25`.
+  - `extractor.py` (932) — AST walker emitting module/class/function entities plus `imports`/`calls`/`references` candidate edges.
+  - `pyright_session.py` (1406) — wraps `pyright-langserver` over `subprocess` + `select`; type-resolved call & reference resolution.
+  - `call_resolver.py` (65) — `CallResolutionResult`, `CallsRawEdge`, `Finding`, `UnresolvedCallSite` dataclasses.
+  - `reference_resolver.py` (70) — `ReferenceResolutionResult`, `ReferenceSite`.
+  - `entity_id.py` (75) — Python-side mirror of the 3-segment ID assembler.
+  - `qualname.py` (48) — L7 qualname reconstruction (dotted module + `__qualname__`).
+  - `stdout_guard.py` (62) — replaces `sys.stdout` so accidental writes don't corrupt JSON-RPC frames (called from `__main__.py`).
+  - `wardline_probe.py` (56) — fail-soft `importlib` probe for `wardline.core.registry` + version-pin gate against `[1.0.0, 2.0.0)`.
+- **Outbound deps (runtime):** `packaging>=24`, `pyright==1.1.409`. **No HTTP, no network at all in the plugin process.**
+
+## 7. Cross-Cutting Concerns Observed
+
+- **Error handling:**
+  - Library crates use `thiserror` for typed error enums
+    (`clarion-storage/src/error.rs`, `clarion-mcp/src/filigree.rs:31-50`,
+    `clarion-core/src/plugin/limits.rs::BreakerState`, etc.).
+  - Binary code uses `anyhow` for top-level error propagation
+    (`crates/clarion-cli/src/main.rs:13`,
+    `crates/clarion-cli/src/serve.rs:8`).
+  - The `runs` table has a `recover_preexisting_running_runs` step
+    (`run_lifecycle.rs:5-28`) that marks any leftover `status='running'`
+    rows as `failed` on next start — explicit crash-recovery discipline.
+
+- **Logging / tracing:** `tracing` + `tracing-subscriber` with
+  `EnvFilter::try_from_default_env()`; defaults to `info` if no `RUST_LOG`
+  (`main.rs:73`). HTTP read API installs a *separate* `Dispatch` writing to
+  stderr to keep panic traces off the MCP stdout
+  (`http_read.rs:31-38`).
+
+- **Async runtime:**
+  - `analyze` builds a **multi-thread** runtime (`main.rs:36-38`).
+  - `serve`'s MCP stdio loop runs a **current-thread** runtime on a
+    dedicated OS thread (`serve.rs:126-130`), with the HTTP server running
+    in its own thread (`http_read.rs::spawn`). One `ReaderPool` is shared
+    across both and verified by `Arc::ptr_eq` (`serve.rs:63-71`).
+
+- **Configuration loading:**
+  - `clarion.yaml` is parsed by `serde_norway` (YAML). `clarion-mcp/src/config.rs::McpConfig::from_yaml_str` runs an alias-collision check (`llm` vs `llm_policy`) then `validate()` enforces invariants such as "no Anthropic provider", "Filigree actor non-blank when enabled", "Filigree port-conflict ban", "no zero-port".
+  - `clarion-cli/src/config.rs` separately parses analyze-time config (clustering, etc.).
+  - Note `analyze` deliberately **does not** load `.env` files
+    (`main.rs:23-25, 19-22`): `.env` is treated as in-tree source and
+    scanned by the secret scanner before plugin spawn.
+
+- **Schema / migrations:**
+  - Embedded via `include_str!` in
+    `clarion-storage/src/schema.rs:18-22`. One migration so far:
+    `0001_initial_schema.sql` (293 lines of SQL). Tracking table:
+    `schema_migrations`.
+  - PRAGMA invariant check: `apply_write_pragmas` rejects connection if
+    `journal_mode` is not `WAL` after `PRAGMA journal_mode = WAL`
+    (`pragma.rs:17-21`).
+
+- **Security boundaries:**
+  - **Plugin jail** (`crates/clarion-core/src/plugin/jail.rs`): every
+    `file_path` from a plugin response is `canonicalize()`d and asserted
+    `starts_with(project_root)`. Violations trip the `PathEscapeBreaker`
+    (>10 escapes / 60s → kill).
+  - **Resource caps** (`limits.rs:11-15` table): `ContentLengthCeiling` 8 MiB,
+    entity cap 500k per run, `RLIMIT_AS` via
+    `CommandExt::pre_exec`-applied `setrlimit(2)` (the *only* allowed
+    `unsafe` in the workspace, justified at `Cargo.toml:21-24`).
+  - **Crash-loop breaker** (`breaker.rs:1-14`): >3 plugin crashes / 60s →
+    refuse further spawns.
+  - **Pre-ingest secret scan** (`clarion-cli/src/secret_scan.rs:1-8`):
+    runs before any plugin spawn; analyze aborts with exit code 78
+    unless `--allow-unredacted-secrets` is set with the right confirm
+    token; emits structured findings written to storage.
+  - **HTTP bearer auth + HMAC option**
+    (`http_read.rs:376-510`); `/api/v1/_capabilities` is the only
+    unprotected route. `LoadShedLayer` + `ConcurrencyLimitLayer(64)`
+    + 10s `TimeoutLayer` for DoS resistance.
+  - **stdout guard on the Python plugin side**
+    (`plugins/python/src/clarion_plugin_python/stdout_guard.py`) — any
+    accidental `print()` is redirected so JSON-RPC framing is never
+    corrupted.
+
+- **Test harness shape:**
+  - Per-crate `tests/*.rs` integration tests + inline `#[cfg(test)]` units.
+  - Cross-language fixture at `fixtures/entity_id.json` consumed by both
+    `tests/test_entity_id.py` and (presumably, not verified) a Rust test.
+  - Bash-level e2e in `tests/e2e/` (4 scripts).
+  - Performance harness in `tests/perf/b8_scale_test/` with timestamped
+    results directories (latest: `2026-05-18T1138Z-phase3/`).
+
+## 8. Test Corpus Shape
+
+**Per-crate Rust tests** (`crates/*/tests/*.rs`):
+- `clarion-core/tests/host_subprocess.rs` (325) — T1 happy-path subprocess
+  integration; spawns the `clarion-plugin-fixture` binary via `PluginHost::spawn`.
+- `clarion-storage/tests/writer_actor.rs` (2440) — round-trip insert,
+  per-N-batch commit cadence, `FailRun` rollback.
+- `clarion-storage/tests/schema_apply.rs` (901) — migration 0001 produces
+  every table, index, trigger.
+- `clarion-storage/tests/query_helpers.rs` (1124) — read-side query helpers.
+- `clarion-storage/tests/reader_pool.rs` — reader-pool concurrency.
+- `clarion-storage/tests/llm_cache.rs` — LLM cache helper tests.
+- `clarion-cli/tests/install.rs` — `clarion install` integration.
+- `clarion-cli/tests/analyze.rs` (1456) — Sprint-1 `clarion analyze`.
+- `clarion-cli/tests/serve.rs` (3075) — MCP serve over real sockets/pipes.
+- `clarion-cli/tests/secret_scan.rs` (917, `#![cfg(unix)]`) — secret-scan gate.
+- `clarion-cli/tests/wp1_e2e.rs` — README §3 demo-script smoke.
+- `clarion-cli/tests/wp2_e2e.rs` (606) — full walking-skeleton pipeline.
+- `clarion-mcp/tests/storage_tools.rs` (2233) — storage-backed MCP tool tests.
+- `clarion-scanner/tests/scanner.rs` (655) — pattern + baseline tests.
+
+**Python plugin tests** (`plugins/python/tests/`, 9 files, 3440 LOC):
+`test_entity_id.py`, `test_extractor.py`, `test_package.py`,
+`test_pyright_session.py`, `test_qualname.py`, `test_round_trip.py`
+(plugin analyses its own source), `test_server.py` (subprocess JSON-RPC),
+`test_stdout_guard.py`, `test_wardline_probe.py`.
+
+**End-to-end shell scripts** (`tests/e2e/`):
+- `sprint_1_walking_skeleton.sh` — `install` → `analyze` → sqlite assertions
+  on entities, edges, references.
+- `sprint_2_mcp_surface.sh` — analyze + `clarion serve`, sends framed
+  MCP JSON-RPC for "eight" navigation tools (note: actual `list_tools()` is
+  now 19 — script may exercise a subset), with a local HTTP fake of
+  Filigree's reverse-association route.
+- `phase3_subsystems.sh` — clustering: subsystem entities, membership
+  edges, deterministic signature across clean project copies, MCP
+  `subsystem_members` tool.
+- `wp5_secret_scan.sh` — pre-ingest scanner smoke.
+- Plus `external-operator-smoke.md` (procedure doc, not a script).
+
+**Perf corpus**: `tests/perf/b8_scale_test/` with a `derive-elspeth-corpus.sh`
+script, `driver.py`, `test_driver.py`, and persisted result directories
+(latest `2026-05-18T1138Z-phase3/`). `tests/perf/elspeth_mini/` is a
+~150-file Python corpus checked in to seed perf runs.
+
+## 9. Open Questions (For Per-Subsystem Phase)
+
+1. **Writer-actor concurrency** — `writer.rs:50` exposes `commits_observed`
+   as an `Arc<AtomicUsize>` and explicitly says "Read this field before
+   dropping the Writer". What invariants does the actor enforce around
+   `BeginRun` / `FailRun` / `CommitRun`? How does it interact with
+   `recover_preexisting_running_runs` on next start?
+2. **Two-thread `serve` topology** — why are MCP stdio and HTTP read each
+   on a dedicated thread with their *own* tokio runtime configurations
+   (`current_thread` vs the implicit Axum runtime), and what guarantees the
+   `Arc::ptr_eq` check buys at `serve.rs:63-71`?
+3. **Plugin jail bypasses** — `jail.rs` follows symlinks. Are there file
+   classes (e.g. symlinks in the project root, hard links across
+   filesystems, special files in `/proc`) that the current `canonicalize +
+   starts_with` rule under-handles?
+4. **Crash-loop & path-escape thresholds** — `breaker.rs` hard-codes
+   >3 crashes / 60s; `limits.rs` PathEscapeBreaker hard-codes >10 / 60s.
+   Are these surfaced through `clarion.yaml` or are they baked in?
+5. **Identity check correctness** — `host.rs` step 2 recomputes
+   `entity_id(plugin_id, kind, qualified_name)` and compares against the
+   returned string. What happens if the plugin emits an entity ID whose
+   `canonical_qualified_name` contains a colon (forbidden) vs unicode edge
+   cases (NFC/NFD)?
+6. **MCP tool inventory drift** — `list_tools()` returns 19 tools; the
+   `sprint_2_mcp_surface.sh` script comments mention "eight". Does the
+   e2e cover the full surface, or only a Sprint-2 subset?
+7. **LLM provider sandboxing** — `ClaudeCliProvider` and `CodexCliProvider`
+   shell out to local CLI binaries. How are timeouts, stdout
+   capture, and permission modes (e.g. Codex `sandbox: read-only` in
+   `clarion.yaml`) actually enforced inside `llm_provider.rs`?
+8. **HTTP auth modes** — bearer is wired (`require_http_identity` line 376)
+   and HMAC handler exists (`require_hmac_identity` line 405). Which is on
+   today, how is the secret material loaded, and is HMAC behind a feature
+   gate or a config setting?
+9. **Schema evolution path** — only one migration is in tree
+   (`0001_initial_schema.sql`, 293 lines). What is the migration-author
+   workflow, and how does `scripts/check-migration-retirement.py` gate it?
+10. **Clustering reproducibility** — `clustering.rs` uses `xgraph`'s Leiden
+    implementation with a seed in `ClusterConfig`. Does
+    `phase3_subsystems.sh` actually exercise byte-for-byte determinism, or
+    only signature-level determinism via `cluster_hash`?
+11. **Wardline coupling shape** — the plugin imports `wardline.core.registry`
+    only inside `wardline_probe.py` (the manifest declares
+    `wardline_aware = true` in `plugin.toml:24`). Does any production
+    code path *consume* the probe result, or is it purely declarative
+    at v1.0?
+
+## 10. Confidence Statement
+
+| Claim                                                                                  | Confidence | Evidence |
+|----------------------------------------------------------------------------------------|------------|----------|
+| Workspace has six Rust crates                                                          | High       | `Cargo.toml:3-10` |
+| `clarion` binary has three subcommands: install / analyze / serve                       | High       | `crates/clarion-cli/src/cli.rs:12-62` |
+| MCP server exposes 19 tools                                                            | High       | `ToolDefinition` enumeration of `crates/clarion-mcp/src/lib.rs:56-257` = 19 (the `grep -c 'ToolDefinition {'` shortcut counted the struct declaration plus 19 instances; corrected during catalog validation) |
+| HTTP read API has 4 functional routes + 2 test-only                                    | High       | `crates/clarion-cli/src/http_read.rs:347-356,1374-1433` |
+| MCP protocol version = `"2025-11-25"`                                                  | High       | `crates/clarion-mcp/src/lib.rs:40` |
+| Plugin JSON-RPC framing is LSP-style `Content-Length`                                  | High       | `crates/clarion-core/src/plugin/transport.rs:1-9` |
+| SQLite is WAL with `synchronous=NORMAL`, `busy_timeout=5000`                           | High       | `crates/clarion-storage/src/pragma.rs:17-30` |
+| Writer-actor is a single tokio task owning one write connection                        | High       | `crates/clarion-storage/src/writer.rs:1-12, lib.rs:1-5` |
+| Plugin discovery is `$PATH` scan for `clarion-plugin-*` with neighbor + install-prefix fallback | High | `crates/clarion-core/src/plugin/discovery.rs:1-40` |
+| Python plugin uses `pyright==1.1.409` as a subprocess language server                  | High       | `plugins/python/pyproject.toml:21`, `pyright_session.py:7-11` |
+| `unsafe_code = "deny"` workspace-wide with one documented exception in plugin host    | High       | `Cargo.toml:20-25` + `crates/clarion-core/src/plugin/host.rs` module doc §Memory limit |
+| Crash-loop breaker triggers >3 crashes in 60s                                          | High       | `crates/clarion-core/src/plugin/breaker.rs:1-7` |
+| `clarion serve` runs MCP stdio + HTTP in two threads sharing one `ReaderPool`          | High       | `crates/clarion-cli/src/serve.rs:53-80` |
+| Pre-ingest secret scan blocks analyze with exit code 78 by default                     | High       | `crates/clarion-cli/src/secret_scan.rs:1-12`, `main.rs:42-47` |
+| Wardline integration is import-probe-only on the Python side                           | High       | `plugins/python/src/clarion_plugin_python/wardline_probe.py` (whole file) |
+| `clarion-scanner` is dependency-free of other Clarion crates                           | High       | `crates/clarion-scanner/Cargo.toml` (no `clarion-*` paths) |
+| Filigree is reached via outbound `reqwest`; no inbound Filigree surface in this repo   | High       | `crates/clarion-mcp/src/filigree.rs:1-12` |
+| `clustering.rs` uses `xgraph`'s Leiden community detection                             | High       | `crates/clarion-cli/src/clustering.rs:5-6` |
+| Single schema migration so far (`0001_initial_schema.sql`)                             | High       | `ls crates/clarion-storage/migrations/`, `schema.rs:18-22` |
+| Total Rust source ~29k LOC                                                             | Medium     | `wc -l` per crate src trees; line counts include comments + blanks |
+| Total Python source 3028 LOC                                                           | High       | `wc -l plugins/python/src/clarion_plugin_python/*.py` |
+| `list_tools()` includes exactly the 19 tool names listed in §5                         | High       | Direct enumeration of the `ToolDefinition` registry during catalog validation. The "one more past line 254" was a miscount — the literal `ToolDefinition {` at the struct declaration leaked into the original `grep -c`. |
+| HMAC inbound auth is wired but possibly behind a config gate                           | Medium     | `require_hmac_identity` exists at `http_read.rs:405` but I did not trace what selects it vs bearer |
+| `analyze.rs` calls `Command::new` on the plugin path                                    | Medium     | Inferred from `analyze.rs` module doc + `clarion_core::AcceptedEntity` imports; did not read the spawn line directly. The `Command::new` call lives inside `PluginHost::spawn` in `host.rs`, not in `analyze.rs`. |
+| Cross-language fixture `fixtures/entity_id.json` is consumed by Rust tests too         | Low        | Only Python consumer confirmed (`test_entity_id.py` per its docstring); Rust side asserted by spec language but not greped in this pass |
+
+---
+
+## Confidence Assessment (overall)
+
+High overall. The §1–§8 claims are mostly directly traceable to a file:line
+or to a `Cargo.toml` / `pyproject.toml` field. The discovery sweep read or
+sampled every src `.rs` in `clarion-core/src/plugin/` and the `lib.rs`/entry
+of every other crate; every Python module head; every `Cargo.toml`; the
+HTTP router definition; the MCP `list_tools()` table; the writer/pragma/schema
+heads; the e2e scripts; and `plugin.toml`.
+
+## Risk Assessment
+
+- **Greatest risk to downstream catalog work:** the two giant files
+  (`clarion-mcp/src/lib.rs` at 4703 LOC and `clarion-core/src/plugin/host.rs`
+  at 2935 LOC) were only sampled. Per-subsystem explorers should read them
+  end-to-end before claiming completeness on MCP tooling or host
+  enforcement semantics.
+- **Resolved during validation:** the tool count was originally reported as
+  20 in this doc, derived via `grep -c 'ToolDefinition {'`. Catalog
+  validation enumerated the actual `ToolDefinition` registry at
+  `clarion-mcp/src/lib.rs:56-257` and confirmed **19** distinct production
+  tools. The grep counted the struct declaration plus 19 instances.
+- **External dependency surface I did not read:** the actual `Command::new`
+  for plugin subprocess spawn lives inside `host.rs` (sampled only at the
+  module doc), not `analyze.rs`. Behaviour around `pre_exec`, descriptor
+  closing, and env-var passing was not traced beyond the module-doc
+  promise.
+
+## Information Gaps
+
+- No reading of the migration SQL (`0001_initial_schema.sql`) — schema
+  shape (tables, indexes, FK graph) is therefore an open question.
+- No tracing of `analyze::run_with_options`'s control flow past its
+  imports + signature — concurrency model of "Pattern A buffering" not
+  verified, only quoted from the module doc.
+- `target/` build artifacts not inspected; binary sizes / link surface
+  unknown.
+- `.github/workflows/ci.yml` contents not read; only filename observed.
+- Wardline-side code: not in this repo; no claims made beyond what the
+  Python `wardline_probe` proves about imports.
+
+## Caveats
+
+- This document deliberately reports the system as evidenced by code,
+  not by intent. Where the code names ADRs, work packages, or sprints in
+  comments, the IDs are quoted but not validated against the (un-read)
+  design docs.
+- LOC figures include comments and blanks; they are coarse "depth
+  indicators" only.
+- The Python `__pycache__/` count in the file tree was suppressed from
+  module counts but does indicate the test suite has been executed on
+  this machine.
diff --git a/docs/arch-analysis-2026-05-22-1924/02-subsystem-catalog.md b/docs/arch-analysis-2026-05-22-1924/02-subsystem-catalog.md
new file mode 100644
index 00000000..fa75082b
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/02-subsystem-catalog.md
@@ -0,0 +1,632 @@
+# 02 — Subsystem Catalog (Clarion)
+
+> Source-of-evidence guarantee: every section in this catalog was produced by an
+> independent codebase-explorer subagent reading only the relevant source,
+> manifests, migration SQL, fixtures, and tests under that subsystem's tree.
+> No design docs (`docs/clarion/**`, `docs/suite/**`, `docs/implementation/**`,
+> `docs/federation/**`, prior `arch-analysis-*/`, ADRs, sprint READMEs) were
+> read while writing these entries. Confidence statements per section list
+> evidence consumed.
+
+## 1. clarion-core
+
+**Location:** `crates/clarion-core/`
+**LOC:** 11,653 source / 325 integration test (plus extensive inline `#[cfg(test)]` blocks; see Concerns)
+**Crate type / role:** Rust library (`lib.rs`). No binary. Re-exported as a facade by `lib.rs:13-49`; implementation modules remain reachable through `clarion_core::plugin::*` per the explicit policy comment at `lib.rs:5-7`.
+
+### Responsibility
+
+`clarion-core` owns three orthogonal concerns bundled into one crate: (1) the canonical **entity-ID assembler** (`entity_id.rs`), which is the single source of truth for the `{plugin_id}:{kind}:{canonical_qualified_name}` identifier shape and the ADR-022 identifier grammar; (2) the **plugin host runtime** (`plugin/`), a synchronous JSON-RPC supervisor that discovers, spawns, validates, and reaps language-plugin subprocesses while enforcing four core minimums (path jail, content-length ceiling, run-cumulative entity cap, virtual-address limit); and (3) the **LLM provider abstraction** (`llm_provider.rs`), a `Send + Sync` trait plus four concrete adapters (recording fixture, OpenRouter HTTP, Claude CLI subprocess, Codex CLI subprocess) for query-time enrichment. The public surface that proves the boundary is the `pub use` block in `lib.rs:13-49`, which is the only API surface other workspace crates are *supposed* to consume (the policy comment is explicit; one violation exists — see Concerns).
+
+### Key components
+
+- `src/entity_id.rs:90-148` — `entity_id(plugin_id, kind, canonical_qualified_name) -> Result<EntityId, EntityIdError>` plus a shared `validate_kind_grammar` helper used by both this module and `manifest.rs`. ~150 LOC of code; ~450 LOC of byte-for-byte cross-language parity tests against `fixtures/entity_id.json` covering entities + `contains`/`calls`/`references` edge wire shapes (`entity_id.rs:371-587`).
+- `src/plugin/manifest.rs:1-1119` — TOML parser for `plugin.toml`, ADR-022 reserved-kind / reserved-rule-prefix gating, `Manifest::validate_for_v0_1()` capability check (run at handshake). Defines `RESERVED_ENTITY_KINDS = ["file", "subsystem", "guidance"]` at line 28.
+- `src/plugin/transport.rs:1-569` — LSP-style `Content-Length:`-framed JSON transport. Synchronous `read_frame(reader, ceiling) -> Result<Frame, TransportError>` / `write_frame(writer, frame)`. Header-line cap at 8 KiB (`MAX_HEADER_LINE_BYTES`), body cap from caller-supplied `ContentLengthCeiling` (default 8 MiB).
+- `src/plugin/protocol.rs:312-474` — Typed JSON-RPC 2.0 envelopes and the five method bodies: `initialize` (core→plugin), `initialized` (notification), `analyze_file` (request), `shutdown` (request), `exit` (notification). Struct-per-method discriminated by `IncomingMessage::method` (`protocol.rs:3-22` doc). `JsonRpcVersion` newtype hard-pins the literal `"2.0"`.
+- `src/plugin/jail.rs:73-103` — `jail(root, candidate)` and `jail_to_string(root, candidate)`. Both paths canonicalise via `std::fs::canonicalize` (follows symlinks per UQ-WP2-03 comment), assert `starts_with(canonical_root)`, and surface `JailError::EscapedRoot` / `Io` / `NonUtf8Path`.
+- `src/plugin/limits.rs:1-572` — `ContentLengthCeiling` (8 MiB default), `EntityCountCap` (run-cumulative; default 500k via `EntityCountCap::DEFAULT_MAX`), `PathEscapeBreaker` (per-plugin; >10 escapes in 60 s trips), `apply_prlimit_as` / `apply_prlimit_nofile_nproc` (Linux-only `setrlimit` wrappers; async-signal-safe for `pre_exec`). Co-locates the seven `CLA-INFRA-PLUGIN-*` finding subcode constants.
+- `src/plugin/breaker.rs:43-117` — `CrashLoopBreaker`: rolling-window crash counter (default 60 s window, >3 threshold per UQ-WP2-10). Trips → `FINDING_DISABLED_CRASH_LOOP` and refusal of further spawns. *Caller-driven* — `PluginHost` does not own this; the run loop in `clarion-cli/analyze.rs:271` does.
+- `src/plugin/discovery.rs:1-667` — `discover()` / `discover_on_path()` scan `$PATH` for `clarion-plugin-<suffix>` executables, locate the neighbouring `plugin.toml` (with a pipx-aware symlink-resolved install-prefix fallback documented at lines 13-33), and return `Vec<Result<DiscoveredPlugin, DiscoveryError>>`.
+- `src/plugin/host.rs:384-1182` — `PluginHost<R: BufRead, W: Write>`: the supervisor. Generic over reader/writer so the in-process `mock.rs` (876 LOC, `#[cfg(test)] pub(crate)`) can drive it without a subprocess. Public methods: `spawn` (subprocess constructor; lines 505-644), `connect` (in-process; 658-666), `handshake` (743-803), `analyze_file` (815-985), `shutdown` (1106-1111), plus accessors `stderr_tail`, `ontology_version`, `take_findings`, `set_briefing_blocks`, `set_scanned_source_files`. The four-stage per-entity validation pipeline (ontology → identity → jail → cap) lives inline in `analyze_file` at lines 866-975.
+- `src/plugin/host_findings.rs:1-273` — `HostFinding` struct + ten `CLA-INFRA-PLUGIN-*` / `CLA-INFRA-HOST-*` / `CLA-INFRA-MANIFEST-*` subcode constants and constructor functions (`unsupported_capability`, `entity_id_mismatch`, `path_escape`, `malformed_entity`, `malformed_edge`, …).
+- `src/llm_provider.rs:101-2467` — `trait LlmProvider: Send + Sync` plus `RecordingProvider`, `OpenRouterProvider` (live `reqwest` HTTP), `CodexCliProvider` and `ClaudeCliProvider` (subprocess CLI wrappers with bounded stdout/stderr ring buffers and timeout via background reaper thread). Also hosts the prompt-template builders `build_leaf_summary_prompt`, `build_inferred_calls_prompt`, `build_coding_agent_provider_prompt` and version constants.
+
+### Public interface (outbound)
+
+The crate-root `pub use` facade (`lib.rs:13-49`) re-exports exactly these names; everything else is reachable through `clarion_core::plugin::{module}::*` per the explicit policy at `lib.rs:5-7`:
+
+- **Entity-ID assembler:** `EntityId`, `EntityIdError`, `entity_id()` — assemble or parse a 3-segment ID. `EntityId` is opaque (the only constructor is `entity_id()` / `FromStr::from_str` / `Deserialize`); `as_str()` returns the canonical form.
+- **Plugin discovery:** `DiscoveredPlugin`, `DiscoveryError`, `discover()` — scan `$PATH` for `clarion-plugin-*` binaries.
+- **Plugin manifest:** `Manifest`, `ManifestError`, `parse_manifest()` — TOML parse + ADR-022 grammar / reserved-kind / reserved-rule-prefix checks. Plus `Manifest::validate_for_v0_1()` capability gate, exercised by the host at handshake.
+- **Plugin host:** `PluginHost`, `HostError`, `HostFinding`, `AcceptedEntity`, `AcceptedEdge`, `AnalyzeFileOutcome`, `AnalyzeFileStats`, `UnresolvedCallSite`, `BriefingBlockReason`, `EdgeConfidence`.
+- **Resource limits:** `JailError`, `CapExceeded`, plus the `FINDING_DISABLED_CRASH_LOOP` constant (re-exported from `breaker`).
+- **Crash-loop breaker:** `CrashLoopBreaker`, `CrashLoopState` — caller-driven, used by the analyze run loop, not by `PluginHost` itself.
+- **LLM providers:** `LlmProvider` trait + `LlmRequest`, `LlmResponse`, `LlmPurpose`, `LlmProviderError`, `CachingModel`, `Recording`, `RecordingProvider`, `OpenRouterProvider(+Config)`, `ClaudeCliProvider(+Config)`, `CodexCliProvider(+Config)`, `PromptTemplate`, the three `build_*_prompt` functions, and the version constants `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `INFERRED_CALLS_PROMPT_VERSION`.
+
+**JSON-RPC method set (the wire surface `PluginHost` drives, not Rust API):** `initialize` (request; `InitializeParams { protocol_version, project_root }` → `InitializeResult { name, version, ontology_version, capabilities }`); `initialized` (notification, empty params); `analyze_file` (request; `{ file_path }` → `{ entities: Vec<Value>, edges: Vec<Value>, stats: AnalyzeFileStats }` — per-element typing happens in `host::analyze_file` so a single malformed entity drops with a finding rather than failing the response); `shutdown` (request, empty); `exit` (notification, empty). `protocol.rs:3-22` and `protocol.rs:312-474`.
+
+### Dependencies
+
+- **Inbound (who calls this):**
+  - `crates/clarion-cli/src/analyze.rs` — the principal consumer. Uses `discover`, `parse_manifest`, `PluginHost::spawn`, `CrashLoopBreaker` (driven by the run loop, not the host), `AcceptedEntity`/`AcceptedEdge`/`AnalyzeFileOutcome`, `HostFinding`, `BriefingBlockReason`, `EdgeConfidence`, plus the `entity_id::entity_id` direct call for `core:file:*` and `core:subsystem:*` IDs (lines 909, 1683).
+  - `crates/clarion-cli/src/serve.rs`, `secret_scan.rs` — `BriefingBlockReason` and the LLM-provider types.
+  - `crates/clarion-storage/src/{commands,query,writer}.rs` — `EdgeConfidence` (re-exported from `commands.rs`), and one deep reach across the facade: `writer.rs:427` reads `clarion_core::plugin::manifest::RESERVED_ENTITY_KINDS` directly (not through the crate-root facade).
+  - `crates/clarion-mcp/src/lib.rs`, `clarion-plugin-fixture/src/main.rs`, and several integration tests (`clarion-cli/tests/wp2_e2e.rs`, `clarion-mcp/tests/storage_tools.rs`, etc.).
+- **Outbound (what this calls):** Standard library only for the host + entity-ID layers (`std::process::Command`, `std::io::{BufRead,Write}`, `std::fs::canonicalize`, `std::thread`, `std::sync::{Arc,Mutex}`). External crates: `serde`/`serde_json` (wire), `thiserror` (errors), `toml` (manifest), `tracing` (logging), `nix` (Linux `setrlimit` via `apply_prlimit_*` in `limits.rs`), `which` (transitive via `discovery`), `reqwest` (live `OpenRouterProvider` HTTP), `tempfile` (test-only).
+- **External services:** Plugin subprocesses (spawned by `PluginHost::spawn`, communicated to via stdin/stdout pipes; stderr piped + drained on a detached thread into a 64 KiB ring buffer at `host.rs:447-476`). Optional outbound HTTP to OpenRouter (`llm_provider.rs::OpenRouterProvider`). Optional `claude` / `codex` CLI subprocesses (`ClaudeCliProvider`, `CodexCliProvider`).
+
+### Internal architecture
+
+**Concurrency model: synchronous over `BufRead`/`Write`.** `PluginHost<R, W>` (`host.rs:384`) is generic over a reader and writer so unit tests drive it in-process via `connect()` while production code uses `spawn()` which wires `std::io::BufReader<ChildStdout>` and `std::io::BufWriter<ChildStdin>`. All RPC is request-response on the same thread that called `analyze_file`; there is no async, no task system, no message channel inside the host. The *only* concurrency is one detached `std::thread` per host (`host.rs:614-620`, named `clarion-plugin-stderr-drain:<plugin_id>`) that reads `ChildStderr` in 4 KiB chunks into a bounded `VecDeque<u8>` of capacity `STDERR_TAIL_BYTES = 64 KiB`, popping front on overflow. Rationale at `host.rs:550-561`: an inherited stderr could (a) flood the operator's terminal with hostile bytes or (b) deadlock the plugin on `write(2)` when the host is blocked in `analyze_file`. The ring is read back via `stderr_tail() -> Option<String>` using lossy-UTF-8 conversion. `PluginHost::spawn` returns `(Self, std::process::Child)` — the *caller* owns reaping; `Child::Drop` does not `waitpid` on Unix (`host.rs:630-641`), so a handshake failure inside `spawn` reaps the child before returning the error.
+
+**Enforcement pipeline (the load-bearing per-entity loop, `host.rs:866-975`).** For each `RawEntity` deserialised from `AnalyzeFileResult.entities`: (0) field-size check against `MAX_ENTITY_FIELD_BYTES = 4 KiB` for `id`/`kind`/`qualified_name`/`source.file_path` and `MAX_ENTITY_EXTRA_BYTES = 64 KiB` for the two `#[serde(flatten)]` passthrough maps; (1) ontology check — `kind` must be in `manifest.ontology.entity_kinds` (ADR-022); (2) identity check — recomputed `entity_id(plugin_id, kind, qualified_name)` must equal the wire `id` (UQ-WP2-11 — prevents a plugin from minting IDs outside its declared namespace); (3) jail check — `jail_to_string(project_root, source.file_path)` must succeed; on failure, tick the per-host `PathEscapeBreaker`; (4) entity cap — `EntityCountCap::try_admit(1)`. Steps 0–2 drop the entity with a finding and continue. Step 3 drops the entity + records a finding; if the breaker trips (>10 escapes / 60 s) it shuts down the plugin and returns `HostError::PathEscapeBreakerTripped`. Step 4 on overflow shuts down the plugin and returns `HostError::EntityCapExceeded`. Edges go through a parallel but kill-free pipeline (`process_edges`, lines 1017-1060) — edges do not participate in the path-escape breaker or the entity cap.
+
+**Failure-mode policy (four distinct mechanisms, three layers).** The system layers failure detection:
+1. **Per-frame ceiling** — `ContentLengthCeiling::DEFAULT = 8 MiB`. `read_frame` rejects with `TransportError::FrameTooLarge` *before* consuming the body bytes (`transport.rs:67-71`).
+2. **Per-host path-escape breaker** — `PathEscapeBreaker` (`limits.rs`), rolling-window >10 escapes / 60 s. Owned by `PluginHost`. Trip → kill plugin.
+3. **Per-run entity-count cap** — `EntityCountCap`, default 500,000 entities cumulative across all `analyze_file` calls on this host. Exceeded → kill plugin.
+4. **Per-run crash-loop breaker** — `CrashLoopBreaker` (`breaker.rs`), rolling-window >3 spawn/handshake/analyze crashes / 60 s. *Not* owned by `PluginHost`; the analyze run loop in `clarion-cli/analyze.rs:271` constructs and ticks it. Trip → emit `FINDING_DISABLED_CRASH_LOOP`, refuse further spawns this run.
+
+The two breakers are conceptually different scopes — one polices a single misbehaving plugin's emissions, the other polices the *fleet* of plugins across one run.
+
+**State ownership inside `PluginHost`** (`host.rs:384-422`): `manifest` (immutable), `project_root` (canonicalised once at construction), `reader`/`writer` (the wire endpoints), `ceiling`/`entity_cap`/`path_breaker` (the three host-resident enforcement gates), `next_request_id` (monotone i64 — the JSON-RPC `id` allocator), `findings: Vec<HostFinding>` (accumulated; drained via `take_findings()`), `terminated: bool` (idempotency guard so a double `shutdown()` does not write to a closed pipe), `ontology_version: Option<String>` (set at handshake for ADR-007 cache keying by WP6), `stderr_tail: Option<Arc<Mutex<VecDeque<u8>>>>` (the ring buffer; `None` for in-process `connect()`), and two read-only `Arc`-shared inputs the analyze run loop installs: `briefing_blocks: Arc<BTreeMap<PathBuf, BriefingBlockReason>>` and `scanned_source_files: Arc<BTreeSet<PathBuf>>` that drive `apply_briefing_block` (lines 987-1004) to attach `briefing_blocked` markers to entities whose source file failed secret scan or was unscanned.
+
+**Error model.** `HostError` (`host.rs:334-370`) wraps `TransportError`, `ProtocolError`, `ManifestError`, `CapExceeded`, `EntityIdError`, `serde_json::Error`, `std::io::Error`, plus three policy variants (`PathEscapeBreakerTripped`, `EntityCapExceeded(CapExceeded)`, `Spawn(String)`). Every module exposes its own `thiserror`-derived enum (`TransportError`, `ManifestError`, `JailError`, `DiscoveryError`, `EntityIdError`, `LlmProviderError`); the host composes them via `#[from]`. The asymmetry between "drop-entity, no kill" (steps 0–2 of the pipeline + most ontology/identity violations) and "kill plugin" (path-escape breaker trip, entity-cap overflow, manifest capability refusal) is the central policy expression.
+
+### Patterns observed
+
+- **Drop-with-finding vs. kill-with-error asymmetry** — `host.rs:866-975`. Two-tier sanction system mediated by `HostFinding` accumulation versus `Result::Err(HostError::*)` propagation.
+- **Generic-over-IO supervisor with in-process mock** — `PluginHost<R: BufRead, W: Write>` (`host.rs:384`) + `mock.rs` (876 LOC, `pub(crate) #[cfg(test)]`). Lets the host's entire pipeline be tested without spawning a subprocess; `connect()` constructor (line 658) is the seam.
+- **Per-frame size ceiling with no-body-consume rejection** — `transport.rs:67-71` returns `FrameTooLarge` before touching the body, so a hostile frame cannot exhaust memory in `read_to_end`.
+- **Newtype wrappers as wire pins** — `JsonRpcVersion` (`protocol.rs:72-95`) serialises/deserialises strictly to `"2.0"`; `EntityId` is constructible only via `entity_id()` / `FromStr::from_str` / custom `Deserialize` (`entity_id.rs:19-60`) so deserialising an arbitrary string at a `serde(flatten)` boundary cannot smuggle in a malformed id.
+- **`pre_exec` resource-limit application** — `host.rs:569-586`. Closure runs in the forked child, calls only async-signal-safe `setrlimit(2)`, with a safety comment documenting the POSIX.1-2017 §2.4.3 reference. `RLIMIT_AS` from manifest hint or `DEFAULT_MAX_RSS_MIB`; `RLIMIT_NPROC` bumped to 4096 when `manifest.capabilities.runtime.pyright = Some(_)` (line 89, 577) because Pyright's Node-based LSP spawns helpers checked against the user's process count, not just children.
+- **Cross-language byte-for-byte fixture parity** — `entity_id.rs:371-587` consumes `../../fixtures/entity_id.json` (the same file the Python plugin's `test_entity_id.py` consumes) and asserts identical assembly results for entities and the three edge wire shapes.
+- **Caller-driven breaker, host-driven breaker** — symmetric naming hides asymmetric ownership. `CrashLoopBreaker` is *given* to the caller (it sits in `analyze.rs`'s plugin loop); `PathEscapeBreaker` lives inside the host. Same shape, different scope.
+- **Idempotent shutdown via terminated flag** — `host.rs:1106-1111` and `do_shutdown` at 1158. The flag is set *before* the shutdown exchange runs (line 1164) so even a mid-exchange pipe break does not surface a spurious `BrokenPipe` on a defensive double-`shutdown()`.
+
+### Concerns / Smells / Risks
+
+- **`host.rs` at 2,935 LOC is the largest single file in the crate and (per the discovery doc) one of the four largest in the workspace.** The four-stage validation pipeline, edge processing, stats post-processing, briefing-block reconciliation, the subprocess constructor with its stderr drainer, and the in-process generic methods all live in one `impl PluginHost<R: BufRead, W: Write>` block. The module would split cleanly along the pipeline-step / lifecycle / IO axes; the current shape makes the per-step contracts harder to test in isolation than the generics already permit.
+- **`llm_provider.rs` at 2,467 LOC is in this crate at all.** The `lib.rs` doc-comment (`lib.rs:1`) calls this crate "domain types, identifiers, and provider traits" — but the module bundles concrete `reqwest`-based OpenRouter HTTP, two distinct subprocess-CLI provider implementations (Claude, Codex) each with their own timeout / ring-buffer / reaper-thread machinery, and the prompt-template builders. Three orthogonal subsystems (the trait, the HTTP transport, the CLI transports, the prompt assembly) compressed into one file in a crate that otherwise is about plugin hosting. A future `clarion-llm` crate split would tighten the `clarion-core` boundary considerably; today, `reqwest` is a top-level dependency of the crate that supervises plugins.
+- **Facade leak from `clarion-storage`.** `writer.rs:427` reaches `clarion_core::plugin::manifest::RESERVED_ENTITY_KINDS` directly through the module path, bypassing the `lib.rs` re-export facade. The policy comment at `lib.rs:5-7` describes the facade as the supported surface; this constant is not in it. Either lift the constant to the facade or expose a `Manifest::is_reserved_kind` helper — the direct module reach pins the internal module path as semi-public.
+- **`mock.rs` at 876 LOC is gated behind `#[cfg(test)] pub(crate)`** (`plugin/mod.rs:22`). This is test infrastructure, not production code, so it does not appear in any release binary — but the volume of the mock (driver-script DSL, frame scripting, response builders) is a sign that the host's pipeline is non-trivially stateful, which corroborates the `host.rs` size concern.
+- **Subprocess lifecycle ownership is split.** `PluginHost::spawn` returns `(Self, std::process::Child)` (`host.rs:509`) and the doc at line 630-641 notes `Child::Drop` does not waitpid on Unix. The caller (currently `clarion-cli/analyze.rs`) must reap. The contract is documented but not enforced by the type system; a future consumer that drops `Child` on a happy path leaks a zombie until parent exit. A `KillOnDrop` newtype around the child would close this.
+- **The path jail is a TOCTOU check by design.** `jail.rs:67-72` explicitly documents this: the canonical-path return is "a membership proof at canonicalization time, not a durable file handle." Any consumer that later opens the path must re-jail after open or use `openat`-anchored I/O. The current consumer in this crate doesn't open files (it returns the canonical string downstream), but the comment is the only enforcement and a future caller could miss it.
+- **Limited integration test coverage in this crate's `tests/` directory.** Only one integration test file (`tests/host_subprocess.rs`, 325 LOC) — a single happy-path subprocess walkthrough against `clarion-plugin-fixture`. The host's many failure modes (every variant of `HostError`, every `CLA-INFRA-*` finding subcode) are exercised through inline `#[cfg(test)] mod tests` blocks at the bottom of each module — which works, but the integration surface (real `Command::spawn`, real `pre_exec`, real stderr-drain thread, real reap-on-error) is tested for the happy path only.
+- **`MAX_PROTOCOL_ERROR_FIELD_BYTES = 4 KiB`, `MAX_ENTITY_FIELD_BYTES = 4 KiB`, `MAX_ENTITY_EXTRA_BYTES = 64 KiB`, `STDERR_TAIL_BYTES = 64 KiB`, `MAX_HEADER_LINE_BYTES = 8 KiB`, `MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512`, `ContentLengthCeiling::DEFAULT = 8 MiB`, `EntityCountCap::DEFAULT_MAX = 500_000`, `DEFAULT_MAX_RSS_MIB`, `DEFAULT_MAX_NOFILE`, `DEFAULT_MAX_NPROC`, `PYRIGHT_MAX_NPROC = 4096`** — eleven hardcoded limit constants across `host.rs`, `transport.rs`, `limits.rs`. The `breaker.rs:7` comment acknowledges the config surface lands in WP6 and is not present at this snapshot. Until then, "operator can tune" is aspirational; every limit is a recompile.
+
+### Confidence: High
+
+Read end-to-end: `lib.rs`, `entity_id.rs`, `plugin/mod.rs`, `plugin/jail.rs`, `plugin/breaker.rs` (first 120 lines + skim of tests), and the doc-comment + public-surface scan plus targeted reads of the load-bearing windows of `protocol.rs` (300-499), `host.rs` (1-820, 1060-1190 + grep of all `pub fn`/`impl`/spawn-related symbols), `manifest.rs` (1-100 + reserved-kind constant cross-ref), `discovery.rs` (1-80 doc), `limits.rs` (1-120 + finding constants), `host_findings.rs` (1-80 + grep), `transport.rs` (1-100), and `llm_provider.rs` (1-130 + public-surface grep). Verified dependency edges by grepping `use clarion_core` across the rest of the workspace (`clarion-cli/{analyze,serve,secret_scan}.rs`, `clarion-storage/{commands,query,writer}.rs`, `clarion-mcp/src/lib.rs`, `clarion-plugin-fixture/src/main.rs`). Cross-checked the `CrashLoopBreaker` ownership claim by reading `clarion-cli/analyze.rs:240-275`. Confirmed the `clarion-storage::writer.rs:427` facade leak directly. The two areas read by sample-and-grep rather than end-to-end are `host.rs` (2,935 LOC; sampled the entry points, the four-stage pipeline, the spawn constructor, and the shutdown idempotency window) and `llm_provider.rs` (2,467 LOC; sampled the trait + the public-surface grep but did not read the OpenRouter/Codex/Claude provider implementations in detail — they are flagged in Concerns as out-of-scope tonally for this crate).
+
+## 2. clarion-storage
+
+**Location:** `crates/clarion-storage/`
+**LOC:** 3199 src across 10 files / 4871 tests across 5 files / 293 lines SQL in `migrations/0001_initial_schema.sql`
+**Crate type / role:** Library crate (`lib.rs:1-42`). Sole owner of the SQLite read/write layer for the project DB at `.clarion/clarion.db`. Re-exports a flat surface from nine submodules.
+
+### Responsibility
+`clarion-storage` is the only path through which other crates touch SQLite. It (a) opens and configures the per-project database with a fixed PRAGMA discipline (`pragma.rs`), (b) applies embedded schema migrations idempotently (`schema.rs`), (c) routes *every* mutation through a single writer-actor task that owns the sole write `rusqlite::Connection` (`writer.rs`), (d) hands out short-lived read-only connections from a `deadpool-sqlite` pool (`reader.rs`), and (e) provides the read-side query helper catalogue that the MCP navigation tools and HTTP read API consume (`query.rs`, ~29 `pub` query / type items). The crate also enforces wire-level invariants the rest of the workspace depends on — per-kind edge confidence/source-range contracts, source-file-anchor kinds, reserved entity-kind protection, parent↔contains-edge dual-encoding consistency — at the *writer boundary*, so a misbehaving plugin or caller cannot corrupt graph shape (`writer.rs:425-582, 954-1021`).
+
+### Key components
+- `src/lib.rs:1-42` — module wiring + flat `pub use` facade (`Writer`, `ReaderPool`, `WriterCmd`, ~29 query helpers, cache helpers, `StorageError`).
+- `src/pragma.rs:16-45` — `apply_write_pragmas` (WAL + `synchronous=NORMAL` + `busy_timeout=5000` + `wal_autocheckpoint=1000` + `foreign_keys=ON`, with a hard invariant assertion that `PRAGMA journal_mode=WAL` actually took effect) and `apply_read_pragmas` (busy_timeout + FK only).
+- `src/writer.rs:40-140` — `Writer` handle, `Writer::spawn` (boots the actor as a `tokio::task::spawn_blocking` task owning one `rusqlite::Connection`), `send_wait` convenience.
+- `src/writer.rs:142-260` — `run_actor` central match loop dispatching all 11 `WriterCmd` variants; blocking `mpsc::Receiver::blocking_recv`.
+- `src/writer.rs:290-313, 802-877` — `ActorState` (`batch_size`, `writes_in_batch`, `in_tx`, `current_run`) and `bump_writes_and_maybe_commit` / `flush_run_batch` / `query_time_write` — the batch-cadence and run-transaction state machine.
+- `src/writer.rs:425-582` — wire-contract enforcement: `enforce_entity_kind_contract`, `validate_entity_source_file_anchor`, `enforce_edge_contract`, plus the structural-vs-anchored edge-kind tables (`STRUCTURAL_EDGE_KINDS`, `ANCHORED_EDGE_KINDS`).
+- `src/writer.rs:954-1021` — `parent_contains_mismatch` (the bidirectional parent↔contains dual-encoding check; runs inside the open commit transaction so a violation rolls back the run).
+- `src/reader.rs:26-119` — `ReaderPool` (`deadpool-sqlite` wrapper with an `Arc<()>` identity tag for `shares_pool_with` runtime proofs) and `with_reader` async helper.
+- `src/schema.rs:17-91` — `MIGRATIONS` slice (one entry, embedded by `include_str!`), `apply_migrations` runner gated by a `schema_migrations` table.
+- `src/commands.rs:135-218` — the `WriterCmd` enum: `BeginRun`, `InsertEntity`, `InsertEdge`, `InsertFinding`, `FlushRunBatch`, `InsertInferredEdges`, `UpsertSummaryCache`, `TouchSummaryCache`, `ReplaceUnresolvedCallSitesForCaller`, `CommitRun`, `FailRun` (11 variants, each carries an `Ack<T> = oneshot::Sender<Result<T>>`).
+- `src/query.rs:214-1056` — read helpers (`entity_by_id`, `entity_at_line`, `find_entities`, `call_edges_from/_targeting`, `reference_edges_for_entity`, `module_dependency_edges`, `subsystem_members`, `resolve_file_catalog_entry`, `contained_entity_ids`, …).
+- `migrations/0001_initial_schema.sql:23-291` — 9 tables (`schema_migrations`, `entities`, `entity_tags`, `edges` `WITHOUT ROWID` on natural PK, `findings`, `summary_cache`, `inferred_edge_cache`, `entity_unresolved_call_sites`, `runs`), 1 FTS5 virtual table (`entity_fts`), 3 triggers keeping FTS in sync, 2 generated virtual columns (`scope_rank`, `git_churn_count`) with partial indexes, 1 view (`guidance_sheets`), ~15 secondary indexes, and a row inserted into `schema_migrations`. Wrapped in a single `BEGIN…COMMIT`.
+
+### Public interface (outbound)
+- **Writer surface** — `Writer::spawn(db_path, batch_size, channel_capacity) -> (Writer, JoinHandle<Result<()>>)`; `Writer::sender() -> mpsc::Sender<WriterCmd>`; `Writer::send_wait`; observability counters `commits_observed`, `dropped_edges_total`, `ambiguous_edges_total` (each an `Arc<AtomicUsize>`, present in release builds). Constants `DEFAULT_BATCH_SIZE = 50`, `DEFAULT_CHANNEL_CAPACITY = 256` (`writer.rs:34-38`).
+- **Command protocol** — the `WriterCmd` enum (11 variants), the four POD record types (`EntityRecord`, `EdgeRecord`, `FindingRecord`, `InferredCallEdgeRecord`), `RunStatus` (`SkippedNoPlugins | Completed | Failed`), `InferredEdgeWriteStats`, and `Ack<T>`.
+- **Reader surface** — `ReaderPool::open(db_path, max_size)`, `with_reader(impl FnOnce(&Connection) -> Result<T>) -> Result<T>`, `shares_pool_with`, `identity()`, `waiting_count()` (test-hook).
+- **Schema runner** — `schema::apply_migrations(&mut Connection)`, `schema::applied_count(&Connection)` (used by `clarion install`).
+- **Cache surface** — `summary_cache_lookup`/`upsert_summary_cache`/`touch_summary_cache`, `inferred_edge_cache_lookup`/`upsert_inferred_edge_cache`/`touch_inferred_edge_cache`, `inferred_edge_cache_key_id` (canonical key-id format `"caller|hash|model|prompt"`), plus the four POD types `SummaryCacheKey/Entry`, `InferredEdgeCacheKey/Entry` (`cache.rs:1-251`).
+- **Unresolved-edges surface** — `UnresolvedCallSiteRecord`, `replace_unresolved_call_sites_for_caller(&Connection, …)` (atomic DELETE-then-INSERT per caller_entity_id; `unresolved.rs:20-49`).
+- **Query helpers** — ~29 `pub` items in `query.rs`: row structs (`EntityRow`, `CallEdgeMatch`, `ContainedEntities`, `ResolvedFile`, `ResolvedFileCatalogEntry`, `ModuleDependencyEdge`, `SubsystemMember`, `UnresolvedCallSiteRow`, `ReferenceEdgeMatch`, `ReferenceDirection`, `CanonicalProjectPath`), and lookup functions (`entity_by_id`, `entity_at_line`, `find_entities`, `existing_entity_ids`, `call_edges_from`, `call_edges_targeting`, `reference_edges_for_entity`, `module_dependency_edges`, `subsystem_members`, `subsystem_for_member`, `unresolved_call_sites_for_caller`, `unresolved_callers_for_target`, `candidate_entities_for_unresolved_sites`, `contained_entity_ids`, `child_entity_ids`, `resolve_file`, `resolve_file_catalog_entry`, `entity_briefing_block_reason`, `normalize_source_path`).
+- **Error type** — `StorageError` (`error.rs:5-46`) with `is_foreign_key_violation()` classifier for callers (notably the MCP envelope) that need `retryable=false` on FK breaches.
+- **Helper inventory** — `known_scan_time_edge_kinds()` iterator (`writer.rs:506-511`) exposes the 9-kind ontology to callers that need to validate before sending.
+
+### Dependencies
+- **Inbound (who calls this):** `clarion-cli` (`analyze.rs`, `serve.rs`, `install.rs`, `http_read.rs`, `run_lifecycle.rs`, `secret_scan.rs` + submodules `anchors.rs`/`findings.rs`); `clarion-mcp` (`lib.rs`, `tests/storage_tools.rs`). No other Clarion crate touches it.
+- **Outbound (what this calls):** `clarion-core` for `EdgeConfidence` (`commands.rs:14`) and `manifest::RESERVED_ENTITY_KINDS` (`writer.rs:427`). Cargo-level: `rusqlite` 0.31 (`bundled`), `deadpool-sqlite` 0.8 (`rt_tokio_1`), `tokio` (`sync`, `task::spawn_blocking`), `serde`/`serde_json` (validate `properties_json` shape on inferred edges), `blake3` (declared dep but not imported in `src/`; likely intended for path/hash helpers), `tracing`, `thiserror`.
+- **External services:** SQLite only — one file at `.clarion/clarion.db`, accessed via two distinct connection populations: one writer connection owned by the actor task, and `max_size` reader connections in `deadpool-sqlite`. No network. WAL is the cross-process coordination mechanism between writer and readers.
+
+### Internal architecture
+
+**Concurrency model — single-writer actor + reader pool (ADR-011, repeated verbatim in `lib.rs:1-5`).** All persistent mutations are funnelled through one `tokio::task::spawn_blocking` task that owns the sole write `rusqlite::Connection` (`writer.rs:86-98`). Producers communicate via a bounded `tokio::sync::mpsc::Sender<WriterCmd>` (default capacity 256); each variant carries a `oneshot::Sender` for the per-command ack so callers can fan out N producers (`Writer::sender().clone()`) and still observe each command's outcome (`commands.rs:20`, `writer.rs:998-1060` test `cloned_senders_accept_concurrent_entity_producers`). The actor loop is `rx.blocking_recv()` on the spawn_blocking thread (`writer.rs:152`), not `await` — this is correct because the loop is blocking-thread-resident and must call synchronous `rusqlite` APIs.
+
+**Transaction discipline — per-N-writes batches inside a per-run super-transaction.** `BeginRun` issues `INSERT INTO runs … status='running'` then `BEGIN`. Every successful `InsertEntity`/`InsertEdge`/`InsertFinding`/`ReplaceUnresolvedCallSitesForCaller` increments `state.writes_in_batch`; when it hits `batch_size` (default 50), `bump_writes_and_maybe_commit` issues `COMMIT` then `BEGIN` immediately to re-open. `CommitRun` runs the parent↔contains-edge consistency check inside the still-open transaction (`writer.rs:894-918`), then atomically folds the `UPDATE runs SET status=… completed_at=… stats=…` into the same `COMMIT`. `FailRun` issues `ROLLBACK` then a separate single-statement run-row UPDATE. The actor also has a `cleanup_after_channel_close` (`writer.rs:262-281`) that rolls back any open tx and marks the run failed if the channel is dropped mid-run. `FlushRunBatch` exists to let readers on separate SQLite connections observe in-flight graph rows mid-run by committing and re-opening the batch. The query-time MCP writes (`InsertInferredEdges`, `UpsertSummaryCache`, `TouchSummaryCache`) commit the surrounding run-batch first (if any), execute outside the run transaction, then re-open the run batch — they explicitly do not require an active run (`writer.rs:855-877`).
+
+**Write-side wire contracts (enforced before any SQL).** `enforce_entity_kind_contract` rejects non-`core` plugins emitting `RESERVED_ENTITY_KINDS` (`writer.rs:425-438`). `enforce_edge_contract` (`writer.rs:521-582`) splits the 9-kind ontology into `STRUCTURAL_EDGE_KINDS` (`contains`, `in_subsystem`, `guides`, `emits_finding` — must be `confidence=resolved`, must have NULL byte ranges) and `ANCHORED_EDGE_KINDS` (`calls`, `references`, `imports`, `decorates`, `inherits_from` — must have both byte-start and byte-end, must NOT be `inferred` at scan time); any unknown kind raises `CLA-INFRA-EDGE-UNKNOWN-KIND`. `validate_source_file_anchor` (`writer.rs:444-493`) checks that any `source_file_id` reference points to an entity whose kind is `file` or `module` (the comment at line 442 calls this transitional until core-minted `file` entities land). `parent_contains_mismatch` (`writer.rs:958-1021`) runs two SQL queries — one in each direction — to assert that `entities.parent_id` and `edges WHERE kind='contains'` are bijective; failure aborts the entire run with code `CLA-INFRA-PARENT-CONTAINS-MISMATCH`.
+
+**Idempotence and dedupe semantics.** `InsertEntity` uses `ON CONFLICT(id) DO UPDATE` that preserves `created_at` + `first_seen_commit` while refreshing `updated_at` + `last_seen_commit` (`writer.rs:362-420`); this is what makes `clarion analyze` re-run-safe. `InsertEdge` uses `INSERT OR IGNORE` on natural PK `(kind, from_id, to_id)`; dedupes increment `dropped_edges_total`. `InsertInferredEdges` first DELETEs the caller's existing inferred-tier `calls` edges that don't match the current cache key, then inserts new ones while *also* short-circuiting any pair that already has a `resolved`/`ambiguous` edge (`static_call_edge_exists`, lines 758-771) — that's how query-time LLM inference cohabits with scan-time static facts without double-counting.
+
+**PRAGMA discipline (`pragma.rs:16-45`).** Writer connection: `journal_mode=WAL` (and aborts with `PragmaInvariant` if SQLite returns anything other than `wal`), `synchronous=NORMAL`, `busy_timeout=5000` (5s — but the writer is single-threaded so this only matters against external `sqlite3` shell access), `wal_autocheckpoint=1000` (auto-checkpoint every 1000 frames), `foreign_keys=ON`. Reader connections: only `busy_timeout=5000` + `foreign_keys=ON`, re-applied on every `with_reader` acquisition as a belt-and-suspenders measure since `deadpool-sqlite` has no post-create hook. No `mmap_size`, no `temp_store`, no `cache_size`, no `application_id`, no `user_version` — schema versioning is done in the application-level `schema_migrations` table only.
+
+**Schema migrations (`schema.rs:17-91`).** Single compile-time-embedded migration via `include_str!`. The runner reads applied versions from `schema_migrations`, tolerating the table's absence via `OptionalExtension::optional()` (with an explicit comment at lines 45-49 warning that `.ok()` would silently mask `DatabaseLocked` / `CorruptDb`). Each migration runs in its own `execute_batch` and then an `INSERT OR IGNORE INTO schema_migrations` belt-and-suspenders insert. The migration SQL itself wraps everything in `BEGIN…COMMIT` and inserts its own row. No `application_id` / `user_version` is set — drift / cross-tool collisions on the SQLite file are not detected at the DB level.
+
+**Error model (`error.rs:5-65`).** One `thiserror`-derived enum, ten variants, three derived from external crates (`rusqlite::Error`, three `deadpool_sqlite::*Error` types, `std::io::Error`); six application-shaped (`PragmaInvariant`, `Migration{version, source}`, `InvalidQuery`, `InvalidSourcePath`, `WriterGone`, `WriterProtocol`, `WriterNoResponse`). `is_foreign_key_violation` is a public classifier on SQLite extended code 787, documented as feeding the MCP envelope's `retryable=false` decision.
+
+### Patterns observed
+- **Actor + bounded mpsc channel + oneshot ack-per-command** (`writer.rs:74-140`, `commands.rs:20`). Producers can be cloned freely; back-pressure is the channel's `send().await`.
+- **Per-connection PRAGMA reapply on every reader-pool acquisition** as a workaround for `deadpool-sqlite` having no post-create hook (`reader.rs:96-107`, comment at lines 76-83).
+- **`Arc<()>` identity tag** for proving two `ReaderPool` clones share the same in-process pool, distinct from "same file path" (`reader.rs:25-70`, used by `clarion-cli/src/serve.rs:63-71`'s `Arc::ptr_eq` assertion).
+- **Plain-old-data records at the wire** (`commands.rs:48-133`): `EntityRecord` / `EdgeRecord` / `FindingRecord` / `InferredCallEdgeRecord`. Caller is responsible for timestamps, content_hash, JSON-string encoding; writer inserts verbatim. No serde derivation on these.
+- **Codified error subcodes embedded in error messages** (`CLA-INFRA-RESERVED-ENTITY-KIND`, `CLA-INFRA-SOURCE-FILE-MISSING`, `CLA-INFRA-SOURCE-FILE-KIND-CONTRACT`, `CLA-INFRA-EDGE-CONFIDENCE-CONTRACT`, `CLA-INFRA-EDGE-SOURCE-RANGE-CONTRACT`, `CLA-INFRA-EDGE-UNKNOWN-KIND`, `CLA-INFRA-PARENT-CONTAINS-MISMATCH`). Strings are load-bearing for downstream `runs.stats.failure_reason` parsing.
+- **`WITHOUT ROWID` on the natural-key `edges` table** (migration line 96) and `WITHOUT ROWID`-style PKs on the three cache/unresolved tables — composite PKs are the access path.
+- **FTS5 virtual table kept in sync by AFTER {INSERT,UPDATE,DELETE} triggers** (`migrations:209-238`); summary text is extracted from `summary.briefing.purpose` JSON path.
+- **Generated VIRTUAL columns over JSON properties + partial indexes** (`scope_rank`, `git_churn_count`, lines 245-262) — the CASE-mapped `scope_rank` exists specifically because the project→subsystem→…→function ordering is not lexicographic.
+- **Embedded migrations + edit-in-place policy until first external operator** (migration header lines 10-16) — comment names the retirement trigger for the policy.
+
+### Concerns / Smells / Risks
+- **`query.rs` is 1161 LOC of mostly hand-written SQL strings**. No prepared-statement caching at the module level, no query builder — every helper builds its own SQL with `params!`/`params_from_iter`. Risk: easy to drift between similar helpers; partially mitigated by the 1137-LOC `tests/query_helpers.rs` (close to 1:1 LOC with the production file). Reviewers must check each new query for FK/composite-PK access path.
+- **No `application_id` / `user_version` discipline**. The migration runner is the *only* schema-identity signal — a non-Clarion SQLite file opened at `.clarion/clarion.db` would pass `apply_migrations` if it happened to lack a `schema_migrations` table, and would *fail confusingly* if it has unrelated tables that collide. Cross-tool DB-file drift is not detectable at open time.
+- **`blake3` is a declared dep but unused inside `src/`** (verified by `grep -rn blake3 src/` — no hits). Likely vestigial from an earlier hashing plan; not load-bearing but is build-time waste.
+- **`busy_timeout=5000` is set on *both* connections, but the writer is single-thread**. The 5s only matters if an external `sqlite3` shell or a second Clarion process opens the file. There is no in-process advisory lock (no `cross-process claim-lease` table) — two `clarion analyze` runs against the same `.clarion/clarion.db` would race on `runs` rows and the SQLite writer mutex; the `recover_preexisting_running_runs` step in `clarion-cli/src/run_lifecycle.rs` is the only mitigation, and it's post-hoc.
+- **`writer.rs` is 1074 LOC in one file with ~25 free functions plus the `ActorState` struct**. The match-and-dispatch loop is large; adding a 12th command means touching the `WriterCmd` enum, the match in `run_actor`, *and* the per-command handler — three places. The pattern is clean but the file is approaching "split me" territory.
+- **`reader_pool` test (line 91) uses `max_size = 1`** as the *exhaustion scenario* — fine for the test, but worth flagging that the real production pool sizes in callers are 16 (`serve.rs`) and 4 (`http_read.rs`'s test seam), so the worst-case queue depth under MCP load is `64` (from `ConcurrencyLimitLayer`) waiting on `16` connections plus one writer holding the FS lock — the math hasn't been load-tested in this crate's tests.
+- **`InsertEntity`/`InsertEdge` validate source-file anchors with a `SELECT kind FROM entities WHERE id = ?` per write** (`writer.rs:451-458`). At 500k entities this is 500k extra round-trips during analyze. The query is single-row PK lookup so it's cheap, but it's per-write overhead that the test corpus may not exercise to scale.
+- **Tests are well above 1:1 LOC ratio with production code** (4871 test : 3199 src). Behavioural coverage looks strong (round-trip, idempotence, FK propagation, edge contracts, FailRun rollback, channel-close cleanup, query helpers, cache lifecycle, reader pool concurrency / queueing / panic recovery, schema-apply re-run safety). Concern: there is no fuzz/property-test seam for `WriterCmd` interleavings — only scripted scenarios. The `commits_observed` counter is the canonical batch-cadence oracle and is asserted in `writer_actor.rs:943` (`batch_size_fifty_commits_every_fifty_inserts`), but the channel-close-mid-run cleanup path (`cleanup_after_channel_close`, `writer.rs:262-281`) does not appear to have a dedicated test asserting the run-row is left in `failed` rather than `running`.
+- **`FlushRunBatch` exists for cross-connection visibility but its consumers are external to this crate**. Within `clarion-storage` no test exercises a reader observing a flushed-but-uncommitted-run batch — that contract is asserted from `clarion-cli` / `clarion-mcp` tests instead, so a regression in `FlushRunBatch` semantics would surface as a downstream test failure rather than a unit-level one here.
+
+### Confidence: High
+Read all 10 source files in `src/` end-to-end, plus `migrations/0001_initial_schema.sql` end-to-end, plus skimmed test-function headers in all 5 test files (notably `writer_actor.rs` 2440 LOC). Cross-checked inbound callers via `grep -rn "use clarion_storage"` — only `clarion-cli` (7 files) and `clarion-mcp` (lib + one test) import it. Confirmed `Writer::spawn` and `ReaderPool::open` call sites in `clarion-cli/src/{analyze,serve,http_read}.rs`. The only items I deliberately did not exhaust are the bodies of the read-side query helpers in `query.rs` past line 220 — I read the public surface and signatures, sampled `entity_at_line`/`find_entities`/`call_edges_from` lightly, and trusted the test file (1137 LOC of `query_helpers.rs`) as evidence of behavioural coverage rather than re-deriving each SQL statement.
+
+## 3. clarion-cli
+
+**Location:** `crates/clarion-cli/`
+**LOC:** ~6981 src across 13 `.rs` files (4 of them in `src/secret_scan/`); 5894 LOC tests across 6 integration test files.
+**Crate type / role:** binary crate; produces the `clarion` executable (`[[bin]] name = "clarion"`, `Cargo.toml:12-14`). No `lib.rs`, no inbound Rust callers — this crate is a pure orchestrator that wires `clarion-core`, `clarion-mcp`, `clarion-scanner`, and `clarion-storage` into three subcommands.
+
+### Responsibility
+
+`clarion-cli` owns the operator-facing entry surface: the `clarion` binary, its three subcommands (`install`, `analyze`, `serve`), and all orchestration logic that sits *between* the user invoking the command and the lower-level libraries doing the work. It owns the `.clarion/` filesystem layout (`install.rs:20-100`, `instance.rs:10-86`), the `analyze` pipeline that walks the tree, gates on secrets, fans out to discovered plugins, persists results, and clusters modules into subsystems (`analyze.rs:75-645`), the `serve` supervisor that runs MCP stdio and the Axum HTTP read API as two threads sharing one `ReaderPool` (`serve.rs:20-227`), and the federation HTTP read surface itself (`http_read.rs:363-387` router; `:392-461` bearer + HMAC middleware). The federation-visible `/api/v1/files*` endpoints live in this crate, not in `clarion-mcp` — a noteworthy split.
+
+### Key components
+
+- `src/main.rs:1-78` — binary entry. Three-arm `match` on `cli::Command`; builds a multi-thread tokio runtime *only* for `analyze`. `dotenvy::dotenv()` is loaded for `install`/`serve` but deliberately **skipped for `analyze`** (`main.rs:23-25`) so `.env` contents flow through the secret scanner instead of being imported into plugin subprocess envs. `analyze` exits with `EX_CONFIG=78` on a misconfigured `--allow-unredacted-secrets`.
+- `src/cli.rs:1-63` — clap derive definitions; three subcommands, five `analyze`-time flags.
+- `src/install.rs:109-194` — initialises `.clarion/{clarion.db, config.json, .gitignore}` plus a `clarion.yaml` stub at project root. `populate_after_mkdir` is wrapped in a cleanup guard (`:142-153`) that `rm -rf`s `.clarion/` if any post-mkdir step fails so retry isn't blocked by "already exists".
+- `src/analyze.rs:75-645` — `run_with_options`, the central analyze pipeline. Single async function (~570 LOC) that runs the entire flow described in §"Internal architecture" below.
+- `src/serve.rs:20-227` — `serve::run` + `supervise_stdio_with_http`. Builds the LLM provider (`build_llm_provider:229-291`), opens a 16-conn `ReaderPool`, spawns the HTTP server thread, spawns the MCP stdio thread, then polls the stdio result channel with a 100 ms timeout while periodically checking HTTP health (`:176-202`). On `Arc::ptr_eq` mismatch between the HTTP thread's reported `ReaderPool` identity and the one held in `serve.rs`, `debug_assert!` fires (`:63-71`) — this catches a refactor that re-opens the pool inside `http_read::spawn`.
+- `src/http_read.rs:146-260` — `spawn` / `spawn_with_env`; `:262-311` `run_http_read_server` (binds TCP, sends back ready signal with `ReaderPool` identity captured *after* the move into the runtime thread); `:363-387` `router`; `:392-461` `require_http_identity` + `require_hmac_identity`; `:692-1034` six request handlers (`get_file`, `post_files_batch`, `post_files_resolve`, `get_capabilities`, plus two cfg(test)-only fixtures referenced in `:329-353`).
+- `src/clustering.rs:53-101` — `cluster_modules` entry point + `cluster_modules_with_algorithms` test seam; `:117-145` `leiden_communities` calling `xgraph::graph::algorithms::leiden_clustering`; `:170-224` `local_weighted_components` fallback; `:247-296` directed modularity score; `:103-115` `cluster_hash` = SHA-256 of sorted member IDs truncated to 12 hex chars.
+- `src/secret_scan.rs:202-325` — `pre_ingest`; submodules `anchors.rs` (links scanner detections to plugin-emitted module/file entities), `baseline.rs` (loads `.clarion/secrets-baseline.yaml`), `files.rs` (extension/skip-dir walk + sidecar matcher for `.env`/`.env.*`/`*.env`), `findings.rs` (`PendingFinding` + `FindingRecord` shaping with `CLA-SEC-SECRET-DETECTED` / `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` rule IDs).
+- `src/run_lifecycle.rs:6-44` — two helpers: `recover_preexisting_running_runs` (raw `UPDATE runs SET status='failed' WHERE status='running'` on next start; not routed through the writer-actor because the writer isn't running yet) and `begin_run` (writer `BeginRun` wrapper).
+- `src/instance.rs:44-86` — `InstanceId(Uuid)` newtype persisted to `.clarion/instance_id` with `O_CREAT|O_EXCL` (`mode = 0o600`) → `fsync` → `hard_link` for atomic publish, and `EEXIST`-on-link → read-existing-file race resolution. Federation contract requires a stable per-project ID; this is it.
+
+### Public interface (outbound)
+
+`clarion-cli` exposes no `pub` library API — it has no `lib.rs`. Its public surface is three things:
+
+- **The `clarion` binary CLI** — `clarion install [--force] [--path P]`, `clarion analyze [P] [--config C] [--allow-unredacted-secrets [--confirm-allow-unredacted-secrets TOKEN]] [--allow-no-plugins]`, `clarion serve [--path P] [--config C]` (`cli.rs:13-62`). Confirmation token literal is `"yes-i-understand"` (`secret_scan.rs:38`).
+- **The HTTP read API** — Axum router at `http_read.rs:363-387`. Four production routes (one unprotected):
+  - `GET  /api/v1/files?path=&language=` → `get_file`. Returns `{entity_id, content_hash, canonical_path, language}`; honours `If-None-Match` ETag (= `\"<content_hash>\"`) returning 304. 403 with `BRIEFING_BLOCKED` if entity has `briefing_blocked` property set by secret scan. Protected (bearer or HMAC).
+  - `POST /api/v1/files/batch` body `{queries:[{path,language},…]}` → returns `{resolved[], not_found[], briefing_blocked[], errors[]}`. Hard cap **256** queries/batch (`http_read.rs:608`), runs the whole batch in a single `with_reader` checkout. Protected.
+  - `POST /api/v1/files:resolve` body `{paths:[…]}` → returns `{results:[{path,response:{status,body}}]}` where `status ∈ {resolved,not_found,blocked,error}`. Hard cap **1000** paths (`http_read.rs:609`). Protected.
+  - `GET  /api/v1/_capabilities` → `{registry_backend, file_registry, api_version, instance_id}`. **Unprotected by design** so siblings can probe pre-auth.
+  - Body cap **16 KiB** (`HTTP_BODY_LIMIT_BYTES`, `http_read.rs:610`). Tower stack (`:373-386`): `CatchPanicLayer` (panics → 500 envelope) → `HandleErrorLayer` (panics on unenumerated middleware errors; `:547-556`) → `TraceLayer` → 10 s `TimeoutLayer` → `RequestBodyLimitLayer` → `LoadShedLayer` → `ConcurrencyLimitLayer(64)`. Errors carry an envelope `{error, code}` with `code ∈ {INVALID_PATH, PATH_OUTSIDE_PROJECT, NOT_FOUND, BRIEFING_BLOCKED, UNAUTHENTICATED, STORAGE_ERROR, BATCH_TOO_LARGE, INTERNAL}` (`http_read.rs:590-601`).
+- **`clarion serve`'s stdio MCP server** — owned by `clarion-mcp`. `clarion-cli` calls `clarion_mcp::serve_stdio_with_state_on_runtime` (`serve.rs:150`) and constructs the `ServerState` with the reader pool, optional summary-LLM writer + `LlmProvider`, and optional `FiligreeHttpClient` (`serve.rs:131-147`).
+
+### Dependencies
+
+- **Inbound (who calls this):** No Rust callers — verified by `grep -rn "clarion_cli" crates/` returning empty. This crate is invoked by humans/CI through the `clarion` binary and by `tests/e2e/*.sh` shell scripts.
+- **Outbound (other Clarion crates):** `clarion-core` (`AcceptedEntity`/`AcceptedEdge`, `discover`, `PluginHost`, `CrashLoopBreaker`, `BriefingBlockReason`, `HostError`, `HostFinding`, LLM provider types), `clarion-mcp` (`ServerState`, `config::McpConfig`, `config::HttpReadConfig`, `filigree::FiligreeHttpClient`, `serve_stdio_with_state_on_runtime`, `select_provider_with_env`, `resolve_filigree_http_target`), `clarion-storage` (`Writer`, `WriterCmd`, `ReaderPool`, `module_dependency_edges`, `resolve_file_catalog_entry`, `CanonicalProjectPath`, `StorageError`, `pragma`, `schema`), `clarion-scanner` (`Scanner`, `Detection`, `Baseline`, `SuppressionResult`).
+- **External crates of note:** `axum` 0.7 (HTTP), `tower`/`tower-http` (middleware), `tokio` (runtimes — multi-thread for analyze + HTTP, current-thread for MCP stdio), `clap` (CLI), `xgraph` (Leiden clustering), `ignore::WalkBuilder` (`.gitignore`-honouring tree walk in both `analyze.rs:2016-2026` and `secret_scan/files.rs`), `rusqlite` (one direct `Connection::open` in `analyze.rs:711` to read module IDs/edges during phase 3, bypassing the reader pool), `uuid`, `dotenvy`, `sha2` (HMAC, `cluster_hash`).
+- **External services / processes:**
+  - **SQLite** at `<project>/.clarion/clarion.db`, opened both via `ReaderPool::open` (`serve.rs:53`) and direct `Connection::open` (`run_lifecycle.rs:10`, `analyze.rs:711`, `install.rs:189`).
+  - **Plugin subprocesses** — spawned via `clarion_core::PluginHost::spawn` from `run_plugin_blocking` (`analyze.rs:1322`) on `tokio::task::spawn_blocking` workers.
+  - **TCP listener** for HTTP read API on `config.serve.http.bind` (default `127.0.0.1:9111` per `install.rs:74`); bound by `tokio::net::TcpListener::bind` inside the HTTP thread's runtime (`http_read.rs:279`).
+  - **LLM CLIs and OpenRouter** — wired via `build_llm_provider` (`serve.rs:229-291`); reaches `codex`/`claude` binaries and OpenRouter HTTPS.
+
+### Internal architecture
+
+**Three subcommands, three concurrency shapes.** `install` is fully synchronous (`install.rs:109`). `analyze` builds a multi-thread tokio runtime in `main.rs:36-38` and runs one big `async fn run_with_options` (`analyze.rs:75-645`); per-plugin work happens inside `tokio::task::spawn_blocking` (`analyze.rs:325-339`) using a **Pattern A buffering** strategy named in the module doc (`analyze.rs:6-8`): collect all entities + edges into in-memory `Vec`s inside the blocking task, return them to the async side, then drain into the writer-actor via `WriterCmd::InsertEntity`/`InsertEdge` one-at-a-time with `send_wait` ack-and-block (`analyze.rs:399-447`). `serve` is the most complex (`serve.rs`): a foreground supervisor thread (the process's original thread) polls a `std::sync::mpsc::Receiver` from the spawned `"clarion-mcp-stdio"` thread (current-thread tokio runtime, `:126-130`) while also `check_running`-polling the `"clarion-http-read"` thread (multi-thread tokio runtime, `http_read.rs:355-360`). Identity of the single shared `ReaderPool` is asserted by `Arc::ptr_eq` on the inner `Arc<()>` tag (`serve.rs:63-71`); the HTTP thread captures its identity **after** the pool has been moved into its runtime (`http_read.rs:272-296`), so a refactor that opened a fresh pool inside the HTTP thread would surface immediately rather than silently double-opening WAL.
+
+**Analyze pipeline ordering (`analyze.rs:75-645`, single function):**
+1. Path canonicalisation + `.clarion/` existence check (`:82-91`).
+2. Load `clarion.yaml`-derived `AnalyzeConfig` (clustering knobs only; LLM/serve config is `serve`-only) — `config.rs:16-29`.
+3. **Run-row crash recovery** — `recover_preexisting_running_runs` flips any prior `status='running'` rows to `failed` (`:95-102`, `run_lifecycle.rs:6-26`).
+4. **Spawn writer-actor** + mint run_id (`:105-113`).
+5. **Plugin discovery** — `clarion_core::discover()` scans `$PATH` for `clarion-plugin-*` (`:116-135`). Empty-with-errors → FailRun + non-zero exit (`:142-174`); empty-without-errors → `RunStatus::SkippedNoPlugins` + non-zero exit unless `--allow-no-plugins` (`:176-223`).
+6. **Build the wanted-extensions union** across plugin manifests (`:226-231`).
+7. **Walk the tree** — `collect_source_files` with `ignore::WalkBuilder` honouring `.gitignore` family + a hard-coded skip-dir list (`:234`, `:2013-2065`).
+8. **Pre-ingest secret scan** — `secret_scan::collect_scan_files` (broader walk that includes `.env` sidecars) → `secret_scan::pre_ingest` runs `clarion-scanner` patterns in **parallel via `thread::scope` with `available_parallelism()` workers** (`secret_scan.rs:333-382`), applies the baseline, classifies each file as `Clean`/`Blocked`/`Overridden` (`:237-243`). **The scan happens before `BeginRun` and before any plugin spawn**, so plugin processes never receive `.env` contents in their analyze stream — they receive `briefing_blocked` flags instead.
+9. **`BeginRun`** (`:244`).
+10. **Per-plugin loop** (`:275-470`): filter source files to the plugin's extensions; `spawn_blocking` `run_plugin_blocking` (`analyze.rs:1309-1456`) which (a) calls `PluginHost::spawn` for the JSON-RPC handshake, (b) iterates files calling `host.analyze_file()` with periodic heartbeat logging (`:1272-1307`), (c) collects entities + edges + unresolved-call-sites + per-file stats, (d) issues `host.shutdown()` on success or `child.kill()` on error, (e) reaps the child and classifies SIGKILL/SIGSEGV as likely `RLIMIT_AS` OOM-finding (`:1466-1574`). Per-plugin crashes record on a `CrashLoopBreaker`; >3 crashes / 60 s trips the breaker, drops the remaining plugins, and surfaces `FINDING_DISABLED_CRASH_LOOP` (`:271-272, 349-358`).
+11. **Entity → edge ingestion** for surviving plugins, in order: `InsertEntity` for collected entities, `ReplaceUnresolvedCallSitesForCaller` for query-time-resolvable call sites, then `InsertEdge` (`:399-448`). Order is load-bearing: edges FK-reference entities (`:392-394` comment).
+12. **`persist_findings`** writes the secret-scan findings now that we have anchor entity IDs from plugin output (`:471-481`, `secret_scan/anchors.rs`).
+13. **Phase 3 clustering** (`:500-520`, `run_phase3_clustering` at `:675-906`): `FlushRunBatch`, open a direct read connection, load module entity IDs + module-dependency edges, build `ModuleGraph`, run `cluster_modules`, emit one `core:subsystem:<cluster_hash>` entity + N `in_subsystem` edges per community, emit a `CLA-FACT-CLUSTERING-WEAK-MODULARITY` finding if `modularity_score < weak_modularity_threshold` (default 0.3).
+14. **`CommitRun(Completed)`** / **`CommitRun(Failed)` for soft-fail (some plugins crashed but writer-actor was healthy)** / **`FailRun` for hard-fail (writer-actor rejection or phase 3 error)** (`:543-625`). The hard/soft distinction matters: SoftFailed commits the partial entity batch *and* marks the run failed atomically (`:576-612`); HardFailed rolls back the open transaction via `FailRun`.
+
+**Clustering (`clustering.rs`):** Two algorithms, both deterministic. Leiden via `xgraph::graph::algorithms::leiden_clustering::CommunityDetection::detect_communities_with_config` with `{gamma, resolution, iterations, deterministic: true, seed}` (`:124-131`). If Leiden returns ≤1 community, fall back to a hand-rolled `local_weighted_components` (`:170-224`) keyed on average-positive-edge-weight as the threshold; the algorithm actually used is reported back in `ClusterResult.algorithm_used`. Directed modularity is recomputed locally on the resulting partition (`:247-296`) — `xgraph` returns communities, not the score. `cluster_hash` (`:103-115`) is SHA-256 of sorted member entity IDs truncated to 12 hex chars; this seeds the `core:subsystem:<hash>` entity ID so the same community shape is byte-stable across runs.
+
+**HTTP read API (`http_read.rs`):** Single `Router` built once at `spawn`. Two-layer auth: the **HMAC path is preferred** when `identity_token_env` is set (`:397-398`), falling back to **bearer** when only `token_env` is set, falling back to **trust-loopback** (`auth = "none"`) when neither is set — with an operator-visible WARN at spawn time (`:244-252`). HMAC canonical message is `"{method}\n{path_and_query}\n{hex(sha256(body))}"` (`:478-484`), HMAC is SHA-256 hand-rolled (`:487-509`) — no `hmac` crate dependency. Constant-time compare on both bearer and HMAC paths (`:415, 456, 521-530`). Two failure modes get explicit non-500 statuses: timeout → 408 (`:533-538`), load-shed → 503 (`:540-546`); anything else from `BoxError` is a `panic!()` with the error chain in the message (`:553-556`) — `CatchPanicLayer` turns it into a 500 envelope, but CI sees the missing enumeration.
+
+**Error model:** `anyhow::Result` everywhere at the binary layer (`main.rs:13`, `serve.rs:8`); typed `StorageError` from `clarion-storage` is classified into HTTP `ErrorCode` enum + status by `classify_read_error` (`http_read.rs:1050-1085`).
+
+### Patterns observed
+
+- **Supervisor + worker threads with shared `Arc<()>` identity tag** (`serve.rs:63-71`, `http_read.rs:141-144, 272-296`) — prevents silent double-open of the WAL pool across the refactor surface.
+- **Pattern A buffering** for plugin output: collect-in-blocking-task, send-from-async-task (`analyze.rs:325-339, 399-448`) — keeps the writer-actor single-threaded discipline while letting blocking JSON-RPC reads happen on `spawn_blocking`.
+- **Atomic file publish via hard-link rename** for `instance_id` (`instance.rs:53-86`) — handles racing concurrent installs without an external lock.
+- **Crash-loop breaker as an in-process circuit** (`analyze.rs:271-272, 349-358`) — borrowed from `clarion_core::CrashLoopBreaker`, applied per-run.
+- **Two-pass HTTP body read** in the HMAC path: `to_bytes` to compute the digest, then reconstruct `Request::from_parts(parts, Body::from(body_bytes))` so the handler still sees a normal body (`http_read.rs:442-461`). Necessary because HMAC needs the full bytes, not a stream.
+- **Constant-time secret comparison** on both bearer and HMAC paths (`http_read.rs:521-530`) — defends against timing attacks even on the loopback default.
+- **Test seam via function-pointer injection**: `cluster_modules_with_algorithms` takes the Leiden and weighted-components closures as parameters (`clustering.rs:60-65`); tests substitute hand-rolled communities to force the fallback path (`:457-482`).
+- **`#[cfg(test)]` panic injection** for supervisor testing: `HTTP_THREAD_PANIC_TRIGGER` static atomic that a test can flip to assert the supervisor's runtime-panic arm still fires after `CatchPanicLayer` was introduced (`http_read.rs:321-353`). A rare and disciplined use of cfg-conditional production code.
+- **Run-lifecycle crash recovery before writer-actor spawn** (`run_lifecycle.rs:6-26`, `analyze.rs:95-102`) — raw `rusqlite` `UPDATE` because the writer can't recover its own pre-mortem state.
+
+### Concerns / Smells / Risks
+
+- **`analyze.rs` is 2549 LOC in a single file**, and `run_with_options` itself spans 570 lines (lines 75–645) with `#[allow(clippy::too_many_lines)]` (`:74`). The function is doing path setup, run lifecycle, discovery error policy, no-plugin policy, tree walk, secret scan, per-plugin orchestration, ingestion ordering, soft/hard-fail promotion, phase 3 clustering invocation, and run finalisation — every one of those is a separate change vector. The module doc and inline comments are excellent (some of the most carefully reasoned `//` comments in the workspace), but extracting `discovery_outcome`, `per_plugin_loop`, and `finalise_run` into named functions would materially reduce the surface that has to be re-read on each touch. Watch this file for change-amplification scars over time.
+- **`http_read.rs` is 1723 LOC with all routes, all auth, both error envelopes, and the test-only panic harness in one module**. The separation between protected and unprotected sub-routers is already in place (`:363-372`) — a future refactor could lift each handler family into a sibling module (`files.rs`, `batch.rs`, `resolve.rs`) without changing the router shape.
+- **Two parallel `WalkBuilder` traversals** of the project tree: one in `analyze::collect_source_files` (`analyze.rs:2013`, extension-filtered) and a broader one in `secret_scan::collect_scan_files` (sidecars + same extensions). Both honour `.gitignore`. On a large repo this is two full I/O passes back-to-back; no caching between them.
+- **Phase 3 clustering opens a raw `rusqlite::Connection` bypassing the writer-actor's view of the WAL** (`analyze.rs:711`). The `FlushRunBatch` call at `:705-709` is what makes this safe — the writer-actor must drain its open transaction so the direct connection sees the same module rows. The dependency between `FlushRunBatch` and the subsequent direct read is implicit; a refactor that removes the flush would silently produce empty clusters on a busy run.
+- **HMAC implementation is hand-rolled** (`http_read.rs:487-509`) rather than using the `hmac` + `sha2` crates' `Hmac<Sha256>` type. The code is short and the `constant_time_eq` is paired with it correctly, but a deps-level choice not to pull `hmac` is a maintenance bet — any future HMAC variant (rotation, key derivation) reopens this. Worth tracking.
+- **Unenumerated middleware error → panic → 500 envelope** (`http_read.rs:553-556`). The design intent is sound (force enumeration via CI failure rather than silently swallow), but in production the user sees a 500 with a vague message; the panic message goes to stderr only. The behaviour is deliberate per the inline comment, but it deserves a runbook entry.
+- **`run_with_options` does not bound the in-memory entity buffer**: `collected_entities` and `collected_edges` for a plugin run accumulate every entity for every file in `Vec`s before any are flushed to the writer-actor (`analyze.rs:1337-1419`). On a very large corpus a misbehaving plugin could exceed memory limits before the entity-cap breaker in `clarion-core` trips. The cap exists but lives in the host, not here.
+- **`scanned_files: Arc<BTreeSet<PathBuf>>` is constructed by the secret scan and then shared into every `PluginHost`** so the host can enforce the briefing-block contract on per-file results (`analyze.rs:273-274, 314-315, 333-334`). This is a clean immutable share, but it does mean every plugin process holds (via the host wrapper) a reference to a `BTreeSet` whose footprint scales with the project source count.
+- **No test coverage for the supervisor's "stdio thread exited but result_rx was disconnected" branch** at `serve.rs:194-200` was visible in my sampling pass — only a unit test for `finish_supervised_result` (`:313-325`) and the e2e shell scripts exercise serve. The `tests/serve.rs` file is 3075 LOC, so this is probably covered; flagged for explicit verification.
+- **`recover_preexisting_running_runs` swallows error context one level** by going through `anyhow!("{err}")` (`run_lifecycle.rs:12-14`) — typed `StorageError` info is folded into a plain string. Mild.
+
+### Confidence: High
+
+Read every source file in `src/` end-to-end except `analyze.rs`, where I read the module doc, all top-level fn signatures, `run_with_options` lines 75-645 in full, `run_phase3_clustering` lines 675-906, `run_plugin_blocking` lines 1309-1456, the source walk lines 2013-2065, and the time helper. Read `http_read.rs` lines 1-260 (transport / spawn / supervisor identity), 260-461 (server bootstrap + auth + HMAC), 692-1034 (handlers + capabilities), 1036-1085 (error classifier), 1107-1148 (logging + panic envelope). Read all four `secret_scan/` submodule heads. Listed inbound callers (`grep -rn "clarion_cli"`) and confirmed none — this is a leaf binary. Did **not** read the test files end-to-end (5894 LOC), only their line counts and the cfg(test) harness inside `http_read.rs` and `clustering.rs`. The 20 MCP tool surface and `clarion-mcp::ServerState` shape are cited only via the call sites at `serve.rs:131-147, 150`, not by reading `clarion-mcp`.
+
+## 4. clarion-mcp
+
+**Location:** `crates/clarion-mcp/`
+**LOC:** 6,595 source (`lib.rs` 4,703 + `config.rs` 1,600 + `filigree.rs` 292) / 2,233 test (`tests/storage_tools.rs`)
+**Crate type / role:** Library crate. Implements the MCP (Model Context Protocol) JSON-RPC tool surface that consult-mode LLM agents call to query Clarion's index; not a binary — the `clarion serve` binary in `clarion-cli` consumes this library and drives the stdio loop.
+
+### Responsibility
+
+`clarion-mcp` owns the JSON-RPC tool dispatch layer and the stdio transport that fronts Clarion's index for external agents. It defines the twenty MCP tools (`list_tools` at `src/lib.rs:56`), translates MCP `tools/call` requests into bounded `clarion-storage` reader queries, mediates LLM-dispatch for on-demand summaries and inferred call edges with token-budget reservation (`BudgetLedger` at `lib.rs:2244`, `reserve_budget` at `lib.rs:2066`), and brokers Filigree enrichment lookups over HTTP. It also owns the YAML configuration schema (`McpConfig` at `config.rs:9`) consumed by `clarion serve` for LLM provider selection, Filigree integration, and the (separate) HTTP read-API bind/auth posture. The crate exposes its surface via `ServerState`, `serve_stdio*`, `handle_json_rpc`, and `list_tools`, and is consumed exclusively by `clarion-cli` (see Inbound below).
+
+### Key components
+
+- `src/lib.rs:56-258` — `list_tools()`: the canonical 20-tool registry with names, descriptions, and JSON schemas. Single source of truth; `handle_tool_call` validates names against it (`lib.rs:401`).
+- `src/lib.rs:316-2210` — `ServerState`: the stateful dispatcher. Holds `ReaderPool`, optional `SummaryLlmState` (writer mpsc + provider), optional `FiligreeLookup`, an `AnalyzeProcess` slot, a clock, an `InferredInflight` coalescer (`lib.rs:43`), and a `BudgetLedger`. Per-tool handlers (`tool_entity_at` at 493 … `tool_subsystem_members` at 1229) sit on `ServerState`.
+- `src/lib.rs:2704-2876` — Transport: `handle_frame*`, `read_stdio_frame`, `serve_stdio`, `serve_stdio_with_state`, `serve_stdio_with_state_on_runtime`. Implements dual framing (LSP-style `Content-Length` and JSON-line) auto-detected from the first non-whitespace byte (`peek_stdio_frame_start` at 2774).
+- `src/lib.rs:1560-2030` — Inferred-edge dispatch pipeline: cache lookup (`read_inferred_inputs` 1624), in-flight coalescing via `tokio::sync::broadcast` (`InferredInflightGuard` 2438; `coalesced_inferred_dispatch`), budget reservation, LLM provider invocation via `spawn_blocking` (`invoke_llm` 2218), and writer-channel persistence (`WriterCmd::InsertInferredEdges` at 1682/1824).
+- `src/lib.rs:2237-2290` — `AnalyzeProcess` + `BudgetLedger` + `BudgetReservation`: spawns `clarion analyze` as a detached child for `analyze_start`/`analyze_status`/`analyze_cancel`; tracks reserved-vs-spent LLM tokens with a `Mutex`-guarded ledger.
+- `src/config.rs:9-742` — `McpConfig` (YAML, `serde_norway`): `LlmConfig` (provider kind, model id, session token ceiling, per-caller inferred-edge cap, cache TTL), provider-specific subsections (`OpenRouterConfig`, `CodexCliConfig`, `ClaudeCliConfig`), `FiligreeConfig` (base URL, project key, token env, actor, timeout), `HttpReadConfig` (bind, loopback trust, bearer + identity HMAC env vars), and `select_provider_with_env` (677) which builds an `LlmProvider` honoring `recording_fixture_path` and `allow_live_provider`.
+- `src/filigree.rs:1-292` — Filigree HTTP client: `FiligreeLookup` trait (52), blocking-reqwest implementation `FiligreeHttpClient` (64), URL builder `entity_associations_url` (148), and response shape `EntityAssociationsResponse` (11).
+
+### Public interface (outbound)
+
+- **20 MCP tools** (the consult-agent contract, from `list_tools`):
+  1. `entity_at` — innermost entity containing `(file, line)`; path-normalized against project root.
+  2. `project_status` — orientation snapshot: index age, latest run, graph counts, git state, plugin discovery, LLM policy, Filigree routing, analyze lifecycle.
+  3. `analyze_start` — spawn background `clarion analyze` child; supports `allow_no_plugins`.
+  4. `analyze_status` — child process state + latest persisted `runs` row.
+  5. `analyze_cancel` — kill the background analyze child if running.
+  6. `find_entity` — paginated FTS-ranked search over entity id/name/short-name/summary; does *not* search `summary_cache`.
+  7. `source_for_entity` — line-numbered source span with bounded context; includes decorator lines.
+  8. `entity_context` — resolve by id or `(file,line)`; returns containing stack + source + diagnostics.
+  9. `call_sites` — caller/callee evidence with source snippets at recorded byte offsets.
+  10. `callers_of` — callers, default confidence `resolved`; opt-in to `ambiguous` (expand candidates) or `inferred` (may trigger LLM dispatch).
+  11. `execution_paths_from` — bounded calls-only traversal; default `max_depth=3`, hard `execution_edge_cap` (default 500, settable via `with_edge_cap`).
+  12. `execution_paths_ranked` — compact ranked path view; optional `exclude_tests`, `max_paths`.
+  13. `summary` — on-demand cached *leaf* summary; module entities return scope-deferred policy envelope, not aggregation.
+  14. `summary_preview_cost` — cache status, model/provider, token estimate, live-spend requirement; no dispatch.
+  15. `issues_for` — Filigree associations for an entity, optionally `include_contained`; returns `unavailable` envelope if Filigree disabled rather than failing.
+  16. `orientation_pack` — deterministic first-pass packet (status, source, callers, callees, issues, next reads); no LLM.
+  17. `index_diff` — freshness signals: latest run, DB mtime, source files newer than index, changed entity hashes.
+  18. `neighborhood` — one-hop graph (callers, callees, container, contained, references).
+  19. `subsystem_members` — module entities for a subsystem entity.
+  20. (twentieth slot) `summary_preview_cost` and `summary` count separately; full enumeration above totals 19 visible — the registry actually contains 19 entries, not 20. **Note:** the discovery doc cites "twenty tools"; the registry as of `lib.rs:56-257` contains 19 distinct `ToolDefinition` entries. Flagging in Concerns.
+- **Rust API:**
+  - `pub fn list_tools() -> Vec<ToolDefinition>` (`lib.rs:56`).
+  - `pub fn handle_json_rpc(&Value) -> Option<Value>` (`lib.rs:295`) — state-free metadata-only path (`initialize`, `tools/list`).
+  - `pub struct ServerState` with builder methods `new`, `with_edge_cap`, `with_summary_llm`, `with_clock`, `with_filigree_client` (`lib.rs:316-376`); `ServerState::handle_json_rpc(&Value) -> Option<Value>` (377).
+  - `pub fn serve_stdio`, `serve_stdio_with_state`, `serve_stdio_with_state_on_runtime` (`lib.rs:2831-2876`).
+  - `pub fn handle_frame`, `handle_frame_with_state` (`lib.rs:2704-2721`) — frame-level entry points for callers that own their own loop.
+  - `pub enum McpError` (`lib.rs:2690`), `pub const MCP_PROTOCOL_VERSION = "2025-11-25"` (`lib.rs:40`).
+- **Config API (`config` module):** `McpConfig::from_path`, `McpConfig::from_yaml_str`, `select_provider_with_env`, `resolve_filigree_http_target`, `resolve_filigree_base_url`, `HttpReadConfig::{validate_loopback_trust, validate_auth_trust, is_loopback_bind}`.
+- **Filigree API (`filigree` module):** `FiligreeLookup` trait, `FiligreeHttpClient::from_config`, `entity_associations_url`, `parse_entity_associations_response`.
+
+### Dependencies
+
+- **Inbound (who calls this):**
+  - `crates/clarion-cli/src/serve.rs:13-150` — sole production caller. Imports `config::{McpConfig, LlmConfig, select_provider_with_env, ...}`, `filigree::FiligreeHttpClient`, `ServerState::new`, `with_summary_llm`, `with_filigree_client`, `serve_stdio_with_state_on_runtime`. Spawns the stdio loop on a named thread `clarion-mcp-stdio`.
+  - `crates/clarion-cli/src/http_read.rs:18` — reuses `clarion_mcp::config::HttpReadConfig` to drive the *separate* HTTP read-API server (which is implemented in `clarion-cli`, not here).
+  - `crates/clarion-cli/src/install.rs:68` — references the literal string `"clarion-mcp"` in template output (the default Filigree actor).
+- **Outbound (what this calls):**
+  - `clarion-core` (`plugin::{Frame, TransportError, ContentLengthCeiling, read_frame, write_frame}`; LLM primitives `LlmProvider`, `LlmRequest`, `LlmResponse`, `LlmProviderError`, `LlmPurpose`, `build_inferred_calls_prompt`, `build_leaf_summary_prompt`, `INFERRED_CALLS_PROMPT_VERSION`, `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `InferredCallsPromptInput`, `LeafSummaryPromptInput`, `EdgeConfidence`).
+  - `clarion-storage` — read side via `ReaderPool::with_reader` (~30 call sites including `entity_at_line`, `entity_by_id`, `find_entities`, `call_edges_from`, `call_edges_targeting`, `reference_edges_for_entity`, `child_entity_ids`, `contained_entity_ids`, `existing_entity_ids`, `subsystem_members`, `summary_cache_lookup`, `inferred_edge_cache_lookup`, `inferred_edge_cache_key_id`, `unresolved_call_sites_for_caller`, `unresolved_callers_for_target`, `candidate_entities_for_unresolved_sites`, `normalize_source_path`); write side strictly via `WriterCmd` over `mpsc::Sender<WriterCmd>` — only three variants emitted: `InsertInferredEdges` (twice, `lib.rs:1682`/`1824`), `TouchSummaryCache` (`lib.rs:1924`), `UpsertSummaryCache` (`lib.rs:2024`).
+  - External crates: `tokio` (current-thread runtime, `AsyncMutex`, `mpsc`, `oneshot`, `broadcast`, `spawn_blocking`), `reqwest::blocking` (Filigree), `rusqlite` (re-exported types only — no direct `Connection::open`; all DB access flows through `ReaderPool`/`WriterCmd`), `serde_norway` (YAML config), `time`, `blake3`, `thiserror`, `tracing`.
+- **External services:**
+  - **SQLite** via `clarion-storage::ReaderPool` — read concurrency; writes only via the writer-actor channel.
+  - **Subprocess: `clarion analyze`** — spawned by `tool_analyze_start` using `std::env::current_exe()` (`lib.rs:572-599`), stdin/stdout/stderr null'd.
+  - **Filigree HTTP** — blocking `reqwest` GET to `{base_url}/api[/p/{project_key}]/entity-associations?entity_id=...` with `x-filigree-actor` and bearer auth (`filigree.rs:98-127`).
+  - **LLM providers** — pluggable `Arc<dyn LlmProvider>` invoked via `tokio::task::spawn_blocking` (`lib.rs:2218`); config chooses OpenRouter (HTTP), Codex CLI, Claude CLI, or a deterministic Recording fixture (`config.rs:677`).
+
+### Internal architecture
+
+The crate is a single stateful dispatcher (`ServerState`) plus a thin stdio I/O loop. `ServerState::handle_json_rpc` (`lib.rs:377`) routes `initialize` and `tools/list` to static helpers, and `tools/call` to `handle_tool_call` (394) which dispatches on tool name via a 19-arm `match` (`lib.rs:413-488`). Each `tool_*` handler is `async`, takes the argument map, parses required/optional params (`required_str`, `optional_bool`, …), and either returns a JSON envelope or a `ParamError` that becomes a JSON-RPC error response. Storage reads flow through `self.readers.with_reader(|conn| …)`, which offloads onto the reader pool's blocking workers; the handler awaits the result and wraps it in `envelope_from_storage_result`.
+
+**Concurrency model.** The crate is built around a borrowed Tokio current-thread runtime (`serve_stdio_with_state_on_runtime` accepts `&Runtime` from the caller; `serve_stdio_with_state` builds its own). The dispatch path is fully async, but the stdio I/O is synchronous: the loop does a blocking `read_stdio_frame` on `&mut impl std::io::BufRead`, then `runtime.block_on(handle_stdio_frame_with_state(...))`, then a blocking `write_stdio_response`. There is no parallel request handling — frames are processed strictly sequentially per stdio session. Three internal concurrency primitives matter:
+  1. `BudgetLedger` behind a `std::sync::Mutex` (`lib.rs:322`) — gates LLM dispatch with a reserve/commit pattern and a `blocked` latch.
+  2. `InferredInflight` — `Arc<AsyncMutex<HashMap<InferredEdgeCacheKey, broadcast::Sender<...>>>>` (`lib.rs:43`) — coalesces concurrent `callers_of`/inferred-edge requests for the same `(caller_id, content_hash, model_id, prompt_version)` tuple so only one LLM call fires; followers subscribe via `broadcast` and `RAII`-clean up via `InferredInflightGuard` (`lib.rs:2438`).
+  3. `analyze_process` — a `std::sync::Mutex<Option<AnalyzeProcess>>` slot for the at-most-one in-flight `clarion analyze` child.
+
+**State ownership.** `ServerState` owns the `ReaderPool`, the optional writer `mpsc::Sender<WriterCmd>` (cloned out of `SummaryLlmState` per dispatch), the optional Filigree client behind `Arc<dyn FiligreeLookup>`, the `clock` (injectable for tests), and the analyze-process slot. The writer-actor itself lives in `clarion-cli/src/serve.rs:135-144`, not here — `clarion-mcp` is a writer *client*, never a writer host.
+
+**Transport.** The stdio frame reader auto-detects between LSP-style `Content-Length` framing (delegated to `clarion_core::plugin::read_frame`/`write_frame`) and bare-JSON-line framing by peeking the first non-whitespace byte (`lib.rs:2757-2789`). The choice is per-frame, recorded in `StdioFrame::framing`, and reused on the response. JSON-RPC notifications (method present, id absent) are silently dropped (`is_json_rpc_notification` at `lib.rs:2740`). Test `serve_stdio_handles_multiple_content_length_frames` (`lib.rs:4309`) and `serve_stdio_with_state_uses_json_line_transport_for_json_line_requests` (4400) pin the dual-framing contract.
+
+**Error model.** Two layers: `McpError` (`lib.rs:2690`) — `Json | Transport | Runtime` — surfaces only from frame I/O and JSON decode failures and aborts the loop; per-tool errors stay inside the JSON-RPC response as either error responses (`ParamError`) or success envelopes with `tool_error_envelope(code, message, retryable)` (e.g. `analyze-already-running`, `analyze-start-failed`, `token-ceiling-exceeded`, `llm-disabled`, `invalid-path`). The retryability flag is on the wire, not just in logs. `ConfigError` (`config.rs:742`) uses stable string error codes (`CLA-CONFIG-*`) so the CLI can route them.
+
+### Patterns observed
+
+- **Tool registry as single source of truth** — `list_tools()` validates incoming names at dispatch (`lib.rs:401`) and is also served verbatim to `tools/list`; adding a tool requires both a registry entry and a `match` arm, but the unreachable arm (`lib.rs:487`) is documented by the prior validation.
+- **Reader pool + writer-actor split** — every DB read goes through `ReaderPool::with_reader` (~30 sites); every DB write goes through `mpsc::Sender<WriterCmd>` with an `oneshot` ack (`send_writer` helper at `lib.rs:2043`). The crate never opens a `rusqlite::Connection` directly.
+- **Coalescing + RAII guards for expensive async work** — `InferredInflightGuard` and `BudgetReservation` both use `Drop` to release in-flight slots / reserved tokens even if the awaiting future is cancelled (`lib.rs:2278-2290`, `2471-2486`). The `Drop` paths for guards spanning runtime boundaries use `tokio::runtime::Handle::try_current` to schedule async cleanup.
+- **Dual-framing transport with byte-peek detection** — same `serve_stdio` loop handles LSP-style and JSON-line clients without configuration (`lib.rs:2757`).
+- **Capability gating via `Option<…>` builder fields** — LLM features (`summary_llm`) and Filigree enrichment (`filigree_client`) are off unless `with_summary_llm` / `with_filigree_client` is called. Tool handlers check for `None` and return policy envelopes (`llm-disabled`, Filigree `unavailable` envelope) rather than failing.
+- **Stable error-code strings on the wire** — both tool envelopes (`token-ceiling-exceeded`, `analyze-already-running`, `invalid-path`) and config errors (`CLA-CONFIG-HTTP-NO-AUTH`, `CLA-CONFIG-FILIGREE-PORT-CONFLICT`, etc.) use prefix-namespaced identifiers callers can switch on.
+- **Recording-provider determinism hook** — `LlmConfig.recording_fixture_path` (`config.rs:78`) + `select_provider_with_env` (677) let tests pin LLM responses without network calls; the test suite at `tests/storage_tools.rs` uses `RecordingProvider` heavily.
+
+### Concerns / Smells / Risks
+
+- **`lib.rs` is 4,703 lines in a single file.** This is the dominant smell. It contains the tool registry, all 19 tool handlers, transport, framing, budget ledger, inflight coalescer, analyze-process management, error/envelope helpers, and ~700 lines of unit tests (`mod tests` at `lib.rs:4309`+). A natural split is at least three files: `tools/` (one module per tool family), `transport.rs` (stdio framing), `dispatch.rs` (inferred-edge + summary LLM machinery). Risk: merge conflicts, slow IDE feedback, hard to review.
+- **Discovery doc says "twenty tools"; registry contains 19.** Enumerated above. Either the doc is stale or a tool was removed without updating discovery; worth confirming against the design intent. Flagging because the prompt called this out as a precise characterization target.
+- **Dispatch is purely sequential.** `serve_stdio_with_state_on_runtime` does `runtime.block_on(...)` inside the loop and a blocking read between frames. A slow LLM-dispatching `summary` or `callers_of` request blocks all subsequent tool calls on the same stdio session. The reader pool is internally concurrent but it doesn't help here. For consult-agent UX this is probably fine; for multi-agent or long-LLM-call scenarios it is a wall.
+- **`reqwest::blocking` inside an async dispatcher.** `FiligreeHttpClient::associations_for` (`filigree.rs:98`) is synchronous and is called from `tool_issues_for` (`lib.rs:1154`) which is `async`. The call appears to happen on whatever thread the `block_on` is running, blocking the current-thread runtime for the configured timeout (default 5s). Should be `spawn_blocking`-wrapped or moved to `reqwest`'s async client.
+- **Writer-channel coupling.** All writer commands flow through the `summary_llm.writer` field — which means inferred-edge writes are gated on the *summary* LLM being configured (`inference_llm_snapshot` at `lib.rs:2093` clones from `summary_llm`). Two LLM features share one writer handle and one config slot. Functional today (one writer per process), but the naming overloads "summary" to mean "any LLM-related writes."
+- **Mutex poisoning swallowed everywhere.** Every `self.analyze_process.lock()`, `self.budget.lock()`, etc. uses `.unwrap_or_else(std::sync::PoisonError::into_inner)` (e.g. `lib.rs:556`, `2061`, `2284`). This silently masks the panic that caused the poisoning. Acceptable as a deliberate "keep serving" choice but worth a comment.
+- **`config.rs` is 1,600 lines** with the YAML schema, three provider config blocks, two HTTP trust-validators, provider selection, and a sizable error enum. Splitting per provider would help.
+- **Test coverage is heavily integration-tested in `tests/storage_tools.rs`** (2,233 LOC, ~35 `#[tokio::test]`s observed) but the in-`lib.rs` unit tests (`lib.rs:4309+`) are narrow — mostly transport framing. The inferred-edge coalescing logic is intricate and would benefit from focused unit tests independent of full storage seeding.
+- **No timeout on `tool_analyze_start` child.** The spawned `clarion analyze` runs unbounded; `analyze_cancel` is the only stop. If the agent forgets to poll, the child can outlive the session.
+- **Filigree client is held behind `Arc<dyn FiligreeLookup>` but `FiligreeHttpClient` itself wraps `reqwest::blocking::Client` (already `Clone`).** The `dyn` indirection is fine for test substitution; just noting that the trait has exactly one production impl plus test fakes.
+
+### Confidence: High
+
+Read `lib.rs` lines 1-260 and 250-600 end-to-end, plus targeted reads of the LLM/budget/coalescing region (1600-1690, 2040-2310), the transport region (2680-2876), and supporting helpers. Read `filigree.rs` end-to-end (292 lines), `config.rs` lines 1-410 plus targeted reads. Confirmed the inbound caller surface by grepping all `clarion_mcp` / `clarion-mcp` references in `crates/` (one consumer: `clarion-cli`, three call sites in `serve.rs` / `http_read.rs` / `install.rs`). Confirmed writer-channel use by enumerating all `WriterCmd::` and `send_writer` sites (4 emission points, 3 distinct variants). Tool count verified by reading the registry block 56-257 directly — registry contains 19 entries, flagged against the discovery doc's claim of 20.
+
+## 5. clarion-scanner
+
+**Location:** `crates/clarion-scanner/`
+**LOC:** 881 source (`lib.rs` 233 + `patterns.rs` 303 + `baseline.rs` 285 + `entropy.rs` 60) / 655 test (`tests/scanner.rs`)
+**Crate type / role:** Library crate (`pub` API consumed by `clarion-cli`); pure CPU, no I/O except baseline YAML read.
+
+### Responsibility
+
+Owns Clarion's pre-ingest secret-detection pass: given an in-memory byte buffer, emit a deduplicated, byte-offset-anchored list of `Detection` records identifying secret-shaped substrings, plus a YAML-backed baseline mechanism that suppresses operator-acknowledged matches at the `(file, rule_type, hashed_secret, line_number)` granularity. The crate is deliberately scoped to detection + suppression — it does not walk the filesystem, decide which files to scan, emit findings, or report results; those concerns live in `clarion-cli/src/secret_scan/*`. Stores only positions, rule identifiers, and a detect-secrets-compatible SHA-1 digest of matched bytes — literal secret values do not leave the call (`lib.rs:1-5`).
+
+### Key components
+
+- `src/lib.rs:23-46` — `Detection` struct + `SecretCategory` enum: closed taxonomy with 9 categories (CloudCredential, VcsCredential, AiProviderCredential, PaymentsCredential, MessagingCredential, PrivateKey, JwtToken, HighEntropy, ContextualCredential).
+- `src/lib.rs:49-99` — `HashedSecret([u8; 20])` newtype: SHA-1 digest with hex round-trip (`from_hex`, `Display`); decoupled from `sha1::Sha1` impl detail at the public surface.
+- `src/lib.rs:102-200` — `DetectSecretsRule` enum: 14-variant closed vocabulary aligned to detect-secrets type names; `as_str()`/`rule_id()`/`FromStr` provide bidirectional mapping between human label (baseline YAML) and stable rule-id string (findings).
+- `src/patterns.rs:25-71` — `Scanner` struct: pre-compiles a `RegexSet` (fast first-pass match) plus per-pattern `Regex` (for captures), holds entropy regexes and tunings; `Default`/`new()` build the ADR-013 v0.1 floor.
+- `src/patterns.rs:79-162` — `scan_bytes()` + `scan_entropy()`: two-pass detection — named patterns first, entropy fallback over non-overlapping ranges; outputs sorted by `(byte_offset, rule_id)`.
+- `src/patterns.rs:194-269` — `default_pattern_meta()`: the 12-entry rule floor (literal source of detection truth).
+- `src/baseline.rs:11-44` — `Baseline`, `BaselineEntry`, `BaselineMatch`, `SuppressionResult` types: model the suppression file shape and the result envelope (allowed/suppressed/fired).
+- `src/baseline.rs:104-144` — `Baseline::suppress()`: O(detections × entries_per_file) match using exact `(hashed_secret, line_number, rule_type)` triple as the suppression key.
+- `src/baseline.rs:146-217` — `from_raw()` validation pipeline: version check (`"1.0"` only), path safety (`validate_baseline_path`), mandatory `justification`, hex-hash validity, closed rule-type vocabulary.
+
+### Public interface (outbound)
+
+Re-exported through `lib.rs:11-16`:
+
+- `Scanner` (`patterns.rs:25`) — owns compiled regexes; cheap to construct once and reuse. Method: `scan_bytes(&self, buf: &[u8]) -> Vec<Detection>`.
+- `Detection` (`lib.rs:23-32`) — one match: `rule_id`, `detect_secrets_type`, `category`, `byte_offset`, `line_number`, `matched_len`, `hashed_secret`.
+- `DetectSecretsRule`, `SecretCategory` (`lib.rs:36-46`, `102-118`) — closed enums for downstream pattern-matching.
+- `HashedSecret`, `HexDigestError` (`lib.rs:49-99`) — opaque hash newtype.
+- `Baseline`, `BaselineEntry`, `BaselineEntryIssue`, `BaselineMatch`, `BaselineError`, `SuppressionResult` (`baseline.rs`) — operator-baseline model + error taxonomy with 7 variants (`UnsupportedVersion`, `MissingJustifications`, `InvalidPath`, `InvalidHash`, `UnsupportedRuleType`, `Parse`, `Io`).
+- `load_baseline(&Path) -> Result<Baseline, BaselineError>` (`baseline.rs:71-77`) — accepts a missing file as `Baseline::empty()` (graceful absence).
+- `EntropyTuning` (`entropy.rs:5-23`) — exposed but only `BASE64` and `HEX` consts are constructed internally; `min_len` + `min_entropy` fields.
+- `PatternMeta` (`patterns.rs:10-15`) — exposed via `Scanner::pattern_meta()`, primarily for introspection.
+
+### Dependencies
+
+- **Inbound (who calls this):** Only `clarion-cli`:
+  - `clarion-cli/src/secret_scan.rs` imports `Detection`, `Scanner`, `SuppressionResult`.
+  - `clarion-cli/src/secret_scan/baseline.rs` imports `Baseline`, `BaselineError`.
+  - `clarion-cli/src/secret_scan/findings.rs` imports `Detection`, `SecretCategory`, `DetectSecretsRule`, `HashedSecret`.
+- **Outbound (what this calls):** No internal Clarion crates. External: `regex` (bytes flavour), `sha1`, `serde` + `serde_norway` (YAML), `thiserror`.
+- **External services:** None directly. Reads the baseline file via `std::fs::read_to_string` (`baseline.rs:72`); no other I/O. Pure-function `scan_bytes` over an `&[u8]`.
+
+### Internal architecture
+
+Three modules + `lib.rs` umbrella. `lib.rs` owns the shared value types (`Detection`, `HashedSecret`, `DetectSecretsRule`, `SecretCategory`) and two tiny helpers — `sha1_digest` (`lib.rs:208-214`) and `line_number_for_offset` (`lib.rs:216-224`, a byte-by-byte newline count over the prefix). Concurrency is **none** — there is no shared mutable state; `Scanner` is `Send + Sync` by construction (only immutable compiled regexes), so callers parallelize at the file-level outside the crate (and `clarion-cli/src/secret_scan.rs:scan_source_files_parallel` does exactly that).
+
+`patterns.rs` runs detection in two layers. Layer 1: `RegexSet` first-pass (`patterns.rs:80`) over the whole buffer — only patterns whose set-membership matched then have their full `Regex` run for capture extraction (`patterns.rs:83-87`). Layer 2: entropy fallback (`scan_entropy`, `patterns.rs:128-161`) runs the base64 candidate regex `[A-Za-z0-9+/]{20,}={0,2}` and hex candidate `\b[a-fA-F0-9]{40,}\b`, skipping candidates that **overlap any already-found named match** (`range_overlaps`, `patterns.rs:271-275`). The base64 fallback additionally requires non-base64 boundary bytes on each side (`base64_candidate_has_boundaries`, `patterns.rs:277-281`) — a hand-rolled `\b`-equivalent because `=` is not a word character.
+
+Entropy is parameterized by two `EntropyTuning` constants:
+- `BASE64`: `min_len = 20`, `min_entropy = 4.5` (`entropy.rs:11-14`).
+- `HEX`: `min_len = 40`, `min_entropy = 3.0` (`entropy.rs:15-18`).
+
+Entropy itself is Shannon entropy in bits/symbol over byte frequency (`entropy.rs:25-41`) using a `BTreeMap<u8, usize>` count table, computed as `-Σ p_i log2(p_i)`. These thresholds are deliberately wide: tests `entropy_minimum_lengths_are_pinned` (`tests/scanner.rs:171-174`) and the lockfile-SHA fixture (`tests/scanner.rs:568-638`) document that the hex threshold *intentionally* fires on git SHAs and npm lockfile integrity hashes — the v0.1 stance is to suppress via baseline rather than tighten the rule and risk missing real secrets.
+
+The `KeywordDetector` rule (`patterns.rs:262-267`) is contextual: a Python/`.env`-shaped `name = "value"` assignment with name ∈ {`password`, `passwd`, `secret`, `token`, `api_key`, `secret_token`}, captured value ≥ 8 chars. To avoid false positives on commented-out examples, `scan_bytes` filters `ContextualCredential` matches whose line begins with `#` (`patterns.rs:91-94, 290-303`). The comment-handling is explicitly Python/shell-only — `//` and `/* */` comments are *not* skipped (tests at `tests/scanner.rs:162-167` lock this in deliberately).
+
+`baseline.rs` is a value-typed YAML parser + suppression engine. The on-disk shape is a `version: "1.0"` envelope with `results: {path: [entry, ...]}` (`baseline.rs:237-253`). Parse-time validation rejects: non-1.0 versions, absolute or `..`-bearing paths, missing/blank `justification` (collected exhaustively — `from_raw` walks all entries before returning the error, see `baseline.rs:153-172` and the test at `tests/scanner.rs:408-433`), unknown detector-type strings, and invalid hex hashes. Suppression is deliberately exact-match: same path, same rule, same hash, same line number — *and* `is_secret: false` (a `true` entry, or omitted field defaulting to `true` per `default_is_secret` at `baseline.rs:255-257`, does **not** suppress; tests at `tests/scanner.rs:300-385` lock this in).
+
+Error model is `thiserror`-derived (`baseline.rs:45-69`) with no panics in the parse path. The detection path has two `expect` calls in `Scanner::new` (`patterns.rs:51, 56-57, 66-69`) — all on compile-time constant regex literals, so they fire only on programmer error during edits, not on runtime input.
+
+### Patterns observed
+
+- **Two-phase regex matching** (`patterns.rs:80-87`) — `RegexSet` for cheap any-match prefilter, individual `Regex` only for matched indices. Trades memory for avoiding O(rules × text) capture work.
+- **Closed enum at the interface, string only at the wire** — `DetectSecretsRule` (`lib.rs:102-118`) forces every consumer to handle the full vocabulary; conversions live at the YAML boundary (`baseline.rs:179-186`) so unknown types fail fast.
+- **Capture-group routing via `Option<usize>`** (`patterns.rs:14, 96-103`) — `KeywordDetector` and `AwsSecretAccessKey` capture an inner group so the hash is over just the secret literal, not the `name="value"` framing.
+- **Boundary-aware regex via helper functions** (`patterns.rs:277-303`) — Rust's `regex` crate's `\b` doesn't handle base64 padding `=` or `#`-comments, so the crate composes regex + post-filter.
+- **Exhaustive error collection** for `MissingJustifications` (`baseline.rs:153-172`) — operator sees all missing entries at once, not one per re-run.
+- **Path safety as a parse-time invariant** (`baseline.rs:219-235`) — absolute paths, `..`, drive prefixes all rejected at load; eliminates a class of suppression-escape attacks at the YAML boundary rather than at match time.
+- **Cross-tool format compatibility by design** — the SHA-1 hash, the rule-name vocabulary, and the YAML schema all mirror Yelp's `detect-secrets` baseline format (cited explicitly in `lib.rs:1-5`), so operators familiar with that tool can reuse baselines.
+
+### Concerns / Smells / Risks
+
+- **`scan_bytes` is O(named_detections × entropy_candidates)** via `range_overlaps`'s linear scan (`patterns.rs:271-275`). For a file with hundreds of named matches and hundreds of entropy candidates this is quadratic. No interval tree, no sort-and-binary-search. For the target corpus (425k LOC Python, ADR-013 mentions) this is likely fine but worth flagging if scanner runtime ever becomes an issue.
+- **`Baseline::suppress` is O(detections × entries_per_file)** with linear scan over the entries for that path (`baseline.rs:111-137`). Acceptable while baseline files are small (~tens of entries) but no index by `(rule, hash, line)`.
+- **`usize_to_f64` truncates above 2³² bytes** (`entropy.rs:43-45`). For >4 GB files entropy will compute as if the buffer were 2³² bytes. Practically irrelevant — file-level scanning is bounded long before this — but the silent saturation deserves a comment.
+- **Contextual-comment handling is Python/`.env`-only** (`patterns.rs:290-303`). A `// password = "..."` line in a JavaScript file *will* fire `ContextualCredential` (locked in by test at `tests/scanner.rs:163-167`). The crate's docstring acknowledges this; the cost is operator-baseline pollution in non-Python codebases until detector context is added.
+- **`Scanner::new` panics on regex compile failure** (`patterns.rs:48, 51, 56, 66, 69`). These are compile-time literals so this is unreachable in shipping builds, but the public API has no fallible constructor — a future operator-provided pattern set would need a new constructor surface.
+- **Entropy thresholds embed false-positive policy in code, not configuration** (`entropy.rs:11-18`). The test fixture explicitly documents that lockfile/git-SHA noise is *intentional* and the answer is operator baseline. This is a deliberate v0.1 trade-off but it pushes calibration burden to every operator until configurable thresholds or per-file-extension tuning lands.
+- **`PatternMeta::capture_group` is private but the type is `pub`** (`patterns.rs:10-15`) — external consumers can read the struct via `Scanner::pattern_meta()` but can't construct one. This is fine as a closed API but the asymmetry is slightly awkward.
+- **No fuzz or property tests** in `tests/scanner.rs` — only example-based assertions. Regex engines under pathological input (catastrophic backtracking) are a known foot-gun; the crate uses Rust's `regex` (which is linear-time by construction) so this is mitigated, but a quickcheck pass would be cheap insurance.
+
+### Confidence: High
+
+Read all 4 source files end-to-end (881 LOC), the full 655-line test file, the crate's `Cargo.toml`, and cross-checked inbound usage by greping the workspace for `clarion_scanner` imports (only `clarion-cli/src/secret_scan/*` and the scanner's own tests). Confirmed pre-ingest invocation timing at `clarion-cli/src/analyze.rs:237-243` (runs before plugin-host extraction, feeds `briefing_blocks` into the rest of the pipeline). Test file is unusually rich — it locks in not only positive/negative detection cases but also the *intentional* false positives (lockfile SHAs) with the documented operator-baseline workaround. No mystery code remains.
+
+## 6. clarion-plugin-fixture
+
+**Location:** `crates/clarion-plugin-fixture/`
+**LOC:** 187 source (3 `lib.rs` + 184 `main.rs`); 0 in-crate tests — exercised externally by 931 LOC of test code in `clarion-core` and `clarion-cli`.
+**Crate type / role:** Binary crate (`[[bin]] name = "clarion-plugin-fixture"`) plus a stub `lib.rs` whose only job is to let Cargo resolve the workspace member cleanly. Functionally a **test-only protocol-reference plugin**: a minimal, correct implementation of the L4 JSON-RPC wire contract used to drive the plugin host's subprocess code paths without needing the Python plugin on `PATH`.
+
+### Responsibility
+
+This crate owns the *smallest valid implementation* of the Clarion plugin protocol — just enough to (a) prove `clarion-core::plugin::host` can spawn a child, negotiate `initialize`/`initialized`/`analyze_file`/`shutdown`/`exit`, and round-trip framed JSON-RPC, and (b) deterministically misbehave on demand (RLIMIT_AS exhaustion via `CLARION_FIXTURE_EXCEED_RLIMIT_AS`) so the host's OOM-kill and crash-loop-breaker paths can be tested end-to-end. It is intentionally not a real analyzer: every `analyze_file` returns the same single hard-coded widget entity regardless of the input file's content. The crate's "public surface" is therefore (1) the binary itself, consumed by `cargo nextest` via `CARGO_BIN_EXE_clarion-plugin-fixture`, and (2) the fixture identity tuple (`plugin_id=fixture`, kind `widget`, qualname `demo.sample`, rule-ID prefix `CLA-FIXTURE-`) that tests assert against verbatim.
+
+### Key components
+
+- `src/main.rs:23-123` — the JSON-RPC dispatch loop: blocking `read_frame` → parse → match on `method` → either no-op (notification) or send a typed result envelope. Uses `clarion-core` framing and request/response types directly so the wire shape stays in lockstep with the host.
+- `src/main.rs:67-76` — `initialize` handler: emits `InitializeResult { name, version, ontology_version: "0.1.0", capabilities: {} }`.
+- `src/main.rs:77-115` — `analyze_file` handler: extracts `file_path` from params, returns one entity (`fixture:widget:demo.sample`, `kind=widget`, `qualified_name=demo.sample`, `source.file_path=<input>`), no edges, default stats.
+- `src/main.rs:48-60` — notification dispatch for `initialized` (becomes-ready, no reply) and `exit` (process-exits-0, no reply).
+- `src/main.rs:78-83, 137-184` — the `CLARION_FIXTURE_EXCEED_RLIMIT_AS` escape hatch: on Unix, repeatedly `mmap_anonymous` doubling-size regions with `PROT_NONE` to blow past `RLIMIT_AS`, then `SIGKILL` self via `nix::sys::signal::kill`. The mappings are held but never dereferenced (documented `SAFETY` comment).
+- `src/main.rs:125-135` — `send_result` helper: wraps a `Value` in `ResponseEnvelope { jsonrpc, id, payload: Result(...) }`, serialises, frames via `write_frame`, flushes.
+- `src/lib.rs:1-3` — three-line doc-only stub explaining why the lib target exists.
+
+### Public interface (outbound)
+
+The plugin speaks the L4 JSON-RPC protocol on stdin/stdout. Methods implemented:
+
+- **`initialize`** (request) — returns `InitializeResult` with `ontology_version=0.1.0`, empty capabilities. `src/main.rs:68-76`
+- **`initialized`** (notification) — accepted, no-op. `src/main.rs:51-53`
+- **`analyze_file`** (request) — accepts `AnalyzeFileParams`, returns one canned entity. `src/main.rs:77-115`
+- **`shutdown`** (request) — returns empty `ShutdownResult`. `src/main.rs:116-119`
+- **`exit`** (notification) — `process::exit(0)`. `src/main.rs:54-56`
+
+Any unknown method, malformed frame, or unparseable JSON causes `process::exit(1)` (`src/main.rs:33-39, 46, 57, 64, 97, 120`).
+
+Companion manifest (consumed by host, not shipped by this crate): `crates/clarion-core/tests/fixtures/plugin.toml` declares `plugin_id="fixture"`, `language="fixture"`, `extensions=["mt"]`, `entity_kinds=["widget"]`, `edge_kinds=["uses"]`, `rule_id_prefix="CLA-FIXTURE-"`.
+
+### Dependencies
+
+- **Inbound (who consumes the binary):**
+  - `crates/clarion-core/tests/host_subprocess.rs` — direct subprocess test of `PluginHost::spawn`; locates the binary via `CARGO_BIN_EXE_clarion-plugin-fixture` (`host_subprocess.rs:30`) with a `cargo build` fallback (`:84-94`). Asserts entity id `fixture:widget:demo.sample` (`:162`).
+  - `crates/clarion-cli/tests/wp2_e2e.rs` — declares `clarion-plugin-fixture` as a `[dev-dependencies]` entry (`clarion-cli/Cargo.toml:43`) so nextest exports the env var, symlinks the binary into a synthetic plugin dir, and drives the full `clarion analyze` CLI through it. Tests: `wp2_e2e_smoke_fixture_plugin_round_trip` (line 135), `wp2_rlimit_as_oom_kill_is_reported_as_host_finding` (line 259, uses `CLARION_FIXTURE_EXCEED_RLIMIT_AS`), `wp2_crash_in_one_plugin_does_not_prevent_other_plugins_from_running` (line 323), `wp2_crash_loop_breaker_trips_and_skips_remaining_plugins` (line 471).
+- **Outbound (what this calls):**
+  - `clarion-core::plugin::transport` — `read_frame` / `write_frame` / `Frame` for length-prefixed framing.
+  - `clarion-core::plugin::limits::ContentLengthCeiling::DEFAULT` (8 MiB per ADR-021 referenced in source comment, `main.rs:30-32`).
+  - `clarion-core::plugin` request/response DTOs: `AnalyzeFileParams`, `AnalyzeFileResult`, `AnalyzeFileStats`, `InitializeResult`, `ShutdownResult`, `JsonRpcVersion`, `ResponseEnvelope`, `ResponsePayload`.
+  - `serde_json` for ad-hoc `Value` parsing of the inbound request envelope.
+  - `nix` (Unix only, `mman` + `signal` features) — only for the deliberate-OOM probe.
+- **External services:** None at runtime. Communicates only over inherited stdin/stdout with its parent (the plugin host).
+
+### Internal architecture
+
+The binary is a single synchronous loop in `main()` (`main.rs:23-123`); there are no modules, threads, async runtime, or background tasks. State machine is implicit and minimal: the loop accepts notifications and requests in any order after the host has spoken — there is no explicit "before-initialize" guard, which is acceptable because the host always sends `initialize` first and the fixture's responses are stateless. The shape is `loop { read_frame → parse Value → branch on (has_id, method) → dispatch }`.
+
+Error model is intentionally brutal: any deviation from the happy path (truncated frame, non-UTF8, missing method, unknown method, unparseable params) calls `std::process::exit(1)` with no reply. This is *desired* behaviour — `clarion-core`'s host has to handle a plugin that hangs up mid-stream, and crashing the fixture is the cheapest way to drive that path. The crash-loop-breaker test (`wp2_e2e.rs:471`) depends on this.
+
+The `exceed_rlimit_as` path (`main.rs:137-184`) is the only piece of nontrivial logic. It pre-reserves 1024 mapping handles before the memory pressure starts (so the `Vec::push` itself does not allocate after the kernel starts refusing maps), then loops `mmap_anonymous(PROT_NONE, MAP_PRIVATE)` doubling the request size each iteration starting at 128 MiB. PROT_NONE means no physical pages are committed — only address space is consumed, which is exactly what `RLIMIT_AS` constrains. When the next request would not grow (`saturating_mul(2)` saturated) or `mmap` returns `Err`, the fixture `SIGKILL`s itself so the parent observes a signal-death, not a clean exit. This is the load-bearing detail that distinguishes OOM-kill from a controlled shutdown in the host's diagnosis.
+
+`lib.rs` exists solely so the crate works as a workspace member with a binary target (3 lines, doc comment only).
+
+### Patterns observed
+
+- **Stub lib + real bin** (`lib.rs:1-3` + `Cargo.toml:12-14`) — workspace-member compatibility trick.
+- **Untyped envelope parse, typed payload re-parse** (`main.rs:37-44, 93-98`) — read the whole frame as `serde_json::Value` to inspect `id`/`method` before committing to a typed struct, so unknown/malformed messages can be rejected without spurious deserialisation errors.
+- **Crash-on-anomaly as a feature** (`main.rs:33-46, 57, 97, 120`) — every error path is `process::exit(1)`. Tests want this behaviour.
+- **Hard-coded fixture identity** (`main.rs:101-108`) — `"fixture:widget:demo.sample"` is the ground-truth string tests assert on; do not change without updating both call sites listed under Inbound.
+- **Environment-flag-driven fault injection** (`main.rs:78-83`) — `CLARION_FIXTURE_EXCEED_RLIMIT_AS` toggles the OOM path; default behaviour is benign.
+- **PROT_NONE address-space probe** (`main.rs:137-178`) — exhausts virtual address space cheaply (no page commits) to trip a specific kernel limit deterministically.
+- **Pre-reserved Vec to avoid allocation under memory pressure** (`main.rs:142-145`).
+
+### Concerns / Smells / Risks
+
+- **`process::exit(1)` everywhere with no diagnostic output.** Reasonable for a test fixture (the host is the system under test), but if a future test asserts on stderr or a specific exit code other than 1, every error branch will need disambiguating. No `eprintln!` anywhere. `main.rs:33-46, 57, 97, 120`.
+- **No "initialize must come first" sequencing check.** A misbehaving host could call `analyze_file` before `initialize` and the fixture would happily respond. This is fine today because the host always sequences correctly, but the fixture is not a conformance checker — do not use it as one.
+- **`unwrap()` on `serde_json::to_value(InitializeResult)`** (`main.rs:75`) and other result serialisations — defensible because the types are `Serialize`-derived, but pedantically these are crash points.
+- **Unix-gated OOM path with a `cfg(not(unix))` arm that just `exit(1)`s** (`main.rs:78-83`) — Windows CI would silently lose coverage of the RLIMIT_AS branch. Acceptable since OOM-kill semantics are Unix-specific.
+- **The manifest lives in another crate's test tree** (`clarion-core/tests/fixtures/plugin.toml`), not in this crate. Discoverable only by `grep`. Two callers (`host_subprocess.rs` and `wp2_e2e.rs`) construct their own variants of it. A `tests/fixtures/plugin.toml` here, re-used by both, would be cleaner; not urgent.
+- **Hard-coded `version = "0.1.0"` and `ontology_version = "0.1.0"`** in the binary (`main.rs:71-72`) do not pick up the workspace version — if version-handshake logic ever depends on these, they will drift from `Cargo.toml`. Currently the host does not validate them.
+- **No in-crate tests.** Justified: the fixture *is* the test apparatus for two upstream test files. Counting test coverage of this crate in isolation is meaningless.
+
+### Confidence: High
+
+Read all 187 source lines end-to-end, the companion manifest in `clarion-core/tests/fixtures/plugin.toml`, and grepped both consumer tests (`host_subprocess.rs`, `wp2_e2e.rs`) for every reference to `clarion-plugin-fixture`, `fixture:widget:demo`, and `CLARION_FIXTURE_EXCEED_RLIMIT_AS` to confirm the protocol surface and the four named test cases. Inbound dep edges verified via `Cargo.toml:43` of `clarion-cli`. Outbound dep edges verified by walking every `use clarion_core::` import in `main.rs`.
+
+## 7. Python language plugin (`clarion-plugin-python`)
+
+**Location:** `plugins/python/`
+**LOC:** 3028 source / 3440 test (`extractor.py` 932, `pyright_session.py` 1406, `server.py` 296, the rest ≤ 75 each)
+**Crate type / role:** Standalone PEP 517 package (hatchling) installing the `clarion-plugin-python` console script; hosts an L4 JSON-RPC plugin process driven by the Rust core over stdio. Ships its `plugin.toml` to `share/clarion/plugins/python/plugin.toml` via `pyproject.toml:38-44`.
+
+### Responsibility
+Owns Python-source ingestion for Clarion: parses `*.py` to an AST, emits `module` / `class` / `function` entities with stable 3-segment EntityIds, anchors structural `contains` and `imports` edges directly, and delegates type-resolved `calls` / `references` edges to a managed pyright-langserver subprocess. It is the *only* component in the workspace that holds Python `ast` semantics and the only Loom-suite-facing surface that probes Wardline (`wardline_probe.py:35-56`) for the L8 integration handshake. Public surface to the core is exactly the five JSON-RPC methods declared in `server.py:237-240` plus the manifest at `plugin.toml`.
+
+### Key components
+- `src/clarion_plugin_python/__main__.py:14-15` — entry point bound to `[project.scripts] clarion-plugin-python = ...:main`; installs stdio guard then runs `serve()`.
+- `src/clarion_plugin_python/server.py:73-128, 143-232, 243-296` — Content-Length framing reader/writer, dispatch table, handlers for `initialize` / `analyze_file` / `shutdown`, and the per-25-files pyright restart policy (`MAX_FILES_PER_PYRIGHT_SESSION = 25`, defined at `server.py:49`, used at `server.py:215-219`).
+- `src/clarion_plugin_python/extractor.py:256-371` — top-level `extract` / `extract_with_stats`; the `_walk` recursion at lines 763-842 emits entities + `contains` edges; `_ImportEdgeCollector` at 396-468 emits `imports` edges; `_ReferenceSiteCollector` at 532-659 produces reference sites for the resolver.
+- `src/clarion_plugin_python/entity_id.py:23-75` — L2 3-segment EntityId assembler; mirrors the Rust validator (`[a-z][a-z0-9_]*` grammar, no `:`, no empty segment).
+- `src/clarion_plugin_python/qualname.py:34-48` — reconstructs CPython `__qualname__` from the AST parent chain (class-nested vs `parent.<locals>.child`).
+- `src/clarion_plugin_python/pyright_session.py:131-890` — `PyrightSession`: subprocess lifecycle, LSP framing, function/entity index builder, `resolve_calls` (callHierarchy) and `resolve_references` (definition/typeDefinition). 1406 lines; the load-bearing class plus helpers `_build_function_index` (893-925) and `_collect_entities` (928-1006).
+- `src/clarion_plugin_python/stdout_guard.py:25-62` — replaces `sys.stdout` with a write-refusing shim so libraries cannot corrupt the host's JSON-RPC frame parser.
+- `src/clarion_plugin_python/wardline_probe.py:35-56` — imports `wardline.core.registry` + reads `wardline.__version__`; returns one of `absent` / `enabled` / `version_out_of_range`.
+
+### Public interface (outbound)
+- **Binary:** `clarion-plugin-python` (bare basename per `plugin.toml:8`, enforced by ADR-021 layer-1 path-component refusal in the core's discovery).
+- **JSON-RPC methods (server.py:237-272):**
+  - `initialize(params{project_root}) → {name, version, ontology_version="0.6.0", capabilities{wardline}}` (`server.py:143-156`).
+  - `initialized` — notification, flips `state.initialized = True` (line 250).
+  - `analyze_file(params{file_path}) → {entities, edges, stats}` (`server.py:179-232`); gated by `_ERR_NOT_INITIALIZED` if called before `initialized` (line 263).
+  - `shutdown() → {}` — closes the pyright child (line 255-260).
+  - `exit` — notification; loop returns `0` if shutdown was requested, `1` otherwise (`server.py:286-287`).
+- **Wire shapes** declared as `TypedDict`s in `extractor.py:88-142` (`RawEntity`, `RawEdge`, `SourceRange`) and `call_resolver.py:11-22`, `reference_resolver.py:28-39` — these match the host's `RawEntity` / `RawEdge` deserialise contracts cited inline at `extractor.py:9-22`.
+- **Manifest surface:** `plugin.toml` advertises `plugin_id="python"`, `entity_kinds=["function","class","module"]`, `edge_kinds=["contains","calls","references","imports"]`, `ontology_version=0.6.0`, `rule_id_prefix="CLA-PY-"`, `wardline_aware=true`, and pyright pin `1.1.409`.
+
+### Dependencies
+- **Inbound (who calls this):** the Rust plugin host. Confirmed via `grep` hits in `crates/clarion-core/src/plugin/{discovery.rs:60, manifest.rs:150-748, protocol.rs:656, host.rs:519}` and `crates/clarion-mcp/src/lib.rs:526`. The core spawns the binary, speaks Content-Length-framed JSON-RPC, and consumes `entities` / `edges` / `stats`.
+- **Outbound (what this calls):** none of the other Clarion crates directly — the plugin is a pure subprocess. It does cross-product import `wardline.core.registry` + `wardline` purely as a capability probe (`wardline_probe.py:38-39`), fail-soft.
+- **External services:**
+  - `pyright-langserver --stdio` subprocess (`pyright_session.py:637-644`), pin `1.1.409` (`pyproject.toml:20`, `plugin.toml:29`). Resolved via venv-sibling first, then `shutil.which` (`pyright_session.py:699-706`). Bounded by `init_timeout=30s`, `call_timeout=5s`, per-file budget `3s`, `MAX_PYRIGHT_RESTARTS_PER_RUN=3`, `MAX_REFERENCE_SITES_PER_FILE=2000`.
+  - Python `packaging.version.Version` for Wardline range parsing (`wardline_probe.py:30`).
+- **Cross-language fixture:** consumes `fixtures/entity_id.json` at `tests/test_entity_id.py:25` — same rows the Rust assembler validates against; this is the byte-for-byte parity proof for L2 EntityId construction.
+
+### Internal architecture
+**Process / I/O model.** The plugin is a single-threaded JSON-RPC dispatch loop (`server.py:275-287`) reading Content-Length-framed frames from `stdin`, writing replies to a captured `stdout` byte stream. Before any framing happens, `install_stdio()` (`stdout_guard.py:57-62`) captures the real `sys.stdin.buffer` / `sys.stdout.buffer` and replaces `sys.stdout` with `_GuardedTextStdout`, which raises `StdoutGuardError` on any write — this is the plugin-side resolution of WP2's UQ-WP2-08 framing-corruption risk. Frame size is capped at 8 MiB (`MAX_CONTENT_LENGTH`, `server.py:48`) on both inbound and outbound to match the host's ceiling.
+
+**Extraction pipeline (per `analyze_file`).** `handle_analyze_file` (`server.py:179-232`) reads the file text, relativises the path to `project_root` for the qualified-name prefix only (`_resolve_module_path`, lines 158-176), and calls `extract_with_stats` with the project-relative prefix and the live `PyrightSession` as both `call_resolver` and `reference_resolver`. The extractor (`extractor.py:274-371`) always emits exactly one `module` entity (whole-file cover, `end_col=0` sentinel — see the module-docstring caveat at lines 49-53), then `_walk` (lines 763-842) recursively emits one `function` per `FunctionDef`/`AsyncFunctionDef` and one `class` per `ClassDef`. Each non-module entity carries `parent_id` and contributes one `contains` edge (ADR-026 dual encoding, lines 845-851). PEP-484 `@overload` stubs are dropped pre-emit (`_has_overload_decorator`, lines 741-760); any surviving same-id collision is dropped first-wins with stderr + `duplicate_entities_dropped_total` bump (lines 803-810). `imports` edges are collected separately by an `ast.NodeVisitor` (lines 396-468); relative imports compute the base package via `_relative_import_base_parts` (lines 499-510) with package-vs-module awareness keyed on `is_package_module`. Reference sites are gathered by a third visitor (lines 532-659) that maintains a `bound_stack` of locally-bound names per scope and suppresses lambdas + `Call` callees (the latter is the `calls` edge's territory).
+
+**Pyright integration.** `PyrightSession` (`pyright_session.py:131-890`) spawns `pyright-langserver --stdio` as a `subprocess.Popen` (line 637), drives it as an LSP client over Content-Length framing (`_write_message`/`_read_message`, lines 800-834), with a daemon stderr-drain thread keeping a 64 KiB tail (`_drain_stderr`, 723-730). Initialize sends `processId`, `rootUri`, and `workspaceFolders` (lines 682-697); when pyright requests `workspace/configuration`, the session responds with `diagnosticMode=openFilesOnly`, `indexing=false`, `useLibraryCodeForTypes=false`, and an explicit `exclude` list for `.git/.venv/__pycache__/...` (`_configuration_for_section`, lines 774-788). Call resolution opens the file (`textDocument/didOpen`), runs `textDocument/prepareCallHierarchy` per function, then `callHierarchy/outgoingCalls`, and translates the returned URIs/selectionRanges back into Clarion entity IDs via a parallel AST-built `_FunctionIndex` cache keyed on `Path.resolve()` (`_function_index_for_path`, lines 861-870). Edges are grouped by `fromRanges` and emitted as `resolved` or `ambiguous` (`pyright_session.py:394-411`). The session augments pyright's static graph with two heuristic dispatch detectors: `_ambiguous_dict_dispatches` (callable-dict lookup patterns) and `_dunder_call_dispatches` (instances whose class has `__call__`) — both produce additional ambiguous-candidate edges. Reference resolution (lines 427-511) issues `textDocument/definition` per site with an `annotation`-kind fallback to `textDocument/typeDefinition`, caches per `(from_id, kind, lexeme)` triple, and accumulates edges by `(from_id, to_id)` pair.
+
+**Resilience model.** Three tiers: (1) **timeouts** — per-request via `_budgeted_timeout`, per-file via `_deadline_for_file` (lines 531-550), with init/call/file knobs all overridable per `__init__`. (2) **restart cap** — `_record_restart_or_poison` (lines 599-615) restarts pyright up to `MAX_PYRIGHT_RESTARTS_PER_RUN=3`, then permanently disables call resolution by setting `_disabled=True` (emits `CLA-PY-PYRIGHT-POISON-FRAME`). (3) **server-side restart-by-attrition** — `server.py:215-219` closes and re-creates the `PyrightSession` every 25 analyzed files. All failure modes degrade gracefully: missing pyright (`absent` install), failed handshake, timeouts, and the reference-site cap all return zero edges plus a `Finding` with subcode `CLA-PY-PYRIGHT-*` (`pyright_session.py:34-41`).
+
+**Error model.** JSON-RPC errors use codes `-32600` / `-32601` / `-32603` / `-32002` (`server.py:52-55`); any handler exception becomes a `_ERR_INTERNAL` response (line 270-271). Framing-level violations (bad headers, oversize Content-Length, JSON decode failure) raise `ProtocolError`, which `main()` translates to exit code `1` (`server.py:295-296`). `ast.SyntaxError` during extraction emits one degraded `module` entity with `parse_status="syntax_error"` + a stderr line (lines 325-335) — the run continues.
+
+### Patterns observed
+- **Single-process dispatch loop with explicit lifecycle states** — `ServerState.initialized` / `shutdown_requested` gating; `analyze_file` rejected before `initialized` (`server.py:263-264`).
+- **Subprocess-as-service with restart cap + capability disable** — `PyrightSession._disabled` poisons the resolver permanently after N failures (lines 600-609); analysis continues without type-resolved edges.
+- **Dual encoding of structural relationships** — every non-module entity carries `parent_id` *and* a corresponding `contains` edge (extractor.py:813, 845-851), per ADR-026.
+- **Parallel AST builds for entity emission vs LSP cross-walking** — `extractor.py` and `pyright_session._build_function_index` (line 893) each parse the file with `ast.parse` for distinct purposes; the index is cached per `Path.resolve()` in the session (line 861).
+- **Stdout discipline via type substitution** — `_GuardedTextStdout` raises on every write rather than silently swallowing (`stdout_guard.py:36-41`).
+- **TypedDict wire-shape contracts mirroring Rust serde structs** — `RawEntity`, `RawEdge`, `CallsRawEdge`, `ReferencesRawEdge`, `Finding` are statically checked under `mypy --strict` and called out in source comments as host-matching (`extractor.py:9-22`, `call_resolver.py:14-22`).
+- **Cross-language fixture-driven parity** — `fixtures/entity_id.json` is consumed by both this plugin's tests and the Rust assembler tests; the validator code is intentionally duplicated rather than shared (`entity_id.py:56-75`).
+
+### Concerns / Smells / Risks
+- **`pyright_session.py` is 1406 lines in a single module** containing the `PyrightSession` class (≈760 lines) plus ~600 lines of free-function helpers (call-site visitors, dispatch heuristics, LSP helpers, byte-offset arithmetic). The class itself is cohesive but the helper sprawl makes the file hard to navigate; the AST-index builder (`_build_function_index`, `_collect_entities`) duplicates traversal work the extractor already does, suggesting an opportunity to fold the index into `extractor.py` and let the session consume it.
+- **`extractor.py` carries three separate `ast.NodeVisitor` walks** (`_walk` recursion, `_ImportEdgeCollector`, `_ReferenceSiteCollector`) plus a fourth in `pyright_session._collect_entities`. Each walks the same tree with slightly different bookkeeping. No measurable performance bug observed in tests, but future maintenance touching scope semantics (e.g., `match`/`case` introducing bindings, `walrus` operator) has four call sites to keep in sync.
+- **Dispatch heuristics are pattern-based and fragile** — `_has_overload_decorator` admits only bare `overload` / `typing.overload` / `typing_extensions.overload` (lines 753-759); aliased imports defeat it and rely on the deduplication safety net. Same shape for `_ambiguous_dict_dispatches` and `_dunder_call_dispatches` in `pyright_session.py:1158-1303` — they will silently miss anything pyright also misses unless the source matches a known pattern.
+- **Per-file pyright restart at 25 files is a magic constant** (`server.py:49`), separate from the 3-restart-cap inside the session. The interaction between server-driven recycling and session-driven failure restarts is not centrally documented in code; if both fire on the same run the failure semantics depend on ordering.
+- **`StdoutGuardError` is raised but never caught by `server.serve`** — a stray write in any handler will bubble through `dispatch`'s broad `except Exception` (line 270) and become an `_ERR_INTERNAL` response with the guard message in plain text. That is probably correct behaviour, but the design implication (guard violations become normal-looking JSON-RPC errors instead of hard exits) is not stated.
+- **`shutdown` handler kills the pyright child synchronously inside dispatch** (`server.py:257-259`); a misbehaving pyright that ignores `shutdown` would extend the host's view of plugin termination by up to ~4s (two `process.wait(timeout=2)` calls in `PyrightSession.close`, lines 191-194). The host's circuit breaker is the backstop, but the plugin does not log when it falls back to `kill()`.
+- **Test coverage is heavy** (test LOC > source LOC; nine pytest files including pyright-marked integration tests), but `pyproject.toml:94` marks the pyright tests as opt-in via the `pyright` marker — easy to skip in environments without the langserver and not obvious from the test names whether a green run actually exercised the LSP path.
+
+### Confidence: High
+Read all 11 source files end-to-end (extractor.py, server.py fully; pyright_session.py covering `PyrightSession` and the main helpers ~600 of 1406 lines closely, the dispatch-heuristic visitors at signature level), the plugin manifest, `pyproject.toml`, and the round-trip + fixture-parity tests. Cross-checked inbound callers via `grep` against `crates/clarion-{core,mcp}/` (5 distinct call sites). One specific number I did not verify by reading source: the `MAX_FILES_PER_PYRIGHT_SESSION` constant is `25` per `server.py:49`, cited above. The relevant integration boundary (Rust `RawEntity` / `RawEdge` deserialise contract) was confirmed only via the docstring references in `extractor.py:9-22` and `call_resolver.py` typeddicts — not by reading the Rust side, which is out of this subsystem's scope.
diff --git a/docs/arch-analysis-2026-05-22-1924/03-diagrams.md b/docs/arch-analysis-2026-05-22-1924/03-diagrams.md
new file mode 100644
index 00000000..d02776fd
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/03-diagrams.md
@@ -0,0 +1,386 @@
+# 03 — Architecture Diagrams (Clarion)
+
+> Derived exclusively from `01-discovery-findings.md`, `02-subsystem-catalog.md`,
+> and small confirmation reads of `crates/clarion-storage/src/writer.rs`,
+> `crates/clarion-mcp/src/lib.rs`, and `crates/clarion-core/src/plugin/host.rs`.
+> No design docs, ADRs, or sprint narratives were read. Every node in every
+> diagram traces to a file in the workspace; residual uncertainties are listed
+> at the bottom.
+
+---
+
+## 1. C4 System Context — Clarion in its environment
+
+```mermaid
+flowchart TD
+    dev["Developer<br/>(CLI user)"]
+    agent["Consult-mode LLM agent<br/>(MCP client)"]
+    peer["Federation peer<br/>(HTTP API consumer)"]
+
+    subgraph clarion_sys["Clarion system<br/>(single 'clarion' binary + plugins)"]
+        clarion["clarion<br/>(install / analyze / serve)"]
+    end
+
+    sqlite[("SQLite<br/>.clarion/clarion.db<br/>(embedded, WAL)")]
+    plugins["Language plugin<br/>subprocesses<br/>(e.g. clarion-plugin-python)"]
+    pyright["pyright-langserver<br/>(transitive, owned by Python plugin)"]
+    openrouter["OpenRouter<br/>(LLM HTTPS API)"]
+    cli_llm["LLM CLI binaries<br/>(claude / codex)"]
+    filigree["Filigree<br/>(sibling product, HTTP)"]
+    wardline["Wardline<br/>(import-probe only,<br/>Python plugin side)"]
+
+    dev -- "argv (install/analyze/serve)" --> clarion
+    agent -- "stdio MCP<br/>(Content-Length JSON-RPC,<br/>protocol 2025-11-25)" --> clarion
+    peer -- "HTTPS read API<br/>(/api/v1/files*,<br/>bearer or HMAC)" --> clarion
+
+    clarion -- "embedded rusqlite<br/>(WAL, FK on)" --> sqlite
+    clarion -- "JSON-RPC over stdio pipes<br/>(Content-Length framing,<br/>5 methods)" --> plugins
+    plugins -- "LSP JSON-RPC<br/>over stdio pipes" --> pyright
+    clarion -- "HTTPS<br/>(reqwest, chat completions)" --> openrouter
+    clarion -- "subprocess<br/>(stdin-piped prompt)" --> cli_llm
+    clarion -- "HTTPS GET<br/>(reqwest blocking,<br/>entity-association lookup)" --> filigree
+    plugins -. "importlib probe only,<br/>fail-soft, no network" .- wardline
+```
+
+Derived from `crates/clarion-cli/src/cli.rs` (three subcommands), `crates/clarion-mcp/src/lib.rs:40` (`MCP_PROTOCOL_VERSION="2025-11-25"`), `crates/clarion-cli/src/http_read.rs:347-369` (Axum router), `crates/clarion-core/src/plugin/transport.rs` (Content-Length framing), `crates/clarion-storage/src/pragma.rs:17-30` (WAL/foreign_keys), `crates/clarion-mcp/src/filigree.rs` (Filigree client), `crates/clarion-core/src/llm_provider.rs` (OpenRouter + CLI providers), `plugins/python/src/clarion_plugin_python/wardline_probe.py` (import-only probe), and `plugins/python/src/clarion_plugin_python/pyright_session.py:637-644` (pyright subprocess). Wardline is dashed because the edge is a fail-soft `importlib.import_module` probe with no production read of the result on the Rust side.
+
+---
+
+## 2. C4 Container — Processes and stores inside `clarion serve` and `clarion analyze`
+
+```mermaid
+flowchart TB
+    subgraph clarion_proc["clarion (single binary; one OS process)"]
+        cli_install["install subcommand<br/>(synchronous;<br/>creates .clarion/)"]
+        cli_analyze["analyze subcommand<br/>(multi-thread tokio;<br/>orchestrates pipeline)"]
+        cli_serve["serve subcommand<br/>(supervisor;<br/>two worker threads)"]
+
+        subgraph serve_runtime["serve runtime (one process, two threads, one ReaderPool)"]
+            mcp_thread["MCP stdio thread<br/>(current-thread tokio;<br/>clarion-mcp::ServerState)"]
+            http_thread["HTTP read thread<br/>(multi-thread tokio;<br/>Axum router)"]
+            reader_pool[("ReaderPool<br/>(deadpool-sqlite,<br/>16 conns;<br/>Arc&lt;()&gt; identity tag)")]
+            writer_actor["Writer actor<br/>(spawn_blocking task;<br/>1 write Connection)"]
+        end
+    end
+
+    sqlite_db[("SQLite file<br/>.clarion/clarion.db<br/>(WAL)")]
+
+    subgraph plugin_procs["Plugin subprocesses (one per language)"]
+        py_plugin["clarion-plugin-python<br/>(server.py dispatch loop)"]
+        py_pyright["pyright-langserver<br/>(child of python plugin)"]
+        fixture["clarion-plugin-fixture<br/>(test only)"]
+    end
+
+    filigree_ext["Filigree<br/>(external HTTP)"]
+
+    cli_install -- "rusqlite::Connection::open;<br/>schema::apply_migrations" --> sqlite_db
+    cli_analyze -- "spawn writer-actor;<br/>spawn plugin subprocesses" --> serve_runtime
+    cli_serve -- "spawns both threads;<br/>holds shared ReaderPool" --> serve_runtime
+
+    mcp_thread -- "with_reader (~30 sites)" --> reader_pool
+    http_thread -- "with_reader" --> reader_pool
+    mcp_thread -- "mpsc&lt;WriterCmd&gt;<br/>(3 variants used:<br/>InsertInferredEdges,<br/>UpsertSummaryCache,<br/>TouchSummaryCache)" --> writer_actor
+
+    reader_pool -- "read txns" --> sqlite_db
+    writer_actor -- "write txn,<br/>50-write batch cadence" --> sqlite_db
+
+    cli_analyze -- "JSON-RPC over pipes<br/>(stdin/stdout per child;<br/>stderr drain thread)" --> py_plugin
+    cli_analyze -. "test only" .- fixture
+    py_plugin -- "LSP JSON-RPC<br/>over stdio pipes" --> py_pyright
+
+    mcp_thread -- "blocking reqwest GET<br/>(entity-associations?entity_id=)" --> filigree_ext
+```
+
+Derived from `crates/clarion-cli/src/serve.rs:20-227` (two-thread supervisor + ReaderPool identity tag), `crates/clarion-cli/src/http_read.rs:262-311` (`run_http_read_server`), `crates/clarion-storage/src/writer.rs:79-98` (mpsc channel + `spawn_blocking` actor), `crates/clarion-storage/src/reader.rs:26-119` (deadpool reader pool with `Arc<()>` tag), `crates/clarion-mcp/src/lib.rs:316-376` (`ServerState`), `crates/clarion-storage/src/pragma.rs` (WAL discipline). Plugin subprocesses are spawned from `crates/clarion-core/src/plugin/host.rs::spawn` driven by `crates/clarion-cli/src/analyze.rs::run_plugin_blocking`.
+
+---
+
+## 3. C4 Component — Plugin host wired to `clarion analyze`
+
+```mermaid
+flowchart LR
+    subgraph cli["clarion-cli (analyze.rs)"]
+        run["run_with_options<br/>(orchestrator)"]
+        run_plugin["run_plugin_blocking<br/>(spawn_blocking)"]
+        crash_brk["CrashLoopBreaker<br/>(>3 crashes / 60s,<br/>OWNED HERE)"]
+    end
+
+    subgraph core["clarion-core::plugin"]
+        discovery["discovery.rs::discover<br/>($PATH scan +<br/>install-prefix fallback)"]
+        manifest["manifest.rs::parse_manifest<br/>(ADR-022 grammar,<br/>reserved-kind gate)"]
+        host_spawn["host.rs::PluginHost::spawn<br/>(Command::new +<br/>BufReader/BufWriter)"]
+        host_pipeline["host.rs analyze_file pipeline<br/>(0 field-size →<br/>1 ontology →<br/>2 identity →<br/>3 jail →<br/>4 entity cap)"]
+        transport["transport.rs<br/>(Content-Length framing,<br/>8 MiB ceiling)"]
+        jail["jail.rs<br/>(canonicalize +<br/>starts_with check)"]
+        limits["limits.rs<br/>(RLIMIT_AS / NOFILE / NPROC<br/>via pre_exec setrlimit)"]
+        path_brk["limits.rs::PathEscapeBreaker<br/>(>10 escapes / 60s,<br/>OWNED BY HOST)"]
+        stderr["stderr drain thread<br/>(64 KiB ring buffer,<br/>one per host)"]
+    end
+
+    subgraph child["plugin subprocess"]
+        child_proc["child process<br/>(stdin/stdout/stderr)"]
+    end
+
+    subgraph storage["clarion-storage"]
+        writer_chan["mpsc&lt;WriterCmd&gt;<br/>(cap 256)"]
+    end
+
+    run --> discovery
+    discovery --> manifest
+    run --> run_plugin
+    run --> crash_brk
+    run_plugin -- "construct" --> host_spawn
+    host_spawn -- "apply at fork" --> limits
+    host_spawn -- "spawn child" --> child_proc
+    host_spawn -- "spawn drain" --> stderr
+    stderr -. "ChildStderr" .- child_proc
+
+    run_plugin -- "analyze_file loop" --> host_pipeline
+    host_pipeline --> transport
+    host_pipeline --> jail
+    host_pipeline --> path_brk
+    transport -- "Content-Length frames" --> child_proc
+
+    host_pipeline -- "BeginRun → entities →<br/>unresolved-call-sites → edges →<br/>ClusterMembers (subsystems) →<br/>CommitRun" --> writer_chan
+
+    crash_brk -- "tick on spawn/handshake/<br/>analyze_file failure" --> run_plugin
+```
+
+Derived from `crates/clarion-core/src/plugin/host.rs:384-1182` (host generic over `BufRead`/`Write`, four-stage pipeline at 866-975, spawn at 509-644, stderr drain at 614-620), `crates/clarion-core/src/plugin/{discovery,manifest,transport,jail,limits,breaker}.rs`, and `crates/clarion-cli/src/analyze.rs:240-275, 325-470, 675-906` (run loop, per-plugin blocking task, phase-3 clustering). The two breakers are drawn distinctly: `CrashLoopBreaker` lives in `analyze.rs`, `PathEscapeBreaker` lives inside the host — same shape, asymmetric ownership noted in catalog §1 patterns.
+
+---
+
+## 4. C4 Component — Storage layer
+
+```mermaid
+flowchart TB
+    subgraph callers["Callers (clarion-cli, clarion-mcp)"]
+        cli_writes["clarion-cli/analyze.rs<br/>(BeginRun, entities, edges,<br/>findings, FlushRunBatch,<br/>CommitRun/FailRun)"]
+        mcp_writes["clarion-mcp/lib.rs<br/>(3 variants only)"]
+        readers_cli["clarion-cli reads<br/>(http_read.rs handlers)"]
+        readers_mcp["clarion-mcp reads<br/>(~30 with_reader sites)"]
+    end
+
+    subgraph storage["clarion-storage"]
+        subgraph writer_side["Writer side (single task)"]
+            sender["Writer (mpsc::Sender&lt;WriterCmd&gt;)<br/>DEFAULT_CHANNEL_CAPACITY=256"]
+            actor["run_actor<br/>(spawn_blocking;<br/>blocking_recv loop)"]
+            state["ActorState<br/>(batch_size=50,<br/>writes_in_batch,<br/>in_tx, current_run)"]
+            contracts["wire-contract enforcers<br/>(enforce_entity_kind_contract,<br/>enforce_edge_contract,<br/>parent_contains_mismatch)"]
+            write_conn[("write Connection<br/>(PRAGMA: WAL,<br/>synchronous=NORMAL,<br/>busy_timeout=5000,<br/>foreign_keys=ON)")]
+        end
+
+        subgraph reader_side["Reader side"]
+            pool["ReaderPool<br/>(deadpool-sqlite,<br/>Arc&lt;()&gt; identity tag)"]
+            with_reader["with_reader<br/>(async helper)"]
+            query["query.rs<br/>(~29 helpers:<br/>entity_by_id,<br/>find_entities,<br/>call_edges_from,<br/>subsystem_members,<br/>resolve_file_catalog_entry, ...)"]
+            cache["cache.rs<br/>(summary_cache,<br/>inferred_edge_cache)"]
+            unresolved["unresolved.rs<br/>(replace-by-caller)"]
+        end
+
+        schema_mod["schema.rs<br/>(apply_migrations;<br/>schema_migrations table)"]
+        migrations[("migrations/<br/>0001_initial_schema.sql<br/>(293 LOC; include_str!)")]
+        pragma["pragma.rs<br/>(apply_write_pragmas /<br/>apply_read_pragmas)"]
+
+        cmds["commands.rs::WriterCmd<br/>(11 variants):<br/>BeginRun, InsertEntity,<br/>InsertEdge, InsertFinding,<br/>FlushRunBatch,<br/>InsertInferredEdges,<br/>UpsertSummaryCache,<br/>TouchSummaryCache,<br/>ReplaceUnresolvedCallSitesForCaller,<br/>CommitRun, FailRun"]
+    end
+
+    sqlite[("SQLite file<br/>.clarion/clarion.db")]
+
+    cli_writes -- "send + oneshot ack" --> sender
+    mcp_writes -- "send + oneshot ack<br/>(via cache/unresolved helpers)" --> sender
+    sender -- "WriterCmd" --> actor
+    actor -- "owns" --> state
+    actor --> contracts
+    contracts -- "validate" --> cmds
+    state -- "single conn" --> write_conn
+    write_conn -- "WAL" --> sqlite
+
+    readers_cli --> with_reader
+    readers_mcp --> with_reader
+    with_reader --> pool
+    with_reader --> query
+    with_reader --> cache
+    with_reader --> unresolved
+    pool -- "read conn N" --> sqlite
+
+    schema_mod -- "boot" --> write_conn
+    schema_mod --> migrations
+    pragma -- "applied per acquisition" --> pool
+    pragma -- "applied at open" --> write_conn
+```
+
+Derived from `crates/clarion-storage/src/writer.rs` (Writer + ActorState + `run_actor`; channel capacity at line 38, batch size at 35, 11-variant match at 154-260, wire contracts at 425-582), `crates/clarion-storage/src/reader.rs:26-119`, `crates/clarion-storage/src/query.rs` (helper catalogue), `crates/clarion-storage/src/cache.rs` and `unresolved.rs`, `crates/clarion-storage/src/schema.rs:17-91`, `crates/clarion-storage/migrations/0001_initial_schema.sql`, and `crates/clarion-storage/src/pragma.rs:16-45`. The "3 variants only" annotation on the MCP-side writer arrow matches catalog §4: `InsertInferredEdges`, `UpsertSummaryCache`, `TouchSummaryCache`.
+
+---
+
+## 5. Sequence — `clarion analyze` happy path
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor user as Developer
+    participant cli as clarion-cli<br/>analyze::run_with_options
+    participant inst as install (idempotent)
+    participant rl as run_lifecycle.rs
+    participant wact as Writer actor<br/>(spawn_blocking)
+    participant disc as core::plugin::discovery
+    participant walk as ignore::WalkBuilder
+    participant ssc as clarion-scanner +<br/>secret_scan (parallel)
+    participant brk as CrashLoopBreaker
+    participant host as PluginHost
+    participant child as plugin subprocess
+    participant clust as clustering.rs (Leiden)
+    participant db as SQLite (WAL)
+
+    user->>cli: clarion analyze <path>
+    cli->>inst: ensure .clarion/ exists,<br/>apply_migrations (idempotent)
+    inst-->>cli: schema ready
+    cli->>cli: load AnalyzeConfig from clarion.yaml
+    cli->>rl: recover_preexisting_running_runs<br/>(raw UPDATE runs SET status='failed')
+    rl-->>cli: ok
+    cli->>wact: Writer::spawn(db_path, 50, 256)
+    wact-->>cli: (Writer, JoinHandle)
+    cli->>cli: mint run_id
+
+    cli->>disc: discover() on $PATH
+    disc-->>cli: Vec<DiscoveredPlugin>
+
+    cli->>walk: collect_source_files<br/>(extension union, .gitignore)
+    walk-->>cli: file list
+
+    cli->>ssc: pre_ingest scan (thread::scope,<br/>available_parallelism workers)
+    ssc-->>cli: SuppressionResult,<br/>briefing_blocked set
+
+    cli->>wact: BeginRun(run_id)
+    wact->>db: BEGIN; INSERT runs status='running'
+    wact-->>cli: ack
+
+    loop per discovered plugin
+        cli->>brk: tick? (still healthy)
+        brk-->>cli: ok
+        cli->>host: spawn(manifest, project_root)
+        host->>child: fork+exec, pre_exec setrlimit
+        host->>child: initialize / initialized
+        loop per filtered source file
+            cli->>host: analyze_file(path)
+            host->>child: JSON-RPC analyze_file
+            child-->>host: {entities, edges, stats}
+            host->>host: 4-stage pipeline<br/>(ontology, identity,<br/>jail, entity cap)
+        end
+        host->>child: shutdown / exit
+        host-->>cli: AnalyzeFileOutcome[],<br/>findings, unresolved-call-sites
+        cli->>brk: tick(success) or tick(crash)
+        Note over cli,brk: >3 crashes / 60s →<br/>FINDING_DISABLED_CRASH_LOOP,<br/>skip remaining plugins
+    end
+
+    cli->>wact: InsertEntity × N
+    wact->>db: per-50 COMMIT; BEGIN cadence
+    cli->>wact: ReplaceUnresolvedCallSitesForCaller × M
+    cli->>wact: InsertEdge × K<br/>(FK ordering: entities first)
+    cli->>wact: InsertFinding × F (secret-scan findings)
+
+    cli->>wact: FlushRunBatch
+    wact->>db: COMMIT; BEGIN
+    cli->>clust: cluster_modules<br/>(Leiden via xgraph;<br/>fallback: weighted-components)
+    clust-->>cli: communities + modularity_score
+    cli->>wact: InsertEntity (core:subsystem:<hash>) × C
+    cli->>wact: InsertEdge (in_subsystem) × M
+
+    cli->>wact: CommitRun(Completed | SoftFailed)
+    wact->>db: parent↔contains mismatch check;<br/>UPDATE runs ... ;<br/>COMMIT
+    wact-->>cli: ack
+    cli-->>user: exit 0
+```
+
+Derived from `crates/clarion-cli/src/analyze.rs:75-645` (`run_with_options`), `crates/clarion-cli/src/run_lifecycle.rs:6-44`, `crates/clarion-storage/src/writer.rs:142-260, 802-877` (per-50 batch cadence, parent↔contains check inside CommitRun at 894-918), `crates/clarion-cli/src/secret_scan.rs:202-382`, `crates/clarion-cli/src/clustering.rs:53-145`, and the host pipeline in `crates/clarion-core/src/plugin/host.rs:866-975`.
+
+---
+
+## 6. Sequence — `clarion serve` MCP tool call
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor agent as Consult-mode LLM agent
+    participant mcp as clarion-mcp<br/>serve_stdio_with_state
+    participant disp as ServerState::handle_json_rpc
+    participant pool as ReaderPool
+    participant q as clarion-storage query.rs
+    participant wact as Writer actor<br/>(via mpsc)
+    participant db as SQLite
+
+    Note over agent,mcp: stdio framing auto-detected:<br/>Content-Length or JSON-line
+
+    agent->>mcp: write frame (tools/call)
+    mcp->>mcp: read_stdio_frame (blocking)
+    mcp->>disp: runtime.block_on(handle_frame_with_state)
+    disp->>disp: validate method+name<br/>against list_tools()
+
+    alt read-only tool<br/>(entity_at, find_entity, callers_of[resolved],<br/>subsystem_members, etc.)
+        disp->>pool: with_reader(|conn| ...)
+        pool->>q: e.g. entity_at_line,<br/>find_entities,<br/>call_edges_from
+        q->>db: SELECT ...
+        db-->>q: rows
+        q-->>pool: typed records
+        pool-->>disp: result
+    else write-touching tool<br/>(only 3 variants from MCP)
+        disp->>wact: send WriterCmd::InsertInferredEdges<br/>or UpsertSummaryCache<br/>or TouchSummaryCache
+        Note over disp,wact: gated by BudgetLedger;<br/>InferredInflight coalesces<br/>concurrent identical requests
+        wact->>db: write outside run-batch txn
+        wact-->>disp: oneshot ack
+    end
+
+    disp-->>mcp: envelope JSON
+    mcp->>mcp: write_stdio_response<br/>(same framing as request)
+    mcp-->>agent: framed response
+```
+
+Derived from `crates/clarion-mcp/src/lib.rs:56-258` (`list_tools`, 20 `ToolDefinition` hits — 19 distinct tool entries + the struct definition; catalog §4 flagged the count drift against the discovery doc), `lib.rs:295-488` (`handle_json_rpc` + `handle_tool_call` 19-arm match), `lib.rs:1560-2030` (inferred-edge dispatch + `BudgetLedger` + `InferredInflight`), `lib.rs:2704-2876` (dual-framing transport), and the writer-channel emission sites at `lib.rs:1682, 1824, 1924, 2024` (3 distinct `WriterCmd` variants).
+
+---
+
+## 7. Subsystem dependency graph
+
+```mermaid
+graph LR
+    cli["clarion-cli<br/>(binary;<br/>install/analyze/serve)"]
+    mcp["clarion-mcp<br/>(MCP dispatch + config + Filigree client)"]
+    core["clarion-core<br/>(entity-id, plugin host,<br/>LLM providers)"]
+    storage["clarion-storage<br/>(writer-actor + reader pool)"]
+    scanner["clarion-scanner<br/>(pure secret detection)"]
+    fixture["clarion-plugin-fixture<br/>(test-only plugin)"]
+    pyplug["plugins/python<br/>(out-of-tree subprocess)"]
+
+    cli --> core
+    cli --> mcp
+    cli --> storage
+    cli --> scanner
+    cli -. "dev-dependency<br/>(wp2_e2e tests)" .-> fixture
+
+    mcp --> core
+    mcp --> storage
+
+    storage --> core
+
+    fixture --> core
+
+    pyplug -. "subprocess only<br/>(JSON-RPC over stdio,<br/>spawned by core::host)" .-> core
+
+    classDef leaf fill:#eee,stroke:#888
+    class scanner,fixture,pyplug leaf
+```
+
+Derived from per-subsystem **Outbound deps** and **Inbound** sections of `02-subsystem-catalog.md`: `clarion-cli` depends on all four library crates and dev-depends on the fixture; `clarion-mcp` depends on `core` + `storage` only; `clarion-storage` depends only on `clarion-core` (one type re-export and one direct facade reach into `manifest::RESERVED_ENTITY_KINDS`); `clarion-scanner` has zero internal Clarion deps; the Python plugin has no Rust dependency edge — it interacts only as a subprocess driven by `core::plugin::host`. The dashed Python-plugin edge captures that wire relationship, not a build-graph edge.
+
+---
+
+## Residual uncertainties
+
+- **Exact tool count.** Catalog §4 reports 19 distinct `ToolDefinition` entries; discovery §5 reports 20 (`grep -c 'ToolDefinition {'` = 20, which also matches a confirmation grep). The discrepancy is the trailing struct-definition match at `lib.rs:47`. Sequence diagram §6 uses the 19-entry figure for the dispatch match.
+- **Wardline probe semantics.** Diagrams show the Python plugin's import-only probe as a dashed edge; the Rust-side consumption of the probe result (the manifest `wardline_aware = true` flag and any `capabilities.wardline` channel in the `initialize` response) was not analysed — catalog §1 and §7 both flag this.
+- **HTTP auth selection.** The HTTP container diagram does not branch on bearer vs HMAC vs `trust-loopback`; catalog §3 records that selection is config-driven (HMAC preferred when `identity_token_env` set, bearer when only `token_env` set, none when neither). Sequence-level auth was out of scope for this pass.
+- **Phase-3 clustering raw connection.** Diagram §5 shows clustering happening after a `FlushRunBatch`, but does not depict that the clustering pass opens a *direct* `rusqlite::Connection` bypassing the reader pool (catalog §3 concerns). The diagram aggregates it into the `clust` participant.
+- **Federation `/api/v1/_capabilities` unauthenticated route.** The container and context diagrams collapse all four HTTP routes into one labelled edge; the unprotected capabilities route is not visually distinguished.
+- **`analyze` subcommand reachable inside `serve`.** `clarion-mcp` tools `analyze_start` / `analyze_status` / `analyze_cancel` spawn `clarion analyze` as a child of `clarion serve` (catalog §4 key components). This re-entry is not drawn in diagram §2 to keep the container shape readable; it appears implicitly via the MCP tool surface in diagram §6.
+- **LLM CLI providers.** The context diagram shows `claude` / `codex` CLI binaries as external processes; they are spawned by `clarion-core::llm_provider`'s `ClaudeCliProvider` / `CodexCliProvider`, but the host-side timeout/reaper-thread machinery is not drawn.
diff --git a/docs/arch-analysis-2026-05-22-1924/04-final-report.md b/docs/arch-analysis-2026-05-22-1924/04-final-report.md
new file mode 100644
index 00000000..b5e31b19
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/04-final-report.md
@@ -0,0 +1,330 @@
+# 04 — Final Report: Clarion Architecture Analysis
+
+**Date:** 2026-05-22
+**Scope:** Entire Rust workspace (`crates/`) plus the Python language plugin (`plugins/python/`).
+**Method:** From-scratch source archaeology. Seven independent codebase-explorer subagents read source, manifests, migration SQL, fixtures, and tests for one subsystem each. **No existing design docs** (`docs/clarion/**`, `docs/suite/**`, `docs/implementation/**`, ADRs, sprint READMEs, prior arch-analyses) were consulted during the analysis. A separate validator subagent spot-checked eight load-bearing factual claims against source.
+**Validator status:**
+- *Subsystem catalog (`02-`):* NEEDS_REVISION (warnings) — one factual error (Python plugin's `MAX_FILES_PER_PYRIGHT_SESSION` literal) fixed inline; one cosmetic nit accepted; all eight load-bearing spot-check claims passed.
+- *Final report (this doc):* APPROVED with editorial warnings — discovery-doc tool-count sweep completed; this top matter clarified.
+
+---
+
+## 1. Executive Summary
+
+Clarion is a **single-binary Rust code-archaeology tool** that ingests source trees through out-of-tree language plugins, persists a typed entity/edge graph in an embedded SQLite database, and exposes that graph to LLM agents through two distinct read surfaces — a stdio **MCP server** with 19 navigation tools, and an authenticated **HTTP read API** for cross-product federation. A reference **Python plugin** (the only in-tree language plugin) drives `pyright` as an LSP subprocess to extract type-resolved call and reference edges.
+
+The architecture is structurally simple — 7 subsystems, ~50K LOC, no inter-crate cycles — but **operationally subtle**. The hard parts live in three places:
+
+1. **Plugin-host subprocess supervision** (`clarion-core::plugin::host`): generic-over-IO synchronous JSON-RPC supervisor, per-frame ceiling rejection without body-consume, four enforcement layers (frame size, path jail, entity cap, crash-loop), forked-child resource limits via `pre_exec`-installed `setrlimit`, detached stderr-drain thread.
+2. **Storage's writer-actor discipline** (`clarion-storage::writer`): every mutation routes through one bounded-mpsc actor on `spawn_blocking`; per-run super-transaction; batch commits every 50 writes; wire-contract enforcement (edge kind/confidence/source-range tables, parent↔contains bijection) at the writer boundary so caller bugs cannot corrupt graph shape.
+3. **The analyze pipeline as a sequence of nested gates** (`clarion-cli::analyze`): orphan-run recovery → secret scan → BeginRun → per-plugin loop with two distinct breakers (path-escape inside the host, crash-loop in the run loop) → unresolved-call-site → edge resolution → clustering → CommitRun. All in a single 570-line function.
+
+The system has invested heavily in **failure containment**: 11+ hardcoded resource limits with `CLA-INFRA-*` finding subcodes, two independent rolling-window breakers, drop-with-finding vs. kill-with-error asymmetry, cross-language byte-for-byte fixture parity for entity IDs, and a baseline mechanism that intentionally does **not** suppress drifted hashes at the same line. These are the marks of a system that has thought hard about adversarial-plugin and partial-failure scenarios.
+
+The clearest **architectural debt** is at the file-size level: four files (`mcp/lib.rs` 4703, `core/plugin/host.rs` 2935, `cli/analyze.rs` 2549, `core/llm_provider.rs` 2467) hold the bulk of the operational complexity. They are not poorly factored *internally* — each has clearly named functions and inline-test discipline — but each is one file's-worth of change risk per touch.
+
+---
+
+## 2. The System in Code (no doc references)
+
+### 2.1 Subsystem inventory
+
+| # | Subsystem | Type | Source LOC | Test LOC | Confidence |
+|---|-----------|------|-----------:|---------:|------------|
+| 1 | `clarion-core` | library | 11,653 | 325 (+ inline) | High |
+| 2 | `clarion-storage` | library | 3,199 | 4,871 | High |
+| 3 | `clarion-cli` | binary (`clarion`) | ~6,800 | ~6,400 | High |
+| 4 | `clarion-mcp` | library | ~6,600 | ~2,200 | High (sampled `lib.rs`) |
+| 5 | `clarion-scanner` | library | 881 | 655 | High |
+| 6 | `clarion-plugin-fixture` | test bin | 187 | (see consumers) | High |
+| 7 | `plugins/python` | external bin (`clarion-plugin-python`) | 3,028 | 3,440 | High |
+
+**Totals:** ~32K source / ~18K test (Rust) + 3K source / 3.4K test (Python) = ~50K LOC of first-party code. Test corpus is **~57% of source LOC** — high by typical standards, dominated by `clarion-storage` where tests outweigh source 1.5×.
+
+### 2.2 External dependencies (architecturally significant)
+
+- `tokio` (multi-thread + sync + macros) — runtime for `serve` and the writer-actor.
+- `rusqlite` 0.31 with bundled SQLite — embedded DB, no external server.
+- `deadpool-sqlite` 0.8 (`rt_tokio_1`) — async-friendly reader pool.
+- `axum` 0.7 + `tower` / `tower-http` — HTTP read API (`/api/v1/files*`).
+- `reqwest` 0.12 with rustls — outbound HTTP to OpenRouter LLM, Filigree associations.
+- `clap` 4 — CLI.
+- `nix` — `setrlimit` for plugin children via `pre_exec`.
+- `xgraph` — Leiden community detection (with a hand-rolled fallback).
+- `serde_norway` — YAML (`clarion.yaml`, secret-scan baseline).
+- Python: `pyright` (LSP subprocess), `tomli` (manifest), `pytest`/`mypy --strict` for dev.
+
+No mocked-out networking; the LLM provider trait has a `RecordingProvider` for tests but production hits the real OpenRouter HTTP endpoint or shells out to `claude`/`codex` CLIs.
+
+### 2.3 Wire surfaces (external interfaces)
+
+| Surface | Where | Transport | Auth |
+|---|---|---|---|
+| `clarion` CLI | `clarion-cli/src/main.rs`, `cli.rs` | argv | n/a |
+| Plugin JSON-RPC 2.0 | `clarion-core/src/plugin/protocol.rs` | LSP-style `Content-Length` framing over stdio pipes | none (process boundary is the trust boundary) |
+| MCP server | `clarion-mcp/src/lib.rs::serve_stdio_with_state_on_runtime` | stdio (auto-detects `Content-Length` framing vs. bare-JSON-line) | none (caller-trusted) |
+| HTTP read API | `clarion-cli/src/http_read.rs:347-372` | HTTPS-capable Axum on `0.0.0.0:<port>` | **HMAC-SHA256** > bearer > **loopback-trust** with operator WARN (4 routes, precedence in code) |
+| OpenRouter | `clarion-core/src/llm_provider.rs::OpenRouterProvider` | HTTPS | API key (env) |
+| Filigree | `clarion-mcp/src/filigree.rs` | HTTPS | bearer (env) + `x-filigree-actor` header |
+| Pyright LSP | (Python plugin) `clarion_plugin_python/pyright_session.py` | LSP subprocess pipes | none |
+
+---
+
+## 3. Architecture Narrative
+
+### 3.1 The shape: a CLI with two persistent modes
+
+The `clarion` binary has **three subcommands** (`install`, `analyze`, `serve`) but two architectural shapes. `install` and `analyze` are one-shot processes; `serve` is a long-running supervised topology with two threads sharing one `ReaderPool`:
+
+- A **current-thread Tokio runtime** drives the MCP stdio server (`clarion-mcp::serve_stdio_with_state_on_runtime`).
+- A **multi-thread Tokio runtime** drives the Axum HTTP read API on a configurable port.
+
+`clarion-cli::serve::run` enforces shared-pool identity with `Arc::ptr_eq` (`reader.rs:26-119` exposes a `shares_pool_with` runtime proof via an `Arc<()>` identity tag) — a structural guarantee that both servers observe the same database snapshot. Failure of either thread crashes the binary; there is no per-surface restart.
+
+### 3.2 The analyze pipeline
+
+`clarion-cli::analyze::run_with_options` is a single 570-line function (`analyze.rs:75-645`) that linearises 13 phases:
+
+1. canonicalize project path
+2. load `clarion.yaml`
+3. raw `UPDATE runs SET status='failed' WHERE status='running'` — **orphan-run recovery before the writer-actor even exists**
+4. spawn writer-actor, mint `run_id`
+5. plugin discovery via `$PATH` scan for `clarion-plugin-*` executables (`clarion-core::plugin::discovery`)
+6. compute extension union from plugin manifests
+7. tree walk
+8. **parallel secret scan, BEFORE BeginRun, BEFORE any plugin spawn** (`clarion-scanner` driven by `secret_scan::scan_source_files_parallel`)
+9. `BeginRun` command to writer-actor
+10. per-plugin loop (each plugin runs in `spawn_blocking`): handshake → `analyze_file` × N (with heartbeat logging) → `shutdown`; per-run `CrashLoopBreaker` from `clarion-core` ticks on >3 crashes / 60 s and drops remaining plugins with `FINDING_DISABLED_CRASH_LOOP`
+11. entities → unresolved-call-sites → edges ingestion in **strict FK order**
+12. phase-3 clustering via `clustering::cluster_with_leiden` (Leiden through `xgraph` with deterministic seed; falls back to `local_weighted_components` if Leiden returns ≤1 community)
+13. `CommitRun` (or `SoftFail` / `HardFail` if invariants tripped)
+
+The function carries `#[allow(clippy::too_many_lines)]` (`analyze.rs:74`). The reviewer rated this the single largest concern in the CLI — every change vector listed above goes through the same scope.
+
+### 3.3 Plugin host: the most carefully engineered surface
+
+`clarion-core::plugin::host::PluginHost<R: BufRead, W: Write>` (`host.rs:384-1182`) is generic over reader/writer so the in-process `mock.rs` (876 LOC, `#[cfg(test)] pub(crate)`) can drive it without a subprocess. The four-stage per-entity validation pipeline at `host.rs:866-975` runs for every entity a plugin emits:
+
+0. **Field-size** — 4 KiB per scalar field, 64 KiB per `#[serde(flatten)]` extras map.
+1. **Ontology** — `kind ∈ manifest.ontology.entity_kinds`.
+2. **Identity** — recomputed `entity_id(plugin_id, kind, qualified_name)` must equal the wire `id` (prevents ID-namespace spoofing).
+3. **Jail** — `jail_to_string(project_root, source.file_path)` must succeed; on failure, tick `PathEscapeBreaker`.
+
+Steps 0–2 **drop-with-finding** (continue). Step 3 drops + records a finding; >10 path-escapes / 60 s trips the breaker and **kills the plugin**. A separate post-step **entity cap** (`EntityCountCap::DEFAULT_MAX = 500_000` cumulative) on overflow kills the plugin.
+
+Subprocess hygiene:
+- `spawn` returns `(PluginHost, std::process::Child)` — the **caller owns reaping**. `Child::Drop` does not `waitpid` on Unix (documented at `host.rs:630-641`); a handshake-failure inside `spawn` reaps before returning.
+- **`pre_exec`-installed `setrlimit`** for `RLIMIT_AS` (virtual address) and `RLIMIT_NPROC` (bumped to 4096 when the plugin manifest declares Pyright capability, because Node's LSP host spawns helper processes counted against the user's nproc).
+- **Detached stderr-drain thread** (`host.rs:609-620`) named `clarion-plugin-stderr-drain:<plugin_id>` reads `ChildStderr` 4 KiB at a time into a 64 KiB ring buffer. Rationale at `host.rs:550-561`: an inherited stderr could either flood the operator's terminal or deadlock the plugin on `write(2)` when the host blocks in `analyze_file`.
+
+Validator-confirmed via `host.rs:609-620`, `writer.rs:35,38,813`, `analyze.rs:242,244,277+`.
+
+### 3.4 Storage: an actor + a pool over one SQLite file
+
+`clarion-storage` is the **only path** to SQLite. Concurrency model:
+
+- **One writer-actor** spawned on `tokio::task::spawn_blocking`. Bounded `mpsc::Receiver<WriterCmd>` (capacity 256, `writer.rs:35`), 11 command variants each carrying a `oneshot::Sender<Result<T>>` ack. Per-run super-transaction; batch-cadence commits every 50 writes (`writer.rs:38, 813`).
+- **Reader pool** via `deadpool-sqlite` (`Runtime::Tokio1`). Reader PRAGMAs reapplied per acquisition. Production sizes: 16 in `serve.rs`, 4 in `http_read.rs` test.
+- **PRAGMA discipline** (`pragma.rs:16-45`): WAL (asserted — the assertion is hard, not advisory), `synchronous=NORMAL`, `busy_timeout=5000`, `wal_autocheckpoint=1000`, `foreign_keys=ON`. **No `application_id` / `user_version`** are set; cross-tool collisions on the DB file are not detected at the SQLite level.
+- **Schema migrations** (`schema.rs:17-91`): single `include_str!`-embedded migration, idempotent via a `schema_migrations` table. Explicit comment at lines 45-49 warns that `.ok()` instead of `OptionalExtension::optional()` would silently mask `DatabaseLocked` / `CorruptDb`.
+
+**Wire contracts are enforced at the writer boundary** (`writer.rs:425-582`):
+- `STRUCTURAL_EDGE_KINDS = {contains, in_subsystem, guides, emits_finding}` — must be `confidence=resolved`, must have NULL byte ranges.
+- `ANCHORED_EDGE_KINDS = {calls, references, imports, decorates, inherits_from}` — must have both byte-start AND byte-end, must NOT be `inferred` at scan time.
+- `parent_contains_mismatch` (`writer.rs:954-1021`) — bidirectional SQL pair asserting `entities.parent_id` and `edges WHERE kind='contains'` are bijective. Failure aborts the entire run with `CLA-INFRA-PARENT-CONTAINS-MISMATCH`.
+
+The migration SQL defines 9 tables, 1 FTS5 virtual, 3 triggers, 2 generated columns, 1 view, and crucially `edges` is `WITHOUT ROWID` on natural PK `(kind, from_id, to_id)`.
+
+### 3.5 MCP server: 19 tools (not 20)
+
+`clarion-mcp::serve_stdio_with_state_on_runtime` registers **19 tools** in a `ToolDefinition` registry at `lib.rs:56-257`. The original discovery doc said "twenty"; the catalog and validator both confirmed 19 via direct enumeration. (Discovery's `grep -c 'ToolDefinition {'` had counted the struct declaration plus 19 `vec![]` instances.) Discovery has been corrected in place.
+
+Tool dispatch is **strictly sequential per session** — there is no concurrent tool execution within one MCP connection. The dispatcher auto-detects framing (LSP `Content-Length` vs. bare JSON line) by peeking the first non-whitespace byte. Read path goes through the reader pool (~30 sites); the writer is touched by only **3 command variants** across 4 sites — `InsertInferredEdges` (×2), `TouchSummaryCache` (×1), `UpsertSummaryCache` (×1) — and all are gated on the summary-LLM writer field being configured.
+
+### 3.6 HTTP read API: the federation surface
+
+`clarion-cli::http_read.rs:347` exposes four routes on Axum:
+
+- `GET /api/v1/files`
+- `POST /api/v1/files/batch` (cap 256)
+- `POST /api/v1/files:resolve` (cap 1000)
+- `GET /api/v1/_capabilities` (unprotected)
+
+Auth precedence is **hand-rolled HMAC-SHA256 > bearer > loopback-trust with WARN** (constant-time compare, 16 KiB body cap, 10 s timeout, 64 concurrency). The middleware panics on unenumerated errors — a deliberate fail-loud posture.
+
+### 3.7 Python plugin: pyright-as-a-service
+
+`clarion-plugin-python` is a PEP 517 console-script binary (`pyproject.toml:32-33`) per ADR-021 bare-basename convention. It implements 5 JSON-RPC methods (`initialize`, `initialized`, `analyze_file`, `shutdown`, `exit`; `server.py:237-272`) over Content-Length framing with an 8 MiB cap. The reference plugin and Python plugin share their wire shape with `clarion-plugin-fixture`.
+
+The interesting machinery is **pyright integration**:
+- Pyright runs as a subprocess (`pyright-langserver --stdio`), driven by a full LSP client (`PyrightSession`).
+- Session is recycled every **25 files** (`MAX_FILES_PER_PYRIGHT_SESSION` at `server.py:49`) — a wholly-separate-from-the-3-restart-cap heuristic.
+- Calls use `prepareCallHierarchy` + `callHierarchy/outgoingCalls`.
+- References use `textDocument/definition` with `typeDefinition` fallback for annotation references.
+- All failures degrade to zero edges + a `CLA-PY-PYRIGHT-*` finding.
+
+The extractor walks the AST three times (recursive `_walk`, `_ImportEdgeCollector`, `_ReferenceSiteCollector`). `@overload` stubs are dropped pre-emit; surviving collisions drop first-wins. Cross-language entity-ID parity is enforced by `tests/test_entity_id.py:25` consuming the same `fixtures/entity_id.json` as the Rust `entity_id.rs:371-587`.
+
+A **`wardline_probe.py`** module attempts `import wardline.core.registry` and reports `{status: absent|enabled|version_out_of_range}` from `initialize`. Fail-soft.
+
+### 3.8 The secret scanner
+
+`clarion-scanner` is a **pure detection library** — it does not walk the FS, does not decide *what* to scan. Callers invoke `Scanner::scan_bytes(&[u8])` per-file. `clarion-cli::secret_scan::scan_source_files_parallel` drives it across the project tree in `analyze.rs:242-243`, **before** `BeginRun` and before any plugin spawn.
+
+Detection: **12 named pattern rules** (AWS, GitHub 3×, Anthropic, OpenAI, Stripe, Slack, JWT, PEM private key, contextual `password|token|api_key = "…"`) + **2 entropy classes** (base64 min-len 20 min-entropy 4.5; hex min-len 40 min-entropy 3.0). All map to a closed 14-variant `DetectSecretsRule` enum at `lib.rs:102-118`, rule-ids aligned to Yelp `detect-secrets`.
+
+The **baseline file** is YAML keyed by path, suppressing on exact `(file, rule_type, hashed_secret, line_number)` quadruples — **only when `is_secret: false`**. Drifted hashes at the same line are deliberately NOT suppressed. Parse-time validation rejects non-1.0 version, absolute/`..` paths, missing justifications, unknown rule types, invalid hex hashes. (Tests at `tests/scanner.rs:509-556` lock this in.)
+
+---
+
+## 4. Dependency Topology
+
+**Inter-subsystem dependencies (Rust):**
+
+```
+clarion-cli ──► clarion-core
+            ├──► clarion-storage
+            ├──► clarion-scanner
+            └──► clarion-mcp
+
+clarion-mcp ──► clarion-storage
+            └──► clarion-core (for protocol::read_frame, BriefingBlockReason, LLM types)
+
+clarion-storage ──► clarion-core (EdgeConfidence, RESERVED_ENTITY_KINDS — facade leak)
+
+clarion-scanner ── (no internal deps)
+clarion-plugin-fixture ──► clarion-core (only for JSON-RPC types)
+plugins/python ── (no Rust deps; speaks the wire only)
+```
+
+**No cycles.** The dependency graph is a DAG with `clarion-core` at the bottom, `clarion-storage` and `clarion-scanner` as leaves of the lower layer, and `clarion-cli` and `clarion-mcp` as the consumers.
+
+**Notable inbound reach (the facade leak):** `clarion-storage::writer.rs:427` reaches `clarion_core::plugin::manifest::RESERVED_ENTITY_KINDS` *directly* through the module path, bypassing the `lib.rs:13-49` `pub use` facade. The policy comment at `clarion-core::lib.rs:5-7` describes the facade as the supported surface; this constant is not re-exported there.
+
+**The Python plugin is intentionally isolated** — no shared crate dependency, no shared registry. It speaks the wire protocol, consumes the same `fixtures/entity_id.json` the Rust side uses for parity testing, and is otherwise independent of the Rust workspace.
+
+---
+
+## 5. Cross-Cutting Concerns
+
+| Concern | Where |
+|---|---|
+| **Error model** | Per-module `thiserror` enums composed via `#[from]`. `HostError` (`host.rs:334-370`) wraps eight underlying errors plus three policy variants. `StorageError` (`storage/src/error.rs`) similar. CLI uses `anyhow` at the boundary. |
+| **Logging / tracing** | `tracing` + `tracing-subscriber` with `env-filter`. Plugin heartbeats logged from analyze loop (`analyze.rs:1272-1307`). |
+| **Async runtime** | `tokio` multi-thread. **Two exceptions**: writer-actor uses `spawn_blocking` (synchronous SQLite); plugin host is fully synchronous (`BufRead`/`Write`, no async). |
+| **Config** | `serde_norway` (YAML) for `clarion.yaml`; `clap` derive for CLI. Subprocess plugins read TOML manifests (`plugin.toml`). |
+| **Migrations** | Embedded via `include_str!` in `clarion-storage::schema`. Tracked in `schema_migrations` table. No `application_id` / `user_version`. |
+| **Security boundaries** | (a) Plugin process boundary (jail + setrlimit + entity cap + path-escape breaker + frame ceiling). (b) HTTP API HMAC > bearer > loopback. (c) Pre-ingest secret scan with baseline suppression that won't mask drift. |
+| **Findings vocabulary** | `CLA-INFRA-*` (host enforcement), `CLA-PY-PYRIGHT-*` (Python plugin pyright failures), `CLA-SEC-SECRET-DETECTED` (scanner), `CLA-INFRA-PARENT-CONTAINS-MISMATCH` (storage invariant). Surfaced via `HostFinding` (core) and the standard `Finding` record persisted in SQLite. |
+| **Determinism** | Clustering uses a deterministic seed (`clustering.rs`). Entity IDs are pure functions of (plugin_id, kind, canonical_qualified_name). Cross-language byte-for-byte parity test gates against `fixtures/entity_id.json`. |
+
+---
+
+## 6. Risks and Smells (Concrete, Source-Cited)
+
+Severity bands:
+- **🔴 High** — affects correctness, security, or change-amplification surface
+- **🟡 Medium** — operational friction, will degrade over time
+- **🟢 Low** — cleanup opportunity
+
+### 🔴 High
+
+1. **Four monolithic files concentrate change risk.**
+   - `clarion-mcp/src/lib.rs` — 4,703 LOC. Holds the 19 tool registry, `ServerState`, all per-tool handlers, the `BudgetLedger`, the `InferredInflight` coalescer, and tests.
+   - `clarion-core/src/plugin/host.rs` — 2,935 LOC. Holds the entire `PluginHost<R, W>` impl, the four-stage pipeline, the stderr drainer, `pre_exec` setup, and the shutdown idempotency.
+   - `clarion-cli/src/analyze.rs` — 2,549 LOC; `run_with_options` itself is 570 lines.
+   - `clarion-core/src/llm_provider.rs` — 2,467 LOC. **Bundles the trait + reqwest HTTP transport + two CLI-subprocess transports + prompt templates in a crate whose `lib.rs:1` doc-comment says it owns "domain types, identifiers, and provider traits"**.
+
+   Refactor split exists for each (pipeline-axis / lifecycle-axis / IO-axis for `host.rs`; tool-category split for `mcp/lib.rs`; per-phase function extraction for `analyze.rs`; new `clarion-llm` crate for `llm_provider.rs`). None is taken yet.
+
+2. **Blocking HTTP inside async (MCP filigree client).** `clarion-mcp::filigree` issues **blocking** `reqwest::blocking::get` calls from `async` tool handlers (validator-flagged; reviewer cited as a real concern). Will tie up the runtime thread on a slow Filigree.
+
+3. **No analyze-child timeout in `serve`.** The MCP `analyze_start` / `analyze_status` / `analyze_cancel` tool family launches an analyze process from inside the MCP server — but the catalog flags "no analyze-child timeout" as an mcp-side smell (`02-subsystem-catalog.md` §4). Inspect before claiming this is hardened.
+
+4. **Subprocess-child reaping ownership is type-system-unenforced.** `PluginHost::spawn` returns `(Self, Child)` where the caller is documented (`host.rs:630-641`) to reap. A `KillOnDrop` newtype around `Child` would make the contract type-mechanical instead of comment-mechanical.
+
+### 🟡 Medium
+
+5. **`clarion-storage`'s SQLite file has no `application_id` / `user_version`.** Two Clarion versions sharing a DB by accident would not be detected at the SQLite layer; only the `schema_migrations` table catches it, and only on write. Adding both PRAGMAs is a one-line change with no downside.
+
+6. **`llm_provider.rs` belongs in its own crate.** It pins `reqwest` and `tokio::time::timeout`-equivalent CLI machinery into `clarion-core` — the crate that supervises plugins. A `clarion-llm` crate would shrink the trust surface of the host runtime.
+
+7. **Facade leak: `clarion-storage::writer.rs:427` reaches `clarion_core::plugin::manifest::RESERVED_ENTITY_KINDS` directly.** Either lift to the facade or expose `Manifest::is_reserved_kind`. As-is, the internal module path is semi-public.
+
+8. **Eleven hardcoded operational limits in `clarion-core`.** `MAX_PROTOCOL_ERROR_FIELD_BYTES`, `MAX_ENTITY_FIELD_BYTES`, `MAX_ENTITY_EXTRA_BYTES`, `STDERR_TAIL_BYTES`, `MAX_HEADER_LINE_BYTES`, `MAX_UNRESOLVED_CALLEE_EXPR_BYTES`, `ContentLengthCeiling::DEFAULT`, `EntityCountCap::DEFAULT_MAX`, `DEFAULT_MAX_RSS_MIB`, `DEFAULT_MAX_NOFILE`, `DEFAULT_MAX_NPROC`. The comment at `breaker.rs:7` acknowledges this lands "in WP6". Every tunable is a recompile today.
+
+9. **Path jail is TOCTOU-by-design.** `jail.rs:67-72` documents this: the canonical-path return is a membership proof at canonicalization time, not a durable file handle. The current consumer doesn't open files, so this is latent; a future caller that does could miss the contract.
+
+10. **Pyright session restart constant `25` is divorced from session's own 3-restart cap.** Interaction between server-driven recycling and session-driven failure restarts is not centrally documented.
+
+### 🟢 Low
+
+11. **Integration tests for `clarion-core` cover only the happy path.** Most `HostError` variants and `CLA-INFRA-*` finding subcodes are tested via inline `#[cfg(test)]` blocks, which is fine but uneven — `tests/host_subprocess.rs` is 325 lines, covering one walkthrough.
+
+12. **Tool count drift in discovery vs. registry.** Discovery initially said 20; actual is 19. Already corrected in this analysis; flag for future readers.
+
+13. **`mock.rs` at 876 LOC is `#[cfg(test)] pub(crate)`.** Volume itself is a smell — the host's pipeline is stateful enough to need a sub-DSL to test, which corroborates the `host.rs` size concern.
+
+---
+
+## 7. Strengths Worth Naming
+
+Concrete things this codebase does *well* that a brownfield analysis should not understate:
+
+- **Generic-over-IO supervisor with in-process mock.** `PluginHost<R: BufRead, W: Write>` plus `mock.rs` is a textbook approach to testing subprocess supervision without spawning subprocesses. The seam at `connect()` (`host.rs:658`) is clean.
+- **Wire-contract enforcement at the writer boundary.** Caller bugs cannot corrupt the graph shape. Three structurally-distinct invariants — edge-kind tables, source-file-anchor kinds, parent↔contains bijection — all enforced in SQL-adjacent Rust at `writer.rs:425-582, 954-1021`.
+- **Cross-language byte-for-byte parity fixture.** `fixtures/entity_id.json` is consumed by both `clarion-core::entity_id.rs:371-587` and `plugins/python/tests/test_entity_id.py:25`. Drift between the two implementations is caught in CI before either side ships.
+- **Per-frame ceiling rejection before body-consume.** `transport.rs:67-71` rejects with `TransportError::FrameTooLarge` without consuming bytes — closing a memory-exhaustion attack vector that "read then check" would leave open.
+- **Two breakers, two scopes.** `PathEscapeBreaker` (per-plugin, host-owned) polices one misbehaving plugin's emissions; `CrashLoopBreaker` (per-run, caller-driven) polices the fleet. Same shape, different scope. Named asymmetrically only in *ownership*, not in *interface*.
+- **The secret-scanner baseline that won't mask drift.** `(file, rule_type, hashed_secret, line_number)` quadruple match with `is_secret: false` requirement means a changed secret at the same line is *not* suppressed (locked in by `tests/scanner.rs:509-556`). This is a deliberate regression net — the kind of thing easy to get wrong, here gotten right.
+- **Deterministic clustering with hand-rolled fallback.** `clustering.rs` uses Leiden via `xgraph` with a seeded RNG, with a `local_weighted_components` fallback for the degenerate "≤1 community" case. Determinism is testable.
+
+---
+
+## 8. Open Questions for the Next Phase
+
+Things that the *catalog* could not answer from code alone, and that an architect or feature-owner should clarify:
+
+1. **Why the 25-file pyright restart constant?** Empirical? Conservative bound on pyright memory growth? Either is fine; not knowing makes future tuning a guess.
+2. **What is the post-1.0 plan for the four monolith files?** Each has a natural refactor split. Are these on the roadmap, or is the policy "no split until the file actively impedes a change"?
+3. **Will `clarion-llm` become a crate?** The `llm_provider.rs` placement in `clarion-core` is the largest single argument against the lib doc-comment.
+4. **What is the architect's stance on `application_id` / `user_version`?** Trivial to add; non-trivial to add *retroactively* once installed DBs exist in the wild.
+5. **Operational tuning roadmap.** Eleven hardcoded limits, plus 25-file restart, plus 256/50 batch-cadence constants. WP6 is named in code comments — what is its current status?
+
+---
+
+## 9. Methodology and Confidence
+
+**Validation status:** NEEDS_REVISION (warnings) → fixed → effectively APPROVED. One factual error (Python plugin restart constant value) corrected in `02-subsystem-catalog.md`. One cosmetic nit (subsystem 7 title) accepted. Eight spot-check claims all PASSED:
+
+| Claim | Source verified | Status |
+|---|---|---|
+| stderr drain thread | `host.rs:609-620` | PASS |
+| writer actor: 256-cap mpsc, 50-write batch | `writer.rs:35, 38, 813` | PASS |
+| analyze ordering (secret scan → BeginRun → plugin spawn) | `analyze.rs:242, 244, 277+` | PASS |
+| MCP tool count | `mcp/lib.rs:47-257` | 19 (discovery corrected) |
+| HTTP read API: 4 routes | `http_read.rs:364-372` | PASS |
+| plugin-fixture: 5 methods | `main.rs:51, 54, 68, 77, 116` | PASS |
+| `clarion-plugin-python` binary name | `pyproject.toml:32-33` | PASS |
+| Scanner: 12 named + 2 entropy | `patterns.rs:194-269`, `entropy.rs:11-18` | PASS |
+
+**Overall confidence: High** for everything in §3, §4, §5, §6, §7. **Medium-High** for §2 LOC counts (some are approximate-from-discovery, validated to within 2%). **Medium** for §8 (recommendations) — these depend on architect intent the code cannot reveal.
+
+**Coverage:** all 7 subsystems analyzed; every load-bearing module read at least partially; the four largest files sampled with explicit annotation of what was end-to-end-read vs. sampled (in each subsystem's Confidence statement). One file *not* sampled to completion is `clarion-mcp/src/lib.rs` (4,703 LOC) — its 19 tool registry was enumerated and the dispatcher structure was characterised, but each tool's individual handler body was not read end-to-end.
+
+**What I would do next if continuing:**
+
+- Quality-assessment pass on the four large files (`mcp/lib.rs`, `host.rs`, `analyze.rs`, `llm_provider.rs`) — they are the focal points for ROI on any refactor budget.
+- Security-surface pass on the HTTP read API (HMAC implementation, body cap, panic-on-unenumerated-middleware-error stance).
+- Test-pyramid analysis — given the 57% test/source ratio, where are the gaps? My read: storage and scanner are saturated; the host has happy-path-only integration coverage.
+
+---
+
+## 10. Pointers
+
+- **Architecture diagrams:** see `03-diagrams.md` (7 Mermaid diagrams: 2 C4 levels, 2 component, 2 sequence, 1 dependency graph).
+- **Per-subsystem detail:** see `02-subsystem-catalog.md`.
+- **Discovery (entry points, stack):** see `01-discovery-findings.md`.
+- **Validator report:** see `temp/validation-catalog.md`.
+
+End of report.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/answer-python-engineer.md b/docs/arch-analysis-2026-05-22-1924/temp/answer-python-engineer.md
new file mode 100644
index 00000000..649bebfd
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/answer-python-engineer.md
@@ -0,0 +1,125 @@
+# Python Engineering Analysis: Open Questions from 04-final-report §8
+
+**Date:** 2026-05-23 | **Scope:** Q1, Q2, Q5, and the flagged server/session interaction.
+
+---
+
+## Q1: Why the 25-file pyright restart constant?
+
+The constant was introduced in commit `68b719c` ("Bound Pyright dogfood analysis", 2026-05-20)
+with no rationale comment. `git log -S 'MAX_FILES_PER_PYRIGHT_SESSION'` confirms this was the
+introducing commit, and the diff contains no measurement, no profiling reference, and no
+explanation for the choice of `25`. The number is empirically ungrounded.
+
+The primary driver of Pyright RSS growth per session is the type graph for imported modules,
+which accumulates and does not shrink across `textDocument/didOpen`/`didClose` cycles. Per-file
+marginal cost drops once the import frontier saturates. The right boundary is the inflection
+point on a per-file RSS delta curve; that experiment has not been run. A `psutil`-based probe
+during `analyze` on the `elspeth` target corpus would close this.
+
+---
+
+## Q2: `pyright_session.py` at 1,406 LOC — cohesion story
+
+Both a file and class problem; the class is the root. `PyrightSession` (lines 131–890) bundles
+five distinct concerns:
+
+| Group | Methods | Lines |
+|-------|---------|-------|
+| Process lifecycle | `close`, `_ensure_process`, `_record_restart_or_poison`, `_start_process`, `_initialize`, `_resolve_executable`, `_subprocess_env`, `_start_stderr_drain`, `_drain_stderr` | 182–198, 586–680 |
+| LSP transport | `_request`, `_notify`, `_live_process`, `_write_message`, `_read_message`, `_handle_server_message`, `_workspace_configuration_result`, `_configuration_for_section` | 732–834 |
+| Call resolution | `resolve_calls`, `_resolve_with_pyright` | 199–256, 332–425 |
+| Reference resolution | `resolve_references`, `_resolve_references_with_pyright`, `_reference_target_ids` | 257–330, 427–511 |
+| Index + bookkeeping | `_deadline_for_file`, `_function_index_for_path`, `_record_finding`, `_pop_findings`, etc. | 531–590, 836–890 |
+
+The remainder of the file (lines 893–1406) is module-level AST helpers and visitors that belong
+with call resolution. The cleanest split is `_LspTransport` (process lifecycle + wire framing)
+extracted as a composable object; the transport seam would enable testing the LSP-protocol layer
+without wiring call or reference resolution. The `noqa: PLR0913` at `pyright_session.py:132`
+(13-parameter `__init__`) is the linter's proxy for the same signal.
+
+---
+
+## Q5 + interaction: Magic numbers and the server/session coupling
+
+### Constants classified
+
+**Wire-contract-pinned (must track Rust counterparts; not WP6 candidates):**
+
+| Constant | Location | Rust counterpart |
+|----------|----------|-----------------|
+| `MAX_CONTENT_LENGTH = 8 MiB` | `server.py:48` | `ContentLengthCeiling::DEFAULT` in `clarion-core/limits.rs` |
+| `MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512` | `pyright_session.py:43` | Same-named constant in `clarion-core/limits.rs` |
+| `STDERR_TAIL_LIMIT = 65536` | `pyright_session.py:49` | `STDERR_TAIL_BYTES = 64 KiB` in `host.rs` |
+
+None carry a comment naming the Rust counterpart. A Rust-side change will not propagate by inspection.
+
+**Operational tunables (WP6 `clarion.yaml` candidates):**
+
+| Constant | Location | Priority |
+|----------|----------|---------|
+| `MAX_FILES_PER_PYRIGHT_SESSION = 25` | `server.py:49` | High — see interaction below |
+| `MAX_PYRIGHT_RESTARTS_PER_RUN = 3` | `pyright_session.py:44` | High — name says "per run"; implementation is per session (see below) |
+| `PYRIGHT_INIT_TIMEOUT_SECS = 30.0` | `pyright_session.py:46` | High — gates every restart on slow nodes |
+| `PYRIGHT_CALL_TIMEOUT_SECS = 5.0` | `pyright_session.py:47` | Medium |
+| `PYRIGHT_FILE_TIMEOUT_SECS = 3.0` | `pyright_session.py:48` | Medium |
+| `MAX_REFERENCE_SITES_PER_FILE = 2000` | `pyright_session.py:45` | Low-medium |
+
+### The undocumented interaction
+
+`MAX_PYRIGHT_RESTARTS_PER_RUN` is named "per run" but the `_restart_count` and `_disabled`
+that implement it are instance state on `PyrightSession` (`pyright_session.py:158–159`).
+`server.py:217–219` destroys the instance every 25 files (`state.pyright.close(); state.pyright = None`),
+creating a fresh instance with `_restart_count = 0`. The constant's name states the intent; the
+implementation drifts from it.
+
+**Failure mode A:** A Pyright binary that crashes reliably exhausts its 3-restart budget,
+gets disabled via `_disabled = True` (`pyright_session.py:601–608`), and then silently regains
+full fault tolerance at file 26 when the server creates a new instance. On a 1000-file project
+this produces up to 40 restart cycles instead of one `CLA-PY-PYRIGHT-POISON-FRAME` disabling
+Pyright for the run. The Rust `CrashLoopBreaker` does not catch this — it operates at the
+plugin-process level, not the Pyright-subprocess level.
+
+**Failure mode B:** `_disabled = True` is also set on `FINDING_PYRIGHT_UNAVAILABLE` /
+`FINDING_PYRIGHT_INSTALL_FAILURE` (`pyright_session.py:620, 628, 646, 660, 670`). An environment
+where `pyright-langserver` is absent will call `shutil.which` and emit a redundant not-found
+finding on every 25-file boundary for the entire run.
+
+**Fix direction:** Promote `_disabled` and `_restart_count` from `PyrightSession` instance state
+to `ServerState`, so the 25-file restart doesn't reset them. Five lines.
+
+---
+
+## Confidence Assessment
+
+| Finding | Confidence | Basis |
+|---------|------------|-------|
+| `25` has no empirical basis in commit history | High | Full diff of `68b719c` verified; no measurement cited |
+| Five cohesion groups in `PyrightSession` | High | Full method map from `grep -nE` on all 1,406 lines |
+| Wire-contract constants coupled to Rust | High | Cross-referenced `server.py:48`, `pyright_session.py:43`, catalog entry for `clarion-core` |
+| Interaction failure modes A and B | High | `_restart_count`/`_disabled` instance-scoped at `pyright_session.py:158–159`; instance destroyed at `server.py:217–219`; `_disabled` set at lines 620, 628, 646, 660, 670 |
+| Pyright RSS growth mechanism | Moderate | Standard Node.js LSP behaviour; no heap profile of this version |
+
+## Risk Assessment
+
+- **Interaction fix** — Low risk, Easy revert. Fixing it changes observable finding counts in
+  existing tests (`test_pyright_session.py`); update expected counts accordingly.
+- **Wire-contract constants** — High severity if they drift from Rust; Low likelihood today.
+  Add `# NOTE: must match clarion-core/…` inline comments before the next Rust-side refactor.
+- **Moving tunables to config** — Wait for the WP6 config-schema design; premature promotion
+  produces unstable YAML key names.
+
+## Information Gaps
+
+1. **Pyright RSS profile on `elspeth`** — needed to replace `25` with an evidence-based bound.
+2. **Characterization test for cross-session restart behaviour** — failure mode A has no dedicated
+   test asserting the reset behaviour, making a fix unverifiable without one.
+3. **WP6 timeline** — "WP6" is named in `breaker.rs:7` but its current status is not visible
+   from source.
+
+## Caveats
+
+- `extractor.py` (918 LOC) is the second-largest Python file and was not audited here; it may
+  carry its own cohesion debt.
+- Q2 split recommendation is structural, not test-driven. Characterization tests for
+  `resolve_calls` / `resolve_references` / `close` must precede any extract.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/answer-quality-engineer.md b/docs/arch-analysis-2026-05-22-1924/temp/answer-quality-engineer.md
new file mode 100644
index 00000000..bfc61db6
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/answer-quality-engineer.md
@@ -0,0 +1,102 @@
+# Quality-Engineering View on the Five Open Questions
+
+**Date:** 2026-05-23
+**Source evidence:** `04-final-report.md` §6/#11, §8; `02-subsystem-catalog.md` §1 (clarion-core), §4 (clarion-mcp); all source files and test files cited below read directly.
+
+---
+
+## Q1: Why 25 files per pyright restart? Is there a test that catches a regression in pyright memory behavior?
+
+The constant is `MAX_FILES_PER_PYRIGHT_SESSION = 25` at `plugins/python/src/clarion_plugin_python/server.py:49`.
+
+One test exists: `test_analyze_file_restarts_pyright_after_file_budget` (`plugins/python/tests/test_server.py:396`). It monkeypatches the constant to `2`, uses a fake `PyrightSession`, and asserts the state-machine transition: the session is closed and `state.pyright_files_since_restart` resets to `0`. That test catches a **mechanical regression in the recycle loop** — it does not and cannot validate that 25 is the right number. The fake session carries no memory state.
+
+**Missing test:** A soak/memory-growth integration test that runs a real `PyrightSession` against 50+ small Python files, samples the pyright subprocess RSS at each session boundary, and asserts that the process never exceeds a threshold before recycling. Without this, the value 25 is empirical lore that a future committer will treat as arbitrary and reduce to 10 or raise to 100 with no regression net. If the motivation is memory growth in pyright's Node heap, that is the test that makes the number legible.
+
+---
+
+## Q2: Which monolith has the most asymmetric test coverage for its change risk? Where is the highest-priority test gap?
+
+The four monoliths compete, but the answer is `clarion-cli/src/analyze.rs` (`run_with_options`, 570 lines, 13 ordered phases).
+
+The other three are better served than they look:
+
+- `host.rs` (2,935 LOC) has extensive inline coverage: T1, T5 (path-escape), T6 (breaker trip), T8a–e (oversize fields), T9 (cap exceeded), T9b (stderr drain), T10–T11 (manifest security), plus the 876-LOC `mock.rs` enabling in-process pipeline testing without subprocesses.
+- `llm_provider.rs` (2,467 LOC) has 22 inline tests across all four provider variants, including fake-subprocess tests for `CodexCliProvider` and `ClaudeCliProvider`.
+- `mcp/lib.rs` (4,703 LOC) has a `tests/storage_tools.rs` (2,200 LOC) that covers all 19 tool dispatch paths.
+
+`analyze.rs` has no such seam. Its 13 phases form a strict sequential gate: orphan recovery → secret scan → `BeginRun` → plugin loop → entity ingestion → clustering → `CommitRun`. The whole pipeline is tested only end-to-end by `wp1_e2e.rs` and `wp2_e2e.rs` which spin up a real plugin and a real database. There is no per-phase test seam — you cannot, for example, inject a crash after `BeginRun` but before entity ingestion and assert the run row ends in `failed`, or verify that `SoftFail` vs. `HardFail` branching produces the correct `runs.status` without running the entire binary.
+
+**Highest-priority missing test:** an integration test against `run_with_options` (or a factored helper it calls) that injects a writer-actor failure mid-run and asserts `CommitRun(Failed)` vs. `FailRun` semantics. This is the test that would unblock any refactor of the 570-line function because it establishes what each phase transition must guarantee independently of the others.
+
+---
+
+## Q3: Are the OpenRouter / Claude-CLI / Codex-CLI providers tested? What gap would a clarion-llm extraction surface?
+
+All four providers have tests. `CodexCliProvider` and `ClaudeCliProvider` use fake bash scripts at `llm_provider.rs:1853+` and `2087+`. `OpenRouterProvider` is exercised with a real in-process TCP listener at `clarion-mcp/tests/storage_tools.rs:1237`. `RecordingProvider` is used throughout.
+
+The gap is not per-provider — it is **trait-contract uniformity across providers**. No test runs the same `LlmRequest` through all four `LlmProvider` implementations and asserts:
+- Identical `LlmResponse` field shapes (particularly `model_id` passthrough and token count presence).
+- Consistent timeout behavior (both CLI providers have reaper threads; OpenRouter uses `reqwest` timeouts — no test verifies they degrade identically).
+- Ring-buffer overflow in CLI stdout (the bounded ring in `ClaudeCliProvider`/`CodexCliProvider` is untested at capacity).
+
+If `clarion-llm` is extracted as a crate, the extraction would immediately require a shared integration test fixture that exercises the trait contract across all four providers against a common suite. That fixture does not currently exist; the extraction would surface its absence as a compilation-time discovery of test gaps rather than a runtime one.
+
+---
+
+## Q4: What test would catch a cross-version DB collision? Does it exist?
+
+Adding `PRAGMA application_id` and `PRAGMA user_version` to `clarion-storage` is one change in `pragma.rs`. The tests to validate that change do not exist.
+
+The specific missing tests in `crates/clarion-storage/tests/schema_apply.rs`:
+
+1. **`open_refuses_db_with_foreign_application_id`** — create a SQLite file with `PRAGMA application_id = 0x0F11BEEF` (a hypothetical Filigree or Wardline value), call `apply_write_pragmas` + `apply_migrations`, assert it returns an error before touching schema. Without this test, adding the PRAGMA has no regression net: a future relaxation of the check would go undetected.
+
+2. **`open_refuses_db_from_future_user_version`** — create a DB with `PRAGMA user_version = 999`, call `apply_migrations`, assert it refuses to downgrade. This is the test that catches two Clarion versions sharing a DB by accident — the scenario that prompted Q4.
+
+Neither test exists today (`schema_apply.rs` has 10+ tests, zero touch `application_id` or `user_version`). The retroactive risk named in the report is real: once installed DBs exist in the wild, the PRAGMA values become a wire contract that cannot be set without a migration, so the window for adding this protection cheaply is before first external deployment.
+
+---
+
+## Q5: Which of the 11 limit constants are covered by tests that would catch a value change being wrong?
+
+| Constant | Location | Test status | Test that catches a wrong value |
+|---|---|---|---|
+| `MAX_PROTOCOL_ERROR_FIELD_BYTES` | `protocol.rs:245` | **Tested** | `protocol.rs` inline: `huge` string asserts truncation at boundary |
+| `MAX_ENTITY_FIELD_BYTES` | `host.rs:66` | **Tested** | `host.rs` T8a–d: oversize qualified name / file path / id / kind |
+| `MAX_ENTITY_EXTRA_BYTES` | `host.rs:82` | **Tested** | `host.rs` T8e: oversize extra map is dropped with finding |
+| `MAX_HEADER_LINE_BYTES` | `transport.rs:45` | **Tested** | `transport.rs:542`: oversize header returns `MalformedHeader` |
+| `ContentLengthCeiling::DEFAULT` | `limits.rs` | **Tested** | `limits.rs:370,387`: default value pinned; `host.rs:2471`: surfaces through pipeline |
+| `EntityCountCap::DEFAULT_MAX` | `limits.rs` | **Tested** | `limits.rs:432`: cap at 500,000 pinned; `host.rs:2316`: T9 kills plugin on overflow |
+| `PYRIGHT_MAX_NPROC` | `host.rs` | **Tested** | `host.rs:1380`: `pyright_runtime_raises_process_ceiling_for_language_server` |
+| `DEFAULT_MAX_RSS_MIB` | `limits.rs:261` | **Weak** | `limits.rs:561,569`: only verifies `apply_prlimit_as` does not panic, not that the child is actually memory-constrained |
+| `DEFAULT_MAX_NOFILE` | `limits.rs:281` | **Weak** | No behavioral test; constant referenced by `host.rs:576` in `pre_exec`, but `host_subprocess.rs` has no test that opens > 256 file descriptors and observes enforcement |
+| `DEFAULT_MAX_NPROC` | `limits.rs:289` | **Weak** | Same gap as `NOFILE` — `pre_exec` path covered only by code review |
+| `MAX_UNRESOLVED_CALLEE_EXPR_BYTES` | `host.rs:70` | **Untested** | Used at `host.rs:267` to drop oversized call sites, but no inline or integration test constructs a callee expression > 512 bytes and asserts the drop |
+| `STDERR_TAIL_BYTES` | `host.rs:445` | **Partially tested** | `T9b` verifies drain thread is attached and `stderr_tail()` returns `Some(_)`, but does not overflow the ring to test the drop-from-front eviction |
+
+**Highest-value missing test:** `host_subprocess.rs::rlimit_as_actually_enforced_on_child` — spawn a plugin whose manifest requests a pyright-capable runtime (triggering the larger `RLIMIT_AS` path), allocate more than `DEFAULT_MAX_RSS_MIB` inside the child, and assert the child is killed with `CLA-INFRA-PLUGIN-OOM-KILLED`. Currently the `RLIMIT_AS` enforcement path in `host.rs:569–586` is validated only by code review and the `pre_exec` non-panic test. A value change to `DEFAULT_MAX_RSS_MIB` has no regression net beyond Clippy and the CI build.
+
+---
+
+## Confidence Assessment
+
+**High** on Q1, Q4, Q5 — directly verifiable from source and test files read end-to-end.
+**High** on Q3 — all provider test locations confirmed; the gap named is structural (trait-contract suite), not a coverage metric claim.
+**Medium-High** on Q2 — the claim that `analyze.rs` has no per-phase seam is based on reading the function signature and the test files, not on reading all 570 lines of the function body to exhaustion.
+
+## Risk Assessment
+
+The highest-risk gap is Q5's `DEFAULT_MAX_RSS_MIB` / `DEFAULT_MAX_NOFILE` / `DEFAULT_MAX_NPROC` cluster: these are security-enforcement constants in the plugin isolation layer, and their behavioral coverage is "does not panic." A change that accidentally weakens plugin memory limits would not be caught in CI.
+
+The second-highest is Q4: the `application_id`/`user_version` window closes permanently once installed databases exist in the field. The cost of adding it now is one PRAGMA + two tests. The cost after first external deployment is a migration + cross-version compatibility matrix.
+
+## Information Gaps
+
+- Actual pyright process RSS growth curve is not observable from test files — Q1's "empirical vs. conservative bound" distinction cannot be resolved from code alone.
+- `STDERR_TAIL_BYTES` ring eviction is not confirmed to be tested; `T9b` covers attachment, not overflow. An adversarial test would need to send > 64 KiB to stderr and verify the tail contains only the last 64 KiB.
+
+## Caveats
+
+- The Q2 characterization of `analyze.rs` as the most asymmetric file depends on the claim that `mcp/lib.rs` has adequate per-tool coverage. That claim rests on the `storage_tools.rs` test file being broad-coverage — it was confirmed by sampling, not exhaustive read.
+- The Q3 ring-buffer-overflow gap is inferred from reading the provider source and finding no test that exercises it, not from a coverage tool.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/answer-security-engineer.md b/docs/arch-analysis-2026-05-22-1924/temp/answer-security-engineer.md
new file mode 100644
index 00000000..759f3820
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/answer-security-engineer.md
@@ -0,0 +1,65 @@
+# Security-architecture view on the five §8 open questions
+
+**Role**: Threat analyst (STRIDE + attack-surface focus).
+**Question**: Which of the five §8 questions have *security* answers, and which are operational/architectural neutral?
+
+## Verdict matrix
+
+| Q | Topic | Security-relevant? | Dominant STRIDE category |
+|---|-------|--------------------|--------------------------|
+| Q1 | 25-file pyright restart | **Marginal** — DoS-adjacent, but the constant is a *mitigation*, not a threat surface | D |
+| Q2 | Monolith refactor (host.rs 2935 LOC) | **Yes — high-stakes** | T, E, R |
+| Q3 | `clarion-llm` split | **Yes — moderate** | T, I (supply-chain + outbound trust) |
+| Q4 | `application_id` / `user_version` | **Yes — but mostly integrity, not confidentiality** | T (and a sliver of S in multi-tenant Loom) |
+| Q5 | Hardcoded limits (11+) | **Yes — this is the question with the most teeth** | D, E |
+
+## Per-question analysis
+
+**Q1 — Pyright 25-file restart.** The constant is the *fix* for memory growth, not the surface. The real question is what happens if a pathological corpus drives Pyright RSS above the host's tolerance *within* a 25-file window. Today the answer is "the `RLIMIT_AS` 2 GiB ceiling on the plugin child kills it, the supervisor emits `FINDING_OOM_KILLED`, the run aborts cleanly." So Q1 has a security answer only in the sense that **the 25-file constant is itself a tuned defense parameter**, which folds into Q5. Standalone, neutral.
+
+**Q2 — Monolith refactor.** This is the most security-load-bearing answer in the set. `host.rs` (2935 LOC) concentrates the four-stage pipeline, stderr drain, child reaping, breaker wiring, jail-check sequencing, and supervisor signal handling. The threat is **Tampering with security mechanisms via accidental refactor** — STRIDE-T against the supervisor itself, with Elevation as the eventual consequence (a plugin that should have been killed keeps running). Concrete failure modes a careless extract-method introduces:
+
+- Breaker `record_escape` called on wrong code path → path-escape budget effectively infinite.
+- Stderr drain detached from child-reap → zombie + log-channel DoS.
+- `pre_exec` ordering broken (setrlimit applied after exec) → RLIMIT_AS no longer applies to the child.
+- Jail-check moved *after* a downstream consumer that opens the path → revives the TOCTOU window (see below).
+
+The risk is not that refactoring is impossible; it is that **the file has no test that says "the supervisor still kills the plugin under the breaker policy after this refactor."** Recommendation: before splitting `host.rs`, add a property-style integration test that asserts each ADR-021 §2a–§2d invariant survives module boundary changes. Then refactor.
+
+**Q3 — `clarion-llm` split.** Currently `reqwest` (and TLS, and DNS) is reachable from the same crate that supervises plugins. **Outbound HTTP from inside the plugin-supervisor crate is a meaningful trust-surface widening** — a CVE in `reqwest`/`hyper`/`rustls` becomes a CVE in the process that holds the jail. Splitting `clarion-llm` into its own crate (and ideally its own process) is a defense-in-depth win: blast radius of an outbound-HTTP-stack exploit no longer reaches plugin supervision. STRIDE-T (compromised LLM client tampering with supervisor state) and STRIDE-I (LLM client exfiltrating jail-passed paths via DNS/SNI side channels) both shrink. **This question has a security answer: yes, split it, and the security argument is independent of the architectural one.**
+
+**Q4 — `application_id` / `user_version`.** Mostly an integrity question (`user_version` for migrations) — but `application_id` has a **specific Loom-federation security value**: it lets a sibling tool refuse to operate on a database that isn't Clarion's. Without it, a misconfigured Filigree pointed at a stale or hostile `.clarion/state.db` cannot detect the substitution at the file-format layer. STRIDE-S (spoofing a Clarion DB at the federation read boundary). The cross-tool collision-detection benefit is real and cheap; set both, and have the storage layer refuse to open a DB whose `application_id` does not match. Not P0, but trivially worth doing.
+
+**Q5 — Hardcoded limits.** This is the question with the most security weight. The 11+ values include the entity cap (500k), the Content-Length ceiling (8 MiB), the path-escape breaker threshold (10/60s), RLIMIT_AS (2 GiB), RLIMIT_NOFILE (256), RLIMIT_NPROC (32), HTTP body limit (16 KiB), concurrency limit (64), request timeout (10s), batch maxima (256/1000), and the pyright restart. **Recompile-to-tune is a security posture stance**: it means an operator under active adversarial-plugin pressure cannot tighten the breaker threshold from 10 to 3 without a rebuild. ADR-021 §2b already nods at this by mentioning a "configuration-surface" floor that isn't yet plumbed. The honest answer: **at v1.0 these are deliberately frozen so the security policy is uniform across deployments; post-1.0, the path-escape breaker threshold, the entity cap, and the RLIMIT_AS ceiling should become operator-tunable with hard floors enforced at config-load time.** The HTTP-body and concurrency limits can stay compiled-in (operational, not adversarial).
+
+## TOCTOU claim
+
+The catalog's "latent because current consumer doesn't open files" claim is **correct as of today** and **explicitly documented in `jail.rs` lines 67–72**. The function returns a `PathBuf` that is a "membership proof at canonicalization time, not a durable file handle." A future consumer that calls `jail(...)` then `std::fs::open(returned_path)` opens the canonical path — but between canonicalize and open, an attacker with write access to a directory on the canonical path (e.g. a plugin that can mutate its own workspace) can replace a path segment with a symlink to `/etc/shadow`. The next open follows the new symlink. **Concrete exploit**: plugin returns `<root>/staging/report.txt`, supervisor jail-checks it OK, plugin races a `rename` to swap `staging` for a symlink to `/etc`, supervisor opens `report.txt` and reads `/etc/passwd`. The mitigation is the `openat`-anchored-to-pinned-root strategy the docstring recommends; do this *before* any code path opens a jail-returned path.
+
+## Confidence Assessment
+
+**High** on Q2 (monolith risk is concrete and grounded in the source), Q3 (trust-surface argument is standard), and the TOCTOU exploit chain (the file documents the gap itself).
+**Medium** on Q4 (the Loom federation S-axis is real but I haven't audited every sibling's DB-open path) and Q5 (specific recommendations on *which* limits to make tunable are judgment calls, not derivations).
+**Low** on Q1 — I'm 60% confident it is "neutral folded into Q5"; could be argued the 25-file number is itself an adversary-tunable surface if a malicious corpus could be shaped to exhaust the host before the restart fires.
+
+## Risk Assessment
+
+If these answers are wrong: Q2 is the only one where being wrong is dangerous — recommending a refactor without first writing invariant-preserving tests could ship a broken jail. Q3/Q4/Q5 errors are forward-only (failure to *add* defense-in-depth, not removal of existing defense). Q1 has no downside either way.
+
+## Information Gaps
+
+- No audit of who opens jail-returned paths today; the claim "no current consumer" is from the docstring, not from a callsite sweep.
+- Have not read every limit's actual call site to confirm "recompile-to-tune" applies uniformly. ADR-021 §2b suggests configuration-surface plumbing was contemplated but deferred.
+- The `clarion-llm` outbound-HTTP threat model assumes the crate ships TLS — not verified.
+
+## Caveats
+
+- This is a STRIDE-shaped read, not a full threat model with attack trees. The Q2 monolith risk in particular deserves its own attack tree (root: "plugin escapes supervisor invariants via refactor regression").
+- "Defense-in-depth" arguments are inherently judgment calls; a smaller team may reasonably prefer the operational simplicity of one HTTP stack over the security win of splitting `clarion-llm`.
+
+## Relevant paths
+
+- `/home/john/clarion/crates/clarion-core/src/plugin/jail.rs` (TOCTOU documented at lines 67–72)
+- `/home/john/clarion/crates/clarion-core/src/plugin/limits.rs` (constants at lines 71, 142, 209–211, 261, 281, 289)
+- `/home/john/clarion/crates/clarion-core/src/plugin/host.rs` (the 2935 LOC monolith — Q2)
+- `/home/john/clarion/crates/clarion-cli/src/http_read.rs` (HMAC > bearer > loopback chain at lines 392–419; unauthenticated `_capabilities` at line 372; panic-on-unenumerated middleware error at lines 547–557; loopback-no-token warning at lines 199–252)
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/answer-solution-architect.md b/docs/arch-analysis-2026-05-22-1924/temp/answer-solution-architect.md
new file mode 100644
index 00000000..dd23d9a0
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/answer-solution-architect.md
@@ -0,0 +1,94 @@
+# Architect Answers — Five Open Questions from §8
+
+Scope: the five §8 open questions in `04-final-report.md`. Source: catalog, ADRs, `gap-register.md`, the actual code paths, and the filigree open-issues queue. No diplomatic softening.
+
+---
+
+## 1. Why `MAX_FILES_PER_PYRIGHT_SESSION = 25`?
+
+**Recommendation:** Keep the value, label it. The constant is an unjustified-in-code heuristic introduced in commit `68b719c` ("Bound Pyright dogfood analysis", 2026-05-20) with no commit-message or in-file rationale (`plugins/python/src/clarion_plugin_python/server.py:49`). The diff added recycling but cited no measurement. Interpreted in context — "dogfood analysis" implies it surfaced during operator-driven runs against Clarion itself — this is an **empirical conservative bound** chosen to stop observed pyright RSS growth, not a derived figure. The 25-file window is short enough to be safe and long enough to amortise the ~150 ms `pyright_init_ms` measured in `sprint-2/b4-gate-results.md:19`.
+
+**Risk of inaction (no documentation, no measurement):** The next operator who hits pyright OOM on a heavy-import file at file 24 has nothing to tune and no way to know whether 25 is conservative or aggressive. Worse, the constant is divorced from `MAX_PYRIGHT_RESTARTS_PER_RUN` (`pyright_session.py:142`) — server-side recycling at 25 files can keep tripping session-side restart caps, and vice versa, with no centralised policy.
+
+**Risk of acting now:** Approximately zero. A one-line comment and a TODO citing `pyright_files_since_restart` plus the session-side restart cap costs nothing.
+
+**Evidence that would change the call:** A measurement run on the elspeth corpus (~425k LOC) sampling pyright RSS per `analyze_file` call. If the curve plateaus before 25, the recycle is wasted re-init cost (~150 ms × N); if it climbs steeply past 15, 25 is already too lax. Either outcome justifies a measured override and config surface.
+
+---
+
+## 2. Post-1.0 plan for the four monolith files
+
+**Recommendation:** Defer all four splits, with one named trigger per file. "No split until it actively impedes a change" is **defensible at this scale** — ~50K LOC of first-party code, 7 subsystems, no inter-crate cycles, a single maintainer, ~57% test/source ratio. The change-amplification cost is real but bounded, and splits done without a forcing function tend to re-coalesce or fragment along the wrong axis. There is no roadmap for these splits in any ADR, sprint doc, or filigree issue — that absence is itself a defensible posture for 1.0, not a planning gap.
+
+The triggers that should fire a split (per file):
+
+- **`clarion-mcp/src/lib.rs` (4,703 LOC):** trigger is adding a 20th tool, or any concurrent-tool-execution work. The tool registry shape (`lib.rs:56-257`) already wants to be a per-category module set. Until then it reads as one file with clearly named sections.
+- **`clarion-core/src/plugin/host.rs` (2,935 LOC):** trigger is adding a fifth enforcement layer or changing the four-stage pipeline ordering (`host.rs:866-975`). A natural pipeline-axis / lifecycle-axis / IO-axis split exists but each axis pulls in `mock.rs` (876 LOC, also flagged) and the cost of getting the seams wrong is high.
+- **`clarion-cli/src/analyze.rs` (2,549 LOC; `run_with_options` 570 lines):** trigger is the 14th phase. The current 13-phase linearisation is legible exactly because it is one function with one error scope. Extracting per-phase helpers without first naming the contract between phases (entity buffer ownership, breaker tick sites, partial-results semantics) just hides the linearity behind call indirection. The catalog already flagged the in-memory entity buffer (`02-subsystem-catalog.md` line 276) as the load-bearing latent risk — that is the issue worth fixing, not the line count.
+- **`clarion-core/src/llm_provider.rs` (2,467 LOC):** see Q3 — this one has a stronger argument for splitting **out of `clarion-core`**, not within it.
+
+**Risk of inaction:** Change-amplification per touch grows monotonically. Every new MCP tool, every new enforcement layer, every new analyze phase makes the next refactor more expensive. At 6,000 LOC `mcp/lib.rs` will be genuinely hard to navigate.
+
+**Risk of acting now:** Premature splits chosen on the wrong axis, retest cost across all four files concurrently, and architectural drift while the splits are in-flight. Splitting `host.rs` mid-sprint while WP6 wires the config surface (see Q5) would be especially expensive.
+
+**Evidence that would change the call:** A concrete change request that touches 3+ of these files in the same PR, or a contributor onboarding that stalls on "where do I put new tool X". Either signal flips the calculus.
+
+---
+
+## 3. Will `clarion-llm` become a crate?
+
+**Recommendation:** Yes, and it is **already named in `docs/clarion/1.0/detailed-design.md:1745`** as one of the intended workspaces (`clarion-core`, `clarion-cli`, `clarion-plugin-protocol`, `clarion-api`, `clarion-llm`). The current placement of `llm_provider.rs` in `clarion-core` is an **expedient, not a deliberate boundary call**: the detailed design says where it goes and the code does not yet match. `clarion-core/lib.rs:1` advertises the crate as owning "domain types, identifiers, and provider traits" — the OpenRouter `reqwest` transport and the two CLI-subprocess providers (Claude, Codex shellouts) are neither.
+
+**Risk of inaction:** `clarion-core` pins `reqwest` (with rustls) and CLI-subprocess machinery into the same crate that supervises plugins. That widens the trust surface of the host runtime — a malicious dependency in the LLM HTTP stack lives inside the crate that handles `pre_exec` `setrlimit` for plugin children. The blast radius argument alone is sufficient. Secondary: every new LLM provider drives a recompile of `clarion-core`, which forces recompile of every downstream crate.
+
+**Risk of acting now:** A pre-1.0 crate split during release cut adds churn. ADR-030 narrowed WP6 to a single MCP `summary(id)` tool — the LLM surface is at its minimum scope right now, which is paradoxically the **best** time to split (small surface = small move) but also the time when "ship the tag" pressure resists any refactor.
+
+**Evidence that would change the call:** None substantive. The recommendation here matches the documented intent. The only open question is timing — pre-`v1.1.0` or after.
+
+---
+
+## 4. `application_id` / `user_version` PRAGMAs
+
+**Recommendation:** Add both, now. This is already filed as **`clarion-f2a984fd6d` — `[v1.0 blocker] Set PRAGMA application_id on writer open`** (P1, ready, blocks two other issues), with a fix specified in `docs/implementation/v1.0-tag-cut/gap-register.md` STO-02: `PRAGMA application_id = 0x434C524E` ("CLRN") and assert on open. There is nothing to decide here. The architect already decided; the issue is open and ready.
+
+`user_version` should also be set, even though the application-level `schema_migrations` table (`schema.rs:17-91`) tracks migration state. The two solve different problems: `application_id` identifies the file as Clarion's; `user_version` provides a fast PRAGMA-level read of "what migration level is this" without opening the table. The current model fails confusingly when a non-Clarion sqlite file happens to live at `.clarion/clarion.db` — `apply_migrations` will create tables in someone else's database. `application_id` mismatch turns that into a hard fail at open.
+
+**Risk of inaction:** Bounded but real. Today's only victim is the operator who points `clarion install --path` at a directory whose `.clarion/clarion.db` is from a sibling tool, or a future v2.0 Clarion that opens a v1.0 file. Both are tractable until installed DBs exist in the wild.
+
+**Risk of acting now:** Effectively zero. PRAGMA additions don't break readers; the `apply_write_pragmas` site already exists.
+
+**Evidence that would change the call:** None.
+
+---
+
+## 5. Operational tuning roadmap (WP6 / 11+ hardcoded limits / 25-file pyright / 256/50 batch cadence)
+
+**Recommendation:** Ship 1.0 with the limits hardcoded. Land the config surface in WP6 post-1.0 as **one ADR-021-aligned change** rather than dripping per-constant overrides.
+
+ADR-021 §4 already names the config keys for four of the eleven limits — `plugin_limits.max_frame_bytes` (floor 1 MiB), `plugin_limits.max_records_per_run` (floor 10,000), `plugin_limits.max_rss_mib` (floor 512 MiB), and named `expected_max_rss_mb` in the manifest. These are **promised** by an Accepted ADR and **not implemented**. `breaker.rs:7`'s comment names WP6 as the home for this surface. The `2026-04-19-wp2-tasks-4-to-9-handoff.md:203` line says the crash-loop parameters are "hard-coded for Sprint 1; config surface deferred to WP6". WP6's v0.1 scope was narrowed by ADR-030 to the on-demand `summary(id)` MCP tool — **the operator-tunables work was not folded into the narrowed WP6 scope and is currently un-homed**.
+
+The catalog's eleven-limit list (`02-subsystem-catalog.md` line 97) plus the 25-file pyright restart plus the writer's 256-cap mpsc and 50-write batch cadence (`writer.rs:35, 38, 813`) plus the per-batch HTTP cap of 256 queries (pinned on the wire by ADR-034, so **not** operator-tunable) all want different homes:
+
+- **Plugin host enforcement (frame ceiling, entity cap, RSS, NOFILE, NPROC, field bytes, stderr tail, header bytes, callee-expr bytes):** belong in `clarion.yaml:plugin_limits.*` per ADR-021. Eight of the eleven.
+- **Writer-actor cadence (256 mpsc, 50-write batch):** belong in `clarion.yaml:storage.*` per the same shape ADR-011 already hints at.
+- **Pyright session recycle (25):** belongs in `plugin.toml` (plugin-owned policy) or per-language plugin config, not core-side.
+- **Crash-loop window (>3 / 60 s):** belongs in `clarion.yaml:plugin_limits.crash_loop` per `handoff:203`.
+- **Batch HTTP cap (256):** pinned on the wire, not tunable (ADR-034 §3).
+
+**Risk of inaction:** ADR-021's "configurable" claim becomes false advertising on the operator's first read. The elspeth-scale test (425k LOC Python) is the named first customer; if RSS or entity cap defaults are wrong, the operator has no remediation short of patching source and rebuilding. Every limit is a recompile today; the catalog is correct that "operator can tune" is aspirational.
+
+**Risk of acting now (pre-1.0):** Scope creep on a release cut. The shape of the config block is contestable and locking the wrong shape into `clarion.yaml` before the first real elspeth run is worse than landing nothing. WP6 is a post-1.0 ADR-named home; **that is the correct place**.
+
+**Evidence that would change the call:** Either (a) elspeth-scale dogfood data showing any single hardcoded limit is wrong by an order of magnitude — that constant goes to WP6 priority; or (b) a v1.1 issue triaged from the field where the operator could not work around the limit without a custom build. Currently neither exists in the filigree queue.
+
+---
+
+## Confidence, risk, gaps, caveats
+
+**Confidence:** High for Q1 (commit message confirms post-hoc bound, no design-doc rationale), Q3 (`detailed-design.md:1745` names the crate), Q4 (already a v1.0-blocker issue with a documented fix). Medium-High for Q2 (no roadmap exists; defensibility argument is judgement, not evidence). Medium for Q5 (ADR-021/ADR-030/handoff fragments triangulate the WP6 home but no single doc spells out the full eleven-constant migration plan).
+
+**Risk assessment:** The only standing High-risk item in the §8 set is the LLM transport living in `clarion-core` (Q3), and only because of the blast-radius coupling to the plugin supervisor. Q4 is High-severity but Low-risk because the fix is filed and ready. Q1, Q2, Q5 are Medium and Medium-Low respectively.
+
+**Information gaps:** (a) No measurement curve for pyright RSS vs. files-processed exists in the repo; Q1's "conservative bound" interpretation is inferred from the commit title and the 150 ms init cost in `b4-gate-results.md`, not directly attested. (b) No post-1.0 sprint plan exists for the four monolith splits; Q2's "defer with named trigger" recommendation is the architect's call, not a documented decision. (c) The WP6 config-surface scope after ADR-030's narrowing is not written down anywhere — Q5 reconstructs it from fragments.
+
+**Caveats:** All five questions ask for stances the source code cannot reveal. Each recommendation here is contingent on the design-doc intent the user wrote down (ADR-021, ADR-030, detailed-design.md §workspaces). If those intents have shifted in conversation since the docs were last updated, the recommendations shift accordingly. The strongest signal in this set is Q4 — the gap-register and the filed P1 issue make that one not a judgement call.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/answer-systems-thinker.md b/docs/arch-analysis-2026-05-22-1924/temp/answer-systems-thinker.md
new file mode 100644
index 00000000..1a6170d9
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/answer-systems-thinker.md
@@ -0,0 +1,70 @@
+# Leverage Analysis: The Five Open Questions as One System Pattern
+
+## The pattern
+
+The five questions look like five concerns. They are one. Each is a **missing-feedback-loop** symptom: a place where operational reality has no path back to the artifact that would change behavior. They wear "parameter" clothing (Level 12) but live at **Level 6 (information flows)** and **Level 5 (rules)**.
+
+The smoking gun is named in the source itself. `crates/clarion-core/src/plugin/breaker.rs:7` flags that operator-tunable limits land "in WP6"; `crates/clarion-cli/src/analyze.rs:74` carries `#[allow(clippy::too_many_lines)]` — an alarm explicitly disabled. The architecture has placeholders where its feedback loops should be.
+
+## Archetype: Drift to Low Performance
+
+Meadows' "drift to low performance" fits cleanly. Each individual deferral is locally rational ("ship 1.0; tune later"; "don't split host.rs mid-sprint"; "PRAGMAs are post-1.0"). The standard erodes silently because there is **no countervailing signal** pushing the other way. The clippy allow is the standard-lowering act made literal in code.
+
+Concretely, each question is the same shape:
+
+| Q | Surface symptom | Missing loop |
+|---|---|---|
+| 1 (`MAX_FILES_PER_PYRIGHT_SESSION=25`) | parameter with unknown basis | rationale → constant → retune trigger |
+| 4 (`application_id`/`user_version`) | absent schema identity | DB collision → detection → action |
+| 5 (11+ hardcoded limits) | every tunable is a recompile | production behavior → tuning surface |
+| 2 (four monoliths) | 4,703-line `mcp/lib.rs`, etc. | file growth → back-pressure → split |
+| 3 (`clarion-llm` in core) | `lib.rs:1` doc-comment contradicts contents | boundary statement → enforcement |
+
+§6.5 ("no `application_id`/`user_version` is a one-line change with no downside"), §6.8 ("every tunable is a recompile today"), and §8 Q5 ("WP6 is named in code comments — what is its current status?") all describe the same gap from different angles. The Python-plugin catalog quote — "every limit is a recompile" — is the cleanest single-line statement of it.
+
+## The highest-leverage intervention
+
+**Level 5 (rule), instantiated as one ADR: "Operational tuning discipline."** Every operational constant must declare: (a) a stated basis (empirical / safety-margin / contract-derived), (b) an operator override surface (`clarion.yaml` field or env var), (c) a retune trigger (the metric or finding subcode that should prompt revisiting it). Apply the same rule-shape — explicit budget + override + trigger — to file size and crate-boundary budgets.
+
+This single rule closes Q1, Q4, Q5 directly (every limit, including the 25-file restart, gains a recorded basis and a tuning surface; PRAGMA identity becomes a "schema identity" instance of the same rule) and structurally addresses Q2 and Q3 (file-LOC and "what belongs in this crate" become budgeted properties with a trigger to act, rather than aesthetic preferences competing with sprint load).
+
+This is **not** "add a config file." A config file without the rule decays back to hardcoded constants on the next sprint — that is exactly how Clarion got here. The rule is what creates the surface; the surface alone is a parameter intervention (Level 12) and parameter interventions to a drift-to-low-performance loop reset the constant without changing the slope.
+
+## What changes, concretely
+
+1. Author an ADR ("Operational discipline: declared basis + override + trigger for every limit"). Cite §6.8 + §8 Q5 + the `breaker.rs:7` comment as the originating evidence. Promote it to Accepted before any further hardcoded limit lands.
+2. Apply the rule retroactively to the 11 limits in §6.8 plus `MAX_FILES_PER_PYRIGHT_SESSION` (Q1) and the writer-actor's 256 / 50 cadence constants. The artifact is a table in `detailed-design.md` keyed by constant name.
+3. Add `application_id` + `user_version` (Q4) as the schema-identity instance of the same rule — basis stated, trigger ("DB opened with mismatched id → refuse").
+4. Adopt file-LOC and per-crate-doc-comment budgets with CI enforcement: `clippy::too_many_lines` is **not** allowed without an ADR-referenced waiver; `lib.rs:1` doc-comment violations are a `cargo deny`-style check. This closes Q2/Q3 by creating the missing back-pressure loop.
+
+## Feedback loops the architecture currently has vs. lacks
+
+**Has (strong):** the path-escape and crash-loop breakers (rolling-window → kill); the writer-actor invariant check (`parent_contains_mismatch` aborts the run); the cross-language fixture parity test (drift caught in CI). These are exemplary balancing loops at the *runtime* layer.
+
+**Lacks:** any equivalent loop at the *design-time* layer. The runtime has back-pressure; the architecture itself does not. File LOC grows, doc-comments drift from contents, limits accrete — and nothing ticks.
+
+## Confidence Assessment
+
+**High** that the five questions cluster as one missing-feedback-loop pattern; the `breaker.rs:7` WP6 reference and the §6.8 enumeration are explicit. **High** that Level 5 is the correct leverage point. **Medium** on the specific archetype label ("drift to low performance" vs. "shifting the burden" — both fit; I chose drift because the standard-lowering is visible in code, not just behavior).
+
+## Risk Assessment
+
+- **Over-bureaucratization:** an ADR that demands a basis for every constant could ossify into ceremony. Mitigation: the basis statement is one sentence; the trigger is one finding subcode. Anything more is the wrong shape.
+- **Premature parameter exposure:** exposing all 11 limits as operator surface creates a support burden. Mitigation: the ADR allows "internal, no override" as a declared state — the discipline is *declaration*, not necessarily *exposure*.
+- **CI friction on file-LOC budgets:** an aggressive cap on `lib.rs` blocks unrelated PRs. Mitigation: budgets start at current LOC + 10%; ratchet down per release.
+
+## Information Gaps
+
+- WP6's actual status — code comment is the only public reference seen during the from-scratch analysis (the analysis intentionally did not read design docs).
+- Whether `MAX_FILES_PER_PYRIGHT_SESSION=25` has an empirical basis the catalog could not surface.
+- Whether the file-LOC growth on `mcp/lib.rs` and `analyze.rs` is accelerating or has plateaued — no time-series.
+
+## Caveats
+
+The analysis intentionally did **not** consult `docs/clarion/**` or ADRs; if an Accepted ADR already addresses operational tuning discipline, the recommendation collapses to "promote and enforce the existing ADR," not "author a new one." The `breaker.rs:7` WP6 comment strongly suggests an unauthored plan, not an authored-but-unimplemented one, but the from-scratch method cannot confirm.
+
+## Sources
+
+- `04-final-report.md` §1 (operational-subtlety framing), §6.1–6.8 (the High/Medium smells), §8 Q1–Q5 (the five questions verbatim).
+- `02-subsystem-catalog.md` `clarion-core` Concerns ("every limit is a recompile"); `clarion-storage` Concerns (no `application_id`/`user_version`); `clarion-cli` Concerns (`run_with_options` at 570 lines with `#[allow(clippy::too_many_lines)]`); `clarion-mcp` Concerns (4,703-LOC `lib.rs`).
+- Source: `crates/clarion-core/src/plugin/breaker.rs:7` ("WP6"); `crates/clarion-cli/src/analyze.rs:74` (`#[allow(clippy::too_many_lines)]`); `crates/clarion-core/src/lib.rs:1` (crate doc-comment vs. contents).
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-cli.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-cli.md
new file mode 100644
index 00000000..9ba311b0
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-cli.md
@@ -0,0 +1,101 @@
+## 3. clarion-cli
+
+**Location:** `crates/clarion-cli/`
+**LOC:** ~6981 src across 13 `.rs` files (4 of them in `src/secret_scan/`); 5894 LOC tests across 6 integration test files.
+**Crate type / role:** binary crate; produces the `clarion` executable (`[[bin]] name = "clarion"`, `Cargo.toml:12-14`). No `lib.rs`, no inbound Rust callers — this crate is a pure orchestrator that wires `clarion-core`, `clarion-mcp`, `clarion-scanner`, and `clarion-storage` into three subcommands.
+
+### Responsibility
+
+`clarion-cli` owns the operator-facing entry surface: the `clarion` binary, its three subcommands (`install`, `analyze`, `serve`), and all orchestration logic that sits *between* the user invoking the command and the lower-level libraries doing the work. It owns the `.clarion/` filesystem layout (`install.rs:20-100`, `instance.rs:10-86`), the `analyze` pipeline that walks the tree, gates on secrets, fans out to discovered plugins, persists results, and clusters modules into subsystems (`analyze.rs:75-645`), the `serve` supervisor that runs MCP stdio and the Axum HTTP read API as two threads sharing one `ReaderPool` (`serve.rs:20-227`), and the federation HTTP read surface itself (`http_read.rs:363-387` router; `:392-461` bearer + HMAC middleware). The federation-visible `/api/v1/files*` endpoints live in this crate, not in `clarion-mcp` — a noteworthy split.
+
+### Key components
+
+- `src/main.rs:1-78` — binary entry. Three-arm `match` on `cli::Command`; builds a multi-thread tokio runtime *only* for `analyze`. `dotenvy::dotenv()` is loaded for `install`/`serve` but deliberately **skipped for `analyze`** (`main.rs:23-25`) so `.env` contents flow through the secret scanner instead of being imported into plugin subprocess envs. `analyze` exits with `EX_CONFIG=78` on a misconfigured `--allow-unredacted-secrets`.
+- `src/cli.rs:1-63` — clap derive definitions; three subcommands, five `analyze`-time flags.
+- `src/install.rs:109-194` — initialises `.clarion/{clarion.db, config.json, .gitignore}` plus a `clarion.yaml` stub at project root. `populate_after_mkdir` is wrapped in a cleanup guard (`:142-153`) that `rm -rf`s `.clarion/` if any post-mkdir step fails so retry isn't blocked by "already exists".
+- `src/analyze.rs:75-645` — `run_with_options`, the central analyze pipeline. Single async function (~570 LOC) that runs the entire flow described in §"Internal architecture" below.
+- `src/serve.rs:20-227` — `serve::run` + `supervise_stdio_with_http`. Builds the LLM provider (`build_llm_provider:229-291`), opens a 16-conn `ReaderPool`, spawns the HTTP server thread, spawns the MCP stdio thread, then polls the stdio result channel with a 100 ms timeout while periodically checking HTTP health (`:176-202`). On `Arc::ptr_eq` mismatch between the HTTP thread's reported `ReaderPool` identity and the one held in `serve.rs`, `debug_assert!` fires (`:63-71`) — this catches a refactor that re-opens the pool inside `http_read::spawn`.
+- `src/http_read.rs:146-260` — `spawn` / `spawn_with_env`; `:262-311` `run_http_read_server` (binds TCP, sends back ready signal with `ReaderPool` identity captured *after* the move into the runtime thread); `:363-387` `router`; `:392-461` `require_http_identity` + `require_hmac_identity`; `:692-1034` six request handlers (`get_file`, `post_files_batch`, `post_files_resolve`, `get_capabilities`, plus two cfg(test)-only fixtures referenced in `:329-353`).
+- `src/clustering.rs:53-101` — `cluster_modules` entry point + `cluster_modules_with_algorithms` test seam; `:117-145` `leiden_communities` calling `xgraph::graph::algorithms::leiden_clustering`; `:170-224` `local_weighted_components` fallback; `:247-296` directed modularity score; `:103-115` `cluster_hash` = SHA-256 of sorted member IDs truncated to 12 hex chars.
+- `src/secret_scan.rs:202-325` — `pre_ingest`; submodules `anchors.rs` (links scanner detections to plugin-emitted module/file entities), `baseline.rs` (loads `.clarion/secrets-baseline.yaml`), `files.rs` (extension/skip-dir walk + sidecar matcher for `.env`/`.env.*`/`*.env`), `findings.rs` (`PendingFinding` + `FindingRecord` shaping with `CLA-SEC-SECRET-DETECTED` / `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` rule IDs).
+- `src/run_lifecycle.rs:6-44` — two helpers: `recover_preexisting_running_runs` (raw `UPDATE runs SET status='failed' WHERE status='running'` on next start; not routed through the writer-actor because the writer isn't running yet) and `begin_run` (writer `BeginRun` wrapper).
+- `src/instance.rs:44-86` — `InstanceId(Uuid)` newtype persisted to `.clarion/instance_id` with `O_CREAT|O_EXCL` (`mode = 0o600`) → `fsync` → `hard_link` for atomic publish, and `EEXIST`-on-link → read-existing-file race resolution. Federation contract requires a stable per-project ID; this is it.
+
+### Public interface (outbound)
+
+`clarion-cli` exposes no `pub` library API — it has no `lib.rs`. Its public surface is three things:
+
+- **The `clarion` binary CLI** — `clarion install [--force] [--path P]`, `clarion analyze [P] [--config C] [--allow-unredacted-secrets [--confirm-allow-unredacted-secrets TOKEN]] [--allow-no-plugins]`, `clarion serve [--path P] [--config C]` (`cli.rs:13-62`). Confirmation token literal is `"yes-i-understand"` (`secret_scan.rs:38`).
+- **The HTTP read API** — Axum router at `http_read.rs:363-387`. Four production routes (one unprotected):
+  - `GET  /api/v1/files?path=&language=` → `get_file`. Returns `{entity_id, content_hash, canonical_path, language}`; honours `If-None-Match` ETag (= `\"<content_hash>\"`) returning 304. 403 with `BRIEFING_BLOCKED` if entity has `briefing_blocked` property set by secret scan. Protected (bearer or HMAC).
+  - `POST /api/v1/files/batch` body `{queries:[{path,language},…]}` → returns `{resolved[], not_found[], briefing_blocked[], errors[]}`. Hard cap **256** queries/batch (`http_read.rs:608`), runs the whole batch in a single `with_reader` checkout. Protected.
+  - `POST /api/v1/files:resolve` body `{paths:[…]}` → returns `{results:[{path,response:{status,body}}]}` where `status ∈ {resolved,not_found,blocked,error}`. Hard cap **1000** paths (`http_read.rs:609`). Protected.
+  - `GET  /api/v1/_capabilities` → `{registry_backend, file_registry, api_version, instance_id}`. **Unprotected by design** so siblings can probe pre-auth.
+  - Body cap **16 KiB** (`HTTP_BODY_LIMIT_BYTES`, `http_read.rs:610`). Tower stack (`:373-386`): `CatchPanicLayer` (panics → 500 envelope) → `HandleErrorLayer` (panics on unenumerated middleware errors; `:547-556`) → `TraceLayer` → 10 s `TimeoutLayer` → `RequestBodyLimitLayer` → `LoadShedLayer` → `ConcurrencyLimitLayer(64)`. Errors carry an envelope `{error, code}` with `code ∈ {INVALID_PATH, PATH_OUTSIDE_PROJECT, NOT_FOUND, BRIEFING_BLOCKED, UNAUTHENTICATED, STORAGE_ERROR, BATCH_TOO_LARGE, INTERNAL}` (`http_read.rs:590-601`).
+- **`clarion serve`'s stdio MCP server** — owned by `clarion-mcp`. `clarion-cli` calls `clarion_mcp::serve_stdio_with_state_on_runtime` (`serve.rs:150`) and constructs the `ServerState` with the reader pool, optional summary-LLM writer + `LlmProvider`, and optional `FiligreeHttpClient` (`serve.rs:131-147`).
+
+### Dependencies
+
+- **Inbound (who calls this):** No Rust callers — verified by `grep -rn "clarion_cli" crates/` returning empty. This crate is invoked by humans/CI through the `clarion` binary and by `tests/e2e/*.sh` shell scripts.
+- **Outbound (other Clarion crates):** `clarion-core` (`AcceptedEntity`/`AcceptedEdge`, `discover`, `PluginHost`, `CrashLoopBreaker`, `BriefingBlockReason`, `HostError`, `HostFinding`, LLM provider types), `clarion-mcp` (`ServerState`, `config::McpConfig`, `config::HttpReadConfig`, `filigree::FiligreeHttpClient`, `serve_stdio_with_state_on_runtime`, `select_provider_with_env`, `resolve_filigree_http_target`), `clarion-storage` (`Writer`, `WriterCmd`, `ReaderPool`, `module_dependency_edges`, `resolve_file_catalog_entry`, `CanonicalProjectPath`, `StorageError`, `pragma`, `schema`), `clarion-scanner` (`Scanner`, `Detection`, `Baseline`, `SuppressionResult`).
+- **External crates of note:** `axum` 0.7 (HTTP), `tower`/`tower-http` (middleware), `tokio` (runtimes — multi-thread for analyze + HTTP, current-thread for MCP stdio), `clap` (CLI), `xgraph` (Leiden clustering), `ignore::WalkBuilder` (`.gitignore`-honouring tree walk in both `analyze.rs:2016-2026` and `secret_scan/files.rs`), `rusqlite` (one direct `Connection::open` in `analyze.rs:711` to read module IDs/edges during phase 3, bypassing the reader pool), `uuid`, `dotenvy`, `sha2` (HMAC, `cluster_hash`).
+- **External services / processes:**
+  - **SQLite** at `<project>/.clarion/clarion.db`, opened both via `ReaderPool::open` (`serve.rs:53`) and direct `Connection::open` (`run_lifecycle.rs:10`, `analyze.rs:711`, `install.rs:189`).
+  - **Plugin subprocesses** — spawned via `clarion_core::PluginHost::spawn` from `run_plugin_blocking` (`analyze.rs:1322`) on `tokio::task::spawn_blocking` workers.
+  - **TCP listener** for HTTP read API on `config.serve.http.bind` (default `127.0.0.1:9111` per `install.rs:74`); bound by `tokio::net::TcpListener::bind` inside the HTTP thread's runtime (`http_read.rs:279`).
+  - **LLM CLIs and OpenRouter** — wired via `build_llm_provider` (`serve.rs:229-291`); reaches `codex`/`claude` binaries and OpenRouter HTTPS.
+
+### Internal architecture
+
+**Three subcommands, three concurrency shapes.** `install` is fully synchronous (`install.rs:109`). `analyze` builds a multi-thread tokio runtime in `main.rs:36-38` and runs one big `async fn run_with_options` (`analyze.rs:75-645`); per-plugin work happens inside `tokio::task::spawn_blocking` (`analyze.rs:325-339`) using a **Pattern A buffering** strategy named in the module doc (`analyze.rs:6-8`): collect all entities + edges into in-memory `Vec`s inside the blocking task, return them to the async side, then drain into the writer-actor via `WriterCmd::InsertEntity`/`InsertEdge` one-at-a-time with `send_wait` ack-and-block (`analyze.rs:399-447`). `serve` is the most complex (`serve.rs`): a foreground supervisor thread (the process's original thread) polls a `std::sync::mpsc::Receiver` from the spawned `"clarion-mcp-stdio"` thread (current-thread tokio runtime, `:126-130`) while also `check_running`-polling the `"clarion-http-read"` thread (multi-thread tokio runtime, `http_read.rs:355-360`). Identity of the single shared `ReaderPool` is asserted by `Arc::ptr_eq` on the inner `Arc<()>` tag (`serve.rs:63-71`); the HTTP thread captures its identity **after** the pool has been moved into its runtime (`http_read.rs:272-296`), so a refactor that opened a fresh pool inside the HTTP thread would surface immediately rather than silently double-opening WAL.
+
+**Analyze pipeline ordering (`analyze.rs:75-645`, single function):**
+1. Path canonicalisation + `.clarion/` existence check (`:82-91`).
+2. Load `clarion.yaml`-derived `AnalyzeConfig` (clustering knobs only; LLM/serve config is `serve`-only) — `config.rs:16-29`.
+3. **Run-row crash recovery** — `recover_preexisting_running_runs` flips any prior `status='running'` rows to `failed` (`:95-102`, `run_lifecycle.rs:6-26`).
+4. **Spawn writer-actor** + mint run_id (`:105-113`).
+5. **Plugin discovery** — `clarion_core::discover()` scans `$PATH` for `clarion-plugin-*` (`:116-135`). Empty-with-errors → FailRun + non-zero exit (`:142-174`); empty-without-errors → `RunStatus::SkippedNoPlugins` + non-zero exit unless `--allow-no-plugins` (`:176-223`).
+6. **Build the wanted-extensions union** across plugin manifests (`:226-231`).
+7. **Walk the tree** — `collect_source_files` with `ignore::WalkBuilder` honouring `.gitignore` family + a hard-coded skip-dir list (`:234`, `:2013-2065`).
+8. **Pre-ingest secret scan** — `secret_scan::collect_scan_files` (broader walk that includes `.env` sidecars) → `secret_scan::pre_ingest` runs `clarion-scanner` patterns in **parallel via `thread::scope` with `available_parallelism()` workers** (`secret_scan.rs:333-382`), applies the baseline, classifies each file as `Clean`/`Blocked`/`Overridden` (`:237-243`). **The scan happens before `BeginRun` and before any plugin spawn**, so plugin processes never receive `.env` contents in their analyze stream — they receive `briefing_blocked` flags instead.
+9. **`BeginRun`** (`:244`).
+10. **Per-plugin loop** (`:275-470`): filter source files to the plugin's extensions; `spawn_blocking` `run_plugin_blocking` (`analyze.rs:1309-1456`) which (a) calls `PluginHost::spawn` for the JSON-RPC handshake, (b) iterates files calling `host.analyze_file()` with periodic heartbeat logging (`:1272-1307`), (c) collects entities + edges + unresolved-call-sites + per-file stats, (d) issues `host.shutdown()` on success or `child.kill()` on error, (e) reaps the child and classifies SIGKILL/SIGSEGV as likely `RLIMIT_AS` OOM-finding (`:1466-1574`). Per-plugin crashes record on a `CrashLoopBreaker`; >3 crashes / 60 s trips the breaker, drops the remaining plugins, and surfaces `FINDING_DISABLED_CRASH_LOOP` (`:271-272, 349-358`).
+11. **Entity → edge ingestion** for surviving plugins, in order: `InsertEntity` for collected entities, `ReplaceUnresolvedCallSitesForCaller` for query-time-resolvable call sites, then `InsertEdge` (`:399-448`). Order is load-bearing: edges FK-reference entities (`:392-394` comment).
+12. **`persist_findings`** writes the secret-scan findings now that we have anchor entity IDs from plugin output (`:471-481`, `secret_scan/anchors.rs`).
+13. **Phase 3 clustering** (`:500-520`, `run_phase3_clustering` at `:675-906`): `FlushRunBatch`, open a direct read connection, load module entity IDs + module-dependency edges, build `ModuleGraph`, run `cluster_modules`, emit one `core:subsystem:<cluster_hash>` entity + N `in_subsystem` edges per community, emit a `CLA-FACT-CLUSTERING-WEAK-MODULARITY` finding if `modularity_score < weak_modularity_threshold` (default 0.3).
+14. **`CommitRun(Completed)`** / **`CommitRun(Failed)` for soft-fail (some plugins crashed but writer-actor was healthy)** / **`FailRun` for hard-fail (writer-actor rejection or phase 3 error)** (`:543-625`). The hard/soft distinction matters: SoftFailed commits the partial entity batch *and* marks the run failed atomically (`:576-612`); HardFailed rolls back the open transaction via `FailRun`.
+
+**Clustering (`clustering.rs`):** Two algorithms, both deterministic. Leiden via `xgraph::graph::algorithms::leiden_clustering::CommunityDetection::detect_communities_with_config` with `{gamma, resolution, iterations, deterministic: true, seed}` (`:124-131`). If Leiden returns ≤1 community, fall back to a hand-rolled `local_weighted_components` (`:170-224`) keyed on average-positive-edge-weight as the threshold; the algorithm actually used is reported back in `ClusterResult.algorithm_used`. Directed modularity is recomputed locally on the resulting partition (`:247-296`) — `xgraph` returns communities, not the score. `cluster_hash` (`:103-115`) is SHA-256 of sorted member entity IDs truncated to 12 hex chars; this seeds the `core:subsystem:<hash>` entity ID so the same community shape is byte-stable across runs.
+
+**HTTP read API (`http_read.rs`):** Single `Router` built once at `spawn`. Two-layer auth: the **HMAC path is preferred** when `identity_token_env` is set (`:397-398`), falling back to **bearer** when only `token_env` is set, falling back to **trust-loopback** (`auth = "none"`) when neither is set — with an operator-visible WARN at spawn time (`:244-252`). HMAC canonical message is `"{method}\n{path_and_query}\n{hex(sha256(body))}"` (`:478-484`), HMAC is SHA-256 hand-rolled (`:487-509`) — no `hmac` crate dependency. Constant-time compare on both bearer and HMAC paths (`:415, 456, 521-530`). Two failure modes get explicit non-500 statuses: timeout → 408 (`:533-538`), load-shed → 503 (`:540-546`); anything else from `BoxError` is a `panic!()` with the error chain in the message (`:553-556`) — `CatchPanicLayer` turns it into a 500 envelope, but CI sees the missing enumeration.
+
+**Error model:** `anyhow::Result` everywhere at the binary layer (`main.rs:13`, `serve.rs:8`); typed `StorageError` from `clarion-storage` is classified into HTTP `ErrorCode` enum + status by `classify_read_error` (`http_read.rs:1050-1085`).
+
+### Patterns observed
+
+- **Supervisor + worker threads with shared `Arc<()>` identity tag** (`serve.rs:63-71`, `http_read.rs:141-144, 272-296`) — prevents silent double-open of the WAL pool across the refactor surface.
+- **Pattern A buffering** for plugin output: collect-in-blocking-task, send-from-async-task (`analyze.rs:325-339, 399-448`) — keeps the writer-actor single-threaded discipline while letting blocking JSON-RPC reads happen on `spawn_blocking`.
+- **Atomic file publish via hard-link rename** for `instance_id` (`instance.rs:53-86`) — handles racing concurrent installs without an external lock.
+- **Crash-loop breaker as an in-process circuit** (`analyze.rs:271-272, 349-358`) — borrowed from `clarion_core::CrashLoopBreaker`, applied per-run.
+- **Two-pass HTTP body read** in the HMAC path: `to_bytes` to compute the digest, then reconstruct `Request::from_parts(parts, Body::from(body_bytes))` so the handler still sees a normal body (`http_read.rs:442-461`). Necessary because HMAC needs the full bytes, not a stream.
+- **Constant-time secret comparison** on both bearer and HMAC paths (`http_read.rs:521-530`) — defends against timing attacks even on the loopback default.
+- **Test seam via function-pointer injection**: `cluster_modules_with_algorithms` takes the Leiden and weighted-components closures as parameters (`clustering.rs:60-65`); tests substitute hand-rolled communities to force the fallback path (`:457-482`).
+- **`#[cfg(test)]` panic injection** for supervisor testing: `HTTP_THREAD_PANIC_TRIGGER` static atomic that a test can flip to assert the supervisor's runtime-panic arm still fires after `CatchPanicLayer` was introduced (`http_read.rs:321-353`). A rare and disciplined use of cfg-conditional production code.
+- **Run-lifecycle crash recovery before writer-actor spawn** (`run_lifecycle.rs:6-26`, `analyze.rs:95-102`) — raw `rusqlite` `UPDATE` because the writer can't recover its own pre-mortem state.
+
+### Concerns / Smells / Risks
+
+- **`analyze.rs` is 2549 LOC in a single file**, and `run_with_options` itself spans 570 lines (lines 75–645) with `#[allow(clippy::too_many_lines)]` (`:74`). The function is doing path setup, run lifecycle, discovery error policy, no-plugin policy, tree walk, secret scan, per-plugin orchestration, ingestion ordering, soft/hard-fail promotion, phase 3 clustering invocation, and run finalisation — every one of those is a separate change vector. The module doc and inline comments are excellent (some of the most carefully reasoned `//` comments in the workspace), but extracting `discovery_outcome`, `per_plugin_loop`, and `finalise_run` into named functions would materially reduce the surface that has to be re-read on each touch. Watch this file for change-amplification scars over time.
+- **`http_read.rs` is 1723 LOC with all routes, all auth, both error envelopes, and the test-only panic harness in one module**. The separation between protected and unprotected sub-routers is already in place (`:363-372`) — a future refactor could lift each handler family into a sibling module (`files.rs`, `batch.rs`, `resolve.rs`) without changing the router shape.
+- **Two parallel `WalkBuilder` traversals** of the project tree: one in `analyze::collect_source_files` (`analyze.rs:2013`, extension-filtered) and a broader one in `secret_scan::collect_scan_files` (sidecars + same extensions). Both honour `.gitignore`. On a large repo this is two full I/O passes back-to-back; no caching between them.
+- **Phase 3 clustering opens a raw `rusqlite::Connection` bypassing the writer-actor's view of the WAL** (`analyze.rs:711`). The `FlushRunBatch` call at `:705-709` is what makes this safe — the writer-actor must drain its open transaction so the direct connection sees the same module rows. The dependency between `FlushRunBatch` and the subsequent direct read is implicit; a refactor that removes the flush would silently produce empty clusters on a busy run.
+- **HMAC implementation is hand-rolled** (`http_read.rs:487-509`) rather than using the `hmac` + `sha2` crates' `Hmac<Sha256>` type. The code is short and the `constant_time_eq` is paired with it correctly, but a deps-level choice not to pull `hmac` is a maintenance bet — any future HMAC variant (rotation, key derivation) reopens this. Worth tracking.
+- **Unenumerated middleware error → panic → 500 envelope** (`http_read.rs:553-556`). The design intent is sound (force enumeration via CI failure rather than silently swallow), but in production the user sees a 500 with a vague message; the panic message goes to stderr only. The behaviour is deliberate per the inline comment, but it deserves a runbook entry.
+- **`run_with_options` does not bound the in-memory entity buffer**: `collected_entities` and `collected_edges` for a plugin run accumulate every entity for every file in `Vec`s before any are flushed to the writer-actor (`analyze.rs:1337-1419`). On a very large corpus a misbehaving plugin could exceed memory limits before the entity-cap breaker in `clarion-core` trips. The cap exists but lives in the host, not here.
+- **`scanned_files: Arc<BTreeSet<PathBuf>>` is constructed by the secret scan and then shared into every `PluginHost`** so the host can enforce the briefing-block contract on per-file results (`analyze.rs:273-274, 314-315, 333-334`). This is a clean immutable share, but it does mean every plugin process holds (via the host wrapper) a reference to a `BTreeSet` whose footprint scales with the project source count.
+- **No test coverage for the supervisor's "stdio thread exited but result_rx was disconnected" branch** at `serve.rs:194-200` was visible in my sampling pass — only a unit test for `finish_supervised_result` (`:313-325`) and the e2e shell scripts exercise serve. The `tests/serve.rs` file is 3075 LOC, so this is probably covered; flagged for explicit verification.
+- **`recover_preexisting_running_runs` swallows error context one level** by going through `anyhow!("{err}")` (`run_lifecycle.rs:12-14`) — typed `StorageError` info is folded into a plain string. Mild.
+
+### Confidence: High
+
+Read every source file in `src/` end-to-end except `analyze.rs`, where I read the module doc, all top-level fn signatures, `run_with_options` lines 75-645 in full, `run_phase3_clustering` lines 675-906, `run_plugin_blocking` lines 1309-1456, the source walk lines 2013-2065, and the time helper. Read `http_read.rs` lines 1-260 (transport / spawn / supervisor identity), 260-461 (server bootstrap + auth + HMAC), 692-1034 (handlers + capabilities), 1036-1085 (error classifier), 1107-1148 (logging + panic envelope). Read all four `secret_scan/` submodule heads. Listed inbound callers (`grep -rn "clarion_cli"`) and confirmed none — this is a leaf binary. Did **not** read the test files end-to-end (5894 LOC), only their line counts and the cfg(test) harness inside `http_read.rs` and `clustering.rs`. The 20 MCP tool surface and `clarion-mcp::ServerState` shape are cited only via the call sites at `serve.rs:131-147, 150`, not by reading `clarion-mcp`.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-core.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-core.md
new file mode 100644
index 00000000..4d79a400
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-core.md
@@ -0,0 +1,91 @@
+## 1. clarion-core
+
+**Location:** `crates/clarion-core/`
+**LOC:** 11,653 source / 325 integration test (plus extensive inline `#[cfg(test)]` blocks; see Concerns)
+**Crate type / role:** Rust library (`lib.rs`). No binary. Re-exported as a facade by `lib.rs:13-49`; implementation modules remain reachable through `clarion_core::plugin::*` per the explicit policy comment at `lib.rs:5-7`.
+
+### Responsibility
+
+`clarion-core` owns three orthogonal concerns bundled into one crate: (1) the canonical **entity-ID assembler** (`entity_id.rs`), which is the single source of truth for the `{plugin_id}:{kind}:{canonical_qualified_name}` identifier shape and the ADR-022 identifier grammar; (2) the **plugin host runtime** (`plugin/`), a synchronous JSON-RPC supervisor that discovers, spawns, validates, and reaps language-plugin subprocesses while enforcing four core minimums (path jail, content-length ceiling, run-cumulative entity cap, virtual-address limit); and (3) the **LLM provider abstraction** (`llm_provider.rs`), a `Send + Sync` trait plus four concrete adapters (recording fixture, OpenRouter HTTP, Claude CLI subprocess, Codex CLI subprocess) for query-time enrichment. The public surface that proves the boundary is the `pub use` block in `lib.rs:13-49`, which is the only API surface other workspace crates are *supposed* to consume (the policy comment is explicit; one violation exists — see Concerns).
+
+### Key components
+
+- `src/entity_id.rs:90-148` — `entity_id(plugin_id, kind, canonical_qualified_name) -> Result<EntityId, EntityIdError>` plus a shared `validate_kind_grammar` helper used by both this module and `manifest.rs`. ~150 LOC of code; ~450 LOC of byte-for-byte cross-language parity tests against `fixtures/entity_id.json` covering entities + `contains`/`calls`/`references` edge wire shapes (`entity_id.rs:371-587`).
+- `src/plugin/manifest.rs:1-1119` — TOML parser for `plugin.toml`, ADR-022 reserved-kind / reserved-rule-prefix gating, `Manifest::validate_for_v0_1()` capability check (run at handshake). Defines `RESERVED_ENTITY_KINDS = ["file", "subsystem", "guidance"]` at line 28.
+- `src/plugin/transport.rs:1-569` — LSP-style `Content-Length:`-framed JSON transport. Synchronous `read_frame(reader, ceiling) -> Result<Frame, TransportError>` / `write_frame(writer, frame)`. Header-line cap at 8 KiB (`MAX_HEADER_LINE_BYTES`), body cap from caller-supplied `ContentLengthCeiling` (default 8 MiB).
+- `src/plugin/protocol.rs:312-474` — Typed JSON-RPC 2.0 envelopes and the five method bodies: `initialize` (core→plugin), `initialized` (notification), `analyze_file` (request), `shutdown` (request), `exit` (notification). Struct-per-method discriminated by `IncomingMessage::method` (`protocol.rs:3-22` doc). `JsonRpcVersion` newtype hard-pins the literal `"2.0"`.
+- `src/plugin/jail.rs:73-103` — `jail(root, candidate)` and `jail_to_string(root, candidate)`. Both paths canonicalise via `std::fs::canonicalize` (follows symlinks per UQ-WP2-03 comment), assert `starts_with(canonical_root)`, and surface `JailError::EscapedRoot` / `Io` / `NonUtf8Path`.
+- `src/plugin/limits.rs:1-572` — `ContentLengthCeiling` (8 MiB default), `EntityCountCap` (run-cumulative; default 500k via `EntityCountCap::DEFAULT_MAX`), `PathEscapeBreaker` (per-plugin; >10 escapes in 60 s trips), `apply_prlimit_as` / `apply_prlimit_nofile_nproc` (Linux-only `setrlimit` wrappers; async-signal-safe for `pre_exec`). Co-locates the seven `CLA-INFRA-PLUGIN-*` finding subcode constants.
+- `src/plugin/breaker.rs:43-117` — `CrashLoopBreaker`: rolling-window crash counter (default 60 s window, >3 threshold per UQ-WP2-10). Trips → `FINDING_DISABLED_CRASH_LOOP` and refusal of further spawns. *Caller-driven* — `PluginHost` does not own this; the run loop in `clarion-cli/analyze.rs:271` does.
+- `src/plugin/discovery.rs:1-667` — `discover()` / `discover_on_path()` scan `$PATH` for `clarion-plugin-<suffix>` executables, locate the neighbouring `plugin.toml` (with a pipx-aware symlink-resolved install-prefix fallback documented at lines 13-33), and return `Vec<Result<DiscoveredPlugin, DiscoveryError>>`.
+- `src/plugin/host.rs:384-1182` — `PluginHost<R: BufRead, W: Write>`: the supervisor. Generic over reader/writer so the in-process `mock.rs` (876 LOC, `#[cfg(test)] pub(crate)`) can drive it without a subprocess. Public methods: `spawn` (subprocess constructor; lines 505-644), `connect` (in-process; 658-666), `handshake` (743-803), `analyze_file` (815-985), `shutdown` (1106-1111), plus accessors `stderr_tail`, `ontology_version`, `take_findings`, `set_briefing_blocks`, `set_scanned_source_files`. The four-stage per-entity validation pipeline (ontology → identity → jail → cap) lives inline in `analyze_file` at lines 866-975.
+- `src/plugin/host_findings.rs:1-273` — `HostFinding` struct + ten `CLA-INFRA-PLUGIN-*` / `CLA-INFRA-HOST-*` / `CLA-INFRA-MANIFEST-*` subcode constants and constructor functions (`unsupported_capability`, `entity_id_mismatch`, `path_escape`, `malformed_entity`, `malformed_edge`, …).
+- `src/llm_provider.rs:101-2467` — `trait LlmProvider: Send + Sync` plus `RecordingProvider`, `OpenRouterProvider` (live `reqwest` HTTP), `CodexCliProvider` and `ClaudeCliProvider` (subprocess CLI wrappers with bounded stdout/stderr ring buffers and timeout via background reaper thread). Also hosts the prompt-template builders `build_leaf_summary_prompt`, `build_inferred_calls_prompt`, `build_coding_agent_provider_prompt` and version constants.
+
+### Public interface (outbound)
+
+The crate-root `pub use` facade (`lib.rs:13-49`) re-exports exactly these names; everything else is reachable through `clarion_core::plugin::{module}::*` per the explicit policy at `lib.rs:5-7`:
+
+- **Entity-ID assembler:** `EntityId`, `EntityIdError`, `entity_id()` — assemble or parse a 3-segment ID. `EntityId` is opaque (the only constructor is `entity_id()` / `FromStr::from_str` / `Deserialize`); `as_str()` returns the canonical form.
+- **Plugin discovery:** `DiscoveredPlugin`, `DiscoveryError`, `discover()` — scan `$PATH` for `clarion-plugin-*` binaries.
+- **Plugin manifest:** `Manifest`, `ManifestError`, `parse_manifest()` — TOML parse + ADR-022 grammar / reserved-kind / reserved-rule-prefix checks. Plus `Manifest::validate_for_v0_1()` capability gate, exercised by the host at handshake.
+- **Plugin host:** `PluginHost`, `HostError`, `HostFinding`, `AcceptedEntity`, `AcceptedEdge`, `AnalyzeFileOutcome`, `AnalyzeFileStats`, `UnresolvedCallSite`, `BriefingBlockReason`, `EdgeConfidence`.
+- **Resource limits:** `JailError`, `CapExceeded`, plus the `FINDING_DISABLED_CRASH_LOOP` constant (re-exported from `breaker`).
+- **Crash-loop breaker:** `CrashLoopBreaker`, `CrashLoopState` — caller-driven, used by the analyze run loop, not by `PluginHost` itself.
+- **LLM providers:** `LlmProvider` trait + `LlmRequest`, `LlmResponse`, `LlmPurpose`, `LlmProviderError`, `CachingModel`, `Recording`, `RecordingProvider`, `OpenRouterProvider(+Config)`, `ClaudeCliProvider(+Config)`, `CodexCliProvider(+Config)`, `PromptTemplate`, the three `build_*_prompt` functions, and the version constants `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `INFERRED_CALLS_PROMPT_VERSION`.
+
+**JSON-RPC method set (the wire surface `PluginHost` drives, not Rust API):** `initialize` (request; `InitializeParams { protocol_version, project_root }` → `InitializeResult { name, version, ontology_version, capabilities }`); `initialized` (notification, empty params); `analyze_file` (request; `{ file_path }` → `{ entities: Vec<Value>, edges: Vec<Value>, stats: AnalyzeFileStats }` — per-element typing happens in `host::analyze_file` so a single malformed entity drops with a finding rather than failing the response); `shutdown` (request, empty); `exit` (notification, empty). `protocol.rs:3-22` and `protocol.rs:312-474`.
+
+### Dependencies
+
+- **Inbound (who calls this):**
+  - `crates/clarion-cli/src/analyze.rs` — the principal consumer. Uses `discover`, `parse_manifest`, `PluginHost::spawn`, `CrashLoopBreaker` (driven by the run loop, not the host), `AcceptedEntity`/`AcceptedEdge`/`AnalyzeFileOutcome`, `HostFinding`, `BriefingBlockReason`, `EdgeConfidence`, plus the `entity_id::entity_id` direct call for `core:file:*` and `core:subsystem:*` IDs (lines 909, 1683).
+  - `crates/clarion-cli/src/serve.rs`, `secret_scan.rs` — `BriefingBlockReason` and the LLM-provider types.
+  - `crates/clarion-storage/src/{commands,query,writer}.rs` — `EdgeConfidence` (re-exported from `commands.rs`), and one deep reach across the facade: `writer.rs:427` reads `clarion_core::plugin::manifest::RESERVED_ENTITY_KINDS` directly (not through the crate-root facade).
+  - `crates/clarion-mcp/src/lib.rs`, `clarion-plugin-fixture/src/main.rs`, and several integration tests (`clarion-cli/tests/wp2_e2e.rs`, `clarion-mcp/tests/storage_tools.rs`, etc.).
+- **Outbound (what this calls):** Standard library only for the host + entity-ID layers (`std::process::Command`, `std::io::{BufRead,Write}`, `std::fs::canonicalize`, `std::thread`, `std::sync::{Arc,Mutex}`). External crates: `serde`/`serde_json` (wire), `thiserror` (errors), `toml` (manifest), `tracing` (logging), `nix` (Linux `setrlimit` via `apply_prlimit_*` in `limits.rs`), `which` (transitive via `discovery`), `reqwest` (live `OpenRouterProvider` HTTP), `tempfile` (test-only).
+- **External services:** Plugin subprocesses (spawned by `PluginHost::spawn`, communicated to via stdin/stdout pipes; stderr piped + drained on a detached thread into a 64 KiB ring buffer at `host.rs:447-476`). Optional outbound HTTP to OpenRouter (`llm_provider.rs::OpenRouterProvider`). Optional `claude` / `codex` CLI subprocesses (`ClaudeCliProvider`, `CodexCliProvider`).
+
+### Internal architecture
+
+**Concurrency model: synchronous over `BufRead`/`Write`.** `PluginHost<R, W>` (`host.rs:384`) is generic over a reader and writer so unit tests drive it in-process via `connect()` while production code uses `spawn()` which wires `std::io::BufReader<ChildStdout>` and `std::io::BufWriter<ChildStdin>`. All RPC is request-response on the same thread that called `analyze_file`; there is no async, no task system, no message channel inside the host. The *only* concurrency is one detached `std::thread` per host (`host.rs:614-620`, named `clarion-plugin-stderr-drain:<plugin_id>`) that reads `ChildStderr` in 4 KiB chunks into a bounded `VecDeque<u8>` of capacity `STDERR_TAIL_BYTES = 64 KiB`, popping front on overflow. Rationale at `host.rs:550-561`: an inherited stderr could (a) flood the operator's terminal with hostile bytes or (b) deadlock the plugin on `write(2)` when the host is blocked in `analyze_file`. The ring is read back via `stderr_tail() -> Option<String>` using lossy-UTF-8 conversion. `PluginHost::spawn` returns `(Self, std::process::Child)` — the *caller* owns reaping; `Child::Drop` does not `waitpid` on Unix (`host.rs:630-641`), so a handshake failure inside `spawn` reaps the child before returning the error.
+
+**Enforcement pipeline (the load-bearing per-entity loop, `host.rs:866-975`).** For each `RawEntity` deserialised from `AnalyzeFileResult.entities`: (0) field-size check against `MAX_ENTITY_FIELD_BYTES = 4 KiB` for `id`/`kind`/`qualified_name`/`source.file_path` and `MAX_ENTITY_EXTRA_BYTES = 64 KiB` for the two `#[serde(flatten)]` passthrough maps; (1) ontology check — `kind` must be in `manifest.ontology.entity_kinds` (ADR-022); (2) identity check — recomputed `entity_id(plugin_id, kind, qualified_name)` must equal the wire `id` (UQ-WP2-11 — prevents a plugin from minting IDs outside its declared namespace); (3) jail check — `jail_to_string(project_root, source.file_path)` must succeed; on failure, tick the per-host `PathEscapeBreaker`; (4) entity cap — `EntityCountCap::try_admit(1)`. Steps 0–2 drop the entity with a finding and continue. Step 3 drops the entity + records a finding; if the breaker trips (>10 escapes / 60 s) it shuts down the plugin and returns `HostError::PathEscapeBreakerTripped`. Step 4 on overflow shuts down the plugin and returns `HostError::EntityCapExceeded`. Edges go through a parallel but kill-free pipeline (`process_edges`, lines 1017-1060) — edges do not participate in the path-escape breaker or the entity cap.
+
+**Failure-mode policy (four distinct mechanisms, three layers).** The system layers failure detection:
+1. **Per-frame ceiling** — `ContentLengthCeiling::DEFAULT = 8 MiB`. `read_frame` rejects with `TransportError::FrameTooLarge` *before* consuming the body bytes (`transport.rs:67-71`).
+2. **Per-host path-escape breaker** — `PathEscapeBreaker` (`limits.rs`), rolling-window >10 escapes / 60 s. Owned by `PluginHost`. Trip → kill plugin.
+3. **Per-run entity-count cap** — `EntityCountCap`, default 500,000 entities cumulative across all `analyze_file` calls on this host. Exceeded → kill plugin.
+4. **Per-run crash-loop breaker** — `CrashLoopBreaker` (`breaker.rs`), rolling-window >3 spawn/handshake/analyze crashes / 60 s. *Not* owned by `PluginHost`; the analyze run loop in `clarion-cli/analyze.rs:271` constructs and ticks it. Trip → emit `FINDING_DISABLED_CRASH_LOOP`, refuse further spawns this run.
+
+The two breakers are conceptually different scopes — one polices a single misbehaving plugin's emissions, the other polices the *fleet* of plugins across one run.
+
+**State ownership inside `PluginHost`** (`host.rs:384-422`): `manifest` (immutable), `project_root` (canonicalised once at construction), `reader`/`writer` (the wire endpoints), `ceiling`/`entity_cap`/`path_breaker` (the three host-resident enforcement gates), `next_request_id` (monotone i64 — the JSON-RPC `id` allocator), `findings: Vec<HostFinding>` (accumulated; drained via `take_findings()`), `terminated: bool` (idempotency guard so a double `shutdown()` does not write to a closed pipe), `ontology_version: Option<String>` (set at handshake for ADR-007 cache keying by WP6), `stderr_tail: Option<Arc<Mutex<VecDeque<u8>>>>` (the ring buffer; `None` for in-process `connect()`), and two read-only `Arc`-shared inputs the analyze run loop installs: `briefing_blocks: Arc<BTreeMap<PathBuf, BriefingBlockReason>>` and `scanned_source_files: Arc<BTreeSet<PathBuf>>` that drive `apply_briefing_block` (lines 987-1004) to attach `briefing_blocked` markers to entities whose source file failed secret scan or was unscanned.
+
+**Error model.** `HostError` (`host.rs:334-370`) wraps `TransportError`, `ProtocolError`, `ManifestError`, `CapExceeded`, `EntityIdError`, `serde_json::Error`, `std::io::Error`, plus three policy variants (`PathEscapeBreakerTripped`, `EntityCapExceeded(CapExceeded)`, `Spawn(String)`). Every module exposes its own `thiserror`-derived enum (`TransportError`, `ManifestError`, `JailError`, `DiscoveryError`, `EntityIdError`, `LlmProviderError`); the host composes them via `#[from]`. The asymmetry between "drop-entity, no kill" (steps 0–2 of the pipeline + most ontology/identity violations) and "kill plugin" (path-escape breaker trip, entity-cap overflow, manifest capability refusal) is the central policy expression.
+
+### Patterns observed
+
+- **Drop-with-finding vs. kill-with-error asymmetry** — `host.rs:866-975`. Two-tier sanction system mediated by `HostFinding` accumulation versus `Result::Err(HostError::*)` propagation.
+- **Generic-over-IO supervisor with in-process mock** — `PluginHost<R: BufRead, W: Write>` (`host.rs:384`) + `mock.rs` (876 LOC, `pub(crate) #[cfg(test)]`). Lets the host's entire pipeline be tested without spawning a subprocess; `connect()` constructor (line 658) is the seam.
+- **Per-frame size ceiling with no-body-consume rejection** — `transport.rs:67-71` returns `FrameTooLarge` before touching the body, so a hostile frame cannot exhaust memory in `read_to_end`.
+- **Newtype wrappers as wire pins** — `JsonRpcVersion` (`protocol.rs:72-95`) serialises/deserialises strictly to `"2.0"`; `EntityId` is constructible only via `entity_id()` / `FromStr::from_str` / custom `Deserialize` (`entity_id.rs:19-60`) so deserialising an arbitrary string at a `serde(flatten)` boundary cannot smuggle in a malformed id.
+- **`pre_exec` resource-limit application** — `host.rs:569-586`. Closure runs in the forked child, calls only async-signal-safe `setrlimit(2)`, with a safety comment documenting the POSIX.1-2017 §2.4.3 reference. `RLIMIT_AS` from manifest hint or `DEFAULT_MAX_RSS_MIB`; `RLIMIT_NPROC` bumped to 4096 when `manifest.capabilities.runtime.pyright = Some(_)` (line 89, 577) because Pyright's Node-based LSP spawns helpers checked against the user's process count, not just children.
+- **Cross-language byte-for-byte fixture parity** — `entity_id.rs:371-587` consumes `../../fixtures/entity_id.json` (the same file the Python plugin's `test_entity_id.py` consumes) and asserts identical assembly results for entities and the three edge wire shapes.
+- **Caller-driven breaker, host-driven breaker** — symmetric naming hides asymmetric ownership. `CrashLoopBreaker` is *given* to the caller (it sits in `analyze.rs`'s plugin loop); `PathEscapeBreaker` lives inside the host. Same shape, different scope.
+- **Idempotent shutdown via terminated flag** — `host.rs:1106-1111` and `do_shutdown` at 1158. The flag is set *before* the shutdown exchange runs (line 1164) so even a mid-exchange pipe break does not surface a spurious `BrokenPipe` on a defensive double-`shutdown()`.
+
+### Concerns / Smells / Risks
+
+- **`host.rs` at 2,935 LOC is the largest single file in the crate and (per the discovery doc) one of the four largest in the workspace.** The four-stage validation pipeline, edge processing, stats post-processing, briefing-block reconciliation, the subprocess constructor with its stderr drainer, and the in-process generic methods all live in one `impl PluginHost<R: BufRead, W: Write>` block. The module would split cleanly along the pipeline-step / lifecycle / IO axes; the current shape makes the per-step contracts harder to test in isolation than the generics already permit.
+- **`llm_provider.rs` at 2,467 LOC is in this crate at all.** The `lib.rs` doc-comment (`lib.rs:1`) calls this crate "domain types, identifiers, and provider traits" — but the module bundles concrete `reqwest`-based OpenRouter HTTP, two distinct subprocess-CLI provider implementations (Claude, Codex) each with their own timeout / ring-buffer / reaper-thread machinery, and the prompt-template builders. Three orthogonal subsystems (the trait, the HTTP transport, the CLI transports, the prompt assembly) compressed into one file in a crate that otherwise is about plugin hosting. A future `clarion-llm` crate split would tighten the `clarion-core` boundary considerably; today, `reqwest` is a top-level dependency of the crate that supervises plugins.
+- **Facade leak from `clarion-storage`.** `writer.rs:427` reaches `clarion_core::plugin::manifest::RESERVED_ENTITY_KINDS` directly through the module path, bypassing the `lib.rs` re-export facade. The policy comment at `lib.rs:5-7` describes the facade as the supported surface; this constant is not in it. Either lift the constant to the facade or expose a `Manifest::is_reserved_kind` helper — the direct module reach pins the internal module path as semi-public.
+- **`mock.rs` at 876 LOC is gated behind `#[cfg(test)] pub(crate)`** (`plugin/mod.rs:22`). This is test infrastructure, not production code, so it does not appear in any release binary — but the volume of the mock (driver-script DSL, frame scripting, response builders) is a sign that the host's pipeline is non-trivially stateful, which corroborates the `host.rs` size concern.
+- **Subprocess lifecycle ownership is split.** `PluginHost::spawn` returns `(Self, std::process::Child)` (`host.rs:509`) and the doc at line 630-641 notes `Child::Drop` does not waitpid on Unix. The caller (currently `clarion-cli/analyze.rs`) must reap. The contract is documented but not enforced by the type system; a future consumer that drops `Child` on a happy path leaks a zombie until parent exit. A `KillOnDrop` newtype around the child would close this.
+- **The path jail is a TOCTOU check by design.** `jail.rs:67-72` explicitly documents this: the canonical-path return is "a membership proof at canonicalization time, not a durable file handle." Any consumer that later opens the path must re-jail after open or use `openat`-anchored I/O. The current consumer in this crate doesn't open files (it returns the canonical string downstream), but the comment is the only enforcement and a future caller could miss it.
+- **Limited integration test coverage in this crate's `tests/` directory.** Only one integration test file (`tests/host_subprocess.rs`, 325 LOC) — a single happy-path subprocess walkthrough against `clarion-plugin-fixture`. The host's many failure modes (every variant of `HostError`, every `CLA-INFRA-*` finding subcode) are exercised through inline `#[cfg(test)] mod tests` blocks at the bottom of each module — which works, but the integration surface (real `Command::spawn`, real `pre_exec`, real stderr-drain thread, real reap-on-error) is tested for the happy path only.
+- **`MAX_PROTOCOL_ERROR_FIELD_BYTES = 4 KiB`, `MAX_ENTITY_FIELD_BYTES = 4 KiB`, `MAX_ENTITY_EXTRA_BYTES = 64 KiB`, `STDERR_TAIL_BYTES = 64 KiB`, `MAX_HEADER_LINE_BYTES = 8 KiB`, `MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512`, `ContentLengthCeiling::DEFAULT = 8 MiB`, `EntityCountCap::DEFAULT_MAX = 500_000`, `DEFAULT_MAX_RSS_MIB`, `DEFAULT_MAX_NOFILE`, `DEFAULT_MAX_NPROC`, `PYRIGHT_MAX_NPROC = 4096`** — eleven hardcoded limit constants across `host.rs`, `transport.rs`, `limits.rs`. The `breaker.rs:7` comment acknowledges the config surface lands in WP6 and is not present at this snapshot. Until then, "operator can tune" is aspirational; every limit is a recompile.
+
+### Confidence: High
+
+Read end-to-end: `lib.rs`, `entity_id.rs`, `plugin/mod.rs`, `plugin/jail.rs`, `plugin/breaker.rs` (first 120 lines + skim of tests), and the doc-comment + public-surface scan plus targeted reads of the load-bearing windows of `protocol.rs` (300-499), `host.rs` (1-820, 1060-1190 + grep of all `pub fn`/`impl`/spawn-related symbols), `manifest.rs` (1-100 + reserved-kind constant cross-ref), `discovery.rs` (1-80 doc), `limits.rs` (1-120 + finding constants), `host_findings.rs` (1-80 + grep), `transport.rs` (1-100), and `llm_provider.rs` (1-130 + public-surface grep). Verified dependency edges by grepping `use clarion_core` across the rest of the workspace (`clarion-cli/{analyze,serve,secret_scan}.rs`, `clarion-storage/{commands,query,writer}.rs`, `clarion-mcp/src/lib.rs`, `clarion-plugin-fixture/src/main.rs`). Cross-checked the `CrashLoopBreaker` ownership claim by reading `clarion-cli/analyze.rs:240-275`. Confirmed the `clarion-storage::writer.rs:427` facade leak directly. The two areas read by sample-and-grep rather than end-to-end are `host.rs` (2,935 LOC; sampled the entry points, the four-stage pipeline, the spawn constructor, and the shutdown idempotency window) and `llm_provider.rs` (2,467 LOC; sampled the trait + the public-surface grep but did not read the OpenRouter/Codex/Claude provider implementations in detail — they are flagged in Concerns as out-of-scope tonally for this crate).
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-mcp.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-mcp.md
new file mode 100644
index 00000000..4279d2e1
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-mcp.md
@@ -0,0 +1,110 @@
+## 4. clarion-mcp
+
+**Location:** `crates/clarion-mcp/`
+**LOC:** 6,595 source (`lib.rs` 4,703 + `config.rs` 1,600 + `filigree.rs` 292) / 2,233 test (`tests/storage_tools.rs`)
+**Crate type / role:** Library crate. Implements the MCP (Model Context Protocol) JSON-RPC tool surface that consult-mode LLM agents call to query Clarion's index; not a binary — the `clarion serve` binary in `clarion-cli` consumes this library and drives the stdio loop.
+
+### Responsibility
+
+`clarion-mcp` owns the JSON-RPC tool dispatch layer and the stdio transport that fronts Clarion's index for external agents. It defines the twenty MCP tools (`list_tools` at `src/lib.rs:56`), translates MCP `tools/call` requests into bounded `clarion-storage` reader queries, mediates LLM-dispatch for on-demand summaries and inferred call edges with token-budget reservation (`BudgetLedger` at `lib.rs:2244`, `reserve_budget` at `lib.rs:2066`), and brokers Filigree enrichment lookups over HTTP. It also owns the YAML configuration schema (`McpConfig` at `config.rs:9`) consumed by `clarion serve` for LLM provider selection, Filigree integration, and the (separate) HTTP read-API bind/auth posture. The crate exposes its surface via `ServerState`, `serve_stdio*`, `handle_json_rpc`, and `list_tools`, and is consumed exclusively by `clarion-cli` (see Inbound below).
+
+### Key components
+
+- `src/lib.rs:56-258` — `list_tools()`: the canonical 20-tool registry with names, descriptions, and JSON schemas. Single source of truth; `handle_tool_call` validates names against it (`lib.rs:401`).
+- `src/lib.rs:316-2210` — `ServerState`: the stateful dispatcher. Holds `ReaderPool`, optional `SummaryLlmState` (writer mpsc + provider), optional `FiligreeLookup`, an `AnalyzeProcess` slot, a clock, an `InferredInflight` coalescer (`lib.rs:43`), and a `BudgetLedger`. Per-tool handlers (`tool_entity_at` at 493 … `tool_subsystem_members` at 1229) sit on `ServerState`.
+- `src/lib.rs:2704-2876` — Transport: `handle_frame*`, `read_stdio_frame`, `serve_stdio`, `serve_stdio_with_state`, `serve_stdio_with_state_on_runtime`. Implements dual framing (LSP-style `Content-Length` and JSON-line) auto-detected from the first non-whitespace byte (`peek_stdio_frame_start` at 2774).
+- `src/lib.rs:1560-2030` — Inferred-edge dispatch pipeline: cache lookup (`read_inferred_inputs` 1624), in-flight coalescing via `tokio::sync::broadcast` (`InferredInflightGuard` 2438; `coalesced_inferred_dispatch`), budget reservation, LLM provider invocation via `spawn_blocking` (`invoke_llm` 2218), and writer-channel persistence (`WriterCmd::InsertInferredEdges` at 1682/1824).
+- `src/lib.rs:2237-2290` — `AnalyzeProcess` + `BudgetLedger` + `BudgetReservation`: spawns `clarion analyze` as a detached child for `analyze_start`/`analyze_status`/`analyze_cancel`; tracks reserved-vs-spent LLM tokens with a `Mutex`-guarded ledger.
+- `src/config.rs:9-742` — `McpConfig` (YAML, `serde_norway`): `LlmConfig` (provider kind, model id, session token ceiling, per-caller inferred-edge cap, cache TTL), provider-specific subsections (`OpenRouterConfig`, `CodexCliConfig`, `ClaudeCliConfig`), `FiligreeConfig` (base URL, project key, token env, actor, timeout), `HttpReadConfig` (bind, loopback trust, bearer + identity HMAC env vars), and `select_provider_with_env` (677) which builds an `LlmProvider` honoring `recording_fixture_path` and `allow_live_provider`.
+- `src/filigree.rs:1-292` — Filigree HTTP client: `FiligreeLookup` trait (52), blocking-reqwest implementation `FiligreeHttpClient` (64), URL builder `entity_associations_url` (148), and response shape `EntityAssociationsResponse` (11).
+
+### Public interface (outbound)
+
+- **20 MCP tools** (the consult-agent contract, from `list_tools`):
+  1. `entity_at` — innermost entity containing `(file, line)`; path-normalized against project root.
+  2. `project_status` — orientation snapshot: index age, latest run, graph counts, git state, plugin discovery, LLM policy, Filigree routing, analyze lifecycle.
+  3. `analyze_start` — spawn background `clarion analyze` child; supports `allow_no_plugins`.
+  4. `analyze_status` — child process state + latest persisted `runs` row.
+  5. `analyze_cancel` — kill the background analyze child if running.
+  6. `find_entity` — paginated FTS-ranked search over entity id/name/short-name/summary; does *not* search `summary_cache`.
+  7. `source_for_entity` — line-numbered source span with bounded context; includes decorator lines.
+  8. `entity_context` — resolve by id or `(file,line)`; returns containing stack + source + diagnostics.
+  9. `call_sites` — caller/callee evidence with source snippets at recorded byte offsets.
+  10. `callers_of` — callers, default confidence `resolved`; opt-in to `ambiguous` (expand candidates) or `inferred` (may trigger LLM dispatch).
+  11. `execution_paths_from` — bounded calls-only traversal; default `max_depth=3`, hard `execution_edge_cap` (default 500, settable via `with_edge_cap`).
+  12. `execution_paths_ranked` — compact ranked path view; optional `exclude_tests`, `max_paths`.
+  13. `summary` — on-demand cached *leaf* summary; module entities return scope-deferred policy envelope, not aggregation.
+  14. `summary_preview_cost` — cache status, model/provider, token estimate, live-spend requirement; no dispatch.
+  15. `issues_for` — Filigree associations for an entity, optionally `include_contained`; returns `unavailable` envelope if Filigree disabled rather than failing.
+  16. `orientation_pack` — deterministic first-pass packet (status, source, callers, callees, issues, next reads); no LLM.
+  17. `index_diff` — freshness signals: latest run, DB mtime, source files newer than index, changed entity hashes.
+  18. `neighborhood` — one-hop graph (callers, callees, container, contained, references).
+  19. `subsystem_members` — module entities for a subsystem entity.
+  20. (twentieth slot) `summary_preview_cost` and `summary` count separately; full enumeration above totals 19 visible — the registry actually contains 19 entries, not 20. **Note:** the discovery doc cites "twenty tools"; the registry as of `lib.rs:56-257` contains 19 distinct `ToolDefinition` entries. Flagging in Concerns.
+- **Rust API:**
+  - `pub fn list_tools() -> Vec<ToolDefinition>` (`lib.rs:56`).
+  - `pub fn handle_json_rpc(&Value) -> Option<Value>` (`lib.rs:295`) — state-free metadata-only path (`initialize`, `tools/list`).
+  - `pub struct ServerState` with builder methods `new`, `with_edge_cap`, `with_summary_llm`, `with_clock`, `with_filigree_client` (`lib.rs:316-376`); `ServerState::handle_json_rpc(&Value) -> Option<Value>` (377).
+  - `pub fn serve_stdio`, `serve_stdio_with_state`, `serve_stdio_with_state_on_runtime` (`lib.rs:2831-2876`).
+  - `pub fn handle_frame`, `handle_frame_with_state` (`lib.rs:2704-2721`) — frame-level entry points for callers that own their own loop.
+  - `pub enum McpError` (`lib.rs:2690`), `pub const MCP_PROTOCOL_VERSION = "2025-11-25"` (`lib.rs:40`).
+- **Config API (`config` module):** `McpConfig::from_path`, `McpConfig::from_yaml_str`, `select_provider_with_env`, `resolve_filigree_http_target`, `resolve_filigree_base_url`, `HttpReadConfig::{validate_loopback_trust, validate_auth_trust, is_loopback_bind}`.
+- **Filigree API (`filigree` module):** `FiligreeLookup` trait, `FiligreeHttpClient::from_config`, `entity_associations_url`, `parse_entity_associations_response`.
+
+### Dependencies
+
+- **Inbound (who calls this):**
+  - `crates/clarion-cli/src/serve.rs:13-150` — sole production caller. Imports `config::{McpConfig, LlmConfig, select_provider_with_env, ...}`, `filigree::FiligreeHttpClient`, `ServerState::new`, `with_summary_llm`, `with_filigree_client`, `serve_stdio_with_state_on_runtime`. Spawns the stdio loop on a named thread `clarion-mcp-stdio`.
+  - `crates/clarion-cli/src/http_read.rs:18` — reuses `clarion_mcp::config::HttpReadConfig` to drive the *separate* HTTP read-API server (which is implemented in `clarion-cli`, not here).
+  - `crates/clarion-cli/src/install.rs:68` — references the literal string `"clarion-mcp"` in template output (the default Filigree actor).
+- **Outbound (what this calls):**
+  - `clarion-core` (`plugin::{Frame, TransportError, ContentLengthCeiling, read_frame, write_frame}`; LLM primitives `LlmProvider`, `LlmRequest`, `LlmResponse`, `LlmProviderError`, `LlmPurpose`, `build_inferred_calls_prompt`, `build_leaf_summary_prompt`, `INFERRED_CALLS_PROMPT_VERSION`, `LEAF_SUMMARY_PROMPT_TEMPLATE_ID`, `InferredCallsPromptInput`, `LeafSummaryPromptInput`, `EdgeConfidence`).
+  - `clarion-storage` — read side via `ReaderPool::with_reader` (~30 call sites including `entity_at_line`, `entity_by_id`, `find_entities`, `call_edges_from`, `call_edges_targeting`, `reference_edges_for_entity`, `child_entity_ids`, `contained_entity_ids`, `existing_entity_ids`, `subsystem_members`, `summary_cache_lookup`, `inferred_edge_cache_lookup`, `inferred_edge_cache_key_id`, `unresolved_call_sites_for_caller`, `unresolved_callers_for_target`, `candidate_entities_for_unresolved_sites`, `normalize_source_path`); write side strictly via `WriterCmd` over `mpsc::Sender<WriterCmd>` — only three variants emitted: `InsertInferredEdges` (twice, `lib.rs:1682`/`1824`), `TouchSummaryCache` (`lib.rs:1924`), `UpsertSummaryCache` (`lib.rs:2024`).
+  - External crates: `tokio` (current-thread runtime, `AsyncMutex`, `mpsc`, `oneshot`, `broadcast`, `spawn_blocking`), `reqwest::blocking` (Filigree), `rusqlite` (re-exported types only — no direct `Connection::open`; all DB access flows through `ReaderPool`/`WriterCmd`), `serde_norway` (YAML config), `time`, `blake3`, `thiserror`, `tracing`.
+- **External services:**
+  - **SQLite** via `clarion-storage::ReaderPool` — read concurrency; writes only via the writer-actor channel.
+  - **Subprocess: `clarion analyze`** — spawned by `tool_analyze_start` using `std::env::current_exe()` (`lib.rs:572-599`), stdin/stdout/stderr null'd.
+  - **Filigree HTTP** — blocking `reqwest` GET to `{base_url}/api[/p/{project_key}]/entity-associations?entity_id=...` with `x-filigree-actor` and bearer auth (`filigree.rs:98-127`).
+  - **LLM providers** — pluggable `Arc<dyn LlmProvider>` invoked via `tokio::task::spawn_blocking` (`lib.rs:2218`); config chooses OpenRouter (HTTP), Codex CLI, Claude CLI, or a deterministic Recording fixture (`config.rs:677`).
+
+### Internal architecture
+
+The crate is a single stateful dispatcher (`ServerState`) plus a thin stdio I/O loop. `ServerState::handle_json_rpc` (`lib.rs:377`) routes `initialize` and `tools/list` to static helpers, and `tools/call` to `handle_tool_call` (394) which dispatches on tool name via a 19-arm `match` (`lib.rs:413-488`). Each `tool_*` handler is `async`, takes the argument map, parses required/optional params (`required_str`, `optional_bool`, …), and either returns a JSON envelope or a `ParamError` that becomes a JSON-RPC error response. Storage reads flow through `self.readers.with_reader(|conn| …)`, which offloads onto the reader pool's blocking workers; the handler awaits the result and wraps it in `envelope_from_storage_result`.
+
+**Concurrency model.** The crate is built around a borrowed Tokio current-thread runtime (`serve_stdio_with_state_on_runtime` accepts `&Runtime` from the caller; `serve_stdio_with_state` builds its own). The dispatch path is fully async, but the stdio I/O is synchronous: the loop does a blocking `read_stdio_frame` on `&mut impl std::io::BufRead`, then `runtime.block_on(handle_stdio_frame_with_state(...))`, then a blocking `write_stdio_response`. There is no parallel request handling — frames are processed strictly sequentially per stdio session. Three internal concurrency primitives matter:
+  1. `BudgetLedger` behind a `std::sync::Mutex` (`lib.rs:322`) — gates LLM dispatch with a reserve/commit pattern and a `blocked` latch.
+  2. `InferredInflight` — `Arc<AsyncMutex<HashMap<InferredEdgeCacheKey, broadcast::Sender<...>>>>` (`lib.rs:43`) — coalesces concurrent `callers_of`/inferred-edge requests for the same `(caller_id, content_hash, model_id, prompt_version)` tuple so only one LLM call fires; followers subscribe via `broadcast` and `RAII`-clean up via `InferredInflightGuard` (`lib.rs:2438`).
+  3. `analyze_process` — a `std::sync::Mutex<Option<AnalyzeProcess>>` slot for the at-most-one in-flight `clarion analyze` child.
+
+**State ownership.** `ServerState` owns the `ReaderPool`, the optional writer `mpsc::Sender<WriterCmd>` (cloned out of `SummaryLlmState` per dispatch), the optional Filigree client behind `Arc<dyn FiligreeLookup>`, the `clock` (injectable for tests), and the analyze-process slot. The writer-actor itself lives in `clarion-cli/src/serve.rs:135-144`, not here — `clarion-mcp` is a writer *client*, never a writer host.
+
+**Transport.** The stdio frame reader auto-detects between LSP-style `Content-Length` framing (delegated to `clarion_core::plugin::read_frame`/`write_frame`) and bare-JSON-line framing by peeking the first non-whitespace byte (`lib.rs:2757-2789`). The choice is per-frame, recorded in `StdioFrame::framing`, and reused on the response. JSON-RPC notifications (method present, id absent) are silently dropped (`is_json_rpc_notification` at `lib.rs:2740`). Test `serve_stdio_handles_multiple_content_length_frames` (`lib.rs:4309`) and `serve_stdio_with_state_uses_json_line_transport_for_json_line_requests` (4400) pin the dual-framing contract.
+
+**Error model.** Two layers: `McpError` (`lib.rs:2690`) — `Json | Transport | Runtime` — surfaces only from frame I/O and JSON decode failures and aborts the loop; per-tool errors stay inside the JSON-RPC response as either error responses (`ParamError`) or success envelopes with `tool_error_envelope(code, message, retryable)` (e.g. `analyze-already-running`, `analyze-start-failed`, `token-ceiling-exceeded`, `llm-disabled`, `invalid-path`). The retryability flag is on the wire, not just in logs. `ConfigError` (`config.rs:742`) uses stable string error codes (`CLA-CONFIG-*`) so the CLI can route them.
+
+### Patterns observed
+
+- **Tool registry as single source of truth** — `list_tools()` validates incoming names at dispatch (`lib.rs:401`) and is also served verbatim to `tools/list`; adding a tool requires both a registry entry and a `match` arm, but the unreachable arm (`lib.rs:487`) is documented by the prior validation.
+- **Reader pool + writer-actor split** — every DB read goes through `ReaderPool::with_reader` (~30 sites); every DB write goes through `mpsc::Sender<WriterCmd>` with an `oneshot` ack (`send_writer` helper at `lib.rs:2043`). The crate never opens a `rusqlite::Connection` directly.
+- **Coalescing + RAII guards for expensive async work** — `InferredInflightGuard` and `BudgetReservation` both use `Drop` to release in-flight slots / reserved tokens even if the awaiting future is cancelled (`lib.rs:2278-2290`, `2471-2486`). The `Drop` paths for guards spanning runtime boundaries use `tokio::runtime::Handle::try_current` to schedule async cleanup.
+- **Dual-framing transport with byte-peek detection** — same `serve_stdio` loop handles LSP-style and JSON-line clients without configuration (`lib.rs:2757`).
+- **Capability gating via `Option<…>` builder fields** — LLM features (`summary_llm`) and Filigree enrichment (`filigree_client`) are off unless `with_summary_llm` / `with_filigree_client` is called. Tool handlers check for `None` and return policy envelopes (`llm-disabled`, Filigree `unavailable` envelope) rather than failing.
+- **Stable error-code strings on the wire** — both tool envelopes (`token-ceiling-exceeded`, `analyze-already-running`, `invalid-path`) and config errors (`CLA-CONFIG-HTTP-NO-AUTH`, `CLA-CONFIG-FILIGREE-PORT-CONFLICT`, etc.) use prefix-namespaced identifiers callers can switch on.
+- **Recording-provider determinism hook** — `LlmConfig.recording_fixture_path` (`config.rs:78`) + `select_provider_with_env` (677) let tests pin LLM responses without network calls; the test suite at `tests/storage_tools.rs` uses `RecordingProvider` heavily.
+
+### Concerns / Smells / Risks
+
+- **`lib.rs` is 4,703 lines in a single file.** This is the dominant smell. It contains the tool registry, all 19 tool handlers, transport, framing, budget ledger, inflight coalescer, analyze-process management, error/envelope helpers, and ~700 lines of unit tests (`mod tests` at `lib.rs:4309`+). A natural split is at least three files: `tools/` (one module per tool family), `transport.rs` (stdio framing), `dispatch.rs` (inferred-edge + summary LLM machinery). Risk: merge conflicts, slow IDE feedback, hard to review.
+- **Discovery doc says "twenty tools"; registry contains 19.** Enumerated above. Either the doc is stale or a tool was removed without updating discovery; worth confirming against the design intent. Flagging because the prompt called this out as a precise characterization target.
+- **Dispatch is purely sequential.** `serve_stdio_with_state_on_runtime` does `runtime.block_on(...)` inside the loop and a blocking read between frames. A slow LLM-dispatching `summary` or `callers_of` request blocks all subsequent tool calls on the same stdio session. The reader pool is internally concurrent but it doesn't help here. For consult-agent UX this is probably fine; for multi-agent or long-LLM-call scenarios it is a wall.
+- **`reqwest::blocking` inside an async dispatcher.** `FiligreeHttpClient::associations_for` (`filigree.rs:98`) is synchronous and is called from `tool_issues_for` (`lib.rs:1154`) which is `async`. The call appears to happen on whatever thread the `block_on` is running, blocking the current-thread runtime for the configured timeout (default 5s). Should be `spawn_blocking`-wrapped or moved to `reqwest`'s async client.
+- **Writer-channel coupling.** All writer commands flow through the `summary_llm.writer` field — which means inferred-edge writes are gated on the *summary* LLM being configured (`inference_llm_snapshot` at `lib.rs:2093` clones from `summary_llm`). Two LLM features share one writer handle and one config slot. Functional today (one writer per process), but the naming overloads "summary" to mean "any LLM-related writes."
+- **Mutex poisoning swallowed everywhere.** Every `self.analyze_process.lock()`, `self.budget.lock()`, etc. uses `.unwrap_or_else(std::sync::PoisonError::into_inner)` (e.g. `lib.rs:556`, `2061`, `2284`). This silently masks the panic that caused the poisoning. Acceptable as a deliberate "keep serving" choice but worth a comment.
+- **`config.rs` is 1,600 lines** with the YAML schema, three provider config blocks, two HTTP trust-validators, provider selection, and a sizable error enum. Splitting per provider would help.
+- **Test coverage is heavily integration-tested in `tests/storage_tools.rs`** (2,233 LOC, ~35 `#[tokio::test]`s observed) but the in-`lib.rs` unit tests (`lib.rs:4309+`) are narrow — mostly transport framing. The inferred-edge coalescing logic is intricate and would benefit from focused unit tests independent of full storage seeding.
+- **No timeout on `tool_analyze_start` child.** The spawned `clarion analyze` runs unbounded; `analyze_cancel` is the only stop. If the agent forgets to poll, the child can outlive the session.
+- **Filigree client is held behind `Arc<dyn FiligreeLookup>` but `FiligreeHttpClient` itself wraps `reqwest::blocking::Client` (already `Clone`).** The `dyn` indirection is fine for test substitution; just noting that the trait has exactly one production impl plus test fakes.
+
+### Confidence: High
+
+Read `lib.rs` lines 1-260 and 250-600 end-to-end, plus targeted reads of the LLM/budget/coalescing region (1600-1690, 2040-2310), the transport region (2680-2876), and supporting helpers. Read `filigree.rs` end-to-end (292 lines), `config.rs` lines 1-410 plus targeted reads. Confirmed the inbound caller surface by grepping all `clarion_mcp` / `clarion-mcp` references in `crates/` (one consumer: `clarion-cli`, three call sites in `serve.rs` / `http_read.rs` / `install.rs`). Confirmed writer-channel use by enumerating all `WriterCmd::` and `send_writer` sites (4 emission points, 3 distinct variants). Tool count verified by reading the registry block 56-257 directly — registry contains 19 entries, flagged against the discovery doc's claim of 20.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-plugin-fixture.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-plugin-fixture.md
new file mode 100644
index 00000000..af489187
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-plugin-fixture.md
@@ -0,0 +1,80 @@
+## 6. clarion-plugin-fixture
+
+**Location:** `crates/clarion-plugin-fixture/`
+**LOC:** 187 source (3 `lib.rs` + 184 `main.rs`); 0 in-crate tests — exercised externally by 931 LOC of test code in `clarion-core` and `clarion-cli`.
+**Crate type / role:** Binary crate (`[[bin]] name = "clarion-plugin-fixture"`) plus a stub `lib.rs` whose only job is to let Cargo resolve the workspace member cleanly. Functionally a **test-only protocol-reference plugin**: a minimal, correct implementation of the L4 JSON-RPC wire contract used to drive the plugin host's subprocess code paths without needing the Python plugin on `PATH`.
+
+### Responsibility
+
+This crate owns the *smallest valid implementation* of the Clarion plugin protocol — just enough to (a) prove `clarion-core::plugin::host` can spawn a child, negotiate `initialize`/`initialized`/`analyze_file`/`shutdown`/`exit`, and round-trip framed JSON-RPC, and (b) deterministically misbehave on demand (RLIMIT_AS exhaustion via `CLARION_FIXTURE_EXCEED_RLIMIT_AS`) so the host's OOM-kill and crash-loop-breaker paths can be tested end-to-end. It is intentionally not a real analyzer: every `analyze_file` returns the same single hard-coded widget entity regardless of the input file's content. The crate's "public surface" is therefore (1) the binary itself, consumed by `cargo nextest` via `CARGO_BIN_EXE_clarion-plugin-fixture`, and (2) the fixture identity tuple (`plugin_id=fixture`, kind `widget`, qualname `demo.sample`, rule-ID prefix `CLA-FIXTURE-`) that tests assert against verbatim.
+
+### Key components
+
+- `src/main.rs:23-123` — the JSON-RPC dispatch loop: blocking `read_frame` → parse → match on `method` → either no-op (notification) or send a typed result envelope. Uses `clarion-core` framing and request/response types directly so the wire shape stays in lockstep with the host.
+- `src/main.rs:67-76` — `initialize` handler: emits `InitializeResult { name, version, ontology_version: "0.1.0", capabilities: {} }`.
+- `src/main.rs:77-115` — `analyze_file` handler: extracts `file_path` from params, returns one entity (`fixture:widget:demo.sample`, `kind=widget`, `qualified_name=demo.sample`, `source.file_path=<input>`), no edges, default stats.
+- `src/main.rs:48-60` — notification dispatch for `initialized` (becomes-ready, no reply) and `exit` (process-exits-0, no reply).
+- `src/main.rs:78-83, 137-184` — the `CLARION_FIXTURE_EXCEED_RLIMIT_AS` escape hatch: on Unix, repeatedly `mmap_anonymous` doubling-size regions with `PROT_NONE` to blow past `RLIMIT_AS`, then `SIGKILL` self via `nix::sys::signal::kill`. The mappings are held but never dereferenced (documented `SAFETY` comment).
+- `src/main.rs:125-135` — `send_result` helper: wraps a `Value` in `ResponseEnvelope { jsonrpc, id, payload: Result(...) }`, serialises, frames via `write_frame`, flushes.
+- `src/lib.rs:1-3` — three-line doc-only stub explaining why the lib target exists.
+
+### Public interface (outbound)
+
+The plugin speaks the L4 JSON-RPC protocol on stdin/stdout. Methods implemented:
+
+- **`initialize`** (request) — returns `InitializeResult` with `ontology_version=0.1.0`, empty capabilities. `src/main.rs:68-76`
+- **`initialized`** (notification) — accepted, no-op. `src/main.rs:51-53`
+- **`analyze_file`** (request) — accepts `AnalyzeFileParams`, returns one canned entity. `src/main.rs:77-115`
+- **`shutdown`** (request) — returns empty `ShutdownResult`. `src/main.rs:116-119`
+- **`exit`** (notification) — `process::exit(0)`. `src/main.rs:54-56`
+
+Any unknown method, malformed frame, or unparseable JSON causes `process::exit(1)` (`src/main.rs:33-39, 46, 57, 64, 97, 120`).
+
+Companion manifest (consumed by host, not shipped by this crate): `crates/clarion-core/tests/fixtures/plugin.toml` declares `plugin_id="fixture"`, `language="fixture"`, `extensions=["mt"]`, `entity_kinds=["widget"]`, `edge_kinds=["uses"]`, `rule_id_prefix="CLA-FIXTURE-"`.
+
+### Dependencies
+
+- **Inbound (who consumes the binary):**
+  - `crates/clarion-core/tests/host_subprocess.rs` — direct subprocess test of `PluginHost::spawn`; locates the binary via `CARGO_BIN_EXE_clarion-plugin-fixture` (`host_subprocess.rs:30`) with a `cargo build` fallback (`:84-94`). Asserts entity id `fixture:widget:demo.sample` (`:162`).
+  - `crates/clarion-cli/tests/wp2_e2e.rs` — declares `clarion-plugin-fixture` as a `[dev-dependencies]` entry (`clarion-cli/Cargo.toml:43`) so nextest exports the env var, symlinks the binary into a synthetic plugin dir, and drives the full `clarion analyze` CLI through it. Tests: `wp2_e2e_smoke_fixture_plugin_round_trip` (line 135), `wp2_rlimit_as_oom_kill_is_reported_as_host_finding` (line 259, uses `CLARION_FIXTURE_EXCEED_RLIMIT_AS`), `wp2_crash_in_one_plugin_does_not_prevent_other_plugins_from_running` (line 323), `wp2_crash_loop_breaker_trips_and_skips_remaining_plugins` (line 471).
+- **Outbound (what this calls):**
+  - `clarion-core::plugin::transport` — `read_frame` / `write_frame` / `Frame` for length-prefixed framing.
+  - `clarion-core::plugin::limits::ContentLengthCeiling::DEFAULT` (8 MiB per ADR-021 referenced in source comment, `main.rs:30-32`).
+  - `clarion-core::plugin` request/response DTOs: `AnalyzeFileParams`, `AnalyzeFileResult`, `AnalyzeFileStats`, `InitializeResult`, `ShutdownResult`, `JsonRpcVersion`, `ResponseEnvelope`, `ResponsePayload`.
+  - `serde_json` for ad-hoc `Value` parsing of the inbound request envelope.
+  - `nix` (Unix only, `mman` + `signal` features) — only for the deliberate-OOM probe.
+- **External services:** None at runtime. Communicates only over inherited stdin/stdout with its parent (the plugin host).
+
+### Internal architecture
+
+The binary is a single synchronous loop in `main()` (`main.rs:23-123`); there are no modules, threads, async runtime, or background tasks. State machine is implicit and minimal: the loop accepts notifications and requests in any order after the host has spoken — there is no explicit "before-initialize" guard, which is acceptable because the host always sends `initialize` first and the fixture's responses are stateless. The shape is `loop { read_frame → parse Value → branch on (has_id, method) → dispatch }`.
+
+Error model is intentionally brutal: any deviation from the happy path (truncated frame, non-UTF8, missing method, unknown method, unparseable params) calls `std::process::exit(1)` with no reply. This is *desired* behaviour — `clarion-core`'s host has to handle a plugin that hangs up mid-stream, and crashing the fixture is the cheapest way to drive that path. The crash-loop-breaker test (`wp2_e2e.rs:471`) depends on this.
+
+The `exceed_rlimit_as` path (`main.rs:137-184`) is the only piece of nontrivial logic. It pre-reserves 1024 mapping handles before the memory pressure starts (so the `Vec::push` itself does not allocate after the kernel starts refusing maps), then loops `mmap_anonymous(PROT_NONE, MAP_PRIVATE)` doubling the request size each iteration starting at 128 MiB. PROT_NONE means no physical pages are committed — only address space is consumed, which is exactly what `RLIMIT_AS` constrains. When the next request would not grow (`saturating_mul(2)` saturated) or `mmap` returns `Err`, the fixture `SIGKILL`s itself so the parent observes a signal-death, not a clean exit. This is the load-bearing detail that distinguishes OOM-kill from a controlled shutdown in the host's diagnosis.
+
+`lib.rs` exists solely so the crate works as a workspace member with a binary target (3 lines, doc comment only).
+
+### Patterns observed
+
+- **Stub lib + real bin** (`lib.rs:1-3` + `Cargo.toml:12-14`) — workspace-member compatibility trick.
+- **Untyped envelope parse, typed payload re-parse** (`main.rs:37-44, 93-98`) — read the whole frame as `serde_json::Value` to inspect `id`/`method` before committing to a typed struct, so unknown/malformed messages can be rejected without spurious deserialisation errors.
+- **Crash-on-anomaly as a feature** (`main.rs:33-46, 57, 97, 120`) — every error path is `process::exit(1)`. Tests want this behaviour.
+- **Hard-coded fixture identity** (`main.rs:101-108`) — `"fixture:widget:demo.sample"` is the ground-truth string tests assert on; do not change without updating both call sites listed under Inbound.
+- **Environment-flag-driven fault injection** (`main.rs:78-83`) — `CLARION_FIXTURE_EXCEED_RLIMIT_AS` toggles the OOM path; default behaviour is benign.
+- **PROT_NONE address-space probe** (`main.rs:137-178`) — exhausts virtual address space cheaply (no page commits) to trip a specific kernel limit deterministically.
+- **Pre-reserved Vec to avoid allocation under memory pressure** (`main.rs:142-145`).
+
+### Concerns / Smells / Risks
+
+- **`process::exit(1)` everywhere with no diagnostic output.** Reasonable for a test fixture (the host is the system under test), but if a future test asserts on stderr or a specific exit code other than 1, every error branch will need disambiguating. No `eprintln!` anywhere. `main.rs:33-46, 57, 97, 120`.
+- **No "initialize must come first" sequencing check.** A misbehaving host could call `analyze_file` before `initialize` and the fixture would happily respond. This is fine today because the host always sequences correctly, but the fixture is not a conformance checker — do not use it as one.
+- **`unwrap()` on `serde_json::to_value(InitializeResult)`** (`main.rs:75`) and other result serialisations — defensible because the types are `Serialize`-derived, but pedantically these are crash points.
+- **Unix-gated OOM path with a `cfg(not(unix))` arm that just `exit(1)`s** (`main.rs:78-83`) — Windows CI would silently lose coverage of the RLIMIT_AS branch. Acceptable since OOM-kill semantics are Unix-specific.
+- **The manifest lives in another crate's test tree** (`clarion-core/tests/fixtures/plugin.toml`), not in this crate. Discoverable only by `grep`. Two callers (`host_subprocess.rs` and `wp2_e2e.rs`) construct their own variants of it. A `tests/fixtures/plugin.toml` here, re-used by both, would be cleaner; not urgent.
+- **Hard-coded `version = "0.1.0"` and `ontology_version = "0.1.0"`** in the binary (`main.rs:71-72`) do not pick up the workspace version — if version-handshake logic ever depends on these, they will drift from `Cargo.toml`. Currently the host does not validate them.
+- **No in-crate tests.** Justified: the fixture *is* the test apparatus for two upstream test files. Counting test coverage of this crate in isolation is meaningless.
+
+### Confidence: High
+
+Read all 187 source lines end-to-end, the companion manifest in `clarion-core/tests/fixtures/plugin.toml`, and grepped both consumer tests (`host_subprocess.rs`, `wp2_e2e.rs`) for every reference to `clarion-plugin-fixture`, `fixture:widget:demo`, and `CLARION_FIXTURE_EXCEED_RLIMIT_AS` to confirm the protocol surface and the four named test cases. Inbound dep edges verified via `Cargo.toml:43` of `clarion-cli`. Outbound dep edges verified by walking every `use clarion_core::` import in `main.rs`.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-scanner.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-scanner.md
new file mode 100644
index 00000000..fc77fa9a
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-scanner.md
@@ -0,0 +1,86 @@
+## 5. clarion-scanner
+
+**Location:** `crates/clarion-scanner/`
+**LOC:** 881 source (`lib.rs` 233 + `patterns.rs` 303 + `baseline.rs` 285 + `entropy.rs` 60) / 655 test (`tests/scanner.rs`)
+**Crate type / role:** Library crate (`pub` API consumed by `clarion-cli`); pure CPU, no I/O except baseline YAML read.
+
+### Responsibility
+
+Owns Clarion's pre-ingest secret-detection pass: given an in-memory byte buffer, emit a deduplicated, byte-offset-anchored list of `Detection` records identifying secret-shaped substrings, plus a YAML-backed baseline mechanism that suppresses operator-acknowledged matches at the `(file, rule_type, hashed_secret, line_number)` granularity. The crate is deliberately scoped to detection + suppression — it does not walk the filesystem, decide which files to scan, emit findings, or report results; those concerns live in `clarion-cli/src/secret_scan/*`. Stores only positions, rule identifiers, and a detect-secrets-compatible SHA-1 digest of matched bytes — literal secret values do not leave the call (`lib.rs:1-5`).
+
+### Key components
+
+- `src/lib.rs:23-46` — `Detection` struct + `SecretCategory` enum: closed taxonomy with 9 categories (CloudCredential, VcsCredential, AiProviderCredential, PaymentsCredential, MessagingCredential, PrivateKey, JwtToken, HighEntropy, ContextualCredential).
+- `src/lib.rs:49-99` — `HashedSecret([u8; 20])` newtype: SHA-1 digest with hex round-trip (`from_hex`, `Display`); decoupled from `sha1::Sha1` impl detail at the public surface.
+- `src/lib.rs:102-200` — `DetectSecretsRule` enum: 14-variant closed vocabulary aligned to detect-secrets type names; `as_str()`/`rule_id()`/`FromStr` provide bidirectional mapping between human label (baseline YAML) and stable rule-id string (findings).
+- `src/patterns.rs:25-71` — `Scanner` struct: pre-compiles a `RegexSet` (fast first-pass match) plus per-pattern `Regex` (for captures), holds entropy regexes and tunings; `Default`/`new()` build the ADR-013 v0.1 floor.
+- `src/patterns.rs:79-162` — `scan_bytes()` + `scan_entropy()`: two-pass detection — named patterns first, entropy fallback over non-overlapping ranges; outputs sorted by `(byte_offset, rule_id)`.
+- `src/patterns.rs:194-269` — `default_pattern_meta()`: the 12-entry rule floor (literal source of detection truth).
+- `src/baseline.rs:11-44` — `Baseline`, `BaselineEntry`, `BaselineMatch`, `SuppressionResult` types: model the suppression file shape and the result envelope (allowed/suppressed/fired).
+- `src/baseline.rs:104-144` — `Baseline::suppress()`: O(detections × entries_per_file) match using exact `(hashed_secret, line_number, rule_type)` triple as the suppression key.
+- `src/baseline.rs:146-217` — `from_raw()` validation pipeline: version check (`"1.0"` only), path safety (`validate_baseline_path`), mandatory `justification`, hex-hash validity, closed rule-type vocabulary.
+
+### Public interface (outbound)
+
+Re-exported through `lib.rs:11-16`:
+
+- `Scanner` (`patterns.rs:25`) — owns compiled regexes; cheap to construct once and reuse. Method: `scan_bytes(&self, buf: &[u8]) -> Vec<Detection>`.
+- `Detection` (`lib.rs:23-32`) — one match: `rule_id`, `detect_secrets_type`, `category`, `byte_offset`, `line_number`, `matched_len`, `hashed_secret`.
+- `DetectSecretsRule`, `SecretCategory` (`lib.rs:36-46`, `102-118`) — closed enums for downstream pattern-matching.
+- `HashedSecret`, `HexDigestError` (`lib.rs:49-99`) — opaque hash newtype.
+- `Baseline`, `BaselineEntry`, `BaselineEntryIssue`, `BaselineMatch`, `BaselineError`, `SuppressionResult` (`baseline.rs`) — operator-baseline model + error taxonomy with 7 variants (`UnsupportedVersion`, `MissingJustifications`, `InvalidPath`, `InvalidHash`, `UnsupportedRuleType`, `Parse`, `Io`).
+- `load_baseline(&Path) -> Result<Baseline, BaselineError>` (`baseline.rs:71-77`) — accepts a missing file as `Baseline::empty()` (graceful absence).
+- `EntropyTuning` (`entropy.rs:5-23`) — exposed but only `BASE64` and `HEX` consts are constructed internally; `min_len` + `min_entropy` fields.
+- `PatternMeta` (`patterns.rs:10-15`) — exposed via `Scanner::pattern_meta()`, primarily for introspection.
+
+### Dependencies
+
+- **Inbound (who calls this):** Only `clarion-cli`:
+  - `clarion-cli/src/secret_scan.rs` imports `Detection`, `Scanner`, `SuppressionResult`.
+  - `clarion-cli/src/secret_scan/baseline.rs` imports `Baseline`, `BaselineError`.
+  - `clarion-cli/src/secret_scan/findings.rs` imports `Detection`, `SecretCategory`, `DetectSecretsRule`, `HashedSecret`.
+- **Outbound (what this calls):** No internal Clarion crates. External: `regex` (bytes flavour), `sha1`, `serde` + `serde_norway` (YAML), `thiserror`.
+- **External services:** None directly. Reads the baseline file via `std::fs::read_to_string` (`baseline.rs:72`); no other I/O. Pure-function `scan_bytes` over an `&[u8]`.
+
+### Internal architecture
+
+Three modules + `lib.rs` umbrella. `lib.rs` owns the shared value types (`Detection`, `HashedSecret`, `DetectSecretsRule`, `SecretCategory`) and two tiny helpers — `sha1_digest` (`lib.rs:208-214`) and `line_number_for_offset` (`lib.rs:216-224`, a byte-by-byte newline count over the prefix). Concurrency is **none** — there is no shared mutable state; `Scanner` is `Send + Sync` by construction (only immutable compiled regexes), so callers parallelize at the file-level outside the crate (and `clarion-cli/src/secret_scan.rs:scan_source_files_parallel` does exactly that).
+
+`patterns.rs` runs detection in two layers. Layer 1: `RegexSet` first-pass (`patterns.rs:80`) over the whole buffer — only patterns whose set-membership matched then have their full `Regex` run for capture extraction (`patterns.rs:83-87`). Layer 2: entropy fallback (`scan_entropy`, `patterns.rs:128-161`) runs the base64 candidate regex `[A-Za-z0-9+/]{20,}={0,2}` and hex candidate `\b[a-fA-F0-9]{40,}\b`, skipping candidates that **overlap any already-found named match** (`range_overlaps`, `patterns.rs:271-275`). The base64 fallback additionally requires non-base64 boundary bytes on each side (`base64_candidate_has_boundaries`, `patterns.rs:277-281`) — a hand-rolled `\b`-equivalent because `=` is not a word character.
+
+Entropy is parameterized by two `EntropyTuning` constants:
+- `BASE64`: `min_len = 20`, `min_entropy = 4.5` (`entropy.rs:11-14`).
+- `HEX`: `min_len = 40`, `min_entropy = 3.0` (`entropy.rs:15-18`).
+
+Entropy itself is Shannon entropy in bits/symbol over byte frequency (`entropy.rs:25-41`) using a `BTreeMap<u8, usize>` count table, computed as `-Σ p_i log2(p_i)`. These thresholds are deliberately wide: tests `entropy_minimum_lengths_are_pinned` (`tests/scanner.rs:171-174`) and the lockfile-SHA fixture (`tests/scanner.rs:568-638`) document that the hex threshold *intentionally* fires on git SHAs and npm lockfile integrity hashes — the v0.1 stance is to suppress via baseline rather than tighten the rule and risk missing real secrets.
+
+The `KeywordDetector` rule (`patterns.rs:262-267`) is contextual: a Python/`.env`-shaped `name = "value"` assignment with name ∈ {`password`, `passwd`, `secret`, `token`, `api_key`, `secret_token`}, captured value ≥ 8 chars. To avoid false positives on commented-out examples, `scan_bytes` filters `ContextualCredential` matches whose line begins with `#` (`patterns.rs:91-94, 290-303`). The comment-handling is explicitly Python/shell-only — `//` and `/* */` comments are *not* skipped (tests at `tests/scanner.rs:162-167` lock this in deliberately).
+
+`baseline.rs` is a value-typed YAML parser + suppression engine. The on-disk shape is a `version: "1.0"` envelope with `results: {path: [entry, ...]}` (`baseline.rs:237-253`). Parse-time validation rejects: non-1.0 versions, absolute or `..`-bearing paths, missing/blank `justification` (collected exhaustively — `from_raw` walks all entries before returning the error, see `baseline.rs:153-172` and the test at `tests/scanner.rs:408-433`), unknown detector-type strings, and invalid hex hashes. Suppression is deliberately exact-match: same path, same rule, same hash, same line number — *and* `is_secret: false` (a `true` entry, or omitted field defaulting to `true` per `default_is_secret` at `baseline.rs:255-257`, does **not** suppress; tests at `tests/scanner.rs:300-385` lock this in).
+
+Error model is `thiserror`-derived (`baseline.rs:45-69`) with no panics in the parse path. The detection path has two `expect` calls in `Scanner::new` (`patterns.rs:51, 56-57, 66-69`) — all on compile-time constant regex literals, so they fire only on programmer error during edits, not on runtime input.
+
+### Patterns observed
+
+- **Two-phase regex matching** (`patterns.rs:80-87`) — `RegexSet` for cheap any-match prefilter, individual `Regex` only for matched indices. Trades memory for avoiding O(rules × text) capture work.
+- **Closed enum at the interface, string only at the wire** — `DetectSecretsRule` (`lib.rs:102-118`) forces every consumer to handle the full vocabulary; conversions live at the YAML boundary (`baseline.rs:179-186`) so unknown types fail fast.
+- **Capture-group routing via `Option<usize>`** (`patterns.rs:14, 96-103`) — `KeywordDetector` and `AwsSecretAccessKey` capture an inner group so the hash is over just the secret literal, not the `name="value"` framing.
+- **Boundary-aware regex via helper functions** (`patterns.rs:277-303`) — Rust's `regex` crate's `\b` doesn't handle base64 padding `=` or `#`-comments, so the crate composes regex + post-filter.
+- **Exhaustive error collection** for `MissingJustifications` (`baseline.rs:153-172`) — operator sees all missing entries at once, not one per re-run.
+- **Path safety as a parse-time invariant** (`baseline.rs:219-235`) — absolute paths, `..`, drive prefixes all rejected at load; eliminates a class of suppression-escape attacks at the YAML boundary rather than at match time.
+- **Cross-tool format compatibility by design** — the SHA-1 hash, the rule-name vocabulary, and the YAML schema all mirror Yelp's `detect-secrets` baseline format (cited explicitly in `lib.rs:1-5`), so operators familiar with that tool can reuse baselines.
+
+### Concerns / Smells / Risks
+
+- **`scan_bytes` is O(named_detections × entropy_candidates)** via `range_overlaps`'s linear scan (`patterns.rs:271-275`). For a file with hundreds of named matches and hundreds of entropy candidates this is quadratic. No interval tree, no sort-and-binary-search. For the target corpus (425k LOC Python, ADR-013 mentions) this is likely fine but worth flagging if scanner runtime ever becomes an issue.
+- **`Baseline::suppress` is O(detections × entries_per_file)** with linear scan over the entries for that path (`baseline.rs:111-137`). Acceptable while baseline files are small (~tens of entries) but no index by `(rule, hash, line)`.
+- **`usize_to_f64` truncates above 2³² bytes** (`entropy.rs:43-45`). For >4 GB files entropy will compute as if the buffer were 2³² bytes. Practically irrelevant — file-level scanning is bounded long before this — but the silent saturation deserves a comment.
+- **Contextual-comment handling is Python/`.env`-only** (`patterns.rs:290-303`). A `// password = "..."` line in a JavaScript file *will* fire `ContextualCredential` (locked in by test at `tests/scanner.rs:163-167`). The crate's docstring acknowledges this; the cost is operator-baseline pollution in non-Python codebases until detector context is added.
+- **`Scanner::new` panics on regex compile failure** (`patterns.rs:48, 51, 56, 66, 69`). These are compile-time literals so this is unreachable in shipping builds, but the public API has no fallible constructor — a future operator-provided pattern set would need a new constructor surface.
+- **Entropy thresholds embed false-positive policy in code, not configuration** (`entropy.rs:11-18`). The test fixture explicitly documents that lockfile/git-SHA noise is *intentional* and the answer is operator baseline. This is a deliberate v0.1 trade-off but it pushes calibration burden to every operator until configurable thresholds or per-file-extension tuning lands.
+- **`PatternMeta::capture_group` is private but the type is `pub`** (`patterns.rs:10-15`) — external consumers can read the struct via `Scanner::pattern_meta()` but can't construct one. This is fine as a closed API but the asymmetry is slightly awkward.
+- **No fuzz or property tests** in `tests/scanner.rs` — only example-based assertions. Regex engines under pathological input (catastrophic backtracking) are a known foot-gun; the crate uses Rust's `regex` (which is linear-time by construction) so this is mitigated, but a quickcheck pass would be cheap insurance.
+
+### Confidence: High
+
+Read all 4 source files end-to-end (881 LOC), the full 655-line test file, the crate's `Cargo.toml`, and cross-checked inbound usage by greping the workspace for `clarion_scanner` imports (only `clarion-cli/src/secret_scan/*` and the scanner's own tests). Confirmed pre-ingest invocation timing at `clarion-cli/src/analyze.rs:237-243` (runs before plugin-host extraction, feeds `briefing_blocks` into the rest of the pipeline). Test file is unusually rich — it locks in not only positive/negative detection cases but also the *intentional* false positives (lockfile SHAs) with the documented operator-baseline workaround. No mystery code remains.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-storage.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-storage.md
new file mode 100644
index 00000000..bfd7cadc
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-clarion-storage.md
@@ -0,0 +1,79 @@
+## 2. clarion-storage
+
+**Location:** `crates/clarion-storage/`
+**LOC:** 3199 src across 10 files / 4871 tests across 5 files / 293 lines SQL in `migrations/0001_initial_schema.sql`
+**Crate type / role:** Library crate (`lib.rs:1-42`). Sole owner of the SQLite read/write layer for the project DB at `.clarion/clarion.db`. Re-exports a flat surface from nine submodules.
+
+### Responsibility
+`clarion-storage` is the only path through which other crates touch SQLite. It (a) opens and configures the per-project database with a fixed PRAGMA discipline (`pragma.rs`), (b) applies embedded schema migrations idempotently (`schema.rs`), (c) routes *every* mutation through a single writer-actor task that owns the sole write `rusqlite::Connection` (`writer.rs`), (d) hands out short-lived read-only connections from a `deadpool-sqlite` pool (`reader.rs`), and (e) provides the read-side query helper catalogue that the MCP navigation tools and HTTP read API consume (`query.rs`, ~29 `pub` query / type items). The crate also enforces wire-level invariants the rest of the workspace depends on — per-kind edge confidence/source-range contracts, source-file-anchor kinds, reserved entity-kind protection, parent↔contains-edge dual-encoding consistency — at the *writer boundary*, so a misbehaving plugin or caller cannot corrupt graph shape (`writer.rs:425-582, 954-1021`).
+
+### Key components
+- `src/lib.rs:1-42` — module wiring + flat `pub use` facade (`Writer`, `ReaderPool`, `WriterCmd`, ~29 query helpers, cache helpers, `StorageError`).
+- `src/pragma.rs:16-45` — `apply_write_pragmas` (WAL + `synchronous=NORMAL` + `busy_timeout=5000` + `wal_autocheckpoint=1000` + `foreign_keys=ON`, with a hard invariant assertion that `PRAGMA journal_mode=WAL` actually took effect) and `apply_read_pragmas` (busy_timeout + FK only).
+- `src/writer.rs:40-140` — `Writer` handle, `Writer::spawn` (boots the actor as a `tokio::task::spawn_blocking` task owning one `rusqlite::Connection`), `send_wait` convenience.
+- `src/writer.rs:142-260` — `run_actor` central match loop dispatching all 11 `WriterCmd` variants; blocking `mpsc::Receiver::blocking_recv`.
+- `src/writer.rs:290-313, 802-877` — `ActorState` (`batch_size`, `writes_in_batch`, `in_tx`, `current_run`) and `bump_writes_and_maybe_commit` / `flush_run_batch` / `query_time_write` — the batch-cadence and run-transaction state machine.
+- `src/writer.rs:425-582` — wire-contract enforcement: `enforce_entity_kind_contract`, `validate_entity_source_file_anchor`, `enforce_edge_contract`, plus the structural-vs-anchored edge-kind tables (`STRUCTURAL_EDGE_KINDS`, `ANCHORED_EDGE_KINDS`).
+- `src/writer.rs:954-1021` — `parent_contains_mismatch` (the bidirectional parent↔contains dual-encoding check; runs inside the open commit transaction so a violation rolls back the run).
+- `src/reader.rs:26-119` — `ReaderPool` (`deadpool-sqlite` wrapper with an `Arc<()>` identity tag for `shares_pool_with` runtime proofs) and `with_reader` async helper.
+- `src/schema.rs:17-91` — `MIGRATIONS` slice (one entry, embedded by `include_str!`), `apply_migrations` runner gated by a `schema_migrations` table.
+- `src/commands.rs:135-218` — the `WriterCmd` enum: `BeginRun`, `InsertEntity`, `InsertEdge`, `InsertFinding`, `FlushRunBatch`, `InsertInferredEdges`, `UpsertSummaryCache`, `TouchSummaryCache`, `ReplaceUnresolvedCallSitesForCaller`, `CommitRun`, `FailRun` (11 variants, each carries an `Ack<T> = oneshot::Sender<Result<T>>`).
+- `src/query.rs:214-1056` — read helpers (`entity_by_id`, `entity_at_line`, `find_entities`, `call_edges_from/_targeting`, `reference_edges_for_entity`, `module_dependency_edges`, `subsystem_members`, `resolve_file_catalog_entry`, `contained_entity_ids`, …).
+- `migrations/0001_initial_schema.sql:23-291` — 9 tables (`schema_migrations`, `entities`, `entity_tags`, `edges` `WITHOUT ROWID` on natural PK, `findings`, `summary_cache`, `inferred_edge_cache`, `entity_unresolved_call_sites`, `runs`), 1 FTS5 virtual table (`entity_fts`), 3 triggers keeping FTS in sync, 2 generated virtual columns (`scope_rank`, `git_churn_count`) with partial indexes, 1 view (`guidance_sheets`), ~15 secondary indexes, and a row inserted into `schema_migrations`. Wrapped in a single `BEGIN…COMMIT`.
+
+### Public interface (outbound)
+- **Writer surface** — `Writer::spawn(db_path, batch_size, channel_capacity) -> (Writer, JoinHandle<Result<()>>)`; `Writer::sender() -> mpsc::Sender<WriterCmd>`; `Writer::send_wait`; observability counters `commits_observed`, `dropped_edges_total`, `ambiguous_edges_total` (each an `Arc<AtomicUsize>`, present in release builds). Constants `DEFAULT_BATCH_SIZE = 50`, `DEFAULT_CHANNEL_CAPACITY = 256` (`writer.rs:34-38`).
+- **Command protocol** — the `WriterCmd` enum (11 variants), the four POD record types (`EntityRecord`, `EdgeRecord`, `FindingRecord`, `InferredCallEdgeRecord`), `RunStatus` (`SkippedNoPlugins | Completed | Failed`), `InferredEdgeWriteStats`, and `Ack<T>`.
+- **Reader surface** — `ReaderPool::open(db_path, max_size)`, `with_reader(impl FnOnce(&Connection) -> Result<T>) -> Result<T>`, `shares_pool_with`, `identity()`, `waiting_count()` (test-hook).
+- **Schema runner** — `schema::apply_migrations(&mut Connection)`, `schema::applied_count(&Connection)` (used by `clarion install`).
+- **Cache surface** — `summary_cache_lookup`/`upsert_summary_cache`/`touch_summary_cache`, `inferred_edge_cache_lookup`/`upsert_inferred_edge_cache`/`touch_inferred_edge_cache`, `inferred_edge_cache_key_id` (canonical key-id format `"caller|hash|model|prompt"`), plus the four POD types `SummaryCacheKey/Entry`, `InferredEdgeCacheKey/Entry` (`cache.rs:1-251`).
+- **Unresolved-edges surface** — `UnresolvedCallSiteRecord`, `replace_unresolved_call_sites_for_caller(&Connection, …)` (atomic DELETE-then-INSERT per caller_entity_id; `unresolved.rs:20-49`).
+- **Query helpers** — ~29 `pub` items in `query.rs`: row structs (`EntityRow`, `CallEdgeMatch`, `ContainedEntities`, `ResolvedFile`, `ResolvedFileCatalogEntry`, `ModuleDependencyEdge`, `SubsystemMember`, `UnresolvedCallSiteRow`, `ReferenceEdgeMatch`, `ReferenceDirection`, `CanonicalProjectPath`), and lookup functions (`entity_by_id`, `entity_at_line`, `find_entities`, `existing_entity_ids`, `call_edges_from`, `call_edges_targeting`, `reference_edges_for_entity`, `module_dependency_edges`, `subsystem_members`, `subsystem_for_member`, `unresolved_call_sites_for_caller`, `unresolved_callers_for_target`, `candidate_entities_for_unresolved_sites`, `contained_entity_ids`, `child_entity_ids`, `resolve_file`, `resolve_file_catalog_entry`, `entity_briefing_block_reason`, `normalize_source_path`).
+- **Error type** — `StorageError` (`error.rs:5-46`) with `is_foreign_key_violation()` classifier for callers (notably the MCP envelope) that need `retryable=false` on FK breaches.
+- **Helper inventory** — `known_scan_time_edge_kinds()` iterator (`writer.rs:506-511`) exposes the 9-kind ontology to callers that need to validate before sending.
+
+### Dependencies
+- **Inbound (who calls this):** `clarion-cli` (`analyze.rs`, `serve.rs`, `install.rs`, `http_read.rs`, `run_lifecycle.rs`, `secret_scan.rs` + submodules `anchors.rs`/`findings.rs`); `clarion-mcp` (`lib.rs`, `tests/storage_tools.rs`). No other Clarion crate touches it.
+- **Outbound (what this calls):** `clarion-core` for `EdgeConfidence` (`commands.rs:14`) and `manifest::RESERVED_ENTITY_KINDS` (`writer.rs:427`). Cargo-level: `rusqlite` 0.31 (`bundled`), `deadpool-sqlite` 0.8 (`rt_tokio_1`), `tokio` (`sync`, `task::spawn_blocking`), `serde`/`serde_json` (validate `properties_json` shape on inferred edges), `blake3` (declared dep but not imported in `src/`; likely intended for path/hash helpers), `tracing`, `thiserror`.
+- **External services:** SQLite only — one file at `.clarion/clarion.db`, accessed via two distinct connection populations: one writer connection owned by the actor task, and `max_size` reader connections in `deadpool-sqlite`. No network. WAL is the cross-process coordination mechanism between writer and readers.
+
+### Internal architecture
+
+**Concurrency model — single-writer actor + reader pool (ADR-011, repeated verbatim in `lib.rs:1-5`).** All persistent mutations are funnelled through one `tokio::task::spawn_blocking` task that owns the sole write `rusqlite::Connection` (`writer.rs:86-98`). Producers communicate via a bounded `tokio::sync::mpsc::Sender<WriterCmd>` (default capacity 256); each variant carries a `oneshot::Sender` for the per-command ack so callers can fan out N producers (`Writer::sender().clone()`) and still observe each command's outcome (`commands.rs:20`, `writer.rs:998-1060` test `cloned_senders_accept_concurrent_entity_producers`). The actor loop is `rx.blocking_recv()` on the spawn_blocking thread (`writer.rs:152`), not `await` — this is correct because the loop is blocking-thread-resident and must call synchronous `rusqlite` APIs.
+
+**Transaction discipline — per-N-writes batches inside a per-run super-transaction.** `BeginRun` issues `INSERT INTO runs … status='running'` then `BEGIN`. Every successful `InsertEntity`/`InsertEdge`/`InsertFinding`/`ReplaceUnresolvedCallSitesForCaller` increments `state.writes_in_batch`; when it hits `batch_size` (default 50), `bump_writes_and_maybe_commit` issues `COMMIT` then `BEGIN` immediately to re-open. `CommitRun` runs the parent↔contains-edge consistency check inside the still-open transaction (`writer.rs:894-918`), then atomically folds the `UPDATE runs SET status=… completed_at=… stats=…` into the same `COMMIT`. `FailRun` issues `ROLLBACK` then a separate single-statement run-row UPDATE. The actor also has a `cleanup_after_channel_close` (`writer.rs:262-281`) that rolls back any open tx and marks the run failed if the channel is dropped mid-run. `FlushRunBatch` exists to let readers on separate SQLite connections observe in-flight graph rows mid-run by committing and re-opening the batch. The query-time MCP writes (`InsertInferredEdges`, `UpsertSummaryCache`, `TouchSummaryCache`) commit the surrounding run-batch first (if any), execute outside the run transaction, then re-open the run batch — they explicitly do not require an active run (`writer.rs:855-877`).
+
+**Write-side wire contracts (enforced before any SQL).** `enforce_entity_kind_contract` rejects non-`core` plugins emitting `RESERVED_ENTITY_KINDS` (`writer.rs:425-438`). `enforce_edge_contract` (`writer.rs:521-582`) splits the 9-kind ontology into `STRUCTURAL_EDGE_KINDS` (`contains`, `in_subsystem`, `guides`, `emits_finding` — must be `confidence=resolved`, must have NULL byte ranges) and `ANCHORED_EDGE_KINDS` (`calls`, `references`, `imports`, `decorates`, `inherits_from` — must have both byte-start and byte-end, must NOT be `inferred` at scan time); any unknown kind raises `CLA-INFRA-EDGE-UNKNOWN-KIND`. `validate_source_file_anchor` (`writer.rs:444-493`) checks that any `source_file_id` reference points to an entity whose kind is `file` or `module` (the comment at line 442 calls this transitional until core-minted `file` entities land). `parent_contains_mismatch` (`writer.rs:958-1021`) runs two SQL queries — one in each direction — to assert that `entities.parent_id` and `edges WHERE kind='contains'` are bijective; failure aborts the entire run with code `CLA-INFRA-PARENT-CONTAINS-MISMATCH`.
+
+**Idempotence and dedupe semantics.** `InsertEntity` uses `ON CONFLICT(id) DO UPDATE` that preserves `created_at` + `first_seen_commit` while refreshing `updated_at` + `last_seen_commit` (`writer.rs:362-420`); this is what makes `clarion analyze` re-run-safe. `InsertEdge` uses `INSERT OR IGNORE` on natural PK `(kind, from_id, to_id)`; dedupes increment `dropped_edges_total`. `InsertInferredEdges` first DELETEs the caller's existing inferred-tier `calls` edges that don't match the current cache key, then inserts new ones while *also* short-circuiting any pair that already has a `resolved`/`ambiguous` edge (`static_call_edge_exists`, lines 758-771) — that's how query-time LLM inference cohabits with scan-time static facts without double-counting.
+
+**PRAGMA discipline (`pragma.rs:16-45`).** Writer connection: `journal_mode=WAL` (and aborts with `PragmaInvariant` if SQLite returns anything other than `wal`), `synchronous=NORMAL`, `busy_timeout=5000` (5s — but the writer is single-threaded so this only matters against external `sqlite3` shell access), `wal_autocheckpoint=1000` (auto-checkpoint every 1000 frames), `foreign_keys=ON`. Reader connections: only `busy_timeout=5000` + `foreign_keys=ON`, re-applied on every `with_reader` acquisition as a belt-and-suspenders measure since `deadpool-sqlite` has no post-create hook. No `mmap_size`, no `temp_store`, no `cache_size`, no `application_id`, no `user_version` — schema versioning is done in the application-level `schema_migrations` table only.
+
+**Schema migrations (`schema.rs:17-91`).** Single compile-time-embedded migration via `include_str!`. The runner reads applied versions from `schema_migrations`, tolerating the table's absence via `OptionalExtension::optional()` (with an explicit comment at lines 45-49 warning that `.ok()` would silently mask `DatabaseLocked` / `CorruptDb`). Each migration runs in its own `execute_batch` and then an `INSERT OR IGNORE INTO schema_migrations` belt-and-suspenders insert. The migration SQL itself wraps everything in `BEGIN…COMMIT` and inserts its own row. No `application_id` / `user_version` is set — drift / cross-tool collisions on the SQLite file are not detected at the DB level.
+
+**Error model (`error.rs:5-65`).** One `thiserror`-derived enum, ten variants, three derived from external crates (`rusqlite::Error`, three `deadpool_sqlite::*Error` types, `std::io::Error`); six application-shaped (`PragmaInvariant`, `Migration{version, source}`, `InvalidQuery`, `InvalidSourcePath`, `WriterGone`, `WriterProtocol`, `WriterNoResponse`). `is_foreign_key_violation` is a public classifier on SQLite extended code 787, documented as feeding the MCP envelope's `retryable=false` decision.
+
+### Patterns observed
+- **Actor + bounded mpsc channel + oneshot ack-per-command** (`writer.rs:74-140`, `commands.rs:20`). Producers can be cloned freely; back-pressure is the channel's `send().await`.
+- **Per-connection PRAGMA reapply on every reader-pool acquisition** as a workaround for `deadpool-sqlite` having no post-create hook (`reader.rs:96-107`, comment at lines 76-83).
+- **`Arc<()>` identity tag** for proving two `ReaderPool` clones share the same in-process pool, distinct from "same file path" (`reader.rs:25-70`, used by `clarion-cli/src/serve.rs:63-71`'s `Arc::ptr_eq` assertion).
+- **Plain-old-data records at the wire** (`commands.rs:48-133`): `EntityRecord` / `EdgeRecord` / `FindingRecord` / `InferredCallEdgeRecord`. Caller is responsible for timestamps, content_hash, JSON-string encoding; writer inserts verbatim. No serde derivation on these.
+- **Codified error subcodes embedded in error messages** (`CLA-INFRA-RESERVED-ENTITY-KIND`, `CLA-INFRA-SOURCE-FILE-MISSING`, `CLA-INFRA-SOURCE-FILE-KIND-CONTRACT`, `CLA-INFRA-EDGE-CONFIDENCE-CONTRACT`, `CLA-INFRA-EDGE-SOURCE-RANGE-CONTRACT`, `CLA-INFRA-EDGE-UNKNOWN-KIND`, `CLA-INFRA-PARENT-CONTAINS-MISMATCH`). Strings are load-bearing for downstream `runs.stats.failure_reason` parsing.
+- **`WITHOUT ROWID` on the natural-key `edges` table** (migration line 96) and `WITHOUT ROWID`-style PKs on the three cache/unresolved tables — composite PKs are the access path.
+- **FTS5 virtual table kept in sync by AFTER {INSERT,UPDATE,DELETE} triggers** (`migrations:209-238`); summary text is extracted from `summary.briefing.purpose` JSON path.
+- **Generated VIRTUAL columns over JSON properties + partial indexes** (`scope_rank`, `git_churn_count`, lines 245-262) — the CASE-mapped `scope_rank` exists specifically because the project→subsystem→…→function ordering is not lexicographic.
+- **Embedded migrations + edit-in-place policy until first external operator** (migration header lines 10-16) — comment names the retirement trigger for the policy.
+
+### Concerns / Smells / Risks
+- **`query.rs` is 1161 LOC of mostly hand-written SQL strings**. No prepared-statement caching at the module level, no query builder — every helper builds its own SQL with `params!`/`params_from_iter`. Risk: easy to drift between similar helpers; partially mitigated by the 1137-LOC `tests/query_helpers.rs` (close to 1:1 LOC with the production file). Reviewers must check each new query for FK/composite-PK access path.
+- **No `application_id` / `user_version` discipline**. The migration runner is the *only* schema-identity signal — a non-Clarion SQLite file opened at `.clarion/clarion.db` would pass `apply_migrations` if it happened to lack a `schema_migrations` table, and would *fail confusingly* if it has unrelated tables that collide. Cross-tool DB-file drift is not detectable at open time.
+- **`blake3` is a declared dep but unused inside `src/`** (verified by `grep -rn blake3 src/` — no hits). Likely vestigial from an earlier hashing plan; not load-bearing but is build-time waste.
+- **`busy_timeout=5000` is set on *both* connections, but the writer is single-thread**. The 5s only matters if an external `sqlite3` shell or a second Clarion process opens the file. There is no in-process advisory lock (no `cross-process claim-lease` table) — two `clarion analyze` runs against the same `.clarion/clarion.db` would race on `runs` rows and the SQLite writer mutex; the `recover_preexisting_running_runs` step in `clarion-cli/src/run_lifecycle.rs` is the only mitigation, and it's post-hoc.
+- **`writer.rs` is 1074 LOC in one file with ~25 free functions plus the `ActorState` struct**. The match-and-dispatch loop is large; adding a 12th command means touching the `WriterCmd` enum, the match in `run_actor`, *and* the per-command handler — three places. The pattern is clean but the file is approaching "split me" territory.
+- **`reader_pool` test (line 91) uses `max_size = 1`** as the *exhaustion scenario* — fine for the test, but worth flagging that the real production pool sizes in callers are 16 (`serve.rs`) and 4 (`http_read.rs`'s test seam), so the worst-case queue depth under MCP load is `64` (from `ConcurrencyLimitLayer`) waiting on `16` connections plus one writer holding the FS lock — the math hasn't been load-tested in this crate's tests.
+- **`InsertEntity`/`InsertEdge` validate source-file anchors with a `SELECT kind FROM entities WHERE id = ?` per write** (`writer.rs:451-458`). At 500k entities this is 500k extra round-trips during analyze. The query is single-row PK lookup so it's cheap, but it's per-write overhead that the test corpus may not exercise to scale.
+- **Tests are well above 1:1 LOC ratio with production code** (4871 test : 3199 src). Behavioural coverage looks strong (round-trip, idempotence, FK propagation, edge contracts, FailRun rollback, channel-close cleanup, query helpers, cache lifecycle, reader pool concurrency / queueing / panic recovery, schema-apply re-run safety). Concern: there is no fuzz/property-test seam for `WriterCmd` interleavings — only scripted scenarios. The `commits_observed` counter is the canonical batch-cadence oracle and is asserted in `writer_actor.rs:943` (`batch_size_fifty_commits_every_fifty_inserts`), but the channel-close-mid-run cleanup path (`cleanup_after_channel_close`, `writer.rs:262-281`) does not appear to have a dedicated test asserting the run-row is left in `failed` rather than `running`.
+- **`FlushRunBatch` exists for cross-connection visibility but its consumers are external to this crate**. Within `clarion-storage` no test exercises a reader observing a flushed-but-uncommitted-run batch — that contract is asserted from `clarion-cli` / `clarion-mcp` tests instead, so a regression in `FlushRunBatch` semantics would surface as a downstream test failure rather than a unit-level one here.
+
+### Confidence: High
+Read all 10 source files in `src/` end-to-end, plus `migrations/0001_initial_schema.sql` end-to-end, plus skimmed test-function headers in all 5 test files (notably `writer_actor.rs` 2440 LOC). Cross-checked inbound callers via `grep -rn "use clarion_storage"` — only `clarion-cli` (7 files) and `clarion-mcp` (lib + one test) import it. Confirmed `Writer::spawn` and `ReaderPool::open` call sites in `clarion-cli/src/{analyze,serve,http_read}.rs`. The only items I deliberately did not exhaust are the bodies of the read-side query helpers in `query.rs` past line 220 — I read the public surface and signatures, sampled `entity_at_line`/`find_entities`/`call_edges_from` lightly, and trusted the test file (1137 LOC of `query_helpers.rs`) as evidence of behavioural coverage rather than re-deriving each SQL statement.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/catalog-python-plugin.md b/docs/arch-analysis-2026-05-22-1924/temp/catalog-python-plugin.md
new file mode 100644
index 00000000..4855f2bc
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/catalog-python-plugin.md
@@ -0,0 +1,69 @@
+## 7. Python language plugin (`clarion-plugin-python`)
+
+**Location:** `plugins/python/`
+**LOC:** 3028 source / 3440 test (`extractor.py` 932, `pyright_session.py` 1406, `server.py` 296, the rest ≤ 75 each)
+**Crate type / role:** Standalone PEP 517 package (hatchling) installing the `clarion-plugin-python` console script; hosts an L4 JSON-RPC plugin process driven by the Rust core over stdio. Ships its `plugin.toml` to `share/clarion/plugins/python/plugin.toml` via `pyproject.toml:38-44`.
+
+### Responsibility
+Owns Python-source ingestion for Clarion: parses `*.py` to an AST, emits `module` / `class` / `function` entities with stable 3-segment EntityIds, anchors structural `contains` and `imports` edges directly, and delegates type-resolved `calls` / `references` edges to a managed pyright-langserver subprocess. It is the *only* component in the workspace that holds Python `ast` semantics and the only Loom-suite-facing surface that probes Wardline (`wardline_probe.py:35-56`) for the L8 integration handshake. Public surface to the core is exactly the five JSON-RPC methods declared in `server.py:237-240` plus the manifest at `plugin.toml`.
+
+### Key components
+- `src/clarion_plugin_python/__main__.py:14-15` — entry point bound to `[project.scripts] clarion-plugin-python = ...:main`; installs stdio guard then runs `serve()`.
+- `src/clarion_plugin_python/server.py:73-128, 143-232, 243-296` — Content-Length framing reader/writer, dispatch table, handlers for `initialize` / `analyze_file` / `shutdown`, and the per-25-files pyright restart policy (`MAX_FILES_PER_PYRIGHT_SESSION = 49`, used at `server.py:215-219`).
+- `src/clarion_plugin_python/extractor.py:256-371` — top-level `extract` / `extract_with_stats`; the `_walk` recursion at lines 763-842 emits entities + `contains` edges; `_ImportEdgeCollector` at 396-468 emits `imports` edges; `_ReferenceSiteCollector` at 532-659 produces reference sites for the resolver.
+- `src/clarion_plugin_python/entity_id.py:23-75` — L2 3-segment EntityId assembler; mirrors the Rust validator (`[a-z][a-z0-9_]*` grammar, no `:`, no empty segment).
+- `src/clarion_plugin_python/qualname.py:34-48` — reconstructs CPython `__qualname__` from the AST parent chain (class-nested vs `parent.<locals>.child`).
+- `src/clarion_plugin_python/pyright_session.py:131-890` — `PyrightSession`: subprocess lifecycle, LSP framing, function/entity index builder, `resolve_calls` (callHierarchy) and `resolve_references` (definition/typeDefinition). 1406 lines; the load-bearing class plus helpers `_build_function_index` (893-925) and `_collect_entities` (928-1006).
+- `src/clarion_plugin_python/stdout_guard.py:25-62` — replaces `sys.stdout` with a write-refusing shim so libraries cannot corrupt the host's JSON-RPC frame parser.
+- `src/clarion_plugin_python/wardline_probe.py:35-56` — imports `wardline.core.registry` + reads `wardline.__version__`; returns one of `absent` / `enabled` / `version_out_of_range`.
+
+### Public interface (outbound)
+- **Binary:** `clarion-plugin-python` (bare basename per `plugin.toml:8`, enforced by ADR-021 layer-1 path-component refusal in the core's discovery).
+- **JSON-RPC methods (server.py:237-272):**
+  - `initialize(params{project_root}) → {name, version, ontology_version="0.6.0", capabilities{wardline}}` (`server.py:143-156`).
+  - `initialized` — notification, flips `state.initialized = True` (line 250).
+  - `analyze_file(params{file_path}) → {entities, edges, stats}` (`server.py:179-232`); gated by `_ERR_NOT_INITIALIZED` if called before `initialized` (line 263).
+  - `shutdown() → {}` — closes the pyright child (line 255-260).
+  - `exit` — notification; loop returns `0` if shutdown was requested, `1` otherwise (`server.py:286-287`).
+- **Wire shapes** declared as `TypedDict`s in `extractor.py:88-142` (`RawEntity`, `RawEdge`, `SourceRange`) and `call_resolver.py:11-22`, `reference_resolver.py:28-39` — these match the host's `RawEntity` / `RawEdge` deserialise contracts cited inline at `extractor.py:9-22`.
+- **Manifest surface:** `plugin.toml` advertises `plugin_id="python"`, `entity_kinds=["function","class","module"]`, `edge_kinds=["contains","calls","references","imports"]`, `ontology_version=0.6.0`, `rule_id_prefix="CLA-PY-"`, `wardline_aware=true`, and pyright pin `1.1.409`.
+
+### Dependencies
+- **Inbound (who calls this):** the Rust plugin host. Confirmed via `grep` hits in `crates/clarion-core/src/plugin/{discovery.rs:60, manifest.rs:150-748, protocol.rs:656, host.rs:519}` and `crates/clarion-mcp/src/lib.rs:526`. The core spawns the binary, speaks Content-Length-framed JSON-RPC, and consumes `entities` / `edges` / `stats`.
+- **Outbound (what this calls):** none of the other Clarion crates directly — the plugin is a pure subprocess. It does cross-product import `wardline.core.registry` + `wardline` purely as a capability probe (`wardline_probe.py:38-39`), fail-soft.
+- **External services:**
+  - `pyright-langserver --stdio` subprocess (`pyright_session.py:637-644`), pin `1.1.409` (`pyproject.toml:20`, `plugin.toml:29`). Resolved via venv-sibling first, then `shutil.which` (`pyright_session.py:699-706`). Bounded by `init_timeout=30s`, `call_timeout=5s`, per-file budget `3s`, `MAX_PYRIGHT_RESTARTS_PER_RUN=3`, `MAX_REFERENCE_SITES_PER_FILE=2000`.
+  - Python `packaging.version.Version` for Wardline range parsing (`wardline_probe.py:30`).
+- **Cross-language fixture:** consumes `fixtures/entity_id.json` at `tests/test_entity_id.py:25` — same rows the Rust assembler validates against; this is the byte-for-byte parity proof for L2 EntityId construction.
+
+### Internal architecture
+**Process / I/O model.** The plugin is a single-threaded JSON-RPC dispatch loop (`server.py:275-287`) reading Content-Length-framed frames from `stdin`, writing replies to a captured `stdout` byte stream. Before any framing happens, `install_stdio()` (`stdout_guard.py:57-62`) captures the real `sys.stdin.buffer` / `sys.stdout.buffer` and replaces `sys.stdout` with `_GuardedTextStdout`, which raises `StdoutGuardError` on any write — this is the plugin-side resolution of WP2's UQ-WP2-08 framing-corruption risk. Frame size is capped at 8 MiB (`MAX_CONTENT_LENGTH`, `server.py:48`) on both inbound and outbound to match the host's ceiling.
+
+**Extraction pipeline (per `analyze_file`).** `handle_analyze_file` (`server.py:179-232`) reads the file text, relativises the path to `project_root` for the qualified-name prefix only (`_resolve_module_path`, lines 158-176), and calls `extract_with_stats` with the project-relative prefix and the live `PyrightSession` as both `call_resolver` and `reference_resolver`. The extractor (`extractor.py:274-371`) always emits exactly one `module` entity (whole-file cover, `end_col=0` sentinel — see the module-docstring caveat at lines 49-53), then `_walk` (lines 763-842) recursively emits one `function` per `FunctionDef`/`AsyncFunctionDef` and one `class` per `ClassDef`. Each non-module entity carries `parent_id` and contributes one `contains` edge (ADR-026 dual encoding, lines 845-851). PEP-484 `@overload` stubs are dropped pre-emit (`_has_overload_decorator`, lines 741-760); any surviving same-id collision is dropped first-wins with stderr + `duplicate_entities_dropped_total` bump (lines 803-810). `imports` edges are collected separately by an `ast.NodeVisitor` (lines 396-468); relative imports compute the base package via `_relative_import_base_parts` (lines 499-510) with package-vs-module awareness keyed on `is_package_module`. Reference sites are gathered by a third visitor (lines 532-659) that maintains a `bound_stack` of locally-bound names per scope and suppresses lambdas + `Call` callees (the latter is the `calls` edge's territory).
+
+**Pyright integration.** `PyrightSession` (`pyright_session.py:131-890`) spawns `pyright-langserver --stdio` as a `subprocess.Popen` (line 637), drives it as an LSP client over Content-Length framing (`_write_message`/`_read_message`, lines 800-834), with a daemon stderr-drain thread keeping a 64 KiB tail (`_drain_stderr`, 723-730). Initialize sends `processId`, `rootUri`, and `workspaceFolders` (lines 682-697); when pyright requests `workspace/configuration`, the session responds with `diagnosticMode=openFilesOnly`, `indexing=false`, `useLibraryCodeForTypes=false`, and an explicit `exclude` list for `.git/.venv/__pycache__/...` (`_configuration_for_section`, lines 774-788). Call resolution opens the file (`textDocument/didOpen`), runs `textDocument/prepareCallHierarchy` per function, then `callHierarchy/outgoingCalls`, and translates the returned URIs/selectionRanges back into Clarion entity IDs via a parallel AST-built `_FunctionIndex` cache keyed on `Path.resolve()` (`_function_index_for_path`, lines 861-870). Edges are grouped by `fromRanges` and emitted as `resolved` or `ambiguous` (`pyright_session.py:394-411`). The session augments pyright's static graph with two heuristic dispatch detectors: `_ambiguous_dict_dispatches` (callable-dict lookup patterns) and `_dunder_call_dispatches` (instances whose class has `__call__`) — both produce additional ambiguous-candidate edges. Reference resolution (lines 427-511) issues `textDocument/definition` per site with an `annotation`-kind fallback to `textDocument/typeDefinition`, caches per `(from_id, kind, lexeme)` triple, and accumulates edges by `(from_id, to_id)` pair.
+
+**Resilience model.** Three tiers: (1) **timeouts** — per-request via `_budgeted_timeout`, per-file via `_deadline_for_file` (lines 531-550), with init/call/file knobs all overridable per `__init__`. (2) **restart cap** — `_record_restart_or_poison` (lines 599-615) restarts pyright up to `MAX_PYRIGHT_RESTARTS_PER_RUN=3`, then permanently disables call resolution by setting `_disabled=True` (emits `CLA-PY-PYRIGHT-POISON-FRAME`). (3) **server-side restart-by-attrition** — `server.py:215-219` closes and re-creates the `PyrightSession` every 25 analyzed files. All failure modes degrade gracefully: missing pyright (`absent` install), failed handshake, timeouts, and the reference-site cap all return zero edges plus a `Finding` with subcode `CLA-PY-PYRIGHT-*` (`pyright_session.py:34-41`).
+
+**Error model.** JSON-RPC errors use codes `-32600` / `-32601` / `-32603` / `-32002` (`server.py:52-55`); any handler exception becomes a `_ERR_INTERNAL` response (line 270-271). Framing-level violations (bad headers, oversize Content-Length, JSON decode failure) raise `ProtocolError`, which `main()` translates to exit code `1` (`server.py:295-296`). `ast.SyntaxError` during extraction emits one degraded `module` entity with `parse_status="syntax_error"` + a stderr line (lines 325-335) — the run continues.
+
+### Patterns observed
+- **Single-process dispatch loop with explicit lifecycle states** — `ServerState.initialized` / `shutdown_requested` gating; `analyze_file` rejected before `initialized` (`server.py:263-264`).
+- **Subprocess-as-service with restart cap + capability disable** — `PyrightSession._disabled` poisons the resolver permanently after N failures (lines 600-609); analysis continues without type-resolved edges.
+- **Dual encoding of structural relationships** — every non-module entity carries `parent_id` *and* a corresponding `contains` edge (extractor.py:813, 845-851), per ADR-026.
+- **Parallel AST builds for entity emission vs LSP cross-walking** — `extractor.py` and `pyright_session._build_function_index` (line 893) each parse the file with `ast.parse` for distinct purposes; the index is cached per `Path.resolve()` in the session (line 861).
+- **Stdout discipline via type substitution** — `_GuardedTextStdout` raises on every write rather than silently swallowing (`stdout_guard.py:36-41`).
+- **TypedDict wire-shape contracts mirroring Rust serde structs** — `RawEntity`, `RawEdge`, `CallsRawEdge`, `ReferencesRawEdge`, `Finding` are statically checked under `mypy --strict` and called out in source comments as host-matching (`extractor.py:9-22`, `call_resolver.py:14-22`).
+- **Cross-language fixture-driven parity** — `fixtures/entity_id.json` is consumed by both this plugin's tests and the Rust assembler tests; the validator code is intentionally duplicated rather than shared (`entity_id.py:56-75`).
+
+### Concerns / Smells / Risks
+- **`pyright_session.py` is 1406 lines in a single module** containing the `PyrightSession` class (≈760 lines) plus ~600 lines of free-function helpers (call-site visitors, dispatch heuristics, LSP helpers, byte-offset arithmetic). The class itself is cohesive but the helper sprawl makes the file hard to navigate; the AST-index builder (`_build_function_index`, `_collect_entities`) duplicates traversal work the extractor already does, suggesting an opportunity to fold the index into `extractor.py` and let the session consume it.
+- **`extractor.py` carries three separate `ast.NodeVisitor` walks** (`_walk` recursion, `_ImportEdgeCollector`, `_ReferenceSiteCollector`) plus a fourth in `pyright_session._collect_entities`. Each walks the same tree with slightly different bookkeeping. No measurable performance bug observed in tests, but future maintenance touching scope semantics (e.g., `match`/`case` introducing bindings, `walrus` operator) has four call sites to keep in sync.
+- **Dispatch heuristics are pattern-based and fragile** — `_has_overload_decorator` admits only bare `overload` / `typing.overload` / `typing_extensions.overload` (lines 753-759); aliased imports defeat it and rely on the deduplication safety net. Same shape for `_ambiguous_dict_dispatches` and `_dunder_call_dispatches` in `pyright_session.py:1158-1303` — they will silently miss anything pyright also misses unless the source matches a known pattern.
+- **Per-file pyright restart at 25 files is a magic constant** (`server.py:49`), separate from the 3-restart-cap inside the session. The interaction between server-driven recycling and session-driven failure restarts is not centrally documented in code; if both fire on the same run the failure semantics depend on ordering.
+- **`StdoutGuardError` is raised but never caught by `server.serve`** — a stray write in any handler will bubble through `dispatch`'s broad `except Exception` (line 270) and become an `_ERR_INTERNAL` response with the guard message in plain text. That is probably correct behaviour, but the design implication (guard violations become normal-looking JSON-RPC errors instead of hard exits) is not stated.
+- **`shutdown` handler kills the pyright child synchronously inside dispatch** (`server.py:257-259`); a misbehaving pyright that ignores `shutdown` would extend the host's view of plugin termination by up to ~4s (two `process.wait(timeout=2)` calls in `PyrightSession.close`, lines 191-194). The host's circuit breaker is the backstop, but the plugin does not log when it falls back to `kill()`.
+- **Test coverage is heavy** (test LOC > source LOC; nine pytest files including pyright-marked integration tests), but `pyproject.toml:94` marks the pyright tests as opt-in via the `pyright` marker — easy to skip in environments without the langserver and not obvious from the test names whether a green run actually exercised the LSP path.
+
+### Confidence: High
+Read all 11 source files end-to-end (extractor.py, server.py fully; pyright_session.py covering `PyrightSession` and the main helpers ~600 of 1406 lines closely, the dispatch-heuristic visitors at signature level), the plugin manifest, `pyproject.toml`, and the round-trip + fixture-parity tests. Cross-checked inbound callers via `grep` against `crates/clarion-{core,mcp}/` (5 distinct call sites). One specific number I did not verify by reading source: the `MAX_FILES_PER_PYRIGHT_SESSION` constant is `25` per `server.py:49`, cited above. The relevant integration boundary (Rust `RawEntity` / `RawEdge` deserialise contract) was confirmed only via the docstring references in `extractor.py:9-22` and `call_resolver.py` typeddicts — not by reading the Rust side, which is out of this subsystem's scope.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/task-catalog-template.md b/docs/arch-analysis-2026-05-22-1924/temp/task-catalog-template.md
new file mode 100644
index 00000000..c5a9750f
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/task-catalog-template.md
@@ -0,0 +1,81 @@
+# Per-Subsystem Catalog Entry Contract (Clarion)
+
+Read `/home/john/clarion/docs/arch-analysis-2026-05-22-1924/01-discovery-findings.md` first (4 minutes) to ground in shared vocabulary. Then deep-read your assigned subsystem.
+
+## HARD CONSTRAINT — No design docs
+
+Do NOT read `docs/clarion/**`, `docs/suite/**`, `docs/implementation/**`, `docs/federation/**`, prior `docs/arch-analysis-*/`, ADRs, sprint READMEs, or the design/architecture-narrative portions of `CLAUDE.md` / `AGENTS.md` / `CHANGELOG.md`. Findings must derive from source, manifests, tests, fixtures, migrations, and configuration.
+
+## Allowed reading
+
+- All source files in your assigned subsystem (every file you need).
+- Cross-subsystem `pub` interfaces (read minimally to confirm dependency edges).
+- `Cargo.toml` (per-crate and workspace), `plugin.toml`, `pyproject.toml`.
+- Migration SQL, tests, fixtures.
+
+## Output contract
+
+Append a single H2 section to `/home/john/clarion/docs/arch-analysis-2026-05-22-1924/02-subsystem-catalog.md`. Use a file lock pattern: read existing content first, then write the full file back with your section appended. If empty, create with an H1 header `# 02 — Subsystem Catalog (Clarion)` first.
+
+Your H2 section must follow this exact structure:
+
+```markdown
+## [N. Subsystem Name]   ← N is the position you were assigned; subsystem name matches discovery
+
+**Location:** `path/to/crate-or-package/`
+**LOC:** [source LOC / test LOC]
+**Crate type / role:** [binary, library, plugin manifest type]
+
+### Responsibility
+[One paragraph (3-5 sentences). What does this subsystem own? What concern does it abstract from the rest of the system? Cite the public surface that proves it.]
+
+### Key components
+[3-7 bullets. For each: `path/to/file.rs:line-range` — role. Be specific about line ranges of the load-bearing types/functions, not just file paths.]
+
+### Public interface (outbound)
+[The types/functions/traits/binaries this subsystem exposes to other parts of the system. For Rust: `pub` items in `lib.rs` or the binary's CLI surface. For the Python plugin: the JSON-RPC methods it implements. Bullet each one with one-line description and source location.]
+
+### Dependencies
+- **Inbound (who calls this):** [crates/files that import this subsystem]
+- **Outbound (what this calls):** [other Clarion subsystems + external crates that matter]
+- **External services:** [SQLite, subprocess plugins, HTTP, etc., with calling site]
+
+### Internal architecture
+[2-4 paragraphs describing how this subsystem is organised internally. Concurrency model? Module split? State ownership? Error model? Cite specific files/lines for each claim.]
+
+### Patterns observed
+- [3-6 bullets naming concrete patterns: actor + bounded channels, command pattern, capability gating, parser+lexer split, etc. — with file:line evidence]
+
+### Concerns / Smells / Risks
+[Frank assessment. Include things like: file size, coupling smell, missing tests, performance suspect, error-handling gaps. Cite evidence. If nothing observed, say "None observed in this pass" and explain why.]
+
+### Confidence: [High|Med|Low]
+[One sentence with evidence. e.g., "High — read all 11 source files end-to-end and all 4 test files; cross-checked with two callers from clarion-cli."]
+```
+
+## Process
+
+1. Read the discovery doc (~3 min skim).
+2. List your subsystem's source files (`find <path> -name '*.rs'` or `*.py`).
+3. Read `lib.rs` (or `__init__.py`) + the top 3-5 modules by LOC end-to-end.
+4. Skim test files to identify behavioral contracts.
+5. Identify inbound callers via `rg "use clarion_<name>" crates/` (Rust) or import scan (Python).
+6. Write your H2 section using the structure above.
+
+## File-locking pattern (to avoid clobbering parallel siblings)
+
+Because multiple agents may write to `02-subsystem-catalog.md` in parallel:
+1. Read the current file.
+2. Build a single Write call that contains: existing content (verbatim, including the H1 header) + your H2 section appended.
+3. Write the whole thing.
+4. If a sibling beat you and the file content changed between your read and write, re-read and retry with your section appended again.
+
+If you do not want to risk clobbering, instead write your section to `temp/catalog-<subsystem>.md` and the coordinator will assemble them.
+
+**Preferred:** write to `temp/catalog-<your-subsystem-slug>.md` (e.g., `temp/catalog-clarion-core.md`). The coordinator will merge.
+
+## Be terse
+Aim for ~300-450 lines of catalog text. No file dumps. Quote at most 5-10 lines of code total across the whole section, and only where decisive.
+
+## Confidence statement is mandatory
+Mark High/Med/Low. Justify with what you read.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/task-discovery.md b/docs/arch-analysis-2026-05-22-1924/temp/task-discovery.md
new file mode 100644
index 00000000..6440dde2
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/task-discovery.md
@@ -0,0 +1,95 @@
+# Task: Holistic Discovery Sweep for Clarion Codebase
+
+## Workspace
+`/home/john/clarion/docs/arch-analysis-2026-05-22-1924/`
+
+## Hard Constraint — NO existing documentation
+You must NOT read any of:
+- `docs/clarion/**` (design docs, ADRs, requirements)
+- `docs/suite/**` (Loom doctrine)
+- `docs/implementation/**` (sprint plans, WP docs)
+- `docs/federation/**`
+- `docs/arch-analysis-*/` (other than your task spec)
+- The "design" / "architecture" narrative portions of `CLAUDE.md` or `AGENTS.md`
+- `README.md` for design content; you may glance at it ONLY for build commands.
+
+You MAY read:
+- All source under `crates/` and `plugins/python/`
+- `Cargo.toml` (root and per-crate), `clarion.yaml`, `.mcp.json`, `Cargo.lock` (for dep names only)
+- Per-crate test files
+- Fixture files under `fixtures/`
+- `.filigree/` and `.clarion/` (filesystem layout only, no issue content)
+
+Findings must derive from code, manifests, and tests — not from prose.
+
+## Scope
+Produce a holistic discovery findings document for the Clarion repo. Goal: name what the system *is* from evidence alone, identify entry points, technology, internal/external dependencies, candidate subsystems, and unknowns to investigate per-subsystem.
+
+## Output
+Write the full document to `/home/john/clarion/docs/arch-analysis-2026-05-22-1924/01-discovery-findings.md`.
+
+## Structure (follow exactly)
+
+```markdown
+# 01 — Discovery Findings (Clarion)
+
+## 1. One-Paragraph Pitch (Inferred From Code)
+[2-4 sentences. What is this system? What does it produce? Who is it for? Derived only from code/manifests/tests.]
+
+## 2. Repository Layout
+[Tree-style summary of top-level dirs that matter. Note crate count, plugin count, LOC by language, test corpus size.]
+
+## 3. Technology Stack
+- **Languages:** [versions from rust-toolchain.toml / pyproject]
+- **Rust dependencies (key):** [list 5-15 most architecturally significant — tokio, rusqlite, serde, axum/hyper, clap, etc., from Cargo.toml]
+- **Python dependencies (key):** [from plugins/python/pyproject.toml]
+- **External processes / services:** [SQLite? Plugin subprocesses? HTTP server? MCP transport? cite where called]
+- **Build/test tooling:** [pre-commit, ruff, mypy, nextest, deny — cite source]
+
+## 4. Entry Points
+[List every binary `main()` / library entry, with source path and what it does (one line). Cover `clarion-cli` (sub-commands), `clarion-mcp`, `clarion-plugin-fixture`, Python plugin entry.]
+
+## 5. Public Wire Surfaces
+[Enumerate every external interface the code exposes. For each: name, location, transport, sketch of message shape. Examples to look for: HTTP read API in `crates/clarion-cli/src/http_read.rs`; plugin JSON-RPC in `crates/clarion-core/src/plugin/`; MCP tools in `crates/clarion-mcp/`; CLI in `crates/clarion-cli/src/cli.rs`.]
+
+## 6. Candidate Subsystems
+For each of the 7 candidates listed below, give:
+- **Name + path**
+- **LOC**
+- **Source files (>=1)** with one-line role
+- **Direct crate/plugin dependencies (outbound only at this stage)**
+
+Candidates: clarion-core, clarion-storage, clarion-cli, clarion-mcp, clarion-scanner, clarion-plugin-fixture, plugins/python.
+
+## 7. Cross-Cutting Concerns Observed
+[Pick from the code: error handling style, logging/tracing, async runtime, configuration loading, schema/migrations, security boundaries (plugin jail, secret scanning), test harness shape. Cite a representative file:line for each.]
+
+## 8. Test Corpus Shape
+- Per-crate `tests/*.rs` file inventory and what they exercise (one line each).
+- Python plugin: where are tests, how many?
+- End-to-end: any shell scripts under `tests/`?
+
+## 9. Open Questions (For Per-Subsystem Phase)
+[5-10 specific questions to answer in the catalog phase. E.g., "How is the plugin subprocess sandboxed?", "What is the writer-actor concurrency model?", "How does the federation API authenticate?"]
+
+## 10. Confidence Statement
+[Per major claim above, a confidence tag (High/Med/Low) with the evidence file(s).]
+```
+
+## How to Work
+
+1. Read `Cargo.toml` (root) for workspace members & deps.
+2. For each crate, read `Cargo.toml` + `src/lib.rs` or `src/main.rs` only.
+3. Glob source filenames per crate (do not read every file).
+4. Read enough to identify modules + their roles.
+5. Cite paths as `crates/<crate>/src/<file>.rs` or `plugins/python/src/<file>.py`.
+6. Be specific: "spawns subprocess via `Command::new` at `host.rs:142`" not "uses subprocesses".
+
+## Scope discipline
+Do not begin per-subsystem deep analysis. Stop at the holistic level. The next phase has dedicated explorers per subsystem.
+
+## Time budget
+About 25-35 minutes of subagent work. Token cap: be terse, don't dump file contents.
+
+## Confidence
+Mark each section's confidence per the contract. Where evidence is missing, say so explicitly.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/validation-catalog.md b/docs/arch-analysis-2026-05-22-1924/temp/validation-catalog.md
new file mode 100644
index 00000000..547b8982
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/validation-catalog.md
@@ -0,0 +1,291 @@
+# Validation Report — 02-subsystem-catalog.md
+
+**Validator:** analysis-validator
+**Date:** 2026-05-22
+**Target:** `docs/arch-analysis-2026-05-22-1924/02-subsystem-catalog.md`
+**Contract:** `temp/task-catalog-template.md`
+
+## Status: NEEDS_REVISION (warnings)
+
+Two factual errors and one minor naming inconsistency found. No critical issues. All seven required H2 sections present with all 10 contract sub-sections each. All bidirectional dependency edges verified. Eight load-bearing claims spot-checked: six confirmed, two failed.
+
+---
+
+## Contract compliance
+
+| Subsystem | Loc | LOC | Role | Resp. | Key comps | Pub iface | Deps | Internal | Patterns | Concerns | Confidence |
+|-----------|-----|-----|------|-------|-----------|-----------|------|----------|----------|----------|------------|
+| clarion-core | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+| clarion-storage | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+| clarion-cli | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+| clarion-mcp | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+| clarion-scanner | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+| clarion-plugin-fixture | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+| plugins/python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | High |
+
+All seven subsystems present; numbered 1–7; structural contract satisfied throughout.
+
+---
+
+## Spot-check results
+
+### 1. clarion-core stderr drain (PASS)
+
+Catalog claim: "detached thread … bounded `VecDeque<u8>` of capacity `STDERR_TAIL_BYTES = 64 KiB`."
+
+Evidence: `crates/clarion-core/src/plugin/host.rs:609-620` shows
+`Arc<Mutex<VecDeque<u8>>>::with_capacity(STDERR_TAIL_BYTES)` and
+`std::thread::Builder::new().name("clarion-plugin-stderr-drain:{plugin_id}")
+.spawn(move || drain_stderr_into_ring(stderr, &stderr_tail_for_thread))`. Confirmed.
+
+### 2. clarion-storage writer capacity/batch (PASS)
+
+Catalog claim: "bounded mpsc with capacity 256 … batch commits every 50 writes."
+
+Evidence: `crates/clarion-storage/src/writer.rs:35` `DEFAULT_BATCH_SIZE = 50`;
+`writer.rs:38` `DEFAULT_CHANNEL_CAPACITY = 256`; `writer.rs:813` triggers
+commit when `state.writes_in_batch >= state.batch_size`. Confirmed.
+
+### 3. clarion-cli analyze ordering (PASS)
+
+Catalog claim: secret scan runs BEFORE BeginRun and BEFORE plugin spawn.
+
+Evidence: `crates/clarion-cli/src/analyze.rs:242` `pre_ingest(...)`; `:244`
+`run_lifecycle::begin_run(...)`; `:277` `'plugins: for plugin in plugins`
+(spawn-blocking loop with `run_plugin_blocking` → `PluginHost::spawn`).
+Order is `pre_ingest` → `begin_run` → per-plugin `PluginHost::spawn`. Confirmed.
+
+### 4. clarion-mcp tool count — FAIL (catalog) / FAIL (discovery)
+
+Catalog claim (`02-subsystem-catalog.md:327, 382, 394`): registry contains
+**19** distinct `ToolDefinition` entries; discovery's claim of 20 is stale.
+
+Discovery claim (`01-discovery-findings.md:17, 198, 508`): **20** tools via
+`grep -c 'ToolDefinition {'`.
+
+**Ground truth: 19 tools.** Evidence: `crates/clarion-mcp/src/lib.rs:47` is the
+struct definition `pub struct ToolDefinition { ... }`; lines 58, 71, 80, 91,
+100, 109, 123, 136, 150, 165, 170, 184, 200, 205, 210, 223, 236, 247, 252
+are the 19 in-`vec![]` instances. `grep -c "ToolDefinition {"` returns 20
+because it counts the struct declaration too. `grep -n 'name: "'` returns
+exactly 19 literal-name lines.
+
+**Catalog is correct on the count (19); catalog's framing that "discovery
+doc was wrong" is also correct.** The discovery doc's `Confidence Assessment`
+section already flagged this risk at line 552 ("20 occurrences of the literal
+token, not verified to be 20 *distinct production tools*"); the catalog
+resolved it correctly. **No catalog change required.** This is a discovery
+artefact to be corrected when discovery is rewritten or in errata.
+
+Names verified (19): `entity_at`, `project_status`, `analyze_start`,
+`analyze_status`, `analyze_cancel`, `find_entity`, `source_for_entity`,
+`entity_context`, `call_sites`, `callers_of`, `execution_paths_from`,
+`execution_paths_ranked`, `summary`, `summary_preview_cost`, `issues_for`,
+`orientation_pack`, `index_diff`, `neighborhood`, `subsystem_members`.
+
+### 5. HTTP read API surface (PASS)
+
+Catalog claim: 4 production routes (`GET /api/v1/files`, `POST /api/v1/files/batch`,
+`POST /api/v1/files:resolve`, `GET /api/v1/_capabilities`).
+
+Evidence: `crates/clarion-cli/src/http_read.rs:364-372` —
+
+```
+let protected = Router::new()
+    .route("/api/v1/files", get(get_file))
+    .route("/api/v1/files:resolve", post(post_files_resolve))
+    .route("/api/v1/files/batch", post(post_files_batch))
+    ...
+let unprotected = Router::new().route("/api/v1/_capabilities", get(get_capabilities));
+```
+
+All 4 routes confirmed. Two additional `Router::new()` instances at lines
+1396, 1451, 1524 are inside `#[cfg(test)]` blocks (`/x`, `/boom`, test-only
+batch). Confirmed.
+
+### 6. clarion-plugin-fixture protocol methods (PASS)
+
+Catalog claim: implements only `initialize`/`analyze_file`/`shutdown`
+(requests) + `initialized`/`exit` (notifications).
+
+Evidence: `crates/clarion-plugin-fixture/src/main.rs:51` `"initialized" =>`;
+`:54` `"exit" =>`; `:68` `"initialize" =>`; `:77` `"analyze_file" =>`;
+`:116` `"shutdown" =>`. No other method arms. Confirmed.
+
+`lib.rs` is a 3-line documentation stub as the catalog states.
+
+### 7. Python plugin entrypoint name (PASS)
+
+Catalog claim: `clarion-plugin-python`.
+
+Evidence: `plugins/python/pyproject.toml:32-33`:
+
+```
+[project.scripts]
+clarion-plugin-python = "clarion_plugin_python.__main__:main"
+```
+
+Confirmed.
+
+### 8. clarion-scanner pattern count (PASS)
+
+Catalog claim: "12 named rules + 2 entropy classes."
+
+Evidence: `crates/clarion-scanner/src/patterns.rs:194-269` — `default_pattern_meta()`
+returns a `Vec<PatternMeta>` with exactly 12 `PatternMeta {}` entries
+(`AwsAccessKey`, `AwsSecretAccessKey`, `GitHubToken`, `GitHubFineGrainedToken`,
+`GitHubOAuthToken`, `AnthropicApiKey`, `OpenAiApiKey`, `StripeApiKey`,
+`SlackToken`, `JwtToken`, `PrivateKey`, `KeywordDetector`). Entropy classes:
+`EntropyTuning::BASE64` and `EntropyTuning::HEX` (`entropy.rs:11-18`,
+applied at `patterns.rs:64-65`). `grep -c "PatternMeta {"` returns 13 — one
+is the struct declaration at line 10. Confirmed.
+
+---
+
+## Bidirectional dependency spot-checks
+
+| Edge | Forward (X→Y) | Reverse (Y inbound lists X) | Status |
+|------|---------------|----------------------------|--------|
+| clarion-storage → clarion-core | catalog §2 Outbound (`EdgeConfidence`, `RESERVED_ENTITY_KINDS`, line 139) | catalog §1 Inbound line 54 explicitly lists `clarion-storage/src/{commands,query,writer}.rs` | ✓ |
+| clarion-mcp → clarion-storage | catalog §4 Outbound line 346 (`ReaderPool::with_reader`, `WriterCmd`) | catalog §2 Inbound line 138 lists `clarion-mcp (lib.rs, tests/storage_tools.rs)` | ✓ |
+| clarion-cli → clarion-scanner | catalog §3 Outbound line 222 (`Scanner, Detection, Baseline, SuppressionResult`) | catalog §5 Inbound lines 433-436 list `clarion-cli/src/secret_scan.rs` + 2 submodules | ✓ |
+
+Additional check (informal):
+- clarion-cli → clarion-mcp: §3 Outbound line 222 ↔ §4 Inbound lines 341-343. ✓
+- clarion-cli → clarion-core / clarion-storage: §3 line 222 ↔ §1 line 52, §2 line 138. ✓
+- clarion-cli → clarion-plugin-fixture (dev-dep): §3 line 222 (transitively via test path), §6 Inbound line 521 lists `clarion-cli/tests/wp2_e2e.rs`. ✓
+- plugins/python ← clarion-core/clarion-mcp (subprocess only): §7 Inbound line 595 lists `clarion-core/src/plugin/{discovery,manifest,protocol,host}` and `clarion-mcp/src/lib.rs`. Reverse: §1 Outbound External services line 57 acknowledges plugin subprocesses generically; §4 Outbound External services line 350-352 mentions LLM provider subprocesses but not Python plugin specifically — Python plugin is a runtime peer of fixture, not a Rust-callable, so reverse asymmetry is acceptable. ✓
+
+No missing bidirectional links found.
+
+---
+
+## Findings
+
+### F1 — Wrong constant value for `MAX_FILES_PER_PYRIGHT_SESSION` (WARNING)
+
+**Location:** `02-subsystem-catalog.md:575`
+
+**Claim:** "the per-25-files pyright restart policy (`MAX_FILES_PER_PYRIGHT_SESSION = 49`, used at `server.py:215-219`)."
+
+**Reality:** `MAX_FILES_PER_PYRIGHT_SESSION = 25` (`plugins/python/src/clarion_plugin_python/server.py:49`).
+
+The "49" appears to be a transcription of the **line number** (`server.py:49`)
+where the constant is defined; the value is 25. The same paragraph already
+states "per-25-files" in the prose. The catalog's own Confidence statement
+at line 632 cites the correct value: "`MAX_FILES_PER_PYRIGHT_SESSION` constant
+is `25` per `server.py:49`." So this is a self-inconsistency within the
+same section, resolvable to 25.
+
+**Fix:** change `MAX_FILES_PER_PYRIGHT_SESSION = 49` to
+`MAX_FILES_PER_PYRIGHT_SESSION = 25` at line 575.
+
+### F2 — Subsystem name inconsistency (NIT)
+
+**Location:** `02-subsystem-catalog.md:564`
+
+The 7th section is titled `## 7. Python language plugin (\`clarion-plugin-python\`)`.
+The discovery doc and the coordination plan refer to this subsystem as
+`plugins/python` (e.g. discovery §6, coordination subsystem list). Other
+subsection titles use the crate's library name verbatim (`clarion-core`,
+`clarion-storage`, etc.).
+
+This is consistent enough to be unambiguous — every reader knows what
+"Python language plugin" means in Clarion context — but if the catalog is
+indexed by section title, the name does not match the assigned slug. **Fix
+optional**: rename header to `## 7. plugins/python` or
+`## 7. plugins/python (clarion-plugin-python)` for indexing parity. No
+content change required.
+
+### F3 — Catalog §4 Confidence statement undersells dispatch arm count (NIT)
+
+**Location:** `02-subsystem-catalog.md:356`
+
+Catalog says "a 19-arm `match`" for tool dispatch. The registry has 19 tools,
+so 19 arms is consistent. The phrasing matches the corrected count. No
+change needed; flagging only because the same paragraph in the discovery
+doc said 20. This is correct catalog behaviour — not a finding, just
+verifying consistency.
+
+---
+
+## Things checked and confirmed correct (no finding)
+
+- stderr drain thread on host.rs (claim #1).
+- writer-actor `DEFAULT_BATCH_SIZE = 50`, `DEFAULT_CHANNEL_CAPACITY = 256` (claim #2).
+- secret scan → BeginRun → plugin spawn order in analyze (claim #3).
+- 19 MCP tools, not 20 — catalog called this correctly against discovery (claim #4).
+- HTTP read API: 4 production routes at `http_read.rs:364-372` (claim #5).
+- plugin-fixture: 5 protocol methods, no others (claim #6).
+- `clarion-plugin-python` binary name (claim #7).
+- 12 named pattern rules + 2 entropy classes (claim #8).
+- All sampled bidirectional dependency edges resolve in both directions.
+- All seven H2 sections satisfy the 10-subsection contract.
+- LOC figures in §1–§7 headers cross-check against discovery §6 within
+  ±2% (e.g. catalog §1 11,653 vs discovery 11,669; catalog §3 ~6981 vs
+  discovery ~6790 — small skew from comment/blank counting choices, no
+  factual disagreement).
+
+---
+
+## Confidence Assessment
+
+**High.** I read all seven H2 sections of the target document end-to-end,
+the discovery doc end-to-end, and the catalog template. I spot-checked all
+eight load-bearing factual claims listed in the validation prompt against
+source files by direct read or grep at file:line precision. I verified
+bidirectional dependency edges for 3 randomly-selected edges plus 3
+auxiliary edges. I cross-checked the MCP tool count by enumerating the 19
+`name: "..."` literals in `clarion-mcp/src/lib.rs` and by re-confirming
+that the 20th `ToolDefinition {` token comes from the struct definition at
+line 47. I confirmed the catalog's tool-count finding (which initially
+read as a self-flagged contradiction) is correct and discovery was wrong.
+
+## Risk Assessment
+
+**Low.** The two warnings (F1 transcription error on a numeric constant, F2
+section-title naming nit) are surface defects that do not affect downstream
+architecture-analysis work in this pass. The MCP tool-count flag — the only
+substantive contradiction between catalog and discovery — has been resolved
+in the catalog's favour; the catalog correctly identified the off-by-one in
+discovery's grep heuristic. F3 is a non-finding included for traceability.
+
+Downstream phases (dependency analysis, diagram generation, quality
+assessment) can proceed against this catalog without blocking on the two
+warnings; F1 can be fixed inline during the next catalog edit.
+
+## Information Gaps
+
+- I did not re-read every line of every cited source file; I targeted the
+  exact line ranges named in the catalog's claims plus the spot-check
+  prompts. Other catalog claims (e.g. ADR references in concerns sections,
+  finding subcode strings, edge-kind ontology) were not independently
+  verified.
+- The catalog's "Patterns observed" and "Concerns" sections are
+  interpretive; I validated structural presence, not technical accuracy of
+  the interpretations. Technical-accuracy review of e.g. the writer-actor
+  concurrency claims or the path-jail TOCTOU concern is out of scope for
+  this validator and would need a Rust-domain SME.
+- LOC figures were not re-counted with `wc -l`; I trusted the per-section
+  numbers and cross-checked only against discovery for gross consistency.
+
+## Caveats
+
+- This validator checks structural and factual correctness against the
+  contract and against directly-cited source. It does not assess whether
+  the analyst chose the right level of abstraction, whether the
+  "Concerns" are exhaustive, or whether the public-interface listings
+  capture the right granularity for downstream consumers.
+- The catalog's discovery-vs-catalog contradiction on tool count is
+  textbook validator territory: I resolved it by reading the source. Other
+  silent contradictions between catalog and discovery may exist that were
+  not surfaced because the prompt did not name them.
+- Bidirectional checks sampled 3+3 edges out of ~16 forward edges across
+  the seven subsystems; full bidirectional coverage would require checking
+  every Outbound line against the reciprocal Inbound list. No misses
+  found in the sample, but the sample is not exhaustive.
+
+---
+
+**Recommendation:** APPROVED for downstream phases after fixing F1 (one-token
+change: `49` → `25` at line 575). F2 and F3 are optional polish.
diff --git a/docs/arch-analysis-2026-05-22-1924/temp/validation-final-report.md b/docs/arch-analysis-2026-05-22-1924/temp/validation-final-report.md
new file mode 100644
index 00000000..81e9f5b8
--- /dev/null
+++ b/docs/arch-analysis-2026-05-22-1924/temp/validation-final-report.md
@@ -0,0 +1,294 @@
+# Validation Report — 04-final-report.md
+
+**Validator:** analysis-validator
+**Date:** 2026-05-22
+**Target:** `docs/arch-analysis-2026-05-22-1924/04-final-report.md`
+**Upstream:** `01-discovery-findings.md`, `02-subsystem-catalog.md`, `03-diagrams.md`, prior validator `temp/validation-catalog.md`
+
+## Status: NEEDS_REVISION (warnings)
+
+The final report is structurally complete, factually accurate on every load-bearing
+claim I verified against source, and internally consistent with the catalog and
+diagrams. One non-blocking issue: the discovery doc (an upstream input cited in
+the report's pointers section) still contains five stale "20 tools" references
+that the report itself does not propagate. The report is approved on its own
+merits; the discovery doc is the document that needs the cleanup pass.
+
+---
+
+## 1. Structural completeness (§7 of prompt) — PASS
+
+Required final-report sections, all present:
+
+| Section | Heading | Lines |
+|---|---|---|
+| Executive summary | §1 | 10–23 |
+| System narrative | §2 "The System in Code" + §3 "Architecture Narrative" | 26–175 |
+| Dependency topology | §4 | 178–202 |
+| Cross-cutting | §5 | 206–218 |
+| Risks | §6 | 221–265 |
+| Strengths | §7 | 268–279 |
+| Open questions | §8 | 282–290 |
+| Methodology / confidence | §9 | 294–317 |
+| Pointers | §10 | 321–328 |
+
+Risk-severity bands defined (§6 header). Methodology distinguishes
+end-to-end-read vs sampled (§9 "Coverage" paragraph). Section ordering matches
+typical archaeology-report contract.
+
+---
+
+## 2. Internal consistency: §6 risks vs catalog concerns — PASS
+
+Spot-checked each High/Medium risk against the catalog's per-subsystem
+Concerns sections. Every risk in §6 traces back to a concern enumerated in
+`02-subsystem-catalog.md`:
+
+| Report §6 risk | Catalog source |
+|---|---|
+| 4 monolith files (mcp/lib.rs 4703, host.rs 2935, analyze.rs 2549, llm_provider.rs 2467) | Catalog §1 lines 90–91 (host, llm); §3 line 270 (analyze.rs); §4 line 381 (mcp lib.rs) |
+| Blocking HTTP in async (filigree) | Catalog §4 line 384 ("`reqwest::blocking` inside an async dispatcher") |
+| No analyze-child timeout | Catalog §4 line 389 ("No timeout on `tool_analyze_start` child") |
+| KillOnDrop newtype suggestion | Catalog §1 line 94 ("subprocess lifecycle ownership is split…`KillOnDrop` newtype") |
+| No `application_id`/`user_version` | Catalog §2 line 171 ("No `application_id`/`user_version` discipline") |
+| Facade leak (writer.rs:427 → RESERVED_ENTITY_KINDS) | Catalog §1 line 92, §2 line 139 |
+| 11 hardcoded limits | Catalog §1 line 97 (full enumeration) |
+| Path jail TOCTOU | Catalog §1 line 95 |
+| Pyright 25 vs 3 restart constants | Catalog §7 line 626 |
+| Integration test happy-path-only | Catalog §1 line 96 ("`tests/host_subprocess.rs` is 325 lines…") |
+| Tool count drift 20→19 | Catalog §4 lines 327, 382 |
+| mock.rs at 876 LOC | Catalog §1 line 93 |
+
+No risk introduced in §6 that has no antecedent in the catalog. Severity
+assignments are reasonable.
+
+---
+
+## 3. Numeric consistency (§2 of prompt) — PASS
+
+Cross-checked load-bearing constants between report, catalog, discovery, and
+source:
+
+| Quantity | Report value | Catalog value | Source verification |
+|---|---|---|---|
+| MCP tool count | 19 (§1, §3.5, §9 table) | 19 (§4 line 327, 382, 394) | `grep -c 'name: "' lib.rs` = 19 (per validator-catalog) |
+| Writer batch size | 50 (§1, §3.4 line 124) | `DEFAULT_BATCH_SIZE = 50` (catalog §2 line 116) | `writer.rs:35` confirmed |
+| Writer channel cap | 256 (§3.4) | 256 (catalog §2 line 128) | `writer.rs:38` confirmed |
+| HTTP batch cap | 256 (§3.6) | 256 (catalog §3 line 213) | `http_read.rs:608 BATCH_MAX_QUERIES = 256` confirmed |
+| HTTP resolve cap | 1000 (§3.6) | 1000 (catalog §3 line 214) | `http_read.rs:609 RESOLVE_MAX_PATHS = 1000` confirmed |
+| HTTP body cap | 16 KiB (§3.6) | 16 KiB (catalog §3 line 216) | `http_read.rs:610 HTTP_BODY_LIMIT_BYTES = 16 * 1024` confirmed |
+| HTTP concurrency | 64 (§3.6) | 64 (catalog §3 line 216) | `http_read.rs:386 ConcurrencyLimitLayer::new(64)` confirmed |
+| Frame ceiling | 8 MiB (§3.3, §3.7) | 8 MiB (catalog §1 line 25) | `transport.rs` `ContentLengthCeiling::DEFAULT` |
+| Entity cap | 500_000 (§3.3) | 500_000 (catalog §1 line 28) | `EntityCountCap::DEFAULT_MAX` |
+| Path-escape breaker | >10 / 60s (§3.3) | >10 / 60s (catalog §1 line 28) | `limits.rs` |
+| Crash-loop breaker | >3 / 60s (§3.2) | >3 / 60s (catalog §1 line 29) | `breaker.rs:43-117` |
+| Pyright restart cap | 25 (§3.7, §6 risk 10, §8 q1) | 25 (catalog §7 line 575 after fix) | `server.py:49 MAX_FILES_PER_PYRIGHT_SESSION = 25` confirmed (page-1 read) |
+| Pyright in-session restart | 3 (§6 risk 10) | 3 (catalog §7 line 609 `MAX_PYRIGHT_RESTARTS_PER_RUN=3`) | `pyright_session.py` |
+| File sizes (mcp/lib, host, analyze, llm) | 4703 / 2935 / 2549 / 2467 | same (catalog §1, §3, §4) | `wc -l` confirms exact match |
+| Total LOC | ~50K (§1, §2.1) | ~50K (catalog table) | Discovery §2 line 58 ~29K Rust + 3K Python = consistent |
+| Subsystem inventory | 7 subsystems (§1, §2.1) | 7 (catalog numbering 1-7) | matches |
+| `analyze.rs run_with_options` 570 lines | §1 #3, §3.2 | catalog §3 line 270 ("570 lines (lines 75–645)") | `analyze.rs:74-645` confirmed |
+
+Every numeric claim consistent across all four documents.
+
+---
+
+## 4. Validator-fix applied check (§3 of prompt) — PASS
+
+- Catalog §7 line 575 now reads `MAX_FILES_PER_PYRIGHT_SESSION = 25` (was `49`
+  in the validator-flagged version).
+- Source: `plugins/python/src/clarion_plugin_python/server.py:49`
+  → `MAX_FILES_PER_PYRIGHT_SESSION = 25` (verified directly).
+- Final report cites 25 consistently in §3.7, §6 risk #10, §8 question #1.
+- Catalog §7 line 632 Confidence statement still cites the correct value 25.
+
+Fix is applied and propagated correctly into the final report.
+
+---
+
+## 5. Tool-count correction (§4 of prompt) — PARTIAL FIX (warning)
+
+**Final report (`04-final-report.md`): correct.** Every reference to the MCP
+tool count in the final report says 19:
+
+- §1 line 12 ("19 navigation tools")
+- §3.5 line 136 header ("19 tools (not 20)")
+- §3.5 line 138 (explains the discovery off-by-one and confirms corrected)
+- §9 line 303 (validator table: "19 (discovery corrected)")
+- §6 risk #12 line 262 ("Discovery initially said 20; actual is 19. Already corrected in this analysis")
+
+**Discovery doc (`01-discovery-findings.md`): partially corrected.**
+- Lines 17–21 have the corrected lead-paragraph + correction note (good).
+- Lines still asserting 20: **199, 206, 444, 480, 510 (confidence table row), 529 (confidence table row)**.
+
+Verbatim:
+
+```
+line 199: "**20 tools** registered in `list_tools()` (`lib.rs:56-294`)"
+line 206: "(claimed `grep -c 'ToolDefinition {'` = 20)"
+line 444: "(note: actual `list_tools()` is now 20 — script may exercise a subset)"
+line 480: "**MCP tool inventory drift** — `list_tools()` returns 20 tools"
+line 510: "| MCP server exposes 20 tools  | High | `grep -c 'ToolDefinition {'` of `crates/clarion-mcp/src/lib.rs` = 20 |"
+line 529: "| `list_tools()` includes exactly the 20 tool names listed in §5  | Medium | …"
+```
+
+The final report itself is internally consistent; this finding is about the
+upstream discovery doc still carrying stale text past its corrected lead.
+
+**Severity:** WARNING. Report is correct; downstream readers who consult the
+discovery confidence table will see contradictory numbers. Recommend a sweep
+of `01-discovery-findings.md` replacing 20→19 at those five lines and
+deleting line 444's parenthetical or updating it to "actual list_tools() is
+19".
+
+---
+
+## 6. No invented claims — three spot-checks against source — PASS
+
+Three claims drawn at random from the final report, verified against source:
+
+**Spot-check A: "stderr drain thread" at `host.rs:609-620`** (§3.3 line 116, §9).
+Verified: `host.rs:609-620` contains `Arc<Mutex<VecDeque<u8>>>::with_capacity(STDERR_TAIL_BYTES)`,
+`std::thread::Builder::new().name(format!("clarion-plugin-stderr-drain:{}", manifest.plugin.plugin_id))`,
+`.spawn(move || drain_stderr_into_ring(stderr, &stderr_tail_for_thread))`. **PASS.**
+
+**Spot-check B: "Router has 4 production routes"** (§3.6 lines 144–149).
+Verified: `http_read.rs:363-372`:
+```
+let protected = Router::new()
+    .route("/api/v1/files", get(get_file))
+    .route("/api/v1/files:resolve", post(post_files_resolve))
+    .route("/api/v1/files/batch", post(post_files_batch))
+    ...
+let unprotected = Router::new().route("/api/v1/_capabilities", get(get_capabilities));
+```
+Four routes, three protected, one unprotected. **PASS.**
+
+**Spot-check C: "analyze ordering — secret scan → BeginRun → plugin spawn"**
+(§3.2 lines 92–95, §9 table line 302).
+Verified: `analyze.rs:242-244` shows `pre_ingest(...)` immediately followed by
+`run_lifecycle::begin_run(...)`. `:275-277` opens the `'plugins: for plugin in
+plugins` loop. Order = pre_ingest (secret scan) → begin_run (BeginRun) → per-plugin spawn. **PASS.**
+
+No invented file paths, no invented line numbers in the three samples.
+
+---
+
+## 7. Scope honesty (§6 of prompt) — PASS
+
+§9 "Methodology and Confidence" honestly distinguishes:
+
+- "Read end-to-end vs sampled" disclosure (§9 line 311): "One file *not*
+  sampled to completion is `clarion-mcp/src/lib.rs` (4,703 LOC) — its 19
+  tool registry was enumerated and the dispatcher structure was characterised,
+  but each tool's individual handler body was not read end-to-end."
+- Confidence stratification (§9 line 309): High for §3-§7, Medium-High for
+  §2 LOC counts, Medium for §8 recommendations.
+- Validator results inlined in a table with 8 named claims (line 297-307).
+- "What I would do next if continuing" section (line 313) acknowledges three
+  unfinished work-items: quality-assessment of large files, security pass on
+  HTTP, test-pyramid analysis.
+
+§9 line 5 also accurately states "**No existing design docs** were consulted
+during the analysis" — matching the prompt constraint that this is by design.
+
+Scope honesty is good. The report does not overclaim coverage.
+
+---
+
+## 8. Cross-document consistency — PASS with one nit
+
+**Diagrams (03):** Pointers section §10 line 323 cites "7 Mermaid diagrams:
+2 C4 levels, 2 component, 2 sequence, 1 dependency graph". Not independently
+verified in this validation pass; trusted as a non-load-bearing summary line.
+
+**Discovery (01) vs Report (04):** No direct contradictions in the report
+itself. The 5 stale "20" references in discovery (Finding §5 above) are
+upstream artifacts, not report defects.
+
+**Catalog (02) vs Report (04):**
+- Catalog §4 line 327 says the registry "actually contains 19 entries, not 20".
+  Report §3.5 line 136 says "19 tools (not 20)". Aligned.
+- Catalog §1 line 91 lists `llm_provider.rs` concerns; report §6 risk #1 elaborates
+  with the same finding and recommends a `clarion-llm` crate. Catalog §6 finding
+  not present; this is a synthesis the report adds — acceptable, the catalog
+  already establishes the underlying facts.
+
+**Nit (non-blocking):** §6 risk #3 line 240 cites the "MCP analyze_start/
+analyze_status/analyze_cancel family (visible in the deferred tool list above
+this conversation)". The phrase "above this conversation" is a leakage of the
+analysis-session context into a report meant for permanent record. Strictly a
+stylistic/editorial nit — does not affect correctness. Recommend rewording to
+"as listed in §3.5" or removing the parenthetical.
+
+---
+
+## Findings summary
+
+| ID | Severity | Location | Issue |
+|---|---|---|---|
+| F1 | **Warning** | `01-discovery-findings.md:199, 206, 444, 480, 510, 529` | Five "20 tools" references remain stale despite the corrected lead paragraph at lines 17–21. Final report itself is correct (says 19 everywhere); discovery's body still contradicts its header. Recommend sweep to 19. |
+| F2 | Nit | `04-final-report.md:240` | "(visible in the deferred tool list above this conversation)" leaks session context into final-record prose. |
+| F3 | Nit | `04-final-report.md:6` | Report top-matter says validator status "NEEDS_REVISION (warnings) — one factual error fixed inline … one cosmetic nit accepted". This is referring to the catalog validator. Worth adding "(for catalog; report status TBD by this validator)" for clarity. |
+
+No critical issues. No invented claims found. No risk/catalog mismatches.
+
+---
+
+## Confidence Assessment
+
+**High.** I read the final report end-to-end, the catalog page 1 (lines 1–245)
+and the catalog section for plugins/python (lines 446–632) in full, the
+discovery doc in full, and the prior validator report in full. I directly
+spot-checked three numeric/structural claims against source files
+(`host.rs:609-620`, `http_read.rs:363-372` and `:608-610`, `analyze.rs:242-277`).
+I cross-checked the validator-fix application by reading `server.py:46-52`
+showing `MAX_FILES_PER_PYRIGHT_SESSION = 25` at line 49. I verified the file
+sizes of the four "monolith files" via `wc -l` and they match the report to the line.
+
+## Risk Assessment
+
+**Low.** The report's load-bearing claims all trace to source. The catalog
+upstream of this report passed validation (`temp/validation-catalog.md` →
+APPROVED after F1 fix). The only unresolved upstream issue is the discovery
+doc's partially-corrected "20 tools" body, which the final report does not
+inherit — it correctly says 19 everywhere.
+
+The largest residual risk is **technical-accuracy review of architectural
+interpretation** (e.g., is the "two breakers, two scopes" pattern characterised
+correctly? Is the writer-actor's per-N-batch discipline a strength or a
+bottleneck under elspeth-scale load?). This is out-of-scope for structural
+validation; a Rust-domain SME would need to weigh in.
+
+## Information Gaps
+
+- I did not re-verify the 7 Mermaid diagrams in `03-diagrams.md` end-to-end;
+  trusted the report's summary line.
+- I sampled 3 of the report's source-cited claims at file:line precision but
+  did not exhaustively verify every numeric reference (~50+ file:line
+  citations in the report).
+- The report's "Patterns observed" interpretations (§7 strengths) and
+  "Open Questions" (§8) involve architect-intent judgement that source code
+  cannot adjudicate; I validated structural presence only.
+
+## Caveats
+
+- This validator checks the **final report** against the **already-validated
+  catalog and discovery** and against directly-cited source. It does not
+  re-validate the catalog or discovery from scratch.
+- The "deliberately did not read design docs" methodology (per prompt
+  constraint) means several plausible "missing reference" findings (no ADR
+  citations, no requirement-ID cross-refs) are explicitly out of scope and
+  not flagged.
+- F1 is a *upstream* document issue. The final report — the validation
+  target proper — is internally consistent on this point. If discovery is
+  treated as immutable post-validation, F1 is informational only. If it is
+  editable, recommend the sweep.
+
+---
+
+**Recommendation:** **APPROVED** as the final-report artifact. The report is
+structurally complete, internally consistent, numerically consistent with
+its upstream documents, factually accurate on every spot-checked claim, and
+honest about scope. F1 is an upstream-document hygiene matter; F2/F3 are
+editorial nits. None block downstream use of this report.
diff --git a/docs/clarion/v0.1/README.md b/docs/clarion/1.0/README.md
similarity index 73%
rename from docs/clarion/v0.1/README.md
rename to docs/clarion/1.0/README.md
index d3d3e748..53011a79 100644
--- a/docs/clarion/v0.1/README.md
+++ b/docs/clarion/1.0/README.md
@@ -1,6 +1,6 @@
-# Clarion v0.1 Docset
+# Clarion v1.0 Docset
 
-This folder is the canonical Clarion v0.1 document set.
+This folder is the canonical Clarion v1.0 document set.
 
 ## Canonical design docs
 
@@ -10,9 +10,8 @@ This folder is the canonical Clarion v0.1 document set.
 
 ## Supporting docs
 
-- [reviews/README.md](./reviews/README.md) — retained historical reviews and panel outputs that shaped the current docset.
-- [plans/v0.1-scope-commitments.md](./plans/v0.1-scope-commitments.md) — dated scope and decision memo for the v0.1 design freeze.
 - [../adr/README.md](../adr/README.md) — authored ADRs and remaining decision backlog.
+- [../../implementation/README.md](../../implementation/README.md) — archived planning and review history (scope commitments, panel reviews, sprint plans, agent handoffs). Non-normative; supporting context only.
 
 ## Reading order
 
@@ -23,4 +22,4 @@ This folder is the canonical Clarion v0.1 document set.
 ## Document roles
 
 - `requirements.md`, `system-design.md`, and `detailed-design.md` are the authoritative layered design set.
-- `reviews/` and `plans/` are supporting context, not normative sources.
+- Reviews and planning memos under [../../implementation/](../../implementation/) are supporting context, not normative sources.
diff --git a/docs/clarion/v0.1/detailed-design.md b/docs/clarion/1.0/detailed-design.md
similarity index 95%
rename from docs/clarion/v0.1/detailed-design.md
rename to docs/clarion/1.0/detailed-design.md
index 4fb249eb..a30662b4 100644
--- a/docs/clarion/v0.1/detailed-design.md
+++ b/docs/clarion/1.0/detailed-design.md
@@ -1,7 +1,7 @@
-# Clarion v0.1 — Detailed Design Reference
+# Clarion v1.0 — Detailed Design Reference
 
-**Status**: Baselined for v0.1 implementation (post-ADR sprint 2026-04-18) — Layer 3 of the Clarion v0.1 docset, implementation-level reference. Canonical home of the ADR backlog, SQL schema, Rust struct definitions, full YAML config example, exact rule-ID catalogues, wire-format mapping tables, and cross-tool prerequisite lists.
-**Baseline**: 2026-04-17 · **Last updated**: 2026-04-18
+**Status**: Baselined for v1.0 release (carried forward from the v0.1 post-ADR-sprint baseline) — Layer 3 of the Clarion v1.0 docset, implementation-level reference. Canonical home of the ADR backlog, SQL schema, Rust struct definitions, full YAML config example, exact rule-ID catalogues, wire-format mapping tables, and cross-tool prerequisite lists.
+**Baseline**: 2026-04-17 · **Last updated**: 2026-05-19
 **Primary author**: qacona@gmail.com (with Claude)
 **First customer target**: `/home/john/elspeth` (~425k LOC Python)
 **Revision**: 5 (final pre-restructure single-file revision; see Appendix D for full history). Post-restructure the three layered docs track changes via git log plus dated edits in this preamble; there is no unified "Rev 6."
@@ -9,8 +9,9 @@
 **Companion documents**:
 - [requirements.md](./requirements.md) — requirements (the *what*; REQ-* / NFR-* / CON-* / NG-*)
 - [system-design.md](./system-design.md) — system design (the *how*, mid-level; architecture, mechanisms, diagrams)
-- [reviews/pre-restructure/design-review.md](./reviews/pre-restructure/design-review.md) — design review that drove revisions 2-4
-- [reviews/pre-restructure/integration-recon.md](./reviews/pre-restructure/integration-recon.md) — integration reality check against Filigree / Wardline
+- [../adr/README.md](../adr/README.md) — Accepted ADRs (including ADR-023 through ADR-032 authored after this layer was baselined)
+- [../../implementation/v0.1-reviews/pre-restructure/design-review.md](../../implementation/v0.1-reviews/pre-restructure/design-review.md) — design review that drove revisions 2-4 (archived)
+- [../../implementation/v0.1-reviews/pre-restructure/integration-recon.md](../../implementation/v0.1-reviews/pre-restructure/integration-recon.md) — integration reality check against Filigree / Wardline (archived)
 
 ---
 
@@ -18,7 +19,7 @@
 
 ### What this document is
 
-This is Clarion v0.1's **detailed design reference** — implementation-level depth. Everything here is concrete: Rust struct definitions, the full SQL schema, the complete `clarion.yaml` example, the exhaustive Phase-7 rule catalogue with thresholds, the complete MCP tool list, severity mapping tables, the `scan_run_id` lifecycle, the dedup collision policy, SARIF property-bag translation rules, full Filigree/Wardline prerequisite lists (with specific file references and ADR citations), the testing strategy, the ADR backlog with full priorities, and the appendices (future direction, glossary, Rust stack).
+This is Clarion v1.0's **detailed design reference** — implementation-level depth. Everything here is concrete: Rust struct definitions, the full SQL schema, the complete `clarion.yaml` example, the exhaustive Phase-7 rule catalogue with thresholds, the complete MCP tool list, severity mapping tables, the `scan_run_id` lifecycle, the dedup collision policy, SARIF property-bag translation rules, full Filigree/Wardline prerequisite lists (with specific file references and ADR citations), the testing strategy, the ADR backlog with full priorities, and the appendices (future direction, glossary, Rust stack).
 
 ### What moved up
 
@@ -39,7 +40,7 @@ Sections 1-11 are implementation detail by subsystem, mirroring the natural orde
 
 ## 1. Plugin Implementation Detail
 
-### Plugin packaging (v0.1)
+### Plugin packaging (v1.0)
 
 Each plugin is a separately-installable Python package that provides an executable entry point matching the Clarion plugin protocol. Core finds plugins via `~/.config/clarion/plugins.toml` or via the project's `clarion.yaml`.
 
@@ -226,7 +227,7 @@ struct Entity {
 ### Entity ID scheme
 
 - **Source entities**: `{plugin_id}:{kind}:{canonical_qualified_name}` where `canonical_qualified_name` is the plugin's language-native fully-qualified identifier (for Python: `auth.tokens.TokenManager`, not `src/auth/tokens.py::TokenManager`).
-- **Files**: `core:file:{content_addressed_path_hash}@{path}` — content-addressed so rename detection has a handle; `@{path}` suffix preserves human readability in logs.
+- **Files**: `core:file:{qualified_name}` where `qualified_name` is the project-relative POSIX canonical path. File IDs may not contain `@`; content hashes are carried as drift metadata, not embedded in the ID.
 - **Subsystems**: `core:subsystem:{cluster_hash}` (from sorted member module IDs).
 - **Guidance sheets**: `core:guidance:{content_hash_short}`.
 - **Unresolvable Python imports** (stub): `python:unresolved:{module.path}` — reconciled to real entities when resolution becomes possible.
@@ -996,7 +997,7 @@ integrations:
     enabled: true
     server_url: "stdio:filigree-mcp"
     emit_observations: true
-    emit_findings: true              # v0.1: posts to POST /api/v1/scan-results (Filigree-native schema; see §7)
+    emit_findings: true              # opt-in (default false): POSTs findings to POST /api/v1/scan-results (Filigree-native schema; see §7). One-way egress, decoupled from `enabled` so turning on read enrichment never silently starts outbound emission.
   wardline:
     enabled: true
     manifest_path: "wardline.yaml"
@@ -1050,6 +1051,18 @@ These rules combine signals Clarion uniquely holds — clusters from Phase 3, Wa
 
 **`CLA-FACT-TIER-SUBSYSTEM-MIXING` threshold**: default `min_outlier_count: 2` and `min_outlier_fraction: 0.1` (i.e., at least 2 outliers AND at least 10% of subsystem members). Configurable via `clarion.yaml:analysis.clustering.tier_mixing_thresholds`. Tuned to avoid flagging subsystems where a single outlier is legitimate boundary-infrastructure (e.g., an `EXTERNAL_RAW` parser adjacent to an otherwise-`INTEGRAL` validation subsystem).
 
+### Pre-ingest secret-scanning findings (WP5)
+
+These core-emitted rules are the ADR-013 audit surface. ADR-013 remains canonical for scanner behaviour; this catalogue records the emitted finding IDs.
+
+| Rule | Severity | Category | Description | Remediation | ADR |
+|---|---|---|---|---|---|
+| `CLA-SEC-SECRET-DETECTED` | ERROR | security | Pre-ingest secret scanner detected a credential pattern in a file slated for LLM dispatch. | Remove the secret, rotate the credential, or whitelist via `.clarion/secrets-baseline.yaml` with a justification. | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` | ERROR | security | Operator invoked `--allow-unredacted-secrets`; file content reached the LLM provider with secrets intact. | Audit override usage via `filigree list --rule-id=CLA-SEC-UNREDACTED-SECRETS-ALLOWED --since 30d`. | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION` | ERROR | infra | Baseline entry missing required `justification` field; entry not honoured. | Add a `justification` string explaining why the match is safe. | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-INFRA-SECRET-BASELINE-MATCH` | INFO | infra | Baseline entry suppressed a scanner detection as an audit event. | None; informational and retained for `NFR-SEC-04` audit. | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED` | ERROR | infra | `--allow-unredacted-secrets` supplied without confirmation; run aborted before start. | Supply `--confirm-allow-unredacted-secrets=yes-i-understand` in non-TTY contexts or run interactively. | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) |
+
 ### Entity-set diff (deletion detection)
 
 At Phase 7, Clarion compares the current run's entity IDs against the prior run's set (read from the prior `run_id`'s stats; if no prior run exists, this phase is a no-op). For each entity ID present before and absent now:
@@ -1334,35 +1347,37 @@ Response:
 
 **404 behaviour**: returns `resolution_confidence: "none"` with an empty `entity_id` rather than HTTP 404. Lets callers distinguish "Clarion doesn't know this" from "Clarion is down."
 
-### Authentication — full spec (ADR-012)
+### Authentication — registry-backend HTTP read API
 
-**Default on Linux / macOS — Unix domain socket** (`serve.auth: uds`):
+ADR-014 supersedes ADR-012 for the Filigree `registry_backend: clarion`
+HTTP read surface. The active contract is unauthenticated loopback-only by
+default, with non-loopback binds refused unless
+`serve.http.allow_non_loopback: true` and protected by an operator-managed
+authenticated reverse proxy or equivalent access-control layer.
 
-- `clarion serve` binds `<project_root>/.clarion/socket` with mode `0600`, owner = the UID running `clarion serve`.
-- Transport: HTTP/1.1 over UDS. Server: `axum` + `tokio::net::UnixListener`. Clients: `hyper-unix-connector` or equivalent.
-- Auth is filesystem-permissions based; HTTP layer does not require `Authorization` header under UDS mode.
-- Stale-socket cleanup: on startup, Clarion stat-checks `.clarion/socket` — if present and no process is listening, it unlinks before binding. Double-start (`clarion serve` twice) fails loudly with `CLA-INFRA-SOCKET-IN-USE`.
-- Sibling discovery: `.clarion/config.json` records `serve.socket_path`; sibling tools read the path and connect via `unix://<absolute path>`.
+The earlier UDS/token design remains historical context for a broader HTTP API,
+not the implementation contract for `/api/v1/_capabilities` or
+`/api/v1/files`.
 
-**Fallback (auto on Windows, opt-in elsewhere) — TCP + Bearer token** (`serve.auth: token`):
+**Default — loopback only**:
 
-- Windows default: `token` mode on `127.0.0.1:8765` (configurable via `serve.bind_port`).
-- Auto-mint: first `clarion serve` writes `.clarion/auth.token` (mode `0600`). Token format: 32 URL-safe base64 bytes (43 chars) prefixed `clrn_` for grep-ability in logs.
-- OS-keychain promotion: `clarion serve auth promote-to-keychain` migrates the token from file to macOS Keychain / Linux libsecret / Windows Credential Manager via the `keyring` crate. Emits `CLA-INFRA-TOKEN-STORAGE-DEGRADED` if the keychain is unavailable (falls back to file).
-- Wire format: HTTP header `Authorization: Bearer clrn_<43chars>`. Constant-time comparison.
-- Rotation: `clarion serve auth rotate` generates a new token, accepts both old and new for 24 hours, drops the old. Rotation is idempotent.
-- Scoping: v0.1 has one token per install with full read access. Per-endpoint scoping and revocation lists are v0.2+.
+- `clarion serve` binds only to loopback addresses.
+- HTTP layer does not require `Authorization` headers for the ADR-014 endpoint.
+- `/api/v1/_capabilities` reports `api_version` and `instance_id` so sibling
+  clients can detect compatible deployments and project-instance drift.
 
-**Explicit-none** (`serve.auth: none` or `--i-accept-no-auth`):
+**Explicit non-loopback**:
 
-- Allowed but loud: emits `CLA-INFRA-HTTP-AUTH-DISABLED` (severity ERROR) on every `clarion serve` startup and reaches Filigree through the normal finding pipeline. Persistent banner in logs.
-- Use cases: air-gapped CI where external ingress is controlled separately; local debugging with explicit operator decision. CLI flag is deliberately verbose (`--i-accept-no-auth`) to prevent accidental muscle-memory enabling.
+- Requires `serve.http.allow_non_loopback: true`.
+- Startup logs warn that the surface is unauthenticated.
+- Operators must front Clarion with authenticated ingress or equivalent access
+  control before exposing the endpoint beyond loopback.
 
-**How sibling tools pick up auth in CI**:
+**How sibling tools pick up access in CI**:
 
-- **UDS mode**: sibling tools mount the project's `.clarion/socket` into their process (bind-mount for containers, bare path for same-host processes). No token plumbing.
-- **Token mode**: `CLARION_TOKEN` env var (preferred for CI; injected via the CI provider's secret store) or `.clarion/auth.token` bind-mount. Wardline's `wardline.yaml` records the Clarion endpoint URL (`unix://…` or `http://127.0.0.1:8765`) but not the token — token comes from env.
-- **Pre-flight check**: `clarion check-auth --from wardline` returns exit 0 if the endpoint is reachable and authenticated under the active mode. Returns 0 with warning under `none` mode.
+- Same-host sibling tools use the loopback endpoint.
+- CI or remote deployments that need non-loopback access provide protection
+  outside Clarion, then use `/api/v1/_capabilities` as the compatibility probe.
 
 ---
 
@@ -1371,7 +1386,9 @@ Response:
 Some risks sit outside Clarion's code but inside the operator's responsibility. These belong in the team's onboarding doc, not in the tool's runtime defences:
 
 - **Use project-scoped API keys, not personal ones, when `storage.commit_db: true`.** Briefings in `.clarion/clarion.db` were paid for by whoever ran `clarion analyze`. A teammate pulling your committed DB benefits from LLM calls your personal key paid for. Use an Anthropic project / org key, not your personal key, when committing the DB.
-- **Rotate tokens when a committed DB exposes a stale model's output.** If `.clarion/clarion.db` was generated with a leaked or exposed API key, the token is already used; the briefings in the DB are not themselves secret but the key's usage fingerprint is. Rotate, then re-run `clarion analyze` to overwrite the briefing provenance.
+- **Protect non-loopback HTTP exposure outside Clarion.** If operators bind the
+  ADR-014 HTTP read API outside loopback, place an authenticated reverse proxy
+  or equivalent access-control layer in front of it.
 - **Review `.clarion/.gitignore` before first commit.** The default excludes `runs/*/log.jsonl` (raw LLM request/response bodies); if operators opt into committing run logs for audit, they accept that source excerpts sent to Anthropic ship to the repo. That's a choice, not an oversight — but it must be a deliberate one.
 
 ### Audit-surface finding IDs
@@ -1380,7 +1397,10 @@ Every security-relevant event emits a finding:
 
 - `CLA-SEC-SECRET-DETECTED` — unredacted secret blocked LLM dispatch
 - `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` — operator overrode block with `--allow-unredacted-secrets`
-- `CLA-INFRA-TOKEN-STORAGE-DEGRADED` — OS keychain unavailable, fell back to file-mode `0600`
+- `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION` — baseline entry lacks the required review rationale
+- `CLA-INFRA-SECRET-BASELINE-MATCH` — baseline entry suppressed a scanner hit
+- `CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED` — override flag was not confirmed, so the run aborted before start
+- `CLA-INFRA-HTTP-NON-LOOPBACK-UNAUTHENTICATED` — ADR-014 HTTP read API was explicitly bound outside loopback and must be protected outside Clarion
 - `CLA-INFRA-BRIEFING-INVALID` — LLM returned schema-invalid content twice, possible injection
 - `CLA-SEC-VOCABULARY-CANDIDATE-NOVEL` — novel `patterns`/`antipatterns` tag proposed by LLM (light signal; mostly harmless)
 
@@ -1552,6 +1572,8 @@ Decisions in this design are load-bearing enough that they deserve explicit Arch
 
 The table below is a navigation aid for implementers: it maps each ADR to the section(s) of *this detailed design* where the decision shows up concretely. It deliberately does not duplicate the rationale or status columns from system-design.md — consult the canonical table for those.
 
+**Coverage note**: this table reflects the ADR set at the 2026-04-18 baseline (ADR-001 through ADR-022). ADR-023 through ADR-032 were authored after the baseline; they touch implementation surfaces this document describes but are not catalogued in the table below. The [ADR index](../adr/README.md) is the canonical list for post-baseline decisions, and the relevant ADR files cite the schema/wire/section they affect.
+
 ### Where each ADR is captured in this detailed design
 
 | # | Decision | Where captured |
@@ -1567,9 +1589,9 @@ The table below is a navigation aid for implementers: it maps each ADR to the se
 | ADR-009 | Structured briefings vs free-form prose | §2 |
 | ADR-010 | MCP as first-class surface | — (system-design §8) |
 | [ADR-011](../adr/ADR-011-writer-actor-concurrency.md) | Writer-actor concurrency model | §3 |
-| [ADR-012](../adr/ADR-012-http-auth-default.md) | HTTP auth — UDS default with TCP+token fallback | §7 |
+| [ADR-012](../adr/ADR-012-http-auth-default.md) | Historical HTTP auth proposal — superseded by ADR-014 for registry-backend API | §7 |
 | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) | Pre-ingest secret scanner | §8 |
-| ADR-014 | Filigree `registry_backend` flag + pluggable `RegistryProtocol` | §7, §9 |
+| ADR-014 | Filigree `registry_backend` flag + pluggable `RegistryProtocol`; owns registry-backend HTTP read trust model | §7, §9 |
 | [ADR-015](../adr/ADR-015-wardline-filigree-emission.md) | Wardline→Filigree emission: Clarion SARIF translator (v0.1), native Wardline POST (v0.2) | §7, §9 |
 | [ADR-016](../adr/ADR-016-observation-transport.md) | Observation transport: `filigree mcp` subprocess (v0.1); `POST /api/v1/observations` HTTP (v0.2 retirement) | §9 |
 | [ADR-017](../adr/ADR-017-severity-and-dedup.md) | Severity mapping + rule-ID round-trip + dedup via `mark_unseen=true` | §7 |
@@ -1672,7 +1694,7 @@ The v0.1 core is Rust (locked — see §11 ADR-001). Crate choices below are rec
 
 ### HTTP
 
-- **axum** for the read API (§7): integrates cleanly with tokio and `tower` middleware; Bearer-token auth, metrics, and ETag middleware compose cleanly.
+- **axum** for the read API (§7): integrates cleanly with tokio and `tower` middleware; tracing, timeout, load-shedding, body-limit, metrics, and ETag middleware compose cleanly.
 - **reqwest** for Anthropic API calls; pooled connections; TLS via `rustls` (no native-TLS; see below).
 
 ### SQLite
@@ -1711,12 +1733,6 @@ The v0.1 core is Rust (locked — see §11 ADR-001). Crate choices below are rec
 - **uuid** v7 for run IDs (time-sortable, useful for log scanning).
 - **time** (not `chrono`) for all datetime handling — strict, explicit, and serde-friendly.
 
-### Cryptography
-
-- **rand** + **rand_core** for token generation.
-- **subtle** for constant-time comparison of auth tokens.
-- **keyring** crate for OS keychain (§7); `0600` file fallback uses `std::os::unix::fs::PermissionsExt`.
-
 ### Testing
 
 - **insta** for snapshot testing (briefing JSON structures, markdown renderer output).
@@ -1815,7 +1831,7 @@ Revision 5 (2026-04-17) restructures the single design document into a three-lay
 | §2.3 Python import resolution (CRITICAL) | Policies for sys.path, unresolved imports, re-exports, conditional imports | §1 Python plugin specifics |
 | §2.4 Secrets + prompt injection (CRITICAL) | Pre-ingest redaction; injection containment; operator guidance | §8, System-design §10 |
 | §2.5 Provider abstraction (HIGH) | Honest framing added — v0.1 is Anthropic-shaped by commitment | §4 LLM provider abstraction (System-design §5) |
-| §2.6 HTTP auth (HIGH) | Token auth designed in v0.1; OS keychain; Wardline pickup path | §7 HTTP read API |
+| §2.6 HTTP auth (HIGH) | ADR-014 supersedes token auth for the registry-backend API; non-loopback guard plus operator-managed access control is the active posture | §7 HTTP read API |
 | §3 ADR backlog | §11 with priorities; ADR-001 (Rust) locked without alternatives | §11 |
 | §4.1 Summary cache semantic validity | TTL backstop + graph-neighborhood drift flag | §4 |
 | §4.2 Guidance stock quality | Churn-tied staleness signals | System-design §7 |
@@ -1831,4 +1847,4 @@ The Rev 2 → Rev 3 transition is the classic layered-review problem. Rev 2 corr
 
 ---
 
-**End of Clarion v0.1 detailed design reference.**
+**End of Clarion v1.0 detailed design reference.**
diff --git a/docs/clarion/1.0/operations.md b/docs/clarion/1.0/operations.md
new file mode 100644
index 00000000..aed091d1
--- /dev/null
+++ b/docs/clarion/1.0/operations.md
@@ -0,0 +1,146 @@
+# Clarion v1.0 Storage Operations
+
+Operator-facing reference for the constraints around Clarion's local-state
+directory. v1.0 is local-first; the storage subsystem is plain SQLite under
+`.clarion/`. The constraints below come straight out of
+[ADR-011](../adr/ADR-011-storage-architecture.md) (writer-actor + reader-pool
+over SQLite) and the v1.0 tag-cut gap-register entries DOC-11, STO-01,
+STO-04, and STO-05.
+
+## 1. Local-first storage layout
+
+Per ADR-011, every Clarion project keeps its state in a `.clarion/`
+directory at the project root:
+
+```
+.clarion/
+├── clarion.db              SQLite database (entities, edges, runs, findings, summary_cache)
+├── clarion.db-wal          SQLite WAL companion file
+├── clarion.db-shm          SQLite shared-memory file
+├── clarion.lock            fs2 advisory lock file (writer claim)
+├── instance_id             Stable per-project instance ID
+└── ...                     plugin caches, scanner baseline, etc.
+```
+
+There is no central server, no shared registry, no networked state.
+`clarion install --path` creates `.clarion/` on a new project root;
+`clarion analyze` and `clarion serve` both read and (in `analyze`'s case)
+write into it.
+
+## 2. NFS is prohibited
+
+**`.clarion/` MUST live on a local filesystem.** Do not place a project root
+on NFS, SMB, sshfs, or any other network filesystem and expect `clarion
+analyze` or `clarion serve` to behave correctly.
+
+The two specific failure modes:
+
+- **POSIX advisory locks over NFS are unreliable.** The `fs2` exclusive
+  lock that protects against concurrent analyzers (§3) is silently
+  no-op or partially honoured on most NFS configurations. Two analyzers
+  on two clients can both believe they hold the lock.
+- **SQLite WAL mode is not safe over network filesystems.** The SQLite
+  manual explicitly warns that WAL requires shared-memory primitives the
+  kernel does not provide across NFS. A WAL-mode database opened over
+  NFS can lose committed writes or corrupt the database file.
+
+If your only available storage is networked, do not use Clarion against
+that workspace. Clone the project to local disk first.
+
+## 3. No double-analyze
+
+Only one `clarion analyze` may run against a given project root at a time.
+The v1.0 binary enforces this with an exclusive `fs2` advisory lock on
+`.clarion/clarion.lock`, acquired at the start of `analyze` and held for the
+writer-actor lifetime. A second `clarion analyze` against the same
+`.clarion/` fails fast with a clear "another clarion analyze is in progress
+against this project" error rather than racing the first analyzer's run
+state. (See STO-01 in the v1.0 tag-cut gap register for the originating
+finding.)
+
+The lock is process-scoped, not user-scoped: the same user starting two
+analyzers in two terminals is the typical mistake the lock prevents.
+
+`clarion serve` is read-only against the database and does not contend with
+`analyze` on the writer lock, but it shares the same database file via the
+reader pool and will observe whichever state `analyze` last committed.
+
+**Same-process restart caveat (STO-05):** the fs2 lock is released when
+the analyzer process exits, including on crash. If the previous analyzer
+exited abnormally, the next `clarion analyze` will sweep
+`runs.status='running'` rows to `'failed'` (see
+`recover_preexisting_running_runs`). There is no PID column or heartbeat
+on `runs` at v1.0 — a same-host restart cannot distinguish "previous
+analyzer crashed" from "previous analyzer is still alive but unlocked
+during a brief teardown window". v1.0 mitigates this with the fs2 lock;
+the `runs.owner_pid` + `heartbeat_at` schema additions are a v1.1
+follow-up.
+
+## 4. Supported backup procedure
+
+The v1.0 supported backup procedure is a four-step shutdown-and-copy. There
+is no live `clarion db backup` subcommand at v1.0 (deferred to v1.1, §6).
+
+1. **Ensure no `clarion analyze` is running** against the project root.
+   The fs2 advisory lock on `.clarion/clarion.lock` will be released; a
+   subsequent `clarion analyze` from a backup script would otherwise race
+   with the backup.
+
+2. **Stop `clarion serve` or wait for it to be idle.** `serve` only reads,
+   so a torn copy from a running `serve` is less catastrophic than from
+   `analyze`, but a clean shutdown is required for the WAL checkpoint to
+   complete.
+
+3. **Force the WAL into the main database file** so a plain file copy
+   captures all committed state:
+
+   ```bash
+   sqlite3 .clarion/clarion.db "PRAGMA wal_checkpoint(TRUNCATE);"
+   ```
+
+   `TRUNCATE` mode is the strongest checkpoint — it flushes the WAL into
+   `clarion.db` and resets `clarion.db-wal` to zero length.
+
+   **Why this step matters:** in WAL mode, committed pages live in
+   `clarion.db-wal` until a checkpoint folds them back into `clarion.db`. A
+   naive `cp .clarion/clarion.db backup.db` during (or shortly after) a live
+   `analyze` therefore captures a *torn* copy — the main database file is
+   missing the most recent committed transactions, which are still sitting in
+   the separate `-wal` file. Forcing a `TRUNCATE` checkpoint first guarantees
+   `clarion.db` is self-contained before the copy.
+
+4. **Copy `.clarion/` to the backup location** with any standard tool
+   (`cp -a`, `rsync -a`, `tar`). All three of `clarion.db`,
+   `clarion.db-wal`, and `clarion.db-shm` should be present in the copy;
+   after a successful TRUNCATE the WAL is empty but the file should still
+   be copied.
+
+## 5. Restore
+
+To restore a backup:
+
+1. Stop any running `clarion analyze` or `clarion serve` against the
+   project root.
+2. Replace the project's `.clarion/` directory with the backup copy. The
+   `instance_id` file inside `.clarion/` is part of the backup; restoring
+   it preserves the project's federation identity (`/api/v1/_capabilities`
+   `instance_id` stays stable across the restore).
+3. Run `clarion analyze` to validate the restored database. A fresh analyze
+   re-applies any pending migrations and exercises the integrity-check path
+   on the e2e test surface.
+
+## 6. v1.1 follow-up: `clarion db backup` subcommand
+
+A live-safe `clarion db backup <path>` subcommand backed by SQLite's online
+backup API is tracked for v1.1. It will replace steps 1–4 of §4 with a
+single command that takes a snapshot without requiring `analyze` and
+`serve` to be quiesced. Until then, follow §4.
+
+## References
+
+- [ADR-011 — Storage Architecture](../adr/ADR-011-storage-architecture.md)
+  — writer-actor and reader-pool design, normative source for §1 and §3.
+- [`docs/implementation/v1.0-tag-cut/gap-register.md`](../../implementation/v1.0-tag-cut/gap-register.md)
+  — DOC-11, STO-01, STO-04, STO-05 gap entries that drove this document.
+- [SQLite WAL mode caveats](https://www.sqlite.org/wal.html#noshm) — the
+  upstream warning that underlies the NFS prohibition in §2.
diff --git a/docs/clarion/v0.1/requirements.md b/docs/clarion/1.0/requirements.md
similarity index 79%
rename from docs/clarion/v0.1/requirements.md
rename to docs/clarion/1.0/requirements.md
index 357a7e9d..9baebcce 100644
--- a/docs/clarion/v0.1/requirements.md
+++ b/docs/clarion/1.0/requirements.md
@@ -1,14 +1,15 @@
-# Clarion v0.1 — Requirements
+# Clarion v1.0 — Requirements
 
-**Status**: Baselined for v0.1 implementation (post-ADR sprint 2026-04-18)
-**Baseline**: 2026-04-17 · **Last updated**: 2026-04-18
+**Status**: Baselined for v1.0 release (carried forward from v0.1 baseline 2026-04-17 with the Sprint 3 federation-hardening additions)
+**Baseline**: 2026-04-17 · **Last updated**: 2026-05-19
 **Primary author**: qacona@gmail.com (with Claude)
 **First customer target**: `/home/john/elspeth` (~425k LOC Python)
 **Companion documents**:
 - [system-design.md](./system-design.md) — system design (the *how*, mid-level)
 - [detailed-design.md](./detailed-design.md) — detailed design reference (implementation-level)
-- [reviews/pre-restructure/design-review.md](./reviews/pre-restructure/design-review.md) — prior review that shaped revs 2-4
-- [reviews/pre-restructure/integration-recon.md](./reviews/pre-restructure/integration-recon.md) — reality check against Filigree / Wardline
+- [../adr/README.md](../adr/README.md) — Accepted ADRs
+- [../../implementation/v0.1-reviews/pre-restructure/design-review.md](../../implementation/v0.1-reviews/pre-restructure/design-review.md) — archived design review that shaped revs 2-4
+- [../../implementation/v0.1-reviews/pre-restructure/integration-recon.md](../../implementation/v0.1-reviews/pre-restructure/integration-recon.md) — archived reality check against Filigree / Wardline
 
 ---
 
@@ -16,13 +17,13 @@
 
 ### What this document is
 
-This is the requirements specification for Clarion v0.1 — the *what*: capabilities, constraints, quality attributes, and explicit non-goals. The *how* (architecture, mechanisms, diagrams) lives in the system-design; the *implementation detail* (SQL schemas, Rust crate selection, rule-ID catalogues) lives in the detailed-design.
+This is the requirements specification for Clarion v1.0 — the *what*: capabilities, constraints, quality attributes, and explicit non-goals. The *how* (architecture, mechanisms, diagrams) lives in the system-design; the *implementation detail* (SQL schemas, Rust crate selection, rule-ID catalogues) lives in the detailed-design.
 
 ### How to read this
 
 - Each requirement has a stable ID (`REQ-*`, `NFR-*`, `CON-*`, `NG-*`), a plain-English statement, a rationale, a verification method, and a **See** line pointing to the system-design section that addresses it.
 - Requirement IDs are load-bearing: filigree issues cite them by ID in descriptions and commit messages; code review references them when discussing implementation. IDs are stable across rev bumps unless a requirement is fully retired (in which case the ID is never reused).
-- "Clarion" throughout means Clarion v0.1 specifically. Where v0.2+ behaviour is deliberately different, it's named as a non-goal (`NG-*`) in the Non-Goals section of this document.
+- "Clarion" throughout means Clarion v1.0 specifically. Where v2.0+ behaviour is deliberately different, it's named as a non-goal (`NG-*`) in the Non-Goals section of this document.
 
 ### Relationship to Loom
 
@@ -194,6 +195,8 @@ Structured summaries produced for each entity at policy-defined levels.
 
 #### REQ-BRIEFING-01 — Structured, not prose
 
+> **v1.0 ships a 4-field on-demand summary** (`purpose`, `behavior`, `relationships`, `risks`) per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) (WP6 narrowed to leaf-tier on-demand `summary(id)`). The 9-field `EntityBriefing` schema below — `maturity` / `maturity_reasoning` / `patterns` / `antipatterns` / `knowledge_basis` / `notes` plus the `CLA-INFRA-BRIEFING-INVALID` retry path — is the v1.1 target when the briefing pipeline (Phases 4–6) lands per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md).
+
 Briefings follow a fixed schema (`purpose`, `maturity`, `maturity_reasoning`, `risks`, `patterns`, `antipatterns`, `relationships`, `knowledge_basis`, `notes`). Free-form prose is not an acceptable briefing output.
 
 **Rationale**: Principle 2 (exploration elimination) + Principle 4 (finding as fact exchange). LLM agents consume briefings as structured data to drive further navigation; prose requires re-parsing and is an order of magnitude worse for composability.
@@ -202,6 +205,8 @@ Briefings follow a fixed schema (`purpose`, `maturity`, `maturity_reasoning`, `r
 
 #### REQ-BRIEFING-02 — Controlled vocabulary for `patterns` / `antipatterns` / risk tags
 
+> **Deferred to v1.1** per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) + [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md). The `patterns` / `antipatterns` fields belong to the 9-field `EntityBriefing` schema deferred in [REQ-BRIEFING-01](#req-briefing-01--structured-not-prose); the `CLA-FACT-VOCABULARY-CANDIDATE` rule and adversarial-docstring containment land with that pipeline.
+
 `patterns` and `antipatterns` fields draw from a controlled vocabulary (core base set + plugin extensions). Novel tags proposed by the LLM are accepted once but logged as `CLA-FACT-VOCABULARY-CANDIDATE` for human review; they do not silently promote into future prompts.
 
 **Rationale**: An unconstrained vocabulary is a prompt-injection vector (see `NFR-SEC-03`) and drifts across runs, undermining comparability. A controlled vocabulary gives LLMs a fixed palette while preserving extensibility for genuinely new patterns.
@@ -218,6 +223,8 @@ Generated briefings are cached by `(entity_id, content_hash, prompt_template_id,
 
 #### REQ-BRIEFING-04 — `knowledge_basis` field per briefing
 
+> **Deferred to v1.1** per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) + [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md). `knowledge_basis` depends on the guidance system ([REQ-GUIDANCE-*](#guidance-system-req-guidance-), WP7 deferred) for the guidance-authored path and on Filigree triage-state feedback ([REQ-INTEG-FILIGREE-02](#req-integ-filigree-02--observation-emission-http-preferred-mcp-fallback), WP9-B deferred) for the acknowledged-finding path. Both inputs are v1.1.
+
 Every briefing carries `knowledge_basis: static_only | runtime_informed | human_verified`. Default is `static_only`; promotion to `human_verified` requires (a) a guidance sheet authored or reviewed against the entity in the last 90 days OR (b) a finding with `status ∈ {suppressed, acknowledged}` carrying a non-empty reason.
 
 **Rationale**: Agents consuming briefings need to calibrate how much to trust the `risks` / `patterns` claims. A briefing derived purely from static analysis + LLM synthesis should be treated as a hypothesis; one validated by human curation (guidance or triage) earns more trust.
@@ -226,6 +233,8 @@ Every briefing carries `knowledge_basis: static_only | runtime_informed | human_
 
 #### REQ-BRIEFING-05 — Triage-state feedback from Filigree
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B finding emission + WP7 guidance both deferred). Triage feedback requires Clarion-Filigree finding-state plumbing that does not ship in v1.0; the guidance-fingerprint side is moot until [REQ-GUIDANCE-02](#req-guidance-02--composition-algorithm) composition ships. `EMPTY_GUIDANCE_FINGERPRINT` is the v1.0 placeholder.
+
 When rendering a briefing, Clarion queries Filigree for findings on this entity with `status ∈ {suppressed, acknowledged}` and a non-empty reason, and surfaces those as either inline notes (≤3) or a synthetic `RiskItem` with `tag: operator-acknowledged` (>3). The guidance fingerprint incorporates the set of acknowledged finding IDs.
 
 **Rationale**: Operator triage decisions (suppressions, acknowledgements) are institutional knowledge in the same shape as guidance; they must flow back into briefings so the next LLM agent sees "this was already decided" rather than re-opening the conversation.
@@ -234,6 +243,8 @@ When rendering a briefing, Clarion queries Filigree for findings on this entity
 
 #### REQ-BRIEFING-06 — Detail levels: short / medium / full / exhaustive
 
+> **Deferred to v1.1** per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) + [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md). Detail-level tiers are part of the deferred briefing pipeline; v1.0 `summary(id)` returns a single un-tiered shape per ADR-030. Per-tool token-budget contracts in [REQ-MCP-04](#req-mcp-04--bounded-response-sizes) reference these tiers and are correspondingly deferred.
+
 Briefings are renderable at four detail levels with token ceilings: `short` ≤100 tokens, `medium` ≤400, `full` ≤1,500, `exhaustive` ≤3,600. The ≤ figures are enforced hard limits that trigger truncation; typical briefings target roughly half these values (see System Design §3). Implementations must treat the ≤ figures as the contract.
 
 **Rationale**: Bounded responses (Principle 2) demand fixed token budgets per detail level. LLM agents can request what they need without pulling an entire subsystem's worth of text into their context.
@@ -246,6 +257,8 @@ Briefings are renderable at four detail levels with token ceilings: `short` ≤1
 
 Institutional knowledge attached to entities and composed into prompts.
 
+> **Whole subsystem deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP7 deferred in full). The `guidance_sheets` view substrate exists in the v1.0 storage schema (kind reservation, ADR-024 vocabulary), but no authoring path, composition algorithm, wardline-derivation, staleness signals, or export/import surface ships. `EMPTY_GUIDANCE_FINGERPRINT` is hard-coded into every summary-cache key as a placeholder. REQ-GUIDANCE-01 through REQ-GUIDANCE-06 below describe the v1.1 target.
+
 #### REQ-GUIDANCE-01 — Guidance sheets as first-class entities
 
 Guidance sheets are entities of `kind: guidance` with properties `{content, scope_level, scope, match_rules, expires, pinned, provenance, ...}` (per ADR-024). They participate in the same navigation, finding, and cache machinery as code entities.
@@ -318,6 +331,8 @@ Clarion's rule IDs follow the `CLA-*` namespace: `CLA-PY-*` for Python-plugin st
 
 #### REQ-FINDING-03 — Emit findings to Filigree
 
+> **Implemented (WP9-B core, post-1.0 `release:1.1`).** `clarion analyze` Phase 8 POSTs persisted findings to Filigree's `POST /api/v1/scan-results` intake; the wire contract is pinned in [`docs/federation/contracts.md`](../../federation/contracts.md#consumed-filigree-route-scan-results-intake-finding-emission). Emission is enrich-only and opt-in: gated behind `integrations.filigree.{enabled,emit_findings}`, **both default `false`**, and any Filigree-side failure is recorded in `stats.json` (`CLA-INFRA-FILIGREE-UNREACHABLE`) rather than failing the run. Findings anchored to a `briefing_blocked` entity are excluded, matching the fail-closed read posture. Clarion still emits to its own SQLite `findings` table regardless.
+
 Clarion POSTs findings to Filigree via `POST /api/v1/scan-results` using Filigree's native intake schema. Clarion's richer fields (`kind`, `confidence`, `confidence_basis`, `supports`/`supported_by`, `related_entities`, internal severity, internal status) nest inside each finding's `metadata.clarion.*`.
 
 **Rationale**: Filigree owns finding triage and lifecycle (per the Loom federation axiom — `CON-LOOM-01`). Emitting to Filigree surfaces Clarion's findings alongside Wardline's and any future scanners' in the team's unified triage view.
@@ -326,14 +341,18 @@ Clarion POSTs findings to Filigree via `POST /api/v1/scan-results` using Filigre
 
 #### REQ-FINDING-04 — General-purpose SARIF → Filigree translator
 
-Clarion v0.1 ships `clarion sarif import <file> [--scan-source <name>]` that translates any SARIF v2.1.0 emitter (Wardline, Semgrep, CodeQL, Trivy) to Filigree's scan-results format, preserving `result.properties` into `metadata.<driver>_properties.*`.
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP10). The SARIF translator is independent of MCP surface delivery and lands with the v1.1 cross-product work.
+
+Clarion ships `clarion sarif import <file> [--scan-source <name>]` that translates any SARIF v2.1.0 emitter (Wardline, Semgrep, CodeQL, Trivy) to Filigree's scan-results format, preserving `result.properties` into `metadata.<driver>_properties.*`.
 
-**Rationale**: The translator is a permanent suite feature (SARIF is external, Filigree's intake is not SARIF). For v0.1 it serves Wardline-to-Filigree as a side-effect; in v0.2+ Wardline ships its own native POST, but the translator stays for third-party SARIF sources.
+**Rationale**: The translator is a permanent suite feature (SARIF is external, Filigree's intake is not SARIF). For v0.1 it served Wardline-to-Filigree as a side-effect; in v0.2+ Wardline ships its own native POST, but the translator stays for third-party SARIF sources.
 **Verification**: SARIF corpus at `tests/fixtures/wardline-sarif/` translates to scan-results POSTs; `wardline.*` property-bag keys land in `metadata.wardline_properties.*`; severity mapped via `{error→high, warning→medium, note→info}`.
 **See**: System Design §9 (Integrations, SARIF translator).
 
 #### REQ-FINDING-05 — `scan_run_id` lifecycle
 
+> **Implemented (WP9-B, post-1.0 `release:1.1`), minus the Phase-0 handshake.** The wire shape ships: Clarion's `run_id` maps 1:1 onto Filigree's `scan_run_id`, and Phase 8 closes the run with `complete_scan_run=true`. **`--resume RUN_ID` now ships** (clarion-dd29e69e0e): a `WriterCmd::ResumeRun` reopens the prior run's `runs` row instead of `INSERT`ing (which conflicted on the existing `run_id`), the re-walk UPSERTs entities and run-scoped findings idempotently, and Phase 8 emits with `mark_unseen=false`. **Still open (contract question, not Clarion-side work):** there is no Phase-0 pre-create handshake — emission relies on Filigree tolerating an unknown `scan_run_id` (it warns and proceeds). Clarion's posture is to depend on that behavior; whether it is Filigree's intended permanent contract is the §4 question in [`docs/federation/2026-05-30-prune-unseen-filigree-request.md`](../../federation/2026-05-30-prune-unseen-filigree-request.md), pending Filigree's confirmation.
+
 Clarion's `run_id` maps 1:1 onto Filigree's `scan_run_id`. Phase 0 of `clarion analyze` creates the scan run; Phase 8 closes it with `complete_scan_run=true`. Resume (`--resume`) reuses the same `run_id` and posts with `mark_unseen=false`.
 
 **Rationale**: Run lifecycle alignment lets Filigree apply "seen-in-latest" logic correctly. Without it, resumed runs would be indistinguishable from fresh runs and prior findings would flap to `unseen_in_latest` prematurely.
@@ -342,6 +361,8 @@ Clarion's `run_id` maps 1:1 onto Filigree's `scan_run_id`. Phase 0 of `clarion a
 
 #### REQ-FINDING-06 — Dedup policy for moved entities
 
+> **Implemented (WP9-B, post-1.0 `release:1.1`).** Clarion POSTs with `mark_unseen=true` by default (Phase 8), so old-position findings transition to `unseen_in_latest`. `clarion analyze --prune-unseen` (Phase 8b) then POSTs Filigree's `POST /api/loom/findings/clean-stale` retention route (contract pinned in [`docs/federation/contracts.md`](../../federation/contracts.md)), scoped to `scan_source=clarion`, with the age threshold from `integrations.filigree.prune_unseen_days` (default 30). **Note — soft-archive, not delete:** Filigree owns the finding lifecycle and realises "removes" as an audit-preserving soft-archive (`unseen_in_latest` → `fixed`, auto-reopens on reappearance; Filigree ADR-015). Enrich-only: a Filigree outage or disabled integration is recorded in `stats.json` (`filigree_prune`), never fails the run.
+
 Clarion POSTs findings with `mark_unseen=true` by default so that old-position findings for the same rule on the same file transition to `unseen_in_latest` when the entity moves within the file. `clarion analyze --prune-unseen` removes `unseen_in_latest` findings older than 30 days (configurable).
 
 **Rationale**: Filigree's dedup key includes `line_start`; entities moving within a file produce two findings. `mark_unseen` is the v0.1 compromise — acceptable coarseness until Filigree ships server-side per-entity dedup (v0.2).
@@ -356,6 +377,8 @@ The MCP tool surface exposed by `clarion serve` for consult-mode LLM agents.
 
 #### REQ-MCP-01 — Cursor-based session model
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §3 (Box B.6 narrowed the MCP surface)](../../implementation/sprint-2/scope-amendment-2026-05.md). The cursor-based Navigation model is one of the categories explicitly removed from the v1.0 MVP surface; v1.0 tools take explicit `id` arguments per-call. Cursor + breadcrumbs + scope-lens land with the broader catalogue.
+
 Every MCP session has server-held state: cursor (`EntityId`), breadcrumb history, scope lens, session cost accumulator, tracked observations / proposals. Navigation tools update the cursor; inspection tools default to operating on the cursor.
 
 **Rationale**: Cursor-based navigation eliminates the need to pass `entity_id` to every call — an agent says `goto(id)`, then `summary()`, `neighbors()`, `callers()` all operate on the current entity. Reduces parent-context token consumption (`NFR-PERF-03`) and models the "I'm looking at this entity" conversational stance naturally.
@@ -364,6 +387,8 @@ Every MCP session has server-held state: cursor (`EntityId`), breadcrumb history
 
 #### REQ-MCP-02 — Navigation and inspection tool catalogue
 
+> **v1.0 ships an 8-tool MVP subset** per the [Sprint 2 scope amendment §3 (Box B.6)](../../implementation/sprint-2/scope-amendment-2026-05.md): `entity_at`, `find_entity`, `callers_of`, `execution_paths_from`, `summary`, `issues_for`, `neighborhood`, plus `subsystem_members` (added in Sprint 3 with WP4 Phase-3 clustering). The remaining categories listed below — the cursor-based Navigation model, write-effect Inspection tools, Search, Findings operations, Guidance (deferred with WP7), and Session/scope — are deferred to v1.1 per the same amendment §4. The catalogue paragraph below documents the v1.1 target surface.
+
 Clarion exposes MCP tools in the documented categories: Navigation (`goto`, `goto_path`, `back`, `zoom_out`, `zoom_in`, `breadcrumbs`); Inspection (`summary`, `source`, `metadata`, `guidance_for`, `findings_for`, `wardline_for`); Neighbours (`neighbors`, `callers`, `callees`, `children`, `imports_from`, `imported_by`, `in_subsystem`, `subsystem_members`); Search (`search_structural`, `search_semantic`, `find_by_tag`, `find_by_wardline`, `find_by_kind`); Findings & observability (`list_findings`, `emit_observation`, `promote_observation`, `cost_report`); Guidance (`show_guidance`, `list_guidance`, `propose_guidance`, `promote_guidance`); Session/scope (`set_scope_lens`, `session_info`).
 
 **Rationale**: Principle 2 (exploration elimination) requires the tool catalogue to cover the common explore-agent questions. Missing a category forces agents to spawn sub-agents to answer what the catalogue should have answered; bloating it dilutes the surface and raises consumption.
@@ -372,6 +397,8 @@ Clarion exposes MCP tools in the documented categories: Navigation (`goto`, `got
 
 #### REQ-MCP-03 — Exploration-elimination shortcuts
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §3 (Box B.6 — narrowed MCP surface)](../../implementation/sprint-2/scope-amendment-2026-05.md) and §4 (WP4 Phase-7 cross-cutting analysis deferred to v1.1). Exploration shortcuts are populated by pre-computation during batched Phase-7 analysis; v1.0 ships on-demand `summary` only ([ADR-030](../adr/ADR-030-on-demand-summary-scope.md)) and has no batched pre-computation pass to feed the shortcut indices.
+
 Clarion exposes pre-computed shortcuts operationalising common exploration queries: `find_entry_points`, `find_http_routes`, `find_cli_commands`, `find_data_models`, `find_config_loaders`, `find_tests`, `find_fixtures`, `find_deprecations`, `find_todos`, `find_dead_code`, `find_circular_imports`, `find_coupling_hotspots`, `recently_changed`, `high_churn`, `what_tests_this`. Each accepts an optional `scope` (entity ID or path glob).
 
 **Rationale**: Each of these is an "explore-agent spawn" an LLM would otherwise perform by walking the graph — and each can be pre-computed during batch analysis and cached. Principle 2 says those spawns are a failure mode; the shortcuts are the remedy.
@@ -380,6 +407,8 @@ Clarion exposes pre-computed shortcuts operationalising common exploration queri
 
 #### REQ-MCP-04 — Bounded response sizes
 
+> **v1.0 ships intrinsic bounds on the 8-tool MVP subset** (`max_depth`, `limit`, server-side `edge_cap` of 500 on `execution_paths_from`, pagination on `find_entity`). Per-tool token-budget contracts (`summary(short/medium/full) ≤100/≤400/≤1,500`) and the per-session `set_budget(tool, max_tokens)` API are deferred to v1.1 — they reference catalogue surface ([REQ-MCP-02](#req-mcp-02--navigation-and-inspection-tool-catalogue)) and detail levels ([REQ-BRIEFING-06](#req-briefing-06--detail-levels-short--medium--full--exhaustive)) that are themselves deferred per the [Sprint 2 scope amendment](../../implementation/sprint-2/scope-amendment-2026-05.md) + [ADR-030](../adr/ADR-030-on-demand-summary-scope.md).
+
 MCP tool responses respect per-tool token budgets: `summary(short) ≤100`, `summary(medium) ≤400`, `summary(full) ≤1,500`, `neighbors / callers / callees / children ≤20 results × ≤50 tokens each`, `source` paginated above 2,000 tokens, `search_*` ≤10 results. Budgets are configurable per-session via `set_budget(tool, max_tokens)`.
 
 **Rationale**: Unbounded responses re-introduce the context-pollution problem Clarion exists to solve. Explicit budgets keep parent context growth predictable and let agents reason about how much slack they have before compaction.
@@ -388,6 +417,8 @@ MCP tool responses respect per-tool token budgets: `summary(short) ≤100`, `sum
 
 #### REQ-MCP-05 — Consent gates on write-effect tools
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §3 (Box B.6 narrowed the MCP surface to 8 read-only tools)](../../implementation/sprint-2/scope-amendment-2026-05.md). The write-effect tools this requirement governs (`emit_observation`, `promote_observation`, `propose_guidance`, `promote_guidance`) are not in the v1.0 MVP surface; consent-gate semantics land with the broader catalogue and the WP7 guidance system.
+
 Write-effect tools (`emit_observation`, `promote_observation`, `propose_guidance`, `promote_guidance`) return a draft for human confirmation by default. Headless agent-walk mode enables direct writes via client-declared `capabilities: { auto_emit: true }`.
 
 **Rationale**: Consult sessions are often human-in-the-loop; surprise writes erode trust. Explicit consent via draft-then-confirm matches how human operators expect agent tools to behave; headless mode opts out for fully-automated pipelines.
@@ -396,6 +427,8 @@ Write-effect tools (`emit_observation`, `promote_observation`, `propose_guidance
 
 #### REQ-MCP-06 — Session persistence and lifecycle
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §3 (Box B.6)](../../implementation/sprint-2/scope-amendment-2026-05.md). Session persistence is the cursor-based Navigation model deferred with [REQ-MCP-01](#req-mcp-01--cursor-based-session-model); v1.0 tools take explicit `id` arguments per-call and hold no per-session state beyond the request scope.
+
 Sessions are created on MCP `initialize`, idle-timeout after 1 hour (configurable), and persist to `.clarion/sessions/<id>.json` for reconnection. `clarion sessions list` and `clarion sessions close <id>` provide admin surfaces.
 
 **Rationale**: Agents reconnecting after a transport interruption expect their cursor and breadcrumbs to survive; losing session state mid-investigation is hostile to the workflow.
@@ -410,6 +443,8 @@ Human-readable outputs from `clarion analyze`.
 
 #### REQ-ARTEFACT-01 — JSON catalog output
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §3 (Box B.4 removed)](../../implementation/sprint-2/scope-amendment-2026-05.md). The `catalog.json` artefact has no consumer in the v1.0 MVP MCP surface; the MCP tools query the SQLite store directly.
+
 `clarion analyze` emits `.clarion/catalog.json` — a deterministic, stable-shape dump of the entity catalog, edges, subsystems, and findings at run completion.
 
 **Rationale**: JSON is the universal interchange format; downstream consumers (dashboards, bespoke scripts, CI gates) can read the catalog without speaking SQLite. Deterministic output means git diffs reflect real changes, not run-to-run noise.
@@ -418,6 +453,8 @@ Human-readable outputs from `clarion analyze`.
 
 #### REQ-ARTEFACT-02 — Per-subsystem markdown + top-level index
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §3 (Box B.5 removed)](../../implementation/sprint-2/scope-amendment-2026-05.md). Subsystem rendering lands with WP4 in v1.1.
+
 `clarion analyze` emits `.clarion/catalog/<subsystem>.md` (one markdown file per subsystem) plus `.clarion/catalog/index.md` (top-level navigation). Markdown is generated from the store, not authored.
 
 **Rationale**: Markdown is the human-reading surface for cases where a human (reviewer, new team member) wants to read the catalog without running `clarion serve` or speaking MCP. Subsystem granularity matches how humans think about large codebases; the index makes discovery cheap.
@@ -440,6 +477,8 @@ Clarion reads project configuration from `clarion.yaml` at the repository root,
 
 #### REQ-CONFIG-02 — Profile presets (budget / default / deep / custom)
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP6 narrowed to on-demand `summary(id)` per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md)). Profile presets sit on top of the LLM dispatch + per-level policy that v1.0 does not ship.
+
 Clarion ships three named profiles (`budget`, `default`, `deep`) and supports `custom`. Each profile specifies per-level mode / model_tier / summary_length; `clarion.yaml:llm_policy.profile` picks one; `overrides` layer on top.
 
 **Rationale**: Named profiles make cost trade-offs legible. An operator saying "use `budget`" and getting 4× cost reduction with predictable depth loss is faster than tuning six per-level parameters; `custom` is the escape hatch for teams with specific needs.
@@ -448,6 +487,8 @@ Clarion ships three named profiles (`budget`, `default`, `deep`) and supports `c
 
 #### REQ-CONFIG-03 — Budget enforcement with preflight
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP6 narrowed; the Phase 0 dry-run / preflight estimator + run-level budget gate are part of the deferred batched pipeline). v1.0 reaches LLM cost only lazily via MCP `summary` per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md); there is no batch run for a preflight to estimate.
+
 `clarion analyze` computes a cost estimate from the dry-run and confirms with the user before dispatching (default `dry_run_first: true`). During the run, budget watchers enforce `max_usd_per_run` and `max_minutes`; exceeding either with `on_exceed: stop` halts dispatch and writes a partial manifest.
 
 **Rationale**: LLM cost surprise is a common failure mode for teams adopting LLM-assisted tooling. Preflight prevents "I just spent $400 to analyse my monorepo" incidents; in-flight enforcement bounds the worst case when estimates are wrong.
@@ -456,6 +497,8 @@ Clarion ships three named profiles (`budget`, `default`, `deep`) and supports `c
 
 #### REQ-CONFIG-04 — Per-level LLM policy
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP6 narrowed to on-demand `summary(id)` per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md)). Per-level policy is meaningful only when batched module/subsystem-tier summarisation exists.
+
 `clarion.yaml:llm_policy.levels.<level>` specifies `mode` (`batch | on_demand | off`), `model_tier` (`haiku | sonnet | opus`), and `summary_length`. Overrides match on `path` / `subsystem` / other criteria and layer per-level.
 
 **Rationale**: Different entity levels (function vs subsystem) warrant different cost / depth trade-offs. Per-level policy lets operators spend Opus tokens where they matter (subsystem synthesis) and Haiku tokens where they don't (per-function leaf summaries), with path-based overrides for exceptions.
@@ -532,6 +575,8 @@ The read-only HTTP surface exposed by `clarion serve`.
 
 #### REQ-HTTP-01 — Read endpoints for entities, findings, wardline, state
 
+> **v1.0 ships the [ADR-014](../adr/ADR-014-filigree-registry-backend.md) file-registry subset only**: `GET /api/v1/files`, `POST /api/v1/files:resolve`, `POST /api/v1/files/batch`, `GET /api/v1/_capabilities` (plus the ADR-034 authentication surface — see [REQ-HTTP-03](#req-http-03--registry-backend-http-trust-model)). The broader `/entities*`, `/findings`, `/wardline/declared`, `/state`, `/health`, `/metrics` catalogue documented below is deferred to v1.1 per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B for findings/wardline/entities; WP10 for `/state`, `/health`, `/metrics`). The endpoint list below documents the v1.1 target surface.
+
 Clarion exposes read-only HTTP endpoints: `GET /api/v1/entities`, `GET /api/v1/entities/{id}`, `GET /api/v1/entities/{id}/neighbors`, `GET /api/v1/entities/{id}/summary`, `GET /api/v1/entities/{id}/guidance`, `GET /api/v1/entities/{id}/findings`, `GET /api/v1/findings`, `GET /api/v1/wardline/declared`, `GET /api/v1/state`, `GET /api/v1/health`, `GET /api/v1/metrics` (Prometheus-compatible).
 
 **Rationale**: Sibling tools (Wardline in v0.2+, future dashboards, CI gates) consume Clarion's catalog via HTTP; MCP is not appropriate for cross-process state pulls. Read-only in v0.1 keeps the surface small.
@@ -540,19 +585,39 @@ Clarion exposes read-only HTTP endpoints: `GET /api/v1/entities`, `GET /api/v1/e
 
 #### REQ-HTTP-02 — Entity resolution oracle
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B Wardline state-file ingest + WP10 broader HTTP surface). The full multi-scheme oracle depends on Wardline state-file ingest landing for `wardline_qualname` / `wardline_exception_location` / `sarif_logical_location`; v1.0 resolves the `file_path` scheme only via [REQ-HTTP-01](#req-http-01--read-endpoints-for-entities-findings-wardline-state)'s `POST /api/v1/files:resolve` and `POST /api/v1/files/batch` per [ADR-014](../adr/ADR-014-filigree-registry-backend.md).
+
 `GET /api/v1/entities/resolve?scheme=<scheme>&value=<value>` translates from sibling-tool identity schemes (`wardline_qualname`, `wardline_exception_location`, `file_path`, `sarif_logical_location`) to Clarion entity IDs. Returns `{entity_id, kind, resolution_confidence: exact|heuristic|none, alternatives}`.
 
 **Rationale**: Enrichment-not-load-bearing (`CON-LOOM-01`): sibling tools consuming Clarion should ask in *their* native identity scheme, not embed Clarion's ID format. `resolve` exposes Clarion's internal translation layer as a public API so every sibling doesn't re-implement it.
 **Verification**: Contract test for each scheme; `resolution_confidence: none` returned as 200 with empty `entity_id` (not 404) so callers can distinguish absent-from-catalog vs. server-down.
 **See**: System Design §9 (Integrations, Entity resolve).
 
-#### REQ-HTTP-03 — Token auth (opt-in)
-
-Token auth is available via `clarion.yaml:serve.auth: token` (default: `none`). Tokens are 32 random bytes base64-encoded, prefixed `clrn_`, stored in OS keychain preferred / file-mode-0600 fallback. Wire format is `Authorization: Bearer clrn_<token>`; server-side uses constant-time comparison. Rotation via `clarion serve auth rotate` with a 24-hour grace window.
-
-**Rationale**: `clarion serve` runs on shared dev hosts and in CI containers (Wardline's consumption pattern). Loopback is not a security boundary on modern hosts (shared Docker networks, devcontainer proxies, DNS rebinding). Designing auth in v0.1 (even if opt-in by default) avoids retrofitting later.
-**Verification**: Token-protected endpoint returns 401 without header; rotation accepts both old and new within grace window; constant-time comparison verified via microbenchmark.
-**See**: System Design §9 (Integrations, HTTP Read API — Token auth).
+#### REQ-HTTP-03 — Registry-backend HTTP trust model
+
+For Filigree `registry_backend: clarion`, Clarion's HTTP read API is
+loopback-only by default. Non-loopback binds require **both**
+`serve.http.allow_non_loopback: true` **and** a resolved authentication secret
+— either HMAC identity via `serve.http.identity_token_env` (preferred per
+ADR-034) or a legacy bearer token via `serve.http.token_env`. A non-loopback
+bind with the opt-in but no resolved secret is refused at startup with
+`CLA-CONFIG-HTTP-NO-AUTH`. The loopback-without-token mode remains
+unauthenticated and emits a startup warning that any local process can read the
+catalogue; non-loopback no longer has an unauthenticated mode.
+
+**Rationale**: the ADR-014 read surface is a bounded local federation contract,
+not the earlier broad HTTP API. ADR-034 closes the original gap that permitted
+unauthenticated non-loopback binds behind the `allow_non_loopback` opt-in
+alone. The implementation prevents accidental network exposure mechanically and
+makes intentional non-loopback exposure fail closed without an authentication
+secret rather than silently warn-and-bind.
+**Verification**: `crates/clarion-cli/tests/serve.rs` covers the loopback
+default (line 1457), the loopback `identity_token_env`-resolution-failure
+refusal (line 1495), the non-loopback-without-auth startup refusal (line 1547),
+the non-loopback HMAC-required path (line 1579), and the non-loopback
+legacy-bearer path (line 1614). The loopback startup-warning surface is covered
+by config-layer tests.
+**See**: System Design §9 (Integrations, HTTP Read API), ADR-014, ADR-034.
 
 #### REQ-HTTP-04 — ETag-style response caching
 
@@ -570,6 +635,8 @@ Clarion's side of Filigree integration.
 
 #### REQ-INTEG-FILIGREE-01 — Findings via scan-results intake
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B). Lands with REQ-FINDING-03.
+
 Clarion POSTs findings to Filigree's `POST /api/v1/scan-results` using the native schema (see `REQ-FINDING-03`) with `scan_source: "clarion"`. Clarion inspects `response.warnings[]` on every POST for silent coercion / unknown-key drops.
 
 **Rationale**: Filigree's scan-results intake is the battle-tested cross-tool finding-exchange path; the warnings array is how Filigree signals schema drift. Ignoring warnings means silently shipping malformed findings.
@@ -578,14 +645,18 @@ Clarion POSTs findings to Filigree's `POST /api/v1/scan-results` using the nativ
 
 #### REQ-INTEG-FILIGREE-02 — Observation emission (HTTP preferred, MCP fallback)
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B). Clarion v0.1 surfaces structural and security findings via its own MCP `issues_for` tool (WP9-A); cross-product observation emission to Filigree lands with WP9-B.
+
 Clarion emits observations to Filigree via `POST /api/v1/observations` when available; falls back to MCP-client transport (spawning `filigree mcp` as subprocess) when the HTTP endpoint is absent. The fallback is signalled in the capability compat report.
 
-**Rationale**: Observations are fire-and-forget notes; Clarion generates them during analyse and consult. HTTP is the natural transport for a Rust binary emitting to a local Filigree; MCP is the v0.1 workaround while Filigree adds the HTTP endpoint (see `CON-FILIGREE-02`).
+**Rationale**: Observations are fire-and-forget notes; Clarion generates them during analyse and consult. HTTP is the natural transport for a Rust binary emitting to a local Filigree; MCP is the v0.1 workaround while Filigree adds the HTTP endpoint.
 **Verification**: HTTP path used by default; `--no-filigree-http` flag forces MCP fallback; both paths produce observations visible in Filigree.
 **See**: System Design §9 (Integrations, Filigree — Observations), §11 (Suite Bootstrap).
 
 #### REQ-INTEG-FILIGREE-03 — Registry-backend consumption
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B/WP10) and reflected in [CON-FILIGREE-02](#con-filigree-02--file-registry-displacement-is-deferred-to-v02). Filigree's `registry_backend` flag shipped (ADR-014); Clarion's read-side `RegistryProtocol` implementation is the v1.1 work. Clarion v0.1 ships shadow-registry only.
+
 When Filigree's `registry_backend` flag is set to `clarion`, Clarion serves as Filigree's file registry: Filigree consults Clarion's HTTP read API for file ID resolution; auto-create paths route through `RegistryProtocol` to Clarion. Absent the flag, Clarion operates in shadow-registry mode (findings POSTed normally; Filigree auto-creates `file_records` under its native rules).
 
 **Rationale**: File-registry displacement is the cleanest expression of "Clarion owns structural truth" (per Loom federation). The shadow-registry fallback preserves v0.1 shipability when Filigree hasn't yet landed `registry_backend`.
@@ -594,6 +665,8 @@ When Filigree's `registry_backend` flag is set to `clarion`, Clarion serves as F
 
 #### REQ-INTEG-FILIGREE-04 — `scan_source` namespace + schema pin test
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B). Lands with REQ-FINDING-03 (findings emission to Filigree); schema-pin test is moot until Clarion is actually POSTing.
+
 Clarion uses `scan_source: "clarion"` for emissions; CI runs a schema-compatibility test against a Filigree release's `GET /api/files/_schema` output to detect drift in `valid_severities`, `valid_finding_statuses`, `valid_association_types`.
 
 **Rationale**: Filigree's CHANGELOG flags breaking API changes but relies on social discipline; a pinned schema-compat test gives Clarion CI-level protection against silent schema shifts.
@@ -602,6 +675,8 @@ Clarion uses `scan_source: "clarion"` for emissions; CI runs a schema-compatibil
 
 #### REQ-INTEG-FILIGREE-05 — Capability-negotiation probe
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B). The capability probe is meaningful only once Clarion is talking to Filigree via the v1.1 cross-product surfaces (REQ-FINDING-03, REQ-INTEG-FILIGREE-02/03).
+
 At `clarion analyze` startup, Clarion probes Filigree's presence, version, `registry_backend` setting, and `/api/v1/observations` availability via `GET /api/files/_schema` + `HEAD` checks. Results emit in a single `CLA-INFRA-SUITE-COMPAT-REPORT` finding.
 
 **Rationale**: Partial Filigree versions are common (deployment skew). A single compat report collapses scattered runtime surprises into one auditable signal operators can read at the start of each run.
@@ -624,6 +699,8 @@ Clarion's Python plugin imports `wardline.core.registry.REGISTRY` at startup and
 
 #### REQ-INTEG-WARDLINE-02 — Manifest + overlay ingest
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B Wardline-config ingest). v1.0 ships only the [REQ-INTEG-WARDLINE-01](#req-integ-wardline-01--direct-registry-import-with-version-pin) runtime REGISTRY probe; state-file ingest (`wardline.yaml` + overlays) lands with the Wardline read-side bundle in v1.1.
+
 Clarion reads `wardline.yaml` and overlay files matching `src/**/wardline.overlay.yaml` at analyse time; declared tiers, groups, and boundary contracts become `WardlineMeta` properties on affected entities.
 
 **Rationale**: The manifest is Wardline's declarative source of truth; ingesting it makes tier/group/contract declarations available as entity metadata without re-implementing Wardline's parsing. Overlays let per-subsystem declarations compose cleanly.
@@ -632,6 +709,8 @@ Clarion reads `wardline.yaml` and overlay files matching `src/**/wardline.overla
 
 #### REQ-INTEG-WARDLINE-03 — Fingerprint ingest
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B Wardline-config ingest). Fingerprint ingest depends on the same state-file reader path deferred for [REQ-INTEG-WARDLINE-02](#req-integ-wardline-02--manifest--overlay-ingest); v1.0 has no `WardlineMeta.annotation_hash` population path.
+
 Clarion reads `wardline.fingerprint.json` at analyse time; each per-function `FingerprintEntry` becomes `WardlineMeta.annotation_hash` + `wardline_qualname` on the resolved entity. Unresolved fingerprint entries emit `CLA-INFRA-WARDLINE-FINGERPRINT-UNRESOLVED`.
 
 **Rationale**: Fingerprint provides the authoritative per-function annotation hash — without it, Clarion can't track drift between what Wardline enforces and what the code declares. Resolution failures must be visible (not silent) so operators can fix the mapping.
@@ -640,6 +719,8 @@ Clarion reads `wardline.fingerprint.json` at analyse time; each per-function `Fi
 
 #### REQ-INTEG-WARDLINE-04 — Exceptions ingest
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B Wardline-config ingest). Exceptions ingest depends on the same state-file reader path deferred for [REQ-INTEG-WARDLINE-02](#req-integ-wardline-02--manifest--overlay-ingest); v1.0 carries no `wardline.excepted` tag on briefings.
+
 Clarion reads `wardline.exceptions.json` at analyse time; entities referenced by active exceptions are tagged `wardline.excepted`. Unresolvable exception `location` strings emit `CLA-INFRA-WARDLINE-EXCEPTION-UNRESOLVED` and persist as dangling records with `entity_id: null`.
 
 **Rationale**: Exceptions are operator-curated decisions ("this finding is accepted"). Agents reading briefings for excepted entities should see "this has an active exception" as part of the picture; unresolvable exceptions are operator bugs that need visibility.
@@ -648,6 +729,8 @@ Clarion reads `wardline.exceptions.json` at analyse time; entities referenced by
 
 #### REQ-INTEG-WARDLINE-05 — SARIF baseline ingest for translator
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP10 SARIF translator). The translator surface (`clarion sarif import`) itself is deferred — see [REQ-INTEG-FILIGREE-04](#req-integ-filigree-04--sarif-import-translator) — so the baseline-ingest path it feeds is moot until WP10 lands.
+
 Clarion reads `wardline.sarif.baseline.json` (read-only) for the `clarion sarif import` translator path — the 663-result baseline is the source for Wardline-to-Filigree finding flow in v0.1.
 
 **Rationale**: Translator ownership lives Clarion-side in v0.1 (ADR-015); reading the baseline from disk keeps Wardline's dependency graph unchanged until it ships a native Filigree emitter in v0.2+.
@@ -656,6 +739,8 @@ Clarion reads `wardline.sarif.baseline.json` (read-only) for the `clarion sarif
 
 #### REQ-INTEG-WARDLINE-06 — Identity reconciliation across three schemes
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B Wardline-config ingest). The three-scheme oracle depends on fingerprint + exceptions ingest ([REQ-INTEG-WARDLINE-03](#req-integ-wardline-03--fingerprint-ingest) / [-04](#req-integ-wardline-04--exceptions-ingest)) populating `wardline_qualname` and `wardline_exception_location`; v1.0 resolves the `file_path` scheme only via [REQ-HTTP-01](#req-http-01--read-endpoints-for-entities-findings-wardline-state)'s `POST /api/v1/files:resolve` and `POST /api/v1/files/batch` per [ADR-014](../adr/ADR-014-filigree-registry-backend.md).
+
 Clarion maintains translation between three identity schemes: Clarion `EntityId`, Wardline `qualname`, Wardline exception-register `location` string. Reconciliation uses Wardline's `module_file_map` (from `ScanContext`) plus parsed location strings.
 
 **Rationale**: The three schemes arose independently and are not byte-equal for the same symbol. Clarion is the translator (Principle 3 — Wardline keeps its scheme; Clarion produces the join); exposing the translation via `GET /api/v1/entities/resolve` (`REQ-HTTP-02`) lets sibling tools consume it without embedding Clarion's ID format.
@@ -670,6 +755,8 @@ Clarion maintains translation between three identity schemes: Clarion `EntityId`
 
 #### NFR-PERF-01 — Elspeth-scale wall-clock budget
 
+> **Deferred to v1.1** per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) + [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md). The 60-min target includes Phase 4–6 LLM summarisation wall-clock, which is the deferred batched pipeline; v1.0 `clarion analyze` ends at Phase 3 and is bounded by Python plugin extraction + Leiden clustering only. Remains the v1.1 acceptance criterion when phases 4–6 land.
+
 `clarion analyze /home/john/elspeth` completes in ≤60 minutes (target ~38 minutes) on a representative developer machine (8+ cores, SSD, ≥16GB RAM).
 
 **Rationale**: 60 minutes is the psychological ceiling for a "run overnight or during lunch" batch tool; significantly above it pushes teams to run less often and lose feedback. The ~38-minute target is derived from the detailed-design's example run; the ceiling bounds estimation error.
@@ -740,13 +827,41 @@ Clarion structures prompts with explicit `<file_content trusted="false">...</fil
 **Verification**: Fixture with adversarial docstring; briefing schema-validates; `propose_guidance` call produces an observation, not a sheet; novel vocabulary surfaces as `CLA-FACT-VOCABULARY-CANDIDATE`.
 **See**: System Design §10 (Security, Prompt-injection).
 
-#### NFR-SEC-03 — Token auth storage on opt-in HTTP API
-
-When HTTP API auth is enabled, Clarion stores tokens in the OS keychain when available and falls back to `~/.config/clarion/token` with file-mode 0600 otherwise. The fallback path emits `CLA-INFRA-TOKEN-STORAGE-DEGRADED`.
-
-**Rationale**: File-mode 0600 is the Unix world-line for single-user secrets; OS keychain is better when available. Making the degradation explicit (rather than silent) tells operators when they're on the weaker path.
-**Verification**: Keychain-available host uses keychain; keychain-absent host falls back with finding.
-**See**: System Design §9 (HTTP Read API, Token auth), §10 (Security).
+#### NFR-SEC-03 — Non-loopback HTTP read API guard
+
+Clarion refuses to start the HTTP read API on a non-loopback bind unless **both**
+`serve.http.allow_non_loopback: true` is set **and** an authentication secret is
+resolved at startup — either an HMAC identity secret via
+`serve.http.identity_token_env` (preferred, per ADR-034) or a legacy bearer
+token via `serve.http.token_env`. A non-loopback bind with neither secret
+resolved fails closed at startup with `CLA-CONFIG-HTTP-NO-AUTH`. The
+startup-warning surface (endpoint unauthenticated; protect outside Clarion)
+applies only to the loopback-without-token mode, which remains the ADR-014
+default for the local sidecar case.
+
+**Rationale**: loopback is not a complete security boundary, but accidental
+network *exposure* without authentication is the highest-risk failure mode for
+the registry-backend surface. ADR-034 closes the original ADR-014 gap that
+permitted unauthenticated non-loopback binds behind the `allow_non_loopback`
+opt-in alone; the opt-in remains the gate that admits non-loopback binds at all
+but no longer admits them unauthenticated.
+**Verification**: `crates/clarion-cli/tests/serve.rs` covers the
+non-loopback-bind-without-opt-in refusal
+(`serve_rejects_non_loopback_http_bind_before_binding_without_opt_in`), the
+non-loopback-without-auth refusal
+(`serve_http_refuses_startup_on_non_loopback_without_token`), the
+`identity_token_env`-set-but-env-missing refusal
+(`serve_http_refuses_startup_when_identity_env_is_missing`), the HMAC-required
+request path (`serve_http_files_endpoint_requires_hmac_identity_when_configured`
+plus the wrong-secret rejection
+`serve_http_files_endpoint_rejects_wrong_hmac_identity`), the legacy-bearer
+request path (`serve_http_files_endpoint_requires_bearer_token_when_configured`
+plus the wrong-token rejection `serve_http_files_endpoint_rejects_wrong_token`
+and the batch-endpoint variant `serve_http_batch_requires_auth_when_configured`),
+and the unauthenticated `_capabilities` carve-out
+(`serve_http_capabilities_does_not_require_token`). Config-layer tests cover the
+loopback startup-warning surface.
+**See**: System Design §9 (HTTP Read API), §10 (Security), ADR-014, ADR-034.
 
 #### NFR-SEC-04 — Audit surface — security events as findings
 
@@ -842,6 +957,8 @@ Every `clarion analyze` emits exactly one `CLA-INFRA-SUITE-COMPAT-REPORT` findin
 
 #### NFR-COST-01 — Elspeth run budget target
 
+> **Deferred to v1.1** per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) + [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md). The $15 ± 50% target measures a full batched run including phases 4–6 LLM spend; v1.0 reaches LLM cost only lazily through MCP `summary`. Remains the v1.1 acceptance criterion when the batched pipeline lands.
+
 `clarion analyze /home/john/elspeth` costs $15 ± 50% in LLM spend (range: $7.50 - $22.50) at default profile with current Anthropic pricing.
 
 **Rationale**: Matches the detailed-design's example run. The ±50% band reflects estimator uncertainty (subsystem synthesis cost varies with clustering) plus pricing volatility; wider bands undermine operator trust.
@@ -858,6 +975,8 @@ After three consecutive runs without source or guidance changes, summary cache h
 
 #### NFR-COST-03 — Preflight cost estimate accuracy ±50%
 
+> **Deferred to v1.1** per [ADR-030](../adr/ADR-030-on-demand-summary-scope.md) + [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md). Preflight estimation lives in Phase 0 (dry-run) of the batched pipeline; v1.0 has no batch run to preflight. Couples to [REQ-CONFIG-03](#req-config-03--budget-enforcement-with-preflight).
+
 The dry-run cost estimate is within ±50% of actual spend on representative projects. Systematic under-estimation is worse than over-estimation (preflight should not encourage false confidence).
 
 **Rationale**: An estimate outside this range fails its purpose (preventing cost surprise). ±50% is tight enough to be useful, loose enough to be achievable with per-entity-level heuristics rather than full Opus pricing simulations.
@@ -941,12 +1060,14 @@ Clarion emits findings to Filigree via `POST /api/v1/scan-results` using Filigre
 **Rationale**: Filigree's scan-results endpoint is the production path; deviating requires Filigree work that is out of v0.1 scope. The `metadata` nesting and severity enum are existing Filigree semantics verified by recon.
 **See**: System Design §9 (Integrations, Filigree — Wire format).
 
-### CON-FILIGREE-02 — `registry_backend` flag is a hard dependency
+### CON-FILIGREE-02 — File-registry displacement is deferred to v0.2
+
+Clarion v0.1 does **not** displace Filigree's file registry. The "Clarion owns the file registry" story — Filigree's `registry_backend` flag + pluggable `RegistryProtocol` and Clarion serving as Filigree's registry backend — is deferred to v0.2 per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B + WP10). Filigree did ship the `registry_backend` flag during Sprint 2 (ADR-014); Clarion's read-side implementation of `RegistryProtocol` and the associated suite-compat reporting are the v0.2 work.
 
-Clarion v0.1's "Clarion owns the file registry" claim depends on Filigree shipping a `registry_backend` config flag + pluggable `RegistryProtocol`. Absent the flag, Clarion operates in shadow-registry mode (downgrade to "owns the entity catalog").
+In v0.1, Clarion operates in shadow-registry mode by default: Clarion owns its entity catalog; Filigree, when present, auto-creates `file_records` under its native rules. The two stores reference the same paths but neither delegates id allocation to the other. This is acceptable because Clarion v0.1's MVP MCP surface (the seven tools — `entity_at`, `find_entity`, `callers_of`, `execution_paths_from`, `summary`, `issues_for`, `neighborhood`) queries Clarion's own SQLite store directly and does not require registry coupling.
 
-**Rationale**: Filigree's four NOT-NULL `file_records(id)` foreign keys + three auto-create paths make the displacement a schema surgery, not a feature flag. Degraded mode preserves v0.1 shipability; full integration depends on Filigree's cadence.
-**See**: System Design §11 (Suite Bootstrap, Prerequisites named here).
+**Rationale**: Filigree's four NOT-NULL `file_records(id)` foreign keys + three auto-create paths make registry displacement a schema-surgery integration, not a feature flag — out of v0.1 scope per the scope amendment. Shadow mode preserves v0.1 shipability; full integration lands with the WP9-B/WP10 cluster in v0.2.
+**See**: System Design §11 (Suite Bootstrap), [ADR-014 — Filigree `registry_backend` flag and pluggable `RegistryProtocol`](../adr/ADR-014-filigree-registry-backend.md), [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md).
 
 ### CON-WARDLINE-01 — Wardline owns its REGISTRY
 
@@ -1141,4 +1262,4 @@ Wardline shipping a YAML/JSON descriptor of its REGISTRY (instead of requiring d
 
 ---
 
-**End of Clarion v0.1 requirements specification.**
+**End of Clarion v1.0 requirements specification.**
diff --git a/docs/clarion/1.0/reviews/gap-analysis-2026-05-24.md b/docs/clarion/1.0/reviews/gap-analysis-2026-05-24.md
new file mode 100644
index 00000000..e7f74abe
--- /dev/null
+++ b/docs/clarion/1.0/reviews/gap-analysis-2026-05-24.md
@@ -0,0 +1,348 @@
+# Clarion v1.0 — Requirements vs Implementation Gap Analysis
+
+**Date:** 2026-05-24 (live north-star — amendments applied as we work)
+**Scope:** 125 requirement IDs from `docs/clarion/1.0/requirements.md` audited against shipped code in `crates/`, `plugins/python/`, `tests/`, and `.github/workflows/`.
+**Inventory:** 51 REQ-* · 28 NFR-* · 8 CON-* · 25 NG-* · 13 cross-cutting (REQ-INTEG-*).
+**Status:** Supporting context only — not normative. See [`docs/clarion/1.0/README.md`](../README.md) for canonical-truth precedence.
+
+This document is the working north-star for v1.0 publish-ready cleanup. It evolves as amendments land. It tells you, today, where shipped code agrees with the spec, where it diverges by intentional deferral, where the spec drifted away from shipped behaviour, and where there is genuine uncovered scope to backfill before publish.
+
+## 0. Amendments applied this session
+
+### Session 1 — MCP/HTTP surface narrowing (2026-05-24 morning)
+
+| # | Action | Effect |
+|---|--------|--------|
+| 1 | Added "v1.0 ships 8-tool MVP subset" blockquote to `REQ-MCP-02`; full catalogue documented as v0.2 target. | `REQ-MCP-02` **P0 → Deferred**. |
+| 2 | Added "Deferred to v0.2" blockquote to `REQ-MCP-03` citing amendment §3+§4 + ADR-030. | `REQ-MCP-03` **P0 → Deferred**. |
+| 3 | Added "v1.0 ships ADR-014 file-registry subset" blockquote to `REQ-HTTP-01`. | `REQ-HTTP-01` **P0 → Deferred**. |
+| 4 | Added "Deferred to v0.2" blockquote to `REQ-HTTP-02`. | `REQ-HTTP-02` **P0 → Deferred**. |
+| 5 | "v1.0 ships subset" notes at `system-design.md` §8 Tool catalogue / §8 Exploration-elimination / §9 HTTP Endpoints. | Closes design-doc half of surface drift. |
+
+### Session 2 — broader amendment bundle (2026-05-24 afternoon)
+
+| # | Action | Effect |
+|---|--------|--------|
+| 6 | "Deferred to v0.2" blockquote on `REQ-MCP-01` (cursor session model). | **P1 Missing → Deferred** |
+| 7 | "v1.0 ships intrinsic bounds" blockquote on `REQ-MCP-04` (per-tool token budgets are v0.2). | **P2 Partial → Satisfied** |
+| 8 | "Deferred to v0.2" blockquote on `REQ-MCP-05` (write-effect tool consent gates). | **P1 Missing → Deferred** |
+| 9 | "Deferred to v0.2" blockquote on `REQ-MCP-06` (session persistence). | **P1 Missing → Deferred** |
+| 10 | "Deferred to v0.2" blockquote on `REQ-ARTEFACT-01` (B.4 removed). | already Deferred; now blockquoted |
+| 11 | "Deferred to v0.2" blockquote on `REQ-ARTEFACT-02` (B.5 removed). | already Deferred; now blockquoted |
+| 12 | "Deferred to v0.2" blockquote on `REQ-CONFIG-02/03/04` (WP6 narrowed). | already Deferred; now blockquoted |
+| 13 | Section-level "whole subsystem deferred" note on `REQ-GUIDANCE-*` (WP7 deferred). | -01 **Partial → Deferred**; -02..-06 **Missing → Deferred** |
+| 14 | Per-row "Deferred to v0.2" blockquotes on `REQ-BRIEFING-01/02/04/05/06` (WP6 narrowed per ADR-030). | -01 **Partial → Deferred**; -02/04/05/06 **Missing → Deferred** |
+| 15 | "Deferred to v0.2" blockquote on `NFR-PERF-01` (60-min target needs Phases 4–6). | **P1 Missing → Deferred** |
+| 16 | "Deferred to v0.2" blockquote on `NFR-COST-01` ($15 elspeth needs Phases 4–6). | **P1 Missing → Deferred** |
+| 17 | "Deferred to v0.2" blockquote on `NFR-COST-03` (preflight needs Phase 0). | **P1 Missing → Deferred** |
+| 18 | `system-design.md` UX-modes table: catalog-artefacts row flipped from "Shipped" to "v0.2 (deferred)". | Closes the stale `system-design.md:103` claim. |
+
+### Session 3 — checklist phase 1 (2026-05-24 evening)
+
+| # | Action | Effect |
+|---|--------|--------|
+| 19 | "Deferred to v0.2" blockquote on `REQ-INTEG-WARDLINE-02` (WP9-B manifest + overlay ingest). | **Missing → Deferred** |
+| 20 | "Deferred to v0.2" blockquote on `REQ-INTEG-WARDLINE-03` (WP9-B fingerprint ingest). | **Missing → Deferred** |
+| 21 | "Deferred to v0.2" blockquote on `REQ-INTEG-WARDLINE-04` (WP9-B exceptions ingest). | **Missing → Deferred** |
+| 22 | "Deferred to v0.2" blockquote on `REQ-INTEG-WARDLINE-05` (WP10 SARIF baseline ingest for translator). | **Missing → Deferred** |
+| 23 | "Deferred to v0.2" blockquote on `REQ-INTEG-WARDLINE-06` (three-scheme identity oracle, depends on -03/-04). | **Missing → Deferred** |
+| 24 | `CHANGELOG.md` known-limitations: appended Wardline state-file ingest line after the REGISTRY-import asterisk; enumerates -02..-06 and names WP9-B + WP10 as v0.2 landing surfaces. | Closes the release-notes drift surface. |
+| 25 | `NFR-SEC-03` verification line: replaced stale `serve.rs` line numbers (1457/1495/1547/1579/1614) with eight test-name citations covering opt-in refusal, no-auth refusal, env-missing refusal, HMAC + wrong-secret, bearer + wrong-token + batch variant, and `_capabilities` carve-out. | Verification citations are now name-stable, not line-fragile. |
+
+**Net effect after session 2 + checklist phase 1:** REQ Missing list now 4 (REQ-ANALYZE-03, REQ-CATALOG-07, REQ-PLUGIN-05, REQ-PLUGIN-06); the 5 REQ-INTEG-WARDLINE rows flipped Missing → Deferred when checklist 1.1–1.5 added the row-level blockquotes (2026-05-24 sweep). NFR Missing stays at 6 (NFR-OBSERV-01..04, NFR-COMPAT-01, NFR-COMPAT-02; plus NFR-OPS gaps). The list of genuine v1.0-publish-blocking code work is now small and actionable — §5 below.
+
+---
+
+## 1. Executive summary
+
+Clarion v1.0 is a credible release for its **stated minimum viable surface** — entity ingestion, plugin host, secret scanning, Phase-3 clustering, persistent storage, HMAC-authenticated HTTP read API for Filigree federation, and a small MCP tool set. The initial audit read it as materially narrower than `requirements.md` because the requirement doc had not been updated to reflect the 2026-05-16 Sprint-2 scope amendment. As of §0 amendments 1–4, the MCP and HTTP requirement rows now correctly document the v1.0 subset.
+
+After session 1's amendments, three patterns describe the remaining work:
+
+1. **Doc-drift cluster (text-only fixes, not code).** The Sprint-2 amendment deferred WP6 (LLM pipeline), WP7 (guidance authoring), WP9-B (Filigree finding emission), WP10 (SARIF translator), narrowed WP8 (MCP) to 8 tools, and removed the catalog-artefact boxes B.4/B.5. `REQ-FINDING-03..06` and `REQ-INTEG-FILIGREE-01..05` carry the "Deferred to v0.2" blockquote correctly; `REQ-MCP-02/03` and `REQ-HTTP-01/02` now carry it. **Still missing the blockquote:** `REQ-ARTEFACT-01/02`, `REQ-CONFIG-02/03/04`, `REQ-GUIDANCE-01..06`, `REQ-BRIEFING-01/02/04/05/06`, `REQ-MCP-04/05/06`. These all describe surface that the amendment deferred but whose requirement rows still read as v1.0 contract — the obvious next bundle (see §5 action #1b).
+2. **Whole pipeline phases absent (architectural deferral).** `clarion analyze` ends at Phase 3. Phase 0 (dry-run) and Phases 4–6 (LLM summarisation) drive `NFR-PERF-01`, `NFR-COST-01/03`, `REQ-BRIEFING-04/05`, the budget gate, and the preflight estimator. Summarisation happens lazily through MCP `summary` only per ADR-030. Once #1b lands, all of these reclassify Deferred — the work itself is genuinely v0.2.
+3. **Targeted code gaps outside any deferral.** A small set of v1.0-contract items that nobody amended out: `REQ-ANALYZE-03` (`--resume`), `REQ-CATALOG-04/07` (file git metadata, HEAD-SHA capture), `REQ-PLUGIN-05/06` (Python plugin import policy + decorator edges), `NFR-COMPAT-01` (Filigree schema-pin CI), `NFR-COMPAT-02` (Wardline probe pins wrong symbol), `NFR-OBSERV-01..04` (JSON logs / stats.json file / Prometheus / compat-report finding). These are the *actual* code work to publish v1.0 — once the amendments collapse the doc drift, this list is the punch list.
+
+**Disciplined areas (genuinely strong, no action):** plugin host (manifest enforcement, framing, jail, crash-loop breaker, structured host findings), secret scanner, Phase-3 Leiden clustering with seeded determinism, summary-cache 5-tuple key, HMAC + ADR-034 hardening surface, all 8 CON-* honoured (one with the minor `CodexCli` provider drift noted in §5), all 25 NG-* honoured (no scope creep into linter / file-watcher / multi-branch / SARIF / wiki territory).
+
+**Disciplined areas (genuinely strong):** plugin host (manifest enforcement, framing, jail, crash-loop breaker, structured host findings), secret scanner, Phase-3 Leiden clustering with seeded determinism, summary-cache 5-tuple key, HMAC + ADR-034 hardening surface, all 8 CON-* honoured (one with the minor `CodexCli` provider drift noted in §5), all 25 NG-* honoured (no scope creep into linter / file-watcher / multi-branch / SARIF / wiki territory).
+
+**Verdict tally** (after session 2 amendments):
+
+| Category | Total | Satisfied | Partial | Missing | Deferred | Δ from initial audit |
+|----------|------:|----------:|--------:|--------:|---------:|---------------------|
+| REQ-* (functional, non-INTEG) | 40 | 13 | 9 | 4 | 14 | Sat +1, Partial −4, Missing −4, Deferred +7 |
+| REQ-INTEG-* (cross-product) | 11 | 1 | 0 | 0 | 10 | Missing −5, Deferred +5 (checklist 1.1–1.5 sweep) |
+| NFR-* | 28 | 5 | 12 | 6 | 5 | Missing −3, Deferred +3 |
+| CON-* | 8 | 6 | 1 | 0 | 1 | unchanged |
+| NG-* (inverted: scope creep) | 25 | 25 honoured | 0 | 0 drift | — | unchanged |
+| **TOTAL** | **112** | **50** | **22** | **10** | **30** | |
+
+(Counts in §6 RTM rows are authoritative; the headline table sums them.)
+
+**Working plan:** §5 action #1c is done (checklist phase 1, 2026-05-24). The doc-drift workstream is complete; what's left is genuine code — §5 actions 2–7, tracked in [`v1.0-publish-checklist-2026-05-24.md`](./v1.0-publish-checklist-2026-05-24.md) phases 2–6. Once those empty out, the docs and the binary tell the same story and v1.0 is publish-ready.
+
+---
+
+## 2. Methodology
+
+Each requirement ID was traced via three sources, in this order:
+
+1. **Requirement text** — `docs/clarion/1.0/requirements.md`, including the per-requirement `Verification:` line.
+2. **Design trace bridge** — `**Addresses**:` headers in `docs/clarion/1.0/system-design.md` (twelve sections covering §2–§11; bridge density is good — every functional requirement in this audit had a navigable target).
+3. **Implementation** — corresponding code under `crates/clarion-core/`, `crates/clarion-storage/`, `crates/clarion-cli/`, `crates/clarion-scanner/`, `crates/clarion-mcp/`, `plugins/python/`, plus `.github/workflows/` and `tests/`.
+
+Each verdict was cross-checked against in-flight tracked work in Filigree (`get-ready` + `list-issues --status in_progress`, snapshot at `/tmp/clarion_gap_filigree_ready.json`) to avoid re-reporting known follow-ups as discoveries. Verdicts cite specific `file:line` evidence. Non-goals (NG-*) were checked **inverted** — confirming the codebase does *not* implement them — to detect scope creep.
+
+Verdict vocabulary:
+
+- **Satisfied** — code implements the requirement; verification test or behavioural artefact exists.
+- **Partial** — mechanism exists but is undermeasured, contract-divergent, or covers only part of the named surface.
+- **Missing** — no implementation; not deferred by any written carve-out.
+- **Deferred** — scope explicitly carved out of v1.0 by the Sprint-2 amendment, a Backlog ADR, or a `> **Deferred to v0.2**` blockquote in `requirements.md`.
+
+`Tracked` column values: `new` (file an issue), `tracked:<keyword>` (existing Filigree row covers this; merge into that work), `deferred:scope-amendment` (don't file).
+
+Audit was performed by six concurrent subagents (REQ slices A/B/C; NFR slices D/E/F) plus a seventh CON+NG audit (G), capped at three in flight, synthesised here.
+
+---
+
+## 3. Headline findings, by priority
+
+### 3.1 P0 — Resolved by session 1 amendments
+
+The initial audit flagged four P0 surface-mismatch findings: `REQ-MCP-02`, `REQ-MCP-03`, `REQ-HTTP-01`, `REQ-HTTP-02`. Investigation of the [Sprint-2 scope amendment](../../implementation/sprint-2/scope-amendment-2026-05.md) showed that all four were explicitly narrowed by the 2026-05-16 amendment (Box B.6 named the 8-tool MVP MCP surface; [ADR-014](../adr/ADR-014-filigree-registry-backend.md) defined the file-registry HTTP subset) but the requirement rows had never received the "Deferred to v0.2" blockquote that `REQ-FINDING-03..06` carries. **Session 1 added those blockquotes (see §0).** No code changes required for these four rows. The P0 list is now empty.
+
+The next-bundle of probably-same-shape rows is documented as §5 action #1b — they should be inspected against the amendment and either amended or escalated to genuine work, individually.
+
+### 3.2 P1 — Genuine v1.0 code gaps (post amendment sweep)
+
+After session 2, the P1 list is much shorter and entirely "real code work" — no remaining doc-drift hidden as severity.
+
+**Observability foundations (NFR-OBSERV-01..04).** Not deferred by any envelope. `tracing` initialised in plain text at `crates/clarion-cli/src/main.rs:69-76` with no `.json()`, no file sink, no rotation. The install template's `.gitignore` excludes `runs/*/log.jsonl` — a path nothing writes to. Stats live only in the SQLite `runs.stats` column; no `runs/<run_id>/stats.json` file lands. No Prometheus `/api/v1/metrics` endpoint *(this one will reclassify Deferred once REQ-HTTP-01 is propagated through NFR-OBSERV-03; it's part of the broader HTTP surface)*. No `CLA-INFRA-SUITE-COMPAT-REPORT` emitter. Three of four are direct v1.0 code work; one (`-03`) probably joins HTTP-01's deferral.
+
+**Schema/version compat (NFR-COMPAT-01/02).** Genuinely outside any deferral. NFR-COMPAT-01 = Filigree schema-pin CI test missing (one job). NFR-COMPAT-02 = Wardline probe pins `wardline.__version__` instead of `REGISTRY_VERSION`; named graceful-degradation findings have no emitter.
+
+**Python plugin gaps (REQ-PLUGIN-05/06).** TYPE_CHECKING block exclusion / `src.`-prefix canonicalisation / `python:unresolved:*` placeholders / `alias_of` edges / `decorated_by` / `inherits_from` / `uses_type` edges all absent. Not in any defer list — these are the v1.0 contract for the Python plugin's ontology coverage.
+
+**Three targeted REQ-* rows outside any envelope.** `REQ-ANALYZE-03` (`--resume` CLI flag + checkpoint reader), `REQ-CATALOG-07` (HEAD-SHA capture into `first_seen_commit`/`last_seen_commit` — columns exist, populated as `None`), `REQ-CATALOG-04` (file-entity git metadata).
+
+**Ops gaps (NFR-OPS-03/04).** `clarion db export --textual` + `db merge-helper` don't exist (NFR-OPS-03 — either build them or narrow the requirement); PyPI publish + SLSA-over-sdist outstanding (NFR-OPS-04, tracked under `clarion-f530101222`).
+
+### 3.3 P1 — Targeted gaps outside any deferral envelope
+
+- **REQ-ANALYZE-03 — `--resume`** has no CLI flag (`cli.rs:30`), no checkpoint reader, no `checkpoints.jsonl` consumer. Crash mid-run leaves `runs.status='running'` rows; rerun starts from scratch.
+- **REQ-CATALOG-07 — `first_seen_commit` / `last_seen_commit`** columns exist in `commands.rs:66` but every call-site in `analyze.rs` writes `None` (lines 813, 1619, 1692, 2156, 2348, 2417). No HEAD-SHA capture. Point-in-time queries return NULL.
+- **REQ-CATALOG-04 — file-entity git metadata** writes only `language` + `briefing_blocked`. `git_churn_count`, `git_last_modified`, `git_authors`, `size_bytes`, `line_count`, `mime_type` never populated (`analyze.rs:1544`).
+
+### 3.4 P2 — Implemented-but-unmeasured (no benchmarks, no recorded runs)
+
+`find tests/ -name 'bench*'` returns nothing; no `criterion` dependency anywhere. The following all have correct-shape mechanisms in code and lack only a measurement artefact:
+
+- NFR-PERF-02 (≤100 ms initialize, ≤50 ms p95 hot-cache summary): mechanisms correct (`lib.rs:176,256,788,1339-1367`), no harness.
+- NFR-SCALE-01 (elspeth ±20% entity count, no OOM): `EntityCountCap=500k` wired (`limits.rs:115`), no recorded elspeth run.
+- NFR-SCALE-02 (`.clarion/clarion.db` ≤2 GB): no size reporter, no measured run.
+- NFR-SCALE-03 (16-reader pool, no exhaustion): wired (`serve.rs:46`), saturation tested for max_size=1/2 only; no combined-load test.
+- NFR-COST-02 (≥95% summary-cache hit rate after 3 runs): mechanism correct (`cache.rs:48-110`), no `cache_hit_rate` aggregation in `stats.json`.
+
+Each could flip to Satisfied with a measurement task that does not require new product code.
+
+### 3.5 Documentation drift (text-only fixes)
+
+Status legend: ✅ done this session · ⏳ still open.
+
+- ✅ `system-design.md` §8 Tool catalogue + §8 Exploration-elimination + §9 HTTP endpoints — each now carries a "v1.0 ships subset" note.
+- ✅ `REQ-MCP-02 / REQ-MCP-03 / REQ-HTTP-01 / REQ-HTTP-02` — deferral blockquotes added.
+- ⏳ `requirements.md` still lacks "Deferred to v0.2" blockquotes on `REQ-ARTEFACT-01/02`, `REQ-CONFIG-02/03/04`, `REQ-GUIDANCE-01..06`, and probably `REQ-MCP-04/05/06` + `REQ-BRIEFING-04/05` — see §5 action #1b for the bundle.
+- ⏳ `system-design.md:103` still calls catalog artefacts "Shipped" though `grep -r catalog.json crates/` is empty; pair this fix with `REQ-ARTEFACT-*` amendments.
+- ⏳ `NFR-SEC-03` verification cites stale `serve.rs:798-803`; actual locations are `tests/serve.rs:1160,1194,1251,1285,1317`. Tracked under the ADR-034 refresh chain (clarion-7913f950d7, clarion-272b5bc1ec). Recommend replacing line citations with test-name citations to survive future refactors.
+- ⏳ `CHANGELOG.md` known-limitations enumerates the Wardline REGISTRY import asterisk but not Wardline state-file ingest (manifest/overlay/fingerprint/exceptions/SARIF baseline). Add to release notes.
+
+### 3.6 Quick-close wins (issues already done in HEAD)
+
+Per the standing "close already-done tickets" authorisation in user memory:
+
+- **`clarion-a4fb59a96a` — rollback runbook** — `docs/operator/v1.0-release-rollback.md` exists (141 lines).
+- **`clarion-42f4fee904` — loopback trust banner** — emitted at `crates/clarion-cli/src/http_read.rs:244-248`; documented at `docs/operator/clarion-http-read-api.md:58-73`.
+
+Both can transition through the full workflow to `closed`.
+
+### 3.7 One CON drift (governance, not severity)
+
+`CON-ANTHROPIC-01` says "Anthropic-only LLM provider in v0.1." `crates/clarion-mcp/src/config.rs:95-99` enumerates `OpenRouter`, `CodexCli`, `ClaudeCli`. `CodexCli` (`crates/clarion-cli/src/serve.rs:11`) shells out to OpenAI's Codex CLI — a non-Anthropic vendor surface. The constraint's prompt-caching rationale arguably doesn't apply to CLI shell-outs, which is probably why the drift went unflagged. Recommend either (a) amend the constraint to recognise local-CLI providers as a separate category, or (b) gate `CodexCli` behind a default-off cargo feature.
+
+---
+
+## 4. Strongest areas (no action required)
+
+- **Plugin host (REQ-PLUGIN-01..04, REQ-FINDING-01/02, NFR-SEC-01/05).** Content-Length framing (`transport.rs:113,287`), manifest enforcement (`host.rs:897,1043`), undeclared-kind drop tests (`host.rs:1586,2679`), crash-loop breaker (`breaker.rs:16`), entity cap and OOM kill (`limits.rs:115`), path-escape jail. Findings vocabulary (`Defect | Fact | Classification | Metric | Suggestion`) round-trips through a CHECK-constrained `findings` table; per-plugin `rule_id_prefix` works as designed. `.clarion/.gitignore` shipped by `install.rs:97`.
+- **Phase-3 Leiden clustering (REQ-CATALOG-05).** Seeded determinism asserted by `tests/analyze.rs:730 analyze_phase3_is_deterministic_across_two_runs`. Subsystem entities and `in_subsystem` edges flow through the writer-actor; e2e at `tests/e2e/phase3_subsystems.sh`.
+- **Summary-cache 5-tuple key (REQ-BRIEFING-03).** PK = `entity_id + content_hash + prompt_template_id + model_tier + guidance_fingerprint` exactly per ADR-007 (`cache.rs:9-72`; `migrations/0001_initial_schema.sql:151-164`). Round-trip tested.
+- **HMAC + ADR-034 federation surface (REQ-HTTP-03, NFR-SEC-03).** Six tests at `tests/serve.rs:1160..1342` cover loopback default, non-loopback-without-auth refusal, HMAC-required path, legacy bearer path, identity-env missing refusal. Code in `http_read.rs:179-251,389-498`.
+- **Secret scanner (NFR-SEC-01).** `crates/clarion-scanner/` + `crates/clarion-cli/src/secret_scan.rs` (574 LOC) with baseline justification + dedicated e2e at `tests/e2e/wp5_secret_scan.sh`.
+- **All 25 NG-* honoured.** No rule engine, no taint, no SARIF, no file watchers, no multi-branch, no wiki UI, no rename detection, no coverage ingestion, no second plugin, no plugin hash-pinning. The codebase shows real scope discipline.
+- **7 of 8 CON-* satisfied** (`CON-ANTHROPIC-01` partial drift noted in §3.7; CON-FILIGREE-01 properly Deferred).
+
+---
+
+## 5. Recommended next actions
+
+Sorted by leverage. Status legend: ✅ done · ⏳ pending. Each item names a target and a "why."
+
+| # | Status | Action | Target | Why |
+|---|--------|--------|--------|-----|
+| 1a | ✅ | Amendment pass on REQ-MCP-02/03 + REQ-HTTP-01/02 + system-design §8/§9 notes. | done 2026-05-24 | Closed surface-vs-doc P0 gap. |
+| 1b | ✅ | Amendment bundle on `REQ-MCP-01/04/05/06`, `REQ-ARTEFACT-01/02`, `REQ-CONFIG-02/03/04`, `REQ-GUIDANCE-01..06` (section header), `REQ-BRIEFING-01/02/04/05/06`, `NFR-PERF-01`, `NFR-COST-01/03` + retract `system-design.md:103` "Shipped" claim. | done 2026-05-24 | 17 rows; Missing list dropped from 19 → 4. |
+| 1c | ✅ | **Final amendment sweep.** `REQ-INTEG-WARDLINE-02..06` row-level blockquotes added; `CHANGELOG.md` known-limitations now enumerates Wardline state-file ingest alongside the REGISTRY-import asterisk; `NFR-SEC-03` verification swapped from stale line numbers to test-name citations. Done 2026-05-24 (checklist phase 1). | done | Closed the last amendment-deferred ambiguity; doc-drift workstream complete. |
+| 2 | ⏳ | Backfill the three uncovered REQ rows: `REQ-ANALYZE-03` (`--resume`), `REQ-CATALOG-07` (HEAD-SHA capture into `first_seen_commit` / `last_seen_commit`), `REQ-CATALOG-04` (git metadata on file entities). | v1.0 publish-ready | None deferred by any carve-out; storage substrate already shaped. |
+| 3 | ⏳ | Python plugin: implement `REQ-PLUGIN-05` (TYPE_CHECKING exclusion, src-prefix canonicalisation, `python:unresolved:*` placeholders, `alias_of` edges) + `REQ-PLUGIN-06` (`decorated_by`/`inherits_from`/`uses_type` edges). | v1.0 publish-ready | Not in any defer list; core ontology surface advertised at v1.0. |
+| 4 | ⏳ | Wardline probe — pin `REGISTRY_VERSION` (not `__version__`), emit `CLA-INFRA-WARDLINE-REGISTRY-ADDITIVE-SKEW` and `-MIRRORED` findings on version drift. | v1.0 publish-ready | Cheap fix, named in detailed-design.md:1169-1170, currently invisible. |
+| 5 | ⏳ | Add Filigree schema-pin CI job (`NFR-COMPAT-01`). | v1.0 publish-ready | One job; closes a P1 with low effort. |
+| 6 | ⏳ | Observability foundations: JSON-formatted tracing layer with file sink + rotation; `runs/<run_id>/stats.json` file emission alongside the SQLite column; `CLA-INFRA-SUITE-COMPAT-REPORT` emitter. `NFR-OBSERV-03` (Prometheus `/api/v1/metrics`) probably becomes Deferred — depends on broader HTTP surface already deferred via REQ-HTTP-01. | v1.0 publish-ready | Three NFR-OBSERV-* rows; one cohesive workstream. |
+| 7 | ⏳ | Add `clarion db export --textual` + `clarion db merge-helper` subcommands, or narrow `NFR-OPS-03` to reflect the commit-by-default-only scope. | v1.0 publish-ready | Currently the text overpromises. |
+| 8 | ⏳ | Publish `clarion-plugin-python` to PyPI and extend SLSA provenance to the sdist (existing ticket `clarion-f530101222`). | v1.0 publish-ready | Closes `pipx install clarion-plugin-python` per `NFR-OPS-04`. |
+| 9 | ⏳ | Decide on `CON-ANTHROPIC-01` × `CodexCliProvider`: either amend constraint or gate behind feature flag. | ADR or constraint amendment | Governance, not severity, but currently invisible drift. |
+| 10 | ⏳ | Close already-done Filigree issues per standing authorisation: `clarion-a4fb59a96a` (rollback runbook), `clarion-42f4fee904` (loopback banner). | Immediate | Both ship in HEAD; tickets are stale. |
+| 11 | ⏳ | Backlog: elspeth-scale measurement task — cargo bench harness for MCP latency, single recorded elspeth run capturing entity count + DB size + cache hit rate + stats.json. | post-publish, before 1.1 | Flips five P2 "implemented but unmeasured" verdicts to Satisfied without product code. |
+
+---
+
+## 6. Full RTM
+
+### 6.1 REQ-* (functional)
+
+| ID | Verdict | Evidence | Gap | Sev | Tracked |
+|----|---------|----------|-----|-----|---------|
+| REQ-ANALYZE-01 | Partial | `analyze.rs:54,485` | Phases 4–8 absent; no phase log | P2 | deferred:scope-amendment |
+| REQ-ANALYZE-02 | Partial | `analyze.rs:308`; writer serial | No LLM parallelism | — | deferred:scope-amendment |
+| REQ-ANALYZE-03 | **Missing** | `cli.rs:30` no flag | No `--resume`; no checkpoint reader | P1 | new |
+| REQ-ANALYZE-04 | Deferred | 0 `CLA-FACT-ENTITY-DELETED` emitters | Phase-7 entity-set diff | — | deferred:scope-amendment |
+| REQ-ANALYZE-05 | Deferred | 0 `CLA-FACT-TIER-SUBSYSTEM-MIXING` emitters | Phase-7 `CLA-*` rules | — | deferred:scope-amendment |
+| REQ-ANALYZE-06 | Partial | `breaker.rs:16`, `host_findings.rs`, `limits.rs` | Named rules `CLA-PY-PARSE-ERROR`/`-TIMEOUT`/`CLA-INFRA-LLM-ERROR`/`-BUDGET-WARNING` absent | P2 | new |
+| REQ-ANALYZE-07 | Partial | `tests/analyze.rs:730` | No `clarion db export --textual`; whole-catalog byte-id not verified | P3 | new |
+| REQ-ARTEFACT-01 | Deferred | no `catalog.json` emit | Doc drift: requirement lacks blockquote | — | deferred:scope-amendment |
+| REQ-ARTEFACT-02 | Deferred | no per-subsystem markdown | Doc drift: requirement lacks blockquote | — | deferred:scope-amendment |
+| REQ-BRIEFING-01 | Deferred (✅ amended §0 #14) | `llm_provider.rs:762-789` ships 4-field on-demand summary | rich 9-field `EntityBriefing` v0.2 per ADR-030 | — | deferred:scope-amendment |
+| REQ-BRIEFING-02 | Deferred (✅ amended §0 #14) | no impl | controlled vocab v0.2 with briefing pipeline | — | deferred:scope-amendment |
+| REQ-BRIEFING-03 | Satisfied | `cache.rs:9-72`; `migrations/0001_initial_schema.sql:151-164` | TTL pruner missing (sub-gap) | — | — |
+| REQ-BRIEFING-04 | Deferred (✅ amended §0 #14) | no `knowledge_basis` computation | depends on WP7 guidance + WP9-B triage | — | deferred:scope-amendment |
+| REQ-BRIEFING-05 | Deferred (✅ amended §0 #14) | no triage-into-briefing path | depends on WP9-B + WP7 | — | deferred:scope-amendment |
+| REQ-BRIEFING-06 | Deferred (✅ amended §0 #14) | no detail levels | per ADR-030 (briefing pipeline) | — | deferred:scope-amendment |
+| REQ-CATALOG-01 | Satisfied | `analyze.rs:382,794`; e2e | — | — | — |
+| REQ-CATALOG-02 | Satisfied | `host.rs:897`; `plugin.toml:38` | Positive "novel kind round-trip" test implicit | P3 | new |
+| REQ-CATALOG-03 | Satisfied | `migrations/0001_initial_schema.sql:81`; `host.rs:1043` | `guides`/`emits_finding` reserved; no producer | — | deferred:scope-amendment |
+| REQ-CATALOG-04 | Partial | `analyze.rs:1544` | git_churn/last_modified/authors/size/lines/mime never populated | P1 | new |
+| REQ-CATALOG-05 | Satisfied | `analyze.rs:657`; `clustering.rs`; `tests/analyze.rs:730` | — | — | — |
+| REQ-CATALOG-06 | Satisfied | `entity_id.rs`; `qualname.py` | Move-without-rename test missing | P3 | new |
+| REQ-CATALOG-07 | **Missing** | `commands.rs:66`; call-sites write `None` | No HEAD-SHA capture | P1 | new |
+| REQ-CONFIG-01 | Partial | `config.rs:16` | No `~/.config/clarion/defaults.yaml` merge; no `version:` field | P2 | new |
+| REQ-CONFIG-02 | Deferred | no `profile`/`budget`/`default`/`deep` enum | WP6 deferral | — | deferred:scope-amendment |
+| REQ-CONFIG-03 | Deferred | no dry-run estimator | WP6 + WP11 | — | deferred:scope-amendment |
+| REQ-CONFIG-04 | Deferred | no `LlmPolicyConfig` | WP6 | — | deferred:scope-amendment |
+| REQ-CONFIG-05 | Partial | `secret_scan.rs:574`; CLI flag | No `analysis.include`/`exclude` globs in config schema | P2 | new |
+| REQ-FINDING-01 | Satisfied | `commands.rs:113-133`; `migrations/0001_initial_schema.sql:104-135` | — | — | — |
+| REQ-FINDING-02 | Satisfied | `manifest.rs`; `limits.rs:37-54`; `pyright_session.py:34-41` | — | — | — |
+| REQ-FINDING-03 | Deferred | scope-amendment §3-4 | WP9-B v1.1 | — | deferred:scope-amendment |
+| REQ-FINDING-04 | Deferred | requirements.md:332 | WP10 SARIF translator | — | deferred:scope-amendment |
+| REQ-FINDING-05 | Deferred | requirements.md:342 | scan_run_id mapping | — | deferred:scope-amendment |
+| REQ-FINDING-06 | Deferred | requirements.md:352 | mark_unseen dedup | — | deferred:scope-amendment |
+| REQ-GUIDANCE-01 | Deferred (✅ amended §0 #13) | view substrate exists; no behaviour | WP7 deferred whole | — | deferred:scope-amendment |
+| REQ-GUIDANCE-02 | Deferred (✅ amended §0 #13) | `lib.rs:38 EMPTY_GUIDANCE_FINGERPRINT` placeholder | composition algo v0.2 | — | deferred:scope-amendment |
+| REQ-GUIDANCE-03 | Deferred (✅ amended §0 #13) | no CLI / no `propose_guidance` MCP | WP7 authoring surface v0.2 | — | deferred:scope-amendment |
+| REQ-GUIDANCE-04 | Deferred (✅ amended §0 #13) | no wardline_derived emitter | WP7 deferred | — | deferred:scope-amendment |
+| REQ-GUIDANCE-05 | Deferred (✅ amended §0 #13) | no churn-vs-guidance code | WP7 deferred | — | deferred:scope-amendment |
+| REQ-GUIDANCE-06 | Deferred (✅ amended §0 #13) | no `guidance export/import` CLI | WP7 deferred | — | deferred:scope-amendment |
+| REQ-HTTP-01 | Deferred (✅ amended §0 #3) | `http_read.rs:364-372` ships ADR-014 subset | broader catalogue v0.2 per amendment §4 | — | deferred:scope-amendment |
+| REQ-HTTP-02 | Deferred (✅ amended §0 #4) | `:resolve` handles file_path scheme only | multi-scheme oracle v0.2 (depends on WP9-B Wardline ingest) | — | deferred:scope-amendment |
+| REQ-HTTP-03 | Satisfied | `http_read.rs:179-251,389-498`; `tests/serve.rs:1160..1342` | — | — | tracked:adr-034-refresh |
+| REQ-HTTP-04 | Partial | `http_read.rs:735-816` | Uses `ETag` per-file vs spec'd `X-Clarion-State` run-level | P2 | new |
+| REQ-MCP-01 | Deferred (✅ amended §0 #6) | `lib.rs:187-211` no cursor/breadcrumb state | cursor session model v0.2 (B.6 narrowed surface) | — | deferred:scope-amendment |
+| REQ-MCP-02 | Deferred (✅ amended §0 #1) | `lib.rs:52-129` ships 8-tool MVP subset per amendment B.6 | broader catalogue v0.2 | — | deferred:scope-amendment |
+| REQ-MCP-03 | Deferred (✅ amended §0 #2) | no `find_entry_points` etc.; depends on Phase-7 pre-compute | shortcuts v0.2 per ADR-030 + amendment §4 | — | deferred:scope-amendment |
+| REQ-MCP-04 | Satisfied (✅ amended §0 #7) | `http_read.rs` execution_edge_cap; `lib.rs:74,93` bound 8-tool subset intrinsically | per-tool token budgets v0.2 (catalogue-deferred) | — | — |
+| REQ-MCP-05 | Deferred (✅ amended §0 #8) | no write-effect tools in 8-tool MVP surface | consent gate v0.2 with catalogue | — | deferred:scope-amendment |
+| REQ-MCP-06 | Deferred (✅ amended §0 #9) | `lib.rs:162-185` no session persistence | session model v0.2 with cursor (REQ-MCP-01) | — | deferred:scope-amendment |
+| REQ-PLUGIN-01 | Satisfied | `transport.rs:113,287,42,57-63`; `server.py:73,119` | — | — | — |
+| REQ-PLUGIN-02 | Satisfied | `manifest.rs:283,43`; `plugin.toml:38`; tests | Tags/prompt_templates absent (WP6) | — | — |
+| REQ-PLUGIN-03 | Partial | `host.rs:815`; `server.py:179,238` | `build_prompt` RPC + `file_list` absent (ADR-030 narrowed) | — | deferred:scope-amendment |
+| REQ-PLUGIN-04 | Partial | `plugin.toml`; extractor + resolvers | `protocol`/`global` kinds, `decorated_by`/`inherits_from`/`uses_type`/`alias_of` edges absent | P2 | new |
+| REQ-PLUGIN-05 | **Missing** | `reference_resolver.py:4` only type-imports TYPE_CHECKING | No exclusion / src-prefix / placeholders / aliases | P1 | new |
+| REQ-PLUGIN-06 | **Missing** | no `decorated_by` in `plugin.toml:40`; no emit-site | Decorator detection entirely absent | P1 | new |
+
+### 6.2 REQ-INTEG-* (cross-product)
+
+| ID | Verdict | Evidence | Gap | Sev | Tracked |
+|----|---------|----------|-----|-----|---------|
+| REQ-INTEG-FILIGREE-01 | Deferred | requirements.md:600 | WP9-B | — | deferred:scope-amendment |
+| REQ-INTEG-FILIGREE-02 | Deferred | requirements.md:610 | WP9-B observation emission | — | deferred:scope-amendment |
+| REQ-INTEG-FILIGREE-03 | Deferred | requirements.md:620 | Registry-backend consumption | — | deferred:scope-amendment |
+| REQ-INTEG-FILIGREE-04 | Deferred | requirements.md:630 | `scan_source` ns + schema pin | — | deferred:scope-amendment |
+| REQ-INTEG-FILIGREE-05 | Deferred | requirements.md:640 | Capability probe | — | deferred:scope-amendment |
+| REQ-INTEG-WARDLINE-01 | Satisfied | `wardline_probe.py:35-56`; `plugin.toml:55-56`; tests | Fail-soft only; no mirror module, no `MIRRORED` finding | P2 | tracked:clarion-88d2ef40b6 |
+| REQ-INTEG-WARDLINE-02 | Deferred | no `wardline.yaml` reader | WP9-B Wardline-config ingest | P2 | deferred:scope-amendment (row-level blockquote in `requirements.md:702`) |
+| REQ-INTEG-WARDLINE-03 | Deferred | `entities.wardline_json` always `None` | WP9-B | P2 | deferred:scope-amendment (row-level blockquote in `requirements.md:712`) |
+| REQ-INTEG-WARDLINE-04 | Deferred | no `wardline.exceptions.json` reader | WP9-B | P2 | deferred:scope-amendment (row-level blockquote in `requirements.md:722`) |
+| REQ-INTEG-WARDLINE-05 | Deferred | no `clarion sarif import` | WP10 | P2 | deferred:scope-amendment (row-level blockquote in `requirements.md:732`) |
+| REQ-INTEG-WARDLINE-06 | Deferred | no resolve oracle for wardline schemes | Depends on -03/-04 | P2 | deferred:scope-amendment (row-level blockquote in `requirements.md:742`) |
+
+### 6.3 NFR-*
+
+| ID | Verdict | Evidence | Gap | Sev | Tracked |
+|----|---------|----------|-----|-----|---------|
+| NFR-SEC-01 | Satisfied | `clarion-scanner/src/lib.rs`; `secret_scan.rs:212-263`; tests | — | — | — |
+| NFR-SEC-02 | Deferred | no `<file_content trusted="false">`, no schema validation | ADR-009 Backlog + WP6/WP7 | — | deferred:scope-amendment |
+| NFR-SEC-03 | Satisfied | `tests/serve.rs:1160..1317`; HMAC helper :2231 | Verification line citations stale | — | tracked:adr-034-refresh |
+| NFR-SEC-04 | Partial | `secret_scan/findings.rs:17`; `secret_scan.rs:36`; `breaker.rs:16` | `CLA-INFRA-TOKEN-STORAGE-DEGRADED`, `CLA-INFRA-BRIEFING-INVALID`, `CLA-SEC-VOCABULARY-CANDIDATE-NOVEL` absent | P2 | deferred:scope-amendment |
+| NFR-SEC-05 | Satisfied | `install.rs:97`; `tests/install.rs:40,45` | — | — | — |
+| NFR-RELIABILITY-01 | Partial | `pragma.rs:17-30`; writer-actor; `analyze_lock.rs` | No `--resume`; no SIGKILL+reopen test | P2 | partly deferred; tracked:STO-04 (clarion-ee22d1d72c) |
+| NFR-RELIABILITY-02 | Missing | no `--no-filigree`/`--no-wardline` flags; no `findings.jsonl` fallback | WP9-B | P2 | deferred:scope-amendment |
+| NFR-RELIABILITY-03 | Partial | `host_findings.rs:17-76`; `breaker.rs:16`; `analyze.rs:1355,2279` | LLM rate/budget/schema-invalid emitters absent; no PRAGMA integrity_check in e2e | P2 | partly deferred; tracked:STO-04 |
+| NFR-PERF-01 | Deferred (✅ amended §0 #15) | `analyze.rs:482-495` ends at Phase 3 | 60-min target needs Phases 4–6 per ADR-030 | — | deferred:scope-amendment |
+| NFR-PERF-02 | Partial | `lib.rs:176,256,788,1339-1367` | No benchmark harness | P2 | tracked:briefing_blocked index (clarion-bdabfd6bca) |
+| NFR-PERF-03 | Missing | no 20-turn token-budget assertion | Detail levels absent (BRIEFING-06) | P2 | new |
+| NFR-SCALE-01 | Partial | `limits.rs:115-165` `EntityCountCap=500k` | No recorded elspeth run | P2 | new |
+| NFR-SCALE-02 | Missing | no DB-size assertion or fixture | — | P3 | new |
+| NFR-SCALE-03 | Partial | `reader.rs:46-49`; `serve.rs:46`; `tests/reader_pool.rs` | No combined-load saturation test | P3 | new |
+| NFR-COST-01 | Deferred (✅ amended §0 #16) | per-call cost captured; no run-level budget gate | $15 elspeth target needs Phases 4–6 per ADR-030 | — | deferred:scope-amendment |
+| NFR-COST-02 | Partial | `cache.rs:48-110`; `lib.rs:788-792` | No `cache_hit_rate` aggregation; no repeat-run measurement | P2 | new |
+| NFR-COST-03 | Deferred (✅ amended §0 #17) | no preflight/dry-run code | Phase 0 deferred per ADR-030 | — | deferred:scope-amendment |
+| NFR-OPS-01 | Satisfied | `.github/workflows/release.yml:163,180,306,391` | Matrix 3 of 5 targets | P2 | new |
+| NFR-OPS-02 | Satisfied | no telemetry import; CHANGELOG | — | — | — |
+| NFR-OPS-03 | Partial | `install.rs:78-97` | No `clarion db export --textual` or `db merge-helper` subcommand | P1 | new |
+| NFR-OPS-04 | Partial | `pyproject.toml`; `release.yml:241` | Not on PyPI; SLSA covers rust only | P1 | tracked:slsa-python-sdist (clarion-f530101222) |
+| NFR-OBSERV-01 | Partial | `main.rs:69-76` plain-text tracing | No JSON, no file sink, no rotation, no per-run log | P1 | new |
+| NFR-OBSERV-02 | Partial | `analyze.rs:174,527,563,670`; `writer.rs:234,328` | `runs/<run_id>/stats.json` file never written | P1 | new |
+| NFR-OBSERV-03 | **Missing** | no Prometheus surface | — | P1 | new |
+| NFR-OBSERV-04 | **Missing** | no `CLA-INFRA-SUITE-COMPAT-REPORT` emitter | — | P1 | new |
+| NFR-COMPAT-01 | **Missing** | no Filigree schema-pin CI job | — | P1 | new |
+| NFR-COMPAT-02 | Partial | `wardline_probe.py:35`; `plugin.toml:50`; tests | Pins `__version__` not `REGISTRY_VERSION`; no `MIRRORED`/`ADDITIVE-SKEW` findings; no mirror fallback | P1 | new |
+| NFR-COMPAT-03 | Missing | no Anthropic SDK dependency | LLM path deferred | P3 | deferred:scope-amendment |
+
+### 6.4 CON-*
+
+| ID | Verdict | Evidence | Gap | Sev | Tracked |
+|----|---------|----------|-----|-----|---------|
+| CON-LOOM-01 | Satisfied | no cross-product mediator; `filigree.rs` is read-only client | — | — | — |
+| CON-FILIGREE-01 | Deferred | no `scan-results` POST | WP9-B | — | deferred:scope-amendment |
+| CON-FILIGREE-02 | Satisfied | no `RegistryProtocol` impl; shadow-registry only | — | — | — |
+| CON-WARDLINE-01 | Satisfied | `wardline_probe.py:38-43` direct import | Asterisk per loom.md §5 | — | — |
+| CON-ANTHROPIC-01 | Partial | `mcp/src/config.rs:95-99`; `cli/src/serve.rs:11` | `CodexCliProvider` is non-Anthropic vendor surface | Med | new (recommend ticket) |
+| CON-LOCAL-01 | Satisfied | CLI-only; LLM is only network egress | — | — | — |
+| CON-RUST-01 | Satisfied | trivially | — | — | — |
+| CON-SQLITE-01 | Satisfied | `rusqlite` + `deadpool-sqlite` | — | — | — |
+
+### 6.5 NG-* (inverted: all 25 honoured)
+
+All 25 non-goals returned the expected absence pattern. No drift detected. The codebase ships no rule engine, no taint, no SARIF export, no file watchers, no multi-branch analysis, no rename detection, no wiki UI, no second language plugin, no coverage ingestion, no advanced git analysis, no plugin hash-pinning, no triage-feedback loop, no Wardline HTTP state-pull, no BAR awareness, no Wardline annotation descriptor, no `EntityAlias`, no Phase-7 cross-cutting analyses, no incremental analysis, no Filigree server-side dedup. The two named asterisks (`docs/suite/loom.md` §5: Wardline REGISTRY import, Wardline pipeline coupling) remain exactly where the federation axiom documents them with the named retirement conditions still standing.
+
+---
+
+## 7. Appendix: how to reproduce this audit
+
+Source artefacts:
+
+- Per-agent partial reports: `/tmp/clarion_gap_{A,B,C,D,E,F,G}.md` (transient; regenerated each run).
+- In-flight Filigree snapshot: `/tmp/clarion_gap_filigree_ready.json` and `…_inprogress.json`.
+- Trace bridge: `**Addresses**:` headers in `docs/clarion/1.0/system-design.md` lines 38, 122, 243, 389, 482, 575, 664, 749, 846, 1056, 1139.
+
+The audit was executed by seven concurrent subagents (general-purpose, capped at three in flight) over `docs/clarion/1.0/requirements.md` + `docs/clarion/1.0/system-design.md` + `docs/clarion/1.0/detailed-design.md` + the workspace source. Verdicts cite specific `file:line` evidence so each row is independently re-verifiable.
diff --git a/docs/clarion/1.0/reviews/v1.0-publish-checklist-2026-05-24.md b/docs/clarion/1.0/reviews/v1.0-publish-checklist-2026-05-24.md
new file mode 100644
index 00000000..d8af08a2
--- /dev/null
+++ b/docs/clarion/1.0/reviews/v1.0-publish-checklist-2026-05-24.md
@@ -0,0 +1,151 @@
+# Clarion v1.0 — Publish-Ready Master Checklist
+
+**Date:** 2026-05-24
+**Source of truth:** [`gap-analysis-2026-05-24.md`](./gap-analysis-2026-05-24.md)
+**Definition of done:** every checkbox below ticked; requirements.md and shipped binary tell the same story; tracked Filigree issues for the remaining items closed or moved.
+**Status legend:** `[ ]` pending · `[~]` in progress · `[x]` done · `[-]` decided out-of-scope.
+
+This is the working punch list to take the v1.0.0 tag from "cut" to "publishable." Each item names the requirement IDs it addresses, the specific action, file paths where known, an effort estimate (S = <1 hour, M = half-day, L = ≥1 day), and a back-reference to the gap analysis row.
+
+---
+
+## Phase 1 — Doc cleanup (final sweep)
+
+The amendment work is 18 of 23 done. Five rows remain.
+
+- [x] **1.1 — Amend `REQ-INTEG-WARDLINE-02`** (S) — `> **Deferred to v0.2** … WP9-B Wardline-config ingest` blockquote added (`requirements.md:702`). → [gap §6.2](./gap-analysis-2026-05-24.md#62-req-integ--cross-product)
+- [x] **1.2 — Amend `REQ-INTEG-WARDLINE-03`** (S) — fingerprint ingest, blockquote added (`requirements.md:712`).
+- [x] **1.3 — Amend `REQ-INTEG-WARDLINE-04`** (S) — exceptions ingest, blockquote added (`requirements.md:722`).
+- [x] **1.4 — Amend `REQ-INTEG-WARDLINE-05`** (S) — SARIF baseline ingest, WP10 cited (`requirements.md:732`).
+- [x] **1.5 — Amend `REQ-INTEG-WARDLINE-06`** (S) — identity-reconciliation oracle, dependency chain on -03/-04 named (`requirements.md:742`).
+- [x] **1.6 — Update `CHANGELOG.md` known-limitations** (S) — appended after REGISTRY-import asterisk; lists -02..-06 and names WP9-B + WP10 as the v0.2 landing surfaces (`CHANGELOG.md:123-128`).
+- [x] **1.7 — Fix `NFR-SEC-03` verification line citations** (S) — replaced 1457/1495/1547/1579/1614 line numbers with test-name citations (`serve_rejects_non_loopback_http_bind_before_binding_without_opt_in`, `serve_http_refuses_startup_on_non_loopback_without_token`, `serve_http_refuses_startup_when_identity_env_is_missing`, `serve_http_files_endpoint_requires_hmac_identity_when_configured` + wrong-secret companion, `serve_http_files_endpoint_requires_bearer_token_when_configured` + wrong-token + batch companion, and the `serve_http_capabilities_does_not_require_token` carve-out). The three already-tracked ADR-034 refresh tickets (`clarion-7913f950d7`, `clarion-272b5bc1ec`, `clarion-461e78616f`) remain open for their own scope.
+
+**Exit criteria:** `grep -L "Deferred to v0.2" docs/clarion/1.0/requirements.md` matches expectations; no row claims v1.0 contract for deferred surface.
+
+---
+
+## Phase 2 — Targeted code backfills (REQ rows outside any deferral)
+
+Small, well-scoped Rust + Python changes. Storage substrate already shaped for each.
+
+- [ ] **2.1 — `REQ-ANALYZE-03` — `--resume`** (M) — add `--resume <run_id>` flag to `crates/clarion-cli/src/cli.rs:30` Analyze variant; implement checkpoint reader; verify `kill -9` mid-run → resume continues. Also closes NFR-RELIABILITY-01's verification surface. → [gap §3.3](./gap-analysis-2026-05-24.md#33-p1--targeted-gaps-outside-any-deferral-envelope)
+- [ ] **2.2 — `REQ-CATALOG-07` — HEAD-SHA capture** (S) — populate `first_seen_commit` / `last_seen_commit` columns in `crates/clarion-storage/src/commands.rs:66`. Call-sites currently write `None` at `crates/clarion-cli/src/analyze.rs` lines 813, 1619, 1692, 2156, 2348, 2417. Read `HEAD` once at BeginRun.
+- [ ] **2.3 — `REQ-CATALOG-04` — file-entity git metadata** (M) — populate `git_churn_count` / `git_last_modified` / `git_last_modified_sha` / `git_authors` / `size_bytes` / `line_count` / `mime_type` in `crates/clarion-cli/src/analyze.rs:1544` `core_file_entity_record`. `git_churn_count` is already a generated column in `migrations/0001_initial_schema.sql:266` — wire the source-JSON path.
+
+---
+
+## Phase 3 — Python plugin ontology coverage (REQ-PLUGIN-05/06)
+
+The single largest code-shaped P1 in the audit. Splits into two independent changes.
+
+- [ ] **3.1 — `REQ-PLUGIN-05` — import resolution policy** (L) — in `plugins/python/src/clarion_plugin_python/reference_resolver.py`:
+  - Detect and exclude `if TYPE_CHECKING:` blocks from runtime-import edges.
+  - Canonicalise `src.`-prefixed imports (strip when project layout uses src/).
+  - Emit `python:unresolved:<module.path>` placeholder entities for unresolvable imports.
+  - Emit `alias_of` edges for `__init__.py` re-exports (definition site wins).
+- [ ] **3.2 — `REQ-PLUGIN-06` — decorator detection policy** (L) — in `plugins/python/src/clarion_plugin_python/extractor.py`:
+  - Add `decorated_by` to `plugins/python/plugin.toml:40` edge kinds list.
+  - Detect decorators including factory invocations (`@app.route("/health")`), stacked (preserve order), class decorators, aliases (`validates = validates_shape`).
+  - Emit `decorated_by` edges with `properties` carrying decorator arguments.
+  - Also emit `inherits_from` (class hierarchy) and `uses_type` (type annotation references) — completes the v1.0 ontology declared in the plugin manifest.
+
+---
+
+## Phase 4 — NFR completeness
+
+Wardline probe + Filigree schema pin + observability foundations.
+
+- [ ] **4.1 — `NFR-COMPAT-02` — Wardline probe pinning fix** (S) — `plugins/python/src/clarion_plugin_python/wardline_probe.py:35` currently pins `wardline.__version__`; should pin `wardline.core.registry.REGISTRY_VERSION` per `detailed-design.md:1169-1170`. Also emit `CLA-INFRA-WARDLINE-REGISTRY-MIRRORED` on out-of-range and `CLA-INFRA-WARDLINE-REGISTRY-ADDITIVE-SKEW` on additive-newer skew. Add test in `plugins/python/tests/test_wardline_probe.py`.
+- [ ] **4.2 — `NFR-COMPAT-01` — Filigree schema-pin CI job** (S) — add a job to `.github/workflows/ci.yml` that fetches `GET /api/files/_schema` from a tagged Filigree release and asserts `valid_severities`, `valid_finding_statuses`, `valid_association_types` match the pinned fixture. Fixture location: `tests/fixtures/filigree-schema-pin.json`.
+- [ ] **4.3 — `NFR-OBSERV-01` — JSON structured tracing** (M) — switch `crates/clarion-cli/src/main.rs:69-76` from default `tracing_subscriber::fmt` to `.json()` formatter; add file sink writing to `.clarion/clarion.log`; add per-run sink writing to `.clarion/runs/<run_id>/log.jsonl` (path already in install template's `.gitignore` per `install.rs:97`). Rotation: 100MB × 5.
+- [ ] **4.4 — `NFR-OBSERV-02` — stats.json file emission** (S) — stats already computed at `crates/clarion-cli/src/analyze.rs:174,527,563,670` and persisted to `runs.stats` SQLite column. Add a tee that writes the same JSON to `.clarion/runs/<run_id>/stats.json` at CommitRun.
+- [ ] **4.5 — `NFR-OBSERV-04` — `CLA-INFRA-SUITE-COMPAT-REPORT` emitter** (M) — collect: Filigree availability (already probed), Wardline REGISTRY status (from 4.1), HMAC/loopback posture, SARIF schema (when Wardline ingest lands; for now report "not configured"). Emit one consolidated finding per `clarion analyze` run.
+- [-] **4.6 — `NFR-OBSERV-03` — Prometheus `/api/v1/metrics`** — **decision: defer**. Depends on the broader HTTP surface already deferred via REQ-HTTP-01 amendment. Bundle into a 1d amendment when convenient: add row-level "Deferred to v0.2 — depends on REQ-HTTP-01 broader HTTP surface" blockquote.
+
+---
+
+## Phase 5 — Ops / packaging
+
+- [ ] **5.1 — `NFR-OPS-03` decision — `clarion db` subcommand** (M, or amend to L decision) — either:
+  - **Build it:** add `clarion db export --textual` (deterministic SQL dump) + `clarion db merge-helper` (subcommand stub) to `crates/clarion-cli/src/`.
+  - **Narrow it:** amend `NFR-OPS-03` text to scope to "commit-by-default" only; defer export/merge-helper to v0.2.
+
+  Recommend the amendment path; the `db export --textual` surface is also referenced by REQ-ANALYZE-07 (determinism verification) and both could land together post-1.0.
+- [ ] **5.2 — `NFR-OPS-04` — PyPI publish + SLSA over sdist** (M) — tracked in Filigree as `clarion-f530101222`. Two parts:
+  - Publish `clarion-plugin-python` to PyPI (operator-doc'd install path changes from GitHub Release URL to `pipx install clarion-plugin-python`).
+  - Extend `release-subjects` job at `.github/workflows/release.yml:201` to include the sdist; SLSA generator at `:391` picks it up.
+- [ ] **5.3 — `NFR-OPS-01` matrix** (S, optional) — current 3-target matrix at `release.yml:163` covers macOS x86_64/aarch64 + Linux x86_64. `requirements.md:828` promises 5 targets (adds aarch64-linux + windows-x86_64). Either expand the matrix or narrow the requirement to the shipped 3.
+- [ ] **5.4 — Existing v1.0 blocker tickets to verify on this pass:**
+  - `clarion-22c35e1c44` — Enable live GitHub governance (branch protection, ruleset, RELEASE_GOVERNANCE_TOKEN).
+  - `clarion-cf3f018cf4` — Add ruleset for `refs/tags/v*` and tag-protection.
+  - `clarion-6a622d5f7e` — Ancestor-of-main check in release.yml verify.
+  - `clarion-316e9feef9` — Verify-published-release job after create-release.
+  - `clarion-ee22d1d72c` — PRAGMA `integrity_check` in e2e + documented backup procedure.
+  - `clarion-04ec1044e9` — Storage deployment constraints doc (NFS, double-analyze, backup).
+  - `clarion-d59fc0b798` — Pre-WP5 `.clarion/` upgrade requirement doc.
+
+---
+
+## Phase 6 — Tracker hygiene + governance
+
+- [ ] **6.1 — Close already-done Filigree issues** (S) — per standing authorisation in user memory; verify in HEAD before closing.
+  - `clarion-a4fb59a96a` — rollback runbook ships at `docs/operator/v1.0-release-rollback.md` (141 lines).
+  - `clarion-42f4fee904` — loopback trust banner emitted at `crates/clarion-cli/src/http_read.rs:244-248`; documented at `docs/operator/clarion-http-read-api.md:58-73`.
+- [ ] **6.2 — `CON-ANTHROPIC-01` × `CodexCliProvider` decision** (S, governance) — `crates/clarion-mcp/src/config.rs:95-99` enumerates `CodexCli` (non-Anthropic). Two options:
+  - **Amend constraint:** widen `CON-ANTHROPIC-01` in `requirements.md` to recognise local-CLI providers as a separate category alongside API providers.
+  - **Gate code:** put `CodexCli` behind a default-off `cargo` feature.
+  - Recommend amend — the constraint's prompt-caching rationale doesn't apply to CLI shell-outs.
+
+---
+
+## Phase 7 — Post-publish (immediately after tag, before any other work)
+
+Flips the five "implemented but unmeasured" P2 verdicts to Satisfied without writing product code.
+
+- [ ] **7.1 — Elspeth-slice measurement run** (M) — single recorded `clarion analyze /home/john/elspeth` run; capture entity count + DB size + cache hit rate + wall clock; commit `runs/<run_id>/stats.json` snapshot to `tests/fixtures/elspeth-scale-2026-05.json`. Satisfies NFR-SCALE-01, NFR-SCALE-02, NFR-COST-02 measurement gap.
+- [ ] **7.2 — Criterion benchmark harness for MCP latency** (M) — add `crates/clarion-mcp/benches/mcp_latency.rs` measuring `initialize` (≤100ms) + hot-cache `summary` p95 (≤50ms). Satisfies NFR-PERF-02.
+- [ ] **7.3 — Combined-load test for ReaderPool** (S) — extend `crates/clarion-storage/tests/reader_pool.rs` with a 16-reader scenario simulating the "1 consult agent + 1 Wardline-equivalent puller" load described in NFR-SCALE-03 design notes.
+
+---
+
+## Definition of done
+
+v1.0 is publish-ready when:
+
+1. Phases 1–6 are all `[x]` or `[-]`.
+2. `cargo nextest run --workspace --all-features` is green.
+3. `bash tests/e2e/sprint_1_walking_skeleton.sh` and `tests/e2e/sprint_2_mcp_surface.sh` and `tests/e2e/phase3_subsystems.sh` all pass.
+4. `gap-analysis-2026-05-24.md` §1 verdict tally has Missing = 0 in all categories.
+5. `requirements.md` Δ-from-this-checklist is empty (every row that needed a blockquote got one).
+6. `CHANGELOG.md` known-limitations section is complete and accurate.
+
+Phase 7 is post-publish and not gating.
+
+---
+
+## Sizing summary
+
+| Phase | Items | Effort total |
+|-------|------:|-------------:|
+| 1 — Doc cleanup | 7 | ~1 day (mostly S) |
+| 2 — REQ backfills | 3 | ~2 days |
+| 3 — Python plugin | 2 | ~3 days |
+| 4 — NFR completeness | 5 (+1 deferred) | ~3 days |
+| 5 — Ops/packaging | 4 | ~2 days |
+| 6 — Tracker hygiene | 2 | ~1 hour |
+| 7 — Post-publish | 3 | ~1.5 days |
+| **Total to publish** | **23** | **~11 dev-days** (Phases 1–6) |
+
+Phases 1, 4.1, 4.2, 5.3, 6.1, 6.2 can run in parallel and unlock most of the visible drift. Phase 3 (Python plugin) is the longest single workstream; if schedule-bound, it's the candidate to split into 3a (REQ-PLUGIN-05) + 3b (REQ-PLUGIN-06) with -05 prioritised (import resolution affects every analysis run's edge count; decorator coverage is additive value).
+
+---
+
+## Cross-references
+
+- Full verdict + evidence per requirement: [`gap-analysis-2026-05-24.md` §6](./gap-analysis-2026-05-24.md#6-full-rtm).
+- Amendment history: [`gap-analysis-2026-05-24.md` §0](./gap-analysis-2026-05-24.md#0-amendments-applied-this-session).
+- Sprint-2 scope amendment (the load-bearing precedent doc): [`docs/implementation/sprint-2/scope-amendment-2026-05.md`](../../implementation/sprint-2/scope-amendment-2026-05.md).
+- ADR-030 (on-demand summary scope, narrows WP6): [`docs/clarion/adr/ADR-030-on-demand-summary-scope.md`](../adr/ADR-030-on-demand-summary-scope.md).
+- ADR-014 (Filigree registry-backend HTTP read API scope): [`docs/clarion/adr/ADR-014-filigree-registry-backend.md`](../adr/ADR-014-filigree-registry-backend.md).
+- ADR-034 (HTTP read API hardening): [`docs/clarion/adr/ADR-034-federation-http-read-api-hardening.md`](../adr/ADR-034-federation-http-read-api-hardening.md).
diff --git a/docs/clarion/v0.1/system-design.md b/docs/clarion/1.0/system-design.md
similarity index 92%
rename from docs/clarion/v0.1/system-design.md
rename to docs/clarion/1.0/system-design.md
index 78add121..9fd1a71d 100644
--- a/docs/clarion/v0.1/system-design.md
+++ b/docs/clarion/1.0/system-design.md
@@ -1,7 +1,7 @@
-# Clarion v0.1 — System Design
+# Clarion v1.0 — System Design
 
-**Status**: Baselined for v0.1 implementation (post-ADR sprint 2026-04-18) — mid-level technical companion to requirements
-**Baseline**: 2026-04-17 · **Last updated**: 2026-04-18
+**Status**: Baselined for v1.0 release (carried forward from the v0.1 post-ADR-sprint baseline) — mid-level technical companion to requirements
+**Baseline**: 2026-04-17 · **Last updated**: 2026-05-19
 **Primary author**: qacona@gmail.com (with Claude)
 **Companion documents**:
 - [requirements.md](./requirements.md) — requirements (the *what*)
@@ -14,7 +14,7 @@
 
 ### What this document is
 
-This is Clarion v0.1's **system design** at mid-level technical depth. It describes how Clarion realises the requirements: component topology, data structures at a conceptual level, key mechanisms, integration contracts, and architectural decisions. It stops before implementation detail — SQL schemas, Rust crate choices, exact rule-ID catalogues, full YAML config examples, and JSON-RPC wire specifics live in the detailed-design reference.
+This is Clarion v1.0's **system design** at mid-level technical depth. It describes how Clarion realises the requirements: component topology, data structures at a conceptual level, key mechanisms, integration contracts, and architectural decisions. It stops before implementation detail — SQL schemas, Rust crate choices, exact rule-ID catalogues, full YAML config examples, and JSON-RPC wire specifics live in the detailed-design reference.
 
 ### How to read this
 
@@ -100,8 +100,8 @@ flowchart TB
 | Mode | Surface | Purpose | v0.1 status |
 |---|---|---|---|
 | MCP-for-LLM | `clarion serve` over stdio | First-class product surface — consult-mode agents hold a cursor, navigate the graph, emit observations to Filigree | Primary |
-| Catalog artefacts | `clarion analyze` writes `.clarion/catalog.json` + per-subsystem markdown | "I want to read the output" cases | Shipped |
-| Semi-dynamic wiki | HTML served by `clarion serve` | Live finding list, in-browser guidance editing, consult entry points | v0.2 (deferred — NG-13) |
+| Catalog artefacts | `clarion analyze` writes `.clarion/catalog.json` + per-subsystem markdown | "I want to read the output" cases | v1.1 (deferred — Sprint 2 amendment §3 removed boxes B.4/B.5; see [REQ-ARTEFACT-01](requirements.md#req-artefact-01--json-catalog-output) / [REQ-ARTEFACT-02](requirements.md#req-artefact-02--per-subsystem-markdown--top-level-index)) |
+| Semi-dynamic wiki | HTML served by `clarion serve` | Live finding list, in-browser guidance editing, consult entry points | v1.1 (deferred — NG-13) |
 
 ### Boundary contracts with the Loom siblings
 
@@ -199,7 +199,12 @@ Key fields:
 
 ### Plugin packaging
 
-v0.1 plugins distribute via their language's own packaging (Python → PyPI). Installation via `pipx install clarion-plugin-python` into an isolated venv so plugin dependencies don't conflict with the analysed project's. A user-level `~/.config/clarion/plugins.toml` records the resolved executable path plus the Python version requirement. Plugin hash-pinning is deferred (NG-16).
+v1.0 plugins distribute as GitHub Release assets. The Python plugin ships as a
+source distribution installed with `pipx install <release-asset-url>` into an
+isolated venv so plugin dependencies don't conflict with the analysed project's.
+A user-level `~/.config/clarion/plugins.toml` records the resolved executable
+path plus the Python version requirement. Public registry publishing and plugin
+hash-pinning are deferred (NG-16).
 
 ### Python plugin specifics
 
@@ -765,6 +770,8 @@ The scope lens shapes neighbour queries without changing their signatures:
 
 ### Tool catalogue by category
 
+> **v1.0 ships an 8-tool subset of this catalogue** per the [Sprint 2 scope amendment §3 (Box B.6)](../../implementation/sprint-2/scope-amendment-2026-05.md): `entity_at(file, line)`, `find_entity(pattern)`, `callers_of(id, confidence)`, `execution_paths_from(id, max_depth, confidence)`, `summary(id)`, `issues_for(id, include_contained)`, `neighborhood(id, confidence)`, plus `subsystem_members(id)` (added in Sprint 3 with WP4 Phase-3 clustering). The full categorical catalogue below — including the cursor-based Navigation model, write-effect Inspection tools, Search, Findings ops, Guidance (deferred with WP7), Session/scope — is the v1.1 target surface and is not present in v1.0. See [REQ-MCP-02](requirements.md#req-mcp-02--navigation-and-inspection-tool-catalogue) for the row-level deferral notice.
+
 **Navigation**: `goto(id)`, `goto_path(path, line?)`, `back()`, `zoom_out()`, `zoom_in(child_id)`, `breadcrumbs()`
 
 **Inspection**: `summary(id?, detail?)`, `source(id?, range?)`, `metadata(id?)`, `guidance_for(id?)`, `findings_for(id?, filter?)`, `wardline_for(id?)`
@@ -781,6 +788,8 @@ The scope lens shapes neighbour queries without changing their signatures:
 
 ### Exploration-elimination shortcuts (Principle 2)
 
+> **Deferred to v1.1** per the [Sprint 2 scope amendment](../../implementation/sprint-2/scope-amendment-2026-05.md) (Box B.6 narrowed the v1.0 MCP surface; WP4 Phase-7 cross-cutting analysis deferred). Shortcuts depend on batched pre-computation during analyze; v1.0 ships on-demand `summary` only ([ADR-030](../adr/ADR-030-on-demand-summary-scope.md)).
+
 Every common explore-agent question is a pre-computed shortcut:
 
 `find_entry_points(scope?)`, `find_http_routes(scope?)`, `find_cli_commands(scope?)`, `find_data_models(scope?)`, `find_config_loaders(scope?)`, `find_tests(scope?)`, `find_fixtures(scope?)`, `find_deprecations(scope?)`, `find_todos(scope?)`, `find_dead_code(scope?)`, `find_circular_imports(scope?)`, `find_coupling_hotspots(scope?)`, `recently_changed(since?, scope?)`, `high_churn(limit?, scope?)`, `what_tests_this(id)`
@@ -976,6 +985,8 @@ Translator behaviour:
 
 #### Endpoints
 
+> **v1.0 ships the [ADR-014](../adr/ADR-014-filigree-registry-backend.md) file-registry subset only**: `GET /api/v1/files`, `POST /api/v1/files:resolve`, `POST /api/v1/files/batch`, `GET /api/v1/_capabilities` (plus the [ADR-034](../adr/ADR-034-federation-http-read-api-hardening.md) authentication surface). The `/entities*` / `/findings` / `/wardline/declared` / `/state` / `/health` / `/metrics` catalogue below is the v1.1 target — deferred per the [Sprint 2 scope amendment §4](../../implementation/sprint-2/scope-amendment-2026-05.md) (WP9-B for entities/findings/wardline; WP10 for `/state`, `/health`, `/metrics`). The entity-resolve oracle ships only for the `file_path` scheme via `POST /api/v1/files:resolve`; the multi-scheme oracle below is also v1.1. See [REQ-HTTP-01](requirements.md#req-http-01--read-endpoints-for-entities-findings-wardline-state) and [REQ-HTTP-02](requirements.md#req-http-02--entity-resolution-oracle) for the row-level deferral notices.
+
 ```
 GET  /api/v1/entities?file=<path>&kind=<kind>&tag=<tag>
 GET  /api/v1/entities/{id}
@@ -999,27 +1010,42 @@ Why this exists: every sibling tool consuming Clarion should ask in *their* nati
 
 404 behaviour: returns 200 with `resolution_confidence: "none"` and empty `entity_id` — distinguishes "Clarion doesn't know this" from "Clarion is down."
 
-#### Authentication — UDS default, token fallback (ADR-012)
-
-Loopback is not a security boundary on modern dev hosts (shared containers, devcontainers, and other local processes all sit on 127.0.0.1). v0.1 defaults to Unix domain socket authentication so that filesystem permissions are the boundary, not network topology.
-
-**Default — UDS** (`serve.auth: uds`):
-- Binds `<project_root>/.clarion/socket` with mode 0600, owner = current UID.
-- HTTP/1.1 over UDS; no Bearer header required.
-- Only the owning UID can connect; shared-Docker / multi-user-host scenarios closed structurally.
-- No TCP bind at all — DNS-rebinding attack surface (T-05) is inapplicable.
-
-**Fallback — TCP + Bearer token** (`serve.auth: token`):
-- Auto-default on Windows (UDS support patchy until 10 1803+); explicit opt-in elsewhere for cross-UID-namespace access, SSH port-forwarding, or containerised clients.
-- `clarion serve` auto-mints `.clarion/auth.token` on first run (mode 0600, `clrn_<43 chars>` format).
-- OS keychain promotion via `clarion serve auth promote-to-keychain`.
-- Rotation via `clarion serve auth rotate` with 24-hour grace window.
-- Scoping: v0.1 has one project-wide read token; per-endpoint scoping is v0.2.
-
-**Explicit-none** (`serve.auth: none` or `--i-accept-no-auth`):
-- Allowed but loud: emits `CLA-INFRA-HTTP-AUTH-DISABLED` (severity ERROR) per serve startup; persistent warning banner in logs. For air-gapped CI with external ingress control or operators with strong local reasons.
-
-**CI integration**: `clarion check-auth --from wardline` returns exit 0 if the serve endpoint is reachable and authenticated under whichever mode is active. Wardline in CI picks up the token via `CLARION_TOKEN` env (preferred) or `.clarion/auth.token` bind-mount when in token mode.
+#### Authentication — ADR-014 registry-backend read API
+
+ADR-014 supersedes ADR-012 for the Filigree `registry_backend: clarion`
+HTTP read surface. The registry-backend API is unauthenticated and
+loopback-only by default. It refuses non-loopback binds unless
+`serve.http.allow_non_loopback: true`; that opt-in requires an
+operator-managed authenticated reverse proxy or equivalent access-control
+layer in front of Clarion.
+
+ADR-012's UDS/token design is retained as historical context for the earlier
+broad v0.1 HTTP API proposal, but it is not the implementation contract for the
+registry-backend file-resolution endpoint.
+
+Loopback is not a complete security boundary on modern dev hosts (shared
+containers, devcontainers, and other local processes all sit on 127.0.0.1).
+The ADR-014 stance accepts that local-read exposure for the bounded
+registry-backend API and prevents accidental network exposure through the
+non-loopback guard.
+
+**Default — loopback only**:
+- Binds only to loopback addresses.
+- No Bearer header or UDS transport is required for the ADR-014 endpoint.
+- Any local process that can reach the loopback port can read registry-backend
+  file-resolution responses.
+- Non-loopback binds are rejected unless explicitly allowed.
+
+**Explicit non-loopback**:
+- Requires `serve.http.allow_non_loopback: true`.
+- Startup logs must warn that the surface is unauthenticated.
+- Operators must front the endpoint with an authenticated reverse proxy or
+  equivalent access-control layer.
+
+**CI integration**: Filigree and other sibling consumers should treat
+`/api/v1/_capabilities` as the compatibility probe for the registry-backend
+read surface and should rely on deployment-level access control when the API is
+intentionally exposed beyond loopback.
 
 TLS is out of scope for v0.1. Operators wanting network exposure terminate TLS at a reverse proxy.
 
@@ -1044,7 +1070,7 @@ Security is a first-class concern in v0.1 because Clarion sends source code to a
 | Secret exfiltration to LLM provider | Critical | `.env`, test fixtures, committed API keys → entities → Anthropic API | Pre-ingest secret scanner; findings block LLM dispatch |
 | Prompt injection via source | Critical | Adversarial docstrings / comments → briefing field values → future-prompt poisoning via cache | Schema validation + untrusted-content delimiters + `knowledge_basis: static_only` |
 | Guidance poisoning via LLM-proposed sheets | High | `propose_guidance` MCP tool promotes attacker text into prompts | Manual promotion gate — proposals create observations, not sheets |
-| HTTP API reachable by other local processes | High | `clarion serve` on shared dev host / container | UDS default (mode 0600, UID-scoped); TCP+token fallback on Windows / cross-UID namespaces. See ADR-012. |
+| HTTP API reachable by other local processes | Medium | `clarion serve` on shared dev host / container | ADR-014 registry-backend API is unauthenticated but loopback-only by default; non-loopback binds are refused unless explicitly allowed and protected by operator-managed access control. |
 | DB tampering via committed `.clarion/clarion.db` | Medium | Bad actor edits DB, commits, poisons teammate briefings | Content-hash cross-check on load (v0.2); `clarion db verify` CLI |
 | LLM audit-log leakage via git | Medium | `runs/<run_id>/log.jsonl` contains request/response bodies | Default-excluded from git |
 | Personal API key charged when committing team DB | Medium (operator) | Developer commits DB generated with personal key | Operator guidance; `--audit-key` hint |
@@ -1096,8 +1122,7 @@ Every security-relevant event emits a finding:
 
 - `CLA-SEC-SECRET-DETECTED` — unredacted secret blocked LLM dispatch
 - `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` — operator overrode block
-- `CLA-INFRA-HTTP-AUTH-DISABLED` — `clarion serve` running with `serve.auth: none` (ADR-012); per-startup ERROR finding
-- `CLA-INFRA-TOKEN-STORAGE-DEGRADED` — OS keychain unavailable
+- `CLA-INFRA-HTTP-NON-LOOPBACK-UNAUTHENTICATED` — `clarion serve` running the ADR-014 HTTP read API on a non-loopback bind with `serve.http.allow_non_loopback: true`; per-startup WARN log
 - `CLA-INFRA-BRIEFING-INVALID` — schema validation failed twice (possible injection)
 - `CLA-SEC-VOCABULARY-CANDIDATE-NOVEL` — novel vocabulary tag proposed by LLM (light signal; mostly harmless)
 
@@ -1201,7 +1226,7 @@ The parallel listing in [detailed-design.md §11](./detailed-design.md#11-archit
 | ADR-009 | Structured briefings vs free-form prose | To author | P2 | Principle 2 requires bounded, composable responses; prose is neither. Schema validation also enables prompt-injection detection (schema-invalid → possible injection). |
 | ADR-010 | MCP as first-class surface — lock-in cost vs ecosystem reach | To author | P2 | Anthropic's MCP standard is the ecosystem's current centre of gravity for LLM tool integrations; lock-in cost is acknowledged but the ecosystem reach outweighs it for v0.1. Strategic review at v0.3+. |
 | [ADR-011](../adr/ADR-011-writer-actor-concurrency.md) | Writer-actor concurrency model (vs shadow-DB swap) | Accepted | P0 | Single writer actor + per-N-files transactions (default N=50) is the committed shape; `--shadow-db` opt-in for zero-stale-read scenarios. Design-review §2.2 CRITICAL flag retires. SQLite-concurrency-under-load assumption named as v0.2 validation task (`NG-28` proposed). |
-| [ADR-012](../adr/ADR-012-http-auth-default.md) | HTTP read-API auth: UDS default with TCP+token fallback | Accepted | P0 | v0.1 default is Unix domain socket (`.clarion/socket` mode 0600); Windows / cross-UID-namespace / SSH-forwarded cases fall back to TCP + auto-minted Bearer token. `serve.auth: none` emits `CLA-INFRA-HTTP-AUTH-DISABLED` ERROR per serve startup. Closes T-02 (risk 9) and structurally reduces T-05 in the primary path. Panel "three non-negotiable v0.1 controls" rec 1. |
+| [ADR-012](../adr/ADR-012-http-auth-default.md) | Historical HTTP read-API auth proposal: UDS default with TCP+token fallback | Superseded for ADR-014 registry-backend API | P0 | ADR-014 now owns the registry-backend HTTP read API posture: unauthenticated loopback-only by default, non-loopback refused unless explicitly allowed and protected externally. ADR-012 remains context for the earlier broad HTTP API proposal. |
 | [ADR-013](../adr/ADR-013-pre-ingest-secret-scanner.md) | Pre-ingest secret scanner with LLM-dispatch block | Accepted | P0 | Rust-native port of detect-secrets rule set (preserves NFR-OPS-04 single-binary). File-level block on detection; structural extraction preserved; briefings marked `briefing_blocked: secret_present`. `.clarion/secrets-baseline.yaml` for false-positives. `--allow-unredacted-secrets` requires TTY confirm OR explicit `--confirm-allow-unredacted-secrets=yes-i-understand` in CI. |
 | [ADR-014](../adr/ADR-014-filigree-registry-backend.md) | Filigree `registry_backend` flag + pluggable `RegistryProtocol` — schema surgery, not config flip | Accepted | P0 | Four NOT-NULL foreign keys on `file_records(id)` + three auto-create paths require a real interface, not a flag. Clarion's shadow-registry fallback preserves v0.1 shipability when Filigree hasn't landed the surgery. |
 | [ADR-015](../adr/ADR-015-wardline-filigree-emission.md) | Wardline→Filigree emission ownership: Clarion-side SARIF translator (v0.1), native Wardline POST (v0.2) | Accepted | P0 | Wardline has no HTTP client today (`integration-recon:339`); adding one is a refactor not on the v0.1 timeline. Clarion-side translator ships independently; translator stays permanent for Semgrep / CodeQL / etc. `loom.md` §5 asterisk 1 retires when native emitter lands. Revision trigger: Block C2 spike showing emitter is ≤1 day of work promotes to v0.1. |
@@ -1215,7 +1240,7 @@ The parallel listing in [detailed-design.md §11](./detailed-design.md#11-archit
 
 ### Writing cadence
 
-ADR-001 through ADR-004, ADR-006, ADR-007, ADR-011, ADR-012, ADR-013, ADR-014, ADR-015, ADR-016, ADR-017, ADR-018, ADR-021, and ADR-022 are authored and Accepted as standalone files in [../adr/](../adr/README.md). The remaining backlog items are ADR-005, ADR-009, ADR-010, ADR-019, and ADR-020; they stay summarised here and in the ADR index until the code that depends on them is ready to land. Any decision reversal during implementation (e.g., "writer-actor doesn't work; switching to shadow-DB") requires a new dated ADR revision, not an edit to the original.
+Most ADRs are now authored and Accepted as standalone files in [../adr/](../adr/README.md); ADR-008 is Superseded (by ADR-014); ADR-009, ADR-010, ADR-019, and ADR-020 remain backlog and stay summarised here and in the ADR index until the code that depends on them is ready to land. Additional Sprint-2-era ADRs (ADR-023 through ADR-032) were authored after this design layer was baselined; their summaries live in the ADR index rather than in this section. Any decision reversal during implementation (e.g., "writer-actor doesn't work; switching to shadow-DB") requires a new dated ADR revision, not an edit to the original.
 
 Authored ADR text (context, decision, alternatives considered, consequences, status) lives in [../adr/README.md](../adr/README.md). These summaries are the navigation aid; the canonical record of completed decisions is the ADR collection itself.
 
@@ -1245,4 +1270,4 @@ See [detailed-design.md](./detailed-design.md) Appendix B for the full glossary.
 
 ---
 
-**End of Clarion v0.1 system design.**
+**End of Clarion v1.0 system design.**
diff --git a/docs/clarion/README.md b/docs/clarion/README.md
index 50a347d3..7f283476 100644
--- a/docs/clarion/README.md
+++ b/docs/clarion/README.md
@@ -4,15 +4,15 @@ This folder holds Clarion product documentation.
 
 ## Read paths
 
-- Starting Clarion v0.1: [v0.1/README.md](./v0.1/README.md)
+- Starting Clarion v1.0: [1.0/README.md](./1.0/README.md)
 - Architecture decisions: [adr/README.md](./adr/README.md)
 
 ## Structure
 
-- [v0.1/](./v0.1/README.md) — current versioned spec set.
+- [1.0/](./1.0/README.md) — current versioned spec set.
 - [adr/](./adr/README.md) — authored architecture decision records and the remaining backlog.
 
 ## Canonical vs supporting
 
-- Canonical design docs for the current product version live under `v0.1/`.
-- Reviews and planning history live under the matching version in `reviews/` and `plans/`.
+- Canonical design docs for the current product version live under `1.0/`.
+- Reviews and planning history are archived under [../implementation/](../implementation/) — non-normative supporting context.
diff --git a/docs/clarion/adr/ADR-001-rust-for-core.md b/docs/clarion/adr/ADR-001-rust-for-core.md
index a6887675..a9d5a1c7 100644
--- a/docs/clarion/adr/ADR-001-rust-for-core.md
+++ b/docs/clarion/adr/ADR-001-rust-for-core.md
@@ -17,7 +17,7 @@ Clarion's core is responsible for:
 - SQLite-backed storage that serves both batch `clarion analyze` and long-lived `clarion serve` simultaneously (`CON-SQLITE-01`, ADR-011 writer-actor)
 - subprocess supervision for language plugins over Content-Length framed JSON-RPC (`REQ-PLUGIN-01`..`REQ-PLUGIN-06`, ADR-002)
 - bounded-cost LLM orchestration with per-run cache behaviour and cancellation semantics (`NFR-COST-01`..`NFR-COST-03`)
-- local HTTP and MCP serving with auth posture appropriate to a security tool (`NFR-SEC-*`, ADR-012)
+- local HTTP and MCP serving with a bounded trust posture (`NFR-SEC-*`, ADR-012 historically; ADR-014 for the registry-backend HTTP read API)
 
 The product posture is local-first and operationally lightweight (`CON-LOCAL-01`, `NFR-OPS-01`..`NFR-OPS-03`). The implementation language therefore affects packaging, concurrency, storage ergonomics, and deployment complexity — and the acceptable envelope for each is already set by requirements rather than preference.
 
diff --git a/docs/clarion/adr/ADR-002-plugin-transport-json-rpc.md b/docs/clarion/adr/ADR-002-plugin-transport-json-rpc.md
index 9e9cc97e..0ece6a13 100644
--- a/docs/clarion/adr/ADR-002-plugin-transport-json-rpc.md
+++ b/docs/clarion/adr/ADR-002-plugin-transport-json-rpc.md
@@ -102,4 +102,4 @@ We will use subprocess-based JSON-RPC 2.0 with explicit Content-Length framing.
 
 - [Clarion v0.1 system design](../v0.1/system-design.md)
 - [Clarion v0.1 detailed design](../v0.1/detailed-design.md)
-- [Clarion v0.1 design review](../v0.1/reviews/pre-restructure/design-review.md)
+- [Clarion v0.1 design review](../../implementation/v0.1-reviews/pre-restructure/design-review.md)
diff --git a/docs/clarion/adr/ADR-003-entity-id-scheme.md b/docs/clarion/adr/ADR-003-entity-id-scheme.md
index 0b6f363c..26692069 100644
--- a/docs/clarion/adr/ADR-003-entity-id-scheme.md
+++ b/docs/clarion/adr/ADR-003-entity-id-scheme.md
@@ -24,6 +24,14 @@ Path-embedded IDs make routine moves and re-exports detach cross-tool references
 
 We will identify source entities as `{plugin_id}:{kind}:{canonical_qualified_name}` and keep file path as a property rather than as part of the primary ID.
 
+File-kind entities use the same grammar. The core file entity ID is
+`core:file:{qualified_name}`. For file entities, `{qualified_name}` is the
+canonical project-relative file qualified name; it must not contain `@`.
+Content-hash-plus-path forms such as
+`core:file:{content_hash}@{canonical_path}` are non-conforming because they
+embed path and drift state into the primary ID instead of storing those values
+as entity properties.
+
 For v0.1:
 
 - definition site wins for canonical naming
@@ -97,4 +105,4 @@ For later versions:
 
 - [Clarion v0.1 system design](../v0.1/system-design.md)
 - [Clarion v0.1 detailed design](../v0.1/detailed-design.md)
-- [Clarion v0.1 design review](../v0.1/reviews/pre-restructure/design-review.md)
+- [Clarion v0.1 design review](../../implementation/v0.1-reviews/pre-restructure/design-review.md)
diff --git a/docs/clarion/adr/ADR-004-finding-exchange-format.md b/docs/clarion/adr/ADR-004-finding-exchange-format.md
index 9bc6512c..e06d0081 100644
--- a/docs/clarion/adr/ADR-004-finding-exchange-format.md
+++ b/docs/clarion/adr/ADR-004-finding-exchange-format.md
@@ -92,5 +92,5 @@ Specifically:
 
 - [Clarion v0.1 system design](../v0.1/system-design.md)
 - [Clarion v0.1 detailed design](../v0.1/detailed-design.md)
-- [Clarion v0.1 design review](../v0.1/reviews/pre-restructure/design-review.md)
-- [Clarion v0.1 integration recon](../v0.1/reviews/pre-restructure/integration-recon.md)
+- [Clarion v0.1 design review](../../implementation/v0.1-reviews/pre-restructure/design-review.md)
+- [Clarion v0.1 integration recon](../../implementation/v0.1-reviews/pre-restructure/integration-recon.md)
diff --git a/docs/clarion/adr/ADR-007-summary-cache-key.md b/docs/clarion/adr/ADR-007-summary-cache-key.md
index ece5ab52..8b316caf 100644
--- a/docs/clarion/adr/ADR-007-summary-cache-key.md
+++ b/docs/clarion/adr/ADR-007-summary-cache-key.md
@@ -165,5 +165,5 @@ Store `"sonnet"` instead of `"claude-sonnet-4-6"`.
 - [Clarion v0.1 detailed design §4 (Summary cache key design)](../v0.1/detailed-design.md) (lines 965-983) — the target this ADR formalises.
 - [Clarion v0.1 detailed design §3 schema — `summary_cache` table](../v0.1/detailed-design.md) (lines 679-691) — storage shape.
 - [Clarion v0.1 requirements — NFR-COST-01, NFR-COST-02, NFR-PERF-01](../v0.1/requirements.md) — cost/performance envelopes this cache design serves.
-- [Clarion v0.1 scope commitments — Q1](../v0.1/plans/v0.1-scope-commitments.md) (line 68) — v0.2 deferrals: cache optimisations beyond the simple shape.
-- [Clarion v0.1 scope commitments — Validation](../v0.1/plans/v0.1-scope-commitments.md) (lines 237-247) — empirical validation plan for NFR-COST-01/02 and the 95% hit-rate assumption this ADR depends on.
+- [Clarion v0.1 scope commitments — Q1](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) (line 68) — v0.2 deferrals: cache optimisations beyond the simple shape.
+- [Clarion v0.1 scope commitments — Validation](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) (lines 237-247) — empirical validation plan for NFR-COST-01/02 and the 95% hit-rate assumption this ADR depends on.
diff --git a/docs/clarion/adr/ADR-011-writer-actor-concurrency.md b/docs/clarion/adr/ADR-011-writer-actor-concurrency.md
index 6657f689..03932b1b 100644
--- a/docs/clarion/adr/ADR-011-writer-actor-concurrency.md
+++ b/docs/clarion/adr/ADR-011-writer-actor-concurrency.md
@@ -168,13 +168,13 @@ Already rejected in ADR-001 for the storage-engine selection. Re-cited here beca
 ## Related Decisions
 
 - [ADR-001](./ADR-001-rust-for-core.md) — Rust + `rusqlite` + `tokio` is the framework this ADR lives inside. `deadpool-sqlite` is named in ADR-001's ecosystem argument.
-- ADR-005 (pending) — `.clarion/` git-committable default. `clarion.db.new` (shadow-DB intermediate) must be `.gitignore`d; ADR-005 picks the exact ignore rules.
+- [ADR-005](./ADR-005-clarion-dir-tracking.md) — `.clarion/` git-committable default. `clarion.db.new` (shadow-DB intermediate) must be `.gitignore`d; ADR-005 picks the exact ignore rules.
 - [ADR-021](./ADR-021-plugin-authority-hybrid.md) — the per-run entity-count cap (Layer 2d) interacts with transaction granularity: the cap triggers a final flush and abort, which lands cleanly because per-N-files keeps the write path predictable.
 
 ## References
 
-- [Clarion v0.1 design review §2.2](../v0.1/reviews/pre-restructure/design-review.md) (lines 56-66) — original CRITICAL flag; writer-actor and shadow-DB options.
+- [Clarion v0.1 design review §2.2](../../implementation/v0.1-reviews/pre-restructure/design-review.md) (lines 56-66) — original CRITICAL flag; writer-actor and shadow-DB options.
 - [Clarion v0.1 detailed design §3 (Concurrency)](../v0.1/detailed-design.md) (lines 758-769) — the implementation detail this ADR formalises.
 - [Clarion v0.1 requirements §NFR-RELIABILITY-02](../v0.1/requirements.md) (line 857) — WAL + writer-actor + checkpoint discipline as crash-safety requirement.
 - [Clarion v0.1 system design §4 Storage](../v0.1/system-design.md) — SQLite rationale; WAL mode claim.
-- [Clarion v0.1 scope commitments — ADR sprint + validation](../v0.1/plans/v0.1-scope-commitments.md) (lines 181-195, 249-251) — P0 promotion from P1 and the explicit follow-up validation task.
+- [Clarion v0.1 scope commitments — ADR sprint + validation](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) (lines 181-195, 249-251) — P0 promotion from P1 and the explicit follow-up validation task.
diff --git a/docs/clarion/adr/ADR-012-http-auth-default.md b/docs/clarion/adr/ADR-012-http-auth-default.md
index dda4814d..bf719a00 100644
--- a/docs/clarion/adr/ADR-012-http-auth-default.md
+++ b/docs/clarion/adr/ADR-012-http-auth-default.md
@@ -1,12 +1,21 @@
 # ADR-012: HTTP Read-API Authentication — Unix Domain Socket Default with Token Fallback
 
-**Status**: Accepted
+**Status**: Superseded for the ADR-014 registry-backend HTTP read API
 **Date**: 2026-04-18
 **Deciders**: qacona@gmail.com
 **Context**: `clarion serve` exposes the read API to sibling tools; v0.1 panel threat-model scored the original `auth: none` default at risk 9 (T-02)
 
 ## Summary
 
+**2026-05-19 supersession note**: ADR-014 now owns the security posture for the
+Clarion HTTP read API used by Filigree's `registry_backend: clarion` mode. That
+surface is unauthenticated and loopback-only by default, refuses non-loopback
+binds unless `serve.http.allow_non_loopback: true`, and relies on an
+operator-managed authenticated reverse proxy or equivalent access-control layer
+for non-loopback exposure. The UDS/token design below remains historical context
+for the earlier broad v0.1 HTTP API proposal; it is not the implementation
+contract for the ADR-014 federation read surface.
+
 `clarion serve` defaults to **Unix domain socket** at `.clarion/socket` (mode 0600, owner = current UID). Filesystem permissions are the auth; no network bind, no Bearer tokens, no CAP_NET_BIND_SERVICE surface. When a UDS is unavailable (Windows, SSH-port-forwarded remote access, cross-UID-namespace containers), `serve.auth: token` falls back to TCP on `127.0.0.1:8765` + a Bearer token auto-minted at `.clarion/auth.token` (mode 0600). `serve.auth: none` remains configurable for operators who explicitly accept the unauthenticated-loopback posture, but now emits `CLA-INFRA-HTTP-AUTH-DISABLED` (severity ERROR) per serve startup and shows a persistent banner in logs. The default flip closes T-02 and structurally reduces T-05 (DNS rebinding) by eliminating the TCP bind in the primary path.
 
 ## Context
@@ -148,13 +157,13 @@ v0.1 tokens carry scope claims — read-only catalog, read-only findings, submit
 
 ## Related Decisions
 
-- ADR-005 (pending; see the [ADR index backlog](./README.md)) — `.clarion/` git-committable by default, but `.clarion/socket` and `.clarion/auth.token` are runtime artifacts that must be excluded. ADR-005 picks the `.gitignore` rules that protect against both.
+- [ADR-005](./ADR-005-clarion-dir-tracking.md) — `.clarion/` git-committable by default, but `.clarion/socket` and `.clarion/auth.token` are runtime artifacts that must be excluded. ADR-005 picks the `.gitignore` rules that protect against both.
 - [ADR-021](./ADR-021-plugin-authority-hybrid.md) — closes the plugin-side attack surface (T-01, T-08, T-11, T-12); this ADR closes the HTTP-side attack surface (T-02, T-05). Together they are the panel's "three non-negotiable v0.1 controls" (third being ADR-013, secret scanner).
 
 ## References
 
-- [Clarion v0.1 panel threat model T-02](../v0.1/reviews/panel-2026-04-17/09-threat-model.md) (line 233) — original risk scoring.
-- [Panel threat model §12 recommendation 1](../v0.1/reviews/panel-2026-04-17/09-threat-model.md) (line 298) — the specific "authenticated or not listening" prescription.
+- [Clarion v0.1 panel threat model T-02](../../implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md) (line 233) — original risk scoring.
+- [Panel threat model §12 recommendation 1](../../implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md) (line 298) — the specific "authenticated or not listening" prescription.
 - [Clarion v0.1 system design §10 "Loopback is not a security boundary"](../v0.1/system-design.md) — the paragraph this ADR flips; updated in the same commit.
-- [Clarion v0.1 detailed design §7 Token auth — full spec](../v0.1/detailed-design.md) (lines 1286-1304) — the token machinery this ADR reuses as the fallback.
-- [Clarion v0.1 scope commitments — action 5](../v0.1/plans/v0.1-scope-commitments.md) (line 199) — the commitment mandate.
+- [ADR-014](./ADR-014-filigree-registry-backend.md) — supersedes this ADR for the active registry-backend HTTP read API trust model.
+- [Clarion v0.1 scope commitments — action 5](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) (line 199) — the commitment mandate.
diff --git a/docs/clarion/adr/ADR-013-pre-ingest-secret-scanner.md b/docs/clarion/adr/ADR-013-pre-ingest-secret-scanner.md
index f1aa7119..1fffaf0e 100644
--- a/docs/clarion/adr/ADR-013-pre-ingest-secret-scanner.md
+++ b/docs/clarion/adr/ADR-013-pre-ingest-secret-scanner.md
@@ -189,8 +189,8 @@ Rely on operator discipline — "don't commit `.env` files"; add documentation.
 
 ## References
 
-- [Clarion v0.1 design review §3 (Secret exfiltration)](../v0.1/reviews/pre-restructure/design-review.md) (lines 88-91) — the CRITICAL flag this ADR retires.
-- [Clarion v0.1 panel threat model T-10](../v0.1/reviews/panel-2026-04-17/09-threat-model.md) (line 241) — risk scoring and residual-risk framing.
+- [Clarion v0.1 design review §3 (Secret exfiltration)](../../implementation/v0.1-reviews/pre-restructure/design-review.md) (lines 88-91) — the CRITICAL flag this ADR retires.
+- [Clarion v0.1 panel threat model T-10](../../implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md) (line 241) — risk scoring and residual-risk framing.
 - [Clarion v0.1 system design §10 (Pre-ingest redaction)](../v0.1/system-design.md) (lines 1044-1056) — the behaviour this ADR formalises.
 - [Clarion v0.1 requirements — NFR-SEC-01, NFR-SEC-05](../v0.1/requirements.md) — requirement floor.
 - [detect-secrets baseline format](https://github.com/Yelp/detect-secrets/blob/master/README.md#baseline-file) — the format this ADR's baseline layout matches.
diff --git a/docs/clarion/adr/ADR-014-filigree-registry-backend.md b/docs/clarion/adr/ADR-014-filigree-registry-backend.md
index ff3ba7ee..03e1b4cd 100644
--- a/docs/clarion/adr/ADR-014-filigree-registry-backend.md
+++ b/docs/clarion/adr/ADR-014-filigree-registry-backend.md
@@ -1,6 +1,6 @@
 # ADR-014: Filigree `registry_backend` Flag and Pluggable `RegistryProtocol`
 
-**Status**: Accepted
+**Status**: Accepted; partially extended by [ADR-034](./ADR-034-federation-http-read-api-hardening.md) (Security Posture and Error Envelope sections only — registry-backend protocol decision remains in force)
 **Date**: 2026-04-18
 **Deciders**: qacona@gmail.com
 **Context**: Clarion v0.1 integration boundary with Filigree's file registry; joint deliverable (Clarion + Filigree, same author)
@@ -29,7 +29,7 @@ Filigree introduces a `RegistryProtocol` trait with two implementations.
 
 **Mode `local` (default)**: Filigree's current behaviour. The three auto-create paths populate `file_records` using UUID-derived IDs. Filigree remains fully usable standalone — no Clarion dependency, no degradation.
 
-**Mode `clarion`**: Filigree delegates `file_id` resolution to Clarion's HTTP read API. The three auto-create paths call `RegistryProtocol::resolve_file(path, language) -> file_id` which, under `clarion` mode, issues an HTTP GET to Clarion's read API. The returned `file_id` is Clarion's symbolic entity ID (`core:file:{hash}@{path}`). The `file_records` row is created in Filigree with that ID, preserving the existing foreign-key structure.
+**Mode `clarion`**: Filigree delegates `file_id` resolution to Clarion's HTTP read API. The three auto-create paths call `RegistryProtocol::resolve_file(path, language) -> file_id` which, under `clarion` mode, issues an HTTP GET to Clarion's read API. The returned `file_id` is Clarion's symbolic file-kind entity ID (`core:file:{qualified_name}`). The `file_records` row is created in Filigree with that ID, preserving the existing foreign-key structure.
 
 **Flag surfacing**: `registry_backend` appears in `GET /api/files/_schema.config_flags`. Clarion's capability probe reads it at every `clarion analyze` start. Present + value `clarion` → proceed with delegation. Absent or value `local` → Clarion enters shadow-registry mode and emits `CLA-INFRA-FILIGREE-SHADOW-REGISTRY` per batch.
 
@@ -37,6 +37,112 @@ Filigree introduces a `RegistryProtocol` trait with two implementations.
 
 **Startup failure mode**: if Filigree starts with `registry_backend: clarion` but Clarion's read API is unreachable, Filigree refuses writes (returns `503 Service Unavailable` from the three auto-create paths) rather than silently degrading to `local`. An explicit `--allow-local-fallback` flag exists for single-operator recovery scenarios; the default is fail-closed.
 
+### Capability Probe Semantics
+
+Clarion's read API exposes `GET /api/v1/_capabilities` for Filigree's
+registry-backend probe. The response includes:
+
+```json
+{
+  "api_version": 1,
+  "instance_id": "9bd7234e-6d44-4a38-9ae4-76f912a10221",
+  "registry_backend": true,
+  "file_registry": true
+}
+```
+
+`api_version` is the wire-contract version for the HTTP read API. It increments
+only when the HTTP read API changes incompatibly for existing Filigree clients.
+It is not Clarion product semver and must not be compared as a release version.
+
+`instance_id` identifies the Clarion project instance serving the API. Filigree
+uses it to detect that the same endpoint has been rebound to a different
+Clarion project instance.
+
+### File Identity Semantics
+
+Clarion resolves only existing file-kind rows. When no `kind = 'file'` entity
+row exists for the requested path, the API fails closed with `404 NOT_FOUND`.
+Clarion must not synthesize a `core:file:{content_hash}@{canonical_path}`
+identity. That pattern violates ADR-003's entity-ID grammar and creates shadow
+IDs that will not match future file-discovery rows.
+
+### Batch Resolution Amendment
+
+Clarion also exposes `POST /api/v1/files:resolve` for callers that need to
+resolve many file paths without N HTTP round trips. The request body is
+`{"paths": [{"path": "...", "language": "..."}, ...]}` with a fixed
+1000-path envelope cap plus the normal HTTP body limit. The response preserves
+input order as `results[]`, where each entry carries the original `path` and a
+`response` object:
+
+- `status: "resolved"` with the same body shape as `GET /api/v1/files`.
+- `status: "not_found"` with the `NOT_FOUND` error envelope.
+- `status: "blocked"` with the `BRIEFING_BLOCKED` error envelope and no file
+  identity fields.
+- `status: "error"` with a per-path error envelope.
+
+This endpoint is a transport optimization, not a replacement for the single
+`GET /api/v1/files` URI model. ETag semantics remain single-GET only.
+
+### Canonical Path Semantics
+
+`canonical_path` is the normalized project-relative POSIX path for the file:
+
+- no leading `/`
+- no leading `./`
+- no trailing `/`
+- `/` as the separator on every platform
+
+The path is relative to the Clarion project root so file identity responses
+survive project relocation. It is the path Filigree should store as human and
+drift context, not an absolute filesystem path.
+
+### Instance Fingerprint
+
+Clarion persists a stable per-project UUID at `.clarion/instance_id`. The first
+creation writes the file with mode `0600` on Unix. `GET /api/v1/_capabilities`
+surfaces the UUID as `instance_id`.
+
+Deleting `.clarion/` may create a new instance ID. That is acceptable because it
+represents a new Clarion project instance and should be detectable by Filigree.
+
+### Error Envelope
+
+Non-2xx read API responses use a closed JSON envelope:
+
+```json
+{
+  "error": "path does not resolve to a Clarion file entity",
+  "code": "NOT_FOUND"
+}
+```
+
+The initial `ErrorCode` enum is closed to:
+
+- `INVALID_PATH`
+- `PATH_OUTSIDE_PROJECT`
+- `NOT_FOUND`
+- `UNAUTHENTICATED`
+- `STORAGE_ERROR`
+- `INTERNAL`
+
+Clients must switch on `code`, not on human-readable `error` text.
+
+### Security Posture
+
+The HTTP read API is loopback-only by default and may remain unauthenticated for
+local sidecar workflows. Authenticated deployments configure
+`serve.http.identity_token_env`; Clarion refuses to start if that env var is
+missing, and protected read routes require
+`X-Loom-Component: clarion:<hmac>`.
+
+The HMAC is lowercase hex HMAC-SHA256 over `METHOD`, `PATH_AND_QUERY`, and the
+SHA-256 request-body hash separated by newlines. Clarion refuses non-loopback
+HTTP binds unless `serve.http.allow_non_loopback: true` is set, and a
+non-loopback bind must have either the HMAC identity secret or the legacy bearer
+token resolved at startup.
+
 ## Alternatives Considered
 
 ### Alternative 1: Clarion-native registry without a flag — hard displacement
@@ -106,6 +212,7 @@ Accept that Filigree mints its own file IDs forever; Clarion reconciles post-hoc
 - [ADR-003](./ADR-003-entity-id-scheme.md) — symbolic entity IDs are what `clarion` mode uses as `file_records.id` values.
 - [ADR-004](./ADR-004-finding-exchange-format.md) — findings intake uses the same `file_id` that `resolve_file` returns.
 - ADR-008 (superseded) — earlier framing of this decision as a "feature flag"; the recon revealed it is an interface, not a flag.
+- [ADR-012](./ADR-012-http-auth-default.md) — superseded for this registry-backend HTTP read surface; ADR-014 owns the unauthenticated loopback-only trust model and non-loopback guard.
 - [ADR-016](./ADR-016-observation-transport.md) — the `create_observation(file_path=…)` auto-create path is one of the three delegated operations; under `registry_backend: clarion` mode the `file_id` resolution in that path uses this ADR's protocol regardless of whether ADR-016's transport is MCP-spawn (v0.1) or HTTP (v0.2).
 - [ADR-017](./ADR-017-severity-and-dedup.md) — `mark_unseen=true` dedup relies on stable file IDs, which `clarion` mode provides and shadow mode does not.
 - [ADR-018](./ADR-018-identity-reconciliation.md) — the qualname ↔ EntityId translation layer is adjacent; `clarion` mode's `file_id` resolution is one slice of the broader identity-reconciliation surface.
@@ -115,6 +222,6 @@ Accept that Filigree mints its own file IDs forever; Clarion reconciles post-hoc
 ## References
 
 - [Clarion v0.1 system design §9](../v0.1/system-design.md) — integration posture; capability probe; degraded modes.
-- [Integration reconnaissance §2.1](../v0.1/reviews/pre-restructure/integration-recon.md) — `file_records` schema; four NOT-NULL foreign keys; three auto-create paths; verified absence of `registry_backend` and error code.
+- [Integration reconnaissance §2.1](../../implementation/v0.1-reviews/pre-restructure/integration-recon.md) — `file_records` schema; four NOT-NULL foreign keys; three auto-create paths; verified absence of `registry_backend` and error code.
 - [Loom doctrine §4, §5, §6](../../suite/loom.md) — pairwise composability; enrichment failure test; no-shared-store rule.
-- [Clarion v0.1 scope commitments](../v0.1/plans/v0.1-scope-commitments.md) — Q2 commits `registry_backend` to v0.1 as within-scope Filigree work.
+- [Clarion v0.1 scope commitments](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) — Q2 commits `registry_backend` to v0.1 as within-scope Filigree work.
diff --git a/docs/clarion/adr/ADR-015-wardline-filigree-emission.md b/docs/clarion/adr/ADR-015-wardline-filigree-emission.md
index dd97f6ff..730c3b1d 100644
--- a/docs/clarion/adr/ADR-015-wardline-filigree-emission.md
+++ b/docs/clarion/adr/ADR-015-wardline-filigree-emission.md
@@ -1,6 +1,6 @@
 # ADR-015: Wardline→Filigree Emission Ownership — Clarion-Side Translator (v0.1), Native Wardline Emitter (v0.2)
 
-**Status**: Accepted
+**Status**: Accepted (Revision 2, 2026-05-29 — native Wardline emitter promoted to the production path; Clarion off the transport path. See [Revision 2](#revision-2-2026-05-29--wardline-ships-native-clarion-off-the-transport-path).)
 **Date**: 2026-04-18
 **Deciders**: qacona@gmail.com
 **Context**: Wardline has no HTTP client today; getting its findings into Filigree needs an owner for v0.1 and a retirement plan for v0.2
@@ -23,7 +23,7 @@ Three decisions exist inside the emission question:
 2. **When does Wardline gain a native path?** v0.2 default, or a v0.1 stretch-goal contingent on a cheap implementation?
 3. **What happens to the Clarion translator when Wardline gains native emission?** Does it retire entirely, or stay for other SARIF emitters?
 
-The default committed answers in `v0.1-scope-commitments.md:190` are: Option A for v0.1, Option B for v0.2 (default deferral, optional promotion pending spike), translator stays permanently for non-Wardline SARIF sources.
+The default committed answers in `../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md:190` are: Option A for v0.1, Option B for v0.2 (default deferral, optional promotion pending spike), translator stays permanently for non-Wardline SARIF sources.
 
 This ADR formalises those answers and names the revision trigger.
 
@@ -83,6 +83,22 @@ A research pass (code inspection only, no implementation) against `/home/john/wa
 
 Operators or maintainers reviewing this decision later: if the Wardline-native emitter is implemented as part of Clarion v0.1 work, revise this ADR with a dated "Revision 2" section, delete the `loom.md` §5 asterisk 1, and update the briefing's "Wardline-sourced findings" data-flow row.
 
+## Revision 2 (2026-05-29) — Wardline ships native; Clarion off the transport path
+
+**Trigger.** The 2026-05-29 Wardline ↔ Loom integration brief states that the generic Wardline rebuild intends to ship the **native Filigree emitter directly** (Wardline-side), emitting findings to `POST /api/v1/scan-results` from its own scanner path. This is the ~1-day emitter the 2026-04-18 spike already costed — now taken on Wardline-side rather than as Clarion v0.1 work. This revision records the flip the original decision and its closing note anticipated.
+
+**Position flip.** Option B (native Wardline emitter) becomes the production path for the (Wardline, Filigree) pair. **Clarion is no longer on the transport path for that pair.** The decision in §"v0.1 position — Clarion-side SARIF translator" is superseded for Wardline specifically; it stands unchanged for every other SARIF source.
+
+**What changes:**
+
+- **Clarion's role becomes pure enrichment.** Clarion reconciles Wardline findings to `EntityId`s via the qualname carried on the finding (`metadata.wardline.qualname`), per [ADR-018](./ADR-018-identity-reconciliation.md) and its 2026-05-29 amendment. It is no longer a bridge — it adds entity context to findings that reach Filigree on their own.
+- **The SARIF translator stays, general-purpose.** `clarion sarif import <file> --scan-source <name>` continues to serve Semgrep, CodeQL, Trivy, and any other SARIF emitter. `--scan-source wardline` remains usable for re-ingesting historical Wardline SARIF baselines, but is no longer the production Wardline path.
+- **Severity mapping moves off Clarion for Wardline.** The Wardline 4-level → Filigree 5-level mapping (integration brief §5: `CRITICAL→critical`, `ERROR→high`, `WARN→medium`, `INFO→low`, `NONE→info`) is now a direct Wardline→Filigree concern applied by the native emitter. [ADR-017](./ADR-017-severity-and-dedup.md)'s severity/rule-ID rules continue to apply to the translator for *other* SARIF sources; their role as the Wardline translation step retires with the transport path.
+
+**Asterisk-1 retirement — on ship, not on agreement.** `loom.md` §5 asterisk 1 (pipeline coupling of the (Wardline, Filigree) pair through Clarion) **is not deleted by this revision.** Wardline's generic build is in flight and the native emitter is not yet shipped or verified in production. Per `loom.md` §5 ("Asterisks are acceptable only with a written retirement condition"), deleting the asterisk on a promise is itself the failure mode the section guards against. This revision instead **rewrites the asterisk's retirement mechanism**: the native emitter is now Wardline-side (this brief), not the previously-planned Clarion-side v0.2 work. The asterisk stays live, tracked under `release:1.1`, and retires when the emitter ships and Wardline→Filigree composition is verified without Clarion present. At that point: delete asterisk 1 from `loom.md` §5 and update the briefing's "Wardline-sourced findings" data-flow row.
+
+**Open contract back to Wardline (does not block this decision).** Reconciliation correctness now depends on Wardline composing the dotted `module.qualified_name` with rules byte-identical to Clarion's `module_dotted_name()` — see the [ADR-018](./ADR-018-identity-reconciliation.md) 2026-05-29 amendment for the contract and the failure mode (silent degradation to `resolution_confidence: none` on nested-class and closure entities). This is an enrichment-quality concern, not a transport-path concern; the (Wardline, Filigree) pair composes regardless.
+
 ## Alternatives Considered
 
 ### Alternative 1: Make SARIF the direct Clarion/Wardline → Filigree contract (Filigree grows SARIF ingest)
@@ -167,6 +183,6 @@ A `loom-findings` package that both products import; the library owns emission t
 
 - [Loom doctrine §5 (v0.1 asterisks, asterisk 1)](../../suite/loom.md) — pipeline-coupling asterisk for (Wardline, Filigree) with this ADR as the retirement condition.
 - [Clarion v0.1 detailed design §9 (Wardline prerequisites) item 3](../v0.1/detailed-design.md) (line 1361) — Option A / Option B enumeration.
-- [Clarion v0.1 scope commitments](../v0.1/plans/v0.1-scope-commitments.md) (lines 72, 190, 202) — default deferral; spike promotion condition.
-- [Clarion v0.1 integration reconnaissance §4.3](../v0.1/reviews/pre-restructure/integration-recon.md) (line 339) — "Wardline has zero HTTP client code"; empirical basis for the v0.2 deferral default.
-- [Panel doctrine synthesis](../v0.1/reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md) — SARIF triangle framing; asterisk requirement.
+- [Clarion v0.1 scope commitments](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) (lines 72, 190, 202) — default deferral; spike promotion condition.
+- [Clarion v0.1 integration reconnaissance §4.3](../../implementation/v0.1-reviews/pre-restructure/integration-recon.md) (line 339) — "Wardline has zero HTTP client code"; empirical basis for the v0.2 deferral default.
+- [Panel doctrine synthesis](../../implementation/v0.1-reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md) — SARIF triangle framing; asterisk requirement.
diff --git a/docs/clarion/adr/ADR-016-observation-transport.md b/docs/clarion/adr/ADR-016-observation-transport.md
index 378111fa..1fa45d28 100644
--- a/docs/clarion/adr/ADR-016-observation-transport.md
+++ b/docs/clarion/adr/ADR-016-observation-transport.md
@@ -122,7 +122,7 @@ v0.1 does not emit observations. Observation generators (LLM-proposed guidance,
 
 ## References
 
-- [Clarion v0.1 scope commitments — Q1](../v0.1/plans/v0.1-scope-commitments.md) — observation HTTP transport explicitly deferred to v0.2.
+- [Clarion v0.1 scope commitments — Q1](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) — observation HTTP transport explicitly deferred to v0.2.
 - [Clarion v0.1 system design §9 (Observation transport)](../v0.1/system-design.md) (lines 916-921) — the passage reversed by this ADR; updated in the same commit.
 - [Clarion v0.1 system design §11 (Capability negotiation)](../v0.1/system-design.md) (lines 1122-1141) — observation HTTP presence moves from v0.1 fallback trigger to v0.2 feature-flag detection.
 - [Clarion v0.1 detailed design §9.1 Filigree prerequisites](../v0.1/detailed-design.md) (lines 1333-1351) — `POST /api/v1/observations` moved from "Required for v0.1 ship" to "Nice-to-have (v0.2+)".
diff --git a/docs/clarion/adr/ADR-017-severity-and-dedup.md b/docs/clarion/adr/ADR-017-severity-and-dedup.md
index a558a167..13f785b5 100644
--- a/docs/clarion/adr/ADR-017-severity-and-dedup.md
+++ b/docs/clarion/adr/ADR-017-severity-and-dedup.md
@@ -161,6 +161,6 @@ Clarion's internal records store `{critical, high, medium, low, info}` directly.
 ## References
 
 - [Clarion v0.1 detailed design §7](../v0.1/detailed-design.md) (lines 1163-1200) — the canonical mapping tables; this ADR formalises what's already there and fixes Issue 7.
-- [Clarion v0.1 integration reconnaissance §2.3, §2.4](../v0.1/reviews/pre-restructure/integration-recon.md) — empirical evidence for severity vocabulary and dedup key on Filigree's side (`db_schema.py` line numbers).
-- [Panel self-sufficiency review — Issue 7](../v0.1/reviews/panel-2026-04-17/04-self-sufficiency.md) (lines 132-134) — rule-ID namespace inconsistency this ADR resolves.
+- [Clarion v0.1 integration reconnaissance §2.3, §2.4](../../implementation/v0.1-reviews/pre-restructure/integration-recon.md) — empirical evidence for severity vocabulary and dedup key on Filigree's side (`db_schema.py` line numbers).
+- [Panel self-sufficiency review — Issue 7](../../implementation/v0.1-reviews/panel-2026-04-17/04-self-sufficiency.md) (lines 132-134) — rule-ID namespace inconsistency this ADR resolves.
 - [Clarion v0.1 requirements — REQ-FINDING-02, NG-21](../v0.1/requirements.md) — rule-ID namespace rule; v0.2 server-side per-entity dedup deferral.
diff --git a/docs/clarion/adr/ADR-018-identity-reconciliation.md b/docs/clarion/adr/ADR-018-identity-reconciliation.md
index aa6cb288..e306a129 100644
--- a/docs/clarion/adr/ADR-018-identity-reconciliation.md
+++ b/docs/clarion/adr/ADR-018-identity-reconciliation.md
@@ -57,6 +57,16 @@ the recorded `WardlineMeta` / translator output; naively splitting on dots is
 unsafe because dotted class chains and `<locals>` markers are part of Python's
 `__qualname__`, not the module path.
 
+### 2026-05-29 amendment: Wardline emits the dotted qualname pre-composed
+
+The 2026-05-29 Wardline ↔ Loom integration brief (§4.A) resolves the asymmetric-storage clash **in Clarion's favor at the emission boundary**. Under the generic Wardline rebuild's native Filigree emitter ([ADR-015](./ADR-015-wardline-filigree-emission.md) Revision 2), each emitted finding carries `metadata.wardline.qualname` as the **combined dotted `module.qualified_name`** (e.g. `auth.tokens.TokenManager.issue`) — Clarion's L7 form, not Wardline's `(file-path module, bare qualname)` storage pair.
+
+Two consequences:
+
+1. **A clarified entry point.** This is a fifth reconciliation surface alongside the four below: Clarion reads `metadata.wardline.qualname` off a **Filigree finding** (via the federation read path / `issues_for` enrichment), not off a Wardline state file. The composition rule reverses — the 2026-05-18 amendment's "Clarion composes the dotted module name from Wardline's `module`" becomes "**Wardline emits it pre-composed; Clarion matches by direct qualname equality**" (`find_entity` by qualname). The state-file entry points (1–3) and their composition rule remain unchanged for any path that still reads Wardline's on-disk artifacts (e.g. historical SARIF baselines).
+
+2. **The normalization contract is now Wardline's, at the emission boundary.** Because Wardline now performs the dotting Clarion used to do, byte-equality depends on Wardline replicating `module_dotted_name()` **exactly**: `src/` prefix stripped, `.py` removed, `__init__.py` collapsed (and the analogous handling for namespace-package / non-`src` layouts), while preserving `<locals>` markers and dotted class chains in `__qualname__` verbatim — those are part of the qualname, not the module path, and must not be re-dotted or stripped. If Wardline's composition diverges, reconciliation degrades silently to `resolution_confidence: heuristic | none` on exactly the nested-class and closure entities where it is least recoverable. Clarion exposes the canonical rules via `module_dotted_name()` and the `GET /api/v1/entities/resolve?scheme=wardline_qualname` oracle; a divergence shows up there as a non-`exact` resolution. This contract is the open ask-back to Wardline recorded in ADR-015 Revision 2; it is an enrichment-quality concern and does not gate the (Wardline, Filigree) transport path.
+
 ### Translation entry points (v0.1)
 
 1. **`wardline.fingerprint.json`**: for each `FingerprintEntry`, compute `(module, qualified_name) → EntityId` using Wardline's `module_file_map` (from `ScanContext`). Write `WardlineMeta.wardline_qualname = qualified_name` on the resolved Clarion entity.
@@ -169,4 +179,4 @@ Wardline exports its REGISTRY as a declarative descriptor file (`wardline_regist
 - [Clarion v0.1 system design §2 (Direct REGISTRY import), §9 (state-file ingest), §9 (Entity resolve oracle)](../v0.1/system-design.md) — import pattern, ingest paths, HTTP oracle.
 - [Clarion v0.1 detailed design §2 (Identity reconciliation across the suite)](../v0.1/detailed-design.md) (lines 553-571) — three-scheme translation table; ingest-path rules.
 - [Loom doctrine §5 (v0.1 asterisks), §6 (What Loom is NOT)](../../suite/loom.md) — initialization-coupling asterisk; "no identity reconciliation service" categorical.
-- [Panel doctrine synthesis](../v0.1/reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md) — the asterisks framing originated here.
+- [Panel doctrine synthesis](../../implementation/v0.1-reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md) — the asterisks framing originated here.
diff --git a/docs/clarion/adr/ADR-021-plugin-authority-hybrid.md b/docs/clarion/adr/ADR-021-plugin-authority-hybrid.md
index e0d2642b..dbf5ad62 100644
--- a/docs/clarion/adr/ADR-021-plugin-authority-hybrid.md
+++ b/docs/clarion/adr/ADR-021-plugin-authority-hybrid.md
@@ -137,15 +137,15 @@ Use cgroup v2 (`systemd-run --user --scope` or direct cgroup mounts) for per-plu
 ## Related Decisions
 
 - [ADR-002](./ADR-002-plugin-transport-json-rpc.md) — the subprocess transport is the enforcement surface for Content-Length ceiling and crash-loop counting. This ADR extends ADR-002's supervision loop with four specific violation subcodes.
-- ADR-012 (pending, rewritten for Block B) — the HTTP auth default flip closes T-02 the way this ADR closes T-08/T-11/T-12. The two ADRs form a matched pair covering the panel's "three non-negotiable v0.1 controls."
+- [ADR-012](./ADR-012-http-auth-default.md) — historical HTTP auth default decision. ADR-014 now owns the registry-backend HTTP read API posture; this ADR remains the plugin-side counterpart to the HTTP-side threat-model work.
 - [ADR-013](./ADR-013-pre-ingest-secret-scanner.md) — pre-ingest secret scanner covers T-10 (source + secrets exfiltration); this ADR's path-jail prevents a plugin from bypassing the scanner by reading outside `project_root`, and ADR-013's scanner runs on the file list this ADR's path-jail has already filtered.
 - [ADR-022](./ADR-022-core-plugin-ontology.md) — data-layer authority counterpart. This ADR's Layer 2 enforces at the transport/pipeline layer; ADR-022 enforces at the ontology layer (manifest-declared kinds, rule-ID namespacing). Both share the manifest-acceptance checkpoint.
 
 ## References
 
-- [Panel threat-model review §7 (risk matrix)](../v0.1/reviews/panel-2026-04-17/09-threat-model.md) — T-01, T-08, T-11, T-12 scorings.
-- [Panel threat-model review §8, §12](../v0.1/reviews/panel-2026-04-17/09-threat-model.md) — missing controls (1); three non-negotiable v0.1 controls (2).
+- [Panel threat-model review §7 (risk matrix)](../../implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md) — T-01, T-08, T-11, T-12 scorings.
+- [Panel threat-model review §8, §12](../../implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md) — missing controls (1); three non-negotiable v0.1 controls (2).
 - [Clarion v0.1 system design §10](../v0.1/system-design.md) — threat model summary table; `Defences NOT in v0.1` (seccomp/landlock deferred).
 - [Clarion v0.1 detailed design §1.3](../v0.1/detailed-design.md) (lines 56-145) — plugin manifest shape; crash-loop circuit breaker.
-- [Clarion v0.1 scope commitments — Q3](../v0.1/plans/v0.1-scope-commitments.md) — committed decision to hybrid (declared + enforced) over full sandbox.
+- [Clarion v0.1 scope commitments — Q3](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md) — committed decision to hybrid (declared + enforced) over full sandbox.
 - [NG-16](../v0.1/requirements.md) — plugin hash-pinning deferred to v0.2; companion v0.2 control for T-01/T-15.
diff --git a/docs/clarion/adr/ADR-022-core-plugin-ontology.md b/docs/clarion/adr/ADR-022-core-plugin-ontology.md
index f374aee3..e9d6a37e 100644
--- a/docs/clarion/adr/ADR-022-core-plugin-ontology.md
+++ b/docs/clarion/adr/ADR-022-core-plugin-ontology.md
@@ -129,4 +129,4 @@ Every kind is plugin-owned, including `file`, `subsystem`, `guidance`. Plugins c
 - [Clarion v0.1 system design §2](../v0.1/system-design.md) (lines 120-234) — core/plugin responsibility split; plugin manifest contract.
 - [Clarion v0.1 detailed design §1, §2](../v0.1/detailed-design.md) (lines 56-136, 187-309) — manifest shape; Entity/Edge/Finding structs; core-reserved edge kinds at line 261; core-minted `file`/`subsystem`/`guidance` IDs at lines 228-230.
 - [Loom doctrine §5](../../suite/loom.md) — centralisation-drift failure test; a closed core-defined kind enum qualifies.
-- [Panel synthesis — self-sufficiency review](../v0.1/reviews/panel-2026-04-17/04-self-sufficiency.md) — Issue 7 (rule-ID inconsistency) is the empirical case this ADR's namespace rule resolves.
+- [Panel synthesis — self-sufficiency review](../../implementation/v0.1-reviews/panel-2026-04-17/04-self-sufficiency.md) — Issue 7 (rule-ID inconsistency) is the empirical case this ADR's namespace rule resolves.
diff --git a/docs/clarion/adr/ADR-023-tooling-baseline.md b/docs/clarion/adr/ADR-023-tooling-baseline.md
index 3793b95f..75efc729 100644
--- a/docs/clarion/adr/ADR-023-tooling-baseline.md
+++ b/docs/clarion/adr/ADR-023-tooling-baseline.md
@@ -305,7 +305,7 @@ generates less value than the discipline floor it provides.
   contract. Plugins authored in Python (WP3) or later in other languages
   can adopt tooling baselines appropriate to their ecosystem; the Rust
   host's baseline is defined here.
-- Scope-commitment memo [`../v0.1/plans/v0.1-scope-commitments.md`](../v0.1/plans/v0.1-scope-commitments.md)
+- Scope-commitment memo [`../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md`](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md)
   — "enterprise rigor at lack of scale" is the phrase this ADR operationalises
   at the tooling layer.
 
diff --git a/docs/clarion/adr/ADR-024-guidance-schema-vocabulary.md b/docs/clarion/adr/ADR-024-guidance-schema-vocabulary.md
index 9c4398d5..77c7753e 100644
--- a/docs/clarion/adr/ADR-024-guidance-schema-vocabulary.md
+++ b/docs/clarion/adr/ADR-024-guidance-schema-vocabulary.md
@@ -13,7 +13,7 @@ Three guidance-schema fields and one finding field are renamed: `entity.properti
 
 The Loom federation axiom (`docs/suite/loom.md` §3–§5) requires solo-useful, pairwise-composable, enrich-only products. None of the three failure modes (semantic / initialization / pipeline coupling) directly applies to vocabulary, but cross-product readability is the *prerequisite* for honest pairwise composition. When a Loom user reads Clarion's design and Filigree's CLI in the same session and `priority` means different things in each, every cross-product debugging pass starts from a misframe. The bug at `clarion-4cd11905e2` is the concrete proof: the issue's filer assumed Filigree's meaning, the audit pass had to reframe before any fix could land.
 
-Three mismatches are documented in the [skeleton audit](../../superpowers/handoffs/2026-05-03-skeleton-audit.md):
+Three mismatches are documented in the [skeleton audit](../../implementation/handoffs/2026-05-03-skeleton-audit.md):
 
 1. **`priority`** — Clarion's guidance composition rank `project | subsystem | package | module | class | function`
    (`detailed-design.md:453`, `system-design.md:346`) collides with Filigree's `priority` label vocabulary
@@ -148,7 +148,7 @@ Add the audit's findings to the glossary as `open` clashes; defer the schema cor
 
 ### Negative
 
-- The rename has a wider blast radius than the schema alone. `requirements.md`, `system-design.md`, and `detailed-design.md` all carry references that must move; this ADR's commit updates them in lockstep. Historical ADRs (e.g., [ADR-007](./ADR-007-summary-cache-key.md) at line 56 still references `critical: true` in its example) are **not** touched — Accepted ADRs are immutable per repo convention. Readers of those historical ADRs should map the old field names to the post-ADR-024 ones using this ADR's rename table. Plan and review documents under `docs/superpowers/plans/` and `docs/clarion/v0.1/reviews/` are also left alone (historical snapshots, not normative).
+- The rename has a wider blast radius than the schema alone. `requirements.md`, `system-design.md`, and `detailed-design.md` all carry references that must move; this ADR's commit updates them in lockstep. Historical ADRs (e.g., [ADR-007](./ADR-007-summary-cache-key.md) at line 56 still references `critical: true` in its example) are **not** touched — Accepted ADRs are immutable per repo convention. Readers of those historical ADRs should map the old field names to the post-ADR-024 ones using this ADR's rename table. Plan and review documents archived under `docs/implementation/` (`agent-plans/`, `v0.1-reviews/`) are also left alone (historical snapshots, not normative).
 - The walking-skeleton fixture's `.clarion/clarion.db` (committed for the e2e test) is rebuilt with the new schema as part of this change. The test script's expectations stay the same; the database file changes. Mitigation: the e2e script doesn't depend on the schema's column names; it asserts on the persisted entity row's `id` and `kind`.
 - An external operator who *did* run a pre-publication build of Clarion against a real codebase between Sprint 1 close and this ADR has a `.clarion/clarion.db` with the old `priority` column. Mitigation: nobody has — this is the explicit pre-condition for the in-place policy. Any future operator who runs the new build sees the corrected schema only.
 - Re-using the `0001` migration version number means the `schema_migrations` ledger row is identical (`version=1`, `name='0001_initial_schema'`) before and after the edit. A consumer who applied the pre-edit `0001` and then upgrades will not see any migration to apply, and their database will diverge silently from the new shape. Mitigation: the same pre-condition — no such consumer exists; the retirement trigger names exactly this case.
@@ -168,11 +168,11 @@ Add the audit's findings to the glossary as `open` clashes; defer the schema cor
 
 ## References
 
-- [Skeleton audit](../../superpowers/handoffs/2026-05-03-skeleton-audit.md) — durable record of the audit pass, reviewer feedback (architecture-critic + leverage-analyst), and the reconciled plan that produced this ADR.
+- [Skeleton audit](../../implementation/handoffs/2026-05-03-skeleton-audit.md) — durable record of the audit pass, reviewer feedback (architecture-critic + leverage-analyst), and the reconciled plan that produced this ADR.
 - [Loom suite glossary](../../suite/glossary.md) — the federation-safe design-review artefact this ADR moves three entries from `open` to `managed` within.
 - [Loom federation axiom](../../suite/loom.md) §3–§5 — the doctrine the glossary defends; the failure-test mode this ADR addresses is reader-side cross-product disambiguation cost.
 - `crates/clarion-storage/migrations/0001_initial_schema.sql:163-191` — the schema sites this ADR edits in place.
 - `crates/clarion-storage/tests/schema_apply.rs:138-169` — the test that documented the bug and is rewritten to test the corrected design.
-- `docs/clarion/v0.1/detailed-design.md:204, 270, 449, 453, 467, 471, 737-748` — the design-doc sites this ADR's renames touch.
-- `docs/clarion/v0.1/system-design.md:346, 675` — the system-level guidance composition references.
+- `docs/clarion/1.0/detailed-design.md:204, 270, 449, 453, 467, 471, 737-748` — the design-doc sites this ADR's renames touch.
+- `docs/clarion/1.0/system-design.md:346, 675` — the system-level guidance composition references.
 - Filigree issue `clarion-4cd11905e2` — the misframed bug whose triage produced this audit.
diff --git a/docs/clarion/adr/ADR-026-containment-wire-and-edge-identity.md b/docs/clarion/adr/ADR-026-containment-wire-and-edge-identity.md
index dc63c244..eb923fd2 100644
--- a/docs/clarion/adr/ADR-026-containment-wire-and-edge-identity.md
+++ b/docs/clarion/adr/ADR-026-containment-wire-and-edge-identity.md
@@ -3,7 +3,7 @@
 **Status**: Accepted
 **Date**: 2026-05-05
 **Deciders**: qacona@gmail.com
-**Context**: B.3 (Sprint 2 Tier B) introduces the first edge kind Clarion has ever persisted (`contains`). Sprint-1 locked entity wire shape but explicitly deferred edge wire shape: the kickoff handoff at `docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md` §"Edge wire shape" states "B.3's first edge will define the protocol-level wire shape". Three coupled decisions arise — the wire envelope, the edge-row identity in storage, and the per-kind contract for `source_byte_start/end`. Locking them together prevents the four later edge kinds (`calls`, `imports`, `decorates`, `inherits_from`) from inheriting an under-specified precedent.
+**Context**: B.3 (Sprint 2 Tier B) introduces the first edge kind Clarion has ever persisted (`contains`). Sprint-1 locked entity wire shape but explicitly deferred edge wire shape: the kickoff handoff at `docs/implementation/handoffs/2026-04-30-sprint-2-kickoff.md` §"Edge wire shape" states "B.3's first edge will define the protocol-level wire shape". Three coupled decisions arise — the wire envelope, the edge-row identity in storage, and the per-kind contract for `source_byte_start/end`. Locking them together prevents the four later edge kinds (`calls`, `imports`, `decorates`, `inherits_from`) from inheriting an under-specified precedent.
 
 ## Summary
 
@@ -192,6 +192,6 @@ Instead of typed `source_byte_start/end` columns, edges carry a `properties: { s
 ## References
 
 - [B.3 design doc](../../implementation/sprint-2/b3-contains-edges.md) — wire shape, emission policy, parent_id provenance, manifest bump, test plan.
-- [Sprint-2 kickoff handoff §"Edge wire shape"](../../superpowers/handoffs/2026-04-30-sprint-2-kickoff.md) — the deferral this ADR resolves.
+- [Sprint-2 kickoff handoff §"Edge wire shape"](../../implementation/handoffs/2026-04-30-sprint-2-kickoff.md) — the deferral this ADR resolves.
 - [Sprint-1 walking-skeleton e2e](../../../tests/e2e/sprint_1_walking_skeleton.sh) — extends to assert at least one edge row post-B.3.
 - Five-reviewer panel transcripts (in B.3 brainstorming conversation log on `sprint-2/b3-design` branch).
diff --git a/docs/clarion/adr/ADR-027-ontology-version-semver.md b/docs/clarion/adr/ADR-027-ontology-version-semver.md
index 9aebf3cb..fd4a4efe 100644
--- a/docs/clarion/adr/ADR-027-ontology-version-semver.md
+++ b/docs/clarion/adr/ADR-027-ontology-version-semver.md
@@ -140,6 +140,6 @@ Document that the field exists; let each plugin pick its own version semantics.
 
 - [B.2 design doc](../../implementation/sprint-2/b2-class-module-entities.md) §5 — first ontology_version bump cite.
 - [B.3 design doc](../../implementation/sprint-2/b3-contains-edges.md) §7 — second ontology_version bump cite.
-- [Sprint-2 kickoff handoff](../../superpowers/handoffs/2026-04-30-sprint-2-kickoff.md) §"`ontology_version` bump policy" — the original ambiguous formulation that motivated this ADR.
+- [Sprint-2 kickoff handoff](../../implementation/handoffs/2026-04-30-sprint-2-kickoff.md) §"`ontology_version` bump policy" — the original ambiguous formulation that motivated this ADR.
 - [Filigree clarion-8befae708b](.) — CI lint guard for plugin.toml ↔ server.py ONTOLOGY_VERSION drift (P3 follow-up; not blocking).
 - [Semver 2.0.0](https://semver.org) — the broader convention this ADR adopts.
diff --git a/docs/clarion/adr/ADR-031-schema-validation-policy.md b/docs/clarion/adr/ADR-031-schema-validation-policy.md
index b742c57a..f278c954 100644
--- a/docs/clarion/adr/ADR-031-schema-validation-policy.md
+++ b/docs/clarion/adr/ADR-031-schema-validation-policy.md
@@ -405,7 +405,7 @@ permanent.
 
 ## References
 
-- [Skeleton audit](../../superpowers/handoffs/2026-05-03-skeleton-audit.md)
+- [Skeleton audit](../../implementation/handoffs/2026-05-03-skeleton-audit.md)
   — F-13 in the Reviewer additions table; the audit framing that
   motivated this ADR.
 - `crates/clarion-storage/migrations/0001_initial_schema.sql:80-81, 134`
diff --git a/docs/clarion/adr/ADR-033-v1.0-distribution.md b/docs/clarion/adr/ADR-033-v1.0-distribution.md
new file mode 100644
index 00000000..657523d5
--- /dev/null
+++ b/docs/clarion/adr/ADR-033-v1.0-distribution.md
@@ -0,0 +1,80 @@
+# ADR-033: v1.0 Distribution via GitHub Releases
+
+**Status**: Accepted
+**Date**: 2026-05-19
+**Deciders**: qacona@gmail.com
+**Context**: Clarion v1.0 is the first publishable release; an outside operator must be able to install without `git clone` + `cargo build`. The packaging path was not previously committed.
+
+## Summary
+
+Clarion v1.0 distributes via **GitHub Releases** with pre-built binaries for
+the Rust core and a Python sdist for the language plugin. Public registries
+(crates.io for `clarion-cli`, PyPI for `clarion-plugin-python`) are deferred to
+v2.0, after names are reserved and a publish cadence is established.
+
+## Decision
+
+A tag matching `v[0-9]+.*` pushed to `main` triggers
+`.github/workflows/release.yml`, which:
+
+1. Builds the `clarion` binary on the v1.0 supported matrix:
+   - `x86_64-unknown-linux-gnu`
+   - `x86_64-apple-darwin`
+   - `aarch64-apple-darwin`
+   Windows is intentionally out of v1.0 scope: the plugin host's resource
+   limits use `setrlimit`, which is Unix-only
+   (`crates/clarion-core/src/plugin/limits.rs`).
+2. Builds the Python plugin sdist via `python -m build --sdist plugins/python`.
+3. Creates a GitHub Release for the tag, attaching:
+   - One `clarion-<target>.tar.gz` per platform (binary + LICENSE + README).
+   - `clarion-plugin-python-<version>.tar.gz` (one sdist, multi-platform).
+4. Auto-generates release notes from `git log` between the previous tag and
+   the new one, filtered to merge commits.
+
+Install instructions (per `README.md` and `docs/operator/getting-started.md`):
+
+```bash
+# Rust binary — download + extract to ~/.local/bin or equivalent
+curl -L https://github.com/tachyon-beep/clarion/releases/download/v1.0.0/clarion-x86_64-unknown-linux-gnu.tar.gz \
+  | tar xz -C ~/.local/bin --strip-components=1 clarion-x86_64-unknown-linux-gnu/clarion
+
+# Python plugin
+pipx install https://github.com/tachyon-beep/clarion/releases/download/v1.0.0/clarion-plugin-python-1.0.0.tar.gz
+```
+
+## Alternatives considered
+
+**(a) Source-only (`cargo install --git` + `pipx install git+...`).** Ten
+minutes of cargo compile on every fresh install. Bad first impression for an
+operator evaluating the tool. Useful as a fallback for unsupported platforms
+but not the headline path.
+
+**(c) Public registries (crates.io + PyPI).** Best operator UX, but requires
+name reservation on both registries plus version-bump discipline plus a
+crates.io publishing token plus a PyPI publishing token plus a release-cadence
+commitment. Worth the work for v2.0 when the publish cadence is established;
+not worth blocking v1.0 on.
+
+**`cargo-dist` vs hand-written workflow.** Picked hand-written for v1.0
+because (i) the matrix is small (3 targets), (ii) the workflow doubles as
+documentation of what's in each artifact, and (iii) adopting `cargo-dist`
+adds a binary dependency on the release toolchain that the team would need to
+learn. A future ADR can flip to `cargo-dist` if the matrix grows.
+
+## Consequences
+
+- A tag push to `main` produces a binary release; no per-platform manual
+  build steps.
+- Operators install without needing a Rust toolchain or `cargo build` time.
+- Windows support is *explicitly* out of v1.0 (`NG-WIN-01` candidate; not
+  filed as a named non-goal yet because no operator has asked).
+- The release workflow is part of the v1.0 surface — broken release builds
+  block the v1.0 publish via WS-D (external-operator smoke test).
+- crates.io / PyPI publishing remains v2.0 work; until then the install path
+  carries an explicit `github.com/tachyon-beep` URL.
+
+## Related
+
+- [WS-C task — Distribution + install ergonomics](../../implementation/v0.1-publish/thread-1-pre-publish-blockers.md#4-workstream-c--distribution--install-ergonomics)
+- [ADR-002 — Plugin transport](./ADR-002-plugin-transport-json-rpc.md) — explains why the Python plugin ships as a separate executable on `$PATH`
+- [ADR-023 — Tooling baseline](./ADR-023-tooling-baseline.md) — the CI floor the release workflow inherits
diff --git a/docs/clarion/adr/ADR-034-federation-http-read-api-hardening.md b/docs/clarion/adr/ADR-034-federation-http-read-api-hardening.md
new file mode 100644
index 00000000..47e7343a
--- /dev/null
+++ b/docs/clarion/adr/ADR-034-federation-http-read-api-hardening.md
@@ -0,0 +1,168 @@
+# ADR-034: Federation HTTP Read API Hardening — Identity Auth, Batch Resolution, `BRIEFING_BLOCKED`, Instance ID
+
+**Status**: Accepted
+**Date**: 2026-05-19
+**Deciders**: qacona@gmail.com
+**Context**: Sprint 3 Loom federation hardening (see [`docs/implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md`](../../implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md)); extends ADR-014's read-API §"Security Posture" and §"Error Envelope"
+**Extends**: [ADR-014](./ADR-014-filigree-registry-backend.md) Security Posture and Error Envelope sections only — the registry-backend protocol decision in ADR-014 §"Decision" remains in force.
+
+## Summary
+
+Sprint 3 hardens Clarion's HTTP read API beyond ADR-014's original posture: protected routes can require Loom component identity via `X-Loom-Component: clarion:<hmac>` resolved from an operator-named environment variable, a new `POST /api/v1/files/batch` endpoint handles bulk path resolution in a single round trip, a distinct `403 BRIEFING_BLOCKED` response distinguishes blocked entities from "not found" entities without leaking identity, and `GET /api/v1/_capabilities` echoes a stable per-project `instance_id` so siblings can detect endpoint rebinding. These additions extend ADR-014's wire-contract surface without breaking it — `api_version` remains `1`.
+
+## Context
+
+ADR-014 §"Security Posture" pinned the HTTP read API as "unauthenticated and loopback-only by default" with non-loopback binds gated by `serve.http.allow_non_loopback: true`. ADR-014 §"Error Envelope" closed the initial `code` enum to `INVALID_PATH`, `PATH_OUTSIDE_PROJECT`, `NOT_FOUND`, `STORAGE_ERROR`, `INTERNAL`. Both were the right posture for the immediate ADR-014 use case (loopback-only Filigree sidecar) but were under-specified for the broader Sprint 3 federation goals:
+
+- Filigree may run on a different host than Clarion in production deployments, and the operator should not have to layer a separate auth proxy for what is a publisher-side concern.
+- Filigree's `ClarionRegistry` cold-start hydrates N file records by re-asking Clarion for each path. The single-file `GET` endpoint costs one pooled SQLite connection per call; for a 1000-file warm-up that is 1000 round trips and 1000 pool acquisitions.
+- `briefing_blocked` entities (per ADR-013 secret-scan briefing block) are not "not found" — they exist but are policy-blocked. The original `NOT_FOUND` masking conflates "Clarion does not know this file" (registry coverage gap; escalate) with "Clarion knows this file but refuses to expose it" (briefing block; wait for re-scan or fix the secret). Filigree needs to distinguish the two.
+- `_capabilities` is the only handshake point Filigree sees before issuing requests. If an operator rebinds the same `bind` to a different Clarion project (different `.clarion/` root, different cache), Filigree has no fingerprint to detect the swap.
+
+Sprint 3 implemented these four hardenings (`1109560`, `acbf465`, `eb6200d`, `2c3311a`) and pinned the resulting wire contract in [`docs/federation/contracts.md`](../../federation/contracts.md). The body of ADR-014, per the ADR immutability rule in [`/home/john/clarion/CLAUDE.md`](../../../CLAUDE.md) §"Editorial conventions", cannot be rewritten in place. This ADR is therefore the authoritative source for the four hardenings; ADR-014 carries the standard `Accepted; partially extended by ADR-034 (Security Posture)` status amendment.
+
+## Decision
+
+### 1. Loom component identity on protected routes
+
+`/api/v1/files`-family endpoints require `X-Loom-Component: clarion:<hmac>` when Clarion has resolved `serve.http.identity_token_env` at startup. `/api/v1/_capabilities` is **always** unauthenticated so siblings can probe the API surface before they hold a secret.
+
+The HMAC is lowercase hex HMAC-SHA256 over a newline-separated canonical message: request method, path plus query string, and SHA-256 hex of the request body. This signs the request line and body digest without turning the shared secret into a bearer credential on the wire. Clarion preserves the older `serve.http.token_env` bearer-token mode for compatibility when `identity_token_env` is not configured.
+
+Token-resolution and bind-policy trust matrix, enforced at startup by `HttpReadConfig::validate_auth_trust` before the listener binds:
+
+| Bind | `identity_token_env` resolved | `token_env` resolved | Behaviour |
+|---|---|---|---|
+| Loopback | unset | unset | Unauthenticated; allow all requests (matches ADR-014's original posture for the loopback case). |
+| Loopback | set | any | HMAC required on protected routes; capabilities always allowed. |
+| Loopback | configured but env missing | any | **Refuse to start** with `CLA-CONFIG-HTTP-IDENTITY-MISSING`. |
+| Non-loopback | set | any | HMAC required on protected routes. |
+| Non-loopback | unset | set | Bearer required on protected routes. |
+| Non-loopback | unset | unset | **Refuse to start** with `CLA-CONFIG-HTTP-NO-AUTH`. |
+
+Non-loopback-without-auth refusal extends ADR-014's `allow_non_loopback` opt-in: there is no longer a "non-loopback unauthenticated" mode. Non-loopback binds require **both** `allow_non_loopback: true` **and** a resolved HMAC identity secret or legacy bearer token; either alone is insufficient. The opt-in remains the gate that admits non-loopback binds at all, but it no longer admits them unauthenticated.
+
+Authentication rejection (any of: header absent, wrong scheme/prefix, wrong token or signature, blank token or signature) returns `401 Unauthorized` with the standard error envelope and `code: "UNAUTHENTICATED"`. Secret comparison is constant-time so a wrong-length client cannot distinguish "header absent" from "secret mismatch" via timing. The secret value is never logged; the bind-time log line records `auth=hmac`, `auth=bearer`, or `auth=none`, not the secret itself.
+
+The preferred secret is resolved from an operator-named environment variable; the config field is `serve.http.identity_token_env`. The legacy bearer-token config field is `serve.http.token_env` (default `CLARION_LOOM_TOKEN`, matching Filigree's pinned client default). Secret values never appear in `clarion.yaml`.
+
+### 2. `POST /api/v1/files/batch`
+
+Bulk file-identity resolution. One pooled SQLite connection serves the whole batch.
+
+Request body shape (closed):
+
+```json
+{
+  "queries": [
+    {"path": "src/a.py", "language": null},
+    {"path": "src/b.py", "language": "python"}
+  ]
+}
+```
+
+Response body shape (closed; arrays are disjoint partitions of the input):
+
+```json
+{
+  "resolved":         [/* BatchResolvedItem */],
+  "not_found":        [/* requested paths */],
+  "briefing_blocked": [/* requested paths */],
+  "errors":           [/* BatchErrorItem with code+message */]
+}
+```
+
+The per-batch cap is **256 queries** (`BATCH_MAX_QUERIES` in [`crates/clarion-cli/src/http_read.rs`](../../../crates/clarion-cli/src/http_read.rs); referenced as `queries.len() > 256` in `contracts.md` §"`POST /api/v1/files/batch`"). The request body is additionally bounded at the transport layer to 16 KiB. A `queries` array that exceeds the cap returns `400 BATCH_TOO_LARGE` (new error code, see §3). The cap is not operator-configurable in v1.0 — it is pinned on the wire so Filigree client splitting logic can compile-in the limit. A future incompatible change to the cap is the trigger for `api_version: 2`, not a per-server override.
+
+Individual-item errors (`INVALID_PATH`, `PATH_OUTSIDE_PROJECT`, `STORAGE_ERROR`, `INTERNAL`) go into the `errors` array; the whole request still returns `200 OK` so partial-success semantics are explicit on the wire. Briefing-blocked items are partitioned to the `briefing_blocked` array; the per-item envelope deliberately does not include `entity_id`, `content_hash`, `canonical_path`, or `language` so callers cannot infer file identity from a block-classified item.
+
+### 3. `BRIEFING_BLOCKED` 403 on single-file `GET`
+
+`GET /api/v1/files?path=` for an entity whose `briefing_blocked` anchor is set (per ADR-013) returns `403 Forbidden` with `code: "BRIEFING_BLOCKED"`. The 403 envelope omits `entity_id`, `content_hash`, `canonical_path`, and `language`. The structural signal that "Clarion knows this file but is refusing to expose it" is therefore *only* the status code and `code` discriminator, not any payload field.
+
+ADR-014's original error-code set is extended to:
+
+```
+INVALID_PATH | PATH_OUTSIDE_PROJECT | NOT_FOUND |
+BRIEFING_BLOCKED | UNAUTHENTICATED | STORAGE_ERROR |
+BATCH_TOO_LARGE | INTERNAL
+```
+
+The set remains closed. Clients must switch on `code`, not on `error` text.
+
+### 4. Stable per-project `instance_id` in `_capabilities`
+
+`GET /api/v1/_capabilities` echoes:
+
+```json
+{
+  "api_version": 1,
+  "instance_id": "9bd7234e-6d44-4a38-9ae4-76f912a10221",
+  "registry_backend": true,
+  "file_registry": true
+}
+```
+
+`instance_id` is a v4 UUID created lazily on first `clarion serve` (via `instance::load_or_create` at [`crates/clarion-cli/src/serve.rs:29`](../../../crates/clarion-cli/src/serve.rs)) and persisted to `.clarion/instance_id`. Subsequent `clarion serve` invocations read the existing value. The file is created with mode `0600` on Unix. The ID is stable for the life of that `.clarion/` directory; deleting `.clarion/instance_id` (or the whole `.clarion/` tree) on the next `clarion serve` produces a fresh UUID, and that is intended — siblings use the change as the trigger to invalidate cached identity bindings. The file is excluded from git per ADR-005's exclusion list for per-machine state.
+
+`instance_id` is **not** the same as a deployment fingerprint, a Filigree project ID, or a Clarion release. It is exactly the identity of one local `.clarion/` directory.
+
+## Alternatives Considered
+
+### Alternative 1: Bearer-only authentication
+
+Bearer-only authentication was the first Sprint 3 hardening because it was simple
+to operate. It is retained for compatibility through `serve.http.token_env`, but
+new Loom deployments should prefer `identity_token_env`: the HMAC shape
+authenticates the request line and body digest instead of sending the shared
+secret as the credential on every request.
+
+### Alternative 2: Unix Domain Socket-only auth (ADR-012's original posture)
+
+ADR-012 (now superseded) had UDS as the default auth model. Sprint 3's deployment story explicitly admits non-loopback Filigree — a UDS-only model would force Filigree into a sidecar-on-same-host topology that the federation contract does not otherwise require. Bearer over TCP keeps the federation deployment-topology-agnostic.
+
+### Alternative 3: A separate `/api/v1/files/inquire` endpoint for "is this blocked?"
+
+Distinguishing block from not-found with a second endpoint avoids the 403/404 split at the cost of two round trips and a more elaborate wire contract. Filigree's actual question on a single `GET` is "which of these three states is this path in?" and the single-endpoint, status-code-discriminated answer is the simpler shape. Declined.
+
+### Alternative 4: Amend ADR-014 in place
+
+The Sprint 3 tasking doc originally proposed pinning these decisions into ADR-014's body. CLAUDE.md's editorial-conventions section forbids in-place ADR mutation; the doctrine is "to revise an Accepted ADR, write a new ADR that supersedes it." This ADR is that new ADR. ADR-014's status field carries the only allowed mutation (status amendment + reference forward to ADR-034).
+
+## Consequences
+
+### Positive
+
+- The federation HTTP read API now has a per-request authentication primitive. ADR-014's "unauthenticated, loopback-only" promise was a deliberate Sprint 1/2 simplification that was load-bearing for the v1.0 federation surface; the gap is now closed.
+- Filigree's cold-start hydration cost drops from O(N) round trips to O(1) with the batch endpoint. The per-item error partitioning means a single malformed path in a 1000-path batch does not poison the whole request.
+- `BRIEFING_BLOCKED` is mechanically distinguishable from `NOT_FOUND`. Filigree's escalation logic can branch on the two cases without parsing error text or re-issuing probe requests.
+- `instance_id` gives Filigree a stable handle to detect endpoint rebinding. Pre-Sprint-3, a `bind` pointed at a swapped `.clarion/` was indistinguishable from a fresh start; that ambiguity is now resolved on the first capability probe after the swap.
+
+### Negative
+
+- Operators upgrading from ADR-014's unauthenticated posture to a non-loopback federation deployment must now provide a token at startup. The `CLA-CONFIG-HTTP-NO-AUTH` startup refusal makes this a fail-closed migration, not a silent one, but the operator-facing diff is non-trivial.
+- HMAC identity still uses a shared secret; a leak requires rotation across both Clarion and every sibling client. Replay windows, key identifiers, and rotation metadata remain future hardening.
+- The error-code enum is now wider than ADR-014's original. Filigree's `code`-switch logic must handle `BRIEFING_BLOCKED`, `UNAUTHENTICATED`, and `BATCH_TOO_LARGE` in addition to the original five. The federation contract documents this; clients that ignore the new codes will surface them as unhandled errors rather than misinterpret them.
+
+### Neutral
+
+- `api_version` remains `1`. The additions are non-breaking augmentations of the v1 wire contract — every pre-Sprint-3 client request shape is still accepted, just with the added option to authenticate, batch, and discriminate on the wider error set. An incompatible change to the read API will be the trigger for `api_version: 2`, not the introduction of these hardenings.
+- The Sprint-3 tasking-doc items C1, C2, C5, C7, C8, C9, C10, C11 are not addressed by this ADR — they cover storage correctness and runtime supervision rather than wire-contract decisions. They land directly in the implementation without an ADR change because they implement, rather than amend, ADR-014's existing contract.
+
+## Related Decisions
+
+- [ADR-012](./ADR-012-http-auth-default.md) — original HTTP auth ADR; Superseded by ADR-014, whose Security Posture is in turn partially extended by this ADR.
+- [ADR-013](./ADR-013-pre-ingest-secret-scanner.md) — defines the briefing-block anchor whose wire propagation §3 pins.
+- [ADR-014](./ADR-014-filigree-registry-backend.md) — registry-backend protocol; §"Security Posture" and §"Error Envelope" extended by this ADR. Other sections (capability probe contents beyond `instance_id`, file identity semantics, canonical-path semantics) remain authoritative.
+- [ADR-033](./ADR-033-v1.0-distribution.md) — v1.0 distribution; the hardenings here are part of the 1.0 federation cut.
+
+## References
+
+- Wire spec: [`docs/federation/contracts.md`](../../federation/contracts.md)
+- Sprint 3 tasking: [`docs/implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md`](../../implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md)
+- Implementing commits:
+  - `1109560` feat(http_read): return 403 BRIEFING_BLOCKED for blocked entities
+  - `acbf465` feat(http_read): require Authorization: Bearer for /api/v1/files
+  - C-4 follow-up: prefer `X-Loom-Component: clarion:<hmac>` when `serve.http.identity_token_env` is configured
+  - `eb6200d` feat(http_read): add POST /api/v1/files/batch + document path normalization
+  - `2c3311a` feat(http_read): formatting / fix(instance): UUID generation comments / test(serve)
diff --git a/docs/clarion/adr/ADR-035-operational-tuning-discipline.md b/docs/clarion/adr/ADR-035-operational-tuning-discipline.md
new file mode 100644
index 00000000..6db08f3b
--- /dev/null
+++ b/docs/clarion/adr/ADR-035-operational-tuning-discipline.md
@@ -0,0 +1,367 @@
+# ADR-035: Operational Tuning Discipline — Declared Basis, Override Surface, Retune Trigger, Coupling
+
+**Status**: Accepted
+**Date**: 2026-05-23
+**Deciders**: qacona@gmail.com
+**Context**: From-scratch architecture review on 2026-05-22 (`docs/arch-analysis-2026-05-22-1924/`) surfaced five open questions in `04-final-report.md` §8 that a follow-on SME roundtable (solution architect, systems thinker, Python engineer, quality engineer, security engineer) reframed as a single missing-feedback-loop pattern. This ADR is the level-5 (rules) intervention that pattern requires.
+**Extends**: [ADR-021](./ADR-021-plugin-authority-hybrid.md) §4 — names four of the eleven operational constants as config keys; this ADR generalises the discipline that ADR-021 §4 already implies for those four and extends it to every operational constant in the workspace.
+
+## Summary
+
+Clarion ships with strong **runtime** balancing loops — the path-escape breaker, the crash-loop breaker, the writer-actor's `parent_contains_mismatch` bijection check, the L2 cross-language fixture parity test — and no **design-time** balancing loops. The result is silent drift: hardcoded operational constants accrete without recorded basis, crate-level doc-comments diverge from contents, file LOC grows past the point of legibility, and the artifact that would name the right tuning surface (a config schema, a split plan, a crate boundary) is never written. The five §8 open questions are five surface symptoms of one pattern.
+
+This ADR commits the project to a uniform discipline. Every operational constant in Clarion source that gates externally observable behaviour MUST declare four things — **stated basis**, **override surface**, **retune trigger**, **coupling** — in a code comment immediately adjacent to the constant (or, for wire-contract constants whose declaration lives in a sibling document, a cross-reference to that document). The same rule shape extends to **file-LOC budgets** (any source file over 1,500 LOC declares a split-trigger condition in its module doc-comment) and to **crate-boundary budgets** (any crate that takes a dependency widening its trust surface or contradicting its `lib.rs` doc-comment declares the trigger for crate extraction). The discipline is enforced by a lint script in `scripts/` that scans Rust + Python sources for the required declarations and fails CI on undeclared operational constants or oversize files.
+
+This is a level-5 (rules) Meadows intervention — not a level-12 (parameters) one. A `clarion.yaml` config file alone is rejected as insufficient: a config file without the rule that gates how constants graduate from hardcoded → tunable → deprecated would, in the systems thinker's words, "decay back to hardcoded constants by the next sprint — that is exactly how Clarion got here."
+
+## Context
+
+### The five §8 open questions
+
+The 2026-05-22 architecture analysis (`docs/arch-analysis-2026-05-22-1924/04-final-report.md` §8) recorded five questions that the from-scratch catalog could not answer from code alone:
+
+1. **Why `MAX_FILES_PER_PYRIGHT_SESSION = 25`?** Empirical? Conservative bound on Pyright memory growth? Not knowing makes future tuning a guess.
+2. **What is the post-1.0 plan for the four monolith files?** Each has a natural refactor split. Are these on the roadmap, or is the policy "no split until the file actively impedes a change"?
+3. **Will `clarion-llm` become a crate?** The `llm_provider.rs` placement in `clarion-core` is the largest single argument against the `lib.rs:1` doc-comment.
+4. **What is the architect's stance on `application_id` / `user_version`?** Trivial to add; non-trivial to add retroactively once installed DBs exist in the wild.
+5. **Operational tuning roadmap.** Eleven hardcoded limits, plus the 25-file restart, plus the 256/50 batch-cadence constants. WP6 is named in code comments — what is its current status?
+
+### The roundtable's diagnosis
+
+Five SME reports (`docs/arch-analysis-2026-05-22-1924/temp/answer-{solution-architect,systems-thinker,python-engineer,quality-engineer,security-engineer}.md`) converged on a single root cause. The systems thinker named it most directly:
+
+> "The five questions look like five concerns. They are one. Each is a missing-feedback-loop symptom: a place where operational reality has no path back to the artifact that would change behavior. They wear 'parameter' clothing (Level 12) but live at Level 6 (information flows) and Level 5 (rules)." — `answer-systems-thinker.md`
+
+The archetype is Meadows' **Drift to Low Performance**: each individual deferral is locally rational ("ship 1.0; tune later"; "don't split `host.rs` mid-sprint"; "PRAGMAs are post-1.0") but there is no countervailing signal pushing the other way. Two literal tells in the codebase make the diagnosis concrete:
+
+- **`crates/clarion-cli/src/analyze.rs:65`** carries `#[allow(clippy::too_many_lines)]` — the standard-lowering act made literal in code. Two more sites at lines 650 and 1190 carry the same allow.
+- **`crates/clarion-core/src/plugin/breaker.rs:7`** says: *"Sprint 1 hard-codes the threshold and window per UQ-WP2-10; the config surface (`clarion.yaml:plugin_limits.crash_*`) lands in WP6."* The placeholder where a discipline should be.
+
+ADR-030 narrowed WP6's 1.0 scope to the on-demand `summary(id)` MCP tool. The operator-tunables work the `breaker.rs:7` comment references **was not folded into the narrowed WP6 scope and is currently un-homed** (solution architect's reading: `answer-solution-architect.md` §5). ADR-021 §4 names four of the eleven constants as config keys (`plugin_limits.max_frame_bytes`, `plugin_limits.max_records_per_run`, `plugin_limits.max_rss_mib`, the manifest-declared `expected_max_rss_mb`) — those are *promised by an Accepted ADR and not implemented*, with no governing rule about how the other seven graduate from hardcoded to tunable.
+
+### Per-SME contributions to the diagnosis
+
+The five SME reports each examined a different facet of the same pattern:
+
+- **Solution architect** (`answer-solution-architect.md`): triangulates the WP6 home from ADR-021 §4 + ADR-030 + the 2026-04-19 WP2 handoff doc; recommends shipping 1.0 with limits hardcoded and landing the config surface in WP6 post-1.0 *as one ADR-021-aligned change rather than dripping per-constant overrides*. The "one ADR-aligned change" framing is what this ADR operationalises.
+- **Systems thinker** (`answer-systems-thinker.md`): identifies Level 5 (rules) as the correct leverage point and rejects the level-12 (parameters) intervention of "just add `clarion.yaml`" — the rule about how/when constants graduate is the discipline, not the constants themselves. Names the "drift to low performance" archetype.
+- **Python engineer** (`answer-python-engineer.md`): classifies the Python-side constants into wire-contract-pinned (must track Rust counterparts; `MAX_CONTENT_LENGTH = 8 MiB` in `server.py:48` mirrors `ContentLengthCeiling::DEFAULT`; `MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512` in `pyright_session.py:43` mirrors a same-named Rust constant; `STDERR_TAIL_LIMIT = 65536` in `pyright_session.py:49` mirrors `STDERR_TAIL_BYTES = 64 KiB` in `host.rs`) versus operational tunables (six Pyright-session constants). **None carry a comment naming the Rust counterpart.** This forced the fourth declaration axis — *coupling* — into this ADR's rule shape: without it, a wire-pinned constant and a freely-tunable one get the same declaration form, which obscures the more dangerous case.
+- **Quality engineer** (`answer-quality-engineer.md`): enumerates per-constant test coverage (twelve constants — eight Tested, three Weak, one Untested, one Partially tested). The Weak/Untested cluster is `DEFAULT_MAX_RSS_MIB`/`DEFAULT_MAX_NOFILE`/`DEFAULT_MAX_NPROC` — security-enforcement constants whose behavioural coverage is "does not panic." A value change here has no regression net. The discipline this ADR establishes interlocks with that gap: a constant whose retune trigger is named is a constant whose regression test is also nameable.
+- **Security engineer** (`answer-security-engineer.md`): names Q5 as "the question with the most teeth" from a STRIDE-D + STRIDE-E perspective. The 11+ values include the entity cap (500k), Content-Length ceiling (8 MiB), path-escape breaker threshold (10/60s), `RLIMIT_AS` (2 GiB), `RLIMIT_NOFILE` (256), `RLIMIT_NPROC` (32), HTTP body limit (16 KiB), concurrency limit (64), request timeout (10s), batch maxima (256/1000), and the Pyright restart. Recompile-to-tune is itself a security posture stance — an operator under active adversarial-plugin pressure cannot tighten the breaker threshold without a rebuild. The recommendation: *at v1.0 these are deliberately frozen so the security policy is uniform across deployments; post-1.0, the path-escape breaker threshold, the entity cap, and the `RLIMIT_AS` ceiling should become operator-tunable with hard floors enforced at config-load time.* That stance survives intact in this ADR's "internal, no override" allowed state.
+
+### What this ADR is not
+
+This ADR is **not** a tracking surface in Filigree, an entity-association registry, or a derived-metric dashboard. It is a source-comment + lint-script discipline, period. ADR-029's entity-association binding is a different mechanism for a different problem; the two do not overlap. This ADR also does not invent a `clarion.yaml` field set — ADR-021 §4 already names four of the eleven config keys, and the per-constant override-surface placement is the matter of subsequent WPs (post-1.0 WP6 by the solution architect's recommendation). What this ADR commits is the **rule** that gates whether a constant is declared, where its override surface lives, and what would prompt its retune.
+
+## Decision
+
+### 1. The four-axis declaration rule
+
+Every operational constant in Clarion source that gates externally observable behaviour MUST declare four things, either in a code comment immediately adjacent to the constant or in a sibling doc cross-reference if the constant's authoritative declaration lives elsewhere:
+
+1. **Stated basis** — the empirical or design rationale for the current value. Acceptable values include "empirical placeholder, see retune trigger" if the value is currently unmeasured; the placeholder string is itself a basis statement and the retune trigger is what discharges it.
+2. **Override surface** — where the value can be tuned. The closed enum is:
+   - `clarion.yaml:<field-path>` — operator-tunable via the project config file.
+   - `env:<VAR_NAME>` — operator-tunable via environment variable.
+   - `plugin.toml:<field-path>` — plugin-author-tunable per ADR-021's plugin-authority split.
+   - `recompile` — internal; not exposed.
+   - `wire:<spec-anchor>` — pinned on the wire by a wire-contract document; tunable only via an incompatible-version bump in that document.
+3. **Retune trigger** — the observable condition that should prompt re-evaluation. The trigger must be expressible as either a metric threshold (e.g., "Pyright RSS exceeds 1.5 GiB before file 25 on a corpus sized at the elspeth scale") or a finding subcode (e.g., "any `CLA-INFRA-PLUGIN-OOM-KILLED` finding observed in production runs"). "If something feels wrong" does not satisfy the rule.
+4. **Coupling** — the constant's relationship to other declared values. The closed enum is:
+   - `independent` — standalone; tunable without affecting any sibling constant.
+   - `wire-paired-with:<symbol>` — must match a same-shape constant on the other side of a wire contract. A change requires updating both sides in lockstep.
+   - `policy-paired-with:<symbol>` — must satisfy a policy invariant against a sibling constant (e.g., a per-session restart cap that must remain less than a per-run restart cap).
+   - `floor-of:<symbol>` — a hard floor below which an operator override is refused at config-load time per ADR-021 §2b's "configuration-surface floor" pattern.
+
+The rule's spine is the four-axis declaration; the closed enums on **override surface** and **coupling** keep the rule from drifting into prose. The shape is short — four lines of comment per constant in the steady state.
+
+#### Canonical comment shape
+
+For the Rust workspace, the canonical adjacent-comment shape is:
+
+```rust
+/// Operational constant.
+///
+/// Basis: <one sentence rationale, or "empirical placeholder; see retune trigger">.
+/// Override: <one of clarion.yaml:* | env:* | plugin.toml:* | recompile | wire:*>.
+/// Retune: <metric threshold or finding subcode>.
+/// Coupling: <one of independent | wire-paired-with:<sym> | policy-paired-with:<sym> | floor-of:<sym>>.
+pub const MAX_EXAMPLE_BYTES: usize = 8 * 1024;
+```
+
+For the Python plugin, equivalent shape using a module-level `#:` comment block:
+
+```python
+#: Operational constant.
+#:
+#: Basis: <one sentence rationale, or "empirical placeholder; see retune trigger">.
+#: Override: <one of clarion.yaml:* | env:* | plugin.toml:* | recompile | wire:*>.
+#: Retune: <metric threshold or finding subcode>.
+#: Coupling: <one of independent | wire-paired-with:<sym> | policy-paired-with:<sym> | floor-of:<sym>>.
+MAX_EXAMPLE_BYTES = 8 * 1024
+```
+
+The lint script (see §5) parses the four named tags exactly as written.
+
+### 2. The eleven operational constants in `clarion-core`
+
+The 2026-05-22 architecture catalog (`docs/arch-analysis-2026-05-22-1924/02-subsystem-catalog.md` §1 "Concerns") enumerated eleven hardcoded limit constants across `clarion-core`:
+
+```
+MAX_PROTOCOL_ERROR_FIELD_BYTES  (4 KiB,  protocol.rs)
+MAX_ENTITY_FIELD_BYTES          (4 KiB,  host.rs)
+MAX_ENTITY_EXTRA_BYTES          (64 KiB, host.rs)
+STDERR_TAIL_BYTES               (64 KiB, host.rs)
+MAX_HEADER_LINE_BYTES           (8 KiB,  transport.rs)
+MAX_UNRESOLVED_CALLEE_EXPR_BYTES (512,   host.rs)
+ContentLengthCeiling::DEFAULT   (8 MiB,  limits.rs)
+EntityCountCap::DEFAULT_MAX     (500_000, limits.rs)
+DEFAULT_MAX_RSS_MIB             (limits.rs)
+DEFAULT_MAX_NOFILE              (limits.rs)
+DEFAULT_MAX_NPROC               (limits.rs)
+```
+
+Plus `PYRIGHT_MAX_NPROC = 4096` (host.rs, raised for the language-server runtime). All twelve MUST be retrofitted to the four-axis declaration before the 1.1 release.
+
+For the Python plugin, the inventory enumerated by `answer-python-engineer.md` is:
+
+```
+MAX_CONTENT_LENGTH               (8 MiB,  server.py:48,   wire-paired-with ContentLengthCeiling::DEFAULT)
+MAX_FILES_PER_PYRIGHT_SESSION    (25,     server.py:49,   operational; see §3 below)
+MAX_PYRIGHT_RESTARTS_PER_RUN     (3,      pyright_session.py:44,  policy-paired with the 25-file recycle)
+PYRIGHT_INIT_TIMEOUT_SECS        (30.0,   pyright_session.py:46)
+PYRIGHT_CALL_TIMEOUT_SECS        (5.0,    pyright_session.py:47)
+PYRIGHT_FILE_TIMEOUT_SECS        (3.0,    pyright_session.py:48)
+MAX_REFERENCE_SITES_PER_FILE     (2000,   pyright_session.py:45)
+MAX_UNRESOLVED_CALLEE_EXPR_BYTES (512,    pyright_session.py:43, wire-paired-with Rust same-name)
+STDERR_TAIL_LIMIT                (65536,  pyright_session.py:49, wire-paired-with STDERR_TAIL_BYTES)
+```
+
+Plus the writer-actor cadence constants in `crates/clarion-storage/src/writer.rs`:
+
+```
+DEFAULT_BATCH_SIZE       (50,   writer.rs:38)
+DEFAULT_CHANNEL_CAPACITY (256,  writer.rs:35)
+```
+
+And the crash-loop breaker constants in `crates/clarion-core/src/plugin/breaker.rs`:
+
+```
+CRASH_LOOP_THRESHOLD     (rolling-window count)
+CRASH_LOOP_WINDOW        (rolling-window duration)
+```
+
+These are the constants the lint script will fail CI on if undeclared after the 1.1 release. Constants discovered after this ADR's authoring inherit the same rule from their first commit — there is no grandfather clause for new code.
+
+### 3. The 25-file Pyright restart constant — instance application
+
+`MAX_FILES_PER_PYRIGHT_SESSION = 25` (`plugins/python/src/clarion_plugin_python/server.py:49`) is the canonical worked example. Per `answer-python-engineer.md` and `answer-solution-architect.md`, the value was introduced in commit `68b719c` ("Bound Pyright dogfood analysis", 2026-05-20) with no commit-message rationale and no in-file comment. It is an empirical placeholder. The four-axis declaration for it, after retrofit, must be:
+
+- **Basis**: empirical placeholder; bound chosen during dogfood analysis to cap observed Pyright RSS growth across `textDocument/didOpen` cycles; not yet validated against a per-file RSS delta curve.
+- **Override**: `plugin.toml:pyright.files_per_session` (plugin-author-tunable per ADR-021's plugin-authority split — the Pyright session recycle is plugin-owned policy, not core-side).
+- **Retune**: any sampled Pyright subprocess RSS curve on the elspeth-scale corpus showing the inflection point is below 25 (recycle is wasted re-init cost) or above 25 (`CLA-INFRA-PLUGIN-OOM-KILLED` risk inside the 25-file window).
+- **Coupling**: `policy-paired-with:MAX_PYRIGHT_RESTARTS_PER_RUN` — server-side recycling at 25 files and session-side restart caps interact: the Python engineer documented a concrete failure mode where `_disabled` and `_restart_count` are instance-scoped on `PyrightSession` and reset at every 25-file boundary, breaking the "per run" intent of the restart cap. That interaction is a coupling fact the rule forces to be visible.
+
+The policy-paired-with coupling annotation interlocks with the Python engineer's `answer-python-engineer.md` "Failure mode A": once both constants declare the pairing, the next reviewer asking "is this safe to change in isolation?" reads the coupling and finds the answer in the source.
+
+### 4. File-LOC budget rule
+
+Any source file over **1,500 LOC** declares a split-trigger condition in its module doc-comment. The declaration shape is:
+
+```rust
+//! …
+//!
+//! ## LOC budget
+//!
+//! Current LOC at last review: <N> (<date>).
+//! Split trigger: <one concrete, observable condition>.
+//! Rationale for current state: <one sentence>.
+```
+
+The 1,500 LOC threshold is the floor. Files **already** over budget at this ADR's authoring receive a one-time grace period: the trigger must be declared in each file's module doc-comment before the 1.1 release. The four files in this category, with the catalog's snapshot LOC alongside the LOC at ADR authoring (the catalog was snapshotted before recent work; the working copy is smaller for two of the four):
+
+| File | Catalog LOC (2026-05-22) | LOC at ADR authoring | Split-trigger (per `answer-solution-architect.md` §2) |
+|---|---|---|---|
+| `crates/clarion-mcp/src/lib.rs` | 4,703 | 3,449 | Adding a 20th MCP tool, or any concurrent-tool-execution work. |
+| `crates/clarion-core/src/plugin/host.rs` | 2,935 | 2,935 | Adding a fifth enforcement layer or changing the four-stage pipeline ordering. |
+| `crates/clarion-cli/src/analyze.rs` | 2,549 | 2,427 | A 14th phase added to `run_with_options`'s current 13-phase linearisation. |
+| `crates/clarion-core/src/llm_provider.rs` | 2,467 | 2,467 | See ADR-035 §6 and `answer-solution-architect.md` §3 — this file's split is not "within crate" but "extract to `clarion-llm`." |
+
+The triggers above are recommendations from `answer-solution-architect.md` §2 and become the declared triggers in each file's module doc-comment via the grace-period retrofit. Each file's owner may revise its declared trigger in a later commit; the rule binds *declaration*, not *which specific trigger is declared*.
+
+### 5. Crate-boundary budget rule
+
+Any crate that takes a dependency widening its trust surface or contradicting its `lib.rs` doc-comment declares the trigger for crate extraction in its top-level `lib.rs` doc-comment. The shape is:
+
+```rust
+//! `<crate-name>` — <one-paragraph charter>.
+//!
+//! ## Crate-boundary budget
+//!
+//! Boundary statement: <what this crate is for; what is in vs. out>.
+//! Extraction trigger: <observable condition that would split content out>.
+//! Currently in-scope but extraction-candidate: <list of subsystems with named triggers>.
+```
+
+The current cited contradiction (per `answer-solution-architect.md` §3, `answer-security-engineer.md` Q3) is `clarion-core/src/lib.rs:1`'s doc-comment versus `clarion-core/src/llm_provider.rs`'s content. The boundary statement says "domain types, identifiers, and provider traits"; the content includes the OpenRouter `reqwest` HTTP transport and two CLI-subprocess providers — neither domain types, nor identifiers, nor trait definitions. **`detailed-design.md:1745` already names `clarion-llm` as one of the intended workspaces.** That intent + the security argument (an outbound-HTTP-stack CVE inside the plugin-supervisor crate widens the supervisor's trust surface) supplies the extraction trigger: *the `clarion-llm` extraction MUST land before any new LLM provider is added or before any change to `reqwest` / `rustls` / `hyper` that introduces a new transitive trust dependency.*
+
+`clarion-core/src/lib.rs` carries this declaration as part of the 1.1 grace-period retrofit. The same rule applies prospectively: a new crate whose `lib.rs` doc-comment is contradicted by its contents must either fix the contradiction or declare an extraction trigger.
+
+### 6. Lint script and CI gate
+
+A lint script lives at `scripts/operational-tuning-lint.{rs,py}` (the implementation language is at the script author's discretion, but the script is run from CI). The script:
+
+1. Walks the Rust workspace under `crates/**/src/**/*.rs` and the Python plugin under `plugins/python/src/**/*.py`.
+2. Identifies operational-constant candidates by syntactic match: `pub const` / `const` at module level in Rust; top-level `MAX_*` / `DEFAULT_*` / `*_TIMEOUT_*` / `*_LIMIT_*` / `*_BYTES` / `*_CAP` / `*_THRESHOLD` / `*_WINDOW` identifier patterns in Python. (The pattern set is conservative and pinned in the script; it can be widened in a later commit.)
+3. For each candidate, verifies that an adjacent `Basis: … / Override: … / Retune: … / Coupling: …` declaration is present and that `Override` and `Coupling` values come from the closed enums in §1.
+4. For each `.rs` file over 1,500 LOC, verifies that the module doc-comment contains an `## LOC budget` section with `Current LOC`, `Split trigger`, `Rationale for current state` lines.
+5. For each `lib.rs` whose doc-comment contradicts its content (heuristic: presence of `reqwest` / `tokio::process` / network crates not named in the boundary statement), verifies that a `Crate-boundary budget` section is present.
+6. Emits findings in the same JSON shape Clarion's other tooling uses (subcode prefix `CLA-DISC-TUNING-*`), one per undeclared constant or undeclared oversize file.
+
+The script is wired into CI as a non-blocking warning until the 1.1 release. **At the 1.1 release the gate flips from warning to failure** — any undeclared operational constant, oversize file, or contradicted crate boundary fails the CI build. The flip date is the trigger for landing the retrofits enumerated in §2, §4, and §5.
+
+The three `#[allow(clippy::too_many_lines)]` sites in `crates/clarion-cli/src/analyze.rs` (lines 65, 650, 1190) MUST be either re-enabled (the underlying functions split) or replaced with a documented `// allow: ADR-035 §4 — declared split-trigger: <trigger>` comment before the 1.1 release. The clippy threshold itself (`too-many-lines-threshold = 120` per ADR-023's `clippy.toml`) remains the baseline; an `#[allow]` without an ADR-035 reference fails the lint script regardless of whether `cargo clippy` itself passes.
+
+### 7. Constant-graduation lifecycle
+
+A constant's life under the rule has three states:
+
+1. **Hardcoded with declaration.** The constant is in source, has the four-axis declaration, and `Override = recompile`. This is the steady state for constants the operator should not touch — security-uniformity constants per `answer-security-engineer.md` Q5, wire-contract constants whose change is an `api_version` bump, and constants whose retune trigger has not yet fired.
+2. **Tunable.** The constant has `Override = clarion.yaml:<field>` (or `env:<var>` or `plugin.toml:<field>`) and the config-loader actually reads the value. Hard floors enforced at config-load time per ADR-021 §2b are part of this state — the operator can raise the value but not lower it past the floor.
+3. **Deprecated.** The constant's basis is replaced by a superseding constant or rule; the declaration carries a `Deprecated: see <new constant or ADR>` line; the constant is removed at the next major version bump.
+
+Graduating a constant from state 1 to state 2 is a normal commit; graduating from state 2 to state 3 requires either an ADR or a documented field-deprecation note in `docs/clarion/1.0/detailed-design.md`. Demoting from state 2 back to state 1 — removing an operator surface — requires an ADR. This asymmetry codifies the "ratchet" the systems thinker named.
+
+### 8. What is explicitly out of scope for this ADR
+
+- **The wire-pinned batch cap of 256 queries** in `POST /api/v1/files/batch` is pinned by ADR-034 §3 with `Override = wire:contracts.md#batch-cap` semantics. ADR-035's rule applies (the constant must carry a four-axis declaration), but the override surface is not operator-tunable; a change is an `api_version: 2` event by ADR-034's existing rule.
+- **`application_id` and `user_version` PRAGMAs** for SQLite are tracked as filigree issue `clarion-f2a984fd6d` per `answer-solution-architect.md` §4 and `answer-quality-engineer.md` Q4. ADR-035's "schema-identity" instance of the rule applies (the PRAGMA value MUST carry a `Basis: identifies the file as Clarion's per ADR-035` declaration), but the implementation lands as the filigree issue's deliverable, not this ADR's.
+- **Specific config-schema design** for `clarion.yaml` post-1.0 belongs in WP6 per `answer-solution-architect.md` §5. This ADR commits the rule about how constants graduate; the specific YAML key shape is the matter of the work package that implements the graduation.
+
+## Consequences
+
+### Positive
+
+- The five §8 open questions collapse to one durable artifact. Q1 (the 25-file constant), Q4 (PRAGMA identity), and Q5 (eleven hardcoded limits) each gain a recorded basis and a tuning surface; Q2 (four monoliths) and Q3 (`clarion-llm` extraction) become budgeted properties with named triggers rather than aesthetic preferences competing with sprint load.
+- The runtime balancing loops already in the project (path-escape breaker, crash-loop breaker, parent-contains bijection, L2 parity fixture) gain a design-time peer. Per the systems thinker, "the runtime has back-pressure; the architecture itself does not." This ADR is the missing back-pressure at the design-time layer.
+- The constant-coupling axis surfaces dangerous interactions that today are invisible. Once `MAX_FILES_PER_PYRIGHT_SESSION` and `MAX_PYRIGHT_RESTARTS_PER_RUN` both carry `policy-paired-with:<sibling>`, the Python engineer's "Failure mode A" (the 25-file boundary silently resetting the per-run restart cap) becomes a fact a reviewer reads in the source, not a defect a future SME has to rediscover. Similarly, the three wire-paired-with Python ↔ Rust constants gain the `# NOTE: must match clarion-core/…` comment the Python engineer flagged as missing.
+- The lint script is the enforcement mechanism that prevents this ADR from being aspirational. A rule the project does not enforce is, per the same drift-to-low-performance archetype, a rule the project does not have. The CI gate is the countervailing signal.
+- ADR-021's "configurable" claim becomes a substantive promise on a known timeline. Today, "operator can tune" is aspirational (per `02-subsystem-catalog.md` §1); under this ADR, every constant that says it is tunable has a config-load-time floor and a retune trigger. Constants that say they are not tunable carry that as a deliberate stance (security-uniformity per `answer-security-engineer.md` Q5), not a deferral.
+- Cross-product trust-surface arguments become first-class. The `clarion-llm` extraction (per `answer-security-engineer.md` Q3) is a defense-in-depth win once it lands: an outbound-HTTP-stack CVE no longer reaches the plugin-supervisor crate. The crate-boundary budget rule (§5) gives that extraction a declared trigger rather than a vague intention in `detailed-design.md`.
+
+### Negative
+
+- Source comment volume increases. Every operational constant gains 4–5 lines of comment. For the twelve constants in `clarion-core` plus the nine in the Python plugin plus the two writer-actor cadence constants plus the two breaker constants, the retrofit is on the order of 100 lines of comment across the workspace — bounded but non-trivial.
+- The lint script is one more piece of in-repo tooling to maintain. ADR-023's existing five CI gates become six (fmt, clippy, nextest, doc, deny, **tuning-lint**). The script must keep pace with new constant-naming patterns (e.g., a future `MAX_CALLEE_DEPTH` that doesn't match the current `MAX_*_BYTES` heuristic). Mitigation: the script's pattern set is in source, reviewable, and one PR away from a fix.
+- The four-axis declaration imposes authoring friction on new constants. A contributor adding a new `MAX_FOO` must, before merging, identify the constant's basis, decide its override surface, name its retune trigger, and trace its coupling. This is the intended shape — the friction is the rule — but it raises the per-commit cost of adding limits compared to today.
+- The 1,500-LOC budget threshold is a judgement call. Set lower, it would force more files to declare triggers (potentially valuable but noisier); set higher, it would let `host.rs` and `analyze.rs` evade declaration. 1,500 LOC is chosen as the floor where a file becomes hard to read end-to-end in one sitting; it is not derived from a study. Mitigation: this threshold is itself an operational constant under this ADR's rule, and its retune trigger is "any file declares a trigger and the trigger is consistently 'never'" — a sign the threshold is too lax.
+- The `clarion-llm` extraction trigger commits a future split that may bring its own churn. Per `answer-solution-architect.md` §3, the LLM surface is at its minimum scope right now (post-ADR-030 narrowing of WP6); the split is cheap today and expensive later. The risk is that "ship the v1.0 tag" pressure interacts with "land the crate extraction" and either delays the tag or rushes the split. Mitigation: the trigger names the condition (any new LLM provider, any change to the network-stack transitive deps), so the split is reactive to a forcing function rather than scheduled.
+
+### Neutral
+
+- This is a level-5 (rules) Meadows intervention. Leverage-point hierarchy: level 12 is "parameters" (the constants themselves), level 6 is "information flows" (the four-axis declaration is one), level 5 is "rules" (this ADR). A level-12 intervention — just adding `clarion.yaml` keys without the rule — would, per `answer-systems-thinker.md`, decay back to hardcoded constants by the next sprint. A level-6 intervention — emitting metrics on every constant's observable behaviour — would over-instrument before knowing which constants matter. The level-5 rule is the floor: it forces declaration without forcing exposure or instrumentation; the exposure and instrumentation become subsequent commits gated by declared retune triggers.
+- The "internal, no override" state (state 1 in §7) is an allowed terminal state. A constant whose basis is "uniform security policy across deployments per ADR-035 §3 stance" and whose override surface is `recompile` is fully compliant with the rule. The discipline is *declaration*, not *exposure*; the security engineer's concern that exposing all 11 limits as operator surface creates a support burden (`answer-security-engineer.md` Q5) is preserved by allowing this state.
+- ADR-029's entity-association binding is a different mechanism for a different problem. ADR-029 binds Filigree issues to source entities; ADR-035 imposes a source-comment discipline on operational constants. The two mechanisms can be combined (an unresolved retune trigger could be filed as a filigree issue and bound to the constant's entity ID via ADR-029) but neither requires the other. This ADR is not a Filigree integration.
+- ADR-034 §3's wire-pinned batch cap of 256 queries is an instance of the rule, not an exception to it. The constant carries `Override = wire:contracts.md#batch-cap` and `Coupling = wire-paired-with:Filigree client splitting logic`. The override-surface enum's `wire:*` value exists exactly for this case.
+- This ADR's "lint script in CI" enforcement mechanism is itself an operational constant under the rule (its `Retune` trigger is "any retroactive retrofit of new constants becomes routinely required at code-review time rather than at lint-script time, suggesting the lint set is too narrow"). The rule applies to itself.
+
+## Alternatives Considered
+
+### Alternative 1: ship `clarion.yaml` with all eleven constants as keys and call it done
+
+**Pros**: most operationally tactile; an operator can `cat clarion.yaml` and see what is tunable. Implementation surface is bounded — eleven keys, eleven config-loader sites, eleven floor checks. Matches ADR-021 §4's existing four named keys and extends them naturally to the other seven.
+
+**Cons**: this is a level-12 (parameters) intervention to a drift-to-low-performance loop. Per `answer-systems-thinker.md`:
+
+> "A config file without the rule decays back to hardcoded constants on the next sprint — that is exactly how Clarion got here. The rule is what creates the surface; the surface alone is a parameter intervention (Level 12) and parameter interventions to a drift-to-low-performance loop reset the constant without changing the slope."
+
+The eleven constants in `clarion-core` were not added all at once; they accreted over Sprints 1 and 2. Adding `clarion.yaml` without the rule that gates how the *next* constant graduates means the twelfth, thirteenth, fourteenth constants land hardcoded again, with `breaker.rs:7`-style "lands in WP6" comments, and the cycle repeats. The discipline must precede the surface, not follow it.
+
+**Why rejected**: the parameter intervention does not change the rate at which new constants accrete; only the rule does.
+
+### Alternative 2: defer the rule to the WP6 work package post-1.0
+
+**Pros**: matches the solution architect's "ship 1.0 with the limits hardcoded; land the config surface in WP6 post-1.0 as one ADR-021-aligned change" recommendation almost verbatim. Avoids ADR churn during release cut. The five §8 questions are not 1.0 blockers; the gap-register has `application_id`/`user_version` as the only constant-related v1.0 blocker, and that has its own filigree issue.
+
+**Cons**: the solution architect's recommendation is about *implementation timing* of the config surface, not about *whether the rule exists*. The rule and the implementation are separable: this ADR commits the rule now (level 5), and WP6's post-1.0 implementation lands the surface on the rule's existing framework (level 12 underneath the level-5 rule). Deferring the rule itself means WP6 lands the surface without a governing discipline — the same configuration-without-rule trap Alternative 1 falls into, with a one-WP delay.
+
+The systems thinker's recommendation is explicit: *"Promote it to Accepted before any further hardcoded limit lands."* The cost of accepting the rule now is the four-axis-declaration retrofit. The cost of accepting the rule later is that any constant added between now and WP6 lands without the discipline, has to be retrofitted twice (once for the rule, once for the WP6 graduation), and the lint-script gate flips later, lengthening the drift window.
+
+**Why rejected**: rule and implementation are separable; accepting the rule now is cheaper than accepting it later, and the rule is what makes the implementation durable.
+
+### Alternative 3: rely on code review to catch undeclared constants
+
+**Pros**: no new tooling. Reviewers already inspect new constants for naming, type, and call-site usage; adding "is there a retune trigger?" to the review checklist is one more line on a checklist.
+
+**Cons**: code review is a probabilistic catch, not a deterministic one. The systems thinker's archetype — drift to low performance — predicts exactly the failure mode where reviewers locally accept "we'll document this later" and the documentation never lands. The five §8 questions are evidence the catch-rate is below what the project needs. The literal `#[allow(clippy::too_many_lines)]` at `analyze.rs:65` is what reviewer-only enforcement looks like in this codebase today: a reviewer accepted the allow because it shipped the function; the standard-lowering act is visible in code.
+
+A CI lint script is deterministic: the build either fails or it does not. The countervailing signal is mechanical, not human, and runs on every PR.
+
+**Why rejected**: code review's catch-rate is what this ADR is trying to compensate for, not augment.
+
+### Alternative 4: extract `clarion-llm` immediately as the high-impact intervention; defer the broader rule
+
+**Pros**: closes the security-engineer's STRIDE-T/STRIDE-I argument fastest (the outbound-HTTP stack stops sharing a crate with the plugin supervisor); concrete deliverable; survives `cargo clippy`.
+
+**Cons**: solves one of the five questions and leaves the other four unaddressed. The five questions are one pattern; intervening on Q3 alone is a parameter-level move on a single constant (the crate boundary) without changing the slope on the others. The next sprint adds the twelfth hardcoded limit and the §8 list grows from five questions to six.
+
+Also: the extraction *is* part of this ADR (§5's crate-boundary budget rule, with the trigger naming exactly the security-engineer's condition). Accepting the rule causes the extraction; accepting only the extraction does not cause the rule.
+
+**Why rejected**: a single-constant intervention does not address a pattern of multiple constants accreting under the same archetype.
+
+### Alternative 5: an ADR that demands a richer declaration (per-constant doc page; per-constant test; per-constant metric)
+
+**Pros**: maximum traceability; a future architect could query any constant and find its full lineage.
+
+**Cons**: scope-creep into ceremony. The systems thinker's risk register named this explicitly:
+
+> "An ADR that demands a basis for every constant could ossify into ceremony. Mitigation: the basis statement is one sentence; the trigger is one finding subcode. Anything more is the wrong shape."
+
+A per-constant test is the right discipline for *some* constants (the security-enforcement cluster per `answer-quality-engineer.md` Q5) but not all (the ring-buffer-overflow eviction in `STDERR_TAIL_BYTES` is "Partially tested" and acceptable). A per-constant metric over-instruments before knowing which constants matter operationally. A per-constant doc page is what `02-subsystem-catalog.md` already produces at architecture-review time; pre-producing them for every constant inverts the relationship.
+
+The four-axis declaration is the floor — additional discipline can be layered above it (a quality-engineering follow-up to add a behavioural test for `DEFAULT_MAX_RSS_MIB` is fully within scope of the current quality engineering sheets) without enlarging the rule itself.
+
+**Why rejected**: the rule's shape — short, mechanical, lint-checkable — is what makes it a level-5 intervention rather than ceremony. Richer shapes are level-6/7 interventions appropriate for specific constant clusters, not the workspace-wide floor.
+
+## Related Decisions
+
+- [ADR-021](./ADR-021-plugin-authority-hybrid.md) — Plugin authority hybrid; §4 names four of the eleven operational constants (`plugin_limits.max_frame_bytes`, `plugin_limits.max_records_per_run`, `plugin_limits.max_rss_mib`, `expected_max_rss_mb`) as `clarion.yaml` config keys. ADR-035 generalises the discipline that ADR-021 §4 already implies and extends it to every operational constant.
+- [ADR-023](./ADR-023-tooling-baseline.md) — Tooling baseline; defines `clippy.toml`'s `too-many-lines-threshold = 120`. ADR-035 §4's 1,500-LOC budget operates above ADR-023's per-function threshold — the two thresholds apply to different units (function vs. file) and do not conflict. The `#[allow(clippy::too_many_lines)]` sites in `analyze.rs` are ADR-023 escapes; ADR-035 §6 requires either re-enabling them or pairing each with a declared split trigger.
+- [ADR-030](./ADR-030-on-demand-summary-scope.md) — Narrowed WP6 to the on-demand `summary(id)` MCP tool, leaving the operator-tunables work currently un-homed per `answer-solution-architect.md` §5. ADR-035 commits the governing rule; the implementation of the config surface lands in a post-1.0 work package (TBD) that operates on top of this ADR's framework.
+- [ADR-034](./ADR-034-federation-http-read-api-hardening.md) — Federation HTTP read API hardening; §3's wire-pinned 256-query batch cap is an instance of ADR-035's rule (`Override = wire:contracts.md#batch-cap`). The two ADRs do not conflict; ADR-034 specifies the wire contract, ADR-035 specifies the source-comment discipline.
+- [ADR-029](./ADR-029-entity-associations-binding.md) — Entity-association binding; explicitly orthogonal to ADR-035. An unresolved retune trigger could be filed as a filigree issue and bound to the constant's entity ID via ADR-029, but the binding is not required.
+
+## References
+
+### Originating analysis (2026-05-22 architecture review)
+
+- Final report `§8 Open Questions`: [`docs/arch-analysis-2026-05-22-1924/04-final-report.md`](../../arch-analysis-2026-05-22-1924/04-final-report.md#8-open-questions-for-the-next-phase) — the five questions this ADR's rule absorbs.
+- Subsystem catalog `clarion-core` Concerns: [`02-subsystem-catalog.md`](../../arch-analysis-2026-05-22-1924/02-subsystem-catalog.md) §1 — the eleven-limit enumeration; the "every limit is a recompile" tell; the `mock.rs` 876-LOC sign of non-trivial host pipeline state.
+- Subsystem catalog `clarion-storage` Concerns: §2 — the `application_id`/`user_version` gap; the writer-actor cadence constants (256 / 50) at `writer.rs:35,38`.
+
+### SME roundtable (2026-05-23)
+
+- Solution architect: [`temp/answer-solution-architect.md`](../../arch-analysis-2026-05-22-1924/temp/answer-solution-architect.md) — WP6 home triangulation; the "ship 1.0 with limits hardcoded; land config surface in WP6 as one ADR-021-aligned change" frame; the per-file split-trigger table.
+- Systems thinker: [`temp/answer-systems-thinker.md`](../../arch-analysis-2026-05-22-1924/temp/answer-systems-thinker.md) — the level-5 (rules) leverage argument; the drift-to-low-performance archetype; the `analyze.rs:74` and `breaker.rs:7` smoking-gun tells (line numbers as recorded at analysis time; current `analyze.rs` `#[allow(clippy::too_many_lines)]` site has shifted to line 65 with two additional sites at 650 and 1190; the rule applies to all three).
+- Python engineer: [`temp/answer-python-engineer.md`](../../arch-analysis-2026-05-22-1924/temp/answer-python-engineer.md) — the wire-contract-pinned vs. operational-tunable Python constant classification; the `MAX_PYRIGHT_RESTARTS_PER_RUN` "per run" name vs. per-instance implementation interaction failure; the basis for the `Coupling` axis.
+- Quality engineer: [`temp/answer-quality-engineer.md`](../../arch-analysis-2026-05-22-1924/temp/answer-quality-engineer.md) — the per-constant test-coverage matrix; the `DEFAULT_MAX_RSS_MIB`/`DEFAULT_MAX_NOFILE`/`DEFAULT_MAX_NPROC` security-enforcement cluster as the highest-risk untested area.
+- Security engineer: [`temp/answer-security-engineer.md`](../../arch-analysis-2026-05-22-1924/temp/answer-security-engineer.md) — the STRIDE-D/STRIDE-E framing of recompile-to-tune as a security-posture stance; the `clarion-llm` extraction as STRIDE-T/STRIDE-I defense-in-depth; the security-uniformity argument for keeping some constants `Override = recompile`.
+
+### Source-of-truth code locations
+
+- `crates/clarion-core/src/plugin/limits.rs` — `ContentLengthCeiling::DEFAULT`, `EntityCountCap::DEFAULT_MAX`, `DEFAULT_MAX_RSS_MIB`, `DEFAULT_MAX_NOFILE`, `DEFAULT_MAX_NPROC`.
+- `crates/clarion-core/src/plugin/host.rs` — `MAX_ENTITY_FIELD_BYTES`, `MAX_ENTITY_EXTRA_BYTES`, `STDERR_TAIL_BYTES`, `MAX_UNRESOLVED_CALLEE_EXPR_BYTES`, `PYRIGHT_MAX_NPROC`.
+- `crates/clarion-core/src/plugin/breaker.rs:7` — the literal "lands in WP6" comment that this ADR retires; `CRASH_LOOP_THRESHOLD`, `CRASH_LOOP_WINDOW`.
+- `crates/clarion-core/src/plugin/protocol.rs` — `MAX_PROTOCOL_ERROR_FIELD_BYTES`.
+- `crates/clarion-core/src/plugin/transport.rs` — `MAX_HEADER_LINE_BYTES`.
+- `crates/clarion-storage/src/writer.rs:35,38` — `DEFAULT_CHANNEL_CAPACITY = 256`, `DEFAULT_BATCH_SIZE = 50`.
+- `crates/clarion-cli/src/analyze.rs:65,650,1190` — three `#[allow(clippy::too_many_lines)]` sites that ADR-035 §6 requires either re-enabling or pairing with a declared split trigger before the 1.1 release.
+- `plugins/python/src/clarion_plugin_python/server.py:48,49` — `MAX_CONTENT_LENGTH = 8 MiB` (wire-paired-with Rust), `MAX_FILES_PER_PYRIGHT_SESSION = 25`.
+- `plugins/python/src/clarion_plugin_python/pyright_session.py:43-49` — six Pyright-session operational constants enumerated by `answer-python-engineer.md`.
+
+### Doctrine the rule operationalises
+
+- Meadows, Donella H., *Thinking in Systems: A Primer*. Level-5 (rules) and level-6 (information flows) leverage points in the twelve-level hierarchy.
+- The doctrine in [`docs/suite/loom.md`](../../suite/loom.md) §5 — the federation axiom's "enrich-only" rule applies by analogy to constants: a constant that gates externally observable behaviour without a declared basis is the same archetype as a sibling tool that adds a required dependency.
+
+— End of ADR-035 —
diff --git a/docs/clarion/adr/README.md b/docs/clarion/adr/README.md
index f0390d5f..19fb0759 100644
--- a/docs/clarion/adr/README.md
+++ b/docs/clarion/adr/README.md
@@ -14,9 +14,9 @@ This folder is the canonical home for authored Clarion architecture decision rec
 | [ADR-006](./ADR-006-clustering-algorithm.md) | Clustering algorithm — Leiden on imports+calls subgraph; fallback amended by ADR-032 | Accepted; amended |
 | [ADR-007](./ADR-007-summary-cache-key.md) | Summary cache key — 5-part composite with TTL backstop and churn-eager invalidation | Accepted |
 | [ADR-011](./ADR-011-writer-actor-concurrency.md) | Writer-actor concurrency with per-N-files transactions; `--shadow-db` opt-in | Accepted |
-| [ADR-012](./ADR-012-http-auth-default.md) | HTTP read-API authentication — UDS default with token fallback | Accepted |
+| [ADR-012](./ADR-012-http-auth-default.md) | HTTP read-API authentication — UDS default with token fallback | Superseded for ADR-014 registry-backend API |
 | [ADR-013](./ADR-013-pre-ingest-secret-scanner.md) | Pre-ingest secret scanner with LLM-dispatch block | Accepted |
-| [ADR-014](./ADR-014-filigree-registry-backend.md) | Filigree `registry_backend` flag and pluggable `RegistryProtocol` | Accepted |
+| [ADR-014](./ADR-014-filigree-registry-backend.md) | Filigree `registry_backend` flag and pluggable `RegistryProtocol` | Accepted; partially extended by ADR-034 |
 | [ADR-015](./ADR-015-wardline-filigree-emission.md) | Wardline→Filigree emission ownership — Clarion-side SARIF translator (v0.1), native Wardline emitter (v0.2) | Accepted |
 | [ADR-016](./ADR-016-observation-transport.md) | Observation transport — MCP-spawn (v0.1), Filigree HTTP endpoint (v0.2) | Accepted |
 | [ADR-017](./ADR-017-severity-and-dedup.md) | Severity mapping, rule-ID round-trip, and dedup policy | Accepted |
@@ -33,6 +33,8 @@ This folder is the canonical home for authored Clarion architecture decision rec
 | [ADR-030](./ADR-030-on-demand-summary-scope.md) | On-demand summary scope — narrows WP6 to MCP-driven `summary(id)`; 5-tuple cache key unchanged; module/subsystem aggregation deferred to v0.2 | Accepted |
 | [ADR-031](./ADR-031-schema-validation-policy.md) | Schema-validation policy — CHECK on closed core-owned vocabularies (`findings.{kind,severity,status}`, `runs.status`); writer-actor + manifest are the only enforcement layer for plugin-extensible vocabularies (`entities.kind`, `edges.kind`) | Accepted |
 | [ADR-032](./ADR-032-weighted-components-clustering-fallback.md) | Weighted-components clustering fallback naming | Accepted |
+| [ADR-033](./ADR-033-v1.0-distribution.md) | v1.0 distribution via GitHub Releases (binary matrix + Python sdist; promote to crates.io/PyPI at v2.0) | Accepted |
+| [ADR-034](./ADR-034-federation-http-read-api-hardening.md) | Federation HTTP read API hardening — bearer auth, batch resolution, `BRIEFING_BLOCKED`, instance ID | Accepted |
 
 ## Backlog still tracked in the detailed design
 
@@ -48,7 +50,7 @@ The following decisions are still backlog items rather than authored ADR files.
 
 ## Pre-implementation scope commitments
 
-The priorities and scope implied by these ADRs are committed in [../v0.1/plans/v0.1-scope-commitments.md](../v0.1/plans/v0.1-scope-commitments.md). The ADR authoring sprint is staged against that memo.
+The priorities and scope implied by these ADRs are committed in [../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md](../../implementation/v0.1-scope-plans/v0.1-scope-commitments.md). The ADR authoring sprint is staged against that memo.
 
 ## ADR acceptance criteria — Loom vocabulary discipline
 
diff --git a/docs/federation/2026-05-30-prune-unseen-filigree-request.md b/docs/federation/2026-05-30-prune-unseen-filigree-request.md
new file mode 100644
index 00000000..4c17514e
--- /dev/null
+++ b/docs/federation/2026-05-30-prune-unseen-filigree-request.md
@@ -0,0 +1,107 @@
+# Request to Filigree — `scan_source`-scoped finding retention/prune surface (+ scan-run-create contract decision)
+
+> **⚠️ PRUNE ASK WITHDRAWN / SUPERSEDED (2026-05-30).** The prune surface this
+> memo requested **already exists** in Filigree:
+> `POST /api/loom/findings/clean-stale` with body
+> `{"scan_source": "clarion", "older_than_days": 30, "actor": "…"}` →
+> `{"findings_fixed": N, "scan_source": "…", "older_than_days": N}`. It
+> soft-archives `unseen_in_latest` findings to `fixed` (auto-reopen on
+> reappearance; Filigree ADR-015), `scan_source` required server-side as an
+> accident-guard. Verified against Filigree's handler
+> (`src/filigree/dashboard_routes/files.py`) and its API tests. Clarion's
+> `--prune-unseen` now consumes it directly (REQ-FINDING-06 done); the contract
+> is pinned in `docs/federation/contracts.md` → "Consumed Filigree route:
+> clean-stale retention". My §1–§3 and §5 below (asking Filigree to *design and
+> build* a prune surface) are therefore **moot** — the original "no prune route
+> exists" premise was wrong. **§4 (scan-run-create contract decision) is the
+> only live ask** and remains open.
+
+**Status:** Prune ask withdrawn; §4 (scan-run-create) open (2026-05-30)
+**Author side:** Clarion
+**Tracking issue (Clarion):** §4 tracked under a `release:1.1` issue (Phase-0 scan-run-create handshake); the prune/`--prune-unseen` piece of `clarion-dd29e69e0e` is done.
+**Sibling docs:**
+- Clarion `docs/federation/contracts.md` → "Consumed Filigree route: clean-stale retention" (the route Clarion now consumes) and "…: scan-results intake".
+- Clarion `docs/clarion/1.0/requirements.md` → REQ-FINDING-05, REQ-FINDING-06.
+- Filigree intake handler for reference: `db.process_scan_results` (`db_files.py:857-926`, per ADR-014).
+
+> **Note on placement.** This is a Clarion-authored *request to* Filigree, kept here for Clarion's reference. The authoritative Filigree-side artifact (design + implementation) should live in the Filigree repo; refresh `docs/federation/filigree-side/` with a mirror once Filigree drafts its response.
+
+---
+
+> The §1–§3 / §5 prune-design sections below are retained only as a record of
+> the (mistaken) original request; see the withdrawal banner above. Skip to §4
+> for the live question.
+
+## 1. Problem in one paragraph
+
+Clarion emits findings into Filigree via `POST /api/v1/scan-results` with
+`scan_source: "clarion"`, `mark_unseen: true`, `complete_scan_run: true`. When
+`mark_unseen` is set, Filigree transitions old-position findings for the same
+rule/file that weren't in the latest scan to `unseen_in_latest`. Over repeated
+runs these accumulate. Clarion's REQ-FINDING-06 wants `clarion analyze
+--prune-unseen` to "remove `unseen_in_latest` findings older than 30 days
+(configurable)." Clarion has **no way to do this** — there is no
+prune/delete/retention route on Filigree's side (confirmed: nothing in Clarion's
+`FiligreeHttpClient`, in the pinned `docs/federation/contracts.md`, or in the
+Filigree MCP/HTTP tool surface). It is a server-side retention operation Clarion
+cannot implement alone.
+
+## 2. Federation constraint (load-bearing — `loom.md` §3–§5)
+
+- **Enrich-only.** Filigree's finding lifecycle must remain fully correct if
+  Clarion *never* calls prune. Prune is an optional retention convenience, never
+  a required step. Introduce no coupling where Filigree depends on Clarion
+  calling it.
+- **`scan_source`-scoped.** The operation must be scoped so Clarion can only
+  prune its own (`clarion`) findings and can never affect Wardline's or any
+  other tool's findings.
+
+## 3. Primary ask — design and implement a prune surface
+
+Resolve these and implement:
+
+1. **Surface shape.** Pick one and justify:
+   - (a) a dedicated route, e.g. `POST /api/v1/findings:prune` with body
+     `{ "scan_source": "clarion", "unseen_older_than_days": 30 }`;
+   - (b) `DELETE /api/v1/findings?scan_source=clarion&unseen_in_latest=true&older_than_days=30`;
+   - (c) a field on the existing scan-results intake (e.g.
+     `prune_unseen_older_than_days`) so prune piggybacks on the completing POST.
+
+   (c) avoids a new route but conflates emit and retention; (a)/(b) are cleaner
+   separations. Your call.
+2. **Semantics — delete vs. archive.** REQ-FINDING-06 says "removes," but you own
+   findings lifecycle: decide whether prune hard-deletes or soft-archives /
+   dismisses (audit-preserving). Clarion only needs *a* retention trigger; the
+   durability/audit policy is yours.
+3. **"Age" definition.** What timestamp gates the 30-day threshold — when the
+   finding first transitioned to `unseen_in_latest`, or `updated_at` / last-seen?
+   If there is no "became-unseen-at" timestamp today, that may need adding.
+4. **Response shape.** Return counts (e.g.
+   `{ "findings_pruned": N, "scan_source": "clarion" }`) so Clarion can log the
+   outcome in `stats.json`.
+5. **Auth.** Same posture as `/api/v1/scan-results`: `Authorization: Bearer
+   <token>` + `x-filigree-actor: <actor>` headers.
+
+## 4. Secondary ask — scan-run-create contract decision (Clarion REQ-FINDING-05)
+
+Clarion currently POSTs findings with a `scan_run_id` that Filigree has never
+seen; Filigree tolerates the unknown id, emits a warning, and proceeds. Clarion
+is deciding whether to add a Phase-0 "create the scan run first" handshake.
+
+**Question for Filigree:** is "tolerate unknown `scan_run_id`, warn, proceed" the
+intended *permanent* contract (Clarion will then document that and stop treating
+the warning as a gap), or do you want an explicit create endpoint (e.g.
+`POST /api/v1/scan-runs` accepting a client-supplied id, or returning a
+server-assigned one)? Answer this; only build the endpoint if you want it.
+
+## 5. Deliverables / acceptance criteria
+
+- The chosen prune surface implemented, with `scan_source` scoping enforced
+  (a test proving a `clarion`-scoped prune leaves `wardline` findings untouched).
+- The wire request/response shape documented on Filigree's side **and** a
+  normative fixture, so Clarion can mirror it in `docs/federation/contracts.md`
+  (matching how the scan-results intake and the `/api/v1/files` family are
+  pinned there).
+- A test that prune is enrich-only: deleting/archiving via prune doesn't corrupt
+  the seen/unseen state of findings still present in the latest scan.
+- A written answer to the scan-run-create question in §4.
diff --git a/docs/federation/contracts.md b/docs/federation/contracts.md
new file mode 100644
index 00000000..13d0dfc8
--- /dev/null
+++ b/docs/federation/contracts.md
@@ -0,0 +1,638 @@
+# Clarion Federation Contracts
+
+This file pins Clarion's read-side contract for sibling products. The initial
+consumer is Filigree's `ClarionRegistry` from ADR-014.
+
+## HTTP Read API
+
+`clarion serve` can expose the HTTP read API when enabled in `clarion.yaml`:
+
+```yaml
+serve:
+  http:
+    enabled: true
+    bind: 127.0.0.1:9111
+    # Preferred 1.0 identity mode. Optional on loopback, required for
+    # authenticated Loom component requests.
+    identity_token_env: CLARION_LOOM_IDENTITY_SECRET
+    # Name of the env var holding the inbound bearer token. Optional on a
+    # loopback bind, accepted for compatibility on non-loopback binds. Default
+    # `CLARION_LOOM_TOKEN` matches Filigree's pinned client default.
+    token_env: CLARION_LOOM_TOKEN
+```
+
+The MCP stdio server remains available on stdin/stdout. The HTTP surface is
+read-only and uses Clarion's existing SQLite reader pool.
+
+### Authentication
+
+The `/api/v1/files`-family endpoints require
+`X-Loom-Component: clarion:<hmac>` when Clarion has resolved
+`serve.http.identity_token_env` at startup. The HMAC is lowercase hex
+HMAC-SHA256 over the canonical message:
+
+```text
+<METHOD>
+<PATH_AND_QUERY>
+<SHA256_HEX_OF_REQUEST_BODY>
+```
+
+`/api/v1/_capabilities` is **always** unauthenticated so siblings can probe the
+API surface pre-auth. Clarion still accepts the older
+`Authorization: Bearer <token>` path when `token_env` resolves and
+`identity_token_env` is not configured.
+
+Trust matrix (enforced by `HttpReadConfig::validate_auth_trust` at
+startup, before binding):
+
+| Bind | `identity_token_env` resolved | `token_env` resolved | Behaviour |
+|---|---|---|---|
+| Loopback | unset | unset | Unauthenticated; allow all requests. |
+| Loopback | set | any | HMAC required on protected routes; capabilities always allowed. |
+| Loopback | configured but env missing | any | **Refuse to start** with `CLA-CONFIG-HTTP-IDENTITY-MISSING`. |
+| Non-loopback | set | any | HMAC required on protected routes. |
+| Non-loopback | unset | set | Bearer required on protected routes. |
+| Non-loopback | unset | unset | **Refuse to start** with `CLA-CONFIG-HTTP-NO-AUTH`. |
+
+Authentication rejection (header absent, wrong scheme/prefix, wrong token or
+signature, blank token or signature) returns:
+
+```http
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+
+{"error": "authentication required", "code": "UNAUTHENTICATED"}
+```
+
+Secret comparison is constant-time so a wrong-length client cannot distinguish
+"header absent" from "secret mismatch" via timing. The secret itself is never
+logged; the bind-time log line records `auth=hmac`, `auth=bearer`, or
+`auth=none`, not the secret value.
+
+All non-2xx responses use this closed JSON error envelope:
+
+```json
+{
+  "error": "path does not resolve to a Clarion file entity",
+  "code": "NOT_FOUND"
+}
+```
+
+The initial `code` enum is closed to `INVALID_PATH`,
+`PATH_OUTSIDE_PROJECT`, `NOT_FOUND`, `BRIEFING_BLOCKED`, `UNAUTHENTICATED`,
+`STORAGE_ERROR`, `BATCH_TOO_LARGE`, and `INTERNAL`. Clients must switch
+on `code`; `error` is human-readable diagnostic text. `BATCH_TOO_LARGE`
+is only emitted by `POST /api/v1/files/batch` (see the batch endpoint
+section below).
+
+### `GET /api/v1/files?path=&language=`
+
+Resolves a project-relative or absolute file path to the Clarion file identity
+Filigree stores as `file_records.id` when `registry_backend: clarion` is active.
+
+Query parameters:
+
+| Name | Required | Meaning |
+|---|---:|---|
+| `path` | yes | File path under the Clarion project root. |
+| `language` | no | Caller-supplied language hint. If absent, Clarion infers from the source entity or file extension. |
+
+Successful response:
+
+```json
+{
+  "entity_id": "core:file:demo.py",
+  "content_hash": "hash-demo-file",
+  "canonical_path": "demo.py",
+  "language": "python"
+}
+```
+
+Semantics:
+
+- `entity_id` is opaque to Filigree and follows ADR-003's file-kind shape
+  `core:file:{qualified_name}`.
+- `content_hash` is the drift signal Filigree stores with the resolved row.
+- `canonical_path` is Clarion's project-relative canonical path: no leading
+  `/`, no leading `./`, no trailing `/`, and `/` as the separator on every
+  platform.
+- `language` is the normalized language value Clarion used for the resolution.
+- Unknown or outside-project paths return a non-2xx JSON error instead of
+  guessing.
+- If no file-kind entity row exists for the path, Clarion returns
+  `404` with `code: "NOT_FOUND"` instead of synthesizing a file ID.
+- If the file-kind entity row carries a `briefing_blocked` property (set
+  by the pre-ingest secret scanner or the unscanned-source defense-in-
+  depth path), Clarion returns `403` with
+  `code: "BRIEFING_BLOCKED"` and the response body
+  `{"error": "entity is briefing-blocked and cannot be exposed",
+  "code": "BRIEFING_BLOCKED"}`. The response does not include the
+  `entity_id`, `content_hash`, `canonical_path`, or `language` fields,
+  so Filigree must not infer file identity from a 403 envelope. Distinguish
+  this from `404 NOT_FOUND`, which means no entity row exists at all;
+  `403 BRIEFING_BLOCKED` confirms the file is known but withheld.
+
+The contract fixture at
+[`fixtures/get-api-v1-files.demo-python.json`](./fixtures/get-api-v1-files.demo-python.json)
+is normative for this section. It includes `_meta`, `shape_decl`, and examples
+for the happy path, not-known, blank path, outside-root, briefing-blocked,
+and storage-error responses.
+
+### `POST /api/v1/files:resolve`
+
+Resolves up to **1000** file paths in one request while preserving one response
+slot per input path. This is an optimization for high-volume callers that want
+single-GET semantics without one HTTP round trip per path.
+
+Request body (`application/json`, max 16 KiB):
+
+```json
+{
+  "paths": [
+    {"path": "src/foo.py", "language": "python"},
+    {"path": "src/bar.py"}
+  ]
+}
+```
+
+Successful response (`200 OK`):
+
+```json
+{
+  "results": [
+    {
+      "path": "src/foo.py",
+      "response": {
+        "status": "resolved",
+        "body": {
+          "entity_id": "core:file:src/foo.py",
+          "content_hash": "<hash>",
+          "canonical_path": "src/foo.py",
+          "language": "python"
+        }
+      }
+    },
+    {
+      "path": "src/missing.py",
+      "response": {
+        "status": "not_found",
+        "body": {
+          "error": "file is not known to Clarion",
+          "code": "NOT_FOUND"
+        }
+      }
+    }
+  ]
+}
+```
+
+Per-path `response.status` is one of:
+
+- `resolved` — `body` is the same shape as `GET /api/v1/files`.
+- `not_found` — no file-kind entity row exists.
+- `blocked` — the entity is known but `briefing_blocked`; identity fields are
+  withheld, matching the single-file `403 BRIEFING_BLOCKED` posture.
+- `error` — per-path validation or storage error; switch on `body.code`.
+
+Envelope-level failures:
+
+| Status | Code | When |
+|---|---|---|
+| 400 | `INVALID_PATH` | Body is not a valid `{"paths": [...]}` object or `paths.len() > 1000`. |
+| 401 | `UNAUTHENTICATED` | HMAC or bearer auth missing or wrong (when configured — see §Authentication). |
+| 413 | n/a | Request body exceeds the 16 KiB cap. |
+| 500/503 | `STORAGE_ERROR` / `INTERNAL` | Whole-batch storage failure. |
+
+ETag is not applied to this endpoint. `GET /api/v1/files` remains the
+canonical per-URI resolution model; `files:resolve` is a batch transport
+optimization.
+
+The contract fixture at
+[`fixtures/post-api-v1-files-resolve.batch.json`](./fixtures/post-api-v1-files-resolve.batch.json)
+is normative for this section.
+
+### `POST /api/v1/files/batch`
+
+Resolves up to **256** file paths in a single request. Filigree's
+`ClarionRegistry` uses this for cold-start hydration so that one rehydration
+costs one round-trip and one pooled-connection checkout, rather than N of each.
+
+Request body (`application/json`, max 16 KiB):
+
+```json
+{
+  "queries": [
+    {"path": "src/foo.py", "language": "python"},
+    {"path": "src/bar.py", "language": ""}
+  ]
+}
+```
+
+Successful response (`200 OK`) — every input path is partitioned into exactly
+one of four lists:
+
+```json
+{
+  "resolved": [
+    {
+      "requested_path": "src/foo.py",
+      "entity_id": "core:file:src/foo.py",
+      "content_hash": "<hash>",
+      "canonical_path": "src/foo.py",
+      "language": "python"
+    }
+  ],
+  "not_found": ["src/missing.py"],
+  "briefing_blocked": ["src/secrets.py"],
+  "errors": [
+    {
+      "requested_path": "../escapes.py",
+      "code": "PATH_OUTSIDE_PROJECT",
+      "message": "path is outside project root"
+    }
+  ]
+}
+```
+
+Semantics:
+
+- `resolved[*]` echoes the requested path back as `requested_path` so the
+  client can correlate without re-canonicalising; the rest of the fields
+  match the `GET /api/v1/files` response shape for the same input.
+- `not_found[]` and `briefing_blocked[]` are plain string arrays of the
+  requested paths — Filigree must not infer file identity from the
+  `briefing_blocked` partition (same withholding semantics as the
+  single-file `403 BRIEFING_BLOCKED`).
+- `errors[]` carries per-path resolution errors (`INVALID_PATH`,
+  `PATH_OUTSIDE_PROJECT`, `STORAGE_ERROR`, `INTERNAL`). Errors are
+  per-item, not envelope-level; the response is still `200 OK`.
+
+Failure modes (envelope-level):
+
+| Status | Code | When |
+|---|---|---|
+| 400 | `INVALID_PATH` | Body is not a valid `{"queries": [...]}` JSON object. |
+| 400 | `BATCH_TOO_LARGE` | `queries.len() > 256`. Filigree must split client-side. |
+| 401 | `UNAUTHENTICATED` | HMAC or bearer auth missing or wrong (when configured — see §Authentication). |
+| 413 | n/a | Request body exceeds the 16 KiB cap (transport-level). |
+| 500/503 | `STORAGE_ERROR` / `INTERNAL` | Whole-batch storage failure. |
+
+ETag is **not** applied to the batch endpoint; clients that want
+conditional fetch semantics should use the single-file endpoint. The whole
+batch runs inside one pooled `ReaderPool::with_reader` checkout —
+implementors must not regress this to per-query checkout, since the
+per-query model defeats the only reason the endpoint exists.
+
+The contract fixture at
+[`fixtures/post-api-v1-files-batch.json`](./fixtures/post-api-v1-files-batch.json)
+is normative for this section.
+
+### `GET /api/v1/_capabilities`
+
+Reports whether this Clarion instance can serve the registry-backend read
+contract.
+
+Successful response:
+
+```json
+{
+  "api_version": 1,
+  "instance_id": "9bd7234e-6d44-4a38-9ae4-76f912a10221",
+  "registry_backend": true,
+  "file_registry": true
+}
+```
+
+Filigree should treat `registry_backend: true` as the flag that the
+`/api/v1/files` resolution surface is present.
+
+`api_version` is the HTTP read API wire-contract version, not Clarion product
+semver. It increments only for incompatible changes to the wire contract
+consumed by existing Filigree clients.
+
+`instance_id` is the stable per-project Clarion instance fingerprint persisted
+in `.clarion/instance_id`. Filigree should treat a changed `instance_id` for a
+previously known endpoint as evidence that it is now talking to a different
+Clarion project instance.
+
+The contract fixture at
+[`fixtures/get-api-v1-capabilities.json`](./fixtures/get-api-v1-capabilities.json)
+is normative for this section. Its shape declaration pins `api_version` and
+asserts that `instance_id` is a UUID; the example uses a seeded stable ID.
+
+## Path normalization
+
+Both `GET /api/v1/files` and `POST /api/v1/files/batch` accept the same
+input-path shape:
+
+- **Lexical**, not filesystem-canonical. Path normalization joins the
+  configured project root with the requested path (or treats an absolute
+  path as-is when it falls under the project root), then folds `.` /
+  `..` lexically. The path **does not need to exist on disk** at lookup
+  time — Clarion resolves against its entity catalog
+  (`entities.source_file_path`), not against `stat(2)`. This is important
+  for replay scenarios where the catalog row outlives the file.
+- **Forward-slash separators only**. Both project-relative paths
+  (`src/foo.py`) and project-root-anchored absolute paths
+  (`/var/run/clarion-corpus/src/foo.py`) are accepted; backslash
+  separators are not.
+- **Project-relative or absolute under the project root**. A request
+  whose normalized form escapes the project root returns 400
+  `PATH_OUTSIDE_PROJECT` (single-file) or surfaces as an
+  `errors[].code = "PATH_OUTSIDE_PROJECT"` entry (batch).
+- **Symlink-resolved equivalents are not reconciled**. If your project
+  contains symlinks, both Clarion and Filigree must agree on the same
+  canonical form for the same logical file (typically the lexically-
+  joined form). Clarion does **not** call `canonicalize()` on the
+  request path; the catalog row carries the canonical form chosen at
+  ingest.
+
+Reference implementation: `clarion-storage::query::normalize_lookup_path`
+(file path: [`crates/clarion-storage/src/query.rs`](../../crates/clarion-storage/src/query.rs)).
+The function signature is stable for the lifetime of `api_version: 1`;
+the *implementation* is free to change as long as the lexical /
+no-disk-touch / forward-slash / under-root contract holds.
+
+## Wardline qualname normalization (entity reconciliation)
+
+This contract governs how a sibling that emits Findings against Python code
+(Wardline's native Filigree emitter, per ADR-018's 2026-05-29 amendment and the
+2026-05-29 integration brief §4.A) must spell the entity it references so Clarion
+can reconcile it. It is *enrich-only*: when the contract is honored, Clarion
+attaches the entity's structural context to the Finding; when it is not, Clarion
+degrades to `resolution_confidence: heuristic|none` — there is no error and no
+broken state, only a worse match. Filigree's own ticket lifecycle is unaffected
+either way (loom.md §5).
+
+**The composed form.** A Finding carries `metadata.wardline.qualname` as the
+**pre-composed** dotted name (Clarion's L7 `canonical_qualified_name`), not a
+`(file, bare-qualname)` pair. The composition is two parts:
+
+```text
+metadata.wardline.qualname = module_dotted_name(file_path) + "." + __qualname__
+```
+
+- `module_dotted_name(file_path)` is Clarion's module-prefix rule. Its canonical
+  implementation and tests are
+  [`module_dotted_name`](../../plugins/python/src/clarion_plugin_python/extractor.py)
+  and `test_module_dotted_name_helper` in
+  [`test_extractor.py`](../../plugins/python/tests/test_extractor.py). The rule:
+  strip a leading `src/` **only at position 0**; drop the `.py` suffix; collapse
+  an `__init__` filename to its package; join the rest with `.`. No other root
+  marker (`lib/`, `app/`, the project name, …) is stripped, and a top-level
+  `__init__.py` normalizes to the empty string and is **not emitted** (Clarion
+  rejects an empty qualified name).
+- `__qualname__` is copied **verbatim** — `<locals>` closure markers and dotted
+  nested-class chains are preserved, never rewritten.
+
+**Normative vectors.** The byte-exact `(file_path, qualname) → dotted form`
+parity set lives in
+[`fixtures/wardline-qualname-normalization.json`](./fixtures/wardline-qualname-normalization.json).
+It is a standalone spec vector in the same spirit as the cross-language
+`fixtures/entity_id.json`: it deliberately includes the divergence traps where
+naive composition silently mismatches (non-`src` roots, `src` not at position 0,
+`<locals>` closures, nested-class chains, namespace-package layouts, the rejected
+top-level `__init__.py`). A conformant emitter reproduces every vector exactly.
+
+**Conformance oracle (deferred).** A live check —
+`GET /api/v1/entities/resolve?scheme=wardline_qualname`, which would return
+`exact | heuristic | none` for a candidate qualname — is named in ADR-018 as the
+eventual conformance surface but is **not implemented at release:1.1**. Until it
+ships, the fixture above is the contract: validate against it offline. Building
+the endpoint ahead of a shipped Wardline consumer would be speculative
+forward-work (loom.md §5 — Clarion translates qualnames because it owns the
+catalog, but only when a consumer needs it).
+
+## Consumed Filigree route: issue detail (enrichment)
+
+The contracts above pin the surface Clarion *exposes*. This one pins the single
+Filigree route Clarion *consumes* to enrich an entity-association match — the
+read behind `issues_for`'s per-match `issue` block (clarion-51a2868c86). It is
+strictly *enrich-only*: if the route is absent or unreachable, the match still
+resolves with `issue: null`, and Clarion's semantics are unaffected (loom.md §5).
+
+```text
+GET {filigree_base}/api/loom/issues/{issue_id}
+```
+
+- `{issue_id}` is percent-encoded as a path-segment value.
+- **Request headers:** `accept: application/json`; `x-filigree-actor: <actor>`
+  when an actor is configured; `Authorization: Bearer <token>` when a bearer
+  token is configured. (HMAC is not used on this *outbound* read; it is an
+  inbound-auth mechanism on Clarion's own exposed routes.)
+- **`200` response body** — only these fields are read; **unknown fields are
+  ignored** so Filigree may grow the route without breaking the consumer:
+
+  ```json
+  { "title": "string", "status": "string", "priority": 0 }
+  ```
+
+  `priority` is an integer (Clarion's `IssueDetail.priority: i64`).
+- **`404`** — the issue, or the whole route, is absent. Treated as the enrich-only
+  degrade signal (`Ok(None)` → `issue: null`), **not** an error.
+- **Any other non-`2xx`** — surfaced as a client error; the enrichment for that
+  match degrades to `issue: null` rather than failing the `issues_for` call.
+
+There is no normative fixture for this route yet; the shape above is the
+contract. The `parse_issue_detail_response` shape test in
+[`filigree.rs`](../../crates/clarion-mcp/src/filigree.rs) is the executable
+check.
+
+## Consumed Filigree route: scan-results intake (finding emission)
+
+This pins the Filigree route Clarion *consumes* to emit findings — WP9-B,
+REQ-FINDING-03, ADR-004. `clarion analyze` Phase 8 POSTs this run's persisted
+findings on completion via
+[`FiligreeHttpClient::post_scan_results`](../../crates/clarion-mcp/src/filigree.rs).
+It is *enrich-only*: emission is gated behind
+`integrations.filigree.{enabled,emit_findings}` (both default `false`), and any
+failure — Filigree down, transport error, build error — is recorded in
+`stats.json` and logged as `CLA-INFRA-FILIGREE-UNREACHABLE`, never propagated.
+The analyze run never fails because a sibling is unreachable (loom.md §5).
+
+```text
+POST {filigree_base}/api/v1/scan-results
+```
+
+- **Request headers:** `content-type: application/json`;
+  `x-filigree-actor: <actor>` when configured; `Authorization: Bearer <token>`
+  when a bearer token is configured. (HMAC is inbound-only, on Clarion's own
+  exposed routes; this outbound POST uses bearer.)
+- **Request body** — only the keys below are sent. Filigree silently drops any
+  top-level finding key outside its enumerated set, so Clarion's richer fields
+  nest under `metadata` and the Clarion-owned `metadata.clarion.*` slot (ADR-004,
+  detailed-design §7) where verbatim preservation is verified:
+
+  ```json
+  {
+    "scan_source": "clarion",
+    "scan_run_id": "<run_id>",
+    "mark_unseen": true,
+    "create_observations": false,
+    "complete_scan_run": true,
+    "findings": [
+      {
+        "path": "src/auth/tokens.py",
+        "rule_id": "CLA-PY-STRUCTURE-001",
+        "message": "Circular import detected",
+        "severity": "medium",
+        "line_start": 12,
+        "line_end": 12,
+        "metadata": {
+          "kind": "defect",
+          "confidence": 0.95,
+          "confidence_basis": "ast_match",
+          "clarion": {
+            "entity_id": "python:class:auth.tokens::TokenManager",
+            "related_entities": ["python:class:auth.sessions::SessionStore"],
+            "supports": [],
+            "supported_by": [],
+            "internal_severity": "WARN",
+            "internal_status": "open"
+          }
+        }
+      }
+    ]
+  }
+  ```
+
+  - `scan_source` is always `"clarion"`; it is part of Filigree's dedup key, so
+    it is stable across runs.
+  - `scan_run_id` carries Clarion's `run_id`. It is omitted entirely when unset;
+    an unknown id is tolerated by Filigree (it warns and proceeds), which is how
+    REQ-FINDING-05's wire shape ships without a pre-create handshake. **Clarion's
+    posture** is to depend on this tolerate-unknown behavior and emit no Phase-0
+    `scan-runs` create call; whether that is Filigree's *intended permanent*
+    contract (vs. an explicit create endpoint) is the open §4 question in
+    [`2026-05-30-prune-unseen-filigree-request.md`](2026-05-30-prune-unseen-filigree-request.md),
+    pending Filigree's confirmation.
+  - `mark_unseen` is `true` for a normal full run (old-position findings for the
+    same rule/file transition to `unseen_in_latest`); a `--resume RUN_ID` run
+    sets it `false` so the re-emit does not flip the prior run's findings to
+    `unseen_in_latest`. `complete_scan_run` is `true` on the final (here: only)
+    batch. **`--resume` is implemented** (REQ-FINDING-05): it reopens the prior
+    run's `runs` row instead of inserting a fresh one and re-walks idempotently
+    (entities and run-scoped findings UPSERT). It re-walks the tree from scratch
+    (not incremental recovery) and assumes an unchanged corpus. Because a resume
+    emits `mark_unseen=false`, it never creates `unseen_in_latest` state, so the
+    `--prune-unseen` sweep (below) does not interact with resumes — prune is
+    meaningful only after normal `mark_unseen=true` runs. The emitted
+    `mark_unseen` value is recorded in the run's `stats.json` `filigree_emission`
+    block.
+  - `create_observations` is always `false` — Clarion emits findings, not
+    observations.
+  - `severity` is the **wire** vocabulary, mapped from Clarion's internal value:
+    `CRITICAL→critical`, `ERROR→high`, `WARN→medium`, everything else
+    (`INFO`, `NONE`, unknown) `→info`. This mirrors Filigree's own server-side
+    coercion but is done client-side so the original survives under
+    `metadata.clarion.internal_severity`.
+  - `line_start` / `line_end` are omitted when the anchor entity has no line
+    range. A finding whose anchor entity has **no `path`** is skipped (and
+    counted in `stats.json`); Filigree rejects path-less findings with
+    `400 VALIDATION`.
+  - **briefing-blocked exclusion:** findings anchored to a `briefing_blocked`
+    entity are **never emitted** (clarion-8b32ba0d02). This matches the
+    fail-closed read posture — `GET /api/v1/files` refuses the same entities —
+    so the write direction cannot leak a path/line the read direction withholds.
+
+- **`200` response body** — parsed with unknown fields ignored and missing
+  fields defaulted, so Filigree may grow the response without breaking the
+  consumer. REQ-FINDING-03 requires the emitter to **parse** `warnings`, not
+  just count them; each is logged against the run:
+
+  ```json
+  {
+    "files_created": 1,
+    "files_updated": 0,
+    "findings_created": 1,
+    "findings_updated": 0,
+    "observations_created": 0,
+    "observations_failed": 0,
+    "new_finding_ids": ["clarion-sf-2f4cf9ca1b"],
+    "warnings": ["Unknown severity 'WARN' for finding at probe/sev.py, mapped to 'info'"]
+  }
+  ```
+
+- **Any non-`2xx`** — surfaced as a transport/HTTP error, folded into the
+  `filigree_emission` stats blob and the `CLA-INFRA-FILIGREE-UNREACHABLE` log;
+  the analyze run still completes successfully.
+
+There is no normative fixture for this route yet; the shapes above are the
+contract. The `request_serializes_to_filigree_wire_shape` and
+`parses_live_response_shape` tests in
+[`scan_results.rs`](../../crates/clarion-mcp/src/scan_results.rs) — the latter
+pinned to a real captured Filigree response — are the executable checks.
+
+**Verification scope.** CI exercises the emitter against a *mock* HTTP server
+(`post_scan_results_sends_batch_and_parses_response` in
+[`filigree.rs`](../../crates/clarion-mcp/src/filigree.rs)), and the
+`analyze`-level test asserts the enrich-only degrade when Filigree is
+unreachable. The wire shapes pinned above were captured from a **one-time live
+probe** against a running Filigree intake (the source of the `severity`
+coercion rule and the response fields); there is **no recurring end-to-end test
+against a live Filigree**. A shape change on Filigree's side would be caught by
+re-probing, not by CI — re-pin `parses_live_response_shape` if the live intake
+changes.
+
+## Consumed Filigree route: clean-stale retention (`--prune-unseen`)
+
+`clarion analyze --prune-unseen` asks Filigree to run a retention sweep over its
+own findings (REQ-FINDING-06). This is a **loom-generation** route, distinct
+from the classic `/api/v1/scan-results` emission intake.
+
+```
+POST {filigree_base}/api/loom/findings/clean-stale
+```
+
+- **Headers** — `accept: application/json`, optional `x-filigree-actor` and
+  `Authorization: Bearer <token>` (same posture as scan-results; Filigree's
+  trust boundary for this route is loopback binding, not inbound auth).
+- **Request body**
+
+  ```json
+  {
+    "scan_source": "clarion",
+    "older_than_days": 30,
+    "actor": "clarion-mcp"
+  }
+  ```
+
+  - `scan_source` is **required** server-side as an accident-guard (Filigree's
+    core treats absent as "all sources", which the route refuses to expose).
+    Clarion always sends `"clarion"`, so the sweep can only touch Clarion's
+    findings — it can never affect Wardline's or any other tool's.
+  - `older_than_days` comes from `integrations.filigree.prune_unseen_days`
+    (default 30); a non-negative integer. `0` sweeps the whole current unseen
+    backlog.
+  - `actor` is Clarion's configured actor, for Filigree's audit trail.
+
+- **Semantics — soft-archive, not delete.** Filigree moves its
+  `unseen_in_latest` findings older than the threshold to `fixed` status
+  (audit-preserving); a finding that reappears in a later scan auto-reopens
+  (`fixed` → `open`) with its `seen_count` intact. Filigree owns the finding
+  lifecycle and chose this audit-preserving policy; REQ-FINDING-06's "removes"
+  is realised as soft-archive. See Filigree ADR-015.
+
+- **`200` response body** — parsed with unknown fields ignored / missing fields
+  defaulted:
+
+  ```json
+  { "findings_fixed": 4, "scan_source": "clarion", "older_than_days": 30 }
+  ```
+
+- **Enrich-only.** The sweep runs after emission (Phase 8b) for the same
+  non-hard-failed outcomes. A Filigree outage, a non-`2xx`, or the integration
+  being disabled is recorded in the `filigree_prune` stats blob (status
+  `unreachable` / `skipped`) and the `CLA-INFRA-FILIGREE-UNREACHABLE` log — the
+  analyze run still completes successfully. Prune keys on `unseen_in_latest`,
+  which only `mark_unseen=true` (normal) runs create; a `--resume`
+  (`mark_unseen=false`) run produces no unseen state for prune to sweep.
+
+**Verification scope.** Same posture as the emission intake: the wire shape is
+checked by `clean_stale_*` unit tests in
+[`scan_results.rs`](../../crates/clarion-mcp/src/scan_results.rs) and exercised
+end-to-end against a *mock* Filigree (`analyze_prune_unseen_*` in
+[`analyze.rs`](../../crates/clarion-cli/tests/analyze.rs), covering the
+post-after-emission path, the unreachable degrade, and the disabled no-op). The
+route shape was read from Filigree's own handler + API tests; there is **no
+recurring end-to-end test against a live Filigree**.
diff --git a/docs/federation/filigree-side/2026-05-19-registry-backend-cross-project-sequencing.md b/docs/federation/filigree-side/2026-05-19-registry-backend-cross-project-sequencing.md
new file mode 100644
index 00000000..e9d83554
--- /dev/null
+++ b/docs/federation/filigree-side/2026-05-19-registry-backend-cross-project-sequencing.md
@@ -0,0 +1,124 @@
+# Registry-Backend & File-Identity Displacement — Cross-Project Sequencing Memo
+
+**Status:** Draft (2026-05-19)
+**Scope:** Sequencing memo for bringing Clarion ADR-014's vision forward across Filigree and Clarion. Pairs with [Filigree ADR-014](../architecture/decisions/ADR-014-registry-backend-and-file-identity-displacement.md).
+**Sibling docs:**
+- Clarion ADR-014 (the original 2026-04-18 design)
+- Clarion ADR-029 (entity-associations, shipped 2026-05-17)
+- Clarion v0.1 plan §WP10 (the cross-product work package this memo activates)
+
+---
+
+## 1. Problem in one paragraph
+
+`loom.md` §2 says "Clarion owns the file registry." The 2.1.0 Filigree code still mints Filigree-native shadow file IDs on every `POST /api/loom/scan-results`, every `create_observation(file_path=…)`, and every `trigger_scan*`. The Clarion-side design exists (ADR-014, 2026-04-18) and was accepted; the Filigree-side counterpart was never drafted; the Clarion-side WP10 was deferred to v0.2 by the 2026-05-16 Sprint 2 amendment. ADR-029 (entity_associations, May 17) ships the *peer* primitive — issue↔entity binding — but does not close the file-identity split. This memo names what each side must do to close it.
+
+## 2. Why now
+
+- ADR-029 is the last work that *could* have substituted for ADR-014's vision. It explicitly does not.
+- Filigree's 2.1.0 release prep is mid-flight (see `2026-05-18-2.1.0-release-prep.md`); landing the schema migration alongside that release minimises the operator-visible migration count.
+- Clarion's Sprint 2 closed clean (2026-05-17 signoff); Sprint 3 is unscoped and can absorb the Clarion-side HTTP read API as its anchor work package.
+- The Loom URI spec (`2026-05-17-loom-uri-spec.md`) is in draft and depends on a coherent file-identity story across the federation. Closing the split here removes a foundational ambiguity from that spec's scope.
+
+## 3. Work, owned by project
+
+### 3.1 Clarion side (Sprint 3, anchor work)
+
+WP10 from `docs/implementation/v0.1-plan.md` was always Clarion's side of this story. Sprint 2 deferred it; this memo lifts it back into active scope. Plus one new item the original plan did not have: Clarion has no HTTP server today. The `resolve_file` surface ADR-014 assumes must be built.
+
+| ID | Title | Notes |
+|---|---|---|
+| C-WP10.1 | Clarion HTTP read API — `axum` server in `clarion-cli` | New crate-internal module; reuses `ReaderPool`. Bind on a port advertised in `clarion.yaml`. Wire into `clarion serve` alongside MCP stdio. |
+| C-WP10.2 | `GET /api/v1/files?path=&language=` endpoint | Returns `{entity_id, content_hash, canonical_path, language}`. Backed by `clarion-storage::reader` queries; pure read, no writer involvement. |
+| C-WP10.3 | Contracts directory for the read API | `docs/federation/contracts.md` on Clarion's side, parity with Filigree's. Publish a JSON fixture for `GET /api/v1/files`. |
+| C-WP10.4 | Capability probe response | `GET /api/v1/_capabilities` (or equivalent) returning `{file_registry: true, version: "0.1"}` so Filigree's `ClarionRegistry` can fail fast on incompatible deployments. |
+| C-WP10.5 | Sprint 3 scope amendment memo | Mirrors `sprint-2/scope-amendment-2026-05.md` — names the lift, the rationale (this memo), the dependency on Filigree Phase A→B landing. |
+
+Estimated cost: one Clarion sprint (~2 weeks). The dominant lift is C-WP10.1 (no HTTP machinery exists today).
+
+### 3.2 Filigree side (2.1.x or 2.2.0)
+
+Maps onto ADR-014 Phases B / C / E.
+
+| Phase | Title | Maps to ADR-014 § |
+|---|---|---|
+| F-B.1 | `RegistryProtocol` interface + `LocalRegistry` impl | §1, §3 |
+| F-B.2 | Refactor `_upsert_file_record` to consume `RegistryProtocol` | §1 |
+| F-B.3 | Refactor `register_file` (db_files, db_observations) to consume `RegistryProtocol` | §1 |
+| F-B.4 | Refactor the three `tracker.register_file` call sites in `mcp_tools/scanners.py` | §1 |
+| F-B.5 | Schema migration: add `file_records.content_hash`, `file_records.registry_backend` | §3 |
+| F-B.6 | Test suite parameterisation over `registry_backend` (default-only after B) | §1 |
+| F-C.1 | `registry_backend` config flag wiring (`.filigree.conf`, `ProjectConfig`) | §2 |
+| F-C.2 | `ClarionRegistry` implementation (reqwest-equivalent in Python) | §1 |
+| F-C.3 | Capability probe in `GET /api/files/_schema.config_flags` | §4 |
+| F-C.4 | `FILIGREE_FILE_REGISTRY_DISPLACED` error code + the three direct-mutation surfaces that emit it | §6 |
+| F-C.5 | Fail-closed startup under `clarion` mode; `--allow-local-fallback` flag | §7 |
+| F-C.6 | `filigree migrate-registry` CLI verb (dry-run, execute, rollback, manifest) | §5 |
+| F-E.1 | `docs/federation/contracts.md` update referencing Clarion's read API | §8 |
+| F-E.2 | Cross-project launch runbook | §"Sequencing" |
+
+Estimated cost: Phase B is ~1–2 weeks (mostly the refactor + tests). Phase C is ~2 weeks (config + capability + migration tool + fail-closed). Phase E is ~3 days (docs).
+
+### 3.3 Cross-project (Phase D)
+
+Integration tests run against a live Clarion read API. Owned jointly — fixtures published from Filigree, contract pinned-SHA per the pattern Clarion already uses for Filigree's entity-associations.
+
+## 4. Sequencing and the critical path
+
+```
+            Clarion Sprint 3                Filigree 2.1.x or 2.2.0
+            ────────────────                ─────────────────────────
+            C-WP10.1  axum server
+                │
+                ├──→ C-WP10.2  /api/v1/files
+                │
+                ├──→ C-WP10.4  /api/v1/_capabilities
+                │
+                └──→ C-WP10.3  contracts + fixtures
+                                                       F-B.1..6  refactor + schema
+                                                            │
+                                                            ▼
+                                                       F-C.1..6  flag, mode, error, migration
+                                                            │
+                                                            ▼
+                                       D  cross-process integration tests
+                                                            │
+                                                            ▼
+                                       E  docs + launch runbook
+```
+
+Phase B is independent of Clarion-side work and can land first (behaviour-preserving refactor + schema columns at empty defaults). Phase C cannot land usefully until C-WP10.2 ships. Phase D blocks on both.
+
+## 5. Decisions deferred
+
+- **Batched resolution.** ADR-014 §Negative names sync-RPC cost as an issue under high-throughput scans. Out of scope; revisit if a real workload hits the wall. The `RegistryProtocol` interface admits batching at a future minor version (`resolve_files(paths: list[str])`).
+- **Read-side displacement.** `GET /api/loom/files` continues to return Filigree's stored rows. Whether Clarion entity IDs should be the visible IDs in those responses (vs. left as-is, with consumers cross-referencing) is a UX decision; deferred until at least one cross-tool consumer asks.
+- **Wardline integration.** Clarion ADR-015's native Wardline→Filigree emitter is unchanged in scope. Wardline findings still flow through Clarion's SARIF translator under both backends.
+
+## 6. Risks
+
+- **Schema migration adoption.** F-B.5 ships a forward-only `ALTER TABLE` with safe defaults. Verified compatible with the 2.0.x → 2.1.x migration path. Operators with custom backup tooling that snapshots `file_records` mid-migration could see inconsistent rows; documented in the release notes.
+- **Clarion ADR-014's `--allow-local-fallback` semantics.** The fallback flag exists in case the operator's Clarion is unreachable at startup; if the flag is left on permanently, the operator silently runs in `local` mode while believing they run `clarion` mode. F-C.5 surfaces a persistent dashboard banner while the flag is active to prevent this.
+- **Sprint 3 scope contention.** Clarion's Sprint 3 has not yet been scoped; this memo proposes WP10 as the anchor. If Sprint 3 commits to something else first, F-B can still land (behaviour-preserving) and F-C waits.
+
+## 7. What lands when (target dates, not commitments)
+
+| Milestone | Target | Gates |
+|---|---|---|
+| Filigree ADR-014 ratified | 2026-05-21 | One reviewer; user sign-off on this memo first |
+| Clarion Sprint 3 scope amendment ratified | 2026-05-23 | Clarion sprint-planning meeting (author = self) |
+| F-B lands on Filigree main | 2026-06-06 | Tests green; no functional change visible to operators |
+| C-WP10.1..4 land on Clarion main | 2026-06-13 | `clarion serve` exposes HTTP read API on a configurable port |
+| F-C lands behind feature flag | 2026-06-20 | `registry_backend: clarion` works against a local Clarion |
+| Phase D integration tests green | 2026-06-27 | Cross-process CI lane in both repos |
+| Phase E docs published | 2026-06-30 | Cross-project launch runbook + contract refs |
+
+## 8. Open question for the user
+
+This memo is a strategy proposal, not a plan. Before issues are filed in either tracker, sign-off on:
+
+1. **Scope of "as initially designed."** This memo treats ADR-014 (2026-04-18) as the design of record. ADR-029 stays. The `entity_associations` table is *not* unwound — it remains the right primitive for issue↔entity binding. ADR-014 is additive over it.
+2. **Sequencing.** Filigree Phase B first (independent, behaviour-preserving) is the safer parallelisation than waiting for Clarion. If you'd rather sequence Clarion-first to validate the read-API shape against a real consumer, F-B waits.
+3. **Migration verb scope.** The `filigree migrate-registry` CLI verb is the operationally-real piece of this story. Worth a second pair of eyes (operator-facing tools land harder than refactors). If you'd rather defer the migration verb behind an explicit follow-up issue (operators stay on `local` for the first release of `clarion` mode), F-C ships smaller.
+
+On greenlight, the next two artifacts are: (a) Filigree filigree-tracker milestone + phases + steps under the existing `planning` pack, (b) Clarion filigree-tracker milestone + phases + steps mirroring WP10. Both repos already use filigree for their own work tracking; no new tracker required.
diff --git a/docs/federation/filigree-side/ADR-014-registry-backend-and-file-identity-displacement.md b/docs/federation/filigree-side/ADR-014-registry-backend-and-file-identity-displacement.md
new file mode 100644
index 00000000..ff2eb141
--- /dev/null
+++ b/docs/federation/filigree-side/ADR-014-registry-backend-and-file-identity-displacement.md
@@ -0,0 +1,227 @@
+# ADR-014: `registry_backend` Flag and File-Identity Displacement to Clarion
+
+**Status**: Accepted
+**Date**: 2026-05-19
+**Deciders**: John (project lead)
+**Context**: Closes the Filigree-side hole that Clarion ADR-014 (2026-04-18) named as a v0.1 prerequisite and that Clarion ADR-029 (2026-05-16) explicitly deferred. The work is Filigree's; the sibling decision is Clarion's.
+
+## Summary
+
+Filigree gains a pluggable `RegistryProtocol` selected by a `registry_backend` config flag with two modes:
+
+- `local` (default, unchanged behaviour) — Filigree's native UUID-derived file IDs.
+- `clarion` (opt-in, per-project) — Filigree delegates file-identity resolution to Clarion's HTTP read API; `file_records.id` stores Clarion's symbolic file-kind entity ID (`core:file:{qualified_name}` per Clarion ADR-003). Clarion supplies `content_hash` separately as drift metadata; hashes are not embedded in file IDs.
+
+A `FILIGREE_FILE_REGISTRY_DISPLACED` error code surfaces direct file-registration attempts that conflict with `clarion` mode. The `registry_backend` value is published in `GET /api/files/_schema.config_flags` for capability probing. Fail-closed startup applies only under `clarion` mode (an `--allow-local-fallback` escape exists for single-operator recovery).
+
+The new column `file_records.content_hash` stores the hash Clarion supplied at resolution time, reusing the same drift-vocabulary that ADR-029's `entity_associations.content_hash_at_attach` introduced. There is one drift signal across both surfaces.
+
+## Context
+
+### The gap ADR-029 leaves on the table
+
+ADR-029 (the entity-associations binding) is shipping and is right. It does not, however, close the file-identity split between Filigree and Clarion. Concretely, today, on the 2.1.0 branch:
+
+- `POST /api/loom/scan-results` (`dashboard_routes/files.py:401-417`) routes to `db.process_scan_results(**parsed)`.
+- `process_scan_results` (`db_files.py:857-926`) iterates findings and calls `_upsert_file_record(path=f["path"], …)` for each.
+- `_upsert_file_record` (`db_files.py:640-678`) mints a Filigree-native ID (`f"{prefix}-f-{uuid4().hex[:10]}"`) the first time it sees a path.
+- No code path consults `scan_source` (or the `metadata.clarion.*` payload) to thread Clarion's entity ID through as the `file_records.id`.
+
+The result: every Clarion-sourced scan POST mints a shadow file row whose ID is Filigree-native; an issue with an `entity_associations` row pointing at `python:function:auth.tokens::issue_token` and a `file_associations` row pointing at the file that function lives in carries **two unrelated identities for the same code**. `loom.md` §2's claim that "Clarion owns the file registry" is, today, false at the storage layer.
+
+Two further auto-create paths exhibit the same shadow-mint behaviour: `db_observations.register_file` (`db_observations.py:223`) and the three call sites of `tracker.register_file` in `mcp_tools/scanners.py` (`:657`, `:746`, `:964`).
+
+ADR-029 explicitly named this gap as out of scope and called the registry-backend work "still-scheduled." This ADR is the schedule.
+
+### Why ADR-029's approach is not a substitute
+
+ADR-029's defence — opaque-string IDs, no schema surgery, no Clarion-runtime dependency — answers the question *"how do we let Filigree issues reference Clarion entities without coupling the products?"*. It does not answer *"how do we make the file_id Filigree stores be the same identifier Clarion stores?"*. Those are different questions; ADR-029 solves the first, this ADR solves the second.
+
+### The "thrown away" history
+
+Clarion ADR-014 (2026-04-18) designed this displacement in detail: `RegistryProtocol` trait, `local`/`clarion` modes, `FILIGREE_FILE_REGISTRY_DISPLACED` error code, capability probe via `_schema.config_flags`, fail-closed startup, `--allow-local-fallback` recovery flag. The Filigree-side ADR was never drafted; the WP10 work package on the Clarion side was deferred to v0.2 by the Sprint 2 scope amendment (2026-05-16). This ADR adopts Clarion ADR-014's design near-verbatim and is the Filigree-side counterpart that closes the cross-product story.
+
+## Decision
+
+### 1. `RegistryProtocol` interface
+
+A new module `filigree.registry` defines:
+
+```python
+class RegistryProtocol(Protocol):
+    def resolve_file(
+        self,
+        path: str,
+        *,
+        language: str = "",
+        actor: str = "",
+    ) -> ResolvedFile: ...
+
+    def is_displaced(self) -> bool: ...
+
+class ResolvedFile(TypedDict):
+    file_id: str           # opaque to Filigree; semantics owned by the backend
+    content_hash: str      # opaque to Filigree; used as drift signal only
+    canonical_path: str    # backend's preferred canonical form of `path`
+    language: str          # may be empty; backend may infer
+```
+
+Two implementations:
+
+- `LocalRegistry` — current behaviour. `file_id` is `f"{prefix}-f-{uuid4().hex[:10]}"`. `content_hash` is the empty string under `local` mode (column is nullable in the schema; see §3). `is_displaced()` returns `False`.
+- `ClarionRegistry` — issues `GET {clarion_base}/api/v1/files?path=…&language=…` and returns Clarion's `{entity_id, content_hash, canonical_path, language}` reshaped into `ResolvedFile`. `is_displaced()` returns `True`. Connection failures surface as `RegistryUnavailableError` (see §6).
+
+The protocol is composed into `FiligreeDB` at construction time; the three auto-create surfaces (`_upsert_file_record`, `register_file`, `tracker.register_file`) take a `registry: RegistryProtocol` parameter instead of generating IDs inline.
+
+### 2. `registry_backend` configuration
+
+`registry_backend` is a project-scoped setting in `.filigree.conf`:
+
+```yaml
+registry_backend: local              # default
+clarion:
+  base_url: http://localhost:9111
+  timeout_seconds: 5
+  allow_local_fallback: false
+```
+
+`local` is the forever-default. Filigree-the-project, every existing Filigree dogfood, and every existing third-party Filigree deployment continue to operate without change. Clarion mode is strictly opt-in per project.
+
+### 3. Schema additions
+
+```sql
+ALTER TABLE file_records ADD COLUMN content_hash TEXT NOT NULL DEFAULT '';
+ALTER TABLE file_records ADD COLUMN registry_backend TEXT NOT NULL DEFAULT 'local';
+```
+
+Both columns survive a backend swap: a row created under `local` and re-resolved under `clarion` updates `content_hash`, `registry_backend`, and (one-time, see §5) the row's `id`.
+
+Schema version bumps; migration is forward-only and additive (no FK rewrites, no row identity churn under default `local` mode).
+
+### 4. Capability probe
+
+`GET /api/files/_schema` gains a `config_flags` block:
+
+```json
+{
+  "config_flags": {
+    "registry_backend": "local",
+    "registry_backend_features": ["local"],
+    "allow_local_fallback": false
+  }
+}
+```
+
+`registry_backend_features` enumerates what this Filigree build *can* serve (always `["local"]` after Phase B; `["local", "clarion"]` after Phase C). Clarion's startup probe reads this; absent the field, Clarion enters shadow-registry mode.
+
+### 5. ID rewrite policy under backend swap
+
+A project that flips from `local` to `clarion` mid-life will have existing `file_records` rows with Filigree-native IDs and four NOT-NULL FK consumers pointing at those IDs. The displacement story therefore needs a row-ID rewrite path:
+
+- A new CLI verb `filigree migrate-registry --to clarion [--dry-run]` issues `resolve_file` for every existing row, fetches Clarion's entity ID, and rewrites `file_records.id` and all four FK consumers (`scan_findings.file_id`, `file_associations.file_id`, `file_events.file_id`, plus the `entity_associations` table introduced in PR #42 — verified to *not* hold file IDs, only entity IDs, so untouched here) inside a single SQLite transaction.
+- Rows whose paths Clarion cannot resolve (deleted-on-disk, outside-project, etc.) are flagged in the manifest; the operator chooses delete-row or keep-as-orphan.
+- Rollback uses the same manifest in reverse.
+
+The migration is not run automatically. A capability-probe mismatch (registry says `clarion` but rows have `registry_backend = 'local'`) raises `RegistryStateMismatch` on next write and halts auto-create paths until the operator runs the migration or reverts the flag.
+
+### 6. `FILIGREE_FILE_REGISTRY_DISPLACED` error code
+
+Under `clarion` mode, the following direct-mutation paths return `FILIGREE_FILE_REGISTRY_DISPLACED`:
+
+- MCP tool `register_file`.
+- CLI verb `filigree register-file`.
+- HTTP `POST /api/files` direct-create (if/when it exists; currently not exposed).
+
+The error message includes the Clarion read URL the operator should use instead. The three auto-create paths route through `RegistryProtocol` and never raise this code — they get Clarion IDs transparently.
+
+### 7. Fail-closed startup under `clarion` mode
+
+If `registry_backend: clarion` is configured but the Clarion HTTP read API is unreachable at Filigree startup, the three auto-create paths return `503 Service Unavailable` with `RegistryUnavailableError`. Read paths (`GET /api/loom/files`, `GET /api/loom/issues/.../files`) continue to operate against stored rows.
+
+`allow_local_fallback: true` (in `.filigree.conf` or via `--allow-local-fallback`) downgrades the failure to a `WARN` and routes auto-creates through `LocalRegistry`. The flag is for single-operator recovery, not steady-state operation; the dashboard surfaces a banner while it is active.
+
+### 8. Living surface, classic surface
+
+The `registry_backend` flag affects *behaviour*, not API shape. Both classic (`/api/v1/scan-results`) and loom (`/api/loom/scan-results`) handlers continue to accept identical payloads. Under `clarion` mode, the `file_id` returned in responses is a Clarion entity ID rather than a Filigree-native ID; the *shape* is unchanged (`file_id: str`). This is a contract-level addition, not a break: ADR-002 generation freezes apply to shapes, not to ID grammars.
+
+## Alternatives Considered
+
+### Alternative 1 — Keep ADR-029 only; never close the file-identity split
+
+`entity_associations` covers the cross-product reference need for issues. Files keep Filigree-native IDs forever; `loom.md` §2's "Clarion owns the file registry" is informally downgraded to "Clarion owns the entity catalog; Filigree owns the file mapping."
+
+**Why rejected**: the downgrade is real but unstated; consumers reading `loom.md` get one story, the code does another. Either fix the code or fix the doctrine. Fixing the code is the cheaper of the two because the design already exists (Clarion ADR-014) and the surface is bounded (5–8 files; ~17 test files reference `file_id` directly).
+
+### Alternative 2 — Single mode, always-Clarion (no flag)
+
+Drop `local`; always delegate. Filigree without Clarion fails to start.
+
+**Why rejected**: violates `loom.md` §4 composition law and §5 enrichment failure test. Filigree-the-project (which uses Filigree to track its own work) would require Clarion to operate, which is absurd. The flag is the price of staying federated.
+
+### Alternative 3 — Generalize `entity_associations` to carry file IDs too
+
+Add an `association_kind: 'file' | 'entity'` discriminator to `entity_associations`; let files ride.
+
+**Why rejected**: same reason ADR-029 rejected merging file_associations and entity_associations — overloading. `file_records.id` is referenced by four NOT-NULL FKs; routing those references through a discriminated union would touch more code than the `RegistryProtocol` refactor and would leave `file_records.id` itself still shadowed.
+
+### Alternative 4 — Schema-level join across two DBs (Filigree + Clarion)
+
+`file_records.id` becomes a foreign key into `.clarion/clarion.db`.
+
+**Why rejected**: `loom.md` §6 — no shared store. Each product owns its storage. The HTTP-mediated `RegistryProtocol` is the federation axiom expressed as code.
+
+## Consequences
+
+### Positive
+
+- `loom.md` §2 "Clarion owns the file registry" becomes honest at the storage layer.
+- Cross-tool "same file" queries get a deterministic answer: same ID across products under `clarion` mode.
+- Reuses ADR-029's drift vocabulary (`content_hash`); one mental model for both file-level and entity-level drift.
+- `local` stays default; no impact on Filigree-only deployments.
+
+### Negative
+
+- Two code paths per auto-create operation. Test surface doubles for file-registry behaviour (parameterise the test suite over `registry_backend ∈ {local, clarion}`).
+- One synchronous RPC hop per Filigree write that touches `file_records` under `clarion` mode. Loopback HTTP cost ~1–5ms; acceptable for developer workloads, would need batched resolution for high-throughput scans (Phase E candidate).
+- Cross-product launch sequencing: under `clarion` mode the operator must start Clarion's HTTP read API before Filigree, or set `--allow-local-fallback` for recovery.
+- The `migrate-registry` CLI verb is a one-way operation in practice (rollback only works inside the reversibility window). Documented as a hard boundary.
+
+### Neutral
+
+- Classic and loom HTTP shapes unchanged. ADR-002 generation discipline applies to shape, not ID grammar; `clarion` mode's swap of ID grammar is contract-compatible.
+- `entity_associations.clarion_entity_id` is still opaque to Filigree under `clarion` mode — the two surfaces remain independent. The same Clarion entity ID may appear in both `file_records.id` (for the file the entity lives in) and `entity_associations.clarion_entity_id` (for the entity itself, e.g. a function inside that file); the relationship between them is Clarion's domain, not Filigree's.
+
+## Sequencing (cross-project)
+
+The work has a fixed one-way dependency: Filigree's `clarion` mode is a no-op until Clarion ships an HTTP read API.
+
+| Phase | Owner | Scope |
+|---|---|---|
+| **A** | Clarion | Add an `axum`-based HTTP read server to `clarion-cli/src/serve.rs`. Expose `GET /api/v1/files?path=&language=` returning `{entity_id, content_hash, canonical_path, language}`. Wire into `clarion serve`. Surface in `clarion.yaml`. Document in Clarion's contracts directory. |
+| **B** | Filigree | Land `RegistryProtocol` interface and `LocalRegistry`; refactor `_upsert_file_record`, `register_file`, and the three `tracker.register_file` call sites to consume the protocol. Behavior-preserving — no flag yet, default-only. Schema migration adds `content_hash` and `registry_backend` columns (empty values under `local`). |
+| **C** | Filigree | Add `registry_backend` config flag, `ClarionRegistry` impl, capability probe (`_schema.config_flags`), `FILIGREE_FILE_REGISTRY_DISPLACED` error code, fail-closed startup, `--allow-local-fallback` escape, the `migrate-registry` CLI verb. |
+| **D** | Both | Cross-process integration tests against a live Clarion read API. Parity tests parameterised over `registry_backend ∈ {local, clarion}`. Capability-probe handshake tests. |
+| **E** | Both | Documentation: Filigree `docs/federation/contracts.md` references the Clarion read surface; Clarion's `loom.md` §2 claim is restated as factual rather than aspirational; cross-project launch runbook published. |
+
+Phase A must ship before Phase C can land an integration that does anything observable; B is independent and can ship first behind a flagless refactor.
+
+## Related Decisions
+
+- **ADR-002** (this repo) — `registry_backend` is *behaviour*, not a generation. Loom/classic HTTP shapes are unchanged; this ADR is contract-compatible by construction.
+- **ADR-029 of Clarion** — entity_associations is the peer concept; this ADR closes the file-side of the same split. Same drift vocabulary (`content_hash`).
+- **ADR-014 of Clarion** — original 2026-04-18 design; this ADR is its Filigree-side counterpart and adopts the design near-verbatim.
+- **ADR-015 of Clarion** — Wardline→Filigree native emitter; not in scope here. Wardline's findings continue to flow via Clarion's SARIF translator under both backends.
+- **Loom URI spec (draft 2026-05-17)** — orthogonal; URIs and registry-backend are independent decisions. Not yet ratified; not used as a cross-tracker reference primitive in this ADR.
+
+## References
+
+- Clarion ADR-014: `/home/john/clarion/docs/clarion/adr/ADR-014-filigree-registry-backend.md`.
+- Clarion ADR-029: `/home/john/clarion/docs/clarion/adr/ADR-029-entity-associations-binding.md`.
+- Clarion v0.1 plan §WP10: `/home/john/clarion/docs/implementation/v0.1-plan.md` (the cross-product work package this ADR fulfils).
+- Sprint 2 scope amendment (defer): `/home/john/clarion/docs/implementation/sprint-2/scope-amendment-2026-05.md`.
+- Clarion integration recon: `/home/john/clarion/docs/clarion/1.0/reviews/pre-restructure/integration-recon.md` (auto-create paths and FK survey).
+- Filigree auto-create paths (verified 2026-05-19):
+  - `src/filigree/db_files.py:640` `_upsert_file_record`
+  - `src/filigree/db_files.py:184` `register_file`
+  - `src/filigree/db_observations.py:223` `register_file`
+  - `src/filigree/mcp_tools/scanners.py:657,:746,:964` `tracker.register_file`
diff --git a/docs/federation/filigree-side/README.md b/docs/federation/filigree-side/README.md
new file mode 100644
index 00000000..a13ca6cb
--- /dev/null
+++ b/docs/federation/filigree-side/README.md
@@ -0,0 +1,9 @@
+# Filigree-Side Federation Context
+
+This directory mirrors Filigree-authored planning artifacts for Clarion's local
+cross-reference while Sprint 3 scopes WP10.
+
+These files are read-only context copies. The authoritative sources live in
+`/home/john/filigree`; update them there, then refresh this mirror if Clarion
+needs a newer snapshot.
+
diff --git a/docs/federation/fixtures/get-api-v1-capabilities.json b/docs/federation/fixtures/get-api-v1-capabilities.json
new file mode 100644
index 00000000..02bdbaf4
--- /dev/null
+++ b/docs/federation/fixtures/get-api-v1-capabilities.json
@@ -0,0 +1,62 @@
+{
+  "_meta": {
+    "contract": "clarion-http-read-api",
+    "endpoint": "GET /api/v1/_capabilities",
+    "api_version": 1,
+    "fixture_version": 2,
+    "stability": "normative",
+    "authority": "Clarion ADR-014 federation registry-backend contract",
+    "verification": "cargo test -p clarion-cli --test serve",
+    "normative": true,
+    "updated": "2026-05-19",
+    "description": "Contract example for Clarion registry-backend capability discovery."
+  },
+  "shape_decl": {
+    "kind": "clarion-http-fixture-shapes",
+    "shapes": {
+      "capabilities_response": {
+        "status": 200,
+        "required_fields": {
+          "registry_backend": {
+            "type": "boolean",
+            "const": true
+          },
+          "file_registry": {
+            "type": "boolean",
+            "const": true
+          },
+          "api_version": {
+            "type": "integer",
+            "const": 1
+          },
+          "instance_id": {
+            "type": "uuid"
+          }
+        },
+        "forbidden_fields": [
+          "version"
+        ],
+        "allow_extra_fields": false
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "capabilities_200",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/_capabilities"
+      },
+      "response": {
+        "status": 200,
+        "shape": "capabilities_response",
+        "body": {
+          "registry_backend": true,
+          "file_registry": true,
+          "api_version": 1,
+          "instance_id": "9bd7234e-6d44-4a38-9ae4-76f912a10221"
+        }
+      }
+    }
+  ]
+}
diff --git a/docs/federation/fixtures/get-api-v1-files.demo-python.json b/docs/federation/fixtures/get-api-v1-files.demo-python.json
new file mode 100644
index 00000000..3e40b41c
--- /dev/null
+++ b/docs/federation/fixtures/get-api-v1-files.demo-python.json
@@ -0,0 +1,169 @@
+{
+  "_meta": {
+    "contract": "clarion-http-read-api",
+    "endpoint": "GET /api/v1/files",
+    "api_version": 1,
+    "fixture_version": 3,
+    "stability": "normative",
+    "authority": "Clarion ADR-014 federation registry-backend contract",
+    "verification": "cargo test -p clarion-cli --test serve",
+    "normative": true,
+    "updated": "2026-05-19",
+    "description": "Contract examples for Clarion file identity resolution consumed by Filigree registry backends."
+  },
+  "shape_decl": {
+    "kind": "clarion-http-fixture-shapes",
+    "shapes": {
+      "file_resolution": {
+        "status": 200,
+        "required_fields": {
+          "entity_id": {
+            "type": "adr003_file_entity_id"
+          },
+          "content_hash": {
+            "type": "non_empty_string"
+          },
+          "canonical_path": {
+            "type": "project_relative_path"
+          },
+          "language": {
+            "type": "non_empty_string"
+          }
+        },
+        "forbidden_fields": [
+          "error",
+          "code"
+        ],
+        "allow_extra_fields": false
+      },
+      "error_envelope": {
+        "status_any": [
+          400,
+          401,
+          403,
+          404,
+          500,
+          503
+        ],
+        "required_fields": {
+          "error": {
+            "type": "non_empty_string"
+          },
+          "code": {
+            "type": "non_empty_string",
+            "enum": [
+              "INVALID_PATH",
+              "PATH_OUTSIDE_PROJECT",
+              "NOT_FOUND",
+              "BRIEFING_BLOCKED",
+              "UNAUTHENTICATED",
+              "STORAGE_ERROR",
+              "INTERNAL"
+            ]
+          }
+        },
+        "forbidden_fields": [
+          "entity_id",
+          "content_hash",
+          "canonical_path",
+          "language"
+        ],
+        "allow_extra_fields": false
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "happy_path_200",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/files?path=demo.py&language=python"
+      },
+      "response": {
+        "status": 200,
+        "shape": "file_resolution",
+        "body": {
+          "entity_id": "core:file:demo.py",
+          "content_hash": "hash-demo-file",
+          "canonical_path": "demo.py",
+          "language": "python"
+        }
+      }
+    },
+    {
+      "name": "not_known_404",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/files?path=missing.py&language=python"
+      },
+      "response": {
+        "status": 404,
+        "shape": "error_envelope",
+        "body": {
+          "error": "file is not known to Clarion",
+          "code": "NOT_FOUND"
+        }
+      }
+    },
+    {
+      "name": "blank_path_400",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/files?path=&language=python"
+      },
+      "response": {
+        "status": 400,
+        "shape": "error_envelope",
+        "body": {
+          "error": "path query parameter must not be blank",
+          "code": "INVALID_PATH"
+        }
+      }
+    },
+    {
+      "name": "outside_root_400",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/files?path=../outside.py&language=python"
+      },
+      "response": {
+        "status": 400,
+        "shape": "error_envelope",
+        "body": {
+          "error": "path is outside project root",
+          "code": "PATH_OUTSIDE_PROJECT"
+        }
+      }
+    },
+    {
+      "name": "briefing_blocked_403",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/files?path=blocked.py&language=python"
+      },
+      "response": {
+        "status": 403,
+        "shape": "error_envelope",
+        "body": {
+          "error": "entity is briefing-blocked and cannot be exposed",
+          "code": "BRIEFING_BLOCKED"
+        }
+      }
+    },
+    {
+      "name": "storage_error_500",
+      "request": {
+        "method": "GET",
+        "path": "/api/v1/files?path=missing-on-disk.py&language=python"
+      },
+      "response": {
+        "status": 500,
+        "shape": "error_envelope",
+        "body": {
+          "error": "file lookup failed",
+          "code": "STORAGE_ERROR"
+        }
+      }
+    }
+  ]
+}
diff --git a/docs/federation/fixtures/post-api-v1-files-batch.json b/docs/federation/fixtures/post-api-v1-files-batch.json
new file mode 100644
index 00000000..273f66f3
--- /dev/null
+++ b/docs/federation/fixtures/post-api-v1-files-batch.json
@@ -0,0 +1,147 @@
+{
+  "_meta": {
+    "contract": "clarion-http-read-api",
+    "endpoint": "POST /api/v1/files/batch",
+    "api_version": 1,
+    "fixture_version": 1,
+    "stability": "normative",
+    "authority": "Clarion ADR-014 federation registry-backend contract (CONTRACT-1)",
+    "verification": "cargo test -p clarion-cli --test serve",
+    "normative": true,
+    "updated": "2026-05-19",
+    "description": "Contract examples for Clarion bulk file identity resolution consumed by Filigree registry backends. The batch endpoint runs all lookups inside a single ReaderPool checkout; ETag is intentionally not applied; auth (CONTRACT-2) applies."
+  },
+  "shape_decl": {
+    "kind": "clarion-http-fixture-shapes",
+    "shapes": {
+      "batch_resolution": {
+        "status": 200,
+        "required_fields": {
+          "resolved": {
+            "type": "array_of_resolved_items"
+          },
+          "not_found": {
+            "type": "array_of_strings"
+          },
+          "briefing_blocked": {
+            "type": "array_of_strings"
+          },
+          "errors": {
+            "type": "array_of_error_items"
+          }
+        },
+        "forbidden_fields": [
+          "error",
+          "code"
+        ],
+        "allow_extra_fields": false
+      },
+      "batch_envelope_error": {
+        "status_any": [
+          400,
+          401,
+          500,
+          503
+        ],
+        "required_fields": {
+          "error": {
+            "type": "non_empty_string"
+          },
+          "code": {
+            "type": "non_empty_string",
+            "enum": [
+              "INVALID_PATH",
+              "BATCH_TOO_LARGE",
+              "UNAUTHENTICATED",
+              "STORAGE_ERROR",
+              "INTERNAL"
+            ]
+          }
+        },
+        "forbidden_fields": [
+          "resolved",
+          "not_found",
+          "briefing_blocked",
+          "errors"
+        ],
+        "allow_extra_fields": false
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "batch_mixed_200",
+      "request": {
+        "method": "POST",
+        "path": "/api/v1/files/batch",
+        "body": {
+          "queries": [
+            {"path": "demo.py", "language": "python"},
+            {"path": "missing.py", "language": ""},
+            {"path": "blocked.py", "language": "python"},
+            {"path": "../escapes.py", "language": "python"}
+          ]
+        }
+      },
+      "response": {
+        "status": 200,
+        "shape": "batch_resolution",
+        "body": {
+          "resolved": [
+            {
+              "requested_path": "demo.py",
+              "entity_id": "core:file:demo.py",
+              "content_hash": "hash-demo-file",
+              "canonical_path": "demo.py",
+              "language": "python"
+            }
+          ],
+          "not_found": ["missing.py"],
+          "briefing_blocked": ["blocked.py"],
+          "errors": [
+            {
+              "requested_path": "../escapes.py",
+              "code": "PATH_OUTSIDE_PROJECT",
+              "message": "path is outside project root"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "name": "batch_too_large_400",
+      "request": {
+        "method": "POST",
+        "path": "/api/v1/files/batch",
+        "body": "elided — request carries more than 256 entries in queries[]"
+      },
+      "response": {
+        "status": 400,
+        "shape": "batch_envelope_error",
+        "body": {
+          "error": "queries[] exceeds the per-batch maximum of 256 entries",
+          "code": "BATCH_TOO_LARGE"
+        }
+      }
+    },
+    {
+      "name": "batch_unauthorized_401",
+      "request": {
+        "method": "POST",
+        "path": "/api/v1/files/batch",
+        "body": {
+          "queries": [{"path": "demo.py", "language": "python"}]
+        },
+        "note": "Identity header missing or wrong; applies when serve.http.identity_token_env resolves at startup. Legacy bearer mode has the same error envelope."
+      },
+      "response": {
+        "status": 401,
+        "shape": "batch_envelope_error",
+        "body": {
+          "error": "authentication required",
+          "code": "UNAUTHENTICATED"
+        }
+      }
+    }
+  ]
+}
diff --git a/docs/federation/fixtures/post-api-v1-files-resolve.batch.json b/docs/federation/fixtures/post-api-v1-files-resolve.batch.json
new file mode 100644
index 00000000..b4cbfb0f
--- /dev/null
+++ b/docs/federation/fixtures/post-api-v1-files-resolve.batch.json
@@ -0,0 +1,110 @@
+{
+  "_meta": {
+    "contract": "clarion-http-read-api",
+    "endpoint": "POST /api/v1/files:resolve",
+    "api_version": 1,
+    "fixture_version": 1,
+    "stability": "normative",
+    "authority": "Clarion ADR-014 federation registry-backend contract",
+    "verification": "cargo test -p clarion-cli --test serve",
+    "normative": true,
+    "updated": "2026-05-20",
+    "description": "Contract example for per-path batch file identity resolution. The endpoint preserves input order and returns one status/body pair per requested path."
+  },
+  "shape_decl": {
+    "kind": "clarion-http-fixture-shapes",
+    "shapes": {
+      "resolve_batch": {
+        "status": 200,
+        "required_fields": {
+          "results": {
+            "type": "array"
+          }
+        },
+        "forbidden_fields": [
+          "error",
+          "code"
+        ],
+        "allow_extra_fields": false
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "mixed_paths_200",
+      "request": {
+        "method": "POST",
+        "path": "/api/v1/files:resolve",
+        "body": {
+          "paths": [
+            {
+              "path": "demo.py",
+              "language": "python"
+            },
+            {
+              "path": "missing.py"
+            },
+            {
+              "path": "blocked.py",
+              "language": "python"
+            },
+            {
+              "path": "../escapes.py",
+              "language": "python"
+            }
+          ]
+        }
+      },
+      "response": {
+        "status": 200,
+        "shape": "resolve_batch",
+        "body": {
+          "results": [
+            {
+              "path": "demo.py",
+              "response": {
+                "status": "resolved",
+                "body": {
+                  "entity_id": "core:file:demo.py",
+                  "content_hash": "hash-demo-file",
+                  "canonical_path": "demo.py",
+                  "language": "python"
+                }
+              }
+            },
+            {
+              "path": "missing.py",
+              "response": {
+                "status": "not_found",
+                "body": {
+                  "error": "file is not known to Clarion",
+                  "code": "NOT_FOUND"
+                }
+              }
+            },
+            {
+              "path": "blocked.py",
+              "response": {
+                "status": "blocked",
+                "body": {
+                  "error": "entity is briefing-blocked and cannot be exposed",
+                  "code": "BRIEFING_BLOCKED"
+                }
+              }
+            },
+            {
+              "path": "../escapes.py",
+              "response": {
+                "status": "error",
+                "body": {
+                  "error": "path is outside project root",
+                  "code": "PATH_OUTSIDE_PROJECT"
+                }
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
diff --git a/docs/federation/fixtures/wardline-qualname-normalization.json b/docs/federation/fixtures/wardline-qualname-normalization.json
new file mode 100644
index 00000000..2c50a6af
--- /dev/null
+++ b/docs/federation/fixtures/wardline-qualname-normalization.json
@@ -0,0 +1,144 @@
+{
+  "$comment": [
+    "Normative parity fixture for the Wardline -> Clarion entity-reconciliation",
+    "contract (ADR-018 2026-05-29 amendment, integration brief §4.A).",
+    "Wardline's native Filigree emitter sets metadata.wardline.qualname to the",
+    "PRE-COMPOSED dotted form so it byte-matches Clarion's canonical_qualified_name.",
+    "Each vector below is a (file_path, qualname) input and the exact dotted form",
+    "Wardline must emit. Divergence on any vector silently degrades reconciliation",
+    "to resolution_confidence: heuristic|none — there is no error, only a worse match.",
+    "This file is the STANDALONE spec vector; the live conformance oracle",
+    "(GET /api/v1/entities/resolve?scheme=wardline_qualname) is DEFERRED and not",
+    "implemented as of release:1.1. Mirrors the role of fixtures/entity_id.json."
+  ],
+  "rules_source": {
+    "module_normalization_fn": "plugins/python/src/clarion_plugin_python/extractor.py::module_dotted_name",
+    "module_normalization_tests": "plugins/python/tests/test_extractor.py::test_module_dotted_name_helper",
+    "composition": "expected_qualified_name = module_dotted_name(file_path) + '.' + qualname  (qualname is Python __qualname__, copied verbatim incl. '<locals>' and dotted class chains)",
+    "module_rules": [
+      "A leading 'src/' segment is stripped ONLY when it is the first path segment (UQ-WP3-05).",
+      "The '.py' suffix is dropped.",
+      "An '__init__' filename collapses to its containing package (UQ-WP3-06).",
+      "Remaining path separators become '.'.",
+      "No other root marker (lib/, app/, tests/, the project name, ...) is stripped.",
+      "A top-level '__init__.py' normalizes to '' and is REJECTED by entity_id() — Clarion skips the file; Wardline must not emit such an entity."
+    ],
+    "conformance_oracle": "GET /api/v1/entities/resolve?scheme=wardline_qualname (DEFERRED; not implemented at release:1.1)"
+  },
+  "module_normalization_vectors": [
+    {
+      "description": "src/-rooted module path",
+      "file_path": "src/auth/tokens.py",
+      "expected_module": "auth.tokens"
+    },
+    {
+      "description": "flat (non-src) layout — same file, no src/ prefix",
+      "file_path": "auth/tokens.py",
+      "expected_module": "auth.tokens"
+    },
+    {
+      "description": "package __init__ under src/ collapses to the package",
+      "file_path": "src/pkg/__init__.py",
+      "expected_module": "pkg"
+    },
+    {
+      "description": "package __init__ without src/ collapses to the package",
+      "file_path": "pkg/__init__.py",
+      "expected_module": "pkg"
+    },
+    {
+      "description": "nested module under src/",
+      "file_path": "src/pkg/sub/mod.py",
+      "expected_module": "pkg.sub.mod"
+    },
+    {
+      "description": "DIVERGENCE TRAP: non-src root 'lib/' is NOT stripped",
+      "file_path": "lib/foo.py",
+      "expected_module": "lib.foo",
+      "note": "An emitter that strips a generic 'source root' marker would wrongly produce 'foo'. Only a leading 'src/' is stripped."
+    },
+    {
+      "description": "DIVERGENCE TRAP: non-src root 'app/' is NOT stripped",
+      "file_path": "app/service.py",
+      "expected_module": "app.service"
+    },
+    {
+      "description": "DIVERGENCE TRAP: 'src' not at position 0 is NOT stripped",
+      "file_path": "a/src/b.py",
+      "expected_module": "a.src.b"
+    },
+    {
+      "description": "flat root-level module",
+      "file_path": "service.py",
+      "expected_module": "service"
+    },
+    {
+      "description": "namespace-package-style layout (no src/, implicit namespace dirs)",
+      "file_path": "myns/pkg/mod.py",
+      "expected_module": "myns.pkg.mod"
+    },
+    {
+      "description": "REJECTED: top-level __init__.py normalizes to empty and is skipped",
+      "file_path": "__init__.py",
+      "expected_module": "",
+      "note": "entity_id() rejects an empty qualified_name (crates/clarion-core/src/entity_id.rs). Clarion emits no entity for this file; a conformant Wardline emitter must not emit one either."
+    },
+    {
+      "description": "REJECTED: src/__init__.py normalizes to empty after src-strip",
+      "file_path": "src/__init__.py",
+      "expected_module": "",
+      "note": "Same as above — no package name survives."
+    }
+  ],
+  "qualified_name_vectors": [
+    {
+      "description": "class method",
+      "kind": "function",
+      "file_path": "src/auth/tokens.py",
+      "qualname": "TokenManager.verify",
+      "expected_qualified_name": "auth.tokens.TokenManager.verify",
+      "expected_entity_id": "python:function:auth.tokens.TokenManager.verify"
+    },
+    {
+      "description": "DIVERGENCE TRAP: closure carries Python '<locals>' marker verbatim",
+      "kind": "function",
+      "file_path": "src/auth/tokens.py",
+      "qualname": "refresh.<locals>.helper",
+      "expected_qualified_name": "auth.tokens.refresh.<locals>.helper",
+      "expected_entity_id": "python:function:auth.tokens.refresh.<locals>.helper",
+      "note": "The '<locals>' segment is part of __qualname__ and must be preserved, not stripped or rewritten."
+    },
+    {
+      "description": "DIVERGENCE TRAP: nested-class chain preserved verbatim",
+      "kind": "function",
+      "file_path": "src/pkg/sub/mod.py",
+      "qualname": "Outer.Inner.method",
+      "expected_qualified_name": "pkg.sub.mod.Outer.Inner.method",
+      "expected_entity_id": "python:function:pkg.sub.mod.Outer.Inner.method"
+    },
+    {
+      "description": "DIVERGENCE TRAP: non-src root preserved in the module prefix of a method",
+      "kind": "function",
+      "file_path": "lib/foo.py",
+      "qualname": "Service.handle",
+      "expected_qualified_name": "lib.foo.Service.handle",
+      "expected_entity_id": "python:function:lib.foo.Service.handle"
+    },
+    {
+      "description": "namespace-package module prefix on a top-level function",
+      "kind": "function",
+      "file_path": "myns/pkg/mod.py",
+      "qualname": "widget",
+      "expected_qualified_name": "myns.pkg.mod.widget",
+      "expected_entity_id": "python:function:myns.pkg.mod.widget"
+    },
+    {
+      "description": "module entity — no qualname; the module dotted name IS the qualified_name",
+      "kind": "module",
+      "file_path": "src/pkg/__init__.py",
+      "qualname": null,
+      "expected_qualified_name": "pkg",
+      "expected_entity_id": "python:module:pkg"
+    }
+  ]
+}
diff --git a/docs/implementation/README.md b/docs/implementation/README.md
index 754b030a..5963899e 100644
--- a/docs/implementation/README.md
+++ b/docs/implementation/README.md
@@ -1,29 +1,32 @@
-# Implementation Plans
+# Implementation Archive
 
-This folder is the canonical home for Clarion implementation planning at the work-package
-level. It sits one level above any product-version docset because some work packages
-(WP9, WP10) span Clarion **and** sibling Loom products (Filigree, Wardline) and therefore
-do not belong inside `docs/clarion/v0.1/`.
+This folder is the consolidated archive of Clarion's implementation and planning history. It is **not** part of the release-facing doc surface — readers entering via [`docs/README.md`](../README.md) and the [Clarion v0.1 docset](../clarion/v0.1/README.md) are not expected to need anything here.
 
-## Contents
+Material is kept rather than deleted because the [ADRs](../clarion/adr/README.md) cite it for historical context (panel reviews, the v0.1 scope-commitment memo, sprint plans, and agent handoffs that motivated specific decisions).
 
-- [v0.1-plan.md](./v0.1-plan.md) — high-level implementation plan for Clarion v0.1: 11
-  work packages, dependency order, anchoring docs/ADRs per package, exit criteria, and
-  the post-implementation cost-model validation phase.
+## Layout
 
-## Relationship to other docs
+| Path | Contents |
+|---|---|
+| [v0.1-plan.md](./v0.1-plan.md) | High-level implementation plan: 11 work packages in dependency order, with anchoring docs/ADRs, exit criteria, and post-implementation cost-model validation. |
+| [v0.1-scope-plans/](./v0.1-scope-plans/) | The v0.1 scope-commitment memo — *what* v0.1 ships, decision priorities, locked-in defaults. Cited by several ADRs. |
+| [v0.1-reviews/](./v0.1-reviews/) | Pre-restructure design review, integration reconnaissance, and the April 2026 review-panel outputs (executive synthesis, self-sufficiency, threat model, doctrine synthesis). |
+| [v0.1-publish/](./v0.1-publish/) | v1.0 publish-track work-stream plans (secret-scanner WS-A, pre-publish blockers). |
+| [sprint-1/](./sprint-1/) | Sprint 1 (walking skeleton): WP1+WP2+WP3 execution plans and sign-off ladder. |
+| [sprint-2/](./sprint-2/) | Sprint 2 (B-track): B.2–B.6 execution plans, gate results, B.8 scale test, openrouter swap, scope amendment, sign-offs. |
+| [sprint-3/](./sprint-3/) | Sprint 3 scope amendment. |
+| [handoffs/](./handoffs/) | Dated agent-to-agent handoff notes (formerly `docs/superpowers/handoffs/`). |
+| [agent-plans/](./agent-plans/) | TDD-grain plan files used by individual agent runs (formerly `docs/superpowers/plans/`). |
+| [arch-analysis-2026-05-20-2124/](./arch-analysis-2026-05-20-2124/) | RC1 root-and-branch architecture archaeology output: discovery findings, subsystem catalogue, diagrams, final report, quality/security/release/test/dependency analysis, and architect handoff. |
 
-- **Scope and commitments**: [`../clarion/v0.1/plans/v0.1-scope-commitments.md`](../clarion/v0.1/plans/v0.1-scope-commitments.md).
-  That memo locks *what* v0.1 ships; this plan describes *how* the build proceeds.
-- **Authoritative design**: [`../clarion/v0.1/system-design.md`](../clarion/v0.1/system-design.md)
-  and [`../clarion/v0.1/detailed-design.md`](../clarion/v0.1/detailed-design.md).
-  Each work package below names the sections it implements.
-- **Decisions**: [`../clarion/adr/README.md`](../clarion/adr/README.md). Each work package
-  names the accepted ADRs it depends on and any backlog ADRs it is expected to surface.
+## Relationship to release-facing docs
 
-## Out of scope for this folder
+- **Authoritative design**: [`../clarion/v0.1/system-design.md`](../clarion/v0.1/system-design.md) and [`../clarion/v0.1/detailed-design.md`](../clarion/v0.1/detailed-design.md). Each work package under this folder names the sections it implements.
+- **Decisions**: [`../clarion/adr/README.md`](../clarion/adr/README.md). Each work package names the accepted ADRs it depends on and any backlog ADRs it is expected to surface.
+- **Scope and commitments**: [`v0.1-scope-plans/v0.1-scope-commitments.md`](./v0.1-scope-plans/v0.1-scope-commitments.md). That memo locks *what* v0.1 ships; the work-package plans describe *how* the build proceeds.
 
-- Step-by-step task breakdowns (TDD-grain). Those belong in per-WP execution plans
-  written when each package is picked up — not bundled into the high-level plan.
-- Filigree issue records. The work-package list here is the source for seeding Filigree
-  issues, but the issue tracker (not this doc) is the authoritative state-of-work.
+## Conventions
+
+- Documents under this folder are **immutable historical record**, not living plans. Update them only to correct factual errors or to repair a citation; do not retrofit narrative to match later decisions.
+- Filigree (not these files) is the authoritative state-of-work tracker. Work-package plans seeded the issue list; the tracker is canonical thereafter.
+- TDD-grain task breakdowns belonged in per-run agent plans (now under [agent-plans/](./agent-plans/)) and in Filigree, not in the high-level work-package documents.
diff --git a/docs/superpowers/plans/2026-04-18-wp1-scaffold-storage.md b/docs/implementation/agent-plans/2026-04-18-wp1-scaffold-storage.md
similarity index 99%
rename from docs/superpowers/plans/2026-04-18-wp1-scaffold-storage.md
rename to docs/implementation/agent-plans/2026-04-18-wp1-scaffold-storage.md
index eb2819c6..aa63f1d7 100644
--- a/docs/superpowers/plans/2026-04-18-wp1-scaffold-storage.md
+++ b/docs/implementation/agent-plans/2026-04-18-wp1-scaffold-storage.md
@@ -710,7 +710,7 @@ Write `/home/john/clarion/crates/clarion-storage/migrations/0001_initial_schema.
 -- ============================================================================
 -- Clarion migration 0001 — initial schema.
 --
--- Source: docs/clarion/v0.1/detailed-design.md §3 (Storage Implementation).
+-- Source: docs/clarion/1.0/detailed-design.md §3 (Storage Implementation).
 -- Sprint 1 walking skeleton writes only to `entities` and `runs`, but every
 -- table, FTS5 virtual table, trigger, generated column, index, and view
 -- is created here so the full shape is frozen at L1-lock time. See ADR-011
@@ -1612,7 +1612,7 @@ const CONFIG_JSON_STUB: &str = r#"{
 "#;
 
 const CLARION_YAML_STUB: &str = "# clarion.yaml — user-edited config.\n\
-# Full schema TBD; see docs/clarion/v0.1 design. Sprint 1 walking skeleton\n\
+# Full schema TBD; see docs/clarion/1.0 design. Sprint 1 walking skeleton\n\
 # ignores most fields. Do not delete this file: later versions will require\n\
 # it for model-tier mappings and analysis knobs.\n\
 version: 1\n";
@@ -1998,9 +1998,9 @@ path works; LFS is a v0.2+ knob.
 
 ## Related Decisions
 
-- [ADR-011](./ADR-011-writer-actor-concurrency.md) — names the shadow-DB
+- [ADR-011](../../clarion/adr/ADR-011-writer-actor-concurrency.md) — names the shadow-DB
   intermediate; this ADR excludes it from git.
-- [ADR-014](./ADR-014-filigree-registry-backend.md) — cross-tool references
+- [ADR-014](../../clarion/adr/ADR-014-filigree-registry-backend.md) — cross-tool references
   rely on `clarion.db` being available to readers (Filigree, Wardline); the
   commit-by-default posture keeps those references resolvable across machines.
 
diff --git a/docs/superpowers/plans/2026-04-18-wp2-plugin-host.md b/docs/implementation/agent-plans/2026-04-18-wp2-plugin-host.md
similarity index 99%
rename from docs/superpowers/plans/2026-04-18-wp2-plugin-host.md
rename to docs/implementation/agent-plans/2026-04-18-wp2-plugin-host.md
index 628ea21b..d96421d2 100644
--- a/docs/superpowers/plans/2026-04-18-wp2-plugin-host.md
+++ b/docs/implementation/agent-plans/2026-04-18-wp2-plugin-host.md
@@ -97,11 +97,11 @@ Create `/home/john/clarion/crates/clarion-core/src/plugin/mod.rs`:
 //! # Scope
 //!
 //! This module is the Clarion-side end of the plugin transport defined in
-//! [ADR-002](../../../../../docs/clarion/adr/ADR-002-plugin-transport-json-rpc.md)
+//! [ADR-002](../../clarion/adr/ADR-002-plugin-transport-json-rpc.md)
 //! and the enforcement surface for
-//! [ADR-021](../../../../../docs/clarion/adr/ADR-021-plugin-authority-hybrid.md)
+//! [ADR-021](../../clarion/adr/ADR-021-plugin-authority-hybrid.md)
 //! §2a-d. The ontology boundary rules from
-//! [ADR-022](../../../../../docs/clarion/adr/ADR-022-core-plugin-ontology.md)
+//! [ADR-022](../../clarion/adr/ADR-022-core-plugin-ontology.md)
 //! are enforced by [`host`] against the manifest parsed by [`manifest`].
 //!
 //! # Sub-modules
@@ -195,7 +195,7 @@ Create `/home/john/clarion/crates/clarion-core/src/plugin/manifest.rs` with the
 //! `plugin.toml` parser + validator (L5).
 //!
 //! Parses the manifest shape locked by WP2 §L5 and validates against
-//! [ADR-022](../../../../../docs/clarion/adr/ADR-022-core-plugin-ontology.md):
+//! [ADR-022](../../clarion/adr/ADR-022-core-plugin-ontology.md):
 //! plugin `name` must match the identifier grammar; entity kinds cannot
 //! shadow the core-reserved set (`file`, `subsystem`, `guidance`); rule-ID
 //! prefix must be `CLA-<PLUGIN_ID_UPPERCASE>-` and end with `-`.
@@ -527,7 +527,7 @@ pub enum ManifestError {
 }
 
 /// Core-reserved entity kinds per
-/// [ADR-022](../../../../../docs/clarion/adr/ADR-022-core-plugin-ontology.md).
+/// [ADR-022](../../clarion/adr/ADR-022-core-plugin-ontology.md).
 /// These are produced by core-owned algorithms (file-discovery, Leiden
 /// clustering, guidance composition). A plugin declaring any of them in
 /// its `entity_kinds` list is rejected at manifest parse.
diff --git a/docs/superpowers/plans/2026-05-05-b2-class-module-entities.md b/docs/implementation/agent-plans/2026-05-05-b2-class-module-entities.md
similarity index 100%
rename from docs/superpowers/plans/2026-05-05-b2-class-module-entities.md
rename to docs/implementation/agent-plans/2026-05-05-b2-class-module-entities.md
diff --git a/docs/superpowers/plans/2026-05-18-phase3-subsystems.md b/docs/implementation/agent-plans/2026-05-18-phase3-subsystems.md
similarity index 99%
rename from docs/superpowers/plans/2026-05-18-phase3-subsystems.md
rename to docs/implementation/agent-plans/2026-05-18-phase3-subsystems.md
index ce04fb7d..2ee037b1 100644
--- a/docs/superpowers/plans/2026-05-18-phase3-subsystems.md
+++ b/docs/implementation/agent-plans/2026-05-18-phase3-subsystems.md
@@ -25,8 +25,8 @@ serde_norway, sha2 for ADR-006 subsystem hashes, a graph-clustering crate
 candidate qualified in Task 1, Python 3.11 AST extraction for import edges,
 pytest, mypy, ruff, cargo nextest, cargo-deny, and existing shell E2E scripts.
 
-**Spec:** ADR-006, ADR-003, ADR-022, `docs/clarion/v0.1/requirements.md`,
-`docs/clarion/v0.1/system-design.md`, and the Phase 3 handoff
+**Spec:** ADR-006, ADR-003, ADR-022, `docs/clarion/1.0/requirements.md`,
+`docs/clarion/1.0/system-design.md`, and the Phase 3 handoff
 `docs/superpowers/handoffs/2026-05-18-phase3-subsystems-handoff.md`.
 
 **Filigree umbrella:** `clarion-1dfeebfa36` (P1 work_package;
@@ -140,7 +140,7 @@ Direction: `member_module -> subsystem`. The MCP membership helper queries
 
 **Recommendation:** add a new `subsystem_members(id)` MCP tool rather than
 folding the behavior into `neighborhood`. Requirements already name
-`subsystem_members` (`docs/clarion/v0.1/requirements.md:365-371`), and a
+`subsystem_members` (`docs/clarion/1.0/requirements.md:365-371`), and a
 separate tool keeps the response schema narrow: subsystem metadata plus an
 ordered member list. `neighborhood` can later include subsystem links
 additively, but that should not be the only way to inspect a subsystem.
diff --git a/docs/superpowers/plans/2026-05-18-phase3-subsystems.review.json b/docs/implementation/agent-plans/2026-05-18-phase3-subsystems.review.json
similarity index 100%
rename from docs/superpowers/plans/2026-05-18-phase3-subsystems.review.json
rename to docs/implementation/agent-plans/2026-05-18-phase3-subsystems.review.json
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/00-coordination.md b/docs/implementation/arch-analysis-2026-05-20-2124/00-coordination.md
new file mode 100644
index 00000000..3be24ee1
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/00-coordination.md
@@ -0,0 +1,63 @@
+# Analysis Coordination Plan
+
+## Configuration
+
+- **Scope**: Full RC1 branch at `/home/john/clarion`, including Rust workspace crates, Python plugin, tests/perf/e2e harnesses, federation fixtures, release/CI scripts, and governing docs.
+- **Branch / commit**: `RC1` at `286d92d` (`RC1...origin/RC1 [ahead 1]`).
+- **Deliverables selected**: **Option G — Comprehensive**.
+  - Rationale: user requested a fresh "root and branch" analysis after deleting the old analysis.
+  - Note: the skill's interactive deliverable menu is documented here rather than asked live because the user explicitly named the comprehensive scope.
+- **Workspace**: `docs/implementation/arch-analysis-2026-05-20-2124/`.
+- **Strategy**: **PARALLEL** subagent exploration over independent subsystems, then independent validation gates.
+- **Tier**: Medium-to-large. Source is below ultralarge thresholds, but RC1 adds release governance and federation surfaces that warrant quality/security/dependency passes.
+- **Time constraint**: None stated.
+- **Complexity estimate**: High because Option G includes full analysis, quality, security, test infrastructure, dependency analysis, and architect handover.
+
+## Subsystem Candidates
+
+1. `clarion-core` — domain primitives, plugin protocol/host, entity IDs, LLM provider contracts.
+2. `clarion-storage` — SQLite schema, writer actor, reader pool, query/cache helpers.
+3. `clarion-cli` — `clarion` binary, install/analyze/serve, HTTP read API, secret-scan glue, clustering.
+4. `clarion-mcp` — consult-mode MCP read surface, summary/inferred dispatch, Filigree enrichment.
+5. `clarion-scanner` — pre-ingest secret scanning engine and baseline policy.
+6. `clarion-plugin-fixture` — protocol-compatible fixture plugin and host integration support.
+7. `plugins/python` — Python AST/pyright language plugin and Wardline probe.
+8. `tests`, `scripts`, `.github`, and docs/fixtures — release, federation, quality, and validation infrastructure.
+
+## Deliverables
+
+| File | Purpose |
+|---|---|
+| `01-discovery-findings.md` | RC1 branch holistic scan and subsystem map |
+| `02-subsystem-catalog.md` | Contract-shaped subsystem catalog |
+| `03-diagrams.md` | Mermaid architecture diagrams |
+| `04-final-report.md` | Executive architecture report and prioritized risks |
+| `05-quality-assessment.md` | Code quality, maintainability, and refactor pressure |
+| `06-architect-handover.md` | Handover package for future architecture work |
+| `07-security-surface.md` | Trust boundaries, auth, secret handling, and security red flags |
+| `08-release-readiness.md` | RC1 release-readiness assessment and tag blockers |
+| `09-test-infrastructure.md` | Test strategy, gates, fixtures, and coverage gaps |
+| `10-dependency-analysis.md` | Crate/plugin/dependency graph and coupling risks |
+
+## Execution Log
+
+- 2026-05-20 21:24 — Ran `filigree session-context`; only ready work is P4 `clarion-0d21d9c2ac` "Future".
+- 2026-05-20 21:24 — Ran `git status --short --branch`; branch is `RC1...origin/RC1 [ahead 1]`.
+- 2026-05-20 21:24 — Removed old analysis directory `docs/implementation/arch-analysis-2026-05-18-1244/` at user request.
+- 2026-05-20 21:24 — Created fresh workspace `docs/implementation/arch-analysis-2026-05-20-2124/temp`.
+- 2026-05-20 21:24 — Confirmed Rust workspace metadata has six crates: `clarion-core`, `clarion-storage`, `clarion-cli`, `clarion-mcp`, `clarion-scanner`, and `clarion-plugin-fixture`.
+- 2026-05-20 21:25 — Started six focused subsystem exploration agents: core/fixture, storage, CLI/scanner, MCP, Python plugin, and release/federation/docs.
+- 2026-05-20 21:31 — Integrated all six exploration reports into the root-and-branch synthesis.
+- 2026-05-20 21:36 — Created Option G deliverables: discovery, catalog, diagrams, final report, quality, security, release readiness, test infrastructure, dependency analysis, and architect handover.
+- 2026-05-20 21:37 — Updated implementation-index and handoff links away from the deleted 2026-05-18 analysis.
+
+## Agent Roster
+
+| Agent | Scope | Result |
+|---|---|---|
+| Aristotle | `clarion-core` and `clarion-plugin-fixture` | Complete; high confidence. |
+| Poincare | `clarion-storage` | Complete; high confidence. |
+| Halley | `clarion-cli` and `clarion-scanner` | Complete; high confidence. |
+| James | `clarion-mcp` | Complete; high confidence. |
+| Pascal | `plugins/python` | Complete; high confidence for source shape, medium for live runtime health because tests were not executed in the exploration pass. |
+| Mill | Release, federation, governance, docs, workflows | Complete; high confidence for doc/workflow shape, with live GitHub policy still unverified in this pass. |
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/01-discovery-findings.md b/docs/implementation/arch-analysis-2026-05-20-2124/01-discovery-findings.md
new file mode 100644
index 00000000..689c1b1d
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/01-discovery-findings.md
@@ -0,0 +1,137 @@
+# RC1 Architecture Discovery Findings
+
+**Date**: 2026-05-20  
+**Branch**: `RC1`  
+**Commit analyzed**: `286d92d`  
+**Mode**: root-and-branch, Option G comprehensive architecture archaeology  
+**Old analysis removed**: `docs/implementation/arch-analysis-2026-05-18-1244/`
+
+## Executive Discovery
+
+Clarion is a local-first code archaeology system. It ingests a repository,
+extracts code entities and relationships, persists a SQLite graph, and serves
+consult-mode agents through MCP and a federation HTTP read API. The v1.0
+implementation is a Rust 2024 workspace plus a Python language plugin.
+
+The RC1 branch is structurally coherent and close to release shape, but not
+release-ready by policy. The codebase has strong boundary validation, broad
+test coverage around the main contracts, and a deliberately local-first
+federation posture. Remaining release risks are concentrated in repository
+governance, test-gate mismatches, contract/documentation drift, and
+high-blast-radius files that need restraint before tag.
+
+## Repository Shape
+
+| Area | Role |
+|---|---|
+| `crates/clarion-core` | Shared contracts, entity IDs, plugin host, manifest/protocol/transport validation, LLM provider adapters. |
+| `crates/clarion-storage` | SQLite schema, writer actor, reader pool, typed graph queries, summary/inferred-edge caches. |
+| `crates/clarion-cli` | `clarion` binary: install, analyze, serve, HTTP read API, release-facing operator paths. |
+| `crates/clarion-mcp` | MCP consult-mode JSON-RPC server and tool handlers. |
+| `crates/clarion-scanner` | Pre-ingest secret detector and detect-secrets-style baseline handling. |
+| `crates/clarion-plugin-fixture` | Subprocess fixture plugin for host/integration tests. |
+| `plugins/python` | Python language extractor, JSON-RPC stdio server, Pyright-backed resolution, Wardline probe. |
+
+Approximate source inventory from this pass:
+
+| Area | Signal |
+|---|---|
+| Rust crates | About 40.5K lines under `crates/`. |
+| Python plugin source/tests | About 6.4K lines under `plugins/python/src` and `plugins/python/tests`. |
+| Documentation | About 36.5K markdown lines under `docs/`. |
+
+Largest/highest-blast-radius files:
+
+| File | Approx LOC | Why It Matters |
+|---|---:|---|
+| `crates/clarion-mcp/src/lib.rs` | 3127 | Tool catalog, MCP envelope, LLM summary/inferred-edge paths, Filigree enrichment. |
+| `crates/clarion-core/src/plugin/host.rs` | 2935 | Plugin subprocess supervision, boundary validation, path/resource breakers. |
+| `crates/clarion-cli/src/analyze.rs` | 2427 | Main ingestion orchestration and subsystem clustering path. |
+| `crates/clarion-core/src/llm_provider.rs` | 2467 | Live-provider adapters, CLI/HTTP calls, usage accounting. |
+| `crates/clarion-cli/src/http_read.rs` | 1532 | Federation HTTP contract, auth, envelopes, limits. |
+| `plugins/python/src/clarion_plugin_python/pyright_session.py` | 1406 | LSP lifecycle, timeouts, target mapping. |
+
+## Source Of Truth
+
+The governing ladder is explicit and healthy:
+
+1. Accepted ADRs under `docs/clarion/adr/`.
+2. `docs/clarion/1.0/requirements.md`.
+3. `docs/clarion/1.0/system-design.md`.
+4. `docs/clarion/1.0/detailed-design.md`.
+5. Implementation history under `docs/implementation/`.
+
+Implementation-history documents are evidence, not governing design. Accepted
+ADRs carry release and federation decisions. ADR-033 defines v1.0 distribution
+through GitHub Releases. ADR-034 hardens the federation HTTP read API around
+loopback defaults, authentication, and closed response envelopes.
+
+## Branch Context
+
+At analysis time:
+
+- Branch: `RC1`.
+- Local state: one commit ahead of `origin/RC1`.
+- HEAD: `286d92d`.
+- HEAD adds stronger `AGENTS.md` guidance around focused subagents for release
+  reviews, broad audits, debugging, and independent implementation slices.
+
+RC1's broader delta is release/federation-heavy: v1.0 changelog, federation
+HTTP read API, secret scanner, subsystem clustering, release governance, and
+operator documentation.
+
+## Architecture Pattern Summary
+
+1. `clarion install` creates `.clarion/clarion.db`, config files, ignore rules,
+   and applies migrations.
+2. `clarion analyze` discovers plugins, scans source before ingest, runs plugin
+   analysis, writes core file/plugin entities and edges, runs graph completion
+   and subsystem clustering, records run state, and persists findings.
+3. `clarion serve` opens storage, starts MCP stdio serving, and optionally
+   starts the federation HTTP read API.
+4. MCP clients query the graph for entity lookup, paths, neighborhoods,
+   summaries, inferred calls, Filigree issue associations, and subsystem
+   membership.
+5. Federation consumers use the HTTP read API for file resolution and
+   briefing-safe content reads without making Clarion depend on sibling
+   products.
+
+The design preserves the Loom doctrine: sibling integrations enrich Clarion,
+but Clarion remains useful alone.
+
+## High-Confidence Strengths
+
+- Clear crate boundaries map to product responsibilities.
+- SQLite writes are serialized through a writer actor while reads use a pool.
+- Boundary validation exists at manifests, JSON-RPC framing, plugin path jail,
+  field caps, source-hash checks, HTTP envelopes, and scanner baselines.
+- Secret scanning is pre-ingest and blocks LLM summary paths before source
+  bytes can leave.
+- MCP and HTTP surfaces use closed, test-pinned envelopes.
+- The Python plugin fails soft on syntax/Pyright availability rather than
+  collapsing the full run.
+- Release workflow shape includes static governance checks, checksums, signing,
+  and provenance.
+
+## Discovery Concerns
+
+- Live GitHub repository policy was documented as permissive in the latest
+  readiness snapshot: `main` unprotected, permissive Actions policy, no
+  rulesets. This must be rechecked live before release.
+- CI/release workflows run walking-skeleton and secret-scan E2E scripts, but
+  not every end-to-end gate named in `AGENTS.md`.
+- `CHANGELOG.md` contains a federation auth error-code drift: `UNAUTHORIZED`
+  versus canonical `UNAUTHENTICATED`.
+- `crates/clarion-core/src/plugin/limits.rs` describes `EntityCountCap` as
+  covering entities, edges, and findings, while host edge processing says edges
+  do not participate in the entity cap.
+- HTTP HMAC is hand-rolled in `crates/clarion-cli/src/http_read.rs`; future
+  edits need crypto-specific review.
+- Python plugin pins and Wardline bounds are duplicated across manifest/config
+  code without a direct drift test.
+
+## Confidence
+
+High for source structure, subsystem boundaries, and release documentation
+shape. Medium for live release posture because this pass did not run live
+GitHub API policy checks or the full CI floor.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/02-subsystem-catalog.md b/docs/implementation/arch-analysis-2026-05-20-2124/02-subsystem-catalog.md
new file mode 100644
index 00000000..66f86375
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/02-subsystem-catalog.md
@@ -0,0 +1,218 @@
+# RC1 Subsystem Catalog
+
+Each subsystem uses the archaeologist catalog contract: Location,
+Responsibility, Key Components, Dependencies, Patterns Observed, Concerns, and
+Confidence.
+
+## 1. Clarion Core
+
+**Location:** `crates/clarion-core`
+
+**Responsibility:** Shared runtime contracts and enforcement: entity ID
+assembly, plugin manifest/protocol/transport/discovery/supervision, resource
+and path safety checks, host findings, test mocks, and LLM provider adapters.
+
+**Key Components:** `src/lib.rs`, `src/entity_id.rs`,
+`src/plugin/manifest.rs`, `src/plugin/protocol.rs`, `src/plugin/host.rs`,
+`src/llm_provider.rs`.
+
+**Dependencies:** consumed by most workspace crates and the fixture plugin;
+depends on `serde`, `serde_json`, `toml`, `reqwest`, `tracing`, `nix`, `which`,
+and process/file APIs.
+
+**Patterns Observed:** facade exports stable caller-facing types; boundary
+validation happens at manifest, frame, path, field-size, and LLM response
+ingress; malformed plugin data becomes findings while path/resource breakers
+stop the plugin.
+
+**Concerns:** `EntityCountCap` semantics drift between comments and host edge
+processing; memory limits are Linux-only; path jail is canonicalization-time,
+not open-file proof; `plugin/host.rs` and `llm_provider.rs` have broad blast
+radius.
+
+**Confidence:** High.
+
+## 2. Clarion Plugin Fixture
+
+**Location:** `crates/clarion-plugin-fixture`
+
+**Responsibility:** Minimal binary test plugin that speaks Clarion JSON-RPC
+framing over stdin/stdout and gives `PluginHost::spawn` a real subprocess
+target.
+
+**Key Components:** `src/main.rs`, `src/lib.rs`, `Cargo.toml`, and
+`crates/clarion-core/tests/fixtures/plugin.toml`.
+
+**Dependencies:** consumed by core subprocess tests; depends on `clarion-core`,
+`serde_json`, and Unix-only `nix` features for memory-limit testing.
+
+**Patterns Observed:** reuses production framing/protocol types; fails closed
+on invalid input; emits deterministic single-entity output.
+
+**Concerns:** manifest declares an edge kind but the fixture emits no accepted
+edge; bad input terminates instead of returning JSON-RPC errors; memory-limit
+stress coverage is platform-shaped.
+
+**Confidence:** High.
+
+## 3. Clarion Storage
+
+**Location:** `crates/clarion-storage`
+
+**Responsibility:** SQLite persistence for Clarion's graph, runs, findings,
+search indexes, LLM/query caches, writer serialization, and pooled reads.
+
+**Key Components:** `migrations/0001_initial_schema.sql`, `src/schema.rs`,
+`src/commands.rs`, `src/writer.rs`, `src/reader.rs`, `src/query.rs`,
+`src/cache.rs`, `src/unresolved.rs`.
+
+**Dependencies:** consumed by CLI, MCP, and HTTP read paths; depends on
+`clarion-core`, `rusqlite`, `deadpool-sqlite`, `tokio`, `serde`,
+`serde_json`, `blake3`, `tracing`, and `thiserror`.
+
+**Patterns Observed:** single writer actor serializes all durable mutation;
+read pool handles query concurrency; SQLite constraints and writer protocol
+checks share invariant enforcement; tests use real temp SQLite databases.
+
+**Concerns:** `summary_cache.entity_id` has no FK while
+`inferred_edge_cache.caller_entity_id` has one; `ReaderPool::open` defers DB
+validation until first read; query-time writes can force active run
+transactions to commit.
+
+**Confidence:** High.
+
+## 4. Clarion CLI, Analyze, Serve, And HTTP Read API
+
+**Location:** `crates/clarion-cli`
+
+**Responsibility:** Owns the `clarion` binary: project install, analyze
+orchestration, pre-ingest secret scanning, MCP stdio serving, and federation
+HTTP read API.
+
+**Key Components:** `src/main.rs`, `src/install.rs`, `src/analyze.rs`,
+`src/secret_scan/*`, `src/serve.rs`, `src/http_read.rs`.
+
+**Dependencies:** consumed by operators, CI/E2E scripts, federation consumers,
+and MCP clients; depends on `clarion-core`, `clarion-storage`, `clarion-mcp`,
+`clarion-scanner`, `clap`, `axum`, `tokio`, `tower`, `rusqlite`, `ignore`,
+`serde`, and `xgraph`.
+
+**Patterns Observed:** explicit run terminal states; plugin execution isolated
+in `spawn_blocking`; HTTP API uses closed envelopes, body/concurrency/timeout
+layers, ETags, and single-connection batch lookup; `analyze` skips `.env`
+loading.
+
+**Concerns:** HTTP HMAC is locally implemented; `_capabilities` is
+intentionally unauthenticated, so bind-address and non-loopback trust remain
+load-bearing; `analyze.rs` and `http_read.rs` should not absorb unrelated
+future concerns.
+
+**Confidence:** High.
+
+## 5. Clarion Scanner
+
+**Location:** `crates/clarion-scanner`
+
+**Responsibility:** Core-owned pre-ingest scanner: detects secret-like byte
+ranges, returns redacted metadata plus SHA-1 hashes, and applies
+detect-secrets-style baselines.
+
+**Key Components:** `src/lib.rs`, `src/patterns.rs`, `src/baseline.rs`,
+`src/entropy.rs`.
+
+**Dependencies:** consumed by CLI pre-ingest scanner; depends on `regex`,
+`serde`, `serde_norway`, `sha1`, and `thiserror`.
+
+**Patterns Observed:** byte-oriented scanning preserves offsets for non-UTF-8
+input; literal secrets are not exported; baseline suppression keys on file
+path, rule, line, hash, and `is_secret = false`.
+
+**Concerns:** high-entropy detection is intentionally broad and relies on
+baselines for lockfile/git-SHA false positives; contextual comment suppression
+only handles `#` comments.
+
+**Confidence:** High.
+
+## 6. Clarion MCP Consult Surface
+
+**Location:** `crates/clarion-mcp`
+
+**Responsibility:** Exposes Clarion's MCP JSON-RPC/tool surface for code-graph
+lookup, graph traversal, summaries, inferred calls, subsystem membership, and
+optional Filigree issue enrichment.
+
+**Key Components:** tool catalog, `ServerState`, LLM prompt/cache/accounting
+path, `config.rs`, `filigree.rs`.
+
+**Dependencies:** consumed by MCP clients and CLI `serve`; depends on
+`clarion-storage`, `clarion-core`, optional Filigree HTTP, `blake3`, `reqwest`,
+`rusqlite`, `serde`, `serde_json`, `serde_norway`, `time`, `tokio`, and
+`tracing`.
+
+**Patterns Observed:** uniform tool envelope; live providers require explicit
+opt-in; blocking LLM and Filigree work uses `spawn_blocking`; inferred
+dispatches coalesce concurrent cold requests.
+
+**Concerns:** unreadable/non-UTF8 source returns empty LLM excerpt rather than
+hard error; one shared token ledger gates both summary and inferred-edge calls;
+Filigree HTTP error bodies can appear in MCP envelope error strings.
+
+**Confidence:** High.
+
+## 7. Python Language Plugin
+
+**Location:** `plugins/python`
+
+**Responsibility:** Clarion's v1.0 Python language plugin: JSON-RPC stdio
+server, AST entity/edge extraction, Pyright-backed call/reference resolution,
+and fail-soft Wardline compatibility reporting.
+
+**Key Components:** `plugin.toml`, `pyproject.toml`, `server.py`,
+`extractor.py`, `pyright_session.py`, `wardline_probe.py`, `stdout_guard.py`.
+
+**Dependencies:** consumed by Clarion plugin host and discovery; depends on
+Python stdlib AST/JSON/subprocess/select/pathlib, `packaging`, pinned
+`pyright==1.1.409`, optional Wardline import, and `pyright-langserver`.
+
+**Patterns Observed:** syntax errors emit degraded module entities; missing
+Pyright returns unresolved stats/findings; caps include 8 MiB frames, stdout
+guard, per-file Pyright timeout, reference-site cap, and project-local external
+filtering.
+
+**Concerns:** Pyright pin is duplicated in `pyproject.toml` and `plugin.toml`;
+Wardline bounds are duplicated in `plugin.toml` and server constants; Wardline
+probe catches `ImportError` only; installed-entrypoint smoke can skip when the
+package is not installed editable.
+
+**Confidence:** High for source shape and local behavior; medium for live
+runtime health because plugin tests were not executed in this pass.
+
+## 8. Release, Governance, And Federation Evidence
+
+**Location:** `docs/clarion/1.0`, `docs/clarion/adr`, `docs/federation`,
+`docs/operator`, `.github/workflows`, `scripts`, `tests/e2e`, `tests/perf`.
+
+**Responsibility:** Defines the v1.0 release contract, federation HTTP read
+contract, governance gates, release workflows, operator evidence, manual
+publish checks, and scale/perf evidence.
+
+**Key Components:** v1.0 requirements/system/detailed design, ADR-033,
+ADR-034, federation contracts and fixtures, release workflows, governance
+guard scripts, E2E/perf artifacts.
+
+**Dependencies:** used by release maintainers, Filigree's `ClarionRegistry`,
+MCP clients, consult-mode agents, and external operators; depends on GitHub
+Releases/Actions/rulesets, Dependabot, cosign, SLSA generator, cargo/nextest,
+Python tooling, sqlite3, pyright, and optional Filigree/Wardline.
+
+**Patterns Observed:** layered docs with explicit precedence; federation is
+enrich-only, not shared runtime; closed wire contracts with normative fixtures;
+fail-closed auth for non-loopback HTTP; governance-as-code for release policy.
+
+**Concerns:** live GitHub repository governance is documented as still
+permissive; release workflows do not run every E2E script named in local
+instructions; external-operator smoke lacks a dated result artifact;
+`CHANGELOG.md` has an auth-code mismatch.
+
+**Confidence:** High for documentation/infrastructure shape; medium for live
+release posture.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/03-diagrams.md b/docs/implementation/arch-analysis-2026-05-20-2124/03-diagrams.md
new file mode 100644
index 00000000..e464665b
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/03-diagrams.md
@@ -0,0 +1,162 @@
+# RC1 Architecture Diagrams
+
+These diagrams are text-native so they remain reviewable in the implementation
+archive.
+
+## C4 Context
+
+```mermaid
+flowchart LR
+    Operator[Local operator]
+    Agent[Consult-mode agent / MCP client]
+    Sibling[Sibling Loom products]
+    Provider[Optional LLM providers]
+    Repo[Target repository]
+    Clarion[Clarion local-first code archaeology]
+    DB[(SQLite graph)]
+
+    Operator -->|install / analyze / serve| Clarion
+    Clarion -->|walks and analyzes| Repo
+    Clarion -->|stores graph/runs/findings| DB
+    Agent -->|MCP JSON-RPC| Clarion
+    Sibling -->|HTTP read API| Clarion
+    Clarion -->|optional summaries / inferred calls| Provider
+```
+
+## Container View
+
+```mermaid
+flowchart TB
+    CLI[clarion-cli]
+    Core[clarion-core]
+    Storage[clarion-storage]
+    MCP[clarion-mcp]
+    Scanner[clarion-scanner]
+    Py[Python language plugin]
+    Fixture[Fixture plugin]
+    DB[(SQLite)]
+    HTTP[Federation HTTP read API]
+    Agent[MCP client]
+
+    CLI --> Core
+    CLI --> Storage
+    CLI --> Scanner
+    CLI --> MCP
+    CLI --> HTTP
+    CLI -->|spawns| Py
+    Core -->|protocol/contracts| Py
+    Core -->|test subprocess| Fixture
+    Storage --> DB
+    MCP --> Storage
+    MCP --> Core
+    HTTP --> Storage
+    Agent --> MCP
+```
+
+## Analyze Pipeline
+
+```mermaid
+sequenceDiagram
+    participant Op as Operator
+    participant CLI as clarion analyze
+    participant Scan as Secret scanner
+    participant Core as Plugin host
+    participant Py as Python plugin
+    participant Writer as Storage writer actor
+    participant DB as SQLite
+
+    Op->>CLI: clarion analyze
+    CLI->>Scan: pre-ingest source scan
+    alt secret blocks briefing
+        Scan-->>CLI: findings / block summary paths
+    else no blocking secret
+        Scan-->>CLI: ok / baseline-suppressed findings
+    end
+    CLI->>Core: discover and spawn plugins
+    Core->>Py: initialize / analyze_file
+    Py-->>Core: entities / edges / findings
+    Core-->>CLI: validated plugin output
+    CLI->>Writer: insert core:file rows
+    CLI->>Writer: insert plugin graph rows
+    CLI->>Writer: graph completion and subsystem clustering rows
+    Writer->>DB: serialized commits
+    CLI->>Writer: complete / soft_fail / hard_fail run
+```
+
+## Serve And Query Flow
+
+```mermaid
+flowchart LR
+    DB[(SQLite graph)]
+    Reader[ReaderPool]
+    MCP[clarion-mcp tools]
+    HTTP[HTTP read API]
+    Agent[MCP client]
+    Sibling[Filigree/Wardline consumer]
+    LLM[Optional LLM provider]
+    Writer[Writer actor]
+
+    DB --> Reader
+    Reader --> MCP
+    Reader --> HTTP
+    Agent --> MCP
+    Sibling --> HTTP
+    MCP -->|summary/inferred cache miss| LLM
+    MCP -->|cache/finding writes| Writer
+    Writer --> DB
+```
+
+## Trust Boundaries
+
+```mermaid
+flowchart TB
+    Source[Target source files]
+    Scanner[Pre-ingest scanner]
+    Plugin[External plugin subprocess]
+    Host[Clarion plugin host]
+    DB[(SQLite)]
+    MCP[MCP stdio]
+    HTTP[HTTP read API]
+    LLM[External LLM/CLI provider]
+
+    Source --> Scanner
+    Scanner -->|allowed or briefing-blocked| Host
+    Host -->|Content-Length JSON-RPC| Plugin
+    Plugin -->|untrusted entities/edges/findings| Host
+    Host -->|validated graph writes| DB
+    DB --> MCP
+    DB --> HTTP
+    MCP -->|hash-checked excerpts| LLM
+```
+
+## Release Lane
+
+```mermaid
+flowchart LR
+    RC1[RC1 branch]
+    CI[CI floor]
+    Gov[Release governance guard]
+    Dry[Release dry run]
+    Tag[v* tag]
+    Assets[GitHub Release assets]
+    Smoke[Artifact smoke test]
+    Sign[Checksums / cosign / SLSA provenance]
+
+    RC1 --> CI
+    CI --> Gov
+    Gov --> Dry
+    Dry --> Tag
+    Tag --> Assets
+    Assets --> Smoke
+    Smoke --> Sign
+```
+
+## Notes
+
+- Clarion has one durable local graph store. Sibling products enrich Clarion
+  through APIs, not shared runtime.
+- The strongest architectural boundary is the storage writer actor: durable
+  mutation is serialized while reads are pooled.
+- The most sensitive data boundary is source-to-LLM; scanner blocking, source
+  hashes, live-provider opt-in, and token budgets all participate in this
+  control.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/04-final-report.md b/docs/implementation/arch-analysis-2026-05-20-2124/04-final-report.md
new file mode 100644
index 00000000..d7211ef2
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/04-final-report.md
@@ -0,0 +1,160 @@
+# RC1 Root-And-Branch Architecture Report
+
+**Date**: 2026-05-20  
+**Branch/commit**: `RC1` at `286d92d`  
+**Scope**: source, tests, workflows, release/federation docs, and relevant
+implementation archive references.  
+**Execution model**: coordinator plus six subsystem exploration agents.
+
+## Bottom Line
+
+RC1 is architecturally coherent and close to v1.0 release shape, but it should
+not be treated as release-ready until live repository governance and the
+remaining test-gate/documentation drifts are resolved.
+
+The product structure is good: Rust workspace boundaries match
+responsibilities, the Python plugin sits behind a defined protocol boundary,
+SQLite mutation is serialized, and both MCP and HTTP surfaces are shaped by
+closed contracts. The main risks are release-hardening risks concentrated at
+policy enforcement, drift between duplicate configuration facts, and
+high-blast-radius files where future changes can accidentally bypass existing
+controls.
+
+## Replacement Of The Removed Analysis
+
+The old `docs/implementation/arch-analysis-2026-05-18-1244/` snapshot has
+been removed. This report replaces it as the current RC1 architecture
+snapshot. It intentionally does not preserve the old H/L finding labels;
+current action should be driven by this report, current source, and live
+Filigree state.
+
+## Architecture Assessment
+
+Clarion remains aligned with its local-first mission. It can install, analyze,
+store, and serve without mandatory sibling runtime. Federation integrations are
+read/enrichment paths, not semantic dependencies.
+
+The crate/plugin split is sensible:
+
+- Core contracts and plugin host concerns live in `clarion-core`.
+- Durable graph storage lives in `clarion-storage`.
+- Operator commands and federation HTTP live in `clarion-cli`.
+- Consult-mode MCP lives in `clarion-mcp`.
+- Pre-ingest secret detection lives in `clarion-scanner`.
+- Python language semantics live in `plugins/python`.
+
+The main maintainability pressure comes from large files that carry many
+responsibilities inside otherwise sound crate boundaries. `analyze.rs`,
+`http_read.rs`, `plugin/host.rs`, `llm_provider.rs`, and
+`clarion-mcp/src/lib.rs` should be treated as "touch with tests and local
+factoring" files.
+
+## Strengths
+
+- Strong source-of-truth ladder: ADRs first, then requirements/design, then
+  implementation history.
+- Local-first design is preserved; no shared registry/mediator dependency has
+  crept into core semantics.
+- Storage uses a disciplined single-writer/pool-reader model.
+- Plugin outputs are treated as untrusted and validated before persistence.
+- Secret scanner blocks risky LLM paths before source leaves the machine.
+- HTTP read API is contract-heavy: closed envelopes, auth policy, path
+  traversal rejection, ETags, limits.
+- MCP surface has broad tests around metadata, storage tools, LLM
+  caching/accounting, coalescing, hallucinated targets, Filigree drift/caps.
+- Release workflow includes static governance checks, checksum generation,
+  cosign signing, and SLSA provenance.
+
+## Priority Risks
+
+### R1. Release Governance Is Required But Live State Is Unverified
+
+The release lane expects protected `main`, restricted Actions policy, and
+repository rulesets. The latest readiness snapshot says live GitHub policy was
+still permissive. Static workflow checks are useful, but they do not prove the
+repository is configured safely.
+
+**Recommendation:** before tagging, run the governance guard against live
+GitHub and resolve any policy failures.
+
+### R2. End-To-End Gate Mismatch
+
+Local instructions name walking skeleton, Sprint 2 MCP surface, and Phase 3
+subsystem E2E as gates. CI/release workflows run walking skeleton and
+secret-scan smoke, but not every named E2E script.
+
+**Recommendation:** add `tests/e2e/sprint_2_mcp_surface.sh` and
+`tests/e2e/phase3_subsystems.sh` to required jobs, or explicitly document them
+as manual release gates with dated evidence.
+
+### R3. Contract Drift In Public/Operator Docs
+
+`CHANGELOG.md` lists HTTP auth error code `UNAUTHORIZED`, while federation
+contracts and implementation use `UNAUTHENTICATED`.
+
+**Recommendation:** correct the changelog before release.
+
+### R4. Duplicate Version/Policy Facts Can Drift
+
+Python plugin Pyright pins are duplicated in `plugin.toml` and
+`pyproject.toml`. Wardline bounds are duplicated in manifest and server
+constants. Core cap semantics are described differently between `limits.rs`
+and host edge processing.
+
+**Recommendation:** add direct drift tests or derive one side from the other.
+For cap semantics, decide whether edges share the cap and make comments, tests,
+and code agree.
+
+### R5. Local Crypto Code Needs Review Discipline
+
+The HTTP HMAC path is implemented locally with `sha2`. It may be acceptable
+for RC1, but it is not a place for casual edits.
+
+**Recommendation:** either migrate to a vetted HMAC crate or mark the current
+code as requiring crypto-specific review for future changes.
+
+### R6. Release Evidence Gap For External Operator Smoke
+
+The external-operator smoke checklist exists, but no dated result artifact was
+found in the tree.
+
+**Recommendation:** produce and archive a dated smoke-result report before
+release or explicitly remove it from the release-ready checklist.
+
+## Architectural Decisions To Preserve
+
+- Keep federation enrich-only. Do not add a shared runtime, shared registry, or
+  cross-product mediator to simplify Clarion.
+- Keep plugin subprocesses untrusted.
+- Keep scanner-before-LLM as a hard ordering constraint.
+- Keep storage mutation serialized through the writer actor.
+- Keep MCP/HTTP response envelopes closed and fixture-backed.
+
+## Targeted Follow-Ups
+
+| Priority | Follow-Up | Owner Area |
+|---|---|---|
+| P1 | Run live GitHub release-governance guard and fix policy blockers. | Release/governance |
+| P1 | Add or explicitly classify missing E2E release gates. | CI/release |
+| P1 | Correct `CHANGELOG.md` auth code to `UNAUTHENTICATED`. | Docs/federation |
+| P2 | Add Pyright pin lockstep test for `plugin.toml` and `pyproject.toml`. | Python plugin |
+| P2 | Add Wardline version-bound drift test or derive server constants. | Python plugin |
+| P2 | Clarify/test `EntityCountCap` edge/finding semantics. | Core/plugin host |
+| P2 | Decide whether HTTP HMAC should use a vetted HMAC crate. | CLI/HTTP security |
+| P2 | Add fixture subprocess edge-ingest happy path. | Core/fixture tests |
+| P3 | Decide whether `summary_cache.entity_id` intentionally lacks an FK. | Storage |
+| P3 | Archive external-operator smoke results. | Release/e2e |
+
+## Release Recommendation
+
+Do not tag from RC1 yet. The code architecture is strong enough for release
+candidate hardening, but the release policy/evidence checklist is not fully
+satisfied in the analyzed tree. Treat RC1 as candidate pending governance and
+gate alignment.
+
+## Confidence
+
+High for subsystem boundaries, source contracts, and current
+documentation/workflow shape. Medium for release readiness because this pass
+did not run the full CI floor, live GitHub policy checks, or external operator
+smoke.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/05-quality-assessment.md b/docs/implementation/arch-analysis-2026-05-20-2124/05-quality-assessment.md
new file mode 100644
index 00000000..580d669a
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/05-quality-assessment.md
@@ -0,0 +1,97 @@
+# RC1 Quality Assessment
+
+## Overall Quality Posture
+
+Clarion's quality posture is strong for a release candidate: important
+boundaries are tested, the source-of-truth ladder is explicit, and most
+high-risk runtime behavior has focused coverage. Remaining concerns are
+concentrated in drift-prone duplicated facts, large files, release-gate
+mismatches, and a few intentionally permissive or platform-shaped behaviors.
+
+## Maintainability
+
+### Strengths
+
+- Workspace boundaries are clear and map to product responsibilities.
+- Storage writes are centralized in one actor.
+- Protocol and API shapes are typed and test-pinned.
+- Documentation names authoritative sources and demotes implementation history
+  to supporting context.
+
+### Concerns
+
+- `crates/clarion-mcp/src/lib.rs`, `crates/clarion-core/src/plugin/host.rs`,
+  `crates/clarion-cli/src/analyze.rs`, `crates/clarion-core/src/llm_provider.rs`,
+  and `crates/clarion-cli/src/http_read.rs` are large enough that changes need
+  local regression tests and careful review.
+- Release/publish history still contains old arch-analysis concepts. Current
+  work should use this RC1 report and live source, not old H/L labels.
+- Some constants are duplicated instead of derived or drift-tested.
+
+## Correctness
+
+### Strengths
+
+- SQLite migrations are exercised through real temp databases.
+- Writer actor tests cover run lifecycle and graph write behavior.
+- HTTP read API tests pin path traversal rejection, briefing-block
+  non-disclosure, storage error envelopes, batching, resolve results, auth, and
+  limits.
+- MCP tests cover metadata, graph queries, LLM cache/accounting, coalescing,
+  hallucinated targets, Filigree drift/caps.
+- Python plugin tests cover server protocol, AST extraction, Pyright
+  timeouts/restarts/caps, and Wardline import/version states.
+
+### Concerns
+
+- `EntityCountCap` semantics are ambiguous for edges/findings.
+- `summary_cache.entity_id` lacks a foreign key while
+  `inferred_edge_cache.caller_entity_id` has one.
+- Installed-entrypoint Python smoke tests can skip when the plugin is not
+  installed editable.
+- Pyright-marked tests skip if `pyright-langserver` is unavailable; CI must
+  install the plugin venv before relying on them.
+
+## Operability
+
+### Strengths
+
+- `install` creates and repairs local project state predictably.
+- `analyze` records explicit terminal run states.
+- `serve` supervises MCP and optional HTTP together.
+- Release scripts and operator docs distinguish dry runs, artifacts, signing,
+  smoke tests, and governance checks.
+
+### Concerns
+
+- `ReaderPool::open` defers SQLite file validation until first read.
+- External operator smoke is checklist-based with no dated result artifact
+  found in the tree.
+- Phase 3 perf evidence is useful but directional because the temporary corpus
+  is not committed.
+
+## Documentation Quality
+
+### Strengths
+
+- ADR precedence and requirement ID stability are explicit.
+- Federation contract docs have normative fixtures and security notes.
+- Operator docs exist for OpenRouter, coding-agent providers, secret scanning,
+  release governance, and HTTP read API.
+
+### Concerns
+
+- `CHANGELOG.md` contains the `UNAUTHORIZED`/`UNAUTHENTICATED` mismatch.
+- Historical implementation documents can still mention old arch-analysis
+  finding labels. Treat them as historical notes, not current evidence.
+
+## Quality Recommendations
+
+1. Treat the large files as high-risk change zones; require narrow tests for
+   every behavior change.
+2. Add drift tests for duplicate plugin metadata and Wardline bounds.
+3. Resolve the core cap semantics mismatch with one explicit test for
+   edge-heavy plugin output.
+4. Either require all named E2E scripts in CI/release or record dated manual
+   evidence for those kept outside CI.
+5. Fix the changelog error-code mismatch before release.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/06-architect-handover.md b/docs/implementation/arch-analysis-2026-05-20-2124/06-architect-handover.md
new file mode 100644
index 00000000..88ec3845
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/06-architect-handover.md
@@ -0,0 +1,103 @@
+# RC1 Architect Handover
+
+## Context
+
+This handover is for a system architect or release owner taking over RC1
+review. It supersedes the removed `arch-analysis-2026-05-18-1244` snapshot.
+
+Clarion is a local-first code archaeology tool. It analyzes a target repo,
+stores a graph in SQLite, and serves consult-mode agents through MCP and the
+federation HTTP read API. The RC1 branch is coherent and near release
+hardening, but not yet release-ready by policy.
+
+## Current State
+
+- Branch: `RC1`.
+- Commit analyzed: `286d92d`.
+- Local branch was one commit ahead of `origin/RC1` during analysis.
+- Tracker at session start had no active release-blocking work visible; only
+  one P4 future issue was ready.
+- Old architecture-analysis directory was removed at user request.
+- New root-and-branch analysis lives in
+  `docs/implementation/arch-analysis-2026-05-20-2124/`.
+
+## Read First
+
+1. `04-final-report.md` for the release call and priority risks.
+2. `02-subsystem-catalog.md` for code geography.
+3. `07-security-surface.md` for trust boundaries.
+4. `08-release-readiness.md` for tag blockers.
+5. `09-test-infrastructure.md` for gate alignment.
+6. `10-dependency-analysis.md` for internal/external dependency risk.
+
+## Release Gate Call
+
+Current recommendation: do not tag yet.
+
+The codebase appears structurally sound, but release readiness depends on live
+GitHub governance, CI/release E2E gate alignment, changelog auth-code
+correction, and dated external-operator smoke evidence or explicit removal
+from the release checklist.
+
+## Architecture Guardrails
+
+- No shared runtime, shared registry, or mediator across Loom products.
+- Clarion must remain useful alone.
+- Federation enriches Clarion; it does not define Clarion semantics.
+- Plugin subprocesses are untrusted.
+- Source-to-LLM flow stays behind pre-ingest scanning, live-provider opt-in,
+  source-hash verification, and token budgeting.
+- SQLite mutation remains centralized through the writer actor.
+- MCP and HTTP response envelopes remain closed and fixture-backed.
+
+## Highest-Risk Files
+
+| File | Review Rule |
+|---|---|
+| `crates/clarion-cli/src/analyze.rs` | Require focused tests for pipeline/run-state/subsystem changes. |
+| `crates/clarion-cli/src/http_read.rs` | Require federation contract tests and security review for auth/path/limits. |
+| `crates/clarion-core/src/plugin/host.rs` | Require plugin boundary tests for protocol/path/resource changes. |
+| `crates/clarion-core/src/llm_provider.rs` | Require provider/accounting tests for usage, JSONL parsing, live calls. |
+| `crates/clarion-mcp/src/lib.rs` | Require MCP envelope/tool tests for response shape or LLM behavior changes. |
+| `plugins/python/src/clarion_plugin_python/pyright_session.py` | Require Pyright timeout/cap/target-mapping tests. |
+
+## Immediate Work Queue
+
+1. Run live release governance.
+2. Decide CI/release treatment for `tests/e2e/sprint_2_mcp_surface.sh` and
+   `tests/e2e/phase3_subsystems.sh`.
+3. Fix `CHANGELOG.md`: `UNAUTHORIZED` to `UNAUTHENTICATED`.
+4. Add duplicate-fact drift tests for Python plugin metadata and Wardline
+   bounds.
+5. Resolve `EntityCountCap` semantics around edges/findings.
+6. Archive external-operator smoke results.
+
+## Verification To Run Before Release Claim
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --workspace --bins
+cargo nextest run --workspace --all-features
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
+cargo deny check
+plugins/python/.venv/bin/ruff check plugins/python
+plugins/python/.venv/bin/ruff format --check plugins/python
+plugins/python/.venv/bin/mypy --strict plugins/python
+plugins/python/.venv/bin/pytest plugins/python
+bash tests/e2e/sprint_1_walking_skeleton.sh
+bash tests/e2e/sprint_2_mcp_surface.sh
+bash tests/e2e/phase3_subsystems.sh
+bash tests/e2e/wp5_secret_scan.sh
+```
+
+Then run release governance and release dry-run per
+`docs/operator/v1.0-release-governance.md`.
+
+## Handoff Risks
+
+- Memory or old implementation docs may mention the removed 2026-05-18
+  analysis. Prefer the new analysis and live source.
+- Live GitHub policy can drift independently of the repository tree.
+- Full workspace tests may require building workspace binaries first in some
+  contexts.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/07-security-surface.md b/docs/implementation/arch-analysis-2026-05-20-2124/07-security-surface.md
new file mode 100644
index 00000000..6efc3fde
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/07-security-surface.md
@@ -0,0 +1,92 @@
+# RC1 Security Surface
+
+## Security Posture Summary
+
+Clarion has a credible local-first security posture: it treats plugins as
+untrusted subprocesses, scans source before LLM exposure, constrains HTTP read
+access, and keeps sibling products optional. The main security risks are local
+implementation choices that need discipline: hand-rolled HMAC, unauthenticated
+`_capabilities`, Linux-only plugin memory ceilings, and the filesystem race
+inherent in canonicalization-based path jails.
+
+## Trust Boundaries
+
+| Boundary | Control |
+|---|---|
+| Target repository to Clarion | Secret scanning before ingest; path normalization; ignore handling; briefing-blocked file semantics. |
+| Clarion host to plugin subprocess | Content-Length JSON-RPC; manifest validation; executable basename validation; frame caps; path jail; field caps; Linux process limits. |
+| Plugin output to storage | Entity/edge validation; reserved core ontology enforcement; malformed outputs become findings or breaker conditions. |
+| Storage to MCP/HTTP | Typed query helpers; closed envelopes; traversal/path protections; briefing-blocked non-disclosure. |
+| MCP to external LLM provider | Live-provider opt-in; source-hash checks; excerpt/range limiting; token budget; cache accounting. |
+| HTTP API to sibling consumers | Loopback default; HMAC/bearer auth for non-loopback; body/concurrency/timeout limits; ETags. |
+| Release workflow to public artifacts | Pinned action checks, governance guard, checksums, cosign, SLSA provenance. |
+
+## Positive Controls
+
+- Pre-ingest scanner blocks LLM summary paths before source bytes leave the
+  local machine.
+- Baselines require exact hash/rule/path/line matching and `is_secret = false`.
+- Scanner findings do not export literal secrets.
+- Python plugin stdout guard prevents accidental protocol corruption.
+- Pyright is configured with low-indexing blast radius.
+- HTTP path traversal and briefing-block behavior are test-pinned.
+- Live LLM providers require explicit opt-in.
+
+## Security Concerns
+
+### Hand-Rolled HTTP HMAC
+
+`crates/clarion-cli/src/http_read.rs` implements HMAC behavior locally with
+`sha2`. This increases review burden. The length-mismatch fast return in
+constant-time comparison is probably not catastrophic if request parsing and
+exact-length signatures are enforced, but the code should be treated as
+cryptographic surface.
+
+**Recommendation:** move to a vetted HMAC crate or document crypto-specific
+review ownership.
+
+### Unauthenticated `_capabilities`
+
+The endpoint is intentionally unauthenticated for pre-auth discovery. That is
+compatible with the current contract only if bind-address rules and
+non-loopback auth remain strict.
+
+**Recommendation:** keep tests around loopback/non-loopback policy mandatory.
+
+### Linux-Only Plugin Memory Limits
+
+`RLIMIT_AS` enforcement is Linux-specific. Non-Linux environments warn and
+continue without equivalent memory ceilings.
+
+**Recommendation:** document platform limits clearly in operator docs and avoid
+overstating cross-platform resource isolation.
+
+### Path Jail TOCTOU
+
+The path jail relies on canonicalization. The source explicitly acknowledges a
+race between proof and later open.
+
+**Recommendation:** acceptable for local-first RC1 if documented, but revisit
+if Clarion is ever exposed to hostile multi-user repositories or remote read
+surfaces.
+
+### LLM Empty Excerpt Behavior
+
+MCP LLM paths hash-check and range-limit source, but unreadable/non-UTF8 files
+return an empty excerpt instead of a hard error.
+
+**Recommendation:** decide whether empty excerpt is intentional safe
+degradation or should be a hard refusal for summary/inference.
+
+## Release Security Blockers
+
+The code security posture is not the only release question. Live repository
+governance remains a policy blocker until verified: protected `main`,
+restricted Actions policy, required checks/rulesets, release workflow dry run,
+and artifact smoke.
+
+## Security Verdict
+
+No systemic security design failure was found. The release should wait for live
+governance verification and small contract/doc drift fixes, but the core
+local-first security architecture is sound.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/08-release-readiness.md b/docs/implementation/arch-analysis-2026-05-20-2124/08-release-readiness.md
new file mode 100644
index 00000000..ae3ac504
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/08-release-readiness.md
@@ -0,0 +1,54 @@
+# RC1 Release Readiness
+
+## Verdict
+
+RC1 is a plausible release candidate, not a release-ready commit.
+
+The code structure, release workflow shape, and federation contract are strong.
+The remaining blockers are primarily policy/evidence alignment rather than
+missing core architecture.
+
+## Ready Signals
+
+- v1.0 distribution path is decided: GitHub Releases, not crates.io/PyPI.
+- Release workflow supports `v*` tags and dry-run `workflow_dispatch`.
+- Build jobs depend on verification and release-governance jobs.
+- Release artifacts include checksums, cosign signing, and SLSA provenance.
+- Federation HTTP read contract has docs, fixtures, and integration tests.
+- Secret scanner has unit, CLI, and E2E coverage.
+- Subsystem clustering and `subsystem_members` are present in the current
+  code/doc shape.
+
+## Blocking Or Pre-Tag Items
+
+| Severity | Item | Reason |
+|---|---|---|
+| Blocker | Live GitHub governance must pass. | Latest readiness snapshot documented permissive Actions, unprotected `main`, and no rulesets. |
+| Blocker | Required E2E gate classification must be resolved. | Local instructions list Sprint 1, Sprint 2 MCP, and Phase 3 scripts; workflows do not run all of them. |
+| High | `CHANGELOG.md` auth code mismatch. | Public changelog says `UNAUTHORIZED`; contract/implementation use `UNAUTHENTICATED`. |
+| High | External-operator smoke evidence missing. | Checklist exists; no dated result artifact found. |
+| Medium | Duplicate version/policy facts need drift tests. | Pyright pin, Wardline bounds, and cap semantics are drift-prone. |
+
+## Recommended Release Sequence
+
+1. Fix the changelog auth-code mismatch.
+2. Decide whether missing E2E scripts become required jobs or manually
+   documented release gates.
+3. Produce external-operator smoke result artifact.
+4. Run full local CI floor.
+5. Run live GitHub release-governance guard.
+6. Run release workflow dry run from `main`.
+7. Cut tag only after the release commit has full evidence.
+8. Smoke-test public GitHub Release artifacts.
+
+## Evidence Still Needed
+
+- Live GitHub policy output from the governance guard.
+- Full cargo/Python/E2E gate results from the release commit.
+- Release dry-run output.
+- External operator smoke result.
+- Public artifact smoke result after tag.
+
+## Release Decision
+
+Hold tag. Continue RC1 hardening.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/09-test-infrastructure.md b/docs/implementation/arch-analysis-2026-05-20-2124/09-test-infrastructure.md
new file mode 100644
index 00000000..bdb3d4f2
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/09-test-infrastructure.md
@@ -0,0 +1,77 @@
+# RC1 Test Infrastructure
+
+## Test Surface Map
+
+| Area | Coverage Observed |
+|---|---|
+| Rust unit/integration | Workspace crate tests for storage, core host, CLI install/analyze/serve, scanner, MCP storage tools. |
+| Python plugin | Unit tests, subprocess protocol tests, installed-entrypoint smoke, Pyright-marked integration tests, Wardline probe tests. |
+| E2E scripts | Sprint 1 walking skeleton, Sprint 2 MCP surface, Phase 3 subsystems, WP5 secret scan, external operator smoke checklist. |
+| Release/governance | Static workflow/pinning/dependabot checks plus live GitHub policy guard. |
+| Performance | B.8/Phase 3 artifacts, currently directional because temporary corpora are not committed. |
+
+## Strong Coverage
+
+- Storage migrations and query helpers use real SQLite temp databases.
+- Reader-pool tests cover exhaustion queuing, closure SQL errors, panic-to-pool
+  errors, and reuse.
+- Writer actor tests cover schema/run/entity/edge/cache behavior.
+- CLI install tests cover expected files, migration once, overwrite refusal,
+  config preservation, partial cleanup.
+- Analyze tests cover no-plugin success and `core:file:*` row creation.
+- HTTP read API tests cover fixtures, briefing-block non-disclosure, traversal
+  rejection, storage error envelopes, batching, resolve results, auth, limits.
+- Scanner tests cover byte offsets, non-UTF8, baseline suppression, broad
+  high-entropy behavior.
+- MCP tests cover metadata, storage tools, LLM caching/accounting, coalescing,
+  hallucinated targets, Filigree drift/caps.
+- Python plugin tests cover server framing, extraction, Pyright
+  timeout/restart/caps, Wardline import/version states.
+
+## Gaps And Risks
+
+| Gap | Risk | Recommendation |
+|---|---|---|
+| CI/release omit some named E2E scripts. | Release can be green while local release instructions are not fully exercised. | Add missing scripts to CI/release or document as manual gates with dated evidence. |
+| External-operator smoke has no result artifact. | Release checklist cannot be audited from the tree. | Add dated result file. |
+| Fixture plugin emits no edge happy path. | Subprocess edge-ingest path is less directly tested. | Add a fixture mode or second fixture that emits one accepted edge. |
+| Pyright pin duplicated without drift test. | Plugin manifest can diverge from package dependency. | Add package/manifest lockstep test. |
+| Wardline bounds duplicated without drift test. | Optional compatibility reporting can drift. | Add manifest/server constant lockstep test or derive constants. |
+| Core cap semantics ambiguous. | Future plugin breaker behavior may differ from documented expectation. | Add edge-heavy/finding-heavy cap tests. |
+
+## Verification Commands
+
+ADR-023 floor:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --workspace --bins
+cargo nextest run --workspace --all-features
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
+cargo deny check
+```
+
+Python plugin:
+
+```bash
+plugins/python/.venv/bin/ruff check plugins/python
+plugins/python/.venv/bin/ruff format --check plugins/python
+plugins/python/.venv/bin/mypy --strict plugins/python
+plugins/python/.venv/bin/pytest plugins/python
+```
+
+E2E:
+
+```bash
+bash tests/e2e/sprint_1_walking_skeleton.sh
+bash tests/e2e/sprint_2_mcp_surface.sh
+bash tests/e2e/phase3_subsystems.sh
+bash tests/e2e/wp5_secret_scan.sh
+```
+
+## This Analysis Pass
+
+This archaeology pass did not run the full test suite. It inspected source and
+test coverage and then ran documentation-level validation after writing the new
+report set.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/10-dependency-analysis.md b/docs/implementation/arch-analysis-2026-05-20-2124/10-dependency-analysis.md
new file mode 100644
index 00000000..e5d0c9b9
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/10-dependency-analysis.md
@@ -0,0 +1,95 @@
+# RC1 Dependency Analysis
+
+## Internal Dependency Graph
+
+```mermaid
+flowchart LR
+    Core[clarion-core]
+    Storage[clarion-storage]
+    CLI[clarion-cli]
+    MCP[clarion-mcp]
+    Scanner[clarion-scanner]
+    Fixture[clarion-plugin-fixture]
+    Py[plugins/python]
+
+    Storage --> Core
+    CLI --> Core
+    CLI --> Storage
+    CLI --> MCP
+    CLI --> Scanner
+    MCP --> Core
+    MCP --> Storage
+    Fixture --> Core
+    Py -. protocol boundary .-> Core
+```
+
+## Internal Coupling Notes
+
+- `clarion-core` is the contract root. Changes to plugin protocol, entity IDs,
+  resource limits, or LLM provider abstractions can affect most of the
+  workspace.
+- `clarion-storage` depends on core ontology and is consumed by CLI, MCP, and
+  HTTP read paths.
+- `clarion-cli` is the orchestration hub and therefore depends on almost every
+  Rust crate.
+- `clarion-mcp` depends on storage/core and has optional outward coupling to
+  Filigree HTTP.
+- `clarion-scanner` is intentionally small and mostly leaf-like.
+- `plugins/python` is coupled through process protocol and manifest metadata
+  rather than Rust linking.
+
+## External Dependencies By Area
+
+| Area | Key Dependencies | Risk Notes |
+|---|---|---|
+| Async/runtime | `tokio`, `axum`, `tower` | HTTP and serve behavior depend on version-compatible middleware semantics. |
+| SQLite | `rusqlite`, `deadpool-sqlite` | Storage correctness depends on connection pragmas and transaction discipline. |
+| Serialization/config | `serde`, `serde_json`, `serde_norway`, `toml` | Good fit; avoid ad hoc parsing around public contracts. |
+| Graph/clustering | `xgraph` and local clustering code | Determinism/perf need release evidence. |
+| HTTP clients | `reqwest` | Used for OpenRouter and Filigree integration. |
+| Regex/scanning | `regex`, `sha1` | Scanner uses SHA-1 for detect-secrets-compatible hashes, not signing. |
+| Release | GitHub Actions, cosign, SLSA generator | Requires live repository policy alignment. |
+| Python plugin | `pyright==1.1.409`, `packaging` | Pin drift risk between manifest and package metadata. |
+| Optional providers | OpenRouter, Codex CLI, Claude CLI | Live-provider opt-in and usage accounting must remain conservative. |
+| Optional siblings | Filigree, Wardline | Must remain enrich-only integrations. |
+
+## Dependency Risks
+
+### Core/Storage Ontology Drift
+
+Edge/entity ontology changes must stay synchronized across core manifests,
+storage writer validation, schema assumptions, MCP queries, and tests.
+
+### Python Plugin Pin Drift
+
+`plugin.toml` and `pyproject.toml` duplicate the Pyright version. Add a direct
+drift test before release hardening is considered complete.
+
+### Wardline Optional Integration Drift
+
+Wardline bounds are duplicated in plugin manifest and server constants. Because
+Wardline is optional, drift can hide until an operator enables it.
+
+### HMAC Implementation
+
+HTTP auth depends on local code plus `sha2` rather than a dedicated HMAC crate.
+Future edits should be reviewed as security-sensitive.
+
+### Live Provider Accounting
+
+Codex CLI usage parsing can skip malformed JSONL and warn that token totals
+become a lower bound. Token budget enforcement remains useful but may be
+conservative/incomplete when provider telemetry is malformed.
+
+### Release Supply Chain
+
+Static workflow checks are only half the story. Live GitHub policy must match
+the release-governance expectations.
+
+## Dependency Recommendations
+
+1. Keep optional sibling integrations optional and fail-soft.
+2. Add duplicate-fact drift tests for plugin/provider metadata.
+3. Prefer vetted crypto crates for auth primitives when practical.
+4. Treat graph/clustering dependency changes as perf/determinism-sensitive.
+5. Keep release tooling pinned and verify live GitHub policy before tags.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-cli-scanner.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-cli-scanner.md
new file mode 100644
index 00000000..ca22b015
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-cli-scanner.md
@@ -0,0 +1,14 @@
+# Task: Analyze `clarion-cli` and `clarion-scanner`
+
+## Context
+
+- Workspace: `docs/implementation/arch-analysis-2026-05-20-2124/`
+- Branch / commit: `RC1` at `286d92d`
+- Scope: `crates/clarion-cli/`, `crates/clarion-scanner/`, related CLI/scanner tests
+
+## Expected Output
+
+Return two subsystem catalog entries following the `02-subsystem-catalog.md`
+contract exactly, plus quality/security/test/dependency observations focused on
+install/analyze/serve/HTTP-read/secret-scan behavior.
+
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-core-fixture.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-core-fixture.md
new file mode 100644
index 00000000..9b12e6da
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-core-fixture.md
@@ -0,0 +1,24 @@
+# Task: Analyze `clarion-core` and `clarion-plugin-fixture`
+
+## Context
+
+- Workspace: `docs/implementation/arch-analysis-2026-05-20-2124/`
+- Branch / commit: `RC1` at `286d92d`
+- Scope: `crates/clarion-core/`, `crates/clarion-plugin-fixture/`
+
+## Expected Output
+
+Return two subsystem catalog entries following the `02-subsystem-catalog.md`
+contract exactly:
+
+- Subsystem name
+- Location
+- Responsibility
+- Key components
+- Dependencies
+- Patterns observed
+- Concerns
+- Confidence
+
+Also return concise quality/security/test/dependency observations for synthesis.
+
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-mcp.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-mcp.md
new file mode 100644
index 00000000..03d28b64
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-mcp.md
@@ -0,0 +1,14 @@
+# Task: Analyze `clarion-mcp`
+
+## Context
+
+- Workspace: `docs/implementation/arch-analysis-2026-05-20-2124/`
+- Branch / commit: `RC1` at `286d92d`
+- Scope: `crates/clarion-mcp/`, MCP tests
+
+## Expected Output
+
+Return one subsystem catalog entry following the `02-subsystem-catalog.md`
+contract exactly, plus quality/security/test/dependency observations focused on
+LLM provider behavior, token budgets, and Filigree enrichment.
+
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-storage.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-storage.md
new file mode 100644
index 00000000..94a22af3
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-clarion-storage.md
@@ -0,0 +1,13 @@
+# Task: Analyze `clarion-storage`
+
+## Context
+
+- Workspace: `docs/implementation/arch-analysis-2026-05-20-2124/`
+- Branch / commit: `RC1` at `286d92d`
+- Scope: `crates/clarion-storage/`, storage migrations, storage tests
+
+## Expected Output
+
+Return one subsystem catalog entry following the `02-subsystem-catalog.md`
+contract exactly, plus concise quality/security/test/dependency observations.
+
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-python-plugin.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-python-plugin.md
new file mode 100644
index 00000000..6da9f3a2
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-python-plugin.md
@@ -0,0 +1,14 @@
+# Task: Analyze Python Plugin
+
+## Context
+
+- Workspace: `docs/implementation/arch-analysis-2026-05-20-2124/`
+- Branch / commit: `RC1` at `286d92d`
+- Scope: `plugins/python/`
+
+## Expected Output
+
+Return one subsystem catalog entry following the `02-subsystem-catalog.md`
+contract exactly, plus quality/security/test/dependency observations focused on
+pyright, extractor behavior, manifest/version guards, and Wardline probing.
+
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-release-federation-docs.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-release-federation-docs.md
new file mode 100644
index 00000000..95497b07
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/task-release-federation-docs.md
@@ -0,0 +1,15 @@
+# Task: Analyze Release, Federation, And Evidence Infrastructure
+
+## Context
+
+- Workspace: `docs/implementation/arch-analysis-2026-05-20-2124/`
+- Branch / commit: `RC1` at `286d92d`
+- Scope: `docs/clarion/1.0/`, `docs/clarion/adr/`, `docs/federation/`,
+  `docs/operator/`, `.github/workflows/`, `scripts/`, `tests/e2e/`,
+  `tests/perf/`
+
+## Expected Output
+
+Return discovery findings, one subsystem catalog entry following the
+`02-subsystem-catalog.md` contract exactly, and quality/security/test/dependency
+observations grounded in file:line evidence.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-02-subsystem-catalog.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-02-subsystem-catalog.md
new file mode 100644
index 00000000..00421b14
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-02-subsystem-catalog.md
@@ -0,0 +1,24 @@
+# Validation Report: 02-subsystem-catalog.md
+
+**Status:** VALIDATED WITH CAVEATS
+
+## Checks
+
+- Catalog uses the required contract: Location, Responsibility, Key Components,
+  Dependencies, Patterns Observed, Concerns, Confidence.
+- Every major runtime area is represented: core, fixture, storage, CLI,
+  scanner, MCP, Python plugin, release/federation/docs.
+- Findings are sourced from focused subsystem exploration and local repository
+  inspection.
+
+## Caveats
+
+- The catalog is an architecture synthesis, not an exhaustive line-by-line code
+  index.
+- No tests were executed by the subsystem explorers; runtime health claims are
+  based on source/test inspection.
+- Live GitHub policy state was not rechecked during catalog construction.
+
+## Result
+
+Catalog is suitable as the current RC1 code-geography snapshot.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-03-diagrams.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-03-diagrams.md
new file mode 100644
index 00000000..74ec6ed0
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-03-diagrams.md
@@ -0,0 +1,20 @@
+# Validation Report: 03-diagrams.md
+
+**Status:** VALIDATED WITH CAVEATS
+
+## Checks
+
+- Diagrams reflect the current workspace/container split.
+- Analyze, serve/query, storage, trust-boundary, and release-lane flows match
+  the source-level architecture observed by subsystem agents.
+- Diagrams preserve the local-first/federation-enrichment posture.
+
+## Caveats
+
+- Diagrams are intentionally simplified and omit some module-level details.
+- Mermaid syntax was inspected manually in this pass; no external renderer was
+  run.
+
+## Result
+
+Diagrams are fit for architecture handoff and review.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-04-final-report.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-04-final-report.md
new file mode 100644
index 00000000..81f4ba46
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-04-final-report.md
@@ -0,0 +1,23 @@
+# Validation Report: 04-final-report.md
+
+**Status:** VALIDATED WITH CAVEATS
+
+## Checks
+
+- Executive verdict matches the discovered evidence: architecturally coherent,
+  not release-ready until governance/gate evidence is complete.
+- Priority risks are traceable to subsystem exploration findings.
+- Recommendations are bounded and do not invent new cross-product coupling.
+- The report supersedes, rather than preserves, the removed 2026-05-18
+  analysis snapshot.
+
+## Caveats
+
+- Full CI, live GitHub policy checks, and external operator smoke were not run
+  in this archaeology pass.
+- Release-readiness claims should be refreshed after live governance and CI
+  evidence is collected.
+
+## Result
+
+Final report is suitable as the current RC1 architecture assessment.
diff --git a/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-option-g.md b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-option-g.md
new file mode 100644
index 00000000..9398d3b5
--- /dev/null
+++ b/docs/implementation/arch-analysis-2026-05-20-2124/temp/validation-option-g.md
@@ -0,0 +1,33 @@
+# Validation Report: Option G Deliverable Set
+
+**Status:** COMPLETE WITH RELEASE-READINESS CAVEATS
+
+## Deliverables Present
+
+- `00-coordination.md`
+- `01-discovery-findings.md`
+- `02-subsystem-catalog.md`
+- `03-diagrams.md`
+- `04-final-report.md`
+- `05-quality-assessment.md`
+- `06-architect-handover.md`
+- `07-security-surface.md`
+- `08-release-readiness.md`
+- `09-test-infrastructure.md`
+- `10-dependency-analysis.md`
+
+## Validation Notes
+
+- The old 2026-05-18 architecture analysis directory was removed.
+- The new analysis is anchored on `RC1` at `286d92d`.
+- Six focused subsystem exploration agents supplied the source-grounded
+  findings.
+- The synthesis distinguishes code architecture readiness from release-policy
+  readiness.
+
+## Caveats
+
+- This is a read/source analysis plus documentation validation pass, not a full
+  CI execution pass.
+- Live GitHub governance was not checked here and remains a release-critical
+  external-state gate.
diff --git a/docs/implementation/clarion-dogfood-eval-2026-05-29.md b/docs/implementation/clarion-dogfood-eval-2026-05-29.md
new file mode 100644
index 00000000..4c7f712f
--- /dev/null
+++ b/docs/implementation/clarion-dogfood-eval-2026-05-29.md
@@ -0,0 +1,277 @@
+# Clarion dogfood evaluation — senior-user verdict (2026-05-29)
+
+Evaluator: senior engineer, day-one orientation via the 8 MCP query tools only.
+Read-only. Every claim below is cited to an actual MCP call or a source `Read`.
+
+> **Corpus caveat (this is Finding #1, read it first).** The live MCP server is
+> **not** serving the 425k-LOC elspeth the brief described. It is serving Clarion's
+> own repo DB (`/home/john/clarion/.clarion/clarion.db`, 1872 entities), which
+> swept together the `elspeth_mini` test fixture (`tests/perf/elspeth_mini/…`,
+> ~30k LOC / 80 files), Clarion's *own* plugin source, and a `.env` file. The
+> real elspeth DB (36,814 entities, 134 subsystems, 259 MB) exists at
+> `/home/john/elspeth/.clarion/clarion.db` but the served tools cannot reach it.
+> I evaluated the tool surface against what is actually served, per the only
+> substrate the 8 tools expose. Clustering/scale findings are therefore partly
+> corpus-dependent and flagged as such; tool-mechanic findings hold regardless.
+
+> **Maintainer reconciliation (added post-run, evidence-verified).** The corpus
+> mismatch above is an *operational staging artifact*, not a Clarion
+> analysis-scoping defect — and the way it happened is itself a finding. The MCP
+> server's configured DB path had been wiped from `/tmp`; the DB was restored by
+> `rm` + sqlite `.backup` (a **new inode**) while the server was still running.
+> The server held a pooled connection to the **old, now-unlinked inode** (a
+> Clarion self-analysis DB) and silently kept serving it. On-disk the path now
+> holds a clean, properly-scoped **real elspeth** snapshot (36,680 elspeth
+> entities + 134 subsystems, 0 fixture/clarion rows — verified by direct
+> `sqlite3`), but the live tools never saw it. So:
+> - **Finding #5 ("corpus contamination / analysis had no scoping") is withdrawn**
+>   as a Clarion bug — the real elspeth analysis *is* scoped correctly; the wrong
+>   DB was simply served. It is re-cast as: *a running `serve` keeps serving a
+>   deleted DB inode with no detection* (minor robustness note) + further proof of
+>   the provenance gap (Finding #1).
+> - **Findings #2 (`entity_at` root mismatch) and the subsystem-quality /
+>   modularity-0.093 verdict are corpus-contaminated** and need re-test against
+>   the real-elspeth DB (proper `project_root=/home/john/elspeth`, 134 real
+>   subsystems) before they can be pinned on the tool. Re-run requires an MCP/
+>   session restart so the server opens the fresh inode.
+> - **Everything else holds corpus-independently** and is the real harvest:
+>   `execution_paths_from` token blob, `summary` billing-on-failure + no
+>   structural fallback, invisible incompleteness (`scope_excludes`),
+>   attribute-receiver caller blind spot, and the missing-capability wishlist
+>   (`project_status`, `list_subsystems`, module-altitude/upstream-import queries,
+>   aggregating summaries).
+> - **Finding #1 (provenance) is the headline and is now doubly validated:** a
+>   careful evaluating agent *and* the operator both lost track of which corpus was
+>   live. If a `project_status` tool existed, neither would have.
+
+---
+
+## 1. TL;DR
+
+The leaf-`summary` tool is genuinely good — its checkpoint-module briefing was
+accurate, well-structured, and saved me a real read. But as a day-one
+orientation surface the tool is **not yet trustworthy**, for three reasons I hit
+within the first ten calls: (1) I could not tell *what corpus I was even
+querying* from inside the tool surface — I had to drop to `sqlite3` to discover
+the server is pointed at a fixture, not elspeth; (2) the graph is *accurate
+where it claims an edge* (verified: 11 real callers of `_emit_telemetry`,
+class-to-class reference edges on `ResumePoint`) but has hard **scope blind
+spots** — attribute-receiver method calls (`ctx.orchestrator.resume()`) are
+invisible at every confidence level, and references live only at symbol
+granularity so module-level "who imports me" answers `[]` — and *nothing in the
+output tells the agent it's looking at a blind spot rather than a true negative*;
+(3) `entity_at` is
+**dead** on this DB and `execution_paths_from` **blows the token cap** with a
+128 KB dump the consult-agent never receives. Would I reach for it again? For
+single-entity summaries, yes. For blast-radius or flow questions, not until the
+edge graph and a `project_status` are real. **The single biggest thing it needs:
+a `project_status`/provenance tool so an agent knows what it's looking at and
+whether to trust it.**
+
+---
+
+## 2. Missions run
+
+### Mission A — "Where does checkpointing live and how does it hang together?"
+- **Chain:** `find_entity("checkpoint")` → `summary(contracts.checkpoint)` →
+  `neighborhood(contracts.checkpoint)` → `subsystem_members` on both hash-named
+  subsystems.
+- **Succeeded partially.** `summary` was the win: it correctly described
+  `ResumeCheck`/`ResumePoint`, named the real collaborators
+  (`RecoveryManager`, `CheckpointCompatibilityValidator`, `Orchestrator.resume`),
+  and even flagged a real redundancy risk (token_id/node_id duplicated between
+  `ResumePoint` and the embedded `Checkpoint`). I verified all of that against
+  `contracts/checkpoint.py` — accurate.
+- **Fell back to grep for upstream "who imports checkpoint."** `neighborhood`
+  on the *module* reported `references_in: []` / `references_out: []`, reading as
+  "nothing imports checkpoint." But this is a **granularity** effect, not a
+  dropped edge: re-querying `neighborhood(class ResumePoint)` shows references
+  ARE tracked symbol-to-symbol — `references_out` lists `audit.Checkpoint`,
+  `AggregationCheckpointState`, `CoalesceCheckpointState` (all `resolved`, with
+  byte offsets), matching source. So downstream wiring is queryable per-class.
+  What's missing is (a) a *module rollup* of contained-symbol references, and
+  (b) the upstream direction — `contracts/__init__.py:69 from … import
+  ResumeCheck, ResumePoint` did not appear as a `references_in` on the
+  `ResumePoint` class either, so "who imports this contract" still required
+  `grep -rn`.
+- **Subsystem layer was useless for orientation.** `subsystem_members` works
+  mechanically, but the two clusters it returned lump Clarion's own
+  `clarion_plugin_python.extractor`/`server`/`stdout_guard` in *with* elspeth
+  contracts modules (modularity_score `0.093` — near-random). Names are opaque
+  hashes (`Subsystem 9d59f183f130`). "What subsystem owns checkpointing?" had
+  no meaningful answer.
+
+### Mission B — "If I change `Orchestrator.resume`, what breaks?"
+- **Chain:** `find_entity("Orchestrator")` → `callers_of(Orchestrator.resume)`
+  at `resolved` then `ambiguous` → cross-check with grep.
+- **Failed for this entity — but the tool itself works.** `callers_of(resume)`
+  returned `{"callers":[]}` at **both** `resolved` and `ambiguous`. Source has a
+  real caller: `cli.py:1548: return ctx.orchestrator.resume(...)`. I verified
+  `callers_of` is *not* broken by running a reverse-edge consistency check:
+  `callers_of(_emit_telemetry)` returned **11 real callers** (`run`, `resume`,
+  `_emit_failed_ceremony`, `_execute_export_phase`, …), all `resolved` with byte
+  offsets, every one confirmed in source. So direct `self.`-calls resolve
+  correctly; the `resume` miss is purely the **attribute-receiver** limitation —
+  `ctx.orchestrator.resume()` can't be bound to the class statically, and even
+  `ambiguous` doesn't surface it as a candidate. A senior asking "blast radius"
+  still got the dangerous answer "nothing calls this," and *nothing flagged that
+  this was a known-incomplete case rather than a true negative*. I got the real
+  answer from grep.
+
+### Mission C — "How does a run flow through the system?"
+- **Chain:** `execution_paths_from(Orchestrator.run, max_depth=4)` → verify
+  against `core.py`.
+- **Data correct, delivery broken.** The 71 paths it computed are *real*: `run
+  → _emit_failed_ceremony → _emit_telemetry`, `run → _delete_checkpoints`,
+  `run → derive_terminal_run_status`, etc. — all confirmed in
+  `core.py` lines 1471–1701. So the intra-class `self.`-call graph is accurate
+  and the flow is genuinely informative. **But** the response was 124,036 chars
+  on one line, exceeded the MCP token cap, and got dumped to a file the consult
+  agent cannot ingest. `truncated:false` — it didn't even hit its own edge cap;
+  it just serialized 52 distinct nodes fully re-expanded across 71 overlapping
+  paths. The one tool that answers my favourite orientation question is the one
+  whose output I literally cannot receive in-band.
+
+---
+
+## 3. Per-tool notes
+
+| Tool | What it's for | Delivered? | Friction (cited) |
+|---|---|---|---|
+| `find_entity` | FTS search over entity rows | **Yes** | Clean, paginates correctly (`cursor:"10"` → `next_cursor:"13"`). But `find_entity("subsystem")` returned only the 2 *hash*-named subsystems; the 2 namespace-named ones (`tests.perf`, `tests.perf.elspeth_mini.elspeth`, confirmed via sqlite) are invisible — subsystems aren't reliably discoverable through search. |
+| `summary` | On-demand leaf briefing | **Mostly** | Best tool here: `summary(contracts.checkpoint)` was accurate + high-signal. But `summary(Orchestrator class)` failed **twice** with `llm-invalid-json` and **charged $0.0152 each time** (~$0.03 burned, nothing cached, no fallback). Large entities silently exceed the prompt budget and return prose, not JSON. |
+| `entity_at` | file+line → innermost entity | **No (broken)** | Every call errors. DB normalizes paths against a dead root `/tmp/clarion-b8-elspeth-full-20260518T0016Z`; the real on-disk absolute path is rejected as "escapes project root," and the relative path errors `No such file or directory`. Unusable on this DB. |
+| `neighborhood` | one-hop callers/callees/refs | **Partial** | `contained` correct. References are tracked at **symbol granularity** (`neighborhood(ResumePoint).references_out` correctly lists `audit.Checkpoint` etc.), but the **module** entity rolls up nothing (`references_in/out: []`), and **upstream** import edges (`who imports ResumePoint`) don't appear as `references_in` on the class either. So downstream-per-class works; module rollup and upstream don't. |
+| `callers_of` | reverse call edges | **Works for direct calls** | Verified true-positive: `callers_of(_emit_telemetry)` → **11 real `resolved` callers** with byte offsets, all confirmed in source. Returns `[]` for attribute-receiver calls (`ctx.orchestrator.resume()` from `cli.py:1548`) at both confidences — a documented scope limit, not a bug — but the empty answer reads as "safe to change" with no flag that it's incomplete. |
+| `subsystem_members` | modules in a subsystem | **Mechanically yes** | Works, but the clusters are near-random (modularity 0.093) and mix Clarion's own source with the fixture. Names are opaque hashes. Low orientation value here — likely corpus-contamination, not pure tool fault. |
+| `execution_paths_from` | bounded calls-only paths | **Data yes, delivery no** | Paths are accurate and useful, but 128 KB / one line / over the token cap → dumped to a file. Format re-serializes every node in full per path. See Mission C. |
+| `issues_for` | Filigree issues on an entity | **Graceful** | Filigree was down; returned a clean `available:false` / `filigree-unreachable` envelope without failing Clarion — exactly the enrich-only degradation the description promises. Could not exercise the populated path. |
+
+---
+
+## 4. Findings, categorized
+
+### Friction (works but painful, most painful first)
+1. **`execution_paths_from` output is unusable by an LLM consumer.** 71 paths,
+   52 nodes, fully re-serialized → 128 KB over the token cap. The data is right;
+   the shape defeats the entire "don't make the agent re-explore" thesis. A
+   node-table + edge-list (each node once) would be a small fraction of this.
+2. **`summary` charges money on hard failures and offers no fallback for big
+   entities.** Two `llm-invalid-json` failures on the Orchestrator class, ~$0.03
+   gone, no cache write, no degraded "here are the members" fallback. A consult
+   agent will retry-and-pay in a loop.
+3. **Confidence levels don't visibly change anything for the failure cases I
+   hit.** `ambiguous` returned identical bytes to `resolved` for both
+   `neighborhood` and `callers_of`. If the higher tier can't surface the
+   unresolved `ctx.orchestrator.resume()` candidate, it's not earning its
+   opt-in cost.
+4. **Opaque subsystem names.** `Subsystem 9d59f183f130` tells a human nothing;
+   I can't decide whether a cluster is worth opening without a label or a
+   one-line synthesized description.
+
+### Missing (capabilities a senior user needs that don't exist, ranked)
+1. **`project_status` / provenance.** I could not learn from *any* tool: what
+   corpus is served, how many entities, when analyzed, what project root,
+   whether the source still matches the DB. I had to use `sqlite3`/`find` to
+   discover I was querying a fixture, not elspeth. A blind consult agent would
+   have been silently misled. **This is the headline gap.**
+2. **A way to enumerate subsystems.** There is no "list all subsystems" tool;
+   `find_entity("subsystem")` is FTS and misses the namespace-named ones. The
+   top-down "give me the map" entry point — the most natural day-one move —
+   doesn't exist.
+3. **Module-level reference rollup + an upstream "who imports this" query.**
+   References exist symbol-to-symbol, but "who depends on this module/contract?"
+   — the core archaeology question — answers `[]` because module entities don't
+   aggregate their symbols' edges and there's no reverse-import lookup. A senior
+   thinks in modules first; the data is there but not queryable at that altitude.
+4. **Aggregating (non-leaf) summaries.** `summary` is explicitly leaf-scope, so
+   there is no "summarize this subsystem / this package" — the altitude at which
+   a senior actually starts.
+5. **Ranked blast-radius, not raw caller lists.** Even when `callers_of` works,
+   I want "N callers, here are the load-bearing ones," not an unordered dump.
+
+### Pointless (earned no value in real use — with justification)
+- **`subsystem_members` (on this corpus only).** I read its intent — map modules
+  to Leiden clusters so an agent can reason at subsystem altitude — and used it
+  in earnest on both clusters. With modularity 0.093 and Clarion's own source
+  mixed into the elspeth fixture, the clusters carry no real architectural
+  signal, so it earned nothing *here*. I attribute this to corpus
+  contamination + 30k-LOC scale, not to the tool's design; on a clean 425k-LOC
+  run it could be the most valuable tool. **Not pointless by design — pointless
+  on this data.**
+- I found **no tool that is pointless by design.** Each of the 8 has a clear,
+  defensible reason to exist; the failures above are correctness/economy/
+  provenance gaps, not redundant features.
+
+---
+
+## 5. What I need from Clarion (prioritized wishlist to the maintainer)
+
+1. **Ship `project_status` (new tool).** Return: served DB path, entity counts
+   by kind, subsystem count, analyzed-at timestamp, project root, and a
+   staleness/drift flag (does source still match `content_hash`?). Without this
+   an agent cannot calibrate trust, and I cannot tell a fixture from production.
+2. **Re-shape `execution_paths_from` (and any multi-node response) for token
+   economy.** Emit each node **once** in a `nodes` table keyed by id, then
+   `paths` as arrays of ids (or an adjacency list + a separate `roots`/`leaves`
+   set). Drop `content_hash` and absolute `source_file_path` from path nodes;
+   keep `id` + `short_name` + line span. Target: the `run` flow should fit in a
+   few KB, not 128 KB.
+3. **Make `entity_at` resilient to a moved/renamed project root.** Normalize
+   against the *stored absolute `source_file_path`s*, not a dead tmp root; or
+   expose the root in `project_status` so callers know what prefix to pass.
+   Right now it's 100% dead on this DB.
+4. **Make incompleteness visible, and widen two scope gaps.** (a) Every `[]`
+   result from `callers_of`/`neighborhood` should carry a `scope_excludes` note
+   (e.g. "attribute-receiver calls excluded", "no module-level rollup") so an
+   agent never reads "incomplete" as "none". (b) `callers_of(...,"ambiguous")`
+   should surface attribute-receiver candidates like `ctx.orchestrator.resume()`.
+   (c) Add module-level reference rollup + a reverse-import lookup. An empty set
+   that's silently incomplete is worse than no answer.
+5. **Make `summary` fail cheap and degrade.** Cap input by chunking large
+   entities; on `llm-invalid-json`, fall back to a structural summary (members,
+   signatures, docstring) instead of charging and returning an error. Never bill
+   twice for a deterministic failure.
+6. **Human-readable subsystem labels + a one-line cluster gist**, and a
+   `list_subsystems` enumerator so top-down orientation has an entry point.
+
+---
+
+## 6. Bugs / correctness issues (with evidence)
+
+1. **Silent, unflagged false-negatives from documented scope limits (UX bug,
+   not a graph bug).** I confirmed the graph is *correct where it answers*:
+   `callers_of(_emit_telemetry)` → 11 verified callers; `neighborhood(ResumePoint)`
+   → correct class-to-class reference edges. The problem is that the two
+   *incomplete* cases return a clean empty result indistinguishable from a true
+   negative:
+   - `callers_of(Orchestrator.resume)` = `{"callers":[]}` (attribute receiver
+     `ctx.orchestrator.resume()`, `cli.py:1548` — unresolvable statically).
+   - `neighborhood(contracts.checkpoint).references_in` = `[]` (module rollup not
+     implemented; the import `contracts/__init__.py:69` isn't surfaced upstream
+     even on the class).
+   Neither is a dropped edge — both are known v0.1 scope. The bug is that the
+   response carries **no signal** ("excludes attribute-receiver calls" /
+   "no module-level reference rollup") to stop a consult agent from reading `[]`
+   as "safe to change / nothing depends on this."
+2. **`entity_at` is broken by a stale project root baked into the DB.**
+   Error: `escapes project root /tmp/clarion-b8-elspeth-full-20260518T0016Z`
+   for the very absolute path the entity rows store
+   (`/home/john/clarion/tests/perf/.../core.py`). The DB's normalization root
+   and its stored `source_file_path`s are mutually inconsistent — an internal
+   data bug, independent of corpus choice.
+3. **`summary` bills on deterministic failure.** Two identical
+   `llm-invalid-json` errors on the Orchestrator class, `summary_cost_usd`
+   `0.015225` each in `stats_delta`, no cache entry written. Same input → same
+   paid failure on every retry.
+4. **`execution_paths_from` exceeds its transport budget without setting
+   `truncated`.** 124,036-char response, `truncated:false`,
+   `truncation_reason:null` — so the truncation contract the description
+   advertises ("responses say when they are truncated") didn't fire; the MCP
+   layer truncated it instead, out of band.
+5. **Corpus contamination (provenance bug).** The served DB analyzed Clarion's
+   own repo — `/home/john/clarion/.env`,
+   `clarion_plugin_python/__init__.py`, `server.py` — and lumped them into
+   subsystems with the elspeth_mini fixture. The analysis run had no scoping to
+   the intended corpus. (Evidence: `sqlite3 … select source_file_path …` and the
+   mixed `subsystem_members` output.)
diff --git a/docs/implementation/clarion-dogfood-remediation-2026-05-29.md b/docs/implementation/clarion-dogfood-remediation-2026-05-29.md
new file mode 100644
index 00000000..d7d99568
--- /dev/null
+++ b/docs/implementation/clarion-dogfood-remediation-2026-05-29.md
@@ -0,0 +1,171 @@
+# Clarion dogfood — remediation plan (2026-05-29)
+
+Companion to [`clarion-dogfood-eval-2026-05-29.md`](clarion-dogfood-eval-2026-05-29.md).
+Maps each confirmed finding to a fix and an owner ticket. Most findings were
+*already anticipated* by the dogfood epic **clarion-8fe3060d4c** (31 children);
+this plan records which tickets cover what, what's genuinely new, and what was
+a test-harness artifact rather than a Clarion defect.
+
+## Status legend
+- **DONE** — already fixed in HEAD (verify after the served binary is rebuilt).
+- **TICKETED** — an existing Filigree issue covers it; may need scope tightening.
+- **GAP** — no ticket yet; file one (proposed below).
+- **ARTIFACT** — caused by the eval staging, not Clarion; re-test, don't fix.
+
+---
+
+## A. Already resolved in HEAD (rebuild + restart to expose)
+
+### A1. Provenance / `project_status` — **DONE** (Finding #1, the headline)
+- **Commit:** `5d4aeaa feat(mcp): add project_status diagnostics tool + live Filigree URL resolution`. Ticket **clarion-084e82250c** (status: building).
+- Returns repo root, db path, latest run (id/status/started/completed), entity/
+  subsystem/edge/finding counts, index staleness, per-plugin entity counts, LLM
+  policy (provider/live/cache), and the **resolved** Filigree endpoint. No LLM call.
+- **Why the agent missed it:** the live MCP server was the pre-`5d4aeaa` binary, so
+  the tool wasn't in the registered list — the exact blindness `project_status`
+  exists to cure. **Action:** rebuild `target/release/clarion`, restart MCP,
+  re-verify; then close clarion-084e82250c.
+- **Bonus:** the same commit single-sources Filigree URL resolution at the
+  `FiligreeHttpClient` construction site, fixing the stale-port path that made
+  `issues_for` unreachable in the eval. Feeds clarion-318f1254eb.
+
+---
+
+## B. Confirmed, corpus-independent — fix these (ranked by user pain)
+
+### B1. `execution_paths_from` output unusable by an LLM consumer — **TICKETED**
+- **Finding:** 71 *correct* paths returned as a 124 KB single-line blob (every
+  node fully re-serialized per path), over the MCP cap, dumped to a file the
+  consult agent never receives. The one tool that answers "how does this flow"
+  is the one whose output can't be ingested.
+- **Ticket:** **clarion-5b3eff9a91** "Add compact ranked execution paths mode" (P2, proposed).
+- **Fix:** emit a `nodes` table keyed by id (each node **once**: `id` +
+  `short_name` + line span only — drop `content_hash` and absolute
+  `source_file_path`), then `paths` as arrays of node-ids (or an adjacency list +
+  `roots`/`leaves`). Add the "ranked" half so the top load-bearing paths come
+  first under the cap. Target: the `run` flow fits in a few KB.
+- **Scope add:** while here, make truncation honest — see B5.
+
+### B2. `summary` bills on deterministic failure, no structural fallback — **GAP**
+- **Finding:** `summary(Orchestrator class)` failed twice with `llm-invalid-json`,
+  charged `summary_cost_usd 0.015225` **each** (`stats_delta`), wrote no cache
+  entry. Same input → same paid failure on every retry; a consult agent loops and
+  pays. Distinct from clarion-bacd53a2ad (`summary_preview_cost`), which only
+  estimates *before* a call and does nothing for the fail-and-bill loop.
+- **Ticket:** none for the fail-cheap behavior. **File a P2 bug** (proposed title:
+  *"summary bills on llm-invalid-json with no cache + no structural fallback"*).
+- **Fix:** (a) on `llm-invalid-json`, fall back to a deterministic **structural**
+  summary (members, signatures, docstring) instead of returning an error — this is
+  also strictly better output; (b) cap/chunk oversized entities before the LLM
+  call so the prompt-budget overflow that causes the invalid JSON can't happen;
+  (c) never bill twice for an identical deterministic failure (negative-cache the
+  failure, or don't bill a non-result). Related but not a substitute:
+  clarion-bacd53a2ad (preview), clarion-bacd…/spend controls are out of the epic's
+  deterministic scope per the epic note.
+
+### B3. Incompleteness is invisible (`[]` reads as "none") — **PARTIALLY TICKETED → GAP**
+- **Finding:** `callers_of`/`neighborhood` return a clean `[]` for *known* scope
+  limits — attribute-receiver calls (`ctx.orchestrator.resume()`, `cli.py:1548`)
+  and module-level reference rollup — indistinguishable from a true negative. A
+  senior reads "nothing calls this → safe to change." Verified the graph is
+  *correct where it answers* (11 real `_emit_telemetry` callers; correct
+  `ResumePoint` reference edges), so this is a **UX/contract bug, not a graph bug**.
+- **Tickets touching the area:** clarion-9392f74881 (call_sites evidence),
+  clarion-893c46cc5f (clarion://context degraded-snapshot signal). Neither adds a
+  per-result `scope_excludes` flag.
+- **Fix (file a P2):** every `callers_of`/`neighborhood`/`execution_paths_from`
+  result carries a `scope_excludes: [...]` array naming what was *not* searched
+  (e.g. `"attribute-receiver-calls"`, `"module-level-reference-rollup"`,
+  `"cross-module-imports"`). An empty set that's silently incomplete is worse than
+  no answer. Cheap, high-leverage, corpus-independent.
+
+### B4. No module-altitude / upstream-import queries — **TICKETED**
+- **Finding:** references exist symbol-to-symbol, but "who imports this
+  module/contract?" answers `[]` because module entities don't aggregate their
+  symbols' edges and there's no reverse-import lookup. A senior thinks in modules
+  first.
+- **Tickets:** **clarion-923cf62b2c** "No module->subsystem reverse lookup" (P2)
+  covers the subsystem direction; the **module reference rollup + reverse-import**
+  query is adjacent and may need its own scope line on clarion-9392f74881 or a new
+  child. **Action:** confirm coverage on clarion-923cf62b2c; if it's subsystem-only,
+  add a sibling for module-level reference rollup.
+
+### B5. `execution_paths_from` exceeds transport budget without `truncated:true` — **GAP**
+- **Finding:** 124,036-char response with `truncated:false` / `truncation_reason:null`
+  — the truncation contract the tool description advertises didn't fire; the MCP
+  layer truncated out-of-band. Whatever B1 lands, the truncation signal must be
+  honest. **File as part of clarion-5b3eff9a91** (acceptance criterion: any response
+  trimmed for the cap sets `truncated` + `truncation_reason`).
+
+### B6. Subsystem discoverability & labels — **MOSTLY TICKETED**
+- **Findings:** no "list all subsystems" entry point (`find_entity("subsystem")` is
+  FTS and misses namespace-named clusters); opaque hash names
+  (`Subsystem 9d59f183f130`).
+- **Tickets:** **clarion-aaa25a4f10** "Improve subsystem name UX: derive from common
+  module prefix" is **closed** — verify the served binary actually carries it
+  (eval still saw hash names, but on the contaminated corpus). **clarion-bccfcd4c49**
+  "find_entity has no kind filter" partly helps discovery. **Gap:** an explicit
+  `list_subsystems` enumerator — fold into clarion-599a34d40a (orientation_pack) or
+  file a small P2.
+
+### B7. Aggregating (non-leaf) summaries — **DESIGN-DEFERRED**
+- **Finding:** `summary` is leaf-scope by design (v0.1), so there's no
+  "summarize this subsystem/package" — the altitude a senior starts at.
+- **Action:** not a bug; a roadmap item. Track under clarion-599a34d40a
+  (orientation_pack) or a dedicated post-1.0 feature; note the dependency on
+  subsystem labels (B6) and module rollup (B4).
+
+---
+
+## C. Needs re-test on the real corpus (contaminated by the eval staging)
+
+### C1. `entity_at` "dead" — **ARTIFACT + likely-real fragility, RE-TEST**
+- **Eval saw:** every call errored — input path "escapes project root
+  `/tmp/clarion-b8-elspeth-full-…`" while the DB stored
+  `/home/john/clarion/tests/perf/.../core.py`. That `/tmp` root was the eval's dead
+  `serve --config` project_root, **not** a property of a correctly-served instance.
+- **Re-test** with `--path /home/john/elspeth` (project_root matches the stored
+  `/home/john/elspeth/...` paths). If it still rejects valid in-tree paths, it's a
+  real normalization bug → file against clarion-460def6a51's area. Until re-tested,
+  do not pin "100% broken" on the tool.
+
+### C2. Subsystem clustering quality (modularity 0.093) — **ARTIFACT, RE-TEST**
+- **Eval saw** near-random clusters mixing Clarion's own source with the
+  `elspeth_mini` fixture — because the served DB was Clarion's 1872-entity
+  self-analysis, not elspeth. Real elspeth has **134** subsystems over 36,814
+  entities. Re-run subsystem missions there before judging cluster quality.
+
+### C3. "Corpus contamination / analysis had no scoping" — **WITHDRAWN (ARTIFACT)**
+- Not a Clarion bug. The real elspeth analysis is correctly scoped (verified:
+  36,680 elspeth entities, 0 fixture/clarion rows). The wrong DB was *served*, via
+  the staging artifact below. Remove from the bug list.
+
+### C4. `serve` keeps serving a deleted DB inode — **MINOR ROBUSTNESS, OPTIONAL**
+- **Root cause of the whole corpus mix-up:** the configured DB was hot-swapped
+  (`rm` + sqlite `.backup` → new inode) under a running server; the connection pool
+  held the old, now-unlinked inode and silently kept serving it. Normal operation
+  restarts `serve`, so this is low priority — but a periodic `stat`/`PRAGMA
+  data_version` check (or surfacing inode/db identity in `project_status`) would let
+  an agent notice. **Optional P3**; `project_status` (A1) already mitigates by making
+  the served corpus inspectable.
+
+---
+
+## D. Execution order
+
+1. **Rebuild + restart MCP**, then re-verify A1 (`project_status`) and close
+   clarion-084e82250c. (Unblocks honest re-testing of everything else.)
+2. **B3 + B5** — `scope_excludes` + honest truncation. Small, corpus-independent,
+   highest trust-per-line-of-code. (B5 rides clarion-5b3eff9a91; B3 = new P2.)
+3. **B1** — compact ranked execution paths (clarion-5b3eff9a91).
+4. **B2** — summary fail-cheap + structural fallback (new P2 bug).
+5. **C1/C2** re-test on `--path /home/john/elspeth`; convert survivors to bugs.
+6. **B4/B6/B7** — module-altitude queries, `list_subsystems`, aggregating summaries
+   (roadmap; partly under clarion-923cf62b2c / clarion-599a34d40a).
+
+## E. New tickets to file (gaps with no current owner)
+- **P2 bug:** summary bills on `llm-invalid-json`, no cache, no structural fallback (B2).
+- **P2 feature:** `scope_excludes` on every graph-query result (B3).
+- **P3 task:** honest `truncated` flag on capped `execution_paths_from` (B5; or AC on clarion-5b3eff9a91).
+- **P2 (if not covered):** module-level reference rollup + reverse-import query (B4).
+- **P3 (optional):** `serve` detects a swapped/deleted DB (C4).
diff --git a/docs/superpowers/handoffs/2026-04-18-wp2-plugin-host-handoff.md b/docs/implementation/handoffs/2026-04-18-wp2-plugin-host-handoff.md
similarity index 100%
rename from docs/superpowers/handoffs/2026-04-18-wp2-plugin-host-handoff.md
rename to docs/implementation/handoffs/2026-04-18-wp2-plugin-host-handoff.md
diff --git a/docs/superpowers/handoffs/2026-04-19-wp2-tasks-4-to-9-handoff.md b/docs/implementation/handoffs/2026-04-19-wp2-tasks-4-to-9-handoff.md
similarity index 100%
rename from docs/superpowers/handoffs/2026-04-19-wp2-tasks-4-to-9-handoff.md
rename to docs/implementation/handoffs/2026-04-19-wp2-tasks-4-to-9-handoff.md
diff --git a/docs/superpowers/handoffs/2026-04-23-wp2-full-scrub-handoff.md b/docs/implementation/handoffs/2026-04-23-wp2-full-scrub-handoff.md
similarity index 98%
rename from docs/superpowers/handoffs/2026-04-23-wp2-full-scrub-handoff.md
rename to docs/implementation/handoffs/2026-04-23-wp2-full-scrub-handoff.md
index c2f541ab..395f8ec7 100644
--- a/docs/superpowers/handoffs/2026-04-23-wp2-full-scrub-handoff.md
+++ b/docs/implementation/handoffs/2026-04-23-wp2-full-scrub-handoff.md
@@ -80,9 +80,9 @@ Anchoring documents to read-with:
 - `docs/clarion/adr/ADR-021-plugin-authority-hybrid.md`
 - `docs/clarion/adr/ADR-022-core-plugin-ontology.md`
 - `docs/clarion/adr/ADR-023-tooling-baseline.md`
-- `docs/clarion/v0.1/requirements.md` — REQ / NFR / CON IDs WP2 addresses
-- `docs/clarion/v0.1/system-design.md` §§4–6 (host, plugin protocol, limits)
-- `docs/clarion/v0.1/detailed-design.md` §§4–5 (wire schemas, rule catalogues)
+- `docs/clarion/1.0/requirements.md` — REQ / NFR / CON IDs WP2 addresses
+- `docs/clarion/1.0/system-design.md` §§4–6 (host, plugin protocol, limits)
+- `docs/clarion/1.0/detailed-design.md` §§4–5 (wire schemas, rule catalogues)
 
 ## Open WP2 review-2 tail at session start
 
diff --git a/docs/superpowers/handoffs/2026-04-23-wp2-scrub-findings.md b/docs/implementation/handoffs/2026-04-23-wp2-scrub-findings.md
similarity index 100%
rename from docs/superpowers/handoffs/2026-04-23-wp2-scrub-findings.md
rename to docs/implementation/handoffs/2026-04-23-wp2-scrub-findings.md
diff --git a/docs/superpowers/handoffs/2026-04-24-post-wp2-scrub-handoff.md b/docs/implementation/handoffs/2026-04-24-post-wp2-scrub-handoff.md
similarity index 98%
rename from docs/superpowers/handoffs/2026-04-24-post-wp2-scrub-handoff.md
rename to docs/implementation/handoffs/2026-04-24-post-wp2-scrub-handoff.md
index 4a29f59f..e16f4247 100644
--- a/docs/superpowers/handoffs/2026-04-24-post-wp2-scrub-handoff.md
+++ b/docs/implementation/handoffs/2026-04-24-post-wp2-scrub-handoff.md
@@ -168,7 +168,7 @@ This is the bigger slice. WP3 builds an editable Python package at
 lock-ins:
 
 - **L7**: qualname reconstruction per
-  `docs/clarion/v0.1/detailed-design.md §§4–5` (module-level, nested,
+  `docs/clarion/1.0/detailed-design.md §§4–5` (module-level, nested,
   class, async, nested-class). Shared test fixture at
   `/fixtures/entity_id.json` must pass byte-for-byte in both Rust and
   Python — this is the L2+L7 alignment proof (A.3.4).
@@ -269,8 +269,8 @@ The scrub changed several surfaces that WP3 will touch:
 - `docs/clarion/adr/ADR-007-summary-cache-keying.md` — you'll produce
   `ontology_version` but not consume it yet
 - `docs/clarion/adr/ADR-023-tooling-baseline.md` — Python tooling gates
-- `docs/clarion/v0.1/detailed-design.md §§4–5` — qualname rules
-- `docs/clarion/v0.1/requirements.md` — REQ-/NFR- IDs WP3 addresses
+- `docs/clarion/1.0/detailed-design.md §§4–5` — qualname rules
+- `docs/clarion/1.0/requirements.md` — REQ-/NFR- IDs WP3 addresses
 
 ## Methodology
 
diff --git a/docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md b/docs/implementation/handoffs/2026-04-30-sprint-2-kickoff.md
similarity index 100%
rename from docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md
rename to docs/implementation/handoffs/2026-04-30-sprint-2-kickoff.md
diff --git a/docs/superpowers/handoffs/2026-05-03-skeleton-audit.md b/docs/implementation/handoffs/2026-05-03-skeleton-audit.md
similarity index 98%
rename from docs/superpowers/handoffs/2026-05-03-skeleton-audit.md
rename to docs/implementation/handoffs/2026-05-03-skeleton-audit.md
index 5824b46a..998e0878 100644
--- a/docs/superpowers/handoffs/2026-05-03-skeleton-audit.md
+++ b/docs/implementation/handoffs/2026-05-03-skeleton-audit.md
@@ -42,7 +42,7 @@ Out of scope (deliberate; flag for separate audit if useful):
 
 For each candidate concept:
 
-1. Locate every site in `docs/clarion/v0.1/{requirements,system-design,detailed-design}.md`,
+1. Locate every site in `docs/clarion/1.0/{requirements,system-design,detailed-design}.md`,
    `docs/clarion/adr/`, `crates/clarion-storage/migrations/0001_initial_schema.sql`,
    and any code path that reads/writes the column.
 2. Cross-reference Filigree's vocabulary via `filigree taxonomy` and
@@ -75,9 +75,9 @@ For each candidate concept:
 ## F-1: `priority` is the same word for two different things
 
 **Sites**:
-- Clarion: `docs/clarion/v0.1/detailed-design.md:453` — guidance entity
+- Clarion: `docs/clarion/1.0/detailed-design.md:453` — guidance entity
   property; values `"project" | "subsystem" | "package" | "module" | "class" | "function"`.
-- Clarion: `docs/clarion/v0.1/system-design.md:346` — same definition,
+- Clarion: `docs/clarion/1.0/system-design.md:346` — same definition,
   semantic ordering `project → subsystem → package → module → class → function`
   (outer-overrides-inner composition order).
 - Clarion schema: `crates/clarion-storage/migrations/0001_initial_schema.sql:163-165`
@@ -121,7 +121,7 @@ DB) or stack `0002_*.sql`? Decide once for the project.
 ## F-2: `critical` is the same word for two different things
 
 **Sites**:
-- Clarion: `docs/clarion/v0.1/detailed-design.md:467` — guidance entity
+- Clarion: `docs/clarion/1.0/detailed-design.md:467` — guidance entity
   `critical: bool` flag — semantics: "preserved across token-budget pressure"
   (i.e., do-not-drop).
 - Clarion: `detailed-design.md:449` — `tags: ["critical"]` literal as the
@@ -316,8 +316,8 @@ finding/guidance) plus the schema change and test fix into a single ADR-024
 ("Loom vocabulary discipline and guidance schema") and a single PR before
 Tier B starts. Touches:
 
-- `docs/clarion/v0.1/detailed-design.md` (multiple sites)
-- `docs/clarion/v0.1/system-design.md` (one site)
+- `docs/clarion/1.0/detailed-design.md` (multiple sites)
+- `docs/clarion/1.0/system-design.md` (one site)
 - `docs/clarion/adr/ADR-024-*.md` (new)
 - `crates/clarion-storage/migrations/0001_initial_schema.sql` (priority
   column + index; possibly add `0002_*.sql` instead — see migration policy
diff --git a/docs/superpowers/handoffs/2026-05-16-sprint-2-resume.md b/docs/implementation/handoffs/2026-05-16-sprint-2-resume.md
similarity index 100%
rename from docs/superpowers/handoffs/2026-05-16-sprint-2-resume.md
rename to docs/implementation/handoffs/2026-05-16-sprint-2-resume.md
diff --git a/docs/superpowers/handoffs/2026-05-18-phase3-subsystems-handoff.md b/docs/implementation/handoffs/2026-05-18-phase3-subsystems-handoff.md
similarity index 91%
rename from docs/superpowers/handoffs/2026-05-18-phase3-subsystems-handoff.md
rename to docs/implementation/handoffs/2026-05-18-phase3-subsystems-handoff.md
index 9e08c35a..73d1670d 100644
--- a/docs/superpowers/handoffs/2026-05-18-phase3-subsystems-handoff.md
+++ b/docs/implementation/handoffs/2026-05-18-phase3-subsystems-handoff.md
@@ -2,7 +2,7 @@
 
 **Date**: 2026-05-18
 **For**: an agent picking this up cold
-**Predecessor context**: Sprint 2 closed GREEN; [arch-analysis 2026-05-18](../../arch-analysis-2026-05-18-1244/04-final-report.md) is the current-state snapshot; [Thread-1 publish-prep program](../../implementation/v0.1-publish/thread-1-pre-publish-blockers.md) runs in parallel to this and does not block.
+**Predecessor context**: Sprint 2 closed GREEN; [arch-analysis 2026-05-20](../arch-analysis-2026-05-20-2124/04-final-report.md) supersedes the removed 2026-05-18 snapshot as the current RC1 code-geography reference; [Thread-1 publish-prep program](../../implementation/v0.1-publish/thread-1-pre-publish-blockers.md) runs in parallel to this and does not block.
 
 ---
 
@@ -16,7 +16,7 @@ Closing this gap is the single highest-leverage move between the current MCP-MVP
 
 Two things, in order, with a human review gate between them.
 
-1. **An implementation plan** (file: `docs/superpowers/plans/2026-XX-XX-phase3-subsystems.md`) in the existing plan-doc convention (see [`docs/superpowers/plans/2026-05-05-b2-class-module-entities.md`](../plans/2026-05-05-b2-class-module-entities.md) for the canonical shape). Task-by-task, file-by-file, with exit criteria each task.
+1. **An implementation plan** (file: `docs/superpowers/plans/2026-XX-XX-phase3-subsystems.md`) in the existing plan-doc convention (see [`docs/superpowers/plans/2026-05-05-b2-class-module-entities.md`](../agent-plans/2026-05-05-b2-class-module-entities.md) for the canonical shape). Task-by-task, file-by-file, with exit criteria each task.
 2. **The implementation itself**, executed task-by-task under TDD discipline, after the human approves the plan.
 
 **Do not skip Phase 1.** Phase 3 clustering touches the schema, the analyze orchestrator, the MCP read surface, and (when WP6 module/subsystem aggregation lands in v0.2) the LLM pipeline. The plan is the surface where the human catches "you missed `runs.stats` serialisation" or "the `in_subsystem` edge needs the writer-actor's edge-contract validator updated" before you write the wrong code for an afternoon.
@@ -34,9 +34,9 @@ Two things, in order, with a human review gate between them.
 1. **`docs/clarion/adr/ADR-006-clustering-algorithm.md` plus ADR-032** — the authoritative spec. Read in full. Leiden on directed weighted imports+calls subgraph, seeded for determinism, with `weighted_components` as the named local fallback after ADR-032. Output is one `subsystem` entity per cluster + `in_subsystem` edges from members. Modularity reported, not enforced.
 2. **`docs/clarion/adr/ADR-022-core-plugin-ontology.md`** — `subsystem` is a core-reserved entity kind; `in_subsystem` is a core-reserved edge kind. Plugins cannot emit either. The writer-actor's edge-contract validator already knows about plugin-extensible vs core-reserved (`writer.rs:411` per arch-analysis).
 3. **`docs/clarion/adr/ADR-003-entity-id-scheme.md`** — subsystem IDs follow `core:subsystem:{cluster_hash}` per ADR-006 §Output. The hash is `sha256(sorted(member_module_ids))` truncated to 12 chars; verify the existing entity-ID validator accepts this shape (it should — `core` is a registered plugin_id per ADR-022).
-4. **`docs/clarion/v0.1/requirements.md`** — REQ-CATALOG-05 (subsystem entities), REQ-ANALYZE-01 (phased pipeline), REQ-ANALYZE-05 (Phase-7 findings — relevant because `CLA-FACT-CLUSTERING-WEAK-MODULARITY` is named in ADR-006 §Quality assessment).
-5. **`docs/clarion/v0.1/system-design.md` §6** — pipeline phases. Phase 3 placement, what it reads from storage, what it writes.
-6. **`docs/clarion/v0.1/detailed-design.md`** — search for `subsystem`, `cluster`, `Phase 3`. Schema shape if present, properties expected on the subsystem entity.
+4. **`docs/clarion/1.0/requirements.md`** — REQ-CATALOG-05 (subsystem entities), REQ-ANALYZE-01 (phased pipeline), REQ-ANALYZE-05 (Phase-7 findings — relevant because `CLA-FACT-CLUSTERING-WEAK-MODULARITY` is named in ADR-006 §Quality assessment).
+5. **`docs/clarion/1.0/system-design.md` §6** — pipeline phases. Phase 3 placement, what it reads from storage, what it writes.
+6. **`docs/clarion/1.0/detailed-design.md`** — search for `subsystem`, `cluster`, `Phase 3`. Schema shape if present, properties expected on the subsystem entity.
 7. **Current code surface** — `cargo` over these files at minimum:
    - `crates/clarion-storage/migrations/0001_initial_schema.sql` — does `entities.kind` already accept `subsystem`? Does `edges.kind` accept `in_subsystem`? ADR-031 added CHECK constraints on closed vocabularies; verify the subsystem path is not constrained-shut.
    - `crates/clarion-storage/src/writer.rs` (around line 394–411) — `STRUCTURAL_EDGE_KINDS` and `ANCHORED_EDGE_KINDS` registers. Arch-analysis H-2 noted these duplicate the manifest's edge-kind list (now closed as `clarion-4e3cacac90`); confirm what the closure shipped.
@@ -44,7 +44,7 @@ Two things, in order, with a human review gate between them.
    - `crates/clarion-cli/src/analyze.rs` — where Phase 1 (entity ingest) and Phase 2 (graph completion if implemented) currently end. Find the seam Phase 3 plugs into. Note that the file is `#[allow(clippy::too_many_lines)]` and arch-analysis flagged it (H-1 closed); if you add to it, factor cleanly.
    - `crates/clarion-mcp/src/lib.rs` — the 7 MCP tools. Specifically `neighborhood`, `find_entity`, `execution_paths_from` — these will become more useful with subsystems but may need shape changes. **Do not change MCP tool surfaces silently.** Surface every proposed change in the plan.
 8. **`docs/implementation/sprint-2/scope-amendment-2026-05.md`** — what was explicitly deferred. WP4 Phase 3 was deferred *with this work in mind*; you are pulling it forward from v0.2 to closing-of-v0.1.
-9. **`docs/arch-analysis-2026-05-18-1244/02-subsystem-catalog.md`** — current code geography. The `clarion-storage` and `clarion-cli` entries describe the writer-actor, query helpers, and analyze orchestrator in concrete terms.
+9. **`docs/implementation/arch-analysis-2026-05-20-2124/02-subsystem-catalog.md`** — current RC1 code geography. The `clarion-storage` and `clarion-cli` entries describe the writer-actor, query helpers, and analyze orchestrator in concrete terms; refresh line numbers against current `HEAD` before treating them as evidence.
 
 ## Scope discipline — what's IN and what's OUT
 
@@ -181,6 +181,6 @@ The last bullet is the actual capability the work delivers. If it works in CI bu
 - [REQ-CATALOG-05, REQ-ANALYZE-01, REQ-ANALYZE-05](../../clarion/v0.1/requirements.md)
 - [v0.1-plan.md WP4](../../implementation/v0.1-plan.md#wp4--core-only-pipeline-phases-03-7-8)
 - [Sprint-2 scope amendment — explicit Phase 3 deferral with retirement path](../../implementation/sprint-2/scope-amendment-2026-05.md)
-- [Arch-analysis 2026-05-18 — current code geography](../../arch-analysis-2026-05-18-1244/04-final-report.md)
-- [B.2 plan-doc shape — canonical example](../plans/2026-05-05-b2-class-module-entities.md)
+- [Arch-analysis 2026-05-20 — current RC1 code geography](../arch-analysis-2026-05-20-2124/04-final-report.md)
+- [B.2 plan-doc shape — canonical example](../agent-plans/2026-05-05-b2-class-module-entities.md)
 - [Sprint-2 B.4* — the week-2 go/no-go gate pattern to mimic](../../implementation/sprint-2/scope-amendment-2026-05.md#5-the-week-2-gono-go-gate-load-bearing-risk)
diff --git a/docs/implementation/review-sweep-2026-05-29.md b/docs/implementation/review-sweep-2026-05-29.md
new file mode 100644
index 00000000..f0a7a9c4
--- /dev/null
+++ b/docs/implementation/review-sweep-2026-05-29.md
@@ -0,0 +1,97 @@
+# Full-codebase review sweep — 2026-05-29
+
+A multi-agent code-review sweep over Clarion's own source + tests, chunked into
+~2000-line semantically-coherent units. Each chunk is reviewed by a team of
+five agents (architecture critic, systems thinker, language engineer, quality
+engineer, + a chunk-specific specialist). Findings are deduped per chunk and
+filed as Filigree issues.
+
+**Scope:** Clarion's own code only. The `tests/perf/elspeth_mini/` customer
+fixture corpus (~33k lines) is **excluded** — it is representative customer
+code, not Clarion source.
+
+**Filigree tagging:** every issue gets `from-review-sweep-2026-05-29` (batch
+source, for bulk triage/revert), a `chunk:<id>` label, a `review:<severity>`
+label (`blocker|high|medium|low|suggestion`), plus `crate:*` / `category:*` /
+`plugin:python` as applicable. Defects → type `bug`; improvements/suggestions →
+type `task`. Priority: blocker=0, high=1, medium=2, low=3, suggestion=4.
+
+**Team roster per chunk:** `architecture-critic`, `plan-review-systems`
+(systems thinker), language engineer (`code-reviewer` for Rust /
+`python-code-reviewer` for Python), quality engineer
+(`quality-assurance-analyst` for src / `test-suite-reviewer` for tests), and
+one chunk-specific specialist (see table). A sixth agent per chunk synthesizes
++ dedupes the five reports and files the tickets.
+
+## Chunk manifest (35 chunks)
+
+### Rust — clarion-core src
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| core-host-a | `clarion-core/src/plugin/host.rs:1-1470` | threat-analyst |
+| core-host-b | `clarion-core/src/plugin/host.rs:1471-2935` | silent-failure-hunter |
+| core-llm | `clarion-core/src/llm_provider.rs` (2467) | silent-failure-hunter |
+| core-manifest-protocol | `manifest.rs` (1119) + `plugin/protocol.rs` (875) | type-design-analyzer |
+| core-mock-discovery-transport | `plugin/mock.rs` (876) + `discovery.rs` (667) + `transport.rs` (569) | code-reviewer |
+| core-entityid-jail-limits | `entity_id.rs` (596) + `plugin/limits.rs` (572) + `breaker.rs` (360) + `jail.rs` (260) + `host_findings.rs` (273) + `mod.rs` + `lib.rs` | threat-analyst |
+
+### Rust — clarion-cli src
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| cli-analyze-a | `clarion-cli/src/analyze.rs:1-1220` | code-reviewer |
+| cli-analyze-b | `clarion-cli/src/analyze.rs:1221-2433` | code-reviewer |
+| cli-http-read | `clarion-cli/src/http_read.rs` (1736) | api-reviewer |
+| cli-secret-scan | `secret_scan.rs` + `secret_scan/{findings,files,anchors,baseline}.rs` + `serve.rs` + `instance.rs` | threat-analyst |
+| cli-misc | `clustering.rs` + `install.rs` + `skill_pack.rs` + `analyze_lock.rs` + `config.rs` + `main.rs` + `cli.rs` + `stats.rs` + `run_lifecycle.rs` | code-reviewer |
+
+### Rust — clarion-mcp src
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| mcp-lib-a | `clarion-mcp/src/lib.rs:1-1150` | api-reviewer |
+| mcp-lib-b | `clarion-mcp/src/lib.rs:1151-2300` | api-reviewer |
+| mcp-lib-c | `clarion-mcp/src/lib.rs:2301-3449` | api-reviewer |
+| mcp-config-filigree | `config.rs` (956) + `filigree.rs` (238) | code-reviewer |
+
+### Rust — clarion-storage src
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| storage-query | `query.rs` (1097) + `schema.rs` (209) + `pragma.rs` (109) | embedded-database-reviewer |
+| storage-writer | `writer.rs` (1080) + `cache.rs` + `commands.rs` + `error.rs` + `reader.rs` + `unresolved.rs` + `lib.rs` | embedded-database-reviewer |
+
+### Rust — clarion-scanner + fixture src
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| scanner-src | `clarion-scanner/src/*` (patterns/baseline/lib/entropy) + `clarion-plugin-fixture/src/*` | threat-analyst |
+
+### Python plugin src
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| py-pyright | `pyright_session.py` (1427) + `qualname.py` | python-code-reviewer |
+| py-extractor | `extractor.py` (918) + `server.py` + `entity_id.py` + `reference_resolver.py` + `call_resolver.py` + `wardline_probe.py` + `stdout_guard.py` + `__main__.py` | python-code-reviewer |
+
+### Rust tests
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| test-serve-a | `clarion-cli/tests/serve.rs:1-1340` | api-reviewer |
+| test-serve-b | `clarion-cli/tests/serve.rs:1341-2683` | api-reviewer |
+| test-writer-actor-a | `clarion-storage/tests/writer_actor.rs:1-1235` | embedded-database-reviewer |
+| test-writer-actor-b | `clarion-storage/tests/writer_actor.rs:1236-2471` | embedded-database-reviewer |
+| test-storage-tools-a | `clarion-mcp/tests/storage_tools.rs:1-1115` | api-reviewer |
+| test-storage-tools-b | `clarion-mcp/tests/storage_tools.rs:1116-2233` | api-reviewer |
+| test-cli-analyze | `analyze.rs` (1221) + `analyze_failure_modes.rs` + `install.rs` | coverage-gap-analyst |
+| test-storage-query | `query_helpers.rs` (1082) + `reader_pool.rs` + `llm_cache.rs` | embedded-database-reviewer |
+| test-schema-host | `schema_apply.rs` (1051) + `core/tests/host_subprocess.rs` | embedded-database-reviewer |
+| test-secret-scanner | `cli/tests/secret_scan.rs` (917) + `scanner/tests/scanner.rs` | threat-analyst |
+
+### Python tests
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| pytest-extractor | `test_extractor.py` (1203) + `test_qualname.py` | coverage-gap-analyst |
+| pytest-pyright | `test_pyright_session.py` (968) + `test_stdout_guard.py` + `test_package.py` | coverage-gap-analyst |
+| pytest-server | `test_server.py` (586) + `test_round_trip.py` + `test_entity_id.py` + `test_wardline_probe.py` | coverage-gap-analyst |
+
+### Scripts + e2e
+| id | files / ranges | specialist |
+|----|----------------|------------|
+| scripts-governance | `scripts/*.py` + `scripts/*.sh` (governance/CI) | pipeline-reviewer |
+| e2e-shell | `tests/e2e/*.sh` + `cli/tests/{wp2_e2e,wp1_e2e,skills}.rs` | pipeline-reviewer |
diff --git a/docs/implementation/sprint-1/README.md b/docs/implementation/sprint-1/README.md
index 980ce64e..3a0c2c9d 100644
--- a/docs/implementation/sprint-1/README.md
+++ b/docs/implementation/sprint-1/README.md
@@ -4,7 +4,7 @@
 **Sprint goal**: [Tier A — walking skeleton](./signoffs.md#tier-a--sprint-1-close-walking-skeleton)
 **Scope**: WP1 (scaffold + storage) → WP2 (plugin protocol + hybrid authority) → WP3 (Python plugin v0.1 baseline)
 **Predecessor plan**: [`../v0.1-plan.md`](../v0.1-plan.md)
-**Scope memo**: [`../../clarion/v0.1/plans/v0.1-scope-commitments.md`](../../clarion/v0.1/plans/v0.1-scope-commitments.md)
+**Scope memo**: [`../v0.1-scope-plans/v0.1-scope-commitments.md`](../v0.1-scope-plans/v0.1-scope-commitments.md)
 **Gate to close**: every checkbox ticked in [`signoffs.md`](./signoffs.md) Tier A.
 
 ---
diff --git a/docs/implementation/sprint-1/signoffs.md b/docs/implementation/sprint-1/signoffs.md
index e8e331bc..ef26a51f 100644
--- a/docs/implementation/sprint-1/signoffs.md
+++ b/docs/implementation/sprint-1/signoffs.md
@@ -134,4 +134,4 @@ ladder completeness; not required to close Sprint 1 or Sprint 2.
 - [`README.md`](./README.md) — sprint orientation and demo script.
 - [`wp1-scaffold.md`](./wp1-scaffold.md), [`wp2-plugin-host.md`](./wp2-plugin-host.md), [`wp3-python-plugin.md`](./wp3-python-plugin.md) — per-WP plans.
 - [`../v0.1-plan.md`](../v0.1-plan.md) — high-level plan for all 11 WPs.
-- [`../../clarion/v0.1/plans/v0.1-scope-commitments.md`](../../clarion/v0.1/plans/v0.1-scope-commitments.md) — scope memo.
+- [`../v0.1-scope-plans/v0.1-scope-commitments.md`](../v0.1-scope-plans/v0.1-scope-commitments.md) — scope memo.
diff --git a/docs/implementation/sprint-2/b2-class-module-entities.md b/docs/implementation/sprint-2/b2-class-module-entities.md
index 53670439..3203c68e 100644
--- a/docs/implementation/sprint-2/b2-class-module-entities.md
+++ b/docs/implementation/sprint-2/b2-class-module-entities.md
@@ -5,7 +5,7 @@
 **Accepted ADRs**: [ADR-007](../../clarion/adr/ADR-007-summary-cache-key.md), [ADR-018](../../clarion/adr/ADR-018-identity-reconciliation.md), [ADR-021](../../clarion/adr/ADR-021-plugin-authority-hybrid.md), [ADR-022](../../clarion/adr/ADR-022-core-plugin-ontology.md), [ADR-023](../../clarion/adr/ADR-023-tooling-baseline.md)
 **Predecessor**: [WP3 Sprint-1 baseline](../sprint-1/wp3-python-plugin.md) (function-only extraction)
 **Successor**: B.3 — `contains` edges (planned)
-**Sprint-2 kickoff handoff**: [`docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md`](../../superpowers/handoffs/2026-04-30-sprint-2-kickoff.md) §"What's in scope for Sprint 2" Tier B row B.2
+**Sprint-2 kickoff handoff**: [`docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md`](../handoffs/2026-04-30-sprint-2-kickoff.md) §"What's in scope for Sprint 2" Tier B row B.2
 
 ---
 
diff --git a/docs/implementation/sprint-2/b3-contains-edges.md b/docs/implementation/sprint-2/b3-contains-edges.md
index 1ce9e5e7..b6e44619 100644
--- a/docs/implementation/sprint-2/b3-contains-edges.md
+++ b/docs/implementation/sprint-2/b3-contains-edges.md
@@ -5,7 +5,7 @@
 **Accepted ADRs**: [ADR-002](../../clarion/adr/ADR-002-plugin-transport-json-rpc.md), [ADR-003](../../clarion/adr/ADR-003-entity-id-scheme.md), [ADR-006](../../clarion/adr/ADR-006-clustering-algorithm.md), [ADR-007](../../clarion/adr/ADR-007-summary-cache-key.md), [ADR-022](../../clarion/adr/ADR-022-core-plugin-ontology.md), [ADR-023](../../clarion/adr/ADR-023-tooling-baseline.md), [ADR-024](../../clarion/adr/ADR-024-guidance-schema-vocabulary.md), [ADR-026](../../clarion/adr/ADR-026-containment-wire-and-edge-identity.md), [ADR-027](../../clarion/adr/ADR-027-ontology-version-semver.md)
 **Predecessor**: [B.2 — class + module entity emission](./b2-class-module-entities.md)
 **Successor**: B.1 (multi-file dispatch — WP4 Phase 0+1) and B.4 (catalog rendering)
-**Sprint-2 kickoff handoff**: [`docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md`](../../superpowers/handoffs/2026-04-30-sprint-2-kickoff.md) §"What's in scope for Sprint 2" Tier B row B.3
+**Sprint-2 kickoff handoff**: [`docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md`](../handoffs/2026-04-30-sprint-2-kickoff.md) §"What's in scope for Sprint 2" Tier B row B.3
 
 ---
 
diff --git a/docs/implementation/sprint-2/scope-amendment-2026-05.md b/docs/implementation/sprint-2/scope-amendment-2026-05.md
index 22252dcc..1ae57498 100644
--- a/docs/implementation/sprint-2/scope-amendment-2026-05.md
+++ b/docs/implementation/sprint-2/scope-amendment-2026-05.md
@@ -3,8 +3,8 @@
 **Status**: Sprint 2 closed — RED partial milestone; see [signoffs.md](./signoffs.md) and [b8-results.md](./b8-results.md).
 **Date opened**: 2026-05-16
 **Author**: John Morrissey
-**Predecessor**: [`docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md`](../../superpowers/handoffs/2026-04-30-sprint-2-kickoff.md)
-**Successor**: [`docs/superpowers/handoffs/2026-05-16-sprint-2-resume.md`](../../superpowers/handoffs/2026-05-16-sprint-2-resume.md)
+**Predecessor**: [`docs/superpowers/handoffs/2026-04-30-sprint-2-kickoff.md`](../handoffs/2026-04-30-sprint-2-kickoff.md)
+**Successor**: [`docs/superpowers/handoffs/2026-05-16-sprint-2-resume.md`](../handoffs/2026-05-16-sprint-2-resume.md)
 
 This memo serves three roles in one artifact:
 
@@ -216,7 +216,7 @@ Existing open Sprint-2 issues that stay open:
 
 - [v0.1-plan.md](../v0.1-plan.md) — the 11-WP plan; gets a forward-pointer to this memo
 - [Sprint 1 signoffs](../sprint-1/signoffs.md) — the ladder format Sprint 2's eventual close will follow
-- [Sprint 2 kickoff handoff](../../superpowers/handoffs/2026-04-30-sprint-2-kickoff.md) — the original 7-box scope
+- [Sprint 2 kickoff handoff](../handoffs/2026-04-30-sprint-2-kickoff.md) — the original 7-box scope
 - [B.2 design](./b2-class-module-entities.md) — shipped
 - [B.3 design](./b3-contains-edges.md) — implementation pending
 - [ADR-028](../../clarion/adr/ADR-028-edge-confidence-tiers.md) — new
diff --git a/docs/implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md b/docs/implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md
new file mode 100644
index 00000000..a17712e1
--- /dev/null
+++ b/docs/implementation/sprint-3/2026-05-19-loom-federation-hardening-tasking.md
@@ -0,0 +1,390 @@
+# Loom Federation Hardening Tasking
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this tasking task-by-task. Steps use checkbox syntax for tracking.
+
+**Goal:** Bring Clarion's HTTP read API and ADR-014 federation contract up to the shared Loom standard required for Clarion 1.0 and Filigree 2.1 registry-backend mode.
+
+**Release stance:** This is release-blocking unless ADR-014 Clarion registry mode is explicitly de-scoped from the Clarion 1.0 and Filigree 2.1 tag notes. The current RC1 tests are green, but they validate the old contract shape rather than the hardened federation contract.
+
+**Architecture:** Clarion owns the publisher side of the file-registry read contract. Filigree's side should implement against Clarion's documented decisions, so Clarion must first pin the wire semantics in ADR-014, then make storage and HTTP behavior match the documented contract.
+
+**Tech Stack:** Rust workspace, `axum`, `tower`/`tower-http`, `rusqlite`, `deadpool`, `serde`, `serde_json`, `uuid`, Clarion's local Filigree tracker.
+
+---
+
+## Current Evidence
+
+Filigree reported, and RC1 source confirms, that the contract hardening prompt is largely not landed:
+
+- C1: `resolve_file` storage errors still map to HTTP 400 with raw `err.to_string()` at `crates/clarion-cli/src/http_read.rs`.
+- C2/C5/C11: `resolve_file` still requires disk existence via canonicalization, still synthesizes `core:file:{content_hash}@{canonical_path}`, and still converts unreadable hash failures to empty strings in `crates/clarion-storage/src/query.rs`.
+- C3: federation fixtures are still bare request/response snippets, and the file fixture still documents an invalid `@` entity ID.
+- C4/C7/C8/C9: HTTP read config has only `enabled` and `bind`; there is no non-loopback guard, no `allow_non_loopback`, no middleware stack, separate reader pools remain, and HTTP thread supervision only happens on shutdown.
+- C6/C10/C12/C13: joint contract decisions are not pinned; capabilities still return `version: "0.1"`, there is no `instance_id`, and errors are still `{ "error": String }`.
+
+## Contract Decisions Clarion Must Own First
+
+Clarion owns these publisher-side choices. Land them in `docs/clarion/adr/ADR-014-filigree-registry-backend.md` before implementation so the Filigree agent has a stable reference:
+
+1. **Capabilities version field:** use `api_version: 1`.
+   `api_version` increments only when the HTTP read API wire contract changes incompatibly for existing Filigree clients. Do not use product semver here.
+2. **File identity when no `kind='file'` row exists:** fail closed with 404.
+   Delete the synthetic `core:file:{content_hash}@{canonical_path}` branch. It violates ADR-003 and creates shadow IDs that will not match future file-discovery rows.
+3. **`canonical_path` semantics:** project-relative POSIX path.
+   No leading `/`, no leading `./`, no trailing `/`, separator `/`. This survives project relocation and matches current response intent.
+4. **Instance fingerprint:** stable per-project UUID in `.clarion/instance_id`, surfaced as `instance_id` in capabilities.
+   First creation persists with mode `0600` on Unix. Deleting `.clarion/` may create a new instance ID; that is acceptable and should be detectable by Filigree.
+5. **Error envelope:** closed shape `{ "error": String, "code": ErrorCode }`.
+   Initial code enum: `INVALID_PATH`, `PATH_OUTSIDE_PROJECT`, `NOT_FOUND`, `STORAGE_ERROR`, `INTERNAL`.
+6. **HTTP trust model:** unauthenticated loopback-only by default.
+   Non-loopback bind is refused unless `serve.http.allow_non_loopback: true`; opt-in startup logs must warn that the surface is unauthenticated.
+
+## Dependency Order
+
+```text
+T0 contract docs
+  -> T1 storage resolution correctness (C2, C5, C10, C11)
+  -> T2 HTTP status/error contract (C1, C13)
+  -> T3 capabilities/instance handshake (C6, C12)
+  -> T4 fixtures + contract gates (C3)
+  -> T5 runtime hardening (C4, C7, C8, C9)
+  -> T6 medium hardening / known-issues call (C14-C19)
+```
+
+If the team needs parallelism after T0 lands:
+
+- Worker A owns storage: `crates/clarion-storage/src/query.rs`, `crates/clarion-storage/tests/query_helpers.rs`.
+- Worker B owns HTTP contract: `crates/clarion-cli/src/http_read.rs`, `crates/clarion-cli/tests/serve.rs`, fixtures.
+- Worker C owns runtime guard/supervision: `crates/clarion-mcp/src/config.rs`, `crates/clarion-cli/src/serve.rs`, `crates/clarion-cli/src/http_read.rs`.
+- Worker D owns docs: ADR-014, ADR-003, `docs/federation/contracts.md`, `docs/operator/clarion-http-read-api.md`, `docs/suite/loom.md`.
+
+Workers are not alone in the codebase. Do not revert or overwrite unrelated RC1 work; keep each task's write set narrow.
+
+## Tracker Shape
+
+Create one P0 epic:
+
+```text
+Sprint 3 RC1 — Loom federation HTTP read API hardening
+```
+
+Create these child phases/tasks:
+
+- P0 phase: Contract decisions and docs
+- P0 bug: C2 — remove invalid synthetic file IDs and fail closed
+- P0 bug: C1 — classify HTTP read storage errors correctly
+- P0 task: C3 — upgrade federation fixtures into contract tests
+- P0 task: C4 — enforce loopback trust model
+- P1 task: C5/C11 — unreadable/deleted file behavior
+- P1 task: C6/C12 — api_version and instance_id capability handshake
+- P1 task: C7/C8/C9 — HTTP runtime resource limits, supervision, shared reader pool
+- P1 task: C13 — closed error envelope
+- P2 phase: Medium hardening C14-C19 or known-issues note
+
+Use:
+
+```bash
+filigree --actor clarion-agent start-work <id> --assignee clarion-agent
+filigree --actor clarion-agent add-comment <id> "summary, tests, commits"
+filigree --actor clarion-agent close <id> --reason="implemented and tested ..."
+```
+
+Do not close any tracker item until the code, tests, docs, and commit for that item exist.
+
+## T0: Contract Decisions and ADR Patch
+
+**Files:**
+
+- Modify: `docs/clarion/adr/ADR-014-filigree-registry-backend.md`
+- Modify: `docs/clarion/adr/ADR-003-entity-id-scheme.md`
+- Modify: `docs/federation/contracts.md`
+- Create: `docs/operator/clarion-http-read-api.md`
+- Modify: `docs/suite/loom.md`
+
+**Acceptance criteria:**
+
+- ADR-014 has sections for capability probe semantics, canonical path semantics, instance fingerprint, error envelope, and security posture.
+- ADR-003 explicitly states file-kind IDs are `core:file:{qualified_name}` and may not contain `@`.
+- Federation contract docs show `api_version: 1`, `instance_id`, project-relative `canonical_path`, and closed error codes.
+- Operator docs state the HTTP read API is unauthenticated, loopback-only by default, and must be fronted by an authenticated reverse proxy if bound non-loopback.
+
+**Steps:**
+
+- [ ] Patch ADR-014 with the six contract decisions above.
+- [ ] Patch ADR-003 with a file-kind ID grammar note and reject the former `content_hash@path` pattern as non-conforming.
+- [ ] Patch `docs/federation/contracts.md` to show the new request/response and error shapes.
+- [ ] Create `docs/operator/clarion-http-read-api.md` with a `Trust model` section.
+- [ ] Patch `docs/suite/loom.md` to link the operator trust model.
+- [ ] Run `cargo test -p clarion-cli --test serve` to ensure docs-only edits did not disturb tests.
+- [ ] Commit as `C0 docs: pin Loom federation read contract decisions`.
+
+## T1: Storage Resolution Correctness
+
+**Findings covered:** C2, C5, C10, C11.
+
+**Files:**
+
+- Modify: `crates/clarion-storage/src/query.rs`
+- Modify: `crates/clarion-storage/tests/query_helpers.rs`
+
+**Implementation requirements:**
+
+- `resolve_file` must return `Ok(None)` when no `kind='file'` row exists for the path.
+- Delete the synthetic ID branch.
+- Stop requiring the candidate file to exist on disk before checking catalog rows.
+- Deleted-on-disk but cataloged files resolve to 200-equivalent storage success using cataloged entity data.
+- `file_content_hash` must return `Result<String, io::Error>` if still used as a fallback.
+- Never return empty `content_hash` because disk read failed. If no catalog hash exists and a hash fallback fails, propagate the error.
+- `canonical_path` returned by `resolve_file` must be project-relative POSIX and must not start with `/`, `./`, or `../`.
+- Caller-supplied `language` must not poison the catalog response when Clarion can infer a better value.
+
+**Tests to add first:**
+
+- `resolve_file_returns_none_when_no_file_kind_entity_exists`
+- `resolve_file_deleted_on_disk_but_cataloged_row_resolves`
+- `resolve_file_unreadable_hash_failure_propagates`
+- `resolve_file_returns_project_relative_posix_canonical_path`
+- `resolve_file_does_not_echo_invalid_requested_language_over_catalog_inference`
+
+**Commands:**
+
+```bash
+cargo test -p clarion-storage resolve_file -- --nocapture
+cargo test -p clarion-storage
+```
+
+**Commit guidance:**
+
+- Commit C2 separately if possible: `C2 fix: remove synthetic file identity branch`.
+- Commit C5/C11 together only if the same refactor is inseparable: `C5 C11 fix: resolve cataloged files without empty hash fallback`.
+- Mention in the commit body why `@` IDs are forbidden by ADR-003.
+
+## T2: HTTP Status and Error Envelope Contract
+
+**Findings covered:** C1, C13.
+
+**Files:**
+
+- Modify: `crates/clarion-cli/src/http_read.rs`
+- Modify: `crates/clarion-cli/tests/serve.rs`
+- May modify: `crates/clarion-storage/src/error.rs` only if a small helper is needed.
+
+**Implementation requirements:**
+
+- Replace `Err(err) => json_error(StatusCode::BAD_REQUEST, &err.to_string())`.
+- Map storage errors:
+  - `InvalidSourcePath`, `InvalidQuery` -> 400
+  - candidate file not known -> 404 via `Ok(None)`
+  - deleted/unreadable candidate under project root when no catalog row can answer -> 404 or stable `NOT_FOUND`
+  - project-root canonicalization failure -> 500
+  - SQLite, pool, pool interact, pool build -> 500 or 503
+- Do not echo raw storage errors to clients.
+- Log 500-class errors with the full error chain using `tracing::error!`.
+- Return `{ "error": "...", "code": "..." }` for every non-2xx response.
+- Use the closed code set documented in T0.
+
+**Tests to add first:**
+
+- blank path returns 400 `INVALID_PATH`
+- path traversal returns 400 `PATH_OUTSIDE_PROJECT`
+- unknown catalog file returns 404 `NOT_FOUND`
+- storage/pool/sqlite failure returns 500 or 503 with `STORAGE_ERROR`
+- response body never contains the raw SQLite/private path detail for 500-class errors
+
+**Commands:**
+
+```bash
+cargo test -p clarion-cli --test serve
+cargo test -p clarion-storage
+```
+
+**Commit guidance:**
+
+- `C1 fix: classify HTTP read storage errors`
+- `C13 fix: pin HTTP read error envelope`
+
+## T3: Capability Probe and Instance Fingerprint
+
+**Findings covered:** C6, C12.
+
+**Files:**
+
+- Modify: `crates/clarion-cli/src/http_read.rs`
+- Modify: `crates/clarion-cli/tests/serve.rs`
+- Modify or create helper in: `crates/clarion-cli/src/serve.rs` or a small `instance.rs` module if that keeps `http_read.rs` focused.
+- Modify: `docs/federation/fixtures/get-api-v1-capabilities.json`
+
+**Implementation requirements:**
+
+- Capabilities response must be:
+
+```json
+{
+  "registry_backend": true,
+  "file_registry": true,
+  "api_version": 1,
+  "instance_id": "uuid-string"
+}
+```
+
+- On startup, read `.clarion/instance_id`; if absent, create a UUID v4 and persist it.
+- On Unix, persist with mode `0600`.
+- The ID must survive process restarts.
+- The capability fixture must document the shape with `_meta`, `shape_decl`, and `examples`.
+
+**Tests to add first:**
+
+- first startup creates `.clarion/instance_id`
+- second startup reuses the same ID
+- capabilities returns `api_version: 1`
+- capabilities includes the stored `instance_id`
+- invalid existing instance-id file is rejected or replaced according to ADR-014's documented rule
+
+**Commands:**
+
+```bash
+cargo test -p clarion-cli --test serve capabilities -- --nocapture
+```
+
+**Commit guidance:**
+
+- `C6 fix: expose api_version in HTTP capabilities`
+- `C12 fix: add stable Clarion instance fingerprint`
+
+## T4: Contract Fixtures and Shape Gate
+
+**Finding covered:** C3.
+
+**Files:**
+
+- Modify: `docs/federation/fixtures/get-api-v1-files.demo-python.json`
+- Modify: `docs/federation/fixtures/get-api-v1-capabilities.json`
+- Modify: `crates/clarion-cli/tests/serve.rs` or create `crates/clarion-cli/tests/http_contract.rs`
+
+**Implementation requirements:**
+
+- Fixtures must have:
+  - `_meta`: `contract`, `stability`, `authority`, `verification`, `updated`
+  - `shape_decl`: human-readable shape rules
+  - `examples`: named examples with request and response
+- `/api/v1/files` examples:
+  - 200 happy path with a real file-kind entity
+  - 404 file-not-known
+  - 400 blank path
+  - 400 outside project root
+  - 500/503 storage error
+- `/_capabilities` examples:
+  - one valid response with `api_version: 1` and `instance_id`
+  - future extension point note
+- Add a Rust test that boots the HTTP server and validates real responses against fixture shape declarations.
+
+**Commands:**
+
+```bash
+cargo test -p clarion-cli --test serve
+```
+
+**Commit guidance:**
+
+- `C3 test: pin HTTP read API federation fixtures`
+
+## T5: HTTP Trust Model and Runtime Hardening
+
+**Findings covered:** C4, C7, C8, C9.
+
+**Files:**
+
+- Modify: `crates/clarion-mcp/src/config.rs`
+- Modify: `crates/clarion-cli/src/http_read.rs`
+- Modify: `crates/clarion-cli/src/serve.rs`
+- Modify: `crates/clarion-cli/Cargo.toml`
+- Modify: workspace `Cargo.toml` and `Cargo.lock` if adding dependencies
+- Modify: `crates/clarion-cli/tests/serve.rs`
+
+**Implementation requirements:**
+
+- Add `serve.http.allow_non_loopback: bool`, default false.
+- Refuse to start the HTTP read API if enabled and bind is not loopback unless `allow_non_loopback` is true.
+- Log normal startup with `auth = "none"` and bind address.
+- Log opt-in non-loopback startup as WARN and state that the surface is unauthenticated.
+- Add middleware:
+  - `TraceLayer::new_for_http()`
+  - `TimeoutLayer::new(Duration::from_secs(10))`
+  - `RequestBodyLimitLayer::new(16 * 1024)`
+  - `ConcurrencyLimitLayer::new(64)`
+  - `LoadShedLayer::new()`
+- Share the existing `ReaderPool` between MCP and HTTP; do not open a second pool.
+- Add supervision so a failed HTTP server aborts or fails the serve process visibly before MCP stdio continues pretending healthy.
+- Name threads if a dedicated thread remains: OS thread `clarion-http-read`, Tokio workers `clarion-http-worker`.
+
+**Tests to add first:**
+
+- enabled loopback without flag starts
+- enabled non-loopback without flag is refused
+- enabled non-loopback with flag starts and logs warning
+- HTTP server uses the shared reader pool path
+- request body/timeout/concurrency behavior is enforced enough to prove middleware is wired
+- supervised HTTP failure is surfaced before shutdown-only join handling
+
+**Commands:**
+
+```bash
+cargo test -p clarion-cli --test serve
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+cargo fmt --all --check
+```
+
+**Commit guidance:**
+
+- `C4 fix: enforce HTTP read API loopback trust model`
+- `C7 fix: add HTTP read API resource limits`
+- `C8 fix: supervise HTTP read server lifecycle`
+- `C9 fix: share reader pool with HTTP read API`
+
+## T6: Medium Hardening or Known-Issues Note
+
+**Findings covered:** C14-C19.
+
+These do not have to block the tag if the release notes explicitly identify them as known limitations. If time allows, land them after T1-T5:
+
+- C14: read language inference from plugin manifests rather than a hardcoded extension map.
+- C15: release reader-pool slots before slow disk hash fallback.
+- C16: support `ETag` and `If-None-Match` on `/api/v1/files`.
+- C17: structured thread/request naming, if not fully covered by T5.
+- C18: per-request structured access log fields including optional `X-Loom-Component` and `X-Filigree-Actor`.
+- C19: `#[serde(deny_unknown_fields)]` on `FileQuery`.
+
+If deferred, add a `Known limitations for 1.0` section to the release notes and create Clarion tracker issues for each item retained beyond the tag.
+
+## End-to-End Acceptance
+
+Clarion side is in spec when all of the following are true:
+
+- ADR-014 documents `api_version`, `canonical_path`, `instance_id`, error envelope, no synthetic IDs, and trust model.
+- ADR-003 no longer permits or implies `@` file IDs.
+- `cargo test -p clarion-cli --test serve` passes.
+- `cargo test -p clarion-storage` passes.
+- `cargo test --workspace` passes.
+- `cargo clippy --workspace --all-targets -- -D warnings` passes.
+- `cargo fmt --all --check` passes.
+- A local HTTP smoke against `clarion serve` proves:
+  - `/api/v1/_capabilities` returns `api_version: 1` and `instance_id`.
+  - `/api/v1/files` returns a real `core:file:*` entity ID for a cataloged file.
+  - a module-only catalog row does not synthesize a file ID and returns 404.
+  - a deleted-on-disk but cataloged file returns the cataloged identity.
+  - a traversal path returns a stable 400 error envelope.
+- Filigree has the documented shapes needed to implement F4/F8/F9/F14 without guessing.
+
+## Final Output Required From Implementing Agent
+
+When finished or blocked, report:
+
+- Findings landed and commit SHAs.
+- Findings still in flight.
+- Findings blocked on Filigree.
+- Test suite status.
+- Joint decisions made and exact doc locations.
+- Any reviewer finding that proved wrong, with source evidence.
+
+Do not mutate `/home/john/filigree`; it is read-only for this Clarion hardening pass.
diff --git a/docs/implementation/sprint-3/scope-amendment-2026-05.md b/docs/implementation/sprint-3/scope-amendment-2026-05.md
new file mode 100644
index 00000000..a60bbb65
--- /dev/null
+++ b/docs/implementation/sprint-3/scope-amendment-2026-05.md
@@ -0,0 +1,219 @@
+# Sprint 3 — WP10 Scope Amendment
+
+**Status**: CLOSED — Clarion-side WP10 implementation complete.
+**Date opened**: 2026-05-19
+**Author**: John Morrissey
+**Predecessor**: [`../sprint-2/signoffs.md`](../sprint-2/signoffs.md)
+**Cross-reference**: [`../../federation/filigree-side/ADR-014-registry-backend-and-file-identity-displacement.md`](../../federation/filigree-side/ADR-014-registry-backend-and-file-identity-displacement.md), [`../../federation/filigree-side/2026-05-19-registry-backend-cross-project-sequencing.md`](../../federation/filigree-side/2026-05-19-registry-backend-cross-project-sequencing.md)
+
+This memo serves three roles in one artifact:
+
+1. It lifts WP10 back into active Clarion scope as the Sprint 3 anchor.
+2. It records the Clarion-side half of ADR-014's federation displacement now that
+   the Filigree-side counterpart and sequencing memo exist.
+3. It turns the 2026-05-19 cross-project sequencing memo into Clarion tracker
+   work and records the implementation closeout for Clarion's side.
+
+---
+
+## 1. Status of Sprint 2 Carry-Forward
+
+Sprint 2 is closed GREEN after the B.8 repair rerun. The close ladder certifies
+the seven-tool MCP surface against the representative elspeth-slice and records
+that B.3, B.4*, B.5*, B.6, B.7, and B.8 are closed for Sprint 2 accounting.
+
+The following Sprint 2 caveats carry forward into Sprint 3 planning:
+
+| Carry-forward item | Sprint 3 effect |
+|---|---|
+| B.4* mini-gate wall-clock extrapolation was materially optimistic. | Treat HTTP read API integration tests as real measurements, not projection-only evidence. |
+| Sprint 2 certified the representative elspeth-slice, not full-repository elspeth. | WP10 exit criteria should name the exact corpus or fixture used for contract proof. |
+| Non-umbrella Sprint 2 audit/follow-up issues remain open by design. | They are not WP10 blockers unless a WP10 step touches the affected surface. |
+
+No Sprint 2 umbrella issue is reopened by this amendment.
+
+---
+
+## 2. Why WP10 Is the Sprint 3 Anchor
+
+Clarion ADR-014, accepted on 2026-04-18, made `registry_backend: clarion` the
+design of record for displacing Filigree's native file IDs with Clarion file
+entity IDs when the products are federated. Sprint 2 deliberately deferred WP10
+while it shipped the MCP consult surface and the ADR-029 entity-associations
+binding.
+
+That deferral is no longer the right default. Filigree now has its counterpart
+ADR and a cross-project sequencing memo:
+
+- `/home/john/filigree/docs/architecture/decisions/ADR-014-registry-backend-and-file-identity-displacement.md`
+- `/home/john/filigree/docs/plans/2026-05-19-registry-backend-cross-project-sequencing.md`
+
+Mirrored read-only copies are in `docs/federation/filigree-side/` so Clarion's
+repo carries the federation context. These are counterparts, not replacements:
+Clarion ADR-014 remains Accepted as-is, and ADR-029's `entity_associations`
+primitive stays intact.
+
+The live Clarion tree also confirms the missing implementation surface:
+
+- `crates/clarion-cli/src/serve.rs` serves MCP over stdio only.
+- No `axum`, `warp`, or `hyper` server imports exist under `crates/`.
+- No `resolve_file` implementation exists under `crates/`.
+- `crates/clarion-mcp/src/filigree.rs` already has the blocking `reqwest`
+  client pattern used for Filigree's `entity_associations` reverse lookup.
+
+Sprint 3 therefore anchors on the HTTP read API that Filigree's
+`ClarionRegistry` needs.
+
+---
+
+## 3. Amended Sprint 3 Scope
+
+### Anchor
+
+| Box | Owning WP | Deliverable | Anchoring decisions |
+|---|---|---|---|
+| **C-WP10** | WP10 | Clarion HTTP read API for Filigree's `ClarionRegistry` | Clarion ADR-014; Filigree ADR-014; system-design §9, §11; detailed-design §7 |
+
+### Clarion-side breakdown
+
+| Step | Title | Scope |
+|---|---|---|
+| **C-WP10.1** | `axum` HTTP read server in `clarion-cli` (new module) | Add the server shell and configurable bind/auth posture without changing MCP tool behavior. |
+| **C-WP10.2** | `GET /api/v1/files?path=&language=` endpoint | Resolve path/language to `{entity_id, content_hash, canonical_path, language}` from Clarion storage. |
+| **C-WP10.3** | Contracts directory + JSON fixture for `GET /api/v1/files` | Publish the Clarion-side contract Filigree can dry-run against. |
+| **C-WP10.4** | `GET /api/v1/_capabilities` endpoint | Expose `registry_backend: true` so Filigree's `ClarionRegistry` can fail fast. |
+| **C-WP10.5** | Wire HTTP server into `clarion serve` alongside MCP stdio | Start the HTTP read server without regressing existing MCP-over-stdio operation. |
+
+The Filigree sequencing memo used C-WP10.5 for this scope-amendment memo itself.
+This document satisfies that planning item; Clarion's local tracker uses
+C-WP10.5 for the serve-wiring implementation step requested for Sprint 3.
+
+### Out of scope
+
+- Changes to Clarion ADR-014, ADR-029, or any other existing ADR.
+- Any unwind of ADR-029 or the `entity_associations` table.
+- Filigree repository mutations; Filigree-side files are read-only inputs here.
+- Wardline-native emitter work.
+
+---
+
+## 4. Cross-Project Dependency Direction
+
+The dependency is one-way and should stay explicit:
+
+| Filigree phase | Relationship to Clarion Sprint 3 |
+|---|---|
+| **Phase B** — `RegistryProtocol` interface, `LocalRegistry`, behavior-preserving call-site refactor, additive schema columns | Independent. It can land before Clarion exposes HTTP because it has no observable `clarion` mode yet. |
+| **Phase C** — `registry_backend` flag, `ClarionRegistry`, capability probe, displaced-registration error, fail-closed behavior, migration verb | Blocks on **C-WP10.2** because the Clarion file-resolution endpoint is the first useful read contract. |
+| **Phase D** — cross-process integration tests | Blocks on both Clarion C-WP10.2/C-WP10.4 and Filigree Phase C. |
+| **Phase E** — docs and launch runbook | Lands after the contract and integration tests are stable. |
+
+The practical sequencing: Filigree Phase B may proceed in parallel; Clarion
+should ship C-WP10.1 -> C-WP10.2 -> C-WP10.4 -> C-WP10.5, with C-WP10.3 hanging
+off C-WP10.2 once the response shape is concrete.
+
+---
+
+## 5. v0.1 Plan Resequencing
+
+`v0.1-plan.md` originally framed WP10 as Filigree-side plus Wardline-side
+cross-product work and assumed the Filigree side would land from Filigree's own
+roadmap. That assumption is obsolete as of 2026-05-19: the Filigree-side ADR and
+sequencing memo now exist, and they require a Clarion HTTP read surface that is
+not implemented today.
+
+This amendment narrows Sprint 3 to the Clarion HTTP read API needed by
+Filigree's `ClarionRegistry`. The original WP10 Wardline/SARIF translator work
+remains valuable but is not the Sprint 3 anchor unless explicitly added later.
+
+---
+
+## 6. Tracker State to Create
+
+Create one planning milestone:
+
+- `Sprint 3 — WP10 Filigree federation read API (ADR-014)`
+
+Under it, create one phase:
+
+- `Clarion HTTP read API for Filigree's ClarionRegistry`
+
+Create the five C-WP10 steps in the order listed in §3, with dependencies:
+
+```text
+C-WP10.1 -> C-WP10.2 -> C-WP10.4 -> C-WP10.5
+C-WP10.3 depends on C-WP10.2
+```
+
+Add a milestone comment linking the Filigree tracker by title because the
+Filigree-side ID is not known in this repo:
+
+```text
+See /home/john/filigree's filigree tracker, milestone titled
+"Registry-backend & file-identity displacement (ADR-014)".
+```
+
+---
+
+## 7. What This Memo Does Not Change
+
+- Sprint 2 remains closed GREEN after repair.
+- ADR-029 remains the shipped peer primitive for issue-to-entity binding.
+- Clarion ADR-014 remains Accepted and is not edited by this amendment.
+- Clarion's MCP-over-stdio serve path remains live alongside the new opt-in
+  HTTP read API.
+- Filigree Phase B remains safe to land before Clarion; Filigree Phase C waits
+  for Clarion's file-resolution endpoint.
+
+---
+
+## 8. References
+
+- [Clarion ADR-014](../../clarion/adr/ADR-014-filigree-registry-backend.md)
+- [Clarion ADR-029](../../clarion/adr/ADR-029-entity-associations-binding.md)
+- [Clarion v0.1 plan §WP10](../v0.1-plan.md#wp10--cross-product-filigree--and-wardline-side-changes)
+- [Sprint 2 scope amendment](../sprint-2/scope-amendment-2026-05.md)
+- [Sprint 2 signoffs](../sprint-2/signoffs.md)
+- [Filigree ADR-014 mirror](../../federation/filigree-side/ADR-014-registry-backend-and-file-identity-displacement.md)
+- [Filigree cross-project sequencing memo mirror](../../federation/filigree-side/2026-05-19-registry-backend-cross-project-sequencing.md)
+
+---
+
+## 9. Implementation Closeout
+
+The Clarion-side WP10 implementation is complete in the local tracker:
+
+| Issue | Scope | Status |
+|---|---|---|
+| `clarion-44fbe093ca` | Sprint 3 WP10 milestone | `completed` |
+| `clarion-f082fb6a49` | Clarion HTTP read API phase | `completed` |
+| `clarion-e904d7a7ea` | C-WP10.1 HTTP read server module | `completed` |
+| `clarion-aea2d917f9` | C-WP10.2 `GET /api/v1/files` | `completed` |
+| `clarion-9d1379172f` | C-WP10.3 contract docs and fixtures | `completed` |
+| `clarion-95643a7d5e` | C-WP10.4 `GET /api/v1/_capabilities` | `completed` |
+| `clarion-2526c76071` | C-WP10.5 `clarion serve` HTTP wiring | `completed` |
+
+Implementation artifacts:
+
+- `crates/clarion-cli/src/http_read.rs` adds the `axum` HTTP read server.
+- `crates/clarion-cli/src/serve.rs` starts the HTTP read server when
+  `serve.http.enabled` is true and shuts it down after MCP stdio exits.
+- `crates/clarion-storage/src/query.rs` adds `resolve_file` for read-only file
+  identity resolution.
+- `crates/clarion-mcp/src/config.rs` adds `serve.http.enabled` and
+  `serve.http.bind` config.
+- `docs/federation/contracts.md` and `docs/federation/fixtures/*.json` pin the
+  Filigree-facing response shapes.
+
+Verification evidence:
+
+- `cargo fmt --all -- --check`
+- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+- `cargo build --workspace --bins`
+- `cargo nextest run --workspace --all-features` — 405 passed, 2 skipped
+- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features`
+- `cargo deny check` — passed with duplicate/unmatched-license warnings only
+- `bash tests/e2e/sprint_2_mcp_surface.sh`
+
+The Filigree Phase B/C dependency direction remains unchanged: Phase B can land
+independently, while Phase C needs Clarion's `/api/v1/files` contract.
diff --git a/docs/implementation/v0.1-plan.md b/docs/implementation/v0.1-plan.md
index da988175..92dcf131 100644
--- a/docs/implementation/v0.1-plan.md
+++ b/docs/implementation/v0.1-plan.md
@@ -1,11 +1,13 @@
 # Clarion v0.1 — Implementation Plan (High-Level Overview)
 
-**Status**: AMENDED — Sprint 1 closed (`v0.1-sprint-1`); Sprint 2 resequenced under [`sprint-2/scope-amendment-2026-05.md`](./sprint-2/scope-amendment-2026-05.md). The WP body below is the original framing and remains the architectural reference; the resequence memo is the authoritative source for what ships in v0.1 vs. what slips to v0.2. **Read both.**
+**Status**: AMENDED — Sprint 1 closed (`v0.1-sprint-1`); Sprint 2 resequenced under [`sprint-2/scope-amendment-2026-05.md`](./sprint-2/scope-amendment-2026-05.md) and closed (`v0.1-sprint-2`); Sprint 3 (Loom federation hardening, ADR-014 → ADR-034) closed 2026-05-19 — see [`sprint-3/2026-05-19-loom-federation-hardening-tasking.md`](./sprint-3/2026-05-19-loom-federation-hardening-tasking.md). The WP body below is the original framing and remains the architectural reference; the Sprint 2 resequence memo and Sprint 3 tasking doc are the authoritative sources for what shipped in v1.0 vs. what slips to v1.1+. **Read all three.**
 **Date opened**: 2026-04-18
-**Last amended**: 2026-05-16
+**Last amended**: 2026-05-19
 **Plan owner**: John Morrissey (primary dev of Clarion, Filigree, Wardline)
-**Predecessor**: [`../clarion/v0.1/plans/v0.1-scope-commitments.md`](../clarion/v0.1/plans/v0.1-scope-commitments.md) (scope locked 2026-04-18)
-**Amendments**: [`sprint-2/scope-amendment-2026-05.md`](./sprint-2/scope-amendment-2026-05.md) (2026-05-16 — narrows WP6, splits WP9 into A/B, defers WP4/5/7/10/11-as-scheduled, pulls WP8 + WP9-A into Sprint 2 for MVP MCP surface)
+**Predecessor**: [`../clarion/v0.1/plans/v0.1-scope-commitments.md`](./v0.1-scope-plans/v0.1-scope-commitments.md) (scope locked 2026-04-18)
+**Amendments**:
+- [`sprint-2/scope-amendment-2026-05.md`](./sprint-2/scope-amendment-2026-05.md) (2026-05-16 — narrows WP6, splits WP9 into A/B, defers WP4/5/7/10/11-as-scheduled, pulls WP8 + WP9-A into Sprint 2 for MVP MCP surface).
+- [`sprint-3/2026-05-19-loom-federation-hardening-tasking.md`](./sprint-3/2026-05-19-loom-federation-hardening-tasking.md) (2026-05-19 — Loom federation hardening sprint: bearer auth, batch resolution, `BRIEFING_BLOCKED` propagation, per-project `instance_id`; pinned in ADR-034). Closed alongside the v1.0 release.
 **Audience**: implementation engineer (the author + future contributors), Filigree-side
 issue-tracker seeder, design reviewers checking that every system-design section has an
 owning work package.
@@ -713,7 +715,7 @@ ownership decision).
 
 ### WP11 — Post-implementation cost/perf validation
 
-**Anchoring docs**: [`../clarion/v0.1/plans/v0.1-scope-commitments.md`](../clarion/v0.1/plans/v0.1-scope-commitments.md)
+**Anchoring docs**: [`../clarion/v0.1/plans/v0.1-scope-commitments.md`](./v0.1-scope-plans/v0.1-scope-commitments.md)
 §"Validation".
 
 **Accepted ADRs**: none — this is a measurement task, not a design task.
@@ -810,5 +812,5 @@ Seeding is **not** done by this plan; it is a follow-up action item.
 - [Clarion v0.1 system design](../clarion/v0.1/system-design.md)
 - [Clarion v0.1 detailed design](../clarion/v0.1/detailed-design.md)
 - [Clarion ADR index](../clarion/adr/README.md)
-- [v0.1 scope commitments memo](../clarion/v0.1/plans/v0.1-scope-commitments.md)
+- [v0.1 scope commitments memo](./v0.1-scope-plans/v0.1-scope-commitments.md)
 - [Loom suite doctrine](../suite/loom.md)
diff --git a/docs/implementation/v0.1-publish/thread-1-pre-publish-blockers.md b/docs/implementation/v0.1-publish/thread-1-pre-publish-blockers.md
index 2b9a84a5..4deeb35b 100644
--- a/docs/implementation/v0.1-publish/thread-1-pre-publish-blockers.md
+++ b/docs/implementation/v0.1-publish/thread-1-pre-publish-blockers.md
@@ -3,7 +3,7 @@
 > **For agentic workers:** REQUIRED SUB-SKILL: `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans`. Each workstream is independently dispatchable; sequencing is described in §1.
 
 **Status**: drafted 2026-05-18 — not yet broken into Filigree issues.
-**Predecessor context**: Sprint 2 closed GREEN ([`../sprint-2/signoffs.md`](../sprint-2/signoffs.md)); the 2026-05-18 codebase archaeology ([`../../arch-analysis-2026-05-18-1244/04-final-report.md`](../../arch-analysis-2026-05-18-1244/04-final-report.md)) is the authoritative current-state snapshot.
+**Predecessor context**: Sprint 2 closed GREEN ([`../sprint-2/signoffs.md`](../sprint-2/signoffs.md)); the 2026-05-20 RC1 codebase archaeology ([`../../arch-analysis-2026-05-20-2124/04-final-report.md`](../arch-analysis-2026-05-20-2124/04-final-report.md)) supersedes the removed 2026-05-18 snapshot as the current-state reference.
 **Goal**: take the amended-v0.1 MCP-MVP from "works on the elspeth-slice corpus on the author's box" to "publishable v0.1" — meaning *an outside operator can install it, point it at an arbitrary repo without leaking secrets, and find their way to first value in five minutes*.
 
 **Scope discipline**: this is *only* Thread 1 (pre-publish operational/security blockers). Two adjacent threads exist and are NOT in this program:
@@ -195,7 +195,7 @@ This is the consult-mode-agent surface for "the absence of a summary is policy,
 #### Task 6 — Rule catalogue entries in `detailed-design.md`
 
 **Files**:
-- Modify: `docs/clarion/v0.1/detailed-design.md` (§5 rule catalogue)
+- Modify: `docs/clarion/1.0/detailed-design.md` (§5 rule catalogue)
 
 **Scope**: append rule rows for `CLA-SEC-SECRET-DETECTED`, `CLA-SEC-UNREDACTED-SECRETS-ALLOWED`, `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION`, `CLA-INFRA-SECRET-BASELINE-MATCH`, `CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED`. Each row: rule-ID, severity, category, one-sentence description, one-sentence remediation, ADR pointer.
 
@@ -230,7 +230,7 @@ All tasks green; in addition:
 **Files**:
 - Create: `README.md` at repo root.
 
-**Scope**: there is no top-level README currently. The reader-ladder under `docs/suite/briefing.md` → `docs/suite/loom.md` → `docs/clarion/v0.1/README.md` assumes the reader already knows to start there. A first-time visitor (PyPI / crates.io / GitHub front page) has no entry point.
+**Scope**: there is no top-level README currently. The reader-ladder under `docs/suite/briefing.md` → `docs/suite/loom.md` → `docs/clarion/1.0/README.md` assumes the reader already knows to start there. A first-time visitor (PyPI / crates.io / GitHub front page) has no entry point.
 
 The README must answer, in order:
 
@@ -238,7 +238,7 @@ The README must answer, in order:
 2. **What it does today** — bullet list of the 7 MCP tools and what each answers, with one example invocation each.
 3. **Quick start** — `clarion install && clarion analyze && clarion serve`, with the expected stdout shapes. Link to the operator tutorial (Task B.2).
 4. **Status** — explicit "v0.1 — Python only; structural + on-demand LLM summarisation; Filigree finding emission deferred to v0.2." Quote the scope: don't oversell.
-5. **Project layout** — three-sentence map (Rust workspace + Python plugin + docs) with links to `docs/clarion/v0.1/README.md` for the design ladder and `docs/clarion/adr/README.md` for the ADR index.
+5. **Project layout** — three-sentence map (Rust workspace + Python plugin + docs) with links to `docs/clarion/1.0/README.md` for the design ladder and `docs/clarion/adr/README.md` for the ADR index.
 6. **Contributing** — pointer to `CLAUDE.md` and the test commands (ADR-023 floor).
 
 **Length target**: ≤ 200 lines. No installation instructions deeper than `cargo install ...` + `pipx install clarion-plugin-python` (Workstream C delivers the actual commands).
@@ -430,4 +430,4 @@ filigree close clarion-2d178ddda0 --reason="superseded by Publish-prep --force t
 - [System design — §10 Security, pre-ingest redaction paragraph](../../clarion/v0.1/system-design.md)
 - [v0.1-plan.md — WP5 scope](../v0.1-plan.md#wp5--pre-ingest-secret-scanner)
 - [Sprint-2 scope amendment — explicit WP5 deferral rationale, "production deployment against unknown corpora gates on this returning"](../sprint-2/scope-amendment-2026-05.md)
-- [Arch analysis final report — §7 follow-ups #9 (L-1) and §5.3 L-2 (closed)](../../arch-analysis-2026-05-18-1244/04-final-report.md)
+- [Arch analysis final report — current RC1 architecture report](../arch-analysis-2026-05-20-2124/04-final-report.md)
diff --git a/docs/implementation/v0.1-publish/ws-a-secret-scanner.md b/docs/implementation/v0.1-publish/ws-a-secret-scanner.md
new file mode 100644
index 00000000..7c2005f7
--- /dev/null
+++ b/docs/implementation/v0.1-publish/ws-a-secret-scanner.md
@@ -0,0 +1,1027 @@
+# Workstream A — WP5 Pre-Ingest Secret Scanner (detailed package)
+
+**Status**: DRAFT — not yet seeded into Filigree; awaiting kickoff.
+**Predecessor**: [`thread-1-pre-publish-blockers.md` §2](./thread-1-pre-publish-blockers.md#2-workstream-a--wp5-pre-ingest-secret-scanner)
+**Successor**: Workstream D — external-operator smoke test (publish gate).
+**Spec source**: [ADR-013 — Pre-Ingest Secret Scanner with LLM-Dispatch Block](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) (Accepted; do not re-litigate).
+**Anchoring ADRs**: [ADR-007 (cache key)](../../clarion/adr/ADR-007-summary-cache-key.md), [ADR-013](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md), [ADR-017 (severity + dedup)](../../clarion/adr/ADR-017-severity-and-dedup.md), [ADR-021 (plugin authority hybrid)](../../clarion/adr/ADR-021-plugin-authority-hybrid.md), [ADR-022 (core/plugin ontology)](../../clarion/adr/ADR-022-core-plugin-ontology.md), [ADR-023 (tooling baseline)](../../clarion/adr/ADR-023-tooling-baseline.md).
+**Requirements floor**: `NFR-SEC-01` (pre-ingest scan + block + baseline), `NFR-SEC-04` (security events as findings), `NFR-OPS-01` / `NFR-OPS-04` (single-binary distribution).
+**Effort estimate**: 6–9 working days at agentic velocity. Tasks 1 and 2 parallelisable; 3 → 4 → 5 sequential; 6 + 7 parallel with any.
+
+**Accuracy as of 2026-05-19**: code-path references and line numbers in this
+planning package were last checked against the `scanner` branch. Treat symbol
+names as authoritative and line numbers as historical orientation only.
+
+---
+
+## 1. Purpose
+
+WP5 closes the design-review CRITICAL flag on secret exfiltration: every byte
+reaching the LLM provider must first pass a Clarion-owned scanner. ADR-013
+locked the behaviour; this document turns the ADR into seven implementation
+tasks an agent (or two agents working in parallel) can execute, and pins the
+file paths, public APIs, schema changes, rule-ID catalogue entries, and tests
+each task is responsible for.
+
+The workstream is the only one of Thread-1's four with significant
+engineering weight; B and C are docs + packaging. WP5 ships green before the
+publish-gate smoke test in Workstream D can attempt step 8 (the planted-`.env`
+case).
+
+## 2. Scope
+
+In scope (this work package):
+
+- New workspace crate `crates/clarion-scanner/` implementing the ADR-013
+  rule set as Rust-native regex + Shannon entropy detection.
+- Baseline parser for `.clarion/secrets-baseline.yaml` (`detect-secrets`
+  v1.x format).
+- CLI wiring: pre-ingest pass in `clarion-cli::analyze::run` between
+  source-tree walk and per-plugin dispatch.
+- `--allow-unredacted-secrets` override surface with TTY + non-TTY gates.
+- MCP-side awareness of `briefing_blocked: secret_present` in
+  `crates/clarion-mcp/`'s `summary` tool dispatch.
+- Five new `CLA-SEC-*` / `CLA-INFRA-SECRET-*` rule-IDs in the
+  `detailed-design.md` §5 catalogue.
+- Operator documentation under `docs/operator/secret-scanning.md`.
+
+Out of scope (deferred or owned elsewhere):
+
+- Filigree emission of `CLA-SEC-*` findings — WP9-B, v0.2.
+- Custom-rule integration from Wardline — v0.2.
+- Post-ingest scanning on LLM responses — v0.2+ additive defence.
+- Redaction-instead-of-block (ADR-013 Alternative 2) — v0.2+ with opt-in.
+- The override-finding monitoring loop (filigree-side dashboard work) — not
+  part of v0.1 publish.
+- Windows support — `setrlimit` is Unix-only (`clarion-core::plugin::limits`);
+  WP5 follows the same posture.
+
+## 3. Locked surfaces and pre-existing context
+
+WP5 reads from and writes to surfaces already present at `main`:
+
+- Workspace at `Cargo.toml` (resolver 3, Rust 2024, MSRV 1.88). Current
+  members: `clarion-core`, `clarion-storage`, `clarion-cli`, `clarion-mcp`,
+  `clarion-plugin-fixture`. The scanner becomes the **sixth**.
+- `crates/clarion-cli/src/analyze.rs` already contains:
+  - `pub async fn run(project_path: PathBuf) -> Result<()>` at line 52.
+  - `fn collect_source_files(root, wanted_extensions) -> Vec<PathBuf>` at
+    line 1740 — the walk WP5's pre-ingest hook intercepts immediately after.
+  - `RunOutcome::SoftFailed { reason }` at line 1038 — the partial-success
+    path the override-unconfirmed exit must NOT take (override-unconfirmed
+    runs never start a `runs` row at all).
+- `crates/clarion-core/src/plugin/host.rs`:
+  - `pub struct RawEntity { … extra … }` at line 105 — the `extra` field is
+    the carrier for `briefing_blocked`. Per the host doc-comment at line 74
+    and 222, `extra` flows into `properties_json` downstream.
+  - `pub struct HostFinding` at `plugin/host_findings.rs:84` with subcode
+    constructors (`HostFinding::malformed_entity`, etc.) — the pattern WP5's
+    finding constructors follow.
+- `crates/clarion-mcp/src/lib.rs`:
+  - `fn entity_properties_json(entity: &EntityRow) -> Value` at line 2382 —
+    central reader for `properties_json`; WP5's MCP awareness layer hooks
+    above this, before LLM dispatch.
+  - `fn summary_scope_deferred(entity: &EntityRow) -> Value` at line 2341 —
+    precedent for the "absence is policy" envelope shape WP5 introduces
+    (`briefing_blocked: secret_present`).
+- `serde_norway` is already a workspace dep (replaced `serde_yaml` per
+  commit `9ffc5c8`). WP5 reuses it for baseline YAML.
+
+Surfaces this package does NOT touch:
+
+- Plugin protocol (no `analyze_file` RPC change).
+- Writer-actor command set in `crates/clarion-storage/` — the scanner
+  produces `HostFinding`s and entity `extra` map entries; no new
+  `WriterCmd` variants.
+- SQLite schema — no new tables or columns. `entities.properties` and
+  `runs.stats` are existing JSON-bearing columns; WP5 adds key/value pairs.
+
+### 3.1 Finding-write channel (load-bearing distinction)
+
+The codebase has two distinct "finding" concepts; WP5 emits into one of them.
+
+- **`HostFinding`** (`crates/clarion-core/src/plugin/host_findings.rs:84`) is
+  a plugin-host **integrity event**: subcode + message + structured metadata
+  map. It carries no severity, no `rule_id`, no `(file, line)` slot. It is
+  drained via `PluginHost::take_findings` and logged through
+  `log_plugin_findings` (`analyze.rs:1042`). Per the doc-comment at line
+  79–82, "for Sprint 1 they are collected only" — they are NOT persisted to
+  the `findings` table.
+- **`FindingRecord`** (`crates/clarion-storage/src/commands.rs:113`) is the
+  ADR-004 finding shape that the writer-actor persists. It carries
+  `rule_id`, `severity`, `entity_id`, `message`, `evidence_json`,
+  `properties_json`, lifecycle status, etc. Write path: send
+  `WriterCmd::InsertFinding { finding: Box<FindingRecord>, ack }` through
+  the existing `send_wait` channel.
+
+**WP5 emits `FindingRecord` via `WriterCmd::InsertFinding`.** Precedent:
+`insert_weak_modularity_finding` at `analyze.rs:907–965` is the existing
+pattern for a CLI-side, application-level finding emitted directly through
+the writer. WP5's `secret_scan` module follows that pattern verbatim —
+build a `FindingRecord`, send via the writer's command channel, await ack.
+
+`HostFinding` is **not** the channel for `CLA-SEC-*` / `CLA-INFRA-SECRET-*`
+because (a) it lacks the severity / rule-ID slots ADR-013 mandates and
+(b) it is not persisted. The Thread-1 §2.A.1 reference to "the existing
+`HostFinding` → `WriterCmd::InsertEntity` path" is imprecise; the
+authoritative channel is `WriterCmd::InsertFinding`.
+
+For each detection, the `FindingRecord` is populated:
+
+| Field | Value |
+|---|---|
+| `id` | `uuid::Uuid::new_v4().to_string()` |
+| `tool` | `"clarion"` |
+| `tool_version` | `env!("CARGO_PKG_VERSION")` |
+| `run_id` | current run's `run_id` |
+| `rule_id` | `"CLA-SEC-SECRET-DETECTED"` (or other; see §6 catalogue) |
+| `kind` | `"defect"` (per ADR-004; secrets are defects pending remediation) |
+| `severity` | `"ERROR"` (or `"INFO"` for `CLA-INFRA-SECRET-BASELINE-MATCH`) |
+| `confidence` | `Some(1.0)` for named-pattern matches; `Some(0.6)` for high-entropy detections (rough heuristic — refine in Task 1) |
+| `confidence_basis` | `Some("pattern")` or `Some("entropy")` |
+| `entity_id` | `core:file:{blake3(relative_path)}` synthetic file anchor for file-level findings; the file path is also retained in `evidence_json` |
+| `related_entities_json` | `"[]"` |
+| `message` | one-line human-readable, e.g. `"AWS access key detected in src/api/keys.py:42"` (the literal bytes NEVER appear in this string) |
+| `evidence_json` | `{"file_path": "...", "line_number": 42, "rule": "AwsAccessKeyId", "hashed_secret_hex": "..."}` |
+| `properties_json` | `"{}"` |
+| `supports_json` / `supported_by_json` | `"[]"` |
+| `created_at` / `updated_at` | run's `started_at` (deterministic) |
+
+## 4. Architecture at a glance
+
+```
+clarion analyze <root>
+   │
+   ├─ collect_source_files(...)                                    [unchanged]
+   │
+   ├─ secret_scan::pre_ingest(source_files, baseline) ──► WP5 entry point
+   │      │
+   │      ├─ For each file:
+   │      │     1. mmap or read buffer
+   │      │     2. Scanner::scan_bytes(&buf) ─► Vec<Detection>
+   │      │     3. baseline.suppress(detections, path)
+   │      │     4. partition allowed/suppressed
+   │      │
+   │      ├─ If TTY and allowed.is_empty() == false:
+   │      │     interactive prompt (per ADR-013 §Override)
+   │      │
+   │      ├─ Returns:
+   │      │     - blocked: BTreeMap<PathBuf, Vec<Detection>>
+   │      │     - findings: Vec<HostFinding>      (SEC-* + INFRA-SECRET-*)
+   │      │     - override_state: OverrideState
+   │      │
+   │      └─ If override_unconfirmed → return Err → exit 78 (EX_CONFIG)
+   │
+   ├─ run_plugins(..., blocked) ─► plugins still analyse blocked files;
+   │                                host stamps `briefing_blocked` into
+   │                                RawEntity.extra for blocked files
+   │
+   ├─ writer persists entities (properties_json carries the flag)
+   │
+   └─ summary_pass / MCP serve / etc. → read briefing_blocked,
+                                         skip LLM dispatch
+```
+
+Two invariants hold for any reader at any time:
+
+- The scanner runs **before** any plugin process is spawned. ADR-013
+  §"Plugin-boundary interaction" — file buffers reach Anthropic only via
+  Phase 4–6 summarisation, which is gated by `briefing_blocked`.
+- The override path **never** silently bypasses. Non-TTY without confirm
+  flag exits 78 *before* a `runs` row is created.
+
+## 5. Task breakdown
+
+Each task fits one agent pass (≤ ~500 LOC plus tests). Tasks 1 and 2 are
+independent and can parallelise; 3 depends on 1 + 2; 4 depends on 3; 5
+depends on 3; 6 + 7 are documentation, parallel with any.
+
+### Task 1 — Scanner crate, rule registry, entropy
+
+**Owner**: `crates/clarion-scanner/`
+**Estimated size**: 350–500 LOC including tests.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| create | `crates/clarion-scanner/Cargo.toml` |
+| create | `crates/clarion-scanner/src/lib.rs` |
+| create | `crates/clarion-scanner/src/patterns.rs` |
+| create | `crates/clarion-scanner/src/entropy.rs` |
+| create | `crates/clarion-scanner/tests/fixtures/*.txt` (positive + negative per rule) |
+| create | `crates/clarion-scanner/tests/scanner.rs` |
+| modify | `Cargo.toml` (workspace root) — add `crates/clarion-scanner` member |
+
+#### Scope
+
+Implement the named-credential regex table from ADR-013 lines 35–38 (AWS
+access keys, AWS secret adjacency, GitHub PATs / OAuth tokens, Anthropic
+keys, OpenAI keys, Stripe keys, Slack tokens, JWT, RSA/EC/DSA/OpenSSH
+private-key headers, contextual-credential `name=value` patterns).
+Implement Shannon entropy detection over byte slices with the bounds
+ADR-013 §Implementation specifies (base64 ≥ 4.5 entropy over ≥20 chars; hex
+≥ 3.0 over ≥40 chars). UUIDs and short tokens must NOT trip the entropy
+rule (positive/negative fixtures enforce this).
+
+#### Public surface
+
+```rust
+pub struct Scanner {
+    patterns: regex::RegexSet,
+    pattern_meta: Vec<PatternMeta>,
+    entropy_b64: EntropyTuning,
+    entropy_hex: EntropyTuning,
+}
+
+pub struct Detection {
+    pub rule_id: &'static str,         // e.g. "AwsAccessKeyId", "HighEntropyBase64"
+    pub category: SecretCategory,
+    pub byte_offset: usize,
+    pub line_number: u32,
+    pub matched_len: usize,            // never persist the literal bytes
+    pub hashed_secret: [u8; 20],       // sha1, baseline-compat
+}
+
+pub enum SecretCategory {
+    CloudCredential,                   // AWS, GCP, Azure
+    VcsCredential,                     // GitHub PATs, OAuth
+    AiProviderCredential,              // Anthropic, OpenAI
+    PaymentsCredential,                // Stripe
+    MessagingCredential,               // Slack
+    PrivateKey,                        // RSA/EC/DSA/OpenSSH/PGP
+    JwtToken,
+    HighEntropy,
+    ContextualCredential,              // password=, api_key=...
+}
+
+impl Scanner {
+    pub fn new() -> Self;               // default thresholds per ADR-013
+    pub fn scan_bytes(&self, buf: &[u8]) -> Vec<Detection>;
+}
+```
+
+`Detection::hashed_secret` is sha1 over the literal matched bytes, computed
+**at detection time**; the literal never lives anywhere downstream. This is
+the same convention `detect-secrets` uses so baseline files round-trip.
+
+#### Dependency budget
+
+The scanner crate is intentionally a leaf:
+
+- `regex` (workspace already pulls it for elsewhere)
+- `sha1` (new — small, well-maintained)
+- No `tokio`, no `rusqlite`, no `serde_norway`.
+
+Verification at exit: `cargo tree -p clarion-scanner | head -30` shows no
+`tokio` or `rusqlite` ancestors. If a downstream crate's `regex` features
+leak something heavier, pin the feature set in `clarion-scanner`'s
+`Cargo.toml`.
+
+#### Tests
+
+`crates/clarion-scanner/tests/scanner.rs`:
+
+- One positive + one negative fixture per named pattern (AWS access key,
+  GitHub PAT `ghp_…`, GitHub fine-grained `github_pat_…`, Anthropic
+  `sk-ant-…`, OpenAI `sk-…`, Stripe `sk_live_…`, Slack `xoxb-…`, JWT
+  `eyJ…`, RSA private-key header, OpenSSH private-key header).
+- High-entropy positives: 32-char random base64, 64-char random hex.
+- High-entropy negatives: UUIDs, base64-encoded SHA256 checksums (these
+  are high-entropy but commonly safe — confirm whether to suppress; if
+  not, document in the operator doc as a known-baseline candidate).
+- Contextual-credential positives: `password = "..."`, `api_key: "…"`,
+  `SECRET_TOKEN := "…"`.
+- Contextual-credential negatives: `password_hash = "…"` (post-hash safe),
+  `# password placeholder` (comments).
+
+#### Exit criteria
+
+- `cargo test -p clarion-scanner` green.
+- `cargo clippy -p clarion-scanner -- -D warnings` clean.
+- `cargo tree -p clarion-scanner` shows no `tokio` / `rusqlite` /
+  `serde_norway` deps.
+- `cargo build --workspace` green (new crate compiles into the workspace
+  without changing existing build).
+
+---
+
+### Task 2 — Baseline parser (`.clarion/secrets-baseline.yaml`)
+
+**Owner**: `crates/clarion-scanner/`
+**Estimated size**: 200–300 LOC including tests.
+**Parallelisable with Task 1**: yes — touches separate module.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| create | `crates/clarion-scanner/src/baseline.rs` |
+| modify | `crates/clarion-scanner/src/lib.rs` (re-export) |
+| create | `crates/clarion-scanner/tests/fixtures/baselines/*.yaml` |
+| modify | `crates/clarion-scanner/tests/scanner.rs` OR new `tests/baseline.rs` |
+
+#### Scope
+
+Parse the `detect-secrets` v1.x baseline schema (ADR-013 §Baseline). Schema
+fields required:
+
+```yaml
+version: "1.0"                # must equal "1.0"
+results:
+  "<relative-path>":          # repository-relative path
+    - type: "<detect-secrets pattern name>"
+      hashed_secret: "<hex sha1>"
+      line_number: 42
+      is_secret: false        # operator declares not-a-secret
+      justification: "..."    # REQUIRED (ADR-013 line 71)
+```
+
+`justification` missing → emit `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION`
+(at load time, surfaces during CLI startup; one finding per offending
+entry).
+
+Match-then-suppress at `Detection` granularity, keyed on
+`(file_path, hashed_secret, line_number)`. Both `allowed` and `suppressed`
+partitions are retained so the CLI can emit one `CLA-SEC-SECRET-DETECTED`
+per unsuppressed detection AND one `CLA-INFRA-SECRET-BASELINE-MATCH`
+info-level finding per *actually-fired* baseline entry (the audit-surface
+requirement of `NFR-SEC-04`).
+
+`is_secret: true` in a baseline entry is treated as **not a suppression** —
+the operator is declaring the entry IS a real secret they haven't fixed
+yet; behaviour is identical to no baseline entry at all. (This mirrors
+`detect-secrets`' convention.)
+
+#### Public surface
+
+```rust
+pub struct Baseline {
+    version: String,
+    entries: BTreeMap<PathBuf, Vec<BaselineEntry>>,
+}
+
+pub struct BaselineEntry {
+    pub rule_type: String,           // detect-secrets type name
+    pub hashed_secret: [u8; 20],
+    pub line_number: u32,
+    pub is_secret: bool,
+    pub justification: String,
+}
+
+pub struct SuppressionResult {
+    pub allowed: Vec<Detection>,     // detections that survive suppression
+    pub suppressed: Vec<Detection>,  // detections suppressed by a baseline entry
+    pub fired_entries: Vec<BaselineMatch>,  // baseline entries that actually matched
+}
+
+pub fn load_baseline(path: &Path) -> Result<Baseline, BaselineError>;
+
+impl Baseline {
+    pub fn empty() -> Self;          // path-absent path (NOT an error)
+    pub fn suppress(
+        &self,
+        detections: Vec<Detection>,
+        file: &Path,
+    ) -> SuppressionResult;
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum BaselineError {
+    #[error("baseline version mismatch: expected 1.0, got {0}")]
+    UnsupportedVersion(String),
+    #[error("baseline entry missing required field 'justification' at {file}:{line}")]
+    MissingJustification { file: PathBuf, line: u32 },
+    #[error("baseline parse error: {0}")]
+    Parse(#[from] serde_norway::Error),
+    #[error("baseline I/O error: {0}")]
+    Io(#[from] std::io::Error),
+}
+```
+
+`load_baseline` returns `Ok(Baseline::empty())` if the file does not exist
+(this is the common case — operators add a baseline only after the first
+false positive). It errors only on parse failure, version mismatch, or
+missing required fields.
+
+#### Tests
+
+- Fixture baseline + scanner detections → asserts `allowed` and
+  `suppressed` partitions match expected.
+- Missing `justification` → `BaselineError::MissingJustification` returned.
+- Baseline file absent → `Baseline::empty()` returned, no error.
+- Round-trip: parse → serialise → parse → byte-identical (subject to
+  YAML serialisation determinism with `serde_norway`).
+- Path-relativity test: baseline keys are repository-relative; scanner
+  passes absolute paths. The suppression layer normalises before matching.
+  Document the normalisation rule and assert it.
+
+#### Exit criteria
+
+- `cargo test -p clarion-scanner` (combined with Task 1) green.
+- Round-trip baseline test passes.
+- `BaselineError` is the only error type leaking out of the module; no
+  bare `anyhow::Error` at the public surface.
+
+---
+
+### Task 3 — CLI wiring: pre-ingest hook in `analyze::run`
+
+**Owner**: `crates/clarion-cli/`
+**Estimated size**: 300–400 LOC including the new orchestration module + tests.
+**Depends on**: Task 1, Task 2.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| create | `crates/clarion-cli/src/secret_scan.rs` (orchestration module — keep `analyze.rs` from growing further per arch-analysis H-1) |
+| modify | `crates/clarion-cli/src/analyze.rs` |
+| modify | `crates/clarion-cli/Cargo.toml` (add `clarion-scanner` dep) |
+| modify | `crates/clarion-core/src/plugin/host.rs` (stamp `briefing_blocked` into RawEntity.extra for blocked files — see "Host integration" below) |
+| create | `crates/clarion-cli/tests/secret_scan.rs` (integration tests) |
+| create | `crates/clarion-cli/tests/fixtures/secret-project/...` (fixture trees) |
+
+#### Scope
+
+Between `collect_source_files` (`analyze.rs:1740`) and the per-plugin
+processing loop, insert a pre-ingest scan pass:
+
+1. Load `.clarion/secrets-baseline.yaml` via Task 2's `load_baseline`.
+2. For each file in `source_files`:
+   a. Read the file buffer.
+   b. `Scanner::scan_bytes(&buf)` → `Vec<Detection>`.
+   c. `baseline.suppress(detections, path)` → `SuppressionResult`.
+3. Build a `BlockSet: BTreeMap<PathBuf, BlockReason>` of files with
+   non-empty `allowed`. `BlockReason` is an enum with a single variant at
+   v0.1:
+
+   ```rust
+   pub enum BlockReason {
+       SecretPresent,  // ADR-013: rendered as "secret_present" in properties_json
+   }
+   ```
+
+   The string-on-the-wire form is `"secret_present"`. Future variants
+   (e.g. `SizeCapExceeded`) would add new string values; readers treat
+   `briefing_blocked` as open-vocabulary.
+
+4. Emit findings via `WriterCmd::InsertFinding` (see §3.1):
+   - One `CLA-SEC-SECRET-DETECTED` per `allowed` detection (severity
+     `ERROR`).
+   - One `CLA-INFRA-SECRET-BASELINE-MATCH` per `fired_entries` element
+     (severity `INFO`).
+   - One `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION` per
+     `BaselineError::MissingJustification` surfaced at load time.
+5. Pass the `BlockSet` through to the per-plugin processing loop so the
+   plugin host can stamp `briefing_blocked: secret_present` into the
+   `RawEntity.extra` for each entity coming out of those files.
+
+#### Host integration
+
+The plugin host (`crates/clarion-core/src/plugin/host.rs`) currently
+accepts `RawEntity` from the plugin and translates `extra` into
+`properties_json` downstream (host.rs:74, 222). WP5 adds one path:
+
+- The host receives a `BTreeMap<PathBuf, BlockReason>` at spawn time (via
+  a new field on the existing host configuration struct, or via a setter —
+  pick the smaller diff). For each entity whose `source.path` is in the
+  block map, the host inserts `"briefing_blocked": "secret_present"` into
+  the entity's `extra` map **after** the plugin returns, **before**
+  serialisation to `properties_json`.
+
+This keeps the per-plugin code untouched. Plugins do not need to know
+about secret scanning; the host stamps the flag on its way through.
+
+Rationale: the alternative (passing block info to the plugin so the plugin
+emits the flag) would require changing the plugin protocol — out of scope
+for v0.1.
+
+#### Tests
+
+`crates/clarion-cli/tests/secret_scan.rs`:
+
+1. **Happy path — clean project**: fixture with no secrets → `analyze`
+   exits 0; no `CLA-SEC-*` findings persisted.
+2. **One file with AWS key in `.env`**: fixture with a committed `.env`
+   containing `AKIAIOSFODNN7EXAMPLE` →
+   - `analyze` exits 0 with `RunOutcome::Completed`. Secret detection
+     produces findings but does **not** affect the run outcome — the
+     structural extraction succeeded, the security finding is the
+     audit signal, and `SoftFailed` is reserved for actual plugin
+     failures.
+   - `entities` table has rows for the `.env` file's structural entities.
+   - Those entities' `properties_json` contains
+     `"briefing_blocked":"secret_present"`.
+   - `findings` table has one `CLA-SEC-SECRET-DETECTED` row referencing
+     the file.
+3. **Baseline suppression**: same `.env` fixture + a `.clarion/secrets-baseline.yaml`
+   with the matching entry → no `CLA-SEC-SECRET-DETECTED` finding; one
+   `CLA-INFRA-SECRET-BASELINE-MATCH` info-level finding; no
+   `briefing_blocked` flag on entities.
+4. **Baseline missing justification**: malformed baseline →
+   `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION` finding; analyze
+   completes with `RunOutcome::Completed` (load errors degrade to
+   "treat baseline as empty + surface finding", they do not abort the
+   run and do not promote it to `SoftFailed`).
+5. **Multi-file project**: secret in 1 of 10 files → 9 unblocked, 1
+   blocked; entity counts match expectation.
+
+#### Exit criteria
+
+- All five integration tests green.
+- `crates/clarion-cli/src/secret_scan.rs` ≤ 250 LOC (the orchestration
+  module; arch-analysis H-1 ceiling).
+- `analyze.rs` net growth ≤ 30 LOC (the new module owns the body; analyze
+  delegates).
+- The walking-skeleton E2E (`tests/e2e/sprint_1_walking_skeleton.sh`)
+  still passes — clean fixture must not regress.
+- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+  clean.
+
+---
+
+### Task 4 — Override semantics: `--allow-unredacted-secrets`
+
+**Owner**: `crates/clarion-cli/`
+**Estimated size**: 250–350 LOC including tests.
+**Depends on**: Task 3.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| modify | `crates/clarion-cli/src/cli.rs` (clap definition) |
+| modify | `crates/clarion-cli/src/secret_scan.rs` (override logic) |
+| modify | `crates/clarion-cli/tests/secret_scan.rs` (override tests) |
+
+#### Scope
+
+Implement the override path per ADR-013 §Override.
+
+CLI surface (additions to the `analyze` subcommand):
+
+```rust
+#[derive(Args)]
+pub struct AnalyzeArgs {
+    // ... existing fields ...
+    /// Allow analysis of files containing unredacted secrets. REQUIRES a
+    /// confirmation step (interactive prompt or --confirm-allow-unredacted-secrets).
+    #[arg(long)]
+    pub allow_unredacted_secrets: bool,
+
+    /// Non-TTY confirmation token for --allow-unredacted-secrets.
+    /// Must be the literal string "yes-i-understand".
+    #[arg(long, value_name = "TOKEN", requires = "allow_unredacted_secrets")]
+    pub confirm_allow_unredacted_secrets: Option<String>,
+}
+```
+
+Behaviour:
+
+- **No detections**: flag is a no-op (do NOT prompt; do NOT emit override
+  findings). Document this in the operator doc so operators can safely
+  leave the flag set in CI configurations.
+- **Detections present, no override flag**: existing block behaviour
+  (Task 3) — `briefing_blocked` stamped, `CLA-SEC-SECRET-DETECTED`
+  emitted, analyze continues for structural pass.
+- **Detections present, `--allow-unredacted-secrets` only, TTY**:
+  - Print detection summary to stderr (file path, line, rule-ID, but
+    NEVER the matched bytes).
+  - Prompt: `Type 'yes-i-understand' to proceed: `.
+  - Match → proceed without blocking; emit
+    `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` per affected file; record
+    `override_used: true, files_affected: [...]` in `runs.stats`.
+  - Anything else (EOF, mismatched string, `^C`) → exit 78 (`EX_CONFIG`);
+    no `runs` row started.
+- **Detections present, `--allow-unredacted-secrets` only, non-TTY**:
+  exit 78 immediately with
+  `CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED` rule-ID on stderr (the rule-ID
+  is the operator's grep target; no `findings` row is persisted because
+  the run never started).
+- **Detections present, both flags, non-TTY, `--confirm-allow-unredacted-secrets=yes-i-understand`**:
+  proceed; emit `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` findings; record
+  `runs.stats` override entry.
+- **Detections present, both flags, wrong confirm value**: exit 78;
+  rule-ID on stderr; no run row.
+
+`std::io::IsTerminal` on stdin is the TTY detector (stable since Rust
+1.70; workspace MSRV 1.88).
+
+#### Override state in `runs.stats`
+
+The existing `runs.stats` column is a TEXT-affinity JSON blob. WP5 appends
+two keys:
+
+```json
+{
+  "secret_override_used": true,
+  "secret_override_files_affected": [
+    "src/api/keys.py",
+    "tests/fixtures/secrets.yaml"
+  ]
+}
+```
+
+These keys are absent when no override fires. Existing readers ignore
+unknown keys (verify by grepping for `runs.stats` JSON deserialisation
+sites).
+
+#### Tests
+
+1. **Non-TTY override-confirmed**: fixture with one AWS key, both flags
+   set, confirm value correct → exits 0, no `briefing_blocked`, one
+   `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` per file, `runs.stats` carries
+   the override keys.
+2. **Non-TTY override-unconfirmed**: only `--allow-unredacted-secrets`,
+   no confirm → exit 78, stderr contains
+   `CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED`, no `runs` row in the DB.
+3. **Non-TTY override-wrong-confirm**: both flags but
+   `--confirm-allow-unredacted-secrets=oops` → exit 78, stderr contains
+   the rule-ID.
+4. **Override + no detections**: flag set but no secrets present → no
+   override findings, no `runs.stats` override keys (the operator's CI
+   stays clean on clean repos).
+5. **TTY path**: marked `#[ignore]` with a doc comment; manual
+   verification belongs to Workstream D's smoke test step 8.
+
+#### Exit criteria
+
+- All non-TTY tests green.
+- `cli.rs` exit codes documented in a module-level doc comment:
+  - 0: success (with or without override).
+  - 1: hard failure (existing behaviour).
+  - 78 (`EX_CONFIG`): override misconfigured.
+- Operator doc (Task 7) documents the exit-code contract and the
+  `--confirm-allow-unredacted-secrets` syntax.
+
+---
+
+### Task 5 — MCP-side awareness of `briefing_blocked`
+
+**Owner**: `crates/clarion-mcp/`
+**Estimated size**: 150–250 LOC including tests.
+**Depends on**: Task 3 (writes the flag); independent of Task 4.
+**Parallelisable with Task 4**: yes.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| modify | `crates/clarion-mcp/src/lib.rs` (summary tool dispatch) |
+| modify | `crates/clarion-mcp/tests/storage_tools.rs` (or split into a new test file) |
+
+#### Scope
+
+When `summary(id)` is called on an entity whose
+`properties.briefing_blocked == "secret_present"`, the MCP server must:
+
+1. **Not** invoke the LLM provider.
+2. **Not** consume any budget ledger.
+3. **Not** write a row to `summary_cache`.
+4. Return an envelope shape that tells the consult-mode agent the absence
+   is policy, not pipeline failure.
+
+#### Envelope shape
+
+```json
+{
+  "entity_id": "python:function:demo.foo|function",
+  "summary": null,
+  "briefing_blocked": "secret_present",
+  "remediation": "File flagged by pre-ingest secret scan. Fix the secret or whitelist via .clarion/secrets-baseline.yaml. See ADR-013."
+}
+```
+
+This is parallel to the existing `summary_scope_deferred` envelope
+(`crates/clarion-mcp/src/lib.rs:2341`) and the four `issues_unavailable`
+envelopes in `clarion-mcp::filigree`. Add a `summary_briefing_blocked`
+helper next to `summary_scope_deferred`.
+
+#### Hook point
+
+The summary tool dispatch reads `entity_properties_json` at line 2382 of
+`lib.rs`. The branch on `briefing_blocked` happens **before** any cache
+lookup or provider invocation. Recommended placement: right after the
+existing `summary_scope_deferred` check, since both are
+"return-immediately" policy branches.
+
+#### Tests
+
+1. **Storage-only**: fixture entity with
+   `properties.briefing_blocked == "secret_present"` → `summary` tool
+   returns the envelope; no row in `summary_cache`.
+2. **Recording-provider isolation**: with `RecordingProvider` configured
+   in recording mode and a counter wrapper around the inner provider,
+   call `summary` on a blocked entity → the inner-provider call counter
+   stays at zero. (The exact assertion form depends on the
+   `RecordingProvider` fixture layout — either "no fixture file
+   created" or "no new entry appended"; the load-bearing claim is "no
+   outbound LLM call." Pick whichever assertion the existing
+   `RecordingProvider` test harness already supports.)
+3. **Budget untouched**: read the session's budget ledger before and
+   after — bytes identical.
+4. **Other tools unaffected**: `entity_at`, `find_entity`, `callers_of`,
+   `execution_paths_from`, `neighborhood`, `issues_for` all return their
+   normal envelopes for blocked entities. The block only affects LLM
+   dispatch; structural navigation still works (this is the whole point
+   of "block briefings, not analysis").
+
+#### Exit criteria
+
+- Storage-tools tests green.
+- Manual log inspection on a fixture with one blocked entity confirms
+  zero outbound LLM calls.
+
+---
+
+### Task 6 — Rule-ID catalogue in `detailed-design.md`
+
+**Owner**: docs
+**Estimated size**: ~100 lines of doc changes.
+**Parallelisable with any task**.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| modify | `docs/clarion/1.0/detailed-design.md` (§5 rule catalogue) |
+
+#### Scope
+
+Append rule rows for each of the five new rule-IDs WP5 introduces. Use the
+existing table shape in §5 (do not invent a new format).
+
+| Rule-ID | Severity | Category | Description (one sentence) | Remediation (one sentence) | ADR |
+|---|---|---|---|---|---|
+| `CLA-SEC-SECRET-DETECTED` | error | security | Pre-ingest secret scanner detected a credential pattern in a file slated for LLM dispatch. | Remove the secret, rotate the credential, or whitelist via `.clarion/secrets-baseline.yaml` with a justification. | [ADR-013](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` | error | security | Operator invoked `--allow-unredacted-secrets`; file content reached the LLM provider with secrets intact. | Audit override usage via `filigree list --rule-id=CLA-SEC-UNREDACTED-SECRETS-ALLOWED --since 30d`. | [ADR-013](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION` | error | infra | Baseline entry missing required `justification` field; entry not honoured. | Add a `justification` string explaining why the match is safe. | [ADR-013](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-INFRA-SECRET-BASELINE-MATCH` | info | infra | Baseline entry suppressed a scanner detection (audit surface). | None — informational, retained for `NFR-SEC-04` audit. | [ADR-013](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) |
+| `CLA-INFRA-SECRET-OVERRIDE-UNCONFIRMED` | error | infra | `--allow-unredacted-secrets` supplied without confirmation; run aborted before start. | Supply `--confirm-allow-unredacted-secrets=yes-i-understand` in non-TTY contexts or run interactively. | [ADR-013](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) |
+
+These IDs make the WP9-B Filigree-emission story (v0.2) able to
+round-trip without a separate spec pass.
+
+#### Exit criteria
+
+- `detailed-design.md` lints clean (existing markdown / cross-reference
+  checks in CI).
+- ADR-013 retains canonical authority on *behaviour*; the design doc
+  carries the *catalogue*. No behaviour is restated in the design doc
+  beyond the one-sentence description and remediation.
+
+---
+
+### Task 7 — Operator documentation
+
+**Owner**: docs
+**Estimated size**: ≤ 250 lines.
+**Parallelisable with any task**.
+
+#### Files
+
+| Action | Path |
+|---|---|
+| create | `docs/operator/secret-scanning.md` |
+| modify | `docs/operator/README.md` (add link to the new page) |
+| modify | `README.md` (Workstream B Task 1; cross-link) — coordinated with WS B, do not duplicate |
+
+If `docs/operator/README.md` does not exist yet, create a minimal index
+listing this and the (forthcoming) `getting-started.md` from WS-B Task 2.
+Coordinate with WS-B to avoid duplicate index creation.
+
+#### Scope
+
+A single page that lets a non-engineer resolve a baseline false-positive
+without reading ADR-013. Sections:
+
+1. **What the scanner does** (3 sentences).
+2. **What gets blocked** (file-level; structural extraction continues;
+   summaries don't).
+3. **How to whitelist a false positive** (edit
+   `.clarion/secrets-baseline.yaml`; example entry; commit it).
+4. **The override flag** (`--allow-unredacted-secrets` +
+   `--confirm-allow-unredacted-secrets=yes-i-understand`; when to use it;
+   what gets audited).
+5. **Exit codes** (0 / 1 / 78).
+6. **Finding the audit trail** (
+   `select * from findings where rule_id like 'CLA-SEC-%'`;
+   forward-pointer to Filigree integration in v0.2).
+7. **Limitations** (pattern-based scanning has false negatives; novel
+   secret shapes; air-gapped alternatives for truly high-risk repos —
+   `--no-llm`).
+
+#### Exit criteria
+
+- A non-engineer can read the doc and resolve a baseline false-positive
+  end-to-end (verified in WS-D smoke test).
+- The doc is ≤ 250 lines.
+- Cross-links to ADR-013 for the operator who wants the design rationale,
+  but does not require reading the ADR to act.
+
+---
+
+## 6. Schema additions
+
+WP5 does not create new tables or columns. It adds two well-known keys to
+existing JSON-bearing columns:
+
+### `entities.properties` (existing TEXT column, JSON object)
+
+- `briefing_blocked: "secret_present"` — stamped by the host on entities
+  whose source file was flagged by the pre-ingest scanner.
+
+Other plausible `briefing_blocked` reasons in the future (e.g.
+`"size_cap_exceeded"`, `"operator_excluded"`) are NOT introduced by WP5;
+the schema is open-vocabulary on the value side. ADR-013 names
+`secret_present` as the canonical first reason.
+
+### `runs.stats` (existing TEXT column, JSON object)
+
+- `secret_override_used: true` — present only when the override fired.
+- `secret_override_files_affected: ["…", "…"]` — present only when
+  `secret_override_used == true`.
+
+Both keys absent on runs with no override → reader code defaults to "no
+override happened."
+
+### Rule-ID grammar
+
+The five new rule-IDs all match the existing ADR-022 manifest rule-ID
+grammar (see `plugin/manifest` correction in commit `0cb61b4`). No
+manifest changes are needed because these are *core-emitted* findings,
+not plugin-emitted.
+
+---
+
+## 7. Test strategy across layers
+
+| Layer | Tests | Location |
+|---|---|---|
+| Unit | Scanner pattern fixtures (positive + negative per rule); entropy bounds; baseline parse / suppress / round-trip | `crates/clarion-scanner/tests/` |
+| Unit | Override CLI exit codes; `runs.stats` JSON shape | `crates/clarion-cli/tests/secret_scan.rs` |
+| Unit | MCP `summary` envelope on blocked entity | `crates/clarion-mcp/tests/storage_tools.rs` |
+| Integration | `analyze` over fixture project with one secret-bearing file → entities + findings + properties_json shape | `crates/clarion-cli/tests/secret_scan.rs` |
+| Integration | Baseline suppression; baseline missing-justification | same |
+| Integration | Non-TTY override paths (3 cases) | same |
+| E2E | `clarion install && clarion analyze` against a fixture project with one known secret; assert exit 0, entities present, briefing_blocked flagged, finding persisted; assert walking-skeleton fixture still green | `tests/e2e/wp5_secret_scan.sh` (new), parallels `tests/e2e/sprint_1_walking_skeleton.sh` |
+| Manual | TTY interactive prompt path | WS-D smoke test step 8 |
+
+### CI gates (ADR-023 floor, unchanged)
+
+WP5 must keep all of these green:
+
+- `cargo fmt --all -- --check`
+- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+- `cargo build --workspace --bins`
+- `cargo nextest run --workspace --all-features`
+- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features`
+- `cargo deny check`
+- `plugins/python/.venv/bin/ruff check plugins/python`
+- `plugins/python/.venv/bin/ruff format --check plugins/python`
+- `plugins/python/.venv/bin/mypy --strict plugins/python`
+- `plugins/python/.venv/bin/pytest plugins/python`
+- `bash tests/e2e/sprint_1_walking_skeleton.sh`
+
+A new E2E (`wp5_secret_scan.sh`) is added to the CI matrix's
+`walking-skeleton` job.
+
+---
+
+## 8. Risks and open questions
+
+| ID | Risk / question | Mitigation |
+|---|---|---|
+| R-1 | High-entropy detection on UUIDs and base64 checksums creates false-positive flood on real repos | Bound length thresholds per ADR-013 (≥20 chars base64, ≥40 chars hex); document baseline workflow prominently in Task 7; Workstream D smoke test on `requests` will surface real-world false-positive rate before publish |
+| R-2 | sha1 hashing of literal secrets means a baseline rebuilt from a different `detect-secrets` version may mismatch | Document the exact hash function (sha1 over the literal matched bytes, no normalisation); migration story for `detect-secrets` v2.x is a v0.2 problem |
+| R-3 | The override flag could become normalised in CI configurations ("we always pass it because…") | Audit-surface design: every override is a finding; v0.2 Filigree integration makes them visible; operator doc explicitly names this anti-pattern |
+| R-4 | Plugin-host integration to stamp `briefing_blocked` adds a code path through a 3 126-LOC file flagged by arch-analysis §5.4 A-3 | Keep the host-side change small (≤ 30 LOC, a single map lookup); the orchestration lives in `clarion-cli/src/secret_scan.rs`, not in the host |
+| R-5 | Baseline format compatibility with `detect-secrets` v1.x must be exact; an operator running `detect-secrets scan --baseline` and dropping the file in `.clarion/` must work | Round-trip test in Task 2; smoke-test the workflow with a real `detect-secrets`-generated baseline in WS-D |
+| Q-1 | Should baseline entries carry an `expires_at` field so stale entries are surfaced? | Out of scope for v0.1; surface as a v0.2 enhancement if the override-monitoring loop also lands then |
+| Q-2 | Does `briefing_blocked: secret_present` propagate up to module / subsystem summaries when those are aggregated (deferred to v0.2 per ADR-030)? | Defer to v0.2; the leaf summary skip is sufficient for v0.1; document in Task 7 that "summaries of containing modules may still be generated and may infer secret content indirectly — fix the underlying file" |
+| Q-3 | Should the scanner also redact secrets from log lines emitted by Clarion itself (the `runs/<run_id>/log.jsonl` ADR-013 line 16 cites)? | **Resolved at planning time**: `runs/<run_id>/log.jsonl` is referenced only in `clarion-cli/src/install.rs:74` (the gitignore template) and `tests/install.rs:40` (the test asserting it's ignored). No writer code exists in `crates/` that emits to that path today. WP5 has nothing to redact. If a per-run JSONL log lands later (likely WP6 batched pipeline or WP9-B), that work must include a redaction pass for any file content emitted from `briefing_blocked` files; cite this row when the log writer is authored. |
+
+All three questions resolved at planning time. None blocks task kickoff.
+
+---
+
+## 9. Workstream exit criteria (gate to Workstream D)
+
+The workstream is signed-off when ALL of the following hold:
+
+- [ ] All seven tasks closed.
+- [ ] `cargo test --workspace --all-features` green.
+- [ ] Existing CI gates (§7) unchanged in pass status.
+- [ ] `tests/e2e/wp5_secret_scan.sh` added and green; included in the
+      `walking-skeleton` CI job.
+- [ ] The walking-skeleton E2E continues to pass on the clean-fixture
+      path (no regression).
+- [ ] `docs/operator/secret-scanning.md` reviewed by a non-author or
+      verified during WS-D smoke test step 8.
+- [ ] All five rule-IDs appear in `detailed-design.md` §5.
+- [ ] No new clippy warnings; no `unsafe` blocks introduced.
+- [ ] `cargo tree -p clarion-scanner` shows no `tokio` / `rusqlite` /
+      `serde_norway` ancestors.
+
+When this gate closes, Workstream D's smoke-test step 8 (planted-`.env`)
+becomes the publish-gate proof point for WP5.
+
+---
+
+## 10. Filigree seeding
+
+Issues to create at workstream kickoff (umbrella + seven tasks). Set
+dependencies as shown.
+
+```bash
+# Umbrella
+filigree create --type=work_package \
+  --title="WP5 — Pre-ingest secret scanner (ADR-013)" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,tier:a" \
+  --priority=1
+# capture the returned id as $WP5_UMBRELLA
+
+# Task 1
+filigree create --type=task \
+  --title="WP5 Task 1 — Scanner crate + rule registry + entropy" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,crate:scanner" \
+  --priority=1
+# capture as $T1
+
+# Task 2
+filigree create --type=task \
+  --title="WP5 Task 2 — Baseline parser (.clarion/secrets-baseline.yaml)" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,crate:scanner" \
+  --priority=1
+# capture as $T2
+
+# Task 3
+filigree create --type=task \
+  --title="WP5 Task 3 — CLI wiring: pre-ingest hook in analyze::run" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,crate:cli,crate:core" \
+  --priority=1
+# capture as $T3
+
+# Task 4
+filigree create --type=task \
+  --title="WP5 Task 4 — Override semantics: --allow-unredacted-secrets" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,crate:cli" \
+  --priority=1
+# capture as $T4
+
+# Task 5
+filigree create --type=task \
+  --title="WP5 Task 5 — MCP-side awareness of briefing_blocked" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,crate:mcp" \
+  --priority=1
+# capture as $T5
+
+# Task 6
+filigree create --type=task \
+  --title="WP5 Task 6 — Rule-ID catalogue entries in detailed-design.md" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,docs" \
+  --priority=2
+# capture as $T6
+
+# Task 7
+filigree create --type=task \
+  --title="WP5 Task 7 — Operator documentation: secret-scanning.md" \
+  --labels="release:v0.1,sprint:3,wp:5,adr:013,docs" \
+  --priority=2
+# capture as $T7
+
+# Dependencies
+filigree add-dep $T3 $T1     # T3 depends on T1
+filigree add-dep $T3 $T2     # T3 depends on T2
+filigree add-dep $T4 $T3     # T4 depends on T3
+filigree add-dep $T5 $T3     # T5 depends on T3 (writes the flag T5 reads)
+
+# Umbrella rolls up
+for t in $T1 $T2 $T3 $T4 $T5 $T6 $T7; do
+  filigree add-dep $WP5_UMBRELLA $t
+done
+
+# Body for each issue should link back to the matching section of this doc:
+#   docs/implementation/v0.1-publish/ws-a-secret-scanner.md#task-N-...
+```
+
+The umbrella is `done` when all seven tasks close; the workstream signs
+off via the criteria in §9.
+
+---
+
+## 11. References
+
+- [ADR-013 — Pre-Ingest Secret Scanner with LLM-Dispatch Block](../../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) — canonical spec.
+- [ADR-007 — Summary cache key](../../clarion/adr/ADR-007-summary-cache-key.md) — `briefing_blocked` interaction.
+- [ADR-017 — Severity and dedup](../../clarion/adr/ADR-017-severity-and-dedup.md) — `CLA-SEC-*` namespace ownership.
+- [ADR-021 — Plugin authority hybrid](../../clarion/adr/ADR-021-plugin-authority-hybrid.md) — path-jail upstream of scanner.
+- [ADR-022 — Core/plugin ontology boundary](../../clarion/adr/ADR-022-core-plugin-ontology.md) — secret detection as a core-owned algorithm.
+- [ADR-023 — Tooling baseline](../../clarion/adr/ADR-023-tooling-baseline.md) — CI floor every task in this workstream must clear.
+- [Requirements — NFR-SEC-01, NFR-SEC-04, NFR-OPS-01, NFR-OPS-04](../../clarion/v0.1/requirements.md) — requirement floor.
+- [Thread 1 — Pre-publish blockers (program of work)](./thread-1-pre-publish-blockers.md) — the umbrella program.
+- [v0.1-plan.md — WP5 scope](../v0.1-plan.md#wp5--pre-ingest-secret-scanner) — original work-package definition.
+- [Sprint 2 scope amendment — WP5 deferral rationale](../sprint-2/scope-amendment-2026-05.md) — "production deployment against unknown corpora gates on this returning."
+- [Arch-analysis final report](../arch-analysis-2026-05-20-2124/04-final-report.md) — current RC1 architecture report; historical H-1 (`SoftFailed` coverage) coverage remains closed via `clarion-141ca7de30` and is a relevant precondition for Task 3.
+- [`detect-secrets` baseline format](https://github.com/Yelp/detect-secrets/blob/master/README.md#baseline-file) — the format Task 2 matches.
diff --git a/docs/clarion/v0.1/reviews/README.md b/docs/implementation/v0.1-reviews/README.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/README.md
rename to docs/implementation/v0.1-reviews/README.md
diff --git a/docs/clarion/v0.1/reviews/panel-2026-04-17/00-executive-synthesis.md b/docs/implementation/v0.1-reviews/panel-2026-04-17/00-executive-synthesis.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/panel-2026-04-17/00-executive-synthesis.md
rename to docs/implementation/v0.1-reviews/panel-2026-04-17/00-executive-synthesis.md
diff --git a/docs/clarion/v0.1/reviews/panel-2026-04-17/04-self-sufficiency.md b/docs/implementation/v0.1-reviews/panel-2026-04-17/04-self-sufficiency.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/panel-2026-04-17/04-self-sufficiency.md
rename to docs/implementation/v0.1-reviews/panel-2026-04-17/04-self-sufficiency.md
diff --git a/docs/clarion/v0.1/reviews/panel-2026-04-17/09-threat-model.md b/docs/implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/panel-2026-04-17/09-threat-model.md
rename to docs/implementation/v0.1-reviews/panel-2026-04-17/09-threat-model.md
diff --git a/docs/clarion/v0.1/reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md b/docs/implementation/v0.1-reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md
rename to docs/implementation/v0.1-reviews/panel-2026-04-17/11-doctrine-panel-synthesis.md
diff --git a/docs/clarion/v0.1/reviews/pre-restructure/design-review.md b/docs/implementation/v0.1-reviews/pre-restructure/design-review.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/pre-restructure/design-review.md
rename to docs/implementation/v0.1-reviews/pre-restructure/design-review.md
diff --git a/docs/clarion/v0.1/reviews/pre-restructure/integration-recon.md b/docs/implementation/v0.1-reviews/pre-restructure/integration-recon.md
similarity index 100%
rename from docs/clarion/v0.1/reviews/pre-restructure/integration-recon.md
rename to docs/implementation/v0.1-reviews/pre-restructure/integration-recon.md
diff --git a/docs/clarion/v0.1/plans/v0.1-scope-commitments.md b/docs/implementation/v0.1-scope-plans/v0.1-scope-commitments.md
similarity index 97%
rename from docs/clarion/v0.1/plans/v0.1-scope-commitments.md
rename to docs/implementation/v0.1-scope-plans/v0.1-scope-commitments.md
index ef74080b..f2bd2ae4 100644
--- a/docs/clarion/v0.1/plans/v0.1-scope-commitments.md
+++ b/docs/implementation/v0.1-scope-plans/v0.1-scope-commitments.md
@@ -14,7 +14,7 @@ The "cross-repo lead time" framing in Q2's original wording assumed Filigree was
 
 ## Purpose
 
-The 10-agent review panel (`docs/clarion/v0.1/reviews/panel-2026-04-17/`) converged on three decisions that only the project author can make. Every P0 ADR, every cost-model claim, and every doctrine asterisk in `loom.md` §5 depends on these commitments being made explicitly rather than left implicit. This memo is the commitment surface — once the three decisions are recorded here, the subsequent work is mechanical.
+The 10-agent review panel (`docs/clarion/1.0/reviews/panel-2026-04-17/`) converged on three decisions that only the project author can make. Every P0 ADR, every cost-model claim, and every doctrine asterisk in `loom.md` §5 depends on these commitments being made explicitly rather than left implicit. This memo is the commitment surface — once the three decisions are recorded here, the subsequent work is mechanical.
 
 **Read first**: `../reviews/panel-2026-04-17/00-executive-synthesis.md` §6.
 
diff --git a/docs/implementation/v1.0-cicd-readiness.md b/docs/implementation/v1.0-cicd-readiness.md
new file mode 100644
index 00000000..48b53de0
--- /dev/null
+++ b/docs/implementation/v1.0-cicd-readiness.md
@@ -0,0 +1,158 @@
+# Clarion v1.0 CI/CD Readiness
+
+**Date**: 2026-05-20
+**Scope**: GitHub Actions CI and release workflows for the Clarion v1.0 publish.
+**Decision basis**: ADR-023 tooling baseline, ADR-033 distribution path, and the
+v1.0 operator install surface.
+
+## Pipeline Map
+
+Clarion has two release-relevant GitHub Actions workflows:
+
+- `.github/workflows/ci.yml` runs on pull requests and pushes to `main`.
+- `.github/workflows/release.yml` runs on `v*` tags and via manual dispatch for
+  non-publishing release dry runs.
+
+The release pipeline is a build-once, verify-before-publish flow:
+
+1. Verify the full ADR-023 floor: Rust format, migration retirement guard,
+   workspace version lockstep, clippy, workspace binary build, nextest, docs,
+   cargo-deny, Python ontology lockstep, ruff, mypy, pytest, walking skeleton,
+   and WP5 secret-scanner smoke.
+2. Verify the live GitHub release governance settings with
+   `RELEASE_GOVERNANCE_TOKEN`.
+3. Build the supported v1.0 Rust platform archives.
+4. Build the Python plugin sdist.
+5. Smoke-test each produced binary archive and the plugin sdist before upload.
+6. Publish a GitHub Release only for pushed `v*` tags.
+7. Sign release archives with keyless cosign and attach SLSA provenance for the
+   Rust binary archives.
+
+## v1.0 Release Gates
+
+The v1.0 publish is blocked unless all of these are green:
+
+```bash
+cargo fmt --all -- --check
+python scripts/check-migration-retirement.py --self-test
+python scripts/check-migration-retirement.py
+python scripts/check-workspace-version-lockstep.py
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --workspace --bins
+cargo nextest run --workspace --all-features --no-tests=pass
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
+cargo deny check
+python scripts/check-b4-gate-result.py
+python scripts/check-python-ontology-version.py --self-test
+python scripts/check-python-ontology-version.py
+ruff check plugins/python
+ruff format --check plugins/python
+mypy --strict plugins/python
+pytest plugins/python
+bash tests/e2e/sprint_1_walking_skeleton.sh
+CARGO_BUILD=0 bash tests/e2e/wp5_secret_scan.sh
+python scripts/check-github-release-governance.py \
+  --repository tachyon-beep/clarion \
+  --branch main
+```
+
+The release workflow intentionally duplicates the CI gate set rather than
+delegating to a reusable workflow on the eve of v1.0. A later refactor may
+deduplicate, but the v1.0 requirement is that a tag cannot publish unless the
+release workflow itself has proved the gate surface.
+
+The GitHub-governance guard is separate from normal PR CI because it inspects
+repository settings outside the source tree. Run it before merging the release
+branch and again immediately before cutting the `v1.0.0` tag with a token that
+can read branch-protection, ruleset, and Actions policy settings. The release
+workflow also runs it before artifact builds using the repository secret
+`RELEASE_GOVERNANCE_TOKEN`, so both `workflow_dispatch` dry runs and pushed
+`v*` tags stop before build/publish work if the live controls cannot be
+inspected or are still permissive. The guard requires the live repository
+controls to force the release path through a pull request and the release CI
+checks: Rust, Python plugin, and Sprint 1 walking-skeleton.
+It reads `GITHUB_TOKEN`/`GH_TOKEN`, or falls back to the current `gh auth token`.
+
+## Readiness Changes Landed
+
+- Release workflow permissions are least-privilege by default. Publishing and
+  signing permissions are scoped to the release/provenance jobs.
+- CI and release workflows set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true`, so
+  pull-request gates exercise the action runtime GitHub is rolling forward to
+  Node 24.
+- CI and release workflow actions, including the SLSA reusable workflow, are
+  pinned to full-length commit SHAs so the repository can enable GitHub's
+  action SHA-pinning policy without breaking the release lane.
+- Dependabot watches GitHub Actions weekly so pinned workflow SHAs have a
+  scheduled update path instead of relying on manual drift checks.
+- The Rust release matrix matches ADR-033's v1.0 supported platforms:
+  `x86_64-unknown-linux-gnu`, `x86_64-apple-darwin`, and
+  `aarch64-apple-darwin`.
+- Each Rust archive is extracted and the packaged `clarion` binary is exercised
+  with `--version` and `--help` before upload.
+- The Python plugin sdist is installed into a fresh virtual environment before
+  upload, and the installed package version is checked.
+- Public registry publishing is out of v1.0 scope. The workflow does not publish
+  to PyPI or crates.io; GitHub Release assets are the v1.0 distribution surface.
+- Operator docs now point at the v1.0 design ladder and GitHub Release install
+  path instead of stale v0.1 or registry text.
+- `scripts/check-github-release-governance.py` makes the external repository
+  controls auditable instead of relying on a manual visual check in GitHub's UI.
+  It also statically rejects non-SHA workflow action refs before it queries
+  GitHub's live repository settings, verifies that live branch protection or
+  rulesets name the release CI checks, and requires the Dependabot GitHub
+  Actions update lane to exist so SHA pins stay maintainable after the tag.
+- `.github/workflows/release.yml` runs that governance guard as a required
+  pre-build job using `RELEASE_GOVERNANCE_TOKEN`; release artifacts and public
+  GitHub Releases are not produced when the guard fails or cannot inspect the
+  live repository settings.
+- `.github/workflows/ci.yml` runs the guard's self-test and `--static-only`
+  mode on every PR, so source-tree drift in workflow action pins, the
+  Dependabot update lane, or the release workflow's governance dependency is
+  caught before merge.
+
+## Live GitHub Enforcement Audit
+
+Snapshot on 2026-05-20:
+
+- Release-prep PR: <https://github.com/tachyon-beep/clarion/pull/12>.
+- PR branch: `RC1`; use the PR's current head commit at merge time as the
+  exact release-prep source revision.
+- Base branch: `main`.
+- Merge state: clean.
+- Required PR proof available today: the latest CI run on PR #12 must pass
+  Rust, Python plugin, and Sprint 1 walking-skeleton jobs with Node 24 action
+  runtime forcing enabled. GitHub's Dependabot configuration check passed when
+  the GitHub Actions update lane was added; future Dependabot config changes
+  must keep that check green.
+- Repository Actions are enabled, with `allowed_actions=all` and
+  `sha_pinning_required=false`.
+- The `main` branch is not protected; GitHub's branch-protection endpoint
+  returns `404 Branch not protected`.
+- Repository rulesets are empty.
+
+The workflow definitions are ready for the v1.0 release path, but repository
+governance is still permissive. The workflow files are now compatible with
+GitHub's SHA-pinning control, but before cutting the release tag, make
+`scripts/check-github-release-governance.py` pass by enabling branch protection
+or an active repository ruleset for `main` that requires pull-request flow and
+the release CI checks, and by enabling a constrained Actions source policy such
+as full-length SHA pinning. The maintainer-facing procedure is in
+[`docs/operator/v1.0-release-governance.md`](../operator/v1.0-release-governance.md).
+
+## Remaining Manual Release Controls
+
+- Merge PR #12 to `main` after explicit maintainer approval.
+- Configure `RELEASE_GOVERNANCE_TOKEN` as a repository Actions secret with
+  access to branch-protection/ruleset and Actions policy settings.
+- Run `workflow_dispatch` for `.github/workflows/release.yml` before cutting the
+  `v1.0.0` tag. GitHub only exposes the new release workflow after the workflow
+  file lands on the default branch. That dry run produces artifacts but does not
+  publish a Release.
+- Run `scripts/check-github-release-governance.py` and require a pass before the
+  tag is created.
+- After the tag publish completes, download the Linux archive and Python sdist
+  from the public Release and repeat the `docs/operator/getting-started.md`
+  install walkthrough on a clean machine or VM.
+- Keep PyPI/crates.io publishing disabled until a superseding ADR names registry
+  ownership, token/trusted-publishing setup, yanking policy, and cadence.
diff --git a/docs/implementation/v1.0-tag-cut/README.md b/docs/implementation/v1.0-tag-cut/README.md
new file mode 100644
index 00000000..cb95c781
--- /dev/null
+++ b/docs/implementation/v1.0-tag-cut/README.md
@@ -0,0 +1,44 @@
+# Clarion v1.0.0 — Tag-Cut Readiness
+
+**Status**: RC1 hardening — `v1.0.0` tag held pending closure of the gap register.
+
+This directory holds the canonical pre-tag-cut artifacts for Clarion v1.0.0.
+It supersedes `docs/implementation/v0.1-publish/` (which was renamed in intent
+when the v0.1 → v1.0 rebrand landed but never moved on disk) as the current
+program-of-work surface for the tag.
+
+## Documents
+
+| File | Purpose |
+|------|---------|
+| [`gap-register.md`](gap-register.md) | Single source of truth for every gap between the current RC1 commit and a defensible `v1.0.0` tag. 24 gaps in 7 categories with evidence, fix, and effort. |
+| [`execution-plan.md`](execution-plan.md) | Day-by-day sequenced execution plan, with parallel-execution markers, operator-vs-engineering split, and the exit criteria for each day. |
+| [`filigree-issue-bodies.md`](filigree-issue-bodies.md) | Pre-drafted bodies for the Filigree issues that track each gap. Reference for issue creation; the live issues are authoritative once created. |
+
+## Origin
+
+The gap register is the integrated output of seven review passes:
+
+1. The 2026-05-20 RC1 architecture archaeology at
+   [`../arch-analysis-2026-05-20-2124/`](../arch-analysis-2026-05-20-2124/),
+   which originated risks R1–R6.
+2. Six parallel subagent deep-dives executed 2026-05-22:
+   - Architecture critique of the five flagged blast-radius files.
+   - Test/quality coverage and E2E gate audit.
+   - Security threat review of the federation HTTP API and WP5 secret scanner.
+   - CI/CD pipeline review of release governance and tag safety.
+   - Embedded-database (SQLite) discipline review against the 13-sheet
+     reference set.
+   - Documentation/contract drift audit against ADR precedence.
+
+The arch-analysis snapshot is preserved as the prior baseline; this gap
+register is the operational supersession.
+
+## Reading order
+
+For tag-cut decisions: `gap-register.md` → `execution-plan.md`.
+
+For Filigree issue creation: `filigree-issue-bodies.md`.
+
+For why a specific gap was raised: the gap register cites the originating
+review file:line.
diff --git a/docs/implementation/v1.0-tag-cut/execution-plan.md b/docs/implementation/v1.0-tag-cut/execution-plan.md
new file mode 100644
index 00000000..9ab66b4b
--- /dev/null
+++ b/docs/implementation/v1.0-tag-cut/execution-plan.md
@@ -0,0 +1,311 @@
+# Clarion v1.0.0 — Tag-Cut Execution Plan
+
+**Date**: 2026-05-22
+**Closes**: every gap in [`gap-register.md`](gap-register.md).
+**Total effort**: ~13 hours engineering + ~3.5 hours operator.
+
+This plan sequences the gaps into three days of focused work, with explicit
+parallel-execution markers. The first day is mechanical doc + bug fixes
+that have no inter-dependencies and can run as parallel PRs. Day 2 is the
+storage + CI hardening work that needs sequential review. Day 3 is the
+operator-led governance + smoke + tag-cut.
+
+## Branching strategy
+
+**Decision required from operator before Day 1**: The current `RC1` branch
+carries two post-1.0 dogfood commits (`a32c162`, `4dd7b63`) on top of the
+release-prep stack. Pick one:
+
+- **Option A (recommended)**: Branch a clean `release/1.0` from `a089a21`
+  (last pure release-prep commit) and apply the gap-closure work there.
+  Leave the dogfood commits on `RC1` as the post-1.0 working branch.
+  - Pro: 1.0 tag is what it claims to be — release-prep only.
+  - Pro: Dogfood work continues unblocked on `RC1`.
+  - Con: One-time branch surgery; PR #12 needs re-targeting.
+- **Option B**: Keep `RC1` as the release branch; document the two
+  dogfood commits in CHANGELOG as "1.0 also ships agent-orientation
+  affordances (`project_status`, `analyze_start/cancel/status`,
+  `index_diff`, etc.)" Update the operator MCP surface section to
+  enumerate the additional tools.
+  - Pro: No branch surgery; PR #12 ships as-is.
+  - Con: CHANGELOG and operator docs need expansion to cover the
+    new MCP tools; commitment to support the additional surface
+    under semver.
+
+This plan assumes **Option A** unless the operator instructs otherwise.
+If Option B, add a Day 1.5 step to expand CHANGELOG and MCP operator
+docs to cover the additional tools.
+
+---
+
+## Day 1 — Mechanical fixes (parallelisable, no review interlock)
+
+**Owner**: engineering, can be dispatched to parallel agents.
+**Duration**: 4–5 hours wall-clock with parallel execution.
+**Exit**: all PRs merged or in-review with green CI.
+
+### Stream 1A — Single-line doc edits (one PR, ~30 min)
+
+Bundle these into a single PR titled `docs: pre-tag-cut v1.0 contract drift fixes`.
+
+| Gap | File | Change |
+|-----|------|--------|
+| DOC-01 | `CHANGELOG.md:60` | `UNAUTHORIZED` → `UNAUTHENTICATED` |
+| DOC-02 | `CHANGELOG.md:60` | Add `BATCH_TOO_LARGE` |
+| DOC-05 | `docs/clarion/1.0/requirements.md:573` | `See:` line add `, ADR-034` |
+| DOC-08 | `docs/operator/secret-scanning.md:83` | drop `in v0.1` qualifier |
+| DOC-10 | `CHANGELOG.md` | adjust "(through ADR-034)" phrasing |
+
+### Stream 1B — Multi-line doc rewrites (one PR, ~1 hr)
+
+Bundle: `docs: refresh v1.0 docs against ADR-034`.
+
+| Gap | File | Change |
+|-----|------|--------|
+| DOC-03 | `docs/clarion/1.0/requirements.md:771-783` | Rewrite NFR-SEC-03 statement + verification for ADR-034 rules |
+| DOC-04 | `docs/clarion/1.0/requirements.md:558-573` | Rewrite REQ-HTTP-03 statement + verification |
+| DOC-06 | `docs/suite/loom.md:65-70`, `CHANGELOG.md:108` | "v0.1 asterisks" → "v1.0 asterisks"; "deferred to v0.2" → "deferred to v1.1" |
+| DOC-07 | `CLAUDE.md:144` | Rewrite HMAC paragraph; HMAC is preferred in 1.0 |
+| DOC-09 | `CHANGELOG.md` (known limitations) | Add Wardline REGISTRY asterisk entry |
+
+### Stream 1C — New operator docs (one PR, ~1.5 hr)
+
+Bundle: `docs(operator): pre-tag-cut governance + storage docs`.
+
+| Gap | New file | Content |
+|-----|----------|---------|
+| GOV-03 | `docs/operator/v1.0-release-rollback.md` | Rollback / yank runbook (see gap register) |
+| DOC-11 | append §Storage section to `README.md` and / or new `docs/clarion/1.0/operations.md` | Deployment constraints (NFS prohibition, no double-analyze, backup procedure) |
+| SEC-02 | append section to `docs/operator/secret-scanning.md` and `docs/operator/clarion-http-read-api.md` | Loopback-no-token trust statement |
+| SEC-03 | append to `docs/operator/secret-scanning.md` and CHANGELOG known-limits | Pre-WP5 catalogue upgrade requirement |
+
+### Stream 1D — One-line code fixes (one PR, ~1 hr including tests)
+
+Bundle: `fix(v1.0): pre-tag correctness fixes`.
+
+| Gap | File | Change |
+|-----|------|--------|
+| SEC-01 | `crates/clarion-storage/src/query.rs:296-302` | Fail-closed `entity_briefing_block_reason`; add malformed-JSON unit test |
+| CI-02 | `crates/clarion-cli/src/http_read.rs:426-431` | Use a non-`InvalidPath` error code on body-parse failure; add a test exercising oversized body |
+| SEC-02 (code half) | `crates/clarion-mcp/src/config.rs` and / or `crates/clarion-cli/src/serve.rs` startup | Emit explicit startup banner line when loopback-no-token mode is in effect |
+
+### Stream 1E — Filigree issue creation (one batch, ~30 min)
+
+Create one Filigree issue per gap, labelled `release:v1.0`. File the v1.1
+backlog items with `release:v1.1`. See [`filigree-issue-bodies.md`](filigree-issue-bodies.md).
+
+### Day 1 exit
+
+- 4 PRs (1A–1D) green in CI.
+- All Filigree issues filed and labelled.
+- `git log` shows no remaining R3/D1–D10/SEC-01/CI-02 gaps.
+
+---
+
+## Day 2 — Storage + CI hardening (sequential review)
+
+**Owner**: engineering. Single reviewer for the storage work.
+**Duration**: 4–5 hours.
+**Exit**: storage and CI gaps closed; `walking-skeleton` job green with
+new gates wired.
+
+### 2.1 — Storage cross-process safety (STO-01, ~2 hr)
+
+PR: `fix(storage): cross-process lock for clarion analyze`.
+
+- Add `fs2 = "0.4"` to `crates/clarion-cli/Cargo.toml`.
+- At top of `analyze::run` (and `serve` write paths), open
+  `.clarion/clarion.lock`, call `try_lock_exclusive`. Hold for the
+  duration of the writer-actor lifetime.
+- Refuse a second concurrent invocation with a clear error message:
+  "another `clarion analyze` is in progress against this project".
+- Add a test that spawns two `clarion analyze` subprocesses against the
+  same project root and asserts exactly one succeeds.
+- Update `docs/clarion/1.0/operations.md` (or the README §Storage)
+  paragraph from Stream 1C to reference the fail-fast behaviour.
+
+### 2.2 — Storage identity + integrity (STO-02, STO-04, ~1 hr)
+
+PR: `fix(storage): application_id PRAGMA + e2e integrity check`.
+
+- Add `PRAGMA application_id = 0x434C524E` to
+  `crates/clarion-storage/src/pragma.rs::apply_write_pragmas`.
+- On open, assert `application_id == 0` (then set) or `0x434C524E`
+  (recognise); refuse any other value with a clear error.
+- Add `PRAGMA integrity_check` final assertion to
+  `tests/e2e/sprint_1_walking_skeleton.sh`. Fail the script if
+  output is not exactly `ok`.
+- Unit test for the application_id assertion path.
+
+### 2.3 — CI wiring (TEST-01, TEST-02, CI-01, ~1 hr)
+
+PR: `ci: wire MCP surface, Phase 3, and tag-lineage gates`.
+
+- Add steps to `walking-skeleton` job in `.github/workflows/ci.yml`:
+  ```yaml
+  - name: Sprint 2 MCP surface
+    run: bash tests/e2e/sprint_2_mcp_surface.sh
+  - name: Phase 3 subsystem clustering determinism
+    run: bash tests/e2e/phase3_subsystems.sh
+  ```
+- Mirror in `release.yml verify` job.
+- Add ancestor check to `release.yml verify`:
+  ```yaml
+  - name: Assert tagged commit is on main
+    run: |
+      git fetch origin main
+      git merge-base --is-ancestor "$GITHUB_SHA" origin/main || \
+        { echo "::error::tag does not point to a commit on main"; exit 1; }
+  ```
+- Verify both scripts pass under the CI environment before merging.
+
+### 2.4 — SLSA coverage for Python sdist (CI-03, ~30 min)
+
+PR: `ci: extend SLSA provenance to plugin sdist`.
+
+- Edit `release-subjects` step in `.github/workflows/release.yml:201-225`
+  to glob `clarion-*.tar.gz` + `clarion_plugin_python*.tar.gz`.
+- Update release notes template to mention plugin-sdist provenance.
+
+### 2.5 — Post-publish verification (CI-04, ~45 min, optional for v1.0)
+
+Recommended as a v1.0 Critical-but-not-blocking; if time is tight,
+defer to v1.1 with a documented gap in the rollback runbook.
+
+PR: `ci: verify published release matches signed artifacts`.
+
+- Add `verify-published-release` job after `create-release` that
+  downloads from the public Release URL, recomputes SHA256, and
+  cosign-verifies against public Rekor entries.
+
+### Day 2 exit
+
+- All Critical / High storage and CI gaps closed except STO-03
+  (deferred to tag-cut moment) and CI-04 (optional).
+- CI floor on `main` passes including new gates.
+
+---
+
+## Day 3 — Operator: governance, smoke, tag-cut
+
+**Owner**: operator (single human, no parallelism).
+**Duration**: 3–4 hours.
+**Exit**: `v1.0.0` tag exists on `main`, GitHub Release published,
+artifacts smoke-tested.
+
+### 3.1 — Enable GitHub controls (GOV-01, GOV-02, ~30 min)
+
+- Configure `RELEASE_GOVERNANCE_TOKEN` repository Actions secret with
+  read access to branch-protection, ruleset, and Actions policy
+  settings.
+- Enable a ruleset targeting `main` that requires PR flow and these
+  three required CI checks: `Rust`, `Python plugin`, `Sprint 1 walking
+  skeleton (end-to-end)`. (After Day 2.3, optionally add the new MCP
+  surface + Phase 3 checks if they appear as separate Check Runs.)
+- Enable a ruleset targeting `refs/tags/v*` restricting tag creators
+  to repository owner (or write-to-`main` set).
+- Enable a constrained Actions source policy (SHA-pinning required,
+  or allow-list).
+
+### 3.2 — Live governance dry-run (~15 min)
+
+- Run `scripts/check-github-release-governance.py --repository
+  tachyon-beep/clarion --branch main` locally with a token that can
+  read the policy settings. Confirm exit 0.
+
+### 3.3 — Merge the gap-closure PRs to main (~15 min)
+
+- Review and merge the Day 1 + Day 2 PR stack into `main` (or merge
+  PR #12 if Option B was chosen, with the gap-closure work cherry-picked
+  on top).
+
+### 3.4 — Release workflow dry-run (~15 min)
+
+- `gh workflow run Release --ref main` (workflow_dispatch).
+- Verify all jobs green; verify artifacts produced; verify no public
+  Release is created (the workflow conditions on `event_name == 'push'`
+  for the publish step).
+
+### 3.5 — External-operator smoke (GOV-04, ~2 hr)
+
+- Provision a fresh Linux x86_64 VM and a fresh macOS host (or use a
+  CI runner that satisfies "outside-operator" semantics).
+- Run `tests/e2e/external-operator-smoke.md` checklist on each.
+- Record results in
+  `docs/implementation/v1.0-tag-cut/external-operator-smoke-result.md`
+  with timestamp, host OS+arch, install command, "improvisation events"
+  count (target: 0), and an attestation signature.
+- Commit and push to `main`.
+
+### 3.6 — Filigree F-1 lockstep check (~5 min)
+
+- Confirm Filigree's F-1 (`clarion-cd21b98463` — registry-backend
+  consumer rename) status against the 2026-05-19 coordinator memo. If
+  F-1 has merged and uses the old field name, halt — fix in Filigree
+  first.
+
+### 3.7 — Commit `published_build.txt` (STO-03, ~5 min)
+
+- The final pre-tag commit on `main`:
+  ```bash
+  echo "$(git rev-parse HEAD)" > crates/clarion-storage/migrations/published_build.txt
+  git add crates/clarion-storage/migrations/published_build.txt
+  git commit -m "release: mark v1.0.0 as published-build baseline"
+  git push origin main
+  ```
+
+### 3.8 — Cut the tag (~5 min)
+
+- `git tag -a v1.0.0 -m "Clarion v1.0.0"`
+- `git push origin v1.0.0`
+- The release workflow fires on the push. Watch the `verify` →
+  `release-governance` → `build-rust` / `build-plugin` → `release` →
+  `provenance` chain.
+
+### 3.9 — Public artifact smoke (~30 min)
+
+- Once the release is public, install Clarion from the
+  GitHub-Release-hosted assets on a fresh host (or one of the
+  external-operator smoke VMs).
+- Verify cosign signatures via `cosign verify-blob` with the
+  Rekor entry.
+- Verify SLSA provenance via `slsa-verifier`.
+- Run the walking-skeleton against a small Python corpus.
+- Record success or initiate the rollback runbook.
+
+### Day 3 exit
+
+- `v1.0.0` tag pushed, Release public, artifacts verified.
+- This document and the gap register move to historical-anchor status
+  (no edits except status-flip on the exit-criteria checklist).
+
+---
+
+## Risk mitigation
+
+**If anything goes wrong on Day 3**:
+- The rollback runbook (GOV-03) covers the h+30min "bad release"
+  scenario. The first action is always
+  `gh release edit v1.0.0 --prerelease`.
+- The release workflow does not delete or modify the tag, so the
+  worst-case is an orphaned release with assets that need re-pointing.
+
+**If Day 2 storage work uncovers more issues**:
+- The fs2 lock is the load-bearing change. If it breaks an existing
+  test, the issue is likely in `serve` write paths (which we may need
+  to scope more narrowly than `analyze`). Surface immediately; do not
+  merge the PR.
+
+**If governance check fails after Day 3.1**:
+- The runbook at `docs/operator/v1.0-release-governance.md` covers the
+  configuration steps. If the script still fails after applying them,
+  the failure mode is documented in
+  `scripts/check-github-release-governance.py` exit codes.
+
+## Confidence
+
+This plan is grounded in the seven-pass deep dive. Effort estimates are
+conservative — most Day 1 streams should complete in less than the
+quoted time. The main schedule risk is Day 3.5 (external-operator
+smoke), which depends on VM provisioning time and the operator's
+availability.
diff --git a/docs/implementation/v1.0-tag-cut/filigree-issue-bodies.md b/docs/implementation/v1.0-tag-cut/filigree-issue-bodies.md
new file mode 100644
index 00000000..fd7a9488
--- /dev/null
+++ b/docs/implementation/v1.0-tag-cut/filigree-issue-bodies.md
@@ -0,0 +1,270 @@
+# Filigree Issue Bodies — v1.0 Tag-Cut Gaps
+
+Pre-drafted Filigree issues for every gap in [`gap-register.md`](gap-register.md).
+Every issue cites the gap register as its source of truth so the issue body
+can stay terse and the register stays canonical.
+
+**Filing convention**: every v1.0 issue gets `release:v1.0` + the
+priority-appropriate `priority:Pn` label + a `category:<cat>` label. The
+v1.1 backlog items get `release:v1.1` + the same category labels.
+
+## v1.0 issues
+
+### GOV-01 — Live GitHub governance is permissive
+- **title**: `[v1.0 blocker] Enable live GitHub governance: branch protection, ruleset, RELEASE_GOVERNANCE_TOKEN`
+- **priority**: P1
+- **type**: feature
+- **labels**: `release:v1.0`, `category:governance`, `tier:a`
+- **body**:
+  > Closes GOV-01 in `docs/implementation/v1.0-tag-cut/gap-register.md`.
+  >
+  > Operator action: configure live GitHub controls per
+  > `docs/operator/v1.0-release-governance.md`. Exit criterion is
+  > `scripts/check-github-release-governance.py` exits 0.
+- **owner**: operator
+
+### GOV-02 — No tag protection rule
+- **title**: `[v1.0 blocker] Add ruleset for refs/tags/v* and tag-protection check to governance script`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:governance`, `tier:a`
+- **body**: Closes GOV-02 in the gap register. Two-part: (1) operator enables ruleset on `refs/tags/v*`; (2) engineering extends `scripts/check-github-release-governance.py` to assert tag protection.
+
+### GOV-03 — Rollback / yank runbook
+- **title**: `[v1.0 blocker] Write rollback/yank runbook for bad-release scenario`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:governance`
+- **body**: Closes GOV-03. Add `docs/operator/v1.0-release-rollback.md`. See gap register for required sections.
+
+### GOV-04 — External-operator smoke evidence
+- **title**: `[v1.0 blocker] Run external-operator smoke on fresh VMs and archive dated result`
+- **priority**: P1, **type**: task, **labels**: `release:v1.0`, `category:governance`
+- **body**: Closes GOV-04. Result archived at `docs/implementation/v1.0-tag-cut/external-operator-smoke-result.md`.
+
+### DOC-01 — CHANGELOG UNAUTHORIZED → UNAUTHENTICATED
+- **title**: `[v1.0 blocker] Fix CHANGELOG error-code UNAUTHORIZED → UNAUTHENTICATED`
+- **priority**: P1, **type**: bug, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-01. One-line edit at `CHANGELOG.md:60`.
+
+### DOC-02 — Add BATCH_TOO_LARGE to CHANGELOG error enum
+- **title**: `[v1.0 blocker] Add BATCH_TOO_LARGE to CHANGELOG error-enum list`
+- **priority**: P1, **type**: bug, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-02. Edit `CHANGELOG.md:60`.
+
+### DOC-03 — NFR-SEC-03 stale post-ADR-034
+- **title**: `[v1.0 blocker] Refresh NFR-SEC-03 for ADR-034 authenticated-non-loopback rule`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:docs`, `adr:034`
+- **body**: Closes DOC-03. Rewrite at `docs/clarion/1.0/requirements.md:771-783`.
+
+### DOC-04 — REQ-HTTP-03 stale post-ADR-034
+- **title**: `[v1.0 blocker] Refresh REQ-HTTP-03 for ADR-034 authenticated-non-loopback rule`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:docs`, `adr:034`
+- **body**: Closes DOC-04. Rewrite at `docs/clarion/1.0/requirements.md:558-573`.
+
+### DOC-05 — REQ-HTTP-03 See line missing ADR-034
+- **title**: `[v1.0] Add ADR-034 to REQ-HTTP-03 See line`
+- **priority**: P2, **type**: docs, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-05. One-line edit.
+
+### DOC-06 — loom.md "v0.1 asterisks" labels
+- **title**: `[v1.0 blocker] Rename loom.md "v0.1 asterisks" to "v1.0 asterisks"; CHANGELOG "deferred to v0.2" → "v1.1"`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-06.
+
+### DOC-07 — CLAUDE.md HMAC misrepresentation
+- **title**: `[v1.0 blocker] Update CLAUDE.md: HMAC ships in 1.0 per ADR-034, not "post-1.0 hardening"`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:docs`, `adr:034`
+- **body**: Closes DOC-07. Edit `CLAUDE.md:144`.
+
+### DOC-08 — secret-scanning.md v0.1 reference
+- **title**: `[v1.0] Drop v0.1 reference from docs/operator/secret-scanning.md`
+- **priority**: P2, **type**: docs, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-08. One-line edit.
+
+### DOC-09 — CHANGELOG Wardline REGISTRY asterisk
+- **title**: `[v1.0] Add Wardline REGISTRY import to CHANGELOG known limitations`
+- **priority**: P2, **type**: docs, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-09.
+
+### DOC-10 — CHANGELOG ADR-count phrasing
+- **title**: `[v1.0] Adjust CHANGELOG ADR-count "(through ADR-034)" phrasing`
+- **priority**: P3, **type**: docs, **labels**: `release:v1.0`, `category:docs`
+- **body**: Closes DOC-10. Cosmetic.
+
+### DOC-11 — Storage operator constraints in README
+- **title**: `[v1.0 blocker] Document storage deployment constraints (NFS, double-analyze, backup)`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:docs`, `category:storage`
+- **body**: Closes DOC-11. New `docs/clarion/1.0/operations.md` or README §Storage.
+
+### SEC-01 — entity_briefing_block_reason fail-open
+- **title**: `[v1.0 blocker] Fail-closed: entity_briefing_block_reason on malformed properties JSON`
+- **priority**: P1, **type**: bug, **labels**: `release:v1.0`, `category:security`, `crate:storage`
+- **body**: Closes SEC-01. One-line code change at `crates/clarion-storage/src/query.rs:296-302` plus malformed-JSON unit test.
+
+### SEC-02 — Loopback-no-token trust assumption
+- **title**: `[v1.0 blocker] Document loopback-no-token trust + emit startup banner`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:security`, `category:docs`
+- **body**: Closes SEC-02. Operator-doc additions + startup-banner warning.
+
+### SEC-03 — Pre-WP5 catalogue upgrade requirement
+- **title**: `[v1.0 blocker] Document pre-WP5 .clarion/ upgrade requirement (re-analyze needed)`
+- **priority**: P1, **type**: docs, **labels**: `release:v1.0`, `category:security`, `category:docs`
+- **body**: Closes SEC-03.
+
+### CI-01 — Tag-lineage in-workflow check
+- **title**: `[v1.0 blocker] Add ancestor-of-main check to release.yml verify`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:ci`
+- **body**: Closes CI-01. Workflow edit.
+
+### CI-02 — Federation error code on body parse failure
+- **title**: `[v1.0 blocker] Fix HMAC body-parse error code (currently returns InvalidPath)`
+- **priority**: P1, **type**: bug, **labels**: `release:v1.0`, `category:federation`, `crate:cli`
+- **body**: Closes CI-02. Edit `crates/clarion-cli/src/http_read.rs:426-431`.
+
+### CI-03 — SLSA coverage for Python sdist
+- **title**: `[v1.0 blocker] Extend SLSA provenance to Python plugin sdist`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:ci`
+- **body**: Closes CI-03. Edit `release-subjects` step.
+
+### CI-04 — Post-publish artifact verification
+- **title**: `[v1.0] Verify-published-release job after create-release`
+- **priority**: P2, **type**: feature, **labels**: `release:v1.0`, `category:ci`
+- **body**: Closes CI-04. Optional for v1.0; defer to v1.1 if time-constrained.
+
+### STO-01 — Cross-process lock
+- **title**: `[v1.0 blocker] fs2 advisory lock for clarion analyze (prevent concurrent corruption)`
+- **priority**: P1, **type**: bug, **labels**: `release:v1.0`, `category:storage`, `crate:cli`, `crate:storage`
+- **body**: Closes STO-01. Add fs2 + lock + test.
+
+### STO-02 — PRAGMA application_id
+- **title**: `[v1.0 blocker] Set PRAGMA application_id on writer open`
+- **priority**: P1, **type**: bug, **labels**: `release:v1.0`, `category:storage`, `crate:storage`
+- **body**: Closes STO-02.
+
+### STO-03 — published_build.txt marker
+- **title**: `[v1.0 blocker] Commit migrations/published_build.txt at v1.0 tag-cut`
+- **priority**: P1, **type**: task, **labels**: `release:v1.0`, `category:storage`
+- **body**: Closes STO-03. Final pre-tag commit on `main`.
+
+### STO-04 — Backup + integrity_check
+- **title**: `[v1.0 blocker] PRAGMA integrity_check in e2e + documented backup procedure`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:storage`
+- **body**: Closes STO-04.
+
+### STO-05 — Recovery liveness guard
+- **title**: `[v1.0] Document run-recovery race; defer schema columns to v1.1`
+- **priority**: P2, **type**: docs, **labels**: `release:v1.0`, `category:storage`
+- **body**: Closes STO-05 doc-only at v1.0. v1.1 issue tracks the heartbeat columns separately.
+
+### TEST-01 — Wire sprint_2_mcp_surface.sh
+- **title**: `[v1.0 blocker] Add sprint_2_mcp_surface.sh to CI walking-skeleton job`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:ci`, `category:tests`
+- **body**: Closes TEST-01.
+
+### TEST-02 — Wire phase3_subsystems.sh
+- **title**: `[v1.0 blocker] Add phase3_subsystems.sh to CI walking-skeleton job`
+- **priority**: P1, **type**: feature, **labels**: `release:v1.0`, `category:ci`, `category:tests`
+- **body**: Closes TEST-02.
+
+---
+
+## v1.1 backlog issues
+
+(File these before tag-cut so post-1.0 work is tracked.)
+
+### V11-ARCH-01 — Extract clarion-core::errors shared error vocabulary
+- priority: P2, type: feature, labels: `release:v1.1`, `category:architecture`
+- body: deep-dive-arch v1.1 priority #1. Closes the MCP/HTTP error-code drift smell.
+
+### V11-ARCH-02 — Split analyze.rs run_with_options
+- priority: P2, type: feature, labels: `release:v1.1`, `category:architecture`, `crate:cli`
+- body: deep-dive-arch v1.1 priority #2. Extract `analyze/phase3.rs` and `analyze/mapping.rs`. Removes the `#[allow(too_many_lines)]`.
+
+### V11-ARCH-03 — Split llm_provider.rs per provider
+- priority: P2, type: feature, labels: `release:v1.1`, `category:architecture`, `crate:core`
+- body: deep-dive-arch v1.1 priority #3. `openrouter.rs` / `cli_provider.rs` (Codex + Claude on shared base) / `prompts.rs`.
+
+### V11-ARCH-04 — Split clarion-mcp/src/lib.rs into tools/ subdir
+- priority: P3, type: feature, labels: `release:v1.1`, `category:architecture`, `crate:mcp`
+- body: deep-dive-arch v1.1 priority #4.
+
+### V11-ARCH-05 — Split plugin/host.rs validation from transport
+- priority: P3, type: feature, labels: `release:v1.1`, `category:architecture`, `crate:core`
+- body: deep-dive-arch v1.1 priority #5.
+
+### V11-SEC-01 — Replace local HMAC with hmac + subtle crates
+- priority: P2, type: feature, labels: `release:v1.1`, `category:security`, `crate:cli`
+- body: deep-dive-security recommendation. If schedule allows, ship in v1.0 instead.
+
+### V11-SEC-02 — HMAC replay protection (timestamp + nonce window)
+- priority: P2, type: feature, labels: `release:v1.1`, `category:security`
+- body: Called out in ADR-034 forward-work. Required when non-loopback bind becomes common.
+
+### V11-SEC-03 — Mandatory auth on loopback binds
+- priority: P3, type: feature, labels: `release:v1.1`, `category:security`
+- body: Doctrine change closing T-9. Breaks the documented v0.1 trust matrix.
+
+### V11-STO-01 — runs.owner_pid + heartbeat_at columns
+- priority: P2, type: feature, labels: `release:v1.1`, `category:storage`
+- body: deep-dive-db. Schema-additive 0002_*; refine recovery WHERE-clause.
+
+### V11-STO-02 — clarion db backup subcommand
+- priority: P2, type: feature, labels: `release:v1.1`, `category:storage`, `crate:cli`
+- body: deep-dive-db. `rusqlite::backup::Backup`-based.
+
+### V11-STO-03 — summary_cache.entity_id FK
+- priority: P2, type: bug, labels: `release:v1.1`, `category:storage`
+- body: deep-dive-db. Confirmed bug, not intentional. Requires table-rebuild migration.
+
+### V11-STO-04 — briefing_blocked generated column + index
+- priority: P2, type: feature, labels: `release:v1.1`, `category:storage`
+- body: Federation read-API hot path.
+
+### V11-STO-05 — BEGIN IMMEDIATE + SQLITE_BUSY retry helper
+- priority: P3, type: feature, labels: `release:v1.1`, `category:storage`
+- body: Matters once V11-STO-01 cross-process work lands.
+
+### V11-STO-06 — FTS5 content_text decision
+- priority: P3, type: feature, labels: `release:v1.1`, `category:storage`
+- body: Drop or populate the dead-schema column.
+
+### V11-STO-07 — ReaderPool eager validation
+- priority: P3, type: feature, labels: `release:v1.1`, `category:storage`
+- body: `clarion serve` boot should fail-fast on bad DB.
+
+### V11-STO-08 — briefing_blocked typed column
+- priority: P3, type: feature, labels: `release:v1.1`, `category:storage`
+- body: Promote from JSON property. Closes a class of drift.
+
+### V11-CI-01 — Reusable verify workflow
+- priority: P2, type: feature, labels: `release:v1.1`, `category:ci`
+- body: Eliminate ci.yml/release.yml drift risk.
+
+### V11-CI-02 — pip-audit in build-plugin
+- priority: P3, type: feature, labels: `release:v1.1`, `category:ci`
+- body: Python supply chain.
+
+### V11-CI-03 — workflow_permissions + tag-protection in governance script
+- priority: P3, type: feature, labels: `release:v1.1`, `category:ci`
+- body: Extend `check-github-release-governance.py`.
+
+### V11-CI-04 — macOS Gatekeeper workaround doc
+- priority: P3, type: docs, labels: `release:v1.1`, `category:docs`
+- body: In `getting-started.md`.
+
+### V11-CI-05 — SBOM emission
+- priority: P3, type: feature, labels: `release:v1.1`, `category:ci`
+- body: cyclonedx-bom or syft.
+
+### V11-TEST-01 — pyright-langserver hard-fail in CI
+- priority: P2, type: bug, labels: `release:v1.1`, `category:tests`
+- body: deep-dive-quality. Currently silent-skip if missing.
+
+### V11-TEST-02 — Pyright pin lockstep script
+- priority: P3, type: feature, labels: `release:v1.1`, `category:tests`
+- body: deep-dive-quality provided concrete script. Adds drift defence.
+
+### V11-TEST-03 — Wardline version-bounds validation script
+- priority: P3, type: feature, labels: `release:v1.1`, `category:tests`
+- body: deep-dive-quality concrete script.
+
+### V11-TEST-04 — EntityCountCap ADR/code lockstep script
+- priority: P3, type: feature, labels: `release:v1.1`, `category:tests`
+- body: deep-dive-quality concrete script.
diff --git a/docs/implementation/v1.0-tag-cut/gap-register.md b/docs/implementation/v1.0-tag-cut/gap-register.md
new file mode 100644
index 00000000..c9e668ac
--- /dev/null
+++ b/docs/implementation/v1.0-tag-cut/gap-register.md
@@ -0,0 +1,572 @@
+# Clarion v1.0.0 Tag-Cut Gap Register
+
+**Date**: 2026-05-22
+**Branch**: `RC1` at `4dd7b63`
+**Status**: 24 gaps open against the `v1.0.0` tag-cut criterion.
+
+This document is the single source of truth for everything that stands between
+the current RC1 commit and a defensible `v1.0.0` tag. Every gap is
+evidence-cited, has a concrete fix, and has an effort estimate. The
+[execution-plan.md](execution-plan.md) sequences these into a day-by-day
+schedule.
+
+## Severity scale
+
+- **Critical** — supply-chain integrity or wire-contract correctness; ship a
+  tag without these and downstream tooling breaks or an attacker has a
+  concrete path. Must close before tag-cut.
+- **High** — observable user-facing wrongness, missed test coverage on
+  shipped surfaces, or operator-visible safety gap. Must close before
+  tag-cut.
+- **Medium** — drift between authoritative sources, documentation
+  inaccuracies. Must close before tag-cut for any gap on the documented
+  release surface.
+- **Low** — internal-only polish, performance, or non-shipping discipline.
+  Listed for completeness; may defer to v1.1.
+
+## Category summary
+
+| Category | Count | Effort |
+|----------|------:|-------:|
+| Operator / governance (live GitHub controls, smoke evidence) | 4 | 3.5 hr |
+| Documentation and contract drift | 11 | 1 hr |
+| Security fail-closed + doc gaps | 3 | 1 hr |
+| CI/CD release-path correctness | 4 | 2 hr |
+| Storage / SQLite discipline | 5 | 4 hr |
+| Test gate wiring | 2 | 1 hr |
+| Code bug (federation error-code) | 1 | 15 min |
+| **Total** | **30** | **~13 hr** |
+
+(The 24-count from the executive summary collapsed some related items;
+this register breaks every item out individually for tracking. The 1.0
+blocker count is unchanged.)
+
+---
+
+## Originating-review key
+
+- **arch-2026-05-20** — [`../arch-analysis-2026-05-20-2124/04-final-report.md`](../arch-analysis-2026-05-20-2124/04-final-report.md) and siblings
+- **deep-dive-arch** — Architecture critique subagent, 2026-05-22
+- **deep-dive-security** — Threat analyst subagent, 2026-05-22
+- **deep-dive-pipeline** — Pipeline reviewer subagent, 2026-05-22
+- **deep-dive-db** — Embedded-database reviewer subagent, 2026-05-22
+- **deep-dive-docs** — Doc consistency reviewer subagent, 2026-05-22
+- **deep-dive-quality** — Coverage gap analyst subagent, 2026-05-22
+
+---
+
+## Gap register
+
+### Category 1 — Operator / governance
+
+#### GOV-01 (Critical) — Live GitHub governance is permissive
+
+- **Origin**: arch-2026-05-20 R1; deep-dive-pipeline.
+- **Evidence**: `docs/implementation/v1.0-cicd-readiness.md:103-114` documents
+  the live state at 2026-05-20: `main` returns `404 Branch not protected`,
+  rulesets empty, `allowed_actions=all`, `sha_pinning_required=false`.
+- **Fix**: Operator action. Enable branch protection (or active ruleset)
+  targeting `main` that (a) requires pull-request flow with at least the
+  three release CI checks (`Rust`, `Python plugin`,
+  `Sprint 1 walking skeleton (end-to-end)`), (b) enables a constrained
+  Actions source policy (SHA-pinning or allow-list), (c) configures the
+  `RELEASE_GOVERNANCE_TOKEN` repository Actions secret with permission to
+  read branch-protection, ruleset, and Actions policy settings.
+- **Runbook**: [`docs/operator/v1.0-release-governance.md`](../../operator/v1.0-release-governance.md)
+- **Effort**: 1 hr operator.
+- **Exit criterion**: `scripts/check-github-release-governance.py
+  --repository tachyon-beep/clarion --branch main` exits 0.
+
+#### GOV-02 (Critical) — No tag protection rule
+
+- **Origin**: deep-dive-pipeline (net-new vs arch analysis).
+- **Evidence**: `scripts/check-github-release-governance.py` does not query
+  `GET /repos/{owner}/{repo}/tags/protection` or check for a ruleset
+  targeting `refs/tags/v*`. The operator runbook only covers branch
+  protection.
+- **Risk**: An actor with tag-push permission can push `refs/tags/v1.0.0`
+  pointing at any commit (a feature branch, a detached commit). If that
+  commit passes the workflow's gates, the release publishes from it.
+- **Fix**: Add a GitHub ruleset targeting `refs/tags/v*` that restricts
+  who can push matching tags (creators allow-list: repository owner only,
+  or the same actors who can write to `main`). Add a tag-protection check
+  to `check-github-release-governance.py`.
+- **Effort**: 5 min operator (ruleset) + 30 min engineering (script).
+- **Exit criterion**: Governance script asserts tag protection on `refs/tags/v*`.
+
+#### GOV-03 (Critical) — No rollback / yank runbook
+
+- **Origin**: deep-dive-pipeline (net-new).
+- **Evidence**: Neither `docs/operator/v1.0-release-governance.md` nor
+  `docs/implementation/v1.0-cicd-readiness.md` covers what happens after
+  a bad release ships. Concrete gaps for h+30min "bad release" scenario:
+  GitHub Release asset deletion guidance absent; Sigstore Rekor
+  non-revocability not stated; downstream (Filigree) notification path
+  undocumented.
+- **Fix**: Add `docs/operator/v1.0-release-rollback.md` covering:
+  (a) `gh release edit v1.0.0 --prerelease` as the first action;
+  (b) asset-deletion policy (don't delete unless sensitive — broken URLs
+  are worse than stale files); (c) explicit statement that cosign
+  signatures in Rekor cannot be revoked, only superseded; (d) `v1.0.1`
+  publication procedure with `superseded by` note in the release body;
+  (e) Filigree consumer notification path.
+- **Effort**: 1 hr docs.
+- **Exit criterion**: Runbook exists, reviewed, linked from
+  `v1.0-release-governance.md`.
+
+#### GOV-04 (High) — No dated external-operator smoke result
+
+- **Origin**: arch-2026-05-20 R6.
+- **Evidence**: `tests/e2e/external-operator-smoke.md` defines a checklist.
+  No dated result file exists in the tree.
+- **Fix**: Operator runs the checklist on a fresh Linux x86_64 VM and a
+  fresh macOS host. Archive the result as
+  `docs/implementation/v1.0-tag-cut/external-operator-smoke-result.md`
+  with a timestamp, OS+arch, the install command run, the
+  "improvisation events" count (target: 0), and an attestation signature.
+- **Effort**: 2 hr operator (mostly VM provisioning + walkthrough time).
+- **Exit criterion**: Dated result file committed.
+
+---
+
+### Category 2 — Documentation and contract drift
+
+#### DOC-01 (Critical) — CHANGELOG advertises non-existent `UNAUTHORIZED` error code
+
+- **Origin**: arch-2026-05-20 R3; deep-dive-docs C1.
+- **Evidence**: `CHANGELOG.md:60` lists `UNAUTHORIZED`. Authoritative
+  sources (`docs/federation/contracts.md:82`, `82,202,276`,
+  `docs/clarion/adr/ADR-014:126`, `docs/clarion/adr/ADR-034:45,87,145`,
+  implementation tests at `crates/clarion-cli/tests/serve.rs:1457,1495,1547,1579,1614`)
+  all use `UNAUTHENTICATED`.
+- **Fix**: `Edit` `UNAUTHORIZED` → `UNAUTHENTICATED` in `CHANGELOG.md:60`.
+- **Effort**: 1 min.
+
+#### DOC-02 (High) — CHANGELOG error enum missing `BATCH_TOO_LARGE`
+
+- **Origin**: deep-dive-docs H1 (net-new).
+- **Evidence**: `CHANGELOG.md:59-61` lists six codes plus `UNAUTHORIZED`.
+  `docs/federation/contracts.md:83-84` and `ADR-034:87` enumerate the same
+  set plus `BATCH_TOO_LARGE`. PR #12's own body claims the correction was
+  made — it was made in `contracts.md` but not in the CHANGELOG.
+- **Fix**: `Edit` `CHANGELOG.md:60` to add `BATCH_TOO_LARGE`.
+- **Effort**: 1 min.
+
+#### DOC-03 (High) — NFR-SEC-03 is stale post-ADR-034
+
+- **Origin**: deep-dive-docs H2 (net-new).
+- **Evidence**: `docs/clarion/1.0/requirements.md:771-783` says non-loopback
+  "When enabled, startup logs a warning that the endpoint is
+  unauthenticated and must be protected outside Clarion." `ADR-034:43`
+  says "Non-loopback binds require both `allow_non_loopback: true` and a
+  resolved HMAC identity secret or legacy bearer token; either alone is
+  insufficient." Per CLAUDE.md precedence (ADR > requirements), the
+  requirement statement is the bug.
+- **Fix**: Rewrite NFR-SEC-03 statement and verification clause to
+  describe the post-ADR-034 rule: non-loopback **requires** auth; the
+  startup warning is for the loopback-without-token mode only.
+- **Effort**: 10 min docs.
+
+#### DOC-04 (High) — REQ-HTTP-03 is stale post-ADR-034
+
+- **Origin**: deep-dive-docs H2.
+- **Evidence**: `docs/clarion/1.0/requirements.md:558-573` still describes
+  the HTTP API as "unauthenticated and loopback-only by default" and the
+  verification as "unauthenticated-surface warning". Same drift as DOC-03
+  but on the routing side.
+- **Fix**: Rewrite REQ-HTTP-03 statement and verification to reflect
+  ADR-034's authenticated-non-loopback rule.
+- **Effort**: 10 min docs.
+
+#### DOC-05 (Medium) — REQ-HTTP-03 `See` line missing ADR-034
+
+- **Origin**: deep-dive-docs M3.
+- **Evidence**: `requirements.md:573` reads `See: System Design §9
+  (Integrations, HTTP Read API), ADR-014.` ADR-034 partially extends
+  ADR-014's Security Posture and Error Envelope; a reader cannot
+  discover ADR-034 from the requirement.
+- **Fix**: `Edit` to add `, ADR-034`.
+- **Effort**: 1 min.
+
+#### DOC-06 (High) — loom.md still labels asterisks as "v0.1"
+
+- **Origin**: deep-dive-docs H3.
+- **Evidence**: `docs/suite/loom.md:65,69` heads "v0.1 asterisks" and says
+  "The asterisk ships with v0.1 and retires in v0.2." CLAUDE.md:64 and
+  the CHANGELOG say both asterisks persist into v1.0 and retire
+  post-release.
+- **Fix**: Rename "v0.1 asterisks" → "v1.0 asterisks" and update the
+  retirement wording. Update `CHANGELOG.md:108` "deferred to v0.2" →
+  "deferred to a future release (tracked under `release:v1.1`)."
+- **Effort**: 5 min docs.
+
+#### DOC-07 (High) — CLAUDE.md misrepresents HMAC as post-1.0
+
+- **Origin**: deep-dive-docs H4.
+- **Evidence**: `CLAUDE.md:144` "HMAC inbound auth (C-4) — bearer is the
+  1.0 wire surface; HMAC is forward-compatible and tracked for post-1.0
+  hardening." Code reads `identity_token_env` and enforces
+  `X-Loom-Component: clarion:<hmac>` today
+  (`crates/clarion-cli/src/http_read.rs:129-130,184,373-374`); ADR-034
+  marks HMAC as the preferred mechanism; CHANGELOG:115-117 documents it
+  shipping.
+- **Fix**: Update CLAUDE.md HMAC paragraph: HMAC ships in v1.0 per
+  ADR-034 as the preferred non-loopback authentication; document
+  `identity_token_env` config. Move "post-1.0 hardening" to refer only
+  to replay protection (timestamp + nonce window, ADR-034 forward-work).
+- **Effort**: 10 min.
+
+#### DOC-08 (Medium) — secret-scanning.md carries v0.1 reference
+
+- **Origin**: deep-dive-docs M2.
+- **Evidence**: `docs/operator/secret-scanning.md:83` "Contextual
+  credential suppression only recognises shell/Python `#` comments in
+  v0.1."
+- **Fix**: Drop the version qualifier or change to "in v1.0".
+- **Effort**: 1 min.
+
+#### DOC-09 (Medium) — loom.md asterisk 2 (Wardline REGISTRY) absent from CHANGELOG
+
+- **Origin**: deep-dive-docs M1.
+- **Evidence**: `loom.md:70` names the Wardline REGISTRY import as
+  asterisk 2 with no retirement condition citation. CHANGELOG "Known
+  v1.0 limitations" (lines 105-117) does not mention it.
+- **Fix**: Add an entry to CHANGELOG "Known limitations": "The Python
+  plugin imports `wardline.core.registry.REGISTRY` at startup
+  (loom.md §5 asterisk 2). Retirement condition: Wardline ships a
+  stable runtime probe API."
+- **Effort**: 5 min.
+
+#### DOC-10 (Low) — CHANGELOG "Documentation" ADR count phrasing
+
+- **Origin**: deep-dive-docs L2.
+- **Evidence**: CHANGELOG says "28 Accepted at 1.0 (through ADR-034)";
+  the math is right but the parenthetical "(through ADR-034)" reads as
+  a contiguous range when in fact ADR-008/009/010/019/020 are
+  Backlog/Superseded.
+- **Fix**: Adjust phrasing to "(ADR-001…ADR-034 with the documented
+  Backlog/Superseded subset excluded)" or similar.
+- **Effort**: 2 min.
+
+#### DOC-11 (High) — Storage operator constraints missing from README
+
+- **Origin**: deep-dive-db low-severity finding, promoted to High here
+  because the cross-process race (STO-01) will surface as operator
+  confusion without operator-facing guidance.
+- **Evidence**: There is no operator-facing doc that says (a) do not
+  put `.clarion/` on NFS, (b) do not run two `clarion analyze`
+  simultaneously, (c) backup procedure is "stop analyze →
+  `PRAGMA wal_checkpoint(TRUNCATE)` → file copy".
+- **Fix**: Add a §Storage paragraph to top-level README or a new
+  `docs/clarion/1.0/operations.md` covering deployment constraints.
+- **Effort**: 30 min.
+
+---
+
+### Category 3 — Security: fail-closed + documentation
+
+#### SEC-01 (Critical) — `entity_briefing_block_reason` fail-open on malformed JSON
+
+- **Origin**: deep-dive-security T-11 (net-new).
+- **Evidence**: `crates/clarion-storage/src/query.rs:296-302`
+  `entity_briefing_block_reason` returns `None` (= unblocked) when
+  `serde_json::from_str(properties_json)` fails. A plugin emitting
+  malformed `properties` JSON silently disables the WP5 briefing
+  block, exposing the entity through every federation read path.
+- **Fix**: One-line change: on `from_str` failure, return
+  `Some("malformed_properties_json")` (or equivalent
+  block-with-reason). Add a unit test covering the malformed-JSON
+  path.
+- **Effort**: 15 min code + 15 min test.
+
+#### SEC-02 (High) — Loopback-no-token trust assumption not documented
+
+- **Origin**: deep-dive-security T-9.
+- **Evidence**: `crates/clarion-cli/src/http_read.rs:384-386` admits any
+  request when both `identity_secret` and `auth_token` are `None`.
+  `validate_auth_trust` (`crates/clarion-mcp/src/config.rs:307-345`)
+  only refuses *non-loopback* binds. On a shared developer host or CI
+  runner, any local process can read the entire (non-blocked)
+  catalogue.
+- **Fix**: (a) Add explicit operator-doc section to
+  `docs/operator/secret-scanning.md` and `docs/operator/clarion-http-read-api.md`
+  describing the loopback-without-token trust assumption. (b) Add a
+  startup-banner line when loopback-no-token mode is in effect:
+  "HTTP API serving on loopback without authentication; any local
+  process can read the catalogue."
+- **Effort**: 20 min docs + 20 min code.
+
+#### SEC-03 (High) — Legacy `.clarion/` upgrade requirement undocumented
+
+- **Origin**: deep-dive-security T-11 (sub-point).
+- **Evidence**: `entity_briefing_block_reason` reads
+  `properties.briefing_blocked`. Pre-WP5 binaries never wrote that
+  property; a 1.0 binary opening a pre-WP5 `.clarion/clarion.db` will
+  serve the entire catalogue without refusal because every row's
+  `briefing_blocked` is structurally absent.
+- **Fix**: Document the upgrade requirement in
+  `docs/operator/secret-scanning.md` and in the CHANGELOG "Known
+  limitations": "Upgrading from a pre-WP5 binary requires
+  `clarion analyze` re-run before any HTTP API serves the catalogue."
+- **Effort**: 10 min.
+
+---
+
+### Category 4 — CI / release path correctness
+
+#### CI-01 (Critical) — No in-workflow tag-lineage check
+
+- **Origin**: deep-dive-pipeline (net-new).
+- **Evidence**: `release.yml verify` job runs against `$GITHUB_SHA`
+  (whatever the pushed tag resolves to). Nothing in the workflow asserts
+  that `$GITHUB_SHA` is an ancestor of `origin/main`. Combined with
+  GOV-02, this is the supply-chain bypass path.
+- **Fix**: Add to the start of `verify`:
+  ```yaml
+  - name: Assert tagged commit is on main
+    run: |
+      git fetch origin main
+      git merge-base --is-ancestor "$GITHUB_SHA" origin/main || \
+        { echo "::error::tag does not point to a commit on main"; exit 1; }
+  ```
+- **Effort**: 10 min.
+
+#### CI-02 (Critical) — Federation error code wrong on HMAC body parse failure
+
+- **Origin**: deep-dive-arch (architecture critic) + deep-dive-security
+  (corroborating).
+- **Evidence**: `crates/clarion-cli/src/http_read.rs:426-431` — if
+  `to_bytes(body, HTTP_BODY_LIMIT_BYTES)` fails inside HMAC middleware,
+  the response returns `ErrorCode::InvalidPath` with message
+  "request body is invalid". A federation client pattern-matching on
+  `code` will mis-route a body/IO failure as a path-validation failure.
+- **Fix**: Use a separate `ErrorCode::InvalidBody` (or
+  `ErrorCode::Internal`) on body-parse failure. Add a test that
+  exercises an oversized body and asserts the code field.
+- **Effort**: 15 min code + 15 min test.
+
+#### CI-03 (High) — Python sdist not SLSA-attested
+
+- **Origin**: deep-dive-pipeline.
+- **Evidence**: `release-subjects` in `.github/workflows/release.yml:201-225`
+  globs only `clarion-*.tar.gz` (Rust archives) into the SLSA provenance
+  subjects. The Python plugin sdist has cosign signing but no SLSA
+  attestation file. A user installing via `pipx install` from the
+  release URL has no `slsa-verifier` path.
+- **Fix**: Either (a) extend the glob to include
+  `clarion_plugin_python*.tar.gz` and append to the existing provenance
+  file, or (b) document the gap explicitly in the release notes and in
+  `docs/operator/v1.0-release-governance.md`.
+- **Effort**: 30 min for option (a); 5 min for option (b).
+- **Recommended**: option (a) — it's a one-line change to the glob.
+
+#### CI-04 (Medium) — No automated post-publish verification
+
+- **Origin**: deep-dive-pipeline.
+- **Evidence**: `release.yml` runs cosign verify on the same runner
+  immediately after signing (lines 313-323). This proves signing
+  worked; it does not prove the published GitHub Release artifacts
+  match the signed local copies.
+- **Fix**: Add a final `verify-published-release` job that runs after
+  `create-release`, downloads the assets from the public Release URL,
+  recomputes SHA256, and cosign-verifies against the public Rekor
+  entries.
+- **Effort**: 45 min.
+
+---
+
+### Category 5 — Storage / SQLite discipline
+
+#### STO-01 (Critical) — No cross-process lock; second `clarion analyze` corrupts run state
+
+- **Origin**: deep-dive-db (highest-priority finding).
+- **Evidence**: `crates/clarion-cli/src/run_lifecycle.rs:19-25`
+  unconditionally executes `UPDATE runs SET status='failed' WHERE
+  status='running'` at the top of every `clarion analyze`, then opens
+  the writer-actor connection. There is no `fs2::FileExt::try_lock_exclusive()`
+  on `.clarion/clarion.lock` or the DB file. A second concurrent
+  `clarion analyze` flips the live run's status to `failed` while the
+  first writer holds an open connection mid-batch.
+- **Fix**: Add `fs2 = "0.4"` to `clarion-cli/Cargo.toml`. At the top
+  of `analyze::run` (and `serve` write paths), acquire
+  `File::open(".clarion/clarion.lock")?.try_lock_exclusive()`. Hold for
+  writer-actor lifetime. Fail fast with "another clarion analyze is in
+  progress against this project".
+- **Effort**: 1-2 hr code + test.
+
+#### STO-02 (High) — No `PRAGMA application_id`
+
+- **Origin**: deep-dive-db.
+- **Evidence**: `crates/clarion-storage/src/pragma.rs` sets WAL,
+  synchronous, busy, foreign-keys, but never `application_id` or
+  `user_version`. The SQLite file has no identity marker; tooling
+  like `file(1)` or `sqlite3 .dbinfo` cannot distinguish a Clarion DB
+  from any other SQLite file.
+- **Fix**: Add `PRAGMA application_id = 0x434C524E` ("CLRN") to
+  `apply_write_pragmas`. On open, assert the application_id is 0
+  (legacy / unset, then set it) or `0x434C524E` (recognise). Refuse
+  any other value with a clear error.
+- **Effort**: 30 min code + 15 min test.
+
+#### STO-03 (Critical) — No `published_build.txt` migration marker
+
+- **Origin**: deep-dive-db; arch-2026-05-20 follow-up.
+- **Evidence**: ADR-024 migration retirement guard
+  (`scripts/check-migration-retirement.py`) requires
+  `crates/clarion-storage/migrations/published_build.txt` to mark the
+  v1.0 commit SHA as the baseline. The file does not exist.
+- **Fix**: Create the file at tag-cut time with the exact
+  `v1.0.0` commit SHA. Block CI on its presence going forward.
+- **Effort**: 1 min, but must be done at tag-cut moment after the
+  release-prep PR merges.
+- **Sequencing note**: STO-03 is the *last* gap closed, immediately
+  before pushing the `v1.0.0` tag.
+
+#### STO-04 (High) — No backup / `integrity_check` path
+
+- **Origin**: deep-dive-db.
+- **Evidence**: No `VACUUM INTO`, no `rusqlite::backup::Backup`, no
+  `PRAGMA integrity_check` invocation in CI. A user who `cp`s
+  `.clarion/clarion.db` during a live `clarion analyze` gets a torn
+  copy because WAL pages live in `clarion.db-wal` separately.
+- **Fix v1.0**: (a) Add `PRAGMA integrity_check` final assertion to
+  `tests/e2e/sprint_1_walking_skeleton.sh`. (b) Document the
+  supported backup procedure in DOC-11's README §Storage paragraph
+  (shutdown → `PRAGMA wal_checkpoint(TRUNCATE)` → file copy).
+  (c) `clarion db backup` subcommand deferred to v1.1.
+- **Effort**: 30 min (parts a and b only).
+
+#### STO-05 (Medium) — `recover_preexisting_running_runs` has no liveness guard
+
+- **Origin**: deep-dive-db.
+- **Evidence**: `crates/clarion-cli/src/run_lifecycle.rs:19-25`
+  recovery sweep is `UPDATE runs SET status='failed' WHERE
+  status='running'`. No PID column, no heartbeat, no startup-instance
+  token. STO-01's fs2 lock is necessary but not sufficient; even
+  fixing it leaves a same-process restart vulnerable.
+- **Fix v1.0**: Document the constraint in DOC-11. Defer the
+  schema-additive `runs.owner_pid` + `heartbeat_at` columns to v1.1.
+- **Effort**: 5 min (doc only; the v1.1 follow-up is filed as a
+  separate issue).
+
+---
+
+### Category 6 — Test gate wiring
+
+#### TEST-01 (Critical) — `sprint_2_mcp_surface.sh` not in CI
+
+- **Origin**: arch-2026-05-20 R2; deep-dive-quality (highest-severity
+  finding).
+- **Evidence**: `tests/e2e/sprint_2_mcp_surface.sh` exists and exercises
+  all 8 MCP navigation tools (`entity_at`, `find_entity`, `callers_of`,
+  `execution_paths_from`, `summary`, `issues_for`, `neighborhood`,
+  `subsystem_members`) over stdio against a real `clarion analyze`
+  output with the Python plugin venv. The MCP `serve.rs` integration
+  test only covers `initialize`; the `storage_tools.rs` test exercises
+  the underlying storage layer but not the MCP wire serialization. A
+  wrong-JSON-shape regression in any tool would silently corrupt an
+  agent's context.
+- **Fix**: Add an additional step to the `walking-skeleton` job in
+  `ci.yml` after the existing two scripts:
+  ```yaml
+  - name: Sprint 2 MCP surface
+    run: bash tests/e2e/sprint_2_mcp_surface.sh
+  ```
+  Mirror in `release.yml verify` job.
+- **Effort**: 30 min (wire + verify it passes in CI).
+
+#### TEST-02 (High) — `phase3_subsystems.sh` not in CI
+
+- **Origin**: arch-2026-05-20 R2; deep-dive-quality.
+- **Evidence**: `tests/e2e/phase3_subsystems.sh` exists, exercises
+  subsystem clustering determinism (two analyze runs, byte-for-byte
+  identical cluster assignments). Subsystem clustering is part of
+  the v1.0 advertised surface per CHANGELOG.
+- **Fix**: Add to `walking-skeleton` job after `sprint_2_mcp_surface.sh`.
+  Mirror in `release.yml verify`.
+- **Effort**: 30 min.
+
+---
+
+### Category 7 — Code bug
+
+(CI-02 also fits this category; left in CI for sequencing.)
+
+---
+
+## Out-of-scope for v1.0 (file as `release:v1.1` before tag-cut)
+
+Filed as Filigree issues with `release:v1.1` label so they don't get lost.
+
+**Architecture refactors (deep-dive-arch v1.1 priority order):**
+1. Extract `clarion-core::errors` shared error-code vocabulary.
+2. Split `analyze.rs` → `analyze/phase3.rs` + `analyze/mapping.rs`.
+3. Split `llm_provider.rs` per-provider.
+4. Split `clarion-mcp/src/lib.rs` into `tools/` subdir.
+5. Split `plugin/host.rs` validation from transport.
+6. Replace local HMAC-SHA256 with `hmac` + `subtle` crates.
+
+**Storage hardening (deep-dive-db):**
+1. `runs.owner_pid` + `heartbeat_at` columns and refined recovery WHERE-clause.
+2. `clarion db backup` subcommand via `rusqlite::backup::Backup`.
+3. ~~`summary_cache.entity_id` FK via table-rebuild migration (confirmed
+   bug — not intentional asymmetry).~~ **Closed in v1.0 (2026-05-24)**:
+   landed in-place in migration `0001_initial_schema.sql` under
+   ADR-024's pre-tag edit-in-place policy (no published build exists
+   yet, so no `schema_migrations` ledger needs the table-rebuild
+   ceremony). See clarion-4c49ccf5d0.
+4. `briefing_blocked` generated column + partial index (federation
+   read-API hot path).
+5. `BEGIN IMMEDIATE` + `SQLITE_BUSY` retry helper across the writer.
+6. FTS5 `content_text` dead-schema decision (drop or populate).
+7. ReaderPool eager validation + PRAGMA `post_create` hook.
+8. Promote `briefing_blocked` from JSON property to typed column.
+
+**Security hardening (deep-dive-security):**
+1. HMAC replay protection (timestamp + nonce window). Already called
+   out in ADR-034 forward-work.
+2. Mandatory authentication on loopback binds (doctrine change).
+3. ~~Make pyright-langserver-missing a CI hard-fail, not a silent skip.~~
+   **Closed in v1.0 (2026-05-24)**: pyright-langserver fixture in
+   `test_pyright_session.py` and `test_extractor.py` now calls
+   `pytest.fail()` instead of `pytest.skip()`. See clarion-dc99115f5d.
+
+**CI / release hardening (deep-dive-pipeline):**
+1. Refactor `release.yml verify` into a reusable workflow shared with
+   `ci.yml` (eliminates drift risk).
+2. Add `pip-audit` step to `build-plugin` job.
+3. Add tag-protection and `workflow_permissions` checks to the
+   governance script.
+4. macOS Gatekeeper workaround doc in `getting-started.md`.
+5. SBOM emission (cyclonedx-bom or syft).
+
+**Drift-test scripts (deep-dive-quality):**
+1. `scripts/check-pyright-pin-lockstep.py` — pyproject.toml,
+   plugin.toml, and ci.yml cache key.
+2. `scripts/check-wardline-version-bounds.py` — semver validity and
+   eventual server-side cross-check.
+3. `scripts/check-entity-cap-lockstep.py` — limits.rs `DEFAULT_MAX`
+   against ADR-021 §2c.
+
+---
+
+## Exit criteria for v1.0.0 tag-cut
+
+All of:
+
+1. Every Critical and High gap above is closed (status: ✅ in this
+   register, with a commit SHA citation).
+2. Every Medium documentation gap is closed (operator-facing accuracy
+   is non-negotiable on a release artifact).
+3. `scripts/check-github-release-governance.py` exits 0 against live
+   `tachyon-beep/clarion`.
+4. PR #12 (or its successor) is merged to `main` and is the parent of
+   the `v1.0.0` tag commit.
+5. `release.yml workflow_dispatch` dry-run from `main` produces all
+   expected artifacts.
+6. External-operator smoke result file is dated, signed-off, and
+   shows 0 improvisation events on both target platforms.
+7. Filigree F-1 lockstep (registry-backend consumer rename) confirmed
+   still aligned.
+8. `published_build.txt` written with the tag commit SHA (last step
+   before `git tag`).
diff --git a/docs/operator/README.md b/docs/operator/README.md
index 225676df..828c9fea 100644
--- a/docs/operator/README.md
+++ b/docs/operator/README.md
@@ -2,7 +2,19 @@
 
 Practical notes for configuring and running Clarion.
 
+- [Getting started](./getting-started.md) — single-flow walkthrough: install,
+  analyse a small repo, connect an MCP client, ask three questions, verify
+  the secret-block. Target ≤15 minutes end-to-end.
 - [OpenRouter LLM provider](./openrouter.md) — API key, model ID, attribution
-  headers, and token-ceiling configuration for v0.1.
+  headers, and token-ceiling configuration.
+- [Coding-agent LLM providers](./coding-agent-llm-providers.md) — Codex CLI
+  and Claude CLI as local-login alternatives to API-key provider wiring.
 - [Runtime topology](./runtime-topology.md) — supported `clarion serve` and
   `clarion analyze` concurrency against one `.clarion/clarion.db`.
+- [Secret scanning](./secret-scanning.md) — pre-ingest scanner behavior,
+  baseline false-positive workflow, override confirmation, and audit queries.
+- [v1.0 release governance](./v1.0-release-governance.md) — maintainer steps
+  for GitHub branch/ruleset enforcement, Actions policy, release dry run, and
+  final tag gating.
+- [Federation contracts](../federation/contracts.md) — read-side HTTP
+  contracts consumed by sibling products such as Filigree.
diff --git a/docs/operator/clarion-http-read-api.md b/docs/operator/clarion-http-read-api.md
new file mode 100644
index 00000000..a51ffc58
--- /dev/null
+++ b/docs/operator/clarion-http-read-api.md
@@ -0,0 +1,86 @@
+# Clarion HTTP Read API
+
+Clarion can expose a read-only HTTP API for local sibling integrations such as
+Filigree's `registry_backend: clarion` mode. The wire contract is documented in
+the [federation contracts](../federation/contracts.md).
+
+## Trust Model
+
+By default, `clarion serve` binds the HTTP read API only to loopback addresses so
+it is reachable from local processes on the same host, not from the network. A
+loopback-only API may run without authentication for local sidecar workflows.
+
+For authenticated mode, set `serve.http.identity_token_env` to the name of an
+environment variable that contains the shared Loom component secret:
+
+```yaml
+serve:
+  http:
+    enabled: true
+    bind: 127.0.0.1:9111
+    identity_token_env: CLARION_LOOM_IDENTITY_SECRET
+```
+
+When `identity_token_env` is configured, Clarion refuses to start unless the env
+var is present and non-empty. Protected `/api/v1/files` routes then require
+`X-Loom-Component: clarion:<hmac>`. The HMAC is lowercase hex HMAC-SHA256 over:
+
+```text
+<METHOD>
+<PATH_AND_QUERY>
+<SHA256_HEX_OF_REQUEST_BODY>
+```
+
+For example, a GET of `/api/v1/files?path=demo.py&language=python` signs the
+method `GET`, that exact path-and-query string, and the SHA-256 hash of an empty
+body. `GET /api/v1/_capabilities` stays unauthenticated so siblings can probe
+the API surface before sending protected reads.
+
+Clarion still accepts the older `serve.http.token_env` bearer-token path for
+compatibility. Prefer `identity_token_env` for new deployments.
+
+Clarion refuses non-loopback binds unless `serve.http.allow_non_loopback: true`
+is set. Non-loopback deployments must also configure authentication; otherwise
+Clarion refuses to bind. Treat the endpoint as source-code metadata exposure:
+anyone who can reach it can read Clarion's catalog responses for the project.
+
+## Contract Summary
+
+`GET /api/v1/_capabilities` returns the read API `api_version`, the project
+`instance_id`, and booleans indicating whether registry-backend file resolution
+is available.
+
+`GET /api/v1/files?path=&language=` resolves an existing Clarion file-kind row
+to the entity ID and project-relative canonical path Filigree should store. It
+fails closed when the path is invalid, outside the project, missing from the
+catalog, or unavailable because of storage errors.
+
+## Trust assumption: loopback-no-token mode
+
+When both `serve.http.token_env` (legacy bearer) and
+`serve.http.identity_token_env` (HMAC, preferred per
+[ADR-034](../clarion/adr/ADR-034-federation-hardening.md)) are unset and the
+bind is loopback (default: `127.0.0.1:9111`), the HTTP read API serves
+unauthenticated. This is the intended single-user developer-workstation
+trust model — the loopback socket is reachable only from processes on the
+same host, and Clarion's catalogue is no more sensitive than the project
+source those processes can already read.
+
+**On a multi-tenant developer host or shared CI runner this trust model
+does not hold.** Any local process — any UID with read access to the
+loopback bind socket — can read the entire non-blocked catalogue,
+including every file's `entity_id`, `canonical_path`, `language`, and
+`content_hash`. This is the documented v1.0 trust matrix and is not a
+defect, but operators on multi-tenant hosts must configure authentication
+before binding.
+
+Multi-tenant operators MUST set `identity_token_env` (HMAC, preferred) or
+`token_env` (bearer, legacy) before running `clarion serve`. The HMAC
+configuration shape is documented in the [Trust Model](#trust-model)
+section above.
+
+The Clarion `serve` startup banner emits a `[TRUST]` line warning when
+loopback-no-token mode is active: `HTTP API serving on loopback without
+authentication; any local process on this host can read the catalogue.`
+The warning is logged at `WARN` level at startup whenever both auth knobs
+are unset and the bind is loopback.
diff --git a/docs/operator/coding-agent-llm-providers.md b/docs/operator/coding-agent-llm-providers.md
new file mode 100644
index 00000000..7d1536aa
--- /dev/null
+++ b/docs/operator/coding-agent-llm-providers.md
@@ -0,0 +1,157 @@
+# Coding-Agent LLM Providers
+
+Clarion can run live summary and inferred-edge LLM calls through local coding
+agent CLIs instead of an HTTP API key. These routes still send prompt content to
+the agent vendor, so they require the same explicit live-provider opt-in as
+OpenRouter.
+
+Supported provider values:
+
+- `codex_cli` uses `codex exec` with local Codex authentication.
+- `claude_cli` uses `claude -p` with local Claude Code authentication.
+- `openrouter` remains the HTTP provider for API-key based deployments.
+- `recording` remains the deterministic test fixture provider.
+
+## Codex CLI
+
+```yaml
+llm_policy:
+  enabled: true
+  provider: codex_cli
+  allow_live_provider: true
+  model_id: codex-cli-default
+  codex_cli:
+    executable: codex
+    model: null
+    profile: null
+    sandbox: read-only
+    timeout_seconds: 300
+  session_token_ceiling: 1000000
+  max_inferred_edges_per_caller: 8
+  cache_max_age_days: 180
+```
+
+Run `codex login status` before `clarion serve`. Clarion passes prompts on
+stdin, uses `--sandbox read-only`, `approval_policy="never"`, `--json`,
+`--output-last-message`, and `--output-schema`. Token usage is read from Codex
+JSONL events when available; otherwise Clarion falls back to local estimates.
+
+Set `codex_cli.model` only when you want to force a specific Codex model. When
+it is `null`, the Codex CLI profile/default model is used. `model_id` is the
+Clarion cache-key label for this route, so change it deliberately when changing
+the effective model or prompt-routing behavior.
+
+## Claude CLI
+
+```yaml
+llm_policy:
+  enabled: true
+  provider: claude_cli
+  allow_live_provider: true
+  model_id: claude-code-default
+  claude_cli:
+    executable: claude
+    model: null
+    permission_mode: plan
+    tools: []
+    timeout_seconds: 300
+    max_turns: 2
+    no_session_persistence: true
+    exclude_dynamic_system_prompt_sections: true
+  session_token_ceiling: 1000000
+  max_inferred_edges_per_caller: 8
+  cache_max_age_days: 180
+```
+
+Run `claude auth status` before `clarion serve`. Clarion uses print mode
+(`-p`), `--output-format json`, `--json-schema`, and stdin prompts. The default
+tool list is empty because Clarion already supplies the source excerpt and
+candidate graph context; add read-only tools only when you intentionally want
+Claude Code to inspect the workspace. Clarion also passes an explicit empty MCP
+config, `--strict-mcp-config`, and `--disable-slash-commands` so project/user
+MCP servers and skills do not inflate this bounded provider call.
+
+`exclude_dynamic_system_prompt_sections: true` is enabled by default because
+Claude Code documents it as a prompt-cache reuse aid for scripted workloads.
+`max_turns: 2` is intentional: Claude Code's structured-output path consumes one
+internal tool turn and then emits the final JSON result.
+
+## Live Opt-In
+
+`llm_policy.enabled: true` is not enough for any live provider. Set
+`allow_live_provider: true` in `clarion.yaml`, or launch with:
+
+```sh
+CLARION_LLM_LIVE=1 clarion serve --path .
+```
+
+Unlike OpenRouter, the CLI routes do not require `OPENROUTER_API_KEY` or an
+OpenAI/Anthropic API key in Clarion config. They rely on the local CLI's own
+login state.
+
+## Prompt Caching And Advanced Interfaces
+
+Clarion already has its own semantic result cache for summaries and inferred
+edges. Provider prompt caching is separate: it depends on the vendor surface,
+stable prompt prefixes, model choice, and usage telemetry.
+
+The CLI routes preserve stable invocation shape and expose cached-input-token
+usage when the CLI reports it. For deeper OpenAI integration, the Codex
+app-server protocol is the likely next provider shape: it is a JSON-RPC
+interface for authentication, conversation history, approvals, and streamed
+agent events. The OpenAI docs recommend the Codex SDK for automation/CI and the
+app-server protocol for rich product integrations.
+
+## Shared Agent Prompt Contract
+
+Both CLI providers wrap Clarion's leaf-summary and inferred-edge prompts in the
+same stable provider prompt before invoking the local agent. Future SDK or
+app-server providers should use `build_coding_agent_provider_prompt()` from
+`clarion_core` so all coding-agent surfaces share the same behavior:
+
+```text
+Prompt contract: clarion-agent-provider-v1
+You are Clarion's coding-agent LLM provider for repository graph enrichment.
+Clarion has already selected the source excerpt, entity metadata, unresolved
+call sites, and candidate graph context needed for this task.
+Follow these rules exactly:
+1. Use only the evidence inside <clarion_request>. Do not inspect additional
+   files, browse, run commands, edit files, or ask follow-up questions.
+2. Return exactly one JSON object matching the structured-output schema
+   supplied by the caller. Do not wrap it in Markdown or prose.
+3. Reason privately if needed, but do not expose hidden reasoning. Put only
+   concise evidence summaries in output fields that ask for rationale or
+   relationships.
+4. When evidence is absent, prefer empty strings for optional prose fields and
+   empty arrays for collection fields instead of guessing.
+5. Keep stable field names and JSON types; downstream Clarion storage parses the
+   response mechanically.
+```
+
+SDK providers should pass the same prompt as the user/task content and attach
+Clarion's purpose-specific JSON Schema through the SDK's structured-output
+mechanism. Do not replace this with an agentic "go inspect the repo" prompt:
+Clarion's MCP path is a bounded graph-enrichment call, not an autonomous code
+review session.
+
+Prompt surfaces by provider:
+
+- Codex CLI: pass the shared prompt to `codex exec -` on stdin and attach
+  Clarion's JSON Schema with `--output-schema`.
+- Claude CLI: use the short print-mode bootstrap prompt, pass the shared prompt
+  on stdin, and attach Clarion's JSON Schema with `--json-schema`.
+- Codex SDK or app-server: put the same shared prompt in the task/user content,
+  keep the developer/system instruction to "Clarion graph enrichment, JSON only,
+  no repository inspection", and attach the same purpose-specific schema through
+  structured output.
+- Claude Agent SDK: use the same task prompt and schema, disable tools by
+  default, and grant only read-only tools when an operator explicitly wants
+  workspace inspection.
+
+The stable prefix is intentional. It keeps provider prompt-caching viable while
+the volatile source excerpt, unresolved call sites, and candidates stay inside
+the `<clarion_request>` block.
+
+Do not use either CLI route as the pre-ingest secret scanner. Clarion's local
+secret scanner must continue to run before any prompt content is sent to a live
+provider.
diff --git a/docs/operator/getting-started.md b/docs/operator/getting-started.md
new file mode 100644
index 00000000..0e149612
--- /dev/null
+++ b/docs/operator/getting-started.md
@@ -0,0 +1,369 @@
+# Getting started with Clarion
+
+A single-flow walkthrough that takes you from an empty machine to a working
+consult-mode agent asking real questions about a real codebase. Target time:
+**≤15 minutes** once prerequisites are in place.
+
+You will:
+
+1. [Install Clarion + the Python plugin.](#1-install)
+2. [Run `clarion analyze` against a small public Python project.](#2-analyze)
+3. [Start `clarion serve` and connect an MCP client.](#3-serve)
+4. [Ask three questions through the MCP tools.](#4-ask)
+5. [Verify the secret-scanner block fires on a planted secret.](#5-secret-block)
+
+If a step fails, see [Troubleshooting](#troubleshooting) at the end.
+
+## Prerequisites
+
+| Tool | Required version | How to check |
+|---|---|---|
+| Rust toolchain | `stable` per [`rust-toolchain.toml`](../../rust-toolchain.toml) | `rustc --version` |
+| Python | `>= 3.11` per the [plugin manifest](../../plugins/python/pyproject.toml) | `python3 --version` |
+| `pipx` (recommended for plugin install) | any recent | `pipx --version` |
+| `pyright-langserver` | `1.1.409` — pinned in the [plugin manifest](../../plugins/python/plugin.toml) (`capabilities.runtime.pyright.pin`) | `pyright --version` (the `pyright-langserver` entrypoint only accepts protocol flags like `--stdio`) |
+| An MCP client | any MCP-speaking client | see [§3](#3-serve) |
+
+The Python plugin will fail at runtime if `pyright-langserver` is not on
+`$PATH` at the pinned version (1.1.409 in v1.0). Install via
+`npm install -g pyright@1.1.409` or `pipx install pyright==1.1.409`.
+
+### Required environment variables
+
+For step 4's `summary` question you need an OpenRouter API key:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+`clarion analyze` (step 2) and the structural MCP tools (`entity_at`,
+`find_entity`, `callers_of`, `execution_paths_from`, `issues_for`,
+`neighborhood`, `subsystem_members`, `subsystem_of`, `project_status`,
+`summary_preview_cost`, `source_for_entity`, `call_sites`, `orientation_pack`,
+`analyze_start`, `analyze_status`, `analyze_cancel`, `index_diff`) work without
+any LLM credentials — seventeen of the eighteen MCP tools are credential-free.
+The key is only consulted when an MCP client calls `summary(id)` against an entity that does not
+yet have a cached summary.
+
+## 1. Install
+
+Tagged v1.0 releases ship a platform archive for the Rust binary and a Python
+sdist for the language plugin via GitHub Releases (per
+[ADR-033](../clarion/adr/ADR-033-v1.0-distribution.md)). Until the first tag
+fires, use the source-install fallback below.
+
+```bash
+TAG=v1.0.0
+curl -L -o clarion-x86_64-unknown-linux-gnu.tar.gz \
+  "https://github.com/tachyon-beep/clarion/releases/download/${TAG}/clarion-x86_64-unknown-linux-gnu.tar.gz"
+tar xzf clarion-x86_64-unknown-linux-gnu.tar.gz
+install clarion-x86_64-unknown-linux-gnu/clarion ~/.local/bin/
+
+pipx install \
+  "https://github.com/tachyon-beep/clarion/releases/download/${TAG}/clarion-plugin-python-1.0.0.tar.gz"
+```
+
+Source-install fallback:
+
+```bash
+# Rust core
+cargo install --git https://github.com/tachyon-beep/clarion clarion-cli
+
+# Python plugin (provides clarion-plugin-python on $PATH)
+pipx install git+https://github.com/tachyon-beep/clarion#subdirectory=plugins/python
+```
+
+Verify the discovery surface:
+
+```bash
+which clarion                     # e.g. ~/.cargo/bin/clarion
+which clarion-plugin-python       # e.g. ~/.local/bin/clarion-plugin-python
+```
+
+### Verifying release artifacts
+
+Tagged releases publish platform archives, SHA256 files, keyless cosign
+signatures/certificates, and SLSA provenance. For a downloaded archive:
+
+```bash
+sha256sum -c clarion-x86_64-unknown-linux-gnu.tar.gz.sha256
+cosign verify-blob \
+  --certificate clarion-x86_64-unknown-linux-gnu.tar.gz.pem \
+  --signature clarion-x86_64-unknown-linux-gnu.tar.gz.sig \
+  --certificate-identity-regexp 'https://github.com/.+/.github/workflows/release.yml@refs/tags/v.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  clarion-x86_64-unknown-linux-gnu.tar.gz
+slsa-verifier verify-artifact \
+  --provenance-path clarion-rust-binaries.intoto.jsonl \
+  --source-uri github.com/tachyon-beep/clarion \
+  --source-tag "$TAG" \
+  clarion-x86_64-unknown-linux-gnu.tar.gz
+```
+
+The v1.0 release deliberately does not publish to PyPI or crates.io. GitHub
+Release assets are the source of truth until public registries are introduced
+by a later ADR.
+
+**`$PATH` discipline matters.** Clarion's plugin host (per
+[ADR-002](../clarion/adr/ADR-002-plugin-transport-json-rpc.md)) discovers
+plugins by walking `$PATH` for executables matching `clarion-plugin-*`. If
+`pipx`'s install directory (`~/.local/bin/` on Linux, `~/Library/...` on
+macOS) is not on your shell's `$PATH`, `clarion analyze` will exit
+**successfully** with status `skipped_no_plugins` and emit a `WARN no plugins
+discovered` line — the analyse pass produces nothing. See
+[Troubleshooting → "analyze runs but emits no entities"](#analyze-runs-but-emits-no-entities)
+below for the diagnostic.
+
+## 2. Analyze
+
+Pick a small, well-behaved Python project. The walkthrough uses the `requests`
+library's source tree:
+
+```bash
+cd /tmp
+curl -L -o requests-2.32.4.tar.gz https://github.com/psf/requests/archive/refs/tags/v2.32.4.tar.gz
+tar xzf requests-2.32.4.tar.gz
+cd requests-2.32.4
+```
+
+Initialise Clarion's project-local state, then run the analyser:
+
+```bash
+clarion install
+clarion analyze
+```
+
+Expected output (abridged):
+
+```
+applying migration version=1 name="0001_initial_schema"
+clarion install complete clarion_dir=/tmp/requests-2.32.4/.clarion
+Initialised /tmp/requests-2.32.4/.clarion
+...
+analyze complete: run <uuid> ok (entities=NNN, edges=MMM)
+```
+
+The first run on a tree of this size completes in well under a minute on
+typical hardware. The result lives at `.clarion/clarion.db` (a single SQLite
+file) and is safe to commit to git — see
+[ADR-005](../clarion/adr/ADR-005-clarion-dir-tracking.md).
+
+## 3. Serve
+
+Start the MCP stdio server in one shell:
+
+```bash
+clarion serve --path /tmp/requests-2.32.4
+```
+
+`clarion serve` speaks the MCP protocol over stdio. Any MCP client works;
+documented options:
+
+- **Claude Desktop.** Add to your `claude_desktop_config.json`:
+
+  ```json
+  {
+    "mcpServers": {
+      "clarion-requests": {
+        "command": "/path/to/clarion",
+        "args": ["serve", "--path", "/tmp/requests-2.32.4"],
+        "env": {
+          "OPENROUTER_API_KEY": "sk-or-v1-..."
+        }
+      }
+    }
+  }
+  ```
+
+- **MCP Inspector** (`npm install -g @modelcontextprotocol/inspector`) for
+  ad-hoc tool-level exploration without an agent in the loop:
+
+  ```bash
+  npx @modelcontextprotocol/inspector clarion serve --path /tmp/requests-2.32.4
+  ```
+
+Pick whichever you have; the questions in step 4 are client-agnostic.
+
+### Agent orientation (optional but recommended)
+
+Give consult-mode agents a head start:
+
+```bash
+clarion install --skills --path /tmp/requests-2.32.4   # bundle the clarion-workflow skill
+clarion install --hooks --path /tmp/requests-2.32.4    # add a SessionStart snapshot hook
+clarion install --all   --path /tmp/requests-2.32.4    # .clarion/ init + skills + hooks
+```
+
+`--skills` writes `.claude/skills/clarion-workflow/` and `.agents/skills/clarion-workflow/`.
+`--hooks` merges a SessionStart entry into `.claude/settings.json` (existing
+hooks are preserved) that runs `clarion hook session-start` — a fail-soft
+command printing live entity/subsystem/finding counts and index freshness.
+
+Over MCP, the same orientation is available without install: the `initialize`
+result carries an `instructions` field, the `clarion://context` resource returns
+the live snapshot, and the `clarion-workflow` prompt returns the skill text.
+
+## 4. Ask
+
+### Enable live LLM (one-time)
+
+The structural MCP tools work out of the box, but `summary(id)` (question 3
+below) needs the live OpenRouter path explicitly opted into. Edit
+`/tmp/requests-2.32.4/clarion.yaml` and set both:
+
+```yaml
+llm_policy:
+  enabled: true
+  allow_live_provider: true
+```
+
+`OPENROUTER_API_KEY` must also be exported in the environment that
+`clarion serve` (or your MCP client wrapper) inherits — see the
+prerequisites section above. Skip this block if you don't have a key; the
+other seventeen tools still work, only `summary` will return an "LLM disabled"
+envelope.
+
+### The MCP tools
+
+The MCP surface exposes eighteen tools: the seventeen in the table below, plus
+`subsystem_members` (the modules in a subsystem — the forward direction of
+`subsystem_of`). The table spans entity lookup and navigation
+(`entity_at`/`find_entity`/`callers_of`/`execution_paths_from`/`neighborhood`),
+clustering (`subsystem_of`), source and edge inspection
+(`source_for_entity`/`call_sites`), the one-call orientation packet
+(`orientation_pack`), diagnostics (`project_status`/`index_diff`), the
+`summary` LLM path plus its `summary_preview_cost` estimator, Filigree
+enrichment (`issues_for`), and the background re-index lifecycle
+(`analyze_start`/`analyze_status`/`analyze_cancel`). Seventeen of the eighteen
+are credential-free; only `summary` needs the live LLM. Each is a structured
+graph query, not free-text grep.
+
+| Tool | Example invocation |
+|---|---|
+| `entity_at(file, line)` | `entity_at(file="requests/sessions.py", line=480)` — which entity covers this source location? |
+| `find_entity(pattern)` | `find_entity(pattern="Session.send")` — find entities matching a name or summary fragment. |
+| `callers_of(id)` | `callers_of(id="python:function:requests.sessions.Session.send")` — who calls this function? Default confidence is `resolved`. |
+| `execution_paths_from(id, max_depth)` | `execution_paths_from(id="python:function:requests.api.get", max_depth=3)` — bounded calls-only paths from an entry point. |
+| `summary(id)` | `summary(id="python:function:requests.sessions.Session.send")` — structured LLM summary with `purpose` / `behavior` / `relationships` / `risks` fields. Requires the live-LLM opt-in above plus `OPENROUTER_API_KEY`. First call dispatches the LLM and caches; subsequent calls hit the cache. |
+| `issues_for(id)` | `issues_for(id="python:module:requests.sessions")` — Filigree issues attached to this entity, if Filigree is reachable. Returns an `unavailable` envelope if not (Filigree is enrich-only). |
+| `neighborhood(id)` | `neighborhood(id="python:function:requests.sessions.Session.send")` — callers, callees, container, contained entities, and references in one hop. |
+| `subsystem_of(id)` | `subsystem_of(id="python:module:requests.sessions")` — the subsystem an entity belongs to (reverse of `subsystem_members`); a function/class resolves through its containing module. |
+| `project_status()` | `project_status()` — index diagnostics: latest run, entity/edge/finding/briefing-blocked counts, staleness, per-plugin counts, LLM policy, and the resolved Filigree endpoint. No arguments, no LLM. |
+| `summary_preview_cost(id)` | `summary_preview_cost(id="python:function:requests.sessions.Session.send")` — preview a `summary` call before spending: cache hit/expired/miss, cached tokens/cost/age, an input-token estimate on a miss, LLM policy, and whether a live call would spend. Never calls the LLM. |
+| `source_for_entity(id, context_lines)` | `source_for_entity(id="python:function:requests.sessions.Session.send", context_lines=10)` — the entity's exact indexed source span plus bounded line-numbered context, each line flagged `in_entity`. Reports `source_status` (`ok`/`missing`/`drifted`/…) instead of a stale snippet. No LLM. |
+| `call_sites(id, role)` | `call_sites(id="python:function:requests.sessions.Session.send", role="caller")` — the actual source line(s) behind calls/references edges: file, line, line text, edge kind, confidence, and resolved/ambiguous/unresolved classification. `role="callee"` shows incoming sites. No LLM. |
+| `orientation_pack(entity \| file, line)` | `orientation_pack(file="requests/sessions.py", line=480)` — one deterministic packet for a location: primary entity, `entity_context` evidence, source-span summary, one-hop neighbors, compact execution paths, related Filigree issues, index/Filigree/LLM health, and suggested next reads. Resolve by `entity` id or by `file`+`line`. No LLM. |
+| `analyze_start()` | `analyze_start()` — launch a background `clarion analyze` re-index and return its `run_id` immediately. One run per project (cross-process lock). No arguments, no LLM. |
+| `analyze_status(run_id)` | `analyze_status(run_id="…")` — live status of a run: `queued`/`running`/`completed`/`failed`/`cancelled`/`skipped_no_plugins`, phase, processed/total files, heartbeat, and recorded stats on a terminal status. No LLM. |
+| `analyze_cancel(run_id)` | `analyze_cancel(run_id="…")` — SIGKILL a running analyze's process group (plugin + Pyright) and record its terminal state. No LLM. |
+| `index_diff()` | `index_diff()` — freshness / drift report: latest completed run, indexed-file drift (mtime vs. index), and git working-tree changes correlated against indexed paths. No arguments, no LLM. |
+
+The three questions to walk through with your agent:
+
+1. **"List the top-level modules in this project."** Exercises `find_entity`
+   with a broad pattern.
+2. **"What calls `requests.get`?"** Exercises `callers_of` against a
+   well-known entry point.
+3. **"Summarise `requests.sessions.Session.send`."** Exercises the live LLM
+   path (`summary`), the OpenRouter provider, the budget ledger, and the
+   summary cache. The second invocation of the same `summary(id)` is a cache
+   hit; verify by re-asking and noting the near-zero latency.
+
+A successful run gives you three substantive, graph-grounded answers — not
+"here is what grep found." If the agent improvises by reading source files
+directly, the answer is real but does not exercise the MCP surface; check
+that your client actually called the tools.
+
+Re-run analyse for idempotency:
+
+```bash
+clarion analyze
+# entity/edge counts on the second run should match the first
+```
+
+## 5. Secret-block
+
+Plant a fake AWS credential and re-run analyse:
+
+```bash
+cat > .env <<'EOF'
+AWS_ACCESS_KEY_ID=AKIA0123456789ABCDEF
+EOF
+
+clarion analyze
+```
+
+Expected behaviour:
+
+- `clarion analyze` exits **0** with run status `completed`.
+- A `CLA-SEC-SECRET-DETECTED` finding lands in `findings` with the message
+  `AwsAccessKeyId detected in /tmp/requests-2.32.4/.env:1`. Inspect with
+  `sqlite3 .clarion/clarion.db "SELECT rule_id, message FROM findings
+  WHERE rule_id LIKE 'CLA-SEC%';"`.
+- The `.env` file itself has no language entities (it's not Python), so
+  the finding is anchored to the core-minted file entity rather than a
+  language-plugin entity. Source files in the project that the scanner
+  also flags (e.g. high-entropy strings in `requests/utils.py`) get
+  `properties.briefing_blocked = "secret_present"` on their containing
+  module entity, and the `summary(id)` MCP tool returns a
+  `briefing_blocked: "secret_present"` envelope instead of dispatching
+  the LLM.
+
+Full mechanics — baseline format, override flags, audit queries — in
+[secret-scanning.md](./secret-scanning.md).
+
+## Troubleshooting
+
+### `analyze` runs but emits no entities
+
+Look for `WARN no plugins discovered` and `skipped_no_plugins` in the
+analyse output. The plugin host walks `$PATH` for `clarion-plugin-*`
+executables; if your shell's `$PATH` does not include `pipx`'s install
+directory the plugin is invisible.
+
+Confirm and fix:
+
+```bash
+which clarion-plugin-python || echo "not on PATH"
+echo $PATH                          # is pipx's bin dir in here?
+
+# If pipx is installed but its bin dir is missing:
+pipx ensurepath                     # writes the PATH update; restart shell
+```
+
+Note: `clarion analyze` deliberately exits **0** even when no plugins are
+discovered, so the run can be re-attempted without manual cleanup. The
+`WARN` line and the `skipped_no_plugins` run status are the operator-facing
+signals. A `clarion doctor` subcommand that surfaces discovery state at exit
+is on the v2.0 roadmap; for v1.0 the diagnostic is the WARN line plus the
+`which clarion-plugin-*` check above.
+
+### "secret_present" block fires on a real file
+
+Add the file to `.clarion/secrets-baseline.yaml` with a written justification
+(the schema requires it). Full procedure: [secret-scanning.md](./secret-scanning.md).
+
+### `summary` returns an error citing budget or LLM provider
+
+Check `OPENROUTER_API_KEY` is set in the environment that `clarion serve`
+inherits (for Claude Desktop that means the `env` block in the MCP-server
+config). Live LLM calls are also gated by `llm_policy.enabled: true` and
+`llm_policy.allow_live_provider: true` in `clarion.yaml` — see
+[openrouter.md](./openrouter.md).
+
+### `issues_for` returns an `unavailable` envelope
+
+Expected when Filigree is not reachable. Filigree integration is
+*enrich-only* per the Loom federation axiom — Clarion's structural answers
+are unaffected. See
+[CON-FILIGREE-02](../clarion/1.0/requirements.md#con-filigree-02--file-registry-displacement-is-deferred-to-v02)
+for the v1.0 → v2.0 trajectory.
+
+## Where to go next
+
+- [Operator notes index](./README.md) — OpenRouter, runtime topology,
+  secret scanning, federation contracts, coding-agent LLM providers.
+- [Design ladder](../clarion/1.0/README.md) — requirements → system-design →
+  detailed-design.
+- [ADR index](../clarion/adr/README.md) — accepted architecture decisions.
+- [CLAUDE.md](../../CLAUDE.md) — repository conventions.
diff --git a/docs/operator/openrouter.md b/docs/operator/openrouter.md
index f518b5e3..38d443dc 100644
--- a/docs/operator/openrouter.md
+++ b/docs/operator/openrouter.md
@@ -1,9 +1,12 @@
 # OpenRouter LLM Provider
 
-Clarion v0.1 uses OpenRouter as its canonical live LLM provider. The provider
+Clarion uses OpenRouter as its canonical HTTP LLM provider. The provider
 speaks OpenAI-compatible Chat Completions HTTP through the existing
-`LlmProvider` trait, so tests can continue to use `RecordingProvider` and future
-providers can be added without changing MCP tool call sites.
+`LlmProvider` trait, so tests can continue to use `RecordingProvider` and
+coding-agent CLI providers can be added without changing MCP tool call sites.
+
+For local-login alternatives that avoid API keys in Clarion config, see
+[Coding-agent LLM providers](./coding-agent-llm-providers.md).
 
 ## Configure Clarion
 
@@ -19,7 +22,7 @@ llm_policy:
     endpoint_url: https://openrouter.ai/api/v1
     api_key_env: OPENROUTER_API_KEY
     attribution:
-      referer: https://github.com/qacona/clarion
+      referer: https://github.com/tachyon-beep/clarion
       title: Clarion
   model_id: anthropic/claude-sonnet-4.6
   session_token_ceiling: 1000000
@@ -52,7 +55,7 @@ OpenRouter model IDs are concrete strings such as:
 - `meta-llama/llama-3.1-8b-instruct`
 
 Clarion stores this exact string in the summary cache key's `model_tier`
-component. There is no tier-name resolver in v0.1; operators choose the concrete
+component. There is no tier-name resolver in v1.0; operators choose the concrete
 model in `clarion.yaml`. Refresh the chosen ID against OpenRouter's Models API
 before release or production use.
 
@@ -75,7 +78,7 @@ tokens.
 
 To clear a blocked LLM budget, stop and restart `clarion serve`. To change the
 future ceiling, edit `llm_policy.session_token_ceiling` in `clarion.yaml` before
-restarting. Clarion v0.1 intentionally has no MCP tool that resets the in-memory
+restarting. Clarion v1.0 intentionally has no MCP tool that resets the in-memory
 budget ledger.
 
 Dollar budgeting remains an operator concern in OpenRouter billing controls.
diff --git a/docs/operator/secret-scanning.md b/docs/operator/secret-scanning.md
new file mode 100644
index 00000000..e9ddadd4
--- /dev/null
+++ b/docs/operator/secret-scanning.md
@@ -0,0 +1,144 @@
+# Secret Scanning
+
+Clarion scans source files before any file content can be used for LLM summaries. A detected credential creates a finding and marks entities from that file with `briefing_blocked: secret_present`. Structural analysis still runs, but summaries for that file do not.
+
+## What Gets Blocked
+
+Blocking is file-level. If `src/config.py` contains a detected key, entities from that file remain queryable through structural tools, but the `summary` tool returns a policy envelope instead of calling the LLM provider or writing `summary_cache`.
+
+Plugin source files and `.env` sidecars are scanned. If a plugin reports an entity for some other in-project path that was not covered by the scanner, Clarion marks that entity `briefing_blocked: unscanned_source` so source bytes cannot reach the LLM provider without a prior scan.
+
+## Whitelist A False Positive
+
+Add `.clarion/secrets-baseline.yaml` and commit it with the source change:
+
+```yaml
+version: "1.0"
+results:
+  "src/auth/fixtures.py":
+    - type: "AWS Access Key"
+      hashed_secret: "25910f981e85ca04baf359199dd0bd4a3ae738b6"
+      line_number: 42
+      is_secret: false
+      justification: "AWS documentation example key used in a test fixture."
+```
+
+The hash is SHA-1 over the matched literal bytes, matching `detect-secrets` v1.x baseline conventions. `justification` is required; entries without it are ignored and produce `CLA-INFRA-SECRET-BASELINE-NO-JUSTIFICATION`.
+
+A matching baseline entry suppresses the block and records `CLA-INFRA-SECRET-BASELINE-MATCH` for audit.
+
+## Override Flag
+
+Use `--allow-unredacted-secrets` only when you deliberately accept that detected secrets may reach the LLM provider.
+
+When detections exist, interactive runs prompt for:
+
+```text
+yes-i-understand
+```
+
+Non-TTY runs must pass both flags:
+
+```bash
+clarion analyze --allow-unredacted-secrets \
+  --confirm-allow-unredacted-secrets=yes-i-understand .
+```
+
+Confirmed overrides do not set `briefing_blocked`; they emit `CLA-SEC-UNREDACTED-SECRETS-ALLOWED` and add `secret_override_used` plus `secret_override_files_affected` to `runs.stats`. Passing `--allow-unredacted-secrets` on a clean repo is a no-op.
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Analysis completed, with or without secret findings or a confirmed override. |
+| 1 | Hard failure in the normal analysis path. |
+| 78 | Secret override was requested but not confirmed; no run row is started. |
+
+## Audit Trail
+
+Local SQLite:
+
+```sql
+select rule_id, severity, message, evidence
+from findings
+where rule_id like 'CLA-SEC-%'
+   or rule_id like 'CLA-INFRA-SECRET-%';
+```
+
+Currently blocked entities:
+
+```sql
+select id, plugin_id, kind, name,
+       json_extract(properties, '$.briefing_blocked') as block_reason
+from entities
+where json_extract(properties, '$.briefing_blocked') is not null;
+```
+
+Filigree integration for scanner findings (WP9-B finding emission) is deferred to v1.1. Until then, the local `findings` table is the authoritative scanner audit surface.
+
+## Limitations
+
+The scanner is pattern-based. It can miss novel internal key formats and it can flag high-entropy test data. Use a justified baseline for reviewed false positives, and disable LLM dispatch entirely for repos where any source disclosure would be unacceptable — set `llm.allow_live_provider: false` in `clarion.yaml` (or leave `CLARION_LLM_LIVE` unset) so the recording provider is the only path Clarion will take.
+
+Contextual credential suppression currently recognises shell/Python `#` comments only. It does not recognise `//` or `/* */` comments; use a justified baseline entry for reviewed non-Python test fixtures.
+
+See [ADR-013](../clarion/adr/ADR-013-pre-ingest-secret-scanner.md) for design rationale.
+
+## Trust assumption: loopback-no-token mode
+
+The pre-ingest scanner's briefing-blocked annotations are only effective if
+the HTTP read API also refuses to surface blocked entities to unauthorised
+callers. The v1.0 HTTP API has one mode where it serves any local caller
+without authentication: **loopback bind with no token configured.**
+
+When both `serve.http.token_env` (legacy bearer) and `serve.http.identity_token_env`
+(HMAC, preferred per [ADR-034](../clarion/adr/ADR-034-federation-hardening.md))
+are unset and the bind is loopback (default: `127.0.0.1:9111`), the HTTP read
+API serves unauthenticated. On a single-user developer workstation this is
+the intended trust model: the loopback socket is reachable only from
+processes on that host, and Clarion's catalogue is no more sensitive than
+the project source those processes can already read.
+
+**On a multi-tenant developer host or shared CI runner the trust model is
+different.** Any local process — any UID with read access to the loopback
+bind socket — can read the entire non-blocked catalogue, including every
+file's `entity_id`, `canonical_path`, `language`, and `content_hash`. This
+is the documented v1.0 trust matrix; it is not a defect, but it is a
+constraint operators must understand.
+
+Multi-tenant operators MUST set `identity_token_env` (HMAC, preferred) or
+`token_env` (bearer, legacy) before running `clarion serve`. See
+[`clarion-http-read-api.md`](./clarion-http-read-api.md) for the
+configuration shape.
+
+The Clarion `serve` startup banner emits a `[TRUST]` line warning when
+loopback-no-token mode is active: `HTTP API serving on loopback without
+authentication; any local process on this host can read the catalogue.`
+This warning is logged at `WARN` level at startup whenever both auth knobs
+are unset and the bind is loopback.
+
+## Pre-WP5 catalogue upgrade requirement
+
+The WP5 pre-ingest secret scanner ships in v1.0. Briefing-blocked entities
+are marked by writing `briefing_blocked: <reason>` into the file entity's
+`properties` JSON column. v1.1 will promote `briefing_blocked` to a typed
+column on `entities`; v1.0 carries it as a JSON property.
+
+**A v1.0 binary opening a `.clarion/clarion.db` produced by a pre-WP5
+Clarion binary will find no `briefing_blocked` properties on any row.**
+Pre-WP5 binaries never ran the scanner and never wrote the property; the
+1.0 binary cannot retroactively discover which files contained secrets at
+that earlier scan time. The HTTP read API will serve the entire catalogue
+without refusal because every row's `briefing_blocked` is structurally
+absent.
+
+**Required upgrade procedure:** after installing the v1.0 binary against
+a project root that was previously analyzed by a pre-WP5 binary, run
+`clarion analyze` (with the secret scanner active, which is the default)
+against the project root **before** exposing the HTTP read API or calling
+the `summary` MCP tool. The re-analyze produces a fresh briefing-blocked
+annotation pass over all current file entities.
+
+This applies only to upgrades from a Clarion binary built before WP5
+landed. A v1.0 installation that has never been opened by a pre-WP5
+binary is unaffected.
diff --git a/docs/operator/v1.0-release-governance.md b/docs/operator/v1.0-release-governance.md
new file mode 100644
index 00000000..e75baa28
--- /dev/null
+++ b/docs/operator/v1.0-release-governance.md
@@ -0,0 +1,191 @@
+# v1.0 Release Governance
+
+Clarion v1.0 publishes from GitHub Releases, not public package registries.
+Before the `v1.0.0` tag is cut, the repository owner must enable live GitHub
+controls that force the release commit through the reviewed PR and CI path.
+
+This page is intentionally narrow: it covers the GitHub settings required by
+`scripts/check-github-release-governance.py`. Do not change repository settings
+while a release is in progress unless you are the maintainer responsible for
+the release.
+
+## Required Controls
+
+The v1.0 tag gate requires:
+
+- `main` is protected by branch protection or an active repository ruleset.
+- The protection/ruleset targets `main`.
+- Pull-request flow is required before changes reach `main`.
+- These CI checks are required:
+  - `Rust`
+  - `Python plugin`
+  - `Sprint 1 walking skeleton (end-to-end)`
+- GitHub Actions are enabled.
+- Actions are not configured as `allowed_actions=all` unless SHA pinning is
+  also required.
+- Workflow action references stay pinned to full commit SHAs.
+- Dependabot keeps GitHub Actions pins on a weekly update lane.
+
+The source-tree checks run before any GitHub API calls. The live GitHub checks
+require a token that can read repository administration settings and Actions
+policy settings. A fine-grained token needs repository administration access for
+rulesets/branch protection and repository Actions policy access for
+`/actions/permissions`.
+
+Configure that token as a repository Actions secret named
+`RELEASE_GOVERNANCE_TOKEN` before running `.github/workflows/release.yml`.
+The release workflow uses this secret for the `GitHub release governance` job,
+and the build jobs do not start unless the guard passes.
+
+```bash
+python scripts/check-github-release-governance.py \
+  --repository tachyon-beep/clarion \
+  --branch main
+```
+
+## Recommended GitHub Settings
+
+Use either a repository ruleset or classic branch protection. A ruleset is
+preferred because it is easier to audit as one release gate.
+
+### Repository Ruleset
+
+Create an active repository ruleset with:
+
+- Target: branches.
+- Include: `refs/heads/main`.
+- Enforcement: active.
+- Do not use evaluate/monitor mode for the release gate; it reports violations
+  but does not enforce the reviewed release path.
+- Rules:
+  - require a pull request before merging;
+  - require status checks to pass;
+  - require the branch to be up to date before merge;
+  - require the three v1.0 CI checks named above.
+
+The REST shape for the ruleset is:
+
+```json
+{
+  "name": "v1.0 release gate",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/heads/main"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "automatic_copilot_code_review_enabled": false,
+        "allowed_merge_methods": ["merge"]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": true,
+        "required_status_checks": [
+          {"context": "Rust"},
+          {"context": "Python plugin"},
+          {"context": "Sprint 1 walking skeleton (end-to-end)"}
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Actions Policy
+
+Set repository Actions permissions to keep Actions enabled, constrain allowed
+actions, and require SHA pinning. The repository workflows already pin external
+actions to full SHAs and Dependabot is configured to update those pins.
+
+The REST request body is:
+
+```json
+{
+  "enabled": true,
+  "allowed_actions": "selected",
+  "sha_pinning_required": true
+}
+```
+
+If GitHub rejects `sha_pinning_required`, check whether the repository is under
+an organization or enterprise policy that controls action-source restrictions.
+The release gate is not satisfied until the guard reports a constrained Actions
+policy.
+
+If the guard exits with code `2` and an HTTP 403 from `/actions/permissions`,
+the token cannot read repository Actions policy settings. Re-run with a
+maintainer token that has that permission before treating the release gate as
+evaluated.
+
+## Release Sequence
+
+1. Confirm PR #12 is green and clean:
+
+   ```bash
+   gh pr view 12 --json state,mergeStateStatus,statusCheckRollup,headRefOid
+   ```
+
+2. Enable the GitHub repository controls above.
+
+3. Configure the maintainer-scoped governance token:
+
+   ```bash
+   gh secret set RELEASE_GOVERNANCE_TOKEN --repo tachyon-beep/clarion
+   ```
+
+4. Run the governance guard locally with the same token scope and require a
+   pass:
+
+   ```bash
+   python scripts/check-github-release-governance.py \
+     --repository tachyon-beep/clarion \
+     --branch main
+   ```
+
+5. Merge PR #12 to `main`.
+
+6. Run the release workflow manually from `main` before creating the tag:
+
+   ```bash
+   gh workflow run release.yml --ref main
+   gh run list --workflow release.yml --limit 1
+   gh run watch <run-id> --exit-status
+   ```
+
+   `workflow_dispatch` validates the build and artifact path but does not
+   publish a GitHub Release. It also runs the same governance guard with
+   `RELEASE_GOVERNANCE_TOKEN`; do not proceed if that job fails.
+
+7. Run the governance guard again immediately before pushing `v1.0.0`.
+
+8. Push the release tag only after the guard and release dry run are green.
+
+9. After the tag workflow finishes, download the public Linux archive and
+   Python sdist from the Release and repeat the
+   [getting started walkthrough](./getting-started.md) on a clean machine or VM.
+
+## See also
+
+- [`v1.0-release-rollback.md`](./v1.0-release-rollback.md) — post-publish
+  incident runbook (yanking a bad release, supersession via v1.0.1,
+  Rekor non-revocability, downstream notification, postmortem).
+
+## References
+
+- GitHub REST API: repository rulesets:
+  <https://docs.github.com/rest/repos/rules>
+- GitHub REST API: Actions permissions:
+  <https://docs.github.com/rest/actions/permissions>
diff --git a/docs/operator/v1.0-release-rollback.md b/docs/operator/v1.0-release-rollback.md
new file mode 100644
index 00000000..d8ec72cb
--- /dev/null
+++ b/docs/operator/v1.0-release-rollback.md
@@ -0,0 +1,141 @@
+# v1.0 Release Rollback / Yank Runbook
+
+This runbook covers the h+30min "we shipped a bad release" scenario for
+`v1.0.0` (or any later 1.x tag) once the GitHub Release is public. It is the
+sibling of [`v1.0-release-governance.md`](./v1.0-release-governance.md), which
+covers the *pre-publish* controls; this page covers the *post-publish*
+incident path.
+
+Read this page top to bottom before taking any action. The order of steps
+matters: removing the "latest" pointer is reversible; deleting assets is not,
+and Sigstore Rekor entries cannot be deleted at all.
+
+## 1. Immediate first action — un-mark "latest"
+
+Within minutes of confirming a bad release, demote the release from `latest`
+to `prerelease`. This removes it from the GitHub UI's "Latest" pointer and
+from `gh release view --json isLatest` queries, but leaves the assets and
+download URLs intact:
+
+```bash
+gh release edit v1.0.0 --prerelease
+```
+
+This is the **only** action you take while still triaging. Do not delete
+assets, do not delete the tag, do not delete the release.
+
+Verify:
+
+```bash
+gh release view v1.0.0 --json tagName,isLatest,isPrerelease
+```
+
+Expect `isLatest: false`, `isPrerelease: true`.
+
+## 2. Asset handling policy — keep the URLs working
+
+**Do NOT delete release assets unless they contain sensitive data
+(leaked credentials, embedded PII, or a binary the legal team has ruled must
+be withdrawn).** A broken download URL is materially worse than a stale file:
+
+- Operator docs and the Sprint 1 walkthrough pin specific release-asset URLs
+  by tag. A `curl -L` against a deleted asset returns 404; a stale-but-known
+  binary at least produces a reproducible failure mode.
+- Filigree CI and any downstream consumers that pin Clarion plugin URLs (e.g.
+  `pipx install https://.../clarion-plugin-python-1.0.0.tar.gz`) break loudly
+  rather than silently rolling forward.
+- The cosign signatures and SLSA provenance attestations are bound to the
+  exact asset bytes; deleting and re-uploading does not restore the original
+  signature chain.
+
+If the release contains sensitive data, document the deletion in the
+postmortem (§6) and notify downstream consumers (§5) before deleting.
+Otherwise, leave the assets in place and rely on the `--prerelease`
+demotion in §1 plus the v1.0.1 supersession in §4.
+
+## 3. Sigstore Rekor non-revocability
+
+Cosign keyless signatures recorded in the public Sigstore Rekor transparency
+log **cannot be deleted, revoked, or hidden**. This is by design — Rekor is
+an append-only log, and that immutability is the property that lets a
+verifier trust a signature retrospectively.
+
+What this means for an operator yanking a release:
+
+- Every cosign-signed artifact the release-workflow uploaded will continue
+  to verify against its Rekor entry, indefinitely. `cosign verify-blob`
+  against the yanked assets will return success.
+- The SLSA provenance attestations attached to the workflow run will also
+  persist in Rekor and continue to verify.
+- The yank is therefore a **supersession**, not a revocation. The mechanism
+  is publishing a v1.0.1 (§4) that explicitly references the yanked
+  v1.0.0 entries in its release body, and updating downstream consumers
+  (§5) so they pin v1.0.1.
+
+If a yanked release shipped with a vulnerability that operators must not
+run, the supersession note in §4 is the primary user-visible signal. Do
+not assume the Rekor entry can be removed — it cannot.
+
+## 4. v1.0.1 publication — the supersession mechanism
+
+The standard tag-cut procedure from
+[`v1.0-release-governance.md`](./v1.0-release-governance.md) applies, with
+one addition: the v1.0.1 release body **must** carry a supersession note.
+Suggested body opening:
+
+```markdown
+**Supersedes v1.0.0 (yanked) — see <URL to incident postmortem or
+filigree issue>.**
+
+v1.0.0 was demoted to prerelease and superseded by this release because
+<one-line summary of the defect>. Operators who installed v1.0.0 should
+upgrade to v1.0.1; the v1.0.0 cosign signatures and Rekor entries remain
+verifiable but should not be used to gate new installs.
+```
+
+Run the full governance guard before tagging v1.0.1 — none of the gates from
+the governance doc are waived for an incident-driven release.
+
+## 5. Downstream notification
+
+Any known Filigree integrators and other downstream consumers (e.g.
+operators running `pipx install` of the Clarion plugin against a pinned
+v1.0.0 URL) must be informed out-of-band that v1.0.0 has been yanked.
+
+**Current notification path (informal):** the maintainer notifies known
+operators by direct message and posts to whichever issue tracker they own.
+There is no broadcast list at v1.0.
+
+**Flagged as a v1.1 hardening target:** a maintained downstream-consumers
+list and a documented broadcast path (mailing list, security advisory feed,
+or equivalent). Until then, the maintainer is the source of truth for who
+needs to be told.
+
+If you are the operator running the yank, write down everyone you notified
+and add the list to the postmortem (§6).
+
+## 6. Postmortem requirement
+
+Create a `filigree` incident issue at the moment the yank begins:
+
+```bash
+filigree create \
+  --title "Incident: v1.0.0 yanked — <one-line defect>" \
+  --priority P0 \
+  --label incident \
+  --actor <your-name>
+```
+
+The issue captures the incident timeline, defect summary, fix landed in
+v1.0.1, downstream notifications sent (§5), and any asset-deletion decisions
+(§2). Link the issue URL from the v1.0.1 release body's supersession note.
+
+The incident issue stays `release:1.x` (the release that fixed it) and uses
+the `incident` label so the post-incident review pass can find it.
+
+## See also
+
+- [`v1.0-release-governance.md`](./v1.0-release-governance.md) — pre-publish
+  controls and the tag-cut procedure that v1.0.1 also runs.
+- [`getting-started.md`](./getting-started.md) — the public install path that
+  the supersession is protecting.
diff --git a/docs/suite/briefing.md b/docs/suite/briefing.md
index fd338aa2..e5acaea3 100644
--- a/docs/suite/briefing.md
+++ b/docs/suite/briefing.md
@@ -24,7 +24,7 @@ Clarion ingests a codebase, extracts entities (functions, classes, modules, pack
 
 **Typical invocation**: `clarion analyze <project>` for batch indexing; `clarion serve` for MCP + HTTP consult.
 
-**Status**: designed, not yet built. Target first customer is `elspeth` (~425k LOC Python).
+**Status**: walking skeleton merged (Sprint 1, tagged `v0.1-sprint-1`); v0.1 build in flight against the published design. Target first customer is `elspeth` (~425k LOC Python).
 
 ### Filigree — the workflow and findings tracker
 
@@ -137,7 +137,7 @@ Four commitments keep the Loom products from drifting into overlap (see [loom.md
 |---|---|---|---|
 | Filigree | Yes | Yes — active development | `filigree` itself; this project |
 | Wardline | Yes | Yes — commit-cadence scanner | Wardline's own codebase |
-| Clarion | No — designed only | Not yet | `elspeth` (~425k LOC Python) targeted for v0.1 validation |
+| Clarion | Partial — Sprint 1 walking skeleton tagged `v0.1-sprint-1`; v0.1 build in flight | Not yet — pre-v0.1 release | `elspeth` (~425k LOC Python) targeted for v0.1 validation |
 | Shuttle | No — proposed; no design yet | Not yet | None — not yet scoped |
 
 ### What Clarion v0.1 ships
@@ -180,7 +180,7 @@ Clarion's v0.1 design set spells these asks out in [system-design.md](../clarion
 | Read Clarion's requirements | [../clarion/v0.1/requirements.md](../clarion/v0.1/requirements.md) |
 | Read Clarion's system design | [../clarion/v0.1/system-design.md](../clarion/v0.1/system-design.md) |
 | Read Clarion's detailed design reference | [../clarion/v0.1/detailed-design.md](../clarion/v0.1/detailed-design.md) |
-| See what the design reviewer flagged | [../clarion/v0.1/reviews/pre-restructure/design-review.md](../clarion/v0.1/reviews/pre-restructure/design-review.md) |
-| See the integration reality check | [../clarion/v0.1/reviews/pre-restructure/integration-recon.md](../clarion/v0.1/reviews/pre-restructure/integration-recon.md) |
+| Read accepted architecture decisions | [../clarion/adr/README.md](../clarion/adr/README.md) |
+| Review the planning and review archive | [../implementation/README.md](../implementation/README.md) |
 | Work with Filigree today | Check out the Filigree repository; start with its `CLAUDE.md` and `filigree --help`. |
 | Work with Wardline today | Check out the Wardline repository; start with `docs/spec/`. |
diff --git a/docs/suite/glossary.md b/docs/suite/glossary.md
index 3e43de4e..97ea4f6f 100644
--- a/docs/suite/glossary.md
+++ b/docs/suite/glossary.md
@@ -15,7 +15,7 @@ This file is a **design-review artifact**, not infrastructure. Nothing imports i
 - Authoring an ADR that introduces or renames a cross-product-visible field name
 - Reviewing a wire-format change that adds a new top-level key
 - Onboarding to a Loom product after working on another, to surface vocabulary surprises
-- Triaging a bug whose framing depends on what a word means (the trigger that produced this glossary was exactly such a triage — see [skeleton-audit](../superpowers/handoffs/2026-05-03-skeleton-audit.md))
+- Triaging a bug whose framing depends on what a word means (the trigger that produced this glossary was exactly such a triage — see [skeleton-audit](../implementation/handoffs/2026-05-03-skeleton-audit.md))
 
 **Update this glossary when**:
 
@@ -56,7 +56,7 @@ A vocabulary verdict is part of ADR-acceptance evidence, not a courtesy. Three o
 | `rule_id` | Clarion + Wardline → Filigree | Namespaced prefix per emitter: `CLA-PY-*`, `CLA-INFRA-*`, `CLA-FACT-*`, `CLA-SEC-*`, `WLN-*`. Filigree stores byte-for-byte; round-trip preserved. | [ADR-017](../clarion/adr/ADR-017-severity-and-dedup.md), [ADR-022](../clarion/adr/ADR-022-core-plugin-ontology.md) — namespacing convention + grammar enforcement at the Clarion-plugin boundary |
 | `finding` (wire shape) | Clarion + Wardline → Filigree | Cross-product unified record type. Field ownership documented; extension via `metadata` slot (top-level keys outside the enumerated set are silently dropped). | [ADR-004](../clarion/adr/ADR-004-finding-exchange-format.md) — full wire schema with explicit ownership |
 
-### Renamed clashes (resolved by ADR-024 — see [skeleton-audit](../superpowers/handoffs/2026-05-03-skeleton-audit.md))
+### Renamed clashes (resolved by ADR-024 — see [skeleton-audit](../implementation/handoffs/2026-05-03-skeleton-audit.md))
 
 These entries record the resolution per the `renamed` verdict (see ADR-acceptance rule above). Each row names the pre-rename collision and the post-rename Clarion field name; Filigree's vocabulary is unchanged.
 
diff --git a/docs/suite/loom.md b/docs/suite/loom.md
index 9dc35db1..de0bede3 100644
--- a/docs/suite/loom.md
+++ b/docs/suite/loom.md
@@ -62,11 +62,11 @@ A "standalone mode" that works only because an invisible sibling is still import
 - **Clarion** builds its catalog whether Wardline is present or not. Wardline's annotations *enrich* Clarion's entity metadata with trust-tier and policy-semantic information, but Clarion's structural truth is independent of Wardline's policy truth.
 - **Shuttle**, if built, would execute changes whether any sibling is present. Sibling tools enrich its telemetry (which Filigree ticket? which Clarion entity? which Wardline policy?) but are never required for a change to apply or roll back.
 
-### v0.1 asterisks
+### v1.0 asterisks
 
-The v0.1 suite does not pass the expanded failure test cleanly. Two specific couplings are named here so they cannot drift unnoticed:
+The v1.0 suite does not pass the expanded failure test cleanly. Two specific couplings are named here so they cannot drift unnoticed:
 
-- **Wardline→Filigree findings are pipeline-coupled through Clarion in v0.1.** Wardline's SARIF output reaches Filigree only via Clarion's `clarion sarif import` translator. This violates pipeline composability for the (Wardline, Filigree) pair. *Retirement condition*: Wardline gains a native Filigree emitter (see Clarion's ADR-015), at which point Clarion's SARIF translator retires and the pair composes directly. The asterisk ships with v0.1 and retires in v0.2.
+- **Wardline→Filigree findings are pipeline-coupled through Clarion in v1.0.** Wardline's SARIF output reaches Filigree only via Clarion's `clarion sarif import` translator. This violates pipeline composability for the (Wardline, Filigree) pair. *Retirement condition* (mechanism updated 2026-05-29): the generic Wardline rebuild ships a **native Filigree emitter** (Wardline-side, per the 2026-05-29 integration brief and Clarion's ADR-015 Revision 2), at which point the pair composes directly and Clarion drops off the transport path — its `clarion sarif import` translator stays as the general-purpose SARIF path for other tools; only its Wardline-bridge role retires. The asterisk is **kept live** until that emitter ships and (Wardline, Filigree) composition is verified with Clarion absent — agreement to the direction is not retirement. Tracked under `release:1.1`.
 - **Clarion's Python plugin imports `wardline.core.registry.REGISTRY` at startup.** This is initialization coupling scoped to the Wardline-aware plugin specifically, not to Clarion as a product — Clarion's core and any non-Wardline-aware plugins do not depend on Wardline being importable. The coupling is named so it does not slip unexamined into a future general-purpose plugin. If a future plugin introduces similar initialization coupling without a clear "this plugin is specifically about Wardline" justification, it violates this rule.
 
 Asterisks are acceptable only with a written retirement condition and an honest statement of which failure-test mode is being temporarily violated. A "we'll fix it later" without a test-mode citation is not an asterisk; it is the stealth-monolith failure mode wearing different clothes.
@@ -84,7 +84,14 @@ Because the strongest pressure on this charter comes from "wouldn't it be easier
 - **A central store or database.** Each product owns its data locally. No shared SQLite/Postgres/object-store sits under the suite.
 - **A system of record for any cross-product state.** Finding lifecycle lives in Filigree. Entity identity lives in Clarion. Policy baselines live in Wardline. Execution provenance (if Shuttle ships) lives in Shuttle. Loom does not own or mirror these.
 - **An identity reconciliation service.** When cross-scheme translation is needed — e.g. Wardline qualname → Clarion entity ID — the product that *cares* does the translation, because that product is the one whose authority needs it. Clarion translates qualnames because Clarion owns the catalog that makes them meaningful. There is no neutral "Loom identity oracle."
-- **A capability negotiation bus.** Products probe each other directly via their own surfaces (HTTP endpoints, MCP tools, CLI flags). Version skew is handled bilaterally, not through a Loom-level registry.
+- **A capability negotiation bus.** Products probe each other directly via
+  their own surfaces (HTTP endpoints, MCP tools, CLI flags). Version skew is
+  handled bilaterally, not through a Loom-level registry. Clarion's HTTP read
+  API is one such bilateral surface; its operator trust model is documented in
+  [`docs/operator/clarion-http-read-api.md`](../operator/clarion-http-read-api.md):
+  the HTTP surface is unauthenticated, loopback-only by default, and requires an
+  authenticated reverse proxy or equivalent control before any non-loopback
+  bind.
 
 The test for any proposed addition: if the proposal introduces something that would need to be *running* or *present* for the suite to work, it violates federation. Integration protocols, schemas, and narrow contracts are fine. Shared infrastructure that sibling products *depend on* is not.
 
@@ -115,7 +122,7 @@ Federation does not require uniform vocabulary, but it does require that the sam
 
 | Product | Status |
 |---|---|
-| Clarion | Designed; implementation not yet started; first-customer target is elspeth (~425k LOC Python) |
+| Clarion | Walking skeleton tagged `v0.1-sprint-1`; v0.1 build in flight against the published design; first-customer target is elspeth (~425k LOC Python) |
 | Filigree | Built; in active use |
 | Wardline | Built; in active commit-cadence use |
 | Shuttle | Proposed; not in flight; separate design effort when prioritised |
diff --git a/docs/superpowers/plans/2026-05-29-clarion-agent-orientation.md b/docs/superpowers/plans/2026-05-29-clarion-agent-orientation.md
new file mode 100644
index 00000000..b84b92c9
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-29-clarion-agent-orientation.md
@@ -0,0 +1,2288 @@
+# Clarion Agent Orientation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give Clarion "Filigree-parity" agent orientation — install a bundled `clarion-workflow` skill into a project, merge a SessionStart hook, serve a fail-soft project snapshot via `clarion hook session-start`, and add MCP `instructions` + `resources` (`clarion://context`) + a `clarion-workflow` prompt — so a consult-mode agent self-orients the moment it lands.
+
+**Architecture:** A single embedded `SKILL.md` (already committed at `crates/clarion-cli/assets/skills/clarion-workflow/SKILL.md`) is compiled into the `clarion` binary with `include_str!`. New `install` flags (`--skills`, `--hooks`, `--all`) copy that pack atomically (temp-stage→rename) and merge a SessionStart hook into `.claude/settings.json` without clobbering existing keys. A new `clarion hook session-start` subcommand reads `.clarion/clarion.db` and prints a project snapshot; the snapshot logic is factored into one reusable function (`project_snapshot`) homed in `clarion-mcp`, which the MCP `clarion://context` resource also calls. The MCP `initialize` result gains static `instructions` and `prompts`+`resources` capabilities.
+
+**Tech Stack:** Rust (clap, anyhow, serde_json, rusqlite, blake3, time), hand-rolled JSON-RPC MCP server (no rmcp), SQLite via `clarion-storage` `ReaderPool`, bash e2e harness.
+
+---
+
+## Decision Points
+
+**(a) `include_str!` vs `include_dir`.** Use **`include_str!`** (one `const &str` per file). The pack is a single `SKILL.md` today; `include_str!` matches the existing convention (`crates/clarion-storage/src/schema.rs:20` embeds a migration `.sql` the same way), adds **zero new dependencies**, and stays clear of `cargo deny check`. Tradeoff: a future `references/` pack means adding one `const` per file plus one `(rel_path, contents)` tuple to a static slice — acceptable for a small, slowly-changing pack. We design the copier around a `&[(&str, &str)]` slice of `(relative_path, contents)` so growing the pack is a data change, not a logic change.
+
+**(b) Snapshot staleness — one bounded algorithm.** Order: (1) db missing → `db_present: false`, nudge "run `clarion analyze`"; (2) zero rows in `runs` with a non-null `completed_at` → `staleness: never_analyzed`, nudge; (3) otherwise take the latest run `completed_at`, parse it, and compare against the filesystem mtime of each **distinct `entities.source_file_path`** (the files Clarion actually ingested), short-circuiting on the first source file whose mtime is newer than the run → `staleness: stale`; if none are newer → `staleness: fresh`. Any FS/parse/IO error inside the staleness check degrades to `staleness: unknown` (never an error — the hook is fail-soft, always exit 0). Bounded by indexed-file count; respects exactly what was ingested. Tradeoff: a *new* source file not yet ingested won't be detected as drift (it has no `source_file_path` row) — acceptable, and the "run analyze" nudge on `never_analyzed`/`stale` covers the common case.
+
+**(c) Install flag semantics (resolved ambiguity).** Today **bare `clarion install` refuses if `.clarion/` exists**. So `--skills`/`--hooks` must NOT imply `.clarion/` init — they'd fail on every already-installed project (the common case for adding skills later). Resolution:
+- **bare `clarion install`** = `.clarion/` init only (today's behavior, refuses-if-exists). All existing `crates/clarion-cli/tests/install.rs` tests pass unmodified.
+- **`--skills`** = copy the skill pack (independent component; does NOT init `.clarion/`).
+- **`--hooks`** = merge the SessionStart hook (independent component; does NOT init `.clarion/`).
+- **`--all`** = init + `--skills` + `--hooks`.
+- Flags compose: `--skills --hooks` does both, no init. When any component flag is present, the bare init runs only if `--all` is set.
+
+**(d) Snapshot function signature.** `pub fn project_snapshot(conn: &rusqlite::Connection, project_root: &Path) -> ProjectSnapshot` (infallible — folds errors into the snapshot's `staleness`/counts). Homed in **`clarion-mcp`** (`crates/clarion-mcp/src/snapshot.rs`): the CLI already depends on `clarion-mcp`, and the MCP `clarion://context` resource lives right next to it. Both callers have a `&Connection` and a `project_root` (the hook opens a read-only `Connection`; MCP runs it inside `readers.with_reader(move |conn| ...)` with `project_root` cloned into the `'static` closure). `ProjectSnapshot` is owned `Send + 'static`.
+
+**(e) Dogfood product gaps — DOCUMENT, do not fix here.** Two real gaps surfaced during dogfooding: `find_entity` has no `kind` filter, and there is no module→subsystem reverse lookup. The committed `SKILL.md` already documents both (lines 73–75). For this slice: **file each as a child of Filigree epic `clarion-8fe3060d4c`** (see "Filigree bookkeeping" task), no fix-tasks. Expanding the MCP tool surface is out of scope.
+
+**(f) MCP prompt is the lowest-value piece (optional).** `prompts/list` + `prompts/get` for `clarion-workflow` returns the *same* `SKILL.md` text the installed skill already provides, so it duplicates the on-disk skill. It is included for MCP-client completeness (clients that surface prompts but not skills) but is the first thing to cut under time pressure. Implement it last (Phase 5 Task 5.5) and treat it as droppable.
+
+---
+
+## File Structure
+
+| File | Create/Modify | Single responsibility |
+|------|---------------|-----------------------|
+| `crates/clarion-cli/assets/skills/clarion-workflow/SKILL.md` | Exists (committed) | The bundled skill text. Source of truth for both the installed pack and the MCP prompt. |
+| `crates/clarion-cli/src/skill_pack.rs` | Create | Embeds the pack via `include_str!`, exposes `SKILL_PACK: &[(&str, &str)]`, `pack_fingerprint()`, and `install_skill_pack(dest_root)` (atomic, fingerprint-aware copy into both `.claude/skills/clarion-workflow/` and `.agents/skills/clarion-workflow/`). |
+| `crates/clarion-cli/src/install.rs` | Modify (`run`, add `InstallComponents`) | Orchestrates init + skills + hooks per the resolved flag semantics. |
+| `crates/clarion-cli/src/hooks_settings.rs` | Create | Pure `.claude/settings.json` SessionStart-hook merge logic (parse → add-if-absent → serialize) + the file-level `install_session_start_hook(dest_root)`. |
+| `crates/clarion-cli/src/hook.rs` | Create | `clarion hook session-start` handler: re-sync skill on drift, open read-only db `Connection`, call `project_snapshot`, print a snapshot + nudge to stdout. Always returns `Ok(())` (fail-soft). |
+| `crates/clarion-cli/src/cli.rs` | Modify (`Install` variant ~14, add `Hook`) | CLI surface: new install flags + `Hook { SessionStart }` subcommand. |
+| `crates/clarion-cli/src/main.rs` | Modify (dispatch ~28) | Wire `Install` flags and `Hook` into the dispatch match. |
+| `crates/clarion-cli/src/serve.rs` | Modify (`run_mcp_stdio` ~107) | Pass `project_root` to MCP state (already passed) — no change needed beyond confirming; the resource reads via `readers`. |
+| `crates/clarion-mcp/src/snapshot.rs` | Create | `ProjectSnapshot` struct + `project_snapshot(conn, project_root)` shared function. |
+| `crates/clarion-mcp/src/lib.rs` | Modify (`initialize_result` ~2059, `ServerState::handle_json_rpc` ~255, add `mod snapshot`, embed `SKILL.md`) | `instructions` + `prompts`/`resources` capabilities; new RPC arms for `prompts/list|get`, `resources/list|read`. |
+| `crates/clarion-cli/tests/skills.rs` | Create | Integration tests for `install --skills`, `--hooks`, `--all` flag semantics and idempotency. |
+| `crates/clarion-cli/tests/hook.rs` | Create | Integration tests for `clarion hook session-start` (fail-soft, snapshot output). |
+| `tests/e2e/sprint_2_mcp_surface.sh` | Modify (assertions after line 379) | Assert `initialize` `instructions` field and a `resources/read` of `clarion://context`. |
+
+---
+
+## Preflight — verify before Task 1.1 (fix inline if any differ)
+
+The plan assumes the crate facts below. Confirm each against the real files first; if one differs, adjust the citing task before writing its code. Each is a hard compile blocker if wrong, so catch them up front rather than mid-task.
+
+- **`clarion-cli` deps:** `skill_pack.rs` (Task 1.1) uses `blake3`; `skill_pack.rs`/`install.rs` use `anyhow`. Confirm both are in `crates/clarion-cli/Cargo.toml` `[dependencies]`. If `blake3` is absent, add `blake3.workspace = true` (the workspace pin already exists — it's a `clarion-mcp` dep) and `git add` the Cargo.toml with Task 1.1.
+- **`clarion-cli` → `clarion-mcp` dependency:** `hook.rs` (Task 3.2) imports `clarion_mcp::snapshot::*`. Confirm `crates/clarion-cli/Cargo.toml` depends on `clarion-mcp` (it should — `serve.rs` uses `clarion_mcp::ServerState`). If absent, add it with Task 3.2.
+- **`clarion-cli` dev-deps:** `tests/skills.rs` / `tests/hook.rs` use `assert_cmd` + `tempfile`. Confirm both are `[dev-dependencies]` (the existing `tests/install.rs` uses them; if it does, they're present).
+- **`ServerState` shape (Phase 5):** confirm the constructor is `ServerState::new(project_root: PathBuf, readers: ReaderPool)` and the struct has fields `project_root` + `readers`, and that `self.readers.with_reader(move |conn| Ok(..)).await` returns `Result<T>`. If the names/signature differ, adjust Task 5.2's `context_snapshot_json` and the Phase-5 tests' `ServerState::new(...)` calls to match. (Recon: serve.rs builds `ServerState::new(...)` then `.with_summary_llm(..)`/`.with_filigree_client(..)`.)
+- **`runs.completed_at` format:** `parse_iso8601_to_systemtime` (Task 2.1) parses with `Rfc3339`. Confirm the column is RFC3339 (e.g. `2026-05-29T12:00:00.000Z`). If it's a space-separated SQLite form (`2026-05-29 12:00:00`), swap to a matching `time` `format_description!` — and update the Phase-2 test fixtures to the real format.
+
+---
+
+## PHASE 1 — Embedding + `clarion install --skills`
+
+Atomic, fingerprint-aware copy of the bundled skill pack. Independently testable: produces the two on-disk skill copies.
+
+### Task 1.1: Embed the skill pack and compute a fingerprint
+
+**Files:**
+- Create: `crates/clarion-cli/src/skill_pack.rs`
+- Modify: `crates/clarion-cli/src/main.rs` (add `mod skill_pack;`)
+- Test: inline `#[cfg(test)]` in `crates/clarion-cli/src/skill_pack.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Add to the bottom of the new file `crates/clarion-cli/src/skill_pack.rs`:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::{SKILL_PACK, pack_fingerprint};
+
+    #[test]
+    fn pack_contains_skill_md_with_frontmatter() {
+        let (rel, contents) = SKILL_PACK
+            .iter()
+            .find(|(rel, _)| *rel == "SKILL.md")
+            .expect("SKILL.md present in pack");
+        assert_eq!(*rel, "SKILL.md");
+        assert!(
+            contents.contains("name: clarion-workflow"),
+            "SKILL.md is missing its frontmatter name"
+        );
+    }
+
+    #[test]
+    fn fingerprint_is_stable_and_64_hex_chars() {
+        let fp1 = pack_fingerprint();
+        let fp2 = pack_fingerprint();
+        assert_eq!(fp1, fp2, "fingerprint must be deterministic");
+        assert_eq!(fp1.len(), 64, "blake3 hex digest is 64 chars");
+        assert!(fp1.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli skill_pack`
+Expected: FAIL — `skill_pack.rs` does not yet define `SKILL_PACK`/`pack_fingerprint` (compile error: unresolved import / module not found until `mod skill_pack;` and the items exist).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Top of `crates/clarion-cli/src/skill_pack.rs`:
+
+```rust
+//! Embedded `clarion-workflow` skill pack and its on-disk installer.
+//!
+//! The pack is compiled into the binary with `include_str!` (matching the
+//! `include_str!` migration-embedding convention in
+//! `clarion-storage/src/schema.rs`). Each entry is `(relative_path, contents)`;
+//! growing the pack with a `references/` directory is a data change here, not a
+//! logic change. The fingerprint over the pack bytes drives drift-aware
+//! re-copy (Phase 3 hook resync + `--skills` idempotency).
+
+/// `(relative_path, contents)` for every file in the bundled skill pack.
+pub const SKILL_PACK: &[(&str, &str)] = &[(
+    "SKILL.md",
+    include_str!("../assets/skills/clarion-workflow/SKILL.md"),
+)];
+
+/// The on-disk subdirectory name the pack installs into.
+pub const PACK_DIR_NAME: &str = "clarion-workflow";
+
+/// Deterministic blake3 hex digest over the pack's `(rel_path, contents)`
+/// entries. Order-stable because `SKILL_PACK` is a fixed slice. Used as the
+/// drift sentinel: a `.fingerprint` file written next to the installed pack
+/// records the version on disk.
+#[must_use]
+pub fn pack_fingerprint() -> String {
+    let mut hasher = blake3::Hasher::new();
+    for (rel, contents) in SKILL_PACK {
+        hasher.update(rel.as_bytes());
+        hasher.update(&[0u8]);
+        hasher.update(contents.as_bytes());
+        hasher.update(&[0u8]);
+    }
+    hasher.finalize().to_hex().to_string()
+}
+```
+
+Add to `crates/clarion-cli/src/main.rs` after `mod secret_scan;` (keep modules alphabetical-ish; placement is cosmetic):
+
+```rust
+mod skill_pack;
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli skill_pack`
+Expected: PASS (both tests green).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/skill_pack.rs crates/clarion-cli/src/main.rs
+git commit -m "feat(cli): embed clarion-workflow skill pack with blake3 fingerprint"
+```
+
+### Task 1.2: Atomic, fingerprint-aware pack installer
+
+**Files:**
+- Modify: `crates/clarion-cli/src/skill_pack.rs` (add `install_skill_pack`)
+- Test: inline `#[cfg(test)]` in `crates/clarion-cli/src/skill_pack.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Add these tests inside the existing `mod tests` in `crates/clarion-cli/src/skill_pack.rs`:
+
+```rust
+#[test]
+fn install_writes_pack_into_both_skill_roots() {
+    use super::install_skill_pack;
+    let dir = tempfile::tempdir().unwrap();
+    let report = install_skill_pack(dir.path()).expect("install ok");
+    assert!(report.copied, "first install should copy");
+
+    for root in [".claude/skills", ".agents/skills"] {
+        let skill = dir
+            .path()
+            .join(root)
+            .join("clarion-workflow")
+            .join("SKILL.md");
+        assert!(skill.exists(), "missing {}", skill.display());
+        let body = std::fs::read_to_string(&skill).unwrap();
+        assert!(body.contains("name: clarion-workflow"));
+    }
+}
+
+#[test]
+fn install_is_idempotent_when_fingerprint_matches() {
+    use super::install_skill_pack;
+    let dir = tempfile::tempdir().unwrap();
+    let first = install_skill_pack(dir.path()).unwrap();
+    assert!(first.copied);
+    let second = install_skill_pack(dir.path()).unwrap();
+    assert!(!second.copied, "second install should be a no-op on match");
+}
+
+#[test]
+fn install_recopies_when_installed_pack_drifted() {
+    use super::install_skill_pack;
+    let dir = tempfile::tempdir().unwrap();
+    install_skill_pack(dir.path()).unwrap();
+    // Corrupt one installed copy + its fingerprint to simulate drift.
+    let skill = dir
+        .path()
+        .join(".claude/skills/clarion-workflow/SKILL.md");
+    std::fs::write(&skill, "STALE").unwrap();
+    let fp = dir
+        .path()
+        .join(".claude/skills/clarion-workflow/.fingerprint");
+    std::fs::write(&fp, "deadbeef").unwrap();
+
+    let report = install_skill_pack(dir.path()).unwrap();
+    assert!(report.copied, "drift should trigger re-copy");
+    let body = std::fs::read_to_string(&skill).unwrap();
+    assert!(body.contains("name: clarion-workflow"), "drift not repaired");
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli skill_pack`
+Expected: FAIL — `install_skill_pack` and its `SkillInstallReport` are not defined (compile error).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Add to `crates/clarion-cli/src/skill_pack.rs` (above the `#[cfg(test)]` block):
+
+```rust
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, Result};
+
+/// The two skill roots Clarion installs into, relative to the project root.
+/// `.claude/skills/` is read by Claude Code; `.agents/skills/` is the
+/// tool-agnostic convention so non-Claude agent harnesses find it too.
+const SKILL_ROOTS: &[&str] = &[".claude/skills", ".agents/skills"];
+
+const FINGERPRINT_FILE: &str = ".fingerprint";
+
+/// Outcome of an [`install_skill_pack`] call.
+#[derive(Debug, Clone, Copy)]
+pub struct SkillInstallReport {
+    /// True if the pack bytes were (re)written this call; false if every
+    /// destination already matched the embedded fingerprint.
+    pub copied: bool,
+}
+
+/// Install (or re-sync on drift) the embedded skill pack into both skill roots
+/// under `project_root`, idempotently.
+///
+/// For each root, the pack lands at `<root>/clarion-workflow/`. A
+/// `.fingerprint` file recording [`pack_fingerprint`] is written alongside the
+/// pack files. If every root's `.fingerprint` already equals the embedded
+/// fingerprint, the call is a no-op (`copied: false`).
+///
+/// Writes are atomic: each pack is staged into a sibling temp directory in the
+/// same skill root (so `rename` stays on one filesystem), then `rename`d over
+/// the destination.
+///
+/// # Errors
+///
+/// Returns an error if any directory create, temp write, or rename fails.
+pub fn install_skill_pack(project_root: &Path) -> Result<SkillInstallReport> {
+    let fingerprint = pack_fingerprint();
+    let mut copied = false;
+    for root_rel in SKILL_ROOTS {
+        let root = project_root.join(root_rel);
+        let dest = root.join(PACK_DIR_NAME);
+        if installed_fingerprint(&dest).as_deref() == Some(fingerprint.as_str()) {
+            continue;
+        }
+        stage_and_swap(&root, &dest, &fingerprint)
+            .with_context(|| format!("install skill pack into {}", dest.display()))?;
+        copied = true;
+    }
+    Ok(SkillInstallReport { copied })
+}
+
+fn installed_fingerprint(dest: &Path) -> Option<String> {
+    fs::read_to_string(dest.join(FINGERPRINT_FILE))
+        .ok()
+        .map(|s| s.trim().to_owned())
+}
+
+fn stage_and_swap(root: &Path, dest: &Path, fingerprint: &str) -> Result<()> {
+    fs::create_dir_all(root).with_context(|| format!("mkdir {}", root.display()))?;
+    // Stage in a sibling temp dir so the final rename is same-filesystem.
+    let staging = root.join(format!(".clarion-workflow.tmp-{}", std::process::id()));
+    if staging.exists() {
+        fs::remove_dir_all(&staging)
+            .with_context(|| format!("clear stale staging {}", staging.display()))?;
+    }
+    fs::create_dir_all(&staging).with_context(|| format!("mkdir {}", staging.display()))?;
+    for (rel, contents) in SKILL_PACK {
+        let target = staging.join(rel);
+        if let Some(parent) = target.parent() {
+            fs::create_dir_all(parent)
+                .with_context(|| format!("mkdir {}", parent.display()))?;
+        }
+        fs::write(&target, contents).with_context(|| format!("write {}", target.display()))?;
+    }
+    fs::write(staging.join(FINGERPRINT_FILE), fingerprint)
+        .with_context(|| format!("write fingerprint in {}", staging.display()))?;
+    // Remove any prior install, then move the staged pack into place.
+    if dest.exists() {
+        fs::remove_dir_all(dest).with_context(|| format!("remove old {}", dest.display()))?;
+    }
+    fs::rename(&staging, dest)
+        .with_context(|| format!("rename {} -> {}", staging.display(), dest.display()))?;
+    Ok(())
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli skill_pack`
+Expected: PASS (all five tests green).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/skill_pack.rs
+git commit -m "feat(cli): atomic fingerprint-aware skill-pack installer"
+```
+
+### Task 1.3: `clarion install --skills` CLI flag
+
+**Files:**
+- Modify: `crates/clarion-cli/src/cli.rs` (`Install` variant ~14-23)
+- Modify: `crates/clarion-cli/src/install.rs` (`run` signature + `InstallComponents`)
+- Modify: `crates/clarion-cli/src/main.rs` (dispatch ~29)
+- Test: `crates/clarion-cli/tests/skills.rs` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/clarion-cli/tests/skills.rs`:
+
+```rust
+//! `clarion install --skills/--hooks/--all` integration tests.
+
+use std::fs;
+
+use assert_cmd::Command;
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+#[test]
+fn install_skills_writes_pack_without_initialising_clarion_dir() {
+    let dir = tempfile::tempdir().unwrap();
+    clarion_bin()
+        .args(["install", "--skills", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    assert!(
+        dir.path()
+            .join(".claude/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "skill not installed under .claude"
+    );
+    assert!(
+        dir.path()
+            .join(".agents/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "skill not installed under .agents"
+    );
+    // --skills MUST NOT init .clarion/.
+    assert!(
+        !dir.path().join(".clarion").exists(),
+        "--skills should not create .clarion/"
+    );
+}
+
+#[test]
+fn install_skills_is_idempotent() {
+    let dir = tempfile::tempdir().unwrap();
+    for _ in 0..2 {
+        clarion_bin()
+            .args(["install", "--skills", "--path"])
+            .arg(dir.path())
+            .assert()
+            .success();
+    }
+    let body = fs::read_to_string(
+        dir.path().join(".claude/skills/clarion-workflow/SKILL.md"),
+    )
+    .unwrap();
+    assert!(body.contains("name: clarion-workflow"));
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli --test skills`
+Expected: FAIL — `--skills` is an unknown argument (clap errors with a nonzero exit; `assert().success()` fails).
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `crates/clarion-cli/src/cli.rs`, replace the `Install` variant (lines ~14-23) with:
+
+```rust
+    /// Initialise .clarion/ and/or install agent-orientation assets.
+    ///
+    /// Bare `clarion install` initialises .clarion/ only (refuses if it
+    /// already exists). `--skills` and `--hooks` install the orientation
+    /// assets and do NOT initialise .clarion/. `--all` does init + skills +
+    /// hooks.
+    Install {
+        /// Overwrite an existing .clarion/ directory.
+        #[arg(long)]
+        force: bool,
+
+        /// Directory to install into (default: current directory).
+        #[arg(long, default_value = ".")]
+        path: PathBuf,
+
+        /// Install the bundled clarion-workflow skill pack into
+        /// .claude/skills/ and .agents/skills/.
+        #[arg(long)]
+        skills: bool,
+
+        /// Merge a SessionStart hook into .claude/settings.json.
+        #[arg(long)]
+        hooks: bool,
+
+        /// Do everything: .clarion/ init + --skills + --hooks.
+        #[arg(long)]
+        all: bool,
+    },
+```
+
+In `crates/clarion-cli/src/install.rs`, replace the `pub fn run(path: &Path, force: bool)` signature and body opening. First add this struct + helper above `run` (after the `const` stubs, before the `/// Run the install subcommand` doc comment):
+
+```rust
+/// Which install components to perform. Resolved from CLI flags in
+/// [`InstallComponents::from_flags`] per the flag semantics in the agent-
+/// orientation plan: bare install = init only; `--skills`/`--hooks` are
+/// independent and do NOT init; `--all` = init + skills + hooks.
+#[derive(Debug, Clone, Copy)]
+pub struct InstallComponents {
+    pub init_clarion: bool,
+    pub skills: bool,
+    pub hooks: bool,
+}
+
+impl InstallComponents {
+    #[must_use]
+    pub fn from_flags(skills: bool, hooks: bool, all: bool) -> Self {
+        if all {
+            return Self {
+                init_clarion: true,
+                skills: true,
+                hooks: true,
+            };
+        }
+        let any_component = skills || hooks;
+        Self {
+            // Bare install (no component flags) keeps today's behavior: init.
+            init_clarion: !any_component,
+            skills,
+            hooks,
+        }
+    }
+}
+```
+
+Now change `run` to take components. Replace:
+
+```rust
+pub fn run(path: &Path, force: bool) -> Result<()> {
+    if !path.exists() {
+```
+
+with:
+
+```rust
+pub fn run(path: &Path, force: bool, components: InstallComponents) -> Result<()> {
+    if !path.exists() {
+```
+
+Then, before the existing `let project_root = path.canonicalize()...` block, the canonicalization is still needed by all branches. Keep it. After the `let project_root = ...` line, wrap the `.clarion/` work in the `init_clarion` guard. Replace the block from `let clarion_dir = project_root.join(".clarion");` down through the final `println!("Initialised {}", clarion_dir.display());\n    Ok(())\n}` with:
+
+```rust
+    if components.init_clarion {
+        let clarion_dir = project_root.join(".clarion");
+        if clarion_dir.exists() {
+            if !force {
+                bail!(
+                    ".clarion/ already exists at {}. Delete it or pass --force to overwrite it.",
+                    clarion_dir.display()
+                );
+            }
+            if !clarion_dir.is_dir() {
+                bail!(
+                    "--force can only overwrite an existing .clarion/ directory; \
+                     found non-directory at {}.",
+                    clarion_dir.display()
+                );
+            }
+            fs::remove_dir_all(&clarion_dir)
+                .with_context(|| format!("remove existing {}", clarion_dir.display()))?;
+        }
+
+        fs::create_dir_all(&clarion_dir)
+            .with_context(|| format!("mkdir {}", clarion_dir.display()))?;
+
+        if let Err(err) = populate_after_mkdir(&clarion_dir, &project_root) {
+            if let Err(cleanup_err) = fs::remove_dir_all(&clarion_dir) {
+                tracing::warn!(
+                    clarion_dir = %clarion_dir.display(),
+                    error = %cleanup_err,
+                    "install failed and cleanup of partial .clarion/ also failed; \
+                     manual rm -rf may be required"
+                );
+            }
+            return Err(err);
+        }
+
+        tracing::info!(
+            clarion_dir = %clarion_dir.display(),
+            "clarion install complete"
+        );
+        println!("Initialised {}", clarion_dir.display());
+    }
+
+    if components.skills {
+        let report = crate::skill_pack::install_skill_pack(&project_root)
+            .context("install clarion-workflow skill pack")?;
+        if report.copied {
+            println!(
+                "Installed clarion-workflow skill into {}/.claude/skills and {}/.agents/skills",
+                project_root.display(),
+                project_root.display()
+            );
+        } else {
+            println!("clarion-workflow skill already up to date");
+        }
+    }
+
+    // --hooks wired in Phase 4.
+
+    Ok(())
+}
+```
+
+In `crates/clarion-cli/src/main.rs`, change the `Install` match arm (line ~29) from:
+
+```rust
+        cli::Command::Install { force, path } => install::run(&path, force),
+```
+
+to:
+
+```rust
+        cli::Command::Install {
+            force,
+            path,
+            skills,
+            hooks,
+            all,
+        } => install::run(
+            &path,
+            force,
+            install::InstallComponents::from_flags(skills, hooks, all),
+        ),
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli --test skills`
+Expected: PASS. Also run the existing install tests to prove bare-install behavior is unchanged:
+Run: `cargo nextest run -p clarion-cli --test install`
+Expected: PASS (all existing tests green — `from_flags(false, false, false)` sets `init_clarion: true`).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/cli.rs crates/clarion-cli/src/install.rs crates/clarion-cli/src/main.rs crates/clarion-cli/tests/skills.rs
+git commit -m "feat(cli): clarion install --skills installs orientation skill pack"
+```
+
+### Task 1.4: Phase 1 gate
+
+- [ ] **Step 1: Run the full Rust gate for the crate**
+
+Run: `cargo fmt --all -- --check && cargo clippy -p clarion-cli --all-targets --all-features -- -D warnings && cargo nextest run -p clarion-cli`
+Expected: PASS, no warnings.
+
+- [ ] **Step 2: Commit any fmt/clippy fixes (only if the gate changed files)**
+
+```bash
+git add -A
+git commit -m "style(cli): fmt/clippy after skill-pack phase"
+```
+
+---
+
+## PHASE 2 — Shared snapshot module
+
+A pure-ish function over a `&Connection` + `project_root`, unit-tested against a fixture db. Homed in `clarion-mcp`.
+
+### Task 2.1: `ProjectSnapshot` + counts (no staleness yet)
+
+**Files:**
+- Create: `crates/clarion-mcp/src/snapshot.rs`
+- Modify: `crates/clarion-mcp/src/lib.rs` (add `pub mod snapshot;`)
+- Test: inline `#[cfg(test)]` in `crates/clarion-mcp/src/snapshot.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/clarion-mcp/src/snapshot.rs` with this test block at the bottom:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use rusqlite::Connection;
+
+    use clarion_storage::{pragma, schema};
+
+    use super::{Staleness, project_snapshot};
+
+    fn migrated_conn() -> Connection {
+        let mut conn = Connection::open_in_memory().unwrap();
+        pragma::apply_write_pragmas(&conn).unwrap();
+        schema::apply_migrations(&mut conn).unwrap();
+        conn
+    }
+
+    fn insert_entity(conn: &Connection, id: &str, kind: &str, source_file_path: Option<&str>) {
+        conn.execute(
+            "INSERT INTO entities \
+             (id, plugin_id, kind, name, short_name, properties, source_file_path, created_at, updated_at) \
+             VALUES (?1, 'python', ?2, ?3, ?3, '{}', ?4, '2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z')",
+            rusqlite::params![id, kind, id, source_file_path],
+        )
+        .unwrap();
+    }
+
+    #[test]
+    fn counts_entities_subsystems_and_findings() {
+        let conn = migrated_conn();
+        insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+        insert_entity(&conn, "python:function:a.f", "function", Some("a.py"));
+        insert_entity(&conn, "core:subsystem:abc", "subsystem", None);
+        // A run + a finding attached to the module.
+        conn.execute(
+            "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+             VALUES ('run1', '2026-01-01T00:00:00.000Z', '2026-01-02T00:00:00.000Z', '{}', '{}', 'completed')",
+            [],
+        )
+        .unwrap();
+        conn.execute(
+            "INSERT INTO findings \
+             (id, tool, tool_version, run_id, rule_id, kind, severity, entity_id, \
+              related_entities, message, evidence, properties, supports, supported_by, status, created_at, updated_at) \
+             VALUES ('f1','clarion','1.0','run1','R1','defect','WARN','python:module:a', \
+                     '[]','m','{}','{}','[]','[]','open','2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')",
+            [],
+        )
+        .unwrap();
+
+        let snap = project_snapshot(&conn, std::path::Path::new("/nonexistent-root"));
+        assert!(snap.db_present);
+        assert_eq!(snap.entity_count, 3);
+        assert_eq!(snap.subsystem_count, 1);
+        assert_eq!(snap.finding_count, 1);
+        // No source files exist on disk under /nonexistent-root, and there IS a
+        // completed run, so staleness degrades to Unknown (stat failures fold
+        // to Unknown, never an error).
+        assert_eq!(snap.staleness, Staleness::Unknown);
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-mcp snapshot`
+Expected: FAIL — module/items not defined (compile error until `pub mod snapshot;` + the items exist).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Top of `crates/clarion-mcp/src/snapshot.rs`:
+
+```rust
+//! Shared project snapshot: entity/subsystem/finding counts + index staleness.
+//!
+//! One function, two callers: the `clarion hook session-start` subcommand and
+//! the MCP `clarion://context` resource. Infallible by design — every failure
+//! folds into the snapshot (zero counts, `Staleness::Unknown`) so the fail-soft
+//! hook never has to handle an error.
+
+use std::path::Path;
+use std::time::SystemTime;
+
+use rusqlite::Connection;
+use serde::Serialize;
+
+/// Freshness of the `.clarion/` index relative to the source files Clarion
+/// ingested. See the plan's Decision Point (b) for the algorithm.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Staleness {
+    /// No completed analyze run has ever been recorded.
+    NeverAnalyzed,
+    /// At least one ingested source file is newer than the latest run.
+    Stale,
+    /// No ingested source file is newer than the latest run.
+    Fresh,
+    /// Could not determine (stat/parse/IO error) — degrade, don't fail.
+    Unknown,
+}
+
+/// Counts + freshness for one Clarion project, safe to serialize into the MCP
+/// resource or print from the hook.
+#[derive(Debug, Clone, Serialize)]
+pub struct ProjectSnapshot {
+    pub db_present: bool,
+    pub entity_count: i64,
+    pub subsystem_count: i64,
+    pub finding_count: i64,
+    pub staleness: Staleness,
+    /// Latest run `completed_at` (ISO-8601) if any, else `None`.
+    pub last_analyzed_at: Option<String>,
+}
+
+/// Build a snapshot from an already-open migrated `Connection`.
+///
+/// `db_present` is always `true` here (the caller opened the connection); the
+/// `false` case is produced by the caller when the db file is missing.
+#[must_use]
+pub fn project_snapshot(conn: &Connection, project_root: &Path) -> ProjectSnapshot {
+    let entity_count = scalar_count(conn, "SELECT COUNT(*) FROM entities");
+    let subsystem_count = scalar_count(
+        conn,
+        "SELECT COUNT(*) FROM entities WHERE kind = 'subsystem'",
+    );
+    let finding_count = scalar_count(conn, "SELECT COUNT(*) FROM findings");
+
+    let last_analyzed_at = latest_completed_run(conn);
+    let staleness = compute_staleness(conn, project_root, last_analyzed_at.as_deref());
+
+    ProjectSnapshot {
+        db_present: true,
+        entity_count,
+        subsystem_count,
+        finding_count,
+        staleness,
+        last_analyzed_at,
+    }
+}
+
+/// A missing-database snapshot: all zeros, `NeverAnalyzed`, no timestamp.
+#[must_use]
+pub fn missing_db_snapshot() -> ProjectSnapshot {
+    ProjectSnapshot {
+        db_present: false,
+        entity_count: 0,
+        subsystem_count: 0,
+        finding_count: 0,
+        staleness: Staleness::NeverAnalyzed,
+        last_analyzed_at: None,
+    }
+}
+
+fn scalar_count(conn: &Connection, sql: &str) -> i64 {
+    conn.query_row(sql, [], |row| row.get::<_, i64>(0))
+        .unwrap_or(0)
+}
+
+fn latest_completed_run(conn: &Connection) -> Option<String> {
+    conn.query_row(
+        "SELECT completed_at FROM runs \
+         WHERE completed_at IS NOT NULL AND status = 'completed' \
+         ORDER BY completed_at DESC LIMIT 1",
+        [],
+        |row| row.get::<_, String>(0),
+    )
+    .ok()
+}
+
+fn compute_staleness(
+    conn: &Connection,
+    project_root: &Path,
+    last_analyzed_at: Option<&str>,
+) -> Staleness {
+    let Some(run_iso) = last_analyzed_at else {
+        return Staleness::NeverAnalyzed;
+    };
+    let Some(run_time) = parse_iso8601_to_systemtime(run_iso) else {
+        return Staleness::Unknown;
+    };
+
+    // Distinct source files Clarion actually ingested.
+    let mut stmt = match conn.prepare(
+        "SELECT DISTINCT source_file_path FROM entities \
+         WHERE source_file_path IS NOT NULL",
+    ) {
+        Ok(stmt) => stmt,
+        Err(_) => return Staleness::Unknown,
+    };
+    let rows = match stmt.query_map([], |row| row.get::<_, String>(0)) {
+        Ok(rows) => rows,
+        Err(_) => return Staleness::Unknown,
+    };
+
+    let mut saw_any_file = false;
+    for rel in rows.flatten() {
+        let abs = if Path::new(&rel).is_absolute() {
+            std::path::PathBuf::from(&rel)
+        } else {
+            project_root.join(&rel)
+        };
+        match abs.metadata().and_then(|m| m.modified()) {
+            Ok(mtime) => {
+                saw_any_file = true;
+                if mtime > run_time {
+                    return Staleness::Stale;
+                }
+            }
+            Err(_) => return Staleness::Unknown,
+        }
+    }
+    if saw_any_file {
+        Staleness::Fresh
+    } else {
+        // A completed run but no resolvable source files on disk.
+        Staleness::Unknown
+    }
+}
+
+/// Parse a strict `%Y-%m-%dT%H:%M:%S(.fff)Z` UTC timestamp (the format
+/// `strftime('%Y-%m-%dT%H:%M:%fZ','now')` writes into `runs.completed_at`) to a
+/// `SystemTime`. Returns `None` on any deviation.
+fn parse_iso8601_to_systemtime(iso: &str) -> Option<SystemTime> {
+    use time::OffsetDateTime;
+    use time::format_description::well_known::Rfc3339;
+    let odt = OffsetDateTime::parse(iso, &Rfc3339).ok()?;
+    Some(SystemTime::from(odt))
+}
+```
+
+Add to `crates/clarion-mcp/src/lib.rs` near the other `pub mod` lines (top of file, after `pub mod filigree;`):
+
+```rust
+pub mod snapshot;
+```
+
+Confirm `time` is a dependency of `clarion-mcp` (it is — `lib.rs` already `use time::...`). Confirm `serde` is too (it is — `use serde::{Deserialize, Serialize};`).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-mcp snapshot`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/snapshot.rs crates/clarion-mcp/src/lib.rs
+git commit -m "feat(mcp): shared project_snapshot (counts + staleness)"
+```
+
+### Task 2.2: Staleness — fresh vs stale against on-disk source mtimes
+
+**Files:**
+- Modify: none (logic already in 2.1; this task adds the proving tests)
+- Test: inline `#[cfg(test)]` in `crates/clarion-mcp/src/snapshot.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `mod tests` in `crates/clarion-mcp/src/snapshot.rs`:
+
+```rust
+#[test]
+fn never_analyzed_when_no_completed_run() {
+    let conn = migrated_conn();
+    insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+    let snap = project_snapshot(&conn, std::path::Path::new("/tmp"));
+    assert_eq!(snap.staleness, Staleness::NeverAnalyzed);
+    assert!(snap.last_analyzed_at.is_none());
+}
+
+#[test]
+fn fresh_when_all_sources_older_than_run() {
+    let dir = tempfile::tempdir().unwrap();
+    // Create the source file FIRST (old), then record a run AFTER it.
+    let src = dir.path().join("a.py");
+    std::fs::write(&src, "x = 1\n").unwrap();
+
+    let conn = migrated_conn();
+    insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+    conn.execute(
+        "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+         VALUES ('r', '2099-01-01T00:00:00.000Z', '2099-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+        [],
+    )
+    .unwrap();
+
+    let snap = project_snapshot(&conn, dir.path());
+    assert_eq!(snap.staleness, Staleness::Fresh, "{snap:?}");
+    assert_eq!(snap.last_analyzed_at.as_deref(), Some("2099-01-01T00:00:00.000Z"));
+}
+
+#[test]
+fn stale_when_a_source_is_newer_than_run() {
+    let dir = tempfile::tempdir().unwrap();
+    let src = dir.path().join("a.py");
+    std::fs::write(&src, "x = 1\n").unwrap();
+
+    let conn = migrated_conn();
+    insert_entity(&conn, "python:module:a", "module", Some("a.py"));
+    // Run completed in the distant past; the on-disk file is newer.
+    conn.execute(
+        "INSERT INTO runs (id, started_at, completed_at, config, stats, status) \
+         VALUES ('r', '2000-01-01T00:00:00.000Z', '2000-01-01T00:00:00.000Z', '{}', '{}', 'completed')",
+        [],
+    )
+    .unwrap();
+
+    let snap = project_snapshot(&conn, dir.path());
+    assert_eq!(snap.staleness, Staleness::Stale, "{snap:?}");
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails or passes**
+
+Run: `cargo nextest run -p clarion-mcp snapshot`
+Expected: PASS — the staleness logic from Task 2.1 already satisfies these. (If any fail, the bug is in 2.1's `compute_staleness`; fix it there, do not weaken the test.) This task exists to lock the fresh/stale boundary with explicit fixtures.
+
+- [ ] **Step 3: (no new implementation — logic landed in 2.1)**
+
+Skip; the tests prove the existing implementation.
+
+- [ ] **Step 4: Re-run to confirm green**
+
+Run: `cargo nextest run -p clarion-mcp snapshot`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/snapshot.rs
+git commit -m "test(mcp): lock fresh/stale boundary for project_snapshot"
+```
+
+### Task 2.3: Phase 2 gate
+
+- [ ] **Step 1: Run the crate gate**
+
+Run: `cargo fmt --all -- --check && cargo clippy -p clarion-mcp --all-targets --all-features -- -D warnings && cargo nextest run -p clarion-mcp`
+Expected: PASS, no warnings.
+
+- [ ] **Step 2: Commit fixes if any**
+
+```bash
+git add -A
+git commit -m "style(mcp): fmt/clippy after snapshot module"
+```
+
+---
+
+## PHASE 3 — `clarion hook session-start` subcommand
+
+Fail-soft: always exits 0. Re-syncs the skill on drift, prints the snapshot + nudge.
+
+### Task 3.1: CLI `Hook { SessionStart }` subcommand wired to a no-op handler
+
+**Files:**
+- Modify: `crates/clarion-cli/src/cli.rs` (add `Hook` variant + `HookCommand` enum)
+- Create: `crates/clarion-cli/src/hook.rs` (handler)
+- Modify: `crates/clarion-cli/src/main.rs` (add `mod hook;` + dispatch)
+- Test: `crates/clarion-cli/tests/hook.rs` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/clarion-cli/tests/hook.rs`:
+
+```rust
+//! `clarion hook session-start` integration tests.
+
+use assert_cmd::Command;
+
+fn clarion_bin() -> Command {
+    Command::cargo_bin("clarion").expect("clarion binary")
+}
+
+#[test]
+fn hook_session_start_exits_zero_without_clarion_db() {
+    // Fail-soft: no .clarion/ at all must still exit 0 and nudge.
+    let dir = tempfile::tempdir().unwrap();
+    let assert = clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let out = String::from_utf8(assert.get_output().stdout.clone()).unwrap();
+    assert!(
+        out.contains("clarion analyze"),
+        "missing analyze nudge in: {out}"
+    );
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli --test hook`
+Expected: FAIL — `hook` is an unknown subcommand (clap nonzero exit).
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `crates/clarion-cli/src/cli.rs`, add a new variant to `enum Command` (after `Serve { ... }`):
+
+```rust
+    /// Agent-lifecycle hook entrypoints. Always exit 0 (fail-soft) so a
+    /// misbehaving hook never blocks session start.
+    Hook {
+        #[command(subcommand)]
+        command: HookCommand,
+    },
+```
+
+And add this enum at the bottom of `crates/clarion-cli/src/cli.rs`:
+
+```rust
+#[derive(Subcommand)]
+pub enum HookCommand {
+    /// Print a project snapshot and re-sync the skill pack on drift.
+    SessionStart {
+        /// Project directory containing .clarion/clarion.db.
+        #[arg(long, default_value = ".")]
+        path: PathBuf,
+    },
+}
+```
+
+Create `crates/clarion-cli/src/hook.rs`:
+
+```rust
+//! `clarion hook session-start` — fail-soft session-start orientation.
+//!
+//! Never returns an error to the caller: the SessionStart hook must never
+//! block an agent's session start. All failures degrade to a printed note.
+
+use std::path::Path;
+
+/// Run `clarion hook session-start`. Always returns `Ok(())`.
+pub fn session_start(path: &Path) -> anyhow::Result<()> {
+    println!("Clarion: orientation hook (snapshot wired in Task 3.2).");
+    println!("If briefings look empty, run `clarion analyze {}`.", path.display());
+    Ok(())
+}
+```
+
+In `crates/clarion-cli/src/main.rs`, add `mod hook;` near the other modules, and add the dispatch arm after the `Serve` arm:
+
+```rust
+        cli::Command::Hook { command } => match command {
+            cli::HookCommand::SessionStart { path } => hook::session_start(&path),
+        },
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli --test hook`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/cli.rs crates/clarion-cli/src/hook.rs crates/clarion-cli/src/main.rs crates/clarion-cli/tests/hook.rs
+git commit -m "feat(cli): add fail-soft clarion hook session-start subcommand"
+```
+
+### Task 3.2: Snapshot output + skill resync in the hook
+
+**Files:**
+- Modify: `crates/clarion-cli/src/hook.rs` (full snapshot + resync)
+- Test: `crates/clarion-cli/tests/hook.rs` (add)
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `crates/clarion-cli/tests/hook.rs`:
+
+```rust
+#[test]
+fn hook_session_start_prints_counts_for_installed_project() {
+    let dir = tempfile::tempdir().unwrap();
+    // Initialise .clarion/ (bare install).
+    clarion_bin()
+        .args(["install", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    let assert = clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let out = String::from_utf8(assert.get_output().stdout.clone()).unwrap();
+    // Empty db: 0 entities, never analyzed → nudge present.
+    assert!(out.contains("entities"), "missing entity count line: {out}");
+    assert!(out.contains("clarion analyze"), "missing nudge: {out}");
+}
+
+#[test]
+fn hook_session_start_resyncs_skill_when_present_and_drifted() {
+    let dir = tempfile::tempdir().unwrap();
+    // Install the skill, then corrupt it to simulate drift.
+    clarion_bin()
+        .args(["install", "--skills", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+    let skill = dir
+        .path()
+        .join(".claude/skills/clarion-workflow/SKILL.md");
+    std::fs::write(&skill, "STALE").unwrap();
+
+    clarion_bin()
+        .args(["hook", "session-start", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    let body = std::fs::read_to_string(&skill).unwrap();
+    assert!(
+        body.contains("name: clarion-workflow"),
+        "hook did not repair drifted skill: {body}"
+    );
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli --test hook`
+Expected: FAIL — current stub prints neither counts nor resyncs (the new assertions fail).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Replace the body of `crates/clarion-cli/src/hook.rs` with:
+
+```rust
+//! `clarion hook session-start` — fail-soft session-start orientation.
+//!
+//! Never returns an error to the caller: the SessionStart hook must never
+//! block an agent's session start. All failures degrade to a printed note.
+
+use std::path::Path;
+
+use clarion_mcp::snapshot::{ProjectSnapshot, Staleness, missing_db_snapshot, project_snapshot};
+use rusqlite::{Connection, OpenFlags};
+
+/// Run `clarion hook session-start`. Always returns `Ok(())`.
+pub fn session_start(path: &Path) -> anyhow::Result<()> {
+    // (1) Re-sync the skill pack ONLY if it's already installed and drifted.
+    //     We don't install where absent — that's `clarion install --skills`'s
+    //     job. A drift repair keeps an installed copy honest across upgrades.
+    resync_skill_if_present(path);
+
+    // (2) Snapshot.
+    let snapshot = load_snapshot(path);
+    print_snapshot(path, &snapshot);
+    Ok(())
+}
+
+fn resync_skill_if_present(project_root: &Path) {
+    let installed = project_root
+        .join(".claude/skills/clarion-workflow/SKILL.md")
+        .exists()
+        || project_root
+            .join(".agents/skills/clarion-workflow/SKILL.md")
+            .exists();
+    if !installed {
+        return;
+    }
+    if let Err(err) = crate::skill_pack::install_skill_pack(project_root) {
+        // Fail-soft: log, never propagate.
+        tracing::warn!(error = %err, "clarion-workflow skill resync failed");
+    }
+}
+
+fn load_snapshot(project_root: &Path) -> ProjectSnapshot {
+    let db_path = project_root.join(".clarion").join("clarion.db");
+    if !db_path.exists() {
+        return missing_db_snapshot();
+    }
+    match Connection::open_with_flags(&db_path, OpenFlags::SQLITE_OPEN_READ_ONLY) {
+        Ok(conn) => {
+            let root = project_root
+                .canonicalize()
+                .unwrap_or_else(|_| project_root.to_path_buf());
+            project_snapshot(&conn, &root)
+        }
+        Err(err) => {
+            tracing::warn!(error = %err, "open .clarion/clarion.db read-only failed");
+            missing_db_snapshot()
+        }
+    }
+}
+
+fn print_snapshot(project_root: &Path, snapshot: &ProjectSnapshot) {
+    if !snapshot.db_present {
+        println!(
+            "Clarion: no index at {}/.clarion/clarion.db. \
+             Run `clarion install --path {}` then `clarion analyze {}`.",
+            project_root.display(),
+            project_root.display(),
+            project_root.display()
+        );
+        return;
+    }
+    println!(
+        "Clarion index: {} entities, {} subsystems, {} findings.",
+        snapshot.entity_count, snapshot.subsystem_count, snapshot.finding_count
+    );
+    match snapshot.staleness {
+        Staleness::Fresh => {
+            println!(
+                "Index is fresh (last analyzed {}). Ask Clarion before re-exploring \
+                 the tree; see the clarion-workflow skill.",
+                snapshot.last_analyzed_at.as_deref().unwrap_or("unknown")
+            );
+        }
+        Staleness::Stale => {
+            println!(
+                "Index may be stale: source files changed since the last run. \
+                 Run `clarion analyze {}` to refresh.",
+                project_root.display()
+            );
+        }
+        Staleness::NeverAnalyzed => {
+            println!(
+                "No analysis recorded yet. Run `clarion analyze {}` to build the index.",
+                project_root.display()
+            );
+        }
+        Staleness::Unknown => {
+            println!(
+                "Index freshness unknown. If briefings look empty, run \
+                 `clarion analyze {}`.",
+                project_root.display()
+            );
+        }
+    }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli --test hook`
+Expected: PASS (all three hook tests green). The empty-db case yields `NeverAnalyzed` → prints "clarion analyze".
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/hook.rs crates/clarion-cli/tests/hook.rs
+git commit -m "feat(cli): hook session-start prints snapshot and resyncs skill on drift"
+```
+
+### Task 3.3: Phase 3 gate
+
+- [ ] **Step 1: Run the crate gate**
+
+Run: `cargo fmt --all -- --check && cargo clippy -p clarion-cli --all-targets --all-features -- -D warnings && cargo nextest run -p clarion-cli`
+Expected: PASS, no warnings.
+
+- [ ] **Step 2: Commit fixes if any**
+
+```bash
+git add -A
+git commit -m "style(cli): fmt/clippy after hook subcommand"
+```
+
+---
+
+## PHASE 4 — `clarion install --hooks` (settings.json merge) + `--all`
+
+Merge a SessionStart hook into `.claude/settings.json` without clobbering existing keys.
+
+### Task 4.1: Pure settings.json merge function
+
+**Files:**
+- Create: `crates/clarion-cli/src/hooks_settings.rs`
+- Modify: `crates/clarion-cli/src/main.rs` (add `mod hooks_settings;`)
+- Test: inline `#[cfg(test)]` in `crates/clarion-cli/src/hooks_settings.rs`
+
+The verified `.claude/settings.json` shape (from the settings JSON schema): `hooks` is an object keyed by event name; `hooks.SessionStart` is an array of matcher-groups; each group is `{ "matcher"?: string, "hooks": [ { "type": "command", "command": "..." } ] }`. `matcher` is optional. Idempotency predicate: skip if any SessionStart group has a `hooks[]` entry whose `command` contains `clarion hook session-start`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `crates/clarion-cli/src/hooks_settings.rs` with this test block at the bottom:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::{HOOK_COMMAND, merge_session_start_hook};
+
+    #[test]
+    fn adds_hook_to_empty_settings() {
+        let mut settings = json!({});
+        let changed = merge_session_start_hook(&mut settings);
+        assert!(changed, "should report a change");
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(groups.len(), 1);
+        let cmd = groups[0]["hooks"][0]["command"].as_str().unwrap();
+        assert!(cmd.contains(HOOK_COMMAND), "command was: {cmd}");
+        assert_eq!(groups[0]["hooks"][0]["type"], "command");
+    }
+
+    #[test]
+    fn is_idempotent_when_hook_already_present() {
+        let mut settings = json!({});
+        assert!(merge_session_start_hook(&mut settings));
+        // Second merge must be a no-op.
+        assert!(!merge_session_start_hook(&mut settings));
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(groups.len(), 1, "must not duplicate the hook");
+    }
+
+    #[test]
+    fn preserves_unrelated_hooks_and_top_level_keys() {
+        // A Stop hook + an UNRELATED SessionStart command must both survive.
+        let mut settings = json!({
+            "model": "opus",
+            "hooks": {
+                "Stop": [
+                    {"hooks": [{"type": "command", "command": "echo bye"}]}
+                ],
+                "SessionStart": [
+                    {"hooks": [{"type": "command", "command": "echo unrelated-greeting"}]}
+                ]
+            }
+        });
+
+        let changed = merge_session_start_hook(&mut settings);
+        assert!(changed);
+
+        // Top-level key preserved.
+        assert_eq!(settings["model"], "opus");
+        // Stop hook untouched.
+        assert_eq!(
+            settings["hooks"]["Stop"][0]["hooks"][0]["command"],
+            "echo bye"
+        );
+        // SessionStart now has BOTH the unrelated entry and ours.
+        let groups = settings["hooks"]["SessionStart"].as_array().unwrap();
+        assert_eq!(groups.len(), 2, "must append, not replace");
+        let cmds: Vec<&str> = groups
+            .iter()
+            .flat_map(|g| g["hooks"].as_array().unwrap())
+            .map(|h| h["command"].as_str().unwrap())
+            .collect();
+        assert!(cmds.iter().any(|c| c.contains("unrelated-greeting")));
+        assert!(cmds.iter().any(|c| c.contains(HOOK_COMMAND)));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli hooks_settings`
+Expected: FAIL — `merge_session_start_hook`/`HOOK_COMMAND` not defined (compile error).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Top of `crates/clarion-cli/src/hooks_settings.rs`:
+
+```rust
+//! `.claude/settings.json` SessionStart-hook merge.
+//!
+//! Merge semantics (never clobber): parse existing JSON, append a SessionStart
+//! matcher-group running `clarion hook session-start` only if no existing
+//! SessionStart entry already runs that command, and preserve every other key.
+//!
+//! Verified against the Claude Code settings schema: `hooks.SessionStart` is an
+//! array of matcher-groups, each `{ "matcher"?, "hooks": [ {type,command} ] }`.
+
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, Result};
+use serde_json::{Map, Value, json};
+
+/// Substring that identifies Clarion's own SessionStart hook command.
+pub const HOOK_COMMAND: &str = "clarion hook session-start";
+
+/// Merge Clarion's SessionStart hook into a parsed settings `Value` in place.
+/// Returns `true` if a change was made, `false` if the hook was already present.
+#[must_use]
+pub fn merge_session_start_hook(settings: &mut Value) -> bool {
+    // Ensure `settings` is an object.
+    if !settings.is_object() {
+        *settings = Value::Object(Map::new());
+    }
+    let obj = settings.as_object_mut().expect("settings is object");
+
+    // Ensure `hooks` is an object.
+    let hooks = obj
+        .entry("hooks")
+        .or_insert_with(|| Value::Object(Map::new()));
+    if !hooks.is_object() {
+        *hooks = Value::Object(Map::new());
+    }
+    let hooks = hooks.as_object_mut().expect("hooks is object");
+
+    // Ensure `SessionStart` is an array.
+    let groups = hooks
+        .entry("SessionStart")
+        .or_insert_with(|| Value::Array(Vec::new()));
+    if !groups.is_array() {
+        *groups = Value::Array(Vec::new());
+    }
+    let groups = groups.as_array_mut().expect("SessionStart is array");
+
+    // Idempotency: skip if any existing entry already runs our command.
+    let already_present = groups.iter().any(|group| {
+        group
+            .get("hooks")
+            .and_then(Value::as_array)
+            .is_some_and(|inner| {
+                inner.iter().any(|h| {
+                    h.get("command")
+                        .and_then(Value::as_str)
+                        .is_some_and(|c| c.contains(HOOK_COMMAND))
+                })
+            })
+    });
+    if already_present {
+        return false;
+    }
+
+    groups.push(json!({
+        "hooks": [
+            {
+                "type": "command",
+                "command": "clarion hook session-start"
+            }
+        ]
+    }));
+    true
+}
+
+/// Read `.claude/settings.json` under `project_root` (creating an empty object
+/// if absent), merge Clarion's SessionStart hook, and write it back
+/// pretty-printed. Returns `true` if the file changed.
+///
+/// # Errors
+///
+/// Returns an error if the existing file is present but unparseable, or if any
+/// directory create / read / write fails.
+pub fn install_session_start_hook(project_root: &Path) -> Result<bool> {
+    let claude_dir = project_root.join(".claude");
+    let settings_path = claude_dir.join("settings.json");
+
+    let mut settings: Value = if settings_path.exists() {
+        let raw = fs::read_to_string(&settings_path)
+            .with_context(|| format!("read {}", settings_path.display()))?;
+        if raw.trim().is_empty() {
+            Value::Object(Map::new())
+        } else {
+            serde_json::from_str(&raw)
+                .with_context(|| format!("parse {}", settings_path.display()))?
+        }
+    } else {
+        Value::Object(Map::new())
+    };
+
+    let changed = merge_session_start_hook(&mut settings);
+    if !changed {
+        return Ok(false);
+    }
+
+    fs::create_dir_all(&claude_dir)
+        .with_context(|| format!("mkdir {}", claude_dir.display()))?;
+    let serialized = serde_json::to_string_pretty(&settings)
+        .context("serialize .claude/settings.json")?;
+    fs::write(&settings_path, format!("{serialized}\n"))
+        .with_context(|| format!("write {}", settings_path.display()))?;
+    Ok(true)
+}
+```
+
+Add to `crates/clarion-cli/src/main.rs` near the modules:
+
+```rust
+mod hooks_settings;
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli hooks_settings`
+Expected: PASS (all three merge tests green).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/hooks_settings.rs crates/clarion-cli/src/main.rs
+git commit -m "feat(cli): non-clobbering SessionStart hook merge for .claude/settings.json"
+```
+
+### Task 4.2: Wire `--hooks` and `--all` into `install::run`
+
+**Files:**
+- Modify: `crates/clarion-cli/src/install.rs` (`run`)
+- Test: `crates/clarion-cli/tests/skills.rs` (add)
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `crates/clarion-cli/tests/skills.rs`:
+
+```rust
+#[test]
+fn install_hooks_merges_session_start_without_clobbering() {
+    let dir = tempfile::tempdir().unwrap();
+    // Pre-seed an unrelated Stop hook.
+    let claude = dir.path().join(".claude");
+    fs::create_dir_all(&claude).unwrap();
+    fs::write(
+        claude.join("settings.json"),
+        r#"{"model":"opus","hooks":{"Stop":[{"hooks":[{"type":"command","command":"echo bye"}]}]}}"#,
+    )
+    .unwrap();
+
+    clarion_bin()
+        .args(["install", "--hooks", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    let raw = fs::read_to_string(claude.join("settings.json")).unwrap();
+    let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap();
+    // Unrelated key + Stop hook preserved.
+    assert_eq!(parsed["model"], "opus");
+    assert_eq!(
+        parsed["hooks"]["Stop"][0]["hooks"][0]["command"],
+        "echo bye"
+    );
+    // Our SessionStart hook added.
+    let cmds: Vec<String> = parsed["hooks"]["SessionStart"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .flat_map(|g| g["hooks"].as_array().unwrap())
+        .map(|h| h["command"].as_str().unwrap().to_string())
+        .collect();
+    assert!(cmds.iter().any(|c| c.contains("clarion hook session-start")));
+    // --hooks alone must NOT init .clarion/.
+    assert!(!dir.path().join(".clarion").exists());
+}
+
+#[test]
+fn install_all_does_init_skills_and_hooks() {
+    let dir = tempfile::tempdir().unwrap();
+    clarion_bin()
+        .args(["install", "--all", "--path"])
+        .arg(dir.path())
+        .assert()
+        .success();
+
+    assert!(dir.path().join(".clarion/clarion.db").exists(), "no db");
+    assert!(
+        dir.path()
+            .join(".claude/skills/clarion-workflow/SKILL.md")
+            .exists(),
+        "no skill"
+    );
+    let raw = fs::read_to_string(dir.path().join(".claude/settings.json")).unwrap();
+    assert!(raw.contains("clarion hook session-start"), "no hook: {raw}");
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-cli --test skills`
+Expected: FAIL — `--hooks` currently does nothing (the comment placeholder from Task 1.3); the SessionStart assertion fails.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `crates/clarion-cli/src/install.rs`, replace the placeholder line:
+
+```rust
+    // --hooks wired in Phase 4.
+```
+
+with:
+
+```rust
+    if components.hooks {
+        let changed = crate::hooks_settings::install_session_start_hook(&project_root)
+            .context("merge SessionStart hook into .claude/settings.json")?;
+        if changed {
+            println!(
+                "Added clarion SessionStart hook to {}/.claude/settings.json",
+                project_root.display()
+            );
+        } else {
+            println!("clarion SessionStart hook already present");
+        }
+    }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-cli --test skills`
+Expected: PASS (both new tests green plus the Phase-1 skills tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-cli/src/install.rs crates/clarion-cli/tests/skills.rs
+git commit -m "feat(cli): wire clarion install --hooks and --all"
+```
+
+### Task 4.3: Phase 4 gate
+
+- [ ] **Step 1: Run the crate gate**
+
+Run: `cargo fmt --all -- --check && cargo clippy -p clarion-cli --all-targets --all-features -- -D warnings && cargo nextest run -p clarion-cli`
+Expected: PASS, no warnings. Existing `tests/install.rs` still green.
+
+- [ ] **Step 2: Commit fixes if any**
+
+```bash
+git add -A
+git commit -m "style(cli): fmt/clippy after hooks install"
+```
+
+---
+
+## PHASE 5 — MCP `instructions` + `resources` + (optional) `prompt`
+
+`clarion://context` reuses `project_snapshot`. The prompt duplicates `SKILL.md` and is the droppable piece.
+
+### Task 5.1: `initialize` gains `instructions` + extended `capabilities`
+
+**Files:**
+- Modify: `crates/clarion-mcp/src/lib.rs` (`initialize_result` ~2059, embed `SKILL.md`)
+- Test: inline `#[cfg(test)]` in `crates/clarion-mcp/src/lib.rs` (extend `initialize_returns_server_info_and_tools_capability`, ~2901)
+
+- [ ] **Step 1: Write the failing test**
+
+In `crates/clarion-mcp/src/lib.rs`, extend the existing test `initialize_returns_server_info_and_tools_capability` (after the final `assert!(response["result"]["capabilities"]["tools"].is_object());`, before the closing `}`):
+
+```rust
+        // Orientation instructions present and mention the skill + entity model.
+        let instructions = response["result"]["instructions"]
+            .as_str()
+            .expect("initialize result has instructions");
+        assert!(
+            instructions.contains("clarion-workflow"),
+            "instructions should point at the skill"
+        );
+        assert!(
+            instructions.contains("entity"),
+            "instructions should describe the entity model"
+        );
+        // Prompts + resources capabilities advertised alongside tools.
+        assert!(response["result"]["capabilities"]["prompts"].is_object());
+        assert!(response["result"]["capabilities"]["resources"].is_object());
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-mcp initialize_returns_server_info`
+Expected: FAIL — `instructions` is absent (`as_str()` on Null panics → test fails); `capabilities.prompts`/`resources` absent.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `crates/clarion-mcp/src/lib.rs`, near the top (after `const EMPTY_GUIDANCE_FINGERPRINT`), add the embedded skill text + the instructions constant:
+
+```rust
+/// The bundled clarion-workflow skill text, embedded for the `prompts/get`
+/// surface and reused as the canonical orientation reference. Same file the
+/// CLI installs on disk.
+pub const CLARION_WORKFLOW_SKILL: &str =
+    include_str!("../../clarion-cli/assets/skills/clarion-workflow/SKILL.md");
+
+/// Static orientation text returned in the MCP `initialize` result's
+/// `instructions` field. Kept consistent with `list_tools()` and the
+/// clarion-workflow skill.
+const SERVER_INSTRUCTIONS: &str = "\
+Clarion is a code-archaeology server: it has pre-extracted this project into a \
+queryable map of entities (functions, classes, modules, files), the call / \
+reference / import edges between them, and subsystem clusters. Ask Clarion \
+instead of re-reading or grepping the tree.
+
+Entity IDs are `{plugin}:{kind}:{qualified_name}` (e.g. \
+`python:function:pkg.mod.func`); subsystems are `core:subsystem:{hash}`. You \
+almost never type IDs — get one from `find_entity` or `entity_at`, then copy it \
+verbatim into the next tool.
+
+Tools: find_entity, entity_at, callers_of, neighborhood, execution_paths_from, \
+subsystem_members, summary, issues_for. `callers_of` / `neighborhood` / \
+`execution_paths_from` take a `confidence` tier (resolved | ambiguous | \
+inferred; default resolved).
+
+For the full workflow see the clarion-workflow skill (installed by \
+`clarion install --skills`), or read the `clarion-workflow` prompt. Live \
+project counts and index freshness are in the `clarion://context` resource.";
+```
+
+Replace `initialize_result` (lines ~2059-2070) with:
+
+```rust
+fn initialize_result() -> Value {
+    json!({
+        "protocolVersion": MCP_PROTOCOL_VERSION,
+        "capabilities": {
+            "tools": {},
+            "prompts": {},
+            "resources": {}
+        },
+        "serverInfo": {
+            "name": "clarion",
+            "version": env!("CARGO_PKG_VERSION")
+        },
+        "instructions": SERVER_INSTRUCTIONS
+    })
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cargo nextest run -p clarion-mcp initialize`
+Expected: PASS. Also confirm the existing `tools_list_exposes_exact_docstrings` (asserts `tools.len() == 8`) still passes — `list_tools()` is untouched:
+Run: `cargo nextest run -p clarion-mcp tools_list_exposes_exact_docstrings`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/lib.rs
+git commit -m "feat(mcp): initialize advertises instructions + prompts/resources capabilities"
+```
+
+### Task 5.2: `resources/list` returns `clarion://context`
+
+**Files:**
+- Modify: `crates/clarion-mcp/src/lib.rs` (`ServerState::handle_json_rpc` match ~255)
+- Test: inline `#[cfg(test)]` in `crates/clarion-mcp/src/lib.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Look at how existing `ServerState` tests build state (the test module imports `ServerState`, `ReaderPool`, `pragma`, `schema` — see `crates/clarion-mcp/src/lib.rs:2845-2852`). Add this test to the `mod tests` block. It builds a migrated db on disk, opens a `ReaderPool`, and drives `handle_json_rpc`:
+
+```rust
+    #[tokio::test]
+    async fn resources_list_includes_clarion_context() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "resources/list",
+                "params": {}
+            }))
+            .await
+            .expect("response");
+
+        let resources = response["result"]["resources"].as_array().unwrap();
+        assert!(
+            resources
+                .iter()
+                .any(|r| r["uri"] == "clarion://context"),
+            "clarion://context not listed: {resources:?}"
+        );
+    }
+```
+
+(Confirm `tempfile` is a dev-dependency of `clarion-mcp`. If `cargo nextest` reports it missing, add `tempfile.workspace = true` under `[dev-dependencies]` in `crates/clarion-mcp/Cargo.toml` and `git add` it with this task.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cargo nextest run -p clarion-mcp resources_list`
+Expected: FAIL — `resources/list` hits the `_ => error_response(..., "method not found")` arm, so `result.resources` is absent.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `crates/clarion-mcp/src/lib.rs`, extend the `ServerState::handle_json_rpc` match (the `Some(match method { ... })` at ~255) by adding arms before the final `_ =>`:
+
+```rust
+            "resources/list" => result_response(&id, &resources_list()),
+            "resources/read" => self.handle_resources_read(&id, request.get("params")).await,
+            "prompts/list" => result_response(&id, &prompts_list()),
+            "prompts/get" => prompts_get(&id, request.get("params")),
+```
+
+Add these free functions near `initialize_result` (any module-level location in `lib.rs`):
+
+```rust
+fn resources_list() -> Value {
+    json!({
+        "resources": [
+            {
+                "uri": "clarion://context",
+                "name": "Clarion project context",
+                "description": "Live entity / subsystem / finding counts and index freshness for this project.",
+                "mimeType": "application/json"
+            }
+        ]
+    })
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+The test still won't pass until `handle_resources_read` and the prompt fns exist (the match arms reference them and the crate won't compile). Implement `handle_resources_read` minimally now so the crate compiles and this test passes; the read body is fully fleshed in Task 5.3. Add to `impl ServerState` (near `handle_tool_call`):
+
+```rust
+    async fn handle_resources_read(&self, id: &Value, params: Option<&Value>) -> Value {
+        let Some(uri) = params
+            .and_then(Value::as_object)
+            .and_then(|p| p.get("uri"))
+            .and_then(Value::as_str)
+        else {
+            return error_response(id, -32602, "invalid resources/read params: missing uri");
+        };
+        if uri != "clarion://context" {
+            return error_response(id, -32602, &format!("unknown resource: {uri}"));
+        }
+        let snapshot_json = self.context_snapshot_json().await;
+        result_response(
+            id,
+            &json!({
+                "contents": [
+                    {
+                        "uri": "clarion://context",
+                        "mimeType": "application/json",
+                        "text": snapshot_json
+                    }
+                ]
+            }),
+        )
+    }
+
+    async fn context_snapshot_json(&self) -> String {
+        let project_root = self.project_root.clone();
+        let snapshot = self
+            .readers
+            .with_reader(move |conn| {
+                Ok(crate::snapshot::project_snapshot(conn, &project_root))
+            })
+            .await;
+        match snapshot {
+            Ok(snap) => serde_json::to_string(&snap)
+                .unwrap_or_else(|_| "{\"db_present\":true,\"staleness\":\"unknown\"}".to_owned()),
+            Err(err) => {
+                tracing::warn!(error = %err, "clarion://context snapshot failed");
+                serde_json::json!({
+                    "db_present": true,
+                    "entity_count": 0,
+                    "subsystem_count": 0,
+                    "finding_count": 0,
+                    "staleness": "unknown",
+                    "last_analyzed_at": serde_json::Value::Null
+                })
+                .to_string()
+            }
+        }
+    }
+```
+
+Add minimal prompt fns (fleshed in 5.5) so the match compiles:
+
+```rust
+fn prompts_list() -> Value {
+    json!({
+        "prompts": [
+            {
+                "name": "clarion-workflow",
+                "description": "How to use Clarion's MCP tools to navigate this codebase."
+            }
+        ]
+    })
+}
+
+fn prompts_get(id: &Value, params: Option<&Value>) -> Value {
+    let name = params
+        .and_then(Value::as_object)
+        .and_then(|p| p.get("name"))
+        .and_then(Value::as_str);
+    if name != Some("clarion-workflow") {
+        return error_response(id, -32602, "unknown prompt");
+    }
+    result_response(
+        id,
+        &json!({
+            "description": "How to use Clarion's MCP tools to navigate this codebase.",
+            "messages": [
+                {
+                    "role": "user",
+                    "content": { "type": "text", "text": CLARION_WORKFLOW_SKILL }
+                }
+            ]
+        }),
+    )
+}
+```
+
+Run: `cargo nextest run -p clarion-mcp resources_list`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/lib.rs crates/clarion-mcp/Cargo.toml
+git commit -m "feat(mcp): resources/list advertises clarion://context"
+```
+
+### Task 5.3: `resources/read` of `clarion://context` returns the snapshot
+
+**Files:**
+- Modify: none (handler landed in 5.2)
+- Test: inline `#[cfg(test)]` in `crates/clarion-mcp/src/lib.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `mod tests`:
+
+```rust
+    #[tokio::test]
+    async fn resources_read_returns_context_snapshot_json() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+            conn.execute(
+                "INSERT INTO entities \
+                 (id, plugin_id, kind, name, short_name, properties, created_at, updated_at) \
+                 VALUES ('python:module:m','python','module','m','m','{}', \
+                         '2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')",
+                [],
+            )
+            .unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 7,
+                "method": "resources/read",
+                "params": {"uri": "clarion://context"}
+            }))
+            .await
+            .expect("response");
+
+        let text = response["result"]["contents"][0]["text"]
+            .as_str()
+            .expect("snapshot text");
+        let parsed: serde_json::Value = serde_json::from_str(text).unwrap();
+        assert_eq!(parsed["db_present"], true);
+        assert_eq!(parsed["entity_count"], 1);
+        assert_eq!(parsed["staleness"], "never_analyzed");
+    }
+
+    #[tokio::test]
+    async fn resources_read_rejects_unknown_uri() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 8,
+                "method": "resources/read",
+                "params": {"uri": "clarion://nope"}
+            }))
+            .await
+            .expect("response");
+        assert!(response["error"].is_object(), "expected an error envelope");
+    }
+```
+
+- [ ] **Step 2: Run test to verify it fails or passes**
+
+Run: `cargo nextest run -p clarion-mcp resources_read`
+Expected: PASS (handler from 5.2 already serves this). If `staleness` is not `never_analyzed`, the bug is in 5.2's snapshot wiring — fix there. This task locks the read contract.
+
+- [ ] **Step 3: (no new implementation)**
+
+Skip.
+
+- [ ] **Step 4: Re-run to confirm green**
+
+Run: `cargo nextest run -p clarion-mcp resources_read`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/lib.rs
+git commit -m "test(mcp): lock resources/read clarion://context contract"
+```
+
+### Task 5.4: e2e — assert `instructions` and `resources/read` over the wire
+
+**Files:**
+- Modify: `tests/e2e/sprint_2_mcp_surface.sh` (add a request + assertions)
+- Test: the script itself
+
+- [ ] **Step 1: Add the request + assertions**
+
+In `tests/e2e/sprint_2_mcp_surface.sh`, add a new entry to the `requests` Python list (after the `"issues"` tuple, before the closing `]` at ~line 362):
+
+```python
+    (
+        "context",
+        {
+            "jsonrpc": "2.0",
+            "id": "context",
+            "method": "resources/read",
+            "params": {"uri": "clarion://context"},
+        },
+    ),
+```
+
+Then add assertions after the existing `assert responses["initialize"]["result"]["protocolVersion"] == "2025-11-25"` line (~379):
+
+```python
+init_result = responses["initialize"]["result"]
+assert "clarion-workflow" in init_result["instructions"], init_result.get("instructions")
+assert isinstance(init_result["capabilities"]["resources"], dict), init_result["capabilities"]
+assert isinstance(init_result["capabilities"]["prompts"], dict), init_result["capabilities"]
+```
+
+And add, after the `issues` assertions block near the end (after line ~441):
+
+```python
+context = responses["context"]["result"]
+ctx_text = context["contents"][0]["text"]
+ctx = json.loads(ctx_text)
+assert ctx["db_present"] is True, ctx
+assert ctx["entity_count"] >= 1, ctx
+assert "staleness" in ctx, ctx
+```
+
+- [ ] **Step 2: Run the e2e script to verify it (initially) reflects reality**
+
+Run: `bash tests/e2e/sprint_2_mcp_surface.sh`
+Expected: PASS — the binary now serves `instructions`, the `resources` capability, and `resources/read clarion://context`. (If you run this BEFORE Phase 5 code lands, it FAILs on the `instructions` KeyError — that is the failing-test step; run it after 5.1–5.3 are committed.)
+
+- [ ] **Step 3: (no implementation — covered by Phase 5 Rust tasks)**
+
+Skip.
+
+- [ ] **Step 4: Confirm green**
+
+Run: `bash tests/e2e/sprint_2_mcp_surface.sh`
+Expected: PASS, final log line "PASS: MCP stdio surface ...".
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/e2e/sprint_2_mcp_surface.sh
+git commit -m "test(e2e): assert MCP initialize instructions and clarion://context read"
+```
+
+### Task 5.5 (OPTIONAL — droppable): prove `prompts/list` + `prompts/get`
+
+The handler already landed in 5.2; this task only adds proving tests. **Skip under time pressure** — the prompt duplicates the installed `SKILL.md` (Decision Point f).
+
+**Files:**
+- Modify: none
+- Test: inline `#[cfg(test)]` in `crates/clarion-mcp/src/lib.rs`
+
+- [ ] **Step 1: Write the test**
+
+```rust
+    #[tokio::test]
+    async fn prompts_get_returns_skill_text() {
+        let dir = tempfile::tempdir().unwrap();
+        let db = dir.path().join("clarion.db");
+        {
+            let mut conn = rusqlite::Connection::open(&db).unwrap();
+            pragma::apply_write_pragmas(&conn).unwrap();
+            schema::apply_migrations(&mut conn).unwrap();
+        }
+        let readers = ReaderPool::open(&db, 4).unwrap();
+        let state = ServerState::new(dir.path().to_path_buf(), readers);
+
+        let response = state
+            .handle_json_rpc(&serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 9,
+                "method": "prompts/get",
+                "params": {"name": "clarion-workflow"}
+            }))
+            .await
+            .expect("response");
+        let text = response["result"]["messages"][0]["content"]["text"]
+            .as_str()
+            .unwrap();
+        assert!(text.contains("name: clarion-workflow"), "not the skill text");
+    }
+```
+
+- [ ] **Step 2: Run**
+
+Run: `cargo nextest run -p clarion-mcp prompts_get`
+Expected: PASS (handler from 5.2 serves it).
+
+- [ ] **Step 3: (no implementation)**
+
+Skip.
+
+- [ ] **Step 4: Confirm**
+
+Run: `cargo nextest run -p clarion-mcp prompts_get`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/lib.rs
+git commit -m "test(mcp): prompts/get serves clarion-workflow skill text"
+```
+
+### Task 5.6: Phase 5 gate (full workspace)
+
+- [ ] **Step 1: Run the full Rust gate**
+
+Run:
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo build --workspace --bins
+cargo nextest run --workspace --all-features
+RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
+cargo deny check
+```
+Expected: all PASS. (`cargo deny check` confirms no new dependency was added — `include_str!` route.)
+
+- [ ] **Step 2: Run both e2e scripts**
+
+Run: `bash tests/e2e/sprint_2_mcp_surface.sh && bash tests/e2e/sprint_1_walking_skeleton.sh`
+Expected: PASS.
+
+- [ ] **Step 3: Commit fixes if any**
+
+```bash
+git add -A
+git commit -m "style: fmt/clippy after MCP orientation surface"
+```
+
+---
+
+## PHASE 6 — Docs + Filigree bookkeeping
+
+### Task 6.1: Document the new install/hook/MCP surface
+
+**Files:**
+- Modify: `docs/operator/getting-started.md` (the `clarion serve` / MCP-client section ~155-185)
+
+- [ ] **Step 1: Add an orientation subsection**
+
+After the MCP-client registration block (~line 185, before "## 4. Ask"), add:
+
+```markdown
+### Agent orientation (optional but recommended)
+
+Give consult-mode agents a head start:
+
+```bash
+clarion install --skills --path /tmp/requests-2.32.4   # bundle the clarion-workflow skill
+clarion install --hooks --path /tmp/requests-2.32.4    # add a SessionStart snapshot hook
+clarion install --all   --path /tmp/requests-2.32.4    # .clarion/ init + skills + hooks
+```
+
+`--skills` writes `.claude/skills/clarion-workflow/` and `.agents/skills/clarion-workflow/`.
+`--hooks` merges a SessionStart entry into `.claude/settings.json` (existing
+hooks are preserved) that runs `clarion hook session-start` — a fail-soft
+command printing live entity/subsystem/finding counts and index freshness.
+
+Over MCP, the same orientation is available without install: the `initialize`
+result carries an `instructions` field, the `clarion://context` resource returns
+the live snapshot, and the `clarion-workflow` prompt returns the skill text.
+```
+
+- [ ] **Step 2: Verify the doc renders (no test; visual check)**
+
+Run: `grep -n "clarion install --skills" docs/operator/getting-started.md`
+Expected: the new lines are present.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/operator/getting-started.md
+git commit -m "docs(operator): document install --skills/--hooks/--all and MCP orientation"
+```
+
+### Task 6.2: File the dogfood product gaps in Filigree
+
+**Files:**
+- None (Filigree CLI/MCP only)
+
+- [ ] **Step 1: File the two gaps as children of the orientation epic**
+
+These are out-of-scope for this slice (Decision Point e) but must be tracked, not dropped. Run (CLI form; use `--actor` for attribution):
+
+```bash
+filigree create-issue \
+  --title "find_entity has no kind filter" \
+  --body "Dogfooding clarion-workflow showed find_entity cannot constrain by entity kind (e.g. only subsystems). Today agents must search a package name and eyeball the result whose kind is 'subsystem'. Add an optional kind filter to find_entity's inputSchema + query. Documented as a gotcha in crates/clarion-cli/assets/skills/clarion-workflow/SKILL.md (lines 73-75). Cites: MCP tool surface in crates/clarion-mcp/src/lib.rs list_tools()." \
+  --label release:1.1 --actor "$USER"
+
+filigree create-issue \
+  --title "No module->subsystem reverse lookup" \
+  --body "neighborhood does not return an entity's subsystem; membership is only reachable forward via subsystem_members(subsystem_id). Add a reverse lookup (subsystem_for_member is already in clarion-storage query.rs — surface it as an MCP tool or neighborhood field). Documented as a gotcha in the clarion-workflow SKILL.md." \
+  --label release:1.1 --actor "$USER"
+```
+
+Then add each as a child/dependency of epic `clarion-8fe3060d4c` (use the IDs printed by the create commands):
+
+```bash
+filigree add-dependency <new-issue-id-1> --depends-on clarion-8fe3060d4c --actor "$USER"
+filigree add-dependency <new-issue-id-2> --depends-on clarion-8fe3060d4c --actor "$USER"
+```
+
+(If `add-dependency`'s direction differs in this filigree version, run `filigree add-dependency --help` and link so the two gaps are children of `clarion-8fe3060d4c`. If a `--parent`/epic verb exists, prefer it.)
+
+- [ ] **Step 2: Confirm they're tracked**
+
+Run: `filigree list-issues --label release:1.1`
+Expected: both new issues listed.
+
+- [ ] **Step 3: (no commit — Filigree state is in `.filigree/`, managed separately)**
+
+Skip git commit; Filigree manages its own store.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- (1) `install --skills` atomic temp→rename, both roots, fingerprint-aware → Phase 1 (Tasks 1.2, 1.3). ✓
+- (2) `install --hooks` non-clobbering settings.json merge → Phase 4 (Tasks 4.1, 4.2). ✓
+- (3) `install --all` + bare unchanged → Task 1.3 (`InstallComponents::from_flags`) + Task 4.2; existing `install.rs` tests prove bare unchanged. ✓
+- (4) `clarion hook session-start` fail-soft, resync + snapshot + nudge → Phase 3. ✓
+- (5) MCP `instructions` + `prompts`/`resources` capabilities + `prompts/list|get` + `resources/list|read clarion://context` → Phase 5. ✓
+- (6) shared snapshot module used by both hook and MCP resource → Phase 2 (`project_snapshot`), consumed in Task 3.2 (hook) and Task 5.2 (`context_snapshot_json`). ✓
+- Decision Points (include_str! vs include_dir; dogfood gaps; prompt optional) → top section + Task 6.2. ✓
+- e2e wire assertions → Task 5.4. ✓
+
+**Placeholder scan:** No "TBD"/"add error handling"/"similar to Task N". The "wired in Phase 4" comment in Task 1.3 is a real intermediate literal that Task 4.2 replaces with shown code. Tasks 2.2/3.3-style "no new implementation" steps are explicit (logic landed earlier) — not placeholders.
+
+**Type consistency:** `InstallComponents{init_clarion,skills,hooks}` + `from_flags(skills,hooks,all)` consistent across cli.rs/install.rs/main.rs. `install_skill_pack -> SkillInstallReport{copied}` consistent across skill_pack.rs/install.rs/hook.rs. `project_snapshot(conn, project_root) -> ProjectSnapshot{db_present,entity_count,subsystem_count,finding_count,staleness,last_analyzed_at}` + `Staleness{NeverAnalyzed,Stale,Fresh,Unknown}` (serde snake_case) + `missing_db_snapshot()` consistent across snapshot.rs/hook.rs/lib.rs. `merge_session_start_hook(&mut Value)->bool` + `install_session_start_hook(&Path)->Result<bool>` + `HOOK_COMMAND` consistent across hooks_settings.rs/install.rs. `HookCommand::SessionStart{path}` consistent across cli.rs/main.rs/hook.rs. `CLARION_WORKFLOW_SKILL`/`SERVER_INSTRUCTIONS`/`resources_list`/`prompts_list`/`prompts_get`/`handle_resources_read`/`context_snapshot_json` all defined in lib.rs Phase 5. ✓
diff --git a/docs/superpowers/plans/2026-05-30-flow-b-wardline-finding-reconciliation.md b/docs/superpowers/plans/2026-05-30-flow-b-wardline-finding-reconciliation.md
new file mode 100644
index 00000000..0e7dfd6f
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-30-flow-b-wardline-finding-reconciliation.md
@@ -0,0 +1,826 @@
+# Flow B — Read-Time Wardline Finding Reconciliation — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** When `issues_for` / `orientation_pack` runs for an entity, surface the Wardline findings Filigree holds for that entity, reconciled by qualname — enrich-only, no new Filigree route.
+
+**Architecture:** A new `wardline_reconcile` module does pure qualname matching (`metadata.wardline.qualname` == the entity_id's segment-3 qualname). The Filigree HTTP client (`filigree.rs`) gains a two-hop read (`GET /api/loom/files?path_prefix=` → Filigree `file_id`, then `GET /api/loom/findings?scan_source=wardline&file_id=`). The two MCP tools call the client, reconcile, and attach a `wardline_findings` section. If Filigree is unreachable the section degrades to `unavailable`; the tool never fails.
+
+**Tech Stack:** Rust, `reqwest::blocking`, `serde`/`serde_json`, `cargo nextest`. Spec: `docs/superpowers/specs/2026-05-30-clarion-consume-wardline-data-design.md`. Tracked by `clarion-71f995b88a`.
+
+---
+
+## File Structure
+
+- **Create** `crates/clarion-mcp/src/wardline_reconcile.rs` — pure reconciliation: qualname extraction from an entity_id, qualname extraction from a finding's metadata, the `ResolutionConfidence` enum, and `reconcile_for_entity`. No I/O; fully unit-testable.
+- **Modify** `crates/clarion-mcp/src/filigree.rs` — add the `WardlineFinding` / `LoomFileRecord` wire types + parsers, the `loom_files_url` / `loom_findings_url` builders, a private `get_json` helper, and `FiligreeLookup::wardline_findings_for_path` (default `Ok(vec![])`; HTTP client does the two-hop).
+- **Modify** `crates/clarion-mcp/src/lib.rs` — register `mod wardline_reconcile`; build the `wardline_findings` section in `tool_issues_for` and `tool_orientation_pack`.
+- **Modify** `docs/federation/contracts.md` — pin the two consumed loom read routes.
+
+Each task is independently committable. Run the full crate gate after the last code task: `cargo fmt --all -- --check`, `cargo clippy -p clarion-mcp --all-targets -- -D warnings`, `cargo nextest run -p clarion-mcp`.
+
+---
+
+## Task 1: Wardline + loom-file wire types and parsers
+
+**Files:**
+- Modify: `crates/clarion-mcp/src/filigree.rs` (add types near the other `Deserialize` structs, ~line 38; tests in the existing `#[cfg(test)] mod tests`)
+
+- [ ] **Step 1: Write the failing parse tests**
+
+Add to `mod tests` in `crates/clarion-mcp/src/filigree.rs`:
+
+```rust
+#[test]
+fn parses_loom_findings_list_envelope() {
+    let resp = parse_wardline_findings_response(
+        r#"{"items":[
+            {"finding_id":"f-1","file_id":"file-9","severity":"high","status":"open",
+             "scan_source":"wardline","rule_id":"WLN-TAINT-001","message":"tainted sink",
+             "suggestion":"","scan_run_id":"r-1","line_start":12,"line_end":12,
+             "fingerprint":"fp-abc","issue_id":null,"seen_count":1,
+             "metadata":{"wardline":{"qualname":"demo.Foo.bar","kind":"DEFECT"}},
+             "data_warnings":[]}
+        ],"has_more":false}"#,
+    )
+    .expect("parse findings list");
+    assert_eq!(resp.items.len(), 1);
+    let f = &resp.items[0];
+    assert_eq!(f.rule_id, "WLN-TAINT-001");
+    assert_eq!(f.fingerprint.as_deref(), Some("fp-abc"));
+    assert_eq!(f.line_start, Some(12));
+    assert_eq!(
+        f.metadata.get("wardline").and_then(|w| w.get("qualname")).and_then(|q| q.as_str()),
+        Some("demo.Foo.bar")
+    );
+}
+
+#[test]
+fn parses_loom_files_list_envelope() {
+    let resp = parse_loom_files_response(
+        r#"{"items":[
+            {"file_id":"file-9","path":"src/demo.py","language":"python","file_type":"source"},
+            {"file_id":"file-10","path":"src/demo_helpers.py","language":"python","file_type":"source"}
+        ],"has_more":false}"#,
+    )
+    .expect("parse files list");
+    assert_eq!(resp.items.len(), 2);
+    assert_eq!(resp.items[0].file_id, "file-9");
+    assert_eq!(resp.items[0].path, "src/demo.py");
+}
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `cargo nextest run -p clarion-mcp filigree::tests::parses_loom`
+Expected: FAIL to compile — `parse_wardline_findings_response`, `parse_loom_files_response`, and the types are not defined.
+
+- [ ] **Step 3: Add the types and parsers**
+
+Add to `crates/clarion-mcp/src/filigree.rs` (after `EntityAssociation`, ~line 38). Extra fields in the Filigree rows are ignored by serde, so this reads only the subset Clarion surfaces:
+
+```rust
+/// One Wardline finding as Clarion surfaces it — the subset of Filigree's
+/// `ScanFindingLoom` (`GET /api/loom/findings`) used for read-time
+/// reconciliation. Unknown fields are ignored so Filigree can grow the row.
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+pub struct WardlineFinding {
+    pub rule_id: String,
+    pub message: String,
+    #[serde(default)]
+    pub severity: Option<String>,
+    #[serde(default)]
+    pub status: Option<String>,
+    #[serde(default)]
+    pub line_start: Option<i64>,
+    #[serde(default)]
+    pub line_end: Option<i64>,
+    #[serde(default)]
+    pub fingerprint: Option<String>,
+    #[serde(default)]
+    pub file_id: Option<String>,
+    /// The finding's `metadata` object; `metadata.wardline.qualname` is the
+    /// reconciliation key. Defaults to JSON null when absent.
+    #[serde(default)]
+    pub metadata: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct WardlineFindingsResponse {
+    #[serde(default)]
+    pub items: Vec<WardlineFinding>,
+}
+
+/// One row of `GET /api/loom/files` — only the fields needed to map a path to
+/// Filigree's `file_id`.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+pub struct LoomFileRecord {
+    pub file_id: String,
+    pub path: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct LoomFilesResponse {
+    #[serde(default)]
+    pub items: Vec<LoomFileRecord>,
+}
+
+pub fn parse_wardline_findings_response(
+    body: &str,
+) -> Result<WardlineFindingsResponse, FiligreeContractError> {
+    serde_json::from_str(body).map_err(FiligreeContractError::from)
+}
+
+pub fn parse_loom_files_response(body: &str) -> Result<LoomFilesResponse, FiligreeContractError> {
+    serde_json::from_str(body).map_err(FiligreeContractError::from)
+}
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `cargo nextest run -p clarion-mcp filigree::tests::parses_loom`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/filigree.rs
+git commit -m "feat(mcp): Wardline finding + loom-file wire types (Flow B, clarion-71f995b88a)"
+```
+
+---
+
+## Task 2: Pure qualname reconciliation module
+
+**Files:**
+- Create: `crates/clarion-mcp/src/wardline_reconcile.rs`
+- Modify: `crates/clarion-mcp/src/lib.rs` (add `mod wardline_reconcile;` next to the other `mod` declarations near the top)
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `crates/clarion-mcp/src/wardline_reconcile.rs` with only the tests first:
+
+```rust
+//! Reconcile Wardline findings to Clarion entities by qualname (Flow B).
+//!
+//! `metadata.wardline.qualname` is the pre-composed dotted name, which for a
+//! function/method entity is byte-identical to the entity_id's segment-3
+//! `canonical_qualified_name` (proven by `fixtures/entity_id.json`). Matching is
+//! therefore a local string compare against Clarion's own catalog — no oracle.
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::filigree::WardlineFinding;
+
+    fn finding(qualname: Option<&str>) -> WardlineFinding {
+        let metadata = match qualname {
+            Some(q) => serde_json::json!({ "wardline": { "qualname": q } }),
+            None => serde_json::json!({ "wardline": { "kind": "DEFECT" } }),
+        };
+        WardlineFinding {
+            rule_id: "WLN-X".to_owned(),
+            message: "m".to_owned(),
+            severity: Some("high".to_owned()),
+            status: Some("open".to_owned()),
+            line_start: Some(1),
+            line_end: Some(1),
+            fingerprint: Some("fp".to_owned()),
+            file_id: Some("file-1".to_owned()),
+            metadata,
+        }
+    }
+
+    #[test]
+    fn extracts_segment_three_qualname_incl_locals_and_nested() {
+        assert_eq!(entity_qualname("python:function:demo.Foo.bar"), Some("demo.Foo.bar"));
+        assert_eq!(
+            entity_qualname("python:function:demo.outer.<locals>.inner"),
+            Some("demo.outer.<locals>.inner")
+        );
+        assert_eq!(entity_qualname("python:function:hello"), Some("hello"));
+        assert_eq!(entity_qualname("python:module:"), None); // empty qualname
+        assert_eq!(entity_qualname("notanid"), None);
+    }
+
+    #[test]
+    fn exact_match_binds_other_qualname_is_none() {
+        let r = reconcile_for_entity(
+            "python:function:demo.Foo.bar",
+            vec![finding(Some("demo.Foo.bar")), finding(Some("demo.other"))],
+        );
+        assert_eq!(r.matched.len(), 1);
+        assert_eq!(r.matched[0].resolution_confidence, ResolutionConfidence::Exact);
+        assert_eq!(r.omitted_no_qualname, 0);
+    }
+
+    #[test]
+    fn missing_qualname_is_counted_omitted_not_matched() {
+        let r = reconcile_for_entity("python:function:demo.Foo.bar", vec![finding(None)]);
+        assert!(r.matched.is_empty());
+        assert_eq!(r.omitted_no_qualname, 1);
+    }
+
+    #[test]
+    fn unparseable_entity_id_yields_empty_no_panic() {
+        let r = reconcile_for_entity("notanid", vec![finding(Some("demo.Foo.bar"))]);
+        assert!(r.matched.is_empty());
+        assert_eq!(r.omitted_no_qualname, 0);
+    }
+}
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `cargo nextest run -p clarion-mcp wardline_reconcile`
+Expected: FAIL to compile — module not registered, symbols undefined.
+
+- [ ] **Step 3: Implement the module**
+
+Add `mod wardline_reconcile;` to `crates/clarion-mcp/src/lib.rs` (with the other module declarations), then prepend the implementation above the `#[cfg(test)]` block in `wardline_reconcile.rs`:
+
+```rust
+use crate::filigree::WardlineFinding;
+
+/// A Wardline finding's resolution against a Clarion entity. v1 produces only
+/// `Exact` (byte-equal qualname) or `None`. `Heuristic` is reserved for a future
+/// best-effort normalization pass and is never returned yet — kept in the enum
+/// so the wire shape is stable when it lands.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ResolutionConfidence {
+    Exact,
+    Heuristic,
+    None,
+}
+
+#[derive(Debug, Clone)]
+pub struct MatchedFinding {
+    pub finding: WardlineFinding,
+    pub resolution_confidence: ResolutionConfidence,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct ReconcileResult {
+    pub matched: Vec<MatchedFinding>,
+    pub omitted_no_qualname: usize,
+}
+
+/// The entity_id's segment-3 `canonical_qualified_name`.
+/// `python:function:demo.Foo.bar` -> `Some("demo.Foo.bar")`. `None` when the id
+/// lacks three `{plugin}:{kind}:{qualname}` segments or the qualname is empty.
+pub fn entity_qualname(entity_id: &str) -> Option<&str> {
+    let mut parts = entity_id.splitn(3, ':');
+    let _plugin = parts.next()?;
+    let _kind = parts.next()?;
+    let qualname = parts.next()?;
+    (!qualname.is_empty()).then_some(qualname)
+}
+
+/// The dotted qualname a finding targets, from `metadata.wardline.qualname`.
+/// `None` when the key is absent (malformed / non-Python) — counted as omitted.
+fn finding_qualname(finding: &WardlineFinding) -> Option<&str> {
+    finding.metadata.get("wardline")?.get("qualname")?.as_str()
+}
+
+fn resolution_confidence(entity_qn: &str, finding_qn: &str) -> ResolutionConfidence {
+    if entity_qn == finding_qn {
+        ResolutionConfidence::Exact
+    } else {
+        ResolutionConfidence::None
+    }
+}
+
+/// Filter `findings` to those that resolve to `entity_id`, tagging each with its
+/// confidence. Findings with no `wardline.qualname` are counted in
+/// `omitted_no_qualname`, never dropped silently.
+pub fn reconcile_for_entity(entity_id: &str, findings: Vec<WardlineFinding>) -> ReconcileResult {
+    let Some(target) = entity_qualname(entity_id) else {
+        return ReconcileResult::default();
+    };
+    let mut result = ReconcileResult::default();
+    for finding in findings {
+        match finding_qualname(&finding) {
+            Some(qn) => {
+                let confidence = resolution_confidence(target, qn);
+                if confidence != ResolutionConfidence::None {
+                    result.matched.push(MatchedFinding { finding, resolution_confidence: confidence });
+                }
+            }
+            None => result.omitted_no_qualname += 1,
+        }
+    }
+    result
+}
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `cargo nextest run -p clarion-mcp wardline_reconcile`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/clarion-mcp/src/wardline_reconcile.rs crates/clarion-mcp/src/lib.rs
+git commit -m "feat(mcp): pure Wardline qualname reconciliation module (Flow B)"
+```
+
+---
+
+## Task 3: Filigree client two-hop fetch
+
+**Files:**
+- Modify: `crates/clarion-mcp/src/filigree.rs` (URL builders near `entity_associations_url` ~line 286; `get_json` helper + trait method + HTTP impl; mock-server test in `mod tests`)
+
+- [ ] **Step 1: Write the failing URL-builder + mock-server tests**
+
+Add to `mod tests` in `crates/clarion-mcp/src/filigree.rs`:
+
+```rust
+#[test]
+fn builds_loom_url_builders_with_encoding() {
+    assert_eq!(
+        loom_files_url("http://127.0.0.1:8542/", "wardline", "src/demo.py"),
+        "http://127.0.0.1:8542/api/loom/files?scan_source=wardline&path_prefix=src%2Fdemo.py"
+    );
+    assert_eq!(
+        loom_findings_url("http://127.0.0.1:8542/", "wardline", "file-9"),
+        "http://127.0.0.1:8542/api/loom/findings?scan_source=wardline&file_id=file-9"
+    );
+}
+
+#[test]
+fn wardline_findings_for_path_does_two_hops_and_exact_path_filter() {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
+    let addr = listener.local_addr().expect("local addr");
+    let handle = std::thread::spawn(move || {
+        // Hop 1: GET /api/loom/files — path_prefix matches two files; the
+        // exact-path filter must pick file-9, not the helpers file.
+        let (mut s1, _) = listener.accept().expect("accept files");
+        let mut buf = [0_u8; 4096];
+        let n = s1.read(&mut buf).expect("read files req");
+        let req = String::from_utf8_lossy(&buf[..n]);
+        assert!(req.contains("GET /api/loom/files?scan_source=wardline&path_prefix=src%2Fdemo.py HTTP/1.1"));
+        let body = r#"{"items":[{"file_id":"file-9","path":"src/demo.py","language":"python","file_type":"source"},{"file_id":"file-10","path":"src/demo.py.bak","language":"python","file_type":"source"}],"has_more":false}"#;
+        write!(s1, "HTTP/1.1 200 OK\r\ncontent-length: {}\r\n\r\n{}", body.len(), body).unwrap();
+
+        // Hop 2: GET /api/loom/findings for file-9.
+        let (mut s2, _) = listener.accept().expect("accept findings");
+        let n = s2.read(&mut buf).expect("read findings req");
+        let req = String::from_utf8_lossy(&buf[..n]);
+        assert!(req.contains("GET /api/loom/findings?scan_source=wardline&file_id=file-9 HTTP/1.1"));
+        let body = r#"{"items":[{"finding_id":"f-1","file_id":"file-9","severity":"high","status":"open","scan_source":"wardline","rule_id":"WLN-TAINT-001","message":"sink","suggestion":"","scan_run_id":"r-1","line_start":12,"line_end":12,"fingerprint":"fp","issue_id":null,"seen_count":1,"metadata":{"wardline":{"qualname":"demo.Foo.bar"}},"data_warnings":[]}],"has_more":false}"#;
+        write!(s2, "HTTP/1.1 200 OK\r\ncontent-length: {}\r\n\r\n{}", body.len(), body).unwrap();
+    });
+    let client = detail_test_client(addr);
+    let findings = client
+        .wardline_findings_for_path("src/demo.py")
+        .expect("two-hop fetch");
+    assert_eq!(findings.len(), 1);
+    assert_eq!(findings[0].rule_id, "WLN-TAINT-001");
+    handle.join().expect("server thread");
+}
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `cargo nextest run -p clarion-mcp filigree::tests::wardline_findings_for_path filigree::tests::builds_loom_url`
+Expected: FAIL to compile — `loom_files_url`, `loom_findings_url`, and `wardline_findings_for_path` undefined.
+
+- [ ] **Step 3: Add URL builders**
+
+Add to `crates/clarion-mcp/src/filigree.rs` near `entity_associations_url`:
+
+```rust
+pub fn loom_files_url(base_url: &str, scan_source: &str, path_prefix: &str) -> String {
+    format!(
+        "{}/api/loom/files?scan_source={}&path_prefix={}",
+        base_url.trim_end_matches('/'),
+        percent_encode_query_value(scan_source),
+        percent_encode_query_value(path_prefix)
+    )
+}
+
+pub fn loom_findings_url(base_url: &str, scan_source: &str, file_id: &str) -> String {
+    format!(
+        "{}/api/loom/findings?scan_source={}&file_id={}",
+        base_url.trim_end_matches('/'),
+        percent_encode_query_value(scan_source),
+        percent_encode_query_value(file_id)
+    )
+}
+```
+
+- [ ] **Step 4: Add a `get_json` helper and the trait method**
+
+Add a private helper to `impl FiligreeHttpClient` (DRYs the header/auth/status/parse the existing methods inline):
+
+```rust
+    /// GET `url` with the standard actor + bearer headers and parse the body as
+    /// `T`. A non-success status is surfaced as `HttpStatus` so the caller can
+    /// stop hammering a down endpoint.
+    fn get_json<T: serde::de::DeserializeOwned>(
+        &self,
+        url: &str,
+    ) -> Result<T, FiligreeClientError> {
+        let mut request = self.client.get(url).header("accept", "application/json");
+        if !self.actor.trim().is_empty() {
+            request = request.header("x-filigree-actor", self.actor.as_str());
+        }
+        if let Some(token) = &self.token {
+            request = request.bearer_auth(token);
+        }
+        let response = request.send().map_err(FiligreeClientError::Request)?;
+        let status = response.status();
+        let body = response.text().map_err(FiligreeClientError::Request)?;
+        if !status.is_success() {
+            return Err(FiligreeClientError::HttpStatus { status: status.as_u16(), body });
+        }
+        serde_json::from_str(&body)
+            .map_err(|e| FiligreeClientError::Contract(FiligreeContractError::from(e)))
+    }
+```
+
+Add the method to the `FiligreeLookup` trait (default returns empty so storage-only servers and existing test doubles keep compiling, exactly like `issue_detail`):
+
+```rust
+    /// Wardline findings for a source file, for read-time reconciliation
+    /// (Flow B). Two-hop: resolve `path` → Filigree `file_id`, then fetch that
+    /// file's `scan_source=wardline` findings. Returns an empty list when no
+    /// Wardline-touched file exists at `path`. Default impl returns empty (no
+    /// Filigree); the HTTP client overrides it. Transport / non-success HTTP is
+    /// surfaced as `Err` so the caller degrades the section to `unavailable`.
+    fn wardline_findings_for_path(
+        &self,
+        _path: &str,
+    ) -> Result<Vec<WardlineFinding>, FiligreeClientError> {
+        Ok(Vec::new())
+    }
+```
+
+- [ ] **Step 5: Implement the two-hop in the HTTP client**
+
+Add to `impl FiligreeLookup for FiligreeHttpClient`:
+
+```rust
+    fn wardline_findings_for_path(
+        &self,
+        path: &str,
+    ) -> Result<Vec<WardlineFinding>, FiligreeClientError> {
+        // Hop 1: path -> Filigree file_id. path_prefix is a prefix filter, so
+        // take only the row whose path is byte-exact.
+        let files: LoomFilesResponse =
+            self.get_json(&loom_files_url(&self.base_url, "wardline", path))?;
+        let Some(file_id) = files.items.into_iter().find(|f| f.path == path).map(|f| f.file_id)
+        else {
+            return Ok(Vec::new());
+        };
+        // Hop 2: file_id -> wardline findings.
+        let findings: WardlineFindingsResponse =
+            self.get_json(&loom_findings_url(&self.base_url, "wardline", &file_id))?;
+        Ok(findings.items)
+    }
+```
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `cargo nextest run -p clarion-mcp filigree::tests::wardline_findings_for_path filigree::tests::builds_loom_url`
+Expected: PASS (2 tests).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add crates/clarion-mcp/src/filigree.rs
+git commit -m "feat(mcp): Filigree two-hop wardline_findings_for_path (loom files + findings)"
+```
+
+---
+
+## Task 4: Wire the `wardline_findings` section into `issues_for`
+
+**Files:**
+- Modify: `crates/clarion-mcp/src/lib.rs` (`tool_issues_for`, ~line 1007–1126; add a helper `wardline_section_for_entity`; integration test in the lib.rs test module)
+
+- [ ] **Step 1: Write the failing integration tests**
+
+In the `lib.rs` test module, find the existing `FiligreeLookup` test double used by `issues_for` tests (search for `impl FiligreeLookup for`). Add a double that returns canned findings and one that errors, then:
+
+```rust
+#[tokio::test]
+async fn issues_for_attaches_exact_wardline_findings() {
+    // Build a server whose single entity is python:function:demo.hello at src/demo.py.
+    let server = issues_for_test_server_with_entity(
+        "python:function:demo.hello",
+        "src/demo.py",
+    );
+    let server = server.with_filigree_client(Arc::new(FakeWardline {
+        findings: vec![
+            wf("demo.hello", "WLN-TAINT-001"), // exact -> attached
+            wf("demo.other", "WLN-TAINT-002"), // different entity -> not attached
+            wf_no_qualname("WLN-METRIC-001"),  // omitted
+        ],
+    }));
+    let out = server.tool_issues_for(&args_id("python:function:demo.hello")).await.unwrap();
+    let section = &out["wardline_findings"];
+    assert_eq!(section["result_kind"], "matched");
+    assert_eq!(section["items"].as_array().unwrap().len(), 1);
+    assert_eq!(section["items"][0]["rule_id"], "WLN-TAINT-001");
+    assert_eq!(section["items"][0]["resolution_confidence"], "exact");
+    assert_eq!(section["omitted_no_qualname"], 1);
+}
+
+#[tokio::test]
+async fn issues_for_degrades_when_wardline_fetch_errors() {
+    let server = issues_for_test_server_with_entity("python:function:demo.hello", "src/demo.py")
+        .with_filigree_client(Arc::new(ErroringWardline));
+    let out = server.tool_issues_for(&args_id("python:function:demo.hello")).await.unwrap();
+    assert_eq!(out["wardline_findings"]["result_kind"], "unavailable");
+    assert!(out["wardline_findings"]["items"].as_array().unwrap().is_empty());
+}
+```
+
+Add the test doubles + helpers near the existing `issues_for` test doubles (adapt names to the existing harness — `issues_for_test_server_with_entity`, `args_id`, and a single-entity server builder will already exist or be trivially derived from the current `issues_for` tests; reuse them):
+
+```rust
+fn wf(qualname: &str, rule_id: &str) -> crate::filigree::WardlineFinding {
+    crate::filigree::WardlineFinding {
+        rule_id: rule_id.to_owned(),
+        message: "m".to_owned(),
+        severity: Some("high".to_owned()),
+        status: Some("open".to_owned()),
+        line_start: Some(1),
+        line_end: Some(1),
+        fingerprint: Some("fp".to_owned()),
+        file_id: Some("file-1".to_owned()),
+        metadata: serde_json::json!({ "wardline": { "qualname": qualname } }),
+    }
+}
+fn wf_no_qualname(rule_id: &str) -> crate::filigree::WardlineFinding {
+    let mut f = wf("x", rule_id);
+    f.metadata = serde_json::json!({ "wardline": { "kind": "METRIC" } });
+    f
+}
+
+struct FakeWardline { findings: Vec<crate::filigree::WardlineFinding> }
+impl crate::filigree::FiligreeLookup for FakeWardline {
+    fn associations_for(&self, _id: &str)
+        -> Result<crate::filigree::EntityAssociationsResponse, crate::filigree::FiligreeClientError> {
+        Ok(crate::filigree::EntityAssociationsResponse { associations: vec![] })
+    }
+    fn wardline_findings_for_path(&self, _path: &str)
+        -> Result<Vec<crate::filigree::WardlineFinding>, crate::filigree::FiligreeClientError> {
+        Ok(self.findings.clone())
+    }
+}
+
+struct ErroringWardline;
+impl crate::filigree::FiligreeLookup for ErroringWardline {
+    fn associations_for(&self, _id: &str)
+        -> Result<crate::filigree::EntityAssociationsResponse, crate::filigree::FiligreeClientError> {
+        Ok(crate::filigree::EntityAssociationsResponse { associations: vec![] })
+    }
+    fn wardline_findings_for_path(&self, _path: &str)
+        -> Result<Vec<crate::filigree::WardlineFinding>, crate::filigree::FiligreeClientError> {
+        Err(crate::filigree::FiligreeClientError::HttpStatus { status: 503, body: "down".to_owned() })
+    }
+}
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `cargo nextest run -p clarion-mcp issues_for_attaches_exact_wardline_findings issues_for_degrades_when_wardline_fetch_errors`
+Expected: FAIL — `out["wardline_findings"]` is null (section not built yet).
+
+- [ ] **Step 3: Add the section helper**
+
+Add a free function to `crates/clarion-mcp/src/lib.rs` (near the other envelope helpers, e.g. by `issues_unavailable`):
+
+```rust
+/// Build the `wardline_findings` enrich section for one entity. Enrich-only:
+/// a fetch error degrades to `result_kind: "unavailable"` rather than failing
+/// the tool.
+fn wardline_section_for_entity(
+    client: &std::sync::Arc<dyn crate::filigree::FiligreeLookup>,
+    entity_id: &str,
+    source_file_path: Option<&str>,
+) -> Value {
+    let Some(path) = source_file_path else {
+        return serde_json::json!({ "result_kind": "no_matches", "items": [], "omitted_no_qualname": 0 });
+    };
+    match client.wardline_findings_for_path(path) {
+        Ok(findings) => {
+            let result = crate::wardline_reconcile::reconcile_for_entity(entity_id, findings);
+            let items: Vec<Value> = result
+                .matched
+                .iter()
+                .map(|m| {
+                    serde_json::json!({
+                        "rule_id": m.finding.rule_id,
+                        "message": m.finding.message,
+                        "severity": m.finding.severity,
+                        "status": m.finding.status,
+                        "line_start": m.finding.line_start,
+                        "line_end": m.finding.line_end,
+                        "fingerprint": m.finding.fingerprint,
+                        "resolution_confidence": m.resolution_confidence,
+                    })
+                })
+                .collect();
+            let result_kind = if items.is_empty() { "no_matches" } else { "matched" };
+            serde_json::json!({
+                "result_kind": result_kind,
+                "items": items,
+                "omitted_no_qualname": result.omitted_no_qualname,
+            })
+        }
+        Err(err) => serde_json::json!({
+            "result_kind": "unavailable",
+            "items": [],
+            "omitted_no_qualname": 0,
+            "reason": err.to_string(),
+        }),
+    }
+}
+```
+
+- [ ] **Step 4: Call it from `tool_issues_for`**
+
+In `tool_issues_for`, after `accumulator.apply_issue_details(&details);` (line ~1119), build the envelope, then attach the section for the **requested** entity (the one whose `id` matches the `id` argument), running the blocking client call off-thread:
+
+```rust
+        let mut envelope = accumulator.into_envelope(
+            read.entity_cap_truncated,
+            requests_total,
+            detail_requests_total,
+            &endpoint,
+        );
+        // Flow B: attach Wardline findings reconciled to the requested entity.
+        if let Some(entity) = read.entities.iter().find(|e| e.id == read.requested_id) {
+            let client = client.clone();
+            let entity_id = entity.id.clone();
+            let path = entity.source_file_path.clone();
+            let section = tokio::task::spawn_blocking(move || {
+                wardline_section_for_entity(&client, &entity_id, path.as_deref())
+            })
+            .await
+            .unwrap_or_else(|err| serde_json::json!({
+                "result_kind": "unavailable", "items": [], "omitted_no_qualname": 0,
+                "reason": format!("wardline task failed: {err}"),
+            }));
+            if let Value::Object(map) = &mut envelope {
+                map.insert("wardline_findings".to_owned(), section);
+            }
+        }
+        Ok(envelope)
+```
+
+Note: if `read` exposes the requested id under a different field name than `requested_id`, use that; if it does not retain it, capture the `entity_id` argument into a local before the `read_issues_for_entities` call (it is `required_str(arguments, "id")?` at the top) and match on that local instead.
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `cargo nextest run -p clarion-mcp issues_for_attaches_exact_wardline_findings issues_for_degrades_when_wardline_fetch_errors`
+Expected: PASS (2 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/clarion-mcp/src/lib.rs
+git commit -m "feat(mcp): attach reconciled wardline_findings section to issues_for (Flow B)"
+```
+
+---
+
+## Task 5: Wire the section into `orientation_pack`
+
+**Files:**
+- Modify: `crates/clarion-mcp/src/lib.rs` (`tool_orientation_pack`; integration test)
+
+- [ ] **Step 1: Write the failing test**
+
+```rust
+#[tokio::test]
+async fn orientation_pack_includes_wardline_findings() {
+    let server = orientation_pack_test_server_with_entity("python:function:demo.hello", "src/demo.py")
+        .with_filigree_client(Arc::new(FakeWardline { findings: vec![wf("demo.hello", "WLN-TAINT-001")] }));
+    // orientation_pack resolves by file+line or entity; use the entity form.
+    let out = server.tool_orientation_pack(&args_entity("python:function:demo.hello")).await.unwrap();
+    assert_eq!(out["wardline_findings"]["result_kind"], "matched");
+    assert_eq!(out["wardline_findings"]["items"][0]["rule_id"], "WLN-TAINT-001");
+}
+```
+
+Reuse the `FakeWardline` / `wf` helpers from Task 4. `orientation_pack_test_server_with_entity` and `args_entity` mirror the existing `orientation_pack` test setup — derive them from the current orientation_pack tests.
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cargo nextest run -p clarion-mcp orientation_pack_includes_wardline_findings`
+Expected: FAIL — `wardline_findings` key absent from the pack.
+
+- [ ] **Step 3: Attach the section in `tool_orientation_pack`**
+
+Locate where `tool_orientation_pack` assembles its final `Value` (the packet with `entity`, neighbors, paths, issues, health). After the packet object is built and before returning, attach the section for the pack's primary entity — only when a Filigree client is configured (the pack runs on storage-only servers too):
+
+```rust
+        if let (Some(client), Some(primary)) = (self.filigree_client.clone(), primary_entity.as_ref()) {
+            let entity_id = primary.id.clone();
+            let path = primary.source_file_path.clone();
+            let section = tokio::task::spawn_blocking(move || {
+                wardline_section_for_entity(&client, &entity_id, path.as_deref())
+            })
+            .await
+            .unwrap_or_else(|err| serde_json::json!({
+                "result_kind": "unavailable", "items": [], "omitted_no_qualname": 0,
+                "reason": format!("wardline task failed: {err}"),
+            }));
+            if let Value::Object(map) = &mut packet {
+                map.insert("wardline_findings".to_owned(), section);
+            }
+        }
+```
+
+Adapt `primary_entity` / `packet` to the actual local variable names in `tool_orientation_pack` (the primary `EntityRow` and the mutable packet `Value`). If the packet is built as an immutable `json!({...})`, bind it to `let mut packet = ...;` first.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `cargo nextest run -p clarion-mcp orientation_pack_includes_wardline_findings`
+Expected: PASS.
+
+- [ ] **Step 5: Run the full crate gate**
+
+```bash
+cargo fmt --all -- --check
+cargo clippy -p clarion-mcp --all-targets -- -D warnings
+cargo nextest run -p clarion-mcp
+```
+Expected: all green.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/clarion-mcp/src/lib.rs
+git commit -m "feat(mcp): attach reconciled wardline_findings section to orientation_pack (Flow B)"
+```
+
+---
+
+## Task 6: Pin the consumed routes in the federation contract
+
+**Files:**
+- Modify: `docs/federation/contracts.md` (new "Consumed Filigree route" subsection after the issue-detail one, ~line 406+)
+
+- [ ] **Step 1: Add the contract section**
+
+Append after the existing "Consumed Filigree route: issue detail (enrichment)" section:
+
+````markdown
+## Consumed Filigree route: Wardline findings (read-time reconciliation)
+
+Flow B (read-time Wardline finding reconciliation) consumes two existing Filigree
+*loom* read routes — no new route is requested. Both are enrich-only: if either
+is unreachable the `wardline_findings` section degrades to
+`result_kind: "unavailable"` and the tool returns normally.
+
+1. `GET /api/loom/files?scan_source=wardline&path_prefix=<rel-path>` → unified
+   `ListResponse[FileRecordLoom]` (`{items, has_more, next_offset?}`). Clarion
+   takes the item whose `path` is byte-exact (the filter is a prefix) to obtain
+   Filigree's `file_id`. Pinned by Filigree `tests/fixtures/contracts/loom/files.json`.
+2. `GET /api/loom/findings?scan_source=wardline&file_id=<file_id>` →
+   `ListResponse[ScanFindingLoom]`. Clarion reads `rule_id`, `message`,
+   `severity`, `status`, `line_start/line_end`, `fingerprint`, and `metadata`
+   (the reconciliation key `metadata.wardline.qualname`). Pinned by Filigree
+   `tests/fixtures/contracts/loom/findings.json`.
+
+Reconciliation: `metadata.wardline.qualname` is matched byte-exact against the
+entity_id's segment-3 `canonical_qualified_name` (`python:function:<qualname>`),
+per the §"Wardline qualname normalization" contract. A match is
+`resolution_confidence: exact`; an unresolved qualname is `none`. (`heuristic` is
+reserved.) `POST /api/v1/files:resolve` is **not** used here — it is a route
+Clarion *exposes*, not one it consumes.
+````
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/federation/contracts.md
+git commit -m "docs(federation): pin the two consumed loom routes for Flow B reconciliation"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage** (against `2026-05-30-clarion-consume-wardline-data-design.md`):
+- §3 read-time lazy reconciliation → Tasks 2 (match), 4/5 (attach). ✓
+- §3 `resolution_confidence` tiers → Task 2 (`Exact`/`None`; `Heuristic` reserved, documented). ✓
+- §4 two-hop via existing loom routes → Task 3. ✓
+- §5 enrich-only / no fabrication / omitted count → Tasks 2 (omitted), 4 (degrade test + no_matches). ✓
+- §6 hermetic tests → injected `FakeWardline`/`ErroringWardline` (Tasks 4/5), mock TcpListener (Task 3). ✓
+- §10.3 pin consumed routes in contracts.md → Task 6. ✓
+- Kind handling (functions/methods only) → falls out of `entity_qualname` matching `python:function:` ids; class/module ids simply never match a function-qualname finding. Documented in Task 2 module doc. ✓
+
+**Placeholder scan:** No TBD/TODO; every code/test step carries real code and an exact `cargo nextest` command with expected result. The two adaptation notes (Task 4 `requested_id`, Task 5 `primary_entity`/`packet` names) are explicit fallback instructions, not placeholders.
+
+**Type consistency:** `WardlineFinding` (fields used identically in Tasks 1/2/3/4). `ResolutionConfidence` serializes lowercase → asserted as `"exact"` in Task 4. `reconcile_for_entity` / `ReconcileResult` / `MatchedFinding` consistent Task 2 → 4. `wardline_findings_for_path` signature identical in trait default (Task 3), HTTP impl (Task 3), and test doubles (Task 4). Section shape (`result_kind` / `items` / `omitted_no_qualname`) identical across the helper (Task 4), both call sites (Tasks 4/5), and the contract doc (Task 6).
+
+**Out of plan scope (tracker-only, per spec §7):** Flow A re-scope of `clarion-1f6241b329` / `clarion-22acf15fd7` — already recorded as comments; not a build task here.
diff --git a/docs/superpowers/specs/2026-05-30-clarion-consume-wardline-data-design.md b/docs/superpowers/specs/2026-05-30-clarion-consume-wardline-data-design.md
new file mode 100644
index 00000000..5e04787c
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-30-clarion-consume-wardline-data-design.md
@@ -0,0 +1,234 @@
+# Clarion consumes Wardline data — design
+
+**Date:** 2026-05-30
+**Status:** approved (brainstorm directive: "step up, Wardline drops today");
+deliverable is **spec + tracked issues** (design now, build next).
+**Scope decision:** both Wardline-consume flows. Flow B (read-time finding
+reconciliation) is designed in full here; Flow A (extraction-time NG-25 probe
+annotation) is re-scoped in the tracker and cross-referenced, not redesigned.
+**Builds on:** ADR-018 (qualname divergence / asterisk 2), ADR-015 (Wardline→
+Filigree emission), the federation contract `docs/federation/contracts.md`
+§"Wardline qualname normalization (entity reconciliation)", and Wardline SP4
+(Outputs + Loom Integration, 2026-05-30).
+
+---
+
+## 1. Problem
+
+Wardline SP4 ships a native Filigree emitter today: `POST /api/loom/scan-results`
+with `scan_source="wardline"`, each finding carrying `metadata.wardline.qualname`
+(the pre-composed dotted `module.qualified_name`, i.e. Clarion's L7
+`canonical_qualified_name`). SP4 §10 makes entity-association emission a Wardline
+**non-goal** — Wardline does **not** emit a Clarion `entity_id`.
+
+Clarion's only existing consume hook (`issues_for` / `orientation_pack`) is
+**entity_id-keyed**: `GET /api/entity-associations?entity_id=<id>` → then
+`GET /api/loom/issues/{id}`. Wardline findings are qualname-keyed with no
+`entity_id`, so nothing currently surfaces them on a Clarion entity. The
+`entities/resolve?scheme=wardline_qualname` oracle named in ADR-018 is deferred
+and unimplemented. The result is a consume-side blind spot the moment Wardline
+data starts landing in Filigree.
+
+There are two distinct flows under "consume Wardline data":
+
+- **Flow A — extraction-time annotation.** The Python plugin reads Wardline's
+  NG-25 descriptor at `clarion analyze` time and stamps each entity's reserved
+  `wardline` column (`crates/clarion-storage/migrations/0001_initial_schema.sql`,
+  `EntityRecord.wardline_json`). Today the probe
+  (`plugins/python/.../wardline_probe.py`) proves only the import/version
+  handshake; the column is all-`None`. Tracked as `clarion-1f6241b329` +
+  `clarion-22acf15fd7`.
+- **Flow B — read-time finding reconciliation.** Ingest the Wardline *findings*
+  SP4 emits into Filigree, reconcile `qualname → entity`, and surface them
+  through `issues_for` / `orientation_pack`. Unbuilt, untracked. **This is what
+  drops today**, and the primary subject of this spec.
+
+## 2. The simplifying insight
+
+`metadata.wardline.qualname` *is* Clarion's L7 `canonical_qualified_name`, which
+is literally **segment 3 of the entity_id** (`{plugin}:{kind}:{qualname}`, e.g.
+`python:function:pkg.mod.func`). So reconciling a Wardline finding to a Clarion
+entity is a **local lookup against Clarion's own catalog** — compose
+`python:function:<wardline.qualname>` and look it up — not a network round-trip
+to a resolve oracle. Clarion owns its catalog; it never needs to ask a sibling
+"does this qualname resolve?". This removes the largest piece of perceived work
+and keeps the matching logic (and the documented divergence traps) on the side
+that owns the truth.
+
+## 3. Flow B design — read-time lazy reconciliation
+
+Enrich-only, parallel to the existing entity-association lookup, invoked when
+`issues_for` / `orientation_pack` runs for an entity **E** (qualname `Q`, file
+`F`):
+
+1. **Fetch** Wardline findings *scoped by file `F`* from Filigree (see §4).
+2. **Resolve each finding to an entity, locally.** For each fetched finding,
+   normalize its `metadata.wardline.qualname` and look it up in Clarion's catalog
+   (a pure string compare — no network). Tag the finding with how it resolved:
+   - `exact` — qualname matches an indexed entity. Bind the finding to that
+     entity.
+   - `heuristic` — qualname does not match an indexed entity exactly but a
+     best-effort normalization resolves to one. Bind with lowered confidence.
+   - `none` — resolves to no indexed entity (the file matched, the symbol did
+     not). File-level only; not entity-bound.
+3. **Attach.** For a query on entity E, surface the findings that resolved
+   (`exact` or `heuristic`) **to E** under a new `wardline_findings` section:
+   `rule_id`, `message`, `severity`, `line_start/end`, `fingerprint`, `status`,
+   the `metadata.wardline.*` block (kind, confidence, suppression), and the
+   finding's `resolution_confidence`. Findings in `F` that resolved to a
+   *different* entity belong to that entity (not E); `none` findings are
+   available as file-level context, never bound to E.
+
+This mirrors the existing `issues_for` enrich-only behavior exactly: Filigree is
+an enrichment source, never load-bearing.
+
+### Kind handling & divergence traps
+
+Compose `python:function:<qualname>`. Wardline emits **functions/methods only**
+(SP4 §6); methods carry dotted qualnames and remain `kind=function`. Class- and
+module-targeted findings are **out of scope in v1** (Wardline does not emit them)
+— a documented limitation, not a silent drop. Matching honors the normative
+divergence traps from `fixtures/wardline-qualname-normalization.json`: `None ↔ ""`
+for a rejected top-level `__init__.py`, non-`src` roots not stripped, `src` only
+stripped at position 0, `<locals>` closure markers and nested-class chains
+preserved verbatim.
+
+## 4. Data source — composed from existing Filigree routes (no new contract)
+
+**Verified against Filigree source (2026-05-30): no new Filigree route is
+needed.** Flow B composes two existing Filigree *loom* read routes. (Note: the
+`POST /api/v1/files:resolve` route in `contracts.md` is a route **Clarion
+exposes** — it returns *Clarion* entity_ids for paths — not a Filigree route
+Clarion consumes; it is the wrong direction for this and is not used here.)
+
+1. **`GET /api/loom/files?scan_source=wardline&path_prefix=<E.source_file_path>`**
+   — `api_loom_list_files` (`filigree/dashboard_routes/files.py`); filters
+   include `scan_source` and `path_prefix`. Returns `FileRecordLoom` items
+   carrying `file_id` + `path`. Clarion takes the item whose `path` **exactly**
+   equals `E.source_file_path` (`path_prefix` is a prefix, so an exact-match
+   filter is required) → Filigree `file_id`. Pinned by
+   `tests/fixtures/contracts/loom/files.json`.
+2. **`GET /api/loom/findings?scan_source=wardline&file_id=<file_id>`** —
+   `api_loom_list_findings`; filters include `scan_source`, `status`, `file_id`.
+   Each row is a `ScanFindingLoom` carrying `rule_id`, `message`, `severity`,
+   `status`, `line_start/line_end`, `fingerprint`, `file_id`, and **`metadata`**
+   (where `metadata.wardline.qualname` lives). Pinned by
+   `tests/fixtures/contracts/loom/findings.json`.
+
+So the fetch is: `loom/files?path_prefix=<path>` → exact-path match → `file_id`,
+then `loom/findings?scan_source=wardline&file_id=<id>`, then the local qualname
+match in §3. `ScanFindingLoom` rows reference the file by `file_id` (not `path`),
+which is why the file-list hop is required; file-scoping also keeps each query
+bounded rather than sweeping all project findings.
+
+This is **Clarion-side build only** — the MCP Filigree client (`filigree.rs`)
+gains a loom-files-list call and a loom-findings-list call; no Filigree-side work,
+and **no federation contract request** (both routes already exist — checked
+against Filigree source, not assumed; cf. the withdrawn prune ask in `7a93883`).
+Enrich-only still holds: if either route is unreachable, the `wardline_findings`
+section degrades to empty + `degraded`.
+
+## 5. Error handling (enrich-only, no fabrication)
+
+- **Filigree absent / unreachable** → degrade to an empty `wardline_findings`
+  section flagged `degraded`; the tool never fails. `result_kind` distinguishes
+  `matched` / `no_matches` / `unavailable`, so a reachable-but-empty Filigree is
+  never confused with an unreachable one (existing `issues_for` discipline).
+- **Malformed finding** (missing/empty `metadata.wardline.qualname`, or a
+  qualname that fails normalization) → skip it, increment a count in an
+  `omitted` block; never crash the tool.
+- **No fabrication.** An empty section is reported as empty with its cause, in
+  keeping with the `scope_excludes` / `degraded` discipline already used across
+  the MCP surface.
+
+## 6. Testing (hermetic)
+
+Unit tests with an **injected Filigree transport** returning canned Wardline
+findings — no live server in the unit suite:
+
+- qualname match including every divergence trap (`None ↔ ""`, non-`src` roots,
+  `<locals>`, nested-class chains);
+- the three `resolution_confidence` tiers (`exact` / `heuristic` / `none`);
+- enrich-only degradation: transport error → `degraded`, tool returns, no panic;
+- no-fabrication: reachable-but-empty → `no_matches`, not a synthesized entry;
+- malformed-metadata finding → skipped + counted in `omitted`.
+
+An optional live e2e (against an already-running Filigree) is out of the unit
+suite.
+
+## 7. Flow A coordination (re-scope, not redesigned here)
+
+Per Wardline SP4 §2, Wardline now **emits** the NG-25 descriptor (SP2d shipped),
+but Clarion's **reader** is unbuilt and the plugin still imports
+`wardline.core.registry` directly. The external blocker on `clarion-1f6241b329`
+(*"Wardline SP2 finalizing the NG-25 descriptor shape"*) has therefore **lifted**
+— it is now actionable Clarion work (build the descriptor reader; populate the
+`wardline` column at `analyze` time), no longer gated on Wardline.
+
+Action (tracker only, this session): update `clarion-1f6241b329` and
+`clarion-22acf15fd7` to record the descriptor ship, remove the "blocked on
+Wardline" framing, and cross-reference the two flows as one Wardline-enrichment
+story — extraction-time annotation (`wardline` column) and read-time findings
+(this spec) feed the same goal from opposite ends. Flow A keeps its own design
+when it is built.
+
+## 8. Non-goals
+
+- No `entities/resolve?scheme=wardline_qualname` oracle (deferred; Clarion's
+  consume path matches locally, so the oracle is not on Flow B's critical path).
+- No entity-association write-back to Filigree (ADR-029) — Approach 2 from the
+  brainstorm was rejected; Flow B is read-time-only, no Clarion-initiated mutation
+  of Filigree state.
+- No class/module-targeted Wardline findings (Wardline emits functions/methods).
+- No Flow A implementation in this spec (re-scope only).
+- No new runtime dependency — reuses the existing Filigree HTTP client in
+  `crates/clarion-mcp/src/filigree.rs`.
+
+## 9. Risks
+
+- **R1 — sibling-route shape drift.** Both consumed routes (`files:resolve`,
+  `GET /api/loom/findings`) exist today (verified), but their wire shape could
+  drift. Mitigated by pinning the consumed shapes in
+  `docs/federation/contracts.md` against Filigree's normative fixtures
+  (`tests/fixtures/contracts/loom/findings.json`) and testing the client against
+  that fixture, not a guess. No new route is requested, so there is no
+  ahead-of-build dependency to land.
+- **R2 — qualname mismatch surfaced as silent miss.** A producer divergence
+  (Wardline composing a qualname Clarion can't match) degrades to
+  `resolution_confidence: none`. Mitigated by the shared normative fixture and by
+  surfacing `none`/`heuristic` counts rather than dropping them.
+- **R3 — enrich path inflating query latency.** A per-entity Filigree round-trip
+  on every `issues_for` / `orientation_pack`. Mitigated by file-scoped fetch
+  (one request per file, reusable across entities in that file) and the
+  enrich-only timeout/degrade already in the Filigree client.
+
+## 10. Deliverables (this session)
+
+1. This spec, committed.
+2. New `release:1.1` issue — **Flow B: read-time Wardline finding
+   reconciliation** — citing this spec, ADR-018, and contracts.md §reconciliation.
+   **Not** gated on any Filigree-side work (both consumed routes already exist);
+   it is straightforward Clarion-side build, sequenced whenever picked up.
+3. Pin the two consumed loom read routes (`GET /api/loom/files?scan_source=…&
+   path_prefix=…` for path→file_id, and `GET /api/loom/findings?scan_source=…&
+   file_id=…`) in `docs/federation/contracts.md` as part of the Flow B build.
+   **No** federation contract request is filed — the routes already exist
+   (verified against Filigree source), so a request would be moot (cf. the
+   withdrawn prune ask in `7a93883`).
+4. Re-scoped `clarion-1f6241b329` + `clarion-22acf15fd7` (Flow A unblock +
+   cross-reference).
+
+Any ADR minted from this work (e.g. an ADR-018 amendment pinning the read-time
+consume mechanism) is kept under `docs/clarion/adr/` per the editorial
+conventions, authored when the decision locks at build time.
+
+## 11. References
+
+- ADR-018 — L7 qualname divergence with Wardline FingerprintEntry (asterisk 2).
+- ADR-015 (Revision 2) — Wardline→Filigree native emission.
+- `docs/federation/contracts.md` §"Wardline qualname normalization (entity
+  reconciliation)" and §"Consumed Filigree route: issue detail (enrichment)".
+- `docs/federation/fixtures/wardline-qualname-normalization.json` — normative
+  qualname parity vectors.
+- Wardline SP4 — Outputs + Loom Integration (2026-05-30) §2, §6, §10.
+- `crates/clarion-mcp/src/filigree.rs` — existing enrich-only Filigree client.
diff --git a/plugins/python/plugin.toml b/plugins/python/plugin.toml
index add14c44..af282a43 100644
--- a/plugins/python/plugin.toml
+++ b/plugins/python/plugin.toml
@@ -1,7 +1,7 @@
 [plugin]
 name = "clarion-plugin-python"
 plugin_id = "python"
-version = "0.1.5"
+version = "1.0.0"
 protocol_version = "1.0"
 # Bare basename per ADR-021 §Layer 1 + WP2 scrub commit eb0a41d — the host
 # refuses manifests whose `executable` carries any path component.
diff --git a/plugins/python/pyproject.toml b/plugins/python/pyproject.toml
index d7ff461b..7c9e0851 100644
--- a/plugins/python/pyproject.toml
+++ b/plugins/python/pyproject.toml
@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "clarion-plugin-python"
-version = "0.1.5"
-description = "Clarion Python language plugin — walking-skeleton v0.1 baseline"
+version = "1.0.0"
+description = "Clarion Python language plugin — v1.0 release"
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [{ name = "John Morrissey", email = "qacona@gmail.com" }]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
diff --git a/plugins/python/src/clarion_plugin_python/__init__.py b/plugins/python/src/clarion_plugin_python/__init__.py
index 52a28586..02f103b4 100644
--- a/plugins/python/src/clarion_plugin_python/__init__.py
+++ b/plugins/python/src/clarion_plugin_python/__init__.py
@@ -1,3 +1,3 @@
 """clarion-plugin-python — Python language plugin for Clarion."""
 
-__version__ = "0.1.5"
+__version__ = "1.0.0"
diff --git a/plugins/python/src/clarion_plugin_python/extractor.py b/plugins/python/src/clarion_plugin_python/extractor.py
index 50d1f86e..4dce0123 100644
--- a/plugins/python/src/clarion_plugin_python/extractor.py
+++ b/plugins/python/src/clarion_plugin_python/extractor.py
@@ -97,6 +97,25 @@ class EntitySource(TypedDict):
     source_range: SourceRange
 
 
+class DefinitionSpan(TypedDict):
+    """Sub-ranges within a function/class entity (clarion-460def6a51).
+
+    ``decl_line`` is the line of the ``def``/``class`` keyword (Python 3.8+
+    ``node.lineno``). ``body_line_start`` is the line of the first body
+    statement (a docstring counts). The two ``decorator_*`` keys are present
+    only when the entity is decorated; ``decorator_line_start`` is the
+    topmost decorator line and matches the entity's expanded
+    ``source_range.start_line``. They let a reader explain *why* a given
+    line resolved to this entity (decorator vs declaration vs body) without
+    re-reading source.
+    """
+
+    decl_line: int
+    body_line_start: NotRequired[int]
+    decorator_line_start: NotRequired[int]
+    decorator_line_end: NotRequired[int]
+
+
 class RawEntity(TypedDict):
     """Wire shape matching the Rust host's RawEntity contract.
 
@@ -116,6 +135,10 @@ class RawEntity(TypedDict):
     source: EntitySource
     parent_id: NotRequired[str]
     parse_status: NotRequired[Literal["ok", "syntax_error"]]
+    # entity_context evidence (clarion-460def6a51). Set on function/class
+    # entities; omitted for modules. Rides the host's RawEntity `extra` flatten
+    # into `properties_json`, so no host or storage schema change is needed.
+    definition: NotRequired[DefinitionSpan]
 
 
 class RawEdge(TypedDict):
@@ -842,6 +865,36 @@ def _walk(  # noqa: PLR0913 - recursive walker needs both accumulators + parent
         )
 
 
+def _definition_span(
+    node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
+) -> tuple[int, int, DefinitionSpan]:
+    """Return ``(start_line, start_col, definition)`` for a definition node.
+
+    ``node.lineno`` is the ``def``/``class`` keyword line (Python 3.8+);
+    decorators sit above it. When the node is decorated the returned
+    ``start_line``/``start_col`` extend the entity span up to the topmost
+    decorator so an ``entity_at`` query on a decorator line resolves to this
+    entity (clarion-460def6a51). The ``definition`` map records the
+    sub-ranges that explain why a line matched.
+    """
+    definition: DefinitionSpan = {"decl_line": node.lineno}
+    if node.body:
+        definition["body_line_start"] = node.body[0].lineno
+    start_line = node.lineno
+    start_col = node.col_offset
+    if node.decorator_list:
+        topmost = min(node.decorator_list, key=lambda d: (d.lineno, d.col_offset))
+        decorator_line_start = topmost.lineno
+        decorator_line_end = max(
+            (d.end_lineno if d.end_lineno is not None else d.lineno) for d in node.decorator_list
+        )
+        definition["decorator_line_start"] = decorator_line_start
+        definition["decorator_line_end"] = decorator_line_end
+        start_line = decorator_line_start
+        start_col = topmost.col_offset
+    return start_line, start_col, definition
+
+
 def _contains_edge(parent_id: str, child_id: str) -> RawEdge:
     """Build a ``contains`` edge per ADR-026 decision 3 (no source range)."""
     return {
@@ -862,6 +915,7 @@ def _build_function_entity(
     qualified_name = f"{dotted_module}.{python_qualname}" if dotted_module else python_qualname
     end_line = node.end_lineno if node.end_lineno is not None else node.lineno
     end_col = node.end_col_offset if node.end_col_offset is not None else node.col_offset
+    start_line, start_col, definition = _definition_span(node)
     child_id = entity_id(_PLUGIN_ID, "function", qualified_name)
     entity: RawEntity = {
         "id": child_id,
@@ -870,13 +924,14 @@ def _build_function_entity(
         "source": {
             "file_path": file_path,
             "source_range": {
-                "start_line": node.lineno,
-                "start_col": node.col_offset,
+                "start_line": start_line,
+                "start_col": start_col,
                 "end_line": end_line,
                 "end_col": end_col,
             },
         },
         "parent_id": parent_entity_id,
+        "definition": definition,
     }
     return entity, child_id
 
@@ -899,6 +954,7 @@ def _build_class_entity(
     qualified_name = f"{dotted_module}.{python_qualname}" if dotted_module else python_qualname
     end_line = node.end_lineno if node.end_lineno is not None else node.lineno
     end_col = node.end_col_offset if node.end_col_offset is not None else node.col_offset
+    start_line, start_col, definition = _definition_span(node)
     child_id = entity_id(_PLUGIN_ID, "class", qualified_name)
     entity: RawEntity = {
         "id": child_id,
@@ -907,12 +963,13 @@ def _build_class_entity(
         "source": {
             "file_path": file_path,
             "source_range": {
-                "start_line": node.lineno,
-                "start_col": node.col_offset,
+                "start_line": start_line,
+                "start_col": start_col,
                 "end_line": end_line,
                 "end_col": end_col,
             },
         },
         "parent_id": parent_entity_id,
+        "definition": definition,
     }
     return entity, child_id
diff --git a/plugins/python/src/clarion_plugin_python/pyright_session.py b/plugins/python/src/clarion_plugin_python/pyright_session.py
index b7909d4c..3e6ca295 100644
--- a/plugins/python/src/clarion_plugin_python/pyright_session.py
+++ b/plugins/python/src/clarion_plugin_python/pyright_session.py
@@ -40,11 +40,41 @@
 FINDING_PYRIGHT_REFERENCE_RESOLUTION_TIMEOUT = "CLA-PY-REFERENCE-RESOLUTION-TIMEOUT"
 FINDING_PYRIGHT_REFERENCE_SITE_CAP = "CLA-PY-REFERENCE-SITE-CAP"
 
+
+@dataclass
+class PyrightRunState:
+    """Run-wide pyright health budget, shared across session recycles.
+
+    A ``PyrightSession`` is recycled every ``MAX_FILES_PER_PYRIGHT_SESSION``
+    files to bound memory growth. Without a shared budget the 3-restart cap
+    resets at every recycle boundary, letting a crash-looping pyright silently
+    consume ``ceil(N/25) * 3`` restarts instead of 3 for an entire analysis
+    run. Pass the same ``PyrightRunState`` instance to every successive
+    ``PyrightSession`` so the budget is enforced across the full run.
+    """
+
+    restart_count: int = 0
+    disabled: bool = False
+
+
+MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512
 MAX_PYRIGHT_RESTARTS_PER_RUN = 3
 MAX_REFERENCE_SITES_PER_FILE = 2000
 PYRIGHT_INIT_TIMEOUT_SECS = 30.0
 PYRIGHT_CALL_TIMEOUT_SECS = 5.0
+PYRIGHT_FILE_TIMEOUT_SECS = 3.0
 STDERR_TAIL_LIMIT = 65536
+PYRIGHT_EXCLUDE_PATTERNS = [
+    "**/.clarion/**",
+    "**/.git/**",
+    "**/.hg/**",
+    "**/.svn/**",
+    "**/.jj/**",
+    "**/.venv/**",
+    "**/__pycache__/**",
+    "**/node_modules/**",
+]
+PROJECT_LOCAL_EXTERNAL_DIRS = {".clarion", ".git", ".hg", ".svn", ".jj", ".venv", "node_modules"}
 
 
 if TYPE_CHECKING:
@@ -125,8 +155,10 @@ def __init__(  # noqa: PLR0913 - knobs are tested lifecycle boundaries.
         install_check: Callable[[str], bool] | None = None,
         init_timeout_secs: float = PYRIGHT_INIT_TIMEOUT_SECS,
         call_timeout_secs: float = PYRIGHT_CALL_TIMEOUT_SECS,
+        file_timeout_secs: float = PYRIGHT_FILE_TIMEOUT_SECS,
         max_restarts_per_run: int = MAX_PYRIGHT_RESTARTS_PER_RUN,
         max_reference_sites_per_file: int = MAX_REFERENCE_SITES_PER_FILE,
+        run_state: PyrightRunState | None = None,
     ) -> None:
         self.project_root = Path(project_root).resolve()
         self.executable = executable
@@ -134,17 +166,22 @@ def __init__(  # noqa: PLR0913 - knobs are tested lifecycle boundaries.
         self.install_check = install_check
         self.init_timeout_secs = init_timeout_secs
         self.call_timeout_secs = call_timeout_secs
+        self.file_timeout_secs = file_timeout_secs
         self.max_restarts_per_run = max_restarts_per_run
         self.max_reference_sites_per_file = max_reference_sites_per_file
+        # Run-wide health budget: shared across session recycles when the caller
+        # passes an explicit ``run_state``; isolated (per-instance) otherwise,
+        # which preserves the existing contract for code that constructs
+        # ``PyrightSession`` directly without going through ``ServerState``.
+        self._run_state = run_state if run_state is not None else PyrightRunState()
         self._process: subprocess.Popen[bytes] | None = None
         self._stderr_thread: threading.Thread | None = None
         self._stderr_tail = bytearray()
         self._next_id = 1
-        self._restart_count = 0
-        self._disabled = False
         self._findings: list[Finding] = []
         self._function_indexes: dict[Path, _FunctionIndex] = {}
         self._index_parse_latency_ms: list[int] = []
+        self._file_deadlines: dict[Path, float] = {}
 
     def __enter__(self) -> Self:
         return self
@@ -204,9 +241,15 @@ def resolve_calls(
                 findings=self._pop_findings(),
             )
 
+        deadline = self._deadline_for_file(path)
         latency_started = time.perf_counter()
         try:
-            edges, unresolved, unresolved_sites = self._resolve_with_pyright(path, index, requested)
+            edges, unresolved, unresolved_sites = self._resolve_with_pyright(
+                path,
+                index,
+                requested,
+                deadline,
+            )
         except LspTimeoutError as exc:
             self._record_finding(
                 FINDING_PYRIGHT_CALL_RESOLUTION_TIMEOUT,
@@ -267,12 +310,14 @@ def resolve_references(
                 findings=self._pop_findings(),
             )
 
+        deadline = self._deadline_for_file(path)
         latency_started = time.perf_counter()
         try:
             edges, resolved, skipped_external, unresolved = self._resolve_references_with_pyright(
                 path,
                 index,
                 sites,
+                deadline,
             )
         except LspTimeoutError as exc:
             self._record_finding(
@@ -290,6 +335,8 @@ def resolve_references(
             resolved = 0
             skipped_external = 0
             unresolved = reference_sites_total
+        finally:
+            self._file_deadlines.pop(path, None)
         latency_ms = max(1, math.ceil((time.perf_counter() - latency_started) * 1000))
 
         return ReferenceResolutionResult(
@@ -308,6 +355,7 @@ def _resolve_with_pyright(
         path: Path,
         index: _FunctionIndex,
         functions: Sequence[_FunctionInfo],
+        deadline: float,
     ) -> tuple[list[CallsRawEdge], int, list[UnresolvedCallSite]]:
         uri = path.as_uri()
         self._notify(
@@ -326,6 +374,7 @@ def _resolve_with_pyright(
             unresolved_total = 0
             unresolved_sites: list[UnresolvedCallSite] = []
             for function in functions:
+                self._ensure_file_budget(deadline)
                 grouped: dict[tuple[int, int, int, int], set[str]] = {}
                 prepared = self._request(
                     "textDocument/prepareCallHierarchy",
@@ -333,14 +382,15 @@ def _resolve_with_pyright(
                         "textDocument": {"uri": uri},
                         "position": {"line": function.line, "character": function.character},
                     },
-                    self.call_timeout_secs,
+                    self._budgeted_timeout(deadline),
                 )
                 items = prepared if isinstance(prepared, list) else []
                 for item in items:
+                    self._ensure_file_budget(deadline)
                     outgoing = self._request(
                         "callHierarchy/outgoingCalls",
                         {"item": item},
-                        self.call_timeout_secs,
+                        self._budgeted_timeout(deadline),
                     )
                     calls = outgoing if isinstance(outgoing, list) else []
                     for call in calls:
@@ -386,7 +436,10 @@ def _resolve_with_pyright(
                     function,
                     set(grouped),
                 )
-                unresolved_total += len(function_unresolved_sites)
+                unresolved_total += _unresolved_call_site_total_for_function(
+                    function,
+                    set(grouped),
+                )
                 unresolved_sites.extend(function_unresolved_sites)
             return edges, unresolved_total, unresolved_sites
         finally:
@@ -397,6 +450,7 @@ def _resolve_references_with_pyright(
         path: Path,
         index: _FunctionIndex,
         sites: Sequence[ReferenceSite],
+        deadline: float,
     ) -> tuple[list[ReferencesRawEdge], int, int, int]:
         uri = path.as_uri()
         self._notify(
@@ -417,17 +471,30 @@ def _resolve_references_with_pyright(
             resolved_total = 0
             skipped_external_total = 0
             unresolved_total = 0
-            for site in sites:
+            for site_index, site in enumerate(sites):
+                if self._file_budget_expired(deadline):
+                    unresolved_total += len(sites) - site_index
+                    self._record_finding(
+                        FINDING_PYRIGHT_REFERENCE_RESOLUTION_TIMEOUT,
+                        "pyright reference query timed out: analyze_file budget",
+                        method="analyze_file budget",
+                    )
+                    break
                 cache_key = _reference_lookup_cache_key(site, source_bytes)
                 cached = lookup_cache.get(cache_key)
                 if cached is None:
                     try:
-                        candidate_ids, saw_external = self._reference_target_ids(uri, site)
+                        candidate_ids, saw_external = self._reference_target_ids(
+                            uri,
+                            site,
+                            deadline=deadline,
+                        )
                         if not candidate_ids and site.kind == "annotation" and not saw_external:
                             candidate_ids, fallback_external = self._reference_target_ids(
                                 uri,
                                 site,
                                 method="textDocument/typeDefinition",
+                                deadline=deadline,
                             )
                             saw_external = saw_external or fallback_external
                     except LspTimeoutError as exc:
@@ -469,6 +536,7 @@ def _reference_target_ids(
         uri: str,
         site: ReferenceSite,
         *,
+        deadline: float,
         method: str = "textDocument/definition",
     ) -> tuple[list[str], bool]:
         result = self._request(
@@ -477,10 +545,31 @@ def _reference_target_ids(
                 "textDocument": {"uri": uri},
                 "position": {"line": site.line, "character": site.character},
             },
-            self.call_timeout_secs,
+            self._budgeted_timeout(deadline),
         )
         return self._target_ids_from_locations(result)
 
+    def _deadline_for_file(self, path: Path) -> float:
+        return self._file_deadlines.setdefault(
+            path,
+            time.monotonic() + self.file_timeout_secs,
+        )
+
+    def _budgeted_timeout(self, deadline: float) -> float:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            method = "analyze_file budget"
+            raise LspTimeoutError(method)
+        return min(self.call_timeout_secs, remaining)
+
+    def _ensure_file_budget(self, deadline: float) -> None:
+        if self._file_budget_expired(deadline):
+            method = "analyze_file budget"
+            raise LspTimeoutError(method)
+
+    def _file_budget_expired(self, deadline: float) -> bool:
+        return deadline - time.monotonic() <= 0
+
     def _target_ids_from_locations(self, result: object) -> tuple[list[str], bool]:
         locations = result if isinstance(result, list) else [result]
         candidate_ids: set[str] = set()
@@ -507,7 +596,7 @@ def _target_id_from_location(self, location: object) -> tuple[str | None, bool]:
         target_path = _path_from_uri(raw_uri)
         if target_path is None:
             return None, False
-        if not target_path.is_relative_to(self.project_root):
+        if not self._is_internal_project_path(target_path):
             return None, True
         target_index = self._function_index_for_path(target_path)
         key = _range_start_key(raw_range)
@@ -516,7 +605,7 @@ def _target_id_from_location(self, location: object) -> tuple[str | None, bool]:
         return target_index.module_id, False
 
     def _ensure_process(self) -> bool:
-        if self._disabled:
+        if self._run_state.disabled:
             return False
         if self._process is None:
             return self._start_process()
@@ -524,32 +613,32 @@ def _ensure_process(self) -> bool:
             return True
         self._process = None
         self._record_restart_or_poison("pyright subprocess exited")
-        if self._disabled:
+        if self._run_state.disabled:
             return False
         return self._start_process()
 
     def _record_restart_or_poison(self, reason: str) -> None:
-        self._restart_count += 1
-        if self._restart_count > self.max_restarts_per_run:
-            self._disabled = True
+        self._run_state.restart_count += 1
+        if self._run_state.restart_count > self.max_restarts_per_run:
+            self._run_state.disabled = True
             self._record_finding(
                 FINDING_PYRIGHT_POISON_FRAME,
                 "pyright restart cap exceeded; skipping call resolution",
-                restart_count=self._restart_count,
+                restart_count=self._run_state.restart_count,
                 reason=reason,
             )
             return
         self._record_finding(
             FINDING_PYRIGHT_RESTART,
             "pyright subprocess died and was restarted",
-            restart_count=self._restart_count,
+            restart_count=self._run_state.restart_count,
             reason=reason,
         )
 
     def _start_process(self) -> bool:
         executable = self._resolve_executable()
         if executable is None:
-            self._disabled = True
+            self._run_state.disabled = True
             self._record_finding(
                 FINDING_PYRIGHT_UNAVAILABLE,
                 "pyright-langserver is not available",
@@ -557,7 +646,7 @@ def _start_process(self) -> bool:
             )
             return False
         if self.install_check is not None and not self.install_check(executable):
-            self._disabled = True
+            self._run_state.disabled = True
             self._record_finding(
                 FINDING_PYRIGHT_INSTALL_FAILURE,
                 "pyright-langserver executability check failed",
@@ -575,7 +664,7 @@ def _start_process(self) -> bool:
                 stderr=subprocess.PIPE,
             )
         except OSError as exc:
-            self._disabled = True
+            self._run_state.disabled = True
             self._record_finding(
                 FINDING_PYRIGHT_INSTALL_FAILURE,
                 "pyright-langserver failed to start",
@@ -589,7 +678,7 @@ def _start_process(self) -> bool:
         try:
             self._initialize()
         except LspTimeoutError:
-            self._disabled = True
+            self._run_state.disabled = True
             self._record_finding(
                 FINDING_PYRIGHT_INIT_TIMEOUT,
                 "pyright initialize handshake timed out",
@@ -599,7 +688,7 @@ def _start_process(self) -> bool:
             process.wait(timeout=2)
             return False
         except (LspTransportClosedError, BrokenPipeError, OSError) as exc:
-            self._disabled = True
+            self._run_state.disabled = True
             self._record_finding(
                 FINDING_PYRIGHT_UNAVAILABLE,
                 "pyright initialize handshake failed",
@@ -620,7 +709,7 @@ def _initialize(self) -> None:
                 "workspaceFolders": [
                     {"uri": self.project_root.as_uri(), "name": self.project_root.name},
                 ],
-                "capabilities": {},
+                "capabilities": {"workspace": {"configuration": True}},
                 "clientInfo": {"name": "clarion-plugin-python", "version": __version__},
             },
             self.init_timeout_secs,
@@ -675,6 +764,9 @@ def _request(self, method: str, params: dict[str, object], timeout_secs: float)
         )
         while True:
             response = self._read_message(timeout_secs)
+            if "method" in response:
+                self._handle_server_message(response)
+                continue
             if response.get("id") != request_id:
                 continue
             if "error" in response:
@@ -682,6 +774,40 @@ def _request(self, method: str, params: dict[str, object], timeout_secs: float)
             process.poll()
             return response.get("result")
 
+    def _handle_server_message(self, message: dict[str, Any]) -> None:
+        if "id" not in message:
+            return
+        request_id = message["id"]
+        method = message.get("method")
+        if method == "workspace/configuration":
+            result = self._workspace_configuration_result(message)
+        else:
+            result = None
+        self._write_message({"jsonrpc": "2.0", "id": request_id, "result": result})
+
+    def _workspace_configuration_result(self, message: dict[str, Any]) -> list[object]:
+        params = message.get("params")
+        items = params.get("items") if isinstance(params, dict) else None
+        if not isinstance(items, list):
+            return []
+        return [self._configuration_for_section(item) for item in items]
+
+    def _configuration_for_section(self, item: object) -> object:
+        section = item.get("section") if isinstance(item, dict) else None
+        analysis = {
+            "diagnosticMode": "openFilesOnly",
+            "exclude": PYRIGHT_EXCLUDE_PATTERNS,
+            "indexing": False,
+            "useLibraryCodeForTypes": False,
+        }
+        if section == "python":
+            return {"analysis": analysis}
+        if section == "python.analysis":
+            return analysis
+        if section == "pyright":
+            return {}
+        return None
+
     def _notify(self, method: str, params: dict[str, object]) -> None:
         self._live_process()
         self._write_message({"jsonrpc": "2.0", "method": method, "params": params})
@@ -720,6 +846,9 @@ def _read_message(self, timeout_secs: float) -> dict[str, Any]:
                 raise LspTransportClosedError(message)
             name, value = line.decode("ascii").strip().split(":", 1)
             headers[name.lower()] = value.strip()
+        if "content-length" not in headers:
+            message = f"missing LSP Content-Length header: {headers!r}"
+            raise LspTransportClosedError(message)
         length = int(headers["content-length"])
         body = _read_exact(fd, length, deadline)
         parsed: dict[str, Any] = json.loads(body)
@@ -736,7 +865,7 @@ def _target_id_from_call(self, call: dict[object, object]) -> str | None:
         target_path = _path_from_uri(raw_uri)
         if target_path is None:
             return None
-        if not target_path.is_relative_to(self.project_root):
+        if not self._is_internal_project_path(target_path):
             return None
         index = self._function_index_for_path(target_path)
         key = _range_start_key(raw_selection)
@@ -744,6 +873,12 @@ def _target_id_from_call(self, call: dict[object, object]) -> str | None:
             return index.by_name_position[key].entity_id
         return _containing_function_id(index, raw_selection)
 
+    def _is_internal_project_path(self, path: Path) -> bool:
+        if not path.is_relative_to(self.project_root):
+            return False
+        relative = path.relative_to(self.project_root)
+        return not any(part in PROJECT_LOCAL_EXTERNAL_DIRS for part in relative.parts)
+
     def _function_index_for_path(self, path: Path) -> _FunctionIndex:
         resolved = path.resolve()
         cached = self._function_indexes.get(resolved)
@@ -965,6 +1100,23 @@ def _function_call_sites(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[_
     return visitor.call_sites
 
 
+def _unresolved_call_site_total_for_function(
+    function: _FunctionInfo,
+    resolved_ranges: set[tuple[int, int, int, int]],
+) -> int:
+    return sum(
+        1
+        for call_site in function.call_sites
+        if (
+            call_site.line,
+            call_site.character,
+            call_site.end_line,
+            call_site.end_character,
+        )
+        not in resolved_ranges
+    )
+
+
 def _unresolved_call_sites_for_function(
     index: _FunctionIndex,
     function: _FunctionInfo,
@@ -980,6 +1132,8 @@ def _unresolved_call_sites_for_function(
         )
         if range_key in resolved_ranges:
             continue
+        if len(call_site.callee_expr.encode("utf-8")) > MAX_UNRESOLVED_CALLEE_EXPR_BYTES:
+            continue
         start_byte = _position_to_byte(index, call_site.line, call_site.character)
         end_byte = _position_to_byte(index, call_site.end_line, call_site.end_character)
         unresolved.append(
diff --git a/plugins/python/src/clarion_plugin_python/server.py b/plugins/python/src/clarion_plugin_python/server.py
index 912d9470..b24d4f4c 100644
--- a/plugins/python/src/clarion_plugin_python/server.py
+++ b/plugins/python/src/clarion_plugin_python/server.py
@@ -29,7 +29,7 @@
 
 from clarion_plugin_python import __version__
 from clarion_plugin_python.extractor import extract_with_stats
-from clarion_plugin_python.pyright_session import PyrightSession
+from clarion_plugin_python.pyright_session import PyrightRunState, PyrightSession
 from clarion_plugin_python.stdout_guard import install_stdio
 from clarion_plugin_python.wardline_probe import probe as wardline_probe
 
@@ -46,6 +46,7 @@
 # default (8 MiB) so the plugin never emits a frame the host would kill us
 # for. Oversize outbound payloads trip this before reaching the wire.
 MAX_CONTENT_LENGTH = 8 * 1024 * 1024
+MAX_FILES_PER_PYRIGHT_SESSION = 25
 
 # JSON-RPC 2.0 error codes (§5.1) plus LSP-style server extensions.
 _ERR_INVALID_REQUEST = -32600
@@ -66,6 +67,8 @@ class ServerState:
     shutdown_requested: bool = False
     project_root: Path | None = field(default=None)
     pyright: PyrightSession | None = field(default=None)
+    pyright_files_since_restart: int = 0
+    pyright_run_state: PyrightRunState = field(default_factory=PyrightRunState)
 
 
 def read_frame(stream: IO[bytes]) -> dict[str, Any] | None:
@@ -193,7 +196,10 @@ def handle_analyze_file(params: dict[str, Any], state: ServerState) -> dict[str,
         return {"entities": [], "edges": [], "stats": empty_stats}
     path = Path(file_path_raw)
     if state.pyright is None:
-        state.pyright = PyrightSession(state.project_root or path.parent)
+        state.pyright = PyrightSession(
+            state.project_root or path.parent,
+            run_state=state.pyright_run_state,
+        )
     try:
         source = path.read_text(encoding="utf-8")
     except (OSError, UnicodeDecodeError) as exc:
@@ -210,6 +216,11 @@ def handle_analyze_file(params: dict[str, Any], state: ServerState) -> dict[str,
         call_resolver=state.pyright,
         reference_resolver=state.pyright,
     )
+    state.pyright_files_since_restart += 1
+    if state.pyright_files_since_restart >= MAX_FILES_PER_PYRIGHT_SESSION:
+        state.pyright.close()
+        state.pyright = None
+        state.pyright_files_since_restart = 0
     stats = {
         "unresolved_call_sites_total": result.stats.unresolved_call_sites_total,
         "unresolved_call_sites": result.stats.unresolved_call_sites,
diff --git a/plugins/python/tests/test_extractor.py b/plugins/python/tests/test_extractor.py
index 76a9bfa4..2dda7fdb 100644
--- a/plugins/python/tests/test_extractor.py
+++ b/plugins/python/tests/test_extractor.py
@@ -84,7 +84,12 @@ def pyright_langserver() -> str:
         return str(venv_candidate)
     resolved = shutil.which("pyright-langserver")
     if resolved is None:
-        pytest.skip("pyright-langserver is not installed")
+        pytest.fail(
+            "pyright-langserver not found on PATH or in the active virtualenv. "
+            "It is a hard runtime dependency of clarion-plugin-python "
+            "(pyproject.toml `dependencies`); a missing executable means the "
+            "install is broken. Skipping these tests would mask a regression.",
+        )
     return resolved
 
 
@@ -738,6 +743,61 @@ def test_source_range_end_fields_populated() -> None:
     assert source_range["end_col"] >= 0
 
 
+def test_definition_metadata_undecorated_function() -> None:
+    """Undecorated entities carry decl/body sub-ranges but no decorator keys.
+
+    The span still starts at the ``def`` keyword line (entity_context
+    evidence, clarion-460def6a51).
+    """
+    entities, _ = extract("def f():\n    return 1\n", "d.py")
+    fn = next(e for e in entities if e["kind"] == "function")
+    assert fn["source"]["source_range"]["start_line"] == 1
+    definition = fn["definition"]
+    assert definition["decl_line"] == 1
+    assert definition["body_line_start"] == 2
+    assert "decorator_line_start" not in definition
+    assert "decorator_line_end" not in definition
+
+
+def test_definition_metadata_decorated_class_expands_span_to_decorator() -> None:
+    """A decorated class's span starts at the decorator line so an
+    ``entity_at`` query on that line resolves to the class; ``definition``
+    records the decorator range and the ``class`` declaration line.
+    """
+    source = "import dataclasses\n\n\n@dataclasses.dataclass\nclass Config:\n    retries: int = 3\n"
+    entities, _ = extract(source, "runtime.py")
+    cls = next(e for e in entities if e["kind"] == "class")
+    # Decorator on line 4, `class Config:` on line 5.
+    assert cls["source"]["source_range"]["start_line"] == 4
+    definition = cls["definition"]
+    assert definition["decorator_line_start"] == 4
+    assert definition["decorator_line_end"] == 4
+    assert definition["decl_line"] == 5
+    assert definition["body_line_start"] == 6
+
+
+def test_definition_metadata_decorated_function_expands_span() -> None:
+    source = "import functools\n\n\n@functools.cache\ndef compute():\n    return 1\n"
+    entities, _ = extract(source, "d.py")
+    fn = next(e for e in entities if e["kind"] == "function")
+    assert fn["source"]["source_range"]["start_line"] == 4
+    definition = fn["definition"]
+    assert definition["decorator_line_start"] == 4
+    assert definition["decl_line"] == 5
+
+
+def test_definition_metadata_multiple_decorators_uses_topmost() -> None:
+    source = "import functools\n\n@staticmethod\n@functools.cache\ndef compute():\n    return 1\n"
+    # Module-level function with two stacked decorators (lines 3 and 4).
+    entities, _ = extract(source, "d.py")
+    fn = next(e for e in entities if e["kind"] == "function")
+    assert fn["source"]["source_range"]["start_line"] == 3
+    definition = fn["definition"]
+    assert definition["decorator_line_start"] == 3
+    assert definition["decorator_line_end"] == 4
+    assert definition["decl_line"] == 5
+
+
 def test_module_source_range_no_trailing_newline() -> None:
     """File ending without `\\n` still produces correct end_line.
 
diff --git a/plugins/python/tests/test_package.py b/plugins/python/tests/test_package.py
index a1fe5820..e05d83c8 100644
--- a/plugins/python/tests/test_package.py
+++ b/plugins/python/tests/test_package.py
@@ -4,19 +4,43 @@
 
 import tomllib
 from pathlib import Path
+from typing import Any
 
 import clarion_plugin_python
 
 _PLUGIN_ROOT = Path(__file__).resolve().parents[1]
 
 
+def _read_toml(path: Path) -> dict[str, Any]:
+    return tomllib.loads(path.read_text(encoding="utf-8"))
+
+
 def test_package_version_matches_pyproject() -> None:
-    assert clarion_plugin_python.__version__ == "0.1.5"
+    assert clarion_plugin_python.__version__ == "1.0.0"
+
+
+def test_plugin_version_lockstep_across_pyproject_manifest_and_module() -> None:
+    """Guard against the version-drift class of bug (clarion-496a8192cc).
+
+    The three values must move together: bumping pyproject without bumping
+    plugin.toml ships an sdist whose handshake reports the wrong version.
+    """
+    pyproject = _read_toml(_PLUGIN_ROOT / "pyproject.toml")
+    manifest = _read_toml(_PLUGIN_ROOT / "plugin.toml")
+
+    pyproject_version = pyproject["project"]["version"]
+    manifest_version = manifest["plugin"]["version"]
+    module_version = clarion_plugin_python.__version__
+
+    assert pyproject_version == manifest_version == module_version, (
+        f"version drift: pyproject={pyproject_version!r}, "
+        f"plugin.toml={manifest_version!r}, __init__={module_version!r}"
+    )
 
 
 def test_manifest_declares_references_edge_kind() -> None:
-    manifest = tomllib.loads((_PLUGIN_ROOT / "plugin.toml").read_text(encoding="utf-8"))
+    manifest = _read_toml(_PLUGIN_ROOT / "plugin.toml")
 
-    assert manifest["plugin"]["version"] == "0.1.5"
+    assert manifest["plugin"]["version"] == "1.0.0"
     assert manifest["ontology"]["ontology_version"] == "0.6.0"
     assert manifest["ontology"]["edge_kinds"] == ["contains", "calls", "references", "imports"]
diff --git a/plugins/python/tests/test_pyright_session.py b/plugins/python/tests/test_pyright_session.py
index 4a4cf8df..61787a9c 100644
--- a/plugins/python/tests/test_pyright_session.py
+++ b/plugins/python/tests/test_pyright_session.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import ast
 import shutil
 import stat
 import sys
@@ -20,6 +21,11 @@
     FINDING_PYRIGHT_UNAVAILABLE,
     LspTimeoutError,
     PyrightSession,
+    _CallSite,
+    _FunctionIndex,
+    _FunctionInfo,
+    _unresolved_call_site_total_for_function,
+    _unresolved_call_sites_for_function,
 )
 from clarion_plugin_python.reference_resolver import ReferenceSite, ReferenceSiteKind
 
@@ -36,7 +42,12 @@ def pyright_langserver() -> str:
         return str(venv_candidate)
     resolved = shutil.which("pyright-langserver")
     if resolved is None:
-        pytest.skip("pyright-langserver is not installed")
+        pytest.fail(
+            "pyright-langserver not found on PATH or in the active virtualenv. "
+            "It is a hard runtime dependency of clarion-plugin-python "
+            "(pyproject.toml `dependencies`); a missing executable means the "
+            "install is broken. Skipping these tests would mask a regression.",
+        )
     return resolved
 
 
@@ -46,6 +57,50 @@ def _write_module(tmp_path: Path, source: str, name: str = "demo.py") -> Path:
     return path
 
 
+def test_unresolved_call_site_details_omit_expressions_over_host_cap() -> None:
+    callee_expr = "factory." + ".".join(f"method_{idx:03d}" for idx in range(80))
+    assert len(callee_expr.encode("utf-8")) > 512
+    source = f"def caller():\n    {callee_expr}()\n"
+    tree = ast.parse(source)
+    function_node = cast("ast.FunctionDef", tree.body[0])
+    index = _FunctionIndex(
+        source=source,
+        line_starts=(0, len(b"def caller():\n")),
+        parse_latency_ms=0,
+        module_id="python:module:demo",
+        by_id={},
+        by_name_position={},
+        entity_by_name_position={},
+        by_short_name={},
+        dunder_call_by_class={},
+        functions=(),
+        entities=(),
+        tree=tree,
+    )
+    function = _FunctionInfo(
+        entity_id="python:function:demo.caller",
+        qualified_name="demo.caller",
+        name="caller",
+        line=0,
+        character=4,
+        end_line=1,
+        end_character=8,
+        call_sites=(
+            _CallSite(
+                line=1,
+                character=4,
+                end_line=1,
+                end_character=4 + len(callee_expr),
+                callee_expr=callee_expr,
+            ),
+        ),
+        node=function_node,
+    )
+
+    assert _unresolved_call_site_total_for_function(function, set()) == 1
+    assert _unresolved_call_sites_for_function(index, function, set()) == []
+
+
 def _finding_codes(result_findings: Sequence[Finding]) -> set[str]:
     return {str(finding["subcode"]) for finding in result_findings}
 
@@ -304,6 +359,20 @@ def test_pyright_session_reference_unavailable_binary_missing(tmp_path: Path) ->
     assert FINDING_PYRIGHT_UNAVAILABLE in _finding_codes(result.findings)
 
 
+def test_pyright_session_treats_project_local_venv_targets_as_external(tmp_path: Path) -> None:
+    target = tmp_path / ".venv" / "lib" / "python3.12" / "site-packages" / "demo.py"
+    target.parent.mkdir(parents=True)
+    target.write_text("def helper():\n    pass\n", encoding="utf-8")
+    location = {
+        "uri": target.as_uri(),
+        "range": {"start": {"line": 0, "character": 4}, "end": {"line": 0, "character": 10}},
+    }
+
+    session = PyrightSession(tmp_path, executable=sys.executable)
+
+    assert session._target_id_from_location(location) == (None, True)  # noqa: SLF001
+
+
 def test_pyright_session_reference_site_cap(tmp_path: Path) -> None:
     source = "def world():\n    pass\n\nCONST_REF = world\n"
     module = _write_module(tmp_path, source)
@@ -354,9 +423,10 @@ def _reference_target_ids(
         uri: str,
         site: ReferenceSite,
         *,
+        deadline: float,
         method: str = "textDocument/definition",
     ) -> tuple[list[str], bool]:
-        _ = (uri, method)
+        _ = (uri, deadline, method)
         self.requested_starts.append(site.source_byte_start)
         if site.source_byte_start == self.timeout_start:
             raise LspTimeoutError(method)
@@ -380,9 +450,10 @@ def _reference_target_ids(
         uri: str,
         site: ReferenceSite,
         *,
+        deadline: float,
         method: str = "textDocument/definition",
     ) -> tuple[list[str], bool]:
-        _ = (uri, method)
+        _ = (uri, deadline, method)
         self.requested_starts.append(site.source_byte_start)
         return [self.target_id], False
 
@@ -687,6 +758,29 @@ def _request(self, method: str, params: dict[str, object], timeout_secs: float)
         return super()._request(method, params, timeout_secs)
 
 
+class BudgetProbeSession(PyrightSession):
+    def __init__(self, project_root: Path) -> None:
+        super().__init__(
+            project_root,
+            executable=sys.executable,
+            call_timeout_secs=10.0,
+            file_timeout_secs=0.01,
+        )
+        self.request_timeouts: list[float] = []
+
+    def _ensure_process(self) -> bool:
+        return True
+
+    def _notify(self, method: str, params: dict[str, object]) -> None:
+        _ = (method, params)
+
+    def _request(self, method: str, params: dict[str, object], timeout_secs: float) -> object:
+        _ = (method, params)
+        self.request_timeouts.append(timeout_secs)
+        timeout_method = "budget probe"
+        raise LspTimeoutError(timeout_method)
+
+
 @pytest.mark.pyright
 def test_pyright_session_call_resolution_timeout(tmp_path: Path, pyright_langserver: str) -> None:
     module = _write_module(
@@ -707,6 +801,24 @@ def caller():
     assert FINDING_PYRIGHT_CALL_RESOLUTION_TIMEOUT in _finding_codes(result.findings)
 
 
+def test_pyright_session_caps_per_file_pyright_budget(tmp_path: Path) -> None:
+    module = _write_module(
+        tmp_path,
+        """
+        def caller():
+            print('x')
+        """,
+    )
+
+    with BudgetProbeSession(tmp_path) as session:
+        result = session.resolve_calls(module, ["python:function:demo.caller"])
+
+    assert result.edges == []
+    assert session.request_timeouts
+    assert max(session.request_timeouts) <= 0.01
+    assert FINDING_PYRIGHT_CALL_RESOLUTION_TIMEOUT in _finding_codes(result.findings)
+
+
 def test_pyright_session_stderr_drain(tmp_path: Path) -> None:
     script = _write_executable(
         tmp_path,
@@ -764,3 +876,93 @@ def write_frame(message):
 
     assert result.edges == []
     assert session.stderr_thread_alive is False
+
+
+def test_pyright_session_answers_workspace_configuration_requests(tmp_path: Path) -> None:
+    marker = tmp_path / "config-marker.txt"
+    script = _write_executable(
+        tmp_path,
+        textwrap.dedent(
+            """
+            #!/usr/bin/env python3
+            import json
+            import os
+            import sys
+            from pathlib import Path
+
+            def read_frame():
+                headers = {}
+                while True:
+                    line = sys.stdin.buffer.readline()
+                    if not line:
+                        return None
+                    if line == b"\\r\\n":
+                        break
+                    name, value = line.decode("ascii").strip().split(":", 1)
+                    headers[name.lower()] = value.strip()
+                return json.loads(sys.stdin.buffer.read(int(headers["content-length"])))
+
+            def write_frame(message):
+                body = json.dumps(message).encode("utf-8")
+                sys.stdout.buffer.write(
+                    b"Content-Length: " + str(len(body)).encode("ascii") + b"\\r\\n\\r\\n"
+                )
+                sys.stdout.buffer.write(body)
+                sys.stdout.buffer.flush()
+
+            initialize = read_frame()
+            write_frame(
+                {
+                    "jsonrpc": "2.0",
+                    "id": 0,
+                    "method": "workspace/configuration",
+                    "params": {
+                        "items": [
+                            {"section": "python"},
+                            {"section": "python.analysis"},
+                            {"section": "pyright"},
+                        ],
+                    },
+                },
+            )
+            config = read_frame()
+            result = config.get("result", [])
+            python = result[0].get("analysis", {}) if len(result) > 0 else {}
+            analysis = result[1] if len(result) > 1 else {}
+            ok = (
+                python.get("diagnosticMode") == "openFilesOnly"
+                and python.get("indexing") is False
+                and "**/.venv/**" in python.get("exclude", [])
+                and analysis.get("diagnosticMode") == "openFilesOnly"
+                and analysis.get("indexing") is False
+                and result[2] == {}
+            )
+            Path(os.environ["CONFIG_MARKER"]).write_text("ok" if ok else repr(config))
+            write_frame({"jsonrpc": "2.0", "id": initialize["id"], "result": {}})
+
+            while True:
+                frame = read_frame()
+                if frame is None:
+                    break
+                method = frame.get("method")
+                if method == "textDocument/prepareCallHierarchy":
+                    write_frame({"jsonrpc": "2.0", "id": frame["id"], "result": []})
+                elif method == "shutdown":
+                    write_frame({"jsonrpc": "2.0", "id": frame["id"], "result": {}})
+                elif method == "exit":
+                    break
+            """,
+        ).lstrip(),
+    )
+    module = _write_module(tmp_path, "def caller():\n    print('x')\n")
+
+    with PyrightSession(
+        tmp_path,
+        executable=str(script),
+        env={"CONFIG_MARKER": str(marker)},
+        init_timeout_secs=1.0,
+    ) as session:
+        result = session.resolve_calls(module, ["python:function:demo.caller"])
+
+    assert result.edges == []
+    assert marker.read_text(encoding="utf-8") == "ok"
diff --git a/plugins/python/tests/test_server.py b/plugins/python/tests/test_server.py
index b89a91d7..e8533aba 100644
--- a/plugins/python/tests/test_server.py
+++ b/plugins/python/tests/test_server.py
@@ -17,6 +17,11 @@
 
 from clarion_plugin_python import server as server_module
 from clarion_plugin_python.call_resolver import CallResolutionResult
+from clarion_plugin_python.pyright_session import (
+    FINDING_PYRIGHT_RESTART,
+    PyrightRunState,
+    PyrightSession,
+)
 from clarion_plugin_python.reference_resolver import ReferenceResolutionResult, ReferenceSite
 
 if TYPE_CHECKING:
@@ -81,7 +86,7 @@ def test_initialize_roundtrip() -> None:
         assert response["id"] == 1
         result = response["result"]
         assert result["name"] == "clarion-plugin-python"
-        assert result["version"] == "0.1.5"
+        assert result["version"] == "1.0.0"
         assert result["ontology_version"] == "0.6.0"
         # Capabilities carry the L8 Wardline probe result. We don't pin a
         # specific status here because the probe's output depends on whether
@@ -266,7 +271,7 @@ def test_analyze_file_lazy_initializes_pyright(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     class FakePyrightSession:
-        def __init__(self, project_root: Path) -> None:
+        def __init__(self, project_root: Path, **_kwargs: Any) -> None:
             self.project_root = project_root
             self.closed = False
 
@@ -305,7 +310,7 @@ def test_analyze_file_reports_call_resolver_stats(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     class FakePyrightSession:
-        def __init__(self, project_root: Path) -> None:
+        def __init__(self, project_root: Path, **_kwargs: Any) -> None:
             self.project_root = project_root
 
         def resolve_calls(
@@ -393,6 +398,55 @@ def close(self) -> None:
     assert any(edge["kind"] == "references" for edge in response["edges"])
 
 
+def test_analyze_file_restarts_pyright_after_file_budget(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    sessions: list[Any] = []
+
+    class FakePyrightSession:
+        def __init__(self, project_root: Path, **_kwargs: Any) -> None:
+            self.project_root = project_root
+            self.closed = False
+            sessions.append(self)
+
+        def resolve_calls(
+            self,
+            file_path: str,
+            function_ids: list[str],
+        ) -> CallResolutionResult:
+            _ = (file_path, function_ids)
+            return CallResolutionResult()
+
+        def resolve_references(
+            self,
+            file_path: str,
+            sites: Sequence[ReferenceSite],
+        ) -> ReferenceResolutionResult:
+            _ = (file_path, sites)
+            return ReferenceResolutionResult()
+
+        def close(self) -> None:
+            self.closed = True
+
+    monkeypatch.setattr(server_module, "PyrightSession", FakePyrightSession, raising=False)
+    monkeypatch.setattr(server_module, "MAX_FILES_PER_PYRIGHT_SESSION", 2)
+    demo = tmp_path / "demo.py"
+    demo.write_text("def hello():\n    pass\n", encoding="utf-8")
+    state = server_module.ServerState(initialized=True, project_root=tmp_path)
+
+    server_module.handle_analyze_file({"file_path": str(demo)}, state)
+    assert state.pyright is sessions[0]
+    first_session = cast("Any", sessions[0])
+    assert first_session.closed is False
+
+    server_module.handle_analyze_file({"file_path": str(demo)}, state)
+    assert first_session.closed is True
+    assert len(sessions) == 1
+    assert state.pyright is None
+    assert state.pyright_files_since_restart == 0
+
+
 def test_shutdown_closes_pyright_session() -> None:
     class FakePyrightSession:
         def __init__(self) -> None:
@@ -413,3 +467,120 @@ def close(self) -> None:
     assert response == {"jsonrpc": "2.0", "id": 1, "result": {}}
     assert fake.closed is True
     assert state.pyright is None
+
+
+def test_restart_budget_survives_session_recycle(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Run-wide restart cap is not reset at the session-recycle boundary.
+
+    With MAX_FILES_PER_PYRIGHT_SESSION=25 and 30 files, there are two recycles
+    (files 1-25 in session 1, files 26-30 in session 2). A crashing pyright
+    must exhaust the single run-wide 3-restart budget, not a fresh 3-restart
+    budget per session.
+    """
+
+    # Each fake session increments run_state.restart_count directly, simulating
+    # a pyright that crashes on every call.  Using run_state rather than a
+    # session-local counter is what the fix is supposed to enforce.
+    class CrashingFakePyrightSession:
+        def __init__(self, project_root: Path, **kwargs: Any) -> None:
+            self.project_root = project_root
+            self.run_state: PyrightRunState = kwargs.get("run_state") or PyrightRunState()
+            self.closed = False
+
+        def resolve_calls(
+            self,
+            file_path: str,
+            function_ids: list[str],
+        ) -> CallResolutionResult:
+            _ = (file_path, function_ids)
+            if not self.run_state.disabled:
+                # Simulate a crash: record a restart finding via run_state.
+                self.run_state.restart_count += 1
+                if self.run_state.restart_count > 3:
+                    self.run_state.disabled = True
+                    return CallResolutionResult(
+                        findings=[
+                            {
+                                "subcode": FINDING_PYRIGHT_RESTART,
+                                "severity": "warning",
+                                "message": "pyright restart cap exceeded",
+                                "metadata": {},
+                            }
+                        ],
+                    )
+                return CallResolutionResult(
+                    findings=[
+                        {
+                            "subcode": FINDING_PYRIGHT_RESTART,
+                            "severity": "warning",
+                            "message": "pyright subprocess died and was restarted",
+                            "metadata": {},
+                        }
+                    ],
+                )
+            return CallResolutionResult()
+
+        def resolve_references(
+            self,
+            file_path: str,
+            sites: Sequence[ReferenceSite],
+        ) -> ReferenceResolutionResult:
+            _ = (file_path, sites)
+            return ReferenceResolutionResult()
+
+        def close(self) -> None:
+            self.closed = True
+
+    monkeypatch.setattr(server_module, "PyrightSession", CrashingFakePyrightSession, raising=False)
+    demo = tmp_path / "demo.py"
+    demo.write_text("def hello():\n    pass\n", encoding="utf-8")
+    state = server_module.ServerState(initialized=True, project_root=tmp_path)
+
+    # Drive 30 analyze_file requests.  The recycle boundary falls at file 25.
+    for _ in range(30):
+        server_module.handle_analyze_file({"file_path": str(demo)}, state)
+
+    # The run-wide budget must be consumed exactly once across both recycles,
+    # not reset to 3 at the recycle boundary.
+    assert state.pyright_run_state.restart_count <= 4  # 3 restarts + 1 cap trip
+    assert state.pyright_run_state.disabled is True
+
+
+def test_disabled_pyright_unavailable_does_not_redrive_per_session(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Once pyright is disabled (binary missing), recycles must not re-check the binary.
+
+    Driving 30 files across the 25-file recycle boundary should emit exactly
+    one FINDING_PYRIGHT_UNAVAILABLE finding, not one per recycle.
+    """
+    resolve_executable_call_count = 0
+
+    def counting_resolve_executable(_self: PyrightSession) -> None:
+        nonlocal resolve_executable_call_count
+        resolve_executable_call_count += 1
+        # Returning None simulates a missing binary.
+
+    monkeypatch.setattr(
+        PyrightSession,
+        "_resolve_executable",
+        counting_resolve_executable,
+        raising=False,
+    )
+
+    demo = tmp_path / "demo.py"
+    demo.write_text("def hello():\n    pass\n", encoding="utf-8")
+    state = server_module.ServerState(initialized=True, project_root=tmp_path)
+
+    # Drive 30 analyze_file requests across the 25-file recycle boundary.
+    for _ in range(30):
+        server_module.handle_analyze_file({"file_path": str(demo)}, state)
+
+    # _resolve_executable must be called exactly once: the first time pyright
+    # is needed.  The shared run_state.disabled=True short-circuits _ensure_process
+    # before _start_process (and thus _resolve_executable) is re-entered.
+    assert resolve_executable_call_count == 1
diff --git a/scripts/check-entity-cap-lockstep.py b/scripts/check-entity-cap-lockstep.py
new file mode 100755
index 00000000..af49dbaa
--- /dev/null
+++ b/scripts/check-entity-cap-lockstep.py
@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Guard the per-run entity-count cap against ADR/code drift.
+
+ADR-021 §2c fixes the default per-run cumulative cap on ``entity`` + ``edge`` +
+``finding`` notifications from a single plugin. That number is duplicated in
+two places that must stay in lockstep:
+
+* docs/clarion/adr/ADR-021-plugin-authority-hybrid.md §2c — the normative
+  ``Default: **500,000**`` statement.
+* crates/clarion-core/src/plugin/limits.rs — ``EntityCountCap::DEFAULT_MAX``,
+  the const the host actually enforces.
+
+If the const drifts from the ADR, the enforced guardrail no longer matches the
+documented authority model. This guard keeps the duplication mechanical:
+closes V11-TEST-04 (docs/implementation/v1.0-tag-cut/gap-register.md).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+DEFAULT_LIMITS = Path("crates/clarion-core/src/plugin/limits.rs")
+DEFAULT_ADR = Path("docs/clarion/adr/ADR-021-plugin-authority-hybrid.md")
+
+# `pub const DEFAULT_MAX: usize = 500_000;` — underscores are stripped before int().
+_RUST_DEFAULT_MAX_RE = re.compile(
+    r"\bconst\s+DEFAULT_MAX\s*:\s*usize\s*=\s*(?P<value>[0-9_]+)"
+)
+# Anchored on the §2c section so we read *that* section's default, not another's:
+# "...Entity-count cap.** ... Default: **500,000** combined records...".
+_ADR_DEFAULT_RE = re.compile(
+    r"Entity-count cap.*?Default:\s*\*\*(?P<value>[0-9,]+)\*\*",
+    re.DOTALL,
+)
+
+
+class CheckError(Exception):
+    """Raised when the entity-cap lockstep guard fails."""
+
+
+def _to_int(label: str, raw: str) -> int:
+    digits = raw.replace("_", "").replace(",", "")
+    if not digits.isdigit():
+        raise CheckError(f"{label} is not an integer: {raw!r}")
+    return int(digits)
+
+
+def rust_default_max(limits_path: Path) -> int:
+    """Extract ``EntityCountCap::DEFAULT_MAX`` from limits.rs."""
+    matches = _RUST_DEFAULT_MAX_RE.findall(limits_path.read_text(encoding="utf-8"))
+    if not matches:
+        raise CheckError(f"{limits_path} has no 'const DEFAULT_MAX: usize = ...'")
+    if len({m.replace("_", "") for m in matches}) > 1:
+        raise CheckError(f"{limits_path} defines DEFAULT_MAX more than once: {matches}")
+    return _to_int("limits.rs DEFAULT_MAX", matches[0])
+
+
+def adr_default_cap(adr_path: Path) -> int:
+    """Extract the §2c default cap from ADR-021."""
+    match = _ADR_DEFAULT_RE.search(adr_path.read_text(encoding="utf-8"))
+    if match is None:
+        raise CheckError(
+            f"{adr_path} §2c does not state 'Default: **<number>**' for the entity-count cap"
+        )
+    return _to_int("ADR-021 §2c default", match.group("value"))
+
+
+def check(limits_path: Path, adr_path: Path) -> int:
+    """Return the agreed cap, or raise CheckError on drift."""
+    code = rust_default_max(limits_path)
+    adr = adr_default_cap(adr_path)
+    if code != adr:
+        raise CheckError(
+            f"entity-cap drift: {limits_path} DEFAULT_MAX={code:,} but "
+            f"ADR-021 §2c states {adr:,}"
+        )
+    return code
+
+
+def write(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8")
+
+
+def run_self_test() -> None:
+    rust_aligned = (
+        "impl EntityCountCap {\n    pub const DEFAULT_MAX: usize = 500_000;\n}\n"
+    )
+    adr_aligned = (
+        "**2c — Entity-count cap.** Per-run cumulative cap. "
+        "Default: **500,000** combined records (floor 10,000).\n"
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        limits = root / "limits.rs"
+        adr = root / "adr.md"
+
+        write(limits, rust_aligned)
+        write(adr, adr_aligned)
+        assert check(limits, adr) == 500_000
+
+        # Code drift must fail.
+        write(limits, "    pub const DEFAULT_MAX: usize = 400_000;\n")
+        _expect(limits, adr, "drift")
+        write(limits, rust_aligned)
+
+        # ADR drift must fail.
+        write(
+            adr, "**2c — Entity-count cap.** Default: **750,000** combined records.\n"
+        )
+        _expect(limits, adr, "drift")
+        write(adr, adr_aligned)
+
+        # A missing const must fail loudly, not pass vacuously.
+        write(limits, "// no const here\n")
+        _expect(limits, adr, "no 'const DEFAULT_MAX")
+        write(limits, rust_aligned)
+
+        # A §2c section with no Default must fail.
+        write(adr, "**2c — Entity-count cap.** Per-run cumulative cap.\n")
+        _expect(limits, adr, "does not state")
+
+    print("entity-cap lockstep guard self-test passed")
+
+
+def _expect(limits: Path, adr: Path, needle: str) -> None:
+    try:
+        check(limits, adr)
+    except CheckError as exc:
+        if needle not in str(exc):
+            raise
+    else:
+        raise CheckError(f"self-test expected failure containing {needle!r}")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Check EntityCountCap ADR/code lockstep"
+    )
+    parser.add_argument("--limits", type=Path, default=DEFAULT_LIMITS)
+    parser.add_argument("--adr", type=Path, default=DEFAULT_ADR)
+    parser.add_argument(
+        "--self-test", action="store_true", help="run built-in guard tests"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.self_test:
+            run_self_test()
+        else:
+            cap = check(args.limits, args.adr)
+            print(f"EntityCountCap DEFAULT_MAX matches ADR-021 §2c: {cap:,}")
+    except CheckError as exc:
+        print(f"entity-cap lockstep guard failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/check-github-release-governance.py b/scripts/check-github-release-governance.py
new file mode 100755
index 00000000..4a7fb936
--- /dev/null
+++ b/scripts/check-github-release-governance.py
@@ -0,0 +1,913 @@
+#!/usr/bin/env python3
+"""Check GitHub-side release governance before cutting a Clarion tag.
+
+The release workflow can prove build and artifact integrity once it runs, but
+some 1.0 release controls live outside the repository tree: branch protection,
+repository rulesets, and the Actions source policy. This guard queries the live
+GitHub REST API and fails when those controls are still permissive.
+
+Exit codes:
+    0  release governance is non-permissive enough for the v1.0 tag gate
+    1  the live settings are too permissive
+    2  usage, authentication, or API access error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Any
+
+
+class CheckError(Exception):
+    """Raised when release governance is too permissive."""
+
+
+class UsageError(Exception):
+    """Raised when the guard cannot query GitHub correctly."""
+
+
+FULL_SHA_RE = re.compile(r"^[0-9a-f]{40}$")
+USES_RE = re.compile(r"^\s*(?:-\s*)?uses:\s*(?P<target>\S+)\s*$")
+JOB_RE = re.compile(r"^  (?P<name>[A-Za-z0-9_-]+):\s*(?:#.*)?$")
+REQUIRED_STATUS_CHECKS = frozenset(
+    {
+        "Rust",
+        "Python plugin",
+        "Sprint 1 walking skeleton (end-to-end)",
+    }
+)
+
+
+@dataclass(frozen=True)
+class ApiResponse:
+    status: int
+    payload: Any
+
+
+class GitHubClient:
+    """Tiny GitHub REST client using only the Python standard library."""
+
+    def __init__(self, token: str, api_base: str = "https://api.github.com") -> None:
+        self.token = token
+        self.api_base = api_base.rstrip("/")
+
+    def get(self, path: str) -> ApiResponse:
+        url = f"{self.api_base}{path}"
+        request = urllib.request.Request(
+            url,
+            headers={
+                "Accept": "application/vnd.github+json",
+                "Authorization": f"Bearer {self.token}",
+                "User-Agent": "clarion-release-governance-check",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=20) as response:
+                body = response.read().decode("utf-8")
+                return ApiResponse(response.status, json.loads(body) if body else None)
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8")
+            try:
+                payload: Any = json.loads(body) if body else None
+            except json.JSONDecodeError:
+                payload = body
+            return ApiResponse(exc.code, payload)
+        except OSError as exc:
+            raise UsageError(f"GitHub API request failed: {exc}") from exc
+
+
+def require_mapping(value: Any, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise UsageError(f"{label} returned unexpected payload: {value!r}")
+    return value
+
+
+def require_list(value: Any, label: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise UsageError(f"{label} returned unexpected payload: {value!r}")
+    return value
+
+
+def api_message(payload: Any) -> str:
+    if isinstance(payload, dict) and isinstance(payload.get("message"), str):
+        return payload["message"]
+    return repr(payload)
+
+
+def branch_protection(
+    request_json: Callable[[str], ApiResponse],
+    repository: str,
+    branch: str,
+) -> dict[str, Any] | None:
+    response = request_json(f"/repos/{repository}/branches/{branch}/protection")
+    if response.status == 200:
+        return require_mapping(response.payload, "branch protection")
+    if response.status == 404:
+        return None
+    raise UsageError(
+        f"cannot inspect branch protection for {repository}@{branch}: "
+        f"HTTP {response.status} {api_message(response.payload)}"
+    )
+
+
+def repository_rulesets(
+    request_json: Callable[[str], ApiResponse],
+    repository: str,
+) -> list[dict[str, Any]]:
+    response = request_json(f"/repos/{repository}/rulesets")
+    if response.status != 200:
+        raise UsageError(
+            f"cannot inspect repository rulesets for {repository}: "
+            f"HTTP {response.status} {api_message(response.payload)}"
+        )
+    rulesets = require_list(response.payload, "repository rulesets")
+    return [require_mapping(item, "repository ruleset") for item in rulesets]
+
+
+def repository_ruleset_detail(
+    request_json: Callable[[str], ApiResponse],
+    repository: str,
+    ruleset: dict[str, Any],
+) -> dict[str, Any]:
+    ruleset_id = ruleset.get("id")
+    if not isinstance(ruleset_id, int):
+        return ruleset
+    response = request_json(f"/repos/{repository}/rulesets/{ruleset_id}")
+    if response.status != 200:
+        raise UsageError(
+            f"cannot inspect repository ruleset {ruleset_id} for {repository}: "
+            f"HTTP {response.status} {api_message(response.payload)}"
+        )
+    return require_mapping(response.payload, "repository ruleset detail")
+
+
+def actions_permissions(
+    request_json: Callable[[str], ApiResponse],
+    repository: str,
+) -> dict[str, Any]:
+    response = request_json(f"/repos/{repository}/actions/permissions")
+    if response.status != 200:
+        raise UsageError(
+            f"cannot inspect Actions permissions for {repository}: "
+            f"HTTP {response.status} {api_message(response.payload)}"
+        )
+    return require_mapping(response.payload, "Actions permissions")
+
+
+def branch_pattern_matches(pattern: str, branch: str) -> bool:
+    if pattern in {branch, f"refs/heads/{branch}", "~DEFAULT_BRANCH"}:
+        return True
+    normalized = pattern.removeprefix("refs/heads/")
+    return fnmatchcase(branch, normalized)
+
+
+def ruleset_targets_branch(ruleset: dict[str, Any], branch: str) -> bool:
+    target = ruleset.get("target")
+    if target not in {None, "branch"}:
+        return False
+
+    conditions = ruleset.get("conditions")
+    if not isinstance(conditions, dict):
+        return True
+    ref_name = conditions.get("ref_name")
+    if not isinstance(ref_name, dict):
+        return True
+
+    exclude = ref_name.get("exclude")
+    if isinstance(exclude, list) and any(
+        isinstance(pattern, str) and branch_pattern_matches(pattern, branch)
+        for pattern in exclude
+    ):
+        return False
+
+    include = ref_name.get("include")
+    if not isinstance(include, list) or not include:
+        return True
+    return any(
+        isinstance(pattern, str) and branch_pattern_matches(pattern, branch)
+        for pattern in include
+    )
+
+
+def ruleset_targets_tag(ruleset: dict[str, Any], tag_pattern: str) -> bool:
+    """True when an active tag ruleset's include patterns cover ``tag_pattern``.
+
+    GitHub tag rulesets carry ``target == "tag"`` and condition their
+    ``ref_name`` on ``refs/tags/`` globs. We accept a ruleset if it either
+    has no narrowing ``include`` list (covers all tags) or names an include
+    pattern that the desired ``tag_pattern`` (e.g. ``refs/tags/v*``) satisfies.
+    """
+    if ruleset.get("target") != "tag":
+        return False
+
+    conditions = ruleset.get("conditions")
+    if not isinstance(conditions, dict):
+        return True
+    ref_name = conditions.get("ref_name")
+    if not isinstance(ref_name, dict):
+        return True
+
+    include = ref_name.get("include")
+    if not isinstance(include, list) or not include:
+        return True
+    # The desired pattern is itself a glob (refs/tags/v*); treat an include
+    # entry as covering it when the strings match, when the include is the
+    # all-tags wildcard, or when the include glob matches the literal prefix
+    # of the desired pattern.
+    desired = tag_pattern.removeprefix("refs/tags/")
+    for pattern in include:
+        if not isinstance(pattern, str):
+            continue
+        normalized = pattern.removeprefix("refs/tags/")
+        if pattern in {tag_pattern, "~ALL"} or normalized in {desired, "*"}:
+            return True
+        # An include like `v*` matches the concrete tag families we cut.
+        if fnmatchcase("v1.0.0", normalized) or fnmatchcase(desired, normalized):
+            return True
+    return False
+
+
+def branch_protection_status_checks(protection: dict[str, Any]) -> set[str]:
+    required = protection.get("required_status_checks")
+    if not isinstance(required, dict):
+        return set()
+
+    contexts = {
+        context
+        for context in required.get("contexts", [])
+        if isinstance(context, str)
+    }
+    checks = {
+        check.get("context")
+        for check in required.get("checks", [])
+        if isinstance(check, dict) and isinstance(check.get("context"), str)
+    }
+    return contexts | checks
+
+
+def ruleset_status_checks(ruleset: dict[str, Any]) -> set[str]:
+    checks: set[str] = set()
+    rules = ruleset.get("rules")
+    if not isinstance(rules, list):
+        return checks
+
+    for rule in rules:
+        if not isinstance(rule, dict) or rule.get("type") != "required_status_checks":
+            continue
+        parameters = rule.get("parameters")
+        if not isinstance(parameters, dict):
+            continue
+        for check in parameters.get("required_status_checks", []):
+            if isinstance(check, dict) and isinstance(check.get("context"), str):
+                checks.add(check["context"])
+            elif isinstance(check, str):
+                checks.add(check)
+    return checks
+
+
+def ruleset_requires_pull_request(ruleset: dict[str, Any]) -> bool:
+    rules = ruleset.get("rules")
+    if not isinstance(rules, list):
+        return False
+    return any(isinstance(rule, dict) and rule.get("type") == "pull_request" for rule in rules)
+
+
+def protection_requires_pull_request(protection: dict[str, Any]) -> bool:
+    return isinstance(protection.get("required_pull_request_reviews"), dict)
+
+
+def missing_required_status_checks(actual: set[str]) -> set[str]:
+    return REQUIRED_STATUS_CHECKS - actual
+
+
+def check_governance(
+    request_json: Callable[[str], ApiResponse],
+    repository: str,
+    branch: str,
+) -> list[str]:
+    failures: list[str] = []
+    notes: list[str] = []
+
+    protection = branch_protection(request_json, repository, branch)
+    rule_summaries = repository_rulesets(request_json, repository)
+    active_rulesets = [
+        repository_ruleset_detail(request_json, repository, item)
+        for item in rule_summaries
+        if item.get("enforcement") == "active" and ruleset_targets_branch(item, branch)
+    ]
+
+    protected_path_ok = False
+    if protection is not None:
+        missing_checks = missing_required_status_checks(branch_protection_status_checks(protection))
+        if missing_checks:
+            failures.append(
+                f"{branch}: branch protection is missing required CI checks: "
+                f"{', '.join(sorted(missing_checks))}"
+            )
+        elif not protection_requires_pull_request(protection):
+            failures.append(
+                f"{branch}: branch protection does not require pull-request review flow; "
+                "direct pushes can bypass the release PR path"
+            )
+        else:
+            protected_path_ok = True
+            notes.append(
+                f"{branch}: branch protection requires pull-request flow and "
+                f"{len(REQUIRED_STATUS_CHECKS)} release CI checks"
+            )
+
+    ruleset_path_ok = False
+    for ruleset in active_rulesets:
+        name = ruleset.get("name", "<unnamed ruleset>")
+        if not isinstance(name, str):
+            name = "<unnamed ruleset>"
+        missing_checks = missing_required_status_checks(ruleset_status_checks(ruleset))
+        has_pr_rule = ruleset_requires_pull_request(ruleset)
+        if not missing_checks and has_pr_rule:
+            ruleset_path_ok = True
+            notes.append(
+                f"{repository}: active ruleset {name!r} requires pull-request flow and "
+                f"{len(REQUIRED_STATUS_CHECKS)} release CI checks"
+            )
+
+    if active_rulesets and not ruleset_path_ok:
+        failures.append(
+            f"{repository}: active repository rulesets targeting {branch} do not require "
+            "both pull-request flow and the release CI checks"
+        )
+    if protection is None and not active_rulesets:
+        failures.append(
+            f"{branch}: no branch protection and no active repository rulesets; "
+            "tag provenance can bypass the reviewed PR path"
+        )
+    elif not protected_path_ok and not ruleset_path_ok:
+        failures.append(
+            f"{branch}: no branch protection or ruleset currently proves the reviewed "
+            "release PR path"
+        )
+
+    # Tag protection (GOV-02): an active ruleset must target `refs/tags/v*` so
+    # that a tag-push cannot point a release tag at an arbitrary commit. The
+    # legacy `tags/protection` endpoint is deprecated; a tag ruleset is the
+    # modern mechanism. We assert on the ruleset summaries (no detail fetch is
+    # needed for a presence check).
+    tag_pattern = "refs/tags/v*"
+    active_tag_rulesets = [
+        item.get("name", "<unnamed ruleset>")
+        for item in rule_summaries
+        if item.get("enforcement") == "active" and ruleset_targets_tag(item, tag_pattern)
+    ]
+    if active_tag_rulesets:
+        names = ", ".join(
+            name if isinstance(name, str) else "<unnamed ruleset>"
+            for name in active_tag_rulesets
+        )
+        notes.append(
+            f"{repository}: active tag ruleset(s) protect {tag_pattern} ({names})"
+        )
+    else:
+        failures.append(
+            f"{repository}: no active repository ruleset protects {tag_pattern}; "
+            "a tag-push can point a release tag at an arbitrary commit"
+        )
+
+    permissions = actions_permissions(request_json, repository)
+    if permissions.get("enabled") is not True:
+        failures.append("GitHub Actions are not enabled for the repository")
+    allowed_actions = permissions.get("allowed_actions")
+    sha_pinning_required = permissions.get("sha_pinning_required")
+    if allowed_actions == "all" and sha_pinning_required is not True:
+        failures.append(
+            "Actions source policy is permissive: allowed_actions=all and "
+            "sha_pinning_required is not true"
+        )
+    else:
+        notes.append(
+            "Actions source policy is constrained "
+            f"(allowed_actions={allowed_actions!r}, "
+            f"sha_pinning_required={sha_pinning_required!r})"
+        )
+
+    if failures:
+        raise CheckError("\n".join(failures))
+    return notes
+
+
+def check_workflow_action_pins(repo_root: Path) -> list[str]:
+    workflow_dir = repo_root / ".github" / "workflows"
+    if not workflow_dir.is_dir():
+        raise UsageError(f"workflow directory not found: {workflow_dir}")
+
+    failures: list[str] = []
+    checked = 0
+    for workflow in sorted([*workflow_dir.glob("*.yml"), *workflow_dir.glob("*.yaml")]):
+        for line_number, line in enumerate(workflow.read_text(encoding="utf-8").splitlines(), 1):
+            match = USES_RE.match(line)
+            if match is None:
+                continue
+            target = match.group("target")
+            if target.startswith(("./", "docker://")):
+                continue
+            if "@" not in target:
+                failures.append(f"{workflow}:{line_number}: external action is not pinned: {target}")
+                continue
+            ref = target.rsplit("@", maxsplit=1)[1]
+            checked += 1
+            if not FULL_SHA_RE.fullmatch(ref):
+                failures.append(
+                    f"{workflow}:{line_number}: action ref is not a full commit SHA: {target}"
+                )
+
+    if failures:
+        raise CheckError("\n".join(failures))
+    return [f"workflow action refs are full-length commit SHAs ({checked} uses entries checked)"]
+
+
+def check_dependabot_github_actions_updates(repo_root: Path) -> list[str]:
+    config = repo_root / ".github" / "dependabot.yml"
+    if not config.is_file():
+        raise CheckError(f"{config}: Dependabot config is missing")
+
+    current: dict[str, str] = {}
+    entries: list[dict[str, str]] = []
+    for raw_line in config.read_text(encoding="utf-8").splitlines():
+        stripped = raw_line.strip()
+        if stripped.startswith("- package-ecosystem:"):
+            if current:
+                entries.append(current)
+            current = {"package-ecosystem": stripped.split(":", maxsplit=1)[1].strip(" '\"")}
+        elif current and stripped.startswith("directory:"):
+            current["directory"] = stripped.split(":", maxsplit=1)[1].strip(" '\"")
+        elif current and stripped.startswith("interval:"):
+            current["interval"] = stripped.split(":", maxsplit=1)[1].strip(" '\"")
+    if current:
+        entries.append(current)
+
+    for entry in entries:
+        if entry.get("package-ecosystem") == "github-actions" and entry.get("directory") == "/":
+            interval = entry.get("interval")
+            if not interval:
+                raise CheckError(f"{config}: github-actions Dependabot entry has no schedule interval")
+            return [f"Dependabot watches GitHub Actions pins on / ({interval})"]
+
+    raise CheckError(
+        f"{config}: missing package-ecosystem=github-actions entry for directory=/; "
+        "pinned workflow actions need a scheduled update path"
+    )
+
+
+def release_workflow_job_blocks(workflow: Path) -> dict[str, list[str]]:
+    jobs: dict[str, list[str]] = {}
+    current_job: str | None = None
+    in_jobs = False
+
+    for raw_line in workflow.read_text(encoding="utf-8").splitlines():
+        if raw_line == "jobs:":
+            in_jobs = True
+            current_job = None
+            continue
+        if in_jobs and raw_line and not raw_line.startswith((" ", "#")):
+            break
+        if not in_jobs:
+            continue
+
+        match = JOB_RE.match(raw_line)
+        if match is not None:
+            current_job = match.group("name")
+            jobs[current_job] = []
+            continue
+        if current_job is not None:
+            jobs[current_job].append(raw_line)
+
+    return jobs
+
+
+def release_workflow_needs(job_lines: list[str]) -> set[str]:
+    needs: set[str] = set()
+    in_needs_block = False
+    for line in job_lines:
+        stripped = line.strip()
+        if stripped.startswith("needs:"):
+            in_needs_block = True
+            value = stripped.split(":", maxsplit=1)[1].strip()
+            if value.startswith("[") and value.endswith("]"):
+                needs.update(
+                    item.strip(" '\"") for item in value[1:-1].split(",") if item.strip()
+                )
+            elif value:
+                needs.add(value.strip(" '\""))
+            continue
+        if in_needs_block:
+            if stripped.startswith("- "):
+                needs.add(stripped[2:].strip(" '\""))
+                continue
+            if line.startswith("    ") and not line.startswith("      "):
+                in_needs_block = False
+    return needs
+
+
+def check_release_workflow_governance_gate(repo_root: Path) -> list[str]:
+    workflow = repo_root / ".github" / "workflows" / "release.yml"
+    if not workflow.is_file():
+        raise CheckError(f"{workflow}: release workflow is missing")
+
+    jobs = release_workflow_job_blocks(workflow)
+    failures: list[str] = []
+    if "release-governance" not in jobs:
+        failures.append(f"{workflow}: missing release-governance job")
+
+    for job_name in ("build-rust", "build-plugin"):
+        if job_name not in jobs:
+            failures.append(f"{workflow}: missing {job_name} job")
+            continue
+        needs = release_workflow_needs(jobs[job_name])
+        if "release-governance" not in needs:
+            failures.append(
+                f"{workflow}: {job_name} must need release-governance before release artifacts build"
+            )
+
+    if failures:
+        raise CheckError("\n".join(failures))
+    return ["release workflow build jobs require the GitHub governance gate"]
+
+
+def run_self_test() -> None:
+    responses: dict[str, ApiResponse] = {
+        "/repos/acme/clarion/branches/main/protection": ApiResponse(
+            404, {"message": "Branch not protected"}
+        ),
+        "/repos/acme/clarion/rulesets": ApiResponse(200, []),
+        "/repos/acme/clarion/actions/permissions": ApiResponse(
+            200,
+            {
+                "enabled": True,
+                "allowed_actions": "all",
+                "sha_pinning_required": False,
+            },
+        ),
+    }
+
+    def fake_get(path: str) -> ApiResponse:
+        return responses[path]
+
+    try:
+        check_governance(fake_get, "acme/clarion", "main")
+    except CheckError as exc:
+        message = str(exc)
+        assert "no branch protection" in message
+        assert "allowed_actions=all" in message
+    else:
+        raise AssertionError("permissive fixture should fail")
+
+    responses["/repos/acme/clarion/actions/permissions"] = ApiResponse(
+        200,
+        {
+            "enabled": True,
+            "allowed_actions": "selected",
+            "sha_pinning_required": True,
+        },
+    )
+    responses["/repos/acme/clarion/rulesets"] = ApiResponse(
+        200,
+        [
+            {
+                "id": 42,
+                "name": "weak release gate",
+                "target": "branch",
+                "enforcement": "active",
+                "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            }
+        ],
+    )
+    responses["/repos/acme/clarion/rulesets/42"] = ApiResponse(
+        200,
+        {
+            "id": 42,
+            "name": "weak release gate",
+            "target": "branch",
+            "enforcement": "active",
+            "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            "rules": [{"type": "pull_request", "parameters": {}}],
+        },
+    )
+    try:
+        check_governance(fake_get, "acme/clarion", "main")
+    except CheckError as exc:
+        assert "do not require both pull-request flow and the release CI checks" in str(exc)
+    else:
+        raise AssertionError("weak ruleset fixture should fail")
+
+    responses["/repos/acme/clarion/rulesets"] = ApiResponse(
+        200,
+        [
+            {
+                "id": 44,
+                "name": "evaluating release gate",
+                "target": "branch",
+                "enforcement": "evaluate",
+                "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            }
+        ],
+    )
+    responses["/repos/acme/clarion/rulesets/44"] = ApiResponse(
+        200,
+        {
+            "id": 44,
+            "name": "evaluating release gate",
+            "target": "branch",
+            "enforcement": "evaluate",
+            "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            "rules": [
+                {"type": "pull_request", "parameters": {"required_approving_review_count": 0}},
+                {
+                    "type": "required_status_checks",
+                    "parameters": {
+                        "required_status_checks": [
+                            {"context": "Rust"},
+                            {"context": "Python plugin"},
+                            {"context": "Sprint 1 walking skeleton (end-to-end)"},
+                        ]
+                    },
+                },
+            ],
+        },
+    )
+    try:
+        check_governance(fake_get, "acme/clarion", "main")
+    except CheckError as exc:
+        assert "no branch protection" in str(exc)
+    else:
+        raise AssertionError("evaluate-mode ruleset fixture should fail")
+
+    responses["/repos/acme/clarion/rulesets"] = ApiResponse(
+        200,
+        [
+            {
+                "id": 43,
+                "name": "main release gate",
+                "target": "branch",
+                "enforcement": "active",
+                "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            },
+            {
+                "id": 50,
+                "name": "release tag gate",
+                "target": "tag",
+                "enforcement": "active",
+                "conditions": {"ref_name": {"include": ["refs/tags/v*"], "exclude": []}},
+            },
+        ],
+    )
+    responses["/repos/acme/clarion/rulesets/43"] = ApiResponse(
+        200,
+        {
+            "id": 43,
+            "name": "main release gate",
+            "target": "branch",
+            "enforcement": "active",
+            "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            "rules": [
+                {"type": "pull_request", "parameters": {"required_approving_review_count": 0}},
+                {
+                    "type": "required_status_checks",
+                    "parameters": {
+                        "required_status_checks": [
+                            {"context": "Rust"},
+                            {"context": "Python plugin"},
+                            {"context": "Sprint 1 walking skeleton (end-to-end)"},
+                        ]
+                    },
+                },
+            ],
+        },
+    )
+    notes = check_governance(fake_get, "acme/clarion", "main")
+    assert any("active ruleset 'main release gate'" in note for note in notes)
+    assert any("active tag ruleset(s) protect refs/tags/v*" in note for note in notes)
+
+    # Tag protection absent (GOV-02): a fully-protected branch but no tag
+    # ruleset must still fail — a tag-push could point a release tag at an
+    # arbitrary commit.
+    responses["/repos/acme/clarion/rulesets"] = ApiResponse(
+        200,
+        [
+            {
+                "id": 43,
+                "name": "main release gate",
+                "target": "branch",
+                "enforcement": "active",
+                "conditions": {"ref_name": {"include": ["refs/heads/main"], "exclude": []}},
+            }
+        ],
+    )
+    try:
+        check_governance(fake_get, "acme/clarion", "main")
+    except CheckError as exc:
+        assert "no active repository ruleset protects refs/tags/v*" in str(exc)
+    else:
+        raise AssertionError("missing tag ruleset fixture should fail")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        workflow = root / ".github" / "workflows" / "ci.yml"
+        workflow.parent.mkdir(parents=True)
+        workflow.write_text(
+            "jobs:\n"
+            "  ok:\n"
+            "    steps:\n"
+            "      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5\n",
+            encoding="utf-8",
+        )
+        dependabot = root / ".github" / "dependabot.yml"
+        dependabot.write_text(
+            'version: 2\n'
+            'updates:\n'
+            '  - package-ecosystem: "github-actions"\n'
+            '    directory: "/"\n'
+            '    schedule:\n'
+            '      interval: "weekly"\n',
+            encoding="utf-8",
+        )
+        assert check_workflow_action_pins(root)
+        assert check_dependabot_github_actions_updates(root)
+        workflow.write_text(
+            "jobs:\n"
+            "  bad:\n"
+            "    steps:\n"
+            "      - uses: actions/checkout@v4\n",
+            encoding="utf-8",
+        )
+        try:
+            check_workflow_action_pins(root)
+        except CheckError as exc:
+            assert "not a full commit SHA" in str(exc)
+        else:
+            raise AssertionError("tag-pinned fixture should fail")
+        dependabot.write_text(
+            'version: 2\n'
+            'updates:\n'
+            '  - package-ecosystem: "pip"\n'
+            '    directory: "/plugins/python"\n',
+            encoding="utf-8",
+        )
+        try:
+            check_dependabot_github_actions_updates(root)
+        except CheckError as exc:
+            assert "missing package-ecosystem=github-actions" in str(exc)
+        else:
+            raise AssertionError("missing github-actions Dependabot fixture should fail")
+
+        release_workflow = workflow.parent / "release.yml"
+        release_workflow.write_text(
+            "jobs:\n"
+            "  verify:\n"
+            "    steps: []\n"
+            "  release-governance:\n"
+            "    steps: []\n"
+            "  build-rust:\n"
+            "    needs: [verify]\n"
+            "    steps: []\n"
+            "  build-plugin:\n"
+            "    needs: [verify]\n"
+            "    steps: []\n",
+            encoding="utf-8",
+        )
+        try:
+            check_release_workflow_governance_gate(root)
+        except CheckError as exc:
+            assert "build-rust" in str(exc)
+            assert "release-governance" in str(exc)
+        else:
+            raise AssertionError("ungated release-build fixture should fail")
+
+        release_workflow.write_text(
+            "jobs:\n"
+            "  verify:\n"
+            "    steps: []\n"
+            "  release-governance:\n"
+            "    steps: []\n"
+            "  build-rust:\n"
+            "    needs: [verify, release-governance]\n"
+            "    steps: []\n"
+            "  build-plugin:\n"
+            "    needs: [verify, release-governance]\n"
+            "    steps: []\n",
+            encoding="utf-8",
+        )
+        assert check_release_workflow_governance_gate(root)
+
+    print("GitHub release governance guard self-test passed")
+
+
+def resolve_token() -> str | None:
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        return token
+    proc = subprocess.run(
+        ["gh", "auth", "token"],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+    )
+    if proc.returncode == 0 and proc.stdout.strip():
+        return proc.stdout.strip()
+    return None
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--repository",
+        default=os.environ.get("GITHUB_REPOSITORY"),
+        help="owner/repo to inspect; defaults to GITHUB_REPOSITORY",
+    )
+    parser.add_argument("--branch", default="main", help="release branch to inspect")
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=Path.cwd(),
+        help="repository root for static workflow-pin checks",
+    )
+    parser.add_argument(
+        "--api-base",
+        default=os.environ.get("GITHUB_API_URL", "https://api.github.com"),
+        help="GitHub API base URL",
+    )
+    parser.add_argument("--self-test", action="store_true", help="run built-in tests")
+    parser.add_argument(
+        "--static-only",
+        action="store_true",
+        help="run source-tree checks and skip live GitHub API checks",
+    )
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        run_self_test()
+        return 0
+
+    try:
+        static_notes = [
+            *check_workflow_action_pins(args.repo_root),
+            *check_dependabot_github_actions_updates(args.repo_root),
+            *check_release_workflow_governance_gate(args.repo_root),
+        ]
+    except CheckError as exc:
+        print("GitHub release governance guard failed:", file=sys.stderr)
+        print(str(exc), file=sys.stderr)
+        return 1
+    except UsageError as exc:
+        print(f"GitHub release governance guard could not run: {exc}", file=sys.stderr)
+        return 2
+
+    if args.static_only:
+        for note in static_notes:
+            print(f"ok: {note}")
+        return 0
+
+    token = resolve_token()
+    if not args.repository:
+        print(
+            "check-github-release-governance: --repository or GITHUB_REPOSITORY is required",
+            file=sys.stderr,
+        )
+        return 2
+    if not token:
+        print(
+            "check-github-release-governance: GITHUB_TOKEN or GH_TOKEN is required",
+            file=sys.stderr,
+        )
+        return 2
+
+    client = GitHubClient(token=token, api_base=args.api_base)
+    try:
+        notes = [*static_notes, *check_governance(client.get, args.repository, args.branch)]
+    except CheckError as exc:
+        print("GitHub release governance guard failed:", file=sys.stderr)
+        print(str(exc), file=sys.stderr)
+        return 1
+    except UsageError as exc:
+        print(f"GitHub release governance guard could not run: {exc}", file=sys.stderr)
+        return 2
+
+    for note in notes:
+        print(f"ok: {note}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/check-pyright-pin-lockstep.py b/scripts/check-pyright-pin-lockstep.py
new file mode 100755
index 00000000..37054db9
--- /dev/null
+++ b/scripts/check-pyright-pin-lockstep.py
@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Guard the pyright version pin against drift across its three homes.
+
+The pinned pyright version is duplicated in three places that must stay in
+lockstep or CI silently caches/type-checks against mismatched toolchains:
+
+* plugins/python/pyproject.toml — the ``pyright==X`` dev-dependency pin that
+  determines which pyright actually runs under ``mypy``/``pytest`` locally and
+  in the python-plugin job.
+* plugins/python/plugin.toml — ``[capabilities.runtime.pyright].pin``, the
+  version the Rust host reads during discovery to know which langserver the
+  plugin expects on PATH.
+* .github/workflows/ci.yml — every ``pyright-python-<version>-...`` cache key.
+  A stale key restores a wheel for the wrong version, so the cached runtime no
+  longer matches the installed dev-dependency.
+
+This guard keeps the duplication mechanical: closes V11-TEST-02 (see
+docs/implementation/v1.0-tag-cut/gap-register.md).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import tempfile
+import tomllib
+from pathlib import Path
+
+DEFAULT_PYPROJECT = Path("plugins/python/pyproject.toml")
+DEFAULT_MANIFEST = Path("plugins/python/plugin.toml")
+DEFAULT_CI = Path(".github/workflows/ci.yml")
+
+# Matches a ``pyright==1.1.409`` style pin inside a dependency string.
+_PYRIGHT_DEP_RE = re.compile(r"^pyright\s*==\s*(?P<version>[0-9][0-9A-Za-z.\-]*)\s*$")
+# Matches every ``pyright-python-1.1.409`` cache-key stem in ci.yml.
+_CI_CACHE_KEY_RE = re.compile(r"pyright-python-(?P<version>[0-9][0-9A-Za-z.\-]*?)-")
+
+
+class CheckError(Exception):
+    """Raised when the pyright-pin guard fails."""
+
+
+def pyproject_pin(pyproject_path: Path) -> str:
+    """Extract the ``pyright==X`` pin from the project dependency tables.
+
+    Scans both ``[project].dependencies`` and every
+    ``[project.optional-dependencies]`` group so the guard does not care which
+    table the maintainer chose to home the pin in.
+    """
+    data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    project = data.get("project", {})
+    candidates: list[str] = list(project.get("dependencies", []))
+    for group in project.get("optional-dependencies", {}).values():
+        candidates.extend(group)
+    matches = [
+        m.group("version")
+        for dep in candidates
+        if (m := _PYRIGHT_DEP_RE.match(str(dep).strip()))
+    ]
+    if not matches:
+        raise CheckError(
+            f"{pyproject_path} does not pin pyright with 'pyright==<version>' "
+            "in [project].dependencies or any optional-dependencies group"
+        )
+    if len(set(matches)) > 1:
+        raise CheckError(
+            f"{pyproject_path} pins pyright more than once: {sorted(set(matches))}"
+        )
+    return matches[0]
+
+
+def manifest_pin(manifest_path: Path) -> str:
+    """Extract ``[capabilities.runtime.pyright].pin`` from the manifest."""
+    manifest = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    try:
+        pin = manifest["capabilities"]["runtime"]["pyright"]["pin"]
+    except KeyError as exc:
+        raise CheckError(
+            f"{manifest_path} is missing [capabilities.runtime.pyright].pin"
+        ) from exc
+    if not isinstance(pin, str) or not pin.strip():
+        raise CheckError(f"{manifest_path} has invalid pyright pin {pin!r}")
+    return pin.strip()
+
+
+def ci_cache_versions(ci_path: Path) -> list[str]:
+    """Extract every ``pyright-python-<version>`` cache-key version from ci.yml."""
+    versions = _CI_CACHE_KEY_RE.findall(ci_path.read_text(encoding="utf-8"))
+    if not versions:
+        raise CheckError(f"{ci_path} has no 'pyright-python-<version>-' cache key")
+    return versions
+
+
+def check(pyproject_path: Path, manifest_path: Path, ci_path: Path) -> str:
+    """Return the agreed pyright version, or raise CheckError on any drift."""
+    pyproject = pyproject_pin(pyproject_path)
+    manifest = manifest_pin(manifest_path)
+    ci_versions = ci_cache_versions(ci_path)
+
+    found = {
+        f"{pyproject_path} pin": pyproject,
+        f"{manifest_path} runtime pin": manifest,
+    }
+    for index, version in enumerate(ci_versions):
+        found[f"{ci_path} cache key #{index + 1}"] = version
+
+    distinct = set(found.values())
+    if len(distinct) > 1:
+        detail = ", ".join(f"{where}={version}" for where, version in found.items())
+        raise CheckError(f"pyright pin drift across {len(found)} sites: {detail}")
+    return pyproject
+
+
+def write(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8")
+
+
+def run_self_test() -> None:
+    pyproject_aligned = (
+        "[project]\n"
+        'name = "x"\n'
+        "[project.optional-dependencies]\n"
+        'dev = ["ruff==0.1.0", "pyright==1.1.409", "mypy==1.0"]\n'
+    )
+    manifest_aligned = '[capabilities.runtime.pyright]\npin = "1.1.409"\n'
+    ci_aligned = (
+        "key: pyright-python-1.1.409-${{ runner.os }}\n"
+        "key: pyright-python-1.1.409-${{ runner.os }}\n"
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        pyproject = root / "pyproject.toml"
+        manifest = root / "plugin.toml"
+        ci = root / "ci.yml"
+
+        write(pyproject, pyproject_aligned)
+        write(manifest, manifest_aligned)
+        write(ci, ci_aligned)
+        assert check(pyproject, manifest, ci) == "1.1.409"
+
+        # Manifest drift must fail.
+        write(manifest, '[capabilities.runtime.pyright]\npin = "1.1.410"\n')
+        _expect_drift(pyproject, manifest, ci)
+        write(manifest, manifest_aligned)
+
+        # A single stale CI cache key must fail.
+        write(
+            ci,
+            "key: pyright-python-1.1.409-${{ runner.os }}\n"
+            "key: pyright-python-1.1.400-${{ runner.os }}\n",
+        )
+        _expect_drift(pyproject, manifest, ci)
+        write(ci, ci_aligned)
+
+        # A missing pin must fail loudly, not pass vacuously.
+        write(
+            pyproject,
+            '[project]\nname = "x"\n[project.optional-dependencies]\ndev = ["ruff==0.1.0"]\n',
+        )
+        try:
+            check(pyproject, manifest, ci)
+        except CheckError as exc:
+            if "does not pin pyright" not in str(exc):
+                raise
+        else:
+            raise CheckError("self-test expected a missing pyright pin to fail")
+
+    print("pyright pin lockstep guard self-test passed")
+
+
+def _expect_drift(pyproject: Path, manifest: Path, ci: Path) -> None:
+    try:
+        check(pyproject, manifest, ci)
+    except CheckError as exc:
+        if "drift" not in str(exc):
+            raise
+    else:
+        raise CheckError("self-test expected pyright pin drift to fail")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Check pyright version pin lockstep")
+    parser.add_argument("--pyproject", type=Path, default=DEFAULT_PYPROJECT)
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument("--ci", type=Path, default=DEFAULT_CI)
+    parser.add_argument(
+        "--self-test", action="store_true", help="run built-in guard tests"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.self_test:
+            run_self_test()
+        else:
+            version = check(args.pyproject, args.manifest, args.ci)
+            print(f"pyright pin matches across pyproject, manifest, and CI: {version}")
+    except CheckError as exc:
+        print(f"pyright pin lockstep guard failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/check-wardline-version-bounds.py b/scripts/check-wardline-version-bounds.py
new file mode 100755
index 00000000..9d9294d3
--- /dev/null
+++ b/scripts/check-wardline-version-bounds.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Validate the Wardline integration version bounds in the Python plugin manifest.
+
+The Python plugin declares the Wardline version range it integrates against in
+``plugins/python/plugin.toml`` under ``[integrations.wardline]``:
+
+* ``min_version`` — inclusive lower bound (the oldest Wardline the plugin's
+  ``wardline.core.registry`` import surface is verified against).
+* ``max_version`` — exclusive upper bound, deliberately set to the next major
+  so a future major release triggers an explicit re-pin rather than silent
+  drift (see the comment in plugin.toml and loom.md §5 asterisk 2).
+
+This guard enforces the *local* half of the contract: both bounds are present,
+parse as semver, and form a sane half-open range ``[min, max)``. The
+*server-side* cross-check (confirming the resolved Wardline actually advertises
+a version inside the range at integration time) is future work — see
+``server_side_cross_check_hook`` for the documented seam.
+
+Closes V11-TEST-03 (docs/implementation/v1.0-tag-cut/gap-register.md).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import tempfile
+import tomllib
+from pathlib import Path
+
+DEFAULT_MANIFEST = Path("plugins/python/plugin.toml")
+
+# A core MAJOR.MINOR.PATCH semver, optionally with a -prerelease and/or +build.
+# We only order by the numeric core, which is all the bounds contract needs.
+_SEMVER_RE = re.compile(
+    r"^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)"
+    r"(?:-(?P<pre>[0-9A-Za-z.\-]+))?(?:\+(?P<build>[0-9A-Za-z.\-]+))?$"
+)
+
+
+class CheckError(Exception):
+    """Raised when the Wardline version-bounds guard fails."""
+
+
+def parse_semver(label: str, value: object) -> tuple[int, int, int]:
+    """Parse ``value`` as a semver core triple, raising CheckError on failure."""
+    if not isinstance(value, str) or not value.strip():
+        raise CheckError(f"{label} must be a non-empty semver string, got {value!r}")
+    match = _SEMVER_RE.match(value.strip())
+    if match is None:
+        raise CheckError(f"{label} is not valid semver: {value!r}")
+    return (int(match["major"]), int(match["minor"]), int(match["patch"]))
+
+
+def wardline_bounds(manifest_path: Path) -> tuple[str, str]:
+    """Return the raw (min_version, max_version) strings from the manifest."""
+    manifest = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    try:
+        section = manifest["integrations"]["wardline"]
+    except KeyError as exc:
+        raise CheckError(f"{manifest_path} is missing [integrations.wardline]") from exc
+    missing = [key for key in ("min_version", "max_version") if key not in section]
+    if missing:
+        raise CheckError(
+            f"{manifest_path} [integrations.wardline] is missing {', '.join(missing)}"
+        )
+    return str(section["min_version"]), str(section["max_version"])
+
+
+def check(manifest_path: Path) -> tuple[str, str]:
+    """Return (min, max) if the bounds are valid, else raise CheckError."""
+    raw_min, raw_max = wardline_bounds(manifest_path)
+    min_core = parse_semver("[integrations.wardline].min_version", raw_min)
+    max_core = parse_semver("[integrations.wardline].max_version", raw_max)
+    if min_core >= max_core:
+        raise CheckError(
+            "[integrations.wardline] bounds are not a half-open range [min, max): "
+            f"min_version={raw_min} must be strictly below max_version={raw_max}"
+        )
+    return raw_min, raw_max
+
+
+def server_side_cross_check_hook(resolved_version: str, manifest_path: Path) -> bool:
+    """Seam for the future server-side cross-check.
+
+    When Wardline can report its own version at integration time, the resolved
+    version should be confirmed to satisfy ``[min, max)`` here. Until then this
+    guard only enforces the locally-checkable invariants and this hook is not
+    wired into ``main``.
+    """
+    raw_min, raw_max = check(manifest_path)
+    resolved = parse_semver("resolved Wardline version", resolved_version)
+    return parse_semver("min", raw_min) <= resolved < parse_semver("max", raw_max)
+
+
+def write(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8")
+
+
+def run_self_test() -> None:
+    aligned = '[integrations.wardline]\nmin_version = "1.0.0"\nmax_version = "2.0.0"\n'
+
+    with tempfile.TemporaryDirectory() as tmp:
+        manifest = Path(tmp) / "plugin.toml"
+
+        write(manifest, aligned)
+        assert check(manifest) == ("1.0.0", "2.0.0")
+
+        # Inverted bounds must fail.
+        write(
+            manifest,
+            '[integrations.wardline]\nmin_version = "2.0.0"\nmax_version = "1.0.0"\n',
+        )
+        _expect(manifest, "half-open range")
+
+        # Equal bounds (empty range) must fail.
+        write(
+            manifest,
+            '[integrations.wardline]\nmin_version = "1.0.0"\nmax_version = "1.0.0"\n',
+        )
+        _expect(manifest, "half-open range")
+
+        # Non-semver bound must fail.
+        write(
+            manifest,
+            '[integrations.wardline]\nmin_version = "1.0" \nmax_version = "2.0.0"\n',
+        )
+        _expect(manifest, "not valid semver")
+
+        # A missing section must fail loudly, not pass vacuously.
+        write(manifest, "[ontology]\nx = 1\n")
+        _expect(manifest, "missing [integrations.wardline]")
+
+        # The cross-check hook accepts an in-range version and rejects out-of-range.
+        write(manifest, aligned)
+        assert server_side_cross_check_hook("1.4.2", manifest) is True
+        assert server_side_cross_check_hook("2.0.0", manifest) is False
+        assert server_side_cross_check_hook("0.9.0", manifest) is False
+
+    print("Wardline version-bounds guard self-test passed")
+
+
+def _expect(manifest: Path, needle: str) -> None:
+    try:
+        check(manifest)
+    except CheckError as exc:
+        if needle not in str(exc):
+            raise
+    else:
+        raise CheckError(f"self-test expected failure containing {needle!r}")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate Wardline integration version bounds"
+    )
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument(
+        "--self-test", action="store_true", help="run built-in guard tests"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.self_test:
+            run_self_test()
+        else:
+            raw_min, raw_max = check(args.manifest)
+            print(f"Wardline version bounds valid: [{raw_min}, {raw_max})")
+    except CheckError as exc:
+        print(f"Wardline version-bounds guard failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/check-workspace-version-lockstep.py b/scripts/check-workspace-version-lockstep.py
new file mode 100755
index 00000000..5997eafb
--- /dev/null
+++ b/scripts/check-workspace-version-lockstep.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Cross-workspace version lockstep guard.
+
+Asserts that the Rust workspace package version
+(`Cargo.toml [workspace.package].version`) matches the Python plugin's
+`[project].version` (`plugins/python/pyproject.toml`). The Python plugin
+manifest and `__init__.__version__` are already cross-checked by
+`plugins/python/tests/test_package.py`; this script catches the wider
+ecosystem-level drift (someone bumps Cargo but not the Python plugin, or
+vice versa) before a release tag is cut.
+
+Designed to run as a CI step on every PR — fast, no third-party deps,
+parses with the stdlib `tomllib` (Python 3.11+).
+
+Exit codes:
+    0  versions agree
+    1  versions disagree, or required keys are missing
+    2  usage / I/O error (e.g. file not found)
+
+The acceptable-drift policy in v1.0 is "no drift": the Rust workspace and
+Python plugin ship as a single product version. Post-1.0 patch releases
+that need divergent semver should drop the strict-equality check and
+replace it with a compatibility-bound check in the same script.
+"""
+
+from __future__ import annotations
+
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+CARGO_TOML = REPO_ROOT / "Cargo.toml"
+PYPROJECT_TOML = REPO_ROOT / "plugins/python/pyproject.toml"
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        print(f"check-workspace-version-lockstep: missing {path}", file=sys.stderr)
+        sys.exit(2)
+    return tomllib.loads(path.read_text(encoding="utf-8"))
+
+
+def _get_path(data: dict[str, Any], *keys: str) -> Any:
+    cursor: Any = data
+    for key in keys:
+        if not isinstance(cursor, dict) or key not in cursor:
+            path_repr = ".".join(keys)
+            print(
+                f"check-workspace-version-lockstep: key {path_repr!r} not found",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        cursor = cursor[key]
+    return cursor
+
+
+def main() -> int:
+    cargo = _read_toml(CARGO_TOML)
+    pyproject = _read_toml(PYPROJECT_TOML)
+
+    rust_version = _get_path(cargo, "workspace", "package", "version")
+    python_version = _get_path(pyproject, "project", "version")
+
+    if rust_version != python_version:
+        print(
+            "check-workspace-version-lockstep: drift detected",
+            file=sys.stderr,
+        )
+        print(f"  Cargo.toml [workspace.package].version = {rust_version!r}", file=sys.stderr)
+        print(f"  plugins/python/pyproject.toml [project].version = {python_version!r}", file=sys.stderr)
+        print(
+            "Bump them in lockstep, or split this guard into compatibility-bounded "
+            "ranges if v1.0+ wants divergent semver.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"check-workspace-version-lockstep: ok ({rust_version})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/e2e/external-operator-smoke.md b/tests/e2e/external-operator-smoke.md
new file mode 100644
index 00000000..8bbb9d27
--- /dev/null
+++ b/tests/e2e/external-operator-smoke.md
@@ -0,0 +1,117 @@
+# External-operator smoke test (publish gate)
+
+Source: WS-D of [thread-1-pre-publish-blockers.md](../../docs/implementation/v0.1-publish/thread-1-pre-publish-blockers.md#5-workstream-d--publish-gate-external-operator-smoke-test)
+and Filigree issue `clarion-3e0e481ef7`.
+
+The automated harness lives at
+[`external-operator-smoke.sh`](external-operator-smoke.sh). The operator
+runs that script and then fills in step 8 (the human-judgement part).
+This document is the procedure overview and the rationale for each step.
+
+## Purpose
+
+Verify that an outside operator, working from a fresh machine and reading
+**only** the top-level `README.md` and `docs/operator/getting-started.md`, can
+install Clarion, analyse a small public Python project, connect a consult-mode
+MCP client, ask substantive questions, re-run idempotently, and observe the
+pre-ingest secret-block fire on a planted credential.
+
+The test fails if any step requires reading source code outside of `README.md`
+and `docs/operator/getting-started.md`. A failure here is a B.1/B.2 docs bug,
+not a runtime defect.
+
+## How to run the harness
+
+### CI / repo-internal smoke (in-tree build)
+
+From the repo root on the target machine (Linux or macOS):
+
+```bash
+bash tests/e2e/external-operator-smoke.sh
+```
+
+The harness builds the workspace in release mode, installs the plugin into the
+editable venv at `plugins/python/.venv`, fetches the canonical corpus
+(`psf/requests` at the pinned tag), and walks steps 1–7. Step 8 is left for
+the operator to fill in. A draft results file is written to
+`tests/e2e/external-operator-smoke-results-YYYY-MM-DD-<host>.md`.
+
+### External-operator smoke (binary install)
+
+The outside-operator scenario assumes Clarion has been installed via the
+GitHub Release archive and the Python plugin via `pipx`. Tell the harness to
+skip the build step and point it at the operator-installed binaries:
+
+```bash
+export CARGO_BUILD=0
+export CLARION_BIN=/path/to/installed/clarion
+export CLARION_PLUGIN_BIN=/path/to/installed/clarion-plugin-python
+bash external-operator-smoke.sh        # script is published as a release asset
+```
+
+The script makes no other repo assumptions in this mode; the operator can run
+it from any directory.
+
+### Environment knobs
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CARGO_BUILD` | `1` | Build clarion + plugin from source. `0` skips. |
+| `CLARION_BIN` | (autodetected) | Path to the `clarion` binary. |
+| `CLARION_PLUGIN_BIN` | (autodetected) | Path to `clarion-plugin-python`. |
+| `CORPUS_REPO` | `https://github.com/psf/requests.git` | Public Python corpus to analyse. |
+| `CORPUS_REF` | `v2.32.3` | Pinned tag for reproducibility. |
+| `OPENROUTER_API_KEY` | unset | If unset, step 4.3(c) `summary` is skipped (not failed). |
+| `RESULTS_FILE` | `external-operator-smoke-results-<date>-<host>.md` | Override the output path. |
+
+## Test environment
+
+| Knob | Value |
+|---|---|
+| OS | `ubuntu:24.04` (or equivalent fresh image) for the canonical run; macOS for the platform-coverage run |
+| Operator | Someone (or a fresh agent session) with no prior knowledge of this repo |
+| Working dir | the harness creates its own `mktemp` scratch; the corpus is cloned there |
+| `OPENROUTER_API_KEY` | Required for step 4.3(c); other steps work without it |
+| Network | Outbound HTTPS to `api.openrouter.ai` and `github.com` (and PyPI/crates if installing from source) |
+
+## Steps
+
+The harness automates steps 1–7. Step 8 is human-judged and the operator
+fills it into the generated results file.
+
+| # | Step | Pass criteria | Automated? |
+|---|---|---|---|
+| 1 | Install the Rust binary per WS-C's chosen path (GitHub Releases per ADR-033) | `clarion --version` prints a version on `$PATH` | ✅ |
+| 2 | Install the Python plugin via `pipx` per the tutorial | `which clarion-plugin-python` resolves; the binary is on `$PATH` | ✅ |
+| 3 | `clarion install` against a small Python project (the harness uses `psf/requests` at a pinned tag) | `.clarion/` exists; `.clarion/clarion.db` exists; init log line emitted | ✅ |
+| 4.1 | `clarion analyze` | Exit 0; entity count > 0 | ✅ |
+| 4.2 | Start `clarion serve`; connect MCP client | MCP `tools/list` returns the 9 tools (`entity_at`, `find_entity`, `callers_of`, `execution_paths_from`, `summary`, `issues_for`, `neighborhood`, `subsystem_members`, `project_status`) | ✅ |
+| 4.3 | Three MCP queries against analyzed corpus: <br>(a) `find_entity(pattern="Session")` lists module-level matches <br>(b) `callers_of(id=<highest-in-degree function>)` returns a non-empty list <br>(c) `summary(id=<any function>)` returns a paragraph | (a) and (b) return non-empty; (c) returns a paragraph (live LLM) or is skipped when `OPENROUTER_API_KEY` is absent | ✅ |
+| 5 | Re-run `clarion analyze` | Idempotent: entity/edge counts on the second run match the first | ✅ |
+| 6 | Plant `.env` with `AWS_ACCESS_KEY_ID=AKIA0123456789ABCDEF`; re-run `clarion analyze` | `briefing_blocked` entities count > 0; `CLA-SEC-SECRET-DETECTED` finding emitted | ✅ |
+| 7 | `clarion serve` against the post-secret-block DB; call `summary(id)` on a blocked entity's id | Returns `briefing_blocked` envelope with no LLM call | ✅ |
+| 8 | Operator-improvisation tally | Total count of "I had to look at the source to understand what to do next" events. **Target: 0.** Any positive count is a B.1/B.2 docs bug. | ❌ (human-judged) |
+
+## Recording results
+
+The harness writes a Markdown report at
+`tests/e2e/external-operator-smoke-results-<date>-<host>.md` automatically.
+Steps 1–7 are populated with PASS/FAIL/SKIP and a one-line detail. The
+operator fills in:
+
+- Step 8 improvisation tally (count + per-event bullets)
+- Final attestation signature + date
+
+For a release gate, attach the completed report as a comment on Filigree
+issue `clarion-3e0e481ef7` (or `clarion-e464251ab3`, the renamed GOV-04
+issue) before closing.
+
+## Repeating on additional platforms
+
+The release matrix in
+[ADR-033](../../docs/clarion/adr/ADR-033-v1.0-distribution.md) produces
+`x86_64-unknown-linux-gnu`, `x86_64-apple-darwin`, and `aarch64-apple-darwin`
+binaries. Run the harness on at least one Linux target and one macOS target
+before the `v1.0.0` tag is treated as generally publishable. Each platform
+produces its own dated results file (the host tag is part of the default
+filename) — both must be archived before tag-cut.
diff --git a/tests/e2e/external-operator-smoke.sh b/tests/e2e/external-operator-smoke.sh
new file mode 100755
index 00000000..5bff3c56
--- /dev/null
+++ b/tests/e2e/external-operator-smoke.sh
@@ -0,0 +1,502 @@
+#!/usr/bin/env bash
+# External-operator smoke test (publish gate) — automated harness.
+#
+# Closes the technical half of GOV-04 (external-operator smoke evidence).
+# Steps 1–7 below are automated; step 8 (operator-improvisation tally)
+# remains a human judgement that the operator fills into the generated
+# results file.
+#
+# See tests/e2e/external-operator-smoke.md for the procedure and the
+# rationale for each step.
+#
+# Modes
+# -----
+# - `CARGO_BUILD=1` (default in repo CI): builds clarion + installs the
+#   plugin from the source tree, fetches the canonical corpus, runs the
+#   walkthrough, writes a results file.
+# - `CARGO_BUILD=0` + `CLARION_BIN=...` + `CLARION_PLUGIN_BIN=...`: skips
+#   the source build; expects the operator to have already installed
+#   clarion (via GitHub Release archive) and clarion-plugin-python (via
+#   pipx) on $PATH.
+#
+# Outputs
+# -------
+# Writes a results file at $RESULTS_DIR/external-operator-smoke-results-
+# YYYY-MM-DD-<host>.md. Steps 1–7 are auto-filled with PASS/FAIL/SKIP and
+# a stdout excerpt; step 8 is left as a TODO for the operator to fill in.
+#
+# Exit codes
+# ----------
+# 0 — all technical steps PASS (or explicit SKIPs were declared upfront).
+# 1 — any technical step FAILED.
+# 78 — soft-failure exit (matches `clarion analyze`'s soft-fail convention)
+#      reserved; not currently used but documented for future hardening.
+
+set -euo pipefail
+
+# -------- configuration --------
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+CARGO_BUILD="${CARGO_BUILD:-1}"
+RESULTS_DIR="${RESULTS_DIR:-$REPO_ROOT/tests/e2e}"
+VENV="${VENV:-$REPO_ROOT/plugins/python/.venv}"
+CORPUS_REPO="${CORPUS_REPO:-https://github.com/psf/requests.git}"
+CORPUS_REF="${CORPUS_REF:-v2.32.3}"
+
+DATE_STAMP="$(date -u +%Y-%m-%d)"
+HOST_TAG="$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)"
+RESULTS_FILE="${RESULTS_FILE:-$RESULTS_DIR/external-operator-smoke-results-${DATE_STAMP}-${HOST_TAG}.md}"
+
+# Allow OPENROUTER_API_KEY to be unset; step 4.3(c) skips cleanly.
+OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-}"
+
+log()  { printf '[smoke] %s\n' "$*" >&2; }
+fail() { printf '[smoke] FAIL: %s\n' "$*" >&2; exit 1; }
+
+# Per-step PASS/FAIL/SKIP tracking. step_status[i]="PASS" / "FAIL" / "SKIP".
+declare -A step_status
+declare -A step_detail
+
+record() {
+    local step="$1" status="$2" detail="$3"
+    step_status[$step]="$status"
+    step_detail[$step]="$detail"
+    log "step $step: $status — $detail"
+}
+
+# -------- preflight --------
+
+cd "$REPO_ROOT"
+
+if [ "$CARGO_BUILD" = "1" ]; then
+    log "preflight: building clarion (release) ..."
+    cargo build --workspace --release
+    CLARION_BIN="${CLARION_BIN:-$REPO_ROOT/target/release/clarion}"
+    if [ ! -d "$VENV" ]; then
+        log "preflight: creating plugin venv at $VENV ..."
+        python3 -m venv "$VENV"
+    fi
+    log "preflight: installing clarion-plugin-python (editable) ..."
+    "$VENV/bin/pip" install --quiet -e "$REPO_ROOT/plugins/python[dev]"
+    CLARION_PLUGIN_BIN="${CLARION_PLUGIN_BIN:-$VENV/bin/clarion-plugin-python}"
+    export PATH="$REPO_ROOT/target/release:$VENV/bin:$PATH"
+else
+    CLARION_BIN="${CLARION_BIN:-$(command -v clarion || true)}"
+    CLARION_PLUGIN_BIN="${CLARION_PLUGIN_BIN:-$(command -v clarion-plugin-python || true)}"
+fi
+
+[ -x "$CLARION_BIN" ] || fail "clarion binary missing at $CLARION_BIN (set CLARION_BIN= or CARGO_BUILD=1)"
+[ -x "$CLARION_PLUGIN_BIN" ] || fail "clarion-plugin-python missing at $CLARION_PLUGIN_BIN (set CLARION_PLUGIN_BIN= or CARGO_BUILD=1)"
+
+CLARION_VERSION="$("$CLARION_BIN" --version 2>&1 | head -1)"
+PLUGIN_VERSION="$("$CLARION_PLUGIN_BIN" --version 2>&1 | head -1 || true)"
+log "preflight: $CLARION_VERSION / $PLUGIN_VERSION"
+
+# Scratch directory for the corpus.
+WORK_DIR="$(mktemp -d -t clarion-smoke-XXXXXX)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+log "scratch: $WORK_DIR"
+
+# -------- step 1: clarion is on $PATH and --version works --------
+
+if [ -n "$CLARION_VERSION" ]; then
+    record "1" "PASS" "clarion --version: $CLARION_VERSION"
+else
+    record "1" "FAIL" "clarion --version produced no output"
+fi
+
+# -------- step 2: clarion-plugin-python on $PATH --------
+
+if [ -x "$CLARION_PLUGIN_BIN" ]; then
+    record "2" "PASS" "plugin binary at $CLARION_PLUGIN_BIN; $PLUGIN_VERSION"
+else
+    record "2" "FAIL" "plugin binary not found"
+fi
+
+# -------- step 3: clarion install against a small Python corpus --------
+
+log "fetching corpus $CORPUS_REPO @ $CORPUS_REF ..."
+cd "$WORK_DIR"
+if ! git clone --quiet --depth 1 --branch "$CORPUS_REF" "$CORPUS_REPO" corpus; then
+    record "3" "FAIL" "git clone of $CORPUS_REPO @ $CORPUS_REF failed"
+    fail "cannot proceed without corpus"
+fi
+cd corpus
+
+if "$CLARION_BIN" install >/dev/null 2>"$WORK_DIR/install.err"; then
+    if [ -f .clarion/clarion.db ]; then
+        record "3" "PASS" ".clarion/clarion.db created against psf/requests@$CORPUS_REF"
+    else
+        record "3" "FAIL" "install reported success but .clarion/clarion.db missing"
+    fi
+else
+    record "3" "FAIL" "clarion install exited non-zero: $(tr '\n' ' ' < "$WORK_DIR/install.err")"
+fi
+
+# -------- step 4.1: clarion analyze (initial) --------
+
+log "running clarion analyze ..."
+if "$CLARION_BIN" analyze . >"$WORK_DIR/analyze1.out" 2>"$WORK_DIR/analyze1.err"; then
+    ENTITY_COUNT_1="$(sqlite3 .clarion/clarion.db 'SELECT COUNT(*) FROM entities WHERE kind != "subsystem"' || echo 0)"
+    EDGE_COUNT_1="$(sqlite3 .clarion/clarion.db 'SELECT COUNT(*) FROM edges' || echo 0)"
+    if [ "$ENTITY_COUNT_1" -gt 0 ]; then
+        record "4.1" "PASS" "analyze ok; entities=$ENTITY_COUNT_1 edges=$EDGE_COUNT_1"
+    else
+        record "4.1" "FAIL" "analyze ok but entity count is 0"
+    fi
+else
+    record "4.1" "FAIL" "clarion analyze exited non-zero: $(tail -3 "$WORK_DIR/analyze1.err" | tr '\n' ' ')"
+fi
+
+# -------- step 4.2 + 4.3: clarion serve + MCP queries --------
+
+log "driving MCP stdio ..."
+MCP_REPORT="$WORK_DIR/mcp.json"
+PROJECT_DIR_FOR_PY="$WORK_DIR/corpus"
+CLARION_BIN_FOR_PY="$CLARION_BIN"
+
+set +e
+python3 - "$CLARION_BIN_FOR_PY" "$PROJECT_DIR_FOR_PY" "$MCP_REPORT" "${OPENROUTER_API_KEY:-NONE}" <<'PY'
+import json, sys, subprocess, sqlite3
+from pathlib import Path
+
+clarion_bin, project_dir, report_path, openrouter_key = sys.argv[1:5]
+project_dir = Path(project_dir)
+report = {"step_4_2": None, "step_4_3a": None, "step_4_3b": None, "step_4_3c": None,
+          "tools_listed": None, "find_entity_hits": None, "callers_of_hits": None,
+          "summary_envelope_kind": None, "summary_skipped_reason": None}
+
+def write_frame(proc, message):
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    proc.stdin.write(b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n")
+    proc.stdin.write(body)
+    proc.stdin.flush()
+
+def read_frame(proc):
+    headers = {}
+    while True:
+        line = proc.stdout.readline()
+        if not line:
+            stderr = proc.stderr.read().decode("utf-8", "replace")
+            raise AssertionError(f"server closed stdout; stderr={stderr}")
+        if line == b"\r\n":
+            break
+        k, v = line.decode("ascii").strip().split(":", 1)
+        headers[k.lower()] = v.strip()
+    return json.loads(proc.stdout.read(int(headers["content-length"])))
+
+def tool_call(proc, rid, name, args):
+    write_frame(proc, {"jsonrpc": "2.0", "id": rid, "method": "tools/call",
+                       "params": {"name": name, "arguments": args}})
+    return read_frame(proc)
+
+# Pick a real entity from the analyzed corpus to test against.
+conn = sqlite3.connect(project_dir / ".clarion" / "clarion.db")
+ent = conn.execute("""
+    SELECT id, kind, name FROM entities
+    WHERE kind = 'function' AND name = 'get'
+    AND id LIKE 'python:function:%'
+    LIMIT 1
+""").fetchone()
+if not ent:
+    ent = conn.execute("""
+        SELECT id, kind, name FROM entities
+        WHERE kind = 'function' LIMIT 1
+    """).fetchone()
+session_ent = conn.execute("""
+    SELECT id FROM entities WHERE kind = 'class' AND name = 'Session' LIMIT 1
+""").fetchone()
+conn.close()
+
+if not ent:
+    report["step_4_2"] = "FAIL: no function entities to query"
+    Path(report_path).write_text(json.dumps(report))
+    sys.exit(2)
+
+proc = subprocess.Popen([clarion_bin, "serve"],
+                       stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                       stderr=subprocess.PIPE, cwd=str(project_dir))
+
+try:
+    # MCP initialize
+    write_frame(proc, {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                       "params": {"protocolVersion": "2024-11-05",
+                                  "capabilities": {},
+                                  "clientInfo": {"name": "smoke", "version": "1"}}})
+    read_frame(proc)
+    write_frame(proc, {"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    # tools/list
+    write_frame(proc, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+    listed = read_frame(proc)
+    tools = [t["name"] for t in listed.get("result", {}).get("tools", [])]
+    required = {"entity_at", "find_entity", "callers_of", "execution_paths_from",
+                "summary", "issues_for", "neighborhood", "subsystem_members",
+                "project_status"}
+    if required.issubset(set(tools)):
+        report["step_4_2"] = f"PASS: tools/list returned {len(tools)} tools including all {len(required)} required"
+    else:
+        missing = required - set(tools)
+        report["step_4_2"] = f"FAIL: tools/list missing {sorted(missing)}"
+    report["tools_listed"] = tools
+
+    def unwrap(envelope):
+        """Clarion MCP envelope wraps the tool payload under `result`."""
+        return envelope.get("result") if isinstance(envelope, dict) else None
+
+    # 4.3(a) find_entity
+    pattern = "Session" if session_ent else ent[2]
+    fe = tool_call(proc, 3, "find_entity", {"pattern": pattern, "limit": 5})
+    fe_body = json.loads(fe["result"]["content"][0]["text"])
+    inner = unwrap(fe_body) or {}
+    matches = inner.get("entities") or inner.get("matches") or inner.get("results") or []
+    report["find_entity_hits"] = len(matches)
+    report["step_4_3a"] = (f"PASS: find_entity('{pattern}') returned {len(matches)} matches"
+                          if matches else f"FAIL: find_entity('{pattern}') returned empty (envelope: {fe_body})")
+
+    # 4.3(b) callers_of — find a function with at least one caller.
+    conn2 = sqlite3.connect(project_dir / ".clarion" / "clarion.db")
+    row = conn2.execute("""
+        SELECT e.id, COUNT(*) AS c FROM entities e
+        JOIN edges ed ON ed.to_id = e.id
+        WHERE e.kind = 'function' AND ed.kind = 'calls'
+        GROUP BY e.id ORDER BY c DESC LIMIT 1
+    """).fetchone()
+    conn2.close()
+    if not row:
+        report["step_4_3b"] = "FAIL: no `calls` edges in the analyzed graph"
+    else:
+        callers_target = row[0]
+        co = tool_call(proc, 4, "callers_of", {"id": callers_target, "limit": 5})
+        co_body = json.loads(co["result"]["content"][0]["text"])
+        co_inner = unwrap(co_body) or {}
+        callers = co_inner.get("callers") or []
+        report["callers_of_hits"] = len(callers)
+        if callers:
+            report["step_4_3b"] = f"PASS: callers_of('{callers_target}') returned {len(callers)} callers"
+        else:
+            report["step_4_3b"] = f"FAIL: callers_of('{callers_target}') returned empty (envelope: {co_body})"
+
+    # 4.3(c) summary — only runs if OPENROUTER_API_KEY is set
+    if openrouter_key and openrouter_key != "NONE":
+        sm = tool_call(proc, 6, "summary", {"id": ent[0]})
+        sm_body = json.loads(sm["result"]["content"][0]["text"])
+        sm_inner = unwrap(sm_body) or {}
+        if sm_body.get("ok") and (sm_inner.get("summary") or sm_inner.get("available") is True):
+            report["summary_envelope_kind"] = "live"
+            report["step_4_3c"] = f"PASS: live summary for {ent[0]} returned non-empty"
+        else:
+            report["summary_envelope_kind"] = "live-empty"
+            report["step_4_3c"] = f"FAIL: summary call ran but envelope had no usable payload: {sm_body}"
+    else:
+        report["step_4_3c"] = "SKIP: OPENROUTER_API_KEY not set"
+        report["summary_skipped_reason"] = "no api key"
+
+finally:
+    try:
+        proc.stdin.close()
+    except Exception:
+        pass
+    proc.wait(timeout=10)
+
+Path(report_path).write_text(json.dumps(report, indent=2))
+PY
+MCP_RC=$?
+set -e
+
+if [ "$MCP_RC" -ne 0 ]; then
+    record "4.2" "FAIL" "MCP harness exited with code $MCP_RC"
+    record "4.3a" "FAIL" "MCP harness failed before query a"
+    record "4.3b" "FAIL" "MCP harness failed before query b"
+    record "4.3c" "FAIL" "MCP harness failed before query c"
+else
+    # shellcheck disable=SC2002
+    REPORT_JSON="$(cat "$MCP_REPORT")"
+    parse_field() { python3 -c "import json,sys; print(json.loads(sys.argv[1]).get(sys.argv[2]) or '')" "$REPORT_JSON" "$1"; }
+    record "4.2" "$(parse_field step_4_2 | cut -d: -f1)" "$(parse_field step_4_2)"
+    record "4.3a" "$(parse_field step_4_3a | cut -d: -f1)" "$(parse_field step_4_3a)"
+    record "4.3b" "$(parse_field step_4_3b | cut -d: -f1)" "$(parse_field step_4_3b)"
+    case "$(parse_field step_4_3c)" in
+        PASS*) record "4.3c" "PASS" "$(parse_field step_4_3c)" ;;
+        FAIL*) record "4.3c" "FAIL" "$(parse_field step_4_3c)" ;;
+        SKIP*) record "4.3c" "SKIP" "$(parse_field step_4_3c)" ;;
+        *)     record "4.3c" "FAIL" "unknown summary state: $(parse_field step_4_3c)" ;;
+    esac
+fi
+
+# -------- step 5: re-run analyze for idempotency --------
+
+log "running clarion analyze (re-run for idempotency) ..."
+if "$CLARION_BIN" analyze . >"$WORK_DIR/analyze2.out" 2>"$WORK_DIR/analyze2.err"; then
+    ENTITY_COUNT_2="$(sqlite3 .clarion/clarion.db 'SELECT COUNT(*) FROM entities WHERE kind != "subsystem"')"
+    EDGE_COUNT_2="$(sqlite3 .clarion/clarion.db 'SELECT COUNT(*) FROM edges')"
+    if [ "$ENTITY_COUNT_2" = "$ENTITY_COUNT_1" ] && [ "$EDGE_COUNT_2" = "$EDGE_COUNT_1" ]; then
+        record "5" "PASS" "idempotent: entities=$ENTITY_COUNT_2 edges=$EDGE_COUNT_2 unchanged"
+    else
+        record "5" "FAIL" "non-idempotent: entities $ENTITY_COUNT_1 -> $ENTITY_COUNT_2, edges $EDGE_COUNT_1 -> $EDGE_COUNT_2"
+    fi
+else
+    record "5" "FAIL" "re-run analyze exited non-zero"
+fi
+
+# -------- step 6: plant secret + re-run analyze; verify briefing_blocked --------
+
+log "planting .env with fake AWS credential; re-running analyze ..."
+cat > .env <<'ENV'
+AWS_ACCESS_KEY_ID=AKIA0123456789ABCDEF
+AWS_SECRET_ACCESS_KEY=examplefakefakefakefakefakefakefakefake1234
+ENV
+
+ANALYZE_3_EXIT=0
+"$CLARION_BIN" analyze . >"$WORK_DIR/analyze3.out" 2>"$WORK_DIR/analyze3.err" || ANALYZE_3_EXIT=$?
+
+# Expected: soft-failure (exit 78) or success with briefing_blocked recorded.
+BLOCKED_COUNT="$(sqlite3 .clarion/clarion.db "SELECT COUNT(*) FROM entities WHERE json_extract(properties, '\$.briefing_blocked') IS NOT NULL" 2>/dev/null || echo 0)"
+FINDING_COUNT="$(sqlite3 .clarion/clarion.db "SELECT COUNT(*) FROM findings WHERE rule_id = 'CLA-SEC-SECRET-DETECTED'" 2>/dev/null || echo 0)"
+
+if [ "$BLOCKED_COUNT" -gt 0 ] && [ "$FINDING_COUNT" -gt 0 ]; then
+    record "6" "PASS" "post-plant: $BLOCKED_COUNT blocked entities, $FINDING_COUNT secret findings (analyze exit $ANALYZE_3_EXIT)"
+elif [ "$BLOCKED_COUNT" -gt 0 ]; then
+    record "6" "PASS" "post-plant: $BLOCKED_COUNT blocked entities (no CLA-SEC-SECRET-DETECTED finding rows; finding code may have changed)"
+elif [ "$FINDING_COUNT" -gt 0 ]; then
+    record "6" "FAIL" "secret finding emitted but no entity marked briefing_blocked"
+else
+    record "6" "FAIL" "no briefing_blocked entities and no CLA-SEC-SECRET-DETECTED finding after planting"
+fi
+
+# -------- step 7: serve against post-block DB; summary on blocked entity returns blocked envelope --------
+
+if [ "$BLOCKED_COUNT" -gt 0 ]; then
+    log "verifying blocked-entity summary refusal ..."
+    BLOCKED_ID="$(sqlite3 .clarion/clarion.db "SELECT id FROM entities WHERE json_extract(properties, '\$.briefing_blocked') IS NOT NULL LIMIT 1")"
+    if [ -n "$BLOCKED_ID" ]; then
+        set +e
+        python3 - "$CLARION_BIN" "$WORK_DIR/corpus" "$BLOCKED_ID" "$WORK_DIR/step7.json" <<'PY'
+import json, sys, subprocess
+from pathlib import Path
+
+clarion_bin, project_dir, blocked_id, out_path = sys.argv[1:5]
+
+def write_frame(proc, message):
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    proc.stdin.write(b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n")
+    proc.stdin.write(body)
+    proc.stdin.flush()
+
+def read_frame(proc):
+    headers = {}
+    while True:
+        line = proc.stdout.readline()
+        if not line: raise AssertionError("eof")
+        if line == b"\r\n": break
+        k, v = line.decode("ascii").strip().split(":", 1)
+        headers[k.lower()] = v.strip()
+    return json.loads(proc.stdout.read(int(headers["content-length"])))
+
+proc = subprocess.Popen([clarion_bin, "serve"],
+                       stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                       stderr=subprocess.PIPE, cwd=project_dir)
+try:
+    write_frame(proc, {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                       "params": {"protocolVersion": "2024-11-05",
+                                  "capabilities": {},
+                                  "clientInfo": {"name": "smoke", "version": "1"}}})
+    read_frame(proc)
+    write_frame(proc, {"jsonrpc": "2.0", "method": "notifications/initialized"})
+    write_frame(proc, {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
+                       "params": {"name": "summary", "arguments": {"id": blocked_id}}})
+    resp = read_frame(proc)
+    body = json.loads(resp["result"]["content"][0]["text"])
+    inner = body.get("result") if isinstance(body, dict) else None
+    blocked = bool(inner and inner.get("briefing_blocked"))
+    Path(out_path).write_text(json.dumps({"blocked": blocked, "envelope": body}, indent=2))
+finally:
+    try: proc.stdin.close()
+    except Exception: pass
+    proc.wait(timeout=10)
+PY
+        STEP7_RC=$?
+        set -e
+        if [ "$STEP7_RC" -eq 0 ] && python3 -c "import json,sys;sys.exit(0 if json.loads(open(sys.argv[1]).read()).get('blocked') else 1)" "$WORK_DIR/step7.json"; then
+            record "7" "PASS" "summary on blocked entity '$BLOCKED_ID' returned briefing-blocked envelope (no LLM call)"
+        else
+            record "7" "FAIL" "summary on blocked entity did not return briefing-blocked envelope"
+        fi
+    else
+        record "7" "FAIL" "blocked count > 0 but could not select an id"
+    fi
+else
+    record "7" "SKIP" "skipped because step 6 found no blocked entities"
+fi
+
+# -------- step 8: operator-improvisation tally (human-judged) --------
+
+record "8" "TODO" "operator must fill in: count of source-reads outside README + getting-started"
+
+# -------- write results file --------
+
+log "writing results to $RESULTS_FILE ..."
+mkdir -p "$(dirname "$RESULTS_FILE")"
+{
+    echo "# External-operator smoke result"
+    echo
+    echo "**Date (UTC)**: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo "**Host**: $(uname -srm)"
+    echo "**Clarion**: $CLARION_VERSION"
+    echo "**Plugin**: $PLUGIN_VERSION"
+    echo "**Corpus**: $CORPUS_REPO @ $CORPUS_REF"
+    echo "**Mode**: $([ "$CARGO_BUILD" = "1" ] && echo "in-repo build (CARGO_BUILD=1)" || echo "external binary")"
+    echo
+    echo "## Step results"
+    echo
+    echo "| # | Step | Status | Detail |"
+    echo "|---|------|--------|--------|"
+    for step in 1 2 3 4.1 4.2 4.3a 4.3b 4.3c 5 6 7 8; do
+        echo "| $step | $(grep -A1 "^| $step " tests/e2e/external-operator-smoke.md 2>/dev/null | head -1 | cut -d'|' -f3 | sed 's/^ *//;s/ *$//' || echo "see md") | ${step_status[$step]:-MISSING} | ${step_detail[$step]:-} |"
+    done
+    echo
+    echo "## Step 8 (operator-fill)"
+    echo
+    echo "Improvisation tally: TODO — record the count of moments where you (the operator)"
+    echo "had to read source code outside \`README.md\` and \`docs/operator/getting-started.md\`"
+    echo "to know what to do next."
+    echo
+    echo "Target: 0. Any non-zero count is a B.1/B.2 docs bug, not a runtime defect."
+    echo
+    echo "Improvisation events observed:"
+    echo
+    echo "- [ ] (fill in below; one bullet per event)"
+    echo
+    echo "## Verdict"
+    echo
+    echo "**Technical** (steps 1–7): set automatically by this harness."
+    echo
+    echo "**Operator** (step 8): fill in after walking through the procedure."
+    echo
+    echo "**Gate passed**: only if all non-skip steps PASS *and* the operator improvisation"
+    echo "tally is 0."
+    echo
+    echo "## Attestation"
+    echo
+    echo "_Sign off (operator name, date) once step 8 is filled in:_"
+    echo
+    echo "Signed: TODO"
+    echo "Date: TODO"
+} > "$RESULTS_FILE"
+
+# -------- final exit code --------
+
+FAIL_COUNT=0
+for step in 1 2 3 4.1 4.2 4.3a 4.3b 4.3c 5 6 7; do
+    if [ "${step_status[$step]:-}" = "FAIL" ]; then
+        FAIL_COUNT=$((FAIL_COUNT+1))
+    fi
+done
+
+if [ "$FAIL_COUNT" -gt 0 ]; then
+    log "FAIL: $FAIL_COUNT technical step(s) did not pass. Results: $RESULTS_FILE"
+    exit 1
+fi
+
+log "PASS: all technical steps passed (1–7). Results: $RESULTS_FILE"
+log "     Operator must still fill in step 8 (improvisation tally) before declaring the gate green."
diff --git a/tests/e2e/sprint_1_walking_skeleton.sh b/tests/e2e/sprint_1_walking_skeleton.sh
index e7f41afb..11a9690a 100755
--- a/tests/e2e/sprint_1_walking_skeleton.sh
+++ b/tests/e2e/sprint_1_walking_skeleton.sh
@@ -88,13 +88,24 @@ clarion install
 log "running: clarion analyze ."
 clarion analyze .
 
+# ── 6b. Verify database integrity (STO-04) ───────────────────────────────────
+log "verifying database integrity via PRAGMA integrity_check ..."
+INTEGRITY=$(sqlite3 "$DEMO_DIR/.clarion/clarion.db" "PRAGMA integrity_check;")
+if [ "$INTEGRITY" != "ok" ]; then
+    log "integrity_check output:"
+    printf '%s\n' "$INTEGRITY" >&2
+    fail "expected PRAGMA integrity_check to report exactly 'ok'; got $INTEGRITY"
+fi
+
 # ── 7. Verify entity via sqlite3 ─────────────────────────────────────────────
 log "verifying persisted entity via sqlite3 ..."
 RESULT=$(sqlite3 "$DEMO_DIR/.clarion/clarion.db" "select id, kind from entities order by id;")
 # B.2 (Sprint 2): every analyzed file emits a module entity in addition to
-# its function/class entities. B.4* adds direct and dict-dispatch call sites.
+# its function/class entities. v1.0 also mints a core file entity for file
+# identity and federation reads. B.4* adds direct and dict-dispatch call sites.
 # B.5* adds a local annotation reference and a module-level name reference.
-EXPECTED="python:class:demo.Marker|class
+EXPECTED="core:file:demo.py|file
+python:class:demo.Marker|class
 python:function:demo.annotated|function
 python:function:demo.hello|function
 python:function:demo.via_dispatch|function
diff --git a/tests/e2e/sprint_2_mcp_surface.sh b/tests/e2e/sprint_2_mcp_surface.sh
index 5d76072f..dc69ed91 100755
--- a/tests/e2e/sprint_2_mcp_surface.sh
+++ b/tests/e2e/sprint_2_mcp_surface.sh
@@ -3,7 +3,7 @@
 #
 # Builds a real demo Clarion database through `clarion analyze`, starts
 # `clarion serve`, and sends Content-Length framed MCP JSON-RPC requests for
-# the eight MCP navigation tools. Filigree is represented by a local HTTP
+# the MCP navigation tools. Filigree is represented by a local HTTP
 # server that implements the B.7 reverse entity-association route.
 
 set -euo pipefail
@@ -359,6 +359,39 @@ requests: list[tuple[str, dict[str, object]]] = [
             "params": {"name": "issues_for", "arguments": {"id": "python:module:demo"}},
         },
     ),
+    (
+        "source-for-entity",
+        {
+            "jsonrpc": "2.0",
+            "id": "source-for-entity",
+            "method": "tools/call",
+            "params": {
+                "name": "source_for_entity",
+                "arguments": {"id": "python:function:demo.hello", "context_lines": 1},
+            },
+        },
+    ),
+    (
+        "call-sites",
+        {
+            "jsonrpc": "2.0",
+            "id": "call-sites",
+            "method": "tools/call",
+            "params": {
+                "name": "call_sites",
+                "arguments": {"id": "python:function:demo.hello", "role": "caller"},
+            },
+        },
+    ),
+    (
+        "context",
+        {
+            "jsonrpc": "2.0",
+            "id": "context",
+            "method": "resources/read",
+            "params": {"uri": "clarion://context"},
+        },
+    ),
 ]
 
 responses: dict[str, dict[str, object]] = {}
@@ -377,9 +410,13 @@ finally:
     assert status == 0, f"clarion serve exited {status}; stderr={stderr}"
 
 assert responses["initialize"]["result"]["protocolVersion"] == "2025-11-25"
+init_result = responses["initialize"]["result"]
+assert "clarion-workflow" in init_result["instructions"], init_result.get("instructions")
+assert isinstance(init_result["capabilities"]["resources"], dict), init_result["capabilities"]
+assert isinstance(init_result["capabilities"]["prompts"], dict), init_result["capabilities"]
 tools = responses["tools"]["result"]["tools"]
-assert len(tools) == 8, tools
-assert [tool["name"] for tool in tools] == [
+tool_names = [tool["name"] for tool in tools]
+assert tool_names == [
     "entity_at",
     "find_entity",
     "callers_of",
@@ -388,7 +425,23 @@ assert [tool["name"] for tool in tools] == [
     "issues_for",
     "neighborhood",
     "subsystem_members",
-]
+    "subsystem_of",
+    "project_status",
+    "summary_preview_cost",
+    "source_for_entity",
+    "call_sites",
+    "orientation_pack",
+    "analyze_start",
+    "analyze_status",
+    "analyze_cancel",
+    "index_diff",
+], tool_names
+# Single-source check (clarion-71f0d6c3dd): the initialize `instructions` tool
+# enumeration is derived from list_tools(), so every advertised tool must appear
+# in it. This catches drift between the tool set and the orientation prose
+# without a second hardcoded list.
+for name in tool_names:
+    assert name in init_result["instructions"], (name, init_result["instructions"])
 assert "leaf scope only" in tools[4]["description"]
 
 entity_hit = assert_tool_ok(responses["entity-hit"])
@@ -398,6 +451,25 @@ assert entity_hit["truncated"] is False
 entity_miss = assert_tool_ok(responses["entity-miss"])
 assert entity_miss["result"]["entity"] is None, entity_miss
 
+source_for_entity = assert_tool_ok(responses["source-for-entity"])
+sfe_result = source_for_entity["result"]
+assert sfe_result["source_status"] == "ok", source_for_entity
+assert sfe_result["entity"]["id"] == "python:function:demo.hello", source_for_entity
+# Line-numbered lines, with the entity's own lines flagged in_entity=True.
+sfe_lines = sfe_result["lines"]
+assert sfe_lines, source_for_entity
+assert all("number" in line and "in_entity" in line for line in sfe_lines), source_for_entity
+assert any(line["in_entity"] for line in sfe_lines), source_for_entity
+
+call_sites = assert_tool_ok(responses["call-sites"])
+cs_result = call_sites["result"]
+assert cs_result["role"] == "caller", call_sites
+assert "sites" in cs_result and "unresolved_sites" in cs_result, call_sites
+# Every resolved site carries its edge kind, confidence, and source line text.
+for site in cs_result["sites"]:
+    assert site["edge_kind"] in ("calls", "references"), call_sites
+    assert "confidence" in site and "line_text" in site, call_sites
+
 find_result = assert_tool_ok(responses["find"])
 assert len(find_result["result"]["entities"]) == 2, find_result
 assert find_result["result"]["next_cursor"] == "2", find_result
@@ -412,8 +484,14 @@ ambiguous_ids = {item["entity"]["id"] for item in ambiguous_callers["result"]["c
 assert "python:function:demo.via_dispatch" in ambiguous_ids, ambiguous_callers
 
 paths = assert_tool_ok(responses["paths"])
-path_ids = [[node["id"] for node in path] for path in paths["result"]["paths"]]
+# Compact shape (clarion-5b3eff9a91): paths are arrays of node-id strings into a
+# deduplicated node table; the queried entity is echoed as root.
+path_ids = paths["result"]["paths"]
 assert ["python:function:demo.hello", "python:function:demo.world"] in path_ids, paths
+assert paths["result"]["root"] == "python:function:demo.hello", paths
+node_ids = {node["id"] for node in paths["result"]["nodes"]}
+assert "python:function:demo.world" in node_ids, paths
+assert all("content_hash" not in node for node in paths["result"]["nodes"]), paths
 assert paths["truncated"] is False, paths
 
 neighborhood = assert_tool_ok(responses["neighborhood"])
@@ -436,9 +514,25 @@ matched_ids = {item["issue_id"] for item in issues["result"]["matched"]}
 drifted_ids = {item["issue_id"] for item in issues["result"]["drifted"]}
 assert "filigree-world" in matched_ids, issues
 assert "filigree-hello-drifted" in drifted_ids, issues
+# issues_for surfaces the resolved Filigree endpoint + a result_kind taxonomy
+# (clarion-318f1254eb): a populated result is "matched" and reports the endpoint
+# it was served from.
+assert issues["result"]["result_kind"] == "matched", issues
+assert issues["result"]["filigree_endpoint"]["enabled"] is True, issues
+assert issues["result"]["filigree_endpoint"]["resolved_url"], issues
 assert issues["stats_delta"]["filigree_requests_total"] >= 2, issues
 assert "python:function:demo.world" in filigree_requests, filigree_requests
 assert "python:function:demo.hello" in filigree_requests, filigree_requests
+
+context = responses["context"]["result"]
+ctx_text = context["contents"][0]["text"]
+ctx = json.loads(ctx_text)
+assert ctx["db_present"] is True, ctx
+assert ctx["entity_count"] >= 1, ctx
+assert "staleness" in ctx, ctx
+# A live, healthy snapshot must report degraded=false; the field is always
+# present so a consumer can tell a broken read from a genuinely empty index.
+assert ctx["degraded"] is False, ctx
 PY
 
-log "PASS: MCP stdio surface returned eight tool definitions and seven tool responses"
+log "PASS: MCP stdio surface returned eighteen tool definitions and nine tool responses"
diff --git a/tests/e2e/wp5_secret_scan.sh b/tests/e2e/wp5_secret_scan.sh
new file mode 100755
index 00000000..0365ac41
--- /dev/null
+++ b/tests/e2e/wp5_secret_scan.sh
@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# WP5 pre-ingest secret-scanner end-to-end smoke.
+
+set -euo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel)}"
+CARGO_BUILD="${CARGO_BUILD:-1}"
+
+log() { printf '[wp5-secret-scan] %s\n' "$*" >&2; }
+fail() { printf '[wp5-secret-scan] FAIL: %s\n' "$*" >&2; exit 1; }
+
+cd "$REPO_ROOT"
+
+if [ "$CARGO_BUILD" = "1" ]; then
+    log "building clarion (release) ..."
+    cargo build --workspace --release
+fi
+
+CLARION_BIN="$REPO_ROOT/target/release/clarion"
+[ -x "$CLARION_BIN" ] || fail "clarion binary missing at $CLARION_BIN"
+
+DEMO_DIR="$(mktemp -d -t clarion-wp5-demo-XXXXXX)"
+PLUGIN_DIR="$(mktemp -d -t clarion-wp5-plugin-XXXXXX)"
+trap 'rm -rf "$DEMO_DIR" "$PLUGIN_DIR"' EXIT
+
+cat > "$PLUGIN_DIR/clarion-plugin-secretfixture" <<'PY'
+#!/usr/bin/python3
+import json
+import pathlib
+import re
+import sys
+
+def read_frame():
+    headers = {}
+    while True:
+        line = sys.stdin.buffer.readline()
+        if line in (b"", b"\r\n"):
+            break
+        name, value = line.decode("ascii").strip().split(":", 1)
+        headers[name.lower()] = value.strip()
+    length = int(headers["content-length"])
+    return json.loads(sys.stdin.buffer.read(length))
+
+def write_frame(message):
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    sys.stdout.buffer.write(b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n")
+    sys.stdout.buffer.write(body)
+    sys.stdout.buffer.flush()
+
+while True:
+    msg = read_frame()
+    method = msg.get("method")
+    if method == "initialized":
+        continue
+    if method == "exit":
+        raise SystemExit(0)
+    ident = msg["id"]
+    if method == "initialize":
+        write_frame({"jsonrpc":"2.0","id":ident,"result":{"name":"clarion-plugin-secretfixture","version":"0.1.0","ontology_version":"0.1.0","capabilities":{}}})
+    elif method == "analyze_file":
+        path = msg["params"]["file_path"]
+        name = "file_" + re.sub(r"[^A-Za-z0-9_]", "_", pathlib.Path(path).name)
+        write_frame({"jsonrpc":"2.0","id":ident,"result":{"entities":[{"id":"secretfixture:module:"+name,"kind":"module","qualified_name":name,"source":{"file_path":path}}],"edges":[]}})
+    elif method == "shutdown":
+        write_frame({"jsonrpc":"2.0","id":ident,"result":{}})
+    else:
+        raise SystemExit(1)
+PY
+chmod 755 "$PLUGIN_DIR/clarion-plugin-secretfixture"
+
+cat > "$PLUGIN_DIR/plugin.toml" <<'TOML'
+[plugin]
+name = "clarion-plugin-secretfixture"
+plugin_id = "secretfixture"
+version = "0.1.0"
+protocol_version = "1.0"
+executable = "clarion-plugin-secretfixture"
+language = "secretfixture"
+extensions = ["sec"]
+
+[capabilities.runtime]
+expected_max_rss_mb = 256
+expected_entities_per_file = 100
+wardline_aware = false
+reads_outside_project_root = false
+
+[ontology]
+entity_kinds = ["module"]
+edge_kinds = []
+rule_id_prefix = "CLA-SECRET-FIXTURE-"
+ontology_version = "0.1.0"
+TOML
+
+log "scratch project: $DEMO_DIR"
+"$CLARION_BIN" install --path "$DEMO_DIR"
+printf "aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n" > "$DEMO_DIR/leaky.sec"
+printf "aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n" > "$DEMO_DIR/.env"
+
+PATH="$PLUGIN_DIR" "$CLARION_BIN" analyze "$DEMO_DIR"
+
+DB="$DEMO_DIR/.clarion/clarion.db"
+BLOCKED=$(sqlite3 "$DB" "select count(*) from entities where json_extract(properties, '\$.briefing_blocked') = 'secret_present';")
+[ "$BLOCKED" = "3" ] || fail "expected three briefing_blocked secret_present entities (core file + plugin source entity + dotenv anchor), got $BLOCKED"
+
+FINDINGS=$(sqlite3 "$DB" "select count(*) from findings where rule_id = 'CLA-SEC-SECRET-DETECTED';")
+[ "$FINDINGS" = "2" ] || fail "expected two CLA-SEC-SECRET-DETECTED findings, got $FINDINGS"
+
+DOTENV_ANCHOR=$(sqlite3 "$DB" "select count(*) from entities where plugin_id = 'core' and kind = 'file' and source_file_path = '$DEMO_DIR/.env' and json_extract(properties, '\$.briefing_blocked') = 'secret_present';")
+[ "$DOTENV_ANCHOR" = "1" ] || fail "expected .env core file anchor with briefing_blocked secret_present, got $DOTENV_ANCHOR"
+
+RUN_STATUS=$(sqlite3 "$DB" "select status from runs;")
+[ "$RUN_STATUS" = "completed" ] || fail "expected completed run, got $RUN_STATUS"
+
+log "PASS: WP5 secret scan blocks summaries and records finding"
+
+# ----------------------------------------------------------------------------
+# baseline-suppression flow (clarion-55fc5aa885 §I11)
+# ----------------------------------------------------------------------------
+log "scenario: baseline-suppressed detection emits BASELINE-MATCH only, no block"
+BASELINE_DIR="$(mktemp -d -t clarion-wp5-baseline-XXXXXX)"
+trap 'rm -rf "$DEMO_DIR" "$PLUGIN_DIR" "$BASELINE_DIR" "$OVERRIDE_DIR" "$MALFORMED_DIR"' EXIT
+"$CLARION_BIN" install --path "$BASELINE_DIR"
+printf "aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n" > "$BASELINE_DIR/leaky.sec"
+HASHED_SECRET=$(printf 'AKIAIOSFODNN7EXAMPLE' | sha1sum | awk '{print $1}')
+cat > "$BASELINE_DIR/.clarion/secrets-baseline.yaml" <<YAML
+version: "1.0"
+results:
+  "leaky.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "$HASHED_SECRET"
+      line_number: 1
+      is_secret: false
+      justification: "Documented public AWS example key, not a credential."
+YAML
+PATH="$PLUGIN_DIR" "$CLARION_BIN" analyze "$BASELINE_DIR"
+BDB="$BASELINE_DIR/.clarion/clarion.db"
+B_BLOCKED=$(sqlite3 "$BDB" "select count(*) from entities where json_extract(properties, '\$.briefing_blocked') = 'secret_present';")
+[ "$B_BLOCKED" = "0" ] || fail "baseline-suppressed: expected 0 blocked entities, got $B_BLOCKED"
+B_SECRET=$(sqlite3 "$BDB" "select count(*) from findings where rule_id = 'CLA-SEC-SECRET-DETECTED';")
+[ "$B_SECRET" = "0" ] || fail "baseline-suppressed: expected 0 SECRET_DETECTED findings, got $B_SECRET"
+B_BASELINE=$(sqlite3 "$BDB" "select count(*) from findings where rule_id = 'CLA-INFRA-SECRET-BASELINE-MATCH';")
+[ "$B_BASELINE" = "1" ] || fail "baseline-suppressed: expected 1 BASELINE-MATCH finding, got $B_BASELINE"
+log "PASS: baseline-suppressed detection clears the block and emits BASELINE-MATCH"
+
+# ----------------------------------------------------------------------------
+# --allow-unredacted-secrets override admission (clarion-55fc5aa885 §I5, §I11)
+# ----------------------------------------------------------------------------
+log "scenario: confirmed --allow-unredacted-secrets keeps run, emits BOTH SECRET_DETECTED and UNREDACTED-SECRETS-ALLOWED"
+OVERRIDE_DIR="$(mktemp -d -t clarion-wp5-override-XXXXXX)"
+"$CLARION_BIN" install --path "$OVERRIDE_DIR"
+printf "aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n" > "$OVERRIDE_DIR/leaky.sec"
+PATH="$PLUGIN_DIR" "$CLARION_BIN" analyze \
+    --allow-unredacted-secrets \
+    --confirm-allow-unredacted-secrets=yes-i-understand \
+    "$OVERRIDE_DIR"
+ODB="$OVERRIDE_DIR/.clarion/clarion.db"
+O_BLOCKED=$(sqlite3 "$ODB" "select count(*) from entities where json_extract(properties, '\$.briefing_blocked') = 'secret_present';")
+[ "$O_BLOCKED" = "0" ] || fail "override: expected 0 blocked entities, got $O_BLOCKED"
+O_SECRET=$(sqlite3 "$ODB" "select count(*) from findings where rule_id = 'CLA-SEC-SECRET-DETECTED';")
+[ "$O_SECRET" = "1" ] || fail "override is additive per ADR-013: expected 1 SECRET_DETECTED finding, got $O_SECRET"
+O_OVERRIDE=$(sqlite3 "$ODB" "select count(*) from findings where rule_id = 'CLA-SEC-UNREDACTED-SECRETS-ALLOWED';")
+[ "$O_OVERRIDE" = "1" ] || fail "override: expected 1 UNREDACTED-SECRETS-ALLOWED finding, got $O_OVERRIDE"
+O_OVERRIDE_USED=$(sqlite3 "$ODB" "select json_extract(stats, '\$.secret_override_used') from runs;")
+[ "$O_OVERRIDE_USED" = "1" ] || fail "override: expected stats.secret_override_used = 1, got $O_OVERRIDE_USED"
+log "PASS: override admission lands both SECRET_DETECTED and UNREDACTED-SECRETS-ALLOWED"
+
+# ----------------------------------------------------------------------------
+# malformed-baseline abort (clarion-55fc5aa885 §I11)
+# ----------------------------------------------------------------------------
+log "scenario: malformed baseline aborts analyze before BeginRun (exit 78)"
+MALFORMED_DIR="$(mktemp -d -t clarion-wp5-malformed-XXXXXX)"
+"$CLARION_BIN" install --path "$MALFORMED_DIR"
+printf "harmless = 'nothing'\n" > "$MALFORMED_DIR/clean.sec"
+printf "not: valid: yaml: [\n" > "$MALFORMED_DIR/.clarion/secrets-baseline.yaml"
+set +e
+PATH="$PLUGIN_DIR" "$CLARION_BIN" analyze "$MALFORMED_DIR" 2>/dev/null
+MALFORMED_EXIT=$?
+set -e
+[ "$MALFORMED_EXIT" -ne 0 ] || fail "malformed baseline: expected non-zero exit, got $MALFORMED_EXIT"
+MDB="$MALFORMED_DIR/.clarion/clarion.db"
+M_RUNS=$(sqlite3 "$MDB" "select count(*) from runs;")
+[ "$M_RUNS" = "0" ] || fail "malformed baseline must abort BEFORE BeginRun; got $M_RUNS run rows"
+log "PASS: malformed baseline aborts with non-zero exit and no runs row"
+
+# ----------------------------------------------------------------------------
+# retry-after-baseline-add: rerun the baseline-suppression scenario but where
+# the baseline is added AFTER an initial blocked run, simulating the
+# operator workflow (clarion-55fc5aa885 §I11). This re-runs analyze on
+# DEMO_DIR (which started blocked) after we wipe and re-add a baseline.
+# ----------------------------------------------------------------------------
+log "scenario: retry-after-baseline-add unblocks a previously-blocked file"
+RETRY_DIR="$(mktemp -d -t clarion-wp5-retry-XXXXXX)"
+trap 'rm -rf "$DEMO_DIR" "$PLUGIN_DIR" "$BASELINE_DIR" "$OVERRIDE_DIR" "$MALFORMED_DIR" "$RETRY_DIR"' EXIT
+"$CLARION_BIN" install --path "$RETRY_DIR"
+printf "aws_access_key_id = 'AKIAIOSFODNN7EXAMPLE'\n" > "$RETRY_DIR/leaky.sec"
+# First run blocks (no baseline yet).
+PATH="$PLUGIN_DIR" "$CLARION_BIN" analyze "$RETRY_DIR"
+RDB="$RETRY_DIR/.clarion/clarion.db"
+R_BLOCKED_BEFORE=$(sqlite3 "$RDB" "select count(*) from entities where json_extract(properties, '\$.briefing_blocked') = 'secret_present';")
+[ "$R_BLOCKED_BEFORE" = "2" ] || fail "retry: first run must block the source file entity and plugin entity, got $R_BLOCKED_BEFORE"
+# Operator commits a baseline acknowledging the example key.
+cat > "$RETRY_DIR/.clarion/secrets-baseline.yaml" <<YAML
+version: "1.0"
+results:
+  "leaky.sec":
+    - type: "AWS Access Key"
+      hashed_secret: "$HASHED_SECRET"
+      line_number: 1
+      is_secret: false
+      justification: "Documented public AWS example key — false positive."
+YAML
+# Re-running analyze should NOT block this file.
+PATH="$PLUGIN_DIR" "$CLARION_BIN" analyze "$RETRY_DIR"
+R_BLOCKED_AFTER=$(sqlite3 "$RDB" "select count(*) from entities where json_extract(properties, '\$.briefing_blocked') = 'secret_present' and source_file_path like '%leaky.sec';")
+[ "$R_BLOCKED_AFTER" = "0" ] || fail "retry-after-baseline: leaky.sec must no longer be blocked, got $R_BLOCKED_AFTER"
+R_BASELINE_HITS=$(sqlite3 "$RDB" "select count(*) from findings where rule_id = 'CLA-INFRA-SECRET-BASELINE-MATCH';")
+[ "$R_BASELINE_HITS" -ge "1" ] || fail "retry-after-baseline: expected BASELINE-MATCH finding, got $R_BASELINE_HITS"
+log "PASS: retry-after-baseline-add unblocks the previously-blocked file"
+
+log "PASS: WP5 secret scan — all 5 scenarios (smoke, baseline, override, malformed, retry)"