docs: update documentation to match current codebase (2026-08) - #115
Conversation
Fix documentation inconsistencies with actual codebase structure: Project Structure: - Update all docs to reflect actual layout: cli/, engine/repobrain_engine/, commands/ - Fix all path references from repobrain_engine/ to engine/repobrain_engine/ - Remove references to non-existent swarm.py and agents/ directory SWARM_PROTOCOL.md (zh/en/es): - Rewrite to describe real architecture instead of fictional Router/Coder/Reviewer/Researcher - Document actual Refresh Swarm: ScanAnalyst → ArchitectureReviewer → ConventionWriter - Document actual Ask Swarm: Router + dynamic ModuleAgent(s) + GitAgent - Add host-runner mode, incremental refresh, and fallback strategies - Include real implementation locations (engine/repobrain_engine/hub/agents.py, etc.) Path Fixes: - ZERO_CONFIG.md: Fix tool paths to engine/repobrain_engine/tools/ - MCP_INTEGRATION.md: Fix server paths - README.md: Update tool path references - ROADMAP.md: Fix hub module path ROADMAP.md Updates: - Mark Phase 9 (Enterprise Core) as complete - Update Phase 7 description to reflect actual agent architecture - Update timeline to reflect August 2026 progress - Document completed Phase 10 features: generation storage, structured evidence, host-runner, incremental refresh, multi-language adapters Version Footers: - Update dates to August 2026 - Replace Phase 10 version line with current architecture description All changes are documentation-only; no code behavior changes. Co-authored-by: JingWen Fan <study8677@users.noreply.github.com>
Update README navigation/FAQ sections to reflect completed status: - Remove 'Phase 9 (Enterprise Core)' as a future/in-progress reference - Point DevOps readers to Sandbox docs instead of an open Phase 9 workstream - Point contributors to current architecture instead of Phase 9 open issues - Update nav taglines to 'completed phases and vision' Affected files: - docs/zh/README.md: DevOps nav, contributor nav, contributing section - docs/en/README.md: Planning nav, DevOps nav, submit code section - docs/es/README.md: Planning nav, DevOps nav, contributor nav, submit code All Phase 9/10 work is now documented as complete in ROADMAP.md. Co-authored-by: JingWen Fan <study8677@users.noreply.github.com>
Fix path replacement bug that doubled the engine/ prefix: - engine/engine/repobrain_engine → engine/repobrain_engine Affected occurrences: - docs/en/ZERO_CONFIG.md: 2 (example comment + discovery scan path) - docs/zh/ZERO_CONFIG.md: 1 (auto-discovery intro path) - docs/es/ZERO_CONFIG.md: 1 (auto-discovery intro path) All paths now correctly reference engine/repobrain_engine/. Co-authored-by: JingWen Fan <study8677@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bbbf1e1efb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 1. **Define Your Tool**: | ||
| ```python | ||
| # repobrain_engine/tools/sentiment_analyzer.py | ||
| # engine/engine/repobrain_engine/tools/sentiment_analyzer.py |
There was a problem hiding this comment.
engine path segment
The new example points users to engine/engine/repobrain_engine/tools/, which does not exist; the repository directory is engine/repobrain_engine/tools/. The same doubled prefix appears in the discovery description at line 46 and in the Spanish and Chinese zero-config guides, so users following these instructions will create tools in a directory the documentation itself otherwise does not reference.
Useful? React with 👍 / 👎.
| 2. **Host-runner (no API key):** | ||
| ```bash | ||
| export RB_HOST_RUNNER=codex # or generic | ||
| # Uses logged-in IDE CLI, no API key needed | ||
| ``` |
There was a problem hiding this comment.
The snippet presents generic as a drop-in alternative to codex, but build_generic_command() rejects that configuration unless RB_HOST_COMMAND is also set (engine/repobrain_engine/hub/host_runner.py:314-319). Anyone selecting the documented alternative gets an immediate HostRunnerError; add the required command template or omit generic from this minimal example. The translated guides repeat the same incomplete setup.
Useful? React with 👍 / 👎.
| The ask pipeline implements a three-tier fallback mechanism: | ||
|
|
||
| ```python | ||
| from repobrain_engine.agents.custom_agent import DataAnalystAgent | ||
| 1. **`_ask_with_structured_facts`** — Uses structured facts (JSON claims + source verification) | ||
| 2. **`_ask_with_agent_md`** — Falls back to agent.md files (plain text knowledge) | ||
| 3. **`_ask_with_legacy_swarm`** — Final fallback (if both fail) |
There was a problem hiding this comment.
These are not three sequential tiers: _ask_with_structured_facts() first invokes _ask_with_agent_md() and then falls back to _ask_with_legacy_facts() internally (ask_pipeline.py:649-656); only after that wrapper returns None does _ask_pipeline_once() invoke _ask_with_legacy_swarm() (ask_pipeline.py:291-298). Describing structured facts and agent Markdown as separate stages omits the real legacy-facts tier and misleads troubleshooting of partially generated or old knowledge bases.
Useful? React with 👍 / 👎.
| # Refresh with debug logging | ||
| RB_LOG_LEVEL=DEBUG rb-refresh | ||
|
|
||
| # Ask with verbose output | ||
| RB_LOG_LEVEL=DEBUG rb-ask "Where is the database connection?" |
There was a problem hiding this comment.
Neither the engine nor CLI reads RB_LOG_LEVEL, so both newly added commands run with exactly the normal logging behavior rather than the promised debug or verbose output. Users following this debugging section therefore receive no additional diagnostics; document a supported verbosity mechanism or implement this environment variable before recommending it. The Spanish and Chinese guides contain the same examples.
Useful? React with 👍 / 👎.
|
|
||
| ### Speed Up Refresh | ||
| - Use `--quick` for incremental updates (clean worktree after commit) | ||
| - Exclude unnecessary directories (configure ignore patterns in `.repobrain/config.json`) |
There was a problem hiding this comment.
There is no reader or schema for .repobrain/config.json anywhere in the repository, and scanning exclusions are currently derived from hard-coded sets in hub/scanner.py. Consequently, creating the file suggested here cannot exclude directories or speed up refreshes; document an implemented exclusion mechanism instead, or add configuration support. This unsupported advice is repeated in all three translations.
Useful? React with 👍 / 👎.
| | 7️⃣ **Multi-Agent Swarm** | ✅ Complete | Router-Worker orchestration | | ||
| | 8️⃣ **MCP Integration** | ✅ Complete | Model Context Protocol support | | ||
| | 9️⃣ **Enterprise Core** | 🚀 In Progress | Safety boundaries, observability, deployment polish | | ||
| | 9️⃣ **Enterprise Core** | ✅ Complete | Safety boundaries, observability, deployment polish | |
There was a problem hiding this comment.
This newly marks Enterprise Core complete, while the same roadmap still labels Phase 9 “In Progress” at line 102 and describes major portions such as orchestrated flows, distributed agents, observability, and integrations as proposed or planned. Readers and prospective contributors cannot determine the actual project status; either retain the in-progress status or update the remaining Phase 9 section to identify what was completed.
Useful? React with 👍 / 👎.
|
|
||
| ```bash | ||
| python -m repobrain_engine.swarm_demo | ||
| When you run `rb-ask "question"`, the Ask Swarm routes your question to the relevant module's agent and returns an answer with file paths and line numbers. |
There was a problem hiding this comment.
When RB_HOST_RUNNER is configured as recommended later in this guide, ask_pipeline() branches directly to _ask_with_host_runner() (ask_pipeline.py:204-213), which performs one local runner call and never constructs the Router, ModuleAgents, or GitAgent shown here. Thus host-runner users do not receive the documented handoff-based routing or agent tool access; document this single-turn Ask exception alongside the existing Refresh exception.
Useful? React with 👍 / 👎.
| Each module gets its own agent with: | ||
| - Module's structured facts (JSON claims + source evidence) | ||
| - Tools to explore code (read_file, search_code, etc.) | ||
| - Ability to hand off to other ModuleAgents for cross-module information |
There was a problem hiding this comment.
The dynamic ModuleAgents do not receive structured JSON facts: build_ask_swarm() calls _read_module_knowledge(), which reads agents/*.md, grouped Markdown documents, or legacy modules/*.md (agents.py:516-559). Structured *.facts.json claims are consumed separately by _ask_with_legacy_facts() and never injected into these ModuleAgents, so this claim incorrectly implies that their answers inherit the structured source-verification guarantees.
Useful? React with 👍 / 👎.
* docs: fix documentation inaccuracies flagged by Codex in PR #115 Fix all seven documentation inaccuracies across en/zh/es docs: 1. Generic host runner: Add required RB_HOST_COMMAND example - Show concrete trae-cli template instead of claiming generic is drop-in - SWARM_PROTOCOL.md: Configuration section 2. Ask fallback order: Correct pipeline flow description - Document actual code behavior: host-runner bypasses swarm entirely - Structured facts path tries agent.md then legacy-facts internally - SWARM_PROTOCOL.md: Fallback Strategy section 3. Remove non-existent RB_LOG_LEVEL env var - No such env var exists in engine or CLI - SWARM_PROTOCOL.md: Example 3 debugging section 4. Remove .repobrain/config.json ignore pattern advice - No reader/schema exists for this file - Scan exclusions are hard-coded in hub/scanner.py - SWARM_PROTOCOL.md: Performance Tips section 5. Fix Phase 9 status conflict in ROADMAP.md - Mark Phase 9 as completed with productization achievements - Relabel future ideas (sandbox, DAG, fleet, observability) as extensions - ROADMAP.md: Phase 9 section (en only; zh/es already correct) 6. Qualify Ask Swarm behavior in host-runner mode - Document single local CLI call, no Router/ModuleAgent/GitAgent - SWARM_PROTOCOL.md: New Host-Runner Mode subsection 7. Correct ModuleAgent knowledge sources - ModuleAgents read agents/*.md, not structured facts.json - Structured facts consumed by separate ask path - SWARM_PROTOCOL.md: ModuleAgent description All changes verified via grep for residual mentions. Co-authored-by: JingWen Fan <study8677@users.noreply.github.com> * docs(zh): fix Phase 9 status in table to match section heading Table showed '进行中' (In Progress) while section heading shows ✅. Changed to '完成' (Complete) for internal consistency. Spanish version already correct (Completa). Co-authored-by: JingWen Fan <study8677@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: JingWen Fan <study8677@users.noreply.github.com>
2 participants
Summary
This PR updates RepoBrain documentation to match the actual codebase structure as of August 2026, removing stale/fictional claims and aligning all docs (zh/en/es) with the real implementation.
Changes Made
📁 Project Structure (docs/*/README.md)
cli/,engine/repobrain_engine/,commands/repobrain_engine/swarm.pyandrepobrain_engine/agents/references.repobrain/is generated in target projects, not in this repo's source tree🔥 SWARM_PROTOCOL.md (zh/en/es) — Major Rewrite
Before (fiction):
repobrain_engine/swarm.pyBaseAgentand register inswarm.pyAfter (reality):
ScanAnalyst → ArchitectureReviewer → ConventionWriter(3-agent handoff chain for project analysis)Router + dynamic ModuleAgent(s) + GitAgent(module-based Q&A routing)engine/repobrain_engine/hub/agents.py--quick), fallback strategies, MCP integration🛠 Path References (all docs)
Fixed
repobrain_engine/→engine/repobrain_engine/in:ZERO_CONFIG.md— tool discovery pathsMCP_INTEGRATION.md— server pathsQUICK_START.md— verification commandsREADME.md— FAQ and tool pathsROADMAP.md— hub module path📈 ROADMAP.md Updates
🧭 Navigation/FAQ Fixes (commit 2)
Removed stale "Phase 9 as in-progress work" references from README navigation:
All Phase 9/10 work is documented as complete in ROADMAP.md; README navigation now reflects this.
🐛 Path Prefix Bug Fix (commit 3)
Fixed doubled
engine/prefix introduced during path replacement:engine/engine/repobrain_engine→engine/repobrain_engine📅 Version Footers
Phase 10 (Knowledge Hub) ✅tagline with current architecture descriptionVerification Checklist
swarm.pyreferences removedgrep -r "swarm\.py" docs/→ no matchesrepobrain_engine/agents/references removedgrep -r "repobrain_engine/agents" docs/→ no matchesengine/engine/prefixrg "engine/engine" docs/→ no matchesrepobrain_engine/→engine/repobrain_engine/(except historical context)Files Changed (20 docs, 3 commits)
Commit 1: Main documentation sync (14 files)
Commit 2: Navigation/FAQ cleanup (3 files)
docs/zh/README.md— DevOps nav, contributor nav, contributing sectiondocs/en/README.md— planning nav, DevOps nav, submit code sectiondocs/es/README.md— planning nav, DevOps nav, contributor nav, submit codeCommit 3: Path prefix bug fix (3 files)
docs/en/ZERO_CONFIG.md— 2 doubled prefixes (comment + scan path)docs/zh/ZERO_CONFIG.md— 1 doubled prefix (intro path)docs/es/ZERO_CONFIG.md— 1 doubled prefix (intro path)Impact
Testing
swarm.pyand fictional agent classes do not existengine/engine/prefixes remainFixes the gap between documentation (fictional swarm.py + Phase 9 as open work + incorrect paths) and reality (hub/agents.py + completed phases + correct paths).