Audit documentation audience, placement, and writing standards

[acoliver]

Scope and method

Read-only audit of every Markdown source file recursively under docs/ and dev-docs/. A document here means a .md source file, including indexes, references, tutorials, migration/release records, plans, merge records, and generated Markdown baselines. Static images are inventoried separately.

Classification	docs/	dev-docs/	Total
1. User-facing	71	0	71
2. Developer/internal	6	22	28
3. AI slop / scratch; delete	0	0	0
Markdown documents	77	22	99

There are also 16 documentation assets under docs/assets/ (15 PNG and one SVG), for 115 total inventoried files.

Executive findings

• No whole document meets a defensible deletion threshold for AI slop. Some pages contain duplicated, malformed, or implementation-record material, but should be edited or moved rather than deleted wholesale.
• Six developer/internal documents are misplaced under docs/ and should move to dev-docs/.
• Several nominally user-facing pages are written partly as implementation records and need a user-focused rewrite or split.
• Immediate correctness/safety defects include an uninstall page that names gemini-cli and recommends deleting the entire npx cache, contradictory telemetry instructions, malformed/duplicated hook guidance, and broken relative links.
• No user-facing document is misplaced under dev-docs/.

1. User docs that are not written from a user perspective, but should be

Highest priority

Document	Problem	Recommendation
docs/Uninstall.md	Names gemini-cli and presents deleting the entire npx cache, including unrelated packages, as uninstall.	Document supported LLxprt install channels separately. Do not make whole-cache deletion the default; clearly warn about collateral deletion if retained as troubleshooting.
docs/telemetry.md	Says telemetry initialization is commented out, gives settings/flags to enable it, then says source changes are required.	Establish one verified current state. If unavailable, make this a short status/privacy page and move re-enable internals to dev-docs/. Otherwise provide a tested enable/verify/disable flow. Reconcile with telemetry-privacy.md.
docs/agent-api.md	Starts as a public API guide but includes issue/requirement IDs, implementation decisions, package-trim sequencing, and future A2A work.	Retain supported imports, lifecycle, configuration, events, errors, disposal, stability, and examples. Move implementation history/future work to dev-docs/ and split the remaining large page by user task.
docs/hooks/best-practices.md	Contains an orphaned JavaScript fragment, a broken hooks-design link, and a second security guide that duplicates earlier guidance.	Remove the fragment, repair the link, merge duplicated security guidance, and link to the API reference instead of repeating schemas.
docs/release-notes/2025Q4.md	Foregrounds plan markers, internal names, doc-production status, and maintainer tests instead of reader impact; links a missing migration page.	Organize by user-visible changes, affected users, compatibility, required actions, security impact, and valid migration links.

Structural rewrites or audience splits

Document	Recommended change
docs/deployment.md	Keep supported installation/run/deployment guidance. Move running-from-source, package architecture, test runner, and release workflow to dev-docs/.
docs/message-bus.md	Lead with the user task of controlling tool execution with policies. Move event routing, legacy flow, implementation security, and performance internals to dev-docs/.
docs/todo-system.md	Lead with what users see and control. Move model tool schemas and complexity heuristics to internal tool documentation.
docs/tools/mcp-server.md	Rebuild in task order: add, authenticate, verify, use, restrict trust, troubleshoot, remove. Deduplicate management/prompts and move discovery/execution internals to dev-docs/.
docs/core/memport.md	Keep import syntax, path rules, safety, examples, errors, and troubleshooting. Move internal function/type and cross-product comparison material to dev-docs/.
docs/migration/stateless-provider-v2.md	Keep in docs/ only if its imports are supported public contracts; otherwise move it. Remove plan bookkeeping and add affected versions, prerequisites, before/after, verification, and rollback.
docs/migration/approval-mode-to-policies.md	Replace rollout-era phases and engine detail with a current-state user migration: affected users, minimal steps, examples, verification, and rollback.
docs/cli/index.md	Replace package-layout framing with task-oriented navigation.
docs/cli/retry-settings.md	Keep user settings and observable behavior; move the source-file implementation pointer.
docs/sandbox.md	Replace sensational/absolute claims with a neutral threat model, explicit boundaries, platform limitations, and verification steps.

Smaller user-perspective improvements

• Extract developer API material from docs/debug-logging.md and implementation detail from docs/multiline-input.md.
• Consolidate docs/keyboard-shortcuts.md and docs/cli/keyboard-shortcuts.md around one canonical generated source.
• Consolidate the overlapping hook tutorials in docs/hooks/creating-custom-hooks.md and docs/hooks/writing-hooks.md.
• Split docs/providers/quick-reference.md into a genuinely scannable setup reference and freshness-owned model/pricing guidance.
• Replace hype such as ?excellent support,? ?powerful,? and ?sophisticated? with verified capabilities and constraints.

2. AI slop / scratch docs to delete

None.

This is deliberately conservative. The implementation plan, merge notes, skipped-test analysis, and generated import baseline are traceable engineering records with durable internal value; move/archive them instead of calling them slop. The malformed fragment in docs/hooks/best-practices.md should be deleted from that page, but the document itself remains useful.

If completed plans and historical analyses should expire, first define a repository-wide retention/archive policy rather than deleting selectively based on tone or suspected authorship.

3. Developer docs currently under docs/ that should move

