@bonesofspring/ai-rules 0.2.30 → 0.2.32

package/presets/cursor/next/ai-local/rules-library/agent-pipeline-gates.md

@@ -0,0 +1,19 @@
+glob: always
+
+## Body
+
+# Agent pipeline gates (local overlay)
+
+These gates are **agent-enforced** (local rules; the preset hook/router is not edited). Treat them as MUST, not advisory. Acknowledge: `Using .ai.local: agent-pipeline-gates(, …)*`.
+
+## Gates
+
+- **UI scope** (`app/src/ui/**`): the pipeline MUST include `mockup-reviewer` — not only when a `figma.com` URL is present. A terminal `mockup-review.md` with verdict `PASS`/`PASS_WITH_NOTES` is required before the task is complete. Missing artifact = **blocked**, not a warning. (See `ui-change-review-gate`.)
+- **DTO/type scope**: `api-contract-reviewer` is blocking per `api-contract-source`.
+- **build-verifier**: when `storybook/**` or `app/src/ui/**` changed, run targeted storybook tests and require green **without** `--update`.
+- **code-reviewer**: (a) a behaviour change under `app/src/**` without a matching `docs/qa/**` or `*.cases.md` update → WARN (REQUEST_CHANGES when AC names the case); (b) a production behaviour change made to satisfy a test → **blocker**; (c) every review artifact states the reviewed revision (sha or `working tree @ <date>`).
+- **single writer**: do not rewrite a block shipped the same day without a new review artifact and an owner.
+
+## Why local, not preset
+
+The mechanical hook/router gate would live in the preset-managed hook + router, which `init` overwrites. Per project decision, all gate changes stay in `.ai.local` (agent-enforced).

package/presets/cursor/next/ai-local/rules-library/analytics-events.md

@@ -0,0 +1,18 @@
+globs: app/src/analytics/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# Analytics / telemetry events (team conventions template)
+
+When emitting or changing an analytics/telemetry event, acknowledge: `Using .ai.local: analytics-events(, …)*`.
+
+Events go through one owned module per domain — not scattered `pushEvent` / `track` calls in components.
+
+## Rules
+
+- Event modules live under `app/src/analytics/events/<domain>/` and expose `logX(...)` functions wrapping the analytics client (`pushEvent` or repo equivalent); payload types live in a sibling `*.types.ts`.
+- Components emit events via a hook or store slice (`_complexSlices/Analytics` analog), not by importing the analytics client directly.
+- Respect the repo's gating flag (e.g. `NEXT_PUBLIC_*_ANALYTICS_DISABLED`) and the init in the app root; do not initialize adapters twice.
+- Deduplicate repeated events with the repo's cache idiom when it exists.
+- **Never** put PD, medical/record text, raw auth tokens, or full URL search params into a payload. See the security rule's compliance section.
+- Analytics is a side effect: cross-slice event emission belongs in listener middleware, not in a reducer (see `store-rtk`).

package/presets/cursor/next/ai-local/rules-library/api-contract-source.md

