@node-boost/node-boost 0.1.0

package/resources/react/architectures/testing-strategy/guideline.md

@@ -0,0 +1,33 @@
+# Testing Strategy
+
+Shape: testing trophy. Most value sits in component/integration tests (Testing Library), a handful of e2e flows (Playwright), unit tests for pure logic.
+
+## Test behavior, not implementation
+
+<code-snippet name="Query by role, act like a user" lang="tsx">
+render(<InvoiceForm />)
+await user.type(screen.getByLabelText(/amount/i), "120")
+await user.click(screen.getByRole("button", { name: /save/i }))
+expect(await screen.findByText(/invoice saved/i)).toBeInTheDocument()
+</code-snippet>
+
+- Select by role/label — it survives refactors and enforces accessible markup for free.
+- No assertions on internal state, no shallow rendering, `data-testid` only when no role/label fits.
+
+## Mock the network, not your code
+
+Use MSW: tests run through the real query hooks and data layer, with the API faked at the network boundary (the FE equivalent of `Http::fake()`). Never mock `useInvoices` itself — that tests a stub.
+
+## What to test
+
+- User-visible behavior of features (happy path + validation).
+- **Off-happy-path states**: loading, error, empty — the fallbacks nobody sees until production (pairs with ui-states).
+- Complex hook logic via `renderHook`; pure functions as plain unit tests.
+- Critical journeys (login, checkout) as Playwright e2e — few and stable.
+- Automate a11y checks where cheap: `jest-axe`/axe-core on key screens.
+
+## Anti-patterns
+
+- Chasing 100% coverage; snapshot-testing everything (brittle, diffs unread).
+- Mocking modules the test is supposed to exercise.
+- Next: async Server Components don't render meaningfully in jsdom — cover RSC via e2e/integration and unit-test the extracted data-layer logic instead.

package/resources/react/architectures/testing-strategy/skill/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: testing-strategy
+description: Write component tests with Testing Library and MSW, e2e with Playwright, and unit tests for pure logic — behavior over implementation.
+---
+
+# Testing Strategy
+
+## When to use this skill
+
+Use when adding tests for a feature, fixing a bug (write the failing test first), or reviewing test quality.
+
+## Procedure
+
+1. Default to a component test: render the feature entry, interact via `userEvent`, assert what the user sees (`getByRole`/`getByLabelText`).
+2. Fake the API with MSW handlers per scenario (success, error, empty) — never mock your own hooks or data-layer functions.
+3. Cover the four view states: happy, loading, error, empty.
+4. Pure logic (formatters, reducers, complex hooks) → unit tests / `renderHook`.
+5. Critical user journey changed? Update/add the Playwright e2e for it.
+6. Next RSC: test through e2e or extract the logic into the data layer and unit-test that.

package/resources/react/architectures/typed-contracts/guideline.md

@@ -0,0 +1,31 @@
+# Typed Contracts
+
+TypeScript types do not exist at runtime. Validate external data at the system's boundaries with zod, infer types from schemas, and trust types everywhere inside.
+
+## The boundaries (validate here, and only here)
+
+1. **API responses** — in the data layer: `invoiceListSchema.parse(await res.json())`. Exception: a generated client (orval/openapi-typescript) already carries the contract — do not double-validate.
+2. **User input** — forms (react-hook-form + zod resolver) and every Server Action (validate the payload first; a Server Action is a public endpoint).
+3. **Environment variables** — a single `env.ts` with a schema; crash at startup, not mid-request (`NB-ARCH-008`, warn, flags `process.env.X` elsewhere).
+4. **URL params** — `searchParams` are untrusted input like any query string.
+
+<code-snippet name="Schema as single source of truth" lang="ts">
+export const invoiceSchema = z.object({
+  id: z.string(),
+  amount: z.number(),
+  status: z.enum(["draft", "paid", "void"]),
+})
+export type Invoice = z.infer<typeof invoiceSchema> // type derives from schema — no duplication
+</code-snippet>
+
+## Rules
+
+- Never `as Invoice` on external data — a cast is a promise the runtime never checks. Parse it (`NB-ARCH-007`, warn, flags unvalidated `res.json()`/`JSON.parse` in the data layer).
+- One schema per contract; derive narrower views with `.pick()`/`.omit()` instead of re-declaring.
+- Form UX: validate on blur for fields, on submit for the whole form; reserve layout space for the error message so the layout does not jump.
+
+## Anti-patterns
+
+- **Zod fatigue**: re-parsing the same data in every component. Validate at the boundary; inside the app the type is the truth.
+- Hand-written interfaces duplicating a schema (they drift apart silently).
+- Mind the zod major in this project — zod 4 changed APIs (`z.email()` top-level, reworked error customization); follow the versioned zod guideline.

