docs-audit-and-refresh

Docs Audit And Refresh

Overview

Audit docs/ from the repository outward: inspect the current implementation, identify documentation gaps or inaccuracies, and update the relevant pages. Keep the work inside docs/ and treat code, tests, and current configuration surfaces as the authoritative source.

Read references/audit-checklist.md before a broad audit so the scan stays focused on high-signal areas.

Workflow

1. Build a current-state inventory

Inspect the repository areas that define user-facing or developer-facing behavior.

• Read the relevant code, tests, schemas, and package surfaces.
• Focus on shipped behavior, stable configuration, exposed commands, integrations, and developer workflows.
• Use the existing docs tree as a map of intended coverage, not as proof that coverage is complete.

2. Compare implementation against docs/

Look for three classes of issues:

• Missing documentation for an existing feature, setting, tool, or workflow
• Incorrect documentation that contradicts the current codebase
• Stale documentation that uses old names, defaults, paths, or examples

Prefer proving a gap with repository evidence before editing. Use current code and tests instead of intuition.

3. Prioritize by reader impact

Fix the highest-cost issues first:

1. Broken onboarding, setup, auth, installation, or command flows
2. Wrong settings, defaults, paths, or feature behavior
3. Entirely missing documentation for a real surface area
4. Lower-impact clarity or organization improvements

4. Refresh the docs

Update the smallest correct set of pages under docs/.

• Edit existing pages first
• Add new pages only for clear, durable gaps
• Update the nearest _meta.ts when adding or moving pages
• Keep examples executable and aligned with the current repository structure
• Remove dead or misleading text instead of layering warnings on top

5. Validate the refresh

Before finishing:

• Search docs/ for old terminology and replaced config keys
• Check neighboring pages for conflicting guidance
• Confirm new pages appear in the right _meta.ts
• Re-read critical examples, commands, and paths against code or tests
• Verify bundled skill doc indices still match the current docs/ tree. The qc-helper bundled skill (packages/core/src/skills/bundled/qc-helper/SKILL.md) maintains a hardcoded table mapping topics to doc file paths. If you added, moved, renamed, or removed a page under docs/users/, that table must be updated to match. Check the Features and Configuration tables in the SKILL.md against the actual files in docs/users/features/ and docs/users/configuration/. Other bundled or project skills may also reference doc paths — search for docs/users/ across .qwen/skills/ and packages/core/src/skills/bundled/ to catch them.

Audit standards

• Favor breadth-first discovery, then depth on confirmed gaps.
• Do not rewrite large areas without evidence that they are wrong or missing.
• Keep README files out of scope for edits; limit changes to docs/.
• Call out residual gaps if the audit finds issues that are too large to solve in one pass.

Deliverable

Produce a focused docs refresh that makes the current repository more accurate and complete. Summarize the audited surfaces and the concrete pages updated.