---
name: kodadocs-docs-audit
description: "Audit documentation freshness by comparing routes, screenshots, and articles against the current codebase, then generate a prioritized report with auto-fix support."
---

# Documentation Freshness Audit

## Overview

This skill performs a comprehensive audit of your KodaDocs documentation site by comparing the current state of your codebase against the last generated documentation. It detects missing documentation for new routes, orphaned documentation for removed routes, stale screenshots that no longer match the UI, and articles that reference outdated content. The audit produces a prioritized report with actionable recommendations and supports a `--fix` mode that auto-regenerates stale content.

Use this skill when:
- You suspect documentation has drifted from the current codebase
- You have added new pages or features and want to verify coverage
- You are preparing for a release and need to ensure docs are current
- You want a periodic health check on your documentation site
- You want to auto-fix stale screenshots and regenerate outdated articles
- You are onboarding contributors and want to identify documentation gaps

## Prerequisites

Before running this skill, ensure the following:

1. **Existing doc site:** A KodaDocs doc site must have been generated at least once. The manifest file `.kodadocs/run_manifest.json` must exist.
2. **Git repository:** The project must be a git repository with commit history. This is required for screenshot freshness checks and change detection.
3. **KodaDocs MCP tools available:** The `mcp__kodadocs__*` tools must be accessible.
4. **Application running (for --fix mode):** If `--fix` mode is requested and screenshots need re-capture, the application should be running at an accessible URL.

## Workflow

### Step 1: Load Existing Documentation State

Load the current manifest to understand what documentation exists and when it was last generated.

**Load the manifest:**
```
Call mcp__kodadocs__load_manifest with:
  project_path: "<project-root>"
```

**Extract from the manifest:**
- `articles` — the list of existing documentation articles (title, slug, content, route)
- `discovered_routes` — the route list from the last pipeline run
- `screenshots_dir` — the directory containing captured screenshots
- `output_dir` — the VitePress output directory
- `last_commit_sha` — the commit at which docs were last generated
- `last_run_timestamp` — when the last pipeline run occurred
- `project_name`, `brand_color`, `logo_path`, `product_summary` — site configuration

**If the manifest does not exist:**
Stop immediately and inform the user: "No previous documentation run found. Run the full KodaDocs pipeline first to establish a baseline before auditing."

**If the manifest is missing expected fields:**
Log which fields are missing. Use sensible defaults where possible (e.g., assume `last_commit_sha` is the oldest commit if not stored). Warn: "Manifest appears to be from an older version. Some audit checks may be limited."

### Step 2: Discover Current Routes

Run route discovery against the current codebase to get the live route list.

**Call route discovery:**
```
Call mcp__kodadocs__discover_routes with:
  project_path: "<project-root>"
```

This returns:
- `discovered_routes` — current routes in the codebase
- `route_metadata` — metadata about each route (file path, dynamic segments, etc.)
- `detected_services` — external services and integrations
- `ui_components` — components found in the project
- `deployment_platform` — detected hosting platform

**Store the result as `current_routes`.** This will be compared against the manifest's `discovered_routes` (referred to as `manifest_routes`).

**Framework-aware route interpretation:**

The route discovery output must be interpreted in the context of the project's framework. Different frameworks have different routing conventions:

| Framework | Route Source | Dynamic Segment Format | Notes |
|-----------|-------------|----------------------|-------|
| Next.js (App Router) | `app/` directory | `[param]`, `[...slug]` | Layouts affect child routes; `route.ts` files are API routes |
| Next.js (Pages Router) | `pages/` directory | `[param]` | `_app.tsx` and `_document.tsx` are not routes |
| SvelteKit | `src/routes/` directory | `[param]` | `+page.svelte` defines a route; `+layout.svelte` is not a route |
| Nuxt | `pages/` directory | `[param]` | Auto-imported; `layouts/` are not routes |
| Django | `urls.py` files | `<param>` | Multiple `urls.py` across apps; `include()` chains |
| React Router | Router config files | `:param` | Routes defined in code, not filesystem |
| Rails | `config/routes.rb` | `:param` | `resources` generates multiple routes |
| WordPress | Database + theme | Permalink structure | Routes are dynamic, detected via crawling |

Use the framework context to properly normalize route names when comparing manifest routes against current routes. For example, `/dashboard/[id]` and `/dashboard/:id` should be treated as the same route.

### Step 3: Compare Route Lists

