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: