@stonepandastudio/cairn 0.4.2 → 0.6.0

package/presets/nestjs/slots/review-checklist.md

@@ -0,0 +1,12 @@
+<!-- cairn preset: nestjs — fills {{> stack/review-checklist }} in the core reviewer.
+     Framework rules only. A repo on `--stack nestjs,typeorm` also gets the ORM
+     rows from presets/typeorm/slots/review-checklist.md (the renderer concatenates
+     this slot from every stack entry). Response-mapping and validation-decorator
+     rows come from the chosen validation-stack variant, not here. -->
+
+| No `any` type — use proper TypeScript types | All changed files |
+| Enums in `enums/` folder, constants in `constants/` folder, kebab-case filenames | Feature module |
+| No magic strings — use enum values or named constants | Anywhere |
+| API modules contain no business logic (thin controllers, delegate to feature services) | Controller / API service files |
+| Feature modules export only the services that API modules need | Module files |
+| NestJS built-in exceptions used for errors (`NotFoundException`, `BadRequestException`, …) | Service and controller files |

package/presets/nestjs/variants/validation-class-validator.md

@@ -0,0 +1,120 @@
+<!-- cairn variant: validation-stack = class-validator. Fills the dto-naming,
+     dto-definition, validation-stack, controller-response,
+     response-transformation and pagination-dtos slots in
+     presets/node/code-guidelines.md.
+     In use by: snap-backend. Requires `class-validator` + `class-transformer`
+     and the project's own `@ResponseMapper` decorator. -->
+
+## slot: dto-naming
+
+* Use operation-prefixed names for incoming request data:
+    - `CreateProjectDto`, `UpdateUserDto`
+    - File: `create-feature.dto.ts`, `update-feature.dto.ts`
+* Use the `Response` suffix for server response shapes:
+    - `UserResponse`, `ProjectListResponse`
+    - File: `feature-response.dto.ts`
+
+## slot: dto-definition
+
+* Use class-validator decorators: `@IsString()`, `@IsNumber()`, `@IsEmail()`, `@IsOptional()`, `@IsNotEmpty()`
+* Use class-transformer decorators: `@Type()`, `@Exclude()`, `@Expose()`
+* Add Swagger documentation: `@ApiProperty()`, `@ApiPropertyOptional()`
+* Provide validation error messages where appropriate
+
+## slot: validation-stack
+
+* Use class-validator decorators on all DTO properties
+* Use `ValidationPipe` globally or per-controller
+* Create custom validators for complex validation logic
+
+## slot: controller-response
+
+* Apply `@UsePipes(ValidationPipe)` for automatic DTO validation
+* Annotate the response shape with `@ResponseMapper(ResponseDtoClass)` on every endpoint that returns data
+
+## slot: response-transformation
+
+**IMPORTANT**: The `@ResponseMapper(ResponseDtoClass)` decorator automatically handles entity-to-DTO transformation using class-transformer.
+
+**How it works**:
+* The decorator uses `@Expose()` decorators in the response DTO to pick which fields to include
+* The decorator uses `@Type()` decorators to handle nested object transformations
+* You **DO NOT** need to manually create mapper functions to pick fields
+
+**Best Practices**:
+* Return entities or plain objects from service methods
+* Only perform minimal transformations needed for data structure (e.g., flattening nested properties)
+* Let `@ResponseMapper` handle field selection and type transformation
+* Do **NOT** create separate mapper functions just to pick fields - the decorator does this automatically
+
+**Example - Correct approach**:
+```typescript
+// Service method - minimal transformation
+async getDevicesByProjects() {
+  const devices = await this.siteDeviceService.getDevicesByProjects();
+
+  // Only flatten nested structures that don't match DTO
+  return devices.map(device => ({
+    ...device,
+    site: device.site ? {
+      ...device.site,
+      city: device.site.city?.name || null  // Flatten CityEntity to string
+    } : null,
+  }));
+}
+
+// Controller - @ResponseMapper handles field picking
+@Get('by-projects')
+@ResponseMapper(DeviceWithProjectsResponse)
+async getDevicesByProjects(@Query() query: QueryDto) {
+  return this.service.getDevicesByProjects(query);
+}
+
+// Response DTO - @Expose() picks fields automatically
+export class DeviceWithProjectsResponse {
+  @Expose() id: string;
+  @Expose() description: string;
+  // Only exposed fields will be returned
+}
+```
+
+**Example - Incorrect approach** (avoid this):
+```typescript
+// ❌ DON'T create mapper functions just to pick fields
+function mapToResponse(device) {
+  return {
+    id: device.id,              // @ResponseMapper does this
+    description: device.description,  // automatically
+  };
+}
+```
+
+## slot: pagination-dtos
+
+**Query params** — declare `page` and `pageSize` with `@Type(() => Number)` so query strings coerce:
+
+```typescript
+export class FooListQuery {
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page = 1;
+
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  pageSize = 50;
+}
+```
+
+**Response DTO** — expose the envelope fields and type the items:
+
+```typescript
+export class FooListResponse {
+  @Expose() @Type(() => FooResponse) items: FooResponse[];
+  @Expose() total: number;
+  @Expose() skip: number;
+  @Expose() take: number;
+}
+```

