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](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.