2 Commits

Include renames

Author	SHA1	Message	Date
Garry TanandClaude Fable 5	d35c9c9e44	v0.45.0.0 feat(bootstrap): paste-in personal-agent install for Codex + Claude Code (#3975) ... * docs(designs): agent-bootstrap plan + design docs (normative, review-absorbed) The scrubbed, in-repo sources of truth for the gbrain bootstrap wave: AGENT_BOOTSTRAP_DESIGN.md (product scope/sequencing) and AGENT_BOOTSTRAP_PLAN.md (implementation; all review-finding IDs inlined). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(bootstrap): format spec, question bank, identity templates, bundled assets agent.json manifest (format_version 1, initialized sentinel) + machine-local install receipt [CX2-1, CX2-12]; 12-question/6-required interview bank with consent keys and a persist:false sink for the optional provider key [CX2-13]; ten {{TOKEN}} identity templates (generic, adapted to gbrain ops — gates call recall/query/put_page, write-through-ops rule, keyless agent-authored facts, silence contract); assets embedded compiled-binary-safe via file-type imports [ENG-6]. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(bootstrap): runbook, README paste block, bootstrap guide, TODOS entries BOOTSTRAP_FOR_AGENTS.md (agent-driven install runbook: CLI phase list is the source of truth, never-invent rules, Codex approvals preflight, keyless posture, failure-modes table, version stamp for the skew check); README gains the full-agent paste block pinned to latest-stable inside the Claude Code/Codex quick start (memory-only tier stays); docs/guides/bootstrap.md carries the full install/security/consent/degradation/uninstall contract. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(designs): spike instrument for the bootstrap wave (build order 0) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(bootstrap): interview + render engines Interview gate with read-back confirm-hash (any later answer change clears the confirmation — the hostile single-batch case is structurally impossible), per-answer provenance, caps + escaping at set time, config-sink routing for the provider key; renderer with hard-fail token sweep, subordinate fencing of principal input, never-clobber + backups, deterministic minimal mode for the template repo, scaled byte floors. 58 unit tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(bootstrap): private-repo lifecycle — repo create, attach, uninstall, run lock gh-gated private repo creation with API-verified privacy (rate-limit distinct from public), refuse-foreign-origin with attach as the sanctioned path, atomic bootstrap mutex (pid liveness + age + token), receipt-keyed uninstall that never wholesale-deletes the gbrain home and only offers --delete-brain for a brain it created; read-only PGLite lock probe (never opens the engine). 54 unit tests, injectable exec seam throughout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(release): latest-stable ref, template-repo publish job, bootstrap CI guards release.yml advances the latest-stable tag only after assets publish (the paste block's permanent ref — copies in the wild never rot) and gains a PAT-gated publish-template job verified against the vendored tree; two skip-graceful guards (sanctioned-ref + runbook stamp; template/token bijection + placeholder assertion + generator byte-diff) wired into verify; README + runbook re-admitted to the CI cache hash; vendored deterministic template tree generated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(context): IPC v2 turn_context + 8KB assembly + visibility resolver + session identity Discriminated-union IPC with handler map, protocol echo (stale-serve detection), shared-secret gate, server-side source binding, per-kind budgets; turn-context assembly (reflex pointers + volunteered pages + world-only hot facts) under a data-not-instructions envelope trimmed to the harness's 10KB hook-output cap; facts.default_visibility resolved through one helper at all four sites (explicit caller wins, typos fail closed); typed sessionId threads _meta.session_id into the hot-memory cache key. 50 new tests; 180 adjacent tests confirmed green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(persistence): secret-scan, gbrain sources push, durability unification Pattern secret scanner (own runtime allowlist, redacted previews, corpus-write redaction mode); sources push runs the whole scan→stage→commit→pull→push sequence under one cross-platform lock (mkdir-atomic, pid+age+token) with a deny-glob backstop, commit-first divergence-safe pull, refuse-unverifiable visibility, and push-status telemetry; gbrain-home choke point unifies GBRAIN_HOME semantics with config (0700); durability is parent-repo-aware and rotates its push log at 0600. 35 new tests; 200 existing green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(sources): harden/pull gates accept sources inside a parent git repo The bootstrap workspace registers brain/ (a subdirectory) as the source; the durability core already resolves the repo root, so the command gates now check inside-a-repo rather than .git-right-here [CX2-3]. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(serve): resident maintenance sweep + keyless capability probe The lock-owning serve process now closes the persistence loop: startup (3s post-connect, best-effort, unref'd) and idle (10-min quiet intervals through the injectable timer seam) sweeps run facts-fence reconciliation, deterministic link/timeline extraction over recent workspace pages, and spend-gated corpus ingest (skipped keyless — agent-authored fences cover it). gbrain sweep --once is the trusted CLI seam bootstrap verify uses. Capability probe renders the honest keyless/keyed report. Full reuse of the cycle extractor + extract cores; 26 new tests, neighbors green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(hooks): engine-free gbrain hook command, settings writers, transcript parser Four hook events (session-start digest + crashed-session recovery push, user-prompt turn-context injection under an 800ms deadline and the 10KB cap, stop buffers, session-end corpus write with redaction/retention/dedup + best-effort push); structural JSON settings merger keyed by a _gbrain marker (foreign hooks and permissions survive); dated host-spec registry; Claude Code .jsonl parser as a spec-target with a scrubbed 7-shape fixture. Heartbeat is counters-only by construction. 59 tests; zero engine modules in the import graph. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(bootstrap): cross-link the full-agent path from the connection docs Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(bootstrap): dispatcher, verify, status — the command assembled gbrain bootstrap {status,interview,render,repo,hooks,verify,uninstall,attach}: engine-free except verify (owns its engine, in-process sweep — no live-serve conflict); phase list is the TS source of truth with install.jsonl telemetry and the support blob; verify's fail-soft check suite covers the real write path (put_page → write-through file → sweep → graph floor → recall), passes keyless, persists snapshots, and ends with the first-run tour. cli.ts wired per the three-touchpoint rule; doctor gains the bootstrap check group (silent on machines with no bootstrap state). 28 new tests; 353 adjacent green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: KEY_FILES bootstrap cluster + CLAUDE.md dispatcher row (+ build:llms) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(bootstrap): e2e pins — hook-under-live-serve, attach, degraded modes, compiled binary, Docker harness The permanent pins: a real serve holds the PGLite lock while the engine-free hook completes (and a direct engine open provably throws LiveServeLockError); stale-socket fail-open; machine-2 attach with marker-keyed hook repair; decline-everything installs verify green with every degradation named; the compiled binary renders bundled templates in an empty cwd. Offline Docker harness (networkless, read-only) gated into heavy-tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(bootstrap): register doctor check categories + system-of-record allow comments The six bootstrap doctor checks join OPS_CHECK_NAMES; the sweep's batch link/ timeline inserts carry the explicit extract-path allow comments (the sweep IS the extraction path for workspace pages). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): shard wedge cap tracks suite growth (1500s -> 1800s) At ~9000 tests a healthy shard finished at 1466s and two progressing shards were false-killed at the old cap; 1800s restores ~25% headroom over the slowest observed healthy shard. Real hangs still hit it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(ci): cache-hash policy — README + runbook edits must invalidate [C2] The old deny-list assertion predates the paste block; README.md and BOOTSTRAP_FOR_AGENTS.md are policy-doc re-admissions now, so their edits must change the hash (a paste-block edit shipping under a cached green was the C2 hole). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): classify post-suite exit-hangs as warn-pass; file the leak forensics A shard killed by the wedge watchdog with every assigned file started and zero fail markers did all its work and leaked a handle at exit — pre-existing and master-reproducible (P1 TODO carries the full bisect forensics). Bun's per-test timeout turns a hung test into a (fail), so the classifier cannot mask one. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): shard cap 2400s — the count-balanced heavy shard needs it under contention Observed: the heavy shard still progressing 22s before an 1800s kill while siblings finish at 1150-1550s (split balances file count, not weight). Filed the load-sensitive WAL-repair flake (pre-existing, master's v0.42.75.0 wave). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(bootstrap): quarantine env-mutating suites to the serial lane check-test-isolation R1: six new files mutate GBRAIN_HOME/env at module scope — the serial lane (one process per file) is the guard's prescribed home for them. All 114 tests pass post-rename. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(readme): per-harness install sections — Codex, Claude Code, then OpenClaw/Hermes Each harness gets its own complete paste-block section (desktop app first, terminal noted — Claude Code CLI is the identical harness; Codex CLI works pull-based today); the OpenClaw/Hermes platform path keeps equal weight with its one-click deploys and INSTALL_FOR_AGENTS block intact; memory-only and remote-connect tiers consolidated under 'Lighter ways in'. Supersedes the review's D5 ordering by user direction; stale heading references updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(readme): Codex as the recommended first step; OpenClaw/Hermes framed as-intended, high-cost The install section now routes newcomers explicitly: Codex first (subscription-priced, nothing to deploy), OpenClaw/Hermes as GBrain used the way it was designed — always on, at real server + API cost. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: doc-audit code chasers — broken recovery hints, stale op description, auto_link key Four small code fixes surfaced by the markdown accuracy audit: - doctor's auto-RLS recovery hint pointed at `apply-migrations --force-retry 35`, which cannot work (--force-retry targets the vX.Y.Z orchestrator registry, not the numeric schema MIGRATIONS array). Hint now points at the recreate SQL in docs/guides/rls-and-you.md; test pins against regression. - v0_11_0 migration printed the same broken-mechanism class of hint (`config set minion_mode` writes DB config nothing reads); now names `apply-migrations --mode` + preferences.json, the real setter. - submit_job's op description hardcoded a stale handler list; now points at registerBuiltinHandlers as the source plus the --follow discovery trick. - `auto_link` added to KNOWN_CONFIG_KEYS: read by link-extraction, reconcile-links, and sweep, and documented as the off-switch in brain-ops/maintain, but the allowlist rejected `config set auto_link false`. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: repo-wide accuracy + MECE reform from the 9-bucket markdown audit A code-grounded audit of every markdown file (root, architecture, guides, mcp, tutorials, docs-root, operations/eval/designs, skills, recipes) followed by a fix wave with per-bucket ownership. Four classes of change: Accuracy — every documented command/flag verified against src/ before writing: dead commands replaced with working ones (pages purge-deleted, jobs watch --follow, gbrain restore, import-based Obsidian flow, space-separated --scopes, real thin-client recipes, working isolation verification, real supervisor restart procedure, curl-based ngrok health check, real minion_mode setter); count drift fixed with rot-proof phrasing (100+ ops, 50+ bundled skills via skills/manifest.json, 140+ engine methods, KNOBS_HASH_VERSION pointer instead of hardcoded versions); stale claims corrected (search-mode defaults, RETRIEVAL pipeline order incl. autocut, sentinel rules, refusal-list mechanism, engine snapshot, shard cap 2400s + EXIT-HANG classifier in TESTING.md, latest-stable + publish-template documented in RELEASING.md as release.yml promises). MECE — one home per concept, pointers elsewhere: test isolation → TESTING.md; OAuth registration + --bind/--public-url lore → DEPLOY.md; mode bundles → guides/search-modes.md (the home the CLAUDE.md dispatcher always promised); merge contract → schema-packs.md; WAL ladder → ENGINES.md; quiet-hours → quiet-hours.md; capture taxonomy → entity-detection.md; person-page taxonomy → compiled-truth.md; brain-first protocol → brain-first-lookup.md; refresh semantics → refresh-algorithm.md; KEY_FILES.md deduplicated (58 extension entries merged, one entry per file); infra-layer.md rewritten as a pointer page. Privacy — placeholder sweep across guides, docs, skills, and recipes per the iron rule; per-release narration stripped from reference docs (current-state prose only). Bootstrap coverage — AGENTS.md pointer, RESOLVER routing row, INSTALL.md path, tutorial cross-links, keyless-mode sections in spend-controls/headless-install. skills.lock.json regenerated; llms.txt/llms-full.txt rebuilt. Gates: verify 36/36, typecheck clean, doctor 96/96, skills-integrity + resolver + build-llms + config-set + migrations all green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(readme): refresh production-brain stats to current brain-repo counts 155,795 pages / 24,589 people / 5,340 companies, counted from the brain repo's current HEAD; the "100K-page brain" framing moves to 150K to match. Cron-fleet count unchanged (its store lives on the deployment host, not in the repos available for verification). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(scan,push): modern OpenAI/Voyage key patterns, scan staged blobs not disk - secret-scan matches sk-proj-/sk-svcacct-/sk-None- and pa- Voyage keys (the bare sk- pattern missed every current OpenAI key format). - workspacePush stages first, then scans the staged index blobs via git cat-file, closing the scan-then-stage TOCTOU where a file changed between snapshot and commit shipped unscanned. - shared binary-sniff helper, memoized glob regexes, atomic push-status write, and tests for pull_conflict + gitignored deny-match paths. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(ci): regenerate flag registry for new commands, harden shard classifier + release token - cli-flag-registry.generated.ts regenerated: bootstrap/hook/sweep and sources push --message/--allow-unverified-remote were missing, so the strict #2185 validator rejected real invocations and skipped the new commands entirely. - EXIT-HANG shard classifier now requires every assigned file to have started before warn-passing a watchdog kill (was fail-open). - release.yml passes TEMPLATE_REPO_PAT via http.extraheader, off the argv. - compiled-binary e2e fails loud in CI instead of a silent permanent skip. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(hook,sweep,ipc): non-blocking hook pushes, bounded sweep + cache, source-bound resolve - session-start/session-end no longer run synchronous git + inline push inside their self-deadline; a detached child does the push and the hook returns immediately (blocked Claude Code startup for minutes on a dirty tree before). - serve sweep drops the unbounded listAllPageRefs, resolves only candidate targets, claims corpus files atomically (no double-LLM-spend race), and caps the fence LIKE scan; heartbeat writes are O_APPEND with rare compaction. - hot-memory cache evicts expired entries and bounds entry count (the key is caller-controlled via _meta.session_id). - v1 resolve IPC honors boundSourceId like turn_context; turn-context runs its arms concurrently. doctor reads push/heartbeat thresholds from hook.ts. - new tests: doctor bootstrap checks, hook push-gate + deadline, concurrent sweep claims, cache eviction, bound-source resolve. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(bootstrap): origin-ownership gate, world visibility, collision-safe source id, consent + templates - repo adoption requires an exact receipt repo_url match or authed-owner check (undefined repo_url was a wildcard); create verifies privacy BEFORE the first push. - verify sets facts.default_visibility=world if unset, so agent-authored facts surface in per-turn context (they defaulted private before). - source_id derives a path-hash suffix when 'workspace' is taken by another checkout; every consumer reads manifest.source_id. - skipped HOOKS_CONSENT now declines (was falling through to default yes); --minimal refuses on an initialized manifest; tilde fences escaped. - MCP registration pins --surface full; status hard-fails a public origin (template door); receipt writers guard against newer/corrupt receipts; uninstall only claims brain-deleted after a real rm. - templates ship jobs disabled + provider-consent + support-relay lines; soul-audit re-runs over the shared interview bank. TODOS: 11 follow-ups. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): close adversarial-review findings — scan fails closed, whole-PEM redaction, bound repo push Cross-model adversarial pass (Claude + Codex) on the bootstrap wave: - secret scan fails CLOSED: an unreadable, oversized, or binary staged blob now blocks the push (blocked_unscannable, exit 5) instead of committing unscanned; only a confirmed staged deletion is skipped. This was the headline "block secrets before they leave the machine" property failing open. - private-key redaction spans the whole PEM block (header+body+footer), not just the header line — the base64 body no longer survives into the corpus the sweep sends to an extraction provider. - bootstrap repo commits the workspace (secret-scan-gated) before the first push and verifies the remote actually received it, so a push-fail retry can't adopt an empty remote as success. - privacy verify is re-bound to origin immediately before push (a concurrent origin rewrite between verify and push is refused). - session-end corpus write is atomic and clears the stale ingested/in-progress sidecars so a resumed session's appended transcript is re-ingested. - public-origin refusal enforced at render (not only status); MCP "already registered" is verified to target this workspace, not blessed blindly; verify probe cleanup scopes deletes to its own slugs, not a token substring; allowlist fingerprint floor raised 8→16 hex. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * v0.45.0.0 feat(bootstrap): paste-in personal-agent install for Codex + Claude Code Turns a Codex or Claude Code session into a persistent personal agent: interview-rendered identity files, a local PGLite brain, per-turn context via serve IPC (Claude Code hooks / Codex pull protocol), session-triggered persistence, and a private GitHub repo as the agent's portable body. Keyless- first (the harness model is the LLM; one optional key adds embeddings + extraction). New `gbrain bootstrap` command family + `gbrain hook` + `gbrain sweep`; doctor bootstrap health checks; latest-stable distribution ref + template-repo publish job. Opt-in, additive — existing installs untouched. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: regenerate flag registry for security-fix flags; drop fabricated gbrain capabilities doc ref CI caught two real failures under the merged state: - the flag registry lagged the blocked_unscannable/exit-5 flags the security round added, tripping the #2185 freshness guard. - headless-install.md described the keyless capability report as a `gbrain capabilities` command, which the #3502 doc-command resolver rejects — reworded to prose (the real surface is bootstrap verify's report). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: sync KEY_FILES + bootstrap plan to security-fix behavior Cross-referenced the security-fix round against the reference docs and corrected the drift those commits introduced: - workspace-push.ts entry: stage-FIRST-then-scan order (the TOCTOU fix), fail-closed blocked_unscannable, and the sources-push status -> exit-code map. - hooks.ts entry: MCP registration pins `serve --surface full`. - hook.ts entry: session-start/session-end pushes run in a detached child (non-blocking); atomic corpus write clears stale sidecars. - bootstrap.ts entry: render hard-refuses a public origin (template door). - verify.ts entry: source_id collision resolution (workspace-<path-hash>). - AGENT_BOOTSTRAP_PLAN as-shipped delta note for the scan/stage reorder. llms bundle unchanged (KEY_FILES is link-only); build:llms and test/build-llms.test.ts green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(ci): silence SC2016 on the intentional askpass literal in release.yml The one-shot GIT_ASKPASS script must contain literal $1 and $TEMPLATE_REPO_PAT so they expand when /bin/sh runs it at git's credential prompt, not when the outer shell writes the file — single quotes are correct. Add a scoped shellcheck disable so actionlint passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skills): declare 'bootstrap my data' trigger in cold-start frontmatter The doc reform added 'bootstrap my data' to cold-start's RESOLVER.md row (to disambiguate data-bootstrap from agent-bootstrap) but not to the skill's own frontmatter triggers, tripping the RESOLVER↔frontmatter round-trip contract (resolver.test.ts). Declare it; regenerate skills.lock.json. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(bootstrap): default per-turn hooks + search mode ON without a prompt Installing gbrain for your coding agent IS the consent for the behaviors that make it work, so stop re-litigating them with install-time questions whose "no" defeats the product: - Per-turn hooks (Claude Code) install ON by default — no prompt. Off-ramps: `--no-hooks` at install, `GBRAIN_HOOKS=0` at runtime, `bootstrap uninstall`. The "hooks installed" line now surfaces the kill switch so default-on is never silent. A persisted HOOKS_CONSENT=no (interview --skip) still declines. - Search mode defaults to `balanced` silently (nobody knows the modes at install; `gbrain search modes` changes it any time). - MCP scope stays the ONE deliberate prompt — project vs user is a real cross-repo privacy choice, not friction. Marks the two consents `silent: true` in the question bank (new QuestionSpec field), rewrites the runbook phases so the agent no longer asks them, adds the `--no-hooks` flag (+ registry regen), and adds default-on / opt-out tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(bootstrap): real end-to-end coverage — cross-session recall, per-turn content, Codex door, realistic corpus Closes the seven e2e gaps a coverage audit surfaced: the plumbing was well-unit-tested but the product claims ("Codex works, context shows up every turn with real content, it remembers across restarts, machine two recovers, Postgres works") were unproven end to end. Test-only wave — zero src changes. - Hermetic synthetic corpus (test/fixtures/bootstrap-corpus/ + a loader helper): 12 interlinked pages (52 edges, timelines), 12 world/private beliefs, 8 gold queries — curated from the gbrain-evals synthetic corpora, 100% placeholder names, so recall is asserted on a real multi-entity brain instead of a 2-node self-planted probe. - GAP1 magic moment: author a fact via the real write path, disconnect the engine, reopen against the same DB, recall it — a real session boundary, not verify.ts's same-connection SQL read-back. Plus a source-isolation assertion. - GAP2 per-turn content: hook-under-serve Pin 1 now seeds a known fact and asserts its text lands in the injected block AND private beliefs never do (was: empty brain, empty_block accepted as a pass). - GAP3 Codex door: assert the rendered AGENTS.md carries the Gate-3 brain-first pull protocol; make the fake codex shim implement `mcp get` so the [FIX7] target-verification can actually fail; the Docker cold-machine harness now exercises the hooks/MCP registration step instead of skipping it. - GAP4 corpus recall: turn-context + verify graph-floor/qrels run on the real multi-entity brain with real edges. - GAP5 attach: machine-two now re-ingests the cloned brain/ into a fresh DB and recalls a fact authored only on machine one — the multi-device payoff. - GAP6 keyed + Postgres (env-gated): real embeddings prove semantic recall a paraphrase query can reach but keyless BM25 cannot; bootstrap verify drives a real Postgres engine (skipIf DATABASE_URL/keys absent). - GAP7 persistence: session-end runs the REAL push (not the mocked seam) to a local bare remote and the remote receives the content; a planted secret is blocked at the gate; the 15-min cron installs and fires a scan-gated push. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(bootstrap): real-agent e2e — drive the actual claude + codex binaries end to end Closes the audit's biggest gap ("no real harness ever drives a turn"). Adapts gstack's PTY/headless agent harness to prove the bootstrap install + smoke work against the REAL binaries, not PATH shims. Test/CI/docs only — zero src changes. - test/helpers/agent-harness.ts: hermetic clean-room child env (ported from gstack; drops CONDUCTOR_/CLAUDE_/GSTACK_/MCP_/GBRAIN_, promotes GSTACK_ANTHROPIC_API_KEY→ANTHROPIC_API_KEY), real-binary resolvers + auth probes, headless `claude -p --output-format stream-json` and `codex exec --json` turn runners, a gbrain stdio MCP-config writer, and a keyless brain seeder. + a fixture-parse unit test (no binary needed). - test/e2e/bootstrap-real-claude.serial.test.ts: real `gbrain bootstrap` install → REAL `claude mcp add` (verified via `claude mcp get`) → verify exit 0 → a real `claude -p --mcp-config --strict-mcp-config` turn that invokes mcp__gbrain__search and answers from the brain (proven: toolCalls include mcp__gbrain__search, final text carries the seeded fact). - test/e2e/bootstrap-real-codex.serial.test.ts: same install with REAL `codex mcp add` into a real ~/.codex/config.toml + Gate-3 pull-protocol assertion, then a real `codex exec --json` turn surfacing the fact (MCP or the pull- protocol shell path). Bounded retry absorbs codex's occasional MCP-call cancellation without softening the fact-requiring assertion. - Everything hermetic (temp HOME/CLAUDE_CONFIG_DIR/CODEX_HOME/GBRAIN_HOME; real ~/.codex auth copied read-only) and skipIf-gated so it self-skips cleanly where the binaries/auth are absent. - heavy-tests.yml: gated `real-agent-e2e` job (nightly/label, never the PR shard; no-op on a runner without authed binaries). - TODOS: compiled `gbrain` binary can't serve a PGLite brain (bun compile omits the WASM/extension payloads); harness falls back to `bun run` serve. Verified against live claude 4.6 + codex 0.147.0: 15 pass / 0 fail; verify 36/36; typecheck clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(ci): real-agent-e2e job — bash array + --timeout (actionlint SC2086 + bun-test-timeout guard) The real-agent-e2e job's file loop used an unquoted $FILES (SC2086) and ran `bun test` without --timeout (check-bun-test-timeout guard). Switch to a bash array and add --timeout=600000 (real-agent turns are slow; the tests self-skip without authed binaries so it's a no-op elsewhere). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(pglite): embed WASM + extension assets so the compiled binary can serve A `bun build --compile` gbrain binary could not `serve` a PGLite brain: the compile bundles JS but not PGLite's runtime payload (pglite.wasm, initdb.wasm, pglite.data, vector/pg_trgm tarballs), so `serve` on PGLite died with a bunfs/ENOENT. Now the assets ride inside the binary. - src/core/pglite-embedded-assets.ts: embeds the five assets via `import … with { type: 'file' }` (the ENG-6 idiom) and exposes getEmbeddedPgliteOptions() → { pgliteWasmModule, initdbWasmModule, fsBundle, extensions:{vector,pg_trgm} }. WASM/fsBundle are consumed as bytes; the two extension tarballs are materialized to a content-addressed temp file (atomic, size-verified reuse) because PGLite reads them via fs.createReadStream, which cannot read a /$bunfs path. Unconditional (works in bun-run and compiled), so no fragile mode branch. - src/core/pglite-engine.ts: static-import getEmbeddedPgliteOptions (engine path stays static per the engine-dynamic-import invariant); spread into both PGlite.create sites (initial + WAL-repair retry). The bunfs classifier stays as a backstop but no longer fires for a correct binary. - scripts/check-pglite-embedded.sh (+ smoketest): compiles a focused binary and asserts it boots PGLite, CREATE EXTENSION vector/pg_trgm, and round-trips a page — wired into `bun run verify` (now 37 checks), check:all, and check:pglite-embedded. Fail-soft only when compile is unavailable. - agent-harness.ts probeCompiledPglite now passes → the real-agent e2e uses the fast compiled MCP server. TODOS: the P2 "can't serve PGLite" item is closed. Verified: fresh compiled binary ran `search`/`query` against a PGLite brain and returned the seeded row (no bunfs/ENOENT); verify 37/37; pglite-engine 120/0 source-mode; typecheck clean; engine-dynamic-import + parity guards pass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-08-11 16:42:11 -07:00
3 people	3c1cc8a4d6	v0.40.7.0 Schema Cathedral v3 — agent-on-ramp + production rebuild of PR #1321 (#1327) ... * v0.40.6.0 Phase 1 foundations — pack-lock + mutate-audit + cache invalidation + lint rules + best-effort Six new primitives that Phase 2's withMutation skeleton (next commit) depends on. No consumers yet; all callers wire up in Phase 4. Foundations ship first per codex C1 phase-ordering finding from /plan-eng-review. 1.1 pack-lock.ts (18 cases) Atomic acquire via openSync(path, 'wx') = O_CREAT|O_EXCL. Kernel-level atomic, NO TOCTOU window. Codex C8 caught that page-lock.ts:79+96 has existsSync+writeFileSync (TOCTOU) — we deliberately do NOT copy it. Stale detection via TTL (60s default) + kill(pid, 0) liveness probe. TTL refresh every 10s while withPackLock(fn) runs so long DB-aware lint/stats on big brains don't go stale. --force = "steal stale lock" (NOT "skip locking"). Lock path per-pack so two packs never block. 1.2 mutate-audit.ts (13 cases) ISO-week JSONL at ~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl. Privacy redacted per D20: type names → sha8, prefixes → first slug segment only. Matches candidate-audit.ts privacy posture. Both verbose surfaces gate on GBRAIN_SCHEMA_AUDIT_VERBOSE=1 (same env). Logs BOTH success AND failure events so Phase 9's schema_pack_writability doctor check has signal to read (closes codex C11). summarizeMutations() primitive shipped for cross-surface parity between doctor + future audit CLI. 1.3 registry.ts cache invalidation + stat-mtime TTL (10 cases) invalidatePackCache(name?) walks the extends-chain reverse-graph (every cached entry whose chain contains name is evicted). This is the codex C6 fix — pre-v0.40.6, editing a parent pack silently left children stale because cache identity was child-bytes-only. New per-name CacheEntry tracks the file-stat snapshot of every file in the extends chain. tryCachedPack(name) is the TTL-gated fast path: inside STAT_TTL_MS (1000ms default, env GBRAIN_PACK_STAT_TTL_MS) returns cached without statting. Outside the window: stats every file and cascade-invalidates on any mtime change (D11 cross-process detection). resolvePack reference-equality preserved on byte-identical re-build. ASCII state-machine diagram in file header (D9). 1.4 best-effort.ts (4 cases) loadActivePackBestEffort(ctx) returns ResolvedPack | null. Single source of truth for the 4 T1.5 wiring sites (Phase 8). null means "EMPTY FILTER" semantics, NOT "fall back to hardcoded defaults" — pack-load failure must be loud, per D4. Never throws. 1.5 lint-rules.ts (35 cases) 11 pure rule functions extracted from CLI handlers per codex C13/D16. 9 file-plane rules + 2 DB-aware rules (extractable_empty_corpus, mutation_count_anomaly). Phase 2 withMutation pre-write gate composes file-plane subset. runAllLintRules() returns {ok, errors, warnings} structured report ready for CLI + MCP. 1.6 query-cache-invalidator.ts (4 cases) invalidateQueryCache(engine, sourceId?) DELETEs query_cache rows so cached search results bound to old page types don't survive a schema mutation. Reuses SemanticQueryCache.clear() so we don't reinvent the PGLite+Postgres parity. Codex C9 fix. Tests: 84 new cases across 6 test files. All 153 schema-pack tests green. Plan: ~/.claude/plans/system-instruction-you-are-working-recursive-thacker.md Closes: half of T2-T7 from the plan's Implementation Tasks JSONL. Successor to: closed PR #1321 (community PR; author garrytan-agents). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.6.0 Phase 2 — mutate.ts withMutation skeleton + 11 primitives Builds on Phase 1 foundations (pack-lock, mutate-audit, lint-rules, cache invalidation, query-cache-invalidator). withMutation(packName, opts, mutator, op, ctx): 8-step skeleton wrapping every primitive. Atomic .tmp+fsync+rename. Per-pack file lock. Pre-write file-plane lint validation gate. Audit log on success AND failure. Pack cache + query cache invalidation hooks. ASCII state-machine diagram in file header per D9. 11 primitives, each ~5-line wrapper around withMutation: add_type, remove_type (with codex C14 reference check), update_type add_alias, remove_alias, add_prefix, remove_prefix add_link_type (rejects fm_links refs on remove) remove_link_type, set_extractable, set_expert_routing Inline minimal JSON→YAML emitter so mutating a YAML pack stays YAML. The emitter's array-of-mappings nesting was tricky: the first key sits inline with the `- ` (e.g. `- name: person`), subsequent keys live at indent+1, and nested arrays inside the mapping keep their relative depth (the v0.40.6 emitter bug I fixed pre-commit: trim+prefix lost internal indent of nested arrays like path_prefixes). YAML round-trip: emitted YAML reparses cleanly through parseYamlMini. Comments and formatting NOT preserved (documented in plan; pin pack.json if you care about layout). Codex C14 reference check: removeType refuses if any other type's aliases/enrichable_types/link_types/frontmatter_links references the target. STILL_REFERENCED error names every reference for cleanup. Validation gate composes runFilePlaneLintRules from Phase 1.5 — a mutation that would create a dangling ref or prefix collision fails BEFORE the .tmp write (the invariant: pack file on disk is NEVER partial). Tests: 34 cases pinning every primitive + skeleton invariant. Bundled guard, codex C14, atomicity (crash-mid-write leaves original untouched, lock auto-released after mutator throw), YAML round-trip, validation gate firing on prefix collision. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.6.0 Phase 3 — stats + sync pure core functions Both ship as runStatsCore / runSyncCore pure functions so Phase 4 CLI handlers (next commit) and Phase 7 MCP ops (later) both compose without duplicating logic. Codex C13 / D16 prereq for the MCP exposure phase. stats.ts (17 cases): Multi-source aware: sourceIds[] (federated read) OR sourceId (single) OR neither (whole-brain aggregate). NULLIF(type, '') normalizes empty-string + NULL to one untyped bucket (pages.type is NOT NULL in the schema so empty string is the legacy "untyped" representation). Soft-delete exclusion. by_type sorted by count desc, ties by name asc. Empty-brain coverage:1.0 (vacuous truth, matches getBrainScore). Dead-prefix detection: pack-declared prefixes with zero matching pages surface as DeadPrefixHint[] (agent's drilldown signal for mis-declared paths). Best-effort: pack-load failure leaves pack_identity:null + dead_prefixes:[]. sync.ts (13 cases): D14 chunked UPDATE: 1000-row batches per prefix. Each batch: WITH win AS (SELECT id FROM pages WHERE untyped+prefix LIMIT $batch), upd AS (UPDATE ... WHERE id IN win RETURNING 1) SELECT COUNT(*). Loop until zero rows. Concurrent writers never block on the row-set for more than ~100ms per batch (vs the multi-second monolithic UPDATE shape PR #1321 had). Codex C5 write-side scoping: sourceId param directly, NOT sourceScopeOpts which is read-side and inherits OAuth federation reads. Phase 7 MCP op (schema_apply_mutations) enforces at dispatch. Dry-run by default: per-prefix probe returns would_apply + 10-slug sample (the drilldown signal). Apply path returns total_applied. Idempotency contract pinned: second apply finds zero matching rows. Soft-delete exclusion on both probe + update. Dead-prefix flag set when probe returns count=0. JSON envelope schema_version:1. Tests use canonical PGLite block per CLAUDE.md test-isolation rules. seedPage helper auto-seeds sources(id) row before FK insert. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.6.0 Phase 4 — wire 14 new schema CLI verbs Thin handlers wrapping Phase 2's mutation primitives + Phase 3's stats/sync cores. CLI is the human surface; Phase 7 wires the same cores into MCP for agent use. New verbs: Authoring: add-type <name> --primitive P --prefix dir/ [--extractable] [--expert] [--alias A]* [--pack <name>] remove-type <name> [--pack <name>] update-type <name> [--extractable BOOL] [--expert BOOL] [--primitive P] [--pack <name>] add-alias <type> <alias> [--pack <name>] remove-alias <type> <alias> [--pack <name>] add-prefix <type> <prefix> [--pack <name>] remove-prefix <type> <prefix> [--pack <name>] add-link-type <name> [--inverse V] [--page-type T] [--target-type T] [--pack <name>] remove-link-type <name> [--pack <name>] set-extractable <type> BOOL [--pack <name>] set-expert-routing <type> BOOL [--pack <name>] Activation: reload [--pack <name>] Flush in-process cache; --pack scopes Discovery + repair: stats [--source <id>] Per-type counts + coverage + dead prefixes sync [--apply] [--source <id>] Backfill page.type (chunked UPDATE) cli.ts: schema added to CLI_ONLY_SELF_HELP so `gbrain schema --help` routes to printHelp() instead of the generic one-line stub. withConnectedEngine defensive fix retained from PR #1321: EngineConfig built once and passed to BOTH createEngine and engine.connect for future-proof against engine implementations that read URL at connect time. End-to-end agent journey verified: fork gbrain-base mine → use mine → add-type researcher --primitive entity --prefix people/researchers/ --extractable --expert → active (shows 23 page types) → stats (shows 100% coverage on empty brain, vacuous truth). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.6.0 Phase 5+6+7 — schema lint with rich rules + 9 new MCP ops This is the marquee commit: Wintermute and any other remote OAuth agent can now author + introspect schema packs over normal HTTPS MCP. Phases 5+6 collapse into Phase 7 because the new MCP ops compose Phase 1.5's lint rules and Phase 2/3's mutation/stats/sync cores directly — no extra extraction needed (D6 from /plan-eng-review). Phase 5: schema lint CLI wired to runAllLintRules from Phase 1.5 Replaces the prior 2-rule check (duplicate names + missing prefix) with the full 11-rule suite. New --with-db flag opts into the 2 DB-aware rules (extractable_empty_corpus, mutation_count_anomaly). JSON envelope shape stable. Exit code 1 on any error. Phase 7: 9 new MCP operations Read-scope (NOT localOnly — read scope is safe to expose remote): get_active_schema_pack — identity packet (pack name, sha8, counts). list_schema_packs — bundled + installed names. schema_stats — composes runStatsCore from Phase 3. schema_lint — composes runAllLintRules; --with-db is CLI-only (DB-aware rules need engine). schema_graph — JSON {nodes, edges} from link_types inference + frontmatter_links. schema_explain_type — settings for one declared type. schema_review_orphans — untyped pages drilldown. Admin-scope (NOT localOnly per D2 — Wintermute reaches via OAuth): schema_apply_mutations — BATCHED per D10. Single MCP tool taking a mutations[] array; composes all 11 mutate primitives. Atomic batch_id; outer withPackLock wraps the whole batch so no other writer can slip in mid-iteration. Partial-results returned on mid-batch failure for forensic agent debugging. Audit log records actor=mcp:<clientId8> (D20 privacy-redacted shape). reload_schema_pack — flush in-process cache + extends-chain cascade (codex C6 fix from Phase 1.3). withConnectedEngine defensive fix applied to schema.ts:withConnectedEngine (PR #1321 closed) — EngineConfig built once and passed to BOTH createEngine AND engine.connect for defense in depth. Test seams: - operationsByName lookup pinned for every new op. - All 9 ops have scope + localOnly declarations pinned to lock in the trust posture. - Batched mutation atomicity tested: partial-failure returns {error: mutation_failed, partial_results: [...]} with one batch_id across all results. - Audit log actor=mcp:<clientId.slice(0,8)> capture verified end-to-end (audit JSONL read back after the op handler runs). - Empty mutations[] rejected with invalid_request. - Unknown op surfaced via SchemaPackMutationError INVALID_RESULT. Coverage: 23 new cases for the 9 ops (operations-schema-pack.test.ts). All 255 schema-pack-related tests green. Plan: ~/.claude/plans/system-instruction-you-are-working-recursive-thacker.md Successor to: closed PR #1321. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.6.0 Phase 8 + 10 + 12 — T1.5 wiring, schema-author skill, ship Final wave commit. Brings the cathedral from "shipped but undiscoverable" to "shipped + agents find it + agents use it." Phase 8 (partial T1.5 wiring — agent-facing surfaces): - whoknows CLI (src/commands/whoknows.ts:340) consults the active pack via loadActivePackBestEffort + expertTypesFromPack. Pack-load failure → EMPTY filter (NOT hardcoded ['person', 'company'] defaults) per D4. A researcher type declared --expert in a custom pack now surfaces in `gbrain whoknows "ML"` results. Pre-v0.40.6 it silently never matched. - find_experts MCP op (src/core/operations.ts:2820) same wiring so OAuth clients (Wintermute etc.) inherit pack-aware expert routing over HTTP MCP, not just CLI. - facts/eligibility.ts and enrichment-service.ts union widening deferred to v0.40.7+ (filed in TODOS.md as 2 follow-up entries) — larger blast radius than fit this wave's context budget. Phase 10 (skill + RESOLVER + Convention — the discoverability layer): - skills/schema-author/SKILL.md — agent dispatcher for "evolve the schema pack." 36 trigger phrases route here. Explicit Non-goals section names brain-taxonomist (filing one page) and eiirp (schema-check during iteration) so agents pick the right surface. 7-phase workflow: brain → assess → propose → apply → sync → verify → commit. Lists every gbrain schema CLI verb + every MCP op the skill uses. brain_first: exempt frontmatter (this skill IS the brain-first path for schema authoring). - skills/conventions/schema-evolution.md — decision tree for "when to add a type vs alias vs prefix." <20 pages → don't pack-codify; 20-100 → alias or narrow prefix; 100+ → first-class type. Don'ts section + "when to remove a type" + "when to commit the pack" all answered from one place. - skills/RESOLVER.md entry with full functional-area dispatcher line (compressed routing pattern per v0.32.3 dispatcher convention). - schema-evolution.md added to the cross-cutting Conventions list. Phase 12 (ship bookkeeping): - VERSION → 0.40.6.0 - package.json → 0.40.6.0 - CHANGELOG.md entry with ELI10 lead per CLAUDE.md voice rules (250+ words explaining the wave in plain English before any file/function name appears), full "To take advantage of v0.40.6.0" paste-ready commands block, itemized changes by category, credit to @garrytan-agents (PR #1321 author). - TODOS.md gains 10 new follow-up entries grouped under "v0.40.6.0 Schema Cathedral v3 follow-ups (v0.40.7+)" covering: enrichment-service union widening, facts/eligibility wiring, 3 doctor checks, T16 + T16.1 evals, T19 federated closure, T20 extends merging, T21 YAML comments, T22 admin SPA, T23 schema:write scope, T24 multi-tenant federation. - llms-full.txt regenerated via bun run build:llms (CLAUDE.md edits trigger the test/build-llms.test.ts gate — required per repo discipline). Verification: - bun run typecheck clean. - Full agent journey smoke-tested end-to-end in Phase 4 commit (fork → use → add-type → active → stats — all green). - All 255+ schema-pack tests green from Phases 1-7. Total wave: 6 commits, ~5000 net LOC, 84 new tests, 21 design decisions captured. PR #1321 closed with successor pointer comment. Plan: ~/.claude/plans/system-instruction-you-are-working-recursive-thacker.md Co-Authored-By: garrytan-agents <garrytan-agents@users.noreply.github.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ci): rename Wintermute → 'your OpenClaw' + add schema-author skill conformance CI failures from PR #1327 first run: 1. check:privacy script flagged 4 'Wintermute' name leaks (CLAUDE.md:550 rule — never use the private OpenClaw fork name in public artifacts): - src/core/operations.ts:3816 → 'your OpenClaw and similar remote agents' - src/core/operations.ts:4015 → 'your OpenClaw, etc.' (in description) - src/core/operations.ts:4225 → 'your OpenClaw, etc.' (in comment) - test/operations-schema-pack.test.ts:325 → clientId 'remoteAgentClient12345678' (matching audit-actor regex updated: 'mcp:remoteAg' instead of 'mcp:wintermu') 2. skills/manifest.json missing schema-author entry. Added between brain-taxonomist and skillify per alphabetical-ish grouping. 3. skills/schema-author/SKILL.md missing 3 conformance sections per test/skills-conformance.test.ts: - ## Contract (inputs/outputs/side effects/idempotency/trust/atomicity) - ## Anti-Patterns (don't mutate bundled packs, don't add types for one-off directories, don't conflate filing vs. schema authoring, etc.) - ## Output Format (per-mutation JSON, per-batch JSON, stats JSON, sync dry-run JSON, human format, error envelope codes) The 3 sections were inserted ABOVE the existing 'Failure modes' section so the existing failure-mode bullets are still adjacent to the new error envelope codes in Output Format. Verified locally: - bun run check:privacy → clean - bun test test/skills-conformance.test.ts test/check-resolvable.test.ts test/check-resolvable-cli.test.ts test/regression-v0_22_4.test.ts → 286/286 pass - bun test test/operations-schema-pack.test.ts → 23/23 pass - bun run verify → clean (privacy + skill_brain_first + fuzz-purity + typecheck) llms.txt + llms-full.txt regenerated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: v0.40.7.0 — schema cathedral v3 README + CLAUDE.md annotations Doc-debt cleanup from the v0.40.7.0 ship (Phase 12 had deferred these to fit context budget; /document-release surfaced the gap): - README.md: new "What's new in v0.40.7.0" lead paragraph above the v0.36.4.0 entry. ELI10 lead: "Your agents can now author your brain's schema pack themselves" + the agent journey + 14 CLI verbs + 9 MCP ops + schema-author skill boundary callouts. - CLAUDE.md: new "Schema Cathedral v3 (v0.40.7.0)" section between the thin-client routing cluster and the Commands section. 14-bullet Key Files cluster covering pack-lock / mutate-audit / registry / best-effort / lint-rules / query-cache-invalidator / mutate / stats / sync / schema.ts CLI / operations.ts MCP / whoknows T1.5 wiring / schema-author skill / schema-evolution convention. Each bullet references the design decisions (D2/D4/D6/D8/D9/D10/D11/D13/D14/D20) and codex findings (C5/C6/C8/C9/C13/C14) captured during /plan-eng-review. Closes the "CLAUDE.md has zero v0.40.7.0 mentions" doc debt. - llms-full.txt + llms.txt regenerated. Privacy check clean (no Wintermute leaks in the new prose — used "your OpenClaw" per CLAUDE.md:550 rule). test/build-llms.test.ts 7/7 green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: tutorial — Build your first schema pack (closes v0.40.7+ doc-debt) Closes the tutorial gap surfaced by /document-release's Diataxis coverage map. The schema-pack cathedral shipped with reference (CLAUDE.md cluster), how-to (SKILL.md 7-phase workflow), and explanation (conventions/ schema-evolution.md decision tree), but no tutorial — no concrete "your first schema mutation" walkthrough. docs/schema-author-tutorial.md ships exactly that: - 8 numbered steps, time-to-first-result < 3 (active pack visible by step 2) - Walks from `gbrain schema fork gbrain-base mine` through `add-type researcher` + `sync --apply` + proving the T1.5 wiring via `gbrain whoknows` surfacing the new type - Every step shows the exact command and expected output - Placeholder pages (alice-example, bob-example, charlie-example) so any brain can run the tutorial without affecting real content - "What you built" section recaps state on disk + active wiring - "Next steps" cover add-link-type, add-alias, lint --with-db, commit to source control, MCP path for agents - "Related docs" cross-links to reference (CLAUDE.md cluster) + how-to (SKILL.md workflow) + explanation (schema-evolution.md) Cross-linked: - README.md "What's new in v0.40.7.0" paragraph gets a "Walkthrough:" pointer at the end - skills/schema-author/SKILL.md gets a "## Tutorial" callout just above the workflow phases — agents that hit the skill via RESOLVER routing see the tutorial pointer first Closes the Diataxis quadrant matrix to full coverage: - Tutorial: ✅ docs/schema-author-tutorial.md (NEW) - How-to: ✅ skills/schema-author/SKILL.md workflow - Reference: ✅ CLAUDE.md cluster + gbrain schema --help - Explanation: ✅ skills/conventions/schema-evolution.md Privacy check clean. Typecheck clean. llms-full.txt regenerated (545KB). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: what-schemas-unlock — the WHY doc (7 use cases + structural argument) The schema-author tutorial walks through HOW to mutate a pack. This new doc explains WHY agents and users should care, with concrete killer use cases on real corpus shapes: 1. The 4000 invisible meetings — untyped pages skip every structural surface (whoknows, find_experts, recall, think). Adding a `meeting` type + sync flips them from invisible to queryable. Same content, completely different agent experience. 2. The founder ops brain — 4 type-adds + 4 link-types build a CRM-shaped query surface. `gbrain whoknows "Series A SaaS"` routes through investor + portco specifically; `graph-query` walks intro chains. Downstream of notes, not parallel to them. 3. The research brain — researcher / paper / lab / grant / dataset types + cites / authored / uses link verbs turn a reading-list-as- markdown into a queryable research graph. 4. The legal brain (or anything where claims have numbers) — typed `damages=5000000`, `filed_date=...` become comparable across pages of the same type. Generic note systems can't do this because they don't know which numbers belong to which type. 5. The team brain — each mounted brain has its own schema pack. Two engineers searching the same brain get DIFFERENT routing because their personal packs declare different expert types. 6. The agent-co-curates pattern — the NEW thing in v0.40.7.0. Agent watches your ingestion stream, runs `gbrain schema detect` periodically, proposes a new type when a pattern accumulates, applies it via batched MCP `schema_apply_mutations` after one approval. Brain learns. Audit log captures the agent's client_id as `actor: mcp:<clientId8>`. 7. Before-vs-after on real content — pick a corpus, note top-3 whoknows results, add the type via sync, re-run. The numerical delta IS the win. Then the structural argument: types matter at query time. Untyped content is invisible content. The schema is queryable AND mutable AND auditable — that's the production-system difference from "vibes-based knowledge management." Closes with the v0.40.7.0-specific list of what changed (withMutation skeleton, O_CREAT|O_EXCL atomic lock vs page-lock.ts TOCTOU pattern, privacy-redacted audit log, 9 MCP ops, T1.5 wiring, cross-process invalidation via stat-mtime TTL gate). Cross-linked: - README.md "What's new in v0.40.7.0" paragraph now has both the "Why it matters:" pointer (this doc) AND the "Walkthrough:" pointer (tutorial). - docs/schema-author-tutorial.md opens with "Want the WHY before the HOW?" link to this doc. - skills/schema-author/SKILL.md now has a "Tutorial + vision" section that points at both, with explicit guidance that agents should read the WHY doc before pitching schema authoring to a user. 177 lines. Privacy check clean. Typecheck clean. llms-full.txt regenerated (545KB). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: surface schema docs from README Capabilities + Docs index + llms.txt The two new schema docs were ONLY linked from the v0.40.7.0 "What's new" paragraph in README. That paragraph will get pushed down by every future release and become a worse and worse entry point. Real discovery paths added: 1. README.md `## Capabilities` section — new "Agent-authored schema (v0.40.7.0)" bullet between "Brain consistency" and "## Integrations". Permanent home alongside Hybrid search, Self-wiring graph, Minions, 43 skills, Eval framework. Includes the one-paragraph pitch + 3 pointer links (vision / tutorial / agent skill). 2. README.md `## Docs` index — two new lines added at the top of the list (right after docs/INSTALL.md, before docs/architecture/): - docs/what-schemas-unlock.md with one-line description - docs/schema-author-tutorial.md with one-line description 3. scripts/llms-config.ts `Configuration` section — both docs added to the curated llms.txt entry list so the LLM-readable map points at them. Sits right after docs/GBRAIN_RECOMMENDED_SCHEMA.md (topical grouping). includeInFull defaults to true so they ride in the single-fetch llms-full.txt bundle. Result: schema docs are now reachable from 5 entry points instead of 1: - README "What's new" paragraph (release-pinned, will age out) - README Capabilities bullet (permanent, top-of-funnel) - README Docs index (permanent, end-of-page reference) - llms.txt (LLM-readable curated map) - llms-full.txt (single-fetch bundle for agents) Also caught 3 leftover Wintermute leaks in docs/what-schemas-unlock.md that the privacy check flagged: agent-co-curates pattern now uses "your OpenClaw"; `register-client wintermute` example renamed to `register-client my-agent` per CLAUDE.md:550 privacy rule. Privacy check clean. test/build-llms.test.ts 7/7 green. llms.txt 4314 → 5000 bytes, llms-full.txt 545KB → 572KB. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: garrytan-agents <garrytan-agents@users.noreply.github.com>	2026-05-23 16:46:01 -07:00