@bonesofspring/ai-rules 0.2.13 → 0.2.15

package/presets/cursor/svelte/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 Svelte UI code and project packages.
+- Public API: index/barrel files and explicitly exported entities under `$lib` (`public-imports`, `layer-barrel-exports`).
+- Allowed examples: shared facade/utility; typing `any`/`unknown`; splitting a large `.svelte`; CSS tokens instead of “magic” values.
+- Lint/stylelint — only **`post-change-lint`**; ESLint (`eslint-plugin-svelte`) + Stylelint configs at SvelteKit root (e.g. `eslint.config.js` / `eslint.config.mjs`, `.stylelintrc*`). Disabling a rule (`eslint-disable`) — only **locally** with a short “why” comment.

package/presets/cursor/svelte/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`, `svelte-app-core.mdc`; network: `http-client.mdc`
+- Imports: `public-imports.mdc`, `layer-barrel-exports.mdc`
+- UI: `svelte-ui.mdc`
+- Security: `security-sveltekit.mdc`
+- Tests: `tests-unit.mdc`, `playwright-agents.mdc`, `tests-e2e-structure.mdc`
+- Lint gate before final report: `post-change-lint.mdc`

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

@@ -0,0 +1,12 @@
+---
+description: CSS property order via Stylelint (Svelte SFC styles included)
+globs: "**/*.{css,scss,svelte}"
+alwaysApply: false
+---
+
+# CSS property order
+
+- Follow the repo Stylelint config (property order plugin if present).
+- Applies to plain CSS/SCSS and `<style>` blocks in `.svelte` 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/svelte/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,svelte}"
+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/svelte/rules/feature-delivery-workflow.mdc

@@ -0,0 +1,55 @@
+---
+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`, `svelte-app-core.mdc`.
+
+Canonical paths: `src/routes/**`, `src/lib/{components,stores,api,clients,types}/**`, `tests/e2e/**`. Aliases: `$lib` preferred; `@/` if configured. State: `store-svelte` (runes primary; legacy stores secondary).
+
+## Checklist (work order)
+
+1. **Domain types** — `src/lib/types/**`, barrel (`public-imports`, `layer-barrel-exports`); JSDoc — `types-jsdoc`.
+2. **API contract** — DTOs where the repo uses them; domain types in `$lib/types`.
+3. **Mappers** — DTO → domain in `*responseMappers.ts` (`api-services`).
+4. **Services** — clients `src/lib/clients/**`, barrel `$lib/api` (`api-services`, `http-client`). No `fetch` from UI/store.
+5. **State** — `src/lib/stores/**` / runes (`store-svelte`); actions → `$lib/api`. **Not** RTK / Pinia.
+6. **UI** — `src/routes/**`, `src/lib/components/**`; data via store / facades / `load`.
+7. **Unit** — colocated `*.spec.ts` (Vitest + Testing Library Svelte).
+8. **E2E** — `tests/e2e/<Area>/<plan>.cases.md` + `*.spec.ts`.
+9. **Gate** — `post-change-lint`: `lint:js`, `lint:css`, `check`.
+
+## Partial scenarios
+
+| Task | Minimum |
+|------|---------|
+| API + types only | Types, service, mappers, `$lib/api` barrel; unit for mapper. |
+| Store only | Store/runes actions on `$lib/api`. |
+| UI only | Store/`load` data; no HTTP/DTO. |
+| E2E only | `*.cases.md` + spec; page object. |
+
+## Anti-patterns
+
+- DTO in UI or untyped store.
+- HTTP from a component / store bypassing the service.
+- Deep-import `$lib/api/services/**` from UI/store.
+- `{...props}` / `$$restProps` without discipline — `no-rest-props-spread`.
+- RTK / Pinia / Vue / Nuxt APIs as defaults.
+- Load `design-guidance` when assessing structure / smells.
+
+## Zone → rules matrix
+
+| Zone | Rules |
+|------|-------|
+| `src/lib/clients/**` | `http-client`, `tests-unit` |
+| `src/lib/api/**` | `api-services`, `layer-barrel-exports`, `http-client` |
+| `src/lib/stores/**` | `store-svelte`, `architecture-boundaries`, `public-imports` |
+| `src/lib/components/**`, `src/routes/**` | `svelte-ui`, `no-rest-props-spread`, `public-imports` |
+| `src/lib/types/**` | `public-imports`, `types-jsdoc`, `layer-barrel-exports` |
+| `tests/e2e/**` | `tests-e2e-structure`, `playwright-agents` |

package/presets/cursor/svelte/rules/http-client.mdc

@@ -0,0 +1,16 @@
+---
+description: HTTP client wrapper for SvelteKit — fetch, one stack, error contracts
+globs: src/lib/clients/**/*.ts,src/lib/api/**/*.ts
+alwaysApply: false
+---
+
+# HTTP client
+
+- One HTTP stack for the app: wrap **`fetch`** (or the shared client already in `src/lib/clients/**`).
+- Do not mix ad-hoc `axios`/`ky` in features if a shared client exists.
+- Services in `src/lib/api/**` call the wrapper — UI/stores do not own transport.
+- In `load` / form actions, prefer the provided `event.fetch` for same-origin SSR cookie forwarding when calling own endpoints.
+- Map responses to domain models in services/mappers before stores/runes.
+- Errors: use project transport error types from `$lib/types`; narrow with `instanceof` when available.
+- Base URL / auth: from `$env/*` / existing client factories — do not hardcode secrets.
+- Calling relative `/api/*` (`+server.ts` BFF) from the client is fine when that is the repo pattern — still through services.

