@iamdangavin/claude-skill-vitepress-docs 3.0.2 → 3.1.0

package/commands/vitedocs/capture.md

@@ -0,0 +1,288 @@
+---
+name: vitedocs:capture
+description: Capture screenshots and record interaction videos for VitePress docs. Uploads videos to GitHub Releases.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# vitedocs:capture
+
+This mode reads `.vitepress/docs-manifest.json`. Run `/vitedocs:generate` first if no manifest exists yet.
+
+Handles two capture types from the manifest:
+- **screenshot** (`"type": "screenshot"`) — static PNG via Playwright
+- **video** (`"type": "video"`) — recorded interaction with step captions, uploaded to GitHub Releases
+
+---
+
+## Step 1 — Gather capture details
+
+**Q1 — Source:**
+- header: "Capture source"
+- question: "Where should I capture 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?"
+
+**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 target screens 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 items should I capture?"
+- options:
+  - "All placeholders from the manifest (screenshots + videos)"
+  - "Screenshots only"
+  - "Videos only"
+  - "Specific items — I'll tell you which"
+
+If specific: ask as plain text — "Which pages or capture names?"
+
+**Q6 — GitHub repo** (ask only if manifest contains any video entries in scope):
+- header: "GitHub repo"
+- question: "Videos are uploaded to GitHub Releases. What is the GitHub repo?"
+- options:
+  - "Same repo as the docs"
+  - "Different repo — I'll type it"
+
+If different: ask as plain text — "What is the repo? (full URL or `owner/repo`)"
+
+Wait for all answers before proceeding.
+
+---
+
+## Step 2 — Find all pending captures
+
+Read `.vitepress/docs-manifest.json`. Filter to:
+- Screenshots where `"placeholder": true`
+- Videos where `"videoUrl": ""`
+
+Group by type. If no manifest exists, scan all markdown files for `VideoDemo` and image references in `public/screenshots/` or `public/videos/`.
+
+Report what was found:
+```
+Found 4 pending captures:
+  Screenshots (2): timer-main.png, settings-overview.png
+  Videos (2):      timer-start.webm, form-submit.webm
+```
+
+---
+
+## Step 3 — Capture screenshots
+
+Run ALL screenshots as a single batched heredoc — one bash approval covers the entire set.
+
+**⛔ Credential rule — NEVER write credentials to any file.** All scripts run as inline bash heredocs. Credentials are passed directly as inline values within the heredoc and exist only in memory.
+
+**For pages requiring auth:** drive a login flow before navigating to target URLs. If no credentials were given, skip auth-gated items and list them in the summary.
+
+Batch all screenshots into one heredoc:
+
+```bash
+node --input-type=module << 'SCRIPT'
+import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
+const browser = await chromium.launch({ channel: 'chrome', args: ['--no-sandbox'] });
+
+const captures = [
+  { url: 'BASE_URL/PATH_1', path: 'OUTPUT_PATH_1', settle: SETTLE_MS },
+  { url: 'BASE_URL/PATH_2', path: 'OUTPUT_PATH_2', settle: SETTLE_MS },
+];
+
+for (const cap of captures) {
+  const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+  await page.goto(cap.url, { waitUntil: 'load', timeout: 60000 });
+  await page.waitForTimeout(cap.settle);
+  await page.screenshot({ path: cap.path, fullPage: false });
+  await page.close();
+  console.log('Captured', cap.path);
+}
+
+await browser.close();
+SCRIPT
+```
+
+Adjust `settle` based on stack: WordPress/non-SPA → `500`, Next.js/SPA → `2000`–`4000`.
+
+After the batch completes, display each captured image inline with the Read tool for verification.
+
+---
+
+## Step 4 — Capture videos
+
+Capture each video one at a time (each needs its own heredoc due to the unique step sequence).
+
+For each video entry, run a heredoc that:
+1. Records the screen with `recordVideo`
+2. Executes the steps from the manifest, tracking elapsed time for each
+3. Captures a poster PNG at the final step
+4. Moves the video from the temp dir to the final output path
+5. Generates the `.vtt` caption file (written to disk — goes in git)
+6. Prints the step timings as JSON
+
+```bash
+node --input-type=module << 'SCRIPT'
+import { chromium } from '/opt/homebrew/lib/node_modules/playwright/index.mjs';
+import { writeFileSync, mkdirSync, readdirSync, renameSync } from 'fs';
+import { dirname } from 'path';
+
+const VIDEO_TMP  = 'DOCS_FOLDER/public/videos/.tmp';
+const VIDEO_OUT  = 'DOCS_FOLDER/public/videos/CAPTURE_NAME.webm';
+const VTT_OUT    = 'DOCS_FOLDER/public/videos/CAPTURE_NAME.vtt';
+const POSTER_OUT = 'DOCS_FOLDER/public/screenshots/CAPTURE_NAME-poster.png';
+const BASE_URL   = 'BASE_URL';
+const CAPTURE_URL = 'CAPTURE_PATH';
+
+mkdirSync(VIDEO_TMP, { recursive: true });
+mkdirSync(dirname(VIDEO_OUT), { recursive: true });
+mkdirSync(dirname(POSTER_OUT), { recursive: true });
+
+const browser = await chromium.launch({ channel: 'chrome', args: ['--no-sandbox'] });
+const context = await browser.newContext({
+  viewport: { width: 1440, height: 900 },
+  recordVideo: { dir: VIDEO_TMP, size: { width: 1440, height: 900 } }
+});
+const page = await context.newPage();
+
+const t0 = Date.now();
+const elapsed = () => (Date.now() - t0) / 1000;
+const stepTimings = [];
+
+await page.goto(`${BASE_URL}${CAPTURE_URL}`, { waitUntil: 'load', timeout: 60000 });
+await page.waitForTimeout(800);
+
+// STEPS — substituted from manifest steps array:
+// stepTimings.push({ caption: 'CAPTION', time: elapsed() }); await page.click('SELECTOR'); await page.waitForTimeout(MS);
+// stepTimings.push({ caption: 'CAPTION', time: elapsed() }); await page.waitForTimeout(MS);
+
+await page.screenshot({ path: POSTER_OUT });
+const duration = elapsed();
+
+await context.close();
+await browser.close();
+
+// Move recorded video to final path
+const files = readdirSync(VIDEO_TMP).filter(f => f.endsWith('.webm'));
+if (files.length) renameSync(`${VIDEO_TMP}/${files[0]}`, VIDEO_OUT);
+
+// Generate VTT
+const toVTT = s => {
+  const m = Math.floor(s / 60);
+  const sec = (s % 60).toFixed(3).padStart(6, '0');
+  return `${String(m).padStart(2,'0')}:${sec}`;
+};
+let vtt = 'WEBVTT\n\n';
+stepTimings.forEach((step, i) => {
+  const end = i < stepTimings.length - 1 ? stepTimings[i + 1].time : duration;
+  vtt += `${toVTT(step.time)} --> ${toVTT(end)}\n${step.caption}\n\n`;
+});
+writeFileSync(VTT_OUT, vtt);
+
+console.log(JSON.stringify({ stepTimings, duration }));
+SCRIPT
+```
+
+After each video runs:
+1. Display the poster image inline with the Read tool so the user can verify the final frame
+2. Update the manifest entry with the step timings (replace the action-based steps from generate with timed steps)
+3. The `.vtt` file is now on disk — it goes in git as-is
+
+---
+
+## Step 5 — GitHub Releases upload
+
+After all videos are captured, provide upload instructions for each video file:
+
+```
+Videos are ready for upload to GitHub Releases.
+
+1. Go to: https://github.com/OWNER/REPO/releases
+2. Create a release tagged `docs-media` (or open the existing one)
+   — This is a dedicated release just for doc assets, not tied to code versions.
+3. Attach these files:
+     public/videos/timer-start.webm
+     public/videos/form-submit.webm
+4. Once uploaded, each file will have a URL like:
+     https://github.com/OWNER/REPO/releases/download/docs-media/timer-start.webm
+```
+
+Then ask:
+
+- header: "Upload complete?"
+- question: "Have you uploaded the videos to GitHub Releases?"
+- options:
+  - "Yes — update the manifest and docs"
+  - "I'll do it later — skip for now"
+
+If yes: update each video entry in the manifest with the correct `videoUrl`. Also update any `<VideoDemo src="...">` placeholders in the markdown files with the real URL.
+
+If skip: leave `videoUrl: ""` in the manifest. The VideoDemo component will still render the step list and poster — it just won't have a playable video until the URL is filled in.
+
+---
+
+## Step 6 — Rewrite prose around captures
+
+After all captures complete:
+- For each screenshot: go back to the doc page and rewrite the surrounding paragraph to match what's actually in the screenshot
+- For each video: verify the step captions in the doc match what was captured — update if anything looks off
+
+Read each screenshot with the Read tool to inform the rewrite.
+
+---
+
+## Step 7 — Update manifest
+
+For each successfully captured item:
+- Screenshots: set `"placeholder": false`, record capture timestamp
+- Videos: set step timings, `vtt` path, `poster` path, and `videoUrl` (once uploaded)
+
+---
+
+## Step 8 — Summary
+
+```
+Captured X screenshots, Y videos.
+
+Screenshots:
+  ✓ timer-main.png
+  ✓ settings-overview.png
+
+Videos:
+  ✓ timer-start.webm — poster captured, VTT written, awaiting upload
+  ✓ form-submit.webm — poster captured, VTT written, awaiting upload
+
+  Upload to: https://github.com/OWNER/REPO/releases/tag/docs-media
+
+Prose rewritten in X doc pages.
+Run /vitedocs:sync after future code changes to keep docs current.
+```