package/presets/nestjs/variants/validation-zod.md

@@ -0,0 +1,194 @@
+<!-- cairn variant: validation-stack = zod. Fills the dto-naming, dto-definition,
+     validation-stack, controller-response, response-transformation and
+     pagination-dtos slots in presets/node/code-guidelines.md.
+     In use by: glossr-api. Requires `zod` + `nestjs-zod`. -->
+
+## slot: dto-naming
+
+* Use **`Payload` prefix** for incoming request data (body, query params):
+    - `RegisterOwnerPayload`, `CreateProjectPayload`, `UpdateUserPayload`
+    - File: `register-owner-payload.dto.ts`
+* Use **`Response` prefix** for server response shapes:
+    - `RegisterOwnerResponse`, `UserResponse`, `ProjectListResponse`
+    - File: `register-owner-response.dto.ts`
+
+**Examples**:
+```typescript
+// Request DTO
+export class RegisterOwnerPayload extends createZodDto(RegisterOwnerSchema) {}
+
+// Response DTO
+export class RegisterOwnerResponse extends createZodDto(RegisterOwnerResponseSchema) {}
+```
+
+## slot: dto-definition
+
+* Use **Zod schemas** with `nestjs-zod` integration: `z.string()`, `z.number()`, `z.email()`, `z.optional()`, etc.
+* Create DTOs by extending `createZodDto()` from Zod schemas
+* Add Swagger documentation via Zod schema metadata or `@ApiProperty()` decorators
+* Provide validation error messages in Zod schema definitions
+
+**Example**:
+```typescript
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email('Invalid email format'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+  name: z.string().min(1, 'Name is required'),
+});
+
+export class CreateUserDto extends createZodDto(CreateUserSchema) {}
+```
+
+## slot: validation-stack
+
+* Use **Zod schemas** for all DTO validation
+* Use `ZodValidationPipe` (from `nestjs-zod`) globally or per-controller
+* Create custom Zod schemas for complex validation logic
+* Provide clear, user-friendly validation error messages in schema definitions
+
+## slot: controller-response
+
+* **ALWAYS** use `@ZodResponse({ type: MyResponse })` on every endpoint that returns data — do NOT add explicit TypeScript return types when using `@ZodResponse` as it infers them
+
+**`@ZodResponse` rules:**
+* Replaces `@ZodSerializerDto`, `@ApiResponse`, and the return type annotation in one decorator
+* Keeps run-time serialization, compile-time types, and OpenAPI docs in sync
+* For arrays use `[MyDto]` syntax: `@ZodResponse({ type: [UserResponse] })`
+* For non-200 status codes: `@ZodResponse({ status: 201, type: MyResponse })`
+* For endpoints returning `void` (e.g. DELETE), omit `@ZodResponse`
+* For endpoints returning raw streams/files (using `@Res()`), omit `@ZodResponse`
+
+**Example**:
+```typescript
+import { ZodResponse } from 'nestjs-zod';
+
+@Controller('users')
+export class UserController {
+  @Get('me')
+  @UseGuards(JwtAuthGuard)
+  @ZodResponse({ type: UserResponse })
+  async getMe(@CurrentUser('sub') userId: string) {
+    return this.userService.findById(userId);
+  }
+
+  @Get()
+  @ZodResponse({ type: [UserResponse] })
+  async listUsers() {
+    return this.userService.findAll();
+  }
+
+  @Post()
+  @ZodResponse({ status: 201, type: UserResponse })
+  async createUser(@Body() dto: CreateUserPayload) {
+    return this.userService.create(dto);
+  }
+
+  @Delete(':id')
+  // No @ZodResponse — returns void
+  async deleteUser(@Param('id') id: string): Promise<void> {
+    await this.userService.delete(id);
+  }
+}
+```
+
+## slot: response-transformation
+
+**IMPORTANT**: Use Zod schemas for response DTOs to automatically handle entity-to-DTO transformation with type safety.
+
+**How it works**:
+* Response DTOs extend `createZodDto()` from Zod schemas
+* Zod schemas pick which fields to include in the response
+* Automatic type inference from Zod schemas
+* Built-in serialization support via `nestjs-zod`
+
+**Best Practices**:
+* Return entities or plain objects from service methods
+* Define response DTOs as separate Zod schemas
+* Only perform minimal transformations needed for data structure (e.g., flattening nested properties)
+* Let Zod handle field selection and type transformation
+* Do **NOT** create separate mapper functions just to pick fields
+
+**Example - Correct approach**:
+```typescript
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+
+// Response schema - pick fields that should be returned
+const DeviceWithProjectsSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  site: z.object({
+    id: z.string(),
+    name: z.string(),
+    city: z.string().nullable(),
+  }).nullable(),
+});
+
+export class DeviceWithProjectsResponse extends createZodDto(DeviceWithProjectsSchema) {}
+
+// Service method - minimal transformation
+async getDevicesByProjects() {
+  const devices = await this.siteDeviceService.getDevicesByProjects();
+
+  // Only flatten nested structures that don't match schema
+  return devices.map(device => ({
+    ...device,
+    site: device.site ? {
+      ...device.site,
+      city: device.site.city?.name || null  // Flatten CityEntity to string
+    } : null,
+  }));
+}
+```
+
+**Example - Incorrect approach** (avoid this):
+```typescript
+// ❌ DON'T create mapper functions just to pick fields
+function mapToResponse(device) {
+  return {
+    id: device.id,              // The Zod schema does this automatically
+    description: device.description,
+  };
+}
+```
+
+## slot: pagination-dtos
+
+**Query params** — always `page` + `pageSize` with `z.coerce.number()` (coercion required because query params arrive as strings):
+
+```typescript
+// src/api/modules/fooApi/dtos/foo-list-query.dto.ts
+const FooListQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(50),
+  // add sorting / filter fields as needed
+});
+
+export class FooListQuery extends createZodDto(FooListQuerySchema) {}
+```
+
+**Response DTO** — wrap the item schema with `paginatedResponseSchema`:
+
+```typescript
+// src/api/modules/fooApi/dtos/foo-list-response.dto.ts
+import { createZodDto } from 'nestjs-zod';
+import { paginatedResponseSchema } from '@common/dtos/paginated-response.schema';
+import { FooResponseSchema } from './foo-response.dto';
+
+const FooListResponseSchema = paginatedResponseSchema(FooResponseSchema);
+
+export class FooListResponse extends createZodDto(FooListResponseSchema) {}
+```
+
+**Controller**:
+
+```typescript
+@Get()
+@ZodResponse({ type: FooListResponse })
+async list(@Query() query: FooListQuery) {
+  return this.fooService.list(query);
+}
+```