package/resources/react/architectures/typed-contracts/skill/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: typed-contracts
+description: Validate external data with zod at system boundaries (API, forms, env, URL) and derive TypeScript types from schemas.
+---
+
+# Typed Contracts
+
+## When to use this skill
+
+Use when consuming an API response, handling form input, adding an env variable, reading searchParams, or fixing `NB-ARCH-007`/`NB-ARCH-008`.
+
+## Procedure
+
+1. Define/extend the zod schema next to the data layer (`features/<x>/api/schemas.ts`); export `type X = z.infer<typeof xSchema>`.
+2. API boundary: `.parse()` (throw) or `.safeParse()` (handle) in the data-layer function. Skip when the client is generated from OpenAPI.
+3. Forms: zod resolver + validate the same schema at the start of the Server Action / mutation.
+4. Env: add the variable to `env.ts` schema; import `env` from there, never `process.env.X` inline.
+5. Never cast external data with `as` — if the shape is unknown, parse it.
+
+## Fixing findings
+
+- `NB-ARCH-007`: wrap the raw `res.json()`/`JSON.parse` result in `schema.parse(...)`.
+- `NB-ARCH-008`: move the `process.env.X` read into `env.ts` and import the validated value.

package/resources/react/architectures/ui-states/guideline.md

@@ -0,0 +1,45 @@
+# UI States
+
+Every data view has four states, not one. Design loading, error and empty explicitly — apps spend ~30% of their time off the happy path, and generated code habitually builds only the happy branch.
+
+<code-snippet name="The four-state contract" lang="tsx">
+function InvoiceList() {
+  const { data, isLoading, isError, refetch } = useInvoices()
+
+  if (isLoading) return <InvoiceListSkeleton />
+  if (isError) return <ErrorState onRetry={refetch} />
+  if (!data.length) return (
+    <EmptyState
+      title="No invoices yet"
+      description="Create your first invoice to get started."
+      action={<CreateInvoiceButton />}
+    />
+  )
+  return <InvoiceTable invoices={data} />
+}
+</code-snippet>
+
+## Empty states are a feature
+
+- Explain **why** it's empty + give the next step (CTA). A blank screen after onboarding is the user's first impression.
+- Distinguish "no data yet" (onboarding CTA) from "filters matched nothing" (show the filters + a clear-filters action — no rocket illustrations).
+
+## Loading: skeletons, not spinners
+
+Skeletons mirror the coming content's shape (no layout shift). One skeleton per meaningful region — five racing spinners are worse than one calm block. In Next, `loading.tsx` is the page-level skeleton (see error-loading-boundaries); in SPAs, per-view skeleton components.
+
+## Optimistic UI (React 19)
+
+For high-confidence mutations (toggle, like, add-to-list) use `useOptimistic` — instant UI, automatic rollback on error. Forms: `useActionState` handles pending/error without hand-rolled `isSubmitting`/`setError` flags. Do **not** use optimistic updates for payments or irreversible operations.
+
+<code-snippet name="Optimistic toggle" lang="tsx">
+const [optimisticDone, setOptimisticDone] = useOptimistic(todo.done)
+async function toggle() {
+  setOptimisticDone(!optimisticDone)   // instant
+  await toggleTodoAction(todo.id)      // rollback happens automatically on error
+}
+</code-snippet>
+
+## Consistency
+
+`EmptyState`/`ErrorState` are shared slot-based components in `components/ui/` — not ad-hoc divs per feature. Test all four states (testing-strategy).

