@node-boost/node-boost 0.1.0

package/resources/react/architectures/custom-hooks/guideline.md

@@ -0,0 +1,38 @@
+# Custom Hooks
+
+Extract stateful logic into `useX` hooks so components stay declarative — thin controllers over a view.
+
+## When to extract
+
+- The logic is used in two or more places, OR
+- the component is unreadable (JSX buried under state/effects), OR
+- the logic deserves its own test.
+
+When none apply, don't: a hook wrapping a single `useState` is ceremony.
+
+<code-snippet name="Thin component, logic in a hook" lang="tsx">
+function InvoiceList() {
+  const { invoices, filter, setFilter, selected, toggleSelection } = useInvoiceSelection()
+  return <Table rows={invoices} filter={filter} onFilter={setFilter} onToggle={toggleSelection} />
+}
+</code-snippet>
+
+## Conventions
+
+- A hook belongs to its feature (`features/<x>/hooks/`); generic ones go to `src/hooks/`.
+- Return an object of named fields when returning more than two values — not a tuple.
+- `useX` only if it calls other hooks. Stateless logic is a plain function in `lib/` — naming it `useX` is a lie.
+
+## React Compiler era (1.0 is stable)
+
+Do **not** wrap everything in `useCallback`/`useMemo` "for performance" — the compiler memoizes automatically. Reach for them only when you need a referential guarantee (e.g. a value in a `useEffect` dependency array). Ritual memoization is legacy noise; do not generate it.
+
+## Effects are a last resort
+
+Before writing `useEffect`, check (per react.dev "You Might Not Need an Effect"):
+
+- Derived state? Compute it during render.
+- Reaction to a user event? Handle it in the event handler.
+- Data fetching? That belongs to the data layer / query hooks, not a hand-rolled effect.
+
+Legitimate effects synchronize with external systems (subscriptions, DOM APIs, analytics) — little else.

package/resources/react/architectures/custom-hooks/skill/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: custom-hooks
+description: Extract component logic into custom hooks with clean APIs, avoid ritual memoization and unnecessary effects.
+---
+
+# Custom Hooks
+
+## When to use this skill
+
+Use when a component's logic outgrows its JSX, when duplicating stateful logic, or when reviewing `useEffect`/`useCallback` usage.
+
+## Procedure
+
+1. Identify the cohesive slice of state + handlers; move it to `features/<x>/hooks/use-<name>.ts`.
+2. Return an object of named fields; keep the component consuming it declarative.
+3. Compose from existing hooks (query hooks, other custom hooks) instead of duplicating.
+4. Audit every `useEffect` you are about to write: derived state → compute in render; event reaction → handler; fetching → data layer. Keep effects only for external-system sync.
+5. Skip `useCallback`/`useMemo` unless a referential guarantee is required — React Compiler handles memoization.
+
+## Testing
+
+Complex hook logic gets a `renderHook` test; simple glue is covered by the component's tests.

package/resources/react/architectures/data-access-layer/guideline.md

