create-win-project 1.3.0

package/playbooks/capabilities/laravel/oidc-resource-server.md

@@ -0,0 +1,10 @@
+# Laravel Auth0 OIDC Resource Server
+
+The generated adapter uses the pinned `auth0/login` package. Auth0 owns login,
+Authorization Code with PKCE, access/refresh issuance,
+rotation, recovery, and revocation. Laravel accepts access tokens only and validates the
+signature against trusted keys plus issuer, audience, expiry/not-before, and required
+permissions. Cache key discovery with safe rotation and fail closed. Never send refresh
+tokens to this API. Configure the exact tenant domain and API audience; never accept an ID
+token as an API access token. Test invalid signature, issuer, audience, time, permission,
+and owner.

package/playbooks/capabilities/laravel/queues.md

@@ -0,0 +1,8 @@
+# Laravel Queues
+
+Jobs are small, idempotent, timeout-bounded, retry-aware, and safe when delivered more
+than once. Dispatch after commit when a job depends on written records. Record terminal
+failure and operational ownership. Use an outbox/relay when a database change and an
+external message must be delivered reliably; a plain event or queued listener is not an
+atomic cross-system guarantee.
+

package/playbooks/capabilities/laravel/sanctum-spa.md

@@ -0,0 +1,8 @@
+# Sanctum Stateful SPA Authentication
+
+Use this only for a first-party browser frontend sharing the Laravel application's parent
+domain. Sanctum authenticates with Laravel's session cookie, not a browser bearer token.
+Initialize CSRF protection, send credentials deliberately, configure exact stateful
+domains/CORS origins, and authorize every resource server-side. Test CSRF rejection,
+credentialed CORS, login/logout, expiry, and forbidden ownership.
+

package/playbooks/capabilities/laravel/scheduler.md

@@ -0,0 +1,7 @@
+# Laravel Scheduler
+
+Scheduled commands are idempotent, observable, and protected from unintended overlap.
+Use one scheduler trigger per environment, explicit time zones, distributed locking where
+multiple instances run, and safe catch-up rules. Test the command behavior separately
+from its clock registration.
+

package/playbooks/capabilities/laravel/session-auth.md

@@ -0,0 +1,8 @@
+# Laravel Session Authentication
+
+Laravel owns the server session and sends only an HttpOnly, Secure cookie with a deployed
+SameSite policy. Rotate the session after login and invalidate it plus its CSRF token on
+logout. Keep CSRF protection on every cookie-authenticated mutation. Generate login,
+logout, recovery, verification as selected, and test fixation resistance, expiry,
+unauthenticated redirects/responses, forbidden resources, and logout invalidation.
+

package/playbooks/capabilities/laravel/storage-uploads.md

@@ -0,0 +1,7 @@
+# Laravel Storage and Uploads
+
+Treat names, MIME claims, and content as untrusted. Enforce size/type/ownership limits,
+generate server-owned object names, keep sensitive files off public disks, authorize
+downloads, and use short-lived signed access where appropriate. Scan risky formats and
+remove abandoned uploads. Never build filesystem paths directly from user input.
+

package/playbooks/capabilities/postgresql/architecture.md

@@ -0,0 +1,5 @@
+# PostgreSQL Architecture
+
+PostgreSQL is the durable source of truth. Application operations own transaction boundaries;
+database constraints protect invariants under concurrency. Keep one authoritative migration history,
+use connection pooling deliberately, and isolate privileged maintenance from normal application roles.

package/playbooks/capabilities/postgresql/migrations.md

@@ -0,0 +1,5 @@
+# PostgreSQL Migrations
+
+Migrations are immutable after deployment. Review locks and table rewrites, prefer expand/contract
+changes, separate long backfills, and keep application versions compatible during rollout. Production
+execution needs a lock, backup/recovery plan, observability, and explicit approval for destructive SQL.

package/playbooks/capabilities/postgresql/postgresql.manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "postgres",
+  "kind": "database",
+  "label": "PostgreSQL",
+  "playbooks": ["capabilities/postgresql/architecture.md", "capabilities/postgresql/schema-design.md", "capabilities/postgresql/migrations.md", "capabilities/postgresql/security.md", "capabilities/postgresql/testing.md"],
+  "appliesTo": { "backend": ["postgres", "springboot"] },
+  "required": true,
+  "architectureProfiles": ["small", "medium", "large"],
+  "makefileTemplate": "postgres",
+  "folders": [],
+  "env": ["DATABASE_URL"],
+  "concerns": [
+    { "id": "schema", "required": true, "playbook": "capabilities/postgresql/schema-design.md", "sections": ["Core Rules"] }
+  ]
+}