Current path	Suggested destination
docs/architecture/message-bus-architecture.md	dev-docs/architecture/message-bus.md
docs/hooks/architecture.md	dev-docs/hooks/architecture.md
docs/tool-output-format.md	dev-docs/tools/tool-output-format.md
docs/tool-parsing.md	dev-docs/providers/text-tool-call-parsing.md, with a short user configuration/troubleshooting page left behind if needed
docs/merge-notes/batch21-25-skipped.md	dev-docs/merge-notes/2026-01-06-batches21-25-skipped.md
docs/plans/2026-01-03-welcome-onboarding.md	dev-docs/plans/archive/2026-01-03-welcome-onboarding.md, or the repository's canonical project-plans archive

Move these with inbound-link updates or redirects. No user-facing page was found misplaced under dev-docs/.

Additional consistency defects

• docs/release-notes/2025Q4.md links to absent docs/release-notes/stateless-provider.md.
• docs/hooks/best-practices.md links to absent docs/hooks-design.md and contains an orphaned JavaScript fragment outside a code fence.
• docs/cli/profiles.md links to absent docs/cli/sandboxing.md; likely targets are docs/cli/sandbox-profiles.md or docs/sandbox.md.
• docs/tools/mcp-server.md duplicates server-management and MCP-prompt sections.
• The two generated keyboard shortcut references overlap but differ; choose one public canonical path.

4. Proposed documentation style guide

Audience and placement

• docs/ is for product consumers: CLI users, administrators, supported public API consumers, provider integrators, extension authors, and hook authors.
• dev-docs/ is for repository contributors/maintainers: architecture, internal APIs, source paths, tests, release/packaging mechanics, baselines, implementation migrations, design decisions, plans, and historical engineering records.
• Public developer docs stay in docs/ only when they describe a supported contract. Label stability clearly and avoid deep source imports.
• Implementation plans and merge/cherry-pick records never belong in public docs navigation.
• A migration guide belongs in docs/ only when external users or integrators must act.

User-focused writing

• Start with the reader outcome and intended audience.
• Use ?you? for actions and describe what the reader can see, configure, and verify.
• Put a minimal successful path before exhaustive reference material.
• For settings, state scope, persistence, default, precedence, and valid values.
• For commands/examples, state prerequisites, expected result, and verification.
• State limitations and security boundaries before advanced setup.
• Do not lead with source paths, class names, internal state machines, issue/plan IDs, test names, or implementation history.

Tone

• Be direct, neutral, and factual; replace hype with capabilities and constraints.
• Avoid absolute security/privacy/performance claims unless the boundary and evidence are explicit.
• Distinguish guarantees from recommendations and use Warning, Note, and Experimental callouts consistently.
• Use ?LLxprt Code? in prose and ?llxprt? for the command.

Standard structure

How-to/tutorial: goal/audience; prerequisites; quick start; numbered steps; expected result; variations; security/limitations; troubleshooting; related reference.

Reference: purpose/scope; syntax/schema; defaults; precedence/persistence; valid values/errors; minimal examples; related guides.

Migration: status/affected versions/audience; compatibility impact; before/after; migration steps; verification; rollback; deprecation timeline.

Release note: version/date/status; user-visible changes; breaking changes; required actions; security/privacy; valid migration/reference links.

Internal design/record: status/owner/date; authoritative vs historical; context; decision/architecture; source/test locations; verification; tradeoffs; follow-ups/supersession.

Maintenance rules

• Maintain one canonical page per subject and link rather than copy.
• Identify generators and canonical sources for generated sections.
• Run a recursive link check in CI.
• Test commands on stated platforms or label them unverified.
• Give mutable provider/model/pricing tables an ?as of? date and owner, or link to provider-maintained data.
• Remove rollout phases from user docs once migrations ship.
• Add a docs review checklist covering audience, placement, public-contract status, task-first structure, security claims, links, and duplication.

Proposed implementation plan

P0: correctness and safety

• Rewrite docs/Uninstall.md.
• Resolve telemetry's actual state and rewrite docs/telemetry.md consistently.
• Repair and deduplicate docs/hooks/best-practices.md.
• Fix the three confirmed broken relative links.

P1: audience and placement

• Move the six internal docs listed above and update inbound links.
• Split mixed user/internal material in agent-api, deployment, message-bus, todo-system, MCP server, and memport docs.
• Rewrite the release note and migration pages around affected readers and supported actions.

P2: consistency and prevention

• Adopt the style guide in contributor-visible documentation.
• Canonicalize duplicated keyboard, hooks, and MCP material.
• Add recursive link checking and a docs review checklist.
• Add freshness ownership for provider/model/pricing guidance.

Acceptance criteria

• Every Markdown source remains classified as user-facing or internal; internal architecture/plans are absent from public navigation.
• User pages start with a reader outcome and contain no unexplained internal issue/plan/workflow markers.
• Uninstall and telemetry instructions are tested and non-contradictory.
• No repository-relative link under docs/ or dev-docs/ is broken.
• Duplicated keyboard, MCP, and hooks material has one canonical source.
• Historical records live in an explicitly internal archive instead of being deleted as ?AI slop.?

---

Complete per-file classification

Every Markdown source appears exactly once below.

1. User-facing documentation (71)

