@bonesofspring/ai-rules 0.2.13 → 0.2.15

package/presets/claude/nuxt/rules/architecture/feature-delivery-workflow.md

@@ -0,0 +1,89 @@
+---
+description: End-to-end checklist for a new feature and the “layer → Cursor rule” matrix. Use when implementing features via feature-developer or feature-delivery skill.
+paths:
+  - pages/**/*
+  - components/**/*
+  - stores/**/*
+  - api/**/*
+  - composables/**/*
+  - types/**/*
+---
+
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (end-to-end order)
+
+## Stack notes
+
+Typical feature with backend data and shared state. Layer details — `architecture-boundaries.mdc`, `nuxt-app-core.mdc`.
+
+## Checklist (work order)
+
+1. **Domain types** — `types/**`, export via barrel (`public-imports.mdc`, **`layer-barrel-exports.mdc`**); JSDoc — `types-jsdoc.mdc`.
+2. **API contract** — DTOs where the repo uses them; domain types in `@/types`.
+3. **Mappers** — DTO → domain in `*responseMappers.ts` (`api-services.mdc`).
+4. **Services** — clients `api/clients/**`, barrel `@/api` (`api-services.mdc`, `http-client.mdc`, **`layer-barrel-exports.mdc`**). No `fetch` from UI/store.
+5. **State** — `defineStore` / Pinia actions (`store-pinia.mdc`); actions → services from `~/api` / `@/api`.
+6. **UI** — types from `@/types`, no DTOs (`vue-ui.mdc`, `architecture-boundaries-ui.mdc`, `no-v-bind-spread.mdc`).
+7. **Mocks** — per repo layout; register in `mocks/handlers.ts` (see below).
+8. **Tests** — unit for mappers (`tests-unit.mdc`); e2e from `*.cases.md` (`tests-e2e-structure.mdc`, `playwright-agents.mdc`).
+9. **Completion** — **`post-change-lint.mdc`**: `lint:js` + `lint:css` + `typecheck`; package manager — `package-manager.mdc`.
+
+## Data flow (orientation)
+
+```mermaid
+flowchart LR
+  subgraph transport [Transport]
+    HttpClient[HttpClient]
+  end
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain types]
+  Domain --> Service[API service]
+  Service --> HttpClient
+  Service --> Action[Pinia action]
+  Action --> Store[Store]
+  Store --> UI[UI]
+```
+
+## Registration by layer
+
+1. **Types** — `types/**`; domain model is the source of truth for UI and store.
+2. **API** — `api/services/<ServiceRoot>/<Segment>/`; public exports (incl. **path constants** for mocks) → **`api/index.ts`**.
+3. **Mocks (MSW)** — `mocks/data/<feature>/`; handlers in **`mocks/handlers.ts`**. Paths from `@/api`; do not duplicate URL strings. Check browser worker and Node `setupServer` if both are used.
+4. **Store** — `stores/<featureName>.ts` (`defineStore`); optional composable facade in `composables/**`. Registration via `@pinia/nuxt` / the repo’s accepted pattern — **not** RTK `reducers.ts` / `middleware/**`.
+5. **UI** — `pages/**`, `components/pages/<FeatureName>Page/**` and/or `components/**`; data via store / composables.
+6. **Unit** — `*.spec.ts`; mappers and non-trivial logic are required.
+7. **E2E** — `tests/e2e/<Area>/<plan>.cases.md` + `*.spec.ts`.
+
+## Partial scenarios
+
+| Task | Minimum actions |
+|------|-----------------|
+| API + types only | Types, service, mappers, `@/api` barrel; unit for mapper. |
+| Mocks only | Path in `@/api`; handlers + `mocks/handlers.ts`. |
+| Store only | Pinia actions via `@/api`; `stores/<feature>.ts`. |
+| UI only | Store state; no HTTP/DTO. |
+| E2E only | `*.cases.md` + spec; page object. |
+
+## Anti-patterns
+
+- DTO in UI or untyped store.
+- HTTP client from a component/Pinia action bypassing the service.
+- Deep-import `@/api/services/**` from UI/store.
+- `{...props}` / `v-bind="$attrs"` spread without an explicit list — `no-v-bind-spread.mdc`.
+- RTK / Redux (`createSlice`, `createAsyncThunk`, `stores/slices/**` as the canon).
+- **Ubiquitous language:** Domain/type names reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## Matrix: zone → rules
+
+| Zone | Rules |
+|------|-------|
+| `api/clients/**`, `lib/clients/**` | `http-client.mdc`, `tests-unit.mdc` (behavior) |
+| `api/services/**` | `api-services.mdc`, `layer-barrel-exports.mdc`, `http-client.mdc` |
+| `stores/**` | `store-pinia.mdc`, `architecture-boundaries.mdc`, `public-imports.mdc` |
+| `components/**` | `vue-ui.mdc`, `no-v-bind-spread.mdc`, `public-imports.mdc` |
+| `types/**` | `public-imports.mdc`, `types-jsdoc.mdc`, `layer-barrel-exports.mdc` |
+| `tests/e2e/**` | `tests-e2e-structure.mdc`, `playwright-agents.mdc` |
+
+When adding or extending a feature, **walk the checklist** and the rules from the table for affected zones.