package/commands/vitedocs/generate.md

@@ -40,10 +40,25 @@ Add this line if not already present:
       "images": [
         {
           "path": "docs/public/screenshots/timer-main.png",
+          "type": "screenshot",
           "placeholder": true,
           "caption": "Timer in active interval state",
           "captureUrl": "/workouts/123",
           "captureNote": "Timer should be running with intervals visible"
+        },
+        {
+          "path": "docs/public/videos/timer-start.webm",
+          "type": "video",
+          "poster": "docs/public/screenshots/timer-start-poster.png",
+          "vtt": "docs/public/videos/timer-start.vtt",
+          "videoUrl": "",
+          "caption": "Starting a timer interval",
+          "captureUrl": "/workouts/123",
+          "steps": [
+            { "caption": "Click Start to begin the interval", "selector": ".start-btn", "action": "click" },
+            { "caption": "Timer counts down in real time", "action": "wait", "ms": 1500 },
+            { "caption": "Pause freezes the current interval", "selector": ".pause-btn", "action": "click" }
+          ]
         }
       ],
       "lastSynced": "ISO-8601 timestamp",
@@ -280,9 +295,72 @@ Present the proposed outline as plain text, then use AskUserQuestion to confirm:
 
 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 3b — Identify home page features
+
+Based on your codebase analysis, identify 3–6 meaningful capabilities or selling points of the project that would work well as `features` entries on the VitePress home page (`index.md`).
+
+Good features are things a user or developer would care about — core functionality, key integrations, notable technical traits, or workflow benefits. Avoid generic filler like "Easy to use" unless it's specifically supported by something concrete in the code.
+
+For each feature, derive:
+- `icon` — a single emoji that represents it
+- `title` — 2–4 words
+- `details` — 1–2 sentences drawn from what you actually read in the codebase
+
+Present the proposed features as plain text before writing anything:
+
+```
+Home page features I identified:
+
+⚡️ Real-time Sync
+   Changes pushed from the dashboard are reflected in the app within 500ms via WebSockets.
+
+🔒 Role-Based Access
+   Three permission tiers (admin, editor, viewer) enforced at the API and UI layer.
+
+🧩 Block Builder
+   Drag-and-drop layout editor built on ACF Blocks — no PHP required for content authors.
+...
+```
+
+Then ask:
+
+- header: "Home page features"
+- question: "Do these features look right for the home page?"
+- options:
+  - "Yes — use these"
+  - "I want to change some"
+  - "Skip the home page features section"
+
+If changes: ask as plain text — "What would you like to add, remove, or reword?"
+
+Store the confirmed features — they are written into `index.md` in Step 4.
+
 ### Step 4 — Write pages
 