package/playbooks/capabilities/postgresql/schema-design.md

@@ -0,0 +1,7 @@
+# PostgreSQL Schema Design
+
+## Core Rules
+
+Use explicit primary/foreign keys, nullability, unique/check constraints, and timestamps with time
+zone. Choose types for domain meaning, not convenience. Index foreign keys and measured filter/sort
+paths; avoid speculative indexes. Define deletion behavior and tenant/resource ownership explicitly.

package/playbooks/capabilities/postgresql/security.md

@@ -0,0 +1,5 @@
+# PostgreSQL Security
+
+Use least-privilege roles, TLS outside trusted local networks, rotated secrets, and separate migration
+credentials. Parameterize values; allowlist identifiers. Never expose PostgreSQL directly to browsers
+or mobile clients. Log operational context without statements/parameters containing secrets or PII.

package/playbooks/capabilities/postgresql/testing.md

@@ -0,0 +1,5 @@
+# PostgreSQL Testing
+
+Test migrations from empty and supported prior schemas against the target PostgreSQL major. Cover
+constraints, conflicts, transaction rollback, locking/concurrency risks, query plans for critical
+paths, and backup restoration. SQLite/H2 cannot prove PostgreSQL-specific behavior.

package/playbooks/capabilities/prisma/architecture.md

@@ -0,0 +1,5 @@
+# Prisma Architecture
+
+Create one server-only Prisma client and inject/use it behind Next-owned data access. Browser code
+never imports Prisma. Services own business operations; repositories are optional boundaries for
+complex owned persistence, not wrappers around every generated method.

package/playbooks/capabilities/prisma/migrations.md

@@ -0,0 +1,11 @@
+# Prisma Migrations
+
+## Development
+
+Use `prisma migrate dev` only against disposable development data, review generated SQL, and commit
+the schema and migration together. Never rewrite an applied migration.
+
+## Production
+
+Use `prisma migrate deploy` in one controlled release job. Never run `migrate reset` or development
+migration commands against production. Use expand/contract changes and forward fixes.

package/playbooks/capabilities/prisma/prisma.manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "prisma",
+  "kind": "migration",
+  "label": "Prisma",
+  "playbooks": ["capabilities/prisma/architecture.md", "capabilities/prisma/schema.md", "capabilities/prisma/migrations.md", "capabilities/prisma/runtime.md", "capabilities/prisma/testing.md"],
+  "appliesTo": { "backend": ["postgres"] },
+  "required": true,
+  "folders": [],
+  "deps": ["@prisma/client", "@prisma/adapter-pg", "pg"],
+  "devDeps": ["prisma", "dotenv", "@types/pg"],
+  "concerns": [
+    { "id": "migration", "required": true, "playbook": "capabilities/prisma/migrations.md", "sections": ["Development", "Production"] }
+  ]
+}

package/playbooks/capabilities/prisma/runtime.md

@@ -0,0 +1,5 @@
+# Prisma Runtime
+
+Use the catalog-tested driver adapter, reuse the client, select only required data, paginate bounded
+queries, avoid N+1 access, and allowlist sorting/filtering. Application operations own `$transaction`;
+keep external network calls out of long database transactions.

package/playbooks/capabilities/prisma/schema.md

@@ -0,0 +1,5 @@
+# Prisma Schema
+
+Model real PostgreSQL constraints, relations, deletion behavior, mapped names, indexes, and deliberate
+nullability. Keep generated client output out of hand-edited source. Validate application input and
+still handle database uniqueness/foreign-key failures safely under races.

package/playbooks/capabilities/prisma/testing.md

@@ -0,0 +1,5 @@
+# Prisma Testing
+
+Unit-test pure rules without Prisma. Test repositories/queries and migrations against real PostgreSQL,
+including constraints, relations, transactions, conflicts, and representative pagination. Reset an
+isolated test database safely; never point tests at shared or production data.

