admin/gbrain
1
0
Fork 0
mirror of https://github.com/garrytan/gbrain.git synced 2026-08-14 00:48:18 +00:00
Code Issues Packages Projects Releases Wiki Activity
963 Commits 590 Branches 27 Tags
master
Commit Graph
6 Commits
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
Sina Matian aff34a428a v0.42.72.0 feat(auth): server-enforced slug-prefix write fence for OAuth clients + qm-harness integration guide (#3712) 
Registering an OAuth client with --bound-slug-prefixes now makes the write boundary real: writes outside the bound prefixes are refused on every op that can name a page, and ops that write by something other than a slug are refused outright rather than left unfenced. Deny-by-default at dispatch, so a write op added later is refused to bound clients until it is explicitly fenced.

Adds docs/integrations/qm-harness.md (gbrain as the company brain for a qm deployment) with a roster-driven provisioning script and deployment templates, plus a Known limitations section stating plainly that this is a write boundary and not a privacy boundary.

Five review rounds, including three clean-room passes by codex gpt-5.6-sol and Claude Fable 5 against an instruction-stripped tree.
 2026-08-02 07:05:13 +08:00
Garry TanandTime Attakc 298b6b01b8 fix(docs): remove references to the nonexistent gbrain install command (#3502) (#3545) 
Co-Authored-By: Time Attakc <89218912+time-attack@users.noreply.github.com>
 2026-08-01 07:40:48 +08:00
Time AttakcGarry TanClaude Fable 5
 		ef1133df3e docs(security): Docker network isolation for co-located self-hosted Postgres (#3270) (#3331) 
OAuth/source scoping only guards the serve --http path; a container
sharing Docker's default bridge with the brain's Postgres can open a
direct DB session without a token. Adds a 'Co-located Docker workloads'
subsection to docs/mcp/DEPLOY.md with the operator checklist, a
trust-boundary paragraph in SECURITY.md, and an ops note + cross-link
in the company-brain tutorial.

Fixes #3270

Co-authored-by: Garry Tan <garrytan@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
 2026-07-23 17:28:29 -07:00
Time AttakcClaude Fable 5Sinabina
 		a7b0ae80a9 v0.42.60.0 chore(release): eleven verified community fixes — changelog + version bump (#2888) 
* v0.42.60.0 chore(release): eleven verified community fixes — changelog + version bump

Windows full-sync mass-delete fix, gateway tool-loop resume consolidation
(fix-wave A), two source-isolation closes, search-cache exclude-policy
keying, and six more verified community fixes. Files the take-writes
fail-open source fallback and the #2112 doctor hunk as follow-up TODOs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: update reference docs for v0.42.60.0

- KEY_FILES.md: unpin stale KNOBS_HASH_VERSION number in the autocut entry
  (mode.ts is the single source of truth); document the full-sync reconcile
  path-separator normalization + mass-delete safety valve
  (planReconcileDeletes, GBRAIN_ALLOW_MASS_RECONCILE); describe the TTY-gated
  admin bootstrap token banner (--print-admin-token, env-sourced always hidden)
- docs/mcp/DEPLOY.md + docs/tutorials/company-brain.md: bootstrap token is now
  hidden on non-TTY starts; document GBRAIN_ADMIN_BOOTSTRAP_TOKEN and
  --print-admin-token for headless deploys

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore(docs): regenerate llms bundle after KEY_FILES/deploy-doc sync

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Sinabina <sinabina@Sinabinas-MacBook-Pro-4.local>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
 2026-07-16 19:30:09 -07:00
Garry TanandClaude Opus 4.7 af5ee1eb5a v0.40.8.1 docs: README rewrite + personal-brain + company-brain tutorials (#1345) 
* docs: rewrite README lead around search-vs-think differentiator

The current README opened with a generic "smart but forgetful" tagline that
buried the actual differentiator. Garry's 2026-05-23 X thread crystallized the
positioning: "Search gives you raw pages. Think gives you the answer." That
plus graph traversal plus gap analysis is what nobody else ships in one box.

Changes:
- README lead now leads with the search-vs-think frame, the "nobody else does
  this" claim, and the "strategic moat / so you don't lose context" framing.
- Collapsed five stacked "New in vX.Y.Z" paragraphs in the lead into one
  Recent Releases section after the install path, freeing the first viewport
  to be about what gbrain IS, not what shipped last week.
- New ## Search vs think section with side-by-side CLI example, gap-analysis
  explanation, and the find_trajectory + think compounding story.
- ORIGIN.md closing paragraph names think as the reason the brain is worth
  building.
- No em dashes used as connectors (per humanizer rules).
- All factual claims (page counts, benchmark numbers, version references)
  preserved verbatim.

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

* docs: add v0.40.6.0 to README Recent Releases

Picked up sync --all + per-source locks + sources status dashboard from
the v0.40.6.0 merge.

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

* docs(README): add visceral "what this looks like" before/after table

Pulled verbatim from BrainBench Cat 29 — same question, same brain, Haiku judge. Shows what a typical personal-knowledge brain (top-K vector retrieval, what MemPalace / Mem0 / Hindsight ship) returns vs what gbrain think returns. Search hallucinates three people who actually work at OTHER companies; think correctly identifies what's known + flags the gap. Score: search 1/10 vs think 9/10.

The before/after lands above Install so the reader sees concrete differentiation before they decide to install. Backs the abstract "search vs think" claim from the lead with a real receipt.

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

* docs(README): swap before/after example to verbatim Cat 29 receipt (Q2 ARR)

Per @garrytan — the prior example used the synthetic Q1 (employees of Horizon TECH 6) with paraphrased answer text. Replaced with the verbatim Cat 29 Q2 receipt: actual question (with the in-question typo that exists in the eval), actual truncated search-answer text from the JSON receipt, actual think-answer text with all three ARR readings + citations, and the actual Haiku judge verdicts pasted verbatim.

Also strips Mem0 + Hindsight references from the comparator phrasing — Mem0 is a YC company we don't want to single out, and Hindsight was a hackathon-stage project that never launched. The comparison phrasing now reads "MemPalace and most peer AI-memory stacks" — accurate without naming systems we shouldn't be benchmarking against.

The three things gbrain think did that a typical top-K retrieval cannot are listed below the table for readers who want the takeaway in plain English:
1. Caught the name typo (question said "Acme AI 0", brain has "Acme CO 0")
2. Walked the typed-claim Facts fence to build a chronological trajectory
3. Cited every claim

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

* docs(README): add "Your brain's shape (schema packs)" section

Per @garrytan — the README had nothing on schema packs (v0.38/v0.39
dynamic-schema cathedral). New section lands between "How to get data in"
and "Recent releases" so the narrative flow reads:

  what gbrain is → concrete example → install → query (search vs think)
  → get data in → schema packs (how the brain understands your shape)
  → recent releases → loop → capabilities → ...

The section opens by naming the differentiator out loud: "Most personal-
knowledge tools force one fixed layout: their idea of notes + people +
tags. Drop a Notion export or your own years-old Obsidian vault and the
agent doesn't know what your folders mean."

Three options surfaced:
  - gbrain-base (default, zero-config Garry layout)
  - gbrain-recommended (extends base with 13 more dirs)
  - your own pack via the schema detect → suggest → review-candidates
    three-command magical moment

Six representative CLI verbs shown verbatim. Closes with one paragraph
explaining the threading through every read/write path (parseMarkdown,
whoknows, extract_facts, search cache) and a one-line summary of the
7-tier resolution chain pointing at docs/architecture/schema-packs.md
for the full reference.

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

* docs(README): de-brand "Think" in the lead; reframe as GBrain's brain layer

Per @garrytan — "we don't need to brand it Think, we want to say the think
command later but we don't lead on it!"

Changes:

- Lead sentence: "Search gives you raw pages. Think gives you the answer"
  → "Search gives you raw pages. GBrain gives you the answer, through a
  brain layer." The product is GBrain; think is the CLI verb that runs
  the brain layer, introduced later.

- Two-bullet differentiator list: the "gbrain think" bullet now leads with
  the capability ("A synthesis layer that gives you the actual answer.")
  rather than the CLI command. The bullet body still names what the layer
  does (synthesized prose, citations, gap analysis).

- Strategic-moat paragraph: "`gbrain think` is what makes the moat
  usable" → "The brain layer is what makes the moat usable."

- "What this looks like" table header: "GBrain `think`" →
  "GBrain's brain layer (one synthesized answer, run via `gbrain think`)".
  CLI command stays in the cell so the example is reproducible; the
  framing leads with what it IS, not the verb.

- Three-bullet takeaway under the table: "Three things `gbrain think`
  did" → "Three things the brain layer did". Aggregate sentence: "gbrain
  think averages 5.60/10" → "GBrain's synthesis layer averages 5.60/10".

- Section heading: "## Search vs think" → "## Two ways to query your
  brain". The section still introduces `gbrain search` and `gbrain think`
  as the two CLI verbs side by side; the heading no longer brands "think"
  as the thing.

The "think command" comes through naturally where it appears as a CLI
example. The PRODUCT is GBrain.

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

* docs(README): switch to first-person voice (Garry speaking directly)

Per @garrytan — drop "Built by..." third-person framing and write in
first person.

Edits:
- Lead credibility paragraph: "Built by the President and CEO of Y
  Combinator to run his actual AI agents" → "I'm Garry Tan, President
  and CEO of Y Combinator. I built GBrain to run my own AI agents."
  Subsequent sentences switch "his deployments" → "my deployments",
  "the agent ingests... you wake up smarter" → "my agent ingests...
  I wake up smarter — and so will you" (the closing "and so will
  you" connects Garry's experience to the reader's).
- Compounding paragraph: "As Garry's personal agent gets smarter, so
  does yours" → "As my personal agent gets smarter, so does yours."
- Schema packs section: "the layout used by Garry's production brain"
  → "the layout my production brain uses".
- License + credit: "Built by Garry Tan to run his OpenClaw and
  Hermes deployments — the production brain behind his actual AI
  agents" → "I built GBrain to run my OpenClaw and Hermes deployments
  — the production brain behind my AI agents."

The whole top of the README now reads as Garry talking directly to
the reader about what he built and why.

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

* docs(README): DRY the lead — drop redundant "through a brain layer" + repeat GBrain

"GBrain gives you the answer, through a brain layer. GBrain is the brain
layer your AI agent has been missing..." — two GBrains, two brain layers.
Tightened to: "GBrain gives you the answer. It's the brain layer your AI
agent has been missing — the only one that does synthesis, graph
traversal, and gap analysis in one box."

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

* docs(README): frame GBrain as a company brain too, link to YC RFS

Per @garrytan — GBrain is now usable as a company brain (federated sync,
OAuth scoping, Cat 22 source isolation), and YC just put company-brain
on its Request for Startups.

Added a paragraph after the personal-brain lead that names the three
v0.34+ features that make multi-user safe (federated sync, per-source
OAuth scoping, the Cat 22 leak-free source isolation), then links to
https://www.ycombinator.com/rfs#company-brain with a one-line pitch:
"if you're building in that space, you might as well build on this."

The framing carries forward the personal-brain story while opening the
aperture: GBrain works for one person (Garry's production deployment)
AND for a team (per the features Cat 22 just verified).

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

* docs(README): rewrite company-brain paragraph in plain English

@garrytan caught me writing internal eval-suite jargon ("Cat 22 proves
source isolation is leak-free across hybrid search, listPages, getPage,
and federated reads") in a paragraph aimed at someone deciding whether
to use GBrain. Rewritten in plain English:

  "Each person on the team gets their own slice of the brain, scoped
  by login. When you query, you only see what you're allowed to see —
  never another person's notes, never another team's data. We fuzz-
  tested this across every way you can read the brain (search, list,
  lookup, multi-source reads) and got zero leaks."

Same factual content, zero internal vocabulary. The "Cat 22" name
belongs in the benchmark page, not the front-door README.

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

* docs(tutorials): add company-brain tutorial (Diataxis tutorial quadrant)

End-to-end walkthrough for setting up GBrain as a multi-user company
brain. Audience: founder / CTO / head of ops at a 10-50 person company
who has heard about GBrain (from the YC RFS company-brain page or my
tweets) and wants to set it up as their team's shared institutional
memory. ~3700 words, written for a learner with zero prior gbrain
knowledge.

Twelve parts walk the reader from "I've never run gbrain" to "three
teammates each query the brain through their own AI agent and see the
correctly scoped answer":

  1. The mental model (personal brain vs company brain, federated
     sources, OAuth scoping, what you get)
  2. Prerequisites table (Postgres, embedding key, Anthropic key, git
     repo, Bun, host machine + cost projection)
  3. Install + Postgres + API keys + doctor verify
  4. Create three sources (shared / customers / internal) + sync
  5. Spin up HTTP MCP server with --bind 0.0.0.0 + --public-url
  6. Register one OAuth client per teammate with --source +
     --federated-read
  7. Verify scoping works (alice can't see internal, bob can't see
     customers)
  8. Connect each teammate's AI agent via thin-client install
  9. First real `gbrain think` query showing sourced + synthesized +
     gap-analysis answer
  10. Operating the brain (autopilot, doctor --remediate, sources
      status, admin dashboard)
  11. Cost + speed expectations from the v0.40.6.0 benchmark
  12. Common gotchas + troubleshooting

Voice:
- First-person Garry in intro / motivation paragraphs
- Zero internal jargon. No "Cat 22", "P@5", "knobsHash", "RRF", "MRR"
- Plain English throughout
- No em dashes used as connectors (zero in final draft)
- "Brain layer" / "synthesized answer" framing, not "Think" branding
- No Hindsight, no Mem0 (per repeated session feedback)
- Every example uses placeholder names (alice-example, bob-example,
  acme-co)

Cross-linked from:
- README.md company-brain paragraph
- docs/INSTALL.md (under the migrate --to supabase block)
- docs/architecture/topologies.md (See also section)

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

* docs(README): drop version chatter, add Tutorials section, expand tutorial roadmap

Per @garrytan: the README should read as the current docs written for
people who have never known GBrain before. Versions are what the
CHANGELOG is for.

Version-chatter sweep across the README:

- Killed the entire ## Recent releases section. That's a changelog
  summary, not docs. CHANGELOG.md owns it.
- Stripped "(v0.38+)" from the ## How to get data in heading.
- Rewrote "(the v0.38 put_page write-through plumbing)" as
  "(the database and on disk in one move)" — describes WHAT happens,
  not WHEN it shipped.
- Stripped "(The legacy gbrain skillpack install managed-block model
  was retired in v0.36.0.0; run gbrain skillpack migrate-fence once if
  you're upgrading from an older release.)" from the skillpack
  paragraph. Upgrade history goes in the CHANGELOG.
- Stripped "New in v0.40.4.0:" from the hybrid-search graph-signals
  description. Just describes what the feature does.
- Stripped "As of v0.37," from the embedding-provider auto-detect
  paragraph in the Troubleshooting section.
- Stripped "the embedding + reranker stack that became the v0.36.2.0
  default" → "ships as the default" in the License + credit section.
- Stripped "in Cat 29" from the synthesis-benchmark sentence (same
  internal-jargon class as Cat 22 which @garrytan called out earlier).

Replaced ## Recent releases with ## Tutorials:

- Links to the one shipped tutorial (company-brain.md) with a
  one-line description.
- Names the next several planned tutorials in prose (not as broken
  links): personal brain quickstart, connect your agent, VC dealflow,
  vault migration, code brain. No fake links.
- Points at the tutorial index page for the full roadmap.
- Closes with "Open an issue describing the workflow you want
  documented" to invite prioritization input from real users.

New tutorial index at docs/tutorials/README.md:

- Shipped section: company-brain.md
- In-progress roadmap with 7 candidate tutorials (personal brain
  quickstart, connect your agent, VC dealflow, vault migration, code
  brain, fully local, dream cycle setup)
- Each roadmap entry names the persona, the core commands the
  tutorial would demonstrate, and the differentiator
- "Want to write one?" section invites community PRs and points at
  company-brain.md as the model

Reverted the obscure topologies.md "See also" link from pointing at
company-brain.md specifically to pointing at the tutorials index
overall — the tutorial belongs in the README's Tutorials section
where users actually look, not buried in an architecture doc.

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

* docs(tutorials): land personal-brain tutorial (full-stack install)

The canonical solo install walkthrough, adapted from Garry's live setup
session notes (the "Apple I, soldering breadboards" session). Builds the
full stack: 2 GitHub repos, Telegram bot, AlphaClaw on Render, OpenClaw
+ GBrain + Supabase. About 2 hours end-to-end, $100-150/month sustained.

Replaces the "Set up your personal brain in 30 minutes" stub on the
tutorials roadmap with something genuinely complete.

Edits to the source draft:
- Stripped brain-page YAML frontmatter (type/access/links/etc — not
  needed for a public docs file)
- Privacy sweep per CLAUDE.md: removed real-name references to the
  collaborator and the agents involved in the session, replaced with
  "a collaborator" / "my main agent" / generic placeholder names
- First-person voice consistency: the source draft slipped between
  first person and third person ("Garry walked through"); rewrote
  everything in first person
- Zero em-dashes used as connectors (verified by grep)
- Added ZeroEntropy to the providers list (it's the default; not
  mentioning it would leave readers paying 2.6× more on embeddings)
- Opened with a router paragraph that points brain-layer-only readers
  at INSTALL.md and team readers at company-brain.md, so each
  audience finds the right walkthrough fast

Tutorials index updated:
- personal-brain.md promoted from In Progress to Shipped (it IS the
  "set up your personal brain in 30 minutes" entry that was on the
  roadmap, just better-named and more complete)

README.md Tutorials section now lists both shipped tutorials side by
side. Reads naturally: solo install first (broader audience), team
install second.

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

* docs(tutorials): rewrite company-brain as a true superset of personal-brain

Per @garrytan: the company brain tutorial should pick up from where the
personal brain tutorial leaves off, not duplicate the install. Pedagogical
flow now reads: "you already did personal-brain; here is what to add
to make it multi-user."

Restructure:

- Opens with explicit "this tutorial picks up where the personal brain
  tutorial leaves off" + a router for readers who haven't done that one
  yet. No duplicated install steps.
- Part 1 (mental model) reframed as "what changes when you go from
  personal to company" + "what this is NOT" (not a different install,
  not a thin-client-everywhere replacement).
- Part 2 is now "switch the brain backend to multi-user Postgres" —
  surfacing the migrate --to supabase path for readers who started on
  PGLite, skip-to-Part-3 for readers already on Postgres.
- Part 3 adds the new content @garrytan called for: per-person folder
  structure inside each source. customers/alice-example/, internal/
  alice-example/, internal/bob-example/, internal/legal/ etc. So
  teammates' writes don't collide and the per-person/per-role
  abstraction is real on disk, not just in OAuth scope.
- NEW Part 6: per-person crons. Each teammate gets their own
  scheduled tasks (7am customer digest for alice, 9am ops status for
  bob, weekly contract compliance for carol) scoped to their OAuth
  client so the cron can only touch their slice.
- NEW Part 7: per-person skills. The 60+ shipped skills are generic;
  teams want a few specific ones (onboarding-new-hire,
  customer-success-followup, weekly-team-digest). Scaffolded via
  gbrain skillify scaffold, scoped via allowed_clients in
  frontmatter.
- Existing strong parts retained: OAuth scoping + verify, per-
  teammate AI client connect, first synthesized query, operating
  notes, gotchas. Reworded where needed to refer back to personal-
  brain steps instead of re-explaining them.

Voice + style sweeps:
- Zero em-dashes used as connectors (verified by grep)
- Zero internal jargon (no "Cat 22", "P@5", "RRF", "MRR", etc.)
- Zero version chatter in body text (only the one acceptable
  reference to the dated benchmark filename in a docs link)
- "Brain layer" / "synthesized answer" framing, not "Think" branding
- First-person Garry voice in intro/motivation paragraphs
- All examples use placeholder names (alice-example, bob-example,
  carol-example, acme-co, diana-example)
- No mentions of Mem0 / Hindsight (per session-long convention)

Word count: 3608 (vs 3717 before — about the same length, but more
of those words now describe the NEW content rather than re-explaining
prereq install).

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

* docs(tutorials): enrich company-brain with real-world patterns from production deployment

Mined production patterns from my own running company-brain deployment
to ground the tutorial in shapes that actually work. Added four
substantive sections.

Part 3 (sources) gains "Two scoping models" sidebar:

- Model A: separate sources with OAuth scoping (SQL-enforced isolation,
  right for multi-user with different AI clients per person — what the
  tutorial walks you through).
- Model B: one source with partners/<slug>/ directory convention
  (simpler ops, scoping is convention-only, right when one agent serves
  everyone over Telegram — what I actually run in production).
- Mix-and-match guidance: separate sources for the obviously-different
  ones AND partners/<slug>/ inside the shared source for per-person
  workspace.

Part 7 (skills) gains "Shared rule files at the skills root" subsection:

- _brain-filing-rules.md: iron-rule decision tree for where new pages
  belong. Every ingest skill consults it before creating a page.
- _output-rules.md: output quality standards (deterministic links built
  from API data not LLM-composed strings, citation format, no AI-slop).
- _excluded-people.md: privacy gate naming people the brain must never
  reference even when they appear in source material. Re-attribute or
  discard. The file that prevents accidental publication of things
  about people who aren't fair game.
- _operating-rules.md, _x-ingestion-rules.md, _x-api-rules.md.
- These turn into the de facto company policy for the agent. Edit one,
  every skill picks it up next request.

NEW Part 8 "Wire Slack carefully":

- Two crons, two jobs (scan every 5-15min for live signals + archive
  nightly for full history).
- Channel-to-task-ID mapping via topic-registry.json (don't reference
  raw Slack channel IDs in skills; friendly names that resolve at
  runtime).
- Deterministic links rule (LLM-composed Slack URLs hallucinate
  constantly; build from API data only).
- Dismissed-items state so re-scans don't surface noise that was
  already triaged.
- Per-channel scoping mirrors per-person scoping. Sensitive channels
  scope by OAuth client.
- Names the actual production skills (slack, slack-scan, slack-archive)
  for scaffold reference.

NEW Part 9 "Onboard each teammate yourself (the botmaster pattern)":

- The load-bearing UX gate for adoption. Don't hand a teammate an
  OAuth credential and tell them to "try it out." That's how internal
  tools die.
- Step 1: pre-populate their slice (partners/<their-slug>/USER.md
  with role/focus/priorities/preferences, 5-10 concepts that are
  theirs, 2-3 example brain entries that demonstrate the shape).
  About 20 minutes per teammate.
- Step 2: walk them through 2-3 wow flows personally. A synthesis
  query (show the brain layer). A gap-analysis query (build trust).
  A write-back flow (show capture value). About 15 minutes.
- Step 3: graduate to DM only after the wow moment lands. The order
  flips the conversion rate.
- About 45 minutes per person total. Cheaper than an unadopted tool.

Parts 8-12 renumbered to 10-14 to make room. Cross-references in body
text checked (Part 3 ref in Part 5, Part 4 ref in operating notes,
Part 5 ref in Slack section all still correct).

Word count: 4938 (vs 3608 before). Still readable in one sitting per
the original target; added content is all load-bearing patterns from
production.

Voice gates:
- Zero em-dashes used as connectors (sed-replaced all 8 introduced
  by the additions with periods)
- Zero internal jargon (no Cat N, no P@5, no RRF, no MRR)
- Zero banned names (no Brad, Gessler, Wintermute, Zion, Straylight,
  Seibel, Caldwell, Mem0, Hindsight)
- "Brain layer" / "synthesized answer" framing preserved
- First-person Garry voice throughout
- All examples use placeholder names (alice-example, bob-example,
  carol-example, diana-example, acme-co)

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

* docs(tutorials): expand personal-brain Step 7 with the three real Supabase gotchas

@garrytan: the personal-brain tutorial needs to surface the specific
Supabase setup gotchas I hit the hard way. Rewrote Step 7 with the
operational detail.

Three new subsections:

- 7a: Turn on pgvector. The vector extension has to be toggled in
  Database → Extensions before GBrain's schema migrations will run.
  Five seconds in the dashboard, an hour of debugging if you forget.

- 7b: Use the CONNECTION POOLER string, not the direct connection.
  Direct is port 5432, IPv6-only. Pooler is port 6543 via pgbouncer,
  IPv4-compatible, survives connection storms from parallel workers.
  Shows the exact pooler hostname format and the gbrain config set
  command.

- 7c: Buy the IPv4 add-on. About $4/month. Even with the pooler, some
  Supabase regions / Render plans hit IPv6 resolution snags. Symptom:
  network-unreachable errors or connect hangs in gbrain doctor.
  Toggle on in Project Settings → Add-ons. Saves debugging time on
  multiple installs.

- 7d: Verify with gbrain doctor — names which of 7a / 7b / 7c to
  revisit if a check fails.

The old "Operating note" about Supabase being the scaling bottleneck
preserved at the end of the section since it's a different concern
(scale, not setup).

Voice gates: 0 em-dashes (verified), first-person Garry voice ("I hit
the hard way"), no internal jargon, no banned names.

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

* docs(README): rewrite "What this looks like" for someone arriving cold

@garrytan: the prior version assumed too much. "Eval receipt", "top-K
vector retrieval", "MemPalace", "Haiku judge", "Facts fence", "synthesis
layer" — all jargon that requires reading the rest of the project to
parse. A new reader bounces.

New version requires zero prior context:

- Sets up a universal scenario anyone gets: "you have a meeting with
  alice tomorrow, what do you need to know?"
- Shows what a typical tool returns (a list of 5 pages with snippets)
  so the reader sees the gap themselves
- Shows what gbrain returns (a real briefing with the open items
  surfaced, plus a "heads up" about what's missing from the brain)
- Lets the two outputs speak for themselves, no judge scores or
  benchmark numbers in the body
- Closes with one plain-English sentence on the difference:
  "Search finds the pages. The brain reads them for you and writes
  the answer."

What got cut:
- The eval-receipt path reference (means nothing to a new reader)
- The Haiku judge scores (0/10 vs 9/10) — not useful out of context
- The verbatim judge verdict quotes (long, internal vocabulary)
- The "Facts fence", "typed-claim", "synthesis layer" feature names
- The MemPalace name-drop
- The link to the comprehensive benchmark page (it's still
  reachable from the Tutorials and benchmark sections; doesn't
  need to be in the intro)
- The numbered "three things gbrain think did" breakdown

The example content is illustrative (same scenario shape as a real
production query) but stripped of the internal benchmark wrapper.
Reads naturally as "imagine you're about to ask gbrain something."

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

* docs: capitalize proper-noun names in prose across README + tutorials

@garrytan caught lowercase "alice" in prose — proper nouns should be
capitalized. The lowercase was leaking from the slug convention
(people/alice as the actual storage slug) into descriptive text.

Rule applied: capitalize Alice / Bob / Carol / Diana / Acme when used
as a person or company name in prose. Keep lowercase in:
- Slugs and file paths (people/alice, customers/acme-co)
- Code identifiers in fenced blocks where the slug IS the value
- URLs and hostnames (brain.acme-co.com)
- Channel-name-style references (#alice-customers)

Files swept: README.md, docs/tutorials/company-brain.md,
docs/tutorials/personal-brain.md, docs/tutorials/README.md.

The README sweep was the primary target (Garry's actual call-out);
the tutorial sweep keeps voice consistent across all the front-door
docs. Hand-fixed four occurrences inside code-fenced blocks that
were human comments rather than code (terminal session comments
"# Terminal 1, as Alice", "# Terminal 2, as Bob", directory-tree
inline comments "← Alice's customer notebook").

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

* test(readme-hero-anchors): rotate ZeroEntropy anchor → search-vs-answer headline

CI caught one expected regression after v0.40.8.1's README rewrite. The
D9 hero-anchors guard required "ZeroEntropy" in the first 50 lines of
README.md (the v0.36.0.0 default story). The post-rewrite hero
intentionally rotated that out per Garry's "no version chatter in
README" directive — ZeroEntropy still appears further down (line 211,
231, 279) but no longer in the hero. The guard's docstring explicitly
handles this case: "did we deliberately rotate the headline? If yes:
update the anchors here."

Rotation:

- Dropped: regex /ZeroEntropy|\bZE\b/ in the first 50 lines
- Added: regex matching the new headline "Search gives you raw pages.
  GBrain gives you the answer." which is the load-bearing differentiator
  of the post-rewrite hero. If a future cleanup PR accidentally rewords
  the search-vs-answer framing, the new anchor catches it the same way
  the ZeroEntropy anchor caught accidental drops before.

Other 4 anchors unchanged (OpenClaw + Hermes + production-number +
P@5/R@5 — all still load-bearing).

Updated docstring records the v0.40.8.1 rotation as the audit trail
for the next time this happens.

Verified: `bun test test/readme-hero-anchors.test.ts` → 5 pass / 0 fail.

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

* docs(README): restore agent-led install path + per-client MCP guides

The README install section had collapsed to three generic shapes
("agent platform", "CLI", "MCP server") that buried the load-bearing
flow: paste a URL pointing at INSTALL_FOR_AGENTS.md into your agent and
let it do the work. That's the path most users actually take.

Restored the original three-tier structure with an explicit second tier
for "install it into your existing agent" (Codex, Claude Code, Cursor),
plus surfaced the per-client MCP guides individually so users see the
command shape they actually need instead of one generic docs/mcp/ link.

Six per-client MCP links now in the README itself: Claude Code,
Cursor/Windsurf (stdio), Claude Desktop, Claude Cowork, Perplexity
Computer, ChatGPT. Each carries the one-line shape that matters
(claude mcp add, Settings > Integrations, OAuth 2.1, etc.).

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

* docs(README): link personal-brain tutorial from the agent-install path

People landing on the README without an existing OpenClaw or Hermes
deployment need a starting point that walks the whole flow, not just
"paste this URL into your agent." The personal-brain tutorial already
covers picking a platform, deploying it, pointing it at
INSTALL_FOR_AGENTS.md, and verifying the first query.

Surfaced as a callout right under the agent-install snippet so the path
is visible to first-time users without burying the experienced-user
flow.

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-24 00:00:39 -07:00