@bonesofspring/ai-rules 0.2.13 → 0.2.15

package/presets/cursor/nuxt/rules/architecture-boundaries.mdc

@@ -0,0 +1,97 @@
+---
+description: Architectural boundaries and import rules
+globs: api/**/*,stores/**/*,types/**/*,lib/**/*
+alwaysApply: false
+impact: CRITICAL
+---
+
+# Layer boundaries
+
+- **UI (`pages/**`, `components/**`, `layouts/**`)**:
+  - May import: `components/**`, `composables/**`, `stores/**` (public), types from `~/types` / `@/types` and enums from `~/types/enums` / `@/types/enums` (**only as in `public-imports.mdc`**), API contract — **only** `import … from '~/api'` / `from '@/api'` (**`public-imports.mdc`**).
+  - Must not:
+    - call the HTTP client directly (`$fetch` / ofetch outside `lib/clients`);
+    - know backend DTO details — only domain types.
+- **Store (`stores/**`)** — Pinia `defineStore` only (`store-pinia.mdc`):
+  - May import: other `stores/**` (public), services and public API entities — **only** from `~/api` / `@/api` (**`public-imports.mdc`**), types from `~/types` / `@/types` and enums from `~/types/enums` / `@/types/enums` (**`public-imports.mdc`**).
+  - Must not:
+    - depend on specific UI components / pages;
+    - work with global/window API directly.
+  - Backend calls — only through services imported from `~/api` / `@/api`; **transport** response and error types (from `@/types`, same shape as the application HTTP client) in **Pinia actions** are acceptable if the API layer is structured that way (`http-client.mdc`, `store-pinia.mdc`).
+- **API (`api/**`)** — implementation in `services/**`, `clients/**`, re-export in `api/index.ts`:
+  - Inside the layer: types from `@/types` and enums from `@/types/enums` (**`public-imports.mdc`**); imports `@/api/services/**`, `@/api/clients/**`, relative paths between layer files (`http-client.mdc`, `api-services.mdc`).
+  - Must not:
+    - pull in UI or store;
+    - mix HTTP and domain layers — use mappers.
+
+## UI and API access (`~/api` / `@/api`)
+
+- By default, scenarios that **change server state** and coordinate multiple steps go through **Pinia actions** (`defineStore`, feature pattern in the repository).
+- Direct calls to service methods imported from **`~/api` / `@/api`** from UI are allowed only in **narrow cases**: mainly **reads** or actions **without needing the result in Pinia**; same **domain types** a store action would use; **do not** duplicate an existing store scenario and **do not** pass DTOs into components.
+- Prefer structuring such calls like **neighboring features** in the repository (composable facade, `use*`, etc.).
+
+## Ports and adapters (short map)
+
+- **Inbound adapter**: UI — user input, display; depends on store and domain types, not transport.
+- **Scenario orchestration**: store (Pinia actions) — calls services, puts **domain** models in state after mapping.
+- **Outbound port (backend contract)**: public API **`~/api` / `@/api`** (barrel `api/index.ts`; implementation — in `api/services/**`, etc., see `public-imports.mdc`).
+- **Outbound adapter**: shared HTTP implementation in **`lib/clients/**`** and instances in **`api/clients/**`** (wrap `$fetch` / ofetch).
+
+## Feature as a slice
+
+- For a complex feature, align names and terms (**ubiquitous language** of the domain) in types, getters/actions, services, and UI; folder structure — as in neighboring features in the repository.
+
+# Import rules
+
+- Always use the `~/` or `@/` alias for cross-layer imports (as established in the repo); respect `#imports`.
+- Within one module/feature, relative imports are OK, but **without climbing above the feature root** (avoid `../../../`).
+- When components, composables, utilities, and other modules reach into another layer or feature, use only **public API** (barrel/index files and explicitly exported entities); no deep imports into other features' internal files; for regulated layers — **`layer-barrel-exports.mdc`** and `public-imports.mdc`; for the API layer from outside `api/**` — **`public-imports.mdc`** (only `~/api` / `@/api`).
+- When adding new code, check:
+  - if the module is reusable — it should depend only on "lower" layers (types, utils, api), not on pages.
+
+# Feature organization
+
+- For complex features (for example, `OrderCheckout`):
+  - Page / route: `pages/**` and/or `components/pages/OrderCheckoutPage/**`.
+  - Local components: `components/**` subdirectories inside the page.
+  - Related store: `stores/orderCheckout.ts` (or the neighboring Pinia module scheme in the repo).
+  - API: `api/services/OrdersApi/OrderCheckout/**` (root service name from the project scheme).
+  - Types: `types/**` with export through barrel **`types/index.ts`** (`public-imports.mdc`).
+
+# Agent requirement
+
+When adding new functionality:
+- Place files in the **appropriate layers**.
+- Check existing features with similar structure and **repeat their organization**.
+- Do not "short-circuit" layers (for example, do not call API directly from a component just to simplify).
+- **Forbidden:** RTK / Redux (`createSlice`, `createAsyncThunk`, `useDispatch`, `stores/slices/**` as the canon).
+
+## Incorrect
+
+```ts
+// UI calling HTTP client / deep service path directly
+import { httpClient } from '@/lib/clients/HttpClient'
+import { fetchOrders } from '@/api/services/OrdersApi/orders.service'
+
+export const loadOrdersInPage = async () => {
+  // bypasses store and @/api barrel
+  await httpClient.get('/orders')
+}
+```
+
+## Correct
+
+```vue
+<script setup lang="ts">
+import { storeToRefs } from 'pinia'
+import { useOrdersStore } from '~/stores/orders'
+
+const ordersStore = useOrdersStore()
+const { orders } = storeToRefs(ordersStore)
+
+// UI → Pinia action → services from ~/api
+onMounted(() => {
+  void ordersStore.loadOrders()
+})
+</script>
+```

