v0.31.7 fix-wave: doctor stops crying wolf — 5 community PRs (#798 + #788 + #536 + #376 + #128 adapted) (#804)

* fix: merge resolver entries from all files (RESOLVER.md + AGENTS.md)

OpenClaw deployments typically have AGENTS.md at the workspace root as the
real skill dispatcher (200+ entries), while gbrain skillpacks install a
thin skills/RESOLVER.md (~40 entries). The previous first-match-wins policy
meant check-resolvable only saw the thin RESOLVER.md, reporting 187 skills
as 'unreachable' when they were fully routed in AGENTS.md.

Now: check-resolvable collects entries from ALL resolver files across both
the skills directory and its parent. Entries are deduped by skillPath
(first occurrence wins). The combined content is also passed to the
routing-eval (Check 5) so routing fixtures see the full trigger index.

New function findAllResolverFiles() in resolver-filenames.ts returns all
matching files instead of just the first. findResolverFile() is unchanged
(backward-compatible for callers that need a single path).

Before: 37/224 reachable (our deployment)
After:  200/224 reachable (remaining 24 are genuine gaps)

Tests: 8 new (findAllResolverFiles + checkResolvable merge behavior)

* fix: graph_coverage skipped when brain has 0 entity pages

Closes #530.

`graph_coverage` measures `link_coverage` (fraction of entity pages with
inbound links) and `timeline_coverage` (fraction with timeline entries).
Both formulas divide by entity-page count.

For markdown-only brains (journals, wikis, notes — Karpathy's original
LLM Wiki use case) the entity count is 0, so coverage is structurally
undefined. The check still reported 'warn: 0%' under that condition,
which:
1. Brain owners cannot satisfy without indexing code/entities
2. Doctor's hint references stale commands (`link-extract` /
   `timeline-extract` were renamed to `extract` in v0.22)
3. Adds noise to compliance/health automation gating on doctor exit

Fix: detect entity-page count via SQL. If 0, mark check 'ok' with explanation.
Otherwise keep existing logic but update hint to current `gbrain extract all`.

Tested on Nous AGaaS production wiki: 2533 markdown pages, 100% embedded,
6086 wikilinks, 1964 timeline entries — 0 entity pages — graph_coverage
correctly clears.

* fix(doctor): deprecate stale link-extract / timeline-extract verb names

The graph_coverage hint and the link-extraction.ts header comment
still referenced `gbrain link-extract` / `gbrain timeline-extract`,
which were consolidated into `gbrain extract <links|timeline|all>` in
v0.16. Following the consolidation in #536's resolution (which fixed
the doctor hint to `gbrain extract all`), this commit removes the last
stale reference in `src/core/link-extraction.ts`'s header comment.

Originally PR #376 by @FUSED-ID. The doctor.ts portion of #376 is
absorbed by #536's richer warn message; this commit lands #376's
`link-extraction.ts` portion only.

Co-Authored-By: Leon-Gerard Vandenberg <FUSED-ID@users.noreply.github.com>

* test(doctor): pin canonical `gbrain extract all` hint, ban stale verbs

IRON-RULE regression guard for PR #376 + #536's graph_coverage hint
fix (locked in v0.31.7 eng-review). The removed verbs `gbrain
link-extract` and `gbrain timeline-extract` were consolidated into
`gbrain extract <links|timeline|all>` in v0.16 but the hint kept
suggesting them for ~30 releases. Pin the user-facing copy at the
source-string level so a future edit can't silently re-regress.

Structural assertion in the existing `doctor command` describe block,
matching the file's existing `frontmatter_integrity` / `rls_event_trigger`
pattern. No DB-fixture infrastructure needed.

* fix: sync RESOLVER.md triggers with v0.25.1 skill frontmatter

`gbrain doctor` reported 36 routing-miss/ambiguous warnings against the
v0.25.1 wave skills (book-mirror, article-enrichment, strategic-reading,
concept-synthesis, perplexity-research, archive-crawler, academic-verify,
brain-pdf, voice-note-ingest). Each skill's frontmatter declared 4-5
triggers, but only the first ever made it into RESOLVER.md's hand-curated
rows. The structural matcher couldn't find any specific phrase for
realistic user intents, so requests fell through to broader parents
(`ingest`, `enrich`, `data-research`).

Pulled the missing triggers from each skill's `triggers:` frontmatter
into the matching RESOLVER.md row. Converted media-ingest's prose row
to quoted triggers so the matcher actually sees them. Added
`"summarize this book"` to media-ingest (covers a book-mirror
disambiguation fixture). Marked article-enrichment + perplexity-research
fixtures with `ambiguous_with` for the parent skills they intentionally
chain with — RESOLVER.md's preamble explicitly documents that skills are
designed to chain, so this is acknowledging the truth, not papering over
a bug.

Result: 36 routing warnings → 0. resolver-test/check-resolvable/
routing-eval suite: 140/0.

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

* fix(doctor): find skills/ on every deployment shape (read-path-only)

Adapts the install-path resolution from PR #128 (TheAndersMadsen) into
the existing 5-tier autoDetectSkillsDir architecture. Two new code paths,
read-path-only by design:

1. Tier-0 $GBRAIN_SKILLS_DIR explicit operator override on the SHARED
   autoDetectSkillsDir. Safe for both read and write paths because the
   operator explicitly set the var — opt-in retargeting is fine.

2. New autoDetectSkillsDirReadOnly() function for READ-ONLY callers
   (gbrain doctor, check-resolvable, routing-eval). Wraps the shared
   detect; on null, walks up from fileURLToPath(import.meta.url) gated
   by isGbrainRepoRoot() so unrelated repos along the install path
   can't false-positive.

The split is the architectural fix for a write-path regression risk
codex outside-voice review surfaced (eng-review D5): adding the
install-path fallback to the SHARED resolver would let `gbrain skillpack
install` from `~` silently target the bundled gbrain repo's skills/
instead of the user's actual workspace. Three write-path call sites stay
on the original autoDetectSkillsDir; three read-path call sites switch
to the new readOnly variant.

Closes the install-path footgun for hosted-CLI installs:
`bun install -g github:garrytan/gbrain && cd ~ && gbrain doctor` now
finds the bundled skills/ instead of warning "Could not find skills
directory."

Test surface: 8 new cases in test/repo-root.test.ts covering tier-0
valid/invalid/precedence, install-path walk, isGbrainRepoRoot gate
(via primary-success-no-drift assertion), AUTO_DETECT_HINT updates,
and the D5 regression guard that pins the read-path/write-path split.

Co-Authored-By: Anders Madsen <TheAndersMadsen@users.noreply.github.com>

* docs(changelog): expand v0.31.7 entry for full 5-PR doctor wave

Promotes headline from "doctor stops crying wolf about unreachable
skills on OpenClaw" to the assembled wave's narrative: every doctor
false-positive class on disk today, plus the install-path footgun
that bit every hosted-CLI user.

Numbers-that-matter table expanded to 6 rows covering all 5 PRs.
Itemized-changes section grouped by sub-wave: resolver merge,
RESOLVER.md trigger sync, graph_coverage zero-entity, stale verb
hint fix, install-path resolver. Contributors named explicitly:
@mayazbay, @psperera, @FUSED-ID, @TheAndersMadsen. "For contributors"
section flags the new SkillsDirSource variants and the read-path /
write-path split as the canonical pattern for future fallback
additions.

* chore(v0.31.7): bump version + regenerate llms + fix CLI regression-gate

Wraps up the v0.31.7 doctor-fix wave:

- VERSION + package.json: 0.31.1.1-fixwave -> 0.31.7
- llms-full.txt: regenerated against the expanded v0.31.7 CHANGELOG
  entry (committed bundle drift caught by test/build-llms.test.ts)
- test/check-resolvable-cli.test.ts: update the REGRESSION-GATE for
  empty-cwd no_skills_dir error to reflect v0.31.7's intentional
  behavior change. The install-path fallback in autoDetectSkillsDirReadOnly
  now finds the bundled skills/ from any cwd inside the gbrain repo,
  so the test asserts source: 'install_path' instead of error: 'no_skills_dir'.
  This is the wave's headline capability ("doctor finds itself on every
  deployment shape") rather than a regression.

Pre-existing flake unrelated to this wave: BrainRegistry — lazy init >
empty/null/undefined id routes to host fails on machines that have
~/.gbrain/config.json present (the test assumes test env has none).
Reproduces on master before this wave landed; not a v0.31.7 regression.
Filed for follow-up in next maintainer hygiene sweep.

* fix(doctor): close write-path leak in --fix + sync routing-eval merge

Codex adversarial review of v0.31.7 caught a HIGH that the eng review
missed (D6 lock during /ship): the read-path-only architecture for the
install-path fallback is leaky because TWO of the three "read-only"
callers (doctor, check-resolvable) actually have write modes via --fix
that call autoFixDryViolations() and writeFileSync to SKILL.md files.
A user running `cd ~ && gbrain doctor --fix` with no skills/RESOLVER.md
up the cwd tree would resolve via the install-path fallback to the
bundled gbrain repo and silently rewrite the install-tree skills —
exactly the regression D5's split was supposed to prevent.

Fix: when --fix is requested and the resolved skills dir came from the
install-path source, refuse with a clear error pointing at GBRAIN_SKILLS_DIR
/ OPENCLAW_WORKSPACE / --skills-dir as explicit overrides. The read parts
of doctor and check-resolvable continue to benefit from the install-path
fallback (the v0.31.7 capability headline); only --fix is gated.

Plus a MEDIUM consistency fix codex flagged: routing-eval was still
single-file-only while check-resolvable does multi-file merge across
skills/RESOLVER.md + ../AGENTS.md. On OpenClaw layouts this caused
routing-eval and check-resolvable to disagree on what's routable.
routing-eval now uses the same findAllResolverFiles + content-merge
pattern as check-resolvable, so all three commands see the same
trigger index.

Test coverage: D6 regression guard in test/check-resolvable-cli.test.ts
spawning a real subprocess from an empty tempdir (no env, no cwd
fallback) and asserting --fix refuses with the correct stderr message.

Co-Authored-By: Codex (outside-voice review) <noreply@openai.com>

* docs(changelog): note D6 --fix gate + routing-eval merge in v0.31.7 entry

* docs: post-ship sync for v0.31.7

CLAUDE.md updates only. CHANGELOG.md was already authored by /ship and was left untouched.

- src/core/repo-root.ts annotation: read-path/write-path split, tier-0 GBRAIN_SKILLS_DIR override, autoDetectSkillsDirReadOnly install-path fallback, D6 --fix safety gate.
- src/commands/check-resolvable.ts annotation: multi-file resolver merge across skills dir + parent (37/224 -> 200/224 reachable on the reference OpenClaw layout), install-path read-only fallback, D6 --fix gate.
- src/commands/routing-eval.ts annotation: same multi-file merge as check-resolvable; v0.25.1 RESOLVER.md trigger sync.
- src/commands/doctor.ts annotation: switched to autoDetectSkillsDirReadOnly so 'cd ~ && gbrain doctor' finds bundled skills via install-path fallback; --fix D6 install-path refuse-write gate; graph_coverage zero-entity short-circuit + canonical 'gbrain extract all' hint with regression-test pin.
- Test inventory: replaced bare regression-v0_16_4 line with explicit test/repo-root.test.ts entry (20 cases - 12 existing + 8 new D3/D5) and new test/resolver-merge.test.ts entry (8 cases).

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

* docs(llms): regenerate after CLAUDE.md sync for v0.31.7

* ci(test): quarantine *.serial.test.ts files from test-shard

CI's test-shard.sh was including *.serial.test.ts files in the parallel
shard runs, which broke voyage-multimodal.test.ts: 18 of its 22 tests
failed in CI shard 2 because eval-takes-quality-runner.serial.test.ts
ran before it in the same bun-test process and leaked its mock.module()
substitution of src/core/ai/gateway.ts. The leaked mock omitted
embedMultimodal and resetGateway, so voyage-multimodal saw `undefined
is not a function` everywhere it touched the gateway.

Locally `bun run test` (run-unit-parallel.sh → run-unit-shard.sh)
already excludes *.serial.test.ts and runs them via `bun run test:serial`
in their own pass with --max-concurrency=1. Master ran green there;
only CI's matrix shards exposed the leak. The runner.serial test file's
own header comment explicitly calls out this exact cross-file mock
leak — the quarantine was the design, CI just wasn't honoring it.

Three changes:

1. scripts/test-shard.sh — exclude *.serial.test.ts and *.slow.test.ts
   from the find expression, mirroring scripts/run-unit-shard.sh.

2. .github/workflows/test.yml — add a `test-serial` sibling job that
   runs `bun run test:serial`. Keeps serial tests gating CI without
   merging them back into the parallel shards.

3. test/scripts/test-shard.test.ts — regression test pinning the three
   exclusion clauses (serial, slow, e2e) so a future refactor that
   drops one of them fails loud rather than silently re-introducing
   the cross-file mock leak.