-Write pages one at a time. For each page:
+Write `index.md` first, then remaining pages one at a time. For `index.md`, use the VitePress home page layout with the confirmed features:
+
+```md
+---
+layout: home
+
+hero:
+  name: "App Name"
+  text: "One-line tagline"
+  tagline: Slightly longer supporting line drawn from Q2 app description.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /FIRST_GUIDE_PAGE
+
+features:
+  - icon: ⚡️
+    title: Feature Title
+    details: Feature details sentence.
+  # ... remaining features
+---
+```
+
+Populate `name`, `text`, `tagline`, and the `link` in `actions` from what you know about the project. For each remaining page:
 
 1. Read the relevant source files
 2. Write the markdown based on what you can confidently determine
@@ -307,6 +385,27 @@ Write pages one at a time. For each page:
    ```
    Populate `method`, `path`, `auth`, `body`, and `response` from what you read in the source files. If a request body or response shape is unclear, leave it as a gap comment.
 
+6. For pages documenting interactions, flows, or button behaviors — anything where "what happens next" matters — suggest a video capture instead of a screenshot. Use `VideoDemo` like this:
+
+   ```md
+   <VideoDemo
+     src="https://github.com/OWNER/REPO/releases/download/docs-media/timer-start.webm"
+     poster="/screenshots/timer-start-poster.png"
+     vtt="/videos/timer-start.vtt"
+     caption="Starting a timer interval"
+     :steps="[
+       { caption: 'Click Start to begin the interval', time: 0 },
+       { caption: 'Timer counts down in real time', time: 1.5 },
+       { caption: 'Pause freezes the current interval', time: 4.2 }
+     ]"
+   />
+   ```
+
+   Leave `src` with a placeholder GitHub Releases URL — it will be filled in after `/vitedocs:capture` runs. Record the entry in the manifest with `"type": "video"` and `"videoUrl": ""`.
+
+   Use a screenshot (not video) for: static UI states, settings screens, empty states, error messages.
+   Use a video for: multi-step flows, button interactions, animations, form submissions, drag-and-drop.
+
 Do not stop to ask gap questions mid-page. Keep writing and accumulate all gaps.
 
 ### Step 5 — Gap review
@@ -484,6 +583,75 @@ const highlightedResponse = computed(() =>
 </style>
 ```
 