package/presets/cursor/nuxt/rules/code-quality-and-refactoring.mdc

@@ -0,0 +1,52 @@
+---
+description: Maintain and improve code quality and architecture
+alwaysApply: true
+---
+
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
+# Match existing style
+
+- Follow existing patterns (names, structure, typing / DI / error handling); avoid drive-by formatting or renames.
+- Before a new solution: find an analog and **repeat the approach**; check the design system / UI packages; go only through the **public API** (deep imports are a reason to refactor).
+
+# Principles
+
+- **KISS:** the simplest change in the repository’s patterns.
+- **DRY + Rule of Three:** share only after the 3rd repetition (wrong abstraction costs more than duplication).
+- **YAGNI:** no APIs, flags, or “for later” layers without a current requirement.
+- **SOLID:** S — one reason to change; O — composition/new implementations; L — subtype contract; I — narrow ports; D — abstractions (ports), details in stack adapters.
+- **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
+- **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
+
+# Refactoring during changes
+
+- Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
+- Examples: shared utility/hook/mapper/use case; narrow unsafe types; split a large module; tokens instead of “magic”; deep import → public API.
+- Do not do a “big” refactor on a point task (structure/public names without a request). Break large work into minimal steps; keep the repo buildable after each step.
+
+# Agent requirement
+
+- **Boy scout:** leave the module a bit better; do not sacrifice architecture and layers for brevity.
+
+## Agent discipline (anti-sycophancy)
+
+Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
+
+- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Before "is this correct?" — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
+- Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
+- Comments = WHY only when non-obvious; ban self-referential "added for issue Y".
+- Urgency/authority: name the trade-off once, then comply — no apology loops.
+- Match verification to risk; report by what was **verified**, not attempted.
+
+Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
+
+> Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.
+
+## Stack notes
+
+- Before adding a new UI control, check existing Vue/Nuxt UI code and project packages.
+- Public API: index/barrel files and explicitly exported entities (`public-imports`, `layer-barrel-exports`).
+- Allowed examples: shared composable/utility; typing `any`/`unknown`; splitting a large SFC; CSS tokens instead of “magic” values.
+- Lint/stylelint — only **`post-change-lint`**; ESLint (vue) + Stylelint configs at repo root (e.g. `eslint.config.mjs`, `.stylelintrc*`). Disabling a rule (`eslint-disable`) — only **locally** with a short “why” comment.