package/resources/react/architectures/ui-states/skill/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: ui-states
+description: Build the full four-state contract (loading, error, empty, happy) for data views, with skeletons, designed empty states and React 19 optimistic updates.
+---
+
+# UI States
+
+## When to use this skill
+
+Use when building any view that renders remote data, or when adding a mutation with user-visible feedback.
+
+## Procedure
+
+1. Scaffold all four branches up front: loading (skeleton mirroring content), error (message + retry), empty (why + CTA), happy.
+2. Empty state: decide which case it is — no data yet (onboarding CTA) vs. no results for filters (keep filters visible, offer clear).
+3. Use shared `EmptyState`/`ErrorState` from `components/ui/`; extend them with slots rather than forking per feature.
+4. Mutations: high-confidence, reversible → `useOptimistic`; forms → `useActionState` for pending/error; payments/irreversible → explicit pending state, no optimism.
+5. Next App Router: page-level loading/error live in `loading.tsx`/`error.tsx`; this skill covers the *content* of those fallbacks.
+6. Add tests for the loading/error/empty branches (MSW scenarios), not just the happy path.

package/resources/react/guidelines/core.md

@@ -0,0 +1,15 @@
+# Node Boost Core
+
+Baseline for AI-assisted work in this repository. Guidelines in `.ai/guidelines/` are composed from the packages actually installed — trust them over training-data habits, which are often a major version stale.
+
+## Working rules
+
+- Match the project's detected stack and versions (see the `application_info` MCP tool) before writing code; version-specific guidelines override generic knowledge.
+- Follow the enabled architecture guidelines (indexed in `node-boost.md`); the `audit`/`guard` commands enforce their rules (`NB-ARCH-xxx`). Use `explain <ID>` when a finding is unclear.
+- Suppressing a finding requires a reason: `// nb-disable NB-ARCH-xxx -- <why>`. Unreasoned suppressions are flagged.
+- After completing changes, run `node-boost audit --changed` (or rely on the installed Stop hook) and fix findings before handing back.
+
+## Repository hygiene
+
+- Do not leave dead code: unused exports, files and dependencies are context noise for both humans and agents. `knip` finds them — prefer removing over commenting out.
+- Keep `node-boost.json` and generated `.ai/**` files committed; regenerate with `node-boost update` after dependency upgrades (`doctor` detects drift).

package/resources/react/guidelines/next/15.md

@@ -0,0 +1,9 @@
+# Next.js 15
+
+This project runs Next 15 — caching defaults changed versus 13/14. Do not generate stale idioms.
+
+- `fetch` is **no longer cached by default**; opt in explicitly with `{ cache: "force-cache" }` or route segment config. GET route handlers and the client router cache are also uncached by default.
+- `params` and `searchParams` in pages/layouts are **async** — `await` them (sync access is deprecated).
+- `"use cache"` / cache components exist behind the experimental flag only — use the stable primitives (`fetch` options, `revalidateTag`, `unstable_cache`) unless the project has the flag enabled.
+- React 19 is the baseline; Server Actions and form Actions are stable — use them for mutations with auth + validation.
+- Partial Prerendering is experimental in 15 — structure pages with `<Suspense>` boundaries anyway (it pays off in streaming today and PPR later).

package/resources/react/guidelines/next/16.md