@@ -0,0 +1,43 @@
+# Data Access Layer
+
+Components never call `fetch` directly. All data access lives in a dedicated layer: server functions in `api/` directories and client-side query hooks.
+
+## Server side (Next)
+
+<code-snippet name="Data layer function" lang="ts">
+// features/invoices/api/get-invoices.ts
+import "server-only"
+
+export async function getInvoices(filter: InvoiceFilter) {
+  "use cache"
+  const res = await apiClient.get("/invoices", { query: filter })
+  return invoiceListSchema.parse(res) // validate at the boundary (typed-contracts)
+}
+</code-snippet>
+
+Server Components call `getInvoices()`, not `fetch`. Auth headers, error handling, retries and cache tags live in one place. Mutations go through Server Actions (`"use server"`) that validate input and call the data layer.
+
+## Client side
+
+Components consume query hooks, never raw fetch:
+
+<code-snippet name="Query hook" lang="ts">
+// features/invoices/hooks/use-invoices.ts
+export function useInvoices(filter: InvoiceFilter) {
+  return useQuery({ queryKey: ["invoices", filter], queryFn: () => invoicesApi.list(filter) })
+}
+</code-snippet>
+
+Generated API clients (orval, openapi-typescript) **are** the data layer — use them instead of hand-writing one.
+
+## Rules
+
+- `NB-ARCH-005` (error): `fetch`/axios/ky in a client component outside the data layer and outside query hooks.
+- `NB-ARCH-006` (warn): raw `fetch` in a Server Component outside the data layer. Fetching directly in RSC is the framework idiom, but a layer keeps caching, headers and validation consistent — prefer it.
+- The layer's location is configurable via `audit.ruleOptions` (`dataLayerGlobs`, default `**/api/**`, `**/server/**`, `lib/api/**`, `route.ts`).
+
+## Anti-patterns
+
+- `useEffect` + `useState` + `fetch` in a component — that is a hand-rolled, worse react-query.
+- Copy-pasting auth headers per call site.
+- Mutations bypassing Server Actions / the API client, losing validation and cache invalidation.

package/resources/react/architectures/data-access-layer/skill/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: data-access-layer
+description: Add or modify data fetching and mutations through the data layer — server api/ functions, query hooks, and Server Actions — instead of inline fetch.
+---
+
+# Data Access Layer
+
+## When to use this skill
+
+Use whenever code needs to read or write remote data, or when fixing `NB-ARCH-005`/`NB-ARCH-006` findings.
+
+## Reading data
+
+1. Server (Next): add a function in the feature's `api/` directory: `import "server-only"`, call the shared client, validate the response with the schema, add `"use cache"` when cacheable. Call it from the Server Component.
+2. Client: add/extend a query hook (`useQuery`) in the feature's `hooks/`, delegating to the API client. Components call the hook.
+3. Project has a generated client (orval/openapi-typescript)? Use it — do not hand-write parallel fetchers.
+
+## Writing data
+
+1. Next: Server Action (`"use server"`) that validates input (zod) and calls the data layer; invalidate affected cache tags/queries.
+2. SPA: `useMutation` delegating to the API client, with `invalidateQueries` on success.
+
+## Fixing findings
+
+- `NB-ARCH-005`: move the call into a query hook or `api/` function; the component receives data via props/hook.
+- `NB-ARCH-006`: wrap the raw RSC fetch in a data-layer function (adds validation + caching in one place).

package/resources/react/architectures/error-loading-boundaries/guideline.md

@@ -0,0 +1,36 @@
+# Error and Loading Boundaries
+
+Every App Router segment that fetches data needs designed boundaries: `loading.tsx` streams an instant skeleton, `error.tsx` scopes failures to the segment.
+
+<code-snippet name="Segment with boundaries" lang="text">
+app/
+├── error.tsx            # root boundary — the global handler
+└── invoices/
+    ├── page.tsx         # async, awaits data
+    ├── loading.tsx      # streamed IMMEDIATELY while page awaits
+    └── error.tsx        # failure renders here, rest of the app lives
+</code-snippet>
+
+## Rules
+
+- `NB-ARCH-010` (warn): a segment whose `page.tsx` fetches data with no `loading.*` **and** no `error.*` anywhere up its branch. A root-level `error.tsx` satisfies the whole tree — this is not a mandate for twenty files.
+- `error.tsx` **must be a Client Component**; it receives `error` and `reset()` for retry. Add `global-error.tsx` for failures in the root layout, `not-found.tsx` for 404 semantics.
+- `loading.tsx` is an automatic Suspense boundary around the page. For slow islands inside a fast page, wrap the island alone:
+
+<code-snippet name="Granular Suspense" lang="tsx">
+<Suspense fallback={<ChartSkeleton />}>
+  <RevenueChart /> {/* slow await only here; rest streams instantly */}
+</Suspense>
+</code-snippet>
+
+## Why this is structural in Next 16
+
+Partial Prerendering splits the page into a static shell plus dynamic holes — and the holes are defined by Suspense boundaries. No boundaries, no PPR.
+
+## Judgment calls
+
+- Skeletons mirror the shape of the coming content (anti-layout-shift); a page rendered fully from cache may not need one.
+- Skeleton fatigue is real: one skeleton per meaningful region, not five spinners racing.
+- Boundary reset drops the subtree's state — fine, but know it.
+
+Design of the fallback *content* (empty/error UX) lives in the ui-states guideline.

