Documentation audit: 39 files outdated across /docs/

[aheritier]

Documentation Audit Results

60 files checked. 39 have issues. 21 are clean.

Audit performed 2026-04-18 by cross-checking every doc in /docs/ against pkg/, cmd/, agent-schema.json, and CHANGELOG.md.

---

🔴 Fix Immediately — Factually Wrong

These contain incorrect information that will break user workflows or actively mislead.

1. Config version number is wrong everywhere

File: configuration/overview/index.md
Current version is 8. The doc says "5" in the versioning section and "6" in an example. agent-schema.json only enumerates up to "7".
Fix: Update prose to say version 8; add "8" to the enum in agent-schema.json.

2. rag: agent property was removed in v7→v8

File: configuration/agents/index.md
The doc shows rag: [list] as a valid agent-level property. In v8 this was migrated to toolsets: [{type: rag, ref: ...}]. The rag: field does not exist in pkg/config/latest/types.go.
Fix: Remove the rag: property row; add a toolsets-based RAG example.

3. handoff tool described as A2A remote (it is local peer-to-peer)

Files: configuration/tools/index.md, concepts/tools/index.md, tools/handoff/index.md
All three say the handoff tool does "A2A remote agent delegation". It is actually the internal mechanism for handing off a conversation to another agent in the same config file, using only a local agent name. The a2a toolset type is the remote one.
handoff/index.md is the worst offender: it invents a nonexistent type: handoff toolset with fake url and timeout fields.
Fix: Rewrite handoff/index.md from scratch; correct the tool type table rows in the other two files.

4. Docker Desktop minimum version inconsistency

Files: getting-started/installation/index.md, README.md
Installation doc says 4.49.0; README says 4.63+. Users on 4.49–4.62 will expect the CLI plugin to be pre-installed when it isn't.
Fix: Align both files on 4.63+.

5. Nebius base URL is wrong

File: providers/nebius/index.md
Doc says https://api.studio.nebius.ai/v1; code has https://api.studio.nebius.com/v1 (.com, not .ai). Users copying the URL will get connection errors.
Fix: Change .ai → .com.

6. Go SDK NewShellTool called with wrong number of arguments

File: guides/go-sdk/index.md
Example shows builtin.NewShellTool(os.Environ(), rtConfig, nil) (3 args). The actual signature is NewShellTool(env []string, runConfig *config.RuntimeConfig) (2 args). The example will not compile.
Fix: Remove the third nil argument.

7. Mistral falsely claims thinking is enabled by default

File: providers/mistral/index.md
Doc says "By default, docker-agent enables medium thinking effort." The code only auto-enables a default thinking budget for OpenAI o-series models (o1/o3/o4 prefixes), never for Mistral.
Fix: Remove the false default claim; clarify that thinking_budget must be set explicitly for Mistral.

8. Provider auto-detection priority is wrong in two docs

Files: providers/overview/index.md, guides/tips/index.md
Both say "Provider priority: OpenAI → Anthropic → Google → Mistral → DMR". The code (pkg/config/auto.go) checks: Anthropic → OpenAI → Google → Mistral → Amazon-Bedrock → DMR.
Both docs also omit Amazon-Bedrock from the list entirely, and miss four built-in provider aliases: requesty, azure, ollama, github-copilot.
Fix: Correct the order in both files; add the missing providers.

9. TUI doc contains a fabricated keyboard shortcut

File: features/tui/index.md
Documents Ctrl+L as "Start audio listening mode (voice input)". This keybinding does not exist anywhere in the codebase. Audio is triggered by the /speak slash command (macOS only).
Fix: Remove the Ctrl+L row; add /speak to the slash-commands table.

---

🟠 Significantly Incomplete or Misleading

10. fetch tool: claims GET/POST/PUT/DELETE; only GET is implemented

File: tools/fetch/index.md
Doc says the tool "lets agents make HTTP requests (GET, POST, PUT, DELETE, etc.)". Implementation issues http.MethodGet only. Also missing tool-call parameters: urls []string (plural, required), format ("markdown"/"html"/"text").

11. filesystem tool: two tools missing from the docs

File: tools/filesystem/index.md
create_directory(paths []string) and remove_directory(paths []string) are fully implemented but not listed in the Available Tools table.

12. shell tool: background job sub-tools entirely undocumented

File: tools/shell/index.md
Four background job tools are missing: run_background_job(cmd, cwd?), list_background_jobs(), view_background_job(job_id), stop_background_job(job_id). Also missing: per-call cwd and timeout parameters on the main shell tool.

13. MCP server HTTP transport mode undocumented

Files: features/mcp-mode/index.md, features/cli/index.md
The --http flag (streaming HTTP transport) and --listen flag are fully implemented (cmd/root/mcp.go) but not mentioned in either doc.

14. Remote MCP OAuth credential config missing

File: features/remote-mcp/index.md
Added in v1.46.0: the oauth: block under remote: (clientId, clientSecret, callbackPort, scopes) is entirely absent from the doc.

15. API server missing three endpoints

File: features/api-server/index.md
Three endpoints implemented but undocumented (all added v1.44.0):

• POST /api/sessions/:id/steer — inject message into running session mid-turn
• POST /api/sessions/:id/followup — send follow-up after turn completes
• GET /api/agents/:id/:agent_name/tools/count

16. CLI reference missing many flags and the models command

File: features/cli/index.md

• docker agent models command missing (added v1.41.0)
• docker agent run missing: --lean, --sandbox, --hide-tool-results, --hide-tool-calls, --json, --session-db, --attach, --dry-run