@@ -0,0 +1,14 @@
+globs: app/src/api/**/*.{ts,tsx},app/src/types/**/*.{ts,tsx},app/src/mocks/**/*.{ts,tsx}
+
+## Body
+
+# API contract source is mandatory (no invented DTOs)
+
+When changing DTOs, response types, mappers, or mocks, acknowledge: `Using .ai.local: api-contract-source(, …)*`.
+
+## Rules
+
+- Any new/changed DTO, response type, response mapper, or shared type **names its contract source** in the task brief: an OpenAPI path + schema (or the project's equivalent contract), or an explicit `no in-repo contract — capture is provisional` risk.
+- The API-contract reviewer is **blocking** when the contract source is a capture and the DTO is new/changed → emit `changes_requested`, not advisory notes.
+- Map only fields present in the contract source. Do not add a field that exists only in mockup copy or a guessed payload.
+- Watch nullability / object-vs-scalar: verify against the contract schema, not a single capture (a capture cannot show absent/empty cases).

package/presets/cursor/next/ai-local/rules-library/artifact-lifecycle.md

@@ -0,0 +1,17 @@
+glob: always
+
+## Body
+
+# Agent artifact lifecycle
+
+When writing team artifacts, acknowledge: `Using .ai.local: artifact-lifecycle(, …)*`.
+
+Task-folder artifacts (`.ai.local/team/tasks/<slug>/**`) are an **audit trail**, not a second source of truth. Durable knowledge (decisions, contracts, product behaviour) belongs in `docs/specs/**` or `openspec/**`.
+
+## Rules
+
+- `.ai.local/team/tasks/**` stays **tracked in git** by default; do not add a gitignore entry. Committing task artifacts is the human's choice at the commit step.
+- Keep artifacts **small**: no host paths (see `agent-artifacts-no-local-paths`), no raw diff dumps, no duplicate copies (`* (1).*`), no screenshots beyond intentional baselines.
+- **Never bulk-purge** committed artifacts to "clean up". Deleting does not remove git history. Prevention only.
+- Durable output (approved spec, ADR, contract, QA cases) is copied into `docs/specs/**` / `openspec/**`; the task folder is not the SoT.
+- Follow `commit-hygiene`: artifact/doc churn does not share a commit with `app/src/**`.

package/presets/cursor/next/ai-local/rules-library/code-style.md

@@ -0,0 +1,68 @@
+globs: app/src/**/*.{ts,tsx},app/__tests__/**/*.{ts,tsx}
+
+## Body
+
+# Code style (team conventions template)
+
+When editing TS/TSX, acknowledge: `Using .ai.local: code-style(, …)*`.
+
+The preset is generic. This repo has its own naming and file shapes — **open the nearest analog in the same layer and mirror it**. Where a preset example differs, this rule wins.
+
+## Reference analogs (mirror these)
+
+| Layer | Analog |
+|-------|--------|
+| UI page | `app/src/ui/pages/<Domain>/` |
+| UI component | `app/src/ui/components/<Name>/` |
+| Store slice | `app/src/store/slices/<Domain>/` |
+| API service | `app/src/api/services/<Service>/<Domain>/` |
+| Types | `app/src/types/<Entity>.types.ts` |
+| Unit tests | `app/__tests__/unit/<mirrored path>/` |
+
+## Naming
+
+- Domain types — `T` prefix: `TAnalysis`, `TUserProfile`. Transport/response types — `T…Response` (`TAnalysisResponse`).
+- Interfaces / props — `I` prefix: `interface IProps`, `IRootState`.
+- DTO → domain mappers — verb `format`: `formatAnalysis`, `formatBiomarkers`. Not `map…`.
+- Endpoint constants — `SCREAMING_SNAKE` + `_ENDPOINT` (`DOMAIN_ANALYSIS_ENDPOINT`); dynamic — `prepare…Endpoint`.
+- No `FC` / `React.FC` (see `no-react-fc`).
+
+## Components
+
+- `export const X = ({ ... }: IProps) => (...)`; no `FC`.
+- Styles: a sibling styles module; root export `Root`.
+- Local children in `./components/<Name>/`: `Name.tsx` + `styles.ts` (or `Name.styles.ts` when the parent already has a `styles.ts`) + optional `Name.data.ts` / `Name.utils.ts` / `Name.hooks.ts` + `index.ts`. **Strictly forbidden:** declaring a subcomponent in the same file as the parent — see `component-child-decomposition`.
+- Layout sizes of one component (skeleton `height` / `width` / `maxWidth`, one-off `px`) stay as literals in the JSX prop or in `styles.ts`. Do not hoist them into `SCREAMING_SNAKE` constants or a `*.data.ts`.
+- `*.data.ts` is for copy, labels, lookup maps, and values imported by another module. A file that only names pixels is overhead — delete it and inline.
+
+## API layer (`app/src/api/services/<Service>/<Domain>/`)
+
+- `<Domain>.apiMethods.ts` — `export const XxxApiMethods = { fetchX, createX, saveX, deleteX: async (...) => { … } }`.
+- `<Domain>.endpoints.ts` — path constants.
+- `<Domain>.responseTypes.ts` — `T…Response` (DTO).
+- `<Domain>.responseMappers.ts` — `formatXxx(data: T…Response): T…`.
+- `index.ts` — re-export the four above.
+- Cross-entity mappers — `_shared/<Entity>/<Entity>.responseMappers.ts`.
+- Outside the layer, import only from the `@/api` barrel.
+
+## Store (`app/src/store/slices/<Domain>/`)
+
+- Folder: `<Domain>.ts` (slice + thunks + selectors), `types.ts`, `utils.ts`, `index.ts` barrel.
+- Slice named `xxxSlice`, re-exported via the barrel; not a default export.
+- Thunks: `fetchX` / `createX` / `saveX` / `deleteX`; error typing via `rejectWithValue`.
+- Selectors: curried `xxxSelector = (args) => (state: IRootState) => …`; memoize derived values with `createSelector`.
+- Local `interface IRootState { <sliceName>: TState }` in the slice file; state shape typed in `types.ts`.
+- Errors: follow the existing slice pattern; do not rewrite the error model in a point task.
+- Domain comments — in the project language.
+
+## Types (`app/src/types`)
+
+- Project-language JSDoc; `[computed]` prefix on frontend-derived fields; `Xxx.types.ts` or a folder + barrel `index.ts`.
+
+## Tests
+
+- Mirrored path `app/__tests__/unit/<rel>`, `*.spec.ts(x)`; project-language `describe` / `it`.
+
+## Format
+
+- Prettier: no semicolons, single quotes, trailing commas, width 100. The linter enforces it — run the post-change gate.

package/presets/cursor/next/ai-local/rules-library/component-child-decomposition.md

@@ -0,0 +1,81 @@
+globs: app/src/**/*.{ts,tsx},storybook/stories/**/*.stories.tsx
+
+## Body
+
+# Component child decomposition (strict)
+
+When this rule applies, acknowledge: `Using .ai.local: component-child-decomposition(, …)*`.
+
+A subcomponent of a parent UI component **must** live in a dedicated `components/<Name>/` subfolder of the parent. Defining a subcomponent in the same file as the parent is a **forbidden** shortcut — it breaks the convention used by every other modal/card in the repo, makes the parent file mix orchestration with detail rendering, and prevents re-use of the child from sibling features.
+
+This is enforced by the file structure visible in the working tree. A reviewer or `code-reviewer` agent who finds a subcomponent declared alongside the parent's main export must request changes with reference to this rule.
+
+## File structure
+
+```
+Parent/
+├── Parent.tsx                 ← public export, thin composition only
+├── Parent.styles.ts           ← only styles used directly by Parent (Root, Title, layout shell, list)
+├── index.ts                   ← re-export of Parent
+└── components/
+    └── Child/
+        ├── Child.tsx          ← public export of the subcomponent
+        ├── Child.styles.ts    ← styles specific to the child (its own Card, Icon, Title, etc.)
+        ├── Child.utils.ts     ← OPTIONAL: pure helpers
+        ├── Child.data.ts      ← OPTIONAL: lookup maps / constants
+        └── index.ts           ← re-export of Child
+```
+
+- Child file name: `Child.tsx` (PascalCase, same as folder name). Styles: `Child.styles.ts` (prefixed with child name) to avoid collision when the parent also has a `styles.ts`.
+- Parent uses `import { Child } from './components/Child'` (or `./components/Child/index`); never imports from `../Child.tsx` or `../../Child`.
+- The child does not import from the parent's `styles.ts`. If both share a token, they each import it from the design-token source directly.
+- `Child.utils.ts` / `Child.data.ts` are optional and only added when there are real helpers/maps. Do not create empty files.
+
+## Subcomponents
+
+A **subcomponent** is any JSX `<X .../>` (a) the parent repeats, (b) the parent passes resolved props to (instead of letting the child compute them), or (c) that owns its own layout/typography/visual contract. Inline JSX like `<s.Icon><img/></s.Icon>` is a styled element, not a subcomponent.
+
+When the parent has more than one or two branches, several repeated JSX subtrees, or any non-trivial rendering block, that block **must** be extracted to a subcomponent in `./components/<Name>/`. The parent then becomes a thin switch — it owns the wiring, the wrapper, and the iteration that maps data into `<Child>` instances.
+
+## Forbidden
+
+```tsx
+// ❌ Parent file with a co-located subcomponent
+export const ItemsModal = () => (
+  <Modal>
+    {items.map((item) => (
+      <s.Card key={item.id}>
+        <s.Icon><s.IconImage src={...} /></s.Icon>
+        <s.Body><s.Title>{item.title}</s.Title>...</s.Body>
+      </s.Card>
+    ))}
+  </Modal>
+)
+
+// Declared in the same file — file structure is wrong
+const CardItem = ({ item }) => <s.Card>...</s.Card>
+```
+
+## Correct
+
+```tsx
+// ItemsModal/ItemsModal.tsx
+import { CardItem } from './components/CardItem'
+
+export const ItemsModal = () => (
+  <Modal>{items.map((i) => <CardItem key={i.id} item={i} />)}</Modal>
+)
+
+// ItemsModal/components/CardItem/CardItem.tsx
+import * as s from './CardItem.styles'
+
+export const CardItem = ({ item }: { item: TItem }) => <s.Card>...</s.Card>
+```
+
+## Why the rule is strict, not a preference
+
+- **Diffability:** a change to the child shows up in `components/Child/Child.tsx`, not as noise in the parent file.
+- **Reviewability:** the parent file stays short (~50 lines) and the reviewer reads orchestration without scrolling past detail rendering.
+- **Re-use:** the child can be imported by other stories, modals, or pages without copy-paste.
+- **Tests:** a child-only story (visual regression of the card alone) is possible without re-rendering the whole modal.
+- **Lint / IDE:** per-folder patterns scale better than 200-line parent files mixing styles + helpers + subcomponents + data.

package/presets/cursor/next/ai-local/rules-library/feature-flags-experiments.md

@@ -0,0 +1,15 @@
+globs: app/src/constants/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# Feature flags & experiments (team conventions template)
+
+When gating UI/behaviour by a flag or A/B experiment, acknowledge: `Using .ai.local: feature-flags-experiments(, …)*`.
+
+## Rules
+
+- Local flags live in one module (e.g. `app/src/constants/localFeatureFlags.ts`) as `isFeature…Enabled`; remote experiments come from the experiments client (`@sh/experiments` analog).
+- Read a flag through the repo's access path — a store slice / provider / singleton mounted at the app root — not by scattering `process.env` checks or ad-hoc constants.
+- Experiment-gated routes are registered in the repo's allowlist (e.g. `EXPERIMENT_PAGES`); do not invent a parallel mechanism.
+- Experimental / legacy page variants are **non-canonical** — do not copy them as the reference for new work, and do not delete a flag without the paired spec / story / e2e sync (flag removal is a cross-cutting change).
+- A flag that flips layout or visual identity is still one purpose per component after the flag is removed — do not bake the flag into a universal branchy component (`react-ui`).

package/presets/cursor/next/ai-local/rules-library/mcp-required-for-ui-layout.md

@@ -1,4 +1,4 @@
-globs: src/ui/**
+globs: app/src/ui/**
 
 ## Body
 

package/presets/cursor/next/ai-local/rules-library/no-react-fc.md

@@ -0,0 +1,46 @@
+globs: **/*.{tsx,ts}
+
+## Body
+
+# No `FC` / `React.FC`
+
+When this rule applies, acknowledge: `Using .ai.local: no-react-fc(, …)*`.
+
+Do **not** type React components as `FC`, `React.FC`, `FunctionComponent`, or `React.FunctionComponent`.
+
+`FC` adds implicit `children`, is outdated for React 18+, and the rest of a typical repo already uses a plain arrow + props type.
+
+## Required shape
+
+```tsx
+interface IProps {
+  title: string
+}
+
+export const Example = ({ title }: IProps) => {
+  return <s.Root>{title}</s.Root>
+}
+```
+
+If there are no props:
+
+```tsx
+export const Example = () => <s.Root />
+```
+
+## Forbidden
+
+```tsx
+import { type FC } from 'react'
+
+export const Example: FC<IProps> = ({ title }) => { /* … */ }
+```
+
+```tsx
+export const Example: React.FC<IProps> = ({ title }) => { /* … */ }
+```
+
+## Notes
+
+- Type props with `interface IProps` / `type TProps` (match the neighboring file).
+- If the component accepts `children`, declare `children` explicitly on the props type — do not get it from `FC`.

package/presets/cursor/next/ai-local/rules-library/no-test-driven-behavior-change.md

@@ -1,4 +1,4 @@
-globs: src/**/*.{ts,tsx}
+globs: app/src/**/*.{ts,tsx},app/__tests__/**/*.{ts,tsx},storybook/**/*.stories.tsx
 
 ## Body
 

package/presets/cursor/next/ai-local/rules-library/pwa-service-worker.md

@@ -0,0 +1,15 @@
+globs: app/src/lib/pwa/**/*.{ts,tsx},app/public/**
+
+## Body
+
+# PWA / service worker (team conventions template)
+
+When touching the service worker, manifest, or offline behaviour, acknowledge: `Using .ai.local: pwa-service-worker(, …)*`.
+
+## Rules
+
+- Service worker and web manifest are wired through the app root / document head via one init hook; do not register a second service worker or add a competing `<link rel="manifest">`.
+- Service-worker scope and asset paths are derived from `basePath` / `assetPrefix` — a hardcoded `/` breaks scoped deployments.
+- A dev-only `Service-Worker-Allowed` header (or equivalent) is a dev concern; do not assume it exists in production.
+- Do not introduce `next-pwa`-style tooling unless the repo already uses it; follow the existing registration path.
+- Offline/caching changes are behaviour changes: update the spec / e2e / QA case that covers offline flows.

package/presets/cursor/next/ai-local/rules-library/qa-test-cases.md

@@ -0,0 +1,14 @@
+globs: docs/qa/**/*.md,app/__tests__/e2e/**/*.cases.md
+
+## Body
+
+# Consolidated QA test cases (`docs/qa/**`)
+
+When editing QA case docs or the matching e2e plan, acknowledge: `Using .ai.local: qa-test-cases(, …)*`.
+
+## Rules
+
+- A consolidated QA doc (`docs/qa/<area>-test-cases.md`) is a **derived view** of the spec + `*.cases.md` — not a second source of truth. Cite the source (spec path / scenario id) per case.
+- Keep the route table, PREFIX map, and grouping in sync with the executable plan; mark each case `as-is` (characterization) or `target` (planned).
+- On a behaviour change, update the QA doc in the same changeset as the `*.cases.md` / spec.
+- Do not weaken or delete cases to match an unintended behaviour change — fix the implementation or file a task (`no-test-driven-behavior-change`).

package/presets/cursor/next/ai-local/rules-library/router-pages.md

@@ -1,5 +1,5 @@
 override: kill next-app-router
-globs: src/pages/**/*.{ts,tsx},src/ui/**/*.{ts,tsx},next.config.ts
+globs: app/src/pages/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx},app/next.config.ts
 
 ## Body
 