package/presets/claude/nuxt/rules/architecture/layer-barrel-exports.md

@@ -0,0 +1,72 @@
+---
+description: Two-level barrel exports for layers with a regulated public API
+paths: **/index.ts
+---
+
+# Barrel exports for layers with a public API
+
+## When to apply
+
+For **any layer** (directory, package, bounded context) that has:
+
+- a **root barrel** — single import point for external consumers;
+- deep imports into the layer **forbidden** from outside (ESLint `no-restricted-imports`, `public-imports.mdc` rules).
+
+Example alias/entry points across projects: `@/api`, `@/types`, `@/core`, `@/store`, `packages/foo`.
+
+## Two barrel levels
+
+1. **Local** — `index.ts` of a module/feature inside the layer.
+2. **Root public API** — layer barrel (e.g. `src/<layer>/index.ts`).
+
+**Inside** the layer — relative imports and paths between submodules. **Outside** — only the root barrel and **explicitly allowed** secondary entry points (if fixed in project rules, e.g. `@/types/enums`).
+
+## What to re-export outward
+
+Only symbols that **must be available** to layer consumers: public functions/services/facades, contract types, constants and helpers needed by other layers or tests.
+
+**Do not re-export:** internal adapters, mappers, transport details, intermediate objects used to assemble a facade inside the layer.
+
+Grouping in the root barrel — **per repository convention** (orient on neighboring modules of the same layer).
+
+## Agent checklist (required)
+
+When adding or substantially extending a **module inside a regulated layer**:
+
+1. Identify the layer, its **root barrel**, and extra entry points (`public-imports.mdc`).
+2. Create/update the **local** `index.ts` — public symbols only.
+3. If the layer has a **facade/aggregator** (`*ApiService.ts`, `rootReducer`, …) — wire the module there.
+4. Add a **re-export** of new public symbols in the layer’s **root barrel**.
+5. **Verify:** grep for the symbol name or path `./<Module>` in the root barrel; no deep imports from outside the layer.
+
+The module is **not ready** until the checklist passes.
+
+## How to find regulated layers in the repository
+
+1. `public-imports.mdc` rules in `.cursor/rules/`.
+2. ESLint `no-restricted-imports` — `@/<layer>/*` patterns with barrel exception.
+3. `architecture-boundaries.mdc`, project README.
+
+## In this repository
+
+| Layer | Root barrel | Import rule |
+|-------|-------------|-------------|
+| API | `api/index.ts` | `public-imports.mdc` |
+| Types | `types/index.ts` | `public-imports.mdc` (+ `@/types/enums`) |
+| Core | `core/index.ts` | ESLint: `@/core/index` |
+
+Two-level illustration (API): local `services/.../<Feature>/index.ts` → facade `*ApiService.ts` → `api/index.ts`.
+## Incorrect
+
+```ts
+// api/index.ts — leaking internals
+export { mapCardResponse } from './services/CardsApi/cardResponseMappers'
+export { rawCardsClient } from './clients/rawCardsClient'
+```
+
+## Correct
+
+```ts
+// api/index.ts — public facade only
+export { cardsApi } from './services/CardsApi'
+```