package/resources/react/architectures/error-loading-boundaries/skill/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: error-loading-boundaries
+description: Add loading.tsx / error.tsx / Suspense boundaries to App Router segments that fetch data.
+---
+
+# Error and Loading Boundaries
+
+## When to use this skill
+
+Use when creating a data-fetching page/segment in the App Router, or fixing `NB-ARCH-010`.
+
+## Procedure
+
+1. New segment fetching data → add `loading.tsx` (skeleton mirroring the content shape) and decide the `error.tsx` level: segment-local when the segment can fail independently, otherwise rely on a parent boundary.
+2. `error.tsx`: mark `"use client"`, render a short explanation + retry button calling `reset()`; report the error to monitoring if the project has it.
+3. Slow widget inside a fast page → wrap only that widget in `<Suspense fallback={<Skeleton />}>` instead of blocking the page.
+4. 404 semantics → `not-found.tsx` + `notFound()` from the data layer.
+5. Do not add skeletons to fully cached/static pages — verify the page is actually dynamic first.

package/resources/react/architectures/feature-modules/guideline.md

@@ -0,0 +1,34 @@
+# Feature Modules
+
+Organize code by feature, not by file type. Each feature is a self-contained module with a public API.
+
+## Structure
+
+<code-snippet name="Feature-first layout" lang="text">
+src/
+├── features/
+│   └── invoices/
+│       ├── api/          # data access for this feature (see data-access-layer)
+│       ├── components/
+│       ├── hooks/
+│       ├── types.ts
+│       └── index.ts      # PUBLIC API — the only entry point for other code
+├── components/ui/        # shared, domain-agnostic UI kit
+├── lib/                  # shared utilities, api client
+└── app/                  # routes — compose features, contain no business logic
+</code-snippet>
+
+## Rules
+
+- Dependency direction is one-way: `shared → features → app`. A feature must never import from `app/**` (rule `NB-ARCH-002`, error). Routes compose features; features do not know about routing entry points.
+- Keep `index.ts` small: export only what other features/routes genuinely need. Everything not exported is private.
+- When two features need the same code, move it down to `lib/` or `components/ui/` — do not import it sideways.
+- Do not introduce `features/` prematurely. A handful of screens does not need it; adopt this structure when a second feature starts bleeding into the first.
+
+## Anti-patterns
+
+- Type-first folders at scale (`components/` with 200 files from every domain).
+- Barrel files re-exporting everything — export the public surface only; large barrels hurt tree-shaking and build times.
+- "Shared" modules importing from features (upward dependency).
+
+For editor-time feedback on these boundaries, `eslint-plugin-boundaries` is a good optional companion; node-boost enforces the same rules in `audit`/`guard`.

package/resources/react/architectures/feature-modules/skill/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: feature-modules
+description: Create and evolve feature modules with enforced boundaries — where new code goes, how features talk to each other, and when code moves to shared.
+---
+
+# Feature Modules
+
+## When to use this skill
+
+Use when adding a new feature, deciding where a new file belongs, or resolving a cross-feature import finding (`NB-ARCH-001`/`NB-ARCH-002`).
+
+## Creating a feature
+
+1. Create `src/features/<name>/` with only the folders you need (`api/`, `components/`, `hooks/`, `types.ts`).
+2. Add `index.ts` exporting the minimal public surface.
+3. Wire it into a route in `app/` — routes compose features, never the other way around.
+
+## Deciding where code goes
+
+- Used by one feature → inside that feature.
+- Used by two or more features → `lib/` (logic) or `components/ui/` (domain-agnostic UI).
+- Needs another feature's UI + data on one screen → compose in the route, pass props.
+
+## Fixing boundary violations
+
+- `NB-ARCH-001`: import via the feature's `index.ts` (public-api variant) or restructure — move shared code down, or compose at the route (forbid variant).
+- `NB-ARCH-002`: the feature imports route-level code; invert it — the route should pass data/callbacks into the feature.
+- A justified exception needs `// nb-disable NB-ARCH-001 -- <reason>` with a real reason.

