rsc-universal 0.1.1

package/skills/vue-nuxt/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: vue-nuxt
+description: "Use when building, reviewing, or optimizing a Vue 3 + Nuxt 4 app — Composition API/`<script setup>`, SSR/SSG/hybrid rendering, the `app/`+`server/` structure, SSR-safe data fetching and shared state, Nitro server routes, reactivity/hydration discipline. Triggers: `.vue` SFCs, `useFetch`/`useAsyncData`/`$fetch`, `useState`/Pinia, `defineModel`/`useTemplateRef`, hydration node mismatch, double-fetch on SSR, `server/api` handlers, `routeRules`, Nuxt 3→4 migration, `nuxt.config.ts`, 'app SSR no hidrata', 'per què es fa doble fetch'. NOT React/RSC (that is nextjs), NOT a static multi-framework site (that is astro)."
+tags: [vue, nuxt, frontend, web, ssr]
+recommends: [design, deployment, secure-coding]
+origin: risco
+---
+
+# Vue 3 + Nuxt 4 — Composition API, SSR, SSR-safe data & state
+
+Build and review Vue 3 (`<script setup>` + Composition API) on the Nuxt 4 meta-framework:
+SSR/SSG/hybrid rendering, the `app/` + `server/` layout, SSR-safe fetching and state, Nitro
+server routes, and the reactivity discipline that keeps hydration correct. Nuxt's render model
+is **whole-component render-then-hydrate** — there is no React-style "server component" boundary.
+
+## When to use
+
+- Editing/creating `.vue` SFCs, `composables/`, `app/pages/`, `app/layouts/`, `server/api/`.
+- Choosing `useFetch` vs `useAsyncData` vs raw `$fetch`; fixing a double-fetch on SSR or a
+  hydration mismatch ("Hydration node mismatch", "text content did not match").
+- SSR-safe shared state: `useState` vs Pinia; stopping cross-request state leakage on the server.
+- Reactivity: `ref`/`reactive`/`computed`, `watch` vs `watchEffect`, reactive props destructure,
+  `defineModel`, `useTemplateRef`, lost reactivity after destructuring.
+- Nitro server routes, `useRuntimeConfig`, private vs `public` runtime config.
+- Nuxt 3 → Nuxt 4 migration (the `app/` srcDir move, shared-key data, shallowRef payload).
+- Rendering strategy: `routeRules` for per-route SSR/SSG/ISR/SWR/SPA.
+
+## When NOT to use
+
+- React / Next.js, App Router, RSC, server actions → `../nextjs/SKILL.md` or `../react/SKILL.md`.
+  Do not import RSC mental models here — Vue has no server-component boundary.
+- Content-first static site mixing frameworks/islands → `../astro/SKILL.md`. Fine-grained signals
+  framework → `../solid-js/SKILL.md`. Compiler-first no-VDOM peer → `../svelte/SKILL.md`.
+  Angular → `../angular/SKILL.md`.
+- Backend not in Nitro/JS (Python/Go/PHP) → `../fastapi/SKILL.md`, `../go/SKILL.md`,
+  `../laravel/SKILL.md`.
+- E2E or component-test *strategy* depth → `../e2e-testing/SKILL.md` / `../testing-web/SKILL.md`
+  (this skill states the Vitest + `@vue/test-utils` + `@nuxt/test-utils` setup, defers strategy).
+- Deploy-platform specifics (the Vercel/Netlify/Cloudflare adapters) → `../deployment/SKILL.md`,
+  `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md`. This skill picks the
+  Nitro preset; those own the platform.
+- Generic security review → `../secure-coding/SKILL.md`; SEO/content strategy → `../marketing/SKILL.md`.
+
+## First: detect Nuxt vs plain Vue, and the version
+
+Never prescribe `useFetch`/`useState`/auto-imports in a project that does not have them. Detect
+before you write a line.
+
+| Signal in the repo | Verdict | What is available |
+|---|---|---|
+| `nuxt.config.{ts,js,mjs}` + `app/` dir holding `pages/`,`components/` | **Nuxt 4** (current) | full auto-imports, `useFetch`/`useState`, `server/`, `routeRules` |
+| `nuxt.config.*` + root `pages/`,`components/` (no `app/`) | **Nuxt 3 layout** | same APIs; flag the migration (see `references/migration-nuxt4.md`) |
+| `vite.config.*` + `createApp(...).mount(...)`, no `nuxt.config` | **plain Vue 3 SPA** | Vue reactivity only — NO `useFetch`/`useState`/Nitro/auto-imports |
+
+Rule: in a plain-Vue SPA, fetch with the browser `fetch`/a client library inside `onMounted` or a
+composable, manage shared state with `reactive`/`provide`/Pinia — `useFetch`/`useState` do not
+exist there. Confirm `nuxt` is in `package.json` before reaching for any Nuxt API.
+
+## Composition API & reactivity core
+
+Use `<script setup lang="ts">` for every SFC. Prefer `ref` over `reactive` — `ref` survives
+destructuring through `.value`, works for primitives, and reads uniformly. Reach for `reactive`
+only for a grouped object you never destructure.
+
+```vue
+<script setup lang="ts">
+import { ref, computed, watch, onWatcherCleanup } from 'vue'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2)        // cached, recomputes on dep change
+
+watch(count, async (next, _prev, onCleanup) => {        // explicit dep, gets old value
+  const ctrl = new AbortController()
+  onCleanup(() => ctrl.abort())                          // or onWatcherCleanup(...) (3.5)
+  await fetch(`/api/log?n=${next}`, { signal: ctrl.signal })
+})
+</script>
+```
+
+`watch` vs `watchEffect`: use `watch` when you need the previous value or an explicit dependency;
+use `watchEffect` for "run now and re-run when anything I touched changes". Register teardown with
+`onWatcherCleanup()` (Vue 3.5) or the `onCleanup` arg to cancel stale async work — why: a watcher
+that fires faster than its async settles will otherwise apply an out-of-order result.
+
+Reactive props destructure is **stable in Vue 3.5** — the compiler rewrites `count` to
+`props.count`, so the binding stays reactive and you get clean default syntax:
+
+```vue
+<script setup lang="ts">
+const { count = 0, label } = defineProps<{ count?: number; label: string }>()
+// `count`/`label` here ARE reactive — compiler maps them back to props.x
+</script>
+```
+
+Two-way binding uses `defineModel()` (stable since 3.4), replacing the manual
+`props`+`emit('update:x')` pair. Template DOM refs use `useTemplateRef('name')` (3.5), not a
+manually-named `ref`.
+
+```vue
+<script setup lang="ts">
+import { useTemplateRef } from 'vue'
+const model = defineModel<string>()          // parent: <Comp v-model="x" />
+const input = useTemplateRef('inputEl')       // <input ref="inputEl">
+</script>
+```
+
+### Bad → Good: do not destructure a `reactive()`
+
+```vue
+<script setup lang="ts">
+import { reactive, toRefs } from 'vue'
+const state = reactive({ name: 'a', age: 1 })
+
+// Bad — `name` is a detached plain string; mutating state.name won't update it.
+const { name } = state
+
+// Good — keep the proxy, or toRefs to preserve reactivity per key.
+const { name: nameRef } = toRefs(state)   // nameRef.value stays linked
+// or just read state.name where you need it.
+</script>
+```
+
+Deep reactivity, effect scope, advanced `provide/inject`, and render-function/JSX notes live in
+`references/reactivity.md`.
+
+## Components & composables
+
+Type `defineProps`/`defineEmits` with generics, not the runtime object form — you get
+compile-time checking for free:
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{ id: string; tags?: string[] }>()
+const emit = defineEmits<{ select: [id: string]; close: [] }>()
+defineExpose({ focus })   // only what a parent template-ref may call
+</script>
+```
+
+Extract reusable logic into `composables/useX.ts` returning refs — **a composable, never a mixin**
+(why: mixins merge invisibly and collide on names; composables are explicit and tree-shakeable).
+No side effects at module scope (that runs once per server process and leaks across requests — see
+state below). Use typed `provide`/`inject` with an `InjectionKey` for dependency injection down a
+tree instead of prop-drilling.
+
+## The data-fetching boundary (core)
+
+This is where most Nuxt bugs live. Pick deliberately:
+
+| API | Use it for | SSR behavior |
+|---|---|---|
+| `useFetch(url, opts)` | the common case — fetch a URL in a page/component | fetches **once on server**, transfers payload to client, no refetch on hydration |
+| `useAsyncData(key, fn)` | wrap custom logic / multiple `$fetch` calls / a non-URL source | same once-then-transfer; you control the fn |
+| `$fetch(url)` | inside event handlers, server routes, or after mount | a plain request; **NOT** for top-level `setup` data |
+
+### Bad → Good: bare `$fetch` in setup double-fetches on SSR
+
+```vue
+<script setup lang="ts">
+// Bad — runs on the server render AND again during client hydration (2× the API hit,
+// possible mismatch). $fetch does not transfer a payload.
+const product = await $fetch(`/api/products/${id}`)
+
+// Good — one server fetch, payload serialized into the page, reused on hydration.
+const { data: product, status, error, refresh } = await useAsyncData(
+  `product:${id}`,                       // stable key → dedupe + shared ref across components
+  () => $fetch(`/api/products/${id}`),
+)
+// equivalently for a plain URL: useFetch(`/api/products/${id}`, { key: `product:${id}` })
+</script>
+```
+
+Key options: `key` (shared/deduped result — same key returns the same `data`/`error`/`status` ref,
+auto-cleaned on last unmount), `lazy: true` (don't block navigation), `server: false` (client-only
+fetch), `transform` (reshape before storing), `pick` (keep only listed fields — shrinks payload),
+`watch`/reactive keys (a `ref`/`computed`/getter key refetches when it changes). In **Nuxt 4 the
+returned `data` is a `shallowRef`** — replace the whole value, don't deep-mutate, to trigger
+updates. Nuxt 4.2 adds `AbortController` signal support for request cancellation. Re-run with the
+returned `refresh()`, or invalidate broadly with `refreshNuxtData(key)`.
+
+Full option matrix, custom `$api` factory, optimistic UI, and error/pending patterns are in
+`references/data-and-state.md`.
+
+## SSR-safe state
+
+On the server one Node process serves many requests. A module-level `ref` is created **once** and
+shared by every visitor — a textbook cross-request data leak.
+
+| Approach | Per-request? | When |
+|---|---|---|
+| module-level `ref`/`reactive` | **NO — leaks across requests** | never for request data; fine only for true constants |
+| `useState(key, init)` | yes — serialized after SSR, restored on hydration, shared by key | lightweight shared value |
+| Pinia store (`@pinia/nuxt`) | yes — hydrated from Nuxt payload | structured state, actions, multiple consumers |
+
+### Bad → Good: module `ref` → `useState`
+
+```ts
+// Bad — module scope: one instance for the whole server, shared between users.
+import { ref } from 'vue'
+export const user = ref(null)
+
+// Good — per-request, hydration-safe, shared by key.
+export const useUser = () => useState('user', () => null)
+```
+
+Pinia 3 (dropped Vue 2) with `@pinia/nuxt` auto-imports stores from `app/stores/`. Use the
+**setup-store** form; SSR state hydrates from the payload automatically:
+
+```ts
+// app/stores/cart.ts
+export const useCartStore = defineStore('cart', () => {
+  const items = ref<Item[]>([])
+  const count = computed(() => items.value.length)
+  function add(i: Item) { items.value.push(i) }
+  return { items, count, add }
+})
+```
+
+## Hydration mismatches
+
+A mismatch means the server-rendered HTML differs from the client's first render. Common causes:
+`Date.now()`/`new Date()`/`Math.random()` in render, reading `localStorage`/`window`/`document` in
+`setup`, locale/timezone differences, invalid HTML nesting (`<p>` wrapping a `<div>`), and
+non-deterministic iteration order.
+
+Fix kit: wrap genuinely client-only UI in `<ClientOnly>`; branch with `import.meta.client` /
+`import.meta.server`; do browser work in `onMounted` (never in `setup` body); and pin a
+server-generated value with `useState` so the client reuses the exact same value instead of
+recomputing it.
+
+```vue
+<template>
+  <ClientOnly><LiveClock /></ClientOnly>
+</template>
+<script setup lang="ts">
+const seed = useState('seed', () => Math.random())   // generated once on server, reused on client
+onMounted(() => { /* safe: window/localStorage here */ })
+</script>
+```
+
+## Nitro server routes
+
+Files in `server/api/*` and `server/routes/*` run on Nitro (Nuxt's server engine). Name by method
+with `.get.ts`/`.post.ts`. Validate input; throw `createError` for HTTP errors.
+
+```ts
+// server/api/products/[id].get.ts
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id')
+  const { fields } = getQuery(event)
+  if (!id) throw createError({ statusCode: 400, statusMessage: 'id required' })
+  const config = useRuntimeConfig()              // private keys server-only
+  const data = await fetchFromDb(id, config.dbUrl)
+  if (!data) throw createError({ statusCode: 404, statusMessage: 'Not found' })
+  return data
+})
+```
+
+`useRuntimeConfig()` exposes top-level keys **only on the server**; only `config.public.*` reaches
+the browser bundle. Rule: a secret in `runtimeConfig.public` (or any `NUXT_PUBLIC_*` env) ships to
+every client — keep API keys, DB URLs, and tokens at the top level, never under `public`. Type
+calls to your own API with `$fetch<ProductDto>('/api/...')`. Handlers, route-rule recipes,
+middleware, and `defineCachedEventHandler` caching live in `references/nitro-and-rendering.md`.
+
+## Rendering strategy
+
+Set per-route rendering in `nuxt.config.ts` with `routeRules`; the right mix is usually hybrid,
+not all-SSR.
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/':            { prerender: true },             // SSG at build
+    '/blog/**':     { swr: 3600 },                   // stale-while-revalidate cache 1h
+    '/products/**': { isr: true },                   // incremental static regeneration
+    '/admin/**':    { ssr: false },                  // client-only SPA island
+    '/old':         { redirect: '/new' },
+    '/api/**':      { headers: { 'cache-control': 's-maxage=60' } },
+  },
+})
+```
+
+`nuxt build` produces an SSR server; `nuxt generate` prerenders a fully static site. The **Nitro
+preset** chooses the deploy target (node-server, vercel, netlify, cloudflare-pages, …) — pick the
+preset here, then hand platform specifics to `../deployment/SKILL.md` / `../vercel/SKILL.md` /
+`../netlify/SKILL.md` / `../cloudflare/SKILL.md`.
+
+## Performance
+
+- `shallowRef`/`shallowReactive` for large payloads/lists — skip deep proxy cost; replace the whole
+  value to update. Why: deep reactivity on a 10k-row array is pure overhead.
+- `v-memo` to freeze a subtree on stable deps; `v-once` for render-once static content.
+- `defineAsyncComponent` and Nuxt's auto `Lazy<Component>` prefix to code-split below the fold.
+- `<NuxtImg>` / `@nuxt/image` for responsive, optimized images (a top LCP lever).
+- Shrink the SSR payload with `pick`/`transform` on `useFetch`/`useAsyncData`.
+- Vue 3.6 **Vapor Mode** (compile-time, no-VDOM, opt-in per component via `<script setup vapor>`) is
+  a 2026 preview targeting mid-2026 stable — treat as opt-in, not the default.
+- Targets: LCP < 2.5s, CLS < 0.1, INP < 200ms.
+
+## TypeScript discipline
+
+Generic `defineProps<{...}>()` / `defineEmits<{...}>()`; typed `useFetch<T>()` /
+`useAsyncData<T>()`; typed `$fetch<T>()` to your own API; `strict: true`. Gate with
+`nuxi typecheck` (Nuxt) or `vue-tsc --noEmit` (plain Vue) — see Verify.
+
+## Anti-patterns → STOP
+
+| Smell | Why it is wrong | Do instead |
+|---|---|---|
+| `await $fetch()` for page data in `setup` | runs on server AND client → double API hit, mismatch | `useAsyncData(key, () => $fetch(...))` / `useFetch` |
+| Module-level `ref`/`reactive` for shared state | one instance per server process → leaks across requests | `useState(key, init)` or a Pinia store |
+| `window`/`localStorage`/`document` in `setup` body | undefined on server → hydration mismatch | `onMounted`, `import.meta.client`, or `<ClientOnly>` |
+| Treating Nuxt like Next RSC ("use server", server components) | Vue has no RSC boundary; whole component renders + hydrates | model it as SSR + client hydration |
+| Destructuring a `reactive()` object | detaches the value from the proxy → loses reactivity | `toRefs()`, or read `state.x`, or prefer `ref` |
+| Secret in `runtimeConfig.public` / `NUXT_PUBLIC_*` | shipped into the client bundle | top-level `runtimeConfig`, server-only |
+| `useFetch`/`useState` in a plain-Vue (non-Nuxt) app | those auto-imports don't exist there | client `fetch` in `onMounted` + Pinia/`provide` |
+| `<ClientOnly>` wrapping everything to "fix" mismatches | kills SSR, hurts SEO/LCP, hides the real bug | find the non-deterministic source; pin with `useState` |
+| Same fetch in two components without a shared `key` | duplicate requests, divergent refs | one stable `key` → shared deduped result |
+| `ref(hugeArray)` / deep `reactive` on big lists | per-element proxy overhead | `shallowRef`/`shallowReactive`, replace whole value |
+
+## Quick reference
+
+| Task | API / file |
+|---|---|
+| Page data, once on SSR | `useFetch(url, { key })` / `useAsyncData(key, fn)` |
+| Request in a handler / after mount | `$fetch(url)` |
+| Shared SSR-safe value | `useState(key, init)` |
+| Structured store | Pinia setup store in `app/stores/` |
+| Two-way binding | `defineModel<T>()` |
+| Template DOM ref | `useTemplateRef('name')` |
+| Server endpoint | `server/api/x.get.ts` + `defineEventHandler` |
+| HTTP error | `throw createError({ statusCode })` |
+| Private vs public config | `useRuntimeConfig()` vs `config.public` |
+| Per-route rendering | `routeRules` in `nuxt.config.ts` |
+| Static build | `nuxt generate`; SSR build `nuxt build` |
+| Typecheck | `nuxi typecheck` / `vue-tsc --noEmit` |
+
+## Verify
+
+`scripts/verify.sh` runs from the project root. It detects Nuxt via `nuxt.config.{ts,js,mjs}`; for
+a Nuxt repo it runs `nuxi typecheck` (fallback `vue-tsc --noEmit`), the package `lint` script if
+present, `vitest run` if Vitest is present, then `nuxi build`. With no Nuxt config it runs
+`vue-tsc --noEmit`, lint, vitest, then `vite build`. Every missing tool is a yellow SKIP, never a
+failure; everything is read-only except the final build, which writes `.nuxt/`/`.output/` (or
+`dist/`). No installs, no network mutations, safe to re-run, exits 0 on a clean/empty target.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
+Karpathy wiki), record this app's decisions there and index them from the root `CLAUDE.md`, so the
+next agent inherits the conventions instead of re-deriving them.
+
+1. **Find the article** `02-DOCS/wiki/stack/vue-nuxt.md`, linked from a `## Knowledge map` section
+   in the root `CLAUDE.md`.
+2. **If missing or stale**, create/update it with the project's real choices — rendering mode per
+   route (`routeRules`), the `useFetch`/`useAsyncData` conventions, the state choice (`useState`
+   vs Pinia), the Nitro preset/deploy target, and the design-system hookup — then add/refresh the
+   `CLAUDE.md` link (creating the `## Knowledge map` section, and `CLAUDE.md` itself, if absent).
+3. **Read it first on every use** and stay consistent; when a convention changes, update the
+   article (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are
+*recorded, not gated* — never block the task on this.
+
+## References
+
+- `references/reactivity.md` — reactivity caveats, effect scope, watcher cleanup, composable
+  patterns, typed `provide/inject`, advanced `defineModel`, render-fn/JSX.
+- `references/data-and-state.md` — full `useFetch`/`useAsyncData` option matrix, custom `$api`,
+  Pinia setup stores + SSR hydration + Pinia Colada, `useState` patterns, optimistic UI.
+- `references/nitro-and-rendering.md` — Nitro handlers, route-rule recipes (ISR/SWR/SPA/prerender),
+  server middleware, runtime config, `defineCachedEventHandler`, preset selection.
+- `references/migration-nuxt4.md` — Nuxt 3 → 4 (`app/` move, `compatibilityVersion`, shared-key
+  data, shallowRef payload, renamed APIs) and Vue 3.4 → 3.5 deltas.
+
+## See Also
+
+- `../nextjs/SKILL.md` — the React/Next analogue; cross over only when the project is React.
+- `../design/SKILL.md` — design system and component visual language this skill consumes.
+- `../deployment/SKILL.md`, `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md`
+  — platform deploy once the Nitro preset is chosen.
+- `../secure-coding/SKILL.md` — generic security; complements the runtime-config secret rules here.
+- `../e2e-testing/SKILL.md` / `../testing-web/SKILL.md` — test strategy beyond the setup stated here.
+- `../marketing/SKILL.md` — SEO/GEO content strategy this skill renders but does not decide.
+- `../harness/SKILL.md` — workspace conventions (`02-DOCS/`).

package/skills/vue-nuxt/evals/README.md

@@ -0,0 +1,11 @@
+# vue-nuxt evals
+
+These cases are not an executable test suite — they are routing and capability rubrics for humans
+or a router harness. To run them, feed each `should_trigger` prompt to the skill router and confirm
+`vue-nuxt` is selected, then feed each `should_not_trigger` prompt and confirm it routes to the
+named sibling (e.g. `nextjs`, `astro`, `cloudflare`, `e2e-testing`, `fastapi`) rather than here.
+The single `capability` case is a manual check: have the agent answer the scenario with the skill
+loaded, then verify every line in `must_include` is satisfied by the worked answer (Nuxt-4
+detection first, `$fetch`→`useAsyncData`/`useFetch` with a shared key, module-`ref`→`useState`/Pinia
+with the per-request-leak explanation, payload-size notes, and no RSC mental models). Pair this with
+`scripts/verify.sh` run against a real Vue/Nuxt repo to confirm the emitted code typechecks/builds.

package/skills/vue-nuxt/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: vue-nuxt
+
+should_trigger:
+  - prompt: "Why does my Nuxt page fetch the API twice on page load?"
+    why: "Classic SSR double-fetch symptom from a bare $fetch in setup — the core data-fetching boundary this skill owns. Non-obvious: the user describes a symptom, not an API."
+  - prompt: "Hydration node mismatch error in my .vue page after deploy"
+    why: "Hydration mismatch is a Vue/Nuxt SSR trap (Date/random/localStorage in setup); .vue + hydration is squarely this skill."
+  - prompt: "Should I use useFetch or useAsyncData here, and how do I share the result between two components?"
+    why: "The exact useFetch-vs-useAsyncData decision plus shared-key dedupe — the load-bearing Nuxt section."
+  - prompt: "Building a Nuxt 4 app, where do composables and stores go now?"
+    why: "Nuxt 4 app/ srcDir structure (app/composables, app/stores) — the version/structure detection this skill leads with."
+  - prompt: "per què el meu estat de Pinia es filtra entre peticions al servidor?"
+    why: "Catalan; SSR cross-request state leak (module-level singleton / store init at module scope). Non-obvious server-side leak that this skill diagnoses."
+  - prompt: "Convert this Vue component to defineModel and reactive props destructure"
+    why: "Vue 3.5 / 3.4 Composition API modernization (defineModel, reactive props destructure) — the reactivity core."
+  - prompt: "How do I set per-route ISR and SSG in nuxt.config with routeRules?"
+    why: "routeRules hybrid rendering strategy — non-obvious that prerender/swr/isr live in routeRules, not per-page config."
+
+should_not_trigger:
+  - prompt: "Set up React Server Components and server actions in my app/ dir"
+    route_to: nextjs
+    why: "RSC and server actions are React/Next concepts; Vue has no server-component boundary. The shared 'app/' word is a false signal."
+  - prompt: "Build a content-heavy static blog mixing React and Vue islands"
+    route_to: astro
+    why: "Multi-framework islands on a content-first static site is Astro's domain, not a single-framework Nuxt app."
+  - prompt: "Deploy my Nuxt app to Cloudflare Pages with the right adapter"
+    route_to: cloudflare
+    why: "Platform deploy specifics (adapter, edge config, bindings) belong to cloudflare; this skill only selects the Nitro preset."
+  - prompt: "Write Playwright E2E tests for my Vue checkout flow"
+    route_to: e2e-testing
+    why: "E2E test strategy and Playwright authoring live in e2e-testing; this skill only states the test setup."
+  - prompt: "Build a Python FastAPI backend for my Vue frontend"
+    route_to: fastapi
+    why: "A non-Nitro backend in Python is fastapi's domain; this skill owns only the Nitro/JS server."
+
+capability:
+  - scenario: >
+      A Nuxt 4 product page double-fetches the product API on SSR (data appears twice in the
+      network panel) and a shared "current user" value leaks between concurrent requests on the
+      server. The current code does `const product = await $fetch('/api/products/' + id)` in setup
+      and exports `export const user = ref(null)` at module scope. Ask the agent to fix both and
+      explain why.
+    must_include:
+      - "Detects/confirms Nuxt 4 (app/ srcDir, nuxt.config) before prescribing Nuxt-only APIs"
+      - "Replaces the bare $fetch in setup with useAsyncData/useFetch (one server fetch + payload transfer to client) and explains $fetch does not transfer a payload"
+      - "Uses a stable key so the two components share one data/error/status ref (dedupe + auto-cleanup)"
+      - "Replaces the module-level ref with useState(key, init) or a Pinia store, explaining the per-request server leak from a module singleton"
+      - "Notes shallowRef payload (Nuxt 4) and/or pick/transform to keep the SSR payload small where relevant"
+      - "Does NOT introduce RSC / 'use server' / server-component mental models"

package/skills/vue-nuxt/references/data-and-state.md

@@ -0,0 +1,127 @@
+# Data fetching & SSR-safe state
+
+Companion to the SKILL "data-fetching boundary" and "SSR-safe state" sections.
+
+## `useFetch` / `useAsyncData` option matrix
+
+Both return `{ data, error, status, refresh, execute, clear }` and run **once on the server**,
+serializing the result into the page payload for hydration. `useFetch(url, opts)` is sugar over
+`useAsyncData(autoKey, () => $fetch(url, opts))`.
+
+| Option | Effect |
+|---|---|
+| `key` | shared/deduped result; same key → same `data`/`error`/`status` ref across components; auto-cleaned on last unmount |
+| `lazy: true` | resolve after navigation instead of blocking it; `status` goes `pending` → `success` |
+| `server: false` | skip the server fetch; fetch only on the client (pairs well with `lazy`) |
+| `immediate: false` | don't fetch until you call `execute()`/`refresh()` |
+| `transform: (d) => ...` | reshape the response before it is stored (also shrinks payload) |
+| `pick: ['a','b']` | keep only these top-level fields → smaller payload |
+| `watch: [refA]` / reactive `key` | refetch when a watched ref / a `ref`/`computed`/getter key changes |
+| `default: () => ...` | value for `data` before the first resolve |
+| `dedupe: 'cancel' \| 'defer'` | how concurrent calls with the same key behave |
+| `getCachedData: (key, nuxtApp, ctx) => ...` | serve cached data; `ctx.cause` tells you why (initial/refresh/watch) |
+
+**Nuxt 4 specifics:** `data` is a `shallowRef` by default (replace the whole value to update, don't
+deep-mutate); `getCachedData` receives a `{ cause }` context; Nuxt 4.2 supports passing an
+`AbortController` `signal` for cancellation.
+
+```vue
+<script setup lang="ts">
+const page = ref(1)
+const { data, status, error, refresh } = await useFetch('/api/products', {
+  key: 'products',
+  query: { page },                 // reactive query → refetch when page changes
+  transform: (r: ProductsDto) => r.items,
+  pick: ['items'],
+  lazy: true,
+})
+function reload() { refresh() }                 // re-run this one
+</script>
+```
+
+Invalidate across the app with `refreshNuxtData('products')` (or no arg to refresh all). `clear()`
+resets `data`/`error` to defaults.
+
+## Custom `$fetch` instance (`$api`)
+
+Centralize base URL, auth header, and error handling once. Register it as a Nuxt plugin and reuse
+everywhere; it is SSR-aware and forwards cookies on the server.
+
+```ts
+// plugins/api.ts
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig()
+  const api = $fetch.create({
+    baseURL: config.public.apiBase,
+    onRequest({ options }) {
+      const token = useCookie('token').value
+      if (token) options.headers.set('Authorization', `Bearer ${token}`)
+    },
+    onResponseError({ response }) {
+      if (response.status === 401) navigateTo('/login')
+    },
+  })
+  return { provide: { api } }
+})
+// use: const { $api } = useNuxtApp()
+//      const { data } = await useAsyncData('me', () => $api('/me'))
+```
+
+## Pinia setup stores + SSR hydration
+
+`@pinia/nuxt` auto-imports stores from `app/stores/`. The setup-store style is the idiomatic
+Composition form; Nuxt serializes store state into the payload and rehydrates it on the client — no
+manual `state` transfer.
+
+```ts
+// app/stores/cart.ts
+export const useCartStore = defineStore('cart', () => {
+  const items = ref<Item[]>([])
+  const total = computed(() => items.value.reduce((s, i) => s + i.price, 0))
+  async function load() {
+    items.value = await $fetch('/api/cart')   // call inside an action, not module scope
+  }
+  function add(i: Item) { items.value.push(i) }
+  return { items, total, load, add }
+})
+```
+
+For server-resolved store state, populate it from a component's `useAsyncData`/`callOnce` so it is
+filled during SSR and hydrated, not refetched on the client.
+
+**Pinia Colada** is the data-fetching layer for Pinia (query cache, invalidation, mutations) — an
+alternative to hand-rolling `useAsyncData` caching when you want React-Query-style ergonomics in a
+Vue/Nuxt app. Add it only if the app's data needs justify a cache layer.
+
+## `useState` patterns
+
+```ts
+// composables/useCounter.ts — shared, SSR-safe, hydrated
+export const useCounter = () => useState('counter', () => 0)
+
+// one-time server work, deduped across components and not re-run on client:
+const { data } = await useAsyncData('settings', () => $fetch('/api/settings'))
+// or for side-effecting init that must run once: await callOnce(() => store.load())
+```
+
+Keep `useState` for small shared values; promote to a Pinia store once you need actions, getters,
+and multiple consumers with logic.
+
+## Optimistic UI
+
+Update the local ref immediately, fire the mutation, roll back on error.
+
+```ts
+async function toggleLike(post: Post) {
+  const prev = post.liked
+  post.liked = !prev                              // optimistic
+  try { await $fetch(`/api/posts/${post.id}/like`, { method: 'POST' }) }
+  catch (e) { post.liked = prev; throw e }        // rollback
+}
+```
+
+## Error & pending states
+
+Drive UI from `status` (`'idle' | 'pending' | 'success' | 'error'`), not from `data == null`.
+Render `error` with a retry that calls `refresh()`. For route-level failures, `throw createError({
+statusCode, fatal: true })` to render the error page.

package/skills/vue-nuxt/references/migration-nuxt4.md

@@ -0,0 +1,79 @@
+# Migration: Nuxt 3 → Nuxt 4, and Vue 3.4 → 3.5
+
+Companion to the SKILL "detect version" table. Nuxt 4.0 shipped July 2025; the 4.x line is current
+stable. Nuxt 5 + Nitro 3 are in active development — treat any "Nuxt 5" claim as pre-release.
+
+## The `app/` srcDir move (headline change)
+
+Nuxt 4 moves application code under `app/` (`srcDir: 'app/'`). New default layout:
+
+```
+app/
+  components/   composables/   pages/   layouts/   stores/   utils/   middleware/
+  app.vue   error.vue   app.config.ts
+server/         # Nitro: api/, routes/, middleware/, plugins/, utils/
+shared/         # code shared between app and server (auto-imported in both)
+public/   modules/   layers/   nuxt.config.ts
+```
+
+Why: cleaner separation of client vs server code, faster file watching, and the `shared/` folder
+for genuinely isomorphic utilities. A Nuxt 3 repo with root `components/`/`pages/` still works, but
+new code should follow the `app/` layout.
+
+## Opting in / compatibility
+
+```ts
+// nuxt.config.ts — stay on legacy behavior while migrating
+export default defineNuxtConfig({
+  future: { compatibilityVersion: 4 },   // opt into v4 behavior on the v3→v4 bridge
+  // or pin srcDir explicitly while you move files:
+  // srcDir: 'app/',
+})
+```
+
+Run the upgrade with `npx nuxi upgrade` and use `npx codemod@latest nuxt/4/migration-recipe` (or
+the official migration guide) to move files and rewrite imports. Migrate folder-by-folder; the
+bridge lets old and new layouts coexist during the move.
+
+## Data-fetching deltas in Nuxt 4
+
+- **Shared keys**: `useFetch`/`useAsyncData` with the same `key` now share one `data`/`error`/
+  `status` ref across all callers, auto-cleaned when the last consumer unmounts. Audit code that
+  relied on per-call isolation.
+- **`data` is a `shallowRef`** by default — replace the whole value to trigger an update; deep
+  mutation no longer re-renders. If you genuinely need deep reactivity, opt out with
+  `{ deep: true }`.
+- **`getCachedData`** now receives a `{ cause }` context (`'initial' | 'refresh:manual' |
+  'refresh:hook' | 'watch'`) so you can vary caching by trigger.
+- Reactive keys (`ref`/`computed`/getter) refetch on change — previously you wired `watch` manually.
+- Nuxt 4.2 adds `AbortController` signal support for request cancellation.
+
+## Other notable changes
+
+- Singleton data layer and consistent `useAsyncData`/`useFetch` keys reduce duplicate fetches.
+- Deprecated/renamed APIs flagged by `nuxi upgrade`; check the warnings and the official migration
+  guide rather than guessing.
+- `@pinia/nuxt` auto-imports stores from `app/stores/` (was `stores/`).
+
+## Vue 3.4 → 3.5 deltas (what Nuxt 4 builds on)
+
+Vue 3.5 is stable and the version Nuxt 4 ships against. Adopt:
+
+- **Reactive Props Destructure stabilized** — `const { count = 0 } = defineProps<{count?: number}>()`
+  stays reactive; the compiler rewrites references to `props.count`. Clean default syntax, no
+  `withDefaults`.
+- **`useTemplateRef('name')`** — typed template DOM refs without a manually-named `ref`.
+- **`useId()`** — SSR-stable unique ids for label/input pairs (no hydration mismatch).
+- **`<Teleport defer>`** — teleport to a target that mounts later in the same render.
+- **`onWatcherCleanup()`** — register watcher teardown without the callback's cleanup arg.
+- **Reactivity refactor** — ~56% lower memory and faster large-array iteration; `shallowRef`/
+  `shallowReactive` remain the lever for very large structures.
+
+From 3.4: **`defineModel()`** is stable — use it instead of the `props` + `emit('update:x')` pair.
+
+## Looking ahead (do not adopt as default)
+
+Vue 3.6 (beta in 2026) previews **Vapor Mode** — a compile-time, virtual-DOM-free render strategy
+opted into per component via `<script setup vapor>`, targeting mid-2026 stable. It is opt-in and
+preview-grade; keep production components on the standard renderer until Vapor is stable and the
+ecosystem (libraries, dev tools) supports it.