@@ -0,0 +1,18 @@
+# Next.js 16
+
+This project runs Next 16 — its caching model is **explicit**. Do not generate Next 13/14-era idioms.
+
+- Nothing is cached by default: pages are dynamic; opt in with the `"use cache"` directive at the function/component level, as close to the data as possible (usually in the data layer).
+- Control lifetimes with `cacheLife()` profiles; invalidate with `revalidateTag()`/`updateTag()` from Server Actions.
+- Partial Prerendering is the default model with cache components enabled: static shell + dynamic holes defined by `<Suspense>` boundaries — structure pages accordingly (see error-loading-boundaries).
+- `params` and `searchParams` in pages/layouts are **async** — `await` them.
+- Do NOT write: `fetch(..., { next: { revalidate } })` as the primary caching tool, `export const revalidate`, or `unstable_cache` — these are legacy patterns superseded by `"use cache"`.
+- Turbopack is the default bundler; do not add webpack-specific config unless the project already has it.
+
+<code-snippet name="Explicit caching in the data layer" lang="ts">
+export async function getInvoices() {
+  "use cache"
+  cacheLife("minutes")
+  return invoiceListSchema.parse(await apiClient.get("/invoices"))
+}
+</code-snippet>

package/resources/react/guidelines/next/core.md

@@ -0,0 +1,8 @@
+# Next.js Core
+
+- App Router conventions: routes are folders; `page.tsx` renders, `layout.tsx` wraps, `route.ts` handles HTTP, `loading.tsx`/`error.tsx` are boundaries. Do not mix in Pages Router idioms (`getServerSideProps`, `getStaticProps`, `_app.tsx`) unless the project actually uses `pages/`.
+- Components are Server Components by default; `"use client"` only on interactive leaves (see server-first-components guideline).
+- Data flows through the data layer; mutations through Server Actions with auth + validation (see data-access-layer and secure-by-default).
+- Use the framework's primitives before reaching for libraries: `next/image` for images, `next/font` for fonts, `next/link` for navigation, Metadata API for `<head>`.
+- Route params and `searchParams` are untrusted input — validate before use.
+- Prefer `redirect()`/`notFound()` from the server over client-side workarounds.

package/resources/react/guidelines/react/18.md

@@ -0,0 +1,8 @@
+# React 18
+
+This project runs React 18 — React 19 APIs are NOT available. Do not generate them.
+
+- No `use()`, no `useActionState`/`useFormStatus`/`useOptimistic`, no form `action={fn}` prop, no ref-as-prop (use `forwardRef` here).
+- No React Compiler by default: memoize hot paths deliberately with `useMemo`/`useCallback`/`React.memo` — but only where profiling or obvious render pressure justifies it.
+- Concurrent features available: `useTransition`/`startTransition` for non-urgent updates, `useDeferredValue` for expensive derived UI, `<Suspense>` for code-splitting and data libraries that support it.
+- Optimistic UI is hand-rolled here: local state + rollback in the mutation's error handler (react-query's `onMutate`/`onError` pattern).

package/resources/react/guidelines/react/19.md

@@ -0,0 +1,10 @@
+# React 19
+
+This project runs React 19 — several long-standing idioms are dead. Do not generate them.
+
+- `ref` is a regular prop: **no `forwardRef`**. `function Input({ ref, ...props })` just works.
+- React Compiler (1.0, stable) memoizes automatically: **no ritual `useCallback`/`useMemo`/`React.memo`** — use them only for referential guarantees (e.g. effect deps).
+- Actions are the mutation primitive: `<form action={fn}>`, `useActionState` for pending/error, `useFormStatus` inside forms, `useOptimistic` for instant feedback (see ui-states guideline).
+- `use(promise)` unwraps promises in render (with Suspense); `use(Context)` replaces `useContext` and may be called conditionally.
+- Metadata tags (`<title>`, `<meta>`) render from components and hoist automatically (in non-Next apps).
+- `propTypes` and `defaultProps` on function components are removed — TypeScript types and default parameters instead.

package/resources/react/guidelines/react/core.md

@@ -0,0 +1,9 @@
+# React Core
+
+- Components are pure functions of props/state — side effects live in event handlers, the data layer, or (rarely) effects that sync with external systems.
+- Compute derived data during render; do not mirror props into state or chain `useEffect` + `setState` (see custom-hooks guideline).
+- Lists need stable `key`s from the data, never array indexes for dynamic lists.
+- Prefer composition (children/slots) over configuration props (see component-composition guideline).
+- Keep state close to where it is used; escalate deliberately (see state-management guideline).
+- Semantic HTML first: `<button>`, `<a>`, `<label>` — not clickable `<div>`s.
+- Follow the version-specific React guideline in this directory — React idioms shift across majors and training data lags behind.

