@damiangilgonzalez/harness 1.3.7

package/skills/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/vocabulario-animacion/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: vocabulario-animacion
+description: "Use when someone describes a web motion effect without knowing its name (\\"that bouncy thing when a popover opens\\", \\"the iOS rubber-band scroll\\") and asks \\"what's it called when...\\". Returns the exact term so it can be requested from an AI or a designer. This is for NAMING an effect, not designing or building one."
+tags: ["animation", "vocabulary", "reference"]
+profiles: [ui, full]
+---
+
+# Vocabulario de animacion
+
+Convierte una descripcion vaga de un movimiento o efecto en el termino preciso, para que el usuario sepa que pedir.
+
+Los terminos se mantienen en INGLES a proposito: es el vocabulario con el que se le habla a una IA, a una libreria de animacion o a un disenador. La explicacion va en espanol.
+
+## Arranque rapido
+
+El usuario describe un efecto vagamente. Tu devuelves el termino o terminos que encajan, con este formato:
+
+```
+**Stagger** — Anima varios elementos uno tras otro con un pequeno retardo entre cada uno, creando una cascada.
+```
+
+Si encajan varios terminos, lista primero el mejor y luego 1-2 alternativas con una linea sobre en que se diferencian.
+
+## Instrucciones
+
+1. **Lee la intencion, no las palabras clave.** El usuario describe lo que *ve* o *siente* ("elastico", "se desliza fuera", "se dibuja solo"), no el nombre tecnico. Mapea la sensacion al glosario de abajo.
+2. **Cita el glosario tal cual.** Sus descripciones son la referencia: usalas como estan, no las parafrasees.
+3. **Desambigua terminos cercanos.** Cuando compiten dos (*Clip-path* vs *Mask*, *Pop in* vs *Bounce*, *Shared element transition* vs *Layout animation*), contrastalos para que el usuario elija.
+4. **Cuando nada encaja exactamente,** nombra el termino mas cercano y di claramente que es una aproximacion, o describe el efecto con el vocabulario del glosario (p. ej. "eso es un *stagger* de entradas *scale-in*").
+5. **No salgas de este glosario.** Si un termino de verdad no esta aqui, dilo en vez de inventarlo; puedes explicar el concepto con estas palabras.
+6. **Se breve.** Una pregunta de nombres quiere un nombre, no un ensayo. Empieza por el termino; amplia solo si te lo piden.
+
+**Ejemplo 1 — basado en sensacion**
+Usuario: "Como se llama cuando un popover parece crecer desde el boton que has pulsado y no desde su centro?"
+Salida:
+```
+**Origin-aware animation** — Un elemento se anima saliendo de su disparador, como un popover que crece desde el boton que lo abrio en vez de desde su propio centro, que es lo que hace CSS por defecto.
+```
+
+**Ejemplo 2 — desambiguacion**
+Usuario: "Eso de que una imagen se convierte en otra imagen."
+Salida:
+```
+**Morph** — Una forma se convierte suavemente en otra, p. ej. la Dynamic Island.
+
+Alternativas cercanas:
+- **Crossfade** — si simplemente se funden una sobre otra en el mismo sitio.
+- **Shared element transition** — si un elemento viaja y se transforma de una posicion a otra.
+```
+
+**Ejemplo 3 — sensacion fisica**
+Usuario: "Ese scroll de iOS que se resiste y vuelve de golpe cuando tiras de mas."
+Salida:
+```
+**Rubber-banding** — Resistencia y vuelta de golpe al arrastrar mas alla de un limite (la sensacion de overscroll de iOS).
+```
+
+## Glosario
+
+### Entradas y salidas — como aparecen y desaparecen los elementos
+- **Fade in / Fade out** — El elemento aparece o desaparece cambiando la opacidad.
+- **Slide in** — El elemento entra deslizandose desde fuera de pantalla (izquierda, derecha, arriba o abajo).
+- **Scale in** — El elemento crece de pequeno a tamano completo al aparecer, a menudo junto con un fundido.
+- **Pop in** — El elemento aparece con un ligero sobrepaso, como si rebotara hasta su sitio.
+- **Reveal** — El contenido se descubre gradualmente, normalmente animando un clip-path o una mascara.
+- **Enter / Exit** — La animacion que reproduce un elemento al anadirse o quitarse de la pantalla.
+
+### Secuenciacion y tiempos — coordinar varios elementos o momentos
+- **Keyframes** — Puntos definidos de una animacion (0%, 50%, 100%) cuyos huecos rellena el navegador.
+- **Interpolation / Tween** — Generar todos los fotogramas intermedios entre un valor inicial y uno final, para que el movimiento sea continuo.
+- **Stagger** — Animar varios elementos uno tras otro con un pequeno retardo entre cada uno, creando una cascada.
+- **Orchestration** — Cronometrar deliberadamente varias animaciones para que se sientan como un unico movimiento coordinado.
+- **Delay** — Tiempo antes de que arranque una animacion.
+- **Duration** — Cuanto dura una animacion.
+- **Fill mode** — Si un elemento conserva los estilos de su primer o ultimo fotograma antes de empezar o despues de acabar (p. ej. forwards).
+- **Stepped animation** — Animacion dividida en pasos discretos, como una cuenta atras.
+
+### Movimiento y transformaciones — cambiar posicion, tamano o angulo
+- **Translate** — Mover un elemento por el eje X o Y.
+- **Scale** — Hacer un elemento mas grande o mas pequeno.
+- **Rotate** — Girar un elemento alrededor de un punto.
+- **Skew** — Inclinar un elemento en X o Y, sacandolo de su forma rectangular.
+- **3D tilt / Flip** — Rotar en el espacio 3D (rotateX / rotateY) para anadir profundidad.
+- **Perspective** — Cuanto se nota el efecto 3D: un valor mas bajo exagera la profundidad, como si el espectador estuviera mas cerca.
+- **Transform origin** — El punto de anclaje desde el que crece o gira una escala o rotacion.
+- **Origin-aware animation** — Un elemento se anima saliendo de su disparador, como un popover que crece desde el boton que lo abrio en vez de desde su propio centro, que es el defecto de CSS.
+
+### Transiciones entre estados — conectar un estado, vista o elemento con otro
+- **Crossfade** — Un elemento se funde a la salida mientras otro se funde a la entrada, en el mismo sitio.
+- **Continuity transition** — Un cambio que mantiene orientado al usuario conectando visualmente el antes y el despues. Por ejemplo, agrandar y encoger el mismo rectangulo.
+- **Morph** — Una forma se convierte suavemente en otra, p. ej. la Dynamic Island.
+- **Shared element transition** — Un elemento viaja y se transforma de una posicion a otra, como una miniatura que se expande hasta ser una tarjeta.
+- **Layout animation** — Cuando cambia el tamano o la posicion de un elemento, se anima hasta el nuevo sitio en vez de saltar.
+- **Accordion / Collapse** — Una seccion expande y colapsa su altura suavemente para mostrar u ocultar contenido.
+- **Direction-aware transition** — El contenido se desliza hacia un lado al avanzar y hacia el contrario al volver, para que la navegacion tenga sentido de direccion.
+
+### Scroll — movimiento ligado al desplazamiento o a la navegacion
+- **Scroll reveal** — Los elementos se funden o deslizan a su sitio al entrar en el viewport.
+- **Scroll-driven animation** — Animacion cuyo progreso esta atado directamente a la posicion del scroll.
+- **Parallax** — Fondo y primer plano se mueven a velocidades distintas al hacer scroll, creando profundidad.
+- **Page transition** — Animacion que se reproduce al navegar de una pagina o ruta a otra.
+- **View transition** — El navegador transforma una vista en otra, conectando los elementos compartidos.
+
+### Feedback e interaccion — responder a las acciones del usuario
+- **Hover effect** — Cambio visual cuando el cursor pasa sobre un elemento.
+- **Press / Tap feedback** — Una reduccion sutil de escala al pulsar, para que se sienta fisico.
+- **Hold to confirm** — Un efecto de progreso que se rellena mientras el usuario mantiene pulsado.
+- **Drag** — Mover un elemento agarrandolo, a menudo con inercia al soltarlo.
+- **Drag to reorder** — Arrastrar elementos de una lista para reordenarlos mientras los demas se apartan para hacer sitio.
+- **Swipe to dismiss** — Arrastrar un elemento fuera de pantalla para cerrarlo, como un drawer o un toast.
+- **Rubber-banding** — Resistencia y vuelta de golpe al arrastrar mas alla de un limite (el overscroll de iOS).
+- **Shake / Wiggle** — Una sacudida rapida de lado a lado que senala un error o una entrada rechazada.
+- **Ripple** — Un circulo que se expande desde el punto de pulsacion, confirmando la pulsacion.
+
+### Easing — como cambia la velocidad a lo largo de una animacion
+- **Easing** — El ritmo al que una animacion acelera o frena.
+- **Ease-out** — Empieza rapido, acaba lento. El defecto para casi toda la UI y para cualquier cosa que responda al usuario.
+- **Ease-in** — Empieza lento, acaba rapido. Normalmente se evita; se siente pesado.
+- **Ease-in-out** — Lento, rapido, lento. Bueno para elementos ya en pantalla que se mueven de A a B.
+- **Linear** — Velocidad constante. Evitalo en UI; reservalo para spinners o marquesinas.
+- **Cubic-bezier** — Una curva de easing propia que defines para control preciso.
+- **Asymmetric easing** — Curva que acelera y frena a ritmos distintos. Se siente mas viva que una simetrica.
+
+### Muelles (springs) — movimiento basado en fisica, alternativa al easing de duracion fija
+- **Spring** — Movimiento gobernado por fisica (tension, masa, amortiguacion) en vez de por una duracion fijada.
+- **Stiffness / Tension** — Con cuanta fuerza tira el muelle hacia su destino. Mas alto se siente mas seco y rapido.
+- **Damping** — Con cuanta rapidez se asienta un muelle. Menos amortiguacion significa mas rebote y oscilacion.
+- **Mass** — Cuanto pesa el elemento animado. Mas masa lo hace mas lento y pesado.
+- **Bounce** — Un muelle que sobrepasa y se asienta, anadiendo un caracter jugueton.
+- **Perceptual duration** — Cuanto tarda un muelle en *parecer* terminado, aunque por debajo siga micro-asentandose.
+- **Momentum** — Movimiento que arrastra velocidad, sobre todo tras un arrastre o una interrupcion.
+- **Velocity** — A que velocidad y en que direccion se mueve un elemento. Un muelle la lleva a la siguiente animacion al interrumpirse, asi que un elemento lanzado conserva su velocidad.
+- **Interruptible animation** — Animacion que se puede redirigir suavemente en pleno vuelo en vez de tener que terminar antes.
+
+### Bucles y movimiento ambiental — animaciones que corren solas
+- **Marquee** — Texto o contenido que se desplaza continuamente en bucle.
+- **Loop** — Animacion que se repite, un numero de veces o infinitamente.
+- **Alternate (yoyo)** — Un bucle que va hacia delante y luego se invierte en cada iteracion, en vez de saltar al principio.
+- **Orbit** — Un elemento girando alrededor de otro en una trayectoria continua.
+- **Pulse** — Un cambio suave y repetido de escala u opacidad para llamar la atencion.
+- **Float** — Una deriva suave y continua arriba y abajo que hace que un elemento estatico parezca vivo e ingravido.
+- **Idle animation** — Movimiento sutil que se reproduce mientras un elemento esta ahi parado, esperando interaccion.
+
+### Pulido y efectos — los detalles que separan lo bueno de lo excelente
+- **Blur** — Filtro de desenfoque para suavizar un elemento o disimular imperfecciones minimas.
+- **Clip-path** — Recortar un elemento a una forma; se usa para reveals, mascaras y sliders de antes/despues.
+- **Mask** — Ocultar o revelar partes de un elemento con una forma o un degradado; como clip-path, pero con bordes suaves y difuminables.
+- **Before / after slider** — Un divisor arrastrable que barre entre dos imagenes superpuestas para compararlas.
+- **Line drawing** — Un path SVG que se dibuja solo, como si un boligrafo invisible lo trazara.
+- **Text morph** — Texto que se anima caracter a caracter al cambiar, llamando la atencion sobre el valor nuevo.
+- **Skeleton / Shimmer** — Un marcador de posicion con un brillo en movimiento mientras carga el contenido.
+- **Number ticker** — Digitos que ruedan o cuentan hasta un valor.
+- **Tabular numbers** — Digitos de ancho fijo para que los numeros no bailen al cambiar. Imprescindible en tickers, temporizadores y contadores.
+- **Typewriter** — Texto que aparece caracter a caracter, como si se estuviera escribiendo.
+
+### Rendimiento — lo que mantiene el movimiento fluido en vez de a tirones
+- **Frame rate (FPS)** — Fotogramas dibujados por segundo. 60fps es la base de un movimiento fluido; 120fps en pantallas modernas.
+- **Jank** — Tiron visible cuando el navegador pierde fotogramas porque no llega.
+- **Dropped frame** — Fotograma que el navegador no llego a dibujar a tiempo, causando un microtiron.
+- **Compositing** — Dejar que la GPU mueva o funda un elemento en su propia capa sin rehacer layout ni pintado.
+- **will-change** — Pista CSS de que un elemento va a animarse, para que el navegador lo promocione a su propia capa por adelantado.
+- **Layout thrashing** — Animar propiedades como width, height, top o left, que obligan al navegador a recalcular el layout en cada fotograma y provocan jank.
+
+### Principios que hay que saber — cuando y como animar
+- **Purposeful animation** — El movimiento debe cumplir una funcion (orientar, dar feedback, mostrar relaciones), no solo decorar.
+- **Anticipation** — Un pequeno impulso en direccion contraria antes de un movimiento, insinuando lo que va a pasar.
+- **Follow-through** — Partes de un elemento siguen moviendose y se asientan un poco despues de que pare el movimiento principal, anadiendo peso.
+- **Squash & stretch** — Deformar un elemento al moverse para transmitir peso, velocidad y flexibilidad.
+- **Perceived performance** — La animacion adecuada hace que una interfaz se sienta mas rapida, aunque no lo sea.
+- **Frequency of use** — Cuanto mas a menudo ve el usuario una animacion, mas corta y sutil debe ser.
+- **Spatial consistency** — Animar de forma que un elemento conserve su identidad y su posicion entre estados, para que el usuario nunca pierda de vista donde han ido las cosas.
+- **Hardware acceleration** — Animar transform y opacity deja que la GPU mantenga el movimiento fluido.
+- **Reduced motion** — Respetar el ajuste prefers-reduced-motion del usuario suavizando o eliminando el movimiento.

