docs: fix doc-code divergences reported in #2464

[dgageot]

Audit of every claim in #2464 against the source code, followed by targeted fixes. All 35 real issues reported in the audit plus one broken cross-reference discovered during review are addressed here (36 logical fixes, squashed into a single commit).

All changes are documentation / JSON Schema only — no Go source is touched, so mise lint and go test ./... stay green.

Coverage

Schema / overview

• Bump the config schema version to 8 in docs/configuration/overview and agent-schema.json (enum, examples, description) to match pkg/config/latest/parse.go (currentVersion = 8).
• Document the top-level mcps: section for reusable MCP server definitions (pkg/config/latest/types.go, Config.MCPs).
• Remove the non-existent rag: agent-level property from the agent reference — RAG is now attached via toolsets:.
• Document skills accepting either a boolean or a list of sources (SkillsConfig supports "local" plus HTTP/HTTPS URLs).
• Show ask: in the main permissions YAML example.

Providers

• Fix Nebius base URL (.com, not .ai) to match pkg/model/provider/provider.go.
• Fix the provider auto-detection priority order in guides/tips (Anthropic → OpenAI → Google → Mistral → Amazon Bedrock → DMR per pkg/config/auto.go).
• Add the missing built-in aliases (requesty, azure, ollama, github-copilot) to the providers overview and concepts/models tables.
• Document GEMINI_API_KEY and the Vertex AI env vars for Google.
• List claude-opus-4-7 and claude-haiku-4-5 in the Anthropic models table.
• Add the apac. inference profile prefix to the Bedrock doc.
• Remove the false "medium thinking by default" claim from Mistral — default thinking is only applied to OpenAI o-series models.
• Add xhigh, max, and adaptive/<level> to the thinking-effort lists in OpenAI, xAI, and configuration/models.

CLI and features

• Align Docker Desktop minimum version to 4.63+ in the installation doc.
• Document the docker agent models command and the missing docker agent run flags (--lean, --sandbox, --template, --sbx, --json, --session-db, --attach, --dry-run, --hide-tool-calls, --hide-tool-results).
• Document serve mcp --http and --listen flags.
• Document serve a2a and serve acp runtime flags (--working-dir, --env-from-file, --models-gateway, --code-mode-tools, --hook-*, --agent, --listen, --session-db).
• Describe the real sandbox backend (docker sandbox / sbx CLI) and add --template / --sbx flags.
• Fix the default --judge-model string to anthropic/claude-opus-4-5-20251101 per cmd/root/eval.go.
• Document the /api/sessions/:id/steer, /followup, and /api/agents/:id/:agent_name/tools/count endpoints.
• Document the OAuth config block for remote MCP servers that don't support Dynamic Client Registration.
• Expand the secrets priority chain with the credential helper and Docker Desktop providers (pkg/environment/default.go).

TUI

• Remove the non-existent Ctrl+L audio keybinding.
• Add the missing slash commands: /clear, /copy-last, /fork, /permissions, /tools, /split-diff, /speak (plus /quit and /q aliases).
• Add tab/multi-agent and yolo/sidebar keybindings (Ctrl+T/W/N/P, Ctrl+1–9, Ctrl+S, Ctrl+B, Ctrl+Y, Ctrl+O, Ctrl+G).

Tools

• Rewrite the handoff tool reference: it is local peer-to-peer, auto-enabled by handoffs:, not an A2A remote toolset with url/timeout fields.
• Document the fetch tool as GET-only with urls, format, and per-call timeout parameters, and a 1 MB / robots.txt note.
• Add create_directory and remove_directory to the filesystem tools table.
• Document the shell toolset's background-job tools (run_background_job, list_background_jobs, view_background_job, stop_background_job) plus cwd/timeout parameters.
• Document parameters for background_agents (agent/task/expected_output/task_id), transfer_task (agent/task/expected_output), and user_prompt (title).
• Mark name as optional and document headers on the a2a toolset.
• Add rag, openapi, tasks, and model_picker to the configuration/tools and concepts/tools tables.
• Add the missing /tools/tasks/ and /tools/model-picker/ reference pages (cross-referenced from the tables above).

Go SDK

• Fix the builtin.NewShellTool example to use the actual 2-argument signature from pkg/tools/builtin/shell.go.

Validation

• go build ./... — passes
• go vet ./... — clean
• gofmt -l . — clean
• golangci-lint run — 0 issues
• go run ./lint . — 754 files, no offenses
• go test ./... — 96 packages pass, 0 failures

Closes #2464

---

Assisted-By: docker-agent