package/presets/nextjs/code-guidelines.md

@@ -0,0 +1,45 @@
+# Next.js Guidelines
+
+<!-- cairn preset: nextjs. The App-Router framework layer, added on top of the
+     `react` component base: `--stack nextjs,react,tailwind,drizzle`. It owns the
+     server/client boundary, Server Actions, Route Handlers, and the App-Router
+     file conventions — not component/hook/state basics, which stay in
+     `presets/react`. Seeded 2026-09-09 from charityiq-app (Next.js 16, Sprint 0).
+     Single consumer; refine when a second Next.js repo appears. -->
+
+## The framework moves fast
+
+Next.js's App Router, `"use cache"`, and the RSC model change between minor
+versions and are often ahead of training data. Before writing anything non-obvious,
+check `node_modules/next/dist/**` or the version's docs. Heed deprecation notices.
+
+## Server / Client boundary
+
+* **Server Components by default.** Add `"use client"` only for interactivity, browser APIs, or hooks (`useState`, `useEffect`, event handlers).
+* A `"use client"` module must not import server-only code — DB clients, secrets, anything marked `server-only`. Push the client boundary as far down the tree as possible; a page can be a Server Component that renders a small client island.
+* Never read a secret in a Client Component. Client-exposed env vars carry the `NEXT_PUBLIC_` prefix; everything else is server-only.
+
+## Server Actions
+
+* `'use server'` at the top of the module (or the function). Actions run on the server; treat every argument as untrusted input and validate it.
+* An action is a mutation entry point — it does the whole unit of work (validate → authorize → mutate → revalidate) and returns a serializable result.
+* Call `revalidatePath` / `revalidateTag` after a write so the RSC cache reflects it.
+* Do not use an action as a generic RPC for reads — read in the Server Component.
+
+## Route Handlers
+
+* `app/**/route.ts` for webhooks, third-party callbacks, and non-action HTTP (file downloads, health checks).
+* Verify the caller (signature, secret, or auth) before doing any work.
+* Keep them thin — parse, authorize, delegate to a service, respond.
+
+## App Router structure
+
+* `page.tsx` / `layout.tsx` / `loading.tsx` / `error.tsx` / `not-found.tsx` per segment; route groups `(name)/` for layout scoping without a URL segment; `[param]` / `[...slug]` for dynamic routes.
+* Colocate a segment's server code (`actions.ts`, `queries.ts`) inside its folder.
+* `Metadata` export (static or `generateMetadata`) on every routable page for SEO.
+* `next/font` for fonts, `next/image` for images — never a raw `<img>` for content images or a `<link>` font.
+
+## Data fetching
+
+* Fetch in Server Components and Server Actions, not in client `useEffect`.
+* Reach for the framework's caching primitives (`fetch` cache options, `revalidate`, `unstable_cache` / `"use cache"` where stable) rather than a bespoke client cache.