package/presets/cursor/svelte/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/svelte/rules/navigation-router-stack.mdc

@@ -0,0 +1,40 @@
+---
+description: SvelteKit navigation APIs — $app/navigation, goto, invalidate
+globs: src/routes/**/*,svelte.config.*
+alwaysApply: false
+---
+
+# Navigation (stack)
+
+For this preset the canon is **SvelteKit** (`svelte-app-core`, `sveltekit-routing`).
+
+## Check in the repo
+
+1. `package.json` workspace with `svelte.config.*` — `@sveltejs/kit` / `svelte` majors.
+2. How neighbors already navigate: `goto`, `invalidate`, `beforeNavigate`, `<a href>`, wrappers.
+3. Do not mix in Next (`next/navigation`) or Nuxt (`navigateTo`, `<NuxtLink>`) by default.
+
+## API
+
+| Need | Prefer |
+|------|--------|
+| Programmatic navigate | `goto` from `$app/navigation` |
+| Refresh load data | `invalidate` / `invalidateAll` |
+| Guards | `beforeNavigate` / `afterNavigate` |
+| Links in UI | see `navigation-router-ui` |
+
+Verify exports against installed `@sveltejs/kit` — mark `// VERIFY` if unsure (`svelte-sveltekit-anti-hallucination`).
+
+## Incorrect
+
+```ts
+import { useRouter } from 'next/navigation'
+await navigateTo('/items')
+```
+
+## Correct
+
+```ts
+import { goto } from '$app/navigation'
+await goto('/items')
+```

package/presets/cursor/svelte/rules/navigation-router-ui.mdc

@@ -0,0 +1,25 @@
+---
+description: SvelteKit link patterns in UI — a href, active state, prefetch
+globs: src/lib/components/**/*,src/routes/**/*
+alwaysApply: false
+---
+
+# Navigation (UI)
+
+- Prefer native **`<a href="…">`** (and design-system Link wrappers that render anchors).
+- Active state: follow repo pattern (`page.url`, `$app/state` / `$app/stores` as version allows — verify).
+- Prefetch: use Kit data-sveltekit-* attributes / patterns already in the repo — do not invent.
+- Do not use `next/link`, `<NuxtLink>`, or `RouterLink` as defaults in this preset.
+- Programmatic navigation from UI handlers → `goto` (`navigation-router-stack`).
+
+## Incorrect
+
+```svelte
+<a on:click|preventDefault={() => location.href = '/x'}>Go</a>
+```
+
+## Correct
+
+```svelte
+<a href="/x">Go</a>
+```

package/presets/cursor/svelte/rules/no-rest-props-spread.mdc

@@ -0,0 +1,32 @@
+---
+description: Ban undisciplined rest props / $$restProps bulk spread in Svelte
+globs: "**/*.svelte"
+alwaysApply: false
+---
+
+# No rest-props spread
+
+- Prefer **explicit props** via `$props()` (Svelte 5) or typed props — name what the component accepts.
+- Do **not** default to `{...props}` / `$$restProps` / bulk forwarding of unknown bags onto DOM or child components.
+- Narrow exceptions OK when following an established neighbor pattern (e.g. design-system polymorphic wrapper) — document why in a short comment.
+- Analogue of next `no-props-spread` / nuxt `no-v-bind-spread` — **do not** ship those stems in this preset.
+
+## Incorrect
+
+```svelte
+<script lang="ts">
+  let props = $props()
+</script>
+
+<button {...props}>…</button>
+```
+
+## Correct
+
+```svelte
+<script lang="ts">
+  let { label, onclick }: { label: string; onclick?: () => void } = $props()
+</script>
+
+<button type="button" {onclick}>{label}</button>
+```

package/presets/cursor/svelte/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/**/*
+  - src/lib/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 slices and services when handling API errors, first consider **`instanceof`** on the transport error class from `@/types` following existing code (`http-client.mdc`, `store-svelte.mdc`).

package/presets/cursor/svelte/rules/package-manager.mdc

@@ -0,0 +1,18 @@
+---
+description: Before terminal package commands, detect the repository package manager and use only that one
+alwaysApply: true
+---
+
+# Package manager (terminal)
+
+Before **`npm install` / `yarn` / `pnpm` / `bun`** and **`… run …`**, detect the repository package manager and **use only that one**.
+
+## How to detect
+
+1. **`packageManager`** in `package.json` (SvelteKit root / workspace root where scripts / `svelte.config.*` live).
+2. **Lockfile** beside it: `yarn.lock` → yarn; `pnpm-lock.yaml` → pnpm; `package-lock.json` → npm; `bun.lock(b)` → bun.
+3. If ambiguous — where `node_modules` is and which lockfile CI uses.
+
+## Stack notes
+
+Working directory for scripts — **SvelteKit root** (directory with `svelte.config.*`), **not** Next `app/` and do not assume `nuxt.config.*`. Examples: `yarn lint:js`, `pnpm run check`. Do not guess — check the files.

package/presets/cursor/svelte/rules/playwright-agents.mdc

@@ -0,0 +1,80 @@
+---
+description: Playwright Agents (planner/generator/healer) configuration for e2e structure in tests/e2e
+globs: tests/e2e/**/*
+alwaysApply: false
+---
+
+# 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 (SvelteKit)
+
+- E2E root: `tests/e2e/`.
+- Default baseURL: `http://localhost:5173`.
+- Prefer Playwright `webServer` → `vite dev` or `vite build && vite preview`.