@gallopsystems/agent-skills 1.5.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/skills/volt-primevue/SKILL.md

@@ -36,6 +36,14 @@ 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
@@ -58,6 +66,27 @@ differ in precedence:
 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
@@ -72,30 +101,33 @@ 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`):
+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 slide **can't** come from `pt:` — `SelectButton` toggles a background class
-  per button and has no shared, position-measured overlay, and `pt:` changes
-  classes, not DOM. But that doesn't force a rewrite: since the source lives in
-  `src/volt/SelectButton.vue`, adding the indicator **there** is a legitimate
-  option (you keep its a11y + selection model).
+- 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, accept that you now own that file and
-  lose easy `volt-vue add` regeneration) **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.
+  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
 
@@ -124,3 +156,15 @@ See **[gotchas.md](./gotchas.md)** — the ones that cost real debugging time:
   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

@@ -64,3 +64,52 @@ const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive
 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

@@ -28,12 +28,13 @@ descending order of weight:
    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. **Regeneration convenience.** `volt-vue add` scaffolds a component in the
-   upstream `surface-*` + `dark:` convention. Restyle it and you own that file —
-   re-adding or pulling a newer version later means redoing your edits. Leaving
-   Volt as-generated keeps that escape hatch cheap. (This is a convenience cost,
-   not "you diverge from upstream forever" — there's no continuous sync; you add
-   once and own it either way.)
+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
@@ -101,6 +102,19 @@ Different namespaces, no collision: `bg-surface-0` (primeui, numbered) and
 `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:

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"
+  }
+}

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

@@ -0,0 +1,48 @@
+---
+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, reactivity, when watch is a code smell, and Vue-shaped template idioms.
+---
+
+# Vue-in-Nuxt component authoring
+
+Patterns for writing Vue 3 `<script setup>` components inside a Nuxt 4 app. This
+is the **frontend authoring** slice — the data layer (`useFetch`/`$fetch`, SSR
+storage, hydration, `definePageMeta`/auth, formatters) lives in the
+`nuxt-nitro-api` skill; Volt/PrimeVue styling and dark mode live in
+`volt-primevue`. This skill cross-links to those rather than restating them.
+
+## When to Use This Skill
+
+- Authoring or reviewing a `.vue` component in a Nuxt 4 project
+- Deciding how a component is named / auto-imported
+- Typing props & emits, defaulting props, building a generic component
+- Wiring `v-model` on a component
+- Designing a component's content API — props vs slots, named/scoped slots
+- Authoring a composable — argument shape, what to return, cleanup
+- Anything reactivity-shaped: `computed` vs `watch`, prop→state sync, DOM measurement
+- You see `watch` and want to know if it should be something else
+
+## Reference Files
+
+- [auto-imports.md](./auto-imports.md) — what auto-imports (components with dir-prefix names, composables, utils, Vue/Nuxt APIs) and what does NOT (third-party, types, test files)
+- [component-authoring.md](./component-authoring.md) — type-only `defineProps`/`defineEmits`, `withDefaults`, the Boolean-prop trap, factory defaults, generic components, `defineExpose`, what to extract into a shared component
+- [v-model.md](./v-model.md) — `defineModel` vs the props+emit+computed proxy, named models, paired fields
+- [slots.md](./slots.md) — slots vs props for markup, named/scoped slots, `defineSlots`/`useSlots`, avoiding empty wrappers, forwarding, slot transitions
+- [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
+- [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
+
+## Core Principles
+
+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).
+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.
+
+## Contributing Back
+
+If you hit a Vue-in-Nuxt authoring gotcha this skill doesn't cover (or one it gets
+wrong), upstream it — run `/contribute-skill`.

package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md

