@gallopsystems/agent-skills 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/copier-template/skills/copier-template/SKILL.md

@@ -62,6 +62,20 @@ git ls-remote --tags --refs --sort=-v:refname <template-url> 'v*' | head -1
 
 If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with an `--allow-empty` commit and opens a PR whose body contains the version delta, release-notes/compare links, and step-by-step instructions an agent can execute. Hard-won details to keep if reimplementing: an explicit `permissions: contents: write, pull-requests: write` block (default token can't open PRs), a static branch name (dated branches caused duplicate PRs), and comparing **tag versions, not commit SHAs**.
 
+## Branch Protection in Descendants
+
+A template **cannot** enable branch protection for the repos it generates — GitHub reads required status checks from repo config, never from committed workflow files. So every descendant starts with nothing gating merges until someone sets it once (after the first CI run, so the check is known). This template's CI exposes a **`ci-success`** summary job to be exactly that gate — require it on `main`:
+
+```bash
+echo '{"required_status_checks":{"strict":false,"contexts":["ci-success"]},"enforce_admins":false,"required_pull_request_reviews":null,"restrictions":null}' \
+  | gh api -X PUT repos/<owner>/<repo>/branches/main/protection --input -
+```
+
+- **Require the single `ci-success` context, not individual job names.** CI shards the test suite, so the per-leg check names embed the matrix size (`test (shard 1/4)`) and change as the project grows — protection pinned to them blocks every PR the moment the count shifts. `ci-success` is a summary job (`needs:` all gating jobs, `if: always()`, fails unless every `needs.*.result` is `success`); `needs.test.result` rolls the whole matrix into one value, so it stays correct at any shard count. If you add a template whose CI lacks such a job, create one rather than requiring the matrix legs directly.
+- **`coverage` is deliberately excluded** from `ci-success` so the report never blocks a merge — don't add it to the required contexts.
+- The PUT body must include `required_status_checks`, `enforce_admins`, `required_pull_request_reviews`, and `restrictions` (any may be `null`) or the call 422s. Needs admin on the repo.
+- A Conventional-Commits **PR-title check is only worth requiring on repos something actually reads the title** — i.e. a published package with release-please/changelog automation. A private app (no release tooling, `"private": true`, no version) gains nothing from it; don't gate on it there.
+
 ## Further Reading
 
 - **Template anatomy & testing changes**: [template-authoring.md](template-authoring.md)

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md

@@ -76,7 +76,7 @@ From nuxt-auth-utils:
 - `hashPassword`, `verifyPassword`
 - `defineOAuth*EventHandler` (Google, GitHub, etc.)
 
-**Need to import:** `z` from "zod", `fromZodError` from "zod-validation-error"
+**Need to import:** `z` from "zod" (zod 4 — error formatting is built in via `z.prettifyError()`; no `zod-validation-error` needed)
 
 ### Client-side
 
@@ -104,7 +104,7 @@ const query = await getValidatedQuery(event, z.object({
 }));
 
 const body = await readValidatedBody(event, z.object({
-  email: z.string().email(),
+  email: z.email(), // Zod 4: top-level, not z.string().email()
   name: z.string().min(1),
 }));
 ```

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md

@@ -33,7 +33,7 @@ Tasks live in `server/tasks/`. Directory structure = task name with colons:
 import { z } from "zod";
 
 const PayloadSchema = z.object({
-  to: z.string().email(),
+  to: z.email(), // Zod 4: top-level, not z.string().email()
   subject: z.string(),
   body: z.string(),
 });

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md

@@ -43,25 +43,28 @@ const query = await getValidatedQuery(event, (data) => querySchema.parse(data));
 
 ## Pattern 3: safeParse for Better Errors
 
+Zod 4 has a built-in `z.prettifyError()` — no `zod-validation-error` dependency needed:
+
 ```typescript
-import { fromZodError } from "zod-validation-error";
+import { z } from "zod";
 
 const rawQuery = getQuery(event);
 const result = querySchema.safeParse(rawQuery);
 
 if (!result.success) {
-  console.error("Validation error:", result.error);  // Dev log
-  const userError = fromZodError(result.error);      // User-friendly
+  console.error("Validation error:", z.treeifyError(result.error)); // structured dev log
   throw createError({
     statusCode: 400,
     statusMessage: "Bad Request",
-    message: userError.message,
+    message: z.prettifyError(result.error), // human-readable, e.g. "✖ Invalid email address\n  → at email"
   });
 }
 
 return result.data;
 ```
 
+`z.prettifyError(err)` returns a readable multi-line string; `z.treeifyError(err)` returns a nested object keyed by field (the replacement for the deprecated `.format()`). Use `z.flattenError(err)` for a flat `{ formErrors, fieldErrors }` shape.
+
 ## Common Zod Patterns
 
 ### Query Parameters
@@ -90,7 +93,7 @@ const querySchema = z.object({
 
 ```typescript
 const createUserSchema = z.object({
-  email: z.string().email(),
+  email: z.email(), // Zod 4: top-level, NOT z.string().email()
   name: z.string().min(1).max(100),
   role: z.enum(["admin", "user"]).default("user"),
   metadata: z.record(z.string(), z.any()).optional(),
@@ -117,7 +120,7 @@ Export schemas for client-side type reuse:
 import { z } from "zod";
 
 export const CreateUserSchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   name: z.string().min(1),
 });
 
@@ -129,3 +132,17 @@ const body: CreateUserInput = { email: "test@example.com", name: "Test" };
 ```
 
 **Note:** Nitro auto-generates response types, but NOT input types from Zod schemas.
+
+## Zod 4 Notes (this stack pins zod ^4)
+
+The model's prior is mostly Zod 3 — these are the idioms that changed. Get them right.
+
+- **String formats are top-level functions, not `z.string()` methods.** Use `z.email()`, `z.url()`, `z.uuid()`, `z.ipv4()`, `z.iso.datetime()`. The chained forms (`z.string().email()`) are deprecated.
+- **Error customization is one `error` param.** `message`, `invalid_type_error`, `required_error`, and `errorMap` are gone:
+  ```typescript
+  z.string().min(5, { error: "Too short." });
+  z.string({ error: (iss) => iss.input === undefined ? "Required" : "Must be a string" });
+  ```
+- **Format errors with the built-ins**, not `zod-validation-error`: `z.prettifyError()` (human string), `z.treeifyError()` (nested, replaces deprecated `.format()`), `z.flattenError()` (replaces deprecated `.flatten()`).
+- **`.default()` applies to the *output* type** and short-circuits parsing when input is `undefined`. For the old "run the default through the schema" behavior, use `.prefault()`.
+- **`z.coerce.*` input type is now `unknown`** (not the output type) — fine for h3 query/body parsing, but affects schemas you consume elsewhere.

package/plugins/tailwind-v4/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "tailwind-v4",
+  "description": "Tailwind CSS v4 (CSS-first): @import/@theme/@source config, the no-tailwind.config.js model, prefers-color-scheme dark mode, and the v3->v4 traps an LLM trained on v3 falls into",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/tailwind-v4/skills/tailwind-v4/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: tailwind-v4
+description: Work effectively with Tailwind CSS v4 (the CSS-first model) in a Nuxt/Vite + PrimeVue/Volt stack. Use when editing Tailwind CSS, configuring @theme/@source/@import, setting up dark mode, defining design tokens, or debugging classes that silently don't apply. Covers the v3→v4 traps an LLM trained on v3 falls into.
+---
+
+# Tailwind CSS v4
+
+Tailwind v4 is **CSS-first**: configuration lives in your CSS file, not a
+`tailwind.config.js`. Most day-to-day utility usage is unchanged and the model is
+already good at it — this skill is about the **v4-specific shifts** and the traps
+that come from a v3-trained prior. When a class "isn't working," the cause is
+almost always one of the gotchas below.
+
+## When to use this skill
+
+- Editing the Tailwind CSS entry file (`@import`, `@theme`, `@source`, `@custom-variant`)
+- Defining or renaming design tokens / colors
+- Setting up or debugging dark mode
+- A utility class silently renders nothing and you don't know why
+- Migrating or porting v3 code (anything with `tailwind.config.js`, `@tailwind`, `darkMode: 'class'`)
+
+## The CSS-first setup (no JS config)
+
+There is **no `tailwind.config.js`/`.ts`**. The whole config is in your CSS entry
+(e.g. `app/assets/css/main.css`):
+
+```css
+@import "tailwindcss";          /* NOT @tailwind base/components/utilities */
+@import "tailwindcss-primeui";
+@source "../../../src/volt";     /* scan sources Tailwind won't auto-detect */
+
+@theme {
+  --color-surface: #ffffff;      /* defines the bg-surface / text-surface utilities */
+  --color-fg: #18181b;
+}
+```
+
+Build integration is the **Vite plugin**, not the old Nuxt module or PostCSS:
+
+```ts
+// nuxt.config.ts / vite.config.ts
+import tailwindcss from "@tailwindcss/vite";
+export default defineNuxtConfig({ vite: { plugins: [tailwindcss()] } });
+```
+
+Do **not** add `@nuxtjs/tailwindcss`, a `postcss.config.js` with `tailwindcss: {}`,
+or `@tailwind base/components/utilities` — those are v3 and either no-op or break.
+`tailwindcss` itself must be a direct dependency (alongside `@tailwindcss/vite`),
+or `tailwindcss-primeui` raises peer-dependency warnings.
+
+## Design tokens: `@theme` vs `:root`
+
+- A custom color token must live in **`@theme`** to generate a utility:
+  `@theme { --color-canvas: #fafafa }` → `bg-canvas`/`text-canvas` exist.
+  The same variable in `:root` is just a CSS variable — **no utility class**.
+- **The utility name is the full `--color-*` suffix.** `--color-fg-subtle` →
+  `text-fg-subtle`. A shortened or undefined name (`text-subtle`, or a dangling
+  `bg-surface-strong` with no matching token) **generates nothing, with no error**
+  — the element just renders unstyled. First thing to check when a custom color
+  "does nothing": does the token name match exactly?
+- **Inverse for PrimeUI:** PrimeVue's `--p-*` variables stay in `:root`. The
+  `tailwindcss-primeui` plugin turns those into utilities — don't move them into
+  `@theme`.
+
+## `@source` — v4 only generates classes from scanned files
+
+v4 auto-detects content, but skips files outside the project's default roots (and
+anything gitignored). Classes used **only** inside a vendored/library directory
+(e.g. Volt components in `src/volt`) get purged and silently go missing. Point
+Tailwind at them: `@source "../../../src/volt";`. If a vendored component's
+classes aren't generating, check this line first.
+
+## Dark mode
+
+v4's `dark:` variant defaults to **`@media (prefers-color-scheme: dark)`** (OS
+preference) — there is no `darkMode: 'class'` config and no `.dark` class by
+default. Two consequences:
+
+1. **Prefer semantic tokens over `dark:` pairs.** Writing `bg-white dark:bg-zinc-900`
+   on every element means one forgotten half silently breaks dark mode. Instead
+   define a token that *flips its value* in one media block, and use it with no
+   `dark:`:
+   ```css
+   @theme { --color-surface: #fff; --color-fg: #18181b; }
+   @media (prefers-color-scheme: dark) {
+     :root { --color-surface: #18181b; --color-fg: #f4f4f5; }
+   }
+   ```
+   ```html
+   <div class="bg-surface text-fg"><!-- flips automatically, no dark: --></div>
+   ```
+2. **For a manual (class/toggle) dark mode, you must redefine the variant** —
+   `darkMode: 'class'` is gone:
+   ```css
+   @custom-variant dark (&:where(.p-dark, .p-dark *));
+   ```
+   Because the default keys off the OS, a JS toggle must also override the tokens
+   (e.g. via a `[data-theme]` block), and any non-CSS consumer of the scheme
+   (canvas/chart libs — see gotchas) must be re-notified on toggle.
+
+## More gotchas
+
+The full set mined from real debugging sessions — `@apply` in scoped `<style>`,
+JS-driven colors that can't read tokens, `@import url()` ordering, the PrimeUI
+surface ramp vs flipping tokens, and more — is in
+[gotchas.md](gotchas.md). Read it when touching CSS in this stack.
+
+## Optional tooling
+
+The community **[`tailwindcss-mcp-server`](https://github.com/clarity-contrib/tailwindcss-mcp-server)**
+(`npx -y tailwindcss-mcp-server`) exposes utility/color lookup, docs search, and
+CSS→Tailwind conversion, with a `version` param defaulting to `v4`. Useful for
+class discovery, but it does not encode the stack-specific gotchas above.
+
+## Related
+
+- **PrimeVue/Volt component styling** (`pt:` pass-through, `ptViewMerge`,
+  `data-pc-*`, `@apply` + `@reference` in SFC `<style>`, reactive chart palettes):
+  see the **volt-primevue** skill — it owns the component layer; this skill owns
+  the Tailwind-v4 fundamentals.
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something
+in this domain that this skill did not cover — an error you had to figure out, a
+behavior that contradicts what is documented above, a workflow knot — ask the
+user: **"Want me to contribute this back to the tailwind-v4 skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the
+equivalent inline: distill the generic lesson (placeholders only — no project
+names, IDs, domains, or secrets), then branch or fork
+[gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and
+open a PR editing this skill.

package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md

@@ -0,0 +1,84 @@
+# Tailwind v4 Gotchas
+
+Mined from real debugging sessions in this stack (Nuxt/Vite + Tailwind v4 +
+PrimeVue/Volt). Each is a place where a class silently did nothing, a v3 habit
+broke, or the fix was non-obvious.
+
+## `@apply` of custom tokens in a `<style>` block needs `@reference` to YOUR css
+
+In v4, a component-scoped `<style>` doesn't see your Tailwind context. `@apply`
+there needs a `@reference` — and the trap is that `@reference "tailwindcss"` loads
+only the **default** theme, so built-in utilities (`rounded-lg`, `zinc-*`) work
+but your custom `@theme` tokens fail with *"Cannot apply unknown utility class."*
+
+```css
+/* ❌ @reference "tailwindcss";  → @apply text-fg fails */
+@reference "../assets/css/main.css";   /* ✅ exposes YOUR tokens; path is relative to the file */
+.prose :where(h2) { @apply text-fg; }
+```
+
+Better still in scoped styles: skip `@apply` and consume the generated CSS
+variables directly — `color: var(--color-fg)` always works with no `@reference`.
+
+Note: a full `yarn build` validates `@apply` in `<style>`; a bare
+`@tailwindcss/cli` compile does **not** — the CLI can pass while the real build
+fails. Include `build` in your check. (The SFC-specific details live in the
+**volt-primevue** skill's gotchas.)
+
+## `@import url(...)` must come before `@import "tailwindcss"`
+
+The CSS spec requires all `@import` statements to precede other rules. Because
+`@import "tailwindcss"` inlines real rules, any plain `@import url(...)` (e.g.
+Google Fonts) placed after it is invalid and silently dropped.
+
+```css
+@import url("https://fonts.googleapis.com/css2?family=Inter");  /* ✅ first */
+@import "tailwindcss";
+@import "some-lib/dist/style.css";
+```
+
+## JS-set colors can't read `var(--color-*)` — they won't flip with the theme
+
+Anything that takes colors as JS values (ApexCharts, canvas, SVG attributes
+written from script) can't use `bg-surface`/`var(--color-fg)` — the value is baked
+at render and won't follow `prefers-color-scheme`. A `colors: ["#18181b"]`
+(near-black) chart line is invisible on dark. Compute a palette from a
+`window.matchMedia("(prefers-color-scheme: dark)")` match and recompute on its
+`change` event. (The volt-primevue skill has the Vue composable version.)
+
+## Two surface systems: PrimeUI's ramp is fixed, your `@theme` tokens flip
+
+- PrimeUI's `--p-surface-0 … --p-surface-950` ramp is defined **once** and does
+  **not** change with the theme. `bg-surface-0` is always white — to go dark you
+  need an explicit `dark:bg-surface-900` pair. Vendored Volt components rely on
+  this full 0–950 ramp.
+- Your `@theme` semantic tokens (`--color-surface`, `--color-fg`) **flip their
+  value** in the dark `@media` block, so `bg-surface` needs no `dark:`.
+
+Rule: tokenize only the markup you own (pages, your components). Leave vendored
+Volt components on the `surface-*` ramp + `dark:` pairs so they stay
+upstream-compatible. Mixing the two is what produces white-striped tables on dark.
+
+## Don't port a v3 `tailwind.config.js` into a v4 app
+
+None of it applies, and some of it actively breaks:
+
+```js
+// ❌ v3 — delete the whole file in v4
+module.exports = {
+  content: ["./**/*.vue"],        // → automatic detection (+ @source for out-of-tree)
+  darkMode: "class",              // → @custom-variant dark (...) in CSS, or rely on @media
+  theme: { extend: { colors: {...} } }, // → @theme { --color-* } in CSS
+  plugins: [require("...")],      // → @plugin / @import in CSS; require() also breaks in ESM
+};
+```
+
+Also drop the `@nuxtjs/tailwindcss` module — it's v3-era and has been observed to
+trigger an infinite dev-server regeneration loop. Use `@tailwindcss/vite`.
+
+## Benign noise
+
+Under Yarn (esp. PnP), `@tailwindcss/vite` and `tailwindcss-primeui` may emit
+"doesn't provide vite/tailwindcss" unmet-peer-dependency warnings even though the
+deps resolve transitively. These are safe to ignore — they are not a config bug.
+(Adding `tailwindcss` as a direct dependency silences the `tailwindcss-primeui` one.)

package/plugins/volt-primevue/skills/volt-primevue/gotchas.md

@@ -106,6 +106,31 @@ section name is prefixed **`pc`** (e.g. a Badge embedded in another component is
 <VoltSomething pt:pcBadge:root:class="bg-red-500" />
 ```
 
+## State styling: use `tailwindcss-primeui`'s `p-*` variants, not edited source
+
+`tailwindcss-primeui` registers component-state variants — `p-selected:`,
+`p-focus:`, `p-disabled:`, `p-invalid:`, `p-editable:` — that key off PrimeVue's
+internal state. Reach for these via `pt:` instead of editing vendored component
+source to style a state:
+
+```vue
+<VoltSelect pt:option:class="p-selected:bg-highlight p-focus:bg-surface-100" />
+```
+
+## PrimeIcons `.pi` is `display:inline-block` — it beats `hidden`
+
+PrimeIcons sets `display: inline-block` on `.pi`, which has higher specificity
+than Tailwind's `hidden` (`display:none`). Toggling an icon's visibility with bare
+`hidden`/`inline-block` silently fails — the icon stays visible. Use the `!`
+important variant:
+
+```vue
+<!-- ❌ stays visible -->
+<i class="pi pi-x hidden sm:inline-block" />
+<!-- ✅ -->
+<i class="pi pi-x !hidden sm:!inline-block" />
+```
+
 ## We don't use `@primevue/forms`
 
 This stack validates with **zod + manual wiring**, not `@primevue/forms`. The

package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vue-nuxt
-description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, slots, composables, reactivity, when watch is a code smell, page structure, display formatting, and Vue-shaped template idioms.
+description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, slots, composables, reactivity, when watch is a code smell, reaching for VueUse over hand-rolled effects, page structure, display formatting, and Vue-shaped template idioms.
 ---
 
 # Vue-in-Nuxt component authoring
@@ -23,6 +23,7 @@ cross-links to those rather than restating them.
 - Formatting display values (currency/date/number) consistently
 - Anything reactivity-shaped: `computed` vs `watch`, prop→state sync, DOM measurement
 - You see `watch` and want to know if it should be something else
+- About to hand-roll a `watch` + lifecycle teardown for a browser API (storage, timers, DOM, listeners, URL) — VueUse likely wraps it
 
 ## Reference Files
 
@@ -33,6 +34,7 @@ cross-links to those rather than restating them.
 - [composables.md](./composables.md) — `MaybeRefOrGetter`/`toValue` argument contract, return refs not `reactive()`, thin pure-core shell, `onScopeDispose`/`effectScope` cleanup
 - [reactivity.md](./reactivity.md) — `ref` over `reactive`, `useTemplateRef`, pure computeds, mutate-don't-reassign, DOM-measure + `ResizeObserver`, `shallowRef`, watch-getter prop sync, `:key` remount, listener cleanup
 - [watch.md](./watch.md) — **`watch` is the escape hatch, not the default**: when it's right, and the four smell shapes (with refactors) found auditing 159 real watchers
+- [vueuse.md](./vueuse.md) — reach for a VueUse composable before hand-rolling a `watch` + lifecycle teardown for an external-world effect (DOM, timers, storage, URL, listeners); the `@vueuse/nuxt` setup, the watch-sugar functions, and what to keep on Nuxt's own APIs
 - [template-idioms.md](./template-idioms.md) — duplicate-`@keyup` TS error, `:deep()`/`:slotted()`/`:global()`, click-outside marker class, `NuxtLink`/thin `app.vue`, `useHead`, `v-bind` shorthand, `useId`, `<Teleport>`/`<KeepAlive>`, `v-memo`/`v-once`, file-input reset
 - [page-structure.md](./page-structure.md) — keep pages thin: route-param parsing + layout in the page, data/logic/forms in components
 - [formatters.md](./formatters.md) — never inline a currency/date/number formatter; centralize in `useFormatters`, prefer Intl/date-fns
@@ -42,7 +44,7 @@ cross-links to those rather than restating them.
 1. **Lean on auto-imports.** `app/components`, `app/composables`, `app/utils`, and the Vue/Nuxt APIs all auto-import. Add an explicit `import` only for third-party symbols and TS types. A nested component's tag carries its directory as a prefix (`components/customers/ProfileCard.vue` → `<CustomersProfileCard>`).
 2. **Type props/emits, default the booleans.** Use the type-only macros (`defineProps<{...}>()`, `defineEmits<{...}>()`). A bare `boolean` prop coerces to `false` when absent (not `undefined`), so any "defaults-on" flag MUST be defaulted — via reactive destructure (`{ flag = true } = defineProps<…>()`, the 3.5 default, no factory needed for arrays/objects) or `withDefaults` (factory required for non-primitives).
 3. **`computed` for derivation, `watch` for escaping the graph.** If a watcher body just assigns one reactive value from others, it's a `computed`. Need to write a value back? A `computed` can have a setter — reach for a writable `computed` or `defineModel` before a sync watcher. Keep computed getters pure (no fetch, no mutation, no DOM).
-4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive).
+4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive). Before hand-rolling that effect-plus-teardown, check whether a **VueUse** composable already wraps it (`vueuse.md`) — they bundle the cleanup.
 5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
 6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. Volt components, `pt:` styling, color tokens, dark mode → `volt-primevue`. Don't duplicate them here.
 

package/plugins/vue-nuxt/skills/vue-nuxt/vueuse.md

@@ -0,0 +1,75 @@
+# VueUse — reach for a composable before hand-rolling an effect
+
+`watch.md` lists the cases where `watch` is legit: they're all effects that cross
+**out of** the reactive graph (DOM, timers, storage, URL, the network). For most
+of those, **VueUse already wraps the boundary** — and a VueUse composable bundles
+the *teardown* with the reactive effect, so it retires the manual-`onUnmounted`
+cleanup, not just the watch. Before you write a `watch` + `onMounted`/`onUnmounted`
+pair against a browser API, check whether a composable does it.
+
+> Not a replacement for the framework. Data fetching stays on
+> `useFetch`/`useAsyncData` (see `nuxt-nitro-api`); cookies use Nuxt's built-in
+> `useCookie`; derivation stays a `computed`. VueUse is for the *external-world*
+> effects — see the caveats at the bottom.
+
+## Setup in Nuxt
+
+Add the module; it auto-imports every `@vueuse/core` function, so they need no
+explicit `import` (same as Nuxt's own composables — see `auto-imports.md`):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({ modules: ['@vueuse/nuxt'] })
+```
+
+The **`@vueuse/router`** and **`@vueuse/integrations`** add-ons are separate
+installs and are **not** auto-imported by the module — import them explicitly.
+
+## The boundary cases (mapped from `watch.md`)
+
+| You were about to `watch` for… | Reach for | Why it's better |
+|---|---|---|
+| `document.body.style.overflow` toggle | `useScrollLock(document.body)` | writable ref; restores the prior value on unmount |
+| `setInterval` polling | `useIntervalFn(fn, ms)` / `useTimeoutPoll` | **auto-clears on unmount** — no `clearInterval` to forget |
+| `setTimeout` | `useTimeoutFn(fn, ms)` | same auto-cleanup, with `start`/`stop` controls |
+| debounced auto-save | `useDebounceFn` / `refDebounced` | no manual timer ref + cleanup |
+| `localStorage`/`sessionStorage` write-back | `useLocalStorage(key, init)` / `useStorage` | a reactive ref mirrored to storage both ways — the write-back watch disappears |
+| `addEventListener` in `onMounted` | `useEventListener(target, evt, fn)` | auto-removes on unmount |
+| click-outside marker class | `onClickOutside(el, fn)` | replaces the hand-rolled document listener (cf. `template-idioms.md`) |
+| `ResizeObserver` re-measure | `useElementSize` / `useElementBounding` / `useResizeObserver` | reactive size, observer torn down for you (cf. `reactivity.md`) |
+| `matchMedia` listener | `useMediaQuery` / `usePreferredColorScheme` / `usePreferredDark` | reactive boolean, no listener bookkeeping |
+| clipboard write + "copied!" flag | `useClipboard()` → `{ copy, copied }` | `copied` auto-resets |
+
+URL sync (`router.replace({ query: { ...route.query, tab } })`) →
+`useRouteQuery('tab')` from `@vueuse/router` gives a ref bound two-way to the query
+param. Nuxt's own `useRoute()` is already reactive for *reads*; reach for
+`useRouteQuery` when you want a **writable** ref bound to a single param.
+
+## VueUse's `watch` sugar — when a `watch` IS warranted
+
+When the effect genuinely belongs in a watcher, VueUse's Watch category removes the
+boilerplate `watch.md` warns about:
+
+- **`watchDebounced(src, cb, { debounce: 300 })`** / **`watchThrottled`** — the
+  debounced-auto-save case without a `setTimeout` inside the callback.
+- **`whenever(source, cb)`** — fires only when `source` becomes truthy; the
+  "re-seed on dialog open" pattern (`watch(visible, v => { if (v) … })`) as one line.
+- **`until(source).toBe(x)`** — await a reactive condition instead of polling.
+- **`watchOnce`** — auto-stops after the first fire; no manual `stop()` handle.
+- **`watchIgnorable` / `watchPausable`** — suppress or pause a watcher around a
+  programmatic write (a cleaner answer than guard flags for the "re-fires on
+  programmatic reseed" trap in `watch.md`).
+
+`onWatcherCleanup` and `flush: 'post'` (in `watch.md`) still apply — these are sugar
+over the same watcher, not a different mechanism.
+
+## Caveats — don't over-reach
+
+- **Cookies:** use Nuxt's built-in **`useCookie`** (SSR-aware), not VueUse's
+  `@vueuse/integrations` `useCookies` (a `universal-cookie` wrapper).
+- **Fetching:** `useFetch`/`useAsyncData`/`$fetch` own the data layer
+  (`nuxt-nitro-api`). Skip VueUse's `useFetch`/`useAsyncState` in a Nuxt app.
+- **Head/title:** prefer Nuxt's `useHead`/`useSeoMeta` over `useTitle`/`useFavicon`.
+- **Derivation is still a `computed`.** VueUse doesn't change the core rule: if the
+  body just assigns one reactive value from others, it's a `computed`, not a
+  composable and not a watch.

package/plugins/vue-nuxt/skills/vue-nuxt/watch.md

@@ -74,6 +74,20 @@ Only when the effect crosses **out of** the reactive graph:
 - **Clone a server prop into a locally-editable draft** —
   `watch(() => props.record, (r) => { if (r) form.value = structuredClone(toRaw(r)) }, { immediate: true })`.
 
+> **Before hand-rolling the external-world cases, check VueUse.** Most of the
+> bullets above (DOM, timers, persist, URL) are exactly what VueUse wraps — and a
+> VueUse composable bundles the *teardown* with the reactive effect, so it
+> retires the manual-`onUnmounted` footgun, not just the watch:
+>
+> - **DOM / body scroll** — `useScrollLock(document.body)` over a watch toggling `document.body.style.overflow`.
+> - **Timers** — `useIntervalFn` / `useTimeoutFn` / `useTimeoutPoll` auto-clear on unmount (no manual `clearInterval`); `useDebounceFn` / `refDebounced` for debounce.
+> - **Persist** — `useLocalStorage` / `useStorage`: a reactive ref mirrored to storage, no write-back watch.
+> - **URL sync** — `useRouteQuery` (from `@vueuse/router`) for a ref bound to a query param.
+>
+> Nuxt caveats: cookies use the built-in `useCookie`, **not** VueUse's
+> `@vueuse/integrations` `useCookies`; data fetching stays on
+> `useFetch`/`useAsyncData`. Auto-import the rest via the `@vueuse/nuxt` module.
+
 ### Cancel stale work with `onWatcherCleanup`
 
 A watcher that starts async work (a keyed `$fetch`, a timer) must cancel the