package/resources/react/guidelines/react-query/core.md

@@ -0,0 +1,8 @@
+# TanStack Query Core
+
+- react-query owns server state — it is a cache, not a store. Never copy query results into zustand/Context (see state-management guideline).
+- Components consume query hooks from the feature (`useInvoices()`), never `useQuery` inline with a raw fetch (see data-access-layer guideline).
+- Query keys are structured and centralized per feature: `["invoices", filter]` — keys are the cache identity, treat them as an API.
+- Mutations invalidate what they change: `useMutation` + `queryClient.invalidateQueries({ queryKey: ["invoices"] })` on success; optimistic updates via `onMutate`/`onError` rollback where UX warrants it.
+- Handle all result states in the UI: `isLoading`, `isError`, empty data (see ui-states guideline).
+- Configure sensible `staleTime` per data class instead of refetching everything on every focus.

package/resources/react/guidelines/react-router/7.md

@@ -0,0 +1,9 @@
+# React Router 7
+
+This project runs React Router 7 — the merged react-router package. Do not generate v5/v6-era imports or idioms.
+
+- Import from `react-router` (v7 merged `react-router-dom` into it; check which import style this project uses and stay consistent).
+- v7 spans modes: library mode (manual `<Routes>`/`createBrowserRouter`) and framework mode (file conventions, loaders/actions). **Match the project's existing mode** — do not introduce loaders/actions into a library-mode SPA that fetches via react-query.
+- In library mode with react-query (typical here): data fetching stays in query hooks; the router only maps URLs to screens.
+- Use `createBrowserRouter`/route objects over JSX route trees for new route configuration; type route params where the setup provides typegen.
+- No `<Switch>`, no `useHistory` (v5 relics) — `<Routes>`, `useNavigate`, `useSearchParams`.

package/resources/react/guidelines/react-router/core.md

@@ -0,0 +1,7 @@
+# React Router Core
+
+- Routes are configuration, not scattered strings: keep the route tree in one module (`src/routers.tsx` / `src/routes/`), and reference paths via constants or typed helpers — no hardcoded `"/invoices/" + id` concatenation in components.
+- URL is state: filters, pagination, tabs and other shareable view state belong in `searchParams`, not in a store (see state-management guideline).
+- Navigation through `<Link>`/`<NavLink>`/`useNavigate` — never `window.location` for internal routes.
+- Route params are untrusted input: validate/parse before use (see typed-contracts guideline).
+- Lazy-load route-level components for code splitting; pair each lazy route with a skeleton fallback (see ui-states guideline).

package/resources/react/guidelines/tailwindcss/3.md

@@ -0,0 +1,8 @@
+# Tailwind CSS 3
+
+This project runs Tailwind 3 — JS-config era. Do not generate v4 idioms.
+
+- Configuration lives in `tailwind.config.js` (`theme.extend`, `plugins`); CSS entry uses `@tailwind base; @tailwind components; @tailwind utilities;` — NOT `@import "tailwindcss"` or `@theme` (those are v4).
+- Maintain the `content` globs — a file missing from `content` means its classes are purged from the build.
+- Design tokens go in `theme.extend`; reference with utilities, or `theme()` in CSS.
+- PostCSS pipeline needs `tailwindcss` + `autoprefixer`.

package/resources/react/guidelines/tailwindcss/4.md