package/presets/nextjs/slots/architect-discussion-topics.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: nextjs — appended to the architect-discussion-topics slot on a
+     `--stack nextjs,react,...` repo. -->
+- **Server vs client** — does this segment need interactivity, or can it stay a Server Component
+- **Action vs Route Handler** — a user-triggered mutation (action) or an external/webhook entry point (handler)
+- **Cache / revalidation** — what has to be re-fetched after this write, and how it's tagged

package/presets/nextjs/slots/architect-mandatory-docs.md

@@ -0,0 +1,3 @@
+<!-- cairn preset: nextjs — appended to the architect-mandatory-docs slot on a
+     `--stack nextjs,react,...` repo. -->
+- `ai/infrastructure/project-structure.md` — the App Router layout and where server code lives

package/presets/nextjs/slots/architect-references.md

@@ -0,0 +1,6 @@
+<!-- cairn preset: nextjs — fills {{> stack/architect-references }} (A.1).
+     Primary-stack-only. This is a fullstack repo — one place holds both the UI
+     and the server code. -->
+- The App Router tree (`app/`) — pages, layouts, colocated `actions.ts` / `queries.ts`
+- Shared server modules (`lib/`) — DB, auth, integrations, the AI client
+- Context docs in `ai/contexts/**` — entities, features, page/flow business logic

package/presets/nextjs/slots/implementation-reference.md

