Merge origin/master into feat/brain-first-convention

Master moved from v0.23.1 → v0.23.2 (PR #527: orchestrator-stamped
self-consumption marker for the dream cycle + verdict-model unit tests).

Conflicts resolved:
- VERSION: kept this branch's 0.24.0 per CLAUDE.md branch-scoped rule.
- package.json version: kept 0.24.0.
- CHANGELOG.md: my v0.24.0 stays on top; master's new v0.23.2 entry
  spliced between v0.24.0 and v0.23.1. Sequence above v0.21.0 monotonic.

Verification:
- bun install — 0 new packages
- All 5 CI guards green: privacy + jsonb + progress + trailing-newline + wasm
- bun run typecheck — clean
- This branch's tests: 103/103 pass

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.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 run test
+      - name: Pre-test gates (shard 1 only — they're not test files)
+        if: matrix.shard == 1
+        run: scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && scripts/check-wasm-embedded.sh && bun run typecheck
+      - name: Run test shard ${{ matrix.shard }}/4
+        run: scripts/test-shard.sh ${{ matrix.shard }} 4

.gitignore

@@ -17,3 +17,13 @@ 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/
+
+# Tier 3 PGLite snapshot fixture (built on demand by build:pglite-snapshot)
+test/fixtures/pglite-snapshot.tar
+test/fixtures/pglite-snapshot.version

AGENTS.md

@@ -43,9 +43,16 @@ writing or reviewing an operation, consult `src/core/operations.ts` for the cont
 
 ## Before shipping
 
-Run `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.
+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
 

CLAUDE.md

@@ -22,24 +22,33 @@ strict behavior when unset.
 
 ## Key files
 
-- `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`. `OperationContext.remote` flags untrusted callers.
+- `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`, plus `matchesSlugAllowList(slug, prefixes)` (v0.23 glob matcher: `<prefix>/*` matches recursive children; bare `<prefix>` matches exact only). `OperationContext.remote` flags untrusted callers; `OperationContext.allowedSlugPrefixes` (v0.23) is the trusted-workspace allow-list set by the dream cycle. `put_page` enforces: when `viaSubagent` and `allowedSlugPrefixes` is set, slug must match the allow-list; else the legacy `wiki/agents/<id>/...` namespace check applies. Auto-link enabled for trusted-workspace writes (skipped only when `remote=true && !trustedWorkspace`).
 - `src/core/engine.ts` — Pluggable engine interface (BrainEngine). `clampSearchLimit(limit, default, cap)` takes an explicit cap so per-operation caps can be tighter than `MAX_SEARCH_LIMIT`. Exports `LinkBatchInput` / `TimelineBatchInput` for the v0.12.1 bulk-insert API (`addLinksBatch` / `addTimelineEntriesBatch`). As of v0.13.1, `BrainEngine` has a `readonly kind: 'postgres' | 'pglite'` discriminator so migrations (`src/core/migrate.ts`) and other consumers can branch on engine without `instanceof` + dynamic imports.
 - `src/core/engine-factory.ts` — Engine factory with dynamic imports (`'pglite'` | `'postgres'`)
-- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly.
+- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly. v0.22.0: `searchKeyword` and `searchKeywordChunks` multiply `ts_rank` by the source-factor CASE expression at the chunk-grain level; `searchVector` becomes a two-stage CTE — inner CTE keeps `ORDER BY cc.embedding <=> vec` so HNSW stays usable, outer SELECT re-ranks by `raw_score * source_factor`. Inner LIMIT scales with offset to preserve pagination contract. As of v0.22.6.1, `initSchema()` calls `applyForwardReferenceBootstrap()` BEFORE replaying SCHEMA_SQL — probes for the specific forward-referenced state the embedded schema blob needs (`pages.source_id`, `links.link_source`, `links.origin_page_id`, `content_chunks.symbol_name`, `content_chunks.language`, `sources` FK target table) and adds only what's missing. Closes the upgrade-wedge bug class that bit users 10+ times across 6 schema versions over 2 years (#239/#243/#266/#357/#366/#374/#375/#378/#395/#396). No-op on fresh installs and modern brains.
 - `src/core/pglite-schema.ts` — PGLite-specific DDL (pgvector, pg_trgm, triggers)
-- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query.
+- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query. v0.22.0: `searchKeyword`, `searchKeywordChunks`, and `searchVector` apply source-aware ranking by inlining the source-factor CASE and `NOT (col LIKE …)` hard-exclude clause from `src/core/search/sql-ranking.ts`. `searchVector` switches to a two-stage CTE (HNSW-safe inner ORDER BY, source-boost re-rank in the outer SELECT) and carries `p.source_id` through inner→outer for v0.18 multi-source callers. v0.22.1 (#406): `_savedConfig` retains the connect config; `reconnect()` tears down + recreates the pool from saved config (called by supervisor watchdog after 3 consecutive health-check failures). `executeRaw` is a single-statement passthrough — no per-call retry (D3 dropped that as unsound for non-idempotent statements; recovery is supervisor-driven). v0.22.1 (#363, contributed by @orendi84): `connect()` applies `resolveSessionTimeouts()` from `db.ts` as connection-time startup parameters (`statement_timeout`, `idle_in_transaction_session_timeout`) so orphan pgbouncer backends can't hold locks for hours. v0.22.1 (#409, contributed by @atrevino47): `countStaleChunks()` + `listStaleChunks()` server-side-filter on `embedding IS NULL` for `embed --stale`, eliminating ~76 MB/call client-side pull on a fully-embedded brain; `upsertChunks()` resets both `embedding` AND `embedded_at` to NULL when chunk_text changes without a new embedding (consistency). As of v0.22.6.1, `initSchema()` calls `applyForwardReferenceBootstrap()` BEFORE replaying SCHEMA_SQL on the same forward-reference probe set as the PGLite engine, so old Postgres brains pinned at v0.13/v0.18/v0.19 walk forward cleanly instead of wedging on `column "..." does not exist`.
 - `src/core/utils.ts` — Shared SQL utilities extracted from postgres-engine.ts. Exports `parseEmbedding(value)` (throws on unknown input, used by migration + ingest paths where data integrity matters) and as of v0.12.3 `tryParseEmbedding(value)` (returns `null` + warns once per process, used by search/rescore paths where availability matters more than strictness).
-- `src/core/db.ts` — Connection management, schema initialization
+- `src/core/db.ts` — Connection management, schema initialization. v0.22.1 (#363, contributed by @orendi84): `resolveSessionTimeouts()` returns `statement_timeout` + `idle_in_transaction_session_timeout` (defaults: 5min each, env-overridable via `GBRAIN_STATEMENT_TIMEOUT` / `GBRAIN_IDLE_TX_TIMEOUT` / `GBRAIN_CLIENT_CHECK_INTERVAL`). Both `connect()` (module singleton) and `PostgresEngine.connect()` (worker pool) consume the result via postgres.js's `connection` option, sending GUCs as startup parameters that survive PgBouncer transaction mode (unlike the prior `setSessionDefaults` post-pool SET, kept as a back-compat no-op shim).
 - `src/commands/migrate-engine.ts` — Bidirectional engine migration (`gbrain migrate --to supabase/pglite`)
 - `src/core/import-file.ts` — importFromFile + importFromContent (chunk + embed + tags)
-- `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion)
+- `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion). v0.22.12 (#500, foundation by @wintermute via #501): `classifyErrorCode(errorMsg)` regex-based classifier with 12 codes (`SLUG_MISMATCH`, `YAML_PARSE`, `YAML_DUPLICATE_KEY`, `MISSING_OPEN`, `MISSING_CLOSE`, `NESTED_QUOTES`, `EMPTY_FRONTMATTER`, `NULL_BYTES`, `INVALID_UTF8`, `STATEMENT_TIMEOUT`, `FILE_TOO_LARGE`, `SYMLINK_NOT_ALLOWED`) plus `UNKNOWN` fallback. `summarizeFailuresByCode(failures)` returns sorted `[{code, count}]`. `code?` optional field on `SyncFailure`; backfilled at ack time on pre-v0.22.12 entries. `acknowledgeSyncFailures()` returns `AcknowledgeResult { count, summary }`. Three regexes (`MISSING_OPEN`, `MISSING_CLOSE`, `EMPTY_FRONTMATTER`) broadened to match actual `markdown.ts:159-244` validator message strings, not just the literal code-name prefix. `FILE_TOO_LARGE` covers all three production size sites in `import-file.ts:199, 352, 401`; `SYMLINK_NOT_ALLOWED` covers the rejection at `:347`. Closes the silent-skip pattern that motivated #500.
 - `src/core/storage.ts` — Pluggable storage interface (S3, Supabase Storage, local)
+- `src/core/storage-config.ts` (v0.22.11) — Storage tiering: `loadStorageConfig` reads `gbrain.yml`, normalizes deprecated keys (`git_tracked` / `supabase_only`) to canonical (`db_tracked` / `db_only`) with once-per-process deprecation warning, and runs `normalizeAndValidateStorageConfig` (auto-fixes missing trailing `/`, throws `StorageConfigError` on tier overlap). Path-segment matcher: `media/x/` does NOT match `media/xerox/foo`. Replaces gray-matter (broken on delimiter-less YAML) with a dedicated parser for the `gbrain.yml` shape.
+- `src/core/disk-walk.ts` (v0.22.11) — `walkBrainRepo(repoPath)` returns `Map<slug, {size, mtimeMs}>` from one recursive `readdirSync`. Skips dot-dirs, `node_modules`, non-`.md` files. Used by `gbrain storage status` to replace per-page `existsSync + statSync` (~400K syscalls on 200K-page brains → tens).
+- `src/commands/storage.ts` (v0.22.11) — `gbrain storage status [--repo P] [--json]`. Split into pure data (`getStorageStatus`) + JSON formatter + human formatter (ASCII-only per D10) matching the `orphans.ts` pattern. `PageCountsByTier` and `DiskUsageByTier` are distinct nominal types so swaps fail at compile time.
+- `gbrain.yml` (brain repo root, v0.22.11) — Optional storage tiering config. Top-level `storage:` section with `db_tracked:` and `db_only:` array-valued keys. `gbrain sync` auto-manages `.gitignore` for `db_only` paths on successful sync (skips on dry-run, blocked-by-failures, submodule context, or `GBRAIN_NO_GITIGNORE=1`). `gbrain export --restore-only [--repo P] [--type T] [--slug-prefix S]` repopulates missing `db_only` files from the database.
 - `src/core/supabase-admin.ts` — Supabase admin API (project discovery, pgvector check)
 - `src/core/file-resolver.ts` — File resolution with fallback chain (local -> .redirect.yaml -> .redirect -> .supabase)
-- `src/core/chunkers/` — 3-tier chunking (recursive, semantic, LLM-guided)
-- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup
+- `src/core/chunkers/` — 3-tier chunking (recursive, semantic, LLM-guided). v0.19.0 adds `code.ts` — tree-sitter-based semantic chunker for 29 languages with embedded-asset WASMs (`src/assets/wasm/`), `@dqbd/tiktoken` cl100k_base tokenizer, small-sibling merging. `CHUNKER_VERSION` constant folded into `importCodeFile`'s `content_hash` so chunker shape changes force clean re-chunks across releases.
+- `src/core/errors.ts` (v0.19.0) — `StructuredAgentError` + `buildError` + `serializeError`. Every new v0.19.0 agent-facing surface (code-def, code-refs, usage errors) uses this envelope; matches v0.17.0 `CycleReport.PhaseResult.error` shape.
+- `src/assets/wasm/` (v0.19.0) — 36 tree-sitter grammar WASMs + tree-sitter runtime. Committed to the repo so `bun --compile` embeds them deterministically via `import path from ... with { type: 'file' }`. The CI guard `scripts/check-wasm-embedded.sh` fails the build if the compiled binary ever silently falls through to recursive chunks.
+- `src/commands/code-def.ts` + `src/commands/code-refs.ts` (v0.19.0) — symbol definition + references lookup. Query `content_chunks.symbol_name` or chunk_text ILIKE with `page_kind='code'` filter. Auto-JSON when stdout is not a TTY (gh-CLI convention). Bypass the standard `searchKeyword` `DISTINCT ON (slug)` collapse so multiple call-sites from the same file surface.
+- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup. As of v0.22.0, `searchKeyword` / `searchKeywordChunks` / `searchVector` apply source-aware ranking at the SQL layer (curated content like `originals/`, `concepts/`, `writing/` outranks bulk content like `wintermute/chat/`, `daily/`, `media/x/`). `searchVector` uses a two-stage CTE so source-boost re-ranking doesn't kill the HNSW index. Hard-exclude prefixes (`test/`, `archive/`, `attachments/`, `.raw/` by default) filter at retrieval, not post-rank. Both gates honor `detail !== 'high'` so temporal queries surface chat pages normally.
 - `src/core/search/intent.ts` — Query intent classifier (entity/temporal/event/general → auto-selects detail level)
 - `src/core/search/eval.ts` — Retrieval eval harness: P@k, R@k, MRR, nDCG@k metrics + runEval() orchestrator
+- `src/core/search/source-boost.ts` (v0.22.0) — Source-type boost map keyed by slug prefix. `DEFAULT_SOURCE_BOOSTS` (originals/ 1.5, concepts/ 1.3, writing/ 1.4, people/companies/deals/ 1.2, daily/ 0.8, media/x/ 0.7, wintermute/chat/ 0.5) and `DEFAULT_HARD_EXCLUDES` (test/, archive/, attachments/, .raw/). `parseSourceBoostEnv` / `parseHardExcludesEnv` parse comma-separated `prefix:factor` pairs from `GBRAIN_SOURCE_BOOST` / `GBRAIN_SEARCH_EXCLUDE` env vars. `resolveBoostMap` and `resolveHardExcludes` merge defaults + env + caller `SearchOpts.exclude_slug_prefixes`/`include_slug_prefixes`.
+- `src/core/search/sql-ranking.ts` (v0.22.0) — Pure SQL string builders. `buildSourceFactorCase(slugColumn, boostMap, detail)` emits a CASE expression with longest-prefix-match wins (returns literal `'1.0'` when `detail === 'high'` for temporal-bypass parity with COMPILED_TRUTH_BOOST). `buildHardExcludeClause(slugColumn, prefixes)` emits `NOT (col LIKE 'p1%' OR col LIKE 'p2%')` — OR-chain wrapped in NOT, NOT `NOT LIKE ALL/ANY` (those quantifiers don't express set-exclusion). LIKE meta-character escape covers all three of `%`, `_`, AND `\` (backslash matters because it's Postgres LIKE's default escape char). Single-quote doubling on SQL string literals so injection-style inputs are inert text.
 - `src/commands/eval.ts` — `gbrain eval` command: single-run table + A/B config comparison
 - `src/core/embedding.ts` — OpenAI text-embedding-3-large, batch, retry, backoff
 - `src/core/check-resolvable.ts` — Resolver validation: reachability, MECE overlap, DRY checks, structured fix objects. v0.14.1: `CROSS_CUTTING_PATTERNS.conventions` is an array (notability gate accepts both `conventions/quality.md` and `_brain-filing-rules.md`). New `extractDelegationTargets()` parses `> **Convention:**`, `> **Filing rule:**`, and inline backtick references. DRY suppression is proximity-based via `DRY_PROXIMITY_LINES = 40`.
@@ -48,9 +57,9 @@ strict behavior when unset.
 - `src/core/resolver-filenames.ts` (v0.19) — central list of accepted routing filenames (`RESOLVER.md`, `AGENTS.md`). Shared by `findRepoRoot`, `check-resolvable`, and skillpack install so every code path walks the same fallback chain.
 - `src/commands/skillify.ts` + `src/core/skillify/{generator,templates}.ts` (v0.19) — `gbrain skillify scaffold <name>` creates all stubs for a new skill in one command: SKILL.md, script, tests, routing-eval.jsonl, resolver entry, filing-rules pointer. `gbrain skillify check <script>` runs the 10-step checklist (LLM evals, routing evals, check-resolvable gate, filing audit) against a candidate skill before it lands.
 - `src/commands/skillify-check.ts` (v0.19) — `gbrain skillpack-check` agent-readable health report. Exit 0/1/2 for CI pipeline gating; JSON for debugging. Wraps `check-resolvable --json`, `doctor --json`, and migration ledger into one payload so agents can decide whether a human action is required.
-- `src/commands/skillpack.ts` + `src/core/skillpack/{bundle,installer}.ts` (v0.19) — `gbrain skillpack install` drops gbrain's curated 25-skill bundle into a host workspace, managed-block style. Never clobbers local edits; tracks a skill manifest so subsequent `install --update` diffs cleanly. Bundle builder (`skillpack/bundle.ts`) packages the set from `skills/` into a versioned payload.
+- `src/commands/skillpack.ts` + `src/core/skillpack/{bundle,installer}.ts` (v0.19) — `gbrain skillpack install` drops gbrain's curated 25-skill bundle into a host workspace, managed-block style. Never clobbers local edits; tracks a skill manifest so subsequent `install --update` diffs cleanly. Bundle builder (`skillpack/bundle.ts`) packages the set from `skills/` into a versioned payload. **v0.24.0:** managed block embeds a `<!-- gbrain:skillpack:manifest cumulative-slugs="..." version="..." -->` receipt inside the fence. Per-skill installs accumulate via `union(prior_receipt, this_call)`; `install --all` is the only path that prunes (drops slugs no longer in the bundle). Rows inside the fence whose slug is in neither the new cumulative set nor the bundle survive as user-added with a stderr `[skillpack] unknown row in managed block: "<slug>" — Investigate: ...` warning. Pre-v0.24 fences upgrade silently on first install (extracted slugs become the prior cumulative set).
 - `src/core/skill-manifest.ts` (v0.19) — parser for `skill-manifest.json` records. Used by skillpack installer to detect drift between the shipped bundle and the user's local edits, so updates merge instead of overwriting.
-- `src/commands/routing-eval.ts` + `src/core/routing-eval.ts` (v0.19) — `gbrain routing-eval` catches user phrasings that route to the wrong skill. Reads `skills/<name>/routing-eval.jsonl` fixtures (`{intent, expected_skill, ambiguous_with?}`). Structural layer runs in `check-resolvable` by default (zero API cost); `--llm` opts into a Haiku tie-break layer for CI. False positives surface before users hit them.
+- `src/commands/routing-eval.ts` + `src/core/routing-eval.ts` (v0.19) — `gbrain routing-eval` catches user phrasings that route to the wrong skill. Reads `skills/<name>/routing-eval.jsonl` fixtures (`{intent, expected_skill, ambiguous_with?}`). Structural layer runs in `check-resolvable` by default (zero API cost). The `--llm` flag is accepted as a placeholder for a future LLM tie-break layer; in v0.24.0 it emits a stderr notice and runs structural only. False positives surface before users hit them.
 - `src/core/filing-audit.ts` + `skills/_brain-filing-rules.json` (v0.19) — Check 6 of `check-resolvable`. Parses new `writes_pages:` / `writes_to:` frontmatter on skills and audits their filing claims against the filing-rules JSON. Warning-only in v0.19, upgrades to error in v0.20.
 - `src/core/dry-fix.ts` — `gbrain doctor --fix` engine. `autoFixDryViolations(fixes, {dryRun})` rewrites inlined rules to `> **Convention:** see [path](path).` callouts via three shape-aware expanders (bullet / blockquote / paragraph). Five guards: working-tree-dirty (`getWorkingTreeStatus()` returns 3-state `'clean' | 'dirty' | 'not_a_repo'`), no-git-backup, inside-code-fence, already-delegated (40-line proximity, consistent with detector), ambiguous-multi-match, block-is-callout. `execFileSync` array args (no shell — no injection surface). EOF newline preserved.
 - `src/core/backoff.ts` — Adaptive load-aware throttling: CPU/memory checks, exponential backoff, active hours multiplier
@@ -58,16 +67,19 @@ strict behavior when unset.
 - `src/core/transcription.ts` — Audio transcription: Groq Whisper (default), OpenAI fallback, ffmpeg segmentation for >25MB
 - `src/core/enrichment-service.ts` — Global enrichment service: entity slug generation, tier auto-escalation, batch throttling
 - `src/core/data-research.ts` — Recipe validation, field extraction (MRR/ARR regex), dedup, tracker parsing, HTML stripping
-- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs).
+- `src/commands/embed.ts` — `gbrain embed [--stale|--all] [--slugs ...]`. v0.22.1 (#409, contributed by @atrevino47): `--stale` path now starts with `engine.countStaleChunks()` (single SELECT count(*) WHERE embedding IS NULL, ~50 bytes wire). On a fully-embedded brain that's a 1-line short-circuit — no further reads. When stale chunks exist, `engine.listStaleChunks()` returns just the chunks needing embeddings (slug + chunk_index + chunk_text + metadata, no `vector(1536)` payload). Caller groups by slug, embeds via OpenAI, re-upserts via `upsertChunks`. Replaces the prior page-walk that pulled every chunk's embedding column over the wire and discarded most.
+- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs). v0.22.1 (#417): `ExtractOpts.slugs?: string[]` enables incremental extract — when set, `extractForSlugs()` reads ONLY those slugs' files (single combined links+timeline pass) instead of the full directory walk. CLI `gbrain extract` keeps full-walk behavior; the cycle path threads sync's `pagesAffected` through. `walkMarkdownFiles(brainDir)` still runs at line 455 to build `allSlugs` for link resolution — see `TODOS.md` for replacing it with `engine.getAllSlugs()`.
 - `src/commands/graph-query.ts` — `gbrain graph-query <slug> [--type T] [--depth N] [--direction in|out|both]`: typed-edge relationship traversal (renders indented tree)
 - `src/core/link-extraction.ts` — shared library for the v0.12.0 graph layer. extractEntityRefs (canonical, replaces backlinks.ts duplicate) matches both `[Name](people/slug)` markdown links and Obsidian `[[people/slug|Name]]` wikilinks as of v0.12.3. extractPageLinks, inferLinkType heuristics (attended/works_at/invested_in/founded/advises/source/mentions), parseTimelineEntries, isAutoLinkEnabled config helper. `DIR_PATTERN` covers `people`, `companies`, `deals`, `topics`, `concepts`, `projects`, `entities`, `tech`, `finance`, `personal`, `openclaw`. Used by extract.ts, operations.ts auto-link post-hook, and backlinks.ts.
 - `src/core/minions/` — Minions job queue: BullMQ-inspired, Postgres-native (queue, worker, backoff, types, protected-names, quiet-hours, stagger, handlers/shell).
-- `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe). v0.14.1 #219: `add()` plumbs `max_stalled` through with a `[1, 100]` clamp; omitted values let the schema DEFAULT (5) kick in.
-- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't.
+- `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe). v0.14.1 #219: `add()` plumbs `max_stalled` through with a `[1, 100]` clamp; omitted values let the schema DEFAULT (5) kick in. v0.19.0: `handleWallClockTimeouts(lockDurationMs)` is Layer 3 kill shot for jobs where `FOR UPDATE SKIP LOCKED` stall detection and the timeout sweep both fail to evict (wedged worker holding a row lock via a pending transaction). v0.19.1: `maxWaiting` coalesce path now uses `pg_advisory_xact_lock` keyed on `(name, queue)` to serialize concurrent submits for the same key, and filters on `queue` in addition to `name` so cross-queue same-name jobs don't suppress each other.
+- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't. v0.22.1 (#403): per-job timeout fires `abort.abort(new Error('timeout'))` then a 30-second grace-then-evict safety net force-evicts the job from `inFlight` and marks it dead in DB if the handler ignores the abort signal — frees the slot even when a handler wedges (the 98-waiting-0-active prod incident driver).
+- `src/core/minions/supervisor.ts` — MinionSupervisor process manager. Spawns `gbrain jobs work` as a child, restarts on crash with exponential backoff, periodic health check. v0.22.1 (#406): `consecutiveHealthFailures` counter; on 3 consecutive failures emits `health_warn` with `reason: 'db_connection_degraded'` and calls `engine.reconnect()` to swap in a fresh pool, then resets the counter. Worker exit classifier emits `likely_cause` field on `worker_exited` events: `oom_or_external_kill` (SIGKILL), `graceful_shutdown` (SIGTERM), `runtime_error` (code 1), `clean_exit` (code 0), `unknown`.
 - `src/core/minions/types.ts` — `MinionJobInput` + `MinionJobStatus` + handler context types. `MinionJobInput.max_stalled` (new in v0.14.1) is optional; omitted values let the schema DEFAULT (5) kick in, provided values are clamped to `[1, 100]`.
 - `src/core/minions/protected-names.ts` — side-effect-free constant module exporting `PROTECTED_JOB_NAMES` + `isProtectedJobName()`. Kept pure so queue core can import without loading handler modules.
 - `src/core/minions/handlers/shell.ts` — `shell` job handler. Spawns `/bin/sh -c cmd` (absolute path, PATH-override-safe) or `argv[0] argv[1..]` (no shell). Env allowlist: `PATH, HOME, USER, LANG, TZ, NODE_ENV` + caller `env:` overrides. UTF-8-safe stdout/stderr tail via `string_decoder.StringDecoder`. Abort (either `ctx.signal` or `ctx.shutdownSignal`) fires SIGTERM → 5s grace → SIGKILL on child. Requires `GBRAIN_ALLOW_SHELL_JOBS=1` on worker (gated by `registerBuiltinHandlers`).
 - `src/core/minions/handlers/shell-audit.ts` — per-submission JSONL audit trail at `~/.gbrain/audit/shell-jobs-YYYY-Www.jsonl` (ISO-week rotation; override via `GBRAIN_AUDIT_DIR`). Best-effort: `mkdirSync(recursive)` + `appendFileSync`; failures logged to stderr, submission not blocked. Logs cmd (first 80 chars) or argv (JSON array). Never logs env values.
+- `src/core/minions/backpressure-audit.ts` (v0.19.1) — sibling of shell-audit.ts for `maxWaiting` coalesce events. JSONL at `~/.gbrain/audit/backpressure-YYYY-Www.jsonl`. Fires one line per coalesce with `(queue, name, waiting_count, max_waiting, returned_job_id, ts)`. Closes the silent-drop vector the v0.19.0 maxWaiting guard introduced.
 - `src/core/minions/handlers/subagent.ts` (v0.15) — LLM-loop handler. Two-phase tool persistence (pending → complete/failed), replay reconciliation for mid-dispatch crashes, dual-signal abort (`ctx.signal` + `ctx.shutdownSignal`), Anthropic prompt caching on system + tool defs. `makeSubagentHandler({engine, client?, ...})` factory; `MessagesClient` is an injectable interface the real SDK implements structurally. Throws `RateLeaseUnavailableError` (renewable) when rate-lease capacity is full.
 - `src/core/minions/handlers/subagent-aggregator.ts` (v0.15) — `subagent_aggregator` handler. Claims AFTER all children resolve (queue changes guarantee every terminal child posts a `child_done` inbox message with outcome). Reads inbox via `ctx.readInbox()`, builds deterministic mixed-outcome markdown summary. No LLM call in v0.15.
 - `src/core/minions/handlers/subagent-audit.ts` (v0.15) — JSONL audit + heartbeat writer at `~/.gbrain/audit/subagent-jobs-YYYY-Www.jsonl`. Events: `submission` (one line per submit) + `heartbeat` (per turn boundary: `llm_call_started | llm_call_completed | tool_called | tool_result | tool_failed`). Never logs prompts or tool inputs. `readSubagentAuditForJob(jobId, {sinceIso})` is the readback path for `gbrain agent logs`.
@@ -75,30 +87,46 @@ strict behavior when unset.
 - `src/core/minions/wait-for-completion.ts` (v0.15) — poll-until-terminal helper for CLI callers. `TimeoutError` does NOT cancel the job; `AbortSignal` exits without throwing. Default `pollMs`: 1000 on Postgres, 250 on PGLite inline.
 - `src/core/minions/transcript.ts` (v0.15) — renders `subagent_messages` + `subagent_tool_executions` to markdown. Tool rows splice under their owning assistant `tool_use` by `tool_use_id`. UTF-8-safe truncation; unknown block types fall through to fenced JSON.
 - `src/core/minions/plugin-loader.ts` (v0.15) — `GBRAIN_PLUGIN_PATH` discovery. Absolute paths only, left-wins collision, `gbrain.plugin.json` with `plugin_version: "gbrain-plugin-v1"`, plugins ship DEFS only (no new tools), `allowed_tools:` validated at load time against the derived registry.
-- `src/core/minions/tools/brain-allowlist.ts` (v0.15) — derives subagent tool registry from `src/core/operations.ts`. 11-name allow-list: `query`, `search`, `get_page`, `list_pages`, `file_list`, `file_url`, `get_backlinks`, `traverse_graph`, `resolve_slugs`, `get_ingest_log`, `put_page`. `put_page` schema is namespace-wrapped per subagent (`^wiki/agents/<subagentId>/.+`); the `put_page` op's server-side check is the authoritative gate via `ctx.viaSubagent` fail-closed.
+- `src/core/minions/tools/brain-allowlist.ts` (v0.15, extended v0.23) — derives subagent tool registry from `src/core/operations.ts`. 11-name allow-list. By default `put_page` schema is namespace-wrapped per subagent (`^wiki/agents/<subagentId>/.+`). **v0.23 trusted-workspace path:** when `BuildBrainToolsOpts.allowedSlugPrefixes` is set, the put_page schema instead describes the prefix list to the model and the OperationContext is threaded with `allowedSlugPrefixes`. Trust comes from `PROTECTED_JOB_NAMES` gating subagent submission — MCP cannot reach this field. Only cycle.ts (synthesize/patterns) and direct CLI submitters set it.
 - `src/mcp/tool-defs.ts` (v0.15) — extracted `buildToolDefs(ops)` helper. MCP server + subagent tool registry both call it; byte-for-byte equivalence pinned by `test/mcp-tool-defs.test.ts`.
 - `src/core/minions/attachments.ts` — Attachment validation (path traversal, null byte, oversize, base64, duplicate detection)
 - `src/commands/agent.ts` (v0.16) — `gbrain agent run <prompt> [flags]` CLI. Submits `subagent` (or N children + 1 aggregator) under `{allowProtectedSubmit: true}`. Single-entry `--fanout-manifest` short-circuits. Children get `on_child_fail: 'continue'` + `max_stalled: 3`. `--follow` is the default on TTY; streams logs + polls `waitForCompletion` in parallel. Ctrl-C detaches, does not cancel.
 - `src/commands/agent-logs.ts` (v0.16) — `gbrain agent logs <job> [--follow] [--since]`. Merges JSONL heartbeat audit + `subagent_messages` into a chronological timeline. `parseSince` accepts ISO-8601 or relative (`5m`, `1h`, `2d`). Transcript tail renders only for terminal jobs.
-- `src/commands/jobs.ts` — `gbrain jobs` CLI subcommands + `gbrain jobs work` daemon. v0.13.1 surfaces the full `MinionJobInput` retry/backoff/timeout/idempotency surface as first-class CLI flags on `jobs submit`: `--max-stalled`, `--backoff-type fixed|exponential`, `--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key`. `jobs smoke --sigkill-rescue` is the opt-in regression guard for #219. v0.16 wires `registerBuiltinHandlers` to always register `subagent` + `subagent_aggregator` (no env flag — `ANTHROPIC_API_KEY` is the natural cost gate, trust is via `PROTECTED_JOB_NAMES`) and loads `GBRAIN_PLUGIN_PATH` plugins at worker startup with a loud startup-line per plugin. `shell` handler still gated by `GBRAIN_ALLOW_SHELL_JOBS=1` (RCE surface, separate concern).
+- `src/commands/jobs.ts` — `gbrain jobs` CLI subcommands + `gbrain jobs work` daemon. v0.13.1 surfaces the full `MinionJobInput` retry/backoff/timeout/idempotency surface as first-class CLI flags on `jobs submit`: `--max-stalled`, `--backoff-type fixed|exponential`, `--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key`. `jobs smoke --sigkill-rescue` is the opt-in regression guard for #219. v0.16 wires `registerBuiltinHandlers` to always register `subagent` + `subagent_aggregator` (no env flag — `ANTHROPIC_API_KEY` is the natural cost gate, trust is via `PROTECTED_JOB_NAMES`) and loads `GBRAIN_PLUGIN_PATH` plugins at worker startup with a loud startup-line per plugin. `shell` handler still gated by `GBRAIN_ALLOW_SHELL_JOBS=1` (RCE surface, separate concern). v0.22.10 (#521): the `autopilot-cycle` handler now forwards `job.data.phases` to `runCycle` (was previously discarded — caller-supplied phase selection silently became a full cycle). Phases are validated against `ALL_PHASES` from `src/core/cycle.ts`; invalid names are filtered out and an empty/missing array falls back to the default 6-phase cycle. v0.22.13 (PR #490 CODEX-1+CODEX-4): `sync` handler now resolves `sourceId` at entry by looking up `sources.local_path` (mirrors `cycle.ts:480`'s autopilot fix from PR #475) so multi-source brains read the per-source `last_commit` anchor instead of the global config key. Concurrency routed through the shared `autoConcurrency()` policy in `src/core/sync-concurrency.ts` instead of the prior hardcoded `4`; PGLite stays serial. `noEmbed` default is `true` (embed is a separate job — submit `gbrain embed --stale` after sync, or rely on the autopilot cycle's embed phase).
 - `src/commands/features.ts` — `gbrain features --json --auto-fix`: usage scan + feature adoption salesman
 - `src/commands/autopilot.ts` — `gbrain autopilot --install`: self-maintaining brain daemon (sync+extract+embed)
-- `src/mcp/server.ts` — MCP stdio server (generated from operations)
-- `src/commands/auth.ts` — Standalone token management (create/list/revoke/test)
+- `src/mcp/server.ts` — MCP stdio server (generated from operations). v0.22.7: tool-call handler delegates to `dispatchToolCall` from `src/mcp/dispatch.ts` so stdio + HTTP transports share one validation, context-build, and error-format path.
+- `src/mcp/dispatch.ts` (v0.22.7) — Shared tool-call dispatch consumed by both stdio (`server.ts`) and HTTP (`http-transport.ts`). Exports `dispatchToolCall(engine, name, params, opts)`, `buildOperationContext(engine, params, opts)`, and `validateParams(op, params)`. Single source of truth for `(ctx, params)` handler arg order and the 5-field `OperationContext` shape (engine + config + logger + dryRun + remote). Defaults to `remote: true` (untrusted); local CLI callers pass `remote: false`. Closed F1 (reversed handler args) + F2 (incomplete OperationContext) + F3 (no param validation) drift bugs in the original v0.22.5 HTTP transport.
+- `src/mcp/rate-limit.ts` (v0.22.7) — Bounded-LRU token-bucket limiter for `gbrain serve --http`. `buildDefaultLimiters()` returns the two-bucket pipeline used by http-transport: pre-auth IP (default 30/60s, fires BEFORE the DB lookup so brute-force load against `access_tokens` is actually capped) + post-auth token-id (default 60/60s). Tracks `lastTouchedMs` separately from `lastRefillMs` so an exhausted key can't be reset by hammering past the TTL. LRU cap (default 10K keys) bounds memory under attacker-controlled key growth; TTL prune at 2× window evicts abandoned buckets.
+- `src/mcp/http-transport.ts` (v0.22.7, rewrite) — `gbrain serve --http` HTTP transport. Postgres-only — fails fast at startup on PGLite (the `access_tokens` table only exists on Postgres). Bearer auth against SHA-256 hashes in `access_tokens`. CORS default-deny via `GBRAIN_HTTP_CORS_ORIGIN` allowlist. Body cap stream-counted (1 MiB default via `GBRAIN_HTTP_MAX_BODY_BYTES`) so chunked transfers without Content-Length still hit the cap. `last_used_at` SQL-level debounce (one UPDATE per token per 60s). Per-request audit row in `mcp_request_log` with token_name + operation + status + latency. Optional `GBRAIN_HTTP_TRUST_PROXY=1` honors `X-Forwarded-For` — only safe when bound to a private interface AND the proxy strips client-supplied XFF (otherwise enables IP spoofing past the pre-auth rate limit). `/health` does `SELECT 1` against Postgres and returns 503 + `status:unhealthy` when the DB is unreachable so orchestration doesn't see green pods while clients get misleading 401s. Replaces the standalone OAuth wrapper that was vulnerable to unauthenticated client registration.
+- `src/commands/auth.ts` — Token management for the HTTP transport. `gbrain auth create/list/revoke/test`. As of v0.22.7 wired into the main CLI (`src/cli.ts`); also runs standalone via `bun run src/commands/auth.ts ...` for environments without a compiled binary. Tokens stored as SHA-256 hashes in `access_tokens` (Postgres-only).
 - `src/commands/upgrade.ts` — Self-update CLI. `runPostUpgrade()` enumerates migrations from the TS registry (src/commands/migrations/index.ts) and tail-calls `runApplyMigrations(['--yes', '--non-interactive'])` so the mechanical side of every outstanding migration runs unconditionally.
 - `src/commands/migrations/` — TS migration registry (compiled into the binary; no filesystem walk of `skills/migrations/*.md` needed at runtime). `index.ts` lists migrations in semver order. `v0_11_0.ts` = Minions adoption orchestrator (8 phases). `v0_12_0.ts` = Knowledge Graph auto-wire orchestrator (5 phases: schema → config check → backfill links → backfill timeline → verify). `phaseASchema` has a 600s timeout (bumped from 60s in v0.12.1 for duplicate-heavy brains). `v0_12_2.ts` = JSONB double-encode repair orchestrator (4 phases: schema → repair-jsonb → verify → record). `v0_14_0.ts` = shell-jobs + autopilot cooperative (2 phases: schema ALTER minion_jobs.max_stalled SET DEFAULT 3 — superseded by v0.14.3's schema-level DEFAULT 5 + UPDATE backfill; pending-host-work ping for skills/migrations/v0.14.0.md). All orchestrators are idempotent and resumable from `partial` status. As of v0.14.2 (Bug 3), the RUNNER owns all ledger writes — orchestrators return `OrchestratorResult` and `apply-migrations.ts` persists a canonical `{version, status, phases}` shape after return. Orchestrators no longer call `appendCompletedMigration` directly. `statusForVersion` prefers `complete` over `partial` (never regresses). 3 consecutive partials → wedged → `--force-retry <version>` writes a `'retry'` reset marker. v0.14.3 (fix wave) ships schema-only migrations v14 (`pages_updated_at_index`) + v15 (`minion_jobs_max_stalled_default_5` with UPDATE backfill) via the `MIGRATIONS` array in `src/core/migrate.ts` — no orchestrator phases needed.
 - `src/commands/repair-jsonb.ts` — `gbrain repair-jsonb [--dry-run] [--json]`: rewrites `jsonb_typeof='string'` rows in place across 5 affected columns (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter). Fixes v0.12.0 double-encode bug on Postgres; PGLite no-ops. Idempotent.
 - `src/commands/orphans.ts` — `gbrain orphans [--json] [--count] [--include-pseudo]`: surfaces pages with zero inbound wikilinks, grouped by domain. Auto-generated/raw/pseudo pages filtered by default. Also exposed as `find_orphans` MCP operation. Shipped in v0.12.3 (contributed by @knee5).
-- `src/commands/doctor.ts` — `gbrain doctor [--json] [--fast] [--fix] [--dry-run] [--index-audit]`: health checks. v0.12.3 added `jsonb_integrity` + `markdown_body_completeness` reliability checks. v0.14.1: `--fix` delegates inlined cross-cutting rules to `> **Convention:** see [path](path).` callouts (pipes DRY violations into `src/core/dry-fix.ts`); `--fix --dry-run` previews without writing. v0.14.2: `schema_version` check fails loudly when `version=0` (migrations never ran — the #218 `bun install -g` signature) and routes users to `gbrain apply-migrations --yes`; new opt-in `--index-audit` flag (Postgres-only) reports zero-scan indexes from `pg_stat_user_indexes` (informational only, no auto-drop). v0.15.2: every DB check is wrapped in a progress phase; `markdown_body_completeness` runs under a 1s heartbeat timer so 10+ min scans are observable on 50K-page brains. Fix hints point at `gbrain repair-jsonb`, `gbrain sync --force`, and `gbrain apply-migrations`.
-- `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). v0.14.2 extended the `Migration` interface with `sqlFor?: { postgres?, pglite? }` (engine-specific SQL overrides `sql`) and `transaction?: boolean` (set to false for `CREATE INDEX CONCURRENTLY`, which Postgres refuses inside a transaction; ignored on PGLite since it has no concurrent writers). Migration v14 (fix wave) uses a handler branching on `engine.kind` to run CONCURRENTLY on Postgres (with a pre-drop of any invalid remnant via `pg_index.indisvalid`) and plain `CREATE INDEX` on PGLite. v15 bumps `minion_jobs.max_stalled` default 1→5 and backfills existing non-terminal rows.
+- `src/commands/integrity.ts` — `gbrain integrity check|auto|review|extract`: bare-tweet detection, dead-link detection, three-bucket repair (auto-repair / review-queue / skip). `scanIntegrity()` is the shared library function called from `gbrain doctor` (sampled at limit=500) and `cmdCheck` (full scan). v0.22.8: batch-load fast path on Postgres uses `SELECT DISTINCT ON (slug)` in a single SQL query to fix the PgBouncer round-trip timeout (60s → ~6s) while preserving `engine.getAllSlugs()`'s `Set<string>` semantics on multi-source brains. Gated by `engine.kind === 'postgres'` at the call site so PGLite never enters batch; fallback `catch` logs at `GBRAIN_DEBUG=1` so real Postgres errors are diagnosable.
+- `src/commands/doctor.ts` — `gbrain doctor [--json] [--fast] [--fix] [--dry-run] [--index-audit]`: health checks. v0.12.3 added `jsonb_integrity` + `markdown_body_completeness` reliability checks. v0.14.1: `--fix` delegates inlined cross-cutting rules to `> **Convention:** see [path](path).` callouts (pipes DRY violations into `src/core/dry-fix.ts`); `--fix --dry-run` previews without writing. v0.14.2: `schema_version` check fails loudly when `version=0` (migrations never ran — the #218 `bun install -g` signature) and routes users to `gbrain apply-migrations --yes`; new opt-in `--index-audit` flag (Postgres-only) reports zero-scan indexes from `pg_stat_user_indexes` (informational only, no auto-drop). v0.15.2: every DB check is wrapped in a progress phase; `markdown_body_completeness` runs under a 1s heartbeat timer so 10+ min scans are observable on 50K-page brains. v0.19.1 added `queue_health` (Postgres-only) with two subchecks: stalled-forever active jobs (started_at > 1h) and waiting-depth-per-name > threshold (default 10, override via `GBRAIN_QUEUE_WAITING_THRESHOLD`). Worker-heartbeat subcheck intentionally deferred to follow-up B7 because it needs a `minion_workers` table to produce ground-truth signal. Fix hints point at `gbrain repair-jsonb`, `gbrain sync --force`, `gbrain apply-migrations`, and `gbrain jobs get/cancel <id>`. v0.22.12 (#500): `sync_failures` check shows `[CODE=N, ...]` breakdown for both unacked entries (warn) and acked-historical entries (ok), surfacing systemic failure modes (`SLUG_MISMATCH=2685`) instead of a bare count.
+- `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). v0.14.2 extended the `Migration` interface with `sqlFor?: { postgres?, pglite? }` (engine-specific SQL overrides `sql`) and `transaction?: boolean` (set to false for `CREATE INDEX CONCURRENTLY`, which Postgres refuses inside a transaction; ignored on PGLite since it has no concurrent writers). Migration v14 (fix wave) uses a handler branching on `engine.kind` to run CONCURRENTLY on Postgres (with a pre-drop of any invalid remnant via `pg_index.indisvalid`) and plain `CREATE INDEX` on PGLite. v15 bumps `minion_jobs.max_stalled` default 1→5 and backfills existing non-terminal rows. v0.22.6.1: migration v24 (`rls_backfill_missing_tables`) uses `sqlFor: { pglite: '' }` to no-op on PGLite — PGLite has no RLS engine and is single-tenant by definition, and the v24 ALTERs target subagent tables that don't exist in pglite-schema.ts. Closes #395 (contributed by @jdcastro2). **v30 (v0.23):** creates `dream_verdicts (file_path TEXT, content_hash TEXT, worth_processing BOOL, reasons JSONB, judged_at TIMESTAMPTZ, PK(file_path, content_hash))`. RLS-enabled when running as a BYPASSRLS role. The synthesize phase reads/writes this table to avoid re-judging on backfill re-runs.
 - `src/core/progress.ts` — Shared bulk-action progress reporter. Writes to stderr. Modes: `auto` (TTY: `\r`-rewriting; non-TTY: plain lines), `human`, `json` (JSONL), `quiet`. Rate-gated by `minIntervalMs` and `minItems`. `startHeartbeat(reporter, note)` helper for single long queries. `child()` composes phase paths. Singleton SIGINT/SIGTERM coordinator emits `abort` events for every live phase. EPIPE defense on both sync throws and stream `'error'` events. Zero dependencies. Introduced in v0.15.2.
 - `src/core/cli-options.ts` — Global CLI flag parser. `parseGlobalFlags(argv)` returns `{cliOpts, rest}` with `--quiet` / `--progress-json` / `--progress-interval=<ms>` stripped. `getCliOptions()` / `setCliOptions()` expose a module-level singleton so commands reach the resolved flags without parameter threading. `cliOptsToProgressOptions()` maps to reporter options. `childGlobalFlags()` returns the flag suffix to append to `execSync('gbrain ...')` calls in migration orchestrators. `OperationContext.cliOpts` extends shared-op dispatch for MCP callers.
-- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive. `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes 6 phases in semantically-driven order (lint → backlinks → sync → extract → embed → orphans). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler (`src/commands/jobs.ts`). One source of truth for what the brain does overnight. Coordination via `gbrain_cycle_locks` DB table (TTL-based; works through PgBouncer transaction pooling, unlike session-scoped `pg_try_advisory_lock`) + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite / engine=null mode. `CycleReport.schema_version: "1"` is the stable agent-consumable shape. `PhaseResult.error: { class, code, message, hint?, docs_url? }` is Stripe-API-tier structured failure info. `yieldBetweenPhases` hook awaited between every phase — Minions handler uses this to renew its job lock and prevent v0.14 stall-death regression. Engine nullable: filesystem phases (lint, backlinks) run without DB; DB phases skip with `status: "skipped", reason: "no_database"`. Lock-skip: read-only phase selections (`--phase orphans`) bypass the cycle lock.
-- `src/commands/dream.ts` — v0.17 `gbrain dream` CLI. ~80-line thin alias over `runCycle`. brainDir resolution requires explicit `--dir` OR `sync.repo_path` config (no more walk-up-cwd-for-.git footgun). Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`. Exit code 1 on status=failed (partial/warn not fatal — don't page on warnings).
+- `src/core/db-lock.ts` (v0.22.13) — generic `tryAcquireDbLock(engine, lockId, ttlMinutes)` over the existing `gbrain_cycle_locks` table. Parameterized lock id so different scopes can nest cleanly: `gbrain-cycle` for the broad cycle (held by `cycle.ts`) and `gbrain-sync` (`SYNC_LOCK_ID` constant) for `performSync`'s narrower writer window. Same UPSERT-with-TTL semantics as the prior cycle-only helper, just generalized. Survives PgBouncer transaction pooling (unlike session-scoped `pg_try_advisory_lock`); crashed holders auto-release once their TTL expires.
+- `src/core/sync-concurrency.ts` (v0.22.13) — single source of truth for the parallel-sync policy. Exports `autoConcurrency(engine, fileCount, override?)` (PGLite always serial; explicit override clamped to >=1; auto path returns `DEFAULT_PARALLEL_WORKERS=4` when `fileCount > AUTO_CONCURRENCY_FILE_THRESHOLD=100`), `shouldRunParallel(workers, fileCount, explicit)` (Q1: explicit `--workers` bypasses the >50-file floor), and `parseWorkers(s)` (rejects `'0'`, `'-3'`, `'foo'`, `'1.5'`, trailing chars — replaces the prior parseInt-with-no-validation in both `sync.ts` and `import.ts`). Used by `performSync`, `performFullSync`, `runImport`, and the Minion `sync` handler so the three sites can no longer drift.
+- `src/commands/sync.ts` — `gbrain sync` CLI + the `performSync` / `performFullSync` library entrypoints (consumed by the autopilot cycle and the Minion sync handler). v0.22.13 (PR #490): `performSync` wraps its body in a `gbrain-sync` writer lock so two concurrent syncs (manual + autopilot, two terminals, two Conductor workspaces) cannot both write `last_commit` and let the last writer win. Head-drift gate after the import phase re-checks `git rev-parse HEAD`; if HEAD moved (someone ran `git checkout` / `git pull` mid-sync), the bookmark refuses to advance. Vanished files now record a failedFiles entry instead of silent-skip — the silent-skip-then-advance pathology that survived prior hardening passes is dead. Worker engines wrap in try/finally so disconnect always fires (panic-path leak fix). Both PGLite-detection sites use `engine.kind === 'pglite'`. CLI accepts `--workers N` (alias `--concurrency N`), validated via `parseWorkers`. Explicit `--workers` bypasses the auto-path file-count floor; auto path defers to `autoConcurrency()`. Banner moved to stderr.
+- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive (extended to **8 phases in v0.23**). `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes phases in semantically-driven order: **lint → backlinks → sync → synthesize → extract → patterns → embed → orphans**. v0.23's `synthesize` phase runs after sync (cross-references see fresh brain) and before extract (auto-link materializes its writes); `patterns` runs after extract so it reads a fresh graph (codex finding #7 — subagent put_page sets `ctx.remote=true` and skips auto-link/timeline by default; extract is the canonical materialization). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler. Coordination via `gbrain_cycle_locks` DB table + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite. `CycleReport.schema_version: "1"` is stable; totals additively grew in v0.23 (`transcripts_processed`, `synth_pages_written`, `patterns_written`). `yieldBetweenPhases` runs between phases. **v0.23 added `yieldDuringPhase`** for in-phase keepalive — synthesize/patterns call it during long waits to renew the cycle-lock TTL. Engine nullable; lock-skip on read-only phase selections. v0.22.1 (#403): `CycleOpts.signal?: AbortSignal` propagates the worker's abort signal; `checkAborted()` fires between every phase. v0.22.1 (#417): `runPhaseSync` returns `pagesAffected` via `SyncPhaseResult`; `runCycle` captures it and threads to `runPhaseExtract` as the 4th arg. v0.22.1 (Codex F2): `runPhaseSync` takes `willRunExtractPhase: boolean` and sets `noExtract: phases.includes('extract')` so `gbrain dream --phase sync` doesn't silently lose extraction. v0.22.5 (#475): `resolveSourceForDir(engine, brainDir)` threads `sourceId` to `performSync()` so sync reads the per-source `sources.last_commit` anchor instead of the drift-prone global `config.sync.last_commit` key.
+- `src/core/cycle/synthesize.ts` (v0.23) — Synthesize phase: conversation-transcript-to-brain pipeline. Reads from `dream.synthesize.session_corpus_dir`, runs cheap Haiku verdict (cached in `dream_verdicts`), then fans out one Sonnet subagent per worth-processing transcript with `allowed_slug_prefixes` (sourced from `skills/_brain-filing-rules.json` `dream_synthesize_paths.globs`). Orchestrator collects slugs from `subagent_tool_executions` (NOT `pages.updated_at` — codex finding #2) and reverse-renders DB → markdown via `serializeMarkdown`. Cooldown via `dream.synthesize.last_completion_ts`, written ONLY on success. Idempotency key `dream:synth:<file_path>:<content_hash>`. Auto-commit deferred to v1.1 (codex #5). `--dry-run` runs Haiku, skips Sonnet (codex #8). Subagent never gets fs-write access. **v0.23.2:** `renderPageToMarkdown` (now exported) stamps `dream_generated: true` and `dream_cycle_date` into every reverse-write's frontmatter; `writeSummaryPage` does the same on the dream-cycle summary index. The marker is the explicit identity surface checked by `isDreamOutput` in `transcript-discovery.ts` — replaces the v0.23.1 content-prefix heuristic that could miss real output (`serializeMarkdown` doesn't embed slugs in body) and false-positive on user transcripts citing brain pages. `judgeSignificance` and `JudgeClient` are exported; `judgeSignificance` accepts a `verdictModel` parameter (default `claude-haiku-4-5-20251001`) loaded from `dream.synthesize.verdict_model` via `loadSynthConfig`.
+- `src/core/cycle/patterns.ts` (v0.23) — Patterns phase: cross-session theme detection over reflections within `dream.patterns.lookback_days` (default 30). Names a pattern only when ≥`dream.patterns.min_evidence` (default 3) reflections support it. Single Sonnet subagent; same allow-list path as synthesize. Runs AFTER `extract` so the graph is fresh.
+- `src/core/cycle/transcript-discovery.ts` (v0.23) — Pure filesystem walk for synthesize. `discoverTranscripts(opts)` filters `.txt` files by date range, min_chars, and word-boundary regex `excludePatterns` (Q-3: `medical` matches "medical advice" but NOT "comedical"; power users may pass full regex). `readSingleTranscript(path)` is the `gbrain dream --input <file>` ad-hoc path. **v0.23.2 self-consumption guard:** `DREAM_OUTPUT_MARKER_RE` (anchored at frontmatter open `---\n`, optional BOM + CRLF tolerance, scans first 2000 chars for `dream_generated: true` with case-insensitive value and word boundary on `true`) drives `isDreamOutput(content, bypass=false)`. Both `discoverTranscripts` and `readSingleTranscript` skip matching files and emit a `[dream] skipped <basename>: dream_generated marker` stderr log (no more silent skips). `bypassGuard?: boolean` on `DiscoverOpts` and `readSingleTranscript`'s opts disables the guard for the explicit `--unsafe-bypass-dream-guard` escape hatch only — never auto-applied for `--input`. Replaces v0.23.1's `DREAM_OUTPUT_SLUGS` content-prefix list.
+- `src/commands/dream.ts` — v0.17 `gbrain dream` CLI; ~80-line thin alias over `runCycle`. brainDir resolution requires explicit `--dir` OR `sync.repo_path` config. Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`. **v0.23 added** `--input <file>` (ad-hoc transcript, implies `--phase synthesize`), `--date YYYY-MM-DD`, `--from <d> --to <d>` (backfill range). Conflict detection: `--input` + `--date` exits 2. ISO date validation. `--dry-run` runs Haiku significance verdict but skips Sonnet synthesis (codex finding #8 — NOT zero LLM calls). Exit code 1 on status=failed. **v0.23.2 added** `--unsafe-bypass-dream-guard` (long-form intentional, plumbed through `runCycle.synthBypassDreamGuard` → `SynthesizePhaseOpts.bypassDreamGuard` → `discoverTranscripts({bypassGuard})` and `readSingleTranscript({bypassGuard})`). Loud stderr warning fires at synthesize-phase entry when set. Never auto-applied for `--input` so any caller can't silently re-trigger the loop bug.
+- `src/commands/friction.ts` + `src/core/friction.ts` (v0.23) — `gbrain friction {log,render,list,summary}` reporter. Append-only JSONL under `$GBRAIN_HOME/friction/<run-id>.jsonl`. Schema is a flat extension of `StructuredAgentError` (D20). Render groups by severity → phase, defaults to `--redact` for md output (strips `$HOME`/`$CWD` to placeholders so reports paste safely in PRs). Run-id resolves from `--run-id` > `$GBRAIN_FRICTION_RUN_ID` > `standalone.jsonl`. Skills the claw-test exercises gain a `_friction-protocol.md` callout so agents know when to log friction.
+- `src/commands/claw-test.ts` + `src/core/claw-test/` (v0.23) — `gbrain claw-test [--scenario <name>] [--live --agent openclaw]`. End-to-end "fresh user" friction harness. Two modes: scripted (CI gate, agent-free) and live (real openclaw subprocess, $1–2 in tokens). Sets `GBRAIN_HOME=<tempdir>` for hermeticity and captures gbrain's `--progress-json` events from each child's stderr to verify expected phases ran (`import.files`, `extract.links_fs`, `doctor.db_checks`). Phases for scripted mode: setup → install_brain (`gbrain init --pglite`) → import (`--no-embed`) → query → extract → verify (`gbrain doctor --json`, asserts `status: 'ok'`) → render. Live mode hands `BRIEF.md` from `test/fixtures/claw-test-scenarios/<name>/` to the agent runner. v1 ships with the OpenClaw runner only (`src/core/claw-test/runners/openclaw.ts`, invokes `openclaw agent --local --agent <name> --message <brief>`); hermes runner deferred to v1.1. Transcript capture (`transcript-capture.ts`) uses `fs.createWriteStream` with `'drain'`-event backpressure — D17 fix for the 256KB-burst child-stall scenario. v0.18 upgrade scenario seeded via `seed-pglite.ts` SQL replay.
+- `skills/_friction-protocol.md` (v0.23) — shared cross-cutting convention skill (like `_brain-filing-rules.md`). Tells agents when to call `gbrain friction log` and how to choose a severity. Routes to friction CLI from any skill the claw-test exercises.
 - `scripts/check-progress-to-stdout.sh` — CI guard against regressing to `\r`-on-stdout progress. Wired into `bun run test` via `scripts/check-progress-to-stdout.sh && bun test` in package.json.
 - `docs/progress-events.md` — Canonical JSON event schema reference. Stable from v0.15.2, additive only.
 - `src/core/markdown.ts` — Frontmatter parsing + body splitter. `splitBody` requires an explicit timeline sentinel (`<!-- timeline -->`, `--- timeline ---`, or `---` immediately before `## Timeline`/`## History`). Plain `---` in body text is a markdown horizontal rule, not a separator. `inferType` auto-types `/wiki/analysis/` → analysis, `/wiki/guides/` → guide, `/wiki/hardware/` → hardware, `/wiki/architecture/` → architecture, `/writing/` → writing (plus the existing people/companies/deals/etc heuristics).
 - `scripts/check-jsonb-pattern.sh` — CI grep guard. Fails the build if anyone reintroduces (a) the `${JSON.stringify(x)}::jsonb` interpolation pattern (postgres.js v3 double-encodes it), or (b) `max_stalled INTEGER NOT NULL DEFAULT 1` in any schema source file (v0.15.1 #219 regression guard — must be DEFAULT 5 to preserve SIGKILL-rescue). Wired into `bun test`.
+- `docker-compose.ci.yml` + `scripts/ci-local.sh` (v0.23.1) — Local CI gate. `bun run ci:local` spins up `pgvector/pgvector:pg16` + `oven/bun:1` with named volumes (`gbrain-ci-pg-data`, `gbrain-ci-node-modules`, `gbrain-ci-bun-cache`), runs gitleaks on host, smoke-tests `scripts/run-e2e.sh` argv handling, runs unit tests with `DATABASE_URL` unset (matches GH Actions structure), then runs all 29 E2E files sequentially. `--diff` swaps in the diff-aware selector; `--no-pull` skips upstream pulls; `--clean` nukes named volumes. Postgres host port defaults to 5434 (avoids 5432 manual `gbrain-test-pg` and 5433 sibling-project conflict); override with `GBRAIN_CI_PG_PORT=NNNN`. Stronger gate than current PR CI's 2-file Tier 1 set — closes the "push-and-wait" feedback loop pre-push.
+- `scripts/select-e2e.ts` + `scripts/e2e-test-map.ts` (v0.23.1) — Diff-aware E2E test selector. Reads three git sources (committed `origin/master...HEAD`, working-tree `HEAD`, and `git ls-files --others --exclude-standard` for untracked, NOT-gitignored files), classifies as EMPTY / DOC_ONLY / SRC. Fail-closed by design: EMPTY → all 29 files (clean branch shouldn't run nothing), DOC_ONLY (every path matches the README/CLAUDE/AGENTS/CHANGELOG/TODOS allowlist) → empty stdout, SRC → escape-hatch paths (schema, package.json, skills/) trigger all; otherwise the hand-tuned `E2E_TEST_MAP` glob → tests narrows; an unmapped src/ change still emits ALL files, never silently nothing. Pure-function exports (`selectTests`, `classify`, `matchGlob`) so it's trivial to test and fork. `bun run ci:select-e2e` prints the current selection on stdout, pipe-friendly. `test/select-e2e.test.ts` covers all 4 branches plus 3 codex regression guards (skills/, untracked files, unmapped src/) — 24 cases.
+- `scripts/run-e2e.sh` (v0.23.1 update) — Sequential E2E runner. Now accepts an optional argv-driven file list (used by `ci:local:diff` to pipe in selector output) and a `--dry-run-list` flag that prints the resolved file list and exits (used by `ci-local.sh`'s startup smoke-test). Falls back to `test/e2e/*.test.ts` when invoked with no args.
 - `scripts/llms-config.ts` + `scripts/build-llms.ts` — Generator for `llms.txt` (llmstxt.org-spec web index) + `llms-full.txt` (inlined single-fetch bundle). Curated config drives both. Run `bun run build:llms` after adding a new doc. `LLMS_REPO_BASE` env var lets forks regenerate with their own URL base. `FULL_SIZE_BUDGET` (600KB) caps the inline bundle; generator WARNs if exceeded. Committed output is not analogous to `schema-embedded.ts` (no runtime consumer); we commit for GitHub browsing and fork-safe fetching.
 - `AGENTS.md` — Local-clone entry point for non-Claude agents (Codex, Cursor, OpenClaw, Aider). Mirrors `CLAUDE.md` intent via relative links. Claude Code keeps using `CLAUDE.md`.
 - `docs/UPGRADING_DOWNSTREAM_AGENTS.md` — Patches for downstream agent skill forks to apply when upgrading. Each release appends a new section. v0.10.3 includes diffs for brain-ops, meeting-ingestion, signal-detector, enrich.
@@ -142,7 +170,7 @@ strict behavior when unset.
 - `skills/soul-audit/SKILL.md` — 6-phase interview for SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md
 - `skills/webhook-transforms/SKILL.md` — External events to brain signals
 - `skills/data-research/SKILL.md` — Structured data research: email-to-tracker pipeline with parameterized YAML recipes
-- `skills/minion-orchestrator/SKILL.md` — Background job orchestration: submit, fan out children with depth/cap/timeouts, collect results via child_done inbox
+- `skills/minion-orchestrator/SKILL.md` — Unified background-work skill (v0.20.4 consolidation of the former `minion-orchestrator` + `gbrain-jobs` split). Two lanes: shell jobs via `gbrain jobs submit shell --params '{"cmd":"..."}'` (operator/CLI only; MCP throws `permission_denied` for protected names) and LLM subagents via `gbrain agent run` (user-facing entrypoint). Shared Preconditions block, parent-child DAGs with depth/cap/timeouts, `child_done` inbox for fan-in, PGLite `--follow` inline path for dev. Triggers narrowed from bare `"gbrain jobs"` to `"gbrain jobs submit"` + `"submit a gbrain job"` so `stats`/`prune`/`retry` questions fall through to `gbrain --help`.
 - `templates/` — SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md templates
 - `skills/migrations/` — Version migration files with feature_pitch YAML frontmatter
 - `src/commands/publish.ts` — Deterministic brain page publisher (code+skill pair, zero LLM calls)
@@ -204,6 +232,20 @@ Key commands added in v0.14.3 (fix wave):
 - `gbrain jobs submit` gains `--max-stalled`, `--backoff-type`, `--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key` — exposing existing `MinionJobInput` fields as first-class CLI flags.
 - `gbrain jobs smoke --sigkill-rescue` — opt-in regression smoke case simulating a killed worker; asserts the v0.14.3 schema default (`max_stalled=5`) actually rescues on first stall.
 
+Key commands added in v0.22.13 (PR #490):
+- `gbrain sync --workers N` (alias `--concurrency N`) — parallelize the import phase using per-worker Postgres engines (small pool of 2 each) with an atomic queue index. Auto-concurrency: defaults to 4 workers when the diff exceeds 100 files. Smaller diffs stay serial. Explicit `--workers` always wins (even on a 30-file diff). PGLite forces serial regardless. Validation rejects `0`, negatives, non-integers loud (replaces the prior silent fall-through to auto-concurrency).
+- `gbrain import --workers N` — same `parseWorkers()` validation as sync; same try/finally worker-engine cleanup. Behavior surface unchanged.
+
+Key commands added in v0.22.16 (claw-test friction loop):
+- `gbrain claw-test [--scenario fresh-install|upgrade-from-v0.18] [--keep-tempdir]` — scripted-mode CI gate that runs the full canonical first-day flow against a fresh tempdir. Asserts every expected `--progress-json` phase fired and doctor's `status === 'ok'`. ~30s, no API keys.
+- `gbrain claw-test --live --agent openclaw` — friction-discovery mode. Spawns real openclaw, hands it `BRIEF.md`, captures stdin/stdout/stderr to `<run>/transcript.jsonl`, lets the agent log friction via the friction CLI. Run on demand; ~5–10 min and ~$1–2 in tokens.
+- `gbrain claw-test --list-agents` — reports which agent runners are registered + their detection state (binary path or unavailable reason).
+- `gbrain friction log --severity {confused|error|blocker|nit} --phase <name> --message <text> [--hint ...] [--kind {friction|delight}] [--run-id ...]` — append a friction or delight entry to the active run JSONL.
+- `gbrain friction render --run-id <id> [--json] [--transcripts] [--no-redact]` — markdown report grouped by severity + phase; `--redact` is the default for md output (strips `$HOME`/`$CWD` placeholders so reports paste safely in PRs/issues).
+- `gbrain friction list [--json]` — recent run-ids with friction/delight counts; interrupted runs marked `(interrupted)`.
+- `gbrain friction summary --run-id <id> [--json]` — two-column friction + delight summary.
+- `GBRAIN_HOME` env override is now honored uniformly across every gbrain write site (config, audit, friction, sync-failures, import checkpoint, integrity log, integrations heartbeat, migration rollback, etc.) — `gbrainPath(...)` from `src/core/config.ts` is the canonical helper. Read-side host-fingerprint detection (`~/.claude`/`~/.openclaw` etc.) intentionally NOT confined in v1; that's a v1.1 follow-up.
+
 ## Testing
 
 `bun test` runs all tests. After the v0.12.1 release: ~75 unit test files + 8 E2E test files (1412 unit pass, 119 E2E when `DATABASE_URL` is set — skip gracefully otherwise). Unit tests run
@@ -215,7 +257,9 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/files.test.ts` (MIME/hash), `test/import-file.test.ts` (import pipeline),
 `test/upgrade.test.ts` (schema migrations),
 `test/file-migration.test.ts` (file migration), `test/file-resolver.test.ts` (file resolution),
-`test/import-resume.test.ts` (import checkpoints), `test/migrate.test.ts` (migration; v8/v9 helper-btree-index SQL structural assertions + 1000-row wall-clock fixtures that guard the O(n²)→O(n log n) fix + v0.13.1 assertions on v12/v13 SQL shape, `sqlFor` + `transaction:false` runner semantics, and the `max_stalled DEFAULT 1` regression guard),
+`test/import-resume.test.ts` (import checkpoints), `test/migrate.test.ts` (migration; v8/v9 helper-btree-index SQL structural assertions + 1000-row wall-clock fixtures that guard the O(n²)→O(n log n) fix + v0.13.1 assertions on v12/v13 SQL shape, `sqlFor` + `transaction:false` runner semantics, the `max_stalled DEFAULT 1` regression guard, and v0.22.6.1 v24 `sqlFor.pglite: ''` no-op assertion),
+`test/bootstrap.test.ts` (v0.22.6.1 — bootstrap contract: no-op on fresh install, idempotent across two `initSchema()` calls, no-op on modern brain that already has every probed column, full bootstrap path on simulated pre-v0.18 brain, fresh-install regression guard, pre-v0.13 `links` shape coverage),
+`test/schema-bootstrap-coverage.test.ts` (v0.22.6.1 CI guard — `REQUIRED_BOOTSTRAP_COVERAGE` lists every forward reference in PGLITE_SCHEMA_SQL; the test fails loudly if `applyForwardReferenceBootstrap` skips one. When you add a column-with-index to the embedded schema blob, you extend both arrays or this guard fails. The pattern that broke gbrain ten times in two years is now structurally prevented.),
 `test/setup-branching.test.ts` (setup flow), `test/slug-validation.test.ts` (slug validation),
 `test/storage.test.ts` (storage backends), `test/supabase-admin.test.ts` (Supabase admin),
 `test/yaml-lite.test.ts` (YAML parsing), `test/check-update.test.ts` (version check + update CLI),
@@ -227,8 +271,9 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/lint.test.ts` (LLM artifact detection, code fence stripping, frontmatter validation),
 `test/report.test.ts` (report format, directory structure),
 `test/skills-conformance.test.ts` (skill frontmatter + required sections validation),
-`test/resolver.test.ts` (RESOLVER.md coverage, routing validation),
+`test/resolver.test.ts` (RESOLVER.md coverage, routing validation + v0.20.4 round-trip: every quoted RESOLVER.md trigger must match a frontmatter `triggers:` entry in the target skill, and every `name="<word>"` reference in any SKILL.md must resolve to a declared op in `src/core/operations.ts` or a Minions handler in `PROTECTED_JOB_NAMES`),
 `test/search.test.ts` (RRF normalization, compiled truth boost, cosine similarity, dedup key),
+`test/sql-ranking.test.ts` (v0.22.0 source-boost helpers: 39 cases covering longest-prefix-match in SQL CASE, detail=high temporal-bypass, three-meta-char LIKE escape (%, _, \\), single-quote SQL-literal doubling, env override parsing for GBRAIN_SOURCE_BOOST + GBRAIN_SEARCH_EXCLUDE, resolveBoostMap / resolveHardExcludes merge semantics),
 `test/dedup.test.ts` (source-aware dedup, compiled truth guarantee, layer interactions),
 `test/intent.test.ts` (query intent classification: entity/temporal/event/general),
 `test/eval.test.ts` (retrieval metrics: precisionAtK, recallAtK, mrr, ndcgAtK, parseQrels),
@@ -256,6 +301,9 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/orphans.test.ts` (v0.12.3 orphans command: detection, pseudo filtering, text/json/count outputs, MCP op),
 `test/postgres-engine.test.ts` (v0.12.3 statement_timeout scoping: `sql.begin` + `SET LOCAL` shape, source-level grep guardrail against reintroduced bare `SET statement_timeout`),
 `test/sync.test.ts` (sync logic + v0.12.3 regression guard asserting top-level `engine.transaction` is not called),
+`test/sync-concurrency.test.ts` (v0.22.13 PR #490: 17 cases covering `autoConcurrency()` thresholds + PGLite-forces-serial + explicit-override clamping, `shouldRunParallel()` Q1 explicit-bypasses-floor contract, and `parseWorkers()` validation that rejects `'0'`/`'-3'`/`'foo'`/`'1.5'`/trailing chars),
+`test/sync-parallel.test.ts` (v0.22.13 PR #490: PGLite-routed coverage of the bookmark gate under concurrency request, head-drift gate, vanished-file failure capture, PGLite-stays-serial, and the `gbrain-sync` writer-lock contract — 7 cases),
+`test/sync-failures.test.ts` (v0.22.12: 28 cases pinning `classifyErrorCode` regex coverage for all 12 codes against literal production message strings from `markdown.ts:159-244` and `import-file.ts:199, 347, 352, 401`; `summarizeFailuresByCode` sort + pre-classified-honor; `recordSyncFailures` code-field persistence; `acknowledgeSyncFailures` AcknowledgeResult shape + backfill on pre-v0.22.12 entries),
 `test/doctor.test.ts` (doctor command + v0.12.3 assertions that `jsonb_integrity` scans the four v0.12.0 write sites and `markdown_body_completeness` is present),
 `test/utils.test.ts` (shared SQL utilities + `tryParseEmbedding` null-return and single-warn semantics),
 `test/build-llms.test.ts` (llms.txt/llms-full.txt generator: path resolution, idempotence, spec shape, regen-drift guard, content contract, AGENTS.md install-path mirror, size-budget enforcement — 7 cases),
@@ -266,16 +314,26 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/skill-manifest.test.ts` (v0.19 skill manifest parser: drift detection, managed-block markers),
 `test/skillify-scaffold.test.ts` (v0.19 `gbrain skillify scaffold` stubs: SKILL.md, script, tests, routing-eval fixtures),
 `test/skillpack-install.test.ts` (v0.19 `gbrain skillpack install` managed-block install / update / no-clobber semantics),
-`test/skillpack-sync-guard.test.ts` (v0.19 sync-guard: bundled skills stay byte-identical to `skills/` source).
+`test/skillpack-sync-guard.test.ts` (v0.19 sync-guard: bundled skills stay byte-identical to `skills/` source),
+`test/http-transport.test.ts` (v0.22.7 HTTP transport: 23 unit cases covering bearer auth + missing/no-Bearer/unknown/revoked + `/health` bypass, F1+F2 round-trip via dispatch.ts, F3 invalid_params, application/json response shape (not SSE), CORS default-deny + allowlist, body cap on Content-Length AND chunked, two-bucket rate limit (refill, exhaust+Retry-After, LRU eviction, TTL prune, pre-auth IP fires before DB), and `mcp_request_log` audit on success + auth_failed).
 
 E2E tests (`test/e2e/`): Run against real Postgres+pgvector. Require `DATABASE_URL`.
 - `bun run test:e2e` runs Tier 1 (mechanical, all operations, no API keys). Includes 9 dedicated cases for the postgres-engine `addLinksBatch` / `addTimelineEntriesBatch` bind path — postgres-js's `unnest()` binding is structurally different from PGLite's and gets its own coverage.
 - `test/e2e/search-quality.test.ts` runs search quality E2E against PGLite (no API keys, in-memory)
 - `test/e2e/graph-quality.test.ts` runs the v0.10.3 knowledge graph pipeline (auto-link via put_page, reconciliation, traversePaths) against PGLite in-memory
 - `test/e2e/postgres-jsonb.test.ts` — v0.12.2 regression test. Round-trips all 5 JSONB write sites (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter) against real Postgres and asserts `jsonb_typeof='object'` plus `->>'key'` returns the expected scalar. The test that should have caught the original double-encode bug.
+- `test/e2e/integrity-batch.test.ts` (v0.22.8) — parity tests for `scanIntegrity`'s batch-load fast path vs sequential. Four cases (dedup, hits, validate, topPages) seed a fixture and assert both paths return identical results. Dedup case uses raw SQL via `getConn().unsafe()` to seed a `(test-source-2, people/alice)` row alongside the default-source row, since `engine.putPage` doesn't take a `source_id`. Pins the codex-caught multi-source overcounting regression.
 - `test/e2e/jsonb-roundtrip.test.ts` — v0.12.3 companion regression against the 4 doctor-scanned JSONB sites. Assertion-level overlap with `postgres-jsonb.test.ts` is intentional defense-in-depth: if doctor's scan surface ever drifts from the actual write surface, one of these tests catches it.
+- `test/e2e/sync.test.ts` (v0.22.12 — `--skip-failed` failure-loop test, alongside the existing 13 happy-path tests): exercises the full chain — broken file → `performSync` returns `blocked_by_failures` with grouped breakdown → `performSync({skipFailed: true})` advances bookmark and returns `AcknowledgeResult` with code summary → second broken file → second cycle. Saves and restores the user's real `~/.gbrain/sync-failures.jsonl` so the test is hermetic on a developer machine. Asserts bookmark gating, JSONL state, dedup across paths, summary aggregation, and the literal doctor-rendering string format. This is the integration test that proves the v0.22.12 chain holds together — unit tests cover the pure functions in isolation, this covers the integration.
 - `test/e2e/upgrade.test.ts` runs check-update E2E against real GitHub API (network required)
+- `test/e2e/minions-shell-pglite.test.ts` (v0.20.4) exercises the PGLite `--follow` inline shell-job path (in-memory, no `DATABASE_URL` required) — the path the consolidated minion-orchestrator skill documents for dev use
 - `test/e2e/openclaw-reference-compat.test.ts` (v0.19) — exercises `check-resolvable` + `skillpack install` against a minimal AGENTS.md workspace fixture (`test/fixtures/openclaw-reference-minimal/`), regression guard for the 107-skill OpenClaw deployment shape
+- `test/e2e/search-swamp.test.ts` (v0.22.0) — reproduces the headline source-swamp case. Seeds a curated `originals/talks/article-outline-fat-code` page against two `wintermute/chat/` pages stuffed with the same multi-word phrase. Asserts the article wins keyword AND vector ranking, that `detail=high` lets the chat swamp re-surface (temporal-query workflow preserved), and that `source_id` passes through the two-stage CTE intact. PGLite in-memory.
+- `test/e2e/search-exclude.test.ts` (v0.22.0) — verifies `test/` + `archive/` pages are hidden by default, that `include_slug_prefixes` opts back in, and that caller-supplied `exclude_slug_prefixes` adds to defaults. Both keyword and vector search paths covered.
+- `test/e2e/engine-parity.test.ts` (v0.22.0) — Postgres ↔ PGLite top-result and result-set parity for `searchKeyword` + `searchVector`. Codex flagged that Postgres ranks pages then picks best chunk while PGLite returns chunks directly — without parity coverage the source-boost fix could pass on PGLite and fail on Postgres. Skips gracefully when `DATABASE_URL` is unset.
+- `test/e2e/postgres-bootstrap.test.ts` (v0.22.6.1) — exercises `PostgresEngine.initSchema()` directly against a fresh real Postgres database. Asserts the bootstrap path is no-op on fresh installs and that SCHEMA_SQL replays cleanly through the engine path (not via the standalone `db.initSchema` from `src/core/db.ts`, which would have produced false-positive coverage). Codex caught the E2E-shape gap during plan review.
+- `test/e2e/http-transport.test.ts` (v0.22.7) — 8 cases against real Postgres covering `gbrain serve --http` end-to-end: bearer auth round-trip, `last_used_at` SQL-level debounce semantics, `mcp_request_log` row insertion on success and auth_failed paths, `/health` DB-down → 503 (DB-probing health check), and the F1+F2+F3 dispatch round-trip with a real operation. Skips gracefully when `DATABASE_URL` is unset.
+- `test/e2e/sync-parallel.test.ts` (v0.22.13 PR #490) — DATABASE_URL-gated. T2: 60-file Postgres sync at concurrency=4 imports all + no connection leak (probes `pg_stat_activity` before/after to confirm worker engines disconnected). P4: 120-file serial-vs-parallel benchmark prints `SYNC_PARALLEL_BENCH N files | serial=Xms | parallel(4)=Yms | speedup=Zx` for CHANGELOG quoting. Asserts parallel ≤ serial × 1.5 (CI-noise tolerant; not a strict speedup gate).
 - Tier 2 (`skills.test.ts`) requires OpenClaw + API keys, runs nightly in CI
 - If `.env.testing` doesn't exist in this directory, check sibling worktrees for one:
   `find ../  -maxdepth 2 -name .env.testing -print -quit` and copy it here if found.
@@ -327,7 +385,7 @@ stop and remove it before starting a new one.
 
 ## Skills
 
-Read the skill files in `skills/` before doing brain operations. GBrain ships 28 skills
+Read the skill files in `skills/` before doing brain operations. GBrain ships 29 skills
 organized by `skills/RESOLVER.md` (`AGENTS.md` is also accepted as of v0.19):
 
 **Original 8 (conformance-migrated):** ingest (thin router), query, maintain, enrich,
@@ -337,11 +395,19 @@ briefing, migrate, setup, publish.
 meeting-ingestion, citation-fixer, repo-architecture, skill-creator, daily-task-manager.
 
 **Operational + identity:** daily-task-prep, cross-modal-review, cron-scheduler, reports,
-testing, soul-audit, webhook-transforms, data-research, minion-orchestrator.
+testing, soul-audit, webhook-transforms, data-research, minion-orchestrator. As of
+v0.20.4, `minion-orchestrator` is the single unified skill for both lanes of background
+work (shell jobs via `gbrain jobs submit shell`, LLM subagents via `gbrain agent run`) ...
+the prior `gbrain-jobs` skill was merged in, Preconditions are shared, and trigger
+routing is narrowed to what the skill actually covers.
 
 **Skillify loop (v0.19):** skillify (the markdown orchestration), skillpack-check
 (agent-readable health report).
 
+**Operational health (v0.19.1):** smoke-test (8 post-restart health checks with auto-fix
+for Bun, CLI, DB, worker, Zod CJS, gateway, API key, brain repo; user-extensible via
+`~/.gbrain/smoke-tests.d/*.sh`).
+
 **Conventions:** `skills/conventions/` has cross-cutting rules (quality, brain-first,
 model-routing, test-before-bulk, cross-modal). `skills/_brain-filing-rules.md` and
 `skills/_output-rules.md` are shared references.
@@ -382,15 +448,100 @@ in bulk paths, the CI guard will fail the build.
 
 `bun build --compile --outfile bin/gbrain src/cli.ts`
 
+## Version locations (single source of truth: `VERSION` file)
+
+Every release advances the version in **five files at once**. Keep these in
+sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs
+package.json drift), but the canonical list lives here so future runs and
+the auto-update agent know where to look.
+
+**Required (every release must update all five):**
+
+| File | What lives there | Format |
+|---|---|---|
+| `VERSION` | The single source of truth. Read first by `/ship`, the binary, and CI version-gate. | Bare 4-digit string `MAJOR.MINOR.PATCH.MICRO` (e.g. `0.22.1`), no leading `v`, no trailing newline-sensitivity issues. |
+| `package.json` | Bun/npm package version. `gbrain --version` reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against `VERSION` and fails if they drift. | `"version": "0.22.1"` |
+| `CHANGELOG.md` | Top entry header `## [0.22.1] - YYYY-MM-DD` plus the "To take advantage of v0.22.1" block. | Standard Keep-a-Changelog header. |
+| `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z` references in TODO bodies. |
+| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z (#NNN, contributed by @user)` references. |
+
+**Auto-derived (no manual edit; refreshed by their own commands):**
+
+- `bun.lock` — root-package version is auto-pinned from `package.json`. After
+  bumping `package.json`, run `bun install` to refresh the lockfile.
+- `llms-full.txt` / `llms.txt` — auto-generated documentation bundles. After
+  any release ship that touches the Key Files annotations in `CLAUDE.md`,
+  run `bun run build:llms` to regenerate. The bundles do not contain a
+  version pin per se; they reflect the current state of the docs they index.
+
+**Historical (DO NOT bump on release):**
+
+- `skills/migrations/v0.21.0.md` — migration files use the version they
+  shipped FROM as their filename. v0.21.0's migration always says v0.21.0.
+- `src/commands/migrations/v0_21_0.ts` — same: migration code references
+  the schema version it migrates to.
+- `test/migrations-v0_21_0.test.ts`, `test/migration-orchestrator-v0_21_0.test.ts`,
+  `test/migrate.test.ts` — migration tests reference historical migration
+  versions; these are correct as-is and should not move.
+- `src/core/db.ts`, `src/core/migrate.ts`, `src/core/import-file.ts`,
+  `src/commands/reindex-code.ts` — code comments cite the release that
+  introduced a feature. Once written, these are historical record.
+- `README.md` — references the latest published feature names by version
+  (e.g. "v0.21.0 Code Cathedral"); update only when the README's marketing
+  copy is intentionally being refreshed, NOT on every micro/patch bump.
+
+**The /ship workflow's version idempotency check:** Step 12 reads
+`VERSION` and `package.json`, classifies as FRESH / ALREADY_BUMPED /
+DRIFT_STALE_PKG / DRIFT_UNEXPECTED, and refuses to proceed on
+DRIFT_UNEXPECTED. This is why the two must move together.
+
+**The CI version-gate** rejects pushes where `VERSION` and
+`package.json` disagree, OR where `VERSION` is not strictly greater
+than master's VERSION. If a queue collision claims your version on
+master before yours lands, /ship's queue-aware allocator (Step 12)
+will detect drift and re-bump on the next run.
+
 ## Pre-ship requirements
 
-Before shipping (/ship) or reviewing (/review), always run the full test suite:
+Before shipping (/ship) or reviewing (/review), always run the full test suite.
+Two equivalent paths:
+
+**Path A — local CI gate (recommended, v0.23.1+):**
+- `bun run ci:local` runs the entire stack inside Docker: gitleaks (host), unit
+  tests with `DATABASE_URL` unset, and all 29 E2E files sequentially against a
+  fresh pgvector container. Stronger than PR CI's 2-file Tier 1 set; closer to
+  what nightly Tier 1 catches. Spins up + tears down postgres automatically via
+  `docker-compose.ci.yml`. Override the host port with
+  `GBRAIN_CI_PG_PORT=5435 bun run ci:local` if 5434 collides.
+- `bun run ci:local:diff` runs only the E2E files matched by the diff selector
+  (`scripts/select-e2e.ts`), falling back to all 29 on unmapped src/ paths or
+  schema/skills/package.json changes. Fast iteration during a focused branch.
+
+**Path B — manual lifecycle (still supported):**
 - `bun test` — unit tests (no database required)
 - Follow the "E2E test DB lifecycle" steps above to spin up the test DB,
   run `bun run test:e2e`, then tear it down.
 
 Both must pass. Do not ship with failing E2E tests. Do not skip E2E tests.
 
+**Always run typecheck before pushing.** `bun test` (the bun runner)
+skips TypeScript type checking — it only enforces runtime behavior.
+Three ways to actually gate on types:
+
+1. `bun run test` (npm script in `package.json`) — includes `bun run typecheck`
+   plus the four shell pre-checks (`check-jsonb-pattern.sh`,
+   `check-progress-to-stdout.sh`, `check-trailing-newline.sh`,
+   `check-wasm-embedded.sh`) before the runner. Use this mid-branch.
+2. `bun run typecheck` — `tsc --noEmit` standalone. Fast (~5s on this repo).
+3. `bun run ci:local` — the full local CI gate from Path A.
+
+The trap is: writing a new test, running `bun test test/foo.test.ts`,
+seeing it pass, pushing — and CI's separate typecheck stage rejects an
+invalid type literal that the runner accepted. Caught one of these
+shipping the v0.23.2 round-trip E2E (`type: 'reflection'` is not a
+member of `PageType`). Run `bun run typecheck` once before push, even
+when only test files changed.
+
 ## Post-ship requirements (MANDATORY)
 
 After EVERY /ship, you MUST run /document-release. This is NOT optional. Do NOT

CONTRIBUTING.md

@@ -52,6 +52,10 @@ docs/                     Architecture docs
 ## Running tests
 
 ```bash
+# Recommended: full CI guard chain + tests (matches what CI runs)
+bun run test                      # privacy + jsonb + progress + wasm + typecheck + bun test
+
+# Just the test runner (skips CI guards)
 bun test                          # all tests (unit + E2E skipped without DB)
 bun test test/markdown.test.ts    # specific unit test
 
@@ -63,6 +67,31 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test bun run t
 DATABASE_URL=postgresql://... bun run test:e2e
 ```
 
+Use `bun run test` 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`), trailing-newline drift across tracked
+files (`scripts/check-trailing-newline.sh`), and silent fallback to recursive
+chunking in the compiled binary (`scripts/check-wasm-embedded.sh`).
+
+### 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

INSTALL_FOR_AGENTS.md

@@ -129,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

README.md

@@ -6,7 +6,7 @@ Built by the President and CEO of Y Combinator to run his actual AI agents. The
 
 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. 28 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
+GBrain is those patterns, generalized. 29 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
 
 > **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
 
@@ -28,7 +28,7 @@ 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 28 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 29 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
@@ -80,16 +80,33 @@ Add to `~/.claude/server.json` (Claude Code), Settings > MCP Servers (Cursor), o
 ### Remote MCP (Claude Desktop, Cowork, Perplexity)
 
 ```bash
-ngrok http 8787 --url your-brain.ngrok.app
-bun run src/commands/auth.ts create "claude-desktop"
+gbrain auth create "claude-desktop"            # tokens via the existing CLI
+gbrain serve --http --port 8787                 # built-in HTTP transport (Postgres-only)
+ngrok http 8787 --url your-brain.ngrok.app      # any tunnel works
 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).
+Per-client guides: [`docs/mcp/`](docs/mcp/DEPLOY.md). Hardening defaults, env vars, and threat model: [SECURITY.md](SECURITY.md). ChatGPT requires OAuth 2.1 (not yet implemented).
 
-## The 28 Skills
+### Using gbrain with GStack
 
-GBrain ships 28 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.
+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 29 Skills
+
+GBrain ships 29 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.
 
 [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.
 
@@ -115,7 +132,7 @@ GBrain ships 28 skills organized by `skills/RESOLVER.md` (or your OpenClaw's `AG
 |-------|-------------|
 | **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. |
@@ -135,7 +152,8 @@ GBrain ships 28 skills organized by `skills/RESOLVER.md` (or your OpenClaw's `AG
 | **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. |
-| **minion-orchestrator** | Long-running agent work as background jobs. Submit, fan out children with depth/cap/timeouts, collect results via child_done inbox. |
+| **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
 
@@ -298,9 +316,11 @@ is what you spend time on. Everything else is boilerplate the CLI writes for you
 
 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 --llm` runs an LLM tie-break layer for CI. 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.
+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
 
@@ -337,11 +357,39 @@ gbrain skillpack diff brain-ops                # compare bundle vs your local co
 
 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.
@@ -377,7 +425,7 @@ Run `gbrain integrations` to see status.
 │   Brain Repo     │    │    GBrain     │    │    AI Agent      │
 │   (git)          │    │  (retrieval)  │    │  (read/write)    │
 │                  │    │               │    │                  │
-│  markdown files  │───>│  Postgres +   │<──>│  28 skills       │
+│  markdown files  │───>│  Postgres +   │<──>│  29 skills       │
 │  = source of     │    │  pgvector     │    │  define HOW to   │
 │    truth         │    │               │    │  use the brain   │
 │                  │<───│  hybrid       │    │                  │
@@ -488,6 +536,8 @@ Question
   │    ├─ 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)
@@ -595,8 +645,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
@@ -638,9 +691,15 @@ ADMIN
   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 8787       MCP server (HTTP, Postgres-only, bearer auth)
+  gbrain auth create|list|revoke|test   Token management for the HTTP transport
   gbrain integrations                   Integration recipe dashboard
   gbrain sources list|add|remove|...    Multi-source brain management (v0.18)
-  gbrain dream [--dry-run] [--phase N]  One maintenance cycle then exit (cron-friendly)
+  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)
@@ -683,7 +742,7 @@ The skills in this repo are those patterns, generalized. What took 11 days to bu
 
 ## 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 test` for unit tests. 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.
 
 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,168 @@
+# 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.

TODOS.md

@@ -1,5 +1,560 @@
 # TODOS
 
+## ci-local-mirror
+
+### CI-skip artifact + signature for stages 1+2 follow-up
+**Priority:** P0
+
+**What:** After a successful local CI run via `bun run ci:local`, write `.ci-cache/passed-<commit-sha>.json` containing `{commit, test_set_hash, bun_version, schema_hash, signature}`. Push to a `ci-cache` orphan branch (or GH Releases). CI's first step fetches the artifact for the current SHA and skips the test job if (a) signature matches Garry's GPG/SSH key, and (b) `test_set_hash` matches what CI would have run.
+
+**Why:** Stages 1+2 (shipped in this branch) give a strong local CI gate, but PR CI still re-runs every test on every push. Stage 3 closes the loop and trades ~10 min of CI wall-time for sub-second artifact verification on Garry's own pushes. External PRs are unaffected because the signature won't match — they hit the normal CI path.
+
+**Pros:**
+- ~10 min/PR saved on Garry's own pushes; the local gate becomes the source of truth.
+- External contributor PRs untouched (no security regression).
+- Forces a clear test-set-hash contract: any drift in what local-vs-CI run is caught at verification time.
+
+**Cons:**
+- Trust model needs careful design: signature scheme, key rotation, what happens when signature verification fails.
+- Cache invalidation is real — if env or service version drifts between local run and CI, a stale local pass could ship to master.
+- Adds a `ci-cache` branch / artifact storage surface to maintain.
+
+**Context:**
+- Discussed during the eng-review of the local CI mirror plan at `~/.claude/plans/lets-do-1-2-dockerfile-ci-zany-charm.md`.
+- Don't start until stages 1+2 have been used for ~2 weeks AND the `scripts/e2e-test-map.ts` has stabilized (so test_set_hash is a meaningful identity).
+- Initial trust-but-verify: run both local and CI in parallel for ~1 week before flipping the skip; alert on any disagreement.
+
+**Effort:** M (human ~2-3 days + ~1 week trust-but-verify period running both local + CI in parallel; CC ~1 day for the mechanics).
+
+**Depends on / blocked by:** Stages 1+2 (this PR) landing first.
+
+### test/e2e/multi-source.test.ts cascade test isn't isolated
+**Priority:** P1
+
+**What:** The "sources remove cascades to pages + chunks + timeline + links + files" test in `test/e2e/multi-source.test.ts:281` fails when the file runs after other E2E files in the sequential `bash scripts/run-e2e.sh` order, but passes 20/20 on a fresh Postgres volume. The failing assertion is `SELECT COUNT(*) FROM links WHERE from_page_id = aliceId` expecting 0, getting 1 — so a prior file's setup left a `links` row that references a page id the cascade test happens to reuse. The test's own `setupDB()` truncates but doesn't sweep all referencing rows back when ids collide.
+
+**Why:** Surfaced when `bun run ci:local` (this PR's local CI gate) ran the full sequential E2E. CI never catches it because `.github/workflows/e2e.yml:40` only runs `mechanical.test.ts + mcp.test.ts` on PRs and nightly Tier 1. So 27 of 29 E2E files including this one aren't actually exercised by CI today. The local gate is stronger and surfaces real cross-file isolation gaps.
+
+**Pros:**
+- Fixing isolation makes `bun run ci:local` (full E2E) reliably green.
+- Same fix likely to harden other E2E files that share id namespaces.
+- Lets us turn `bun run ci:local` into a real ship gate.
+
+**Cons:**
+- Could require a per-file "namespace your test ids" pattern, ~30 min per affected file across the suite.
+
+**Context:**
+- Repro: `bash scripts/run-e2e.sh test/e2e/multi-source.test.ts` against a stale DB after other E2E files have run → fails. Same against a fresh `docker compose down -v && up -d postgres` → passes 20/20.
+- The test inserts a hardcoded `cascadetest` source id and `aliceId` page id; collisions across runs are predictable.
+- Likely fix: use `mkdtemp`-style randomized source/page ids per test, OR have the test do a deeper reset (DELETE FROM all five tables in beforeEach) instead of relying on `setupDB`'s TRUNCATE behavior.
+
+**Effort:** S (CC ~30 min for the multi-source.test.ts fix; M if we audit all 29 E2E files for similar id-collision risk).
+
+**Depends on / blocked by:** Nothing.
+
+### scripts/run-e2e.sh:71 echo overflows on large-output failing tests
+**Priority:** P2
+
+**What:** When an E2E test fails AND prints lots of output (e.g., `multi-source.test.ts` floods postgres NOTICE objects), `scripts/run-e2e.sh:71` does `echo "$output"` against a multi-megabyte shell variable. The host pipe to docker-compose-run hits `EAGAIN` and fails with `echo: write error: Resource temporarily unavailable`. With `set -e`, the script aborts at that point, skipping the remaining E2E files and the final SUMMARY block.
+
+**Why:** When the local CI gate finds a real failure (per the multi-source.test.ts entry above), the user wants to see it AND see how the rest of the suite did. Currently the failure shadows the rest.
+
+**Pros:**
+- See all E2E failures from a single run instead of needing to bisect.
+- Quick win, ~5 lines.
+
+**Cons:**
+- None worth listing.
+
+**Context:**
+- Reproduced live during plan verification on 2026-04-29. Previous `multi-source.test.ts` failure killed the script before postgres-bootstrap, postgres-jsonb, etc. could run.
+- Likely fix: replace `echo "$output"` with `printf '%s\n' "$output"`, or write `$output` to a tmpfile and `cat` it (handles large blobs better than echo over pipes), or pipe through `stdbuf -o0`.
+- Don't suppress the postgres NOTICE flood at the test layer — that's separate; here we just want the script to not die when bun's stderr is verbose.
+
+**Effort:** S (human or CC: ~10 min).
+
+**Depends on / blocked by:** Nothing.
+
+## claw-test E2E (v0.22.16 follow-ups)
+
+### Hermes runner — `src/core/claw-test/runners/hermes.ts`
+**Priority:** P2
+
+**What:** Add a Hermes implementation of the `AgentRunner` interface. v1 ships only OpenClaw; v1.1 lands hermes once we have real friction reports from openclaw to validate the contract against.
+
+**Why:** Cross-agent diff (`gbrain friction diff --base openclaw --compare hermes`) is the highest-leverage next signal. Friction unique to one agent vs common-to-both separates "agent contract bug" from "gbrain bug" automatically.
+
+**Effort:** S (CC ~30m). Depends on: v1 openclaw runner producing real friction reports first.
+
+---
+
+### Friction analytics suite — `diff` / `trend` / `migration-stub`
+**Priority:** P2
+
+**What:** Three new `gbrain friction` subcommands deferred from v1:
+- `gbrain friction diff --base <run-or-agent> --compare <run-or-agent>` (cross-agent comparison; ~80 LOC)
+- `gbrain friction trend [--since <version-or-date>] [--phase <name>]` (time-series across runs; ~60 LOC)
+- `gbrain friction migration-stub [--threshold N]` (clusters friction by phase + tokens, emits `skills/migrations/v[N+1].md` stub; ~150 LOC)
+
+**Why:** Turns point-in-time reports into a slope. Pairs with the v1.1 public scoreboard.
+
+**Effort:** M (CC ~2h total).
+
+---
+
+### Scenario expansion — `supabase-migration` and `supervisor-restart`
+**Priority:** P2
+
+**What:** Two more scenarios under `test/fixtures/claw-test-scenarios/`:
+- `supabase-migration` — `gbrain init --pglite` then `gbrain migrate --to supabase`; verifies the cross-engine migration path
+- `supervisor-restart` — kill worker mid-job; verify supervisor recovers without data loss
+
+**Why:** These are the other highest-historical-pain regression points (per CLAUDE.md fix-wave history). v1 ships only `fresh-install` + `upgrade-from-v0.18` because Codex flagged that mixing them dilutes the fresh-install signal; v1.1 lands them as separate scenarios.
+
+**Effort:** M (CC ~1h each).
+
+---
+
+### Real v0.18 SQL dump for upgrade scenario
+**Priority:** P2
+
+**What:** The `upgrade-from-v0.18` scenario ships scaffolded — `seed/dump.sql` is missing. The harness gracefully no-ops the seed phase when absent, so the scenario currently behaves like fresh-install. v1.1: generate a real v0.18-shape PGLite dump per the procedure documented in `test/fixtures/claw-test-scenarios/upgrade-from-v0.18/seed/README.md`.
+
+**Why:** Without a real seed, the scenario doesn't actually exercise the migration chain forward-walk. That's the whole point of the upgrade scenario — proves issue #239/#243/#266/#357 class regressions stay fixed.
+
+**Effort:** S (CC ~30m once a v0.18 checkout is handy). Depends on: ability to run a v0.18 gbrain build.
+
+---
+
+### Public scoreboard — `gbrain-evals.io/friction`
+**Priority:** P3
+
+**What:** Sibling-repo PR in `garrytan/gbrain-evals` that renders friction JSONL into a public dashboard. Friction count per version per agent, line charts over time. v1's JSONL already includes `gbrain_version` + `agent` tags so the scoreboard is a thin layer on top.
+
+**Why:** Marketing surface. Proves install quality is improving release-over-release. The friction loop becomes visible to the world, not just maintainers.
+
+**Effort:** M. Depends on: a working live mode and ≥10 real friction reports.
+
+---
+
+### PTY-mode transcript capture
+**Priority:** P3
+
+**What:** `transcript-capture.ts` currently uses plain `child_process.spawn` pipes. Some agents only emit ANSI colors / progress UI on a TTY. v1.1 adds a PTY mode (likely via `node-pty`) so live-mode transcripts capture the full agent UX.
+
+**Why:** Faithful transcripts make the friction → reasoning link more useful. v1 accepts that some agent UI is lost.
+
+**Effort:** S (CC ~30m). Mostly a ~30 LOC swap inside `spawnWithCapture`.
+
+---
+
+### Read-side host-isolation (`$GBRAIN_HOST_HOME`)
+**Priority:** P3
+
+**What:** v0.22.16 confined every `~/.gbrain` write site to honor `$GBRAIN_HOME`. But `src/commands/init.ts:299-313` still reads real `~/.claude` / `~/.openclaw` / `~/.codex` / `~/.factory` / `~/.kiro` for module fingerprinting (host detection). Even with write-isolation, a claw-test running on a developer's box discovers their real installed mods. v1.1: add a separate `$GBRAIN_HOST_HOME` override for the read-side detection so the claw-test can run truly hermetic.
+
+**Why:** v1's hermeticity contract is "writes are isolated, reads are not." v1.1 closes the read-side gap.
+
+**Effort:** S (CC ~30m).
+
+---
+
+### Routing-callout sweep — annotate skills the claw-test exercises
+**Priority:** P3
+
+**What:** `skills/_friction-protocol.md` is a cross-cutting convention. v1.1: sweep the 4–6 skills the claw-test actually exercises (setup, brain-ops, query, ingest, smoke-test, the migrations the test covers) and add a `> **Convention:** see [skills/_friction-protocol.md](_friction-protocol.md).` callout via the existing `src/core/dry-fix.ts` shape so DRY auto-fix doesn't fight it.
+
+**Why:** Right now agents only call `gbrain friction log` if they find the protocol skill on their own. The callouts route them there proactively from any harness-exercised skill.
+
+**Effort:** S (CC ~15m).
+
+---
+
+## minions / worker (v0.22.14 follow-ups)
+
+### v0.22.15 — Embed cooperative-abort (HIGHEST PRIORITY — daily pain)
+**Priority:** P0
+
+**What:** Plumb `signal: AbortSignal` through `runPhaseEmbed` →
+`src/commands/embed.ts` → `embedBatch` in `src/core/embedding.ts`. Check
+`signal?.aborted` between OpenAI batch calls (every ~100 texts, ~2s
+real-time) and between slugs in the per-slug loop.
+
+**Why:** Embed phase ignores `signal.aborted` between batches today. Job
+wall-clock timeout fires → handler keeps running → cycle's finally block
+unreachable → `gbrain_cycle_locks` row stays held indefinitely. Every
+subsequent autopilot cron cycle sees `cycle_already_running` → skips. Lock
+TTL is 30 min; new cycles give up before that. Doctor reports UNHEALTHY.
+
+**The chain in production:** ~5min cron submits cycle → 22K stale pages →
+embed phase takes 10–15 min → 600s timeout fires → job dead-lettered → embed
+keeps running → lock held → all subsequent cycles skip. Garry hits this
+DAILY on his production brain.
+
+**Pros:** Closes the daily wedge. Makes timeouts actually effective. Lets
+operators bump worker timeouts confidently knowing abort actually stops
+work.
+
+**Cons:** Touching the embed hot path; small risk of botching the abort
+checks. Mitigation: between-batch granularity (~2s), not per-text (too fine)
+or per-slug (too coarse for 500+ chunk slugs).
+
+**Context:** PR #503 (v0.22.14) catches the SYMPTOM (worker stalled, queue
+piling up) via self-health-monitoring. This PR catches the CAUSE for one
+specific failure class. Both fixes are needed; they're complementary, not
+duplicative.
+
+**Files to touch:**
+- `src/core/cycle.ts:579` — `runPhaseEmbed(engine, dryRun)` → add
+  `signal?: AbortSignal` arg
+- `src/core/cycle.ts:803` — pass `opts.signal` through
+- `src/commands/embed.ts:~363` — accept signal, check between slugs
+- `src/core/embedding.ts:51-56` — `embedBatch(texts, onProgress?, signal?)`,
+  check between for-loop iterations of `BATCH_SIZE` slices
+
+**Tests required:**
+1. embedBatch checks signal between OpenAI calls; aborts within one batch (~2s)
+2. Per-slug loop in `embed.ts` checks signal between slugs
+3. End-to-end: cycle handler with embed phase + signal aborted mid-flight →
+   finally runs → `gbrain_cycle_locks` row deleted
+4. Regression: 1K+ chunks scenario — embed does NOT block lock release when
+   timeout fires
+
+**Effort:** M (human: ~3 hr / CC: ~30 min).
+
+**Depends on / blocked by:** Nothing. v0.22.14 ships first.
+
+### v0.23+ — Bare-worker engine reconnect parity with supervisor
+**Priority:** P2
+
+**What:** Extract the supervisor's reconnect-then-fail pattern into
+`MinionWorker` so bare workers can retry transient DB blips before exiting.
+Today the supervisor calls `engine.reconnect()` after 3 consecutive DB health
+failures (#406); the bare worker just emits `'unhealthy'` and the CLI calls
+`process.exit(1)`.
+
+**Why:** Bare-worker behavior is more disruptive than supervised behavior on
+transient PgBouncer blips. A bare worker restarts the entire process; a
+supervised worker just reconnects the pool. Operationally the supervisor
+approach is gentler (no in-flight job loss, no PM restart latency).
+
+**Pros:** Unifies bare and supervised behavior. Reduces process churn on
+transient network blips.
+
+**Cons:** More code in MinionWorker; risk of reconnect masking a real
+problem. Mitigation: cap retry attempts, fall through to `'unhealthy'`
+emission after the cap.
+
+**Context:** Filed during v0.22.14 plan-eng-review. The asymmetry is
+documented in v0.22.14 CHANGELOG as deliberate; this TODO captures the
+"unify someday" intent.
+
+**Effort:** S (human: ~2 hr / CC: ~20 min).
+
+**Depends on / blocked by:** Nothing.
+
+### v0.23+ — `minion_workers` heartbeat table for queue_health doctor (B7)
+**Priority:** P3
+
+**What:** Add a `minion_workers` table (`worker_id` PK, `hostname`,
+`last_heartbeat`, `queue`, `concurrency`, `started_at`) so the existing
+`queue_health` doctor check (Postgres path) can detect dead workers via
+heartbeat staleness instead of relying on the indirect `lock_until` proxy.
+
+**Why:** v0.19.1 added `queue_health` checks for stalled-active jobs and
+waiting-depth threshold. The worker-heartbeat subcheck was deferred (B7)
+because the `lock_until`-on-active-jobs proxy can't distinguish "worker
+exited cleanly" from "worker idle" — a check that cries wolf erodes trust
+in every doctor check. With a real heartbeat row, doctor can say "no worker
+seen in N intervals" with confidence.
+
+**Pros:** Doctor's `queue_health` becomes ground-truth. Detects "worker
+container died but cron didn't restart it" scenario.
+
+**Cons:** New table, schema migration, every health-tick UPSERTs. Costs
+a write per worker per minute (default).
+
+**Context:** Filed during v0.22.14 plan-eng-review. PR #503's self-health
+monitoring is the worker-side liveness; this would be the queue-side
+ground-truth.
+
+**Effort:** M (human: ~1 day / CC: ~1 hr).
+
+**Depends on / blocked by:** Schema migration system; nothing else.
+
+## sync (v0.22.13 follow-up — PR #490 review)
+
+### D-PR490-1 — Plumb resolved `database_url` through `SyncOpts`
+**Priority:** P3
+
+**What:** Add `database_url?: string` (or a richer `resolvedConnection` shape) to
+`SyncOpts` and have the caller (`runSync`, the cycle handler, the jobs handler)
+populate it from the active engine instead of having `performSync` /
+`performFullSync` / `import.ts` each call `loadConfig()` separately. Today every
+sync run hits the config file three times.
+
+**Why:** v0.18 multi-source brains can in principle run different sources against
+different `database_url` endpoints (or different per-source overrides via
+`sources.config_jsonb`). Right now `loadConfig()` returns the global config, and
+that always matches the engine in practice — but the convention papers over a
+real divergence the moment someone wants per-source connection settings. Folding
+the resolution into `SyncOpts` makes the worker-engine creation in `sync.ts` and
+`import.ts` deterministic from `SyncOpts` alone.
+
+**Pros:**
+- Removes 3 redundant `loadConfig()` calls per sync.
+- Makes `performSync` / `performFullSync` side-effect-free with respect to the
+  on-disk config file.
+- Sets up for per-source `database_url` overrides without further refactor.
+- Makes the v0.22.13 belt-and-suspenders fallback (PR #490 Q3) cleaner — no
+  more `!config?.database_url` short-circuit inside the parallel branch.
+
+**Cons:**
+- API-shape change to `SyncOpts` (mild; not externally exported).
+- Touching three callers (`runSync`, jobs handler, `cycle.ts` `runPhaseSync`).
+- Only worth doing when paired with a per-source override story; otherwise
+  it's just plumbing.
+
+**Context:** Surfaced during the PR #490 plan-eng-review (parallel sync).
+Deferred because it isn't on the v0.22.13 critical path. The same pattern would
+benefit the cycle handler and the autopilot daemon. See the plan-eng-review
+decisions log: A4 = "Defer; file as TODO."
+
+**Depends on / blocked by:** Nothing structural. Best paired with the v0.18
+per-source `config_jsonb` work if/when that lands.
+
+## sync error-code classification (PR #501 follow-ups)
+
+### Plumb structured `ParseValidationCode` through `ImportResult`
+**Priority:** P2
+
+**What:** Replace the regex-on-error-message path in `src/core/sync.ts:classifyErrorCode`
+with a structured `code` field threaded through `ImportResult` from the parse layer.
+
+Three changes:
+1. `src/core/import-file.ts:362` — call `parseMarkdown(content, relativePath, { validate: true, expectedSlug })`
+   so `parsed.errors[0].code` is populated.
+2. `src/core/import-file.ts` — add `code?: string` to `ImportResult`. Promote the
+   structured code (or `'SLUG_MISMATCH'` when the existing expectedSlug check trips)
+   into the result envelope alongside `error`.
+3. `src/commands/sync.ts:488` — extend `failedFiles` shape with `code?: string`.
+   `recordSyncFailures` already accepts the field; the only thing missing is the
+   capture site populating it.
+4. `src/core/sync.ts:classifyErrorCode` — keep as a fallback for un-coded errors
+   (DB exceptions, generic catches). Primary path reads the structured code.
+
+**Why:** The repo already has `ParseValidationCode` + `ParseValidationError` in
+`src/core/markdown.ts:5-18`, and three other consumers (`src/commands/lint.ts:72`,
+`src/commands/frontmatter.ts:148`, `src/core/brain-writer.ts:314`) read structured
+errors directly. Sync is the outlier — it calls `parseMarkdown` without validation
+and reverse-engineers codes via regex. PR #501 shipped that regex out of pragmatism;
+this TODO removes ~50% of `classifyErrorCode` and eliminates a class of false-positives.
+
+**Pros:**
+- One source of truth for parse codes (the enum in `markdown.ts`).
+- Eliminates regex fragility — adding a new validation code in `markdown.ts`
+  automatically flows to sync without a new regex.
+- Closes the case where canonical messages (`File is empty...`, `No closing ---...`)
+  don't match aspirational regex patterns.
+
+**Cons:** Touches `ImportResult` interface, which ripples through `src/commands/import.ts:105`,
+`src/commands/sync.ts:498-510`, `src/core/cycle.ts`, brain-writer reconciler.
+
+**Context:** PR #501 documented this as P3 in the eng review at
+`~/.claude/plans/then-codex-synchronous-toucan.md`. Codex's outside-voice review
+agreed independently. The fix is small — ~50 lines including tests + downstream
+call sites — and it's the correct architectural endpoint.
+
+**Effort:** M (human: ~2 hr / CC: ~20 min).
+
+**Depends on / blocked by:** Nothing.
+
+### CHANGELOG migration note for `acknowledgeSyncFailures()` shape change
+**Priority:** P0 — required at /ship time
+
+**What:** When PR #501 ships, the release CHANGELOG entry MUST include this
+`### For contributors` block:
+
+```markdown
+### For contributors
+
+`acknowledgeSyncFailures()` now returns `{count, summary}` instead of `number`.
+If you import this directly from `gbrain/sync`, replace `n` with `result.count`
+and use `result.summary` for the new code-grouped breakdown.
+```
+
+**Why:** The function is exported from `src/core/sync.ts:433` and reachable via
+the package exports map. External TS consumers (gbrain-evals, host agent forks)
+that imported it got `number` and now get an object — silent type break.
+
+**Effort:** XS (human: ~1 min). Just don't forget.
+
+**Depends on / blocked by:** PR #501 ship.
+
+### Concurrent-safe ack of `~/.gbrain/sync-failures.jsonl`
+**Priority:** P3
+
+**What:** Two concurrent `gbrain sync` runs hitting `acknowledgeSyncFailures()`
+can clobber each other. The function does a whole-file `writeFileSync` rewrite
+(`src/core/sync.ts:433-455`); `recordSyncFailures()` does independent
+`appendFileSync` (`src/core/sync.ts:395-416`). Concurrent ack + append can lose rows.
+
+**Why:** Pre-existing — predates PR #501. Real risk only on autopilot setups where
+multiple sync invocations might overlap (rare today, more likely as multi-source
+sync matures).
+
+**Fix sketch:** Atomic rename pattern (write to `sync-failures.jsonl.tmp`, then
+`renameSync`) plus a file lock for the read-modify-write cycle. Or move the
+acknowledged-set to the DB.
+
+**Effort:** S (human: ~1 hr / CC: ~10 min).
+
+**Depends on / blocked by:** Nothing.
+
+## test-infra
+
+### Parallel-load timeout flake on v0.21 PGLite-heavy tests
+**Priority:** P0
+
+**What:** 22 tests added in v0.21.0 (Code Cathedral II) consistently fail in the full `bun test` run with timeout-pattern elapsed times of 7-10s, but pass in isolation. Every failing test calls `engine.initSchema()` in `beforeAll` without a timeout extension. Under parallel load (168 test files now run concurrently after v0.21 added ~24 new files), `initSchema` exceeds bun's default 5s `beforeAll` timeout.
+
+Affected files include (non-exhaustive): `test/sync-strategy.test.ts`, `test/cathedral-ii-brainbench.test.ts`, `test/code-edges.test.ts`, `test/reindex-code.test.ts`, `test/reconcile-links.test.ts`, `test/two-pass.test.ts`, `test/parent-symbol-path.test.ts`, `test/pglite-v0_19.test.ts`.
+
+**Why:** Currently triaged as "skip pre-existing, ship anyway" but that's not a real fix. Blocks /ship for anyone whose CHANGELOG-time test run sees them.
+
+**Pros:** Fixing it lets /ship run cleanly without manual triage every release.
+
+**Cons:** ~22 file edits adding `beforeAll(async () => {...}, 30000)` is mechanical but dull.
+
+**Context:** Same pattern fixed in v0.20.5 wave for `test/e2e/minions-shell-pglite.test.ts`. Single-file repro: each fails in `bun test`, passes in `bun test <file>`. Reproduces with my changes stashed, so it's on master.
+
+**Effort:** S (human: ~30 min / CC: ~5 min). Mechanical: grep for `beforeAll(async () => {` in affected files, add `, 30000)` argument.
+
+**Depends on / blocked by:** Nothing.
+
+## resolver / check-resolvable (v0.22.4 follow-ups)
+
+### D10 — Extend `check-resolvable` to parse RESOLVER.md disambiguation rules
+**Priority:** P2
+
+**What:** Extend `src/core/check-resolvable.ts:357-390` to parse a structured
+disambiguation block in `RESOLVER.md` (e.g. a `## Disambiguation rules`
+numbered list with parseable `<trigger>` → `<winning-skill>` shape) and treat
+resolved overlaps as non-issues. Then the action message at
+`src/core/check-resolvable.ts:388` ("Add disambiguation rule in RESOLVER.md OR
+narrow triggers") stops lying about the OR — currently only the second branch
+silences the warning.
+
+**Why:** The current MECE-overlap fix path forces authors to delete user-facing
+triggers from skill frontmatter. That's wrong for cases where two skills
+legitimately respond to the same phrase under different contexts (e.g.
+"citation audit" → focused fix vs broader brain health). A real
+disambiguation parser would let `RESOLVER.md` carry the resolution while
+keeping both skills' triggers intact for chaining.
+
+**Pros:**
+- The action message stops misleading users.
+- v0.22.4 D2 used the "narrow triggers" path because the disambiguation
+  parser doesn't exist yet; landing this would let v0.23+ keep dual triggers
+  for genuinely-overlapping skills.
+- Aligns RESOLVER.md's stated role (the dispatcher) with what the checker
+  actually reads.
+
+**Cons:**
+- Introduces a new `RESOLVER.md` syntactic contract that other tooling now
+  has to respect (parser, lint, downstream forks reading the same file).
+- Risk of false-positive resolution if the parser is loose.
+- ~80 lines of parser + tests; not blocking anything in v0.22.4.
+
+**Context:**
+- The "OR" in the action message is misleading today. Confirmed at
+  `src/core/check-resolvable.ts:388`.
+- The MECE detector loop is at `src/core/check-resolvable.ts:357-390`.
+- The disambiguation rules already exist as prose in
+  `skills/RESOLVER.md` (the citation-audit row added in v0.22.4 is the
+  pattern). They're agent-facing routing hints today, not parsed structure.
+
+**Effort:** S (human: ~4-6 hours / CC: ~30 min for parser + 12-16 test cases).
+
+**Depends on / blocked by:** Nothing.
+
+## code-indexing (v0.21.0 Cathedral II follow-ups)
+
+### B2 — Magika auto-detect for extension-less files (Layer 9 deferred)
+**Priority:** P2
+
+**What:** Embed Google's Magika ML classifier (~1MB ONNX) as a bundled asset. Wire into `detectCodeLanguage` as the fallback for files with no recognized extension (Dockerfile, Makefile, `.envrc`, shell scripts with shebangs but no `.sh`). The chunker already has `setLanguageFallback(fn)` as a module-level hook.
+
+**Why:** v0.20.0 widens the file classifier from 9 to 35 extensions (Layer 2), covering most real-world cases. Extension-less files still slip through to recursive chunks. Magika would close the last common case.
+
+**Pros:** Completes the file-classification story. Unblocks chunker on real-world configs + build scripts.
+
+**Cons:** ~1MB asset bundled with `bun --compile`. Integration risk: Magika's ONNX runtime needs WASM compat with bun. The plan explicitly allowed deferring B2 because bundling surprises late in implementation are costly.
+
+**Context:**
+- `src/core/chunkers/code.ts` exports `setLanguageFallback(fn: LanguageFallback | null)` — call at process start with a Magika-powered classifier.
+- `detectCodeLanguage(filePath, content?)` already accepts optional content for fallback paths.
+- The NPM `magika` package is the first thing to try; needs bun-compile compatibility verification.
+
+**Effort:** M (human: ~2-3 days / CC: ~2 hours for the integration + CI guard).
+
+**Depends on / blocked by:** Nothing. Hook is in place as of v0.20.0.
+
+### A4 — full doc_comment extraction at chunk time
+**Priority:** P2
+
+**What:** When the chunker emits a method/class/function, look at the comment node(s) immediately preceding the declaration and persist them as `content_chunks.doc_comment`. The FTS trigger from Layer 1b already weights `doc_comment` 'A' above `chunk_text` 'B' — the ranking is ready, the column is populated NULL today.
+
+**Why:** "how does X handle N+1" should rank the docstring that explains N+1 above the function body or any prose paragraph. Layer 1b paved the ranking half; extraction is the remaining half.
+
+**Pros:** Material MRR lift on natural-language queries. Zero schema work (column + trigger already in place).
+
+**Cons:** Per-language convention detection — JSDoc blocks, Python docstrings (first string expression in a function body), C-style doc comments, etc. Not hard but each language has edge cases.
+
+**Context:**
+- `src/core/chunkers/code.ts` emits chunks in `chunkCodeTextFull`. Walk each declaration's preceding sibling(s) for comment nodes.
+- ChunkInput already has `doc_comment?: string`. Populate at chunk time and it flows through `upsertChunks` (Layer 6 wired those columns).
+- Per-language config: leading-comment type names per language (`comment`, `line_comment`, `block_comment`, `documentation_comment`).
+- Test hook: `test/cathedral-ii-brainbench.test.ts` has a `doc_comment_matching` placeholder — flesh it out end-to-end.
+
+**Effort:** M (human: ~2 days / CC: ~90 min for the 8 Layer-5 langs).
+
+**Depends on / blocked by:** Nothing. Layer 1b + Layer 6 both in place.
+
+### C6 — gbrain code-signature "(A, B) => C"
+**Priority:** P3 (stretch)
+
+**What:** Type-signature retrieval via tree-sitter type captures per language. "Find every function whose signature returns a Promise<User>" or "(string, number) => boolean".
+
+**Why:** Each language's type system is its own mini-cathedral. Ship per-language rather than as one item.
+
+**Effort:** L per language (typescript-first).
+
+**Depends on / blocked by:** Nothing — additive on the Layer 5 edge schema.
+
+### Cross-file edge resolution (Layer 5 precision upgrade)
+**Priority:** P3
+
+**What:** Today every call edge lands unresolved in `code_edges_symbol` with to_symbol_qualified = bare callee name. Second-pass resolution: after all code files import, walk every `code_edges_symbol` row and try to resolve `to_symbol_qualified` via `symbol_name_qualified` join; if found within the same source, write a resolved row to `code_edges_chunk`.
+
+**Why:** `getCallersOf("searchKeyword")` currently returns the Layer 6 ambiguity — every `searchKeyword` call site in any class. Receiver-type analysis lifts this.
+
+**Effort:** L. Needs receiver-type inference; can ship per-language.
+
+**Depends on / blocked by:** Nothing — UNION-on-read path keeps unresolved edges surfaced even without this.
+
+## P3 — Dev experience: test suite parallelism on fast multi-core machines
+
+**Context:** `bun test` on M-series Macs spawns ~1 worker per core. `test/dream.test.ts` (5 describe blocks, 11 tests) and `test/orphans.test.ts` create a fresh PGLite engine in `beforeEach` that runs ~20 schema migrations per test. Under parallel load, WASM-instance contention causes ~18 `beforeEach` timeouts at 5–9s.
+
+**Evidence:** CI (ubuntu-latest, fewer cores) is green on every PR. Running the suspect files in isolation (`bun test test/dream.test.ts test/orphans.test.ts`) is also green. Reproduces only on fast multi-core local machines running the full 136-file parallel suite.
+
+**Fix:** move engine creation from `beforeEach` to `beforeAll` per describe block; add a data-reset helper (delete-all-rows-in-relevant-tables) between tests. ~80 LOC change across two test files.
+
+**Priority:** P3 because production CI is unaffected. Hits local dev iteration speed on fast Macs.
+
+**Found:** 2026-04-24 during v0.19.0 production-readiness review.
+
 ## Completed
 
 ### ~~Checks 5 + 6 for check-resolvable~~
@@ -408,3 +963,135 @@ iteration's residuals.
 
 ### Implement AWS Signature V4 for S3 storage backend
 **Completed:** v0.6.0 (2026-04-10) — replaced with @aws-sdk/client-s3 for proper SigV4 signing.
+
+### Caller-opt-in retry for `executeRaw` (D3 follow-up from v0.22.1)
+**What:** Add `PostgresEngine.executeRawIdempotent(sql, params)` (or a `{retry: true}` parameter flag on `executeRaw`) so callers explicitly opt into auto-retry for statements they know are idempotent. Audit existing call sites and migrate the read-only ones (search, page fetches, etc.) to the new method.
+
+**Why:** Closes the gap left by D3's drop-the-wrapper decision in v0.22.1. The original #406 wrapped `executeRaw` in a regex-gated retry that was unsound for writable CTEs and side-effecting SELECTs. Recovery moved up to the supervisor watchdog, but per-call recovery for reads (the bulk of `executeRaw` traffic from MCP, search, page fetches) is gone. A caller-opt-in flag puts the idempotency decision where it belongs (at the call site, with full statement context).
+
+**Pros:** Restores per-call auto-recovery for reads without the phantom-write risk on mutations. Explicit > clever: each call site declares its own idempotency posture. Future caller-added mutations get safe-by-default behavior.
+
+**Cons:** Touches every existing `executeRaw` call site (~25). Requires careful audit — accidentally tagging a mutation as idempotent re-introduces the phantom-write bug.
+
+**Context:** Codex F3 demonstrated that `READ_ONLY_PREFIX = /^(\s|--.*\n)*(SELECT|WITH)\b/i` is unsound — `WITH x AS (UPDATE … RETURNING …) SELECT …` matches the prefix but updates a row; `SELECT pg_advisory_xact_lock(...)` is a SELECT with side effects. The plan-eng-review wrap-up in `~/.claude/plans/system-instruction-you-are-working-tender-horizon.md` has the full discussion.
+
+**Effort estimate:** M (human: ~1 day / CC: ~30 min including call-site audit).
+**Priority:** P2 — current behavior (no retry, supervisor recovers within ~3 min) is acceptable but per-call recovery is a real ergonomic win.
+**Depends on:** Nothing.
+
+### Replace `walkMarkdownFiles` with `engine.getAllSlugs()` in `extractForSlugs` (F1 follow-up from v0.22.1)
+**What:** The cycle path's `extractForSlugs()` at `src/commands/extract.ts:455` still does a `walkMarkdownFiles(brainDir)` to build the `allSlugs` set for link resolution. On a 54K-page brain that's a single `readdir` traversal (~hundreds of ms — acceptable, dominated by the file-content-read elimination from #417). But `engine.getAllSlugs()` exists at `extract.ts:728` and produces the same set via a single SQL query (~tens of ms).
+
+**Why:** Eliminates the residual directory walk on every cycle. Codex F1 noted that the v0.22.1 plan's "cycle never re-walks the whole tree again" claim was overstated — it stops READING file contents but still walks the directory. This TODO closes that gap honestly.
+
+**Pros:** Cycle becomes O(slugs sync touched), not O(total brain size). No more readdir on a growing brain. ~5 LOC change.
+
+**Cons:** Crosses an FS-vs-DB consistency boundary in the FS-source extract path. Edge case: a file deleted from disk but still in DB. Currently `extractForSlugs` skips with `if (!existsSync(fullPath)) continue` — unchanged. But if a markdown file references a slug whose page exists in DB but file was deleted, the link would resolve via DB but the original extractor caught it. Needs a careful test for this case.
+
+**Context:** Codex plan-review during v0.22.1 wrap, verified at `extract.ts:455-456`. The plan-eng-review session captured the rationale.
+
+**Effort estimate:** S (human: ~2 hr / CC: ~10 min including the consistency-edge-case test).
+**Priority:** P3 — pure perf, no correctness gap.
+**Depends on:** Nothing.
+
+### `err.code`-based connection-error matching in `postgres-engine.ts` (B1 follow-up from v0.22.1)
+**What:** The CONNECTION_ERROR_PATTERNS array (~12 strings: `ECONNREFUSED`, `connection terminated`, `password authentication failed`, etc.) matched against `err.message` and `err.code`. Replace with structured matching against `err.code` only, using postgres.js's typed error classes (`PostgresError` with structured codes).
+
+**Why:** String matching against error messages breaks on library upgrades (postgres.js could change its error message phrasing without bumping major). Code matching is durable. The Layer 1 cleanup follows: gbrain itself doesn't define connection-error codes; it should defer to postgres.js's classification.
+
+**Pros:** More durable across library updates. Less code (drop the 12-string array). Follows the typed-errors pattern v0.21.0 introduced (`src/core/errors.ts`).
+
+**Cons:** Requires verifying which `err.code` values postgres.js actually exposes for each connection-failure mode. May need fallback to message-substring matching for codes that postgres.js doesn't surface.
+
+**Context:** Section 2/B1 from the v0.22.1 plan-eng-review. After D3 dropped the per-call retry, `isConnectionError` is no longer in the hot path — only the supervisor watchdog cares about classifying connection errors, and it currently catches *anything*. This TODO is a cleanup pass when someone next touches that surface.
+
+**Effort estimate:** S (human: ~2 hr / CC: ~10 min).
+**Priority:** P3.
+**Depends on:** The above caller-opt-in retry (#1) is the natural co-lander since both touch the same error-classification surface.
+
+## remote MCP / HTTP transport (v0.22.7 follow-ups)
+
+### Audit-log write amplification on rejected `/mcp` traffic
+**What:** `src/mcp/http-transport.ts` writes a row to `mcp_request_log` for every
+incoming `/mcp` request, including rate-limited (429), oversized (413), and
+auth-failed (401) traffic. Under sustained attack the IP rate limit caps audit
+writes per IP at 30/min, but at scale (10K distinct IPs) that's still 300K
+inserts/min. Two follow-ups: (1) instrument the audit-write rate so we can see
+the actual production volume; (2) consider a separate "rejected" table or
+sampling for failed-auth rows so the success-path audit table doesn't get
+swamped.
+
+**Why:** Codex flagged this during the v0.22.7 ship adversarial review. We kept
+the full audit on purpose — forensic data of an attack is valuable — but want
+to revisit once we have real volume numbers.
+
+**Pros:** Bounds DB write volume under attack. Keeps the success-path audit
+table small enough for fast queries.
+
+**Cons:** Adds a second table or a sampling rule. Not free complexity. Probably
+not worth it until production hits a real attack pattern.
+
+**Context:** `src/mcp/http-transport.ts:222,235,245` (the three audit-on-reject
+call sites) + `src/schema.sql:342` (the unbounded table).
+
+**Effort estimate:** M (human: ~half day / CC: ~30 min once we have volume data).
+**Priority:** P3 — wait for evidence.
+**Depends on:** Production telemetry on `mcp_request_log` insert rate.
+
+### `validateParams` doesn't check enum values or array item types
+**What:** `src/mcp/dispatch.ts:27` (extracted from `src/mcp/server.ts` in
+v0.22.7) only checks top-level JS types. Operations declare `enum` constraints
+(e.g. `direction: 'in' | 'out' | 'both'`) and array `items: { type: ... }`
+schemas in `src/core/operations.ts`, but `validateParams` ignores both. Bad
+inputs still reach handlers — concretely, an invalid `direction` falls through
+the engine's else branch at `src/core/postgres-engine.ts:954`, widening
+traversal unexpectedly; malformed `pages_updated` arrays could be written as
+garbage JSONB.
+
+**Why:** Codex flagged this during the v0.22.7 ship adversarial review. The
+validator was lifted verbatim from the pre-existing stdio path during the
+dispatch.ts extraction — same gap exists on the stdio MCP server today, so
+this isn't a v0.22.7 regression. Still worth tightening, since "shared
+validation" is now the architectural guarantee both transports rely on.
+
+**Pros:** Better defense-in-depth at the MCP boundary. Catches malformed agent
+inputs before the engine layer has to.
+
+**Cons:** Need to walk every operation's param schema and decide which enum
+violations are user-facing errors vs internal bugs. May need a typed Zod-style
+schema layer to do this cleanly.
+
+**Context:** `src/mcp/dispatch.ts:27` + `src/core/operations.ts` (param defs).
+Same gap pre-existed on stdio MCP path.
+
+**Effort estimate:** M (human: ~half day / CC: ~30 min if we use the existing
+ParamDef shape; XL if a Zod migration is the chosen direction).
+**Priority:** P2.
+**Depends on:** Whether we want to keep the lightweight ParamDef shape or
+migrate to typed schemas.
+
+### Streaming MCP tool support (re-add SSE based on Accept header)
+**What:** v0.22.7 dropped SSE entirely from `gbrain serve --http` because no
+current MCP tool streams. When the first streaming tool ships (long-running
+agent delegation as an MCP tool, `resources/subscribe`, `sampling/createMessage`),
+re-add SSE in `/mcp` based on the `Accept` header per the Streamable HTTP
+transport spec. ~30 lines + spec compliance test.
+
+**Why:** Removing SSE simplified the v0.22.7 transport (one response path,
+fewer test cases). Adding it back when actually needed is cheap and keeps the
+code lean in the meantime.
+
+**Effort estimate:** S (human: ~2 hr / CC: ~15 min).
+**Priority:** P3 — wait for the first streaming tool.
+**Depends on:** A streaming MCP tool actually existing.
+
+### `access_tokens.scopes` enforcement
+**What:** The `access_tokens` schema has had a `scopes TEXT[]` column since
+migration v4 (`src/core/migrate.ts:84`), but nothing enforces it. v0.22.7's
+`gbrain auth create` doesn't accept a `--scopes` flag, and `dispatchToolCall`
+doesn't gate on scopes. Adding per-tool scope enforcement would let
+"claude-desktop-readonly" and "ingest-only" tokens exist.
+
+**Effort estimate:** M (human: ~1 day / CC: ~30 min for the schema-aware gate).
+**Priority:** P3.
+**Depends on:** Nothing.

VERSION

@@ -1 +1 @@
-0.20.2
+0.24.0

bun.lock

@@ -7,6 +7,7 @@
       "dependencies": {
         "@anthropic-ai/sdk": "^0.30.0",
         "@aws-sdk/client-s3": "^3.1028.0",
+        "@dqbd/tiktoken": "^1.0.22",
         "@electric-sql/pglite": "0.4.3",
         "@modelcontextprotocol/sdk": "^1.0.0",
         "gray-matter": "^4.0.3",
@@ -14,9 +15,12 @@
         "openai": "^4.0.0",
         "pgvector": "^0.2.0",
         "postgres": "^3.4.0",
+        "tree-sitter-wasms": "0.1.13",
+        "web-tree-sitter": "0.22.6",
       },
       "devDependencies": {
         "@types/bun": "latest",
+        "bun-types": "^1.3.13",
         "typescript": "^5.6.0",
       },
     },
@@ -107,6 +111,8 @@
 
     "@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.2.4", "", {}, "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ=="],
 
+    "@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=="],
@@ -215,7 +221,7 @@
 
     "@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/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=="],
 
@@ -237,7 +243,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=="],
 
@@ -453,13 +459,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=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
     "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
 
@@ -467,6 +475,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=="],
@@ -479,30 +489,32 @@
 
     "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=="],
-
-    "bun-types/@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
+    "@types/bun/bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
 
     "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

@@ -3,4 +3,10 @@
 # Default 5s is too short when many test files boot PGLite instances at once.
 # 60s is the empirical ceiling we observed before the first file's beforeAll
 # completed on a loaded machine.
+#
+# NOTE: this bunfig.toml `timeout` key is read by `bun test` but empirically
+# does NOT apply to beforeEach/afterEach hook timeouts under `bun run test`
+# chained behind `bun run typecheck`. The test script in package.json passes
+# `--timeout=60000` explicitly to cover both per-test and per-hook timeouts.
+# Leaving both in place as belt-and-suspenders.
 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/UPGRADING_DOWNSTREAM_AGENTS.md

@@ -458,6 +458,75 @@ 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

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/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/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/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/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,8 +1,13 @@
 # Deploy GBrain Remote MCP Server
 
+> **v0.22.7+:** Use `gbrain serve --http` for remote access. It includes built-in
+> bearer token auth, default-deny CORS, two-bucket rate limiting, body cap, and
+> per-request audit log. **Postgres-only** (PGLite is local-only by design).
+> See [SECURITY.md](../../SECURITY.md) for env vars and tunable defaults.
+
 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.
+via `gbrain serve` (stdio). For remote access, expose it via the built-in HTTP
+transport behind a public tunnel.
 
 ## Two Paths
 
@@ -13,21 +18,23 @@ 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 (any device, any AI client) — 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
 
@@ -46,13 +53,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
@@ -68,7 +75,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
 ```
@@ -96,7 +103,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.

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/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.

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-full.txt

@@ -56,9 +56,16 @@ writing or reviewing an operation, consult `src/core/operations.ts` for the cont
 
 ## Before shipping
 
-Run `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.
+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
 
@@ -101,24 +108,33 @@ strict behavior when unset.
 
 ## Key files
 
-- `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`. `OperationContext.remote` flags untrusted callers.
+- `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`, plus `matchesSlugAllowList(slug, prefixes)` (v0.23 glob matcher: `<prefix>/*` matches recursive children; bare `<prefix>` matches exact only). `OperationContext.remote` flags untrusted callers; `OperationContext.allowedSlugPrefixes` (v0.23) is the trusted-workspace allow-list set by the dream cycle. `put_page` enforces: when `viaSubagent` and `allowedSlugPrefixes` is set, slug must match the allow-list; else the legacy `wiki/agents/<id>/...` namespace check applies. Auto-link enabled for trusted-workspace writes (skipped only when `remote=true && !trustedWorkspace`).
 - `src/core/engine.ts` — Pluggable engine interface (BrainEngine). `clampSearchLimit(limit, default, cap)` takes an explicit cap so per-operation caps can be tighter than `MAX_SEARCH_LIMIT`. Exports `LinkBatchInput` / `TimelineBatchInput` for the v0.12.1 bulk-insert API (`addLinksBatch` / `addTimelineEntriesBatch`). As of v0.13.1, `BrainEngine` has a `readonly kind: 'postgres' | 'pglite'` discriminator so migrations (`src/core/migrate.ts`) and other consumers can branch on engine without `instanceof` + dynamic imports.
 - `src/core/engine-factory.ts` — Engine factory with dynamic imports (`'pglite'` | `'postgres'`)
-- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly.
+- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly. v0.22.0: `searchKeyword` and `searchKeywordChunks` multiply `ts_rank` by the source-factor CASE expression at the chunk-grain level; `searchVector` becomes a two-stage CTE — inner CTE keeps `ORDER BY cc.embedding <=> vec` so HNSW stays usable, outer SELECT re-ranks by `raw_score * source_factor`. Inner LIMIT scales with offset to preserve pagination contract. As of v0.22.6.1, `initSchema()` calls `applyForwardReferenceBootstrap()` BEFORE replaying SCHEMA_SQL — probes for the specific forward-referenced state the embedded schema blob needs (`pages.source_id`, `links.link_source`, `links.origin_page_id`, `content_chunks.symbol_name`, `content_chunks.language`, `sources` FK target table) and adds only what's missing. Closes the upgrade-wedge bug class that bit users 10+ times across 6 schema versions over 2 years (#239/#243/#266/#357/#366/#374/#375/#378/#395/#396). No-op on fresh installs and modern brains.
 - `src/core/pglite-schema.ts` — PGLite-specific DDL (pgvector, pg_trgm, triggers)
-- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query.
+- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query. v0.22.0: `searchKeyword`, `searchKeywordChunks`, and `searchVector` apply source-aware ranking by inlining the source-factor CASE and `NOT (col LIKE …)` hard-exclude clause from `src/core/search/sql-ranking.ts`. `searchVector` switches to a two-stage CTE (HNSW-safe inner ORDER BY, source-boost re-rank in the outer SELECT) and carries `p.source_id` through inner→outer for v0.18 multi-source callers. v0.22.1 (#406): `_savedConfig` retains the connect config; `reconnect()` tears down + recreates the pool from saved config (called by supervisor watchdog after 3 consecutive health-check failures). `executeRaw` is a single-statement passthrough — no per-call retry (D3 dropped that as unsound for non-idempotent statements; recovery is supervisor-driven). v0.22.1 (#363, contributed by @orendi84): `connect()` applies `resolveSessionTimeouts()` from `db.ts` as connection-time startup parameters (`statement_timeout`, `idle_in_transaction_session_timeout`) so orphan pgbouncer backends can't hold locks for hours. v0.22.1 (#409, contributed by @atrevino47): `countStaleChunks()` + `listStaleChunks()` server-side-filter on `embedding IS NULL` for `embed --stale`, eliminating ~76 MB/call client-side pull on a fully-embedded brain; `upsertChunks()` resets both `embedding` AND `embedded_at` to NULL when chunk_text changes without a new embedding (consistency). As of v0.22.6.1, `initSchema()` calls `applyForwardReferenceBootstrap()` BEFORE replaying SCHEMA_SQL on the same forward-reference probe set as the PGLite engine, so old Postgres brains pinned at v0.13/v0.18/v0.19 walk forward cleanly instead of wedging on `column "..." does not exist`.
 - `src/core/utils.ts` — Shared SQL utilities extracted from postgres-engine.ts. Exports `parseEmbedding(value)` (throws on unknown input, used by migration + ingest paths where data integrity matters) and as of v0.12.3 `tryParseEmbedding(value)` (returns `null` + warns once per process, used by search/rescore paths where availability matters more than strictness).
-- `src/core/db.ts` — Connection management, schema initialization
+- `src/core/db.ts` — Connection management, schema initialization. v0.22.1 (#363, contributed by @orendi84): `resolveSessionTimeouts()` returns `statement_timeout` + `idle_in_transaction_session_timeout` (defaults: 5min each, env-overridable via `GBRAIN_STATEMENT_TIMEOUT` / `GBRAIN_IDLE_TX_TIMEOUT` / `GBRAIN_CLIENT_CHECK_INTERVAL`). Both `connect()` (module singleton) and `PostgresEngine.connect()` (worker pool) consume the result via postgres.js's `connection` option, sending GUCs as startup parameters that survive PgBouncer transaction mode (unlike the prior `setSessionDefaults` post-pool SET, kept as a back-compat no-op shim).
 - `src/commands/migrate-engine.ts` — Bidirectional engine migration (`gbrain migrate --to supabase/pglite`)
 - `src/core/import-file.ts` — importFromFile + importFromContent (chunk + embed + tags)
-- `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion)
+- `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion). v0.22.12 (#500, foundation by @wintermute via #501): `classifyErrorCode(errorMsg)` regex-based classifier with 12 codes (`SLUG_MISMATCH`, `YAML_PARSE`, `YAML_DUPLICATE_KEY`, `MISSING_OPEN`, `MISSING_CLOSE`, `NESTED_QUOTES`, `EMPTY_FRONTMATTER`, `NULL_BYTES`, `INVALID_UTF8`, `STATEMENT_TIMEOUT`, `FILE_TOO_LARGE`, `SYMLINK_NOT_ALLOWED`) plus `UNKNOWN` fallback. `summarizeFailuresByCode(failures)` returns sorted `[{code, count}]`. `code?` optional field on `SyncFailure`; backfilled at ack time on pre-v0.22.12 entries. `acknowledgeSyncFailures()` returns `AcknowledgeResult { count, summary }`. Three regexes (`MISSING_OPEN`, `MISSING_CLOSE`, `EMPTY_FRONTMATTER`) broadened to match actual `markdown.ts:159-244` validator message strings, not just the literal code-name prefix. `FILE_TOO_LARGE` covers all three production size sites in `import-file.ts:199, 352, 401`; `SYMLINK_NOT_ALLOWED` covers the rejection at `:347`. Closes the silent-skip pattern that motivated #500.
 - `src/core/storage.ts` — Pluggable storage interface (S3, Supabase Storage, local)
+- `src/core/storage-config.ts` (v0.22.11) — Storage tiering: `loadStorageConfig` reads `gbrain.yml`, normalizes deprecated keys (`git_tracked` / `supabase_only`) to canonical (`db_tracked` / `db_only`) with once-per-process deprecation warning, and runs `normalizeAndValidateStorageConfig` (auto-fixes missing trailing `/`, throws `StorageConfigError` on tier overlap). Path-segment matcher: `media/x/` does NOT match `media/xerox/foo`. Replaces gray-matter (broken on delimiter-less YAML) with a dedicated parser for the `gbrain.yml` shape.
+- `src/core/disk-walk.ts` (v0.22.11) — `walkBrainRepo(repoPath)` returns `Map<slug, {size, mtimeMs}>` from one recursive `readdirSync`. Skips dot-dirs, `node_modules`, non-`.md` files. Used by `gbrain storage status` to replace per-page `existsSync + statSync` (~400K syscalls on 200K-page brains → tens).
+- `src/commands/storage.ts` (v0.22.11) — `gbrain storage status [--repo P] [--json]`. Split into pure data (`getStorageStatus`) + JSON formatter + human formatter (ASCII-only per D10) matching the `orphans.ts` pattern. `PageCountsByTier` and `DiskUsageByTier` are distinct nominal types so swaps fail at compile time.
+- `gbrain.yml` (brain repo root, v0.22.11) — Optional storage tiering config. Top-level `storage:` section with `db_tracked:` and `db_only:` array-valued keys. `gbrain sync` auto-manages `.gitignore` for `db_only` paths on successful sync (skips on dry-run, blocked-by-failures, submodule context, or `GBRAIN_NO_GITIGNORE=1`). `gbrain export --restore-only [--repo P] [--type T] [--slug-prefix S]` repopulates missing `db_only` files from the database.
 - `src/core/supabase-admin.ts` — Supabase admin API (project discovery, pgvector check)
 - `src/core/file-resolver.ts` — File resolution with fallback chain (local -> .redirect.yaml -> .redirect -> .supabase)
-- `src/core/chunkers/` — 3-tier chunking (recursive, semantic, LLM-guided)
-- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup
+- `src/core/chunkers/` — 3-tier chunking (recursive, semantic, LLM-guided). v0.19.0 adds `code.ts` — tree-sitter-based semantic chunker for 29 languages with embedded-asset WASMs (`src/assets/wasm/`), `@dqbd/tiktoken` cl100k_base tokenizer, small-sibling merging. `CHUNKER_VERSION` constant folded into `importCodeFile`'s `content_hash` so chunker shape changes force clean re-chunks across releases.
+- `src/core/errors.ts` (v0.19.0) — `StructuredAgentError` + `buildError` + `serializeError`. Every new v0.19.0 agent-facing surface (code-def, code-refs, usage errors) uses this envelope; matches v0.17.0 `CycleReport.PhaseResult.error` shape.
+- `src/assets/wasm/` (v0.19.0) — 36 tree-sitter grammar WASMs + tree-sitter runtime. Committed to the repo so `bun --compile` embeds them deterministically via `import path from ... with { type: 'file' }`. The CI guard `scripts/check-wasm-embedded.sh` fails the build if the compiled binary ever silently falls through to recursive chunks.
+- `src/commands/code-def.ts` + `src/commands/code-refs.ts` (v0.19.0) — symbol definition + references lookup. Query `content_chunks.symbol_name` or chunk_text ILIKE with `page_kind='code'` filter. Auto-JSON when stdout is not a TTY (gh-CLI convention). Bypass the standard `searchKeyword` `DISTINCT ON (slug)` collapse so multiple call-sites from the same file surface.
+- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup. As of v0.22.0, `searchKeyword` / `searchKeywordChunks` / `searchVector` apply source-aware ranking at the SQL layer (curated content like `originals/`, `concepts/`, `writing/` outranks bulk content like `wintermute/chat/`, `daily/`, `media/x/`). `searchVector` uses a two-stage CTE so source-boost re-ranking doesn't kill the HNSW index. Hard-exclude prefixes (`test/`, `archive/`, `attachments/`, `.raw/` by default) filter at retrieval, not post-rank. Both gates honor `detail !== 'high'` so temporal queries surface chat pages normally.
 - `src/core/search/intent.ts` — Query intent classifier (entity/temporal/event/general → auto-selects detail level)
 - `src/core/search/eval.ts` — Retrieval eval harness: P@k, R@k, MRR, nDCG@k metrics + runEval() orchestrator
+- `src/core/search/source-boost.ts` (v0.22.0) — Source-type boost map keyed by slug prefix. `DEFAULT_SOURCE_BOOSTS` (originals/ 1.5, concepts/ 1.3, writing/ 1.4, people/companies/deals/ 1.2, daily/ 0.8, media/x/ 0.7, wintermute/chat/ 0.5) and `DEFAULT_HARD_EXCLUDES` (test/, archive/, attachments/, .raw/). `parseSourceBoostEnv` / `parseHardExcludesEnv` parse comma-separated `prefix:factor` pairs from `GBRAIN_SOURCE_BOOST` / `GBRAIN_SEARCH_EXCLUDE` env vars. `resolveBoostMap` and `resolveHardExcludes` merge defaults + env + caller `SearchOpts.exclude_slug_prefixes`/`include_slug_prefixes`.
+- `src/core/search/sql-ranking.ts` (v0.22.0) — Pure SQL string builders. `buildSourceFactorCase(slugColumn, boostMap, detail)` emits a CASE expression with longest-prefix-match wins (returns literal `'1.0'` when `detail === 'high'` for temporal-bypass parity with COMPILED_TRUTH_BOOST). `buildHardExcludeClause(slugColumn, prefixes)` emits `NOT (col LIKE 'p1%' OR col LIKE 'p2%')` — OR-chain wrapped in NOT, NOT `NOT LIKE ALL/ANY` (those quantifiers don't express set-exclusion). LIKE meta-character escape covers all three of `%`, `_`, AND `\` (backslash matters because it's Postgres LIKE's default escape char). Single-quote doubling on SQL string literals so injection-style inputs are inert text.
 - `src/commands/eval.ts` — `gbrain eval` command: single-run table + A/B config comparison
 - `src/core/embedding.ts` — OpenAI text-embedding-3-large, batch, retry, backoff
 - `src/core/check-resolvable.ts` — Resolver validation: reachability, MECE overlap, DRY checks, structured fix objects. v0.14.1: `CROSS_CUTTING_PATTERNS.conventions` is an array (notability gate accepts both `conventions/quality.md` and `_brain-filing-rules.md`). New `extractDelegationTargets()` parses `> **Convention:**`, `> **Filing rule:**`, and inline backtick references. DRY suppression is proximity-based via `DRY_PROXIMITY_LINES = 40`.
@@ -127,9 +143,9 @@ strict behavior when unset.
 - `src/core/resolver-filenames.ts` (v0.19) — central list of accepted routing filenames (`RESOLVER.md`, `AGENTS.md`). Shared by `findRepoRoot`, `check-resolvable`, and skillpack install so every code path walks the same fallback chain.
 - `src/commands/skillify.ts` + `src/core/skillify/{generator,templates}.ts` (v0.19) — `gbrain skillify scaffold <name>` creates all stubs for a new skill in one command: SKILL.md, script, tests, routing-eval.jsonl, resolver entry, filing-rules pointer. `gbrain skillify check <script>` runs the 10-step checklist (LLM evals, routing evals, check-resolvable gate, filing audit) against a candidate skill before it lands.
 - `src/commands/skillify-check.ts` (v0.19) — `gbrain skillpack-check` agent-readable health report. Exit 0/1/2 for CI pipeline gating; JSON for debugging. Wraps `check-resolvable --json`, `doctor --json`, and migration ledger into one payload so agents can decide whether a human action is required.
-- `src/commands/skillpack.ts` + `src/core/skillpack/{bundle,installer}.ts` (v0.19) — `gbrain skillpack install` drops gbrain's curated 25-skill bundle into a host workspace, managed-block style. Never clobbers local edits; tracks a skill manifest so subsequent `install --update` diffs cleanly. Bundle builder (`skillpack/bundle.ts`) packages the set from `skills/` into a versioned payload.
+- `src/commands/skillpack.ts` + `src/core/skillpack/{bundle,installer}.ts` (v0.19) — `gbrain skillpack install` drops gbrain's curated 25-skill bundle into a host workspace, managed-block style. Never clobbers local edits; tracks a skill manifest so subsequent `install --update` diffs cleanly. Bundle builder (`skillpack/bundle.ts`) packages the set from `skills/` into a versioned payload. **v0.24.0:** managed block embeds a `<!-- gbrain:skillpack:manifest cumulative-slugs="..." version="..." -->` receipt inside the fence. Per-skill installs accumulate via `union(prior_receipt, this_call)`; `install --all` is the only path that prunes (drops slugs no longer in the bundle). Rows inside the fence whose slug is in neither the new cumulative set nor the bundle survive as user-added with a stderr `[skillpack] unknown row in managed block: "<slug>" — Investigate: ...` warning. Pre-v0.24 fences upgrade silently on first install (extracted slugs become the prior cumulative set).
 - `src/core/skill-manifest.ts` (v0.19) — parser for `skill-manifest.json` records. Used by skillpack installer to detect drift between the shipped bundle and the user's local edits, so updates merge instead of overwriting.
-- `src/commands/routing-eval.ts` + `src/core/routing-eval.ts` (v0.19) — `gbrain routing-eval` catches user phrasings that route to the wrong skill. Reads `skills/<name>/routing-eval.jsonl` fixtures (`{intent, expected_skill, ambiguous_with?}`). Structural layer runs in `check-resolvable` by default (zero API cost); `--llm` opts into a Haiku tie-break layer for CI. False positives surface before users hit them.
+- `src/commands/routing-eval.ts` + `src/core/routing-eval.ts` (v0.19) — `gbrain routing-eval` catches user phrasings that route to the wrong skill. Reads `skills/<name>/routing-eval.jsonl` fixtures (`{intent, expected_skill, ambiguous_with?}`). Structural layer runs in `check-resolvable` by default (zero API cost). The `--llm` flag is accepted as a placeholder for a future LLM tie-break layer; in v0.24.0 it emits a stderr notice and runs structural only. False positives surface before users hit them.
 - `src/core/filing-audit.ts` + `skills/_brain-filing-rules.json` (v0.19) — Check 6 of `check-resolvable`. Parses new `writes_pages:` / `writes_to:` frontmatter on skills and audits their filing claims against the filing-rules JSON. Warning-only in v0.19, upgrades to error in v0.20.
 - `src/core/dry-fix.ts` — `gbrain doctor --fix` engine. `autoFixDryViolations(fixes, {dryRun})` rewrites inlined rules to `> **Convention:** see [path](path).` callouts via three shape-aware expanders (bullet / blockquote / paragraph). Five guards: working-tree-dirty (`getWorkingTreeStatus()` returns 3-state `'clean' | 'dirty' | 'not_a_repo'`), no-git-backup, inside-code-fence, already-delegated (40-line proximity, consistent with detector), ambiguous-multi-match, block-is-callout. `execFileSync` array args (no shell — no injection surface). EOF newline preserved.
 - `src/core/backoff.ts` — Adaptive load-aware throttling: CPU/memory checks, exponential backoff, active hours multiplier
@@ -137,16 +153,19 @@ strict behavior when unset.
 - `src/core/transcription.ts` — Audio transcription: Groq Whisper (default), OpenAI fallback, ffmpeg segmentation for >25MB
 - `src/core/enrichment-service.ts` — Global enrichment service: entity slug generation, tier auto-escalation, batch throttling
 - `src/core/data-research.ts` — Recipe validation, field extraction (MRR/ARR regex), dedup, tracker parsing, HTML stripping
-- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs).
+- `src/commands/embed.ts` — `gbrain embed [--stale|--all] [--slugs ...]`. v0.22.1 (#409, contributed by @atrevino47): `--stale` path now starts with `engine.countStaleChunks()` (single SELECT count(*) WHERE embedding IS NULL, ~50 bytes wire). On a fully-embedded brain that's a 1-line short-circuit — no further reads. When stale chunks exist, `engine.listStaleChunks()` returns just the chunks needing embeddings (slug + chunk_index + chunk_text + metadata, no `vector(1536)` payload). Caller groups by slug, embeds via OpenAI, re-upserts via `upsertChunks`. Replaces the prior page-walk that pulled every chunk's embedding column over the wire and discarded most.
+- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs). v0.22.1 (#417): `ExtractOpts.slugs?: string[]` enables incremental extract — when set, `extractForSlugs()` reads ONLY those slugs' files (single combined links+timeline pass) instead of the full directory walk. CLI `gbrain extract` keeps full-walk behavior; the cycle path threads sync's `pagesAffected` through. `walkMarkdownFiles(brainDir)` still runs at line 455 to build `allSlugs` for link resolution — see `TODOS.md` for replacing it with `engine.getAllSlugs()`.
 - `src/commands/graph-query.ts` — `gbrain graph-query <slug> [--type T] [--depth N] [--direction in|out|both]`: typed-edge relationship traversal (renders indented tree)
 - `src/core/link-extraction.ts` — shared library for the v0.12.0 graph layer. extractEntityRefs (canonical, replaces backlinks.ts duplicate) matches both `[Name](people/slug)` markdown links and Obsidian `[[people/slug|Name]]` wikilinks as of v0.12.3. extractPageLinks, inferLinkType heuristics (attended/works_at/invested_in/founded/advises/source/mentions), parseTimelineEntries, isAutoLinkEnabled config helper. `DIR_PATTERN` covers `people`, `companies`, `deals`, `topics`, `concepts`, `projects`, `entities`, `tech`, `finance`, `personal`, `openclaw`. Used by extract.ts, operations.ts auto-link post-hook, and backlinks.ts.
 - `src/core/minions/` — Minions job queue: BullMQ-inspired, Postgres-native (queue, worker, backoff, types, protected-names, quiet-hours, stagger, handlers/shell).
-- `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe). v0.14.1 #219: `add()` plumbs `max_stalled` through with a `[1, 100]` clamp; omitted values let the schema DEFAULT (5) kick in.
-- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't.
+- `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe). v0.14.1 #219: `add()` plumbs `max_stalled` through with a `[1, 100]` clamp; omitted values let the schema DEFAULT (5) kick in. v0.19.0: `handleWallClockTimeouts(lockDurationMs)` is Layer 3 kill shot for jobs where `FOR UPDATE SKIP LOCKED` stall detection and the timeout sweep both fail to evict (wedged worker holding a row lock via a pending transaction). v0.19.1: `maxWaiting` coalesce path now uses `pg_advisory_xact_lock` keyed on `(name, queue)` to serialize concurrent submits for the same key, and filters on `queue` in addition to `name` so cross-queue same-name jobs don't suppress each other.
+- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't. v0.22.1 (#403): per-job timeout fires `abort.abort(new Error('timeout'))` then a 30-second grace-then-evict safety net force-evicts the job from `inFlight` and marks it dead in DB if the handler ignores the abort signal — frees the slot even when a handler wedges (the 98-waiting-0-active prod incident driver).
+- `src/core/minions/supervisor.ts` — MinionSupervisor process manager. Spawns `gbrain jobs work` as a child, restarts on crash with exponential backoff, periodic health check. v0.22.1 (#406): `consecutiveHealthFailures` counter; on 3 consecutive failures emits `health_warn` with `reason: 'db_connection_degraded'` and calls `engine.reconnect()` to swap in a fresh pool, then resets the counter. Worker exit classifier emits `likely_cause` field on `worker_exited` events: `oom_or_external_kill` (SIGKILL), `graceful_shutdown` (SIGTERM), `runtime_error` (code 1), `clean_exit` (code 0), `unknown`.
 - `src/core/minions/types.ts` — `MinionJobInput` + `MinionJobStatus` + handler context types. `MinionJobInput.max_stalled` (new in v0.14.1) is optional; omitted values let the schema DEFAULT (5) kick in, provided values are clamped to `[1, 100]`.
 - `src/core/minions/protected-names.ts` — side-effect-free constant module exporting `PROTECTED_JOB_NAMES` + `isProtectedJobName()`. Kept pure so queue core can import without loading handler modules.
 - `src/core/minions/handlers/shell.ts` — `shell` job handler. Spawns `/bin/sh -c cmd` (absolute path, PATH-override-safe) or `argv[0] argv[1..]` (no shell). Env allowlist: `PATH, HOME, USER, LANG, TZ, NODE_ENV` + caller `env:` overrides. UTF-8-safe stdout/stderr tail via `string_decoder.StringDecoder`. Abort (either `ctx.signal` or `ctx.shutdownSignal`) fires SIGTERM → 5s grace → SIGKILL on child. Requires `GBRAIN_ALLOW_SHELL_JOBS=1` on worker (gated by `registerBuiltinHandlers`).
 - `src/core/minions/handlers/shell-audit.ts` — per-submission JSONL audit trail at `~/.gbrain/audit/shell-jobs-YYYY-Www.jsonl` (ISO-week rotation; override via `GBRAIN_AUDIT_DIR`). Best-effort: `mkdirSync(recursive)` + `appendFileSync`; failures logged to stderr, submission not blocked. Logs cmd (first 80 chars) or argv (JSON array). Never logs env values.
+- `src/core/minions/backpressure-audit.ts` (v0.19.1) — sibling of shell-audit.ts for `maxWaiting` coalesce events. JSONL at `~/.gbrain/audit/backpressure-YYYY-Www.jsonl`. Fires one line per coalesce with `(queue, name, waiting_count, max_waiting, returned_job_id, ts)`. Closes the silent-drop vector the v0.19.0 maxWaiting guard introduced.
 - `src/core/minions/handlers/subagent.ts` (v0.15) — LLM-loop handler. Two-phase tool persistence (pending → complete/failed), replay reconciliation for mid-dispatch crashes, dual-signal abort (`ctx.signal` + `ctx.shutdownSignal`), Anthropic prompt caching on system + tool defs. `makeSubagentHandler({engine, client?, ...})` factory; `MessagesClient` is an injectable interface the real SDK implements structurally. Throws `RateLeaseUnavailableError` (renewable) when rate-lease capacity is full.
 - `src/core/minions/handlers/subagent-aggregator.ts` (v0.15) — `subagent_aggregator` handler. Claims AFTER all children resolve (queue changes guarantee every terminal child posts a `child_done` inbox message with outcome). Reads inbox via `ctx.readInbox()`, builds deterministic mixed-outcome markdown summary. No LLM call in v0.15.
 - `src/core/minions/handlers/subagent-audit.ts` (v0.15) — JSONL audit + heartbeat writer at `~/.gbrain/audit/subagent-jobs-YYYY-Www.jsonl`. Events: `submission` (one line per submit) + `heartbeat` (per turn boundary: `llm_call_started | llm_call_completed | tool_called | tool_result | tool_failed`). Never logs prompts or tool inputs. `readSubagentAuditForJob(jobId, {sinceIso})` is the readback path for `gbrain agent logs`.
@@ -154,30 +173,46 @@ strict behavior when unset.
 - `src/core/minions/wait-for-completion.ts` (v0.15) — poll-until-terminal helper for CLI callers. `TimeoutError` does NOT cancel the job; `AbortSignal` exits without throwing. Default `pollMs`: 1000 on Postgres, 250 on PGLite inline.
 - `src/core/minions/transcript.ts` (v0.15) — renders `subagent_messages` + `subagent_tool_executions` to markdown. Tool rows splice under their owning assistant `tool_use` by `tool_use_id`. UTF-8-safe truncation; unknown block types fall through to fenced JSON.
 - `src/core/minions/plugin-loader.ts` (v0.15) — `GBRAIN_PLUGIN_PATH` discovery. Absolute paths only, left-wins collision, `gbrain.plugin.json` with `plugin_version: "gbrain-plugin-v1"`, plugins ship DEFS only (no new tools), `allowed_tools:` validated at load time against the derived registry.
-- `src/core/minions/tools/brain-allowlist.ts` (v0.15) — derives subagent tool registry from `src/core/operations.ts`. 11-name allow-list: `query`, `search`, `get_page`, `list_pages`, `file_list`, `file_url`, `get_backlinks`, `traverse_graph`, `resolve_slugs`, `get_ingest_log`, `put_page`. `put_page` schema is namespace-wrapped per subagent (`^wiki/agents/<subagentId>/.+`); the `put_page` op's server-side check is the authoritative gate via `ctx.viaSubagent` fail-closed.
+- `src/core/minions/tools/brain-allowlist.ts` (v0.15, extended v0.23) — derives subagent tool registry from `src/core/operations.ts`. 11-name allow-list. By default `put_page` schema is namespace-wrapped per subagent (`^wiki/agents/<subagentId>/.+`). **v0.23 trusted-workspace path:** when `BuildBrainToolsOpts.allowedSlugPrefixes` is set, the put_page schema instead describes the prefix list to the model and the OperationContext is threaded with `allowedSlugPrefixes`. Trust comes from `PROTECTED_JOB_NAMES` gating subagent submission — MCP cannot reach this field. Only cycle.ts (synthesize/patterns) and direct CLI submitters set it.
 - `src/mcp/tool-defs.ts` (v0.15) — extracted `buildToolDefs(ops)` helper. MCP server + subagent tool registry both call it; byte-for-byte equivalence pinned by `test/mcp-tool-defs.test.ts`.
 - `src/core/minions/attachments.ts` — Attachment validation (path traversal, null byte, oversize, base64, duplicate detection)
 - `src/commands/agent.ts` (v0.16) — `gbrain agent run <prompt> [flags]` CLI. Submits `subagent` (or N children + 1 aggregator) under `{allowProtectedSubmit: true}`. Single-entry `--fanout-manifest` short-circuits. Children get `on_child_fail: 'continue'` + `max_stalled: 3`. `--follow` is the default on TTY; streams logs + polls `waitForCompletion` in parallel. Ctrl-C detaches, does not cancel.
 - `src/commands/agent-logs.ts` (v0.16) — `gbrain agent logs <job> [--follow] [--since]`. Merges JSONL heartbeat audit + `subagent_messages` into a chronological timeline. `parseSince` accepts ISO-8601 or relative (`5m`, `1h`, `2d`). Transcript tail renders only for terminal jobs.
-- `src/commands/jobs.ts` — `gbrain jobs` CLI subcommands + `gbrain jobs work` daemon. v0.13.1 surfaces the full `MinionJobInput` retry/backoff/timeout/idempotency surface as first-class CLI flags on `jobs submit`: `--max-stalled`, `--backoff-type fixed|exponential`, `--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key`. `jobs smoke --sigkill-rescue` is the opt-in regression guard for #219. v0.16 wires `registerBuiltinHandlers` to always register `subagent` + `subagent_aggregator` (no env flag — `ANTHROPIC_API_KEY` is the natural cost gate, trust is via `PROTECTED_JOB_NAMES`) and loads `GBRAIN_PLUGIN_PATH` plugins at worker startup with a loud startup-line per plugin. `shell` handler still gated by `GBRAIN_ALLOW_SHELL_JOBS=1` (RCE surface, separate concern).
+- `src/commands/jobs.ts` — `gbrain jobs` CLI subcommands + `gbrain jobs work` daemon. v0.13.1 surfaces the full `MinionJobInput` retry/backoff/timeout/idempotency surface as first-class CLI flags on `jobs submit`: `--max-stalled`, `--backoff-type fixed|exponential`, `--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key`. `jobs smoke --sigkill-rescue` is the opt-in regression guard for #219. v0.16 wires `registerBuiltinHandlers` to always register `subagent` + `subagent_aggregator` (no env flag — `ANTHROPIC_API_KEY` is the natural cost gate, trust is via `PROTECTED_JOB_NAMES`) and loads `GBRAIN_PLUGIN_PATH` plugins at worker startup with a loud startup-line per plugin. `shell` handler still gated by `GBRAIN_ALLOW_SHELL_JOBS=1` (RCE surface, separate concern). v0.22.10 (#521): the `autopilot-cycle` handler now forwards `job.data.phases` to `runCycle` (was previously discarded — caller-supplied phase selection silently became a full cycle). Phases are validated against `ALL_PHASES` from `src/core/cycle.ts`; invalid names are filtered out and an empty/missing array falls back to the default 6-phase cycle. v0.22.13 (PR #490 CODEX-1+CODEX-4): `sync` handler now resolves `sourceId` at entry by looking up `sources.local_path` (mirrors `cycle.ts:480`'s autopilot fix from PR #475) so multi-source brains read the per-source `last_commit` anchor instead of the global config key. Concurrency routed through the shared `autoConcurrency()` policy in `src/core/sync-concurrency.ts` instead of the prior hardcoded `4`; PGLite stays serial. `noEmbed` default is `true` (embed is a separate job — submit `gbrain embed --stale` after sync, or rely on the autopilot cycle's embed phase).
 - `src/commands/features.ts` — `gbrain features --json --auto-fix`: usage scan + feature adoption salesman
 - `src/commands/autopilot.ts` — `gbrain autopilot --install`: self-maintaining brain daemon (sync+extract+embed)
-- `src/mcp/server.ts` — MCP stdio server (generated from operations)
-- `src/commands/auth.ts` — Standalone token management (create/list/revoke/test)
+- `src/mcp/server.ts` — MCP stdio server (generated from operations). v0.22.7: tool-call handler delegates to `dispatchToolCall` from `src/mcp/dispatch.ts` so stdio + HTTP transports share one validation, context-build, and error-format path.
+- `src/mcp/dispatch.ts` (v0.22.7) — Shared tool-call dispatch consumed by both stdio (`server.ts`) and HTTP (`http-transport.ts`). Exports `dispatchToolCall(engine, name, params, opts)`, `buildOperationContext(engine, params, opts)`, and `validateParams(op, params)`. Single source of truth for `(ctx, params)` handler arg order and the 5-field `OperationContext` shape (engine + config + logger + dryRun + remote). Defaults to `remote: true` (untrusted); local CLI callers pass `remote: false`. Closed F1 (reversed handler args) + F2 (incomplete OperationContext) + F3 (no param validation) drift bugs in the original v0.22.5 HTTP transport.
+- `src/mcp/rate-limit.ts` (v0.22.7) — Bounded-LRU token-bucket limiter for `gbrain serve --http`. `buildDefaultLimiters()` returns the two-bucket pipeline used by http-transport: pre-auth IP (default 30/60s, fires BEFORE the DB lookup so brute-force load against `access_tokens` is actually capped) + post-auth token-id (default 60/60s). Tracks `lastTouchedMs` separately from `lastRefillMs` so an exhausted key can't be reset by hammering past the TTL. LRU cap (default 10K keys) bounds memory under attacker-controlled key growth; TTL prune at 2× window evicts abandoned buckets.
+- `src/mcp/http-transport.ts` (v0.22.7, rewrite) — `gbrain serve --http` HTTP transport. Postgres-only — fails fast at startup on PGLite (the `access_tokens` table only exists on Postgres). Bearer auth against SHA-256 hashes in `access_tokens`. CORS default-deny via `GBRAIN_HTTP_CORS_ORIGIN` allowlist. Body cap stream-counted (1 MiB default via `GBRAIN_HTTP_MAX_BODY_BYTES`) so chunked transfers without Content-Length still hit the cap. `last_used_at` SQL-level debounce (one UPDATE per token per 60s). Per-request audit row in `mcp_request_log` with token_name + operation + status + latency. Optional `GBRAIN_HTTP_TRUST_PROXY=1` honors `X-Forwarded-For` — only safe when bound to a private interface AND the proxy strips client-supplied XFF (otherwise enables IP spoofing past the pre-auth rate limit). `/health` does `SELECT 1` against Postgres and returns 503 + `status:unhealthy` when the DB is unreachable so orchestration doesn't see green pods while clients get misleading 401s. Replaces the standalone OAuth wrapper that was vulnerable to unauthenticated client registration.
+- `src/commands/auth.ts` — Token management for the HTTP transport. `gbrain auth create/list/revoke/test`. As of v0.22.7 wired into the main CLI (`src/cli.ts`); also runs standalone via `bun run src/commands/auth.ts ...` for environments without a compiled binary. Tokens stored as SHA-256 hashes in `access_tokens` (Postgres-only).
 - `src/commands/upgrade.ts` — Self-update CLI. `runPostUpgrade()` enumerates migrations from the TS registry (src/commands/migrations/index.ts) and tail-calls `runApplyMigrations(['--yes', '--non-interactive'])` so the mechanical side of every outstanding migration runs unconditionally.
 - `src/commands/migrations/` — TS migration registry (compiled into the binary; no filesystem walk of `skills/migrations/*.md` needed at runtime). `index.ts` lists migrations in semver order. `v0_11_0.ts` = Minions adoption orchestrator (8 phases). `v0_12_0.ts` = Knowledge Graph auto-wire orchestrator (5 phases: schema → config check → backfill links → backfill timeline → verify). `phaseASchema` has a 600s timeout (bumped from 60s in v0.12.1 for duplicate-heavy brains). `v0_12_2.ts` = JSONB double-encode repair orchestrator (4 phases: schema → repair-jsonb → verify → record). `v0_14_0.ts` = shell-jobs + autopilot cooperative (2 phases: schema ALTER minion_jobs.max_stalled SET DEFAULT 3 — superseded by v0.14.3's schema-level DEFAULT 5 + UPDATE backfill; pending-host-work ping for skills/migrations/v0.14.0.md). All orchestrators are idempotent and resumable from `partial` status. As of v0.14.2 (Bug 3), the RUNNER owns all ledger writes — orchestrators return `OrchestratorResult` and `apply-migrations.ts` persists a canonical `{version, status, phases}` shape after return. Orchestrators no longer call `appendCompletedMigration` directly. `statusForVersion` prefers `complete` over `partial` (never regresses). 3 consecutive partials → wedged → `--force-retry <version>` writes a `'retry'` reset marker. v0.14.3 (fix wave) ships schema-only migrations v14 (`pages_updated_at_index`) + v15 (`minion_jobs_max_stalled_default_5` with UPDATE backfill) via the `MIGRATIONS` array in `src/core/migrate.ts` — no orchestrator phases needed.
 - `src/commands/repair-jsonb.ts` — `gbrain repair-jsonb [--dry-run] [--json]`: rewrites `jsonb_typeof='string'` rows in place across 5 affected columns (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter). Fixes v0.12.0 double-encode bug on Postgres; PGLite no-ops. Idempotent.
 - `src/commands/orphans.ts` — `gbrain orphans [--json] [--count] [--include-pseudo]`: surfaces pages with zero inbound wikilinks, grouped by domain. Auto-generated/raw/pseudo pages filtered by default. Also exposed as `find_orphans` MCP operation. Shipped in v0.12.3 (contributed by @knee5).
-- `src/commands/doctor.ts` — `gbrain doctor [--json] [--fast] [--fix] [--dry-run] [--index-audit]`: health checks. v0.12.3 added `jsonb_integrity` + `markdown_body_completeness` reliability checks. v0.14.1: `--fix` delegates inlined cross-cutting rules to `> **Convention:** see [path](path).` callouts (pipes DRY violations into `src/core/dry-fix.ts`); `--fix --dry-run` previews without writing. v0.14.2: `schema_version` check fails loudly when `version=0` (migrations never ran — the #218 `bun install -g` signature) and routes users to `gbrain apply-migrations --yes`; new opt-in `--index-audit` flag (Postgres-only) reports zero-scan indexes from `pg_stat_user_indexes` (informational only, no auto-drop). v0.15.2: every DB check is wrapped in a progress phase; `markdown_body_completeness` runs under a 1s heartbeat timer so 10+ min scans are observable on 50K-page brains. Fix hints point at `gbrain repair-jsonb`, `gbrain sync --force`, and `gbrain apply-migrations`.
-- `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). v0.14.2 extended the `Migration` interface with `sqlFor?: { postgres?, pglite? }` (engine-specific SQL overrides `sql`) and `transaction?: boolean` (set to false for `CREATE INDEX CONCURRENTLY`, which Postgres refuses inside a transaction; ignored on PGLite since it has no concurrent writers). Migration v14 (fix wave) uses a handler branching on `engine.kind` to run CONCURRENTLY on Postgres (with a pre-drop of any invalid remnant via `pg_index.indisvalid`) and plain `CREATE INDEX` on PGLite. v15 bumps `minion_jobs.max_stalled` default 1→5 and backfills existing non-terminal rows.
+- `src/commands/integrity.ts` — `gbrain integrity check|auto|review|extract`: bare-tweet detection, dead-link detection, three-bucket repair (auto-repair / review-queue / skip). `scanIntegrity()` is the shared library function called from `gbrain doctor` (sampled at limit=500) and `cmdCheck` (full scan). v0.22.8: batch-load fast path on Postgres uses `SELECT DISTINCT ON (slug)` in a single SQL query to fix the PgBouncer round-trip timeout (60s → ~6s) while preserving `engine.getAllSlugs()`'s `Set<string>` semantics on multi-source brains. Gated by `engine.kind === 'postgres'` at the call site so PGLite never enters batch; fallback `catch` logs at `GBRAIN_DEBUG=1` so real Postgres errors are diagnosable.
+- `src/commands/doctor.ts` — `gbrain doctor [--json] [--fast] [--fix] [--dry-run] [--index-audit]`: health checks. v0.12.3 added `jsonb_integrity` + `markdown_body_completeness` reliability checks. v0.14.1: `--fix` delegates inlined cross-cutting rules to `> **Convention:** see [path](path).` callouts (pipes DRY violations into `src/core/dry-fix.ts`); `--fix --dry-run` previews without writing. v0.14.2: `schema_version` check fails loudly when `version=0` (migrations never ran — the #218 `bun install -g` signature) and routes users to `gbrain apply-migrations --yes`; new opt-in `--index-audit` flag (Postgres-only) reports zero-scan indexes from `pg_stat_user_indexes` (informational only, no auto-drop). v0.15.2: every DB check is wrapped in a progress phase; `markdown_body_completeness` runs under a 1s heartbeat timer so 10+ min scans are observable on 50K-page brains. v0.19.1 added `queue_health` (Postgres-only) with two subchecks: stalled-forever active jobs (started_at > 1h) and waiting-depth-per-name > threshold (default 10, override via `GBRAIN_QUEUE_WAITING_THRESHOLD`). Worker-heartbeat subcheck intentionally deferred to follow-up B7 because it needs a `minion_workers` table to produce ground-truth signal. Fix hints point at `gbrain repair-jsonb`, `gbrain sync --force`, `gbrain apply-migrations`, and `gbrain jobs get/cancel <id>`. v0.22.12 (#500): `sync_failures` check shows `[CODE=N, ...]` breakdown for both unacked entries (warn) and acked-historical entries (ok), surfacing systemic failure modes (`SLUG_MISMATCH=2685`) instead of a bare count.
+- `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). v0.14.2 extended the `Migration` interface with `sqlFor?: { postgres?, pglite? }` (engine-specific SQL overrides `sql`) and `transaction?: boolean` (set to false for `CREATE INDEX CONCURRENTLY`, which Postgres refuses inside a transaction; ignored on PGLite since it has no concurrent writers). Migration v14 (fix wave) uses a handler branching on `engine.kind` to run CONCURRENTLY on Postgres (with a pre-drop of any invalid remnant via `pg_index.indisvalid`) and plain `CREATE INDEX` on PGLite. v15 bumps `minion_jobs.max_stalled` default 1→5 and backfills existing non-terminal rows. v0.22.6.1: migration v24 (`rls_backfill_missing_tables`) uses `sqlFor: { pglite: '' }` to no-op on PGLite — PGLite has no RLS engine and is single-tenant by definition, and the v24 ALTERs target subagent tables that don't exist in pglite-schema.ts. Closes #395 (contributed by @jdcastro2). **v30 (v0.23):** creates `dream_verdicts (file_path TEXT, content_hash TEXT, worth_processing BOOL, reasons JSONB, judged_at TIMESTAMPTZ, PK(file_path, content_hash))`. RLS-enabled when running as a BYPASSRLS role. The synthesize phase reads/writes this table to avoid re-judging on backfill re-runs.
 - `src/core/progress.ts` — Shared bulk-action progress reporter. Writes to stderr. Modes: `auto` (TTY: `\r`-rewriting; non-TTY: plain lines), `human`, `json` (JSONL), `quiet`. Rate-gated by `minIntervalMs` and `minItems`. `startHeartbeat(reporter, note)` helper for single long queries. `child()` composes phase paths. Singleton SIGINT/SIGTERM coordinator emits `abort` events for every live phase. EPIPE defense on both sync throws and stream `'error'` events. Zero dependencies. Introduced in v0.15.2.
 - `src/core/cli-options.ts` — Global CLI flag parser. `parseGlobalFlags(argv)` returns `{cliOpts, rest}` with `--quiet` / `--progress-json` / `--progress-interval=<ms>` stripped. `getCliOptions()` / `setCliOptions()` expose a module-level singleton so commands reach the resolved flags without parameter threading. `cliOptsToProgressOptions()` maps to reporter options. `childGlobalFlags()` returns the flag suffix to append to `execSync('gbrain ...')` calls in migration orchestrators. `OperationContext.cliOpts` extends shared-op dispatch for MCP callers.
-- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive. `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes 6 phases in semantically-driven order (lint → backlinks → sync → extract → embed → orphans). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler (`src/commands/jobs.ts`). One source of truth for what the brain does overnight. Coordination via `gbrain_cycle_locks` DB table (TTL-based; works through PgBouncer transaction pooling, unlike session-scoped `pg_try_advisory_lock`) + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite / engine=null mode. `CycleReport.schema_version: "1"` is the stable agent-consumable shape. `PhaseResult.error: { class, code, message, hint?, docs_url? }` is Stripe-API-tier structured failure info. `yieldBetweenPhases` hook awaited between every phase — Minions handler uses this to renew its job lock and prevent v0.14 stall-death regression. Engine nullable: filesystem phases (lint, backlinks) run without DB; DB phases skip with `status: "skipped", reason: "no_database"`. Lock-skip: read-only phase selections (`--phase orphans`) bypass the cycle lock.
-- `src/commands/dream.ts` — v0.17 `gbrain dream` CLI. ~80-line thin alias over `runCycle`. brainDir resolution requires explicit `--dir` OR `sync.repo_path` config (no more walk-up-cwd-for-.git footgun). Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`. Exit code 1 on status=failed (partial/warn not fatal — don't page on warnings).
+- `src/core/db-lock.ts` (v0.22.13) — generic `tryAcquireDbLock(engine, lockId, ttlMinutes)` over the existing `gbrain_cycle_locks` table. Parameterized lock id so different scopes can nest cleanly: `gbrain-cycle` for the broad cycle (held by `cycle.ts`) and `gbrain-sync` (`SYNC_LOCK_ID` constant) for `performSync`'s narrower writer window. Same UPSERT-with-TTL semantics as the prior cycle-only helper, just generalized. Survives PgBouncer transaction pooling (unlike session-scoped `pg_try_advisory_lock`); crashed holders auto-release once their TTL expires.
+- `src/core/sync-concurrency.ts` (v0.22.13) — single source of truth for the parallel-sync policy. Exports `autoConcurrency(engine, fileCount, override?)` (PGLite always serial; explicit override clamped to >=1; auto path returns `DEFAULT_PARALLEL_WORKERS=4` when `fileCount > AUTO_CONCURRENCY_FILE_THRESHOLD=100`), `shouldRunParallel(workers, fileCount, explicit)` (Q1: explicit `--workers` bypasses the >50-file floor), and `parseWorkers(s)` (rejects `'0'`, `'-3'`, `'foo'`, `'1.5'`, trailing chars — replaces the prior parseInt-with-no-validation in both `sync.ts` and `import.ts`). Used by `performSync`, `performFullSync`, `runImport`, and the Minion `sync` handler so the three sites can no longer drift.
+- `src/commands/sync.ts` — `gbrain sync` CLI + the `performSync` / `performFullSync` library entrypoints (consumed by the autopilot cycle and the Minion sync handler). v0.22.13 (PR #490): `performSync` wraps its body in a `gbrain-sync` writer lock so two concurrent syncs (manual + autopilot, two terminals, two Conductor workspaces) cannot both write `last_commit` and let the last writer win. Head-drift gate after the import phase re-checks `git rev-parse HEAD`; if HEAD moved (someone ran `git checkout` / `git pull` mid-sync), the bookmark refuses to advance. Vanished files now record a failedFiles entry instead of silent-skip — the silent-skip-then-advance pathology that survived prior hardening passes is dead. Worker engines wrap in try/finally so disconnect always fires (panic-path leak fix). Both PGLite-detection sites use `engine.kind === 'pglite'`. CLI accepts `--workers N` (alias `--concurrency N`), validated via `parseWorkers`. Explicit `--workers` bypasses the auto-path file-count floor; auto path defers to `autoConcurrency()`. Banner moved to stderr.
+- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive (extended to **8 phases in v0.23**). `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes phases in semantically-driven order: **lint → backlinks → sync → synthesize → extract → patterns → embed → orphans**. v0.23's `synthesize` phase runs after sync (cross-references see fresh brain) and before extract (auto-link materializes its writes); `patterns` runs after extract so it reads a fresh graph (codex finding #7 — subagent put_page sets `ctx.remote=true` and skips auto-link/timeline by default; extract is the canonical materialization). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler. Coordination via `gbrain_cycle_locks` DB table + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite. `CycleReport.schema_version: "1"` is stable; totals additively grew in v0.23 (`transcripts_processed`, `synth_pages_written`, `patterns_written`). `yieldBetweenPhases` runs between phases. **v0.23 added `yieldDuringPhase`** for in-phase keepalive — synthesize/patterns call it during long waits to renew the cycle-lock TTL. Engine nullable; lock-skip on read-only phase selections. v0.22.1 (#403): `CycleOpts.signal?: AbortSignal` propagates the worker's abort signal; `checkAborted()` fires between every phase. v0.22.1 (#417): `runPhaseSync` returns `pagesAffected` via `SyncPhaseResult`; `runCycle` captures it and threads to `runPhaseExtract` as the 4th arg. v0.22.1 (Codex F2): `runPhaseSync` takes `willRunExtractPhase: boolean` and sets `noExtract: phases.includes('extract')` so `gbrain dream --phase sync` doesn't silently lose extraction. v0.22.5 (#475): `resolveSourceForDir(engine, brainDir)` threads `sourceId` to `performSync()` so sync reads the per-source `sources.last_commit` anchor instead of the drift-prone global `config.sync.last_commit` key.
+- `src/core/cycle/synthesize.ts` (v0.23) — Synthesize phase: conversation-transcript-to-brain pipeline. Reads from `dream.synthesize.session_corpus_dir`, runs cheap Haiku verdict (cached in `dream_verdicts`), then fans out one Sonnet subagent per worth-processing transcript with `allowed_slug_prefixes` (sourced from `skills/_brain-filing-rules.json` `dream_synthesize_paths.globs`). Orchestrator collects slugs from `subagent_tool_executions` (NOT `pages.updated_at` — codex finding #2) and reverse-renders DB → markdown via `serializeMarkdown`. Cooldown via `dream.synthesize.last_completion_ts`, written ONLY on success. Idempotency key `dream:synth:<file_path>:<content_hash>`. Auto-commit deferred to v1.1 (codex #5). `--dry-run` runs Haiku, skips Sonnet (codex #8). Subagent never gets fs-write access. **v0.23.2:** `renderPageToMarkdown` (now exported) stamps `dream_generated: true` and `dream_cycle_date` into every reverse-write's frontmatter; `writeSummaryPage` does the same on the dream-cycle summary index. The marker is the explicit identity surface checked by `isDreamOutput` in `transcript-discovery.ts` — replaces the v0.23.1 content-prefix heuristic that could miss real output (`serializeMarkdown` doesn't embed slugs in body) and false-positive on user transcripts citing brain pages. `judgeSignificance` and `JudgeClient` are exported; `judgeSignificance` accepts a `verdictModel` parameter (default `claude-haiku-4-5-20251001`) loaded from `dream.synthesize.verdict_model` via `loadSynthConfig`.
+- `src/core/cycle/patterns.ts` (v0.23) — Patterns phase: cross-session theme detection over reflections within `dream.patterns.lookback_days` (default 30). Names a pattern only when ≥`dream.patterns.min_evidence` (default 3) reflections support it. Single Sonnet subagent; same allow-list path as synthesize. Runs AFTER `extract` so the graph is fresh.
+- `src/core/cycle/transcript-discovery.ts` (v0.23) — Pure filesystem walk for synthesize. `discoverTranscripts(opts)` filters `.txt` files by date range, min_chars, and word-boundary regex `excludePatterns` (Q-3: `medical` matches "medical advice" but NOT "comedical"; power users may pass full regex). `readSingleTranscript(path)` is the `gbrain dream --input <file>` ad-hoc path. **v0.23.2 self-consumption guard:** `DREAM_OUTPUT_MARKER_RE` (anchored at frontmatter open `---\n`, optional BOM + CRLF tolerance, scans first 2000 chars for `dream_generated: true` with case-insensitive value and word boundary on `true`) drives `isDreamOutput(content, bypass=false)`. Both `discoverTranscripts` and `readSingleTranscript` skip matching files and emit a `[dream] skipped <basename>: dream_generated marker` stderr log (no more silent skips). `bypassGuard?: boolean` on `DiscoverOpts` and `readSingleTranscript`'s opts disables the guard for the explicit `--unsafe-bypass-dream-guard` escape hatch only — never auto-applied for `--input`. Replaces v0.23.1's `DREAM_OUTPUT_SLUGS` content-prefix list.
+- `src/commands/dream.ts` — v0.17 `gbrain dream` CLI; ~80-line thin alias over `runCycle`. brainDir resolution requires explicit `--dir` OR `sync.repo_path` config. Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`. **v0.23 added** `--input <file>` (ad-hoc transcript, implies `--phase synthesize`), `--date YYYY-MM-DD`, `--from <d> --to <d>` (backfill range). Conflict detection: `--input` + `--date` exits 2. ISO date validation. `--dry-run` runs Haiku significance verdict but skips Sonnet synthesis (codex finding #8 — NOT zero LLM calls). Exit code 1 on status=failed. **v0.23.2 added** `--unsafe-bypass-dream-guard` (long-form intentional, plumbed through `runCycle.synthBypassDreamGuard` → `SynthesizePhaseOpts.bypassDreamGuard` → `discoverTranscripts({bypassGuard})` and `readSingleTranscript({bypassGuard})`). Loud stderr warning fires at synthesize-phase entry when set. Never auto-applied for `--input` so any caller can't silently re-trigger the loop bug.
+- `src/commands/friction.ts` + `src/core/friction.ts` (v0.23) — `gbrain friction {log,render,list,summary}` reporter. Append-only JSONL under `$GBRAIN_HOME/friction/<run-id>.jsonl`. Schema is a flat extension of `StructuredAgentError` (D20). Render groups by severity → phase, defaults to `--redact` for md output (strips `$HOME`/`$CWD` to placeholders so reports paste safely in PRs). Run-id resolves from `--run-id` > `$GBRAIN_FRICTION_RUN_ID` > `standalone.jsonl`. Skills the claw-test exercises gain a `_friction-protocol.md` callout so agents know when to log friction.
+- `src/commands/claw-test.ts` + `src/core/claw-test/` (v0.23) — `gbrain claw-test [--scenario <name>] [--live --agent openclaw]`. End-to-end "fresh user" friction harness. Two modes: scripted (CI gate, agent-free) and live (real openclaw subprocess, $1–2 in tokens). Sets `GBRAIN_HOME=<tempdir>` for hermeticity and captures gbrain's `--progress-json` events from each child's stderr to verify expected phases ran (`import.files`, `extract.links_fs`, `doctor.db_checks`). Phases for scripted mode: setup → install_brain (`gbrain init --pglite`) → import (`--no-embed`) → query → extract → verify (`gbrain doctor --json`, asserts `status: 'ok'`) → render. Live mode hands `BRIEF.md` from `test/fixtures/claw-test-scenarios/<name>/` to the agent runner. v1 ships with the OpenClaw runner only (`src/core/claw-test/runners/openclaw.ts`, invokes `openclaw agent --local --agent <name> --message <brief>`); hermes runner deferred to v1.1. Transcript capture (`transcript-capture.ts`) uses `fs.createWriteStream` with `'drain'`-event backpressure — D17 fix for the 256KB-burst child-stall scenario. v0.18 upgrade scenario seeded via `seed-pglite.ts` SQL replay.
+- `skills/_friction-protocol.md` (v0.23) — shared cross-cutting convention skill (like `_brain-filing-rules.md`). Tells agents when to call `gbrain friction log` and how to choose a severity. Routes to friction CLI from any skill the claw-test exercises.
 - `scripts/check-progress-to-stdout.sh` — CI guard against regressing to `\r`-on-stdout progress. Wired into `bun run test` via `scripts/check-progress-to-stdout.sh && bun test` in package.json.
 - `docs/progress-events.md` — Canonical JSON event schema reference. Stable from v0.15.2, additive only.
 - `src/core/markdown.ts` — Frontmatter parsing + body splitter. `splitBody` requires an explicit timeline sentinel (`<!-- timeline -->`, `--- timeline ---`, or `---` immediately before `## Timeline`/`## History`). Plain `---` in body text is a markdown horizontal rule, not a separator. `inferType` auto-types `/wiki/analysis/` → analysis, `/wiki/guides/` → guide, `/wiki/hardware/` → hardware, `/wiki/architecture/` → architecture, `/writing/` → writing (plus the existing people/companies/deals/etc heuristics).
 - `scripts/check-jsonb-pattern.sh` — CI grep guard. Fails the build if anyone reintroduces (a) the `${JSON.stringify(x)}::jsonb` interpolation pattern (postgres.js v3 double-encodes it), or (b) `max_stalled INTEGER NOT NULL DEFAULT 1` in any schema source file (v0.15.1 #219 regression guard — must be DEFAULT 5 to preserve SIGKILL-rescue). Wired into `bun test`.
+- `docker-compose.ci.yml` + `scripts/ci-local.sh` (v0.23.1) — Local CI gate. `bun run ci:local` spins up `pgvector/pgvector:pg16` + `oven/bun:1` with named volumes (`gbrain-ci-pg-data`, `gbrain-ci-node-modules`, `gbrain-ci-bun-cache`), runs gitleaks on host, smoke-tests `scripts/run-e2e.sh` argv handling, runs unit tests with `DATABASE_URL` unset (matches GH Actions structure), then runs all 29 E2E files sequentially. `--diff` swaps in the diff-aware selector; `--no-pull` skips upstream pulls; `--clean` nukes named volumes. Postgres host port defaults to 5434 (avoids 5432 manual `gbrain-test-pg` and 5433 sibling-project conflict); override with `GBRAIN_CI_PG_PORT=NNNN`. Stronger gate than current PR CI's 2-file Tier 1 set — closes the "push-and-wait" feedback loop pre-push.
+- `scripts/select-e2e.ts` + `scripts/e2e-test-map.ts` (v0.23.1) — Diff-aware E2E test selector. Reads three git sources (committed `origin/master...HEAD`, working-tree `HEAD`, and `git ls-files --others --exclude-standard` for untracked, NOT-gitignored files), classifies as EMPTY / DOC_ONLY / SRC. Fail-closed by design: EMPTY → all 29 files (clean branch shouldn't run nothing), DOC_ONLY (every path matches the README/CLAUDE/AGENTS/CHANGELOG/TODOS allowlist) → empty stdout, SRC → escape-hatch paths (schema, package.json, skills/) trigger all; otherwise the hand-tuned `E2E_TEST_MAP` glob → tests narrows; an unmapped src/ change still emits ALL files, never silently nothing. Pure-function exports (`selectTests`, `classify`, `matchGlob`) so it's trivial to test and fork. `bun run ci:select-e2e` prints the current selection on stdout, pipe-friendly. `test/select-e2e.test.ts` covers all 4 branches plus 3 codex regression guards (skills/, untracked files, unmapped src/) — 24 cases.
+- `scripts/run-e2e.sh` (v0.23.1 update) — Sequential E2E runner. Now accepts an optional argv-driven file list (used by `ci:local:diff` to pipe in selector output) and a `--dry-run-list` flag that prints the resolved file list and exits (used by `ci-local.sh`'s startup smoke-test). Falls back to `test/e2e/*.test.ts` when invoked with no args.
 - `scripts/llms-config.ts` + `scripts/build-llms.ts` — Generator for `llms.txt` (llmstxt.org-spec web index) + `llms-full.txt` (inlined single-fetch bundle). Curated config drives both. Run `bun run build:llms` after adding a new doc. `LLMS_REPO_BASE` env var lets forks regenerate with their own URL base. `FULL_SIZE_BUDGET` (600KB) caps the inline bundle; generator WARNs if exceeded. Committed output is not analogous to `schema-embedded.ts` (no runtime consumer); we commit for GitHub browsing and fork-safe fetching.
 - `AGENTS.md` — Local-clone entry point for non-Claude agents (Codex, Cursor, OpenClaw, Aider). Mirrors `CLAUDE.md` intent via relative links. Claude Code keeps using `CLAUDE.md`.
 - `docs/UPGRADING_DOWNSTREAM_AGENTS.md` — Patches for downstream agent skill forks to apply when upgrading. Each release appends a new section. v0.10.3 includes diffs for brain-ops, meeting-ingestion, signal-detector, enrich.
@@ -221,7 +256,7 @@ strict behavior when unset.
 - `skills/soul-audit/SKILL.md` — 6-phase interview for SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md
 - `skills/webhook-transforms/SKILL.md` — External events to brain signals
 - `skills/data-research/SKILL.md` — Structured data research: email-to-tracker pipeline with parameterized YAML recipes
-- `skills/minion-orchestrator/SKILL.md` — Background job orchestration: submit, fan out children with depth/cap/timeouts, collect results via child_done inbox
+- `skills/minion-orchestrator/SKILL.md` — Unified background-work skill (v0.20.4 consolidation of the former `minion-orchestrator` + `gbrain-jobs` split). Two lanes: shell jobs via `gbrain jobs submit shell --params '{"cmd":"..."}'` (operator/CLI only; MCP throws `permission_denied` for protected names) and LLM subagents via `gbrain agent run` (user-facing entrypoint). Shared Preconditions block, parent-child DAGs with depth/cap/timeouts, `child_done` inbox for fan-in, PGLite `--follow` inline path for dev. Triggers narrowed from bare `"gbrain jobs"` to `"gbrain jobs submit"` + `"submit a gbrain job"` so `stats`/`prune`/`retry` questions fall through to `gbrain --help`.
 - `templates/` — SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md templates
 - `skills/migrations/` — Version migration files with feature_pitch YAML frontmatter
 - `src/commands/publish.ts` — Deterministic brain page publisher (code+skill pair, zero LLM calls)
@@ -283,6 +318,20 @@ Key commands added in v0.14.3 (fix wave):
 - `gbrain jobs submit` gains `--max-stalled`, `--backoff-type`, `--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key` — exposing existing `MinionJobInput` fields as first-class CLI flags.
 - `gbrain jobs smoke --sigkill-rescue` — opt-in regression smoke case simulating a killed worker; asserts the v0.14.3 schema default (`max_stalled=5`) actually rescues on first stall.
 
+Key commands added in v0.22.13 (PR #490):
+- `gbrain sync --workers N` (alias `--concurrency N`) — parallelize the import phase using per-worker Postgres engines (small pool of 2 each) with an atomic queue index. Auto-concurrency: defaults to 4 workers when the diff exceeds 100 files. Smaller diffs stay serial. Explicit `--workers` always wins (even on a 30-file diff). PGLite forces serial regardless. Validation rejects `0`, negatives, non-integers loud (replaces the prior silent fall-through to auto-concurrency).
+- `gbrain import --workers N` — same `parseWorkers()` validation as sync; same try/finally worker-engine cleanup. Behavior surface unchanged.
+
+Key commands added in v0.22.16 (claw-test friction loop):
+- `gbrain claw-test [--scenario fresh-install|upgrade-from-v0.18] [--keep-tempdir]` — scripted-mode CI gate that runs the full canonical first-day flow against a fresh tempdir. Asserts every expected `--progress-json` phase fired and doctor's `status === 'ok'`. ~30s, no API keys.
+- `gbrain claw-test --live --agent openclaw` — friction-discovery mode. Spawns real openclaw, hands it `BRIEF.md`, captures stdin/stdout/stderr to `<run>/transcript.jsonl`, lets the agent log friction via the friction CLI. Run on demand; ~5–10 min and ~$1–2 in tokens.
+- `gbrain claw-test --list-agents` — reports which agent runners are registered + their detection state (binary path or unavailable reason).
+- `gbrain friction log --severity {confused|error|blocker|nit} --phase <name> --message <text> [--hint ...] [--kind {friction|delight}] [--run-id ...]` — append a friction or delight entry to the active run JSONL.
+- `gbrain friction render --run-id <id> [--json] [--transcripts] [--no-redact]` — markdown report grouped by severity + phase; `--redact` is the default for md output (strips `$HOME`/`$CWD` placeholders so reports paste safely in PRs/issues).
+- `gbrain friction list [--json]` — recent run-ids with friction/delight counts; interrupted runs marked `(interrupted)`.
+- `gbrain friction summary --run-id <id> [--json]` — two-column friction + delight summary.
+- `GBRAIN_HOME` env override is now honored uniformly across every gbrain write site (config, audit, friction, sync-failures, import checkpoint, integrity log, integrations heartbeat, migration rollback, etc.) — `gbrainPath(...)` from `src/core/config.ts` is the canonical helper. Read-side host-fingerprint detection (`~/.claude`/`~/.openclaw` etc.) intentionally NOT confined in v1; that's a v1.1 follow-up.
+
 ## Testing
 
 `bun test` runs all tests. After the v0.12.1 release: ~75 unit test files + 8 E2E test files (1412 unit pass, 119 E2E when `DATABASE_URL` is set — skip gracefully otherwise). Unit tests run
@@ -294,7 +343,9 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/files.test.ts` (MIME/hash), `test/import-file.test.ts` (import pipeline),
 `test/upgrade.test.ts` (schema migrations),
 `test/file-migration.test.ts` (file migration), `test/file-resolver.test.ts` (file resolution),
-`test/import-resume.test.ts` (import checkpoints), `test/migrate.test.ts` (migration; v8/v9 helper-btree-index SQL structural assertions + 1000-row wall-clock fixtures that guard the O(n²)→O(n log n) fix + v0.13.1 assertions on v12/v13 SQL shape, `sqlFor` + `transaction:false` runner semantics, and the `max_stalled DEFAULT 1` regression guard),
+`test/import-resume.test.ts` (import checkpoints), `test/migrate.test.ts` (migration; v8/v9 helper-btree-index SQL structural assertions + 1000-row wall-clock fixtures that guard the O(n²)→O(n log n) fix + v0.13.1 assertions on v12/v13 SQL shape, `sqlFor` + `transaction:false` runner semantics, the `max_stalled DEFAULT 1` regression guard, and v0.22.6.1 v24 `sqlFor.pglite: ''` no-op assertion),
+`test/bootstrap.test.ts` (v0.22.6.1 — bootstrap contract: no-op on fresh install, idempotent across two `initSchema()` calls, no-op on modern brain that already has every probed column, full bootstrap path on simulated pre-v0.18 brain, fresh-install regression guard, pre-v0.13 `links` shape coverage),
+`test/schema-bootstrap-coverage.test.ts` (v0.22.6.1 CI guard — `REQUIRED_BOOTSTRAP_COVERAGE` lists every forward reference in PGLITE_SCHEMA_SQL; the test fails loudly if `applyForwardReferenceBootstrap` skips one. When you add a column-with-index to the embedded schema blob, you extend both arrays or this guard fails. The pattern that broke gbrain ten times in two years is now structurally prevented.),
 `test/setup-branching.test.ts` (setup flow), `test/slug-validation.test.ts` (slug validation),
 `test/storage.test.ts` (storage backends), `test/supabase-admin.test.ts` (Supabase admin),
 `test/yaml-lite.test.ts` (YAML parsing), `test/check-update.test.ts` (version check + update CLI),
@@ -306,8 +357,9 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/lint.test.ts` (LLM artifact detection, code fence stripping, frontmatter validation),
 `test/report.test.ts` (report format, directory structure),
 `test/skills-conformance.test.ts` (skill frontmatter + required sections validation),
-`test/resolver.test.ts` (RESOLVER.md coverage, routing validation),
+`test/resolver.test.ts` (RESOLVER.md coverage, routing validation + v0.20.4 round-trip: every quoted RESOLVER.md trigger must match a frontmatter `triggers:` entry in the target skill, and every `name="<word>"` reference in any SKILL.md must resolve to a declared op in `src/core/operations.ts` or a Minions handler in `PROTECTED_JOB_NAMES`),
 `test/search.test.ts` (RRF normalization, compiled truth boost, cosine similarity, dedup key),
+`test/sql-ranking.test.ts` (v0.22.0 source-boost helpers: 39 cases covering longest-prefix-match in SQL CASE, detail=high temporal-bypass, three-meta-char LIKE escape (%, _, \\), single-quote SQL-literal doubling, env override parsing for GBRAIN_SOURCE_BOOST + GBRAIN_SEARCH_EXCLUDE, resolveBoostMap / resolveHardExcludes merge semantics),
 `test/dedup.test.ts` (source-aware dedup, compiled truth guarantee, layer interactions),
 `test/intent.test.ts` (query intent classification: entity/temporal/event/general),
 `test/eval.test.ts` (retrieval metrics: precisionAtK, recallAtK, mrr, ndcgAtK, parseQrels),
@@ -335,6 +387,9 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/orphans.test.ts` (v0.12.3 orphans command: detection, pseudo filtering, text/json/count outputs, MCP op),
 `test/postgres-engine.test.ts` (v0.12.3 statement_timeout scoping: `sql.begin` + `SET LOCAL` shape, source-level grep guardrail against reintroduced bare `SET statement_timeout`),
 `test/sync.test.ts` (sync logic + v0.12.3 regression guard asserting top-level `engine.transaction` is not called),
+`test/sync-concurrency.test.ts` (v0.22.13 PR #490: 17 cases covering `autoConcurrency()` thresholds + PGLite-forces-serial + explicit-override clamping, `shouldRunParallel()` Q1 explicit-bypasses-floor contract, and `parseWorkers()` validation that rejects `'0'`/`'-3'`/`'foo'`/`'1.5'`/trailing chars),
+`test/sync-parallel.test.ts` (v0.22.13 PR #490: PGLite-routed coverage of the bookmark gate under concurrency request, head-drift gate, vanished-file failure capture, PGLite-stays-serial, and the `gbrain-sync` writer-lock contract — 7 cases),
+`test/sync-failures.test.ts` (v0.22.12: 28 cases pinning `classifyErrorCode` regex coverage for all 12 codes against literal production message strings from `markdown.ts:159-244` and `import-file.ts:199, 347, 352, 401`; `summarizeFailuresByCode` sort + pre-classified-honor; `recordSyncFailures` code-field persistence; `acknowledgeSyncFailures` AcknowledgeResult shape + backfill on pre-v0.22.12 entries),
 `test/doctor.test.ts` (doctor command + v0.12.3 assertions that `jsonb_integrity` scans the four v0.12.0 write sites and `markdown_body_completeness` is present),
 `test/utils.test.ts` (shared SQL utilities + `tryParseEmbedding` null-return and single-warn semantics),
 `test/build-llms.test.ts` (llms.txt/llms-full.txt generator: path resolution, idempotence, spec shape, regen-drift guard, content contract, AGENTS.md install-path mirror, size-budget enforcement — 7 cases),
@@ -345,16 +400,26 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/skill-manifest.test.ts` (v0.19 skill manifest parser: drift detection, managed-block markers),
 `test/skillify-scaffold.test.ts` (v0.19 `gbrain skillify scaffold` stubs: SKILL.md, script, tests, routing-eval fixtures),
 `test/skillpack-install.test.ts` (v0.19 `gbrain skillpack install` managed-block install / update / no-clobber semantics),
-`test/skillpack-sync-guard.test.ts` (v0.19 sync-guard: bundled skills stay byte-identical to `skills/` source).
+`test/skillpack-sync-guard.test.ts` (v0.19 sync-guard: bundled skills stay byte-identical to `skills/` source),
+`test/http-transport.test.ts` (v0.22.7 HTTP transport: 23 unit cases covering bearer auth + missing/no-Bearer/unknown/revoked + `/health` bypass, F1+F2 round-trip via dispatch.ts, F3 invalid_params, application/json response shape (not SSE), CORS default-deny + allowlist, body cap on Content-Length AND chunked, two-bucket rate limit (refill, exhaust+Retry-After, LRU eviction, TTL prune, pre-auth IP fires before DB), and `mcp_request_log` audit on success + auth_failed).
 
 E2E tests (`test/e2e/`): Run against real Postgres+pgvector. Require `DATABASE_URL`.
 - `bun run test:e2e` runs Tier 1 (mechanical, all operations, no API keys). Includes 9 dedicated cases for the postgres-engine `addLinksBatch` / `addTimelineEntriesBatch` bind path — postgres-js's `unnest()` binding is structurally different from PGLite's and gets its own coverage.
 - `test/e2e/search-quality.test.ts` runs search quality E2E against PGLite (no API keys, in-memory)
 - `test/e2e/graph-quality.test.ts` runs the v0.10.3 knowledge graph pipeline (auto-link via put_page, reconciliation, traversePaths) against PGLite in-memory
 - `test/e2e/postgres-jsonb.test.ts` — v0.12.2 regression test. Round-trips all 5 JSONB write sites (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter) against real Postgres and asserts `jsonb_typeof='object'` plus `->>'key'` returns the expected scalar. The test that should have caught the original double-encode bug.
+- `test/e2e/integrity-batch.test.ts` (v0.22.8) — parity tests for `scanIntegrity`'s batch-load fast path vs sequential. Four cases (dedup, hits, validate, topPages) seed a fixture and assert both paths return identical results. Dedup case uses raw SQL via `getConn().unsafe()` to seed a `(test-source-2, people/alice)` row alongside the default-source row, since `engine.putPage` doesn't take a `source_id`. Pins the codex-caught multi-source overcounting regression.
 - `test/e2e/jsonb-roundtrip.test.ts` — v0.12.3 companion regression against the 4 doctor-scanned JSONB sites. Assertion-level overlap with `postgres-jsonb.test.ts` is intentional defense-in-depth: if doctor's scan surface ever drifts from the actual write surface, one of these tests catches it.
+- `test/e2e/sync.test.ts` (v0.22.12 — `--skip-failed` failure-loop test, alongside the existing 13 happy-path tests): exercises the full chain — broken file → `performSync` returns `blocked_by_failures` with grouped breakdown → `performSync({skipFailed: true})` advances bookmark and returns `AcknowledgeResult` with code summary → second broken file → second cycle. Saves and restores the user's real `~/.gbrain/sync-failures.jsonl` so the test is hermetic on a developer machine. Asserts bookmark gating, JSONL state, dedup across paths, summary aggregation, and the literal doctor-rendering string format. This is the integration test that proves the v0.22.12 chain holds together — unit tests cover the pure functions in isolation, this covers the integration.
 - `test/e2e/upgrade.test.ts` runs check-update E2E against real GitHub API (network required)
+- `test/e2e/minions-shell-pglite.test.ts` (v0.20.4) exercises the PGLite `--follow` inline shell-job path (in-memory, no `DATABASE_URL` required) — the path the consolidated minion-orchestrator skill documents for dev use
 - `test/e2e/openclaw-reference-compat.test.ts` (v0.19) — exercises `check-resolvable` + `skillpack install` against a minimal AGENTS.md workspace fixture (`test/fixtures/openclaw-reference-minimal/`), regression guard for the 107-skill OpenClaw deployment shape
+- `test/e2e/search-swamp.test.ts` (v0.22.0) — reproduces the headline source-swamp case. Seeds a curated `originals/talks/article-outline-fat-code` page against two `wintermute/chat/` pages stuffed with the same multi-word phrase. Asserts the article wins keyword AND vector ranking, that `detail=high` lets the chat swamp re-surface (temporal-query workflow preserved), and that `source_id` passes through the two-stage CTE intact. PGLite in-memory.
+- `test/e2e/search-exclude.test.ts` (v0.22.0) — verifies `test/` + `archive/` pages are hidden by default, that `include_slug_prefixes` opts back in, and that caller-supplied `exclude_slug_prefixes` adds to defaults. Both keyword and vector search paths covered.
+- `test/e2e/engine-parity.test.ts` (v0.22.0) — Postgres ↔ PGLite top-result and result-set parity for `searchKeyword` + `searchVector`. Codex flagged that Postgres ranks pages then picks best chunk while PGLite returns chunks directly — without parity coverage the source-boost fix could pass on PGLite and fail on Postgres. Skips gracefully when `DATABASE_URL` is unset.
+- `test/e2e/postgres-bootstrap.test.ts` (v0.22.6.1) — exercises `PostgresEngine.initSchema()` directly against a fresh real Postgres database. Asserts the bootstrap path is no-op on fresh installs and that SCHEMA_SQL replays cleanly through the engine path (not via the standalone `db.initSchema` from `src/core/db.ts`, which would have produced false-positive coverage). Codex caught the E2E-shape gap during plan review.
+- `test/e2e/http-transport.test.ts` (v0.22.7) — 8 cases against real Postgres covering `gbrain serve --http` end-to-end: bearer auth round-trip, `last_used_at` SQL-level debounce semantics, `mcp_request_log` row insertion on success and auth_failed paths, `/health` DB-down → 503 (DB-probing health check), and the F1+F2+F3 dispatch round-trip with a real operation. Skips gracefully when `DATABASE_URL` is unset.
+- `test/e2e/sync-parallel.test.ts` (v0.22.13 PR #490) — DATABASE_URL-gated. T2: 60-file Postgres sync at concurrency=4 imports all + no connection leak (probes `pg_stat_activity` before/after to confirm worker engines disconnected). P4: 120-file serial-vs-parallel benchmark prints `SYNC_PARALLEL_BENCH N files | serial=Xms | parallel(4)=Yms | speedup=Zx` for CHANGELOG quoting. Asserts parallel ≤ serial × 1.5 (CI-noise tolerant; not a strict speedup gate).
 - Tier 2 (`skills.test.ts`) requires OpenClaw + API keys, runs nightly in CI
 - If `.env.testing` doesn't exist in this directory, check sibling worktrees for one:
   `find ../  -maxdepth 2 -name .env.testing -print -quit` and copy it here if found.
@@ -406,7 +471,7 @@ stop and remove it before starting a new one.
 
 ## Skills
 
-Read the skill files in `skills/` before doing brain operations. GBrain ships 28 skills
+Read the skill files in `skills/` before doing brain operations. GBrain ships 29 skills
 organized by `skills/RESOLVER.md` (`AGENTS.md` is also accepted as of v0.19):
 
 **Original 8 (conformance-migrated):** ingest (thin router), query, maintain, enrich,
@@ -416,11 +481,19 @@ briefing, migrate, setup, publish.
 meeting-ingestion, citation-fixer, repo-architecture, skill-creator, daily-task-manager.
 
 **Operational + identity:** daily-task-prep, cross-modal-review, cron-scheduler, reports,
-testing, soul-audit, webhook-transforms, data-research, minion-orchestrator.
+testing, soul-audit, webhook-transforms, data-research, minion-orchestrator. As of
+v0.20.4, `minion-orchestrator` is the single unified skill for both lanes of background
+work (shell jobs via `gbrain jobs submit shell`, LLM subagents via `gbrain agent run`) ...
+the prior `gbrain-jobs` skill was merged in, Preconditions are shared, and trigger
+routing is narrowed to what the skill actually covers.
 
 **Skillify loop (v0.19):** skillify (the markdown orchestration), skillpack-check
 (agent-readable health report).
 
+**Operational health (v0.19.1):** smoke-test (8 post-restart health checks with auto-fix
+for Bun, CLI, DB, worker, Zod CJS, gateway, API key, brain repo; user-extensible via
+`~/.gbrain/smoke-tests.d/*.sh`).
+
 **Conventions:** `skills/conventions/` has cross-cutting rules (quality, brain-first,
 model-routing, test-before-bulk, cross-modal). `skills/_brain-filing-rules.md` and
 `skills/_output-rules.md` are shared references.
@@ -461,15 +534,100 @@ in bulk paths, the CI guard will fail the build.
 
 `bun build --compile --outfile bin/gbrain src/cli.ts`
 
+## Version locations (single source of truth: `VERSION` file)
+
+Every release advances the version in **five files at once**. Keep these in
+sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs
+package.json drift), but the canonical list lives here so future runs and
+the auto-update agent know where to look.
+
+**Required (every release must update all five):**
+
+| File | What lives there | Format |
+|---|---|---|
+| `VERSION` | The single source of truth. Read first by `/ship`, the binary, and CI version-gate. | Bare 4-digit string `MAJOR.MINOR.PATCH.MICRO` (e.g. `0.22.1`), no leading `v`, no trailing newline-sensitivity issues. |
+| `package.json` | Bun/npm package version. `gbrain --version` reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against `VERSION` and fails if they drift. | `"version": "0.22.1"` |
+| `CHANGELOG.md` | Top entry header `## [0.22.1] - YYYY-MM-DD` plus the "To take advantage of v0.22.1" block. | Standard Keep-a-Changelog header. |
+| `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z` references in TODO bodies. |
+| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z (#NNN, contributed by @user)` references. |
+
+**Auto-derived (no manual edit; refreshed by their own commands):**
+
+- `bun.lock` — root-package version is auto-pinned from `package.json`. After
+  bumping `package.json`, run `bun install` to refresh the lockfile.
+- `llms-full.txt` / `llms.txt` — auto-generated documentation bundles. After
+  any release ship that touches the Key Files annotations in `CLAUDE.md`,
+  run `bun run build:llms` to regenerate. The bundles do not contain a
+  version pin per se; they reflect the current state of the docs they index.
+
+**Historical (DO NOT bump on release):**
+
+- `skills/migrations/v0.21.0.md` — migration files use the version they
+  shipped FROM as their filename. v0.21.0's migration always says v0.21.0.
+- `src/commands/migrations/v0_21_0.ts` — same: migration code references
+  the schema version it migrates to.
+- `test/migrations-v0_21_0.test.ts`, `test/migration-orchestrator-v0_21_0.test.ts`,
+  `test/migrate.test.ts` — migration tests reference historical migration
+  versions; these are correct as-is and should not move.
+- `src/core/db.ts`, `src/core/migrate.ts`, `src/core/import-file.ts`,
+  `src/commands/reindex-code.ts` — code comments cite the release that
+  introduced a feature. Once written, these are historical record.
+- `README.md` — references the latest published feature names by version
+  (e.g. "v0.21.0 Code Cathedral"); update only when the README's marketing
+  copy is intentionally being refreshed, NOT on every micro/patch bump.
+
+**The /ship workflow's version idempotency check:** Step 12 reads
+`VERSION` and `package.json`, classifies as FRESH / ALREADY_BUMPED /
+DRIFT_STALE_PKG / DRIFT_UNEXPECTED, and refuses to proceed on
+DRIFT_UNEXPECTED. This is why the two must move together.
+
+**The CI version-gate** rejects pushes where `VERSION` and
+`package.json` disagree, OR where `VERSION` is not strictly greater
+than master's VERSION. If a queue collision claims your version on
+master before yours lands, /ship's queue-aware allocator (Step 12)
+will detect drift and re-bump on the next run.
+
 ## Pre-ship requirements
 
-Before shipping (/ship) or reviewing (/review), always run the full test suite:
+Before shipping (/ship) or reviewing (/review), always run the full test suite.
+Two equivalent paths:
+
+**Path A — local CI gate (recommended, v0.23.1+):**
+- `bun run ci:local` runs the entire stack inside Docker: gitleaks (host), unit
+  tests with `DATABASE_URL` unset, and all 29 E2E files sequentially against a
+  fresh pgvector container. Stronger than PR CI's 2-file Tier 1 set; closer to
+  what nightly Tier 1 catches. Spins up + tears down postgres automatically via
+  `docker-compose.ci.yml`. Override the host port with
+  `GBRAIN_CI_PG_PORT=5435 bun run ci:local` if 5434 collides.
+- `bun run ci:local:diff` runs only the E2E files matched by the diff selector
+  (`scripts/select-e2e.ts`), falling back to all 29 on unmapped src/ paths or
+  schema/skills/package.json changes. Fast iteration during a focused branch.
+
+**Path B — manual lifecycle (still supported):**
 - `bun test` — unit tests (no database required)
 - Follow the "E2E test DB lifecycle" steps above to spin up the test DB,
   run `bun run test:e2e`, then tear it down.
 
 Both must pass. Do not ship with failing E2E tests. Do not skip E2E tests.
 
+**Always run typecheck before pushing.** `bun test` (the bun runner)
+skips TypeScript type checking — it only enforces runtime behavior.
+Three ways to actually gate on types:
+
+1. `bun run test` (npm script in `package.json`) — includes `bun run typecheck`
+   plus the four shell pre-checks (`check-jsonb-pattern.sh`,
+   `check-progress-to-stdout.sh`, `check-trailing-newline.sh`,
+   `check-wasm-embedded.sh`) before the runner. Use this mid-branch.
+2. `bun run typecheck` — `tsc --noEmit` standalone. Fast (~5s on this repo).
+3. `bun run ci:local` — the full local CI gate from Path A.
+
+The trap is: writing a new test, running `bun test test/foo.test.ts`,
+seeing it pass, pushing — and CI's separate typecheck stage rejects an
+invalid type literal that the runner accepted. Caught one of these
+shipping the v0.23.2 round-trip E2E (`type: 'reflection'` is not a
+member of `PageType`). Run `bun run typecheck` once before push, even
+when only test files changed.
+
 ## Post-ship requirements (MANDATORY)
 
 After EVERY /ship, you MUST run /document-release. This is NOT optional. Do NOT
@@ -1035,8 +1193,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
@@ -1096,13 +1255,15 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 
 | Trigger | Skill |
 |---------|-------|
-| "What do we know about", "tell me about", "search for" | `skills/query/SKILL.md` |
+| "What do we know about", "tell me about", "search for", "who is", "background on", "notes on" | `skills/query/SKILL.md` |
 | "Who knows who", "relationship between", "connections", "graph query" | `skills/query/SKILL.md` (use graph-query) |
 | Creating/enriching a person or company page | `skills/enrich/SKILL.md` |
 | Where does a new file go? Filing rules | `skills/repo-architecture/SKILL.md` |
 | Fix broken citations in brain pages | `skills/citation-fixer/SKILL.md` |
+| "citation audit", "check citations", "fix citations" | `skills/citation-fixer/SKILL.md` (focused fix). For broader brain health, chain into `skills/maintain/SKILL.md` |
 | "Research", "track", "extract from email", "investor updates", "donations" | `skills/data-research/SKILL.md` |
 | Share a brain page as a link | `skills/publish/SKILL.md` |
+| "validate frontmatter", "check frontmatter", "fix frontmatter", "frontmatter audit", "brain lint" | `skills/frontmatter-guard/SKILL.md` |
 
 ## Content & media ingestion
 
@@ -1141,7 +1302,7 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 | Cross-modal review, second opinion | `skills/cross-modal-review/SKILL.md` |
 | "Validate skills", skill health check | `skills/testing/SKILL.md` |
 | Webhook setup, external event processing | `skills/webhook-transforms/SKILL.md` |
-| "Spawn agent", "background task", "parallel tasks", "steer agent", "pause/resume agent" | `skills/minion-orchestrator/SKILL.md` |
+| "Spawn agent", "background task", "parallel tasks", "steer agent", "pause/resume agent", "gbrain jobs submit", "submit a gbrain job", "submit a shell job", "shell job" | `skills/minion-orchestrator/SKILL.md` |
 
 ## Setup & migration
 
@@ -1151,6 +1312,7 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 | "Migrate from Obsidian/Notion/Logseq" | `skills/migrate/SKILL.md` |
 | Brain health check, maintenance run | `skills/maintain/SKILL.md` |
 | "Extract links", "build link graph", "populate timeline" | `skills/maintain/SKILL.md` (extraction sections) |
+| "Run dream", "process today's session", "synthesize my conversations", "consolidate yesterday's conversations", "what patterns did you see", "did the dream cycle run" | `skills/maintain/SKILL.md` (dream cycle section) |
 | "Brain health", "what features am I missing", "brain score" | Run `gbrain features --json` |
 | "Set up autopilot", "run brain maintenance", "keep brain updated" | Run `gbrain autopilot --install --repo ~/brain` |
 | Agent identity, "who am I", customize agent | `skills/soul-audit/SKILL.md` |
@@ -1198,7 +1360,7 @@ Built by the President and CEO of Y Combinator to run his actual AI agents. The
 
 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. 28 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
+GBrain is those patterns, generalized. 29 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
 
 > **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
 
@@ -1220,7 +1382,7 @@ 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 28 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 29 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
@@ -1272,16 +1434,33 @@ Add to `~/.claude/server.json` (Claude Code), Settings > MCP Servers (Cursor), o
 ### Remote MCP (Claude Desktop, Cowork, Perplexity)
 
 ```bash
-ngrok http 8787 --url your-brain.ngrok.app
-bun run src/commands/auth.ts create "claude-desktop"
+gbrain auth create "claude-desktop"            # tokens via the existing CLI
+gbrain serve --http --port 8787                 # built-in HTTP transport (Postgres-only)
+ngrok http 8787 --url your-brain.ngrok.app      # any tunnel works
 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).
+Per-client guides: [`docs/mcp/`](docs/mcp/DEPLOY.md). Hardening defaults, env vars, and threat model: [SECURITY.md](SECURITY.md). ChatGPT requires OAuth 2.1 (not yet implemented).
 
-## The 28 Skills
+### Using gbrain with GStack
 
-GBrain ships 28 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.
+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 29 Skills
+
+GBrain ships 29 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.
 
 [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.
 
@@ -1307,7 +1486,7 @@ GBrain ships 28 skills organized by `skills/RESOLVER.md` (or your OpenClaw's `AG
 |-------|-------------|
 | **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. |
@@ -1327,7 +1506,8 @@ GBrain ships 28 skills organized by `skills/RESOLVER.md` (or your OpenClaw's `AG
 | **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. |
-| **minion-orchestrator** | Long-running agent work as background jobs. Submit, fan out children with depth/cap/timeouts, collect results via child_done inbox. |
+| **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
 
@@ -1490,9 +1670,11 @@ is what you spend time on. Everything else is boilerplate the CLI writes for you
 
 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 --llm` runs an LLM tie-break layer for CI. 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.
+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
 
@@ -1529,11 +1711,39 @@ gbrain skillpack diff brain-ops                # compare bundle vs your local co
 
 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.
@@ -1569,7 +1779,7 @@ Run `gbrain integrations` to see status.
 │   Brain Repo     │    │    GBrain     │    │    AI Agent      │
 │   (git)          │    │  (retrieval)  │    │  (read/write)    │
 │                  │    │               │    │                  │
-│  markdown files  │───>│  Postgres +   │<──>│  28 skills       │
+│  markdown files  │───>│  Postgres +   │<──>│  29 skills       │
 │  = source of     │    │  pgvector     │    │  define HOW to   │
 │    truth         │    │               │    │  use the brain   │
 │                  │<───│  hybrid       │    │                  │
@@ -1680,6 +1890,8 @@ Question
   │    ├─ 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)
@@ -1787,8 +1999,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
@@ -1830,9 +2045,15 @@ ADMIN
   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 8787       MCP server (HTTP, Postgres-only, bearer auth)
+  gbrain auth create|list|revoke|test   Token management for the HTTP transport
   gbrain integrations                   Integration recipe dashboard
   gbrain sources list|add|remove|...    Multi-source brain management (v0.18)
-  gbrain dream [--dry-run] [--phase N]  One maintenance cycle then exit (cron-friendly)
+  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)
@@ -1875,7 +2096,7 @@ The skills in this repo are those patterns, generalized. What took 11 days to bu
 
 ## 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 test` for unit tests. 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.
 
 PRs welcome for: new enrichment APIs, performance optimizations, additional engine backends, new skills following the conformance standard in `skills/skill-creator/SKILL.md`.
 
@@ -4010,9 +4231,14 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/mcp/DEPLOY
 
 # Deploy GBrain Remote MCP Server
 
+> **v0.22.7+:** Use `gbrain serve --http` for remote access. It includes built-in
+> bearer token auth, default-deny CORS, two-bucket rate limiting, body cap, and
+> per-request audit log. **Postgres-only** (PGLite is local-only by design).
+> See [SECURITY.md](../../SECURITY.md) for env vars and tunable defaults.
+
 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.
+via `gbrain serve` (stdio). For remote access, expose it via the built-in HTTP
+transport behind a public tunnel.
 
 ## Two Paths
 
@@ -4023,21 +4249,23 @@ 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 (any device, any AI client) — 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
 
@@ -4056,13 +4284,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
@@ -4078,7 +4306,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
 ```
@@ -4106,7 +4334,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.
@@ -5140,6 +5368,75 @@ 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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbrain",
-  "version": "0.20.2",
+  "version": "0.24.0",
   "description": "Postgres-native personal knowledge brain with hybrid RAG search",
   "type": "module",
   "main": "src/core/index.ts",
@@ -32,10 +32,19 @@
     "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:schema": "bash scripts/build-schema.sh",
     "build:llms": "bun run scripts/build-llms.ts",
-    "test": "scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && bun run typecheck && bun test",
+    "build:pglite-snapshot": "bun run scripts/build-pglite-snapshot.ts",
+    "test": "scripts/check-privacy.sh && scripts/check-jsonb-pattern.sh && scripts/check-progress-to-stdout.sh && scripts/check-trailing-newline.sh && scripts/check-wasm-embedded.sh && bun run typecheck && bun test --timeout=60000",
+    "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",
+    "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",
     "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",
@@ -49,16 +58,20 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.30.0",
     "@aws-sdk/client-s3": "^3.1028.0",
+    "@dqbd/tiktoken": "^1.0.22",
     "@electric-sql/pglite": "0.4.3",
     "@modelcontextprotocol/sdk": "^1.0.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"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "bun-types": "^1.3.13",
     "typescript": "^5.6.0"
   },
   "trustedDependencies": [

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-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,63 @@
+// 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",
+  ],
+  // PGLite bootstrap path + parity guard.
+  "src/core/pglite-engine.ts": [
+    "test/e2e/postgres-bootstrap.test.ts",
+    "test/e2e/engine-parity.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/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

@@ -15,22 +15,85 @@
 # 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 test/e2e/*.test.ts; do
+for f in "${files[@]}"; do
   name=$(basename "$f")
   echo ""
   echo "=== $name ==="
-  if output=$(bun test "$f" 2>&1); then
+  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)

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[@]}"

scripts/run-unit-shard.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# scripts/run-unit-shard.sh
+#
+# Runs the unit suite for a single shard. Excludes test/e2e/* (those are run
+# by scripts/run-e2e.sh in the E2E phase). When SHARD=N/M is set, keeps every
+# M-th file starting at index N (1-indexed); otherwise runs the full unit set.
+#
+# Used by scripts/ci-local.sh to fan 4 unit-shard workers in parallel inside
+# the runner container, each pinned to its own postgres shard for the
+# downstream E2E phase.
+#
+# Sequential bun processes within a shard (one bun test invocation with the
+# shard's file list); parallel across shards (4 of these run concurrently).
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# All non-E2E test files, sorted for deterministic shard splits.
+# Tier 4: *.slow.test.ts is the convention for "always-slow" tests (e.g.,
+# bootstrap correctness checks that intentionally exercise the cold init
+# path and can't benefit from Tier 3's snapshot). They're excluded from the
+# fast loop and run via `bun run test:slow` (or in CI where everything runs).
+# Use while-read to stay portable to macOS bash 3.2 (no mapfile).
+all_files=()
+while IFS= read -r f; do
+  all_files+=("$f")
+done < <(find test -name '*.test.ts' -not -path 'test/e2e/*' -not -name '*.slow.test.ts' | sort)
+
+files=()
+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
+  i=0
+  for f in "${all_files[@]}"; do
+    if [ $((i % shard_m + 1)) -eq "$shard_n" ]; then
+      files+=("$f")
+    fi
+    i=$((i + 1))
+  done
+else
+  files=("${all_files[@]}")
+fi
+
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "[unit-shard ${SHARD:-(unsharded)}] no files; exiting clean."
+  exit 0
+fi
+
+# --dry-run-list mirrors scripts/run-e2e.sh for inline smoke checks.
+if [ "${1:-}" = "--dry-run-list" ]; then
+  printf '%s\n' "${files[@]}"
+  exit 0
+fi
+
+echo "[unit-shard ${SHARD:-(unsharded)}] running ${#files[@]} files"
+exec bun test --timeout=60000 "${files[@]}"

scripts/select-e2e.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env bun
+// scripts/select-e2e.ts
+//
+// Fail-closed diff-based E2E test selector. Reads the working-tree diff vs
+// origin/master plus untracked files, classifies the change set as
+// EMPTY / DOC_ONLY / SRC, and emits the relevant E2E test files on stdout.
+//
+// CONTRACT (fail-closed):
+//   - When in doubt, run all E2E. The map narrows from "all"; it never widens
+//     from "none". An unmapped src/ change emits ALL test/e2e/*.test.ts.
+//   - Doc-only diffs emit nothing (the only case where stdout is empty).
+//   - Empty diff emits ALL (clean branch shouldn't run nothing).
+//
+// Selection algorithm:
+//   1. Read changed files from three git sources, union them:
+//        - git diff --name-only origin/master...HEAD   (committed)
+//        - git diff --name-only HEAD                   (unstaged + staged)
+//        - git ls-files --others --exclude-standard    (untracked, NOT .gitignore'd)
+//   2. EMPTY  -> emit ALL test/e2e/*.test.ts
+//      DOC_ONLY (every path matches doc allowlist) -> emit nothing
+//      SRC (at least one path is outside doc allowlist):
+//        a. Any escape-hatch path matched -> emit ALL
+//        b. Else union map matches; include directly-modified test/e2e/*.test.ts
+//        c. If still empty -> FAIL-CLOSED -> emit ALL
+//
+// On git command failure: print error to stderr and exit 2 so callers see the
+// failure (xargs -r will run nothing AND the human sees the error).
+//
+// Usage:
+//   bun run scripts/select-e2e.ts
+//   bun run scripts/select-e2e.ts | xargs -r bash scripts/run-e2e.sh
+
+import { spawnSync } from "node:child_process";
+import { readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { E2E_TEST_MAP } from "./e2e-test-map.ts";
+
+// Doc allowlist (inclusive). A path counts as doc-only ONLY if it matches one
+// of these patterns. Unrecognized paths fall through to SRC, never silently
+// doc-only. skills/ is intentionally NOT here — skills are product input.
+const DOC_ROOT_FILES = new Set([
+  "README.md",
+  "CLAUDE.md",
+  "AGENTS.md",
+  "CHANGELOG.md",
+  "TODOS.md",
+  "LICENSE",
+  "VERSION",
+]);
+
+function isDocPath(p: string): boolean {
+  if (DOC_ROOT_FILES.has(p)) return true;
+  // Any *.md at repo root.
+  if (!p.includes("/") && p.endsWith(".md")) return true;
+  // Anything under docs/.
+  if (p.startsWith("docs/")) return true;
+  return false;
+}
+
+// Escape-hatch triggers. Any match -> emit ALL.
+const ESCAPE_HATCH_FILES = new Set([
+  "src/schema.sql",
+  "src/core/migrate.ts",
+  "src/core/db.ts",
+  "src/core/engine-factory.ts",
+  "src/core/operations.ts",
+  "package.json",
+  "bun.lock",
+  "Dockerfile.ci",
+  "docker-compose.ci.yml",
+  "scripts/ci-local.sh",
+  "scripts/run-e2e.sh",
+  "scripts/select-e2e.ts",
+  "scripts/e2e-test-map.ts",
+  "test/e2e/helpers.ts",
+]);
+
+const ESCAPE_HATCH_PREFIXES = [
+  "src/commands/migrations/",
+  "test/e2e/fixtures/",
+  "skills/",
+  ".github/workflows/",
+];
+
+function isEscapeHatch(p: string): boolean {
+  if (ESCAPE_HATCH_FILES.has(p)) return true;
+  for (const prefix of ESCAPE_HATCH_PREFIXES) {
+    if (p.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+// Minimal glob matcher: supports ** (any segments) and * (one segment, no /).
+// Throws on unsupported syntax so map mistakes surface loudly.
+export function matchGlob(glob: string, path: string): boolean {
+  if (glob.includes("?") || glob.includes("[") || glob.includes("{")) {
+    throw new Error(
+      `select-e2e: unsupported glob syntax in "${glob}" (only ** and * are supported)`
+    );
+  }
+  // Build a regex: ** -> .*, * -> [^/]*, escape other regex meta-chars.
+  let regex = "";
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === "*" && glob[i + 1] === "*") {
+      regex += ".*";
+      i += 2;
+    } else if (c === "*") {
+      regex += "[^/]*";
+      i += 1;
+    } else if (/[.+^${}()|\\]/.test(c)) {
+      regex += "\\" + c;
+      i += 1;
+    } else {
+      regex += c;
+      i += 1;
+    }
+  }
+  return new RegExp("^" + regex + "$").test(path);
+}
+
+function listAllE2ETests(repoRoot: string): string[] {
+  const dir = join(repoRoot, "test/e2e");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".test.ts"))
+    .map((f) => `test/e2e/${f}`)
+    .sort();
+}
+
+// Pure function — exposed for unit tests. Decides what to emit given the
+// inputs, without touching git or filesystem (callers pass arrays in).
+export interface SelectInputs {
+  changedFiles: string[]; // union of three git sources
+  allE2ETests: string[]; // glob result of test/e2e/*.test.ts
+  map: Record<string, string[]>; // E2E_TEST_MAP
+}
+
+export type Classification = "EMPTY" | "DOC_ONLY" | "SRC";
+
+export function classify(changedFiles: string[]): Classification {
+  if (changedFiles.length === 0) return "EMPTY";
+  for (const f of changedFiles) {
+    if (!isDocPath(f)) return "SRC";
+  }
+  return "DOC_ONLY";
+}
+
+export function selectTests(inputs: SelectInputs): string[] {
+  const { changedFiles, allE2ETests, map } = inputs;
+  const cls = classify(changedFiles);
+  const allSorted = allE2ETests.slice().sort();
+
+  if (cls === "EMPTY") return allSorted;
+  if (cls === "DOC_ONLY") return [];
+
+  // SRC case.
+  // 3a. Any escape-hatch -> ALL.
+  for (const f of changedFiles) {
+    if (isEscapeHatch(f)) return allSorted;
+  }
+
+  // 3b. Union map matches; include directly-modified test files.
+  const result = new Set<string>();
+  for (const f of changedFiles) {
+    if (isDocPath(f)) continue;
+    // Direct test file modification: include it.
+    if (f.startsWith("test/e2e/") && f.endsWith(".test.ts")) {
+      result.add(f);
+      continue;
+    }
+    for (const [glob, tests] of Object.entries(map)) {
+      if (matchGlob(glob, f)) {
+        for (const t of tests) result.add(t);
+      }
+    }
+  }
+
+  // 3c. Fail-closed: if no map entry matched any src/ path AND no test files
+  // were directly modified, run everything.
+  if (result.size === 0) return allSorted;
+
+  // Sort for determinism (helps tests + readability).
+  return Array.from(result).sort();
+}
+
+function runGit(args: string[], cwd: string): string {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").trim();
+    process.stderr.write(
+      `select-e2e: git ${args.join(" ")} failed: ${stderr}\n`
+    );
+    process.exit(2);
+  }
+  return result.stdout || "";
+}
+
+function readChangedFiles(repoRoot: string): string[] {
+  const sources = [
+    runGit(["diff", "--name-only", "origin/master...HEAD"], repoRoot),
+    runGit(["diff", "--name-only", "HEAD"], repoRoot),
+    runGit(["ls-files", "--others", "--exclude-standard"], repoRoot),
+  ];
+  const set = new Set<string>();
+  for (const out of sources) {
+    for (const line of out.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.length > 0) set.add(trimmed);
+    }
+  }
+  return Array.from(set).sort();
+}
+
+// Entrypoint. Skipped under test (Bun.main check).
+if (import.meta.main) {
+  const repoRoot = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+  }).stdout?.trim();
+  if (!repoRoot) {
+    process.stderr.write("select-e2e: not a git repository\n");
+    process.exit(2);
+  }
+
+  const changedFiles = readChangedFiles(repoRoot);
+
+  // --classify-only: print EMPTY|DOC_ONLY|SRC + exit. Used by ci-local.sh's
+  // Tier 2 fast-path so doc-only diffs skip the unit phase entirely.
+  if (process.argv.includes("--classify-only")) {
+    process.stdout.write(classify(changedFiles) + "\n");
+    process.exit(0);
+  }
+
+  const allE2ETests = listAllE2ETests(repoRoot);
+  const tests = selectTests({
+    changedFiles,
+    allE2ETests,
+    map: E2E_TEST_MAP,
+  });
+
+  process.stdout.write(tests.join(" "));
+  if (tests.length > 0) process.stdout.write("\n");
+}

scripts/test-shard.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Partition unit test files into N shards by stable hash and run one shard.
+#
+# Usage: scripts/test-shard.sh <shard-index> <total-shards>
+#   shard-index: 1-based (1..N)
+#   total-shards: positive integer
+#
+# E2E tests under test/e2e/ are excluded — they need DATABASE_URL and run via
+# bun run test:e2e separately.
+#
+# Stable partitioning: a file's shard is `(hash(path) % N) + 1`. Same file
+# lands in the same shard on every run, regardless of how many other files
+# exist, so retries are reproducible. Hash is FNV-1a — pure shell, no jq.
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  echo "usage: scripts/test-shard.sh <shard-index> <total-shards>" >&2
+  exit 1
+fi
+
+SHARD_INDEX="$1"
+TOTAL_SHARDS="$2"
+
+if ! [[ "$SHARD_INDEX" =~ ^[0-9]+$ ]] || ! [[ "$TOTAL_SHARDS" =~ ^[0-9]+$ ]]; then
+  echo "error: shard index and total must be positive integers" >&2
+  exit 1
+fi
+if [ "$SHARD_INDEX" -lt 1 ] || [ "$SHARD_INDEX" -gt "$TOTAL_SHARDS" ]; then
+  echo "error: shard index $SHARD_INDEX out of range 1..$TOTAL_SHARDS" >&2
+  exit 1
+fi
+
+cd "$(dirname "$0")/.."
+
+# Find all unit test files, deterministic order. Excludes test/e2e/.
+# Portable: avoid `mapfile` (bash 4+) so this runs on macOS bash 3.2 too.
+FILES=()
+while IFS= read -r line; do
+  FILES+=("$line")
+done < <(find test -name '*.test.ts' -not -path 'test/e2e/*' | sort)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo "no test files found under test/" >&2
+  exit 1
+fi
+
+# FNV-1a 32-bit hash of a string — implemented in pure bash so we don't depend
+# on python/openssl/etc on the runner. Output is decimal.
+fnv1a() {
+  local str="$1"
+  local h=2166136261  # FNV offset basis
+  local i ord
+  for (( i=0; i<${#str}; i++ )); do
+    ord=$(printf '%d' "'${str:$i:1}")
+    h=$(( (h ^ ord) & 0xFFFFFFFF ))
+    h=$(( (h * 16777619) & 0xFFFFFFFF ))
+  done
+  echo "$h"
+}
+
+SHARD_FILES=()
+for f in "${FILES[@]}"; do
+  hash=$(fnv1a "$f")
+  bucket=$(( hash % TOTAL_SHARDS + 1 ))
+  if [ "$bucket" -eq "$SHARD_INDEX" ]; then
+    SHARD_FILES+=("$f")
+  fi
+done
+
+echo "shard $SHARD_INDEX/$TOTAL_SHARDS: ${#SHARD_FILES[@]}/${#FILES[@]} files"
+if [ "${#SHARD_FILES[@]}" -eq 0 ]; then
+  echo "warning: shard $SHARD_INDEX has no files (rehash or reduce shard count)" >&2
+  exit 0
+fi
+
+exec bun test --timeout=60000 "${SHARD_FILES[@]}"

skills/RESOLVER.md

@@ -13,13 +13,15 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 
 | Trigger | Skill |
 |---------|-------|
-| "What do we know about", "tell me about", "search for" | `skills/query/SKILL.md` |
+| "What do we know about", "tell me about", "search for", "who is", "background on", "notes on" | `skills/query/SKILL.md` |
 | "Who knows who", "relationship between", "connections", "graph query" | `skills/query/SKILL.md` (use graph-query) |
 | Creating/enriching a person or company page | `skills/enrich/SKILL.md` |
 | Where does a new file go? Filing rules | `skills/repo-architecture/SKILL.md` |
 | Fix broken citations in brain pages | `skills/citation-fixer/SKILL.md` |
+| "citation audit", "check citations", "fix citations" | `skills/citation-fixer/SKILL.md` (focused fix). For broader brain health, chain into `skills/maintain/SKILL.md` |
 | "Research", "track", "extract from email", "investor updates", "donations" | `skills/data-research/SKILL.md` |
 | Share a brain page as a link | `skills/publish/SKILL.md` |
+| "validate frontmatter", "check frontmatter", "fix frontmatter", "frontmatter audit", "brain lint" | `skills/frontmatter-guard/SKILL.md` |
 
 ## Content & media ingestion
 
@@ -58,7 +60,7 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 | Cross-modal review, second opinion | `skills/cross-modal-review/SKILL.md` |
 | "Validate skills", skill health check | `skills/testing/SKILL.md` |
 | Webhook setup, external event processing | `skills/webhook-transforms/SKILL.md` |
-| "Spawn agent", "background task", "parallel tasks", "steer agent", "pause/resume agent" | `skills/minion-orchestrator/SKILL.md` |
+| "Spawn agent", "background task", "parallel tasks", "steer agent", "pause/resume agent", "gbrain jobs submit", "submit a gbrain job", "submit a shell job", "shell job" | `skills/minion-orchestrator/SKILL.md` |
 
 ## Setup & migration
 
@@ -68,6 +70,7 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 | "Migrate from Obsidian/Notion/Logseq" | `skills/migrate/SKILL.md` |
 | Brain health check, maintenance run | `skills/maintain/SKILL.md` |
 | "Extract links", "build link graph", "populate timeline" | `skills/maintain/SKILL.md` (extraction sections) |
+| "Run dream", "process today's session", "synthesize my conversations", "consolidate yesterday's conversations", "what patterns did you see", "did the dream cycle run" | `skills/maintain/SKILL.md` (dream cycle section) |
 | "Brain health", "what features am I missing", "brain score" | Run `gbrain features --json` |
 | "Set up autopilot", "run brain maintenance", "keep brain updated" | Run `gbrain autopilot --install --repo ~/brain` |
 | Agent identity, "who am I", customize agent | `skills/soul-audit/SKILL.md` |

skills/_brain-filing-rules.json

@@ -97,5 +97,15 @@
     "The PRIMARY SUBJECT of the content determines the directory, not the format or source skill.",
     "When in doubt: what would you search for to find this page again?",
     "Cross-link from related directories via back-links — do not duplicate content."
-  ]
+  ],
+  "dream_synthesize_paths": {
+    "description": "Single source of truth for the v0.23 dream-cycle synthesize/patterns trusted-workspace allow-list. The cycle's synthesize phase reads this list and threads it as `allowed_slug_prefixes` to every subagent it dispatches; put_page enforces it server-side. Editing this list is the ONLY way to add a new directory the synthesis subagent may write to.",
+    "globs": [
+      "wiki/personal/reflections/*",
+      "wiki/originals/*",
+      "wiki/personal/patterns/*",
+      "wiki/people/*",
+      "dream-cycle-summaries/*"
+    ]
+  }
 }

skills/_brain-filing-rules.md

@@ -112,3 +112,24 @@ gbrain files restore <dir>                # Download back to local
 
 This ensures any derived brain page can be traced back to its original source,
 and large files don't bloat the git repo.
+
+## Dream-cycle synthesize / patterns directories (v0.23)
+
+The `synthesize` and `patterns` phases of `gbrain dream` write to a
+**fixed allow-list** of paths sourced from `_brain-filing-rules.json`'s
+`dream_synthesize_paths.globs` array. Editing that JSON is the ONLY way
+to add a new directory the synthesis subagent may write to:
+
+| Output type | Slug pattern | What goes here |
+|-------------|--------------|----------------|
+| Reflection | `wiki/personal/reflections/YYYY-MM-DD-<topic>-<hash[:6]>` | Self-knowledge, emotional processing, pattern recognition. Verbatim quotes from the user, with analysis. |
+| Original idea | `wiki/originals/ideas/YYYY-MM-DD-<idea>-<hash[:6]>` | New frames, theses, mental models, "conceptive ideologist" outputs. Capture the user's exact phrasing — that's the artifact. |
+| People enrichment | `wiki/people/<existing-slug>` | Timeline entries appended to existing people pages from session mentions. Stub pages for new substantive people. |
+| Pattern | `wiki/personal/patterns/<theme>` | Cross-session theme detected across ≥3 reflections. Highest-leverage output: a pattern can span 25 years if reflections reference dated content. |
+| Cycle summary | `dream-cycle-summaries/YYYY-MM-DD` | Index of every page produced by one dream cycle. Auto-written deterministically by the orchestrator. |
+
+**Iron Law for synthesize output:**
+1. Quote the user verbatim. Do not paraphrase memorable phrasings.
+2. Cross-reference compulsively: every new page MUST link to existing brain content.
+3. Slug discipline: lowercase alphanumeric and hyphens only, slash-separated. NO underscores, NO file extensions.
+4. Edited transcripts produce NEW slugs (content-hash suffix changes) — never silently overwrite a prior reflection.

skills/_friction-protocol.md

@@ -0,0 +1,60 @@
+# Friction protocol — convention
+
+> Cross-cutting rule shared by skills the claw-test harness exercises (setup,
+> brain-ops, query, ingest, smoke-test, migrations). Reference via
+> `> **Convention:** see [skills/_friction-protocol.md](_friction-protocol.md).`
+
+When you encounter friction running gbrain — anything confusing, missing, surprising, or wrong — log it via `gbrain friction log` so maintainers can see it without you writing a bug report. Friction reports drive the claw-test feedback loop (the harness collects, renders, and re-runs).
+
+## When to log
+
+Log friction when any of these happens:
+
+- A command failed with a non-actionable error message
+- A doc said one thing and the tool did another
+- You couldn't find the next step
+- A setup command needed a manual workaround
+- A flag exists but isn't documented in `--help`
+- A success condition was unclear (you couldn't tell if the command worked)
+
+Log delight (positive signal) when:
+
+- Something worked on the first try and the docs were exactly right
+- An error message handed you the fix
+- A flag you guessed at turned out to exist with the obvious name
+
+## How to log
+
+```
+gbrain friction log \
+  --severity {confused|error|blocker|nit} \
+  --phase <which-phase-or-command> \
+  --message "<one-line-what-happened>" \
+  [--hint "<one-line-what-could-be-better>"]
+```
+
+For delight, add `--kind delight` and pick any severity.
+
+The CLI auto-fills `ts`, `cwd`, `gbrain_version`, and resolves `run_id` from `$GBRAIN_FRICTION_RUN_ID` (set by the harness) or falls back to `standalone.jsonl`. So you can call this anywhere — inside a harness run, manually during normal use, or from a scripted test.
+
+## Severity guide
+
+| severity   | meaning |
+|------------|---------|
+| `blocker`  | Couldn't proceed at all. Hard stop. |
+| `error`    | Command failed unexpectedly. |
+| `confused` | Docs/tool mismatch, ambiguity, missing pointer. |
+| `nit`      | Polish opportunity. Cosmetic or low-impact. |
+
+Be specific: "doctor says `schema_version=0` and points at apply-migrations, but apply-migrations exits 0 with no output" beats "doctor was confusing."
+
+## Inspecting reports
+
+```
+gbrain friction list                      # recent runs with counts
+gbrain friction render --run-id <id>      # markdown report (default)
+gbrain friction render --run-id <id> --json
+gbrain friction summary --run-id <id>     # friction + delight side-by-side
+```
+
+`render` defaults to `--redact` for markdown (strips `$HOME`/`$CWD` to `<HOME>`/`<CWD>` placeholders) so reports paste safely into PRs and issues.

skills/citation-fixer/routing-eval.jsonl

@@ -1,7 +1,7 @@
 // Routing eval fixtures for skills/citation-fixer. Check 5 (W2, v0.17).
 // Layer A (structural) requires intents to contain trigger words from
 // the resolver. Paraphrase the trigger framing, not its meaning.
-{"intent": "please fix broken citations across the latest batch of pages", "expected_skill": "citation-fixer"}
-{"intent": "I think we need to fix broken citations in these brain pages", "expected_skill": "citation-fixer"}
+{"intent": "please fix citations in the latest batch of brain pages", "expected_skill": "citation-fixer"}
+{"intent": "I need to fix citations across these pages", "expected_skill": "citation-fixer"}
 // Negative case: something that sounds similar but should NOT route here.
 {"intent": "What does this book say about mentorship", "expected_skill": null, "ambiguous_with": []}

skills/conventions/brain-first.md

@@ -1,21 +1,75 @@
 # Brain-First Lookup Convention
 
-Before using ANY external API (web search, enrichment services, social APIs) to
-research a person, company, or topic, check the brain first.
+**Read this before doing ANY entity/person/company/fact lookup.**
 
-## The 5-Step Lookup
+Sub-agents and fresh sessions inherit gbrain tools but not the knowledge of
+when and how to use them. This file is that knowledge.
 
-1. `gbrain search "name"` — keyword search for existing pages
-2. `gbrain query "natural question about name"` — hybrid search for related context
-3. `gbrain get <slug>` — if you know the slug, read the full page
-4. Check backlinks: `gbrain get_backlinks <slug>` — who references this entity?
-5. Check timeline: `gbrain get_timeline <slug>` — recent events involving this entity
+## Available GBrain Tools
 
-The brain almost always has something. External APIs fill gaps, not start from scratch.
+Your tool inventory includes these (prefixed `gbrain__` in OpenClaw):
 
-## Why This Matters
+| Tool | Use for |
+|------|---------|
+| `gbrain__search` / `search` | Keyword search — fast, always works |
+| `gbrain__query` / `query` | Hybrid search (keyword + semantic) — best quality |
+| `gbrain__get_page` / `get_page` | Direct page read when you know the slug |
+| `gbrain__get_links` / `get_links` | Outgoing links from a page |
+| `gbrain__get_backlinks` / `get_backlinks` | Who references this entity |
+| `gbrain__get_timeline` / `get_timeline` | Dated events for an entity |
+| `gbrain__resolve_slugs` / `resolve_slugs` | Fuzzy slug resolution |
+| `gbrain__traverse_graph` / `traverse_graph` | Walk the relationship graph |
+| `gbrain__put_page` / `put_page` | Create or update a brain page |
+| `gbrain__add_timeline_entry` | Add a dated event |
+| `gbrain__add_link` | Add a relationship edge |
 
-- The brain has context that external APIs don't (user's direct observations, meeting notes, personal relationships)
-- External API calls cost money and time
-- Brain context makes external lookups more targeted (you know what's missing)
-- The user's direct statements are highest-authority data. External sources are lowest.
+Tool names vary by transport (MCP uses short names, OpenClaw plugin uses
+`gbrain__` prefix). Both work. Use whichever your environment provides.
+
+## The Lookup Chain (MANDATORY ORDER)
+
+1. **`search`** first — keyword search, fast, zero API cost
+2. **`query`** if search is thin — hybrid semantic search, uses embedding API
+3. **`get_page`** if you found a slug — read the full compiled truth
+4. **External APIs only after steps 1-2 return nothing useful**
+
+Never skip to external APIs without completing steps 1-2. The brain has
+thousands of pages. The answer is almost always there.
+
+## Rules
+
+- **Score > 0.5 = use it.** Don't reach for external APIs when the brain answered.
+- **User's direct statements are highest-authority data.** The brain captures
+  what the user said in meetings, conversations, and notes. External sources
+  are supplementary.
+- **After any brain page write:** trigger a sync so new pages are searchable.
+  In OpenClaw: `gbrain__sync_brain`. From CLI: `gbrain sync --no-pull`.
+- **Every brain page reference in output** should use a clickable link format
+  appropriate to the deployment (GitHub URL, local path, or slug).
+- **Never use `memory_search` for entity lookups.** Memory tools search
+  session notes (MEMORY.md), not the brain knowledge graph. Use
+  `search` or `query` for entity lookups.
+
+## Entity Page Conventions
+
+Standard directory structure:
+
+| Directory | Type | Example |
+|-----------|------|---------|
+| `people/` | person | `people/paul-graham.md` |
+| `companies/` | company | `companies/stripe.md` |
+| `deals/` | deal | `deals/stripe-series-c.md` |
+| `meetings/` | meeting | `meetings/2026-04-23-weekly-sync.md` |
+| `projects/` | project | `projects/gbrain.md` |
+| `yc/` | yc | `yc/batch-w26.md` |
+
+When creating new pages, include proper frontmatter with `type`, `title`,
+and `tags` fields.
+
+## When Spawning Further Sub-agents
+
+If you spawn your own sub-agents, include this line in their task prompt:
+
+> Read `skills/conventions/brain-first.md` before starting work.
+
+This ensures the convention propagates through any depth of sub-agent chain.

skills/conventions/subagent-routing.md

@@ -79,7 +79,7 @@ Even when Minions is the default (mode A), some work should run inline:
 
 Before submitting batch jobs:
 
-- Check `get_job_stats` queue_health.active
+- Check active queue depth via `list_jobs --status active` (MCP-callable) or `gbrain jobs stats` (CLI)
 - If active > 5, stagger new jobs with `delay` so you don't swarm
 - The resource governor auto-throttles but don't dump 20 jobs at once
 

skills/enrich/SKILL.md

@@ -55,18 +55,7 @@ they building, what makes them tick, where are they headed.
 
 ## Citation Requirements (MANDATORY)
 
-Every fact must carry an inline `[Source: ...]` citation.
-
-Three formats:
-- **Direct attribution:** `[Source: User, {context}, YYYY-MM-DD]`
-- **API/external:** `[Source: {provider} enrichment, YYYY-MM-DD]`
-- **Synthesis:** `[Source: compiled from {list of sources}]`
-
-Source precedence (highest to lowest):
-1. User's direct statements
-2. Compiled truth (pre-existing brain synthesis)
-3. Timeline entries (raw evidence)
-4. External sources (API enrichment, web search)
+> **Convention:** see `skills/conventions/quality.md` for citation formats and source precedence.
 
 When sources conflict, note the contradiction with both citations.
 

skills/frontmatter-guard/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: frontmatter-guard
+version: 1.0.0
+description: |
+  Validate and auto-repair YAML frontmatter on brain pages. Catches malformed
+  pages before they enter the brain (missing closing ---, nested quotes, slug
+  mismatches, null bytes, empty frontmatter, YAML parse failures). Wraps the
+  `gbrain frontmatter` CLI for agent-driven workflows.
+triggers:
+  - "validate frontmatter"
+  - "check frontmatter"
+  - "fix frontmatter"
+  - "frontmatter audit"
+  - "brain lint"
+tools:
+  - exec
+mutating: true
+---
+
+# Frontmatter Guard Skill
+
+> **Convention:** see `skills/conventions/quality.md` for citation rules; this skill is structural validation, not citation auditing.
+
+## Contract
+
+This skill guarantees:
+- Every brain page is scanned against the seven canonical frontmatter validation classes
+- Mechanical errors (nested quotes, missing closing `---`, null bytes, slug mismatch) are auto-repairable on demand with `.bak` backups
+- Validation logic is shared with `gbrain doctor`'s `frontmatter_integrity` subcheck — single source of truth
+- Reports per source (gbrain is multi-source since v0.18.0); never silently audits the wrong root
+
+## Why This Exists
+
+Brain pages pile up over months. Agents write them with malformed frontmatter:
+- Missing closing `---` (entity detector bugs)
+- Unstructured YAML in meeting pages (ingestion bugs)
+- Slug mismatches (path renames not propagated)
+- Null bytes (binary corruption from copy-paste accidents)
+- Nested double quotes in titles (`title: "Phil "Nick" Last"`)
+
+Without a guard, these accumulate silently until `gbrain sync` chokes or search returns garbage. The guard makes the failure visible at audit time and trivially fixable.
+
+## Validation classes
+
+| Code | Meaning | Auto-fixable? |
+|------|---------|---------------|
+| `MISSING_OPEN` | File doesn't start with `---` | No (needs human) |
+| `MISSING_CLOSE` | No closing `---` before first heading | Yes |
+| `YAML_PARSE` | YAML failed to parse | Sometimes (depends on cause) |
+| `SLUG_MISMATCH` | Frontmatter `slug:` differs from path-derived slug | Yes (removes the field) |
+| `NULL_BYTES` | Binary corruption (`\x00`) | Yes |
+| `NESTED_QUOTES` | `title: "outer "inner" outer"` shape | Yes |
+| `EMPTY_FRONTMATTER` | Open + close present but nothing between | No (needs human) |
+
+## Phases
+
+### Phase 1: Audit
+
+Run a read-only scan across all registered sources (or one with `--source <id>`).
+
+```bash
+gbrain frontmatter audit --json
+```
+
+Reports:
+- Per-source counts grouped by error code
+- Sample of up to 20 affected pages per source
+- Total count
+- Scan timestamp
+
+Output is JSON; agents parse `errors_by_code` and `per_source` to decide next steps.
+
+### Phase 2: Validate one path
+
+Validate a single file or directory (does not require source registration):
+
+```bash
+gbrain frontmatter validate <path> --json
+```
+
+Exit code 0 = clean; 1 = errors found. Use this in CI pipelines or pre-commit hooks.
+
+### Phase 3: Fix
+
+When issues are found:
+
+```bash
+gbrain frontmatter validate <path> --fix
+```
+
+`--fix` writes `<file>.bak` for every modified file before mutating. The backup is the safety contract — works whether the brain is a git repo or a plain directory.
+
+`--dry-run` previews without writing. Use this before applying fixes in batch.
+
+### Phase 4: Pre-commit hook (optional)
+
+For brain repos that ARE git repos, install the pre-commit hook to block malformed pages from being committed in the first place:
+
+```bash
+gbrain frontmatter install-hook [--source <id>]
+```
+
+The hook runs `gbrain frontmatter validate` against staged `.md`/`.mdx` files. Bypass with `git commit --no-verify`.
+
+## Trigger words
+
+When the user says any of these, route here:
+- "validate frontmatter"
+- "check frontmatter"
+- "fix frontmatter"
+- "frontmatter audit"
+- "brain lint"
+
+## Output rules
+
+- Always run `gbrain frontmatter audit --json` first; never assume a brain is clean.
+- Surface counts to the user in plain language; do not dump raw JSON.
+- For `--fix` operations: state how many files will be modified BEFORE running, then confirm.
+- `SLUG_MISMATCH` fixes remove the frontmatter `slug:` field — gbrain derives slug from path. Mention this when the user's title is intentionally renamed.
+- Never auto-fix `MISSING_OPEN` or `EMPTY_FRONTMATTER` without explicit user input — these usually mean a human author started a page and didn't finish.
+
+## Chains with
+
+- `gbrain doctor` — the `frontmatter_integrity` subcheck reports the same counts as `audit`.
+- `skills/maintain/SKILL.md` — broader brain health audit; chain after this skill if other classes of issue are suspected.
+- `skills/lint/SKILL.md` (via `gbrain lint`) — overlapping rules for skill-file lint; the `frontmatter-*` rule names in lint output come from this skill's validation surface.
+
+## Output Format
+
+Audit summary (terse, agent-friendly):
+
+```
+Frontmatter audit — 17 issue(s) across 1 source(s)
+
+[default] /Users/me/brain
+  17 issue(s)
+    MISSING_CLOSE: 8
+    NESTED_QUOTES: 5
+    NULL_BYTES: 4
+  sample:
+    people/jane.md — MISSING_CLOSE
+    companies/acme.md — NESTED_QUOTES
+    (+ 12 more)
+
+Fix with: gbrain frontmatter validate /Users/me/brain --fix
+```
+
+JSON envelope (when `--json` is passed):
+
+```json
+{
+  "ok": false,
+  "total": 17,
+  "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+  "per_source": [
+    {
+      "source_id": "default",
+      "source_path": "/Users/me/brain",
+      "total": 17,
+      "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+      "sample": [{ "path": "people/jane.md", "codes": ["MISSING_CLOSE"] }]
+    }
+  ],
+  "scanned_at": "2026-04-25T22:30:00.000Z"
+}
+```
+
+`gbrain frontmatter validate <path> --json` returns a similar envelope keyed on per-file results instead of per-source.
+
+## Anti-Patterns
+
+**Don't auto-fix `MISSING_OPEN` or `EMPTY_FRONTMATTER` without user input.** These usually mean a human author started a page and didn't finish — silently inserting `---` markers around an unfinished draft is wrong.
+
+**Don't use `--fix` to "make doctor green" without reading the audit first.** SLUG_MISMATCH cases are surfaced for manual review specifically because gbrain derives the slug from path. A mismatch usually means the user renamed a file intentionally; auto-removing the slug field is the right outcome only when you've confirmed the rename was deliberate.
+
+**Don't skip the `.bak` backups.** The `.bak` is the safety contract for non-git brain repos. If `.bak` files accumulate after a fix run, that's a feature, not a bug — the user can review the diffs and delete the backups when satisfied.
+
+**Don't run `audit` on a brain where sources aren't registered.** The CLI returns "no registered sources to audit" gracefully, but the migration emits a `skipped: no_sources` phase result. Don't paper over this with a manual path-walk; the right fix is to register the source via `gbrain sources add`.
+
+**Don't install the pre-commit hook on non-git brain dirs.** The install-hook command skips them automatically with a one-line note. If you see "skipped — not a git repo" and want validation at write time anyway, use the `audit` command on a cron schedule.

skills/frontmatter-guard/routing-eval.jsonl

@@ -0,0 +1,8 @@
+// Routing eval fixtures for skills/frontmatter-guard. Check 5 (W2, v0.17).
+// Layer A (structural) requires intents to contain trigger words from
+// the resolver. Paraphrase the trigger framing, not its meaning.
+{"intent": "please validate frontmatter on the latest batch of brain pages", "expected_skill": "frontmatter-guard"}
+{"intent": "fix frontmatter on these pages", "expected_skill": "frontmatter-guard"}
+{"intent": "I want to run a frontmatter audit across the brain", "expected_skill": "frontmatter-guard"}
+// Negative case: something that sounds similar but should NOT route here.
+{"intent": "what's for breakfast", "expected_skill": null, "ambiguous_with": []}

skills/maintain/SKILL.md

@@ -8,10 +8,22 @@ description: |
 triggers:
   - "brain health"
   - "check backlinks"
-  - "citation audit"
   - "maintenance"
   - "orphan pages"
   - "stale pages"
+  - "extract links"
+  - "build link graph"
+  - "populate timeline"
+  - "populate links"
+  - "backfill graph"
+  - "extract timeline entries"
+  - "run dream"
+  - "process today's session"
+  - "process yesterday's transcripts"
+  - "synthesize my conversations"
+  - "what patterns did you see"
+  - "did the dream cycle run"
+  - "consolidate yesterday's conversations"
 tools:
   - get_health
   - get_page
@@ -72,6 +84,81 @@ If timeline_entry_count is 0, extract structured timeline from markdown:
 ```bash
 gbrain extract timeline --dir ~/brain
 ```
+
+### Dream cycle (v0.23): synthesize + patterns
+
+`gbrain dream` runs the full 8-phase maintenance cycle:
+
+```
+lint -> backlinks -> sync -> synthesize -> extract -> patterns -> embed -> orphans
+```
+
+The two new phases consolidate yesterday's conversations into long-term memory:
+
+**Synthesize phase:** reads transcripts from `dream.synthesize.session_corpus_dir`,
+runs a cheap Haiku verdict (cached in `dream_verdicts`) to filter routine
+ops sessions, then fans out one Sonnet subagent per worth-processing
+transcript. Each subagent writes reflections (`wiki/personal/reflections/...`),
+originals (`wiki/originals/ideas/...`), and people timeline entries. The
+orchestrator collects the slugs from `subagent_tool_executions` (NOT
+`pages.updated_at` — that would pick up unrelated writes) and reverse-renders
+each new page from DB → markdown on disk.
+
+**Patterns phase:** runs after `extract` (so the graph state is fresh).
+Reads recent reflections within `dream.patterns.lookback_days` (default 30),
+runs a single Sonnet pass to surface recurring themes, and writes pattern
+pages to `wiki/personal/patterns/<theme>` when ≥`dream.patterns.min_evidence`
+(default 3) reflections support a pattern.
+
+**Quality bar (Iron Law for synthesis):**
+1. Quote the user verbatim. Do not paraphrase memorable phrasings.
+2. Cross-reference compulsively: every new page MUST have at least one wikilink.
+3. Slug discipline: lowercase alphanumeric and hyphens only. NO underscores, NO file extensions.
+4. Edited transcripts produce NEW slugs (content-hash suffix changes) — never silently overwrite.
+
+**Trust boundary (`allowed_slug_prefixes`):** the synthesis subagent runs with an
+explicit allow-list of write paths sourced from `_brain-filing-rules.json`'s
+`dream_synthesize_paths.globs`. Even on prompt-injection success, the subagent
+cannot write outside that list. Trust comes from PROTECTED_JOB_NAMES — MCP
+cannot submit subagent jobs at all. Editing the JSON is the only way to add
+a new directory the synthesizer can write to.
+
+**Idempotency + privacy:** transcripts are keyed by `(file_path, content_hash)`,
+so re-running on the same content is a no-op. `dream.synthesize.exclude_patterns`
+(default `["medical", "therapy"]`) filters out transcripts before any LLM call.
+Each entry is auto-wrapped as a word-boundary regex (e.g. `medical` matches
+"medical advice" but NOT "comedical"). Power users may pass full regex.
+
+**Cooldown:** the cycle's spend cap. `dream.synthesize.cooldown_hours` (default
+12) means at most ~2 synthesize runs per day under autopilot. The completion
+timestamp is stored in `dream.synthesize.last_completion_ts` and is written
+ONLY on successful runs (not on skipped/failed). Explicit `--input` /
+`--date` / `--from` / `--to` invocations bypass cooldown.
+
+**`--dry-run` semantics:** runs the cheap Haiku significance filter (caches
+verdicts) but skips the Sonnet synthesis pass. NOT zero LLM calls.
+
+**Configure synthesize on a fresh brain:**
+```bash
+gbrain config set dream.synthesize.session_corpus_dir /path/to/transcripts
+gbrain config set dream.synthesize.enabled true
+gbrain dream --phase synthesize --dry-run --json   # preview
+gbrain dream                                       # full 8-phase cycle
+```
+
+**Invocation patterns:**
+```bash
+gbrain dream                                          # full cycle
+gbrain dream --phase synthesize                       # just synthesize
+gbrain dream --phase patterns                         # just patterns
+gbrain dream --input ~/transcripts/2026-04-25.txt     # ad-hoc one transcript
+gbrain dream --from 2026-04-01 --to 2026-04-25        # backfill range
+gbrain dream --json                                   # CycleReport JSON
+```
+
+**Auto-commit deferred to v1.1:** v1 writes files to `brain_dir` but does NOT
+`git add` / `commit` / `push`. Either commit yourself or let `gbrain autopilot`
+handle it.
 Parses `- **YYYY-MM-DD** | Source — Summary` and `### YYYY-MM-DD — Title` formats.
 Note: extracted entries improve structured queries (`gbrain timeline`), not vector search.
 

skills/manifest.json

@@ -44,6 +44,11 @@
       "path": "publish/SKILL.md",
       "description": "Share brain pages as beautiful password-protected HTML (code + skill pair, zero LLM calls)"
     },
+    {
+      "name": "frontmatter-guard",
+      "path": "frontmatter-guard/SKILL.md",
+      "description": "Validate and auto-repair YAML frontmatter on brain pages; gates against malformed YAML, missing closing ---, nested quotes, slug mismatches, null bytes"
+    },
     {
       "name": "signal-detector",
       "path": "signal-detector/SKILL.md",
@@ -132,7 +137,7 @@
     {
       "name": "minion-orchestrator",
       "path": "minion-orchestrator/SKILL.md",
-      "description": "Manage background agents via Minions job queue. Submit, monitor, steer, pause/resume, replay. Replaces sessions_spawn for durable observable agents."
+      "description": "Unified Minions skill for deterministic shell jobs and LLM subagent orchestration. Submit, monitor, steer, pause/resume, replay. Replaces the older gbrain-jobs routing intent and sessions_spawn for durable observable background work."
     },
     {
       "name": "skillify",

skills/migrations/v0.19.0.md

@@ -0,0 +1,71 @@
+---
+version: 0.19.0
+feature_pitch:
+  headline: "Your code is now first-class in the brain."
+  one_liner: "gbrain code-refs BrainEngine --json returns every usage site in <100ms."
+  user_action_required: true
+---
+
+# v0.19.0 — Code Indexing
+
+This release makes code a first-class citizen in the brain. Tree-sitter parses 29 languages into semantic chunks. `gbrain code-def` and `gbrain code-refs` let agents find symbol definitions and references without grep. Incremental chunking drops daily autopilot embedding cost by ~95%. The chunker is a strict superset of Chonkie's CodeChunker plus a structured header Chonkie lacks.
+
+## Schema migrations applied automatically
+
+- **v25 — `pages.page_kind`** — distinguishes markdown vs code pages at the DB level. Existing rows backfill to `'markdown'`. Postgres uses `ADD CONSTRAINT ... NOT VALID` + `VALIDATE CONSTRAINT` so large tables don't block.
+- **v26 — `content_chunks` code metadata** — adds `language`, `symbol_name`, `symbol_type`, `start_line`, `end_line`. All nullable. Partial indexes on `symbol_name` and `language` for fast symbol lookup.
+
+These run as part of `gbrain upgrade` → `gbrain apply-migrations`. No manual DDL needed.
+
+## What the agent should do after upgrading
+
+1. **Confirm migrations landed:**
+   ```bash
+   gbrain doctor
+   ```
+   Look for `schema_version: 26`. If lower, run `gbrain apply-migrations --yes`.
+
+2. **Register a code source** if the user wants their code indexed:
+   ```bash
+   gbrain sources add <id> --path <path-to-repo>
+   ```
+   Pick a short `<id>` (e.g. `wiki`, `gbrain`, `yc-media`). Shorter is better — it's used in citation keys.
+
+3. **Sync the code source:**
+   ```bash
+   gbrain sync --source <id>
+   ```
+   First sync may run tens of minutes depending on repo size. Each TypeScript function becomes a chunk with a structured header like `[TypeScript] src/core/sync.ts:380-415 function performFullSync`.
+
+4. **Verify code-def and code-refs work:**
+   ```bash
+   gbrain code-def BrainEngine       # prints the file + line of the definition
+   gbrain code-refs BrainEngine --json  # JSON array of every usage site
+   ```
+   If both return non-empty arrays, code indexing is working end-to-end.
+
+5. **Observe incremental chunking.** Edit one function in a 20-function file, re-run `sync --source <id>`. Embedding cost should be ~5% of the first sync because unchanged chunks reuse their existing embeddings.
+
+## Migration from your OpenClaw's `repos` (if you used it)
+
+v0.19.0 deletes `~/.gbrain/config.json`'s `repos` array in favor of the `sources` table. The CLI surface is preserved as a deprecated alias: `gbrain repos add` still works, but routes into `runSources` with a one-line deprecation notice on stderr. Existing scripts keep working; prefer `gbrain sources` going forward.
+
+If you had repos configured in `~/.gbrain/config.json`, re-register them:
+```bash
+gbrain sources add <name> --path <path>
+```
+Per-repo sync bookmarks live in the `sources` table now (not config.json).
+
+## Flag in `pending-host-work.jsonl`
+
+Per the v0.11.0 convention, the migration orchestrator writes an entry to `~/.gbrain/migrations/pending-host-work.jsonl` flagging the new CLI surfaces so headless agents can walk the TODOs:
+
+```json
+{"version": "0.19.0", "action": "register_code_source", "status": "pending"}
+```
+
+Agents that handle pending-host-work should offer the user a `gbrain sources add ...` prompt.
+
+## When NOT to run the migration
+
+Never. v0.19.0 is fully backward-compatible. Existing markdown-only brains see zero behavior change until the user adds a code source.

skills/migrations/v0.21.0.md

@@ -0,0 +1,64 @@
+---
+version: 0.21.0
+feature_pitch:
+  headline: "Code Cathedral II — chunk-grain FTS, qualified symbols, structural edges."
+  one_liner: "Natural-language queries now rank docstring matches first. CHUNKER_VERSION 3→4 rolls the new chunker over existing code pages automatically on next sync."
+  user_action_required: true
+---
+
+# v0.21.0 — Code Cathedral II
+
+This release is the biggest code-search upgrade in gbrain history. Chunk-grain FTS with doc_comment Weight A ranks natural-language queries against docstrings above prose. CHUNKER_VERSION 3 → 4 folds into content_hash so every existing code page re-chunks. File classifier widened from 9 to 35 extensions. Markdown fence extraction, `sync --all` cost preview, and `reconcile-links` batch command ship alongside the chunker upgrade.
+
+## Schema migrations applied automatically
+
+- **v27 — cathedral_ii_foundation** — adds `code_edges_chunk`, `code_edges_symbol`, `sources.chunker_version`, and new `content_chunks` columns (`parent_symbol_path`, `doc_comment`, `symbol_name_qualified`, `search_vector`). Includes the chunk-grain FTS trigger that builds from `setweight(to_tsvector('english', doc_comment), 'A') || setweight(to_tsvector('english', chunk_text), 'B') || setweight(to_tsvector('english', symbol_name_qualified), 'A')`.
+- **v28 — cathedral_ii_chunk_fts_backfill** — populates `search_vector` on every existing chunk so day-1 queries already rank correctly.
+
+These run as part of `gbrain upgrade` → `gbrain apply-migrations`. No manual DDL needed.
+
+## What the agent should do after upgrading
+
+1. **Confirm migrations landed:**
+   ```bash
+   gbrain doctor
+   ```
+   Look for `schema_version: 28`. If lower, run `gbrain apply-migrations --yes`.
+
+2. **Pick a backfill path.** The `CHUNKER_VERSION` bump + `sources.chunker_version` gate means existing code pages must re-chunk for the new shape to take effect. Two paths:
+
+   **Automatic (recommended):** next `gbrain sync --source <id>` detects the version mismatch and forces a full re-walk regardless of git HEAD equality. No cost preview, no user interaction. The Layer 12 SP-1 fix from codex's second-pass review.
+
+   **Immediate:** preview cost, then reindex every code page now.
+   ```bash
+   gbrain reindex-code --dry-run       # preview token count + $USD cost
+   gbrain reindex-code --yes           # reindex all code pages
+   gbrain reindex-code --source <id> --yes  # scope to one source
+   ```
+   On non-TTY (automation / cron) `reindex-code` without `--yes` emits a `ConfirmationRequired` envelope and exits 2 — same shape as `sync --all`. The envelope matches v0.19.0's `StructuredAgentError`.
+
+3. **Verify chunk-grain FTS works.** A query that mentions a concept in a docstring (not just the function body) should rank higher than a page that mentions it only in prose:
+   ```bash
+   gbrain query "whatever your docstring says"
+   ```
+   Expected: top hit is the chunk whose `doc_comment` matches.
+
+4. **(Optional) Reconcile doc↔impl links.** v0.19.0 Layer 6 forward-extracted code refs from markdown pages when they imported, but edges dropped if the code page hadn't imported yet. v0.21.0's `reconcile-links` batch-scans every markdown page and idempotently reinserts missing edges:
+   ```bash
+   gbrain reconcile-links              # full run
+   gbrain reconcile-links --dry-run    # preview only
+   gbrain reconcile-links --json       # machine output
+   ```
+   Respects `auto_link=false` config (prints warn + exits 0 when disabled).
+
+## Widened file classifier — more languages sync now
+
+Previous classifier recognized 9 extensions as code. v0.21.0 widens to 35 (Rust, Ruby, Java, C#, C/C++, Swift, Kotlin, Scala, PHP, Elixir, Elm, OCaml, Dart, Zig, Solidity, Lua, shell, etc.). If your repo contains source files in languages beyond TS/JS/Py/Go, they'll flow through the code chunker on next sync. No action needed — `detectCodeLanguage` handles dispatch.
+
+## Flag in `pending-host-work.jsonl`
+
+The migration orchestrator emits a backfill-prompt phase that prints the two backfill choices directly. No `pending-host-work.jsonl` entry is written — the choice is user-driven and ephemeral (either reindex now or wait for next sync).
+
+## When NOT to run the migration
+
+Never skip it. v0.21.0 is fully backward-compatible at the API level (page-grain FTS shape preserved externally; chunk-grain is internal only). Skipping the migration means agents miss doc_comment Weight A ranking and the chunker_version gate never fires — existing code pages silently stay on CHUNKER_VERSION 3 forever until you sync with `--full`.

skills/migrations/v0.22.14.md

@@ -0,0 +1,210 @@
+---
+feature_pitch:
+  headline: Bare workers now self-monitor and fail-stop into your PM's restart loop
+  body: |
+    Bare `gbrain jobs work` now ships with the same health protection the
+    supervisor already had: DB liveness probes (with per-probe timeout so a
+    hung connection can't wedge the monitor), stall detection filtered by
+    registered handler names, and an RSS watchdog default of 2048 MB.
+
+    When the worker detects it's wedged (stuck pgbouncer connection, hung
+    event loop, stalled job claim), it emits `'unhealthy'` and the CLI calls
+    `process.exit(1)`. This is **fail-stop**: it requires an external process
+    manager (systemd, Docker `restart: always`, launchd `KeepAlive`, cron
+    watchdog) to bring the worker back. Without one, the process exits and
+    stays dead — that's a regression from pre-v0.22.14 self-healing.
+
+    Pre-v0.22.14 behavior: bare workers had ZERO health monitoring. A wedged
+    worker stayed alive doing nothing while jobs piled up in `waiting` and
+    your PM's `pgrep` check happily reported green.
+
+    If you're using `gbrain jobs supervisor`, you're already protected — the
+    supervisor handles spawn-on-crash itself. The fail-stop concern only
+    applies to direct `gbrain jobs work` invocations.
+---
+
+# v0.22.14 — Bare-worker self-health-monitoring
+
+## ⚠️ Pre-flight: confirm you have a process supervisor
+
+If you run `gbrain jobs work` directly (NOT under `gbrain jobs supervisor`),
+verify your process manager is configured to restart the worker on exit
+BEFORE upgrading:
+
+| Manager | What to check |
+|---|---|
+| systemd | `Restart=always` (or `Restart=on-failure`) in the `.service` unit |
+| Docker | `restart: always` / `restart: unless-stopped` in compose, OR `--restart` flag |
+| launchd (macOS) | `<key>KeepAlive</key><true/>` in the plist |
+| cron watchdog | Cron entry that re-spawns when `pgrep -f "gbrain jobs work"` is empty |
+| supervisord | `autorestart=true` |
+
+**If your bare worker has no restart loop, the v0.22.14 fail-stop behavior
+will leave you with a dead worker after the first DB blip.** Either add a
+restart policy OR switch to `gbrain jobs supervisor` (which spawns its own
+child + restarts on crash internally).
+
+## What ships
+
+- DB liveness probes inside `gbrain jobs work` (60s interval, 3 strikes → exit)
+- Stall detection (5min warn / 10min exit when waiting jobs accumulate but
+  in-flight is empty)
+- `--max-rss` defaults to 2048 MB for bare workers (matches supervisor default;
+  was 0 = disabled)
+- New `MinionWorkerOpts.{healthCheckInterval, stallWarnAfterMs,
+  stallExitAfterMs, dbFailExitAfter, dbProbeTimeoutMs}` for tuning (5 fields)
+- `MinionWorker` now extends `EventEmitter`; emits `'unhealthy'` event with
+  a structured reason payload. **No-listener fallback**: if the caller does
+  not subscribe to `'unhealthy'`, the worker calls `process.exit(1)` itself
+  to preserve the pre-refactor fail-stop behavior. The CLI subscribes; direct
+  API consumers without a listener inherit the fail-stop default. Inline
+  paths (`jobs submit --follow`, `jobs smoke`) explicitly pass
+  `healthCheckInterval: 0` to disable the timer entirely so the fallback
+  cannot trip on a one-shot run.
+- `GBRAIN_SUPERVISED=1` env var (set by supervisor on its child) causes the
+  child worker to skip its own health timer (no double-monitoring)
+- Constructor validation: throws if `stallExitAfterMs <= stallWarnAfterMs`
+  (the contract requires strict greater-than)
+
+## ⚠️ Breaking change you may need to act on
+
+**`gbrain jobs work` now defaults `--max-rss 2048` (MB).** Pre-v0.22.14, bare
+workers had no RSS limit. If you ran bare workers with intentionally large
+embed/import working sets, your worker may now get killed by the watchdog after
+upgrade.
+
+**You need to act if any of the following is true:**
+
+- You run `gbrain jobs work` directly under a process manager (systemd, Docker,
+  cron, supervisord, your own bash wrapper)
+- Your worker handles large embed batches, multi-GB import jobs, or
+  memory-intensive subagent tasks that legitimately exceed 2 GB RSS
+- You rely on bare-worker resident memory exceeding 2 GB
+
+**You do NOT need to act if:**
+
+- You run `gbrain jobs supervisor` (the supervisor already defaulted to
+  `--max-rss 2048` and has reconnect-then-fail logic on top)
+- Your typical worker stays well under 2 GB RSS
+
+## What the agent should do post-upgrade
+
+### 1. Run the orchestrator (mechanical migration)
+
+```bash
+gbrain apply-migrations --yes
+```
+
+This is a no-op for v0.22.14 — there's no schema migration. The mechanical work
+is in the binary; the user-side decision is the breaking-change handling below.
+
+### 2. Detect bare-worker deployments
+
+If the user runs OpenClaw, Hermes, or any agent fork that uses `gbrain jobs
+work` directly (NOT under `gbrain jobs supervisor`), they need to know. Check:
+
+```bash
+# Look for bare worker invocations in cron, systemd, Docker, launchctl, etc.
+grep -r "gbrain jobs work" ~/.config/systemd/ /etc/systemd/ 2>/dev/null | head
+crontab -l 2>/dev/null | grep "gbrain jobs work" | head
+launchctl list 2>/dev/null | grep gbrain | head
+ps -ef | grep "gbrain jobs work" | grep -v grep | grep -v supervisor
+```
+
+If you find bare-worker invocations, surface them to the user.
+
+### 3. Ask about RSS profile
+
+Use AskUserQuestion to confirm whether the user's bare workers need >2 GB RSS:
+
+> "v0.22.14 changes `gbrain jobs work` to default `--max-rss 2048` (MB).
+> Pre-v0.22.14 bare workers had no limit. If your worker handles large embed
+> batches or multi-GB imports, the watchdog may now kill it. Do you want
+> to keep the new 2 GB default, raise the limit, or opt out entirely?"
+
+Options:
+- **A) Keep 2 GB default (recommended for most)** — protects against memory
+  leaks; restarts on overflow; matches supervisor behavior.
+- **B) Raise to N GB (specify N)** — pass `--max-rss <N*1024>` to the worker
+  invocation.
+- **C) Opt out** — pass `--max-rss 0`.
+
+### 4. Apply the user's choice
+
+For each bare-worker invocation, edit the unit/cron/launchctl/script to add
+the chosen `--max-rss` flag.
+
+**systemd (~/.config/systemd/user/gbrain-worker.service):**
+
+```ini
+ExecStart=/usr/local/bin/gbrain jobs work --queue default --concurrency 3 --max-rss 4096
+# Or to opt out: --max-rss 0
+```
+
+Then `systemctl --user daemon-reload && systemctl --user restart gbrain-worker`.
+
+**cron (`crontab -e`):**
+
+```cron
+@reboot /usr/local/bin/gbrain jobs work --queue default --concurrency 3 --max-rss 4096
+```
+
+**Docker compose:**
+
+```yaml
+command: ["gbrain", "jobs", "work", "--queue", "default", "--concurrency", "3", "--max-rss", "4096"]
+```
+
+**launchctl (~/Library/LaunchAgents/com.user.gbrain-worker.plist):**
+
+```xml
+<key>ProgramArguments</key>
+<array>
+  <string>/usr/local/bin/gbrain</string>
+  <string>jobs</string>
+  <string>work</string>
+  <string>--max-rss</string>
+  <string>4096</string>
+</array>
+```
+
+Then `launchctl unload ... && launchctl load ...`.
+
+### 5. (Optional) Tune health-check thresholds
+
+The new opts default to sensible values (60s probe interval, 5min warn / 10min
+exit, 3 DB failures). If you have specific SLAs, you can pass `--health-interval
+<ms>` to adjust the probe cadence. Stall thresholds are not yet CLI-exposed
+(only the API; CLI flags coming in a follow-up).
+
+To disable self-monitoring entirely (e.g. you have your own external health
+checker):
+
+```bash
+gbrain jobs work --health-interval 0 --max-rss 0
+```
+
+### 6. Verify
+
+```bash
+gbrain jobs stats              # queue should be flowing normally
+gbrain doctor --json | jq '.'  # no critical warnings
+ps -o rss= -p $(pgrep -f "gbrain jobs work") | awk '{print $1/1024 " MB"}'
+```
+
+Worker startup log line should now show health-check status:
+
+```
+Minion worker started (queue: default, concurrency: 3, watchdog: 2048MB, health-check: 60s)
+```
+
+If running under supervisor, you'll see the watchdog but NOT the `health-check:
+60s` segment (because `GBRAIN_SUPERVISED=1` skips the child's self-monitor).
+
+### 7. If anything fails
+
+Open an issue at https://github.com/garrytan/gbrain/issues with:
+- Output of `gbrain doctor`
+- Contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
+- Your bare-worker invocation (systemd unit / cron line / Dockerfile snippet)
+- Which step broke

skills/migrations/v0.22.4.md

@@ -0,0 +1,113 @@
+# v0.22.4 — Frontmatter Guard
+
+## What ships
+
+- `gbrain frontmatter` CLI (validate / audit / install-hook)
+- `frontmatter_integrity` subcheck under `gbrain doctor`
+- New `frontmatter-guard` skill (`skills/frontmatter-guard/SKILL.md`)
+- Pre-commit hook helper for git-backed brain repos
+- Audit-only migration that scans every registered source, writes
+  `~/.gbrain/migrations/v0.22.4-audit.json`, and queues per-source TODO
+  entries to `~/.gbrain/migrations/pending-host-work.jsonl`
+- 0 warnings on `gbrain check-resolvable` (down from 7 on master)
+
+## What the agent should do post-upgrade
+
+The orchestrator handles the mechanical side. Your job is to surface the audit
+to the user and apply fixes with their consent.
+
+### 1. Run the orchestrator
+
+```bash
+gbrain apply-migrations --yes
+```
+
+This runs three idempotent phases:
+
+- `schema` (no-op in v0.22.4)
+- `audit` — `scanBrainSources()` over every registered source; writes
+  `~/.gbrain/migrations/v0.22.4-audit.json`
+- `emit-todo` — appends one entry per source-with-issues to
+  `~/.gbrain/migrations/pending-host-work.jsonl`. Each entry contains the
+  exact `gbrain frontmatter validate <source-path> --fix` command.
+
+The migration **never mutates brain pages**. Auto-fixes only run when the user
+explicitly invokes the validate-with-fix command below.
+
+### 2. Read the audit report
+
+```bash
+cat ~/.gbrain/migrations/v0.22.4-audit.json
+```
+
+The shape:
+
+```json
+{
+  "ok": false,
+  "total": 17,
+  "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+  "per_source": [
+    {
+      "source_id": "default",
+      "source_path": "/Users/me/brain",
+      "total": 17,
+      "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+      "sample": [
+        { "path": "people/jane.md", "codes": ["MISSING_CLOSE"] }
+      ]
+    }
+  ],
+  "scanned_at": "2026-04-25T22:30:00.000Z"
+}
+```
+
+### 3. Surface the report to the user
+
+State the per-source counts in plain language. Example:
+
+> "v0.22.4 ships frontmatter-guard. I ran an audit and found 17 issues across
+> 1 source (default: 8 MISSING_CLOSE, 5 NESTED_QUOTES, 4 NULL_BYTES). The
+> mechanical errors are auto-fixable; SLUG_MISMATCH cases (if any) need your
+> review. Want me to fix the auto-fixable ones now?"
+
+### 4. Run the fix (with consent)
+
+Per source with issues, the queued command is:
+
+```bash
+gbrain frontmatter validate <source_path> --fix
+```
+
+`--fix` writes a `.bak` backup for every modified file. SLUG_MISMATCH errors
+are surfaced for manual review (not auto-fixed) — gbrain derives slugs from
+path, so a mismatched slug usually means the user renamed the file
+intentionally or the slug field is stale.
+
+### 5. (Optional) Install the pre-commit hook
+
+For git-backed sources only:
+
+```bash
+gbrain frontmatter install-hook [--source <id>]
+```
+
+This blocks future malformed-frontmatter commits at the git layer. Bypass with
+`git commit --no-verify`. Skip this step for non-git brains.
+
+### 6. Verify
+
+```bash
+gbrain doctor --json | jq '.checks[] | select(.name == "frontmatter_integrity")'
+gbrain frontmatter audit --json | jq '.total'
+```
+
+Both should report 0 issues after fixes are applied.
+
+### 7. If anything fails
+
+Open an issue at https://github.com/garrytan/gbrain/issues with:
+- output of `gbrain doctor`
+- contents of `~/.gbrain/migrations/v0.22.4-audit.json`
+- contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
+- which step broke

skills/migrations/v0.23.0.md

@@ -0,0 +1,171 @@
+---
+version: 0.23.0
+feature_pitch:
+  headline: "gbrain dream now actually dreams: conversation transcripts → reflections, originals, and 25-year patterns."
+  description: |
+    The maintenance cycle gains two new phases: `synthesize` and `patterns`.
+    The 8-phase order is now: lint → backlinks → sync → synthesize →
+    extract → patterns → embed → orphans.
+
+    Synthesize reads conversation transcripts (e.g., OpenClaw session corpus,
+    meeting transcripts) and writes brain-native pages: reflections to
+    `wiki/personal/reflections/...`, originals to `wiki/originals/ideas/...`,
+    timeline entries on existing people pages.
+
+    Patterns runs after extract (so the graph is fresh) and surfaces
+    recurring themes across reflections — when ≥3 reflections mention the
+    same motif, a pattern page is written to `wiki/personal/patterns/...`
+    citing every reflection that constitutes its evidence.
+
+    Hard guarantees: subagent writes are bounded to an explicit allow-list
+    (sourced from `_brain-filing-rules.json`). Edited transcripts produce
+    new slugs (content-hash suffix) — never silently overwrite. A 12-hour
+    cooldown bounds spend at ~$1-2/day under autopilot.
+  recipe: skills/maintain/SKILL.md
+  tiers: null
+---
+
+# v0.23.0 Migration: Dream cycle synthesize + patterns phases
+
+**Audience: host agents reading this after `gbrain apply-migrations` has
+run. The synthesize phase ships disabled by default — set
+`dream.synthesize.session_corpus_dir` to opt in.**
+
+## Mechanical migration: automatic, no action required
+
+`gbrain upgrade` chains to `gbrain apply-migrations --yes`, which runs:
+
+- **migration v25** — creates the `dream_verdicts` table:
+  `(file_path TEXT, content_hash TEXT, worth_processing BOOL, reasons JSONB,
+  judged_at TIMESTAMPTZ, PRIMARY KEY(file_path, content_hash))`. Cache
+  for the cheap Haiku verdict so backfill re-runs skip already-judged
+  transcripts. RLS-enabled when running as a BYPASSRLS role.
+
+The migration is idempotent. Safe to re-run.
+
+## What changes for existing brains
+
+`gbrain dream` (and `gbrain autopilot`) now run an 8-phase cycle:
+
+```
+lint → backlinks → sync → synthesize → extract → patterns → embed → orphans
+```
+
+If `dream.synthesize.enabled` is false (the default, post-migration), the
+synthesize and patterns phases emit `status: "skipped", reason: "not_configured"`
+and the cycle continues to the next phase. **Existing autopilot users see
+zero behavior change** until they configure synthesize.
+
+## To enable synthesize on your brain
+
+Three steps. Take them when ready — there is no rush.
+
+```bash
+# 1. Point at the directory where your conversation transcripts live.
+#    OpenClaw stores session transcripts at memory/.dreams/session-corpus/<YYYY-MM-DD>.txt
+#    by default. If you have a different layout, point at that.
+gbrain config set dream.synthesize.session_corpus_dir /path/to/transcripts
+
+# 2. Enable the phase.
+gbrain config set dream.synthesize.enabled true
+
+# 3. Preview without spending real LLM tokens (runs cheap Haiku verdict only).
+gbrain dream --phase synthesize --dry-run --json
+```
+
+## Tunables (sensible defaults; override only if needed)
+
+```bash
+# Skip transcripts shorter than this many characters (default 2000).
+gbrain config set dream.synthesize.min_chars 2000
+
+# Word-boundary regex patterns to skip. Default ["medical","therapy"].
+# Each entry auto-wraps as \b<entry>\b — "medical" matches "medical advice"
+# but NOT "comedical". Pass full regex (e.g. ^therapy:) for advanced patterns.
+gbrain config set dream.synthesize.exclude_patterns '["medical","therapy"]'
+
+# Synthesize model (default: claude-sonnet-4-6).
+gbrain config set dream.synthesize.model claude-sonnet-4-6
+
+# Hours between synthesize runs (the v1 spend cap; default 12 → ~$1-2/day).
+gbrain config set dream.synthesize.cooldown_hours 12
+
+# Patterns lookback window in days (default 30).
+gbrain config set dream.patterns.lookback_days 30
+
+# Minimum distinct reflections needed to name a pattern (default 3).
+gbrain config set dream.patterns.min_evidence 3
+```
+
+## Allow-list source of truth
+
+The synthesize subagent's allowed write paths live in
+`skills/_brain-filing-rules.json` under `dream_synthesize_paths.globs`:
+
+```json
+{
+  "dream_synthesize_paths": {
+    "globs": [
+      "wiki/personal/reflections/*",
+      "wiki/originals/*",
+      "wiki/personal/patterns/*",
+      "wiki/people/*",
+      "dream-cycle-summaries/*"
+    ]
+  }
+}
+```
+
+Editing this list is the ONLY way to add a new directory the synthesizer
+can write to. The subagent's `put_page` calls are gated server-side; even
+on prompt-injection success the write is bounded to these prefixes.
+
+## Slug discipline
+
+Reflections: `wiki/personal/reflections/YYYY-MM-DD-<topic>-<hash[:6]>`
+Originals:   `wiki/originals/ideas/YYYY-MM-DD-<idea>-<hash[:6]>`
+Patterns:    `wiki/personal/patterns/<theme>`
+Summary:     `dream-cycle-summaries/YYYY-MM-DD`
+
+The 6-char content-hash suffix on reflections / originals means an edited
+transcript produces a NEW slug — the original reflection is preserved
+alongside the new one. No silent overwrite.
+
+Lowercase alphanumeric and hyphens only. NO underscores, NO file extensions.
+
+## Provenance
+
+Every put_page call from the synthesize subagent shows up in
+`subagent_tool_executions` with full input. The orchestrator collects
+slugs by querying that table — NOT `pages.updated_at` — so the cycle's
+write list cannot accidentally include manual edits or sync output.
+
+## What's deferred to v1.1
+
+- **Auto git commit + push.** v1 writes markdown files to `brain_dir`
+  but does NOT `git add` / `commit` / `push`. Either commit yourself
+  or let `gbrain autopilot` handle it. v1.1 will add explicit
+  --commit / --push flags with handling for dirty worktree, staged
+  changes, auth failure, and non-fast-forward push.
+- **Daily token budget cap.** Cooldown alone is the spend bound at v1
+  scale. If real-world telemetry surfaces a problem, v1.1 adds an
+  explicit `daily_token_budget` config.
+- **Cross-modal pattern review.** Patterns currently runs against
+  reflections only. Future revision could roll up across reflections,
+  meetings, and timeline entries together.
+
+## Verify after upgrade
+
+```bash
+# Schema migration applied?
+gbrain doctor
+
+# Phase ordering correct?
+gbrain dream --help    # shows the 8-phase pipeline
+
+# Dry-run against a single transcript (cheap Haiku call only):
+gbrain dream --phase synthesize --input /tmp/some-transcript.txt --dry-run --json
+```
+
+If any step fails, file an issue with `gbrain doctor` output and the
+contents of `~/.gbrain/upgrade-errors.jsonl` if it exists.

skills/minion-orchestrator/SKILL.md

@@ -2,11 +2,18 @@
 name: minion-orchestrator
 version: 1.0.0
 description: |
-  Manage background agents via Minions job queue. Use when: spawning subagents,
-  checking agent progress, steering running agents, pausing/resuming work,
-  parallel task execution, fan-out research. Replaces sessions_spawn for
-  durable, observable, steerable agents.
+  Unified Minions skill for both deterministic shell jobs and LLM subagent
+  orchestration. Replaces the older `gbrain-jobs` routing intent. Use when:
+  submitting gbrain jobs, shell/background tasks, spawning subagents,
+  checking progress, steering running work, pausing/resuming, parallel
+  fan-out. One durable, observable, steerable queue interface.
 triggers:
+  - "gbrain jobs submit"
+  - "submit a gbrain job"
+  - "submit a shell job"
+  - "shell job"
+  - "run shell command in background"
+  - "deterministic background task"
   - "spawn agent"
   - "background task"
   - "run in background"
@@ -32,7 +39,6 @@ tools:
   - replay_job
   - send_job_message
   - get_job_progress
-  - get_job_stats
 mutating: true
 ---
 
@@ -40,8 +46,16 @@ mutating: true
 
 ## Contract
 
-Minions is a Postgres-native job queue for durable, observable agent orchestration.
-Every background agent task goes through Minions. No in-memory subagent spawning.
+Minions is a Postgres-native job queue for durable, observable background work.
+This single skill handles two lanes:
+- Deterministic shell jobs (`gbrain jobs submit shell ...`)
+- LLM subagent jobs (`gbrain agent run ...`)
+
+When to route to Minions: durable, observable work that must survive restarts,
+fan out across many parallel tasks, or persist across sessions. Routing policy
+is defined in `skills/conventions/subagent-routing.md` — the project default is
+`pain_triggered` (native subagents first, Minions after specific pain signals
+fire); Mode A (all-through-Minions) is opt-in.
 
 Guarantees:
 - Jobs survive gateway restart (Postgres-backed)
@@ -50,51 +64,155 @@ Guarantees:
 - Jobs can be paused, resumed, or cancelled at any time
 - Parent-child DAGs with configurable failure policies
 
-## When to Use Minions vs Inline Work
+## Route the Request: Shell Job vs Subagent
 
 | Condition | Action |
 |---|---|
-| Single tool call, < 30s | Do it inline |
-| Multi-step, any duration | Submit as Minion job |
-| Parallel work (2+ streams) | Submit N Minion jobs with shared parent |
-| Needs to survive restart | Submit as Minion job |
-| User wants progress updates | Submit as Minion job with progress tracking |
-| Research / bulk operation | Submit as Minion job, always |
-| File imports, bulk embeds | Submit as Minion job |
+| User asks for deterministic command/script run | Shell job (CLI: `gbrain jobs submit shell ...`) |
+| User asks to "run in minions" + explicit command/argv | Shell job (CLI, `--params` with `cmd` or `argv`) |
+| User asks for research/reasoning/iterative agent | Subagent job (CLI: `gbrain agent run`) |
+| User asks to steer/pause/resume an agent | Subagent job lifecycle tools (MCP-callable) |
+| Single simple operation under ~30s | Consider inline execution first |
+| Needs restart durability/observability | Submit as Minion job |
+| Parallel work (2+ streams) | `gbrain agent run --fanout-manifest` or parent + child subagents |
 
-**Rule of thumb:** If it takes more than 3 tool calls, use a Minion.
+If intent is ambiguous, ask one clarification:
+"Do you want a deterministic shell command job, or an LLM agent job?"
+
+## Shell Jobs (Deterministic Scripts)
+
+Use for reproducible command execution, ETL steps, cron work, and scriptable
+tasks where no LLM reasoning loop is needed.
+
+### Preconditions (read before submitting your first shell job)
+
+- **`GBRAIN_ALLOW_SHELL_JOBS=1` must be set on the worker environment.**
+  Without it, the shell handler refuses to register and submissions sit in
+  `waiting` silently. Gate lives in `src/core/minions/handlers/shell.ts`.
+- **Security:** flipping `GBRAIN_ALLOW_SHELL_JOBS=1` authorizes arbitrary
+  command execution on the worker. On a shared queue, this is a remote code
+  execution surface. Treat as privileged infrastructure authorization.
+- **Execution mode — pick one:**
+  - **Postgres + daemon:** `gbrain jobs work` runs a persistent worker that
+    claims and executes jobs from the queue.
+  - **PGLite + --follow:** `gbrain jobs submit ... --follow` runs inline.
+    The daemon mode is not available on PGLite (exclusive file lock). See
+    `docs/guides/minions-shell-jobs.md`.
+- **MCP boundary:** shell-job submission is CLI-only. `submit_job name="shell"`
+  over MCP throws an `OperationError` with code `permission_denied` ("'shell'
+  jobs cannot be submitted over MCP") because `shell` is in `PROTECTED_JOB_NAMES`.
+  Agents CAN observe shell jobs via `get_job` / `list_jobs` / `get_job_progress`
+  (not protected), but cannot submit them. Operator or autopilot submits;
+  agent observes.
+- **Verify setup:** after configuration, run `gbrain jobs stats` (CLI) to
+  confirm the worker is registered and consuming the queue.
+
+### Submit (CLI, operator or autopilot)
+
+Shell jobs take their command via `--params` as a JSON object with `cmd` (string)
+or `argv` (array), plus `cwd` and optional `env`.
+
+Command string form:
+```
+gbrain jobs submit shell --params '{"cmd":"echo hello","cwd":"/abs/path"}'
+```
+
+Argv form (no shell expansion):
+```
+gbrain jobs submit shell --params '{"argv":["bash","-lc","echo hello"],"cwd":"/abs/path"}'
+```
+
+Inline execution on PGLite or any one-shot deployment:
+```
+gbrain jobs submit shell --params '{"cmd":"echo hello","cwd":"/tmp"}' --follow
+```
+
+Queue/lifecycle flags exposed by `gbrain jobs submit --help`: `--queue`,
+`--priority`, `--delay`, `--max-attempts`, `--max-stalled`, `--backoff-type`,
+`--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key`,
+`--dry-run`.
+
+### Monitor (agents or operator)
+
+These operations are MCP-callable and safe for agent use:
+
+```
+list_jobs --name shell --status active
+get_job ID
+get_job_progress ID
+```
+
+Check structured result fields (exit code, stdout/stderr tails, attempts,
+timings) from `get_job`. Use `gbrain jobs stats` (CLI) for worker/queue
+health dashboard.
+
+### Control (MCP-callable)
+
+```
+cancel_job id=ID
+replay_job id=ID
+```
+
+`replay_job` is not protected — only shell *submission* is. Agents can
+cancel or replay a shell job without CLI access.
+
+Use idempotency keys for recurring shell workloads to avoid duplicate runs.
+
+## Subagent Jobs (LLM Orchestration)
+
+Use for open-ended reasoning, tool-using research, and fan-out synthesis.
+
+**User-facing entrypoint:** `gbrain agent run <prompt>` is the canonical way
+to submit subagent work. It handles the elevated-trust plumbing — `subagent`
+and `subagent_aggregator` are both in `PROTECTED_JOB_NAMES`, so direct MCP
+submission requires `{allowProtectedSubmit: true}`, which `gbrain agent run`
+supplies.
 
 ## Phase 1: Submit
 
 ```
-submit_job name="research" data={"prompt":"Research Acme Corp revenue","tools":["search","web_search"]}
+gbrain agent run "Research Acme Corp revenue" --tools "search,query"
 ```
 
-Options:
-- `queue` — queue name (default: 'default')
-- `priority` — lower = higher priority (default: 0)
-- `max_attempts` — retry limit (default: 3)
-- `delay` — ms delay before eligible
+`--tools` accepts a comma-separated subset of `BRAIN_TOOL_ALLOWLIST` (see
+`src/core/minions/tools/brain-allowlist.ts`): `query`, `search`, `get_page`,
+`list_pages`, `file_list`, `file_url`, `get_backlinks`, `traverse_graph`,
+`resolve_slugs`, `get_ingest_log`, `put_page`. Anything outside the allow-list
+is rejected at submit time with `allowed_tools references unknown tool`.
 
-For parallel work, submit a parent then children:
+For parallel work with a fan-out manifest:
 ```
-submit_job name="orchestrate" data={"task":"research 5 companies"}
-# Returns parent_id
-
-submit_job name="research" data={"company":"Acme"} parent_job_id=PARENT_ID
-submit_job name="research" data={"company":"Beta"} parent_job_id=PARENT_ID
-submit_job name="research" data={"company":"Gamma"} parent_job_id=PARENT_ID
+gbrain agent run --fanout-manifest companies.json
 ```
 
-Parent auto-enters `waiting-children` and unblocks when all children finish.
+The manifest describes N children + 1 aggregator. Each child runs
+`name="subagent"` under the hood; the aggregator runs `name="subagent_aggregator"`
+and claims AFTER every child terminates. See
+`src/core/minions/handlers/subagent.ts` and
+`src/core/minions/handlers/subagent-aggregator.ts`.
+
+Flags (from `src/commands/agent.ts`):
+- `--subagent-def <name>` — named subagent definition
+- `--model <id>` — override model
+- `--max-turns <N>` — cap the LLM loop
+- `--tools <csv>` — allow-listed brain tools (see above)
+- `--timeout-ms <N>` — hard timeout per job
+- `--fanout-manifest <file>` — N children + 1 aggregator
+- `--follow` / `--no-follow` — stream logs + wait (default on TTY)
+- `--detach` — submit and return immediately
+
+Queue/priority/retry tuning is not exposed by `gbrain agent run`; submit the
+raw `subagent` handler via `gbrain jobs submit` (requires CLI trust) if you
+need those knobs.
 
 ## Phase 2: Monitor
 
 ```
-list_jobs --status active          # what's running?
-get_job ID                         # full details + logs + tokens
-get_job_progress ID                # structured progress snapshot
-get_job_stats                      # health dashboard
+list_jobs --status active          # MCP — what's running?
+get_job ID                         # MCP — full details + logs + tokens
+get_job_progress ID                # MCP — structured progress snapshot
+gbrain jobs stats                  # CLI — queue health dashboard
+gbrain agent logs ID --follow      # CLI — streaming transcript + heartbeat
 ```
 
 Progress includes: step count, total steps, message, token usage, last tool called.
@@ -121,6 +239,8 @@ replay_job id=ID                   # re-run with same or modified params
 replay_job id=ID data_overrides={"depth":"deep"}  # replay with changes
 ```
 
+All lifecycle ops are MCP-callable.
+
 ## Phase 5: Review Results
 
 ```
@@ -154,9 +274,9 @@ When reporting batch status (parent with children):
 
 ```
 Parent #ID — waiting-children
-  #A research(Acme) — active, 3/5 steps, 2.5k tokens
-  #B research(Beta) — completed, 1.8k tokens
-  #C research(Gamma) — paused
+  #A subagent(Acme) — active, 3/5 steps, 2.5k tokens
+  #B subagent(Beta) — completed, 1.8k tokens
+  #C subagent(Gamma) — paused
 Total tokens so far: 4.3k
 ```
 
@@ -164,19 +284,19 @@ Total tokens so far: 4.3k
 
 - Don't spawn a Minion for a single search query (use search tool directly)
 - Don't fire-and-forget without checking results
-- Don't spawn > 5 concurrent agents without checking `get_job_stats` first
-- Don't use `sessions_spawn` with `runtime: "subagent"` when Minions is available
+- Don't spawn > 5 concurrent agents without checking `gbrain jobs stats` first
+- For subagent work, don't use `sessions_spawn` with `runtime: "subagent"` when Minions is available (use `gbrain agent run` instead)
 - Don't poll `get_job` in a tight loop (use `get_job_progress` for lightweight checks)
 
 ## Tools Used
 
-- Submit a background job (submit_job)
-- Get job details (get_job)
-- List jobs with filters (list_jobs)
-- Cancel a job (cancel_job)
-- Pause a job (pause_job)
-- Resume a paused job (resume_job)
-- Replay a completed/failed job (replay_job)
-- Send sidechannel message (send_job_message)
-- Get structured progress (get_job_progress)
-- Get job queue stats (get_job_stats)
+- Submit a background job — `submit_job` (MCP, non-protected names only; shell jobs are CLI-only, subagent jobs via `gbrain agent run`)
+- Get job details — `get_job` (MCP)
+- List jobs with filters — `list_jobs` (MCP)
+- Cancel a job — `cancel_job` (MCP)
+- Pause a job — `pause_job` (MCP)
+- Resume a paused job — `resume_job` (MCP)
+- Replay a completed/failed job — `replay_job` (MCP)
+- Send sidechannel message — `send_job_message` (MCP)
+- Get structured progress — `get_job_progress` (MCP)
+- Queue stats — `gbrain jobs stats` (CLI; no MCP equivalent)

skills/query/SKILL.md

@@ -12,6 +12,12 @@ triggers:
   - "what happened"
   - "search for"
   - "look up"
+  - "background on"
+  - "notes on"
+  - "who knows who"
+  - "relationship between"
+  - "connections"
+  - "graph query"
 tools:
   - search
   - query

skills/smoke-test/SKILL.md

@@ -10,6 +10,7 @@ triggers:
   - "container restart check"
   - "health check"
   - "did the restart break anything"
+  - "did the container restart break anything"
 tools:
   - exec
   - read

src/cli.ts

@@ -19,7 +19,7 @@ for (const op of operations) {
 }
 
 // CLI-only commands that bypass the operation layer
-const CLI_ONLY = new Set(['init', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test']);
+const CLI_ONLY = new Set(['init', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'storage', 'repos', 'code-def', 'code-refs', 'reindex-code', 'code-callers', 'code-callees', 'frontmatter', 'auth', 'friction', 'claw-test']);
 
 async function main() {
   // Parse global flags (--quiet / --progress-json / --progress-interval)
@@ -285,6 +285,11 @@ async function handleCliOnly(command: string, args: string[]) {
     await runIntegrations(args);
     return;
   }
+  if (command === 'auth') {
+    const { runAuth } = await import('./commands/auth.ts');
+    await runAuth(args);
+    return;
+  }
   if (command === 'resolvers') {
     const { runResolvers } = await import('./commands/resolvers.ts');
     await runResolvers(args);
@@ -305,6 +310,11 @@ async function handleCliOnly(command: string, args: string[]) {
     await runBacklinks(args);
     return;
   }
+  if (command === 'frontmatter') {
+    const { runFrontmatter } = await import('./commands/frontmatter.ts');
+    await runFrontmatter(args);
+    return;
+  }
   if (command === 'lint') {
     const { runLint } = await import('./commands/lint.ts');
     await runLint(args);
@@ -333,6 +343,14 @@ async function handleCliOnly(command: string, args: string[]) {
     await runSkillpack(args);
     return;
   }
+  if (command === 'friction') {
+    const { runFriction } = await import('./commands/friction.ts');
+    process.exit(runFriction(args));
+  }
+  if (command === 'claw-test') {
+    const { runClawTest } = await import('./commands/claw-test.ts');
+    process.exit(await runClawTest(args));
+  }
   if (command === 'report') {
     const { runReport } = await import('./commands/report.ts');
     await runReport(args);
@@ -442,7 +460,7 @@ async function handleCliOnly(command: string, args: string[]) {
       }
       case 'serve': {
         const { runServe } = await import('./commands/serve.ts');
-        await runServe(engine);
+        await runServe(engine, args);
         return; // serve doesn't disconnect
       }
       case 'call': {
@@ -501,6 +519,15 @@ async function handleCliOnly(command: string, args: string[]) {
         await runGraphQuery(engine, args);
         break;
       }
+      case 'reconcile-links': {
+        // v0.20.0 Cathedral II Layer 8 D3: batch-recompute doc↔impl edges
+        // for any markdown page that cites code files. Idempotent; safe to
+        // re-run. Closes the v0.19.0 Layer 6 order-dependency bug where
+        // guides imported before their code never got their edges written.
+        const { runReconcileLinksCli } = await import('./commands/reconcile-links.ts');
+        await runReconcileLinksCli(engine, args);
+        break;
+      }
       case 'orphans': {
         const { runOrphans } = await import('./commands/orphans.ts');
         await runOrphans(engine, args);
@@ -511,6 +538,53 @@ async function handleCliOnly(command: string, args: string[]) {
         await runSources(engine, args);
         break;
       }
+      case 'storage': {
+        const { runStorage } = await import('./commands/storage.ts');
+        await runStorage(engine, args);
+        break;
+      }
+      case 'code-def': {
+        const { runCodeDef } = await import('./commands/code-def.ts');
+        await runCodeDef(engine, args);
+        break;
+      }
+      case 'code-refs': {
+        const { runCodeRefs } = await import('./commands/code-refs.ts');
+        await runCodeRefs(engine, args);
+        break;
+      }
+      case 'reindex-code': {
+        // v0.20.0 Cathedral II Layer 13 (E2): explicit code-page reindex
+        // for users upgrading from v0.19.0. Cost-preview gated; TTY prompt
+        // or ConfirmationRequired envelope for non-TTY/JSON callers.
+        const { runReindexCodeCli } = await import('./commands/reindex-code.ts');
+        await runReindexCodeCli(engine, args);
+        break;
+      }
+      case 'code-callers': {
+        // v0.20.0 Cathedral II Layer 10 (C4): "who calls <symbol>?"
+        const { runCodeCallers } = await import('./commands/code-callers.ts');
+        await runCodeCallers(engine, args);
+        break;
+      }
+      case 'code-callees': {
+        // v0.20.0 Cathedral II Layer 10 (C5): "what does <symbol> call?"
+        const { runCodeCallees } = await import('./commands/code-callees.ts');
+        await runCodeCallees(engine, args);
+        break;
+      }
+      case 'repos': {
+        // v0.19.0: `gbrain repos ...` is an alias into the v0.18.0 sources
+        // subsystem. The repos abstraction (Garry's OpenClaw baseline) was
+        // redundant with sources and carried per-user config state that
+        // couldn't participate in federation / RLS / multi-tenancy. We
+        // keep the alias so scripts like `gbrain repos add .` keep
+        // working, with a nudge toward the canonical command.
+        console.error('[gbrain] Note: "repos" is an alias for "sources" as of v0.19.0. Prefer `gbrain sources <subcommand>`.');
+        const { runSources } = await import('./commands/sources.ts');
+        await runSources(engine, args);
+        break;
+      }
     }
   } finally {
     if (command !== 'serve') await engine.disconnect();
@@ -525,7 +599,10 @@ async function connectEngine(): Promise<BrainEngine> {
   }
   const { createEngine } = await import('./core/engine-factory.ts');
   const engine = await createEngine(toEngineConfig(config));
-  await engine.connect(toEngineConfig(config));
+  const noRetry = process.argv.includes('--no-retry-connect') ||
+                  process.env.GBRAIN_NO_RETRY_CONNECT === '1';
+  const { connectWithRetry } = await import('./core/db.ts');
+  await connectWithRetry(engine, toEngineConfig(config), { noRetry });
   return engine;
 }
 
@@ -581,6 +658,8 @@ IMPORT/EXPORT
   sync --watch [--interval N]        Continuous sync (loops until stopped)
   sync --install-cron                Install persistent sync daemon
   export [--dir ./out/]              Export to markdown
+  export --restore-only [--repo <p>] Restore missing supabase-only files
+        [--type T] [--slug-prefix S] With optional filters
 
 FILES
   files list [slug]                  List stored files
@@ -625,6 +704,25 @@ TOOLS
   check-resolvable [--json] [--fix]  Validate skill tree (reachability/MECE/DRY)
   report --type <name> --content ... Save timestamped report to brain/reports/
 
+SOURCES (multi-repo / multi-brain)
+  sources list                       Show registered sources
+  sources add <id> --path <p>        Register a source (id = short name, e.g. 'wiki')
+  sources remove <id>                Remove a source + its pages
+  sync --all                         Sync all sources with a local_path
+  sync --source <id>                 Sync one specific source
+  repos ...                          DEPRECATED alias for 'sources' (v0.19.0)
+
+CODE INDEXING (v0.19.0 / v0.20.0 Cathedral II)
+  code-def <symbol> [--lang l]       Find the definition of a symbol across code pages
+  code-refs <symbol> [--lang l]      Find all references to a symbol (JSON-first)
+  code-callers <symbol>              Who calls this symbol? (v0.20.0 A1)
+  code-callees <symbol>              What does this symbol call? (v0.20.0 A1)
+  query <q> --lang <l>               Filter hybrid search to one language (v0.20.0)
+  query <q> --symbol-kind <k>        Filter to symbol type (function|class|method|...) (v0.20.0)
+  reconcile-links [--dry-run]        Batch-recompute doc↔impl edges (v0.20.0)
+  reindex-code [--source id] [--yes] Explicit code-page reindex (v0.20.0)
+  sync --strategy code               Sync code files into the brain
+
 JOBS (Minions)
   jobs submit <name> [--params JSON]  Submit background job [--follow] [--dry-run]
   jobs list [--status S] [--limit N]  List jobs
@@ -643,6 +741,8 @@ ADMIN
   features [--json] [--auto-fix]     Scan usage + recommend unused features
   autopilot [--repo] [--interval N]  Self-maintaining brain daemon
   config [show|get|set] <key> [val]  Brain config
+  storage status [--repo <path>]     Storage tier status and health
+        [--json]                     (git-tracked vs supabase-only)
   serve                              MCP server (stdio)
   call <tool> '<json>'               Raw tool invocation
   version                            Version info

src/commands/auth.ts

@@ -1,20 +1,29 @@
 #!/usr/bin/env bun
 /**
- * GBrain token management — standalone script, no gbrain CLI dependency.
+ * GBrain token management.
  *
- * Usage:
+ * Wired into the CLI as of v0.22.5:
+ *   gbrain auth create "claude-desktop"
+ *   gbrain auth list
+ *   gbrain auth revoke "claude-desktop"
+ *   gbrain auth test <url> --token <token>
+ *
+ * Also runs standalone (no compiled binary required):
  *   DATABASE_URL=... bun run src/commands/auth.ts create "claude-desktop"
- *   DATABASE_URL=... bun run src/commands/auth.ts list
- *   DATABASE_URL=... bun run src/commands/auth.ts revoke "claude-desktop"
- *   DATABASE_URL=... bun run src/commands/auth.ts test <url> --token <token>
+ *
+ * Both paths require DATABASE_URL or GBRAIN_DATABASE_URL (except `test`,
+ * which only hits the remote URL and doesn't need a local DB).
  */
 import postgres from 'postgres';
 import { createHash, randomBytes } from 'crypto';
 
-const DATABASE_URL = process.env.DATABASE_URL || process.env.GBRAIN_DATABASE_URL;
-if (!DATABASE_URL && process.argv[2] !== 'test') {
-  console.error('Set DATABASE_URL or GBRAIN_DATABASE_URL environment variable.');
-  process.exit(1);
+function getDatabaseUrl(requireDb: boolean): string | undefined {
+  const url = process.env.DATABASE_URL || process.env.GBRAIN_DATABASE_URL;
+  if (!url && requireDb) {
+    console.error('Set DATABASE_URL or GBRAIN_DATABASE_URL environment variable.');
+    process.exit(1);
+  }
+  return url;
 }
 
 function hashToken(token: string): string {
@@ -27,7 +36,7 @@ function generateToken(): string {
 
 async function create(name: string) {
   if (!name) { console.error('Usage: auth create <name>'); process.exit(1); }
-  const sql = postgres(DATABASE_URL!);
+  const sql = postgres(getDatabaseUrl(true)!);
   const token = generateToken();
   const hash = hashToken(token);
 
@@ -53,7 +62,7 @@ async function create(name: string) {
 }
 
 async function list() {
-  const sql = postgres(DATABASE_URL!);
+  const sql = postgres(getDatabaseUrl(true)!);
   try {
     const rows = await sql`
       SELECT name, created_at, last_used_at, revoked_at
@@ -80,7 +89,7 @@ async function list() {
 
 async function revoke(name: string) {
   if (!name) { console.error('Usage: auth revoke <name>'); process.exit(1); }
-  const sql = postgres(DATABASE_URL!);
+  const sql = postgres(getDatabaseUrl(true)!);
   try {
     const result = await sql`
       UPDATE access_tokens SET revoked_at = now()
@@ -216,26 +225,38 @@ async function test(url: string, token: string) {
   console.log(`\n🧠 Your brain is live! (${elapsed}s)`);
 }
 
-// CLI dispatch
-const [cmd, ...args] = process.argv.slice(2);
-switch (cmd) {
-  case 'create': await create(args[0]); break;
-  case 'list': await list(); break;
-  case 'revoke': await revoke(args[0]); break;
-  case 'test': {
-    const tokenIdx = args.indexOf('--token');
-    const url = args.find(a => !a.startsWith('--') && a !== args[tokenIdx + 1]);
-    const token = tokenIdx >= 0 ? args[tokenIdx + 1] : '';
-    await test(url || '', token || '');
-    break;
-  }
-  default:
-    console.log(`GBrain Token Management
+/**
+ * Entry point for the `gbrain auth` CLI subcommand. Also reused by the
+ * direct-script path (see bottom of file) so `bun run src/commands/auth.ts`
+ * still works.
+ */
+export async function runAuth(args: string[]): Promise<void> {
+  const [cmd, ...rest] = args;
+  switch (cmd) {
+    case 'create': await create(rest[0]); return;
+    case 'list': await list(); return;
+    case 'revoke': await revoke(rest[0]); return;
+    case 'test': {
+      const tokenIdx = rest.indexOf('--token');
+      const url = rest.find(a => !a.startsWith('--') && a !== rest[tokenIdx + 1]);
+      const token = tokenIdx >= 0 ? rest[tokenIdx + 1] : '';
+      await test(url || '', token || '');
+      return;
+    }
+    default:
+      console.log(`GBrain Token Management
 
 Usage:
-  bun run src/commands/auth.ts create <name>      Create a new access token
-  bun run src/commands/auth.ts list               List all tokens
-  bun run src/commands/auth.ts revoke <name>       Revoke a token
-  bun run src/commands/auth.ts test <url> --token <token>  Smoke test a remote MCP server
+  gbrain auth create <name>           Create a new access token
+  gbrain auth list                    List all tokens
+  gbrain auth revoke <name>           Revoke a token
+  gbrain auth test <url> --token <t>  Smoke-test a remote MCP server
 `);
+  }
+}
+
+// Direct-script entry point — only runs when this file is invoked as the main module
+// (e.g. `bun run src/commands/auth.ts ...`). When imported by cli.ts, this block is skipped.
+if (import.meta.main) {
+  await runAuth(process.argv.slice(2));
 }