package/presets/cursor/nuxt/rules/code-review-mr.mdc

@@ -0,0 +1,58 @@
+---
+description: Requirements for Cursor agents reviewing merge requests
+alwaysApply: false
+---
+
+<!-- shared-core: review/code-review-mr.md -->
+
+# Code review merge requests
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+## When to load
+
+- User asks for review/MR/diff
+- Pipeline step `code-reviewer`
+- Platform automated review (e.g. BUGBOT) when present
+
+## Checklist references (abstract)
+
+- Architecture layers and stack core rules
+- Public imports / module boundaries
+- UI conventions of the stack
+- Unit and e2e/UI test conventions
+- Post-change lint/build gate before final report
+- Design smells **in MR diff scope** — load `design-guidance`; do not expand the full Fowler catalog outside the diff
+- Pattern name (GoF) — only if the repository already uses that shape or the match is minimal
+- Principles (KISS / DRY+Ro3 / YAGNI / SOLID / CUPID) — via always-on `code-quality-and-refactoring`, do not duplicate the essay in review
+
+Concrete rule stems — in **Stack notes**.
+
+## Constraints
+
+- Focus on MR diff, not the whole repo.
+- Use local `git diff` — do not invent hosting metadata.
+- Boy scout rule: suggest fixes feasible within the MR scope.
+- No “big refactors” without an explicit request (`code-quality-and-refactoring`).
+
+## Output contract
+
+Procedure details live in skill `code-review`. Required shape:
+
+- Each finding cites **`path:line`**, the problem, impact, and a concrete fix direction.
+- Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
+- End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+### Checklist references
+
+- Architecture layers: `architecture-boundaries.mdc`, `nuxt-app-core.mdc`; network: `http-client.mdc`
+- Imports: `public-imports.mdc`, `layer-barrel-exports.mdc`
+- UI: `vue-ui.mdc`
+- Security: `security-nuxt.mdc`
+- Tests: `tests-unit.mdc`, `playwright-agents.mdc`, `tests-e2e-structure.mdc`
+- Lint gate before final report: `post-change-lint.mdc`

package/presets/cursor/nuxt/rules/css-property-order-stylelint.mdc

@@ -0,0 +1,12 @@
+---
+description: CSS property order via Stylelint (Vue SFC styles included)
+globs: "**/*.{css,scss,vue}"
+alwaysApply: false
+---
+
+# CSS property order
+
+- Follow the repo Stylelint config (property order plugin if present).
+- Applies to plain CSS/SCSS and `<style>` blocks in `.vue` SFCs.
+- Do not hand-resort entire files unrelated to the task; fix order in touched rulesets.
+- Run via **`post-change-lint`** (`lint:css`).

package/presets/cursor/nuxt/rules/design-guidance.mdc

