@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/vllm/references/memory-and-throughput.md

@@ -0,0 +1,78 @@
+# vLLM — memory, OOM, and throughput tuning
+
+Grounded in [engine args](https://docs.vllm.ai/en/latest/configuration/engine_args.html),
+[optimization/conserving memory](https://docs.vllm.ai/en/latest/configuration/optimization.html), and
+the [V1 guide](https://docs.vllm.ai/en/latest/usage/v1_guide.html) (accessed 2026-07). Defaults drift
+between weekly releases — verify.
+
+## Where the VRAM goes
+
+For each GPU:
+
+```
+usable          = gpu_memory_utilization × total_VRAM       # default utilization ≈ 0.92
+KV_cache_pool   = usable − weights − activation/CUDA-graph overhead
+max_concurrency ≈ KV_cache_pool ÷ (bytes_per_token × max_model_len)
+```
+
+- **Weights** are fixed once the model (and quant) is chosen; TP splits them across GPUs.
+- **KV cache** is the elastic part — PagedAttention blocks allocated per active token. It grows with
+  `max_model_len × concurrent sequences`. This is what runs you out of memory, not the weights.
+- **Overhead** — activations, CUDA graphs, the profiling reservation vLLM makes at startup. `--enforce-eager`
+  drops CUDA-graph memory (and some speed); it is a lever when you are just over the line.
+
+`bytes_per_token` depends on layers × KV heads × head_dim × 2 (K and V) × dtype bytes. You do not
+usually compute it — you observe `/metrics` (`vllm:gpu_cache_usage_perc`) and adjust.
+
+## OOM playbook (in order)
+
+1. **Cap `--max-model-len`** to the real max prompt+output. Going from 128K to, say, 8K multiplies how
+   many sequences fit. This is the highest-leverage fix.
+2. **Lower `--gpu-memory-utilization`** if OOM happens *at load* or on bursty spikes (e.g. 0.92 → 0.85).
+   Counterintuitively, a lower number can stop crashes by leaving headroom for activation spikes.
+3. **Lower `--max-num-seqs`** to bound concurrent sequences (and thus peak KV usage).
+4. **Quantize the weights** (AWQ/GPTQ/FP8/compressed-tensors) to free VRAM for the KV pool — a memory
+   win, not necessarily a speed win.
+5. **Add GPUs via `--tensor-parallel-size`** so weights + KV split across devices.
+6. **`--enforce-eager`** or **`--kv-cache-dtype fp8`** to trim graph/cache memory when marginally over.
+
+If none fit, the box is too small — that is a `runpod`/`modal` sizing decision, not a vLLM flag.
+
+## Quantization tradeoffs by regime
+
+| Method | Weights | Typical use | Watch out |
+| --- | --- | --- | --- |
+| FP8 (W8A8) | 8-bit | near-lossless, good on Ada/Hopper+ | needs recent NVIDIA/AMD arch; older GPUs unsupported |
+| INT8 / W8A8 | 8-bit | broad support, small quality hit | activation quant sensitive to calibration |
+| AWQ / GPTQ (4-bit) | ~4-bit | max VRAM savings | quality cost real; dequant can add latency |
+| compressed-tensors | varies | LLM Compressor output, mixed schemes | method-specific kernel/arch support |
+| bitsandbytes | 4/8-bit | convenient, load-time quant | generally slower than dedicated kernels |
+
+Regime that decides whether a quant *helps speed*:
+
+- **Low batch / low concurrency** — memory-bandwidth-bound; a quant that shrinks weights can raise
+  tokens/s. But dequant overhead can eat the win — measure.
+- **High batch / high concurrency** — often compute-bound; a *weight-only* quant does little for
+  throughput there (its win is the freed VRAM → bigger KV pool → more concurrency).
+
+So: quantize primarily to **fit** and to **grow the KV pool**, and benchmark before claiming it is
+faster. Choosing *which* quantized checkpoint to pull is `open-weights`.
+
+## Throughput knobs (once it fits)
+
+- **Prefix caching** (on by default in V1) reuses the KV of shared prompt prefixes — big win for repeated
+  system prompts / few-shot / agent loops. Watch `vllm:prefix_cache_hit_rate` in `/metrics`.
+- **Chunked prefill** (V1 default) interleaves prefill and decode so long prompts do not stall decoding.
+  `--max-num-batched-tokens` sets the per-step budget.
+- **`--max-num-seqs`** raises the concurrency ceiling if you have KV headroom; lowering it cuts latency.
+- **Speculative decoding** (`--speculative-config …`) can raise tokens/s for a request when a draft model
+  or n-gram method fits — verify current syntax in the docs; the flag shape changes.
+
+## Measuring, not guessing
+
+- Scrape `/metrics` for `gpu_cache_usage_perc`, `num_requests_running`/`_waiting`, `prompt`/`generation`
+  throughput, and prefix-cache hit rate.
+- Load-test with the bundled benchmark (`vllm bench serve` / `benchmarks/benchmark_serving.py` in the
+  repo — name has moved across versions; check `vllm bench --help`) at your real concurrency and prompt
+  mix. Tune `--max-model-len`, `--gpu-memory-utilization`, `--max-num-seqs` against those numbers, not a
+  single-request feel.

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

@@ -0,0 +1,323 @@
+---
+name: vue-nuxt
+description: "Use when building or reviewing a Vue 3 + Nuxt 4 app — `<script setup>` reactivity, SSR/SSG/hybrid `routeRules`, the `app/`+`server/` layout, SSR-safe fetching (`useFetch`/`useAsyncData`) and state (`useState`/Pinia), Nitro routes, hydration mismatches, Nuxt 3→4 migration. NOT React/React Server Components (that is nextjs), NOT a static islands site (that is astro)."
+tags: [vue, nuxt, frontend, web, ssr]
+recommends: [design, deployment, secure-coding]
+origin: ai-hub
+---
+
+# 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,
+so never import React Server Components mental models here.
+
+Not this skill: React / Next App Router / server actions → [`nextjs`](../nextjs/SKILL.md) or
+[`react`](../react/SKILL.md). Content-first site mixing frameworks/islands →
+[`astro`](../astro/SKILL.md); fine-grained signals → [`solid-js`](../solid-js/SKILL.md);
+compiler-first no-VDOM peer → [`svelte`](../svelte/SKILL.md); [`angular`](../angular/SKILL.md).
+Backend not in Nitro/JS → [`fastapi`](../fastapi/SKILL.md), [`go`](../go/SKILL.md),
+[`laravel`](../laravel/SKILL.md). Test *strategy* beyond the Vitest + `@vue/test-utils` +
+`@nuxt/test-utils` setup named here → [`e2e-testing`](../e2e-testing/SKILL.md) /
+[`testing-web`](../testing-web/SKILL.md). Generic security review →
+[`secure-coding`](../secure-coding/SKILL.md); SEO/content strategy →
+[`marketing`](../marketing/SKILL.md); component visual language → [`design`](../design/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`](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`](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). Type the result
+with `useFetch<T>()` / `useAsyncData<T>()`. 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`](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`](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`](../deployment/SKILL.md),
+[`vercel`](../vercel/SKILL.md), [`netlify`](../netlify/SKILL.md), or
+[`cloudflare`](../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.
+
+## 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 React Server Components ("use server", server components) | Vue has no React Server Components 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 |
+
+## Verify
+
+`scripts/verify.sh` runs from the project root. With a `nuxt.config.{ts,js,mjs}` 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, `vue-tsc --noEmit`, lint, vitest, then
+`vite build`. Keep `strict: true` in tsconfig so the typecheck is worth running. 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)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`02-DOCS/wiki/stack/vue-nuxt.md` first and stay consistent with it. If it is missing or stale,
+create/update it with this app's real choices — rendering mode per route (`routeRules`), the
+`useFetch`/`useAsyncData` conventions, `useState` vs Pinia, the Nitro preset/deploy target, the
+design-system hookup — bump its `Updated` date, and link it from a `## Knowledge map` section in
+the root `CLAUDE.md` (creating that section, and `CLAUDE.md` itself, if absent). No `02-DOCS/`
+layer? Skip silently. Technical conventions are *recorded, not gated* — never block the task.
+
+Nuxt 3 → 4 deltas (`app/` move, `compatibilityVersion`, shared-key data, shallowRef payload,
+renamed APIs) and Vue 3.4 → 3.5 changes are in
+[`references/migration-nuxt4.md`](references/migration-nuxt4.md).

package/skills/shared/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 React Server Components mental models). Pair this with
+`scripts/verify.sh` run against a real Vue/Nuxt repo to confirm the emitted code typechecks/builds.

package/skills/shared/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: "React Server Components 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 React Server Components / 'use server' / server-component mental models"

package/skills/shared/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.