@mrciphersmith/keryx 0.2.164 → 0.3.1

package/src/gdskills/bundled/stacks/nextjs-nuxt/governance/scout.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Use when implementing a new page, route, or data-fetching feature in a Next.js App Router or Nuxt 3+ project: choosing Server vs. Client Components ('use client' placement), a Nuxt composable/page fetching data with useFetch/useAsyncData, a Server Action ('use server') or Nuxt server/api route, or a route's rendering mode (static/ISR/revalidate vs. Nuxt's ssr/routeRules). Not for plain React component logic with no meta-framework routing/data concern (use react-implementation), plain Vue SFC logic outside Nuxt's routing/server layer (use vue-implementation), or fixing an existing build/type error (use nextjs-nuxt-build-fix).",
+    "decision": "use",
+    "topMatch": "nextjs-nuxt/nextjs-nuxt-testing",
+    "recordedAt": "2026-09-25T06:43:38.521Z",
+    "skillName": "nextjs-nuxt-implementation",
+    "justification": "extends react-implementation/vue-implementation coverage to Next.js App Router / Nuxt 3 routing+data-fetching specifically; existing react/vue implementation skills explicitly excluded via disclaimer, no meta-framework skill exists"
+  },
+  {
+    "query": "Use when writing or fixing tests for a Next.js App Router page/Server Action or a Nuxt page/composable/server route: testing a Server Component's rendered output, a Client Component's interactivity with React Testing Library, a Nuxt composable that calls useFetch/useAsyncData with @nuxt/test-utils' mountSuspended, or a server/api handler's auth and validation paths. Not for plain React/Vue component unit tests with no meta-framework routing, SSR, or server-route concern (use react-testing/vue-testing), and not for implementing the feature under test (use nextjs-nuxt-implementation).",
+    "decision": "use",
+    "topMatch": "nextjs-nuxt/nextjs-nuxt-implementation",
+    "recordedAt": "2026-09-25T06:43:51.459Z",
+    "skillName": "nextjs-nuxt-testing",
+    "justification": "mutual same-pack overlap with nextjs-nuxt-implementation (both describe the same App Router/Nuxt surface, scores 0.594/0.621); accepted per flow 318 journal as a lexical-scorer limitation applied to two genuinely distinct skill categories (implement vs. test), not a duplicate skill"
+  },
+  {
+    "query": "Use when reviewing a diff that touches Next.js App Router files ('use client'/'use server' directives, Route Handlers, revalidatePath/revalidateTag) or Nuxt files (composables, server/api routes, nuxt.config.ts routeRules/runtimeConfig) for meta-framework-specific risk: a misplaced Server/Client boundary, a composable called outside setup context, a hydration-mismatch-prone render, a rendering-mode choice that doesn't match the data's actual freshness need, or an unauthenticated Server Action/server route. Does not edit code. Not for general React/Vue component review with no App Router/Nuxt-specific concern (use review-frontend or a react/vue pack review skill), and not for NestJS backend review (use review-backend).",
+    "decision": "fork",
+    "topMatch": "nextjs-nuxt/nextjs-nuxt-implementation",
+    "recordedAt": "2026-09-25T06:43:59.476Z",
+    "skillName": "nextjs-nuxt-code-review",
+    "justification": "shares review vocabulary with review-frontend/review-backend/vue/react review skills but scoped specifically to App Router / Nuxt meta-framework files (Server Actions, routeRules, composables) that no existing review skill covers"
+  },
+  {
+    "query": "Use when resolving a Next.js build/type error ('use client'/'use server' boundary violation, a Server Component importing a client-only hook, an invalid Route Handler export) or a Nuxt build/type error (an auto-imported composable/component that fails to resolve, a nuxi typecheck failure, a hydration-mismatch warning) blocking `next build` or `nuxi build`. Applies the smallest root-cause fix and never silences it with ssr: false, suppressHydrationWarning, or a widened tsconfig. Not for generic tsc/ESM module-resolution errors with no meta-framework cause (use nodejs-build-fix), and not for implementing a new feature (use nextjs-nuxt-implementation).",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-build-fix",
+    "recordedAt": "2026-09-25T06:44:07.524Z",
+    "skillName": "nextjs-nuxt-build-fix",
+    "justification": "shares generic build-fix vocabulary with nodejs-build-fix but is scoped to Next.js/Nuxt-specific compile failures (Server/Client boundary violations, composable auto-import resolution, nuxi typecheck) that nodejs-build-fix's own disclaimer explicitly excludes"
+  },
+  {
+    "query": "Use when migrating a Next.js project from the Pages Router to the App Router, upgrading a Next.js major version, or migrating a Nuxt 2 project to Nuxt 3+ (Options API to Composition API, the Vuex-to-Pinia move, module/plugin API changes). Covers rewriting data-fetching (getServerSideProps/getStaticProps to Server Components and route rendering config; asyncData/fetch to useAsyncData/useFetch), routing conventions, and rendering-mode equivalents between the old and new APIs. Not for a same-version bug fix or new feature (use nextjs-nuxt-implementation/nextjs-nuxt-build-fix), and not for a plain React/Vue version bump with no meta-framework routing change (use react-upgrade-migration or the vue pack's migration skill).",
+    "decision": "fork",
+    "topMatch": "nextjs-nuxt/nextjs-nuxt-implementation",
+    "recordedAt": "2026-09-25T06:44:07.697Z",
+    "skillName": "nextjs-nuxt-upgrade-migration",
+    "justification": "shares Next.js/Nuxt vocabulary with nextjs-nuxt-implementation but is scoped specifically to version-migration mechanics (Pages->App Router, Vue 2 Options API->Vue 3 Composition API, Vuex->Pinia) that react-upgrade-migration's own disclaimer explicitly excludes for the meta-framework case"
+  }
+]