Perform a set comparison between `manifest_routes` and `current_routes` to identify discrepancies.

**Compute three sets:**

1. **New routes** = routes in `current_routes` but NOT in `manifest_routes`
   These are routes that have been added since documentation was last generated. They have no corresponding articles or screenshots.

2. **Removed routes** = routes in `manifest_routes` but NOT in `current_routes`
   These are routes that no longer exist in the codebase. Any articles or screenshots for them are orphaned.

3. **Unchanged routes** = routes present in BOTH `current_routes` and `manifest_routes`
   These exist in both the code and the documentation. They may still be stale if the underlying code has changed.

**Normalization before comparison:**
- Strip trailing slashes from all routes
- Normalize dynamic segments to a common format (e.g., treat `[id]`, `:id`, and `<id>` as equivalent)
- Ignore case differences (e.g., `/Dashboard` vs `/dashboard`)
- Ignore query parameters (e.g., `/search?q=` is the same as `/search`)

**For each new route, determine its significance:**

Check the route file to assess whether it is a user-facing page that warrants documentation:
```bash
# Get the file that defines the route (from route_metadata)
# Check its content to determine if it is a meaningful page
```

Skip routes that are:
- API endpoints (`/api/*`) unless the project is an API-only project
- Internal/admin routes (`/admin/*`, `/_internal/*`) unless explicitly included
- Error pages (`/404`, `/500`) unless they have custom content
- Redirect-only routes (no meaningful content)

**For each removed route, check if the article exists:**

Cross-reference the removed route against the `articles` list in the manifest. If an article references a removed route (by slug, route path, or screenshot filename), it is an orphaned article.

### Step 4: Check Screenshot Freshness

Determine whether existing screenshots still reflect the current state of the UI by comparing file modification dates against code changes.

**For each route in `unchanged_routes`, check whether its screenshot is stale:**

**Step 4a: Identify the screenshot file for each route.**

Screenshots are stored in the `screenshots_dir` from the manifest. The filename typically corresponds to the route path (e.g., `/dashboard` -> `dashboard.png`, `/settings/profile` -> `settings-profile.png`).

List all screenshot files:
```bash
ls -la <screenshots_dir>/*.png 2>/dev/null
```

Map each screenshot file to its corresponding route.

**Step 4b: Determine when the route's code was last modified.**

For each route, find the source file(s) that define it (from `route_metadata` or by framework convention). Then check the git history for those files:

```bash
# Get the last modification date of the route's source file
git log -1 --format="%ai" -- <route-source-file>
```

Also check for changes to shared components that the route imports:

```bash
# Get imports used by the route file
# Then check git log for each imported component
git log -1 --format="%ai" -- <component-file>
```

**Step 4c: Compare timestamps.**

For each route, compare `screenshot_mtime` (file modification time via `stat`) against `code_last_modified` (most recent git commit date touching the route file or its imported components):
- `code_last_modified` > `screenshot_mtime`: screenshot is **STALE**
- `code_last_modified` <= `screenshot_mtime`: screenshot is **CURRENT**
- Screenshot file does not exist: screenshot is **MISSING**

**Step 4d: Check for global style and layout changes.**

Global style changes (`*.css`, `*.scss`, `tailwind.config.*`, `postcss.config.*`, `theme.*`) affect ALL screenshots. Check their last modification date via `git log -1 --format="%ai"`. If changed after the last run, mark all screenshots as potentially stale at INFO level.

Layout files affect all child routes that use them. Check framework-specific layout files:
- Next.js App Router: `app/layout.tsx`, `app/<segment>/layout.tsx`
- Next.js Pages Router: `pages/_app.tsx`, `pages/_document.tsx`
- SvelteKit: `src/routes/+layout.svelte`, nested `+layout.svelte`
- Nuxt: `layouts/default.vue`, `layouts/<name>.vue`
- Django: `templates/base.html`, template inheritance chain
- Rails: `app/views/layouts/application.html.erb`

If a layout file changed, mark all child routes' screenshots as STALE at WARNING level.

### Step 5: Check Article Content Freshness

Beyond screenshots, check whether article text content is still accurate by analyzing code changes that affect documented behavior.

**Step 5a: Identify articles referencing specific code elements.**

For each article in the manifest, scan its content for:
- References to function names, class names, or variable names
- Code blocks or inline code snippets
- Feature descriptions tied to specific routes or components
- Screenshot references (image paths or filenames)