package/resources/react/architectures/feature-modules/variants/forbid.md

@@ -0,0 +1,36 @@
+# Feature Modules (forbid boundary)
+
+Organize code by feature. In this strict variant features are fully isolated: **no imports between features at all**. Shared code moves down to `lib/`/`components/ui/`; composite screens are assembled at the route level.
+
+## Structure
+
+<code-snippet name="Feature-first layout" lang="text">
+src/
+├── features/
+│   └── invoices/
+│       ├── api/
+│       ├── components/
+│       ├── hooks/
+│       ├── types.ts
+│       └── index.ts      # public API consumed ONLY by app/ routes
+├── components/ui/        # shared, domain-agnostic UI kit
+├── lib/                  # shared utilities, api client
+└── app/                  # routes — the ONLY place features are combined
+</code-snippet>
+
+## Boundary rules (enforced by node-boost audit)
+
+- `NB-ARCH-001` (error): **any** import from one feature into another is forbidden — including via `index.ts`.
+- `NB-ARCH-002` (error): a feature must never import from `app/**`. Dependency direction is `shared → features → app`.
+
+## How to work within the rules
+
+- Need feature B's component inside feature A's screen? Compose both in the route (`app/`), passing data via props.
+- Need feature B's types or helpers? Move them to `lib/` — if two features need it, it is shared by definition.
+- The payoff: zero dependency cycles, features are deletable and extractable wholesale, and every feature can be understood in isolation.
+
+## Anti-patterns
+
+- Smuggling cross-feature access through `lib/` wrappers that just re-export a feature's internals.
+- A giant "shared" dumping ground — `lib/` is for genuinely generic code, not a backdoor.
+- Deep relative paths that dodge aliases — the boundary applies regardless of import style.

package/resources/react/architectures/feature-modules/variants/public-api.md

@@ -0,0 +1,37 @@
+# Feature Modules (public-api boundary)
+
+Organize code by feature. Each feature is a module with a public API in `index.ts`; cross-feature imports are allowed **only through that public API**.
+
+## Structure
+
+<code-snippet name="Feature-first layout" lang="text">
+src/
+├── features/
+│   └── invoices/
+│       ├── api/          # data access for this feature
+│       ├── components/
+│       ├── hooks/
+│       ├── types.ts
+│       └── index.ts      # PUBLIC API — the only cross-feature entry point
+├── components/ui/        # shared, domain-agnostic UI kit
+├── lib/                  # shared utilities, api client
+└── app/                  # routes — compose features, no business logic
+</code-snippet>
+
+## Boundary rules (enforced by node-boost audit)
+
+- `NB-ARCH-001` (error): importing another feature's internals is forbidden. `import { CartSummary } from "@/features/cart"` is fine; `import { store } from "@/features/cart/internal/store"` is not.
+- `NB-ARCH-002` (error): a feature must never import from `app/**`. Dependency direction is `shared → features → app`.
+
+## Conventions
+
+- Keep `index.ts` deliberately small — every export is a contract. If a feature's public API grows past ~10 exports, it is probably two features.
+- Shared code goes down to `lib/` or `components/ui/`, never sideways between features.
+- Watch for cycles: if feature A imports B and B imports A (even via `index.ts`), extract the shared piece to `lib/` or compose both at the route level.
+- Do not introduce `features/` prematurely — adopt it when a second feature starts bleeding into the first.
+
+## Anti-patterns
+
+- Re-exporting everything from `index.ts` "just in case" — large barrels hurt tree-shaking and make everything public.
+- "Shared" modules importing from features (upward dependency).
+- Deep relative paths (`../../cart/...`) that dodge the alias — the boundary applies regardless of import style.