package/playbooks/capabilities/supabase/architecture.md

@@ -0,0 +1,5 @@
+# Supabase Architecture
+
+Supabase PostgreSQL, Auth, Storage, and Realtime are separate capabilities sharing an authorization
+boundary. Normal clients use the publishable key plus user identity; RLS protects rows. Secret/service
+operations run only in trusted server jobs and never share the normal client path.

package/playbooks/capabilities/supabase/authentication.md

@@ -0,0 +1,5 @@
+# Supabase Authentication
+
+Supabase owns access/refresh issuance, persistence, rotation, and revocation. Next.js synchronizes SSR
+cookies through Proxy and verifies claims; Vite uses browser SDK refresh; Expo stores sessions in
+SecureStore and binds refresh to app lifecycle. Allowlist web callbacks and native deep links exactly.

package/playbooks/capabilities/supabase/expo.md

@@ -0,0 +1,16 @@
+# Supabase with Expo
+
+## Native Session
+
+Persist Supabase session material with the generated SecureStore adapter, never
+AsyncStorage. Disable URL-session detection intended for browsers. Start/stop automatic
+refresh with application foreground/background lifecycle when required by the installed
+SDK version, and handle revoked/expired sessions without a retry loop.
+
+Register exact deep-link schemes and callback URLs for sign-in, verification, recovery,
+and OAuth. Validate in-app destinations. `EXPO_PUBLIC_` values are public; only the
+Supabase URL and publishable key belong there.
+
+RLS remains authorization. A decoded token or local role flag is not permission to access
+a row. Test session restore, foreground refresh, logout, deep-link rejection, and secure
+storage failures on Android and iOS.

package/playbooks/capabilities/supabase/migrations.md

@@ -0,0 +1,7 @@
+# Supabase Migrations
+
+## Local and Hosted Flow
+
+The pinned local CLI owns `supabase/config.toml`, ordered SQL migrations, generated types, and pgTAP
+tests. Develop/reset only locally, review diffs, test from empty state, and use a reviewed linked
+deployment command in CI/release. Production reset is forbidden; deployed history receives a forward fix.

package/playbooks/capabilities/supabase/nextjs.md

@@ -0,0 +1,24 @@
+# Supabase with Next.js
+
+## Clients and Proxy
+
+Use `@supabase/ssr` with three responsibilities:
+
+```text
+Client Component → browser client
+Server Component/Function/Route Handler → cookie-aware server client
+Next Proxy → getClaims() + synchronized request/response cookies
+```
+
+Proxy refresh keeps cookies current but is not authorization. Every protected server
+operation verifies claims and lets RLS enforce row access. Do not trust `getSession()`'s
+user object alone on the server. Use `getUser()` only when a fresh Auth user record is
+specifically required.
+
+Use PKCE callbacks. Allow only registered origins and validated application-relative
+destinations; never redirect to an arbitrary query-string URL. Mark server/admin modules
+`server-only`. The admin client is not imported into Client Components.
+
+Repositories under a Next feature may use the authenticated server client when Next owns
+the application operation. Preserve the caller's RLS context instead of automatically
+switching to a secret client.

package/playbooks/capabilities/supabase/rls.md

@@ -0,0 +1,7 @@
+# Supabase Row-Level Security
+
+## Grants and Policies
+
+Enable RLS, grant only required table operations to explicit roles, and write separate policies for
+select/insert/update/delete with both `using` and `with check` where applicable. Use `(select auth.uid())`,
+index policy columns, enforce ownership beside API operations, and test owner/non-owner/anonymous paths.

package/playbooks/capabilities/supabase/supabase.manifest.json