@@ -0,0 +1,111 @@
+---
+description: Design smells (Fowler) and curated GoF patterns for agents. Load when assessing structure, smells, or pattern fit.
+globs:
+  - **/*.{ts,tsx}
+alwaysApply: false
+---
+
+<!-- shared-core: quality/design-guidance.md -->
+
+# Design guidance (smells & patterns)
+
+Glossary of **code smells** (Fowler) and **design patterns** (GoF) for agents during implement / review / debug.
+
+Apply only within the task or MR scope. Light refactor — yes; a “big” rewrite without an explicit request — no.
+
+Name a pattern **only if** the repository already does it that way or the match is minimal. Otherwise — extract/split/move without a GoF label.
+
+Does not replace always-on Principles in `code-quality-and-refactoring` (KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition, Demeter).
+
+## When to load
+
+- **Feature delivery / implement** — assess module structure, boundaries, and duplication.
+- **Code review** — smells and pattern fit **in the MR diff**, not across the whole repo.
+- **Debug** — root cause looks like wrong abstraction, Feature Envy, Message Chains, Shotgun Surgery.
+- **Light refactor only** — improvements within boy-scout / MR scope; do not expand the task for the catalog.
+
+Agents and skills load this stem via one-liner wiring — do not copy this catalog into the agent prompt.
+
+## How to use (agent rules of thumb)
+
+1. First check against Principles (always-on): is the solution simpler, is there no premature abstraction, is the public API respected.
+2. Then mark smells **in the changed files** of the task/MR; propose a fix only if it fits a light refactor.
+3. A GoF pattern is an optional label after the structure is already clear; do not start design by picking a pattern.
+4. If a smell or pattern conflicts with stack layer boundaries — stack boundaries and existing repo patterns win.
+5. Do not require renaming “for GoF” if behavior is already correct and readable.
+
+## Code smells (Fowler, curated ≤12)
+
+Table: smell → detect hint → fix hint (one line each). No mechanical refactoring menus.
+
+| # | Smell | Detect | Fix hint |
+|---|-------|--------|----------|
+| 1 | Duplicate Code | same logic in ≥2 places | dedupe after Rule of Three |
+| 2 | Long Method / Long Module | unit does too much | extract within scope; no big rewrite |
+| 3 | Feature Envy | method touches foreign data more than its own | move logic toward the data / public API |
+| 4 | Data Clumps | the same argument groups travel together | group into a type / value object |
+| 5 | Primitive Obsession | raw string/int instead of domain concepts | typed ids / value objects when the domain needs them |
+| 6 | Speculative Generality | unused hooks, flags, “for later” abstractions | remove (YAGNI) |
+| 7 | Message Chains | `a.b.c.d` chains | Demeter; facade / module public API |
+| 8 | Middle Man | class almost only forwards calls | remove pass-through **or** keep as a boundary |
+| 9 | Divergent Change | one module changes for different reasons | split by reasons to change |
+| 10 | Shotgun Surgery | one semantic change spreads across many files | consolidate responsibility |
+| 11 | Inappropriate Intimacy | access to foreign internals / private details | public API / ports / facades only |
+| 12 | Refused Bequest / Parallel Inheritance | subtype ignores base; mirrored class hierarchies | composition; do not grow parallel trees |
+
+**Skip Fowler (not in core):** Lazy Class, Incomplete Library Class, Comments-as-smell dogma, full 70+ catalog, step-by-step recipe menus.
+
+Smell conflict priority: Inappropriate Intimacy and Message Chains (module boundaries) > Duplicate Code (after Rule of Three) > Long Method inside an already correct module.
+
+## Design patterns (GoF, curated ≤8)
+
+Suggest only when repo already uses the shape or the match is minimal. Prefer extract-function over naming Strategy for the label alone.
+
+Patterns below are the **allowed minimum** for agents; the rest of GoF is Skip by default.
+
+| Pattern | When to suggest | Anti-trigger |
+|---------|-----------------|--------------|
+| Strategy | interchangeable algorithms already (or clearly soon) chosen by policy | one algorithm with no policy branching |
+| Adapter | wrap external / foreign API under a local port | extra wrapper around your own API |
+| Facade | simplify a multi-step subsystem behind a public API | facade turns into a god-object |
+| Factory Method | polymorphic creation already accepted in repo style | factory for every trivial `new` |
+| Decorator | additive behavior without exploding subclass hierarchies | decorator “for layers” with no real need |
+| Observer | events / subscriptions already exist in the architecture | homemade pub/sub with no repo precedent |
+| Template Method | shared algorithm skeleton + variable hooks | inheritance for a couple of differing lines |
+| Composite | tree of homogeneous nodes (UI/domain), as already in the repo | Composite on a flat list with no hierarchy |
+
+If unsure between two patterns — choose the simpler extract/compose without a name; the label may be added on review if the repo already speaks that way.
+
+## Skip / avoid by default
+
+| Catalog | Skip |
+|---------|------|
+| GoF | Singleton, Abstract Factory, Flyweight, Memento, Interpreter, Visitor, Bridge, Prototype |
+| GoF (conditional) | Command, Chain of Responsibility, State — mention **only if** the repo already uses them |
+| Fowler | everything beyond the 12 smells above |
+| DDD | Aggregates, bounded-context maps, event sourcing, CQRS — **not in core** |
+| DDD (pointer) | ubiquitous language anti-pattern — expand in `feature-delivery-workflow`, not here |
+| GRASP | Larman list as separate rules — skip (covered by SOLID/CUPID) |
+| Clean Code dogma | hard caps on function lines / “exactly one assert” — skip |
+
+Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agents`) — one catalog: `design-guidance`.
+
+## Out of scope for this stem
+
+- Full GoF (23) and full Fowler catalog.
+- Stack-specific recipes (module paths, lint commands) — only in the adapter **Stack notes**.
+- Security, a11y, perf — separate review rules; here only structural smells/patterns.
+- A fourth always-on rule — forbidden; this stem is requestable / agent-load only.
+
+## Cross-refs
+
+- Always-on Principles: `code-quality-and-refactoring`.
+- DIP / ports vs adapters: stack `architecture-boundaries` (stack details — in adapter Stack notes).
+- Ubiquitous language: `feature-delivery-workflow` (lineage).
+- MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
+- Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).
+
+## Stack notes
+
+- Prefer hooks/mappers over HOC or new pattern names when the repo already extracts that way.
+- Suggest Strategy/Adapter only when ports or policy branching already exist in `**`.

package/presets/cursor/nuxt/rules/feature-delivery-workflow.mdc

@@ -0,0 +1,83 @@
+---
+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.
+alwaysApply: false
+---
+
+<!-- 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/cursor/nuxt/rules/http-client.mdc

@@ -0,0 +1,15 @@
+---
+description: HTTP client wrapper for Nuxt — $fetch/ofetch, one stack, error contracts
+globs: lib/clients/**/*.ts,api/clients/**/*.ts,api/**/*.ts
+alwaysApply: false
+---
+
+# HTTP client
+
+- One HTTP stack for the app: wrap **`$fetch` / ofetch** (or the client already used in `lib/clients/**`).
+- Do not mix ad-hoc `fetch`/`axios` in features if a shared client exists.
+- Services in `api/**` call the wrapper — UI/stores do not own transport.
+- Map responses to domain models in services/mappers before Pinia.
+- Errors: use project transport error types from `~/types` / `@/types`; narrow with `instanceof` when available.
+- Base URL / auth headers: from `runtimeConfig` / existing client factories — do not hardcode secrets.
+- Calling Nitro `/api/*` from the client is fine when that is the BFF pattern — still through services.