+**`.vitepress/components/VideoDemo.vue`** — write this file exactly:
+
+```vue
+<template>
+  <figure class="vd">
+    <div class="vd__player">
+      <video
+        ref="videoEl"
+        :src="src"
+        :poster="poster"
+        controls
+        preload="metadata"
+        @timeupdate="onTimeUpdate"
+      >
+        <track v-if="vtt" kind="subtitles" :src="vtt" default label="Steps" />
+      </video>
+    </div>
+    <ol v-if="steps && steps.length" class="vd__steps">
+      <li
+        v-for="(step, i) in steps"
+        :key="i"
+        class="vd__step"
+        :class="{ 'vd__step--active': activeStep === i }"
+      >
+        <span class="vd__num">{{ i + 1 }}</span>
+        {{ step.caption }}
+      </li>
+    </ol>
+    <figcaption v-if="caption" class="vd__caption">{{ caption }}</figcaption>
+  </figure>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const props = defineProps({
+  src:     { type: String, required: true },
+  poster:  { type: String, default: '' },
+  vtt:     { type: String, default: '' },
+  caption: { type: String, default: '' },
+  steps:   { type: Array,  default: () => [] },
+})
+
+const videoEl   = ref(null)
+const activeStep = ref(-1)
+
+const onTimeUpdate = () => {
+  if (!props.steps.length || !videoEl.value) return
+  const t = videoEl.value.currentTime
+  let active = -1
+  for (let i = 0; i < props.steps.length; i++) {
+    if (t >= props.steps[i].time) active = i
+  }
+  activeStep.value = active
+}
+</script>
+
+<style scoped>
+.vd { margin: 1.5rem 0 2.5rem; }
+.vd__player { border-radius: 8px; overflow: hidden; border: 1px solid var(--vp-c-divider); background: #000; }
+.vd__player video { width: 100%; display: block; max-height: 500px; }
+.vd__steps { margin: 12px 0 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 6px; }
+.vd__step { display: flex; align-items: baseline; gap: 8px; font-size: 0.82rem; color: var(--vp-c-text-2); padding: 6px 10px; border-radius: 6px; border: 1px solid transparent; transition: all 0.2s; }
+.vd__step--active { color: var(--vp-c-text-1); background: var(--vp-c-bg-soft); border-color: var(--vp-c-divider); }
+.vd__num { font-size: 0.65rem; font-weight: 700; color: var(--vp-c-brand-1); background: var(--vp-c-brand-soft); width: 18px; height: 18px; border-radius: 50%; display: inline-flex; align-items: center; justify-content: center; flex-shrink: 0; }
+.vd__caption { font-size: 0.75rem; color: var(--vp-c-text-3); margin-top: 8px; text-align: center; }
+</style>
+```
+
 **Install dependencies** in the docs folder:
 
 ```bash
@@ -511,6 +679,7 @@ import { useRoute } from 'vitepress'
 import mediumZoom from 'medium-zoom'
 import './index.css'
 import ApiEndpoint from '../components/ApiEndpoint.vue'
+import VideoDemo from '../components/VideoDemo.vue'
 
 export default {
   extends: DefaultTheme,
@@ -522,6 +691,7 @@ export default {
   },
   enhanceApp({ app }) {
     app.component('ApiEndpoint', ApiEndpoint)
+    app.component('VideoDemo', VideoDemo)
   }
 }
 ```
