Docs audit phase 2: user-perspective rewrites and deduplication (follow-up to #2654)

[acoliver]

Follow-up to #2654. That issue's audit identified two classes of work: (a) mechanical/verifiable fixes and prevention tooling, and (b) subjective prose rewrites of large user-facing pages. The first PR for #2654 delivers (a) — link/placement CI guards, six internal-doc relocations, factual corrections to telemetry/uninstall/tool-parsing, and a documentation style guide. This issue tracks (b).

These were deliberately deferred to keep the first change reviewable and to separate mechanically-verifiable fixes from prose judgement. #2654 should NOT be closed until this work lands.

Remaining work from the #2654 audit

Split mixed user/internal material

• docs/agent-api.md (1373 lines) — retain supported imports, lifecycle, configuration, events, errors, disposal, stability, examples; move implementation history and future work to dev-docs/; split by user task.
• docs/deployment.md — keep install/run/deployment guidance; move running-from-source, package/build architecture, test runner, and release-workflow internals to dev-docs/.
• docs/message-bus.md — lead with controlling tool execution via policies; move call-flow pseudocode, legacy flow, and performance internals to dev-docs/architecture/message-bus.md.
• docs/todo-system.md — lead with user-visible behavior; move model-facing tool schemas and complexity heuristics out.
• docs/core/memport.md — keep syntax, path rules, safety, examples, errors, troubleshooting; move internal function/type and cross-product comparison material out.

Rebuild in task order and deduplicate

• docs/tools/mcp-server.md (730 lines) — rebuild as add, authenticate, verify, use, restrict trust, troubleshoot, remove. Deduplicate the repeated MCP-prompts and server-management sections; move discovery/execution internals to dev-docs/.
• Consolidate the overlapping hook tutorials docs/hooks/creating-custom-hooks.md and docs/hooks/writing-hooks.md (1592 lines combined) into one canonical tutorial plus cross-links.

Rewrite records around readers

• docs/release-notes/2025Q4.md — organize by user-visible changes, affected users, compatibility, required actions, security impact.
• docs/migration/stateless-provider-v2.md — add affected versions, prerequisites, before/after, verification, rollback.
• docs/migration/approval-mode-to-policies.md (734 lines) — replace rollout-era phase framing with a current-state migration.

Tone and freshness

• docs/sandbox.md — replace absolute/sensational claims with a neutral threat model, explicit boundaries, platform limitations, and verification steps.
• docs/providers/quick-reference.md (667 lines) — split into a scannable setup reference plus freshness-owned model/pricing guidance with an "as of" date and owner.
• docs/cli/index.md — replace package-layout framing with task-oriented navigation.
• docs/cli/retry-settings.md, docs/debug-logging.md, docs/multiline-input.md — move source-file/implementation pointers to dev-docs/.

Notes for the implementer

• The placement guard added in Audit documentation audience, placement, and writing standards #2654 (npm run lint:doc-placement) already enforces the placement half mechanically: docs/ cannot regain architecture/, plans/, or merge-notes/ directories, and plan/requirement bookkeeping markers are rejected outside code fences.
• The link guard (npm run lint:doc-links) validates every repo-relative link and heading anchor across docs/, dev-docs/, and root-level Markdown. Relocations must keep it green.
• dev-docs/documentation-style-guide.md defines the audience/placement policy and the docs review checklist to follow.
• Verify every factual claim against source before writing it. The Audit documentation audience, placement, and writing standards #2654 work found docs asserting behavior the code does not implement.

[coderabbitai]

🔗 Related PRs

#593 - Fix Pipeline ToolCall Issues #518 #556 [closed]
#931 - Add subagent docs and align sandbox image references [merged]
#1893 - Clean up old dev-docs (Fixes #1745) [merged]
#2311 - docs: Update documentation for Bun runtime migration (Fixes #2245) [merged]
#2655 - Fix ACP/Zed: task tool crash + todo_pause loop-break (Closes #2653) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!