@gallopsystems/agent-skills 1.4.0 → 1.6.0

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/state-management.md

@@ -0,0 +1,68 @@
+# Shared State with `useState`
+
+Cross-component shared state in Nuxt is `useState` — NOT a module-scope `ref`.
+This is the single most important state rule in an SSR app, because the wrong
+version is a cross-request data leak, not just a bug.
+
+## Never export a module-scope `ref`
+
+A `ref` declared at module scope is created **once per server process** and shared
+by every request the server handles. During SSR that means one user can see
+another user's data. `useState(key, init)` creates state that is **per-request on
+the server** and hydrated to the client:
+
+```typescript
+// ❌ SHARED ACROSS ALL SSR REQUESTS — leaks state between users
+export const user = ref(null);
+
+// ✅ keyed, per-request, hydration-safe — wrap it in a composable
+export const useUser = () => useState("user", () => null);
+```
+
+Always expose `useState` through a `use*` composable so the key is defined once
+and can't drift between call sites.
+
+## Rules
+
+- **Provide a factory initializer:** `useState("count", () => 0)`. The init runs
+  on the server; the value is serialized into the payload and reused on the
+  client (no re-init, no mismatch).
+- **State must be JSON-serializable** — no class instances, functions, `Date`
+  round-trips, or `Map`/`Set`. It travels through the SSR payload as JSON.
+- **Same key = same state.** Two `useState("user")` calls anywhere in the app
+  read/write the same cell. Namespace keys for anything non-global.
+- **Reset with `clearNuxtState(key?)`** — clears one key or all keyed state (e.g.
+  on logout).
+
+```typescript
+// composables/useFilters.ts — app-wide filter state, survives navigation
+export const useFilters = () => useState("filters", () => ({ search: "", page: 1 }));
+```
+
+## `useState` vs the alternatives
+
+| Need | Reach for |
+|---|---|
+| Shared reactive state across components, SSR-safe | `useState` |
+| Per-request state that also persists in the browser across reloads | `useCookie` (small, ≤4 KB) — see [ssr-client.md](./ssr-client.md) |
+| Client-only persistence (no SSR) | VueUse `useLocalStorage` — see [ssr-client.md](./ssr-client.md) |
+| Cached server data | `useFetch`/`useAsyncData` (already keyed state) — see [fetch-patterns.md](./fetch-patterns.md) |
+
+`useState` is plain shared state; it does NOT fetch or cache. For server data,
+reach for `useAsyncData`/`useFetch` (which are themselves keyed payload state) and
+invalidate with `refreshNuxtData` rather than mirroring fetched data into a
+separate `useState`.
+
+## Run one-time init with `callOnce`
+
+To run a side effect **exactly once** across SSR + hydration (seed a store, fire a
+one-time analytics/init call), use `callOnce` — not `onMounted` + a flag, which
+re-fires on every client mount:
+
+```typescript
+await callOnce("init-analytics", () => initAnalytics());
+// mode: "navigation" (3.15+) re-runs once per client-side navigation instead of once ever
+```
+
+`callOnce` returns nothing — it's for effects. For data, use `useAsyncData` (which
+already de-dupes). The call must be unconditional (don't put it behind an `if`).

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

@@ -0,0 +1,59 @@
+# Storage (unstorage / `useStorage`)
+
+Nitro's `useStorage()` is a unified KV abstraction (powered by unstorage). It's
+the right tool for cross-request ephemeral state — rate-limit counters,
+idempotency keys, short-lived caches, one-off blobs — **without** a Postgres
+table. Auto-imported in `server/`.
+
+> This is a KV store, not the app database. Persistent relational data still lives
+> in Kysely/Postgres (`server/utils/db.ts`). Note both are called `useDatabase` in
+> their respective worlds — see [server-runtime.md](./server-runtime.md).
+
+## Basic use
+
+```typescript
+const store = useStorage("redis");        // a configured mount, or useStorage() for default (memory/fs)
+
+await store.setItem("rate:user:42", { count: 1, resetAt });
+const hit = await store.getItem<{ count: number }>("rate:user:42");
+await store.removeItem("rate:user:42");
+const keys = await store.getKeys("rate:");  // prefix scan
+```
+
+`setItem`/`getItem` JSON-serialize automatically; use `getItemRaw`/`setItemRaw`
+for binary/strings you don't want parsed.
+
+## Configuring mounts
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: {
+    storage: {
+      redis: { driver: "redis", url: process.env.REDIS_URL },
+    },
+    devStorage: {
+      redis: { driver: "fs", base: "./.data/redis" },  // dev override → local fs
+    },
+  },
+});
+```
+
+## Read bundled server assets
+
+Files under `server/assets/` are readable (read-only) via the `assets:server`
+mount — handy for seed data, templates, or fixtures shipped with the build:
+
+```typescript
+const seed = await useStorage("assets:server").getItem("seed.json");
+```
+
+## Gotchas
+
+- **Default mount is memory (dev) — not durable.** For anything that must survive
+  a restart or be shared across instances, configure a real driver (redis, fs, a
+  cloud KV).
+- **Multi-instance:** an in-memory mount is per-process; counters/locks across
+  replicas need a shared driver (redis).
+- **The `cache` mount** is what [caching.md](./caching.md) writes to — point it at
+  redis in prod so cached responses are shared.

package/plugins/volt-primevue/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "volt-primevue",
+  "description": "Volt (unstyled PrimeVue + Tailwind) UI: adding components, pt: pass-through styling, the surface-* vs semantic-token color model, and prefers-color-scheme dark mode",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

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

@@ -0,0 +1,170 @@
+---
+name: volt-primevue
+description: Build UIs with Volt (unstyled PrimeVue + Tailwind). Covers adding components, pt: pass-through customization, choosing components, and the two-layer color model for prefers-color-scheme dark mode.
+---
+
+# Volt + PrimeVue UI
+
+Volt components are **PrimeVue unstyled components styled with Tailwind**. They
+ship as source you vendor into `src/volt/` and register with a `Volt` prefix, so
+you own the markup but track upstream styling conventions.
+
+## When to Use This Skill
+
+- Building UI in a Nuxt + Tailwind v4 + PrimeVue/Volt project
+- Adding or customizing a Volt component
+- Anything color/theme/dark-mode related in this stack
+- Deciding between a Volt component and a hand-rolled one
+
+## What Volt is
+
+- PrimeVue **unstyled** components + Tailwind classes, vendored under `src/volt/`.
+- Registered with a `Volt` prefix via `nuxt.config.ts` (`<VoltButton>`, `<VoltCard>`, …).
+- `app/assets/css/main.css` has `@source "../../../src/volt";` so Tailwind scans
+  the vendored sources for class names. If a Volt class isn't generating, that
+  `@source` line is the first thing to check.
+
+## Adding components
+
+Use the CLI — **never hand-create a Volt component**:
+
+```bash
+npx volt-vue add MultiSelect      # adds src/volt/MultiSelect.vue
+```
+
+Hand-writing one means you've guessed the PrimeVue part structure and the
+`surface-*`/`dark:` conventions; the generator gets both right and stays
+consistent with upstream.
+
+**`volt-vue add` is a one-time fetch, not a sync channel.** Volt's docs are
+explicit that vendored components [aren't meant to be updated](https://volt.primevue.org/overview/)
+— once added, the file is yours and editing it is the *expected* path, not a
+fallback. There's no `volt-vue update`. Upstream **behavior/structure** fixes
+arrive by bumping the **`primevue`** version (the unstyled logic is imported from
+it); the **styling** is yours to keep. So "edit the vendored source" carries no
+hidden regeneration penalty — that escape hatch was never there to lose.
+
+## Customization — `pt:` pass-through
+
+Volt uses PrimeVue's pass-through API. Target a component's internal section with
+`pt:<section>:class`:
+
+```vue
+<VoltButton pt:root:class="bg-zinc-900 hover:bg-zinc-800" />
+<VoltCard pt:root:class="rounded-2xl" pt:body:class="p-6" />
+```
+
+**Use `pt:`, not a plain `class`.** Volt merges classes with
+[tailwind-merge](https://volt.primevue.org/overview/#twmerge), and the two paths
+differ in precedence:
+
+- `pt:{section}:class` is **merged with the component's defaults** and reliably
+  overrides them — `pt:root:class="bg-primary"` wins.
+- A plain `class="bg-primary"` has **lower precedence and may not apply** — its
+  conflicting utilities can lose to the component's own classes.
+
+So `<VoltInputText pt:root:class="bg-primary" />` works; `<VoltInputText
+class="bg-primary" />` may silently not.
+
+Both paths run through **`ptViewMerge` in `src/volt/utils.ts`**
+(`twMerge(globalClass, selfClass)` + Vue `mergeProps`), wired onto every component
+via `:ptOptions="{ mergeProps: ptViewMerge }"`. That local helper — not a global
+config — is the actual override point; it's *why* `pt:` reliably wins. To change
+merge behavior across components, edit `utils.ts`. See [gotchas.md](./gotchas.md).
+
+### Restyle component states with `p-*` variants
+
+Per-state styling (active, focus, disabled, invalid) is expressed declaratively in
+the class string via `tailwindcss-primeui` variants — `p-selected:`, `p-focus:`,
+`p-disabled:`, `p-editable:`, `p-invalid:` (you'll see them throughout the
+vendored sources). They're plain Tailwind variants, so you can **override a state's
+look through `pt:`** without touching DOM or source:
+
+```vue
+<VoltSelect pt:option:class="p-selected:bg-highlight p-focus:bg-surface-100" />
+```
+
+Reach for these before editing vendored source — restyling the *active* or
+*disabled* appearance rarely needs a source edit.
+
+What `pt:` **can't** do is change DOM — it only restyles sections the component
+already renders. To add an element the component doesn't have (e.g. an animated
+overlay), you have two honest options, because Volt components are **vendored and
+yours to edit** (see [Choosing a component](#choosing-a-component-volt-vs-custom)):
+edit the component's source in `src/volt/`, or build a standalone component.
+
+## Choosing a component: Volt vs custom
+
+Volt gives you selection semantics + accessibility for free. The question is only
+whether you need DOM/behavior the component doesn't render — and remember Volt
+components are **vendored and editable**, so "the component doesn't do X" has
+three answers, not two: restyle via `pt:`, **edit the source in `src/volt/`**, or
+build standalone.
+
+Worked example — **segmented toggle** (`SelectButton` vs a custom `SlidingTabs`).
+*Illustrative:* `SelectButton` isn't vendored in every project (e.g. not in this
+repo's `src/volt/` by default) — you'd `npx volt-vue add SelectButton` first.
+
+- `VoltSelectButton` ships v-model, single/multi-select, label+icon options, and
+  proper radiogroup a11y, with a *highlighted-active* look.
+- A custom `SlidingTabs` adds an **animated indicator** (a single shared element
+  that measures the active button and slides), responsive label collapse, and
+  token-matched styling.
+- The active/focus/disabled *look* **is** `pt:`-reachable (via the `p-selected:`/
+  `p-focus:` variants above). What `pt:` can't add is the **shared sliding
+  element** — `SelectButton` toggles a per-button background and has no single
+  position-measured overlay, and `pt:` changes classes, not DOM. Adding that
+  indicator means editing the vendored `SelectButton.vue` (you keep its a11y +
+  selection model) or building standalone.
+
+So the real decision:
+
+- **No animation needed → `SelectButton` as-is** (`pt:` to match your design).
+  Free a11y + multi-select; don't reinvent it.
+- **Animated indicator / responsive collapse needed →** either **edit the
+  vendored `SelectButton`** (keep its a11y; you own the file — which is true the
+  moment you `volt-vue add` it anyway, so there's no regeneration to forfeit) **or
+  build a standalone `SlidingTabs`** (clean and decoupled, but you owe the a11y
+  yourself — `role="group"` + `aria-pressed` at minimum). Standalone wins when
+  it's a *filter* toggle rather than a form field; editing the source wins when
+  you want the full input semantics.
+
+## Theming & dark mode
+
+This is the part people get wrong. Read **[theming.md](./theming.md)** — the
+two-layer color model (`surface-*` for Volt, semantic tokens for your markup),
+why they can't be unified, and the `prefers-color-scheme` mechanics.
+
+The one-paragraph version: dark mode follows the OS via
+`@media (prefers-color-scheme: dark)`. **Your app markup** uses semantic `@theme`
+tokens (`bg-surface`, `text-fg`, `border-line`) written **once** — the
+`--color-*` var flips in the dark media block, so there's no `dark:` half to
+forget. **Volt internals** stay on the `surface-*` scale with explicit `dark:`
+pairs — they need the full 0–950 ramp, and leaving them as `volt-vue add`
+generated them keeps regeneration easy. You *could* restyle a vendored component
+to tokens (it's your code), but the small token set can't express the whole ramp,
+so don't — tokens for your opinionated markup, `surface-*` for the component
+library.
+
+## Gotchas
+
+See **[gotchas.md](./gotchas.md)** — the ones that cost real debugging time:
+
+- `@reference "main.css"` (not `"tailwindcss"`) for `@apply` of custom tokens in
+  SFC `<style>` blocks.
+- JS-driven colors (ApexCharts, canvas) can't read CSS tokens — pick them from a
+  reactive `prefers-color-scheme` palette.
+- A bare `boolean` prop casts to `false` when absent — default it with
+  `withDefaults`, never rely on `undefined`.
+- The class merge lives in `ptViewMerge` (`src/volt/utils.ts`) — the lever when a
+  `pt:` override won't take.
+- `data-pc-name` / `data-pc-section` to reach internals from CSS; `pc`-prefixed
+  section names (`pt:pcBadge:…`) for nested child components.
+- We deliberately **don't** use `@primevue/forms` — zod + manual wiring instead.
+
+## Plugin config
+
+See **[config.md](./config.md)** for PrimeVue plugin options beyond colors —
+global `pt` defaults, `ptOptions` merge behavior, `zIndex` overlay stacking, and
+`locale`. (Keep `unstyled: true`; styled-mode `definePreset`/`theme.preset` are
+inert — see [theming.md](./theming.md).)

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

@@ -0,0 +1,51 @@
+# PrimeVue plugin config
+
+Options passed where PrimeVue is registered (`app.use(PrimeVue, { … })` / the Nuxt
+module config), beyond colors. Volt runs **`unstyled: true`** — keep that; it's
+what makes the components unstyled (and what makes styled-mode theming inert; see
+[theming.md](./theming.md)).
+
+## App-wide section styling: global `pt`
+
+Instead of repeating the same `pt:` on every call site, set defaults once with a
+global `pt` object keyed by lowercase component name → sections. A component-level
+`pt:` still overrides the global:
+
+```ts
+app.use(PrimeVue, {
+  unstyled: true,
+  pt: {
+    dialog: { header: { class: "border-b border-line" } },  // every dialog's header
+    select: { dropdown: { class: "text-fg-muted" } },
+  },
+  ptOptions: { mergeSections: true, mergeProps: true },
+});
+```
+
+`ptOptions` governs how global + local combine: `mergeSections` (default `true`)
+merges section objects; `mergeProps` (default `false`) merges class/listener
+props rather than replacing. Set `mergeProps: true` if you want a call-site
+`pt:` to *add to* the global classes instead of replacing them. (Note the vendored
+components already pass their own `mergeProps: ptViewMerge` per-component — see
+[gotchas.md](./gotchas.md).)
+
+## Config knobs worth knowing
+
+```ts
+app.use(PrimeVue, {
+  unstyled: true,
+  zIndex: { modal: 1100, overlay: 1000, menu: 1000, tooltip: 1100 },  // overlay stacking
+  locale: { /* aria, filter, date strings — overrides built-in en defaults */ },
+});
+```
+
+- **`zIndex`** — the dial when a Volt overlay (dialog, menu, tooltip) renders
+  under or over app chrome. Defaults: modal/tooltip `1100`, overlay/menu `1000`.
+- **`locale`** — overrides all built-in aria labels, filter/date/pagination
+  strings (i18n, or just rewording an aria label).
+- **`inputVariant: 'outlined' | 'filled'`** — default `outlined`; affects input
+  styling defaults.
+- **`ripple`** — irrelevant under unstyled (no ripple CSS), harmless if set.
+
+Don't set `theme` / `definePreset` — inert under `unstyled: true`
+([theming.md](./theming.md)).

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

@@ -0,0 +1,115 @@
+# Gotchas
+
+The ones that cost real debugging time in this stack.
+
+## `@apply` of custom tokens in `<style>` needs `@reference "main.css"`
+
+Tailwind v4 SFC `<style>` blocks need a `@reference` to resolve `@apply`. The
+trap: `@reference "tailwindcss"` only loads the **default** theme — built-in
+colors (`zinc`, etc.) work, but your custom `@theme` tokens (`text-fg`,
+`bg-surface`) fail with *"Cannot apply unknown utility class."*
+
+```vue
+<style scoped>
+/* ❌ @reference "tailwindcss";  → @apply text-fg fails */
+@reference "../assets/css/main.css";   /* ✅ exposes your tokens */
+.prose :where(h2) { @apply text-fg; }
+</style>
+```
+
+`@reference` is relative to the SFC. Note `yarn build` validates `@apply` in
+`<style>`; a bare `@tailwindcss/cli` compile does **not**, so the CLI can pass
+while the real build fails — include `build` in your check.
+
+## JS-driven colors can't read CSS tokens — use a reactive palette
+
+Anything that sets 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. Pick concrete colors from a reactive `prefers-color-scheme`
+match and recompute on change:
+
+```ts
+const isDark = ref(false);
+let mq: MediaQueryList | null = null;
+const sync = () => (isDark.value = mq?.matches ?? false);
+onMounted(() => {
+  mq = window.matchMedia("(prefers-color-scheme: dark)");
+  sync();
+  mq.addEventListener("change", sync);
+});
+onBeforeUnmount(() => mq?.removeEventListener("change", sync));
+
+const palette = computed(() =>
+  isDark.value ? { fg: "#f4f4f5", line: "#f4f4f5", grid: "#27272a" }
+               : { fg: "#18181b", line: "#18181b", grid: "#f4f4f5" });
+```
+
+Mirror the dark values from `main.css`. A chart `colors: ["#18181b"]` (near-black)
+is invisible on dark — invert the line to a light value via the palette.
+
+## A bare `boolean` prop casts to `false` when absent — `withDefaults` it
+
+Vue's Boolean-prop casting: a prop typed `boolean` with **no default** coerces to
+`false` when the parent doesn't pass it — *not* `undefined`. So a "default-on"
+flag written as `responsive?: boolean` + `props.responsive !== false` is always
+`false` unless explicitly passed, and the feature silently never fires.
+
+```ts
+// ❌ absent → false → feature off, no error
+const props = defineProps<{ responsive?: boolean }>();
+// ✅ absent → true
+const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive: true });
+```
+
+Not Volt-specific, but it bit the `SlidingTabs` responsive collapse, so it lives
+here. Any "defaults to on" boolean prop must use `withDefaults` (or invert it to
+an opt-out flag that naturally defaults false).
+
+## The class merge lives in `src/volt/utils.ts` (`ptViewMerge`)
+
+When a `pt:` class won't override, or you want to change how a component's own
+classes combine with yours, the lever is **not** a global PrimeVue config — it's a
+local helper. Every vendored component sets `:ptOptions="{ mergeProps: ptViewMerge }"`,
+and `ptViewMerge` (in `src/volt/utils.ts`) does `twMerge(globalClass, selfClass)`
+then Vue `mergeProps`:
+
+```ts
+export const ptViewMerge = (globalPTProps = {}, selfPTProps = {}, datasets) => {
+  const { class: globalClass, ...globalRest } = globalPTProps;
+  const { class: selfClass, ...selfRest } = selfPTProps;
+  return mergeProps({ class: twMerge(globalClass, selfClass) }, globalRest, selfRest, datasets);
+};
+```
+
+That `twMerge` is why a conflicting `pt:` utility wins (last-writer in the merge)
+and a plain `class` may not. Debugging an override that won't take? Look here, not
+at a config flag.
+
+## Reaching internals from CSS: `data-pc-name` / `data-pc-section`
+
+When `pt:` class styling isn't enough — you need to style a component's internals
+from a parent `<style>` block or third-party CSS — PrimeVue stamps stable
+`data-pc-name="<component>"` and `data-pc-section="<section>"` attributes on its
+DOM. Target those instead of brittle structural selectors:
+
+```css
+[data-pc-name="select"] [data-pc-section="dropdown"] { /* … */ }
+```
+
+## Styling a nested child component: the `pc`-prefixed section
+
+When one PrimeVue component renders another inside it, the inner one's `pt`
+section name is prefixed **`pc`** (e.g. a Badge embedded in another component is
+`pcBadge`). Address it through the prefix; a flat section name silently fails:
+
+```vue
+<VoltSomething pt:pcBadge:root:class="bg-red-500" />
+```
+
+## We don't use `@primevue/forms`
+
+This stack validates with **zod + manual wiring**, not `@primevue/forms`. The
+package's `zodResolver` looks tempting given how much zod is already around, but
+its ergonomics weren't worth the workarounds. Don't reach for it — drive
+validation from the zod schema directly (`safeParse` in the submit handler, or a
+small `useFormState`-style composable).

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

@@ -0,0 +1,137 @@
+# Theming & dark mode
+
+Dark mode follows the OS: `@media (prefers-color-scheme: dark)`. No toggle, no
+`dark` class on `<html>`. Tailwind v4's `dark:` variant also keys on
+`prefers-color-scheme` by default, so everything reacts to the same signal.
+
+There are **two color systems** in play, and the whole skill is knowing which to
+use where.
+
+## The two layers
+
+| | App markup (you own) | Volt internals (vendored) |
+|---|---|---|
+| **System** | semantic `@theme` tokens | `surface-*` scale + `dark:` pairs |
+| **Example** | `bg-surface text-fg` | `bg-surface-0 dark:bg-surface-900` |
+| **How it flips** | the `--color-*` var changes value in the dark media block | each shade is fixed; the component picks the dark end with `dark:` |
+| **You write** | once | both halves |
+
+### Why not use semantic tokens everywhere (incl. Volt)?
+
+You *can* — Volt components are vendored and editable, so nothing stops you from
+restyling one to `bg-surface text-fg`. The reasons not to are practical, in
+descending order of weight:
+
+1. **Vocabulary mismatch (the real one).** Semantic tokens are a small,
+   opinionated set (`surface`, `surface-muted`, `line`, `fg`, `fg-muted`, …) for
+   "card / text / border" decisions. A component library reaches all over the
+   0–950 ramp — subtle fills, two border weights, icon idle vs hover, elevation
+   layering. To express all of Volt in tokens you'd expand them until they *are*
+   the ramp, at which point you've just renamed `surface-*`.
+2. **Consistency with newly-added siblings.** `volt-vue add` always scaffolds in
+   the upstream `surface-*` + `dark:` convention, so keeping existing components on
+   it means every Volt file reads the same way and a freshly-added one drops in
+   without restyling. This is a mild *consistency* benefit, **not** a regeneration
+   one: there's no `volt-vue update` and no continuous sync — you own each file the
+   moment you add it, edits or not. (Upstream behavior fixes ride the `primevue`
+   version bump, not a re-add.)
+3. **The convention they ship in.** As generated, `--p-surface-0…950` are fixed
+   (never flipped), so a Volt component flips by *picking the dark end* with
+   `dark:bg-surface-900` — not by a value that changes. Semantic tokens flip the
+   variable's value instead, so one class covers both schemes. You could rewrite
+   a component to the token style, but then you're back to reasons 1 and 2.
+
+## The token set
+
+Defined in `app/assets/css/main.css`: light values in a top-level `@theme`
+block, dark values overriding the same `--color-*` vars inside the
+`prefers-color-scheme: dark` media block.
+
+```css
+@theme {
+  --color-canvas: #fafafa;        /* app background */
+  --color-surface: #ffffff;       /* cards, panels, dialogs */
+  --color-surface-muted: #fafafa; /* subtle fills, row hover */
+  --color-line: #e4e4e7;          /* borders */
+  --color-line-soft: #f4f4f5;     /* soft dividers */
+  --color-fg: #18181b;            /* primary text */
+  --color-fg-muted: #71717a;      /* secondary text */
+  --color-fg-subtle: #a1a1aa;     /* tertiary text */
+  --color-accent: #18181b;        /* inverted/primary fills (buttons) */
+  --color-on-accent: #ffffff;     /* text/icon on an accent fill */
+  --color-fill: #e4e4e7;          /* neutral solid fills: avatars, tracks, dots */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-canvas: #09090b;
+    --color-surface: #18181b;
+    --color-surface-muted: #27272a;
+    --color-line: #27272a;
+    --color-line-soft: #27272a;
+    --color-fg: #f4f4f5;
+    --color-fg-muted: #b4b4bc;    /* lifted off a strict mirror-invert for legibility */
+    --color-fg-subtle: #8c8c95;   /* ~5.5:1 on near-black */
+    --color-accent: #f4f4f5;      /* inverts so filled buttons read on dark */
+    --color-on-accent: #18181b;
+    --color-fill: #3f3f46;
+  }
+}
+```
+
+The dark `fg-muted` / `fg-subtle` are **lifted** off a strict mirror-invert —
+the perfectly-inverted values are too dark to read on near-black.
+
+### Where each layer lives (and why it's not fighting Volt)
+
+[Volt's Nuxt setup](https://volt.primevue.org/nuxt/#css-variables) prescribes the
+`--p-*` palette + semantic tokens in **`:root`**, with dark mode via
+`@media (prefers-color-scheme: dark)`. Keep that exactly as-is — don't move
+`--p-*` into `@theme`; the `tailwindcss-primeui` plugin already turns them into
+`surface-*` / `primary-*` utilities.
+
+Your semantic tokens go in **`@theme`** instead, because that's the Tailwind v4
+mechanism that generates the utilities (`--color-canvas` → `bg-canvas`). Defining
+them only in `:root` would set the variable but produce **no class**. So:
+
+- `--p-*` → `:root` (Volt's way; plugin generates `surface-*`)
+- `--color-*` → `@theme` (Tailwind's way; generates `bg-surface`, `text-fg`, …)
+
+Different namespaces, no collision: `bg-surface-0` (primeui, numbered) and
+`bg-surface` (your token, bare) coexist. Dark values for **both** sit in the same
+`prefers-color-scheme` block — your `--color-*` overrides next to Volt's `--p-*`
+overrides.
+
+## Ignore styled-mode theming (`definePreset`, `theme.preset`)
+
+Most PrimeVue theming docs describe **styled** mode — `definePreset`, `theme: {
+preset: Aura }`, component design tokens like `button.background`. Volt runs
+PrimeVue with **`unstyled: true`**, which turns all of that **off**: the built-in
+CSS and preset machinery aren't loaded, so a `definePreset`/`theme.preset` config
+does nothing here. If you're following a primevue.org theming tutorial and it
+reaches for `definePreset`, stop — that's the wrong layer. Your knobs are the
+`--p-*` variables in `:root` (Volt's way) plus the Tailwind `@theme` tokens above.
+
+(The `--p-*` variable **prefix** still applies — `tailwindcss-primeui` reads it.
+It's the preset/design-token *machinery* that's inert, not the variables.)
+
+## The naming trap (this one bites)
+
+In Tailwind v4 the utility name is the **full** variable suffix:
+
+- `--color-fg-subtle` → `text-fg-subtle`  ✅
+- `text-subtle` ❌ — generates **nothing**, element falls back to near-black
+
+A wrong/shortened token name fails silently (no class generated), so a
+suspicious "secondary text is black in dark mode" is almost always a misnamed
+token, not a wrong value. **Compile the CSS and grep the generated utilities** —
+don't eyeball the browser.
+
+## Adding a new token
+
+1. Add `--color-foo: <light>;` to the `@theme` block.
+2. Add `--color-foo: <dark>;` inside the dark media block.
+3. Use `bg-foo` / `text-foo` / `border-foo` — done, both schemes covered.
+
+No `dark:` variant, ever, for app markup. If you're typing `dark:` in a page or
+app component, you're reaching for the wrong layer.

package/plugins/vue-nuxt/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "vue-nuxt",
+  "description": "Vue 3 component authoring inside a Nuxt 4 app: auto-import rules, props/emits/withDefaults, v-model/defineModel, reactivity, when watch is a smell, and template idioms",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}