@@ -551,7 +721,7 @@ Add `docs-manifest.json` to `.vitepress/` entry in `.gitignore`.
 
 ```
 Generated X pages (Y user-facing, Z developer).
-Created N placeholder screenshots — run /vitedocs:screenshot when ready to capture real images.
+Created N placeholder screenshots — run /vitedocs:capture when ready to capture real images.
 Filled M of P gaps — X remaining gap comments left in files for manual review.
 ```
 

package/commands/vitedocs/init.md

@@ -15,7 +15,7 @@ Use AskUserQuestion to ask which mode to run:
 - 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"
+  - "capture — Capture screenshots and record interaction videos"
   - "sync — Detect code drift and update docs that are out of date"
   - "brand — Configure colors, fonts, logo, and visual identity"
   - "update — Retrofit an existing docs setup with the latest components"

package/commands/vitedocs/update.md

@@ -24,7 +24,8 @@ Scan the current working directory and any known focus paths for `.vitepress/con
 For each confirmed docs path, check what is already present:
 
 - `.vitepress/components/ApiEndpoint.vue` — exists?
-- `.vitepress/theme/index.js` — exists? includes `medium-zoom`? includes `ApiEndpoint`?
+- `.vitepress/components/VideoDemo.vue` — exists?
+- `.vitepress/theme/index.js` — exists? includes `medium-zoom`? includes `ApiEndpoint`? includes `VideoDemo`?
 - `.vitepress/theme/index.css` — exists? includes `.medium-zoom-overlay` z-index rules?
 - `package.json` — are `medium-zoom` and `highlight.js` listed in dependencies?
 
@@ -32,9 +33,10 @@ Report findings as a checklist:
 ```
 Path: docs/
   [x] ApiEndpoint.vue — found (needs update)