1. docs/agent-api.md
2. docs/checkpointing.md
3. docs/debug-logging.md
4. docs/deployment.md
5. docs/disabled-tools.md
6. docs/EMOJI-FILTER.md
7. docs/extension.md
8. docs/gemini-cli-tips.md
9. docs/getting-started.md
10. docs/ide-integration.md
11. docs/index.md
12. docs/keyboard-shortcuts.md
13. docs/llxprt-ignore.md
14. docs/local-models.md
15. docs/message-bus.md
16. docs/multiline-input.md
17. docs/oauth-setup.md
18. docs/policy-configuration.md
19. docs/prompt-configuration.md
20. docs/sandbox.md
21. docs/settings-and-profiles.md
22. docs/shell-replacement.md
23. docs/subagents.md
24. docs/telemetry-privacy.md
25. docs/telemetry.md
26. docs/todo-system.md
27. docs/tos-privacy.md
28. docs/troubleshooting.md
29. docs/Uninstall.md
30. docs/zed-integration.md
31. docs/cli/authentication.md
32. docs/cli/commands.md
33. docs/cli/configuration.md
34. docs/cli/context-dumping.md
35. docs/cli/enterprise.md
36. docs/cli/google-cloud-auth.md
37. docs/cli/index.md
38. docs/cli/keyboard-shortcuts.md
39. docs/cli/profiles.md
40. docs/cli/providers.md
41. docs/cli/retry-settings.md
42. docs/cli/sandbox-profiles.md
43. docs/cli/skills.md
44. docs/cli/themes.md
45. docs/cli/token-caching.md
46. docs/cli/token-tracking.md
47. docs/cli/tutorials.md
48. docs/cli/tutorials/skills-getting-started.md
49. docs/core/memport.md
50. docs/examples/proxy-script.md
51. docs/features/async-tasks.md
52. docs/hooks/api-reference.md
53. docs/hooks/best-practices.md
54. docs/hooks/creating-custom-hooks.md
55. docs/hooks/index.md
56. docs/hooks/writing-hooks.md
57. docs/migration/approval-mode-to-policies.md
58. docs/migration/stateless-provider-v2.md
59. docs/providers/quick-reference.md
60. docs/recipes/claude-pro-workflow.md
61. docs/recipes/free-tier-setup.md
62. docs/recipes/high-availability.md
63. docs/recipes/index.md
64. docs/reference/application-directories.md
65. docs/reference/ephemerals.md
66. docs/reference/profiles.md
67. docs/release-notes/2025Q4.md
68. docs/tools/index.md
69. docs/tools/mcp-server.md
70. docs/tools/memory.md
71. docs/tutorials/sandbox-setup.md

2. Developer/internal documentation (28)

1. docs/architecture/message-bus-architecture.md
2. docs/hooks/architecture.md
3. docs/merge-notes/batch21-25-skipped.md
4. docs/plans/2026-01-03-welcome-onboarding.md
5. docs/tool-output-format.md
6. docs/tool-parsing.md
7. dev-docs/agents-neutral-gate-allowlist.md
8. dev-docs/agents-neutral-gate-baseline.md
9. dev-docs/bun.md
10. dev-docs/cherrypicking-runbook.md
11. dev-docs/cherrypicking.md
12. dev-docs/COORDINATING.md
13. dev-docs/genai-enclave-boundary-rules.md
14. dev-docs/genai-import-baseline.md
15. dev-docs/genai-migration.md
16. dev-docs/integration-tests.md
17. dev-docs/LINTING.md
18. dev-docs/npm.md
19. dev-docs/PLAN-TEMPLATE.md
20. dev-docs/PLAN.md
21. dev-docs/profileandsettings.md
22. dev-docs/REGRESSION_TESTS.md
23. dev-docs/RULES.md
24. dev-docs/runtime-loader.md
25. dev-docs/schema-guide.md
26. dev-docs/SKIPPED-TEST-ANALYSIS-20260327.md
27. dev-docs/stryker.md
28. dev-docs/tmux-harness.md

3. AI slop / scratch notes to delete (0)

None.

Excluded assets (16)

• docs/assets/connected_devtools.png
• docs/assets/llxprt-screenshot.png
• docs/assets/llxprt.svg
• docs/assets/theme-ansi-light.png
• docs/assets/theme-ansi.png
• docs/assets/theme-atom-one.png
• docs/assets/theme-ayu-light.png
• docs/assets/theme-ayu.png
• docs/assets/theme-custom.png
• docs/assets/theme-default-light.png
• docs/assets/theme-default.png
• docs/assets/theme-dracula.png
• docs/assets/theme-github-light.png
• docs/assets/theme-github.png
• docs/assets/theme-google-light.png
• docs/assets/theme-xcode-light.png

[acoliver]

@coderabbitai plan

[coderabbitai]

🔗 Related PRs

#593 - Fix Pipeline ToolCall Issues #518 #556 [closed]
#630 - feat: add --profile flag for inline JSON profiles [merged]
#917 - Fix tool-call history for provider switching [merged]
#931 - Add subagent docs and align sandbox image references [merged]
#1345 - fix: improve sandbox Git support and SSH agent forwarding [merged]
#1563 - docs: big fat doc updates (closes #1499) [merged]
#1815 - Remove dead upstream agent architecture files (Fixes #1765) [merged]
#1893 - Clean up old dev-docs (Fixes #1745) [merged]
#2577 - Generate trustworthy release notes (Fixes #2288) [merged]
#2646 - Complete OS-standard path migration for OAuth and global state (Fixes #2606) [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.}

---

🧪 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!

[coderabbitai]

Coding Plan

Summary

• Fix urgent correctness/safety defects first (uninstall, telemetry grounded in verified source behavior, malformed hooks guidance, and confirmed broken links) as independent content edits.
• Enforce the docs/ (user) vs dev-docs/ (internal) audience boundary by relocating the six misplaced documents with inbound-link updates and splitting mixed-audience pages so user docs lead with reader outcomes.
• Prevent recurrence via recursive link-check CI (reusing the orphaned .lycheeignore), canonicalization of duplicated keyboard/hooks/MCP content, and a new style guide plus docs review checklist.