@@ -15,9 +15,11 @@ This rule drops the preset's `next-app-router` rule from context for repos using
 - Domain UI lives in `src/ui/pages/<Name>Page`; route files do not contain layout/business logic.
 - Navigation: `next/router` (`useRouter`) and `next/link`. **Never** `next/navigation`.
 - `_app.tsx` / `_document.tsx` stay in `src/pages/`.
+- Dynamic routes: the dynamic segment is **last**, `[id].tsx` → `[id].html`; do **not** add catch-all `[...slug]` routes. Read a dynamic param only after the router is ready (`useRouterReady()` analog) and parse it with the repo's slug helper; push `/404` when it is invalid.
 
 ## Forbidden
 
 - Creating App Router files (`src/app/**`, `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`).
 - Importing `next/navigation` or App Router server APIs (`cookies()`, `headers()`, `redirect()`).
-- `getServerSideProps` / `getStaticProps` — the app is a client-rendered static export; data goes through the store/`@/api`.
+- `getServerSideProps` / `getStaticProps` — the app is a client-rendered static export; data goes through the store/`@/api`.
+- Reading `router.query` before `router.isReady` (cold-load crash); non-integer / non-final dynamic segments (nginx serves only integer slugs at the end).

package/presets/cursor/next/ai-local/rules-library/single-source-copy-constants.md