**Step 5b: Check for broken screenshot references.**

Scan each article's markdown content for image references:
```
Search for patterns:
  ![...](...)
  <img src="..."
```

For each image reference found:
- Does the referenced file still exist in `screenshots_dir`?
- If the route was removed, the screenshot may have been deleted or is orphaned
- If the screenshot was re-captured with a different filename, the reference is broken

**Step 5c: Check for renamed or restructured routes.**

For each removed route, check if a new route shares the same leaf segment (e.g., `/settings` removed and `/account/settings` added both end in "settings"). Flag matches as POSSIBLE_RENAME with a recommendation to update the existing article to reference the new route path.

**Step 5d: Check data model changes.**

If the project uses Prisma, Drizzle, or another ORM, check whether data models have changed:

```
Call mcp__kodadocs__analyze_codebase with:
  project_path: "<project-root>"
```

Compare the `data_models` from the analysis against any model references in existing articles. If a model field was added, removed, or renamed, articles describing forms or data displays for that model may be outdated.

### Step 6: Generate Priority Report

Compile all findings into a structured, prioritized report.

**Priority levels:**

| Priority | Label | Criteria | Example |
|----------|-------|----------|---------|
| CRITICAL | Missing documentation | New user-facing route has no article or screenshot | New `/billing` page added but not documented |
| CRITICAL | Broken references | Article references a screenshot or route that no longer exists | Article links to `/old-feature` which was deleted |
| WARNING | Stale screenshots | Screenshot was captured before the route's code was last modified | `/dashboard` screenshot is 3 weeks older than the latest dashboard code change |
| WARNING | Orphaned documentation | Article exists for a route that was removed from the codebase | Article for `/legacy-settings` but route no longer exists |
| WARNING | Stale article content | Data models or key code elements referenced in an article have changed | Article describes a form with 5 fields but the model now has 7 |
| INFO | Layout drift | Global styles or layout files changed since last capture | `tailwind.config.js` was modified; all screenshots may have minor visual differences |
| INFO | Possible route rename | A removed route has a similar new route, suggesting a rename | `/settings` removed, `/account/settings` added |
| INFO | Minor component changes | A shared component changed but it affects only styling or non-functional elements | Icon component updated; visual change only |

**Report structure:**

The report saved to `.kodadocs/audit-report.md` must contain these sections:

1. **Header** — Project name, audit date, last doc generation timestamp, current HEAD SHA, commit count since last generation
2. **Summary table** — Issue counts by priority (CRITICAL, WARNING, INFO) and overall health status
3. **Route coverage** — Total current routes, documented routes, coverage percentage, new/removed route counts
4. **Critical issues** — Each issue with an ID (CRITICAL-001, etc.), affected route/article, source file, commit reference, recommendation, and whether it is auto-fixable
5. **Warnings** — Each issue with ID, affected route, screenshot date vs code date, changed files, recommendation
6. **Info** — Each issue with ID, description, and recommendation
7. **Recommendations summary** — Numbered list of all recommendations with priority labels
8. **Estimated fix effort** — Count of auto-fixable vs manual-only issues

### Step 7: Determine Overall Health Status

Compute an overall health status based on the findings:

```
If CRITICAL count > 0:
  status = "CRITICALLY_OUTDATED"
  message = "Documentation has critical gaps. New features are undocumented or references are broken."
Else if WARNING count > 5:
  status = "STALE"
  message = "Documentation is significantly out of date. Multiple screenshots and articles need updating."
Else if WARNING count > 0:
  status = "NEEDS_ATTENTION"
  message = "Documentation is mostly current but has some areas that need updating."
Else:
  status = "HEALTHY"
  message = "Documentation is up to date. No issues found."
```

### Step 8: Save the Audit Report

Save the full report to `.kodadocs/audit-report.md`.

Update the manifest with audit metadata by calling `mcp__kodadocs__save_manifest`. Add a `last_audit` object containing: timestamp, commit SHA, health status, issue counts by priority, coverage percentage, and lists of new routes, removed routes, and stale screenshots.

### Step 9: Auto-Fix Mode (--fix)

If the user requests `--fix` mode, automatically resolve issues that can be fixed without manual intervention.

**Fixable issues (auto-resolved):**