@@ -0,0 +1,24 @@
+<!-- cairn preset: nextjs — appended to the implementation-reference slot on a
+     `--stack nextjs,react,...` repo. -->
+
+### Server / Client
+- Default Server Component; `"use client"` at the smallest island that needs it
+- Client boundary never pulls in DB clients, secrets, or `server-only` modules
+- Pass data down as props from the Server Component; don't refetch on the client
+
+### Server Actions
+- `'use server'`; validate args; do the whole unit of work (authorize → mutate → revalidate)
+- `revalidatePath` / `revalidateTag` after a write; return a serializable result
+- Colocate as `app/<segment>/actions.ts`
+
+### Route Handlers
+- `app/**/route.ts` for webhooks and non-action HTTP; verify the caller first; keep thin
+
+### App Router
+- `page` / `layout` / `loading` / `error` / `not-found` per segment
+- Route groups `(name)/`, dynamic `[param]` / `[...slug]`
+- `Metadata` / `generateMetadata` on every routable page
+- `next/font`, `next/image` — no raw `<img>` / `<link>` font
+
+### Data
+- Fetch in RSC / Actions; use framework cache primitives, not a client cache

package/presets/nextjs/slots/key-patterns.md

@@ -0,0 +1,8 @@
+<!-- cairn preset: nextjs — appended to the key-patterns slot on a
+     `--stack nextjs,react,...` repo. -->
+
+App Router structure, the server/client boundary, Server Action and Route Handler
+conventions: **`ai/infrastructure/code-guidelines.md`** § Next.js.
+
+Existing routes and their layouts: **`app/`** — mirror the nearest segment's shape
+(colocated `actions.ts` / `queries.ts`, `loading` / `error` files) before adding one.

package/presets/nextjs/slots/plan-step-ordering.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: nextjs — fills {{> stack/plan-step-ordering }} in the core
+     architect's Plan format. Primary-stack-only. Put `nextjs` first in `--stack`
+     so this fullstack ordering wins over the plain-react one. -->
+1. Types / schema / DB migration
+2. Server modules — queries, integrations, `lib/` helpers
+3. Server Actions / Route Handlers
+4. Server Components — pages, layouts, data loading
+5. Client islands — interactive components
+6. Styling and responsive / dark-mode passes
+7. Tests — Vitest units, then a Playwright flow
+8. Context doc updates

package/presets/nextjs/slots/review-checklist.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: nextjs — appended to the review-checklist slot on a
+     `--stack nextjs,react,...` repo. Framework-boundary rules only. -->
+
+| Server Component by default — `"use client"` only for interactivity / browser APIs / hooks | component `.tsx` |
+| `"use client"` module imports no server-only code (DB client, secrets, `server-only`) | client components |
+| No secret read in a Client Component; client env vars are `NEXT_PUBLIC_`-prefixed | `.tsx`, env usage |
+| Server Action starts with `'use server'` and validates every argument as untrusted | `actions.ts` |
+| Server Action calls `revalidatePath` / `revalidateTag` after a write | `actions.ts` |
+| Route Handler verifies the caller before any work | `app/**/route.ts` |
+| Data fetched in a Server Component / Action, not a client `useEffect` | component / hook files |
+| Routable page exports `Metadata`; content images use `next/image`, fonts use `next/font` | `page.tsx`, `layout.tsx` |

package/presets/react/code-guidelines.md

@@ -0,0 +1,46 @@
+# React Guidelines
+
+<!-- cairn preset: react. The frontend framework spine for a React app — Vite SPA
+     or the client layer of a Next.js app. Seeded 2026-09-09 from charityiq-app
+     (Sprint 0: CLAUDE.md conventions + ADR 0001, no component code yet). Single
+     consumer; refine when a second React repo appears.
+
+     What is NOT here: RSC, Server Actions, route handlers, the App Router. Those
+     are Next.js-specific — a `presets/nextjs` composes on top (`--stack
+     nextjs,drizzle`) if the repo stays Next.js. If it splits into a NestJS API +
+     a React SPA, this preset pairs with `presets/nestjs` (`--stack
+     nestjs,react,typeorm` on the API side is nonsense — each repo has its own
+     stack). The styling system is a separate add-on (`presets/tailwind`); this
+     preset is styling-agnostic. -->
+
+## Components
+
+* Function components only. One component per file, named after the file.
+* Group by role: `components/ui/` (primitives), `components/feature/` (domain), `components/brand/` (marketing/identity).
+* Props typed with an explicit `interface` or `type`; no `any` without a comment saying why.
+* Derive, don't duplicate — compute from props/state in render, not in an effect.
+
+## State
+
+* **No `localStorage` or `sessionStorage`.** Persistent state lives server-side; per-session state lives in signed cookies. Client caches that survive a reload leak data across users on shared devices.
+* Local UI state via `useState` / `useReducer`. Cross-tree state via context, kept small.
+* Server state via a query library (or RSC) — not hand-rolled fetch-in-effect.
+
+## Styling
+
+* Framework-agnostic — the styling system is a composable add-on. For Tailwind, see
+  `presets/tailwind` (`--stack react,tailwind`). The one rule that holds regardless:
+  no hard-coded colours in components; go through whatever token layer the styling
+  preset defines.
+
+## Tests
+
+* Unit: **Vitest** + jsdom + Testing Library, in `tests/unit/`. Test behaviour, not implementation.
+* HTTP mocks: **MSW**.
+* End-to-end: **Playwright**, in `tests/e2e/`.
+
+## Tooling
+
+* TypeScript strict.
+* **Biome** for formatting (tabs, double quotes) and import organisation; ESLint for lint rules Biome does not cover.
+* Path alias `@/*` → repo root.