package/skills/vocabulario-animacion/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: vocabulario-animacion
+
+should_trigger:
+  - prompt: "Como se llama ese efecto que rebota al abrirse un popover."
+    why: "Disparador directo de vocabulario-animacion."
+  - prompt: "Necesito el nombre exacto del scroll elastico de iOS."
+    why: "Disparador directo de vocabulario-animacion."
+  - prompt: "Que termino uso para pedirle a un disenador ese efecto de movimiento."
+    why: "Disparador directo de vocabulario-animacion."
+  - prompt: "What's it called when a card springs back after you release it."
+    why: "Disparador directo de vocabulario-animacion."
+  - prompt: "Dame el nombre tecnico de esta animacion de entrada."
+    why: "Disparador directo de vocabulario-animacion."
+
+should_not_trigger:
+  - prompt: "Construye esta animacion desde cero, no necesito el nombre."
+    route_to: "animar"
+    why: "Construir la animacion desde cero es el trabajo de animar, no de vocabulario-animacion."
+  - prompt: "Critica la animacion que ya existe en este componente."
+    route_to: "none"
+    why: "Fuera del alcance de vocabulario-animacion."
+  - prompt: "Revisa la accesibilidad del movimiento reducido."
+    route_to: "mejor-accesibilidad"
+    why: "Revisar la accesibilidad del movimiento reducido es el trabajo de mejor-accesibilidad, no de vocabulario-animacion."
+  - prompt: "Escribe el copy de este boton."
+    route_to: "mejor-redaccion"
+    why: "Escribir el copy de un boton es el trabajo de mejor-redaccion, no de vocabulario-animacion."
+
+capability:
+  - scenario: "El usuario quiere el nombre exacto de un efecto de movimiento que no sabe nombrar."
+    must_include:
+      - "nombre"

package/skills/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/RSC (that is nextjs), NOT a static islands 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,
+so never import RSC 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 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 |
+
+## 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 (docs + CLAUDE.md)
+
+In a project with a `docs/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`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 `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/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.