package/presets/claude/nuxt/rules/architecture/public-imports.md

@@ -0,0 +1,61 @@
+---
+description: Import domain types and API only through public barrels @/types and @/api
+paths:
+  - pages/**/*
+  - components/**/*
+  - stores/**/*
+  - api/**/*
+  - composables/**/*
+  - types/**/*
+---
+
+# Public imports (`@/types`, `@/api`)
+
+**Collisions:** type imports — `@/types` section below; API outside `api/**` — `@/api` section below (mirrors ESLint `no-restricted-imports` in `eslint.config.mjs`).
+
+## `@/types`
+
+- **Public types API** — barrel `types/index.ts`; import types only as `@/types` (or `@/types/index`).
+- **Forbidden** to bypass the barrel: `@/types/<anything>`, except enums.
+- **Enums** — only `@/types/enums` / `@/types/enums.ts`.
+- Inside `types/**` — relative imports between layer files.
+
+```typescript
+// ✅
+import type { TUserProfile } from '@/types'
+import { SomeEnum } from '@/types/enums'
+
+// ❌
+import type { TUserProfile } from '@/types/User.types'
+```
+
+New public types — re-export in `types/index.ts` per **`layer-barrel-exports.mdc`**.
+
+## `@/api`
+
+- **Public API** — barrel `api/index.ts`. Outside `api/**` — only `import … from '@/api'` (or `@/api/index`).
+- **Forbidden** from outside the layer: `@/api/<anything>`, except `@/api/index`.
+- Inside `api/**` — relative imports and `@/api/services/**`, `@/api/clients/**`.
+
+```typescript
+// ✅ in store, UI, lib outside api
+import { MedcardApiService } from '@/api'
+
+// ❌ outside api
+import { MedcardApiService } from '@/api/services/MedcardApiService/MedcardApiService'
+```
+
+New public API symbols — re-export in `api/index.ts` per **`layer-barrel-exports.mdc`**.
+## Incorrect
+
+```ts
+import type { TUserProfile } from '@/types/User.types'
+import { OrdersApi } from '@/api/services/OrdersApi'
+```
+
+## Correct
+
+```ts
+import type { TUserProfile } from '@/types'
+import { ordersApi } from '@/api'
+```

package/presets/claude/nuxt/rules/architecture/reference-features.md

@@ -0,0 +1,50 @@
+---
+description: Repository reference features — copy structure when implementing new tasks. Fill paths after init in the target repo.
+paths:
+  - pages/**/*
+  - components/**/*
+  - stores/**/*
+  - api/**/*
+  - composables/**/*
+  - types/**/*
+---
+
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features
+
+## Stack notes
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+
+## Reference table
+
+Replace **TBD** with real paths after team agreement (or on `ai-rules init` in the target repo):
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI page | **TBD** `components/pages/<Example>/` | `components/`, `*.data.ts`, `styles.ts`, barrel |
+| Store | **TBD** `stores/<example>.ts` | `defineStore`, actions, getters, types |
+| API service | **TBD** `api/services/<example>/` | service, mappers, barrel |
+| Types module | **TBD** `types/<example>/` | domain types, JSDoc, barrel export |
+| Unit tests | **TBD** next to the reference mapper/service | `*.spec.ts`, describe/it naming |
+| E2E area | **TBD** `tests/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
+
+## How to use
+
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature of the same layer and record the choice in the handoff.
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.cursor/team/conventions.md`** (and the twin tool path if both Cursor and Claude are installed). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
+
+## Related rules
+
+- `code-quality-and-refactoring.mdc` — repeat patterns, no deep-import.
+- `feature-delivery-workflow.mdc` — layer order.
+- skill `feature-delivery` — end-to-end scenario.

package/presets/claude/nuxt/rules/stack/README.md