| Issue Type | Fix Action |
|-----------|-----------|
| Missing documentation for new routes | Capture screenshots + generate new articles |
| Stale screenshots | Re-capture screenshots for affected routes |
| Broken screenshot references | Re-capture and update image paths in articles |
| Orphaned documentation | Remove orphaned articles from the article list (with confirmation) |
| Stale article content (data model changes) | Regenerate affected articles |

**Non-fixable issues (require manual review):**

| Issue Type | Why Manual |
|-----------|-----------|
| Possible route rename | Cannot determine intent; user must confirm |
| Protected articles (<!-- manual --> marker) | User has opted out of auto-regeneration |
| Articles with complex manual edits | Risk of losing custom content |
| Global style changes | May or may not affect visual appearance; user judgment needed |

**Fix workflow:**

**Step 9a: Confirm with the user.**

Present a summary of all auto-fixable issues (screenshot captures, article generations, article removals) and non-fixable issues (route renames, protected articles, global style changes). Ask for explicit confirmation before proceeding. Note that screenshot capture requires the application to be running.

**Step 9b: Capture screenshots for new and stale routes.**

Combine the list of new routes and stale routes into a single capture batch:

```
Call mcp__kodadocs__capture_screenshots with:
  routes: [<new routes> + <stale routes>]
  app_url: "<application URL>"
  auth: <auth config from manifest, or null>
  output_dir: "<screenshots_dir from manifest>"
  blur_pii: true
```

If the application is not running:
- Warn: "Application not accessible at <url>. Cannot re-capture screenshots."
- Offer to proceed with article-only fixes (skip screenshot-dependent issues)
- Offer to abort the fix entirely

**Step 9c: Analyze the codebase for new article generation.**

```
Call mcp__kodadocs__analyze_codebase with:
  project_path: "<project-root>"
  discovered_routes: [<new routes that need articles>]
```

Use the analysis results to generate accurate, context-aware articles for new routes.

**Step 9d: Generate new articles for undocumented routes.**

For each new route, generate an article following the same style and structure as existing articles in the manifest. The article should include:
- A descriptive title derived from the route name and page content
- Step-by-step instructions for using the page
- References to the newly captured screenshot
- Context from the codebase analysis (data models, error patterns, components)

**Step 9e: Regenerate stale articles.**

For routes where the article content references outdated code elements (changed data models, renamed functions, removed features):

1. Check for the `<!-- manual -->` marker. If present, SKIP and log: "Skipping protected article for <route>."
2. Check for possible manual edits (git history of the article file). If found, ask before overwriting.
3. If safe to regenerate, generate a fresh article using the same approach as new articles.

**Step 9f: Remove orphaned articles.**

For articles that reference removed routes:
1. Confirm removal with the user (list each orphaned article).
2. Remove them from the articles list.
3. Do NOT delete article files directly; they will be excluded from the next VitePress assembly.

**Step 9g: Reassemble the doc site.**

Build the complete articles list: existing unchanged articles + newly generated articles + regenerated articles (minus orphaned articles).

```
Call mcp__kodadocs__assemble_vitepress with:
  articles: [<complete updated articles list>]
  screenshots_dir: "<screenshots_dir>"
  brand_color: "<from manifest>"
  logo_path: "<from manifest or null>"
  output_dir: "<from manifest>"
  project_name: "<from manifest>"
  product_summary: "<from manifest>"
  discovered_routes: [<current full route list>]
```

**Step 9h: Update the manifest and print fix summary.**

Call `mcp__kodadocs__save_manifest` with the updated manifest including `last_audit` metadata: timestamp, commit SHA, health status set to the post-fix status, `fix_applied: true`, and counts for articles added, regenerated, removed, and screenshots captured.

Print a fix summary showing screenshots captured (new + re-captured), articles added/regenerated/removed/unchanged, remaining manual issues, coverage change (before% -> after%), and the output directory path.

## Decision Trees

### Audit Scope Assessment

```
Does .kodadocs/run_manifest.json exist?
  NO  -> "No documentation found. Run the full KodaDocs pipeline first."
         Exit immediately.
  YES -> Load manifest and proceed.

Does the manifest contain discovered_routes?
  NO  -> "Manifest is incomplete. Route comparison is not possible."
         Fall back to screenshot-only audit (check file dates).
  YES -> Proceed with full route comparison.

Does the manifest contain last_commit_sha?
  YES -> Use git diff from that SHA to HEAD for precise change detection.
  NO  -> Does it contain last_run_timestamp?
           YES -> Use git log --since=<timestamp> as approximation.
           NO  -> Compare only route lists and screenshot dates.
                  Warn: "Cannot determine change window. Audit may be less precise."
```

