docs: fix documentation inaccuracies flagged by Codex in PR #115 - #117
Conversation
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>
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>
![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: 954cc5a8af
ℹ️ 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".
| ### Host-Runner Mode (No Multi-Agent Routing) | ||
|
|
||
| When `RB_HOST_RUNNER` is set (`codex` or `generic`), Ask uses `_ask_with_host_runner` exclusively: | ||
| - **Single local CLI invocation** with project context and question |
There was a problem hiding this comment.
When RB_ASK_RETRIEVAL_FIRST=2 and retrieval finds evidence, _ask_with_host_runner returns that evidence before calling run_host_runner, so this path performs zero local CLI invocations and does not return an answer from the host CLI. Qualify the single-invocation claim to avoid misdescribing this supported configuration.
Useful? React with 👍 / 👎.
| 1. **`_ask_with_structured_facts`** (when `.repobrain/map.md` and `agents/*.md` exist): | ||
| - First tries `_ask_with_agent_md` — Routes via map.md to agent.md knowledge | ||
| - Falls back to `_ask_with_legacy_facts` within the same call — Uses legacy `*.facts.json` if available |
There was a problem hiding this comment.
For an older knowledge base containing module_registry.json, status.json, and modules/*.facts.json but no map.md/agents directory, _structured_artifacts_available still selects _ask_with_structured_facts, which proceeds directly to _ask_with_legacy_facts. Saying the structured path runs only when map.md and agents/*.md exist incorrectly implies these supported legacy installations skip directly to the swarm; describe both entry conditions.
Useful? React with 👍 / 👎.
| # Check refresh status | ||
| rb report |
There was a problem hiding this comment.
rb report with a real status check
In this debugging example, rb report cannot check refresh status: rb report --help describes it as “Log a report to .repobrain/memory/reports.md” and marks the {message} argument required, so the command shown exits with a missing-argument error. The same newly added command appears in the Spanish and Chinese examples; replace all three with an actual knowledge-health/status inspection command.
Useful? React with 👍 / 👎.
| The core phase is complete. Below are **future extension ideas** (not currently in-progress) that would build on this foundation: | ||
|
|
||
| ### Future Extension: Sandbox Environment 🔒 |
There was a problem hiding this comment.
The blanket statement that the following sections are future ideas “not currently in-progress” now includes the Sandbox Environment, but this repository already ships get_sandbox(), a local implementation, an opt-in MicrosandboxSandbox, tests, and a dedicated docs/en/SANDBOX.md usage guide. Distinguish the implemented sandbox support from genuinely future backends such as E2B instead of telling readers that the entire capability is only an extension idea.
Useful? React with 👍 / 👎.
| # Ask with verbose output (streamed progress) | ||
| rb-ask "Where is the database connection?" |
There was a problem hiding this comment.
With the default STREAM_ENABLED=false, the plain rb-ask command shown here uses Runner.run rather than Runner.run_streamed, so it does not provide the promised streamed progress. Either set STREAM_ENABLED=true in the example or describe the always-emitted stage messages without calling them streamed output; the same misleading comment was added to all three translations.
Useful? React with 👍 / 👎.
|
|
||
| When no API key is configured (`RB_HOST_RUNNER` set to `codex` or `generic`), Refresh uses a single-turn, tool-free Convention Agent (`build_single_turn_convention_agent()`) that collapses the three-stage chain into one generation. | ||
|
|
||
| **Important:** Host-runner mode for refresh is single-turn only. It does not use the full three-agent handoff chain. |
There was a problem hiding this comment.
A full host-runner rb-refresh is not itself single-turn: after the one-call convention agent, the pipeline invokes a separate host completion for every module group and another for the map agent. Only each individual host-backed agent call is single-turn and tool-free, so phrase this qualification per agent or per stage to avoid implying that refresh performs one model turn or one CLI invocation.
Useful? React with 👍 / 👎.
2 participants
Summary
Fixes all seven documentation inaccuracies that Codex flagged during review of PR #115 (now on main). These are docs-only changes verified against current engine code.
Checklist of Fixes
✅ 1. Generic host runner requires RB_HOST_COMMAND
Issue:
RB_HOST_RUNNER=genericwithoutRB_HOST_COMMANDraises HostRunnerError (verified inengine/repobrain_engine/hub/host_runner.pyline 316-318). Docs presentedgenericas drop-in alternative tocodex.Fixed in:
docs/en/SWARM_PROTOCOL.md— Configuration sectiondocs/zh/SWARM_PROTOCOL.md— Configuration sectiondocs/es/SWARM_PROTOCOL.md— Configuration sectionChange: Added concrete
trae-cliexample withRB_HOST_COMMANDtemplate andRB_HOST_OUTPUT_MODE=fileas documented in README.✅ 2. Ask fallback order incorrect
Issue: Docs described structured facts, agent.md, and legacy swarm as three sequential peer tiers. Actual code (verified in
ask_pipeline.py):RB_HOST_RUNNERset:_ask_with_host_runneronly (no Router/ModuleAgent/GitAgent)_ask_with_structured_factstries_ask_with_agent_mdthen_ask_with_legacy_factsinternally, then falls back to_ask_with_legacy_swarmif None returnedFixed in:
docs/en/SWARM_PROTOCOL.md— Fallback Strategy sectiondocs/zh/SWARM_PROTOCOL.md— Fallback Strategy sectiondocs/es/SWARM_PROTOCOL.md— Fallback Strategy sectionChange: Rewrote fallback section to match actual code flow with two-tier structure: host-runner bypass + API-based nested fallback.
✅ 3. RB_LOG_LEVEL does not exist
Issue: Neither engine nor CLI reads
RB_LOG_LEVEL. Grepped entire codebase — no such env var exists.Fixed in:
docs/en/SWARM_PROTOCOL.md— Example 3: Debugging Usagedocs/zh/SWARM_PROTOCOL.md— Example 3: Debugging Usagedocs/es/SWARM_PROTOCOL.md— Example 3: Debugging UsageChange: Removed fake
RB_LOG_LEVEL=DEBUGexamples. Replaced with real debugging approach: checking refresh status withrb reportand using built-in streamed progress.✅ 4. .repobrain/config.json ignore patterns do not exist
Issue: No reader/schema for that file exists. Scan exclusions are hard-coded in
hub/scanner.pyviaSKIP_DIRSconstant.Fixed in:
docs/en/SWARM_PROTOCOL.md— Performance Tips sectiondocs/zh/SWARM_PROTOCOL.md— Performance Tips sectiondocs/es/SWARM_PROTOCOL.md— Performance Tips sectionChange: Removed advice to create
.repobrain/config.jsonfor exclusions. Mentioned that skip dirs are built-in and referenced the constant location.✅ 5. Phase 9 status conflict
Issue: Top table says Phase 9 complete, but later "Phase 9: Enterprise Core (In Progress)" section lists orchestrated flows, distributed fleet, etc. as current work instead of future ideas.
Fixed in:
docs/en/ROADMAP.md— Phase 9 section header and subsection labelsdocs/zh/ROADMAP.md— Status table (changed "进行中" to "完成")Change:
Note: Spanish
docs/es/ROADMAP.mdwas already correct (table shows "Completa") — no changes needed.✅ 6. Qualify Ask Swarm in host-runner mode
Issue: When
RB_HOST_RUNNERis set, ask is a single local CLI call (_ask_with_host_runnerinask_pipeline.pyline 212). It does not build Router/ModuleAgents/GitAgent or do handoffs.Fixed in:
docs/en/SWARM_PROTOCOL.md— New "Host-Runner Mode (No Multi-Agent Routing)" subsectiondocs/zh/SWARM_PROTOCOL.md— New "Host-Runner Mode (No Multi-Agent Routing)" subsectiondocs/es/SWARM_PROTOCOL.md— New "Host-Runner Mode (No Multi-Agent Routing)" subsectionChange: Added explicit subsection documenting that host-runner mode uses single-turn local answer, not full Router-Worker collaboration.
✅ 7. ModuleAgents do not load structured facts.json
Issue:
build_ask_swarm()→_read_module_knowledge()readsagents/*.md, grouped markdown, or legacymodules/*.md(verified in code). Structured*.facts.jsonclaims are consumed by structured/legacy-facts ask path, NOT injected into ModuleAgents.Fixed in:
docs/en/SWARM_PROTOCOL.md— ModuleAgent descriptiondocs/zh/SWARM_PROTOCOL.md— ModuleAgent descriptiondocs/es/SWARM_PROTOCOL.md— ModuleAgent descriptionChange: Corrected description to say ModuleAgents read
agents/*.mdknowledge, not structured facts.json. Clarified that structured facts are used by separate ask path.Verification
All fixes verified with grep searches:
Files Changed
docs/en/ROADMAP.md— 1 issue fixeddocs/zh/ROADMAP.md— 1 issue fixed (table status consistency)docs/en/SWARM_PROTOCOL.md— 6 issues fixeddocs/zh/SWARM_PROTOCOL.md— 6 issues fixeddocs/es/SWARM_PROTOCOL.md— 6 issues fixed