@@ -0,0 +1,32 @@
+{
+  "id": "supabase",
+  "kind": "database",
+  "label": "Supabase",
+  "appliesTo": { "backend": ["supabase"] },
+  "required": true,
+  "architectureProfiles": ["small", "medium", "large"],
+  "playbooks": [
+    "capabilities/supabase/architecture.md",
+    "capabilities/supabase/migrations.md",
+    "capabilities/supabase/rls.md",
+    "capabilities/supabase/authentication.md",
+    "capabilities/supabase/testing.md",
+    { "file": "capabilities/supabase/nextjs.md", "appliesWhen": { "frontend": "nextjs" } },
+    { "file": "capabilities/supabase/vite.md", "appliesWhen": { "frontend": "react" } },
+    { "file": "capabilities/supabase/expo.md", "appliesWhen": { "frontend": "react-native" } },
+    "capabilities/supabase/testing.md"
+  ],
+  "makefileTemplate": "supabase",
+  "folders": [],
+  "deps": ["@supabase/ssr", "@supabase/supabase-js"],
+  "devDeps": ["supabase"],
+  "env": ["SUPABASE_URL", "SUPABASE_PUBLISHABLE_KEY"],
+  "clientEnv": ["SUPABASE_URL", "SUPABASE_PUBLISHABLE_KEY"],
+  "concerns": [
+    { "id": "supabase-runtime", "required": true, "playbook": "capabilities/supabase/migrations.md", "sections": ["Local and Hosted Flow"] },
+    { "id": "rls", "required": true, "playbook": "capabilities/supabase/rls.md", "sections": ["Grants and Policies"] },
+    { "id": "supabase-next", "required": true, "appliesWhen": { "frontend": "nextjs" }, "playbook": "capabilities/supabase/nextjs.md", "sections": ["Clients and Proxy"] },
+    { "id": "supabase-vite", "required": true, "appliesWhen": { "frontend": "react" }, "playbook": "capabilities/supabase/vite.md", "sections": ["Browser Session"] },
+    { "id": "supabase-expo", "required": true, "appliesWhen": { "frontend": "react-native" }, "playbook": "capabilities/supabase/expo.md", "sections": ["Native Session"] }
+  ]
+}

package/playbooks/capabilities/supabase/testing.md

@@ -0,0 +1,5 @@
+# Supabase Testing
+
+Run migrations and pgTAP against the local stack. Include allow and deny RLS cases for anonymous,
+authenticated owner, authenticated non-owner, and trusted system operations. Test callback/deep-link
+allowlists, expiry, refresh, logout/revocation, generated types, storage policies, and destructive safety.

package/playbooks/capabilities/supabase/vite.md

@@ -0,0 +1,14 @@
+# Supabase with Vite
+
+## Browser Session
+
+The browser SDK owns session persistence and refresh. Do not create a second refresh-token
+interceptor or copy credentials into an application store. UI route guards prevent visual
+confusion; grants and RLS authorize every database operation.
+
+Only `VITE_SUPABASE_URL` and the publishable key enter browser code. A secret/service-role
+key, database password, or OAuth client secret is never a Vite environment value.
+
+Place Supabase queries in feature `data.ts` functions, validate data crossing external
+boundaries, and clean up Realtime channels. Handle signed-out, expired, revoked, loading,
+and retry states without refresh loops.

package/playbooks/concerns/axios.md