package/src/gdskills/bundled/stacks/nextjs-nuxt/pack.json

@@ -0,0 +1,42 @@
+{
+  "id": "nextjs-nuxt",
+  "family": "framework",
+  "extends": ["react", "vue"],
+  "modules": ["nextjs-nuxt-rules", "nextjs-nuxt-skills"],
+  "detectionMarkers": ["nextjs", "nuxt"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 318, Wave 4 batch 2"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["nextjs-nuxt-implementation"],
+    "test": ["nextjs-nuxt-testing"],
+    "review": ["nextjs-nuxt-code-review"],
+    "build-fix": ["nextjs-nuxt-build-fix"],
+    "migrate": ["nextjs-nuxt-upgrade-migration"]
+  },
+  "agentProfile": {
+    "displayName": "Next.js / Nuxt",
+    "auditFocus": [
+      "a Next.js Server Component importing browser-only APIs, hooks, or event handlers with no 'use client' boundary, or a 'use client' pushed higher up the tree than the leaf that actually needs it",
+      "a Nuxt composable (a useX function) called outside a component's setup()/<script setup> context, a plugin, or middleware, where it cannot access Nuxt's injection context",
+      "a server-only secret read without the framework's public-var guard (a bare env var reaching the client instead of NEXT_PUBLIC_-prefixed, or Nuxt's private runtimeConfig read from a component instead of its public: block)",
+      "a data-fetch that re-runs on every request when the route was clearly meant to be static/ISR (Next's revalidate) or Nuxt's cached/prerendered, or a page marked static that actually needs per-request data",
+      "a Server Action ('use server') or Nuxt server route (server/api/**) with no auth/authorization check before it touches data",
+      "a component rendering a nondeterministic value (Date.now(), Math.random(), locale-dependent formatting) directly in its render path, which mismatches between server and client hydration"
+    ],
+    "buildCommands": [
+      "the project's type-check script (tsc --noEmit for Next.js, or nuxi typecheck for Nuxt)",
+      "next build (Next.js) or nuxi build (Nuxt) — read the framework's own build output for prerender, route, and boundary errors, not just exit code",
+      "the project's lint script (next lint / eslint-config-next, or @nuxt/eslint-config)",
+      "the project's test script (Jest or Vitest with React Testing Library, or Vitest with Vue Test Utils/@nuxt/test-utils)"
+    ],
+    "fixGuardrails": [
+      "never move a 'use client' directive up to a shared layout or ancestor component to silence a Server/Client Component boundary error — narrow it to the actual leaf that needs browser APIs, state, or event handlers",
+      "never hand-import or re-path a Nuxt auto-imported composable/component to unblock a type or resolution error when the real fix is registering or exporting it correctly (checking nuxt.config.ts's imports/components dirs)",
+      "never rename a server-only secret under NEXT_PUBLIC_ or into Nuxt's public runtimeConfig just to make it reachable from client code that shouldn't have it",
+      "never delete or skip a failing SSR/hydration test, or wrap a hydration mismatch in suppressHydrationWarning/<ClientOnly>, to reach a green build instead of fixing the nondeterministic render"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/nextjs-nuxt/rules/coding-style.mdc

@@ -0,0 +1,69 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx", "**/*.vue"]
+metadata:
+  origin: authored
+---
+
+# Next.js / Nuxt coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to the two
+meta-frameworks this pack covers: Next.js (App Router, React) and Nuxt
+(Vue 3). Applies to `.tsx`/`.jsx` (Next.js) and `.vue` (Nuxt) files — a
+project using only one of the two frameworks still gets guidance scoped to
+that framework from the sections below; a monorepo with both gets both.
+
+## File and directory naming
+
+- Next.js App Router: route segment folders are `kebab-case`
+  (`app/order-history/page.tsx`); reserved file names (`page.tsx`,
+  `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`) stay exactly as the
+  framework requires them — do not rename them for house style.
+- Nuxt: page files under `pages/` are `kebab-case` and map to routes by
+  file-system convention (`pages/order-history.vue` ->
+  `/order-history`); a dynamic segment is `pages/orders/[id].vue`, a
+  catch-all `pages/[...slug].vue`. Component files are `PascalCase.vue`.
+- Composables (Nuxt) and custom hooks (Next.js/React) both start with
+  `use` (`useOrderTotals.ts`, `useOrderTotals`), one export per file for a
+  non-trivial composable/hook.
+
+## Component and directive placement
+
+- Next.js: every component file is a Server Component by default; add
+  `'use client'` as the FIRST line of a file only when that file itself
+  needs browser state (`useState`, `useEffect`), event handlers, or a
+  browser-only API — not because an ancestor or descendant needs it. Keep
+  the directive on the smallest leaf component that actually needs it.
+- Nuxt: use `<script setup lang="ts">` for new single-file components
+  instead of the Options API or a bare `<script>` with `defineComponent` —
+  it is the current idiomatic form and gives auto-imported
+  `ref`/`computed`/`watch` without explicit imports.
+- Type props explicitly: Next.js components take a typed `props` object
+  (an interface or inline type, not `any`); Nuxt SFCs declare props with
+  `defineProps<{ ... }>()` (the type-only generic form), not the runtime
+  object form, for anything beyond a trivial component.
+
+## Imports and auto-imports
+
+- Nuxt auto-imports composables from `composables/`, components from
+  `components/`, and utils from `utils/` — do not hand-import something
+  Nuxt already auto-imports (it adds a redundant, easily-stale import
+  line); DO explicitly import anything outside those conventional
+  directories.
+- Next.js has no auto-import convention — import explicitly, using the
+  project's configured path aliases (`@/components/...`) instead of long
+  relative chains once the project has one configured.
+
+## Formatting and typing
+
+- Format with the project's configured formatter (Prettier is standard for
+  both ecosystems); do not hand-format around one that is already
+  configured.
+- Avoid `any` for props, route params, and fetch responses in either
+  framework — type route params from Next.js's generated `PageProps`
+  types (or the project's own param type) and Nuxt's `useRoute().params`
+  by name, not by casting.
+- Server-only code (`'use server'` files, Nuxt `server/` routes) and
+  client-only code should not share a barrel import file that re-exports
+  both — that is how a server-only secret or a `node:` import ends up
+  bundled into client JavaScript.

package/src/gdskills/bundled/stacks/nextjs-nuxt/rules/patterns.mdc

@@ -0,0 +1,88 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx", "**/*.vue"]
+metadata:
+  origin: authored
+---
+
+# Next.js / Nuxt patterns
+
+Idiomatic meta-framework design for Next.js's App Router and Nuxt 3+ —
+routing conventions, rendering-mode choice, and data fetching, covering
+both where their concerns diverge and where they converge. Narrows
+`core-common-rules`; framework-agnostic design patterns still come from
+there.
+
+## Server/client boundary (Next.js) and setup context (Nuxt)
+
+- Fetch data in Server Components (no `'use client'`) by default; push
+  `'use client'` only to the interactive leaf (a button, a form, a chart
+  that needs a browser API) so the rest of the tree stays server-rendered
+  and out of the client bundle.
+- Pass data down from a Server Component to a Client Component as plain
+  serializable props — a Client Component cannot `await` a server-only
+  data call itself; if it needs fresh data after mount, call a Route
+  Handler (`app/api/.../route.ts`) or a Server Action, not a re-implemented
+  server-only fetch client-side.
+- A Server Action is declared with `'use server'` (file-level or inline in
+  an async function) and can be called directly from a form's `action`
+  prop or a Client Component's event handler; mutate, then call
+  `revalidatePath()`/`revalidateTag()` so the affected route re-renders
+  with fresh data in the same round trip — don't hand-roll a client-side
+  refetch-after-mutation when a Server Action + revalidate already covers
+  it.
+- Nuxt composables (`useX`) must be called synchronously during a
+  component's `setup()` (top level of `<script setup>`), a plugin, or
+  middleware — never inside an `async` callback, a `setTimeout`, or after
+  an `await` inside setup, because Nuxt resolves a composable's injection
+  context (route, app, Pinia store) synchronously at call time.
+
+## Rendering modes
+
+- Next.js: a route is static by default (build-time render, cached);
+  reading `cookies()`/`headers()`/a `searchParams` prop, or an uncached
+  `fetch`, opts it into dynamic per-request rendering. Use
+  `export const revalidate = <seconds>` for ISR when the data is allowed
+  to go stale for a bounded window rather than forcing full dynamic
+  rendering.
+- Nuxt: `ssr: true` (default) renders on each request; `routeRules` in
+  `nuxt.config.ts` set per-route rendering (`{ '/blog/**': { isr: 3600 } }`
+  for ISR-like caching, `{ '/app/**': { ssr: false } }` for an SPA-only
+  section, `{ '/': { prerender: true } }` for static). Choose the rule per
+  route instead of setting `ssr: false` globally when only part of the app
+  needs it.
+- Both frameworks: a component that needs data on first paint should fetch
+  it where the framework already renders (Server Component / `useFetch`),
+  not fetch client-side after an empty shell — that trade-off (an extra
+  client round trip, a loading flash) should be a deliberate choice, not
+  the default from not knowing the server-fetch path exists.
+
+## Data fetching
+
+- Next.js: `fetch()` inside a Server Component is deduplicated and cached
+  by the framework across a single render pass — prefer it over a
+  third-party data-fetching library for simple server-side reads unless
+  the project already standardizes on one (e.g. a query library for
+  client-side cache/mutation needs).
+- Nuxt: use `useFetch`/`useAsyncData` for data a page needs during SSR
+  (they dedupe across server and client and hydrate without a second
+  request); a plain `$fetch` call inside `onMounted` only re-fetches
+  client-side and loses SSR — use it for a genuinely client-only,
+  post-interaction call (e.g. in response to a click), not initial page
+  data.
+- Both: key async data explicitly (`useAsyncData('orders', ...)` in Nuxt;
+  a stable cache key in whatever client-side query library Next.js code
+  uses) — an unkeyed or auto-keyed-by-reference call can silently refetch
+  or fail to dedupe across re-renders/navigations.
+
+## Anti-patterns
+
+- Marking an entire page or layout `'use client'` to fix one interactive
+  child, instead of isolating the directive to that child.
+- Reaching for `ssr: false` on a whole Nuxt page to work around a
+  hydration mismatch instead of finding the actual nondeterministic
+  render source.
+- Storing derived/computed state in a `ref`/`useState` and syncing it with
+  an effect/`watch`, instead of computing it inline with `computed()` or
+  during render — both frameworks' reactivity systems already handle
+  derivation without an effect.

package/src/gdskills/bundled/stacks/nextjs-nuxt/rules/security.mdc

@@ -0,0 +1,72 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.ts"]
+metadata:
+  origin: authored
+---
+
+# Next.js / Nuxt security
+
+Stack-specific risks for Next.js's App Router and Nuxt's server layer, with
+the safe pattern to use instead of each. Narrows `core-common-rules`;
+generic web risks (XSS, CSRF fundamentals) still come from there — this
+file covers where each framework's own boundary can leak.
+
+## Environment variable and secret exposure
+
+- Next.js: only a variable prefixed `NEXT_PUBLIC_` is inlined into the
+  client bundle; every other `process.env.*` read in a file that ships to
+  the client is `undefined` at runtime, which itself is a signal — but the
+  real risk is the reverse: never prefix a secret (API key, DB URL, signing
+  secret) with `NEXT_PUBLIC_` just to make a client read succeed, and never
+  read a non-`NEXT_PUBLIC_` secret from a file that lacks a `'use server'`/
+  server-only boundary and could be pulled into a client bundle by an
+  import chain.
+- Nuxt: `nuxt.config.ts`'s `runtimeConfig` splits `public` (sent to the
+  client) from the top-level/private keys (server-only). Never move a
+  secret into the `public` block to reach it from a component — read it
+  server-side only (`server/api/*` handlers, or a server-only composable)
+  and expose only the derived, non-sensitive result to the client.
+
+## Server Actions and server routes
+
+- Every Next.js Server Action (`'use server'`) and Nuxt `server/api/**`
+  handler is a public HTTP endpoint even though it looks like an internal
+  function call — re-check auth/authorization inside the action/handler
+  itself; do not rely on the calling component having already checked,
+  since the endpoint is reachable directly.
+- Re-validate every argument a Server Action or Nuxt server route receives
+  server-side (type, ownership, range) even when the client already
+  validated the form — client-side validation is a UX affordance, not a
+  security boundary.
+- Nuxt: read cookies/headers via `useRequestEvent()`/`getCookie(event, ...)`
+  inside `server/api/**`, not by trusting a value the client sent in the
+  request body for something that should be derived from an authenticated
+  session.
+
+## Rendering and injection
+
+- Next.js: `dangerouslySetInnerHTML` with unsanitized user content is an
+  XSS vector in a Server Component exactly as much as a Client one —
+  server rendering does not sanitize it; run it through a sanitizer (e.g.
+  DOMPurify server-side) before it reaches the prop, or avoid raw HTML
+  injection entirely.
+- Nuxt/Vue: `v-html` with unsanitized user content is the equivalent risk
+  in a `.vue` template — sanitize before binding, never bind raw user
+  input directly.
+- Both: a value interpolated into a `<script>` tag, an inline event
+  handler string, or a redirect URL built from user input (open-redirect
+  risk) needs the same scrutiny as any other untrusted-input sink — encode
+  or allowlist, don't string-concatenate.
+
+## Route and middleware auth
+
+- Next.js: `middleware.ts` runs on the Edge runtime and can check auth
+  before a route renders, but it cannot be the ONLY check — a Server
+  Component/Route Handler that skips its own auth check because
+  "middleware already handles it" breaks the moment middleware's matcher
+  config changes; check again where the data is actually read.
+- Nuxt: a route middleware (`defineNuxtRouteMiddleware`) guards
+  client-side navigation but does not protect the underlying
+  `server/api/**` endpoint — protect the API handler itself, not just the
+  page route.

package/src/gdskills/bundled/stacks/nextjs-nuxt/rules/testing.mdc

@@ -0,0 +1,64 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx", "**/*.vue"]
+metadata:
+  origin: authored
+---
+
+# Next.js / Nuxt testing
+
+Test layout, runner, and mocking conventions for Next.js and Nuxt
+projects. Narrows `core-common-rules`; generic test-writing guidance
+(determinism, one behavior per test) still comes from there.
+
+## Layout and runner
+
+- Co-locate a component/page test next to what it tests
+  (`app/orders/page.test.tsx`, `pages/orders.test.ts` next to
+  `orders.vue`, or a project's existing `__tests__`/`tests` convention —
+  match what the project already does rather than introducing a second
+  layout).
+- Next.js: Jest or Vitest with React Testing Library is standard for
+  component/page tests; a Server Component that only renders server-side
+  (no interactivity) is usually tested by rendering its resolved output or
+  through an integration/e2e test, since RTL's `render()` alone does not
+  execute the App Router's server data-fetching lifecycle.
+- Nuxt: Vitest with `@nuxt/test-utils` (`mountSuspended` for a component
+  that uses auto-imported composables or Nuxt context) or Vue Test Utils
+  directly for a plain, context-free component. Use `@nuxt/test-utils`'s
+  `mountSuspended`/`renderSuspended` when the component under test calls
+  `useFetch`/`useAsyncData`/a Nuxt composable — a plain Vue Test Utils
+  `mount()` has no Nuxt runtime context to resolve those against.
+
+## Mocking the network boundary
+
+- Mock at the network boundary (MSW, or the project's existing HTTP mock
+  layer) for a component/page test that calls `fetch`/`useFetch` — not by
+  mocking the framework's data-fetching hook itself, which tests the mock
+  instead of the component's actual request/response handling.
+- A Server Action or Nuxt server route under test should be called
+  through its real handler with a mocked downstream dependency (database
+  client, external API), not have its entire body replaced by a stub —
+  the goal is proving the handler's own auth/validation logic runs, not
+  just that some function returns the expected shape.
+
+## Determinism and fixtures
+
+- Freeze or inject time (`vi.setSystemTime`, a clock passed as a
+  parameter) for any test touching a component that renders `Date.now()`-
+  or locale-dependent output — the same nondeterminism that causes a
+  hydration mismatch in the app causes a flaky test in CI.
+- Use fixtures/factories for route params, `searchParams`, and Nuxt route
+  objects (`useRoute()` mocked with a realistic shape) instead of
+  hand-built partial objects that happen to satisfy today's test but drift
+  from the real router's shape.
+
+## Coverage expectations
+
+- Cover: the interactive/client boundary (event handlers, form
+  submission, a Server Action's success and validation-failure paths, a
+  Nuxt composable's loading/error/data states), not just the happy-path
+  render.
+- Do not chase coverage on generated framework files (`layout.tsx` that
+  only renders `{children}`, an empty `error.vue`) — spend test budget on
+  logic the project actually wrote.

package/src/gdskills/bundled/stacks/nextjs-nuxt/skills/nextjs-nuxt-build-fix/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: nextjs-nuxt-build-fix
+description: "Use when resolving a Next.js build/type error ('use client'/'use server' boundary violation, a Server Component importing a client-only hook, an invalid Route Handler export) or a Nuxt build/type error (an auto-imported composable/component that fails to resolve, a nuxi typecheck failure, a hydration-mismatch warning) blocking `next build` or `nuxi build`. Applies the smallest root-cause fix and never silences it with ssr: false, suppressHydrationWarning, or a widened tsconfig. Not for generic tsc/ESM module-resolution errors with no meta-framework cause (use nodejs-build-fix), and not for implementing a new feature (use nextjs-nuxt-implementation)."
+triggers:
+  - "fix this use client server component boundary error"
+  - "next build fails with a Server Component importing useState"
+  - "nuxi typecheck fails on this auto-imported composable"
+  - "fix this hydration mismatch warning in Next.js"
+  - "route handler export is invalid in this Next.js app router file"
+  - "nuxt build can't resolve this composable"
+  - "fix this Next.js build error about async component"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Next.js / Nuxt build-fix
+
+Resolve a `next build`/`nuxi build`/`nuxi typecheck` failure caused by a
+meta-framework-specific boundary or resolution error. Applies the
+smallest change that fixes the actual root cause — never a change that
+merely makes the build stop complaining. See `rules/patterns.mdc` for the
+boundary/composable-context rules a correct fix should restore.
+
+## Workflow
+
+### Step 1: Reproduce the failure
+
+```bash
+# Next.js
+npx tsc --noEmit
+npx next build
+
+# Nuxt
+npx nuxi typecheck
+npx nuxi build
+```
+
+Run the project's own `package.json` scripts if they wrap these
+differently. Capture the exact error and file:line before changing
+anything.
+
+### Step 2: Classify the failure
+
+- **Server/Client boundary error** (Next.js): "You're importing a
+  component that needs `useState`/`useEffect`/an event handler. This
+  React hook only works in a Client Component" or similar — a Server
+  Component (no `'use client'`) imports something that needs the client
+  runtime.
+- **Server-only import reaching the client** (Next.js): a build error or
+  warning about a Node-only module (`fs`, `node:crypto`) or a
+  `'use server'`-only import ending up in a client bundle.
+- **Invalid Route Handler shape** (Next.js): `route.ts` exporting
+  something other than the recognized HTTP method functions
+  (`GET`/`POST`/etc.), or missing the required async signature.
+- **Auto-import resolution failure** (Nuxt): `nuxi typecheck`/build
+  cannot resolve a composable/component that should be auto-imported —
+  usually a naming mismatch, wrong directory, or a missing `export`.
+- **Composable-context error** (Nuxt): "must be called within a
+  `setup()`" or similar — a composable was invoked outside the
+  synchronous setup window.
+- **Hydration mismatch warning**: server-rendered HTML text/attributes
+  don't match the client's first render.
+
+### Step 3: Find the root cause
+
+- Boundary error: find which import in the Server Component actually
+  needs the client runtime, and trace whether it belongs in a smaller
+  extracted Client Component, or whether the whole file was mistakenly
+  missing `'use client'`.
+- Auto-import failure: check the file lives in a directory Nuxt actually
+  scans (`composables/`, `components/`, `utils/` by default, or a
+  configured `imports`/`components` dir in `nuxt.config.ts`) and exports
+  what's being imported under the expected name.
+- Hydration mismatch: trace the mismatched text/attribute back to its
+  source — usually `Date.now()`, `Math.random()`, `typeof window`
+  branching, or a locale-dependent format called during render.
+
+### Step 4: Apply the smallest correct fix
+
+- Boundary error: add `'use client'` to the smallest component that
+  actually needs it (extracting it into its own file if it's currently
+  bundled with server-only siblings) — not to the whole page/layout.
+- Server-only import leak: move the server-only code behind its own
+  `'use server'` file or a `server/`-only module, and pass only the
+  derived, safe result down as a prop.
+- Route Handler shape: export the correct named HTTP method function
+  with the framework's expected signature — not a default export or a
+  renamed function.
+- Auto-import failure: fix the file's location/export name/registration
+  — not a hand-added explicit import that routes around Nuxt's
+  convention, unless the project has deliberately disabled auto-imports.
+- Composable-context error: move the call to the synchronous top level
+  of `setup()`/a plugin/middleware — not a workaround that stores the
+  composable's return value in a ref before the async point instead of
+  fixing the call site.
+- Hydration mismatch: make the value deterministic across server and
+  client (compute it once and pass it down, or gate the
+  client-only-varying part behind a mount-effect check) — not
+  `suppressHydrationWarning` or Nuxt's `<ClientOnly>`/`ssr: false` used as
+  a blanket cover for the mismatch.
+
+### Step 5: Verify and report
+
+Re-run the exact command from Step 1; confirm it exits 0 with no new
+warnings. Report the root cause and the fix, not just "build passes now".
+
+## Rules
+
+- Follow `rules/patterns.mdc` for the boundary/composable-context/
+  rendering-mode conventions a fix must restore.
+- ALWAYS fix the root cause with the smallest change confined to the
+  files the failure actually touches.
+- NEVER add `suppressHydrationWarning`, wrap a component in
+  `<ClientOnly>`, or set `ssr: false` on a route as a way to silence a
+  hydration mismatch instead of fixing the nondeterministic render.
+- NEVER move a `'use client'` directive up to a shared layout/ancestor,
+  or hand-import around a broken Nuxt auto-import, just to make the
+  build pass without understanding why resolution failed.
+- NEVER widen `tsconfig.json`'s `strict`/`moduleResolution` or disable a
+  Next.js/Nuxt build check globally to route around one file's error.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add suppressHydrationWarning here, the mismatch is harmless" | Hides the actual nondeterministic render source instead of fixing it; a "harmless" mismatch today can silently grow |
+| "Easiest fix: mark the whole layout 'use client', then the boundary error goes away for sure" | Ships the entire subtree to the client and defeats server rendering for content that never needed it |
+| "This composable won't auto-import, I'll just hand-import it from a relative path to unblock the build" | Routes around the actual misconfiguration (wrong directory, missing export) instead of fixing it, and drifts from the project's own auto-import convention |
+| "I'll set ssr: false on this Nuxt page, that always clears a hydration error" | Turns off server rendering for the route entirely instead of fixing the one nondeterministic value causing the mismatch |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- The exact command that reproduced the failure in Step 1 now exits 0
+  with no new warnings.
+- No `suppressHydrationWarning`, `<ClientOnly>`/`ssr: false` used as a
+  blanket workaround, or widened `tsconfig.json` setting was added.
+- A `'use client'` directive, if added, sits on the smallest component
+  that needs it, not a shared ancestor.
+- The report states the actual root cause (which import/call needed
+  client/setup context, or which directory/export was wrong), not just
+  "fixed the build".

package/src/gdskills/bundled/stacks/nextjs-nuxt/skills/nextjs-nuxt-build-fix/evals.json

@@ -0,0 +1,75 @@
+{
+  "triggers": {
+    "positive": [
+      "This Server Component in my Next.js app imports useState, and the build keeps failing because of it, what's the actual fix?",
+      "Every time this Next.js page renders, the console throws a hydration mismatch error, and I need to actually fix the root cause instead of suppressing it.",
+      "Running nuxi typecheck, I keep getting a failure because it can't resolve this auto-imported composable, how do I fix the build?",
+      "This Next.js route.ts file has an invalid export and won't build",
+      "Fix this nuxt build error about a composable being called outside setup",
+      "My next build is failing because a Server Component in this file imports a browser-only API, what's the correct fix?",
+      "Nuxt build can't find this component even though it's in the components folder"
+    ],
+    "negative": [
+      "Add a new Next.js server action for creating an order",
+      "Review this Next.js server action for missing auth checks",
+      "Write a test for this Nuxt composable",
+      "Migrate this Nuxt 2 project to Nuxt 3",
+      "Fix this Vite build error in a plain Vue component with no Nuxt involved",
+      "Fix this generic tsc module resolution error in a Node script"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "no-suppress-hydration-warning",
+      "prompt": "My Next.js page shows a hydration mismatch warning in the console because it renders new Date().toLocaleTimeString() directly in the component. What's the right fix?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": "suppressHydrationWarning" },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer fixes the actual nondeterminism -- making the time value consistent between server and client (e.g. computing it once and passing it down, or only rendering the time after mount on the client) -- rather than adding suppressHydrationWarning to hide the warning.",
+          "pass_criteria": [
+            "Names a concrete fix for the nondeterminism itself: e.g. only render the live time after the component mounts client-side (using a mounted-state check or an effect), or pass a server-computed timestamp down as a stable prop instead of calling new Date() during render on both sides",
+            "Shows or names the specific code change (the mounted-flag pattern, useEffect setting state after mount, or the prop being passed) rather than only describing the idea in the abstract"
+          ],
+          "fail_criteria": [
+            "Recommends adding suppressHydrationWarning as the fix -- mentioning it only to say it should not be used here is not a failure"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The mismatch happens because new Date().toLocaleTimeString() evaluates once on the server (at render/build time) and again on the client during hydration, producing two different strings for the same node. Don't paper over it with suppressHydrationWarning -- instead make the client-rendered time appear only after mount, so the server and initial client render agree (both render nothing or a static placeholder), and the live value fills in afterward:\n\nconst [time, setTime] = useState<string | null>(null);\nuseEffect(() => { setTime(new Date().toLocaleTimeString()); }, []);\nreturn <span>{time ?? '--:--:--'}</span>;\n\nThis way the server HTML and the client's first render both show the placeholder, hydration matches, and the real time appears right after mount.",
+        "known_wrong": "Easiest fix: add suppressHydrationWarning to the element rendering the time. React will stop complaining about the mismatch and the time still displays correctly on the client, so functionally nothing is lost.",
+        "vague": "You should make the time rendering consistent between server and client instead of just silencing the warning.",
+        "subtle_wrong": "Fix the root cause by moving the Date().toLocaleTimeString() call into a useMemo with an empty dependency array instead of calling new Date() inline in the JSX: const time = useMemo(() => new Date().toLocaleTimeString(), []); return <span>{time}</span>;. Memoizing it means the value is computed exactly once per mount rather than on every render, so the server and client agree on a single stable value."
+      },
+      "anti_patterns": ["suppressHydrationWarning"]
+    },
+    {
+      "id": "narrow-use-client-not-widen",
+      "prompt": "Next.js flags a Server/Client boundary build error because a small icon-button inside my Server Component page uses the useState hook, and that hook needs client-side rendering to run at all. How should I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": "'use client'" },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer adds 'use client' to the small icon-button component itself (extracting it into its own file if needed), not to the parent page/layout, so only the component that actually needs client state gets the directive.",
+          "pass_criteria": [
+            "States that 'use client' should be added to the icon-button component's own file, not the parent page",
+            "Names extracting the icon-button into its own component file if it currently isn't one, so the directive can be scoped to just it"
+          ],
+          "fail_criteria": [
+            "Recommends adding 'use client' to the page or a shared parent/layout component as the fix -- mentioning that as something to avoid is not a failure"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The fix is to add 'use client' to the icon-button component itself, not to the page. If the icon-button isn't already its own file, extract it into one (e.g. IconButton.tsx) and put 'use client' as the first line of that file -- that's the component that actually calls useState, so it's the one that needs the client boundary. Leave the page (page.tsx) with no directive so it stays a Server Component and everything else on the page keeps rendering server-side. Pass any props the icon-button needs down from the page as usual.",
+        "known_wrong": "Just add 'use client' to the top of the page.tsx file that contains it -- that's the fastest way to make the error go away without having to split anything into a new file.",
+        "vague": "Add 'use client' somewhere so the hook works, ideally not too broadly.",
+        "subtle_wrong": "I'd add 'use client' to the layout.tsx that wraps this page, since that's one level up from the page itself and technically not the page file -- that should satisfy the boundary requirement while being less invasive than touching the page directly."
+      },
+      "anti_patterns": []
+    }
+  ]
+}