@@ -1,4 +1,4 @@
-globs: src/**/*.{ts,tsx}
+globs: app/src/**/*.{ts,tsx}
 
 ## Body
 
@@ -11,6 +11,8 @@ Copy (button labels, headings, alt text, aria-labels), constants, enums, and rou
 ## Rules
 
 - User-visible copy: inline unless the same string is used in ≥2 distinct places OR is consumed by tests/stories that need a shared reference. Multi-instance refactors belong to a dedicated task.
+- A new inline data table (dictionary/map) larger than ~50 entries requires a cited source (spec, mockup node, or contract) in the task artifact — otherwise it is invented content.
+- Copy changes cite a spec or mockup node.
 - Numeric / pixel / token aliases: inline directly; do not re-wrap into a named constant when used exactly once in the same file.
 - Counters and derived single-use values: inline (`array.length`, computed expressions).
 - Layout sizes of one component (skeleton `height`/`width`/`maxWidth`, one-off `px`) stay as literals in the JSX prop or in `styles.ts`. Do not hoist them into named constants or a `*.data.ts`, even when the same number is repeated in that component's JSX and its styles.

package/presets/cursor/next/ai-local/rules-library/storybook-catalog-structure.md

@@ -0,0 +1,62 @@
+globs: storybook/stories/**/*.stories.tsx, storybook/stories/**/README.md, storybook/stories/**/*
+
+## Body
+
+# Storybook catalog structure
+
+When editing Storybook catalog files, acknowledge: `Using .ai.local: storybook-catalog-structure(, …)*`.
+
+## Before you add a story
+
+- UI develop/refactor starts with **`storybook-ui-quality-gate`** (preview vs mockup + story tests) — stories are not post-hoc docs.
+- Read the folder README: `storybook/stories/pages/README.md`, `components/README.md`, `modals/README.md`.
+- Copy the nearest analog file; do not invent a new sidebar branch.
+- After add/edit (and after UI refactors that stories cover): **`storybook-keep-tests-current`** — tests + baselines green.
+
+## Sidebar roots (fixed)
+
+| Title pattern | Path | Notes |
+|---------------|------|-------|
+| `UI/Pages/<ShortName>` | `pages/<Page>/<Page>.stories.tsx` | Full page; `layout: 'fullscreen'`, `defaultViewport: 'desktop'`. |
+| `UI/Pages/<Page>/Components/<Block>` | `pages/<Page>/Components/<Block>.stories.tsx` | **Required** for page-level blocks. |
+| `UI/Pages/<Page>/Cards/<Card>` | `pages/<Page>/Cards/` | List cards only. |
+| `UI/Components/<Name>` | `components/` | Reusable `app/src/ui/components/**`. |
+| `UI/Modals/<Domain>/<Modal>` | `modals/<Domain>/` | Isolated dialogs only. |
+
+## Page Components section (required)
+
+When a page has distinct blocks (summary, side panel, files, skeletons, etc.):
+
+- Add `storybook/stories/pages/<Page>/Components/<BlockName>.stories.tsx`.
+- Title: `UI/Pages/<ShortName>/Components/<BlockName>`.
+- Cover **every code-implemented visual state** (loading skeleton, empty, error, feature-flag variants).
+- Document in page `README.md`: block × state → export name → fixture/mock id.
+- Nested modals inside blocks: story the **block** or use existing `UI/Modals/*` — not a separate modal story.
+- Pure skeleton/presentational blocks: single default export is OK.
+- White-card blocks: apply the grey-canvas decorator so the card edge is visible. Skip grey/primary/secondary roots (see `storybook-csf-authoring`).
+- If the page CSF grows: extract a block into `Components/` — **never** `PageName.p1.stories.tsx`.
+
+## Placement rules
+
+- Reusable across pages → `storybook/stories/components/` (see components README out-of-scope table).
+- Modal/dialog → `storybook/stories/modals/` only.
+- Page-only block → page `Components/` (not `UI/Components/`).
+- List cards → `pages/<Page>/Cards/` (not modal wrappers).
+
+## README requirement
+
+Each page folder keeps `README.md`: mock id map, state vocabulary, vitest validation path, Components catalog when present.
+
+Example validation (from `storybook/`):
+
+```bash
+yarn vitest run --project=storybook stories/pages/<Page>/Components/<Block>.stories.tsx
+```
+
+## Forbidden
+
+- Duplicating a modal under page/Components when `UI/Modals/...` already exists.
+- New `*Modal*` titles under `UI/Components/`.
+- New flat page-block files at page root — use `Components/`.
+- **No** `*.p1.stories.tsx`, `*.p2.stories.tsx`, or any `*.pN.stories.tsx` — one CSF per `title`.
+- **No** viewport-duplicate stories: `Mobile*`, `Mobile_*`, `defaultViewport: 'mobile*'`, `isMobile` preloads.

