Merge remote-tracking branch 'origin/master' into fix/adaptive-embed-batch-sizing

# Conflicts:
#	CHANGELOG.md
#	VERSION
#	package.json

.github/PULL_REQUEST_TEMPLATE/tier5-queries.md

@@ -0,0 +1,39 @@
+<!--
+Tier 5.5 Externally-Authored Query Submission template
+See eval/CONTRIBUTING.md for the full workflow.
+-->
+
+## Summary
+
+Submitting **N** Tier 5.5 queries for BrainBench.
+
+- Author handle: `@your-handle`
+- File location: `eval/external-authors/your-handle/queries.json`
+- Queries authored fresh (not copy-pasted from a model output)
+- Slugs verified against `eval/data/world-v1/` (via `bun run eval:world:view`)
+
+## Checklist
+
+- [ ] `bun run eval:query:validate eval/external-authors/your-handle/queries.json` passes
+- [ ] At least 20 queries
+- [ ] Each query has either `gold.relevant` (with real slugs) or `gold.expected_abstention: true`
+- [ ] Temporal queries have `as_of_date` set (`corpus-end` | `per-source` | ISO-8601)
+- [ ] Phrasing is varied (not all the same template)
+- [ ] `author` field matches my handle
+
+## Phrasing variety (optional self-audit)
+
+Tick the styles represented in your batch:
+
+- [ ] Full sentence questions
+- [ ] Fragment-style ("crypto founder Goldman Sachs background")
+- [ ] Comparison ("X vs Y")
+- [ ] Follow-up ("And who else...")
+- [ ] Imperative ("Pull up Alice Davis")
+- [ ] Trait-based ("the demanding engineering leader")
+- [ ] Abstention bait (answer is "not in corpus")
+
+## Notes to reviewer
+
+Anything worth flagging — ambiguous cases, corpus gaps you found, specific
+phrasings you were uncertain about.

.github/workflows/e2e.yml

@@ -44,7 +44,10 @@ jobs:
   tier2:
     name: Tier 2 (LLM Skills)
     runs-on: ubuntu-latest
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    # Runs on every push/PR now (promoted from schedule-only in v0.19.0).
+    # Tier 1 must pass first; Tier 2 uses OPENAI_API_KEY + ANTHROPIC_API_KEY
+    # from repo/org secrets. Nightly + manual triggers still supported via
+    # the workflow-level `on:` list.
     needs: tier1
     services:
       postgres:

.github/workflows/test.yml

@@ -21,11 +21,22 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   test:
+    # ubuntu-latest is free 2-core/7GB. Larger runners (16-cores, etc.) require
+    # a provisioned runner pool in repo settings. Falling back to default keeps
+    # the matrix shard speedup (~5-6x via parallelism) at zero cost.
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6  # v2
         with:
           bun-version: latest
       - run: bun install
-      - run: bun test
+      - name: Pre-test gates (shard 1 only — they're not test files)
+        if: matrix.shard == 1
+        run: bun run verify
+      - name: Run test shard ${{ matrix.shard }}/4
+        run: scripts/test-shard.sh ${{ matrix.shard }} 4

.gitignore

@@ -5,9 +5,36 @@ bin/
 .env
 .env.*
 !.env.*.example
-.18a49dfd730ff378-00000000.bun-build
-.18a49f9dfb996f70-00000000.bun-build
+# Bun --compile temp artifacts. Each build emits a new hash-named .bun-build
+# file in cwd; glob catches all of them.
+*.bun-build
 .gstack/
 supabase/.temp/
 .claude/skills/
+# admin/dist/ is the React SPA bundle. CLAUDE.md says it's committed for
+# self-contained binaries (the bun --compile path embeds it via
+# `import path from 'admin/dist/index.html' with { type: 'file' }`).
+# Build via: cd admin && bun install && bun run build.
+admin/node_modules/
 .idea
+eval/reports/
+eval/data/world-v1/world.html
+
+# BrainBench amara-life-v1 Opus cache (regenerate via eval:generate-amara-life)
+eval/data/amara-life-v1/_cache/
+
+# claw-test E2E build cache (shim + scratch outputs)
+test/.cache/
+
+.claude/
+export/
+
+# Conductor workspace-local agent artifacts: plans, todos, run-unit-parallel
+# failure logs and per-shard test output. v0.26.4 (run-unit-parallel.sh)
+# writes .context/test-failures.log + .context/test-summary.txt +
+# .context/test-shards/. Workspace-local by design — never committed.
+.context/
+
+# Tier 3 PGLite snapshot fixture (built on demand by build:pglite-snapshot)
+test/fixtures/pglite-snapshot.tar
+test/fixtures/pglite-snapshot.version

AGENTS.md

@@ -0,0 +1,77 @@
+# Agents working on GBrain
+
+This is your install + operating protocol. Claude Code reads `./CLAUDE.md` automatically.
+Everyone else (Codex, Cursor, OpenClaw, Aider, Continue, or an LLM fetching via URL):
+start here.
+
+## Install (5 min)
+
+1. Clone: `git clone https://github.com/garrytan/gbrain ~/gbrain && cd ~/gbrain`
+2. Install: `bun install`
+3. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or
+   multi-machine sync, init suggests Postgres + pgvector via Supabase.
+4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full 9-step flow
+   (API keys, identity, cron, verification).
+
+## Read this order
+
+1. `./AGENTS.md` (this file) — install + operating protocol.
+2. [`./CLAUDE.md`](./CLAUDE.md) — architecture reference, key files, trust boundaries,
+   test layout.
+3. [`./docs/architecture/brains-and-sources.md`](./docs/architecture/brains-and-sources.md)
+   — the two-axis mental model (brain = which DB, source = which repo in the DB). Every
+   query routes on both axes. Read before writing anything that touches brain ops.
+4. [`./skills/conventions/brain-routing.md`](./skills/conventions/brain-routing.md) —
+   agent-facing decision table: when to switch brain, when to switch source, how
+   cross-brain federation works (latent-space only; the agent decides).
+5. [`./skills/RESOLVER.md`](./skills/RESOLVER.md) — skill dispatcher. Read before any task.
+
+## Trust boundary (critical)
+
+GBrain distinguishes **trusted local CLI callers** (`OperationContext.remote = false`,
+set by `src/cli.ts`) from **untrusted agent-facing callers** (`remote = true`, set by
+`src/mcp/server.ts`). Security-sensitive operations like `file_upload` tighten filesystem
+confinement when `remote = true` and default to strict behavior when unset. If you are
+writing or reviewing an operation, consult `src/core/operations.ts` for the contract.
+
+## Common tasks
+
+- **Configure:** [`docs/ENGINES.md`](./docs/ENGINES.md),
+  [`docs/guides/live-sync.md`](./docs/guides/live-sync.md),
+  [`docs/mcp/DEPLOY.md`](./docs/mcp/DEPLOY.md).
+- **Debug:** [`docs/GBRAIN_VERIFY.md`](./docs/GBRAIN_VERIFY.md),
+  [`docs/guides/minions-fix.md`](./docs/guides/minions-fix.md), `gbrain doctor --fix`.
+- **Migrate:** [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md),
+  [`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations`.
+- **Eval retrieval changes:** capture is off by default. To benchmark a
+  retrieval change against real captured queries, set
+  `GBRAIN_CONTRIBUTOR_MODE=1`, then `gbrain eval export --since 7d > base.ndjson`
+  and `gbrain eval replay --against base.ndjson`. Full guide:
+  [`docs/eval-bench.md`](./docs/eval-bench.md).
+- **Everything else:** [`./llms.txt`](./llms.txt) is the full documentation map.
+  [`./llms-full.txt`](./llms-full.txt) is the same map with core docs inlined for
+  single-fetch ingestion.
+
+## Before shipping
+
+Easiest path: `bun run ci:local` runs the full CI gate inside Docker (gitleaks,
+unit tests with `DATABASE_URL` unset, then all 29 E2E files sequentially against a
+fresh pgvector container) and tears down. Use `bun run ci:local:diff` for the
+diff-aware subset during fast iteration on a focused branch. Requires Docker
+(Docker Desktop / OrbStack / Colima) and `gitleaks` (`brew install gitleaks`).
+
+Manual path: `bun test` plus the E2E lifecycle described in `./CLAUDE.md` (spin
+up the test Postgres container, run `bun run test:e2e`, tear it down).
+
+Ship via the `/ship` skill, not by hand.
+
+## Privacy
+
+Never commit real names of people, companies, or funds into public artifacts. See the
+Privacy rule in `./CLAUDE.md`. GBrain pages reference real contacts; public docs must
+use generic placeholders (`alice-example`, `acme-example`, `fund-a`).
+
+## Forks
+
+If you are a fork, regenerate `llms.txt` + `llms-full.txt` with your own URL base before
+publishing: `LLMS_REPO_BASE=https://raw.githubusercontent.com/your-org/your-fork/main bun run build:llms`.

CONTRIBUTING.md

@@ -52,10 +52,22 @@ docs/                     Architecture docs
 ## Running tests
 
 ```bash
-bun test                          # all tests (unit + E2E skipped without DB)
+# Inner edit loop (~85s on a Mac dev box, 3700+ unit tests)
+bun run test                      # parallel 8-shard fan-out + serial post-pass
 bun test test/markdown.test.ts    # specific unit test
 
-# E2E tests (requires Postgres with pgvector)
+# Pre-push gate (matches what CI runs on shard 1 + typecheck)
+bun run verify                    # privacy + jsonb + progress + test-isolation + wasm + admin-build + typecheck
+
+# Pre-merge sanity (everything CI runs)
+bun run test:full                 # verify + parallel unit + slow + smart e2e
+
+# Slow / serial / e2e in isolation
+bun run test:slow                 # *.slow.test.ts only (cold-path correctness)
+bun run test:serial               # *.serial.test.ts only (--max-concurrency=1)
+bun run test:e2e                  # real-Postgres E2E (requires DATABASE_URL)
+
+# E2E setup (Postgres with pgvector)
 docker compose -f docker-compose.test.yml up -d
 DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test bun run test:e2e
 
@@ -63,6 +75,91 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test bun run t
 DATABASE_URL=postgresql://... bun run test:e2e
 ```
 
+Use `bun run verify` before pushing. The guard chain catches: banned fork-name
+leaks (`scripts/check-privacy.sh`), `JSON.stringify(x)::jsonb` interpolation
+patterns (`scripts/check-jsonb-pattern.sh`), `\r` progress bleed to stdout
+(`scripts/check-progress-to-stdout.sh`), test-isolation rule violations
+(`scripts/check-test-isolation.sh` — see "Writing tests that survive the parallel
+loop" below), silent fallback to recursive chunking in the compiled binary
+(`scripts/check-wasm-embedded.sh`), and stale admin-dashboard build artifacts
+(`scripts/check-admin-build.sh`). `bun run check:all` runs the full historical
+sweep including the trailing-newline and exports-count checks.
+
+### Writing tests that survive the parallel loop
+
+`bun run test` shards 92+ unit-test files across 8 worker processes. Files in the
+same shard share a process, so process-global state leaks between them. Four
+lint rules (`scripts/check-test-isolation.sh`, R1-R4) enforce isolation:
+
+| Rule | What it bans | Fix |
+|---|---|---|
+| **R1** | Direct `process.env.X = ...` mutation | Use `withEnv()` from `test/helpers/with-env.ts`, or rename to `*.serial.test.ts` |
+| **R2** | `mock.module(...)` anywhere in the file | Rename to `*.serial.test.ts` |
+| **R3** | `new PGLiteEngine(` outside ~50 lines after `beforeAll(` | Use the canonical PGLite block (see below) |
+| **R4** | `new PGLiteEngine(` without paired `afterAll(disconnect)` | Add the `afterAll(() => engine.disconnect())` |
+
+Canonical PGLite block (R3 + R4 compliant — paste this verbatim):
+
+```ts
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+
+let engine: PGLiteEngine;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+});
+afterAll(async () => { await engine.disconnect(); });
+beforeEach(async () => { await resetPgliteState(engine); });
+```
+
+Env-touching tests:
+
+```ts
+import { withEnv } from './helpers/with-env.ts';
+
+test('reads OPENAI_API_KEY', async () => {
+  await withEnv({ OPENAI_API_KEY: 'sk-test' }, async () => {
+    expect(loadConfig().openai_key).toBe('sk-test');
+  });
+});
+```
+
+`withEnv` saves and restores keys via try/finally including when the callback
+throws. Cross-test safe; **NOT** intra-file concurrent-safe (`process.env` is
+process-global). Files using `withEnv` stay outside the future
+`test.concurrent()` codemod's eligibility filter.
+
+When to quarantine instead of fix: rename to `*.serial.test.ts` if the file
+uses `mock.module(...)`, is genuinely env-coupled (module-load env readers +
+ESM caching defeat dynamic-import-after-env tricks), or intentionally shares
+state across `it()` boundaries. Quarantine count cap: 10 (informational).
+
+Files that violated these rules at the v0.26.7 baseline are listed in
+`scripts/check-test-isolation.allowlist`. **The allow-list MUST shrink over
+time** ... never add new entries. v0.26.8 (env sweep) and v0.26.9 (PGLite sweep
++ codemod) remove entries as files get fixed.
+
+### Local CI gate (recommended before pushing, v0.23.1+)
+
+```bash
+bun run ci:local         # full gate: gitleaks + unit + ALL 29 E2E files (sequential)
+bun run ci:local:diff    # gate with diff-aware E2E selector
+bun run ci:select-e2e    # print which E2E files the selector would run
+```
+
+`ci:local` spins up `pgvector/pgvector:pg16` + `oven/bun:1` via
+`docker-compose.ci.yml`, runs everything PR CI runs plus the full E2E suite, then
+tears down. Named volumes keep the install warm across runs (~16-20 min sequential
+E2E after the first cold pull). Requires Docker (Docker Desktop, OrbStack, or
+Colima) and `gitleaks` on host (`brew install gitleaks`). Override the postgres
+host port with `GBRAIN_CI_PG_PORT=5435 bun run ci:local` if 5434 collides.
+
+Fail-closed selector: an unmapped `src/` change runs all 29 E2E files. Hand-tune
+narrower mappings via `scripts/e2e-test-map.ts`.
+
 ## Building
 
 ```bash
@@ -95,6 +192,84 @@ See `docs/ENGINES.md` for the full guide. In short:
 
 The SQLite engine is designed and ready for implementation. See `docs/SQLITE_ENGINE.md`.
 
+## CONTRIBUTOR_MODE — turn on the dev loop
+
+gbrain captures retrieval traffic so you can replay real queries against
+your code changes before merging. **This is off by default** (production
+users get a quiet brain, no surprise data accumulation). Contributors turn
+it on with one shell rc line:
+
+```bash
+# In ~/.zshrc or ~/.bashrc:
+export GBRAIN_CONTRIBUTOR_MODE=1
+```
+
+That's it. Every `query` / `search` you (or agents pointed at your dev
+brain) run from that shell now writes a row to `eval_candidates`, and the
+[replay tool](#running-real-world-eval-benchmarks-touching-retrieval-code)
+has data to work against.
+
+What CONTRIBUTOR_MODE actually does:
+
+- Turns on `query`/`search` capture into the local `eval_candidates` table.
+  Without it the gate is closed and capture is a no-op.
+- That's all. PII scrubbing, retention, and replay are independent.
+
+Resolution order (most explicit wins):
+
+1. `eval.capture: true` in `~/.gbrain/config.json` → on
+2. `eval.capture: false` in `~/.gbrain/config.json` → off
+3. `GBRAIN_CONTRIBUTOR_MODE=1` → on
+4. otherwise → off
+
+Quick check that capture is actually running:
+
+```bash
+gbrain query "anything" >/dev/null
+psql $DATABASE_URL -c 'SELECT count(*) FROM eval_candidates'
+# (or `gbrain doctor` — surfaces silent capture failures cross-process)
+```
+
+To disable capture even with the env var set, write
+`{"eval": {"capture": false}}` to `~/.gbrain/config.json` — explicit config
+beats the env var both directions.
+
+## Running real-world eval benchmarks (touching retrieval code)
+
+If your PR touches retrieval — search ranking, RRF fusion, embeddings,
+intent classification, query expansion, source boost, or the `query` /
+`search` op handlers — run `gbrain eval replay` against a snapshot of
+real traffic before merging. Requires `CONTRIBUTOR_MODE` (above) so you
+have captured rows to replay against.
+
+Quick loop:
+
+```bash
+gbrain eval export --since 7d > baseline.ndjson    # snapshot before your change
+# ... make your change ...
+gbrain eval replay --against baseline.ndjson       # diff retrieval, get Jaccard@k
+```
+
+Three numbers come back: mean Jaccard@k between captured and current slug
+sets, top-1 stability, and mean latency Δ. The replay tool flags the worst
+regressions so you can eyeball whether the change is hurting real queries.
+
+Trigger paths (rerun if your diff touches any of these):
+
+- `src/core/search/hybrid.ts`
+- `src/core/search/source-boost.ts`, `sql-ranking.ts`
+- `src/core/search/intent.ts`, `expansion.ts`, `dedup.ts`
+- `src/core/embedding.ts`
+- `src/core/operations.ts` (query / search handlers)
+- `src/core/postgres-engine.ts` / `pglite-engine.ts` (searchKeyword /
+  searchVector SQL)
+
+See [`docs/eval-bench.md`](./docs/eval-bench.md) for the full guide
+including CI integration, hand-crafted NDJSON corpora (so a fresh checkout
+without captured data can still replay), and cost considerations. The
+NDJSON wire format is documented in
+[`docs/eval-capture.md`](./docs/eval-capture.md).
+
 ## Welcome PRs
 
 - SQLite engine implementation

INSTALL_FOR_AGENTS.md

@@ -3,6 +3,17 @@
 Read this entire file, then follow the steps. Ask the user for API keys when needed.
 Target: ~30 minutes to a fully working brain.
 
+## Step 0: If you are not Claude Code
+
+Read `AGENTS.md` at the repo root first. It's the non-Claude-agent operating
+protocol (install, read order, trust boundary, common tasks). Claude Code reads
+`CLAUDE.md` automatically and can skip ahead.
+
+If you fetched this file by URL without cloning yet, the companion files live at:
+- `https://raw.githubusercontent.com/garrytan/gbrain/master/AGENTS.md` — start here
+- `https://raw.githubusercontent.com/garrytan/gbrain/master/llms.txt` — full doc map
+- `https://raw.githubusercontent.com/garrytan/gbrain/master/llms-full.txt` — same map, inlined
+
 ## Step 1: Install GBrain
 
 ```bash
@@ -15,6 +26,11 @@ bun install && bun link
 Verify: `gbrain --version` should print a version number. If `gbrain` is not found,
 restart the shell or add the PATH export to the shell profile.
 
+> **Do NOT use `bun install -g github:garrytan/gbrain`.** Bun blocks the top-level
+> postinstall hook on global installs, so schema migrations never run and the CLI
+> aborts with `Aborted()` when it opens PGLite. Use the `git clone + bun link` path
+> above. Tracking issue: [#218](https://github.com/garrytan/gbrain/issues/218).
+
 ## Step 2: API Keys
 
 Ask the user for these:
@@ -53,6 +69,30 @@ gbrain embed --stale                  # generate vector embeddings
 gbrain query "key themes across these documents?"
 ```
 
+## Step 4.5: Wire the Knowledge Graph
+
+If the user already had a brain repo (Step 3 imported existing markdown), backfill
+the typed-link graph and structured timeline. This populates the `links` and
+`timeline_entries` tables that future writes will maintain automatically.
+
+```bash
+gbrain extract links --source db --dry-run | head -20    # preview
+gbrain extract links --source db                         # commit
+gbrain extract timeline --source db                      # dated events
+gbrain stats                                             # verify links > 0
+```
+
+For brand-new empty brains, skip this step — auto-link populates the graph as the
+agent writes pages going forward. There is nothing to backfill yet.
+
+After this step:
+- `gbrain graph-query <slug> --depth 2` works (relationship traversal)
+- Search ranks well-connected entities higher (backlink boost)
+- Every future `put_page` auto-creates typed links and reconciles stale ones
+
+If a user has a very large brain (>10K pages), `extract --source db` is idempotent
+and supports `--since YYYY-MM-DD` for incremental runs.
+
 ## Step 5: Load Skills
 
 Read `~/gbrain/skills/RESOLVER.md`. This is the skill dispatcher. It tells you which
@@ -89,8 +129,9 @@ Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab):
 - **Live sync** (every 15 min): `gbrain sync --repo ~/brain && gbrain embed --stale`
 - **Auto-update** (daily): `gbrain check-update --json` (tell user, never auto-install)
 - **Dream cycle** (nightly): read `docs/guides/cron-schedule.md` for the full protocol.
-  Entity sweep, citation fixes, memory consolidation. This is what makes the brain
-  compound. Do not skip it.
+  Entity sweep, citation fixes, memory consolidation, plus (v0.23+) overnight conversation
+  synthesis and cross-session pattern detection. 8 phases, one cron-friendly command. This
+  is what makes the brain compound. Do not skip it.
 - **Weekly**: `gbrain doctor --json && gbrain embed --stale`
 
 ## Step 8: Integrations
@@ -103,13 +144,28 @@ Verify: `gbrain integrations doctor` (after at least one is configured)
 
 ## Step 9: Verify
 
-Read `docs/GBRAIN_VERIFY.md` and run all 6 verification checks. Check #4 (live sync
+Read `docs/GBRAIN_VERIFY.md` and run all 7 verification checks. Check #4 (live sync
 actually works) is the most important.
 
 ## Upgrade
 
 ```bash
-cd ~/gbrain && git pull origin main && bun install
+cd ~/gbrain && git pull origin master && bun install
+gbrain init                           # apply schema migrations (idempotent)
+gbrain post-upgrade                   # show migration notes for the version range
 ```
 
-Then run `gbrain init` to apply any schema migrations (idempotent, safe to re-run).
+Then read `~/gbrain/skills/migrations/v<NEW_VERSION>.md` (and any intermediate
+versions you skipped) and run any backfill or verification steps it lists. Skipping
+this is how features ship in the binary but stay dormant in the user's brain.
+
+For v0.12.0+ specifically: if your brain was created before v0.12.0, run
+`gbrain extract links --source db && gbrain extract timeline --source db` to
+backfill the new graph layer (see Step 4.5 above).
+
+For v0.12.2+ specifically: if your brain is Postgres- or Supabase-backed and
+predates v0.12.2, the `v0_12_2` migration runs `gbrain repair-jsonb`
+automatically during `gbrain post-upgrade` to fix the double-encoded JSONB
+columns. PGLite brains no-op. If wiki-style imports were truncated by the old
+`splitBody` bug, run `gbrain sync --full` after upgrading to rebuild
+`compiled_truth` from source markdown.

README.md

@@ -4,10 +4,16 @@ Your AI agent is smart but forgetful. GBrain gives it a brain.
 
 Built by the President and CEO of Y Combinator to run his actual AI agents. The production brain powering his OpenClaw and Hermes deployments: **17,888 pages, 4,383 people, 723 companies**, 21 cron jobs running autonomously, built in 12 days. The agent ingests meetings, emails, tweets, voice calls, and original ideas while you sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. You wake up and the brain is smarter than when you went to bed.
 
-GBrain is those patterns, generalized. 25 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
+The brain wires itself. Every page write extracts entity references and creates typed links (`attended`, `works_at`, `invested_in`, `founded`, `advises`) with zero LLM calls. Hybrid search. Self-wiring knowledge graph. Structured timeline. Backlink-boosted ranking. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked side-by-side against the category: gbrain lands **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, beating its own graph-disabled variant by **+31.4 points P@5** and ripgrep-BM25 + vector-only RAG by a similar margin. The graph layer plus v0.12 extract quality together carry the gap. Full BrainBench scorecards + corpus live in the sibling [gbrain-evals](https://github.com/garrytan/gbrain-evals) repo.
+
+GBrain is those patterns, generalized. 34 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
+
+**New in v0.25.0 — BrainBench-Real (session capture, contributor opt-in):** with `GBRAIN_CONTRIBUTOR_MODE=1` set in your shell, every real `query` + `search` call through MCP, CLI, or the subagent tool-bridge gets captured (PII-scrubbed) into an `eval_candidates` table. Snapshot with `gbrain eval export`, replay against your code change with `gbrain eval replay`. Three numbers come back: mean Jaccard@k between captured and current retrieved slugs, top-1 stability, and latency Δ. **Off by default** for production users — no surprise data accumulation. Walkthrough: [docs/eval-bench.md](docs/eval-bench.md). NDJSON wire format: [docs/eval-capture.md](docs/eval-capture.md).
 
 > **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
 
+> **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).
+
 ## Install
 
 ### On an agent platform (recommended)
@@ -24,7 +30,12 @@ Retrieve and follow the instructions at:
 https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
 ```
 
-That's it. The agent clones the repo, installs GBrain, sets up the brain, loads 25 skills, and configures recurring jobs. You answer a few questions about API keys. ~30 minutes.
+That's it. The agent clones the repo, installs GBrain, sets up the brain, loads 34 skills, and configures recurring jobs. You answer a few questions about API keys. ~30 minutes.
+
+If your agent doesn't auto-read `AGENTS.md`, point it at that file first:
+`https://raw.githubusercontent.com/garrytan/gbrain/master/AGENTS.md` is the non-Claude
+agent operating protocol (install, read order, trust boundary, common tasks). For
+the full doc map, use `llms.txt` at the same URL root.
 
 ### Standalone CLI (no agent)
 
@@ -35,6 +46,19 @@ gbrain import ~/notes/          # index your markdown
 gbrain query "what themes show up across my notes?"
 ```
 
+**Do NOT use `bun install -g github:garrytan/gbrain`.** Bun blocks the top-level
+postinstall hook on global installs, so schema migrations never run and the CLI
+aborts with `Aborted()` the first time it opens PGLite. Use `git clone + bun install
+&& bun link` as shown above. See [#218](https://github.com/garrytan/gbrain/issues/218).
+
+**Do NOT use `bun add -g gbrain` or `npm install -g gbrain`.** The npm registry
+has an unrelated package squatting that name (`gbrain@1.3.x`) — you'd silently
+install the wrong binary and overwrite the canonical one. v0.28.5+ detects this
+and prints a recovery message on `gbrain upgrade`, but the `git clone + bun link`
+path above is the only reliable install method until we publish under
+`@garrytan/gbrain` (tracked v0.29 follow-up). See
+[#658](https://github.com/garrytan/gbrain/issues/658).
+
 ```
 3 results (hybrid search, 0.12s):
 
@@ -63,19 +87,56 @@ GBrain exposes 30+ MCP tools via stdio:
 
 Add to `~/.claude/server.json` (Claude Code), Settings > MCP Servers (Cursor), or your client's MCP config.
 
-### Remote MCP (Claude Desktop, Cowork, Perplexity)
+### Remote MCP with OAuth 2.1 (ChatGPT, Claude Desktop, Cowork, Perplexity)
+
+`gbrain serve --http` starts a production-grade OAuth 2.1 server with an embedded admin dashboard. Zero external infrastructure. Every major AI client connects, every request is scoped, every action is logged.
 
 ```bash
-ngrok http 8787 --url your-brain.ngrok.app
-bun run src/commands/auth.ts create "claude-desktop"
+# Start the HTTP server (prints admin bootstrap token on first start)
+gbrain serve --http --port 3131
+
+# Open the admin dashboard, paste the bootstrap token, register a client
+open http://localhost:3131/admin
+
+# Expose publicly (set --public-url so the OAuth issuer matches)
+ngrok http 3131 --url your-brain.ngrok.app
+gbrain serve --http --port 3131 --public-url https://your-brain.ngrok.app
+
+# ChatGPT and other OAuth-aware clients can also connect:
 claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp -H "Authorization: Bearer TOKEN"
 ```
 
-Per-client guides: [`docs/mcp/`](docs/mcp/DEPLOY.md). ChatGPT requires OAuth 2.1 (not yet implemented).
+Register OAuth clients from the `/admin` dashboard — click **Register client**,
+pick scopes, save the credentials shown once in the reveal modal. Programmatic
+registration via `oauthProvider.registerClientManual(...)` and the
+`gbrain auth register-client` CLI are also available.
 
-## The 25 Skills
+- **OAuth 2.1 via the MCP SDK** — client credentials (machine-to-machine: Perplexity, Claude), authorization code + PKCE (browser-based: ChatGPT), refresh token rotation, revocation, protected resource metadata. Optional Dynamic Client Registration behind `--enable-dcr` (DCR redirect_uris must be `https://` or loopback per RFC 6749 §3.1.2.1).
+- **Scoped operations** — 30 operations tagged `read | write | admin`. `sync_brain` and `file_upload` are `localOnly`, rejected over HTTP.
+- **React admin dashboard** — 7 screens baked into the binary (~65KB gzip). Live SSE activity feed, agents table, credential reveal, filterable request log, per-client config export.
+- **Legacy bearer tokens still work** — pre-v0.26 `gbrain auth create` tokens continue to authenticate as `read+write+admin`. v0.22.7's simpler `src/mcp/http-transport.ts` path stays compiled in for backward compat callers; v0.26+ deployments use the OAuth-aware `serve-http.ts`.
 
-GBrain ships 25 skills organized by `skills/RESOLVER.md`. The resolver tells your agent which skill to read for any task.
+Per-client guides: [`docs/mcp/`](docs/mcp/DEPLOY.md). Hardening defaults, env vars, and threat model: [SECURITY.md](SECURITY.md).
+
+### Using gbrain with GStack
+
+If your engineering agent runs on [GStack](https://github.com/garrytan/gstack), point it at gbrain for code lookup instead of grep+read. Cathedral II (v0.21.0) ships call-graph edges and two-pass retrieval — `/investigate`, `/review`, `/plan-eng-review`, and `/office-hours` all benefit when the agent walks the symbol graph instead of scanning files line by line.
+
+The five magical-moment commands:
+
+```bash
+gbrain code-callers searchKeyword           # who calls this symbol?
+gbrain code-callees searchKeyword           # what does this symbol call?
+gbrain code-def BrainEngine                 # where is X defined?
+gbrain code-refs BrainEngine                # all reference sites
+gbrain query "how does N+1 handling work" --near-symbol BrainEngine.searchKeyword --walk-depth 2
+```
+
+All five auto-emit JSON on non-TTY (gh-CLI convention) so a GStack subagent shelling out via bash gets a clean parseable response. Run `gbrain sources add <repo> --strategy code` to index a repo, then your agent's brain-first lookup covers code, not just markdown. ([Cathedral II release notes](CHANGELOG.md#0210---2026-04-25))
+
+## The 34 Skills
+
+GBrain ships 34 skills organized by `skills/RESOLVER.md` (or your OpenClaw's `AGENTS.md` — both filenames are supported as of v0.19). The resolver tells your agent which skill to read for any task. v0.25.1 added 9 research-flavored skills (`book-mirror` flagship plus 8 pairings); see the new "Research and synthesis" section below.
 
 [Skill files are code.](https://x.com/garrytan/status/2042925773300908103) They're the most powerful way to get knowledge work done. A skill file is a fat markdown document that encodes an entire workflow: when to fire, what to check, how to chain with other skills, what quality bar to enforce. The agent reads the skill and executes it. Skills can also call deterministic TypeScript code bundled in GBrain (search, import, embed, sync) for the parts that shouldn't be left to LLM judgment. [Thin harness, fat skills](docs/ethos/THIN_HARNESS_FAT_SKILLS.md): the intelligence lives in the skills, not the runtime.
 
@@ -94,6 +155,20 @@ GBrain ships 25 skills organized by `skills/RESOLVER.md`. The resolver tells you
 | **idea-ingest** | Links, articles, tweets become brain pages with analysis, author people pages, and cross-linking. |
 | **media-ingest** | Video, audio, PDF, books, screenshots, GitHub repos. Transcripts, entity extraction, backlink propagation. |
 | **meeting-ingestion** | Transcripts become brain pages. Every attendee gets enriched. Every company gets a timeline entry. |
+| **voice-note-ingest** | Voice notes captured verbatim — exact phrasing preserved, never paraphrased. Routes to originals/concepts/people/companies/ideas/personal/voice-notes based on content. |
+| **article-enrichment** | Raw article dumps become structured pages with executive summary, verbatim quotes, key insights, and why-it-matters. |
+
+### Research and synthesis (v0.25.1)
+
+| Skill | What it does |
+|-------|-------------|
+| **book-mirror** | Flagship. Hand the agent a book, get a personalized two-column chapter-by-chapter analysis. Left column preserves the chapter's actual content; right column maps every idea to your life using your words from the brain. ~$6 for a 20-chapter book at Opus. Pairs with `gbrain book-mirror` CLI for the trusted runtime. |
+| **strategic-reading** | Read a book / article / case study through ONE specific problem-lens. Output: applied playbook with do / avoid / watch-for and short / medium / long-term recommendations. |
+| **concept-synthesis** | Deduplicate thousands of concept stubs into a tiered intellectual map (T1 Canon to T4 Riff). Trace how ideas evolved across years of notes. |
+| **perplexity-research** | Brain-augmented web research. Sends brain context to Perplexity so the search focuses on what's NEW vs already-known. Output: Executive Summary + Key New Developments + Confirming Signals + Contradictions or Updates + Recommended Brain Updates + Citations. |
+| **archive-crawler** | Universal archivist for personal file archives (Dropbox / Backblaze / Gmail-takeout / hard-drive dumps). REFUSES to run unless `archive-crawler.scan_paths:` is set in `gbrain.yml`. Safe-by-default safety fence. |
+| **academic-verify** | Trace a research claim through publication → methodology → raw data → independent replication. Routes through perplexity-research; produces a verdict (verified / partial / unverifiable / misattributed / retracted). |
+| **brain-pdf** | Render any brain page to publication-quality PDF via the gstack `make-pdf` binary. Strips frontmatter, sanitizes emoji, applies running headers. |
 
 ### Brain operations
 
@@ -101,7 +176,7 @@ GBrain ships 25 skills organized by `skills/RESOLVER.md`. The resolver tells you
 |-------|-------------|
 | **enrich** | Tiered enrichment (Tier 1/2/3). Creates and updates person/company pages with compiled truth and timelines. |
 | **query** | 3-layer search with synthesis and citations. Says "the brain doesn't have info on X" instead of hallucinating. |
-| **maintain** | Periodic health: stale pages, orphans, dead links, citation audit, back-link enforcement, tag consistency. |
+| **maintain** | Periodic health: stale pages, orphans, dead links, citation audit, back-link enforcement, tag consistency. v0.23 adds the dream cycle's synthesize + patterns phases ... overnight conversation transcripts become reflections, originals, and 25-year patterns. |
 | **citation-fixer** | Scans pages for missing or malformed citations. Fixes format to match the standard. |
 | **repo-architecture** | Where new brain files go. Decision protocol: primary subject determines directory, not format. |
 | **publish** | Share brain pages as password-protected HTML. Zero LLM calls. |
@@ -119,6 +194,10 @@ GBrain ships 25 skills organized by `skills/RESOLVER.md`. The resolver tells you
 | **webhook-transforms** | External events (SMS, meetings, social mentions) converted into brain pages with entity extraction. |
 | **testing** | Validates every skill has SKILL.md with frontmatter, manifest coverage, resolver coverage. |
 | **skill-creator** | Create new skills following the conformance standard. MECE check against existing skills. |
+| **skillify** | The "skillify it!" meta-skill. Orchestrates the 10-step loop so failures become durable skills: scaffold the stubs via `gbrain skillify scaffold`, write the real logic, gate with `gbrain skillify check` + `gbrain check-resolvable`. |
+| **skillpack-check** | Agent-readable gbrain health report. Exit code for CI; JSON for debugging. Cron-friendly. |
+| **smoke-test** | 8 post-restart health checks with auto-fix (Bun, CLI, DB, worker, Zod CJS, gateway, API key, brain repo). Drop-in user tests at `~/.gbrain/smoke-tests.d/*.sh`. |
+| **minion-orchestrator** | Background work in one skill. Shell jobs via `gbrain jobs submit shell` (operator/CLI, MCP blocks protected names) and LLM subagents via `gbrain agent run`. Parent-child DAGs, `child_done` inbox, durability across worker restarts. |
 
 ### Identity and setup
 
@@ -146,6 +225,7 @@ Signal arrives (meeting, email, tweet, link)
   -> Brain-ops: check the brain first (gbrain search, gbrain get)
   -> Respond with full context
   -> Write: update brain pages with new information + citations
+  -> Auto-link: typed relationships extracted on every write (zero LLM calls)
   -> Sync: gbrain indexes changes for next query
 ```
 
@@ -159,6 +239,201 @@ The system gets smarter on its own. Entity enrichment auto-escalates: a person m
 > "What have I said about the relationship between shame and founder performance?"
 > ... searches YOUR thinking, not the internet
 
+## Minions: your sub-agents won't drop work anymore
+
+A durable, Postgres-native job queue built into the brain. Every long-running agent task is now a job that survives gateway restarts, streams progress, gets paused / resumed / steered mid-flight, and shows up in `gbrain jobs list`. Zero infra beyond your existing brain.
+
+### The production numbers that matter
+
+Here's my personal OpenClaw deployment: one Render container. Supabase Postgres holding a 45,000-page brain. 19 cron jobs firing on schedule. Real gateway load from real daily work. The task: pull a month of my social posts from an external API and ingest them end-to-end into the brain as a structured page.
+
+|              | Minions   | `sessions_spawn`               |
+|---           |---        |---                             |
+| Wall time    | **753ms** | **>10,000ms** (gateway timeout) |
+| Token cost   | **$0.00** | ~$0.03 per run                 |
+| Success rate | **100%**  | **0%** (couldn't even spawn)   |
+| Memory/job   | ~2 MB     | ~80 MB                         |
+
+Under that 19-cron load, sub-agent spawn couldn't clear the 10-second gateway wall. Minions landed it in under a second for zero tokens. **Scaling:** 19,240 posts across 36 months, single bash loop, ~15 min total, $0.00. Sub-agents: ~9 min best case, ~$1.08 in tokens, ~40% spawn failure. **Lab:** durability ∞ (SIGKILL mid-flight, 10/10 rescued), throughput ~10× faster, fan-out ~21× with no failure wall, memory ~400× less.
+
+Full benchmarks live in [gbrain-evals](https://github.com/garrytan/gbrain-evals/tree/main/docs/benchmarks).
+
+### The routing rule
+
+> **Deterministic** (same input → same steps → same output) → **Minions**
+> **Judgment** (input requires assessment or decision) → **Sub-agents**
+
+Pull posts, parse JSON, write a brain page, run a sync — deterministic. $0 tokens, survives restart, millisecond runtime. Triage the inbox, assess meeting priority, decide if a cold email deserves a reply — judgment. What sub-agents are actually good at. `minion_mode: pain_triggered` (the default) automates the routing.
+
+### What's fixed
+
+The six daily pains — spawn storms, agents that stop responding, forgotten dispatches, gateway crashes mid-run, runaway grandchildren, debugging soup — all belonged to the "deterministic work through a reasoning model" mistake. Minions fixes them by not making that mistake: `max_children` cap, `timeout_ms` + AbortSignal, `child_done` inbox, full `parent_job_id`/`depth`/transcript per job, Postgres durability with stall detection, cascade cancel via recursive CTE. Plus idempotency keys, attachment validation, `removeOnComplete`, and `gbrain jobs smoke` that proves the install in half a second.
+
+```bash
+gbrain jobs smoke                        # verify install
+gbrain jobs submit sync --params '{}'    # fire a background job
+gbrain jobs stats                        # health dashboard
+gbrain jobs supervisor --concurrency 4   # canonical: auto-restarting worker (Postgres only)
+gbrain jobs work --concurrency 4         # raw worker (no crash recovery — prefer `supervisor`)
+```
+
+`gbrain jobs supervisor` keeps the worker alive across crashes with exponential backoff, atomic PID locking, structured audit events at `~/.gbrain/audit/supervisor-*.jsonl`, and a `start --detach` / `status --json` / `stop` subcommand surface for agents. In containers it runs as PID 1; on systemd hosts it's the child of `gbrain-worker.service`. Full deployment guide: [`docs/guides/minions-deployment.md`](docs/guides/minions-deployment.md).
+
+Read [`skills/minion-orchestrator/SKILL.md`](skills/minion-orchestrator/SKILL.md) for parent-child DAGs, fan-in collection, steering via inbox.
+
+**Minions is not incrementally better than sub-agents for background work. It's categorically different.** 753ms vs gateway timeout. $0 vs tokens. 100% vs couldn't-spawn. If your agent does deterministic work on a schedule, it runs on Minions now.
+
+### Health check and self-heal
+
+Minions is canonical as of v0.11.1 — every `gbrain upgrade` runs the migration automatically (schema → smoke → prefs → host rewrites → env-aware autopilot install). If you ever want to verify manually or wire a cron into your morning briefing:
+
+```bash
+gbrain doctor                    # half-migrated state? prints loud banner + exits non-zero
+gbrain skillpack-check --quiet    # exit 0/1/2 for pipeline gating
+gbrain skillpack-check | jq       # full JSON: {healthy, summary, actions[], doctor, migrations}
+```
+
+If anything's off, `actions[]` tells you the exact command to run. For deeper troubleshooting: [`docs/guides/minions-fix.md`](docs/guides/minions-fix.md).
+
+Moving gateway crons to Minions (deterministic scripts, zero LLM tokens per fire): [`docs/guides/minions-shell-jobs.md`](docs/guides/minions-shell-jobs.md).
+
+## Durable agents: `gbrain agent` (v0.15)
+
+Your subagent runs survive crashes now. OpenClaw died mid-run? The worker re-claims on restart and replays from the last committed turn. Fan-out across 50 shards, one shard crashes — the aggregator still claims after every child reaches a terminal state and writes a mixed-outcome summary. Tool calls persist as a two-phase ledger (`pending` → `complete | failed`) so replay is safe by construction, not by hope.
+
+```bash
+# Submit a single-subagent run
+gbrain agent run "summarize my last 10 journal pages"
+
+# Fan out N prompts across N subagent children + 1 aggregator
+gbrain agent run "analyze every page" \
+  --fanout-manifest manifests/pages.json \
+  --subagent-def analyzer
+
+# Tail a running job (heartbeat per turn + full transcript on completion)
+gbrain agent logs 1247 --follow --since 5m
+```
+
+Durability is the point: every Anthropic turn commits to `subagent_messages`, every tool call to `subagent_tool_executions`. Worker kills, OpenClaw crashes, timeouts — all resumable. Host repos (your OpenClaw, etc.) ship their own subagent definitions via `GBRAIN_PLUGIN_PATH` + a `gbrain.plugin.json` manifest: see [`docs/guides/plugin-authors.md`](docs/guides/plugin-authors.md). Requires `ANTHROPIC_API_KEY` on the worker.
+
+## Skillify: say "skillify it!" and the bug becomes structurally impossible to repeat
+
+Your OpenClaw hit a new failure. You fix it once in conversation. You say "skillify it!"
+And now the fix is permanent: a SKILL.md with triggers, a deterministic script with tests, a
+routing fixture the agent re-evaluates daily, a filing audit that keeps the output from
+drifting. Ten items. Every one required. The bug can't recur.
+
+Hermes and similar agent frameworks auto-create skills as a background behavior. Fine until
+you don't know what the agent shipped. Checklists decay. Tests drift. Resolver entries get
+stale. Six months later it's an opaque pile nobody has read, nobody has tested, and nobody
+is sure still works. GBrain ships the same capability except the human stays in the loop
+and every step is a command you can run.
+
+### The four verbs you need (v0.19)
+
+```bash
+# 1. Scaffold all 5 stub files for a new skill in one shot.
+gbrain skillify scaffold webhook-verify \
+  --description "verify ngrok webhooks" \
+  --triggers "verify the webhook,check tunnel" \
+  --writes-pages --writes-to people/,companies/
+
+# 2. Replace the SKILLIFY_STUB sentinels with real logic + real tests.
+$EDITOR skills/webhook-verify/scripts/webhook-verify.mjs
+$EDITOR test/webhook-verify.test.ts
+
+# 3. Run the 10-item audit: SKILL.md exists, script exists, unit + E2E tests,
+#    LLM evals, resolver entry, trigger eval, check-resolvable gate, brain filing.
+gbrain skillify check skills/webhook-verify/scripts/webhook-verify.mjs
+
+# 4. Verify the whole tree: reachability, MECE overlap, DRY, routing gaps,
+#    filing audit, SKILLIFY_STUB sentinels (fails if any skill still has one).
+gbrain check-resolvable              # warnings advisory, errors block
+gbrain check-resolvable --strict     # warnings block too (CI opt-in)
+```
+
+Idempotent re-runs. `--force` regenerates stub files but NEVER duplicates a resolver row.
+Scaffold completes in under 2 seconds. The real work (your rule, your script, your tests)
+is what you spend time on. Everything else is boilerplate the CLI writes for you.
+
+### `gbrain routing-eval` — catch the routing gaps your users actually hit
+
+Drop a `routing-eval.jsonl` fixture next to any skill. Each line is `{intent, expected_skill,
+ambiguous_with?}`. `gbrain check-resolvable` runs the structural layer by default; `gbrain
+routing-eval` runs the same structural layer as a dedicated CI verb. The `--llm` flag is
+accepted as a placeholder for a future LLM tie-break layer; in this release it emits a stderr
+notice and runs structural only. False positives (wrong skill matched), missed routes (no
+skill matched), and tautological fixtures (intent copies trigger verbatim) all surface as
+specific advisories with the exact file:line to fix.
+
+### Works on your OpenClaw, not just gbrain's repo
+
+v0.19 teaches `gbrain check-resolvable` to accept `AGENTS.md` as a resolver file alongside
+`RESOLVER.md`, at either the skills directory OR one level up (OpenClaw-native workspace-root
+layout). The skill manifest auto-derives from walking `skills/*/SKILL.md` when `manifest.json`
+is missing. Set `OPENCLAW_WORKSPACE=~/your-openclaw/workspace` and everything just works:
+
+```bash
+export OPENCLAW_WORKSPACE=~/your-openclaw/workspace
+gbrain check-resolvable --verbose
+# Auto-detects: AGENTS.md at workspace root, 107 skills derived from SKILL.md walk,
+# 15 unreachable errors surfaced, 108 advisory warnings for overlaps and gaps.
+```
+
+First run on a real OpenClaw deployment found 15 unreachable skills out of 102 — about 15%
+of the tree was dark. The essay's "skills the agent can never reach" footgun, now visible.
+
+### `gbrain skillpack install` — drop 25 curated skills into your OpenClaw
+
+The skills gbrain ships are a curated bundle. Install them into your workspace with
+dependency closure (shared conventions come along), per-file diff protection (your local
+edits are never clobbered without `--overwrite-local`), a file lock that serializes
+concurrent installers, and an atomic managed-block update to your AGENTS.md so you can
+see exactly what gbrain wrote.
+
+```bash
+gbrain skillpack list                          # 25 curated skills
+gbrain skillpack install brain-ops             # one skill + its shared conventions
+gbrain skillpack install --all                 # the full bundle
+gbrain skillpack install brain-ops --dry-run   # preview; no writes
+gbrain skillpack diff brain-ops                # compare bundle vs your local copy
+```
+
+Re-running is safe. The managed-block markers in your AGENTS.md let `skillpack install`
+accumulate rows across separate single-skill installs instead of overwriting each other.
+A receipt comment inside the fence (`<!-- gbrain:skillpack:manifest cumulative-slugs="..." -->`)
+tracks what gbrain has installed across runs. `install --all` is the only path that prunes;
+per-skill install never deletes what it didn't install. If you hand-add a row inside the fence,
+gbrain preserves it on reinstall and emits a stderr notice telling your agent to investigate.
+
+**Skillify is the piece that makes the skills tree survive six months of compounding work.**
+Read [`skills/skillify/SKILL.md`](skills/skillify/SKILL.md) for the full 10-item checklist
+and the anti-patterns it catches.
+
+## Storage tiering: keep bulk content out of git (v0.22.11)
+
+When your brain crosses 100K files and bulk machine-generated content (tweets, articles, transcripts)
+becomes the size driver, declare which directories belong in git and which live in the database only.
+
+```yaml
+# gbrain.yml at the brain repo root
+storage:
+  db_tracked:
+    - people/
+    - companies/
+    - deals/
+  db_only:
+    - media/x/
+    - media/articles/
+    - meetings/transcripts/
+```
+
+`gbrain sync` auto-manages your `.gitignore` for `db_only` paths. `gbrain export --restore-only --repo .`
+repopulates missing files from the database (container restart, fresh clone, accidental rm).
+`gbrain storage status` shows the tier breakdown.
+
+Full guide: [docs/storage-tiering.md](docs/storage-tiering.md).
+
 ## Getting Data In
 
 GBrain ships integration recipes that your agent sets up for you. Each recipe tells the agent what credentials to ask for, how to validate, and what cron to register.
@@ -172,6 +447,7 @@ GBrain ships integration recipes that your agent sets up for you. Each recipe te
 | [X-to-Brain](recipes/x-to-brain.md) | — | Twitter timeline + mentions + deletions |
 | [Calendar-to-Brain](recipes/calendar-to-brain.md) | credential-gateway | Google Calendar to searchable daily pages |
 | [Meeting Sync](recipes/meeting-sync.md) | — | Circleback transcripts to brain pages with attendees |
+| [Restart Sweep](recipes/restart-sweep.md) | OpenClaw + Telegram | Detect dropped Telegram messages after OpenClaw gateway restarts |
 
 **Data research recipes** extract structured data from email into tracked brain pages. Built-in recipes for investor updates (MRR, ARR, runway, headcount), expense tracking, and company metrics. Create your own with `gbrain research init`.
 
@@ -194,7 +470,7 @@ Run `gbrain integrations` to see status.
 │   Brain Repo     │    │    GBrain     │    │    AI Agent      │
 │   (git)          │    │  (retrieval)  │    │  (read/write)    │
 │                  │    │               │    │                  │
-│  markdown files  │───>│  Postgres +   │<──>│  25 skills       │
+│  markdown files  │───>│  Postgres +   │<──>│  29 skills       │
 │  = source of     │    │  pgvector     │    │  define HOW to   │
 │    truth         │    │               │    │  use the brain   │
 │                  │<───│  hybrid       │    │                  │
@@ -230,6 +506,36 @@ want, which you can't learn any other way.
 
 Above the `---`: **compiled truth**. Your current best understanding. Gets rewritten when new evidence changes the picture. Below: **timeline**. Append-only evidence trail. Never edited, only added to.
 
+## Knowledge Graph
+
+Pages aren't just text. Every mention of a person, company, or concept becomes a typed link in a structured graph. The brain wires itself.
+
+```
+Write a meeting page mentioning Alice and Acme AI
+  -> Auto-link extracts entity refs from content (zero LLM calls)
+  -> Infers types: meeting page + person ref => `attended`
+                   "CEO of X" pattern        => `works_at`
+                   "invested in"             => `invested_in`
+                   "advises", "advisor"      => `advises`
+                   "founded", "co-founded"   => `founded`
+  -> Reconciles stale links: edits remove links no longer in content
+  -> Backlinks rank well-connected entities higher in search
+```
+
+```bash
+gbrain graph-query people/alice --type attended --depth 2
+# returns who Alice met with, transitively
+```
+
+The graph powers questions vector search can't: "who works at Acme AI?", "what has Bob invested in?", "find the connection between Alice and Carol". Backfill an existing brain in one command:
+
+```bash
+gbrain extract links --source db        # wire up the existing 29K pages
+gbrain extract timeline --source db     # extract dated events from markdown timelines
+```
+
+Then ask graph questions or watch the search ranking improve. Benchmarked side-by-side against ripgrep-BM25, vector-only RAG (same embedder), and gbrain-with-graph-disabled: gbrain lands **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, beating hybrid-nograph by **+31.4 points P@5**. Isolate the contribution: v0.11→v0.12 moved the same gbrain codebase from P@5 22.1% → 49.1% on identical inputs, so typed-link extract quality is load-bearing. Full scorecards + reproducible corpus: [gbrain-evals](https://github.com/garrytan/gbrain-evals).
+
 ## Search
 
 Hybrid search: vector + keyword + RRF fusion + multi-query expansion + 4-layer dedup.
@@ -247,6 +553,76 @@ Query
 
 Keyword alone misses conceptual matches. Vector alone misses exact phrases. RRF gets both. Search quality is benchmarked and reproducible: `gbrain eval --qrels queries.json` measures P@k, Recall@k, MRR, and nDCG@k. A/B test config changes before deploying them.
 
+## Why it works: many strategies in concert
+
+The brain isn't one trick. Every retrieval question goes through ~20 deterministic
+techniques layered together. No single one is magic; the win comes from stacking
+them so each layer covers what the others miss.
+
+```
+Question
+  │
+  ├─ INGESTION (every put_page)
+  │    ├─ Recursive markdown chunking (or semantic / LLM-guided)
+  │    ├─ Embedding cache invalidation on edit
+  │    └─ Idempotent imports (content-hash dedup)
+  │
+  ├─ GRAPH EXTRACTION (auto-link post-hook, zero LLM)
+  │    ├─ Entity-ref regex (markdown links + bare slugs)
+  │    ├─ Code-fence stripping (no false-positive slugs in code blocks)
+  │    ├─ Typed inference cascade (FOUNDED → INVESTED → ADVISES → WORKS_AT)
+  │    ├─ Page-role priors (partner-bio language → invested_in)
+  │    ├─ Within-page dedup (same target collapses to one link)
+  │    ├─ Stale-link reconciliation (edits remove dropped refs)
+  │    └─ Multi-type link constraint (same person can works_at AND advises)
+  │
+  ├─ SEARCH PIPELINE (every query)
+  │    ├─ Intent classifier (entity / temporal / event / general — auto-routes)
+  │    ├─ Multi-query expansion (Haiku rephrases the question 3 ways)
+  │    ├─ Vector search (HNSW cosine over OpenAI embeddings)
+  │    ├─ Keyword search (Postgres tsvector + websearch_to_tsquery)
+  │    ├─ Source-aware ranking (curated dirs outrank chat/daily swamp at SQL layer)
+  │    ├─ Hard-exclude (test/ archive/ attachments/ .raw/ filtered before retrieval)
+  │    ├─ Reciprocal Rank Fusion (score = sum 1/(60+rank) across both)
+  │    ├─ Cosine re-scoring (re-rank chunks against actual query embedding)
+  │    ├─ Compiled-truth boost (assessments outrank timeline noise)
+  │    ├─ Backlink boost (well-connected entities rank higher)
+  │    └─ Source-aware dedup (one CT chunk per page guaranteed)
+  │
+  ├─ GRAPH TRAVERSAL (relational queries)
+  │    ├─ Recursive CTE with cycle prevention (visited-array check)
+  │    ├─ Type-filtered edges (--type works_at, attended, etc.)
+  │    ├─ Direction control (in / out / both)
+  │    └─ Depth-capped (≤10 for remote MCP; DoS prevention)
+  │
+  └─ AGENT WORKFLOW (graph-confident hybrid)
+       ├─ Graph-query first (high-precision typed answers)
+       ├─ Grep fallback when graph returns nothing
+       └─ Graph hits ranked first in top-K (better P@K and R@K)
+```
+
+End-to-end on the BrainBench v1 corpus (240 rich-prose pages, before/after PR #188):
+
+| Metric                  | BEFORE PR #188 | AFTER PR #188 | Δ           |
+|-------------------------|----------------|---------------|-------------|
+| **Precision@5**         | 39.2%          | **44.7%**     | **+5.4 pts**|
+| **Recall@5**            | 83.1%          | **94.6%**     | **+11.5 pts**|
+| Correct in top-5        | 217            | 247           | **+30**     |
+| Graph-only F1 (ablation)| 57.8% (grep)   | **86.6%**     | **+28.8 pts**|
+
+Plus 5 orthogonal capability checks (identity resolution, temporal queries,
+performance at 10K-page scale, robustness to malformed input, MCP operation
+contract). All pass. Full report: [gbrain-evals](https://github.com/garrytan/gbrain-evals).
+
+The point: each technique handles a class of inputs the others miss. Vector
+search misses exact slug refs; keyword catches them. Keyword misses conceptual
+matches; vector catches them. RRF picks the best of both. Compiled-truth boost
+keeps assessments above timeline noise. Auto-link extraction wires the graph
+that lets backlink boost rank well-connected entities higher. Graph traversal
+answers questions search alone can't reach. The agent picks graph-first for
+precision and falls back to keyword for recall. **All deterministic, all in
+concert, all measured.**
+
 ## Voice
 
 Call a phone number. Your AI answers. It knows who's calling, pulls their full context from the brain, and responds like someone who actually knows your world. When the call ends, a brain page appears with the transcript, entity detection, and cross-references.
@@ -314,8 +690,11 @@ SEARCH
   gbrain query <question>              Hybrid search (vector + keyword + RRF)
 
 IMPORT
-  gbrain import <dir> [--no-embed]      Import markdown (idempotent)
-  gbrain sync [--repo <path>]           Git-to-brain incremental sync
+  gbrain import <dir> [--no-embed] [--workers N]
+                                        Import markdown (idempotent)
+  gbrain sync [--repo <path>] [--workers N]
+                                        Git-to-brain incremental sync
+                                        (>100-file diffs auto-parallelize 4 workers on Postgres)
   gbrain export [--dir ./out/]          Export to markdown
 
 FILES
@@ -325,16 +704,65 @@ EMBEDDINGS
   gbrain embed [<slug>|--all|--stale]   Generate/refresh embeddings
 
 LINKS + GRAPH
-  gbrain link|unlink|backlinks|graph    Cross-reference management
+  gbrain link|unlink|backlinks          Cross-reference management
+  gbrain extract links|timeline|all     Batch backfill from existing pages
+                                        (--source db|fs, --type, --since, --dry-run)
+  gbrain graph-query <slug>             Typed traversal (--type T --depth N
+                                        --direction in|out|both)
+
+JOBS (Minions)
+  gbrain jobs submit <name> [--params JSON] [--follow]  Submit a background job
+  gbrain jobs list [--status S] [--queue Q]             List jobs with filters
+  gbrain jobs get|cancel|retry|delete <id>              Manage job lifecycle
+  gbrain jobs prune [--older-than 30d]                  Clean completed/dead jobs
+  gbrain jobs stats                                     Job health dashboard
+  gbrain jobs smoke                                     One-command health check
+  gbrain jobs work [--queue Q] [--concurrency N]        Start worker daemon
+
+SKILLS (v0.19)
+  gbrain skillify scaffold <name>       Create 5 stub files + idempotent resolver row
+  gbrain skillify check [path]          10-item audit of a skill
+  gbrain skillpack list                 Print the 25 curated skills in the bundle
+  gbrain skillpack install <name>       Copy one skill + its shared conventions into target
+  gbrain skillpack install --all        Install the full curated bundle
+  gbrain skillpack diff <name>          Per-file diff: bundle vs target workspace
+  gbrain check-resolvable [--strict]    Resolver audit (reachability, MECE, DRY, routing, filing,
+                                        SKILLIFY_STUB). Accepts RESOLVER.md OR AGENTS.md.
+  gbrain routing-eval [--llm] [--json]  Intent→skill routing accuracy on fixtures
 
 ADMIN
   gbrain doctor [--json] [--fast]       Health checks (resolver, skills, DB, embeddings)
-  gbrain doctor --fix                   Auto-fix resolver issues
+  gbrain doctor --fix [--dry-run]       Auto-fix DRY violations (delegate inlined rules to conventions)
+  gbrain doctor --locks                 List idle-in-tx backends (57014 diagnostic, Postgres only)
   gbrain stats                          Brain statistics
   gbrain serve                          MCP server (stdio)
+  gbrain serve --http [--port 3131]     HTTP MCP server with OAuth 2.1 + admin dashboard
+                                        [--token-ttl 3600] [--enable-dcr]
+                                        [--public-url URL] [--log-full-params]
+  gbrain auth create|list|revoke|test   Legacy bearer token management
+  gbrain auth register-client <name>    Register an OAuth 2.1 client
+        --grant-types client_credentials,authorization_code
+        --scopes "read write admin"
+  gbrain auth revoke-client <client_id> Revoke an OAuth 2.1 client (cascade purges
+                                        active tokens + auth codes via FK CASCADE)
+  # OAuth 2.1 clients can also be registered from the /admin dashboard or
+  # programmatically via oauthProvider.registerClientManual() for host-repo wrappers.
   gbrain integrations                   Integration recipe dashboard
+  gbrain sources list|add|remove|...    Multi-source brain management (v0.18)
+                                        v0.28.2: --url <https://...> registers a federated
+                                        remote git repo; clone is auto-managed under
+                                        $GBRAIN_HOME/clones/<id>/ and re-cloned on sync if
+                                        it goes missing. Also exposed via MCP for remote
+                                        agent setup (whoami + sources_{add,list,remove,status}).
+  gbrain dream [--dry-run] [--phase N]  8-phase maintenance cycle (lint→backlinks→sync→synthesize
+                                        →extract→patterns→embed→orphans). v0.23 added synthesize +
+                                        patterns: transcripts → reflections + cross-session themes.
+  gbrain dream --input <file>           Ad-hoc transcript synthesis (implies --phase synthesize)
+  gbrain dream --date YYYY-MM-DD        Synthesize a single day; --from/--to for backfill ranges
   gbrain check-backlinks check|fix      Back-link enforcement
   gbrain lint [--fix]                   LLM artifact detection
+  gbrain repair-jsonb [--dry-run]       Repair v0.12.0 double-encoded JSONB (Postgres)
+  gbrain orphans [--json] [--count]     Find pages with zero inbound wikilinks
   gbrain transcribe <audio>             Transcribe audio (Groq Whisper)
   gbrain research init <name>           Scaffold a data-research recipe
   gbrain research list                  Show available recipes
@@ -354,7 +782,7 @@ The skills in this repo are those patterns, generalized. What took 11 days to bu
 
 **For agents:**
 - **[skills/RESOLVER.md](skills/RESOLVER.md)** ... Start here. The skill dispatcher.
-- [Individual skill files](skills/) ... 25 standalone instruction sets
+- [Individual skill files](skills/) ... 28 standalone instruction sets (25 ship in the curated `gbrain skillpack install` bundle)
 - [GBRAIN_SKILLPACK.md](docs/GBRAIN_SKILLPACK.md) ... Legacy reference architecture
 - [Getting Data In](docs/integrations/README.md) ... Integration recipes and data flow
 - [GBRAIN_VERIFY.md](docs/GBRAIN_VERIFY.md) ... Installation verification
@@ -368,9 +796,14 @@ The skills in this repo are those patterns, generalized. What took 11 days to bu
 - [GBRAIN_V0.md](docs/GBRAIN_V0.md) ... Full product spec
 - [CHANGELOG.md](CHANGELOG.md) ... Version history
 
+**Benchmarks:**
+- [gbrain-evals](https://github.com/garrytan/gbrain-evals) ... BrainBench, the sibling repo that holds the eval harness, corpus, scorecards, and 4-adapter comparisons. Depends on gbrain; not installed alongside gbrain.
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Run `bun test` for unit tests. E2E tests: spin up Postgres with pgvector, run `bun run test:e2e`, tear down.
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run `bun run test` for the parallel unit-test fast loop (~85s on a Mac dev box, 3700+ tests) or `bun run verify` for the pre-push gate (privacy + jsonb + progress + test-isolation + wasm + admin-build + typecheck). For the full local CI gate (gitleaks + unit + all 29 E2E files in Docker, the same checks GH Actions runs), use `bun run ci:local` ... or `bun run ci:local:diff` for the diff-aware subset during fast iteration.
+
+If you're working on retrieval or any of the search/embedding/ranking surface, set `GBRAIN_CONTRIBUTOR_MODE=1` in your shell rc and use `gbrain eval replay` to gate your changes against a snapshot of real captured queries — the dev loop is documented in [`docs/eval-bench.md`](docs/eval-bench.md). Capture is **off by default** for production users (no surprise data accumulation); the env var is the contributor opt-in.
 
 PRs welcome for: new enrichment APIs, performance optimizations, additional engine backends, new skills following the conformance standard in `skills/skill-creator/SKILL.md`.
 

SECURITY.md

@@ -0,0 +1,179 @@
+# Security
+
+## Reporting Vulnerabilities
+
+If you discover a security issue in GBrain, please report it privately by opening
+a [private security advisory](https://github.com/garrytan/gbrain/security/advisories/new)
+on GitHub.
+
+Do not open a public issue for security vulnerabilities.
+
+## Remote MCP Security
+
+### ⚠️ Do NOT use open OAuth client registration for remote MCP
+
+If you deploy GBrain's MCP server behind an HTTP wrapper with OAuth 2.1
+support, **never allow unauthenticated client registration**. An attacker
+who discovers your server URL can:
+
+1. Register a new OAuth client via `POST /register`
+2. Use `client_credentials` grant to obtain a bearer token
+3. Access all brain data via the MCP tools
+
+### Recommended: `gbrain serve --http`
+
+As of v0.22.7, GBrain ships a built-in HTTP transport that uses the
+existing `access_tokens` table for authentication:
+
+```bash
+# Create a token
+gbrain auth create "my-client"
+
+# Start the HTTP server
+gbrain serve --http --port 8787
+
+# Connect via ngrok, Tailscale, or any tunnel
+ngrok http 8787 --url your-brain.ngrok.app
+```
+
+This is the recommended way to expose GBrain remotely. No OAuth, no
+registration endpoint, no self-service tokens. Tokens are managed
+exclusively via `gbrain auth create/list/revoke`.
+
+### If you must use a custom HTTP wrapper
+
+1. **Require a secret for client registration** — check a header or body
+   parameter before creating new OAuth clients
+2. **Disable `client_credentials` grant** — only allow `authorization_code`
+   with browser-based approval
+3. **Restrict scopes** — never issue tokens with unlimited scope
+4. **Log all token issuance** — alert on unexpected registrations
+5. **Rate-limit registration and token endpoints**
+
+### Token Management
+
+```bash
+gbrain auth create "claude-desktop"   # Create a new token
+gbrain auth list                       # List all tokens
+gbrain auth revoke "claude-desktop"    # Revoke a token
+gbrain auth test <url> --token <tok>   # Smoke-test a remote server
+```
+
+Tokens are stored as SHA-256 hashes in the `access_tokens` table. The
+plaintext token is shown once at creation and never stored.
+
+## `gbrain serve --http` hardening (v0.22.7+)
+
+The built-in HTTP transport ships with several layers of hardening on by
+default. All env vars below are optional; the defaults are intentionally
+conservative.
+
+### Postgres-only
+
+`gbrain serve --http` requires a Postgres engine. PGLite is local-only by
+design and the `access_tokens` / `mcp_request_log` tables don't exist in
+the PGLite schema. Local agents continue to use stdio (`gbrain serve`).
+Running `--http` against a PGLite-backed install fails fast with a clear
+error message at startup.
+
+### CORS
+
+Default-deny: no `Access-Control-Allow-Origin` header is sent unless an
+allowlist is configured. To allow browser-based MCP clients:
+
+```bash
+GBRAIN_HTTP_CORS_ORIGIN=https://claude.ai gbrain serve --http --port 8787
+# Multiple origins: comma-separated
+GBRAIN_HTTP_CORS_ORIGIN=https://claude.ai,https://your.app gbrain serve --http
+```
+
+When the request `Origin` matches the allowlist, the server echoes it
+back in `Access-Control-Allow-Origin` (with `Vary: Origin`). Otherwise no
+CORS header is sent and the browser blocks the request.
+
+### Rate limiting
+
+Two buckets, both stored in a bounded LRU map (default 10K keys, evicts
+least-recently-used on overflow, prunes entries older than 2× the
+window):
+
+| Bucket | When it fires | Default | Env var |
+|---|---|---|---|
+| Pre-auth IP | Before the DB lookup, on every `/mcp` request | 30 req / 60s | `GBRAIN_HTTP_RATE_LIMIT_IP` |
+| Post-auth token | After a valid token is resolved | 60 req / 60s | `GBRAIN_HTTP_RATE_LIMIT_TOKEN` |
+| LRU cap | Maximum distinct keys across both buckets | 10000 | `GBRAIN_HTTP_RATE_LIMIT_LRU` |
+
+On exhaustion the server returns `429 Too Many Requests` with a
+`Retry-After` header.
+
+**Caveat for tunneled deployments (ngrok, Tailscale Funnel, Cloudflare
+Tunnel):** all requests share one egress IP, so the pre-auth IP bucket
+becomes effectively shared by all clients on that tunnel. The
+post-auth token-id bucket is the load-bearing limiter for tunnel-fronted
+deployments.
+
+### Reverse-proxy trust
+
+Disabled by default. To honor `X-Forwarded-For` (or `X-Real-IP`) when
+gbrain runs behind a trusted reverse proxy:
+
+```bash
+GBRAIN_HTTP_TRUST_PROXY=1 gbrain serve --http --port 8787
+```
+
+**Critical safety contract:** only set `GBRAIN_HTTP_TRUST_PROXY=1` when
+**both** of these are true:
+
+1. gbrain is reachable only via a trusted reverse proxy (not directly
+   exposed to the internet on the configured port). The simplest
+   guarantee is to bind gbrain to `127.0.0.1` or a private interface
+   and have the proxy forward to it.
+2. The proxy strips any client-supplied `X-Forwarded-For` and `X-Real-IP`
+   headers, then sets them itself. (nginx with `proxy_set_header
+   X-Forwarded-For $remote_addr` does this; Cloudflare and most cloud
+   load balancers handle it automatically.)
+
+If gbrain is reachable directly AND `GBRAIN_HTTP_TRUST_PROXY=1` is set,
+clients can spoof their IP by sending arbitrary `X-Forwarded-For`
+headers, defeating the pre-auth IP rate limit. Without the flag, gbrain
+ignores all forwarded-for headers and uses the socket peer address,
+which is the safe default for direct-exposure deployments.
+
+### Body size cap
+
+Default 1 MiB, stream-counted (chunked transfers without
+`Content-Length` are still capped). Override:
+
+```bash
+GBRAIN_HTTP_MAX_BODY_BYTES=2097152 gbrain serve --http   # 2 MiB
+```
+
+Over-cap requests get `413 Payload Too Large` immediately, before any
+body is materialized in memory.
+
+### Audit log
+
+Every `/mcp` request writes one row to `mcp_request_log`:
+
+```bash
+psql "$DATABASE_URL" -c \
+  "SELECT created_at, token_name, operation, status, latency_ms
+   FROM mcp_request_log
+   ORDER BY created_at DESC LIMIT 100"
+```
+
+`status` is one of: `success`, `error`, `auth_failed`, `rate_limited`,
+`body_too_large`, `parse_error`, `unknown_method`. Failed-auth rows have
+`token_name = NULL`. Inserts are fire-and-forget so audit failures
+never block requests.
+
+**v0.26.9 redaction default.** The `params` column now stores
+`{redacted, kind, declared_keys, unknown_key_count, approx_bytes}` instead
+of raw JSON-RPC payloads. Declared keys (intersected against the operation's
+spec) preserve for debug visibility; unknown keys are counted but never
+named so attackers can't probe key existence; byte sizes bucket to 1KB so
+content sizes can't be binary-searched. The same shape is broadcast on the
+admin SSE feed at `/admin/events`. Operators on a personal laptop who want
+raw payloads back can pass `gbrain serve --http --log-full-params` (loud
+stderr warning at startup). Multi-tenant deployments should leave it
+on the redacted default.

VERSION

@@ -1 +1 @@
-0.10.0
+0.28.7

admin/DESIGN.md

@@ -0,0 +1,158 @@
+# Design System — GBrain Admin Dashboard
+
+## Product Context
+- **What this is:** Admin dashboard for GBrain MCP server — manage OAuth agents, API keys, monitor requests
+- **Who it's for:** GBrain operators managing multi-agent access to their brain
+- **Space/industry:** Developer infrastructure (peers: Supabase dashboard, Vercel, Railway)
+- **Project type:** Dense utilitarian admin panel — Steve Krug "Don't Make Me Think"
+
+## Aesthetic Direction
+- **Direction:** Industrial/Utilitarian — function-first, data-dense, zero decoration
+- **Decoration level:** None — every pixel earns its place with information
+- **Mood:** Ops dashboard for someone who builds. Not a marketing site. Not a consumer app. A cockpit.
+- **Reference:** Supabase dashboard (dark + dense), Linear (restrained), Grafana (data-forward)
+
+## Alignment
+- **Text alignment:** Left-align everything. No centered text in tables, cards, forms, or labels.
+- **Headings:** Left-aligned
+- **Table data:** Left-aligned (including numbers — contextual readability over columnar alignment)
+- **Form labels:** Left-aligned above inputs
+- **Buttons in forms:** Right-aligned (action flows left-to-right: Cancel → Submit)
+- **Modal titles:** Left-aligned
+- **Page titles:** Left-aligned
+- **Only exception:** Empty states and the login page lock icon can center for visual weight
+
+## Typography
+- **Display/Headings:** Inter (Semibold 600) — clean, neutral, disappears into the content
+- **Body/UI:** Inter (Regular 400 / Medium 500)
+- **Data/Tables/Code:** JetBrains Mono (Regular 400 / Medium 500) — monospace for anything the user might copy, any ID, any token, any technical value
+- **Loading:** Google Fonts. `display=swap`.
+- **Scale:**
+  - Page title: 24px / Inter Semibold
+  - Section title: 14px / Inter Semibold, uppercase, letter-spacing 0.5px
+  - Table header: 12px / Inter Medium, uppercase, letter-spacing 1px, muted color
+  - Body: 14px / Inter Regular
+  - Small/Caption: 13px
+  - Micro: 12px (badges, timestamps)
+  - Code/Data: 13px / JetBrains Mono
+
+## Color
+- **Approach:** Monochrome base + semantic color only. No primary brand color. Color means something.
+- **Background:**
+  - Base: #0a0a0f (near-black with blue undertone)
+  - Surface/cards: #12121a
+  - Hover: #1a1a2a
+  - Input/code blocks: #0f0f1a
+- **Borders:** #1e1e2e (default), #3a3a5a (hover/active)
+- **Text:**
+  - Primary: #e0e0e0
+  - Secondary: #888888
+  - Muted: #555555
+  - Link: #88aaff
+- **Semantic (badges only):**
+  - Success/active: #34a853
+  - Error/danger: #ff6b6b
+  - Warning: #f5a623
+  - Read scope: #3b82f6
+  - Write scope: #f59e0b
+  - Admin scope: #ef4444
+- **No accent color.** The data IS the interface. Badges carry all the color.
+
+## Spacing
+- **Base unit:** 4px
+- **Density:** Dense — this is an ops tool, not a landing page
+- **Scale:** 4px, 8px, 12px, 16px, 20px, 24px, 32px, 48px
+- **Table row padding:** 10px 16px
+- **Card padding:** 24px
+- **Modal padding:** 24px
+- **Section gaps:** 24px between sections, 12px between related elements
+
+## Layout
+- **Sidebar:** Fixed left, 200px wide, dark (#0a0a0f)
+- **Main content:** Fluid, max-width none (fills available space)
+- **Grid:** Single column for tables (full width), 2-column for stats cards
+- **Border radius:**
+  - Cards/panels: 16px
+  - Buttons/inputs: 8px
+  - Badges: 9999px (pill)
+  - Tables: 0 (sharp edges — data is rectangular)
+
+## Components
+
+### Tables
+- Full-width, no outer border
+- Header row: uppercase, letter-spaced, muted color, no background
+- Data rows: subtle hover (#1a1a2a), pointer cursor when clickable
+- All text left-aligned
+- Monospace for IDs, tokens, latency values
+
+### Badges
+- Pill shape (border-radius: 9999px)
+- Padding: 2px 8px
+- Font: 12px
+- Scoped to semantic meaning: `success`, `danger`, `read`, `write`, `admin`
+
+### Buttons
+- Primary: white text on #3a3a5a, hover brightens
+- Secondary: muted text on transparent, border #1e1e2e
+- Danger: white text on #ff6b6b background
+- Size: 13px font, 6px 14px padding
+
+### Modals
+- Overlay: rgba(0,0,0,0.7)
+- Card: #12121a, border #1e1e2e, border-radius 16px, max-width 480px
+- Title: 18px Semibold, left-aligned
+- Close: top-right ✕ button
+
+### Drawers
+- Right-side panel, 400px wide
+- Slide in from right
+- Dark overlay behind
+- Close button top-right
+- Sections separated by section titles (uppercase, muted)
+
+### Tabs
+- Inline horizontal, wrapping allowed
+- Active: white text, bottom border
+- Inactive: muted text, no border
+- No background color on tabs
+
+### Code blocks
+- Background: rgba(0,0,0,0.3)
+- Border-radius: 8px
+- Padding: 10px 14px
+- Font: JetBrains Mono 12px
+- Copy button: right-aligned, subtle
+
+### Empty states
+- Centered text (only exception to left-align rule)
+- Muted color
+- Suggest next action
+
+## Motion
+- **Approach:** Minimal — transitions for hover states only
+- **Duration:** 150ms for hovers, 200ms for drawer slide
+- **No loading spinners** — show stale data until fresh arrives
+- **SSE live feed:** Real-time, no animation on new entries (just prepend)
+
+## Anti-Patterns (do NOT do these)
+- ❌ Center-aligned table data
+- ❌ Center-aligned headings or labels (except empty states)
+- ❌ Gradient backgrounds
+- ❌ Shadows (the dark theme IS the depth model)
+- ❌ Rounded table corners
+- ❌ Icons as navigation (use text labels)
+- ❌ Loading skeletons (show real data or nothing)
+- ❌ Confirmation toasts (action → result is immediate and visible)
+- ❌ Color for decoration (every color means something)
+
+## Decisions Log
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2026-05-01 | Dark theme only | Ops dashboard. No light mode needed. |
+| 2026-05-01 | Steve Krug lens | Zero happy talk, mindless choices, scannable tables, billboard-speed comprehension. |
+| 2026-05-01 | JetBrains Mono for data | Anything copyable or technical should be monospace. |
+| 2026-05-03 | Left-align everything | Garry preference. Centered text is a design crutch. Left-align forces hierarchy through typography weight and spacing, not position. |
+| 2026-05-03 | Incorporate GStack design DNA | Same family: Inter + JetBrains Mono, dark base, semantic-only color. Diverges on accent (GStack: amber; GBrain: none — data is the color). |
+| 2026-05-03 | Per-client config export tabs | Claude Code, ChatGPT, Claude.ai, Cursor, Perplexity, JSON. Every agent has a copy-paste setup path. |
+| 2026-05-03 | Magic link auth | Login page tells you to ask your agent. No pasting hex strings into forms. |

admin/bun.lock

@@ -0,0 +1,257 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "gbrain-admin",
+      "dependencies": {
+        "react": "^19.1.0",
+        "react-dom": "^19.1.0",
+      },
+      "devDependencies": {
+        "@types/react": "^19.1.2",
+        "@types/react-dom": "^19.1.2",
+        "@vitejs/plugin-react": "^4.4.1",
+        "typescript": "^5.8.3",
+        "vite": "^6.3.3",
+      },
+    },
+  },
+  "packages": {
+    "@babel/code-frame": ["@babel/code-frame@7.29.0", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.28.5", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw=="],
+
+    "@babel/compat-data": ["@babel/compat-data@7.29.0", "", {}, "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg=="],
+
+    "@babel/core": ["@babel/core@7.29.0", "", { "dependencies": { "@babel/code-frame": "^7.29.0", "@babel/generator": "^7.29.0", "@babel/helper-compilation-targets": "^7.28.6", "@babel/helper-module-transforms": "^7.28.6", "@babel/helpers": "^7.28.6", "@babel/parser": "^7.29.0", "@babel/template": "^7.28.6", "@babel/traverse": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/remapping": "^2.3.5", "convert-source-map": "^2.0.0", "debug": "^4.1.0", "gensync": "^1.0.0-beta.2", "json5": "^2.2.3", "semver": "^6.3.1" } }, "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA=="],
+
+    "@babel/generator": ["@babel/generator@7.29.1", "", { "dependencies": { "@babel/parser": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw=="],
+
+    "@babel/helper-compilation-targets": ["@babel/helper-compilation-targets@7.28.6", "", { "dependencies": { "@babel/compat-data": "^7.28.6", "@babel/helper-validator-option": "^7.27.1", "browserslist": "^4.24.0", "lru-cache": "^5.1.1", "semver": "^6.3.1" } }, "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA=="],
+
+    "@babel/helper-globals": ["@babel/helper-globals@7.28.0", "", {}, "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw=="],
+
+    "@babel/helper-module-imports": ["@babel/helper-module-imports@7.28.6", "", { "dependencies": { "@babel/traverse": "^7.28.6", "@babel/types": "^7.28.6" } }, "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw=="],
+
+    "@babel/helper-module-transforms": ["@babel/helper-module-transforms@7.28.6", "", { "dependencies": { "@babel/helper-module-imports": "^7.28.6", "@babel/helper-validator-identifier": "^7.28.5", "@babel/traverse": "^7.28.6" }, "peerDependencies": { "@babel/core": "^7.0.0" } }, "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA=="],
+
+    "@babel/helper-plugin-utils": ["@babel/helper-plugin-utils@7.28.6", "", {}, "sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug=="],
+
+    "@babel/helper-string-parser": ["@babel/helper-string-parser@7.27.1", "", {}, "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA=="],
+
+    "@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.28.5", "", {}, "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q=="],
+
+    "@babel/helper-validator-option": ["@babel/helper-validator-option@7.27.1", "", {}, "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg=="],
+
+    "@babel/helpers": ["@babel/helpers@7.29.2", "", { "dependencies": { "@babel/template": "^7.28.6", "@babel/types": "^7.29.0" } }, "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw=="],
+
+    "@babel/parser": ["@babel/parser@7.29.2", "", { "dependencies": { "@babel/types": "^7.29.0" }, "bin": "./bin/babel-parser.js" }, "sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA=="],
+
+    "@babel/plugin-transform-react-jsx-self": ["@babel/plugin-transform-react-jsx-self@7.27.1", "", { "dependencies": { "@babel/helper-plugin-utils": "^7.27.1" }, "peerDependencies": { "@babel/core": "^7.0.0-0" } }, "sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw=="],
+
+    "@babel/plugin-transform-react-jsx-source": ["@babel/plugin-transform-react-jsx-source@7.27.1", "", { "dependencies": { "@babel/helper-plugin-utils": "^7.27.1" }, "peerDependencies": { "@babel/core": "^7.0.0-0" } }, "sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw=="],
+
+    "@babel/template": ["@babel/template@7.28.6", "", { "dependencies": { "@babel/code-frame": "^7.28.6", "@babel/parser": "^7.28.6", "@babel/types": "^7.28.6" } }, "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ=="],
+
+    "@babel/traverse": ["@babel/traverse@7.29.0", "", { "dependencies": { "@babel/code-frame": "^7.29.0", "@babel/generator": "^7.29.0", "@babel/helper-globals": "^7.28.0", "@babel/parser": "^7.29.0", "@babel/template": "^7.28.6", "@babel/types": "^7.29.0", "debug": "^4.3.1" } }, "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA=="],
+
+    "@babel/types": ["@babel/types@7.29.0", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
+
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.25.12", "", { "os": "aix", "cpu": "ppc64" }, "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.25.12", "", { "os": "android", "cpu": "arm" }, "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.25.12", "", { "os": "android", "cpu": "arm64" }, "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.25.12", "", { "os": "android", "cpu": "x64" }, "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.25.12", "", { "os": "darwin", "cpu": "arm64" }, "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.25.12", "", { "os": "darwin", "cpu": "x64" }, "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.25.12", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.25.12", "", { "os": "freebsd", "cpu": "x64" }, "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.25.12", "", { "os": "linux", "cpu": "arm" }, "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.25.12", "", { "os": "linux", "cpu": "arm64" }, "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.25.12", "", { "os": "linux", "cpu": "ia32" }, "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.25.12", "", { "os": "linux", "cpu": "none" }, "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.25.12", "", { "os": "linux", "cpu": "none" }, "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.25.12", "", { "os": "linux", "cpu": "ppc64" }, "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.25.12", "", { "os": "linux", "cpu": "none" }, "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.25.12", "", { "os": "linux", "cpu": "s390x" }, "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.25.12", "", { "os": "linux", "cpu": "x64" }, "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw=="],
+
+    "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.25.12", "", { "os": "none", "cpu": "arm64" }, "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.25.12", "", { "os": "none", "cpu": "x64" }, "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ=="],
+
+    "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.25.12", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.25.12", "", { "os": "openbsd", "cpu": "x64" }, "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw=="],
+
+    "@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.25.12", "", { "os": "none", "cpu": "arm64" }, "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.25.12", "", { "os": "sunos", "cpu": "x64" }, "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.25.12", "", { "os": "win32", "cpu": "arm64" }, "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.25.12", "", { "os": "win32", "cpu": "ia32" }, "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.25.12", "", { "os": "win32", "cpu": "x64" }, "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA=="],
+
+    "@jridgewell/gen-mapping": ["@jridgewell/gen-mapping@0.3.13", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.0", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA=="],
+
+    "@jridgewell/remapping": ["@jridgewell/remapping@2.3.5", "", { "dependencies": { "@jridgewell/gen-mapping": "^0.3.5", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ=="],
+
+    "@jridgewell/resolve-uri": ["@jridgewell/resolve-uri@3.1.2", "", {}, "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw=="],
+
+    "@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="],
+
+    "@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
+
+    "@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-beta.27", "", {}, "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA=="],
+
+    "@rollup/rollup-android-arm-eabi": ["@rollup/rollup-android-arm-eabi@4.60.1", "", { "os": "android", "cpu": "arm" }, "sha512-d6FinEBLdIiK+1uACUttJKfgZREXrF0Qc2SmLII7W2AD8FfiZ9Wjd+rD/iRuf5s5dWrr1GgwXCvPqOuDquOowA=="],
+
+    "@rollup/rollup-android-arm64": ["@rollup/rollup-android-arm64@4.60.1", "", { "os": "android", "cpu": "arm64" }, "sha512-YjG/EwIDvvYI1YvYbHvDz/BYHtkY4ygUIXHnTdLhG+hKIQFBiosfWiACWortsKPKU/+dUwQQCKQM3qrDe8c9BA=="],
+
+    "@rollup/rollup-darwin-arm64": ["@rollup/rollup-darwin-arm64@4.60.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-mjCpF7GmkRtSJwon+Rq1N8+pI+8l7w5g9Z3vWj4T7abguC4Czwi3Yu/pFaLvA3TTeMVjnu3ctigusqWUfjZzvw=="],
+
+    "@rollup/rollup-darwin-x64": ["@rollup/rollup-darwin-x64@4.60.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-haZ7hJ1JT4e9hqkoT9R/19XW2QKqjfJVv+i5AGg57S+nLk9lQnJ1F/eZloRO3o9Scy9CM3wQ9l+dkXtcBgN5Ew=="],
+
+    "@rollup/rollup-freebsd-arm64": ["@rollup/rollup-freebsd-arm64@4.60.1", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-czw90wpQq3ZsAVBlinZjAYTKduOjTywlG7fEeWKUA7oCmpA8xdTkxZZlwNJKWqILlq0wehoZcJYfBvOyhPTQ6w=="],
+
+    "@rollup/rollup-freebsd-x64": ["@rollup/rollup-freebsd-x64@4.60.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-KVB2rqsxTHuBtfOeySEyzEOB7ltlB/ux38iu2rBQzkjbwRVlkhAGIEDiiYnO2kFOkJp+Z7pUXKyrRRFuFUKt+g=="],
+
+    "@rollup/rollup-linux-arm-gnueabihf": ["@rollup/rollup-linux-arm-gnueabihf@4.60.1", "", { "os": "linux", "cpu": "arm" }, "sha512-L+34Qqil+v5uC0zEubW7uByo78WOCIrBvci69E7sFASRl0X7b/MB6Cqd1lky/CtcSVTydWa2WZwFuWexjS5o6g=="],
+
+    "@rollup/rollup-linux-arm-musleabihf": ["@rollup/rollup-linux-arm-musleabihf@4.60.1", "", { "os": "linux", "cpu": "arm" }, "sha512-n83O8rt4v34hgFzlkb1ycniJh7IR5RCIqt6mz1VRJD6pmhRi0CXdmfnLu9dIUS6buzh60IvACM842Ffb3xd6Gg=="],
+
+    "@rollup/rollup-linux-arm64-gnu": ["@rollup/rollup-linux-arm64-gnu@4.60.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-Nql7sTeAzhTAja3QXeAI48+/+GjBJ+QmAH13snn0AJSNL50JsDqotyudHyMbO2RbJkskbMbFJfIJKWA6R1LCJQ=="],
+
+    "@rollup/rollup-linux-arm64-musl": ["@rollup/rollup-linux-arm64-musl@4.60.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-+pUymDhd0ys9GcKZPPWlFiZ67sTWV5UU6zOJat02M1+PiuSGDziyRuI/pPue3hoUwm2uGfxdL+trT6Z9rxnlMA=="],
+
+    "@rollup/rollup-linux-loong64-gnu": ["@rollup/rollup-linux-loong64-gnu@4.60.1", "", { "os": "linux", "cpu": "none" }, "sha512-VSvgvQeIcsEvY4bKDHEDWcpW4Yw7BtlKG1GUT4FzBUlEKQK0rWHYBqQt6Fm2taXS+1bXvJT6kICu5ZwqKCnvlQ=="],
+
+    "@rollup/rollup-linux-loong64-musl": ["@rollup/rollup-linux-loong64-musl@4.60.1", "", { "os": "linux", "cpu": "none" }, "sha512-4LqhUomJqwe641gsPp6xLfhqWMbQV04KtPp7/dIp0nzPxAkNY1AbwL5W0MQpcalLYk07vaW9Kp1PBhdpZYYcEw=="],
+
+    "@rollup/rollup-linux-ppc64-gnu": ["@rollup/rollup-linux-ppc64-gnu@4.60.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-tLQQ9aPvkBxOc/EUT6j3pyeMD6Hb8QF2BTBnCQWP/uu1lhc9AIrIjKnLYMEroIz/JvtGYgI9dF3AxHZNaEH0rw=="],
+
+    "@rollup/rollup-linux-ppc64-musl": ["@rollup/rollup-linux-ppc64-musl@4.60.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-RMxFhJwc9fSXP6PqmAz4cbv3kAyvD1etJFjTx4ONqFP9DkTkXsAMU4v3Vyc5BgzC+anz7nS/9tp4obsKfqkDHg=="],
+
+    "@rollup/rollup-linux-riscv64-gnu": ["@rollup/rollup-linux-riscv64-gnu@4.60.1", "", { "os": "linux", "cpu": "none" }, "sha512-QKgFl+Yc1eEk6MmOBfRHYF6lTxiiiV3/z/BRrbSiW2I7AFTXoBFvdMEyglohPj//2mZS4hDOqeB0H1ACh3sBbg=="],
+
+    "@rollup/rollup-linux-riscv64-musl": ["@rollup/rollup-linux-riscv64-musl@4.60.1", "", { "os": "linux", "cpu": "none" }, "sha512-RAjXjP/8c6ZtzatZcA1RaQr6O1TRhzC+adn8YZDnChliZHviqIjmvFwHcxi4JKPSDAt6Uhf/7vqcBzQJy0PDJg=="],
+
+    "@rollup/rollup-linux-s390x-gnu": ["@rollup/rollup-linux-s390x-gnu@4.60.1", "", { "os": "linux", "cpu": "s390x" }, "sha512-wcuocpaOlaL1COBYiA89O6yfjlp3RwKDeTIA0hM7OpmhR1Bjo9j31G1uQVpDlTvwxGn2nQs65fBFL5UFd76FcQ=="],
+
+    "@rollup/rollup-linux-x64-gnu": ["@rollup/rollup-linux-x64-gnu@4.60.1", "", { "os": "linux", "cpu": "x64" }, "sha512-77PpsFQUCOiZR9+LQEFg9GClyfkNXj1MP6wRnzYs0EeWbPcHs02AXu4xuUbM1zhwn3wqaizle3AEYg5aeoohhg=="],
+
+    "@rollup/rollup-linux-x64-musl": ["@rollup/rollup-linux-x64-musl@4.60.1", "", { "os": "linux", "cpu": "x64" }, "sha512-5cIATbk5vynAjqqmyBjlciMJl1+R/CwX9oLk/EyiFXDWd95KpHdrOJT//rnUl4cUcskrd0jCCw3wpZnhIHdD9w=="],
+
+    "@rollup/rollup-openbsd-x64": ["@rollup/rollup-openbsd-x64@4.60.1", "", { "os": "openbsd", "cpu": "x64" }, "sha512-cl0w09WsCi17mcmWqqglez9Gk8isgeWvoUZ3WiJFYSR3zjBQc2J5/ihSjpl+VLjPqjQ/1hJRcqBfLjssREQILw=="],
+
+    "@rollup/rollup-openharmony-arm64": ["@rollup/rollup-openharmony-arm64@4.60.1", "", { "os": "none", "cpu": "arm64" }, "sha512-4Cv23ZrONRbNtbZa37mLSueXUCtN7MXccChtKpUnQNgF010rjrjfHx3QxkS2PI7LqGT5xXyYs1a7LbzAwT0iCA=="],
+
+    "@rollup/rollup-win32-arm64-msvc": ["@rollup/rollup-win32-arm64-msvc@4.60.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-i1okWYkA4FJICtr7KpYzFpRTHgy5jdDbZiWfvny21iIKky5YExiDXP+zbXzm3dUcFpkEeYNHgQ5fuG236JPq0g=="],
+
+    "@rollup/rollup-win32-ia32-msvc": ["@rollup/rollup-win32-ia32-msvc@4.60.1", "", { "os": "win32", "cpu": "ia32" }, "sha512-u09m3CuwLzShA0EYKMNiFgcjjzwqtUMLmuCJLeZWjjOYA3IT2Di09KaxGBTP9xVztWyIWjVdsB2E9goMjZvTQg=="],
+
+    "@rollup/rollup-win32-x64-gnu": ["@rollup/rollup-win32-x64-gnu@4.60.1", "", { "os": "win32", "cpu": "x64" }, "sha512-k+600V9Zl1CM7eZxJgMyTUzmrmhB/0XZnF4pRypKAlAgxmedUA+1v9R+XOFv56W4SlHEzfeMtzujLJD22Uz5zg=="],
+
+    "@rollup/rollup-win32-x64-msvc": ["@rollup/rollup-win32-x64-msvc@4.60.1", "", { "os": "win32", "cpu": "x64" }, "sha512-lWMnixq/QzxyhTV6NjQJ4SFo1J6PvOX8vUx5Wb4bBPsEb+8xZ89Bz6kOXpfXj9ak9AHTQVQzlgzBEc1SyM27xQ=="],
+
+    "@types/babel__core": ["@types/babel__core@7.20.5", "", { "dependencies": { "@babel/parser": "^7.20.7", "@babel/types": "^7.20.7", "@types/babel__generator": "*", "@types/babel__template": "*", "@types/babel__traverse": "*" } }, "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA=="],
+
+    "@types/babel__generator": ["@types/babel__generator@7.27.0", "", { "dependencies": { "@babel/types": "^7.0.0" } }, "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg=="],
+
+    "@types/babel__template": ["@types/babel__template@7.4.4", "", { "dependencies": { "@babel/parser": "^7.1.0", "@babel/types": "^7.0.0" } }, "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A=="],
+
+    "@types/babel__traverse": ["@types/babel__traverse@7.28.0", "", { "dependencies": { "@babel/types": "^7.28.2" } }, "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q=="],
+
+    "@types/estree": ["@types/estree@1.0.8", "", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
+
+    "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
+
+    "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
+
+    "@vitejs/plugin-react": ["@vitejs/plugin-react@4.7.0", "", { "dependencies": { "@babel/core": "^7.28.0", "@babel/plugin-transform-react-jsx-self": "^7.27.1", "@babel/plugin-transform-react-jsx-source": "^7.27.1", "@rolldown/pluginutils": "1.0.0-beta.27", "@types/babel__core": "^7.20.5", "react-refresh": "^0.17.0" }, "peerDependencies": { "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" } }, "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA=="],
+
+    "baseline-browser-mapping": ["baseline-browser-mapping@2.10.18", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-VSnGQAOLtP5mib/DPyg2/t+Tlv65NTBz83BJBJvmLVHHuKJVaDOBvJJykiT5TR++em5nfAySPccDZDa4oSrn8A=="],
+
+    "browserslist": ["browserslist@4.28.2", "", { "dependencies": { "baseline-browser-mapping": "^2.10.12", "caniuse-lite": "^1.0.30001782", "electron-to-chromium": "^1.5.328", "node-releases": "^2.0.36", "update-browserslist-db": "^1.2.3" }, "bin": { "browserslist": "cli.js" } }, "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg=="],
+
+    "caniuse-lite": ["caniuse-lite@1.0.30001788", "", {}, "sha512-6q8HFp+lOQtcf7wBK+uEenxymVWkGKkjFpCvw5W25cmMwEDU45p1xQFBQv8JDlMMry7eNxyBaR+qxgmTUZkIRQ=="],
+
+    "convert-source-map": ["convert-source-map@2.0.0", "", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],
+
+    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "electron-to-chromium": ["electron-to-chromium@1.5.336", "", {}, "sha512-AbH9q9J455r/nLmdNZes0G0ZKcRX73FicwowalLs6ijwOmCJSRRrLX63lcAlzy9ux3dWK1w1+1nsBJEWN11hcQ=="],
+
+    "esbuild": ["esbuild@0.25.12", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.25.12", "@esbuild/android-arm": "0.25.12", "@esbuild/android-arm64": "0.25.12", "@esbuild/android-x64": "0.25.12", "@esbuild/darwin-arm64": "0.25.12", "@esbuild/darwin-x64": "0.25.12", "@esbuild/freebsd-arm64": "0.25.12", "@esbuild/freebsd-x64": "0.25.12", "@esbuild/linux-arm": "0.25.12", "@esbuild/linux-arm64": "0.25.12", "@esbuild/linux-ia32": "0.25.12", "@esbuild/linux-loong64": "0.25.12", "@esbuild/linux-mips64el": "0.25.12", "@esbuild/linux-ppc64": "0.25.12", "@esbuild/linux-riscv64": "0.25.12", "@esbuild/linux-s390x": "0.25.12", "@esbuild/linux-x64": "0.25.12", "@esbuild/netbsd-arm64": "0.25.12", "@esbuild/netbsd-x64": "0.25.12", "@esbuild/openbsd-arm64": "0.25.12", "@esbuild/openbsd-x64": "0.25.12", "@esbuild/openharmony-arm64": "0.25.12", "@esbuild/sunos-x64": "0.25.12", "@esbuild/win32-arm64": "0.25.12", "@esbuild/win32-ia32": "0.25.12", "@esbuild/win32-x64": "0.25.12" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg=="],
+
+    "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
+
+    "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
+
+    "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
+
+    "gensync": ["gensync@1.0.0-beta.2", "", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
+
+    "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
+
+    "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
+
+    "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
+
+    "lru-cache": ["lru-cache@5.1.1", "", { "dependencies": { "yallist": "^3.0.2" } }, "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
+
+    "node-releases": ["node-releases@2.0.37", "", {}, "sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg=="],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
+
+    "picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
+
+    "postcss": ["postcss@8.5.9", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-7a70Nsot+EMX9fFU3064K/kdHWZqGVY+BADLyXc8Dfv+mTLLVl6JzJpPaCZ2kQL9gIJvKXSLMHhqdRRjwQeFtw=="],
+
+    "react": ["react@19.2.5", "", {}, "sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA=="],
+
+    "react-dom": ["react-dom@19.2.5", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.5" } }, "sha512-J5bAZz+DXMMwW/wV3xzKke59Af6CHY7G4uYLN1OvBcKEsWOs4pQExj86BBKamxl/Ik5bx9whOrvBlSDfWzgSag=="],
+
+    "react-refresh": ["react-refresh@0.17.0", "", {}, "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ=="],
+
+    "rollup": ["rollup@4.60.1", "", { "dependencies": { "@types/estree": "1.0.8" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.60.1", "@rollup/rollup-android-arm64": "4.60.1", "@rollup/rollup-darwin-arm64": "4.60.1", "@rollup/rollup-darwin-x64": "4.60.1", "@rollup/rollup-freebsd-arm64": "4.60.1", "@rollup/rollup-freebsd-x64": "4.60.1", "@rollup/rollup-linux-arm-gnueabihf": "4.60.1", "@rollup/rollup-linux-arm-musleabihf": "4.60.1", "@rollup/rollup-linux-arm64-gnu": "4.60.1", "@rollup/rollup-linux-arm64-musl": "4.60.1", "@rollup/rollup-linux-loong64-gnu": "4.60.1", "@rollup/rollup-linux-loong64-musl": "4.60.1", "@rollup/rollup-linux-ppc64-gnu": "4.60.1", "@rollup/rollup-linux-ppc64-musl": "4.60.1", "@rollup/rollup-linux-riscv64-gnu": "4.60.1", "@rollup/rollup-linux-riscv64-musl": "4.60.1", "@rollup/rollup-linux-s390x-gnu": "4.60.1", "@rollup/rollup-linux-x64-gnu": "4.60.1", "@rollup/rollup-linux-x64-musl": "4.60.1", "@rollup/rollup-openbsd-x64": "4.60.1", "@rollup/rollup-openharmony-arm64": "4.60.1", "@rollup/rollup-win32-arm64-msvc": "4.60.1", "@rollup/rollup-win32-ia32-msvc": "4.60.1", "@rollup/rollup-win32-x64-gnu": "4.60.1", "@rollup/rollup-win32-x64-msvc": "4.60.1", "fsevents": "~2.3.2" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-VmtB2rFU/GroZ4oL8+ZqXgSA38O6GR8KSIvWmEFv63pQ0G6KaBH9s07PO8XTXP4vI+3UJUEypOfjkGfmSBBR0w=="],
+
+    "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
+
+    "semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
+
+    "source-map-js": ["source-map-js@1.2.1", "", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
+
+    "tinyglobby": ["tinyglobby@0.2.16", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "update-browserslist-db": ["update-browserslist-db@1.2.3", "", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": { "update-browserslist-db": "cli.js" } }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
+
+    "vite": ["vite@6.4.2", "", { "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.4.4", "picomatch": "^4.0.2", "postcss": "^8.5.3", "rollup": "^4.34.9", "tinyglobby": "^0.2.13" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0", "jiti": ">=1.21.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "jiti", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ=="],
+
+    "yallist": ["yallist@3.1.1", "", {}, "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="],
+  }
+}

admin/dist/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>GBrain Admin</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  <script type="module" crossorigin src="/admin/assets/index-CDv6_ml5.js"></script>
+  <link rel="stylesheet" crossorigin href="/admin/assets/index-BOifXQpQ.css">
+</head>
+<body>
+  <div id="root"></div>
+</body>
+</html>

admin/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>GBrain Admin</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>

admin/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "gbrain-admin",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@vitejs/plugin-react": "^4.4.1",
+    "vite": "^6.3.3",
+    "typescript": "^5.8.3"
+  }
+}

admin/src/App.tsx

@@ -0,0 +1,84 @@
+import React, { useState, useEffect } from 'react';
+import { LoginPage } from './pages/Login';
+import { DashboardPage } from './pages/Dashboard';
+import { AgentsPage } from './pages/Agents';
+import { RequestLogPage } from './pages/RequestLog';
+import { api } from './api';
+
+type Page = 'login' | 'dashboard' | 'agents' | 'log';
+
+function getPage(): Page {
+  const hash = window.location.hash.replace('#', '') || 'dashboard';
+  if (['login', 'dashboard', 'agents', 'log'].includes(hash)) return hash as Page;
+  return 'dashboard';
+}
+
+export function App() {
+  const [page, setPage] = useState<Page>(getPage);
+
+  useEffect(() => {
+    const onHash = () => setPage(getPage());
+    window.addEventListener('hashchange', onHash);
+    return () => window.removeEventListener('hashchange', onHash);
+  }, []);
+
+  const navigate = (p: Page) => {
+    window.location.hash = p;
+    setPage(p);
+  };
+
+  if (page === 'login') {
+    return <LoginPage onLogin={() => navigate('dashboard')} />;
+  }
+
+  const handleSignOutEverywhere = async () => {
+    if (!confirm('Sign out every active admin session, including other browsers and tabs? Each one will need to re-authenticate via a fresh magic link.')) {
+      return;
+    }
+    try {
+      await api.signOutEverywhere();
+    } catch {
+      // Even if the call fails, push to login — cookie is likely already invalid.
+    }
+    navigate('login');
+  };
+
+  return (
+    <div className="app">
+      <nav className="sidebar">
+        <div className="sidebar-logo">GBrain</div>
+        <div className="sidebar-nav">
+          <a className={`nav-item ${page === 'dashboard' ? 'active' : ''}`}
+             onClick={() => navigate('dashboard')}>Dashboard</a>
+          <a className={`nav-item ${page === 'agents' ? 'active' : ''}`}
+             onClick={() => navigate('agents')}>Agents</a>
+          <a className={`nav-item ${page === 'log' ? 'active' : ''}`}
+             onClick={() => navigate('log')}>Request Log</a>
+        </div>
+        <div style={{ marginTop: 'auto', padding: '16px 12px', borderTop: '1px solid var(--border)' }}>
+          <button
+            onClick={handleSignOutEverywhere}
+            style={{
+              background: 'transparent',
+              border: '1px solid var(--border)',
+              color: 'var(--text-secondary)',
+              padding: '6px 10px',
+              borderRadius: 6,
+              fontSize: 12,
+              cursor: 'pointer',
+              width: '100%',
+            }}
+            title="Revoke every active admin session — every browser, every tab"
+          >
+            Sign out everywhere
+          </button>
+        </div>
+      </nav>
+      <main className="main">
+        {page === 'dashboard' && <DashboardPage />}
+        {page === 'agents' && <AgentsPage />}
+        {page === 'log' && <RequestLogPage />}
+      </main>
+    </div>
+  );
+}

admin/src/api.ts

@@ -0,0 +1,37 @@
+const BASE = '';
+
+// v0.26.3 trust model (D11 + D12): the admin UI does NOT cache the
+// bootstrap token in browser JS state. On 401, redirect to login —
+// no auto-reauth via saved token, no localStorage/sessionStorage read.
+// The HttpOnly cookie set by /admin/login is the only session credential.
+async function apiFetch(path: string, options?: RequestInit) {
+  const res = await fetch(`${BASE}${path}`, {
+    ...options,
+    credentials: 'same-origin',
+    headers: { 'Content-Type': 'application/json', ...options?.headers },
+  });
+  if (res.status === 401) {
+    // No token cache to retry from. Redirect to login.
+    window.location.hash = '#login';
+    throw new Error('Unauthorized');
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || `HTTP ${res.status}`);
+  }
+  return res.json();
+}
+
+export const api = {
+  login: (token: string) => apiFetch('/admin/login', { method: 'POST', body: JSON.stringify({ token }) }),
+  signOutEverywhere: () => apiFetch('/admin/api/sign-out-everywhere', { method: 'POST' }),
+  stats: () => apiFetch('/admin/api/stats'),
+  health: () => apiFetch('/admin/api/health-indicators'),
+  agents: () => apiFetch('/admin/api/agents'),
+  requests: (page = 1, qs = '') => apiFetch(`/admin/api/requests?page=${page}${qs}`),
+  apiKeys: () => apiFetch('/admin/api/api-keys'),
+  createApiKey: (name: string) => apiFetch('/admin/api/api-keys', { method: 'POST', body: JSON.stringify({ name }) }),
+  revokeApiKey: (name: string) => apiFetch('/admin/api/api-keys/revoke', { method: 'POST', body: JSON.stringify({ name }) }),
+  updateClientTtl: (clientId: string, tokenTtl: number | null) => apiFetch('/admin/api/update-client-ttl', { method: 'POST', body: JSON.stringify({ clientId, tokenTtl }) }),
+  revokeClient: (clientId: string) => apiFetch('/admin/api/revoke-client', { method: 'POST', body: JSON.stringify({ clientId }) }),
+};

admin/src/index.css

@@ -0,0 +1,356 @@
+:root {
+  --bg-primary: #0a0a0f;
+  --bg-secondary: #14141f;
+  --bg-tertiary: #1e1e2e;
+  --text-primary: #e0e0e0;
+  --text-secondary: #888;
+  --text-muted: #555;
+  --accent: #3b82f6;
+  --success: #22c55e;
+  --warning: #f59e0b;
+  --error: #ef4444;
+  --font-mono: 'JetBrains Mono', monospace;
+  --font-sans: 'Inter', system-ui, sans-serif;
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+body {
+  font-family: var(--font-sans);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+/* Layout */
+.app { display: flex; min-height: 100vh; }
+
+.sidebar {
+  width: 200px;
+  background: var(--bg-secondary);
+  border-right: 1px solid #1e1e2e;
+  padding: 16px 0;
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.sidebar-logo {
+  font-size: 18px;
+  font-weight: 600;
+  padding: 0 16px 24px;
+  color: var(--text-primary);
+}
+
+.sidebar-nav { display: flex; flex-direction: column; gap: 2px; }
+
+.nav-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 16px;
+  color: var(--text-secondary);
+  text-decoration: none;
+  font-size: 13px;
+  cursor: pointer;
+  border-left: 3px solid transparent;
+  transition: all 0.15s;
+}
+
+.nav-item:hover { background: var(--bg-tertiary); color: var(--text-primary); }
+.nav-item.active {
+  border-left-color: var(--accent);
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.main { flex: 1; padding: 24px 32px; overflow-y: auto; }
+
+.page-title {
+  font-size: 24px;
+  font-weight: 600;
+  margin-bottom: 24px;
+}
+
+/* Metrics bar */
+.metrics { display: flex; gap: 16px; margin-bottom: 24px; }
+.metric {
+  background: var(--bg-secondary);
+  padding: 16px 20px;
+  border-radius: 6px;
+  min-width: 140px;
+}
+.metric-value {
+  font-family: var(--font-mono);
+  font-size: 28px;
+  font-weight: 500;
+}
+.metric-label { font-size: 12px; color: var(--text-secondary); margin-top: 4px; }
+
+/* Tables */
+table { width: 100%; border-collapse: collapse; }
+th {
+  text-align: left;
+  font-size: 11px;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  padding: 8px 12px;
+  font-weight: 500;
+  letter-spacing: 0.5px;
+}
+td {
+  padding: 10px 12px;
+  font-size: 13px;
+  border-top: 1px solid #1a1a2a;
+}
+tr:hover td { background: var(--bg-tertiary); }
+
+/* Badges */
+.badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 10px;
+  font-size: 11px;
+  font-weight: 500;
+}
+.badge-read { background: rgba(59,130,246,0.15); color: var(--accent); }
+.badge-write { background: rgba(245,158,11,0.15); color: var(--warning); }
+.badge-admin { background: rgba(239,68,68,0.15); color: var(--error); }
+.badge-success { background: rgba(34,197,94,0.15); color: var(--success); }
+.badge-error { background: rgba(239,68,68,0.15); color: var(--error); }
+
+/* Status dots */
+.status-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  margin-right: 6px;
+}
+.status-active { background: var(--success); }
+.status-warning { background: var(--warning); }
+.status-inactive { background: var(--text-muted); }
+
+/* Buttons */
+.btn {
+  padding: 8px 16px;
+  border-radius: 6px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  border: none;
+  transition: all 0.15s;
+}
+.btn-primary { background: var(--accent); color: white; }
+.btn-primary:hover { background: #2563eb; }
+.btn-secondary { background: transparent; color: var(--text-secondary); border: 1px solid #333; }
+.btn-secondary:hover { border-color: var(--text-secondary); color: var(--text-primary); }
+.btn-danger { background: transparent; color: var(--error); border: 1px solid var(--error); }
+.btn-danger:hover { background: rgba(239,68,68,0.1); }
+
+/* Forms */
+input, select {
+  background: var(--bg-primary);
+  border: 1px solid #333;
+  color: var(--text-primary);
+  padding: 8px 12px;
+  border-radius: 6px;
+  font-size: 13px;
+  font-family: var(--font-sans);
+  width: 100%;
+}
+input:focus, select:focus {
+  outline: none;
+  border-color: var(--accent);
+  box-shadow: 0 0 0 2px rgba(59,130,246,0.2);
+}
+input::placeholder { color: var(--text-muted); }
+label { display: block; font-size: 13px; font-weight: 500; margin-bottom: 6px; }
+
+/* Modal */
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0,0,0,0.7);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 100;
+}
+.modal {
+  background: var(--bg-secondary);
+  border-radius: 8px;
+  padding: 24px;
+  min-width: 420px;
+  max-width: 520px;
+}
+.modal-title { font-size: 18px; font-weight: 600; margin-bottom: 20px; }
+
+/* Drawer */
+.drawer-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0,0,0,0.5);
+  z-index: 90;
+}
+.drawer {
+  position: fixed;
+  right: 0;
+  top: 0;
+  bottom: 0;
+  width: 420px;
+  background: var(--bg-secondary);
+  border-left: 1px solid var(--accent);
+  padding: 24px;
+  z-index: 91;
+  overflow-y: auto;
+}
+.drawer-close {
+  position: absolute;
+  top: 16px;
+  right: 16px;
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  font-size: 18px;
+  cursor: pointer;
+}
+
+/* Section headers */
+.section-title {
+  font-size: 11px;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  letter-spacing: 0.5px;
+  margin: 20px 0 12px;
+  font-weight: 500;
+}
+
+/* Health panel */
+.health-panel {
+  background: var(--bg-secondary);
+  border-radius: 6px;
+  padding: 16px;
+}
+.health-row {
+  display: flex;
+  justify-content: space-between;
+  padding: 6px 0;
+  font-size: 13px;
+}
+
+/* Code block */
+.code-block {
+  background: var(--bg-primary);
+  border-radius: 6px;
+  padding: 12px;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  overflow-x: auto;
+  position: relative;
+}
+.code-block .copy-btn {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  background: var(--accent);
+  color: white;
+  border: none;
+  padding: 4px 10px;
+  border-radius: 4px;
+  font-size: 11px;
+  cursor: pointer;
+}
+
+/* Activity feed */
+.feed { max-height: 400px; overflow-y: auto; }
+.feed-empty {
+  color: var(--text-muted);
+  text-align: center;
+  padding: 32px;
+  font-size: 13px;
+}
+
+/* Sparkline */
+.sparkline { display: inline-block; vertical-align: middle; }
+
+/* Filter bar */
+.filter-bar { display: flex; gap: 12px; margin-bottom: 16px; align-items: center; }
+.filter-bar select { width: auto; min-width: 140px; }
+
+/* Pagination */
+.pagination {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px 0;
+  font-size: 13px;
+  color: var(--text-secondary);
+}
+.pagination button {
+  background: var(--bg-secondary);
+  border: 1px solid #333;
+  color: var(--text-primary);
+  padding: 6px 12px;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 12px;
+}
+.pagination button:disabled { opacity: 0.3; cursor: default; }
+
+/* Warning bar */
+.warning-bar {
+  background: rgba(245,158,11,0.15);
+  border: 1px solid var(--warning);
+  color: var(--warning);
+  padding: 10px 16px;
+  border-radius: 6px;
+  font-size: 13px;
+  margin: 12px 0;
+}
+
+/* Checkbox */
+.checkbox-group { display: flex; gap: 16px; flex-wrap: wrap; }
+.checkbox-label {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+  cursor: pointer;
+}
+
+/* Tabs */
+.tabs { display: flex; gap: 0; margin-bottom: 12px; }
+.tab {
+  padding: 6px 12px;
+  font-size: 13px;
+  color: var(--text-secondary);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+}
+.tab.active { color: var(--accent); border-bottom-color: var(--accent); }
+
+/* Login page */
+.login-page {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  background: var(--bg-primary);
+}
+.login-box { text-align: left; width: 340px; }
+.login-logo { font-size: 32px; font-weight: 600; margin-bottom: 32px; }
+.login-hint { color: var(--text-muted); font-size: 12px; margin-top: 12px; }
+.login-error { color: var(--error); font-size: 13px; margin-top: 8px; }
+
+/* Monospace data */
+.mono { font-family: var(--font-mono); font-size: 12px; }
+
+/* Responsive */
+@media (max-width: 768px) {
+  .sidebar { display: none; }
+  .main { padding: 16px; }
+  .metrics { flex-wrap: wrap; }
+  .drawer { width: 100%; }
+}

admin/src/lib/scope-constants.ts

@@ -0,0 +1,22 @@
+/**
+ * Admin SPA scope constants — HAND-MAINTAINED MIRROR of src/core/scope.ts.
+ *
+ * The admin tsconfig.json scopes `include: ['src']` to admin/src/, so we
+ * cannot directly import from ../../src/core/scope.ts without breaking the
+ * SPA's compile boundary. Instead, this file is a hand-maintained duplicate;
+ * scripts/check-admin-scope-drift.sh fails the build if the two lists drift.
+ *
+ * If you change ALLOWED_SCOPES in src/core/scope.ts, update this file too,
+ * or `bun run verify` will reject the change.
+ */
+
+export type Scope = 'read' | 'write' | 'admin' | 'sources_admin' | 'users_admin';
+
+// MIRROR OF src/core/scope.ts ALLOWED_SCOPES_LIST — keep alphabetically sorted.
+export const ALLOWED_SCOPES_LIST: ReadonlyArray<Scope> = [
+  'admin',
+  'read',
+  'sources_admin',
+  'users_admin',
+  'write',
+];

admin/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { App } from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

admin/src/pages/Agents.tsx

@@ -0,0 +1,633 @@
+import React, { useState, useEffect } from 'react';
+import { api } from '../api';
+import { ALLOWED_SCOPES_LIST, type Scope } from '../lib/scope-constants';
+
+function timeAgo(date: Date): string {
+  const s = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+interface Agent {
+  id: string;
+  name: string;
+  auth_type: 'oauth' | 'api_key';
+  client_id?: string;  // compat
+  client_name?: string; // compat
+  grant_types: string[];
+  scope: string;
+  created_at: string;
+  last_used_at: string | null;
+  total_requests: number;
+  requests_today: number;
+  token_ttl: number | null;
+  status: 'active' | 'revoked';
+}
+
+interface ApiKey {
+  id: string;
+  name: string;
+  created_at: string;
+  last_used_at: string | null;
+  status: 'active' | 'revoked';
+}
+
+export function AgentsPage() {
+  const [agents, setAgents] = useState<Agent[]>([]);
+  const [hideRevoked, setHideRevoked] = useState(true);
+  const [showRegister, setShowRegister] = useState(false);
+  const [showCredentials, setShowCredentials] = useState<{ clientId: string; clientSecret: string; name: string } | null>(null);
+  const [showApiKeyCreate, setShowApiKeyCreate] = useState(false);
+  const [showApiKeyToken, setShowApiKeyToken] = useState<{ name: string; token: string } | null>(null);
+  const [selectedAgent, setSelectedAgent] = useState<Agent | null>(null);
+
+  useEffect(() => { loadAgents(); }, []);
+
+  const loadAgents = () => { api.agents().then(setAgents).catch(() => {}); };
+
+  return (
+    <>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 24 }}>
+        <h1 className="page-title" style={{ marginBottom: 0 }}>Agents</h1>
+        <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+          <label style={{ fontSize: 13, color: 'var(--text-secondary)', display: 'flex', alignItems: 'center', gap: 6, cursor: 'pointer' }}>
+            <input type="checkbox" checked={hideRevoked} onChange={e => setHideRevoked(e.target.checked)} /> Hide revoked
+          </label>
+          <button className="btn btn-secondary" onClick={() => setShowApiKeyCreate(true)}>+ API Key</button>
+          <button className="btn btn-primary" onClick={() => setShowRegister(true)}>+ OAuth Client</button>
+        </div>
+      </div>
+
+      {(() => {
+        // Filter once and reuse, so the empty-state guard sees the same
+        // rows the table renders. Pre-fix: agents.length === 0 used the
+        // unfiltered array, so an all-revoked dataset with hideRevoked=on
+        // showed a header-only table with no placeholder.
+        const visibleAgents = agents.filter(a => !hideRevoked || a.status !== 'revoked');
+        if (agents.length === 0) {
+          return (
+            <div style={{ textAlign: 'center', padding: 48, color: 'var(--text-muted)' }}>
+              No agents registered. Register your first agent to get started.
+            </div>
+          );
+        }
+        if (visibleAgents.length === 0) {
+          return (
+            <div style={{ textAlign: 'center', padding: 48, color: 'var(--text-muted)' }}>
+              All agents are revoked. Uncheck "Hide revoked" to view them.
+            </div>
+          );
+        }
+        return (
+        <>
+          <table>
+            <thead>
+              <tr>
+                <th>Name</th>
+                <th>Type</th>
+                <th>Scopes</th>
+                <th>Status</th>
+                <th>Requests</th>
+                <th>Last Used</th>
+              </tr>
+            </thead>
+            <tbody>
+              {visibleAgents.map(a => (
+                <tr key={a.id} onClick={() => setSelectedAgent(a)}
+                    style={{ cursor: 'pointer' }}>
+                  <td style={{ fontWeight: 500 }}>{a.name || a.client_name}</td>
+                  <td>
+                    <span className={`badge ${a.auth_type === 'oauth' ? 'badge-read' : 'badge-write'}`} style={{ fontSize: 11 }}>
+                      {a.auth_type === 'oauth' ? 'OAuth' : 'API Key'}
+                    </span>
+                  </td>
+                  <td>
+                    {(a.scope || '').split(' ').filter(Boolean).map(s => (
+                      <span key={s} className={`badge badge-${s}`} style={{ marginRight: 4 }}>{s}</span>
+                    ))}
+                  </td>
+                  <td>
+                    <span className={`badge ${a.status === 'active' ? 'badge-success' : 'badge-danger'}`}>{a.status}</span>
+                  </td>
+                  <td>
+                    <span style={{ fontWeight: 500 }}>{a.requests_today || 0}</span>
+                    <span style={{ color: 'var(--text-muted)', fontSize: 12 }}> / {a.total_requests || 0}</span>
+                  </td>
+                  <td style={{ color: 'var(--text-secondary)' }}>
+                    {a.last_used_at ? timeAgo(new Date(a.last_used_at)) : 'Never'}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+          <div style={{ color: 'var(--text-muted)', fontSize: 13, marginTop: 12 }}>
+            {agents.filter(a => a.status === 'active').length} active / {agents.length} total
+          </div>
+        </>
+        );
+      })()}
+
+      {showRegister && (
+        <RegisterModal
+          onClose={() => setShowRegister(false)}
+          onRegistered={(creds) => { setShowRegister(false); setShowCredentials(creds); loadAgents(); }}
+        />
+      )}
+
+      {showCredentials && (
+        <CredentialsModal
+          credentials={showCredentials}
+          onClose={() => setShowCredentials(null)}
+        />
+      )}
+
+      {selectedAgent && (
+        <AgentDrawer agent={selectedAgent} onClose={() => setSelectedAgent(null)} onRevoked={loadAgents} />
+      )}
+
+      {showApiKeyCreate && (
+        <ApiKeyCreateModal
+          onClose={() => setShowApiKeyCreate(false)}
+          onCreated={(result) => { setShowApiKeyCreate(false); setShowApiKeyToken(result); loadAgents(); }}
+        />
+      )}
+
+      {showApiKeyToken && (
+        <ApiKeyTokenModal token={showApiKeyToken} onClose={() => setShowApiKeyToken(null)} />
+      )}
+    </>
+  );
+}
+
+function ApiKeyCreateModal({ onClose, onCreated }: {
+  onClose: () => void;
+  onCreated: (result: { name: string; token: string }) => void;
+}) {
+  const [name, setName] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!name.trim()) { setError('Name required'); return; }
+    setLoading(true);
+    try {
+      const data = await api.createApiKey(name.trim());
+      onCreated({ name: data.name, token: data.token });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed');
+    } finally { setLoading(false); }
+  };
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <form className="modal" onClick={e => e.stopPropagation()} onSubmit={handleSubmit}>
+        <div className="modal-title">Create API Key</div>
+        <p style={{ color: 'var(--text-secondary)', fontSize: 13, marginBottom: 16 }}>
+          API keys use simple bearer token auth. They grant full read+write+admin access.
+          For scoped access, use OAuth clients instead.
+        </p>
+        <div style={{ marginBottom: 16 }}>
+          <label>Key Name</label>
+          <input placeholder="e.g. claude-code-local" value={name} onChange={e => setName(e.target.value)} autoFocus />
+        </div>
+        {error && <div style={{ color: 'var(--error)', fontSize: 13, marginBottom: 12 }}>{error}</div>}
+        <div style={{ display: 'flex', gap: 12, justifyContent: 'flex-end' }}>
+          <button type="button" className="btn btn-secondary" onClick={onClose}>Cancel</button>
+          <button type="submit" className="btn btn-primary" disabled={loading}>
+            {loading ? 'Creating...' : 'Create Key'}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+
+function ApiKeyTokenModal({ token, onClose }: {
+  token: { name: string; token: string };
+  onClose: () => void;
+}) {
+  const copy = (text: string) => navigator.clipboard.writeText(text);
+
+  return (
+    <div className="modal-overlay">
+      <div className="modal" style={{ maxWidth: 560 }}>
+        <div style={{ textAlign: 'center', marginBottom: 16 }}>
+          <div style={{ fontSize: 36, color: 'var(--success)', marginBottom: 8 }}>&#10003;</div>
+          <div style={{ fontSize: 20, fontWeight: 600 }}>API Key Created</div>
+        </div>
+        <div style={{ marginBottom: 12 }}>
+          <label style={{ fontSize: 12 }}>Name</label>
+          <div className="code-block"><span>{token.name}</span></div>
+        </div>
+        <div style={{ marginBottom: 12 }}>
+          <label style={{ fontSize: 12 }}>Bearer Token</label>
+          <div className="code-block">
+            <span>{token.token}</span>
+            <button className="copy-btn" onClick={() => copy(token.token)}>Copy</button>
+          </div>
+        </div>
+        <div style={{ marginBottom: 12 }}>
+          <label style={{ fontSize: 12 }}>Usage</label>
+          <div className="code-block">
+            <pre style={{ whiteSpace: 'pre-wrap', margin: 0, fontSize: 12 }}>{`Authorization: Bearer ${token.token}`}</pre>
+            <button className="copy-btn" onClick={() => copy(`Authorization: Bearer ${token.token}`)}>Copy</button>
+          </div>
+        </div>
+        <div className="warning-bar">Save this token now. It will not be shown again.</div>
+        <div style={{ display: 'flex', gap: 12, justifyContent: 'flex-end', marginTop: 20 }}>
+          <button className="btn btn-primary" onClick={onClose}>Done</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function RegisterModal({ onClose, onRegistered }: {
+  onClose: () => void;
+  onRegistered: (creds: { clientId: string; clientSecret: string; name: string }) => void;
+}) {
+  const [name, setName] = useState('');
+  // v0.28: scope set sourced from admin/src/lib/scope-constants.ts (mirror
+  // of src/core/scope.ts). CI drift check at scripts/check-admin-scope-drift.sh
+  // fails the build if these diverge.
+  const [scopes, setScopes] = useState<Record<Scope, boolean>>(() =>
+    Object.fromEntries(ALLOWED_SCOPES_LIST.map(s => [s, s === 'read'])) as Record<Scope, boolean>,
+  );
+  const [ttl, setTtl] = useState('86400'); // 24h default
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  const ttlOptions = [
+    { label: '1 hour', value: '3600' },
+    { label: '24 hours', value: '86400' },
+    { label: '7 days', value: '604800' },
+    { label: '30 days', value: '2592000' },
+    { label: '1 year', value: '31536000' },
+    { label: 'No expiry', value: '0' },
+  ];
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!name.trim()) { setError('Name required'); return; }
+    setLoading(true);
+    setError('');
+    try {
+      // Use the CLI registration endpoint (POST to admin API)
+      const selectedScopes = Object.entries(scopes).filter(([, v]) => v).map(([k]) => k).join(' ');
+      const res = await fetch('/admin/api/register-client', {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: name.trim(), scopes: selectedScopes, tokenTtl: ttl === '0' ? 315360000 : Number(ttl) }),
+      });
+      if (!res.ok) throw new Error('Registration failed');
+      const data = await res.json();
+      onRegistered({ clientId: data.clientId, clientSecret: data.clientSecret, name: name.trim() });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Registration failed');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <form className="modal" onClick={e => e.stopPropagation()} onSubmit={handleSubmit}>
+        <div className="modal-title">Register Agent</div>
+        <div style={{ marginBottom: 16 }}>
+          <label>Agent Name</label>
+          <input placeholder="e.g. perplexity-production" value={name} onChange={e => setName(e.target.value)} autoFocus />
+        </div>
+        <div style={{ marginBottom: 16 }}>
+          <label>Scopes</label>
+          <div className="checkbox-group">
+            {ALLOWED_SCOPES_LIST.map(s => (
+              <label key={s} className="checkbox-label">
+                <input type="checkbox" checked={scopes[s]} onChange={e => setScopes(p => ({ ...p, [s]: e.target.checked }))} />
+                {s}
+              </label>
+            ))}
+          </div>
+        </div>
+        <div style={{ marginBottom: 20 }}>
+          <label>Token Lifetime</label>
+          <select value={ttl} onChange={e => setTtl(e.target.value)}
+            style={{ width: '100%', background: 'var(--bg-secondary)', color: 'var(--text-primary)', border: '1px solid var(--border)', borderRadius: 6, padding: '6px 10px', fontSize: 14 }}>
+            {ttlOptions.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
+          </select>
+        </div>
+        {error && <div style={{ color: 'var(--error)', fontSize: 13, marginBottom: 12 }}>{error}</div>}
+        <div style={{ display: 'flex', gap: 12, justifyContent: 'flex-end' }}>
+          <button type="button" className="btn btn-secondary" onClick={onClose}>Cancel</button>
+          <button type="submit" className="btn btn-primary" disabled={loading}>
+            {loading ? 'Registering...' : 'Register'}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+
+function CredentialsModal({ credentials, onClose }: {
+  credentials: { clientId: string; clientSecret: string; name: string };
+  onClose: () => void;
+}) {
+  const copy = (text: string) => navigator.clipboard.writeText(text);
+  const downloadJson = () => {
+    const blob = new Blob([JSON.stringify(credentials, null, 2)], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url; a.download = `${credentials.name}-credentials.json`; a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <div className="modal-overlay">
+      <div className="modal" style={{ maxWidth: 560 }}>
+        <div style={{ textAlign: 'center', marginBottom: 16 }}>
+          <div style={{ fontSize: 36, color: 'var(--success)', marginBottom: 8 }}>&#10003;</div>
+          <div style={{ fontSize: 20, fontWeight: 600 }}>Agent Registered</div>
+        </div>
+
+        <div style={{ marginBottom: 12 }}>
+          <label style={{ fontSize: 12 }}>Client ID</label>
+          <div className="code-block">
+            <span>{credentials.clientId}</span>
+            <button className="copy-btn" onClick={() => copy(credentials.clientId)}>Copy</button>
+          </div>
+        </div>
+
+        <div style={{ marginBottom: 12 }}>
+          <label style={{ fontSize: 12 }}>Client Secret</label>
+          <div className="code-block">
+            <span>{credentials.clientSecret}</span>
+            <button className="copy-btn" onClick={() => copy(credentials.clientSecret)}>Copy</button>
+          </div>
+        </div>
+
+        <div className="warning-bar">
+          Save this secret now. It will not be shown again.
+        </div>
+
+        <div style={{ display: 'flex', gap: 12, justifyContent: 'flex-end', marginTop: 20 }}>
+          <button className="btn btn-secondary" onClick={downloadJson}>Download as JSON</button>
+          <button className="btn btn-primary" onClick={onClose}>Done</button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function AgentDrawer({ agent, onClose, onRevoked }: { agent: Agent; onClose: () => void; onRevoked: () => void }) {
+  const [tab, setTab] = useState<'claude-code' | 'chatgpt' | 'claude-cowork' | 'perplexity' | 'cursor' | 'json'>('claude-code');
+  const copy = (text: string) => navigator.clipboard.writeText(text);
+  const serverUrl = window.location.origin;
+
+  const cid = agent.id || agent.client_id || '';
+  const isOAuth = agent.auth_type === 'oauth';
+  const agentName = agent.name || agent.client_name || 'unknown';
+
+  // For API keys, we can't show the actual token (it was shown once at creation).
+  // For OAuth, we show the client_id and tell them to use their secret.
+
+  const configSnippets: Record<string, string> = {
+    'claude-code': isOAuth
+      ? [
+        `The user wants to connect GBrain MCP to your context. Here's how.`,
+        ``,
+        `# Step 1 — read the client secret from the operator without putting it in shell history.`,
+        `# read -s suppresses the echo; export keeps it scoped to this shell session.`,
+        `read -rs -p "Client Secret: " GBRAIN_CS && echo`,
+        ``,
+        `# Step 2 — mint a token and register GBrain in one go.`,
+        `claude mcp add --transport http gbrain ${serverUrl}/mcp \\`,
+        `  --header "Authorization: Bearer $(curl -s -X POST ${serverUrl}/token \\`,
+        `    -d 'grant_type=client_credentials' \\`,
+        `    -d 'client_id=${cid}' \\`,
+        `    --data-urlencode "client_secret=$GBRAIN_CS" \\`,
+        `    -d 'scope=${agent.scope || 'read write'}' | jq -r .access_token)"`,
+        ``,
+        `# Step 3 — clear the secret from this shell.`,
+        `unset GBRAIN_CS`,
+        ``,
+        `The token will last ${agent.token_ttl ? (agent.token_ttl >= 86400 ? Math.floor(agent.token_ttl / 86400) + ' days' : Math.floor(agent.token_ttl / 3600) + ' hours') : '1 hour (default)'}.`,
+        ``,
+        `─── Fallback: 2-step curl + paste ───`,
+        ``,
+        `If your shell doesn't support read -s, mint the token first, then paste:`,
+        ``,
+        `curl -s -X POST ${serverUrl}/token \\`,
+        `  -d 'grant_type=client_credentials' \\`,
+        `  -d 'client_id=${cid}' \\`,
+        `  -d 'client_secret=PASTE_YOUR_CLIENT_SECRET_HERE' \\`,
+        `  -d 'scope=${agent.scope || 'read write'}' | jq -r .access_token`,
+        ``,
+        `claude mcp add --transport http gbrain ${serverUrl}/mcp \\`,
+        `  --header "Authorization: Bearer PASTE_TOKEN_FROM_ABOVE"`,
+        ``,
+        `# Then run: history -d $((HISTCMD-1))   # zsh: print -s -- '' && fc -p`,
+      ].join('\n')
+      : [
+        `The user wants to connect GBrain MCP to your context. Here's how.`,
+        ``,
+        `Run this command in terminal to register GBrain:`,
+        ``,
+        `claude mcp add --transport http gbrain ${serverUrl}/mcp \\`,
+        `  --header "Authorization: Bearer PASTE_YOUR_API_KEY_HERE"`,
+        ``,
+        `Replace PASTE_YOUR_API_KEY_HERE with the API key shown when "${agentName}" was created.`,
+        `API keys never expire.`,
+      ].join('\n'),
+
+    'chatgpt': [
+      `The user wants to connect GBrain MCP to ChatGPT.`,
+      ``,
+      `1. Open ChatGPT > Settings > Tools & Integrations > Add MCP Server`,
+      `2. Enter this URL — ChatGPT will auto-discover the OAuth configuration:`,
+      ``,
+      `   ${serverUrl}/.well-known/oauth-authorization-server`,
+      ``,
+      `3. When prompted for credentials:`,
+      `   Client ID: ${cid}`,
+      `   Client Secret: (the secret from agent registration)`,
+      `   Grant Type: client_credentials`,
+      `   Scope: ${agent.scope || 'read write'}`,
+    ].join('\n'),
+
+    'claude-cowork': [
+      `The user wants to connect GBrain MCP to Claude.ai.`,
+      ``,
+      `1. Open claude.ai > Settings > Connected Apps > Add MCP Server`,
+      `2. Server URL: ${serverUrl}/mcp`,
+      `3. When prompted for auth:`,
+      `   Token endpoint: ${serverUrl}/token`,
+      `   Client ID: ${cid}`,
+      `   Client Secret: (the secret from agent registration)`,
+      `   Scope: ${agent.scope || 'read write'}`,
+      ``,
+      `Discovery URL: ${serverUrl}/.well-known/oauth-authorization-server`,
+    ].join('\n'),
+
+    cursor: isOAuth
+      ? [
+        `The user wants to connect GBrain MCP to Cursor.`,
+        ``,
+        `Cursor supports OAuth for remote MCP. Add to .cursor/mcp.json:`,
+        ``,
+        `{`,
+        `  "mcpServers": {`,
+        `    "gbrain": {`,
+        `      "url": "${serverUrl}/mcp",`,
+        `      "transport": "sse"`,
+        `    }`,
+        `  }`,
+        `}`,
+        ``,
+        `Cursor will auto-discover OAuth via:`,
+        `${serverUrl}/.well-known/oauth-authorization-server`,
+        ``,
+        `When prompted: Client ID ${cid}, use the secret from registration.`,
+      ].join('\n')
+      : [
+        `The user wants to connect GBrain MCP to Cursor.`,
+        ``,
+        `Add to .cursor/mcp.json:`,
+        ``,
+        `{`,
+        `  "mcpServers": {`,
+        `    "gbrain": {`,
+        `      "url": "${serverUrl}/mcp",`,
+        `      "transport": "sse",`,
+        `      "headers": {`,
+        `        "Authorization": "Bearer PASTE_YOUR_API_KEY_HERE"`,
+        `      }`,
+        `    }`,
+        `  }`,
+        `}`,
+        ``,
+        `Replace PASTE_YOUR_API_KEY_HERE with the API key shown when "${agentName}" was created.`,
+      ].join('\n'),
+
+    perplexity: [
+      `The user wants to connect GBrain MCP to Perplexity.`,
+      ``,
+      `1. Go to Settings > Connectors > Add MCP`,
+      `2. Server URL: ${serverUrl}/mcp`,
+      `3. Client ID: ${cid}`,
+      `4. Client Secret: (the secret from agent registration)`,
+    ].join('\n'),
+
+    json: JSON.stringify({
+      server_url: serverUrl + '/mcp',
+      token_url: serverUrl + '/token',
+      discovery_url: serverUrl + '/.well-known/oauth-authorization-server',
+      client_id: cid,
+      client_name: agentName,
+      auth_type: agent.auth_type,
+      scope: agent.scope,
+    }, null, 2),
+  };
+
+  return (
+    <>
+      <div className="drawer-overlay" onClick={onClose} />
+      <div className="drawer">
+        <button className="drawer-close" onClick={onClose}>&#10005;</button>
+        <div style={{ fontSize: 18, fontWeight: 600, marginBottom: 4 }}>{agent.name || agent.client_name}</div>
+        <span className={`badge ${agent.status === 'active' ? 'badge-success' : 'badge-danger'}`}>{agent.status}</span>
+
+        <div className="section-title">Details</div>
+        <div style={{ display: 'grid', gridTemplateColumns: '100px 1fr', gap: '6px 12px', fontSize: 13 }}>
+          <span style={{ color: 'var(--text-secondary)' }}>Client ID</span>
+          <span className="mono">{(agent.id || agent.id || agent.client_id || '').substring(0, 24)}...</span>
+          <span style={{ color: 'var(--text-secondary)' }}>Scopes</span>
+          <span>{(agent.scope || '').split(' ').filter(Boolean).map(s => (
+            <span key={s} className={`badge badge-${s}`} style={{ marginRight: 4 }}>{s}</span>
+          ))}</span>
+          <span style={{ color: 'var(--text-secondary)' }}>Registered</span>
+          <span>{new Date(agent.created_at).toLocaleDateString()}</span>
+          <span style={{ color: 'var(--text-secondary)' }}>Token TTL</span>
+          <span>{agent.token_ttl ? (agent.token_ttl >= 31536000 ? 'No expiry' : agent.token_ttl >= 86400 ? `${Math.floor(agent.token_ttl / 86400)}d` : agent.token_ttl >= 3600 ? `${Math.floor(agent.token_ttl / 3600)}h` : `${agent.token_ttl}s`) : '1h (default)'}</span>
+        </div>
+
+        {/*
+          Config Export visible for both auth_type=oauth AND auth_type=api_key.
+          Claude Code + Cursor + JSON tabs render real snippets regardless
+          (commit 15's snippets are auth-type-aware for those two clients;
+          JSON is just structured metadata). ChatGPT, Claude.ai, and
+          Perplexity tabs render an "OAuth client required" message on
+          api_key agents — those MCP clients only speak OAuth 2.0
+          client_credentials, not raw bearer tokens.
+
+          Pre-fix (Wintermute commit 16): the entire Config Export
+          section was hidden for api_key agents, dropping the working
+          Claude Code + Cursor snippets along with the broken ones.
+          (D5=C in the eng review.)
+        */}
+        <div className="section-title">Config Export</div>
+        <div className="tabs" style={{ flexWrap: 'wrap' }}>
+          <div className={`tab ${tab === 'claude-code' ? 'active' : ''}`} onClick={() => setTab('claude-code')}>Claude Code</div>
+          <div className={`tab ${tab === 'chatgpt' ? 'active' : ''}`} onClick={() => setTab('chatgpt')}>ChatGPT</div>
+          <div className={`tab ${tab === 'claude-cowork' ? 'active' : ''}`} onClick={() => setTab('claude-cowork')}>Claude.ai</div>
+          <div className={`tab ${tab === 'cursor' ? 'active' : ''}`} onClick={() => setTab('cursor')}>Cursor</div>
+          <div className={`tab ${tab === 'perplexity' ? 'active' : ''}`} onClick={() => setTab('perplexity')}>Perplexity</div>
+          <div className={`tab ${tab === 'json' ? 'active' : ''}`} onClick={() => setTab('json')}>JSON</div>
+        </div>
+        {(() => {
+          const oauthOnlyTabs = new Set(['chatgpt', 'claude-cowork', 'perplexity']);
+          if (!isOAuth && oauthOnlyTabs.has(tab)) {
+            const clientName = { chatgpt: 'ChatGPT', 'claude-cowork': 'Claude.ai', perplexity: 'Perplexity' }[tab] || tab;
+            return (
+              <div style={{
+                background: 'rgba(255, 200, 100, 0.08)',
+                border: '1px solid rgba(255, 200, 100, 0.2)',
+                borderRadius: 8,
+                padding: '14px 16px',
+                marginTop: 12,
+                fontSize: 13,
+                lineHeight: 1.6,
+                color: 'var(--text-secondary)',
+              }}>
+                <div style={{ fontWeight: 600, color: 'var(--text-primary)', marginBottom: 6 }}>
+                  {clientName} requires an OAuth client
+                </div>
+                {clientName} only supports OAuth 2.0 (client_credentials). API keys use raw bearer tokens, which {clientName} does not accept. Register a separate OAuth client and use that to connect this AI.
+              </div>
+            );
+          }
+          return (
+            <div className="code-block">
+              <pre style={{ whiteSpace: 'pre-wrap', margin: 0 }}>{configSnippets[tab]}</pre>
+              <button className="copy-btn" onClick={() => copy(configSnippets[tab])}>Copy</button>
+            </div>
+          );
+        })()}
+
+        <div style={{ marginTop: 32 }}>
+          {agent.status === 'active' && (
+            <button className="btn btn-danger" onClick={async () => {
+              if (!confirm(`Revoke ${agent.name || agent.client_name}? All active tokens will be invalidated.`)) return;
+              try {
+                if (agent.auth_type === 'oauth') {
+                  await api.revokeClient(agent.id || agent.client_id || '');
+                } else {
+                  await api.revokeApiKey(agent.name || '');
+                }
+                onRevoked();
+                onClose();
+              } catch (e) {
+                alert('Revoke failed: ' + (e instanceof Error ? e.message : 'unknown error'));
+              }
+            }}>Revoke Agent</button>
+          )}
+          {agent.status === 'revoked' && (
+            <span style={{ color: 'var(--text-muted)', fontSize: 13 }}>This agent has been revoked.</span>
+          )}
+        </div>
+      </div>
+    </>
+  );
+}

admin/src/pages/Dashboard.tsx

@@ -0,0 +1,137 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { api } from '../api';
+
+interface FeedEvent {
+  agent: string;
+  operation: string;
+  scopes: string;
+  latency_ms: number;
+  status: string;
+  timestamp: string;
+}
+
+export function DashboardPage() {
+  const [stats, setStats] = useState({ connected_agents: 0, requests_today: 0, active_tokens: 0 });
+  const [health, setHealth] = useState({ expiring_soon: 0, error_rate: '0%' });
+  const [events, setEvents] = useState<FeedEvent[]>([]);
+  const [sseStatus, setSseStatus] = useState<'connecting' | 'connected' | 'disconnected'>('connecting');
+  const eventSourceRef = useRef<EventSource | null>(null);
+
+  useEffect(() => {
+    api.stats().then(setStats).catch(() => {});
+    api.health().then(setHealth).catch(() => {});
+
+    const es = new EventSource('/admin/events');
+    eventSourceRef.current = es;
+    es.onopen = () => setSseStatus('connected');
+    es.onmessage = (e) => {
+      try {
+        const event = JSON.parse(e.data) as FeedEvent;
+        setEvents(prev => [event, ...prev].slice(0, 50));
+      } catch {}
+    };
+    es.onerror = () => {
+      setSseStatus('disconnected');
+      setTimeout(() => {
+        setSseStatus('connecting');
+        es.close();
+        // Reconnect handled by browser EventSource auto-retry
+      }, 3000);
+    };
+
+    const interval = setInterval(() => {
+      api.stats().then(setStats).catch(() => {});
+      api.health().then(setHealth).catch(() => {});
+    }, 30000);
+
+    return () => { es.close(); clearInterval(interval); };
+  }, []);
+
+  const timeAgo = (ts: string) => {
+    const diff = Date.now() - new Date(ts).getTime();
+    if (diff < 60000) return `${Math.floor(diff / 1000)}s ago`;
+    if (diff < 3600000) return `${Math.floor(diff / 60000)} min ago`;
+    return `${Math.floor(diff / 3600000)}h ago`;
+  };
+
+  return (
+    <>
+      <h1 className="page-title">Dashboard</h1>
+
+      <div style={{ display: 'flex', gap: 24 }}>
+        <div style={{ flex: 1 }}>
+          <div className="metrics">
+            <div className="metric">
+              <div className="metric-value">{stats.connected_agents}</div>
+              <div className="metric-label">Connected Agents</div>
+            </div>
+            <div className="metric">
+              <div className="metric-value">{stats.requests_today}</div>
+              <div className="metric-label">Requests Today</div>
+            </div>
+            <div className="metric">
+              <div className="metric-value">{stats.active_tokens}</div>
+              <div className="metric-label">Active Tokens</div>
+            </div>
+          </div>
+
+          <h2 className="section-title">
+            Live Activity
+            <span style={{ marginLeft: 8, fontSize: 10, color: sseStatus === 'connected' ? 'var(--success)' : sseStatus === 'connecting' ? 'var(--warning)' : 'var(--error)' }}>
+              {sseStatus === 'connected' ? '● connected' : sseStatus === 'connecting' ? '● connecting...' : '● disconnected'}
+            </span>
+          </h2>
+
+          <div className="feed">
+            {events.length === 0 ? (
+              <div className="feed-empty">
+                {sseStatus === 'connected' ? 'No requests yet. Agents will appear when they connect.' : 'Connecting...'}
+              </div>
+            ) : (
+              <table>
+                <thead>
+                  <tr>
+                    <th>Agent</th>
+                    <th>Operation</th>
+                    <th>Scopes</th>
+                    <th>Latency</th>
+                    <th>Status</th>
+                    <th>Time</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {events.map((e, i) => (
+                    <tr key={i}>
+                      <td className="mono">{e.agent}</td>
+                      <td className="mono">{e.operation}</td>
+                      <td>{e.scopes.split(',').map(s => (
+                        <span key={s} className={`badge badge-${s.trim()}`} style={{ marginRight: 4 }}>{s.trim()}</span>
+                      ))}</td>
+                      <td className="mono">{e.latency_ms} ms</td>
+                      <td><span className={`badge badge-${e.status}`}>{e.status}</span></td>
+                      <td style={{ color: 'var(--text-secondary)' }}>{timeAgo(e.timestamp)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            )}
+          </div>
+        </div>
+
+        <div style={{ width: 220 }}>
+          <h2 className="section-title">Token Health</h2>
+          <div className="health-panel">
+            <div className="health-row">
+              <span style={{ color: 'var(--warning)' }}>Expiring Soon</span>
+              <span className="mono">{health.expiring_soon}</span>
+            </div>
+            <div className="health-row">
+              <span style={{ color: 'var(--error)' }}>Error Rate</span>
+              <span className="mono">{health.error_rate}</span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}

admin/src/pages/Login.tsx

@@ -0,0 +1,96 @@
+import React, { useState } from 'react';
+import { api } from '../api';
+
+// v0.26.3 trust model (D11 + D12):
+// - The bootstrap token is NEVER stored in browser JS state. No
+//   localStorage, no sessionStorage, no React state beyond the form
+//   submit cycle. After successful POST /admin/login the operator's
+//   token only lives in the HttpOnly cookie that the server set.
+// - Magic-link URLs use single-use server-issued nonces, not the
+//   bootstrap token itself (see /admin/api/issue-magic-link). The
+//   bootstrap token never appears in a URL.
+// - Closing the tab ends the session client-side. Reopening the
+//   dashboard 401s and shows this page again. Operator asks the agent
+//   for a fresh magic link or pastes the bootstrap token from the
+//   server's terminal scrollback.
+export function LoginPage({ onLogin }: { onLogin: () => void }) {
+  const [token, setToken] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError('');
+    setLoading(true);
+    try {
+      await api.login(token);
+      // Don't persist the token. The HttpOnly cookie is the only
+      // session credential after this point.
+      setToken('');
+      onLogin();
+    } catch (err) {
+      setError('Invalid token.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="login-page">
+      <div className="login-box">
+        <div className="login-logo">GBrain</div>
+
+        <div style={{
+          background: 'rgba(136, 170, 255, 0.08)',
+          border: '1px solid rgba(136, 170, 255, 0.2)',
+          borderRadius: 8,
+          padding: '14px 16px',
+          marginBottom: 20,
+          fontSize: 13,
+          lineHeight: 1.5,
+          color: 'var(--text-secondary)',
+        }}>
+          <div style={{ fontWeight: 600, color: 'var(--text-primary)', marginBottom: 6 }}>
+            🔒 This is a protected dashboard
+          </div>
+          Ask your AI agent for the admin login link:
+          <div style={{
+            background: 'rgba(0,0,0,0.3)',
+            borderRadius: 6,
+            padding: '8px 12px',
+            marginTop: 8,
+            fontFamily: 'var(--font-mono)',
+            fontSize: 12,
+            color: '#88aaff',
+            wordBreak: 'break-all',
+          }}>
+            "Give me the GBrain admin login link"
+          </div>
+          <div style={{ marginTop: 8, fontSize: 12, color: 'var(--text-muted)' }}>
+            Each link is single-use. Your agent generates a fresh one each time.
+          </div>
+        </div>
+
+        <details style={{ marginBottom: 16 }}>
+          <summary style={{ cursor: 'pointer', fontSize: 13, color: 'var(--text-muted)' }}>
+            Or paste bootstrap token manually
+          </summary>
+          <form onSubmit={handleSubmit} style={{ marginTop: 12 }}>
+            <div style={{ marginBottom: 12 }}>
+              <input
+                type="password"
+                placeholder="Admin Token"
+                value={token}
+                onChange={e => setToken(e.target.value)}
+              />
+            </div>
+            <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading}>
+              {loading ? 'Authenticating...' : 'Submit'}
+            </button>
+            {error && <div className="login-error">{error}</div>}
+          </form>
+        </details>
+      </div>
+    </div>
+  );
+}

admin/src/pages/RequestLog.tsx

@@ -0,0 +1,150 @@
+import React, { useState, useEffect } from 'react';
+import { api } from '../api';
+
+interface LogEntry {
+  id: number;
+  token_name: string;
+  agent_name: string;
+  operation: string;
+  latency_ms: number;
+  status: string;
+  params: Record<string, unknown> | null;
+  error_message: string | null;
+  created_at: string;
+}
+
+export function RequestLogPage() {
+  const [data, setData] = useState<{ rows: LogEntry[]; total: number; page: number; pages: number }>({
+    rows: [], total: 0, page: 1, pages: 1,
+  });
+  const [page, setPage] = useState(1);
+  const [agentFilter, setAgentFilter] = useState('all');
+  const [expandedRow, setExpandedRow] = useState<number | null>(null);
+
+  useEffect(() => { loadPage(page); }, [page, agentFilter]);
+
+  const loadPage = (p: number) => {
+    const qs = agentFilter !== 'all' ? `&agent=${encodeURIComponent(agentFilter)}` : '';
+    api.requests(p, qs).then(setData).catch(() => {});
+  };
+
+  const timeAgo = (ts: string) => {
+    const diff = Date.now() - new Date(ts).getTime();
+    if (diff < 60000) return `${Math.floor(diff / 1000)}s ago`;
+    if (diff < 3600000) return `${Math.floor(diff / 60000)} min ago`;
+    if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
+    return new Date(ts).toLocaleDateString();
+  };
+
+
+
+  const formatParams = (params: Record<string, unknown> | null) => {
+    if (!params) return null;
+    const { query, slug, partial, limit, ...rest } = params as any;
+    const parts: string[] = [];
+    if (query) parts.push(`"${query}"`);
+    if (slug) parts.push(slug);
+    if (partial) parts.push(`~${partial}`);
+    if (limit) parts.push(`limit=${limit}`);
+    if (Object.keys(rest).length > 0) parts.push(`+${Object.keys(rest).length} params`);
+    return parts.join(' ');
+  };
+
+  // Collect unique agents for filter (use name for display, token_name for value)
+  const agentMap = new Map<string, string>();
+  data.rows.forEach(r => { if (r.token_name) agentMap.set(r.token_name, r.agent_name || r.token_name); });
+
+  return (
+    <>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 24 }}>
+        <h1 className="page-title" style={{ marginBottom: 0 }}>Request Log</h1>
+        <select value={agentFilter} onChange={e => { setAgentFilter(e.target.value); setPage(1); }}
+          style={{ background: 'var(--bg-secondary)', color: 'var(--text-primary)', border: '1px solid var(--border)', borderRadius: 6, padding: '4px 8px', fontSize: 13 }}>
+          <option value="all">All agents</option>
+          {[...agentMap.entries()].map(([id, name]) => <option key={id} value={id}>{name}</option>)}
+        </select>
+      </div>
+
+      {data.rows.length === 0 ? (
+        <div style={{ textAlign: 'center', padding: 48, color: 'var(--text-muted)' }}>
+          No requests yet.
+        </div>
+      ) : (
+        <>
+          <table>
+            <thead>
+              <tr>
+                <th>Time</th>
+                <th>Agent</th>
+                <th>Operation</th>
+                <th>Params</th>
+                <th>Latency</th>
+                <th>Status</th>
+              </tr>
+            </thead>
+            <tbody>
+              {data.rows.map(r => (
+                <React.Fragment key={r.id}>
+                  <tr onClick={() => setExpandedRow(expandedRow === r.id ? null : r.id)}
+                      style={{ cursor: 'pointer' }}>
+                    <td style={{ color: 'var(--text-secondary)', whiteSpace: 'nowrap' }}>{timeAgo(r.created_at)}</td>
+                    <td>
+                      <a style={{ color: 'var(--text-link, #88aaff)', cursor: 'pointer', textDecoration: 'none', fontWeight: 500 }}
+                         onClick={(e) => { e.stopPropagation(); setAgentFilter(r.token_name); setPage(1); }}>
+                        {r.agent_name || r.token_name}
+                      </a>
+                    </td>
+                    <td className="mono">{r.operation}</td>
+                    <td style={{ color: 'var(--text-secondary)', fontSize: 12, maxWidth: 200, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                      {formatParams(r.params)}
+                    </td>
+                    <td className="mono">{r.latency_ms}ms</td>
+                    <td><span className={`badge badge-${r.status}`}>{r.status}</span></td>
+                  </tr>
+                  {expandedRow === r.id && (
+                    <tr>
+                      <td colSpan={6} style={{ background: 'var(--bg-secondary, #0f0f1a)', padding: 16 }}>
+                        <div style={{ display: 'grid', gridTemplateColumns: '100px 1fr', gap: '6px 12px', fontSize: 13 }}>
+                          <span style={{ color: 'var(--text-muted)' }}>Time</span>
+                          <span>{new Date(r.created_at).toLocaleString()}</span>
+                          <span style={{ color: 'var(--text-muted)' }}>Agent</span>
+                          <span className="mono">{r.token_name}</span>
+                          <span style={{ color: 'var(--text-muted)' }}>Operation</span>
+                          <span className="mono">{r.operation}</span>
+                          <span style={{ color: 'var(--text-muted)' }}>Latency</span>
+                          <span>{r.latency_ms}ms</span>
+                          {r.params && (
+                            <>
+                              <span style={{ color: 'var(--text-muted)' }}>Params</span>
+                              <pre className="mono" style={{ margin: 0, whiteSpace: 'pre-wrap', fontSize: 12 }}>
+                                {JSON.stringify(r.params, null, 2)}
+                              </pre>
+                            </>
+                          )}
+                          {r.error_message && (
+                            <>
+                              <span style={{ color: 'var(--error, #ff6b6b)' }}>Error</span>
+                              <span style={{ color: 'var(--error, #ff6b6b)' }}>{r.error_message}</span>
+                            </>
+                          )}
+                        </div>
+                      </td>
+                    </tr>
+                  )}
+                </React.Fragment>
+              ))}
+            </tbody>
+          </table>
+
+          <div className="pagination">
+            <span>Page {data.page} of {data.pages} ({data.total} total)</span>
+            <div style={{ display: 'flex', gap: 8 }}>
+              <button disabled={data.page <= 1} onClick={() => setPage(p => p - 1)}>Previous</button>
+              <button disabled={data.page >= data.pages} onClick={() => setPage(p => p + 1)}>Next</button>
+            </div>
+          </div>
+        </>
+      )}
+    </>
+  );
+}

admin/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

admin/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}

admin/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  base: '/admin/',
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+  },
+});

bun.lock

@@ -5,22 +5,58 @@
     "": {
       "name": "gbrain",
       "dependencies": {
+        "@ai-sdk/anthropic": "^3.0.71",
+        "@ai-sdk/google": "^3.0.64",
+        "@ai-sdk/openai": "^3.0.53",
+        "@ai-sdk/openai-compatible": "^2.0.41",
         "@anthropic-ai/sdk": "^0.30.0",
         "@aws-sdk/client-s3": "^3.1028.0",
-        "@electric-sql/pglite": "^0.4.4",
-        "@modelcontextprotocol/sdk": "^1.0.0",
+        "@dqbd/tiktoken": "^1.0.22",
+        "@electric-sql/pglite": "0.4.3",
+        "@modelcontextprotocol/sdk": "1.29.0",
+        "ai": "^6.0.168",
+        "cookie-parser": "^1.4.7",
+        "cors": "^2.8.5",
+        "eventsource-parser": "^3.0.8",
+        "express": "^5.1.0",
+        "express-rate-limit": "^7.5.0",
         "gray-matter": "^4.0.3",
         "marked": "^18.0.0",
         "openai": "^4.0.0",
         "pgvector": "^0.2.0",
         "postgres": "^3.4.0",
+        "tree-sitter-wasms": "0.1.13",
+        "web-tree-sitter": "0.22.6",
+        "zod": "^4.3.6",
       },
       "devDependencies": {
         "@types/bun": "latest",
+        "@types/cookie-parser": "^1.4.7",
+        "@types/cors": "^2.8.19",
+        "@types/express": "^5.0.6",
+        "bun-types": "^1.3.13",
+        "typescript": "^5.6.0",
       },
     },
   },
+  "trustedDependencies": [
+    "@electric-sql/pglite",
+  ],
   "packages": {
+    "@ai-sdk/anthropic": ["@ai-sdk/anthropic@3.0.74", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.26" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-Xew9rfz9WWhDSyF8rNhjT/XWOWelNfJrMlmG0Ahw210hStisRpQZ1s+7VeI9JTJOZ5y5tXqBi5kfPwYnCfyRTA=="],
+
+    "@ai-sdk/gateway": ["@ai-sdk/gateway@3.0.109", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.26", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-r6dOqThjODp1vOhGRJg2OCmyB/ZOQtGx1esZ2SDvwDX5XoX8dBqYaYjLg8MPXTzMGJSgOkJyCxWgUcZtAl16pw=="],
+
+    "@ai-sdk/google": ["@ai-sdk/google@3.0.67", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.26" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-Qeq+SidYtzMrcf0fdw3L0QLmtXK+ErwdBzbxS4+0Q/2UP85Ges8RJJcbAj7SO8e2JbeJoM35BLqkeNy1o3wJvQ=="],
+
+    "@ai-sdk/openai": ["@ai-sdk/openai@3.0.58", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.26" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-2+5xGMROmrBboJuoOwqLL3b/o3i56+NRdxXDNVAiTyYjLiBj6KzembeuyuBT217be1X+zkEfAqD1H0irJlGIyw=="],
+
+    "@ai-sdk/openai-compatible": ["@ai-sdk/openai-compatible@2.0.45", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.26" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-5YBvurNL7Oj7mT3srws4Rh4cQidoorfEGObAOb5jV40eld8IC7EkXWARZjnWYqgYzabUs6Sn6muiXfQVkgOyOQ=="],
+
+    "@ai-sdk/provider": ["@ai-sdk/provider@3.0.10", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-Q3BZ27qfpYqnCYGvE3vt+Qi6LGOF9R5Nmzn+9JoM1lCRsD9mYaIhfJLkSunN48nfGXJ6n+XNV0J/XVpqGQl7Dw=="],
+
+    "@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.26", "", { "dependencies": { "@ai-sdk/provider": "3.0.10", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.8" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-CsKNLKsOpvPujRlIYvoz+Ybw+kGn7J4/fIZa/58+R7iWLLfwn6ifE2G6Yq8K9XvH/I/3bzaDAJ3NhRwEMsLBKQ=="],
+
     "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.30.1", "", { "dependencies": { "@types/node": "^18.11.18", "@types/node-fetch": "^2.6.4", "abort-controller": "^3.0.0", "agentkeepalive": "^4.2.1", "form-data-encoder": "1.7.2", "formdata-node": "^4.3.2", "node-fetch": "^2.6.7" } }, "sha512-nuKvp7wOIz6BFei8WrTdhmSsx5mwnArYyJgh4+vYu3V4J0Ltb8Xm3odPm51n1aSI0XxNCrDl7O88cxCtUdAkaw=="],
 
     "@aws-crypto/crc32": ["@aws-crypto/crc32@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg=="],
@@ -103,12 +139,16 @@
 
     "@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.2.4", "", {}, "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ=="],
 
-    "@electric-sql/pglite": ["@electric-sql/pglite@0.4.4", "", {}, "sha512-g/6CWAJ4XOkObWCWAQ2IReZD8VvsDy3poRHSKvpRR2F96F8WJ3HVbjpso3gN7l0q6QPPgvxSSpl/qo5k8a7mkQ=="],
+    "@dqbd/tiktoken": ["@dqbd/tiktoken@1.0.22", "", {}, "sha512-RYhO8xeHkMNX5Ixqf4M1Ve3siCYJY/dI0yLnlX4M4oIEDOvjMIQ+E+3OUpAaZcWTaMtQJzGcDAghYfllpx3i/w=="],
+
+    "@electric-sql/pglite": ["@electric-sql/pglite@0.4.3", "", {}, "sha512-ichuWTgtd4mOM1G4SpyGJa5trT03lWbMypDV0fUXUCXg5hiHqVAz/bZyV68NqmkLB7WcYmj1RMJVSp8HV/v/ZQ=="],
 
     "@hono/node-server": ["@hono/node-server@1.19.12", "", { "peerDependencies": { "hono": "^4" } }, "sha512-txsUW4SQ1iilgE0l9/e9VQWmELXifEFvmdA1j6WFh/aFPj99hIntrSsq/if0UWyGVkmrRPKA1wCeP+UCr1B9Uw=="],
 
     "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.29.0", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ=="],
 
+    "@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
+
     "@smithy/chunked-blob-reader": ["@smithy/chunked-blob-reader@5.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-St+kVicSyayWQca+I1rGitaOEH6uKgE8IUWoYnnEX26SWdWQcL6LvMSD19Lg+vYHKdT9B2Zuu7rd3i6Wnyb/iw=="],
 
     "@smithy/chunked-blob-reader-native": ["@smithy/chunked-blob-reader-native@4.2.3", "", { "dependencies": { "@smithy/util-base64": "^4.3.2", "tslib": "^2.6.2" } }, "sha512-jA5k5Udn7Y5717L86h4EIv06wIr3xn8GM1qHRi/Nf31annXcXHJjBKvgztnbn2TxH3xWrPBfgwHsOwZf0UmQWw=="],
@@ -209,18 +249,46 @@
 
     "@smithy/uuid": ["@smithy/uuid@1.1.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-O/IEdcCUKkubz60tFbGA7ceITTAJsty+lBjNoorP4Z6XRqaFb/OjQjZODophEcuq68nKm6/0r+6/lLQ+XVpk8g=="],
 
+    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
+
+    "@types/body-parser": ["@types/body-parser@1.19.6", "", { "dependencies": { "@types/connect": "*", "@types/node": "*" } }, "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g=="],
+
     "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
 
-    "@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "~5.26.4" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
+    "@types/connect": ["@types/connect@3.4.38", "", { "dependencies": { "@types/node": "*" } }, "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug=="],
+
+    "@types/cookie-parser": ["@types/cookie-parser@1.4.10", "", { "peerDependencies": { "@types/express": "*" } }, "sha512-B4xqkqfZ8Wek+rCOeRxsjMS9OgvzebEzzLYw7NHYuvzb7IdxOkI0ZHGgeEBX4PUM7QGVvNSK60T3OvWj3YfBRg=="],
+
+    "@types/cors": ["@types/cors@2.8.19", "", { "dependencies": { "@types/node": "*" } }, "sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg=="],
+
+    "@types/express": ["@types/express@5.0.6", "", { "dependencies": { "@types/body-parser": "*", "@types/express-serve-static-core": "^5.0.0", "@types/serve-static": "^2" } }, "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA=="],
+
+    "@types/express-serve-static-core": ["@types/express-serve-static-core@5.1.1", "", { "dependencies": { "@types/node": "*", "@types/qs": "*", "@types/range-parser": "*", "@types/send": "*" } }, "sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A=="],
+
+    "@types/http-errors": ["@types/http-errors@2.0.5", "", {}, "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg=="],
+
+    "@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
 
     "@types/node-fetch": ["@types/node-fetch@2.6.13", "", { "dependencies": { "@types/node": "*", "form-data": "^4.0.4" } }, "sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw=="],
 
+    "@types/qs": ["@types/qs@6.15.0", "", {}, "sha512-JawvT8iBVWpzTrz3EGw9BTQFg3BQNmwERdKE22vlTxawwtbyUSlMppvZYKLZzB5zgACXdXxbD3m1bXaMqP/9ow=="],
+
+    "@types/range-parser": ["@types/range-parser@1.2.7", "", {}, "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ=="],
+
+    "@types/send": ["@types/send@1.2.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ=="],
+
+    "@types/serve-static": ["@types/serve-static@2.2.0", "", { "dependencies": { "@types/http-errors": "*", "@types/node": "*" } }, "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ=="],
+
+    "@vercel/oidc": ["@vercel/oidc@3.2.0", "", {}, "sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug=="],
+
     "abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
 
     "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
 
     "agentkeepalive": ["agentkeepalive@4.6.0", "", { "dependencies": { "humanize-ms": "^1.2.1" } }, "sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ=="],
 
+    "ai": ["ai@6.0.174", "", { "dependencies": { "@ai-sdk/gateway": "3.0.109", "@ai-sdk/provider": "3.0.10", "@ai-sdk/provider-utils": "4.0.26", "@opentelemetry/api": "1.9.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-bTrfLUWHWtkjzWyCY4bmyuk4Qvmj4S4NSNsXyNSVVqkmftQNtxRj7dzUoMeQDBBwlJO6fC7m2Q/lNOPqQQfAGA=="],
+
     "ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
     "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
@@ -233,7 +301,7 @@
 
     "bowser": ["bowser@2.14.1", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="],
 
-    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+    "bun-types": ["bun-types@1.3.13", "", { "dependencies": { "@types/node": "*" } }, "sha512-QXKeHLlOLqQX9LgYaHJfzdBaV21T63HhFJnvuRCcjZiaUDpbs5ED1MgxbMra71CsryN/1dAoXuJJJwIv/2drVA=="],
 
     "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
 
@@ -249,7 +317,9 @@
 
     "cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
 
-    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+    "cookie-parser": ["cookie-parser@1.4.7", "", { "dependencies": { "cookie": "0.7.2", "cookie-signature": "1.0.6" } }, "sha512-nGUvgXnotP3BsjiLX2ypbQnWoGUPIIfHQNZkkC668ntrzGWEZVW70HDEB1qnNGMicPje6EttlIgzo51YSwNQGw=="],
+
+    "cookie-signature": ["cookie-signature@1.0.6", "", {}, "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ=="],
 
     "cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="],
 
@@ -285,11 +355,11 @@
 
     "eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
 
-    "eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+    "eventsource-parser": ["eventsource-parser@3.0.8", "", {}, "sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ=="],
 
     "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
 
-    "express-rate-limit": ["express-rate-limit@8.3.2", "", { "dependencies": { "ip-address": "10.1.0" }, "peerDependencies": { "express": ">= 4.11" } }, "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg=="],
+    "express-rate-limit": ["express-rate-limit@7.5.1", "", { "peerDependencies": { "express": ">= 4.11" } }, "sha512-7iN8iPMDzOMHPUYllBEsQdWVB6fPDMPqwjBaFrgr4Jgr/+okjvzAy+UHlYYL/Vs0OsOrMkwS6PJDkFlJwoxUnw=="],
 
     "extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="],
 
@@ -353,6 +423,8 @@
 
     "js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
 
+    "json-schema": ["json-schema@0.4.0", "", {}, "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA=="],
+
     "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
 
     "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
@@ -449,11 +521,15 @@
 
     "tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
 
+    "tree-sitter-wasms": ["tree-sitter-wasms@0.1.13", "", { "dependencies": { "tree-sitter-wasms": "^0.1.11" } }, "sha512-wT+cR6DwaIz80/vho3AvSF0N4txuNx/5bcRKoXouOfClpxh/qqrF4URNLQXbbt8MaAxeksZcZd1j8gcGjc+QxQ=="],
+
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
     "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
 
-    "undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
     "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
 
@@ -461,6 +537,8 @@
 
     "web-streams-polyfill": ["web-streams-polyfill@4.0.0-beta.3", "", {}, "sha512-QW95TCTaHmsYfHDybGMwO5IJIM93I/6vTRk+daHTWFPhwh+C8Cg7j7XyKrwrj8Ib6vYXe0ocYNrmzY4xAAN6ug=="],
 
+    "web-tree-sitter": ["web-tree-sitter@0.22.6", "", {}, "sha512-hS87TH71Zd6mGAmYCvlgxeGDjqd9GTeqXNqTT+u0Gs51uIozNIaaq/kUAbV/Zf56jb2ZOyG8BxZs2GG9wbLi6Q=="],
+
     "webidl-conversions": ["webidl-conversions@3.0.1", "", {}, "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="],
 
     "whatwg-url": ["whatwg-url@5.0.0", "", { "dependencies": { "tr46": "~0.0.3", "webidl-conversions": "^3.0.0" } }, "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw=="],
@@ -473,30 +551,40 @@
 
     "zod-to-json-schema": ["zod-to-json-schema@3.25.2", "", { "peerDependencies": { "zod": "^3.25.28 || ^4" } }, "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA=="],
 
+    "@anthropic-ai/sdk/@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "~5.26.4" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
+
     "@aws-crypto/sha1-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
 
     "@aws-crypto/sha256-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
 
     "@aws-crypto/util/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
 
-    "@types/node-fetch/@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
+    "@modelcontextprotocol/sdk/eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
 
-    "bun-types/@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
+    "@modelcontextprotocol/sdk/express-rate-limit": ["express-rate-limit@8.3.2", "", { "dependencies": { "ip-address": "10.1.0" }, "peerDependencies": { "express": ">= 4.11" } }, "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg=="],
+
+    "@types/bun/bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "eventsource/eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+
+    "express/cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
 
     "form-data/mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
 
+    "openai/@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "~5.26.4" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
+
+    "@anthropic-ai/sdk/@types/node/undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
+
     "@aws-crypto/sha1-browser/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
 
     "@aws-crypto/sha256-browser/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
 
     "@aws-crypto/util/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
 
-    "@types/node-fetch/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
-
-    "bun-types/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
-
     "form-data/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
 
+    "openai/@types/node/undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
+
     "@aws-crypto/sha1-browser/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
 
     "@aws-crypto/sha256-browser/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],

bunfig.toml

@@ -0,0 +1,9 @@
+[test]
+# PGLite WASM cold start + initSchema() runs ~5–20s on loaded machines.
+# Default 5s is too short for those tests' beforeAll hooks. 60s is the
+# empirical ceiling we observed for the slowest cold-init paths.
+#
+# v0.26.4: scripts/run-unit-parallel.sh and scripts/run-unit-shard.sh
+# also pass `--timeout=60000` explicitly so the ceiling is consistent
+# whether tests are invoked through the wrapper or directly via bun test.
+timeout = 60_000

docker-compose.ci.yml

@@ -0,0 +1,117 @@
+# docker-compose.ci.yml
+#
+# Local CI gate with 4-way E2E sharding. Spins up 4 pgvector services + a bun
+# runner that bind-mounts the repo. Used by `bun run ci:local` and
+# `bun run ci:local:diff` (see scripts/ci-local.sh).
+#
+# All services are pulled as `image:` (no build) so `docker compose pull`
+# refreshes everything. The bun version floats with `oven/bun:1` to track CI's
+# `bun-version: latest`. Named volumes isolate the Linux container's deps from
+# the host's darwin-arm64 deps and keep bun + postgres data warm across runs.
+#
+# Why 4 postgres services: bun's E2E suite shares one DB across 36 files and
+# uses TRUNCATE CASCADE in setupDB(). Running files in parallel against ONE DB
+# races (file A's TRUNCATE clobbers file B's fixture import). 4 separate DBs
+# remove the race; we shard the file list 1/4..4/4 and run shards in parallel.
+# Within a shard, files still run sequentially. Total wall-time on a 16-core
+# host: ~6 min sequential -> ~1.5-2 min sharded.
+#
+# Postgres host ports default to 5434-5437 (avoid 5432 manual `gbrain-test-pg`
+# and 5433 sibling-project conflicts). Override BASE port with GBRAIN_CI_PG_PORT;
+# shards take BASE..BASE+3.
+
+services:
+  postgres-1:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: gbrain_test
+    ports:
+      - "${GBRAIN_CI_PG_PORT:-5434}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d gbrain_test"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - gbrain-ci-pg-data-1:/var/lib/postgresql/data
+
+  postgres-2:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: gbrain_test
+    ports:
+      - "${GBRAIN_CI_PG_PORT_2:-5435}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d gbrain_test"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - gbrain-ci-pg-data-2:/var/lib/postgresql/data
+
+  postgres-3:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: gbrain_test
+    ports:
+      - "${GBRAIN_CI_PG_PORT_3:-5436}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d gbrain_test"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - gbrain-ci-pg-data-3:/var/lib/postgresql/data
+
+  postgres-4:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: gbrain_test
+    ports:
+      - "${GBRAIN_CI_PG_PORT_4:-5437}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d gbrain_test"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - gbrain-ci-pg-data-4:/var/lib/postgresql/data
+
+  runner:
+    image: oven/bun:1
+    working_dir: /app
+    depends_on:
+      postgres-1:
+        condition: service_healthy
+      postgres-2:
+        condition: service_healthy
+      postgres-3:
+        condition: service_healthy
+      postgres-4:
+        condition: service_healthy
+    # No global DATABASE_URL — scripts/ci-local.sh sets per-shard URL via -e.
+    # Unit phase explicitly unsets DATABASE_URL so test/e2e/* gracefully skip.
+    volumes:
+      - .:/app
+      # Linux container's node_modules MUST be isolated from host darwin-arm64.
+      # Without this, container `bun install` stomps host node_modules and
+      # subsequent `bun test` on host fails with binary-incompat errors.
+      - gbrain-ci-node-modules:/app/node_modules
+      # Warm install cache across runs.
+      - gbrain-ci-bun-cache:/root/.bun/install/cache
+
+volumes:
+  gbrain-ci-pg-data-1:
+  gbrain-ci-pg-data-2:
+  gbrain-ci-pg-data-3:
+  gbrain-ci-pg-data-4:
+  gbrain-ci-node-modules:
+  gbrain-ci-bun-cache:

docs/GBRAIN_SKILLPACK.md

@@ -49,11 +49,25 @@ Running a production brain.
 | Guide | What It Covers |
 |-------|---------------|
 | [Reference Cron Schedule](guides/cron-schedule.md) | 20+ recurring jobs, quiet hours, dream cycle |
+| [Cron via Minions](../skills/conventions/cron-via-minions.md) | Why scheduled work runs as Minion jobs, not `agentTurn`. Auto-applied by v0.11.0 migration for built-in handlers; host-specific handlers use the plugin contract below. |
+| [Plugin Handlers](guides/plugin-handlers.md) | Registering host-specific Minion handlers via code (no data-file exec surface). |
+| [Minions fix](guides/minions-fix.md) | Repairing a half-migrated v0.11.0 install. |
+| [Shell jobs (v0.14.0+)](guides/minions-shell-jobs.md) | Move deterministic crons (API fetch, token refresh, scrape+write) off the LLM gateway. Zero tokens per fire, ~60% gateway headroom. Follow `skills/migrations/v0.14.0.md` for the adoption playbook. |
 | [Quiet Hours & Timezone](guides/quiet-hours.md) | Hold notifications during sleep, timezone-aware delivery |
 | [Executive Assistant Pattern](guides/executive-assistant.md) | Email triage, meeting prep, scheduling |
 | [Operational Disciplines](guides/operational-disciplines.md) | Signal detection, brain-first, sync-after-write, heartbeat, dream cycle |
 | [Skill Development Cycle](guides/skill-development.md) | 5-step cycle: concept, prototype, evaluate, codify, cron |
 
+**Subagent routing (v0.11.0+):** agents that dispatch background work should route through
+`skills/conventions/subagent-routing.md` — it reads `~/.gbrain/preferences.json#minion_mode`
+and branches between native subagents and Minion jobs. The v0.11.0 migration auto-injects
+a marker into AGENTS.md pointing at this convention.
+
+**Cron routing (v0.11.0+):** scheduled work goes through Minions, not OpenClaw's `agentTurn`.
+See `skills/conventions/cron-via-minions.md` for the rewrite pattern. The v0.11.0 migration
+auto-rewrites entries whose handler is a gbrain builtin; host-specific handlers (e.g.
+`ea-inbox-sweep`) need a code-level registration per `docs/guides/plugin-handlers.md`.
+
 ## Architecture
 
 How to structure your system.

docs/GBRAIN_VERIFY.md

@@ -183,6 +183,84 @@ system context. See `skills/setup/SKILL.md` Phase D.
 
 ---
 
+## 7. Knowledge Graph Wired
+
+The v0.12.0 graph layer needs to be populated for existing brains. New writes are
+auto-linked, but historical pages need a one-time backfill.
+
+**Command:**
+
+```bash
+gbrain stats | grep -E 'links|timeline'
+```
+
+**Expected:** Both `links` and `timeline_entries` are non-zero (assuming the brain
+has content with entity references and dated markdown).
+
+**If it's zero on a brain with imported content:** Run the backfill.
+
+```bash
+gbrain extract links --source db --dry-run | head -5    # preview
+gbrain extract links --source db                         # commit
+gbrain extract timeline --source db
+gbrain stats                                             # confirm > 0
+```
+
+**Bonus check** — graph traversal works:
+
+```bash
+# Pick any well-connected slug from your brain
+gbrain graph-query people/<some-person-slug> --depth 2
+```
+
+**Expected:** Indented tree of typed edges (`--attended-->`, `--works_at-->`, etc.).
+If the slug has no inbound or outbound links, try a different one or run extract
+again.
+
+**If extract finds nothing:** Your pages may not use entity-reference syntax. The
+extractor matches `[Name](people/slug)`, `[Name](../people/slug.md)`, and bare
+`people/slug` references. If your brain uses a different format, the auto-link
+heuristics won't find them — file an issue with a sample page.
+
+---
+
+## 8. JSONB Frontmatter Integrity (v0.12.2)
+
+Postgres-backed brains created before v0.12.2 had double-encoded JSONB columns
+(`frontmatter->>'key'` returned NULL, GIN indexes were inert). `gbrain upgrade`
+runs `gbrain repair-jsonb` automatically via the `v0_12_2` orchestrator.
+Verify the repair succeeded.
+
+**Command:**
+
+```bash
+gbrain repair-jsonb --dry-run --json
+```
+
+**Expected:** `totalRepaired: 0` across all 5 columns (`pages.frontmatter`,
+`raw_data.data`, `ingest_log.pages_updated`, `files.metadata`,
+`page_versions.frontmatter`). A zero count means every row is properly-typed
+JSON objects, not string-encoded JSON.
+
+**If the count is > 0:** The repair didn't run or was interrupted. Re-run
+without `--dry-run`:
+
+```bash
+gbrain repair-jsonb
+```
+
+Idempotent. PGLite brains always report 0 (unaffected by the original bug).
+
+**Bonus check** — frontmatter-keyed queries actually resolve:
+
+```bash
+gbrain call list_pages '{"frontmatterKey": "type", "frontmatterValue": "person"}'
+```
+
+If this returns rows on a brain with person pages, the JSONB path is healthy.
+
+---
+
 ## Quick Verification (all checks in one pass)
 
 ```bash
@@ -203,7 +281,13 @@ gbrain embed --stale
 
 # 6. Auto-update
 gbrain check-update --json
+
+# 7. Knowledge graph populated (links + timeline > 0)
+gbrain stats | grep -E 'links|timeline'
+
+# 8. JSONB integrity (v0.12.2 — Postgres only, PGLite always 0)
+gbrain repair-jsonb --dry-run --json
 ```
 
-If all six return successfully, the installation is healthy. For the full
+If all eight return successfully, the installation is healthy. For the full
 end-to-end sync test (4c), push a real change and verify it appears in search.

docs/UPGRADING_DOWNSTREAM_AGENTS.md

@@ -0,0 +1,540 @@
+# Upgrading Downstream Agents
+
+GBrain ships skills in `skills/`. Downstream agents (custom OpenClaw deployments,
+agent forks of any kind) often **copy** these skill files into their own workspace and
+diverge over time — adding agent-specific phases, removing irrelevant ones, tightening
+language. Once that happens, gbrain can't push updates to those forks. The agent has
+to apply the diffs by hand.
+
+This doc lists the exact diffs each downstream agent needs to apply when upgrading.
+Cross-reference against your fork's local skill files.
+
+## Why this exists
+
+`gbrain upgrade` ships the new binary. `gbrain post-upgrade [--execute --yes]` runs
+the schema migrations and backfills the data. But the **skill files themselves**
+that tell the agent how to behave — those are user-owned. If your `~/git/<your-agent>/workspace/skills/brain-ops/SKILL.md`
+says `# Based on gbrain v0.10.0` at the top, it doesn't know about v0.12.0 features.
+
+The agent will keep manually calling `gbrain link` after every `put_page` (now redundant —
+auto-link does it), miss out on `gbrain graph-query` for relationship questions, and
+not know to backfill the structured timeline.
+
+## How to apply
+
+1. Identify your forked skill files. Typically at `~/git/<your-agent>/workspace/skills/` or wherever your agent's skill directory lives.
+2. For each skill listed below, find the matching phase/section in your fork.
+3. Apply the diff (paste the new block in the indicated location).
+4. Update the version banner at the top of your fork (`# Based on gbrain v0.12.0`).
+5. Verify: ask the agent to write a test page and confirm the response includes
+   `auto_links: { created, removed, errors }`.
+
+Total time: ~10 minutes for all four skills.
+
+---
+
+## 1. brain-ops/SKILL.md
+
+**Where:** Insert a new `### Phase 2.5` section immediately after `### Phase 2: On Every Inbound Signal`.
+
+**Why:** Phase 2.5 declares that auto-link runs automatically. Without this, the
+agent's mental model says it must call `gbrain link` after every `put_page`, which
+is now redundant and can cause double-add warnings.
+
+```markdown
+### Phase 2.5: Structured Graph Updates (automatic)
+
+Every `put_page` call automatically extracts entity references and writes them
+to the graph (`links` table) with inferred relationship types. Stale links
+(refs no longer in the page text) are removed in the same call. This is
+"auto-link" reconciliation.
+
+- No manual `add_link` calls needed for ordinary page writes.
+- Inferred link types: `attended` (meeting -> person), `works_at`, `invested_in`,
+  `founded`, `advises`, `source` (frontmatter), `mentions` (default).
+- The `put_page` MCP response includes `auto_links: { created, removed, errors }`
+  so the agent can verify outcomes.
+- To disable: `gbrain config set auto_link false`. Default is on.
+- Timeline entries with specific dates still need explicit `gbrain timeline-add`
+  (or batch via `gbrain extract timeline --source db`).
+```
+
+**Also update the Iron Law section.** If your fork still says "Back-links maintained
+on every brain write (Iron Law)" without qualification, append:
+
+```markdown
+**v0.12.0 update:** Auto-link satisfies the Iron Law for entity-reference links
+on every `put_page`. The agent's Iron Law obligation is now: include the
+entity reference in the page content (e.g., `[Alice](people/alice)`); auto-link
+handles the structured row. Manual `add_link` calls are reserved for
+relationships you can't express in markdown content.
+```
+
+---
+
+## 2. meeting-ingestion/SKILL.md
+
+**Where:** Append to the end of `### Phase 3: Attendee enrichment`.
+
+**Why:** Eliminates redundant `gbrain link` calls per attendee (auto-link handles them
+when the meeting page references attendees as `[Name](people/slug)`).
+
+```markdown
+**Note (v0.12.0):** Once the meeting page is written via `gbrain put`, the
+auto-link post-hook automatically creates `attended` links from the meeting
+to each attendee whose page is referenced as `[Name](people/slug)`. You don't
+need to call `gbrain link` for attendees. You DO still need `gbrain timeline-add`
+for dated events (auto-link only handles links, not timeline entries).
+```
+
+**Where:** In `### Phase 4: Entity propagation`, the line "Back-link from entity page
+to meeting page" can be replaced with:
+
+```markdown
+4. Entity references in the meeting page body auto-create the link via auto-link.
+   For incoming references on the entity page (entity page → meeting page), edit
+   the entity page to mention the meeting and `put_page` it — auto-link handles
+   the rest.
+```
+
+---
+
+## 3. signal-detector/SKILL.md
+
+**Where:** Append to the end of `### Phase 2: Entity Detection`.
+
+**Why:** Same logic as brain-ops — eliminates manual `gbrain link` after writing
+originals/ideas pages that reference people or companies.
+
+```markdown
+**Auto-link (v0.12.0):** When you write/update an originals or ideas page that
+references a person or company, the auto-link post-hook on `put_page`
+automatically creates the link from the new page to that entity. You don't
+need to call `gbrain link` manually. Timeline entries still need explicit calls.
+```
+
+---
+
+## 4. enrich/SKILL.md
+
+**Where:** Replace `### Step 7: Cross-reference` with the v0.12.0 version.
+
+**Why:** Step 7 used to be primarily about creating links between related entity
+pages. With auto-link, that's automatic. Step 7 is now about content updates,
+not link creation.
+
+Old (delete):
+```markdown
+### Step 7: Cross-reference
+
+- Update company pages from person enrichment (and vice versa)
+- Update related project/deal pages if relevant context surfaced
+- Check index files if the brain uses them
+- Add back-links manually via `gbrain link` for any new entity references
+```
+
+New (paste):
+```markdown
+### Step 7: Cross-reference
+
+- Update company pages from person enrichment (and vice versa)
+- Update related project/deal pages if relevant context surfaced
+- Check index files if the brain uses them
+
+**Note (v0.12.0):** Links between brain pages are auto-created on every
+`put_page` call (auto-link post-hook). Step 7 focuses on content
+cross-references (updating related pages' compiled truth with new signal
+from this enrichment), not on creating links. Verify via the `auto_links`
+field in the put_page response (`{ created, removed, errors }`).
+Timeline entries still need explicit `gbrain timeline-add` calls.
+```
+
+---
+
+## After all four diffs are applied
+
+1. **Bump the version banner** at the top of each forked file:
+   ```
+   # Based on gbrain v0.12.0 skills/<skill-name>, extended with <your-agent>-specific config
+   ```
+
+2. **Run the v0.12.0 backfill** (this populates the graph for your existing brain):
+   ```bash
+   gbrain post-upgrade
+   ```
+   The v0.12.0 release wires post-upgrade to call `apply-migrations --yes`
+   automatically, which runs the v0_12_0 orchestrator (schema → config check →
+   `extract links --source db` → `extract timeline --source db` → verify).
+   Idempotent; cheap when nothing is pending.
+
+3. **Verify auto-link works:** ask the agent to write a test page that references
+   `[Some Person](people/some-person)`. Confirm the put_page response includes
+   `auto_links: { created: 1, removed: 0, errors: 0 }`.
+
+4. **Verify graph traversal works:**
+   ```bash
+   gbrain graph-query people/some-well-connected-person --depth 2
+   ```
+   Should return an indented tree of typed edges.
+
+---
+
+## v0.12.2 hotfix (data-correctness, no skill edits)
+
+v0.12.2 is a Postgres data-correctness hotfix. No forked skill files need to
+change — the skill contracts are unchanged. But you DO need to run the migration,
+and you should know about one behavior change in markdown parsing.
+
+### 1. Run the migration (Postgres-backed brains)
+
+```bash
+gbrain upgrade
+```
+
+The `v0_12_2` orchestrator runs `gbrain repair-jsonb` automatically. It rewrites
+rows where `jsonb_typeof = 'string'` across `pages.frontmatter`, `raw_data.data`,
+`ingest_log.pages_updated`, `files.metadata`, and `page_versions.frontmatter`.
+Idempotent, safe to re-run. PGLite brains no-op cleanly.
+
+Verify after upgrade:
+
+```bash
+gbrain repair-jsonb --dry-run --json    # expect totalRepaired: 0
+```
+
+### 2. Recover any truncated wiki articles
+
+If your brain imported wiki-style markdown before v0.12.2, some pages were
+silently truncated (any standalone `---` in body content was treated as a
+timeline separator). Re-import from source:
+
+```bash
+gbrain sync --full
+```
+
+The new `splitBody` rebuilds `compiled_truth` correctly.
+
+### 3. Know the splitBody contract going forward
+
+`splitBody` now requires an explicit timeline sentinel. Recognized markers
+(priority order):
+
+1. `<!-- timeline -->` (preferred — what `serializeMarkdown` emits)
+2. `--- timeline ---` (decorated separator)
+3. `---` directly before `## Timeline` or `## History` heading (backward-compat)
+
+A bare `---` in body text is now a markdown horizontal rule, not a timeline
+separator. If your agent writes pages with a bare `---` delimiter, migrate to
+`<!-- timeline -->` — the `serializeMarkdown` helper already does this.
+
+### 4. Wiki subtypes now auto-typed
+
+`inferType` now auto-detects five additional directory patterns as their own
+page types (previously they all defaulted to `concept`):
+
+| Path pattern           | New type       |
+|------------------------|----------------|
+| `/wiki/analysis/`      | `analysis`     |
+| `/wiki/guides/`        | `guide`        |
+| `/wiki/hardware/`      | `hardware`     |
+| `/wiki/architecture/`  | `architecture` |
+| `/writing/`            | `writing`      |
+
+If your skills or queries filter by `type=concept` and expect wiki content in
+that bucket, update them to include the new types.
+
+---
+
+## v0.13.0 — Frontmatter Relationship Indexing
+
+**Verdict: no action required for most skills.** v0.13 projects YAML frontmatter fields into the graph as typed edges. The ingestion API is unchanged — keep calling `put_page` with frontmatter the way you do today; the graph auto-populates behind the scenes.
+
+Three skills get an optional new phase if you want to consume the new `auto_links.unresolved` response field. Without this, unresolvable frontmatter names silently skip (same as v0.12 behavior).
+
+### 1. meeting-ingestion/SKILL.md (optional)
+
+**Where:** Add a new section after "Phase 3: Write Meeting Page".
+
+```markdown
+### Phase 3.5: Check for unresolved attendees (v0.13+)
+
+After `put_page`, inspect `response.auto_links.unresolved` — an array of frontmatter
+references that did not resolve to existing pages. For meetings, this usually means
+attendees you haven't created a person page for yet.
+
+If `unresolved.length > 0`:
+- Option 1 (create pages now): trigger an enrichment pass to build the missing people pages.
+- Option 2 (defer): log the unresolved names to the enrichment queue for later.
+- Option 3 (accept the gap): the attendee edge will not be created until a page exists.
+  Re-running `gbrain extract links --source db --include-frontmatter` after creating
+  the page fills in the missing edges.
+```
+
+### 2. enrich/SKILL.md (optional)
+
+**Where:** Add to the enrichment trigger list.
+
+```markdown
+### Drain unresolved frontmatter names (v0.13+)
+
+If any `put_page` response includes `auto_links.unresolved` entries, the enrichment
+tier should pick up those (field, name) pairs and try to create the missing entity
+pages. Example flow:
+
+1. signal-detector captures a meeting with `attendees: [Alice Known, Unknown Person]`
+2. put_page returns `auto_links.unresolved = [{field: 'attendees', name: 'Unknown Person'}]`
+3. enrichment tier consumes `Unknown Person` → web search → creates `people/unknown-person.md`
+4. The next put_page (or a backfill run) wires up the `attended` edge automatically
+```
+
+### 3. idea-ingest/SKILL.md (optional)
+
+**Where:** Same pattern as meeting-ingestion — check `auto_links.unresolved` after `put_page`, route names to enrichment.
+
+### Unchanged skills (no diffs needed)
+
+- **brain-ops/SKILL.md** — auto-link mechanics are internal; the write path stays the same.
+- **signal-detector/SKILL.md** — signal capture path unchanged.
+- **query/SKILL.md** — `traverse_graph` now returns richer results automatically.
+- **daily-task-manager/SKILL.md**, **briefing/SKILL.md**, **citation-fixer/SKILL.md**, **media-ingest/SKILL.md** — unchanged.
+
+### New edge types you can filter in graph queries
+
+v0.13 edges carry new `link_type` values. If your fork has graph-query skills that filter by type, these are now available:
+
+- `works_at` (person → company) — from `company:`, `companies:`, or `key_people:`
+- `founded` (person → company) — from `founded:`
+- `invested_in` (investor → deal/company) — from `investors:` or `lead:`
+- `led_round` (lead → deal) — from `lead:`
+- `yc_partner` (partner → company) — from `partner:`
+- `attended` (person → meeting) — from `attendees:`
+- `discussed_in` (source → page) — from `sources:`
+- `source` (page → source) — from `source:`
+- `related_to` (page → target) — from `related:` or `see_also:`
+
+### Migration timing
+
+`gbrain upgrade` takes 2-5 min on a 46K-page brain (one-time). Runs out-of-process via `gbrain post-upgrade`. If your agent holds a DB connection during the upgrade, reconnect after; otherwise keep serving.
+
+### Type normalization NOT in v0.13
+
+Legacy rows with `link_type='attendee'` or `link_type='mention'` coexist with new `'attended'` / `'mentions'` rows. Your queries filtering on old type names keep working. A separate opt-in `gbrain normalize-types` command in v0.14 handles the rename.
+## v0.14.0 shell jobs (optional adoption, no skill edits)
+
+Adds a `shell` job type to Minions so deterministic cron scripts (API fetch, token
+refresh, scrape + write) move off the LLM gateway. Zero tokens per fire. ~60%
+gateway CPU headroom at typical scale. Feature is **off by default**, existing
+installs keep running exactly as they did before. Nothing breaks.
+
+To adopt, follow `skills/migrations/v0.14.0.md`. The short version:
+
+1. Set `GBRAIN_ALLOW_SHELL_JOBS=1` on the worker process, then `gbrain jobs work`
+   (Postgres). On PGLite, every crontab invocation uses `--follow` for inline
+   execution; no persistent worker.
+2. Classify each of your host's cron entries: LLM-requiring (keep on gateway) vs
+   deterministic (candidate for shell). Typical splits:
+   - **Deterministic → shell:** `ycli-token-refresh`, `x-oauth2-refresh`,
+     `x-garrytan-unified`, `calendar-sync-to-brain`, `github-pulse`,
+     `frameio-scan`, `flight-tracker`, `x-raw-json-backfill`.
+   - **LLM-requiring → stay:** `social-radar`, `content-ideas`, `adversary-vacuum`,
+     `ea-inbox-sweep`, `morning-briefing`, `brain-maintenance`.
+3. For each deterministic cron, rewrite as:
+   ```cron
+   3 13,16,19,22,1,4,7,10 * * * \
+     gbrain jobs submit shell \
+       --params '{"cmd":"node scripts/your-script.mjs","cwd":"/data/.openclaw/workspace"}' \
+       --max-attempts 3 --timeout-ms 300000
+   ```
+4. Watch `gbrain jobs get <id>` for exit_code / stdout_tail / stderr_tail on each
+   fire. Compare against pre-migration behavior before approving the next batch.
+
+**No skill edits required.** The handler runs worker-side; skill files don't
+change. If your host exposed custom handlers via the plugin contract (v0.11.0),
+they still work the same way.
+
+Iron rule: **never auto-rewrite the operator's crontab.** Every rewrite is
+per-cron, human-approved, with a diff. If you want automation later, the
+upcoming `gbrain crontab-to-minions <file>` helper is P1 in TODOS.
+
+---
+
+## v0.16.0: durable agent runtime
+
+v0.15 ships `gbrain agent run` / `gbrain agent logs`, a new `subagent` handler
+type in Minions, and a plugin contract for host-repo subagent defs. None of the
+existing skills need surgery. The question for downstream agents is *how* to
+adopt the new runtime, not how to patch around a breaking change.
+
+### 1. Run a worker with an Anthropic key
+
+The subagent handlers (`subagent` and `subagent_aggregator`) are always
+registered on the worker. No separate opt-in flag — `ANTHROPIC_API_KEY` is
+the natural cost gate (no key, the SDK call fails on the first turn), and
+who-can-submit is already protected (`PROTECTED_JOB_NAMES` + trusted-submit:
+MCP callers get `permission_denied`; only `gbrain agent run` can insert
+these rows).
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-... gbrain jobs work
+```
+
+Worker startup prints:
+
+```
+[minion worker] subagent handlers enabled
+```
+
+### 2. Ship your subagents as a plugin (OpenClaw + similar)
+
+Move your custom subagent definitions out of your gbrain fork and into your own
+repo as a plugin. Concretely:
+
+```
+~/<your-agent>/gbrain-plugin/
+├── gbrain.plugin.json
+└── subagents/
+    ├── meeting-ingestion.md
+    ├── signal-detector.md
+    └── daily-task-prep.md
+```
+
+`gbrain.plugin.json`:
+
+```json
+{
+  "name": "your-openclaw",
+  "version": "2026.4.20",
+  "plugin_version": "gbrain-plugin-v1"
+}
+```
+
+Each `subagents/*.md` is a plain-text agent definition — YAML frontmatter +
+body-as-system-prompt. Recognized frontmatter fields: `name`, `model`,
+`max_turns`, `allowed_tools` (must subset the derived brain-tool registry).
+
+Turn it on:
+
+```bash
+export GBRAIN_PLUGIN_PATH="$HOME/<your-agent>/gbrain-plugin"
+```
+
+Worker startup prints `[plugin-loader] loaded '<name>' v<ver> (N subagents)`
+per plugin; any rejection (bad manifest, unknown tool in `allowed_tools`,
+version mismatch) shows up as a loud warning at startup, not a silent dispatch-
+time failure. See `docs/guides/plugin-authors.md` for the full contract.
+
+### 3. Replace ephemeral subagent runs with durable ones
+
+If your agent currently spawns ephemeral subagents (OpenClaw `Agent()`, ad-hoc
+Anthropic API calls, etc.) for work that should survive crashes, sleeps, or
+worker restarts, migrate those to `gbrain agent run`. The durability is free:
+
+```bash
+gbrain agent run "analyze my last 50 journal pages for recurring themes" \
+  --subagent-def analyzer --fanout-manifest manifests/journal-pages.json
+```
+
+Every turn persists to `subagent_messages`, every tool call is a two-phase
+ledger, and `gbrain agent logs <job>` shows where it died + what the last
+successful call returned. No more "re-run from scratch because the session
+context evaporated."
+
+### 4. `put_page` from subagents writes under an agent namespace
+
+If you adopted the v0.15 subagent runtime, note that `put_page` calls
+originating from a subagent's tool dispatch MUST target
+`wiki/agents/<subagent_id>/...`. The schema shown to the model enforces this
+on first try; a server-side fail-closed check rejects anything else. This
+does NOT affect your skill files, CLI put_page calls, or MCP put_page —
+only tool-dispatched writes from inside an LLM loop.
+
+Aggregation output (the final "here's what all N children found" brain page)
+goes via a separate trusted CLI path, not through a subagent tool call, so
+it can write anywhere you want.
+
+Iron rule: **never grant an agent write access beyond its namespace**. The
+server-side check exists because dispatcher bugs happen; treat it as defense
+in depth, not the primary boundary.
+
+---
+
+## v0.22.4 — frontmatter-guard adoption
+
+### 1. Stop hand-rolling frontmatter validators
+
+If your fork has scripts that call `js-yaml` directly to validate brain page
+frontmatter, replace them with `gbrain frontmatter validate` calls. The CLI
+covers the seven canonical error classes and ships a `--json` envelope that's
+stable across releases.
+
+```diff
+- # Custom validator script
+- node scripts/validate-frontmatter.mjs <path>
++ gbrain frontmatter validate <path> --json
+```
+
+For consumers that need the validator inside another script, import from
+gbrain's `markdown` export instead of duplicating logic:
+
+```ts
+import { parseMarkdown } from 'gbrain/markdown';
+
+const parsed = parseMarkdown(content, filePath, { validate: true, expectedSlug });
+for (const err of parsed.errors ?? []) {
+  // err.code: MISSING_OPEN | MISSING_CLOSE | YAML_PARSE | SLUG_MISMATCH |
+  //           NULL_BYTES | NESTED_QUOTES | EMPTY_FRONTMATTER
+}
+```
+
+### 2. Drop any references to `lib/brain-writer.mjs`
+
+If your fork's skills or scripts referenced an aspirational
+`lib/brain-writer.mjs` (it never shipped — the spec was in PR #392 and never
+landed), replace those references with the gbrain CLI. The `frontmatter-guard`
+skill lives at `skills/frontmatter-guard/SKILL.md` and points at
+`gbrain frontmatter validate` / `audit` / `install-hook`.
+
+### 3. Wire the doctor subcheck into your health pipeline
+
+`gbrain doctor` now reports `frontmatter_integrity` automatically. If your
+fork has a custom health pipeline (e.g. a daily Slack post about brain
+health), pull from `gbrain doctor --json` and surface the
+`frontmatter_integrity` row counts.
+
+### 4. (Optional) Install the pre-commit hook on brain repos
+
+For sources backed by git, the v0.22.4 install-hook helper drops a
+pre-commit script that blocks commits with malformed frontmatter:
+
+```bash
+gbrain frontmatter install-hook
+```
+
+Skip this if your brain isn't a git repo or if your downstream agent already
+enforces validation at write time. See `docs/integrations/pre-commit.md` for
+the full recipe.
+
+### 5. Migration ergonomics — read pending-host-work.jsonl
+
+After `gbrain apply-migrations --yes` runs the v0.22.4 audit, your agent
+should read `~/.gbrain/migrations/pending-host-work.jsonl` (filter to
+`migration === "0.22.4"`) and walk each entry's `command` field. Each entry
+points to a per-source `gbrain frontmatter validate <source_path> --fix`
+command — surface counts to the user, get explicit consent, then run.
+
+The migration is **audit-only**. It never mutates brain content during
+`apply-migrations`. Your agent runs the fix command with user consent.
+
+---
+
+## Future versions
+
+When gbrain ships a new version, this doc will be updated with the diffs for that
+version. Each new version appends a section; old sections stay so you can catch up
+multiple versions at once.
+
+To check what your fork is missing:
+```bash
+diff <(grep -A3 "Based on gbrain" ~/<your-fork>/skills/brain-ops/SKILL.md) \
+     <(grep "v[0-9]" ~/gbrain/skills/migrations/ | tail -3)
+```

docs/architecture/brains-and-sources.md

@@ -0,0 +1,242 @@
+# Brains and Sources — the mental model
+
+GBrain has two orthogonal axes for organizing knowledge. Users and agents both
+need to understand both of them, or queries misroute silently.
+
+**TL;DR:**
+- A **brain** is a database. You can have many.
+- A **source** is a named repo of content *inside* a brain. One brain can hold many.
+- `--brain <id>` picks WHICH DATABASE.
+- `--source <id>` picks WHICH REPO WITHIN that database.
+- They're independent. You can target any combination.
+
+---
+
+## The two axes
+
+### Brains (the DB axis)
+
+A **brain** is one database — PGLite file, self-hosted Postgres, or Supabase.
+Each brain has:
+- Its own `pages` table, `chunks` table, `embeddings`, etc.
+- Its own OAuth surface if served over HTTP MCP (v0.19+, PR 2).
+- Its own separate lifecycle, backup, access control.
+
+Brains are enumerated by:
+- **host** — your default brain, configured in `~/.gbrain/config.json`.
+- **mounts** — additional brains registered in `~/.gbrain/mounts.json` via
+  `gbrain mounts add <id>` (v0.19+).
+
+Routing: `--brain <id>`, `GBRAIN_BRAIN_ID`, `.gbrain-mount` dotfile, or
+longest-path match against registered mount paths. Falls back to `host`.
+
+### Sources (the repo axis, v0.18.0+)
+
+A **source** is a named content repo *inside* one brain. Every `pages` row
+carries a `source_id`. Slugs are unique per source, not globally.
+
+Example: in one brain, the slug `topics/ai` can exist under `source=wiki`
+AND under `source=gstack` — they're different pages.
+
+Routing: `--source <id>`, `GBRAIN_SOURCE`, `.gbrain-source` dotfile, or
+registered `local_path` match in the `sources` table.
+
+### When does each axis move?
+
+| You want to | Adjust |
+|---|---|
+| Work in a different repo within the same brain (wiki → gstack notes) | `--source` |
+| Query a team-published brain that isn't yours | `--brain` |
+| Isolate a topic so it never leaks into personal search | `--source` with `federated=false` |
+| Share a brain with teammates | `--brain` (mount the team brain) |
+| Add a new repo to your personal brain | `--source` via `gbrain sources add` |
+| Add a team brain | `--brain` via `gbrain mounts add` |
+
+**Rule of thumb:** if the data owner changes, it's a brain boundary. If the
+data owner stays the same but the topic/repo changes, it's a source boundary.
+
+---
+
+## Topology: a single-person developer
+
+Simplest case. One brain, one source.
+
+```
+┌─────────────────────────────────────────┐
+│  host brain (~/.gbrain)                 │
+│  ├── source: default (federated=true)   │
+│  │   └── all pages                      │
+└─────────────────────────────────────────┘
+```
+
+`gbrain query "retry budgets"` finds everything. No `--brain`, no `--source`
+needed.
+
+---
+
+## Topology: a personal brain with multiple repos
+
+You maintain several codebases or writing streams. Each is its own source
+inside one brain. Cross-source search is on by default so a query about
+"caching" returns hits from every repo.
+
+```
+┌──────────────────────────────────────────────┐
+│  host brain (~/.gbrain)                      │
+│  ├── source: wiki      (federated=true)      │
+│  │   └── personal notes, people, companies   │
+│  ├── source: gstack    (federated=true)      │
+│  │   └── gstack plans, learnings             │
+│  ├── source: openclaw  (federated=true)      │
+│  │   └── openclaw docs, memos                │
+│  └── source: essays    (federated=false)     │
+│      └── draft essays, isolated on purpose   │
+└──────────────────────────────────────────────┘
+```
+
+Inside `~/openclaw/` the `.gbrain-source` dotfile pins every command to
+`source=openclaw`. Inside `~/gstack/` the dotfile pins to `source=gstack`.
+Everything still targets one DB.
+
+Use this topology when:
+- You own all the content.
+- You want cross-repo search to just work.
+- You don't need to share any of it with someone who isn't you.
+
+---
+
+## Topology: personal brain + one team brain
+
+You're on a team that publishes a shared brain. Your personal brain stays
+as-is; you mount the team brain alongside it.
+
+```
+┌──────────────────────────────────────────────┐
+│  host brain (~/.gbrain)  — YOUR personal DB  │
+│  ├── source: wiki                            │
+│  ├── source: gstack                          │
+│  └── ...                                     │
+└──────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────┐
+│  mount: media-team                           │
+│  path:   ~/team-brains/media                 │
+│  engine: postgres (team's Supabase)          │
+│  └── sources: wiki, raw, enriched            │
+└──────────────────────────────────────────────┘
+```
+
+`gbrain query "X"` (no flags) → runs against host (your personal brain).
+`gbrain query "X" --brain media-team` → runs against the team's DB.
+Inside `~/team-brains/media/` a `.gbrain-mount` dotfile pins brain to
+`media-team` automatically.
+
+Use this topology when:
+- You're on a team and someone publishes a brain the team subscribes to.
+- You need data isolation between work and personal.
+- Different teams/orgs own different brains.
+
+---
+
+## Topology: a CEO-class user with multiple team memberships
+
+You're senior enough to sit across multiple teams. You maintain your personal
+brain (with N sources inside) AND mount several work team brains. Each team
+brain is itself a multi-source brain in the v0.18.0 sense — organized
+internally however the team owner chose.
+
+```
+┌──────────────────────────────────────────────┐
+│  host brain — YOUR personal DB               │
+│  ├── source: wiki                            │
+│  ├── source: essays                          │
+│  ├── source: gstack                          │
+│  └── source: openclaw                        │
+└──────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────┐
+│  mount: media-team (your media team's brain) │
+│  └── sources: wiki, pipeline, enriched       │
+└──────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────┐
+│  mount: policy-team (your policy team's)     │
+│  └── sources: wiki, research, letters        │
+└──────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────┐
+│  mount: portfolio (another team's)           │
+│  └── sources: companies, deals, diligence    │
+└──────────────────────────────────────────────┘
+```
+
+Inside each team's checkout, a `.gbrain-mount` dotfile pins the brain. Inside
+a specific subdirectory, a `.gbrain-source` dotfile pins the source. So `cd
+~/team-brains/policy/research && gbrain query "X"` targets
+`brain=policy-team, source=research` with zero flags.
+
+Use this topology when:
+- You cross-cut multiple teams.
+- Each team owns its own brain with its own access policy.
+- You need latent-space federation (agent decides when to query across
+  brains), not SQL federation.
+
+Cross-brain queries are **not deterministic** in v0.19. The agent sees the
+brain list and re-queries as needed. That's the feature — it keeps debugging
+sane and access control clean.
+
+---
+
+## Resolution precedence (one page to remember)
+
+```
+WHICH BRAIN (DB)?                    WHICH SOURCE (repo in DB)?
+ 1. --brain <id>                      1. --source <id>
+ 2. GBRAIN_BRAIN_ID env               2. GBRAIN_SOURCE env
+ 3. .gbrain-mount dotfile             3. .gbrain-source dotfile
+ 4. longest-prefix mount path match   4. longest-prefix source path match
+ 5. (reserved: brains.default v2)     5. sources.default config
+ 6. fallback: 'host'                  6. fallback: 'default'
+```
+
+Both axes follow the same layered pattern on purpose. If you know one, you
+know the other.
+
+---
+
+## For agents reading this
+
+- Default assumption when the user asks a question: start in the current
+  brain (resolved via the precedence above). Don't jump brains without a
+  reason.
+- If the user asks a question that crosses topic areas a team might own
+  (e.g. "what did Team X decide last week?"), the right move is to *query
+  the team's brain explicitly* rather than searching host with "team x".
+- Cross-brain federation is YOUR JOB, not the DB's. You have the brain list
+  (`gbrain mounts list`). You decide when to fan out. You synthesize
+  findings. You cite `brain:source:slug`.
+- When writing a page, respect the brain boundary. A fact about a team's
+  work belongs in the team's brain, not in the user's personal brain. Ask
+  before writing cross-brain.
+- See `skills/conventions/brain-routing.md` for the full decision table.
+
+## For users reading this
+
+- **Default path:** set up your personal brain (`gbrain init`), add a source
+  per repo you care about (`gbrain sources add gstack --path ~/gstack`).
+  You'll almost never need `--brain`.
+- **When a team publishes a brain:** `gbrain mounts add <team-id> --path
+  <clone> --db-url <url>` and the `.gbrain-mount` dotfile in that checkout
+  routes queries there automatically.
+- **When you are the CEO-class user with multiple team memberships:** mount
+  each team brain. Trust the resolver — inside a team's directory the
+  dotfile picks the brain, inside a subdirectory the dotfile picks the
+  source. The flags are for when you want to query across the boundary
+  deliberately.
+
+## Further reading
+
+- v0.18.0 CHANGELOG — introduced `sources` primitive.
+- v0.19.0 CHANGELOG (TBD after PR 0+1+2 ship) — introduces `mounts`.
+- `docs/mounts/publishing-a-team-brain.md` (PR 2) — how to be the brain
+  publisher, not just the subscriber.

docs/benchmarks/2026-04-14-search-quality.md

@@ -1,167 +0,0 @@
-# Search Quality Benchmark — PR #64
-
-**Date:** 2026-04-14
-**Branch:** garrytan/search-quality-boost
-**Inspired by:** Ramp Labs' "Latent Briefing" paper (April 2026)
-
-## What this PR does
-
-GBrain stores knowledge in brain pages. Each page has two sections: **compiled truth**
-(your distilled assessment of a person, company, or concept) and **timeline** (dated
-entries like meeting notes, announcements, funding rounds).
-
-Before this PR, search treated both sections equally. Ask "who is Alice Chen?" and you
-might get a meeting note from March instead of the actual assessment. Ask "when did we
-last meet Alice?" and you might get the assessment instead of the date.
-
-This PR teaches search to understand the difference. It picks the right section based
-on what you're asking.
-
-## How we test it
-
-We built a synthetic brain with **29 fictional pages** and **58 chunks** (2 per page:
-one compiled truth, one timeline). The pages span 10 people, 10 companies, and 9
-concept pages across topics like AI, fintech, climate, crypto, robotics, education,
-biotech, and design.
-
-The embeddings share dimensions to simulate real-world overlap. "AI" shows up in
-health pages, education pages, design pages, and robotics pages. A query about "AI
-companies" has to sort through 5+ relevant pages, not just find one obvious match.
-
-We run **20 queries** with hand-labeled ground truth:
-- 11 entity queries ("who is X?", "what does Y do?", "tell me about Z")
-- 7 temporal queries ("when did we last meet?", "recent updates", "what launched?")
-- 1 negative control (irrelevant topic, no matches expected)
-- 1 ambiguous query (could go either way)
-
-Each query has **graded relevance**: the primary answer gets grade 3, related pages get
-2 or 1. A query about climate investing has 4 relevant pages ranked by importance.
-
-We compare three configurations:
-- **A. Baseline** — how search worked before this PR
-- **B. Boost only** — compiled truth chunks get a 2x score multiplier (the naive approach)
-- **C. Boost + Intent** — the full PR: boost + intent classifier that auto-detects query type
-
-## Results: finding the right page
-
-These are standard information retrieval metrics. They answer: "did search find the
-right page?"
-
-| Metric | What it measures | A. Before | C. After | Change |
-|--------|-----------------|-----------|----------|--------|
-| **P@1** | Is the #1 result relevant? | 94.7% | 94.7% | same |
-| **MRR** | How far down is the first relevant result? | 0.974 | 0.974 | same |
-| **nDCG@5** | Are the top 5 results in the right order? | 1.191 | 1.069 | -10% |
-
-Page-level retrieval is roughly the same. The right page was already being found. This
-is not where the improvement lives.
-
-## Results: finding the right chunk (the actual improvement)
-
-These metrics answer: "did search find the right SECTION of the right page?" This is
-what matters when an agent reads search results to answer a question.
-
-| Metric | What it measures | A. Before | C. After | Change |
-|--------|-----------------|-----------|----------|--------|
-| **Source accuracy** | Is the top chunk the right type for this query? (assessment for "who is X?", timeline for "when did we meet?") | 89.5% | 89.5% | same |
-| **CT-first rate** | For entity lookups, does the assessment show up before timeline noise? | 100% | 100% | same |
-| **Timeline accessible** | For temporal queries, can you actually find the dates? | 100% | 100% | same |
-| **Unique pages** | How many different pages appear in top 10? (more = broader context) | 7.2 | **8.7** | **+21%** |
-| **Compiled truth ratio** | What % of returned chunks are assessments vs timeline noise? | 51.6% | **66.8%** | **+29%** |
-
-Two big improvements:
-
-1. **21% more page coverage.** The agent sees 8.7 unique pages per query instead of 7.2.
-   When you ask "AI companies building real products", you get results from MindBridge,
-   EduStack, PixelCraft, GenomeAI, AND the AI-first thesis page. Before, some of those
-   were crowded out.
-
-2. **29% more signal in results.** Two thirds of returned chunks are now compiled truth
-   (assessments) instead of roughly half. The agent reads more distilled knowledge and
-   less timeline noise.
-
-## Why the boost alone isn't enough
-
-We also tested configuration B: the 2x compiled truth boost without the intent classifier.
-This is the naive version that just says "rank assessments higher, always."
-
-| What broke | Before | Boost only | With intent |
-|-----------|--------|------------|-------------|
-| Source accuracy | 89.5% | **63.2%** | 89.5% |
-| Timeline accessible | 100% | **71.4%** | 100% |
-| P@1 | 94.7% | **89.5%** | 94.7% |
-
-The boost forces compiled truth to the top even when timeline IS the right answer. Ask
-"what launched this year?" and the boost pushes assessment chunks above the actual launch
-dates. The source accuracy drops from 89.5% to 63.2%.
-
-The **intent classifier** fixes this. It reads the query text (zero latency, no LLM call)
-and detects whether you're asking an entity question or a temporal question:
-
-- "Who is Alice Chen?" → entity → boost compiled truth
-- "When did we last meet Alice?" → temporal → skip boost, show timeline
-- "Recent funding rounds" → temporal → skip boost, show dates
-- "AI companies building real products" → general → moderate boost
-
-This recovers all the regressions while keeping the improvements.
-
-## Per-query results
-
-Every query, every configuration. "Src" column shows which chunk type ranked first.
-
-| Query | Expected | Before src | After src | Before pages | After pages |
-|-------|----------|-----------|-----------|-------------|-------------|
-| Who is Alice Chen? | assessment | assessment | assessment | 7 | 10 |
-| What does MindBridge do? | assessment | assessment | assessment | 6 | 10 |
-| Tell me about climate investing | assessment | assessment | assessment | 5 | 10 |
-| When did we last meet Alice? | timeline | timeline | timeline | 9 | 9 |
-| Recent updates on GenomeAI | timeline | timeline | timeline | 8 | 8 |
-| CloudScale acquisition | timeline | timeline | timeline | 8 | 8 |
-| Alice Chen NovaPay payments | assessment | assessment | assessment | 7 | 8 |
-| Carol Nakamura MindBridge AI | assessment | assessment | assessment | 6 | 8 |
-| AI companies building products | assessment | assessment | assessment | 9 | 10 |
-| Who raised funding recently? | timeline | timeline | timeline | 10 | 10 |
-| Bob and James climate investments | assessment | assessment | assessment | 5 | 9 |
-| AI replacing designers | assessment | assessment | assessment | 7 | 8 |
-| Everything on RoboLogic | timeline | assessment | assessment | 6 | 6 |
-| Deep dive on crypto custody | timeline | assessment | assessment | 6 | 6 |
-| Education technology Africa | assessment | assessment | assessment | 7 | 10 |
-| What launched this year? | timeline | timeline | timeline | 10 | 10 |
-| MPC multi-party computation | assessment | assessment | assessment | 7 | 9 |
-| Protein folding drug discovery | assessment | assessment | assessment | 7 | 9 |
-| EduStack Nigeria | assessment | assessment | assessment | 7 | 8 |
-
-The "pages" column tells the clearest story. Entity lookups with `detail=low` (the
-intent classifier's choice) go from 5-7 pages to 8-10 pages. The agent gets significantly
-broader context for the same query.
-
-## What shipped in PR #64
-
-1. **Compiled truth boost** — 2.0x score multiplier after RRF normalization
-2. **Intent classifier** — zero-latency regex that auto-selects detail level per query
-3. **Detail parameter** — `--detail low/medium/high` for explicit agent control
-4. **Source-aware dedup** — guarantees compiled truth chunk per page in results
-5. **Cosine re-scoring** — re-ranks chunks against the actual query embedding
-6. **RRF normalization** — scores normalized to 0-1 before boosting
-7. **CJK word count fix** — Chinese/Japanese/Korean queries now expand correctly
-8. **Eval harness** — `gbrain eval --qrels` with P@k, R@k, MRR, nDCG@k + A/B comparison
-9. **This benchmark** — 29 pages, 20 queries, reproducible, no private data
-
-## How to reproduce
-
-```bash
-bun run test/benchmark-search-quality.ts
-```
-
-Runs in ~2 seconds against in-memory PGLite. No API keys, no database, no network.
-
-## Methodology notes
-
-- All data is fictional. No private information from any real brain.
-- Embeddings use 25 topic dimensions with shared axes (not orthogonal basis vectors).
-  "AI" and "health" share signal so that an AI health query naturally ranks both the
-  AI-health concept page and the MindBridge company page.
-- Each page has exactly 2 chunks (1 compiled truth, 1 timeline) for clean measurement.
-  Real brains have more chunks per page, which would amplify the boost's effect.
-- The baseline uses the old text-prefix dedup key. The new configurations use chunk_id.
-- Graded relevance: 3 = primary answer, 2 = strongly related, 1 = tangentially related.

docs/designs/CODE_CATHEDRAL_II.md

@@ -0,0 +1,162 @@
+# Code Cathedral II — v0.20.0 Design
+
+**Status:** Accepted. CEO + Eng + 2 codex passes CLEARED (2026-04-24). 16 cross-model findings absorbed total: 7 codex pass 1 (structural prereqs) + 6 codex pass 2 (absorption errors including the CHUNKER_VERSION silent-no-op gate and inbound-edge invalidation) + 3 eng-review architectural decisions. DX review recommended post-Layer 8 (new CLI surfaces) before ship.
+**Supersedes:** Cathedral I (planned v0.18.0–v0.19.0 code indexing, shipped v0.19.0).
+**Mode:** SCOPE EXPANSION (user explicit: "I want the best code search in the world").
+**Scale:** 14 bisectable layers, ~20–25 CC hours, 3–5 human-weeks. One schema migration with split edge tables (`code_edges_chunk` + `code_edges_symbol`). Backfill via `CHUNKER_VERSION` bump (automatic on next sync) + explicit `gbrain reindex-code` command.
+
+## Why v0.20.0
+
+v0.19.0 shipped code indexing: tree-sitter chunker, 29 active languages, symbol columns, forward doc↔impl linking, incremental embed cache, BrainBench code category. Four cathedral-I items got deferred during shipping: `query --lang` filter, `sync --all` cost preview, markdown fence extraction, reverse-scan doc↔impl backfill.
+
+Cathedral II is a promise-keeping release for those four, bundled with the leap that makes gbrain *the* code search: structural edges (call graph + references + imports + inheritance), parent-scope capture, doc-comment FTS binding, and two-pass retrieval. No more grep-class retrieval on code.
+
+## The 10x leap
+
+Today: agent asks "how does hybrid search handle N+1?" → gets 3 prose chunks of `hybrid.ts`.
+
+Cathedral II: same query returns the anchor function + its 3 callers + its 2 callees + its JSDoc + the guide in `/docs` that cites it + the test file exercising it + parent scope chain. One walk. Code-aware brain.
+
+## Scope (5 tiers + Layer 0 prerequisites, 14 bisectable layer commits)
+
+### Tier 0 — Prerequisites (surfaced by codex outside voice)
+
+**0a. File-classification widening.** `sync.ts:35` currently classifies only 9 extensions as code (TS, JS, Python, Go, Rust, Ruby, Java, C, C++). Cathedral II's B1 ships 165 lazy-loadable grammars, so the classifier needs to accept any extension the chunker can handle. Also reorders `detectCodeLanguage` so Magika (B2) runs as a fallback for extension-less files, not after a null-return gate.
+
+**0b. Chunk-grain FTS.** Current keyword search lives on `pages.search_vector`. Adding doc-comments or two-pass anchoring at the chunk level has zero ranking effect against a page-grain primitive. Layer 0b adds `content_chunks.search_vector` with a trigger building from qualified symbol name + doc-comment (weight A) and chunk_text (weight B), plus rewrites `searchKeyword` to rank chunks directly. Page-level search_vector stays for title-heavy searches.
+
+Both Layer 0 items are prerequisites for the 10x leap to actually move retrieval metrics.
+
+### Tier A — Structural edges (the 10x leap)
+
+**A1. Call-graph + reference extraction with qualified symbol identity.** Per-language tree-sitter queries at `importCodeFile` time capture:
+
+- `calls` — function call-sites
+- `imports` — module deps
+- `extends` / `implements` — type hierarchies
+- `mixes_in` — Ruby `include`/`extend`/`prepend`
+- `type_refs` — parameter + return type usage
+- `declares` — chunk owns a symbol definition
+
+**Qualified symbol identity across all 8 langs.** `parent_symbol_path` (A3) is the source of truth for scope; edges use qualified names built from it. Examples: `Admin::UsersController#render` (Ruby instance), `Admin::UsersController.find_all` (Ruby singleton), `admin.users_controller.UsersController.render` (Python), `(*UsersController).Render` (Go), `users::UsersController::render` (Rust), `com.acme.admin.UsersController.render` (Java). Per-lang delimiter + method/class-method distinction. Ruby ships fully in ranker (CLI + A2 two-pass) — no deferral.
+
+**Split schema (two tables, not one polymorphic):**
+```sql
+CREATE TABLE code_edges_chunk (
+  from_chunk_id INTEGER NOT NULL REFERENCES content_chunks(id) ON DELETE CASCADE,
+  to_chunk_id   INTEGER NOT NULL REFERENCES content_chunks(id) ON DELETE CASCADE,
+  from_symbol_qualified TEXT NOT NULL,
+  to_symbol_qualified   TEXT NOT NULL,
+  edge_type     TEXT NOT NULL,
+  source_id     TEXT REFERENCES sources(id) ON DELETE CASCADE,
+  UNIQUE (from_chunk_id, to_chunk_id, edge_type)
+);
+CREATE TABLE code_edges_symbol (
+  from_chunk_id INTEGER NOT NULL REFERENCES content_chunks(id) ON DELETE CASCADE,
+  from_symbol_qualified TEXT NOT NULL,
+  to_symbol_qualified   TEXT NOT NULL,
+  edge_type     TEXT NOT NULL,
+  source_id     TEXT REFERENCES sources(id) ON DELETE CASCADE,
+  UNIQUE (from_chunk_id, to_symbol_qualified, edge_type)
+);
+```
+`code_edges_chunk` = resolved (both endpoints known). `code_edges_symbol` = unresolved (target symbol exists by qualified name, definition chunk not yet seen). Promotion from symbol→chunk table happens on later import. `source_id` is TEXT matching actual `sources.id` type.
+
+**Shipped languages:** TypeScript, TSX, JavaScript, Ruby, Python, Go, Rust, Java (8 langs, ~85% of real brain code). Other languages chunk normally (via B1 lazy-load) but don't emit edges in v0.20.0 — extension is one query file + delimiter config per language, shippable as small follow-up PRs.
+
+**A2. Two-pass retrieval.** Current: keyword + vector → RRF → dedup. New: keyword + vector → anchor set → expand 1–2 hops on `code_edges_chunk` with structural-distance decay → blend into RRF.
+
+**Default OFF in all cases.** Opt-in only via `--walk-depth N` or `--near-symbol <name>`. Exact-symbol-match auto-on was unsafe (symbol names collide across files). Neighbor cap 50 per hop, depth cap 2. Dedup's per-page cap (currently 2) lifts to `min(10, walkDepth × 5)` when walking so structural neighbors from one file aren't clipped. Distance decay: `1/(1 + hop)` on expanded-neighbor RRF contributions.
+
+**A3. Parent-scope capture + nested-chunk emission.** Two parts:
+
+*Part 1:* Nested symbols get `parent_symbol_path text[]` on `content_chunks`. Embedded into chunk header: `[TypeScript] src/foo.ts:42-58 function formatResult (in BrainEngine.searchKeyword)`. Scope flows into embedding. Dual-use: drives A1's qualified symbol identity.
+
+*Part 2:* Extend `splitLargeNode` to emit nested functions/methods/inner-classes as their own chunks. The current chunker is top-level-node oriented — a `class Foo { method1() {} method2() {} }` emits one chunk. Parent_symbol_path on top-level nodes is empty (no parent above top level), so A3 contributes nothing without sub-top-level chunks. Part 2 makes the scope annotation load-bearing.
+
+**A4. Doc-comment → symbol binding.** Leading AST comment extracted to `doc_comment text`. Lands on **chunk-grain** search_vector (Layer 0b prerequisite) with FTS weight `'A'`. Natural-language queries rank docstring matches above body text and below title. `'A' > 'B' > 'C' > 'D'` per Postgres FTS weight convention.
+
+### Tier B — Coverage (honest Chonkie parity)
+
+**B1.** Lazy-load tree-sitter-language-pack (~165 languages). Replace 36 committed WASMs with a manifest + per-process parser cache. Cathedral I promised this and didn't deliver — Cathedral II does.
+
+**B2.** Magika auto-detect for extension-less files (Dockerfile, Makefile, `.envrc`). ~1MB bundled asset. Falls back to null → recursive chunker if classifier fails to load.
+
+### Tier C — Agent CLI surfaces
+
+- `query --lang <lang>` — filter by `content_chunks.language`
+- `query --symbol-kind function|class|method|type|interface|enum` — filter by `symbol_type`
+- `query --near-symbol <name> --depth 1..2` — two-pass retrieval anchored at a known symbol
+- `code-callers <symbol>` — uses A1 `calls` edges, reversed
+- `code-callees <symbol>` — uses A1 `calls` edges, forward
+
+All auto-JSON on non-TTY. `StructuredAgentError` envelopes on failure. `code-signature` deferred to v0.20.1 (needs per-language type captures).
+
+### Tier D — Bridge items (cathedral I promises)
+
+**D1.** `sync --all` cost preview. `estimateTokens` extracted from `chunkers/code.ts` to new `tokens.ts` module. Before per-source loop: walk sync-diff set, sum tokens, compute $ estimate. TTY + !json + !yes → interactive `[y/N]`. Non-TTY or `--json` or piped → emit `ConfirmationRequired` envelope, exit 2. `--yes` skips. `--dry-run` previews + exit 0. Preview on `--all` only, not single-source (DX review pain is first-time large-sync surprise bills).
+
+**D2.** Markdown fence extraction in `importFromContent`. After `parseMarkdown`, iterate marked lexer tokens for `{type:'code', lang, text}`. Map fence tag → language. Chunk each fence through `chunkCodeText`. Persist as `chunk_source='fenced_code'`. Cap 100 fences per markdown page (DOS defense). Per-fence try/catch — one bad fence doesn't break the page import.
+
+**D3.** `reconcile-links` batch command. Walks markdown pages, calls existing v0.19.0 `extractCodeRefs` per page, emits `addLink(md, code, ..., 'documents')` + reverse. `ON CONFLICT DO NOTHING` handles idempotency. Statement-timeout scoped via `sql.begin` + `SET LOCAL`. Progress reporter + final summary (edges added / existed / missing-target). Respects `auto_link` config.
+
+### Tier E — Eval, backfill, honesty
+
+**E1.** BrainBench code sub-categories: `call_graph_recall` (callers of X → expected set), `parent_scope_coverage` (nested-symbol queries return correct scope), `doc_comment_matching` (NL queries rank doc-comments above prose). Regression gates against A1/A3/A4 drift.
+
+**E2.** Backfill: schema migrates automatically (zero cost). **`CHUNKER_VERSION` bumps 3 → 4** — that constant is folded into each code page's `content_hash`, so every code page's hash changes on upgrade. Next `gbrain sync` won't short-circuit on "git HEAD unchanged"; it re-chunks every code file. New `gbrain reindex-code [--source <id>] [--dry-run] [--yes] [--force]` provides explicit full backfill with cost preview (reuses D1 infra) and `--force` bypasses content_hash skip entirely. Users control when to pay; silent no-op path closed.
+
+**E3.** Honest CHANGELOG. Retire "Chonkie superset" framing. Run BrainBench before/after for real numbers: 150+ languages loaded (after B1), MRR on NL→code queries, P@1 call-graph precision, P@k on symbol_name queries, sync cost preview on 5K-file repo. Back every claim with a runnable command.
+
+## Implementation ordering (14 layers, post-codex)
+
+1. **0a** — File-classification widening (sync.ts:35) + Magika reordered as fallback
+2. **0b** — Chunk-grain FTS (content_chunks.search_vector + trigger + searchKeyword chunk-level rewrite)
+3. **Foundation** — schema migration (split edge tables, qualified name columns on content_chunks) + engine method stubs + types
+4. **B1** — lazy-load grammar manifest + bun --compile guard
+5. **A1** — edge-extractor + 8 per-lang query files + qualified symbol identity + tests
+6. **A3** — parent-scope column + doc-comment column + splitLargeNode nested-chunk emission
+7. **A4** — doc-comment FTS weight A on chunk-grain search_vector
+8. **A2** — two-pass retrieval, default OFF, opt-in only; dedup cap lifts when walking
+9. **D tier bundled** — cost preview + fence extraction + reconcile-links
+10. **B2** — Magika auto-detect
+11. **C tier** — 5 CLI surfaces
+12. **E1** — BrainBench sub-categories + CHUNKER_VERSION 3→4 bump
+13. **E2** — `reindex-code` with `--force` + migration orchestrator with backfill-prompt phase
+14. **E3 + release** — honest CHANGELOG + docs + migration skill + `/ship`
+
+## Size and cost
+
+- Diff: ~5500–6500 lines (~2.5x v0.19.0 post-codex expansion)
+- Tests: ~2000 lines (8 langs × qualified-name + edge-extraction fixtures + Layer 0b FTS migration tests)
+- Files: ~36 new, ~25 modified
+- CC time: ~20–25 hours focused (was 14–18 pre-codex; +6h for Layer 0a/0b + qualified identity across 8 langs + nested-chunk emission + CHUNKER_VERSION bump layer)
+- Human-equivalent: 3–5 weeks
+- First-sync cost bump for upgraded v0.19.0 users: every code page re-chunks on first sync after upgrade (CHUNKER_VERSION bump forces invalidation). Users run `gbrain reindex-code --dry-run` for cost preview, then `--yes` or accept gradual backfill over time as files change.
+- Daily autopilot cost post-backfill: unchanged (edges extracted at chunk time, no per-query LLM)
+
+## Risks and mitigations
+
+1. **Schema migration on live Postgres.** Test against production-shape DB before ship. v0.12.0 JSONB incident is the canary.
+2. **Per-language tree-sitter queries are fiddly.** Hand-verified edge-set fixtures per language. Ruby gets extra coverage for dynamic-dispatch false negatives.
+3. **Two-pass retrieval regression.** Default off for prose. BrainBench Cat 1 MUST show no regression before shipping.
+4. **Backfill shape (G1 resolved).** Three composable layers: schema-auto migrates columns empty (zero cost). Lazy on-touch catches 80% over time (zero cost). Explicit `reindex-code` with cost preview for users wanting immediate full benefit. No surprise bills.
+5. **Magika bundle (G2 resolved).** +1MB asset, `bun --compile` guard extension. If bundling surfaces bugs late in implementation, B2 is the only tier that can fall back to v0.20.1 without blocking the cathedral — it's self-contained at Layer 8.
+6. **High-fan-out symbols.** `console.log`-style symbols have 100K callers. Neighbor cap 50, depth cap 2. Chaos test fixture required.
+
+## Review gates
+
+- CEO review (cathedral II) — CLEARED 2026-04-24
+- Outside voice (codex) — run during cathedral II CEO review
+- `/plan-devex-review` — up next (per user request, 5 new CLI surfaces + reindex-code need DX polish review before eng)
+- `/plan-eng-review` — required before implementation begins
+- `/review` + `/codex review` — required before `/ship`
+
+## What's deferred to later cathedrals
+
+- **C6** `code-signature "(A, B) => C"` — per-language type captures. v0.20.1.
+- **Call-graph langs beyond 8 shipped** — PHP, Swift, Kotlin, Scala, C#, C++, Elixir, etc. One small PR per language.
+- **LSP integration** for live precision. v0.22+ cathedral.
+- **Code-tour generator** (cathedral I T1).
+- **Private-code redaction pre-embed** (cathedral I T3).
+- **`gbrain doctor --chunker-debug`** AST dump.

docs/designs/KNOWLEDGE_RUNTIME.md

@@ -0,0 +1,717 @@
+# GBrain Knowledge Runtime — Design Doc
+
+**Status:** DRAFT for CEO review.
+**Date:** 2026-04-18.
+**Supersedes:** The earlier "Feynman Ideas Assessment + Phase A/B" plan.
+
+---
+
+## 0. Context
+
+During a CEO review of a narrow two-feature plan (bare-tweet citation repair + completeness score, borrowed from Feynman), the scope was reframed. The narrow plan duplicated work Garry's OpenClaw already does and missed the real leverage point: **the bespoke abstractions hiding inside OpenClaw — resolvers, enrichment orchestration, scheduling, deterministic output — should live in GBrain as first-class primitives.**
+
+North star: *"When Garry's OpenClaw's Claw upgrades to this version of GBrain, it should immediately recognize brilliance and completeness and say 'It's time to switch to these abstractions.'"*
+
+That is the test this document is designed against. Everything else is downstream.
+
+---
+
+## 1. The Four Layers
+
+The design is four layered abstractions. Each is independently useful; together they are the Knowledge Runtime.
+
+```
+  ┌───────────────────────────────────────────────────────────────────┐
+  │                   KNOWLEDGE RUNTIME (new)                         │
+  ├───────────────────────────────────────────────────────────────────┤
+  │  Layer 4: Deterministic Output Builder                            │
+  │     BrainWriter · Scaffolds · Back-link enforcer · Slug registry  │
+  │     Rule: LLM picks WHAT to write. Code guarantees WHERE and HOW. │
+  ├───────────────────────────────────────────────────────────────────┤
+  │  Layer 3: Scheduler                                               │
+  │     ScheduledResolver · TZ-aware quiet hours (enforced) ·         │
+  │     Auto-stagger · Durable state · Retry/circuit-break            │
+  ├───────────────────────────────────────────────────────────────────┤
+  │  Layer 2: Enrichment Orchestrator                                 │
+  │     Trigger convergence · Tier routing · Budget · Cascade ·       │
+  │     Evidence-weighted completeness · Fail-safe transactions       │
+  ├───────────────────────────────────────────────────────────────────┤
+  │  Layer 1: Resolver SDK                                            │
+  │     Resolver<I,O> interface · Registry · Factory · Plugin recipes │
+  │     Ported reference impls: X-API, Perplexity, Mistral, brain     │
+  └───────────────────────────────────────────────────────────────────┘
+          │                                                │
+          ▼                                                ▼
+     REUSES (polished primitives already in GBrain)  REPLACES (ad-hoc code)
+     FailImproveLoop · backoff · storage factory ·   enrichment-service ·
+     check-resolvable · operations validators ·      embedding · transcription ·
+     engine interface · publish · backlinks          2 recipe formats
+```
+
+---
+
+## 2. Why This Order (L1 → L4)
+
+Every higher layer depends on the lower one. **L1 must land first or the rest leaks abstractions.**
+
+- **L1 (Resolvers)** is the substrate. Without a uniform lookup interface, every orchestrator + writer has bespoke callers.
+- **L2 (Orchestrator)** uses L1 to fetch; without L1 it's still ad-hoc.
+- **L3 (Scheduler)** runs L2 periodically; without L2 it's scheduling nothing structured.
+- **L4 (Output Builder)** is what every layer ultimately writes through; without it we have 14 call sites doing `fs.writeFile` with hand-rolled citation discipline.
+
+An earlier implementation could ship L1 + L4 first (the two "purest" layers) and have the most immediate integrity impact, then add L2 + L3. But the end-state must include all four.
+
+---
+
+## 3. Layer 1 — Resolver SDK
+
+### 3.1 What's broken today
+
+Garry's OpenClaw has **69 distinct external-lookup patterns** across X API (14 shapes), Perplexity, Mistral OCR, Gmail, Calendar, Slack, GitHub, YouTube, Diarize.io, YC tools, OSINT collectors, and brain-local lookups. Each one is a bespoke script under `scripts/` with its own error handling, retry logic, and output shape. GBrain has 3 ad-hoc wrappers (`embedding.ts`, `transcription.ts`, `enrichment-service.ts`) that don't share an interface.
+
+Common consequences:
+- No uniform retry/backoff strategy (some scripts retry, most don't)
+- No cost tracking (Perplexity bills eaten silently when calls return no-substance results)
+- No confidence/provenance propagation (callers can't tell if an answer is verified or inferred)
+- Users can't add a resolver without forking GBrain
+
+### 3.2 Interface
+
+```typescript
+// src/core/resolvers/interface.ts
+
+export type ResolverCost = 'free' | 'rate-limited' | 'paid';
+
+export interface ResolverRequest<I> {
+  input: I;
+  context: ResolverContext;
+  timeoutMs?: number;
+}
+
+export interface ResolverResult<O> {
+  value: O;
+  confidence: number;      // 0.0–1.0; 1.0 = deterministic from ground-truth API
+  source: string;          // e.g. "x-api-v2", "perplexity-sonar", "brain-local"
+  fetchedAt: Date;
+  costEstimate?: number;   // dollars; 0 if free
+  raw?: unknown;           // for sidecar preservation via put_raw_data
+}
+
+export interface Resolver<I, O> {
+  readonly id: string;           // stable, slug-like: "x_handle_to_tweet"
+  readonly cost: ResolverCost;
+  readonly backend: string;      // "x-api-v2", "perplexity", "brain-local"
+  readonly inputSchema: JSONSchema;
+  readonly outputSchema: JSONSchema;
+
+  available(ctx: ResolverContext): Promise<boolean>;
+  resolve(req: ResolverRequest<I>): Promise<ResolverResult<O>>;
+}
+```
+
+### 3.3 Context
+
+```typescript
+export interface ResolverContext {
+  engine: BrainEngine;
+  storage: StorageBackend;
+  config: GBrainConfig;
+  logger: Logger;
+  metrics: MetricsRecorder;
+  budget: BudgetLedger;       // hard spend caps, queried pre-resolve
+  requestId: string;
+  remote: boolean;            // trust boundary — untrusted callers get stricter validation
+  deadline?: Date;
+}
+```
+
+### 3.4 Registry + Factory (mirrors `src/core/storage.ts`)
+
+```typescript
+// src/core/resolvers/registry.ts
+export class ResolverRegistry {
+  register<I, O>(r: Resolver<I, O>): void;
+  get(id: string): Resolver<unknown, unknown>;
+  list(filter?: { cost?: ResolverCost; backend?: string }): Resolver[];
+  async resolve<I, O>(id: string, input: I, ctx: ResolverContext): Promise<ResolverResult<O>>;
+}
+
+// src/core/resolvers/factory.ts (dynamic import like engine-factory)
+export async function createResolver(
+  type: 'x-api' | 'perplexity' | 'mistral-ocr' | 'brain-local' | 'plugin',
+  config: ResolverConfig,
+): Promise<Resolver>;
+```
+
+### 3.5 Plugin format (unifies `recipes/` + `data-research` formats)
+
+A plugin is YAML + JS module, discovered via filesystem scan of `~/.gbrain/resolvers/` and `recipes/`.
+
+```yaml
+# Example: resolvers/x-api/handle-to-tweet.yaml
+id: x_handle_to_tweet
+version: 1
+category: lookup
+cost: rate-limited
+backend: x-api-v2
+module: ./handle-to-tweet.ts
+input_schema:
+  type: object
+  properties:
+    handle:   { type: string, pattern: "^[A-Za-z0-9_]{1,15}$" }
+    keywords: { type: string }
+  required: [handle]
+output_schema:
+  type: object
+  properties:
+    url:        { type: string, format: uri }
+    tweet_id:   { type: string }
+    text:       { type: string }
+    created_at: { type: string, format: date-time }
+requires:
+  env: [X_API_BEARER_TOKEN]
+health_check:
+  kind: http
+  url: https://api.twitter.com/2/tweets/1
+  expect: { status: [200, 401] }   # 401 = auth failure but endpoint reachable
+tests:
+  - input:  { handle: "garrytan" }
+    expect: { url: { pattern: "^https://x\\.com/garrytan/status/\\d+$" } }
+```
+
+Trust flagging follows the existing `src/commands/integrations.ts` pattern: only package-bundled resolvers are `embedded=true` and may run arbitrary commands; user-provided resolvers are restricted to `http` and validated schemas.
+
+### 3.6 Wraps every resolver with `FailImproveLoop`
+
+Existing `src/core/fail-improve.ts` is the deterministic-first/LLM-fallback pattern. Every resolver automatically gets wrapped: if the deterministic path (e.g. X API) returns a valid result, use it; if it fails, optionally fall back to an LLM-based resolver; log both paths for future pattern analysis and auto-test generation.
+
+### 3.7 Reference implementations to ship
+
+The OpenClaw survey inventoried 69 resolver shapes. Shipping all of them is wrong (over-scoped); shipping zero is under-scoped. The dogfood set:
+
+| # | Resolver | Purpose | Used by |
+|---|---|---|---|
+| 1 | `x_handle_to_tweet` | Bare-tweet citation repair (original Phase A) | `gbrain integrity` |
+| 2 | `url_reachable` | Dead-link detection | `gbrain integrity` |
+| 3 | `brain_slug_lookup` | Name/email → slug (wraps existing `resolveSlugs`) | Output Builder |
+| 4 | `openai_embedding` | Refactor of `src/core/embedding.ts` into Resolver | Import pipeline |
+| 5 | `perplexity_query` | Query → synthesis + citations | Enrichment Orchestrator |
+| 6 | `text_to_entities` | LLM entity extraction (structured JSON) | Enrichment Orchestrator |
+
+The remaining 63 OpenClaw patterns port incrementally, driven by user need. Each port is a new YAML + module under `recipes/` or `~/.gbrain/resolvers/` with no framework changes.
+
+---
+
+## 4. Layer 2 — Enrichment Orchestrator
+
+### 4.1 What's broken today
+
+Garry's OpenClaw's enrichment is **polished at the data layer, hacky at the control layer**:
+
+- **Completeness = "length > 500 chars + no `needs-enrichment` tag"** (`lib/enrich.mjs:351-355`). Naïve. A rich page of repetitive Perplexity summaries (see `brain/people/0interestrates.md` — 38 repeating blocks) passes this check.
+- **30-day auto-re-enrichment** runs forever. No "done" state. A person met once in 2023 still gets re-researched monthly.
+- **Cascade is convention-only.** Person→company stubs are created automatically; company→investors, company→employees traversals are documented but never implemented.
+- **No hard budget cap.** Cost is estimated per batch, never enforced across batches or per day.
+- **Failure is silent.** A bad Perplexity response logs and continues; partial writes can leave a page with a timeline entry but no raw-data sidecar.
+
+### 4.2 The orchestrator
+
+```typescript
+// src/core/enrichment/orchestrator.ts
+
+export interface EnrichmentRequest {
+  entitySlug: string;
+  trigger: 'mention' | 'stub-creation' | 'cron-sweep' | 'manual' | 'cascade';
+  tier?: 1 | 2 | 3;                // optional override; auto-computed if absent
+  cascadeDepth?: number;           // 0 = no cascade; default 1
+}
+
+export interface EnrichmentResult {
+  entitySlug: string;
+  completenessBefore: number;
+  completenessAfter: number;
+  resolversUsed: string[];         // e.g. ["perplexity_query", "x_handle_to_tweet"]
+  costSpent: number;
+  writtenTo: string[];             // page paths touched, for transaction audit
+  cascadedTo: string[];            // related entities enriched
+  status: 'enriched' | 'skipped' | 'failed' | 'budget-exhausted';
+  reason?: string;
+}
+
+export class EnrichmentOrchestrator {
+  constructor(
+    private registry: ResolverRegistry,
+    private writer: BrainWriter,
+    private budget: BudgetLedger,
+    private scorer: CompletenessScorer,
+    private graph: EntityGraph,
+  ) {}
+
+  async enrich(req: EnrichmentRequest): Promise<EnrichmentResult>;
+  async enrichBatch(reqs: EnrichmentRequest[]): Promise<EnrichmentResult[]>;
+}
+```
+
+### 4.3 Evidence-weighted completeness (replaces length heuristic)
+
+Completeness is a per-entity-type rubric, stored in frontmatter on write and recomputed on demand.
+
+```typescript
+// src/core/enrichment/completeness.ts
+export interface CompletenessRubric<Page> {
+  entityType: PageType;
+  dimensions: {
+    name: string;
+    weight: number;                // sum must = 1.0
+    check: (page: Page) => number; // 0.0–1.0
+  }[];
+}
+
+// Example rubric for persons:
+//   - has_role_and_company   0.20
+//   - has_source_urls        0.20  (≥1 URL with resolver-verified reachability)
+//   - has_timeline_entries   0.15  (≥1)
+//   - has_citations          0.15  (every claim has [Source: ...])
+//   - has_backlinks          0.10  (every linked page links back)
+//   - recency_score          0.10  (last_verified within 90 days)
+//   - non_redundancy         0.10  (no repeated blocks; distinct-lines/total-lines > 0.8)
+```
+
+**Key property:** `non_redundancy` + `recency_score` explicitly kill the two brain pathologies observed in the audit (Wilco-style repeating blocks; stale pages without `last_verified`).
+
+The `completeness` field goes in frontmatter as `0.0–1.0`. It becomes queryable via `list_pages(where: completeness < 0.5)`.
+
+### 4.4 Tier routing with hard budget
+
+Two-dimensional routing: **importance** (tier 1/2/3 from person-score) × **budget state**.
+
+```typescript
+// src/core/enrichment/tiers.ts
+export const TIER_CONFIG = {
+  1: { models: ['opus', 'sonar-deep'], maxCostUsd: 0.10, cascadeDepth: 2 },
+  2: { models: ['sonar'],              maxCostUsd: 0.02, cascadeDepth: 1 },
+  3: { models: ['sonar'],              maxCostUsd: 0.005, cascadeDepth: 0 },
+};
+
+// src/core/enrichment/budget.ts
+export class BudgetLedger {
+  // Hard caps. Queryable pre-resolve.
+  dailyCapUsd: number;
+  perEntityCapUsd: number;
+  perResolverCapUsd: Map<string, number>;
+
+  async reserve(resolverId: string, estimateUsd: number): Promise<Reservation | 'exhausted'>;
+  async commit(reservation: Reservation, actualUsd: number): Promise<void>;
+  async rollback(reservation: Reservation): Promise<void>;
+  async state(): Promise<{ spent: number; remaining: number; perResolver: Record<string, number> }>;
+}
+```
+
+**Property:** if the daily cap is reached, `orchestrator.enrich()` returns `status: 'budget-exhausted'` immediately. No silent overages. Circuit-breaker resets at midnight in the user's configured TZ.
+
+### 4.5 Cascade (entity graph traversal)
+
+```typescript
+// src/core/enrichment/cascade.ts
+export class EntityGraph {
+  // Deterministic, no LLM. Uses engine.getLinks() + engine.getBacklinks().
+  async neighbors(slug: string, depth: number): Promise<string[]>;
+  async cascadeFrom(trigger: string, depth: number): Promise<EnrichmentRequest[]>;
+}
+```
+
+If person X is enriched and gains a new `company: Acme` field, cascade checks: does `companies/acme` exist? If not, create stub + enqueue at tier 2. Does `companies/acme` link back to X? If not, write the back-link. **Iron Law is machine-enforced, not skill-enforced.**
+
+### 4.6 Fail-safe transactions
+
+Every enrichment is wrapped in a BrainWriter transaction (Layer 4). Partial writes are rolled back. No asymmetric state like timeline-entry-without-raw-sidecar.
+
+```typescript
+await writer.transaction(async (tx) => {
+  const research = await registry.resolve('perplexity_query', {...}, ctx);
+  await tx.appendTimeline(slug, {...});
+  await tx.putRawData(slug, 'perplexity', research.raw);
+  await tx.setFrontmatterField(slug, 'completeness', score);
+  // All-or-nothing commit on exit.
+});
+```
+
+---
+
+## 5. Layer 3 — Scheduler
+
+### 5.1 What's broken today
+
+Garry's OpenClaw's cron is **externally-driven JSON** (`cron/jobs.json`) with ~30 jobs manually stagger-offset at different minutes. GBrain has **zero native scheduling** — `src/commands/autopilot.ts` is a single daemon loop, and `docs/guides/cron-schedule.md` is architectural guidance, not code.
+
+Failures observed in Garry's OpenClaw's actual state:
+- `X OAuth2 Token Refresh`: 11 consecutive timeouts (critical-path silent failure)
+- `flight-tracker daily scan`: 5 consecutive timeouts
+- `morning-briefing`: 4 consecutive timeouts
+- Quiet hours are checked at runtime in skills, so a skill that forgets to check will DM at 3 a.m.
+- Staggering is manual convention; no protection against two jobs colliding after a config edit.
+
+### 5.2 ScheduledResolver interface
+
+```typescript
+// src/core/scheduling/scheduler.ts
+export interface Schedule {
+  kind: 'cron' | 'interval';
+  expr?: string;                    // cron string
+  intervalMs?: number;
+  tz: string;                       // IANA: "America/Los_Angeles"
+  quietHours?: {
+    startHour: number;              // 22 = 10 PM local
+    endHour: number;                // 7 = 7 AM local
+    policy: 'skip' | 'defer' | 'silent-run';
+  };
+  staggerKey?: string;              // jobs with same key auto-offset
+  maxConcurrent?: number;           // global concurrency cap
+  maxDurationMs?: number;           // timeout
+}
+
+export interface ScheduledResolver extends Resolver<void, ScheduledResult> {
+  schedule: Schedule;
+  retryPolicy: { maxRetries: number; backoffMs: number };
+  circuitBreaker: { failureThreshold: number; cooldownMs: number };
+  state: DurableState;              // watermark, content-hash, idempotency key
+}
+```
+
+### 5.3 Enforcement vs convention (the key delta from Garry's OpenClaw)
+
+| Concern | Garry's OpenClaw today | Knowledge Runtime |
+|---|---|---|
+| Quiet hours | Checked inside each skill (trust-based) | Enforced at scheduler, skill cannot override |
+| Staggering | Manual minute-offset in `jobs.json` | Scheduler assigns slots via hashed staggerKey |
+| Concurrency | `MAX_BATCH_PROCESSES=2` in backoff, ignored by cron | Global semaphore in scheduler |
+| Timeout | Per-job string in JSON, not always respected | Enforced via `AbortController`, timeout raises `TimeoutError` caught by orchestrator |
+| Retry | None at cron level | `retryPolicy` with exponential backoff |
+| Silent failure | "11 consecutive timeouts" unnoticed | Circuit breaker opens at threshold → escalation to user |
+| Idempotency | State files per job, no framework | `DurableState` primitive: watermark/ID/content-hash |
+
+### 5.4 Native engine + OS cron adapter
+
+The scheduler runs as either:
+1. **Embedded** (default for `gbrain autopilot`): native event loop inside the daemon process. One process, many ScheduledResolvers.
+2. **OS-driven** (for Railway/launchd/systemd): `gbrain schedule run <id>` invoked by OS cron, scheduler state is durable so cross-invocation dedup still works.
+
+Both modes share the same `Schedule` config + state.
+
+### 5.5 Observability
+
+Every scheduled run emits structured events: `started`, `skipped-quiet-hours`, `deferred-to-active-hours`, `failed-retrying`, `circuit-opened`, `completed`. Events go to:
+- `~/.gbrain/scheduler/events.jsonl` (local, always)
+- `engine.logIngest` (audit trail in brain DB)
+- Optional webhook (Slack/Telegram for the user)
+
+`gbrain doctor` reads the event log and reports: current circuit-breaker state, any resolver with > 3 consecutive failures, any resolver that hasn't fired within 3× its interval (freshness SLA like Garry's OpenClaw's `freshness-check.mjs` but built-in).
+
+---
+
+## 6. Layer 4 — Deterministic Output Builder
+
+### 6.1 The anti-hallucination invariant
+
+**Iron Law: LLM picks WHAT. Code guarantees WHERE and HOW.**
+
+Garry's OpenClaw's existing `lib/enrich.mjs:buildTweetEntry` is close to this — tweet URLs are built from `tweet.id` returned by the X API, never from LLM memory. But:
+
+- A past incident: *"Sub-agent test #2 FAILED — hallucinated 'Philip Leung' entity links across all daily files. LLM rewriting of daily files is too error-prone."* (Garry's OpenClaw memory log, 2026-04-13.)
+- Back-links depend on `appendTimeline` being called everywhere; skips are silent.
+- Slug collisions are unchecked (no conflict detection on `slugify`).
+- Citation format is post-hoc linted weekly, not pre-write enforced.
+
+### 6.2 BrainWriter
+
+```typescript
+// src/core/output/writer.ts
+export class BrainWriter {
+  constructor(
+    private engine: BrainEngine,
+    private slugRegistry: SlugRegistry,
+    private scaffolder: Scaffolder,
+  ) {}
+
+  async transaction<T>(fn: (tx: WriteTx) => Promise<T>): Promise<T>;
+}
+
+export interface WriteTx {
+  // High-level typed operations; never raw string writes.
+  createEntity(input: EntityInput): Promise<string>;          // returns slug, conflict-checked
+  appendTimeline(slug: string, entry: TimelineInput): Promise<void>;
+  setCompiledTruth(slug: string, body: CompiledTruthInput): Promise<void>;
+  setFrontmatterField(slug: string, key: string, value: unknown): Promise<void>;
+  putRawData(slug: string, source: string, data: object): Promise<void>;
+  addLink(from: string, to: string, context: string): Promise<void>;  // auto-creates reverse back-link
+
+  // Validators (called implicitly on commit)
+  validate(): Promise<ValidationReport>;
+}
+```
+
+### 6.3 Scaffolder — deterministic link + citation construction
+
+Every user-visible URL/link/citation is built by code from resolver outputs, not from LLM text.
+
+```typescript
+// src/core/output/scaffold.ts
+export class Scaffolder {
+  tweetCitation(handle: string, tweetId: string, dateISO: string): string {
+    // "[Source: [X/garrytan, 2026-04-18](https://x.com/garrytan/status/123456)]"
+  }
+  emailCitation(account: string, messageId: string, subject: string): string {
+    // deterministic Gmail URL per OpenClaw pattern
+  }
+  sourceCitation(resolverResult: ResolverResult<unknown>): string {
+    // pulls .source, .fetchedAt, .raw from the result
+  }
+  entityLink(slug: string): string {
+    // slugRegistry checks existence; returns resolvable wikilink
+  }
+}
+```
+
+### 6.4 SlugRegistry — conflict detection
+
+```typescript
+// src/core/output/slug-registry.ts
+export class SlugRegistry {
+  async create(desiredSlug: string, displayName: string, type: PageType): Promise<CreatedSlug>;
+  // Throws SlugCollision if another entity already occupies desiredSlug and isn't
+  // confirmed as the same person (via email / x_handle / disambiguator).
+  // Auto-resolves near-collisions by appending disambiguator.
+
+  async confirmSame(slugA: string, slugB: string, confidence: number): Promise<void>;
+  async merge(canonical: string, duplicate: string): Promise<void>;
+}
+```
+
+### 6.5 Pre-write validators (fail-closed for integrity)
+
+On `WriteTx.validate()` before commit:
+
+1. **Citation validator.** Every factual sentence in `compiled_truth` must have an inline `[Source: ...]` within N lines. Non-compliant paragraphs are flagged. Configurable: strict-mode rejects the transaction, lint-mode warns.
+2. **Link validator.** Every `[text](path)` must point to a page that exists OR to a URL the Scaffolder built (so it's guaranteed-valid). No raw LLM-composed URLs.
+3. **Back-link validator.** Every outbound link must have a reverse link written in the same transaction.
+4. **Triple-HR validator.** Compiled truth / timeline split enforced at the schema level.
+
+**Fails closed**: the default is strict-mode. Loosening requires explicit `writer.transaction({ strictMode: false }, ...)` and logs a warning to the ingest log.
+
+### 6.6 LLM output sanitization
+
+Any LLM output destined for a brain page passes through a JSON-Schema-validated parser first. No free-form markdown goes to disk.
+
+- Entity extraction: JSON array of `{ name, type, context }` per existing `extractEntities` pattern — strict validation.
+- Compiled-truth synthesis: LLM emits structured `{ sections: [{heading, paragraphs: [{text, sources: [...]}]}]}`, scaffolder renders to markdown.
+- Timeline entries: LLM emits `{ date, summary, detail, sources }`, scaffolder renders.
+
+LLM never sees file paths, never writes files, never emits finished markdown.
+
+---
+
+## 7. Integration with existing GBrain
+
+### 7.1 Reuse (already polished)
+
+| Existing | Used by | Change |
+|---|---|---|
+| `src/core/fail-improve.ts` (9/10) | Wraps every Resolver in L1 | None; becomes default wrapper |
+| `src/core/backoff.ts` (9/10) | ResolverContext.backoff | None |
+| `src/core/storage.ts` (9/10) | Template for Resolver factory pattern | None; serves as pattern reference |
+| `src/core/check-resolvable.ts` (9/10) | Extend to validate Resolver plugins | Add `checkResolvers()` mode |
+| `src/commands/publish.ts` (9/10) | Uses BrainWriter under the hood | Minor: route through L4 |
+| `src/commands/backlinks.ts` (8/10) | Folded into L4 validator | Keep as CLI-facing lint entry point |
+| `src/core/operations.ts` validators | Reused in ResolverContext trust enforcement | None |
+| `src/core/engine.ts` BrainEngine (35 methods) | ResolverContext.engine | Extend with `getResolverRegistry()` |
+
+### 7.2 Replace (ad-hoc today)
+
+| Existing | Replace with |
+|---|---|
+| `src/core/enrichment-service.ts` (5/10) | `src/core/enrichment/orchestrator.ts` (L2) |
+| `src/core/embedding.ts` (monolithic) | `src/core/resolvers/builtin/embedding/openai.ts` |
+| `src/core/transcription.ts` (monolithic) | `src/core/resolvers/builtin/transcription/{groq,openai}.ts` |
+| `src/commands/integrations.ts` recipe format | Unified Resolver plugin format (§3.5) |
+| `src/core/data-research.ts` recipe format | Same unified format |
+| `src/commands/autopilot.ts` hard-coded daemon loop | Wraps a set of ScheduledResolvers |
+
+### 7.3 Extend
+
+- `src/core/engine.ts`: add `getResolverRegistry()`, `getWriter()`, `getScheduler()`. Engine becomes the runtime's root container.
+- `src/core/operations.ts`: `OperationContext` inherits from `ResolverContext` (or vice-versa). Trust flags unified.
+- `src/core/types.ts`: add `completeness: number` to `Page`, `sourcedBy: string[]` for provenance.
+
+---
+
+## 8. Migration Path (phased, shippable)
+
+Each phase ships independently, passes full E2E, is feature-flagged, and is reversible. No big-bang.
+
+### Phase 0 — Foundation (human: ~1 wk / CC: ~4 h)
+- Define `Resolver<I,O>`, `ResolverContext`, `ResolverRegistry`, `ResolverResult` (§3.2–3.4).
+- Add `src/core/resolvers/index.ts` wiring + tests for registry (register/get/list).
+- No behavioral change; ship as `v0.11.0-alpha` with feature flag.
+
+### Phase 1 — Three reference resolvers (human: ~1 wk / CC: ~4 h)
+- Port `src/core/embedding.ts` → `resolvers/builtin/embedding/openai.ts`.
+- Implement `resolvers/builtin/brain-local/slug-lookup.ts` (wraps `engine.resolveSlugs`).
+- Implement `resolvers/builtin/url-reachable.ts` (HEAD-check).
+- Prove the interface: old callers swap to `registry.resolve('openai_embedding', ...)`.
+
+### Phase 2 — BrainWriter + Slug Registry (human: ~1.5 wk / CC: ~6 h)
+- L4 core: `BrainWriter.transaction`, `Scaffolder`, `SlugRegistry` with conflict detection.
+- Pre-write validators: citation, link, back-link, triple-HR.
+- Migrate `src/commands/publish.ts` + `src/commands/backlinks.ts` to route through BrainWriter.
+- **Now** Garry's OpenClaw's "Philip Leung" hallucination is structurally impossible — LLM output passes through JSON-Schema validator before reaching Scaffolder.
+
+### Phase 3 — `gbrain integrity` command (human: ~0.5 wk / CC: ~2 h)
+- Ship the originally-scoped user-facing feature on top of the new foundation.
+- Uses Resolver SDK: `x_handle_to_tweet` + `url_reachable`.
+- Uses BrainWriter: all auto-repairs go through validated writes.
+- `--auto --confidence 0.8` mode as user approved in cherry-pick #1.
+- **User-visible value ships in Phase 3, not Phase 7.**
+
+### Phase 4 — Enrichment Orchestrator (human: ~2 wk / CC: ~8 h)
+- L2 core: `EnrichmentOrchestrator`, `BudgetLedger`, `CompletenessScorer`, `EntityGraph.cascadeFrom`.
+- Migrate `src/core/enrichment-service.ts` callers (deprecate the old file after).
+- Completeness score in frontmatter on every write (dogfooding cascades).
+
+### Phase 5 — Scheduler (human: ~2 wk / CC: ~8 h)
+- L3 core: `Scheduler`, `ScheduledResolver`, `DurableState`, circuit breaker, quiet-hours enforcer.
+- Migrate `src/commands/autopilot.ts` to a ScheduledResolver set.
+- Ship `gbrain schedule list|run|pause|tail` CLI for observability.
+
+### Phase 6 — Port 5–8 OpenClaw resolvers (human: ~1.5 wk / CC: ~6 h)
+- `perplexity_query`, `text_to_entities`, `mistral_ocr_pdf`, `x_search_all`, `x_user_to_tweets`, `gmail_query_to_threads`, `calendar_date_to_events`.
+- Each ships as YAML + TS module under `resolvers/builtin/` — **proof of the plugin format.**
+
+### Phase 7 — OpenClaw Adoption Integration (human: ~1 wk / CC: ~4 h)
+- Write `docs/openclaw/ADOPTION.md` showing your OpenClaw how to replace its 69 bespoke scripts with calls to `gbrain registry.resolve(...)`.
+- Ship a `gbrain claw-bridge` subcommand that proxies Garry's OpenClaw's current script invocations to the resolver registry — zero-edit adoption path.
+- **This is the test of the north star.** If your OpenClaw can stand up a 1-line shim and drop `scripts/x-api-client.mjs`, the abstraction succeeded.
+
+Total: human: ~10 weeks / CC: ~42 hours / calendar with single implementer: ~3–4 weeks.
+
+---
+
+## 9. Critical Files
+
+### New directories / files
+
+```
+src/core/
+  runtime/
+    index.ts                       # RuntimeContext (engine, storage, config, logger, metrics, budget)
+    registry.ts                    # ResolverRegistry
+    factory.ts                     # createResolver()
+  resolvers/
+    interface.ts                   # Resolver<I, O>
+    fail-improve-wrapper.ts        # auto-wraps every resolver in FailImproveLoop
+    builtin/
+      x-api/
+        handle-to-tweet.ts
+        handle-to-tweet.yaml
+      perplexity/
+        query.ts
+        query.yaml
+      brain-local/
+        slug-lookup.ts
+        url-reachable.ts
+      embedding/
+        openai.ts                  # refactored from src/core/embedding.ts
+      transcription/
+        groq.ts
+        openai.ts
+  enrichment/
+    orchestrator.ts                # EnrichmentOrchestrator
+    tiers.ts                       # TIER_CONFIG
+    budget.ts                      # BudgetLedger
+    completeness.ts                # CompletenessScorer + per-type rubrics
+    cascade.ts                     # EntityGraph
+  scheduling/
+    scheduler.ts                   # Scheduler + ScheduledResolver
+    schedule.ts                    # Schedule type, cron expr parser
+    state.ts                       # DurableState primitives
+    quiet-hours.ts                 # TZ-aware enforcement
+    stagger.ts                     # deterministic slot assignment
+  output/
+    writer.ts                      # BrainWriter
+    scaffold.ts                    # Scaffolder (typed URL builders)
+    slug-registry.ts               # SlugRegistry (conflict detection)
+    validators/
+      citation.ts
+      link.ts
+      back-link.ts
+      triple-hr.ts
+
+src/commands/
+  integrity.ts                     # ships in Phase 3, replaces Feynman Phase A/B
+  schedule.ts                      # gbrain schedule list|run|pause|tail (Phase 5)
+
+docs/openclaw/
+  ADOPTION.md                      # written in Phase 7
+```
+
+### Replaced / removed
+- `src/core/enrichment-service.ts` — folded into `enrichment/orchestrator.ts`
+- `src/core/embedding.ts` — moved into `resolvers/builtin/embedding/openai.ts`
+- `src/core/transcription.ts` — moved into `resolvers/builtin/transcription/`
+
+### Extended
+- `src/core/engine.ts` — add `getResolverRegistry()`, `getWriter()`, `getScheduler()`
+- `src/core/operations.ts` — unify with ResolverContext; every operation validator reusable by resolvers
+- `src/core/types.ts` — add `completeness: number`, `sourcedBy: string[]`, `lastVerified: Date`
+
+---
+
+## 10. Testing Strategy
+
+### Contract tests
+Every Resolver implementation tested against the interface spec. Table-driven: run the same suite against `openai_embedding`, `x_handle_to_tweet`, etc. Ensures plugin authors can't ship broken resolvers.
+
+### Property tests
+- **Idempotency:** running a ScheduledResolver twice with the same state produces the same output and doesn't double-write.
+- **Atomicity:** a BrainWriter transaction that throws mid-flight leaves the brain bit-for-bit identical to pre-transaction.
+- **Deterministic scaffolds:** given the same resolver outputs, the Scaffolder produces byte-identical citations/links.
+
+### Integration tests
+- `EnrichmentOrchestrator` end-to-end against PGLite (in-memory, no API keys) with mocked resolver registry.
+- `Scheduler` with fake clock + quiet-hours scenarios.
+- BrainWriter transaction rollback on validator failure.
+
+### Chaos tests
+- Kill the process mid-enrichment; next run must resume cleanly.
+- Simulate API timeout mid-transaction; transaction must roll back completely.
+- Corrupted state file; scheduler must escalate, not silently skip.
+
+### Regression tests vs. Garry's OpenClaw behavior
+For each OpenClaw pattern we port (e.g. X-handle → tweet URL), a regression test proves the new resolver produces the same answer on real-world inputs from the brain audit. This is the "your OpenClaw would adopt" proof.
+
+---
+
+## 11. Open Questions (flagged for CEO re-review)
+
+1. **Scope shape.** Is this the right four-layer decomposition, or are some layers better left to OpenClaw (e.g. Scheduling lives above GBrain, not in it)?
+2. **Phase 3 user-value break.** Does Phase 3 (user-visible `gbrain integrity`) ship early enough, or do we need an even smaller MVP?
+3. **LLM-as-resolver.** Should `text_to_entities` be a Resolver, or does that blur the "code vs LLM" line the invariant relies on?
+4. **Plugin format.** YAML + TS module (§3.5) vs. pure TS module with decorator-style metadata. Latter is more type-safe; former is more discoverable.
+5. **Cross-resolver transactions.** Do we support "atomic fetch-from-Perplexity + write-to-brain" at the L2 layer? Current design says yes; implementation is tricky (Perplexity call isn't rollbackable).
+6. **OpenClaw bridge scope.** Phase 7 `gbrain claw-bridge` — is that worth a phase of its own, or should adoption be documentation-only?
+7. **Completeness rubric coverage.** Do we define rubrics for all 9 PageTypes upfront, or ship people/company/meeting first and extend incrementally?
+8. **Budget config UX.** Hard daily cap is strict; should we also expose a soft-cap warning mode, and how is the cap set (env var? config file? prompt on first use?)
+9. **Backwards compat.** `src/commands/publish.ts` and `src/commands/backlinks.ts` have been running cleanly for weeks. Refactoring through BrainWriter carries migration risk. Acceptable?
+10. **Existing TODOS alignment.** `TODOS.md` has P0 "Runtime MCP access control" and P2 security hardening. The new RuntimeContext.remote flag interacts with both — do we fold MCP access control into Phase 0 or keep separate?
+
+---
+
+## 12. Verification (the "your OpenClaw would adopt" test)
+
+The design succeeds iff:
+
+- [ ] A user can add a new resolver by dropping a YAML + TS module in `~/.gbrain/resolvers/` without editing GBrain source.
+- [ ] Your OpenClaw can delete `scripts/x-api-client.mjs` and replace all callers with 1-line `await registry.resolve('x_handle_to_tweet', ...)`.
+- [ ] No brain page can be written with a bare tweet reference, a missing back-link, or an unverified URL (validators catch it pre-commit).
+- [ ] Running `gbrain integrity --auto --confidence 0.8` over a real brain fixes ≥1,000 of the 1,424 known bare-tweet citations without human review.
+- [ ] Full E2E test suite passes on both PGLite + Postgres engines.
+- [ ] The Knowledge Runtime ships across 7 phases with each phase individually shippable and reversible.

docs/designs/MINIONS_AGENT_ORCHESTRATION.md

@@ -0,0 +1,448 @@
+---
+status: ACTIVE
+---
+# CEO Plan: Minions as Universal Agent Orchestration Protocol
+Generated by /plan-ceo-review on 2026-04-15
+Branch: garrytan/minions-jobs | Mode: SCOPE EXPANSION
+Repo: garrytan/gbrain
+
+## Vision
+
+### 10x Check
+Instead of "GBrain has a queue, OpenClaw uses it," make Minions a universal agent
+orchestration protocol. Any platform (OpenClaw, Hermes, Claude Code, Codex, custom
+scripts) submits, monitors, steers, and composes agents through the same Postgres-native
+protocol. GBrain IS the agent control plane.
+
+### Platonic Ideal (aspirational North Star, NOT in v1 scope)
+Open a terminal, type `gbrain jobs dashboard`. See every agent across every platform.
+Their progress, tool calls, token spend. Click any agent for full execution trace.
+Type a message to redirect a running agent mid-flight. See the governor's decisions
+visualized. Run A/B tests between agent configurations. The feeling: complete
+situational awareness of your AI workforce.
+
+**Note:** The dashboard, A/B testing, and visual governor are future phases. This plan
+builds the primitives they would sit on top of: real-time events, structured progress,
+token accounting, inbox with ack, and session transcripts.
+
+## Scope Decisions
+
+| # | Proposal | Effort | Decision | Reasoning |
+|---|----------|--------|----------|-----------|
+| 1 | pg LISTEN/NOTIFY real-time events | S | ACCEPTED | Sub-second event delivery vs 5s polling. Every platform benefits. |
+| 2 | Structured progress protocol | S | ACCEPTED | Standard progress makes unified dashboard possible. |
+| 3 | Job cost tracking (token accounting) | M | ACCEPTED | Token cost is #1 thing users want to know about agent work. |
+| 4 | Job replay | S | ACCEPTED | Small surface area, high utility for debugging failures. |
+| 5 | Job groups / waves | M | DEFERRED | Parent-child already provides grouping. Overlap concern. |
+| 6 | Inbox acknowledgment (read receipts) | S | ACCEPTED | Without it, inbox is fire-and-forget — same problem we're fixing. |
+| 7 | Universal agent protocol | S | ACCEPTED | Design framing, not extra code. Platform-agnostic naming/docs. |
+| 8 | Session transcript capture | M | ACCEPTED | Full audit trail of every agent run. |
+
+## Accepted Scope — Implementation Detail
+
+### 0a. Pause/resume (from base plan)
+
+**Schema:** Add `'paused'` to `MinionJobStatus` (already in migration v6 constraint).
+
+**New methods:**
+- `MinionQueue.pauseJob(id): MinionJob | null`
+  Transitions `waiting` or `active` → `paused`. For `active` jobs, clears `lock_token`
+  and `lock_until` (worker will detect lock loss and stop). Returns null if job not
+  in pausable state.
+- `MinionQueue.resumeJob(id): MinionJob | null`
+  Transitions `paused` → `waiting`. Resets for claiming. Returns null if not paused.
+
+**Worker integration:** Worker's lock renewal loop checks `isActive()`. When a job
+is paused, the lock is cleared, so `renewLock()` returns false and the worker stops
+execution gracefully (same path as stall detection). The job's progress and state
+are preserved in the DB for when it resumes.
+
+**MCP operations:** `pause_job`, `resume_job` (added in Step 3 of implementation plan).
+
+**PGLite compatibility:** Full.
+
+### 0b. Resource governor (from base plan)
+
+**New file:** `src/core/minions/governor.ts`
+
+```typescript
+interface GovernorConfig {
+  maxConcurrency: number;       // ceiling
+  minConcurrency: number;       // floor (default 1)
+  checkIntervalMs: number;      // default 10000
+  cpuThreshold: number;         // default 0.80 (80%)
+  memoryThreshold: number;      // default 0.85 (85%)
+  circuitBreakerMemory: number; // default 0.90 (90%)
+}
+
+class ResourceGovernor {
+  getEffectiveConcurrency(): number;  // current allowed concurrency
+  start(): void;                       // begin polling system metrics
+  stop(): void;                        // stop polling
+  onCircuitBreak(cb: (jobId) => void): void; // kill callback
+}
+```
+
+**System metrics:** Reuse `getSystemLoad()` from `src/core/backoff.ts` (already
+implements CPU and memory checks). Add event loop lag measurement via
+`perf_hooks.monitorEventLoopDelay()`.
+
+**Worker integration:** `MinionWorker.start()` consults `governor.getEffectiveConcurrency()`
+before claiming new jobs. If current in-flight count >= effective concurrency, skip claim.
+
+**Circuit breaker:** If memory > 90%, governor calls `onCircuitBreak` with the
+lowest-priority active job ID. Worker cancels that job via `failJob()` with
+`UnrecoverableError("circuit breaker: memory pressure")`.
+
+**Prerequisite:** Concurrent job processing must be implemented first (see
+Concurrency Note below).
+
+**PGLite compatibility:** Full (governor is app-level, not DB-level).
+
+### 1. pg LISTEN/NOTIFY (real-time events)
+
+**Schema:** No new columns. Add NOTIFY triggers to state transitions.
+
+**SQL trigger:**
+```sql
+CREATE OR REPLACE FUNCTION notify_minion_job_change() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify('minion_jobs', json_build_object(
+    'id', NEW.id, 'status', NEW.status, 'name', NEW.name,
+    'queue', NEW.queue, 'prev_status', COALESCE(OLD.status, 'new')
+  )::text);
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER minion_job_notify AFTER INSERT OR UPDATE OF status ON minion_jobs
+  FOR EACH ROW EXECUTE FUNCTION notify_minion_job_change();
+```
+
+**New method:** `MinionQueue.subscribe(callback: (event) => void): () => void`
+Returns unsubscribe function. Requires direct Postgres connection (NOT pooled).
+
+**PGLite compatibility:** PGLite does NOT support LISTEN/NOTIFY. Fallback: polling
+via `getJob()` at configurable interval (default 2s). The `subscribe()` method
+detects engine type and uses polling fallback automatically.
+
+**Supabase constraint:** Requires direct connection (port 5432), not pgBouncer
+pooler (port 6543). Document in skill file and setup guide.
+
+### 2. Structured progress protocol
+
+**TypeScript interface (convention, not enforced at DB level):**
+```typescript
+interface AgentProgress {
+  step: number;           // current step (1-based)
+  total: number;          // total expected steps (0 = unknown)
+  message: string;        // human-readable status
+  tokens_in: number;      // cumulative input tokens
+  tokens_out: number;     // cumulative output tokens
+  last_tool: string;      // name of last tool called
+  started_at: string;     // ISO 8601 when this step started
+}
+```
+
+**Storage:** Existing `progress JSONB` column. No schema change needed.
+Handlers use `ctx.updateProgress(agentProgress)`. Non-agent jobs can use
+any JSONB shape (backward compatible).
+
+**Validation:** `updateProgress()` accepts any JSONB. The `AgentProgress`
+interface is a convention enforced by the agent handler, not by the queue.
+
+### 3. Job cost tracking (token accounting)
+
+**Schema changes (migration v6):**
+```sql
+ALTER TABLE minion_jobs ADD COLUMN tokens_input INTEGER DEFAULT 0;
+ALTER TABLE minion_jobs ADD COLUMN tokens_output INTEGER DEFAULT 0;
+ALTER TABLE minion_jobs ADD COLUMN tokens_cache_read INTEGER DEFAULT 0;
+ALTER TABLE minion_jobs ADD COLUMN cost_usd NUMERIC(10,6) DEFAULT 0;
+```
+
+**New method:** `MinionQueue.updateTokens(id, lockToken, { input, output, cache_read, cost_usd })`
+Accumulates (adds to existing values, does not replace).
+
+**Parent rollup:** When `completeJob()` is called, if `parent_job_id` is set,
+add this job's token counts to the parent's via:
+```sql
+UPDATE minion_jobs SET
+  tokens_input = tokens_input + $child_input,
+  tokens_output = tokens_output + $child_output,
+  tokens_cache_read = tokens_cache_read + $child_cache,
+  cost_usd = cost_usd + $child_cost
+WHERE id = $parent_id;
+```
+
+**PGLite compatibility:** Full support (standard columns).
+
+### 4. Job replay
+
+**New method:** `MinionQueue.replayJob(id, dataOverrides?: Record<string, unknown>): MinionJob`
+
+Implementation: Read the completed/failed/dead job. Create a NEW job with:
+- Same `name`, `queue`, `priority`, `max_attempts`, `backoff_type`, `backoff_delay`
+- `data` = deep merge of original data + overrides
+- Fresh `attempts_made: 0`, `status: 'waiting'`
+- `parent_job_id` = null (replay is a new top-level job, not a child)
+- Does NOT clone children (replay is a single job, not a DAG)
+
+**Constraint:** Only works on terminal statuses (completed/failed/dead).
+Returns the new job record.
+
+**Idempotency:** Each replay creates a distinct new job. No deduplication.
+If the original had side effects, the replay may repeat them. Document this
+in the skill file as a user responsibility.
+
+### 5. Inbox (sidechannel messaging)
+
+**Schema changes (migration v6):**
+```sql
+ALTER TABLE minion_jobs ADD COLUMN inbox JSONB DEFAULT '[]';
+```
+
+**Inbox message format:**
+```typescript
+interface InboxMessage {
+  id: string;          // UUIDv4
+  sent_at: string;     // ISO 8601
+  read_at: string | null;  // null until worker reads it
+  sender: string;      // 'parent' | 'user' | job ID
+  payload: unknown;    // arbitrary directive
+}
+```
+
+**New methods:**
+- `MinionQueue.sendMessage(jobId, payload, sender?): InboxMessage`
+  Appends message to inbox array via atomic JSONB append
+  (`inbox = inbox || $1::jsonb`), not read-modify-write. Returns the message with id + sent_at.
+- `MinionQueue.readInbox(jobId, lockToken): InboxMessage[]`
+  Returns unread messages (read_at = null). Marks them as read (sets read_at).
+  Token-fenced: only the worker holding the lock can read.
+
+**Worker integration:** Agent handler calls `readInbox()` on each iteration.
+If messages exist, injects them into the agent's context as system messages.
+
+**PGLite compatibility:** Full support (standard JSONB column).
+
+### 6. Inbox acknowledgment (read receipts)
+
+Built into the inbox design above. The `read_at` field on each `InboxMessage`
+provides the receipt. `sendMessage()` returns the message ID; the sender can
+later check `getJob(id)` and inspect `inbox` to see which messages have been
+read.
+
+No additional schema or methods needed beyond what's in #5.
+
+### 7. Universal agent protocol (platform-agnostic framing)
+
+**This is a design decision, not code.** It means:
+
+1. The skill file (`skills/minion-orchestrator/SKILL.md`) is written for ANY
+   agent platform, not just OpenClaw. Examples show MCP tool calls, not
+   OpenClaw-specific commands.
+
+2. The agent handler (`agent-handler.ts`) accepts a generic interface:
+   ```typescript
+   interface AgentJobData {
+     prompt: string;
+     tools?: string[];        // MCP tool names
+     model?: string;          // e.g., 'claude-opus-4-6', 'gpt-4o'
+     context?: string;        // additional context
+     platform?: string;       // 'openclaw' | 'hermes' | 'claude-code' | 'custom'
+     max_iterations?: number; // agent loop budget
+   }
+   ```
+
+3. The OpenClaw plugin is ONE consumer. Hermes, Claude Code extensions,
+   or custom scripts can submit `agent` jobs through the same MCP operations.
+
+4. **NOT in v1 scope:** Multi-tenant auth, cross-network connectivity,
+   protocol versioning, API key isolation. These are Phase 2 concerns when
+   actual multi-platform usage materializes. v1 is single-user, single-brain.
+
+### Agent Handler Architecture (critical design decision)
+
+The agent handler does NOT live in GBrain. GBrain provides the queue infrastructure
+and a clean handler contract. The actual agent execution lives in the platform plugin.
+
+```
+GBrain (this repo):
+  MinionQueue  — queue/claim/complete/inbox/tokens/NOTIFY
+  MinionWorker — poll/lock/stall/governor framework
+  Handler contract — AgentJobData interface + MinionJobContext
+
+OpenClaw plugin (separate repo):
+  Registers "agent" handler with MinionWorker
+  Handler calls OpenClaw's PI agent core (the actual LLM loop)
+  Each iteration: readInbox → inject as system message, updateProgress, updateTokens
+  Completion: store result + session transcript in job.result + job.stacktrace
+
+GBrain ships a test/echo handler for unit testing only.
+```
+
+**Handler contract (GBrain side):**
+```typescript
+// The handler receives this context (already exists in worker.ts)
+interface MinionJobContext {
+  id: number;
+  name: string;
+  data: Record<string, unknown>;  // AgentJobData when name="agent"
+  attempts_made: number;
+  updateProgress(progress: unknown): Promise<void>;
+  updateTokens(tokens: TokenUpdate): Promise<void>;  // NEW
+  log(message: string | TranscriptEntry): Promise<void>;
+  isActive(): Promise<boolean>;
+  readInbox(): Promise<InboxMessage[]>;  // NEW
+}
+```
+
+**Why this is right:** GBrain is orchestration, not execution. OpenClaw has the
+PI agent core. Hermes has AIAgent. Claude Code has its own loop. Each platform
+brings its own engine and registers a handler. GBrain manages lifecycle, progress,
+steering, cost tracking, and persistence around it.
+
+### 8. Session transcript capture
+
+**Extends existing stacktrace mechanism.** The `stacktrace` field (JSONB array
+of strings) already captures log messages. Session transcripts use the same
+field with structured entries:
+
+```typescript
+type TranscriptEntry =
+  | { type: 'log'; message: string; ts: string }
+  | { type: 'tool_call'; tool: string; args_size: number; result_size: number; ts: string }
+  | { type: 'llm_turn'; model: string; tokens_in: number; tokens_out: number; ts: string }
+  | { type: 'error'; message: string; stack?: string; ts: string };
+```
+
+**Storage:** Existing `stacktrace JSONB` column. No schema change.
+The agent handler appends `TranscriptEntry` objects instead of plain strings.
+Backward compatible: non-agent jobs continue appending strings.
+
+**Size concern:** Long agent runs could generate large transcripts. Add a
+`max_transcript_entries` option (default 1000) that rotates oldest entries
+when exceeded (FIFO). The full transcript for forensic analysis can be
+stored as a brain file via `gbrain files upload-raw`.
+
+## Schema Migration v6
+
+All schema changes are additive (ALTER TABLE ADD COLUMN). No backfill needed.
+Existing jobs continue to work with default values.
+
+```sql
+-- Migration v6: Agent orchestration primitives
+ALTER TABLE minion_jobs ADD COLUMN IF NOT EXISTS tokens_input INTEGER DEFAULT 0;
+ALTER TABLE minion_jobs ADD COLUMN IF NOT EXISTS tokens_output INTEGER DEFAULT 0;
+ALTER TABLE minion_jobs ADD COLUMN IF NOT EXISTS tokens_cache_read INTEGER DEFAULT 0;
+
+-- Separate inbox table (not JSONB on job row)
+CREATE TABLE IF NOT EXISTS minion_inbox (
+  id SERIAL PRIMARY KEY,
+  job_id INTEGER NOT NULL REFERENCES minion_jobs(id) ON DELETE CASCADE,
+  sender TEXT NOT NULL,
+  payload JSONB NOT NULL,
+  sent_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  read_at TIMESTAMPTZ
+);
+CREATE INDEX IF NOT EXISTS idx_minion_inbox_unread
+  ON minion_inbox (job_id) WHERE read_at IS NULL;
+
+-- Status constraint update: add 'paused'
+ALTER TABLE minion_jobs DROP CONSTRAINT IF EXISTS minion_jobs_status_check;
+ALTER TABLE minion_jobs ADD CONSTRAINT minion_jobs_status_check
+  CHECK (status IN ('waiting','active','completed','failed','delayed','dead','cancelled','waiting-children','paused'));
+
+-- NOTIFY trigger for real-time events (Postgres only, not PGLite)
+CREATE OR REPLACE FUNCTION notify_minion_job_change() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify('minion_jobs', json_build_object(
+    'id', NEW.id, 'status', NEW.status, 'name', NEW.name,
+    'queue', NEW.queue, 'prev_status', COALESCE(OLD.status, 'new')
+  )::text);
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER minion_job_notify AFTER INSERT OR UPDATE OF status ON minion_jobs
+  FOR EACH ROW EXECUTE FUNCTION notify_minion_job_change();
+```
+
+## PGLite Compatibility Matrix
+
+| Feature | Postgres | PGLite | Fallback |
+|---|---|---|---|
+| Pause/resume | Full | Full | — |
+| Inbox + ack | Full | Full | — |
+| Token accounting | Full | Full | — |
+| Job replay | Full | Full | — |
+| LISTEN/NOTIFY | Full | NO | Polling (2s interval) |
+| NOTIFY trigger | Full | NO | Skipped in PGLite schema |
+| Structured progress | Full | Full | — |
+| Session transcripts | Full | Full | — |
+| Resource governor | Full | Full | — |
+| Worker daemon | Full | NO (existing limitation) | — |
+
+## Concurrency Note
+
+The current `MinionWorker.start()` processes jobs sequentially (one at a time)
+despite `concurrency` being declared in `MinionWorkerOpts`. Implementing actual
+concurrent job processing (Promise pool) is a prerequisite for the resource
+governor to be meaningful. The governor adjusts effective concurrency, which
+requires actual concurrent processing to exist.
+
+**Action:** Implement concurrent job processing in `worker.ts` before or as
+part of the governor step. Use a semaphore pattern: maintain up to N in-flight
+promises, claim new jobs as slots free up.
+
+## Outside Voice Decisions (from adversarial review)
+
+1. **AbortController for pause/resume** — Handler contract gets `signal: AbortSignal`.
+   Pause clears lock AND signals abort. Handler must check `signal.aborted` on each
+   iteration. Without this, pausing active jobs creates duplicate execution.
+
+2. **Drop cost_usd column** — Token counts (input/output/cache_read) are stable facts.
+   USD pricing is volatile. Compute cost at display/read time from a pricing table,
+   not at write time. Removes `cost_usd NUMERIC(10,6)` from migration v6.
+
+3. **Separate minion_inbox table** — Instead of JSONB array on job row, use a dedicated
+   table for inbox messages. Avoids row bloat from rewriting entire inbox on every send.
+   Properly concurrent-safe with standard INSERT (no JSONB append concerns).
+   ```sql
+   CREATE TABLE minion_inbox (
+     id SERIAL PRIMARY KEY,
+     job_id INTEGER NOT NULL REFERENCES minion_jobs(id) ON DELETE CASCADE,
+     sender TEXT NOT NULL,
+     payload JSONB NOT NULL,
+     sent_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+     read_at TIMESTAMPTZ
+   );
+   CREATE INDEX idx_minion_inbox_unread ON minion_inbox (job_id) WHERE read_at IS NULL;
+   ```
+
+4. **One release, not two** — Ship all features in one migration (v6). User prefers
+   cohesive release over incremental delivery for this feature set.
+
+5. **Selective column projection** — Fix SELECT * queries in getJobs(), claim(),
+   handleStalled() to exclude stacktrace column. Include stacktrace only in getJob()
+   detail view. Prevents transcript bloat from affecting query performance.
+
+## Future Phases (accepted trajectory)
+
+- **Phase 2: Dashboard CLI** — `gbrain jobs dashboard` live TUI showing all agents.
+  Enabled by: LISTEN/NOTIFY, structured progress, token accounting.
+- **Phase 3: Multi-tenant auth** — Runtime MCP access control, per-platform API keys.
+  Enabled by: platform-agnostic framing, sender validation on inbox.
+- **Phase 4: Agent composition patterns** — Map-reduce, pipeline, approval gates as
+  first-class primitives. Enabled by: parent-child DAGs, inbox sidechannel.
+
+## Deferred to TODOS.md
+- Job groups / waves (parent-child covers this; revisit if real grouping need emerges)
+- cost_usd column (compute from pricing table at read time when pricing API exists)
+
+## Key Premises Confirmed
+1. GBrain is intentionally evolving from knowledge brain to agent infrastructure (user confirmed)
+2. Coupling between OpenClaw and GBrain's Postgres is acceptable (OpenClaw already depends on GBrain)
+3. Full Infrastructure approach (all 8+ steps) selected over Minimal Viable or Sidecar Tracking
+4. Prior learning [agent-dx-instruction-layer] validates that the teaching layer (skill + evals) is mandatory

docs/embedding-migrations.md

@@ -0,0 +1,105 @@
+# Switching embedding models or dimensions on an existing brain
+
+GBrain stores embeddings in a fixed-dimension `vector(N)` column on
+`content_chunks`. If you switch to a model with a different dimension
+(e.g. `text-embedding-3-large` 1536 → `voyage-multilingual-large-2` 2048,
+or back to a smaller model like `nomic-embed-text` 768), the on-disk
+column type doesn't change automatically.
+
+`gbrain init` and `gbrain doctor` both detect and refuse to silently
+proceed in this case. This doc is the recipe they point at.
+
+## Why we don't do this automatically
+
+Switching dimensions requires:
+
+1. Dropping the HNSW vector index (pgvector won't survive an `ALTER COLUMN TYPE`).
+2. Altering the column type.
+3. Wiping every existing embedding (the old vectors are unusable in the new space).
+4. Re-embedding the entire corpus (can take hours on a 50K-page brain and costs $1-100 in API calls depending on model).
+5. Conditionally recreating the index (HNSW supports up to 2000 dimensions per pgvector; above that you must use exact scans).
+
+That's not an upgrade-time auto-run. It's a deliberate, expensive
+operation. Run it when you've decided you actually want the new model.
+
+## Recipe — manual `psql` against your brain
+
+Replace `<NEW_DIMS>` with your target dimension count.
+
+```sql
+BEGIN;
+
+-- 1. Drop the HNSW index. It can't survive the column type change.
+DROP INDEX IF EXISTS idx_chunks_embedding;
+
+-- 2. Alter the column type. (You can DROP COLUMN + ADD COLUMN instead
+--    if the existing data is already gone — same end state.)
+ALTER TABLE content_chunks ALTER COLUMN embedding TYPE vector(<NEW_DIMS>);
+
+-- 3. Clear stale embeddings so they don't survive into the new space.
+--    Either truncate (faster, drops all chunks) or null out (preserves
+--    chunk text so re-embed regenerates without re-chunking):
+UPDATE content_chunks SET embedding = NULL, embedded_at = NULL;
+
+-- 4. Recreate the HNSW index ONLY IF dims <= 2000. Above that, leave it
+--    indexless and rely on exact scans (gbrain searchVector handles this
+--    automatically — search just gets slower, not broken).
+-- For dims <= 2000 (e.g. 1024, 1536, 768):
+CREATE INDEX IF NOT EXISTS idx_chunks_embedding
+  ON content_chunks USING hnsw (embedding vector_cosine_ops);
+-- For dims > 2000 (e.g. 2048 Voyage 4 Large): skip step 4.
+
+COMMIT;
+```
+
+Then update gbrain's config so it knows the new dim:
+
+```bash
+gbrain config set embedding_model <model>
+gbrain config set embedding_dimensions <NEW_DIMS>
+```
+
+And re-embed the corpus:
+
+```bash
+gbrain embed --stale
+```
+
+## PGLite (local brain)
+
+Same recipe, but you connect to the embedded database differently:
+
+```bash
+gbrain config get database_url   # confirm engine: pglite
+# Open a psql-equivalent — for PGLite, the easiest path is to write a small
+# script that imports PGLiteEngine and runs the SQL via engine.executeRaw.
+# Or migrate to Postgres temporarily (gbrain migrate --to supabase) if you
+# want a real psql connection.
+```
+
+For most PGLite users the simpler path is to **wipe and re-init** if your
+corpus is small enough that re-syncing is faster than hand-crafting the
+migration:
+
+```bash
+mv ~/.gbrain/brain.pglite ~/.gbrain/brain.pglite.bak
+gbrain init --pglite --embedding-dimensions <NEW_DIMS>
+gbrain sync   # re-imports your brain repo from disk
+```
+
+## Verify
+
+After the recipe lands, `gbrain doctor --fast` should report green and
+`gbrain doctor` (full) should say check 8b passes:
+
+```
+✓ embedding_provider     dim parity: config 768 / column vector(768) / live probe 768
+```
+
+If it doesn't, file an issue with the doctor output and the SQL you ran.
+
+## v0.29+ plans
+
+`gbrain migrate-embedding-dim --to <N>` is a tracked TODO. It will run
+the recipe above with progress reporting + an explicit confirmation
+gate. Until that lands, this manual recipe is the canonical path.

docs/eval-bench.md

@@ -0,0 +1,224 @@
+# Running real-world eval benchmarks against your gbrain changes
+
+Audience: gbrain maintainers and contributors. If you're touching retrieval
+(search, ranking, embeddings, intent classification, query expansion, source
+boost, hybrid fusion), this is the doc.
+
+For the **NDJSON wire format** consumed by gbrain-evals, see
+[`eval-capture.md`](./eval-capture.md). This doc is the human dev loop
+that lives on top of that format.
+
+## Prerequisite: turn on contributor mode
+
+Capture is **off by default** for production users (privacy-positive — no
+surprise data accumulation). Contributors flip it on with one line:
+
+```bash
+# In ~/.zshrc or ~/.bashrc:
+export GBRAIN_CONTRIBUTOR_MODE=1
+```
+
+Verify:
+
+```bash
+gbrain query "anything" >/dev/null
+psql $DATABASE_URL -c 'SELECT count(*) FROM eval_candidates'   # should be > 0
+```
+
+To override (force on/off regardless of env var), edit `~/.gbrain/config.json`:
+
+```json
+{"eval": {"capture": true}}    // force on
+{"eval": {"capture": false}}   // force off
+```
+
+Explicit config beats the env var both directions.
+
+## The 4-command loop
+
+```bash
+# ① Capture: writes to eval_candidates whenever CONTRIBUTOR_MODE is set.
+#   Inspect what's been collected:
+gbrain doctor                                     # surfaces capture failures
+psql $DATABASE_URL -c 'SELECT count(*) FROM eval_candidates'
+
+# ② Snapshot: freeze a baseline before your code change.
+gbrain eval export --since 7d > baseline.ndjson
+
+# ③ Code change: do whatever you want — tune RRF_K, swap embed model, edit
+#    hybrid.ts, add a new boost source, change the intent classifier.
+
+# ④ Replay: re-run every captured query against the current build.
+gbrain eval replay --against baseline.ndjson
+```
+
+Output:
+
+```
+Replaying 247 captured queries…
+  ...25/247
+  ...50/247
+  ...
+Replayed 247 of 247 captured queries (0 skipped, 0 errored)
+Mean Jaccard@k:    0.927
+Top-1 stability:   91.5%
+Mean latency Δ:    +14ms (current vs captured)
+
+Top 5 regression(s):
+  jaccard=0.20  captured=12  current=3   "find every reference to widget-co"
+  jaccard=0.43  captured=14  current=8   "show me everything tagged for review"
+  jaccard=0.50  captured=8   current=4   "what did alice say about the spec"
+  ...
+```
+
+Three numbers tell you whether the change is safe to land:
+
+| Metric | What it means | Healthy range |
+|---|---|---|
+| **Mean Jaccard@k** | Average overlap between captured retrieved slugs and current run's slugs. 1.0 = identical sets. | ≥0.85 for "neutral" changes. <0.7 means major retrieval shift. |
+| **Top-1 stability** | Fraction of queries whose #1 result didn't change. | ≥85% for tuning passes. <70% means top-of-funnel broke. |
+| **Mean latency Δ** | Current minus captured. Positive = slower now. | Within ±50ms of captured. >2× anywhere = regression alarm. |
+
+## What it actually does
+
+`gbrain eval replay` reads your NDJSON snapshot and, for each row:
+
+1. Re-executes the same op (`searchKeyword` for `tool_name='search'`,
+   `hybridSearch` for `tool_name='query'`) with the captured `detail` and
+   `expand_enabled` values threaded back in.
+2. Captures the current `retrieved_slugs` (deduped, in result order).
+3. Computes set-Jaccard between captured and current slug sets.
+4. Records top-1 match (was the #1 result the same slug?).
+5. Records latency delta vs captured `latency_ms`.
+
+It does NOT compute MRR or nDCG — those need ground-truth relevance labels,
+not a baseline comparison. For metric-against-truth eval, use
+`gbrain eval --qrels <path>` (the legacy IR-eval path, still supported). The
+replay tool answers a different question: "did my code change move
+retrieval, and which queries did it move most?"
+
+## Best-effort by design
+
+Replay is not pure. Three things can drift between capture and replay:
+
+1. **Brain state** — your brain probably has more pages now than when the
+   snapshot was taken. Unless you explicitly seed a fixed corpus, mean
+   Jaccard will drop simply because new pages are eligible.
+2. **Embedding source** — if you changed `OPENAI_API_KEY` between capture
+   and replay (or the embedding model rotated), vector-path results drift
+   even with identical code.
+3. **Capture cap** — captured `retrieved_slugs` is a deduped set; it doesn't
+   preserve internal ranking metadata. Two tools can return the same slug
+   set with different scores — Jaccard will say 1.0, but a downstream
+   consumer that orders by score may behave differently.
+
+The metrics are **regression alarms on real queries**, not a hash check.
+Pair them with manual inspection of the top regressions.
+
+## Cost
+
+Every `query` row in the snapshot embeds the query string via OpenAI to run
+the vector half of `hybridSearch`. Cost is identical to a normal `gbrain
+query` invocation — text-embedding-3-large at OpenAI list price, batched
+inside a single replay row.
+
+If you're iterating locally and don't want to pay per change, use
+`--limit 50` to cap rows replayed. The 50 most recent rows are usually
+enough to catch direction; expand for the final pre-merge run.
+
+```bash
+# Iteration mode — 50 most recent queries
+gbrain eval replay --against baseline.ndjson --limit 50
+
+# Pre-merge — full snapshot
+gbrain eval replay --against baseline.ndjson --top-regressions 20
+```
+
+## CI integration
+
+```bash
+gbrain eval replay --against baseline.ndjson --json > replay.json
+jq -e '.summary.mean_jaccard >= 0.85' replay.json || exit 1
+jq -e '.summary.top1_stability_rate >= 0.85' replay.json || exit 1
+```
+
+Stable JSON shape (schema_version: 1):
+
+```json
+{
+  "schema_version": 1,
+  "summary": {
+    "rows_total": 247,
+    "rows_replayed": 247,
+    "rows_skipped": 0,
+    "rows_errored": 0,
+    "mean_jaccard": 0.927,
+    "top1_stability_rate": 0.915,
+    "mean_latency_delta_ms": 14,
+    "rows_over_2x_latency": 0
+  }
+}
+```
+
+`--verbose` adds a `results: [...]` array with one entry per replayed row
+(useful for piping into jq or a notebook for deeper analysis).
+
+## When to run this
+
+Before merging anything that touches:
+
+- `src/core/search/hybrid.ts` (RRF, fusion, dedup, two-pass retrieval)
+- `src/core/search/source-boost.ts` / `sql-ranking.ts` (per-source ranking)
+- `src/core/search/intent.ts` (auto-detail classification)
+- `src/core/search/expansion.ts` (Haiku query expansion)
+- `src/core/search/dedup.ts` (cross-page result collapse)
+- `src/core/embedding.ts` or any embedding model swap
+- `src/core/operations.ts` `query` or `search` op handlers (capture surface)
+- `src/core/postgres-engine.ts` / `pglite-engine.ts` `searchKeyword` /
+  `searchVector` SQL
+
+Skip for: schema-only migrations, doc changes, tests-only PRs, CLI ergonomics
+that don't touch retrieval.
+
+## Building your own corpus
+
+If you don't have captured traffic yet (fresh install, can't dogfood for a
+week before merging), you can hand-author an NDJSON file:
+
+```jsonl
+{"schema_version":1,"id":1,"tool_name":"query","query":"who is alice","retrieved_slugs":["people/alice","people/alice-bio"],"expand_enabled":false,"detail":null,"latency_ms":0,"remote":false}
+{"schema_version":1,"id":2,"tool_name":"search","query":"acme deal","retrieved_slugs":["deals/acme-seed","companies/acme"],"latency_ms":0,"remote":false}
+```
+
+Then run `gbrain eval replay --against handcrafted.ndjson` to confirm the
+authoritative slugs come back. This is the seam between the BrainBench-Real
+pipeline (replay against live captures) and the BrainBench fixed-fixture
+pipeline (`gbrain eval --qrels` with the sibling
+[gbrain-evals](https://github.com/garrytan/gbrain-evals) corpus).
+
+## Off-switch
+
+Two ways to disable capture:
+
+```bash
+unset GBRAIN_CONTRIBUTOR_MODE             # easy: just unset the env var
+```
+
+Or force off regardless of the env var via `~/.gbrain/config.json`:
+
+```json
+{"eval": {"capture": false}}
+```
+
+Existing `eval_candidates` rows stay until you `gbrain eval prune
+--older-than 0d` (or just drop the table).
+
+## Failure modes
+
+| What you see | What it means |
+|---|---|
+| `Mean Jaccard@k: 0.4`, top regressions all in one source dir | Source boost or hard-exclude regression on that prefix |
+| `Top-1 stability: 30%`, mean Jaccard still high | RRF tuning shifted the rank order without changing the set — re-tune `rrfK` |
+| `Mean latency Δ: +500ms`, jaccard high | Vector path got slower; check embedding API or HNSW probes |
+| `rows_errored > 0` | One or more queries threw. Inspect first 3 in human output, or `--json` to see all `error_message` fields |
+| Many `skipped: empty query` | Capture ran on rows where someone passed empty `query` — check why those were captured |

docs/eval-capture.md

@@ -0,0 +1,160 @@
+# Eval capture — NDJSON schema reference
+
+**Status:** stable from v0.21.0. Schema versioning via `schema_version`
+on every row; additive changes increment the minor version; removals
+are breaking-schema-v2.
+
+**Audience:** downstream consumers (primarily the sibling
+[gbrain-evals](https://github.com/garrytan/gbrain-evals) repo) that
+replay captured real-world queries as a BrainBench-Real fixture.
+
+## The pipeline
+
+```
+MCP / CLI / subagent tool-bridge caller
+     │
+     ▼
+src/core/operations.ts — query + search op handlers
+     │
+     │ (hybridSearch or searchKeyword)
+     │
+     ▼
+{results, meta: HybridSearchMeta}                 ┌── captureEvalCandidate
+     │                                             │    (fire-and-forget)
+     ▼                                             │
+return to caller                                   ▼
+                                            scrubPii(query) ←── src/core/eval-capture-scrub.ts
+                                                   │
+                                                   ▼
+                                           buildEvalCandidateInput
+                                                   │
+                                                   ▼
+                                           engine.logEvalCandidate
+                                                   │
+                                    ┌──────────────┴──────────────┐
+                                    │ success                     │ fail
+                                    ▼                             ▼
+                                INSERT into eval_candidates    engine.logEvalCaptureFailure
+                                                                 (reason: db_down | rls_reject |
+                                                                  check_violation |
+                                                                  scrubber_exception | other)
+```
+
+## `gbrain eval export` — the consumer contract
+
+```sh
+gbrain eval export [--since DUR] [--limit N] [--tool query|search]
+```
+
+Emits NDJSON to **stdout**. One JSON object per `\n`-terminated line.
+stderr receives progress heartbeats. Every line starts with
+`"schema_version": 1` so a forward-compat parser can fail loudly on
+schema v2 instead of silently misparsing.
+
+Typical usage from gbrain-evals:
+
+```sh
+# Snapshot the last week of real traffic for replay
+gbrain eval export --since 7d > brainbench-real.ndjson
+```
+
+```sh
+# Stream through jq for ad-hoc analysis
+gbrain eval export --tool query | jq -c 'select(.latency_ms > 500)'
+```
+
+## Row schema (v1)
+
+Every exported row has this shape. Field order in JSON output is not
+guaranteed; consumers MUST key by name, not position.
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_version` | number | Always `1` on v1 rows. Forward-compat gate. |
+| `id` | number | Autoincrement primary key. Stable across exports. |
+| `tool_name` | `"query"` \| `"search"` | Which MCP operation captured this row. |
+| `query` | string | **Already PII-scrubbed** by `scrubPii` unless `eval.scrub_pii: false`. Emails / phones / SSN / Luhn-verified credit cards / JWTs / bearer tokens replaced with `[REDACTED]`. Max length 50KB (CHECK-enforced). |
+| `retrieved_slugs` | string[] | Deduplicated slugs that came back in `SearchResult[]`. |
+| `retrieved_chunk_ids` | number[] | Every chunk id in result order (duplicates preserved — one per hit). |
+| `source_ids` | string[] | Distinct `sources.id` values across the result set (v0.18 multi-source). Empty for pre-v0.18 rows that lacked the column. |
+| `expand_enabled` | boolean \| null | Whether the caller **requested** Haiku expansion. `null` for `search` (no expansion concept). |
+| `detail` | `"low"` \| `"medium"` \| `"high"` \| null | Detail level the caller **requested**. `null` when omitted. |
+| `detail_resolved` | `"low"` \| `"medium"` \| `"high"` \| null | What `hybridSearch` **actually used** after auto-detect. `null` when neither caller nor heuristic classified. |
+| `vector_enabled` | boolean | True iff vector search actually ran. `false` when `OPENAI_API_KEY` was missing or the embed call failed. **Replay MUST respect this** — rows with `false` only exercised the keyword path. |
+| `expansion_applied` | boolean | True iff Haiku expansion actually produced variants (not just "was requested"). |
+| `latency_ms` | number | Wall-clock duration of the op handler (includes capture itself — negligible since it's fire-and-forget). |
+| `remote` | boolean | `true` for MCP callers (untrusted), `false` for local CLI. Partitions "real agent traffic" from "operator probing." |
+| `job_id` | number \| null | `OperationContext.jobId` when the caller was a subagent tool-bridge. Null for MCP + CLI. |
+| `subagent_id` | number \| null | `OperationContext.subagentId` for subagent-owned runs. |
+| `created_at` | string (ISO 8601) | UTC timestamp of insert. |
+
+## Ordering + determinism
+
+`listEvalCandidates` orders by `created_at DESC, id DESC`. Same-
+millisecond inserts tie on `created_at`; `id DESC` is the stable
+tiebreaker. Replay tools can consume rows in order and assume:
+- no duplicate rows across calls with non-overlapping `--since` windows
+- no missed rows across calls that chain `--since` windows (window end
+  of run 1 is the strict upper bound, not a soft cursor)
+
+## Schema versioning promise
+
+- **v1 (shipped v0.21.0)** — this document. All fields listed above.
+- **Additive changes** increment gbrain minor version (v0.25.0, v0.23.0
+  …) and ship with new optional fields. Consumers keyed on known fields
+  ignore unknown keys and keep working.
+- **Breaking changes** (rename, type change, removal) increment
+  `schema_version` to 2. Consumers MUST branch on `schema_version` to
+  stay compatible.
+
+## `eval_capture_failures` — companion audit table
+
+Not exported by `gbrain eval export`. Surfaced via `gbrain doctor`:
+
+```sh
+gbrain doctor   # warns when failures in last 24h > 0
+```
+
+Reason enum (stable): `db_down` | `rls_reject` | `check_violation` |
+`scrubber_exception` | `other`. Cross-process visibility is the whole
+point — `gbrain doctor` runs in its own process and reads the table
+directly, so in-process counters wouldn't work.
+
+## Config + CONTRIBUTOR_MODE
+
+Capture is **off by default** as of v0.25.0 (was on for everyone in
+earlier drafts). Two paths to turn it on:
+
+**Path A — env var (contributor opt-in, the common case):**
+
+```bash
+export GBRAIN_CONTRIBUTOR_MODE=1     # in ~/.zshrc or ~/.bashrc
+```
+
+**Path B — explicit config (`~/.gbrain/config.json`, file-plane only):**
+
+```json
+{
+  "engine": "postgres",
+  "database_url": "...",
+  "eval": {
+    "capture": true,
+    "scrub_pii": true
+  }
+}
+```
+
+Resolution order (most explicit wins):
+
+1. `eval.capture: true` in config → on
+2. `eval.capture: false` in config → off (overrides CONTRIBUTOR_MODE=1)
+3. `GBRAIN_CONTRIBUTOR_MODE === '1'` → on
+4. otherwise → off
+
+`scrub_pii` defaults to `true` independent of capture. Set
+`eval.scrub_pii: false` to preserve raw query text (only if you control
+the brain's distribution).
+
+`gbrain config set eval.capture false` does **not** work — that
+command writes the DB-plane config, and the MCP server reads the
+file-plane. Edit the JSON directly or use the env var.

docs/guides/minions-deployment-snippets/Procfile

@@ -0,0 +1,13 @@
+# Procfile — Render / Railway / Heroku.
+#
+# Fly.io users: see fly.toml.partial instead.
+#
+# Set secrets via the platform's env UI or CLI (e.g. `heroku config:set`,
+# `render env:set`, `railway variables set`). At minimum:
+#   DATABASE_URL=postgresql://...
+#   GBRAIN_ALLOW_SHELL_JOBS=1   # only if submitting shell jobs
+
+# Two-layer supervision: the platform restarts the container on host
+# events (OOM, deploy); `gbrain jobs supervisor` restarts the worker
+# on in-process crashes with exponential backoff.
+worker: gbrain jobs supervisor --concurrency 2

docs/guides/minions-deployment-snippets/fly.toml.partial

@@ -0,0 +1,24 @@
+# fly.toml — partial. Merge into your existing fly.toml.
+#
+# Set secrets once (never commit them):
+#   fly secrets set DATABASE_URL='postgresql://user:pass@host:6543/db?prepare=false'
+#   fly secrets set GBRAIN_ALLOW_SHELL_JOBS=1   # only if submitting shell jobs
+#   fly secrets set ANTHROPIC_API_KEY=...       # optional
+#
+# Two-layer supervision: Fly restarts the VM on host events; the
+# `gbrain jobs supervisor` process restarts the worker on in-process
+# crashes with exponential backoff and a structured audit trail.
+
+[processes]
+  worker = "gbrain jobs supervisor --concurrency 2"
+
+# Scale the worker process to 1 machine (job queue serializes work; more
+# machines means higher concurrency but also more Postgres connections).
+#   fly scale count worker=1
+
+# If you want the worker in its own VM size:
+# [[vm]]
+#   processes = ["worker"]
+#   memory = "512mb"
+#   cpu_kind = "shared"
+#   cpus = 1

docs/guides/minions-deployment-snippets/gbrain.env.example

@@ -0,0 +1,35 @@
+# /etc/gbrain.env — secrets + env for the gbrain worker.
+#
+# Install:
+#   sudo install -m 600 -o $GBRAIN_WORKER_USER -g $GBRAIN_WORKER_USER \
+#     gbrain.env.example /etc/gbrain.env
+#   sudoedit /etc/gbrain.env   # fill in real values
+#
+# Referenced from crontab via BASH_ENV=/etc/gbrain.env, or from systemd
+# via EnvironmentFile=/etc/gbrain.env. Never commit real secrets.
+
+# --- Required ---------------------------------------------------------------
+
+# Postgres connection string. For Supabase transaction pooler, include
+# prepare=false (see CLAUDE.md #284/#286).
+DATABASE_URL=postgresql://user:pass@host:6543/db?prepare=false
+
+# --- Required if you submit `shell` jobs ------------------------------------
+# Only the worker process needs this. Submitters do not.
+GBRAIN_ALLOW_SHELL_JOBS=1
+
+# --- Optional ---------------------------------------------------------------
+
+# LLM provider keys (needed for `subagent` handler, transcription, enrichment).
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+
+# Custom handler plugins (see docs/guides/plugin-handlers.md).
+# GBRAIN_PLUGIN_PATH=/etc/gbrain/plugins
+
+# Pool size tuning for Supabase transaction pooler (default 10; drop to 2
+# if you hit MaxClients during upgrade subprocess spawns).
+# GBRAIN_POOL_SIZE=2
+
+# Connection-level concurrency cap for Anthropic Messages API.
+# GBRAIN_ANTHROPIC_MAX_INFLIGHT=4

docs/guides/minions-deployment-snippets/systemd.service

@@ -0,0 +1,50 @@
+[Unit]
+Description=gbrain minion worker
+Documentation=https://github.com/garrytan/gbrain/blob/master/docs/guides/minions-deployment.md
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# Runs as an unprivileged user that owns the brain repo and any shell-job cwds.
+# Create with: sudo useradd --system --home /srv/gbrain --shell /usr/sbin/nologin gbrain
+User=gbrain
+Group=gbrain
+WorkingDirectory=/srv/gbrain
+
+# Env file is mode 600, owned by User=. Do not put secrets in this unit.
+EnvironmentFile=/etc/gbrain.env
+
+# Two-layer supervision: systemd restarts `gbrain jobs supervisor` on host
+# events (reboot, unit crash); the supervisor restarts `gbrain jobs work`
+# on in-process crashes with exponential backoff + structured audit.
+ExecStart=/usr/local/bin/gbrain jobs supervisor --concurrency 2
+
+# systemd restarts the supervisor on any non-zero exit. The supervisor
+# itself handles worker-level crash recovery.
+Restart=always
+RestartSec=10s
+
+# Graceful shutdown: SIGTERM → wait → SIGKILL. 30s matches worker grace
+# for in-flight jobs and the shell handler's 5s child SIGTERM window.
+KillSignal=SIGTERM
+TimeoutStopSec=30s
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=gbrain-worker
+
+# Default 1024 is tight for Bun + Postgres pool + concurrent subagent LLM calls.
+LimitNOFILE=65535
+
+# Hardening (optional — remove if they break your deployment).
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+# ReadWritePaths must include the brain workspace AND ~/.gbrain (PID file +
+# audit log written by the supervisor).
+ReadWritePaths=/srv/gbrain /home/gbrain/.gbrain
+
+[Install]
+WantedBy=multi-user.target

docs/guides/minions-deployment.md

@@ -0,0 +1,332 @@
+# Minions Worker Deployment Guide
+
+Keep `gbrain jobs work` running across crashes, reboots, and Postgres
+connection blips. Written for agents to execute line-by-line.
+
+## The problem
+
+The persistent worker can die silently from:
+
+- Database connection drops (Supabase/Postgres maintenance or network blips).
+- Lock-renewal failures → the stall detector eventually dead-letters jobs.
+- Bun process crashes with no automatic restart.
+- Internal event-loop death (PID alive, worker loop stopped).
+
+When the worker dies, submitted jobs sit in `waiting` forever. The
+canonical answer is `gbrain jobs supervisor` — a first-class CLI that
+spawns `gbrain jobs work` as a child and auto-restarts it on crash.
+
+## Worker supervision
+
+### The canonical pattern
+
+`gbrain jobs supervisor` is an auto-restarting wrapper around
+`gbrain jobs work`. It writes a PID file, restarts the worker on crash
+with exponential backoff (1s → 60s cap), emits lifecycle events to an
+audit file, and drains gracefully on SIGTERM (35s worker-drain window
+before SIGKILL). Exit codes are documented so agents can branch on them.
+
+**Typical commands:**
+
+```bash
+# Start in the foreground (blocks; Ctrl-C to stop).
+gbrain jobs supervisor --concurrency 4
+
+# Start detached — returns {"event":"started","supervisor_pid":…} on stdout.
+gbrain jobs supervisor start --detach --json
+
+# Check liveness without reading log files.
+gbrain jobs supervisor status --json
+
+# Graceful stop (SIGTERM + drain wait + SIGKILL fallback).
+gbrain jobs supervisor stop
+```
+
+**Exit codes:**
+
+| Code | Meaning |
+|---|---|
+| 0 | Clean shutdown (SIGTERM/SIGINT received, worker drained) |
+| 1 | Max crashes exceeded (worker kept dying) |
+| 2 | Another supervisor holds the PID lock |
+| 3 | PID file unwritable (permission / path error) |
+
+An agent seeing exit=2 can safely treat it as "one is already running";
+exit=1 should page a human.
+
+### Which supervisor when?
+
+The supervisor solves in-process crash recovery. Platform-level
+supervision (systemd, Fly, Render) handles host-level failures. You
+usually want both.
+
+| Environment | Recommendation |
+|---|---|
+| **Container (Fly / Railway / Render / Heroku)** | `gbrain jobs supervisor` runs as PID 1. The platform restarts the container on OOM / host loss; supervisor restarts the worker on crash. See [Fly.io](#flyio) / [Render / Railway / Heroku](#render--railway--heroku). |
+| **Linux VM with systemd** | Two-layer recommended: systemd supervises `gbrain jobs supervisor`, which in turn supervises `gbrain jobs work`. Buys you automatic restart on reboot (systemd) plus fast crash recovery (supervisor). See [systemd](#systemd). |
+| **Dev laptop / macOS** | `gbrain jobs supervisor` in a terminal. Ctrl-C stops it. No system-level setup needed. |
+
+### Variables used in this guide
+
+Substitute these once before copy-pasting any snippet.
+
+| Variable | Meaning | Typical value |
+|---|---|---|
+| `$GBRAIN_BIN` | Absolute path to the `gbrain` binary | `$(command -v gbrain)` — often `/usr/local/bin/gbrain` or `~/.bun/bin/gbrain` |
+| `$GBRAIN_WORKER_USER` | OS user that owns the worker process | the same user that ran `gbrain init`; never `root` |
+| `$GBRAIN_WORKSPACE` | `cwd` for shell jobs submitted by this deployment | absolute path, e.g. `/srv/my-brain` |
+| `$GBRAIN_ENV_FILE` | Secrets file sourced by systemd / shell | `/etc/gbrain.env` (mode 600) |
+
+### Preconditions
+
+Run these before any deployment step.
+
+```bash
+# 1. gbrain is on PATH and resolves to an absolute location.
+command -v gbrain || { echo "gbrain not on PATH. Install, then retry."; exit 1; }
+
+# 2. DATABASE_URL points at reachable Postgres.
+#    (Supervisor is Postgres-only. PGLite's exclusive file lock blocks the
+#    separate worker process. If `config.engine === 'pglite'` the CLI rejects
+#    with a clear error.)
+gbrain doctor --fast --json | jq '.checks[] | select(.name=="db_connectivity")'
+
+# 3. Schema is up to date. If version=0 or status=="fail":
+#    gbrain apply-migrations --yes
+gbrain doctor --fast --json | jq '.checks[] | select(.name=="schema_version")'
+
+# 4. If you plan to submit `shell` jobs, pass --allow-shell-jobs to the
+#    supervisor (or export GBRAIN_ALLOW_SHELL_JOBS=1 before starting).
+#    Without the flag, the shell handler is disabled at worker startup.
+```
+
+## Agent usage (OpenClaw / Hermes / Cursor / Codex)
+
+Three-command pattern an agent can drive without shell archaeology:
+
+```bash
+# Start (returns PIDs + pid_file on stdout as JSON, then detaches)
+gbrain jobs supervisor start --detach --json
+# → {"event":"started","supervisor_pid":1234,"worker_pid":1235,"pid_file":"/Users/you/.gbrain/supervisor.pid"}
+
+# Check health (machine-parseable JSON, no log scraping)
+gbrain jobs supervisor status --json
+# → {"running":true,"supervisor_pid":1234,"last_start":"2026-04-23T15:30:22Z","crashes_24h":0, ...}
+
+# Stop cleanly (SIGTERM + 35s drain + SIGKILL fallback)
+gbrain jobs supervisor stop
+```
+
+Every lifecycle event (spawn, crash, backoff, health warning, max-crashes,
+shutdown) is also written to `${GBRAIN_AUDIT_DIR:-~/.gbrain/audit}/supervisor-YYYY-Www.jsonl`
+for historical inspection. `gbrain doctor` reads that file and surfaces
+a `supervisor` check in its health report.
+
+## Deployment: systemd
+
+For long-running Linux VMs with shell access.
+
+```bash
+# Create the worker user if it doesn't exist.
+sudo useradd --system --home "$GBRAIN_WORKSPACE" --shell /usr/sbin/nologin gbrain \
+  2>/dev/null || true
+sudo mkdir -p "$GBRAIN_WORKSPACE" && sudo chown gbrain:gbrain "$GBRAIN_WORKSPACE"
+
+# Install the env file (secrets stay out of the unit file).
+sudo install -m 600 -o gbrain -g gbrain \
+  docs/guides/minions-deployment-snippets/gbrain.env.example /etc/gbrain.env
+sudoedit /etc/gbrain.env
+# Fill in DATABASE_URL, optional GBRAIN_ALLOW_SHELL_JOBS=1.
+
+# Install the unit file, substituting /srv/gbrain → your workspace path.
+sudo install -m 644 docs/guides/minions-deployment-snippets/systemd.service \
+  /etc/systemd/system/gbrain-worker.service
+sudo sed -i "s|/srv/gbrain|$GBRAIN_WORKSPACE|g" \
+  /etc/systemd/system/gbrain-worker.service
+
+sudo systemctl daemon-reload
+sudo systemctl enable --now gbrain-worker
+sudo systemctl status gbrain-worker
+journalctl -u gbrain-worker -n 50
+```
+
+The shipped unit file invokes `gbrain jobs supervisor` (not `gbrain jobs work`
+directly) so you get two-layer supervision: systemd restarts the supervisor
+on host reboot, supervisor restarts the worker on in-process crash.
+
+`Restart=always` + `RestartSec=10s` handle the supervisor-level recovery.
+The unit runs as unprivileged `gbrain` with `PrivateTmp`, `ProtectSystem=strict`,
+and `ReadWritePaths=$GBRAIN_WORKSPACE,$HOME/.gbrain` (for the PID file and
+audit log). `LimitNOFILE=65535` covers Bun + Postgres pool + concurrent
+LLM subagent calls without hitting the default 1024 cap.
+
+## Deployment: Fly.io
+
+```bash
+# Merge the [processes] block from fly.toml.partial into your fly.toml.
+cat docs/guides/minions-deployment-snippets/fly.toml.partial >> fly.toml
+# Review + edit as needed.
+
+# Set secrets (Fly handles restart on crash).
+fly secrets set DATABASE_URL='postgres://…' GBRAIN_ALLOW_SHELL_JOBS=1
+```
+
+The `[processes]` block runs `gbrain jobs supervisor` as PID 1. Fly
+restarts the container on host failure; the supervisor restarts the
+worker on in-process crash.
+
+## Deployment: Render / Railway / Heroku
+
+Drop [`Procfile`](./minions-deployment-snippets/Procfile) at the repo
+root. The shipped Procfile calls `gbrain jobs supervisor`. Set
+`DATABASE_URL` + optional `GBRAIN_ALLOW_SHELL_JOBS=1` via the platform's
+env UI or CLI.
+
+## Deployment: inline `--follow` (no persistent worker)
+
+For short deterministic scripts on a fixed schedule where you don't need
+a persistent worker between runs. Each cron run brings its own temporary
+worker. `--follow` starts one on the queue and blocks until the
+just-submitted job reaches a terminal state (`completed` / `failed` /
+`dead` / `cancelled`). 2-3 s startup overhead per job; negligible vs job
+duration for scheduled work.
+
+```bash
+GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs submit shell \
+  --queue nightly-enrich \
+  --params "{\"cmd\":\"$GBRAIN_BIN embed --stale\",\"cwd\":\"$GBRAIN_WORKSPACE\"}" \
+  --follow \
+  --timeout-ms 600000
+```
+
+Replace `gbrain embed --stale` with whichever gbrain subcommand you're
+scheduling (`sync`, `extract`, `orphans`, `doctor`, `check-backlinks`,
+`lint`, `autopilot`). For strict single-job semantics on shared queues,
+use a dedicated queue name like `nightly-enrich` above.
+
+## Upgrading from an older deployment
+
+### From `minion-watchdog.sh` (pre-v0.20)
+
+Earlier versions of this guide shipped a 68-line bash watchdog
+(`minion-watchdog.sh`). It's been replaced by `gbrain jobs supervisor`
+which handles everything the script did, plus atomic PID locking,
+structured audit events, queue-scoped health checks, and graceful
+drain on SIGTERM.
+
+**Migration:**
+
+```bash
+# 1. Stop and remove the old watchdog.
+sudo kill $(head -n1 /tmp/gbrain-worker.pid) 2>/dev/null
+sudo rm -f /usr/local/bin/minion-watchdog.sh /tmp/gbrain-worker.pid \
+           /tmp/gbrain-worker.log
+crontab -e   # delete the "*/5 * * * * /usr/local/bin/minion-watchdog.sh" line
+
+# 2. Start the supervisor (systemd users: reinstall the unit from
+#    docs/guides/minions-deployment-snippets/systemd.service, which
+#    now calls `gbrain jobs supervisor`).
+gbrain jobs supervisor start --detach --json
+# Or: sudo systemctl restart gbrain-worker
+
+# 3. Verify.
+gbrain jobs supervisor status --json
+gbrain doctor   # 'supervisor' check should report running=true
+```
+
+### Schema / migration hygiene
+
+Regardless of which deployment path you're upgrading from:
+
+1. **Stop the worker before upgrading.** `gbrain jobs supervisor stop`
+   (or `sudo systemctl stop gbrain-worker`). Skipping this risks an
+   in-flight job landing partial schema.
+2. **Run `gbrain upgrade`**. Then `gbrain apply-migrations --yes` if
+   `gbrain doctor` reports any migration as `partial` or `pending`.
+3. **If you run shell jobs:** from v0.14 onward, pass
+   `--allow-shell-jobs` to the supervisor (or keep
+   `GBRAIN_ALLOW_SHELL_JOBS=1` in `/etc/gbrain.env`). Submitters don't
+   need the flag; only the worker does.
+4. **Verify.** `gbrain doctor` should report zero `pending` or `partial`
+   migrations plus a healthy `supervisor` check. `gbrain jobs stats`
+   should show no unexplained growth in `dead` between pre- and
+   post-upgrade.
+
+## Known issues
+
+### Supabase connection drops
+
+The worker uses a single Postgres connection. If Supabase drops it
+(maintenance, connection limits, network blip), lock renewal fails
+silently. The stall detector then dead-letters the job after
+`max_stalled` misses.
+
+**Current defaults that make this worse:**
+
+- `lockDuration: 30000` (30 s) — too short for long jobs during
+  connection blips.
+- `max_stalled: 5` (schema column default — see `src/schema.sql` and
+  `src/core/pglite-schema.ts`). Five missed heartbeats before dead-letter.
+- `stalledInterval: 30000` (30 s) — checks too aggressively.
+
+**Tune per-job today.** `gbrain jobs submit` accepts `--max-stalled N`,
+`--backoff-type fixed|exponential`, `--backoff-delay <ms>`,
+`--backoff-jitter 0..1`, and `--timeout-ms N` as first-class flags
+(since v0.13.1). These write onto the job row at submit time — which is
+what `handleStalled()` reads — so per-job tuning is the real knob today.
+
+### DO NOT pass `maxStalledCount` to `MinionWorker`
+
+It's a no-op. The stall detector reads the row's `max_stalled` column
+(set at submit time), not the worker opt in `src/core/minions/worker.ts:74`.
+Use `gbrain jobs submit --max-stalled N` per-job instead.
+
+### Zombie shell children
+
+When the Bun worker crashes hard, child processes from shell jobs can
+become zombies. The supervisor's SIGTERM → 35s drain → SIGKILL window
+covers the shell handler's 5 s child-kill grace (`KILL_GRACE_MS`). For
+long-running shell jobs, prefer timeouts via `--timeout-ms` on submit
+over relying on hard kills.
+
+## Smoke test
+
+```bash
+# Supervisor alive?
+gbrain jobs supervisor status --json | jq .running
+
+# Aggregate queue health.
+gbrain jobs stats
+
+# Jobs currently stalled (still `active` with expired lock_until, pre-requeue).
+gbrain jobs list --status active --limit 10
+
+# Dead-lettered jobs.
+gbrain jobs list --status dead --limit 10
+
+# Shell handler registered? (check supervisor audit log or worker stderr.)
+gbrain jobs supervisor status --json | jq '.worker_config.allow_shell_jobs'
+```
+
+## Uninstall
+
+**`gbrain jobs supervisor`** (foreground or `--detach`):
+
+```bash
+gbrain jobs supervisor stop
+```
+
+**systemd:**
+
+```bash
+sudo systemctl disable --now gbrain-worker
+sudo rm /etc/systemd/system/gbrain-worker.service /etc/gbrain.env
+sudo systemctl daemon-reload
+```
+
+**Fly / Render / Railway:** delete the `worker` process from `fly.toml`
+/ `Procfile` and redeploy. Secrets set via `fly secrets` persist until
+`fly secrets unset`.
+
+**Inline `--follow`:** remove the cron entry. Nothing else to clean up
+— temporary workers exit with their jobs.

docs/guides/minions-fix.md

@@ -0,0 +1,159 @@
+# Minions fix — repairing a half-migrated install
+
+**tl;dr:** on v0.11.1+ everything should self-heal. If Minions is partially
+set up (no `~/.gbrain/preferences.json`, autopilot still inline, cron jobs
+still on `agentTurn`), run:
+
+```bash
+gbrain apply-migrations --yes
+```
+
+It's idempotent. On v0.11.1 installs that already migrated it's a cheap
+no-op.
+
+## Context
+
+v0.11.0 shipped the Minions schema, queue, worker, and migration skill —
+but the migration skill itself never fired on upgrade. `runPostUpgrade`
+printed the feature pitch and stopped. v0.11.0 was never released
+publicly; v0.11.1 is the first public Minions ship and fixes the
+mega-bug (migration fires automatically on `gbrain upgrade` and via
+the `postinstall` hook).
+
+If you're on a pre-v0.11.1 branch build (e.g. running the
+`minions-jobs` branch before v0.11.1 tagged), Minions may be installed
+but not wired: schema is v7, but no `~/.gbrain/preferences.json`,
+autopilot still runs inline, cron jobs still call `agentTurn`.
+
+This guide covers both paths: the canonical v0.11.1+ fix, and the
+stopgap for pre-v0.11.1 binaries that don't have `apply-migrations`.
+
+## Detecting the half-migrated state
+
+```bash
+gbrain doctor
+```
+
+If the install is half-migrated, you'll see:
+
+```
+[FAIL] minions_migration: MINIONS HALF-INSTALLED (partial migration: 0.11.0). Run: gbrain apply-migrations --yes
+```
+
+or
+
+```
+[FAIL] minions_config: MINIONS HALF-INSTALLED (schema v7+ but no ~/.gbrain/preferences.json). Run: gbrain apply-migrations --yes
+```
+
+For a machine-readable report (cron-friendly):
+
+```bash
+gbrain skillpack-check --quiet && echo healthy || echo needs_action
+gbrain skillpack-check | jq -r '.actions[]'    # prints the exact commands to run
+```
+
+## The fix (v0.11.1 or later)
+
+```bash
+gbrain apply-migrations --yes
+```
+
+Reads `~/.gbrain/migrations/completed.jsonl`, diffs against the TS
+migration registry, runs whatever's pending. Seven phases:
+
+```
+A. Schema        gbrain init --migrate-only
+B. Smoke         gbrain jobs smoke
+C. Mode          prompt (or --yes default pain_triggered)
+D. Prefs         write ~/.gbrain/preferences.json
+E. Host          AGENTS.md marker injection + cron rewrites for gbrain
+                 builtins; JSONL TODOs for host-specific handlers
+F. Install       gbrain autopilot --install (env-aware)
+G. Record        append completed.jsonl status:"complete"
+```
+
+If Phase E emits TODOs for host-specific handlers (e.g. your OpenClaw's
+~29 non-gbrain crons), the migration finishes with `status: "partial"`.
+Your host agent walks the TODOs using `skills/migrations/v0.11.0.md` +
+`docs/guides/plugin-handlers.md`, ships handler registrations in the
+host repo, then re-runs `gbrain apply-migrations --yes`. Newly
+registerable cron entries get rewritten and the JSONL rows mark
+`status: "complete"`.
+
+## The stopgap (pre-v0.11.1 binary, no apply-migrations yet)
+
+If you're stuck on a branch build that doesn't have `apply-migrations`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/garrytan/gbrain/v0.11.1/scripts/fix-v0.11.0.sh | bash
+```
+
+This bash script does what apply-migrations does from a shell environment:
+
+1. `gbrain init --migrate-only` — schema v7.
+2. `gbrain jobs smoke` — verify Minions health.
+3. Prompt for `minion_mode` (defaults `pain_triggered` on non-TTY).
+4. Write `~/.gbrain/preferences.json` atomically.
+5. Append `~/.gbrain/migrations/completed.jsonl` with `status: "partial"`
+   and `apply_migrations_pending: true`. That partial record is the
+   signal to v0.11.1's `apply-migrations` to pick up remaining phases
+   after the user upgrades.
+6. Detect host agent repos and PRINT rewrite instructions (never
+   auto-edits from a curl-piped script).
+7. Print the next step: `Run: gbrain autopilot --install`.
+
+Once v0.11.1 is installed, re-run `gbrain apply-migrations --yes` to
+finish the remaining phases (host rewrites + autopilot install). The
+stopgap's `status: "partial"` record is designed to resume cleanly
+(it doesn't poison the permanent migration path).
+
+## Verify the fix landed
+
+```bash
+# 1. Preferences exist and are readable
+cat ~/.gbrain/preferences.json
+
+# 2. Migration recorded
+cat ~/.gbrain/migrations/completed.jsonl
+
+# 3. Autopilot is supervising a Minions worker child
+gbrain autopilot --status
+ps aux | grep 'jobs work'
+
+# 4. Jobs show up in the queue
+gbrain jobs list
+
+# 5. Any host-specific TODOs still pending
+cat ~/.gbrain/migrations/pending-host-work.jsonl 2>/dev/null || echo "(none — all host work is done)"
+
+# 6. Doctor + skillpack-check should both be clean
+gbrain doctor
+gbrain skillpack-check --quiet && echo ok
+```
+
+## If the fix fails
+
+Each phase is idempotent. Re-running is safe. Common failure modes:
+
+- **Phase B smoke fails:** the schema didn't apply. Check
+  `~/.gbrain/config.json` has a valid `database_url` (or `database_path`
+  for PGLite). Run `gbrain init --migrate-only` directly and look at
+  the error.
+- **Phase F install fails:** your host environment doesn't match any
+  detected target. Pass `--target <macos|linux-systemd|ephemeral-container|linux-cron>`
+  explicitly.
+- **Pending host work never clears:** your host agent hasn't shipped
+  handler registrations yet. Read
+  `~/.gbrain/migrations/pending-host-work.jsonl`, open
+  `skills/migrations/v0.11.0.md`, and follow the host-agent instruction
+  manual.
+
+## Related
+
+- `skills/migrations/v0.11.0.md` — full migration skill for host agents.
+- `skills/skillpack-check/SKILL.md` — when and how to run the health check.
+- `docs/guides/plugin-handlers.md` — plugin contract for host-specific
+  handlers.
+- `skills/conventions/cron-via-minions.md` — the canonical cron rewrite
+  pattern.

docs/guides/minions-shell-jobs.md

@@ -0,0 +1,167 @@
+# Minions shell jobs — move deterministic crons off the gateway
+
+## 30 seconds
+
+```bash
+# Run your first shell job:
+GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs submit shell \
+  --params '{"cmd":"echo hello","cwd":"/tmp"}' --follow
+# → exit_code: 0, stdout_tail: "hello\n", duration_ms: 43
+```
+
+That's it. Your cron scripts now have a home with retry, backoff, DLQ, and
+`gbrain jobs list` visibility, without each one booting a full LLM session.
+
+**PGLite users:** `gbrain jobs work` does not run on PGLite (exclusive file
+lock). Every crontab invocation must use `--follow` for inline execution.
+Postgres users can run a persistent worker; see recipes below.
+
+---
+
+## Why it exists
+
+If your agent runs deterministic scripts from cron (token refresh, API fetch,
+scrape + write), each one pays the cost of a full LLM session on the gateway.
+Fourteen simultaneous fires on a Series A deployment pin CPU at 100% and block
+live messages. None of those scripts need reasoning. They need a shell.
+
+Shell jobs move them to the Minions worker: one deterministic-script execution
+per cron, zero LLM tokens, unified visibility and retry.
+
+---
+
+## Security model (read this)
+
+Shell exec is a large blast radius. We ship two independent gates, both must
+pass:
+
+1. **MCP boundary.** `submit_job` with `name: 'shell'` is rejected when
+   `ctx.remote === true` (MCP callers). Independent of the env flag. Remote
+   agents can never submit shell jobs. `MinionQueue.add('shell', ...)` has its
+   own guard too, so an in-process handler can't programmatically bypass this.
+2. **Env flag.** The worker only registers the shell handler when
+   `GBRAIN_ALLOW_SHELL_JOBS=1` is set on the worker process. Default: off. Your
+   agent opts in per-host.
+
+**What the env allowlist does AND does not do.** Shell jobs run with a minimal
+env: `PATH, HOME, USER, LANG, TZ, NODE_ENV`. Your secrets like `OPENAI_API_KEY`
+and `DATABASE_URL` are NOT passed to the child. You opt-in additional keys per
+job via `env: { ... }`. This stops accidental `$OPENAI_API_KEY` interpolation in
+a user-authored script. It does **not** sandbox filesystem reads: a shell
+script can `cat ~/.env` or any file the worker process can read. The operator
+picks a safe `cwd`. That is the trust boundary.
+
+**Audit trail, not forensic insurance.** Every submission writes a JSONL line
+to `~/.gbrain/audit/shell-jobs-YYYY-Www.jsonl` (ISO-week rotation; override
+with `GBRAIN_AUDIT_DIR`). Failures log to stderr and don't block submission, so
+a disk-full adversary could silently disable the trail. Good for "what did
+this cron submit last Tuesday", not for security-critical forensics.
+
+**The command text is logged as-is.** If you embed a secret in `cmd`
+(`curl -H 'Authorization: Bearer ...'`), it shows up in the audit file. Put
+secrets in `env:` instead.
+
+---
+
+## Migrate a cron
+
+### Postgres worker (recommended)
+
+On one terminal, start a persistent worker:
+
+```bash
+GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work
+```
+
+Rewrite crontab to submit shell jobs (no `--follow`):
+
+```cron
+# Before (LLM gateway):
+#   OpenClaw cron: x-garrytan-unified
+# After (Minions worker):
+3 13,16,19,22,1,4,7,10 * * * \
+  gbrain jobs submit shell \
+    --params '{"cmd":"node scripts/x-garrytan-daily.mjs","cwd":"/data/.openclaw/workspace"}' \
+    --max-attempts 3 --timeout-ms 300000
+```
+
+Worker claims the job on next poll, runs it, records `exit_code` +
+`stdout_tail` + `stderr_tail` in the result. Failures retry per
+`--max-attempts` with exponential backoff.
+
+### PGLite (inline execution)
+
+PGLite doesn't support the persistent worker daemon. Every crontab invocation
+uses `--follow` to run inline:
+
+```cron
+# Each cron tick spawns a short-lived worker that runs the job inline.
+3 13,16,19,22,1,4,7,10 * * * \
+  GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs submit shell \
+    --params '{"cmd":"node scripts/x-garrytan-daily.mjs","cwd":"/data/.openclaw/workspace"}' \
+    --follow --timeout-ms 300000
+```
+
+Note: `--follow` blocks the crontab slot until the job finishes. If 14 shell
+crons land at the same minute and each takes 30s, they serialize through
+crontab's spawning limits. Postgres + persistent worker scales better.
+
+### Submitting with `argv` (no shell interpolation)
+
+For programmatic callers assembling commands from JSON, use `argv` instead of
+`cmd`. No shell, no injection surface:
+
+```bash
+gbrain jobs submit shell \
+  --params '{"argv":["node","scripts/fetch.mjs","--date","2026-04-19"],"cwd":"/data"}' \
+  --follow
+```
+
+---
+
+## Debug a failed job
+
+```bash
+# List dead shell jobs
+gbrain jobs list --status dead
+
+# Inspect one
+gbrain jobs get 42
+# → error_text, stacktrace, result.stdout_tail, result.stderr_tail
+
+# Submission audit log (operator trail, not forensic)
+cat ~/.gbrain/audit/shell-jobs-*.jsonl | jq '.'
+
+# First-time failure mode: submitted without env flag on the worker
+gbrain jobs list --status waiting --name shell
+# If rows pile up here, no worker with GBRAIN_ALLOW_SHELL_JOBS=1 is running.
+```
+
+---
+
+## Limitations
+
+- **Filesystem reads are not sandboxed.** See "Security model" above. Don't
+  point `cwd` at a directory full of secrets.
+- **Audit log is advisory.** Disk-full or EACCES silently disables it.
+- **Cancel latency is lock-renewal-bounded** (~7-15 s by default). A cancelled
+  child keeps running until the next lock-renewal tick fails.
+- **`--follow` claim order** is by priority/created_at. If another job is
+  waiting in the same queue at the time of `--follow`, that one runs first.
+- **`cwd` symlink TOCTOU.** The absolute-path check doesn't guard against
+  symlinks pointing elsewhere at execution time. Operator-scope concern.
+
+---
+
+## Errors {#errors}
+
+| Error | What it means | Fix |
+|---|---|---|
+| `shell: specify exactly one of cmd or argv` | `cmd` and `argv` are mutually exclusive. Both absent is also invalid. | Choose one. `cmd` for shell-interpolated strings; `argv` for structured args. |
+| `shell: cwd is required and must be an absolute path` | `cwd` must be a string starting with `/`. | Set `cwd` in `--params` to an absolute path. |
+| `shell: argv must be an array of strings` | `argv` has a non-string entry or isn't an array. | Pass `argv: ["bin","arg1","arg2"]`. |
+| `shell: env values must all be strings` | `env` has a number/bool/object value. | Stringify: `"env":{"COUNT":"3"}` not `"env":{"COUNT":3}`. |
+| `permission_denied: shell jobs cannot be submitted over MCP` | An MCP client tried to submit a shell job. By design CLI-only. | Submit from CLI or via a trusted operation handler (`ctx.remote === false`). |
+| `protected job name 'shell' requires CLI or operation-local submitter` | A caller invoked `MinionQueue.add('shell', ...)` without the `trusted` opt-in. | Pass `{ allowProtectedSubmit: true }` as the 4th arg. CLI and `submit_job` do this automatically. |
+| `aborted: timeout` / `aborted: cancel` / `aborted: shutdown` / `aborted: lock-lost` | The worker's abort signal fired mid-execution. Child got SIGTERM, 5s grace, then SIGKILL. | Expected: timeout / user cancel / deploy restart / stall. Inspect `gbrain jobs get` to see which. |
+| `exit N: <stderr_tail_500>` | Script exited non-zero. | Read `stderr_tail` in `gbrain jobs get`. |

docs/guides/multi-source-brains.md

@@ -0,0 +1,182 @@
+# Multi-source brains
+
+**A single gbrain database can hold multiple knowledge repos.** Each one
+is a `source`: a logical brain-within-the-brain with its own slug
+namespace, its own sync state, and its own federation policy. The rest
+of this guide walks the three canonical scenarios.
+
+## The three scenarios
+
+### 1. Unified knowledge recall (wiki + gstack)
+
+You have a personal wiki and a `gstack` checkout. Both belong to you,
+both are knowledge you want your agent to recall across. When you ask
+"what did I learn about X?" you want the best hit whether it lives in
+the wiki or in a gstack plan.
+
+```bash
+# Register the gstack source, federate so it joins cross-source search
+gbrain sources add gstack --path ~/.gstack --federated
+
+# Pin the directory so `gbrain sync` knows which source it's walking
+cd ~/.gstack && gbrain sources attach gstack
+
+# Initial sync
+gbrain sync --source gstack
+
+# Now `gbrain search "retry budgets"` returns hits from BOTH wiki and
+# gstack. Each result includes source_id so the agent can cite properly.
+```
+
+Result: wiki pages and gstack plans are separate (different source_ids,
+different slug namespaces) but share the search surface.
+
+### 2. Purpose-separated brains (yc-media + garrys-list)
+
+You run two completely different content pipelines on the same backend.
+YC Media covers portfolio news and founder profiles. Garry's List is
+personal writing. You explicitly DON'T want them mixed in search — YC
+portfolio content leaking into essay searches is a bug, not a feature.
+
+```bash
+# Two sources, both isolated (federated=false)
+gbrain sources add yc-media --path ~/yc-media --no-federated
+gbrain sources add garrys-list --path ~/writing --no-federated
+
+# Pin each checkout directory
+(cd ~/yc-media && gbrain sources attach yc-media)
+(cd ~/writing && gbrain sources attach garrys-list)
+
+# Sync each independently
+gbrain sync --source yc-media
+gbrain sync --source garrys-list
+```
+
+Result: searching from neither directory returns the `default` source
+(your main brain). Searching from inside `~/yc-media` returns only yc-
+media hits. Searching from inside `~/writing` returns only garrys-list.
+Federation is opt-in, not leaked.
+
+To search across them explicitly on demand:
+
+```bash
+gbrain search "tech layoffs" --source yc-media,garrys-list
+```
+
+### 3. Mixed (wiki federated + sessions isolated)
+
+Your main wiki is federated with a few trusted sources. Your session
+transcripts (coming in v0.18) land in a separate isolated source so
+they don't dominate every search result.
+
+```bash
+# Federated sources
+gbrain sources add gstack --path ~/.gstack --federated
+
+# Isolated source (future v0.18 — sessions use this shape today for ingest)
+gbrain sources add sessions --path ~/.claude/sessions --no-federated
+```
+
+## Resolution priority
+
+When any command needs to pick a source, gbrain walks this list (highest
+first):
+
+1. Explicit `--source <id>` flag.
+2. `GBRAIN_SOURCE` environment variable.
+3. `.gbrain-source` dotfile in CWD or any ancestor directory.
+4. A registered source whose `local_path` contains the CWD (longest
+   prefix wins for nested checkouts).
+5. The brain-level default set via `gbrain sources default <id>`.
+6. The seeded `default` source.
+
+So inside `~/.gstack/plans/` on a brain that pinned `gstack` to
+`~/.gstack` via `.gbrain-source`, `gbrain put-page` implicitly writes to
+the `gstack` source. Outside any registered directory with no env/dotfile
+set, it writes to the default.
+
+## Federation flag
+
+Every source row stores `config.federated: boolean` in its JSONB config.
+
+| Value | Meaning |
+|-------|---------|
+| `true` | Source participates in unqualified `gbrain search "X"` results. |
+| `false` (default for new sources) | Source only searched when explicitly named via `--source <id>` or qualified citation. |
+
+The seeded `default` source is `federated=true` so pre-v0.17 brains
+behave exactly as before — every page appears in search.
+
+Flip later with `gbrain sources federate <id>` / `unfederate <id>`.
+
+## Commands
+
+Full subcommand reference:
+
+```
+gbrain sources add <id> --path <p> [--name <n>] [--federated|--no-federated]
+                               Register a source. id: [a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?
+gbrain sources list [--json]   List all sources with page counts + federation state.
+gbrain sources remove <id> [--yes] [--dry-run] [--keep-storage]
+                               Cascade-delete a source (pages, chunks, timeline).
+gbrain sources rename <id> <new-name>
+                               Change display name only; id is immutable.
+gbrain sources default <id>    Set the brain-level default.
+gbrain sources attach <id>     Write .gbrain-source in CWD (like kubectl context).
+gbrain sources detach          Remove .gbrain-source from CWD.
+gbrain sources federate <id>
+gbrain sources unfederate <id>
+```
+
+## Citation format for agents
+
+When agents receive multi-source results they MUST cite pages in
+`[source-id:slug]` form. Example:
+
+> You told me about the distillation protocol — see [wiki:topics/ai]
+> and [gstack:plans/multi-repo] for where this came from.
+
+The citation key is `sources.id` (immutable). Renaming a source via
+`gbrain sources rename` changes the display name only; existing
+citations keep working.
+
+## Writing to a specific source
+
+```bash
+# Pass --source explicitly
+gbrain put-page topics/ai ... --source wiki
+
+# Or rely on the dotfile / env / CWD match
+cd ~/.gstack && gbrain put-page plans/multi-repo ...
+# → source auto-resolves to gstack
+```
+
+Reads span federated sources by default. Writes require a resolved
+source (explicit, inferred, or default). The resolver never picks a
+source silently when ambiguous — it errors with a clear fix.
+
+## Upgrading an existing brain
+
+`gbrain upgrade` runs the v16 + v17 migrations automatically. Your
+existing pages all move under `source_id='default'`. Behavior is
+unchanged until you add a second source.
+
+To add one:
+
+```bash
+gbrain sources add gstack --path ~/.gstack --federated
+cd ~/.gstack && gbrain sources attach gstack && gbrain sync
+```
+
+Two commands. The existing default source is untouched.
+
+## Not in v0.18.0
+
+- Session transcript ingest (`.jsonl`, raised size cap, session
+  PageType) — v0.18.
+- Per-source retention/TTL (`gbrain sources prune`) — v0.18.
+- ACL enforcement via caller-identity — v0.17.1.
+- `gbrain sources import-from-github <url>` one-shot bootstrap — patch
+  release after the core plumbing stabilizes.
+
+All of these build on the `sources` primitive shipped here.

docs/guides/plugin-authors.md

@@ -0,0 +1,163 @@
+# Plugin authors guide (v0.15)
+
+`gbrain` discovers subagent definitions from outside this repo via
+`GBRAIN_PLUGIN_PATH`. If you maintain a downstream agent (your OpenClaw
+deployment, a workflow host, a private tool) and want to ship custom
+subagents alongside it, drop a plugin directory on that env path.
+
+This guide is for plugin authors. The CLI user doesn't need to read it.
+
+## Minimum viable plugin
+
+```
+/path/to/my-plugin/
+├── gbrain.plugin.json
+└── subagents/
+    └── my-summarizer.md
+```
+
+`gbrain.plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "plugin_version": "gbrain-plugin-v1"
+}
+```
+
+`subagents/my-summarizer.md`:
+
+```markdown
+---
+name: my-summarizer
+model: claude-sonnet-4-6
+allowed_tools:
+  - brain_search
+  - brain_get_page
+---
+
+You are a brain page summarizer. Given a slug, fetch the page and produce
+a 3-sentence summary.
+```
+
+## Turning it on
+
+```bash
+export GBRAIN_PLUGIN_PATH="/path/to/my-plugin"
+gbrain jobs work           # worker startup prints the plugin load line
+gbrain agent run "summarize meetings/2026-04-20" --subagent-def my-summarizer
+```
+
+Multiple plugins: colon-separated, just like `$PATH`.
+
+```bash
+export GBRAIN_PLUGIN_PATH="/path/to/plugin-a:/path/to/plugin-b"
+```
+
+## Rules (strict by design)
+
+**Path policy.** Absolute paths only. Relative paths, `~`-prefixed paths,
+and URL-style paths (`https://`, `file://`) are rejected with a warning.
+You control where your plugin lives on disk; `gbrain` doesn't guess.
+
+**Collision policy.** If two plugins ship a subagent with the same `name`,
+the one listed FIRST in `GBRAIN_PLUGIN_PATH` wins. The other is dropped
+with a warning naming both sources.
+
+**Trust policy.** Plugins ship subagent definitions ONLY in v0.15:
+
+- You **cannot** declare new tools.
+- You **cannot** extend the brain tool allow-list.
+- You **cannot** override any `agentSafe` or similar flag.
+- Your `allowed_tools:` frontmatter field MUST subset the derived brain
+  tool registry. Names not in the registry are rejected at plugin load
+  time (worker startup), NOT at subagent dispatch time — so a typo in
+  your plugin gives you a loud startup error, not a silent "tool never
+  fires" at 3am.
+
+v0.16+ may open up plugin-declared tools with a separate contract. Don't
+expect it.
+
+## `gbrain.plugin.json`
+
+| field            | type   | required | notes                                                              |
+|------------------|--------|----------|--------------------------------------------------------------------|
+| `name`           | string | yes      | Human-readable plugin id. Shows up in warnings and collision logs. |
+| `version`        | string | yes      | Your plugin's semver. Informational.                               |
+| `plugin_version` | string | yes      | Contract lock. Must equal `"gbrain-plugin-v1"` for v0.15.          |
+| `subagents`      | string | no       | Subdir name (default `subagents`). Escape-attempts are rejected.   |
+| `description`    | string | no       | Shown in future `gbrain plugin list`.                              |
+
+## Subagent definition files
+
+Plain markdown with YAML frontmatter. The body is the system prompt. The
+frontmatter controls runtime behavior.
+
+Recognized frontmatter fields:
+
+| field           | type     | required | notes                                                                                   |
+|-----------------|----------|----------|-----------------------------------------------------------------------------------------|
+| `name`          | string   | no       | Subagent identifier used as `--subagent-def`. Defaults to the file basename.            |
+| `model`         | string   | no       | Anthropic model id. Defaults to the handler default (sonnet).                           |
+| `max_turns`     | number   | no       | Cap on assistant turns. Defaults to 20.                                                 |
+| `allowed_tools` | string[] | no       | Whitelist of tool names. Must subset the derived brain registry. Rejected on mismatch.  |
+
+Unknown frontmatter fields are preserved but ignored by the handler. v0.16
+may consume more of them.
+
+## Caveats that will bite you
+
+1. **Plugin definitions can't change during a run.** The loader reads the
+   disk once at worker startup. Editing a subagent def doesn't re-take
+   effect until you restart the worker. This is deliberate — live
+   reloads would break crash-resumable replay.
+
+2. **`~/.gbrain/audit/subagent-jobs-*.jsonl` is local only.** If your
+   worker runs on a different host than the `gbrain agent logs` caller,
+   the CLI won't see heartbeats from that worker. v0.16 will unify this;
+   for now assume worker + CLI share a filesystem.
+
+3. **Tool calls always run with `ctx.remote = true`.** Even on local CLI
+   invocation. Tools that gate on `remote=true` (file_upload's strict
+   confinement, put_page's namespace check) will apply. Good default; a
+   subagent definition that wants local-filesystem reach beyond the brain
+   can't have it.
+
+4. **`put_page` writes are namespace-scoped.** A subagent with id 42 can
+   only write under `wiki/agents/42/...`. This is enforced both in the
+   tool schema (the slug pattern shown to the model) AND server-side in
+   the `put_page` operation (fail-closed if `viaSubagent=true`). Don't
+   try to route around it; you'll get `permission_denied`.
+
+## Example: a downstream-OpenClaw plugin
+
+```
+~/your-openclaw/
+└── gbrain-plugin/
+    ├── gbrain.plugin.json
+    └── subagents/
+        ├── meeting-ingestion.md
+        ├── signal-detector.md
+        └── daily-task-prep.md
+```
+
+`~/your-openclaw/gbrain-plugin/gbrain.plugin.json`:
+
+```json
+{
+  "name": "your-openclaw",
+  "version": "2026.4.20",
+  "plugin_version": "gbrain-plugin-v1",
+  "description": "Your OpenClaw's personal-brain subagents"
+}
+```
+
+Environment:
+
+```bash
+export GBRAIN_PLUGIN_PATH="$HOME/your-openclaw/gbrain-plugin"
+```
+
+Then your OpenClaw calls `gbrain agent run --subagent-def meeting-ingestion
+--fanout-by transcript ...` and its definitions load automatically.

docs/guides/plugin-handlers.md

@@ -0,0 +1,137 @@
+# Plugin handlers — registering host-specific Minion handlers
+
+GBrain's Minion worker ships with seven built-in handlers: `sync`,
+`embed`, `lint`, `import`, `extract`, `backlinks`, `autopilot-cycle`.
+These cover every background operation the gbrain CLI itself performs.
+
+Host platforms (OpenClaw deployments, future hosts) register their own
+handlers via a plugin bootstrap that imports
+`gbrain/minions`. No `handlers.json`-style data file — handlers are
+code, loaded by the worker, with the same trust model as any other
+code in the host's repo.
+
+## Why code, not data
+
+An earlier design draft shipped `~/.claude/gbrain-handlers.json` where
+each entry was a shell command the worker would exec on job claim.
+Codex flagged this as a durable RCE surface: an agent-writable data
+file that spawns arbitrary shell. We dropped the data-file approach;
+handlers are code that the host imports explicitly and ships through
+code review.
+
+## The plugin contract
+
+A host worker bootstrap looks like this (TypeScript):
+
+```ts
+import { MinionQueue, MinionWorker } from 'gbrain/minions';
+import type { BrainEngine } from 'gbrain/engine';
+
+async function main() {
+  const engine: BrainEngine = /* your engine setup */;
+  await engine.connect({});
+
+  const worker = new MinionWorker(engine, { queue: 'default' });
+
+  // Register every host-specific handler the host's cron manifest references.
+  // Each handler returns a plain object (serialized as the job result).
+  // Throw on failure — the worker catches and retries per max_attempts.
+
+  worker.register('ea-inbox-sweep', async (ctx) => {
+    const slot = ctx.data.slot ?? new Date().toISOString();
+    // Host-specific agent turn: call your LLM, scan the inbox, write
+    // brain pages, return a summary. ctx.signal.aborted indicates the
+    // worker wants you to cooperate with shutdown — honor it.
+    return { swept: true, slot };
+  });
+
+  worker.register('morning-briefing', async (ctx) => {
+    /* host logic */
+    return { briefed: true };
+  });
+
+  // Call start() AFTER every handler is registered. The worker's
+  // stall-detector ignores jobs whose name is not in the registered set.
+  await worker.start();
+}
+
+main().catch(err => { console.error(err); process.exit(1); });
+```
+
+Ship this as a separate binary in the host repo (e.g. `your-openclaw-worker`)
+or as a side-effect module that the stock `gbrain jobs work` command
+auto-loads on startup (configurable via a host-provided entry point).
+
+## Handler contract
+
+Every handler receives a `MinionJobContext`:
+
+```ts
+interface MinionJobContext {
+  data: Record<string, unknown>;   // job params (whatever the cron submit passed)
+  job: MinionJob;                   // full job row (id, queue, attempts, etc.)
+  signal: AbortSignal;              // set to aborted when the worker is shutting down
+  inbox: MinionInbox;               // read messages sent to this job while it runs
+}
+```
+
+Return a serializable object on success. Throw on failure (the worker
+will log + retry per `max_attempts`).
+
+**Abort cooperation.** When `ctx.signal.aborted` becomes true, finish
+gracefully. The worker will wait 30s for you to return before SIGKILL.
+Long-running LLM calls should pass the signal through to whatever
+network library they use.
+
+**Idempotency.** The queue enforces unique `idempotency_key` at the DB
+layer, so you don't need to worry about double-submits from a cron that
+fires while the previous invocation is still running.
+
+## Gbrain's migration flow
+
+The v0.11.0 migration orchestrator (run by `gbrain apply-migrations`)
+detects cron entries whose handler name is NOT in GBrain's builtin set
+and emits a structured TODO to `~/.gbrain/migrations/pending-host-work.jsonl`.
+Each TODO has shape:
+
+```json
+{
+  "type": "cron-handler-needs-host-registration",
+  "handler": "ea-inbox-sweep",
+  "cron_schedule": "0 */30 * * *",
+  "manifest_path": "/path/to/cron/jobs.json",
+  "current_cmd": "agentTurn ea-inbox-sweep",
+  "recommendation": "Add a handler registration for `ea-inbox-sweep` in your host worker bootstrap per docs/guides/plugin-handlers.md. Once registered, re-run `gbrain apply-migrations` to auto-rewrite this entry.",
+  "status": "pending"
+}
+```
+
+The host agent walks these entries using `skills/migrations/v0.11.0.md`:
+
+1. Read `~/.gbrain/migrations/pending-host-work.jsonl`.
+2. For each `cron-handler-needs-host-registration` row, ship a handler
+   registration in the host's worker bootstrap following the pattern
+   above.
+3. Deploy the updated worker.
+4. Re-run `gbrain apply-migrations --yes`. The orchestrator now
+   recognizes the newly-registerable handler (worker writes the
+   registered names to a discovery file on startup) and rewrites the
+   cron entry to use `gbrain jobs submit`. The JSONL row is marked
+   `status: "complete"`.
+
+## Trust boundary
+
+Handler code runs inside the worker process with the same privileges
+as the rest of the host binary. There is no elevation. But there is
+also no runtime sandbox — handlers can read + write anywhere the
+worker user can. Review handler PRs the same way you review any other
+code that touches production data.
+
+## Related
+
+- `skills/conventions/cron-via-minions.md` — the rewrite convention
+  for cron manifests.
+- `skills/migrations/v0.11.0.md` — how the migration orchestrator
+  drives the host agent through this work.
+- `skills/minion-orchestrator/SKILL.md` — patterns for submitting,
+  monitoring, steering, and replaying jobs once the handler is live.

docs/guides/queue-operations-runbook.md

@@ -0,0 +1,76 @@
+# Queue operations runbook
+
+"My queue looks wedged — what do I run?" The commands below are in the order
+you probably want them. Shipped with v0.19.1 after a production incident
+where the queue held for 90+ minutes before the operator noticed.
+
+## First signal: jobs aren't running
+
+```bash
+gbrain doctor --json | jq '.checks[] | select(.name == "queue_health")'
+```
+
+`queue_health` flags two patterns:
+
+- **stalled-forever**: active job whose `started_at` is older than 1h.
+- **waiting-depth**: any per-name queue deeper than 10 (override via
+  `GBRAIN_QUEUE_WAITING_THRESHOLD`). Signals a missing `maxWaiting`.
+
+## Triage commands
+
+```bash
+# Who's active right now?
+gbrain jobs list --status active
+
+# Who's waiting, biggest pile first?
+gbrain jobs list --status waiting --limit 50
+
+# What's wrong with a specific job?
+gbrain jobs get <id>
+```
+
+## Rescue actions (in order of escalation)
+
+```bash
+# Force-kill a single stuck job:
+gbrain jobs cancel <id>
+
+# Clear a specific job entirely (last resort):
+gbrain jobs delete <id>
+
+# Health smoke on the mechanism itself:
+gbrain jobs smoke --wedge-rescue
+```
+
+## What each subcheck means
+
+- **stalled-forever** — A worker claimed a job, started executing, and has
+  held the row for over an hour. The wall-clock sweep evicts jobs past
+  2× `timeout_ms`; if one's still active, either no `timeout_ms` was set
+  or the sweep is newly deployed and this job predates it. Cancel it.
+- **waiting-depth** — Submitters are piling up jobs faster than workers
+  drain them. Set `--max-waiting N` on the submission or on the programmatic
+  `queue.add()` call. If you want a taller pile, raise the threshold via
+  `GBRAIN_QUEUE_WAITING_THRESHOLD=50 gbrain doctor`.
+
+## Self-check: is a worker even running?
+
+```bash
+# If you're running autopilot with --no-worker, check that your external
+# worker (systemd / Docker / OpenClaw service-manager) is alive:
+gbrain jobs list --status active | head -5
+```
+
+If the list is empty AND your submissions keep piling up, no worker is
+claiming. Start one:
+
+```bash
+GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work --concurrency 4
+```
+
+## Follow-ups tracked for v0.20+
+
+- B7 — `minion_workers` heartbeat table for ground-truth liveness (the
+  `--no-worker` probe and the dropped `queue_health` worker-heartbeat
+  subcheck both need this).
+- B3 — `gbrain doctor --fix` learns to rescue queue wedges.

docs/guides/rls-and-you.md

@@ -0,0 +1,233 @@
+# RLS and you
+
+Short version: every table in your gbrain's `public` schema needs Row Level
+Security enabled. If one doesn't, `gbrain doctor` now fails, not warns, and the
+process exits 1.
+
+This guide explains why, what to do when you hit the check, and the escape hatch
+for the cases where you really do want a table to stay readable by the anon key.
+
+## Why RLS matters
+
+Supabase exposes everything in the `public` schema via PostgREST. Whatever's
+there is reachable by the anon key, which is a client-side secret by design.
+If RLS is off on a public table, the anon key can read it. On anything sensitive
+(auth tokens, chat history, financial data) that's an exfiltration vector, not
+a footgun.
+
+gbrain's service-role connection holds `BYPASSRLS`, so enabling RLS without
+policies does NOT break gbrain itself. It just blocks the anon key's default
+read. That's the security posture: deny-by-default to anon, full access for
+the service role.
+
+## What to do when doctor fails
+
+Doctor's message names every table missing RLS and gives you a `ALTER TABLE`
+line per table:
+
+```
+1 table(s) WITHOUT Row Level Security: expenses_ramp.
+Fix: ALTER TABLE "public"."expenses_ramp" ENABLE ROW LEVEL SECURITY;
+If a table should stay readable by the anon key on purpose, see
+docs/guides/rls-and-you.md for the GBRAIN:RLS_EXEMPT comment escape hatch.
+```
+
+99% of the time, you want the fix. Run the SQL. Re-run `gbrain doctor`. Done.
+
+## v0.26.7 — auto-RLS event trigger and one-time backfill
+
+Starting in v0.26.7 (migration v35), gbrain ships two changes that close the
+gap where a table could exist in your `public` schema without RLS for any
+amount of time at all.
+
+**1. The event trigger.** A Postgres DDL event trigger named
+`auto_rls_on_create_table` runs `ALTER TABLE … ENABLE ROW LEVEL SECURITY`
+on every newly created `public.*` table. It covers `CREATE TABLE`,
+`CREATE TABLE AS … SELECT`, and `SELECT … INTO` — every syntax Postgres
+reports as a table-creation command. Tables created by gbrain itself, by
+your other apps sharing the same Supabase project (Baku, Hermes, anything),
+or by a human running raw SQL all get RLS enabled the moment they exist.
+Non-`public` schemas (`auth`, `storage`, `realtime`, etc.) are explicitly
+ignored — Supabase manages those, and we should not touch them.
+
+**2. The one-time backfill.** When you upgrade to v0.26.7, the migration
+walks every existing `public.*` base table whose RLS is off and whose comment
+doesn't carry the `GBRAIN:RLS_EXEMPT` exemption (see below) and enables RLS
+on each. After the upgrade, `gbrain doctor`'s `rls` check should be a no-op
+on every brain.
+
+### Breaking change: read this before upgrading
+
+If you have public tables that are intentionally RLS-off and you want them
+to stay that way, you MUST add the `GBRAIN:RLS_EXEMPT` comment **before**
+running `gbrain upgrade` to v0.26.7. The backfill flips RLS on for any public
+table that doesn't carry the exact comment contract documented below. There
+is no `--dry-run` flag on the migration.
+
+The minimum cost of getting this wrong is one round-trip: the operator runs
+the SQL to enable RLS on a table that should have been exempt, then
+`ALTER TABLE … DISABLE ROW LEVEL SECURITY` and adds the exempt comment to
+prevent a re-flip on a later doctor run. No data is lost.
+
+### Cross-app implications
+
+If a non-gbrain app (Baku, Hermes, a script you wrote, anything) creates
+tables in the same Supabase project, the trigger will enable RLS on those
+tables too. Two ways to handle that:
+
+1. **The app's connection role has BYPASSRLS** (e.g. it's also using the
+   `postgres` role). Newly created tables get RLS on but the app reads/writes
+   freely because BYPASSRLS bypasses policies entirely.
+2. **The app's role does NOT have BYPASSRLS.** Then the app needs to add a
+   `CREATE POLICY` immediately after creating the table, granting itself
+   the read/write access it needs. The trigger does NOT add policies — it
+   only enables RLS, leaving the deny-by-default posture in place until the
+   app's policy lands.
+
+If neither condition holds, the app will fail to read its own freshly-created
+tables. The fix is at the app side, not gbrain's: either grant BYPASSRLS or
+ship a policy.
+
+### What if the trigger gets dropped?
+
+`gbrain doctor` includes a new `rls_event_trigger` check that verifies the
+trigger is installed and enabled. If you drop it manually for any reason
+(debugging, migration testing, anything), doctor warns and gives you the
+recovery command:
+
+```
+gbrain apply-migrations --force-retry 35
+```
+
+Re-running migration v35 is idempotent — it `DROP EVENT TRIGGER IF EXISTS`
+and recreates cleanly.
+
+### Why no FORCE ROW LEVEL SECURITY?
+
+Postgres has two RLS dials. `ENABLE` blocks anon/authenticated; `FORCE` also
+blocks the table OWNER unless they hold BYPASSRLS. We use `ENABLE` only,
+matching the posture in `src/schema.sql`, migrations v24, and v29. `FORCE`
+would lock non-BYPASSRLS apps out of their own freshly-created tables (the
+trigger function inherits the caller's role, not the gbrain role) — which
+defeats the cross-app coexistence story above. If you want defense-in-depth
+`FORCE` on a specific gbrain-owned table, add it explicitly in your own
+migration; gbrain's auto-RLS does not opt you in by default.
+
+## The 1% case: deliberate exemption
+
+Sometimes a public table is supposed to be readable by the anon key. An
+analytics view backing a public dashboard. A read-only reference table. A
+plugin that ships its own frontend and intentionally uses the anon key for
+reads.
+
+gbrain has an escape hatch for these. It is deliberately painful to set up.
+That is the feature.
+
+### The format
+
+```sql
+-- In psql, connected as a BYPASSRLS role (e.g. postgres):
+COMMENT ON TABLE public.your_table IS
+  'GBRAIN:RLS_EXEMPT reason=<why this is anon-readable on purpose>';
+```
+
+Rules:
+
+- The comment value MUST start with `GBRAIN:RLS_EXEMPT` (case-sensitive).
+- It MUST include `reason=` followed by at least 4 characters of justification.
+- No other prefix, no checkbox in a config file, no environment variable. Only
+  a Postgres table comment counts.
+- If RLS is also off on the table (which it must be for the anon key to
+  actually read), you also need `ALTER TABLE ... DISABLE ROW LEVEL SECURITY;`
+  explicitly. Disabling alone is not enough; the comment is what tells doctor
+  this is intentional.
+
+### Example
+
+```sql
+ALTER TABLE public.expenses_ramp DISABLE ROW LEVEL SECURITY;
+COMMENT ON TABLE public.expenses_ramp IS
+  'GBRAIN:RLS_EXEMPT reason=analytics-only, anon-readable ok, owner=garry, 2026-04-22';
+```
+
+After that, `gbrain doctor` reports:
+
+```
+rls: ok — RLS enabled on 20/21 public tables (1 explicitly exempt: expenses_ramp)
+```
+
+Note that every subsequent run re-enumerates your exemptions by name. That's
+intentional. The escape hatch is not a one-time sign-off, it's a recurring
+reminder. If you ever want to know which tables are open, run `gbrain doctor`.
+
+## Why SQL and not a CLI subcommand
+
+gbrain does NOT ship a `gbrain rls-exempt add <table>` command. A CLI command
+would make it easy for an agent to silently open a table to anon reads. The
+comment-in-psql requirement forces the operator to type the justification
+in SQL, which is:
+
+- Visible in shell history.
+- Visible in a git-tracked schema dump.
+- Visible in `pg_dump` output the next time you restore.
+- Visible in `gbrain doctor` output on every run.
+
+An agent CAN still run the SQL, but it can't do it without the user seeing the
+action. That's the "write it in blood" design.
+
+## Auditing exemptions later
+
+To see every exemption in the current DB:
+
+```sql
+SELECT
+  c.relname AS table_name,
+  obj_description(c.oid, 'pg_class') AS comment
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE n.nspname = 'public'
+  AND c.relkind = 'r'
+  AND obj_description(c.oid, 'pg_class') LIKE 'GBRAIN:RLS_EXEMPT%';
+```
+
+If that list is longer than you remember signing off on, that's the signal.
+
+## Removing an exemption
+
+Just drop the comment and re-enable RLS:
+
+```sql
+ALTER TABLE public.expenses_ramp ENABLE ROW LEVEL SECURITY;
+COMMENT ON TABLE public.expenses_ramp IS NULL;
+```
+
+`gbrain doctor` stops listing the table as exempt and goes back to checking
+it like any other.
+
+## PGLite
+
+If you're on PGLite (the zero-config default), doctor skips this check
+entirely: PGLite is embedded, single-user, and has no PostgREST in front of
+it. The public-schema-exposure risk doesn't exist. You'll see:
+
+```
+rls: ok — Skipped (PGLite — no PostgREST exposure, RLS not applicable)
+```
+
+If you migrate to Supabase or self-hosted Postgres later, the check starts
+running and will flag any table that came over without RLS.
+
+## Self-hosted Postgres
+
+If you're running Postgres without PostgREST in front, the anon-key exposure
+doesn't apply. But gbrain still fails the check on missing RLS, because:
+
+- The framing is "RLS on all public tables" is a gbrain security invariant,
+  not a Supabase-specific workaround.
+- The `ALTER TABLE ... ENABLE RLS` fix is harmless on any Postgres: it only
+  constrains non-bypass roles, which gbrain doesn't use.
+- If you ever put PostgREST or a similar tool in front later, the guard is
+  already in place.
+
+If this framing doesn't fit your deployment, file an issue with the specifics
+so we can decide whether a self-hosted-exempt mode is justified.

docs/integrations/README.md

@@ -62,8 +62,13 @@ secrets:                        # API keys and credentials needed
   - name: TWILIO_ACCOUNT_SID
     description: Twilio account SID
     where: https://console.twilio.com    # exact URL to get this key
-health_checks:                  # commands to verify the integration is working
-  - "curl -sf https://api.twilio.com/..."
+health_checks:                  # typed DSL to verify the integration is working
+  - type: http
+    url: "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"
+    auth: basic
+    auth_user: "$TWILIO_ACCOUNT_SID"
+    auth_token: "$TWILIO_AUTH_TOKEN"
+    label: "Twilio account"
 setup_time: 30 min              # estimated time to complete setup
 ---
 
@@ -74,6 +79,16 @@ setup_time: 30 min              # estimated time to complete setup
 the markdown body and executes the setup steps. It asks you for API keys, validates
 each one, configures the integration, and runs a smoke test.
 
+### Recipe trust boundary
+
+Only recipes shipped inside the gbrain package itself (the `recipes/` directory in
+a source install, or the global install copy) are trusted. Recipes discovered at
+runtime from `$GBRAIN_RECIPES_DIR` or a cwd-local `./recipes/` are marked untrusted:
+they cannot run `command` health checks, cannot run `http` health checks (SSRF
+defense), and cannot use the deprecated string health_check form. Untrusted recipes
+can still use `env_exists` and `any_of` compositions. To ship a recipe that runs
+live checks, contribute it upstream so it becomes package-bundled.
+
 ## The Deterministic Collector Pattern
 
 When an LLM keeps failing at a mechanical task despite repeated prompt fixes,

docs/integrations/pre-commit.md

@@ -0,0 +1,105 @@
+# Pre-commit hook for brain repos (v0.22.4+)
+
+`gbrain frontmatter install-hook` installs a git pre-commit hook in your
+brain source's repo that runs `gbrain frontmatter validate` against staged
+`.md` and `.mdx` files. Malformed frontmatter blocks the commit. Bypass with
+`git commit --no-verify`.
+
+## What the hook catches
+
+The same seven validation classes the `frontmatter-guard` skill and
+`gbrain doctor`'s `frontmatter_integrity` subcheck report:
+
+| Code              | What it catches                                                     |
+|-------------------|---------------------------------------------------------------------|
+| `MISSING_OPEN`    | File doesn't start with `---`                                       |
+| `MISSING_CLOSE`   | No closing `---` before first heading                               |
+| `YAML_PARSE`      | YAML failed to parse (syntax or structure)                          |
+| `SLUG_MISMATCH`   | `slug:` in frontmatter doesn't match path-derived slug              |
+| `NULL_BYTES`      | Binary corruption (`\x00`) anywhere in the content                  |
+| `NESTED_QUOTES`   | `title: "outer "inner" outer"` shape that breaks YAML               |
+| `EMPTY_FRONTMATTER` | `---` ... `---` with nothing meaningful between                   |
+
+## Install
+
+For all registered sources that are git repos:
+
+```bash
+gbrain frontmatter install-hook
+```
+
+For one source:
+
+```bash
+gbrain frontmatter install-hook --source <id>
+```
+
+For force-overwrite of an existing pre-commit hook (writes a `.bak`):
+
+```bash
+gbrain frontmatter install-hook --force
+```
+
+The hook lands at `<source>/.githooks/pre-commit`. If `core.hooksPath` is
+unset, the install also runs `git config core.hooksPath .githooks` so the
+hook is picked up without manual git config.
+
+## Bypass
+
+Standard git escape hatch:
+
+```bash
+git commit --no-verify
+```
+
+This skips ALL pre-commit hooks. Use sparingly — the next time the user
+runs `gbrain doctor`, the issues will surface.
+
+## Uninstall
+
+```bash
+gbrain frontmatter install-hook --uninstall
+```
+
+If a `.bak` was saved during install, it's restored as the active hook.
+Otherwise the hook is removed cleanly.
+
+## Behavior on machines without gbrain installed
+
+The hook script checks for `gbrain` on `$PATH`. When missing, it prints a
+one-line warning to stderr and exits 0 — commits aren't blocked just because
+a developer hasn't installed gbrain locally. Once gbrain is installed, the
+hook resumes blocking malformed pages.
+
+## For downstream agent forks
+
+If your OpenClaw wraps gbrain in a host repo
+that's not the brain repo itself, you may want a separate hook strategy:
+
+- **Brain repo IS the host repo** (gbrain skills + brain pages in one repo):
+  install via `gbrain frontmatter install-hook` as above.
+- **Brain repo is a separate registered source** (e.g. `~/brain` registered
+  as a source, host repo is `~/agent-fork`): install in the brain repo only;
+  agent-fork code doesn't need this hook.
+- **Brain repo is auto-generated** (e.g. by a sync daemon writing to a
+  bucket): skip the hook entirely; gate at the writer instead via
+  `import { writeBrainPage } from 'gbrain/brain-writer'` (planned in a
+  later release; currently the CLI is the surface).
+
+## How it fits into the broader frontmatter pipeline
+
+```
+agent writes a page         git commit                 doctor scan
+       ↓                          ↓                          ↓
+[source content]   →  [pre-commit hook validates]   →  [frontmatter_integrity check]
+       ↓                          ↓                          ↓
+  raw file on disk       blocks malformed commits     surfaces existing issues
+                                                             ↓
+                                                  `gbrain frontmatter validate
+                                                   <source-path> --fix`
+                                                   (writes .bak backups)
+```
+
+The hook is the write-time gate; doctor is the audit gate; the CLI is the
+fix tool. They share `parseMarkdown(..., {validate:true})` as the single
+source of truth for what counts as malformed.

docs/integrations/reliability-repair.md

@@ -0,0 +1,66 @@
+# Reliability repair (v0.12.2)
+
+If you ran v0.12.0 on real Postgres or Supabase, two bugs may have corrupted
+data already in your brain. v0.12.1 fixed the code going forward.
+v0.12.2 adds detection in `gbrain doctor` and a standalone `gbrain repair-jsonb`
+command for the mechanically fixable class. PGLite users are not affected.
+
+## What got corrupted
+
+**JSONB double-encode.** Four write sites used
+`${JSON.stringify(x)}::jsonb` with postgres.js, which stored a JSONB
+*string literal* instead of an object. `frontmatter ->> 'key'` returns NULL;
+GIN indexes are ineffective. Affected: `pages.frontmatter`,
+`raw_data.data`, `ingest_log.pages_updated`, `files.metadata`.
+
+**Markdown body truncation.** `splitBody()` treated `---` horizontal rules
+as a body/timeline delimiter, dropping everything after the first rule.
+Wiki-style pages with multiple `##`/`###` sections lost the bulk of their
+content at import time.
+
+## Detect
+
+```
+gbrain doctor
+```
+
+Reports two new checks:
+
+- `jsonb_integrity` — counts double-encoded rows per table and points you
+  at `gbrain repair-jsonb`.
+- `markdown_body_completeness` — heuristic for pages whose `compiled_truth`
+  is suspiciously short compared to `raw_data.data ->> 'content'`.
+
+## Repair
+
+For JSONB (mechanically fixable):
+
+```
+gbrain repair-jsonb
+```
+
+Runs `UPDATE <table> SET <col> = (<col>#>>'{}')::jsonb WHERE jsonb_typeof(<col>) = 'string'`
+across every affected column. Idempotent. Second run reports 0 rows. Use
+`--dry-run` to preview, `--json` for structured output. The `v0_12_2`
+migration runs this automatically on `gbrain upgrade`.
+
+For truncated markdown bodies (source-dependent):
+
+```
+gbrain sync --force
+# or per-page
+gbrain import <slug> --force
+```
+
+v0.12.2 cannot recover content that was already lost if you no longer have
+the source markdown file. `gbrain doctor` tells you which pages look short;
+you decide whether to re-import from source or accept the truncation.
+
+## Verify
+
+```
+gbrain doctor
+```
+
+All four `jsonb_integrity` rows should read zero. `markdown_body_completeness`
+should match your expectations for the corpus.

docs/mcp/ALTERNATIVES.md

@@ -1,8 +1,9 @@
 # Remote MCP Deployment Options
 
 GBrain's MCP server runs via `gbrain serve` (stdio transport). To make it
-accessible from other devices and AI clients, you need an HTTP wrapper and
-a public tunnel. Here are your options.
+accessible from other devices and AI clients, run `gbrain serve --http`
+(built-in HTTP transport with bearer auth, Postgres-only ... see
+[DEPLOY.md](DEPLOY.md)) behind a public tunnel. Here are your tunnel options.
 
 ## ngrok (recommended)
 
@@ -13,8 +14,9 @@ a public tunnel. Here are your options.
 # 1. Install ngrok
 brew install ngrok
 
-# 2. Start your MCP server (behind an HTTP wrapper)
-# See docs/mcp/DEPLOY.md for the server setup
+# 2. Start the built-in HTTP transport
+gbrain serve --http --port 8787
+# See docs/mcp/DEPLOY.md for token setup
 
 # 3. Expose via ngrok
 ngrok http 8787 --url your-brain.ngrok.app
@@ -59,6 +61,7 @@ Both run Bun natively. No bundling, no Deno, no cold start, no timeout limits.
 | All 30 operations | Yes | Yes | Yes |
 | Setup time | 5 min | 10 min | 15 min |
 
-**Note:** `gbrain serve --http` (built-in HTTP transport) is planned but not yet
-implemented. Currently, remote MCP requires a custom HTTP wrapper around `gbrain serve`.
-See [DEPLOY.md](DEPLOY.md) for details.
+**Note:** `gbrain serve --http` is the built-in HTTP transport (v0.22.7+). Bearer auth
+against the `access_tokens` table, default-deny CORS, two-bucket rate limit, body cap,
+per-request audit log. Postgres-only by design (PGLite is local-only). See
+[DEPLOY.md](DEPLOY.md) and [SECURITY.md](../../SECURITY.md) for env vars and tunables.

docs/mcp/CHATGPT.md

@@ -0,0 +1,103 @@
+# Connect GBrain to ChatGPT
+
+**Status (v0.26.0):** Unblocked. GBrain's `gbrain serve --http` ships OAuth 2.1
+with PKCE, which is the ChatGPT MCP connector's hard requirement. Before v1.0,
+this was a P0 TODO — the only major AI client that could not connect.
+
+ChatGPT does not support bearer-token MCP servers. You must use the OAuth 2.1
+HTTP server.
+
+## Setup
+
+### 1. Start the HTTP server
+
+```bash
+gbrain serve --http --port 3131
+```
+
+Save the admin bootstrap token printed on stderr. Open
+`http://localhost:3131/admin` and paste it to access the dashboard.
+
+### 2. Register a ChatGPT client
+
+ChatGPT uses the authorization code flow with PKCE (browser-based OAuth).
+Register from the `/admin` dashboard:
+
+1. Click **Register client**.
+2. Name: `chatgpt`.
+3. Grant type: `authorization_code`.
+4. Scopes: `read`, `write` (leave `admin` unchecked for ChatGPT).
+5. Redirect URI: ChatGPT's OAuth redirect (copy it from the ChatGPT
+   connector setup screen — something like
+   `https://chat.openai.com/connector_platform_oauth_redirect`).
+6. Hit **Register**. The credential-reveal modal shows the `client_id` once
+   with Copy and Download JSON buttons. There is no client secret for
+   PKCE-based public clients.
+
+Host-repo wrappers can register programmatically:
+
+```ts
+await oauthProvider.registerClientManual(
+  'chatgpt',
+  ['authorization_code'],
+  'read write',
+  ['https://chat.openai.com/connector_platform_oauth_redirect'],
+);
+```
+
+### 3. Expose the server publicly
+
+```bash
+brew install ngrok
+ngrok http 3131 --url your-brain.ngrok.app
+```
+
+Your OAuth issuer URL becomes `https://your-brain.ngrok.app`. ChatGPT's
+connector auto-discovers the spec-compliant endpoint at
+`/.well-known/oauth-authorization-server`.
+
+### 4. Add the connector in ChatGPT
+
+1. Open ChatGPT > Settings > Connectors.
+2. Click **Add connector**.
+3. MCP server URL: `https://your-brain.ngrok.app/mcp`.
+4. Client ID: the `client_id` you saved in step 2.
+5. Click **Connect**. ChatGPT opens the OAuth consent page, you approve, and
+   the connector is live.
+
+Start a new conversation and ask ChatGPT to search your brain. The MCP tool
+calls show up in the admin dashboard's live SSE feed in real time.
+
+## Scopes
+
+ChatGPT clients can request any combination of `read`, `write`, `admin`. The
+scopes granted at consent time are enforced on every tool call. Four
+operations are `localOnly` and rejected over HTTP regardless of scope:
+`sync_brain`, `file_upload`, `file_list`, `file_url`. The HTTP server fails
+closed for any attempt to reach local filesystem surface area.
+
+Recommended ChatGPT scope: `read write`. Leave `admin` for your local CLI
+and the admin dashboard.
+
+## Troubleshooting
+
+**"Invalid redirect_uri" during the ChatGPT connector OAuth handshake**
+The registered `redirect-uri` must match ChatGPT's exactly. If ChatGPT
+rejects your server, check the admin dashboard's **Agents** table for the
+client, confirm the redirect URI matches what the error page shows, and
+re-register with the correct URI.
+
+**ChatGPT shows an MCP connection error after approval**
+Open `/admin`, watch the SSE feed, and try again. If no request arrives, the
+connector isn't reaching your ngrok URL. If a request arrives but fails,
+the Request Log tab shows the exact error.
+
+**"Unsupported grant_type" on the token endpoint**
+ChatGPT uses `authorization_code`, which the MCP SDK supports natively.
+If you see this error, verify the client was registered with
+`--grant-types authorization_code` and not `client_credentials`.
+
+## See also
+
+- [DEPLOY.md](DEPLOY.md) — full OAuth 2.1 setup reference
+- [ALTERNATIVES.md](ALTERNATIVES.md) — tunnel options (ngrok, Tailscale, Fly)

docs/mcp/CLAUDE_CODE.md

@@ -21,7 +21,7 @@ claude mcp add gbrain -t http \
 ```
 
 Replace `YOUR-DOMAIN` with your ngrok domain and `YOUR_TOKEN` with a token
-from `bun run src/commands/auth.ts create "claude-code"`.
+from `gbrain auth create "claude-code"`.
 
 ## Verify
 

docs/mcp/CLAUDE_COWORK.md

@@ -12,7 +12,7 @@ For Team/Enterprise plans, an org Owner adds the connector:
    https://YOUR-DOMAIN.ngrok.app/mcp
    ```
 3. Add Bearer token authentication in Advanced Settings
-   (create one with `bun run src/commands/auth.ts create "cowork"`)
+   (create one with `gbrain auth create "cowork"`)
 4. Save
 
 Note: Cowork connects from Anthropic's cloud, not your device. Your server

docs/mcp/CLAUDE_DESKTOP.md

@@ -16,7 +16,7 @@ Remote HTTP servers must be added through the GUI.
    Replace `YOUR-DOMAIN` with your ngrok domain (see
    [ngrok-tunnel recipe](../../recipes/ngrok-tunnel.md) for setup).
 5. Set authentication to **Bearer Token** and paste your token
-   (create one with `bun run src/commands/auth.ts create "claude-desktop"`)
+   (create one with `gbrain auth create "claude-desktop"`)
 6. Save
 
 ## Verify

docs/mcp/DEPLOY.md

@@ -1,35 +1,165 @@
 # Deploy GBrain Remote MCP Server
 
-Access your brain from any device, any AI client. GBrain's MCP server runs locally
-via `gbrain serve` (stdio). For remote access, wrap it in an HTTP server behind a
-public tunnel.
+> **v0.26.0+:** `gbrain serve --http` ships full OAuth 2.1 (client credentials,
+> auth code + PKCE, refresh rotation, optional DCR), an embedded React admin
+> dashboard at `/admin`, scoped operations, and a live SSE activity feed.
+> Pre-v0.26 legacy bearer tokens still work — `verifyAccessToken` falls back
+> to the `access_tokens` table and grandfathers tokens to `read+write+admin`.
+> Postgres-only for the legacy fallback (the `access_tokens` table is Postgres-only);
+> OAuth tables work on both PGLite and Postgres. See [SECURITY.md](../../SECURITY.md)
+> for env vars and tunable defaults.
 
-## Two Paths
+Access your brain from any device, any AI client. GBrain ships two transports:
+`gbrain serve` (stdio) for local agents, and `gbrain serve --http` (v0.26.0+)
+for remote clients over OAuth 2.1.
 
-### Local (zero setup)
+## Three Paths
+
+### Local stdio (zero setup)
 
 ```bash
 gbrain serve
 ```
 
 Works with Claude Code, Cursor, Windsurf, and any MCP client that supports stdio.
-No server, no tunnel, no token needed.
+No server, no tunnel, no token needed. Works on both PGLite and Postgres engines.
 
-### Remote (any device, any AI client)
+### Remote over OAuth 2.1 (recommended, v0.26.0+)
+
+```bash
+gbrain serve --http --port 3131
+ngrok http 3131 --url your-brain.ngrok.app
+gbrain serve --http --port 3131 --public-url https://your-brain.ngrok.app
+```
+
+Built-in HTTP transport with OAuth 2.1, scoped operations, an admin dashboard
+at `/admin`, and a live SSE activity feed. Zero external dependencies. This is
+the only path that works with ChatGPT (OAuth 2.1 + PKCE is required by the
+ChatGPT MCP connector). Pass `--public-url` whenever the server is reachable
+at anything other than `http://localhost:<port>` so the OAuth issuer in
+discovery metadata matches what clients hit (RFC 8414 §3.3).
+
+Supported clients:
+- **ChatGPT** — requires OAuth 2.1 + PKCE. Works natively with `--http`.
+- **Claude Desktop / Cowork** — OAuth 2.1 or legacy bearer tokens.
+- **Perplexity** — OAuth 2.1 client credentials grant.
+- **Claude Code, Cursor, Windsurf** — can use OAuth or legacy bearer.
+
+See the [OAuth 2.1 setup](#oauth-21-setup-v100) section below.
+
+### Remote with legacy bearer tokens (pre-v0.26 deployments) — Postgres only
 
 ```
 Your AI client (Claude Desktop, Perplexity, etc.)
   → ngrok tunnel (https://YOUR-DOMAIN.ngrok.app)
-  → Your HTTP server (wraps gbrain serve)
-  → Supabase Postgres (via pooler connection string)
+  → gbrain serve --http  (built-in transport with bearer auth)
+  → Postgres (pooler connection or self-hosted)
 ```
 
 This requires:
-1. A machine running `gbrain serve` behind an HTTP wrapper
-2. A public tunnel (ngrok, Tailscale, or cloud host)
-3. Bearer token auth for security
+1. A Postgres-backed brain (the `access_tokens` table only exists on Postgres;
+   running `gbrain serve --http` against a PGLite install fails fast at startup)
+2. A machine running `gbrain serve --http`
+3. A public tunnel (ngrok, Tailscale, or cloud host)
+4. A bearer token created via `gbrain auth create <name>`
 
-## Remote Setup
+Pre-v1.0 tokens are grandfathered as `read+write+admin` scopes when you upgrade
+to the HTTP server, so no migration is required.
+
+## OAuth 2.1 Setup (v0.26.0+)
+
+### 1. Start the HTTP server
+
+```bash
+gbrain serve --http --port 3131
+```
+
+On first start, the server prints an **admin bootstrap token** to stderr:
+
+```
+Admin bootstrap token: 3a1f9c...
+Open http://localhost:3131/admin and paste it to log in.
+```
+
+Save this token. Open `http://localhost:3131/admin` and paste it to access the
+dashboard. The dashboard shows live activity, registered clients, request logs,
+and per-client config export.
+
+> **v0.26.9+:** `mcp_request_log.params` and the live SSE activity feed default
+> to a redacted summary `{redacted, kind, declared_keys, unknown_key_count, approx_bytes}`.
+> Declared param keys are kept (intersected against the operation's spec); unknown
+> keys are counted but never named, and byte sizes round up to 1KB so size-probe
+> attacks can't binary-search secret content. Operators on a personal laptop who
+> want raw payloads back can pass `gbrain serve --http --log-full-params` (loud
+> stderr warning fires at startup). Multi-tenant deployments should leave it on
+> the redacted default.
+
+### 2. Register OAuth clients
+
+Register clients from the **`/admin` dashboard**:
+
+1. Click **Register client**.
+2. Enter a name (e.g. `perplexity`, `chatgpt`).
+3. Pick scopes: `read`, `write`, `admin` (checkboxes).
+4. Pick grant type: `client_credentials` for machine-to-machine (Perplexity,
+   Claude Desktop bearer mode) or `authorization_code` for browser-based
+   clients with PKCE (ChatGPT).
+5. For `authorization_code` clients, paste the redirect URI.
+6. Hit **Register**. The credential-reveal modal shows the `client_id` (and
+   `client_secret` for confidential clients) once. Copy or Download JSON
+   immediately — secrets are hashed on storage and never shown again.
+
+Or from the CLI — faster for scripting:
+
+```bash
+gbrain auth register-client perplexity \
+  --grant-types client_credentials \
+  --scopes "read write"
+```
+
+Host-repo wrappers can register programmatically:
+
+```ts
+await oauthProvider.registerClientManual(
+  'perplexity',
+  ['client_credentials'],
+  'read write',
+  [],  // redirect_uris, empty for CC
+);
+```
+
+For self-service client registration (Dynamic Client Registration, RFC 7591),
+start the server with `--enable-dcr`. DCR is off by default.
+
+### 3. Expose the server
+
+```bash
+brew install ngrok
+ngrok config add-authtoken YOUR_TOKEN
+ngrok http 3131 --url your-brain.ngrok.app
+```
+
+Your OAuth issuer URL becomes `https://your-brain.ngrok.app`. The MCP SDK's
+router exposes the spec-compliant discovery endpoint at
+`/.well-known/oauth-authorization-server`.
+
+### 4. Scopes and localOnly
+
+Every operation is tagged `read | write | admin`. Four operations are
+`localOnly` and rejected over HTTP regardless of scope: `sync_brain`,
+`file_upload`, `file_list`, `file_url`. Remote agents cannot reach local
+filesystem surface area.
+
+| Scope | What it allows |
+|-------|---------------|
+| `read` | `search`, `query`, `get_page`, `list_pages`, graph traversal |
+| `write` | `put_page`, `delete_page`, `add_link`, `add_timeline_entry` |
+| `admin` | Client management, token revocation, sweep, local-only ops |
+
+## Legacy Bearer Token Setup
+
+Keep using pre-v0.26 bearer tokens if you aren't ready to migrate. They
+grandfather to `read+write+admin` scopes on the HTTP server.
 
 ### 1. Set up the tunnel
 
@@ -46,13 +176,13 @@ ngrok http 8787 --url your-brain.ngrok.app  # Hobby tier for fixed domain
 
 ```bash
 # Create a token for each client
-bun run src/commands/auth.ts create "claude-desktop"
+gbrain auth create "claude-desktop"
 
 # List all tokens
-bun run src/commands/auth.ts list
+gbrain auth list
 
 # Revoke a token
-bun run src/commands/auth.ts revoke "claude-desktop"
+gbrain auth revoke "claude-desktop"
 ```
 
 Tokens are per-client. Create one for each device/app. Revoke individually
@@ -60,6 +190,7 @@ if compromised. Tokens are stored SHA-256 hashed in your database.
 
 ### 3. Connect your AI client
 
+- **ChatGPT:** [setup guide](CHATGPT.md) (OAuth 2.1 + PKCE, requires `gbrain serve --http`)
 - **Claude Code:** [setup guide](CLAUDE_CODE.md)
 - **Claude Desktop:** [setup guide](CLAUDE_DESKTOP.md) (must use GUI, not JSON config)
 - **Claude Cowork:** [setup guide](CLAUDE_COWORK.md)
@@ -68,7 +199,7 @@ if compromised. Tokens are stored SHA-256 hashed in your database.
 ### 4. Verify
 
 ```bash
-bun run src/commands/auth.ts test \
+gbrain auth test \
   https://YOUR-DOMAIN.ngrok.app/mcp \
   --token YOUR_TOKEN
 ```
@@ -78,6 +209,13 @@ bun run src/commands/auth.ts test \
 All 30 GBrain operations are available remotely, including `sync_brain` and
 `file_upload` (no timeout limits with self-hosted server).
 
+**Security note on `file_upload`:** remote MCP callers are confined to the working
+directory where `gbrain serve` was launched. Symlinks, `..` traversal, and absolute
+paths outside cwd are rejected. Page slugs and filenames are allowlist-validated
+(alphanumeric + hyphens; no control chars, RTL overrides, or backslashes). Local
+CLI callers (`gbrain file upload ...`) keep unrestricted filesystem access since
+the user owns the machine.
+
 ## Deployment Options
 
 See [ALTERNATIVES.md](ALTERNATIVES.md) for a comparison of ngrok, Tailscale
@@ -89,7 +227,7 @@ Funnel, and cloud hosts (Fly.io, Railway).
 Include the Authorization header: `Authorization: Bearer YOUR_TOKEN`
 
 **"invalid_token" error**
-Run `bun run src/commands/auth.ts list` to see active tokens.
+Run `gbrain auth list` to see active tokens.
 
 **"service_unavailable" error**
 Database connection failed. Check your Supabase dashboard for outages.
@@ -109,7 +247,8 @@ Remote servers must be added via Settings > Integrations, NOT
 | put_page | 100-500ms | Write + trigger search_vector update |
 | get_stats | < 100ms | Aggregate query |
 
-**Note:** `gbrain serve --http` (built-in HTTP transport) is planned but not yet
-implemented. Currently, remote MCP requires a custom HTTP wrapper. See the
-production deployment pattern in the [voice recipe](../../recipes/twilio-voice-brain.md)
-for a reference implementation.
+**Note:** `gbrain serve --http` shipped in v0.26.0 with OAuth 2.1 + admin
+dashboard baked into the binary. The custom HTTP wrapper pattern (see
+[voice recipe](../../recipes/twilio-voice-brain.md)) is still supported for
+teams that need bespoke middleware, but for most remote deployments the
+built-in server is the recommended path.

docs/mcp/PERPLEXITY.md

@@ -10,7 +10,7 @@ Perplexity Computer supports remote MCP servers with bearer token authentication
    - **URL:** `https://YOUR-DOMAIN.ngrok.app/mcp`
    - **Authentication:** API Key / Bearer Token
    - **Token:** your GBrain access token
-     (create one with `bun run src/commands/auth.ts create "perplexity"`)
+     (create one with `gbrain auth create "perplexity"`)
 4. Save
 
 Replace `YOUR-DOMAIN` with your ngrok domain (see

docs/progress-events.md

@@ -0,0 +1,191 @@
+# Progress events
+
+Canonical reference for the JSONL progress stream that `gbrain` writes to
+`stderr` when a bulk command runs with `--progress-json`. Stable from
+v0.15.2. Additive changes only; no renames or removals without a major
+version bump.
+
+Most humans won't read this page. Agents parsing progress will.
+
+## When do I get these events?
+
+Any of these commands stream events when `--progress-json` is set:
+
+- `gbrain doctor` (DB checks, JSONB integrity, markdown body completeness,
+  integrity sample)
+- `gbrain orphans`
+- `gbrain embed`
+- `gbrain files sync`
+- `gbrain export`
+- `gbrain extract [links|timeline|all]` (fs or db source)
+- `gbrain import`
+- `gbrain sync`
+- `gbrain migrate --to …`
+- `gbrain repair-jsonb`
+- `gbrain check-backlinks`
+- `gbrain lint`
+- `gbrain integrity auto`
+- `gbrain eval`
+- `gbrain apply-migrations` (the orchestrator + every child command)
+
+Non-bulk commands (`stats`, `graph-query`, `get`, `put`, etc.) don't emit
+events — they return in under a second.
+
+## Channel
+
+- Progress events: **`stderr`**, one JSON object per line, `\n`-terminated.
+- Data results (`--json` payloads from each command): **`stdout`**.
+- Final human summaries: **`stdout`**.
+
+Agents can safely capture stdout for their result parsing and read stderr
+separately for progress.
+
+## Flags
+
+| Flag | Behavior |
+|---|---|
+| *(none)* | Auto. TTY: `\r`-rewriting single line. Non-TTY: plain line-per-event on stderr. |
+| `--progress-json` | Force JSON-lines mode on stderr (this doc). |
+| `--quiet` | Suppress progress entirely. Warnings and final output still print. |
+| `--progress-interval=<ms>` | Override the minimum interval between tick emits (default 1000). |
+
+Global flags: parsed by `src/core/cli-options.ts` before command dispatch,
+so `gbrain --progress-json doctor` works the same as
+`gbrain doctor --progress-json` (the latter also works — per-command
+parsers see the flag via the shared `CliOptions` singleton).
+
+## Event types
+
+Every event is a single-line JSON object with these common fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `event` | string | One of: `start`, `tick`, `heartbeat`, `finish`, `abort`. |
+| `phase` | string | Machine-stable snake_case, dot-separated. See "Phase names" below. |
+| `ts` | ISO 8601 UTC string | Event emission time. |
+| `elapsed_ms` | number | Ms since the phase started. Present on `tick`/`heartbeat`/`finish`/`abort`. |
+
+### `start`
+
+Emitted when a phase begins.
+
+```json
+{"event":"start","phase":"doctor.db_checks","ts":"2026-04-20T12:34:56.789Z"}
+{"event":"start","phase":"import.files","total":52000,"ts":"2026-04-20T12:34:56.789Z"}
+```
+
+Optional fields:
+
+- `total` — the total item count if known at start.
+
+### `tick`
+
+Emitted periodically during iteration. Time- and item-gated: the reporter
+won't emit more often than `minIntervalMs` (default 1000) and
+`minItems` (default `max(10, ceil(total/100))`).
+
+```json
+{"event":"tick","phase":"orphans.scan","done":15000,"total":52000,"pct":28.8,"elapsed_ms":4200,"eta_ms":10300,"ts":"..."}
+```
+
+Fields:
+
+- `done` — items completed in this phase.
+- `total` — total items, if known. Omitted when the scan doesn't have a
+  total up front (e.g. a streaming iterator).
+- `pct` — `done/total * 100`, one decimal. Omitted when `total` is unknown.
+- `eta_ms` — projected ms until `done === total`, from the observed rate.
+  Omitted when `total` is unknown.
+- `note` — optional string with the current item (e.g. a slug or filename).
+
+### `heartbeat`
+
+Emitted for long-running single operations that don't iterate
+(e.g. `SELECT` against a 50K-row table). No `done`, no `total` — just a
+signal that work is still happening.
+
+```json
+{"event":"heartbeat","phase":"doctor.markdown_body_completeness","note":"scanning pages for truncation…","elapsed_ms":1000,"ts":"..."}
+```
+
+### `finish`
+
+Emitted when a phase completes normally.
+
+```json
+{"event":"finish","phase":"import.files","done":52000,"total":52000,"elapsed_ms":187000,"ts":"..."}
+```
+
+### `abort`
+
+Emitted by a single process-level SIGINT/SIGTERM handler that tracks every
+live phase. After `abort`, no further events emit for that phase.
+
+```json
+{"event":"abort","phase":"doctor.markdown_body_completeness","reason":"SIGINT","elapsed_ms":5300,"ts":"..."}
+```
+
+## Phase names
+
+Phases use `snake_case.dot.path` naming. A fresh reporter starts at the
+root; `child()` composition appends to the parent's current phase, so a
+sync that calls import emits `sync.import.<file>`, not `import.<file>`.
+
+Stable phase names shipped in v0.15.2:
+
+- `doctor.db_checks` (umbrella for all DB-side doctor checks)
+- `orphans.scan`
+- `embed.pages`
+- `extract.links_fs`, `extract.timeline_fs`, `extract.links_db`, `extract.timeline_db`
+- `import.files`
+- `sync.deletes`, `sync.renames`, `sync.imports`
+- `migrate.copy_pages`, `migrate.copy_links`
+- `repair_jsonb.run`, `repair_jsonb.<table>.<column>`
+- `backlinks.scan`
+- `lint.pages`
+- `integrity.auto`
+- `eval.single`, `eval.ab`
+- `export.pages`
+- `files.sync`
+
+Sub-phases exposed via `child()`:
+
+- `sync.import.files` — nested inside a sync
+- `apply_migrations.v0_12_2.jsonb_repair` — nested inside the orchestrator
+
+## Subprocess inheritance
+
+When a parent CLI spawns `gbrain …` child processes (mostly in
+`src/commands/migrations/*`), global flags (`--quiet`, `--progress-json`,
+`--progress-interval`) are propagated to the child's argv via the
+`childGlobalFlags()` helper in `src/core/cli-options.ts`. Child stderr
+passes straight through `stdio: 'inherit'` so the event stream is one
+merged JSONL feed on the parent's stderr.
+
+One exception: the orchestrator phase in `migrations/v0_12_2.ts` that
+captures child stdout (`repair-jsonb --dry-run --json` for verification)
+does not pass `--progress-json` to avoid any risk of stdout pollution
+breaking the orchestrator's `JSON.parse`. Its stdio is explicit:
+`['ignore', 'pipe', 'inherit']` so stderr still flows through.
+
+## Minion jobs
+
+`gbrain jobs work` (the Minion worker daemon) keeps progress in the DB,
+not on stderr. Each Minion handler that runs a bulk core (embed, sync,
+extract, import, backlinks) calls `job.updateProgress({done, total,
+…})` per iteration. Agents read per-job progress via the
+`get_job_progress` MCP operation or `gbrain jobs get <id>`.
+
+The `jobs work` daemon itself emits coarse one-line-per-job stderr output
+for liveness only. Per-page detail lives in the DB.
+
+## Compatibility
+
+- **Added**: only. A new event type, a new field, a new phase name — all
+  safe. Agents must ignore unknown fields and unknown event types.
+- **Removed/renamed**: never without a major version bump.
+- **Schema changes**: announced in `CHANGELOG.md` and in
+  `skills/migrations/v<next>.md`.
+
+If your agent depends on this schema and something surprises you, open
+an issue with the event you received and what you expected.

docs/storage-tiering.md

@@ -0,0 +1,210 @@
+# Storage Tiering: db-tracked vs db-only directories
+
+## Overview
+
+GBrain supports storage tiering to separate version-controlled content from bulk machine-generated data. This prevents git repositories from becoming bloated with large amounts of automatically generated content while still preserving it in the database.
+
+> Note on naming: prior to v0.22.11 the keys were `git_tracked` / `supabase_only`. The canonical names are now `db_tracked` / `db_only` (engine-agnostic — works on both PGLite and Postgres). The deprecated keys still load with a once-per-process warning. Run `gbrain doctor --fix` for an automated rename when that path lands.
+
+## Configuration
+
+Add a `storage` section to your `gbrain.yml` file in the brain repository root:
+
+```yaml
+storage:
+  # Directories that are version-controlled (human-edited, committed to git).
+  db_tracked:
+    - people/
+    - companies/
+    - deals/
+    - concepts/
+    - yc/
+    - ideas/
+    - projects/
+
+  # Directories persisted via the brain database only (bulk machine-generated
+  # content). Written to disk as a local cache but not committed to git;
+  # `gbrain sync` auto-manages .gitignore for these paths. `gbrain export
+  # --restore-only` repopulates missing files from the database.
+  db_only:
+    - media/x/
+    - media/articles/
+    - meetings/transcripts/
+```
+
+Path requirements:
+
+- Each directory must end with `/` for canonical form. The validator auto-normalizes missing trailing slashes (one-time info note shows what changed).
+- A directory cannot appear in both tiers — that's a tier-overlap error and `loadStorageConfig` throws `StorageConfigError`. Edit `gbrain.yml` to remove the overlap and try again.
+
+## Behavior Changes
+
+### 1. `gbrain sync` — automatic .gitignore management
+
+When storage configuration is present, `gbrain sync` automatically manages `.gitignore` entries on every successful sync:
+
+- Adds missing `db_only` directory patterns to `.gitignore`.
+- Idempotent — re-running adds no duplicate entries.
+- Stable comment header so the managed block is grep-able.
+- Skipped on `--dry-run` (don't mutate disk in preview mode).
+- Skipped on `blocked_by_failures` status (sync state is inconsistent).
+- Skipped when the repo is a git submodule (`.git` is a file, not a directory) — submodule .gitignore changes don't survive parent updates. A warning explains.
+- Skipped entirely when `GBRAIN_NO_GITIGNORE=1` is set (escape hatch for shared-repo setups where a maintainer wants gbrain to leave .gitignore alone).
+- Failures (write permission denied, etc.) are caught and logged, never crash sync.
+
+Example `.gitignore` addition:
+
+```gitignore
+# Auto-managed by gbrain (db_only directories)
+media/x/
+media/articles/
+meetings/transcripts/
+```
+
+### 2. `gbrain export --restore-only` — repopulate missing db_only files
+
+```bash
+# Restore only missing db_only files from the database.
+gbrain export --restore-only --repo /path/to/brain
+
+# Filter by page type.
+gbrain export --restore-only --type media --repo /path/to/brain
+
+# Filter by slug prefix.
+gbrain export --restore-only --slug-prefix media/x/ --repo /path/to/brain
+
+# Combine filters.
+gbrain export --restore-only --type media --slug-prefix media/x/ --repo /path/to/brain
+```
+
+The `--restore-only` flag:
+
+- Resolves repoPath via the chain `--repo` → typed `sources.getDefault()` → hard error.
+  Never falls through to the current directory.
+- Only exports pages that match `db_only` patterns AND are missing from disk.
+- Ideal for container restart recovery and fresh clones.
+
+### 3. `gbrain storage status` — storage-tier health dashboard
+
+```bash
+# Human-readable status.
+gbrain storage status --repo /path/to/brain
+
+# JSON output for scripts and orchestrators.
+gbrain storage status --repo /path/to/brain --json
+```
+
+Output includes:
+
+- Total page counts by storage tier.
+- Disk usage breakdown by tier.
+- Missing files that need restoration (top 10 shown; full list in `--json`).
+- Configuration validation warnings.
+- Current tier directory listing.
+
+Example output:
+
+```
+Storage Status
+==============
+
+Repository: /data/brain
+Total pages: 15,243
+
+Storage Tiers:
+-------------
+DB tracked:     2,156 pages
+DB only:        12,887 pages
+Unspecified:    200 pages
+
+Disk Usage:
+-----------
+DB tracked:     45.2 MB
+DB only:        2.1 GB
+
+Missing Files (need restore):
+-----------------------------
+  media/x/tweet-1234567890
+  media/x/tweet-0987654321
+  ... and 47 more
+
+Use: gbrain export --restore-only --repo "/data/brain"
+
+Configuration:
+--------------
+DB tracked directories:
+  - people/
+  - companies/
+  - deals/
+
+DB-only directories:
+  - media/x/
+  - media/articles/
+  - meetings/transcripts/
+```
+
+## Validation
+
+`loadStorageConfig` runs `normalizeAndValidateStorageConfig` after parsing:
+
+- Auto-fixes (silent, with one-time info note showing what changed):
+  - Missing trailing `/` is added: `'media/x'` → `'media/x/'`.
+- Throws `StorageConfigError` (caller sees a clean exit-1 with actionable message):
+  - Same directory in both `db_tracked` and `db_only` (ambiguous routing).
+
+## Use cases
+
+### Brain repository scaling
+
+Perfect for brain repositories crossing 50K-200K+ files where:
+
+- Core knowledge (people, companies, deals) remains git-tracked.
+- Bulk data (tweets, articles, transcripts) moves to db_only.
+- Development stays fast with smaller git repos.
+- Full data remains available via the database.
+
+### Container-based deployments
+
+Essential for ephemeral container environments:
+
+- Git repo contains only essential files.
+- Container restarts don't lose db_only data.
+- `gbrain export --restore-only` quickly restores bulk files when needed.
+- Local disk acts as a cache layer.
+
+### Multi-environment consistency
+
+Enables consistent data access across environments:
+
+- Development: small git clone, restore bulk data on demand.
+- Production: full dataset via the database, selective local caching.
+- CI/CD: fast tests with git-tracked data only.
+
+## Migration strategy
+
+1. **Assess current repository**: use `gbrain storage status` to understand current distribution.
+2. **Plan directory structure**: identify which directories should be db_tracked vs db_only.
+3. **Create `gbrain.yml`**: add storage configuration to the repository root.
+4. **Test with dry-run**: `gbrain sync --dry-run` to verify behavior; `.gitignore` is NOT touched on dry-run.
+5. **Run a real sync**: `gbrain sync` updates `.gitignore` automatically on success.
+6. **Verify restore**: test `gbrain export --restore-only --repo .` against a small db_only directory.
+
+## Best practices
+
+- **Directory naming**: end storage paths with `/` (canonical form). The validator normalizes if you forget.
+- **Start small**: begin with clearly machine-generated directories in `db_only`.
+- **Address validation errors**: tier overlap is an error, not a warning. Fix it before sync.
+- **Test restore**: regularly test `--restore-only` in staging environments.
+- **Document decisions**: comment your `gbrain.yml` to explain tier choices.
+
+## PGLite engine note
+
+On the PGLite engine (gbrain's local-only embedded Postgres), the "DB" your db_only pages live in IS the local file gbrain uses for everything else. The `.gitignore` housekeeping still helps (keeps bulk content out of git history), but the offload-to-DB promise is technically vacuous. A once-per-process soft-warn explains when the engine is detected. To get full tiering, migrate to Postgres with `gbrain migrate --to supabase`.
+
+## Compatibility
+
+- **Backward compatible**: systems without `gbrain.yml` work unchanged.
+- **Progressive enhancement**: add configuration when needed.
+- **Database unchanged**: all data remains in Postgres regardless of tier.
+- **Existing workflows**: all existing `sync` and `export` behavior preserved.
+- **Deprecated keys**: `git_tracked` / `supabase_only` still load with a once-per-process warning.

evals/embedding-provider-eval.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "description": "Embedding provider smoke test — verifies semantic search returns expected results for known brain content. Run after any embedding model change or migration.",
+  "queries": [
+    {
+      "id": "yc-labs-strategy",
+      "query": "YC Labs strategy and product team",
+      "relevant": [
+        "originals/yc-labs-internal-team",
+        "originals/harj-yc-labs-strategy-2026-05"
+      ]
+    },
+    {
+      "id": "garry-tan-person",
+      "query": "Who is Garry Tan",
+      "relevant": [
+        "people/garry-tan"
+      ]
+    },
+    {
+      "id": "gstack-project",
+      "query": "GStack open source AI coding framework",
+      "relevant": [
+        "projects/gstack/gstackbrain"
+      ]
+    },
+    {
+      "id": "yc-carry-compensation",
+      "query": "GP carry and compensation structure at YC",
+      "relevant": [
+        "originals/harj-yc-labs-strategy-2026-05"
+      ]
+    },
+    {
+      "id": "meeting-search",
+      "query": "recent office hours meeting notes",
+      "relevant": []
+    }
+  ]
+}

gbrain.yml

@@ -0,0 +1,18 @@
+storage:
+  # Directories that are version-controlled — human-curated, edited by hand.
+  db_tracked:
+    - people/
+    - companies/
+    - deals/
+    - concepts/
+    - yc/
+    - ideas/
+    - projects/
+
+  # Directories persisted via the brain database only — bulk machine-generated
+  # content. .gitignored automatically by `gbrain sync`. Restorable from the DB
+  # via `gbrain export --restore-only`.
+  db_only:
+    - media/x/
+    - media/articles/
+    - meetings/transcripts/

llms.txt

@@ -0,0 +1,52 @@
+# GBrain
+
+> GBrain is a personal knowledge brain and GStack mod for agent platforms. Pluggable engines (PGLite default, Postgres+pgvector for scale), contract-first operations, 26 fat-markdown skills. Teaches agents brain ops, ingestion, enrichment, scheduling, identity, and access control.
+
+Repo: https://github.com/garrytan/gbrain
+
+## Core entry points
+
+- [AGENTS.md](https://raw.githubusercontent.com/garrytan/gbrain/master/AGENTS.md): Start here if you are not Claude Code. Install order, trust boundary, skill resolver, config/debug/migration pointers.
+- [CLAUDE.md](https://raw.githubusercontent.com/garrytan/gbrain/master/CLAUDE.md): Architecture reference. Key files, trust boundaries, engine factory, test layout.
+- [INSTALL_FOR_AGENTS.md](https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md): 9-step agent installation.
+- [skills/RESOLVER.md](https://raw.githubusercontent.com/garrytan/gbrain/master/skills/RESOLVER.md): Skill dispatcher. Read first for any task.
+- [README.md](https://raw.githubusercontent.com/garrytan/gbrain/master/README.md): Project overview, benchmarks, 30-minute setup.
+
+## Configuration
+
+- [docs/ENGINES.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/ENGINES.md): PGLite vs Postgres trade-off and when to migrate.
+- [docs/GBRAIN_RECOMMENDED_SCHEMA.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_RECOMMENDED_SCHEMA.md): MECE directory structure (people/, companies/, concepts/).
+- [docs/guides/live-sync.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/live-sync.md): Incremental markdown sync setup.
+- [docs/guides/cron-schedule.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/cron-schedule.md): Recurring job scheduling.
+- [docs/guides/minions-deployment.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/minions-deployment.md): Deploying the gbrain jobs worker: crontab + watchdog, inline --follow, systemd/Procfile/fly.toml, upgrade checklist.
+- [docs/guides/quiet-hours.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/quiet-hours.md): Notification hold + timezone-aware delivery.
+- [docs/mcp/DEPLOY.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/mcp/DEPLOY.md): MCP server deployment.
+
+## Debugging
+
+- [docs/GBRAIN_VERIFY.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_VERIFY.md): 7-check post-setup verification. Start here when something feels off.
+- [docs/guides/minions-fix.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/minions-fix.md): Troubleshooting the Minions job queue.
+- [docs/integrations/reliability-repair.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/integrations/reliability-repair.md): Data integrity recovery.
+
+## Migrations
+
+- [docs/UPGRADING_DOWNSTREAM_AGENTS.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/UPGRADING_DOWNSTREAM_AGENTS.md): Patches for downstream agent skill forks. One section per release.
+- [skills/migrations/](https://raw.githubusercontent.com/garrytan/gbrain/master/skills/migrations/): Per-version (v0.5.0 - v0.14.1) agent-executable migration instructions.
+- [CHANGELOG.md](https://raw.githubusercontent.com/garrytan/gbrain/master/CHANGELOG.md): Release-summary voice + itemized changes + self-repair block per version.
+
+## Philosophy
+
+- [docs/ethos/THIN_HARNESS_FAT_SKILLS.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/ethos/THIN_HARNESS_FAT_SKILLS.md): Why skills live in markdown.
+- [docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md): Homebrew for Personal AI.
+
+## Optional
+
+- [docs/designs/](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/designs/): Forward-looking designs.
+- [docs/architecture/infra-layer.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/architecture/infra-layer.md): Shared infra patterns.
+
+## Operational tips
+
+- `gbrain doctor [--json] [--fast] [--fix]` - built-in health checks.
+- `gbrain orphans [--json]` - pages with zero inbound wikilinks.
+- `gbrain repair-jsonb [--dry-run]` - repair v0.12.0 double-encoded JSONB rows.
+- `gbrain upgrade` runs post-upgrade + apply-migrations.

openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gbrain",
-  "version": "0.4.1",
+  "version": "0.25.1",
   "description": "Personal knowledge brain with Postgres + pgvector hybrid search",
   "family": "bundle-plugin",
   "configSchema": {
@@ -24,13 +24,51 @@
     }
   },
   "skills": [
-    "skills/ingest",
-    "skills/query",
-    "skills/maintain",
-    "skills/enrich",
+    "skills/academic-verify",
+    "skills/archive-crawler",
+    "skills/article-enrichment",
+    "skills/book-mirror",
+    "skills/brain-ops",
+    "skills/brain-pdf",
     "skills/briefing",
+    "skills/citation-fixer",
+    "skills/concept-synthesis",
+    "skills/cross-modal-review",
+    "skills/cron-scheduler",
+    "skills/daily-task-manager",
+    "skills/daily-task-prep",
+    "skills/data-research",
+    "skills/enrich",
+    "skills/idea-ingest",
+    "skills/ingest",
+    "skills/maintain",
+    "skills/media-ingest",
+    "skills/meeting-ingestion",
+    "skills/minion-orchestrator",
+    "skills/perplexity-research",
+    "skills/query",
+    "skills/reports",
+    "skills/repo-architecture",
+    "skills/signal-detector",
+    "skills/skill-creator",
+    "skills/skillify",
+    "skills/skillpack-check",
+    "skills/soul-audit",
+    "skills/strategic-reading",
+    "skills/testing",
+    "skills/voice-note-ingest",
+    "skills/webhook-transforms"
+  ],
+  "shared_deps": [
+    "skills/conventions",
+    "skills/_brain-filing-rules.md",
+    "skills/_brain-filing-rules.json",
+    "skills/_output-rules.md"
+  ],
+  "excluded_from_install": [
+    "skills/setup",
     "skills/migrate",
-    "skills/setup"
+    "skills/publish"
   ],
   "openclaw": {
     "compat": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbrain",
-  "version": "0.10.0",
+  "version": "0.28.7",
   "description": "Postgres-native personal knowledge brain with hybrid RAG search",
   "type": "module",
   "main": "src/core/index.ts",
@@ -11,15 +11,52 @@
     ".": "./src/core/index.ts",
     "./engine": "./src/core/engine.ts",
     "./types": "./src/core/types.ts",
-    "./operations": "./src/core/operations.ts"
+    "./operations": "./src/core/operations.ts",
+    "./minions": "./src/core/minions/index.ts",
+    "./engine-factory": "./src/core/engine-factory.ts",
+    "./pglite-engine": "./src/core/pglite-engine.ts",
+    "./link-extraction": "./src/core/link-extraction.ts",
+    "./import-file": "./src/core/import-file.ts",
+    "./transcription": "./src/core/transcription.ts",
+    "./embedding": "./src/core/embedding.ts",
+    "./config": "./src/core/config.ts",
+    "./markdown": "./src/core/markdown.ts",
+    "./backoff": "./src/core/backoff.ts",
+    "./search/hybrid": "./src/core/search/hybrid.ts",
+    "./search/expansion": "./src/core/search/expansion.ts",
+    "./extract": "./src/commands/extract.ts"
   },
   "scripts": {
     "dev": "bun run src/cli.ts",
     "build": "bun build --compile --outfile bin/gbrain src/cli.ts",
     "build:all": "bun build --compile --target=bun-darwin-arm64 --outfile bin/gbrain-darwin-arm64 src/cli.ts && bun build --compile --target=bun-linux-x64 --outfile bin/gbrain-linux-x64 src/cli.ts",
+    "build:admin": "cd admin && bun run build",
     "build:schema": "bash scripts/build-schema.sh",
-    "test": "bun test",
-    "test:e2e": "bun test test/e2e/",
+    "build:llms": "bun run scripts/build-llms.ts",
+    "build:pglite-snapshot": "bun run scripts/build-pglite-snapshot.ts",
+    "test": "bash scripts/run-unit-parallel.sh",
+    "test:full": "bun run verify && bash scripts/run-unit-parallel.sh && bun run test:slow && ([ -n \"$DATABASE_URL\" ] && bash scripts/run-e2e.sh || echo '[test:full] skipped E2E (no DATABASE_URL); run docker-compose -f docker-compose.ci.yml up + bun run test:e2e to include' 1>&2)",
+    "verify": "bun run check:privacy && bun run check:jsonb && bun run check:progress && bun run check:test-isolation && bun run check:wasm && bun run check:admin-build && bun run check:admin-scope-drift && bun run check:cli-exec && bun run typecheck",
+    "check:admin-scope-drift": "scripts/check-admin-scope-drift.sh",
+    "check:cli-exec": "scripts/check-cli-executable.sh",
+    "check:all": "scripts/check-privacy.sh && scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && scripts/check-no-legacy-getconnection.sh && scripts/check-test-isolation.sh && scripts/check-trailing-newline.sh && scripts/check-wasm-embedded.sh && scripts/check-exports-count.sh && scripts/check-admin-build.sh && scripts/check-admin-scope-drift.sh && scripts/check-cli-executable.sh",
+    "check:wasm": "scripts/check-wasm-embedded.sh",
+    "check:newlines": "scripts/check-trailing-newline.sh",
+    "test:e2e": "bash scripts/run-e2e.sh",
+    "test:slow": "bash scripts/run-slow-tests.sh",
+    "test:profile": "bash scripts/profile-tests.sh",
+    "test:serial": "bash scripts/run-serial-tests.sh",
+    "ci:local": "bash scripts/ci-local.sh",
+    "ci:local:diff": "bash scripts/ci-local.sh --diff",
+    "ci:select-e2e": "bun run scripts/select-e2e.ts",
+    "typecheck": "tsc --noEmit",
+    "check:jsonb": "scripts/check-jsonb-pattern.sh",
+    "check:privacy": "scripts/check-privacy.sh",
+    "check:progress": "scripts/check-progress-to-stdout.sh",
+    "check:exports-count": "scripts/check-exports-count.sh",
+    "check:admin-build": "scripts/check-admin-build.sh",
+    "check:test-isolation": "scripts/check-test-isolation.sh",
+    "postinstall": "command -v gbrain >/dev/null 2>&1 && gbrain apply-migrations --yes --non-interactive || echo '[gbrain] postinstall skipped. If installed via bun install -g github:...: run `gbrain doctor` and `gbrain apply-migrations --yes` manually. See https://github.com/garrytan/gbrain/issues/218' 1>&2",
     "prepublish:clawhub": "bun run build:all",
     "publish:clawhub": "clawhub package publish . --family bundle-plugin"
   },
@@ -29,18 +66,43 @@
     }
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.71",
+    "@ai-sdk/google": "^3.0.64",
+    "@ai-sdk/openai": "^3.0.53",
+    "@ai-sdk/openai-compatible": "^2.0.41",
     "@anthropic-ai/sdk": "^0.30.0",
     "@aws-sdk/client-s3": "^3.1028.0",
-    "@electric-sql/pglite": "^0.4.4",
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@dqbd/tiktoken": "^1.0.22",
+    "@electric-sql/pglite": "0.4.3",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "ai": "^6.0.168",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.5",
+    "eventsource-parser": "^3.0.8",
+    "express": "^5.1.0",
+    "express-rate-limit": "^7.5.0",
     "gray-matter": "^4.0.3",
     "marked": "^18.0.0",
     "openai": "^4.0.0",
     "pgvector": "^0.2.0",
-    "postgres": "^3.4.0"
+    "postgres": "^3.4.0",
+    "tree-sitter-wasms": "0.1.13",
+    "web-tree-sitter": "0.22.6",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@types/cookie-parser": "^1.4.7",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "bun-types": "^1.3.13",
+    "typescript": "^5.6.0"
+  },
+  "trustedDependencies": [
+    "@electric-sql/pglite"
+  ],
+  "engines": {
+    "bun": ">=1.3.10"
   },
   "license": "MIT"
 }

recipes/restart-sweep.md

@@ -0,0 +1,654 @@
+---
+id: restart-sweep
+name: Restart Sweep
+version: 0.1.0
+description: Detect Telegram messages dropped during OpenClaw gateway restarts. Reads OpenClaw session state, alerts on aborted-mid-run sessions and (opt-in) suspicious silence gaps. Cooldown-gated so repeat detections don't spam.
+category: reflex
+requires: []
+secrets:
+  - name: OPENCLAW_OWNER_IDS
+    description: Comma-separated user IDs that own this brain instance
+    where: openclaw config — your own user IDs from the platforms you connect
+  - name: OPENCLAW_TELEGRAM_GROUP
+    description: Target Telegram group ID for restart alerts (negative number for groups)
+    where: forward a message from the group to @userinfobot, copy the chat.id
+health_checks:
+  - type: env_exists
+    name: OPENCLAW_OWNER_IDS
+    label: Owner IDs configured
+  - type: env_exists
+    name: OPENCLAW_TELEGRAM_GROUP
+    label: Telegram group configured
+  - type: command
+    argv: [openclaw, sessions, --json]
+    label: OpenClaw CLI reachable
+setup_time: 10 min
+cost_estimate: "$0 (no per-call cost; runs locally on cron)"
+---
+
+# Restart Sweep: Detect Dropped Messages After Gateway Restarts
+
+When the OpenClaw gateway restarts, webhook-delivered Telegram messages
+that haven't been processed yet get dropped permanently. Long-poll bots
+can replay missed updates via `getUpdates`. Webhook bots cannot. This
+recipe detects the gap by reading OpenClaw's session state and alerting
+when a session was active just before a restart but silent afterward.
+
+## IMPORTANT: Instructions for the Agent
+
+**You are the installer.** This recipe is written for YOU (the AI agent)
+to execute on behalf of the user. Follow these steps precisely.
+
+**Stop points (MUST pause and verify before continuing):**
+- After Step 1: prerequisites pass? If not, fix before proceeding.
+- After Step 4: dry run produces sensible output? If not, debug before
+  wiring cron.
+- After Step 5: cron entry created and visible in `crontab -l`? If not,
+  cron isn't installed.
+
+**When something fails:** Tell the user EXACTLY what failed, what it
+means, and what to try. Never say "something went wrong."
+
+## What this does
+
+1. Reads `/tmp/bootstrap-services.log` (or `$OPENCLAW_BOOTSTRAP_LOG`)
+   to find when the gateway last restarted. Falls back to `now() - 30
+   minutes` if the log isn't readable.
+2. Runs `openclaw sessions --json` to enumerate all live sessions.
+3. Filters to Telegram group sessions matching `$OPENCLAW_TELEGRAM_GROUP`.
+4. Flags sessions with `abortedLastRun: true` (strong signal of a
+   dropped message). Optionally flags sessions that were active in the
+   5 minutes before restart but silent in the 10 minutes after — gated
+   behind `OPENCLAW_RESTART_SWEEP_AGGRESSIVE=1` because the timing
+   heuristic produces false positives during quiet periods.
+5. Cooldown layer: each sessionKey alerted gets stamped with a
+   `lastAlertedAt` timestamp. Re-alerting on the same sessionKey is
+   suppressed for 6 hours regardless of whether the synthesized restart
+   time matches. This prevents the "missing bootstrap log →
+   re-alert-every-5-minutes-forever" failure mode.
+6. Sends one alert per cycle to Telegram (or stdout if no Telegram
+   config), then records the alert in
+   `~/.gbrain/integrations/restart-sweep/alerted.json`.
+
+## Prerequisites
+
+- OpenClaw running with Telegram in webhook mode (long-poll mode
+  doesn't need this — `getUpdates` recovers missed messages on restart)
+- The `openclaw` CLI on PATH (or you'll provide an absolute path in
+  Step 5)
+- Telegram bot token already configured in OpenClaw, group ID and
+  optional topic ID known
+- Cron available on the host (this recipe schedules a 5-minute job;
+  systemd timers, launchd, or any other scheduler also work — adapt
+  Step 5 accordingly)
+
+## Step 1: Verify prerequisites
+
+```bash
+openclaw sessions --json | head -40
+```
+
+Should print JSON with a `sessions` array. If it errors, fix
+`openclaw` reachability before continuing.
+
+Decide a host-repo install path. The recipe assumes
+`~/openclaw/scripts/restart-sweep.mjs` and the user's `.env` lives at
+`~/openclaw/.env`. Adapt to your repo layout.
+
+## Step 2: Collect the secrets
+
+Confirm with the user:
+
+- `OPENCLAW_OWNER_IDS` — comma-separated user IDs (e.g. `123456789,987654321`)
+- `OPENCLAW_TELEGRAM_GROUP` — the target group ID (negative number for
+  group chats, e.g. `-1001234567890`). Forward a message from the
+  group to `@userinfobot` to get it.
+- `OPENCLAW_ALERT_TOPIC` — optional, the topic/thread ID for forum
+  groups. Open the topic in Telegram, the URL ends with the thread ID.
+
+Add these three lines to the host's `.env` (or wherever the host loads
+env from):
+
+```bash
+OPENCLAW_OWNER_IDS=...
+OPENCLAW_TELEGRAM_GROUP=...
+OPENCLAW_ALERT_TOPIC=...
+```
+
+Optional tuning:
+
+```bash
+# Set to 1 to enable the timing-based heuristic (active before restart,
+# silent after). Off by default because it false-positives during quiet
+# periods.
+OPENCLAW_RESTART_SWEEP_AGGRESSIVE=1
+
+# Override the bootstrap log path (default /tmp/bootstrap-services.log)
+OPENCLAW_BOOTSTRAP_LOG=/var/log/openclaw/bootstrap.log
+```
+
+## Step 3: Write the script to the host repo
+
+Write the script content from the next section to
+`~/openclaw/scripts/restart-sweep.mjs` (or wherever the user picks).
+The script is self-contained — no npm install needed, just Node 18+
+or Bun.
+
+<!-- restart-sweep:script -->
+```javascript
+#!/usr/bin/env node
+
+/**
+ * Restart Message Sweep Script
+ *
+ * Detects Telegram messages dropped during OpenClaw gateway restarts.
+ * Webhook-delivered messages can't be replayed via getUpdates, so we
+ * read OpenClaw's session state and look for sessions that show signs
+ * of dropped processing.
+ *
+ * Runs under Node 18+ or Bun. Copy this file into your host repo and
+ * wire it to a 5-minute cron.
+ */
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { exec, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execP = promisify(exec);
+
+// Module-level constants (no env reads here — env is read at construct time)
+const RESTART_THRESHOLD_MINUTES = 30;  // Fallback restart-time window when bootstrap log is missing
+const COOLDOWN_HOURS = 6;              // Re-alert suppression per sessionKey
+const STALE_DAYS = 30;                 // Prune alerted.json entries older than this
+const PRE_RESTART_WINDOW_MS = 5 * 60 * 1000;
+const POST_RESTART_WINDOW_MS = 10 * 60 * 1000;
+
+class MessageSweepDetector {
+    /**
+     * @param {{ execFile?: typeof execFile, runOpenclawSessions?: () => Promise<any[]> }} [deps]
+     *   Optional dependency injection for tests. Production: leave undefined.
+     */
+    constructor(deps = {}) {
+        // Constructor-time env reads (C2): tests can mutate process.env per construction
+        const ownerEnv = process.env.OPENCLAW_OWNER_IDS ?? '';
+        this.OWNER_IDS = ownerEnv.split(',').map(s => s.trim()).filter(Boolean);
+        this.TELEGRAM_GROUP_ID = process.env.OPENCLAW_TELEGRAM_GROUP ?? '';
+        this.ALERT_TOPIC = process.env.OPENCLAW_ALERT_TOPIC ?? '';
+        this.AGGRESSIVE = process.env.OPENCLAW_RESTART_SWEEP_AGGRESSIVE === '1';
+
+        const gbrainHome = process.env.GBRAIN_HOME ?? path.join(os.homedir(), '.gbrain');
+        this.STATE_DIR = path.join(gbrainHome, 'integrations', 'restart-sweep');
+        this.LOG_PATH = path.join(this.STATE_DIR, 'sweep.log.jsonl');
+        this.ALERTED_PATH = path.join(this.STATE_DIR, 'alerted.json');
+        this.BOOTSTRAP_LOG = process.env.OPENCLAW_BOOTSTRAP_LOG ?? '/tmp/bootstrap-services.log';
+
+        // DI hooks (default to real implementations)
+        this._execFile = deps.execFile ?? execFile;
+        this._runOpenclawSessions = deps.runOpenclawSessions ?? null;
+
+        this.sessions = null;
+        this.restartTime = null;
+        this.alertMode = this.determineAlertMode();
+        this.alerted = new Map();  // populated in run() / loadAlerted()
+    }
+
+    determineAlertMode() {
+        if (this.TELEGRAM_GROUP_ID && this.ALERT_TOPIC) return 'telegram';
+        if (this.TELEGRAM_GROUP_ID) return 'telegram_stdout';
+        return 'stdout';
+    }
+
+    async run() {
+        try {
+            console.log('🔍 Starting restart message sweep detection...');
+
+            if (this.OWNER_IDS.length === 0) {
+                console.warn('⚠️  No OPENCLAW_OWNER_IDS configured. Set this environment variable.');
+            }
+            if (!this.TELEGRAM_GROUP_ID) {
+                console.warn('⚠️  No OPENCLAW_TELEGRAM_GROUP configured. Alerts will only go to stdout.');
+            }
+
+            fs.mkdirSync(this.STATE_DIR, { recursive: true });
+            this.alerted = await this.loadAlerted();
+
+            this.restartTime = await this.getLastRestartTime();
+            console.log(`📅 Last restart detected at: ${new Date(this.restartTime).toISOString()}`);
+
+            this.sessions = await this.getSessionState();
+            console.log(`📊 Found ${this.sessions.length} total sessions`);
+
+            const telegramSessions = this.filterTelegramSessions(this.sessions);
+            console.log(`📱 Found ${telegramSessions.length} Telegram sessions`);
+
+            const droppedMessages = await this.detectDroppedMessages(telegramSessions);
+            const newDrops = droppedMessages.filter(m => !this.isInCooldown(m.sessionKey));
+            const suppressedCount = droppedMessages.length - newDrops.length;
+
+            if (newDrops.length > 0) {
+                const tail = suppressedCount > 0 ? ` (${suppressedCount} suppressed by cooldown)` : '';
+                console.log(`⚠️  Found ${newDrops.length} potentially dropped message(s)${tail}`);
+                await this.recordAndAlert(newDrops);
+            } else if (suppressedCount > 0) {
+                console.log(`✅ All ${suppressedCount} candidate(s) suppressed by cooldown`);
+            } else {
+                console.log('✅ No dropped messages detected');
+            }
+
+            await this.logResults(droppedMessages);
+
+        } catch (error) {
+            console.error('❌ Error in message sweep:', error);
+            await this.logError(error);
+        }
+    }
+
+    async getLastRestartTime() {
+        try {
+            const logContent = await fsp.readFile(this.BOOTSTRAP_LOG, 'utf8');
+            const gatewayLines = logContent.split('\n')
+                .filter(line => line.includes('Gateway token synced') || line.includes('✅ OpenClaw gateway'))
+                .reverse();
+            if (gatewayLines.length > 0) {
+                const match = gatewayLines[0].match(/^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})/);
+                if (match) {
+                    return new Date(match[1] + ' UTC').getTime();
+                }
+            }
+            return Date.now() - (RESTART_THRESHOLD_MINUTES * 60 * 1000);
+        } catch (error) {
+            console.warn('⚠️  Could not determine restart time from logs, using fallback');
+            return Date.now() - (RESTART_THRESHOLD_MINUTES * 60 * 1000);
+        }
+    }
+
+    async getSessionState() {
+        if (this._runOpenclawSessions) {
+            return await this._runOpenclawSessions();
+        }
+        try {
+            const { stdout } = await execP('openclaw sessions --json');
+            const sessionData = JSON.parse(stdout);
+            return sessionData.sessions || [];
+        } catch (error) {
+            console.error('❌ Failed to get session state:', error);
+            throw error;
+        }
+    }
+
+    filterTelegramSessions(sessions) {
+        if (!this.TELEGRAM_GROUP_ID) return [];
+        return sessions.filter(session => {
+            return session.key &&
+                   session.key.includes('telegram:group:' + this.TELEGRAM_GROUP_ID) &&
+                   session.kind === 'group';
+        });
+    }
+
+    async detectDroppedMessages(telegramSessions) {
+        const droppedMessages = [];
+        const recentRestartWindow = this.restartTime - PRE_RESTART_WINDOW_MS;
+        const afterRestartWindow = this.restartTime + POST_RESTART_WINDOW_MS;
+
+        for (const session of telegramSessions) {
+            try {
+                const sessionUpdated = session.updatedAt;
+
+                // Primary: aborted last run is the strong signal
+                if (session.abortedLastRun) {
+                    const topic = this._extractTopic(session.key);
+                    droppedMessages.push({
+                        sessionKey: session.key,
+                        topic,
+                        lastUpdate: new Date(sessionUpdated).toISOString(),
+                        sessionId: session.sessionId,
+                        abortedLastRun: true,
+                        reason: 'Session aborted on last run',
+                    });
+                    continue;
+                }
+
+                // Secondary: timing-based gap detection — opt-in only (false-positive prone)
+                if (!this.AGGRESSIVE) continue;
+
+                if (sessionUpdated >= recentRestartWindow &&
+                    sessionUpdated < this.restartTime &&
+                    Date.now() > afterRestartWindow) {
+                    const topic = this._extractTopic(session.key);
+                    droppedMessages.push({
+                        sessionKey: session.key,
+                        topic,
+                        lastUpdate: new Date(sessionUpdated).toISOString(),
+                        timeSinceUpdate: Math.floor((Date.now() - sessionUpdated) / 1000 / 60),
+                        sessionId: session.sessionId,
+                        suspiciousGap: true,
+                        reason: 'Active before restart, silent after',
+                    });
+                }
+            } catch (error) {
+                console.warn(`⚠️  Error analyzing session ${session.key}:`, error);
+            }
+        }
+        return droppedMessages;
+    }
+
+    _extractTopic(sessionKey) {
+        const m = sessionKey?.match(/:topic:(\d+)/);
+        return m ? m[1] : 'unknown';
+    }
+
+    /**
+     * Cooldown layer (C1): suppresses re-alerts on the same sessionKey
+     * for COOLDOWN_HOURS, regardless of whether the synthesized
+     * restartTime matches. Cooldown wins when the bootstrap log is
+     * missing and restartTime is unstable.
+     */
+    isInCooldown(sessionKey) {
+        const entry = this.alerted.get(sessionKey);
+        if (!entry || !entry.lastAlertedAt) return false;
+        const ageMs = Date.now() - new Date(entry.lastAlertedAt).getTime();
+        return ageMs < COOLDOWN_HOURS * 60 * 60 * 1000;
+    }
+
+    async loadAlerted() {
+        try {
+            const content = await fsp.readFile(this.ALERTED_PATH, 'utf8');
+            const parsed = JSON.parse(content);
+            const map = new Map();
+            const cutoffMs = Date.now() - STALE_DAYS * 24 * 60 * 60 * 1000;
+            for (const [key, entry] of Object.entries(parsed || {})) {
+                if (entry && entry.lastAlertedAt) {
+                    const ts = new Date(entry.lastAlertedAt).getTime();
+                    if (Number.isFinite(ts) && ts >= cutoffMs) {
+                        map.set(key, entry);
+                    }
+                }
+            }
+            return map;
+        } catch (err) {
+            if (err && err.code === 'ENOENT') return new Map();
+            console.warn(`⚠️  Failed to load ${this.ALERTED_PATH}: ${err && err.message}; starting with empty state`);
+            return new Map();
+        }
+    }
+
+    async saveAlerted() {
+        const obj = Object.fromEntries(this.alerted);
+        const json = JSON.stringify(obj, null, 2);
+        const tmp = this.ALERTED_PATH + '.tmp';
+        // Atomic on POSIX: write tmp, then rename. Note: this prevents
+        // file corruption only — concurrent cron runs can still both
+        // read old state, both decide to alert, both rename. Given
+        // 5-min cadence and 2-5s runtime, overlap is rare and a
+        // duplicate alert is preferable to a missed one.
+        await fsp.writeFile(tmp, json);
+        await fsp.rename(tmp, this.ALERTED_PATH);
+    }
+
+    async recordAndAlert(droppedMessages) {
+        let alertSent = false;
+        try {
+            await this.alertOnDroppedMessages(droppedMessages);
+            alertSent = true;
+        } catch (err) {
+            console.error('❌ Failed to send alert (will retry next cycle):', err && err.message);
+        }
+        if (!alertSent) return;
+
+        const nowIso = new Date().toISOString();
+        const restartIso = new Date(this.restartTime).toISOString();
+        for (const msg of droppedMessages) {
+            this.alerted.set(msg.sessionKey, {
+                lastAlertedAt: nowIso,
+                restartTime: restartIso,
+            });
+        }
+        try {
+            await this.saveAlerted();
+        } catch (err) {
+            console.warn('⚠️  Failed to save alerted state:', err && err.message);
+        }
+    }
+
+    async alertOnDroppedMessages(droppedMessages) {
+        let alertText = `⚠️ Found ${droppedMessages.length} unprocessed message(s) after restart:\n\n`;
+        for (const msg of droppedMessages.slice(0, 10)) {
+            alertText += `• Topic ${msg.topic}: ${msg.reason} (last update: ${msg.lastUpdate})\n`;
+            if (msg.timeSinceUpdate) {
+                alertText += `  ${msg.timeSinceUpdate} minutes ago\n`;
+            }
+        }
+        if (droppedMessages.length > 10) {
+            alertText += `\n... and ${droppedMessages.length - 10} more`;
+        }
+
+        switch (this.alertMode) {
+            case 'telegram':
+                await this.sendTelegramAlert(alertText);
+                break;
+            case 'telegram_stdout':
+                console.log('📢 Would send Telegram alert, but no topic configured:');
+                console.log(alertText);
+                break;
+            default:
+                console.log('📢 Alert:');
+                console.log(alertText);
+        }
+    }
+
+    async sendTelegramAlert(alertText) {
+        // execFile (not exec): argv array, no shell interpretation,
+        // shell metachars in env vars cannot inject commands.
+        const argv = [
+            'message', 'send',
+            '--channel', 'telegram',
+            '--target', this.TELEGRAM_GROUP_ID,
+            '--thread-id', this.ALERT_TOPIC,
+            '--message', alertText,
+        ];
+        await new Promise((resolve, reject) => {
+            this._execFile('openclaw', argv, (err, _stdout, stderr) => {
+                if (err) {
+                    err.stderr = stderr;
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+        console.log('📢 Alert sent to Telegram');
+    }
+
+    async logResults(droppedMessages) {
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            restartTime: new Date(this.restartTime).toISOString(),
+            droppedMessageCount: droppedMessages.length,
+            droppedMessages,
+        };
+        try {
+            await fsp.appendFile(this.LOG_PATH, JSON.stringify(logEntry) + '\n');
+        } catch (error) {
+            console.warn('⚠️  Failed to write log file:', error && error.message);
+        }
+    }
+
+    async logError(error) {
+        const errorEntry = {
+            timestamp: new Date().toISOString(),
+            error: error && error.message,
+            stack: error && error.stack,
+        };
+        try {
+            await fsp.appendFile(this.LOG_PATH, 'ERROR: ' + JSON.stringify(errorEntry) + '\n');
+        } catch (logError) {
+            console.error('Failed to log error:', logError && logError.message);
+        }
+    }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const detector = new MessageSweepDetector();
+    detector.run().catch(console.error);
+}
+
+export default MessageSweepDetector;
+```
+
+## Step 4: Dry-run
+
+Run the script once manually with the env loaded, before wiring cron:
+
+```bash
+set -a; source ~/openclaw/.env; set +a
+node ~/openclaw/scripts/restart-sweep.mjs
+```
+
+Expected output (no drops):
+
+```
+🔍 Starting restart message sweep detection...
+📅 Last restart detected at: 2026-05-06T12:53:45.000Z
+📊 Found 48 total sessions
+📱 Found 39 Telegram sessions
+✅ No dropped messages detected
+```
+
+If you want to see the alert path, manually edit a session in OpenClaw
+to set `abortedLastRun: true` and re-run. After the alert fires, check
+`~/.gbrain/integrations/restart-sweep/alerted.json` — the sessionKey
+should be there with a `lastAlertedAt` timestamp. Re-running within 6
+hours suppresses the alert.
+
+## Step 5: Wire 5-minute cron
+
+Cron does NOT inherit your shell environment. `openclaw` and `node` may
+not be on cron's stripped PATH. `.env` files don't auto-load. Use the
+wrapper-script pattern below to handle both.
+
+Create `~/openclaw/scripts/restart-sweep-wrapper.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+set -a
+source ~/openclaw/.env
+set +a
+exec /usr/local/bin/node ~/openclaw/scripts/restart-sweep.mjs
+```
+
+```bash
+chmod +x ~/openclaw/scripts/restart-sweep-wrapper.sh
+```
+
+Adjust `/usr/local/bin/node` to wherever your `node` actually lives
+(`which node` to find it). Same for `openclaw` if the wrapper needs to
+add it to PATH explicitly:
+
+```bash
+export PATH=/usr/local/bin:/usr/bin:/bin:$PATH
+```
+
+Add to crontab via `crontab -e`:
+
+```cron
+PATH=/usr/local/bin:/usr/bin:/bin
+*/5 * * * * /bin/bash ~/openclaw/scripts/restart-sweep-wrapper.sh >> ~/.gbrain/integrations/restart-sweep/cron.log 2>&1
+```
+
+Verify with `crontab -l`. Wait 5 minutes, then check the cron log to
+confirm it ran:
+
+```bash
+tail -20 ~/.gbrain/integrations/restart-sweep/cron.log
+```
+
+## Step 6: Verification
+
+1. `gbrain integrations doctor restart-sweep` — should pass all three
+   health checks
+2. `~/.gbrain/integrations/restart-sweep/sweep.log.jsonl` exists and
+   gets a new entry every 5 minutes
+3. `~/.gbrain/integrations/restart-sweep/cron.log` shows successful
+   invocations (no PATH errors, no `command not found`)
+4. After a real OpenClaw restart with a stuck session, the Telegram
+   alert fires once, then the cooldown layer suppresses repeats for 6h
+
+## Tuning
+
+`OPENCLAW_RESTART_SWEEP_AGGRESSIVE=1` — enables the secondary
+"active-before-restart, silent-after" heuristic. Off by default because
+during normal quiet periods (overnight, weekends) it false-positives.
+Enable if you want maximum sensitivity AND you've established that your
+group is consistently active.
+
+The cooldown threshold (6 hours) is a constant in the script. Edit
+`COOLDOWN_HOURS` if you need different behavior — e.g. 24 hours if your
+group's normal cadence is daily.
+
+## Troubleshooting
+
+### Alerts firing repeatedly on the same session
+
+Check `~/.gbrain/integrations/restart-sweep/alerted.json`. If the
+sessionKey is missing or `lastAlertedAt` is recent, the cooldown should
+suppress. If it's not suppressing:
+
+- The state file may not be writable. Check `ls -ld
+  ~/.gbrain/integrations/restart-sweep/`.
+- `GBRAIN_HOME` may be set to a different path under cron than under
+  your shell. Check the wrapper script's env loading.
+- The script's `STATE_DIR` resolution prints in stderr if mkdir fails.
+  Check the cron log.
+
+### Telegram alert fails silently
+
+The script logs `❌ Failed to send alert (will retry next cycle)` to
+stderr when `openclaw message send` returns non-zero. Common causes:
+
+- `openclaw` not on cron's PATH (use absolute path in the wrapper)
+- Telegram bot token expired or rate-limited
+- Wrong group/topic ID (try `openclaw message send --channel telegram
+  --target $OPENCLAW_TELEGRAM_GROUP --message test` manually)
+
+When the send fails, state is NOT updated, so next cycle retries.
+
+### Bootstrap log missing
+
+If `/tmp/bootstrap-services.log` (or `$OPENCLAW_BOOTSTRAP_LOG`) doesn't
+exist, the script falls back to `now() - 30 minutes` for restartTime.
+The cooldown layer keeps this from spamming. If you want a stable
+restart anchor, point `OPENCLAW_BOOTSTRAP_LOG` at OpenClaw's actual
+startup log (whatever your deployment uses).
+
+### Cron environment
+
+The wrapper script in Step 5 handles 80% of cron-day-one failures, but
+two more knobs:
+
+- **Locale:** if your script ever interpolates user-provided text into
+  log lines, set `LANG=en_US.UTF-8` in the cron entry to avoid mojibake.
+- **Working directory:** cron starts in `$HOME` by default. The script
+  uses absolute paths everywhere, so this shouldn't matter, but if you
+  ever add a relative-path dependency, `cd ~/openclaw` in the wrapper.
+
+## Future upgrade path
+
+This recipe is the v1 shape: a script copied into the host repo and
+wired to cron. The v2 shape is a plugin Minion handler registered in
+the OpenClaw repo against `gbrain/minions` (see
+`docs/guides/plugin-handlers.md`). Plugin-handler advantages:
+
+- Built-in queue idempotency (no cooldown layer needed)
+- Submit via `gbrain jobs submit restart-sweep` from any cron / agent /
+  manual trigger
+- Centralized retry / backoff / lock management
+- One less host script to maintain
+
+When this becomes the right tradeoff (multiple deployments, multiple
+cron schedules, or just enough complexity to justify the move), promote
+to the plugin-handler shape and deprecate this recipe.

scripts/build-llms.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env bun
+/**
+ * build-llms — generate llms.txt + llms-full.txt from scripts/llms-config.ts.
+ *
+ * Run: `bun run build:llms` (or `bun run scripts/build-llms.ts`).
+ *
+ * Outputs:
+ *   - llms.txt       — llmstxt.org-spec index (H1 / blockquote / H2 sections).
+ *   - llms-full.txt  — concatenated full content of non-optional entries.
+ *
+ * Deterministic: no timestamps, sorted within categories by config order.
+ * Warns (does not fail) if llms-full.txt exceeds FULL_SIZE_BUDGET. CI catches
+ * drift via test/build-llms.test.ts.
+ *
+ * Fork override: set LLMS_REPO_BASE to regenerate with a different URL base.
+ */
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  FULL_SIZE_BUDGET,
+  INLINE_TIPS,
+  PROJECT,
+  SECTIONS,
+  type DocEntry,
+  type DocSection,
+} from "./llms-config";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function urlFor(entry: DocEntry): string {
+  return `${PROJECT.rawBaseUrl}/${entry.path}`;
+}
+
+function isDirectoryPath(path: string): boolean {
+  return path.endsWith("/");
+}
+
+function renderLlmsTxt(): string {
+  const lines: string[] = [];
+  lines.push(`# ${PROJECT.name}`);
+  lines.push("");
+  lines.push(`> ${PROJECT.summary}`);
+  lines.push("");
+  lines.push(`Repo: ${PROJECT.repoUrl}`);
+  lines.push("");
+
+  for (const section of SECTIONS) {
+    lines.push(`## ${section.heading}`);
+    lines.push("");
+    for (const entry of section.entries) {
+      lines.push(
+        `- [${entry.title}](${urlFor(entry)}): ${entry.description}`,
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push("## Operational tips");
+  lines.push("");
+  for (const tip of INLINE_TIPS) {
+    lines.push(`- ${tip}`);
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function renderLlmsFullTxt(): { content: string; sizes: Array<{ path: string; bytes: number }> } {
+  const lines: string[] = [];
+  const sizes: Array<{ path: string; bytes: number }> = [];
+
+  lines.push(`# ${PROJECT.name} — Full Context`);
+  lines.push("");
+  lines.push(`> ${PROJECT.summary}`);
+  lines.push("");
+  lines.push(
+    `This file concatenates core GBrain documentation for single-fetch ingestion.`,
+  );
+  lines.push(
+    `For the link-only index, see \`llms.txt\`. Source of truth: ${PROJECT.repoUrl}.`,
+  );
+  lines.push("");
+
+  for (const section of SECTIONS) {
+    if (section.optional) continue;
+    lines.push(`# ${section.heading}`);
+    lines.push("");
+    for (const entry of section.entries) {
+      if (entry.includeInFull === false) continue;
+      if (isDirectoryPath(entry.path)) continue;
+
+      const absPath = join(repoRoot, entry.path);
+      if (!existsSync(absPath)) {
+        // build-llms won't silently skip — surface the problem. Test case 1
+        // catches this too, but fail fast for manual runs.
+        throw new Error(
+          `llms-config references missing file: ${entry.path}`,
+        );
+      }
+
+      const body = readFileSync(absPath, "utf8");
+      const bytes = Buffer.byteLength(body, "utf8");
+      sizes.push({ path: entry.path, bytes });
+
+      lines.push(`## ${entry.path}`);
+      lines.push("");
+      lines.push(`Source: ${urlFor(entry)}`);
+      lines.push("");
+      lines.push(body.trimEnd());
+      lines.push("");
+      lines.push("---");
+      lines.push("");
+    }
+  }
+
+  return { content: lines.join("\n"), sizes };
+}
+
+function validateConfig(): void {
+  for (const section of SECTIONS) {
+    for (const entry of section.entries) {
+      const absPath = join(repoRoot, entry.path);
+      if (!existsSync(absPath)) {
+        throw new Error(
+          `llms-config references missing path: ${entry.path}`,
+        );
+      }
+      const st = statSync(absPath);
+      if (isDirectoryPath(entry.path) && !st.isDirectory()) {
+        throw new Error(
+          `llms-config path ends with '/' but is a file: ${entry.path}`,
+        );
+      }
+      if (!isDirectoryPath(entry.path) && !st.isFile()) {
+        throw new Error(
+          `llms-config path is a directory but missing trailing '/': ${entry.path}`,
+        );
+      }
+    }
+  }
+}
+
+export function buildLlmsFiles(): {
+  llmsTxt: string;
+  llmsFullTxt: string;
+  sizes: Array<{ path: string; bytes: number }>;
+} {
+  validateConfig();
+  const llmsTxt = renderLlmsTxt();
+  const { content: llmsFullTxt, sizes } = renderLlmsFullTxt();
+  return { llmsTxt, llmsFullTxt, sizes };
+}
+
+function main(): void {
+  const { llmsTxt, llmsFullTxt, sizes } = buildLlmsFiles();
+
+  const llmsPath = join(repoRoot, "llms.txt");
+  const llmsFullPath = join(repoRoot, "llms-full.txt");
+
+  writeFileSync(llmsPath, llmsTxt);
+  writeFileSync(llmsFullPath, llmsFullTxt);
+
+  const fullBytes = Buffer.byteLength(llmsFullTxt, "utf8");
+  console.log(`wrote ${llmsPath} (${Buffer.byteLength(llmsTxt, "utf8")} bytes)`);
+  console.log(`wrote ${llmsFullPath} (${fullBytes} bytes)`);
+
+  if (fullBytes > FULL_SIZE_BUDGET) {
+    console.warn("");
+    console.warn(
+      `WARN: llms-full.txt (${fullBytes} bytes) exceeds FULL_SIZE_BUDGET (${FULL_SIZE_BUDGET} bytes).`,
+    );
+    console.warn(
+      "Add `includeInFull: false` to the biggest entries in scripts/llms-config.ts:",
+    );
+    const sorted = [...sizes].sort((a, b) => b.bytes - a.bytes);
+    for (const entry of sorted.slice(0, 5)) {
+      console.warn(`  ${entry.bytes} bytes  ${entry.path}`);
+    }
+  }
+}
+
+const isMainModule = fileURLToPath(import.meta.url) === process.argv[1];
+if (isMainModule) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}

scripts/build-pglite-snapshot.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+// scripts/build-pglite-snapshot.ts
+//
+// Tier 3 fast-restore: boot a fresh PGLite, run the full initSchema (forward
+// bootstrap + PGLITE_SCHEMA_SQL + every migration), dump the post-init state
+// to a tar fixture. Test files that read GBRAIN_PGLITE_SNAPSHOT can skip the
+// 1-3 seconds of cold init and load the post-schema state directly.
+//
+// Output: test/fixtures/pglite-snapshot.tar (binary, gitignored)
+//         test/fixtures/pglite-snapshot.version (hex SHA256 of MIGRATIONS SQL)
+//
+// The version file lets the engine detect snapshot staleness — if the tar's
+// recorded version doesn't match the current MIGRATIONS hash, the engine
+// ignores the snapshot and runs a normal initSchema.
+//
+// Run: bun run scripts/build-pglite-snapshot.ts
+//      (or: bun run build:pglite-snapshot)
+//
+// Re-run whenever you touch src/core/migrate.ts or src/schema.sql.
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import * as crypto from "node:crypto";
+
+import { PGLiteEngine, computeSnapshotSchemaHash } from "../src/core/pglite-engine.ts";
+import { MIGRATIONS } from "../src/core/migrate.ts";
+import { PGLITE_SCHEMA_SQL } from "../src/core/pglite-schema.ts";
+
+function computeSchemaHash(): string {
+  return computeSnapshotSchemaHash(MIGRATIONS, PGLITE_SCHEMA_SQL, crypto);
+}
+
+async function main() {
+  const fixturePath = "test/fixtures/pglite-snapshot.tar";
+  const versionPath = "test/fixtures/pglite-snapshot.version";
+  mkdirSync(dirname(fixturePath), { recursive: true });
+
+  const schemaHash = computeSchemaHash();
+  console.log(`[build-pglite-snapshot] schema hash: ${schemaHash.slice(0, 16)}...`);
+  console.log(`[build-pglite-snapshot] booting PGLite (in-memory)...`);
+  const engine = new PGLiteEngine();
+
+  // Bypass the env-aware short-circuit: we WANT a real init here.
+  delete process.env.GBRAIN_PGLITE_SNAPSHOT;
+
+  await engine.connect({});
+  console.log(`[build-pglite-snapshot] running initSchema (forward bootstrap + ${MIGRATIONS.length} migrations)...`);
+  const t0 = Date.now();
+  await engine.initSchema();
+  console.log(`[build-pglite-snapshot] initSchema completed in ${Date.now() - t0}ms`);
+
+  console.log(`[build-pglite-snapshot] dumping data dir...`);
+  const dump = await engine.db.dumpDataDir("none");
+  const buffer = Buffer.from(await dump.arrayBuffer());
+
+  writeFileSync(fixturePath, buffer);
+  writeFileSync(versionPath, schemaHash + "\n");
+  await engine.disconnect();
+
+  console.log(`[build-pglite-snapshot] wrote ${fixturePath} (${buffer.length} bytes)`);
+  console.log(`[build-pglite-snapshot] wrote ${versionPath}`);
+}
+
+await main();

scripts/check-admin-build.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# CI gate: admin React app must compile.
+#
+# Catches missing-symbol bugs (e.g., calling loadApiKeys() when only
+# loadAgents is defined) before they reach E2E. Codex flagged this gap
+# during the PR #586 review pass — five Claude review passes missed
+# the loadApiKeys reference because the bash test pipeline doesn't run
+# Vite builds. This script runs `bun install` in admin/ to ensure
+# react/vite/etc. are present, then runs Vite's build which performs
+# TypeScript type-check + bundle.
+#
+# Skip with GBRAIN_SKIP_ADMIN_BUILD=1 (e.g., for fast inner-loop test
+# runs that don't touch admin/src). Production CI must NOT skip.
+set -euo pipefail
+
+if [ "${GBRAIN_SKIP_ADMIN_BUILD:-0}" = "1" ]; then
+  echo "[check:admin-build] GBRAIN_SKIP_ADMIN_BUILD=1, skipping"
+  exit 0
+fi
+
+cd "$(dirname "$0")/.."
+
+if [ ! -d admin ]; then
+  echo "[check:admin-build] no admin/ directory, skipping"
+  exit 0
+fi
+
+cd admin
+
+# Idempotent install — bun is fast enough on no-op (~50ms).
+bun install --silent >/dev/null 2>&1 || bun install
+
+# Build runs `tsc -b && vite build`. Output to admin/dist/. Exit non-zero
+# on TS error, missing symbol, or Vite bundling error.
+bun run build

scripts/check-admin-scope-drift.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Check that admin/src/lib/scope-constants.ts ALLOWED_SCOPES_LIST matches
+# src/core/scope.ts ALLOWED_SCOPES_LIST. The admin SPA's tsconfig include
+# scopes to admin/src/ so we can't import the source list directly; instead
+# this script extracts both lists and diffs them.
+#
+# Wired into `bun run verify` and `bun run check:all`.
+#
+# Exits 0 on match, 1 on drift, 2 on internal error (file missing, parse fail).
+#
+# Usage:  scripts/check-admin-scope-drift.sh
+set -euo pipefail
+
+SRC=src/core/scope.ts
+ADMIN=admin/src/lib/scope-constants.ts
+
+[ -f "$SRC" ] || { echo "[check-admin-scope-drift] missing $SRC" >&2; exit 2; }
+[ -f "$ADMIN" ] || { echo "[check-admin-scope-drift] missing $ADMIN" >&2; exit 2; }
+
+# Extract the contents of ALLOWED_SCOPES_LIST = [...] from each file.
+# The list spans multiple lines, terminated by ']'. awk pulls it cleanly.
+extract_list() {
+  awk '
+    /ALLOWED_SCOPES_LIST/ && /\[/ { capture = 1 }
+    capture {
+      print
+      if (/\]/) { capture = 0; exit }
+    }
+  ' "$1"
+}
+
+src_block=$(extract_list "$SRC")
+admin_block=$(extract_list "$ADMIN")
+
+if [ -z "$src_block" ]; then
+  echo "[check-admin-scope-drift] could not find ALLOWED_SCOPES_LIST in $SRC" >&2
+  exit 2
+fi
+if [ -z "$admin_block" ]; then
+  echo "[check-admin-scope-drift] could not find ALLOWED_SCOPES_LIST in $ADMIN" >&2
+  exit 2
+fi
+
+# Strip everything that isn't a quoted scope string and emit one per line.
+strip_to_scopes() {
+  printf '%s\n' "$1" \
+    | tr ',' '\n' \
+    | grep -oE "'[a-z_]+'" \
+    | tr -d "'" \
+    | sort -u
+}
+
+src_scopes=$(strip_to_scopes "$src_block")
+admin_scopes=$(strip_to_scopes "$admin_block")
+
+if [ "$src_scopes" != "$admin_scopes" ]; then
+  echo "[check-admin-scope-drift] DRIFT detected between:" >&2
+  echo "  $SRC" >&2
+  echo "  $ADMIN" >&2
+  echo "" >&2
+  echo "src/core/scope.ts has:" >&2
+  printf '  %s\n' $src_scopes >&2
+  echo "" >&2
+  echo "admin/src/lib/scope-constants.ts has:" >&2
+  printf '  %s\n' $admin_scopes >&2
+  echo "" >&2
+  echo "Update admin/src/lib/scope-constants.ts to match, then 'cd admin && bun run build'." >&2
+  exit 1
+fi
+
+echo "[check-admin-scope-drift] ok: $(echo "$src_scopes" | wc -l | tr -d ' ') scopes match"

scripts/check-cli-executable.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# CI guard: src/cli.ts must be tracked by git in executable mode (100755).
+#
+# Why: bun-link installs symlink to src/cli.ts directly. If the mode bit
+# regresses to 100644, the very first `gbrain --version` invocation fails
+# with `permission denied`. v0.28.5 (cluster C, #683) fixed the original
+# regression; this guard prevents future drift.
+#
+# Wired into `bun run verify`. Fast, no external deps.
+set -e
+
+MODE=$(git ls-files --stage src/cli.ts | awk '{print $1}')
+if [ "$MODE" != "100755" ]; then
+  echo "FAIL: src/cli.ts is tracked at mode $MODE; expected 100755 (executable)."
+  echo ""
+  echo "Fix: chmod +x src/cli.ts && git add --chmod=+x src/cli.ts"
+  echo ""
+  echo "Background: bun-link installs symlink to this file directly. Mode 100644"
+  echo "produces 'permission denied' on first invocation (issue #683)."
+  exit 1
+fi
+
+echo "OK: src/cli.ts is git-tracked as executable (100755)"

scripts/check-exports-count.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# CI guard: the public exports surface never shrinks silently (v0.21.0).
+#
+# Precedent: scripts/check-jsonb-pattern.sh + check-progress-to-stdout.sh
+# are grep-based structural guards wired into `bun run test`. This one
+# counts the entries in package.json "exports" and fails when the count
+# drops below the v0.21.0 baseline (17 entries).
+#
+# Policy (from CLAUDE.md):
+#   "Removing any of these is a breaking change going forward."
+#
+# If you're legitimately removing a public export: bump gbrain's minor
+# version, note the removal in CHANGELOG.md under a "Breaking changes"
+# bullet, then bump EXPECTED_COUNT below. Anything else is a regression.
+#
+# Adding a new export: update EXPECTED_COUNT to match AND extend the
+# EXPECTED_EXPORTS list in test/public-exports.test.ts so the runtime
+# contract test pins the canary symbol.
+
+set -euo pipefail
+
+EXPECTED_COUNT=17
+
+# Count top-level keys in the exports object. `node -e` parses JSON
+# reliably without needing jq (which isn't in every CI environment).
+ACTUAL=$(node -e "
+  const pkg = require('./package.json');
+  console.log(Object.keys(pkg.exports || {}).length);
+")
+
+if [ "$ACTUAL" -lt "$EXPECTED_COUNT" ]; then
+  echo "❌ public-exports guard: package.json exports shrank from $EXPECTED_COUNT to $ACTUAL"
+  echo "   Removing a public export is a breaking change (see CLAUDE.md)."
+  echo "   If intentional: bump gbrain minor version + update EXPECTED_COUNT in"
+  echo "   scripts/check-exports-count.sh and EXPECTED_EXPORTS in"
+  echo "   test/public-exports.test.ts, AND add a CHANGELOG 'Breaking changes' bullet."
+  exit 1
+fi
+
+if [ "$ACTUAL" -gt "$EXPECTED_COUNT" ]; then
+  echo "⚠️  public-exports guard: package.json exports grew from $EXPECTED_COUNT to $ACTUAL"
+  echo "   Additive public API change. Update EXPECTED_COUNT in this script + the"
+  echo "   EXPECTED_EXPORTS list in test/public-exports.test.ts to lock the new"
+  echo "   canary symbols."
+  exit 1
+fi
+
+echo "✓ public-exports guard: $ACTUAL entries (matches baseline $EXPECTED_COUNT)"

scripts/check-jsonb-pattern.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# CI guard: fail if any source file uses the buggy `${JSON.stringify(x)}::jsonb`
+# template-string pattern instead of postgres.js's `sql.json(x)`.
+#
+# This is best-effort static analysis. It catches the common copy-paste form
+# that caused the v0.12.0 silent-data-loss bug (JSONB columns stored as
+# string literals on Postgres while PGLite hid the bug). Multi-line and
+# helper-wrapped variants are NOT caught here — those are covered by
+# test/e2e/postgres-jsonb.test.ts which round-trips actual writes through
+# real Postgres and asserts `frontmatter->>'k'` returns objects, not strings.
+#
+# Usage: scripts/check-jsonb-pattern.sh
+# Exit:  0 when no matches, 1 when matches found.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+# Match the interpolated form: ${JSON.stringify(...)}::jsonb
+# Using grep -P for Perl-compatible regex (lookahead-free pattern is enough here).
+PATTERN='\$\{JSON\.stringify\([^)]*\)\}::jsonb'
+
+if grep -rEn "$PATTERN" src/ 2>/dev/null; then
+  echo
+  echo "ERROR: Found JSON.stringify(...)::jsonb pattern in src/."
+  echo "       postgres.js v3 stringifies again, producing JSONB string literals."
+  echo "       Use sql.json(x) instead. See feedback_postgres_jsonb_double_encode.md."
+  exit 1
+fi
+
+echo "OK: no JSON.stringify(x)::jsonb interpolation pattern in src/"
+
+# v0.13.1 #219: guard against max_stalled DEFAULT 1 regressing in any schema
+# source file. DEFAULT 1 dead-lettered any SIGKILL'd job on first stall, making
+# the "10/10 rescued" claim false for out-of-the-box users. Default is 5 now.
+MAX_STALLED_PATTERN='max_stalled\s+INTEGER\s+NOT\s+NULL\s+DEFAULT\s+1\b'
+
+if grep -rEn "$MAX_STALLED_PATTERN" src/schema.sql src/core/migrate.ts src/core/pglite-schema.ts src/core/schema-embedded.ts 2>/dev/null; then
+  echo
+  echo "ERROR: max_stalled DEFAULT 1 reintroduced in schema."
+  echo "       Must be DEFAULT 5 to preserve SIGKILL-rescue guarantee. See #219."
+  exit 1
+fi
+
+echo "OK: max_stalled defaults are 5 in all schema sources"

scripts/check-no-legacy-getconnection.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# CI guard against silent singleton reuse in connected-gbrains code paths.
+#
+# Codex finding #7 (plan review 2026-04-22): the module singleton in
+# src/core/db.ts is shared across the process. With multi-brain routing,
+# any `db.getConnection()` call in an op-dispatch code path means that op
+# silently targets whichever brain connected to the singleton first,
+# regardless of ctx.brainId / ctx.engine. This is exactly the bug Codex
+# #1 flagged in postgres-engine.ts internals.
+#
+# This script fails the build when NEW `db.getConnection()` calls appear
+# in src/core/operations.ts (the per-op handler surface) or in any new
+# `src/commands/*.ts` file. Existing legitimate callers are grandfathered
+# via an explicit allowlist — cleanups land in PR 1.
+#
+# When you hit this guard: instead of `db.getConnection()` or `db.connect(...)`,
+# use `ctx.engine` from the passed-in OperationContext. See
+# src/core/brain-registry.ts for how ctx.engine gets populated per-call.
+#
+# Run manually:  bash scripts/check-no-legacy-getconnection.sh
+# Wired into CI: `bun test` (via package.json scripts.test)
+
+set -euo pipefail
+
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$ROOT"
+
+# Files that are allowed to touch the singleton today. Every other file
+# under src/core or src/commands is forbidden. This list shrinks in PR 1.
+ALLOWED=(
+  "src/core/db.ts"                      # the singleton's definition
+  "src/core/postgres-engine.ts"         # calls db.connect + fallback in sql getter — PR 1 removes the fallback
+  "src/commands/init.ts"                # first-time setup path, no engine yet
+  "src/commands/doctor.ts"              # PR 1 refactors to accept engine
+  "src/commands/files.ts"               # PR 1 refactors to accept engine
+  "src/commands/repair-jsonb.ts"        # PR 1 refactors
+  "src/commands/serve-http.ts"          # PR 1 threads engine through the OAuth dispatch path
+  "src/commands/integrity.ts"           # v0.22.8 batch-load fast path + scanIntegrityBatch; PR 1 refactors to accept engine
+  "src/core/operations.ts"              # 3 localOnly ops (file_list/upload/url) move to ctx.engine in PR 1
+)
+
+# Build an argument list for `grep` that excludes allowed files.
+EXCLUDE_ARGS=()
+for file in "${ALLOWED[@]}"; do
+  EXCLUDE_ARGS+=(--exclude="$file")
+done
+
+# Search src/core/ and src/commands/ for db.getConnection or db.connect calls.
+# We look for the `db.` prefix so references to the symbol elsewhere (e.g.
+# the grep guard itself) don't trip the check.
+VIOLATIONS=$(
+  grep -rn "db\.\(getConnection\|connect\)(" \
+    --include="*.ts" \
+    "${EXCLUDE_ARGS[@]}" \
+    src/core src/commands 2>/dev/null \
+    | grep -v -F "src/core/db.ts" \
+    | grep -v "^[^:]*:[0-9]*:[[:space:]]*\(//\|\*\)" \
+    || true
+)
+
+if [ -n "$VIOLATIONS" ]; then
+  # Filter out allowed files from the result (the --exclude only matches basename)
+  FILTERED=$(printf '%s\n' "$VIOLATIONS" | while IFS= read -r line; do
+    path="${line%%:*}"
+    allow=0
+    for ok in "${ALLOWED[@]}"; do
+      if [ "$path" = "$ok" ]; then allow=1; break; fi
+    done
+    if [ "$allow" -eq 0 ]; then printf '%s\n' "$line"; fi
+  done)
+
+  if [ -n "$FILTERED" ]; then
+    echo "ERROR: new direct db.getConnection() / db.connect() call found in multi-brain code path:" >&2
+    echo "" >&2
+    printf '%s\n' "$FILTERED" >&2
+    echo "" >&2
+    echo "Use ctx.engine from the passed-in OperationContext instead." >&2
+    echo "See src/core/brain-registry.ts for the routing model." >&2
+    echo "If this call is legitimate, add its path to the ALLOWED list in" >&2
+    echo "scripts/check-no-legacy-getconnection.sh with a PR 1 cleanup note." >&2
+    exit 1
+  fi
+fi
+
+echo "check-no-legacy-getconnection: ok (no new singleton callers)"

scripts/check-privacy.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+#
+# check-privacy.sh — CLAUDE.md:550 enforcement.
+#
+# CLAUDE.md forbids the private OpenClaw fork name in public artifacts:
+# CHANGELOG.md, README.md, docs/, skills/, PR titles + bodies, commit
+# messages, and comments in checked-in code. This script greps for the
+# banned name in either the staged index (for pre-commit hooks) or the
+# working tree (for CI) and fails loudly if found.
+#
+# The allow-list below whitelists files where the name is legitimate
+# — specifically, this script itself (where we reference the name to
+# describe the rule) and upgrade guides that historically referenced
+# the pre-rename fork name.
+#
+# Usage:
+#   scripts/check-privacy.sh          # scan working tree
+#   scripts/check-privacy.sh --staged # scan git staged index
+#   scripts/check-privacy.sh --help
+#
+# Exit codes:
+#   0  clean
+#   1  banned name found (or --help printed)
+#   2  git / grep not available
+
+set -euo pipefail
+
+BANNED_NAME='wintermute'
+# v0.25.1 (codex T7): additional patterns from wintermute-specific filesystem
+# layouts that would leak private fork context if they slipped through a port.
+# `wintermute_only` already matches via the case-insensitive `wintermute` regex
+# above; this list is for orthogonal patterns.
+BANNED_PATHS=(
+  '/data/brain/'
+  '/data/.openclaw/'
+)
+
+usage() {
+  cat <<EOF
+scripts/check-privacy.sh — scan for the banned OpenClaw fork name.
+
+USAGE:
+  scripts/check-privacy.sh           Scan all tracked files in the working tree.
+  scripts/check-privacy.sh --staged  Scan only files staged for commit.
+  scripts/check-privacy.sh --help    Show this message.
+
+The script greps for '${BANNED_NAME}' (case-insensitive) in:
+  - CHANGELOG.md, README.md
+  - docs/**
+  - skills/**
+  - src/**
+  - test/**
+  - scripts/**
+
+Allow-list (references to the name are permitted):
+  - scripts/check-privacy.sh itself
+  - docs/UPGRADING_DOWNSTREAM_AGENTS.md (historical context for pre-rename upgrades)
+  - .git/** (branch names, commit history — not checked in artifacts)
+
+Exit codes: 0 clean, 1 banned name found, 2 setup error.
+EOF
+}
+
+MODE=working
+for arg in "$@"; do
+  case "$arg" in
+    --staged) MODE=staged ;;
+    --help|-h) usage; exit 1 ;;
+    *)
+      echo "Unknown argument: $arg" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if ! command -v git >/dev/null 2>&1; then
+  echo "check-privacy: git not found" >&2
+  exit 2
+fi
+
+# Build the file list by scanning-mode.
+if [ "$MODE" = staged ]; then
+  FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+else
+  FILES=$(git ls-files 2>/dev/null || true)
+fi
+
+if [ -z "$FILES" ]; then
+  exit 0
+fi
+
+# Allow-list: files in which the banned name is legitimate.
+# Meta-rule docs (define the rule itself), auto-generated LLM indexes,
+# historical upgrade guides, and the test that enforces the rule
+# against recipes/ all reference the banned name by necessity.
+ALLOW_LIST=(
+  'scripts/check-privacy.sh'
+  'CLAUDE.md'
+  'llms-full.txt'
+  'docs/UPGRADING_DOWNSTREAM_AGENTS.md'
+  'test/integrations.test.ts'
+  # v0.25.1 (codex T7) BANNED_PATHS allow-list:
+  # Historical docs, frozen migration files, test fixtures, and env-var
+  # fallbacks where /data/brain/ or /data/.openclaw/ appears legitimately.
+  # New skills/, src/, and tests must NOT slip onto this list — extend the
+  # banned check above instead.
+  'docs/GBRAIN_RECOMMENDED_SCHEMA.md'
+  'docs/GBRAIN_V0.md'
+  'docs/guides/minions-shell-jobs.md'
+  'scripts/smoke-test.sh'
+  'skills/migrations/v0.9.0.md'
+  'skills/migrations/v0.14.0.md'
+  'test/storage-status.test.ts'
+  # CHANGELOG.md documents the rule (the v0.25.1 entry references the
+  # banned literals in describing what's banned). Same exception status
+  # as CLAUDE.md and this script itself: meta-documentation needs to
+  # name the patterns it forbids.
+  'CHANGELOG.md'
+  # skills/migrations/v0.25.1.md is the agent-readable upgrade
+  # walkthrough; it explains the privacy-guard extension to the
+  # operating agent and references the banned literals while doing so.
+  'skills/migrations/v0.25.1.md'
+)
+
+is_allowed() {
+  local f="$1"
+  for a in "${ALLOW_LIST[@]}"; do
+    if [ "$f" = "$a" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+FOUND=0
+while IFS= read -r file; do
+  [ -z "$file" ] && continue
+  [ ! -f "$file" ] && continue
+  if is_allowed "$file"; then
+    continue
+  fi
+  # Case-insensitive grep; only specific extensions + known docs.
+  case "$file" in
+    *.md|*.ts|*.mjs|*.js|*.py|*.sh|*.json|*.yaml|*.yml|*.txt|README*|CHANGELOG*|CLAUDE*|AGENTS*)
+      if grep -in "$BANNED_NAME" "$file" >/dev/null 2>&1; then
+        echo "[check-privacy] BANNED NAME in $file:" >&2
+        grep -in "$BANNED_NAME" "$file" | sed 's|^|  |' >&2
+        FOUND=1
+      fi
+      # Banned wintermute-specific filesystem paths (codex T7).
+      for path in "${BANNED_PATHS[@]}"; do
+        if grep -nF "$path" "$file" >/dev/null 2>&1; then
+          echo "[check-privacy] BANNED PATH '$path' in $file:" >&2
+          grep -nF "$path" "$file" | sed 's|^|  |' >&2
+          FOUND=1
+        fi
+      done
+      ;;
+  esac
+done <<< "$FILES"
+
+if [ "$FOUND" -eq 1 ]; then
+  echo "" >&2
+  echo "The private OpenClaw fork name is banned in public artifacts." >&2
+  echo "CLAUDE.md:550. Replace with 'your OpenClaw', 'OpenClaw reference deployment', or 'openclaw-reference'." >&2
+  exit 1
+fi
+
+exit 0

scripts/check-progress-to-stdout.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# CI guard: fail if any new code emits \r-progress to stdout.
+#
+# Since v0.14.2, bulk-action progress lives on stderr via the shared
+# src/core/progress.ts reporter. \r-rewriting on stdout breaks every
+# piped-output scenario: agents that capture stdout for structured
+# results see progress garbage mixed with the data, and CI logs show
+# a single line per command because everything after the last \r
+# is truncated by the terminal emulator when played back.
+#
+# This script greps for the anti-pattern. Legitimate uses of \r inside
+# string literals (e.g. Windows line-ending normalization, regex
+# patterns) are expected to contain \r without being preceded by
+# `process.stdout.write`. We match the full write-call form only.
+#
+# Usage: scripts/check-progress-to-stdout.sh
+# Exit:  0 when clean, 1 when a banned pattern is found.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+# The banned pattern: process.stdout.write('\r... or process.stdout.write("\r...
+# Greedy quote character class so both quote styles match.
+PATTERN="process\.stdout\.write\([\`'\"]\\\\r"
+
+# Files allowed to use this pattern historically. Empty allowlist — the point
+# of v0.14.2 was to remove every one of them. Add entries only if you really
+# need a \r on stdout (if so, add the rationale as a comment at the call site
+# and list the file here).
+ALLOWLIST=()
+
+matches=""
+if command -v rg >/dev/null 2>&1; then
+  matches="$(rg -n --no-heading "$PATTERN" src/ 2>/dev/null || true)"
+else
+  matches="$(grep -rEn "$PATTERN" src/ 2>/dev/null || true)"
+fi
+
+if [ -n "$matches" ]; then
+  # Filter out allowlisted files.
+  filtered="$matches"
+  for f in "${ALLOWLIST[@]:-}"; do
+    [ -z "$f" ] && continue
+    filtered="$(echo "$filtered" | grep -v "^${f}:" || true)"
+  done
+
+  if [ -n "$filtered" ]; then
+    echo "ERROR: found process.stdout.write('\\r…') pattern(s) in src/:"
+    echo
+    echo "$filtered"
+    echo
+    echo "Bulk-action progress must go through src/core/progress.ts"
+    echo "(writes to stderr, handles TTY vs non-TTY, honors --quiet /"
+    echo " --progress-json / --progress-interval). If you genuinely"
+    echo "need a \\r on stdout, add the file to the ALLOWLIST at the"
+    echo "top of this script and explain why at the call site."
+    exit 1
+  fi
+fi
+
+echo "check-progress-to-stdout: OK (no banned stdout \\r patterns)"

scripts/check-test-isolation.allowlist

@@ -0,0 +1,73 @@
+# v0.26.7 baseline allow-list for scripts/check-test-isolation.sh.
+#
+# Files here violate one or more of the lint rules (env mutation,
+# mock.module, PGLite outside beforeAll, missing afterAll{disconnect}).
+# The lint ships in v0.26.7 and v0.26.8 (env sweep) + v0.26.9 (PGLite
+# sweep) remove entries from this file as each sweep makes the file
+# clean.
+#
+# RULES:
+#  - This list MUST shrink over time. Never add new entries — adding a
+#    new file means accepting cross-file flake risk for that file.
+#  - When you fix a file (apply withEnv, add the canonical PGLite
+#    block, etc.), remove its entry here.
+#  - When you cannot fix a file cleanly (genuinely env-coupled,
+#    or shares state intentionally), rename it to *.serial.test.ts
+#    instead of leaving it allow-listed.
+#
+# Permanent exemption: the test of the lint itself. Its fixture strings
+# (passed verbatim into subprocesses) legitimately match the lint
+# patterns it is testing detection of. The file does NOT mutate
+# process.env at runtime. Permanent — do not remove.
+test/scripts/check-test-isolation.test.ts
+test/autopilot-install.test.ts
+test/bootstrap.test.ts
+test/brain-resolver.test.ts
+test/check-resolvable-cli.test.ts
+test/claw-test-cli.test.ts
+test/code-def-refs.test.ts
+test/core/cycle.test.ts
+test/destructive-guard.test.ts
+test/doctor-minions-check.test.ts
+test/doctor.test.ts
+test/dream.test.ts
+test/embed.test.ts
+test/eval-capture.test.ts
+test/friction-cli.test.ts
+test/friction.test.ts
+test/gbrain-home-isolation.test.ts
+test/helpers/with-env.test.ts
+test/http-transport.test.ts
+test/hybrid-meta.test.ts
+test/init-migrate-only.test.ts
+test/integrations.test.ts
+test/mcp-eval-capture.test.ts
+test/migrate.test.ts
+test/migration-resume.test.ts
+test/migrations-v0_11_0.test.ts
+test/migrations-v0_13_1.test.ts
+test/migrations-v0_14_0.test.ts
+test/migrations-v0_19_0.test.ts
+test/migrations-v0_22_4.test.ts
+test/minions-shell.test.ts
+test/minions.test.ts
+test/mounts-cli.test.ts
+test/multi-source-integration.test.ts
+test/orphans.test.ts
+test/pages-soft-delete.test.ts
+test/preferences.test.ts
+test/reindex-code.test.ts
+test/resolve-prepare.test.ts
+test/resolvers.test.ts
+test/scenarios.test.ts
+test/schema-bootstrap-coverage.test.ts
+test/search-limit.test.ts
+test/seed-pglite.test.ts
+test/skillpack-check.test.ts
+test/source-resolver.test.ts
+test/storage-sync.test.ts
+test/subagent-audit.test.ts
+test/supervisor.test.ts
+test/sync-failures.test.ts
+test/sync-parallel.test.ts
+test/transcription.test.ts

scripts/check-test-isolation.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# CI guard: fail if any non-serial unit test file violates intra-process
+# isolation rules. The v0.26.4 parallel runner loads multiple test files
+# into one bun process per shard; module-level state (env vars, PGLite
+# engines, mock.module overrides) leaks across files in that process and
+# silently flakes other tests.
+#
+# Rules enforced (non-serial unit test files only):
+#  R1: no `process.env.X = ...`, `process.env['X'] = ...`,
+#      `delete process.env.X`, `Object.assign(process.env, ...)`,
+#      `Reflect.set(process.env, ...)` mutations. Use withEnv() helper or
+#      rename the file to `*.serial.test.ts`.
+#  R2: no `mock.module(...)` anywhere. Top-level module mocks affect every
+#      other file in the same shard process. Rename to `*.serial.test.ts`.
+#  R3: `new PGLiteEngine(` may only appear within ~50 lines following a
+#      `beforeAll(` line. Engines created at module scope (or in describe
+#      bodies) leak across files in the shard process.
+#  R4: any file that creates `new PGLiteEngine(` must call `.disconnect(`
+#      inside an `afterAll(` block. Without disconnect, engines leak across
+#      file boundaries within a shard process.
+#
+# Scope:
+#  - Recursively scans `test/**/*.test.ts`.
+#  - Skips `*.serial.test.ts` entirely (the quarantine escape hatch).
+#  - Skips `test/e2e/**` (E2E runs sequentially in its own runner; not in
+#    the parallel pool).
+#
+# Allow-list:
+#  Files in `scripts/check-test-isolation.allowlist` (one filename per
+#  line, # comments allowed) are skipped. This exists because v0.26.7
+#  ships the lint as a foundation; v0.26.8 (env sweep) and v0.26.9
+#  (PGLite sweep) remove entries as files get fixed. New files MUST NOT
+#  be added — the allow-list shrinks over time, never grows.
+#
+# Usage: scripts/check-test-isolation.sh [TARGET_DIR]
+# Exit:  0 when clean, 1 when un-allow-listed violations found.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+TARGET_DIR="${1:-test}"
+ALLOWLIST_FILE="$ROOT/scripts/check-test-isolation.allowlist"
+
+# Read allowlist (one filename per line, # comments allowed). Empty file
+# is fine — every violation will fail.
+ALLOWLIST=""
+if [ -f "$ALLOWLIST_FILE" ]; then
+  ALLOWLIST="$(grep -v '^[[:space:]]*#' "$ALLOWLIST_FILE" | grep -v '^[[:space:]]*$' || true)"
+fi
+
+is_allowlisted() {
+  local f="$1"
+  [ -z "$ALLOWLIST" ] && return 1
+  echo "$ALLOWLIST" | grep -qxF "$f"
+}
+
+# Find non-serial unit test files (excluding test/e2e). Portable across
+# bash 3.2 (macOS default) and bash 4+; no mapfile.
+FILE_LIST="$(find "$TARGET_DIR" -name '*.test.ts' \
+  -not -name '*.serial.test.ts' \
+  -not -path "*/e2e/*" \
+  -type f 2>/dev/null | sort)"
+
+violations=0
+file_count=0
+
+emit_violation() {
+  local f="$1" rule="$2" detail="$3" lines="$4"
+  if is_allowlisted "$f"; then
+    return
+  fi
+  echo "ERROR: $f"
+  echo "       rule $rule: $detail"
+  if [ -n "$lines" ]; then
+    echo "$lines" | head -3 | sed 's/^/         /'
+  fi
+  violations=$((violations + 1))
+}
+
+# Read newline-separated file list; OK on macOS bash 3.2.
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  file_count=$((file_count + 1))
+  # R1: env mutations.
+  env_lines=$(grep -nE 'process\.env\.[A-Za-z_][A-Za-z_0-9]*[[:space:]]*=[^=]|process\.env\[[^]]+\][[:space:]]*=[^=]|delete[[:space:]]+process\.env\.|delete[[:space:]]+process\.env\[|Object\.assign[[:space:]]*\([[:space:]]*process\.env|Reflect\.set[[:space:]]*\([[:space:]]*process\.env' "$f" 2>/dev/null || true)
+  if [ -n "$env_lines" ]; then
+    emit_violation "$f" "R1" "process.env mutation; use withEnv() or rename to *.serial.test.ts" "$env_lines"
+  fi
+
+  # R2: mock.module() anywhere.
+  mock_lines=$(grep -nE 'mock\.module[[:space:]]*\(' "$f" 2>/dev/null || true)
+  if [ -n "$mock_lines" ]; then
+    emit_violation "$f" "R2" "mock.module() leaks across files in the shard process; rename to *.serial.test.ts" "$mock_lines"
+  fi
+
+  # R3: PGLiteEngine outside ~50 lines after a beforeAll(.
+  if grep -qE 'new PGLiteEngine[[:space:]]*\(' "$f" 2>/dev/null; then
+    bad=$(awk '
+      BEGIN { last_before_all = -1000 }
+      /beforeAll[[:space:]]*\(/ { last_before_all = NR }
+      /new PGLiteEngine[[:space:]]*\(/ {
+        if (NR - last_before_all > 50) {
+          printf "%d:%s\n", NR, $0
+        }
+      }
+    ' "$f" 2>/dev/null)
+    if [ -n "$bad" ]; then
+      emit_violation "$f" "R3" "new PGLiteEngine(...) outside beforeAll() context (>50 lines); move into beforeAll" "$bad"
+    fi
+  fi
+
+  # R4: PGLiteEngine creation requires afterAll{disconnect}.
+  if grep -qE 'new PGLiteEngine[[:space:]]*\(' "$f" 2>/dev/null; then
+    if ! grep -qE 'afterAll[[:space:]]*\(' "$f" 2>/dev/null \
+       || ! grep -qE '\.disconnect[[:space:]]*\(' "$f" 2>/dev/null; then
+      emit_violation "$f" "R4" "creates PGLiteEngine but missing afterAll(() => engine.disconnect()); engine leaks across files in the shard process" ""
+    fi
+  fi
+done <<EOF
+$FILE_LIST
+EOF
+
+if [ $violations -gt 0 ]; then
+  echo
+  echo "check-test-isolation: FAIL ($violations violation(s))"
+  echo
+  echo "Fix:"
+  echo "  - For env mutations, use withEnv() from test/helpers/with-env.ts"
+  echo "  - For mock.module(), rename to *.serial.test.ts (quarantine)"
+  echo "  - For PGLiteEngine, follow the canonical pattern in"
+  echo "    test/helpers/reset-pglite.ts JSDoc and CLAUDE.md."
+  echo
+  echo "Or, if this is a baseline file from before the lint shipped,"
+  echo "add it to scripts/check-test-isolation.allowlist (with a TODO"
+  echo "comment naming the sweep PR that will remove it)."
+  exit 1
+fi
+
+echo "check-test-isolation: OK ($file_count non-serial unit files scanned)"

scripts/check-trailing-newline.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# CI guard: every text file under src/, test/, and the repo root .yml/.md
+# files must end with a newline. POSIX-noncompliant trailing data shows up
+# as a phantom diff on every future edit and trips most linters.
+#
+# Sibling to scripts/check-progress-to-stdout.sh and
+# scripts/check-jsonb-pattern.sh per CLAUDE.md's CI guard pattern.
+# Wired into `bun run test` via package.json's `test` script.
+
+set -euo pipefail
+
+# Files to check: anything tracked under src/ + test/ that's a code/text file.
+# Also the top-level *.yml + *.md the repo controls. Portable to bash 3.2
+# (macOS default) — no mapfile, no associative arrays.
+files=$(
+  git ls-files \
+    'src/**/*.ts' 'src/**/*.js' 'src/**/*.json' 'src/**/*.sql' 'src/**/*.md' \
+    'test/**/*.ts' 'test/**/*.js' 'test/**/*.json' 'test/**/*.md' \
+    'gbrain.yml' '*.md' \
+  2>/dev/null | sort -u
+)
+
+missing=""
+total=0
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  [ -f "$f" ] || continue
+  [ -s "$f" ] || continue
+  total=$((total + 1))
+  if [ -n "$(tail -c 1 "$f")" ]; then
+    missing="${missing}  $f"$'\n'
+  fi
+done <<< "$files"
+
+if [ -n "$missing" ]; then
+  echo "ERROR: the following files are missing a trailing newline:" >&2
+  printf '%s' "$missing" >&2
+  echo >&2
+  echo "Fix: append a newline. e.g. \`printf '\\n' >> <file>\` or your editor's" >&2
+  echo "'final newline' setting (most editors do this automatically)." >&2
+  exit 1
+fi
+
+echo "trailing-newline check: ok ($total files)"

scripts/check-wasm-embedded.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# CI guard: verify that bun --compile binaries ship with embedded tree-sitter
+# WASMs and produce real semantic chunks (not recursive-fallback chunks).
+#
+# This is the #1 silent-failure mode for v0.19.0 code indexing. If the WASM
+# import attributes regress or the asset path drifts, the compiled binary
+# silently falls through to the recursive text chunker. Users see no error,
+# just degraded chunking quality. This script catches that regression.
+#
+# Fails the build when:
+#   - bun build --compile fails
+#   - The resulting binary can't parse TypeScript
+#   - Chunks come back without real symbol names (fallback signature)
+#
+# Runs as part of `bun test` via the package.json pre-test pipeline.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+OUT_BIN="$(mktemp /tmp/gbrain-wasm-check.XXXXXX)"
+trap 'rm -f "$OUT_BIN"' EXIT
+
+# Build a minimal smoketest binary that imports the chunker. We compile this
+# instead of the full gbrain CLI so the failure mode is laser-focused on
+# chunker + WASM path resolution, not unrelated CLI wiring.
+bun build --compile --outfile "$OUT_BIN" scripts/chunker-smoketest.ts >/dev/null 2>&1
+
+# Run it and capture JSON output.
+OUTPUT="$("$OUT_BIN" 2>&1)"
+
+# Sanity: JSON parses and has expected shape.
+# - has_symbol_names: at least one chunk carries a concrete symbol name
+#   (proves tree-sitter AST extraction, not recursive-fallback chunks).
+# - has_typescript_header: the structured header is emitted with the
+#   correct language tag (proves the language map reached displayLang).
+# - calculateScore by name: specific function that MUST appear as a
+#   top-level semantic node. If it's missing, the chunker either fell
+#   through to recursive or the TypeScript grammar didn't load.
+if ! echo "$OUTPUT" | grep -q '"has_symbol_names": true'; then
+  echo "[check-wasm-embedded] FAIL: compiled binary returned no symbol names (fallback chunks)." >&2
+  echo "[check-wasm-embedded] Output was:" >&2
+  echo "$OUTPUT" >&2
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q '"has_typescript_header": true'; then
+  echo "[check-wasm-embedded] FAIL: chunk header missing TypeScript language tag." >&2
+  echo "[check-wasm-embedded] Output was:" >&2
+  echo "$OUTPUT" >&2
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q '"calculateScore"'; then
+  echo "[check-wasm-embedded] FAIL: tree-sitter did not extract the calculateScore function symbol." >&2
+  echo "[check-wasm-embedded] Output was:" >&2
+  echo "$OUTPUT" >&2
+  exit 1
+fi
+
+echo "[check-wasm-embedded] OK — compiled binary produced real semantic chunks."

scripts/chunker-smoketest.ts

@@ -0,0 +1,51 @@
+import { chunkCodeText } from '../src/core/chunkers/code.ts';
+
+// Large function body so it doesn't merge with siblings — the CI guard
+// needs at least one chunk with a concrete symbol name to prove the
+// tree-sitter WASM is actually resolving (not just recursive fallback).
+const src = `export function calculateScore(
+  items: Array<{ value: number; weight: number }>,
+  opts: { normalize?: boolean; cap?: number } = {}
+): number {
+  if (items.length === 0) return 0;
+  const sum = items.reduce((acc, it) => acc + it.value * it.weight, 0);
+  const totalWeight = items.reduce((acc, it) => acc + it.weight, 0);
+  if (totalWeight === 0) return 0;
+  const raw = sum / totalWeight;
+  if (opts.normalize) {
+    const clamped = Math.max(0, Math.min(1, raw));
+    return opts.cap !== undefined ? Math.min(opts.cap, clamped) : clamped;
+  }
+  return opts.cap !== undefined ? Math.min(opts.cap, raw) : raw;
+}
+
+export class UserRegistry {
+  private users: Map<string, { name: string; score: number }> = new Map();
+
+  register(id: string, name: string, score: number): void {
+    this.users.set(id, { name, score });
+  }
+
+  lookup(id: string): { name: string; score: number } | null {
+    return this.users.get(id) ?? null;
+  }
+
+  topK(k: number): Array<{ id: string; name: string; score: number }> {
+    const entries = Array.from(this.users.entries());
+    entries.sort((a, b) => b[1].score - a[1].score);
+    return entries.slice(0, k).map(([id, v]) => ({ id, ...v }));
+  }
+}
+
+export type UserId = string;
+`;
+const result = await chunkCodeText(src, 'smoketest.ts');
+const hasSymbolNames = result.some(c => c.metadata.symbolName !== null);
+const hasTypeScriptHeader = result.some(c => c.text.startsWith('[TypeScript]'));
+console.log(JSON.stringify({
+  count: result.length,
+  has_symbol_names: hasSymbolNames,
+  has_typescript_header: hasTypeScriptHeader,
+  first_header: result[0]?.text.split('\n')[0],
+  symbol_names: result.map(c => c.metadata.symbolName),
+}, null, 2));

scripts/ci-local.sh

@@ -0,0 +1,346 @@
+#!/usr/bin/env bash
+# scripts/ci-local.sh
+#
+# Local CI gate. Runs the same checks GH Actions does (and a stricter superset
+# of E2E) inside Docker. See docker-compose.ci.yml.
+#
+# Modes:
+#   bash scripts/ci-local.sh              # full local gate: gitleaks + unit + ALL E2E (4-way sharded)
+#   bash scripts/ci-local.sh --diff       # full local gate: gitleaks + unit + selected E2E (4-way sharded)
+#   bash scripts/ci-local.sh --no-pull    # skip docker compose pull (offline / debug)
+#   bash scripts/ci-local.sh --clean      # nuke named volumes for cold debug
+#   bash scripts/ci-local.sh --no-shard   # debug: run E2E sequentially against postgres-1 only
+#
+# 4-way E2E sharding: 4 pgvector services on host ports 5434-5437. The 36 E2E
+# files split N/4 per shard; shards run in parallel. Within a shard, files run
+# sequentially (TRUNCATE CASCADE no-race property documented in run-e2e.sh).
+# Wall-time on a 16-core host: ~6 min sequential -> ~1.5-2 min sharded.
+#
+# Stronger than PR CI: PR CI runs only Tier 1's 2 files; this runs all 36.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+COMPOSE_FILE="docker-compose.ci.yml"
+
+DIFF=0
+NO_PULL=0
+CLEAN=0
+NO_SHARD=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --diff) DIFF=1 ;;
+    --no-pull) NO_PULL=1 ;;
+    --clean) CLEAN=1 ;;
+    --no-shard) NO_SHARD=1 ;;
+    *)
+      echo "Usage: $0 [--diff] [--no-pull] [--clean] [--no-shard]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+cleanup() {
+  echo ""
+  echo "[ci-local] Tearing down postgres..."
+  docker compose -f "$COMPOSE_FILE" down --remove-orphans 2>&1 | tail -5 || true
+}
+trap cleanup EXIT
+
+if [ "$CLEAN" = "1" ]; then
+  echo "[ci-local] --clean: removing named volumes..."
+  docker compose -f "$COMPOSE_FILE" down -v --remove-orphans 2>&1 | tail -5 || true
+fi
+
+# Tier 2: --diff fast-path. If the diff is doc-only (or empty), skip the
+# whole heavy gate (postgres + bun install + unit + E2E) and just verify
+# gitleaks on host. Doc-only diffs go from ~25 min to ~5 seconds.
+if [ "$DIFF" = "1" ]; then
+  CLASSIFICATION=$(bun run scripts/select-e2e.ts --classify-only 2>/dev/null || echo "ERR")
+  case "$CLASSIFICATION" in
+    DOC_ONLY)
+      echo "[ci-local] --diff: diff is doc-only — skipping postgres + unit + E2E (Tier 2 fast-path)."
+      echo "[ci-local] Running gitleaks on host as the only gate..."
+      if ! command -v gitleaks >/dev/null 2>&1; then
+        echo "[ci-local] WARN: gitleaks not installed; skipping. brew install gitleaks." >&2
+      else
+        gitleaks dir . --redact --no-banner
+        gitleaks git . --redact --no-banner --log-opts="origin/master..HEAD"
+      fi
+      echo "[ci-local] Doc-only fast-path complete. No code paths exercised."
+      trap - EXIT
+      exit 0
+      ;;
+    EMPTY)
+      echo "[ci-local] --diff: diff is empty (clean branch) — running full gate per fail-closed contract."
+      ;;
+    SRC)
+      echo "[ci-local] --diff: diff touches src/ — running selected E2E + full unit phase."
+      ;;
+    *)
+      echo "[ci-local] WARN: select-e2e.ts --classify-only returned '$CLASSIFICATION' — running full gate." >&2
+      ;;
+  esac
+fi
+
+# Pre-flight: postgres host ports for 4 shards. Defaults to 5434-5437 (avoid
+# 5432 manual gbrain-test-pg, 5433 commonly held by sibling projects).
+# GBRAIN_CI_PG_PORT defines BASE; shards take BASE..BASE+3.
+PG_PORT_BASE="${GBRAIN_CI_PG_PORT:-5434}"
+for shard in 1 2 3 4; do
+  port=$((PG_PORT_BASE + shard - 1))
+  PORT_OWNER=$(docker ps --filter "publish=$port" --format "{{.Names}}" | head -1)
+  if [ -n "$PORT_OWNER" ]; then
+    echo "[ci-local] ERROR: host port $port (shard $shard) is already used by docker container '$PORT_OWNER'." >&2
+    echo "[ci-local] Either stop that container or run with: GBRAIN_CI_PG_PORT=NNNN bun run ci:local" >&2
+    exit 1
+  fi
+  if lsof -iTCP:"$port" -sTCP:LISTEN -P -n >/dev/null 2>&1; then
+    echo "[ci-local] ERROR: host port $port (shard $shard) is held by a non-docker process." >&2
+    echo "[ci-local] Run with: GBRAIN_CI_PG_PORT=NNNN bun run ci:local" >&2
+    exit 1
+  fi
+done
+export GBRAIN_CI_PG_PORT="$PG_PORT_BASE"
+export GBRAIN_CI_PG_PORT_2=$((PG_PORT_BASE + 1))
+export GBRAIN_CI_PG_PORT_3=$((PG_PORT_BASE + 2))
+export GBRAIN_CI_PG_PORT_4=$((PG_PORT_BASE + 3))
+
+# Step 0: gitleaks on the host (no docker, no postgres, no bun needed).
+# Mirrors test.yml's separate gitleaks job. Fail loudly if not installed.
+echo "[ci-local] gitleaks detect (host)..."
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "[ci-local] ERROR: gitleaks not installed on host." >&2
+  echo "[ci-local]   macOS:  brew install gitleaks" >&2
+  echo "[ci-local]   Linux:  https://github.com/gitleaks/gitleaks/releases" >&2
+  exit 1
+fi
+# Two scopes for pre-push:
+#   1. Working-tree files (catch uncommitted secrets sitting in files)
+#   2. Branch commits vs origin/master (catch secrets committed on this branch)
+# Full-history scan is ~4 min on this repo's 3700+ commits; not useful pre-push.
+gitleaks dir . --redact --no-banner
+gitleaks git . --redact --no-banner --log-opts="origin/master..HEAD"
+
+# Step 1: pull. Refreshes pgvector + oven/bun:1 (both are `image:` not `build:`).
+if [ "$NO_PULL" = "0" ]; then
+  echo "[ci-local] Pulling base images (use --no-pull to skip)..."
+  docker compose -f "$COMPOSE_FILE" pull 2>&1 | tail -5
+fi
+
+# Step 2: 4 postgres shards up + wait for healthy.
+echo "[ci-local] Starting 4 postgres shards..."
+docker compose -f "$COMPOSE_FILE" up -d postgres-1 postgres-2 postgres-3 postgres-4
+echo "[ci-local] Waiting for all 4 postgres shards healthy..."
+for i in {1..40}; do
+  all_healthy=1
+  for shard in 1 2 3 4; do
+    status=$(docker compose -f "$COMPOSE_FILE" ps --format json postgres-$shard 2>/dev/null | grep -o '"Health":"[^"]*"' | head -1 | sed 's/.*":"//;s/"//')
+    if [ "$status" != "healthy" ]; then
+      all_healthy=0
+      break
+    fi
+  done
+  if [ "$all_healthy" = "1" ]; then
+    echo "[ci-local] All 4 postgres shards healthy."
+    break
+  fi
+  if [ "$i" = "40" ]; then
+    echo "[ci-local] ERROR: not all postgres shards became healthy in 40 attempts" >&2
+    exit 1
+  fi
+  sleep 1
+done
+
+# Step 3: smoke-test run-e2e.sh argv + shard handling.
+echo "[ci-local] Smoke: run-e2e.sh argv + shard..."
+SMOKE_NO_ARGS=$(bash scripts/run-e2e.sh --dry-run-list | wc -l | tr -d ' ')
+EXPECTED_ALL=$(ls test/e2e/*.test.ts | wc -l | tr -d ' ')
+if [ "$SMOKE_NO_ARGS" != "$EXPECTED_ALL" ]; then
+  echo "[ci-local] ERROR: --dry-run-list (no args) printed $SMOKE_NO_ARGS, expected $EXPECTED_ALL" >&2
+  exit 1
+fi
+SMOKE_ONE_ARG=$(bash scripts/run-e2e.sh --dry-run-list test/e2e/sync.test.ts)
+if [ "$SMOKE_ONE_ARG" != "test/e2e/sync.test.ts" ]; then
+  echo "[ci-local] ERROR: --dry-run-list with 1 arg printed '$SMOKE_ONE_ARG'" >&2
+  exit 1
+fi
+SHARD_TOTAL=$(( $(SHARD=1/4 bash scripts/run-e2e.sh --dry-run-list | wc -l) + \
+                $(SHARD=2/4 bash scripts/run-e2e.sh --dry-run-list | wc -l) + \
+                $(SHARD=3/4 bash scripts/run-e2e.sh --dry-run-list | wc -l) + \
+                $(SHARD=4/4 bash scripts/run-e2e.sh --dry-run-list | wc -l) ))
+if [ "$SHARD_TOTAL" != "$EXPECTED_ALL" ]; then
+  echo "[ci-local] ERROR: shards 1-4 covered $SHARD_TOTAL files, expected $EXPECTED_ALL" >&2
+  exit 1
+fi
+echo "[ci-local] Smoke OK ($SMOKE_NO_ARGS files no-arg, 1 single-arg, ${SHARD_TOTAL}=4-shard total)."
+
+# Step 4: build the runner-side command.
+# Tier 1: 4-shard parallel UNIT + E2E. Each shard runs ~46 unit files + ~9
+# E2E files against postgres-N. Guards + typecheck run ONCE before fan-out.
+# --no-shard runs the legacy unsharded flow (debug aid).
+if [ "$NO_SHARD" = "1" ]; then
+  if [ "$DIFF" = "1" ]; then
+    RUN_PHASES_CMD='echo "[runner] guards + typecheck"
+bash scripts/check-jsonb-pattern.sh
+bash scripts/check-progress-to-stdout.sh
+bash scripts/check-trailing-newline.sh
+bash scripts/check-wasm-embedded.sh
+bun run typecheck
+echo "[runner] unit (unsharded, DATABASE_URL unset)"
+env -u DATABASE_URL bash scripts/run-unit-shard.sh
+echo "[runner] e2e (unsharded, --diff selected)"
+SELECTED=$(bun run scripts/select-e2e.ts)
+if [ -z "$SELECTED" ]; then
+  echo "[runner] selector emitted nothing (doc-only diff); skipping E2E."
+else
+  DATABASE_URL=postgresql://postgres:postgres@postgres-1:5432/gbrain_test echo "$SELECTED" | xargs bash scripts/run-e2e.sh
+fi'
+  else
+    RUN_PHASES_CMD='echo "[runner] guards + typecheck"
+bash scripts/check-jsonb-pattern.sh
+bash scripts/check-progress-to-stdout.sh
+bash scripts/check-trailing-newline.sh
+bash scripts/check-wasm-embedded.sh
+bun run typecheck
+echo "[runner] unit (unsharded, DATABASE_URL unset)"
+env -u DATABASE_URL bash scripts/run-unit-shard.sh
+echo "[runner] e2e (unsharded)"
+DATABASE_URL=postgresql://postgres:postgres@postgres-1:5432/gbrain_test bash scripts/run-e2e.sh'
+  fi
+else
+  # Tier 1 sharded path. Each shard runs unit+E2E sequentially against its
+  # own postgres-N. Shards run in parallel via xargs -P4.
+  if [ "$DIFF" = "1" ]; then
+    DIFF_E2E_PREP='SELECTED=$(bun run scripts/select-e2e.ts)
+if [ -z "$SELECTED" ]; then
+  echo "" > /tmp/e2e-selected.txt
+else
+  echo "$SELECTED" | tr " " "\n" | grep -v "^$" > /tmp/e2e-selected.txt
+fi'
+  else
+    # Empty file -> run-e2e.sh uses default glob (all 36 E2E files).
+    DIFF_E2E_PREP='> /tmp/e2e-selected.txt'
+  fi
+  RUN_PHASES_CMD="echo \"[runner] guards + typecheck (run once before sharding)\"
+bash scripts/check-jsonb-pattern.sh
+bash scripts/check-progress-to-stdout.sh
+bash scripts/check-trailing-newline.sh
+bash scripts/check-wasm-embedded.sh
+bun run typecheck
+echo \"[runner] Tier 3: building PGLite snapshot fixture (cached across reruns)\"
+if [ ! -f test/fixtures/pglite-snapshot.tar ] || [ ! -f test/fixtures/pglite-snapshot.version ]; then
+  bun run build:pglite-snapshot
+else
+  echo \"[runner] snapshot fixture exists; engine will validate hash at load time\"
+fi
+export GBRAIN_PGLITE_SNAPSHOT=test/fixtures/pglite-snapshot.tar
+echo \"[runner] resolving E2E file selection (--diff aware)\"
+${DIFF_E2E_PREP}
+mkdir -p /tmp/shard-logs
+echo \"[runner] Tier 1: 4-shard parallel unit + E2E (xargs -P4)\"
+set +e
+printf '%s\\n' 1 2 3 4 | xargs -P4 -I{} sh -c '
+  shard=\$1
+  log=/tmp/shard-logs/shard-\${shard}.log
+  echo \"[shard \${shard}] start\" > \$log
+  echo \"[shard \${shard}] unit phase (SHARD=\${shard}/4, DATABASE_URL unset)\" >> \$log
+  env -u DATABASE_URL SHARD=\${shard}/4 bash scripts/run-unit-shard.sh >> \$log 2>&1
+  unit_exit=\$?
+  if [ \$unit_exit -ne 0 ]; then
+    echo \"[shard \${shard}] UNIT FAILED (exit=\$unit_exit)\" >> \$log
+    exit \$unit_exit
+  fi
+  echo \"[shard \${shard}] e2e phase (SHARD=\${shard}/4, DATABASE_URL=postgres-\${shard})\" >> \$log
+  if [ -s /tmp/e2e-selected.txt ]; then
+    SHARD=\${shard}/4 \\
+    DATABASE_URL=postgresql://postgres:postgres@postgres-\${shard}:5432/gbrain_test \\
+    xargs -a /tmp/e2e-selected.txt bash scripts/run-e2e.sh >> \$log 2>&1
+  else
+    SHARD=\${shard}/4 \\
+    DATABASE_URL=postgresql://postgres:postgres@postgres-\${shard}:5432/gbrain_test \\
+    bash scripts/run-e2e.sh >> \$log 2>&1
+  fi
+  e2e_exit=\$?
+  if [ \$e2e_exit -ne 0 ]; then
+    echo \"[shard \${shard}] E2E FAILED (exit=\$e2e_exit)\" >> \$log
+    exit \$e2e_exit
+  fi
+  echo \"[shard \${shard}] DONE\" >> \$log
+' _ {}
+shard_xargs_exit=\$?
+set -e
+echo \"\"
+echo \"=== SHARD LOGS (last 30 lines each + unit/e2e summaries) ===\"
+for s in 1 2 3 4; do
+  echo \"\"
+  echo \"--- shard \$s ---\"
+  if [ -f /tmp/shard-logs/shard-\$s.log ]; then
+    # Pull the unit + E2E summary lines explicitly so they survive even if
+    # the file is huge. Match: bun's '<N> pass / <N> fail' pairs, run-e2e.sh's
+    # 'Files: ... / Tests: ...' summary, and our own shard markers.
+    grep -E '^\\[shard|^Files: |^Tests: |Ran [0-9]+ tests|^[[:space:]]+[0-9]+ (pass|fail|skip)\$' /tmp/shard-logs/shard-\$s.log || true
+    echo \"  (last 30 lines for context)\"
+    tail -30 /tmp/shard-logs/shard-\$s.log
+  else
+    echo \"(no log file written — shard never started)\"
+  fi
+done
+echo \"\"
+if [ \$shard_xargs_exit -ne 0 ]; then
+  echo \"[runner] One or more shards failed (xargs exit=\$shard_xargs_exit). See SHARD LOGS above.\"
+  exit \$shard_xargs_exit
+fi
+echo \"[runner] All 4 shards passed.\""
+fi
+
+INNER_CMD=$(cat <<'EOF'
+set -euo pipefail
+echo "[runner] bun version: $(bun --version)"
+# oven/bun:1 omits git; many unit tests use mkdtemp + git init for fixtures.
+if ! command -v git >/dev/null 2>&1; then
+  echo "[runner] Installing git (debian apt)..."
+  apt-get update -qq >/dev/null
+  apt-get install -y -qq git ca-certificates >/dev/null
+fi
+# Container runs as root (uid 0) against a host-uid bind-mount; mark repo +
+# any worktree gitdir as safe so `git status` etc. don't refuse.
+git config --global --add safe.directory '*' || true
+if [ ! -d /app/node_modules ] || [ -z "$(ls -A /app/node_modules 2>/dev/null)" ]; then
+  echo "[runner] First run (or --clean): bun install --frozen-lockfile"
+  bun install --frozen-lockfile
+fi
+__RUN_PHASES__
+EOF
+)
+INNER_CMD="${INNER_CMD/__RUN_PHASES__/$RUN_PHASES_CMD}"
+
+# Conductor / git-worktree support: when `.git` is a file (not a directory),
+# it points at a host gitdir outside the bind-mount. Without remounting that
+# path, scripts/check-trailing-newline.sh and any other in-container `git`
+# call exits 128 ("not a git repository"). Resolve the host gitdir + the
+# shared common gitdir and bind-mount them at the same absolute paths.
+EXTRA_MOUNTS=()
+if [ -f .git ]; then
+  WORKTREE_GITDIR=$(awk '{print $2}' .git)
+  if [ -d "$WORKTREE_GITDIR" ]; then
+    COMMONDIR_FILE="$WORKTREE_GITDIR/commondir"
+    if [ -f "$COMMONDIR_FILE" ]; then
+      COMMON_REL=$(cat "$COMMONDIR_FILE")
+      COMMON_GITDIR=$(cd "$WORKTREE_GITDIR" && cd "$COMMON_REL" && pwd)
+    else
+      COMMON_GITDIR="$WORKTREE_GITDIR"
+    fi
+    # Mount the higher-level common gitdir; covers worktrees/<name> automatically.
+    EXTRA_MOUNTS+=( -v "${COMMON_GITDIR}:${COMMON_GITDIR}:ro" )
+    echo "[ci-local] Worktree detected; mounting shared gitdir: $COMMON_GITDIR"
+  fi
+fi
+
+echo "[ci-local] Running checks inside runner container..."
+docker compose -f "$COMPOSE_FILE" run --rm "${EXTRA_MOUNTS[@]:-}" runner bash -c "$INNER_CMD"
+
+echo ""
+echo "[ci-local] All checks passed."

scripts/e2e-test-map.ts

@@ -0,0 +1,69 @@
+// scripts/e2e-test-map.ts
+//
+// Path-glob -> E2E test files map. Used by scripts/select-e2e.ts.
+//
+// CONTRACT: This map can ONLY narrow from "all". When a changed src/ path
+// matches no glob here, the selector falls back to "run all E2E" (fail-closed).
+// You can safely add narrowing entries; you cannot break correctness by missing
+// one. Tune as misses surface (i.e., when ci:local:diff ran more than necessary
+// and you'd like to narrow that surface area).
+//
+// Glob syntax is the minimal subset implemented in select-e2e.ts:
+//   - "**" matches any sequence of path segments (including zero)
+//   - "*" matches any characters within a single path segment
+//   - everything else is literal
+// No brace expansion, no ?, no [ ].
+
+export const E2E_TEST_MAP: Record<string, string[]> = {
+  // Source-aware ranking, hybrid search, intent classification.
+  "src/core/search/**": [
+    "test/e2e/search-quality.test.ts",
+    "test/e2e/search-exclude.test.ts",
+    "test/e2e/search-swamp.test.ts",
+  ],
+  // Tree-sitter chunkers feed code-indexing E2E.
+  "src/core/chunkers/**": ["test/e2e/code-indexing.test.ts"],
+  // dream.ts is a thin alias over runCycle in cycle.ts.
+  "src/core/cycle.ts": ["test/e2e/cycle.test.ts", "test/e2e/dream.test.ts"],
+  // Multi-source sync writes share the per-source bookmark anchor.
+  "src/core/sync.ts": ["test/e2e/sync.test.ts", "test/e2e/multi-source.test.ts"],
+  // Any minions queue/worker/handler change exercises all minion E2E.
+  "src/core/minions/**": [
+    "test/e2e/minions-concurrency.test.ts",
+    "test/e2e/minions-resilience.test.ts",
+    "test/e2e/minions-shell.test.ts",
+    "test/e2e/minions-shell-pglite.test.ts",
+    "test/e2e/worker-abort-recovery.test.ts",
+  ],
+  // postgres.js bind paths + JSONB shapes + parity vs PGLite.
+  "src/core/postgres-engine.ts": [
+    "test/e2e/postgres-bootstrap.test.ts",
+    "test/e2e/postgres-jsonb.test.ts",
+    "test/e2e/jsonb-roundtrip.test.ts",
+    "test/e2e/engine-parity.test.ts",
+    "test/e2e/schema-drift.test.ts",
+  ],
+  // PGLite bootstrap path + parity guard.
+  "src/core/pglite-engine.ts": [
+    "test/e2e/postgres-bootstrap.test.ts",
+    "test/e2e/engine-parity.test.ts",
+    "test/e2e/schema-drift.test.ts",
+  ],
+  // Schema source of truth: any change must pass the cross-engine drift gate.
+  "src/schema.sql": ["test/e2e/schema-drift.test.ts"],
+  "src/core/pglite-schema.ts": ["test/e2e/schema-drift.test.ts"],
+  "src/core/migrate.ts": ["test/e2e/schema-drift.test.ts", "test/e2e/migrate-chain.test.ts"],
+  // MCP stdio + HTTP transports share dispatch.
+  "src/mcp/**": ["test/e2e/mcp.test.ts", "test/e2e/http-transport.test.ts"],
+  // Integrity batch-load fast path.
+  "src/commands/integrity.ts": ["test/e2e/integrity-batch.test.ts"],
+  // Upgrade chains migration ledger; touches both runners.
+  "src/commands/upgrade.ts": [
+    "test/e2e/upgrade.test.ts",
+    "test/e2e/migrate-chain.test.ts",
+    "test/e2e/migration-flow.test.ts",
+  ],
+  "src/commands/doctor.ts": ["test/e2e/doctor-progress.test.ts"],
+  // Knowledge graph layer feeds graph-quality.
+  "src/core/link-extraction.ts": ["test/e2e/graph-quality.test.ts"],
+};

scripts/fix-v0.11.0.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# fix-v0.11.0.sh — stopgap for broken v0.11.0 installs where the Minions
+# migration never fired on upgrade.
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/garrytan/gbrain/v0.11.1/scripts/fix-v0.11.0.sh | bash
+#
+# What it does:
+#   1. gbrain init --migrate-only — applies schema v7 without touching config.
+#   2. gbrain jobs smoke — fails loudly if Minions isn't healthy.
+#   3. Prompts for minion_mode (or defaults to pain_triggered on non-TTY).
+#   4. Atomically writes ~/.gbrain/preferences.json (0o600).
+#   5. Appends ~/.gbrain/migrations/completed.jsonl with status:"partial" and
+#      apply_migrations_pending: true — the v0.11.1 `apply-migrations` runner
+#      will pick up where we left off (host rewrites, autopilot install).
+#   6. Detects host AGENTS.md / cron/jobs.json and PRINTS the rewrite guidance
+#      as text. Never auto-edits host files from a curl-piped script — too
+#      high blast-radius (user trust model is "I pasted this").
+#   7. Final line: tells the user to run `gbrain autopilot --install` as the
+#      one-stop finisher (autopilot forks the Minions worker as a child).
+#
+# Retires when v0.11.1 is out: the canonical fix becomes
+#   gbrain upgrade && gbrain apply-migrations
+
+set -euo pipefail
+
+RED=$'\033[1;31m'
+GREEN=$'\033[1;32m'
+YELLOW=$'\033[1;33m'
+NC=$'\033[0m'
+
+say()  { printf "%s%s%s\n" "$1" "$2" "$NC"; }
+info() { say "" "$1"; }
+ok()   { say "$GREEN" "$1"; }
+warn() { say "$YELLOW" "$1"; }
+die()  { say "$RED" "$1"; exit 1; }
+
+command -v gbrain >/dev/null 2>&1 || die "gbrain not found on \$PATH. Install it first (\`bun add -g gbrain\` or download a binary)."
+
+GBRAIN_DIR="${HOME}/.gbrain"
+PREFS_PATH="${GBRAIN_DIR}/preferences.json"
+COMPLETED_PATH="${GBRAIN_DIR}/migrations/completed.jsonl"
+
+mkdir -p "${GBRAIN_DIR}/migrations"
+
+# ------------------------------------------------------------
+# Step 1: schema
+# ------------------------------------------------------------
+info "[1/8] Applying schema (gbrain init --migrate-only)..."
+if ! gbrain init --migrate-only; then
+  die "Schema migration failed. Check ~/.gbrain/config.json has a valid database_url (or database_path for PGLite), then re-run."
+fi
+ok "      schema ok"
+
+# ------------------------------------------------------------
+# Step 2: smoke
+# ------------------------------------------------------------
+info "[2/8] Running Minions smoke test (gbrain jobs smoke)..."
+if ! gbrain jobs smoke; then
+  die "Smoke test failed. See the error above. Fix before continuing."
+fi
+ok "      smoke ok"
+
+# ------------------------------------------------------------
+# Step 3: mode prompt
+# ------------------------------------------------------------
+info "[3/8] Choose minion_mode..."
+MODE="pain_triggered"
+if [ -t 0 ] && [ -t 1 ]; then
+  echo ""
+  echo "  [1] always          — route every background task through Minions (most durable)"
+  echo "  [2] pain_triggered  — default to native subagents, switch to Minions on pain signals (recommended)"
+  echo "  [3] off             — disable Minions; keep native subagents"
+  echo ""
+  read -r -p "  Choice [2]: " CHOICE
+  case "${CHOICE:-2}" in
+    1) MODE="always" ;;
+    3) MODE="off" ;;
+    *) MODE="pain_triggered" ;;
+  esac
+else
+  warn "      non-interactive shell → defaulting to pain_triggered (change later: \`gbrain config set minion_mode <mode>\`)"
+fi
+ok "      mode=${MODE}"
+
+# ------------------------------------------------------------
+# Step 4: atomic write preferences.json (0o600)
+# ------------------------------------------------------------
+info "[4/8] Writing ~/.gbrain/preferences.json..."
+NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TMP_PREFS=$(mktemp)
+cat > "${TMP_PREFS}" <<EOF
+{
+  "minion_mode": "${MODE}",
+  "set_at": "${NOW_ISO}",
+  "set_in_version": "0.11.0"
+}
+EOF
+chmod 600 "${TMP_PREFS}"
+mv "${TMP_PREFS}" "${PREFS_PATH}"
+chmod 600 "${PREFS_PATH}"
+ok "      wrote ${PREFS_PATH}"
+
+# ------------------------------------------------------------
+# Step 5: append completed.jsonl as status:"partial"
+# ------------------------------------------------------------
+info "[5/8] Recording migration as partial..."
+# We write "partial" + apply_migrations_pending:true. v0.11.1 apply-migrations
+# detects this and resumes the remaining phases (host rewrites + autopilot
+# install). If we wrote "complete" here, apply-migrations would SKIP the
+# remaining phases and the broken install would stay broken (Codex H2).
+echo "{\"version\":\"0.11.0\",\"status\":\"partial\",\"apply_migrations_pending\":true,\"mode\":\"${MODE}\",\"ts\":\"${NOW_ISO}\",\"source\":\"fix-v0.11.0.sh\"}" >> "${COMPLETED_PATH}"
+ok "      appended ${COMPLETED_PATH}"
+
+# ------------------------------------------------------------
+# Step 6: detect AGENTS.md — PRINT guidance, do not auto-edit
+# ------------------------------------------------------------
+info "[6/8] Scanning for AGENTS.md..."
+AGENTS_FOUND=()
+for CANDIDATE in "${HOME}/.claude/AGENTS.md" "${HOME}/.openclaw/AGENTS.md" "${PWD}/AGENTS.md"; do
+  [ -f "${CANDIDATE}" ] && AGENTS_FOUND+=("${CANDIDATE}")
+done
+if [ ${#AGENTS_FOUND[@]} -eq 0 ]; then
+  ok "      no AGENTS.md found — nothing to suggest"
+else
+  for F in "${AGENTS_FOUND[@]}"; do
+    warn "      AGENTS.md detected: ${F}"
+    echo "        - Next steps (this script does NOT auto-edit):"
+    echo "            1. Add a pointer to skills/conventions/subagent-routing.md"
+    echo "            2. The v0.11.1 binary's \`gbrain apply-migrations --yes\` will inject"
+    echo "               this automatically once v0.11.1 is installed."
+  done
+fi
+
+# ------------------------------------------------------------
+# Step 7: detect cron/jobs.json and scan for agentTurn
+# ------------------------------------------------------------
+info "[7/8] Scanning for cron manifests..."
+CRON_FOUND=()
+for CANDIDATE in "${HOME}/.claude/cron/jobs.json" "${HOME}/.openclaw/cron/jobs.json" "${PWD}/cron/jobs.json"; do
+  [ -f "${CANDIDATE}" ] && CRON_FOUND+=("${CANDIDATE}")
+done
+if [ ${#CRON_FOUND[@]} -eq 0 ]; then
+  ok "      no cron/jobs.json found — nothing to suggest"
+else
+  for F in "${CRON_FOUND[@]}"; do
+    warn "      cron manifest detected: ${F}"
+    COUNT=$(grep -c 'agentTurn' "${F}" 2>/dev/null || echo 0)
+    echo "        - ${COUNT} agentTurn entries"
+    echo "        - v0.11.1 apply-migrations will:"
+    echo "            * auto-rewrite builtin handlers (sync/embed/lint/import/"
+    echo "              extract/backlinks/autopilot-cycle) to gbrain jobs submit"
+    echo "            * emit a pending-host-work.jsonl TODO for every non-builtin"
+    echo "              handler; host agent walks those per skills/migrations/v0.11.0.md"
+  done
+fi
+
+# ------------------------------------------------------------
+# Step 8: final line
+# ------------------------------------------------------------
+info "[8/8] Done. Next step:"
+echo ""
+echo "      ${GREEN}gbrain autopilot --install${NC}"
+echo ""
+echo "      That ONE command does the rest: supervises autopilot, forks the"
+echo "      Minions worker, and installs the right entry for your host (launchd"
+echo "      on macOS, systemd on Linux, bootstrap hook on ephemeral containers)."
+echo ""
+echo "      Once v0.11.1 is out:"
+echo "        ${GREEN}gbrain upgrade && gbrain apply-migrations${NC}"
+echo "      becomes the canonical fix. This script retires then."

scripts/llms-config.ts

@@ -0,0 +1,205 @@
+/**
+ * llms-config — single source of truth for llms.txt + llms-full.txt.
+ *
+ * Consumed by scripts/build-llms.ts (emits llms.txt, llms-full.txt) and
+ * test/build-llms.test.ts (asserts paths resolve, content contract holds).
+ *
+ * Adding a doc? Add it here and run `bun run build:llms`. The drift-detection
+ * test fails CI if you forget.
+ *
+ * Fork-friendliness: `rawBaseUrl` reads from `LLMS_REPO_BASE` so forks can
+ * regenerate without manual URL rewrites:
+ *   LLMS_REPO_BASE=https://raw.githubusercontent.com/fork-org/gbrain/main bun run build:llms
+ */
+
+export type DocEntry = {
+  title: string;
+  description: string;
+  path: string;
+  includeInFull?: boolean;
+};
+
+export type DocSection = {
+  heading: string;
+  optional?: boolean;
+  entries: DocEntry[];
+};
+
+export const PROJECT = {
+  name: "GBrain",
+  summary:
+    "GBrain is a personal knowledge brain and GStack mod for agent platforms. Pluggable engines (PGLite default, Postgres+pgvector for scale), contract-first operations, 26 fat-markdown skills. Teaches agents brain ops, ingestion, enrichment, scheduling, identity, and access control.",
+  repoUrl: "https://github.com/garrytan/gbrain",
+  rawBaseUrl:
+    process.env.LLMS_REPO_BASE ??
+    "https://raw.githubusercontent.com/garrytan/gbrain/master",
+};
+
+export const SECTIONS: DocSection[] = [
+  {
+    heading: "Core entry points",
+    entries: [
+      {
+        title: "AGENTS.md",
+        description:
+          "Start here if you are not Claude Code. Install order, trust boundary, skill resolver, config/debug/migration pointers.",
+        path: "AGENTS.md",
+      },
+      {
+        title: "CLAUDE.md",
+        description:
+          "Architecture reference. Key files, trust boundaries, engine factory, test layout.",
+        path: "CLAUDE.md",
+      },
+      {
+        title: "INSTALL_FOR_AGENTS.md",
+        description: "9-step agent installation.",
+        path: "INSTALL_FOR_AGENTS.md",
+      },
+      {
+        title: "skills/RESOLVER.md",
+        description: "Skill dispatcher. Read first for any task.",
+        path: "skills/RESOLVER.md",
+      },
+      {
+        title: "README.md",
+        description: "Project overview, benchmarks, 30-minute setup.",
+        path: "README.md",
+      },
+    ],
+  },
+  {
+    heading: "Configuration",
+    entries: [
+      {
+        title: "docs/ENGINES.md",
+        description: "PGLite vs Postgres trade-off and when to migrate.",
+        path: "docs/ENGINES.md",
+      },
+      {
+        title: "docs/GBRAIN_RECOMMENDED_SCHEMA.md",
+        description:
+          "MECE directory structure (people/, companies/, concepts/).",
+        path: "docs/GBRAIN_RECOMMENDED_SCHEMA.md",
+      },
+      {
+        title: "docs/guides/live-sync.md",
+        description: "Incremental markdown sync setup.",
+        path: "docs/guides/live-sync.md",
+      },
+      {
+        title: "docs/guides/cron-schedule.md",
+        description: "Recurring job scheduling.",
+        path: "docs/guides/cron-schedule.md",
+      },
+      {
+        title: "docs/guides/minions-deployment.md",
+        description:
+          "Deploying the gbrain jobs worker: crontab + watchdog, inline --follow, systemd/Procfile/fly.toml, upgrade checklist.",
+        path: "docs/guides/minions-deployment.md",
+      },
+      {
+        title: "docs/guides/quiet-hours.md",
+        description: "Notification hold + timezone-aware delivery.",
+        path: "docs/guides/quiet-hours.md",
+      },
+      {
+        title: "docs/mcp/DEPLOY.md",
+        description: "MCP server deployment.",
+        path: "docs/mcp/DEPLOY.md",
+      },
+    ],
+  },
+  {
+    heading: "Debugging",
+    entries: [
+      {
+        title: "docs/GBRAIN_VERIFY.md",
+        description:
+          "7-check post-setup verification. Start here when something feels off.",
+        path: "docs/GBRAIN_VERIFY.md",
+      },
+      {
+        title: "docs/guides/minions-fix.md",
+        description: "Troubleshooting the Minions job queue.",
+        path: "docs/guides/minions-fix.md",
+      },
+      {
+        title: "docs/integrations/reliability-repair.md",
+        description: "Data integrity recovery.",
+        path: "docs/integrations/reliability-repair.md",
+      },
+    ],
+  },
+  {
+    heading: "Migrations",
+    entries: [
+      {
+        title: "docs/UPGRADING_DOWNSTREAM_AGENTS.md",
+        description:
+          "Patches for downstream agent skill forks. One section per release.",
+        path: "docs/UPGRADING_DOWNSTREAM_AGENTS.md",
+      },
+      {
+        title: "skills/migrations/",
+        description:
+          "Per-version (v0.5.0 - v0.14.1) agent-executable migration instructions.",
+        path: "skills/migrations/",
+      },
+      {
+        title: "CHANGELOG.md",
+        description:
+          "Release-summary voice + itemized changes + self-repair block per version.",
+        path: "CHANGELOG.md",
+        includeInFull: false,
+      },
+    ],
+  },
+  {
+    heading: "Philosophy",
+    optional: true,
+    entries: [
+      {
+        title: "docs/ethos/THIN_HARNESS_FAT_SKILLS.md",
+        description: "Why skills live in markdown.",
+        path: "docs/ethos/THIN_HARNESS_FAT_SKILLS.md",
+        includeInFull: false,
+      },
+      {
+        title: "docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md",
+        description: "Homebrew for Personal AI.",
+        path: "docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md",
+        includeInFull: false,
+      },
+    ],
+  },
+  {
+    heading: "Optional",
+    optional: true,
+    entries: [
+      {
+        title: "docs/designs/",
+        description: "Forward-looking designs.",
+        path: "docs/designs/",
+        includeInFull: false,
+      },
+      {
+        title: "docs/architecture/infra-layer.md",
+        description: "Shared infra patterns.",
+        path: "docs/architecture/infra-layer.md",
+        includeInFull: false,
+      },
+    ],
+  },
+];
+
+export const INLINE_TIPS = [
+  "`gbrain doctor [--json] [--fast] [--fix]` - built-in health checks.",
+  "`gbrain orphans [--json]` - pages with zero inbound wikilinks.",
+  "`gbrain repair-jsonb [--dry-run]` - repair v0.12.0 double-encoded JSONB rows.",
+  "`gbrain upgrade` runs post-upgrade + apply-migrations.",
+];
+
+// Target ~600KB so llms-full.txt fits in ~150k-token contexts with room to spare.
+// Generator prints a WARN if exceeded; ship with includeInFull=false exclusions.
+export const FULL_SIZE_BUDGET = 600_000;

scripts/profile-tests.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# scripts/profile-tests.sh
+# Tier 4 helper: prints the top N slowest unit tests from a previous run.
+# Pipe a captured `bun test` output (or a ci:local log) into stdin; we extract
+# `(pass|fail) ... [Xms|Xs]` lines, convert to ms, sort descending.
+#
+# Usage:
+#   bun test --timeout=60000 2>&1 | bash scripts/profile-tests.sh
+#   bash scripts/profile-tests.sh < /path/to/captured.log
+#   bash scripts/profile-tests.sh -n 20 < /path/to/captured.log
+#
+# To demote a test as slow: rename its file to *.slow.test.ts. The file
+# stays discoverable by `bun test` (CI runs everything via `bun run test`)
+# but is excluded from `bun run ci:local`'s fast unit shard fan-out.
+
+set -euo pipefail
+
+TOP_N=10
+if [ "${1:-}" = "-n" ] && [ -n "${2:-}" ]; then
+  TOP_N=$2
+fi
+
+# Lines look like: (pass) describe > test name [12345.67ms] OR [12.34s]
+# Single awk pass for performance (input can be tens of MB).
+awk '{
+  # Find the LAST bracket in the line: [<num><unit>] where unit is ms or s.
+  for (i = length($0); i > 0; i--) {
+    if (substr($0, i, 1) == "]") {
+      # Walk back to matching "["
+      j = i - 1
+      while (j > 0 && substr($0, j, 1) != "[") j--
+      if (j == 0) break
+      bracket = substr($0, j+1, i-j-1)
+      # bracket should match ^[0-9]+(\.[0-9]+)?(ms|s)$
+      if (bracket ~ /^[0-9]+(\.[0-9]+)?(ms|s)$/) {
+        if (bracket ~ /ms$/) {
+          n = substr(bracket, 1, length(bracket) - 2) + 0
+        } else {
+          n = (substr(bracket, 1, length(bracket) - 1) + 0) * 1000
+        }
+        if (n > 0) printf "%.0f\t%s\n", n, $0
+      }
+      break
+    }
+  }
+}' | sort -rn | head -n "$TOP_N" | awk -F'\t' '{ printf "%8.0fms  %s\n", $1, $2 }'

scripts/run-e2e.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Run E2E tests ONE FILE AT A TIME.
+#
+# Bun's default is to run test files in parallel (each in its own worker).
+# Our E2E suite shares one Postgres database across all 13 files, and
+# `setupDB()` does TRUNCATE CASCADE + fixture import. When files run in
+# parallel, file A's TRUNCATE can race with file B's fixture import,
+# producing observed fails like "expected 16 pages, got 8", missing
+# links, orphaned timeline entries, etc. The flakiness was visible on
+# ~3 of every 5 runs pre-fix.
+#
+# Running files sequentially eliminates the race entirely. It also costs
+# some startup overhead (each file spins up a fresh bun process) but for
+# a suite this size that is measured in ~1-2s per file, amortized under
+# the natural per-file test time of 5-10s.
+#
+# Exits non-zero on the first failing file so CI fails fast.
+#
+# `--timeout=60000` matches the unit test suite. Bun's default is 5s,
+# which is too tight for setupDB's TRUNCATE CASCADE on ~30 tables on
+# CI runners under load (one CI flake observed on PR #475 hitting
+# exactly 5000.09ms in the Tags beforeAll).
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# --dry-run-list: print the resolved file list (one per line) and exit. Used
+# by scripts/ci-local.sh to smoke-test the argv branching at startup.
+DRY_RUN_LIST=0
+if [ "${1:-}" = "--dry-run-list" ]; then
+  DRY_RUN_LIST=1
+  shift
+fi
+
+# Argv-driven file list (used by `ci:local:diff`); fall back to the full glob.
+if [ "$#" -gt 0 ]; then
+  files=("$@")
+else
+  files=(test/e2e/*.test.ts)
+fi
+
+# SHARD env (e.g. SHARD=1/4) keeps every M-th file starting at index N (1-indexed).
+# Used by scripts/ci-local.sh to fan 4 shards in parallel against 4 postgres
+# containers. Sequential execution within a shard is preserved (the TRUNCATE
+# CASCADE no-race rationale at the top of this file still holds).
+if [ -n "${SHARD:-}" ]; then
+  shard_n=${SHARD%/*}
+  shard_m=${SHARD#*/}
+  if ! printf '%s' "$shard_n" | grep -qE '^[0-9]+$' || \
+     ! printf '%s' "$shard_m" | grep -qE '^[0-9]+$' || \
+     [ "$shard_n" -lt 1 ] || [ "$shard_m" -lt 1 ] || [ "$shard_n" -gt "$shard_m" ]; then
+    echo "ERROR: invalid SHARD=$SHARD (expected N/M with 1<=N<=M, both integers)" >&2
+    exit 1
+  fi
+  filtered=()
+  i=0
+  for f in "${files[@]}"; do
+    if [ $((i % shard_m + 1)) -eq "$shard_n" ]; then
+      filtered+=("$f")
+    fi
+    i=$((i + 1))
+  done
+  # ${filtered[@]:-} avoids "unbound variable" under `set -u` when no files matched.
+  files=("${filtered[@]:-}")
+  # If the empty placeholder slipped in, drop it.
+  if [ "${#files[@]}" -eq 1 ] && [ -z "${files[0]}" ]; then
+    files=()
+  fi
+fi
+
+if [ "$DRY_RUN_LIST" = "1" ]; then
+  if [ "${#files[@]}" -eq 0 ]; then
+    exit 0
+  fi
+  printf '%s\n' "${files[@]}"
+  exit 0
+fi
+
+if [ "${#files[@]}" -eq 0 ]; then
+  # Empty shard (e.g. SHARD=4/4 with only 3 files): nothing to do.
+  echo "No files for shard ${SHARD:-(unsharded)}; exiting clean."
+  exit 0
+fi
+
+pass_files=0
+fail_files=0
+fail_list=()
+total_pass=0
+total_fail=0
+
+for f in "${files[@]}"; do
+  name=$(basename "$f")
+  echo ""
+  echo "=== $name ==="
+  if output=$(bun test --timeout=60000 "$f" 2>&1); then
+    pass_files=$((pass_files + 1))
+    # Extract pass/fail counts from bun's summary (e.g., "123 pass")
+    p=$(echo "$output" | grep -oE '[0-9]+ pass' | tail -1 | grep -oE '[0-9]+' || echo 0)
+    total_pass=$((total_pass + p))
+    echo "$output" | tail -8
+  else
+    fail_files=$((fail_files + 1))
+    fail_list+=("$name")
+    p=$(echo "$output" | grep -oE '[0-9]+ pass' | tail -1 | grep -oE '[0-9]+' || echo 0)
+    fl=$(echo "$output" | grep -oE '[0-9]+ fail' | tail -1 | grep -oE '[0-9]+' || echo 0)
+    total_pass=$((total_pass + p))
+    total_fail=$((total_fail + fl))
+    echo "$output"
+    echo ""
+    echo "FAILED: $name"
+    # Continue so we see all failures; exit nonzero at the end.
+  fi
+done
+
+echo ""
+echo "========================================"
+echo "E2E SUMMARY (sequential execution)"
+echo "========================================"
+echo "Files: $((pass_files + fail_files)) total, $pass_files passed, $fail_files failed"
+echo "Tests: $total_pass passed, $total_fail failed"
+if [ ${#fail_list[@]} -gt 0 ]; then
+  echo ""
+  echo "Failing files:"
+  for f in "${fail_list[@]}"; do
+    echo "  - $f"
+  done
+  exit 1
+fi

scripts/run-serial-tests.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# scripts/run-serial-tests.sh — run *.serial.test.ts files with --max-concurrency=1.
+#
+# Serial files are tests that share file-wide state (top-level mock.module,
+# module-level singletons that intentionally cross test cases) and would race
+# under intra-file concurrency. Discovered via filename suffix; no annotation
+# inside the file is needed.
+#
+# Excluded by run-unit-shard.sh and run-unit-parallel.sh's parallel pass.
+# Invoked separately by run-unit-parallel.sh after the parallel pass succeeds.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Use while-read for portability to macOS bash 3.2 (no mapfile).
+files=()
+while IFS= read -r f; do
+  files+=("$f")
+done < <(find test -name '*.serial.test.ts' -not -path 'test/e2e/*' | sort)
+
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "[serial-tests] no *.serial.test.ts files found"
+  exit 0
+fi
+
+# --dry-run-list mirrors run-unit-shard.sh for inline checks/tests.
+if [ "${1:-}" = "--dry-run-list" ]; then
+  printf '%s\n' "${files[@]}"
+  exit 0
+fi
+
+echo "[serial-tests] running ${#files[@]} file(s) with --max-concurrency=1"
+exec bun test --max-concurrency=1 --timeout=60000 "${files[@]}"

scripts/run-slow-tests.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# scripts/run-slow-tests.sh
+# Tier 4 sister to run-unit-shard.sh: runs ONLY *.slow.test.ts files.
+# CI runs both; bun run ci:local skips slow tests via run-unit-shard.sh.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+slow_files=()
+while IFS= read -r f; do
+  slow_files+=("$f")
+done < <(find test -name '*.slow.test.ts' -not -path 'test/e2e/*' | sort)
+
+if [ "${#slow_files[@]}" -eq 0 ]; then
+  echo "[run-slow-tests] no *.slow.test.ts files; nothing to do."
+  exit 0
+fi
+
+echo "[run-slow-tests] running ${#slow_files[@]} slow files (CI runs these as part of bun run test)"
+exec bun test --timeout=60000 "${slow_files[@]}"