Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
W4: fix cheap-tier verify and semgrep (key-files split, llms budget, isolation, nosemgrep on fixed-name probes)
garrytane79fe37bceba
diff --git a/docs/architecture/KEY_FILES.md b/docs/architecture/KEY_FILES.mdindex 69a1ff129d..c3b141e196 100644--- a/docs/architecture/KEY_FILES.md+++ b/docs/architecture/KEY_FILES.md@@ -12,7 +12,7 @@ rg -n -F 'src/core/ops/pages.ts' docs/architecture/key-files/Ranges use each entry's first path; an entry can document severalfiles. Search when a path crosses subsystems.Edit the subsystem entry, not this page, when behavior changes.-Keep entries current-state: history belongs in `CHANGELOG.md` and Git.+Keep entries current-state: history belongs in CHANGELOG and Git.Where a new storage method, migration, doctor check, command, route or syncphase goes: [CONTRIBUTING.md](../../CONTRIBUTING.md#where-does-my-change-go).A branch from before refactor wave 1 follows the generated@@ -28,7 +28,7 @@ link it here rather than raising the cap.| [Company-brain ingestion](key-files/company-brain.md) | Inspection, admission, receipts, derived relationships and schema; [operator guide](../guides/company-brain-ingestion.md) || [Agent operator contract](key-files/agent-contract.md) | `agent-output.ts`, error registry + docs, notice ledger, `isCallable`, `--json` guard, contract scanner || [Commands (1/6)](key-files/commands-1.md) | `src/commands/agent-logs.ts` through `src/commands/db-repair.ts` |-| [Commands (2/6)](key-files/commands-2.md) | `src/commands/doctor.ts` and `src/commands/doctor/` |+| [Commands (2/6)](key-files/commands-2.md) | `doctor.ts`, `doctor/`; [alert](key-files/doctor-alert.md) || [Commands (2/6, continued)](key-files/commands-2-continued.md) | `doctor/checks/routing-federation.ts`, `git-convergence.ts`, `keyword-plan.ts`, `dream-retriage.ts` to `embed.ts` || [Commands (3/6)](key-files/commands-3.md) | `src/commands/engine-status.ts` through `src/commands/extract.ts` || [Commands (3/6, continued)](key-files/commands-3-continued.md) | `src/commands/extract-timeline-db.ts` through `src/commands/frontmatter-install-hook.ts` |diff --git a/docs/architecture/key-files/commands-2.md b/docs/architecture/key-files/commands-2.mdindex 4892e439cf..bbd623b297 100644--- a/docs/architecture/key-files/commands-2.md+++ b/docs/architecture/key-files/commands-2.md@@ -41,7 +41,6 @@ Doctor's embedding-dimension warning treats existing chunks as existing data eveSize ceiling: `scripts/module-size-limits.tsv` (per-change raise history: `git log -p` on that file). The ceiling covers the façade: re-exports, `Check`/`DoctorReport` and report scoring, the `buildChecks` flag parse, `runDoctor`, output rendering and `--locks`; every check block lives in a registry entry under `doctor/checks/*` (refactor wave 1 W4 doctor), remediation in `doctor/remediate.ts`, wave checks in `doctor/wave-checks.ts`.- `src/commands/doctor/check-fix.ts` (+ `heartbeat.ts`, `checks/harness-wiring.ts`, `checks/agent-contract.ts`) — doctor speaks agent contract v1. `Check` carries optional `fix` (stored `Action`; `computeDoctorReport` renders it for the report's transport via `finalizeCheckFixes`, redacted on http), `fix_unavailable_reason` (`check_errored`, `operator_judgement`, `no_safe_automatic_fix`, `unstructured` for legacy prose-only warns), `severity: 'info'` and `readiness_state`; `schema_version` stays 2 and status stays `ok | warn | fail`. Capabilities that are off by choice or not applicable yet (keyless embeddings and their staleness/vector checks, opt-in takes, no serve running, 0 pages, never-cycled empty or <24 h sources, backup before 25 pages+facts or 7 days via `backupCoachingDue`) report `ok` + `info` with the enable command as `fix`; the report adds `capped_by: ['embeddings_disabled']` and, when the `connection` check is present and not ok, `unknown_scores: ['brain']`. `top_issues[]` gain `action` (the rendered fix) beside the legacy `fix` string. `checkError(name, what, err)` is the one "Could not …" shape (a `gbrain db-repair` fix when the error classifies as DB access). `gbrain doctor --only <check>[,…] [--json]` (`parseOnlyChecks`, `onlyNeedsEngine`, CLI `runDoctorOnly`) runs only the entries that emit those names plus the connection lane, engine-free when every name is a filesystem check, else `connectEngine({ probeOnly: true })`; unknown names exit 2 with the valid list; a requested check that produced nothing reports `info`/`not_applicable` (or `check_errored` after an early stop). It is every doctor fix's `verify`. `harness_wiring` reads the gbrain registration from `~/.claude.json`, Codex `config.toml` and `opencode.json`; under `--only harness_wiring` it smoke-tests it (live serve lock owner → `wired_running`; else spawn the registered argv, 15 s, initialize + tools/list + `recall`; `gbrain_status` replies reported with their reason/fix); it writes nothing. #6453: with no PGLite lock, an HTTP registration gets a credential-free 3 s GET of `/health` (`probeHttpRegistration`): gbrain `ok` → `wired_running` + `mcp_access: 'unverified'`; refused loopback `http:` → `http_serve_missing` + fix; else `http_serve_unreachable`/`http_serve_unhealthy`, no fix. `redactRegistrationUrl` strips userinfo, query and fragment from every printed URL (`test/harness-wiring-redaction-6453.test.ts`). `agent_contract` reads the whole size-bounded log (`readAgentContractEvents(Infinity)`, 7-day window) and warns on `internal_error`/suggestion-less envelopes, consent refusals, `derived_cap_exhausted` and `json_document_missing`, with the user-only `consent.preapprove.*` command as fix. `throttleDoctorHeartbeat`: piped doctor progress emits at most one heartbeat per 5 s. Tests: `test/doctor-status-set.test.ts`, `test/doctor-harness-smoke.test.ts`, `test/doctor-day-zero.test.ts` (keyless init then doctor: 0 WARN, health ≥ 90), `test/doctor-remote-parity.test.ts` (run_doctor and CLI agree per shared check; run_doctor renders fixes for its transport). `harness_wiring` with no registration drops every detected harness an enabled plugin lane covers (`enabledPluginLanes`): all covered → `ok`, `reason: plugin_lane_enabled` with the plugins, harnesses and a verify hint (plugin lanes are not smoke-tested); partly covered → the missing-registration warning for the uncovered harnesses only. Claude Code detection also honors `CLAUDE_CONFIG_DIR`.-- `src/commands/doctor/alert.ts` — GBRA-224 W4 `DoctorReport.alert`: `computeAlert(checks, { ran, render })` (called by `computeDoctorReport` after fixes render) grades only `PAGE_CHECK_LEVELS` (`src/core/doctor-categories.ts`): `act` items keep the check's rendered `fix` plus a stable `code` and `docs`; `unknown` items (budget, bound, errored, last_known, not_run) name the check, `budget_ms` and a measuring `fix`; act over unknown over none. `ran` (`alertRanChecks`: none without an ok `connection`, else the page checks whose entry runs at the tier) makes a page check the run executed but did not emit "did not apply"; without it a missing page check is unknown. A non-CLI render omits messages and redacts. `alertRunArgs` turns `--alert` into `--only <page class> --budget-ms 30000 --scope=brain` unless `--tier`/`--only`/`--budget-ms` is given; `recordAlertStreak` keeps the per-brain consecutive-unknown count in `doctor-alert-state.json` (atomic, read-only home tolerated); exit 0/17/18 via `alertExitCode`. Tests: `test/doctor-alert-w4.test.ts`, `test/doctor-alert-cli-w4.test.ts`.- `src/commands/doctor/registry.ts` + `src/commands/doctor/context.ts` — the doctor check registry (refactor wave 1, W4 doctor). `DOCTOR_CHECK_REGISTRY` lists 126 `DoctorEntry` records `{ name, emits, run(ctx) -> Promise<Check[] | STOP_DOCTOR> }` in output order; `runDoctorRegistry(ctx)` runs them, returns the checks gathered so far on `STOP_DOCTOR`, and otherwise finishes the DB-checks progress phase. The run is one `withGitListingCache` scope (`src/core/git-visible-files.ts`), so entries that list the same source checkout (frontmatter scan, fence census, slug collisions) share one `git ls-files` per listing and one "not a git repository" verdict per directory (`ls-files`, `discoverGitRoot`, the census HEAD probe; any repository-changing `sync-git.ts` command or `invalidateGitListingCache()` drops the scope's memo: `test/git-listing-memo.serial.test.ts`). Execution groups: filesystem-first entries (the resolver-health entry applies `--fix` before it scans), the no-engine connection lane plus a STOP when `--fast` or no engine, the live connection entry plus a STOP when `getStats` failed, then the DB entries, which take the engine via `connectedEngine(ctx)`. `DoctorContext` carries the parsed flags (`jsonOutput`, `fastMode`, `doFix`, `dryRun`, `scope`, `orphanRatioSourceId`, `args`), `engine`, `dbSource`, `connectError`, `progress`, the skills-dir resolution and the cross-entry values `autoFixReport`, `schemaVersion`, `connectionFailed`, each written by the entry that computes it. Entry modules (one `run*` function per former `buildChecks` block, moved verbatim): `checks/skill-group.ts`, `local-runtime.ts`, `supervisor-health.ts`, `local-audits.ts`, `db-connection.ts` (also `pgbouncerPrepareCheck`, `classifiedConnectionCheck` — a live serve owner warns with the exclusive two-step fix, a `pglite_busy` reason `legacy_owner_unverified` fails with details.reason and the refusal's ask_user preview fix, anything else is classified for `db-repair` — and the two STOP gates), `schema-health.ts`, `embedding-health.ts`, `graph-health.ts`, `data-integrity.ts`, `content-quality.ts`, `knowledge-health.ts`, `queue-assets.ts`, `sync-search.ts`; `checks/legacy-token-grants.ts` (F3) emits `legacy_token_grant_shape` (info: active tokens still on the JSONB-only grant shape, fix `gbrain auth rescope --migrate-legacy`) and `legacy_token_grant_drift` (warn: per-token drifted axes with the two adopt commands); `checks/grant-new-ops.ts` (D4) emits `grant_new_ops_available` (warn: active clients and tokens whose operation snapshot or stored surface keeps operations their scopes allow out of reach, with proven blockers apart from inferred grant age, per-grant names in details, and an ask_user fix whose rescope argv differs for tokens and clients; `--operations all` is a disclosed choice, never the fix); `checks/upgrade-health.ts` holds `checkUpgradeErrors` / `checkSelfUpgradeHealth` / `upgradeErrorResolved` (re-exported by the façade). A pre-gate entry declares the names it only emits with a connected engine in `engineChecks` (#6303), so `onlyNeedsEngine` connects for `--only` of them; `test/doctor-only-engine-checks.test.ts` is the drift guard. To add a check: add an entry in the topic module, place it in `DOCTOR_CHECK_REGISTRY` where its output belongs, and categorize every emitted name in `src/core/doctor-categories.ts`. Tests: `test/doctor-registry.test.ts` (category contract with FAIL/Why/Fix/See, `emits[]` equals the AST walk, STOP positions), `test/doctor-mode-matrix.serial.test.ts` (entries run, STOP point, engine calls and `--fix` mutations per mode), and the W0 goldens `test/doctor-registry-golden.test.ts` (the AST walker follows `runDoctorRegistry` into the registry), `test/doctor-early-stop-golden.serial.test.ts`, `test/doctor-json-golden.test.ts`.- `src/commands/doctor/` — the doctor module directory (the meat behind the `doctor.ts` façade). `checks/` holds the check-function library in bundles grouped by concern (`core-health.ts`, `queue-jobs.ts`, `extraction-sync.ts` (its `sync_freshness` check excludes sources disabled by `isSyncDisabledConfig` and adds `--no-pull` to its sync hint on a managed brain; `content_hash_duplicates` prescribes `GBRAIN_SOURCE=<id> gbrain delete <bare-slug> --force` per wrong-root pair, naming each source when pairs span several, and never a hard purge; `cycle_freshness` in `consolidation-cycle.ts` still monitors their maintenance; its `atom_provenance_drift` check scopes drift to page-bound atoms and splits it into `source_changed` / `source_gone`; atoms with no `source_slug` — transcript-origin `source_path`-only rows, whose hash is over a file and whose page liveness cannot be resolved by slug — are reported as their own `slug_unbound` count and never enter the drift total or the WARN ratio), `graph-embedding.ts`, `search-eval.ts`, `calibration.ts`, `consolidation-cycle.ts`, `pglite-worker.ts`, `routing-federation.ts` (`source_routing_health` exempts zero-page skill-pack sources), `verbs-reflex.ts`, `stale-mentions.ts`, `timeline-history.ts` (`timeline_history`: database-only timeline rows, bounded to 2,000 pages / 10 s per run, cursor in config `doctor.timeline_history.scan:<sources>` so runs finish a pass (a clean pass stays `ok` until a newer row; `doctor-timeline-history-cursor-5821.test.ts`), exact-or-lower-bound counts, non-round-trippable rows informational, repair `gbrain repair timeline`; segmented pages counted apart (`segmented_*`), no repair advice), `derived-visibility.ts` (`derived_visibility`: atoms and synthesized concepts without explicit visibility or looser than their origin, one exact aggregate, repair `gbrain repair visibility`), `engine-fit.ts` — the last carrying `pglite_scale` + the engine-free `db_repair_recurrence` over the db-repair receipts); `schema-pack-checks.ts`, `report-remote.ts`, `bootstrap-checks.ts`, and `skill-checks.ts` are the four tail-cluster modules (schema-pack checks, the remote/thin-client doctor report, bootstrap checks, skill checks). `harness-hook-checks.ts` (`harnessHookCarrierChecks`, called from `bootstrap_harness_health`) reads each receipt-named Claude Code hook carrier read-only: an event wired more than once by this install warns `harness_hook_duplicates` with a consented re-run carrying the install's `--project`/`--no-capture` choices, a lookalike it did not write warns `harness_hook_unowned` (operator judgement), an unparseable carrier warns naming the file, and entries the host stripped of their marker are an `ok` info row; `plugin_lane_collision` iterates `enabledPluginLanes`. `multiSourceDriftCheck` is the one local/remote `multi_source_drift` verdict: on a managed brain (`managedPersistenceEnabled`) its sync advice names `--no-pull` and drops `--include-gitignored`, unmanaged wording is unchanged, and any skipped source keeps it warn/not_verified. `src/core/multi-source-drift.ts` derives a `git-root`-pinned source's slug prefix from its git toplevel (realpaths, empty at the repo root) and skips only a source whose toplevel cannot be resolved (`git_root_skipped`). It drops every walked path sync would refuse (`unsyncableReason(prefix + relPath)`: metafiles such as root `AGENTS.md`/`CLAUDE.md`, pruned dirs, malformed names) before probing, so a same-slug page on `default` is not reported for a file sync never imports (#6681). `graph-health.ts` `graph_coverage`, like onboard's link and timeline coverage, is `ok` (not applicable, with the count) below `MIN_ENTITY_PAGES_FOR_COVERAGE` (5) eligible entity pages. `graph_coverage` and `orphan_ratio` count the entity types the active schema pack declares (#4772, `src/core/schema-pack/entity-types.ts`, resolved per source: brain-wide for `graph_coverage`, the asked source for `orphan_ratio --source`); a pack that does not load makes `graph_coverage` a warn naming the pack (never the old hardcoded list) and `orphan_ratio` answers with an "entity count unknown" caveat instead of a vacuous ok. All are re-exported by the façade. Structural guards that pin doctor source text load it through `test/helpers/doctor-source.ts`: `doctorSource()` concatenates the façade plus every `src/commands/doctor/**/*.ts` (façade first, then sorted) so a module move can never take a pinned string out of a guard's sight; `doctorFileSource(rel)` reads one named file for positional/ordering assertions; the helper also feeds the `doctor-source-helper` detector in `scripts/classify-tests.ts`. `facadeExpansion` in `scripts/generate-flag-registry.ts` keeps this directory on the doctor command's flag-scan surface. Two read-only derived-data checks live beside them: `timeline-orphans.ts` (`timeline_orphans`, samples 500 pages for rows an earlier page version produced that the current text no longer does; fix is `gbrain extract timeline --prune-orphans`) and `slug-collisions.ts` (`slug_collisions`, walks each live source checkout with `collectSyncableFiles` and reports paths that map to one slug plus the indexed one; sources without a checkout are skipped). `checks/graph-embedding.ts` `checkJunkEntityHubs` (#6158) splits connector contact pages (frontmatter `google_contact_id` or a connector source kind) into `details.connector_twins` with their main-brain `canonical_twin`, never calls them extractor-minted or offers `junk_hub_exempt`, and carries `fix_unavailable_reason: 'operator_judgement'` while the defer-to-twin policy is open.diff --git a/docs/architecture/key-files/doctor-alert.md b/docs/architecture/key-files/doctor-alert.mdnew file mode 100644index 0000000000..793ebcf711--- /dev/null+++ b/docs/architecture/key-files/doctor-alert.md@@ -0,0 +1,6 @@+# Key files: Commands (2/6, doctor alert)++[Subsystem index](../KEY_FILES.md) · [Previous entries](commands-2-continued.md). Read only the entries relevant to your change.+Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.++- `src/commands/doctor/alert.ts` — GBRA-224 W4 `DoctorReport.alert`: `computeAlert(checks, { ran, render })` (called by `computeDoctorReport` after fixes render) grades only `PAGE_CHECK_LEVELS` (`src/core/doctor-categories.ts`): `act` items keep the check's rendered `fix` plus a stable `code` and `docs`; `unknown` items (budget, bound, errored, last_known, not_run) name the check, `budget_ms` and a measuring `fix`; act over unknown over none. `ran` (`alertRanChecks`: none without an ok `connection`, else the page checks whose entry runs at the tier) makes a page check the run executed but did not emit "did not apply"; without it a missing page check is unknown. A non-CLI render omits messages and redacts. `alertRunArgs` turns `--alert` into `--only <page class> --budget-ms 30000 --scope=brain` unless `--tier`/`--only`/`--budget-ms` is given; `recordAlertStreak` keeps the per-brain consecutive-unknown count in `doctor-alert-state.json` (atomic, read-only home tolerated); exit 0/17/18 via `alertExitCode`. Tests: `test/doctor-alert-w4.test.ts`, `test/doctor-alert-cli-w4.test.ts`.diff --git a/llms-full.txt b/llms-full.txtindex 47696f13a1..5aa20fd23b 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -6816,243 +6816,6 @@ Note: there is no SQLite engine. PGLite uses the same SQL as Postgres, so no sep----## docs/schema-author-tutorial.md--Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/schema-author-tutorial.md--# Tutorial: Build your first schema pack--You'll fork the bundled `gbrain-base` pack, add a custom `researcher` page type, import a handful of placeholder researcher pages, backfill their `page.type` column with one command, then prove the wiring works by running `gbrain whoknows` and seeing your new type surface in results. End state: a forked-and-active pack on disk, ~5 pages typed as `researcher`, and a query that proves the pack-aware routing fires end-to-end.--**Want the WHY before the HOW?** Read [`what-schemas-unlock.md`](what-schemas-unlock.md) first — 7 concrete use cases (4000 invisible meetings, the founder ops brain, the research brain, the legal brain, the team brain, agent-as-co-curator) plus the structural argument for why types matter at query time. Then come back here for the 5-minute walkthrough.--The whole walkthrough takes about 5 minutes. You'll see something working by step 3.--## What you'll need--- gbrain installed (`gbrain --version` to check)-- A brain that's been initialized (`gbrain init` already run; either PGLite or Postgres is fine)-- A terminal you can paste commands into--That's it. No API keys required for this tutorial — every step works against the bundled pack and local-only commands.--## Step 1: See what pack is active today--```bash-gbrain schema active-```--You'll see something like:--```text-Active pack: gbrain-base v1.0.0-Source: default-Pack identity: ...-Page types: 22-Link verbs: 12-Takes kinds: hot, warm, cold-```--`Source: default` means you haven't customized anything — you're on the bundled pack. `Page types: 22` is the universal starter (person, company, meeting, note, etc.). (Agents needing this as JSON use the MCP op `get_active_schema_pack` — the CLI subcommand prints human output only.)--**You can't mutate bundled packs directly.** Step 2 forks it so you have something writable.--## Step 2: Fork the bundled pack--```bash-gbrain schema fork gbrain-base mine-```--Output: `Forked 'gbrain-base' → 'mine' at ~/.gbrain/schema-packs/mine/pack.json`.--The fork is a byte-for-byte copy of `gbrain-base` living at `~/.gbrain/schema-packs/mine/pack.json`. Now you have a writable pack you can mutate.--## Step 3: Activate the fork--```bash-gbrain schema use mine-```--Output: `Pack: mine (json) ... Active.`--Run `gbrain schema active` again to confirm `Active pack:` now says `mine` and `Source:` is `home-config` (read from `~/.gbrain/config.json`).--**You've already accomplished something visible** — the active pack changed, and any future query will route through your fork. The next four steps add a custom type and prove it works.--## Step 4: Add a researcher type--```bash-gbrain schema add-type researcher \- --primitive entity \- --prefix people/researchers/ \- --extractable \- --expert-```--Output: `Pack: mine (json)` + `Sha8: <prev> → <new>`.--What just happened:-- The mutation went through `withMutation`'s 8-step skeleton: bundled-guard → per-pack lock → read → mutate → file-plane lint validation → atomic write → audit log → cache invalidation.-- The pack now declares `researcher` as an entity primitive bound to `people/researchers/`, marked `extractable: true` (eligible for facts extraction) and `expert_routing: true` (surfaces in `whoknows` queries).-- An audit row landed in `~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl` with your type name SHA-8-redacted and the prefix's first segment only (`people`) for privacy.--Verify the type is in the pack:--```bash-gbrain schema explain researcher-```--You'll see the resolved settings printed back.--## Step 5: Import some placeholder researcher pages--You need pages under `people/researchers/` for the next step to do anything. If your brain repo already has them, skip ahead. If not, drop 3-5 placeholder markdown files into `<your-brain-repo>/people/researchers/` and import:--```bash-mkdir -p people/researchers-cat > people/researchers/alice-example.md <<'EOF'-----title: Alice Example------ML researcher at Example Lab. Works on contrastive embeddings.-EOF--cat > people/researchers/bob-example.md <<'EOF'-----title: Bob Example------Vision researcher at Widget University. Recent paper on diffusion models.-EOF--cat > people/researchers/charlie-example.md <<'EOF'-----title: Charlie Example------RL researcher at Acme Research. Focus on inverse reinforcement learning.-EOF--gbrain sync-```--The sync imports the new files. They'll be stored in the database but their `type` column will still be empty — the new type was added to the pack AFTER these pages already existed (the typical real-world scenario for an agent walking into an existing brain).--## Step 6: See the gap with `stats`--```bash-gbrain schema stats --json | jq '.aggregate, .dead_prefixes'-```--You'll see `untyped_pages: 3` (or however many you just imported) and `dead_prefixes: []` — your new prefix has 3 matching pages, so it's not dead.--The 3 researcher pages are "orphaned" by type even though they live in the right directory. The next step backfills them.--## Step 7: Backfill with `sync --apply`--First dry-run to see what would happen:--```bash-gbrain schema sync --json-```--You'll see something like:--```json-{- "schema_version": 1,- "apply": false,- "per_prefix": [- {- "type": "researcher",- "prefix": "people/researchers/",- "would_apply": 3,- "sample_slugs": ["people/researchers/alice-example", "people/researchers/bob-example", "people/researchers/charlie-example"],- "applied": 0- }- ],- "total_would_apply": 3,- "total_applied": 0-}-```--`would_apply: 3` is what you'd touch. `sample_slugs` is the agent's drilldown signal — if those slugs look wrong, abort. They look right, so apply:--```bash-gbrain schema sync --apply-```--You'll see per-batch progress lines on stderr and a final `total_applied: 3`. The UPDATE ran in chunks of 1000 (yours fit in one chunk) and never wedged any concurrent writer.--## Step 8: Prove the wiring works--```bash-gbrain whoknows "machine learning"-```--If your researcher pages contain ML-related content, they'll surface in the ranked results — even though they're typed `researcher`, not `person` or `company`.--**This is the load-bearing demonstration of the pack-aware wiring.** `whoknows` consults the active pack's `expert_routing: true` types via `expertTypesFromPack(pack.manifest)` rather than a hardcoded `['person', 'company']` list, so your custom type routes through expert search instead of being ignored.--## What you built--You now have:-- A fork of `gbrain-base` named `mine` at `~/.gbrain/schema-packs/mine/pack.json`, active in your brain via `~/.gbrain/config.json`.-- A `researcher` page type registered in the pack with `entity` primitive, `people/researchers/` prefix, `extractable: true`, `expert_routing: true`.-- 3 pages typed as `researcher` (backfilled from disk via `gbrain schema sync --apply`).-- A query path that routes through the new type: `gbrain whoknows` reads the pack and includes `researcher` in its type filter.--You also exercised the full mutation skeleton: bundled-pack guard, per-pack lock, validation gate, atomic write, audit log, cache invalidation. Every step was idempotent — re-running any of them is a no-op.--## Next steps--**Add a type set by frontmatter only.** Some types don't live in one directory: an `archive` page can sit anywhere and is typed by its frontmatter `type: archive`. Declare it with `--no-prefix` instead of `--prefix`:--```bash-gbrain schema add-type archive --primitive concept --no-prefix-```--The pack records `path_prefixes: []`, so pages get this type only from frontmatter. Leaving out both `--prefix` and `--no-prefix` is refused (exit 2, `invalid_params`), and `--no-prefix` can't be combined with `--extractable` or `--expert` (lint rules `extractable_empty_corpus`, `expert_routing_without_prefix`).--**Add a link verb.** A `researcher` can `author` a `paper`. To model that:--```bash-gbrain schema add-type paper --primitive annotation --prefix research/papers/ --extractable-gbrain schema add-link-type authored --page-type researcher --target-type paper-gbrain schema graph-```--The graph now shows `researcher --(authored)--> paper`.--**Add aliases for query closure.** If you want `gbrain query researcher` to also surface `person` rows (because researchers ARE people):--```bash-gbrain schema add-alias researcher person-```--Read [`skills/conventions/schema-evolution.md`](../skills/conventions/schema-evolution.md) for the decision tree on when to add types vs aliases vs prefixes. The short version: <20 pages → don't pack-codify; 20-100 → alias on existing type; 100+ → first-class type.--**Lint your pack before shipping.** The 14-rule lint surface (with the optional `--with-db` flag for DB-aware checks, including the stored-type alias/undeclared rules) catches dangling references, prefix collisions, and dead-corpus warnings:--```bash-gbrain schema lint --with-db-```--**Commit your pack to source control.** If `~/.gbrain/schema-packs/mine/` is a git repo, commit `pack.json` and push. Your pack survives across machines, and the `mutation_count_anomaly` lint rule will nudge you when you hit >50 mutations in a week (the "you should be committing this" signal).--**For agents (MCP):** the same operations are reachable over HTTPS MCP as schema ops. Register an admin-scope OAuth client and `schema_apply_mutations` lets a remote agent compose multi-step refactors as one atomic batch. The batched MCP op + per-pack lock + audit log are the load-bearing primitives that make remote schema authoring safe. See [`skills/schema-author/SKILL.md`](../skills/schema-author/SKILL.md) for the agent dispatcher.--**Undo a mistake.** Every mutation primitive has an inverse (`remove-type`, `remove-alias`, `remove-prefix`, `remove-link-type`, `set-extractable false`, etc.). If you fork twice and want to revert, `gbrain schema downgrade --to <pack>` re-activates the pack you name (e.g. `--to gbrain-base`). The bare history-based form depends on `~/.gbrain/schema-pack-history.jsonl`, which nothing writes today — always pass `--to`.--## Related docs--- **Reference:** `gbrain schema --help` for the full CLI surface (30+ subcommands); the "Schema packs: mutation surface" section of `docs/architecture/KEY_FILES.md` for the module-by-module architecture.-- **How-to:** [`skills/schema-author/SKILL.md`](../skills/schema-author/SKILL.md) — the agent dispatcher with the 7-phase workflow (brain → assess → propose → apply → sync → verify → commit).-- **Explanation:** [`skills/conventions/schema-evolution.md`](../skills/conventions/schema-evolution.md) — when to add a type vs alias vs prefix.------## docs/guides/live-sync.mdSource: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/live-sync.mddiff --git a/scripts/llms-config.ts b/scripts/llms-config.tsindex e0118e417e..a18f171373 100644--- a/scripts/llms-config.ts+++ b/scripts/llms-config.ts@@ -146,6 +146,8 @@ export const SECTIONS: DocSection[] = [description:"5-minute walkthrough: fork the bundled pack, add a custom `researcher` type, backfill existing pages via `gbrain schema sync --apply`, prove the T1.5 wiring via `gbrain whoknows`.",path: "docs/schema-author-tutorial.md",+ // Linked, not inlined: the doctor --alert guide (troubleshooting, exit codes, cron) put llms-full.txt over FULL_SIZE_BUDGET.+ includeInFull: false,},{title: "docs/guides/system-one.md",diff --git a/src/core/skill-manifest.ts b/src/core/skill-manifest.tsindex 0aa5c7c560..32a737987f 100644--- a/src/core/skill-manifest.ts+++ b/src/core/skill-manifest.ts@@ -162,7 +162,9 @@ export function loadOrDeriveManifest(skillsDir: string): ManifestLoadResult {* not gbrain's to grade.*/export function isGbrainManagedSkillsDir(dir: string): boolean {+ // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- the second segment is a fixed file name; dir is the operator's own skills folder and is only probed for existence, never written.if (existsSync(join(dir, SKILLS_MANIFEST_FILENAME))) return true;+ // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- fixed file name under the operator's own skills folder; existence probe only.if (existsSync(join(dir, 'manifest.json')) && !loadOrDeriveManifest(dir).derived) return true;return [...findAllResolverFiles(dir), ...findAllResolverFiles(dirname(dir))].some((file) => {try { return readFileSync(file, 'utf-8').includes(SKILLPACK_MANAGED_BEGIN); } catch { return false; }diff --git a/test/doctor-alert-cli-w4.test.ts b/test/doctor-alert-cli-w4.test.tsindex 9ede97ed4b..79198dec84 100644--- a/test/doctor-alert-cli-w4.test.ts+++ b/test/doctor-alert-cli-w4.test.ts@@ -12,7 +12,7 @@ import { afterAll, describe, expect, test } from 'bun:test';import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { join } from 'node:path';import { makeDoctorHome, runGbrain, type DoctorHome } from './helpers/doctor-json-golden.ts';-import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { pgliteSql } from './helpers/doctor-hot-checks-fixture.ts';const homes: DoctorHome[] = [];afterAll(() => { for (const h of homes) h.cleanup(); });@@ -48,15 +48,9 @@ const check = (report: any, name: string) => report.checks.find((c: any) => c.naasync function corruptJsonb(h: DoctorHome, fix = false): Promise<void> {const cfg = JSON.parse(readFileSync(join(h.home, '.gbrain', 'config.json'), 'utf-8'));- const engine = new PGLiteEngine();- await engine.connect({ database_path: cfg.database_path });- try {- await engine.executeRaw(fix- ? `DELETE FROM ingest_log WHERE source_ref = 'w4-alert-fixture'`- : `INSERT INTO ingest_log (source_type, source_ref, pages_updated) VALUES ('fixture', 'w4-alert-fixture', to_jsonb('["notes/alpha-example"]'::text))`);- } finally {- await engine.disconnect();- }+ await pgliteSql(cfg.database_path)([[fix+ ? `DELETE FROM ingest_log WHERE source_ref = 'w4-alert-fixture'`+ : `INSERT INTO ingest_log (source_type, source_ref, pages_updated) VALUES ('fixture', 'w4-alert-fixture', to_jsonb('["notes/alpha-example"]'::text))`, []]]);}for (const kind of ['repo-less', 'repo'] as const) {