package/presets/cursor/next/ai-local/rules-library/storybook-cleanup-temp-screenshots.md

@@ -0,0 +1,40 @@
+glob: always
+
+## Body
+
+# Storybook temp screenshot cleanup
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-cleanup-temp-screenshots(, …)*`.
+
+## When (mandatory)
+
+Before declaring Storybook or UI work complete, and after any browser / Figma / Playwright / Storybook MCP screenshot: delete files **this turn created** that are not product assets or vis baselines.
+
+Leaving dump PNGs in the repo is incomplete work — same severity as red Storybook tests.
+
+## Delete
+
+Typical dumps (names vary):
+
+- Repo-root images: `*-after.png`, `*-before.png`, `positive-story.png`, and any other untracked `*.png` / `*.jpg` / `*.webp` at the workspace root that you created.
+- `/tmp/**` review dumps.
+- Workspace copies of Figma screenshots, browser screenshots, or Playwright traces/screenshots written **into the git worktree** (not CI artifacts).
+
+## Keep
+
+- `storybook/__vis__/<platform>/__baselines__` — CI vis; refresh via `--update`, never `rm` to hide drift.
+- `storybook/__vis__/local` — gitignored local baselines; still refresh, do not wipe.
+- Product assets: `app/public/**`, component `images/`, committed mocks.
+- Files the user explicitly asked to keep.
+
+## How
+
+1. `git status --short` (and `ls` repo root) for untracked/modified images from this turn.
+2. Delete **only those paths**. No `git clean -fd`, no `git checkout` of vis baselines.
+3. Confirm gone. Do not `git add` temp screenshots.
+
+## Forbidden
+
+- Committing verification / MCP / Playwright dump images.
+- Leaving repo-root PNGs "for the user to review" unless they asked.
+- Deleting vis baselines instead of `--update`.

package/presets/cursor/next/ai-local/rules-library/storybook-csf-authoring.md

@@ -0,0 +1,100 @@
+globs: storybook/**/*.stories.tsx, storybook/**/*.fixtures.ts, storybook/**/*.fixtures.data.ts, storybook/**/*.stories.meta.ts
+
+## Body
+
+# Storybook CSF authoring
+
+When editing CSF/fixtures, acknowledge: `Using .ai.local: storybook-csf-authoring(, …)*`.
+
+## CSF3 skeleton
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta = {
+  title: 'UI/Pages/ExamplePage',
+  component: ExamplePage,
+  tags: ['test', 'snapshot'],
+  decorators: [withStoreProvider({ preloadedState })],
+  parameters: { layout: 'fullscreen', viewport: { defaultViewport: 'desktop' } },
+} satisfies Meta<typeof ExamplePage>;
+
+export default meta;
+type TStory = StoryObj<typeof meta>;
+
+/** S01 — default loaded state */
+export const Default: TStory = { /* … */ };
+```
+
+## Imports
+
+- Production: `@/ui/...`, `@/store/...`, `@/types/...`.
+- Storybook: the project's shared decorators/helpers (`withStoreProvider`, `withGreyCanvas`, `withStorybookSearchParams`, `withDocumentReferrer`), the shared MSW helper, and the test utilities (`expect`, `within`, `userEvent`, `fn`, `waitFor`).
+- Play helpers: co-locate in `*.stories.meta.ts` or `*.fixtures.ts` — do not duplicate selectors.
+
+## Data & decorators
+
+- MSW: `parameters: { ...storyMsw(handlers) }` from the shared MSW helper.
+- Store: `decorators: [withStoreProvider({ preloadedState })]` — use fixture builders.
+- Search params: `withStorybookSearchParams({ key: 'value' })`.
+- Browser globals (render-time): `withDocumentReferrer('')` — `document.referrer` and in-app list session signals are **story fixtures**, not play-only setup. Reset session keys when production reads them at render.
+- White-card isolated blocks **only** (a solid white surface token): `withGreyCanvas`. Do not use on grey primary/secondary roots.
+- **Never** `parameters.nextjs.appDirectory`. Do not null-guard production `useSearchParams`.
+
+## Fixtures
+
+Split: handlers/ids (`*.fixtures.ts`), static data (`*.fixtures.data.ts`), play constants (`*.stories.meta.ts`).
+Reuse page fixtures before inventing ids. Document story-local id ranges in the README.
+
+## One CSF file per `title` (strict)
+
+Allowed: `PageName.stories.tsx`, `Components/<Block>.stories.tsx`, `modals/<Domain>/<Modal>.stories.tsx`.
+
+**Forbidden:**
+
+- New `*.p1.stories.tsx`, `*.p2.stories.tsx`, or any `*.pN.stories.tsx`.
+- Adding exports to existing p1/p2 files.
+- Numbered overflow siblings sharing the same `title`.
+
+Existing p1/p2 in a repo are **legacy — do not copy or extend**. If the main file is large, extract a page block into `Components/` (new `title`).
+
+## No mobile/viewport duplicates (strict)
+
+One desktop canvas per logical state; reviewers use the Storybook viewport toolbar.
+
+**Ban:** `export const Mobile*`, `Mobile_*`, `defaultViewport: 'mobile1'` / `'mobile2'`, `isMobile: true` preloads, `*MobileMediaPreload` fixtures, dedicated `*Mobile*.stories.tsx` for viewport variants.
+
+**Keep only** product UI whose name is Mobile (a distinct component, not a second viewport of a page).
+
+## Play vs visual
+
+- Every snapshot story has a `play` asserting primary `data-testid`s or visible copy.
+- Call the visual-settle helper after icon/header paint (~300ms) when flaking — use it on isolated blocks/modals with masked icons before vis.
+- Portals: assert `within(canvasElement.ownerDocument.body)`.
+- **Loading / spinner vis:** preload the store slice (`loadingStatus: 'loading'`) or MSW `delay('infinite')`. **Forbidden:** click download/submit then vis the in-flight frame without pinning the request.
+- Freeze animations only on spinner/QR/skeleton stories, as the last line of `play`; then `--update -t` that story only.
+- **Intentional** `LoadFailed` export (MSW 500) ≠ an accidental "failed to load the page" (missing API mocking).
+
+## Tags & layout
+
+- `tags: ['test', 'snapshot']` on visual catalog entries.
+- Page: `layout: 'fullscreen'`, `viewport.defaultViewport: 'desktop'`.
+- Isolated block: `layout: 'centered'` unless the block needs width.
+
+## Grey canvas (white cards only)
+
+Apply the grey-canvas decorator **only** when the production root is a solid white surface. Use the project's grey-surface token. Never hex.
+
+```tsx
+import { withGreyCanvas } from '<shared-decorators>' // adjust depth
+
+decorators: [withGreyCanvas], // outer; width shells stay inside
+```
+
+**Do not apply** when the root is already grey, transparent, a fullscreen page, or a modal. Grey-on-grey hides radius and rest/hover fills.
+
+**Forbidden:** `parameters.backgrounds` hex lists; a grey wrapper the same size as the card (edge still invisible).
+
+## After batch
+
+Mandatory: **`storybook-ui-quality-gate`** — preview stories, compare canvas vs mockup, then run story tests. Then **`storybook-keep-tests-current`**: fix play/fixtures, targeted vitest, `--update` vis after intentional visual changes, re-run green. Then **`storybook-cleanup-temp-screenshots`** — delete dump PNGs from this turn; do not commit them.

package/presets/cursor/next/ai-local/rules-library/storybook-dev-compare-figma.md

@@ -0,0 +1,67 @@
+globs: app/src/ui/**/*.tsx, app/src/ui/**/*.ts, storybook/stories/**/*.stories.tsx
+
+## Body
+
+# Storybook dev-time Figma visual compare (mandatory)
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-dev-compare-figma(, …)*`.
+
+While implementing or refactoring `app/src/ui/**` (new component, visual/interaction change, layout, styles, copy, hover/open), the **source of visual truth is Figma** — not Storybook vis-baselines. Vis-baselines are a **regression detector** (they catch "you broke what was working"), not a design spec (they do not validate "this matches the Figma mockup"). They can lock in a wrong implementation as the baseline if `--update` is run before the implementation is correct.
+
+This rule makes the dev-loop **mandatory** and forbids the failure mode where an agent captures a `--update` baseline against a wrong implementation, the wrong implementation becomes the "correct" baseline, and the next round of changes is compared against the wrong baseline — drift is hidden forever.
+
+## The required loop (every visual change)
+
+1. **Read Figma first** — `figma_get_metadata` for the node structure, `figma_get_design_context` for the actual styles/tokens, `figma_get_variable_defs` for design tokens, `figma_get_screenshot` for the visual reference. Do not pick the wrong reference node (e.g. a wrapper frame instead of the card component). Pick the **innermost** matching node.
+2. **Implement to spec** — every token (color, padding, gap, font, radius) must come from `figma_get_design_context` / `figma_get_variable_defs`, not from memory or from guessing. If a style is not in the Figma spec, the implementation is wrong; do not invent.
+3. **Open the story in a browser** — navigate to the story URL (e.g. `http://localhost:6006/?path=/story/<story-id>`). If Storybook is not running, start it with `yarn storybook` from `storybook/`.
+4. **Take a screenshot** — of the **opened dialog / visible state**, not the Storybook iframe placeholder.
+5. **Visual compare with Figma** — open the Figma screenshot in the same view (saved PNG of the Figma node). Compare element-by-element:
+   - Title (font, size, weight, color, line-height, letter-spacing)
+   - Subtitle / supporting text (same)
+   - Container (background, border, radius, padding, gap)
+   - Icon (image content, size, container styling)
+   - Status / state (text + color)
+   - Disclosure / actions (icon, size, position)
+   - Hover state (compare in both the Figma "Hover" variant AND Storybook hover)
+6. **Diff and fix** — if the Storybook render does not match the Figma, fix the production code (or fixture, if the data was wrong) and re-screenshot. Do not `--update` the baseline until the Figma match is confirmed by a human-readable visual side-by-side.
+7. **Only then `--update`** — `yarn vitest run --project=storybook <path> --update` records the now-correct baseline. After the rewrite, run **without** `--update` once to confirm the new baseline is stable.
+
+## Why baselines are NOT enough
+
+A baseline is a pixel diff against an existing image. If the existing image is wrong, the baseline silently approves future wrongness.
+
+The failure mode this guards against: an agent implements UI with wrong border, wrong icon, wrong font, and wrong background; captures a `--update` baseline; vis-tests go green. The next round tightens tokens but keeps the wrong icon; `--update` again; still green. An operator later opens the story and it looks nothing like Figma. The "green" vis-tests had been comparing to a wrong baseline for two rounds.
+
+The fix is not "more `--update` discipline". The fix is a **mandatory dev-time visual compare with Figma** before any `--update`.
+
+## Forbidden
+
+- Running `yarn vitest -u` against a story that has not been visually compared with Figma in the current session.
+- "Vis-tests are green" used as evidence the UI matches Figma.
+- Comparing only via a single Figma screenshot and then trusting memory for the rest of the change.
+- Using a Figma screenshot of a **different node** as the reference (e.g. the outer modal instead of the card component, the empty state instead of the loaded state, the desktop variant instead of the mobile variant).
+- Skipping the dev-time compare and relying on the operator to spot drift after the fact.
+
+## Required when
+
+Mandatory for any change under `app/src/ui/**` that affects:
+
+- Layout, padding, gap, alignment
+- Typography (font, size, weight, color)
+- Color, background, border, radius, shadow
+- Icon / image / illustration
+- Hover / open / focused / error / empty / loading visual states
+- Storybook vis-baseline first capture (`--update`) or any intentional change to baselines
+
+## MCP wiring
+
+- `chrome-devtools_*` (in the session MCP catalog) is the preferred browser navigation / screenshot tool for the dev-time compare. If it is `error` / `needsAuth` / `loading`, **stop** and report the block, do not approximate.
+- `playwright` MCP can be used as a substitute **only if** `chrome-devtools` is unavailable — but `chrome-devtools` is preferred because it gives a real DOM + screenshot of the running app.
+- A `localhost:6006` reached via a browser MCP is the right way; a screenshot of the production Next.js route is **not** an acceptable substitute (per `mcp-required-for-ui-layout.md`).
+
+## Reference
+
+- `storybook-ui-quality-gate.md` — this rule makes its "compare with mockup" step mandatory and dev-time, not at-the-end.
+- `storybook-keep-tests-current.md` — the post-change half (play + baseline refresh); this rule is the pre-`--update` half.
+- `mcp-required-for-ui-layout.md` — Figma + Storybook MCP gate.