@gallopsystems/agent-skills 1.5.0 → 1.6.1

package/README.md

@@ -19,6 +19,7 @@ Then install the skills you want:
 /plugin install git-github@gallop-systems-agent-skills
 /plugin install copier-template@gallop-systems-agent-skills
 /plugin install volt-primevue@gallop-systems-agent-skills
+/plugin install vue-nuxt@gallop-systems-agent-skills
 ```
 
 ## Updating
@@ -87,14 +88,13 @@ Covers:
 
 ### nuxt-nitro-api
 
-Nuxt 3 / Nitro API patterns for building type-safe full-stack applications. Automatically activates when working in Nuxt 3 projects.
+Nuxt 4 / Nitro API patterns for building type-safe full-stack applications. Automatically activates when working in Nuxt 4 projects.
 
 Covers:
 - Zod validation with h3 (Standard Schema support)
 - useFetch vs $fetch vs useAsyncData
 - Type inference (don't add manual types!)
 - nuxt-auth-utils (OAuth, WebAuthn, middleware)
-- Page structure (keep pages thin)
 - Composables vs utils
 - SSR + localStorage patterns
 - Deep linking (URL params sync)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/nuxt-nitro-api/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-nitro-api",
-  "description": "Nuxt 3 / Nitro API patterns: validation, auth, SSR, tasks, SSE",
+  "description": "Nuxt 4 / Nitro API patterns: validation, auth, SSR, tasks, SSE",
   "version": "1.0.0",
   "author": {
     "name": "yeedle"

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

@@ -1,16 +1,22 @@
 ---
 name: nuxt-nitro-api
-description: Build type-safe Nuxt 3 applications with Nitro API patterns. Covers validation, fetch patterns, auth, SSR, composables, background tasks, and real-time features.
+description: Build type-safe Nuxt 4 applications with Nitro API patterns. Covers validation, fetch patterns, auth, SSR, composables, background tasks, and real-time features.
 ---
 
-# Nuxt 3 / Nitro API Patterns
+# Nuxt 4 / Nitro API Patterns
 
-This skill provides patterns for building type-safe Nuxt 3 applications with Nitro backends.
+This skill provides patterns for building type-safe Nuxt applications with Nitro backends.
+
+> **Version note:** Nitro's version follows Nuxt — **Nuxt 4.x ships Nitro v2**
+> (`nitropack ^2.x`, via `@nuxt/nitro-server`; you have no direct `nitropack`
+> dependency). `nitro.build` now documents **Nitro v3**, which renames core APIs;
+> copying its examples verbatim breaks here. See [server-runtime.md](./server-runtime.md)
+> for the v2↔v3 mapping.
 
 ## When to Use This Skill
 
 Use this skill when:
-- Working in a Nuxt 3 project with TypeScript
+- Working in a Nuxt 4 project with TypeScript
 - Building API endpoints with Nitro
 - Implementing authentication with nuxt-auth-utils
 - Handling SSR + client-side state
@@ -21,13 +27,18 @@ Use this skill when:
 For detailed patterns, see these topic-focused reference files:
 
 - [validation.md](./validation.md) - Zod validation with h3, Standard Schema, error handling
-- [fetch-patterns.md](./fetch-patterns.md) - useFetch vs $fetch vs useAsyncData
+- [fetch-patterns.md](./fetch-patterns.md) - useFetch vs $fetch vs useAsyncData, refreshNuxtData
 - [auth-patterns.md](./auth-patterns.md) - nuxt-auth-utils, OAuth, WebAuthn, middleware
-- [page-structure.md](./page-structure.md) - Keep pages thin, components do the work
-- [composables-utils.md](./composables-utils.md) - When to use composables vs utils
-- [formatters.md](./formatters.md) - Centralize currency/date/number formatters in useFormatters, never inline
-- [ssr-client.md](./ssr-client.md) - SSR + localStorage, hydration, VueUse
+- [error-handling.md](./error-handling.md) - createError (fatal), error.vue, clearError, NuxtErrorBoundary
+- [state-management.md](./state-management.md) - useState (never a module-scope ref), clearNuxtState, callOnce
+- [composables-utils.md](./composables-utils.md) - composables vs utils, runtimeConfig public/private, runWithContext
+- [ssr-client.md](./ssr-client.md) - SSR + localStorage, hydration, useRequestURL/Headers, useCookie, VueUse
 - [deep-linking.md](./deep-linking.md) - URL params sync with filters and useFetch
+- [caching.md](./caching.md) - defineCachedFunction/EventHandler, SWR, per-key invalidation (Nitro v2)
+- [storage.md](./storage.md) - useStorage / unstorage KV layer, mounts
+- [route-rules.md](./route-rules.md) - declarative cache/headers/redirect/proxy/CORS per path
+- [server-runtime.md](./server-runtime.md) - **Nitro v2 vs v3 version pin**, middleware order, useEvent, internal-$fetch auth, WebSockets
+- [layers.md](./layers.md) - sharing components/composables/config across repos via extends
 - [nitro-tasks.md](./nitro-tasks.md) - Background jobs, scheduled tasks, job queues
 - [sse.md](./sse.md) - Server-Sent Events for real-time streaming
 - [server-services.md](./server-services.md) - Third-party service integration patterns
@@ -49,7 +60,7 @@ Working examples from a Nuxt project:
 2. **Use h3 validation** - `getValidatedQuery()`, `readValidatedBody()` with Zod schemas
 3. **Composables for context, utils for pure functions** - Composables access Nuxt context, utils are pure
 4. **SSR-safe code** - Guard browser APIs with `import.meta.client` or `onMounted`
-5. **Keep pages thin** - Pages = layout + route params + components. Components own data fetching and logic.
+5. **Keep pages thin** - Pages = layout + route params + components. Components own data fetching and logic. (Page composition + display formatting now live in the `vue-nuxt` skill.)
 
 ## Auto-Imports Quick Reference
 
@@ -72,7 +83,7 @@ From nuxt-auth-utils:
 All auto-imported:
 - Vue: `ref`, `computed`, `watch`, `onMounted`, etc.
 - VueUse: `refDebounced`, `useLocalStorage`, `useUrlSearchParams`, etc.
-- Nuxt: `useFetch`, `useAsyncData`, `useRoute`, `useRouter`, `useState`, `navigateTo`
+- Nuxt: `useFetch`, `useAsyncData`, `useRoute`, `useRouter`, `useState`, `navigateTo`, `callOnce`, `refreshNuxtData`, `clearNuxtState`, `useRequestURL`, `useRequestHeaders`, `useCookie`, `createError`, `showError`, `clearError`, `useNuxtApp`
 
 ### Shared (`/shared` directory - Nuxt 3.14+)
 
@@ -209,6 +220,8 @@ Needs Nuxt/Vue context (useRuntimeConfig, useRoute, refs)?
 8. **Cookie size limit is 4096 bytes** - Store only essential session data.
 9. **Ambiguous routes need type assertion** - See below.
 10. **Never use generic type params with useFetch/$fetch** - See below.
+11. **Never export a module-scope `ref` for shared state** - Leaks across SSR requests; use `useState`. See [state-management.md](./state-management.md).
+12. **Internal server `$fetch` doesn't forward cookies** - Pass `headers` explicitly or the callee sees no session. See [server-runtime.md](./server-runtime.md).
 
 ### Ambiguous Route Type Inference
 

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md

@@ -226,3 +226,4 @@ NUXT_OAUTH_GOOGLE_CLIENT_SECRET=...
 4. **setUserSession merges** - Use `replaceUserSession` to replace
 5. **requireUserSession throws** - Use getUserSession for null
 6. **Cannot use with `nuxt generate`** - Requires running server
+7. **`navigateTo` external routes need `{ external: true }`** - In-app routes: `navigateTo('/dashboard')`. Server/OAuth endpoints that aren't Vue routes (e.g. `/api/auth/google`, `/api/auth/preview-login`) must pass `navigateTo('/api/auth/google', { external: true })`, or Vue Router tries to resolve them as client routes and fails. Build query routes with `navigateTo({ path, query })` and `String()` any numeric ids.

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

@@ -0,0 +1,68 @@
+# Response & Function Caching (Nitro)
+
+Nitro ships a KV-backed cache layer with stale-while-revalidate and per-key
+invalidation. Reach for it before adding a memoization Map or a Postgres cache
+table. All helpers are **auto-imported in `server/`**.
+
+> **Nitro v2 names** (this project — see [server-runtime.md](./server-runtime.md)).
+> `nitro.build` documents v3, which moves these to `import { … } from "nitro/cache"`.
+> Here they are auto-imported globals.
+
+## `defineCachedFunction` — cache an expensive async function
+
+```typescript
+const getStars = defineCachedFunction(
+  async (repo: string) => {
+    const { stargazers_count } = await $fetch(`https://api.github.com/repos/${repo}`);
+    return stargazers_count as number;
+  },
+  {
+    maxAge: 60 * 60,       // serve from cache for 1h
+    swr: true,             // after maxAge, serve stale and revalidate in the background
+    name: "ghStars",
+    group: "nitro/functions",
+    getKey: (repo) => repo,  // cache key from the args
+  },
+);
+
+await getStars("unjs/nitro");
+await getStars.invalidate("unjs/nitro");  // drop one key on demand (e.g. after a mutation)
+```
+
+`getKey` is what makes it safe to call with different arguments — without it,
+every arg shares one cache entry.
+
+## `defineCachedEventHandler` — cache a whole endpoint
+
+```typescript
+export default defineCachedEventHandler(
+  async (event) => ({ now: Date.now(), data: await loadData() }),
+  {
+    maxAge: 60,
+    swr: true,
+    varies: ["host"],                        // vary the key on these headers
+    shouldBypassCache: (event) => !!getQuery(event).fresh,  // skip cache for ?fresh=1
+    getKey: (event) => event.path,
+  },
+);
+```
+
+Don't cache an endpoint whose body depends on the session/user unless you `vary`
+on the discriminator — otherwise one user's response is served to another.
+
+## Where the cache lives
+
+The cache backs onto the `cache` **storage mount** (see [storage.md](./storage.md)):
+filesystem in dev, whatever you mount (Redis, etc.) in production. Configure via
+`nitro.storage` / `nitro.devStorage` in `nuxt.config.ts`.
+
+## Gotchas
+
+- **`maxAge` is seconds, not ms.**
+- **`swr: true`** means a request after expiry gets the *stale* value immediately
+  while a background refresh runs — great for latency, but readers can see
+  slightly old data. Omit it for must-be-fresh endpoints.
+- **Invalidate on write.** After a mutation changes the source data, call
+  `fn.invalidate(key)` — caches don't know your DB changed.
+- **Route-level caching** for simple cases can be declared without a handler
+  wrapper via `routeRules` (`swr` / `cache`) — see [route-rules.md](./route-rules.md).

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/composables-utils.md

@@ -82,7 +82,7 @@ export const usePermissions = () => {
 > **Formatters belong in one shared place.** The examples below show util *placement*,
 > not where to call formatters from. Never define a currency/date/number formatter inline
 > at the call site — centralize them in `useFormatters` or a shared util, and prefer
-> VueUse / date-fns over hand-rolling. See [formatters.md](./formatters.md).
+> VueUse / date-fns over hand-rolling. See the `vue-nuxt` skill's `formatters.md`.
 
 ```typescript
 // utils/formatting.ts