package/resources/react/architectures/modern-typescript/guideline.md

@@ -0,0 +1,47 @@
+# Modern TypeScript
+
+The language contract for this codebase: strict compiler, no `any`, closed sets as unions, IDs as branded types.
+
+## Compiler
+
+`strict: true` is non-negotiable (`NB-ARCH-013`, warn). New projects also enable `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`.
+
+## No `any` — narrow `unknown`
+
+`any` switches the type checker off at every use site (`NB-ARCH-014`, warn). For data of unknown shape use `unknown` and narrow with guards or parse with zod (typed-contracts). Casting external data with `as` is the same lie with better manners.
+
+## Closed sets: discriminated unions + exhaustiveness
+
+<code-snippet name="Union with exhaustive switch" lang="ts">
+type PaymentState =
+  | { kind: "pending" }
+  | { kind: "paid"; paidAt: Date }
+  | { kind: "failed"; reason: string }
+
+function label(state: PaymentState): string {
+  switch (state.kind) {
+    case "pending": return "Pending"
+    case "paid":    return `Paid ${state.paidAt.toLocaleDateString()}`
+    case "failed":  return state.reason
+    default: { const _exhaustive: never = state; throw new Error("unreachable") }
+  }
+}
+// Adding { kind: "refunded" } breaks the build HERE — every switch is found for you.
+</code-snippet>
+
+Do not use TS `enum` — runtime quirks, poor tree-shaking. Closed value sets are const objects: `const Role = { admin: "admin", user: "user" } as const; type Role = keyof typeof Role`.
+
+## Branded types for identifiers
+
+<code-snippet name="IDs that cannot be swapped" lang="ts">
+type UserId = string & { readonly __brand: "UserId" }
+type InvoiceId = string & { readonly __brand: "InvoiceId" }
+// payInvoice(userId, invoiceId) with swapped args → compile error, not a prod bug
+</code-snippet>
+
+Zero runtime cost — compile-time value objects. Use for IDs and easily-confused scalars (amounts, emails).
+
+## Also
+
+- `satisfies` to type-check without widening: `const config = {...} satisfies Config`.
+- Prefer `readonly` arrays/fields on data that must not mutate.

package/resources/react/architectures/modern-typescript/skill/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: modern-typescript
+description: Apply strict TypeScript idioms — unknown over any, discriminated unions with exhaustive switches, branded IDs, const objects over enums.
+---
+
+# Modern TypeScript
+
+## When to use this skill
+
+Use when modeling domain types, handling unknown-shaped data, or fixing `NB-ARCH-013`/`NB-ARCH-014`.
+
+## Procedure
+
+1. State that varies by kind → discriminated union with a `kind` field; every `switch` gets a `never` exhaustiveness check in `default`.
+2. Closed value set → const object + `keyof typeof`, never `enum`.
+3. New identifier type → brand it (`string & { readonly __brand: "XId" }`); constructors live next to the schema (`invoiceIdSchema.parse(raw) as InvoiceId` at the boundary only).
+4. Unknown-shaped data → `unknown`, then a type guard or zod parse. Never `any`, never bare `as`.
+5. Config-like literals → `satisfies` instead of a type annotation.
+
+## Fixing findings
+
+- `NB-ARCH-013`: enable `strict: true` in tsconfig; fix fallout incrementally (start with `strictNullChecks` errors).
+- `NB-ARCH-014`: replace `any` with `unknown` + narrowing, a precise type, or a generic; in tests it is tolerated (rule skips test files).

package/resources/react/architectures/secure-by-default/guideline.md