package/presets/react/slots/architect-discussion-topics.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: react — fills {{> stack/architect-discussion-topics }} (A.3). -->
+- **Ambiguities** — anything in the description that admits multiple reasonable interpretations
+- **UX / layout tradeoffs** — modal vs. page, tabs vs. stacked sections, inline vs. separate view
+- **Component boundary** — extend an existing `ui/`/`feature/` component vs. add a new one
+- **State placement** — local, context, or server

package/presets/react/slots/architect-references.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: react — fills {{> stack/architect-references }} (A.1).
+     Primary-stack-only, not concatenated. -->
+- Frontend source — components, hooks, the app shell
+- The API's context docs, if the task touches a request/response shape the frontend consumes
+- The API source, for shape confirmation

package/presets/react/slots/implementation-reference.md

@@ -0,0 +1,26 @@
+<!-- cairn preset: react — fills {{> stack/implementation-reference }} in the core
+     developer. -->
+
+### Components
+- Function component per file; props via an explicit `interface`
+- Folder by role: `components/{ui,feature,brand}/`
+- Compose small primitives; lift state only as far as it is shared
+
+### Hooks
+- Custom hooks in `hooks/` (or colocated), prefixed `use`
+- One concern per hook; return a stable shape
+- Effects only for genuine side effects (subscriptions, imperative DOM) — not to mirror props into state
+
+### Styling
+- Whatever the styling add-on defines (`presets/tailwind` for Tailwind repos)
+- The constant: no inline hex in components, responsive and dark mode handled at the token layer
+
+### Data
+- Server state through a query library (or RSC where the framework provides it)
+- No `localStorage` / `sessionStorage`
+- Loading and error states are explicit, not implicit
+
+### Tests
+- `tests/unit/*.test.tsx` — Vitest + Testing Library, behaviour-first
+- MSW for any HTTP the component makes
+- `tests/e2e/*.spec.ts` — Playwright for the whole flow

package/presets/react/slots/key-patterns.md

@@ -0,0 +1,8 @@
+<!-- cairn preset: react — fills {{> stack/key-patterns }} in the core architect
+     and developer. -->
+
+Component and folder conventions, state rules, test wiring:
+**`ai/infrastructure/code-guidelines.md`** § React.
+
+Reusable primitives and domain components already built: **`components/`** — check
+`ui/` and `feature/` for an analog before adding a new one.

package/presets/react/slots/plan-step-ordering.md

@@ -0,0 +1,9 @@
+<!-- cairn preset: react — fills {{> stack/plan-step-ordering }} in the core
+     architect's Plan format. Primary-stack-only, not concatenated. -->
+1. Types / models / API client methods
+2. Hooks and state
+3. Components (`ui/` primitives first, then `feature/`)
+4. Wiring — routes, layout, data loading
+5. Styling (per the styling add-on) — responsive and dark-mode passes
+6. Tests — Vitest units, then a Playwright flow
+7. Context doc updates

package/presets/react/slots/review-checklist.md