### New Route Classification

```
Is the new route a user-facing page?
  Check: Does it render HTML/UI content (not just JSON/API)?
  YES -> Is it a meaningful page (not a redirect, error page, or placeholder)?
           YES -> CRITICAL: Missing documentation.
           NO  -> INFO: New route detected but does not require documentation.
  NO  -> Is this an API endpoint?
           YES -> INFO: New API endpoint. Consider API reference documentation.
           NO  -> Skip. (Internal route, middleware, etc.)
```

### Removed Route Classification

```
Was the route removed from the codebase?
  YES -> Does an article exist for this route?
           YES -> WARNING: Orphaned documentation.
                  Is there a similar new route (possible rename)?
                    YES -> INFO: Possible route rename. Suggest updating the article.
                    NO  -> Recommend removing the orphaned article.
           NO  -> No action needed. The route was never documented.
  NO  -> (Route still exists; this branch should not be reached.)
```

### Screenshot Staleness Assessment

```
Does a screenshot exist for this route?
  NO  -> Is the route documented (has an article)?
           YES -> WARNING: Documented route has no screenshot.
           NO  -> (Not documented; no screenshot expected.)
  YES -> Was the route's source code modified after the screenshot was taken?
           YES -> How long ago was the code modified?
                    < 7 days   -> WARNING: Recently changed. Screenshot likely stale.
                    7-30 days  -> WARNING: Screenshot may be stale.
                    > 30 days  -> INFO: Code change is old. Screenshot might still be valid.
           NO  -> Did a shared component used by this route change?
                    YES -> WARNING: Shared component changed. Screenshot may be affected.
                    NO  -> Did global styles change?
                             YES -> INFO: Global styles changed. Minor visual drift possible.
                             NO  -> Screenshot is CURRENT. No action needed.
```

### Fix Mode Gating

```
Did the user request --fix mode?
  NO  -> Generate audit report only. Do not modify any files.
  YES -> Are there fixable issues?
           NO  -> "All issues require manual review. No auto-fixes available."
           YES -> Is the application running (for screenshot capture)?
                    YES -> Proceed with full auto-fix (screenshots + articles).
                    NO  -> Can article-only fixes be applied?
                             YES -> "App not running. Fixing articles only. Screenshots skipped."
                                    Apply article fixes. Flag screenshot issues as remaining.
                             NO  -> "App not running and all issues require screenshots. Start the app and retry."
                                    Exit without fixing.
```

### Orphaned Article Handling

```
Is the orphaned article protected (<!-- manual --> marker)?
  YES -> Do NOT remove. Flag as: "Protected orphaned article. Manual review required."
  NO  -> Was the article manually edited (git history check)?
           YES -> Ask user: "Article for /removed-route was manually edited. Remove anyway?"
                  User says YES -> Remove from article list.
                  User says NO  -> Keep and flag as: "Orphaned but preserved by user request."
           NO  -> Safe to remove in --fix mode. Remove from article list.
```

### Coverage Threshold Evaluation

```
What is the documentation coverage percentage?
  100%    -> HEALTHY. All routes are documented.
  80-99%  -> NEEDS_ATTENTION. Most routes are documented but some gaps exist.
  50-79%  -> STALE. Significant documentation gaps.
  < 50%   -> CRITICALLY_OUTDATED. Most routes lack documentation.
             Recommend a full pipeline regeneration rather than incremental fixes.
```

## Output Format

The skill produces:

1. **Audit report** (`.kodadocs/audit-report.md`) — A comprehensive markdown report with all findings, organized by priority
2. **Console summary** — A brief summary printed to the terminal with issue counts and health status
3. **Updated manifest** — The manifest updated with audit metadata (timestamp, health status, issue counts)
4. **Fixed doc site (--fix mode only)** — Reassembled VitePress site with new and regenerated articles and screenshots

**Console summary format (audit only):**

```
Documentation Audit Complete:
  Project: <project_name>
  Routes: <current_count> current, <documented_count> documented
  Coverage: <percentage>%
  Issues: CRITICAL: <n>, WARNING: <n>, INFO: <n>
  Overall health: <status>
  Report: .kodadocs/audit-report.md
  Run with --fix to auto-resolve <n> of <total> issues.
```

**Console summary format (--fix mode):**