@@ -161,6 +161,35 @@ export function formatCurrency(amount: number) {
 // - /pages/invoice.vue
 ```
 
+## `useRuntimeConfig`: `public` on the client, private on the server
+
+Only `config.public.*` exists in client code. Reading a private (top-level) key
+in the browser returns an empty string — a silent bug, not an error:
+
+```typescript
+const config = useRuntimeConfig();
+config.public.apiBase;   // ✅ client + server
+config.apiSecret;        // ✅ server only — ❌ empty on the client
+```
+
+Env binding follows the split: `NUXT_*` → server keys, `NUXT_PUBLIC_*` → public
+keys. Put anything a browser must never see under a private (non-`public`) key.
+
+## Calling a composable after `await`: `runWithContext`
+
+Composables and `navigateTo` must run in Nuxt's context. After an `await`, that
+context can be lost — the classic **"Nuxt instance unavailable"** error. Restore
+it with `nuxtApp.runWithContext`:
+
+```typescript
+const nuxtApp = useNuxtApp();
+const result = await someAsyncWork();
+return nuxtApp.runWithContext(() => navigateTo("/next"));  // ✅ context restored post-await
+```
+
+(Capture `useNuxtApp()`/the composable result *before* the await when you can;
+`runWithContext` is the escape hatch for when you can't.)
+
 ## Summary Table
 
 | Location | Naming | Vue APIs | Auto-imported | Use Case |
@@ -176,4 +205,5 @@ export function formatCurrency(amount: number) {
 2. **Don't use Vue APIs in utils** - Keeps them testable and portable
 3. **Server utils can't use Vue** - Different runtime
 4. **Auto-import scoping** - `/utils` is client-only, `/server/utils` is server-only
-5. **Composables call order matters** - Call at top of `<script setup>`, not in callbacks
+5. **Composables call order matters** - Call at top of `<script setup>`, not in callbacks, and **never inside a template expression** - a composable invoked from the template (or a callback) runs outside the request/setup scope and throws "must be called at the top of setup". Call it once in setup, then use the returned helpers/refs in the template.
+6. **Guard possibly-null data when deriving** - Composables like `useUserSession` expose refs that can be `null` (logged out, still loading). Derive display state through a `computed` with a null guard (`computed(() => user.value ? getInitials(user.value) : '')`), not a bare property access that assumes presence.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md

@@ -0,0 +1,74 @@
+# Error Handling (client + server)
+
+The skill covers throwing `createError` in API handlers (see `auth-patterns.md`).
+This file is the **client/page** surface: triggering the error page, the
+`error.vue` root, recovering, and containing a failure to a subtree.
+
+## `createError` — fatal vs non-fatal
+
+`createError` works on both sides. On the **server** it sets the HTTP status. On
+the **client/page**, a `createError` with `fatal: true` replaces the whole page
+with the error page (`error.vue`); without `fatal`, it's a non-fatal error you
+handle locally:
+
+```typescript
+// page setup — show the full-screen error page for a missing resource
+const { data } = await useFetch(`/api/invoices/${id}`);
+if (!data.value) {
+  throw createError({ statusCode: 404, statusMessage: "Invoice not found", fatal: true });
+}
+```
+
+`showError(...)` is the imperative equivalent (call it from a handler instead of
+throwing). Pass `data` on the error to carry structured detail to `error.vue`.
+
+## `error.vue` — the app-root error page
+
+A single `error.vue` at the project root renders for any fatal error (and SSR
+500s). It receives the error as a prop and clears it with `clearError`:
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{ error: NuxtError }>();
+// clearError unmounts the error page; redirect clears the errored route
+const handled = () => clearError({ redirect: "/" });
+</script>
+
+<template>
+  <div>
+    <h1>{{ error.statusCode }}</h1>
+    <p>{{ error.statusMessage }}</p>
+    <button @click="handled">Go home</button>
+  </div>
+</template>
+```
+
+Only `clearError` dismisses the error page — re-rendering won't. Gotcha: on the
+error page, **middleware re-runs** but **plugins do not re-run** until you
+`clearError()`, so don't rely on plugin-provided state inside `error.vue`.
+
+## `<NuxtErrorBoundary>` — contain a failure to a subtree
+
+When one widget can fail without taking down the page (a flaky third-party embed,
+an optional panel), wrap it so the error is caught locally instead of bubbling to
+`error.vue`:
+
+```vue
+<NuxtErrorBoundary @error="logError">
+  <RiskyWidget />
+  <template #error="{ error, clearError }">
+    <p>Couldn't load this section.</p>
+    <button @click="clearError">Retry</button>
+  </template>
+</NuxtErrorBoundary>
+```
+
+## Which to reach for
+
+| Situation | Use |
+|---|---|
+| Resource missing / unauthorized in page setup | `throw createError({ …, fatal: true })` |
+| Imperatively show the error page from a handler | `showError(...)` |
+| Render for any fatal error, app-wide | `error.vue` + `clearError` |
+| One section may fail without killing the page | `<NuxtErrorBoundary>` |
+| API handler rejecting a request | `createError` (status code) — see `auth-patterns.md` |

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md

@@ -121,6 +121,24 @@ const handleDelete = async (id: number) => {
 };
 ```
 
+## Invalidating after a mutation
+
+`refresh()` re-pulls a single `useFetch`. When a mutation affects data loaded by
+**other** components, use the global `refreshNuxtData(keys?)` instead of wiring
+cross-component refresh plumbing — it re-runs every matching `useFetch`/
+`useAsyncData` payload:
+
+```typescript
+await $fetch("/api/invoices", { method: "POST", body });
+await refreshNuxtData(["invoices", "invoice-summary"]);  // re-pull by explicit key
+// refreshNuxtData() with no args refetches everything (use sparingly)
+```
+
+For this to target precisely, give the fetches explicit keys
+(`useAsyncData("invoices", …)` / `useFetch("/api/invoices", { key: "invoices" })`).
+`clearNuxtData(keys?)` drops cached payload + error state without refetching (e.g.
+reset a wizard's loaded data on cancel).
+
 ## Type Inference
 
 Template literals preserve type inference (fixed late 2024):

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

@@ -0,0 +1,40 @@
+# Nuxt Layers
+
+Layers let multiple Nuxt projects share components, composables, utils, server
+routes, and config. Relevant when a base/template repo feeds several apps — e.g. a
+copier-scaffolded house style, or a shared design system across products.
+
+## Extending
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    "../base-layer",          // local path
+    "@my-org/nuxt-theme",     // npm package
+    ["github:my-org/layer", { install: true }],  // remote
+  ],
+});
+```
+
+Auto-imports work **across** layers — a composable in the base layer is available
+unprefixed in the consumer, same as a local one.
+
+## Precedence
+
+Project root **overrides** `~~/layers/*` (alphabetical) **overrides** `extends`
+entries (in listed order). So a consumer can shadow any layer file by placing a
+file at the same path. Local `~~/layers/*` directories are auto-registered without
+listing them in `extends`; they also get `#layers/*` aliases.
+
+## When a layer vs a package vs the agent-skills repo
+
+| Sharing | Use |
+|---|---|
+| Runtime Nuxt surface (components, composables, server routes, config) | a **layer** (`extends`) |
+| Framework-agnostic JS/TS logic | a plain npm package |
+| Agent guidance / Claude skills | the `@gallopsystems/agent-skills` package |
+
+Don't reach for a layer to share a pure function — that's a package. Layers earn
+their weight when you're sharing *Nuxt-shaped* surface (auto-imported components,
+pages, server handlers) and config.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/route-rules.md

