docs: fix documentation inaccuracies flagged by Codex in PR #115

docs/en/ROADMAP.md

@@ -99,19 +99,18 @@ one IDE.
 
 **Implemented by:** [@devalexanderdaza](https://github.com/devalexanderdaza)
 
-## 🚀 Phase 9: Enterprise Core (In Progress)
+## 🚀 Phase 9: Enterprise Core (Completed with Future Extensions)
 
-**Goal**: Transform RepoBrain from a workspace into an autonomous **Agent Operating System**
+**Completed:** 2025
 
-The final vision is a production-grade system where enterprises can:
-- 🏗️ Build agents declaratively
-- 🚀 Deploy at global scale
-- 🔒 Execute code safely in sandboxes
-- 🧪 Orchestrate complex workflows
-- 📊 Monitor and observe at scale
-- 💾 Persist state and history
+**Productized Achievements:**
+- Safety boundaries and model selection controls
+- Observability through `rb report`, status tracking, and structured logs
+- Deployment polish: host-runner backend, incremental refresh, stable CLI
 
-### Phase 9A: Sandbox Environment 🔒
+The core phase is complete. Below are **future extension ideas** (not currently in-progress) that would build on this foundation:
+
+### Future Extension: Sandbox Environment 🔒
 **Objective**: Safe, isolated code execution for high-risk operations
 
 **Proposed Solutions:**
@@ -138,7 +137,7 @@ result = sandbox.execute(
 - ✅ Cost-efficient resource scaling
 - ✅ Compliance with security policies
 
-### Phase 9B: Orchestrated Flows 🔀
+### Future Extension: Orchestrated Flows 🔀
 **Objective**: Complex, structured task pipelines with DAG support
 
 **Proposed Architecture:**
@@ -185,7 +184,7 @@ steps:
 - 📈 Real-time monitoring and observability
 - 🎯 Composable, reusable workflows
 
-### Phase 9C: Distributed Agent Fleet 🌍
+### Future Extension: Distributed Agent Fleet 🌍
 **Objective**: Multi-agent coordination across regions
 
 **Planned Features:**
@@ -195,8 +194,8 @@ steps:
 - **Load Balancing**: Intelligent task distribution
 - **Failover**: Automatic agent replacement
 
-### Phase 9D: Observability & Monitoring 📊
-**Objective**: Production-grade observability
+### Future Extension: Observability & Monitoring 📊
+**Objective**: Production-grade observability beyond current status tracking
 
 **Planned Components:**
 - **Metrics**: Agent performance, tool usage, success rates
@@ -205,7 +204,7 @@ steps:
 - **Alerts**: Anomaly detection and alerting
 - **Dashboards**: Real-time agent health monitoring
 
-### Phase 9E: Enterprise Integrations 🔗
+### Future Extension: Enterprise Integrations 🔗
 **Objective**: Out-of-the-box enterprise connectors
 
 **Target Integrations:**

docs/en/SWARM_PROTOCOL.md

@@ -72,6 +72,8 @@ Keeps it under 300 words, outputs ONLY Markdown content.
 
 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.
+
 ## 💬 Ask Swarm: Dynamic Module Router
 
 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.
@@ -115,11 +117,11 @@ graph TD
 **Responsibility:** Deep knowledge of a specific module
 
 Each module gets its own agent with:
-- Module's structured facts (JSON claims + source evidence)
+- Module's agent knowledge (`agents/*.md` — grouped module summaries or legacy `modules/*.md`)
 - Tools to explore code (read_file, search_code, etc.)
 - Ability to hand off to other ModuleAgents for cross-module information
 
-ModuleAgents are created dynamically based on the project scan (one agent per detected module).
+ModuleAgents are created dynamically in the legacy swarm path (one agent per detected module). When structured artifacts exist, the ask pipeline uses `_ask_with_agent_md` instead, which routes directly via `map.md` without building the full swarm.
 
 #### 📜 GitAgent
 **Responsibility:** Git history and change analysis
@@ -136,13 +138,29 @@ Handles questions about:
 - **Pipeline:** `engine/repobrain_engine/hub/ask_pipeline.py`
 - **Knowledge:** Reads from generation directory pointed to by `.repobrain/current.json`
 
+### 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
+- Does **not** build Router/ModuleAgent/GitAgent or perform multi-agent handoffs
+- Returns direct answer from the local host CLI (no swarm orchestration)
+
+Users of the no-API-key path must understand that they get a single-turn local answer, not the full Router-Worker collaboration.
+
 ### Fallback Strategy
 
-The ask pipeline implements a three-tier fallback mechanism:
+The ask pipeline implements a context-sensitive fallback mechanism:
+
+**When `RB_HOST_RUNNER` is set** (codex or generic):
+- Uses `_ask_with_host_runner` exclusively
+- Does not build Router/ModuleAgent/GitAgent
+- Single local CLI invocation with no multi-agent routing
 
-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)
+**Standard API-based ask flow:**
+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
+2. **`_ask_with_legacy_swarm`** — Final fallback when structured artifacts return no answer
 
 This ensures ask functionality remains available even if knowledge base is partially generated or uses older formats.
 
@@ -157,7 +175,13 @@ This ensures ask functionality remains available even if knowledge base is parti
 
 2. **Host-runner (no API key):**
    ```bash
-   export RB_HOST_RUNNER=codex  # or generic
+   # Codex preset (built-in configuration)
+   export RB_HOST_RUNNER=codex
+
+   # Generic runner (requires RB_HOST_COMMAND template)
+   export RB_HOST_RUNNER=generic
+   export RB_HOST_COMMAND='trae-cli exec --cd {workspace} --sandbox read-only --skip-git-repo-check --ephemeral -o {output_file}'
+   export RB_HOST_OUTPUT_MODE=file
    # Uses logged-in IDE CLI, no API key needed
    ```
 
@@ -219,11 +243,14 @@ rb-ask "What changed in the auth module?"
 ### Example 3: Debugging Usage
 
 ```bash
-# Refresh with debug logging
-RB_LOG_LEVEL=DEBUG rb-refresh
+# Ask with verbose output (streamed progress)
+rb-ask "Where is the database connection?"
 
-# Ask with verbose output
-RB_LOG_LEVEL=DEBUG rb-ask "Where is the database connection?"
+# Check refresh status
+rb report
+
+# Force full refresh (non-incremental)
+rb-refresh  # without --quick
 ```
 
 ## 🐛 Troubleshooting
@@ -272,7 +299,7 @@ MCP server implementation: `engine/repobrain_engine/hub/mcp_server.py`
 
 ### Speed Up Refresh
 - Use `--quick` for incremental updates (clean worktree after commit)
-- Exclude unnecessary directories (configure ignore patterns in `.repobrain/config.json`)
+- Scan exclusions are built-in (venv, node_modules, .git, etc. — see `SKIP_DIRS` in `engine/repobrain_engine/hub/_constants.py`)
 - Use faster models (e.g., GPT-4o-mini or Claude 3.5 Haiku)
 
 ### Improve Answer Quality

docs/es/SWARM_PROTOCOL.md

@@ -72,6 +72,8 @@ Lo mantiene bajo 300 palabras, genera SOLO contenido Markdown.
 
 Cuando no hay API key configurada (`RB_HOST_RUNNER` establecido en `codex` o `generic`), Refresh usa un Agente de Convenciones de turno único sin herramientas (`build_single_turn_convention_agent()`) que colapsa la cadena de tres etapas en una sola generación.
 
+**Importante:** El modo host-runner para refresh es de turno único solamente. No usa la cadena completa de handoff de tres agentes.
+
 ## 💬 Ask Swarm: Enrutador de Módulos Dinámico
 
 Cuando ejecutas `rb-ask "pregunta"`, el Ask Swarm enruta tu pregunta al agente del módulo relevante y devuelve una respuesta con rutas de archivo y números de línea.
@@ -115,11 +117,11 @@ graph TD
 **Responsabilidad:** Conocimiento profundo de un módulo específico
 
 Cada módulo obtiene su propio agente con:
-- Facts estructurados del módulo (claims JSON + evidencia de fuente)
+- Conocimiento del agente del módulo (`agents/*.md` — resúmenes de módulos agrupados o `modules/*.md` heredado)
 - Herramientas para explorar código (read_file, search_code, etc.)
 - Capacidad de pasar el control a otros ModuleAgents para información entre módulos
 
-Los ModuleAgents se crean dinámicamente basados en el escaneo del proyecto (un agente por módulo detectado).
+Los ModuleAgents se crean dinámicamente en el camino de swarm heredado (un agente por módulo detectado). Cuando existen artefactos estructurados, el pipeline ask usa `_ask_with_agent_md` en su lugar, que enruta directamente vía `map.md` sin construir el swarm completo.
 
 #### 📜 GitAgent
 **Responsabilidad:** Historial de Git y análisis de cambios
@@ -136,13 +138,29 @@ Maneja preguntas sobre:
 - **Pipeline:** `engine/repobrain_engine/hub/ask_pipeline.py`
 - **Conocimiento:** Lee del directorio de generación apuntado por `.repobrain/current.json`
 
+### Modo Host-Runner (Sin Enrutamiento Multi-Agente)
+
+Cuando `RB_HOST_RUNNER` está configurado (`codex` o `generic`), Ask usa `_ask_with_host_runner` exclusivamente:
+- **Invocación CLI local única** con contexto del proyecto y pregunta
+- **No** construye Router/ModuleAgent/GitAgent ni realiza handoffs multi-agente
+- Devuelve respuesta directa del CLI local (sin orquestación de swarm)
+
+Los usuarios del modo sin API key deben entender que reciben una respuesta local de turno único, no la colaboración completa Router-Worker.
+
 ### Estrategia de Fallback
 
-El pipeline de ask implementa un mecanismo de fallback de tres niveles:
+El pipeline de ask implementa un mecanismo de fallback sensible al contexto:
+
+**Cuando `RB_HOST_RUNNER` está configurado** (codex o generic):
+- Usa `_ask_with_host_runner` exclusivamente
+- No construye Router/ModuleAgent/GitAgent
+- Invocación CLI local única sin enrutamiento multi-agente
 
-1. **`_ask_with_structured_facts`** — Usa facts estructurados (claims JSON + verificación de fuente)
-2. **`_ask_with_agent_md`** — Recurre a archivos agent.md (conocimiento en texto plano)
-3. **`_ask_with_legacy_swarm`** — Fallback final (si ambos fallan)
+**Flujo ask estándar basado en API:**
+1. **`_ask_with_structured_facts`** (cuando `.repobrain/map.md` y `agents/*.md` existen):
+   - Primero intenta `_ask_with_agent_md` — Enruta vía map.md al conocimiento de agent.md
+   - Recurre a `_ask_with_legacy_facts` dentro de la misma llamada — Usa `*.facts.json` heredado si está disponible
+2. **`_ask_with_legacy_swarm`** — Fallback final cuando los artefactos estructurados no devuelven respuesta
 
 Esto asegura que la funcionalidad ask permanezca disponible incluso si la base de conocimiento está parcialmente generada o usa formatos antiguos.
 
@@ -157,7 +175,13 @@ Esto asegura que la funcionalidad ask permanezca disponible incluso si la base d
 
 2. **Host-runner (sin API key):**
    ```bash
-   export RB_HOST_RUNNER=codex  # o generic
+   # Preset Codex (configuración incorporada)
+   export RB_HOST_RUNNER=codex
+
+   # Generic runner (requiere plantilla RB_HOST_COMMAND)
+   export RB_HOST_RUNNER=generic
+   export RB_HOST_COMMAND='trae-cli exec --cd {workspace} --sandbox read-only --skip-git-repo-check --ephemeral -o {output_file}'
+   export RB_HOST_OUTPUT_MODE=file
    # Usa IDE CLI con sesión iniciada, no se necesita API key
    ```
 
@@ -219,11 +243,14 @@ rb-ask "¿Qué cambió en el módulo auth?"
 ### Ejemplo 3: Uso de Depuración
 
 ```bash
-# Actualizar con logging de depuración
-RB_LOG_LEVEL=DEBUG rb-refresh
+# Preguntar con salida verbosa (progreso en streaming)
+rb-ask "¿Dónde está la conexión de base de datos?"
 
-# Preguntar con salida verbosa
-RB_LOG_LEVEL=DEBUG rb-ask "¿Dónde está la conexión de base de datos?"
+# Verificar estado de actualización
+rb report
+
+# Forzar actualización completa (no incremental)
+rb-refresh  # sin --quick
 ```
 
 ## 🐛 Solución de Problemas
@@ -272,7 +299,7 @@ Implementación del servidor MCP: `engine/repobrain_engine/hub/mcp_server.py`
 
 ### Acelerar Actualización
 - Usar `--quick` para actualizaciones incrementales (árbol de trabajo limpio después de commit)
-- Excluir directorios innecesarios (configurar patrones de ignorar en `.repobrain/config.json`)
+- Las exclusiones de escaneo están incorporadas (venv, node_modules, .git, etc. — ver `SKIP_DIRS` en `engine/repobrain_engine/hub/_constants.py`)
 - Usar modelos más rápidos (ej., GPT-4o-mini o Claude 3.5 Haiku)
 
 ### Mejorar Calidad de Respuesta

docs/zh/ROADMAP.md

@@ -17,7 +17,7 @@ RepoBrain 正收敛为一个可移植的 repository knowledge engine：把 works
 | 6 动态发现 | 完成 | 工具/上下文零配置加载 |
 | 7 Multi-Agent Swarm | 完成 | Router-Worker 编排 |
 | 8 MCP 集成 | 完成 | MCP server / consumer 支持 |
-| 9 产品化加固 | 进行中 | 安全边界、可观测、安装与文档契约 |
+| 9 产品化加固 | 完成 | 安全边界、可观测、安装与文档契约 |
 | 10 Knowledge Hub | 完成 | 代码库刷新、模块知识、路由式问答 |
 
 ## 已完成的核心功能（截至 2026 年 8 月）

docs/zh/SWARM_PROTOCOL.md

@@ -72,6 +72,8 @@ graph LR
 
 当没有配置 API key 时（`RB_HOST_RUNNER` 设置为 `codex` 或 `generic`），Refresh 会使用单轮、无工具的 Convention Agent (`build_single_turn_convention_agent()`)，该 Agent 将三阶段链压缩为一次生成。
 
+**重要：** Host-runner 模式的 refresh 仅为单轮。不使用完整的三 Agent handoff 链。
+
 ## 💬 Ask Swarm：动态模块路由
 
 当你运行 `rb-ask "问题"` 时，Ask Swarm 会将问题路由到相关模块的 Agent 并返回带有文件路径和行号的答案。
@@ -115,11 +117,11 @@ graph TD
 **职责：** 负责特定模块的深度知识
 
 每个模块都有自己的 Agent，具有：
-- 模块的结构化 facts（JSON claims + 源码证据）
+- 模块的 agent 知识（`agents/*.md` — 分组模块摘要或旧版 `modules/*.md`）
 - 探索代码的工具（read_file、search_code 等）
 - 可以移交给其他 ModuleAgent 以获取跨模块信息
 
-ModuleAgent 根据项目扫描结果动态创建（每个检测到的模块一个 Agent）。
+ModuleAgent 在旧版 swarm 路径中动态创建（每个检测到的模块一个 Agent）。当结构化工件存在时，ask pipeline 使用 `_ask_with_agent_md`，通过 `map.md` 直接路由，而不构建完整的 swarm。
 
 #### 📜 GitAgent
 **职责：** Git 历史和变更分析
@@ -136,13 +138,29 @@ ModuleAgent 根据项目扫描结果动态创建（每个检测到的模块一
 - **管道：** `engine/repobrain_engine/hub/ask_pipeline.py`
 - **知识库：** 从 `.repobrain/current.json` 指向的生成目录读取
 
+### Host-Runner 模式（无多 Agent 路由）
+
+当设置 `RB_HOST_RUNNER`（`codex` 或 `generic`）时，Ask 仅使用 `_ask_with_host_runner`：
+- **单次本地 CLI 调用**，包含项目上下文和问题
+- **不**构建 Router/ModuleAgent/GitAgent 或执行多 Agent handoff
+- 从本地 host CLI 直接返回答案（无 swarm 编排）
+
+使用无 API key 路径的用户必须理解，他们得到的是单轮本地答案，而非完整的 Router-Worker 协作。
+
 ### 回退策略
 
-Ask pipeline 实现了三层回退机制：
+Ask pipeline 实现了上下文感知的回退机制：
+
+**当设置 `RB_HOST_RUNNER`（codex 或 generic）时：**
+- 仅使用 `_ask_with_host_runner`
+- 不构建 Router/ModuleAgent/GitAgent
+- 单次本地 CLI 调用，无多 Agent 路由
 
-1. **`_ask_with_structured_facts`** — 使用结构化 facts（JSON claims + 源码验证）
-2. **`_ask_with_agent_md`** — 回退到 agent.md 文件（纯文本知识）
-3. **`_ask_with_legacy_swarm`** — 最终回退（如果前两者都失败）
+**标准 API-based ask 流程：**
+1. **`_ask_with_structured_facts`**（当 `.repobrain/map.md` 和 `agents/*.md` 存在时）：
+   - 首先尝试 `_ask_with_agent_md` — 通过 map.md 路由到 agent.md 知识
+   - 在同一调用中回退到 `_ask_with_legacy_facts` — 如可用则使用旧版 `*.facts.json`
+2. **`_ask_with_legacy_swarm`** — 当结构化工件未返回答案时的最终回退
 
 这确保了即使知识库部分生成或使用旧格式，ask 功能仍然可用。
 
@@ -157,7 +175,13 @@ Ask pipeline 实现了三层回退机制：
 
 2. **Host-runner（无 API key）：**
    ```bash
-   export RB_HOST_RUNNER=codex  # 或 generic
+   # Codex 预设（内置配置）
+   export RB_HOST_RUNNER=codex
+
+   # Generic runner（需要 RB_HOST_COMMAND 模板）
+   export RB_HOST_RUNNER=generic
+   export RB_HOST_COMMAND='trae-cli exec --cd {workspace} --sandbox read-only --skip-git-repo-check --ephemeral -o {output_file}'
+   export RB_HOST_OUTPUT_MODE=file
    # 使用登录的 IDE CLI，无需 API key
    ```
 
@@ -219,11 +243,14 @@ rb-ask "auth 模块有什么变化？"
 ### 示例 3：调试使用
 
 ```bash
-# 带调试日志的刷新
-RB_LOG_LEVEL=DEBUG rb-refresh
+# 带详细输出的问答（流式进度）
+rb-ask "数据库连接在哪里？"
 
-# 带详细输出的问答
-RB_LOG_LEVEL=DEBUG rb-ask "数据库连接在哪里？"
+# 检查刷新状态
+rb report
+
+# 强制完全刷新（非增量）
+rb-refresh  # 不使用 --quick
 ```
 
 ## 🐛 故障排查
@@ -272,7 +299,7 @@ MCP server 实现：`engine/repobrain_engine/hub/mcp_server.py`
 
 ### 加快刷新速度
 - 使用 `--quick` 进行增量更新（提交后的干净工作树）
-- 排除不必要的目录（在 `.repobrain/config.json` 中配置忽略模式）
+- 扫描排除项已内置（venv、node_modules、.git 等 — 参见 `engine/repobrain_engine/hub/_constants.py` 中的 `SKIP_DIRS`）
 - 使用更快的模型（例如 GPT-4o-mini 或 Claude 3.5 Haiku）
 
 ### 提高回答质量