+  [ ] VideoDemo.vue — missing
   [ ] medium-zoom installed
   [x] highlight.js installed
-  [x] theme/index.js — found (missing medium-zoom wiring)
+  [x] theme/index.js — found (missing medium-zoom wiring, missing VideoDemo)
   [x] theme/index.css — found (missing z-index rules)
 ```
 
@@ -71,6 +73,8 @@ Apply only the items selected (or all missing/outdated items if "Everything" was
 
 **`ApiEndpoint.vue`** — write the full component from the template in generate Step 6, substituting the correct tab list. If the file already exists, replace it entirely (it is a generated component, not hand-edited).
 
+**`VideoDemo.vue`** — if missing, write the full component from the template in generate Step 6. If it already exists, replace it entirely (it is a generated component, not hand-edited).
+
 **`medium-zoom` + `highlight.js`** — if either is missing from `package.json` dependencies, run:
 ```bash
 cd DOCS_FOLDER && npm install medium-zoom highlight.js
@@ -101,6 +105,7 @@ import { useRoute } from 'vitepress'
 import mediumZoom from 'medium-zoom'
 import './index.css'
 import ApiEndpoint from '../components/ApiEndpoint.vue'
+import VideoDemo from '../components/VideoDemo.vue'
 
 export default {
   extends: DefaultTheme,
@@ -112,6 +117,7 @@ export default {
   },
   enhanceApp({ app }) {
     app.component('ApiEndpoint', ApiEndpoint)
+    app.component('VideoDemo', VideoDemo)
   }
 }
 ```

package/install.js

@@ -18,6 +18,10 @@ if (existsSync(oldSkill)) {
 const src = join(__dirname, 'commands', 'vitedocs');
 const dest = join(home, '.claude', 'commands', 'vitedocs');
 
+// Clean destination before installing to remove any stale files
+if (existsSync(dest)) {
+  rmSync(dest, { recursive: true });
+}
 mkdirSync(dest, { recursive: true });
 
 const files = readdirSync(src).filter(f => f.endsWith('.md'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdangavin/claude-skill-vitepress-docs",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Installs the vitedocs: Claude Code skill suite — VitePress docs setup, generate, screenshot, sync, brand, and update.",
   "type": "module",
   "bin": {

package/commands/vitedocs/screenshot.md

@@ -1,126 +0,0 @@
----
-name: vitedocs:screenshot
-description: Capture real screenshots using Playwright and replace placeholders in docs.
-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: 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 a script file, `.env`, the manifest, or anywhere on disk. All Playwright scripts run as inline bash heredocs — credentials are passed directly as inline values to `page.fill()` calls within the heredoc and exist only in memory for the duration of the command. 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 `/vitedocs:screenshot` again with credentials.
-
-**Standard capture script template:**
-
-Run inline via bash heredoc — no file is ever written to disk:
-
-```bash
-node --input-type=module << 'SCRIPT'
-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(SETTLE_MS);
-await page.screenshot({ path: 'OUTPUT_PATH', fullPage: false });
-await browser.close();
-SCRIPT
-```
-
-Adjust `SETTLE_MS` based on stack type: WordPress/non-SPA → `500`, Next.js/SPA → `2000`–`4000`.
-
-Never write the script to a file — always use the heredoc form above.
-
-### 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 /vitedocs:sync after future code changes to keep docs current.
-```