@@ -0,0 +1,38 @@
+# Secure by Default
+
+JSX escapes everything automatically. The vulnerabilities live in the escape hatches — close them by default.
+
+## XSS: one door, keep it locked
+
+<code-snippet name="Sanitize or don't render" lang="tsx">
+// NB-ARCH-011 (error): raw HTML from any dynamic source
+<div dangerouslySetInnerHTML={{ __html: comment.body }} />
+
+// The only acceptable form — sanitize first:
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(comment.body) }} />
+</code-snippet>
+
+Prefer rendering data as JSX; reach for raw HTML only for trusted rich text (CMS/editor output), always sanitized (DOMPurify client-side, isomorphic-dompurify/sanitize-html on the server — or sanitize at write time). Trusted static literals may use `// nb-disable NB-ARCH-011 -- <reason>`.
+
+## Public env prefixes are publication
+
+Everything named `NEXT_PUBLIC_*` / `VITE_*` ships inside the JS bundle, readable in DevTools by anyone. `NB-ARCH-012` (warn) flags secret-sounding names (`SECRET`, `TOKEN`, `PRIVATE`, `PASSWORD`, `*_KEY`) behind a public prefix. A key that grants write/admin access must never be public; server-side secrets stay unprefixed.
+
+## Server Actions are public endpoints
+
+Every `"use server"` function compiles to an HTTP endpoint anyone can call. Treat each like a controller route:
+
+1. **Authenticate** the caller,
+2. **authorize** the operation,
+3. **validate** the input (zod — typed-contracts),
+4. return only what the caller may see.
+
+Never assume "only my form calls this".
+
+## Keep server code on the server
+
+Add `import "server-only"` to data-layer modules that touch secrets — importing them from a Client Component then fails the build instead of leaking at runtime. React taint APIs are an extra experimental layer, not a substitute.
+
+## Baseline
+
+Set a Content-Security-Policy (via `next.config`/middleware or hosting), keep dependencies patched, and never log tokens or PII to the browser console.

package/resources/react/architectures/secure-by-default/skill/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: secure-by-default
+description: Handle untrusted content, env variables, Server Actions and server-only code safely in React/Next apps.
+---
+
+# Secure by Default
+
+## When to use this skill
+
+Use when rendering user/CMS-provided content, adding env variables, writing Server Actions, or fixing `NB-ARCH-011`/`NB-ARCH-012`.
+
+## Procedure
+
+1. Rich text/HTML to render → sanitize (`DOMPurify.sanitize`) before `dangerouslySetInnerHTML`; if the content can be plain data, render it as JSX instead.
+2. New env variable → secret? no public prefix, access via `env.ts` server-side only. Client-needed? confirm it is harmless when public, then prefix (`NEXT_PUBLIC_`/`VITE_`).
+3. New Server Action → first lines: auth check, then `schema.parse(input)`; return minimal data; add cache invalidation after writes.
+4. Data-layer module touching secrets → `import "server-only"` at the top.
+
+## Fixing findings
+
+- `NB-ARCH-011`: wrap the value in a sanitizer call, or replace raw HTML with JSX rendering.
+- `NB-ARCH-012`: remove the public prefix and move usage server-side; if genuinely public, rename so it does not masquerade as a secret and suppress with a reason.

package/resources/react/architectures/server-first-components/guideline.md