@@ -0,0 +1,48 @@
+# Nuxt auto-imports
+
+Nuxt auto-imports your own UI surface and the Vue/Nuxt APIs. Add an explicit
+`import` only for third-party symbols and TypeScript types. Knowing exactly what
+resolves — and how component tags are named — prevents the silent "renders
+nothing" failures.
+
+## Components: the tag carries the directory prefix
+
+Files in `app/components` auto-import with **no manual import**. A nested
+component's tag is the PascalCased **directory path prefixed onto** the
+PascalCased filename:
+
+| File | Tag |
+|---|---|
+| `app/components/AppHeader.vue` | `<AppHeader>` |
+| `app/components/customers/ProfileCard.vue` | `<CustomersProfileCard>` |
+| `app/components/form/FileUpload.vue` | `<FormFileUpload>` |
+| `app/components/settings/Sidebar.vue` | `<SettingsSidebar>` |
+
+- **Name to avoid stutter.** Put `ProfileCard.vue` in `customers/` → `<CustomersProfileCard>`, not `CustomerProfileCard.vue` → `<CustomersCustomerProfileCard>`.
+- **Guessing the bare filename fails silently.** `<FileUpload>` for `form/FileUpload.vue` resolves to nothing — no error, just an unrendered tag. If a component "isn't showing up," check the prefix first.
+- **Want a clean unprefixed tag?** Either explicitly import it
+  (`import EstimateHeader from '~/components/estimates/EstimateHeader.vue'`), or
+  register a directory with a prefix in `nuxt.config` (`components: [{ path: '../src/volt', prefix: 'Volt' }]` → `<VoltButton>`).
+
+## What auto-imports (no `import` line)
+
+- **Vue reactivity & lifecycle:** `ref`, `shallowRef`, `reactive`, `computed`, `watch`, `watchEffect`, `onWatcherCleanup`, `toValue`/`toRef`/`toRefs`, `useTemplateRef`, `useId`, `effectScope`/`onScopeDispose`, `onMounted`, `onBeforeUnmount`/`onUnmounted`, `nextTick`, `defineProps`/`defineEmits`/`defineModel`/`withDefaults`/`defineOptions`, `resolveComponent`.
+- **Nuxt helpers:** `useRoute`, `useRouter`, `navigateTo`, `useFetch`, `$fetch`, `useAsyncData`, `useState`, `useCookie`, `useRuntimeConfig`, `useHead`, `definePageMeta`, `useNuxtApp`.
+- **Your `app/composables`** (`useFoo`) and **`app/utils`** (pure helpers, by bare name) — app-wide.
+- **`<NuxtLink>`, `<NuxtPage>`, `<NuxtLayout>`, `<ClientOnly>`, `<Teleport>`** in templates.
+
+Reach for `#imports` (`import { useFoo } from '#imports'`) only to disambiguate a
+naming collision.
+
+## What does NOT auto-import (import explicitly)
+
+- **Third-party composables/components:** `useToast` from `'primevue/usetoast'`, `Column` from `'primevue/column'`, `date-fns` helpers, etc.
+- **TypeScript types** — interfaces, enums, type aliases are never auto-imported. `import type { Foo } from '...'`.
+- **`server/utils`** — auto-imported on the *server* only, never into client code.
+- **Vitest unit tests** — plain `*.test.ts` files do NOT get Nuxt's auto-import context. Import the composable/util under test explicitly: `import { useFormatters } from './useFormatters'`. (Component tests via `@nuxt/test-utils/runtime` + `mountSuspended` DO have the context — see the `nitro-testing` skill.)
+
+## Consistency caveat
+
+Some repos still write explicit `import { ref } from 'vue'` everywhere. **Match
+the file you're editing** — but the default for new code is to rely on
+auto-import.

package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md

