---
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/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?

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, missing VideoDemo)
  [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).

**`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
```

**`.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'
import VideoDemo from '../components/VideoDemo.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)
    app.component('VideoDemo', VideoDemo)
  }
}
```

**`.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

Next: run /vitedocs:capture to refresh screenshots, or /vitedocs:sync to check for code drift.
```

---

## 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.