fix(docs): comprehensive drift audit — contradictions, broken links, stale refs#1201
Merged
Merged
Conversation
…stale refs
A community member reported docs 'have quite a bit of drift and some broken
links' and contradictions like 'says don't use bun but also to use bun.' This
PR is a top-to-bottom audit + fix across every doc file at the repo root and
under docs/. Where docs disagreed with each other, the code was the tie-breaker.
## Categories of fix
### 1. Stale CLI commands (skillpack install → scaffold)
`gbrain skillpack install` was retired in v0.36.0.0 (replaced by the
scaffold/reference/migrate-fence model). The CLI now errors out with a hint:
$ gbrain skillpack install
Error: 'gbrain skillpack install' was removed in v0.33.
Use 'gbrain skillpack scaffold <name>' instead.
But the docs still recommended it:
- README.md line 29 — primary install path
- docs/INSTALL.md lines 12 — primary install path
Both updated to `gbrain skillpack scaffold --all` with the v0.36.0.0 retirement
explained inline + the migrate-fence escape hatch for users upgrading from older
releases.
### 2. The 'bun install -g vs bun link' contradiction
The community member's exact complaint. The drift:
- README.md + docs/INSTALL.md: recommended `bun install -g github:garrytan/gbrain`
- INSTALL_FOR_AGENTS.md line 29: 'Do NOT use `bun install -g github:garrytan/gbrain`.'
Reading the code + CHANGELOG: `bun install -g` IS the canonical path. Bun
occasionally blocks the top-level postinstall hook on global installs (issue garrytan#218),
but the postinstall now prints a loud recovery hint when that happens, and
`gbrain doctor` flags `schema_version: 0` and routes users to
`gbrain apply-migrations --yes`. The 'do not use' warning was correct in 2024
when the postinstall silently swallowed errors with `|| true`; it's stale now.
Reconciled:
- INSTALL_FOR_AGENTS.md Step 1: now recommends `bun install -g` as the primary
path, documents garrytan#218 as a known issue with the recovery command, and keeps
`git clone + bun link` as a documented fallback.
- AGENTS.md Install (5 min): same reconciliation; clone path is the fallback,
not the default.
- docs/INSTALL.md CLI standalone: added the garrytan#218 callout so the deterministic
fallback is one click away when the default fails.
### 3. Broken internal links
- README.md → `docs/integrations/voice.md` (file doesn't exist). The real voice
recipe lives at `recipes/twilio-voice-brain.md` (Twilio + OpenAI Realtime).
Fixed to point there with an accurate one-line summary.
- CONTRIBUTING.md → `docs/SQLITE_ENGINE.md` (file doesn't exist; superseded by
PGLite per docs/ENGINES.md). Replaced with a paragraph explaining the
supersession and pointing at the live ENGINES.md.
- docs/GBRAIN_V0.md → `docs/SQLITE_ENGINE.md` (2 references; same supersession).
Added a historical-doc banner at the top + rewrote both references to point at
the current ENGINES.md.
### 4. Stale API key recommendations
INSTALL_FOR_AGENTS.md Step 2 only mentioned OpenAI + Anthropic. As of v0.36.2.0
ZeroEntropy is the default embedding + reranker stack (README opens with this);
the agent install guide didn't reflect it. Added `ZEROENTROPY_API_KEY` as the
default, kept OpenAI/Voyage as documented fallbacks, noted that keys can live in
`~/.gbrain/config.json` (file plane) or env.
### 5. Stale upgrade workflow
INSTALL_FOR_AGENTS.md 'Upgrade' section assumed the clone+bun-install model
(`cd ~/gbrain && git pull && bun install && gbrain init && gbrain post-upgrade`)
and didn't mention `gbrain upgrade` (the single-command path that exists in the
CLI today: binary self-update + schema migrations + post-upgrade prompts in one).
Split into two paths — `gbrain upgrade` for the bun-install-g case (now the
default per Step 1), clone-path for the fallback case.
Also fixed AGENTS.md 'Migrate' bullet (was `gbrain apply-migrations` only;
now leads with `gbrain upgrade` and keeps apply-migrations as the manual
schema-only path).
### 6. Stale cron-workflow
INSTALL_FOR_AGENTS.md Step 7 referenced cron docs but didn't mention
`gbrain autopilot --install` (the built-in self-maintaining daemon that
exists in the CLI today) or `gbrain sync --watch` (continuous loop). Added
both as alternatives to platform-cron glue.
### 7. ZeroEntropy version typo
docs/INSTALL.md said 'the v0.36.0.0 ZE switch' — ZE landed in v0.36.2.0
(v0.36.0.0 was the skillpack-scaffold retirement). Fixed.
## What I did NOT change
- CHANGELOG.md, CLAUDE.md, TODOS.md prose mentions of historical commands like
`gbrain skillpack install` are correct as history — they're documenting what
was true in past releases. Only forward-looking docs got updated.
- The 'broken link' false-positive matches in CHANGELOG / CLAUDE / TODOS are
inside code-fence examples or regex patterns (`[Name](people/slug)`,
`[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])`, `[--json](interrupted)`); they're
illustrative syntax, not real links. Leaving alone.
- llms.txt / llms-full.txt regenerated via `bun run build:llms` so the
agent-fetch documentation map matches the new content.
## Verification
- `bun run src/cli.ts --help` cross-checked against every command/flag the
install docs reference: init, doctor, apply-migrations, upgrade, post-upgrade,
skillpack scaffold/reference/migrate-fence, embed --stale, sync --watch,
autopilot --install, dream, integrations list, extract links/timeline,
graph-query, query, search modes — all real, all current.
- `bun run src/cli.ts skillpack install` confirmed to error out with the
retirement hint pointing at scaffold (proves the README guidance was actively
misleading users into a dead-end).
- Re-ran the broken-internal-link scanner across all root .md + docs/**/*.md;
zero real broken links remain (5 residual matches are illustrative syntax
inside prose, not actionable links).
garrytan
added a commit
that referenced
this pull request
May 19, 2026
Master added PR #1193 (v0.36.4.0 — brain-health-100, autonomous remediation via doctor --remediate + Minions) and PR #1201 (docs drift audit) since the last merge. My branch stays at v0.36.5.0; CHANGELOG sequence is now 0.36.5.0 (mine) → 0.36.4.0 (master) → 0.36.3.0 → 0.36.2.0. Resolved: VERSION + package.json (kept 0.36.5.0); CHANGELOG (mine on top, strip markers, all entries preserved). All source files auto-merged cleanly. verify green, llms regenerated. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
brandonlipman
added a commit
to brandonlipman/gbrain
that referenced
this pull request
May 29, 2026
* upstream/master: v0.37.0.0 feat(skillpack): registry cathedral — third-party publish + install + 10/10 quality bar (garrytan#1208) v0.36.6.0 feat: cross-modal search wave (text↔image + unified column + LLM intent) (garrytan#1165) v0.36.5.0 feat: secure DATABASE_URL access for shell jobs (inherit: ["database_url"]) (garrytan#1192) v0.36.4.0 feat: brain-health-100 — autonomous remediation via doctor --remediate + Minions (garrytan#1193) fix(docs): comprehensive drift audit — contradictions, broken links, stale refs (garrytan#1201) v0.36.3.0 feat: dynamic embedding column selection for search (garrytan#1164) v0.36.2.0 feat: ZeroEntropy as default + zero-based README rewrite (garrytan#1136) v0.36.1.1 fix-wave: community PR triage + 28 atomic fixes (garrytan#1182) v0.36.1.0 Hindsight calibration wave: brain learns how you tend to be wrong (garrytan#1139) v0.36.0.0 feat(skillpack): scaffold + reference + harvest (retire managed-block install) (garrytan#1130) v0.35.8.0 feat(cycle): phantom-page redirect inside extract_facts (garrytan#1138) v0.35.7.0 feat: temporal trajectory + founder scorecard (Phases 2-4) (garrytan#1131) v0.35.6.0 feat(search): floor-ratio gate for metadata boost stages (closes garrytan#1091) (garrytan#1129) v0.35.5.1 fix(doctor): stop counting clean supervisor exits as crashes (garrytan#1108) v0.35.5.0 fix wave: bootstrap + orphans + think MCP + worktree + walker (garrytan#1111) v0.35.4.0 fix(doctor,entities): supervisor crash classification + bare-name resolver + 58x perf + stub guard observability (garrytan#1085) v0.35.3.1 feat(eval): temporal-aware contradiction probe + verdict enum (garrytan#1052) v0.35.3.0 fix wave: extract_facts items + git --no-recurse-submodules placement (garrytan#1053) # Conflicts: # src/core/postgres-engine.ts # test/schema-bootstrap-coverage.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A community member reported the docs "have quite a bit of drift and some broken links" and contradictions like "says don't use bun but also to use bun." This PR is a top-to-bottom audit + fix across every doc file at the repo root and under
docs/. Where docs disagreed with each other, the code was the tie-breaker.TL;DR
Reconciled the "don't use bun / use bun" contradiction. The README +
docs/INSTALL.mdrecommendedbun install -g github:garrytan/gbrainas primary;INSTALL_FOR_AGENTS.mdsaid "Do NOT use" that command and requiredgit clone + bun linkinstead. The "do not use" warning was correct in 2024 when the postinstall silently swallowed migration errors. It's stale now: the postinstall prints a loud recovery hint for issue #218,gbrain doctorcatchesschema_version: 0and routes users togbrain apply-migrations --yes. Aligned all four files:bun install -gis the primary path, clone + bun link is the documented fallback for the postinstall-hook edge case.Killed
gbrain skillpack installfrom the user-facing install docs. The command was retired in v0.36.0.0 and the CLI now errors out with a hint pointing atscaffold. README.md anddocs/INSTALL.mdwere still recommending it as the primary install step — actively misleading users into a dead-end. Replaced withgbrain skillpack scaffold --alleverywhere, with the v0.36.0.0 retirement +migrate-fenceescape hatch explained inline for upgraders.Fixed broken internal links.
README.md→docs/integrations/voice.md(file doesn't exist; voice lives atrecipes/twilio-voice-brain.md).CONTRIBUTING.md+docs/GBRAIN_V0.md→docs/SQLITE_ENGINE.md(file doesn't exist; superseded by PGLite perdocs/ENGINES.md).Categories of fix
1. Stale CLI commands (
skillpack install→scaffold)gbrain skillpack installwas retired in v0.36.0.0. The CLI errors out:But the install docs still pointed users at it. Fixed in
README.mdanddocs/INSTALL.md.2. The bun install -g vs bun link contradiction
Resolved across
README.md,docs/INSTALL.md,AGENTS.md,INSTALL_FOR_AGENTS.md.bun install -gis the canonical path;git clone + bun linkis the documented fallback for the #218 postinstall-hook case.3. Broken internal links
README.md→docs/integrations/voice.md(missing; pointed to nonexistent file). Fixed →recipes/twilio-voice-brain.md.CONTRIBUTING.md→docs/SQLITE_ENGINE.md(missing; superseded). Fixed → pointer todocs/ENGINES.mdwith supersession context.docs/GBRAIN_V0.md→docs/SQLITE_ENGINE.md(2 refs). Added a "historical doc" banner at the top + updated both refs.4. Stale API key recommendations
INSTALL_FOR_AGENTS.mdStep 2 only mentioned OpenAI + Anthropic, but v0.36.2.0 made ZeroEntropy the default embedding + reranker stack (the README opens with this). AddedZEROENTROPY_API_KEYas the default, kept OpenAI/Voyage as fallbacks.5. Stale upgrade workflow
INSTALL_FOR_AGENTS.md"Upgrade" section assumed the clone-based model and didn't mentiongbrain upgrade(the single-command path that exists today). Split into two paths matching the new install hierarchy. Also fixedAGENTS.md"Migrate" bullet to lead withgbrain upgradeand keepapply-migrationsas the manual-schema-only fallback.6. Stale cron workflow
INSTALL_FOR_AGENTS.mdStep 7 didn't mentiongbrain autopilot --install(built-in self-maintaining daemon) orgbrain sync --watch(continuous loop), both of which exist in the CLI today. Added as alternatives to platform-cron glue.7. Version typo
docs/INSTALL.mdsaid "the v0.36.0.0 ZE switch" — ZeroEntropy actually landed in v0.36.2.0. Fixed.What I deliberately did NOT change
CHANGELOG.md,CLAUDE.md,TODOS.mdprose mentions of historical commands are correct as history — they document what was true in past releases.[Name](people/slug),[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9]),[--json](interrupted)). These are illustrative syntax, not real links.Verification
bun run src/cli.ts --helpon0.36.3.0. All real, all current.bun run src/cli.ts skillpack installerrors out with the retirement hint — proving the README guidance was actively misleading users..md+docs/**/*.md; zero real broken links remain. The 5 residual regex matches are illustrative syntax in prose, not actionable links.bun run build:llmsregeneratedllms.txt/llms-full.txtso the agent-fetch documentation map matches the new content.Files changed
README.mddocs/INSTALL.mdAGENTS.mdINSTALL_FOR_AGENTS.mdCONTRIBUTING.mddocs/GBRAIN_V0.md(added historical-doc banner)llms-full.txt(auto-regenerated)