Design Choices

Design Choice 1: What final shape should `docs/telemetry.md` take now that source truth is known?

Options Considered:

1. Reduce docs/telemetry.md to a short status/privacy page and move all enable internals to dev-docs/.
2. Rewrite docs/telemetry.md as a tested enable/verify/disable flow that accurately states local-only behavior and reconciles with telemetry-privacy.md.

Chosen Option: 2

Rationale: The verified state is available, so an accurate, non-contradictory user flow is the highest-value outcome and directly satisfies the acceptance criterion for tested telemetry instructions.

Design Choice 2: Where should the internal plan and merge-note records be relocated?

Options Considered:

1. Move plan/merge-note records into new dev-docs/plans/ and dev-docs/merge-notes/ subdirectories.
2. Move them into project-plans/ where analogous plan documents already live.

Chosen Option: 1

Rationale: It matches the ticket's explicit destination table and the .coderabbit.yaml "internal runbooks" categorization, keeping the change self-contained within the audited trees; project-plans/ has no archival convention to inherit.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Correctness and Safety (P0)

Fix the defects that mislead or endanger users. These are content-only edits to a small set of high-priority pages plus repair of confirmed broken repository-relative links. Grouped together because they are the most urgent and independently shippable.

Task 1: Rewrite `docs/Uninstall.md`

Present accurate, non-destructive uninstall guidance for LLxprt Code.

• Document the supported LLxprt install/uninstall channels first (global npm: npm uninstall -g @vybestack/llxprt-code``), using the product name "LLxprt Code" in prose and llxprt for commands.
• Reframe the npx shared-cache clearing as an optional troubleshooting step, with an explicit warning that it removes unrelated packages (collateral deletion); do not present whole-cache deletion as the default path.
• Remove gemini-cli framing except where genuinely required to explain shared-cache behavior, and clarify that caveat.

Task 2: Rewrite `docs/telemetry.md` to match verified source behavior

Replace contradictory "commented out / source changes required" claims with a tested, accurate flow.

• State the real current behavior: setting telemetry.enabled: true in settings.json (or the deprecated CLI flags) starts a working local pipeline; network/OTLP exporters are intentionally disabled and output goes to file/console only.
• Provide a minimal enable → verify → disable path describing scope, persistence, default (false), precedence (CLI over settings), and where output is written.
• Reconcile with docs/telemetry-privacy.md by clearly distinguishing OTEL telemetry from the separate /logging conversation-logging feature.
• Move any remaining re-enable/network internals or engineering rationale to dev-docs/ rather than leaving them in the user page.

Task 3: Repair and deduplicate `docs/hooks/best-practices.md`

Remove malformed content and consolidate duplicated guidance.

• Delete the orphaned JavaScript fragment rendered outside a code fence (the Promise.all snippet before the "Using Hooks Securely" heading).
• Repair the broken ../hooks-design.md link (retarget to an existing doc such as ./architecture.md or remove the dangling reference).
• Merge the duplicated security guidance ("Security considerations" vs "Authoring Secure Hooks", repeated SECRET_PATTERNS/containsSecret) into a single section, and link to docs/hooks/api-reference.md instead of repeating schemas.
• Preserve the #using-hooks-securely anchor since docs/extension.md links to it.

Task 4: Fix the three confirmed broken relative links

Ensure no repository-relative link is broken.

• In docs/release-notes/2025Q4.md, remove/replace the reference to the non-existent docs/release-notes/stateless-provider.md (retarget to ../migration/stateless-provider-v2.md, which exists).
• In docs/cli/profiles.md, fix the link to the non-existent ./sandboxing.md (retarget to ../sandbox.md or ./sandbox-profiles.md).
• The ../hooks-design.md link is handled in Task 1.3.

🤖 Prompt for AI agents

Implement Phase 1 (Correctness and Safety, P0): fix documentation defects that
mislead or endanger users via content-only edits to specific pages plus repair
of confirmed broken repository-relative links.

1. Rewrite `docs/Uninstall.md`:
- Lead with the supported LLxprt install/uninstall channels (global npm: `npm
uninstall -g `@vybestack/llxprt-code``); use "LLxprt Code" in prose and `llxprt`
in commands.
- Reframe npx shared-cache clearing as an optional troubleshooting step only,
with an explicit warning that it deletes unrelated packages; do not present it
as the default uninstall path.
- Remove `gemini-cli` framing except where required to explain shared-cache
behavior, with that caveat clarified.

2. Rewrite `docs/telemetry.md`:
- State the real, verified behavior: `telemetry.enabled: true` (via
settings.json or deprecated CLI flags) starts a working local pipeline;
network/OTLP exporters are intentionally disabled; output goes to file/console
only.
- Provide a minimal enable → verify → disable flow covering scope, persistence,
default value (`false`), CLI-over-settings precedence, and output location.
- Reconcile with `docs/telemetry-privacy.md` by distinguishing OTEL telemetry
from the separate `/logging` conversation-logging feature.
- Move remaining re-enable/network internals or engineering rationale to
`dev-docs/`.

