mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
3aedffadc0
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 #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 #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 #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).
Co-authored-by: garrytan-agents <agents@garrytan-agents.local>