@@ -0,0 +1,123 @@
+# Axios — HTTP Client
+
+> **When to use:** Any stack that communicates with a REST API via a typed axios client.
+> Next.js uses `apiFetch` (server-only). React Vite and React Native use this pattern.
+
+---
+
+# 1. One Shared Client
+
+Never create ad-hoc axios instances per feature. One shared `apiClient` for all HTTP calls.
+
+```ts
+// lib/apiClient.ts
+import axios from 'axios'
+import { ENV } from '@/config/env'  // RN
+// import { env } from '@/lib/env'  // React Vite — adjust import to your env helper
+
+const http = axios.create({
+  baseURL: ENV.API_BASE_URL,
+  headers: { 'Content-Type': 'application/json' },
+  timeout: 10_000,
+})
+
+http.interceptors.request.use(async (config) => {
+  const token = await tokenStorage.get() // RN: expo-secure-store
+  // Browser apps should prefer same-origin HttpOnly cookies. If bearer access
+  // tokens are required, keep the short-lived access token in memory.
+  if (token) config.headers.Authorization = `Bearer ${token}`
+  return config
+})
+
+http.interceptors.response.use(
+  (response) => response.data,
+  (error) => {
+    const appError: AppError = {
+      status: error.response?.status ?? 0,
+      code: error.response?.data?.code ?? 'NETWORK_ERROR',
+      message: error.response?.data?.message ?? error.message,
+    }
+    return Promise.reject(appError)
+  }
+)
+
+export const apiClient = {
+  get:    <T>(path: string)                 => http.get<T, T>(path),
+  post:   <T>(path: string, body?: unknown) => http.post<T, T>(path, body),
+  put:    <T>(path: string, body?: unknown) => http.put<T, T>(path, body),
+  patch:  <T>(path: string, body?: unknown) => http.patch<T, T>(path, body),
+  delete: <T>(path: string)                 => http.delete<T, T>(path),
+}
+```
+
+---
+
+# 2. AppError Type
+
+Errors are normalized in the response interceptor. Everything above sees `AppError` only.
+
+```ts
+// types/errors.ts  (web: src/types/errors.ts | RN: types/errors.ts)
+export type AppError = {
+  status: number
+  code: string
+  message: string
+}
+
+export function isAppError(err: unknown): err is AppError {
+  return typeof err === 'object' && err !== null && 'code' in err && 'status' in err
+}
+```
+
+---
+
+# 3. Service Calls apiClient, Hook Calls Service
+
+```ts
+// features/products/services/productService.ts
+import { apiClient } from '@/lib/apiClient'
+
+export const productService = {
+  getAll: (): Promise<Product[]>              => apiClient.get('/products'),
+  getById: (id: string): Promise<Product>    => apiClient.get(`/products/${id}`),
+  create: (input: CreateProductInput)         => apiClient.post<Product>('/products', input),
+  delete: (id: string): Promise<void>         => apiClient.delete(`/products/${id}`),
+}
+```
+
+Hooks call `productService`. Never call `apiClient` directly from a hook.
+
+---
+
+# 4. Rules
+
+- One `apiClient` instance. Never create new axios instances per feature.
+- Auth token injection → request interceptor only. Not in every service call.
+- Error normalization → response interceptor only. Services receive `AppError`.
+- Route on `error.code`, never `error.message` — codes are stable, messages change.
+- Services are the only callers of `apiClient`. Hooks call services.
+
+---
+
+# 5. Platform Notes
+
+> **React Native** — token storage uses `expo-secure-store` via a `tokenStorage` helper.
+> Never use `localStorage` in React Native — it does not exist.
+
+> **React Vite** — prefer a same-origin `HttpOnly` session/refresh cookie. Do not
+> store session IDs, access tokens, or refresh tokens in `localStorage` or
+> `sessionStorage`. Cookie-authenticated mutations also require CSRF protection.
+> See `playbooks/universal/security.md`.
+
+---
+
+# 6. Agent Quick Reference
+
+```text
+New API endpoint?         → new method in features/[name]/services/[name]Service.ts
+                          → calls apiClient, never raw fetch/axios
+Hook needs data?          → call service from hook, not apiClient directly
+Auth not attaching?       → check request interceptor in lib/apiClient.ts
+Error not normalized?     → check response interceptor in lib/apiClient.ts
+New error code to handle? → route on error.code in the hook or component
+```

package/playbooks/concerns/next-safe-action.md

@@ -0,0 +1,66 @@
+# next-safe-action — Type-Safe Server Actions (Next.js)
+
+> **When to use:** Next.js projects using Server Actions that want typed, validated,
+> and composable action middleware (auth guards, error handling).
+
+---
+
+# 1. Setup
+
+```ts
+// src/lib/safe-action.ts
+import { createSafeActionClient } from 'next-safe-action'
+
+// Unauthenticated actions
+export const action = createSafeActionClient()
+
+// Authenticated actions — throws if no session
+export const authAction = createSafeActionClient({
+  async middleware() {
+    const user = await getCurrentUser()
+    if (!user) throw new Error('UNAUTHORIZED')
+    return { user }
+  },
+})
+```
+
+---
+
+# 2. Defining an Action
+
+```ts
+// features/users/actions/createUser.action.ts
+'use server'
+import { authAction } from '@/lib/safe-action'
+import { createUserSchema } from '@/features/users/schemas/user.schema'
+
+export const createUserAction = authAction
+  .schema(createUserSchema)
+  .action(async ({ parsedInput: { name, email }, ctx: { user } }) => {
+    // Input already validated by Zod, user already confirmed by middleware
+    const created = await userService.create({ name, email, createdBy: user.id })
+    revalidatePath('/users')
+    return { user: created }
+  })
+```
+
+---
+
+# 3. Rules
+
+- Every server action that touches protected data uses `authAction`, not `action`.
+- Always call `revalidatePath` or `revalidateTag` after mutations that affect cached pages.
+- Actions are entry points — business logic lives in services, not inside `.action()`.
+- Schema validation is automatic — never manually parse `parsedInput`.
+
+---
+
+# 4. Agent Quick Reference
+
+```text
+New server action?           → features/[name]/actions/[name].action.ts
+Public action (no auth)?     → action.schema(schema).action(...)
+Protected action?            → authAction.schema(schema).action(...)
+After mutation?              → revalidatePath('/affected-path')
+Business logic in action?    → move to a service, call from action
+```