@@ -0,0 +1,34 @@
+# Server-First Components
+
+In the App Router, components are Server Components by default. Keep them that way: fetch data on the server, ship less JavaScript, and push `"use client"` down to interactive leaves.
+
+## Rules
+
+- Never put `"use client"` in `page.tsx` or `layout.tsx` (`NB-ARCH-003`, error). Route entries stay server-side; extract the interactive part into a leaf component instead.
+- Do not add `"use client"` to files with no hooks, event handlers, or browser APIs (`NB-ARCH-004`, warn) — the directive is not a talisman, it makes the whole subtree client-side.
+- A genuinely full-client page (canvas playground, embedded editor shell) is a documented exception: `// nb-disable NB-ARCH-003 -- <reason>`.
+
+<code-snippet name="Interactive leaf, server entry" lang="tsx">
+// app/invoices/page.tsx — Server Component: async, fetches data
+export default async function InvoicesPage() {
+  const invoices = await getInvoices()
+  return <InvoiceTable invoices={invoices} toolbar={<InvoiceFilter />} />
+}
+
+// features/invoices/components/InvoiceFilter.tsx — client leaf
+"use client"
+export function InvoiceFilter() {
+  const [query, setQuery] = useState("")
+  return <input value={query} onChange={(e) => setQuery(e.target.value)} />
+}
+</code-snippet>
+
+## Mental model
+
+`"use client"` marks a boundary, not a component: everything imported below it becomes client code. Server Components can render Client Components and pass serializable props (no functions, no class instances) — compose interactivity in, don't lift the whole page out.
+
+## Next 16 specifics
+
+- Nothing is cached by default; caching is explicit via `"use cache"` on components/functions — which only works if the tree stays server-first.
+- Partial Prerendering splits pages into a static shell plus dynamic holes in `<Suspense>`. A client-rooted page opts out of all of it.
+- Do not generate legacy idioms: `getServerSideProps`/`getStaticProps` belong to the Pages Router, not here.

package/resources/react/architectures/server-first-components/skill/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: server-first-components
+description: Decide where the "use client" boundary goes in Next.js App Router code and keep pages/layouts server-side.
+---
+
+# Server-First Components
+
+## When to use this skill
+
+Use when creating pages/layouts, when tempted to add `"use client"`, or when fixing `NB-ARCH-003`/`NB-ARCH-004` findings.
+
+## Procedure
+
+1. Start every component as a Server Component (no directive). Fetch data with `await` in the component body via the data layer.
+2. Add `"use client"` only when the file actually uses state/effects, event handlers, or browser APIs.
+3. If a page needs interactivity, extract the interactive part into a leaf component in the feature and render it from the server page — never mark the page itself.
+4. Pass only serializable props across the boundary. Need a callback? Move the state down into the client leaf, or use a Server Action.
+5. For caching, add `"use cache"` in the data layer function, not in the component; wrap truly dynamic islands in `<Suspense>`.
+
+## Fixing findings
+
+- `NB-ARCH-003`: move interactivity to a leaf; keep the entry async and server-side.
+- `NB-ARCH-004`: delete the unnecessary directive — the file has nothing client-only in it.

package/resources/react/architectures/state-management/guideline.md

@@ -0,0 +1,34 @@
+# State Management
+
+Classify state before placing it. Each kind has exactly one correct home; most bugs come from putting server data in a client store.
+
+| Kind | Example | Home |
+|---|---|---|
+| Server state | invoices, users | react-query cache (or RSC props in Next) |
+| Local UI state | open modal, input value | `useState` in the component |
+| Shared client state | theme, sidebar, multi-step draft | Context (rare updates) / store like zustand (frequent) |
+| URL state | filters, pagination, active tab | `searchParams` |
+
+## The one big rule: server state is a cache, not state
+
+<code-snippet name="Anti-pattern: copying cache into a store" lang="ts">
+// WRONG — two sources of truth, manual sync, staleness bugs (NB-ARCH-009, warn)
+const invoices = await api.getInvoices()
+useInvoiceStore.setState({ invoices })
+</code-snippet>
+
+react-query already is the store for server data: keys, staleness, refetch, `invalidateQueries` after mutations. A client store holds only what the backend does not know (preferences, drafts, selections).
+
+## Escalation ladder
+
+`useState` → URL → Context → store. Escalate only when the level below fails. URL state is underused: filters and pagination in `searchParams` give deep links, back button and refresh survival for free.
+
+## Next specifics
+
+Server Components remove the need for much client state — data arriving as props needs no client cache. Keep react-query for interactive islands, not for whole server-rendered pages.
+
+## Anti-patterns
+
+- A global store as junk drawer (2016-Redux style).
+- Deriving state with `useEffect` + `setState` — compute it during render instead.
+- Duplicating URL state in a store and syncing by hand.