```
Documentation Audit + Auto-Fix Complete:
  Issues resolved: <n> of <total>
  Screenshots captured: <n> (new: <n>, re-captured: <n>)
  Articles: +<added> added, ~<regenerated> regenerated, -<removed> removed
  Remaining manual issues: <n>
  Coverage: <before>% -> <after>%
  Health: <before_status> -> <after_status>
  Output: <output_dir>
```

## Error Handling

### No manifest found
If `.kodadocs/run_manifest.json` does not exist:
- Stop and inform: "No previous documentation run found. Run the full KodaDocs pipeline first to establish a baseline before auditing."
- Do not attempt to audit without a baseline

### Route discovery fails
If `mcp__kodadocs__discover_routes` returns an error or empty route list:
- Check if the project path is correct
- Check if the framework is supported
- Inform: "Route discovery failed. Verify the project path and framework. Audit will proceed with screenshot freshness checks only."
- Skip route comparison (Steps 3 and 5c) and proceed with screenshot checks (Step 4) and article content checks (Step 5a, 5b)

### Git repository not available
If `git log` commands fail (not a git repo, shallow clone, corrupted history):
- Warn: "Git history is not available. Screenshot freshness checks will be limited to file modification dates only (less precise)."
- Use filesystem `stat` timestamps instead of git history
- Skip commit-based change detection entirely

### Screenshots directory missing or empty
If the `screenshots_dir` from the manifest does not exist or contains no files:
- Log: "Screenshots directory not found or empty. Skipping screenshot freshness checks."
- Proceed with route comparison and article content checks only
- If in --fix mode, create the directory and capture all screenshots fresh

### Application not running in fix mode
If `--fix` mode is requested but the application is not accessible:
- Warn: "Application not accessible at <url>. Cannot capture screenshots."
- Offer to apply article-only fixes (generate new articles, remove orphaned articles)
- Offer to abort and retry when the application is available
- Never silently skip screenshot capture without informing the user

### Manifest schema mismatch
If the manifest was created by an older KodaDocs version and is missing fields:
- Use sensible defaults for missing fields:
  - Missing `last_commit_sha`: use the earliest commit in the repo as baseline
  - Missing `screenshots_dir`: look for `.kodadocs/screenshots/` as default
  - Missing `articles`: treat as empty list (all routes are undocumented)
- Warn: "Manifest appears to be from an older version. Some audit checks were adjusted."
- After the audit (or fix), save the manifest with the current schema

### Codebase analysis fails
If `mcp__kodadocs__analyze_codebase` returns an error:
- Log: "Codebase analysis failed. Article content freshness checks for data model changes will be skipped."
- Proceed with all other audit checks
- In --fix mode, generate articles without codebase context (less detailed but still functional)

### Too many issues found
If the audit finds more than 50 issues total:
- Summarize by category rather than listing each individually
- Recommend a full pipeline regeneration: "More than 50 issues found. A full documentation regeneration is more efficient than incremental fixes."
- In --fix mode, ask for confirmation before proceeding

### Concurrent modification
Capture the HEAD SHA at the start of the audit (`git rev-parse HEAD`) and use it consistently throughout. This prevents inconsistencies if a commit is pushed mid-audit in CI environments.

### Protected article with broken references
If an article marked with `<!-- manual -->` has broken screenshot references, do NOT modify the article content. Flag as WARNING for manual review. In --fix mode, re-capture the screenshot but do NOT update image paths in the protected article.

## Success Criteria

The run is successful when:
- [ ] Manifest was loaded and parsed correctly
- [ ] Current routes were discovered via `discover_routes`
- [ ] Route comparison identified new, removed, and unchanged routes
- [ ] Screenshot freshness was checked for all documented routes
- [ ] Article content was scanned for broken references and stale content
- [ ] All findings were classified by priority (CRITICAL, WARNING, INFO)
- [ ] A structured audit report was generated and saved to `.kodadocs/audit-report.md`
- [ ] The manifest was updated with audit metadata
- [ ] Console summary was printed with issue counts and health status
- [ ] Overall health status was computed and reported
- [ ] If --fix mode: fixable issues were resolved, doc site was reassembled, and fix summary was printed
- [ ] If --fix mode: protected articles were never overwritten
- [ ] If --fix mode: user was asked for confirmation before destructive actions (removing orphaned articles)
- [ ] Coverage percentage was computed and reported before and after fixes