@@ -0,0 +1,10 @@
+<!-- cairn preset: react — fills {{> stack/review-checklist }} in the core reviewer.
+     Concatenated with any other stack entry's slot. -->
+
+| Function components, one per file, typed props (no bare `any`) | component `.tsx` files |
+| Component in the right folder — `ui/` primitive, `feature/` domain, `brand/` identity | `components/` |
+| No `localStorage` / `sessionStorage` | any client code |
+| No fetch-in-`useEffect` for server state — a query library or RSC | component / hook files |
+| No hard-coded colours in components — go through the styling preset's token layer | `.tsx` |
+| Derived values computed in render, not synced via an effect | component `.tsx` |
+| New behaviour has a Vitest test; user-visible flow has a Playwright spec | `tests/unit/`, `tests/e2e/` |

package/presets/tailwind/code-guidelines.md

@@ -0,0 +1,28 @@
+# Tailwind Guidelines
+
+<!-- cairn preset: tailwind. The styling add-on — orthogonal to the framework, the
+     way an ORM add-on is. Compose it: `--stack nextjs,tailwind,drizzle`,
+     `--stack react,tailwind`. Seeded 2026-09-09 from charityiq-app (Tailwind v4).
+     Single consumer; refine when a second Tailwind repo appears.
+
+     Not in it: the repo's actual brand token values and font choice — those are
+     project-owned (charityiq's `app/globals.css` holds `coral`/`ink`/`paper` and
+     Geist). This preset says *where* tokens go and *how* to consume them. -->
+
+## Tokens
+
+* Design tokens live in a `@theme` block in the app's global stylesheet (Tailwind v4). **Never create a `tailwind.config.ts`** — Tailwind v4 ignores it.
+* Semantic tokens (`--color-background`, `--color-foreground`) map to raw brand tokens; components use the semantic ones.
+* Dark mode via `@media (prefers-color-scheme: dark)` re-mapping the semantic tokens — not a `dark:` variant on every element.
+
+## Usage
+
+* Consume tokens through the standard utility names Tailwind generates (`bg-coral`, `text-ink`, `font-sans`). No raw hex, `rgb()`, or CSS custom properties in component markup.
+* Utility classes in the markup; reach for `@apply` only for a genuinely repeated cluster, in a component-scoped stylesheet.
+* Responsive with Tailwind's breakpoint prefixes; do not hand-write media queries for layout.
+* Class order left to the formatter (Biome / Prettier plugin) — do not hand-sort.
+
+## Structure
+
+* One global stylesheet for tokens and base layer; everything else is utilities in components.
+* No global element selectors beyond a minimal base (`body`, `:root`).

package/presets/tailwind/slots/implementation-reference.md

@@ -0,0 +1,8 @@
+<!-- cairn preset: tailwind — appended to the framework preset's
+     implementation-reference slot on `--stack <framework>,tailwind`. -->
+
+### Styling
+- Tailwind v4 utilities in the markup; tokens from the `@theme` block
+- Semantic tokens (`background`/`foreground`) in components; raw brand tokens only in `@theme`
+- Responsive via breakpoint prefixes (`md:`, `lg:`); dark mode via `prefers-color-scheme` token re-mapping
+- No `tailwind.config.ts`, no inline hex, no per-element `dark:` sprawl

package/presets/tailwind/slots/key-patterns.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: tailwind — appended to the framework preset's key-patterns slot
+     on `--stack <framework>,tailwind`. -->
+
+Design tokens and the base layer: the app's global stylesheet `@theme` block.
+Token names and dark-mode mapping conventions: **`ai/infrastructure/code-guidelines.md`** § Tailwind.

package/presets/tailwind/slots/review-checklist.md

@@ -0,0 +1,8 @@
+<!-- cairn preset: tailwind — appended to the framework preset's review-checklist
+     slot on `--stack <framework>,tailwind`. -->
+
+| No raw hex / `rgb()` / CSS custom properties in markup — only token utilities (`bg-coral`, `text-ink`) | `.tsx` / `.html` |
+| No `tailwind.config.ts` — tokens live in a `@theme` block in the global stylesheet | project root |
+| Dark mode via re-mapped semantic tokens, not `dark:` on every element | global stylesheet |
+| `@apply` only for a genuinely repeated cluster, component-scoped — not scattered | component stylesheets |
+| No hand-written layout media queries — Tailwind breakpoint prefixes | `.tsx` / `.html` |