fix(notes): the edit lock excludes other processes; pin OpenLock and the rollback (#192)

Review round 1 on PR #194:
- The edit lock did not exclude other processes (also on main): unlock
  removes the lock file, so a waiter could wake holding a flock on the
  orphaned inode while the next caller locked a fresh file. flockFile now
  re-checks after flock that the locked file is still the one at the path
  (brainfs LockIsCurrent) and retries otherwise; OpenLock reports a lock
  replaced mid-open as ErrLockChanged, which is retried instead of
  failing the edit. New cross-process test (3 re-executed processes x 400
  rounds, O_EXCL marker under the lock): 0 overlaps; red without the
  re-check.
- OpenLock unit test: relative dangling link (only the Lstat pre-check
  stops it; os.Root refuses absolute links on its own), live link, FIFO,
  directory, behind a symlinked dir, unclean path, positive control.
- Rollback test: a symlink swapped in for the note before the rollback
  (test seam beforeStampHook) is refused, target untouched in and outside
  the brain.
- The in-brain dangling-lock case uses a relative link and asserts the
  refusal names the lock. OpenLock reuses #189's RealParent; RemoveLock is
  dropped for brainfs.Remove. The doc comment names the swap residual.

Rebased onto main after #189.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.aider.conventions.md

@@ -1,315 +0,0 @@
-# Agent context — Mathias workspace
-
-<!-- Canonical root context for all AI coding agents.
-     Lives at: ~/dev/.context/AGENT.md
-     Applies to every project under ~/dev/ unless overridden.
-     
-     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
-     Project-level context in .context/PROJECT.md layers on top of this. -->
-
-## Who I am
-
-I'm Mathias, a digital product manager and technology consultant based in Sweden.
-I build software, research emerging tech, and deliver consulting engagements
-for clients under NDA. I work across AI/ML, financial automation, web applications,
-and climate/sustainability tech.
-
-## How I work with agents
-
-- I think like a product manager — I care about *why* before *how*
-- I want agents to be opinionated and push back, not just execute blindly
-- I prefer concise responses; skip ceremony and get to the point
-- When I say "build this", I mean production-quality with tests, not a demo
-- Ask me before making irreversible changes or adding heavy dependencies
-- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK
-
-## Behavior rules
-
-These rules apply to every task across every project, regardless of harness.
-
-1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
-   Think before coding; if the problem is unclear, ask or state assumptions before acting.
-2. **Minimum viable code.** Solve with the smallest change that works. Nothing
-   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
-3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
-   files, and formatting alone. Diffs should be small and reviewable.
-4. **Goal-driven execution.** Define clear success criteria up front for every task.
-   Loop — implement, verify, refine — until those criteria are met. Don't claim
-   completion without evidence (tests pass, command output, observed behavior).
-5. **Trunk-Based Development — commit directly to main.** Every commit is one
-   logical change (one tool, one fix, one test) with passing tests. Main is always
-   deployable. Never create long-lived feature branches.
-
-   **Exception — parallel agents on same repo:** If another agent is known to be
-   actively working on the same repo simultaneously, create a short-lived branch
-   (`agent/<description>`), finish the task, and merge to main within the same
-   session. Do not leave agent branches open between sessions.
-
-   **Exception — external contributor or client four-eyes requirement:** Use
-   PR flow only when a human reviewer outside the project is required. Document
-   the reason in PROJECT.md.
-
-## Default stack
-
-| Layer | Default | Fallback | Last resort |
-|-------|---------|----------|-------------|
-| Language | Go | Python | TypeScript, Java, C |
-| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
-| Build | Task (taskfile.dev) | Make | — |
-| Containers | Docker Compose (dev), k3s (prod) | — | — |
-| DB | PostgreSQL + sqlc | SQLite | — |
-| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
-| Logging | slog (structured) | — | — |
-| Testing | Table-driven, testify | — | — |
-| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
-
-Exploratory: Rust, Zig — I'll tell you when I want these.
-
-## Code conventions
-
-- **Go style**: golines, gofumpt, golangci-lint
-- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
-- **Naming**: stdlib conventions, no stuttering
-- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
-- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
-  one logical change per commit, CI is the quality gate
-- **Never**: long-lived feature branches, PRs for solo work, direct push without
-  passing `task check` locally first
-- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
-- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
-
-## Infrastructure
-
-Three machines on Tailscale:
-
-| Machine | Role | Key specs |
-|---------|------|-----------|
-| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
-| iguana | Services, builds | M2 Ultra Mac |
-| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
-
-- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
-- **Orchestration**: k3s cluster across all three machines
-- **Networking**: Tailscale mesh
-
-## Project landscape
-
-All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
-
-Organized in thematic folders:
-
-| Folder | Focus | Count |
-|--------|-------|-------|
-| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
-| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
-| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
-| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
-| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
-
-See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
-
-### Key active projects
-
-- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
-- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
-- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
-- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
-- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
-
-## Knowledge base — actively use it
-
-A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
-hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
-Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
-reference material — query it actively, not just when explicitly told.**
-
-### When to query (treat as a reflex)
-
-- **Before** starting a non-trivial task — search for prior art with the symptom
-  AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
-- **When debugging** — search for the error string, the stack frame, the affected
-  service. Past you may have already paid this tax.
-- **Before adopting** a pattern, library, framework, or model name — check if it
-  was tried and rejected, or what the integration footguns are.
-- **When making architectural decisions** — search for the domain + "ADR" or
-  "decision" to find prior reasoning before re-deriving it.
-- **When a recommendation feels novel** — challenge yourself: "has this been
-  documented?" The brain often has it.
-
-### When to write
-
-After you discover something that **future-you would forget** and that **isn't
-recoverable from the code, git log, or PR description alone**:
-
-- Bugs whose root cause is non-obvious and generalisable beyond this project.
-- Framework / library / model-name quirks that bit you and would bite anyone.
-- Design principles validated under fire (e.g. "every `_get` needs a `_list`").
-- Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
-
-DON'T write project status, sprint progress, PR summaries, or "what I did this
-session" — those rot fast and the originals are in git/gitea anyway. Brain
-entries that age well are about *why*, *how to avoid*, and *what to do when*.
-
-### How to access (per harness)
-
-| Harness | Query | Write |
-|---------|-------|-------|
-| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
-| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
-| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
-| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
-
-- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
-- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
-  fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
-  on the koala k3s cluster; don't hardcode local-only model names into the
-  berget URL (see knowledge entry on namespace mismatches).
-
-### Quick reflex checks
-
-If you find yourself about to say any of these out loud, you owe yourself a brain query first:
-
-- "I think the issue might be..."
-- "Let me try X and see..."
-- "I'll just write a script to..."
-- "This is probably a new bug..."
-- "Has anyone done this before?" — *yes, probably, go check.*
-
-## Client work rules
-
-When working on a project tagged with a client name:
-1. Never send code, data, or context to cloud APIs — use local models only
-2. Never reference other client projects or their data
-3. Keep all artifacts within the client's git org / directory
-4. Treat everything as confidential unless told otherwise
-
-## Harness-agnostic principles
-
-This context is designed to work with any AI coding tool:
-- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
-- Pi Coding Agent, Mistral Vibe, Antigravity
-- Any tool that accepts a system prompt or reads a markdown context file
-
-The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
-Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
-
-## How context propagates
-
-Canonical sources of truth:
-- Universal: `~/dev/.context/AGENT.md` (this file)
-- Project: `<repo>/.context/PROJECT.md` (per-repo)
-
-Derived files (committed, regenerated by `task context:sync`):
-- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
-  `.context/system-prompt.txt`
-
-Workflow:
-1. Edit a canonical file. Run `task context:sync`. Commit canonical and
-   derived together. Push.
-2. On any other host, `git pull` brings both. Claude Code (tree-walking)
-   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
-   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
-3. `task check` runs `context:sync` then asserts `git status --porcelain`
-   is empty over the derived files (catches both modified-tracked drift
-   and missing-untracked adapters). A drift fails the check with a
-   message telling you to stage the regenerated files.
-
-Behavior rules in this file and per-project rules in `PROJECT.md` apply
-unconditionally on every host, every harness.
-
-## Engineering Skills
-
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
-
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
-
-Key skills:
-- **TDD**: always write tests first — load `tdd` skill
-- **Code Review**: load `code-review` skill before any review
-- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
-- **Problem first**: load `problem-analysis` skill before coding non-trivial features
-
----
-
-# Project context
-
-<!-- Canonical project context. Edit this, run `task context:sync`.
-     Root agent context from ~/dev/.context/AGENT.md is automatically
-     prepended for harnesses that don't walk the directory tree. -->
-
-## Identity
-
-- **Name**: supervisor
-- **Owner**: Mathias
-- **Client**: personal
-- **Repo**: 
-- **Status**: active
-
-## Stack
-
-- **Primary language**: Go
-- **UI layer**: HTMX + Templ (when applicable)
-- **Fallback languages**: Python, TypeScript (justify in PR if used)
-- **Build**: Task (taskfile.dev), not Make
-- **Containers**: Docker (compose for dev, k3s for deploy)
-- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
-
-## Conventions
-
-### Code style
-- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
-- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
-- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
-- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
-
-### Architecture preferences
-- Prefer standard library over frameworks (net/http over gin/echo)
-- Dependency injection via constructor functions, not containers
-- Configuration via environment variables, parsed at startup into a typed struct
-- Structured logging via `slog`
-
-### Git
-- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
-- Branch naming: `feat/short-description`, `fix/short-description`
-- PRs: one concern per PR, description explains *why* not *what*
-
-### Security
-- No secrets in code, ever — use env vars or SOPS-encrypted files
-- Client data never leaves local network unless explicitly cleared
-- Dependencies: audit with `govulncheck` before adding
-
-## MCP endpoints
-
-Two MCP servers are live, both reachable over Tailscale and via HTTPS domain:
-
-- **`brain`** at `https://brain-mcp.d-ma.be/mcp` (NodePort `koala:30330`) —
-  `brain_query`, `brain_write`, `brain_ingest`, `brain_ingest_raw`,
-  `brain_answer`, `brain_classify`, `session_log`. Hosted by the ingestion
-  service. Auth: Dex JWT (claude.ai OAuth) or static `BRAIN_MCP_TOKEN`.
-- **`routing`** at `http://koala:30310/mcp` — Mode 2 routing pod. Advertises
-  `review`, `debug`, `retrospective`, `trainer`; per-call routes to local model
-  or Claude based on brain `/pass-rate`. Bearer auth via `ROUTING_MCP_TOKEN`
-  (opt-in). Only `mode client-local` registers this endpoint.
-
-The supervisor MCP (`koala:30320`) was retired in Plan 7 (2026-05-12). Its
-skill workers (`tdd`, `spec`) are now SKILL.md files; routed skills moved to
-the routing pod; brain tools moved to the brain MCP.
-
-The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
-`/ingest-path`, `/backfill-refs`, `/pass-rate`) remains available on port 3300
-for shell scripts and non-MCP clients.
-
-`brain_answer(query)` performs BM25 retrieval + LLM synthesis (berget.ai
-gemma4:31b → iguana fallback). `brain_classify(text)` infers doc type, title,
-and tags. Both require `BRAIN_LLM_PRIMARY_URL` to be set in the ingestion pod.
-
-## Agent instructions
-
-When acting as a coding agent on this project:
-
-1. Read this file and all `SKILL.md` files in `.skills/` before starting work
-2. Run `task check` before committing (lint + test + vet)
-3. If unsure about a convention, check `DECISIONS.md` or ask
-4. Never modify files outside the project root without explicit permission
-5. When adding a dependency, explain why in the commit message
-6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

.context/PROJECT.md

@@ -64,7 +64,11 @@ the routing pod; brain tools moved to the brain MCP.
 
 The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
 `/ingest-path`, `/backfill-refs`, `/pass-rate`) remains available on port 3300
-for shell scripts and non-MCP clients.
+for shell scripts and non-MCP clients, **with the same bearer token as `/mcp`**
+(`BRAIN_MCP_TOKEN`; hyperguild#149). It is not served on the public host
+(infra#517): use the tailnet (`koala:8443`) or in-cluster
+`ingestion.supervisor.svc:3300`. `/ingest-path` and `brain_ingest` `path`
+accept only paths inside `brain/raw/`.
 
 `brain_answer(query)` performs BM25 retrieval + LLM synthesis (berget.ai
 gemma4:31b → iguana fallback). `brain_classify(text)` infers doc type, title,

.context/mcp.json

@@ -7,6 +7,29 @@
     "supervisor": {
       "url": "http://localhost:3200/mcp",
       "description": "Hyperguild SDO — skill workers (tdd, retrospective), brain tools (brain_query, brain_write), session logging, tier detection"
+    },
+    "brain": {
+      "type": "http",
+      "url": "https://koala.tail30472e.ts.net:8443/mcp",
+      "headers": {
+        "Authorization": "Bearer ${BRAIN_MCP_TOKEN}"
+      }
+    },
+    "gitea": {
+      "_comment": "gitea-mcp authenticates by PASS-THROUGH: the bearer is a Gitea PAT it validates against Gitea and then acts as. GITEA_MCP_TOKEN -- which this entry used until 2026-09-08 -- 401s against it, so every harness synced from this file had a dead gitea server and no signal saying so. Probed 2026-09-08: GITEA_MCP_TOKEN 401, DMABE_GITEA_API_TOKEN 200, on both the public and the Serve URL.",
+      "type": "http",
+      "url": "https://koala.tail30472e.ts.net:8446/mcp",
+      "headers": {
+        "Authorization": "Bearer ${DMABE_GITEA_API_TOKEN}"
+      }
+    },
+    "infra": {
+      "_comment": "The bearer is belt-and-braces: this endpoint answers 200 with or without it, since Serve already limits reach to the tailnet. Sending it anyway means the day the server starts enforcing is not the day every harness breaks.",
+      "type": "http",
+      "url": "https://koala.tail30472e.ts.net:8444/mcp",
+      "headers": {
+        "Authorization": "Bearer ${INFRA_MCP_TOKEN}"
+      }
     }
   }
 }

.context/system-prompt.txt

@@ -32,6 +32,14 @@ and climate/sustainability tech.
 
 These rules apply to every task across every project, regardless of harness.
 
+0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line:
+   - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours.
+   - **Load the relevant skill** — see trigger table in *Engineering Skills* below.
+   - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test.
+   - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done?
+
+   **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it.
+
 1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
    Think before coding; if the problem is unclear, ask or state assumptions before acting.
 2. **Minimum viable code.** Solve with the smallest change that works. Nothing
@@ -45,14 +53,124 @@ These rules apply to every task across every project, regardless of harness.
    logical change (one tool, one fix, one test) with passing tests. Main is always
    deployable. Never create long-lived feature branches.
 
-   **Exception — parallel agents on same repo:** If another agent is known to be
-   actively working on the same repo simultaneously, create a short-lived branch
-   (`agent/<description>`), finish the task, and merge to main within the same
-   session. Do not leave agent branches open between sessions.
+   **The PR trigger is RISK, not concurrency.** `risk/low` work commits straight to
+   main with CI as the gate — that is most work and is unchanged. `risk/medium` and
+   above opens a PR, even solo, even with nobody waiting to review it. This mirrors
+   the tiered merge model in `assessor-loop`
+   `method/transfer-to-a-regulated-organisation.md` §4.1, so the estate practises
+   what it sells instead of merging everything on green and claiming otherwise.
 
-   **Exception — external contributor or client four-eyes requirement:** Use
-   PR flow only when a human reviewer outside the project is required. Document
-   the reason in PROJECT.md.
+   **Concurrency is NOT a reason to branch.** Measured 2026-08-29 across three real
+   collisions between parallel sessions: two were not branching problems at all — a
+   generated artifact written to the same path by both (branching turns that into a
+   merge conflict on a 33k-line JSON), and uncommitted work in a shared checkout
+   (a per-session worktree fixes it) — and the third was an ordinary non-fast-forward
+   push resolved by rebase in seconds. Use a worktree per session on shared repos and
+   timestamp generated artifacts. Do not reach for a branch.
+
+   Branch+PR flow carries documented costs on solo repos: merging auto-closes gated
+   issues, review comments live on a thread separate from the issue's, and a
+   merged-and-deleted branch cannot be amended (brain:
+   `gitea-pr-merge-autoclose-and-review-comment-footguns`). Those are the price of
+   the `risk/medium`+ lane — paid deliberately, not incurred by accident.
+
+   **Exception — external contributor or client four-eyes requirement:** Use PR flow
+   when a human reviewer outside the project is required. Document the reason in
+   PROJECT.md.
+
+   **Exception — a GitOps repo where a branch cannot be reconciled.** In a repo whose
+   deployment watches one branch (`mathias/infra`: Flux watches `main`), a branch is
+   invisible to the thing that applies it. A `risk/medium` change to `alerts.yaml` or
+   `litellm-config.yaml` can be linted on a branch but never *exercised* there, so a
+   PR would buy a review of a state that was never deployed.
+
+   There, `risk/medium`+ work stays on `main` and instead requires a **recorded
+   adversarial review pass before the push** — `skills:pr-gatekeeper` or equivalent,
+   reviewing the staged diff. **The reviewer's verdict goes in the issue, not a PR
+   thread.** No verdict recorded means the lane was not used, and saying "the gate was
+   green" is not the same claim.
+
+   Be honest about what this is: a recorded *independent* pass, not four-eyes in the
+   sense `assessor-loop` §4.1 means for a regulated organisation, because the reviewer
+   is an agent. It is more than the repo had and less than the model it mirrors; do not
+   describe it as the stronger property. (infra#470, decided 2026-09-29.)
+
+   This lane depends on the `risk/` label being right. A label that triggers a heavier
+   lane is load-bearing, not cosmetic — if work that belongs in it is unlabelled, the
+   lane silently does not apply.
+
+6. **Close the loop — every substantive task ends with the same ritual.** Shipping
+   the code is not the end of the task; capturing it is. Run this unprompted:
+   - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or
+     new/changed ADR, patch for a fix; docs in the same commit). Check the repo's
+     actual last tag — stated versions in docs drift stale.
+   - **Push** main and the tag (CI is the gate).
+   - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) —
+     the reusable patterns and the footguns that would bite anyone again, never
+     project status. See *Knowledge base — when to write* below.
+   - **File discovered-but-deferred work as tracker issues** on the project's own
+     repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let
+     "out of scope, recorded" rot in a commit message; make it a ticket with a
+     source pointer.
+   - Surface the brain entries and issue numbers in the closing summary so the
+     trail is auditable.
+
+   **Chat is not a durable store. Never rely on Mathias remembering anything.**
+   Every gap, caveat, risk, open question and next step must land in one of four
+   places before the turn ends: **the brain**, **a repo** (code, docs, ADR),
+   **a tracker issue**, or **a plan file**. A finding stated only in conversation is
+   lost the moment the session closes — and this estate has repeatedly proved that a
+   remembered convention is an unreliable control.
+
+   This applies hardest to what is tempting to leave as a closing remark: "worth
+   knowing X isn't enforced yet", "this is a convention, not a gate", "we should
+   revisit Y". Those are exactly the items that need a locator. If it is worth
+   saying in a summary, it is worth writing where it can be found again without you.
+
+7. **Finish what's closable — only involve me for a genuine call.** If a
+   tracker issue, PR, or checklist item is demonstrably resolved — the fix
+   landed, the state changed, you verified it live — close/merge/check it off
+   in the same turn. Don't leave it open "for the record" or park it waiting
+   on me to confirm something that already happened; that's bookkeeping, not
+   a decision. Reserve asking me (`AskUserQuestion`, a `DECISION NEEDED`
+   comment, or otherwise pausing) for when it's genuinely mine to call:
+   irreversible or prod/host-impacting actions, a real judgment call with no
+   clearly-better option, ambiguous intent, or anything secret-writes/
+   destructive-git already gate. Before claiming something is closable,
+   verify it live (re-check the issue, re-run the command) rather than
+   trusting your own earlier summary (brain: `filed-issue-not-same-as-fixed`).
+
+8. **Control code needs an adversary, not a checklist.** Code whose job is to
+   refuse, deny, gate or contain is not adequately verified by a green gate.
+   Rule 5 makes CI the quality gate and that holds for ordinary work — but a
+   passing suite only asserts what its author already thought of, and for a
+   control the author is precisely the person whose imagination just failed.
+   Measured on `dispatch#75`: five review rounds, five real escapes verified by
+   execution, and **CI was green on every one of them** while `git rm
+   ././.dispatch-allow` deleted the file the control existed to protect. So
+   route this work through a review with authority to block, instructed to
+   verify by execution rather than by reading the implementation. Expect to be
+   blocked more than once; that is the control working, not the reviewer being
+   difficult. (brain: `a-green-gate-is-not-evidence-for-control-code`; the
+   practices live in the `pr-gatekeeper` agent.)
+
+9. **A test's name must not claim more than its assertions prove.** Name a test
+   after the mechanism it observes, not the goal it serves.
+   `DoesNotInheritEnv` is honest; `IsContained` is a claim the test cannot
+   support. This is not pedantry about naming — when name and assertion
+   diverge, the name wins in the reader's head and the gap becomes invisible,
+   which is what lets the defect survive review. Found three times in one PR,
+   twice in tests written to fix the previous instance of it; each passed while
+   the thing it was named for was exploitable. If you cannot name the mechanism,
+   you do not yet know what the test observes.
+
+## CAD sprint patterns
+
+Two CAD sprint archetypes (defs: brain `wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16`):
+- **Inception Sprint** — birth a new repo. Oath-gated close; tag only once every clause holds. Brain: `.../inception-sprint-and-oath`.
+- **Sweep Sprint** — clear an existing backlog. Parallel read-only research per issue → sequential one-issue-per-commit execution. Brain: `.../sweep-sprint-and-oath`.
+
+Shared: decisions that are yours, not the agent's, surface as `DECISION NEEDED` (question/options/recommendation/blocks) — ask live if you're present, else comment and wait, never act past it. Live-breaking regressions get `git revert`, never forward-fixed; host-network work skips even read-only research (solo, synchronous, you present). Rule 6's closing ritual only fires once every Oath clause genuinely holds — blocked = descoped-and-tracked, never marked done.
 
 ## Default stack
 
@@ -64,7 +182,7 @@ These rules apply to every task across every project, regardless of harness.
 | Containers | Docker Compose (dev), k3s (prod) | — | — |
 | DB | PostgreSQL + sqlc | SQLite | — |
 | Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
-| Logging | slog (structured) | — | — |
+| Logging | slog (structured) | stdlib `logging` w/ structured `extra=` (or structlog) | — |
 | Testing | Table-driven, testify | — | — |
 | Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
 
@@ -73,7 +191,12 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 ## Code conventions
 
 - **Go style**: golines, gofumpt, golangci-lint
-- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
+- **Python style** (fallback language): ruff (format+lint, one tool), mypy --strict (non-negotiable,
+  matches Go's static typing discipline), pytest + pytest-cov (table-driven via
+  `@pytest.mark.parametrize`), uv (venv+deps+lock, one tool), pydantic-settings (typed env-var config
+  — same principle as Go's typed structs), src-layout + `pyproject.toml` only (no `setup.py`)
+- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return.
+  Python: `raise X from e` (exception chaining, same principle) — never bare `except`, never silent `pass`
 - **Naming**: stdlib conventions, no stuttering
 - **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
 - **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
@@ -83,6 +206,26 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 - **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
 - **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
 
+## Secret handling (every harness, every command)
+
+Tool output is persisted: terminal → `~/.claude/projects` transcripts →
+claudewatcher → brain/wiki → gitea history. A secret printed once is
+searchable forever, and clearing it means rotating the key. So:
+
+1. **Never print, echo, log, or transform a secret to inspect it.** No
+   `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform
+   to defeat `op run`'s output masking (it masks raw values; base64 hides them
+   from the mask — that exact trick leaked a key on 2026-06-11).
+2. **Secrets stay in the subprocess.** Reference them only as env vars consumed
+   *inside* `op run --env-file ~/.op-env -- <cmd>`. Never place a literal secret
+   in a command's argv (it lands in the tool call and the transcript).
+3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` —
+   never `${X:-...}` (returns the value when set) and never echo a substring of it.
+4. **Cross-host secrets:** run the secret-consuming command on the host that has
+   the secret; do not forward a raw key over ssh argv/stdout.
+5. If a secret does leak into output, say so immediately and flag it for rotation —
+   don't bury it.
+
 ## Infrastructure
 
 Three machines on Tailscale:
@@ -91,10 +234,10 @@ Three machines on Tailscale:
 |---------|------|-----------|
 | koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
 | iguana | Services, builds | M2 Ultra Mac |
-| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+| flamingo | Daily driver, edge | Apple Silicon Mac, ~/dev is here |
 
 - **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
-- **Orchestration**: k3s cluster across all three machines
+- **Orchestration**: k3s on koala only — single control-plane node, no workers (verified 2026-08-30). iguana and flamingo are on the tailnet but are not cluster members
 - **Networking**: Tailscale mesh
 
 ## Project landscape
@@ -161,10 +304,16 @@ entries that age well are about *why*, *how to avoid*, and *what to do when*.
 |---------|-------|-------|
 | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
 | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
-| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
-| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
+| **Anything HTTP-only (curl, scripts)** | Tailnet only: `POST https://koala.tail30472e.ts.net:8443/query` with `{"query":"..."}`, sending `BRAIN_MCP_TOKEN` (not yet enforced on REST, hyperguild#149). The public `brain-mcp.d-ma.be` serves `/mcp` only (infra#517). | `POST .../write` with `{"content":"...","wing":"...","hall":"..."}` |
+| **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
 
-- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
+- **Scoping — the brain holds no confidential client content.** Nothing on the read path
+  filters by client: every token holder can read every wing, and `wing` on `brain_query`
+  is an optional argument, not an access control. Client confidentiality is enforced only
+  at write time (`capture`'s I1 gate refuses internal/confidential). So never `brain_write`
+  client material; generalise it first or keep it in the client's own repo. (hyperguild#144,
+  decided 2026-10-01. This line previously claimed client projects were filtered; they
+  were not.)
 - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
   fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
   on the koala k3s cluster; don't hardcode local-only model names into the
@@ -190,10 +339,11 @@ When working on a project tagged with a client name:
 
 ## Harness-agnostic principles
 
-This context is designed to work with any AI coding tool:
-- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
-- Pi Coding Agent, Mistral Vibe, Antigravity
-- Any tool that accepts a system prompt or reads a markdown context file
+Supported harnesses (2026-09-01) — Cursor and Aider were dropped; do not
+re-add adapters for them:
+- Claude Code, Antigravity, OpenCode, Mistral Vibe, Crush, Pi Coding Agent
+- Open WebUI, Charmbracelet Mods, or any tool that takes a system prompt string
+- Any other tool that reads `AGENTS.md`, which is the de facto convention
 
 The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
 Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
@@ -205,34 +355,75 @@ Canonical sources of truth:
 - Project: `<repo>/.context/PROJECT.md` (per-repo)
 
 Derived files (committed, regenerated by `task context:sync`):
-- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
-  `.context/system-prompt.txt`
+- `CLAUDE.md`, `AGENTS.md`, `.context/system-prompt.txt`
+
+Repos still carrying `.cursorrules`, `.aider.conventions.md` or
+`.aider.conf.yml` are stale: nothing regenerates them. Delete them the next time
+you touch the repo, along with their entries in that repo's `task check`
+assertion.
 
 Workflow:
 1. Edit a canonical file. Run `task context:sync`. Commit canonical and
    derived together. Push.
-2. On any other host, `git pull` brings both. Claude Code (tree-walking)
-   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
-   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+2. On any other host, `git pull` brings both. Which file a harness reads does
+   NOT split cleanly by lookup strategy, so do not reason from the strategy:
+   - `CLAUDE.md` — Claude Code (walks up the tree)
+   - `AGENTS.md` — Crush, Pi, Antigravity (cwd-only), OpenCode (project root,
+     global at `~/.config/opencode/AGENTS.md`), and Mistral Vibe, which **walks
+     up** from cwd and takes the first `AGENTS.md` it finds
+     (user-level `~/.vibe/AGENTS.md`)
+   - `.context/system-prompt.txt` — Open WebUI, Mods, raw API calls; not read by
+     any harness, it is for pasting
+
+   Vibe tree-walks for `AGENTS.md`, so "tree-walkers use CLAUDE.md" is false.
+   Each repo's `AGENTS.md` embeds the canonical and is the first one found from
+   inside that repo, so this works — but by construction, not by luck.
 3. `task check` runs `context:sync` then asserts `git status --porcelain`
    is empty over the derived files (catches both modified-tracked drift
    and missing-untracked adapters). A drift fails the check with a
    message telling you to stage the regenerated files.
 
-Behavior rules in this file and per-project rules in `PROJECT.md` apply
-unconditionally on every host, every harness.
+Behavior rules in this file and per-project rules in `PROJECT.md` apply on every
+host and every harness.
+
+**Where a project rule contradicts a rule here, the project rule governs — and it
+must state its reason.** Both halves matter: the project file wins because it knows
+something this file cannot (infra's Flux constraint is real and not visible from
+here), and it must say why because a bare override is indistinguishable from drift.
+
+This replaces the previous wording, which said rules here and in `PROJECT.md` both
+apply *"unconditionally"*. That was not a tiebreak but a contradiction, and it went
+unnoticed until rule 5 and infra's "never create feature branches" had to be obeyed
+at the same time (infra#470). A standard can hold two individually sensible clauses
+that are jointly unsatisfiable, and survive for as long as everyone reads it
+charitably — the same failure the Inception Sprint Oath's G6 had.
 
 ## Engineering Skills
 
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Load at task start — not "on demand" but on schedule, before writing code. Browse `SKILLS_INDEX.md` for the full list.
 
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+**Claude Code** installs the repo as a plugin from the marketplace the same repo hosts. That path also carries the `secret-guard` and `pre-task-ritual` hooks and the brain/gitea/infra MCP servers, which symlinks cannot:
 
-Key skills:
-- **TDD**: always write tests first — load `tdd` skill
-- **Code Review**: load `code-review` skill before any review
-- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
-- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+```
+/plugin marketplace add https://git.d-ma.be/mathias/skills.git
+/plugin install skills@mathias
+```
+
+Skills are **namespaced** under Claude Code: load `tdd` as `skills:tdd`. The trigger table below uses bare names — prefix them.
+
+**Crush, Pi and OpenCode** have no plugin system and are wired by `install.sh` as one directory symlink per harness via `~/.agents/skills`. Do not clone the checkout into `~/dev`: that folder is iCloud-shared between the Macs and spans two path roots (`/Users/mathias` vs `/home/mathias` on koala), so a checkout there is a git working tree with two concurrent writers, and any absolute symlink stored in it is broken on one side by construction (skills#23). Leave `SKILLS_CHECKOUT_DIR` at its host-local default.
+
+Check a host with `task doctor` in the skills repo; it also runs automatically at session start via the plugin.
+
+**Skill trigger table — load before starting, not after getting stuck:**
+
+| Task type | Load |
+|-----------|------|
+| Any feature or bug fix | `tdd` |
+| Refactor or design | `clean-code` or `solid` |
+| Debug | `problem-analysis` |
+| Review code or PRs | `code-review` |
+| Frame a problem before coding | `problem-analysis` |
 
 ---
 
@@ -302,7 +493,11 @@ the routing pod; brain tools moved to the brain MCP.
 
 The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
 `/ingest-path`, `/backfill-refs`, `/pass-rate`) remains available on port 3300
-for shell scripts and non-MCP clients.
+for shell scripts and non-MCP clients, **with the same bearer token as `/mcp`**
+(`BRAIN_MCP_TOKEN`; hyperguild#149). It is not served on the public host
+(infra#517): use the tailnet (`koala:8443`) or in-cluster
+`ingestion.supervisor.svc:3300`. `/ingest-path` and `brain_ingest` `path`
+accept only paths inside `brain/raw/`.
 
 `brain_answer(query)` performs BM25 retrieval + LLM synthesis (berget.ai
 gemma4:31b → iguana fallback). `brain_classify(text)` infers doc type, title,

.cursorrules

@@ -1,318 +0,0 @@
-# Cursor rules — auto-generated
-# Do not edit. Run: task context:sync
-
-# Agent context — Mathias workspace
-
-<!-- Canonical root context for all AI coding agents.
-     Lives at: ~/dev/.context/AGENT.md
-     Applies to every project under ~/dev/ unless overridden.
-     
-     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
-     Project-level context in .context/PROJECT.md layers on top of this. -->
-
-## Who I am
-
-I'm Mathias, a digital product manager and technology consultant based in Sweden.
-I build software, research emerging tech, and deliver consulting engagements
-for clients under NDA. I work across AI/ML, financial automation, web applications,
-and climate/sustainability tech.
-
-## How I work with agents
-
-- I think like a product manager — I care about *why* before *how*
-- I want agents to be opinionated and push back, not just execute blindly
-- I prefer concise responses; skip ceremony and get to the point
-- When I say "build this", I mean production-quality with tests, not a demo
-- Ask me before making irreversible changes or adding heavy dependencies
-- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK
-
-## Behavior rules
-
-These rules apply to every task across every project, regardless of harness.
-
-1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
-   Think before coding; if the problem is unclear, ask or state assumptions before acting.
-2. **Minimum viable code.** Solve with the smallest change that works. Nothing
-   speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
-3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
-   files, and formatting alone. Diffs should be small and reviewable.
-4. **Goal-driven execution.** Define clear success criteria up front for every task.
-   Loop — implement, verify, refine — until those criteria are met. Don't claim
-   completion without evidence (tests pass, command output, observed behavior).
-5. **Trunk-Based Development — commit directly to main.** Every commit is one
-   logical change (one tool, one fix, one test) with passing tests. Main is always
-   deployable. Never create long-lived feature branches.
-
-   **Exception — parallel agents on same repo:** If another agent is known to be
-   actively working on the same repo simultaneously, create a short-lived branch
-   (`agent/<description>`), finish the task, and merge to main within the same
-   session. Do not leave agent branches open between sessions.
-
-   **Exception — external contributor or client four-eyes requirement:** Use
-   PR flow only when a human reviewer outside the project is required. Document
-   the reason in PROJECT.md.
-
-## Default stack
-
-| Layer | Default | Fallback | Last resort |
-|-------|---------|----------|-------------|
-| Language | Go | Python | TypeScript, Java, C |
-| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
-| Build | Task (taskfile.dev) | Make | — |
-| Containers | Docker Compose (dev), k3s (prod) | — | — |
-| DB | PostgreSQL + sqlc | SQLite | — |
-| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
-| Logging | slog (structured) | — | — |
-| Testing | Table-driven, testify | — | — |
-| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
-
-Exploratory: Rust, Zig — I'll tell you when I want these.
-
-## Code conventions
-
-- **Go style**: golines, gofumpt, golangci-lint
-- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
-- **Naming**: stdlib conventions, no stuttering
-- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
-- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
-  one logical change per commit, CI is the quality gate
-- **Never**: long-lived feature branches, PRs for solo work, direct push without
-  passing `task check` locally first
-- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
-- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
-
-## Infrastructure
-
-Three machines on Tailscale:
-
-| Machine | Role | Key specs |
-|---------|------|-----------|
-| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
-| iguana | Services, builds | M2 Ultra Mac |
-| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
-
-- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
-- **Orchestration**: k3s cluster across all three machines
-- **Networking**: Tailscale mesh
-
-## Project landscape
-
-All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
-
-Organized in thematic folders:
-
-| Folder | Focus | Count |
-|--------|-------|-------|
-| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
-| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
-| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
-| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
-| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
-
-See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
-
-### Key active projects
-
-- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
-- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
-- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
-- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
-- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
-
-## Knowledge base — actively use it
-
-A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
-hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
-Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
-reference material — query it actively, not just when explicitly told.**
-
-### When to query (treat as a reflex)
-
-- **Before** starting a non-trivial task — search for prior art with the symptom
-  AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
-- **When debugging** — search for the error string, the stack frame, the affected
-  service. Past you may have already paid this tax.
-- **Before adopting** a pattern, library, framework, or model name — check if it
-  was tried and rejected, or what the integration footguns are.
-- **When making architectural decisions** — search for the domain + "ADR" or
-  "decision" to find prior reasoning before re-deriving it.
-- **When a recommendation feels novel** — challenge yourself: "has this been
-  documented?" The brain often has it.
-
-### When to write
-
-After you discover something that **future-you would forget** and that **isn't
-recoverable from the code, git log, or PR description alone**:
-
-- Bugs whose root cause is non-obvious and generalisable beyond this project.
-- Framework / library / model-name quirks that bit you and would bite anyone.
-- Design principles validated under fire (e.g. "every `_get` needs a `_list`").
-- Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
-
-DON'T write project status, sprint progress, PR summaries, or "what I did this
-session" — those rot fast and the originals are in git/gitea anyway. Brain
-entries that age well are about *why*, *how to avoid*, and *what to do when*.
-
-### How to access (per harness)
-
-| Harness | Query | Write |
-|---------|-------|-------|
-| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
-| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
-| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
-| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
-
-- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
-- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
-  fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
-  on the koala k3s cluster; don't hardcode local-only model names into the
-  berget URL (see knowledge entry on namespace mismatches).
-
-### Quick reflex checks
-
-If you find yourself about to say any of these out loud, you owe yourself a brain query first:
-
-- "I think the issue might be..."
-- "Let me try X and see..."
-- "I'll just write a script to..."
-- "This is probably a new bug..."
-- "Has anyone done this before?" — *yes, probably, go check.*
-
-## Client work rules
-
-When working on a project tagged with a client name:
-1. Never send code, data, or context to cloud APIs — use local models only
-2. Never reference other client projects or their data
-3. Keep all artifacts within the client's git org / directory
-4. Treat everything as confidential unless told otherwise
-
-## Harness-agnostic principles
-
-This context is designed to work with any AI coding tool:
-- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
-- Pi Coding Agent, Mistral Vibe, Antigravity
-- Any tool that accepts a system prompt or reads a markdown context file
-
-The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
-Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
-
-## How context propagates
-
-Canonical sources of truth:
-- Universal: `~/dev/.context/AGENT.md` (this file)
-- Project: `<repo>/.context/PROJECT.md` (per-repo)
-
-Derived files (committed, regenerated by `task context:sync`):
-- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
-  `.context/system-prompt.txt`
-
-Workflow:
-1. Edit a canonical file. Run `task context:sync`. Commit canonical and
-   derived together. Push.
-2. On any other host, `git pull` brings both. Claude Code (tree-walking)
-   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
-   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
-3. `task check` runs `context:sync` then asserts `git status --porcelain`
-   is empty over the derived files (catches both modified-tracked drift
-   and missing-untracked adapters). A drift fails the check with a
-   message telling you to stage the regenerated files.
-
-Behavior rules in this file and per-project rules in `PROJECT.md` apply
-unconditionally on every host, every harness.
-
-## Engineering Skills
-
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
-
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
-
-Key skills:
-- **TDD**: always write tests first — load `tdd` skill
-- **Code Review**: load `code-review` skill before any review
-- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
-- **Problem first**: load `problem-analysis` skill before coding non-trivial features
-
----
-
-# Project context
-
-<!-- Canonical project context. Edit this, run `task context:sync`.
-     Root agent context from ~/dev/.context/AGENT.md is automatically
-     prepended for harnesses that don't walk the directory tree. -->
-
-## Identity
-
-- **Name**: supervisor
-- **Owner**: Mathias
-- **Client**: personal
-- **Repo**: 
-- **Status**: active
-
-## Stack
-
-- **Primary language**: Go
-- **UI layer**: HTMX + Templ (when applicable)
-- **Fallback languages**: Python, TypeScript (justify in PR if used)
-- **Build**: Task (taskfile.dev), not Make
-- **Containers**: Docker (compose for dev, k3s for deploy)
-- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
-
-## Conventions
-
-### Code style
-- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
-- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
-- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
-- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
-
-### Architecture preferences
-- Prefer standard library over frameworks (net/http over gin/echo)
-- Dependency injection via constructor functions, not containers
-- Configuration via environment variables, parsed at startup into a typed struct
-- Structured logging via `slog`
-
-### Git
-- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
-- Branch naming: `feat/short-description`, `fix/short-description`
-- PRs: one concern per PR, description explains *why* not *what*
-
-### Security
-- No secrets in code, ever — use env vars or SOPS-encrypted files
-- Client data never leaves local network unless explicitly cleared
-- Dependencies: audit with `govulncheck` before adding
-
-## MCP endpoints
-
-Two MCP servers are live, both reachable over Tailscale and via HTTPS domain:
-
-- **`brain`** at `https://brain-mcp.d-ma.be/mcp` (NodePort `koala:30330`) —
-  `brain_query`, `brain_write`, `brain_ingest`, `brain_ingest_raw`,
-  `brain_answer`, `brain_classify`, `session_log`. Hosted by the ingestion
-  service. Auth: Dex JWT (claude.ai OAuth) or static `BRAIN_MCP_TOKEN`.
-- **`routing`** at `http://koala:30310/mcp` — Mode 2 routing pod. Advertises
-  `review`, `debug`, `retrospective`, `trainer`; per-call routes to local model
-  or Claude based on brain `/pass-rate`. Bearer auth via `ROUTING_MCP_TOKEN`
-  (opt-in). Only `mode client-local` registers this endpoint.
-
-The supervisor MCP (`koala:30320`) was retired in Plan 7 (2026-05-12). Its
-skill workers (`tdd`, `spec`) are now SKILL.md files; routed skills moved to
-the routing pod; brain tools moved to the brain MCP.
-
-The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
-`/ingest-path`, `/backfill-refs`, `/pass-rate`) remains available on port 3300
-for shell scripts and non-MCP clients.
-
-`brain_answer(query)` performs BM25 retrieval + LLM synthesis (berget.ai
-gemma4:31b → iguana fallback). `brain_classify(text)` infers doc type, title,
-and tags. Both require `BRAIN_LLM_PRIMARY_URL` to be set in the ingestion pod.
-
-## Agent instructions
-
-When acting as a coding agent on this project:
-
-1. Read this file and all `SKILL.md` files in `.skills/` before starting work
-2. Run `task check` before committing (lint + test + vet)
-3. If unsure about a convention, check `DECISIONS.md` or ask
-4. Never modify files outside the project root without explicit permission
-5. When adding a dependency, explain why in the commit message
-6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

.dispatch-allow

@@ -0,0 +1,2 @@
+# Presence of this file marks this repo as opt-in for headless dispatch.
+# See dispatch#3.

.env.example

@@ -1,7 +1,6 @@
 # Supervisor MCP server
 SUPERVISOR_PORT=3200
 SUPERVISOR_CONFIG_DIR=./config/supervisor
-SUPERVISOR_MODELS_FILE=./config/models.yaml
 
 # LiteLLM gateway (iguana)
 LITELLM_BASE_URL=http://iguana:4000

.gitea/workflows/cd.yml

@@ -1,6 +1,6 @@
 name: cd
 
-on:
+"on":
   workflow_run:
     workflows: ["CI"]
     types: [completed]
@@ -13,9 +13,8 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' }}
     environment: staging
     env:
-      INGESTION_IMAGE: gitea.d-ma.be/mathias/ingestion
-      ROUTING_IMAGE: gitea.d-ma.be/mathias/routing
-      INFRA_REPO: git@gitea.d-ma.be:mathias/infra.git
+      INGESTION_IMAGE: git.d-ma.be/mathias/ingestion
+      INFRA_REPO: git@git.d-ma.be:mathias/infra.git
       BUILDKIT_HOST: unix:///run/buildkit/buildkitd.sock
     steps:
       - name: Checkout
@@ -41,58 +40,60 @@ jobs:
 
           echo "Built and pushed ${INGESTION_IMAGE}:${IMAGE_TAG}"
 
-      - name: Build and push routing image
-        run: |
-          set -e
-          trap 'rm -f /tmp/routing-image.tar' EXIT
-          IMAGE_TAG="${{ github.sha }}"
-          echo "Building ${ROUTING_IMAGE}:${IMAGE_TAG}"
-
-          buildctl --addr "${BUILDKIT_HOST}" build \
-            --frontend dockerfile.v0 \
-            --local context=. \
-            --local dockerfile=. \
-            --opt filename=Dockerfile.routing \
-            --opt build-arg:VERSION="${IMAGE_TAG}" \
-            --output type=oci,dest=/tmp/routing-image.tar
-
-          skopeo copy \
-            oci-archive:/tmp/routing-image.tar \
-            docker://${ROUTING_IMAGE}:${IMAGE_TAG} \
-            --dest-creds "${{ secrets.REGISTRY_CREDS }}"
-
-          echo "Built and pushed ${ROUTING_IMAGE}:${IMAGE_TAG}"
-
       - name: Update infra repo
         run: |
           set -e
           trap 'rm -rf /tmp/infra-update; rm -f ~/.ssh/infra_deploy_key' EXIT
           IMAGE_TAG="${{ github.sha }}"
+          # infra#311: github.sha is never empty in practice, but the manifest
+          # patch below is the same shape that took Flux down estate-wide on
+          # 2026-08-25 -- an empty tag yields `image: <repo>:`, which is invalid
+          # YAML and fails the ENTIRE Kustomization, not just this app. The
+          # assert costs nothing and removes the class.
+          [ -n "${IMAGE_TAG:-}" ] || { echo "IMAGE_TAG is empty - refusing to patch"; exit 1; }
           mkdir -p ~/.ssh
           echo "${{ secrets.INFRA_DEPLOY_KEY }}" > ~/.ssh/infra_deploy_key
           chmod 600 ~/.ssh/infra_deploy_key
-          printf 'Host gitea.d-ma.be\n  HostName 127.0.0.1\n  Port 30022\n  StrictHostKeyChecking no\n' >> ~/.ssh/config
-
-          GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
+          # In-cluster DNS to gitea's SSH NodePort service, not 127.0.0.1:30022
+          # (that only worked when act_runner ran on koala's bare host network;
+          # from inside the containerized runner's own pod netns, loopback
+          # never reaches the host — "Connection refused", found 2026-07-27).
+          #
+          # Pass as -o overrides on the ssh invocation itself, NOT appended to
+          # ~/.ssh/config: $HOME (/data) is a PVC that persists across job
+          # runs on this runner (same "workspace not ephemeral" class as
+          # brain: act-runner-host-executor-tmp-persists), so an appended
+          # line here would pile up duplicate `Host git.d-ma.be` blocks
+          # across every run — ssh_config is first-match-wins, so a stale
+          # entry from an earlier failed run would silently shadow this
+          # fix forever (exactly what happened once already: this fix's
+          # own first attempt got appended AFTER an already-stale entry
+          # and lost). CLI -o options always win regardless of file state,
+          # so this step is safe to re-run any number of times.
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes -o HostName=gitea-ssh-nodeport.gitea.svc.cluster.local -o Port=22 -o StrictHostKeyChecking=no" \
             git clone "${INFRA_REPO}" /tmp/infra-update
 
           cd /tmp/infra-update
 
-          sed -i "s|gitea.d-ma.be/mathias/ingestion:.*|gitea.d-ma.be/mathias/ingestion:${IMAGE_TAG}|" \
+          sed -i "s|git.d-ma.be/mathias/ingestion:.*|git.d-ma.be/mathias/ingestion:${IMAGE_TAG}|" \
             "k3s/apps/supervisor/ingestion-deployment.yaml"
 
-          sed -i "s|gitea.d-ma.be/mathias/routing:.*|gitea.d-ma.be/mathias/routing:${IMAGE_TAG}|" \
-            "k3s/apps/routing/deployment.yaml"
-
           git config user.email "cd-bot@d-ma.be"
           git config user.name "CD Bot"
-          git add "k3s/apps/supervisor/ingestion-deployment.yaml" \
-                  "k3s/apps/routing/deployment.yaml"
-          git commit -m "chore(deploy): ingestion+routing → ${IMAGE_TAG}"
+          git add "k3s/apps/supervisor/ingestion-deployment.yaml"
+          # Idempotent: `git commit` exits 1 on an empty index, so a run that
+          # finds the bump already applied failed the whole job and rang the
+          # CI-red alarm for a deploy that was fine (hyperguild#118). Two
+          # sources of a no-op run: a manual re-run, and the tag-push CI run
+          # that used to shadow the branch-push one for the same sha.
+          if git diff --cached --quiet; then
+            echo "Infra already at ${IMAGE_TAG} — nothing to commit"
+          else
+            git commit -m "chore(deploy): ingestion → ${IMAGE_TAG}"
             GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
               git push
-
-          echo "Infra repo updated: ingestion+routing → ${IMAGE_TAG}"
+            echo "Infra repo updated: ingestion → ${IMAGE_TAG}"
+          fi
 
       - name: Trigger Flux reconcile (immediate)
         run: |
@@ -103,7 +104,7 @@ jobs:
 
       - name: Wait for Flux to apply new ingestion image
         run: |
-          EXPECTED="gitea.d-ma.be/mathias/ingestion:${{ github.sha }}"
+          EXPECTED="git.d-ma.be/mathias/ingestion:${{ github.sha }}"
           for i in $(seq 1 60); do
             CURRENT=$(kubectl get deploy ingestion -n supervisor \
               -o jsonpath='{.spec.template.spec.containers[0].image}' 2>/dev/null || echo "")
@@ -132,35 +133,3 @@ jobs:
             kubectl describe pods -n supervisor -l app=ingestion | tail -40
             exit 1
           }
-
-      - name: Wait for Flux to apply new routing image
-        run: |
-          EXPECTED="gitea.d-ma.be/mathias/routing:${{ github.sha }}"
-          for i in $(seq 1 60); do
-            CURRENT=$(kubectl get deploy routing -n routing \
-              -o jsonpath='{.spec.template.spec.containers[0].image}' 2>/dev/null || echo "")
-            if [ "$CURRENT" = "$EXPECTED" ]; then
-              echo "✓ Flux applied routing image after ${i}s"
-              break
-            fi
-            sleep 1
-          done
-          kubectl get deploy routing -n routing \
-            -o jsonpath='{.spec.template.spec.containers[0].image}' \
-            | grep -qx "$EXPECTED" \
-            || { echo "✗ Flux did not apply routing image within 60s"; exit 1; }
-
-      - name: Verify routing rollout
-        run: |
-          kubectl rollout status deployment/routing \
-            --namespace routing \
-            --timeout=120s \
-          || {
-            echo "── pod status ──"
-            kubectl get pods -n routing -o wide
-            echo "── events ──"
-            kubectl get events -n routing --sort-by='.lastTimestamp' | tail -20
-            echo "── describe ──"
-            kubectl describe pods -n routing -l app=routing | tail -40
-            exit 1
-          }

.gitea/workflows/ci.yml

@@ -1,9 +1,14 @@
 name: CI
 
-on:
+"on":
   push:
+    # Branch only. A `v*` tag here points at a commit main already tested, so
+    # the tag push re-ran the whole gate and — because cd.yml keys off "CI
+    # succeeded" — triggered a SECOND full image build and deploy for the same
+    # sha. That second deploy then died on "nothing to commit" (hyperguild#118).
+    # Nothing consumes a tag-triggered run: there is no release workflow, and
+    # cd.yml reads github.sha, not the tag.
     branches: [main]
-    tags: ["v*"]
   pull_request:
     branches: [main]
 

.githooks/pre-commit

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Pre-commit secret scan for the hyperguild repo.
+#
+# task check -> security:gitleaks enforces this in CI, but CI is after the
+# push. This catches a staged secret before it ever leaves the machine --
+# the infra#39 rotation pass found exactly this class of leak (a printed
+# credential, committed, archived into git) and there was no local gate to
+# have caught it. Mirrors infra's own .githooks/pre-commit (infra#326).
+#
+# Enable once per clone:   git config core.hooksPath .githooks
+# Bypass if absolutely needed: git commit --no-verify
+
+set -euo pipefail
+
+GITLEAKS="$(command -v gitleaks || true)"
+if [[ -z "$GITLEAKS" && -x "$(go env GOPATH 2>/dev/null)/bin/gitleaks" ]]; then
+  GITLEAKS="$(go env GOPATH)/bin/gitleaks"
+fi
+
+if [[ -z "$GITLEAKS" ]]; then
+  echo "⚠ gitleaks not installed — skipping local secret scan (CI still enforces it)."
+  echo "  Install: go install github.com/zricethezav/gitleaks/v8@latest"
+  exit 0
+fi
+
+echo "→ Scanning staged changes for secrets..."
+if ! "$GITLEAKS" protect --staged --redact --config .gitleaks.toml >/dev/null 2>&1; then
+  echo "  ✗ gitleaks found a secret in the staged changes."
+  echo "    Review with: gitleaks protect --staged --redact --config .gitleaks.toml -v"
+  echo "    If it is a false positive, allowlist it in .gitleaks.toml or add a"
+  echo "    '# gitleaks:allow' comment. Do NOT --no-verify a real secret."
+  exit 1
+fi
+echo "  ✓ no staged secrets"

.gitleaks.toml

@@ -0,0 +1,71 @@
+# gitleaks config for the hyperguild repo (infra#39 — leak prevention pass,
+# Phase 3 checklist item: "gitleaks pre-commit hook in infra AND hyperguild").
+#
+# Ported from mathias/infra's .gitleaks.toml (2026-08-04) — same homelab
+# token-shape rules, minus the SOPS/searxng allowlists infra needed (this
+# repo doesn't use SOPS).
+
+title = "hyperguild gitleaks config"
+
+[extend]
+useDefault = true
+
+# --- Homelab-specific rules -------------------------------------------------
+
+[[rules]]
+id = "homelab-static-bearer"
+description = "Homelab MCP/LLM static bearer or API key assigned a long literal value"
+regex = '''(?i)\b(DMABE_[A-Z0-9_]+|[A-Z0-9_]*MCP_TOKEN|ROUTING_MCP_TOKEN|INFRA_MCP_TOKEN|BRAIN_MCP_TOKEN|GITEA_MCP_TOKEN|LITELLM_MASTER_KEY|LITELLM_SALT_KEY|DMABE_LLMAPI_KEY|BRAIN_PG_DSN)\s*[:=]\s*['"]?([A-Za-z0-9/_+.\-]{16,})['"]?'''
+keywords = ["dmabe_", "mcp_token", "litellm_master_key", "litellm_salt_key", "llmapi_key", "brain_pg_dsn"]
+[[rules.allowlists]]
+description = "Env indirection is not a literal secret"
+regexes = [
+  '''os\.environ''',
+  '''valueFrom''',
+  '''secretKeyRef''',
+  '''\$\{?[A-Za-z_][A-Za-z0-9_]*\}?''',
+  '''REDACTED''',
+  '''<[A-Z_]+>''',
+]
+
+[[rules]]
+id = "homelab-authorization-bearer"
+description = "Hardcoded Authorization: Bearer header"
+regex = '''(?i)authorization['"]?\s*[:=]\s*['"]?bearer\s+([A-Za-z0-9/_+.\-=]{16,})'''
+keywords = ["authorization", "bearer"]
+[[rules.allowlists]]
+description = "Env indirection is not a literal secret"
+regexes = [
+  '''\$\{?[A-Za-z_][A-Za-z0-9_]*\}?''',
+  '''os\.environ''',
+  '''REDACTED''',
+  '''<[A-Z_]+>''',
+]
+
+# --- Global allowlist: claudewatcher's own scrubber test fixtures ------------
+# ingestion/internal/claudewatcher/{scrubber,watcher}_test.go deliberately
+# contain fake secret-shaped literals to test that the scrubber detects and
+# redacts them. Verified 2026-08-04: all 9 findings here are test fixtures
+# (github-pat, jwt, generic-api-key, homelab-authorization-bearer rules) plus
+# 1 doc finding that was gitleaks matching the literal placeholder word
+# "REDACTED" in a plan doc — not a real secret in either case.
+[[allowlists]]
+description = "claudewatcher scrubber test fixtures — deliberately fake secrets"
+paths = [
+  '''ingestion/internal/claudewatcher/scrubber_test\.go$''',
+  '''ingestion/internal/claudewatcher/watcher_test\.go$''',
+]
+
+# infra#344: the allowlist that used to sit here is gone, and so is the reason
+# for it. It suppressed docs/superpowers/plans/2026-04-22-phase4-attempt-wiring.md
+# on the stated grounds that "extracted Secret == 'REDACTED' exactly ... the
+# placeholder text itself, not a real credential" (verified 2026-08-04). That was
+# not what the file contained: line 1054 carried a real 40-char hex Gitea PAT in
+# an `Authorization: token ...` header. Confirmed dead by side-effect — GET
+# /api/v1/user with it returns 401 — and redacted in that file, so there is now
+# nothing to allowlist.
+#
+# The `paths` entry also made the block far broader than its description: gitleaks
+# ORs global allowlist clauses and ignores `condition = "AND"`, so the whole file
+# was immune, not just lines matching /REDACTED/. A live token added to that doc
+# would have been suppressed on the strength of a note about a different value.

.gitleaksignore

@@ -0,0 +1,33 @@
+# Historical gitleaks findings, dispositioned (infra#326 / infra#317).
+#
+# WHY THIS FILE AND NOT .gitleaks.toml:
+# This is a finding in git HISTORY, surfaced by the full-history audit
+# (`task security:gitleaks:history`). The working-tree scan that gates commits
+# (`task security:gitleaks`, the pre-commit hook, CI) is clean. Suppressing by
+# PATH in .gitleaks.toml would also blind the working-tree scan for that file
+# forever; a fingerprint pins one finding in one commit, so a NEW secret in the
+# same file still fires.
+#
+# History is not rewritten here, so the remediation for a real leak is
+# ROTATION -- making the committed value worthless -- never scrubbing.
+#
+# Dispositioned 2026-08-29. Re-check with: task security:gitleaks:history
+
+# --- Real credential, ALREADY DEAD -------------------------------------------
+# A Gitea PAT pasted into a CD-watching command in a planning doc
+# (`Authorization: token <40-hex>`, last_eight 3105a670).
+#
+# Verified dead 2026-08-29: authenticating against
+# GET https://git.d-ma.be/api/v1/user with this exact value returns 401, so the
+# committed token no longer grants anything. It was almost certainly invalidated
+# by the early-August rotation of the `mathias` PATs (the same rotation whose
+# fan-out caused infra#260, where CI copies of the old value kept failing).
+#
+# No rotation action outstanding. Kept as a fingerprint rather than removed from
+# history because history cannot be rewritten here.
+#
+# The generalisable lesson is recorded separately: a credential printed into a
+# doc/transcript is permanent, so the only remedy is rotating it -- which in
+# this case had already happened for unrelated reasons, by luck rather than by
+# the leak being noticed.
+c9310b1079478bf4430b0a2dfb25445d7ccc9b59:docs/superpowers/plans/2026-04-22-phase4-attempt-wiring.md:curl-auth-header:1053

.mcp.json

@@ -6,6 +6,13 @@
       "headers": {
         "Authorization": "Bearer ${BRAIN_MCP_TOKEN}"
       }
+    },
+    "gitea": {
+      "type": "http",
+      "url": "https://git-mcp.d-ma.be/mcp",
+      "headers": {
+        "Authorization": "Bearer ${GITEA_MCP_TOKEN}"
+      }
     }
   }
 }

AGENTS.md

@@ -27,6 +27,14 @@ and climate/sustainability tech.
 
 These rules apply to every task across every project, regardless of harness.
 
+0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line:
+   - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours.
+   - **Load the relevant skill** — see trigger table in *Engineering Skills* below.
+   - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test.
+   - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done?
+
+   **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it.
+
 1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
    Think before coding; if the problem is unclear, ask or state assumptions before acting.
 2. **Minimum viable code.** Solve with the smallest change that works. Nothing
@@ -40,14 +48,124 @@ These rules apply to every task across every project, regardless of harness.
    logical change (one tool, one fix, one test) with passing tests. Main is always
    deployable. Never create long-lived feature branches.
 
-   **Exception — parallel agents on same repo:** If another agent is known to be
-   actively working on the same repo simultaneously, create a short-lived branch
-   (`agent/<description>`), finish the task, and merge to main within the same
-   session. Do not leave agent branches open between sessions.
+   **The PR trigger is RISK, not concurrency.** `risk/low` work commits straight to
+   main with CI as the gate — that is most work and is unchanged. `risk/medium` and
+   above opens a PR, even solo, even with nobody waiting to review it. This mirrors
+   the tiered merge model in `assessor-loop`
+   `method/transfer-to-a-regulated-organisation.md` §4.1, so the estate practises
+   what it sells instead of merging everything on green and claiming otherwise.
 
-   **Exception — external contributor or client four-eyes requirement:** Use
-   PR flow only when a human reviewer outside the project is required. Document
-   the reason in PROJECT.md.
+   **Concurrency is NOT a reason to branch.** Measured 2026-08-29 across three real
+   collisions between parallel sessions: two were not branching problems at all — a
+   generated artifact written to the same path by both (branching turns that into a
+   merge conflict on a 33k-line JSON), and uncommitted work in a shared checkout
+   (a per-session worktree fixes it) — and the third was an ordinary non-fast-forward
+   push resolved by rebase in seconds. Use a worktree per session on shared repos and
+   timestamp generated artifacts. Do not reach for a branch.
+
+   Branch+PR flow carries documented costs on solo repos: merging auto-closes gated
+   issues, review comments live on a thread separate from the issue's, and a
+   merged-and-deleted branch cannot be amended (brain:
+   `gitea-pr-merge-autoclose-and-review-comment-footguns`). Those are the price of
+   the `risk/medium`+ lane — paid deliberately, not incurred by accident.
+
+   **Exception — external contributor or client four-eyes requirement:** Use PR flow
+   when a human reviewer outside the project is required. Document the reason in
+   PROJECT.md.
+
+   **Exception — a GitOps repo where a branch cannot be reconciled.** In a repo whose
+   deployment watches one branch (`mathias/infra`: Flux watches `main`), a branch is
+   invisible to the thing that applies it. A `risk/medium` change to `alerts.yaml` or
+   `litellm-config.yaml` can be linted on a branch but never *exercised* there, so a
+   PR would buy a review of a state that was never deployed.
+
+   There, `risk/medium`+ work stays on `main` and instead requires a **recorded
+   adversarial review pass before the push** — `skills:pr-gatekeeper` or equivalent,
+   reviewing the staged diff. **The reviewer's verdict goes in the issue, not a PR
+   thread.** No verdict recorded means the lane was not used, and saying "the gate was
+   green" is not the same claim.
+
+   Be honest about what this is: a recorded *independent* pass, not four-eyes in the
+   sense `assessor-loop` §4.1 means for a regulated organisation, because the reviewer
+   is an agent. It is more than the repo had and less than the model it mirrors; do not
+   describe it as the stronger property. (infra#470, decided 2026-09-29.)
+
+   This lane depends on the `risk/` label being right. A label that triggers a heavier
+   lane is load-bearing, not cosmetic — if work that belongs in it is unlabelled, the
+   lane silently does not apply.
+
+6. **Close the loop — every substantive task ends with the same ritual.** Shipping
+   the code is not the end of the task; capturing it is. Run this unprompted:
+   - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or
+     new/changed ADR, patch for a fix; docs in the same commit). Check the repo's
+     actual last tag — stated versions in docs drift stale.
+   - **Push** main and the tag (CI is the gate).
+   - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) —
+     the reusable patterns and the footguns that would bite anyone again, never
+     project status. See *Knowledge base — when to write* below.
+   - **File discovered-but-deferred work as tracker issues** on the project's own
+     repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let
+     "out of scope, recorded" rot in a commit message; make it a ticket with a
+     source pointer.
+   - Surface the brain entries and issue numbers in the closing summary so the
+     trail is auditable.
+
+   **Chat is not a durable store. Never rely on Mathias remembering anything.**
+   Every gap, caveat, risk, open question and next step must land in one of four
+   places before the turn ends: **the brain**, **a repo** (code, docs, ADR),
+   **a tracker issue**, or **a plan file**. A finding stated only in conversation is
+   lost the moment the session closes — and this estate has repeatedly proved that a
+   remembered convention is an unreliable control.
+
+   This applies hardest to what is tempting to leave as a closing remark: "worth
+   knowing X isn't enforced yet", "this is a convention, not a gate", "we should
+   revisit Y". Those are exactly the items that need a locator. If it is worth
+   saying in a summary, it is worth writing where it can be found again without you.
+
+7. **Finish what's closable — only involve me for a genuine call.** If a
+   tracker issue, PR, or checklist item is demonstrably resolved — the fix
+   landed, the state changed, you verified it live — close/merge/check it off
+   in the same turn. Don't leave it open "for the record" or park it waiting
+   on me to confirm something that already happened; that's bookkeeping, not
+   a decision. Reserve asking me (`AskUserQuestion`, a `DECISION NEEDED`
+   comment, or otherwise pausing) for when it's genuinely mine to call:
+   irreversible or prod/host-impacting actions, a real judgment call with no
+   clearly-better option, ambiguous intent, or anything secret-writes/
+   destructive-git already gate. Before claiming something is closable,
+   verify it live (re-check the issue, re-run the command) rather than
+   trusting your own earlier summary (brain: `filed-issue-not-same-as-fixed`).
+
+8. **Control code needs an adversary, not a checklist.** Code whose job is to
+   refuse, deny, gate or contain is not adequately verified by a green gate.
+   Rule 5 makes CI the quality gate and that holds for ordinary work — but a
+   passing suite only asserts what its author already thought of, and for a
+   control the author is precisely the person whose imagination just failed.
+   Measured on `dispatch#75`: five review rounds, five real escapes verified by
+   execution, and **CI was green on every one of them** while `git rm
+   ././.dispatch-allow` deleted the file the control existed to protect. So
+   route this work through a review with authority to block, instructed to
+   verify by execution rather than by reading the implementation. Expect to be
+   blocked more than once; that is the control working, not the reviewer being
+   difficult. (brain: `a-green-gate-is-not-evidence-for-control-code`; the
+   practices live in the `pr-gatekeeper` agent.)
+
+9. **A test's name must not claim more than its assertions prove.** Name a test
+   after the mechanism it observes, not the goal it serves.
+   `DoesNotInheritEnv` is honest; `IsContained` is a claim the test cannot
+   support. This is not pedantry about naming — when name and assertion
+   diverge, the name wins in the reader's head and the gap becomes invisible,
+   which is what lets the defect survive review. Found three times in one PR,
+   twice in tests written to fix the previous instance of it; each passed while
+   the thing it was named for was exploitable. If you cannot name the mechanism,
+   you do not yet know what the test observes.
+
+## CAD sprint patterns
+
+Two CAD sprint archetypes (defs: brain `wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16`):
+- **Inception Sprint** — birth a new repo. Oath-gated close; tag only once every clause holds. Brain: `.../inception-sprint-and-oath`.
+- **Sweep Sprint** — clear an existing backlog. Parallel read-only research per issue → sequential one-issue-per-commit execution. Brain: `.../sweep-sprint-and-oath`.
+
+Shared: decisions that are yours, not the agent's, surface as `DECISION NEEDED` (question/options/recommendation/blocks) — ask live if you're present, else comment and wait, never act past it. Live-breaking regressions get `git revert`, never forward-fixed; host-network work skips even read-only research (solo, synchronous, you present). Rule 6's closing ritual only fires once every Oath clause genuinely holds — blocked = descoped-and-tracked, never marked done.
 
 ## Default stack
 
@@ -59,7 +177,7 @@ These rules apply to every task across every project, regardless of harness.
 | Containers | Docker Compose (dev), k3s (prod) | — | — |
 | DB | PostgreSQL + sqlc | SQLite | — |
 | Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
-| Logging | slog (structured) | — | — |
+| Logging | slog (structured) | stdlib `logging` w/ structured `extra=` (or structlog) | — |
 | Testing | Table-driven, testify | — | — |
 | Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — |
 
@@ -68,7 +186,12 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 ## Code conventions
 
 - **Go style**: golines, gofumpt, golangci-lint
-- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
+- **Python style** (fallback language): ruff (format+lint, one tool), mypy --strict (non-negotiable,
+  matches Go's static typing discipline), pytest + pytest-cov (table-driven via
+  `@pytest.mark.parametrize`), uv (venv+deps+lock, one tool), pydantic-settings (typed env-var config
+  — same principle as Go's typed structs), src-layout + `pyproject.toml` only (no `setup.py`)
+- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return.
+  Python: `raise X from e` (exception chaining, same principle) — never bare `except`, never silent `pass`
 - **Naming**: stdlib conventions, no stuttering
 - **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
 - **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
@@ -78,6 +201,26 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
 - **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
 - **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
 
+## Secret handling (every harness, every command)
+
+Tool output is persisted: terminal → `~/.claude/projects` transcripts →
+claudewatcher → brain/wiki → gitea history. A secret printed once is
+searchable forever, and clearing it means rotating the key. So:
+
+1. **Never print, echo, log, or transform a secret to inspect it.** No
+   `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform
+   to defeat `op run`'s output masking (it masks raw values; base64 hides them
+   from the mask — that exact trick leaked a key on 2026-06-11).
+2. **Secrets stay in the subprocess.** Reference them only as env vars consumed
+   *inside* `op run --env-file ~/.op-env -- <cmd>`. Never place a literal secret
+   in a command's argv (it lands in the tool call and the transcript).
+3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` —
+   never `${X:-...}` (returns the value when set) and never echo a substring of it.
+4. **Cross-host secrets:** run the secret-consuming command on the host that has
+   the secret; do not forward a raw key over ssh argv/stdout.
+5. If a secret does leak into output, say so immediately and flag it for rotation —
+   don't bury it.
+
 ## Infrastructure
 
 Three machines on Tailscale:
@@ -86,10 +229,10 @@ Three machines on Tailscale:
 |---------|------|-----------|
 | koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
 | iguana | Services, builds | M2 Ultra Mac |
-| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+| flamingo | Daily driver, edge | Apple Silicon Mac, ~/dev is here |
 
 - **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
-- **Orchestration**: k3s cluster across all three machines
+- **Orchestration**: k3s on koala only — single control-plane node, no workers (verified 2026-08-30). iguana and flamingo are on the tailnet but are not cluster members
 - **Networking**: Tailscale mesh
 
 ## Project landscape
@@ -156,10 +299,16 @@ entries that age well are about *why*, *how to avoid*, and *what to do when*.
 |---------|-------|-------|
 | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
 | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
-| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
-| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
+| **Anything HTTP-only (curl, scripts)** | Tailnet only: `POST https://koala.tail30472e.ts.net:8443/query` with `{"query":"..."}`, sending `BRAIN_MCP_TOKEN` (not yet enforced on REST, hyperguild#149). The public `brain-mcp.d-ma.be` serves `/mcp` only (infra#517). | `POST .../write` with `{"content":"...","wing":"...","hall":"..."}` |
+| **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
 
-- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
+- **Scoping — the brain holds no confidential client content.** Nothing on the read path
+  filters by client: every token holder can read every wing, and `wing` on `brain_query`
+  is an optional argument, not an access control. Client confidentiality is enforced only
+  at write time (`capture`'s I1 gate refuses internal/confidential). So never `brain_write`
+  client material; generalise it first or keep it in the client's own repo. (hyperguild#144,
+  decided 2026-10-01. This line previously claimed client projects were filtered; they
+  were not.)
 - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
   fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
   on the koala k3s cluster; don't hardcode local-only model names into the
@@ -185,10 +334,11 @@ When working on a project tagged with a client name:
 
 ## Harness-agnostic principles
 
-This context is designed to work with any AI coding tool:
-- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
-- Pi Coding Agent, Mistral Vibe, Antigravity
-- Any tool that accepts a system prompt or reads a markdown context file
+Supported harnesses (2026-09-01) — Cursor and Aider were dropped; do not
+re-add adapters for them:
+- Claude Code, Antigravity, OpenCode, Mistral Vibe, Crush, Pi Coding Agent
+- Open WebUI, Charmbracelet Mods, or any tool that takes a system prompt string
+- Any other tool that reads `AGENTS.md`, which is the de facto convention
 
 The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
 Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
@@ -200,34 +350,75 @@ Canonical sources of truth:
 - Project: `<repo>/.context/PROJECT.md` (per-repo)
 
 Derived files (committed, regenerated by `task context:sync`):
-- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
-  `.context/system-prompt.txt`
+- `CLAUDE.md`, `AGENTS.md`, `.context/system-prompt.txt`
+
+Repos still carrying `.cursorrules`, `.aider.conventions.md` or
+`.aider.conf.yml` are stale: nothing regenerates them. Delete them the next time
+you touch the repo, along with their entries in that repo's `task check`
+assertion.
 
 Workflow:
 1. Edit a canonical file. Run `task context:sync`. Commit canonical and
    derived together. Push.
-2. On any other host, `git pull` brings both. Claude Code (tree-walking)
-   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
-   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+2. On any other host, `git pull` brings both. Which file a harness reads does
+   NOT split cleanly by lookup strategy, so do not reason from the strategy:
+   - `CLAUDE.md` — Claude Code (walks up the tree)
+   - `AGENTS.md` — Crush, Pi, Antigravity (cwd-only), OpenCode (project root,
+     global at `~/.config/opencode/AGENTS.md`), and Mistral Vibe, which **walks
+     up** from cwd and takes the first `AGENTS.md` it finds
+     (user-level `~/.vibe/AGENTS.md`)
+   - `.context/system-prompt.txt` — Open WebUI, Mods, raw API calls; not read by
+     any harness, it is for pasting
+
+   Vibe tree-walks for `AGENTS.md`, so "tree-walkers use CLAUDE.md" is false.
+   Each repo's `AGENTS.md` embeds the canonical and is the first one found from
+   inside that repo, so this works — but by construction, not by luck.
 3. `task check` runs `context:sync` then asserts `git status --porcelain`
    is empty over the derived files (catches both modified-tracked drift
    and missing-untracked adapters). A drift fails the check with a
    message telling you to stage the regenerated files.
 
-Behavior rules in this file and per-project rules in `PROJECT.md` apply
-unconditionally on every host, every harness.
+Behavior rules in this file and per-project rules in `PROJECT.md` apply on every
+host and every harness.
+
+**Where a project rule contradicts a rule here, the project rule governs — and it
+must state its reason.** Both halves matter: the project file wins because it knows
+something this file cannot (infra's Flux constraint is real and not visible from
+here), and it must say why because a bare override is indistinguishable from drift.
+
+This replaces the previous wording, which said rules here and in `PROJECT.md` both
+apply *"unconditionally"*. That was not a tiebreak but a contradiction, and it went
+unnoticed until rule 5 and infra's "never create feature branches" had to be obeyed
+at the same time (infra#470). A standard can hold two individually sensible clauses
+that are jointly unsatisfiable, and survive for as long as everyone reads it
+charitably — the same failure the Inception Sprint Oath's G6 had.
 
 ## Engineering Skills
 
-Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.
+Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Load at task start — not "on demand" but on schedule, before writing code. Browse `SKILLS_INDEX.md` for the full list.
 
-See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.
+**Claude Code** installs the repo as a plugin from the marketplace the same repo hosts. That path also carries the `secret-guard` and `pre-task-ritual` hooks and the brain/gitea/infra MCP servers, which symlinks cannot:
 
-Key skills:
-- **TDD**: always write tests first — load `tdd` skill
-- **Code Review**: load `code-review` skill before any review
-- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
-- **Problem first**: load `problem-analysis` skill before coding non-trivial features
+```
+/plugin marketplace add https://git.d-ma.be/mathias/skills.git
+/plugin install skills@mathias
+```
+
+Skills are **namespaced** under Claude Code: load `tdd` as `skills:tdd`. The trigger table below uses bare names — prefix them.
+
+**Crush, Pi and OpenCode** have no plugin system and are wired by `install.sh` as one directory symlink per harness via `~/.agents/skills`. Do not clone the checkout into `~/dev`: that folder is iCloud-shared between the Macs and spans two path roots (`/Users/mathias` vs `/home/mathias` on koala), so a checkout there is a git working tree with two concurrent writers, and any absolute symlink stored in it is broken on one side by construction (skills#23). Leave `SKILLS_CHECKOUT_DIR` at its host-local default.
+
+Check a host with `task doctor` in the skills repo; it also runs automatically at session start via the plugin.
+
+**Skill trigger table — load before starting, not after getting stuck:**
+
+| Task type | Load |
+|-----------|------|
+| Any feature or bug fix | `tdd` |
+| Refactor or design | `clean-code` or `solid` |
+| Debug | `problem-analysis` |
+| Review code or PRs | `code-review` |
+| Frame a problem before coding | `problem-analysis` |
 
 ---
 
@@ -297,7 +488,11 @@ the routing pod; brain tools moved to the brain MCP.
 
 The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
 `/ingest-path`, `/backfill-refs`, `/pass-rate`) remains available on port 3300
-for shell scripts and non-MCP clients.
+for shell scripts and non-MCP clients, **with the same bearer token as `/mcp`**
+(`BRAIN_MCP_TOKEN`; hyperguild#149). It is not served on the public host
+(infra#517): use the tailnet (`koala:8443`) or in-cluster
+`ingestion.supervisor.svc:3300`. `/ingest-path` and `brain_ingest` `path`
+accept only paths inside `brain/raw/`.
 
 `brain_answer(query)` performs BM25 retrieval + LLM synthesis (berget.ai
 gemma4:31b → iguana fallback). `brain_classify(text)` infers doc type, title,

CLAUDE.md

@@ -64,7 +64,11 @@ the routing pod; brain tools moved to the brain MCP.
 
 The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
 `/ingest-path`, `/backfill-refs`, `/pass-rate`) remains available on port 3300
-for shell scripts and non-MCP clients.
+for shell scripts and non-MCP clients, **with the same bearer token as `/mcp`**
+(`BRAIN_MCP_TOKEN`; hyperguild#149). It is not served on the public host
+(infra#517): use the tailnet (`koala:8443`) or in-cluster
+`ingestion.supervisor.svc:3300`. `/ingest-path` and `brain_ingest` `path`
+accept only paths inside `brain/raw/`.
 
 `brain_answer(query)` performs BM25 retrieval + LLM synthesis (berget.ai
 gemma4:31b → iguana fallback). `brain_classify(text)` infers doc type, title,

DECISIONS.md

@@ -4,6 +4,74 @@ Record *why* things are the way they are. Future-you will thank present-you.
 
 ---
 
+## 2026-05-28 — three active harnesses: hyperguild, agentsquad, Crush (extends earlier boundary decision)
+
+**Context:** After wiring Crush to LiteLLM in May 2026, there are now three active harnesses.
+The earlier boundary decision only covered hyperguild vs agentsquad. Crush's role was undefined.
+
+**Decision:** Three harnesses, three distinct roles, shared skills layer.
+
+| Harness | Engine | Primary use | Brain MCP? | Routing pod? | Skills? |
+|---------|--------|-------------|------------|--------------|---------|
+| **hyperguild** | Claude Code + MCP | Disciplined solo coding sessions, TDD/review/debug workflows | Yes | Yes | Yes (SKILL.md) |
+| **agentsquad** | OpenCode + LiteLLM | Multi-agent task execution, executor/reviewer pipelines | No | No (own routing) | Yes (SKILL.md) |
+| **Crush** | Charmbracelet TUI + LiteLLM | Interactive local coding, quick iterations on flamingo | No (not yet) | No (direct LiteLLM) | Yes (SKILL.md) |
+
+**Crush specifics (as of 2026-05-28):**
+- Config: `~/.config/crush/crush.json` on flamingo (see brain: `homelab/facts/crush-litellm-wiring-2026-05`)
+- Connects directly to LiteLLM at `http://koala:4000/v1/` using `sk-local-123`
+- Auth type: `openai-compat` (not `openai`)
+- Does NOT go through the routing pod — model selection is manual in the Crush UI
+- Brain MCP not wired — Crush has no MCP client capability today; revisit if Crush adds MCP support
+
+**Shared across all three:**
+- `mathias/skills` — any SKILL.md file works in all three harnesses
+- LiteLLM proxy on koala (`http://koala:4000/v1/`) — Crush and agentsquad both route through it; hyperguild does too for local model calls
+
+**Consequences:** No consolidation needed. crush.json must be kept in sync when litellm_config.yaml model names change. The `crush.json` canonical location is `~/.config/crush/crush.json` on flamingo — not yet tracked in a dotfiles repo (track as tech debt).
+
+---
+
+## 2026-05-28 — "field benchmark" for local models = pass-rate at scale (supersedes GOTTH eval suite)
+
+**Context:** The GOTTH eval suite (45 offline prompts across 5 categories) was replaced by
+a "field benchmark" in May 2026, but the replacement was never defined concretely.
+
+**Decision:** The field benchmark is per-skill pass rate over real routing pod usage,
+collected automatically by `internal/routing/passrate.go` and exposed at:
+
+```
+GET /pass-rate?skill=<name>&window=<duration>
+```
+
+No separate eval suite. No synthetic prompts. The benchmark runs itself once the routing
+pod receives real traffic. Target: 30-day rolling window per skill, reviewed monthly.
+
+**Bootstrap note:** With no session history, `passrate.go` returns `nil` and the router
+defaults to the thinking model for every call. The fast-model path activates only after
+real pass-rate data accumulates. Seed with real usage — do not pre-populate.
+
+**Consequences:** Zero maintenance overhead for the benchmark. The tradeoff is that results
+are only meaningful after ~2 weeks of real usage, and skills that are rarely invoked will
+have statistically thin pass-rate data. Revisit if a skill has fewer than 20 calls in 30 days.
+
+---
+
+## 2026-05-28 — brain injection in skill handlers: review is done, others unverified
+
+**Context:** The April 2026 scope reset listed "brain_query injection into skill handlers"
+as the top priority. As of 2026-05-28, `internal/skills/review/handlers.go` calls
+`brain.Query(ctx, ...)` before dispatching to the LLM — confirmed in code review.
+Status of debug, retrospective, and trainer handlers is unverified.
+
+**Decision:** Treat review as the reference implementation. Verify debug, retrospective,
+trainer against the same pattern before shipping new skill work. Tracked in issue #32.
+
+**Consequences:** The April concern may be stale for review. A one-pass audit of the other
+three skill handlers closes this fully.
+
+---
+
 ## 2026-04-08 — AGENTS.md as cross-tool standard, not CLAUDE.md
 
 **Context**: Multiple tools (Crush, Pi, Antigravity) read `AGENTS.md` natively. Claude Code reads `CLAUDE.md`. Building on `CLAUDE.md` as the primary format locks into one vendor.

Dockerfile.routing

@@ -1,30 +0,0 @@
-# syntax=docker/dockerfile:1
-
-# ── Build stage ───────────────────────────────────────────────────────────────
-FROM golang:1.26-bookworm AS builder
-
-ARG VERSION=dev
-WORKDIR /src
-
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
-    go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
-    -o /out/routing ./cmd/routing
-
-# ── Runtime stage ─────────────────────────────────────────────────────────────
-FROM gcr.io/distroless/base-debian12
-
-COPY --from=builder /out/routing /usr/local/bin/routing
-COPY config/ /app/config/
-
-ENV SUPERVISOR_CONFIG_DIR=/app/config/supervisor
-ENV ROUTING_PORT=3210
-
-EXPOSE 3210
-
-USER 65532:65532
-
-ENTRYPOINT ["/usr/local/bin/routing"]

ICEBOX.md

@@ -0,0 +1,49 @@
+# Icebox — retired code (recoverable, not destroyed)
+
+Per issue #75 (consolidate to a single harness), the routing-pod path was removed
+from the live tree. It is **preserved and recoverable**, not deleted without trace.
+
+## What was iceboxed (2026-07-01, issue #75)
+
+| Path | Why |
+|------|-----|
+| `cmd/routing/` | The routing MCP-server binary; every skill call was wrapped through the broken pass-rate router (`wrap(skillName)`). |
+| `internal/routing/` | Router / Fetcher / Policy / pass-rate. Signal is survivorship-biased and unusable as-is (infra#174). |
+| `internal/skills/{review,debug,retrospective,trainer,project}/` | Skill handlers usable **only** through `cmd/routing` (verified: each imported solely by `cmd/routing`). |
+| `Dockerfile.routing` | Built `cmd/routing` exclusively. |
+| `.gitea/workflows/cd.yml` (routing steps only) | Removed the routing image build + infra image-bump + Flux-wait/rollout-verify for routing; **ingestion build/deploy is unchanged**. |
+
+## Why
+
+The live minimal harness is `cmd/hyperguild` + `brain-mcp` (+ `gitea-mcp` available) —
+that is what ran the infra#170 loop-1 experiment (routing/injection machinery off) and
+closed it twice. `cmd/hyperguild` has **zero** transitive dependency on `internal/routing`
+or `cmd/routing`'s packages (it imports only `internal/tier`). The routing pass-rate signal
+is being retired, not resurrected (fresh start, per infra#174).
+
+## How to recover
+
+Everything above is preserved at commit `00e5f62` under:
+
+- **tag** `icebox/cmd-routing-2026-07-01`
+- **branch** `icebox/cmd-routing`
+
+```bash
+# inspect
+git checkout icebox/cmd-routing-2026-07-01
+
+# restore specific packages onto a branch
+git checkout icebox/cmd-routing-2026-07-01 -- cmd/routing internal/routing \
+  internal/skills/review internal/skills/debug internal/skills/retrospective \
+  internal/skills/trainer internal/skills/project Dockerfile.routing
+```
+
+## Deliberately NOT touched here (separate scope)
+
+- **Live k8s routing deployment** (`infra` repo, `k3s/apps/routing/`) still runs its last
+  image; CD no longer rebuilds/redeploys it. Tearing down that deployment is a separate
+  infra-repo task.
+- **`internal/skills/{brain,org,sessionlog}/`** — kept per #75; already had no importer
+  (orphaned before this cut), harmless, compile + test green.
+- **`config/supervisor/{review,debug,retrospective,trainer-*}.md`** — routing skill prompts,
+  now orphaned data; left in place (not code, no build impact).

Procfile

@@ -1,2 +1 @@
 ingestion: cd ingestion && INGEST_BRAIN_DIR=../brain INGEST_PORT=3300 INGEST_WATCH_INTERVAL=30 go run ./cmd/server/
-supervisor: SUPERVISOR_CONFIG_DIR=./config/supervisor SUPERVISOR_MODELS_FILE=./config/models.yaml SUPERVISOR_SESSIONS_DIR=./brain/sessions INGEST_BASE_URL=http://localhost:3300 INGEST_SVC_URL=http://localhost:3300 go run ./cmd/supervisor/

README.md

@@ -5,14 +5,36 @@ Instead of letting Claude Code do whatever it wants, hyperguild enforces structu
 workflows (TDD red/green/refactor), logs every session, and accumulates learnings
 into a searchable brain.
 
+**This repo is also where `brain-mcp` lives** — the MCP server at
+`brain-mcp.d-ma.be` that `brain_query`, `brain_write`, `brain_read`, `brain_edit`
+and `capture` are served from. It is not a separate deployable; see
+[Where brain-mcp lives](#where-brain-mcp-lives).
+
+## Hypothesis
+
+> We believe routing skill tasks through local models, backed by brain context,
+> produces measurably better outcomes than raw Claude Code alone —
+> measurable by per-skill pass rate over rolling 30-day windows
+> (available at `GET /pass-rate?skill=<name>&window=30d` on the brain pod).
+
+This is the falsifiable claim the routing pod and pass-rate infrastructure exist to test.
+If per-skill pass rates don't improve over baseline (all-cloud) after 30 days of real
+usage, the fast-model routing path should be reconsidered.
+
+## Harness
+
+**hyperguild = Claude Code + MCP.** This is a supervisor for Claude Code sessions specifically.
+For multi-agent orchestration (OpenCode + LiteLLM, executor/reviewer pipelines), see
+[agentsquad](https://git.d-ma.be/mathias/agentsquad) — a separate harness for a different
+orchestration model. Skills (mathias/skills) are shared between both.
+
 ## How it works
 
 ```
 Your Claude Code session (in any project)
     │
     │  MCP over HTTP (Tailscale)
-    ├──▶ supervisor  :3200 (NodePort 30320 on koala) — skill workers: tdd, debug, spec, …
-    ├──▶ routing     :3210 (NodePort 30310 on koala) — Mode 2 only: review, debug, retrospective, trainer
+    ├──▶ routing     :3210 (NodePort 30310 on koala) — review, debug, retrospective, trainer
     └──▶ brain       :3300 (NodePort 30330 on koala) — brain_query, brain_write, brain_ingest, session_log
                        │
                        └─ also serves the legacy REST endpoints (/query, /write, /ingest, …)
@@ -20,34 +42,113 @@ Your Claude Code session (in any project)
     ▼
 brain/
 ├── sessions/       — JSONL log, one file per session_id
-├── wiki/           — searchable knowledge (full-text)
-│   ├── concepts/
-│   ├── entities/
-│   └── sources/
-├── raw/            — retrospective output, staged for review
-└── training-data/  — SFT/DPO/RL data (Phase 2)
+├── wiki/           — searchable knowledge (wing/hall layout)
+│   ├── homelab/
+│   ├── claude-sessions/
+│   └── ...
+└── knowledge/      — legacy flat notes (migration pending: hyperguild#22)
 ```
 
+## Where brain-mcp lives
+
+`brain-mcp` is served from **`ingestion/internal/mcp`** in this repo, at
+**`brain-mcp.d-ma.be`**. It is a component *inside* the `ingestion` service, not
+a standalone deployable — one pod in the `supervisor` namespace serves the MCP
+endpoint, the REST API, and the claudewatcher together.
+
+| You are looking for | It is here |
+|---|---|
+| The MCP tool surface (`brain_query`, `brain_write`, `brain_read`, `brain_edit`, `capture`, …) | `ingestion/internal/mcp` |
+| The HTTP/REST API (`/query`, `/write`, `/ingest`) | `ingestion/internal/api` |
+| Session ingestion from Claude Code transcripts | `ingestion/internal/claudewatcher` |
+| The brain *content* (notes, wings, halls) | [`mathias/brain`](https://git.d-ma.be/mathias/brain) — a separate repo |
+| Deployment manifests | `config/supervisor` |
+
+### Why it is not its own repo
+
+Asked and decided in [#91](https://git.d-ma.be/mathias/hyperguild/issues/91)
+(part 2). `internal/mcp` imports 17 of ingestion's other internal packages and
+has exactly one importer — it is the MCP facade over the service's own
+internals, so "move it out" resolves to renaming `ingestion`, publishing 17
+packages as a shared library, or maintaining a shim. The discoverability problem
+that prompted the question is answered by naming it here instead.
+
+Full reasoning, including the reversal trigger: brain
+`wiki/hyperguild/decisions/brain-mcp-stays-in-ingestion-fix-discoverability-by-name`.
+
+## Ingest revises, it does not overwrite
+
+Re-ingesting a source **merges into the page already on disk** rather than
+replacing it. Previously the write was unconditional, so a second ingest of the
+same source discarded everything accumulated since — including hand-written
+sections.
+
+The merge is deliberately asymmetric in the existing page's favour:
+
+| On the page | In the fresh extraction | Result |
+|---|---|---|
+| a section | the same section | **the on-disk version wins** |
+| — | a new section | added |
+| a bullet list (`Sources`, `Key Claims`, …) | more bullets | unioned, no duplicates |
+| an append section (`Open Questions`, `Updates`, …) | more lines | only genuinely new lines appended |
+| frontmatter | frontmatter | **the on-disk frontmatter wins** |
+
+So an extraction can add to a note but never silently rewrite what a human put
+there, which is what makes it safe to run on every ingest rather than behind a
+review gate.
+
+Re-ingesting unchanged content is **byte-identical** — no diff, so brain-sync
+does not commit noise that hides real edits.
+
+Two fields are **generator-owned** and do get refreshed on a revise:
+`last_updated` and `source_hash`. Everything else on disk wins. The boundary is
+an explicit allowlist, so a field nobody has thought about stays human-owned.
+
+### Disagreement is reported, not resolved
+
+When the fresh extraction produces a *different version* of a section that
+already exists, the on-disk version still wins — but the run now says so:
+
+```
+wiki/sources/shape-up.md: source now disagrees on section "Summary" — on-disk version kept
+```
+
+That line lands in `log.md` with the rest of the run's warnings. Without it, "the
+source is unchanged" and "the source changed its mind and we ignored it" look
+identical from the outside.
+
+This is deliberately **textual** disagreement, not semantic contradiction: cheap,
+deterministic, no model on the write path. Deciding whether a disagreement is a
+genuine contradiction stays with the Judge-gated `brain-enrich` pass, which is
+approval-gated by design. Detection here, adjudication there.
+
+## Re-ingesting an unchanged source is skipped
+
+Ingest stores `source_hash` — sha256 of the ingested **body**, frontmatter
+excluded — on the source page. A later ingest of the same source compares it
+first and skips extraction entirely when it matches, reporting the skip rather
+than doing it silently.
+
+Body-only is deliberate: a re-crawl that stamps a new fetch date has not changed
+the source, and treating that as drift would re-extract the corpus every time a
+crawler ran. A missing or unreadable hash always means "extract" — a missed skip
+costs one extraction, a wrong skip loses an update.
+
 ## Phase 1 tools (available now)
 
 | Tool | What it does |
 |------|-------------|
-| `tdd_red` | Writes a failing test for a spec, verifies it fails |
-| `tdd_green` | Writes the minimal implementation to make tests pass |
-| `tdd_refactor` | Cleans up implementation while keeping tests green |
 | `session_log` | Appends a structured entry to the session JSONL log |
-| `retrospective` | Reads the session log, identifies novel learnings, writes to brain/raw/ |
+| `retrospective` | Reads the session log, identifies novel learnings, writes to brain |
+| `review` | Structured code review via local model, brain-context injected |
+| `debug` | Hypothesis-driven debugging via local model |
 | `brain_query` | Full-text search over brain/wiki/ |
-| `brain_write` | Writes a note to brain/raw/ (with optional YAML frontmatter) |
+| `brain_write` | Writes a note to brain (with wing/hall routing) |
+| `brain_answer` | BM25 + LLM synthesis — Q&A over brain corpus |
 | `tier` | Returns the current connectivity tier (1=cloud, 2=LAN, 3=offline) |
 
-## Start the servers
-
-```bash
-# Requires goreman: go install github.com/mattn/goreman@latest
-task start    # starts ingestion (:3300) + supervisor (:3200) via goreman
-task stop     # kills both by port
-```
+> **Note:** `tdd_red/green/refactor` and `spec` were retired in Plan 7 (2026-05-12).
+> They are now SKILL.md files in [mathias/skills](https://git.d-ma.be/mathias/skills).
 
 ## Connect a project
 
@@ -56,9 +157,9 @@ Create `.mcp.json` in your project root:
 ```json
 {
   "mcpServers": {
-    "supervisor": {
+    "routing": {
       "type": "http",
-      "url": "http://koala:30320/mcp"
+      "url": "http://koala:30310/mcp"
     },
     "brain": {
       "type": "http",
@@ -68,33 +169,29 @@ Create `.mcp.json` in your project root:
 }
 ```
 
-Two MCP servers are exposed today, both reachable over Tailscale:
+Two MCP servers are exposed, both reachable over Tailscale:
 
-- **`supervisor`** at `koala:30320` — skill workers (`tdd_red/green/refactor`,
-  `review`, `debug`, `spec`, `retrospective`, `trainer`, `tier`).
+- **`routing`** at `koala:30310` — skill workers (`review`, `debug`, `retrospective`, `trainer`).
+  Routes each call to fast local model or thinking model based on per-skill pass rate.
 - **`brain`** at `koala:30330` — knowledge access (`brain_query`, `brain_write`,
-  `brain_ingest`, `brain_ingest_raw`) and `session_log`. Hosted by the ingestion
-  service directly, no separate pod.
+  `brain_ingest`, `brain_ingest_raw`, `brain_answer`, `brain_classify`) and `session_log`.
 
 No local binary or stdio shim is required — Claude Code talks to both via HTTP.
 
 Open Claude Code in your project — run `/mcp` to confirm both servers are listed.
 
-## A typical TDD session
+## A typical session
 
 ```
-1. Call tdd_red    → spec in, failing test file out
-2. Call tdd_green  → test path in, implementation out
-3. Call tdd_refactor → impl + test in, cleaned code out
-4. Call session_log  → log each phase result
-5. Call retrospective → extracts learnings → brain/raw/
-6. Review brain/raw/, move worthy notes to brain/wiki/concepts/
-7. Future sessions: call brain_query to retrieve relevant context
+1. Call review      → brain context injected + local model review → findings
+2. Call session_log → log each phase result
+3. Call retrospective → extracts learnings → brain
+4. Future sessions: call brain_query / brain_answer to retrieve relevant context
 ```
 
 ## Tier detection
 
-The supervisor probes connectivity at call time:
+The routing pod probes connectivity at call time:
 
 | Tier | Label | Condition |
 |------|-------|-----------| 
@@ -102,31 +199,47 @@ The supervisor probes connectivity at call time:
 | 2 | lan-only | Can reach LiteLLM but not Anthropic |
 | 3 | airplane | No external connectivity |
 
+## Model routing
+
+The routing pod selects models per skill call based on historical pass rate:
+
+| Pass rate | Decision |
+|-----------|----------|
+| ≥ 0.90 (FLOOR) | Fast model (`HYPERGUILD_FAST_MODEL`) |
+| ≤ 0.70 (CEIL) | Thinking model (`HYPERGUILD_THINKING_MODEL`) |
+| between CEIL and FLOOR | Sample band — probabilistic routing |
+| nil (no history yet) | Defaults to thinking model |
+
+> **Bootstrap note:** With no session history, all calls route to the thinking model.
+> The fast-model path activates only after real pass-rate data accumulates at `/pass-rate`.
+> Seed with real usage — don't try to pre-populate.
+
 ## Key env vars
 
 | Variable | Default | Purpose |
 |----------|---------|---------| 
 | `INGEST_BRAIN_DIR` | `../brain` | Brain directory for ingestion server |
 | `INGEST_PORT` | `3300` | Ingestion server port |
-| `SUPERVISOR_CONFIG_DIR` | `./config/supervisor` | Skill discipline files |
-| `SUPERVISOR_SESSIONS_DIR` | `./brain/sessions` | JSONL session logs |
-| `INGEST_BASE_URL` | `http://localhost:3300` | Supervisor → ingestion |
+| `INGEST_BASE_URL` | `http://localhost:3300` | Routing pod → brain |
 | `LITELLM_BASE_URL` | — | LiteLLM proxy for Tier 2 model routing |
-| `SUPERVISOR_MCP_TOKEN` | — | Optional bearer token for the supervisor MCP HTTP endpoint; when empty, no auth is enforced |
 | `ROUTING_PORT` | `3210` | Routing pod's listen port |
-| `ROUTING_MCP_TOKEN` | — | Optional bearer token for the routing MCP HTTP endpoint |
+| `ROUTING_MCP_TOKEN` | — | Optional bearer token; when empty, no auth enforced |
 | `BRAIN_URL` | `http://ingestion.supervisor:3300` | Routing pod → brain (in-cluster) |
 | `HYPERGUILD_FAST_MODEL` | `koala/qwen35-9b-fast` | Fast model for high-pass-rate skill calls |
 | `HYPERGUILD_THINKING_MODEL` | `iguana/gemma4-26b` | Thinking model for low-pass-rate skill calls |
-| `HYPERGUILD_ROUTE_LOCAL_FLOOR` | `0.90` | At/above pass rate, route to fast model |
-| `HYPERGUILD_ROUTE_LOCAL_CEIL` | `0.70` | Below pass rate, route to thinking model. Between CEIL and FLOOR is the sample band. |
+| `HYPERGUILD_ROUTE_LOCAL_FLOOR` | `0.90` | Fast model threshold |
+| `HYPERGUILD_ROUTE_LOCAL_CEIL` | `0.70` | Thinking model threshold |
 | `HYPERGUILD_PASS_RATE_TTL_SECONDS` | `60` | Per-skill pass-rate cache TTL |
 
-> **Operator note:** LiteLLM at `LITELLM_BASE_URL` must register both `HYPERGUILD_FAST_MODEL` and `HYPERGUILD_THINKING_MODEL` for routing to do useful work. If a model is missing, LiteLLM returns 4xx, the routing pod's fast route fails, the fail-open retry on the thinking model likely also fails (since both are missing), and the only signal is `final_status: "fail"` on `_routing` entries in the brain.
+> **Operator note:** LiteLLM at `LITELLM_BASE_URL` must register both `HYPERGUILD_FAST_MODEL`
+> and `HYPERGUILD_THINKING_MODEL`. If a model is missing, the fail-open retry also fails and
+> the only signal is `final_status: "fail"` on `_routing` entries in the brain.
 
-## Phase 2 (planned)
+## Open issues
 
-- `review` skill — structured code review with iron law enforcement
-- `debug` skill — hypothesis-driven debugging sessions
-- `spec` skill — generates specs from conversations
-- `trainer` — extracts SFT/DPO pairs from session logs for fine-tuning
+See [issues](https://git.d-ma.be/mathias/hyperguild/issues) — key open items:
+
+- **#25** — skills platform overhaul (audit first, then lazy loading + brain feedback loop)
+- **#24** — reduce context burn from skill listing
+- **#22** — migrate legacy brain notes to wing/hall layout (one-shot script, low risk)
+- **#31** — connect routing-mcp to claude.ai as custom connector

Taskfile.yml

@@ -17,13 +17,11 @@ tasks:
     cmds: [bash scripts/context-sync.sh claude]
   context:sync:agents:
     cmds: [bash scripts/context-sync.sh agents]
-  context:sync:cursor:
-    cmds: [bash scripts/context-sync.sh cursor]
 
   # ── Development ────────────────────────────────────────────────────────────
 
   start:
-    desc: Start ingestion + supervisor (requires goreman — go install github.com/mattn/goreman@latest)
+    desc: Start ingestion (requires goreman — go install github.com/mattn/goreman@latest)
     cmds:
       - goreman start
 
@@ -34,11 +32,6 @@ tasks:
       - lsof -ti:3200 | xargs kill -9 2>/dev/null || true
       - echo "hyperguild stopped"
 
-  supervisor:dev:
-    desc: Run supervisor MCP server (development)
-    cmds:
-      - go run ./cmd/supervisor
-
   hyperguild:dev:
     desc: Run hyperguild CLI from source (e.g. task hyperguild:dev -- tier)
     cmds:
@@ -69,14 +62,9 @@ tasks:
   build:
     desc: Build all binaries
     cmds:
-      - task: supervisor:build
+      - task: hyperguild:build
       - task: ingestion:build
 
-  supervisor:build:
-    desc: Build supervisor binary
-    cmds:
-      - go build -trimpath -ldflags="-s -w -X main.version={{.VERSION}}" -o bin/supervisor ./cmd/supervisor
-
   ingestion:build:
     desc: Build ingestion server binary
     dir: ingestion
@@ -86,29 +74,90 @@ tasks:
   # ── Quality ────────────────────────────────────────────────────────────────
 
   check:
-    desc: Run all checks (context freshness + lint + test + vet) across all modules
+    desc: Run all checks (context freshness + lint + test + vet + build) across all modules
     cmds:
-      - task: context:sync
+      # Context sync is skipped under CI, matching dma-cli, gitea-mcp, and the
+      # rest of the estate. It is not a preference: context-sync.sh walks UP
+      # the tree for the canonical .context/AGENT.md, which lives in local-dev
+      # and does not exist on a CI runner. Without this guard, the script
+      # silently falls back to "project context only" and regenerates AGENTS.md
+      # and .context/system-prompt.txt shorter than their committed, correct
+      # versions -- so the drift assertion fails every CI run for a purely
+      # environmental reason, not real drift. Verified, not assumed: this is
+      # exactly what was happening here (AGENTS.md 430 lines committed vs. an
+      # 82-line regeneration on the runner).
+      #
+      # The cost is real and worth stating: drift is therefore only ever caught
+      # on a developer machine, or by infra's estate-wide context-sync-drift
+      # CronJob (ADR-0019), which does have canonical access and is the actual
+      # enforcement mechanism now.
       - cmd: |
-          drift=$(git status --porcelain -- AGENTS.md CLAUDE.md .cursorrules .aider.conventions.md .context/system-prompt.txt 2>/dev/null)
+          if [ -n "${CI:-}" ]; then
+            echo "✓ context sync: skipped in CI (no canonical AGENT.md on the runner)"
+          else
+            bash scripts/context-sync.sh
+            drift=$(git status --porcelain -- AGENTS.md CLAUDE.md .context/system-prompt.txt 2>/dev/null)
             if [ -n "$drift" ]; then
               echo "ERROR: derived adapters drifted from canonical context." >&2
               echo "$drift" >&2
               echo "" >&2
-            echo "Run: git add AGENTS.md CLAUDE.md .cursorrules .aider.conventions.md .context/system-prompt.txt" >&2
+              echo "Run: git add AGENTS.md CLAUDE.md .context/system-prompt.txt" >&2
               echo "     git commit -m 'chore: re-sync context adapters'" >&2
               exit 1
             fi
             echo "✓ context: canonical and adapters are in sync"
+          fi
       - task: lint
       - task: test
       - task: vet
+      # `build` is in the gate deliberately (hyperguild#120). vet and test walk
+      # ./... , which enumerates the packages that EXIST — so a build target
+      # naming a DELETED package is invisible to both. `task build` pointed at
+      # ./cmd/supervisor for months after that directory was removed, and CI
+      # stayed green the whole time because nothing in check ever built.
+      - task: build
+      - task: security:gitleaks
+
+  # ── Security ─────────────────────────────────────────────
+  security:gitleaks:
+    desc: Scan the working tree for secrets (gitleaks, fail-closed; skipped if gitleaks absent)
+    dir: '{{.ROOT_DIR}}'
+    cmds:
+      - |
+        GL="$(command -v gitleaks || true)"
+        [ -z "$GL" ] && [ -x "$(go env GOPATH 2>/dev/null)/bin/gitleaks" ] && GL="$(go env GOPATH)/bin/gitleaks"
+        if [ -z "$GL" ]; then
+          echo "⚠ gitleaks not installed — skipping secret scan (CI enforces it)."
+          echo "  Install: go install github.com/zricethezav/gitleaks/v8@latest"
+          exit 0
+        fi
+        "$GL" detect --no-git --redact --config .gitleaks.toml --source .
+
+  security:gitleaks:history:
+    desc: "One-time FULL-HISTORY secret audit (infra#39 rotation pass; not a per-push gate)"
+    dir: '{{.ROOT_DIR}}'
+    cmds:
+      - |
+        GL="$(command -v gitleaks || true)"
+        [ -z "$GL" ] && [ -x "$(go env GOPATH 2>/dev/null)/bin/gitleaks" ] && GL="$(go env GOPATH)/bin/gitleaks"
+        if [ -z "$GL" ]; then
+          echo "gitleaks not installed: go install github.com/zricethezav/gitleaks/v8@latest" >&2
+          exit 2
+        fi
+        echo "Scanning FULL git history (redacted). Known historical leaks are expected"
+        echo "until the infra#39 rotation pass completes — triage against the rotation list."
+        "$GL" detect --redact --config .gitleaks.toml
 
   lint:
     cmds:
       - golangci-lint run ./...
       - cd ingestion && golangci-lint run ./...
 
+  lint:frontmatter:
+    desc: Report brain notes whose YAML frontmatter does not parse (BRAIN=path, FIX=1 repairs in place)
+    cmds:
+      - cd ingestion && go run ./cmd/frontmatterlint {{if .FIX}}-fix{{end}} {{.BRAIN | default "../../brain"}}
+
   test:
     cmds:
       - go test -race -count=1 ./...
@@ -120,19 +169,6 @@ tasks:
       - govulncheck ./... || true
       - cd ingestion && go vet ./...
 
-  supervisor:test:smoke:
-    desc: Smoke test supervisor via MCP (requires start running)
-    cmds:
-      - |
-        curl -s -X POST http://localhost:${SUPERVISOR_PORT:-3200}/mcp \
-          -H "Content-Type: application/json" \
-          -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .
-
-  smoke:routing:
-    desc: Boot the routing pod against live LiteLLM + brain and verify _routing logs land
-    cmds:
-      - bash scripts/smoke-routing.sh
-
   # ── Git / Release ──────────────────────────────────────────────────────────
 
   tag:

brain/eval/baseline-pre-fix.txt

@@ -0,0 +1,167 @@
+# baseline-pre-fix — 20 questions, k=5
+
+top-1 hit rate: 4/20 = 20%
+top-3 hit rate: 13/20 = 65%
+
+## per-question detail
+
+· rank=3  expected=dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     q: how do I stop dex from logging users out on every pod restart?
+     1. homelab-network-perimeter-model
+     2. 2026-05-12-koala-machine-state
+     3. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart  <-- expected
+     4. infra-litellm-absorption-2026-05-16
+     5. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+
+★ rank=1  expected=postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+     q: my postgres-exporter broke after revoking PUBLIC CONNECT — why?
+     1. postgres-least-privilege-migration-tenant-grant-bypass-2026-05  <-- expected
+     2. infra-litellm-absorption-2026-05-16
+     3. brain-mcp-activation-runbook
+     4. extension-version-lags-platform-major-upgrade
+     5. ntfy-deny-all-rollout-ordering-keep-alert-pipeline-live-during-auth-flip
+
+★ rank=1  expected=homelab-network-perimeter-model
+     q: when is a NodePort acceptable vs needing a public ingress with bearer gate?
+     1. homelab-network-perimeter-model  <-- expected
+     2. qwen3-thinking-model-empty-content-trap
+     3. mcpclient-empty-token-silent-401-envfrom-missing-key
+     4. 2026-05-12-koala-machine-state
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=3  expected=exit-255-unknown-reason-not-oom
+     q: what does container exit code 255 with reason Unknown mean?
+     1. qwen3-thinking-model-empty-content-trap
+     2. infra-litellm-absorption-2026-05-16
+     3. exit-255-unknown-reason-not-oom  <-- expected
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=3  expected=gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     q: can gitea push-mirror create the github repo automatically?
+     1. infra-litellm-absorption-2026-05-16
+     2. Autoresearch
+     3. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo  <-- expected
+     4. adr-new-project-gitea-first-github-mirror
+     5. adr-github-as-primary-remote
+
+✗ rank=0  expected=flux-healthcheck-stale-on-resource-removal
+     q: a flux kustomization is stuck after I removed a resource — why?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-12-koala-machine-state
+     3. homelab-architecture-principles-2026-05
+     4. gitea-mcp: full stack shipped end-to-end (2026-05-05)
+     5. k8s-configmap-mount-no-reload-needs-pod-restart
+
+· rank=2  expected=go-bytes-buffer-bytes-reset-aliasing-trap
+     q: the bytes buffer aliasing trap with Reset in a loop — what's the bug?
+     1. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     2. go-bytes-buffer-bytes-reset-aliasing-trap  <-- expected
+     3. homelab-security-chains-not-bugs
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. Hash Encoding
+
+★ rank=1  expected=homelab-architecture-principles-2026-05
+     q: what are the homelab architecture principles from may 2026?
+     1. homelab-architecture-principles-2026-05  <-- expected
+     2. homelab-network-perimeter-model
+     3. Claude Managed Agents — architecture notes relevant to homelab agent platform
+     4. homelab-core-glossary
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=2026-05-04-sops-age-key-from-flux-cluster
+     q: where does the sops age private key live in the cluster?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-network-perimeter-model
+     3. postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+     4. brain-mcp-activation-runbook
+     5. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+
+✗ rank=0  expected=grafana-dashboards-as-code-not-ui-state
+     q: why do my grafana dashboards disappear after a pod restart?
+     1. infra-litellm-absorption-2026-05-16
+     2. 2026-05-12-koala-machine-state
+     3. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     4. brain-mcp-activation-runbook
+     5. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+
+· rank=2  expected=double-diamond-methodology
+     q: what is the double diamond methodology?
+     1. Harnessing the Power of Hash Encoding for Categorical Data in Data Science
+     2. double-diamond-methodology  <-- expected
+     3. unified-methodology-diamond-futures-autoresearch
+     4. futures-thinking-extended-double-diamond
+     5. insight-exploration-as-diamond-1
+
+· rank=3  expected=2026-05-04-mcp-transport-version-claude-ai-strict
+     q: my MCP server works from claude code but fails on claude.ai — what's different?
+     1. qwen3-thinking-model-empty-content-trap
+     2. mcp-resource-url-empty-breaks-claude-ai-discovery-silently
+     3. 2026-05-04-mcp-transport-version-claude-ai-strict  <-- expected
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. finding-github-mcp-claudeai-vs-claudecode
+
+· rank=2  expected=homelab-security-chains-not-bugs
+     q: how should I rate security findings — isolated bugs or exploit chains?
+     1. homelab-network-perimeter-model
+     2. homelab-security-chains-not-bugs  <-- expected
+     3. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     4. policy-audit-mode-blocks-nothing
+     5. homelab-document-accepted-risk-to-break-audit-cycle
+
+· rank=2  expected=2026-05-03-canonical-vs-derived-context-flow
+     q: how should canonical context files relate to derived adapter files?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-03-canonical-vs-derived-context-flow  <-- expected
+     3. 2026-05-12-koala-machine-state
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=2  expected=homelab-core-glossary
+     q: what is the homelab core vocabulary glossary?
+     1. homelab-architecture-principles-2026-05
+     2. homelab-core-glossary  <-- expected
+     3. Claude Managed Agents — architecture notes relevant to homelab agent platform
+     4. 2026-05-12-koala-machine-state
+     5. Autoresearch
+
+★ rank=1  expected=koala-llama-swap-native-tool-calls-survey-2026-05
+     q: which models on koala llama-swap actually emit native tool_calls correctly?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05  <-- expected
+     2. 2026-05-12-koala-machine-state
+     3. infra-litellm-absorption-2026-05-16
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. qwen3-thinking-model-empty-content-trap
+
+✗ rank=0  expected=qwen35-9b-fast
+     q: what is qwen35-9b-fast and what's it used for?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05
+     2. qwen3-thinking-model-empty-content-trap
+     3. Qwen35-9b-fast
+     4. infra-litellm-absorption-2026-05-16
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=go-defer-errcheck-body-close
+     q: in go, how do I prevent defer body close from silently dropping errors?
+     1. infra-litellm-absorption-2026-05-16
+     2. homelab-network-perimeter-model
+     3. go-bytes-buffer-bytes-reset-aliasing-trap
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. brain-mcp-activation-runbook
+
+✗ rank=0  expected=hyperguild-level3-pipeline-rewrite
+     q: what was the level 3 rewrite of hyperguild's ingestion pipeline?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-core-glossary
+     3. brain-mcp-activation-runbook
+     4. koala-llama-swap-native-tool-calls-survey-2026-05
+     5. infra-litellm-absorption-2026-05-16
+
+? rank=4  expected=adr-new-project-gitea-first-github-mirror
+     q: what's the new-project ADR — is it gitea-first or github-first?
+     1. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     2. gitea-mcp: full stack shipped end-to-end (2026-05-05)
+     3. mcp-tool-design-get-needs-list-partner
+     4. adr-new-project-gitea-first-github-mirror  <-- expected
+     5. 2026-05-04-gitea-mcp-build-session
+

brain/eval/post-fix.txt

@@ -0,0 +1,167 @@
+# post-fix — 20 questions, k=5
+
+top-1 hit rate: 4/20 = 20%
+top-3 hit rate: 14/20 = 70%
+
+## per-question detail
+
+· rank=3  expected=dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     q: how do I stop dex from logging users out on every pod restart?
+     1. homelab-network-perimeter-model
+     2. 2026-05-12-koala-machine-state
+     3. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart  <-- expected
+     4. infra-litellm-absorption-2026-05-16
+     5. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+
+★ rank=1  expected=postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+     q: my postgres-exporter broke after revoking PUBLIC CONNECT — why?
+     1. postgres-least-privilege-migration-tenant-grant-bypass-2026-05  <-- expected
+     2. infra-litellm-absorption-2026-05-16
+     3. brain-mcp-activation-runbook
+     4. extension-version-lags-platform-major-upgrade
+     5. ntfy-deny-all-rollout-ordering-keep-alert-pipeline-live-during-auth-flip
+
+★ rank=1  expected=homelab-network-perimeter-model
+     q: when is a NodePort acceptable vs needing a public ingress with bearer gate?
+     1. homelab-network-perimeter-model  <-- expected
+     2. qwen3-thinking-model-empty-content-trap
+     3. mcpclient-empty-token-silent-401-envfrom-missing-key
+     4. 2026-05-12-koala-machine-state
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=3  expected=exit-255-unknown-reason-not-oom
+     q: what does container exit code 255 with reason Unknown mean?
+     1. qwen3-thinking-model-empty-content-trap
+     2. infra-litellm-absorption-2026-05-16
+     3. exit-255-unknown-reason-not-oom  <-- expected
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=3  expected=gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     q: can gitea push-mirror create the github repo automatically?
+     1. infra-litellm-absorption-2026-05-16
+     2. Autoresearch
+     3. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo  <-- expected
+     4. adr-new-project-gitea-first-github-mirror
+     5. adr-github-as-primary-remote
+
+✗ rank=0  expected=flux-healthcheck-stale-on-resource-removal
+     q: a flux kustomization is stuck after I removed a resource — why?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-12-koala-machine-state
+     3. homelab-architecture-principles-2026-05
+     4. gitea-mcp: full stack shipped end-to-end (2026-05-05)
+     5. k8s-configmap-mount-no-reload-needs-pod-restart
+
+· rank=2  expected=go-bytes-buffer-bytes-reset-aliasing-trap
+     q: the bytes buffer aliasing trap with Reset in a loop — what's the bug?
+     1. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     2. go-bytes-buffer-bytes-reset-aliasing-trap  <-- expected
+     3. homelab-security-chains-not-bugs
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. Hash Encoding
+
+★ rank=1  expected=homelab-architecture-principles-2026-05
+     q: what are the homelab architecture principles from may 2026?
+     1. homelab-architecture-principles-2026-05  <-- expected
+     2. homelab-network-perimeter-model
+     3. Claude Managed Agents — architecture notes relevant to homelab agent platform
+     4. homelab-core-glossary
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=2026-05-04-sops-age-key-from-flux-cluster
+     q: where does the sops age private key live in the cluster?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-network-perimeter-model
+     3. postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+     4. brain-mcp-activation-runbook
+     5. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+
+✗ rank=0  expected=grafana-dashboards-as-code-not-ui-state
+     q: why do my grafana dashboards disappear after a pod restart?
+     1. infra-litellm-absorption-2026-05-16
+     2. 2026-05-12-koala-machine-state
+     3. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     4. brain-mcp-activation-runbook
+     5. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+
+· rank=2  expected=double-diamond-methodology
+     q: what is the double diamond methodology?
+     1. Harnessing the Power of Hash Encoding for Categorical Data in Data Science
+     2. double-diamond-methodology  <-- expected
+     3. unified-methodology-diamond-futures-autoresearch
+     4. futures-thinking-extended-double-diamond
+     5. insight-exploration-as-diamond-1
+
+· rank=3  expected=2026-05-04-mcp-transport-version-claude-ai-strict
+     q: my MCP server works from claude code but fails on claude.ai — what's different?
+     1. qwen3-thinking-model-empty-content-trap
+     2. mcp-resource-url-empty-breaks-claude-ai-discovery-silently
+     3. 2026-05-04-mcp-transport-version-claude-ai-strict  <-- expected
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. finding-github-mcp-claudeai-vs-claudecode
+
+· rank=2  expected=homelab-security-chains-not-bugs
+     q: how should I rate security findings — isolated bugs or exploit chains?
+     1. homelab-network-perimeter-model
+     2. homelab-security-chains-not-bugs  <-- expected
+     3. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     4. policy-audit-mode-blocks-nothing
+     5. homelab-document-accepted-risk-to-break-audit-cycle
+
+· rank=2  expected=2026-05-03-canonical-vs-derived-context-flow
+     q: how should canonical context files relate to derived adapter files?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-03-canonical-vs-derived-context-flow  <-- expected
+     3. 2026-05-12-koala-machine-state
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=2  expected=homelab-core-glossary
+     q: what is the homelab core vocabulary glossary?
+     1. homelab-architecture-principles-2026-05
+     2. homelab-core-glossary  <-- expected
+     3. Claude Managed Agents — architecture notes relevant to homelab agent platform
+     4. 2026-05-12-koala-machine-state
+     5. Autoresearch
+
+★ rank=1  expected=koala-llama-swap-native-tool-calls-survey-2026-05
+     q: which models on koala llama-swap actually emit native tool_calls correctly?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05  <-- expected
+     2. 2026-05-12-koala-machine-state
+     3. infra-litellm-absorption-2026-05-16
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. qwen3-thinking-model-empty-content-trap
+
+· rank=2  expected=qwen35-9b-fast
+     q: what is qwen35-9b-fast and what's it used for?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05
+     2. qwen35-9b-fast  <-- expected
+     3. qwen3-thinking-model-empty-content-trap
+     4. infra-litellm-absorption-2026-05-16
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=go-defer-errcheck-body-close
+     q: in go, how do I prevent defer body close from silently dropping errors?
+     1. infra-litellm-absorption-2026-05-16
+     2. homelab-network-perimeter-model
+     3. go-bytes-buffer-bytes-reset-aliasing-trap
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. brain-mcp-activation-runbook
+
+✗ rank=0  expected=hyperguild-level3-pipeline-rewrite
+     q: what was the level 3 rewrite of hyperguild's ingestion pipeline?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-core-glossary
+     3. brain-mcp-activation-runbook
+     4. koala-llama-swap-native-tool-calls-survey-2026-05
+     5. infra-litellm-absorption-2026-05-16
+
+? rank=4  expected=adr-new-project-gitea-first-github-mirror
+     q: what's the new-project ADR — is it gitea-first or github-first?
+     1. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     2. gitea-mcp: full stack shipped end-to-end (2026-05-05)
+     3. mcp-tool-design-get-needs-list-partner
+     4. adr-new-project-gitea-first-github-mirror  <-- expected
+     5. 2026-05-04-gitea-mcp-build-session
+

brain/eval/post-m4.txt

@@ -0,0 +1,167 @@
+# post-m4-tier-weighting — 20 questions, k=5
+
+top-1 hit rate: 6/20 = 30%
+top-3 hit rate: 15/20 = 75%
+
+## per-question detail
+
+· rank=3  expected=dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     q: how do I stop dex from logging users out on every pod restart?
+     1. homelab-network-perimeter-model
+     2. 2026-05-12-koala-machine-state
+     3. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart  <-- expected
+     4. infra-litellm-absorption-2026-05-16
+     5. k8s-configmap-mount-no-reload-needs-pod-restart
+
+· rank=2  expected=postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+     q: my postgres-exporter broke after revoking PUBLIC CONNECT — why?
+     1. infra-litellm-absorption-2026-05-16
+     2. postgres-least-privilege-migration-tenant-grant-bypass-2026-05  <-- expected
+     3. extension-version-lags-platform-major-upgrade
+     4. ntfy-deny-all-rollout-ordering-keep-alert-pipeline-live-during-auth-flip
+     5. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+
+★ rank=1  expected=homelab-network-perimeter-model
+     q: when is a NodePort acceptable vs needing a public ingress with bearer gate?
+     1. homelab-network-perimeter-model  <-- expected
+     2. qwen3-thinking-model-empty-content-trap
+     3. mcpclient-empty-token-silent-401-envfrom-missing-key
+     4. 2026-05-12-koala-machine-state
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=3  expected=exit-255-unknown-reason-not-oom
+     q: what does container exit code 255 with reason Unknown mean?
+     1. qwen3-thinking-model-empty-content-trap
+     2. infra-litellm-absorption-2026-05-16
+     3. exit-255-unknown-reason-not-oom  <-- expected
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=2  expected=gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     q: can gitea push-mirror create the github repo automatically?
+     1. infra-litellm-absorption-2026-05-16
+     2. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo  <-- expected
+     3. adr-new-project-gitea-first-github-mirror
+     4. adr-github-as-primary-remote
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=flux-healthcheck-stale-on-resource-removal
+     q: a flux kustomization is stuck after I removed a resource — why?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-12-koala-machine-state
+     3. homelab-architecture-principles-2026-05
+     4. k8s-configmap-mount-no-reload-needs-pod-restart
+     5. training-on-rtx-5070-pretraining-vs-finetuning
+
+★ rank=1  expected=go-bytes-buffer-bytes-reset-aliasing-trap
+     q: the bytes buffer aliasing trap with Reset in a loop — what's the bug?
+     1. go-bytes-buffer-bytes-reset-aliasing-trap  <-- expected
+     2. homelab-security-chains-not-bugs
+     3. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. flux-healthcheck-stale-on-resource-removal
+
+★ rank=1  expected=homelab-architecture-principles-2026-05
+     q: what are the homelab architecture principles from may 2026?
+     1. homelab-architecture-principles-2026-05  <-- expected
+     2. homelab-network-perimeter-model
+     3. homelab-core-glossary
+     4. 2026-05-12-koala-machine-state
+     5. pattern-reddit-tmux-multiagent-conductor
+
+? rank=4  expected=2026-05-04-sops-age-key-from-flux-cluster
+     q: where does the sops age private key live in the cluster?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-network-perimeter-model
+     3. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     4. 2026-05-04-sops-age-key-from-flux-cluster  <-- expected
+     5. homelab-security-chains-not-bugs
+
+★ rank=1  expected=grafana-dashboards-as-code-not-ui-state
+     q: why do my grafana dashboards disappear after a pod restart?
+     1. grafana-dashboards-as-code-not-ui-state  <-- expected
+     2. infra-litellm-absorption-2026-05-16
+     3. 2026-05-12-koala-machine-state
+     4. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     5. k8s-configmap-mount-no-reload-needs-pod-restart
+
+★ rank=1  expected=double-diamond-methodology
+     q: what is the double diamond methodology?
+     1. double-diamond-methodology  <-- expected
+     2. unified-methodology-diamond-futures-autoresearch
+     3. futures-thinking-extended-double-diamond
+     4. insight-exploration-as-diamond-1
+     5. workflow-idea-to-running-service
+
+· rank=3  expected=2026-05-04-mcp-transport-version-claude-ai-strict
+     q: my MCP server works from claude code but fails on claude.ai — what's different?
+     1. qwen3-thinking-model-empty-content-trap
+     2. mcp-resource-url-empty-breaks-claude-ai-discovery-silently
+     3. 2026-05-04-mcp-transport-version-claude-ai-strict  <-- expected
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. finding-github-mcp-claudeai-vs-claudecode
+
+· rank=2  expected=homelab-security-chains-not-bugs
+     q: how should I rate security findings — isolated bugs or exploit chains?
+     1. homelab-network-perimeter-model
+     2. homelab-security-chains-not-bugs  <-- expected
+     3. policy-audit-mode-blocks-nothing
+     4. homelab-document-accepted-risk-to-break-audit-cycle
+     5. audit-shortcut-tls-blocks-zero-equals-edge-only
+
+· rank=2  expected=2026-05-03-canonical-vs-derived-context-flow
+     q: how should canonical context files relate to derived adapter files?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-03-canonical-vs-derived-context-flow  <-- expected
+     3. 2026-05-12-koala-machine-state
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=2  expected=homelab-core-glossary
+     q: what is the homelab core vocabulary glossary?
+     1. homelab-architecture-principles-2026-05
+     2. homelab-core-glossary  <-- expected
+     3. 2026-05-12-koala-machine-state
+     4. flux-kustomization-depends-on-bootstrap-ordering
+     5. brain-ingest-ntfy-service
+
+★ rank=1  expected=koala-llama-swap-native-tool-calls-survey-2026-05
+     q: which models on koala llama-swap actually emit native tool_calls correctly?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05  <-- expected
+     2. 2026-05-12-koala-machine-state
+     3. infra-litellm-absorption-2026-05-16
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. qwen3-thinking-model-empty-content-trap
+
+✗ rank=0  expected=qwen35-9b-fast
+     q: what is qwen35-9b-fast and what's it used for?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05
+     2. qwen3-thinking-model-empty-content-trap
+     3. infra-litellm-absorption-2026-05-16
+     4. 2026-05-12-koala-machine-state
+     5. index
+
+✗ rank=0  expected=go-defer-errcheck-body-close
+     q: in go, how do I prevent defer body close from silently dropping errors?
+     1. homelab-network-perimeter-model
+     2. infra-litellm-absorption-2026-05-16
+     3. go-bytes-buffer-bytes-reset-aliasing-trap
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+✗ rank=0  expected=hyperguild-level3-pipeline-rewrite
+     q: what was the level 3 rewrite of hyperguild's ingestion pipeline?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-core-glossary
+     3. koala-llama-swap-native-tool-calls-survey-2026-05
+     4. infra-litellm-absorption-2026-05-16
+     5. homelab-architecture-principles-2026-05
+
+· rank=3  expected=adr-new-project-gitea-first-github-mirror
+     q: what's the new-project ADR — is it gitea-first or github-first?
+     1. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     2. mcp-tool-design-get-needs-list-partner
+     3. adr-new-project-gitea-first-github-mirror  <-- expected
+     4. 2026-05-04-gitea-mcp-build-session
+     5. adr-local-dev-vs-hyperguild-new-project
+

brain/eval/post-m4b.txt

@@ -0,0 +1,167 @@
+# post-m4b-entities-promoted — 20 questions, k=5
+
+top-1 hit rate: 7/20 = 35%
+top-3 hit rate: 16/20 = 80%
+
+## per-question detail
+
+· rank=3  expected=dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     q: how do I stop dex from logging users out on every pod restart?
+     1. homelab-network-perimeter-model
+     2. 2026-05-12-koala-machine-state
+     3. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart  <-- expected
+     4. infra-litellm-absorption-2026-05-16
+     5. k8s-configmap-mount-no-reload-needs-pod-restart
+
+· rank=2  expected=postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+     q: my postgres-exporter broke after revoking PUBLIC CONNECT — why?
+     1. infra-litellm-absorption-2026-05-16
+     2. postgres-least-privilege-migration-tenant-grant-bypass-2026-05  <-- expected
+     3. extension-version-lags-platform-major-upgrade
+     4. ntfy-deny-all-rollout-ordering-keep-alert-pipeline-live-during-auth-flip
+     5. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+
+★ rank=1  expected=homelab-network-perimeter-model
+     q: when is a NodePort acceptable vs needing a public ingress with bearer gate?
+     1. homelab-network-perimeter-model  <-- expected
+     2. qwen3-thinking-model-empty-content-trap
+     3. mcpclient-empty-token-silent-401-envfrom-missing-key
+     4. 2026-05-12-koala-machine-state
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=3  expected=exit-255-unknown-reason-not-oom
+     q: what does container exit code 255 with reason Unknown mean?
+     1. qwen3-thinking-model-empty-content-trap
+     2. infra-litellm-absorption-2026-05-16
+     3. exit-255-unknown-reason-not-oom  <-- expected
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=2  expected=gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     q: can gitea push-mirror create the github repo automatically?
+     1. infra-litellm-absorption-2026-05-16
+     2. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo  <-- expected
+     3. adr-new-project-gitea-first-github-mirror
+     4. adr-github-as-primary-remote
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=flux-healthcheck-stale-on-resource-removal
+     q: a flux kustomization is stuck after I removed a resource — why?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-12-koala-machine-state
+     3. homelab-architecture-principles-2026-05
+     4. k8s-configmap-mount-no-reload-needs-pod-restart
+     5. training-on-rtx-5070-pretraining-vs-finetuning
+
+★ rank=1  expected=go-bytes-buffer-bytes-reset-aliasing-trap
+     q: the bytes buffer aliasing trap with Reset in a loop — what's the bug?
+     1. go-bytes-buffer-bytes-reset-aliasing-trap  <-- expected
+     2. homelab-security-chains-not-bugs
+     3. Financial Sentiment Analysis on Stock Market Headlines With FinBERT & HuggingFace
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. flux-healthcheck-stale-on-resource-removal
+
+★ rank=1  expected=homelab-architecture-principles-2026-05
+     q: what are the homelab architecture principles from may 2026?
+     1. homelab-architecture-principles-2026-05  <-- expected
+     2. homelab-network-perimeter-model
+     3. homelab-core-glossary
+     4. 2026-05-12-koala-machine-state
+     5. pattern-reddit-tmux-multiagent-conductor
+
+? rank=4  expected=2026-05-04-sops-age-key-from-flux-cluster
+     q: where does the sops age private key live in the cluster?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-network-perimeter-model
+     3. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     4. 2026-05-04-sops-age-key-from-flux-cluster  <-- expected
+     5. homelab-security-chains-not-bugs
+
+★ rank=1  expected=grafana-dashboards-as-code-not-ui-state
+     q: why do my grafana dashboards disappear after a pod restart?
+     1. grafana-dashboards-as-code-not-ui-state  <-- expected
+     2. infra-litellm-absorption-2026-05-16
+     3. 2026-05-12-koala-machine-state
+     4. dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+     5. k8s-configmap-mount-no-reload-needs-pod-restart
+
+★ rank=1  expected=double-diamond-methodology
+     q: what is the double diamond methodology?
+     1. double-diamond-methodology  <-- expected
+     2. unified-methodology-diamond-futures-autoresearch
+     3. futures-thinking-extended-double-diamond
+     4. insight-exploration-as-diamond-1
+     5. workflow-idea-to-running-service
+
+· rank=3  expected=2026-05-04-mcp-transport-version-claude-ai-strict
+     q: my MCP server works from claude code but fails on claude.ai — what's different?
+     1. qwen3-thinking-model-empty-content-trap
+     2. mcp-resource-url-empty-breaks-claude-ai-discovery-silently
+     3. 2026-05-04-mcp-transport-version-claude-ai-strict  <-- expected
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. finding-github-mcp-claudeai-vs-claudecode
+
+· rank=2  expected=homelab-security-chains-not-bugs
+     q: how should I rate security findings — isolated bugs or exploit chains?
+     1. homelab-network-perimeter-model
+     2. homelab-security-chains-not-bugs  <-- expected
+     3. policy-audit-mode-blocks-nothing
+     4. homelab-document-accepted-risk-to-break-audit-cycle
+     5. audit-shortcut-tls-blocks-zero-equals-edge-only
+
+· rank=2  expected=2026-05-03-canonical-vs-derived-context-flow
+     q: how should canonical context files relate to derived adapter files?
+     1. qwen3-thinking-model-empty-content-trap
+     2. 2026-05-03-canonical-vs-derived-context-flow  <-- expected
+     3. 2026-05-12-koala-machine-state
+     4. 2026-05-04-claude-ai-custom-mcp-connectors
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+· rank=2  expected=homelab-core-glossary
+     q: what is the homelab core vocabulary glossary?
+     1. homelab-architecture-principles-2026-05
+     2. homelab-core-glossary  <-- expected
+     3. 2026-05-12-koala-machine-state
+     4. qwen35-9b-fast
+     5. flux-kustomization-depends-on-bootstrap-ordering
+
+★ rank=1  expected=koala-llama-swap-native-tool-calls-survey-2026-05
+     q: which models on koala llama-swap actually emit native tool_calls correctly?
+     1. koala-llama-swap-native-tool-calls-survey-2026-05  <-- expected
+     2. 2026-05-12-koala-machine-state
+     3. infra-litellm-absorption-2026-05-16
+     4. training-on-rtx-5070-pretraining-vs-finetuning
+     5. qwen3-thinking-model-empty-content-trap
+
+★ rank=1  expected=qwen35-9b-fast
+     q: what is qwen35-9b-fast and what's it used for?
+     1. qwen35-9b-fast  <-- expected
+     2. koala-llama-swap-native-tool-calls-survey-2026-05
+     3. qwen3-thinking-model-empty-content-trap
+     4. infra-litellm-absorption-2026-05-16
+     5. 2026-05-12-koala-machine-state
+
+✗ rank=0  expected=go-defer-errcheck-body-close
+     q: in go, how do I prevent defer body close from silently dropping errors?
+     1. homelab-network-perimeter-model
+     2. infra-litellm-absorption-2026-05-16
+     3. go-bytes-buffer-bytes-reset-aliasing-trap
+     4. mcpclient-empty-token-silent-401-envfrom-missing-key
+     5. koala-llama-swap-native-tool-calls-survey-2026-05
+
+✗ rank=0  expected=hyperguild-level3-pipeline-rewrite
+     q: what was the level 3 rewrite of hyperguild's ingestion pipeline?
+     1. 2026-05-12-koala-machine-state
+     2. homelab-core-glossary
+     3. koala-llama-swap-native-tool-calls-survey-2026-05
+     4. infra-litellm-absorption-2026-05-16
+     5. homelab-architecture-principles-2026-05
+
+· rank=3  expected=adr-new-project-gitea-first-github-mirror
+     q: what's the new-project ADR — is it gitea-first or github-first?
+     1. gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+     2. mcp-tool-design-get-needs-list-partner
+     3. adr-new-project-gitea-first-github-mirror  <-- expected
+     4. 2026-05-04-gitea-mcp-build-session
+     5. adr-local-dev-vs-hyperguild-new-project
+

brain/eval/qa-2026-05.md

@@ -0,0 +1,76 @@
+# Brain retrieval eval set — 2026-05-24
+
+20 hand-authored Q→expected-top-1-slug pairs. Used by `score.sh` to
+measure brain_query top-1 + top-3 hit rate against the live brain.
+
+Authoring rules:
+- Each question maps to **one** clear-best entry. Avoid ambiguous
+  questions where multiple slugs could be the right answer.
+- Questions are phrased the way a future-me would actually ask, not
+  the way the entry's title reads. Some lexical distance is the point.
+- `expected` is the slug as stored in `brain_entities.slug`. Update
+  if the slug renames.
+
+## Pairs
+
+```
+q: how do I stop dex from logging users out on every pod restart?
+expected: dex-in-memory-storage-wipes-oauth-tokens-on-every-pod-restart
+
+q: my postgres-exporter broke after revoking PUBLIC CONNECT — why?
+expected: postgres-least-privilege-migration-tenant-grant-bypass-2026-05
+
+q: when is a NodePort acceptable vs needing a public ingress with bearer gate?
+expected: homelab-network-perimeter-model
+
+q: what does container exit code 255 with reason Unknown mean?
+expected: exit-255-unknown-reason-not-oom
+
+q: can gitea push-mirror create the github repo automatically?
+expected: gitea-push-mirror-cannot-create-remote-repo-needs-pre-existing-github-repo
+
+q: a flux kustomization is stuck after I removed a resource — why?
+expected: flux-healthcheck-stale-on-resource-removal
+
+q: the bytes buffer aliasing trap with Reset in a loop — what's the bug?
+expected: go-bytes-buffer-bytes-reset-aliasing-trap
+
+q: what are the homelab architecture principles from may 2026?
+expected: homelab-architecture-principles-2026-05
+
+q: where does the sops age private key live in the cluster?
+expected: 2026-05-04-sops-age-key-from-flux-cluster
+
+q: why do my grafana dashboards disappear after a pod restart?
+expected: grafana-dashboards-as-code-not-ui-state
+
+q: what is the double diamond methodology?
+expected: double-diamond-methodology
+
+q: my MCP server works from claude code but fails on claude.ai — what's different?
+expected: 2026-05-04-mcp-transport-version-claude-ai-strict
+
+q: how should I rate security findings — isolated bugs or exploit chains?
+expected: homelab-security-chains-not-bugs
+
+q: how should canonical context files relate to derived adapter files?
+expected: 2026-05-03-canonical-vs-derived-context-flow
+
+q: what is the homelab core vocabulary glossary?
+expected: homelab-core-glossary
+
+q: which models on koala llama-swap actually emit native tool_calls correctly?
+expected: koala-llama-swap-native-tool-calls-survey-2026-05
+
+q: what is qwen35-9b-fast and what's it used for?
+expected: qwen35-9b-fast
+
+q: in go, how do I prevent defer body close from silently dropping errors?
+expected: go-defer-errcheck-body-close
+
+q: what was the level 3 rewrite of hyperguild's ingestion pipeline?
+expected: hyperguild-level3-pipeline-rewrite
+
+q: what's the new-project ADR — is it gitea-first or github-first?
+expected: adr-new-project-gitea-first-github-mirror
+```

brain/eval/score.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Score brain_query against the qa-2026-05.md eval set.
+
+Reads `q:` / `expected:` pairs, calls brain_query MCP for each, records
+top-1 + top-3 hit rate. Run:
+
+    BRAIN_MCP_TOKEN=$(grep '^export BRAIN_MCP_TOKEN=' ~/.llmkeys | cut -d= -f2-) \\
+      python3 score.py qa-2026-05.md
+
+Optionally pass --baseline <name> to save the result as a labeled run.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+import time
+import urllib.request
+
+ENDPOINT = "https://brain-mcp.d-ma.be/mcp"
+
+
+def load_pairs(path):
+    pairs = []
+    q = None
+    with open(path) as f:
+        for line in f:
+            line = line.rstrip()
+            if line.startswith("q:"):
+                q = line[2:].strip()
+            elif line.startswith("expected:") and q is not None:
+                expected = line[len("expected:"):].strip()
+                pairs.append((q, expected))
+                q = None
+    return pairs
+
+
+def brain_query(token, query, k=5):
+    body = json.dumps({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": "brain_query", "arguments": {"query": query, "k": k}},
+    }).encode()
+    req = urllib.request.Request(
+        ENDPOINT,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as r:
+        raw = r.read().decode()
+    for line in raw.splitlines():
+        if line.startswith("data:"):
+            raw = line[5:].strip()
+            break
+    d = json.loads(raw)
+    if "error" in d:
+        raise RuntimeError(d["error"])
+    text = d["result"]["content"][0]["text"]
+    return json.loads(text).get("results", [])
+
+
+def slug_of(result):
+    # `title` mirrors the slug in brain_entities for normal entries.
+    # Fall back to basename(path) if title is missing.
+    t = result.get("title", "")
+    if t:
+        return t
+    p = result.get("path", "")
+    return re.sub(r"\.md$", "", os.path.basename(p))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("evalset")
+    ap.add_argument("--baseline", default="run")
+    ap.add_argument("--k", type=int, default=5)
+    args = ap.parse_args()
+
+    token = os.environ.get("BRAIN_MCP_TOKEN")
+    if not token:
+        sys.exit("BRAIN_MCP_TOKEN not set")
+
+    pairs = load_pairs(args.evalset)
+    if not pairs:
+        sys.exit(f"no pairs in {args.evalset}")
+
+    print(f"# {args.baseline} — {len(pairs)} questions, k={args.k}")
+    print()
+    hits1 = 0
+    hits3 = 0
+    detail = []
+    for q, expected in pairs:
+        try:
+            results = brain_query(token, q, k=args.k)
+        except Exception as e:
+            detail.append((q, expected, [], f"ERR {e}"))
+            continue
+        slugs = [slug_of(r) for r in results]
+        rank = slugs.index(expected) + 1 if expected in slugs else 0
+        h1 = 1 if rank == 1 else 0
+        h3 = 1 if 0 < rank <= 3 else 0
+        hits1 += h1
+        hits3 += h3
+        detail.append((q, expected, slugs, rank))
+
+    total = len(pairs)
+    print(f"top-1 hit rate: {hits1}/{total} = {100*hits1/total:.0f}%")
+    print(f"top-3 hit rate: {hits3}/{total} = {100*hits3/total:.0f}%")
+    print()
+    print("## per-question detail")
+    print()
+    for q, expected, slugs, rank in detail:
+        marker = {0: "✗", 1: "★", 2: "·", 3: "·"}.get(rank, "?")
+        if isinstance(rank, str):
+            marker = "!"
+        print(f"{marker} rank={rank}  expected={expected}")
+        print(f"     q: {q}")
+        for i, s in enumerate(slugs[:args.k], 1):
+            mark = "  <-- expected" if s == expected else ""
+            print(f"     {i}. {s}{mark}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

brain/sessions/analysis/agent-intent-column.jsonl

@@ -0,0 +1,48 @@
+{"_meta":true,"note":"Agent-consumer column of brain-MCP intent analysis. consumer_type fixed=autonomous_agent. CAVEAT: canonical schema file brain-intent-extraction.md is NOT present on this host (koala) — only this session's own task prompt references it. The closed intent vocabulary below was RECONSTRUCTED from the task prompt's framing + brain/schema.md. Re-map intent labels if the canonical vocab differs. schema_source=reconstructed on every row.","closed_intent_vocab":["semantic_retrieval","lexical_lookup","check_prior_art","synthesized_answer","store_new_knowledge","update_or_supersede","ingest_raw_source","verify_write_landed","discover_capability","intent_unclear"],"intent_tool_match_values":["match","mismatch","partial"],"corpus":"~/.claude/projects/*/*.jsonl (Claude Code agent transcripts on koala). brain/sessions/*.jsonl empty. agentsquad docs/eval/*.jsonl are code-review eval results, NOT brain calls. No separate Crush logs found. Zero brain calls appear under any mcp__ name with a human typing the call — all brain acts are agent-initiated (CLAUDE.md reflex), so all qualify as autonomous_agent."}
+{"id":"a01","session":"tapir-c","ts":"2026-06-?T15:01:51","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"single pre-task query 'YouTube Data API captions download ownership limitation timedtext adapter Go' — named-entity lexical lookup, fit BM25 well, no reformulation."}
+{"id":"a02","session":"tapir","ts":"2026-06-05T21:44:10","tool":"brain_ingest","intent":"ingest_raw_source","intent_tool_match":"match","workaround":null,"observed_friction":"preceded by ToolSearch select:brain_ingest 14s earlier — tool not ambient, had to be discovered/loaded first.","evidence":"source=tapir-scheduled-discovery-session-2026-06-05, a session learnings dump."}
+{"id":"a03","session":"tapir","ts":"2026-06-?T14:00:59","tool":"brain_ingest","intent":"ingest_raw_source","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"source=tapir-rls-identity-bootstrapping, first write of RLS lesson."}
+{"id":"a04","session":"tapir","ts":"2026-06-?T14:02:08","tool":"brain_ingest","intent":"update_or_supersede","intent_tool_match":"mismatch","workaround":"RE-INGESTED same source name 'tapir-rls-identity-bootstrapping' 69s later with edited/condensed body. No update/patch/supersede verb exists, so the agent overwrote-by-re-ingest. Whether this dedups or creates a v2 duplicate is opaque to the agent.","observed_friction":"agent revised content within 70s of first write — classic edit-after-write with no edit primitive.","evidence":"two brain_ingest, identical source string, divergent content."}
+{"id":"a05","session":"tapir","ts":"2026-06-?T14:56:27","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"postgres-cascade-skips-tables-without-fk.md — distinct new lesson."}
+{"id":"a06","session":"tapir","ts":"2026-06-?T21:08:57","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":"preceded by ToolSearch select:brain_query — discovery tax again.","evidence":"'Dex passwords.dex.coreos.com CRD ...' keyword-rich, single shot."}
+{"id":"a07","session":"AI-infra","ts":"2026-05-?T15:38:03","tool":"brain_query(HTTP-curl)","intent":"discover_capability","intent_tool_match":"mismatch","workaround":"raw `curl -X POST` to brain-mcp endpoint instead of MCP tool. Preceded by two ToolSearch ('brain knowledge memory' then 'brain') that did not yield a usable loaded tool, so agent fell back to HTTP.","observed_friction":"3-step ladder: ToolSearch 'brain knowledge memory' -> ToolSearch 'brain' -> curl. Agent did not know which act maps to which tool name.","evidence":"curl -s -o /tmp/brain-init.txt -w code:%{http_code} -X POST ..."}
+{"id":"a08","session":"AI-infra","ts":"2026-05-?T04:46:13","tool":"brain_query(HTTP-curl)","intent":"discover_capability","intent_tool_match":"mismatch","workaround":"hand-set TOKEN=... then curl brain-test endpoint — probing whether the HTTP brain path is reachable/authed at all. MCP path not used.","observed_friction":"agent testing connectivity by hand; MCP auth/availability not trusted.","evidence":"TOKEN=...; curl -s -o /tmp/brain-test ..."}
+{"id":"a09","session":"AI-infra","ts":"2026-05-?T05:23:35","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":"preceded by ToolSearch select:brain_query (after an earlier 05:03 ToolSearch 'brain ingestion knowledge wiki' that explored layers).","evidence":"'koala machine state RTX 5070 llama-swap' — named-entity recall, fits lexical."}
+{"id":"a10","session":"AI-infra","ts":"2026-05-?T05:27:36","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"batch of 3 in ~1s (k3s/flux gitops; llama-swap ai-stack GPU; MCP Dex OAuth claude.ai) — parallel prior-art sweep, all named-entity."}
+{"id":"a11","session":"AI-infra","ts":"2026-05-?T07:13:50","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"batch of 4 in ~2s before a debugging session (flux healthCheck; exit 255 restart loop; NVML mismatch; mirror rebase). Named symptoms, lexical fit OK on first pass."}
+{"id":"a12","session":"AI-infra","ts":"2026-05-?T07:14:26","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"4 writes in ~35s (flux-healthcheck-stale; exit-255-unknown-reason-not-oom; nvidia-nvml-mismatch; mcp-static-bearer) — answers to the 4 queries just run, captured as lessons. Healthy query->fix->write loop."}
+{"id":"a13","session":"AI-infra","ts":"2026-05-?T07:15:25","tool":"brain_query","intent":"verify_write_landed","intent_tool_match":"mismatch","workaround":"25s after writing exit-255-unknown-reason-not-oom.md, re-queried 'exit 255 unknown SIGKILL containerd' — reformulated terms (SIGKILL/containerd not in original query 'exit 255 unknown reason restart loop diagnosis'). Either confirming the fresh write is retrievable or re-searching because first lexical query missed. No read-after-write / get-by-id act exists.","observed_friction":"reformulation chain: 'exit 255 unknown reason restart loop diagnosis' -> 'exit 255 unknown SIGKILL containerd'. Same need, different keywords.","evidence":"query at 07:13:51 vs 07:15:25 bracketing the 07:14:37 write."}
+{"id":"a14","session":"AI-infra","ts":"2026-05-?T07:22:55","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"batch of 5 in ~20s before a homelab security audit (piguard/iguana tailscale; unifi UCG firewall; SOPS age; ingress TLS cert-manager; koala UFW iptables). Named-entity sweep."}
+{"id":"a15","session":"AI-infra","ts":"2026-05-?T09:27:53","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"audit-shortcut-tls-blocks-zero; policy-audit-mode-blocks-nothing — distinct new audit lessons."}
+{"id":"a16","session":"AI-infra","ts":"2026-05-?T09:28:22","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"homelab-security-chains-not-bugs.md FIRST write (worked example: koala 2026-05-13)."}
+{"id":"a17","session":"AI-infra","ts":"2026-05-?T10:32:49","tool":"brain_write","intent":"update_or_supersede","intent_tool_match":"mismatch","workaround":"RE-WROTE homelab-security-chains-not-bugs.md ~64min later with a different/expanded worked example (host-user dotfile, over-broad ClusterRole). Same filename, additive revision, no patch/append/supersede verb — agent overwrites and hopes the index replaces rather than duplicates.","observed_friction":"the in-between hour of audit work produced a better example; only way to fold it in was a full re-write of the same slug.","evidence":"two brain_write same filename at 09:28:22 and 10:32:49, divergent worked examples."}
+{"id":"a18","session":"AI-infra","ts":"2026-05-?T10:18:25","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"homelab-document-accepted-risk-to-break-audit-cycle.md — distinct."}
+{"id":"a19","session":"AI-infra","ts":"2026-05-?T10:32:55","tool":"brain_query","intent":"verify_write_landed","intent_tool_match":"mismatch","workaround":"6s after the homelab-chains re-write, queried 'RBAC MCP cluster pods log chain' — checking the chain reasoning is retrievable / finding the related entry. Read-after-write done via lexical search.","observed_friction":null,"evidence":"query immediately follows the 10:32:49 write."}
+{"id":"a20","session":"AI-infra","ts":"2026-05-?T18:57:34","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":"preceded by ToolSearch select:brain_write,brain_query — re-discovered tools this session.","evidence":"'extension build pinned version major version upgrade postgres pgvector'."}
+{"id":"a21","session":"AI-infra","ts":"2026-05-?T18:57:58","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"extension-version-lags-platform-major-upgrade.md."}
+{"id":"a22","session":"AI-infra","ts":"2026-05-?T18:58:06","tool":"brain_query","intent":"verify_write_landed","intent_tool_match":"mismatch","workaround":"8s after writing extension-version-lags, re-queried 'pgvector postgres extension version compile error bump' — reformulated from the 18:57:34 query ('extension build pinned version...'). Lexical re-search to confirm the just-written lesson is findable, with different keyword guess.","observed_friction":"reformulation: 'extension build pinned version major version upgrade postgres pgvector' -> 'pgvector postgres extension version compile error bump'.","evidence":"write at 18:57:58 bracketed by queries 18:57:34 and 18:58:06."}
+{"id":"a23","session":"AI-infra","ts":"2026-05-?T18:31:23","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"webfetch-readme-when-image-or-flag-uncertain.md FIRST write."}
+{"id":"a24","session":"AI-infra","ts":"2026-05-?T18:34:23","tool":"brain_write","intent":"update_or_supersede","intent_tool_match":"mismatch","workaround":"RE-WROTE webfetch-readme-when-image-or-flag-uncertain.md 3min later, near-identical body. Looks like a retry/overwrite (uncertain the first landed, or minor edit). No idempotent upsert with confirmation, so agent re-fires the write.","observed_friction":"followed 7s later by a brain_query on the same topic ('OSS tool image registry CLI flag webhook path schema drift README pre-flight') — write-write-query, i.e. overwrite then verify-by-search.","evidence":"two brain_write same filename 18:31:23 / 18:34:23, then query 18:34:31."}
+{"id":"a25","session":"AI-infra","ts":"2026-05-?T18:34:31","tool":"brain_query","intent":"verify_write_landed","intent_tool_match":"mismatch","workaround":"keyword-stuffed lexical query 'OSS tool image registry CLI flag webhook path schema drift README pre-flight' fired right after the webfetch-readme write — agent dumps every concept token hoping BM25 surfaces its own fresh note. This is semantic intent (find that conceptual lesson) coerced into a bag-of-keywords.","observed_friction":"query is a concatenation of the note's section headings — a tell that the agent is groping lexically for content it knows by meaning.","evidence":"query text mirrors the just-written note's bullet topics."}
+{"id":"a26","session":"dev","ts":"2026-06-?T21:18:26","tool":"brain_answer","intent":"synthesized_answer","intent_tool_match":"match","workaround":null,"observed_friction":"preceded by ToolSearch select:brain_answer.","evidence":"'tapir transcript persistence shared cross-user dedup table RLS isolation ADR-021 ...' -> 22min later a brain_write (acted on the answer). Answer consumed, not re-queried. Healthy."}
+{"id":"a27","session":"dev","ts":"2026-06-?T21:40:20","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"tapir-migration-and-rls-test-infra-gotchas, with wing/hall absent here (flat) — see schema-confusion note a40."}
+{"id":"a28","session":"dev","ts":"2026-06-?T05:35:04","tool":"brain_answer","intent":"synthesized_answer","intent_tool_match":"partial","workaround":"asked 'gitea MCP not working workaround file issue via API which token ... how to authenticate gitea API' — a how-do-I question. Next brain act (05:39 query) is a different topic (tapir transcript), so the answer was apparently sufficient OR abandoned; ambiguous.","observed_friction":null,"evidence":"brain_answer then unrelated brain_query 4min later."}
+{"id":"a29","session":"dev","ts":"2026-06-?T05:39:54","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"'tapir transcript persistence ADR-021 shared non-RLS'."}
+{"id":"a30","session":"dev","ts":"2026-06-?T05:57:37","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"gitea-mcp-per-repo-tools-404-and-rest-fallback FIRST write."}
+{"id":"a31","session":"dev","ts":"2026-06-?T05:57:55","tool":"brain_write","intent":"update_or_supersede","intent_tool_match":"mismatch","workaround":"RE-WROTE gitea-mcp-per-repo-tools-404-and-rest-fallback 18s later — overwrite/retry of same slug, no upsert confirmation.","observed_friction":"sub-20s gap = almost certainly a content tweak the agent could not express as an edit.","evidence":"two brain_write same filename 05:57:37 / 05:57:55."}
+{"id":"a32","session":"dev","ts":"2026-05-?T11:51:47","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"infra-litellm-absorption-2026-05-16.md."}
+{"id":"a33","session":"dev","ts":"2026-05-?T12:07:04","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"batch of 3 (litellm rebuild time piguard; docker compose orphaned volumes; prometheus_client ModuleNotFoundError) — lexical, error-string driven."}
+{"id":"a34","session":"dev","ts":"2026-05-?T15:08:15","tool":"brain_answer","intent":"synthesized_answer","intent_tool_match":"mismatch","workaround":"THREE brain_answer at 15:08 (moved compose volumes? / pi rebuild time? / litellm ModuleNotFound prometheus) — the SAME three topics queried lexically an hour earlier (12:07) — were IMMEDIATELY followed at 15:09 by THREE brain_query on the same three topics. The agent asked the synthesizer, was unsatisfied, and fell straight back to raw lexical search. Strongest answer->query fallback in the corpus.","observed_friction":"answer/query duplication across one intent: agent hedges by firing both interfaces, trusting neither.","evidence":"15:08 answers vs 15:09 queries, topic-for-topic aligned."}
+{"id":"a35","session":"dev","ts":"2026-05-?T15:09:16","tool":"brain_query","intent":"semantic_retrieval","intent_tool_match":"mismatch","workaround":"after the 3 brain_answer calls failed to satisfy, re-issued as lexical brain_query ('moved compose stack to new directory volumes disappeared empty'; 'raspberry pi docker build time arm slow'; 'how to enable prometheus metrics on litellm proxy callback'). The want is meaning-based ('did my volumes move?') but the only retrieval that 'worked' was keyword search — and these are full natural-language sentences crammed into a BM25 box.","observed_friction":"natural-language questions ('how to enable...', 'moved ... disappeared') passed to a lexical query tool — semantic intent, lexical interface.","evidence":"3 queries at 15:09 mirror the 3 answers at 15:08."}
+{"id":"a36","session":"dev","ts":"2026-05-?T20:31:50","tool":"brain_answer","intent":"synthesized_answer","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"'What happened with the litellm migration on 2026-05-16?' — episodic recall question, answer fit; no re-query followed."}
+{"id":"a37","session":"dev","ts":"2026-05-?T21:07:17","tool":"brain_query","intent":"semantic_retrieval","intent_tool_match":"mismatch","workaround":"FOUR-step reformulation chain over one Go bug: 'bytes.Buffer Bytes Reset aliasing slice sharing' -> 'go buffer reuse map backing array bug' -> [write go-bytes-buffer-bytes-reset-aliasing-trap.md] -> 'go map values all show same content after loop' -> 'bytes.Buffer Bytes returns same data every iteration'. The agent knows the SYMPTOM (all map values identical) and the CAUSE (Bytes() aliasing) but cannot phrase a single lexical query that bridges them — it wants concept retrieval and is forced to brute-force keyword variants.","observed_friction":"4 distinct phrasings of the same bug, two before and two after writing the lesson — also doubles as verify_write_landed on the trailing queries.","evidence":"21:07:17, 21:07:17, (write 21:08:01), 21:08:10, 21:08:19."}
+{"id":"a38","session":"dev","ts":"2026-05-?T21:08:01","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"go-bytes-buffer-bytes-reset-aliasing-trap.md."}
+{"id":"a39","session":"dev","ts":"2026-05-?T07:54:26","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"mcp-tool-design-get-needs-list-partner.md — a design principle."}
+{"id":"a40","session":"dev","ts":"2026-06-?T06:25:00","tool":"brain_query","intent":"check_prior_art","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"'Dex to Authentik migration auth.d-ma.be issuer cutover OIDC subject ...'."}
+{"id":"a41","session":"dev","ts":"2026-06-?T06:25:08","tool":"brain_answer","intent":"synthesized_answer","intent_tool_match":"mismatch","workaround":"brain_query (a40) and brain_answer (a41) fired ~8s apart on the SAME intent (Dex->Authentik subject-keyed token orphan). Agent runs lexical search AND synthesized answer in parallel for one question rather than choosing — it cannot predict which interface will return usable knowledge, so it pays both.","observed_friction":"query+answer doublet on one need.","evidence":"06:25:00 query then 06:25:08 answer, same topic."}
+{"id":"a42","session":"dev","ts":"2026-06-?T13:48:49","tool":"brain_query","intent":"verify_write_landed","intent_tool_match":"mismatch","workaround":"'authentik cutover validation probe' then 6min later 'authentik cutover post-flip validation' — reformulated pair, likely searching for the agent's own earlier cutover notes / confirming validation steps are recorded. Lexical re-search standing in for recall-my-recent-context.","observed_friction":"reformulation: 'validation probe' -> 'post-flip validation'.","evidence":"13:48:49 and 13:54:56."}
+{"id":"a43","session":"dev","ts":"2026-06-?T13:59:17","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":"preceded by ToolSearch select:brain_write.","evidence":"oidc-issuer-host-change-vs-idp-swap-subject."}
+{"id":"a44","session":"dev","ts":"2026-06-?T13:59:50","tool":"brain_write","intent":"store_new_knowledge","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"cannot-move-ingress-host-across-namespaces-flux-dryrun FIRST write."}
+{"id":"a45","session":"dev","ts":"2026-06-?T14:00:13","tool":"brain_write","intent":"update_or_supersede","intent_tool_match":"mismatch","workaround":"RE-WROTE cannot-move-ingress-host-across-namespaces-flux-dryrun 23s later — overwrite of same slug, no edit/upsert primitive.","observed_friction":"sub-30s gap = content correction expressed as a full re-write.","evidence":"two brain_write same filename 13:59:50 / 14:00:13."}
+{"id":"a46","session":"dev","ts":"2026-06-?T13:53:54","tool":"brain_write(HTTP-staged)","intent":"store_new_knowledge","intent_tool_match":"mismatch","workaround":"after `ToolSearch select:mcp__claude_ai_brain__authenticate` (MCP auth flow), the agent staged the entry as `cat > /tmp/brain_entry.json` ({filename:'postgres-force-rls-cross-u...', content}) for a curl write rather than calling brain_write directly — MCP write path was not usable (auth/loading), so it dropped to the HTTP bodge.","observed_friction":"reached for an 'authenticate' tool, then abandoned MCP for hand-built JSON + curl. Matches known pattern: brain/op MCP auth lapses often.","evidence":"ToolSearch authenticate 13:53:27 -> cat /tmp/brain_entry.json 13:53:54."}
+{"id":"a47","session":"template-go-agent","ts":"2026-05-?T18:46:26","tool":"BASH(not-a-brain-act)","intent":"intent_unclear","intent_tool_match":"match","workaround":null,"observed_friction":null,"evidence":"'brain_' substring was inside a git commit message body ('agent boundaries, network policy, agent s...'), NOT a brain call. Excluded from knowledge-act analysis; logged for audit completeness."}

brain/sessions/analysis/agent-intent-column.md

@@ -0,0 +1,148 @@
+# Agent-Consumer Brain Intent Analysis — koala column
+
+**Consumer:** `autonomous_agent` (all rows). **Host:** koala. **Date:** 2026-06-15.
+**Raw rows:** `agent-intent-column.jsonl` (46 real knowledge-acts + 1 excluded false-positive).
+
+## Caveat — canonical schema not on this host
+
+The shared closed-vocabulary file `brain-intent-extraction.md` **does not exist on
+koala** — the only reference to it is inside *this task's own prompt*. The intent
+vocabulary below was **reconstructed** from the prompt's framing + `brain/schema.md`.
+Every row carries `schema_source: reconstructed`. If the canonical vocab differs,
+re-map the `intent` field; the `intent_tool_match` / `workaround` / `observed_friction`
+evidence stands regardless of label names.
+
+**Reconstructed closed vocab:** `semantic_retrieval`, `lexical_lookup`,
+`check_prior_art`, `synthesized_answer`, `store_new_knowledge`, `update_or_supersede`,
+`ingest_raw_source`, `verify_write_landed`, `discover_capability`, `intent_unclear`.
+
+## Corpus
+
+- `~/.claude/projects/*/*.jsonl` — Claude Code agent transcripts (98 files). **The only
+  source with brain calls.**
+- `brain/sessions/*.jsonl` — empty (only `.gitkeep`).
+- `agentsquad docs/eval/*.jsonl` — code-review eval results, **not** brain calls.
+- No separate Crush session logs on this host.
+- **Zero** brain calls were human-typed. Every brain act is agent-initiated (the
+  CLAUDE.md "query as reflex / close-the-loop write" behaviour), so all qualify as
+  `autonomous_agent`. The human gave the top-level task; the agent chose every brain act.
+
+## 1. Intent histogram, split by `intent_tool_match`
+
+| intent | match | mismatch | partial | total |
+|---|---|---|---|---|
+| check_prior_art | 10 | 0 | 0 | 10 |
+| store_new_knowledge | 14 | 1 | 0 | 15 |
+| update_or_supersede | 0 | 5 | 0 | 5 |
+| synthesized_answer | 2 | 2 | 1 | 5 |
+| verify_write_landed | 0 | 4 | 0 | 4 |
+| semantic_retrieval | 0 | 3 | 0 | 3 |
+| ingest_raw_source | 2 | 0 | 0 | 2 |
+| discover_capability | 0 | 2 | 0 | 2 |
+| **total** | **28** | **17** | **1** | **46** |
+
+> Batch note: several rows collapse a same-second fan-out of identical-intent calls
+> (a10=3, a11=4, a14=5, a33=3, a34=3, a35=3). Call-level the corpus is ~62 brain calls;
+> the table counts the 46 distinct knowledge-acts. Frequency is deliberately *not* the
+> point — the mismatch column is.
+
+**37% of agent knowledge-acts (17/46) are interface mismatches.** Every mismatch falls
+into one of four intents: `update_or_supersede`, `verify_write_landed`,
+`semantic_retrieval`, `discover_capability` — plus one `store` that had to use HTTP.
+
+## 2. Mismatch list, grouped by intent (primary deliverable)
+
+### update_or_supersede → re-write same slug (5/5 mismatch) — HIGHEST VALUE
+There is **no update / patch / append / supersede verb**. When an agent improves a note
+it already wrote, the only move is to call `brain_write`/`brain_ingest` **again with the
+same filename/source** and hope the index replaces rather than duplicates. Observed:
+
+| slug | 1st write | 2nd write | gap | what changed |
+|---|---|---|---|---|
+| `tapir-rls-identity-bootstrapping` (ingest) | 14:00:59 | 14:02:08 | 69s | condensed body |
+| `homelab-security-chains-not-bugs.md` | 09:28:22 | 10:32:49 | 64m | new worked example |
+| `webfetch-readme-when-image-or-flag-uncertain.md` | 18:31:23 | 18:34:23 | 3m | near-identical (retry) |
+| `gitea-mcp-per-repo-tools-404-and-rest-fallback` | 05:57:37 | 05:57:55 | 18s | content tweak |
+| `cannot-move-ingress-host-across-namespaces-flux-dryrun` | 13:59:50 | 14:00:13 | 23s | content tweak |
+
+Sub-30s gaps (3 of 5) read as "I wanted to edit but can only overwrite." The agent has
+no way to know whether the second write deduped or created a contradictory v2 — opacity
+the brain's own design principle (`mcp-tool-design-get-needs-list-partner.md`, written
+*by one of these very agents*) would flag: every `_write` needs a `_get`/`_update` partner.
+
+### verify_write_landed → lexical re-query (4/4 mismatch)
+No read-after-write / get-by-id confirmation. After every substantive write, agents
+re-query lexically to check the note is retrievable — and *reformulate the keywords*
+because they can't predict what BM25 indexed:
+- `exit-255` lesson: query `exit 255 unknown reason restart loop diagnosis` → write →
+  query `exit 255 unknown SIGKILL containerd`.
+- `extension-version-lags`: query `extension build pinned version...pgvector` → write →
+  query `pgvector postgres extension version compile error bump`.
+- `webfetch-readme`: write → write → query stuffed with the note's own section headings.
+
+### semantic_retrieval → BM25 keyword-stuffing (3/3 mismatch)
+Agent knows the *meaning* but not the *indexed words*, so it brute-forces phrasings of
+one need against a lexical tool:
+- **4-step chain on one Go bug:** `bytes.Buffer Bytes Reset aliasing slice sharing` →
+  `go buffer reuse map backing array bug` → (write) → `go map values all show same
+  content after loop` → `bytes.Buffer Bytes returns same data every iteration`. Symptom
+  and cause both known; no single lexical query bridges them.
+- Natural-language questions (`how to enable prometheus metrics on litellm proxy
+  callback`, `moved compose stack to new directory volumes disappeared empty`) shoved
+  into `brain_query`.
+
+### synthesized_answer → fall back to / hedge with brain_query (2 mismatch + 1 partial)
+`brain_answer` is frequently **not trusted as terminal**:
+- **Strongest signal:** 3× `brain_answer` at 15:08 (compose volumes / pi rebuild time /
+  litellm ModuleNotFound) → 3× `brain_query` at 15:09 on the *same three topics*. The
+  agent asked the synthesizer, was unsatisfied, and immediately re-ran raw search.
+- Dex→Authentik: `brain_query` and `brain_answer` fired **8s apart on one question** —
+  the agent pays both interfaces because it can't predict which returns usable knowledge.
+- (Counter-examples exist: `brain_answer` for episodic recall — "what happened with the
+  litellm migration on 2026-05-16?" — was consumed and not re-queried. So `answer`
+  works for *episodic/temporal* recall, fails for *how-do-I / does-X-hold* reasoning.)
+
+### discover_capability + store-via-HTTP (3 mismatch)
+brain tools are **not ambient** — they are deferred and must be `ToolSearch`-loaded each
+session. Agents fumble the discovery (`ToolSearch 'brain knowledge memory'` →
+`'brain'` → `'brain ingestion knowledge wiki'`) and, when MCP load/auth fails, drop to
+**raw `curl` against `brain-mcp` / hand-built `/tmp/brain_entry.json`**. One agent even
+`ToolSearch`-ed an `authenticate` tool, then abandoned MCP for the HTTP bodge — matching
+the known "brain/op MCP auth lapses too often" footgun.
+
+### Write-interface / layer schema confusion (cross-cutting)
+`brain_write` was called with **three different param shapes** in the same corpus:
+`{filename, type:"lesson", content}`, `{filename, content}` (no type), and
+`{wing:"tapir", hall:"failures", filename, content}` — plus `brain_ingest {source,
+content}`. Agents are unsure which verb and which layer (flat slug vs `wing`/`hall`
+knowledge routing vs raw ingest) a given knowledge-act maps to. This is the
+`knowledge/ vs wiki/` confusion expressed at the parameter level.
+
+## 3. `intent_unclear` rate
+
+**0 / 46 genuine brain acts (0%).** Agent intent is unusually legible because these are
+Claude Code transcripts: the surrounding task, the query/filename strings, and the
+write content all disambiguate. One row (`a47`) was tagged `intent_unclear` and
+**excluded** — its `brain_` substring was inside a git commit message, not a brain call.
+Example of the only ambiguity that arose: a `brain_answer` on "gitea MCP not working...
+how to authenticate" followed by an unrelated query — can't tell if the answer satisfied
+or was abandoned (`partial`, row a28).
+
+## 4. The single biggest intent↔interface gap
+
+**The brain offers one write verb and one lexical read verb, but autonomous agents
+perform four distinct knowledge-acts against them — and three of the four have no fitting
+interface.** The deepest gap is the **missing update/supersede path**: agents close every
+task by writing a lesson (the CLAUDE.md ritual), routinely improve it minutes-to-an-hour
+later, and — having no edit primitive — re-write the same slug blind, unable to tell
+whether they corrected the entry or forked a contradiction into the index. This compounds
+with the lexical-only read side: because there is no `get-by-id` or semantic retrieval,
+agents can't even reliably *find their own just-written note* to check it, so they
+keyword-stuff reformulated queries and hedge `brain_answer` with parallel `brain_query`.
+The interface is built for *append-and-keyword-search*; the agents are trying to
+*curate a living, deduplicated knowledge base*, and the seam between those two shows up
+as the 5 blind re-writes, 4 read-after-write re-queries, and 3 semantic-as-lexical chains
+that dominate the mismatch column.
+
+---
+*Evidence-only per task scope — no redesign proposed.*

brain/sessions/analysis/intent-interface-findings.md

@@ -0,0 +1,140 @@
+# Brain-MCP Intent↔Interface Findings — Unified (two-column merge)
+
+**Status — 2026-06-16**
+- ✅ **Agent column** filled from `agent-intent-column.jsonl` (46 acts, koala).
+- ⏳ **Human column** = `PENDING`. Drop the Claude.ai-history analysis into
+  `human-intent-column.jsonl` (same dir, schema below), then fill the `PENDING`
+  cells and the synthesis blocks marked `<<SYNTH>>`.
+- ⚠️ Canonical `brain-intent-extraction.md` still absent on koala. Vocab below is
+  the **reconstructed** lock both columns must share. If the real file surfaces,
+  re-map `intent` labels in *both* columns identically before merging.
+
+---
+
+## Shared schema (LOCKED — both columns conform)
+
+Per-call row, JSONL:
+
+| field | values / form | notes |
+|---|---|---|
+| `id` | `a01..` (agent) / `h01..` (human) | column prefix kept distinct |
+| `session` | string | source session/conversation id |
+| `ts` | ISO-8601 | best-effort |
+| `tool` | brain tool name (+ `(HTTP-curl)` / `(HTTP-staged)` suffix for bodges) | |
+| `intent` | closed vocab ↓ | the knowledge-act WANTED |
+| `intent_tool_match` | `match` \| `mismatch` \| `partial` | does the called tool fit the want |
+| `consumer_type` | `autonomous_agent` \| `human_interactive` | fixed per column |
+| `workaround` | string \| null | the bodge when mismatch — **primary signal** |
+| `observed_friction` | string \| null | reformulation chains, discovery tax, hedging |
+| `evidence` | string | excerpt anchoring the classification |
+| `schema_source` | `reconstructed` | flip to `canonical` if real vocab lands |
+
+### Closed intent vocab (LOCKED)
+`semantic_retrieval`, `lexical_lookup`, `check_prior_art`, `synthesized_answer`,
+`store_new_knowledge`, `update_or_supersede`, `ingest_raw_source`,
+`verify_write_landed`, `discover_capability`, `intent_unclear`.
+
+---
+
+## Master comparison — by intent
+
+| intent | agent acts | agent mismatch | human acts | human mismatch | shared gap |
+|---|---|---|---|---|---|
+| check_prior_art | 10 | 0% | `PENDING` | `PENDING` | — |
+| store_new_knowledge | 15 | 7% (1/15) | `PENDING` | `PENDING` | `<<SYNTH>>` |
+| update_or_supersede | 5 | **100%** (5/5) | `PENDING` | `PENDING` | `<<SYNTH>>` no edit verb |
+| synthesized_answer | 5 | 40% (2/5)+1 partial | `PENDING` | `PENDING` | `<<SYNTH>>` |
+| verify_write_landed | 4 | **100%** (4/4) | `PENDING` | `PENDING` | `<<SYNTH>>` no read-after-write |
+| semantic_retrieval | 3 | **100%** (3/3) | `PENDING` | `PENDING` | `<<SYNTH>>` lexical-only read |
+| ingest_raw_source | 2 | 0% | `PENDING` | `PENDING` | — |
+| discover_capability | 2 | **100%** (2/2) | `PENDING` | `PENDING` | agent-specific (ToolSearch/auth)? |
+| intent_unclear | 0 | — | `PENDING` | `PENDING` | divergence expected ↓ |
+| **TOTAL** | **46** | **37% (17)** | `PENDING` | `PENDING` | |
+
+---
+
+## Per-intent merged findings
+
+### update_or_supersede — agent: 5/5 mismatch (highest value)
+**Agent:** no edit/patch/append verb. Agents re-write same slug blind:
+`homelab-security-chains-not-bugs.md` (+64m), `tapir-rls-identity-bootstrapping`,
+`webfetch-readme...`, `gitea-mcp-per-repo-tools-404...`,
+`cannot-move-ingress-host...` — 3 of 5 sub-30s ("wanted edit, got overwrite").
+Cannot tell if write deduped or forked a contradiction.
+**Human:** `PENDING` — *look for: user editing a prior note, asking "update what I
+saved about X", or expressing frustration that an old fact is stale/duplicated.*
+**<<SYNTH>>** shared verdict once both filled.
+
+### verify_write_landed — agent: 4/4 mismatch
+**Agent:** no `get-by-id`/read-after-write. Agents lexically re-query their own
+fresh note with reformulated keywords (`exit 255 unknown reason` → `...SIGKILL
+containerd`; `extension build pinned...` → `pgvector ...compile error bump`).
+**Human:** `PENDING` — *humans may not exhibit this (they trust the write UI
+confirmation). If absent in human column, it's an agent-specific gap → flag.*
+**<<SYNTH>>**.
+
+### semantic_retrieval — agent: 3/3 mismatch
+**Agent:** meaning known, indexed words unknown → BM25 keyword-stuffing. 4-step
+chain on one Go `bytes.Buffer` bug; NL questions shoved into `brain_query`.
+**Human:** `PENDING` — *humans likely hit this HARDER (they phrase conversationally).
+Compare reformulation-chain length agent vs human.*
+**<<SYNTH>>** — likely the strongest cross-consumer overlap.
+
+### synthesized_answer — agent: 2 mismatch + 1 partial
+**Agent:** `brain_answer` not trusted terminal — 3 answers → 3 same-topic queries
+1min later; query+answer fired 8s apart hedging one need. Works for *episodic*
+recall, fails for *how-do-I / does-X-hold*.
+**Human:** `PENDING` — *humans may prefer `brain_answer` as primary (chat-native).
+If human match-rate >> agent, the tool fits humans not agents → key divergence.*
+**<<SYNTH>>**.
+
+### store_new_knowledge — agent: 14/15 match
+**Agent:** healthy, except 1 HTTP-staged bodge when MCP auth lapsed. Also surfaced
+write-schema confusion: 3 param shapes (`{filename,type}` / `{filename}` /
+`{wing,hall,filename}`) + `ingest{source}`.
+**Human:** `PENDING` — *humans rarely write directly; expect low volume.*
+**<<SYNTH>>**.
+
+### check_prior_art / ingest_raw_source — agent: 0% mismatch
+Lexical fits named-entity recall and raw-source capture. **Human:** `PENDING`.
+
+### discover_capability — agent: 2/2 mismatch (agent-specific)
+Brain tools deferred → `ToolSearch`-load each session; auth lapse → `curl` bodge.
+**Likely has NO human analog** (humans get ambient connectors). Candidate for
+"agent-only gap" bucket. **Human:** `PENDING` to confirm absent.
+
+---
+
+## Cross-consumer divergence — questions to resolve at merge
+
+1. **intent_unclear rate.** Agent = 0% (transcripts self-document). Human expected
+   higher (conversational, implicit). Big delta = the columns measure legibility
+   differently, not just intent.
+2. **Where does each consumer's mismatch concentrate?** Agent mismatch is
+   write-side-heavy (supersede + verify-landed = 9/17). Hypothesis: human mismatch
+   is read-side-heavy (semantic + answer). If true → **the interface fails the two
+   consumers at opposite ends.**
+3. **Agent-only gaps** (`discover_capability`, `verify_write_landed`) vs
+   **shared gaps** (`semantic_retrieval`, `update_or_supersede`). Shared gaps =
+   highest-priority evidence; agent-only = harness/auth issues.
+
+---
+
+## Combined headline — `<<SYNTH>>` (fill when human column lands)
+
+> Agent-side draft (to be reconciled with human-side):
+> Brain = append + keyword-search; agents want a curated, dedup'd, self-verifying KB.
+> Missing update/supersede path + lexical-only reads are the seam. **Open question
+> for the merge: do humans hit the same read-side wall, making semantic-retrieval the
+> universal gap — or do agents uniquely suffer the write-side (supersede / verify)
+> wall that humans sidestep via the chat UI?**
+
+---
+
+## Drop-in checklist (when human column arrives)
+1. Place `human-intent-column.jsonl` in this dir; conform to LOCKED schema.
+2. Fill every `PENDING` cell in master table + per-intent blocks.
+3. Resolve the 3 divergence questions with evidence.
+4. Replace each `<<SYNTH>>` with the reconciled verdict; write the combined headline.
+5. If canonical vocab surfaced: re-map both columns' `intent`, flip `schema_source`.
+6. Commit as `docs(brain): merge human+agent intent columns`.

cmd/hyperguild/README.md

@@ -55,18 +55,21 @@ Flags:
 - `--limit N` — max results (default 5)
 - `--json` — emit the raw response envelope
 
-### `hyperguild brain write <type> <slug>`
+### `hyperguild brain write <wing> <hall> <slug>`
 
-Reads markdown from stdin, writes a knowledge entry.
+Reads markdown from stdin, writes it to `brain/wiki/<wing>/<hall>/<slug>.md`
+with `wing`/`hall`/`created_at` frontmatter injected (there is no legacy
+`brain/knowledge/` fallback — ADR-0012 / #79, both wing and hall are
+required).
 
 ```bash
-$ cat <<EOF | hyperguild brain write knowledge example-lesson
+$ cat <<EOF | hyperguild brain write homelab facts example-lesson
 # Example lesson
 
 ## Lesson
 ...
 EOF
-knowledge/example-lesson.md
+wiki/homelab/facts/example-lesson.md
 ```
 
 ### `hyperguild brain pass-rate <skill>`
@@ -112,16 +115,15 @@ Flags:
 - `--out PATH` — output file (default `./.mcp.json`)
 - `--force` — overwrite an existing file
 
-Modes:
+Modes (all list **brain + gitea** — Gitea is the audit-trail invariant of the
+consolidated single harness, #75):
 
-- **cloud** — brain MCP only. Claude Code with no routing.
-- **client-local** — brain + routing pod. The `routing` entry points at
-  `koala:30310/mcp` (the routing pod, deployed in Plan 6). The
-  `X-Hyperguild-Mode: client-local` header is forward-compat for future
-  modes; the pod treats absent or unknown values as `client-local`.
-- **sovereign** — brain only, with a `_mode_note` explaining that this
-  mode primarily uses Crush + LiteLLM and the `.mcp.json` is a Claude
-  Code fallback for emergency offline use.
+- **cloud** — brain + gitea MCP.
+- **client-local** — brain + gitea MCP. (The former `routing` entry pointing at
+  `koala:30310/mcp` was removed — the routing pod is iceboxed, #75.)
+- **sovereign** — brain + gitea, with a `_mode_note` explaining that this mode
+  primarily uses Crush + LiteLLM and the `.mcp.json` is a Claude Code fallback
+  for emergency offline use.
 
 ## Environment
 

cmd/hyperguild/brain.go

@@ -60,13 +60,14 @@ func runBrainWrite(ctx context.Context, args []string, stdin io.Reader, stdout,
 	if err := fs.Parse(args); err != nil {
 		return fmt.Errorf("parse flags: %w", err)
 	}
-	if fs.NArg() < 2 {
-		return errors.New("type and slug required (e.g. brain write knowledge my-slug)")
+	if fs.NArg() < 3 {
+		return errors.New("wing, hall and slug required (e.g. brain write homelab facts my-slug)")
 	}
-	kind := fs.Arg(0)
-	slug := fs.Arg(1)
+	wing := fs.Arg(0)
+	hall := fs.Arg(1)
+	slug := fs.Arg(2)
 
-	res, err := newBrainClient().Write(ctx, kind, slug, stdin)
+	res, err := newBrainClient().Write(ctx, wing, hall, slug, stdin)
 	if err != nil {
 		return err
 	}

cmd/hyperguild/brain_test.go

@@ -101,7 +101,7 @@ func TestRunBrainWrite_Success(t *testing.T) {
 	var out, errBuf bytes.Buffer
 	err := runBrain(
 		context.Background(),
-		[]string{"write", "knowledge", "test-slug"},
+		[]string{"write", "homelab", "facts", "test-slug"},
 		strings.NewReader("# Test\n\nSome body content.\n"),
 		&out, &errBuf,
 	)
@@ -111,9 +111,9 @@ func TestRunBrainWrite_Success(t *testing.T) {
 
 func TestRunBrainWrite_MissingArgs(t *testing.T) {
 	var out, errBuf bytes.Buffer
-	err := runBrain(context.Background(), []string{"write", "knowledge"}, strings.NewReader("x"), &out, &errBuf)
+	err := runBrain(context.Background(), []string{"write", "homelab"}, strings.NewReader("x"), &out, &errBuf)
 	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "type and slug required")
+	assert.Contains(t, err.Error(), "wing, hall and slug required")
 }
 
 func TestRunBrainWrite_BackendError(t *testing.T) {
@@ -127,7 +127,7 @@ func TestRunBrainWrite_BackendError(t *testing.T) {
 	var out, errBuf bytes.Buffer
 	err := runBrain(
 		context.Background(),
-		[]string{"write", "knowledge", "bad slug"},
+		[]string{"write", "homelab", "facts", "bad slug"},
 		strings.NewReader("body"),
 		&out, &errBuf,
 	)
@@ -150,7 +150,7 @@ func TestRunBrainWrite_EmptyStdin(t *testing.T) {
 	t.Setenv("BRAIN_URL", srv.URL)
 
 	var out, errBuf bytes.Buffer
-	err := runBrain(context.Background(), []string{"write", "knowledge", "empty"}, strings.NewReader(""), &out, &errBuf)
+	err := runBrain(context.Background(), []string{"write", "homelab", "facts", "empty"}, strings.NewReader(""), &out, &errBuf)
 	require.NoError(t, err)
 	assert.Equal(t, 0, gotLen, "empty stdin should produce empty content payload")
 }

cmd/hyperguild/http.go

@@ -20,6 +20,7 @@ const defaultBrainURL = "http://koala:30330"
 // shell-friendly client; MCP framing is unnecessary.
 type brainClient struct {
 	baseURL string
+	token   string // BRAIN_MCP_TOKEN; the REST API requires it since hyperguild#149
 	http    *http.Client
 }
 
@@ -30,6 +31,7 @@ func newBrainClient() *brainClient {
 	}
 	return &brainClient{
 		baseURL: u,
+		token:   os.Getenv("BRAIN_MCP_TOKEN"),
 		http:    &http.Client{Timeout: 5 * time.Second},
 	}
 }
@@ -62,8 +64,7 @@ func (c *brainClient) Query(ctx context.Context, topic string, limit int) (*Quer
 		return nil, fmt.Errorf("build request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := c.http.Do(req)
+	resp, err := c.do(req)
 	if err != nil {
 		return nil, fmt.Errorf("brain POST /query: %w", err)
 	}
@@ -84,16 +85,17 @@ type WriteResult struct {
 	Path string `json:"path"`
 }
 
-func (c *brainClient) Write(ctx context.Context, kind, slug string, content io.Reader) (*WriteResult, error) {
+func (c *brainClient) Write(ctx context.Context, wing, hall, filename string, content io.Reader) (*WriteResult, error) {
 	body, err := io.ReadAll(content)
 	if err != nil {
 		return nil, fmt.Errorf("read content: %w", err)
 	}
 	payload, err := json.Marshal(struct {
-		Type    string `json:"type"`
-		Slug    string `json:"slug"`
+		Wing     string `json:"wing"`
+		Hall     string `json:"hall"`
+		Filename string `json:"filename"`
 		Content  string `json:"content"`
-	}{Type: kind, Slug: slug, Content: string(body)})
+	}{Wing: wing, Hall: hall, Filename: filename, Content: string(body)})
 	if err != nil {
 		return nil, fmt.Errorf("marshal payload: %w", err)
 	}
@@ -104,8 +106,7 @@ func (c *brainClient) Write(ctx context.Context, kind, slug string, content io.R
 		return nil, fmt.Errorf("build request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := c.http.Do(req)
+	resp, err := c.do(req)
 	if err != nil {
 		return nil, fmt.Errorf("brain POST /write: %w", err)
 	}
@@ -142,7 +143,7 @@ func (c *brainClient) PassRate(ctx context.Context, skill, window string) (*Pass
 	if err != nil {
 		return nil, fmt.Errorf("build request: %w", err)
 	}
-	resp, err := c.http.Do(req)
+	resp, err := c.do(req)
 	if err != nil {
 		return nil, fmt.Errorf("brain GET /pass-rate: %w", err)
 	}
@@ -157,3 +158,13 @@ func (c *brainClient) PassRate(ctx context.Context, skill, window string) (*Pass
 	}
 	return &out, nil
 }
+
+// do sends every brain request, adding the bearer token when one is
+// configured. All methods go through here so none can forget it (PassRate
+// did, PR #152 review).
+func (c *brainClient) do(req *http.Request) (*http.Response, error) {
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
+	return c.http.Do(req)
+}

cmd/hyperguild/http_auth_test.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#149: the ingestion REST API now requires a bearer token; the CLI
+// sends BRAIN_MCP_TOKEN, or it gets 401 on every brain call.
+func TestBrainClientSendsBrainMCPTokenOnQueryWriteAndPassRate(t *testing.T) {
+	var got []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = append(got, r.URL.Path+" "+r.Header.Get("Authorization"))
+		switch r.URL.Path {
+		case "/write":
+			_, _ = w.Write([]byte(`{"path":"wiki/x/facts/y.md"}`))
+			return
+		case "/pass-rate":
+			_, _ = w.Write([]byte(`{}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{"results":[]}`))
+	}))
+	defer srv.Close()
+	t.Setenv("BRAIN_URL", srv.URL)
+	t.Setenv("BRAIN_MCP_TOKEN", "cli-test-token")
+
+	c := newBrainClient()
+	_, err := c.Query(context.Background(), "x", 1)
+	require.NoError(t, err)
+	_, err = c.Write(context.Background(), "x", "facts", "y", strings.NewReader("# y"))
+	require.NoError(t, err)
+	// PR #152 review: PassRate sent no token and would 401 in production.
+	_, _ = c.PassRate(context.Background(), "tdd", "7d")
+	assert.Equal(t, []string{"/query Bearer cli-test-token", "/write Bearer cli-test-token",
+		"/pass-rate Bearer cli-test-token"}, got)
+}
+
+func TestBrainClientSendsNoAuthorizationWhenTokenUnset(t *testing.T) {
+	var auth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		auth = r.Header.Get("Authorization")
+		_, _ = w.Write([]byte(`{"results":[]}`))
+	}))
+	defer srv.Close()
+	t.Setenv("BRAIN_URL", srv.URL)
+	t.Setenv("BRAIN_MCP_TOKEN", "")
+	_, err := newBrainClient().Query(context.Background(), "x", 1)
+	require.NoError(t, err)
+	assert.Empty(t, auth)
+}

cmd/hyperguild/http_test.go

@@ -65,23 +65,25 @@ func TestBrainClient_Write_Success(t *testing.T) {
 		assert.Equal(t, http.MethodPost, r.Method)
 		body, _ := io.ReadAll(r.Body)
 		var got struct {
-			Type    string `json:"type"`
-			Slug    string `json:"slug"`
+			Wing     string `json:"wing"`
+			Hall     string `json:"hall"`
+			Filename string `json:"filename"`
 			Content  string `json:"content"`
 		}
 		require.NoError(t, json.Unmarshal(body, &got))
-		assert.Equal(t, "knowledge", got.Type)
-		assert.Equal(t, "find-h", got.Slug)
+		assert.Equal(t, "homelab", got.Wing)
+		assert.Equal(t, "facts", got.Hall)
+		assert.Equal(t, "find-h", got.Filename)
 		assert.Equal(t, "# body\n", got.Content)
 		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"path":"knowledge/find-h.md"}`))
+		_, _ = w.Write([]byte(`{"path":"wiki/homelab/facts/find-h.md"}`))
 	}))
 	defer srv.Close()
 
 	c := &brainClient{baseURL: srv.URL, http: srv.Client()}
-	res, err := c.Write(context.Background(), "knowledge", "find-h", strings.NewReader("# body\n"))
+	res, err := c.Write(context.Background(), "homelab", "facts", "find-h", strings.NewReader("# body\n"))
 	require.NoError(t, err)
-	assert.Equal(t, "knowledge/find-h.md", res.Path)
+	assert.Equal(t, "wiki/homelab/facts/find-h.md", res.Path)
 }
 
 func TestBrainClient_PassRate_Success(t *testing.T) {

cmd/hyperguild/mode.go

@@ -59,31 +59,40 @@ func runMode(ctx context.Context, args []string, _ io.Reader, stdout, stderr io.
 	return nil
 }
 
+// giteaMCPURL is the public Gitea MCP endpoint (OAuth via Dex/Authentik). Gitea
+// is the audit-trail invariant of the consolidated single harness (#75), so every
+// mode lists it as an available connection.
+const giteaMCPURL = "https://git-mcp.d-ma.be/mcp"
+
+func brainEntry(brainURL string) map[string]any {
+	return map[string]any{
+		"url":         brainURL + "/mcp",
+		"description": "Brain MCP — knowledge query, write, ingestion, session log",
+	}
+}
+
+func giteaEntry() map[string]any {
+	return map[string]any{
+		"url":         giteaMCPURL,
+		"description": "Gitea MCP — issues/PRs/repo ops (audit-trail invariant)",
+	}
+}
+
 func modeCloud(brainURL string) map[string]any {
 	return map[string]any{
 		"mcpServers": map[string]any{
-			"brain": map[string]any{
-				"url":         brainURL + "/mcp",
-				"description": "Brain MCP — knowledge query, write, ingestion, session log",
-			},
+			"brain": brainEntry(brainURL),
+			"gitea": giteaEntry(),
 		},
 	}
 }
 
 func modeClientLocal(brainURL string) map[string]any {
+	// The routing pod is iceboxed (#75); the consolidated harness is brain + gitea.
 	return map[string]any{
 		"mcpServers": map[string]any{
-			"brain": map[string]any{
-				"url":         brainURL + "/mcp",
-				"description": "Brain MCP — knowledge query, write, ingestion, session log",
-			},
-			"routing": map[string]any{
-				"url":         "http://koala:30310/mcp",
-				"description": "Mode 2 routing pod — routes skill calls to LiteLLM/local",
-				"headers": map[string]any{
-					"X-Hyperguild-Mode": "client-local",
-				},
-			},
+			"brain": brainEntry(brainURL),
+			"gitea": giteaEntry(),
 		},
 	}
 }
@@ -92,10 +101,8 @@ func modeSovereign(brainURL string) map[string]any {
 	return map[string]any{
 		"_mode_note": "Sovereign mode primarily uses Crush + LiteLLM. This .mcp.json is provided as Claude Code fallback (e.g. emergency offline editing).",
 		"mcpServers": map[string]any{
-			"brain": map[string]any{
-				"url":         brainURL + "/mcp",
-				"description": "Brain MCP — knowledge query, write, ingestion, session log",
-			},
+			"brain": brainEntry(brainURL),
+			"gitea": giteaEntry(),
 		},
 	}
 }

cmd/hyperguild/mode_test.go

@@ -35,11 +35,13 @@ func TestRunMode_Cloud_Default(t *testing.T) {
 	servers, ok := got["mcpServers"].(map[string]any)
 	require.True(t, ok, "mcpServers must be a JSON object")
 	assert.Contains(t, servers, "brain")
+	assert.Contains(t, servers, "gitea")
 	assert.NotContains(t, servers, "routing")
 	assert.NotContains(t, got, "_mode_note")
 }
 
-func TestRunMode_ClientLocal_HasRoutingEntry(t *testing.T) {
+func TestRunMode_ClientLocal_NoRouting_HasGitea(t *testing.T) {
+	// #75: the routing pod is iceboxed; the consolidated harness is brain + gitea.
 	dir := t.TempDir()
 	outPath := filepath.Join(dir, ".mcp.json")
 	t.Setenv("BRAIN_URL", "http://koala:30330")
@@ -51,17 +53,11 @@ func TestRunMode_ClientLocal_HasRoutingEntry(t *testing.T) {
 	got := readJSON(t, outPath)
 	servers := got["mcpServers"].(map[string]any)
 	require.Contains(t, servers, "brain")
-	require.Contains(t, servers, "routing")
-
-	routing := servers["routing"].(map[string]any)
-	assert.NotContains(t, routing, "_routing_pending", "placeholder should be removed once Plan 6 ships")
-
-	headers, ok := routing["headers"].(map[string]any)
-	require.True(t, ok, "routing entry should have headers block")
-	assert.Equal(t, "client-local", headers["X-Hyperguild-Mode"])
+	require.Contains(t, servers, "gitea")
+	assert.NotContains(t, servers, "routing", "routing pod iceboxed (#75)")
 }
 
-func TestModeClientLocalHasRoutingHeader(t *testing.T) {
+func TestModeGiteaEntryPresentAndWellFormed(t *testing.T) {
 	tmp := t.TempDir() + "/mcp.json"
 	out := &bytes.Buffer{}
 	stderr := &bytes.Buffer{}
@@ -73,13 +69,10 @@ func TestModeClientLocalHasRoutingHeader(t *testing.T) {
 	require.NoError(t, json.Unmarshal(body, &doc))
 
 	servers := doc["mcpServers"].(map[string]any)
-	routing := servers["routing"].(map[string]any)
-	assert.Equal(t, "http://koala:30310/mcp", routing["url"])
-	assert.NotContains(t, routing, "_routing_pending", "placeholder should be removed once Plan 6 ships")
-
-	headers, ok := routing["headers"].(map[string]any)
-	require.True(t, ok, "routing entry should have headers block")
-	assert.Equal(t, "client-local", headers["X-Hyperguild-Mode"])
+	require.NotContains(t, servers, "routing")
+	gitea, ok := servers["gitea"].(map[string]any)
+	require.True(t, ok, "gitea entry must be present (audit-trail invariant)")
+	assert.Equal(t, "https://git-mcp.d-ma.be/mcp", gitea["url"])
 }
 
 func TestRunMode_Sovereign_HasModeNote(t *testing.T) {
@@ -94,6 +87,7 @@ func TestRunMode_Sovereign_HasModeNote(t *testing.T) {
 	assert.Contains(t, got, "_mode_note")
 	servers := got["mcpServers"].(map[string]any)
 	assert.Contains(t, servers, "brain")
+	assert.Contains(t, servers, "gitea")
 	assert.NotContains(t, servers, "routing")
 }
 

cmd/hyperguild/tier.go

@@ -8,7 +8,7 @@ import (
 	"io"
 	"os"
 
-	"github.com/mathiasbq/supervisor/internal/tier"
+	"git.d-ma.be/mathias/hyperguild/internal/tier"
 )
 
 const defaultAnthropicProbe = "https://api.anthropic.com"

cmd/routing/main.go

@@ -1,170 +0,0 @@
-package main
-
-// The internal/skills/{debug,retrospective,review,trainer} packages imported
-// below are also imported by cmd/supervisor. Plan 7 (supervisor retirement)
-// MUST NOT delete these four packages — the routing pod is their second
-// consumer. Plan 7 deletes only internal/skills/{tdd,spec,tier} (the skills
-// that don't route to local), the supervisor binary, and supervisor manifests.
-// See docs/superpowers/specs/2026-05-04-mode-2-routing-pod-design.md (Constraints).
-
-import (
-	"context"
-	"log/slog"
-	"net/http"
-	"os"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/auth"
-	"github.com/mathiasbq/supervisor/internal/config"
-	iexec "github.com/mathiasbq/supervisor/internal/exec"
-	"github.com/mathiasbq/supervisor/internal/githubclient"
-	"github.com/mathiasbq/supervisor/internal/mcp"
-	"github.com/mathiasbq/supervisor/internal/mcpclient"
-	"github.com/mathiasbq/supervisor/internal/registry"
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/mathiasbq/supervisor/internal/skills/debug"
-	"github.com/mathiasbq/supervisor/internal/skills/project"
-	"github.com/mathiasbq/supervisor/internal/skills/retrospective"
-	"github.com/mathiasbq/supervisor/internal/skills/review"
-	"github.com/mathiasbq/supervisor/internal/skills/trainer"
-)
-
-func main() {
-	logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
-	slog.SetDefault(logger)
-
-	cfg, err := config.LoadRouting()
-	if err != nil {
-		logger.Error("config load failed", "err", err)
-		os.Exit(1)
-	}
-
-	configDir := envOr("SUPERVISOR_CONFIG_DIR", "/app/config/supervisor")
-	mustRead := func(path string) string {
-		b, err := os.ReadFile(configDir + "/" + path)
-		if err != nil {
-			logger.Error("read prompt failed", "path", path, "err", err)
-			os.Exit(1)
-		}
-		return string(b)
-	}
-
-	llm := iexec.NewLiteLLM(cfg.LiteLLMBaseURL, cfg.LiteLLMAPIKey, 0)
-
-	router := &routing.Router{
-		Fetcher:       routing.NewFetcher(cfg.BrainURL, "7d", time.Duration(cfg.PassRateTTLSeconds)*time.Second),
-		Logger:        routing.NewLogger(cfg.BrainURL),
-		Policy:        routing.Policy{Floor: cfg.RouteLocalFloor, Ceil: cfg.RouteLocalCeil},
-		FastModel:     cfg.FastModel,
-		ThinkingModel: cfg.ThinkingModel,
-		Complete:      llm.Complete,
-	}
-
-	// Skill packages call CompleteFunc(ctx, model, system, user) — no session_id
-	// or project_root in the signature. Rather than modifying every skill's API
-	// (and inflating Plan 6's blast radius), the routing pod logs every decision
-	// under a fixed session_id "_routing". Operators query
-	// `GET /pass-rate?skill=_routing&window=...` to inspect routing health.
-	const routingSessionID = "_routing"
-	wrap := func(skillName string) routing.CompleteFunc {
-		return func(ctx context.Context, _, system, user string) (string, int64, error) {
-			// The model param is ignored: the router picks the model based on policy.
-			return router.Run(ctx, routing.RunInput{
-				Skill:       skillName,
-				System:      system,
-				User:        user,
-				SessionID:   routingSessionID,
-				ProjectRoot: "",
-			})
-		}
-	}
-
-	reg := registry.New()
-	reg.Register(review.New(review.Config{
-		SkillPrompt:  mustRead("review.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: review.CompleteFunc(wrap("review")),
-	}))
-	reg.Register(debug.New(debug.Config{
-		SkillPrompt:  mustRead("debug.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: debug.CompleteFunc(wrap("debug")),
-	}))
-	reg.Register(retrospective.New(retrospective.Config{
-		SkillPrompt:  mustRead("retrospective.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: retrospective.CompleteFunc(wrap("retrospective")),
-	}))
-	reg.Register(trainer.New(trainer.Config{
-		ReaderPrompt: mustRead("trainer-reader.md"),
-		WriterPrompt: mustRead("trainer-writer.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: trainer.CompleteFunc(wrap("trainer")),
-	}))
-
-	if cfg.GiteaMCPURL != "" {
-		mcpC, err := mcpclient.New(cfg.GiteaMCPURL, cfg.GiteaMCPToken)
-		if err != nil {
-			logger.Error("mcpclient init for project_create — GITEA_MCP_URL is set but GITEA_MCP_TOKEN is empty (check routing-secrets)", "err", err)
-			os.Exit(1)
-		}
-		var ghClient *githubclient.Client
-		if cfg.GitHubPAT != "" {
-			ghClient = githubclient.New(cfg.GitHubPAT)
-		}
-		reg.Register(project.New(project.Config{
-			Client:      mcpC,
-			GitHub:      ghClient,
-			GiteaOwner:  cfg.GiteaOwner,
-			GitHubOwner: cfg.GitHubOwner,
-			GitHubPAT:   cfg.GitHubPAT,
-			InfraRepo:   cfg.InfraRepo,
-		}))
-		logger.Info("project_create registered", "gitea_mcp_url", cfg.GiteaMCPURL,
-			"gitea_owner", cfg.GiteaOwner, "github_owner", cfg.GitHubOwner,
-			"infra_repo", cfg.InfraRepo, "github_pat_set", cfg.GitHubPAT != "")
-	} else {
-		logger.Info("project_create skipped — GITEA_MCP_URL not set")
-	}
-
-	var validator *auth.Validator
-	if dexURL := os.Getenv("DEX_ISSUER_URL"); dexURL != "" {
-		audience := os.Getenv("MCP_AUDIENCE")
-		v, err := auth.NewValidator(dexURL, audience)
-		if err != nil {
-			logger.Error("build jwt validator", "err", err)
-			os.Exit(1)
-		}
-		validator = v
-		logger.Info("jwt auth enabled", "issuer", dexURL)
-	}
-
-	srv := mcp.NewServer(reg, cfg.MCPAuthToken, validator)
-	mux := http.NewServeMux()
-	mux.Handle("/mcp", srv)
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	})
-
-	if dexURL := os.Getenv("DEX_ISSUER_URL"); dexURL != "" {
-		resourceURL := os.Getenv("MCP_RESOURCE_URL")
-		mux.HandleFunc("GET /.well-known/oauth-protected-resource",
-			auth.ProtectedResourceHandler(resourceURL, dexURL))
-	}
-
-	addr := ":" + cfg.Port
-	logger.Info("routing pod starting", "addr", addr,
-		"fast", cfg.FastModel, "thinking", cfg.ThinkingModel,
-		"floor", cfg.RouteLocalFloor, "ceil", cfg.RouteLocalCeil)
-	if err := http.ListenAndServe(addr, mux); err != nil { //nolint:gosec
-		logger.Error("server stopped", "err", err)
-		os.Exit(1)
-	}
-}
-
-func envOr(key, def string) string {
-	if v := os.Getenv(key); v != "" {
-		return v
-	}
-	return def
-}

cmd/routing/main_test.go

@@ -1,135 +0,0 @@
-package main_test
-
-import (
-	"context"
-	"encoding/json"
-	"io"
-	"net"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"os/exec"
-	"strconv"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestRoutingPodEndToEnd boots the binary against fake LiteLLM + brain servers,
-// calls tools/list and one tools/call, and verifies the brain saw a session_log POST.
-func TestRoutingPodEndToEnd(t *testing.T) {
-	if testing.Short() {
-		t.Skip("end-to-end binary boot")
-	}
-
-	var brainHits int
-	llm := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		_ = json.NewEncoder(w).Encode(map[string]any{
-			"choices": []map[string]any{{"message": map[string]any{"role": "assistant", "content": "stub"}}},
-		})
-	}))
-	defer llm.Close()
-
-	brain := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch r.URL.Path {
-		case "/pass-rate":
-			brainHits++
-			_ = json.NewEncoder(w).Encode(map[string]any{"pass_rate": 0.95})
-		case "/mcp":
-			brainHits++
-			_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": map[string]any{}})
-		}
-	}))
-	defer brain.Close()
-
-	port := freePort(t)
-	addr := "127.0.0.1:" + port
-	baseURL := "http://" + addr
-
-	bin := buildRouting(t)
-	cmd := exec.Command(bin)
-	cmd.Env = []string{
-		"ROUTING_PORT=" + port,
-		"LITELLM_BASE_URL=" + llm.URL,
-		"LITELLM_API_KEY=stub",
-		"BRAIN_URL=" + brain.URL,
-		"SUPERVISOR_CONFIG_DIR=../../config/supervisor",
-		"PATH=" + os.Getenv("PATH"),
-		"HOME=" + os.Getenv("HOME"),
-	}
-	require.NoError(t, cmd.Start())
-	t.Cleanup(func() { _ = cmd.Process.Kill() })
-
-	require.NoError(t, waitForPort(t, addr, 30*time.Second))
-
-	resp := mcpCall(t, baseURL+"/mcp", `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
-	assert.Contains(t, resp, `"review"`)
-	assert.Contains(t, resp, `"debug"`)
-	assert.Contains(t, resp, `"retrospective"`)
-	assert.Contains(t, resp, `"trainer"`)
-
-	resp = mcpCall(t, baseURL+"/mcp", `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"review","arguments":{"project_root":"/tmp","files":["README.md"]}}}`)
-	_ = resp // shape varies by skill; we only need a 200
-
-	// Wait briefly for the async session_log to land.
-	deadline := time.Now().Add(2 * time.Second)
-	for time.Now().Before(deadline) && brainHits < 2 {
-		time.Sleep(50 * time.Millisecond)
-	}
-	assert.GreaterOrEqual(t, brainHits, 2, "expected at least one /pass-rate hit and one /mcp session_log hit")
-}
-
-func buildRouting(t *testing.T) string {
-	t.Helper()
-	bin := t.TempDir() + "/routing"
-	out, err := exec.Command("go", "build", "-o", bin, "github.com/mathiasbq/supervisor/cmd/routing").CombinedOutput()
-	require.NoError(t, err, "build failed: %s", out)
-	return bin
-}
-
-func waitForPort(_ *testing.T, addr string, dur time.Duration) error {
-	deadline := time.Now().Add(dur)
-	for time.Now().Before(deadline) {
-		c, err := http.Get("http://" + addr + "/healthz") //nolint:noctx
-		if err == nil {
-			_ = c.Body.Close()
-			return nil
-		}
-		conn, err := http.NewRequest(http.MethodPost, "http://"+addr+"/mcp", strings.NewReader(`{}`))
-		if err == nil {
-			r, err := http.DefaultClient.Do(conn)
-			if err == nil {
-				_ = r.Body.Close()
-				return nil
-			}
-		}
-		time.Sleep(50 * time.Millisecond)
-	}
-	return context.DeadlineExceeded
-}
-
-func mcpCall(t *testing.T, url, body string) string {
-	t.Helper()
-	r, err := http.Post(url, "application/json", strings.NewReader(body)) //nolint:noctx
-	require.NoError(t, err)
-	defer func() { _ = r.Body.Close() }()
-	raw, err := io.ReadAll(r.Body)
-	require.NoError(t, err)
-	return string(raw)
-}
-
-// freePort grabs an OS-assigned TCP port and releases it. There is a small
-// race window before the subprocess re-binds it, but it is acceptable for
-// test isolation against a hardcoded port colliding with another test or
-// stray process.
-func freePort(t *testing.T) string {
-	t.Helper()
-	l, err := net.Listen("tcp", "127.0.0.1:0")
-	require.NoError(t, err)
-	port := l.Addr().(*net.TCPAddr).Port
-	require.NoError(t, l.Close())
-	return strconv.Itoa(port)
-}

config/models.yaml

@@ -1,26 +0,0 @@
-# Model selection — first entry per skill is used.
-# Override per-call by passing model in the MCP tool args.
-# Model names come from LiteLLM /v1/models (host/name format).
-
-default_chain:
-  - iguana/qwen3-coder-next
-
-skills:
-  tdd:
-    chain:
-      - koala/qwen3-coder-30b
-  review:
-    chain:
-      - iguana/devstral
-  debug:
-    chain:
-      - iguana/deepseek-r1-14b
-  spec:
-    chain:
-      - koala/phi4-14b
-  retrospective:
-    chain:
-      - iguana/qwen3-coder-next
-  trainer:
-    chain:
-      - iguana/qwen3-coder-next

docs/runbooks/exercising-pass-rate-traffic.md

@@ -0,0 +1,104 @@
+# Runbook: exercising review/debug traffic to fill the pass-rate dataset
+
+**Why this exists:** the routing pod's local-vs-cloud decision is gated on a
+pass-rate history that only accrues from real `review`/`debug` invocations
+**through the pod**. Until the dataset has data, the fast (local) path never
+activates and the core hypothesis (hyperguild #35) can't be validated. This
+runbook is how you spin that flywheel.
+
+## The one trap
+
+Pass-rate accrues **only** when a skill tool is called via the routing pod's MCP
+endpoint. These look like they should count but **do not**:
+
+- **Crush** — talks to LiteLLM directly, bypasses the pod. No log.
+- **claude.ai web / Claude Desktop without the connector** — no log.
+- **Running the local `code-review` / `debug` skills** (`~/dev/.skills`) inline in
+  a Claude Code session — those are local skills, not the pod's MCP tools. No log.
+
+Only a `tools/call` to the routing pod records a pass/fail.
+
+## Endpoints
+
+| Purpose | URL | Auth |
+|---------|-----|------|
+| Routing MCP (local, Tailscale) | `http://koala:30310/mcp` | Bearer `ROUTING_MCP_TOKEN` |
+| Routing MCP (remote) | `https://routing-mcp.d-ma.be/mcp` | OAuth via `auth.d-ma.be` (audience `claude-ai`) |
+| Pass-rate readout | `http://koala:30330/pass-rate?skill=<name>` | Bearer `BRAIN_MCP_TOKEN` (since hyperguild#149) |
+
+Tools advertised: **`review`**, **`debug`** (the two the #35 gate measures),
+plus `session_log`, `retrospective`, `trainer`.
+
+## Step 1 — connect the routing pod as an MCP server
+
+**Local** (needs the bearer token; keep it out of argv via 1Password):
+
+```bash
+op run --env-file ~/.op-env -- \
+  claude mcp add routing --transport http http://koala:30310/mcp \
+    --header "Authorization: Bearer $ROUTING_MCP_TOKEN"
+```
+
+**Remote** (claude.ai / Claude Desktop): add a custom connector pointing at
+`https://routing-mcp.d-ma.be/mcp`; it completes OAuth against `auth.d-ma.be`,
+no static token.
+
+Verify: a `tools/list` should return `review`, `debug`, `session_log`,
+`retrospective`, `trainer`.
+
+## Step 2 — route real work through it
+
+In normal sessions, invoke the pod's tools instead of reviewing/debugging inline:
+
+- *"Use the **routing** `review` tool on this diff."*
+- *"**debug** this failure through the routing pod."*
+
+Each call logs an outcome to ingestion → `/pass-rate` ticks up.
+
+## Step 3 — how routing actually picks the model
+
+Per `internal/routing/policy.go`:
+
+1. pass-rate `nil` (cold) → **local** fast tier. The router defaults to local
+   from invocation #1, not to cloud — so the fast tier is exercised immediately.
+2. pass-rate `>= 0.90` (floor) → **local**; `< 0.70` (ceil) → **cloud/thinking**;
+   in the `[0.70, 0.90)` band a request-hash bit samples 50/50.
+3. On a local execution error the router falls open to the thinking model for
+   that one call (logged `thinking_fallback`).
+
+So you are not "paying in on cloud" — cold calls already run on the (validated)
+local fast tier **`koala/qwen36-35b-a3b`** (Qwen3.6-35B-A3B MTP, promoted
+2026-06-29, infra `c66a195`, `HYPERGUILD_FAST_MODEL`). Accumulating passes just
+keeps it there once real pass-rate is computed.
+
+> **Instrumentation note (#73, fixed 2026-06-30):** until v0.11.1 the pod logged
+> successes as `"skip"` (not `"pass"`), under `skill:"_routing"`, via an
+> unauthenticated POST that silently 401'd — so `/pass-rate` stayed at zero no
+> matter how much you used it. That's fixed and verified (a real review call now
+> moves `/pass-rate?skill=review` 0→1). If you see traffic not registering,
+> re-check #73's three failure modes first.
+
+## Target & verification
+
+- **50 logged invocations** across `review` + `debug` within the 14-day window.
+  The clock restarts **2026-06-30** (the day instrumentation was verified working;
+  the original 2026-06-26→07-10 window measured broken plumbing) → **kill-date
+  2026-07-14**, ~4 calls/day (1 already logged from the #73 smoke test).
+- Check progress anytime:
+
+  ```bash
+  curl -s "http://koala:30330/pass-rate?skill=review"
+  curl -s "http://koala:30330/pass-rate?skill=debug"
+  ```
+
+- If ~4–5/day isn't realistic alongside Crush, that is **not** a failure — per
+  #35 deliverable #1 it's the signal hyperguild isn't on the work critical path,
+  and the pre-decided **Berget fallback** (`gpt-oss-120b` / `qwen3-32b`) carries
+  the fast tier instead.
+
+## Refs
+
+- hyperguild #35 — the validation issue (data gate = deliverable #1)
+- `docs/multi-model-routing.md` — routing policy
+- brain: `wiki/homelab/hypotheses/qwen36-35b-a3b-fast-model-experiment-2026-05-28.md`
+- infra `c66a195` — qwen36 promotion; `models.yml` / `llama-swap-configmap.yaml`

docs/superpowers/plans/2026-04-22-phase4-attempt-wiring.md

@@ -1051,7 +1051,7 @@ git push
 ```bash
 # Poll until complete (replace RUN_ID with the new run):
 curl -s "https://gitea.d-ma.be/api/v1/repos/mathias/hyperguild/actions/runs?limit=2" \
-  -H "Authorization: token 736a8c36adcc6ecb41fff56e5ae4d0eb3105a670" \
+  -H "Authorization: token <REDACTED-dead-gitea-pat-infra#344>" \
   | python3 -c "import sys,json; [print(r['id'],r['status'],r.get('conclusion','—')) for r in json.load(sys.stdin)['workflow_runs']]"
 ```
 

docs/superpowers/specs/2026-05-03-hyperguild-cli-design.md

@@ -16,7 +16,7 @@ Three needs converge on a single small Go binary:
 
 - [ ] `hyperguild tier` returns the same `tier.Info` that `internal/tier.Detect` produces for the same probe URLs, in < 3 s under all three tier conditions, with both human-readable and `--json` output.
 - [ ] `hyperguild brain query <topic>` returns BM25 results from the brain HTTP REST `/query` endpoint, exit 0 on success and non-zero on transport failure.
-- [ ] `hyperguild brain write <type> <slug>` reads markdown content from stdin, posts to `/write` with the type and slug, and creates `brain/knowledge/<slug>.md`. A round-trip (`hyperguild brain query <slug>` immediately after) finds the entry.
+- [ ] `hyperguild brain write <wing> <hall> <slug>` reads markdown content from stdin, posts to `/write` with wing/hall/filename, and creates `brain/wiki/<wing>/<hall>/<slug>.md`. A round-trip (`hyperguild brain query <slug>` immediately after) finds the entry. (Updated post-ADR-0012/#79: the legacy `<type> <slug>` shape and the `brain/knowledge/` fallback were removed; wing and hall are now required.)
 - [ ] `hyperguild mode <cloud|client-local|sovereign>` writes a parseable JSON file at the target path with the per-mode `mcpServers` entries; `jq -e .mcpServers` succeeds on the output.
 - [ ] All commands print usage on `--help`, exit 2 on unknown flags, exit non-zero on operational errors.
 - [ ] `task check` passes (lint + test + vet) on each task and on the merged branch.
@@ -50,7 +50,7 @@ Three needs converge on a single small Go binary:
 
 - **`brain` subcommand calls the HTTP REST API.** Two nested subcommands:
   - `brain query <topic>` issues `POST /query` with JSON body `{query, limit}` (default `--limit 5`), prints results in human-readable form by default and with `--json` for machine consumption.
-  - `brain write <type> <slug>` reads stdin, posts `POST /write` with JSON body `{type, slug, content}`, prints the resulting path on success.
+  - `brain write <wing> <hall> <slug>` reads stdin, posts `POST /write` with JSON body `{wing, hall, filename, content}`, prints the resulting path on success. (Updated post-ADR-0012/#79: wing and hall are required, replacing the old `<type> <slug>` shape and the `brain/knowledge/` legacy fallback.)
   Rationale: HTTP REST is simpler than MCP framing for a CLI. Per CLAUDE.md, the REST endpoints are documented as the official non-MCP interface.
 
 - **`mode <name>` writes a per-mode `.mcp.json` template.** Defaults to writing `./.mcp.json` (cwd); accepts `--out <path>`. Per-mode bodies:

go.mod

@@ -1,4 +1,4 @@
-module github.com/mathiasbq/supervisor
+module git.d-ma.be/mathias/hyperguild
 
 go 1.26.1
 

ingestion/Dockerfile

@@ -5,6 +5,15 @@ FROM golang:1.26-bookworm AS builder
 ARG VERSION=dev
 WORKDIR /src
 
+# Fetch internal gitea-hosted Go modules (mcp-chassis) without going through
+# proxy.golang.org and without HTTP→HTTPS surprises. The Gitea server returns
+# http:// in its go-import meta tag (config-level limitation), so rewrite to
+# https here and bypass the module proxy + sumdb.
+RUN git config --global url."https://gitea.d-ma.be/".insteadOf "http://gitea.d-ma.be/"
+ENV GOPRIVATE=gitea.d-ma.be
+ENV GOPROXY=direct
+ENV GOSUMDB=off
+
 COPY go.mod go.sum ./
 RUN go mod download
 

ingestion/cmd/frontmatterlint/main.go

@@ -0,0 +1,53 @@
+// Command frontmatterlint reports markdown notes whose YAML frontmatter does
+// not parse, and optionally repairs the ones that only need quoting.
+//
+//	go run ./cmd/frontmatterlint ../../brain          # report
+//	go run ./cmd/frontmatterlint -fix ../../brain     # repair in place
+//
+// Exit codes: 0 clean (or everything repaired), 1 findings remain, 2 the scan
+// itself failed.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/frontmatter"
+)
+
+func main() {
+	fix := flag.Bool("fix", false, "repair files that quoting can rescue, in place")
+	flag.Parse()
+
+	root := "."
+	if flag.NArg() > 0 {
+		root = flag.Arg(0)
+	}
+
+	findings, err := frontmatter.Scan(root, *fix)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "frontmatterlint:", err)
+		os.Exit(2)
+	}
+
+	var unresolved int
+	for _, f := range findings {
+		if f.Repaired {
+			fmt.Printf("repaired  %s\n", f.Path)
+			continue
+		}
+		unresolved++
+		fmt.Printf("BROKEN    %s: %v\n", f.Path, f.Err)
+	}
+
+	if unresolved > 0 {
+		fmt.Fprintf(os.Stderr, "\n%d file(s) with unparseable frontmatter", unresolved)
+		if !*fix {
+			fmt.Fprint(os.Stderr, " — re-run with -fix")
+		}
+		fmt.Fprintln(os.Stderr)
+		os.Exit(1)
+	}
+	fmt.Printf("✓ frontmatter: %d file(s) repaired, none broken\n", len(findings))
+}

ingestion/cmd/server/jwt_validator.go

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
+)
+
+// buildJWTValidator builds the JWT validator for issuer (nil when issuer is
+// empty: JWT auth disabled). Since mcp-chassis v0.7 construction no longer
+// fails when OIDC discovery does (mcp-chassis#4): the issuer resolves lazily,
+// and until it does a JWT is answered 503-and-retry, not 401. That replaces
+// #83's boot-time retry loop (hyperguild#155). An issuer still unresolved at
+// boot is logged, so a misconfigured issuer is visible rather than silent.
+func buildJWTValidator(ctx context.Context, logger *slog.Logger, issuer, audience string) (*chassisauth.JWTValidator, error) {
+	v, err := chassisauth.NewJWTValidator(ctx, issuer, audience)
+	if err != nil {
+		return nil, fmt.Errorf("build jwt validator: %w", err)
+	}
+	if ok, rerr := v.Ready(ctx); !ok {
+		logger.Warn("jwt issuer not resolved at boot; JWTs answer 503 until it is", "issuer", issuer, "err", rerr)
+	}
+	return v, nil
+}

ingestion/cmd/server/jwt_validator_test.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
+)
+
+// fakeIssuer answers OIDC discovery with 502 for the first fail requests, as
+// ingress does while dex is not yet serving on a cold boot (#83), then with a
+// real discovery document and an empty JWKS.
+func fakeIssuer(t *testing.T, fail int32) (*httptest.Server, *atomic.Int32) {
+	t.Helper()
+	var discoveries atomic.Int32
+	mux := http.NewServeMux()
+	var srv *httptest.Server
+	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, _ *http.Request) {
+		if discoveries.Add(1) <= fail {
+			w.WriteHeader(http.StatusBadGateway)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"issuer":"`+srv.URL+`","jwks_uri":"`+srv.URL+`/keys"}`)
+	})
+	mux.HandleFunc("/keys", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"keys":[]}`)
+	})
+	srv = httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv, &discoveries
+}
+
+// #83 retried discovery at boot because chassis v0.2.0 failed construction on
+// a 502. Since chassis v0.7 (mcp-chassis#4) the validator is built anyway and
+// resolves the issuer lazily, so boot no longer waits or exits on it
+// (hyperguild#155). An unresolved issuer is logged at boot.
+func TestBuildJWTValidatorReturnsAValidatorWhileDiscovery502s(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	var buf bytes.Buffer
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.NewTextHandler(&buf, nil)), srv.URL, "brain")
+	require.NoError(t, err)
+	assert.NotNil(t, v)
+	assert.Contains(t, buf.String(), "jwt issuer not resolved at boot")
+}
+
+func TestBuildJWTValidatorLogsNothingAgainstAHealthyIssuer(t *testing.T) {
+	srv, _ := fakeIssuer(t, 0)
+	var buf bytes.Buffer
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.NewTextHandler(&buf, nil)), srv.URL, "brain")
+	require.NoError(t, err)
+	assert.NotNil(t, v)
+	assert.NotContains(t, buf.String(), "not resolved")
+}
+
+func TestBuildJWTValidatorIsNilWithoutAnIssuer(t *testing.T) {
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), "", "brain")
+	require.NoError(t, err)
+	assert.Nil(t, v)
+}
+
+// With the issuer unresolved, a JWT on a REST route answers 503 (retry), not
+// 401: the token may be fine, the server just cannot check it yet.
+func TestBuildMuxAnswers503ToAJWTWhileTheIssuerIsUnresolved(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), srv.URL, "brain")
+	require.NoError(t, err)
+	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	code, _ := do(t, mux, "GET", "/pending", "Bearer aaa.bbb.ccc")
+	assert.Equal(t, http.StatusServiceUnavailable, code)
+}
+
+// PR #183 review: /mcp shares REST's bearer, but only the static token was
+// asserted on it. With the issuer unresolved, a JWT on /mcp answers 503 too,
+// so /mcp's middleware was built with the JWT validator.
+func TestBuildMuxAnswers503ToAJWTOnMCPWhileTheIssuerIsUnresolved(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), srv.URL, "brain")
+	require.NoError(t, err)
+	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	code, _ := do(t, mux, "POST", "/mcp", "Bearer aaa.bbb.ccc")
+	assert.Equal(t, http.StatusServiceUnavailable, code)
+}
+
+// PR #183 review: a 401 on /mcp names the protected-resource metadata in
+// WWW-Authenticate (what the claude.ai OAuth connector discovers from), so
+// /mcp's middleware was built with resourceMetadataURL.
+func TestBuildMuxMCP401CarriesResourceMetadataInWWWAuthenticate(t *testing.T) {
+	const rm = "https://brain.example/.well-known/oauth-protected-resource"
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain", resourceMetadataURL: rm}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/mcp", nil))
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), `resource_metadata="`+rm+`"`)
+}

ingestion/cmd/server/main.go

@@ -8,23 +8,98 @@ import (
 	"net/http"
 	"net/url"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"time"
 
+	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
+
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/auth"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claudewatcher"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/embed"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/gitea"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/graphstore"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/graphsync"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/llm"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/mcp"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/embed"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/oauth"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/reranker"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/symlinkguard"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/watcher"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/webhook"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/rest"
+	"k8s.io/client-go/tools/clientcmd"
 )
 
+// kubeClient builds an in-cluster Kubernetes client (falls back to
+// $KUBECONFIG for local dev/testing against a real cluster).
+func kubeClient() (kubernetes.Interface, error) {
+	if cfg, err := rest.InClusterConfig(); err == nil {
+		return kubernetes.NewForConfig(cfg)
+	}
+	rules := clientcmd.NewDefaultClientConfigLoadingRules()
+	cc := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(rules, &clientcmd.ConfigOverrides{})
+	cfg, err := cc.ClientConfig()
+	if err != nil {
+		return nil, fmt.Errorf("kube config (no in-cluster, no kubeconfig): %w", err)
+	}
+	return kubernetes.NewForConfig(cfg)
+}
+
+// claudeSink converts each claudewatcher.Batch into a raw session dump
+// under brain/archive/claude-sessions/<host>/. Deliberately NOT a wiki
+// note (api.WriteNote / brain/wiki/) — raw full transcripts out-ranked
+// curated ai-sessions summaries in BM25 (177,818 vs 45,335 on the same
+// query) and duplicated content already summarized elsewhere. Kept for
+// deep lookups, never indexed. See ai-sessions#10.
+type claudeSink struct {
+	brainDir string
+	logger   *slog.Logger
+}
+
+func (s *claudeSink) Ingest(ctx context.Context, b claudewatcher.Batch) error {
+	if len(b.Turns) == 0 {
+		return nil
+	}
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "# Claude session %s (%s)\n\n", b.SessionID, b.Host)
+	fmt.Fprintf(&sb, "_Project: `%s`. File: `%s`. Turns: %d._\n\n", b.ProjectID, b.FilePath, len(b.Turns))
+	for _, t := range b.Turns {
+		fmt.Fprintf(&sb, "## %s — %s\n\n", t.Type, t.Timestamp.UTC().Format(time.RFC3339))
+		if t.ToolName != "" {
+			fmt.Fprintf(&sb, "_tool: `%s`_\n\n", t.ToolName)
+		}
+		// Cap per-turn excerpt to keep page size bounded; the full
+		// transcript lives on disk under ~/.claude/projects/ already.
+		content := t.Content
+		if len(content) > 2000 {
+			content = content[:2000] + "…"
+		}
+		sb.WriteString(content)
+		sb.WriteString("\n\n")
+	}
+	slug := "session-" + b.Host + "-" + b.SessionID
+	dest := filepath.Join(s.brainDir, "archive", "claude-sessions", b.Host, slug+".md")
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return fmt.Errorf("create claude-sessions archive dir: %w", err)
+	}
+	if err := os.WriteFile(dest, []byte(sb.String()), 0o644); err != nil {
+		return fmt.Errorf("write claude session archive: %w", err)
+	}
+	s.logger.Debug("claude session archived (non-indexed)", "path", dest)
+	return nil
+}
+
 // redactDSN parses a Postgres URL and replaces its password with `***`
 // for safe inclusion in logs. Falls back to a non-leaking placeholder
 // if parsing fails — we never log a raw DSN.
@@ -69,10 +144,109 @@ func envInt(key string, fallback int) int {
 	return fallback
 }
 
+// buildNotifier returns the ntfy notifier, or a nil interface when
+// BRAIN_NTFY_URL is unset. A nil *interface* (not a typed-nil) is required so
+// DegradingSink/Reconcile and the governance observer skip it cleanly.
+// alertingWarnings names every alert that will not fire under the current
+// configuration (#107).
+//
+// buildNotifier returns a nil interface when BRAIN_NTFY_URL is unset, and every
+// consumer skips a nil notifier silently — right for an unconfigured homelab,
+// wrong for an alert whose entire value is that someone finds out. The cost of
+// the silence is that "configured and working" and "never configured" are
+// byte-identical in behaviour: no error, no warning, only a message that never
+// arrives, which nobody notices because nobody is waiting for an alert they
+// have never seen. Two alerts were dark in production for exactly that reason
+// (#100), found by firing a real event rather than by reading anything.
+//
+// WARN rather than fatal, deliberately. The brain sibling rule
+// (`empty-credential-must-refuse-to-start-not-switch-modes`) says an empty
+// credential must be a startup error, never a silent mode switch — but that is
+// about a control being removed. Here observability is degraded, not a gate
+// bypassed, and refusing to boot would break the unconfigured-homelab case the
+// nil notifier exists to support. What the rule does demand, and what this
+// provides, is that the mode switch stops being silent.
+//
+// Pure and env-injected so the message is testable without a running server:
+// the reason this gap survived is that nothing about it was observable.
+func alertingWarnings(getenv func(string) string) []string {
+	var out []string
+	if getenv("BRAIN_NTFY_URL") == "" {
+		out = append(out, "alerting DISABLED: BRAIN_NTFY_URL unset — "+
+			"brain_edit_root governance rewrites, capture audit degradation and the "+
+			"brain symlink tripwire (hyperguild#157) will not notify")
+	}
+	return out
+}
+
+// buildNotifier returns the ntfy notifier for one alert source, titled so
+// the source is recognisable (hyperguild#163), or nil when ntfy is not
+// configured.
+func buildNotifier(getenv func(string) string, title string) audit.Notifier {
+	if n := audit.NewNtfyNotifier(getenv("BRAIN_NTFY_URL"), getenv("BRAIN_NTFY_TOKEN")); n != nil {
+		return n.WithTitle(title)
+	}
+	return nil
+}
+
+// buildAuditSink selects the capture audit sink. When BRAIN_LOKI_URL is
+// set it builds the classification-aware DegradingSink (loki central +
+// durable file buffer + optional ntfy) and starts the reconcile loop;
+// otherwise it falls back to a plain slog sink. The buffer lives under the
+// brain dir so it survives process restarts.
+func buildAuditSink(ctx context.Context, brainDir string, logger *slog.Logger) capture.AuditSink {
+	lokiURL := os.Getenv("BRAIN_LOKI_URL")
+	central := audit.NewLokiCentral(lokiURL)
+	if central == nil {
+		logger.Info("capture audit: slog sink (BRAIN_LOKI_URL unset)")
+		return audit.NewSlogSink(logger)
+	}
+	buffer, err := audit.NewFileBuffer(filepath.Join(brainDir, ".audit-buffer", "capture.jsonl"))
+	if err != nil {
+		logger.Error("capture audit buffer init", "err", err)
+		os.Exit(1)
+	}
+	notifier := buildNotifier(os.Getenv, "brain-capture audit degraded")
+	reconcileInterval := time.Duration(envInt("BRAIN_AUDIT_RECONCILE_INTERVAL", 60)) * time.Second
+	audit.StartReconcile(ctx, central, buffer, notifier, reconcileInterval)
+	logger.Info("capture audit: loki+buffer sink", "loki", lokiURL, "reconcile_s", int(reconcileInterval.Seconds()))
+	return audit.NewDegradingSink(central, buffer, notifier)
+}
+
+// splitList parses a comma-separated env value into a trimmed,
+// empty-free slice. Used for the capture sovereign-principal allowlist.
+func splitList(v string) []string {
+	var out []string
+	for _, p := range strings.Split(v, ",") {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// systemHostname returns os.Hostname() with a "unknown" fallback so the
+// caller never has to handle the rare error path.
+func systemHostname() string {
+	h, err := os.Hostname()
+	if err != nil || h == "" {
+		return "unknown"
+	}
+	return h
+}
+
 func main() {
 	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
 
+	for _, w := range alertingWarnings(os.Getenv) {
+		logger.Warn(w)
+	}
+
 	brainDir := envOr("INGEST_BRAIN_DIR", "../brain")
+	if err := startupSymlinkCheck(brainDir); err != nil {
+		logger.Error("brain symlink tripwire", "err", err)
+		os.Exit(1)
+	}
 	port := envOr("INGEST_PORT", "3300")
 
 	llmURL := envOr("INGEST_LLM_URL", "http://iguana:4000/v1")
@@ -105,6 +279,11 @@ func main() {
 			fallbackModel := envOr("BRAIN_LLM_FALLBACK_MODEL", "gemma4:31b")
 			router.Fallback = llm.New(fallbackURL, "", fallbackModel, timeout)
 		}
+		if tertiaryURL := os.Getenv("BRAIN_LLM_TERTIARY_URL"); tertiaryURL != "" {
+			tertiaryModel := envOr("BRAIN_LLM_TERTIARY_MODEL", "gemini-2.5-flash")
+			tertiaryKey := os.Getenv("GEMINI_API_KEY")
+			router.Tertiary = llm.New(tertiaryURL, tertiaryKey, tertiaryModel, timeout)
+		}
 		answerComplete = router.Complete
 		logger.Info("brain answer LLM configured", "primary", primaryURL, "model", primaryModel)
 	}
@@ -116,6 +295,15 @@ func main() {
 		logger.Info("brain reranker configured", "url", rerankURL, "model", rerankModel)
 	}
 
+	// Gitea ticket tracker for the capture capability (#52). Token via env
+	// only — never logged or in argv. Both vars must be set to enable it;
+	// gitea.New returns nil otherwise, leaving ticket integration off.
+	giteaURL := envOr("BRAIN_GITEA_URL", "https://git.d-ma.be")
+	if tracker := gitea.New(giteaURL, os.Getenv("BRAIN_GITEA_TOKEN")); tracker != nil {
+		mcpSrv = mcpSrv.WithIssueTracker(tracker)
+		logger.Info("brain gitea tracker configured", "url", giteaURL)
+	}
+
 	// Hybrid retrieval (pgvector + nomic-embed-text). Both env vars must
 	// be set together for the path to wire on; otherwise BM25-only.
 	var vectorStore *vectorstore.PGStore
@@ -140,6 +328,32 @@ func main() {
 		logger.Info("brain hybrid retrieval enabled",
 			"pg", redactDSN(pgDSN),
 			"embed_url", embedURL, "embed_model", embedModel)
+
+		// Graph store shares the same postgres18 DSN as the vector
+		// store and is opt-in via BRAIN_GRAPH_ENABLED=true. Defaults
+		// to off so first rollout doesn't surprise — flip on after
+		// the migration completes and the backfill finishes.
+		if envOr("BRAIN_GRAPH_ENABLED", "false") == "true" {
+			gstore, gerr := graphstore.New(context.Background(), pgDSN)
+			if gerr != nil {
+				logger.Error("graph store init", "err", gerr)
+				os.Exit(1)
+			}
+			if gerr := gstore.Init(context.Background()); gerr != nil {
+				logger.Error("graph store migrate", "err", gerr)
+				os.Exit(1)
+			}
+			mcpSrv = mcpSrv.WithGraph(gstore)
+			if envOr("BRAIN_GRAPH_BACKFILL", "false") == "true" {
+				n, berr := graphsync.BackfillFromBrainDir(context.Background(), gstore, brainDir)
+				if berr != nil {
+					logger.Warn("graph backfill incomplete", "indexed", n, "err", berr)
+				} else {
+					logger.Info("graph backfill complete", "indexed", n)
+				}
+			}
+			logger.Info("brain graph enabled", "pg", redactDSN(pgDSN))
+		}
 	case pgDSN == "" && embedURL == "":
 		// disabled — fine
 	default:
@@ -154,6 +368,26 @@ func main() {
 	}
 
 	ctx := context.Background()
+	// hyperguild#157: report a symlink that appears in the brain while running.
+	go symlinkguard.Watch(ctx, brainDir, symlinkScanInterval(os.Getenv), buildNotifier(os.Getenv, "brain symlink tripwire"))
+
+	// Never fatal on an unreachable issuer (#83): on a cold cluster boot this
+	// pod can beat dex to serving and get a 502 from ingress, and exiting meant
+	// CrashLoopBackOff redoing the backfill. Since mcp-chassis v0.7 the
+	// validator resolves the issuer lazily and answers JWTs 503-and-retry until
+	// it does (hyperguild#155), so no boot retry is needed. A misconfigured
+	// issuer no longer exits the process: it is logged at boot and every JWT
+	// gets 503; the static bearer keeps working.
+	jwtValidator, err := buildJWTValidator(ctx, logger,
+		os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"))
+	if err != nil {
+		logger.Error("build jwt validator", "err", err)
+		os.Exit(1)
+	}
+	if jwtValidator != nil {
+		logger.Info("jwt auth enabled", "issuer", os.Getenv("DEX_ISSUER_URL"))
+	}
+
 	if watchInterval > 0 {
 		watcher.Start(ctx, watcher.Config{
 			BrainDir: brainDir,
@@ -161,6 +395,103 @@ func main() {
 			Pipeline: pipelineCfg,
 		})
 	}
+
+	// Claude Code session ingestion (hyperguild#27 / infra#73 Track E.1).
+	// Off by default — explicitly opt in by setting CLAUDE_SESSIONS_DIR
+	// to the ~/.claude/projects path. Requires BRAIN_PG_DSN for the
+	// cursor table (resumable offsets across restarts).
+	if claudeDir := os.Getenv("CLAUDE_SESSIONS_DIR"); claudeDir != "" {
+		if pgDSN == "" {
+			logger.Error("CLAUDE_SESSIONS_DIR set but BRAIN_PG_DSN missing — claudewatcher needs the cursor table")
+			os.Exit(1)
+		}
+		// Client-name guard. The env value is a regex alternation
+		// (e.g. "SEB|Mastercard"); we wrap it with word boundaries
+		// and case-insensitive flag so substrings inside longer
+		// identifiers don't false-match. Sourced from a SOPS secret
+		// so client identities never live in source.
+		if clientBlock := os.Getenv("CLAUDE_INGEST_CLIENT_BLOCK"); clientBlock != "" {
+			pattern := `(?i)\b(` + clientBlock + `)\b`
+			if err := claudewatcher.RegisterRule("client-name", pattern); err != nil {
+				logger.Error("claudewatcher client-block rule invalid", "err", err)
+				os.Exit(1)
+			}
+			logger.Info("claudewatcher client-block guard registered")
+		}
+		cursorStore, cerr := claudewatcher.NewCursorStore(ctx, pgDSN)
+		if cerr != nil {
+			logger.Error("claudewatcher cursor init", "err", cerr)
+			os.Exit(1)
+		}
+		if cerr := cursorStore.Init(ctx); cerr != nil {
+			logger.Error("claudewatcher cursor migrate", "err", cerr)
+			os.Exit(1)
+		}
+		host := envOr("CLAUDE_INGEST_HOST", systemHostname())
+		interval := time.Duration(envInt("CLAUDE_INGEST_INTERVAL", 60)) * time.Second
+
+		// Project directories excluded from ingestion entirely, as globs
+		// against the project directory name — e.g.
+		// "*cobalt-dingo*,*claude-worktrees-bridge-cse*".
+		//
+		// This is a veto list, deliberately named as one. It complements the
+		// client-name scrubber rather than replacing it: the scrubber drops
+		// individual TURNS whose content matches, while this never opens a
+		// project's files at all. Sessions working on live company financials
+		// are excluded here because their content is confidential in ways no
+		// pattern reliably recognises, and their learnings are captured
+		// deliberately through the session-close ritual instead.
+		//
+		// Caveat worth knowing: a project directory is derived from the
+		// session's WORKING DIRECTORY, not from the repositories it touches.
+		// A session run from ~/dev that happens to read a skipped repo will
+		// NOT be excluded by this. The scrubber remains the control for
+		// content; this is a control for whole workspaces.
+		skipProjects := splitList(os.Getenv("CLAUDE_INGEST_SKIP_PROJECTS"))
+		if len(skipProjects) > 0 {
+			logger.Info("claudewatcher: projects excluded from ingestion", "patterns", skipProjects)
+		}
+
+		sink := &claudeSink{brainDir: brainDir, logger: logger}
+		go func() {
+			if err := claudewatcher.Watch(ctx, claudewatcher.Config{
+				SessionsDir:  claudeDir,
+				Host:         host,
+				Interval:     interval,
+				Sink:         sink,
+				Cursors:      cursorStore,
+				Logger:       logger,
+				SkipProjects: skipProjects,
+			}); err != nil && err != context.Canceled {
+				logger.Error("claudewatcher exited", "err", err)
+			}
+		}()
+		logger.Info("claudewatcher started",
+			"sessions_dir", claudeDir, "host", host, "interval", interval)
+	}
+
+	// Gitea push webhook -> on-demand brain-sync Job, instead of waiting up
+	// to 15 minutes for the next CronJob poll. Off by default (opt in via
+	// GITEA_WEBHOOK_SECRET) since it needs Job-create RBAC in the "brain"
+	// namespace that a fresh deploy won't have granted yet.
+	var webhookHandler *webhook.Handler
+	if webhookSecret := os.Getenv("GITEA_WEBHOOK_SECRET"); webhookSecret != "" {
+		kc, err := kubeClient()
+		if err != nil {
+			logger.Error("brain-sync webhook: kube client", "err", err)
+			os.Exit(1)
+		}
+		webhookHandler = &webhook.Handler{
+			Secret:      webhookSecret,
+			Clientset:   kc,
+			Namespace:   envOr("BRAIN_SYNC_NAMESPACE", "brain"),
+			CronJobName: envOr("BRAIN_SYNC_CRONJOB", "brain-sync"),
+			WatchRepo:   envOr("BRAIN_SYNC_WATCH_REPO", "mathias/brain"),
+			Logger:      logger,
+		}
+		logger.Info("brain-sync webhook enabled", "namespace", webhookHandler.Namespace, "cronjob", webhookHandler.CronJobName)
+	}
+
 	if vectorStore != nil {
 		embedSyncInterval := envInt("BRAIN_EMBED_SYNC_INTERVAL", 300)
 		vectorstore.StartSync(ctx, brainDir, vectorStore,
@@ -170,42 +501,60 @@ func main() {
 		logger.Info("embed sync started", "interval_s", embedSyncInterval)
 	}
 
-	mux := http.NewServeMux()
-	mux.HandleFunc("POST /query", h.Query)
-	mux.HandleFunc("POST /write", h.Write)
-	mux.HandleFunc("POST /index", h.Index)
-	mux.HandleFunc("POST /ingest", h.Ingest)
-	mux.HandleFunc("POST /ingest-path", h.IngestPath)
-	mux.HandleFunc("POST /ingest-raw", h.IngestRaw)
-	mux.HandleFunc("POST /backfill-refs", h.BackfillRefs)
-	mux.HandleFunc("POST /backfill-embeddings", h.BackfillEmbeddings)
-	mux.HandleFunc("GET /pass-rate", h.PassRate)
-	var jwtValidator *auth.Validator
-	if dexURL := os.Getenv("DEX_ISSUER_URL"); dexURL != "" {
-		audience := os.Getenv("MCP_AUDIENCE")
-		v, err := auth.NewValidator(dexURL, audience)
-		if err != nil {
-			logger.Error("build jwt validator", "err", err)
-			os.Exit(1)
+	// Public routes only; buildMux mounts the authenticated REST API (#149).
+	public := map[string]http.Handler{}
+	if webhookHandler != nil {
+		public["POST /webhooks/brain-sync"] = webhookHandler
 	}
-		jwtValidator = v
-		logger.Info("jwt auth enabled", "issuer", dexURL)
-	}
-
 	// Resource-metadata URL is only emitted on 401 when Dex OAuth is
 	// configured. Static-Bearer-only deployments leave this empty so
 	// clients never see an OAuth challenge.
 	var resourceMetadataURL string
 	if dexURL := os.Getenv("DEX_ISSUER_URL"); dexURL != "" {
 		resourceURL := os.Getenv("MCP_RESOURCE_URL")
-		mux.HandleFunc("GET /.well-known/oauth-protected-resource",
-			auth.ProtectedResourceHandler(resourceURL, dexURL))
+		public["GET /.well-known/oauth-protected-resource"] = http.HandlerFunc(
+			chassisauth.ProtectedResourceHandler(resourceURL, dexURL))
 		if resourceURL != "" {
 			resourceMetadataURL = strings.TrimRight(resourceURL, "/") + "/.well-known/oauth-protected-resource"
 		}
 	}
 
-	mux.Handle("/mcp", mcp.BearerAuth(mcpToken, jwtValidator, resourceMetadataURL, mcpSrv))
+	// POST /capture (#53/#54): the uniform capture REST door. Needs a ticket
+	// tracker to file action items, so it only mounts when Gitea is
+	// configured. It reuses the MCP server's graph-wired brain store (one
+	// implementation), the classification tags for the I1 gate, and a
+	// classification-aware audit sink (loki + durable buffer + ntfy when
+	// BRAIN_LOKI_URL is set, else a plain slog sink). The handler does its
+	// own auth (static + JWT) because it needs the principal to derive the
+	// trust-zone origin — the chassis middleware hides it.
+	if tracker := mcpSrv.IssueTracker(); tracker != nil {
+		classCfg, cerr := classification.Load(brainDir)
+		if cerr != nil {
+			logger.Error("load classification config", "err", cerr)
+			os.Exit(1)
+		}
+		auditSink := buildAuditSink(ctx, brainDir, logger)
+		captureSvc := capture.NewService(
+			mcpSrv.BrainStore(), tracker, classCfg, auditSink)
+		sovereign := splitList(os.Getenv("BRAIN_CAPTURE_SOVEREIGN_PRINCIPALS"))
+		resolver := capturehttp.NewOriginResolver(sovereign)
+		captureH := capturehttp.New(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
+		public["POST /capture"] = captureH
+		// Same use-case behind the MCP `capture` tool (#55 relay) so MCP-native
+		// harnesses (claude.ai, Crush, Pi, LLM Council) reach capture through
+		// the existing /mcp OAuth connector. buildMux wraps this same mcpSrv;
+		// WithCapture mutates the same instance, so the tool appears live.
+		mcpSrv.WithCapture(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
+		// hyperguild#97: a governance-file rewrite gets the same trail a
+		// capture already gets, plus an out-of-band alert. Wired here because
+		// brain_edit_root needs the capture plumbing anyway — that is what
+		// re-derives the static principal its gate checks.
+		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier(os.Getenv, "brain governance edit"))
+		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign),
+			"governance_observer", true)
+	} else {
+		logger.Info("capture endpoint disabled (BRAIN_GITEA_TOKEN unset)")
+	}
 
 	// Opt-in OAuth 2.0 client_credentials flow for claude.ai's custom-MCP
 	// integration UI, which has no static-Bearer field. Setting both
@@ -220,9 +569,9 @@ func main() {
 			logger.Error("OAUTH_CLIENT_ID/SECRET set but MCP_RESOURCE_URL is empty; cannot derive issuer")
 			os.Exit(1)
 		}
-		mux.HandleFunc("GET /.well-known/oauth-authorization-server",
+		public["GET /.well-known/oauth-authorization-server"] = http.HandlerFunc(
 			oauth.MetadataHandler(issuer))
-		mux.HandleFunc("POST /oauth/token", oauth.TokenHandler(oauth.TokenConfig{
+		public["POST /oauth/token"] = http.HandlerFunc(oauth.TokenHandler(oauth.TokenConfig{
 			ClientID:     oauthID,
 			ClientSecret: oauthSecret,
 			AccessToken:  mcpToken,
@@ -235,6 +584,24 @@ func main() {
 		os.Exit(1)
 	}
 
+	// /metrics — unauthenticated Prometheus endpoint, scraped via the
+	// ServiceMonitor in k3s/apps/supervisor/. buildMux registers it and wraps
+	// the whole router in the registry's middleware.
+	//
+	// The whole router, /mcp's bearer included, is built in buildMux so its
+	// tests are tests of production wiring (PR #152 review, hyperguild#154).
+	// The REST API's credential is the same as /mcp's. Untested here: the
+	// restAuth fields and the public map this call passes in (e.g. a nil
+	// validator would drop JWT auth on /mcp and REST and the suite stays
+	// green), and ListenAndServe serving the result unchanged (hyperguild#182).
+	handler, err := buildMux(restAuth{token: mcpToken, validator: jwtValidator, realm: "brain",
+		resourceMetadataURL: resourceMetadataURL}, h, mcpSrv, metrics.New(), public)
+	if err != nil {
+		logger.Error("build router", "err", err)
+		os.Exit(1)
+	}
+	logger.Info("metrics endpoint registered", "path", "/metrics")
+
 	addr := ":" + port
 	watchIntervalLog := "disabled"
 	if watchInterval > 0 {
@@ -249,7 +616,7 @@ func main() {
 		"watch_interval", watchIntervalLog,
 		"mcp_enabled", true,
 	)
-	if err := http.ListenAndServe(addr, mux); err != nil {
+	if err := http.ListenAndServe(addr, handler); err != nil {
 		logger.Error("server stopped", "err", err)
 		os.Exit(1)
 	}

ingestion/cmd/server/main_test.go

@@ -0,0 +1,78 @@
+// ingestion/cmd/server/main_test.go
+package main
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claudewatcher"
+)
+
+func TestClaudeSink_IngestWritesToNonIndexedArchiveNotWiki(t *testing.T) {
+	dir := t.TempDir()
+	sink := &claudeSink{brainDir: dir, logger: slog.New(slog.NewTextHandler(os.Stderr, nil))}
+
+	err := sink.Ingest(context.Background(), claudewatcher.Batch{
+		Host:      "koala",
+		FilePath:  "/host-home-claude/projects/-home-mathias-dev/abc.jsonl",
+		SessionID: "abc",
+		ProjectID: "-home-mathias-dev",
+		Turns: []claudewatcher.Turn{
+			{Type: "assistant", Content: "did a thing"},
+		},
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, "archive", "claude-sessions", "koala", "session-koala-abc.md"))
+	require.NoError(t, err, "raw session dump must land in the non-indexed archive")
+	assert.Contains(t, string(got), "did a thing")
+
+	_, err = os.Stat(filepath.Join(dir, "wiki", "claude-sessions"))
+	assert.True(t, os.IsNotExist(err), "raw transcripts must never land under wiki/ (ai-sessions#10 — BM25 pollution)")
+}
+
+// --- #107: an unconfigured alert must announce itself ----------------------
+
+func TestAlertingWarnings(t *testing.T) {
+	tests := []struct {
+		name string
+		env  map[string]string
+		want []string // substrings that must appear across the warnings
+		none bool     // true = expect no warnings at all
+	}{
+		{
+			// The failure this exists to prevent: two alerts dark in
+			// production, discovered only by firing a real event and watching
+			// nothing arrive (#100).
+			name: "notifier unconfigured names what will not fire",
+			env:  map[string]string{},
+			want: []string{"BRAIN_NTFY_URL", "brain_edit_root", "audit"},
+		},
+		{
+			name: "configured notifier is silent",
+			env:  map[string]string{"BRAIN_NTFY_URL": "http://ntfy/brain-alerts"},
+			none: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := alertingWarnings(func(k string) string { return tt.env[k] })
+			if tt.none {
+				assert.Empty(t, got)
+				return
+			}
+			joined := strings.Join(got, " ")
+			for _, w := range tt.want {
+				assert.Contains(t, joined, w)
+			}
+		})
+	}
+}

ingestion/cmd/server/routes.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
+)
+
+// publicRoutes is the complete set of patterns a caller may register on the
+// outer mux, outside the REST API's auth (hyperguild#149). Each authenticates
+// itself or is meant to be open: /capture (bearer/JWT), the webhook (HMAC),
+// /oauth/token (client secret) and OAuth metadata (open). /mcp and /metrics
+// are not here: buildMux builds them itself (hyperguild#154). A REST pattern
+// added here would beat the authenticated catch-all by specificity and ship
+// open, which is why buildMux refuses anything else.
+var publicRoutes = map[string]bool{
+	"POST /capture":             true,
+	"POST /webhooks/brain-sync": true,
+	"GET /.well-known/oauth-protected-resource":   true,
+	"GET /.well-known/oauth-authorization-server": true,
+	"POST /oauth/token":                           true,
+}
+
+// restAuth is the credential the REST API checks: the same as /mcp's.
+type restAuth struct {
+	token               string
+	validator           *chassisauth.JWTValidator
+	realm               string
+	resourceMetadataURL string
+}
+
+// buildMux builds the handler main passes to ListenAndServe unchanged. The
+// REST API is mounted at "/" and /mcp is registered, both behind bearer auth
+// that buildMux constructs itself from auth (one credential), so a caller
+// cannot pass a no-op. GET /metrics serves reg, and the whole router is
+// wrapped in reg's middleware. Other public handlers are registered as given,
+// and only for patterns on the publicRoutes allowlist. It returns an
+// http.Handler, not the *ServeMux, so nothing can register a route on the
+// result. What stays untested is main's call site: the restAuth fields and
+// the public map main passes in, and ListenAndServe serving this handler
+// unchanged (hyperguild#182). The tests build their own arguments.
+func buildMux(
+	auth restAuth, h *api.Handler, mcpHandler http.Handler, reg *metrics.Registry, public map[string]http.Handler,
+) (http.Handler, error) {
+	if auth.token == "" {
+		return nil, errors.New("buildMux: REST auth needs a token")
+	}
+	if mcpHandler == nil || reg == nil {
+		return nil, errors.New("buildMux: needs the MCP handler and the metrics registry")
+	}
+	mux := http.NewServeMux()
+	for pattern, handler := range public {
+		if !publicRoutes[pattern] {
+			return nil, fmt.Errorf("buildMux: %q is not an allowed public route", pattern)
+		}
+		mux.Handle(pattern, handler)
+	}
+	bearer := func(next http.Handler) http.Handler {
+		return chassisauth.BearerMiddleware(auth.token, auth.validator, auth.realm, auth.resourceMetadataURL, next)
+	}
+	mux.Handle("/mcp", bearer(mcpHandler))
+	// /metrics is registered on the mux and so observed by its own
+	// middleware, like any route.
+	mux.Handle("GET /metrics", reg.Handler())
+	mountREST(mux, h, bearer)
+	return reg.Middleware(mux), nil
+}
+
+// mountREST registers the REST API on its own mux and mounts it at "/" behind
+// auth: anything not registered as public lands here and is authenticated,
+// including routes added later.
+func mountREST(mux *http.ServeMux, h *api.Handler, auth func(http.Handler) http.Handler) {
+	rest := http.NewServeMux()
+	rest.HandleFunc("POST /query", h.Query)
+	rest.HandleFunc("POST /write", h.Write)
+	rest.HandleFunc("POST /index", h.Index)
+	rest.HandleFunc("POST /ingest", h.Ingest)
+	rest.HandleFunc("POST /ingest-path", h.IngestPath)
+	rest.HandleFunc("POST /ingest-raw", h.IngestRaw)
+	rest.HandleFunc("POST /backfill-refs", h.BackfillRefs)
+	rest.HandleFunc("GET /pending", h.Pending)
+	rest.HandleFunc("POST /promote", h.Promote)
+	rest.HandleFunc("POST /backfill-embeddings", h.BackfillEmbeddings)
+	rest.HandleFunc("GET /pass-rate", h.PassRate)
+	mux.Handle("/", labelRESTPattern(rest, auth(rest)))
+}
+
+// labelRESTPattern sets the request's Pattern to the REST route it addresses
+// before auth runs, so the metrics middleware (which reads Pattern from the
+// same *http.Request) labels a refused request by its route rather than by
+// the "/" mount (hyperguild#155). A refused request to a path no route
+// matches keeps "/", so for refused requests the label set stays bounded by
+// the registered routes. That bound does not hold for authenticated
+// requests: an unregistered path reaches the REST mux, which 404s with an
+// empty Pattern, and the metrics middleware falls back to the raw URL path
+// (hyperguild#185).
+func labelRESTPattern(rest *http.ServeMux, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, pattern := rest.Handler(r); pattern != "" {
+			r.Pattern = pattern
+		}
+		next.ServeHTTP(w, r)
+	})
+}

ingestion/cmd/server/routes_observability_test.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"bytes"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// wrongTokSentinel is a presented credential distinctive enough that any
+// occurrence in a log line is the raw token, not a coincidence.
+const wrongTokSentinel = "wrong-tok-sentinel-q7zx"
+
+// hyperguild#155: since #149 every REST route sits behind BearerMiddleware,
+// and chassis v0.2.0 refused without logging, so an unknown caller got
+// silent 401s. The chassis now writes an `mcp auth rejected` line, and the
+// presented token appears nowhere in the log as a bare value (PR #181
+// review: asserting on the "Bearer " header form could never fail, since
+// the chassis logs fields, not headers).
+func TestBuildMuxRejectionLogLineOmitsTheBarePresentedToken(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	code, _ := do(t, testMux(t), "POST", "/query", "Bearer "+wrongTokSentinel)
+	require.Equal(t, http.StatusUnauthorized, code)
+	assert.Contains(t, buf.String(), "mcp auth rejected")
+	assert.Contains(t, buf.String(), "path=/query")
+	assert.NotContains(t, buf.String(), wrongTokSentinel, "the rejected token is logged as a bare value")
+	assert.NotContains(t, buf.String(), routesTok, "the valid static token is logged")
+}
+
+// The `mcp auth accepted` line leaves out the valid static token.
+func TestBuildMuxAcceptedLogLineOmitsTheBareStaticToken(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	code, _ := do(t, testMux(t), "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+	assert.Contains(t, buf.String(), "mcp auth accepted")
+	assert.NotContains(t, buf.String(), routesTok, "the accepted static token is logged as a bare value")
+}
+
+// An authenticated REST request is labelled with the REST mux's pattern:
+// the inner mux sets it on the same *http.Request the outer middleware reads.
+func TestMetricsLabelAnAuthenticatedRESTRequestWithItsRoutePattern(t *testing.T) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="GET /pending"`)
+	assert.NotContains(t, rec.Body.String(), `path="/"`)
+}
+
+// hyperguild#155: a request refused by REST auth never reaches the REST mux,
+// so it was labelled path="/" and a 4xx on /query could not be told from one
+// on /write. It is now labelled with the REST pattern it was addressed to.
+func TestMetricsLabelARejectedRESTRequestWithItsRoutePattern(t *testing.T) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/query", "")
+	require.Equal(t, http.StatusUnauthorized, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="POST /query",status="4xx"`)
+}
+
+// A path no REST route matches keeps the catch-all label, so an attacker
+// probing random URLs cannot grow the series set.
+func TestMetricsLabelARejectedUnknownPathWithTheCatchAll(t *testing.T) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/no-such-route-zq", "")
+	require.Equal(t, http.StatusUnauthorized, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="/",status="4xx"`)
+	assert.NotContains(t, rec.Body.String(), "no-such-route-zq")
+}

ingestion/cmd/server/routes_test.go

@@ -0,0 +1,161 @@
+package main
+
+import (
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
+)
+
+const routesTok = "routes-test-token"
+
+func okHandler(body string) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(body)) })
+}
+
+// testMux builds the router through buildMux, the function main calls, with
+// every allowlisted public pattern (stub handlers), a stub MCP server and a
+// static token only: no JWT validator and no resourceMetadataURL (the tests
+// in jwt_validator_test.go pass those). It does not use main's own restAuth
+// or public map (hyperguild#182). hyperguild#149: the REST API is
+// authenticated as a whole; the PR #152 review showed a test of a COPY of
+// the router let main.go regress unseen.
+func testMux(t *testing.T) http.Handler {
+	t.Helper()
+	mux, _ := testMuxAndRegistry(t)
+	return mux
+}
+
+func testMuxAndRegistry(t *testing.T) (http.Handler, *metrics.Registry) {
+	t.Helper()
+	public := map[string]http.Handler{}
+	for p := range publicRoutes {
+		public[p] = okHandler("public " + p)
+	}
+	reg := metrics.New()
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, testHandler(t), okHandler("mcp"), reg, public)
+	require.NoError(t, err)
+	return mux, reg
+}
+
+func testHandler(t *testing.T) *api.Handler {
+	t.Helper()
+	return api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
+}
+
+func do(t *testing.T, h http.Handler, method, path, authz string) (int, string) {
+	t.Helper()
+	req := httptest.NewRequest(method, path, strings.NewReader(`{"query":"x"}`))
+	if authz != "" {
+		req.Header.Set("Authorization", authz)
+	}
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	return rec.Code, rec.Body.String()
+}
+
+func TestBuildMuxRefusesRESTRoutesWithoutAValidToken(t *testing.T) {
+	r := testMux(t)
+	for _, rt := range []struct{ method, path string }{
+		{"POST", "/query"}, {"POST", "/write"}, {"POST", "/index"}, {"POST", "/ingest"},
+		{"POST", "/ingest-path"}, {"POST", "/ingest-raw"}, {"POST", "/backfill-refs"},
+		{"GET", "/pending"}, {"POST", "/promote"}, {"POST", "/backfill-embeddings"}, {"GET", "/pass-rate"},
+	} {
+		code, _ := do(t, r, rt.method, rt.path, "")
+		assert.Equal(t, http.StatusUnauthorized, code, "%s %s without a token", rt.method, rt.path)
+		code, _ = do(t, r, rt.method, rt.path, "Bearer wrong")
+		assert.Equal(t, http.StatusUnauthorized, code, "%s %s with a wrong token", rt.method, rt.path)
+	}
+}
+
+func TestBuildMuxServesRESTRoutesToAValidToken(t *testing.T) {
+	r := testMux(t)
+	code, _ := do(t, r, "GET", "/pending", "Bearer "+routesTok)
+	assert.Equal(t, http.StatusOK, code)
+}
+
+func TestBuildMuxAuthenticatesAnUnregisteredPath(t *testing.T) {
+	code, _ := do(t, testMux(t), "POST", "/some-future-route", "")
+	assert.Equal(t, http.StatusUnauthorized, code)
+}
+
+// buildMux registers public handlers as given, without adding auth: each
+// public route owns its own (bearer/JWT on /capture, HMAC on the webhook,
+// client secret on /oauth/token) or is meant to be open (OAuth metadata).
+// /mcp and /metrics are not public routes: buildMux builds them itself.
+func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
+	r := testMux(t)
+	for p := range publicRoutes {
+		method, path, ok := strings.Cut(p, " ")
+		if !ok {
+			method, path = "GET", p
+		}
+		code, body := do(t, r, method, path, "")
+		assert.Equal(t, http.StatusOK, code, p)
+		assert.Equal(t, "public "+p, body, p)
+	}
+}
+
+// The allowlist is the control: a REST pattern registered as public would win
+// over the authenticated catch-all (more specific pattern), so it is refused.
+func TestBuildMuxRefusesAPublicPatternOffTheAllowlist(t *testing.T) {
+	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
+	// "/mcp" and "GET /metrics" are built by buildMux itself (hyperguild#154):
+	// passing either as public would register them unauthenticated or twice.
+	for _, p := range []string{"POST /query", "GET /pending", "/", "POST /metrics", "/mcp", "GET /metrics"} {
+		_, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, okHandler("mcp"), metrics.New(),
+			map[string]http.Handler{p: okHandler("x")})
+		assert.Error(t, err, "public pattern %q must be refused", p)
+	}
+}
+
+func TestBuildMuxRefusesAnEmptyToken(t *testing.T) {
+	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
+	_, err := buildMux(restAuth{token: "", realm: "brain"}, h, okHandler("mcp"), metrics.New(), nil)
+	assert.Error(t, err)
+}
+
+// hyperguild#154: /mcp's bearer was built in main.go, untested; the buildMux
+// tests used stubs. buildMux now wraps the MCP handler itself, with the same
+// credential as the REST API.
+func TestBuildMuxRefusesMCPWithoutAValidToken(t *testing.T) {
+	r := testMux(t)
+	for _, authz := range []string{"", "Bearer wrong"} {
+		code, body := do(t, r, "POST", "/mcp", authz)
+		assert.Equal(t, http.StatusUnauthorized, code, "authz %q", authz)
+		assert.NotEqual(t, "mcp", body)
+	}
+	code, body := do(t, r, "POST", "/mcp", "Bearer "+routesTok)
+	assert.Equal(t, http.StatusOK, code)
+	assert.Equal(t, "mcp", body)
+}
+
+func TestBuildMuxRefusesANilMCPHandlerOrRegistry(t *testing.T) {
+	auth := restAuth{token: routesTok, realm: "brain"}
+	_, err := buildMux(auth, testHandler(t), nil, metrics.New(), nil)
+	assert.Error(t, err)
+	_, err = buildMux(auth, testHandler(t), okHandler("mcp"), nil, nil)
+	assert.Error(t, err)
+}
+
+// hyperguild#154: main wrapped buildMux's result in the metrics middleware
+// before ListenAndServe, untested. buildMux now returns the handler main
+// serves as-is, metrics included: a request through it is observed and
+// exposed on its own GET /metrics.
+func TestBuildMuxObservesRequestsAndServesMetrics(t *testing.T) {
+	r := testMux(t)
+	code, _ := do(t, r, "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+	code, body := do(t, r, "GET", "/metrics", "")
+	require.Equal(t, http.StatusOK, code)
+	assert.Contains(t, body, `path="GET /pending"`)
+}

ingestion/cmd/server/symlink_check.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/symlinkguard"
+)
+
+// startupSymlinkCheck is the hyperguild#157 tripwire at boot: a symlink in the
+// brain dir would let brain readers serve a file from outside the brain, so
+// the server does not start until it is removed. A directory the scan cannot
+// read could hide one, so it refuses on that too. A missing brain dir (first
+// boot) is the only case it lets pass.
+func startupSymlinkCheck(brainDir string) error {
+	r, err := symlinkguard.Scan(brainDir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil
+		}
+		return fmt.Errorf("refusing to start: cannot scan the brain dir %s (hyperguild#157): %w", brainDir, err)
+	}
+	if !r.Clean() {
+		return fmt.Errorf("refusing to start: brain dir %s has %s (hyperguild#157); fix them first", brainDir, r)
+	}
+	return nil
+}
+
+// symlinkScanInterval reads BRAIN_SYMLINK_SCAN_INTERVAL (seconds), falling
+// back to the default on an unset, non-numeric or non-positive value.
+func symlinkScanInterval(getenv func(string) string) time.Duration {
+	if s, err := strconv.Atoi(getenv("BRAIN_SYMLINK_SCAN_INTERVAL")); err == nil && s > 0 {
+		return time.Duration(s) * time.Second
+	}
+	return symlinkguard.DefaultInterval
+}

ingestion/cmd/server/symlink_check_test.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#157: the server refuses to start while a symlink exists in the
+// brain dir, or while any part of it cannot be scanned (which could hide
+// one); a missing brain dir is the only thing it lets pass.
+func TestStartupSymlinkCheckRefusesABrainWithASymlink(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.Symlink(t.TempDir(), filepath.Join(brain, "planted")))
+	err := startupSymlinkCheck(brain)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "planted")
+}
+
+func TestStartupSymlinkCheckRefusesABrainWithAnUnreadableDir(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root reads mode-000 directories")
+	}
+	brain := t.TempDir()
+	locked := filepath.Join(brain, "aaa")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+	err := startupSymlinkCheck(brain)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "aaa")
+}
+
+func TestStartupSymlinkCheckPassesACleanOrMissingBrain(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "n.md"), []byte("x"), 0o644))
+	assert.NoError(t, startupSymlinkCheck(brain))
+	assert.NoError(t, startupSymlinkCheck(filepath.Join(brain, "missing")))
+}
+
+func TestSymlinkScanIntervalFallsBackOnNonPositive(t *testing.T) {
+	for _, v := range []string{"0", "-5", "", "junk"} {
+		got := symlinkScanInterval(func(string) string { return v })
+		assert.Positive(t, got, "env %q", v)
+	}
+}
+
+func TestAlertingWarningsNamesTheSymlinkTripwire(t *testing.T) {
+	w := strings.Join(alertingWarnings(func(string) string { return "" }), " ")
+	assert.Contains(t, w, "symlink tripwire")
+}
+
+func TestStartupSymlinkCheckRefusesAnUnlistableBrainRoot(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root lists mode-0100 directories")
+	}
+	brain := t.TempDir()
+	require.NoError(t, os.Chmod(brain, 0o100))
+	t.Cleanup(func() { _ = os.Chmod(brain, 0o755) })
+	assert.Error(t, startupSymlinkCheck(brain))
+}
+
+// hyperguild#179: a FIFO in the brain is refused at startup with a clear
+// message, instead of hanging or exiting later in a reader.
+func TestStartupSymlinkCheckRefusesABrainWithAFIFO(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "classification.yaml"), 0o644))
+	err := startupSymlinkCheck(brain)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "classification.yaml")
+}
+
+// hyperguild#163: each alert source gets its own ntfy title.
+func TestBuildNotifierUsesTheGivenTitle(t *testing.T) {
+	var got string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { got = r.Header.Get("Title") }))
+	defer srv.Close()
+	env := map[string]string{"BRAIN_NTFY_URL": srv.URL}
+	n := buildNotifier(func(k string) string { return env[k] }, "brain symlink tripwire")
+	require.NotNil(t, n)
+	require.NoError(t, n.Notify(context.Background(), "m"))
+	assert.Equal(t, "brain symlink tripwire", got)
+	assert.Nil(t, buildNotifier(func(string) string { return "" }, "x"), "no ntfy URL, no notifier")
+}

ingestion/go.mod

@@ -3,28 +3,72 @@ module github.com/mathiasbq/hyperguild/ingestion
 go 1.26.1
 
 require (
-	github.com/lestrrat-go/jwx/v2 v2.1.6
 	github.com/stretchr/testify v1.11.1
+	k8s.io/api v0.31.3
+	k8s.io/apimachinery v0.31.3
+	k8s.io/client-go v0.31.3
 )
 
 require (
-	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/emicklei/go-restful/v3 v3.11.0 // indirect
+	github.com/fxamacker/cbor/v2 v2.7.0 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.22.4 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/gnostic-models v0.6.8 // indirect
+	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/imdario/mergo v0.3.6 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/lestrrat-go/jwx/v2 v2.1.6 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/rogpeppe/go-internal v1.15.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	golang.org/x/net v0.55.0 // indirect
+	golang.org/x/oauth2 v0.21.0 // indirect
+	golang.org/x/term v0.43.0 // indirect
+	golang.org/x/time v0.3.0 // indirect
+	google.golang.org/protobuf v1.34.2 // indirect
+	gopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
+	k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
+	sigs.k8s.io/yaml v1.4.0 // indirect
+)
+
+require (
+	git.d-ma.be/mathias/mcp-chassis v0.7.1
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
 	github.com/goccy/go-json v0.10.3 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.9.2 // indirect
+	github.com/jackc/pgx/v5 v5.9.2
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/lestrrat-go/blackmagic v1.0.3 // indirect
 	github.com/lestrrat-go/httpcc v1.0.1 // indirect
 	github.com/lestrrat-go/httprc v1.0.6 // indirect
 	github.com/lestrrat-go/iter v1.0.2 // indirect
 	github.com/lestrrat-go/option v1.0.1 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/segmentio/asm v1.2.0 // indirect
-	golang.org/x/crypto v0.32.0 // indirect
-	golang.org/x/sync v0.17.0 // indirect
-	golang.org/x/sys v0.31.0 // indirect
-	golang.org/x/text v0.29.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.45.0
+	golang.org/x/text v0.39.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1
 )

ingestion/go.sum

@@ -1,10 +1,47 @@
+git.d-ma.be/mathias/mcp-chassis v0.7.1 h1:4h8TOBHTA0L/no4IPcr4tLcQtmKUlhE2/cXyPdNFGmM=
+git.d-ma.be/mathias/mcp-chassis v0.7.1/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 h1:NMZiJj8QnKe1LgsbDayM4UoHwbvwDRwnI3hwNaAHRnc=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
+github.com/emicklei/go-restful/v3 v3.11.0 h1:rAQeMHw1c7zTmncogyy8VvRZwtkmkZ4FxERmMY4rD+g=
+github.com/emicklei/go-restful/v3 v3.11.0/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=
+github.com/fxamacker/cbor/v2 v2.7.0 h1:iM5WgngdRBanHcxugY4JySA0nk1wZorNOpTgCMedv5E=
+github.com/fxamacker/cbor/v2 v2.7.0/go.mod h1:pxXPTn3joSm21Gbwsv0w9OSA2y1HFR9qXEeXQVeNoDQ=
+github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
+github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-openapi/jsonpointer v0.19.6 h1:eCs3fxoIi3Wh6vtgmLTOjdhSpiqphQ+DaPn38N2ZdrE=
+github.com/go-openapi/jsonpointer v0.19.6/go.mod h1:osyAmYz/mB/C3I+WsTTSgw1ONzaLJoLCyoi6/zppojs=
+github.com/go-openapi/jsonreference v0.20.2 h1:3sVjiK66+uXK/6oQ8xgcRKcFgQ5KXa2KvnJRumpMGbE=
+github.com/go-openapi/jsonreference v0.20.2/go.mod h1:Bl1zwGIM8/wsvqjsOQLJ/SH+En5Ap4rVB5KVcIDZG2k=
+github.com/go-openapi/swag v0.22.3/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
+github.com/go-openapi/swag v0.22.4 h1:QLMzNJnMGPRNDCbySlcj1x01tzU8/9LTTL9hZZZogBU=
+github.com/go-openapi/swag v0.22.4/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
+github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
+github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
 github.com/goccy/go-json v0.10.3 h1:KZ5WoDbxAIgm2HNbYckL0se1fHD6rz5j4ywS6ebzDqA=
 github.com/goccy/go-json v0.10.3/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/gnostic-models v0.6.8 h1:yo/ABAfM5IMRsS1VnXjTBvUb61tFIHozhlYvRgGre9I=
+github.com/google/gnostic-models v0.6.8/go.mod h1:5n7qKqH0f5wFt+aWF8CW6pZLLNOfYuF5OpfBSENuI8U=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
+github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20240525223248-4bfdf5a9a2af h1:kmjWCqn2qkEml422C2Rrd27c3VGxi6a/6HNq8QmHRKM=
+github.com/google/pprof v0.0.0-20240525223248-4bfdf5a9a2af/go.mod h1:K1liHPHnj73Fdn/EKuT8nrFqBihUSKXoLYU0BuatOYo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/imdario/mergo v0.3.6 h1:xTNEAn+kxVO7dTZGu0CegyqKZmoWFI0rF8UxjlB2d28=
+github.com/imdario/mergo v0.3.6/go.mod h1:2EnlNZ0deacrJVfApfmtdGgDfMuh/nq6Ok1EcJh5FfA=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
@@ -13,6 +50,19 @@ github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
 github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/lestrrat-go/blackmagic v1.0.3 h1:94HXkVLxkZO9vJI/w2u1T0DAoprShFd13xtnSINtDWs=
 github.com/lestrrat-go/blackmagic v1.0.3/go.mod h1:6AWFyKNNj0zEXQYfTMPfZrAXUWUfTIZ5ECEUEJaijtw=
 github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZrIE=
@@ -25,28 +75,118 @@ github.com/lestrrat-go/jwx/v2 v2.1.6 h1:hxM1gfDILk/l5ylers6BX/Eq1m/pnxe9NBwW6lVf
 github.com/lestrrat-go/jwx/v2 v2.1.6/go.mod h1:Y722kU5r/8mV7fYDifjug0r8FK8mZdw0K0GpJw/l8pU=
 github.com/lestrrat-go/option v1.0.1 h1:oAzP2fvZGQKWkvHa1/SAcFolBEca1oN+mQ7eooNBEYU=
 github.com/lestrrat-go/option v1.0.1/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/onsi/ginkgo/v2 v2.19.0 h1:9Cnnf7UHo57Hy3k6/m5k3dRfGTMXGvxhHFvkDTCTpvA=
+github.com/onsi/ginkgo/v2 v2.19.0/go.mod h1:rlwLi9PilAFJ8jCg9UE1QP6VBpd6/xj3SRC0d6TU0To=
+github.com/onsi/gomega v1.19.0 h1:4ieX6qQjPP/BfC3mpsAtIGGlxTWPeA3Inl/7DtXw1tw=
+github.com/onsi/gomega v1.19.0/go.mod h1:LY+I3pBVzYsTBU1AnDwOSxaYi9WoWiqgwooUqq9yPro=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
+github.com/rogpeppe/go-internal v1.15.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/segmentio/asm v1.2.0 h1:9BQrFxC+YOHJlTlHGkTrFWf59nbL3XnCoFLTwDCI7ys=
 github.com/segmentio/asm v1.2.0/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
-golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
-golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
-golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
-golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
-golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
-golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
+golang.org/x/oauth2 v0.21.0 h1:tsimM75w1tF/uws5rbeHzIWxEqElMehnc+iW793zsZs=
+golang.org/x/oauth2 v0.21.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.39.0 h1:UbZz4pLOvn600D6Oh6GGEI6VAmndrEBLv8/6BEXzyus=
+golang.org/x/text v0.39.0/go.mod h1:3UwRclnC2g0TU9x8PZiyfOajCd1zaUNHF9cvqcQZ+ZM=
+golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4=
+golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
+google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/evanphx/json-patch.v4 v4.12.0 h1:n6jtcsulIzXPJaxegRbvFNNrZDjbij7ny3gmSPG+6V4=
+gopkg.in/evanphx/json-patch.v4 v4.12.0/go.mod h1:p8EYWUEYMpynmqDbY58zCKCFZw8pRWMG4EsWvDvM72M=
+gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
+gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+k8s.io/api v0.31.3 h1:umzm5o8lFbdN/hIXbrK9oRpOproJO62CV1zqxXrLgk8=
+k8s.io/api v0.31.3/go.mod h1:UJrkIp9pnMOI9K2nlL6vwpxRzzEX5sWgn8kGQe92kCE=
+k8s.io/apimachinery v0.31.3 h1:6l0WhcYgasZ/wk9ktLq5vLaoXJJr5ts6lkaQzgeYPq4=
+k8s.io/apimachinery v0.31.3/go.mod h1:rsPdaZJfTfLsNJSQzNHQvYoTmxhoOEofxtOsF3rtsMo=
+k8s.io/client-go v0.31.3 h1:CAlZuM+PH2cm+86LOBemaJI/lQ5linJ6UFxKX/SoG+4=
+k8s.io/client-go v0.31.3/go.mod h1:2CgjPUTpv3fE5dNygAr2NcM8nhHzXvxB8KL5gYc3kJs=
+k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
+k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
+k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 h1:BZqlfIlq5YbRMFko6/PM7FjZpUb45WallggurYhKGag=
+k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340/go.mod h1:yD4MZYeKMBwQKVht279WycxKyM84kkAx2DPrTXaeb98=
+k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 h1:pUdcCO1Lk/tbT5ztQWOBi5HBgbBP1J8+AsQnQCKsi8A=
+k8s.io/utils v0.0.0-20240711033017-18e509b52bc8/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=
+sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd h1:EDPBXCAspyGV4jQlpZSudPeMmr1bNJefnuqLsRAsHZo=
+sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd/go.mod h1:B8JuhiUyNFVKdsE8h686QcCxMaH6HrOAZj4vswFpcB0=
+sigs.k8s.io/structured-merge-diff/v4 v4.4.1 h1:150L+0vs/8DA78h1u02ooW1/fFq/Lwr+sGiqlzvrtq4=
+sigs.k8s.io/structured-merge-diff/v4 v4.4.1/go.mod h1:N8hJocpFajUSSeSJ9bOZ77VzejKZaXsTtZo4/u7Io08=
+sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E=
+sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY=

ingestion/internal/api/frontmatter.go

@@ -0,0 +1,129 @@
+package api
+
+import (
+	"strings"
+
+	// Aliased: this package's own frontmatter type (below) would collide
+	// with the imported package's name otherwise.
+	sharedfm "github.com/mathiasbq/hyperguild/ingestion/internal/frontmatter"
+)
+
+// frontmatter is an ordered, line-preserving view of a note's YAML
+// frontmatter block. It deliberately avoids a full YAML round-trip: the
+// brain writes flat `key: value` frontmatter by hand, and a yaml.v3
+// re-marshal would reorder keys and strip comments. Preserving the
+// original lines verbatim keeps brain_update a surgical edit — only the
+// keys it manages (updated_at, supersedes, supersede_reason) change.
+type frontmatter struct {
+	lines []fmLine
+}
+
+// fmLine is one frontmatter line. For `key: value` lines, key and value
+// are populated; for blank lines, comments, or anything that isn't a
+// simple scalar pair, key is empty and raw holds the line verbatim.
+type fmLine struct {
+	key   string
+	value string
+	raw   string
+}
+
+// parseFrontmatter splits src into its frontmatter block and body. A
+// frontmatter block is recognised only when the file opens with a `---`
+// fence and a closing `---` fence follows. Otherwise the whole input is
+// the body and the returned frontmatter is empty.
+//
+// Fence detection itself is frontmatter.Split (hyperguild#138) — this
+// package's own contribution is purely the ordered, line-preserving fmLine
+// shape below, which a shared parser has no business owning since it's
+// specific to how brain_update does a surgical, byte-round-trip edit.
+func parseFrontmatter(src string) (frontmatter, string) {
+	var fm frontmatter
+	blockBytes, restBytes, ok := sharedfm.Split([]byte(src))
+	if !ok {
+		return fm, src
+	}
+	// sharedfm.Split's block/rest boundary sits one byte earlier than this
+	// package's always has: block keeps the "\n" immediately before the
+	// closing fence, and rest keeps the "\n" immediately after it (both by
+	// design, for Fix's own reconstruction). This package's block/body
+	// never included either — TrimSuffix/TrimPrefix restore that exact
+	// boundary. Split guarantees ok=true only when "\n---\n" matched, so
+	// both trims are always exactly one byte, never ambiguous.
+	block := strings.TrimSuffix(string(blockBytes), "\n")
+	body := strings.TrimPrefix(string(restBytes), "\n")
+
+	for _, line := range strings.Split(block, "\n") {
+		// An indented line is a continuation (a YAML block-list item, a
+		// wrapped value) never a top-level key, regardless of whether it
+		// happens to contain a colon — "  - 'Chapter 3: The Reckoning'" is
+		// not a key named "- 'Chapter 3" (hyperguild#128). Checked before
+		// Cut so a colon inside one never reaches the key/value path.
+		if line != "" && (line[0] == ' ' || line[0] == '\t') {
+			fm.lines = append(fm.lines, fmLine{raw: line})
+			continue
+		}
+		key, val, ok := strings.Cut(line, ":")
+		key = strings.TrimSpace(key)
+		if !ok || key == "" || strings.HasPrefix(strings.TrimSpace(line), "#") {
+			fm.lines = append(fm.lines, fmLine{raw: line})
+			continue
+		}
+		fm.lines = append(fm.lines, fmLine{key: key, value: strings.TrimSpace(val)})
+	}
+	return fm, body
+}
+
+// get returns the value for key, or "" if absent.
+func (f *frontmatter) get(key string) string {
+	for _, l := range f.lines {
+		if l.key == key {
+			return l.value
+		}
+	}
+	return ""
+}
+
+// set overrides the value for an existing key in place, or appends a new
+// `key: value` line when the key is absent.
+func (f *frontmatter) set(key, value string) {
+	for i := range f.lines {
+		if f.lines[i].key == key {
+			f.lines[i].value = value
+			return
+		}
+	}
+	f.lines = append(f.lines, fmLine{key: key, value: value})
+}
+
+// render serialises the frontmatter back into a `---`-fenced block. An
+// empty frontmatter renders to the empty string so bodies without a
+// header stay header-less.
+func (f *frontmatter) render() string {
+	if len(f.lines) == 0 {
+		return ""
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	for _, l := range f.lines {
+		switch {
+		case l.key == "":
+			b.WriteString(l.raw)
+		case l.value == "":
+			// A key with nothing after the colon (the YAML block-list
+			// shape: "aliases:" followed by indented "- item" lines on
+			// their own raw lines) must stay bare — "key: " with a
+			// trailing space is a different byte sequence than the
+			// original, and this type's whole purpose (see the package
+			// doc) is a byte-preserving round-trip.
+			b.WriteString(l.key)
+			b.WriteByte(':')
+		default:
+			b.WriteString(l.key)
+			b.WriteString(": ")
+			b.WriteString(l.value)
+		}
+		b.WriteByte('\n')
+	}
+	b.WriteString("---\n")
+	return b.String()
+}

ingestion/internal/api/frontmatter_test.go

@@ -0,0 +1,95 @@
+package api
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestParseFrontmatterSplitsHeaderAndBody(t *testing.T) {
+	src := "---\nwing: jepa-fx\nhall: facts\ncreated_at: 2026-01-01T00:00:00Z\n---\n# Title\n\nbody text\n"
+	fm, body := parseFrontmatter(src)
+
+	assert.Equal(t, "jepa-fx", fm.get("wing"))
+	assert.Equal(t, "facts", fm.get("hall"))
+	assert.Equal(t, "2026-01-01T00:00:00Z", fm.get("created_at"))
+	assert.Equal(t, "# Title\n\nbody text\n", body)
+}
+
+func TestParseFrontmatterNoHeader(t *testing.T) {
+	src := "# Just a body\n\nno frontmatter here\n"
+	fm, body := parseFrontmatter(src)
+
+	assert.Empty(t, fm.lines)
+	assert.Equal(t, src, body)
+}
+
+func TestFrontmatterSetOverridesExistingKey(t *testing.T) {
+	fm, _ := parseFrontmatter("---\nwing: a\nupdated_at: old\n---\nbody\n")
+	fm.set("updated_at", "new")
+
+	assert.Equal(t, "new", fm.get("updated_at"))
+	// No duplicate key.
+	assert.Equal(t, 1, strings.Count(fm.render(), "updated_at:"))
+}
+
+func TestFrontmatterSetAppendsNewKey(t *testing.T) {
+	fm, _ := parseFrontmatter("---\nwing: a\n---\nbody\n")
+	fm.set("supersedes", "abc123")
+
+	out := fm.render()
+	assert.Contains(t, out, "wing: a")
+	assert.Contains(t, out, "supersedes: abc123")
+}
+
+func TestFrontmatterRenderPreservesCustomFields(t *testing.T) {
+	src := "---\nwing: a\nhall: facts\ncustom_field: keep-me\ntags: [x, y]\n---\nbody\n"
+	fm, _ := parseFrontmatter(src)
+	fm.set("updated_at", "2026-06-22T00:00:00Z")
+
+	out := fm.render()
+	assert.Contains(t, out, "custom_field: keep-me")
+	assert.Contains(t, out, "tags: [x, y]")
+	assert.Contains(t, out, "updated_at: 2026-06-22T00:00:00Z")
+}
+
+func TestFrontmatterRenderRoundTrips(t *testing.T) {
+	src := "---\nwing: a\nhall: facts\n---\n"
+	fm, _ := parseFrontmatter(src)
+	assert.Equal(t, src, fm.render())
+}
+
+func TestParseFrontmatterIndentedListItemWithColonIsNotMisparsedAsKey(t *testing.T) {
+	// hyperguild#128: an indented YAML block-list item that happens to
+	// contain a colon (e.g. a title with a subtitle) is a continuation
+	// line, never a top-level key — strings.Cut doesn't know that just
+	// because TrimSpace(key) happens to be non-empty. Misparsing it as a
+	// key/value pair and re-rendering strips its indentation, de-indenting
+	// it out of the list it belongs to. Same bug class already found and
+	// fixed in the sibling internal/wiki package's parseFrontmatterBlock
+	// (hyperguild#126 review round 3) — this package was the original the
+	// reimplementation was modeled on and had the gap too.
+	src := "---\naliases:\n  - 'Chapter 3: The Reckoning'\ntitle: 'X'\n---\nbody\n"
+	fm, _ := parseFrontmatter(src)
+	fm.set("updated_at", "2026-09-23T00:00:00Z")
+
+	out := fm.render()
+	assert.Contains(t, out, "  - 'Chapter 3: The Reckoning'",
+		"the indented list item must survive verbatim, not get re-emitted as a de-indented fake key")
+	assert.NotContains(t, out, "\n- 'Chapter 3",
+		"must not be split into a fake key/value pair at column 0 (as opposed to surviving indented, asserted above)")
+}
+
+func TestFrontmatterRenderEmptyValueKeyStaysBareNoTrailingSpace(t *testing.T) {
+	// Companion to the indented-list-item fix: "aliases:" (a key with
+	// nothing after the colon, the YAML block-list header) must round-trip
+	// bare, not as "aliases: " with a trailing space — a different byte
+	// sequence than the original, breaking this type's whole reason for
+	// being a line-preserving view rather than a YAML re-marshal.
+	// render() returns only the frontmatter block (see
+	// TestFrontmatterRenderRoundTrips), no trailing body.
+	src := "---\naliases:\n  - one\n  - two\n---\n"
+	fm, _ := parseFrontmatter(src)
+	assert.Equal(t, src, fm.render())
+}

ingestion/internal/api/handler.go

@@ -12,7 +12,8 @@ import (
 	"time"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
@@ -53,10 +54,9 @@ type queryRequest struct {
 type writeRequest struct {
 	Content    string `json:"content"`
 	Filename   string `json:"filename,omitempty"`
-	Type     string `json:"type,omitempty"`
-	Domain   string `json:"domain,omitempty"`
 	Wing       string `json:"wing,omitempty"`
 	Hall       string `json:"hall,omitempty"`
+	SourceType string `json:"source_type,omitempty"` // "external" opts a hall=facts entry out of the internal default
 }
 
 type ingestRequest struct {
@@ -108,19 +108,21 @@ func (h *Handler) Query(w http.ResponseWriter, r *http.Request) {
 
 // WriteNoteOptions configures how a brain note is written.
 //
-// When both Wing and Hall are non-empty, the note routes into the
-// structured wiki at brain/wiki/<wing>/<hall>/<slug>.md and gets
-// wing/hall/created_at injected into its YAML frontmatter.
-//
-// When either is empty, the note falls back to brain/knowledge/<filename>
-// with optional type/domain frontmatter (legacy behaviour).
+// Wing and Hall are both required: the note routes into the structured
+// wiki at brain/wiki/<wing>/<hall>/<slug>.md and gets wing/hall/created_at
+// injected into its YAML frontmatter. There is no other valid destination
+// (the legacy brain/knowledge/ fallback was removed — ADR-0012 / #79).
 type WriteNoteOptions struct {
 	Content    string
 	Filename   string
-	Type     string
-	Domain   string
 	Wing       string
 	Hall       string
+	SourceType string // "internal" marks a first-party observation (e.g. claudewatcher) that needs no external citation
+	// Origin/WrittenBy are server-owned provenance (hyperguild#145): any
+	// origin/written_by in Content's own frontmatter is discarded, so a
+	// caller cannot claim a more trusted origin than it authenticated as.
+	Origin    string
+	WrittenBy string
 }
 
 // WriteNote writes a markdown note into the brain. Returns the path
@@ -129,14 +131,21 @@ func WriteNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	if opts.Content == "" {
 		return "", fmt.Errorf("content is required")
 	}
+	if opts.Wing == "" || opts.Hall == "" {
+		return "", fmt.Errorf("wing and hall are required")
+	}
+
+	// In the primitive, not in a caller: POST /write reaches here directly,
+	// without the BrainStore, and a gate one door wide is not a gate.
+	// BrainStore still calls the strip itself to report Ref.Unlinked; the
+	// second pass is a no-op on already-clean content.
+	clean, _, err := brain.StripUnresolvedLinks(brainDir, opts.Content)
+	if err != nil {
+		return "", err
+	}
+	opts.Content = clean
 
-	if opts.Wing != "" && opts.Hall != "" {
 	return writeHallNote(brainDir, opts)
-	}
-	if opts.Wing != "" || opts.Hall != "" {
-		return "", fmt.Errorf("wing and hall must be set together")
-	}
-	return writeLegacyNote(brainDir, opts)
 }
 
 // writeHallNote routes a note into brain/wiki/<wing>/<hall>/ and injects
@@ -150,94 +159,182 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create hall dir: %w", err)
+	existingFields, body := splitFrontmatter(opts.Content)
+	existingByKey := make(map[string]frontmatterField, len(existingFields))
+	for _, f := range existingFields {
+		existingByKey[f.key] = f
 	}
 
+	// Validate the claim-property envelope BEFORE creating the directory, so a
+	// rejected write leaves nothing behind — not even an empty hall dir
+	// (brain#21). Fail closed: a value outside the enum is worse than an absent
+	// one, because a lint skips what it cannot parse and the note then reads as
+	// classified while nothing acts on it.
+	if err := claim.ValidateEnvelope(scalarValues(existingFields)); err != nil {
+		return "", fmt.Errorf("claim envelope: %w", err)
+	}
+
+	emitted := make(map[string]bool, 6)
+
 	var fm strings.Builder
 	fm.WriteString("---\n")
 	fmt.Fprintf(&fm, "wing: %s\n", brain.Sanitise(opts.Wing))
 	fmt.Fprintf(&fm, "hall: %s\n", opts.Hall)
 	fmt.Fprintf(&fm, "created_at: %s\n", time.Now().UTC().Format(time.RFC3339))
-	if opts.Type != "" {
-		fmt.Fprintf(&fm, "type: %s\n", opts.Type)
+	emitted["wing"], emitted["hall"], emitted["created_at"] = true, true, true
+
+	// writeField merges one key: opts.Content's own value (if the note already
+	// carries this field in its own frontmatter) always wins over the fallback,
+	// so promotion/extraction-step metadata survives verbatim instead of being
+	// shadowed by a second, stacked frontmatter block (#86).
+	writeField := func(key, fallback string) {
+		emitted[key] = true
+		if f, ok := existingByKey[key]; ok {
+			for _, line := range f.lines {
+				fm.WriteString(line)
+				fm.WriteString("\n")
+			}
+			return
+		}
+		if fallback != "" {
+			fmt.Fprintf(&fm, "%s: %s\n", key, fallback)
+		}
+	}
+	sourceType := opts.SourceType
+	if sourceType == "" && opts.Hall == "facts" {
+		// Most hall=facts entries are first-party (an eval/benchmark the
+		// writer ran itself), not external claims — default to internal and
+		// require an explicit source_type: external opt-out for the rare
+		// citation-needing entry (brain-gardener#7).
+		sourceType = "internal"
+	}
+	writeField("source_type", sourceType)
+
+	for _, f := range existingFields {
+		if emitted[f.key] {
+			continue
+		}
+		for _, line := range f.lines {
+			fm.WriteString(line)
+			fm.WriteString("\n")
 		}
-	if opts.Domain != "" {
-		fmt.Fprintf(&fm, "domain: %s\n", opts.Domain)
 	}
 	fm.WriteString("---\n")
 
-	if err := os.WriteFile(dest, []byte(fm.String()+opts.Content), 0o644); err != nil {
+	final, err := StampProvenance(fm.String()+body, opts.Origin, opts.WrittenBy)
+	if err != nil {
+		return "", err
+	}
+	// The directory is created only once the note is known to be writable:
+	// a refused write leaves nothing behind, not even an empty hall dir
+	// (brain#21; provenance refusal joins the envelope refusal here).
+	// Created through the brain root, never through a symlinked wing or
+	// hall directory (hyperguild#188).
+	rel, err := filepath.Rel(brainDir, dest)
+	if err != nil {
+		return "", fmt.Errorf("note path: %w", err)
+	}
+	rel = filepath.ToSlash(rel)
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if err := bfs.PutRegular(rel, []byte(final)); err != nil {
 		return "", fmt.Errorf("write: %w", err)
 	}
-	rel, _ := filepath.Rel(brainDir, dest)
-	return filepath.ToSlash(rel), nil
+	return rel, nil
 }
 
-// writeLegacyNote preserves the original brain/knowledge/ behaviour for
-// callers that have not adopted the wing/hall taxonomy.
-func writeLegacyNote(brainDir string, opts WriteNoteOptions) (string, error) {
-	filename := opts.Filename
-	if filename == "" {
-		filename = fmt.Sprintf("%s-auto.md", time.Now().UTC().Format("2006-01-02-150405"))
+// scalarValues flattens frontmatter fields to key -> scalar value for
+// validation. Multi-line values (lists, nested blocks) yield the text after
+// the colon on the first line, which is empty for a list — correct here,
+// since every claim-property field is a scalar enum.
+func scalarValues(fields []frontmatterField) map[string]string {
+	out := make(map[string]string, len(fields))
+	for _, f := range fields {
+		if len(f.lines) == 0 {
+			continue
 		}
-
-	rawDir := filepath.Join(brainDir, "knowledge")
-	if err := os.MkdirAll(rawDir, 0o755); err != nil {
-		return "", fmt.Errorf("create raw dir: %w", err)
+		_, value, found := strings.Cut(f.lines[0], ":")
+		if !found {
+			continue
 		}
-
-	finalContent := opts.Content
-	if opts.Type != "" || opts.Domain != "" {
-		var fm strings.Builder
-		fm.WriteString("---\n")
-		if opts.Type != "" {
-			fmt.Fprintf(&fm, "type: %s\n", opts.Type)
+		out[f.key] = strings.TrimSpace(value)
 	}
-		if opts.Domain != "" {
-			fmt.Fprintf(&fm, "domain: %s\n", opts.Domain)
-		}
-		fm.WriteString("---\n")
-		finalContent = fm.String() + opts.Content
-	}
-
-	if strings.ContainsAny(filename, `/\`) {
-		return "", fmt.Errorf("invalid filename")
-	}
-	base := filepath.Base(filename)
-	if base == "." || base == ".." || base == "" {
-		return "", fmt.Errorf("invalid filename")
-	}
-	if !strings.HasSuffix(base, ".md") {
-		base += ".md"
-	}
-	dest := filepath.Join(rawDir, base)
-	if err := os.WriteFile(dest, []byte(finalContent), 0o644); err != nil {
-		return "", fmt.Errorf("write: %w", err)
-	}
-
-	rel, _ := filepath.Rel(brainDir, dest)
-	return filepath.ToSlash(rel), nil
+	return out
 }
 
-// Write handles POST /write — write raw content to brain/knowledge/.
+// frontmatterField is one top-level YAML key from a frontmatter block,
+// along with its raw line and any indented continuation lines (e.g. a
+// bulleted list value spanning multiple lines).
+type frontmatterField struct {
+	key   string
+	lines []string
+}
+
+// splitFrontmatter splits a leading "---\n...\n---\n" YAML block out of
+// content, returning its top-level fields in original order and the
+// remaining body. If content has no leading frontmatter block, fields is
+// nil and body is content unchanged.
+func splitFrontmatter(content string) (fields []frontmatterField, body string) {
+	if !strings.HasPrefix(content, "---\n") {
+		return nil, content
+	}
+
+	lines := strings.Split(content, "\n")
+	i := 1
+	var cur *frontmatterField
+	for ; i < len(lines); i++ {
+		line := lines[i]
+		if strings.TrimSpace(line) == "---" {
+			i++
+			break
+		}
+		if line != "" && !strings.HasPrefix(line, " ") && !strings.HasPrefix(line, "\t") {
+			if cur != nil {
+				fields = append(fields, *cur)
+			}
+			key, _, _ := strings.Cut(line, ":")
+			cur = &frontmatterField{key: strings.TrimSpace(key), lines: []string{line}}
+		} else if cur != nil {
+			cur.lines = append(cur.lines, line)
+		}
+	}
+	if cur != nil {
+		fields = append(fields, *cur)
+	}
+	body = strings.Join(lines[i:], "\n")
+	return fields, body
+}
+
+// Write handles POST /write — write a note into brain/wiki/<wing>/<hall>/.
 func (h *Handler) Write(w http.ResponseWriter, r *http.Request) {
 	var req writeRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		writeError(w, http.StatusBadRequest, "invalid JSON")
 		return
 	}
-	relPath, err := WriteNote(h.brainDir, WriteNoteOptions(req))
+	// Field by field, not a struct conversion: provenance is server-owned and
+	// this door carries no principal, so it stamps origin: unknown
+	// (hyperguild#145). A JSON body must never be able to set it.
+	relPath, err := WriteNote(h.brainDir, WriteNoteOptions{
+		Content:    req.Content,
+		Filename:   req.Filename,
+		Wing:       req.Wing,
+		Hall:       req.Hall,
+		SourceType: req.SourceType,
+	})
 	if err != nil {
 		h.logger.Error("write failed", "err", err)
 		writeError(w, http.StatusBadRequest, err.Error())
 		return
 	}
-	if req.Wing != "" && req.Hall != "" {
+	// WriteNote errors out above unless both are set, so this always runs —
+	// no legacy fallback path left to guard against.
 	if err := brain.BuildWingIndex(h.brainDir, req.Wing); err != nil {
 		h.logger.Warn("auto-index failed", "wing", req.Wing, "err", err)
 	}
-	}
 	writeJSON(w, map[string]string{"path": relPath})
 }
 
@@ -332,11 +429,19 @@ func (h *Handler) Ingest(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, ingestResponse{Pages: pages, Warnings: warnings})
 }
 
-// supportedExtensions lists file extensions that IngestPath will process.
-var supportedExtensions = map[string]bool{
-	".md":  true,
-	".txt": true,
-	".pdf": true,
+// isSupportedExtension reports whether IngestPath will process ext.
+// .docx/.xlsx/.pptx/.png/.jpg/.jpeg require docmark (ADR-0013) and are only
+// supported when DOCMARK_URL is configured — checked per-call (not cached at
+// package init) so it reflects the environment at request time.
+func isSupportedExtension(ext string) bool {
+	switch ext {
+	case ".md", ".txt", ".pdf":
+		return true
+	case ".docx", ".xlsx", ".pptx", ".png", ".jpg", ".jpeg":
+		return os.Getenv("DOCMARK_URL") != ""
+	default:
+		return false
+	}
 }
 
 // IngestPath handles POST /ingest-path — ingest a file or directory.
@@ -350,6 +455,12 @@ func (h *Handler) IngestPath(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "path is required")
 		return
 	}
+	resolved, err := ResolveIngestPath(h.brainDir, req.Path)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	req.Path = resolved
 
 	info, err := os.Stat(req.Path)
 	if err != nil {
@@ -369,10 +480,16 @@ func (h *Handler) IngestPath(w http.ResponseWriter, r *http.Request) {
 				return nil
 			}
 			ext := strings.ToLower(filepath.Ext(path))
-			if !supportedExtensions[ext] {
+			if !isSupportedExtension(ext) {
 				return nil
 			}
-			content, readErr := extract.Text(path)
+			// Each walked file is re-resolved: a symlinked file inside raw/
+			// would otherwise lead extract.Text out of the inbox (#149).
+			if _, rerr := ResolveIngestPath(h.brainDir, path); rerr != nil {
+				allWarnings = append(allWarnings, fmt.Sprintf("skipped %s: %v", path, rerr))
+				return nil
+			}
+			content, readErr := ReadIngestFile(h.brainDir, path)
 			if readErr != nil {
 				allWarnings = append(allWarnings, fmt.Sprintf("extract %s: %v", path, readErr))
 				return nil
@@ -397,11 +514,11 @@ func (h *Handler) IngestPath(w http.ResponseWriter, r *http.Request) {
 		}
 	} else {
 		ext := strings.ToLower(filepath.Ext(req.Path))
-		if !supportedExtensions[ext] {
+		if !isSupportedExtension(ext) {
 			writeError(w, http.StatusBadRequest, fmt.Sprintf("unsupported file extension: %s", ext))
 			return
 		}
-		content, readErr := extract.Text(req.Path)
+		content, readErr := ReadIngestFile(h.brainDir, req.Path)
 		if readErr != nil {
 			writeError(w, http.StatusInternalServerError, fmt.Sprintf("extract text: %v", readErr))
 			return
@@ -453,7 +570,8 @@ func (h *Handler) IngestRaw(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	result, err := pipeline.RunRaw(h.brainDir, req.Source, req.Pages, req.DryRun)
+	// No principal on this door: pages are stamped origin: unknown (#145).
+	result, err := pipeline.RunRaw(r.Context(), h.brainDir, req.Source, req.Pages, req.DryRun)
 	if err != nil {
 		h.logger.Error("ingest-raw failed", "source", req.Source, "err", err)
 		writeError(w, http.StatusInternalServerError, "ingest error")
@@ -483,6 +601,44 @@ func (h *Handler) BackfillRefs(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, map[string]int{"updated": n})
 }
 
+// Pending handles GET /pending — list raw/ notes awaiting promotion.
+func (h *Handler) Pending(w http.ResponseWriter, _ *http.Request) {
+	pending, err := ListPending(h.brainDir)
+	if err != nil {
+		h.logger.Error("pending failed", "err", err)
+		writeError(w, http.StatusInternalServerError, "pending error")
+		return
+	}
+	writeJSON(w, map[string]any{"pending": pending})
+}
+
+type promoteRequest struct {
+	Filename string `json:"filename"`
+	Wing     string `json:"wing"`
+	Hall     string `json:"hall"`
+	Slug     string `json:"slug,omitempty"`
+}
+
+// Promote handles POST /promote — move a raw/ note into the wiki. A bad
+// hall / collision / missing source is a 400 (caller error), not a 500.
+func (h *Handler) Promote(w http.ResponseWriter, r *http.Request) {
+	var req promoteRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON")
+		return
+	}
+	// Field by field: this door carries no principal, so the promoted note is
+	// stamped origin: unknown and the body cannot set provenance (#145).
+	rel, err := PromoteNote(h.brainDir, PromoteOptions{
+		Filename: req.Filename, Wing: req.Wing, Hall: req.Hall, Slug: req.Slug,
+	})
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	writeJSON(w, map[string]string{"path": rel})
+}
+
 func writeJSON(w http.ResponseWriter, v any) {
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(v) //nolint:errcheck

ingestion/internal/api/handler_test.go

@@ -65,11 +65,13 @@ func TestQuery_ReturnsResults(t *testing.T) {
 	assert.NotEmpty(t, results)
 }
 
-func TestWrite_CreatesKnowledgeFile(t *testing.T) {
+func TestWrite_CreatesWikiFile(t *testing.T) {
 	dir, h := setup(t)
 	body, _ := json.Marshal(map[string]any{
 		"content":  "# Test note\n\nSome content.",
-		"filename": "test-note.md",
+		"filename": "test-note",
+		"wing":     "homelab",
+		"hall":     "facts",
 	})
 	req := httptest.NewRequest(http.MethodPost, "/write", bytes.NewReader(body))
 	rec := httptest.NewRecorder()
@@ -81,11 +83,25 @@ func TestWrite_CreatesKnowledgeFile(t *testing.T) {
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
 	assert.NotEmpty(t, resp["path"])
 
-	content, err := os.ReadFile(filepath.Join(dir, "knowledge", "test-note.md"))
+	content, err := os.ReadFile(filepath.Join(dir, "wiki", "homelab", "facts", "test-note.md"))
 	require.NoError(t, err)
 	assert.Contains(t, string(content), "Some content.")
 }
 
+// TestWrite_RequiresWingAndHall is the HTTP-contract counterpart of
+// TestWriteNote_RequiresWingAndHall: a caller (e.g. the MCP brain_write
+// handler) that omits wing/hall gets a 400, not a silent legacy write.
+func TestWrite_RequiresWingAndHall(t *testing.T) {
+	_, h := setup(t)
+	body, _ := json.Marshal(map[string]any{"content": "no destination"})
+	req := httptest.NewRequest(http.MethodPost, "/write", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	h.Write(rec, req)
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+}
+
 func TestQuery_RequiresQuery(t *testing.T) {
 	_, h := setup(t)
 	body, _ := json.Marshal(map[string]any{"limit": 5})
@@ -97,13 +113,131 @@ func TestQuery_RequiresQuery(t *testing.T) {
 	assert.Equal(t, http.StatusBadRequest, rec.Code)
 }
 
-func TestWrite_IncludesFrontmatterWhenTypeProvided(t *testing.T) {
+func TestWriteNote_HallRouteIncludesSourceTypeWhenSet(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:    "# Claude session abc (koala)\n\nBody.\n",
+		Filename:   "session-koala-abc",
+		Wing:       "claude-sessions",
+		Hall:       "facts",
+		SourceType: "internal",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "source_type: internal")
+	assert.Contains(t, string(got), "wing: claude-sessions")
+}
+
+func TestWriteNote_HallFactsDefaultsSourceTypeInternalWhenUnset(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "manually captured fact.\n",
+		Wing:    "agentsquad",
+		Hall:    "facts",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	// Most hall=facts entries are first-party (an eval/benchmark the agent ran
+	// itself), not external claims — default to internal, require explicit
+	// opt-out for the rare case that does need a citation (brain-gardener#7).
+	assert.Contains(t, string(got), "source_type: internal")
+}
+
+func TestWriteNote_HallFactsPreservesExplicitExternalSourceType(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:    "vendor pricing claim, needs a citation.\n",
+		Wing:       "agentsquad",
+		Hall:       "facts",
+		SourceType: "external",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "source_type: external")
+}
+
+func TestWriteNote_HallRouteOmitsSourceTypeForNonFactsHalls(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "a decision record.\n",
+		Wing:    "agentsquad",
+		Hall:    "decisions",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.NotContains(t, string(got), "source_type")
+}
+
+func TestWriteNote_HallRouteMergesExistingFrontmatterInsteadOfStacking(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\ntitle: act_runner host-executor\ntags: [gitea-actions, act_runner]\n---\n\n# Body\n\nSome content.\n",
+		Filename: "act-runner-host-executor",
+		Wing:     "homelab",
+		Hall:     "failures",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	body := string(got)
+
+	// exactly one frontmatter block: only two "---" delimiter lines total
+	assert.Equal(t, 2, strings.Count(body, "---\n"), "expected a single merged frontmatter block, not stacked blocks")
+	assert.Contains(t, body, "wing: homelab")
+	assert.Contains(t, body, "hall: failures")
+	assert.Contains(t, body, "title: act_runner host-executor")
+	assert.Contains(t, body, "tags: [gitea-actions, act_runner]")
+	assert.Contains(t, body, "# Body")
+}
+
+// TestWriteNote_RequiresWingAndHall pins the post-legacy-removal contract
+// (hyperguild#79 / ADR-0012): with the knowledge/ fallback gone, wing+hall
+// is the only valid destination, so omitting either is a caller error, not
+// a silent fallback.
+func TestWriteNote_RequiresWingAndHall(t *testing.T) {
+	cases := []struct {
+		name string
+		wing string
+		hall string
+	}{
+		{"neither set", "", ""},
+		{"wing only", "homelab", ""},
+		{"hall only", "", "facts"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			_, err := api.WriteNote(dir, api.WriteNoteOptions{
+				Content: "body",
+				Wing:    tc.wing,
+				Hall:    tc.hall,
+			})
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), "wing and hall are required")
+		})
+	}
+}
+
+func TestWrite_GeneratesFilenameIfAbsent(t *testing.T) {
 	dir, h := setup(t)
 	body, _ := json.Marshal(map[string]any{
-		"content":  "Some learning.",
-		"filename": "typed-note.md",
-		"type":     "concept",
-		"domain":   "software",
+		"content": "auto name",
+		"wing":    "homelab",
+		"hall":    "facts",
 	})
 	req := httptest.NewRequest(http.MethodPost, "/write", bytes.NewReader(body))
 	rec := httptest.NewRecorder()
@@ -111,26 +245,54 @@ func TestWrite_IncludesFrontmatterWhenTypeProvided(t *testing.T) {
 	h.Write(rec, req)
 
 	assert.Equal(t, http.StatusOK, rec.Code)
-	content, err := os.ReadFile(filepath.Join(dir, "knowledge", "typed-note.md"))
+	entries, err := os.ReadDir(filepath.Join(dir, "wiki", "homelab", "facts"))
 	require.NoError(t, err)
-	assert.Contains(t, string(content), "type: concept")
-	assert.Contains(t, string(content), "domain: software")
-	assert.Contains(t, string(content), "Some learning.")
+	require.Len(t, entries, 1)
+	assert.True(t, strings.HasSuffix(entries[0].Name(), ".md"))
 }
 
-func TestWrite_GeneratesFilenameIfAbsent(t *testing.T) {
+// TestWrite_CLIPayloadRoundTrips exercises the real Handler.Write (not a
+// hand-rolled mock) over an actual HTTP round trip, POSTing the exact JSON
+// envelope cmd/hyperguild's brainClient.Write sends: {wing, hall, filename,
+// content}. cmd/hyperguild lives in a separate Go module from ingestion
+// (no shared go.work), so a Go-level test can't import brainClient
+// directly — this test instead pins the wire contract from the server
+// side and proves a real `hyperguild brain write <wing> <hall> <slug>`
+// invocation writes a real file with real frontmatter under wiki/<wing>/<hall>/.
+// A prior version of this contract test on the client side (in
+// cmd/hyperguild/http_test.go) used only an httptest.NewServer with a
+// hand-rolled mock body, so it stayed green through a regression where the
+// server required wing/hall but the client never sent them (hyperguild#79
+// PR review).
+func TestWrite_CLIPayloadRoundTrips(t *testing.T) {
 	dir, h := setup(t)
-	body, _ := json.Marshal(map[string]any{"content": "auto name"})
-	req := httptest.NewRequest(http.MethodPost, "/write", bytes.NewReader(body))
-	rec := httptest.NewRecorder()
+	srv := httptest.NewServer(http.HandlerFunc(h.Write))
+	defer srv.Close()
 
-	h.Write(rec, req)
+	payload, err := json.Marshal(struct {
+		Wing     string `json:"wing"`
+		Hall     string `json:"hall"`
+		Filename string `json:"filename"`
+		Content  string `json:"content"`
+	}{Wing: "homelab", Hall: "facts", Filename: "cli-roundtrip", Content: "# CLI roundtrip\n\nReal write.\n"})
+	require.NoError(t, err)
 
-	assert.Equal(t, http.StatusOK, rec.Code)
-	entries, _ := os.ReadDir(filepath.Join(dir, "knowledge"))
-	// +1 because setup already wrote tdd.md
-	assert.Len(t, entries, 2)
-	assert.True(t, strings.HasSuffix(entries[1].Name(), ".md"))
+	resp, err := http.Post(srv.URL+"/write", "application/json", bytes.NewReader(payload)) //nolint:noctx
+	require.NoError(t, err)
+	defer resp.Body.Close() //nolint:errcheck
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	var out struct {
+		Path string `json:"path"`
+	}
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&out))
+	assert.Equal(t, "wiki/homelab/facts/cli-roundtrip.md", out.Path)
+
+	written, err := os.ReadFile(filepath.Join(dir, "wiki", "homelab", "facts", "cli-roundtrip.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(written), "wing: homelab")
+	assert.Contains(t, string(written), "hall: facts")
+	assert.Contains(t, string(written), "Real write.")
 }
 
 // ---------------------------------------------------------------------------
@@ -199,10 +361,11 @@ func TestIngestPath_MissingPath(t *testing.T) {
 }
 
 func TestIngestPath_File(t *testing.T) {
-	_, h := setup(t)
+	brainDir, h := setup(t)
 
 	// Create a temp file with content
-	dir := t.TempDir()
+	dir := filepath.Join(brainDir, "raw", "fixture") // ingest paths must live in brain/raw/ (#149)
+	require.NoError(t, os.MkdirAll(dir, 0o755))
 	f := filepath.Join(dir, "doc.md")
 	require.NoError(t, os.WriteFile(f, []byte("# Hello\nThis is markdown content."), 0o644))
 
@@ -306,10 +469,11 @@ func TestIngestRaw_DryRun(t *testing.T) {
 }
 
 func TestIngestPath_Directory(t *testing.T) {
-	_, h := setup(t)
+	brainDir, h := setup(t)
 
 	// Create a temp dir with one .md file
-	dir := t.TempDir()
+	dir := filepath.Join(brainDir, "raw", "fixture") // ingest paths must live in brain/raw/ (#149)
+	require.NoError(t, os.MkdirAll(dir, 0o755))
 	require.NoError(t, os.WriteFile(filepath.Join(dir, "notes.md"), []byte("# Notes\nSome notes."), 0o644))
 
 	body, _ := json.Marshal(map[string]any{
@@ -330,3 +494,102 @@ func TestIngestPath_Directory(t *testing.T) {
 	require.True(t, ok, "pages must be an array")
 	assert.NotEmpty(t, pagesSlice)
 }
+
+// --- brain#21: claim-property envelope on the write path -------------------
+
+func TestWriteNote_PreservesClaimEnvelopeVerbatim(t *testing.T) {
+	// writeHallNote already passes unknown keys through; this pins that
+	// behaviour for the envelope specifically, so a future refactor of the
+	// merge loop cannot silently drop it.
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "---\nhalf_life: durable\napplies: universal\nclaim_provenance: asserted\n---\n\nA durable claim.\n",
+		Wing:    "homelab",
+		Hall:    "decisions",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "half_life: durable")
+	assert.Contains(t, string(got), "applies: universal")
+	assert.Contains(t, string(got), "claim_provenance: asserted")
+}
+
+func TestWriteNote_RejectsInvalidClaimEnvelopeAndWritesNothing(t *testing.T) {
+	// Fail closed: a value outside the enum must not land. A lint skips what
+	// it cannot parse, so an unvalidated write produces a note that reads as
+	// classified while nothing acts on it.
+	dir := t.TempDir()
+
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\nhalf_life: forever\nclaim_provenance: asserted\n---\n\nBody.\n",
+		Filename: "bad-envelope",
+		Wing:     "homelab",
+		Hall:     "facts",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "half_life")
+
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/homelab/facts/bad-envelope.md"))
+	assert.True(t, os.IsNotExist(statErr), "a rejected write must leave no file behind")
+}
+
+func TestWriteNote_RejectsClaimFieldWithoutProvenance(t *testing.T) {
+	dir := t.TempDir()
+
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\napplies: homelab\n---\n\nBody.\n",
+		Filename: "no-provenance",
+		Wing:     "homelab",
+		Hall:     "facts",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "claim_provenance")
+
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/homelab/facts/no-provenance.md"))
+	assert.True(t, os.IsNotExist(statErr))
+}
+
+// The HTTP POST /write door reaches WriteNote directly, without the
+// BrainStore, so the unresolved-wikilink strip has to live in the primitive
+// or that door stays ungated.
+func TestWriteNote_UnwrapsUnresolvedWikilinks(t *testing.T) {
+	dir := t.TempDir()
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "# Target\n\nbody\n", Filename: "target", Wing: "a", Hall: "facts",
+	})
+	require.NoError(t, err)
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "See [[target]] and [[gitea-ci]].\n",
+		Filename: "src", Wing: "a", Hall: "facts",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "[[target]]")
+	assert.Contains(t, string(got), "and gitea-ci.")
+	assert.NotContains(t, string(got), "[[gitea-ci]]")
+}
+
+func TestUpdateNote_UnwrapsUnresolvedWikilinks(t *testing.T) {
+	dir := t.TempDir()
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "old\n", Filename: "n", Wing: "a", Hall: "facts",
+	})
+	require.NoError(t, err)
+
+	rel, _, _, err := api.UpdateNote(dir, api.UpdateNoteOptions{
+		Wing: "a", Hall: "facts", Slug: "n",
+		Content: "Related: [[secret-hygiene]].\n", Reason: "r",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "Related: secret-hygiene.")
+	assert.NotContains(t, string(got), "[[secret-hygiene]]")
+}

ingestion/internal/api/ingestpath_docmark_test.go

@@ -0,0 +1,62 @@
+// ingestion/internal/api/ingestpath_docmark_test.go
+package api_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIngestPath_DocxUnsupportedWhenDocmarkNotConfigured(t *testing.T) {
+	t.Setenv("DOCMARK_URL", "")
+	_, h := setup(t)
+
+	dir := t.TempDir()
+	f := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(f, []byte("fake docx"), 0o644))
+
+	body, _ := json.Marshal(map[string]any{"path": f, "source": "test-doc", "dry_run": true})
+	req := httptest.NewRequest(http.MethodPost, "/ingest-path", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	h.IngestPath(rec, req)
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code, rec.Body.String())
+}
+
+func TestIngestPath_DocxSupportedWhenDocmarkConfigured(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"# Converted Doc"}]}}`))
+	}))
+	defer srv.Close()
+	t.Setenv("DOCMARK_URL", srv.URL+"/mcp")
+	t.Setenv("DOCMARK_BEARER_TOKEN", "tok")
+
+	brainDir, h := setup(t)
+
+	dir := filepath.Join(brainDir, "raw", "fixture") // ingest paths must live in brain/raw/ (#149)
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	f := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(f, []byte("fake docx"), 0o644))
+
+	body, _ := json.Marshal(map[string]any{"path": f, "source": "test-doc", "dry_run": true})
+	req := httptest.NewRequest(http.MethodPost, "/ingest-path", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	h.IngestPath(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	pages, ok := resp["pages"].([]any)
+	require.True(t, ok)
+	assert.NotEmpty(t, pages)
+}

ingestion/internal/api/ingestpath_root.go

@@ -0,0 +1,67 @@
+package api
+
+import (
+	"errors"
+	"os"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
+	"path/filepath"
+	"strings"
+)
+
+// ErrOutsideIngestRoot is the one refusal for every bad ingest path. It never
+// carries the underlying error: "no such file" versus "permission denied"
+// would let a caller probe which server files exist (PR #152 review).
+var ErrOutsideIngestRoot = errors.New("ingest path must be an existing file or directory inside brain/raw/")
+
+// ResolveIngestPath confines a caller-supplied ingest path to brain/raw/, the
+// inbox the watcher already owns (hyperguild#149). Relative paths resolve
+// against that root; symlinks are evaluated before the containment check, so
+// a link inside raw/ that points elsewhere is refused. The path must exist.
+func ResolveIngestPath(brainDir, p string) (string, error) {
+	if strings.TrimSpace(p) == "" {
+		return "", ErrOutsideIngestRoot
+	}
+	// raw/ itself must be a real directory: if it were a symlink, containment
+	// inside it would mean nothing (hyperguild#153 item 4).
+	if fi, lerr := os.Lstat(filepath.Join(brainDir, "raw")); lerr != nil || fi.Mode()&os.ModeSymlink != 0 || !fi.IsDir() {
+		return "", ErrOutsideIngestRoot
+	}
+	root, err := filepath.EvalSymlinks(filepath.Join(brainDir, "raw"))
+	if err != nil {
+		return "", ErrOutsideIngestRoot
+	}
+	if !filepath.IsAbs(p) {
+		p = filepath.Join(root, p)
+	}
+	real, err := filepath.EvalSymlinks(filepath.Clean(p))
+	if err != nil {
+		return "", ErrOutsideIngestRoot
+	}
+	rel, err := filepath.Rel(root, real)
+	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) || filepath.IsAbs(rel) {
+		return "", ErrOutsideIngestRoot
+	}
+	return real, nil
+}
+
+// ReadIngestFile extracts text from an ingest path already confined by
+// ResolveIngestPath, reading it through the raw/ root rather than reopening
+// the path by name (hyperguild#153 item 3): if the file is swapped for a
+// symlink after the check, the read still cannot leave raw/.
+func ReadIngestFile(brainDir, resolved string) (string, error) {
+	root, rawPath, err := OpenRawRoot(brainDir)
+	if err != nil {
+		return "", ErrOutsideIngestRoot
+	}
+	defer func() { _ = root.Close() }()
+	realRoot, err := filepath.EvalSymlinks(rawPath)
+	if err != nil {
+		return "", ErrOutsideIngestRoot
+	}
+	rel, err := filepath.Rel(realRoot, resolved)
+	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) || filepath.IsAbs(rel) {
+		return "", ErrOutsideIngestRoot
+	}
+	return extract.TextIn(root, rel)
+}

ingestion/internal/api/ingestpath_root_test.go

@@ -0,0 +1,88 @@
+package api_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#149: /ingest-path and MCP brain_ingest read a caller-chosen
+// server path, so any file the pod could read (the ServiceAccount token,
+// /etc/passwd) could be pulled into the brain and read back out. Ingest paths
+// now resolve inside brain/raw/ — the inbox the watcher already owns — with
+// symlinks evaluated, or are refused.
+func TestResolveIngestPathConfinesToRawInbox(t *testing.T) {
+	brain := t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(filepath.Join(raw, "sub"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "sub", "ok.md"), []byte("x"), 0o644))
+	outside := filepath.Join(t.TempDir(), "secret.txt")
+	require.NoError(t, os.WriteFile(outside, []byte("s"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(raw, "link.md")))
+	require.NoError(t, os.Symlink(filepath.Dir(outside), filepath.Join(raw, "dirlink")))
+
+	for _, ok := range []string{filepath.Join(raw, "sub", "ok.md"), "sub/ok.md", raw, "sub"} {
+		_, err := api.ResolveIngestPath(brain, ok)
+		assert.NoError(t, err, ok)
+	}
+	for _, bad := range []string{
+		"/etc/hostname", outside, "../secret.txt", filepath.Join(raw, "..", "wiki"),
+		filepath.Join(raw, "link.md"), filepath.Join(raw, "dirlink", "secret.txt"),
+		raw + "-evil/x.md", "",
+	} {
+		_, err := api.ResolveIngestPath(brain, bad)
+		assert.Error(t, err, "must refuse %q", bad)
+	}
+}
+
+func TestIngestPathRefusesAPathOutsideTheInbox(t *testing.T) {
+	_, h := setup(t)
+	body, _ := json.Marshal(map[string]any{"path": "/etc/hostname"})
+	rec := httptest.NewRecorder()
+	h.IngestPath(rec, httptest.NewRequest(http.MethodPost, "/ingest-path", bytes.NewReader(body)))
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+	assert.Contains(t, rec.Body.String(), "raw")
+}
+
+// A directory ingest must not follow a symlinked FILE inside raw/ out of it.
+func TestIngestPathDirectoryWalkSkipsSymlinksLeavingTheInbox(t *testing.T) {
+	dir, h := setup(t)
+	raw := filepath.Join(dir, "raw", "batch")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	outside := filepath.Join(t.TempDir(), "secret.md")
+	require.NoError(t, os.WriteFile(outside, []byte("# secret\n\nSENTINEL-149-OUTSIDE"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(raw, "leak.md")))
+	body, _ := json.Marshal(map[string]any{"path": "batch", "source": "walk"})
+	rec := httptest.NewRecorder()
+	h.IngestPath(rec, httptest.NewRequest(http.MethodPost, "/ingest-path", bytes.NewReader(body)))
+	assert.Contains(t, rec.Body.String(), "skipped")
+	assert.NotContains(t, rec.Body.String(), "SENTINEL-149-OUTSIDE")
+}
+
+// PR #152 review: the raw EvalSymlinks error told an authenticated caller
+// whether any server file existed ("no such file") or was unreadable
+// ("permission denied"), and leaked the brain directory. Every refusal now
+// reads the same.
+func TestResolveIngestPathRefusalsAreIndistinguishable(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+	var msgs []string
+	for _, p := range []string{"/etc/hostname", "/etc/definitely-not-here-149", "../x", "nope/missing.md", ""} {
+		_, err := api.ResolveIngestPath(brain, p)
+		require.Error(t, err, p)
+		msgs = append(msgs, err.Error())
+		assert.NotContains(t, err.Error(), brain, "refusal for %q leaks the brain dir", p)
+	}
+	for _, m := range msgs[1:] {
+		assert.Equal(t, msgs[0], m)
+	}
+}

ingestion/internal/api/promote.go

@@ -0,0 +1,241 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// PendingNote describes a raw/ note awaiting human promotion to the wiki.
+type PendingNote struct {
+	Filename  string `json:"filename"`
+	CreatedAt string `json:"created_at"`
+	SizeBytes int64  `json:"size_bytes"`
+	Excerpt   string `json:"excerpt"`
+}
+
+// datePrefix matches a leading YYYY-MM-DD- on a raw filename, stripped when
+// deriving the default promoted slug.
+var datePrefix = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}-`)
+
+// ListPending returns the notes in brain/raw/ awaiting review, oldest-first
+// (natural review order). An absent raw/ dir yields an empty slice, not an
+// error. Only .md files are listed; tunnel-candidate files are skipped.
+func ListPending(brainDir string) ([]PendingNote, error) {
+	root, _, err := OpenRawRoot(brainDir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return []PendingNote{}, nil
+		}
+		return nil, fmt.Errorf("read raw dir: %w", err)
+	}
+	defer func() { _ = root.Close() }()
+	entries, err := fs.ReadDir(root.FS(), ".")
+	if err != nil {
+		return nil, fmt.Errorf("read raw dir: %w", err)
+	}
+
+	out := make([]PendingNote, 0, len(entries))
+	for _, e := range entries {
+		if !e.Type().IsRegular() || !strings.HasSuffix(e.Name(), ".md") || strings.HasPrefix(e.Name(), "tunnel-candidates-") {
+			continue // directories, and symlinks whose target may be anywhere (#153)
+		}
+		raw, info, readErr := readRawNote(root, e.Name())
+		if readErr != nil {
+			continue
+		}
+		fm, body := parseFrontmatter(string(raw))
+		created := fm.get("created_at")
+		if created == "" {
+			created = info.ModTime().UTC().Format(time.RFC3339)
+		}
+		out = append(out, PendingNote{
+			Filename:  e.Name(),
+			CreatedAt: created,
+			SizeBytes: info.Size(),
+			Excerpt:   excerpt(body, 200),
+		})
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].CreatedAt < out[j].CreatedAt })
+	return out, nil
+}
+
+// PromoteOptions identifies a raw note to promote and its wiki destination.
+type PromoteOptions struct {
+	Filename string // basename in brain/raw/
+	Wing     string
+	Hall     string
+	Slug     string // optional; defaults to Filename minus date prefix + .md
+	// Origin/WrittenBy re-attribute the promoted note to the promoter: the raw
+	// note's own frontmatter claims are not provenance (hyperguild#145).
+	Origin    string
+	WrittenBy string
+}
+
+// PromoteNote moves a note from brain/raw/ into the structured wiki: it
+// rewrites frontmatter (sets wing/hall/promoted_at, preserves created_at and
+// any custom fields), writes to brain/wiki/<wing>/<hall>/<slug>.md, deletes
+// the source, then rebuilds the wing index and runs auto-tunnel detection.
+//
+// It is atomic from the caller's view: validation (hall, wing, slug,
+// collision) happens before any filesystem change, and the source is deleted
+// only after the destination write succeeds (write-then-delete, never move).
+// Returns the promoted note's path relative to brainDir.
+func PromoteNote(brainDir string, opts PromoteOptions) (string, error) {
+	// Validate filename (basename only — no traversal) before touching fs.
+	base := filepath.Base(opts.Filename)
+	if base != opts.Filename || base == "." || base == ".." || strings.ContainsAny(opts.Filename, `/\`) {
+		return "", fmt.Errorf("invalid filename %q", opts.Filename)
+	}
+
+	slug := opts.Slug
+	if slug == "" {
+		slug = datePrefix.ReplaceAllString(strings.TrimSuffix(base, ".md"), "")
+	}
+	// NotePath validates hall + wing + slug; do this before reading anything.
+	dest, err := brain.NotePath(brainDir, opts.Wing, opts.Hall, slug)
+	if err != nil {
+		return "", err
+	}
+
+	src := filepath.Join(brainDir, "raw", base)
+	raw, err := readRawSource(brainDir, base)
+	if err != nil {
+		return "", err
+	}
+
+	// Collision: never silently overwrite an existing promoted note.
+	if _, statErr := os.Stat(dest); statErr == nil {
+		rel, _ := filepath.Rel(brainDir, dest)
+		return "", fmt.Errorf("target %s already exists; choose a different slug", filepath.ToSlash(rel))
+	}
+
+	fm, body := parseFrontmatter(string(raw))
+	now := time.Now().UTC().Format(time.RFC3339)
+	fm.set("wing", brain.Sanitise(opts.Wing))
+	fm.set("hall", opts.Hall)
+	if fm.get("created_at") == "" {
+		fm.set("created_at", now)
+	}
+	fm.set("promoted_at", now)
+
+	// Write-then-delete: the source survives any write failure. Both go
+	// through the brain root (hyperguild#188).
+	promoted, err := StampProvenance(fm.render()+body, opts.Origin, opts.WrittenBy)
+	if err != nil {
+		return "", err
+	}
+	// Created with O_EXCL: a note that appeared after the collision check
+	// above is never overwritten.
+	if err := createBrainFile(brainDir, dest, []byte(promoted)); err != nil {
+		return "", fmt.Errorf("write promoted note: %w", err)
+	}
+	if err := removeBrainFile(brainDir, src); err != nil {
+		return "", fmt.Errorf("promoted note written but source removal failed: %w", err)
+	}
+
+	rel, _ := filepath.Rel(brainDir, dest)
+	relSlash := filepath.ToSlash(rel)
+
+	// Best-effort wiki upkeep — the note is already promoted.
+	_ = brain.BuildWingIndex(brainDir, opts.Wing)
+	_ = brain.AutoTunnel(brainDir, relSlash, body)
+
+	return relSlash, nil
+}
+
+// RejectOptions identifies a raw note to reject and why.
+type RejectOptions struct {
+	Filename string // basename in brain/raw/
+	Reason   string // optional
+}
+
+// RejectNote records a human decision not to promote a brain/raw/ note,
+// without silently losing it: it stamps rejected_at (+ reject_reason when
+// given) into frontmatter and moves the file to brain/raw/rejected/, using
+// the same write-then-delete safety PromoteNote uses — the source survives
+// any write failure — and the same basename-only filename validation.
+//
+// A rejected note never entered the wiki, so no index rebuild or
+// auto-tunnel run: unlike PromoteNote, this is the end of the note's
+// journey, not the start of a new one. It stays out of ListPending's view
+// (raw/rejected/ is a subdirectory, and ListPending's os.ReadDir on raw/
+// does not recurse), so a rejected note is never re-surfaced as pending —
+// the human decision, once made, stays made, the same principle behind
+// this estate's "issue status is surfaced, not auto-closed, but once a
+// human decides, the decision is recorded" rule applied one level earlier.
+func RejectNote(brainDir string, opts RejectOptions) (string, error) {
+	base := filepath.Base(opts.Filename)
+	if base != opts.Filename || base == "." || base == ".." || strings.ContainsAny(opts.Filename, `/\`) {
+		return "", fmt.Errorf("invalid filename %q", opts.Filename)
+	}
+
+	src := filepath.Join(brainDir, "raw", base)
+	raw, err := readRawSource(brainDir, base)
+	if err != nil {
+		return "", err
+	}
+
+	dest := filepath.Join(brainDir, "raw", "rejected", base)
+	if _, statErr := os.Stat(dest); statErr == nil {
+		rel, _ := filepath.Rel(brainDir, dest)
+		return "", fmt.Errorf("a rejected note named %s already exists", filepath.ToSlash(rel))
+	}
+
+	fm, body := parseFrontmatter(string(raw))
+	fm.set("rejected_at", time.Now().UTC().Format(time.RFC3339))
+	if opts.Reason != "" {
+		fm.set("reject_reason", opts.Reason)
+	}
+
+	// Write-then-delete: the source survives any write failure. Both go
+	// through the brain root (hyperguild#188).
+	if err := createBrainFile(brainDir, dest, []byte(fm.render()+body)); err != nil {
+		return "", fmt.Errorf("write rejected note: %w", err)
+	}
+	if err := removeBrainFile(brainDir, src); err != nil {
+		return "", fmt.Errorf("rejected note written but source removal failed: %w", err)
+	}
+
+	rel, _ := filepath.Rel(brainDir, dest)
+	return filepath.ToSlash(rel), nil
+}
+
+// excerpt returns the first n runes of s, trimmed, single-spaced.
+func excerpt(s string, n int) string {
+	s = strings.TrimSpace(s)
+	r := []rune(s)
+	if len(r) > n {
+		r = r[:n]
+	}
+	return strings.TrimSpace(string(r))
+}
+
+// readRawSource reads a pending note for promote/reject through the raw root,
+// refusing symlinks and a symlinked raw/ (hyperguild#153).
+func readRawSource(brainDir, base string) ([]byte, error) {
+	root, _, err := OpenRawRoot(brainDir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("pending note %q does not exist in raw/", base)
+		}
+		return nil, fmt.Errorf("read source: %w", err)
+	}
+	defer func() { _ = root.Close() }()
+	raw, _, err := readRawNote(root, base)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("pending note %q does not exist in raw/", base)
+		}
+		return nil, fmt.Errorf("read source: %w", err)
+	}
+	return raw, nil
+}

ingestion/internal/api/promote_redirect_test.go

@@ -0,0 +1,87 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#188: promote and reject wrote the destination with
+// os.MkdirAll + os.WriteFile by path, so a symlinked wing (promote) or a
+// symlinked raw/rejected (reject) redirected the note; the raw source was
+// then removed.
+func TestPromoteAndRejectRefuseASymlinkedDestinationDirectory(t *testing.T) {
+	brain := t.TempDir()
+	outside := t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-10-05-n.md"), []byte("---\ntitle: n\n---\nbody\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(outside, filepath.Join(brain, "wiki", "lw")))
+	require.NoError(t, os.Symlink(outside, filepath.Join(raw, "rejected")))
+
+	_, err := api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "lw", Hall: "facts"})
+	assert.Error(t, err)
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	assert.Error(t, err)
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "a note was written outside the brain")
+	_, err = os.Stat(filepath.Join(raw, "2026-10-05-n.md"))
+	assert.NoError(t, err, "the raw source is kept when the write is refused")
+
+	require.NoError(t, os.Remove(filepath.Join(raw, "rejected")))
+	_, err = api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "w", Hall: "facts"})
+	require.NoError(t, err, "positive control: promote into a real wing")
+}
+
+// StampProvenanceFile read and rewrote the note by path (provenance.ApplyFile).
+func TestStampProvenanceFileRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	brain := t.TempDir()
+	victim := filepath.Join(brain, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("---\ntitle: v\n---\nuntouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(brain, "wiki", "w", "alias")))
+	assert.Error(t, api.StampProvenanceFile(brain, "wiki/w/alias/v.md", "static", "x"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "---\ntitle: v\n---\nuntouched\n", string(got))
+
+	real := filepath.Join(brain, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("---\ntitle: r\n---\nbody\n"), 0o644))
+	require.NoError(t, api.StampProvenanceFile(brain, "wiki/w/facts/r.md", "static", "x"), "positive control")
+	got, _ = os.ReadFile(real)
+	assert.Contains(t, string(got), "written_by: x")
+}
+
+// The same through an in-brain symlinked wing and raw/rejected, which
+// os.Root alone would follow.
+func TestPromoteAndRejectRefuseAnInBrainSymlinkedDestinationDirectory(t *testing.T) {
+	brain := t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-10-05-n.md"), []byte("---\ntitle: n\n---\nbody\n"), 0o644))
+	target := filepath.Join(brain, "archive")
+	require.NoError(t, os.MkdirAll(target, 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "archive"), filepath.Join(brain, "wiki", "lw")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "archive"), filepath.Join(raw, "rejected")))
+
+	_, err := api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "lw", Hall: "facts"})
+	assert.Error(t, err)
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	assert.Error(t, err)
+	ents, _ := os.ReadDir(target)
+	assert.Empty(t, ents, "a note was written at the in-brain link's target")
+	_, err = os.Stat(filepath.Join(raw, "2026-10-05-n.md"))
+	assert.NoError(t, err, "the raw source is kept")
+
+	require.NoError(t, os.Remove(filepath.Join(raw, "rejected")))
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	require.NoError(t, err, "positive control: reject into a real raw/rejected")
+}

ingestion/internal/api/promote_test.go

@@ -0,0 +1,203 @@
+package api
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func writeRaw(t *testing.T, brainDir, name, content string) {
+	t.Helper()
+	dir := filepath.Join(brainDir, "raw")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644))
+}
+
+func TestListPendingEmptyWhenAbsent(t *testing.T) {
+	got, err := ListPending(t.TempDir())
+	require.NoError(t, err, "absent raw/ is not an error")
+	assert.Empty(t, got)
+}
+
+func TestListPendingReturnsOldestFirstWithExcerpt(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-02-newer.md", "---\ncreated_at: 2026-06-02T00:00:00Z\n---\nNewer body here.\n")
+	writeRaw(t, dir, "2026-06-01-older.md", "---\ncreated_at: 2026-06-01T00:00:00Z\n---\nOlder body content.\n")
+	// non-md ignored
+	writeRaw(t, dir, "notes.txt", "ignore me")
+
+	got, err := ListPending(dir)
+	require.NoError(t, err)
+	require.Len(t, got, 2)
+	assert.Equal(t, "2026-06-01-older.md", got[0].Filename, "oldest first")
+	assert.Equal(t, "2026-06-02-newer.md", got[1].Filename)
+	assert.Contains(t, got[0].Excerpt, "Older body content")
+	assert.NotContains(t, got[0].Excerpt, "---", "excerpt is body, not frontmatter")
+	assert.Positive(t, got[0].SizeBytes)
+}
+
+func TestPromoteHappyPath(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-lejpa-decision.md",
+		"---\ncreated_at: 2026-06-01T09:00:00Z\ncustom_field: keep-me\n---\n# LeJEPA\n\nbody.\n")
+
+	rel, err := PromoteNote(dir, PromoteOptions{
+		Filename: "2026-06-01-lejpa-decision.md", Wing: "jepa-fx", Hall: "decisions",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "wiki/jepa-fx/decisions/lejpa-decision.md", rel, "slug defaults to filename minus date prefix")
+
+	// Source deleted.
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-lejpa-decision.md"))
+	assert.True(t, os.IsNotExist(statErr), "source removed after promote")
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	s := string(got)
+	assert.Contains(t, s, "wing: jepa-fx")
+	assert.Contains(t, s, "hall: decisions")
+	assert.Contains(t, s, "created_at: 2026-06-01T09:00:00Z", "original created_at preserved")
+	assert.Contains(t, s, "promoted_at:")
+	assert.Contains(t, s, "custom_field: keep-me", "custom frontmatter preserved")
+	assert.Contains(t, s, "# LeJEPA")
+}
+
+func TestPromoteExplicitSlug(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "body\n")
+	rel, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts", Slug: "custom-slug"})
+	require.NoError(t, err)
+	assert.Equal(t, "wiki/a/facts/custom-slug.md", rel)
+}
+
+func TestPromoteInvalidHallErrorsBeforeTouchingFS(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "body\n")
+	_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "garbage"})
+	require.Error(t, err)
+	// Source untouched.
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-x.md"))
+	assert.NoError(t, statErr, "invalid hall must not delete or move the source")
+}
+
+func TestPromoteMissingSourceErrors(t *testing.T) {
+	_, err := PromoteNote(t.TempDir(), PromoteOptions{Filename: "ghost.md", Wing: "a", Hall: "facts"})
+	require.Error(t, err)
+}
+
+func TestPromoteSlugCollisionNoOverwrite(t *testing.T) {
+	dir := t.TempDir()
+	// Pre-existing target.
+	dest := filepath.Join(dir, "wiki", "a", "facts", "x.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(dest), 0o755))
+	require.NoError(t, os.WriteFile(dest, []byte("EXISTING\n"), 0o644))
+	writeRaw(t, dir, "2026-06-01-x.md", "NEW\n")
+
+	_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts"})
+	require.Error(t, err, "collision must error, not overwrite")
+
+	got, _ := os.ReadFile(dest)
+	assert.Equal(t, "EXISTING\n", string(got), "target not overwritten")
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-x.md"))
+	assert.NoError(t, statErr, "source preserved on collision (atomic: no delete without write)")
+}
+
+func TestPromoteRejectsTraversalFilename(t *testing.T) {
+	_, err := PromoteNote(t.TempDir(), PromoteOptions{Filename: "../escape.md", Wing: "a", Hall: "facts"})
+	require.Error(t, err)
+}
+
+func TestPromoteRebuildsWingIndex(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "---\ntitle: X Note\n---\nbody\n")
+	_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts"})
+	require.NoError(t, err)
+	idx, err := os.ReadFile(filepath.Join(dir, "wiki", "a", "_index.md"))
+	require.NoError(t, err, "wing _index regenerated")
+	assert.Contains(t, string(idx), "x", "promoted note appears in the index")
+}
+
+// --- RejectNote (hyperguild#81) ---------------------------------------------
+
+func TestRejectHappyPath(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-04-23-fed-sentiment-scrape.md",
+		"---\ncreated_at: 2026-04-23T13:20:07Z\n---\n# Sentiment scrape\n\nbody.\n")
+
+	rel, err := RejectNote(dir, RejectOptions{
+		Filename: "2026-04-23-fed-sentiment-scrape.md", Reason: "generic scrape, not homelab-relevant",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "raw/rejected/2026-04-23-fed-sentiment-scrape.md", rel)
+
+	// Source removed from the pending queue.
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-04-23-fed-sentiment-scrape.md"))
+	assert.True(t, os.IsNotExist(statErr), "source removed from raw/ after reject")
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	s := string(got)
+	assert.Contains(t, s, "created_at: 2026-04-23T13:20:07Z", "original created_at preserved")
+	assert.Contains(t, s, "rejected_at:")
+	assert.Contains(t, s, "reject_reason: generic scrape, not homelab-relevant")
+	assert.Contains(t, s, "# Sentiment scrape", "body preserved for later reference")
+
+	// Rejected notes never entered the wiki, and are no longer pending.
+	pending, err := ListPending(dir)
+	require.NoError(t, err)
+	assert.Empty(t, pending)
+}
+
+func TestRejectWithoutReason(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "body\n")
+	rel, err := RejectNote(dir, RejectOptions{Filename: "2026-06-01-x.md"})
+	require.NoError(t, err)
+	got, _ := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	assert.NotContains(t, string(got), "reject_reason:", "no reason given, none stamped")
+}
+
+func TestRejectMissingSourceErrors(t *testing.T) {
+	_, err := RejectNote(t.TempDir(), RejectOptions{Filename: "ghost.md"})
+	require.Error(t, err)
+}
+
+func TestRejectRejectsTraversalFilename(t *testing.T) {
+	_, err := RejectNote(t.TempDir(), RejectOptions{Filename: "../escape.md"})
+	require.Error(t, err)
+}
+
+func TestRejectCollisionNoOverwrite(t *testing.T) {
+	dir := t.TempDir()
+	dest := filepath.Join(dir, "raw", "rejected", "x.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(dest), 0o755))
+	require.NoError(t, os.WriteFile(dest, []byte("EXISTING\n"), 0o644))
+	writeRaw(t, dir, "x.md", "NEW\n")
+
+	_, err := RejectNote(dir, RejectOptions{Filename: "x.md"})
+	require.Error(t, err, "collision must error, not overwrite")
+
+	got, _ := os.ReadFile(dest)
+	assert.Equal(t, "EXISTING\n", string(got), "target not overwritten")
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "x.md"))
+	assert.NoError(t, statErr, "source preserved on collision (atomic: no delete without write)")
+}
+
+func TestRejectedNotesAreNotListedAsPendingAgain(t *testing.T) {
+	// ListPending already skips tunnel-candidates-*.md; confirm raw/rejected/
+	// (a subdirectory) doesn't leak into the top-level pending listing either
+	// — os.ReadDir on raw/ doesn't recurse, but pin it so a future change to
+	// ListPending can't silently start surfacing rejected notes as pending
+	// again.
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "body\n")
+	_, err := RejectNote(dir, RejectOptions{Filename: "2026-06-01-x.md"})
+	require.NoError(t, err)
+
+	pending, err := ListPending(dir)
+	require.NoError(t, err)
+	assert.Empty(t, pending, "a rejected note must not still appear as pending")
+}

ingestion/internal/api/provenance.go

@@ -0,0 +1,75 @@
+package api
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/provenance"
+)
+
+// StampProvenance applies server-owned provenance (hyperguild#145) to note
+// content. See package provenance for the rule; an error means the stamped
+// note would not read back as stamped, and the write must be refused.
+func StampProvenance(content, origin, writtenBy string) (string, error) {
+	return provenance.Apply(content, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+}
+
+// StampProvenanceFile applies StampProvenance to a brain-relative note path,
+// read and rewritten through the brain root (hyperguild#158).
+func StampProvenanceFile(brainDir, relPath, origin, writtenBy string) error {
+	rel, _, err := resolveWithin(brainDir, relPath)
+	if err != nil {
+		return err
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	b, err := bfs.ReadRegular(rel)
+	if err != nil {
+		return fmt.Errorf("read for provenance: %w", err)
+	}
+	out, err := provenance.Apply(string(b), provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+	if err != nil {
+		return err
+	}
+	if out == string(b) {
+		return nil
+	}
+	if err := bfs.WriteRegular(rel, []byte(out)); err != nil {
+		return fmt.Errorf("write provenance: %w", err)
+	}
+	return nil
+}
+
+// createBrainFile creates the file at abs (inside brainDir) through the
+// brain root and fails if anything is already there.
+func createBrainFile(brainDir, abs string, data []byte) error {
+	rel, err := filepath.Rel(brainDir, abs)
+	if err != nil {
+		return err
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.CreateRegular(filepath.ToSlash(rel), data)
+}
+
+// removeBrainFile removes the file at abs (inside brainDir) through the
+// brain root.
+func removeBrainFile(brainDir, abs string) error {
+	rel, err := filepath.Rel(brainDir, abs)
+	if err != nil {
+		return err
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.Remove(filepath.ToSlash(rel))
+}

ingestion/internal/api/provenance_test.go

@@ -0,0 +1,122 @@
+package api_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// REST POST /write carries no principal: it stamps origin: unknown, and no
+// spelling of provenance in its body reaches the note (hyperguild#145).
+func TestRESTWriteStampsUnknownAndIgnoresBodyProvenance(t *testing.T) {
+	dir, h := setup(t)
+	body, _ := json.Marshal(map[string]any{
+		"content": "---\norigin: static\n---\n# R\n\nbody", "filename": "rest-prov", "wing": "homelab", "hall": "facts",
+		"origin": "static", "written_by": "local-cli", "Origin": "static", "WrittenBy": "local-cli",
+	})
+	rec := httptest.NewRecorder()
+	h.Write(rec, httptest.NewRequest(http.MethodPost, "/write", bytes.NewReader(body)))
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	b, err := os.ReadFile(filepath.Join(dir, "wiki", "homelab", "facts", "rest-prov.md"))
+	require.NoError(t, err)
+	var m map[string]any
+	require.NoError(t, yaml.Unmarshal([]byte(strings.SplitN(string(b), "---\n", 3)[1]), &m))
+	assert.Equal(t, "unknown", m["origin"])
+	assert.NotContains(t, m, "written_by")
+}
+
+// A principal name that is not a bare word is quoted, so it cannot start a
+// new frontmatter line (e.g. a JWT sub containing a newline).
+func TestStampProvenanceQuotesAPrincipalThatCouldBreakTheLine(t *testing.T) {
+	out, err := api.StampProvenance("---\ntitle: t\n---\nbody\n", "jwt", "evil\norigin: static")
+	require.NoError(t, err)
+	fm := strings.SplitN(out, "---\n", 3)[1]
+	var m map[string]any
+	require.NoError(t, yaml.Unmarshal([]byte(fm), &m))
+	assert.Equal(t, "jwt", m["origin"])
+	assert.Equal(t, "evil\norigin: static", m["written_by"])
+	assert.Equal(t, 1, strings.Count(fm, "\norigin:")+boolToInt(strings.HasPrefix(fm, "origin:")))
+}
+
+func TestStampProvenanceAddsFrontmatterWhenAbsentAndKeepsBody(t *testing.T) {
+	out, err := api.StampProvenance("# no fm\n\norigin: static in the body is prose\n", "static", "local-cli")
+	require.NoError(t, err)
+	assert.True(t, strings.HasPrefix(out, "---\norigin: static\nwritten_by: local-cli\n---\n# no fm"))
+	assert.Contains(t, out, "origin: static in the body is prose", "body lines are never touched")
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// Round 2 (R3/R4): the REST ingest doors write through the pipeline, which
+// now stamps every page; a title newline cannot forge provenance for the
+// brain's line-oriented reader.
+func TestRESTIngestRawStampsUnknownAndTitleNewlineCannotForge(t *testing.T) {
+	dir, h := setup(t)
+	body, _ := json.Marshal(map[string]any{
+		"source": "zqrest", "pages": []map[string]any{
+			{"title": "Zqrestinj\norigin: static\nwritten_by: local-cli\nx: 'y", "type": "concept", "content": "zqrestinj body"},
+		},
+	})
+	rec := httptest.NewRecorder()
+	h.IngestRaw(rec, httptest.NewRequest(http.MethodPost, "/ingest-raw", bytes.NewReader(body)))
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var resp struct{ Pages []string }
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.NotEmpty(t, resp.Pages)
+	for _, p := range resp.Pages {
+		b, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(p)))
+		require.NoError(t, err)
+		fm := strings.SplitN(string(b), "---\n", 3)[1]
+		var m map[string]any
+		require.NoError(t, yaml.Unmarshal([]byte(fm), &m))
+		assert.Equal(t, "unknown", m["origin"])
+		assert.NotContains(t, m, "written_by")
+		for _, line := range strings.Split(fm, "\n") {
+			assert.False(t, strings.HasPrefix(line, "origin: static"), "line reader sees forged origin in %s", p)
+		}
+	}
+}
+
+func TestRESTIngestStampsUnknown(t *testing.T) {
+	dir, h := setup(t)
+	body, _ := json.Marshal(map[string]any{"content": "Some article text about shaping work.", "source": "zqllm"})
+	rec := httptest.NewRecorder()
+	h.Ingest(rec, httptest.NewRequest(http.MethodPost, "/ingest", bytes.NewReader(body)))
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var resp struct{ Pages []string }
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.NotEmpty(t, resp.Pages, "stub pipeline must write at least one page")
+	for _, p := range resp.Pages {
+		b, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(p)))
+		require.NoError(t, err)
+		assert.Contains(t, strings.SplitN(string(b), "---\n", 3)[1], "origin: unknown\n", p)
+	}
+}
+
+// A refused write leaves nothing behind, not even an empty hall directory
+// (brain#21's invariant, round 3 non-blocking finding).
+func TestWriteNoteRefusedForProvenanceLeavesNoDirectory(t *testing.T) {
+	dir := t.TempDir()
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "# x\n\nbody", Wing: "freshwing", Hall: "facts", Filename: "x", Origin: "jwt", WrittenBy: "bad\xff",
+	})
+	require.Error(t, err)
+	_, statErr := os.Stat(filepath.Join(dir, "wiki", "freshwing"))
+	assert.True(t, os.IsNotExist(statErr), "no wing directory may be created by a refused write")
+}

ingestion/internal/api/raw_race_test.go

@@ -0,0 +1,178 @@
+package api_test
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#153 / PR #156: behavioural race tests, so the control does not
+// rest on lints that list forbidden APIs (round 3: an os.ReadFile or
+// Root.ReadFile rewrite passed the lint and leaked 19k times in 4s). A
+// swapper keeps renaming a regular note, a symlink to an outside file, or a
+// FIFO into raw/r.md while the public readers loop. Any leaked byte fails;
+// any hang fails.
+
+const raceSentinel = "SENTINEL-153-RACE"
+
+// startSwapper runs fn until the test ends, and waits for it to exit before
+// t.TempDir's cleanup removes the directory it writes into (hyperguild#162:
+// an unawaited swapper raced the cleanup, "directory not empty").
+func startSwapper(t *testing.T, fn func(stop *atomic.Bool)) {
+	t.Helper()
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() { defer wg.Done(); fn(&stop) }()
+	t.Cleanup(func() { stop.Store(true); wg.Wait() })
+}
+
+func swap(raw, outside string, fifo bool, stop *atomic.Bool) {
+	tgt := filepath.Join(raw, "r.md")
+	for i := 0; !stop.Load(); i++ {
+		tmp := filepath.Join(raw, ".swap")
+		_ = os.Remove(tmp)
+		switch {
+		case i%2 == 0:
+			_ = os.WriteFile(tmp, []byte("# r\n\ninside"), 0o644)
+		case fifo:
+			_ = syscall.Mkfifo(tmp, 0o644)
+		default:
+			_ = os.Symlink(outside, tmp)
+		}
+		_ = os.Rename(tmp, tgt)
+	}
+}
+
+func raceBrain(t *testing.T) (brain, raw, outside string) {
+	t.Helper()
+	brain = t.TempDir()
+	raw = filepath.Join(brain, "raw")
+	if err := os.MkdirAll(raw, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	outside = filepath.Join(t.TempDir(), "secret.md")
+	if err := os.WriteFile(outside, []byte("# s\n\n"+raceSentinel), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(raw, "r.md"), []byte("# r\n\ninside"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return brain, raw, outside
+}
+
+// readers runs every public raw/ reader once and returns all text they
+// produced (excerpts, extracted text).
+func readers(brain, raw string) string {
+	var b strings.Builder
+	if ns, err := api.ListPending(brain); err == nil {
+		for _, n := range ns {
+			b.WriteString(n.Excerpt)
+		}
+	}
+	if s, err := api.ReadIngestFile(brain, filepath.Join(raw, "r.md")); err == nil {
+		b.WriteString(s)
+	}
+	return b.String()
+}
+
+func TestRawReadersLeakNothingUnderASymlinkSwapRace(t *testing.T) {
+	brain, raw, outside := raceBrain(t)
+	startSwapper(t, func(stop *atomic.Bool) { swap(raw, outside, false, stop) })
+	leaks, iters := 0, 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); iters++ {
+		leaks += strings.Count(readers(brain, raw), raceSentinel)
+	}
+	if leaks > 0 {
+		t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters)
+	}
+	t.Logf("%d iterations, 0 leaks", iters)
+}
+
+func TestRawReadersDoNotHangUnderAFIFOSwapRace(t *testing.T) {
+	brain, raw, outside := raceBrain(t)
+	startSwapper(t, func(stop *atomic.Bool) { swap(raw, outside, true, stop) })
+	var iters atomic.Int64
+	done := make(chan struct{})
+	go func() {
+		for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+			_ = readers(brain, raw)
+			iters.Add(1)
+		}
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(6 * time.Second):
+		// Unblock the stuck open so the test process can exit.
+		if f, err := os.OpenFile(filepath.Join(raw, "r.md"), os.O_WRONLY|syscall.O_NONBLOCK, 0); err == nil {
+			_ = f.Close()
+		}
+		t.Fatalf("a raw/ reader hung on a swapped-in FIFO after %d iterations", iters.Load())
+	}
+}
+
+// PR #156 round 4: the pdf/docmark branch of TextIn copies the file through
+// the root to a temp file; pointing the extractor back at the raw/ path by
+// name stayed green because the race tests only used r.md (a stub docmark
+// then received the outside file's bytes 34k times in 4s). This races a
+// symlink into raw/r.docx and has a fake docmark count the sentinel in every
+// document it is sent.
+func TestDocmarkExtractionLeaksNothingUnderASymlinkSwapRace(t *testing.T) {
+	var seen atomic.Int64
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Params struct {
+				Arguments struct {
+					ContentBase64 string `json:"content_base64"`
+				} `json:"arguments"`
+			} `json:"params"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&req)
+		if b, err := base64.StdEncoding.DecodeString(req.Params.Arguments.ContentBase64); err == nil &&
+			strings.Contains(string(b), raceSentinel) {
+			seen.Add(1)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"converted"}]}}`))
+	}))
+	defer srv.Close()
+	t.Setenv("DOCMARK_URL", srv.URL)
+
+	brain, raw, outside := raceBrain(t)
+	tgt := filepath.Join(raw, "r.docx")
+	if err := os.WriteFile(tgt, []byte("inside docx bytes"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	startSwapper(t, func(stop *atomic.Bool) {
+		for i := 0; !stop.Load(); i++ {
+			tmp := filepath.Join(raw, ".swapdocx")
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte("inside docx bytes"), 0o644)
+			} else {
+				_ = os.Symlink(outside, tmp)
+			}
+			_ = os.Rename(tmp, tgt)
+		}
+	})
+	iters := 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); iters++ {
+		_, _ = api.ReadIngestFile(brain, tgt)
+	}
+	if n := seen.Load(); n > 0 {
+		t.Fatalf("docmark received the outside file %d times in %d iterations", n, iters)
+	}
+	t.Logf("%d iterations, 0 leaks to docmark", iters)
+}

ingestion/internal/api/raw_symlink_test.go

@@ -0,0 +1,80 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#153: readers of brain/raw/ followed symlinks. /pending showed the
+// target's contents and promote would copy it into wiki/ (and brain-sync to
+// Gitea). raw/ is writable via Syncthing, so a symlink there is reachable
+// input. Every raw/ reader now treats a symlink as not-a-note.
+const sentinel153 = "SENTINEL-153-OUTSIDE"
+
+func rawWithSymlink(t *testing.T) (brain string) {
+	t.Helper()
+	brain = t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	outside := filepath.Join(t.TempDir(), "secret.md")
+	require.NoError(t, os.WriteFile(outside, []byte("---\ncreated_at: 2026-01-01T00:00:00Z\n---\n# s\n\n"+sentinel153), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(raw, "2026-01-01-leak.md")))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-01-02-real.md"), []byte("# real\n\nreal body"), 0o644))
+	return brain
+}
+
+func TestListPendingSkipsSymlinkedNotes(t *testing.T) {
+	notes, err := api.ListPending(rawWithSymlink(t))
+	require.NoError(t, err)
+	var names []string
+	for _, n := range notes {
+		names = append(names, n.Filename)
+		assert.NotContains(t, n.Excerpt, sentinel153)
+	}
+	assert.Equal(t, []string{"2026-01-02-real.md"}, names)
+}
+
+func TestPromoteNoteRefusesASymlinkedSource(t *testing.T) {
+	brain := rawWithSymlink(t)
+	_, err := api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-01-01-leak.md", Wing: "testing", Hall: "facts"})
+	require.Error(t, err)
+	_, statErr := os.Stat(filepath.Join(brain, "wiki", "testing", "facts", "leak.md"))
+	assert.True(t, os.IsNotExist(statErr), "nothing may be promoted from a symlink")
+}
+
+func TestRejectNoteRefusesASymlinkedSource(t *testing.T) {
+	brain := rawWithSymlink(t)
+	_, err := api.RejectNote(brain, api.RejectOptions{Filename: "2026-01-01-leak.md"})
+	require.Error(t, err)
+	b, _ := os.ReadFile(filepath.Join(brain, "raw", "rejected", "2026-01-01-leak.md"))
+	assert.False(t, strings.Contains(string(b), sentinel153))
+}
+
+// Item 4: if raw/ itself is a symlink, containment inside it means nothing.
+func TestResolvePendingPromoteRejectAndReadIngestRefuseASymlinkedRawRoot(t *testing.T) {
+	brain := t.TempDir()
+	elsewhere := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(elsewhere, "x.md"), []byte("# x\n\n"+sentinel153), 0o644))
+	require.NoError(t, os.Symlink(elsewhere, filepath.Join(brain, "raw")))
+
+	_, err := api.ResolveIngestPath(brain, "x.md")
+	assert.Error(t, err, "ingest must refuse a symlinked raw/")
+	notes, err := api.ListPending(brain)
+	assert.Error(t, err, "pending must refuse a symlinked raw/")
+	assert.Empty(t, notes)
+	_, err = api.PromoteNote(brain, api.PromoteOptions{Filename: "x.md", Wing: "testing", Hall: "facts"})
+	assert.Error(t, err, "promote must refuse a symlinked raw/")
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "x.md"})
+	assert.Error(t, err, "reject must refuse a symlinked raw/")
+	text, err := api.ReadIngestFile(brain, filepath.Join(elsewhere, "x.md"))
+	assert.Error(t, err, "ReadIngestFile must refuse a symlinked raw/")
+	assert.NotContains(t, text, sentinel153)
+	// The watcher's refusal is tested in internal/watcher.
+}

ingestion/internal/api/rawroot.go

@@ -0,0 +1,67 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
+)
+
+// errNotANote is returned for a raw/ entry that is not a regular file — in
+// particular a symlink, whose target may be anywhere (hyperguild#153).
+var errNotANote = errors.New("not a regular note file in raw/ (symlinks are refused)")
+
+// errRawNotDir means brain/raw is not a real directory (e.g. a symlink), so
+// containment inside it would mean nothing (hyperguild#153 item 4).
+var errRawNotDir = errors.New("brain/raw is not a real directory")
+
+// OpenRawRoot opens brain/raw as an os.Root, refusing a raw/ that is itself a
+// symlink. Reads through the root cannot leave it, even if an entry is
+// swapped for a symlink between a check and the read. It returns the root
+// and raw/'s path. A missing raw/ returns an error wrapping os.ErrNotExist.
+func OpenRawRoot(brainDir string) (*os.Root, string, error) {
+	p := filepath.Join(brainDir, "raw")
+	fi, err := os.Lstat(p)
+	if err != nil {
+		return nil, "", err
+	}
+	if fi.Mode()&os.ModeSymlink != 0 || !fi.IsDir() {
+		return nil, "", errRawNotDir
+	}
+	r, err := os.OpenRoot(p)
+	if err != nil {
+		return nil, "", fmt.Errorf("open raw root: %w", err)
+	}
+	return r, p, nil
+}
+
+// readRawNote reads one raw/ entry by basename through the root, refusing
+// anything that is not a regular file.
+//
+// Accepted residual: a HARD link to an outside file is a regular file and is
+// read. Syncthing syncs contents, not links, so a peer cannot create one;
+// fs.protected_hardlinks=1 and the pod's secrets live on a different
+// filesystem from the brain volume, so a local caller cannot link them in.
+// Refusing Nlink > 1 is the next step if either assumption changes.
+func readRawNote(r *os.Root, base string) ([]byte, os.FileInfo, error) {
+	fi, err := r.Lstat(base)
+	if err != nil {
+		return nil, nil, err
+	}
+	if !fi.Mode().IsRegular() {
+		return nil, nil, errNotANote
+	}
+	f, _, err := extract.OpenRegular(r, base)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer func() { _ = f.Close() }()
+	b, err := io.ReadAll(f)
+	if err != nil {
+		return nil, nil, err
+	}
+	return b, fi, nil
+}

ingestion/internal/api/readnote_root_test.go

@@ -0,0 +1,52 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+// hyperguild#157 slice 2: ReadNote (brain_get, read-after-write) read by
+// path; it now reads through brainfs.
+func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+	_, body, _, err := api.ReadNote(brain, "wiki/w/facts/leak.md")
+	assert.Error(t, err)
+	assert.NotContains(t, body, brainfstest.Sentinel)
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it (hyperguild#171).
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	_, body, _, err = api.ReadNote(brain, "wiki/w/facts/inlink.md")
+	assert.Error(t, err)
+	assert.NotContains(t, body, brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644))
+	fm, body, _, err := api.ReadNote(brain, "wiki/w/facts/r.md")
+	require.NoError(t, err)
+	assert.Equal(t, "y", fm["x"])
+	assert.Contains(t, body, "inside")
+	read := func() string {
+		fm, body, _, _ := api.ReadNote(brain, "wiki/w/facts/r.md")
+		s := body
+		for k, v := range fm {
+			s += k + v
+		}
+		return s
+	}
+	brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, read)
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}

ingestion/internal/api/update.go

@@ -0,0 +1,215 @@
+package api
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/notes"
+)
+
+// ContentHash returns the lowercase hex sha256 of b. It is the note's
+// content_hash handle: brain_write / brain_update return it, brain_get
+// recomputes it from the file on disk, and brain_update stamps the prior
+// note's hash into the new note's `supersedes` frontmatter.
+func ContentHash(b []byte) string {
+	sum := sha256.Sum256(b)
+	return hex.EncodeToString(sum[:])
+}
+
+// resolveWithin maps a brainDir-relative path to an absolute path and
+// guarantees it does not escape brainDir. Returns the cleaned relPath
+// (forward-slashed) and the absolute path.
+func resolveWithin(brainDir, relPath string) (rel, abs string, err error) {
+	clean := filepath.Clean("/" + filepath.ToSlash(relPath))
+	rel = strings.TrimPrefix(clean, "/")
+	abs = filepath.Join(brainDir, filepath.FromSlash(rel))
+	check, err := filepath.Rel(brainDir, abs)
+	if err != nil || check == ".." || strings.HasPrefix(check, ".."+string(filepath.Separator)) {
+		return "", "", fmt.Errorf("path %q escapes brain dir", relPath)
+	}
+	return rel, abs, nil
+}
+
+// UpdateNoteOptions identifies the note to supersede and supplies its new
+// body. Path takes precedence; otherwise the target is resolved from
+// Wing/Hall/Slug via brain.NotePath.
+type UpdateNoteOptions struct {
+	Path    string // brainDir-relative path; takes precedence over wing/hall/slug
+	Wing    string
+	Hall    string
+	Slug    string
+	Content string // new full body (whole-note replace)
+	Reason  string // optional; stamped as supersede_reason
+	// Origin/WrittenBy re-stamp provenance to the updating principal: the
+	// body is replaced wholesale, so the last writer is the author of what
+	// a reader sees (hyperguild#145). Never taken from Content's fragment.
+	Origin    string
+	WrittenBy string
+}
+
+// UpdateNote supersedes an existing note in place. It replaces the body
+// with opts.Content, preserves the existing frontmatter (created_at,
+// wing, hall, and any custom fields), and stamps updated_at, supersedes
+// (the prior content hash), and supersede_reason (when given).
+//
+// It never creates: if the target does not exist, it returns an error so
+// the caller can fall back to brain_write. Returns the note's relPath,
+// the new content hash, and the prior content hash.
+//
+// Embeddings are NOT refreshed here. The rewritten file's mtime advances,
+// which the mtime-driven vectorstore.Sync ticker uses to re-embed it on
+// its next pass — the same out-of-band mechanism brain_write relies on.
+func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash, priorHash string, err error) {
+	if opts.Content == "" {
+		return "", "", "", fmt.Errorf("content is required")
+	}
+
+	// Same reason as WriteNote: the strip belongs in the primitive so every
+	// door inherits it.
+	clean, _, err := brain.StripUnresolvedLinks(brainDir, opts.Content)
+	if err != nil {
+		return "", "", "", err
+	}
+	opts.Content = clean
+
+	var rel string
+	if opts.Path != "" {
+		rel = opts.Path
+	} else {
+		full, perr := brain.NotePath(brainDir, opts.Wing, opts.Hall, opts.Slug)
+		if perr != nil {
+			return "", "", "", perr
+		}
+		rel, _ = filepath.Rel(brainDir, full)
+		rel = filepath.ToSlash(rel)
+	}
+
+	// The path is caller-supplied (brain_update): resolve it as brain_edit
+	// does, knowledge/ and wiki/ notes only, and read and rewrite it through
+	// the brain root, never through a symlink (hyperguild#169).
+	t, err := notes.Resolve(brainDir, rel, notes.ScopeNotes)
+	if err != nil {
+		return "", "", "", err
+	}
+	rel = t.Rel
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return "", "", "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+
+	prior, err := bfs.ReadRegular(rel)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return "", "", "", fmt.Errorf("note %q does not exist: use brain_write to create", rel)
+		}
+		return "", "", "", fmt.Errorf("read target: %w", err)
+	}
+	priorHash = ContentHash(prior)
+
+	// A caller may lead opts.Content with its own frontmatter fence to set or
+	// change fields on supersede (e.g. the claim envelope). Split it off
+	// before it reaches the body — left un-split, it would render as a
+	// second, inert `---`-fenced block of literal text rather than taking
+	// effect, and any claim-envelope fields inside it would reach disk
+	// unvalidated (hyperguild#111: the same rule that guards note birth in
+	// writeHallNote must guard a change to the same fields).
+	contentFM, contentBody := parseFrontmatter(opts.Content)
+
+	fm, _ := parseFrontmatter(string(prior))
+	for _, l := range contentFM.lines {
+		// updated_at/supersedes/supersede_reason are this function's own
+		// output, not something a caller's fragment sets — updated_at and
+		// supersedes are already unconditionally re-set below regardless of
+		// what the loop does with them, but supersede_reason is only
+		// re-set when opts.Reason is non-empty, so without this skip a
+		// caller could set it via its own fragment and have it survive
+		// even when Reason is empty, bypassing the one intended entry
+		// point for that field (hyperguild#125, found in #111's review).
+		// Skipping all three here rather than relying on the unconditional
+		// overwrites below to save the other two keeps the invariant
+		// explicit at the one place it can be silently broken by a future
+		// reordering, not implicit in call order.
+		if l.key == "" || l.key == "updated_at" || l.key == "supersedes" || l.key == "supersede_reason" ||
+			l.key == "origin" || l.key == "written_by" {
+			continue
+		}
+		fm.set(l.key, l.value)
+	}
+	fm.set("updated_at", time.Now().UTC().Format(time.RFC3339))
+	fm.set("supersedes", priorHash)
+	if opts.Reason != "" {
+		fm.set("supersede_reason", opts.Reason)
+	}
+
+	// Validate the envelope AFTER the merge, against the full field set that
+	// is about to reach disk — not just the caller's fragment. Validating the
+	// fragment alone would miss a caller that supersedes claim_provenance to
+	// empty while half_life/applies survive untouched from the prior note:
+	// each side looks individually fine, but the merged result is an
+	// unprovenanced envelope, which is the exact laundering this check
+	// exists to catch. (Caught in review before merge, not filed after —
+	// worth being honest about in the history: this second pass was the
+	// actual fix; the first one validated the wrong document.)
+	envelope := make(map[string]string, len(fm.lines))
+	for _, l := range fm.lines {
+		if l.key != "" {
+			envelope[l.key] = l.value
+		}
+	}
+	if err := claim.ValidateEnvelope(envelope); err != nil {
+		return "", "", "", fmt.Errorf("claim envelope: %w", err)
+	}
+
+	stamped, err := StampProvenance(fm.render()+contentBody, opts.Origin, opts.WrittenBy)
+	if err != nil {
+		return "", "", "", err
+	}
+	out := []byte(stamped)
+	if err := bfs.WriteRegular(rel, out); err != nil {
+		return "", "", "", fmt.Errorf("write: %w", err)
+	}
+	return rel, ContentHash(out), priorHash, nil
+}
+
+// ReadNote reads the note at the brainDir-relative relPath and returns
+// its parsed frontmatter, body, and content hash. It is the read-after-
+// write primitive behind brain_get: the hash it returns equals the hash
+// brain_write / brain_update returned for the same bytes.
+func ReadNote(brainDir, relPath string) (fm map[string]string, body, contentHash string, err error) {
+	rel, _, err := resolveWithin(brainDir, relPath)
+	if err != nil {
+		return nil, "", "", err
+	}
+	// Through the brain root, regular files only (hyperguild#157).
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, "", "", fmt.Errorf("read note: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	raw, err := bfs.ReadRegular(rel)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, "", "", fmt.Errorf("note %q does not exist", relPath)
+		}
+		return nil, "", "", fmt.Errorf("read note: %w", err)
+	}
+	parsed, body := parseFrontmatter(string(raw))
+	fm = make(map[string]string, len(parsed.lines))
+	for _, l := range parsed.lines {
+		if l.key != "" {
+			fm[l.key] = l.value
+		}
+	}
+	return fm, body, ContentHash(raw), nil
+}

ingestion/internal/api/update_redirect_test.go

@@ -0,0 +1,36 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// hyperguild#173: a directory symlink inside wiki/ that points elsewhere in
+// the brain redirected brain_update's write (os.Root follows in-root
+// intermediate symlinks). Every directory above the note must be real.
+func TestUpdateNoteRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	brain := t.TempDir()
+	victim := filepath.Join(brain, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("---\ntitle: v\n---\nuntouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(brain, "wiki", "w", "alias")))
+
+	_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/alias/v.md", Content: "replaced"})
+	assert.ErrorIs(t, err, brainfs.ErrNotRegular)
+	got, _ := os.ReadFile(victim)
+	assert.Contains(t, string(got), "untouched")
+
+	real := filepath.Join(brain, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("---\ntitle: r\n---\nold\n"), 0o644))
+	_, _, _, err = api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/r.md", Content: "new"})
+	require.NoError(t, err, "positive control: a note in a real directory is updated")
+}

ingestion/internal/api/update_scope_test.go

@@ -0,0 +1,112 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// brain_update passed the caller's path through resolveWithin, a lexical
+// containment check only: any file in the brain could be superseded
+// (classification.yaml, raw/, sessions/), and a final symlink was written
+// through. It now resolves like brain_edit: knowledge/ and wiki/ notes only,
+// read and rewritten through the brain root.
+func TestUpdateNoteRefusesPathsOutsideKnowledgeAndWikiNotes(t *testing.T) {
+	brain := t.TempDir()
+	files := map[string]string{
+		"classification.yaml": "levels: {}\n",
+		"raw/r.md":            "raw\n",
+		"sessions/s.jsonl":    "{}\n",
+		"wiki/w/facts/ok.md":  "---\ntitle: ok\n---\nold\n",
+		"knowledge/k.md":      "---\ntitle: k\n---\nold\n",
+		"wiki/w/facts/x.txt":  "txt\n",
+	}
+	for rel, body := range files {
+		p := filepath.Join(brain, filepath.FromSlash(rel))
+		require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
+		require.NoError(t, os.WriteFile(p, []byte(body), 0o644))
+	}
+	for _, rel := range []string{"classification.yaml", "raw/r.md", "sessions/s.jsonl", "wiki/w/facts/x.txt", "wiki/w/../../raw/r.md"} {
+		_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: rel, Content: "replaced"})
+		assert.Error(t, err, rel)
+	}
+	for rel, body := range files {
+		if rel == "wiki/w/facts/ok.md" || rel == "knowledge/k.md" {
+			continue
+		}
+		got, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+		require.NoError(t, err)
+		assert.Equal(t, body, string(got), rel)
+	}
+	for _, rel := range []string{"wiki/w/facts/ok.md", "knowledge/k.md"} {
+		_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: rel, Content: "new body"})
+		require.NoError(t, err, "positive control: %s", rel)
+		got, _ := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+		assert.Contains(t, string(got), "new body")
+	}
+}
+
+func TestUpdateNoteDoesNotWriteThroughASymlinkedNote(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	victim := filepath.Join(brain, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), filepath.Join(facts, "l.md")))
+	_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/l.md", Content: "replaced"})
+	assert.Error(t, err)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+}
+
+// The note is swapped between a regular file and an in-brain symlink to a
+// raw/ file while UpdateNote runs: the read and the write each refuse a
+// symlink, so the raw/ file is never rewritten.
+func TestUpdateNoteNeverRewritesASymlinkSwappedInForTheNote(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	victim := filepath.Join(brain, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	note := filepath.Join(facts, "n.md")
+	body := "---\ntitle: n\n---\nold\n"
+	require.NoError(t, os.WriteFile(note, []byte(body), 0o644))
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := note + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte(body), 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, note)
+		}
+	}()
+	ok := 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		if _, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/n.md", Content: "new"}); err == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	wg.Wait()
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+	assert.Positive(t, ok, "positive control: some updates reach the regular note")
+}

ingestion/internal/api/update_test.go

@@ -0,0 +1,277 @@
+package api
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// seedNote writes a note directly to disk and returns its relPath.
+func seedNote(t *testing.T, brainDir, rel, content string) string {
+	t.Helper()
+	full := filepath.Join(brainDir, filepath.FromSlash(rel))
+	require.NoError(t, os.MkdirAll(filepath.Dir(full), 0o755))
+	require.NoError(t, os.WriteFile(full, []byte(content), 0o644))
+	return rel
+}
+
+func TestUpdateNoteSupersedesAndStamps(t *testing.T) {
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md",
+		"---\nwing: jepa-fx\nhall: facts\ncreated_at: 2026-01-01T00:00:00Z\ncustom: keep-me\n---\n# Old\n\nold body\n")
+
+	relPath, hash, priorHash, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "# New\n\nnew body\n",
+		Reason:  "facts changed",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, rel, relPath)
+	assert.NotEmpty(t, hash)
+	assert.NotEmpty(t, priorHash)
+	assert.NotEqual(t, hash, priorHash)
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	s := string(got)
+	// Body replaced.
+	assert.Contains(t, s, "# New")
+	assert.NotContains(t, s, "old body")
+	// Prior fields preserved.
+	assert.Contains(t, s, "wing: jepa-fx")
+	assert.Contains(t, s, "hall: facts")
+	assert.Contains(t, s, "created_at: 2026-01-01T00:00:00Z")
+	assert.Contains(t, s, "custom: keep-me")
+	// Supersession stamped.
+	assert.Contains(t, s, "updated_at:")
+	assert.Contains(t, s, "supersedes: "+priorHash)
+	assert.Contains(t, s, "supersede_reason: facts changed")
+}
+
+func TestUpdateNoteRejectsInvalidEnvelopeAndWritesNothing(t *testing.T) {
+	// hyperguild#111: WriteNote validates the claim envelope before create;
+	// UpdateNote didn't before supersede, so the same rule must hold on
+	// change as on birth, fail-closed, nothing written on rejection.
+	brainDir := t.TempDir()
+	original := "---\nwing: jepa-fx\nhall: facts\ncreated_at: 2026-01-01T00:00:00Z\n---\n# Old\n\nold body\n"
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md", original)
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "---\nhalf_life: forever\n---\n# New\n\nnew body\n",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "claim envelope")
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Equal(t, original, string(got), "rejected update must leave the note byte-identical")
+}
+
+func TestUpdateNoteRejectsAppliesWithoutProvenance(t *testing.T) {
+	brainDir := t.TempDir()
+	original := "---\nwing: jepa-fx\nhall: facts\n---\nold\n"
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md", original)
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "---\napplies: universal\n---\nnew\n",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "claim envelope")
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Equal(t, original, string(got))
+}
+
+func TestUpdateNoteAcceptsValidEnvelopeAndMergesIntoFrontmatter(t *testing.T) {
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md",
+		"---\nwing: jepa-fx\nhall: facts\ncreated_at: 2026-01-01T00:00:00Z\n---\nold\n")
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "---\nhalf_life: durable\napplies: universal\nclaim_provenance: asserted\n---\nnew body\n",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	s := string(got)
+	assert.Contains(t, s, "half_life: durable")
+	assert.Contains(t, s, "applies: universal")
+	assert.Contains(t, s, "claim_provenance: asserted")
+	assert.Contains(t, s, "wing: jepa-fx", "prior fields survive")
+	assert.Contains(t, s, "new body")
+	assert.Equal(t, 2, strings.Count(s, "---\n"),
+		"exactly one open+close fence pair — the caller's own fence must not leak in as a second, inert block")
+}
+
+func TestUpdateNoteRejectsClearingProvenanceWhileEnvelopeSurvives(t *testing.T) {
+	// Found in review, not written speculatively: validating only the
+	// caller's fragment (rather than the merged result) let a caller blank
+	// out claim_provenance alone while half_life/applies survived from the
+	// prior note untouched — each side looks fine on its own, the merged
+	// envelope on disk is the unprovenanced one the whole check exists to
+	// catch.
+	brainDir := t.TempDir()
+	original := "---\nwing: jepa-fx\nhall: facts\nhalf_life: durable\napplies: universal\nclaim_provenance: asserted\n---\nold\n"
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md", original)
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "---\nclaim_provenance: \n---\nnew body\n",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "claim envelope")
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Equal(t, original, string(got), "rejected update must leave the note byte-identical")
+}
+
+func TestUpdateNoteWithoutEnvelopeFieldsIsUnchangedFromToday(t *testing.T) {
+	// Regression pin: plain fence-less content (the common case) must behave
+	// exactly as it did before the envelope-merge fix.
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md",
+		"---\nwing: jepa-fx\nhall: facts\ncreated_at: 2026-01-01T00:00:00Z\ncustom: keep-me\n---\n# Old\n\nold body\n")
+
+	relPath, hash, priorHash, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "# New\n\nnew body\n",
+		Reason:  "facts changed",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, rel, relPath)
+	assert.NotEmpty(t, hash)
+	assert.NotEqual(t, hash, priorHash)
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	s := string(got)
+	assert.Contains(t, s, "# New")
+	assert.Contains(t, s, "custom: keep-me")
+	assert.Contains(t, s, "supersedes: "+priorHash)
+}
+
+func TestUpdateNoteResolvesByWingHallSlug(t *testing.T) {
+	brainDir := t.TempDir()
+	seedNote(t, brainDir, "wiki/jepa-fx/facts/val-vol.md",
+		"---\nwing: jepa-fx\nhall: facts\n---\nold\n")
+
+	relPath, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Wing: "jepa-fx", Hall: "facts", Slug: "val-vol",
+		Content: "new\n",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "wiki/jepa-fx/facts/val-vol.md", relPath)
+}
+
+func TestUpdateNoteErrorsOnMissingAndDoesNotCreate(t *testing.T) {
+	brainDir := t.TempDir()
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Wing: "jepa-fx", Hall: "facts", Slug: "ghost",
+		Content: "x\n",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "does not exist")
+
+	// No file created.
+	_, statErr := os.Stat(filepath.Join(brainDir, "wiki/jepa-fx/facts/ghost.md"))
+	assert.True(t, os.IsNotExist(statErr), "missing-target update must not create a note")
+}
+
+func TestUpdateNoteRejectsTraversal(t *testing.T) {
+	brainDir := t.TempDir()
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    "../escape.md",
+		Content: "x\n",
+	})
+	require.Error(t, err)
+}
+
+func TestReadNoteReturnsFrontmatterBodyHash(t *testing.T) {
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/jepa-fx/facts/n.md",
+		"---\nwing: jepa-fx\nhall: facts\n---\n# Body\n\ntext\n")
+
+	fm, body, hash, err := ReadNote(brainDir, rel)
+	require.NoError(t, err)
+	assert.Equal(t, "jepa-fx", fm["wing"])
+	assert.Equal(t, "facts", fm["hall"])
+	assert.Equal(t, "# Body\n\ntext\n", body)
+
+	// Hash matches ContentHash of the raw bytes on disk (round-trip).
+	raw, _ := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	assert.Equal(t, ContentHash(raw), hash)
+}
+
+func TestReadNoteRejectsTraversal(t *testing.T) {
+	brainDir := t.TempDir()
+	_, _, _, err := ReadNote(brainDir, "../../etc/passwd")
+	require.Error(t, err)
+}
+
+func TestUpdateThenReadRoundTripsHash(t *testing.T) {
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/a/facts/n.md", "---\nwing: a\nhall: facts\n---\nold\n")
+
+	_, hash, _, err := UpdateNote(brainDir, UpdateNoteOptions{Path: rel, Content: "new\n"})
+	require.NoError(t, err)
+
+	_, _, readHash, err := ReadNote(brainDir, rel)
+	require.NoError(t, err)
+	assert.Equal(t, hash, readHash, "update content_hash must round-trip through ReadNote")
+}
+
+func TestUpdateNoteSupersedeReasonNotSettableViaCallerFragmentWhenReasonOptionEmpty(t *testing.T) {
+	// hyperguild#125, found in #111's review: the merge loop applied every
+	// field from the caller's leading frontmatter fragment, including
+	// supersede_reason -- which is only re-set unconditionally when
+	// opts.Reason is non-empty, so a caller could set it via its own
+	// fragment and have it survive even with Reason left empty, bypassing
+	// the one intended entry point for that field.
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/a/facts/n.md", "---\nwing: a\nhall: facts\n---\nold\n")
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path:    rel,
+		Content: "---\nsupersede_reason: snuck in via the fragment\n---\nnew\n",
+		// Reason deliberately left empty.
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.NotContains(t, string(got), "supersede_reason",
+		"supersede_reason must not appear at all when opts.Reason is empty, regardless of what the fragment tried to set")
+}
+
+func TestUpdateNoteSupersedeReasonFromOptionStillWorks(t *testing.T) {
+	// Regression pin: the legitimate entry point (opts.Reason) must be
+	// completely unaffected by #125's fix.
+	brainDir := t.TempDir()
+	rel := seedNote(t, brainDir, "wiki/a/facts/n.md", "---\nwing: a\nhall: facts\n---\nold\n")
+
+	_, _, _, err := UpdateNote(brainDir, UpdateNoteOptions{
+		Path: rel, Content: "new\n", Reason: "facts changed",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "supersede_reason: facts changed")
+}
+
+func TestContentHashStable(t *testing.T) {
+	assert.Equal(t, ContentHash([]byte("abc")), ContentHash([]byte("abc")))
+	assert.NotEqual(t, ContentHash([]byte("abc")), ContentHash([]byte("abd")))
+	assert.True(t, strings.HasPrefix(ContentHash([]byte("")), "")) // hex, non-panicking
+}

ingestion/internal/api/write_keeps_learning_test.go

@@ -0,0 +1,34 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#178: an unreadable directory under wiki/ made the link check
+// fail and brain_write refuse the note, losing the learning. The note is now
+// written with its links as given.
+func TestWriteNoteKeepsTheLearningWhenTheLinkCheckCannotIndex(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "w", "facts", "real.md"), []byte("x"), 0o644))
+	locked := filepath.Join(brain, "wiki", "other", "locked")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+
+	rel, err := api.WriteNote(brain, api.WriteNoteOptions{Wing: "w", Hall: "facts", Filename: "n", Content: "learning [[real]] and [[gone]]"})
+	require.NoError(t, err)
+	got, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "[[gone]]", "links kept as given when the index is partial")
+}

ingestion/internal/api/write_redirect_test.go

@@ -0,0 +1,43 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#188: brain_write created a new note with os.MkdirAll +
+// os.WriteFile by path, so a symlinked wing directory redirected the note
+// elsewhere in the brain or outside it.
+func TestWriteNoteRefusesASymlinkedWing(t *testing.T) {
+	for name, target := range map[string]func(t *testing.T, brain string) string{
+		"in-brain": func(t *testing.T, brain string) string {
+			require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+			return filepath.Join("..", "raw")
+		},
+		"outside": func(t *testing.T, _ string) string { return t.TempDir() },
+	} {
+		t.Run(name, func(t *testing.T) {
+			brain := t.TempDir()
+			require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+			link := target(t, brain)
+			require.NoError(t, os.Symlink(link, filepath.Join(brain, "wiki", "lw")))
+			_, err := api.WriteNote(brain, api.WriteNoteOptions{Wing: "lw", Hall: "facts", Filename: "n", Content: "learning"})
+			assert.Error(t, err)
+			resolved := link
+			if !filepath.IsAbs(resolved) {
+				resolved = filepath.Join(brain, "wiki", link)
+			}
+			_, serr := os.Stat(filepath.Join(resolved, "facts"))
+			assert.True(t, os.IsNotExist(serr), "a hall was created at the link's target")
+
+			_, err = api.WriteNote(brain, api.WriteNoteOptions{Wing: "w", Hall: "facts", Filename: "n", Content: "learning"})
+			require.NoError(t, err, "positive control: a real wing is written")
+		})
+	}
+}

ingestion/internal/audit/buffer.go

@@ -0,0 +1,167 @@
+package audit
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+)
+
+// FileBuffer is a durable, restart-surviving audit buffer backed by a
+// JSONL file: one {id, entry} record per line. It is the internal/public
+// tier fallback when loki is unreachable. Confirm rewrites the file
+// without the confirmed record, so a record is cleared only after its
+// central write is confirmed.
+//
+// Access is serialised by a mutex; the buffer is low-throughput (only
+// written during a loki outage), so a whole-file rewrite on Confirm is
+// acceptable and keeps the on-disk format trivially correct.
+type FileBuffer struct {
+	path string
+	mu   sync.Mutex
+}
+
+type bufferLine struct {
+	ID    string             `json:"id"`
+	Entry capture.AuditEntry `json:"entry"`
+}
+
+// NewFileBuffer returns a buffer backed by path. The parent directory is
+// created if needed. The file itself is created lazily on first Append.
+func NewFileBuffer(path string) (*FileBuffer, error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return nil, fmt.Errorf("create buffer dir: %w", err)
+	}
+	return &FileBuffer{path: path}, nil
+}
+
+// Writable reports whether the buffer file can be appended to. It probes
+// by opening the file for append (creating it if absent) — the same
+// operation Append performs — so Reserve's check matches Append's reality.
+func (b *FileBuffer) Writable() error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	f, err := os.OpenFile(b.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+// Append durably writes one audit record. The ID is derived from the
+// content + timestamp so it is stable and unique per record.
+func (b *FileBuffer) Append(e capture.AuditEntry) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	line := bufferLine{ID: recordID(e), Entry: e}
+	data, err := json.Marshal(line)
+	if err != nil {
+		return fmt.Errorf("marshal buffer line: %w", err)
+	}
+	f, err := os.OpenFile(b.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	if _, err := f.Write(append(data, '\n')); err != nil {
+		return err
+	}
+	return f.Sync()
+}
+
+// Pending reads all buffered records. A missing file means none.
+func (b *FileBuffer) Pending() ([]Buffered, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.readAllLocked()
+}
+
+func (b *FileBuffer) readAllLocked() ([]Buffered, error) {
+	f, err := os.Open(b.path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	defer func() { _ = f.Close() }()
+
+	var out []Buffered
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for sc.Scan() {
+		raw := sc.Bytes()
+		if len(raw) == 0 {
+			continue
+		}
+		var l bufferLine
+		if err := json.Unmarshal(raw, &l); err != nil {
+			return nil, fmt.Errorf("parse buffer line: %w", err)
+		}
+		out = append(out, Buffered(l))
+	}
+	return out, sc.Err()
+}
+
+// Confirm removes a single record after its central write is confirmed, by
+// rewriting the file without it. Unknown IDs are a no-op.
+func (b *FileBuffer) Confirm(id string) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	all, err := b.readAllLocked()
+	if err != nil {
+		return err
+	}
+	tmp := b.path + ".tmp"
+	f, err := os.OpenFile(tmp, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	w := bufio.NewWriter(f)
+	kept := 0
+	for _, rec := range all {
+		if rec.ID == id {
+			continue
+		}
+		data, _ := json.Marshal(bufferLine(rec))
+		if _, err := w.Write(append(data, '\n')); err != nil {
+			_ = f.Close()
+			return err
+		}
+		kept++
+	}
+	if err := w.Flush(); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err := f.Sync(); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err := f.Close(); err != nil {
+		return err
+	}
+	// Empty buffer → remove the file entirely so Pending sees nothing.
+	if kept == 0 {
+		_ = os.Remove(tmp)
+		return os.Remove(b.path)
+	}
+	return os.Rename(tmp, b.path)
+}
+
+// recordID is a stable per-record identifier: sha256 of the principal,
+// timestamp, and item list. Distinct captures never collide; the same
+// buffered record always hashes the same.
+func recordID(e capture.AuditEntry) string {
+	h := sha256.New()
+	_, _ = fmt.Fprintf(h, "%s|%s|%v|%s", e.Principal, e.Timestamp.UTC().Format("2006-01-02T15:04:05.000000000Z07:00"), e.Items, e.SessionRef)
+	return hex.EncodeToString(h.Sum(nil))[:16]
+}

ingestion/internal/audit/degrading.go

@@ -0,0 +1,96 @@
+package audit
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+)
+
+// Central is the central audit substrate (loki). Ready is a cheap
+// reachability probe used by the pre-write reserve; Push writes a record.
+type Central interface {
+	Ready(ctx context.Context) error
+	Push(ctx context.Context, e capture.AuditEntry) error
+}
+
+// Buffer is the durable local fallback for internal/public-tier records
+// when the central sink is unreachable. It must survive process restart.
+type Buffer interface {
+	// Writable reports whether the buffer can currently be appended to.
+	Writable() error
+	Append(e capture.AuditEntry) error
+	// Pending returns buffered records awaiting reconciliation, each with a
+	// stable ID used to Confirm (delete) it after a confirmed central write.
+	Pending() ([]Buffered, error)
+	Confirm(id string) error
+}
+
+// Buffered is a buffered audit record plus its stable buffer ID.
+type Buffered struct {
+	ID    string
+	Entry capture.AuditEntry
+}
+
+// Notifier raises an out-of-band alert (ntfy) about a degraded state.
+type Notifier interface {
+	Notify(ctx context.Context, msg string) error
+}
+
+// DegradingSink is the classification-aware AuditSink (§4.4):
+//
+//   - central reachable → AuditCentral (all tiers).
+//   - central down + confidential → refuse (no buffer): confidential must
+//     be centrally auditable at write time.
+//   - central down + internal/public + buffer writable → AuditBuffered.
+//   - central down + (confidential, or buffer not writable) → refuse (floor).
+//
+// The decision is made in Reserve, before any write; Record then executes it.
+type DegradingSink struct {
+	central  Central
+	buffer   Buffer
+	notifier Notifier
+}
+
+// NewDegradingSink wires the central sink, durable buffer, and notifier.
+func NewDegradingSink(central Central, buffer Buffer, notifier Notifier) *DegradingSink {
+	return &DegradingSink{central: central, buffer: buffer, notifier: notifier}
+}
+
+// Reserve decides, before any write, how the capture will be audited — or
+// returns an error to refuse it.
+func (d *DegradingSink) Reserve(ctx context.Context, level classification.Level) (capture.AuditOutcome, error) {
+	if err := d.central.Ready(ctx); err == nil {
+		return capture.AuditCentral, nil
+	}
+	// Central sink is down.
+	if level == classification.Confidential {
+		return 0, fmt.Errorf("confidential capture requires the central audit sink, which is unreachable")
+	}
+	if err := d.buffer.Writable(); err != nil {
+		// Floor: neither central nor local buffer can record the audit.
+		return 0, fmt.Errorf("audit floor: central sink down and local buffer unwritable: %w", err)
+	}
+	return capture.AuditBuffered, nil
+}
+
+// Record persists the entry per the reserved outcome. For AuditBuffered it
+// also fires the degraded-state alert.
+func (d *DegradingSink) Record(ctx context.Context, e capture.AuditEntry, outcome capture.AuditOutcome) error {
+	switch outcome {
+	case capture.AuditBuffered:
+		if err := d.buffer.Append(e); err != nil {
+			return fmt.Errorf("buffer audit record: %w", err)
+		}
+		// Best-effort alert; the record is already durably buffered.
+		if d.notifier != nil {
+			_ = d.notifier.Notify(ctx, fmt.Sprintf(
+				"capture audit BUFFERED LOCALLY (loki unreachable) — principal=%s class=%s items=%d",
+				e.Principal, e.EffectiveClassification, len(e.Items)))
+		}
+		return nil
+	default:
+		return d.central.Push(ctx, e)
+	}
+}

ingestion/internal/audit/degrading_test.go

@@ -0,0 +1,191 @@
+package audit_test
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// --- fakes ---
+
+type fakeCentral struct {
+	down    bool
+	pushed  []capture.AuditEntry
+	pushErr error
+}
+
+func (f *fakeCentral) Ready(context.Context) error {
+	if f.down {
+		return errors.New("loki down")
+	}
+	return nil
+}
+
+func (f *fakeCentral) Push(_ context.Context, e capture.AuditEntry) error {
+	if f.pushErr != nil {
+		return f.pushErr
+	}
+	f.pushed = append(f.pushed, e)
+	return nil
+}
+
+type fakeNotifier struct{ msgs []string }
+
+func (f *fakeNotifier) Notify(_ context.Context, msg string) error {
+	f.msgs = append(f.msgs, msg)
+	return nil
+}
+
+// unwritableBuffer always reports it cannot be written (floor condition).
+type unwritableBuffer struct{}
+
+func (unwritableBuffer) Writable() error                    { return errors.New("disk full") }
+func (unwritableBuffer) Append(capture.AuditEntry) error    { return errors.New("disk full") }
+func (unwritableBuffer) Pending() ([]audit.Buffered, error) { return nil, nil }
+func (unwritableBuffer) Confirm(string) error               { return nil }
+
+func newFileBuffer(t *testing.T) *audit.FileBuffer {
+	t.Helper()
+	b, err := audit.NewFileBuffer(filepath.Join(t.TempDir(), "audit-buffer.jsonl"))
+	require.NoError(t, err)
+	return b
+}
+
+func entry(principal string) capture.AuditEntry {
+	return capture.AuditEntry{Principal: principal, EffectiveClassification: "internal", Items: []string{"insight:x"}}
+}
+
+// --- Reserve: classification-aware decision ---
+
+func TestReserveCentralUpGrantsCentral(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{}, newFileBuffer(t), &fakeNotifier{})
+	for _, lvl := range []classification.Level{classification.Public, classification.Internal, classification.Confidential} {
+		out, err := d.Reserve(context.Background(), lvl)
+		require.NoError(t, err)
+		assert.Equal(t, capture.AuditCentral, out)
+	}
+}
+
+func TestReserveConfidentialSinkDownRefuses(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, newFileBuffer(t), &fakeNotifier{})
+	_, err := d.Reserve(context.Background(), classification.Confidential)
+	require.Error(t, err, "confidential + sink down → refuse, no buffer")
+}
+
+func TestReserveInternalSinkDownBuffers(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, newFileBuffer(t), &fakeNotifier{})
+	out, err := d.Reserve(context.Background(), classification.Internal)
+	require.NoError(t, err)
+	assert.Equal(t, capture.AuditBuffered, out)
+}
+
+func TestReserveFloorRefusesWhenNothingCanRecord(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, unwritableBuffer{}, &fakeNotifier{})
+	_, err := d.Reserve(context.Background(), classification.Internal)
+	require.Error(t, err, "central down AND buffer unwritable → floor refuse")
+}
+
+// --- Record: executes the reserved outcome ---
+
+func TestRecordCentralPushes(t *testing.T) {
+	c := &fakeCentral{}
+	d := audit.NewDegradingSink(c, newFileBuffer(t), &fakeNotifier{})
+	require.NoError(t, d.Record(context.Background(), entry("p"), capture.AuditCentral))
+	assert.Len(t, c.pushed, 1)
+}
+
+func TestRecordBufferedAppendsAndNotifies(t *testing.T) {
+	buf := newFileBuffer(t)
+	nt := &fakeNotifier{}
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, buf, nt)
+	require.NoError(t, d.Record(context.Background(), entry("p"), capture.AuditBuffered))
+
+	pending, err := buf.Pending()
+	require.NoError(t, err)
+	assert.Len(t, pending, 1)
+	assert.NotEmpty(t, nt.msgs, "degraded state alerts via ntfy")
+}
+
+// --- FileBuffer durability + Confirm ---
+
+func TestFileBufferSurvivesRestart(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "buf.jsonl")
+	b1, err := audit.NewFileBuffer(path)
+	require.NoError(t, err)
+	require.NoError(t, b1.Append(entry("p1")))
+	require.NoError(t, b1.Append(entry("p2")))
+
+	// "restart": a fresh FileBuffer over the same file sees the records.
+	b2, err := audit.NewFileBuffer(path)
+	require.NoError(t, err)
+	pending, err := b2.Pending()
+	require.NoError(t, err)
+	assert.Len(t, pending, 2)
+}
+
+func TestFileBufferConfirmRemovesOnlyThatRecord(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("keep")))
+	require.NoError(t, buf.Append(entry("drop")))
+
+	pending, _ := buf.Pending()
+	require.Len(t, pending, 2)
+	var dropID string
+	for _, p := range pending {
+		if p.Entry.Principal == "drop" {
+			dropID = p.ID
+		}
+	}
+	require.NoError(t, buf.Confirm(dropID))
+
+	after, _ := buf.Pending()
+	require.Len(t, after, 1)
+	assert.Equal(t, "keep", after[0].Entry.Principal)
+}
+
+// --- Reconcile ---
+
+func TestReconcileReplaysAndClearsOnlyAfterConfirmedWrite(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("a")))
+	require.NoError(t, buf.Append(entry("b")))
+	c := &fakeCentral{} // up
+	nt := &fakeNotifier{}
+
+	n, err := audit.Reconcile(context.Background(), c, buf, nt)
+	require.NoError(t, err)
+	assert.Equal(t, 2, n)
+	assert.Len(t, c.pushed, 2, "buffered records replayed to central")
+
+	pending, _ := buf.Pending()
+	assert.Empty(t, pending, "buffer cleared after confirmed central writes")
+}
+
+func TestReconcileNoopWhenCentralDown(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("a")))
+	n, err := audit.Reconcile(context.Background(), &fakeCentral{down: true}, buf, &fakeNotifier{})
+	require.NoError(t, err)
+	assert.Equal(t, 0, n)
+	pending, _ := buf.Pending()
+	assert.Len(t, pending, 1, "records stay buffered while central is down")
+}
+
+func TestReconcileKeepsRecordWhenPushFails(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("a")))
+	// Ready ok but Push fails → record must remain buffered (not lost).
+	c := &fakeCentral{pushErr: errors.New("push rejected")}
+	n, err := audit.Reconcile(context.Background(), c, buf, &fakeNotifier{})
+	require.NoError(t, err)
+	assert.Equal(t, 0, n)
+	pending, _ := buf.Pending()
+	assert.Len(t, pending, 1)
+}

ingestion/internal/audit/loki.go

@@ -0,0 +1,99 @@
+package audit
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+)
+
+// LokiCentral pushes capture audit records to a Grafana Loki instance via
+// its push API, and probes readiness via /ready. It is the central audit
+// substrate behind DegradingSink.
+type LokiCentral struct {
+	baseURL string
+	labels  map[string]string
+	http    *http.Client
+}
+
+// NewLokiCentral constructs a LokiCentral for the given base URL (e.g.
+// http://loki:3100). Returns nil when baseURL is empty so callers can
+// treat missing config as "no central sink" with a single nil check.
+func NewLokiCentral(baseURL string) *LokiCentral {
+	if baseURL == "" {
+		return nil
+	}
+	return &LokiCentral{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		labels:  map[string]string{"service": "brain-capture", "kind": "audit"},
+		http:    &http.Client{Timeout: 10 * time.Second},
+	}
+}
+
+// Ready probes Loki's readiness endpoint.
+func (l *LokiCentral) Ready(ctx context.Context) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, l.baseURL+"/ready", nil)
+	if err != nil {
+		return err
+	}
+	resp, err := l.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("loki not ready: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("loki not ready: status %d", resp.StatusCode)
+	}
+	return nil
+}
+
+// pushPayload is the Loki push API body: one stream, one entry whose line
+// is the JSON-encoded audit record.
+type pushPayload struct {
+	Streams []lokiStream `json:"streams"`
+}
+
+type lokiStream struct {
+	Stream map[string]string `json:"stream"`
+	Values [][2]string       `json:"values"`
+}
+
+// Push writes one audit record to Loki as a structured log line.
+func (l *LokiCentral) Push(ctx context.Context, e capture.AuditEntry) error {
+	line, err := json.Marshal(e)
+	if err != nil {
+		return fmt.Errorf("marshal audit entry: %w", err)
+	}
+	ts := e.Timestamp
+	if ts.IsZero() {
+		ts = time.Now()
+	}
+	body, err := json.Marshal(pushPayload{Streams: []lokiStream{{
+		Stream: l.labels,
+		Values: [][2]string{{strconv.FormatInt(ts.UTC().UnixNano(), 10), string(line)}},
+	}}})
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		l.baseURL+"/loki/api/v1/push", bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := l.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("loki push: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("loki push: status %d", resp.StatusCode)
+	}
+	return nil
+}

ingestion/internal/audit/loki_ntfy_test.go

@@ -0,0 +1,86 @@
+package audit_test
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLokiReadyAndPush(t *testing.T) {
+	var pushBody string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/ready":
+			w.WriteHeader(http.StatusOK)
+		case "/loki/api/v1/push":
+			b, _ := io.ReadAll(r.Body)
+			pushBody = string(b)
+			w.WriteHeader(http.StatusNoContent)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	c := audit.NewLokiCentral(srv.URL)
+	require.NotNil(t, c)
+	require.NoError(t, c.Ready(context.Background()))
+
+	err := c.Push(context.Background(), capture.AuditEntry{
+		Principal: "koala-cli", EffectiveClassification: "internal", Items: []string{"insight:x"},
+	})
+	require.NoError(t, err)
+	assert.Contains(t, pushBody, "streams")
+	assert.Contains(t, pushBody, "koala-cli", "audit entry serialised into the loki line")
+}
+
+func TestLokiReadyFailsWhenDown(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}))
+	defer srv.Close()
+	require.Error(t, audit.NewLokiCentral(srv.URL).Ready(context.Background()))
+}
+
+func TestLokiNilWhenUnconfigured(t *testing.T) {
+	assert.Nil(t, audit.NewLokiCentral(""))
+}
+
+func TestNtfyNotify(t *testing.T) {
+	var gotBody, gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		b, _ := io.ReadAll(r.Body)
+		gotBody = string(b)
+		gotAuth = r.Header.Get("Authorization")
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	n := audit.NewNtfyNotifier(srv.URL, "ntfy-token")
+	require.NotNil(t, n)
+	require.NoError(t, n.Notify(context.Background(), "audit buffered locally"))
+	assert.Contains(t, gotBody, "audit buffered locally")
+	assert.Equal(t, "Bearer ntfy-token", gotAuth)
+}
+
+func TestNtfyDoesNotLeakTokenOnError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+	err := audit.NewNtfyNotifier(srv.URL, "secret-token").Notify(context.Background(), "x")
+	require.Error(t, err)
+	assert.False(t, strings.Contains(err.Error(), "secret-token"), "token must not leak into errors")
+}
+
+func TestNtfyNilWhenUnconfigured(t *testing.T) {
+	assert.Nil(t, audit.NewNtfyNotifier("", "tok"))
+}

ingestion/internal/audit/ntfy.go

@@ -0,0 +1,86 @@
+package audit
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// NtfyNotifier posts alerts to an ntfy topic URL. Used to surface a
+// degraded audit state (records buffered locally during a loki outage).
+type NtfyNotifier struct {
+	topicURL string
+	token    string
+	title    string
+	http     *http.Client
+}
+
+// defaultNtfyTitle is the title of a notifier built without WithTitle: the
+// capture audit's degraded-state alert, its first user.
+const defaultNtfyTitle = "brain-capture audit degraded"
+
+// NewNtfyNotifier constructs a notifier for the given ntfy topic URL
+// (e.g. https://ntfy.sh/my-topic). token is an optional bearer for
+// protected ntfy instances; it is held here and only sent in the
+// Authorization header, never logged. Returns nil when topicURL is empty.
+func NewNtfyNotifier(topicURL, token string) *NtfyNotifier {
+	if topicURL == "" {
+		return nil
+	}
+	return &NtfyNotifier{
+		topicURL: strings.TrimRight(topicURL, "/"),
+		token:    token,
+		title:    defaultNtfyTitle,
+		http:     &http.Client{Timeout: 10 * time.Second},
+	}
+}
+
+// WithTitle returns a copy that sends title as the ntfy Title header, so each
+// alert source (the capture audit, the symlink tripwire, governance edits)
+// is recognisable on the phone (hyperguild#163). A nil notifier (ntfy not
+// configured) stays nil.
+func (n *NtfyNotifier) WithTitle(title string) *NtfyNotifier {
+	if n == nil {
+		return nil
+	}
+	c := *n
+	c.title = title
+	return &c
+}
+
+// Notify posts a message to the ntfy topic.
+func (n *NtfyNotifier) Notify(ctx context.Context, msg string) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, n.topicURL, strings.NewReader(msg))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Title", n.title)
+	req.Header.Set("Priority", "high")
+	req.Header.Set("Tags", "warning,brain")
+	if n.token != "" {
+		req.Header.Set("Authorization", "Bearer "+n.token)
+	}
+	resp, err := n.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("ntfy notify: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return &RejectedError{Status: resp.StatusCode}
+	}
+	return nil
+}
+
+// RejectedError is a non-2xx ntfy response.
+type RejectedError struct{ Status int }
+
+func (e *RejectedError) Error() string { return fmt.Sprintf("ntfy notify: status %d", e.Status) }
+
+// Permanent reports whether resending the same message cannot succeed: a 4xx
+// other than 429 (rate limited). Callers may drop such a message; anything
+// else (5xx, 429, transport errors) is an outage and must be retried.
+func (e *RejectedError) Permanent() bool {
+	return e.Status >= 400 && e.Status < 500 && e.Status != http.StatusTooManyRequests
+}

ingestion/internal/audit/ntfy_rejected_test.go

@@ -0,0 +1,27 @@
+package audit
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// A non-2xx ntfy response is a *RejectedError, and only a client-side refusal
+// other than rate limiting is permanent: callers may drop a message on a
+// permanent rejection and must retry the rest (hyperguild#157, PR #160).
+func TestNotifyClassifiesRejectionsAsPermanentOrNot(t *testing.T) {
+	for status, permanent := range map[int]bool{413: true, 400: true, 403: true, 429: false, 500: false, 503: false} {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(status) }))
+		err := NewNtfyNotifier(srv.URL, "").Notify(context.Background(), "m")
+		srv.Close()
+		var rej *RejectedError
+		require.True(t, errors.As(err, &rej), "status %d: %v", status, err)
+		assert.Equal(t, status, rej.Status)
+		assert.Equal(t, permanent, rej.Permanent(), "status %d", status)
+	}
+}

ingestion/internal/audit/ntfy_title_test.go

@@ -0,0 +1,29 @@
+package audit
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#163: every alert went out titled "brain-capture audit
+// degraded", including the symlink tripwire's and governance alerts.
+func TestNtfyNotifierSendsItsOwnTitle(t *testing.T) {
+	var got []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = append(got, r.Header.Get("Title"))
+	}))
+	defer srv.Close()
+	base := NewNtfyNotifier(srv.URL, "")
+	require.NoError(t, base.Notify(context.Background(), "m"))
+	require.NoError(t, base.WithTitle("brain symlink tripwire").Notify(context.Background(), "m"))
+	require.NoError(t, base.Notify(context.Background(), "m"))
+	assert.Equal(t, []string{"brain-capture audit degraded", "brain symlink tripwire", "brain-capture audit degraded"}, got,
+		"WithTitle returns a copy; the base keeps its default title")
+	var nilN *NtfyNotifier
+	assert.Nil(t, nilN.WithTitle("x"), "nil (ntfy not configured) stays nil")
+}

ingestion/internal/audit/reconcile.go

@@ -0,0 +1,65 @@
+package audit
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+)
+
+// Reconcile replays locally-buffered audit records to the central sink
+// when it is reachable again. A record is removed from the buffer ONLY
+// after its central write is confirmed, so a crash mid-reconcile re-plays
+// rather than loses. Returns the number of records reconciled.
+//
+// A no-op (0, nil) when the central sink is still unreachable or the
+// buffer is empty.
+func Reconcile(ctx context.Context, central Central, buffer Buffer, notifier Notifier) (int, error) {
+	if err := central.Ready(ctx); err != nil {
+		return 0, nil // still down; try again next tick
+	}
+	pending, err := buffer.Pending()
+	if err != nil {
+		return 0, fmt.Errorf("read buffer: %w", err)
+	}
+	reconciled := 0
+	for _, rec := range pending {
+		if err := central.Push(ctx, rec.Entry); err != nil {
+			// Central went away mid-drain; stop and keep the rest buffered.
+			break
+		}
+		if err := buffer.Confirm(rec.ID); err != nil {
+			return reconciled, fmt.Errorf("confirm buffered record %s: %w", rec.ID, err)
+		}
+		reconciled++
+	}
+	if reconciled > 0 && notifier != nil {
+		_ = notifier.Notify(ctx, fmt.Sprintf("reconciled %d buffered capture audit record(s) to loki", reconciled))
+	}
+	return reconciled, nil
+}
+
+// StartReconcile runs Reconcile on a ticker until ctx is cancelled. It is
+// the recovery half of the degrade-and-buffer path; pair it with a
+// DegradingSink sharing the same buffer + central.
+func StartReconcile(ctx context.Context, central Central, buffer Buffer, notifier Notifier, interval time.Duration) {
+	if interval <= 0 {
+		interval = time.Minute
+	}
+	go func() {
+		t := time.NewTicker(interval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				if n, err := Reconcile(ctx, central, buffer, notifier); err != nil {
+					slog.Warn("audit reconcile failed", "err", err)
+				} else if n > 0 {
+					slog.Info("audit reconcile", "reconciled", n)
+				}
+			}
+		}
+	}()
+}

ingestion/internal/audit/slog.go

@@ -0,0 +1,56 @@
+// Package audit provides AuditSink implementations for the capture
+// capability (I5). This file ships the minimal slog-backed sink used in
+// #53: it emits the request-level audit record to structured logs, which
+// the alloy/loki substrate already scrapes. The classification-aware
+// degradation/refusal sink (confidential fails closed, internal buffers +
+// reconciles) lands in #54 and replaces this behind the same interface.
+package audit
+
+import (
+	"context"
+	"log/slog"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+)
+
+// SlogSink records audit entries to an slog.Logger. It never fails and is
+// always centrally available, so its Reserve always grants AuditCentral —
+// it does not exercise the I5 degradation/floor. That is DegradingSink's
+// job (loki + durable buffer). SlogSink is the default for deployments
+// without a loki endpoint configured. A nil logger ⇒ slog.Default().
+type SlogSink struct {
+	logger *slog.Logger
+}
+
+// NewSlogSink constructs a SlogSink. nil logger ⇒ slog.Default().
+func NewSlogSink(logger *slog.Logger) *SlogSink {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &SlogSink{logger: logger}
+}
+
+// Reserve always grants central recording — slog is always available.
+func (s *SlogSink) Reserve(_ context.Context, _ classification.Level) (capture.AuditOutcome, error) {
+	return capture.AuditCentral, nil
+}
+
+// Record emits the audit entry at info level. Security events, when
+// present, are logged at warn level so they surface independently of the
+// routine audit stream.
+func (s *SlogSink) Record(_ context.Context, e capture.AuditEntry, _ capture.AuditOutcome) error {
+	s.logger.Info("capture audit",
+		"principal", e.Principal,
+		"actor", e.Actor,
+		"harness", e.Harness,
+		"session_ref", e.SessionRef,
+		"classification", e.EffectiveClassification,
+		"items", e.Items,
+		"ts", e.Timestamp,
+	)
+	for _, ev := range e.SecurityEvents {
+		s.logger.Warn("capture security event", "principal", e.Principal, "event", ev)
+	}
+	return nil
+}

ingestion/internal/audit/slog_test.go

@@ -0,0 +1,41 @@
+package audit_test
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSlogSinkRecordsEntryAndSecurityEvents(t *testing.T) {
+	var buf bytes.Buffer
+	sink := audit.NewSlogSink(slog.New(slog.NewTextHandler(&buf, nil)))
+
+	err := sink.Record(context.Background(), capture.AuditEntry{
+		Principal:               "koala-cli",
+		Harness:                 "claude-code",
+		EffectiveClassification: "confidential",
+		Items:                   []string{"insight:wiki/a/facts/x.md"},
+		SecurityEvents:          []string{"asserted-vs-derived origin mismatch"},
+	}, capture.AuditCentral)
+	require.NoError(t, err)
+
+	out := buf.String()
+	assert.Contains(t, out, "capture audit")
+	assert.Contains(t, out, "koala-cli")
+	assert.Contains(t, out, "confidential")
+	assert.Contains(t, out, "capture security event")
+	assert.Contains(t, out, "asserted-vs-derived origin mismatch")
+}
+
+func TestSlogSinkNilLoggerDefaults(t *testing.T) {
+	// nil logger must not panic.
+	require.NotPanics(t, func() {
+		_ = audit.NewSlogSink(nil).Record(context.Background(), capture.AuditEntry{}, capture.AuditCentral)
+	})
+}

ingestion/internal/auth/jwt.go

@@ -1,84 +0,0 @@
-package auth
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"time"
-
-	"github.com/lestrrat-go/jwx/v2/jwk"
-	"github.com/lestrrat-go/jwx/v2/jwt"
-)
-
-// Validator validates Bearer JWTs issued by a Dex (OIDC) authorization server.
-// Audience is optional; leave empty to skip audience validation.
-type Validator struct {
-	issuer   string
-	audience string
-	jwksURI  string
-	cache    *jwk.Cache
-}
-
-// NewValidator fetches the OIDC discovery document from issuerURL, extracts
-// jwks_uri, seeds the JWKS cache, and returns a ready Validator.
-// If DEX_ISSUER_URL is not set the caller should pass "" and skip construction.
-func NewValidator(issuerURL, audience string) (*Validator, error) {
-	resp, err := http.Get(issuerURL + "/.well-known/openid-configuration") //nolint:noctx
-	if err != nil {
-		return nil, fmt.Errorf("fetch oidc discovery: %w", err)
-	}
-	defer resp.Body.Close() //nolint:errcheck
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("oidc discovery: status %d", resp.StatusCode)
-	}
-
-	var doc struct {
-		JWKSURI string `json:"jwks_uri"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&doc); err != nil {
-		return nil, fmt.Errorf("decode oidc discovery: %w", err)
-	}
-	if doc.JWKSURI == "" {
-		return nil, fmt.Errorf("oidc discovery: empty jwks_uri")
-	}
-
-	ctx := context.Background()
-	cache := jwk.NewCache(ctx)
-	if err := cache.Register(doc.JWKSURI, jwk.WithMinRefreshInterval(time.Hour)); err != nil {
-		return nil, fmt.Errorf("register jwks cache: %w", err)
-	}
-	if _, err := cache.Refresh(ctx, doc.JWKSURI); err != nil {
-		return nil, fmt.Errorf("initial jwks fetch: %w", err)
-	}
-
-	return &Validator{
-		issuer:   issuerURL,
-		audience: audience,
-		jwksURI:  doc.JWKSURI,
-		cache:    cache,
-	}, nil
-}
-
-// Validate parses and validates rawToken. Returns the subject claim on success.
-func (v *Validator) Validate(ctx context.Context, rawToken string) (string, error) {
-	keySet, err := v.cache.Get(ctx, v.jwksURI)
-	if err != nil {
-		return "", fmt.Errorf("get jwks: %w", err)
-	}
-
-	opts := []jwt.ParseOption{
-		jwt.WithKeySet(keySet),
-		jwt.WithValidate(true),
-		jwt.WithIssuer(v.issuer),
-	}
-	if v.audience != "" {
-		opts = append(opts, jwt.WithAudience(v.audience))
-	}
-
-	tok, err := jwt.ParseString(rawToken, opts...)
-	if err != nil {
-		return "", fmt.Errorf("validate jwt: %w", err)
-	}
-	return tok.Subject(), nil
-}

ingestion/internal/auth/jwt_test.go

@@ -1,169 +0,0 @@
-package auth_test
-
-import (
-	"context"
-	"crypto/rand"
-	"crypto/rsa"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-	"time"
-
-	"github.com/lestrrat-go/jwx/v2/jwa"
-	"github.com/lestrrat-go/jwx/v2/jwk"
-	"github.com/lestrrat-go/jwx/v2/jwt"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/auth"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-type testKeys struct {
-	priv jwk.Key
-	pub  jwk.Key
-}
-
-func generateRSAKeys(t *testing.T) testKeys {
-	t.Helper()
-	raw, err := rsa.GenerateKey(rand.Reader, 2048)
-	require.NoError(t, err)
-
-	priv, err := jwk.FromRaw(raw)
-	require.NoError(t, err)
-	require.NoError(t, priv.Set(jwk.KeyIDKey, "test-kid"))
-	require.NoError(t, priv.Set(jwk.AlgorithmKey, jwa.RS256))
-
-	pub, err := jwk.PublicKeyOf(priv)
-	require.NoError(t, err)
-
-	return testKeys{priv: priv, pub: pub}
-}
-
-func mockOIDCServer(t *testing.T, keys testKeys) *httptest.Server {
-	t.Helper()
-	set := jwk.NewSet()
-	require.NoError(t, set.AddKey(keys.pub))
-	jwksBytes, err := json.Marshal(set)
-	require.NoError(t, err)
-
-	mux := http.NewServeMux()
-	var srv *httptest.Server
-	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(map[string]string{
-			"issuer":   srv.URL,
-			"jwks_uri": srv.URL + "/jwks",
-		})
-	})
-	mux.HandleFunc("/jwks", func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write(jwksBytes)
-	})
-	srv = httptest.NewServer(mux)
-	t.Cleanup(srv.Close)
-	return srv
-}
-
-func signToken(t *testing.T, keys testKeys, issuer, audience, subject string, exp time.Time) string {
-	t.Helper()
-	b := jwt.NewBuilder().
-		Issuer(issuer).
-		Subject(subject).
-		Expiration(exp)
-	if audience != "" {
-		b = b.Audience([]string{audience})
-	}
-	tok, err := b.Build()
-	require.NoError(t, err)
-	signed, err := jwt.Sign(tok, jwt.WithKey(jwa.RS256, keys.priv))
-	require.NoError(t, err)
-	return string(signed)
-}
-
-func TestValidator(t *testing.T) {
-	keys := generateRSAKeys(t)
-	srv := mockOIDCServer(t, keys)
-	ctx := context.Background()
-
-	v, err := auth.NewValidator(srv.URL, "brain")
-	require.NoError(t, err)
-
-	tests := []struct {
-		name      string
-		token     string
-		wantSub   string
-		wantErr   bool
-	}{
-		{
-			name:    "valid jwt",
-			token:   signToken(t, keys, srv.URL, "brain", "test-user", time.Now().Add(time.Hour)),
-			wantSub: "test-user",
-		},
-		{
-			name:    "expired jwt",
-			token:   signToken(t, keys, srv.URL, "brain", "test-user", time.Now().Add(-time.Hour)),
-			wantErr: true,
-		},
-		{
-			name:    "wrong issuer",
-			token:   signToken(t, keys, "https://evil.example.com", "brain", "test-user", time.Now().Add(time.Hour)),
-			wantErr: true,
-		},
-		{
-			name:    "wrong audience",
-			token:   signToken(t, keys, srv.URL, "other-service", "test-user", time.Now().Add(time.Hour)),
-			wantErr: true,
-		},
-		{
-			name:    "tampered token",
-			token:   signToken(t, keys, srv.URL, "brain", "test-user", time.Now().Add(time.Hour)) + "tampered",
-			wantErr: true,
-		},
-		{
-			name:    "not a jwt",
-			token:   "not-a-jwt",
-			wantErr: true,
-		},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			sub, err := v.Validate(ctx, tc.token)
-			if tc.wantErr {
-				assert.Error(t, err)
-				assert.Empty(t, sub)
-			} else {
-				require.NoError(t, err)
-				assert.Equal(t, tc.wantSub, sub)
-			}
-		})
-	}
-}
-
-func TestNewValidator_NoAudience(t *testing.T) {
-	keys := generateRSAKeys(t)
-	srv := mockOIDCServer(t, keys)
-	ctx := context.Background()
-
-	v, err := auth.NewValidator(srv.URL, "")
-	require.NoError(t, err)
-
-	// Token without audience passes when audience validation is disabled.
-	tok, err := jwt.NewBuilder().
-		Issuer(srv.URL).
-		Subject("sub").
-		Expiration(time.Now().Add(time.Hour)).
-		Build()
-	require.NoError(t, err)
-	signed, err := jwt.Sign(tok, jwt.WithKey(jwa.RS256, keys.priv))
-	require.NoError(t, err)
-
-	sub, err := v.Validate(ctx, string(signed))
-	require.NoError(t, err)
-	assert.Equal(t, "sub", sub)
-}
-
-func TestNewValidator_BadDiscoveryURL(t *testing.T) {
-	_, err := auth.NewValidator("http://127.0.0.1:1", "brain")
-	assert.Error(t, err)
-}

ingestion/internal/auth/protected_resource.go

@@ -1,23 +0,0 @@
-package auth
-
-import (
-	"encoding/json"
-	"net/http"
-)
-
-// ProtectedResourceHandler returns an RFC 9728 oauth-protected-resource metadata
-// handler. Mount at GET /.well-known/oauth-protected-resource (no auth required).
-func ProtectedResourceHandler(resourceURL, issuerURL string) http.HandlerFunc {
-	type metadata struct {
-		Resource             string   `json:"resource"`
-		AuthorizationServers []string `json:"authorization_servers"`
-	}
-	body, _ := json.Marshal(metadata{
-		Resource:             resourceURL,
-		AuthorizationServers: []string{issuerURL},
-	})
-	return func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write(body)
-	}
-}

ingestion/internal/auth/protected_resource_test.go

@@ -1,28 +0,0 @@
-package auth_test
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/mathiasbq/hyperguild/ingestion/internal/auth"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestProtectedResourceHandler(t *testing.T) {
-	h := auth.ProtectedResourceHandler("https://brain-mcp.d-ma.be", "https://auth.d-ma.be")
-	req := httptest.NewRequest(http.MethodGet, "/.well-known/oauth-protected-resource", nil)
-	rr := httptest.NewRecorder()
-	h(rr, req)
-
-	assert.Equal(t, http.StatusOK, rr.Code)
-	assert.Equal(t, "application/json", rr.Header().Get("Content-Type"))
-
-	var body map[string]any
-	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &body))
-	assert.Equal(t, "https://brain-mcp.d-ma.be", body["resource"])
-	servers := body["authorization_servers"].([]any)
-	assert.Equal(t, "https://auth.d-ma.be", servers[0])
-}

ingestion/internal/brain/detect_root_test.go

@@ -0,0 +1,125 @@
+package brain_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+// hyperguild#174 / #157 slice 5b: DetectTunnels walked wiki/ and opened
+// every note with a blocking os.Open, so a FIFO named *.md anywhere under
+// wiki/ hung every brain_write and brain_update (wikiUpkeep -> AutoTunnel),
+// and a symlinked note's title became a tunnel candidate.
+func TestDetectTunnelsReturnsPromptlyWithAFIFOUnderWikiWithAndWithoutAWriter(t *testing.T) {
+	for _, withWriter := range []bool{false, true} {
+		t.Run(fmt.Sprintf("writer=%v", withWriter), func(t *testing.T) {
+			b := t.TempDir()
+			facts := filepath.Join(b, "wiki", "w", "facts")
+			require.NoError(t, os.MkdirAll(facts, 0o755))
+			require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: Zqinside Phrase\n---\n"), 0o644))
+			fifo := filepath.Join(facts, "f.md")
+			require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+			if withWriter {
+				// A writer held open: a reader that opens the FIFO gets no
+				// EOF and parks, unless the FIFO is never opened.
+				w, err := os.OpenFile(fifo, os.O_RDWR, 0)
+				require.NoError(t, err)
+				t.Cleanup(func() { _ = w.Close() })
+			}
+			done := make(chan []brain.TunnelCandidate, 1)
+			go func() {
+				cs, _ := brain.DetectTunnels(b, "text mentioning zqinside phrase here")
+				done <- cs
+			}()
+			select {
+			case cs := <-done:
+				assert.Contains(t, fmt.Sprintf("%+v", cs), "Zqinside Phrase", "positive control")
+			case <-time.After(3 * time.Second):
+				if r, err := os.OpenFile(fifo, os.O_WRONLY|syscall.O_NONBLOCK, 0); err == nil {
+					_ = r.Close()
+				}
+				t.Fatal("DetectTunnels blocked on a FIFO")
+			}
+		})
+	}
+}
+
+func TestDetectTunnelsRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
+	b := t.TempDir()
+	facts := filepath.Join(b, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	// The static note's title differs from the raced note's, so the
+	// harness's "inside was read" floor can only be met by reading r.md.
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: Zqstatic Words\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "out.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "in.md")))
+	content := "zqstatic words, zqinside phrase and " + brainfstest.Sentinel
+
+	cs, err := brain.DetectTunnels(b, content)
+	require.NoError(t, err)
+	got := fmt.Sprintf("%+v", cs)
+	assert.Contains(t, got, "Zqstatic Words", "positive control")
+	assert.NotContains(t, got, brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		cs, _ := brain.DetectTunnels(b, content)
+		return fmt.Sprintf("%+v", cs)
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: Zqinside Phrase\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: Zqinside Phrase\n---\n", inBrain, 1500*time.Millisecond, read)
+}
+
+// A wiki/ that is not a real directory yields no candidates and no error:
+// AutoTunnel runs inside brain_write.
+func TestDetectTunnelsSkipsAWikiThatIsNotARealDirectory(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "raw", "w", "facts", "r.md"), []byte("---\ntitle: Zqrawonly Phrase\n---\n"), 0o644))
+	require.NoError(t, os.Symlink("raw", filepath.Join(b, "wiki")))
+	cs, err := brain.DetectTunnels(b, "zqrawonly phrase")
+	require.NoError(t, err)
+	assert.Empty(t, cs)
+}
+
+// An unreadable directory under wiki/ is a walk error and DetectTunnels
+// reports it, as filepath.WalkDir did; it is not silently dropped.
+func TestDetectTunnelsReportsAnUnreadableDirectoryUnderWiki(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "ok.md"), []byte("---\ntitle: Zqinside Phrase\n---\n"), 0o644))
+	locked := filepath.Join(b, "wiki", "other", "locked")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+	_, err := brain.DetectTunnels(b, "zqinside phrase")
+	assert.ErrorIs(t, err, os.ErrPermission)
+}
+
+// _index.md files are generated, not notes: their title never becomes a
+// candidate.
+func TestDetectTunnelsSkipsIndexFiles(t *testing.T) {
+	b := t.TempDir()
+	w := filepath.Join(b, "wiki", "w")
+	require.NoError(t, os.MkdirAll(filepath.Join(w, "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(w, "_index.md"), []byte("---\ntitle: Zqindex Words\n---\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(w, "facts", "ok.md"), []byte("---\ntitle: Zqinside Phrase\n---\n"), 0o644))
+	cs, err := brain.DetectTunnels(b, "zqindex words and zqinside phrase")
+	require.NoError(t, err)
+	got := fmt.Sprintf("%+v", cs)
+	assert.Contains(t, got, "Zqinside Phrase", "positive control")
+	assert.NotContains(t, got, "Zqindex")
+}

ingestion/internal/brain/index.go

@@ -2,12 +2,16 @@ package brain
 
 import (
 	"bufio"
+	"bytes"
+	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"io"
+	"io/fs"
 	"sort"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // noteEntry is one row in a Wing _index.md.
@@ -26,14 +30,18 @@ func BuildWingIndex(brainDir, wing string) error {
 	if w == "" {
 		return fmt.Errorf("invalid wing %q", wing)
 	}
-	wingDir := filepath.Join(brainDir, "wiki", w)
-	if _, err := os.Stat(wingDir); os.IsNotExist(err) {
+	// Listed and read through the brain root (hyperguild#157): a wing or
+	// hall that is a symlink is not followed, and notes are regular files.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if _, err := bfs.Lstat("wiki/" + w); errors.Is(err, fs.ErrNotExist) {
 		return nil
-	} else if err != nil {
-		return fmt.Errorf("stat wing: %w", err)
 	}
 
-	entries, err := collectWingEntries(wingDir)
+	entries, err := collectWingEntries(bfs, "wiki/"+w)
 	if err != nil {
 		return err
 	}
@@ -52,74 +60,85 @@ func BuildWingIndex(brainDir, wing string) error {
 		fmt.Fprintf(&b, "| %s | [%s](%s/%s.md) | %s |\n", e.Hall, e.Title, e.Hall, e.Slug, e.Created)
 	}
 
-	dest := filepath.Join(wingDir, "_index.md")
-	return os.WriteFile(dest, []byte(b.String()), 0o644)
+	// Written through the brain root, never through a symlinked _index.md
+	// (hyperguild#158).
+	return bfs.PutRegular("wiki/"+w+"/_index.md", []byte(b.String()))
 }
 
 // BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.
 func BuildAllWingIndexes(brainDir string) error {
-	wikiDir := filepath.Join(brainDir, "wiki")
-	ents, err := os.ReadDir(wikiDir)
-	if os.IsNotExist(err) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	wings, err := bfs.ReadDirDirs("wiki")
+	_ = bfs.Close()
+	if errors.Is(err, fs.ErrNotExist) {
 		return nil
 	}
 	if err != nil {
 		return fmt.Errorf("read wiki: %w", err)
 	}
-	for _, e := range ents {
-		if !e.IsDir() {
-			continue
-		}
-		if err := BuildWingIndex(brainDir, e.Name()); err != nil {
-			return fmt.Errorf("index %s: %w", e.Name(), err)
+	for _, w := range wings {
+		if err := BuildWingIndex(brainDir, w); err != nil {
+			return fmt.Errorf("index %s: %w", w, err)
 		}
 	}
 	return nil
 }
 
-func collectWingEntries(wingDir string) ([]noteEntry, error) {
+func collectWingEntries(bfs *brainfs.Brain, wingRel string) ([]noteEntry, error) {
 	var out []noteEntry
-	ents, err := os.ReadDir(wingDir)
+	halls, err := bfs.ReadDirDirs(wingRel)
 	if err != nil {
 		return nil, fmt.Errorf("read wing: %w", err)
 	}
-	for _, hallEnt := range ents {
-		if !hallEnt.IsDir() {
-			continue
-		}
-		hall := hallEnt.Name()
+	for _, hall := range halls {
 		if !IsValidHall(hall) {
 			continue
 		}
-		hallDir := filepath.Join(wingDir, hall)
-		notes, err := os.ReadDir(hallDir)
+		hallRel := wingRel + "/" + hall
+		names, err := bfs.ReadDirRegular(hallRel)
 		if err != nil {
 			return nil, fmt.Errorf("read hall %s: %w", hall, err)
 		}
-		for _, n := range notes {
-			if n.IsDir() || !strings.HasSuffix(n.Name(), ".md") || n.Name() == "_index.md" {
+		for _, name := range names {
+			if !strings.HasSuffix(name, ".md") || name == "_index.md" {
 				continue
 			}
-			slug := strings.TrimSuffix(n.Name(), ".md")
-			full := filepath.Join(hallDir, n.Name())
-			title, created := readTitleAndCreated(full, slug)
+			slug := strings.TrimSuffix(name, ".md")
+			title, created := readTitleAndCreatedIn(bfs, hallRel+"/"+name, slug)
 			out = append(out, noteEntry{Hall: hall, Slug: slug, Title: title, Created: created})
 		}
 	}
 	return out, nil
 }
 
-// readTitleAndCreated reads YAML frontmatter for title + created_at; falls
-// back to slug and file mtime when absent.
-func readTitleAndCreated(path, slug string) (string, string) {
-	f, err := os.Open(path)
+// readTitleAndCreatedIn is readTitleAndCreated through the brain root,
+// regular files only (hyperguild#157).
+func readTitleAndCreatedIn(bfs *brainfs.Brain, rel, slug string) (string, string) {
+	content, err := bfs.ReadRegular(rel)
 	if err != nil {
 		return slug, ""
 	}
-	defer func() { _ = f.Close() }()
+	title, created := parseTitleAndCreated(bytes.NewReader(content))
+	if created == "" {
+		if info, err := bfs.Lstat(rel); err == nil {
+			created = info.ModTime().UTC().Format("2006-01-02")
+		}
+	}
+	return titleOrSlug(title, slug), created
+}
 
-	title, created := "", ""
-	scanner := bufio.NewScanner(f)
+func titleOrSlug(title, slug string) string {
+	if title == "" {
+		return strings.ReplaceAll(slug, "-", " ")
+	}
+	return title
+}
+
+func parseTitleAndCreated(r io.Reader) (title, created string) {
+	scanner := bufio.NewScanner(r)
 	inFrontmatter := false
 	for scanner.Scan() {
 		line := scanner.Text()
@@ -149,13 +168,5 @@ func readTitleAndCreated(path, slug string) (string, string) {
 			}
 		}
 	}
-	if title == "" {
-		title = strings.ReplaceAll(slug, "-", " ")
-	}
-	if created == "" {
-		if info, err := os.Stat(path); err == nil {
-			created = info.ModTime().UTC().Format("2006-01-02")
-		}
-	}
 	return title, created
 }

ingestion/internal/brain/index_root_test.go

@@ -0,0 +1,132 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+func readIndex(t *testing.T, brainDir, wing string) string {
+	t.Helper()
+	b, _ := os.ReadFile(filepath.Join(brainDir, "wiki", wing, "_index.md"))
+	return string(b)
+}
+
+// hyperguild#157 slice 5: BuildWingIndex listed wiki/<wing>/<hall>/ with
+// os.ReadDir and opened each note by path, so a symlinked note put the
+// target's title into _index.md, and a FIFO hung the index build.
+func TestBuildWingIndexRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
+	b := t.TempDir()
+	facts := filepath.Join(b, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: zqinside\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+
+	require.NoError(t, brain.BuildWingIndex(b, "w"))
+	idx := readIndex(t, b, "w")
+	assert.Contains(t, idx, "zqinside", "positive control")
+	assert.NotContains(t, idx, brainfstest.Sentinel)
+	assert.NotContains(t, idx, "leak")
+	assert.NotContains(t, idx, "inlink")
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		_ = brain.BuildWingIndex(b, "w")
+		return readIndex(t, b, "w")
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+// A symlinked hall is skipped while a real hall next to it is indexed; a
+// symlinked wing is refused and nothing is written into its target.
+func TestBuildWingIndexSkipsASymlinkedHallAndRefusesASymlinkedWing(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "raw", "facts", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "decisions"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "decisions", "d.md"), []byte("---\ntitle: zqrealhall\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "w", "facts")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(b, "wiki", "alias")))
+
+	require.NoError(t, brain.BuildWingIndex(b, "w"))
+	idx, err := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	require.NoError(t, err, "the wing index is written")
+	assert.Contains(t, string(idx), "zqrealhall", "the real hall is indexed")
+	assert.NotContains(t, string(idx), "zqrawonly", "the symlinked hall is not")
+
+	assert.Error(t, brain.BuildWingIndex(b, "alias"))
+	_, err = os.Stat(filepath.Join(b, "raw", "_index.md"))
+	assert.True(t, os.IsNotExist(err), "an index was written into the symlinked wing's target")
+}
+
+// BuildAllWingIndexes indexes the real wings and skips a symlinked one.
+func TestBuildAllWingIndexesSkipsASymlinkedWing(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "n.md"), []byte("---\ntitle: zqrealwing\n---\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "facts"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(b, "wiki", "alias")))
+
+	require.NoError(t, brain.BuildAllWingIndexes(b))
+	idx, err := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(idx), "zqrealwing")
+	_, err = os.Stat(filepath.Join(b, "raw", "_index.md"))
+	assert.True(t, os.IsNotExist(err))
+}
+
+// A link to a symlinked note does not resolve: only regular files count as
+// entries, so StripUnresolvedLinks unwraps it.
+func TestStripUnresolvedLinksDoesNotCountASymlinkedNoteAsAnEntry(t *testing.T) {
+	b := t.TempDir()
+	facts := filepath.Join(b, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "real.md"), []byte("x"), 0o644))
+	brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "ghost.md")))
+	out, unlinked, err := brain.StripUnresolvedLinks(b, "see [[real]] and [[ghost]]")
+	require.NoError(t, err)
+	assert.Contains(t, out, "[[real]]", "positive control")
+	assert.NotContains(t, out, "[[ghost]]")
+	assert.Contains(t, unlinked, "ghost")
+}
+
+// A linked tree (knowledge/ or wiki/) that is not a real directory is
+// skipped, not an error: StripUnresolvedLinks runs before every brain_write,
+// and an error there loses the learning.
+func TestStripUnresolvedLinksSkipsALinkedTreeThatIsNotARealDirectory(t *testing.T) {
+	for name, mk := range map[string]func(t *testing.T, b string){
+		"symlink to an in-brain dir": func(t *testing.T, b string) {
+			require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "k"), 0o755))
+			require.NoError(t, os.Symlink(filepath.Join("raw", "k"), filepath.Join(b, "knowledge")))
+		},
+		"dangling symlink": func(t *testing.T, b string) {
+			require.NoError(t, os.Symlink("nowhere", filepath.Join(b, "knowledge")))
+		},
+		"regular file": func(t *testing.T, b string) {
+			require.NoError(t, os.WriteFile(filepath.Join(b, "knowledge"), []byte("x"), 0o644))
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			b := t.TempDir()
+			require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+			require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "real.md"), []byte("x"), 0o644))
+			mk(t, b)
+			out, _, err := brain.StripUnresolvedLinks(b, "learning [[real]] and [[gone]]")
+			require.NoError(t, err)
+			assert.Contains(t, out, "[[real]]", "links into wiki/ still resolve")
+			assert.NotContains(t, out, "[[gone]]")
+		})
+	}
+}

ingestion/internal/brain/linkcheck.go

@@ -0,0 +1,177 @@
+package brain
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"path"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// wikilinkRE matches [[target]] and [[target|Display Text]].
+var wikilinkRE = regexp.MustCompile(`\[\[([^\]|]+)(?:\|([^\]]*))?\]\]`)
+
+// fencedCodeRE and inlineCodeRE mark the regions where a [[...]] is a
+// syntax example rather than a link. Same exclusion brain-gardener's audit
+// applies on the read side, so the write gate and the audit agree on what
+// counts as a link at all.
+var (
+	fencedCodeRE = regexp.MustCompile("(?s)```.*?```")
+	inlineCodeRE = regexp.MustCompile("`[^`\n]*`")
+)
+
+// StripUnresolvedLinks unwraps every [[wikilink]] in content whose target
+// resolves to no entry under knowledge/ or wiki/, leaving the link's display
+// text (or its target) as plain prose. It returns the rewritten content and
+// the sorted, de-duplicated targets it unwrapped.
+//
+// WHY UNWRAP RATHER THAN REJECT THE WRITE
+// Agents write [[...]] around anything that feels related — a skill name, a
+// repo, an agent-local memory file — and none of those are brain entries.
+// Every one of those becomes a permanent [high] broken-link finding that no
+// deterministic Fixer can repair, because there is no target to repoint to:
+// the brain-audit digest grew from 19 to 63 high findings between 2026-08-26
+// and 2026-09-16, and 53 of the 63 were exactly this. Rejecting the write
+// instead would push the failure onto claudewatcher's unattended ingest path,
+// where a refused write is a lost learning. Unwrapping keeps the author's
+// words, keeps the write, and keeps the graph honest.
+//
+// An empty corpus (no knowledge/ or wiki/ yet, or a misconfigured brainDir)
+// returns content unchanged: nothing resolving is a bootstrap state, not
+// evidence that every target was invented.
+func StripUnresolvedLinks(brainDir, content string) (string, []string, error) {
+	index, err := entryIndex(brainDir)
+	if err != nil {
+		// A partial index cannot tell an invented link from one into the
+		// part it could not read, so unwrap nothing, and do not refuse the
+		// write either: this runs before every brain_write, and a refused
+		// write is a lost learning (hyperguild#178).
+		slog.Warn("link check skipped: cannot index the brain", "err", err)
+		return content, nil, nil
+	}
+	if len(index) == 0 {
+		return content, nil, nil
+	}
+
+	code := codeSpans(content)
+	stripped := map[string]struct{}{}
+
+	var b strings.Builder
+	last := 0
+	for _, m := range wikilinkRE.FindAllStringSubmatchIndex(content, -1) {
+		start, end := m[0], m[1]
+		if overlaps(start, end, code) {
+			continue
+		}
+		target := strings.TrimSpace(content[m[2]:m[3]])
+		if _, ok := index[linkKey(target)]; ok {
+			continue
+		}
+		display := target
+		if m[4] >= 0 {
+			if d := strings.TrimSpace(content[m[4]:m[5]]); d != "" {
+				display = d
+			}
+		}
+		b.WriteString(content[last:start])
+		b.WriteString(display)
+		last = end
+		stripped[target] = struct{}{}
+	}
+	if last == 0 {
+		return content, nil, nil
+	}
+	b.WriteString(content[last:])
+
+	targets := make([]string, 0, len(stripped))
+	for t := range stripped {
+		targets = append(targets, t)
+	}
+	sort.Strings(targets)
+	return b.String(), targets, nil
+}
+
+// linkedTrees are the two trees that hold linkable entries — the same pair
+// package notes admits under ScopeNotes. Duplicated rather than imported
+// because that list is unexported there and this is a read-only mirror.
+var linkedTrees = []string{"knowledge", "wiki"}
+
+// entryIndex maps every form a wikilink may name an entry by — its bare slug
+// and its path form (wiki/<wing>/<hall>/<slug>.md -> wing/hall/slug) — to a
+// present marker. Mirrors brain-gardener's resolver so an accepted link is
+// one the audit will also resolve.
+func entryIndex(brainDir string) (map[string]struct{}, error) {
+	index := map[string]struct{}{}
+	// Walked through the brain root (hyperguild#157): only regular files
+	// count as entries, so a symlinked .md name cannot make a link resolve.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	for _, dir := range linkedTrees {
+		if _, err := bfs.Lstat(dir); errors.Is(err, fs.ErrNotExist) {
+			continue
+		}
+		var walkErr error
+		err := bfs.WalkRegular(dir, func(rel string) error {
+			if !strings.HasSuffix(rel, ".md") {
+				return nil
+			}
+			index[strings.TrimSuffix(path.Base(rel), ".md")] = struct{}{}
+			index[strings.TrimPrefix(strings.TrimSuffix(rel, ".md"), "wiki/")] = struct{}{}
+			return nil
+		}, func(rel string, err error) {
+			// A linked tree that is not a real directory (a symlink, a
+			// file) is skipped, as filepath.WalkDir did: this runs before
+			// every brain_write, and an error here loses the learning.
+			if rel == dir && errors.Is(err, brainfs.ErrNotRegular) {
+				slog.Warn("link check: skipping a linked tree that is not a real directory", "dir", dir)
+				return
+			}
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
+			}
+		})
+		if err == nil {
+			err = walkErr
+		}
+		if err != nil {
+			return nil, fmt.Errorf("walk %s: %w", dir, err)
+		}
+	}
+	return index, nil
+}
+
+// linkKey normalises a link target for index lookup: an exact path form is
+// tried as written, and anything else falls back to its final segment.
+func linkKey(target string) string {
+	return strings.TrimSuffix(target, ".md")
+}
+
+// codeSpans returns the byte ranges of fenced blocks and inline code spans.
+func codeSpans(content string) [][2]int {
+	var spans [][2]int
+	for _, m := range fencedCodeRE.FindAllStringIndex(content, -1) {
+		spans = append(spans, [2]int{m[0], m[1]})
+	}
+	for _, m := range inlineCodeRE.FindAllStringIndex(content, -1) {
+		spans = append(spans, [2]int{m[0], m[1]})
+	}
+	return spans
+}
+
+// overlaps reports whether [start,end) intersects any span.
+func overlaps(start, end int, spans [][2]int) bool {
+	for _, s := range spans {
+		if start < s[1] && end > s[0] {
+			return true
+		}
+	}
+	return false
+}