@@ -0,0 +1,9 @@
+# Tailwind CSS 4
+
+This project runs Tailwind 4 — configuration is CSS-first. Do not generate v3 idioms.
+
+- **No `tailwind.config.js`.** Configuration lives in CSS: `@import "tailwindcss"` plus `@theme { --color-brand: ...; }` for tokens. Do not create a JS config file.
+- Theme tokens are CSS variables, usable directly (`var(--color-brand)`) and generating utilities automatically.
+- No `content` array to maintain — sources are auto-detected; no PostCSS `autoprefixer`/`postcss-import` boilerplate (built in via `@tailwindcss/postcss` or the Vite plugin).
+- v3 → v4 renames to respect: `shadow-sm` → `shadow-xs`, `outline-none` → `outline-hidden`, ring default width changed — check migrated class names rather than assuming v3 scales.
+- Custom utilities via `@utility`, plugins via `@plugin` — in CSS, not JS.

package/resources/react/guidelines/tailwindcss/core.md

@@ -0,0 +1,8 @@
+# Tailwind CSS Core
+
+- Utility-first in JSX; reuse through React components, not through custom CSS classes. Keep `@apply` to a rare minimum.
+- Never construct class names dynamically (`text-${color}-500`) — the compiler scans sources statically; interpolated classes silently don't exist. Map conditions to full literal class strings.
+- Use theme tokens for colors/spacing; arbitrary values (`w-[347px]`) are one-off exceptions with a reason.
+- Visual variants via `cva` + `tailwind-merge`; conditional classes via a `cn()` helper (see styling-tailwind guideline).
+- Keep class order consistent with the project's formatter (prettier-plugin-tailwindcss or Biome's sorting).
+- Follow the version-specific Tailwind guideline — configuration differs fundamentally between v3 and v4.

package/resources/react/guidelines/testing/playwright.md

@@ -0,0 +1,8 @@
+# Playwright
+
+- Reserve e2e for critical user journeys (login, checkout, core flows) — few, stable, high-value; everything else belongs in component tests.
+- Select by role/label (`getByRole`, `getByLabel`) — same philosophy as Testing Library; avoid CSS/XPath selectors.
+- Rely on web-first assertions (`await expect(locator).toBeVisible()`) — no manual `waitForTimeout` sleeps.
+- Isolate state per test (fresh context/storage); seed data through APIs or fixtures, not through UI click-chains.
+- Stub third-party/external services with `page.route()`; your own backend runs real in e2e when feasible.
+- Use the accessibility snapshot/axe integration on key pages when cheap.

package/resources/react/guidelines/testing/vitest.md

@@ -0,0 +1,8 @@
+# Vitest
+
+- Runner for unit and component tests; component tests use Testing Library + `@testing-library/jest-dom` matchers in a jsdom (or browser-mode) environment.
+- Test behavior through roles/labels; mock the network with MSW, never your own hooks/modules under test (see testing-strategy guideline).
+- Structure: `describe` per unit/feature, test names state observable behavior ("shows validation error when amount is empty").
+- Use `vi.fn()`/`vi.spyOn` for collaborator seams; avoid `vi.mock` of internal modules — it usually signals a missing seam.
+- Keep tests deterministic: fake timers for time-dependent logic (`vi.useFakeTimers`), no real network, no ordering dependence.
+- Run a focused file with `vitest run <path>`; the full gate is the project's `npm test`.

package/resources/react/guidelines/typescript/core.md