@@ -0,0 +1,41 @@
+# Route Rules
+
+`routeRules` in `nuxt.config.ts` declaratively apply caching, headers, redirects,
+proxying, and CORS per URL pattern — no handler code. Reach for them before
+hand-rolling middleware to do what a rule does in one line.
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  routeRules: {
+    "/api/**":          { cors: true },                          // CORS on all API routes
+    "/api/realtime/**": { cache: false },                        // never cache SSE/streaming
+    "/blog/**":         { swr: 3600 },                           // cache + revalidate hourly
+    "/docs/**":         { prerender: true },                     // render at build time
+    "/old-path":        { redirect: "/new-path" },               // 301 (redirectCode to change)
+    "/external/**":     { proxy: "https://upstream.example/**" },// reverse-proxy
+    "/admin/**":        { headers: { "X-Robots-Tag": "noindex" } },
+  },
+});
+```
+
+## Semantics
+
+- **Specificity wins:** a more specific path overrides a general one; `/api/**`
+  rules are overridden by `/api/realtime/**`.
+- **`swr: N`** = stale-while-revalidate for N seconds; **`cache: { maxAge: N }`**
+  for a plain TTL; **`cache: false`** disables inherited caching (use on
+  streaming/per-user routes that a broader rule would otherwise cache).
+- **`isr`** (incremental static regen) is the same idea on supported platforms.
+- Rules apply to both Nitro routes and rendered pages under the path.
+
+## When to use a rule vs a handler
+
+| Want | Use |
+|---|---|
+| Cache/headers/redirect/proxy/CORS by path | `routeRules` |
+| Per-key cache with invalidation, SWR on a function | `defineCachedFunction` — [caching.md](./caching.md) |
+| Logic (auth, body inspection, dynamic redirect) | server middleware / handler — [server-runtime.md](./server-runtime.md) |
+
+Don't write a middleware that just sets a static header or redirects a fixed path
+— that's a route rule.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-runtime.md

@@ -0,0 +1,97 @@
+# Nitro Server Runtime (version, middleware, context, $fetch, ws)
+
+Server-side mechanics that aren't endpoints or validation: which Nitro you're on,
+how `server/middleware/` runs, reading the event without threading it, the
+internal-`$fetch` auth trap, and the WebSocket option.
+
+## ⚠️ Version: Nitro follows Nuxt — you're on v2
+
+Nitro's version is **set by Nuxt, not chosen by you**. Nuxt 4.x ships
+`@nuxt/nitro-server`, which depends on `nitropack ^2.x` — you have no direct
+`nitropack` dependency to bump. **`nitro.build` now documents Nitro v3**, a
+separate in-progress major Nuxt has not adopted; copying its examples verbatim
+gives you code that doesn't compile here. Ignore the v3 renames until Nuxt ships
+on v3. Map back to v2:
+
+| v3 docs (nitro.build) | v2 (this project) |
+|---|---|
+| `defineHandler` | `defineEventHandler` (auto-imported) |
+| `definePlugin` | `defineNitroPlugin` |
+| `import { defineCachedEventHandler } from "nitro/cache"` | auto-imported global |
+| `features: { websocket: true }` | `experimental: { websocket: true }` |
+| `routes/` directory | `server/` directory |
+| `render:response` → `response` hook | `render:response` |
+
+When unsure, trust the installed `node_modules/nitropack/dist/runtime/*.d.ts`
+over the website.
+
+## Server middleware (`server/middleware/`)
+
+Every request runs **all** files in `server/middleware/` (not route-scoped).
+Three rules that bite:
+
+- **Order is filename order** — prefix numerically: `1.logger.ts`, `2.auth.ts`.
+- **Don't return a value.** Returning a body **ends the request** there. Set
+  `event.context.*` and return nothing.
+- **Scope by checking `event.path`** yourself — there's no per-path registration.
+
+```typescript
+// server/middleware/2.auth.ts — runs after 1.*, sets context, returns nothing
+export default defineEventHandler((event) => {
+  if (!event.path.startsWith("/api/")) return;
+  event.context.user = parseUser(event);   // ❌ a `return user` here would 200 every request
+});
+```
+
+## `useEvent()` — read the event without threading it
+
+With `experimental.asyncContext: true` (set in `nuxt.config.ts`), `useEvent()`
+returns the current `H3Event` from async context, so deep util/service layers can
+read the session/headers without every caller passing `event` down:
+
+```typescript
+// nuxt.config.ts → nitro: { experimental: { asyncContext: true } }
+import { useEvent } from "nitropack/runtime";   // auto-imported in server/
+
+export async function currentUser() {
+  const event = useEvent();                       // no event parameter needed
+  return (await getUserSession(event)).user;
+}
+```
+
+Node-runtime only; it's flagged experimental. Without the flag, `useEvent()`
+throws — keep threading `event` explicitly.
+
+## Internal `$fetch` does NOT forward cookies
+
+On the server, `$fetch("/api/…")` to an internal route short-circuits HTTP (direct
+handler call — faster), but it **does not carry the incoming request's
+cookies/headers**. A session-dependent internal call silently sees no user. Pass
+them through:
+
+```typescript
+// inside a handler, calling another internal route that needs the session:
+await $fetch("/api/me", { headers: { cookie: getHeader(event, "cookie") ?? "" } });
+```
+
+## WebSockets — when SSE isn't enough
+
+[sse.md](./sse.md) covers one-way streaming. For bidirectional (client → server),
+Nitro has `defineWebSocketHandler` behind `experimental.websocket: true` (NOT v3's
+`features.websocket`), with built-in pub/sub:
+
+```typescript
+// server/routes/ws.ts
+export default defineWebSocketHandler({
+  open(peer) { peer.subscribe("room"); },
+  message(peer, msg) { peer.publish("room", msg.text()); },  // publish excludes sender
+  close(peer) { /* cleanup */ },
+});
+```
+
+## Two `useDatabase`s — don't confuse them
+
+Nitro ships its own `useDatabase()` (a `db0`-backed SQL layer, gated on
+`experimental.database`). This project **shadows** it with the Kysely
+`useDatabase()` in `server/utils/db.ts` (see [composables-utils.md](./composables-utils.md)).
+Use the Kysely one; don't enable `nitro.database` or import Nitro's.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/ssr-client.md

@@ -113,6 +113,66 @@ With `@vueuse/nuxt`, these are auto-imported:
 - `useFetch` - use Nuxt's version
 - `useHead` - use Nuxt's version
 
+## `useCookie` / `useState` for SSR-shared state
+
+`useLocalStorage` reads only on the client, so state that must be **correct in the
+first server-rendered paint** (a theme, sidebar-collapsed flag, accounting-basis
+toggle) flickers if stored in localStorage. Persist it in a cookie instead — the
+server sees it and renders the right thing immediately:
+
+```typescript
+const basis = useCookie<"accrual" | "cash">("basis", { default: () => "accrual" });
+// readable during SSR; writes sync to the cookie. No onMounted flicker.
+```
+
+For SSR-shared state that needn't persist across reloads, use `useState` (it
+serializes the server value to the client, so both render identically). See
+[state-management.md](./state-management.md) for the full `useState` story
+(including the never-export-a-module-`ref` rule):
+
+```typescript
+const expanded = useState("nav-expanded", () => false);
+```
+
+`useState` is also the fix for **SSR-nondeterministic values** — anything from
+`Math.random()` / `Date.now()` rendered into markup mismatches on hydration unless
+the server's choice is serialized:
+
+```typescript
+const variant = useState("hero-variant", () => Math.floor(Math.random() * 3)); // server picks once, client reuses
+```
+
+### `useCookie` options worth knowing
+
+- **Nested writes need `watch: 'deep'`** — the default shallow watch won't
+  persist a mutation to a nested property of a cookie object.
+- **`httpOnly` cookies are unreadable client-side** — reading one in setup yields
+  different values on server vs client → hydration mismatch.
+- **`refreshCookie(name)`** re-syncs the ref if the cookie changed out-of-band
+  (e.g. set by an API response).
+- 4 KB size limit (see gotcha below).
+
+## SSR-safe URL & request headers
+
+`window.location` and request headers don't exist during SSR. Don't guard them
+away — use the universal composables that work on both sides:
+
+- **`useRequestURL()`** → a `URL` object available on server *and* client. Use it
+  for `origin`/`hostname`/`searchParams` instead of `window.location`:
+
+  ```typescript
+  const url = useRequestURL();
+  const origin = url.origin;   // works during SSR; window.location would throw
+  ```
+
+- **`useRequestHeaders(['cookie'])`** → inbound request headers on the server
+  (`{}` on the client). The canonical way to **forward auth** when an SSR
+  `useFetch` calls an endpoint that needs the session cookie:
+
+  ```typescript
+  const { data } = await useFetch("/api/me", { headers: useRequestHeaders(["cookie"]) });
+  ```
+
 ## Hydration Mismatch Prevention
 
 **Problem:** Server renders with default, client reads different value = mismatch.

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

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