---
name: vitedocs:sync
description: Detect code drift and update docs that are out of date.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
---

This mode reads `.vitepress/docs-manifest.json`. Run `/vitedocs:generate` first if no manifest exists yet.

---

## Mode: sync

### Step 1 — Gather sync preferences

**Q1 — Drift detection method:**
- header: "Sync method"
- question: "How should I check for drift?"
- options:
  - "Git diff — compare code changes since last sync (fast)"
  - "Full re-analysis — re-read source files and compare to docs (thorough)"
  - "Both — git diff first, then deep re-analysis on flagged pages"

**Q2 — Update style:**
- header: "Update approach"
- question: "How should I handle pages that need updating?"
- options:
  - "Update all automatically, then show me a summary"
  - "Show me each changed page and confirm before updating"

Wait for answers.

### Step 2 — Detect drift

**Git diff approach:**
```bash
git diff --name-only LAST_SYNC_COMMIT HEAD
```
Get `LAST_SYNC_COMMIT` from the manifest's `generated` timestamp — find the nearest commit at or before that time with `git log --before="TIMESTAMP" -1 --format="%H"`.

Cross-reference changed files against the manifest's `sources` arrays to find which doc pages are affected.

**Full re-analysis approach:**
For each page in the manifest, re-read the source files listed in `sources`. Compute a hash of their current contents and compare to `syncHash`. Flag any mismatch as drifted.

**Both:** run git diff first for speed, then re-analyze only the flagged pages for depth.

### Step 3 — Report drift before changing anything

```
Found N pages with drift:

  guides/timer.md         — src/state/timer.js changed (interval logic updated)
  developer/auth.md       — src/proxy.js changed (new middleware added)
  developer/api/users.md  — src/app/api/users/route.js changed (new endpoint)

Images that may need recapture:
  public/screenshots/timer-main.png — source page changed
```

If the user chose "confirm before each", use AskUserQuestion per page:
- header: "[filename]"
- question: "[source file] changed — [brief description of what changed]. Update this page?"
- options:
  - "Yes — update it"
  - "Skip this one"
  - "Update all remaining without asking"

Otherwise update all and summarize at the end.

### Step 4 — Update affected pages

For each drifted page:
1. Re-read the source files
2. Update the relevant sections in the doc
3. Add a `<!-- GAP: ... -->` comment if something is now unclear
4. If images on the page likely show outdated UI, mark them as `"placeholder": true` again in the manifest and note that they need recapture

Do not touch pages that have not drifted.

### Step 5 — Update manifest

Update `lastSynced` and `syncHash` for all updated pages. Update the top-level `generated` timestamp.

### Step 6 — Summary

```
Updated X of N drifted pages.
  X gap comments added for manual review.
  Y screenshots flagged for recapture — run /vitedocs:capture when ready.
```