Verified locally:
- shard 2 reproduction: 18 voyage-multimodal failures → 0 (1 unrelated
  env-dependent perf flake remains, won't fail on CI)
- bun run test:serial: 189/190 pass (1 unrelated env-dependent
  BrainRegistry flake from ~/.gbrain/config.json presence)
- typecheck + check:test-isolation clean

* ci(test): rephrase mock-module comment to satisfy R2 lint

The verify gate's check:test-isolation flagged test/scripts/test-shard.test.ts
because the JSDoc comment contained the literal string 'mock.module()'
which matches R2's grep regex 'mock\.module[[:space:]]*\('. The file
itself doesn't use mock.module — it just describes why the linter rule
exists in human-readable prose.

Rephrased to avoid the trailing parens. The regex requires the open
paren, so 'bun's module-mocking primitive' instead of 'mock.module()'
is invisible to the linter while preserving meaning for the next
maintainer who reads the test.

* docs(claude): tighten version-consistency rules + add merge recovery procedure

After several merges from master where VERSION + package.json +
CHANGELOG.md drifted out of sync (each merge hit conflicts on those
three files; auto-merge sometimes resolved silently in the wrong
direction), CLAUDE.md gets an explicit drift-recovery checklist + a
3-line paste-ready audit command anyone can run.

Three additions to the existing "Version locations" section:

1. **Mandatory audit command** — three echo lines that print VERSION,
   package.json version, and the top CHANGELOG header. All three MUST
   match the wave's `MAJOR.MINOR.PATCH.MICRO`. Designed for paste-after-
   every-merge use.

2. **Merge-conflict recovery procedure** — exact sed/echo patterns for
   resolving VERSION + package.json + CHANGELOG conflicts, in the order
   to apply them. Names the anti-pattern (mixing `git checkout --ours`
   on the trio) that's bitten us before.

3. **Pre-push gate** — re-run the audit before `git push` of any merge
   commit. /ship Step 12 catches drift but only if you actually run
   /ship; manual pushes skip the check.

Confirmed consistent at d361482a, 7e8f6960, 65a5994a (every merge
commit on this branch). The doc gap was the rules being too loose,
not the rules being wrong — this beefs up the procedural side so the
next merge can't silently desync.

* docs(llms): regenerate after CLAUDE.md edit + tighten the rule

CI failed on the build-llms generator test because CLAUDE.md edited
in fe050ae0 (version-consistency procedure) shipped without a
matching `bun run build:llms` regen. The committed llms-full.txt was
77 lines short of fresh generator output, and test/build-llms.test.ts
caught the drift in CI shard 1.

Two changes:

1. llms.txt + llms-full.txt — regenerated to match current CLAUDE.md.

2. CLAUDE.md — strengthened the "Auto-derived" entry for llms.txt /
   llms-full.txt with explicit "every CLAUDE.md edit chases with
   `bun run build:llms` in the same commit" wording. Notes that
   `verify` doesn't run the build-llms test, only the full unit
   suite does, so a clean typecheck is NOT enough to know you can
   push after touching CLAUDE.md.

This is now the third time this has bitten the wave. The previous
"Auto-derived" entry said the right thing but was buried in a list;
elevating it to imperative voice with a count of past regressions
should make the next CLAUDE.md edit hard to land without the chaser.

---------

Co-authored-by: garrytan-agents <garrytan-agents@users.noreply.github.com>
Co-authored-by: Madi Ayazbay <madia@Mac.localdomain>
Co-authored-by: Leon-Gerard Vandenberg <FUSED-ID@users.noreply.github.com>
Co-authored-by: psperera <pperera@mac.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Anders Madsen <TheAndersMadsen@users.noreply.github.com>
Co-authored-by: Codex (outside-voice review) <noreply@openai.com>

CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to GBrain will be documented in this file.
 
+## [0.31.7] - 2026-05-09
+
+**`gbrain doctor` stops crying wolf, period — and finds itself on every deployment shape. Five community PRs land one cohesive narrative: every false-positive class on disk today, plus the install-path footgun that bit every hosted-CLI user who ever ran `gbrain doctor` from `~`.**
+
+When the doctor cries wolf, agents and humans learn to ignore it, which then masks the real problems. The previous wave (v0.31.1.1-fixwave) sharpened real signal with `sync_failures` code classification. This wave fixes the inverse: every false-positive class on disk today gets honest. Five PRs, four contributors, one theme.
+
+### The numbers that matter
+
+Verified against a live OpenClaw deployment with 224 skills, `skills/RESOLVER.md` (41 entries from skillpack), and `../AGENTS.md` (206 entries); plus a markdown-only journal brain (2533 pages, 0 entity pages); plus the v0.25.1 wave skills' routing-eval suite; plus a hosted-CLI install:
+
+| | Before | After |
+|---|---|---|
+| OpenClaw reachable skills | 37/224 | **200/224** |
+| v0.25.1 skill routing accuracy | 36 ambiguous matches | **0** |
+| Markdown-only brain `graph_coverage` | warn forever | **OK** |
+| Stale `gbrain link-extract` hint (since v0.16) | suggested in WARN | **`gbrain extract all`** |
+| Hosted-CLI doctor from `~` | "Could not find skills directory" | **finds bundled `skills/`** |
+| Health score on healthy OpenClaw + journal brains | 40/100 | **100/100** |
+
+The remaining unreachable skills, low-coverage warnings, and any future doctor warns are real gaps: new skills without trigger rows, brains with actual coverage shortfalls, fixes you actually want to see.
+
+### What you can now do
+
+**`gbrain doctor` is honest about resolver health on OpenClaw deployments.** OpenClaw workspaces typically have a thin `skills/RESOLVER.md` (~40 entries from the skillpack) and a fat `AGENTS.md` at the workspace root (200+ entries, the real dispatcher). The previous first-match-wins policy only saw `RESOLVER.md`, so the doctor reported 187 skills as "unreachable" when they were fully routed in `AGENTS.md`. Now `check-resolvable` collects entries from every resolver file across both the skills directory and its parent, deduped by `skillPath`. New helper `findAllResolverFiles()` returns every match instead of the first. ([#798](https://github.com/garrytan/gbrain/pull/798))
+
+**Routing accuracy on the v0.25.1 wave skills lifts from "36 ambiguous warnings" to zero.** Each skill's `triggers:` frontmatter declares 4-5 entries, but only the first ever made it into the matching RESOLVER.md row, so the structural matcher couldn't find a specific phrase for realistic user intents. RESOLVER.md is now synced with the full frontmatter triggers across book-mirror, article-enrichment, strategic-reading, concept-synthesis, perplexity-research, archive-crawler, academic-verify, brain-pdf, voice-note-ingest, and media-ingest. Plus targeted `ambiguous_with` fixture annotations where chains like `enrich → article-enrichment` are designed to co-fire. Contributed by [@psperera](https://github.com/psperera). ([#788](https://github.com/garrytan/gbrain/pull/788))
+
+**Markdown-only brains pass `graph_coverage` instead of warning at 0% forever.** The check measures `link_coverage` and `timeline_coverage` over entity pages. For wikis, journals, and notes brains (Karpathy's original LLM Wiki use case), entity count is 0, so coverage is structurally undefined. The doctor now detects this and reports `ok: no entity pages — graph_coverage not applicable`. Verified on a 2533-page production wiki with 6086 wikilinks, 1964 timeline entries, zero entity pages. Contributed by [@mayazbay](https://github.com/mayazbay). ([#536](https://github.com/garrytan/gbrain/pull/536), closes #530)
+
+**The `graph_coverage` hint stops suggesting commands that haven't existed since v0.16.** The hint pointed at `gbrain link-extract && gbrain timeline-extract` (consolidated into `gbrain extract <links|timeline|all>` 30 releases ago). Now says `gbrain extract all`. Header comment in `src/core/link-extraction.ts` updated to match. Pinned by an IRON-RULE regression test that bans the stale verb names from the source string. Originally raised by [@FUSED-ID](https://github.com/FUSED-ID). ([#376](https://github.com/garrytan/gbrain/pull/376), folded into the wave's clean shape)
+
+**`gbrain doctor` works from anywhere.** On `bun install -g github:garrytan/gbrain && cd ~ && gbrain doctor`, the doctor used to warn "Could not find skills directory" and dock the health score forever — every hosted-CLI user took a permanent `-5`. The bundled `skills/` lives under `node_modules/gbrain/`; the cwd-only walk never looked there. Now there's a tier-0 `$GBRAIN_SKILLS_DIR` operator override (Docker mounts, CI, monorepo subdirs) plus a read-only install-path fallback that walks up from the gbrain module's own location. Doctor / check-resolvable / routing-eval get the install-path fallback; write-path callers (skillpack install, skillify scaffold) deliberately do NOT — the architectural split prevents `gbrain skillpack install` from `~` silently retargeting the bundled gbrain repo's skills/ instead of the user's actual workspace. Originally raised by [@TheAndersMadsen](https://github.com/TheAndersMadsen) ([#128](https://github.com/garrytan/gbrain/pull/128)); adapted into the existing 5-tier resolver after eng + outside-voice review.
+
+### To take advantage of v0.31.7
+
+```bash
+gbrain upgrade
+gbrain doctor
+```
+
+After upgrade, anything that was `[WARN] graph_coverage` or `[WARN] resolver_health` on a healthy brain should now be `[OK]`. Real warnings remain real. The `[WARN]` lines you see are the ones worth acting on — file an issue at https://github.com/garrytan/gbrain/issues with `gbrain doctor --json` output if anything looks off.
+
+### Itemized changes
+
+#### Resolver merge across multiple files
+- `src/core/resolver-filenames.ts`: add `findAllResolverFiles(dir)` returning every recognized resolver file in `dir`. `findResolverFile()` unchanged (backward-compatible).
+- `src/core/check-resolvable.ts`: replace single-file lookup with multi-file merge across skills dir + parent. Entries deduped by `skillPath`. Combined `resolverContent` passed to routing-eval. Error message switches from hardcoded "RESOLVER.md" to `RESOLVER_FILENAMES_LABEL`.
+- `test/resolver-merge.test.ts`: 8 new cases covering `findAllResolverFiles` behavior and the merge path in `checkResolvable`.
+
+#### RESOLVER.md trigger sync (v0.25.1 wave)
+- `skills/RESOLVER.md`: 9 hand-curated rows expanded to include the full frontmatter triggers per skill. media-ingest's prose row converted to quoted triggers so the matcher actually sees them; `"PDF book"` and `"ingest it into my brain"` carried over from HEAD's richer frontmatter.
+- `skills/article-enrichment/routing-eval.jsonl`: `ambiguous_with: ["enrich"]` added to all 5 fixtures (acknowledges the resolver doc's framing that skills chain).
+
+#### graph_coverage zero-entity short-circuit + verb fix
+- `src/commands/doctor.ts`: detect entity-page count via SQL; mark check `ok` when 0 entity pages. Hint updated to `gbrain extract all`.
+- `src/core/link-extraction.ts`: header comment updated to reference the consolidated `extract.ts`.
+- `test/doctor.test.ts`: IRON-RULE regression assertion bans `gbrain link-extract` / `gbrain timeline-extract` from the source string.
+
+#### Install-path resolver (read-path-only)
+- `src/core/repo-root.ts`: tier-0 `$GBRAIN_SKILLS_DIR` explicit override on shared `autoDetectSkillsDir`. New exported `autoDetectSkillsDirReadOnly` wraps it with install-path fallback gated by `isGbrainRepoRoot`. Two new `SkillsDirSource` variants: `'env_explicit'`, `'install_path'`. New `AUTO_DETECT_HINT_READ_ONLY` constant.
+- Read-path callers switched to `autoDetectSkillsDirReadOnly`: `src/commands/doctor.ts`, `src/commands/check-resolvable.ts`, `src/commands/routing-eval.ts`.
+- Write-path callers stay on `autoDetectSkillsDir`: `src/commands/skillpack.ts`, `src/commands/skillify.ts`, `src/core/skillpack/post-install-advisory.ts`. The split prevents silent workspace retargeting on `gbrain skillpack install` from `~`.
+- `test/repo-root.test.ts`: 8 new cases covering tier-0 valid/invalid/precedence, install-path walk, no-drift on primary success, AUTO_DETECT_HINT updates, and the D5 regression guard that pins the read-path/write-path split (asserts the shared resolver MUST NEVER return `'install_path'` source).
+
+### For contributors
+
+- New `SkillsDirSource` variants `'env_explicit'` and `'install_path'` — downstream consumers using the type union should add cases (TypeScript exhaustiveness will flag missing handlers).
+- The architectural split between `autoDetectSkillsDir` (read+write-safe) and `autoDetectSkillsDirReadOnly` (read-only with install-path fallback) is the canonical pattern for any future "fall back further when nothing else worked" addition. New consumers default to the safer (write-safe) variant; opt into the read-only variant with intent.
+- `gbrain doctor --fix` and `gbrain check-resolvable --fix` refuse to write when the skills dir resolved via the install-path fallback (caught by codex during the ship review — without this gate, running `--fix` from a cwd with no skills dir would have silently rewritten the bundled install tree). Set `$GBRAIN_SKILLS_DIR`, `$OPENCLAW_WORKSPACE`, or pass `--skills-dir <path>` to enable `--fix`.
+- `gbrain routing-eval` now uses the same multi-file resolver merge as `check-resolvable`, so on OpenClaw layouts (`skills/RESOLVER.md` + `../AGENTS.md`) all three commands see the same trigger index. Previously `routing-eval` read only the first resolver file it found.
+- Contributors: [@mayazbay](https://github.com/mayazbay), [@psperera](https://github.com/psperera), [@FUSED-ID](https://github.com/FUSED-ID), [@TheAndersMadsen](https://github.com/TheAndersMadsen). Outside-voice plan review (codex) caught the read-path/write-path split risk on the original plan; a second codex pass during /ship caught the `--fix` write-path leak before merge.
+
+[#798](https://github.com/garrytan/gbrain/pull/798) [#788](https://github.com/garrytan/gbrain/pull/788) [#536](https://github.com/garrytan/gbrain/pull/536) [#376](https://github.com/garrytan/gbrain/pull/376) [#128](https://github.com/garrytan/gbrain/pull/128)
 ## [0.31.4.1] - 2026-05-10
 
 **Takes v2: lessons from a 100K-take production extraction folded back into the runtime, and `gbrain auth` works on Postgres again.**

CLAUDE.md

@@ -89,8 +89,8 @@ strict behavior when unset.
 - `src/core/ai/gateway.ts` — unified seam for every AI call. **v0.28.7 (#680):** module-scoped `_embedTransport` defaulting to AI SDK `embedMany`, with `__setEmbedTransportForTests(fn)` test seam so tests drive the public `embed()` function with a stubbed transport instead of probing private helpers. `splitByTokenBudget` and `isTokenLimitError` are now exported `@internal` — pure functions reused directly by the test file. Module-level `_shrinkState: Map<recipeId, {factor, consecutiveSuccesses}>` halves the recipe's effective `safety_factor` on token-limit miss (floor 0.05) and heals back ×1.5 toward the ceiling after `SHRINK_HEAL_AFTER=10` consecutive successes. `configureGateway()` walks every registered recipe at construction time and emits a once-per-process stderr warning for any embedding touchpoint missing `max_batch_tokens` (excluding the canonical OpenAI fast-path recipe). `resetGateway()` clears `_shrinkState`, the warned-set, and restores the real transport. ASCII flow diagram embedded in the `embed()` JSDoc covers the routing decision, recursion + halving, and shrinkState lifecycle. **v0.28.11 (#719):** `embedMultimodal()` reads `cfg.embedding_multimodal_model` first (falls back to `cfg.embedding_model` for single-model setups). After the existing recipe-level `supports_multimodal` fast-fail, validates the resolved model against `touchpoint.multimodal_models` when declared — closes the Voyage-text-only-model-into-multimodal-endpoint footgun before any HTTP call (Codex F1 from PR review). New `getMultimodalModel()` accessor mirrors `getEmbeddingModel` / `getChatModel` so doctor and integration tests can read the gateway state.
 - `src/core/ai/recipes/voyage.ts` — Voyage AI openai-compatible recipe. **v0.28.7 (#680):** declares `chars_per_token=1` + `safety_factor=0.5` so the gateway pre-splits Voyage batches at a 60K-character budget (50% of 120K-token cap with the dense-tokenizer ratio). Closes the v0.27 backfill loop where ~26% of the corpus stayed un-embedded because tiktoken-grounded budgeting silently undercounted Voyage's actual token usage. **v0.28.11 (#719):** declares `multimodal_models: ['voyage-multimodal-3']` so the gateway rejects text-only Voyage models pointed at the multimodal endpoint with a clear `AIConfigError` instead of waiting for Voyage's HTTP 400.
 - `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`.
-- `src/core/repo-root.ts` — Shared `findRepoRoot(startDir?)` (v0.16.4): walks up from `startDir` (default `process.cwd()`) looking for `skills/RESOLVER.md`. Zero-dependency module imported by both `doctor.ts` and `check-resolvable.ts`. Parameterized `startDir` makes tests hermetic.
-- `src/commands/check-resolvable.ts` — Standalone CLI wrapper (v0.16.4) over `checkResolvable()`. Exports `parseFlags`, `resolveSkillsDir`, `DEFERRED`, `runCheckResolvable`. Exit rule: **1 on any issue (warnings OR errors)**, stricter than doctor's `ok` flag — honors README:259. Stable JSON envelope `{ok, skillsDir, report, autoFix, deferred, error, message}` — same shape on success and error paths. `--fix` path runs `autoFixDryViolations` BEFORE `checkResolvable` (same ordering as doctor). `scripts/skillify-check.ts` subprocess-calls `gbrain check-resolvable --json` (cached per process) and fails loud on binary-missing — no silent false-pass. **v0.19:** AGENTS.md workspaces now resolve natively (see `src/core/resolver-filenames.ts`) — gbrain inspects the 107-skill OpenClaw deployment whether the routing file is `RESOLVER.md` or `AGENTS.md`. `DEFERRED[]` is empty — Checks 5 + 6 shipped as real code, not issue URLs.
+- `src/core/repo-root.ts` — Shared `findRepoRoot(startDir?)` (v0.16.4): walks up from `startDir` (default `process.cwd()`) looking for `skills/RESOLVER.md`. Zero-dependency module imported by both `doctor.ts` and `check-resolvable.ts`. Parameterized `startDir` makes tests hermetic. **v0.31.7:** read-path / write-path split. `autoDetectSkillsDir` (shared, read+write-safe) gains tier-0 `$GBRAIN_SKILLS_DIR` explicit operator override (Docker mounts, CI, monorepo subdirs) ahead of the existing 4-tier chain. New `autoDetectSkillsDirReadOnly` wraps it with a tier-5 install-path fallback that walks up from `fileURLToPath(import.meta.url)` and gates on `isGbrainRepoRoot` so unrelated repos can't false-positive. Read-path callers (`doctor`, `check-resolvable`, `routing-eval`) use the read-only variant; write-path callers (`skillpack install`, `skillify scaffold`, `post-install-advisory`) deliberately stay on the shared function so `gbrain skillpack install` from `~` cannot silently retarget the bundled gbrain repo's `skills/` instead of the user's actual workspace. Two new `SkillsDirSource` variants: `'env_explicit'`, `'install_path'`. New `AUTO_DETECT_HINT_READ_ONLY` documents the extra tier. The D6 `--fix` safety gate in `doctor.ts` + `check-resolvable.ts` refuses auto-repair when `detected.source === 'install_path'` so `gbrain doctor --fix` from `~` cannot silently rewrite the bundled install tree.
+- `src/commands/check-resolvable.ts` — Standalone CLI wrapper (v0.16.4) over `checkResolvable()`. Exports `parseFlags`, `resolveSkillsDir`, `DEFERRED`, `runCheckResolvable`. Exit rule: **1 on any issue (warnings OR errors)**, stricter than doctor's `ok` flag — honors README:259. Stable JSON envelope `{ok, skillsDir, report, autoFix, deferred, error, message}` — same shape on success and error paths. `--fix` path runs `autoFixDryViolations` BEFORE `checkResolvable` (same ordering as doctor). `scripts/skillify-check.ts` subprocess-calls `gbrain check-resolvable --json` (cached per process) and fails loud on binary-missing — no silent false-pass. **v0.19:** AGENTS.md workspaces now resolve natively (see `src/core/resolver-filenames.ts`) — gbrain inspects the 107-skill OpenClaw deployment whether the routing file is `RESOLVER.md` or `AGENTS.md`. `DEFERRED[]` is empty — Checks 5 + 6 shipped as real code, not issue URLs. **v0.31.7:** the resolver lookup switched from first-match-wins to the multi-file merge in `src/core/check-resolvable.ts` — entries collected from every `RESOLVER.md` / `AGENTS.md` across the skills dir AND its parent, deduped by `skillPath` (first occurrence wins). Lifted reachable skills on the reference OpenClaw layout from 37/224 to 200/224 — the deployment ships a thin `skills/RESOLVER.md` (~40 entries from skillpack) plus a fat `../AGENTS.md` (200+ entries, the real dispatcher), and the previous code only saw the first one. The CLI also switched to `autoDetectSkillsDirReadOnly` so `cd ~ && gbrain check-resolvable` finds the bundled skills via the install-path fallback. `--fix` carries the same D6 safety gate as `gbrain doctor --fix`: refuses to write when `detected.source === 'install_path'`.
 - `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.
@@ -99,7 +99,7 @@ strict behavior when unset.
 - `src/core/archive-crawler-config.ts` (v0.25.1) — D12 + codex HIGH-4 safety gate for the `archive-crawler` skill. Refuses to run unless `archive-crawler.scan_paths:` is explicitly set in the brain repo's `gbrain.yml`. Mirrors the storage-config.ts parsing pattern (sibling file; separate concern from storage tiering). `loadArchiveCrawlerConfig(repoPath)` throws `ArchiveCrawlerConfigError(missing_section | empty_scan_paths | invalid_path | parse_error)`. `normalizeAndValidateArchiveCrawlerConfig` rejects relative paths and `..` traversal; `~` is expanded; trailing-slash normalized for unambiguous prefix matching. `isPathAllowed(candidate, config)` is the runtime per-file gate (scan_paths prefix-match with directory-boundary correctness; deny_paths overrides). Tests in `test/archive-crawler-config.test.ts` (19 cases).
 - `test/helpers/cli-pty-runner.ts` (v0.25.1) — generic real-PTY harness ported from gstack and trimmed to ~470 lines. Uses pure `Bun.spawn({terminal:})` (Bun 1.3.10+; engines.bun pin in package.json). Generic primitives only — no plan-mode orchestrators. Exports: `launchPty`, `resolveBinary`, `stripAnsi`, `parseNumberedOptions`, `optionsSignature`, `isNumberedOptionListVisible`, `isTrustDialogVisible`. Self-tests in `test/cli-pty-runner.test.ts` (24 cases).
 - `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). 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/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. **v0.31.7:** switched to `autoDetectSkillsDirReadOnly` and the same multi-file resolver merge as `check-resolvable`, so on OpenClaw layouts (`skills/RESOLVER.md` + `../AGENTS.md`) all three commands see the same trigger index — previously `routing-eval` read only the first resolver file it found. The v0.25.1 wave skills' RESOLVER.md rows were also synced to include the full frontmatter `triggers:` arrays (was only the first trigger), so the structural matcher actually sees the realistic phrasings; ambiguous-fixture annotations cover deliberate skill chains like `enrich → article-enrichment`.
 - `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
@@ -154,7 +154,7 @@ strict behavior when unset.
 - `src/commands/anomalies.ts` (v0.29) — `gbrain anomalies [--since YYYY-MM-DD] [--lookback-days N] [--sigma N] [--json]`: cohort-level activity outliers. Calls `engine.findAnomalies(opts)`. Two cohort kinds in v1: tag, type. Year cohort deferred to v0.30.
 - `src/commands/transcripts.ts` (v0.29) — `gbrain transcripts recent [--days N] [--full] [--json]`: recent raw `.txt` transcripts from the dream-cycle corpus dirs. Imports `listRecentTranscripts` from `src/core/transcripts.ts` (the same library the gated `get_recent_transcripts` MCP op uses). Local-only by construction — the CLI always runs with `ctx.remote=false`.
 - `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. v0.26.7 (#612): `rls_event_trigger` check (post-install drift detector for migration v35's auto-RLS event trigger). Lives outside the `// 5. RLS` slice that the structural doctor.test.ts guards anchor on, so the existing test guards stay intact. Healthy `evtenabled` set is `('O','A')` only — `R` is replica-only and would not fire in normal sessions; `D` is disabled. Fix hint is `gbrain apply-migrations --force-retry 35`. **v0.30.2:** `queue_health` gains a fourth subcheck — surfaces dead-lettered subagent jobs with `last_error` matching the `prompt_too_long` classifier within the last 24h. Fix hint points at `gbrain dream --phase synthesize --dry-run --json` to identify the offending transcript and `gbrain jobs prune --status dead --queue default` to clean up. Postgres-only.
+- `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. v0.26.7 (#612): `rls_event_trigger` check (post-install drift detector for migration v35's auto-RLS event trigger). Lives outside the `// 5. RLS` slice that the structural doctor.test.ts guards anchor on, so the existing test guards stay intact. Healthy `evtenabled` set is `('O','A')` only — `R` is replica-only and would not fire in normal sessions; `D` is disabled. Fix hint is `gbrain apply-migrations --force-retry 35`. **v0.30.2:** `queue_health` gains a fourth subcheck — surfaces dead-lettered subagent jobs with `last_error` matching the `prompt_too_long` classifier within the last 24h. Fix hint points at `gbrain dream --phase synthesize --dry-run --json` to identify the offending transcript and `gbrain jobs prune --status dead --queue default` to clean up. Postgres-only. **v0.31.7:** `runDoctor` switches to `autoDetectSkillsDirReadOnly` (from `src/core/repo-root.ts`) so `bun install -g github:garrytan/gbrain && cd ~ && gbrain doctor` finds the bundled `skills/` via the install-path fallback instead of warning "Could not find skills directory" + docking the health score. `--fix` carries a D6 safety gate: when `detected.source === 'install_path'`, the command refuses auto-repair with a stderr message pointing at `$GBRAIN_SKILLS_DIR` / `$OPENCLAW_WORKSPACE` / `--skills-dir`, because `autoFixDryViolations` writes to SKILL.md files and would otherwise silently rewrite the install tree. The `graph_coverage` check now short-circuits to `ok: 'No entity pages — graph_coverage not applicable (markdown-only brain)'` when `SELECT COUNT(*) FROM pages WHERE type IN ('entity','person','company','organization')` returns 0 (closes #530); the entity count is woven into the warn message and the WARN hint switches from the long-deprecated `gbrain link-extract && gbrain timeline-extract` (gone since v0.16) to the canonical `gbrain extract all`. Pinned by an IRON-RULE regression assertion in `test/doctor.test.ts` that bans the stale verb names from the source string.
 - `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). **v40 (v0.29):** `pages_emotional_weight` adds `pages.emotional_weight REAL NOT NULL DEFAULT 0.0`. Column-only (no index). On Postgres 11+ and PGLite, `ADD COLUMN` with a constant DEFAULT is metadata-only — instant on tables of any size. 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. **v35 (v0.26.7):** auto-RLS event trigger + one-time backfill. `auto_rls_on_create_table` fires on `ddl_command_end` for `WHEN TAG IN ('CREATE TABLE','CREATE TABLE AS','SELECT INTO')` and runs `ALTER TABLE … ENABLE ROW LEVEL SECURITY` on every new `public.*` table — no FORCE (matches v24/v29/schema.sql posture so non-BYPASSRLS apps can still read their own tables). The same migration backfills RLS on every existing `public.*` base table whose comment doesn't match the doctor regex (`^GBRAIN:RLS_EXEMPT\s+reason=\S.{3,}`). Per-table failure aborts the offending CREATE TABLE (event triggers fire inside the DDL transaction); no EXCEPTION wrap — that would convert loud rollback into silent permissive default. PGLite no-op via `sqlFor.pglite: ''`. Breaking change: operators with intentionally-RLS-off public tables must add the GBRAIN:RLS_EXEMPT comment BEFORE upgrade or the backfill will flip them on. **v46 (v0.31.3):** `mcp_request_log_params_jsonb_normalize` rewrites pre-v0.31.3 rows where `mcp_request_log.params` was stored as a JSON-encoded string (`jsonb_typeof = 'string'`) up to a real JSONB object via `UPDATE ... SET params = params::text::jsonb WHERE jsonb_typeof(params) = 'string'`. Single statement, idempotent — second-run finds no string-shaped rows and is a no-op. Closes the bug where `/admin/api/requests` returned a quoted string instead of the parsed object.
 - `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.
@@ -574,6 +574,8 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/trust-boundary-contract.test.ts` (v0.26.9 — 4 cases pinning F7b fail-closed semantics under cast bypass: `ctx.remote === undefined` treated as remote/untrusted at every flipped call site, `as any` and `Partial<>` spreads can't downgrade trust by accident),
 `test/check-resolvable-cli.test.ts` (v0.19 CLI wrapper: exit codes, JSON envelope shape, AGENTS.md fallback chain),
 `test/regression-v0_16_4.test.ts` (findRepoRoot regression guard — hermetic startDir parameterization),
+`test/repo-root.test.ts` (v0.16.4 / v0.19 / v0.31.7 — 20 cases: `findRepoRoot` walk semantics + default-arg parity, the 4-tier `autoDetectSkillsDir` fallback chain (`$OPENCLAW_WORKSPACE` → `~/.openclaw/workspace` → repo-root → `./skills`), W1 RESOLVER.md/AGENTS.md filename precedence, D-CX-4 explicit-env-wins-over-repo-root, and 8 new v0.31.7 D3+D5 cases pinning tier-0 `$GBRAIN_SKILLS_DIR` valid/invalid/precedence-over-OPENCLAW_WORKSPACE, the install-path walk in `autoDetectSkillsDirReadOnly`, no-drift on primary success, `AUTO_DETECT_HINT` + `AUTO_DETECT_HINT_READ_ONLY` content, and the D5 regression guard asserting the shared `autoDetectSkillsDir` MUST NEVER return `'install_path'` source — that's how the read-path/write-path split stays safe),
+`test/resolver-merge.test.ts` (v0.31.7 — 8 cases pinning the multi-file resolver merge: `findAllResolverFiles` empty / RESOLVER.md-only / AGENTS.md-only / both-present (RESOLVER.md first), and `checkResolvable` merge semantics across `skills/RESOLVER.md` + `../AGENTS.md` for the OpenClaw layout where the skillpack ships a thin RESOLVER.md and the real dispatcher lives at the workspace root — dedup by `skillPath` (first occurrence wins), AGENTS.md-at-workspace-root works alone, and the previously-unreachable 187/224 OpenClaw skills become reachable),
 `test/filing-audit.test.ts` (v0.19 Check 6: `writes_pages` / `writes_to` frontmatter, filing-rules JSON validation),
 `test/routing-eval.test.ts` (v0.19 Check 5: fixture parsing, structural routing, ambiguous_with, Haiku tie-break layer),
 `test/skill-manifest.test.ts` (v0.19 skill manifest parser: drift detection, managed-block markers),
@@ -800,10 +802,15 @@ four numeric segments are required first. Historical 3-segment versions
 
 - `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.
+- `llms-full.txt` / `llms.txt` — auto-generated documentation bundles. **Any
+  CLAUDE.md edit MUST be followed by `bun run build:llms` in the same commit
+  (or a follow-up commit before push).** The committed bundles are checked
+  against fresh generator output by `test/build-llms.test.ts`, which runs in
+  CI shard 1. If you edited CLAUDE.md and didn't regenerate, CI will fail.
+  This has bitten the wave 3 times — every CLAUDE.md edit gets a `bun run
+  build:llms` chaser, no exceptions. (The `verify` gate doesn't run this
+  test; only the full unit suite does. So `bun run typecheck` clean is NOT
+  enough to know you can push after a CLAUDE.md edit.)
 
 **Historical (DO NOT bump on release):**
 
@@ -832,6 +839,83 @@ 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.
 
+### Mandatory version-consistency audit (run after EVERY merge or commit that touches VERSION, package.json, or CHANGELOG)
+
+**The trio MUST agree.** Every merge from master will hit conflicts on
+VERSION + package.json + CHANGELOG.md because master ships its own
+version bumps. Auto-merge sometimes resolves these silently in unexpected
+ways. After any merge, branch update, or version-related edit, run this
+audit. It's three lines and never lies:
+
+```bash
+echo "VERSION:     $(cat VERSION)"
+echo "package.json: $(node -e 'process.stdout.write(require("./package.json").version)')"
+grep -E "^## \[" CHANGELOG.md | head -1
+```
+
+All three MUST show the same `MAJOR.MINOR.PATCH.MICRO`. If any one
+disagrees, you have not finished the merge. Fix it before pushing or
+shipping. There is no situation in which "I'll fix it next push" is OK,
+because:
+
+- A green local test run with mismatched VERSION/package.json still
+  fails the CI version-gate.
+- A green CHANGELOG entry under the wrong version header silently lies
+  to release-notes consumers.
+- /ship's Step 12 idempotency check classifies a mismatch as
+  `DRIFT_UNEXPECTED` and HALTS — but only if you remember to run /ship
+  before pushing. Manual `git push` skips the check.
+
+### Merge-conflict recovery procedure (memorize this)
+
+When `git merge origin/master` reports conflicts on VERSION,
+package.json, or CHANGELOG.md, resolve in this exact order:
+
+1. **VERSION** — overwrite with the wave's version (`echo -n "X.Y.Z.W"
+   > VERSION`). Highest semver wins; do NOT take master's lower version.
+2. **package.json** — strip the conflict markers, keep the wave's
+   version line. Sed pattern:
+   `sed -i.bak '/^<<<<<<< HEAD$/d; /^=======$/,/^>>>>>>> /d' package.json && rm package.json.bak`
+   (assumes ours is above the `=======`).
+3. **CHANGELOG.md** — strip ALL three conflict markers; both your entry
+   and master's entry stay. Sed pattern:
+   `sed -i.bak '/^<<<<<<< HEAD$/d; /^=======$/d; /^>>>>>>> origin\/master$/d' CHANGELOG.md && rm CHANGELOG.md.bak`
+   Then verify your entry is the topmost `## [X.Y.Z.W]` and master's
+   newer-than-yours entries (if any) sit below.
+4. **Run the 3-line audit above.** If it doesn't show your version on
+   all three lines, you missed a marker.
+5. **Run `bun install`** to refresh `bun.lock` against the resolved
+   `package.json`. Stage and commit if it changed.
+6. **Run `bun run typecheck`** before committing the merge.
+7. Only THEN run `git commit` for the merge.
+
+If the audit shows drift after step 4, do NOT proceed to step 5. Re-run
+steps 1-3 against the actual file content; you missed a marker or
+resolved one in the wrong direction.
+
+**Anti-pattern to avoid:** Resolving via `git checkout --ours package.json`
+and `git checkout --theirs scripts/test-shard.sh` mixed in the same
+commit. The selective directional resolution is fine, but on
+VERSION/package.json/CHANGELOG specifically, ALWAYS use the explicit
+`echo > VERSION` + sed-strip-markers pattern above. The directional
+checkout flags have bitten us when the conflict shape was unexpected
+(e.g. master stripped a section we expected to keep).
+
+### Pre-push gate (manual; tighten when you remember to)
+
+Before any `git push` of a merge commit, run the audit one more time:
+
+```bash
+echo "VERSION:     $(cat VERSION)"
+echo "package.json: $(node -e 'process.stdout.write(require("./package.json").version)')"
+grep -E "^## \[" CHANGELOG.md | head -1
+```
+
+If you've been editing the branch via `/ship` you can rely on Step 12's
+idempotency check. If you've been editing manually (merge resolution,
+conflict fix, version bump), the audit is the last line of defense
+before CI yells at you.
+
 ## Pre-ship requirements
 
 Before shipping (/ship) or reviewing (/review), always run the full test suite.

VERSION

@@ -1 +1 @@
-0.31.4.1
+0.31.7

llms-full.txt

@@ -189,8 +189,8 @@ strict behavior when unset.
 - `src/core/ai/gateway.ts` — unified seam for every AI call. **v0.28.7 (#680):** module-scoped `_embedTransport` defaulting to AI SDK `embedMany`, with `__setEmbedTransportForTests(fn)` test seam so tests drive the public `embed()` function with a stubbed transport instead of probing private helpers. `splitByTokenBudget` and `isTokenLimitError` are now exported `@internal` — pure functions reused directly by the test file. Module-level `_shrinkState: Map<recipeId, {factor, consecutiveSuccesses}>` halves the recipe's effective `safety_factor` on token-limit miss (floor 0.05) and heals back ×1.5 toward the ceiling after `SHRINK_HEAL_AFTER=10` consecutive successes. `configureGateway()` walks every registered recipe at construction time and emits a once-per-process stderr warning for any embedding touchpoint missing `max_batch_tokens` (excluding the canonical OpenAI fast-path recipe). `resetGateway()` clears `_shrinkState`, the warned-set, and restores the real transport. ASCII flow diagram embedded in the `embed()` JSDoc covers the routing decision, recursion + halving, and shrinkState lifecycle. **v0.28.11 (#719):** `embedMultimodal()` reads `cfg.embedding_multimodal_model` first (falls back to `cfg.embedding_model` for single-model setups). After the existing recipe-level `supports_multimodal` fast-fail, validates the resolved model against `touchpoint.multimodal_models` when declared — closes the Voyage-text-only-model-into-multimodal-endpoint footgun before any HTTP call (Codex F1 from PR review). New `getMultimodalModel()` accessor mirrors `getEmbeddingModel` / `getChatModel` so doctor and integration tests can read the gateway state.
 - `src/core/ai/recipes/voyage.ts` — Voyage AI openai-compatible recipe. **v0.28.7 (#680):** declares `chars_per_token=1` + `safety_factor=0.5` so the gateway pre-splits Voyage batches at a 60K-character budget (50% of 120K-token cap with the dense-tokenizer ratio). Closes the v0.27 backfill loop where ~26% of the corpus stayed un-embedded because tiktoken-grounded budgeting silently undercounted Voyage's actual token usage. **v0.28.11 (#719):** declares `multimodal_models: ['voyage-multimodal-3']` so the gateway rejects text-only Voyage models pointed at the multimodal endpoint with a clear `AIConfigError` instead of waiting for Voyage's HTTP 400.
 - `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`.
-- `src/core/repo-root.ts` — Shared `findRepoRoot(startDir?)` (v0.16.4): walks up from `startDir` (default `process.cwd()`) looking for `skills/RESOLVER.md`. Zero-dependency module imported by both `doctor.ts` and `check-resolvable.ts`. Parameterized `startDir` makes tests hermetic.
-- `src/commands/check-resolvable.ts` — Standalone CLI wrapper (v0.16.4) over `checkResolvable()`. Exports `parseFlags`, `resolveSkillsDir`, `DEFERRED`, `runCheckResolvable`. Exit rule: **1 on any issue (warnings OR errors)**, stricter than doctor's `ok` flag — honors README:259. Stable JSON envelope `{ok, skillsDir, report, autoFix, deferred, error, message}` — same shape on success and error paths. `--fix` path runs `autoFixDryViolations` BEFORE `checkResolvable` (same ordering as doctor). `scripts/skillify-check.ts` subprocess-calls `gbrain check-resolvable --json` (cached per process) and fails loud on binary-missing — no silent false-pass. **v0.19:** AGENTS.md workspaces now resolve natively (see `src/core/resolver-filenames.ts`) — gbrain inspects the 107-skill OpenClaw deployment whether the routing file is `RESOLVER.md` or `AGENTS.md`. `DEFERRED[]` is empty — Checks 5 + 6 shipped as real code, not issue URLs.
+- `src/core/repo-root.ts` — Shared `findRepoRoot(startDir?)` (v0.16.4): walks up from `startDir` (default `process.cwd()`) looking for `skills/RESOLVER.md`. Zero-dependency module imported by both `doctor.ts` and `check-resolvable.ts`. Parameterized `startDir` makes tests hermetic. **v0.31.7:** read-path / write-path split. `autoDetectSkillsDir` (shared, read+write-safe) gains tier-0 `$GBRAIN_SKILLS_DIR` explicit operator override (Docker mounts, CI, monorepo subdirs) ahead of the existing 4-tier chain. New `autoDetectSkillsDirReadOnly` wraps it with a tier-5 install-path fallback that walks up from `fileURLToPath(import.meta.url)` and gates on `isGbrainRepoRoot` so unrelated repos can't false-positive. Read-path callers (`doctor`, `check-resolvable`, `routing-eval`) use the read-only variant; write-path callers (`skillpack install`, `skillify scaffold`, `post-install-advisory`) deliberately stay on the shared function so `gbrain skillpack install` from `~` cannot silently retarget the bundled gbrain repo's `skills/` instead of the user's actual workspace. Two new `SkillsDirSource` variants: `'env_explicit'`, `'install_path'`. New `AUTO_DETECT_HINT_READ_ONLY` documents the extra tier. The D6 `--fix` safety gate in `doctor.ts` + `check-resolvable.ts` refuses auto-repair when `detected.source === 'install_path'` so `gbrain doctor --fix` from `~` cannot silently rewrite the bundled install tree.
+- `src/commands/check-resolvable.ts` — Standalone CLI wrapper (v0.16.4) over `checkResolvable()`. Exports `parseFlags`, `resolveSkillsDir`, `DEFERRED`, `runCheckResolvable`. Exit rule: **1 on any issue (warnings OR errors)**, stricter than doctor's `ok` flag — honors README:259. Stable JSON envelope `{ok, skillsDir, report, autoFix, deferred, error, message}` — same shape on success and error paths. `--fix` path runs `autoFixDryViolations` BEFORE `checkResolvable` (same ordering as doctor). `scripts/skillify-check.ts` subprocess-calls `gbrain check-resolvable --json` (cached per process) and fails loud on binary-missing — no silent false-pass. **v0.19:** AGENTS.md workspaces now resolve natively (see `src/core/resolver-filenames.ts`) — gbrain inspects the 107-skill OpenClaw deployment whether the routing file is `RESOLVER.md` or `AGENTS.md`. `DEFERRED[]` is empty — Checks 5 + 6 shipped as real code, not issue URLs. **v0.31.7:** the resolver lookup switched from first-match-wins to the multi-file merge in `src/core/check-resolvable.ts` — entries collected from every `RESOLVER.md` / `AGENTS.md` across the skills dir AND its parent, deduped by `skillPath` (first occurrence wins). Lifted reachable skills on the reference OpenClaw layout from 37/224 to 200/224 — the deployment ships a thin `skills/RESOLVER.md` (~40 entries from skillpack) plus a fat `../AGENTS.md` (200+ entries, the real dispatcher), and the previous code only saw the first one. The CLI also switched to `autoDetectSkillsDirReadOnly` so `cd ~ && gbrain check-resolvable` finds the bundled skills via the install-path fallback. `--fix` carries the same D6 safety gate as `gbrain doctor --fix`: refuses to write when `detected.source === 'install_path'`.
 - `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.
@@ -199,7 +199,7 @@ strict behavior when unset.
 - `src/core/archive-crawler-config.ts` (v0.25.1) — D12 + codex HIGH-4 safety gate for the `archive-crawler` skill. Refuses to run unless `archive-crawler.scan_paths:` is explicitly set in the brain repo's `gbrain.yml`. Mirrors the storage-config.ts parsing pattern (sibling file; separate concern from storage tiering). `loadArchiveCrawlerConfig(repoPath)` throws `ArchiveCrawlerConfigError(missing_section | empty_scan_paths | invalid_path | parse_error)`. `normalizeAndValidateArchiveCrawlerConfig` rejects relative paths and `..` traversal; `~` is expanded; trailing-slash normalized for unambiguous prefix matching. `isPathAllowed(candidate, config)` is the runtime per-file gate (scan_paths prefix-match with directory-boundary correctness; deny_paths overrides). Tests in `test/archive-crawler-config.test.ts` (19 cases).
 - `test/helpers/cli-pty-runner.ts` (v0.25.1) — generic real-PTY harness ported from gstack and trimmed to ~470 lines. Uses pure `Bun.spawn({terminal:})` (Bun 1.3.10+; engines.bun pin in package.json). Generic primitives only — no plan-mode orchestrators. Exports: `launchPty`, `resolveBinary`, `stripAnsi`, `parseNumberedOptions`, `optionsSignature`, `isNumberedOptionListVisible`, `isTrustDialogVisible`. Self-tests in `test/cli-pty-runner.test.ts` (24 cases).
 - `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). 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/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. **v0.31.7:** switched to `autoDetectSkillsDirReadOnly` and the same multi-file resolver merge as `check-resolvable`, so on OpenClaw layouts (`skills/RESOLVER.md` + `../AGENTS.md`) all three commands see the same trigger index — previously `routing-eval` read only the first resolver file it found. The v0.25.1 wave skills' RESOLVER.md rows were also synced to include the full frontmatter `triggers:` arrays (was only the first trigger), so the structural matcher actually sees the realistic phrasings; ambiguous-fixture annotations cover deliberate skill chains like `enrich → article-enrichment`.
 - `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
@@ -254,7 +254,7 @@ strict behavior when unset.
 - `src/commands/anomalies.ts` (v0.29) — `gbrain anomalies [--since YYYY-MM-DD] [--lookback-days N] [--sigma N] [--json]`: cohort-level activity outliers. Calls `engine.findAnomalies(opts)`. Two cohort kinds in v1: tag, type. Year cohort deferred to v0.30.
 - `src/commands/transcripts.ts` (v0.29) — `gbrain transcripts recent [--days N] [--full] [--json]`: recent raw `.txt` transcripts from the dream-cycle corpus dirs. Imports `listRecentTranscripts` from `src/core/transcripts.ts` (the same library the gated `get_recent_transcripts` MCP op uses). Local-only by construction — the CLI always runs with `ctx.remote=false`.
 - `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. v0.26.7 (#612): `rls_event_trigger` check (post-install drift detector for migration v35's auto-RLS event trigger). Lives outside the `// 5. RLS` slice that the structural doctor.test.ts guards anchor on, so the existing test guards stay intact. Healthy `evtenabled` set is `('O','A')` only — `R` is replica-only and would not fire in normal sessions; `D` is disabled. Fix hint is `gbrain apply-migrations --force-retry 35`. **v0.30.2:** `queue_health` gains a fourth subcheck — surfaces dead-lettered subagent jobs with `last_error` matching the `prompt_too_long` classifier within the last 24h. Fix hint points at `gbrain dream --phase synthesize --dry-run --json` to identify the offending transcript and `gbrain jobs prune --status dead --queue default` to clean up. Postgres-only.
+- `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. v0.26.7 (#612): `rls_event_trigger` check (post-install drift detector for migration v35's auto-RLS event trigger). Lives outside the `// 5. RLS` slice that the structural doctor.test.ts guards anchor on, so the existing test guards stay intact. Healthy `evtenabled` set is `('O','A')` only — `R` is replica-only and would not fire in normal sessions; `D` is disabled. Fix hint is `gbrain apply-migrations --force-retry 35`. **v0.30.2:** `queue_health` gains a fourth subcheck — surfaces dead-lettered subagent jobs with `last_error` matching the `prompt_too_long` classifier within the last 24h. Fix hint points at `gbrain dream --phase synthesize --dry-run --json` to identify the offending transcript and `gbrain jobs prune --status dead --queue default` to clean up. Postgres-only. **v0.31.7:** `runDoctor` switches to `autoDetectSkillsDirReadOnly` (from `src/core/repo-root.ts`) so `bun install -g github:garrytan/gbrain && cd ~ && gbrain doctor` finds the bundled `skills/` via the install-path fallback instead of warning "Could not find skills directory" + docking the health score. `--fix` carries a D6 safety gate: when `detected.source === 'install_path'`, the command refuses auto-repair with a stderr message pointing at `$GBRAIN_SKILLS_DIR` / `$OPENCLAW_WORKSPACE` / `--skills-dir`, because `autoFixDryViolations` writes to SKILL.md files and would otherwise silently rewrite the install tree. The `graph_coverage` check now short-circuits to `ok: 'No entity pages — graph_coverage not applicable (markdown-only brain)'` when `SELECT COUNT(*) FROM pages WHERE type IN ('entity','person','company','organization')` returns 0 (closes #530); the entity count is woven into the warn message and the WARN hint switches from the long-deprecated `gbrain link-extract && gbrain timeline-extract` (gone since v0.16) to the canonical `gbrain extract all`. Pinned by an IRON-RULE regression assertion in `test/doctor.test.ts` that bans the stale verb names from the source string.
 - `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). **v40 (v0.29):** `pages_emotional_weight` adds `pages.emotional_weight REAL NOT NULL DEFAULT 0.0`. Column-only (no index). On Postgres 11+ and PGLite, `ADD COLUMN` with a constant DEFAULT is metadata-only — instant on tables of any size. 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. **v35 (v0.26.7):** auto-RLS event trigger + one-time backfill. `auto_rls_on_create_table` fires on `ddl_command_end` for `WHEN TAG IN ('CREATE TABLE','CREATE TABLE AS','SELECT INTO')` and runs `ALTER TABLE … ENABLE ROW LEVEL SECURITY` on every new `public.*` table — no FORCE (matches v24/v29/schema.sql posture so non-BYPASSRLS apps can still read their own tables). The same migration backfills RLS on every existing `public.*` base table whose comment doesn't match the doctor regex (`^GBRAIN:RLS_EXEMPT\s+reason=\S.{3,}`). Per-table failure aborts the offending CREATE TABLE (event triggers fire inside the DDL transaction); no EXCEPTION wrap — that would convert loud rollback into silent permissive default. PGLite no-op via `sqlFor.pglite: ''`. Breaking change: operators with intentionally-RLS-off public tables must add the GBRAIN:RLS_EXEMPT comment BEFORE upgrade or the backfill will flip them on. **v46 (v0.31.3):** `mcp_request_log_params_jsonb_normalize` rewrites pre-v0.31.3 rows where `mcp_request_log.params` was stored as a JSON-encoded string (`jsonb_typeof = 'string'`) up to a real JSONB object via `UPDATE ... SET params = params::text::jsonb WHERE jsonb_typeof(params) = 'string'`. Single statement, idempotent — second-run finds no string-shaped rows and is a no-op. Closes the bug where `/admin/api/requests` returned a quoted string instead of the parsed object.
 - `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.
@@ -674,6 +674,8 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/trust-boundary-contract.test.ts` (v0.26.9 — 4 cases pinning F7b fail-closed semantics under cast bypass: `ctx.remote === undefined` treated as remote/untrusted at every flipped call site, `as any` and `Partial<>` spreads can't downgrade trust by accident),
 `test/check-resolvable-cli.test.ts` (v0.19 CLI wrapper: exit codes, JSON envelope shape, AGENTS.md fallback chain),
 `test/regression-v0_16_4.test.ts` (findRepoRoot regression guard — hermetic startDir parameterization),
+`test/repo-root.test.ts` (v0.16.4 / v0.19 / v0.31.7 — 20 cases: `findRepoRoot` walk semantics + default-arg parity, the 4-tier `autoDetectSkillsDir` fallback chain (`$OPENCLAW_WORKSPACE` → `~/.openclaw/workspace` → repo-root → `./skills`), W1 RESOLVER.md/AGENTS.md filename precedence, D-CX-4 explicit-env-wins-over-repo-root, and 8 new v0.31.7 D3+D5 cases pinning tier-0 `$GBRAIN_SKILLS_DIR` valid/invalid/precedence-over-OPENCLAW_WORKSPACE, the install-path walk in `autoDetectSkillsDirReadOnly`, no-drift on primary success, `AUTO_DETECT_HINT` + `AUTO_DETECT_HINT_READ_ONLY` content, and the D5 regression guard asserting the shared `autoDetectSkillsDir` MUST NEVER return `'install_path'` source — that's how the read-path/write-path split stays safe),
+`test/resolver-merge.test.ts` (v0.31.7 — 8 cases pinning the multi-file resolver merge: `findAllResolverFiles` empty / RESOLVER.md-only / AGENTS.md-only / both-present (RESOLVER.md first), and `checkResolvable` merge semantics across `skills/RESOLVER.md` + `../AGENTS.md` for the OpenClaw layout where the skillpack ships a thin RESOLVER.md and the real dispatcher lives at the workspace root — dedup by `skillPath` (first occurrence wins), AGENTS.md-at-workspace-root works alone, and the previously-unreachable 187/224 OpenClaw skills become reachable),
 `test/filing-audit.test.ts` (v0.19 Check 6: `writes_pages` / `writes_to` frontmatter, filing-rules JSON validation),
 `test/routing-eval.test.ts` (v0.19 Check 5: fixture parsing, structural routing, ambiguous_with, Haiku tie-break layer),
 `test/skill-manifest.test.ts` (v0.19 skill manifest parser: drift detection, managed-block markers),
@@ -900,10 +902,15 @@ four numeric segments are required first. Historical 3-segment versions
 
 - `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.
+- `llms-full.txt` / `llms.txt` — auto-generated documentation bundles. **Any
+  CLAUDE.md edit MUST be followed by `bun run build:llms` in the same commit
+  (or a follow-up commit before push).** The committed bundles are checked
+  against fresh generator output by `test/build-llms.test.ts`, which runs in
+  CI shard 1. If you edited CLAUDE.md and didn't regenerate, CI will fail.
+  This has bitten the wave 3 times — every CLAUDE.md edit gets a `bun run
+  build:llms` chaser, no exceptions. (The `verify` gate doesn't run this
+  test; only the full unit suite does. So `bun run typecheck` clean is NOT
+  enough to know you can push after a CLAUDE.md edit.)
 
 **Historical (DO NOT bump on release):**
 
@@ -932,6 +939,83 @@ 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.
 
+### Mandatory version-consistency audit (run after EVERY merge or commit that touches VERSION, package.json, or CHANGELOG)
+
+**The trio MUST agree.** Every merge from master will hit conflicts on
+VERSION + package.json + CHANGELOG.md because master ships its own
+version bumps. Auto-merge sometimes resolves these silently in unexpected
+ways. After any merge, branch update, or version-related edit, run this
+audit. It's three lines and never lies:
+
+```bash
+echo "VERSION:     $(cat VERSION)"
+echo "package.json: $(node -e 'process.stdout.write(require("./package.json").version)')"
+grep -E "^## \[" CHANGELOG.md | head -1
+```
+
+All three MUST show the same `MAJOR.MINOR.PATCH.MICRO`. If any one
+disagrees, you have not finished the merge. Fix it before pushing or
+shipping. There is no situation in which "I'll fix it next push" is OK,
+because:
+
+- A green local test run with mismatched VERSION/package.json still
+  fails the CI version-gate.
+- A green CHANGELOG entry under the wrong version header silently lies
+  to release-notes consumers.
+- /ship's Step 12 idempotency check classifies a mismatch as
+  `DRIFT_UNEXPECTED` and HALTS — but only if you remember to run /ship
+  before pushing. Manual `git push` skips the check.
+
+### Merge-conflict recovery procedure (memorize this)
+
+When `git merge origin/master` reports conflicts on VERSION,
+package.json, or CHANGELOG.md, resolve in this exact order:
+
+1. **VERSION** — overwrite with the wave's version (`echo -n "X.Y.Z.W"
+   > VERSION`). Highest semver wins; do NOT take master's lower version.
+2. **package.json** — strip the conflict markers, keep the wave's
+   version line. Sed pattern:
+   `sed -i.bak '/^<<<<<<< HEAD$/d; /^=======$/,/^>>>>>>> /d' package.json && rm package.json.bak`
+   (assumes ours is above the `=======`).
+3. **CHANGELOG.md** — strip ALL three conflict markers; both your entry
+   and master's entry stay. Sed pattern:
+   `sed -i.bak '/^<<<<<<< HEAD$/d; /^=======$/d; /^>>>>>>> origin\/master$/d' CHANGELOG.md && rm CHANGELOG.md.bak`
+   Then verify your entry is the topmost `## [X.Y.Z.W]` and master's
+   newer-than-yours entries (if any) sit below.
+4. **Run the 3-line audit above.** If it doesn't show your version on
+   all three lines, you missed a marker.
+5. **Run `bun install`** to refresh `bun.lock` against the resolved
+   `package.json`. Stage and commit if it changed.
+6. **Run `bun run typecheck`** before committing the merge.
+7. Only THEN run `git commit` for the merge.
+
+If the audit shows drift after step 4, do NOT proceed to step 5. Re-run
+steps 1-3 against the actual file content; you missed a marker or
+resolved one in the wrong direction.
+
+**Anti-pattern to avoid:** Resolving via `git checkout --ours package.json`
+and `git checkout --theirs scripts/test-shard.sh` mixed in the same
+commit. The selective directional resolution is fine, but on
+VERSION/package.json/CHANGELOG specifically, ALWAYS use the explicit
+`echo > VERSION` + sed-strip-markers pattern above. The directional
+checkout flags have bitten us when the conflict shape was unexpected
+(e.g. master stripped a section we expected to keep).
+
+### Pre-push gate (manual; tighten when you remember to)
+
+Before any `git push` of a merge commit, run the audit one more time:
+
+```bash
+echo "VERSION:     $(cat VERSION)"
+echo "package.json: $(node -e 'process.stdout.write(require("./package.json").version)')"
+grep -E "^## \[" CHANGELOG.md | head -1
+```
+
+If you've been editing the branch via `/ship` you can rely on Step 12's
+idempotency check. If you've been editing manually (merge resolution,
+conflict fix, version bump), the audit is the last line of defense
+before CI yells at you.
+
 ## Pre-ship requirements
 
 Before shipping (/ship) or reviewing (/review), always run the full test suite.
@@ -1615,7 +1699,7 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 | Trigger | Skill |
 |---------|-------|
 | User shares a link, article, tweet, or idea | `skills/idea-ingest/SKILL.md` |
-| "video", "PDF book", "YouTube", "screenshot", "summarize this book", "ingest this PDF", "process this book", "ingest it into my brain" | `skills/media-ingest/SKILL.md` |
+| "watch this video", "process this YouTube link", "ingest this PDF", "save this podcast", "process this book", "summarize this book", "PDF book", "ingest it into my brain", "what's in this screenshot", "check out this repo" | `skills/media-ingest/SKILL.md` |
 | Meeting transcript received | `skills/meeting-ingestion/SKILL.md` |
 | Generic "ingest this" (auto-routes to above) | `skills/ingest/SKILL.md` |
 
@@ -1696,23 +1780,15 @@ These apply to ALL brain-writing skills:
 
 | Trigger | Skill |
 |---------|-------|
-| "personalized version of this book", "mirror this book", "two-column book", "book to my life", "this book apply to me", "personalized version" | `skills/book-mirror/SKILL.md` |
-
-| "enrich this article", "enriching the article", "enrich the article", "enrich brain pages", "batch enrich", "enrich pass" | `skills/article-enrichment/SKILL.md` |
-
-| "strategic reading", "read this through the lens", "apply this to my problem", "what can I learn from this", "extract a playbook from this" | `skills/strategic-reading/SKILL.md` |
-
-| "concept synthesis", "synthesize my concepts", "intellectual map", "find patterns across my notes", "trace idea evolution", "canon vs riff" | `skills/concept-synthesis/SKILL.md` |
-
-| "perplexity research", "perplexity-research", "what's new about this", "current state of", "web research pass", "what changed about", "surface new developments" | `skills/perplexity-research/SKILL.md` |
-
-| "crawl my archive", "find gold in my archive", "archive crawler", "scan my dropbox", "mine my old files" | `skills/archive-crawler/SKILL.md` |
-
-| "verify this academic claim", "check this study", "academic verify", "validate citation", "Retraction Watch", "is this study real" | `skills/academic-verify/SKILL.md` |
-
-| "make pdf from brain", "brain pdf", "convert brain page to pdf", "page as pdf", "export brain page", "publish this page as pdf" | `skills/brain-pdf/SKILL.md` |
-
-| "voice note", "voice memo", "audio message", "audio note", "transcribe and file" | `skills/voice-note-ingest/SKILL.md` |
+| "personalized version of this book", "mirror this book", "two-column book analysis", "apply this book to my life", "how does this book apply to me" | `skills/book-mirror/SKILL.md` |
+| "enrich this article", "enrich brain pages", "batch enrich", "make brain pages useful" | `skills/article-enrichment/SKILL.md` |
+| "strategic reading", "read this through the lens of", "apply this to my problem", "what can I learn from this about", "extract a playbook from" | `skills/strategic-reading/SKILL.md` |
+| "concept synthesis", "synthesize my concepts", "find patterns across my notes", "build my intellectual map", "trace idea evolution" | `skills/concept-synthesis/SKILL.md` |
+| "perplexity research", "what's new about", "current state of", "web research", "what changed about" | `skills/perplexity-research/SKILL.md` |
+| "crawl my archive", "find gold in my archive", "archive crawler", "scan my dropbox for", "mine my old files for" | `skills/archive-crawler/SKILL.md` |
+| "verify this academic claim", "check this study", "academic verify", "validate citation", "is this study real" | `skills/academic-verify/SKILL.md` |
+| "make pdf from brain", "brain pdf", "convert brain page to pdf", "publish this page as pdf", "export brain page" | `skills/brain-pdf/SKILL.md` |
+| "voice note", "ingest this voice memo", "transcribe and file", "voice note ingest", "save this audio note" | `skills/voice-note-ingest/SKILL.md` |
 
 ---
 

package.json

@@ -1,6 +1,7 @@
 {
   "name": "gbrain",
-  "version": "0.31.4.1",
+
+  "version": "0.31.7",
   "description": "Postgres-native personal knowledge brain with hybrid RAG search",
   "type": "module",
   "main": "src/core/index.ts",

scripts/check-test-isolation.allowlist

@@ -43,6 +43,7 @@ test/init-migrate-only.test.ts
 test/integrations.test.ts
 test/mcp-eval-capture.test.ts
 test/migrate.test.ts
+test/migration-orchestrator-v0_31_0.test.ts
 test/migration-resume.test.ts
 test/migrations-v0_11_0.test.ts
 test/migrations-v0_13_1.test.ts

skills/RESOLVER.md

@@ -28,7 +28,7 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 | Trigger | Skill |
 |---------|-------|
 | User shares a link, article, tweet, or idea | `skills/idea-ingest/SKILL.md` |
-| "video", "PDF book", "YouTube", "screenshot", "summarize this book", "ingest this PDF", "process this book", "ingest it into my brain" | `skills/media-ingest/SKILL.md` |
+| "watch this video", "process this YouTube link", "ingest this PDF", "save this podcast", "process this book", "summarize this book", "PDF book", "ingest it into my brain", "what's in this screenshot", "check out this repo" | `skills/media-ingest/SKILL.md` |
 | Meeting transcript received | `skills/meeting-ingestion/SKILL.md` |
 | Generic "ingest this" (auto-routes to above) | `skills/ingest/SKILL.md` |
 
@@ -109,20 +109,13 @@ These apply to ALL brain-writing skills:
 
 | Trigger | Skill |
 |---------|-------|
-| "personalized version of this book", "mirror this book", "two-column book", "book to my life", "this book apply to me", "personalized version" | `skills/book-mirror/SKILL.md` |
+| "personalized version of this book", "mirror this book", "two-column book analysis", "apply this book to my life", "how does this book apply to me" | `skills/book-mirror/SKILL.md` |
+| "enrich this article", "enrich brain pages", "batch enrich", "make brain pages useful" | `skills/article-enrichment/SKILL.md` |
+| "strategic reading", "read this through the lens of", "apply this to my problem", "what can I learn from this about", "extract a playbook from" | `skills/strategic-reading/SKILL.md` |
+| "concept synthesis", "synthesize my concepts", "find patterns across my notes", "build my intellectual map", "trace idea evolution" | `skills/concept-synthesis/SKILL.md` |
+| "perplexity research", "what's new about", "current state of", "web research", "what changed about" | `skills/perplexity-research/SKILL.md` |
+| "crawl my archive", "find gold in my archive", "archive crawler", "scan my dropbox for", "mine my old files for" | `skills/archive-crawler/SKILL.md` |
+| "verify this academic claim", "check this study", "academic verify", "validate citation", "is this study real" | `skills/academic-verify/SKILL.md` |
+| "make pdf from brain", "brain pdf", "convert brain page to pdf", "publish this page as pdf", "export brain page" | `skills/brain-pdf/SKILL.md` |
+| "voice note", "ingest this voice memo", "transcribe and file", "voice note ingest", "save this audio note" | `skills/voice-note-ingest/SKILL.md` |
 
-| "enrich this article", "enriching the article", "enrich the article", "enrich brain pages", "batch enrich", "enrich pass" | `skills/article-enrichment/SKILL.md` |
-
-| "strategic reading", "read this through the lens", "apply this to my problem", "what can I learn from this", "extract a playbook from this" | `skills/strategic-reading/SKILL.md` |
-
-| "concept synthesis", "synthesize my concepts", "intellectual map", "find patterns across my notes", "trace idea evolution", "canon vs riff" | `skills/concept-synthesis/SKILL.md` |
-
-| "perplexity research", "perplexity-research", "what's new about this", "current state of", "web research pass", "what changed about", "surface new developments" | `skills/perplexity-research/SKILL.md` |
-
-| "crawl my archive", "find gold in my archive", "archive crawler", "scan my dropbox", "mine my old files" | `skills/archive-crawler/SKILL.md` |
-
-| "verify this academic claim", "check this study", "academic verify", "validate citation", "Retraction Watch", "is this study real" | `skills/academic-verify/SKILL.md` |
-
-| "make pdf from brain", "brain pdf", "convert brain page to pdf", "page as pdf", "export brain page", "publish this page as pdf" | `skills/brain-pdf/SKILL.md` |
-
-| "voice note", "voice memo", "audio message", "audio note", "transcribe and file" | `skills/voice-note-ingest/SKILL.md` |

skills/article-enrichment/routing-eval.jsonl

@@ -1,7 +1,9 @@
 // Routing eval fixtures for skills/article-enrichment. Each intent
 // includes at least one trigger string as substring.
-{"intent":"This article page is a wall of raw text — please enrich this article with quotes and insights","expected_skill":"article-enrichment"}
-{"intent":"Run a batch enrich pass on the unstructured articles in my brain","expected_skill":"article-enrichment"}
-{"intent":"Make brain pages useful by enriching the article dumps","expected_skill":"article-enrichment"}
-{"intent":"Please enrich brain pages that have raw content but no executive summary","expected_skill":"article-enrichment"}
-{"intent":"Enrich this article so it has verbatim quotes, key insights, and a why-it-matters section","expected_skill":"article-enrichment"}
+// `enrich` parent skill naturally co-fires (skills chain by design,
+// per RESOLVER.md preamble); ambiguous_with acknowledges that.
+{"intent":"This article page is a wall of raw text — please enrich this article with quotes and insights","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
+{"intent":"Run a batch enrich pass on the unstructured articles in my brain","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
+{"intent":"Make brain pages useful by enriching the article dumps","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
+{"intent":"Please enrich brain pages that have raw content but no executive summary","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}
+{"intent":"Enrich this article so it has verbatim quotes, key insights, and a why-it-matters section","expected_skill":"article-enrichment","ambiguous_with":["enrich"]}

src/commands/check-resolvable.ts

@@ -23,7 +23,7 @@ import {
   type ResolvableIssue,
   type AutoFixReport,
 } from '../core/check-resolvable.ts';
-import { autoDetectSkillsDir, AUTO_DETECT_HINT, type SkillsDirSource } from '../core/repo-root.ts';
+import { autoDetectSkillsDirReadOnly, AUTO_DETECT_HINT_READ_ONLY, type SkillsDirSource } from '../core/repo-root.ts';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -142,7 +142,7 @@ export function resolveSkillsDir(flags: Flags): {
     return { dir, error: null, message: null, source: 'explicit' };
   }
 
-  const detected = autoDetectSkillsDir();
+  const detected = autoDetectSkillsDirReadOnly();
   if (!detected.dir) {
     return {
       dir: null,
@@ -150,19 +150,21 @@ export function resolveSkillsDir(flags: Flags): {
       message:
         'Could not auto-detect skills/ with a RESOLVER.md or AGENTS.md.\n' +
         'Priority order:\n' +
-        AUTO_DETECT_HINT +
-        '\nFix: export OPENCLAW_WORKSPACE=<path> or pass --skills-dir <path>.',
+        AUTO_DETECT_HINT_READ_ONLY +
+        '\nFix: export GBRAIN_SKILLS_DIR=<path>, OPENCLAW_WORKSPACE=<path>, or pass --skills-dir <path>.',
       source: null,
     };
   }
 
   const sourceLabel = {
+    env_explicit: '$GBRAIN_SKILLS_DIR (explicit operator override)',
     repo_root: 'repo root skills/',
     openclaw_workspace_env: '$OPENCLAW_WORKSPACE/skills',
     openclaw_workspace_env_root: '$OPENCLAW_WORKSPACE (AGENTS.md at workspace root)',
     openclaw_workspace_home: '~/.openclaw/workspace/skills',
     openclaw_workspace_home_root: '~/.openclaw/workspace (AGENTS.md at workspace root)',
     cwd_skills: './skills',
+    install_path: 'gbrain install path (read-only fallback)',
   }[detected.source!]!;
 
   return {
@@ -280,6 +282,21 @@ export async function runCheckResolvable(args: string[]): Promise<void> {
 
   let autoFix: AutoFixReport | null = null;
   if (flags.fix) {
+    // SAFETY GATE (v0.31.7 follow-up to D5): refuse --fix when the skills
+    // dir came from the install-path fallback. autoFixDryViolations writes
+    // to SKILL.md files; running --fix from a directory with no resolver up
+    // the cwd tree would resolve to the bundled gbrain repo via the
+    // read-only install-path fallback and silently mutate it. Codex caught
+    // this leak in the v0.31.7 ship review (D6 lock).
+    if (source === 'install_path') {
+      process.stderr.write(
+        'gbrain check-resolvable --fix refused: skills dir resolved via install-path fallback (read-only).\n' +
+        'The --fix flag writes to SKILL.md files; running it against the bundled install\n' +
+        'tree would silently mutate gbrain itself. Set $GBRAIN_SKILLS_DIR, $OPENCLAW_WORKSPACE,\n' +
+        'or pass --skills-dir <path> to point at the workspace you actually want to fix.\n',
+      );
+      process.exit(1);
+    }
     autoFix = autoFixDryViolations(skillsDir, { dryRun: flags.dryRun });
   }
 

src/commands/doctor.ts

@@ -3,7 +3,7 @@ import * as db from '../core/db.ts';
 import { LATEST_VERSION, getIdleBlockers } from '../core/migrate.ts';
 import { checkResolvable } from '../core/check-resolvable.ts';
 import { autoFixDryViolations, type AutoFixReport, type FixOutcome } from '../core/dry-fix.ts';
-import { autoDetectSkillsDir } from '../core/repo-root.ts';
+import { autoDetectSkillsDirReadOnly } from '../core/repo-root.ts';
 import { loadCompletedMigrations } from '../core/preferences.ts';
 import { compareVersions } from './migrations/index.ts';
 import { createProgress, startHeartbeat, type ProgressReporter } from '../core/progress.ts';
@@ -295,16 +295,35 @@ export async function runDoctor(engine: BrainEngine | null, args: string[], dbSo
   // Use the same auto-detect as `check-resolvable` so doctor sees a
   // workspace/skills dir reachable via $OPENCLAW_WORKSPACE or
   // ~/.openclaw/workspace, not just a `skills/` walked up from cwd.
-  const detected = autoDetectSkillsDir();
+  // Read-only variant adds the install-path fallback so a hosted-CLI install
+  // run from `~` (e.g., `bun install -g github:garrytan/gbrain && cd ~ &&
+  // gbrain doctor`) can still find the bundled skills/ dir without warning.
+  const detected = autoDetectSkillsDirReadOnly();
   const skillsDir = detected.dir;
   if (skillsDir) {
 
     // --fix: run auto-repair BEFORE checkResolvable so the post-fix scan
     // reflects the new state. Auto-fix only targets DRY violations today;
     // other resolver issues are left to human repair.
+    //
+    // SAFETY GATE (v0.31.7 follow-up to D5): refuse --fix when the skills
+    // dir came from the install-path fallback. autoFixDryViolations writes
+    // to SKILL.md files; a user running `cd ~ && gbrain doctor --fix`
+    // without an explicit signal would have install_path resolve to the
+    // bundled gbrain repo and silently rewrite the install-tree skills.
+    // Codex caught this leak in the v0.31.7 ship review (D6 lock).
     if (doFix) {
-      autoFixReport = autoFixDryViolations(skillsDir, { dryRun });
-      printAutoFixReport(autoFixReport, dryRun, jsonOutput);
+      if (detected.source === 'install_path') {
+        process.stderr.write(
+          'gbrain doctor --fix refused: skills dir resolved via install-path fallback (read-only).\n' +
+          'The --fix flag writes to SKILL.md files; running it against the bundled install\n' +
+          'tree would silently mutate gbrain itself. Set $GBRAIN_SKILLS_DIR, $OPENCLAW_WORKSPACE,\n' +
+          'or pass --skills-dir <path> to point at the workspace you actually want to fix.\n',
+        );
+      } else {
+        autoFixReport = autoFixDryViolations(skillsDir, { dryRun });
+        printAutoFixReport(autoFixReport, dryRun, jsonOutput);
+      }
     }
 
     const report = checkResolvable(skillsDir);
@@ -930,18 +949,35 @@ export async function runDoctor(engine: BrainEngine | null, args: string[], dbSo
 
   // 9. Graph health (link + timeline coverage on entity pages).
   // dead_links removed in v0.10.1: ON DELETE CASCADE on link FKs makes it always 0.
+  //
+  // Skip when the brain has 0 entity pages (markdown-only wikis, journals,
+  // notes brains). The coverage formula divides by entity-page count, so it's
+  // structurally undefined when no entities exist — emitting WARN under that
+  // condition is a false positive. Closes #530.
   progress.heartbeat('graph_coverage');
   try {
     const health = await engine.getHealth();
+    const entityCount = (await engine.executeRaw<{ count: number }>(
+      "SELECT COUNT(*)::int AS count FROM pages WHERE type IN ('entity', 'person', 'company', 'organization')",
+    ))[0]?.count ?? 0;
+
     const linkPct = ((health.link_coverage ?? 0) * 100).toFixed(0);
     const timelinePct = ((health.timeline_coverage ?? 0) * 100).toFixed(0);
-    if ((health.link_coverage ?? 0) >= 0.5 && (health.timeline_coverage ?? 0) >= 0.5) {
+    if (entityCount === 0) {
+      // Markdown-only / journal / wiki brain — no entity pages to compute
+      // coverage against. Coverage formula is structurally inapplicable.
+      checks.push({
+        name: 'graph_coverage',
+        status: 'ok',
+        message: 'No entity pages — graph_coverage not applicable (markdown-only brain)',
+      });
+    } else if ((health.link_coverage ?? 0) >= 0.5 && (health.timeline_coverage ?? 0) >= 0.5) {
       checks.push({ name: 'graph_coverage', status: 'ok', message: `Entity link coverage ${linkPct}%, timeline ${timelinePct}%` });
     } else {
       checks.push({
         name: 'graph_coverage',
         status: 'warn',
-        message: `Entity link coverage ${linkPct}%, timeline ${timelinePct}%. Run: gbrain extract links && gbrain extract timeline`,
+        message: `Entity link coverage ${linkPct}%, timeline ${timelinePct}% (${entityCount} entity pages). Run: gbrain extract all`,
       });
     }
 

src/commands/routing-eval.ts

@@ -14,7 +14,7 @@
  * layer only. A future release will implement the tie-break layer.
  */
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync } from 'fs';
 import { resolve as resolvePath, isAbsolute } from 'path';
 
 import {
@@ -25,8 +25,8 @@ import {
   type RoutingReport,
   type FixtureLintIssue,
 } from '../core/routing-eval.ts';
-import { findResolverFile, RESOLVER_FILENAMES_LABEL } from '../core/resolver-filenames.ts';
-import { autoDetectSkillsDir } from '../core/repo-root.ts';
+import { findAllResolverFiles, RESOLVER_FILENAMES_LABEL } from '../core/resolver-filenames.ts';
+import { autoDetectSkillsDirReadOnly } from '../core/repo-root.ts';
 import { join } from 'path';
 
 interface Flags {
@@ -93,7 +93,7 @@ function resolveSkillsDir(
       : resolvePath(process.cwd(), flags.skillsDir);
     return { dir, source: 'explicit', error: null, message: null };
   }
-  const detected = autoDetectSkillsDir();
+  const detected = autoDetectSkillsDirReadOnly();
   if (!detected.dir) {
     return {
       dir: null,
@@ -140,8 +140,17 @@ export async function runRoutingEvalCli(args: string[]): Promise<void> {
   }
 
   const skillsDir = dir!;
-  const resolverFile =
-    findResolverFile(skillsDir) ?? findResolverFile(join(skillsDir, '..'));
+  // v0.31.7 D6 fix: collect entries from ALL resolver files across both the
+  // skills directory and its parent, matching the multi-file merge behavior
+  // in src/core/check-resolvable.ts. Without this, OpenClaw deployments
+  // (thin skills/RESOLVER.md + rich ../AGENTS.md) would have routing-eval
+  // see only the thin file's triggers and report false misses/ambiguity
+  // while doctor and check-resolvable see the full merged index.
+  const allResolverPaths = [
+    ...findAllResolverFiles(skillsDir),
+    ...findAllResolverFiles(join(skillsDir, '..')),
+  ];
+  const resolverFile = allResolverPaths[0] ?? null;
   if (!resolverFile) {
     const env: RoutingEvalEnvelope = {
       ok: false,
@@ -158,7 +167,11 @@ export async function runRoutingEvalCli(args: string[]): Promise<void> {
     process.exit(2);
   }
 
-  const resolverContent = readFileSync(resolverFile, 'utf-8');
+  // Build combined resolverContent across all matched files (RESOLVER.md +
+  // ../AGENTS.md, etc.), so indexResolverTriggers sees the union.
+  const resolverContent = allResolverPaths
+    .map(p => readFileSync(p, 'utf-8'))
+    .join('\n\n');
   const index = indexResolverTriggers(resolverContent);
 
   const loaded = loadRoutingFixtures(skillsDir);

src/core/check-resolvable.ts

@@ -12,7 +12,7 @@
 
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, relative } from 'path';
-import { findResolverFile, RESOLVER_FILENAMES_LABEL } from './resolver-filenames.ts';
+import { findResolverFile, findAllResolverFiles, RESOLVER_FILENAMES_LABEL } from './resolver-filenames.ts';
 import { loadOrDeriveManifest } from './skill-manifest.ts';
 import {
   indexResolverTriggers,
@@ -251,10 +251,20 @@ export function checkResolvable(skillsDir: string): ResolvableReport {
   // Load inputs
   // Accept RESOLVER.md or AGENTS.md (W1). Also check one level up: the
   // reference OpenClaw deployment layout places AGENTS.md at the
-  // workspace root, with skills/ below. We try skills dir first
-  // (gbrain-native), then its parent (OpenClaw-native).
-  const resolverPath =
-    findResolverFile(skillsDir) ?? findResolverFile(join(skillsDir, '..'));
+  // workspace root, with skills/ below.
+  //
+  // Merge strategy (D-CX-14): collect entries from ALL resolver files
+  // across both directories (skills dir + parent). This handles the
+  // common OpenClaw layout where a skillpack installs a thin
+  // skills/RESOLVER.md while the real dispatcher lives in ../AGENTS.md.
+  // Entries are deduped by skillPath (first occurrence wins).
+  const allResolverPaths = [
+    ...findAllResolverFiles(skillsDir),
+    ...findAllResolverFiles(join(skillsDir, '..')),
+  ];
+
+  // Primary resolver: first found (for error messages and --fix targets)
+  const resolverPath = allResolverPaths[0] ?? null;
   if (!resolverPath) {
     const suggested = join(skillsDir, 'RESOLVER.md');
     const missingIssue: ResolvableIssue = {
@@ -274,8 +284,22 @@ export function checkResolvable(skillsDir: string): ResolvableReport {
     };
   }
 
-  const resolverContent = readFileSync(resolverPath, 'utf-8');
-  const entries = parseResolverEntries(resolverContent);
+  // Merge entries from all resolver files, dedup by skillPath.
+  // Also build a combined resolverContent for routing-eval (Check 5).
+  const seenSkillPaths = new Set<string>();
+  const entries: ResolverEntry[] = [];
+  const resolverContentParts: string[] = [];
+  for (const rPath of allResolverPaths) {
+    const content = readFileSync(rPath, 'utf-8');
+    resolverContentParts.push(content);
+    for (const entry of parseResolverEntries(content)) {
+      if (!seenSkillPaths.has(entry.skillPath)) {
+        seenSkillPaths.add(entry.skillPath);
+        entries.push(entry);
+      }
+    }
+  }
+  const resolverContent = resolverContentParts.join('\n\n');
   const { skills: manifest } = loadOrDeriveManifest(skillsDir);
 
   // Build lookup sets
@@ -306,7 +330,7 @@ export function checkResolvable(skillsDir: string): ResolvableReport {
           type: 'unreachable',
           severity: 'error',
           skill: skill.name,
-          message: `Skill '${skill.name}' is in manifest but has no trigger row in RESOLVER.md`,
+          message: `Skill '${skill.name}' is in manifest but has no trigger row in ${RESOLVER_FILENAMES_LABEL}`,
           action: `Add a trigger row for 'skills/${skill.path}' in RESOLVER.md under ${section}`,
           fix: {
             type: 'add_trigger',

src/core/link-extraction.ts

@@ -2,8 +2,7 @@
  * Shared link/timeline extraction utilities.
  *
  * Used by:
- *   - src/commands/link-extract.ts        (batch DB extraction)
- *   - src/commands/timeline-extract.ts    (batch DB extraction)
+ *   - src/commands/extract.ts             (batch DB + FS extraction — `gbrain extract links|timeline|all`)
  *   - src/commands/backlinks.ts           (filesystem walk, legacy)
  *   - src/core/operations.ts put_page     (auto-link post-hook)
  *

src/core/repo-root.ts

@@ -1,4 +1,5 @@
 import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { isAbsolute, join, resolve as resolvePath } from 'path';
 import { RESOLVER_FILENAMES, hasResolverFile } from './resolver-filenames.ts';
 
@@ -24,7 +25,7 @@ export function findRepoRoot(startDir: string = process.cwd()): string | null {
 
 /**
  * Where auto-detect found the skills directory.
- *   - `explicit`                    — user passed --skills-dir / equivalent
+ *   - `env_explicit`                 — $GBRAIN_SKILLS_DIR (operator override; v0.31.7)
  *   - `openclaw_workspace_env`       — $OPENCLAW_WORKSPACE/skills
  *   - `openclaw_workspace_env_root`  — $OPENCLAW_WORKSPACE/ (AGENTS.md at
  *                                      workspace root; skills in subdir)
@@ -32,14 +33,18 @@ export function findRepoRoot(startDir: string = process.cwd()): string | null {
  *   - `openclaw_workspace_home_root` — ~/.openclaw/workspace (root AGENTS.md)
  *   - `repo_root`                    — walked up from cwd, found gbrain repo
  *   - `cwd_skills`                   — ./skills fallback
+ *   - `install_path`                 — walked up from this module's install
+ *                                      path; READ-ONLY callers only (v0.31.7)
  */
 export type SkillsDirSource =
+  | 'env_explicit'
   | 'openclaw_workspace_env'
   | 'openclaw_workspace_env_root'
   | 'openclaw_workspace_home'
   | 'openclaw_workspace_home_root'
   | 'repo_root'
-  | 'cwd_skills';
+  | 'cwd_skills'
+  | 'install_path';
 
 export interface SkillsDirDetection {
   dir: string | null;
@@ -76,24 +81,50 @@ function resolveWorkspaceSkillsDir(
 }
 
 /**
- * Auto-detect the skills directory. Priority (D-CX-4, post-codex-review):
+ * Auto-detect the skills directory. Priority (v0.31.7 read+write-safe order):
+ *   0. $GBRAIN_SKILLS_DIR explicit operator override (any caller)
  *   1. $OPENCLAW_WORKSPACE when explicitly set (env > repo-root walk)
  *   2. ~/.openclaw/workspace/ (user's default OpenClaw deployment)
  *   3. findRepoRoot() walk from cwd (gbrain's own repo)
  *   4. ./skills fallback (dev scratch, fixtures)
  *
+ * Tier 0 ($GBRAIN_SKILLS_DIR) is safe for both read and write paths because
+ * the operator explicitly set the variable — opt-in retargeting is fine. The
+ * silent retargeting risk that motivates `autoDetectSkillsDirReadOnly` is
+ * about implicit fallback to install-path when no explicit signal is set.
+ *
  * The prior order put `findRepoRoot` first, which meant
  * `export OPENCLAW_WORKSPACE=...; gbrain check-resolvable` run from
  * inside the gbrain repo silently shadowed the env var by walking up
  * to gbrain's own skills/. Explicit env should win. Unset env → behavior
  * is unchanged from before.
  *
+ * Write-path callers (skillpack install, skillify scaffold,
+ * post-install-advisory) MUST use this function, not the read-only variant —
+ * a write-path install-path fallback would let `gbrain skillpack install`
+ * from `~` silently target the bundled gbrain repo's skills/ instead of the
+ * user's workspace.
+ *
  * `startDir` + `env` params keep tests hermetic.
  */
 export function autoDetectSkillsDir(
   startDir: string = process.cwd(),
   env: NodeJS.ProcessEnv = process.env,
 ): SkillsDirDetection {
+  // 0. $GBRAIN_SKILLS_DIR explicit operator override. Safe for all callers
+  //    because the operator explicitly set the env var. Does NOT support the
+  //    `workspace-root with AGENTS.md + skills/ sibling` shape — operator who
+  //    wants that should point the env var at the skills/ dir directly.
+  if (env.GBRAIN_SKILLS_DIR) {
+    const explicit = isAbsolute(env.GBRAIN_SKILLS_DIR)
+      ? env.GBRAIN_SKILLS_DIR
+      : resolvePath(startDir, env.GBRAIN_SKILLS_DIR);
+    if (hasResolverFile(explicit)) {
+      return { dir: explicit, source: 'env_explicit' };
+    }
+    // Fall through — invalid env override doesn't crash, lets lower tiers try.
+  }
+
   // 1. $OPENCLAW_WORKSPACE wins when explicitly set.
   if (env.OPENCLAW_WORKSPACE) {
     const workspace = isAbsolute(env.OPENCLAW_WORKSPACE)
@@ -140,6 +171,53 @@ function isGbrainRepoRoot(dir: string): boolean {
   );
 }
 
+/**
+ * Read-only skills-dir detection (v0.31.7). Wraps `autoDetectSkillsDir` and
+ * adds an install-path fallback when the primary detection returns null —
+ * walks up from this module's install location to find a gbrain repo root,
+ * gated by `isGbrainRepoRoot` to avoid false-positive on unrelated repos.
+ *
+ * Use this from READ-ONLY callers only: `gbrain doctor`,
+ * `gbrain check-resolvable`, `gbrain routing-eval`. Never from write paths.
+ *
+ * Why a separate function? `autoDetectSkillsDir` is shared with write paths
+ * (`skillpack install`, `skillify scaffold`, `post-install-advisory`).
+ * Adding the install-path fallback to the shared function would let
+ * `gbrain skillpack install` from `~` silently target the bundled gbrain
+ * repo's skills/ instead of the user's actual workspace — a quiet data-flow
+ * regression. Read-only callers don't write anything to the resolved path,
+ * so the install-path fallback is safe for them.
+ *
+ * Closes the install-path footgun for hosted-CLI installs (`bun install -g
+ * github:garrytan/gbrain && cd ~ && gbrain doctor`) without expanding the
+ * blast radius to write-path callers.
+ */
+export function autoDetectSkillsDirReadOnly(
+  startDir: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): SkillsDirDetection {
+  const primary = autoDetectSkillsDir(startDir, env);
+  if (primary.dir) return primary;
+
+  // Tier-5 install-path fallback: walk up from this module's install
+  // location. Gate with isGbrainRepoRoot so we don't false-positive when
+  // the install path lives inside an unrelated repo (e.g., a monorepo
+  // that vendored gbrain in a subdir).
+  try {
+    const moduleDir = fileURLToPath(import.meta.url);
+    const installRoot = findRepoRoot(moduleDir);
+    if (installRoot && isGbrainRepoRoot(installRoot)) {
+      return { dir: join(installRoot, 'skills'), source: 'install_path' };
+    }
+  } catch {
+    // fileURLToPath can throw on malformed import.meta.url (rare; some
+    // bundlers/runtimes). Fall through to the null detection — better to
+    // refuse the fallback than to fabricate a path.
+  }
+
+  return primary; // null detection, source: null
+}
+
 /**
  * Human-readable summary of the resolver-file search paths, for error
  * messages when auto-detect fails. Mirrors the priority order used by
@@ -147,8 +225,19 @@ function isGbrainRepoRoot(dir: string): boolean {
  */
 export const AUTO_DETECT_HINT = [
   `  1. --skills-dir flag`,
-  `  2. $OPENCLAW_WORKSPACE/{skills/,}{${RESOLVER_FILENAMES.join(',')}}`,
-  `  3. ~/.openclaw/workspace/{skills/,}{${RESOLVER_FILENAMES.join(',')}}`,
-  `  4. repo root with skills/${RESOLVER_FILENAMES.join(' or skills/')}`,
-  `  5. ./skills/${RESOLVER_FILENAMES.join(' or ./skills/')}`,
+  `  2. $GBRAIN_SKILLS_DIR (explicit operator override)`,
+  `  3. $OPENCLAW_WORKSPACE/{skills/,}{${RESOLVER_FILENAMES.join(',')}}`,
+  `  4. ~/.openclaw/workspace/{skills/,}{${RESOLVER_FILENAMES.join(',')}}`,
+  `  5. repo root with skills/${RESOLVER_FILENAMES.join(' or skills/')}`,
+  `  6. ./skills/${RESOLVER_FILENAMES.join(' or ./skills/')}`,
+].join('\n');
+
+/**
+ * Read-only auto-detect hint. Includes the install-path fallback that
+ * `autoDetectSkillsDirReadOnly` adds for `gbrain doctor` /
+ * `gbrain check-resolvable` / `gbrain routing-eval`.
+ */
+export const AUTO_DETECT_HINT_READ_ONLY = [
+  AUTO_DETECT_HINT,
+  `  7. (read-only) walk up from gbrain's install path`,
 ].join('\n');

src/core/resolver-filenames.ts

@@ -32,6 +32,22 @@ export function findResolverFile(dir: string): string | null {
   return null;
 }
 
+/**
+ * Return ALL existing resolver files in `dir`.
+ * OpenClaw deployments often have both skills/RESOLVER.md (from skillpack)
+ * and ../AGENTS.md (workspace root, the real dispatcher). Returning all
+ * files lets callers merge entries instead of silently ignoring the richer
+ * file.
+ */
+export function findAllResolverFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const name of RESOLVER_FILENAMES) {
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) results.push(candidate);
+  }
+  return results;
+}
+
 /** True iff `dir` contains at least one recognized resolver file. */
 export function hasResolverFile(dir: string): boolean {
   return findResolverFile(dir) !== null;

test/check-resolvable-cli.test.ts

@@ -138,17 +138,25 @@ describe('check-resolvable — unit: resolveSkillsDir', () => {
     expect(r.source).toBe('explicit');
   });
 
-  it('REGRESSION-GATE: returns no_skills_dir error when no --skills-dir and findRepoRoot fails', () => {
-    // Temporarily chdir to a guaranteed-empty tmpdir. findRepoRoot will walk
-    // up and fail to find skills/RESOLVER.md.
+  it('v0.31.7: empty cwd falls back to install-path (finds bundled skills/)', () => {
+    // Temporarily chdir to a guaranteed-empty tmpdir. findRepoRoot from cwd
+    // walks up and fails — but autoDetectSkillsDirReadOnly's tier-5
+    // install-path fallback then walks up from the gbrain module's own
+    // location and finds the bundled skills/ dir. This is the v0.31.7
+    // capability: doctor and check-resolvable work from anywhere.
+    //
+    // To test the underlying no_skills_dir error path, see the unit tests
+    // in test/repo-root.test.ts that drive autoDetectSkillsDirReadOnly
+    // with mocked env to suppress the install-path success.
     const empty = mkdtempSync(join(tmpdir(), 'empty-for-resolve-'));
     const original = process.cwd();
     try {
       process.chdir(empty);
       const r = resolveSkillsDir({ help: false, json: false, fix: false, dryRun: false, verbose: false, strict: false, skillsDir: null });
-      expect(r.error).toBe('no_skills_dir');
-      expect(r.dir).toBeNull();
-      expect(typeof r.message).toBe('string');
+      // Install-path fallback succeeds when test runs inside the gbrain repo.
+      expect(r.error).toBeNull();
+      expect(r.dir).toMatch(/\/skills$/);
+      expect(r.source).toBe('install_path');
     } finally {
       process.chdir(original);
       rmSync(empty, { recursive: true, force: true });
@@ -358,4 +366,27 @@ describe('gbrain check-resolvable CLI — integration', () => {
     expect(r.stdout).toContain('Auto-detected skills directory');
     expect(r.stdout).toContain('/skills');
   });
+
+  // v0.31.7 D6 regression guard: --fix must refuse install-path fallback.
+  // Without this gate, `cd ~ && gbrain check-resolvable --fix` would silently
+  // mutate SKILL.md files in the bundled gbrain repo via autoFixDryViolations.
+  // Codex caught this leak in the v0.31.7 ship review.
+  it('v0.31.7 D6: --fix refuses when source is install_path', () => {
+    // Run from a guaranteed-empty tempdir so the install-path fallback fires.
+    const empty = mkdtempSync(join(tmpdir(), 'cr-fix-installpath-'));
+    try {
+      // Pass --fix; expect refusal exit + clear error message.
+      const r = spawnSync('bun', ['run', CLI, 'check-resolvable', '--fix'], {
+        cwd: empty,
+        env: { ...process.env, OPENCLAW_WORKSPACE: '', GBRAIN_SKILLS_DIR: '' },
+        encoding: 'utf-8',
+      });
+      expect(r.status).toBe(1);
+      expect(r.stderr).toContain('install-path fallback');
+      expect(r.stderr).toContain('refused');
+      expect(r.stderr).toMatch(/GBRAIN_SKILLS_DIR|OPENCLAW_WORKSPACE|--skills-dir/);
+    } finally {
+      rmSync(empty, { recursive: true, force: true });
+    }
+  });
 });

test/doctor.test.ts

@@ -203,6 +203,23 @@ describe('doctor command', () => {
     expect(block).toContain('--force-retry 35');
   });
 
+  // v0.31.7 IRON-RULE regression test for #376 + #536.
+  // The graph_coverage WARN message used to suggest stale verbs (`gbrain
+  // link-extract` / `gbrain timeline-extract`) that were removed in v0.16
+  // when extraction was consolidated into `gbrain extract <links|timeline|all>`.
+  // PR #376 (FUSED-ID) flagged the stale hint; PR #536 (mayazbay) replaced it
+  // with the canonical `gbrain extract all`. Pin the user-facing copy so a
+  // future edit can't silently re-regress to a stale verb.
+  test('graph_coverage hint uses canonical `gbrain extract all`, not removed verbs', async () => {
+    const fs = await import('fs');
+    const src = fs.readFileSync('src/commands/doctor.ts', 'utf8');
+    // Canonical form (post-v0.16 single-verb consolidation).
+    expect(src).toContain('Run: gbrain extract all');
+    // Stale verb names removed in v0.16 must not return.
+    expect(src).not.toContain('gbrain link-extract');
+    expect(src).not.toContain('gbrain timeline-extract');
+  });
+
   // v0.32 — takes_weight_grid pure-helper export.
   // Codex review #7 demanded the check be extracted as a pure function so
   // tests target it directly with stubbed engines instead of running the

test/repo-root.test.ts

@@ -2,7 +2,13 @@ import { describe, it, expect, afterEach } from 'bun:test';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
-import { autoDetectSkillsDir, findRepoRoot } from '../src/core/repo-root.ts';
+import {
+  autoDetectSkillsDir,
+  autoDetectSkillsDirReadOnly,
+  findRepoRoot,
+  AUTO_DETECT_HINT,
+  AUTO_DETECT_HINT_READ_ONLY,
+} from '../src/core/repo-root.ts';
 
 describe('findRepoRoot', () => {
   const created: string[] = [];
@@ -159,4 +165,113 @@ describe('findRepoRoot', () => {
     // and RESOLVER.md takes precedence inside resolveWorkspaceSkillsDir.
     expect(found.source).toBe('openclaw_workspace_env');
   });
+
+  // -----------------------------------------------------------------------
+  // v0.31.7 #128 adaptation: tier-0 GBRAIN_SKILLS_DIR + read-only
+  // install-path fallback. Locked in eng-review D3 + D5.
+  // -----------------------------------------------------------------------
+
+  it('v0.31.7 D3-1: tier-0 $GBRAIN_SKILLS_DIR valid path returns env_explicit source', () => {
+    const cwd = scratch();
+    const explicit = scratch();
+    seedSkillsDir(explicit);
+    const found = autoDetectSkillsDir(cwd, { GBRAIN_SKILLS_DIR: explicit });
+    expect(found.dir).toBe(explicit);
+    expect(found.source).toBe('env_explicit');
+  });
+
+  it('v0.31.7 D3-2: tier-0 invalid path falls through to lower tiers', () => {
+    // GBRAIN_SKILLS_DIR points to a directory with no resolver file. Must
+    // not crash; must continue to the next tier (OPENCLAW_WORKSPACE here).
+    const cwd = scratch();
+    const invalid = scratch(); // no RESOLVER.md / AGENTS.md inside
+    const workspace = scratch();
+    seedSkillsDir(join(workspace, 'skills'));
+    const found = autoDetectSkillsDir(cwd, {
+      GBRAIN_SKILLS_DIR: invalid,
+      OPENCLAW_WORKSPACE: workspace,
+    });
+    expect(found.dir).toBe(join(workspace, 'skills'));
+    expect(found.source).toBe('openclaw_workspace_env');
+  });
+
+  it('v0.31.7 D3-3: tier-0 wins over $OPENCLAW_WORKSPACE precedence', () => {
+    // Both env vars set. Tier-0 (explicit operator override) MUST win.
+    const cwd = scratch();
+    const explicit = scratch();
+    seedSkillsDir(explicit);
+    const workspace = scratch();
+    seedSkillsDir(join(workspace, 'skills'));
+    const found = autoDetectSkillsDir(cwd, {
+      GBRAIN_SKILLS_DIR: explicit,
+      OPENCLAW_WORKSPACE: workspace,
+    });
+    expect(found.dir).toBe(explicit);
+    expect(found.source).toBe('env_explicit');
+  });
+
+  it('v0.31.7 D3-4: autoDetectSkillsDirReadOnly install-path walk finds bundled skills', () => {
+    // When primary detection returns null (no env, no openclaw, no repo
+    // root walk-up, no ./skills), the read-only variant walks up from
+    // import.meta.url (the gbrain module's install path) and finds the
+    // bundled skills/. This test runs from a tempdir cwd with no env vars
+    // set; the only path that can succeed is the install-path fallback.
+    const cwd = scratch();
+    const found = autoDetectSkillsDirReadOnly(cwd, {});
+    // We're inside the gbrain repo when running the test, so the install
+    // path resolves to the repo's skills dir.
+    expect(found.dir).not.toBeNull();
+    expect(found.source).toBe('install_path');
+    expect(found.dir).toMatch(/\/skills$/);
+  });
+
+  it('v0.31.7 D3-5: autoDetectSkillsDirReadOnly returns same primary detection on success', () => {
+    // When primary detection succeeds, the read-only variant must return
+    // the SAME result — no behavior drift, install-path is fallback only.
+    const cwd = scratch();
+    const workspace = scratch();
+    seedSkillsDir(join(workspace, 'skills'));
+    const env = { OPENCLAW_WORKSPACE: workspace };
+    const primary = autoDetectSkillsDir(cwd, env);
+    const readOnly = autoDetectSkillsDirReadOnly(cwd, env);
+    expect(readOnly.dir).toBe(primary.dir);
+    expect(readOnly.source).toBe(primary.source);
+    // Specifically NOT install_path — primary succeeded so fallback never fires.
+    expect(readOnly.source).toBe('openclaw_workspace_env');
+  });
+
+  it('v0.31.7 D3-6: AUTO_DETECT_HINT documents tier-0 GBRAIN_SKILLS_DIR', () => {
+    // Hint string is what users see when auto-detect fails — must list the
+    // tier-0 explicit override so they know to set it.
+    expect(AUTO_DETECT_HINT).toContain('$GBRAIN_SKILLS_DIR');
+    expect(AUTO_DETECT_HINT).toContain('explicit operator override');
+  });
+
+  it('v0.31.7 D3-7: AUTO_DETECT_HINT_READ_ONLY adds install-path tier', () => {
+    // Read-only hint must mention the install-path fallback so doctor's
+    // user can understand what gbrain found and where.
+    expect(AUTO_DETECT_HINT_READ_ONLY).toContain('install path');
+    expect(AUTO_DETECT_HINT_READ_ONLY).toContain('read-only');
+    // And must include everything from the base hint.
+    expect(AUTO_DETECT_HINT_READ_ONLY).toContain('$GBRAIN_SKILLS_DIR');
+    expect(AUTO_DETECT_HINT_READ_ONLY).toContain('$OPENCLAW_WORKSPACE');
+  });
+
+  it('v0.31.7 D5 regression guard: autoDetectSkillsDir does NOT install-path-fallback', () => {
+    // CRITICAL: this test pins the read-path/write-path split. The shared
+    // autoDetectSkillsDir is used by write-path callers (skillpack install,
+    // skillify scaffold, post-install-advisory). If a future edit adds the
+    // install-path fallback to the SHARED function, those write-path
+    // callers running from `~` would silently retarget the bundled gbrain
+    // repo's skills/ instead of the user's actual workspace — a quiet
+    // data-flow regression. This test asserts the shared function returns
+    // null (not an install_path source) when no env or repo-root signal
+    // is present, even though the install-path fallback would succeed.
+    const cwd = scratch(); // empty tempdir; no resolver anywhere up
+    const found = autoDetectSkillsDir(cwd, {});
+    // Either null (no skills dir found) or repo_root if test runs inside
+    // the gbrain repo. In either case, NEVER 'install_path' on the shared
+    // function — that variant is reserved for autoDetectSkillsDirReadOnly.
+    expect(found.source).not.toBe('install_path');
+  });
 });

test/resolver-merge.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Verify: check-resolvable merges entries from all resolver files.
+ *
+ * The common OpenClaw layout has:
+ *   workspace/AGENTS.md       — the real dispatcher (200+ entries)
+ *   workspace/skills/RESOLVER.md — thin skillpack-installed subset (~40 entries)
+ *
+ * Before this fix, RESOLVER.md won by first-match policy, so 160+ skills
+ * showed as "unreachable" even though AGENTS.md had routing for them.
+ *
+ * After: entries from both files are merged (deduped by skillPath).
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { checkResolvable, parseResolverEntries } from '../src/core/check-resolvable.ts';
+import { findAllResolverFiles } from '../src/core/resolver-filenames.ts';
+
+// ---------------------------------------------------------------------------
+// findAllResolverFiles
+// ---------------------------------------------------------------------------
+
+describe('findAllResolverFiles', () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'resolver-merge-'));
+  });
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns empty when no resolver files exist', () => {
+    expect(findAllResolverFiles(dir)).toEqual([]);
+  });
+
+  it('returns RESOLVER.md when only it exists', () => {
+    writeFileSync(join(dir, 'RESOLVER.md'), '# test');
+    const files = findAllResolverFiles(dir);
+    expect(files).toHaveLength(1);
+    expect(files[0]).toEndWith('RESOLVER.md');
+    rmSync(join(dir, 'RESOLVER.md'));
+  });
+
+  it('returns AGENTS.md when only it exists', () => {
+    writeFileSync(join(dir, 'AGENTS.md'), '# test');
+    const files = findAllResolverFiles(dir);
+    expect(files).toHaveLength(1);
+    expect(files[0]).toEndWith('AGENTS.md');
+    rmSync(join(dir, 'AGENTS.md'));
+  });
+
+  it('returns both when both exist (RESOLVER.md first)', () => {
+    writeFileSync(join(dir, 'RESOLVER.md'), '# resolver');
+    writeFileSync(join(dir, 'AGENTS.md'), '# agents');
+    const files = findAllResolverFiles(dir);
+    expect(files).toHaveLength(2);
+    expect(files[0]).toEndWith('RESOLVER.md');
+    expect(files[1]).toEndWith('AGENTS.md');
+    rmSync(join(dir, 'RESOLVER.md'));
+    rmSync(join(dir, 'AGENTS.md'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Merge behavior in checkResolvable
+// ---------------------------------------------------------------------------
+
+describe('checkResolvable merges resolver files', () => {
+  let workspace: string;
+  let skillsDir: string;
+
+  beforeAll(() => {
+    workspace = mkdtempSync(join(tmpdir(), 'resolver-merge-e2e-'));
+    skillsDir = join(workspace, 'skills');
+    mkdirSync(skillsDir, { recursive: true });
+
+    // Create 3 skills on disk
+    for (const name of ['alpha', 'beta', 'gamma']) {
+      const skillDir = join(skillsDir, name);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(join(skillDir, 'SKILL.md'), `---\nname: ${name}\ntriggers:\n  - "${name} trigger"\n---\n# ${name}\n`);
+    }
+  });
+
+  afterAll(() => {
+    rmSync(workspace, { recursive: true, force: true });
+  });
+
+  it('with only skills/RESOLVER.md covering 1 of 3 → 2 unreachable', () => {
+    writeFileSync(join(skillsDir, 'RESOLVER.md'), `# Resolver\n\n| Trigger | Skill |\n|---|---|\n| do alpha | \`skills/alpha/SKILL.md\` |\n`);
+    const report = checkResolvable(skillsDir);
+    expect(report.summary.reachable).toBe(1);
+    expect(report.summary.unreachable).toBe(2);
+    rmSync(join(skillsDir, 'RESOLVER.md'));
+  });
+
+  it('with skills/RESOLVER.md (1 skill) + ../AGENTS.md (2 more) → all 3 reachable', () => {
+    // Thin RESOLVER.md in skills dir (e.g. from skillpack)
+    writeFileSync(join(skillsDir, 'RESOLVER.md'),
+      `# Resolver\n\n| Trigger | Skill |\n|---|---|\n| do alpha | \`skills/alpha/SKILL.md\` |\n`);
+
+    // Rich AGENTS.md at workspace root (OpenClaw convention)
+    writeFileSync(join(workspace, 'AGENTS.md'),
+      `# AGENTS.md\n\n## Skills\n\n| Trigger | Skill |\n|---|---|\n| do beta | \`skills/beta/SKILL.md\` |\n| do gamma | \`skills/gamma/SKILL.md\` |\n`);
+
+    const report = checkResolvable(skillsDir);
+    expect(report.summary.reachable).toBe(3);
+    expect(report.summary.unreachable).toBe(0);
+    expect(report.ok).toBe(true);
+
+    rmSync(join(skillsDir, 'RESOLVER.md'));
+    rmSync(join(workspace, 'AGENTS.md'));
+  });
+
+  it('deduplicates overlapping entries (first occurrence wins)', () => {
+    // Both files reference alpha
+    writeFileSync(join(skillsDir, 'RESOLVER.md'),
+      `# Resolver\n\n| Trigger | Skill |\n|---|---|\n| do alpha | \`skills/alpha/SKILL.md\` |\n`);
+    writeFileSync(join(workspace, 'AGENTS.md'),
+      `# AGENTS\n\n| Trigger | Skill |\n|---|---|\n| alpha thing | \`skills/alpha/SKILL.md\` |\n| do beta | \`skills/beta/SKILL.md\` |\n| do gamma | \`skills/gamma/SKILL.md\` |\n`);
+
+    const report = checkResolvable(skillsDir);
+    expect(report.summary.reachable).toBe(3);
+    expect(report.summary.unreachable).toBe(0);
+
+    rmSync(join(skillsDir, 'RESOLVER.md'));
+    rmSync(join(workspace, 'AGENTS.md'));
+  });
+
+  it('AGENTS.md at workspace root works alone (no RESOLVER.md)', () => {
+    writeFileSync(join(workspace, 'AGENTS.md'),
+      `# AGENTS\n\n| Trigger | Skill |\n|---|---|\n| a | \`skills/alpha/SKILL.md\` |\n| b | \`skills/beta/SKILL.md\` |\n| c | \`skills/gamma/SKILL.md\` |\n`);
+
+    const report = checkResolvable(skillsDir);
+    expect(report.summary.reachable).toBe(3);
+    expect(report.summary.unreachable).toBe(0);
+
+    rmSync(join(workspace, 'AGENTS.md'));
+  });
+});