package/resources/react/architectures/state-management/skill/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: state-management
+description: Choose the right home for a piece of state (react-query, useState, URL, Context, store) and keep server data out of client stores.
+---
+
+# State Management
+
+## When to use this skill
+
+Use when introducing any new state, choosing between store/context/URL, or fixing `NB-ARCH-009`.
+
+## Procedure
+
+1. Classify: does the backend own this data? → react-query (or RSC props). Is it one component's concern? → `useState`. Should a link/refresh preserve it? → URL `searchParams`. Only genuinely shared, client-owned state goes to Context/store.
+2. Mutating server data: `useMutation`/Server Action + `invalidateQueries` — never write the response into a store.
+3. Before adding a store: check the ladder (`useState` → URL → Context → store) and justify each escalation.
+4. Deriving from existing state? Compute in render (or `useMemo` if expensive) — not `useEffect` + `setState`.
+
+## Fixing findings
+
+- `NB-ARCH-009`: delete the store write; read the data via the query hook where it is needed. If the store held a derived selection, keep only the selection (ids), not the server objects.

package/resources/react/architectures/styling-tailwind/guideline.md

@@ -0,0 +1,33 @@
+# Styling with Tailwind
+
+Utility-first with discipline: tokens from the theme, variants through cva, reuse through components.
+
+## Check the Tailwind major first
+
+Tailwind 4 configures in CSS — there is **no `tailwind.config.js`**:
+
+<code-snippet name="Tailwind 4 CSS-first config" lang="css">
+@import "tailwindcss";
+@theme {
+  --color-brand: oklch(0.62 0.19 260);
+  --spacing-gutter: 1.5rem;
+}
+</code-snippet>
+
+Generating a v3-style JS config in a v4 project is a common error — follow the versioned tailwindcss guideline for this project.
+
+## Rules
+
+- **Tokens over arbitrary values**: colors/spacing come from `@theme`; `w-[347px]` needs a reason, or the codebase grows fifty shades of gray.
+- **Variants via cva + tailwind-merge**, not string concatenation:
+
+<code-snippet name="Variants with cva" lang="ts">
+const button = cva("rounded px-4 py-2 font-medium", {
+  variants: { intent: { primary: "bg-brand text-white", danger: "bg-red-600 text-white" } },
+  defaultVariants: { intent: "primary" },
+})
+</code-snippet>
+
+- **Never build class names dynamically**: `text-${color}-500` does not exist in the build — the compiler scans sources statically; a class not written literally is a class not generated. Map to full literal classes instead.
+- **Repeating a class string? Extract a component**, not an `@apply` class — the unit of reuse is the React component. Keep `@apply` to a minimum.
+- Conditional classes through a `cn()` helper (clsx + tailwind-merge); class order handled by prettier-plugin-tailwindcss (or Biome's sorting when the project uses Biome).

package/resources/react/architectures/styling-tailwind/skill/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: styling-tailwind
+description: Style components with Tailwind using theme tokens, cva variants and component extraction — matching the project's Tailwind major version.
+---
+
+# Styling with Tailwind
+
+## When to use this skill
+
+Use when styling components, adding visual variants, or touching Tailwind configuration.
+
+## Procedure
+
+1. Check the project's Tailwind major (see application_info / package.json). v4: config lives in CSS (`@theme`); never create `tailwind.config.js`. v3: JS config applies.
+2. New color/spacing → add a token to the theme; avoid arbitrary values unless one-off and justified.
+3. Component with visual variants → define with cva, merge overrides with tailwind-merge, expose a `variant` prop.
+4. Conditional classes → `cn(base, cond && "...")`; never template-interpolate class fragments.
+5. Same class string appearing twice → extract a component in `components/ui/`.