Skip to content

fix(docs): comprehensive drift audit — contradictions, broken links, stale refs#1201

Merged
garrytan merged 1 commit into
garrytan:masterfrom
garrytan-agents:fix/docs-drift-audit
May 19, 2026
Merged

fix(docs): comprehensive drift audit — contradictions, broken links, stale refs#1201
garrytan merged 1 commit into
garrytan:masterfrom
garrytan-agents:fix/docs-drift-audit

Conversation

@garrytan-agents

Copy link
Copy Markdown
Contributor

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.md recommended bun install -g github:garrytan/gbrain as primary; INSTALL_FOR_AGENTS.md said "Do NOT use" that command and required git clone + bun link instead. 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 doctor catches schema_version: 0 and routes users to gbrain apply-migrations --yes. Aligned all four files: bun install -g is the primary path, clone + bun link is the documented fallback for the postinstall-hook edge case.

Killed gbrain skillpack install from the user-facing install docs. The command was retired in v0.36.0.0 and the CLI now errors out with a hint pointing at scaffold. README.md and docs/INSTALL.md were still recommending it as the primary install step — actively misleading users into a dead-end. Replaced with gbrain skillpack scaffold --all everywhere, with the v0.36.0.0 retirement + migrate-fence escape hatch explained inline for upgraders.

Fixed broken internal links. README.mddocs/integrations/voice.md (file doesn't exist; voice lives at recipes/twilio-voice-brain.md). CONTRIBUTING.md + docs/GBRAIN_V0.mddocs/SQLITE_ENGINE.md (file doesn't exist; superseded by PGLite per docs/ENGINES.md).

Categories of fix

1. Stale CLI commands (skillpack installscaffold)

gbrain skillpack install was retired in v0.36.0.0. The CLI errors out:

$ gbrain skillpack install
Error: 'gbrain skillpack install' was removed in v0.33.
Use 'gbrain skillpack scaffold <name>' instead.

But the install docs still pointed users at it. Fixed in README.md and docs/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 -g is the canonical path; git clone + bun link is the documented fallback for the #218 postinstall-hook case.

3. Broken internal links

  • README.mddocs/integrations/voice.md (missing; pointed to nonexistent file). Fixed → recipes/twilio-voice-brain.md.
  • CONTRIBUTING.mddocs/SQLITE_ENGINE.md (missing; superseded). Fixed → pointer to docs/ENGINES.md with supersession context.
  • docs/GBRAIN_V0.mddocs/SQLITE_ENGINE.md (2 refs). Added a "historical doc" banner at the top + updated both refs.

4. Stale API key recommendations

INSTALL_FOR_AGENTS.md Step 2 only mentioned OpenAI + Anthropic, but v0.36.2.0 made ZeroEntropy the default embedding + reranker stack (the README opens with this). Added ZEROENTROPY_API_KEY as 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 mention gbrain upgrade (the single-command path that exists today). Split into two paths matching the new install hierarchy. Also fixed AGENTS.md "Migrate" bullet to lead with gbrain upgrade and keep apply-migrations as the manual-schema-only fallback.

6. Stale cron workflow

INSTALL_FOR_AGENTS.md Step 7 didn't mention gbrain autopilot --install (built-in self-maintaining daemon) or gbrain sync --watch (continuous loop), both of which exist in the CLI today. Added as alternatives to platform-cron glue.

7. Version typo

docs/INSTALL.md said "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.md prose mentions of historical commands are correct as history — they document what was true in past releases.
  • Broken-link false positives in CHANGELOG / CLAUDE / TODOS that live inside code-fence examples or regex patterns ([Name](people/slug), [a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9]), [--json](interrupted)). These are illustrative syntax, not real links.

Verification

  • Cross-checked every CLI command / flag the install docs reference against bun run src/cli.ts --help on 0.36.3.0. All real, all current.
  • Confirmed bun run src/cli.ts skillpack install errors out with the retirement hint — proving the README guidance was actively misleading users.
  • Re-ran the broken-internal-link scanner across all root .md + docs/**/*.md; zero real broken links remain. The 5 residual regex matches are illustrative syntax in prose, not actionable links.
  • bun run build:llms regenerated llms.txt / llms-full.txt so the agent-fetch documentation map matches the new content.

Files changed

  • README.md
  • docs/INSTALL.md
  • AGENTS.md
  • INSTALL_FOR_AGENTS.md
  • CONTRIBUTING.md
  • docs/GBRAIN_V0.md (added historical-doc banner)
  • llms-full.txt (auto-regenerated)

…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 garrytan merged commit 3aedffa into garrytan:master May 19, 2026
7 checks passed
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants