@iamdangavin/claude-skill-vitepress-docs 1.0.0

package/install.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { mkdirSync, copyFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const skillName = 'vitepress-docs';
+const dest = join(homedir(), '.claude', 'skills', skillName);
+
+mkdirSync(dest, { recursive: true });
+copyFileSync(join(__dirname, 'skill', 'SKILL.md'), join(dest, 'SKILL.md'));
+
+console.log(`✓ Installed @iamdangavin/claude-skill-vitepress-docs`);
+console.log(`  → ${dest}/SKILL.md`);
+console.log(`  Invoke with: /vitepress-docs in Claude Code`);

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@iamdangavin/claude-skill-vitepress-docs",
+  "version": "1.0.0",
+  "description": "Installs the vitepress:docs Claude Code skill — VitePress docs setup, generation, screenshots, and sync.",
+  "type": "module",
+  "bin": {
+    "claude-skill-vitepress-docs": "./install.js"
+  },
+  "files": [
+    "install.js",
+    "skill/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-skill",
+    "vitepress",
+    "docs"
+  ],
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,759 @@
+---
+name: vitepress:docs
+description: VitePress documentation suite — setup GitHub Pages deployment, generate docs from a codebase, capture screenshots of any running app, and sync docs as code changes.
+argument-hint: [mode: setup|generate|screenshot|sync] or omit to be prompted
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# Skill: vitepress:docs
+
+Four modes for full VitePress documentation lifecycle. If no mode is given as an argument, use AskUserQuestion to prompt for one:
+
+- header: "vitepress:docs"
+- question: "Which mode do you need?"
+- options:
+  - "setup — Wire up VitePress + GitHub Actions for Pages deployment"
+  - "generate — Analyze the codebase and write documentation pages"
+  - "screenshot — Capture real screenshots and replace placeholders"
+  - "sync — Detect code drift and update docs that are out of date"
+
+---
+
+## Manifest
+
+All modes read and write a manifest at `.vitepress/docs-manifest.json`. This file is **local-only** — always add it to `.gitignore` (under the docs folder's nearest `.gitignore`) so it is never committed or distributed.
+
+Add this line if not already present:
+```
+.vitepress/docs-manifest.json
+```
+
+### Manifest schema
+
+```json
+{
+  "generated": "ISO-8601 timestamp",
+  "project": {
+    "type": "user-facing | developer | both",
+    "baseUrl": "http://localhost:3000",
+    "serverType": "node | wordpress | static | other",
+    "startCommand": "npm run dev"
+  },
+  "pages": [
+    {
+      "file": "docs/guides/timer.md",
+      "title": "Running a Timer",
+      "docType": "user-facing",
+      "sources": ["src/state/timer.js", "src/components/layouts/workouts.jsx"],
+      "images": [
+        {
+          "path": "docs/public/screenshots/timer-main.png",
+          "placeholder": true,
+          "caption": "Timer in active interval state",
+          "captureUrl": "/workouts/123",
+          "captureNote": "Timer should be running with intervals visible"
+        }
+      ],
+      "lastSynced": "ISO-8601 timestamp",
+      "syncHash": "sha of source file contents at last sync"
+    }
+  ]
+}
+```
+
+---
+
+## Mode: setup
+
+### Step 1 — Gather project details
+
+Use AskUserQuestion for each choice below. For freeform text inputs (repo URL, domain name, docs path) ask as plain text immediately after the relevant choice is made.
+
+**Q1 — VitePress status:**
+- header: "VitePress"
+- question: "Is VitePress already installed in this project?"
+- options:
+  - "Already installed"
+  - "Starting from scratch"
+
+**Q2 — Docs folder** (plain text): Ask — "Where do the docs live (or where should they go)? e.g. `docs/` at project root, or the repo root itself."
+
+**Q3 — GitHub repo** (plain text): Ask — "What is the GitHub repo? (full URL or `owner/repo`)"
+
+**Q4 — Domain type:**
+- header: "Hosting"
+- question: "Where will the docs be served?"
+- options:
+  - "Custom domain I own (e.g. docs.myapp.com)"
+  - "GitHub Pages subdomain (e.g. owner.github.io/repo-name)"
+
+If custom domain: ask as plain text — "What is the domain? (e.g. `docs.myapp.com`)"
+
+**Q5 — Deploy trigger:**
+- header: "Deploy trigger"
+- question: "When should docs deploy?"
+- options:
+  - "Every push to main"
+  - "Every push to a specific branch — I'll tell you which"
+  - "Only when a version tag is pushed (v*)"
+  - "Manual only (workflow_dispatch)"
+
+If specific branch: ask as plain text — "Which branch?"
+
+**Q6 — Docs on GitHub:**
+- header: "Repo state"
+- question: "Are the docs already committed and pushed to GitHub?"
+- options:
+  - "Yes, already pushed"
+  - "No, this is all new"
+
+Wait for all answers before proceeding.
+
+### Step 2 — Prerequisites checklist
+
+Present the relevant checklist as plain text, then use AskUserQuestion to confirm before writing files:
+
+- header: "Ready to proceed?"
+- question: "Have you completed the steps above?"
+- options:
+  - "Yes, all done — generate the files"
+  - "Not yet — I need more time"
+  - "I have a question"
+
+If "Not yet": tell the user to run `/vitepress:docs setup` again when ready and exit.
+If "I have a question": answer it, then re-ask this question.
+
+The checklist to present (tailor to their answers):
+
+**Always required:**
+- [ ] GitHub repo exists with push access
+- [ ] In repo **Settings → Pages**, set Source to **"GitHub Actions"**
+  _(You do not need to configure anything else here — the workflow handles the entire deployment. Just flip the source and leave everything else alone.)_
+
+**If custom domain:**
+- [ ] CNAME DNS record: `docs.yourdomain.com` → `<owner>.github.io`
+- [ ] In repo **Settings → Pages → Custom domain**, enter the domain after DNS propagates
+- [ ] TLS cert will provision automatically after first deploy
+
+**If VitePress not installed:**
+- [ ] Node.js 18+ installed
+
+Before proceeding to Step 3, ask permission to handle the docs scaffold automatically:
+
+- header: "Docs scaffold"
+- question: "VitePress isn't installed yet. Can I create the docs folder and run the install for you?"
+- options:
+  - "Yes — set it up for me"
+  - "No — I'll do it myself"
+
+If yes, run:
+```bash
+mkdir -p DOCS_FOLDER
+cd DOCS_FOLDER && npm init -y && npm install -D vitepress
+```
+Then confirm it succeeded before continuing.
+If no, tell the user to run those two commands in the docs folder and come back when done.
+
+**Playwright (required for screenshot mode):**
+
+Check if it's already installed:
+```bash
+ls /opt/homebrew/lib/node_modules/playwright/index.mjs 2>/dev/null && echo "Found" || echo "Not found"
+```
+
+If not found, install it:
+```bash
+brew install playwright
+playwright install chrome
+```
+
+If the user is **not on macOS / Homebrew**, note that the screenshot mode hardcodes the Homebrew path. They'll need to find their global Playwright path (`npm root -g`) and will have to update the import line in any capture scripts the skill generates. Offer to help with that when screenshot mode is first used.
+
+### Step 3 — Generate files
+
+**`.github/workflows/docs.yml`** (at repo root, not inside docs folder):
+
+```yaml
+name: Deploy Docs
+
+on:
+  push:
+    branches: [BRANCH]        # from answer 5
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: DOCS_FOLDER/package-lock.json
+      - run: npm ci
+        working-directory: DOCS_FOLDER
+      - run: npm run build
+        working-directory: DOCS_FOLDER
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: DOCS_FOLDER/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment
+```
+
+Fill `BRANCH` and `DOCS_FOLDER` from answers. For tag-based triggers replace `branches` with `tags: ['v*']`. For manual-only, remove the `push:` block.
+
+**VitePress config updates:**
+
+Read the existing config before editing. Make only these targeted changes:
+
+1. Set `base`:
+   - Custom domain → `base: '/'`
+   - GitHub subdomain → `base: '/repo-name/'`
+
+2. Add PostCSS override if not already present. This prevents VitePress from inheriting a PostCSS config from a parent project (e.g. a Next.js or Laravel root that uses Tailwind), which would cause the Actions build to fail with a "Cannot find module" error:
+   ```js
+   vite: {
+     css: {
+       postcss: {},
+     },
+   },
+   ```
+   Always add this — it is harmless when there is no parent PostCSS config and critical when there is.
+
+**`DOCS_FOLDER/public/CNAME`** (custom domain only):
+```
+docs.yourdomain.com
+```
+
+**`.gitignore` check:** ensure `node_modules` and `.vitepress/cache` are present.
+
+### Step 4 — Summary
+
+List files written and give the user a next-steps checklist with the expected deploy URL.
+
+---
+
+## Mode: generate
+
+### Step 0 — Detect tech stack
+
+Before asking any questions, scan the codebase root for stack markers. Use Glob and Grep — do not ask the user what their stack is until you've made an attempt to detect it yourself.
+
+**WordPress indicators** — check for any of these:
+```
+wp-config.php
+wp-content/
+wp-includes/
+functions.php (in a theme directory)
+style.css with "Theme Name:" header
+composer.json with "johnpbloch/wordpress" or "roots/wordpress"
+```
+
+**Node/Next indicators:**
+```
+next.config.js / next.config.ts / next.config.mjs
+package.json with "next" dependency
+.next/ directory
+```
+
+**Other Node indicators:** `package.json`, `vite.config.*`, `astro.config.*`, `nuxt.config.*`
+
+**Static:** no package.json, no wp-config.php, only HTML/CSS/JS files.
+
+After scanning, present your finding and confirm with the user:
+
+- header: "Tech stack detected"
+- question: "I detected this as a [DETECTED_STACK] project — is that right?"
+- options:
+  - "Yes, that's correct"
+  - "No — let me tell you what it actually is"
+
+If the user corrects you, accept their answer and proceed with the corrected stack.
+
+---
+
+**If WordPress is detected**, ask the following WP-specific questions before running the git root check:
+
+**WP-Q1 — WordPress project type:**
+- header: "WordPress setup"
+- question: "What kind of WordPress project is this?"
+- options:
+  - "Traditional theme (PHP templates, The Loop, etc.)"
+  - "Block theme (Full Site Editing / Gutenberg blocks)"
+  - "Headless WordPress (REST API or WPGraphQL feeding a front-end)"
+  - "Plugin (documenting a plugin, not a theme)"
+  - "Full site — theme + plugins together"
+
+**WP-Q2 — Local dev environment** (plain text): Ask — "What URL is the WordPress site running on locally? (e.g. `http://localhost:8888`, `http://mysite.local`)"
+
+**WP-Q3 — Page builder / block editor:**
+- header: "Page builder"
+- question: "Is this site built with a page builder or block toolkit?"
+- options:
+  - "Standard Gutenberg / block editor only"
+  - "Elementor"
+  - "Divi"
+  - "ACF Blocks (Advanced Custom Fields)"
+  - "Other — I'll tell you"
+  - "No page builder — mostly PHP templates"
+
+**WP-Q4 — Key plugins to document** (plain text): Ask — "Are there any plugins that are central to how the site works and should be included in the docs? (e.g. WooCommerce, ACF, Yoast — or 'none')"
+
+**WP-Q5 — Headless front-end** (only if headless was selected in WP-Q1):
+- header: "Front-end"
+- question: "What is the headless front-end stack?"
+- options:
+  - "Next.js"
+  - "Nuxt"
+  - "SvelteKit"
+  - "Astro"
+  - "Other — I'll tell you"
+
+**WP-Q6 — Theme / plugin folder** (plain text): Scan `wp-content/themes/` and `wp-content/plugins/` for likely candidates first — present your best guess and let the user confirm or correct it. Ask — "Which theme or plugin should I focus on? (e.g. `wp-content/themes/my-theme` or `wp-content/plugins/my-plugin`)"
+
+Once WP-Q6 is answered, the **focus path** is now the theme/plugin folder — not the WP install root. All subsequent analysis, docs placement, and git root detection use this path as the base.
+
+Store all WP answers and carry them through the rest of generate mode. They affect codebase analysis (Step 2) and the doc structure proposal (Step 3).
+
+---
+
+#### Git root detection (all stacks)
+
+**For WordPress:** run this check against the theme/plugin path confirmed in WP-Q6.
+**For all other stacks:** run this check against the detected codebase root (current working directory unless corrected above).
+
+Check for a `.git` directory at **that exact path**:
+
+```bash
+ls FOCUS_PATH/.git
+```
+
+Do not check parent folders — the `.git` must be in the specific folder being documented. For WordPress this means checking inside `wp-content/themes/my-theme/` or `wp-content/plugins/my-plugin/`, not in `wp-content/themes/`, `wp-content/`, or the WP install root.
+
+**If `.git` is found at the focus path:** no question needed — the repo root and focus path are the same. Proceed.
+
+**If `.git` is not found:** ask:
+
+- header: "Git root"
+- question: "I didn't find a `.git` folder at [FOCUS_PATH]. Where is the git root for this project?"
+- options:
+  - "It's at the WP install root (the folder I was invoked from)"
+  - "It's somewhere else — I'll tell you the path"
+  - "There's no git repo yet"
+
+Then ask as plain text — "Where inside the git repo should the docs folder and VitePress config live? (Default: `docs/` inside [FOCUS_PATH].)"
+
+This matters because the GitHub Actions workflow file must go in `.github/workflows/` at the **git root**, even if the VitePress config and docs folder live deeper inside it (e.g. inside the theme or plugin subfolder).
+
+---
+
+### Step 1 — Gather project details
+
+**Q1 — Doc type:**
+- header: "Documentation type"
+- question: "What type of docs should I generate?"
+- options:
+  - "User-facing guides — how to use the app"
+  - "Developer reference — architecture, API, data layer"
+  - "Both"
+
+**Q2 — App description** (plain text): Ask — "What is this app called, and what does it do in one sentence? (Used for headings and introductions.)"
+
+**Q3 — Codebase root** (plain text): Ask — "Where is the codebase root? (Press enter to use the current directory.)" — **Skip for WordPress; already established by WP-Q6.**
+
+**Q4 — Docs output** (plain text): Ask — "Where should docs be written? (Default: `docs/` inside [FOCUS_PATH].)" — For WordPress, default to `docs/` inside the theme/plugin folder from WP-Q6, not the WP install root.
+
+**Q5 — Skip anything:**
+- header: "Exclusions"
+- question: "Anything to exclude from analysis? (node_modules, dist, .git, .next, coverage are always skipped.)"
+- options:
+  - "No, defaults are fine"
+  - "Yes — I'll tell you what to skip"
+
+If yes: ask as plain text — "Which folders or files should I skip?"
+
+Wait for all answers.
+
+### Step 2 — Analyze the codebase
+
+Scan the codebase systematically. Build a mental map before writing anything. Look for:
+
+**For user-facing docs:**
+- App routes / pages (what screens exist)
+- Key user flows (what can a user do)
+- Forms and interactive features
+- Settings and configuration surfaces
+
+**For developer docs:**
+- Entry points and routing structure
+- Data layer (API routes, DB queries, service modules)
+- State management
+- Auth and middleware
+- Reusable utilities and lib functions
+- Environment variable requirements
+
+Use Glob and Grep to find these. Do not read every file — read enough to understand what each area does.
+
+### Step 3 — Plan the doc structure
+
+Before writing any pages, output a proposed outline:
+
+Present the proposed outline as plain text, then use AskUserQuestion to confirm:
+
+- header: "Doc structure"
+- question: "Does this outline look right?"
+- options:
+  - "Looks good — start writing"
+  - "I want to make changes"
+
+If changes: ask as plain text — "What would you like to add, remove, or rename?" Then re-present the updated outline and ask again.
+
+### Step 4 — Write pages
+
+Write pages one at a time. For each page:
+
+1. Read the relevant source files
+2. Write the markdown based on what you can confidently determine
+3. Where information is unclear or missing, insert a gap comment and continue:
+   ```md
+   <!-- GAP: What are the valid values for rotation frequency? -->
+   ```
+4. Where a screenshot would help understanding, insert a placeholder image and record it in the manifest:
+   ```md
+   ![Timer in active interval state](../public/screenshots/timer-main.png)
+   ```
+   Then generate the placeholder PNG (see **Placeholder generation** below).
+
+Do not stop to ask gap questions mid-page. Keep writing and accumulate all gaps.
+
+### Step 5 — Gap review
+
+After all pages are written, present all gaps in one batch:
+
+```
+I've written all X pages. I hit N gaps where I couldn't confidently determine
+the correct information. Can you fill these in?
+
+1. [guides/timer.md] What are the valid values for rotation frequency?
+2. [developer/auth.md] Is the OAuth callback scoped to a single provider or does it support multiple?
+...
+```
+
+Go back and fill in the answers the user provides.
+
+### Step 6 — Update VitePress config sidebar
+
+Read the existing `.vitepress/config.mjs` (or `.ts`) and update the `sidebar` and `nav` to include all newly generated pages. Edit the config in place — do not rewrite unrelated sections.
+
+### Step 7 — Write the manifest
+
+Write `.vitepress/docs-manifest.json` capturing all pages, their source file mappings, image placeholder status, and a `syncHash` (SHA of source file contents at generation time — use a simple string hash if needed).
+
+Add `docs-manifest.json` to `.vitepress/` entry in `.gitignore`.
+
+### Step 8 — Summary
+
+```
+Generated X pages (Y user-facing, Z developer).
+Created N placeholder screenshots — run /vitepress:docs screenshot when ready to capture real images.
+Filled M of P gaps — X remaining gap comments left in files for manual review.
+```
+
+---
+
+## Placeholder generation
+
+When a page needs a screenshot, generate a 1200×630 grey PNG at the specified path before moving on.
+
+Try in order:
+
+**Option A — ImageMagick:**
+```bash
+convert -size 1200x630 xc:'#888888' path/to/placeholder.png
+```
+
+**Option B — Node.js (no external deps):**
+
+Write this to `/tmp/make-placeholder.mjs`, run it, then delete it:
+
+```js
+import zlib from 'zlib';
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+const W = 1200, H = 630;
+const OUTPUT = 'FILL_IN_OUTPUT_PATH';
+
+const scanlines = [];
+for (let y = 0; y < H; y++) {
+  const row = Buffer.alloc(1 + W * 3);
+  row[0] = 0;        // filter type: None
+  row.fill(0x88, 1); // grey RGB pixels
+  scanlines.push(row);
+}
+const raw = Buffer.concat(scanlines);
+const compressed = zlib.deflateSync(raw, { level: 9 });
+
+const crcTable = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let j = 0; j < 8; j++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+  crcTable[i] = c;
+}
+function crc32(buf) {
+  let c = 0xFFFFFFFF;
+  for (const b of buf) c = crcTable[(c ^ b) & 0xFF] ^ (c >>> 8);
+  return (c ^ 0xFFFFFFFF) >>> 0;
+}
+function makeChunk(type, data) {
+  const t = Buffer.from(type, 'ascii');
+  const len = Buffer.alloc(4); len.writeUInt32BE(data.length);
+  const crcVal = Buffer.alloc(4); crcVal.writeUInt32BE(crc32(Buffer.concat([t, data])));
+  return Buffer.concat([len, t, data, crcVal]);
+}
+
+const sig = Buffer.from([137,80,78,71,13,10,26,10]);
+const ihdr = Buffer.alloc(13);
+ihdr.writeUInt32BE(W, 0); ihdr.writeUInt32BE(H, 4);
+ihdr[8] = 8; ihdr[9] = 2; // 8-bit RGB
+
+mkdirSync(dirname(OUTPUT), { recursive: true });
+writeFileSync(OUTPUT, Buffer.concat([
+  sig,
+  makeChunk('IHDR', ihdr),
+  makeChunk('IDAT', compressed),
+  makeChunk('IEND', Buffer.alloc(0))
+]));
+console.log('Created', OUTPUT);
+```
+
+If both options fail, tell the user and skip the placeholder for that image — leave the `![...](path)` reference in the markdown so it renders as a broken image, making it obvious during preview.
+
+---
+
+## Mode: screenshot
+
+### Step 1 — Gather capture details
+
+**Q1 — Source:**
+- header: "Capture source"
+- question: "Where should I capture screenshots from?"
+- options:
+  - "Local dev server — I'll capture from a running server"
+  - "Deployed URL — give me the base URL"
+
+If deployed: ask as plain text — "What is the base URL? (e.g. `https://docs.myapp.com`)"
+
+**Q2 — Stack type** (only if local):
+- header: "Project type"
+- question: "What type of project is this?"
+- options:
+  - "Node/npm — you can optionally start the server for me"
+  - "WordPress, PHP, or other non-Node stack"
+  - "Static files"
+
+**Q3 — Server status** (only if local Node):
+- header: "Dev server"
+- question: "Is the dev server already running?"
+- options:
+  - "Already running"
+  - "Not running — please start it for me"
+
+If starting: ask as plain text — "What command starts it? And what URL/port does it run on?"
+
+**Q4 — Authentication:**
+- header: "Login required?"
+- question: "Does reaching the screens that need screenshots require login?"
+- options:
+  - "No — all target screens are public"
+  - "Yes — I'll provide credentials"
+
+If yes: ask as plain text — "Please provide the username and password. ⚠️ Credentials are used only to drive the browser in this session — they will NEVER be written to any file, the manifest, or anywhere outside this conversation."
+
+**Q5 — Scope:**
+- header: "Capture scope"
+- question: "Which screenshots should I capture?"
+- options:
+  - "All placeholders from the manifest"
+  - "Specific pages only — I'll tell you which"
+
+If specific: ask as plain text — "Which pages or screenshots?"
+
+Wait for all answers.
+
+### Step 2 — Find all placeholders
+
+Read `.vitepress/docs-manifest.json`. Filter to all images where `"placeholder": true`. Group by the doc page they belong to.
+
+If no manifest exists, scan all markdown files in the docs folder for images referencing `public/screenshots/` — treat all of them as needing capture.
+
+### Step 3 — Capture screenshots
+
+For each placeholder, refer to the manifest's `captureUrl` and `captureNote` fields to understand what state to capture.
+
+Use Playwright via Homebrew for all captures:
+```js
+import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
+```
+
+**⛔ Credential rule — NEVER write credentials to any file.** Do not write them to the capture script, a `.env` file, the manifest, a temp file, or anywhere else. Use them only as inline values passed directly to `page.fill()` calls in the script held in memory. Delete the script immediately after running it (`rm /tmp/screenshot.mjs`). If Playwright needs credentials in a reusable way, use a saved storage state file — but prompt the user for credentials fresh each time rather than caching them.
+
+**For pages requiring auth:** if credentials were provided, drive a login flow before navigating to the target URL. If no credentials were given, skip auth-gated pages and list them in the final summary so the user can run screenshot mode again with credentials.
+
+**Standard capture script template:**
+```js
+import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
+const browser = await chromium.launch({ channel: 'chrome', args: ['--no-sandbox'] });
+const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+await page.goto('BASE_URL + captureUrl', { waitUntil: 'load', timeout: 60000 });
+await page.waitForTimeout(2000); // settle time for SPAs
+await page.screenshot({ path: 'OUTPUT_PATH', fullPage: false });
+await browser.close();
+```
+
+Adjust settle time based on stack type. For WordPress/non-SPA sites use 500ms. For Next.js/SPA use 2000–4000ms.
+
+After each capture, display the image inline with the Read tool so the user can verify it before moving on.
+
+### Step 4 — Rewrite prose around captured images
+
+After capturing an image, go back to the doc page that references it and rewrite the paragraph or section surrounding that image. The placeholder was written with generic framing — now that you can see the actual screenshot, make the description specific and accurate.
+
+Read the screenshot with the Read tool to inform the rewrite.
+
+### Step 5 — Update manifest
+
+For each successfully captured image, update `"placeholder": false` in the manifest and record the capture timestamp.
+
+### Step 6 — Summary
+
+```
+Captured X of Y screenshots.
+  Skipped: [list any skipped with reason]
+
+Rewrote prose in X doc pages.
+
+Run /vitepress:docs sync after future code changes to keep docs current.
+```
+
+---
+
+## 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 /vitepress:docs screenshot when ready.
+```
+
+---
+
+## Notes
+
+- Never write the GitHub Actions workflow inside the docs folder — it goes in `.github/workflows/` at the repo root.
+- Always read an existing config before editing it — never rewrite the whole file.
+- For non-Node stacks in screenshot mode (WordPress, PHP, static): do not attempt to start a server. Just ask for the URL.
+- `workflow_dispatch` should always be present in the workflow so manual deploys are possible.
+- Do not use `peaceiris/actions-gh-pages` — use `actions/upload-pages-artifact` + `actions/deploy-pages`.
+- The manifest is intentionally not committed. Each environment generates its own. Don't suggest committing it.