3. Repair `docs/hooks/best-practices.md`:
- Delete the orphaned JavaScript `Promise.all` fragment that renders outside a
code fence, located before the "Using Hooks Securely" heading.
- Fix the broken `../hooks-design.md` link by retargeting to an existing doc
(e.g., `./architecture.md`) or removing the dangling reference.
- Merge duplicated security guidance ("Security considerations" vs "Authoring
Secure Hooks", repeated `SECRET_PATTERNS`/`containsSecret`) into one section,
linking to `docs/hooks/api-reference.md` instead of repeating schemas.
- Preserve the `#using-hooks-securely` anchor since `docs/extension.md` links to
it.

4. Fix broken relative links:
- In `docs/release-notes/2025Q4.md`, replace the reference to non-existent
`docs/release-notes/stateless-provider.md` with
`../migration/stateless-provider-v2.md`.
- In `docs/cli/profiles.md`, fix the link to non-existent `./sandboxing.md` by
retargeting to `../sandbox.md` or `./sandbox-profiles.md`.

Phase 2: Audience and Placement (P1)

Relocate misplaced internal documents into dev-docs/, and rewrite/split nominally user-facing pages so they lead with reader outcomes while moving implementation history and internals out. Grouped because all tasks enforce the docs/ vs dev-docs/ audience boundary.

Task 1: Relocate the six misplaced internal documents with inbound-link updates

Move contributor/internal content out of public navigation.

• Move docs/architecture/message-bus-architecture.md → dev-docs/architecture/message-bus.md.
• Move docs/hooks/architecture.md → dev-docs/hooks/architecture.md.
• Move docs/tool-output-format.md → dev-docs/tools/tool-output-format.md.
• Move docs/tool-parsing.md → dev-docs/providers/text-tool-call-parsing.md, leaving behind a small user-facing page in docs/ covering only the enableTextToolCallParsing/textToolCallModels settings and /toolformat usage/troubleshooting.
• Move docs/merge-notes/batch21-25-skipped.md → dev-docs/merge-notes/2026-01-06-batches21-25-skipped.md.
• Move docs/plans/2026-01-03-welcome-onboarding.md → dev-docs/plans/archive/2026-01-03-welcome-onboarding.md.
• Create the new dev-docs/ subdirectories as needed; update or add redirects for every inbound link (e.g., docs/message-bus.md's cross-link to the architecture doc, and any docs/index.md/section indexes referencing moved pages). Remove now-empty docs/architecture/, docs/merge-notes/, docs/plans/ directories.

Task 2: Split mixed user/internal material in high-traffic user pages

Rewrite pages to lead with user tasks and push internals to dev-docs/.

• docs/agent-api.md: retain supported imports, lifecycle, configuration, events, errors, disposal, stability, and examples; move issue/requirement IDs (PLAN-*, REQ-*, #2204 A2A follow-up, package-trim sequencing) and future work to dev-docs/; split the remaining large page by user task.
• docs/deployment.md: keep supported 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, implementation security algorithm, and performance internals to the relocated dev-docs/architecture/message-bus.md.
• docs/todo-system.md: lead with user-visible behavior and controls; move model-facing tool schemas and complexity heuristics to internal tool documentation.
• docs/tools/mcp-server.md: rebuild in task order (add → authenticate → verify → use → restrict trust → troubleshoot → remove); deduplicate the repeated "MCP Prompts as Slash Commands" and server-management sections; move "Discovery Process Deep Dive" and "Tool Execution Flow" internals to dev-docs/.
• docs/core/memport.md: keep import syntax, path rules, safety, examples, errors, troubleshooting; move internal function/type and cross-product comparison material to dev-docs/.

Task 3: Rewrite release-note and migration pages around readers and supported actions

Reorient records that currently foreground internal bookkeeping.

• docs/release-notes/2025Q4.md: reorganize by user-visible changes, affected users, compatibility, required actions, security impact, and valid migration links; remove plan markers/internal names/doc-production status.
• docs/migration/stateless-provider-v2.md: remove the @plan:/@requirement: bookkeeping metadata and plan-ID prose; add affected versions, prerequisites, before/after, verification, and rollback; keep in docs/ only if its imports are supported public contracts (otherwise relocate to dev-docs/).
• docs/migration/approval-mode-to-policies.md: replace the Phase 1/2/3 rollout framing and build-version gating with a current-state user migration (affected users, minimal steps, examples, verification, rollback).

🤖 Prompt for AI agents

Implement Phase 2 (Audience and Placement, P1): relocate misplaced internal
documents into `dev-docs/` and rewrite/split user-facing pages so they lead with
reader outcomes while moving internals out. All tasks enforce the `docs/` (user)
vs `dev-docs/` (internal) audience boundary.

1. Relocate six misplaced internal documents with inbound-link updates:
- Move `docs/architecture/message-bus-architecture.md` →
`dev-docs/architecture/message-bus.md`.
   - Move `docs/hooks/architecture.md` → `dev-docs/hooks/architecture.md`.
   - Move `docs/tool-output-format.md` → `dev-docs/tools/tool-output-format.md`.
- Move `docs/tool-parsing.md` → `dev-docs/providers/text-tool-call-parsing.md`,
leaving a small user-facing page in `docs/` covering only
`enableTextToolCallParsing`/`textToolCallModels` settings and `/toolformat`
usage/troubleshooting.
- Move `docs/merge-notes/batch21-25-skipped.md` →
`dev-docs/merge-notes/2026-01-06-batches21-25-skipped.md`.
- Move `docs/plans/2026-01-03-welcome-onboarding.md` →
`dev-docs/plans/archive/2026-01-03-welcome-onboarding.md`.
- Create new `dev-docs/` subdirectories as needed. Update/add redirects for
every inbound link (e.g., `docs/message-bus.md`'s cross-link, and section
indexes referencing moved pages). Remove now-empty `docs/architecture/`,
`docs/merge-notes/`, `docs/plans/` directories.

2. Split mixed user/internal material in high-traffic user pages:
- `docs/agent-api.md`: retain supported imports, lifecycle, configuration,
events, errors, disposal, stability, examples; move issue/requirement IDs
(`PLAN-*`, `REQ-*`, `#2204` A2A follow-up, package-trim sequencing) and future
work to `dev-docs/`; split the remaining large page by user task.
- `docs/deployment.md`: keep supported 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, implementation security algorithm, and
performance internals to the relocated `dev-docs/architecture/message-bus.md`.
- `docs/todo-system.md`: lead with user-visible behavior and controls; move
model-facing tool schemas and complexity heuristics to internal tool
documentation.
- `docs/tools/mcp-server.md`: rebuild content in task order (add → authenticate
→ verify → use → restrict trust → troubleshoot → remove); deduplicate repeated
"MCP Prompts as Slash Commands" and server-management sections; move "Discovery
Process Deep Dive" and "Tool Execution Flow" internals to `dev-docs/`.
- `docs/core/memport.md`: keep import syntax, path rules, safety, examples,
errors, troubleshooting; move internal function/type and cross-product
comparison material to `dev-docs/`.

3. Rewrite release-note and migration pages:
- `docs/release-notes/2025Q4.md`: reorganize by user-visible changes, affected
users, compatibility, required actions, security impact, and valid migration
links; remove plan markers/internal names/doc-production status.
- `docs/migration/stateless-provider-v2.md`: remove `@plan:`/`@requirement:`
bookkeeping metadata and plan-ID prose; add affected versions, prerequisites,
before/after, verification, and rollback; keep in `docs/` only if imports are
supported public contracts, otherwise relocate to `dev-docs/`.
- `docs/migration/approval-mode-to-policies.md`: replace Phase 1/2/3 rollout
framing and build-version gating with a current-state user migration (affected
users, minimal steps, examples, verification, rollback).

Phase 3: Consistency and Prevention (P2)

Introduce standards and automation so the audited issues do not recur, and finish the smaller consolidation/perspective fixes. Grouped because these are cross-cutting, prevention-oriented changes.

Task 1: Canonicalize duplicated keyboard, hooks, and MCP material

Ensure one canonical source per subject.

• Consolidate keyboard shortcuts around the generated docs/keyboard-shortcuts.md; delete or replace the stale, unreferenced docs/cli/keyboard-shortcuts.md with a redirect/stub (do not add a second generator target).
• Consolidate the overlapping hook tutorials docs/hooks/creating-custom-hooks.md and docs/hooks/writing-hooks.md into one canonical tutorial and cross-links, removing duplicated security/audit examples.
• Confirm MCP deduplication from Task 2.2 leaves a single canonical section per topic.

Task 2: Apply smaller user-perspective and freshness fixes

Complete the remaining lower-priority content corrections.

• Extract the "API Usage (For Developers)" section from docs/debug-logging.md and the "Implementation Details" source-file references from docs/multiline-input.md into dev-docs/.
• docs/cli/retry-settings.md: keep user settings/observable behavior; move the packages/core/src/utils/retry.ts implementation pointer to dev-docs/.
• docs/cli/index.md: replace residual package-layout framing with task-oriented navigation.
• docs/sandbox.md: replace absolute/sensational claims ("nearly impossible", pervasive "always"/"never") with a neutral threat model, explicit boundaries, platform limitations, and verification steps.
• docs/providers/quick-reference.md: split into a scannable setup reference and freshness-owned model/pricing guidance; add an "as of" date and owner to the pricing table (or link to provider-maintained data).

Task 3: Add recursive link checking in CI

Prevent future broken repository-relative links.

• Add a lychee-based GitHub Actions workflow under .github/workflows/ that recursively scans docs/ and dev-docs/, reusing the existing .lycheeignore (reference the AUDIT.md note as the previously-skipped source).
• Ensure the workflow fails on broken internal links so the "no broken repo-relative link" acceptance criterion is enforced going forward.

Task 4: Adopt the documentation style guide and review checklist

Codify audience/placement/writing standards for contributors.

• Add the proposed style guide (audience & placement policy, user-focused writing, tone, standard structures, maintenance rules) to contributor-visible documentation, e.g. a new dev-docs/documentation-style-guide.md, and reference it from CONTRIBUTING.md.
• Add a docs review checklist (covering audience, placement, public-contract status, task-first structure, security claims, links, and duplication), mirroring the structure of the existing code-review checklist in dev-docs/RULES.md.

🤖 Prompt for AI agents

Implement Phase 3 (Consistency and Prevention, P2): introduce standards and
automation to prevent recurrence of the audited issues, and complete remaining
smaller consolidation/perspective fixes. These are cross-cutting,
prevention-oriented changes.

1. Canonicalize duplicated keyboard, hooks, and MCP material:
- Consolidate keyboard shortcuts around the generated
`docs/keyboard-shortcuts.md`; delete or replace the stale, unreferenced
`docs/cli/keyboard-shortcuts.md` with a redirect/stub; do not add a second
generator target.
- Consolidate overlapping hook tutorials `docs/hooks/creating-custom-hooks.md`
and `docs/hooks/writing-hooks.md` into one canonical tutorial with cross-links,
removing duplicated security/audit examples.
- Confirm MCP deduplication from the Phase 2 mcp-server task leaves a single
canonical section per topic.

2. Apply smaller user-perspective and freshness fixes:
- Extract the "API Usage (For Developers)" section from `docs/debug-logging.md`
and the "Implementation Details" source-file references from
`docs/multiline-input.md` into `dev-docs/`.
- `docs/cli/retry-settings.md`: keep user settings/observable behavior; move the
`packages/core/src/utils/retry.ts` implementation pointer to `dev-docs/`.
- `docs/cli/index.md`: replace residual package-layout framing with
task-oriented navigation.
- `docs/sandbox.md`: replace absolute/sensational claims ("nearly impossible",
pervasive "always"/"never") with a neutral threat model, explicit boundaries,
platform limitations, and verification steps.
- `docs/providers/quick-reference.md`: split into a scannable setup reference
and freshness-owned model/pricing guidance; add an "as of" date and owner to the
pricing table (or link to provider-maintained data).

3. Add recursive link checking in CI:
- Add a lychee-based GitHub Actions workflow under `.github/workflows/` that
recursively scans `docs/` and `dev-docs/`, reusing the existing `.lycheeignore`
(reference the AUDIT.md note about the previously-skipped upstream
lychee-action).
- Ensure the workflow fails on broken internal links, enforcing the "no broken
repo-relative link" acceptance criterion going forward.

4. Adopt the documentation style guide and review checklist:
- Add the proposed style guide (audience & placement policy, user-focused
writing, tone, standard structures, maintenance rules) as contributor-visible
documentation, e.g. a new `dev-docs/documentation-style-guide.md`, and reference
it from `CONTRIBUTING.md`.
- Add a docs review checklist (covering audience, placement, public-contract
status, task-first structure, security claims, links, and duplication),
mirroring the structure of the existing code-review checklist in
`dev-docs/RULES.md`.

Research

Documentation lives in two trees: docs/ (77 Markdown files, user-facing, reviewed and shipped) and dev-docs/ (22 flat Markdown files, internal runbooks). .coderabbit.yaml codifies the audience split (docs/=shipped, dev-docs/=internal runbooks, project-plans/=planning/tracking). Two generator scripts (scripts/generate-keybindings-doc.ts → docs/keyboard-shortcuts.md; scripts/generate-settings-doc.ts → docs/cli/configuration.md) own AUTOGEN-marked sections. There is no markdownlint or link-check CI today, though an orphaned .lycheeignore and an AUDIT.md note (upstream lychee-action was skipped) exist. Telemetry behavior is defined in packages/core/src/config/configConstructor.ts and packages/telemetry/src/telemetry/sdk.ts, which show telemetry is genuinely functional (local/file-only; network exporters intentionally disabled) when telemetry.enabled: true — contradicting the current docs.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1 (Correctness and Safety, P0): fix documentation defects that
mislead or endanger users via content-only edits to specific pages plus repair
of confirmed broken repository-relative links.

1. Rewrite `docs/Uninstall.md`:
- Lead with the supported LLxprt install/uninstall channels (global npm: `npm
uninstall -g `@vybestack/llxprt-code``); use "LLxprt Code" in prose and `llxprt`
in commands.
- Reframe npx shared-cache clearing as an optional troubleshooting step only,
with an explicit warning that it deletes unrelated packages; do not present it
as the default uninstall path.
- Remove `gemini-cli` framing except where required to explain shared-cache
behavior, with that caveat clarified.

2. Rewrite `docs/telemetry.md`:
- State the real, verified behavior: `telemetry.enabled: true` (via
settings.json or deprecated CLI flags) starts a working local pipeline;
network/OTLP exporters are intentionally disabled; output goes to file/console
only.
- Provide a minimal enable → verify → disable flow covering scope, persistence,
default value (`false`), CLI-over-settings precedence, and output location.
- Reconcile with `docs/telemetry-privacy.md` by distinguishing OTEL telemetry
from the separate `/logging` conversation-logging feature.
- Move remaining re-enable/network internals or engineering rationale to
`dev-docs/`.

3. Repair `docs/hooks/best-practices.md`:
- Delete the orphaned JavaScript `Promise.all` fragment that renders outside a
code fence, located before the "Using Hooks Securely" heading.
- Fix the broken `../hooks-design.md` link by retargeting to an existing doc
(e.g., `./architecture.md`) or removing the dangling reference.
- Merge duplicated security guidance ("Security considerations" vs "Authoring
Secure Hooks", repeated `SECRET_PATTERNS`/`containsSecret`) into one section,
linking to `docs/hooks/api-reference.md` instead of repeating schemas.
- Preserve the `#using-hooks-securely` anchor since `docs/extension.md` links to
it.

4. Fix broken relative links:
- In `docs/release-notes/2025Q4.md`, replace the reference to non-existent
`docs/release-notes/stateless-provider.md` with
`../migration/stateless-provider-v2.md`.
- In `docs/cli/profiles.md`, fix the link to non-existent `./sandboxing.md` by
retargeting to `../sandbox.md` or `./sandbox-profiles.md`.
===============================================================================

Task: 2

Implement Phase 2 (Audience and Placement, P1): relocate misplaced internal
documents into `dev-docs/` and rewrite/split user-facing pages so they lead with
reader outcomes while moving internals out. All tasks enforce the `docs/` (user)
vs `dev-docs/` (internal) audience boundary.

1. Relocate six misplaced internal documents with inbound-link updates:
- Move `docs/architecture/message-bus-architecture.md` →
`dev-docs/architecture/message-bus.md`.
   - Move `docs/hooks/architecture.md` → `dev-docs/hooks/architecture.md`.
   - Move `docs/tool-output-format.md` → `dev-docs/tools/tool-output-format.md`.
- Move `docs/tool-parsing.md` → `dev-docs/providers/text-tool-call-parsing.md`,
leaving a small user-facing page in `docs/` covering only
`enableTextToolCallParsing`/`textToolCallModels` settings and `/toolformat`
usage/troubleshooting.
- Move `docs/merge-notes/batch21-25-skipped.md` →
`dev-docs/merge-notes/2026-01-06-batches21-25-skipped.md`.
- Move `docs/plans/2026-01-03-welcome-onboarding.md` →
`dev-docs/plans/archive/2026-01-03-welcome-onboarding.md`.
- Create new `dev-docs/` subdirectories as needed. Update/add redirects for
every inbound link (e.g., `docs/message-bus.md`'s cross-link, and section
indexes referencing moved pages). Remove now-empty `docs/architecture/`,
`docs/merge-notes/`, `docs/plans/` directories.

2. Split mixed user/internal material in high-traffic user pages:
- `docs/agent-api.md`: retain supported imports, lifecycle, configuration,
events, errors, disposal, stability, examples; move issue/requirement IDs
(`PLAN-*`, `REQ-*`, `#2204` A2A follow-up, package-trim sequencing) and future
work to `dev-docs/`; split the remaining large page by user task.
- `docs/deployment.md`: keep supported 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, implementation security algorithm, and
performance internals to the relocated `dev-docs/architecture/message-bus.md`.
- `docs/todo-system.md`: lead with user-visible behavior and controls; move
model-facing tool schemas and complexity heuristics to internal tool
documentation.
- `docs/tools/mcp-server.md`: rebuild content in task order (add → authenticate
→ verify → use → restrict trust → troubleshoot → remove); deduplicate repeated
"MCP Prompts as Slash Commands" and server-management sections; move "Discovery
Process Deep Dive" and "Tool Execution Flow" internals to `dev-docs/`.
- `docs/core/memport.md`: keep import syntax, path rules, safety, examples,
errors, troubleshooting; move internal function/type and cross-product
comparison material to `dev-docs/`.

3. Rewrite release-note and migration pages:
- `docs/release-notes/2025Q4.md`: reorganize by user-visible changes, affected
users, compatibility, required actions, security impact, and valid migration
links; remove plan markers/internal names/doc-production status.
- `docs/migration/stateless-provider-v2.md`: remove `@plan:`/`@requirement:`
bookkeeping metadata and plan-ID prose; add affected versions, prerequisites,
before/after, verification, and rollback; keep in `docs/` only if imports are
supported public contracts, otherwise relocate to `dev-docs/`.
- `docs/migration/approval-mode-to-policies.md`: replace Phase 1/2/3 rollout
framing and build-version gating with a current-state user migration (affected
users, minimal steps, examples, verification, rollback).
===============================================================================

Task: 3

Implement Phase 3 (Consistency and Prevention, P2): introduce standards and
automation to prevent recurrence of the audited issues, and complete remaining
smaller consolidation/perspective fixes. These are cross-cutting,
prevention-oriented changes.

1. Canonicalize duplicated keyboard, hooks, and MCP material:
- Consolidate keyboard shortcuts around the generated
`docs/keyboard-shortcuts.md`; delete or replace the stale, unreferenced
`docs/cli/keyboard-shortcuts.md` with a redirect/stub; do not add a second
generator target.
- Consolidate overlapping hook tutorials `docs/hooks/creating-custom-hooks.md`
and `docs/hooks/writing-hooks.md` into one canonical tutorial with cross-links,
removing duplicated security/audit examples.
- Confirm MCP deduplication from the Phase 2 mcp-server task leaves a single
canonical section per topic.

2. Apply smaller user-perspective and freshness fixes:
- Extract the "API Usage (For Developers)" section from `docs/debug-logging.md`
and the "Implementation Details" source-file references from
`docs/multiline-input.md` into `dev-docs/`.
- `docs/cli/retry-settings.md`: keep user settings/observable behavior; move the
`packages/core/src/utils/retry.ts` implementation pointer to `dev-docs/`.
- `docs/cli/index.md`: replace residual package-layout framing with
task-oriented navigation.
- `docs/sandbox.md`: replace absolute/sensational claims ("nearly impossible",
pervasive "always"/"never") with a neutral threat model, explicit boundaries,
platform limitations, and verification steps.
- `docs/providers/quick-reference.md`: split into a scannable setup reference
and freshness-owned model/pricing guidance; add an "as of" date and owner to the
pricing table (or link to provider-maintained data).

3. Add recursive link checking in CI:
- Add a lychee-based GitHub Actions workflow under `.github/workflows/` that
recursively scans `docs/` and `dev-docs/`, reusing the existing `.lycheeignore`
(reference the AUDIT.md note about the previously-skipped upstream
lychee-action).
- Ensure the workflow fails on broken internal links, enforcing the "no broken
repo-relative link" acceptance criterion going forward.

4. Adopt the documentation style guide and review checklist:
- Add the proposed style guide (audience & placement policy, user-focused
writing, tone, standard structures, maintenance rules) as contributor-visible
documentation, e.g. a new `dev-docs/documentation-style-guide.md`, and reference
it from `CONTRIBUTING.md`.
- Add a docs review checklist (covering audience, placement, public-contract
status, task-first structure, security claims, links, and duplication),
mirroring the structure of the existing code-review checklist in
`dev-docs/RULES.md`.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!