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

package/commands/vitedocs/screenshot.md

@@ -0,0 +1,126 @@
+---
+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.
+```

package/commands/vitedocs/setup.md

@@ -0,0 +1,277 @@
+---
+name: vitedocs:setup
+description: Wire up VitePress + GitHub Actions for GitHub Pages deployment.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+## 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.
+
+**Multiple focus paths:** if more than one path was established in Step 0, ask Q2 through Q6 once per path — fully completing all questions for the first path before starting the second. Never present questions for two paths at the same time.
+
+**Q1 — VitePress status:**
+- header: "VitePress"
+- question: "Is VitePress already installed in this project?"
+- options:
+  - "Already installed"
+  - "Starting from scratch"
+
+**Q2 — Docs folder:**
+- header: "Docs location"
+- question: "Where should the docs folder be created? I found your repo at `[GIT_ROOT_PATH]`."
+- options:
+  - "Here → `[GIT_ROOT_PATH]/docs/`"
+  - "Somewhere else — I'll type the path"
+
+If "Somewhere else": ask as plain text — "What path should I use? (Full path or relative to `[GIT_ROOT_PATH]`)"
+
+**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`)"
+
+**Q4b — Search engine visibility:**
+- header: "Search visibility"
+- question: "Should these docs be visible to search engines and bots?"
+- options:
+  - "Yes — index these docs publicly"
+  - "No — block all search engines and bots"
+
+If "No": add the following to the VitePress config's `head` array and write a `robots.txt` to the public folder:
+
+`head` entry in `config.mjs`:
+```js
+head: [
+  ['meta', { name: 'robots', content: 'noindex, nofollow' }],
+]
+```
+If a `head` array already exists in the config, append to it — do not replace it.
+
+`DOCS_FOLDER/public/robots.txt`:
+```
+User-agent: *
+Disallow: /
+```
+
+**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 `/vitedocs: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.

package/commands/vitedocs/sync.md

@@ -0,0 +1,97 @@
+---
+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:screenshot when ready.
+```

package/commands/vitedocs/update.md

@@ -0,0 +1,142 @@
+---
+name: vitedocs:update
+description: Retrofit an existing VitePress docs setup with the latest components and dependencies.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+## Mode: update
+
+Retrofits an existing VitePress docs setup with the latest components, dependencies, and theme wiring. Does not re-run setup or regenerate pages.
+
+### Step 1 — Locate docs paths
+
+Scan the current working directory and any known focus paths for `.vitepress/config.mjs` (or `.ts`) files. List what was found and ask the user to confirm which paths to update.
+
+### Step 2 — Inventory current state
+
+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/theme/index.css` — exists? includes `.medium-zoom-overlay` z-index rules?
+- `package.json` — are `medium-zoom` and `highlight.js` listed in dependencies?
+
+Report findings as a checklist:
+```
+Path: docs/
+  [x] ApiEndpoint.vue — found (needs update)
+  [ ] medium-zoom installed
+  [x] highlight.js installed
+  [x] theme/index.js — found (missing medium-zoom wiring)
+  [x] theme/index.css — found (missing z-index rules)
+```
+
+Then ask:
+
+- header: "Update"
+- question: "What would you like to update?"
+- options:
+  - "Everything that's missing or outdated"
+  - "Let me choose item by item"
+
+### Step 3 — Gather inputs (only if needed)
+
+If `ApiEndpoint.vue` is being written or updated and no existing `apiBase` is in the VitePress config, ask:
+
+**U-Q1 — API base URL** (plain text): "What is the API base URL? (e.g. `https://api.example.com/wp-json/my-plugin/v1`)"
+
+**U-Q2 — Code sample tabs:**
+- header: "Code tabs"
+- question: "Which code sample tabs should the ApiEndpoint component show?"
+- options:
+  - "Fetch + cURL (default)"
+  - "Fetch + cURL + PHP"
+  - "Fetch + cURL + Python"
+  - "Fetch + cURL + Axios"
+  - "All of the above"
+  - "Custom — I'll list them"
+
+Skip U-Q1 and U-Q2 if `apiBase` already exists in `.vitepress/config.mjs` `themeConfig` — infer `apiBase` and existing tabs from the config and the current `ApiEndpoint.vue`.
+
+### Step 4 — Apply updates
+
+Apply only the items selected (or all missing/outdated items if "Everything" was chosen). Always read existing files before editing — never overwrite unrelated content.
+
+**`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).
+
+**`medium-zoom` + `highlight.js`** — if either is missing from `package.json` dependencies, run:
+```bash
+cd DOCS_FOLDER && npm install medium-zoom highlight.js
+```
+
+**`.vitepress/theme/index.css`** — if `.medium-zoom-overlay` z-index block is missing, append:
+```css
+.medium-zoom-overlay {
+  z-index: 100;
+}
+
+.medium-zoom-image--opened {
+  z-index: 101;
+}
+```
+Do not remove or overwrite existing entries.
+
+**`.vitepress/theme/index.js`** — merge only what is missing:
+- If `medium-zoom` wiring is absent, add the `onMounted`/`watch` setup block
+- If `ApiEndpoint` registration is absent (and `apiBase` is configured), add the import and `app.component()` call
+- Never remove existing registrations or setup logic
+
+Reference template for the full correct state:
+```js
+import DefaultTheme from 'vitepress/theme'
+import { onMounted, watch, nextTick } from 'vue'
+import { useRoute } from 'vitepress'
+import mediumZoom from 'medium-zoom'
+import './index.css'
+import ApiEndpoint from '../components/ApiEndpoint.vue'
+
+export default {
+  extends: DefaultTheme,
+  setup() {
+    const route = useRoute()
+    const initZoom = () => mediumZoom('.main img', { background: 'var(--vp-c-bg)' })
+    onMounted(initZoom)
+    watch(() => route.path, () => nextTick(initZoom))
+  },
+  enhanceApp({ app }) {
+    app.component('ApiEndpoint', ApiEndpoint)
+  }
+}
+```
+
+**`.vitepress/config.mjs`** — if `apiBase` was collected and is not already in `themeConfig`, add it.
+
+### Step 5 — Summary
+
+```
+Updated X of Y docs path(s).
+
+Changes applied:
+  PATH/.vitepress/components/ApiEndpoint.vue  — written
+  PATH/.vitepress/theme/index.js              — merged medium-zoom + ApiEndpoint
+  PATH/.vitepress/theme/index.css             — added z-index rules
+  PATH/package.json                           — installed medium-zoom, highlight.js
+```
+
+---
+
+## 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.

package/package.json

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