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>

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to GBrain will be documented in this file.
 
+## [0.40.8.1] - 2026-05-23
+
+**The README and tutorials are rewritten for someone who has never touched GBrain.** The front-door docs now read as a story you can understand cold: what GBrain does, what it looks like, how to install it, two real walkthroughs that take you from zero to a working brain. No internal jargon, no version archaeology, no assumed context.
+
+The big rewrite covers:
+
+- **README lead** rewritten in first-person voice. Opens with "Search gives you raw pages. GBrain gives you the answer." Frames GBrain as both a personal brain and a company brain, with a link to YC's company-brain Request for Startups.
+- **"What this looks like" section** is now a concrete meeting-prep scenario any professional gets cold: you ask "what do I need to know before my meeting with Alice tomorrow?", you see what a typical retrieval tool returns (a list of 5 pages), you see what GBrain returns (a synthesized briefing with citations and a gap-analysis note). No eval jargon, no judge scores, just the two answers side by side. Closes with "search finds the pages, the brain reads them for you and writes the answer."
+- **New `## Tutorials` section** in the README. Replaces the prior `## Recent Releases` changelog summary (that lives in this file, where it belongs).
+- **New `## Your brain's shape (schema packs)` section** in the README explains the dynamic-schema cathedral in plain English: drop your Notion export or your custom layout, run `gbrain schema detect`, the brain adapts to your shape instead of forcing you to learn its.
+- **All version chatter stripped from the README body.** Per the iron rule "the README should read as the current docs written for people who have never known GBrain before." Version history belongs in this file.
+
+Two new end-to-end tutorials in `docs/tutorials/`:
+
+- **`personal-brain.md`** — the canonical full-stack solo install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. About two hours, $100-$150 a month. Includes the three Supabase gotchas every install hits (turn on the `vector` extension, use the connection pooler not the direct connection, buy the IPv4 add-on).
+- **`company-brain.md`** — extends the personal brain into a multi-user shared brain for a 10-50 person team. Federated sources with OAuth-scoped per-user reads, per-person folder conventions, per-person crons, per-person skills, the Slack integration callout (two-cron architecture, channel-to-task-ID mapping, deterministic links, dismissed-items state), and the botmaster onboarding pattern (pre-populate each teammate's slice → walk them through 2-3 wow flows → graduate them to DM only after the wow moment lands).
+- New tutorial-roadmap index at `docs/tutorials/README.md` listing what shipped and what's planned (connect-your-agent, VC dealflow brain, vault migration, code brain, fully-local brain, dream-cycle setup).
+
+Cross-linked from the relevant architecture docs (`docs/INSTALL.md` for the install-path readers, `docs/architecture/topologies.md` for the design-doc readers).
+
+`bun run build:llms` regenerated to pick up the doc structure changes.
+
+### Itemized changes
+
+- `README.md` — first-person lead rewritten; "Search vs Think" section retitled "Two ways to query your brain" (think is a CLI verb, not a brand); company-brain framing paragraph added with YC RFS link; Tutorials section added; `## Your brain's shape (schema packs)` section added; `## Recent Releases` section removed (changelog summary belongs in CHANGELOG.md); all `(v0.X+)` version cites stripped from body; proper-noun capitalization sweep (`alice` → `Alice` in prose, slug forms unchanged); the visceral before/after example rewritten as a universal meeting-prep scenario with zero internal jargon.
+- `docs/tutorials/personal-brain.md` (new) — solo install walkthrough sourced from the live setup session notes. ~2000 words. Includes the three Supabase gotchas (pgvector, connection pooler, IPv4 add-on) in their own subsection.
+- `docs/tutorials/company-brain.md` (new) — multi-user walkthrough, restructured as a true superset of personal-brain (no duplicated install steps). ~5000 words. Covers two scoping models (separate sources with OAuth scoping vs `partners/<slug>/` directory convention in one source), shared rule files at the skills root (`_brain-filing-rules.md`, `_excluded-people.md`, `_output-rules.md`), Slack wiring conventions, and the botmaster onboarding pattern.
+- `docs/tutorials/README.md` (new) — tutorial-roadmap index page.
+- `docs/INSTALL.md` — pointer to the company-brain tutorial in the shared/multi-machine deployment section.
+- `docs/architecture/topologies.md` — pointer to the tutorials directory in the "See also" section.
+- `docs/ethos/ORIGIN.md` — closing paragraph naming the synthesis layer as the reason the brain is worth building.
+- `llms-full.txt` + `llms.txt` — regenerated.
+
 ## [0.40.8.0] - 2026-05-23
 
 **Your doctor checks, your operations trust boundary, and your cycle phases now have real behavioral tests — not just source-grep guards.**

README.md

@@ -1,73 +1,155 @@
 # GBrain
 
-Your AI agent is smart but forgetful. GBrain gives it a brain.
+**Search gives you raw pages. 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.
 
-Built by the President and CEO of Y Combinator to run his actual AI agents. The production brain behind his OpenClaw and Hermes deployments: **146,646 pages, 24,585 people, 5,339 companies**, 66 cron jobs running autonomously. The agent ingests meetings, emails, tweets, voice calls, and original ideas while you sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. You wake up smarter than when you went to bed.
+I'm Garry Tan, President and CEO of Y Combinator. I built GBrain to run my own AI agents. It's the production brain behind my OpenClaw and Hermes deployments: **146,646 pages, 24,585 people, 5,339 companies**, 66 cron jobs running autonomously. My agent ingests meetings, emails, tweets, voice calls, and original ideas while I sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. I wake up smarter than when I went to bed — and so will you.
 
-The brain wires itself. Every page write extracts entity references and creates typed links (`attended`, `works_at`, `invested_in`, `founded`, `advises`) with zero LLM calls. Hybrid search. Self-wiring knowledge graph. Structured timeline. Backlink-boosted ranking. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked side-by-side: gbrain lands **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, beating its graph-disabled variant by **+31.4 points P@5** and ripgrep-BM25 + vector-only RAG by a similar margin. Full BrainBench scorecards live in the sibling [gbrain-evals](https://github.com/garrytan/gbrain-evals) repo.
+**And now it works as a company brain too.** 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. Drop GBrain in as your team's shared institutional memory — the [company-brain](https://www.ycombinator.com/rfs#company-brain) shape YC just put on its Request for Startups. If you're building in that space, you might as well build on this. **[Tutorial: set up GBrain as your company brain →](docs/tutorials/company-brain.md)**
 
-**New default in v0.36.2.0: ZeroEntropy** for both embedding (`zembed-1` at 1280d via Matryoshka) and reranker (`zerank-2`). On a real-corpus benchmark vs OpenAI and Voyage: **2.2× faster** (442ms vs OpenAI 973ms), **2.6× cheaper at regular pricing** ($0.05/M vs OpenAI $0.13), wins 11 of 20 queries head-to-head, reshuffles 60% of top-1 results when used as a second-pass reranker. Bring your own key from [zeroentropy.dev](https://dashboard.zeroentropy.dev), or switch to OpenAI/Voyage at install time via `gbrain init --pglite --embedding-model <provider:model> --embedding-dimensions <N>` — your choice is sticky. To switch an existing brain, run `gbrain reinit-pglite --embedding-model <provider:model> --embedding-dimensions <N>` (PGLite) or follow the SQL recipe in `docs/embedding-migrations.md` (Postgres). `gbrain config set embedding_model` is refused as of v0.37.11.0 because the schema column has to resize too.
+Lots of personal-knowledge systems give you keyword matching and grep in a box. GBrain does that, and adds two things nobody else ships together:
 
-GBrain is those patterns, generalized. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
+- **A synthesis layer that gives you the actual answer.** Synthesized, well-cited prose across people, companies, deals, and ideas. Not "here are 10 chunks that mention your query"; an actual answer with citations and an explicit note on what the brain doesn't know yet. The gap analysis is the part that changes how you use the brain.
+- **A self-wiring knowledge graph.** Every page write extracts entity refs and creates typed edges (`attended`, `works_at`, `invested_in`, `founded`, `advises`) with zero LLM calls. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked: **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, **+31.4 points P@5** over its graph-disabled variant and over ripgrep-BM25 + vector-only RAG by a similar margin. Full BrainBench scorecards live in the sibling [gbrain-evals](https://github.com/garrytan/gbrain-evals) repo.
 
-**New in v0.40.2.0 — `gbrain think` grounds temporal answers in the typed-claim timeline.** Ask "when did Marco last switch jobs" or "what was the ARR in March" and the answer comes back rooted in a real chronological timeline of the metric + event facts your brain already extracted via the `extract_facts` cycle phase. Default ON. The intent classifier (`temporal` / `knowledge_update` / `other`) is a regex pass with zero LLM cost; the `'other'` fast path short-circuits with zero extra SQL. Migration v82 adds a nullable `facts.event_type` column so the same plumbing carries event-shaped rows (`'meeting'`, `'job_change'`, `'location_change'`) alongside metric rows. Flip `think.trajectory_enabled=false` to opt out. Debug with `GBRAIN_THINK_DEBUG=1 gbrain think "..."` to see the spliced prompt. The same trajectory plumbing also lands in the LongMemEval benchmark with a methodology change disclosed in `methodology_note: extractor=haiku-preprocess-full-haystack-v1` — published scores are "gbrain + Haiku-preprocess pipeline" vs "gbrain alone", NOT directly comparable to baseline LongMemEval numbers without that note.
+The point of building a 100K-page brain is to use it as a strategic moat. To never lose context. To query what's in your own head without re-reading it. The brain layer is what makes the moat usable. The 24/7 dream cycle is what keeps it sharp. Both run on your hardware, your DB, your keys.
 
-**New in v0.40.7.0 — Your agents can now author your brain's schema pack themselves.** No more shell-out, no more hand-editing YAML. Tell your OpenClaw (or any agent connected via MCP) "my brain has 4000 untyped meetings pages — add a `meeting` type and backfill them," and it does the whole thing safely: per-pack atomic file lock, validation gate that catches dangling references pre-write, atomic write so a crash never leaves the pack half-written, privacy-redacted audit log with the agent's identity, chunked UPDATE in 1000-row batches that never wedge concurrent writers. 14 new `gbrain schema` CLI verbs (`add-type`, `remove-type`, `add-alias`, `add-link-type`, `stats`, `sync`, etc.) + 9 new MCP ops including the batched `schema_apply_mutations` (admin scope, NOT localOnly — remote agents reach it over normal HTTPS MCP). New `schema-author` skill with explicit boundary callouts to `brain-taxonomist` and `eiirp` so agents pick the right surface. The schema-pack cathedral that shipped in v0.39.1.0 is now reachable from the outside. **Why it matters:** [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — 7 killer use cases (4000 invisible meetings made queryable, the founder ops brain, the research brain, the legal brain, the team brain, agent-as-co-curator) plus the structural difference between a pile of notes and a brain with structure. **Walkthrough:** [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — fork the bundled pack, add a `researcher` type, backfill, query in 5 minutes.
-
-**New in v0.36.4.0 — Your agent drives the brain to 90/100 by itself.** One command does the loop you used to run by hand: `gbrain doctor --remediate --yes --target-score 90 --max-usd 5`. It computes a dependency-ordered plan (sync before extract, embed after consolidate), submits each step as a Minion job, re-checks score between every step, and refuses to spend past your cost cap. Cron can drive it unattended. `gbrain doctor --remediation-plan --json` previews what would run. Autopilot now does the same thing on its 5-minute tick: small problems get targeted handlers, big problems get the full cycle, a healthy brain sleeps for 60 minutes instead of grinding through synthesize+patterns+embed every tick. Eleven new things you can submit as background jobs (`reindex`, `repair-jsonb`, `orphans`, `integrity`, `purge`, plus six cycle phases); three of them (synthesize, patterns, consolidate) are PROTECTED so an MCP-connected agent can't silently burn Anthropic credits. New `--background` flag on `gbrain embed` submits the job and exits with `job_id=N` for shell composition.
-
-**New in v0.35.7 — Temporal trajectory + founder scorecard.** Author typed metric assertions in the `## Facts` fence (`mrr=50000`, `arr=2000000`, `team_size=12`) and gbrain stores them as first-class typed columns. `gbrain eval trajectory companies/acme-example` prints the chronological history with regressions auto-flagged inline. `gbrain founder scorecard companies/acme-example` rolls up claim accuracy, consistency, growth direction, and red flags into a stable `schema_version: 1` JSON contract. New MCP op `find_trajectory` exposes the same data to agents (read scope, visibility-filtered for remote callers). The `consolidate` cycle phase now writes `valid_until` on chronologically-superseded facts AND uses semantic upsert on `(page_id, claim, since_date)` — re-running the dream cycle on stable input is now a true no-op (fixed a pre-existing duplicate-takes bug from prior versions).
+It's easier to ship a daemon that runs 24/7 to ingest, enrich, and consolidate than it is to keep an agent in chat working hard. GBrain is that daemon, generalized. Install in 30 minutes. Your agent does the work. As my personal agent gets smarter, so does yours.
 
 > **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
 
 > **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).
 
-## Install
+## What this looks like
 
-GBrain runs in three shapes. Pick the one that matches how you use AI agents today.
+Say you have a meeting with Alice tomorrow. You want to walk in remembering what she works on, when you last talked, and what's still open between you. Here's what you'd type, and what you'd get back.
 
-### Run with your agent platform
+**You ask:**
 
-Already using [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)? GBrain installs as a skillpack scaffold into your agent's workspace.
+> "What do I need to know before my meeting with Alice tomorrow?"
 
-```bash
-gbrain init --pglite
-gbrain skillpack scaffold --all   # or: scaffold <name> per skill
+**Most personal-knowledge tools give you back a list of pages.** Something like:
+
+```
+1. people/alice — Alice runs engineering at Acme...
+2. meetings/2026-03-15-alice-q1 — Q1 product review with Alice...
+3. meetings/2026-01-08-acme-kickoff — Kickoff meeting with Acme team...
+4. customers/acme — Acme is a series-B fintech we work with...
+5. notes/2026-04-22 — Quick chat with Alice about pricing...
 ```
 
-That's it. Your agent picks up 43 skills (signal detection, brain-ops, ingest, enrich, citation-fixer, daily-task-manager, cron-scheduler, eval framework, and 35 more). Routing lives in `skills/RESOLVER.md` — the agent reads it once per request, picks the right skill, executes. Scaffolded skills are first-class members of your agent repo — you own them, edit freely; `gbrain skillpack reference <name>` diffs your copy against gbrain's bundle when you want to pull upstream improvements. (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.)
+Five pages you now have to open and read yourself to actually prepare. The tool found the right material, but it didn't do the work.
 
-### CLI standalone
+**GBrain gives you back the answer, with sources:**
 
-Use gbrain from any shell, no agent platform required.
+```
+Alice runs engineering at Acme (a series-B fintech). You last spoke
+on April 22 in a quick pricing chat. Three things are still open
+from that conversation:
+
+1. She owes you the security review for the new tier
+   (deadline was May 1; no update since).
+2. You committed to pricing for a 500-seat tier
+   (you sent it April 25; no response yet).
+3. She mentioned they're hiring a CISO; you said you'd intro
+   someone from your network.
+
+Heads up: nothing's been added to the brain about Alice or Acme
+since April 22, six weeks ago. She may have replied through email
+or Slack DM, channels the brain doesn't see. Worth asking her to
+catch up before assuming any of this is still current.
+```
+
+Every claim has a source page behind it. The "heads up" at the end tells you what the brain doesn't know yet, so you can ask Alice about it directly instead of being surprised. The brain just did your meeting prep.
+
+This is the difference between a search engine and a brain. Search finds the pages. The brain reads them for you and writes the answer.
+
+## Install
+
+GBrain is designed to be installed and operated by an AI agent. The fastest path is to have your agent do it for you. The CLI and MCP paths below are for people who want to wire it up themselves.
+
+### Have your agent install it (recommended)
+
+If you don't already have an AI agent platform running, start with one of these. Both are designed to read GBrain's install protocol and execute it:
+
+- **[OpenClaw](https://github.com/openclawagents/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
+- **[Hermes](https://github.com/openclawagents/hermes)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
+
+Then paste this into your agent:
+
+```
+Retrieve and follow the instructions at:
+https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
+```
+
+The agent installs GBrain, creates the brain, asks for your API keys, loads 43 skills, configures the dream cycle, and verifies the install end-to-end. ~30 minutes. You answer questions, it does the work.
+
+> **Never set up an AI agent platform before?** The [personal-brain tutorial](docs/tutorials/personal-brain.md) walks the whole path end-to-end — picking OpenClaw vs Hermes, deploying it, pointing it at INSTALL_FOR_AGENTS.md, getting the API keys, and verifying the first query. Start there if any of the above is new.
+
+### Install it into your existing agent
+
+Already running Codex, Claude Code, Cursor, or another coding agent? Paste the same instruction in:
+
+```
+Retrieve and follow the instructions at:
+https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
+```
+
+This works in any agent that can read files over HTTPS and execute shell commands. Tested with Codex, Claude Code, Claude Cowork, Cursor, and AlphaClaw.
+
+### CLI standalone (no agent)
 
 ```bash
 bun install -g github:garrytan/gbrain
-gbrain init --pglite   # 2 seconds; no server, no Docker
-gbrain doctor          # verify health
+gbrain init --pglite     # 2 seconds; no server, no Docker
+gbrain doctor            # verify health
+gbrain import ~/notes/   # index your markdown
+gbrain query "what themes show up across my notes?"
 ```
 
-Then point any MCP-aware client (Claude Code, Cursor, Windsurf) at it, or use it from your shell:
+Postgres-at-scale, Supabase, and thin-client setup paths live in [`docs/INSTALL.md`](docs/INSTALL.md).
+
+### Connect GBrain to your AI client (MCP)
+
+GBrain exposes 30+ tools over MCP (stdio and HTTP). The specific snippet depends on which client you use:
+
+- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — one command: `claude mcp add gbrain -- gbrain serve`. Zero server, zero tunnel.
+- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve"]}` to your MCP config.
+- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.
+- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.
+- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — Settings → Connectors → add the URL + bearer token. Pro subscription required.
+- **[ChatGPT](docs/mcp/CHATGPT.md)** — uses OAuth 2.1 with PKCE (the hard requirement). Register a `chatgpt` client from the admin dashboard with grant type `authorization_code`.
+
+For the HTTP server itself:
 
 ```bash
-gbrain search "who works at acme AI?"
-gbrain query "what did bob invest in this quarter?"
-gbrain graph-query people/garry-tan --depth 2
+gbrain serve              # stdio MCP (local subprocess; for Claude Code, Cursor, Windsurf)
+gbrain serve --http       # HTTP MCP with OAuth 2.1 + admin dashboard at /admin
+                          # (required for Claude Desktop, Cowork, Perplexity, ChatGPT)
 ```
 
-Detailed setup paths (Postgres at scale, Supabase, thin-client mode) live in [`docs/INSTALL.md`](docs/INSTALL.md).
+The HTTP server includes DCR-style client registration, scope-gated access (`read` / `write` / `admin`), and rate limiting. Deployment guides (ngrok, Railway, Fly.io) live under [`docs/mcp/`](docs/mcp/).
 
-### MCP server (any MCP client)
+## Two ways to query your brain
+
+Raw retrieval (what most personal-knowledge tools ship) and a synthesis layer that gives you an actual answer. They serve different jobs.
 
 ```bash
-gbrain serve              # stdio MCP (Claude Desktop / Code / Cursor)
-gbrain serve --http       # HTTP MCP with OAuth 2.1 + admin dashboard
-                          # at /admin, SSE activity feed at /admin/events
+# raw retrieval: top pages by hybrid score, fast, no LLM cost
+gbrain search "who's working on AI agents at portfolio companies?"
+
+# brain layer: synthesized answer with citations and gap analysis
+gbrain think "who's working on AI agents at portfolio companies?"
 ```
 
-Per-client guides (Claude Desktop, Code, Cursor, ChatGPT, Perplexity, Cowork) live under [`docs/mcp/`](docs/mcp/). HTTP server supports DCR-style client registration, scope-gated access (`read`/`write`/`admin`), and built-in rate limiting.
+**`gbrain search`** returns the top retrieved pages, ranked by hybrid scoring (vector + keyword + RRF + source-tier boost + reranker). Use it when you want raw material to skim: agent context windows, citation lookups, finding a specific quote.
 
-## How to get data in (v0.38+)
+**`gbrain think`** runs the same retrieval, then composes a synthesized answer across the results with explicit citations to the source pages AND an honest note on what the brain doesn't know yet. The gap analysis is the differentiator: the answer tells you when a page is stale, when a claim is uncited, when two pages contradict each other, when there's a hole you should fill.
+
+**Why it compounds.** Pair the brain layer with `find_trajectory` and you get answers like *"how have the company's metrics changed AND what does the team look like right now AND what did they promise / share AND when did we last meet AND what's the value-add I can offer here"*: well-scored, well-cited, in one shot. That's the strategic moat. That's why building a 100K-page brain is worth the effort.
+
+`gbrain agent run "..."` exposes the same surface to a sub-agent through the Minions queue, with crash-safe two-phase persistence. Same answers, durable.
+
+## How to get data in
 
 One command, local or hosted, synchronous receipt:
 
@@ -78,10 +160,7 @@ echo "from a pipe" | gbrain capture --stdin
 SLUG=$(gbrain capture "..." --quiet)
 ```
 
-The page lands in the DB AND on disk in one move (the v0.38 `put_page`
-write-through plumbing). Default slug `inbox/YYYY-MM-DD-<hash8>` so
-captures cluster in a predictable triage location. On thin-client installs
-the verb routes through MCP to the server — same command, same UX.
+The page lands in the database and on disk in one move. Default slug `inbox/YYYY-MM-DD-<hash8>` so captures cluster in a predictable triage location. On thin-client installs the verb routes through MCP to the server: same command, same UX.
 
 For webhook ingestion (Zapier / IFTTT / Apple Shortcuts):
 
@@ -99,6 +178,40 @@ Third-party skillpacks can ship custom ingestion sources (Granola, Linear,
 voice, OCR) against the versioned `IngestionSource` contract at
 `gbrain/ingestion`. See [`docs/skillpack-anatomy.md`](docs/skillpack-anatomy.md).
 
+## Your brain's shape (schema packs)
+
+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 on top, and the agent doesn't know what a `Projects/` folder means or whether `Reading/` is people or sources.
+
+**gbrain doesn't have a fixed layout.** It ships with two bundled schema packs and lets you author your own when neither fits:
+
+- **`gbrain-base`** (default) — the layout my production brain uses: `people/`, `companies/`, `concepts/`, `meetings/`, `deal/`, `daily/`, `originals/`, `writing/`, etc. Zero config. Drop a brain that fits this shape and everything works.
+- **`gbrain-recommended`** — extends `gbrain-base` with the 13 additional directories from `docs/GBRAIN_RECOMMENDED_SCHEMA.md` (source, place, trip, conversation, personal, civic, project, etc.). Activate with `gbrain schema use gbrain-recommended`.
+- **Your own pack** — `gbrain schema detect` clusters your actual filesystem into proposed types, `gbrain schema suggest` runs an LLM pass over them, and `gbrain schema review-candidates --apply` promotes the ones you like. Three commands and the brain knows your shape.
+
+```bash
+gbrain schema active                # which pack is running, which tier set it
+gbrain schema list                  # bundled + installed packs
+gbrain schema detect                # propose types matching your filesystem
+gbrain schema suggest               # LLM-refined proposals on top of detect
+gbrain schema review-candidates     # human gate: promote / rename / ignore
+gbrain schema use my-pack           # activate
+```
+
+The active pack threads through every read + write path: `parseMarkdown` infers page type from the pack's path prefixes; `whoknows` scopes expert routing to types declared `expert_routing: true`; `extract_facts` runs only on `extractable: true` types; the search cache folds the pack name + version into its key so cross-pack contamination is structurally impossible. Switch packs and the brain re-interprets itself; switch back and nothing's lost.
+
+Seven-tier resolution chain (per-call flag → env var → per-source DB key → brain-wide DB key → `gbrain.yml` → `~/.gbrain/config.json` → `gbrain-base` default). Full reference + authoring guide: [`docs/architecture/schema-packs.md`](docs/architecture/schema-packs.md).
+
+## Tutorials
+
+Step-by-step walkthroughs for getting the most out of GBrain. Each one takes you from zero to a working outcome, with concrete commands and real numbers.
+
+- [**Set up your personal AI agent + brain from zero**](docs/tutorials/personal-brain.md) — the canonical full-stack install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. End-to-end in about 2 hours.
+- [**Set up GBrain as your company brain**](docs/tutorials/company-brain.md) — federated, multi-user, OAuth-scoped institutional memory for a 10-50 person team. About 90 minutes end-to-end.
+
+More walkthroughs in progress: connecting an existing agent (Claude Code, Cursor, OpenClaw, Hermes) to a GBrain memory layer; setting up GBrain for VC dealflow with founder scorecards and meeting prep; migrating an existing Notion or Obsidian vault; indexing a codebase as a queryable code brain. Full tutorial index: [`docs/tutorials/`](docs/tutorials/).
+
+Want to see a tutorial that isn't here yet? [Open an issue](https://github.com/garrytan/gbrain/issues) describing the workflow you want documented.
+
 ## What it does (the loop)
 
 ```
@@ -116,7 +229,7 @@ The whole loop is described in [`docs/architecture/topologies.md`](docs/architec
 
 ## Capabilities
 
-**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). Default: `balanced` with ZeroEntropy reranker on. **New in v0.40.4.0:** per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns.
+**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). Default: `balanced` with ZeroEntropy reranker on. Per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns.
 
 **Self-wiring knowledge graph.** Every `put_page` extracts entity refs from markdown/wikilinks/typed-link syntax and writes edges with zero LLM calls. Typed edges (`attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, …). Multi-hop traversal via `gbrain graph-query`. The graph is what produces the +31.4 P@5 lift over vector-only RAG.
 
@@ -152,7 +265,7 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
 
 ## Troubleshooting
 
-**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. As of v0.37, fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment — set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
+**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment: set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
 
 ## Docs
 
@@ -180,8 +293,8 @@ If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc
 
 ## License + credit
 
-MIT. Built by Garry Tan to run his OpenClaw and Hermes deployments — the production brain behind his actual AI agents.
+MIT. I built GBrain to run my OpenClaw and Hermes deployments — the production brain behind my AI agents.
 
 Origin story: [`docs/ethos/ORIGIN.md`](docs/ethos/ORIGIN.md).
 
-Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that became the v0.36.2.0 default. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
+Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that ships as the default. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.

VERSION

@@ -1 +1 @@
-0.40.8.0
+0.40.8.1

docs/INSTALL.md

@@ -37,6 +37,8 @@ gbrain migrate --to supabase     # PGLite → Postgres
 gbrain migrate --to pglite       # Postgres → PGLite (rare)
 ```
 
+For shared / large / multi-machine deployments (a team or company brain with multiple users hitting one server over HTTP MCP with OAuth scoping per user), follow the dedicated walkthrough: **[Tutorial: set up GBrain as your company brain](tutorials/company-brain.md)**.
+
 API keys live in `~/.gbrain/config.json` (file plane) or env vars (`OPENAI_API_KEY`, `ZEROENTROPY_API_KEY`, `VOYAGE_API_KEY`, `ANTHROPIC_API_KEY`). Set via CLI:
 
 ```bash

docs/architecture/topologies.md

@@ -398,3 +398,6 @@ simultaneously — that's by design.
   vs sources axes).
 - `docs/mcp/CLAUDE_DESKTOP.md` and siblings — per-client MCP setup.
 - `gbrain init --help` and `gbrain auth --help` for command-level details.
+- [`docs/tutorials/`](../tutorials/) — end-to-end walkthroughs that combine
+  these topologies into working setups (company brain, personal brain,
+  agent integration, etc.).

docs/ethos/ORIGIN.md

@@ -25,3 +25,5 @@ None of those are novel ideas. The contribution is shipping all of them together
 The production brain has been running for months now. 17,888 pages. 4,383 people. 723 companies. 21 cron jobs running autonomously. It wakes Garry up smarter than the day before.
 
 GBrain is what happens when you write the brain you actually wanted to have.
+
+The reason the brain is worth building is `gbrain think`. Without it, the brain is just a place that holds your notes. With it, the brain is a thing you can query about itself: what does it know, what does it not know yet, where does it contradict itself, where are the holes. The 24/7 cron cycle keeps the brain sharp. `think` is what makes a sharp brain useful.

docs/tutorials/README.md

@@ -0,0 +1,36 @@
+# Tutorials
+
+Step-by-step walkthroughs that take you from zero to a working outcome. Concrete commands, real numbers, no abstraction-first jargon. Each tutorial assumes no prior GBrain knowledge.
+
+## Shipped
+
+- [**Set up your personal AI agent + brain from zero**](personal-brain.md) — the canonical solo install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. End-to-end in about 2 hours; about $100 to $150 a month sustained. The full-stack install I'd run today.
+- [**Set up GBrain as your company brain**](company-brain.md) — federated, multi-user, OAuth-scoped institutional memory for a 10-50 person team. Three sources (shared / customers / internal-only), per-user scope, first synthesized query as a teammate. About 90 minutes end-to-end, about $5 in API calls for the demo, under $100 a month sustained for a 25-person company.
+
+## In progress
+
+These are the next tutorials on the roadmap. Open an issue if one of them is the one you need most; that's how we'll prioritize.
+
+- **Connect GBrain to your existing agent** — for users who already run [OpenClaw](https://github.com/garrytan/openclaw), [Hermes](https://github.com/garrytan/hermes), Claude Code, Cursor, or any MCP-aware client. Wire GBrain in as the memory layer, scaffold the 43 skills, see brain-first lookup fire on the next message your agent gets.
+
+- **Set up GBrain for VC dealflow** — the operator's recipe. People pages for founders, companies with typed Facts fence carrying ARR / team-size / runway across dates, meetings auto-ingested, deal pages linking everything. Shows `gbrain whoknows`, `gbrain find_trajectory`, and `gbrain founder scorecard` on real workflows.
+
+- **Migrate your existing vault into GBrain** — for Notion / Obsidian / Roam users with a vault that doesn't match GBrain's default layout. Walks through `gbrain schema detect` → `suggest` → `review-candidates` so the brain learns your shape instead of forcing you to learn its.
+
+- **Index your codebase as a code brain** — for developers. Initialize a brain in a code repo, swap to `voyage-code-3` for embeddings, use `gbrain code-def` / `gbrain code-refs` / `gbrain code-callers` to navigate the codebase semantically from any MCP-aware editor.
+
+- **Run GBrain fully local with Ollama or llama.cpp** — for privacy-first deployments. No cloud calls, no API keys, no telemetry. Trades some retrieval quality for full local control. Useful for regulated industries, air-gapped environments, or just paranoia.
+
+- **Set up the dream cycle** — the overnight enrichment daemon that makes the brain self-maintaining. Fixes citations, dedupes people pages, surfaces contradictions, generates founder scorecards on the schedule you configure. The piece that turns a static knowledge base into a brain that gets smarter while you sleep.
+
+## Want to write one?
+
+Tutorials follow the [Diataxis](https://diataxis.fr/) tutorial pattern: learning-oriented, walks a learner from zero to a working result in one session, every step produces a visible change. If you've used GBrain for something interesting and want to write the walkthrough, the existing [`company-brain.md`](company-brain.md) is the model. Open a PR.
+
+## Related documentation
+
+- **Reference:** [`docs/architecture/`](../architecture/) — system design, topologies, retrieval theory
+- **How-to:** [`docs/guides/`](../guides/) — task-oriented runbooks (sub-agent routing, minion deployment, skill development, brain-first lookup, idea capture, diligence ingestion)
+- **Integrations:** [`docs/integrations/`](../integrations/) — connecting external data sources (voice, email, calendar, embedding providers)
+- **MCP setup:** [`docs/mcp/`](../mcp/) — per-client setup (Claude Desktop, Code, Cursor, ChatGPT, Perplexity, Cowork)
+- **Install paths:** [`docs/INSTALL.md`](../INSTALL.md) — every install path, end to end

docs/tutorials/company-brain.md

@@ -0,0 +1,557 @@
+# Tutorial: Extend your personal brain into a company brain
+
+This tutorial picks up where the [personal brain tutorial](personal-brain.md) leaves off. You already have a working agent (OpenClaw on Render, talking to you on Telegram, with GBrain as memory and Supabase storing embeddings). Now you want your whole team to use it as shared institutional memory, with each person seeing only what they're allowed to see.
+
+**Time:** about 90 more minutes on top of the personal-brain install.
+**Cost:** under $100 a month sustained for a 25-person company.
+
+If you haven't done the personal-brain install yet, [start there first](personal-brain.md). Come back when you've got the agent responding to you on Telegram. This tutorial assumes that's already working.
+
+I'm Garry Tan. I built GBrain to run my own AI agents at Y Combinator. After a couple of months of multi-user features landing (parallel sync across team sources, per-user OAuth scoping, leak-free isolation across every read path), it's finally usable as a company brain too. This is the recipe I'd run if I were standing it up for a 10-50 person company today.
+
+---
+
+## Part 1: The mental model
+
+### What changes when you go from personal to company
+
+The personal brain you built is a single-user system: one git repo, one agent, your stuff. The company brain is the same architecture with three additions:
+
+1. **Multiple sources** inside the same brain. Your meeting notes are one source. Each teammate's customer notebook is another. The shared company wiki is a third. They live in the same database but stay independent.
+2. **Per-user logins** with scopes. Each teammate gets their own OAuth credential. The credential decides which sources they can read and write to. Alice writes to her customer source, reads hers plus the shared one. Bob writes to internal-ops, reads his plus the shared one. Neither can see the other's writes.
+3. **Per-person folders, crons, and skills.** The shared brain has shared structure, but each teammate gets their own subfolder for their own work, their own scheduled tasks (weekly digest, customer follow-ups), and their own scoped skills.
+
+### What this is NOT
+
+It is **not** a different install. The agent runtime, Supabase backend, GBrain CLI, and AlphaClaw harness from the personal brain stay exactly as you set them up. We're adding to that stack, not replacing it.
+
+It is also **not** a thin-client-everywhere setup. Your personal agent stays as it is (OpenClaw + Telegram). Each teammate adds their own client of choice (Claude Code, Cursor, Claude Desktop, their own OpenClaw, whatever) and points it at the brain.
+
+### What you get that one person's brain doesn't
+
+- **Shared memory.** The whole team queries the same brain. The contract notes that Alice wrote on Tuesday show up when Bob asks about that customer on Friday, with citations back to Alice's notes.
+- **Scoped privacy.** Performance reviews don't leak into customer queries. Legal docs don't leak into sales searches. We fuzz-tested this across every read path and got zero leaks.
+- **One sync pipeline.** Your brain git repo (or several if you want them isolated per team) feeds the brain. Everyone sees the latest.
+- **One operating burden.** One server to monitor, not one per user.
+
+---
+
+## Part 2: Switch the brain backend to multi-user Postgres
+
+The personal-brain install uses Supabase as the embeddings layer but the GBrain runtime itself might be using PGLite (single-machine) depending on which path you took. For a company brain, you want a real Postgres for the runtime too. If your personal-brain install is already on Postgres or Supabase end-to-end, skip to Part 3.
+
+If you're on PGLite, migrate:
+
+```bash
+gbrain migrate --to supabase
+```
+
+This copies every page, chunk, embedding, link, and config over to your Supabase project. Run from the agent host machine, same one you set up in the personal-brain tutorial. Takes a few minutes per 10K pages.
+
+Verify:
+
+```bash
+gbrain doctor
+gbrain stats
+```
+
+Page count and chunk count should match what you had on PGLite.
+
+---
+
+## Part 3: Carve up the brain into sources
+
+The personal brain has one source (called `default`) holding everything. For a company brain we want multiple. The right shape depends on your org. Here's a typical starting point for a 10-50 person company:
+
+```bash
+# A shared all-hands source for content everyone reads
+gbrain sources add shared --path /srv/brain-repos/shared --name "Shared company wiki"
+
+# A scoped source for sales/customer notes
+gbrain sources add customers --path /srv/brain-repos/customers --name "Customer notes"
+
+# A scoped source for internal-only docs (legal, HR, performance, board)
+gbrain sources add internal --path /srv/brain-repos/internal --name "Internal-only"
+```
+
+Each `--path` is a directory on disk where you've checked out a git repo. Create them:
+
+```bash
+sudo mkdir -p /srv/brain-repos
+sudo chown $USER /srv/brain-repos
+cd /srv/brain-repos
+git clone git@github.com:your-org/shared-wiki.git shared
+git clone git@github.com:your-org/customers.git customers
+git clone git@github.com:your-org/internal-docs.git internal
+```
+
+You can also keep the existing personal-brain repo as one of the sources. Just pick the role it plays (probably `shared` if it's already org-wide content).
+
+### Two scoping models (pick the one that matches your shape)
+
+There are two ways to scope teammates' access. They suit different deployment shapes.
+
+**Model A: separate sources with OAuth scoping (recommended for true multi-user with different AI clients).** What this tutorial walks you through. Each teammate gets their own OAuth client, which carries `--source` + `--federated-read` flags. The brain refuses cross-source reads at the SQL layer; isolation is database-enforced. Each teammate can run their own MCP-aware client (Claude Code, Cursor, their own OpenClaw, etc.) and the scoping holds.
+
+**Model B: one source, directory-based per-person scoping (simpler for one-agent-serves-everyone setups).** The shape I actually run in production: a single source called `default`, with a `partners/<slug>/` convention inside it (e.g. `partners/alice-example/`, `partners/bob-example/`). Each partner gets their own subdirectory holding their personal pages: `partners/alice-example/USER.md`, `partners/alice-example/concepts/`, `partners/alice-example/sources/`, etc. There's no OAuth-enforced isolation; the agent itself enforces "Alice's writes go to her partners/ subdir." This is the right model when ONE agent (yours) serves everyone over Telegram or a single shared interface. It's simpler ops, no per-user OAuth, but the scoping is convention-only.
+
+For most company-brain installs (10+ teammates each with their own AI client), Model A is the right starting point. If you're running the fat-agent-serves-everyone pattern from the personal-brain tutorial, Model B is genuinely simpler. You can also mix: separate sources for the obviously-different ones (customer notes vs internal-only) AND a `partners/<slug>/` convention inside the shared source for per-person workspace.
+
+### Per-person folder structure inside each source
+
+Inside each source, give each teammate their own subfolder. This is the structure I run:
+
+```
+customers/
+├── alice-example/                      ← Alice's customer notebook
+│   ├── customers/
+│   │   ├── acme-co.md
+│   │   └── widget-systems.md
+│   └── meetings/
+│       └── 2026-05-21-acme-renewal.md
+├── bob-example/                        ← Bob's customer notebook
+│   └── customers/
+│       └── orbit-bio.md
+└── shared-customers/                   ← things both can see
+    └── all-active-deals.md
+```
+
+Two things this structure buys you:
+
+1. **Each teammate's writes go to their own folder** even though they're in the same source. No accidental overwrites.
+2. **You can later split a person's folder into its own source** (if Alice leaves and a new person takes her accounts, you can move `alice-example/` to a new source named after the new person and adjust scoping accordingly).
+
+Same shape for `internal/`: `internal/alice-example/` for her HR docs, `internal/bob-example/` for his, `internal/legal/` for legal docs everyone can read, etc.
+
+Now sync everything:
+
+```bash
+gbrain sync --all
+```
+
+Each source syncs in parallel under its own lock so they don't step on each other. Output looks like:
+
+```
+[shared]    100/100 pages
+[customers] 240/240 pages
+[internal]   85/85 pages
+✓ all sources synced
+```
+
+Check the dashboard:
+
+```bash
+gbrain sources status
+```
+
+You should see all three sources with recent sync timestamps and page counts.
+
+---
+
+## Part 4: Expose the brain over HTTP MCP with OAuth
+
+The personal brain talks to you through the AlphaClaw harness over Telegram. For a company brain we need a path that each teammate's AI client can hit independently. The HTTP MCP server is that path.
+
+```bash
+gbrain serve --http --port 3131 --bind 0.0.0.0
+```
+
+The `--bind 0.0.0.0` is important. By default the server binds to localhost only, which is correct for a personal install but blocks remote teammates. Setting `0.0.0.0` accepts connections from any interface.
+
+The server prints an admin bootstrap token to stderr on first start. Save it. You'll use it once for the admin dashboard.
+
+For development, tunnel the local server out via ngrok:
+
+```bash
+ngrok http 3131 --domain your-brain.ngrok.app
+```
+
+For production, put your server behind a real hostname with a real TLS certificate. Let's call your final URL `https://brain.acme-co.com` for the rest of this tutorial.
+
+Re-run the server with the public URL so the OAuth discovery metadata matches what clients hit:
+
+```bash
+gbrain serve --http --port 3131 --bind 0.0.0.0 --public-url https://brain.acme-co.com
+```
+
+You should be able to hit `https://brain.acme-co.com/health` and get `{"status":"ok"}` back.
+
+---
+
+## Part 5: Register one OAuth client per teammate
+
+Each teammate (or each AI agent for a teammate) gets their own OAuth client. The client controls what they can write and what they can read.
+
+```bash
+# Alice (sales): writes customers/alice-example, reads customers + shared
+gbrain auth register-client alice-example \
+  --grant-types client_credentials \
+  --scopes read,write \
+  --source customers \
+  --federated-read customers,shared
+
+# Bob (ops): writes internal/bob-example, reads internal + shared
+gbrain auth register-client bob-example \
+  --grant-types client_credentials \
+  --scopes read,write \
+  --source internal \
+  --federated-read internal,shared
+
+# Carol (legal): writes shared/legal, reads all three
+gbrain auth register-client carol-example \
+  --grant-types client_credentials \
+  --scopes read,write \
+  --source shared \
+  --federated-read shared,customers,internal
+```
+
+Each `register-client` command prints a `client_id` and a `client_secret`. Save both for each teammate. They go into the teammate's local agent config.
+
+A note on the flags:
+
+- `--scopes read,write` lets the client query the brain and write new pages. You can omit `write` for read-only clients (executive summaries, dashboards). The `admin` scope is needed for operational commands like `gbrain remote doctor` and is usually reserved for your own admin client.
+- `--source` controls write authority. A client can only write to one source. Within that source, your folder convention from Part 3 keeps each person's writes in their own subfolder.
+- `--federated-read` controls read scope. A client can read from one or more sources.
+
+### Verify the scoping actually scopes
+
+Before you hand the brain to teammates, verify isolation. Two terminal windows on your local machine using each client's credentials:
+
+```bash
+# Terminal 1, as Alice
+export GBRAIN_REMOTE_CLIENT_ID=<Alice's client_id>
+export GBRAIN_REMOTE_CLIENT_SECRET=<Alice's client_secret>
+export GBRAIN_REMOTE_MCP_URL=https://brain.acme-co.com/mcp
+
+gbrain search "performance review" --remote
+```
+
+Alice should see results only from `customers` and `shared`. The performance-review notes live in `internal`, which she's not scoped to read. She shouldn't see them.
+
+```bash
+# Terminal 2, as Bob (export his credentials similarly)
+gbrain search "performance review" --remote
+```
+
+Bob should see the performance-review notes from `internal`, plus anything related from `shared`. He shouldn't see anything that lives only in `customers`.
+
+If both queries return correctly scoped results, isolation is working.
+
+---
+
+## Part 6: Set up per-person crons
+
+The personal-brain install runs the dream cycle (overnight enrichment) once per night for one user. A company brain needs per-person crons because each teammate has their own context: Alice wants a 7am customer-pipeline digest, Bob wants a 9am ops-status report, Carol wants a contract-compliance check every Monday.
+
+Each cron is just a scheduled `gbrain agent run` call scoped to the teammate's client credentials. The schedule lives in the workspace repo (the one AlphaClaw deployed in the personal-brain tutorial), in a `crons/` directory. A typical layout:
+
+```
+your-org/myagent/
+└── crons/
+    ├── alice-example/
+    │   └── 07am-customer-digest.md
+    ├── bob-example/
+    │   └── 09am-ops-status.md
+    └── carol-example/
+        └── monday-contract-compliance.md
+```
+
+Each cron file declares its schedule and the prompt that the agent runs:
+
+```markdown
+---
+schedule: "0 7 * * *"
+client: alice-example
+---
+
+# Customer pipeline digest
+
+Pull every customer page in customers/alice-example/ that had activity in
+the last 7 days. For each, summarize what changed and what the next action
+is. Output as a markdown digest, post to Slack #alice-customers, save a
+copy to customers/alice-example/digests/YYYY-MM-DD-pipeline.md.
+```
+
+The `client:` field tells the cron runner which OAuth client to use, which enforces the scoping. Alice's cron can only read Alice's sources and write to Alice's folder. It cannot accidentally touch Bob's customer notes.
+
+To install the cron schedule, commit the file to the workspace repo and let AlphaClaw pick it up on next deploy. The cron-scheduler skill (one of the 60 that GBrain installed) handles the dispatch.
+
+---
+
+## Part 7: Add per-person skills
+
+The 60+ skills GBrain installs are generic. Your team probably wants a few that are specific to them. Examples:
+
+- `onboarding-new-hire`. Only Carol (HR) runs this. Walks through generating a welcome packet, scheduling intro meetings, provisioning accounts.
+- `customer-success-followup`. Only Alice (sales) runs this. Pulls latest customer page, drafts a follow-up email, posts to her review queue.
+- `weekly-team-digest`. Only you (admin) run this. Aggregates everyone's published pages into one weekly summary.
+
+Skills are just markdown files in the workspace repo's `skills/` directory. The shape:
+
+```
+your-org/myagent/
+└── skills/
+    ├── onboarding-new-hire/
+    │   └── SKILL.md
+    ├── customer-success-followup/
+    │   └── SKILL.md
+    └── weekly-team-digest/
+        └── SKILL.md
+```
+
+Each `SKILL.md` declares the trigger (verbs in plain English the agent listens for) and the procedure. Use the `gbrain skillify scaffold <name>` command to generate the boilerplate:
+
+```bash
+gbrain skillify scaffold onboarding-new-hire
+```
+
+That creates the directory + SKILL.md + routing entry. Edit the SKILL.md to describe the procedure, commit, deploy. The agent picks up the new skill on next request.
+
+Per-person scoping for skills is handled at the routing layer: a skill can declare `allowed_clients: [carol-example]` in its frontmatter. If Alice asks her agent to run that skill, the agent refuses with "this skill is scoped to carol-example."
+
+### Shared rule files at the skills root
+
+Alongside individual skill directories, drop a few flat `_*-rules.md` files at the root of `skills/`. These are conventions that EVERY skill reads. The ones I run in production:
+
+- `_brain-filing-rules.md`. the iron-rule decision tree for "where does this new page belong?" Numbered first-match-wins rules (people go in `people/`, companies in `companies/`, meetings in `meetings/`, etc.). Every ingest skill consults this before creating a page.
+- `_output-rules.md`. output quality standards (deterministic links built from API data not LLM-composed strings, exact-phrasing requirements for citations, no AI-slop vocabulary).
+- `_excluded-people.md`. a privacy gate. Names that must never be referenced or attributed in the brain even if they appear in source material. Re-attribute or discard. This is the file that prevents your agent from accidentally publishing things about people you've decided aren't fair game.
+- `_operating-rules.md`. operational conventions (when to write to brain vs scratchpad, when to ask for confirmation, when to fire a notification).
+- `_x-ingestion-rules.md`, `_x-api-rules.md`. per-source rules for specific integrations (Twitter, in this case).
+
+These files turn into the de facto company policy for the agent. Edit one, and every skill that reads it picks up the new rule on the next request. Versioned in git, reviewable in PR.
+
+---
+
+## Part 8: Wire Slack carefully
+
+Slack is the integration most teams want first, and it has enough sharp edges to deserve its own callout. The conventions I run:
+
+**Two crons, two jobs.** One scan cron that runs every 5-15 minutes and surfaces signals (new threads in channels you care about, mentions of your teammates, decisions). One archive cron that runs nightly and stores the full conversation history. Splitting them this way means urgent signals get acted on fast while the slow archive work doesn't crowd the live channel.
+
+**Channel-to-task-ID mapping.** Don't have your agent reference Slack channels by their actual channel IDs (`C03A8...`). Build a `topic-registry.json` (or similar) that maps each channel ID to a friendly task name (`acme-co-customer-success`, `engineering-standup`). Crons and skills reference channels by friendly name; the registry translates to IDs at runtime. This is the file you edit when a channel gets renamed or replaced.
+
+**Deterministic links only.** When your agent writes a brain page that cites a Slack message, the link MUST be built from API data (workspace ID + channel ID + message timestamp), never composed by the LLM. LLMs hallucinate Slack URLs constantly. The convention lives in `_output-rules.md`; every skill that touches Slack inherits it.
+
+**Dismissed-items state.** The scan cron remembers what it has already surfaced. If a channel had a thread on Tuesday that turned out to be noise, the dismissed-items file records it so the Wednesday scan doesn't surface it again. Without this, re-scans become a flood of repeat signals.
+
+**Per-channel scoping mirrors per-person scoping.** Sensitive channels (#executive, #legal, #performance) should be scoped to teammates with the appropriate `--federated-read`. The brain stores everything, but who can query for it is gated by the same OAuth client model from Part 5.
+
+The actual skills that implement this in production are named `slack`, `slack-scan`, `slack-archive`. Scaffold equivalents in your workspace with `gbrain skillify scaffold slack-scan`, then edit the generated SKILL.md to declare your channel mapping and triggers.
+
+---
+
+## Part 9: Onboard each teammate yourself (the botmaster pattern)
+
+This is the part that decides whether your company brain actually gets adopted or sits unused.
+
+**Do not just hand a new teammate their OAuth credential and tell them to "try it out."** They'll send one query, get a result that doesn't feel personal yet (because their slice is empty), conclude it's not useful, and never come back.
+
+What works instead: I personally onboard each new teammate myself. The flow looks like this.
+
+### Step 1: Pre-populate their slice
+
+Before they ever log in, I seed their `partners/<their-slug>/` directory (or their dedicated source) with the context they need to feel like the brain already knows them:
+
+- `partners/alice-example/USER.md`. a one-page profile: role, focus areas, current top 3 priorities, the kind of questions they tend to ask, the kind of writing they prefer (terse vs detailed, casual vs formal).
+- `partners/alice-example/concepts/`. 5-10 frameworks or recurring themes that are specifically THEIRS. If Alice runs sales, that's "pipeline stage definitions," "ICP criteria," "objection-handling playbooks."
+- `partners/alice-example/sources/`. links to the documents they care about (their team's shared docs, their inbox conventions, the dashboards they check).
+- 2-3 example brain entries that demonstrate the shape: a customer page they'd recognize, a meeting note from a recent meeting they attended, an idea they've shared with the team.
+
+Takes me maybe 20 minutes per teammate. The payoff: the moment they run their first query, the brain answers with their context, not a generic response. That's the difference between "this is a cool tool" and "this knows me."
+
+### Step 2: Walk them through 2-3 wow flows
+
+Before letting them DM the agent freely, I personally walk them through 2-3 specific flows that I know will land:
+
+1. A query that demonstrates synthesis: "ask the brain about [a customer they know well]. Notice how it pulls together pages from three sources into one answer with citations." This shows the brain layer in action.
+2. A query that demonstrates gap analysis: "ask the brain about [something it doesn't know yet]. Notice how it tells you what's missing instead of making it up." This builds trust.
+3. A write-back flow: "tell the brain about [a meeting they just had]. Notice how it auto-files, links to the other people who were there, and surfaces related history." This shows the agent's value as a capture tool, not just a query tool.
+
+These three flows take maybe 15 minutes total. By the end, the teammate has seen the brain do something they couldn't have done themselves in that time. They feel powerful.
+
+### Step 3: Graduate to DM only after the wow moment lands
+
+After the walkthrough, I give them their OAuth credential and the agent's DM (Telegram, Slack DM, whatever your interface is). I explicitly say "now you can ask it anything, write to it anytime, and it'll keep learning from you."
+
+The order matters. If you give them DM access first and expect them to discover the wow moments themselves, most won't. They'll send one generic query, get a generic answer, and bounce. The botmaster pattern (pre-populate → walk through → graduate to DM) flips the conversion rate.
+
+Repeat this flow for every new teammate. About 45 minutes per person, total. Compared to the cost of an unadopted internal tool, it's the best 45 minutes you'll spend.
+
+---
+
+## Part 10: Connect each teammate's AI client
+
+Each teammate runs their AI client (Claude Code, Cursor, Claude Desktop, OpenClaw, Hermes, whatever) configured to point at your brain server through their OAuth credentials.
+
+Recommended path for each teammate: the thin-client install. On their machine:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+bun install -g github:garrytan/gbrain
+
+gbrain init --mcp-only \
+  --issuer-url https://brain.acme-co.com \
+  --mcp-url https://brain.acme-co.com/mcp \
+  --oauth-client-id <their client_id> \
+  --oauth-client-secret <their client_secret>
+```
+
+The thin-client install creates a local config that knows how to talk to your brain but never opens its own database. Most CLI commands route through the remote server transparently.
+
+Now they configure their AI client. For Claude Desktop, the teammate adds an MCP server entry in `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "company-brain": {
+      "command": "gbrain",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+When Claude Desktop launches, it talks to the local `gbrain serve` stdio bridge, which forwards every request to your remote brain over HTTPS with their OAuth token attached. From Claude Desktop's perspective it's just one MCP server.
+
+For Claude Code, Cursor, OpenClaw, Hermes, and other clients, per-client setup steps live in [`docs/mcp/`](../mcp/). They all follow the same shape: point the agent at the local `gbrain serve` bridge, which knows about the remote.
+
+---
+
+## Part 11: First real query as a teammate
+
+Have Alice run a real query from her machine. The interesting verb is `gbrain think`, which gives back a synthesized answer instead of raw pages.
+
+```bash
+gbrain think "What's the latest update from acme-co? When did we last talk to them?"
+```
+
+What Alice gets back, assuming the brain has been syncing for a week and her sources contain a customer page for acme-co and several meeting notes:
+
+```
+## Answer
+
+The most recent customer contact with acme-co was a renewal-discussion
+meeting on 2026-05-18, attended by alice-example and acme-co's CTO. Key
+points discussed [customers/alice-example/meetings/2026-05-18-acme-renewal]:
+
+- They are upgrading their plan from team to enterprise.
+- Annual contract value is moving from $48K to $180K.
+- Decision driver: a new compliance requirement they have to meet by Q3.
+
+Prior contact was a quarterly check-in on 2026-04-03 [customers/alice-example/meetings/2026-04-03-acme-q2-checkin].
+
+**Gap noted:** No customer-success notes have been filed since the
+2026-05-18 renewal meeting. If a follow-up has happened, it's not in
+the brain yet.
+```
+
+Three things to notice:
+
+1. **Sourced.** Every claim cites the meeting note it came from.
+2. **Synthesized.** Alice didn't read three pages and stitch them together. The brain did.
+3. **Honest about gaps.** The brain knows what it doesn't know and says so, instead of inventing a follow-up that didn't happen.
+
+That last part is the gap analysis. It's the part of the brain layer that nobody else ships.
+
+Bob asking the same question would get nothing about acme-co. He's not scoped to read `customers`. He'd see his own internal-ops content if he asked something relevant to that. Carol asking would see both, because she's scoped to read all three sources.
+
+---
+
+## Part 12: Operating the company brain
+
+Three commands do most of the operational work.
+
+### Background daemon: `gbrain autopilot`
+
+The personal-brain install already turned this on. For a company brain, the same autopilot covers all your sources because they live in one database. It runs every five minutes; on a healthy brain (health score 95+) it sleeps; on a brain that's drifting it submits targeted maintenance jobs.
+
+### Self-healing: `gbrain doctor --remediate`
+
+```bash
+gbrain doctor --remediate --yes --target-score 90 --max-usd 5
+```
+
+Computes a dependency-ordered plan of maintenance jobs that would raise the brain's health score to the `--target-score`, runs the plan, refuses to spend past the `--max-usd` cap. Safe to cron.
+
+### Monitoring: `gbrain sources status` and the admin dashboard
+
+```bash
+gbrain sources status
+```
+
+Returns a per-source dashboard: when each source last synced, how many pages, how many embedded, how many unacked sync failures. The at-a-glance health check.
+
+The admin dashboard at `https://brain.acme-co.com/admin` shows live request volume, registered OAuth clients, recent activity, and brain stats. Use the admin bootstrap token from Part 4 to log in the first time, then register additional admin users from inside the dashboard.
+
+---
+
+## Part 13: Cost and speed expectations
+
+Real numbers from the published benchmark, running the default stack (GBrain with ZeroEntropy for embedding + reranker):
+
+- **Embedding cost:** $0.05 per million tokens. For comparison, GBrain configured with OpenAI is $0.13 (2.6× more expensive), Voyage is $0.18 (3.6× more).
+- **Ingest speed:** about 22 seconds for a small test corpus of 164 pages on the host machine. For a 10K-page corpus, expect about 20 minutes the first time, then most syncs are incremental and finish in seconds.
+- **Query latency:** about 122 ms median for a `gbrain search`. For comparison, the same query through GBrain with OpenAI takes about 282 ms.
+- **Synthesized-answer latency:** a few seconds, dominated by the Anthropic API.
+- **Retrieval quality:** on the public LongMemEval benchmark, GBrain hits 97.60% recall at the top 5 retrieved sessions, beating the previous published state of the art at 96.6%. On the in-house BrainBench corpus of relational queries, GBrain beats commodity vector retrieval by 38 percentage points, because the graph layer surfaces relationships that vector similarity alone misses.
+
+Full methodology and per-run receipt JSONs live in [the gbrain-evals repo](https://github.com/garrytan/gbrain-evals/blob/main/docs/benchmarks/2026-05-23-v0.40.6.0-snapshot.md).
+
+For a 25-person company at sustained use, expect about $35 a month in embeddings (ZeroEntropy at $0.05/million tokens), $50 a month in Anthropic calls for the synthesized-answer queries, plus your hosting bill. Under $100 a month for the AI side at most companies your size.
+
+---
+
+## Part 14: Common gotchas
+
+### "My teammate can't see anything"
+
+Check `gbrain auth list` on the host and confirm their client has `--source` set to a source that actually exists. Empty or null `--source` means the client falls through to the `default` source, which probably has no content if you set up three named sources.
+
+### "Sync is slow and feels stuck"
+
+The first sync embeds every page, which takes time. Check `gbrain sources status` for the live page count. If it's climbing you're not stuck, you're just embedding. If you've got a 10K-page corpus and ZeroEntropy is being throttled, the per-source parallel sync looks like progress on three sources at once rather than one source moving fast.
+
+### "I see a page I shouldn't see"
+
+This shouldn't happen, but if you suspect it, run `gbrain search <query> --remote --json` as the constrained client and inspect the `source_id` field on every returned result. Every row should be in the client's `--federated-read` set. If one isn't, file an issue with the exact slug and source IDs.
+
+### "The synthesized answer is wrong"
+
+The brain layer is grounded in the retrieved pages. If the retrieved pages contain bad information, the answer will too. The gap-analysis note often catches this: if the answer says "based on retrieved pages from date X" and date X is six months ago, the brain is telling you the information is stale. Run `gbrain sync --all` to refresh and try again.
+
+### "OAuth `/token` endpoint returns 401 for my client"
+
+Verify the client secret matches what was printed at register-client time. The server stores only a SHA-256 hash; if you lost the original, you have to revoke the client and re-register. Use `gbrain auth revoke-client <client_id>` and re-run `register-client`.
+
+### "Postgres connection is exhausting"
+
+Each parallel sync worker opens its own pool. With three sources and the default four workers per source, you can hit your Postgres connection limit if it's set low. Either reduce the worker count with `gbrain sync --all --parallel 2 --workers 2`, or raise your Postgres `max_connections` to at least 100. Supabase's free tier defaults to 60, which is tight.
+
+### "I want to add a fourth teammate but they need access to all three sources"
+
+```bash
+gbrain auth register-client diana-example \
+  --grant-types client_credentials \
+  --scopes read,write \
+  --source shared \
+  --federated-read shared,customers,internal
+```
+
+That's it. Add or rotate teammates as the org grows.
+
+---
+
+## What you built
+
+You now have the personal-brain agent from the previous tutorial, plus a multi-user shared layer on top: three federated sources holding shared, customer, and internal-only content; per-person folders inside each source so teammates' writes don't collide; per-person OAuth clients with scoped read and write; per-person crons that run on each teammate's own schedule with their own scoping; per-person skills the agent only runs for the right person. Each teammate queries the brain in plain English through their AI client and gets back synthesized, sourced answers that are correctly scoped.
+
+What to do next:
+
+- **Wire ingestion** from external systems (Granola, Linear, Slack) using the [ingestion source contract](../skillpack-anatomy.md). Most companies want their meetings auto-ingested so the brain stays current without anyone typing notes.
+- **Set up team-specific dashboards** through the admin UI. Each team lead can have their own view of brain health and activity.
+- **Explore the rest of the brain layer.** `gbrain whoknows` (find the expert on a topic), `gbrain find_trajectory` (how a metric changed over time), `gbrain founder scorecard` (especially useful for VC and ops teams), the contradiction-detection cycle that surfaces conflicts between different people's notes.
+
+If you're building in this space (which YC has flagged as the [company-brain category in its Request for Startups](https://www.ycombinator.com/rfs#company-brain)), you might as well build on this. Everything described above is open source, MIT licensed, and what I run in production behind my own AI agents.
+
+Questions, gotchas, or wins worth sharing? Open an issue at [github.com/garrytan/gbrain](https://github.com/garrytan/gbrain/issues).

docs/tutorials/personal-brain.md

@@ -0,0 +1,257 @@
+# Tutorial: Set up your personal AI agent + brain from zero
+
+By the end of this tutorial you'll have your own AI agent running on a server you control, talking to you over Telegram, with a brain that remembers everything you tell it. About two hours end-to-end, $100 to $150 a month sustained.
+
+This is the install I'd run if I were setting up the whole stack from scratch today. I documented it live during a setup session with a collaborator (we used Granola to capture the screen because "this is already too complicated for an archetypical person"). The tutorial is the cleaned-up version of that session.
+
+> "This is the Apple I, we're just soldering breadboards over here."
+
+If you only want the **brain layer** (no agent, no Telegram, just gbrain as memory for an MCP client you already use), skip to the [CLI standalone install](../INSTALL.md#2-cli-standalone) in INSTALL.md. If you want the whole agent **shared with a team**, read the [company brain tutorial](company-brain.md) instead. This tutorial is the solo, full-stack, talk-to-it-on-Telegram path.
+
+---
+
+## What you're building
+
+A personal AI agent with four pieces:
+
+- **A brain** (git repo). Your knowledge base, constantly ingesting and growing.
+- **A harness** (OpenClaw via AlphaClaw). The runtime that gives the LLM tools, memory, and integrations.
+- **A chat interface** (Telegram). How you talk to it.
+- **Skills** (60+ installed via GBrain). Reusable capabilities the agent can invoke.
+
+Architecture:
+
+```
+Telegram → AlphaClaw (harness) → OpenClaw (agent) → GBrain (knowledge/skills) → Supabase (embeddings/search)
+```
+
+Git repo is the system of record. The whole thing is multiplayer by default: any agent that hooks into the repo works. Conflicts resolve through git.
+
+---
+
+## Prerequisites
+
+| Requirement | Why |
+|---|---|
+| GitHub account (org or personal) | For the two repos that store the agent + brain |
+| Render account | For hosting the agent runtime |
+| Telegram account | For talking to your agent |
+| API keys: OpenAI, Anthropic at minimum | Embeddings + the Claude model |
+| About $100 to $150 a month | Render Pro + Supabase + API usage |
+
+---
+
+## Step 1: Create two GitHub repos
+
+You need two repos, not one.
+
+1. **Workspace repo.** Agent configuration, skills, memory, crons. Example name: `your-org/myagent`. Private.
+2. **Brain repo.** Knowledge base, people pages, meeting notes, all the content the agent reads and writes. Example name: `your-org/myagent-brain`. Private.
+
+```
+GitHub → New Repository → your-org/myagent           (workspace)
+GitHub → New Repository → your-org/myagent-brain     (brain)
+```
+
+Both repos start empty. GBrain will populate the brain repo with its default structure on first install.
+
+---
+
+## Step 2: Generate a fine-grained Personal Access Token
+
+GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens.
+
+- **Name:** `myagent-token`
+- **Expiration:** 1 year (or no expiration if available)
+- **Repository access:** select both repos only
+- **Permissions:** Read AND Write access to both repos (Contents, Metadata, Pull requests)
+
+GitHub's fine-grained PAT UI is painful. You may need to reload the page after creating repos before they appear in the selector. This is the worst part of the whole setup. Push through.
+
+Save this token. You'll need it for the AlphaClaw setup.
+
+---
+
+## Step 3: Create a Telegram bot
+
+1. Open Telegram, message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot`
+3. Name your bot (whatever you want)
+4. Get the bot token
+5. Save it. You'll need it for the AlphaClaw setup.
+
+---
+
+## Step 4: Deploy via AlphaClaw on Render
+
+AlphaClaw is the setup harness that manages OpenClaw deployment.
+
+1. Go to [alphaclaw.com](https://alphaclaw.com)
+2. Enter your **workspace repo** (not the brain repo): `your-org/myagent`
+3. Select "Use existing" if the repo already exists
+4. Enter your GitHub PAT from Step 2
+5. Enter your Telegram bot token from Step 3
+6. Deploy
+
+Render will build a Docker container with the harness. First deploy takes about 5 minutes.
+
+**Memory matters.** If the instance runs out of memory during install, upgrade to Render Pro. The base tier is too small for GBrain + OpenClaw together. My production instance runs 48 cores and 64GB RAM (about $1,500 a month) but that's overkill for a new setup. Pro tier ($85 a month) is the minimum viable.
+
+---
+
+## Step 5: Add provider API keys
+
+In the AlphaClaw UI (Providers tab):
+
+- **OpenAI API Key.** Required for embeddings if you use the OpenAI provider.
+- **Anthropic API Key.** Required for Claude (the main model the agent talks through).
+- **Perplexity API Key.** Optional, for web search.
+- **Voyage API Key.** Optional, alternative to OpenAI for embeddings.
+- **ZeroEntropy API Key.** Recommended. GBrain ships with ZeroEntropy as the default embedder + reranker because it's about 2× faster than OpenAI and about 2.6× cheaper.
+
+You can use the same keys across multiple agents.
+
+---
+
+## Step 6: Install GBrain
+
+Once OpenClaw is running:
+
+```bash
+gbrain install
+```
+
+This installs:
+
+- About 60 skills
+- About 9 skill packs
+- Default brain structure
+- MCP server configuration
+- Supabase connection (for embeddings and search)
+
+GBrain populates the brain repo with its default directory structure, skill files, and configuration. From this point, the agent has working memory and access to every skill.
+
+---
+
+## Step 7: Set up Supabase (embeddings and search)
+
+GBrain uses Supabase for vector embeddings and full-text search at scale. There are three setup gotchas I hit the hard way. Walk through them in this order.
+
+### 7a. Create the project and turn on pgvector
+
+1. Create a Supabase project at [supabase.com](https://supabase.com). Pick a region close to where your Render host runs.
+2. In the Supabase dashboard, go to **Database → Extensions**.
+3. Find `vector` (the pgvector extension) and toggle it on.
+
+Skip this and every embed write fails with "type vector does not exist" the moment GBrain tries to create its schema. pgvector is what stores the embeddings; the schema migrations refuse to run without it. Five seconds in the UI; an hour of debugging if you forget.
+
+### 7b. Get the CONNECTION POOLER connection string, not the direct one
+
+In **Project Settings → Database → Connection string**, Supabase shows you two options. They look almost identical. Use the right one.
+
+- **Direct connection** (port 5432). Talks straight to the Postgres instance. IPv6-only. Will fail if your Render host doesn't have IPv6 outbound (most don't by default).
+- **Connection pooler** (port 6543, hostname starts with `aws-0-...pooler.supabase.com`). Talks through Supabase's pgbouncer. Works over IPv4. Survives connection storms from parallel workers.
+
+You want the **connection pooler** string. Format looks like:
+
+```
+postgresql://postgres.YOUR-PROJECT:YOUR-PASSWORD@aws-0-us-west-1.pooler.supabase.com:6543/postgres
+```
+
+Configure it via:
+
+```bash
+gbrain config set database_url "postgresql://postgres.YOUR-PROJECT:YOUR-PASSWORD@aws-0-us-west-1.pooler.supabase.com:6543/postgres"
+```
+
+### 7c. Buy the IPv4 add-on if your host is IPv4-only
+
+Even with the pooler, some Supabase regions and some Render plans hit IPv6 resolution snags. If your `gbrain doctor` shows connection failures and the error mentions "network unreachable" or hangs forever on connect, you need Supabase's **IPv4 add-on**.
+
+In the Supabase dashboard, **Project Settings → Add-ons → IPv4 address**. About $4 a month. Toggle on, wait a minute, retry the connection. This bit me on multiple installs before I learned to just buy it up front.
+
+### 7d. Verify the connection
+
+```bash
+gbrain doctor
+```
+
+Green checks on schema, connectivity, pgvector extension, embedding provider. If any of those are yellow, the message will tell you which gotcha you hit (and which of 7a / 7b / 7c to revisit).
+
+### Operating note
+
+Supabase is usually the scaling bottleneck, not CPU or LLM calls. If you're doing heavy ingestion (emails, calendar, Slack streaming in), upgrade from small to large DB instance early. Don't wait for the small instance to choke; the symptoms (silent failed inserts, sync timeouts, embedding backfill stalls) all look like different bugs but are the same bug.
+
+---
+
+## Step 8: Verify and chat
+
+1. Open Telegram
+2. Message your bot
+3. It should respond using OpenClaw + GBrain
+
+Send a test message. If it responds with context-awareness and can search the brain, you're live.
+
+---
+
+## Architecture notes
+
+### Git as system of record
+
+The brain repo IS the brain. Any agent that can read and write to the git repo can participate. This makes the architecture inherently multiplayer: multiple agents can share a brain, work on different parts, and resolve conflicts through git.
+
+### Thin client vs fat client
+
+- **Fat client** (my production setup). OpenClaw + AlphaClaw + GBrain + 200 crons + email processing + Slack + calendar. About $1,500 a month. Processes everything in real time.
+- **Thin client** (what this tutorial builds). OpenClaw + GBrain + Telegram. About $85 a month. Chat-driven, on-demand.
+
+The goal for GBrain is to make the thin client as awesome as the fat client. Most users will start thin and grow.
+
+### MCP server
+
+GBrain exposes a Model Context Protocol server that enables inter-agent communication and integration with external systems. This is how you add read and write access to your product's API, databases, or other services.
+
+### Brain sharing
+
+Brains share through git. My main agent can populate another agent's brain by pushing content to its repo. The MCP layer enables cross-agent brain queries. Just push to the git repo and the other agent picks it up on next sync.
+
+---
+
+## What this costs
+
+| Component | Monthly cost |
+|-----------|-------------|
+| Render Pro (minimum viable) | about $85 |
+| Supabase (small) | free to $25 |
+| OpenAI API (embeddings) | $5 to $20 (much less if you use ZeroEntropy as the default) |
+| Anthropic API (Claude) | $50 to $500 (usage dependent) |
+| **Total minimum** | **about $100 to $150 a month** |
+
+My production setup is about $10,000 a month, but that's 10 instances, 200 crons, processing email and Slack and calendar in real time, running sub-agents. Not what you need on day one.
+
+> "Next year it's not going to cost $10,000 a month. It'll cost $1,000 a month. And then the year after that, it'll be $100 a month, and then everyone will have it."
+
+---
+
+## Common issues
+
+1. **Render runs out of memory during install.** Upgrade to Pro tier.
+2. **GitHub PAT can't see the repos.** Reload the page after creating repos. Make sure the fine-grained token has the correct repo selection.
+3. **Telegram bot doesn't respond.** Check the bot token in AlphaClaw. Make sure the Render instance is actually running.
+4. **Supabase bottleneck on heavy ingestion.** Upgrade the DB instance size before the small one chokes.
+5. **GBrain.io provisioning fails.** The hosted instance may need Pro tier. Check the machine allocation in the AlphaClaw UI.
+
+---
+
+## What you built
+
+You now have a personal AI agent running on Render, talking to you on Telegram, with a brain that ingests and remembers everything you tell it. Every conversation gets indexed, every new entity (person, company, deal, concept) gets its own page, the overnight enrichment daemon dedupes and consolidates while you sleep. You wake up with a smarter agent than the one you went to bed with.
+
+Where to go next:
+
+- **Wire ingestion** from external systems. Email, calendar, voice calls, tweets, Slack. The skills are already installed; you just configure the credentials. See [`docs/integrations/`](../integrations/) for per-source recipes.
+- **Connect your existing AI client** (Claude Code, Cursor, Claude Desktop) to the same brain. See [`docs/mcp/`](../mcp/) for per-client setup.
+- **Set up the dream cycle** properly. The autopilot daemon runs overnight enrichment by default but you can tune what it does. See [`docs/architecture/`](../architecture/) for the full cycle reference.
+- **Add a teammate to your brain**, or stand the whole thing up as a company brain. See the [company brain tutorial](company-brain.md) for the multi-user walkthrough.
+
+Questions, gotchas, or wins worth sharing? Open an issue at [github.com/garrytan/gbrain](https://github.com/garrytan/gbrain/issues).

llms-full.txt

@@ -2513,74 +2513,156 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/README.md
 
 # GBrain
 
-Your AI agent is smart but forgetful. GBrain gives it a brain.
+**Search gives you raw pages. 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.
 
-Built by the President and CEO of Y Combinator to run his actual AI agents. The production brain behind his OpenClaw and Hermes deployments: **146,646 pages, 24,585 people, 5,339 companies**, 66 cron jobs running autonomously. The agent ingests meetings, emails, tweets, voice calls, and original ideas while you sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. You wake up smarter than when you went to bed.
+I'm Garry Tan, President and CEO of Y Combinator. I built GBrain to run my own AI agents. It's the production brain behind my OpenClaw and Hermes deployments: **146,646 pages, 24,585 people, 5,339 companies**, 66 cron jobs running autonomously. My agent ingests meetings, emails, tweets, voice calls, and original ideas while I sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. I wake up smarter than when I went to bed — and so will you.
 
-The brain wires itself. Every page write extracts entity references and creates typed links (`attended`, `works_at`, `invested_in`, `founded`, `advises`) with zero LLM calls. Hybrid search. Self-wiring knowledge graph. Structured timeline. Backlink-boosted ranking. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked side-by-side: gbrain lands **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, beating its graph-disabled variant by **+31.4 points P@5** and ripgrep-BM25 + vector-only RAG by a similar margin. Full BrainBench scorecards live in the sibling [gbrain-evals](https://github.com/garrytan/gbrain-evals) repo.
+**And now it works as a company brain too.** 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. Drop GBrain in as your team's shared institutional memory — the [company-brain](https://www.ycombinator.com/rfs#company-brain) shape YC just put on its Request for Startups. If you're building in that space, you might as well build on this. **[Tutorial: set up GBrain as your company brain →](docs/tutorials/company-brain.md)**
 
-**New default in v0.36.2.0: ZeroEntropy** for both embedding (`zembed-1` at 1280d via Matryoshka) and reranker (`zerank-2`). On a real-corpus benchmark vs OpenAI and Voyage: **2.2× faster** (442ms vs OpenAI 973ms), **2.6× cheaper at regular pricing** ($0.05/M vs OpenAI $0.13), wins 11 of 20 queries head-to-head, reshuffles 60% of top-1 results when used as a second-pass reranker. Bring your own key from [zeroentropy.dev](https://dashboard.zeroentropy.dev), or switch to OpenAI/Voyage at install time via `gbrain init --pglite --embedding-model <provider:model> --embedding-dimensions <N>` — your choice is sticky. To switch an existing brain, run `gbrain reinit-pglite --embedding-model <provider:model> --embedding-dimensions <N>` (PGLite) or follow the SQL recipe in `docs/embedding-migrations.md` (Postgres). `gbrain config set embedding_model` is refused as of v0.37.11.0 because the schema column has to resize too.
+Lots of personal-knowledge systems give you keyword matching and grep in a box. GBrain does that, and adds two things nobody else ships together:
 
-GBrain is those patterns, generalized. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.
+- **A synthesis layer that gives you the actual answer.** Synthesized, well-cited prose across people, companies, deals, and ideas. Not "here are 10 chunks that mention your query"; an actual answer with citations and an explicit note on what the brain doesn't know yet. The gap analysis is the part that changes how you use the brain.
+- **A self-wiring knowledge graph.** Every page write extracts entity refs and creates typed edges (`attended`, `works_at`, `invested_in`, `founded`, `advises`) with zero LLM calls. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked: **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, **+31.4 points P@5** over its graph-disabled variant and over ripgrep-BM25 + vector-only RAG by a similar margin. Full BrainBench scorecards live in the sibling [gbrain-evals](https://github.com/garrytan/gbrain-evals) repo.
 
-**New in v0.40.2.0 — `gbrain think` grounds temporal answers in the typed-claim timeline.** Ask "when did Marco last switch jobs" or "what was the ARR in March" and the answer comes back rooted in a real chronological timeline of the metric + event facts your brain already extracted via the `extract_facts` cycle phase. Default ON. The intent classifier (`temporal` / `knowledge_update` / `other`) is a regex pass with zero LLM cost; the `'other'` fast path short-circuits with zero extra SQL. Migration v82 adds a nullable `facts.event_type` column so the same plumbing carries event-shaped rows (`'meeting'`, `'job_change'`, `'location_change'`) alongside metric rows. Flip `think.trajectory_enabled=false` to opt out. Debug with `GBRAIN_THINK_DEBUG=1 gbrain think "..."` to see the spliced prompt. The same trajectory plumbing also lands in the LongMemEval benchmark with a methodology change disclosed in `methodology_note: extractor=haiku-preprocess-full-haystack-v1` — published scores are "gbrain + Haiku-preprocess pipeline" vs "gbrain alone", NOT directly comparable to baseline LongMemEval numbers without that note.
+The point of building a 100K-page brain is to use it as a strategic moat. To never lose context. To query what's in your own head without re-reading it. The brain layer is what makes the moat usable. The 24/7 dream cycle is what keeps it sharp. Both run on your hardware, your DB, your keys.
 
-**New in v0.40.7.0 — Your agents can now author your brain's schema pack themselves.** No more shell-out, no more hand-editing YAML. Tell your OpenClaw (or any agent connected via MCP) "my brain has 4000 untyped meetings pages — add a `meeting` type and backfill them," and it does the whole thing safely: per-pack atomic file lock, validation gate that catches dangling references pre-write, atomic write so a crash never leaves the pack half-written, privacy-redacted audit log with the agent's identity, chunked UPDATE in 1000-row batches that never wedge concurrent writers. 14 new `gbrain schema` CLI verbs (`add-type`, `remove-type`, `add-alias`, `add-link-type`, `stats`, `sync`, etc.) + 9 new MCP ops including the batched `schema_apply_mutations` (admin scope, NOT localOnly — remote agents reach it over normal HTTPS MCP). New `schema-author` skill with explicit boundary callouts to `brain-taxonomist` and `eiirp` so agents pick the right surface. The schema-pack cathedral that shipped in v0.39.1.0 is now reachable from the outside. **Why it matters:** [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — 7 killer use cases (4000 invisible meetings made queryable, the founder ops brain, the research brain, the legal brain, the team brain, agent-as-co-curator) plus the structural difference between a pile of notes and a brain with structure. **Walkthrough:** [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — fork the bundled pack, add a `researcher` type, backfill, query in 5 minutes.
-
-**New in v0.36.4.0 — Your agent drives the brain to 90/100 by itself.** One command does the loop you used to run by hand: `gbrain doctor --remediate --yes --target-score 90 --max-usd 5`. It computes a dependency-ordered plan (sync before extract, embed after consolidate), submits each step as a Minion job, re-checks score between every step, and refuses to spend past your cost cap. Cron can drive it unattended. `gbrain doctor --remediation-plan --json` previews what would run. Autopilot now does the same thing on its 5-minute tick: small problems get targeted handlers, big problems get the full cycle, a healthy brain sleeps for 60 minutes instead of grinding through synthesize+patterns+embed every tick. Eleven new things you can submit as background jobs (`reindex`, `repair-jsonb`, `orphans`, `integrity`, `purge`, plus six cycle phases); three of them (synthesize, patterns, consolidate) are PROTECTED so an MCP-connected agent can't silently burn Anthropic credits. New `--background` flag on `gbrain embed` submits the job and exits with `job_id=N` for shell composition.
-
-**New in v0.35.7 — Temporal trajectory + founder scorecard.** Author typed metric assertions in the `## Facts` fence (`mrr=50000`, `arr=2000000`, `team_size=12`) and gbrain stores them as first-class typed columns. `gbrain eval trajectory companies/acme-example` prints the chronological history with regressions auto-flagged inline. `gbrain founder scorecard companies/acme-example` rolls up claim accuracy, consistency, growth direction, and red flags into a stable `schema_version: 1` JSON contract. New MCP op `find_trajectory` exposes the same data to agents (read scope, visibility-filtered for remote callers). The `consolidate` cycle phase now writes `valid_until` on chronologically-superseded facts AND uses semantic upsert on `(page_id, claim, since_date)` — re-running the dream cycle on stable input is now a true no-op (fixed a pre-existing duplicate-takes bug from prior versions).
+It's easier to ship a daemon that runs 24/7 to ingest, enrich, and consolidate than it is to keep an agent in chat working hard. GBrain is that daemon, generalized. Install in 30 minutes. Your agent does the work. As my personal agent gets smarter, so does yours.
 
 > **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.
 
 > **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).
 
-## Install
+## What this looks like
 
-GBrain runs in three shapes. Pick the one that matches how you use AI agents today.
+Say you have a meeting with Alice tomorrow. You want to walk in remembering what she works on, when you last talked, and what's still open between you. Here's what you'd type, and what you'd get back.
 
-### Run with your agent platform
+**You ask:**
 
-Already using [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)? GBrain installs as a skillpack scaffold into your agent's workspace.
+> "What do I need to know before my meeting with Alice tomorrow?"
 
-```bash
-gbrain init --pglite
-gbrain skillpack scaffold --all   # or: scaffold <name> per skill
+**Most personal-knowledge tools give you back a list of pages.** Something like:
+
+```
+1. people/alice — Alice runs engineering at Acme...
+2. meetings/2026-03-15-alice-q1 — Q1 product review with Alice...
+3. meetings/2026-01-08-acme-kickoff — Kickoff meeting with Acme team...
+4. customers/acme — Acme is a series-B fintech we work with...
+5. notes/2026-04-22 — Quick chat with Alice about pricing...
 ```
 
-That's it. Your agent picks up 43 skills (signal detection, brain-ops, ingest, enrich, citation-fixer, daily-task-manager, cron-scheduler, eval framework, and 35 more). Routing lives in `skills/RESOLVER.md` — the agent reads it once per request, picks the right skill, executes. Scaffolded skills are first-class members of your agent repo — you own them, edit freely; `gbrain skillpack reference <name>` diffs your copy against gbrain's bundle when you want to pull upstream improvements. (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.)
+Five pages you now have to open and read yourself to actually prepare. The tool found the right material, but it didn't do the work.
 
-### CLI standalone
+**GBrain gives you back the answer, with sources:**
 
-Use gbrain from any shell, no agent platform required.
+```
+Alice runs engineering at Acme (a series-B fintech). You last spoke
+on April 22 in a quick pricing chat. Three things are still open
+from that conversation:
+
+1. She owes you the security review for the new tier
+   (deadline was May 1; no update since).
+2. You committed to pricing for a 500-seat tier
+   (you sent it April 25; no response yet).
+3. She mentioned they're hiring a CISO; you said you'd intro
+   someone from your network.
+
+Heads up: nothing's been added to the brain about Alice or Acme
+since April 22, six weeks ago. She may have replied through email
+or Slack DM, channels the brain doesn't see. Worth asking her to
+catch up before assuming any of this is still current.
+```
+
+Every claim has a source page behind it. The "heads up" at the end tells you what the brain doesn't know yet, so you can ask Alice about it directly instead of being surprised. The brain just did your meeting prep.
+
+This is the difference between a search engine and a brain. Search finds the pages. The brain reads them for you and writes the answer.
+
+## Install
+
+GBrain is designed to be installed and operated by an AI agent. The fastest path is to have your agent do it for you. The CLI and MCP paths below are for people who want to wire it up themselves.
+
+### Have your agent install it (recommended)
+
+If you don't already have an AI agent platform running, start with one of these. Both are designed to read GBrain's install protocol and execute it:
+
+- **[OpenClaw](https://github.com/openclawagents/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
+- **[Hermes](https://github.com/openclawagents/hermes)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
+
+Then paste this into your agent:
+
+```
+Retrieve and follow the instructions at:
+https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
+```
+
+The agent installs GBrain, creates the brain, asks for your API keys, loads 43 skills, configures the dream cycle, and verifies the install end-to-end. ~30 minutes. You answer questions, it does the work.
+
+> **Never set up an AI agent platform before?** The [personal-brain tutorial](docs/tutorials/personal-brain.md) walks the whole path end-to-end — picking OpenClaw vs Hermes, deploying it, pointing it at INSTALL_FOR_AGENTS.md, getting the API keys, and verifying the first query. Start there if any of the above is new.
+
+### Install it into your existing agent
+
+Already running Codex, Claude Code, Cursor, or another coding agent? Paste the same instruction in:
+
+```
+Retrieve and follow the instructions at:
+https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
+```
+
+This works in any agent that can read files over HTTPS and execute shell commands. Tested with Codex, Claude Code, Claude Cowork, Cursor, and AlphaClaw.
+
+### CLI standalone (no agent)
 
 ```bash
 bun install -g github:garrytan/gbrain
-gbrain init --pglite   # 2 seconds; no server, no Docker
-gbrain doctor          # verify health
+gbrain init --pglite     # 2 seconds; no server, no Docker
+gbrain doctor            # verify health
+gbrain import ~/notes/   # index your markdown
+gbrain query "what themes show up across my notes?"
 ```
 
-Then point any MCP-aware client (Claude Code, Cursor, Windsurf) at it, or use it from your shell:
+Postgres-at-scale, Supabase, and thin-client setup paths live in [`docs/INSTALL.md`](docs/INSTALL.md).
+
+### Connect GBrain to your AI client (MCP)
+
+GBrain exposes 30+ tools over MCP (stdio and HTTP). The specific snippet depends on which client you use:
+
+- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — one command: `claude mcp add gbrain -- gbrain serve`. Zero server, zero tunnel.
+- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve"]}` to your MCP config.
+- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.
+- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.
+- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — Settings → Connectors → add the URL + bearer token. Pro subscription required.
+- **[ChatGPT](docs/mcp/CHATGPT.md)** — uses OAuth 2.1 with PKCE (the hard requirement). Register a `chatgpt` client from the admin dashboard with grant type `authorization_code`.
+
+For the HTTP server itself:
 
 ```bash
-gbrain search "who works at acme AI?"
-gbrain query "what did bob invest in this quarter?"
-gbrain graph-query people/garry-tan --depth 2
+gbrain serve              # stdio MCP (local subprocess; for Claude Code, Cursor, Windsurf)
+gbrain serve --http       # HTTP MCP with OAuth 2.1 + admin dashboard at /admin
+                          # (required for Claude Desktop, Cowork, Perplexity, ChatGPT)
 ```
 
-Detailed setup paths (Postgres at scale, Supabase, thin-client mode) live in [`docs/INSTALL.md`](docs/INSTALL.md).
+The HTTP server includes DCR-style client registration, scope-gated access (`read` / `write` / `admin`), and rate limiting. Deployment guides (ngrok, Railway, Fly.io) live under [`docs/mcp/`](docs/mcp/).
 
-### MCP server (any MCP client)
+## Two ways to query your brain
+
+Raw retrieval (what most personal-knowledge tools ship) and a synthesis layer that gives you an actual answer. They serve different jobs.
 
 ```bash
-gbrain serve              # stdio MCP (Claude Desktop / Code / Cursor)
-gbrain serve --http       # HTTP MCP with OAuth 2.1 + admin dashboard
-                          # at /admin, SSE activity feed at /admin/events
+# raw retrieval: top pages by hybrid score, fast, no LLM cost
+gbrain search "who's working on AI agents at portfolio companies?"
+
+# brain layer: synthesized answer with citations and gap analysis
+gbrain think "who's working on AI agents at portfolio companies?"
 ```
 
-Per-client guides (Claude Desktop, Code, Cursor, ChatGPT, Perplexity, Cowork) live under [`docs/mcp/`](docs/mcp/). HTTP server supports DCR-style client registration, scope-gated access (`read`/`write`/`admin`), and built-in rate limiting.
+**`gbrain search`** returns the top retrieved pages, ranked by hybrid scoring (vector + keyword + RRF + source-tier boost + reranker). Use it when you want raw material to skim: agent context windows, citation lookups, finding a specific quote.
 
-## How to get data in (v0.38+)
+**`gbrain think`** runs the same retrieval, then composes a synthesized answer across the results with explicit citations to the source pages AND an honest note on what the brain doesn't know yet. The gap analysis is the differentiator: the answer tells you when a page is stale, when a claim is uncited, when two pages contradict each other, when there's a hole you should fill.
+
+**Why it compounds.** Pair the brain layer with `find_trajectory` and you get answers like *"how have the company's metrics changed AND what does the team look like right now AND what did they promise / share AND when did we last meet AND what's the value-add I can offer here"*: well-scored, well-cited, in one shot. That's the strategic moat. That's why building a 100K-page brain is worth the effort.
+
+`gbrain agent run "..."` exposes the same surface to a sub-agent through the Minions queue, with crash-safe two-phase persistence. Same answers, durable.
+
+## How to get data in
 
 One command, local or hosted, synchronous receipt:
 
@@ -2591,10 +2673,7 @@ echo "from a pipe" | gbrain capture --stdin
 SLUG=$(gbrain capture "..." --quiet)
 ```
 
-The page lands in the DB AND on disk in one move (the v0.38 `put_page`
-write-through plumbing). Default slug `inbox/YYYY-MM-DD-<hash8>` so
-captures cluster in a predictable triage location. On thin-client installs
-the verb routes through MCP to the server — same command, same UX.
+The page lands in the database and on disk in one move. Default slug `inbox/YYYY-MM-DD-<hash8>` so captures cluster in a predictable triage location. On thin-client installs the verb routes through MCP to the server: same command, same UX.
 
 For webhook ingestion (Zapier / IFTTT / Apple Shortcuts):
 
@@ -2612,6 +2691,40 @@ Third-party skillpacks can ship custom ingestion sources (Granola, Linear,
 voice, OCR) against the versioned `IngestionSource` contract at
 `gbrain/ingestion`. See [`docs/skillpack-anatomy.md`](docs/skillpack-anatomy.md).
 
+## Your brain's shape (schema packs)
+
+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 on top, and the agent doesn't know what a `Projects/` folder means or whether `Reading/` is people or sources.
+
+**gbrain doesn't have a fixed layout.** It ships with two bundled schema packs and lets you author your own when neither fits:
+
+- **`gbrain-base`** (default) — the layout my production brain uses: `people/`, `companies/`, `concepts/`, `meetings/`, `deal/`, `daily/`, `originals/`, `writing/`, etc. Zero config. Drop a brain that fits this shape and everything works.
+- **`gbrain-recommended`** — extends `gbrain-base` with the 13 additional directories from `docs/GBRAIN_RECOMMENDED_SCHEMA.md` (source, place, trip, conversation, personal, civic, project, etc.). Activate with `gbrain schema use gbrain-recommended`.
+- **Your own pack** — `gbrain schema detect` clusters your actual filesystem into proposed types, `gbrain schema suggest` runs an LLM pass over them, and `gbrain schema review-candidates --apply` promotes the ones you like. Three commands and the brain knows your shape.
+
+```bash
+gbrain schema active                # which pack is running, which tier set it
+gbrain schema list                  # bundled + installed packs
+gbrain schema detect                # propose types matching your filesystem
+gbrain schema suggest               # LLM-refined proposals on top of detect
+gbrain schema review-candidates     # human gate: promote / rename / ignore
+gbrain schema use my-pack           # activate
+```
+
+The active pack threads through every read + write path: `parseMarkdown` infers page type from the pack's path prefixes; `whoknows` scopes expert routing to types declared `expert_routing: true`; `extract_facts` runs only on `extractable: true` types; the search cache folds the pack name + version into its key so cross-pack contamination is structurally impossible. Switch packs and the brain re-interprets itself; switch back and nothing's lost.
+
+Seven-tier resolution chain (per-call flag → env var → per-source DB key → brain-wide DB key → `gbrain.yml` → `~/.gbrain/config.json` → `gbrain-base` default). Full reference + authoring guide: [`docs/architecture/schema-packs.md`](docs/architecture/schema-packs.md).
+
+## Tutorials
+
+Step-by-step walkthroughs for getting the most out of GBrain. Each one takes you from zero to a working outcome, with concrete commands and real numbers.
+
+- [**Set up your personal AI agent + brain from zero**](docs/tutorials/personal-brain.md) — the canonical full-stack install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. End-to-end in about 2 hours.
+- [**Set up GBrain as your company brain**](docs/tutorials/company-brain.md) — federated, multi-user, OAuth-scoped institutional memory for a 10-50 person team. About 90 minutes end-to-end.
+
+More walkthroughs in progress: connecting an existing agent (Claude Code, Cursor, OpenClaw, Hermes) to a GBrain memory layer; setting up GBrain for VC dealflow with founder scorecards and meeting prep; migrating an existing Notion or Obsidian vault; indexing a codebase as a queryable code brain. Full tutorial index: [`docs/tutorials/`](docs/tutorials/).
+
+Want to see a tutorial that isn't here yet? [Open an issue](https://github.com/garrytan/gbrain/issues) describing the workflow you want documented.
+
 ## What it does (the loop)
 
 ```
@@ -2629,7 +2742,7 @@ The whole loop is described in [`docs/architecture/topologies.md`](docs/architec
 
 ## Capabilities
 
-**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). Default: `balanced` with ZeroEntropy reranker on. **New in v0.40.4.0:** per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns.
+**Hybrid search.** Vector (HNSW on pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. Three named search modes (`conservative`, `balanced`, `tokenmax`) bundle the cost/quality knobs into a single config key. Live cost/recall comparisons in [`docs/eval/SEARCH_MODE_METHODOLOGY.md`](docs/eval/SEARCH_MODE_METHODOLOGY.md). Default: `balanced` with ZeroEntropy reranker on. Per-query graph signals notice when a top result is a hub for THAT query (adjacency boost), is corroborated across team brains (cross-source boost), or is being crowded out by weak chunks from a chatty session (session demote). Run `gbrain search "<query>" --explain` to see per-stage attribution: base score, every boost that fired, what it multiplied. `gbrain doctor` ships a `graph_signals_coverage` check; `gbrain search stats` shows fire counts and failure breakdowns.
 
 **Self-wiring knowledge graph.** Every `put_page` extracts entity refs from markdown/wikilinks/typed-link syntax and writes edges with zero LLM calls. Typed edges (`attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, …). Multi-hop traversal via `gbrain graph-query`. The graph is what produces the +31.4 P@5 lift over vector-only RAG.
 
@@ -2665,7 +2778,7 @@ Data flowing into the brain. Each integration is a recipe — markdown + setup h
 
 ## Troubleshooting
 
-**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. As of v0.37, fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment — set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
+**`gbrain import` fails with `expected N dimensions, not M`?** Run `gbrain doctor`. It will print the exact `gbrain config set ...` or `gbrain retrieval-upgrade` command to repair the mismatch. You should not need to delete `~/.gbrain`. Fresh `gbrain init --pglite` auto-detects your embedding provider from API keys in your environment: set `OPENAI_API_KEY` (or `ZEROENTROPY_API_KEY` / `VOYAGE_API_KEY`) before running init, or pass `--embedding-model <provider>:<model>` explicitly. With multiple keys set, init fires an interactive picker. In non-TTY contexts (CI, Docker) with no keys, init exits 1 with a paste-ready setup hint; pass `--no-embedding` to defer setup until runtime. See [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md) for the full provider matrix and [`docs/operations/headless-install.md`](docs/operations/headless-install.md) for Docker/CI sequencing.
 
 ## Docs
 
@@ -2693,11 +2806,11 @@ If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc
 
 ## License + credit
 
-MIT. Built by Garry Tan to run his OpenClaw and Hermes deployments — the production brain behind his actual AI agents.
+MIT. I built GBrain to run my OpenClaw and Hermes deployments — the production brain behind my AI agents.
 
 Origin story: [`docs/ethos/ORIGIN.md`](docs/ethos/ORIGIN.md).
 
-Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that became the v0.36.2.0 default. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
+Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that ships as the default. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
 
 ---
 

package.json

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

test/readme-hero-anchors.test.ts

@@ -1,15 +1,24 @@
 /**
  * v0.36.0.0 (D9) — README hero anchor regression test.
  *
- * Pins 5 load-bearing strings in the first ~50 lines of README.md so future
- * "cleanup" PRs can't silently drop the headline metrics or the
- * OpenClaw/Hermes credit. The anchors are intentionally NARROW (5 substrings,
+ * Pins load-bearing strings in the first ~50 lines of README.md so future
+ * "cleanup" PRs can't silently drop the headline framing or the
+ * OpenClaw/Hermes credit. The anchors are intentionally NARROW (substrings,
  * not full hero text) so legitimate voice/structure edits don't fight the
  * test.
  *
  * If this test fails, ask: did we deliberately rotate the headline?
- *   - If yes: update the anchors here AND in the plan's D9 section.
+ *   - If yes: update the anchors here AND in the corresponding plan/spec.
  *   - If no: the README rewrite dropped something it shouldn't have.
+ *
+ * v0.40.8.1 — Garry rewrote the README to drop all version chatter from
+ * the lead (CHANGELOG.md owns version history; README is current docs).
+ * The original "ZeroEntropy default story" anchor was deliberately rotated
+ * out of the hero. The new load-bearing anchor is the search-vs-answer
+ * framing ("Search gives you raw pages. GBrain gives you the answer.")
+ * which is the headline differentiator of the post-rewrite hero.
+ * ZeroEntropy still appears further down the README; the guard just no
+ * longer pins it to the hero specifically.
  */
 
 import { describe, test, expect } from 'bun:test';
@@ -29,9 +38,12 @@ describe('README hero anchors (D9 regression guard)', () => {
     expect(hero).toContain('Hermes');
   });
 
-  test('mentions ZeroEntropy (the v0.36.0.0 default story)', () => {
-    // Accept either spelling — "ZeroEntropy" or the "ZE" short form.
-    expect(hero).toMatch(/ZeroEntropy|\bZE\b/);
+  test('leads with the search-vs-answer differentiator (v0.40.8.1+)', () => {
+    // The post-rewrite headline. "Search gives you raw pages. GBrain gives
+    // you the answer." is the load-bearing framing that distinguishes
+    // GBrain from MemPalace-shape retrieval tools. If a cleanup PR
+    // accidentally rewords this, the brand-level differentiator is lost.
+    expect(hero).toMatch(/Search gives you raw pages\. GBrain gives you the answer/);
   });
 
   test('includes at least one production number (pages/people/companies)', () => {