@@ -0,0 +1,12 @@
+# Stack (Nuxt 3, Vue, TypeScript)
+
+Framework- and language-level rules.
+
+| File | Contents | Loading |
+|------|----------|---------|
+| `nuxt-app-core.md` | Stack, `pages/`/`components/`/`stores/` structure, layers | session start |
+| `script-setup-conventions.md` | `<script setup>` conventions | `paths: **/*.{vue,ts}` |
+| `no-type-assertion.md` | Limit `as` at module boundaries | on-demand |
+| `navigation-router-ui.md` | Navigation in UI components (slim) | `paths: pages/**,layouts/**,middleware/**,components/**` |
+| `navigation-router.md` | Full navigation stack audit (Nuxt file-based routing) | `paths: pages/**,layouts/**,middleware/**,nuxt.config.*` |
+| `types-jsdoc.md` | JSDoc in `types` | `paths: types/**/*.ts` |

package/presets/claude/nuxt/rules/stack/navigation-router-ui.md

@@ -0,0 +1,14 @@
+---
+paths: pages/**/*,layouts/**/*,middleware/**/*,components/**/*
+---
+
+# Navigation in UI components
+
+Before links, programmatic navigation, or URL work in UI:
+
+1. **`package.json`** of the app workspace — `nuxt` vs plain `vue-router` SPA.
+2. **Neighboring imports** in the same feature (`navigateTo`, `<NuxtLink>`, `useRouter` / `useRoute` vs `from 'vue-router'`).
+3. **Project wrappers** (`~/components/...` Link) — preferred over raw router API.
+4. **Default (preset):** Nuxt 3 file-based routing → `navigateTo` + `<NuxtLink>` + `useRouter` / `useRoute` (`nuxt-app-core.mdc`, `nuxt-pages-routing.mdc`).
+
+Full audit (route tree, hybrids, lockfile): **`navigation-router-stack.mdc`** — when editing `pages/**`, `layouts/**`, `middleware/**`, `nuxt.config.*`.

package/presets/claude/nuxt/rules/stack/navigation-router.md