@@ -0,0 +1,159 @@
+# Component authoring
+
+Type-only macros, props/emits, the Boolean trap, generics, and what to extract.
+
+## Props & emits: type-only macros
+
+Declare props and emits with the type-only generic form; emit payloads as named
+tuple types:
+
+```ts
+const props = defineProps<{ label: string; size?: 'sm' | 'md'; rows: Row[] }>()
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  saved: []
+  rowClick: [row: Row]
+}>()
+```
+
+Use the runtime/object form only when you need `withDefaults`.
+
+### Forward many props / handlers at once
+
+Spread a whole object of props with `v-bind="obj"`, or a map of handlers with
+`v-on="handlers"`, instead of listing each:
+
+```vue
+<UserCard v-bind="user" v-on="cardHandlers" />
+<!-- equivalent to :name="user.name" :email="user.email" … @edit="…" @delete="…" -->
+```
+
+Handy for forwarding `$attrs`/`$props` straight through a thin wrapper component
+(`<Inner v-bind="$attrs" />`). Be deliberate, though — spreading a large object
+binds *every* key, which can pass props the child didn't ask for.
+
+When you forward `$attrs` onto a specific inner element, set `inheritAttrs: false`
+via **`defineOptions`** so Vue doesn't *also* dump them on the root — the only
+`<script setup>`-native way to set component options (`name`, `inheritAttrs`):
+
+```ts
+defineOptions({ inheritAttrs: false })
+// then: <input v-bind="$attrs" />   — attrs land only where you put them
+```
+
+## Defaulting props: reactive destructure (3.5) vs `withDefaults`
+
+As of Vue 3.5, you can **destructure** `defineProps` and give defaults with `=`.
+The compiler rewrites each reference back to `props.x`, so reactivity is
+preserved, and — unlike `withDefaults` — **non-primitive defaults need no
+factory**. This is now the idiomatic way to default props:
+
+```ts
+const { responsive = true, size = 'md', items = [] } = defineProps<{
+  responsive?: boolean; size?: 'sm' | 'md'; items?: Item[]
+}>()
+// items = [] is safe here — no shared-reference leak, no factory needed
+```
+
+One gotcha: passing a destructured prop into a `watch` source or a standalone
+function **snapshots** it (you destructured a value, not a ref), losing
+reactivity. Wrap it in a getter:
+
+```ts
+watch(() => responsive, onChange)   // ✅   watch(responsive, …) ❌ passes a bool, never re-fires
+```
+
+`withDefaults(defineProps<…>(), {…})` remains correct and is what you'll see in
+existing code — match the file you're in. The two sections below describe the
+traps `withDefaults` has that destructure defaults sidestep.
+
+## The Boolean prop trap (the most-cited authoring gotcha)
+
+A bare `boolean` prop is subject to Vue's **Boolean casting**: when the attribute
+is absent it coerces to **`false`**, not `undefined`. So `props.flag ?? true`
+never sees `undefined`, and a "defaults-on" flag silently stays off.
+
+```ts
+// ❌ absent → false → feature silently disabled (typechecks fine)
+const props = defineProps<{ responsive?: boolean }>()
+const on = props.responsive !== false // always false when not passed
+
+// ✅ default it explicitly
+const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive: true })
+```
+
+Any boolean that should default **on** MUST be defaulted explicitly — via
+destructure (`const { responsive = true } = defineProps<…>()`) or `withDefaults`
+— or be inverted to an opt-*out* flag that naturally defaults `false`. (The
+Boolean casting still happens; the default just gives the absent case a value.)
+
+## Factory defaults for arrays/objects
+
+Non-primitive defaults need a **factory** in `withDefaults`, or every instance
+shares one object:
+
+```ts
+withDefaults(defineProps<{ items?: Item[]; config?: Cfg }>(), {
+  items: () => [],          // ✅ factory
+  config: () => ({ x: 1 }), // ✅ factory
+})
+// ❌ { items: [] } — one array shared across all instances, leaks state
+```
+
+Bare literals are only safe for primitives (`isAdmin: false`, `size: 'md'`). This
+factory requirement is a `withDefaults`-ism — reactive destructure defaults
+(`{ items = [] } = defineProps(…)`) take a plain literal safely.
+
+## Generic components
+
+Declare the type param in the tag and thread it through props/emits so a
+tabs/select preserves the caller's literal union instead of widening to `string`:
+
+```vue
+<script setup lang="ts" generic="T extends string">
+const props = defineProps<{ modelValue: T; options: readonly { value: T; label: string }[] }>()
+const emit = defineEmits<{ 'update:modelValue': [value: T] }>()
+</script>
+```
+
+## `defineExpose` — the sanctioned imperative escape hatch
+
+Expose child methods for a parent to call (reset a form after save, trigger
+submit from a dialog footer) instead of prop hacks:
+
+```ts
+defineExpose({ reset, submit })
+// parent: const child = useTemplateRef('child'); child.value?.reset()
+```
+
+## What to put in a shared component vs leave in the caller
+
+When extracting, a **composable shares logic-only**; a **component shares
+markup + logic**. Extract only the genuinely universal surface and leave
+page-specific chrome in each caller. E.g. a reusable `<Dropzone>` owns the
+drag/drop box and file handling; the page keeps its own heading, helper banner,
+and "or paste text" affordance. If you find yourself adding props just to toggle
+caller-specific chrome inside the shared component, that chrome belongs in the
+caller.
+
+## Type off the server contract, don't hand-write DTOs
+
+Derive prop/state types from the data you fetch rather than redeclaring an
+interface that drifts from the API:
+
+```ts
+// from a fetch ref:
+type Project = NonNullable<typeof projects.value>[number]
+// or an endpoint-response helper indexing the generated InternalApi (illustrative —
+// the general rule is "derive from the endpoint type, never hand-write the DTO";
+// see nuxt-nitro-api/fetch-patterns.md type-extraction)
+```
+
+## Advanced: config-driven generic shells
+
+A generic table/form shell can take a typed config array
+(`columns: Column[]`, `fields: FormField[]`) whose entries optionally carry a
+`template?: Component` rendered via `<component :is="col.template" v-bind="...">`,
+plus `defineExpose`d imperative methods. Powerful, but it's an advanced pattern —
+reach for it only when several call sites genuinely share the shell, not as a
+default.