@@ -0,0 +1,7 @@
+# TypeScript Core
+
+- `strict: true` is the floor; treat compiler errors as design feedback, not noise to cast away.
+- No `any` and no `as` on external data — `unknown` + narrowing, or a zod parse at the boundary (see typed-contracts and modern-typescript guidelines).
+- Model closed sets as discriminated unions or const objects (never `enum`); make switches exhaustive with a `never` check.
+- Derive types instead of duplicating them: `z.infer`, `ReturnType`, `Pick`/`Omit`, `satisfies` for literal checking.
+- Types live next to their domain (feature's `types.ts`); shared primitives (branded IDs) in `lib/`.

package/resources/react/guidelines/vite/core.md

@@ -0,0 +1,8 @@
+# Vite Core
+
+- This is a client-rendered SPA: every component is client code, all secrets stay on the backend — the browser bundle is public.
+- Env variables: only `VITE_`-prefixed values reach the client (`import.meta.env.VITE_X`) — and they are readable by every visitor. Never prefix secrets; validate env in one `env.ts` (see typed-contracts and secure-by-default guidelines).
+- Use `import.meta.env` (`DEV`, `PROD`, `MODE`) — not `process.env` in app code.
+- Code-split at route level with dynamic `import()`; heavy rarely-used components load lazily with a skeleton fallback.
+- Static assets through imports (hashed URLs) or `public/` for verbatim files; prefer imports.
+- Config in `vite.config.ts` stays lean — resolve aliases (`@/` → `src/`) should match `tsconfig.json` paths.

package/resources/react/guidelines/zod/3.md

@@ -0,0 +1,8 @@
+# Zod 3
+
+This project runs zod 3 — do not use zod 4 APIs.
+
+- String formats chain off strings: `z.string().email()`, `z.string().uuid()` — top-level `z.email()` does NOT exist here.
+- Error customization uses `message` / `required_error` / `invalid_type_error` params and `errorMap` — the v4 unified `error` param does not exist.
+- Strict/passthrough objects via `.strict()` / `.passthrough()` on `z.object`.
+- `z.record(valueSchema)` accepts a single argument (string keys implied).

package/resources/react/guidelines/zod/4.md

@@ -0,0 +1,10 @@
+# Zod 4
+
+This project runs zod 4 — several v3 idioms are gone or renamed. Do not generate v3 API.
+
+- String formats are top-level: `z.email()`, `z.url()`, `z.uuid()` — NOT `z.string().email()` (deprecated/removed in v4).
+- Error customization is unified under `error`: `z.string({ error: "Required" })`, `.min(5, { error: "Too short" })` — NOT `message`, `required_error`, `invalid_type_error`, or `errorMap`.
+- `z.strictObject({...})`/`z.looseObject({...})` replace `.strict()`/`.passthrough()` styles; default objects strip unknown keys.
+- Discriminated unions and recursive types are stronger — prefer `z.discriminatedUnion` for tagged payloads.
+- Need a slim client bundle? `zod/mini` exists (functional API) — only introduce it if the project already uses it.
+- Records: `z.record(z.string(), valueSchema)` requires the key schema explicitly.

package/resources/react/guidelines/zod/core.md

@@ -0,0 +1,7 @@
+# Zod Core
+
+- Validate at system boundaries only: API responses (data layer), form/action input, env, URL params. Inside the app, the inferred type is the truth — no re-parsing (see typed-contracts guideline).
+- One schema per contract, types derived with `z.infer`; narrower views via `.pick()`/`.omit()`/`.extend()`, not re-declared interfaces.
+- `.parse()` when failure is a bug (throw), `.safeParse()` when failure is a flow (form input, external data you degrade gracefully on).
+- Keep schemas next to the data layer that uses them (`features/<x>/api/schemas.ts`).
+- Follow the version-specific zod guideline — the v3 → v4 API changed materially.

package/resources/react/guidelines/zustand/core.md

@@ -0,0 +1,8 @@
+# Zustand Core
+
+- The store holds **client-owned** state only: UI preferences, drafts, selections. Server data lives in react-query — writing fetched results into the store creates a second source of truth (flagged by `NB-ARCH-009`).
+- Small, focused stores per concern beat one global store; colocate a feature's store inside the feature.
+- Select narrowly: `useStore((s) => s.sidebarOpen)` — subscribing to the whole store re-renders on every change.
+- Actions live inside the store definition (`set`/`get`), components call them — no external mutation of store state.
+- Persist only what genuinely survives sessions (`persist` middleware) and version the storage schema.
+- Before adding to the store, walk the ladder: `useState` → URL → Context → store (see state-management guideline).

package/resources/react/skills/next-development/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: next-development
+description: Build Next.js App Router features end-to-end — server-first pages, data layer, Server Actions, boundaries — per this project's version and conventions.
+---
+
+# Next Development
+
+## When to use this skill
+
+Use when adding or changing pages, layouts, route handlers, Server Actions, or data flow in this Next.js app.
+
+## Procedure
+
+1. Check the Next major (`application_info`) and follow the versioned guideline — caching semantics differ between 15 and 16.
+2. New route: folder in `app/`, async server `page.tsx`, data via the feature's `api/` functions; add `loading.tsx`/`error.tsx` when the page fetches (error-loading-boundaries skill).
+3. Interactivity goes into `"use client"` leaf components inside the feature (server-first-components skill).
+4. Mutations: Server Action with auth check + zod validation, then cache invalidation (`revalidateTag`/`updateTag` per version).
+5. Use framework primitives: `next/image`, `next/font`, `next/link`, Metadata API.
+6. Before handing back: `node-boost audit --changed` and fix findings.

package/resources/react/skills/react-development/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: react-development
+description: Write React components and hooks following this project's composition, state and hooks conventions.
+---
+
+# React Development
+
+## When to use this skill
+
+Use when creating or refactoring components, hooks, or client-side state.
+
+## Procedure
+
+1. Check the React major (`application_info`) and follow the versioned guideline — 18 vs 19 idioms differ (ref-as-prop, Actions, compiler memoization).
+2. New component: start from composition (children/slots), semantic HTML, props for variants only (component-composition skill).
+3. State: classify first — server data → query hooks; URL-worthy → searchParams; local → `useState`; shared client → Context/store (state-management skill).
+4. Logic outgrowing the JSX → extract a custom hook in the feature (custom-hooks skill); avoid needless `useEffect` and ritual memoization.
+5. Cover the four UI states (ui-states skill) and add behavior tests (testing-frontend skill).

package/resources/react/skills/spa-routing/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: spa-routing
+description: Add screens and navigation in this Vite + React Router SPA — central route config, URL-first state, lazy routes.
+---
+
+# SPA Routing
+
+## When to use this skill
+
+Use when adding a screen, changing navigation, or wiring view state to the URL.
+
+## Procedure
+
+1. Add the route in the central route config (`src/routers.tsx`/`src/routes/`) — never scatter path strings through components; use route constants/helpers.
+2. Lazy-load the route component (`import()`), pair with a skeleton fallback.
+3. Shareable view state (filters, page, tab) → `useSearchParams`, validated before use; do not mirror it into a store.
+4. Navigate with `<Link>`/`useNavigate`; internal redirects never touch `window.location`.
+5. The screen composes feature components (feature-modules skill); data arrives via query hooks (data-access-layer skill).

package/resources/react/skills/tailwindcss-development/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: tailwindcss-development
+description: Style with Tailwind matching this project's major version — tokens, cva variants, no dynamic class names.
+---
+
+# Tailwind CSS Development
+
+## When to use this skill
+
+Use when styling components or touching Tailwind configuration.
+
+## Procedure
+
+1. Check the Tailwind major first: v4 = CSS-first config (`@theme`, no `tailwind.config.js`); v3 = JS config + `content` globs. Follow the versioned guideline.
+2. Use theme tokens; introduce new tokens in the theme, not arbitrary values.
+3. Variants with `cva` + `tailwind-merge`; conditionals through `cn()` — never interpolate class fragments (`text-${x}-500` doesn't exist in the build).
+4. Repeated class strings → extract a `components/ui/` component instead of `@apply`.

package/resources/react/skills/testing-frontend/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: testing-frontend
+description: Test features with Testing Library + MSW (Vitest) and critical journeys with Playwright — behavior over implementation.
+---
+
+# Frontend Testing
+
+## When to use this skill
+
+Use when writing or fixing tests for components, hooks, or user flows.
+
+## Procedure
+
+1. Default to a component test: render the feature entry, drive it with `userEvent`, assert via `getByRole`/`getByLabelText`.
+2. Fake the network with MSW per scenario (success/error/empty); never mock the project's own hooks or data layer.
+3. Cover the four view states, not just the happy path.
+4. Pure logic → unit test; complex hooks → `renderHook`; critical journeys → Playwright (own guideline).
+5. Bug fix? Write the failing test first, then fix.