package/presets/cursor/nuxt/rules/layer-barrel-exports.mdc

@@ -0,0 +1,74 @@
+---
+description: Two-level barrel exports for layers with a regulated public API
+globs: **/index.ts
+alwaysApply: false
+impact: MEDIUM
+---
+
+# 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/cursor/nuxt/rules/navigation-router-stack.mdc

@@ -0,0 +1,61 @@
+---
+description: Choose the navigation API for the project stack (Nuxt 3 vs Vue Router SPA)
+globs: pages/**/*,layouts/**/*,middleware/**/*,nuxt.config.*
+alwaysApply: false
+---
+
+# 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/cursor/nuxt/rules/navigation-router-ui.mdc

@@ -0,0 +1,16 @@
+---
+description: Navigation in UI components — short guide (full stack audit — navigation-router-stack.mdc)
+globs: pages/**/*,layouts/**/*,middleware/**/*,components/**/*
+alwaysApply: false
+---
+
+# 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/cursor/nuxt/rules/no-type-assertion-as-import-export.mdc

@@ -0,0 +1,60 @@
+---
+description: Avoid type assertions via as at module boundaries (import/export)
+globs:
+  - api/**/*
+  - stores/**/*
+  - types/**/*
+alwaysApply: false
+---
+
+# 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`).