@bonesofspring/ai-rules 0.2.31 → 0.2.32

package/presets/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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/opencode/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.

package/presets/opencode/next/ai-local/rules-library/storybook-keep-tests-current.md

@@ -0,0 +1,75 @@
+globs: storybook/**/*.stories.tsx, storybook/**/*.fixtures.ts, storybook/**/*.fixtures.data.ts, storybook/**/*.stories.meta.ts, storybook/stories/**/README.md, app/src/ui/**/*.tsx, app/src/ui/**/*.ts
+
+## Body
+
+# Storybook keep tests current
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-keep-tests-current(, …)*`.
+
+## When (mandatory)
+
+Storybook tests and vis baselines are **part of the change**. Do not finish with red or stale snapshots.
+
+Triggers:
+
+1. Add or edit a story, fixture, `*.stories.meta.ts`, or page Storybook README.
+2. Change production UI a story imports (`app/src/ui/**`) — layout, styles, copy, `data-testid`, states. New/refactored UI must already have stories via **`storybook-ui-quality-gate`** (preview vs mockup); this rule is the test/baseline half.
+3. Change mocks / domain / store fields that stories preload — grep `storybook/stories` and apply this gate.
+
+Leaving play broken or skipping `--update` after an intentional visual change is incomplete work.
+
+## Find related stories
+
+Grep `storybook/stories` for the component name and its import. Cover **all** hits: page, `Components/<Block>`, cards, modals — not only the file you opened. Check the page `README.md` state map.
+
+## Keep working
+
+- **Play:** selectors, copy, `data-testid`s, settle/portal helpers must match the new UI.
+- **Fixtures / MSW / preloadedState:** match domain after mapper or store changes.
+- New production visual state → new story export (catalog structure). Removed UI → delete or retarget the story.
+- Page `README.md`: state → export → fixture id.
+
+**Forbidden:** commenting out `play`; dropping `test` / `snapshot` tags to silence failures; ignoring vis drift.
+
+## Computed copy & browser fixtures
+
+When play asserts **visible copy** that production derives from `document.referrer`, sessionStorage, in-app signals, or i18n: stub those inputs in a **decorator** (sync before mount). Play is too late.
+
+- Do not treat a hard-coded label as a stable selector when the same `data-testid` can show two production strings. Assert the variant's **inputs** first, then the copy.
+- After adding/changing a story that depends on browser document state, grep production for `document.referrer` / session keys used at render.
+
+## Play queries & timeouts
+
+- Static shells (no fetch): prefer `getByTestId` / `getByRole` so a missing node fails immediately, not `Test timed out in 30000ms`.
+- `findBy*` / `waitFor` only when UI is actually async (MSW, loader). Cap timeout (e.g. 3–5s). Never wait for a testid that production does not mount without mocks.
+- Vitest `testTimeout` includes the vis auto-snapshot `afterEach`. A 30s timeout on a story with a tiny `play` is often vis (icon masks, large SVG, full header/footer), not a missing node. Isolated green + full-suite 30s timeout → cap the wait, do not raise `testTimeout`.
+- Any `new Image()` / mask-URL wait **must** have a 3–5s cap. Unbounded `Image()` → full-suite hang while isolated still passes.
+- **Vis loading race:** a `userEvent.click` that dispatches an unmocked thunk (download, fetch) → vis captures spinner **or** idle. Pin the frame: preload the store slice (`loadingStatus: 'loading'`) or MSW `delay('infinite')`. **Forbidden:** click-then-snapshot an in-flight request.
+
+## Run (from `storybook/`)
+
+Targeted path only — do not `--update` the whole catalog.
+
+```bash
+yarn vitest run --project=storybook <path>
+```
+
+Play / fixture failures: **fix CSF**, then re-run. Do not `--update` to hide a broken `play`.
+
+After an **intentional** visual change, refresh baselines (`--update` **after** the path):
+
+```bash
+yarn vitest run --project=storybook <path> --update
+yarn vitest run --project=storybook <path> -t '<Story name>' --update
+```
+
+`--update` on a **file path** rewrites **every** export in that file. A spinner/animation-freeze story can recapture siblings not yet painted. Use `-t '<Story name>'` for one snapshot. Review each rewritten PNG; do not blind-accept.
+
+Re-run **without** `--update` until exit 0. After a vis/timeout flake: re-run the **originally failing files together** (isolated green ≠ full-suite green).
+
+## Baselines
+
+- Local: `storybook/__vis__/local` (gitignored) — still refresh so the next local run is green.
+- CI: `storybook/__vis__/<platform>/__baselines__` — add when those files exist in git.
+- Done only when targeted vitest is green **without** `--update`.
+- Done only after **`storybook-cleanup-temp-screenshots`**: no leftover dump PNGs from this turn.

package/presets/opencode/next/ai-local/rules-library/storybook-modals.md

@@ -0,0 +1,64 @@
+globs: storybook/stories/modals/**
+
+## Body
+
+# Storybook modals catalog
+
+When editing modal stories, acknowledge: `Using .ai.local: storybook-modals(, …)*`.
+
+## Scope
+
+- Isolated modal components only — no page underlay.
+- No "card wrapper" stories when `UI/Modals/...` already covers the trigger (see the modals README reuse table).
+- A component-catalog open-by-default `ConfirmModal` is a component-catalog exception — **do not copy** that pattern here.
+
+## Title & path
+
+- Title: `UI/Modals/<Domain>/<ModalName>` matching `storybook/stories/modals/<Domain>/`.
+- Never place modal titles under `UI/Pages/` or `UI/Components/`.
+
+## Closed by default
+
+First paint shows a labeled trigger (`BasicButton`), not an open dialog.
+
+- Trigger: a stable `data-testid` (e.g. `modal-story__open-trigger`).
+- **Forbidden:** always-open default export; snapshot variants that skip the closed state unless separately named + justified in README.
+
+## Render helpers
+
+From the shared modal decorators module:
+
+- `createReduxModalStoryRender` — dispatch prod open actions from a closed `preloadedState`.
+- `createLocalModalStoryRender` — `useState(isOpen)` harness.
+- A `ModalStoryShell` wrapper; pass `isMounted` when prod conditionally mounts the modal.
+
+## Play sequence
+
+1. `expectNoModalDialog`
+2. `clickModalStoryTrigger`
+3. `expectVisibleTextInModal` / `expectVisibleTestIdInModal`
+4. Close via prod affordances (overlay, cancel/confirm) — no story-only close button.
+
+Portals: assert `within(canvasElement.ownerDocument.body)`.
+
+## Visual
+
+Vis addon snapshots **after** play (opened dialog + trigger). Document per-modal exceptions (e.g. a modal that closes after confirm).
+
+- After open + copy assertions: call the visual-settle helper when the dialog has masked icons. Isolated green + full-suite `Test timed out in 30000ms` → vis afterEach / unbounded icon wait, not a missing node.
+- Do not add `new Image()` / mask waits without a 3–5s cap.
+- Do not raise story `testTimeout` to hide a CDN hang.
+
+After add/edit/UI refactor: **`storybook-ui-quality-gate`** (preview vs mockup) then **`storybook-keep-tests-current`** — play + `--update` + re-run green.
+
+## MSW / store / query-open
+
+- Fetch-on-mount: shared MSW helper + store provider (same as pages).
+- Postpayment / query-open modals: shell-controlled `isOpen` + `withStorybookSearchParams` when prod uses query params.
+
+## Forbidden
+
+- Always-open default export.
+- Duplicate card modals under `modals/` when listed in the modals README reuse table.
+- Viewport-duplicate modal stories (`Mobile*`, `defaultViewport: 'mobile*'`).
+- New `*.pN.stories.tsx` overflow files — one CSF per modal `title`.

package/presets/opencode/next/ai-local/rules-library/storybook-no-app-node-modules.md

@@ -0,0 +1,40 @@
+glob: always
+
+## Body
+
+# Storybook must not resolve packages from app/node_modules
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-no-app-node-modules`.
+
+## Rule
+
+When Storybook lives in its own package (`storybook/package.json`, `storybook/yarn.lock`, `storybook/node_modules`), it **must not** load npm dependencies from the app's `node_modules`.
+
+Categorical. Missing a design-system package, "versions match `app/`", ESLint plugin lookup, a Vite alias, or a Docker `COPY` of `app/node_modules` do not waive it. Do not cite an existing violation as a pattern to copy.
+
+## Forbidden
+
+Any mechanism that makes Storybook (dev, build, test, lint, typecheck, Docker) import an installed package from `app/node_modules`:
+
+- Vite/webpack `resolve.alias`, `resolve.modules`, `optimizeDeps`, `dedupe`, or a plugin `resolveId` aimed at `app/node_modules` / `../app/node_modules`.
+- `paths` in any `storybook/**/tsconfig*.json` that point at `../app/node_modules/**`.
+- `NODE_PATH`, yarn/npm/pnpm link, workspace hoisting, or a symlink from `storybook/node_modules` into `app/node_modules`.
+- Docker `COPY`, volume, or bind-mount of `app/node_modules` into a Storybook stage or image.
+- ESLint, Stylelint, Vitest, or another Storybook tool resolving plugins or packages from `app/node_modules`.
+
+## Allowed
+
+Application **source and static files**, not installed packages:
+
+- `@/` → `app/src/**`
+- `app/next.config.ts`, `app/environment.d.ts`, `app/public/**`, `app/src/assets/**`
+
+`server.fs.allow` may include `app/` so Vite can read that source. It must not be used to import from `app/node_modules`.
+
+## If a package is missing
+
+Add it to `storybook/package.json`, install it into `storybook/node_modules`, and align the version with `app/package.json`. Do not alias it into `app/node_modules`.
+
+## Known violations — do not extend
+
+Existing aliases, `paths`, and Docker `COPY` sites that resolve through `app/node_modules` today are violations, not a pattern. A change that edits one of those sites removes that `app/node_modules` binding in the same change.

package/presets/opencode/next/ai-local/rules-library/storybook-ui-quality-gate.md

@@ -0,0 +1,38 @@
+glob: always
+
+## Body
+
+# Storybook UI quality gate
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-ui-quality-gate(, …)*`.
+
+Storybook is the **mandatory** surface for developing and refactoring UI. Use it to compare the canvas with the mockup and to control visual/interaction quality. A Next.js route screenshot, source-only review, or unit tests without stories is **not** enough.
+
+## When (mandatory)
+
+Triggers:
+
+1. New page, block, modal, or reusable component (`app/src/ui/**`).
+2. Visual or interaction refactor — layout, styles, tokens, copy, hover/open, empty/error/loading.
+3. Existing UI that already has stories (then also **`storybook-keep-tests-current`**).
+
+**Skip:** types / API / store / mocks with **no** render or style change.
+
+## Loop (do not skip steps)
+
+1. **Before UI code:** read the Storybook story instructions (Storybook MCP) if available. Copy the nearest analog CSF. If the brief has a `figma.com` URL, keep that node as the visual SoT.
+2. **Stories with the UI — not after.** Cover **every implemented visual state** (see `storybook-catalog-structure`). New state without an export is incomplete work.
+3. **Compare with mockup:** preview the stories and open **every** returned URL. Side-by-side story canvas vs Figma (or vs AC / `ux-design.md` when there is no Figma). Check spacing, tokens, typography, empty/error/loading, hover/open. Use the viewport **toolbar** — no `Mobile*` duplicate stories.
+4. **Quality:** run the story tests, then **`storybook-keep-tests-current`** (play + vis green without `--update`). Then **`storybook-cleanup-temp-screenshots`**.
+
+Mismatch with the mockup → fix **production** (or the fixture if data was wrong), then preview again. Do not "accept" drift.
+
+MCP down: `yarn storybook` + folder README analog; still visually review the canvas and run vitest from `storybook/`.
+
+## Forbidden
+
+- Shipping UI without stories for new/changed visual states.
+- "Looks fine on the Next.js page" without Storybook preview.
+- Skipping preview / story tests when MCP is up.
+- Treating Storybook as post-hoc docs after the feature is "done".
+- Closing the task while canvas ≠ mockup for a state that was in scope.