17. mcps: top-level config section completely undocumented

File: configuration/overview/index.md
mcps: map[string]MCPToolset is a top-level config key for defining reusable named MCP toolsets (referenced via ref: inside agents). It's in agent-schema.json and the code but has zero documentation coverage.

18. Sandbox doc: wrong backend described, missing flags

File: configuration/sandbox/index.md
Doc says the agent runs in "a Docker container". The actual backend uses Docker Desktop's sandbox API (sbx CLI or docker sandbox exec). Missing CLI flags: --template <image> (customize sandbox template) and --sbx=false (force backend selection).

19. Four toolset types missing from tool reference pages

Files: configuration/tools/index.md, concepts/tools/index.md
Valid, usable toolset types that are not listed: rag, openapi, tasks, model_picker.

---

🟡 Missing Parameters, Incomplete Tables, Undocumented Additions

20. background-agents tool: all tool parameters missing

File: tools/background-agents/index.md
Tools listed but parameters absent: run_background_agent(agent, task, expected_output?), view_background_agent(task_id), stop_background_agent(task_id).

21. transfer-task tool: all tool parameters missing

File: tools/transfer-task/index.md
Parameters not documented: agent (required), task (required), expected_output (optional).

22. user-prompt tool: title parameter missing

File: tools/user-prompt/index.md
UserPromptArgs.Title string (sets dialog window title, defaults to "Question") is absent from the parameters table.

23. a2a tool: name incorrectly marked required; headers missing

File: tools/a2a/index.md
name is optional (tool name derived from remote agent card when empty). headers: map[string]string config field is supported but not documented.

24. TUI: seven slash commands undocumented

File: features/tui/index.md
Missing from the slash-commands table: /fork, /clear, /copy-last, /permissions, /tools, /split-diff, /speak.

25. TUI: tab and multi-agent keyboard shortcuts missing

File: features/tui/index.md
Not documented: Ctrl+T (new tab), Ctrl+W (close tab), Ctrl+N/Ctrl+P (next/prev tab), Ctrl+1–9 (switch to agent by index), Ctrl+B (toggle sidebar), Ctrl+G (open editor), Ctrl+Y (copy session ID).

26. evaluation: wrong default judge model string and missing --repeat

File: features/evaluation/index.md
Doc says anthropic/claude-opus-4-5; code constant is anthropic/claude-opus-4-5-20251101. --repeat flag (added v1.46.0) absent from CLI table.

27. xhigh effort level missing across three provider docs

Files: providers/openai/index.md, providers/mistral/index.md, providers/xai/index.md
xhigh was added in v1.46.0 but is absent from the thinking_budget effort level enumerations in all three docs.

28. Anthropic: missing models and misleading "Defaults to 8192"

File: providers/anthropic/index.md
Model table missing claude-haiku-4-5 and claude-opus-4-7. "Defaults to 8192" is misleading — there is no default thinking_budget for Anthropic; 8192 is a max_tokens supplement. xhigh and max effort levels also missing.

29. Google: missing alternative env vars and misleading "default" comments

File: providers/google/index.md
GEMINI_API_KEY and GOOGLE_GENAI_USE_VERTEXAI env var alternatives not documented. YAML comments imply certain thinking budgets are system defaults when they are not.

30. Bedrock: apac. inference profile prefix missing

File: providers/bedrock/index.md
Code supports us., eu., apac., global.; doc table only lists the first three.

31. Provider list incomplete in model reference docs

Files: configuration/models/index.md, concepts/models/index.md
Supported providers not listed: nebius, ollama, minimax, github-copilot, requesty, azure.

32. skills documented as boolean-only; also accepts list of sources

Files: configuration/agents/index.md, concepts/agents/index.md
Code supports skills: ["local"] (list) in addition to skills: true. Schema is also boolean-only and needs updating.

33. Permissions: ask: field never shown in config examples

File: configuration/permissions/index.md
ask: is mentioned in prose but no YAML example shows it in use.

34. Secrets priority chain incomplete

File: guides/secrets/index.md
Credential helper and Docker Desktop provider are present in the code resolution chain (NewDefaultProvider()) but absent from the priority table.

35. ACP and A2A serve commands: runtime flags undocumented

Files: features/acp/index.md, features/a2a/index.md
Both commands inherit addRuntimeConfigFlags (hooks, --working-dir, --env-from-file, --models-gateway, --code-mode-tools, etc.). None of these flags are listed. The --agent flag for serve a2a (to expose a specific sub-agent) is also undocumented.

---

🔵 Minor / Low Impact

File	Issue
community/troubleshooting/index.md	Prose typo: "When docker-agent as an API server" → missing "running"
providers/minimax/index.md	API Type shows (openai) (internal name); other docs use (openai_chatcompletions)
providers/dmr/index.md	Custom base_url example uses llama.cpp-specific path instead of generic /engines/v1/
configuration/models/index.md	Full schema comment lists only 5 providers (incomplete)

---

Files with No Issues

configuration/hooks/, configuration/routing/, configuration/structured-output/, concepts/distribution/, concepts/multi-agent/, getting-started/introduction/, getting-started/quickstart/, tools/api/, tools/lsp/, tools/memory/, tools/openapi/, tools/script/, tools/think/, tools/todo/, features/rag/, features/skills/, community/contributing/, community/telemetry/, providers/custom/, providers/local/

[aheritier]

@dgageot a real review is required to be sure that these are not just hallucinations