## Parent
#1
## Type
AFK
## What to build
Add a central Mode Selection Guide that explains when to use the major current GBrain operational surfaces without inventing unsupported command names. It should cover retrieval, synthesis, maintenance, and the new push-based context surfaces from the current changelog baseline.
## Acceptance criteria
- [x] Explain when to use gbrain search, gbrain think, and gbrain dream/autopilot.
- [x] Include retrieval reflex, volunteer_context, gbrain volunteer-context, and gbrain watch as current push-context surfaces.
- [x] Include cost/quality/safety implications where relevant, especially for search modes and agent systems.
- [x] Avoid ambiguous non-canonical names such as chat unless the repo documents a supported public surface by that name.
- [x] Link the guide from human install, agent install, and production operational paths.
## Blocked by
- #2
- #5
- #7
## Implementation status
Implemented in PR #2212.
Evidence:
- `docs/guides/mode-selection.md` covers `gbrain search`, `gbrain think`, `gbrain dream`/autopilot, retrieval reflex, `volunteer_context`, `gbrain volunteer-context`, and `gbrain watch`.
- It covers cost/quality/safety implications and avoids introducing unsupported `chat` terminology.
- It is linked from `README.md`, `docs/INSTALL.md`, and `INSTALL_FOR_AGENTS.md`.
Tracker note: this issue is closed as complete in the fork because the work is present in garrytan/gbrain#2212. Upstream merge/review remains tracked by https://github.com/garrytan/gbrain/pull/2212.
Implemented in commit 9d363a11 (`docs: add mode selection guide`).
What changed:
- Added `docs/guides/mode-selection.md` as the central guide for retrieval, synthesis, maintenance, and push-context choices.
- Covered `gbrain search`, `gbrain think`, `gbrain dream` / autopilot, retrieval reflex, MCP `volunteer_context`, `gbrain volunteer-context`, and `gbrain watch`.
- Documented search-mode cost/quality/safety implications and the `gbrain search "<query>"` vs `gbrain search modes|stats|tune|diagnose` distinction from the CLI dispatch path.
- Linked the guide from `README.md`, `docs/INSTALL.md`, the production/shared-brain checklist, and `INSTALL_FOR_AGENTS.md`.
- Added the guide to `scripts/llms-config.ts` and regenerated `llms.txt` / `llms-full.txt`.
- Updated the local consolidation ledger for #9.
Static proof run:
- Used CodeGraph and source/docs inspection for the command surfaces.
- `bun run build:llms` passed.
- `git diff --check` passed.
- `git diff --cached --check` passed.
- Acceptance `rg` checks confirmed the guide and links cover the required names/paths.
- Secret scan only matched existing placeholders such as `gbrain_xxx` and `sk-ant-...`, not real secrets.
Not test-proven: `bun test test/build-llms.test.ts` currently fails in this checkout because `src/core/ai/gateway.ts` cannot resolve package `ai`. I did not install dependencies as part of this docs-only slice.
Marked complete for the docs-only branch in garrytan/gbrain#2212. Acceptance criteria are checked in the issue body with evidence and proof limits. Upstream review/merge remains tracked at https://github.com/garrytan/gbrain/pull/2212.