@@ -0,0 +1,59 @@
+---
+paths: pages/**/*,layouts/**/*,middleware/**/*,nuxt.config.*
+---
+
+# Navigation and routing: project stack first
+
+**For any task involving navigation, page transitions, URLs, redirects, breadcrumbs, protected routes, or programmatic route changes** — before proposing code or imports, **do not** default to a “typical Vue SPA”. You must **explicitly check the target repository stack** and use **one** mechanism consistent with the project.
+
+## Dependencies: what to check first
+
+1. **`package.json`** at the app root (the package with `nuxt.config.*` / the one that builds and deploys). Inspect **`dependencies`** and, if needed, **`peerDependencies`**:
+   - **`nuxt`** — Nuxt 3 (file-based routing); version matters for API nuances (check docs for that major).
+   - **`vue-router`** without Nuxt — separate SPA routing; do not replace its API with Nuxt calls (`navigateTo`, `<NuxtLink>`) without checking.
+   - **`nuxt`** and a separate manual `createRouter` at once — may be legacy or hybrid; **do not** pick an API by default — see “Routing implementation in the project” below.
+
+2. **Monorepo / workspaces** — routing may not live in the root `package.json`. Open **`package.json` of the workspace** that holds `pages/` and `nuxt.config.*`.
+
+3. **Installation fact** — when in doubt, check the lockfile (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or `node_modules`: confirm the declared package is actually installed.
+
+## Routing implementation in the project (code and structure)
+
+Before proposing a navigation pattern, **check how it is already done in the repository**:
+
+1. **Route tree**
+   - **Nuxt 3 file-based routing:** **`pages/`** directory (`.vue`), layouts in **`layouts/`**, middleware in **`middleware/`**, `definePageMeta`.
+   - **Nuxt 4 note:** `app/` may be `srcDir` — confirm via `nuxt.config`; **do not** confuse with Next `app/` + `page.tsx`.
+   - Plain **Vue Router SPA:** route config (`router/index.ts`, `createRouter`) without Nuxt file routing.
+
+2. **Entry points and wrappers**
+   - Search the code: **`navigateTo`**, **`<NuxtLink>`**, **`useRouter` / `useRoute`** (Nuxt auto-import), **`from 'vue-router'`**, **`createRouter`**, **`RouterLink`**.
+   - Where routes are declared (Nuxt file structure vs explicit `routes` in SPA).
+
+3. **Shared project abstractions**
+   - Link wrappers (`~/components/...`, design-system Link), path helpers, route constants — **use them**, do not duplicate raw API.
+
+4. **Neighboring feature files**
+   - New navigation code — same style as pages/composables in that area (`navigateTo` / `<NuxtLink>` vs `vue-router` as in neighboring imports).
+
+## How to decide what to use (summary)
+
+1. **Dependencies** — see section above; they define the allowed package set.
+2. **Structure** — Nuxt `pages/` vs Vue Router SPA by directories and config.
+3. **Actual code** — which imports and wrappers already dominate in the app.
+
+## What to use (short matrix)
+
+| Stack | Programmatic navigation / path read | Links |
+|-------|-------------------------------------|-------|
+| **Nuxt 3 file-based routing** | `navigateTo`, `useRouter`, `useRoute`, `useRouter().push` (per Nuxt docs for your version) | `<NuxtLink>` |
+| **Vue Router SPA (no Nuxt)** | `vue-router` (`useRouter`, `useRoute`, `router.push`, …) | `<RouterLink>` / `<router-link>` |
+
+**Do not:** add `react-router-dom` or `next/navigation` / `next/link` in a Nuxt project; import Next hooks (`usePathname`, `useSearchParams` from `next/navigation`); mix manual `createRouter` and Nuxt file routing without a clear reason in the codebase.
+
+## Agent requirement
+
+- Before generating or reviewing navigation code, **briefly state the conclusion** (e.g. “dependencies: `nuxt`; code uses `<NuxtLink>` / `navigateTo` everywhere → use the same”) and follow it.
+- **Required check:** current **`dependencies`** in the relevant workspace `package.json` + **how routes and imports are already implemented** (repo search, neighboring files). Do not rely on a single signal alone (e.g. only the presence of a `pages/` folder).
+- If the stack is unclear (hybrid) — **check lockfile / installed packages** and **dominant imports**, then pick the API.
+- For **this** preset the baseline is **`nuxt-app-core.mdc`** + **`nuxt-pages-routing.mdc`**: Nuxt 3; prefer **`navigateTo`**, **`useRouter` / `useRoute`**, **`<NuxtLink>`**.

package/presets/claude/nuxt/rules/stack/no-type-assertion.md

@@ -0,0 +1,62 @@
+---
+description: Avoid type assertions via as at module boundaries (import/export)
+paths:
+  - pages/**/*
+  - components/**/*
+  - stores/**/*
+  - api/**/*
+  - composables/**/*
+  - types/**/*
+---
+
+# Do not use `as` for type assertion on export and import (except necessary cases)
+
+## What this is about
+
+This is about TypeScript **type assertion**: expressions like `value as Type`.
+
+**Not covered by this rule** (not assertion — module syntax):
+
+- rename on export: `export { foo as bar }`, `export { default as Baz } from '...'`;
+- rename on import: `import { foo as bar } from '...'`;
+- `import type { Foo as Bar }` — type alias in a type import.
+
+## Requirement
+
+- On the **public module boundary** (what is **exported** from a file / barrel, and what is immediately **assigned from imported symbols** with a forced cast) **do not use** `as Type` to “force-fit” types when normal typing would work.
+
+## Prefer instead of `as`
+
+- an explicit annotation: `const x: T = ...` / `function f(): T`;
+- **generics** on functions and classes;
+- **`satisfies`** (when you need to check compatibility without narrowing to `any`);
+- narrowing **`unknown`** after checks (type guards, `zod`, etc.);
+- fixing **source types/DTOs/mappers**, not an assertion on the way out.
+
+## When `as` is allowed
+
+- interaction with **untyped** or incorrectly typed external modules where there is no reasonable alternative;
+- narrow spots after **validation**, if a type guard still cannot be expressed without noise (prefer guard/`satisfies` anyway);
+- **`as const`** — when literal types are needed and wide inference breaks the contract (a separate mechanism; use on purpose, not as a substitute for API typing).
+- a **`catch (error)`** block after HTTP via the shared client: prefer narrowing with **`instanceof`** on the **transport error class** from `@/types` (which one — follow the existing implementation) and work with the narrowed type; bare **`as` to the same type** — only if `instanceof` is unavailable (different throw source) and deliberately.
+
+## Examples
+
+```typescript
+// ❌ Bad: assertion on exported API
+export const config = loadRaw() as AppConfig
+
+// ✅ Better: annotation + check or mapper
+export const config: AppConfig = mapToAppConfig(loadRaw())
+
+// ❌ Bad: immediately after import we “break” the type
+import { getData } from './api'
+export const data = getData() as MyDto[]
+
+// ✅ Better: type getData / wrap with a type-safe function
+```
+
+## Agent requirement
+
+On review and code generation **do not add** new `as Type` on exported entities and on the import → export chain without clear need; when possible fix the type contract at the source.
+- In stores and services when handling API errors, first consider **`instanceof`** on the transport error class from `@/types` following existing code (`http-client.mdc`, `store-pinia.mdc`).

package/presets/claude/nuxt/rules/stack/nuxt-app-core.md

@@ -0,0 +1,44 @@
+---
+description: Baseline principles, stack, and architecture for a Nuxt 3 application (preset)
+---
+
+# Stack and environment
+
+Concrete versions — **from `package.json` and configs of the target repository**. Preset frame: Nuxt 3, Vue 3, TypeScript; runner/e2e/mocks/UI/APM — as established in the repo.
+
+# Project structure
+
+| Path | Purpose |
+|------|---------|
+| `pages/**` | File-based routes |
+| `components/**` | UI components (SFC) |
+| `composables/**` | Vue `use*` facades |
+| `stores/**` | Pinia stores |
+| `api/**` | Client services + mappers (barrel) |
+| `lib/clients/**`, `api/clients/**` | HTTP (`$fetch` / ofetch) |
+| `server/api/**` | Nitro server routes (BFF) |
+| `types/**` | Domain types (barrel) |
+| `tests/e2e/**` | Playwright e2e |
+
+**Aliases:** prefer `~/`, accept `@/`, respect `#imports` (do not invent auto-import symbols). Scripts cwd — **repository root** (where `nuxt.config.*` lives), not a Next-style `app/` wrapper.
+
+# Architectural layers
+
+| Layer | Directory | Details |
+|-------|-----------|---------|
+| UI | `pages/**`, `components/**`, `layouts/**` | `vue-ui`, `architecture-boundaries-ui` |
+| Composables | `composables/**` | thin orchestration; no raw HTTP |
+| Store | `stores/**` | `store-pinia` — `defineStore` only |
+| API | `api/**` | `api-services`, `http-client` |
+| HTTP | `lib/clients/**`, `api/clients/**` | wrap `$fetch` |
+| Server | `server/api/**` | `security-nuxt`; not a substitute for `api/**` |
+| Types | `types/**` | `public-imports`, `types-jsdoc` |
+
+Boundaries — **`architecture-boundaries`**. Imports `~/types` / `@/types`, `~/api` / `@/api` — **`public-imports`**. **Forbidden:** RTK / `store-rtk`, React/RSC defaults, `app/src/**` paths as the canon.
+
+# Agent work
+
+- Architecture and imports: `architecture-boundaries`, `public-imports`
+- Features: `feature-delivery-workflow` + skill `feature-delivery`
+- After edits: **invoke** `post-change-lint` (requestable); package manager: `package-manager`
+- Copy neighbor patterns; prefer `unknown` over `any`

package/presets/claude/nuxt/rules/stack/nuxt-pages-routing.md

@@ -0,0 +1,39 @@
+---
+description: Nuxt file-based routing, layouts, middleware, page meta
+paths:
+  - "pages/**/*.{vue,ts}"
+  - "layouts/**/*.{vue,ts}"
+  - "middleware/**/*.{ts,js}"
+  - nuxt.config.*
+---
+# Nuxt pages & routing
+
+Canonical layout: **Nuxt 3 project root** — `pages/`, `layouts/`, `middleware/`.  
+Nuxt 4 may use `app/` as `srcDir`; mention only as a note — **do not** default globs/examples to Next-style `app/src/**`.
+
+## Routing
+
+- File-based routes under `pages/**`.
+- Layouts in `layouts/**`; select via `definePageMeta({ layout: '…' })`.
+- Route middleware in `middleware/**` (`defineNuxtRouteMiddleware`).
+- Navigation helpers: `<NuxtLink>`, `navigateTo`, `useRouter`, `useRoute` — not `next/link` / `next/navigation`.
+- Server/API routes: `server/api/**` (Nitro) — see `security-nuxt`; domain client services stay in `api/**`.
+
+## Data on pages
+
+- Prefer composables + Pinia for client orchestration.
+- `useFetch` / `useAsyncData` OK when that is the repo pattern — still map to domain models; no raw DTO sprawl in templates.
+- Secrets only via `runtimeConfig` server-side.
+
+## Incorrect
+
+```ts
+import { useRouter } from 'next/navigation'
+```
+
+## Correct
+
+```ts
+const router = useRouter()
+await navigateTo('/items')
+```

package/presets/claude/nuxt/rules/stack/script-setup-conventions.md

@@ -0,0 +1,12 @@
+---
+description: Prefer script setup lang=ts and idiomatic Vue function style
+paths:
+  - "**/*.{vue,ts}"
+---
+# Script setup conventions
+
+- Prefer `<script setup lang="ts">` for pages/components/layouts.
+- Named composables / helpers: follow repo naming (`useX`); export functions consistently with neighbors.
+- Prefer `const fn = () =>` / concise handlers where the file already does; do not churn style across untouched files.
+- Auto-imports (`#imports`) OK when Nuxt resolves them — do not invent symbols; verify against `.nuxt/` / docs (`vue-nuxt-anti-hallucination`).
+- Keep business orchestration in composables/stores; keep SFC scripts thin.

package/presets/claude/nuxt/rules/stack/types-jsdoc.md

@@ -0,0 +1,41 @@
+---
+description: JSDoc style for domain and transport types under types
+paths: types/**/*.ts
+---
+
+# Type documentation in `types`
+
+When adding or substantially changing types in this layer **follow the JSDoc style already used in the repository** (see examples: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+
+## Language and form
+
+- Comment text — **in Russian**, short and to the point: what the type or field means in the domain or API contract.
+- **Do not rely** on tags like `@param`, `@returns`, `@see`, `@deprecated` for type descriptions — they are **not used** in this layer; plain `/** … */` text is enough.
+
+## Exported `type` / `interface`
+
+- Immediately **before the declaration** — a `/** … */` block.
+- If you need to explain data source, constraints, or non-obvious bits — a **second paragraph** in the same block (blank line between paragraphs in JSDoc).
+- For **nested** objects in the same file, each such type gets its own block above its declaration.
+
+## Fields
+
+- Every **public** property — a **one-line** `/** … */` on the line immediately **above** the field.
+- If a field **does not come from the backend “as is”** but is computed or enriched on the frontend (mapper, selector, UI) — start the description with the **`[computed]`** prefix (as in `TUserProfile`, treatment-plan types).
+- For data formats, state that **in the text**: e.g. date `YYYY-MM-DD`, example display string in quotes.
+
+## Classes and other declarations
+
+- For **classes** (e.g. transport errors), when changing the public API — a short block above the class and **comments on public fields** by the same rules as interface properties.
+
+## `enum`
+
+- In `enums.ts` historically often **without JSDoc** on each member; for new enums a short description **above the enum itself** is OK if purpose is not obvious from the name. UI labels — as usual, via `*Names` objects next to the enum.
+
+## Agent practice
+
+- When adding a new type or field, **do not leave** new public fields unexplained if the meaning is not 100% equal to the name.
+- When editing a file that already has such comments, **keep the same style**, do not mix with English or “tag-style” blocks.
+- Do not inflate comments: one–two phrases per type, one line per field — normal; exception — a truly complex domain caveat.
+
+See also imports and barrel: `public-imports.mdc`.

package/presets/claude/nuxt/rules/testing/README.md

@@ -0,0 +1,11 @@
+# Testing
+
+Unit, e2e, Playwright agents.
+
+| File | Contents | Loading |
+|------|----------|---------|
+| `playwright-agents.md` | Planner / generator / healer — e2e structure | session start |
+| `tests-unit.md` | Unit/integration, Russian locale naming | `paths: **/*.spec.*`, `*.test.*` |
+| `tests-e2e-structure.md` | `*.cases.md`, page objects, data-testid | `paths: tests/e2e/**` |
+
+See also `.claude/agents/playwright-test-*.md` after `ai-rules init`.

package/presets/claude/nuxt/rules/testing/playwright-agents.md

@@ -0,0 +1,78 @@
+---
+description: Playwright Agents (planner/generator/healer) configuration for e2e structure in tests/e2e
+paths: tests/e2e/**/*
+---
+# Playwright Agents in this project
+
+In this repository, Playwright Agents (planner, generator, healer) **must follow the existing e2e structure**:
+
+- **Test directory**: `tests/e2e`
+- **Test plans (specs)**: `*.cases.md` files under `tests/e2e/**`
+- **Executable tests**: `*.spec.ts` files under `tests/e2e/**`
+- **Seed test**: `tests/e2e/seed.spec.ts`
+
+Do **not** introduce separate top-level `specs/` and `tests/` folders for real test coverage. Those may be used only as temporary sandboxes if explicitly requested.
+
+## Planner (test plans)
+
+When acting as a **Planner** (or working with the Playwright planner agent):
+
+- **Treat `*.cases.md` as the canonical test plan files**, equivalent to Playwright's `specs/*.md`.
+- **Location**:
+  - For a feature/domain, use the corresponding `*.cases.md` file under `tests/e2e`, e.g.:
+    - `tests/e2e/OrderHistory/order-history.cases.md`
+    - `tests/e2e/BillingReport/invoice-list.cases.md`
+- **Content requirements**:
+  - Group scenarios by feature and subfeature using headings.
+  - For each scenario include:
+    - clear title,
+    - preconditions,
+    - ordered steps,
+    - expected results.
+  - Write in concise business language, but precise enough for automatic test generation.
+- **Seed**:
+  - Assume environment is prepared by `tests/e2e/seed.spec.ts` (login, baseURL, mocks, etc.).
+
+When asked to "generate a test plan" for a feature, **create or update the appropriate `*.cases.md` file in `tests/e2e/**`**, not in a separate `specs/` folder.
+
+## Generator (tests from plans)
+
+When acting as a **Generator** (or working with the Playwright generator agent):
+
+- **Source of truth for scenarios**:
+  - Use the relevant `*.cases.md` file under `tests/e2e/**` as the test plan.
+- **Target for tests**:
+  - Generate or update `*.spec.ts` files under the same folder, e.g.:
+    - plan: `tests/e2e/OrderHistory/order-history.cases.md`
+    - tests: `tests/e2e/OrderHistory/order-history.spec.ts` (or additional `*.spec.ts` in that folder if needed).
+- **Structure**:
+  - Use `test.describe` to group by top-level plan sections (feature / user flow).
+  - Use `test(...)` titles that match scenario names from the plan.
+  - Prefer Page Object and fluent interfaces that already exist in this project, for example:
+    - `tests/e2e/OrderHistory/OrderHistoryPage.ts`
+    - shared helpers under `tests/e2e/_shared/`.
+- **Seed**:
+  - If a seed test is needed, use `tests/e2e/seed.spec.ts` as the reference for environment setup.
+
+Do **not** generate Playwright tests into a separate `tests/` folder by default. Keep all e2e tests under `tests/e2e/**` to respect project conventions.
+
+## Healer (fixing tests)
+
+When acting as a **Healer** (or working with the Playwright healer agent):
+
+- Operate only on `*.spec.ts` files under `tests/e2e/**`.
+- Use `*.cases.md` in the same folder as **documentation of the intended behavior**:
+  - Do not weaken or change business assertions in tests in a way that conflicts with the corresponding `*.cases.md`.
+  - Prefer updating locators, waits, and flow details to match the UI while keeping the scenario semantics intact.
+- When multiple specs are involved, prioritize:
+  - the spec file in the same folder as the failing test,
+  - then shared utilities in `tests/e2e/_shared/`.
+
+Healer should keep tests aligned with the existing test plans (`*.cases.md`) and with the page objects and helpers already used in the project.
+
+
+## Stack notes (Nuxt)
+
+- E2E root: `tests/e2e/`.
+- Default baseURL: `http://localhost:3000`.
+- Prefer Playwright `webServer` → `nuxt dev` or `nuxt build && nuxt preview`.