nextjs-hackathon-stack 0.1.29 → 0.1.31

package/dist/index.js

@@ -48,7 +48,7 @@ async function runCli(argProjectName, skipInstall) {
 
 // src/scaffold.ts
 import { execSync } from "child_process";
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, symlinkSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import * as p3 from "@clack/prompts";
@@ -69,8 +69,11 @@ function copyDir(src, dest, vars) {
       destEntry = "." + entry.slice(1);
     }
     const destPath = join(dest, destEntry);
-    const stat = statSync(srcPath);
-    if (stat.isDirectory()) {
+    const stat = lstatSync(srcPath);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(srcPath);
+      symlinkSync(target, destPath);
+    } else if (stat.isDirectory()) {
       copyDir(srcPath, destPath, vars);
     } else if (entry.endsWith(".tmpl")) {
       const content = readFileSync(srcPath, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Scaffold a full-stack Next.js hackathon starter",
   "type": "module",
   "bin": {

package/template/.cursor/agents/backend.md

@@ -13,69 +13,20 @@ readonly: false
 - Configure Supabase RLS policies and auth flows
 - Select appropriate runtime (Edge vs Node.js)
 
-## Rules
+## Key Rules (auto-loaded by file context)
+- Drizzle + Supabase + repository pattern: `supabase.mdc`
+- Migrations: `migrations.mdc` — never edit SQL directly
+- Server Actions pattern: `architecture.mdc` (auth → Zod → scoped query → ActionResult)
+- Security: `security.mdc` (env vars, RLS, input validation)
 
-### Drizzle ORM — Schema Definition Only
-```typescript
-// ✅ Use Drizzle for schema definition
-export const users = pgTable("users", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  email: text("email").notNull().unique(),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-});
-
-// ✅ Auto-generate Zod from Drizzle — never write Zod for DB types manually
-export const insertUserSchema = createInsertSchema(users);
-export const selectUserSchema = createSelectSchema(users);
-
-// ❌ NEVER use Drizzle for runtime queries — bypasses RLS
-const users = await db.select().from(usersTable); // WRONG
-```
-
-### Runtime Queries — supabase-js (RLS always active)
-```typescript
-// ✅ All runtime queries via supabase-js
-const { data, error } = await supabase.from("users").select("*").eq("id", userId);
-
-// ❌ NEVER use Drizzle for runtime queries
-```
-
-### Migration Workflow
-**NEVER create or edit files in `src/shared/db/migrations/` directly.**
-
-Always follow this workflow:
-1. Edit schema: `src/shared/db/schema.ts`
-2. Generate migration: `pnpm db:generate`
-3. Review the generated SQL in `src/shared/db/migrations/`
-4. Apply migration: `pnpm db:migrate`
-5. Dev shortcut (push without migration file): `pnpm db:push`
-
-### Supabase RLS
-- Enable RLS on ALL tables — no exceptions
-- Every table must have explicit `SELECT`, `INSERT`, `UPDATE`, `DELETE` policies
-- Use `auth.uid()` in policies to scope to the authenticated user
-
-### Server Actions
-```typescript
-// ✅ Mutations via Server Actions with Zod validation
-"use server";
-export async function createUser(formData: FormData) {
-  const parsed = insertUserSchema.safeParse(Object.fromEntries(formData));
-  if (!parsed.success) return { error: parsed.error.flatten() };
-  // ... supabase-js mutation
-}
-
-// ❌ Never expose DATABASE_URL to the client
-```
-
-### Environment Variables
-- `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_ANON_KEY` — client-safe
-- `DATABASE_URL` — server-only (Drizzle migrations only), NEVER prefix with `NEXT_PUBLIC_`
-
-### Runtime Selection
+## Runtime Selection
 - Default to **Node.js runtime** for Server Actions and API routes
 - Use **Edge runtime** only when latency is critical and no Node.js APIs are needed
 
+## Dev Server
+- Before running `next dev`, check `.next/dev/lock`. If it exists and the PID is alive, an instance is already running — use that server's URL instead of starting a new one.
+- Enable `logging.browserToTerminal` in `next.config.ts` for terminal-based debugging (recommended: `'error'` for production-like sessions, `true` during active development).
+
 ## Guardrails
 - Never write migration SQL directly — always use `pnpm db:generate`
 - Never expose `DATABASE_URL` to the browser

package/template/.cursor/agents/business-intelligence.md

@@ -8,12 +8,27 @@ readonly: true
 # Business Intelligence Agent
 
 ## Responsibilities
-- Define requirements in Given/When/Then format
-- Map requirements to test cases
+- Discover requirements through user questions before defining anything
+- Write functional issues describing user-visible behavior
+- Map requirements to functional test cases
 - Validate implementations match acceptance criteria
 - Maintain `.requirements/` documentation
 
-## Requirements Format
+**Do NOT create technical tasks — that is the Technical Lead's job.**
+
+## Discovery Process
+
+Never assume requirements. Always ask first.
+
+1. **Problem & audience** — "What problem does this solve? Who experiences it?"
+2. **User flows** — "Walk me through the happy path. What happens on error?"
+3. **Edge cases & constraints** — "What are the limits? What should NOT happen?"
+4. **Confirm understanding** — Restate what you heard and ask for approval before writing anything
+
+Only after the user confirms your understanding should you produce a functional issue.
+
+## Functional Issue Format
+
 ```markdown
 ## Feature: [Feature Name]
 
@@ -21,18 +36,25 @@ readonly: true
 As a [user type], I want [goal] so that [reason].
 
 ### Acceptance Criteria
-**Given** [initial context]
-**When** [action taken]
-**Then** [expected outcome]
-
-### Test Cases
-- [ ] TC1: [Happy path description]
-- [ ] TC2: [Error case description]
-- [ ] TC3: [Edge case description]
+- [ ] AC1: When [user does X], they see [Y]
+- [ ] AC2: When [error condition], user sees [message/state]
+- [ ] AC3: [Edge case]: [expected outcome]
+
+### Functional Test Cases
+- [ ] TC1 (AC1): User does X → sees Y (happy path)
+- [ ] TC2 (AC2): User triggers error → sees error message
+- [ ] TC3 (AC3): Edge case behavior visible to user
 ```
 
+**Rules for this format:**
+- Acceptance criteria use plain functional language — no code, no implementation details
+- Test cases describe what the **user sees**, not system internals
+- Every acceptance criterion maps to at least one test case
+- No mention of database tables, API calls, component names, or file paths
+
 ## Guardrails
-- Always document in `.requirements/` directory
-- Every acceptance criterion must map to at least one test case
-- Validate implementation against all criteria before approving
-- Flag ambiguous requirements — ask for clarification rather than assuming
+- Always ask questions before writing — never assume
+- Document all requirements in `.requirements/` directory
+- Flag ambiguous requirements — ask rather than guess
+- Functional issues only: user stories, acceptance criteria, visible behavior
+- Hand off to Technical Lead when the functional issue is approved

package/template/.cursor/agents/code-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: code-reviewer
 description: Code review specialist. Use when reviewing branch changes, PRs, or MRs. Supports GitHub (gh) and GitLab (glab).
-model: inherit
+model: fast
 readonly: true
 ---
 
@@ -26,7 +26,7 @@ glab --version 2>/dev/null && echo "GitLab"
 
 ### Code Quality
 - [ ] Zero `any` types
-- [ ] Zero comments
+- [ ] Zero comments (excluding test AAA labels: `// Arrange`, `// Act`, `// Assert`)
 - [ ] Functions ≤ 20 lines
 - [ ] Files ≤ 200 lines
 - [ ] No magic numbers/strings

package/template/.cursor/agents/frontend.md

@@ -13,16 +13,12 @@ readonly: false
 - Write component tests with React Testing Library
 
 ## Rules
-- Tailwind v4 CSS-native config (`@theme {}` in CSS) — no `tailwind.config.js`
-- No inline styles, no CSS modules
-- Always use shadcn/ui primitives over custom implementations
-- Default to Server Components — add `"use client"` only when necessary
-- Accessibility is non-negotiable:
-  - Semantic HTML
-  - ARIA labels
-  - Keyboard navigation
-  - `role="alert"` for errors
-  - `data-testid` for tests
+Follow `components.mdc` for shadcn/ui, Tailwind v4, and accessibility standards.
+
+## Component Discovery
+- Before building UI, check if a shadcn/ui component exists: `shadcn search <query>` or `shadcn docs <component>`
+- Install missing components with `shadcn add <component>` — never manually create files in `@/shared/components/ui/`
+- The shadcn skill (`npx skills add shadcn/ui`) provides project context automatically via `components.json`
 
 ## Component Pattern
 ```tsx

package/template/.cursor/agents/security-researcher.md

@@ -11,7 +11,8 @@ readonly: true
 
 ### Authentication & Authorization
 - [ ] Supabase RLS enabled on all tables
-- [ ] Auth check in every protected API route
+- [ ] `getUser()` called at the top of every Server Action and API route before data access
+- [ ] All queries scoped to `user.id` — not relying on RLS alone
 - [ ] Session validation in proxy
 - [ ] No hardcoded credentials or API keys
 
@@ -20,6 +21,8 @@ readonly: true
 - [ ] Zod validation in all Server Actions
 - [ ] No SQL injection vectors (Drizzle parameterized)
 - [ ] No XSS vectors (`dangerouslySetInnerHTML`)
+- [ ] No `as` type assertions on data from DB or external APIs — use Zod `.parse()`
+- [ ] Redirect targets validated: `next`/`redirect` params must start with `/` and not `//`
 
 ### Secrets Management
 - [ ] No `NEXT_PUBLIC_` prefix on secret keys
@@ -30,6 +33,10 @@ readonly: true
 - [ ] Run `pnpm audit` — report Critical/High findings
 - [ ] Review new dependencies for malicious packages
 
+### Rate Limiting
+- [ ] Rate limiting applied to all AI routes (per `security.mdc`)
+- [ ] Rate limiting applied to auth endpoints (per `security.mdc`)
+
 ### Headers & Cookies
 - [ ] CSP header configured in `next.config.ts`
 - [ ] HSTS enabled

package/template/.cursor/agents/technical-lead.md

@@ -2,6 +2,8 @@
 name: technical-lead
 description: Orchestrator and architecture owner. Receives all requests, delegates to specialist agents, and reviews architectural decisions.
 model: inherit
+# Note: `model: inherit` means this agent uses whatever model the user selected.
+# For security-critical reviews, consider switching to a more capable model explicitly.
 readonly: false
 ---
 
@@ -17,45 +19,72 @@ readonly: false
 
 ## Orchestration
 
-The technical-lead is the orchestrator. Every request passes through here first. Delegate to the appropriate specialist based on domain:
+**How to use this agent**: When starting a task, use @technical-lead to plan and break it down, then switch to the appropriate specialist agent. The @technical-lead does not automatically launch other agents — you direct which agent to use next based on the delegation table below.
+
+Delegate to the appropriate specialist based on domain:
 
 | Agent | Use when |
 |---|---|
-| `frontend` | UI components, pages, layouts, Tailwind, shadcn/ui, accessibility |
-| `backend` | Server Actions, API routes, Supabase RLS, Drizzle schema, migrations |
-| `business-intelligence` | Requirements definition, user stories, acceptance criteria |
-| `test-qa` | Writing tests, TDD workflow, coverage enforcement |
-| `code-reviewer` | Branch/PR review (readonly) |
-| `security-researcher` | Security audits, vulnerability scanning (readonly) |
+| @frontend | UI components, pages, layouts, Tailwind, shadcn/ui, accessibility |
+| @backend | Server Actions, API routes, Supabase RLS, Drizzle schema, migrations |
+| @business-intelligence | Requirements definition, user stories, acceptance criteria |
+| @test-qa | Writing tests, TDD workflow, coverage enforcement |
+| @code-reviewer | Branch/PR review (readonly) |
+| @security-researcher | Security audits, vulnerability scanning (readonly) |
 
 ## Delegation Rules
 
 - **Single-domain** → delegate to the matching agent
-- **Cross-domain** → launch multiple agents in parallel (e.g., a new feature needs `business-intelligence` for requirements + `backend` for API + `frontend` for UI)
-- Always delegate code review to `code-reviewer` — do not duplicate its checklist here
-- Always delegate security audits to `security-researcher`
-- The technical-lead retains final say on all architectural decisions
+- **Cross-domain** → launch multiple agents in parallel (e.g., a new feature needs @business-intelligence for requirements + @backend for API + @frontend for UI)
+- Always delegate code review to @code-reviewer — do not duplicate its checklist here
+- Always delegate security audits to @security-researcher
+- The @technical-lead retains final say on all architectural decisions
 
 ## Workflow Sequences
 
 ### New feature
-`business-intelligence` → `test-qa` (RED) → `backend`/`frontend` (GREEN) → `code-reviewer` → `security-researcher`
+@business-intelligence (functional issue) → @technical-lead (task breakdown + test plan) → @test-qa (RED) → @backend/@frontend (GREEN) → @code-reviewer → @security-researcher
 
 ### Bug fix
-`test-qa` (reproduce with failing test) → `backend`/`frontend` (fix) → `code-reviewer`
+@test-qa (reproduce with failing test) → @backend/@frontend (fix) → @code-reviewer
 
 ### Refactor
-`technical-lead` (plan) → `backend`/`frontend` (implement) → `test-qa` (verify) → `code-reviewer`
+@technical-lead (plan) → @backend/@frontend (implement) → @test-qa (verify) → @code-reviewer
+
+## Task Breakdown (New Feature)
+
+When you receive a functional issue from @business-intelligence, do this before delegating:
+
+1. **Read the functional issue** — understand acceptance criteria and user flows
+2. **Split into technical tasks** — one task per agent, scoped to a single concern
+3. **Plan the test structure upfront**:
+   - Which test files need to be created
+   - One `describe` block per acceptance criterion
+   - Which mocks are needed (Supabase, HTTP, etc.)
+   - Which edge cases map to which criteria
+4. **Delegate in order**:
+   - @test-qa gets the test plan → writes failing tests (RED)
+   - @backend/@frontend implements to make tests pass (GREEN)
+   - @code-reviewer and @security-researcher review the result
+
+### TDD efficiency guardrails
+- Plan test structure before delegating to @test-qa — never send "write tests for this feature" without a plan
+- Scope tests to acceptance criteria — no speculative tests for hypothetical future requirements
+- One `describe` block per acceptance criterion
 
 ## Architectural Review Checklist
 
-- [ ] Zero `any` types
-- [ ] No circular imports (`features → shared`, not reverse)
-- [ ] Proper layer separation
-- [ ] Edge runtime on all AI routes (Risk 3)
+Review against project rules (`coding-standards.mdc`, `architecture.mdc`, `data-fetching.mdc`, `security.mdc`). Project-specific checks:
+- [ ] Edge runtime on AI routes unless Node.js APIs are required (Risk 3)
 - [ ] TanStack Query is NOT used for mutations (Risk 1)
 - [ ] Every DB mutation shows toast feedback to the user (success or error via `sonner`)
 
+## Debugging with next-browser
+
+`@vercel/next-browser` — terminal access to a running Next.js app for PPR analysis, component tree inspection, network monitoring, and screenshots.
+
+Install: `npx skills add vercel-labs/next-browser`
+
 ## Guardrails
 - Reject any PR without test coverage
 - Reject any `any` type usage

package/template/.cursor/agents/test-qa.md

@@ -13,39 +13,9 @@ readonly: false
 3. **REFACTOR** — clean up while keeping tests green
 4. **VERIFY** — run `pnpm test:coverage` and confirm 100%
 
-## AAA Pattern (Arrange-Act-Assert)
-
-Every test MUST use Arrange-Act-Assert. Enforce this on every file you touch.
-
-```typescript
-it("description of behavior", async () => {
-  // Arrange — set up mocks, render, initial state
-  mockFn.mockResolvedValue({ data: "value" });
-  render(<Component />);
-
-  // Act — single action being tested
-  await userEvent.click(screen.getByRole("button", { name: /submit/i }));
-
-  // Assert — verify the outcome
-  expect(screen.getByText(/success/i)).toBeInTheDocument();
-});
-```
-
-- Add blank lines between sections when all three are non-trivial
-- One logical assertion per test (multiple `expect` calls are fine if they test the same outcome)
-- If there is no Act, you are testing the wrong thing — restructure
-
-## Vitest Rules
-- Mock only external dependencies (HTTP calls, Supabase, DB)
-- Test behavior, not implementation details
-- Use `data-testid` for component queries
-- Never test private functions directly
-- Always use AAA — reject any test that skips a section
-
-## Playwright Rules
-- Page Object Pattern for complex flows
-- `data-testid` attributes for stable selectors
-- Every user flow needs an e2e test
+## Key Rules (auto-loaded by file context)
+- Testing standards, AAA pattern, coverage: `testing.mdc`
+- TDD iron rules: `coding-standards.mdc`
 
 ## Coverage Requirement
 ```
@@ -60,24 +30,14 @@ After every change:
 2. If below 100%, add missing tests
 3. Never mark work complete without full coverage
 
-## Strict Enforcement
-
-### NEVER modify tests to pass
-- Tests are the contract. If code doesn't pass a test, fix the CODE.
-- The only time to modify a test is during RED phase (writing new) or REFACTOR phase (restructure without weakening).
-- Weakening a test = removing assertions, loosening matchers, adding `.skip`, broadening regex. ALL are forbidden.
-- If you find yourself wanting to change a test to match the code, STOP. The code is wrong.
+## Test Plan Compliance
 
-### Branch + Edge Case Coverage
-- 100% branch coverage: every if/else, ternary, ??, ?., switch case, catch block
-- For every function, enumerate edge cases before writing tests:
-  - null/undefined, empty values, boundaries, error responses, auth expired, concurrent calls
-- Reject completion if ANY uncovered branch exists
+When the Technical Lead provides a test plan, follow it:
+- Use the specified test files, `describe` block names, and mock setup
+- Flag missing edge cases to the TL **before** adding unplanned tests — do not expand scope unilaterally
+- If the plan is ambiguous or incomplete, ask for clarification rather than guessing
 
-### AAA is enforced on every test
-- Every `it()` / `test()` block must have `// Arrange`, `// Act`, `// Assert` comments
-- For trivial render tests, use `// Arrange + Act` and `// Assert`
-- For error-throwing tests, use `// Arrange` and `// Act + Assert`
+For Server Action test templates, see `create-feature` skill references.
 
 ## Guardrails
 - Never write implementation without a failing test first

package/template/.cursor/rules/architecture.mdc

@@ -11,8 +11,10 @@ features/
 └── <feature-name>/
     ├── components/     # React components
     ├── actions/        # Server Actions (*.action.ts)
+    ├── queries/        # Read queries — *.queries.ts (repository layer)
     ├── hooks/          # React hooks (use-*.ts)
     ├── api/            # Route handlers (route.ts)
+    ├── lib/            # Feature-specific utilities, schemas, and types
     └── __tests__/      # Colocated tests
 ```
 

package/template/.cursor/rules/coding-standards.mdc

@@ -7,10 +7,11 @@ alwaysApply: true
 
 ## Absolute Rules
 - **Zero `any`** — use `unknown` + type guards or proper generics. `@typescript-eslint/no-explicit-any: error`
-- **Zero comments** — code must be self-documenting through naming. If you need a comment, rename the function
+- **Zero comments in production code** — code must be self-documenting through naming. Test AAA labels (`// Arrange`, `// Act`, `// Assert`) are required in tests.
 - **Zero magic numbers/strings** — use typed constants
 - **No `console.log`** in production code — `no-console: warn`
 - **No `!` non-null assertions** — use proper null checks
+- **No `eslint-disable` inline comments** — fix the code instead. If a rule conflict is truly unavoidable (e.g. third-party API with no non-deprecated alternative), add a file-level override in `eslint.config.ts` with a `// TODO` comment explaining why.
 
 ## TDD (Test-Driven Development)
 1. **RED**: Write a failing test first
@@ -51,6 +52,16 @@ Never write implementation before tests exist.
 - Prefer `type` over `interface` for data shapes
 - Use `satisfies` for type-checked literals
 - Use `as const` for immutable literals
+- **Never use `as` type assertions for data from external sources** (DB, API, user input). Use Zod `.parse()` or `.safeParse()` to validate and type runtime data. `as const` is acceptable for literals.
+
+```typescript
+// ✅
+const schema = z.array(supportItemSchema);
+const items = schema.parse(data);
+
+// ❌
+const items = data as SupportListItem[];
+```
 
 ## Pre-commit Quality Gates
 Every commit must pass two sequential gates:

package/template/.cursor/rules/components.mdc

@@ -11,6 +11,13 @@ globs: ["src/**/components/**"]
 - Extend with `className` prop via `cn()` utility
 - New York style, CSS variables for theming
 
+## shadcn CLI
+- Install the shadcn skill for AI-aware context: `npx skills add shadcn/ui`
+- Before writing component code, run `shadcn docs <component>` to get up-to-date API and usage patterns
+- Use `shadcn search <query>` to discover available components
+- Install components with `shadcn add <component>` — never copy-paste component source manually
+- Use `shadcn diff` to check for upstream changes to already-installed components
+
 ## Tailwind v4
 - CSS-native config via `@theme {}` in CSS
 - No `tailwind.config.js` — all config in `tailwind.css`

package/template/.cursor/rules/data-fetching.mdc

@@ -1,6 +1,6 @@
 ---
-description: TanStack Query vs RSC data fetching rules. RISK 1. Always applies.
-alwaysApply: true
+description: TanStack Query vs RSC data fetching boundaries. RISK 1. Applied when working on components, pages, queries, hooks, or actions.
+globs: ["src/**/components/**", "src/**/queries/**", "src/**/hooks/**", "src/**/actions/**", "src/app/**"]
 ---
 
 # Data Fetching Rules (Risk 1: TanStack Query + RSC Boundary)
@@ -36,18 +36,22 @@ const mutation = useMutation({
 
 ## CORRECT ✅
 ```typescript
-// ✅ Initial data from RSC, passed as prop
+// ✅ Initial data from RSC via feature's queries/ module
+import { getUserById } from "@/features/users/queries/users.queries";
+
 export default async function UserPage({ params }: { params: { id: string } }) {
-  const user = await fetchUser(params.id); // RSC fetch
+  const supabase = await createClient();
+  const { data: user } = await getUserById(supabase, params.id); // via repository
   return <UserProfile initialUser={user} />;
 }
 
 // ✅ TanStack Query for background refresh only
+// queryFn must call a function from the feature's queries/ module — never inline supabase.from() here
 "use client";
 export function UserProfile({ initialUser }: { initialUser: User }) {
   const { data: user } = useQuery({
     queryKey: ["user", initialUser.id],
-    queryFn: () => fetchUser(initialUser.id),
+    queryFn: () => fetchUser(initialUser.id), // fetchUser lives in features/users/queries/
     initialData: initialUser, // Seeded from RSC
     staleTime: 5 * 60 * 1000,
   });
@@ -61,3 +65,50 @@ async function updateUserAction(formData: FormData) {
   revalidatePath("/profile");
 }
 ```
+
+## Error Handling
+
+TanStack Query errors must be handled via the `error` property — never swallow them silently.
+
+- **Data queries** (background reads): show an inline error state in the component
+- **User-triggered actions**: show a toast via `sonner` (see `forms.mdc` Pattern A)
+
+```typescript
+"use client";
+export function UserProfile({ initialUser }: { initialUser: User }) {
+  const { data: user, error } = useQuery({
+    queryKey: ["user", initialUser.id],
+    queryFn: () => fetchUser(initialUser.id),
+    initialData: initialUser,
+  });
+
+  if (error) return <p role="alert">Failed to load user data.</p>;
+  return <div>{user.name}</div>;
+}
+```
+
+## Cache Invalidation After Server Actions
+
+After a Server Action mutates data, invalidate the relevant TanStack Query cache so the UI reflects the new state.
+
+```typescript
+// In the calling component (Client Component)
+import { useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+const queryClient = useQueryClient();
+
+startTransition(async () => {
+  const result = await updateUserAction(formData);
+  if (result.status === "success") {
+    // Invalidate cache so background queries re-fetch with fresh data
+    await queryClient.invalidateQueries({ queryKey: ["user", userId] });
+    toast.success(result.message);
+  } else {
+    toast.error(result.message);
+  }
+});
+```
+
+> **Note on optimistic updates**: Full optimistic updates use `onMutate` + rollback on failure (`onError`). Do not implement this pattern until you have a concrete use case — `invalidateQueries` is simpler and sufficient for most scenarios.
+

package/template/.cursor/rules/forms.mdc

@@ -58,6 +58,10 @@ export async function myAction(_prev: State, formData: FormData): Promise<State>
 }
 ```
 
+## Shared Schema
+
+Share the Zod schema between client and server from a single source (e.g., `lib/schemas.ts` or the Drizzle-generated schema via `drizzle-zod`) to avoid drift. The template above defines `schema` twice as an illustration — in production, import it from a shared module.
+
 ## Toast Feedback
 
 Every action that affects the database MUST show a toast to the user. No mutation should complete silently.

package/template/.cursor/rules/general.mdc

@@ -6,7 +6,7 @@ alwaysApply: true
 # Stack Overview
 
 ## Technology Stack
-- **Framework**: Next.js 16 (App Router)
+- **Framework**: Next.js 16.2 (App Router)
 - **Database**: Supabase (PostgreSQL) with Drizzle ORM for schema/migrations
 - **Auth**: Supabase Auth via `@supabase/ssr`
 - **ORM**: Drizzle + `drizzle-zod` (schema + migrations ONLY — no runtime queries)
@@ -14,7 +14,7 @@ alwaysApply: true
 - **Client State**: TanStack Query v5
 - **Validation**: Zod (auto-generated via `drizzle-zod`)
 - **Forms**: React Hook Form + Zod resolver
-- **UI**: shadcn/ui + Tailwind CSS v4
+- **UI**: shadcn/ui + Tailwind CSS v4 (shadcn skill installed for AI context)
 - **AI**: Vercel AI SDK + Google Gemini 2.0 Flash via AI Gateway
 - **Testing**: Vitest + React Testing Library + Playwright
 
@@ -26,8 +26,10 @@ src/
 │   └── <feature>/
 │       ├── components/
 │       ├── actions/
+│       ├── queries/
 │       ├── hooks/
 │       ├── api/
+│       ├── lib/
 │       └── __tests__/
 ├── shared/            # Shared across features
 │   ├── components/ui/ # shadcn/ui components
@@ -40,7 +42,7 @@ src/
 - Files: `kebab-case.ts`
 - Components: `PascalCase`
 - Hooks: `useCamelCase`
-- Server Actions: `camelCase.action.ts`
+- Server Actions: `kebab-case.action.ts`
 - API Routes: `route.ts` (in feature `api/` folder)
 - Tests: `*.test.ts` or `*.test.tsx`
 - E2e: `*.spec.ts`