package/playbooks/concerns/next-themes.md

@@ -0,0 +1,87 @@
+# next-themes — Dark Mode (Next.js)
+
+> **When to use:** Next.js projects that need system-aware or user-toggled dark mode
+> with Tailwind CSS.
+
+---
+
+# 1. Provider Setup
+
+```tsx
+// src/app/providers.tsx
+'use client'
+import { ThemeProvider } from 'next-themes'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      {children}
+    </ThemeProvider>
+  )
+}
+```
+
+```tsx
+// src/app/layout.tsx
+import { Providers } from './providers'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+---
+
+# 2. Toggle Component
+
+```tsx
+// src/components/ui/ThemeToggle.tsx
+'use client'
+import { useTheme } from 'next-themes'
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme()
+  return (
+    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+      {theme === 'dark' ? 'Light' : 'Dark'}
+    </button>
+  )
+}
+```
+
+---
+
+# 3. Tailwind Config
+
+```ts
+// tailwind.config.ts
+export default {
+  darkMode: 'class', // controlled by next-themes
+}
+```
+
+---
+
+# 4. Rules
+
+- Always add `suppressHydrationWarning` to `<html>` — prevents hydration mismatch on theme read.
+- Use Tailwind `dark:` variants for all dark mode styles — not inline style checks.
+- `defaultTheme: 'system'` is the right default — respects user OS preference.
+
+---
+
+# 5. Agent Quick Reference
+
+```text
+Add dark mode?              → ThemeProvider in app/providers.tsx
+                            → tailwind.config.ts darkMode: 'class'
+Toggle theme?               → useTheme() from next-themes
+Apply dark style?           → Tailwind dark: variant (dark:bg-gray-900)
+Hydration mismatch?         → add suppressHydrationWarning to <html>
+```

package/playbooks/concerns/nuqs.md

@@ -0,0 +1,59 @@
+# nuqs — URL State Management (Next.js)
+
+> **When to use:** Filters, search, pagination, tabs — any state that belongs in the URL
+> so it survives refresh and is shareable via link.
+
+---
+
+# 1. Basic Usage
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger, parseAsString } from 'nuqs'
+
+export function UserFilters() {
+  const [search, setSearch] = useQueryState('search', parseAsString.withDefault(''))
+  const [page, setPage]     = useQueryState('page', parseAsInteger.withDefault(1))
+  const [role, setRole]     = useQueryState('role', parseAsString)
+
+  return (
+    <div>
+      <input value={search} onChange={(e) => setSearch(e.target.value)} />
+      {/* URL auto-updates: /users?search=john&page=2&role=ADMIN */}
+    </div>
+  )
+}
+```
+
+---
+
+# 2. nuqs vs Zustand Decision
+
+```text
+nuqs (URL state):
+  → search queries, pagination (page/limit), active filters,
+     selected tab that should survive refresh, anything shareable via URL
+
+Zustand (memory state):
+  → modal open/close, sidebar state, wizard steps,
+     anything that should reset on page refresh or navigation
+```
+
+---
+
+# 3. Rules
+
+- Use nuqs for anything the user might want to bookmark, share, or return to via back button.
+- Use Zustand for ephemeral UI state that should reset when the user navigates away.
+- Never duplicate URL state in component `useState` — read from `useQueryState` directly.
+
+---
+
+# 4. Agent Quick Reference
+
+```text
+Filter / search / pagination?    → nuqs useQueryState
+Tab that survives refresh?       → nuqs useQueryState
+Modal open state?                → useState (or Zustand if shared)
+State that resets on nav?        → useState or Zustand
+```