@live-change/frontend-template 0.9.201 → 0.9.203

package/.claude/rules/live-change-backend-architecture.md

@@ -1,6 +1,6 @@
 ---
 description: Rules for LiveChange backend service architecture and directory structure
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 ---
 
 # LiveChange backend – service architecture (Claude Code)
@@ -104,17 +104,17 @@ services: [
 
 ## Inspecting services with `describe`
 
-Use the `describe` CLI command to see what the framework generated from your definitions (models, views, actions, triggers, indexes, events):
+Use the `describe` CLI command to see what the framework generated from your definitions (models, views, actions, triggers, indexes, events). From the app root (directory with `.node-version` / `.nvmrc`), run Node via **fnm** so the toolchain matches the project — see rule `live-change-node-toolchain-fnm`.
 
 ```bash
 # All services overview
-node server/start.js describe
+fnm exec -- node server/start.js describe
 
 # One service in YAML (shows all generated code)
-node server/start.js describe --service myService --output yaml
+fnm exec -- node server/start.js describe --service myService --output yaml
 
 # Specific entity
-node server/start.js describe --service myService --model MyModel --output yaml
+fnm exec -- node server/start.js describe --service myService --model MyModel --output yaml
 ```
 
 This is especially useful after using relations (`userItem`, `itemOf`, `propertyOf`) — `describe` shows all the auto-generated views, actions, triggers, and indexes.

package/.claude/rules/live-change-backend-event-sourcing.md

@@ -1,6 +1,6 @@
 ---
 description: Event-sourcing data flow rules — emit events for DB writes, use triggerService for cross-service writes
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 ---
 
 # LiveChange backend – event-sourcing data flow (Claude Code)
@@ -155,7 +155,7 @@ Without `waitForEvents: true`, the action returns immediately and events are pro
 When a model uses relations (`userItem`, `itemOf`, `propertyOf`, etc.), the relations plugin auto-generates CRUD triggers. Use `describe` to discover them:
 
 ```bash
-node server/start.js describe --service myService --output yaml
+fnm exec -- node server/start.js describe --service myService --output yaml
 ```
 
 Common auto-generated trigger patterns:

package/.claude/rules/live-change-backend-models-and-relations.md

@@ -1,6 +1,6 @@
 ---
 description: Rules for defining models, relations, indexes and access control in LiveChange
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 ---
 
 # LiveChange backend – models and relations (Claude Code)
@@ -203,7 +203,7 @@ definition.model({
 })
 ```
 
-Use `node server/start.js describe --service myService --model MyModel --output yaml` to see all fields including auto-added ones.
+Use `fnm exec -- node server/start.js describe --service myService --model MyModel --output yaml` (from the app root, with fnm — see `live-change-node-toolchain-fnm`) to see all fields including auto-added ones.
 
 ## Indexes
 
@@ -223,6 +223,45 @@ indexes: {
 
 In other services, the same index may be visible with a prefixed name such as `myService_Model_byDeviceAndStatus`.
 
+### When index should be outside a model
+
+If an index is a union/projection over multiple peer tables (no single natural owner model), do not force it into `model.indexes`.
+
+- Use service-level `definition.index(...)` (prefer a dedicated `indexes.js` file).
+- Keep `model.indexes` for indexes semantically owned by one model.
+
+### Function index serialization constraint
+
+Function indexes (both `definition.index({ function })` and model `indexes: { name: { function } }`) are **serialized via `toString()`** and run on a remote server. All helpers, mappers, and variables used inside the function **must be defined inside the function body**. References to outer scope (module-level functions, imports, closures) will be `undefined` at runtime.
+
+```js
+// ❌ BROKEN — mapper defined outside, invisible after serialization
+const mapper = obj => ({
+  id: obj.name + '_' + obj.id, to: obj.id
+})
+indexes: {
+  byDerived: {
+    function: async (input, output, { tableName }) => {
+      const table = await input.table(tableName)
+      await table.map(mapper).to(output)  // mapper is undefined!
+    }
+  }
+}
+
+// ✅ CORRECT — mapper defined inside the function
+indexes: {
+  byDerived: {
+    function: async (input, output, { tableName }) => {
+      const mapper = obj => ({
+        id: obj.name + '_' + obj.id, to: obj.id
+      })
+      const table = await input.table(tableName)
+      await table.map(mapper).to(output)
+    }
+  }
+}
+```
+
 ## Access control on relations
 
 - Always set `readAccessControl` and `writeAccessControl` on relations (`userItem`, `itemOf`, `propertyOf`).

package/.claude/rules/live-change-frontend-e2e-lifecycle.md

@@ -0,0 +1,42 @@
+---
+description: Stable node:test E2E lifecycle with env, withBrowser and e2eSuite
+globs: **/e2e/**/*.{js,ts}
+---
+
+# Frontend E2E lifecycle
+
+Use this pattern in LiveChange E2E tests based on `node:test`.
+
+## Required files
+
+- `e2e/env.ts` with `getTestEnv()` and `disposeTestEnv()`
+- `e2e/withBrowser.ts` that closes context/browser in `finally`
+- `e2e/e2eSuite.ts` that wraps each test file in `describe(...)` + `after(...)`
+- `e2e/*.test.ts` wrapped in exactly one `e2eSuite(...)`
+
+## Teardown rule
+
+- Never register `after(...process.exit(...))` inside shared `e2e/env.ts`.
+- Register final `process.exit(0)` only in `e2eSuite.ts` after calling `disposeTestEnv()`.
+- Keep startup failure `process.exit(1)` in `getTestEnv()` catch block.
+
+## Minimal suite wrapper
+
+```ts
+import { after, describe } from 'node:test'
+import { disposeTestEnv } from './env.js'
+
+export function e2eSuite(name: string, define: () => void): void {
+  describe(name, () => {
+    after(async () => {
+      await disposeTestEnv()
+      process.exit(0)
+    })
+    define()
+  })
+}
+```
+
+## Running commands
+
+When running E2E commands, use `fnm exec -- ...` so Node matches `.node-version` / `.nvmrc`.

package/.claude/rules/live-change-frontend-i18n-locales.md

@@ -0,0 +1,25 @@
+---
+description: Keep all locale files under front/locales in sync when adding or changing i18n strings
+globs: **/front/locales/**/*.{json,js,ts}, **/front/src/**/*.{vue,js,ts}
+---
+
+# Frontend i18n – every file in `front/locales`
+
+When you add or change **user-visible strings** (labels, messages, buttons, errors, page titles, etc.) that go through **vue-i18n** or the project’s locale files, you must update **every** locale resource in that app’s **`front/locales/`** directory — not only one language.
+
+## Required workflow
+
+1. **Identify the app root** for the frontend you are editing (the folder whose tree contains `front/src` and `front/locales`).
+2. **List all locale files** in `front/locales/` for that app (`en.json`, `pl.json`, `en.js`, `pl.js`, `landing-en.json`, … — whatever exists).
+3. **Add or update the same keys** in **each** of those files. Structure and nesting must stay consistent across languages (same key paths).
+4. **Do not** add a new key to a single locale file and leave others missing — that breaks builds or shows raw keys at runtime.
+
+## Translations you are unsure about
+
+- Prefer a correct string in the primary locales (e.g. `en` + `pl`) when the product supports them.
+- For other files, use a sensible placeholder, copy from English, or add a clearly marked temporary string — but **still add the key** everywhere so nothing is omitted.
+
+## Scope
+
+- Applies to any work under `front/src` that introduces or changes translated text, and to direct edits in `front/locales`.
+- If a project uses multiple locale formats (`.json` and `.js`), update **all** files that participate in i18n for that app, not only one extension.

package/.claude/rules/live-change-frontend-vue-primevue.md

@@ -7,6 +7,10 @@ globs: **/front/src/**/*.{vue,js,ts}
 
 Use these rules when working on frontends that talk to LiveChange backends.
 
+## i18n and `front/locales`
+
+Whenever you introduce or change translated strings, follow **`live-change-frontend-i18n-locales`**: add the same keys to **all** files in that app’s **`front/locales/`** directory (every language / variant — not only one file).
+
 ## Stack
 
 - Vue 3 + TypeScript
@@ -48,6 +52,25 @@ In templates, use the `.value` of these refs:
 </template>
 ```
 
+## One-time fetches – `useFetch` (not `api.get` with Path)
+
+When you need a **one-time fetch** (not a live subscription), use `useFetch`:
+
+```js
+import { usePath, useFetch } from '@live-change/vue3-ssr'
+const path = usePath()
+
+const data = await useFetch(path.paperInvoice.invoiceFileInfo({ invoiceFile: fileId }))
+```
+
+**WARNING:** `path.service.view({ params })` returns a **Path object** (with `.what`, `.more`, `.to` properties), not a raw array. Do NOT pass it to `api.get()` — it will silently fail or produce wrong results.
+
+| Pattern | Correct? |
+|---|---|
+| `useFetch(path.svc.view({ ... }))` | **Yes** — handles Path objects |
+| `api.get(['svc', 'view', { ... }])` | **Yes** — raw array, low-level |
+| `api.get(path.svc.view({ ... }))` | **NO** — Path object, will break |
+
 ## Commands and forms – choosing the right pattern
 
 There are 4 ways to execute backend actions. Use the right one:
@@ -65,6 +88,51 @@ Decision flow:
 2. Is it editing a model record (create/update)? → **Yes**: use `editorData`. **No**: use `actionData`.
 3. Only use `<command-form>` for the simplest throwaway cases.
 
+## Autosave helpers – `synchronized` and `synchronizedList`
+
+Use these helpers when editing reactive data from `live(...)`:
+
+- Use `synchronized` for a single editable object.
+- Use `synchronizedList` for editable list rows.
+- Use shared context in `identifiers` and row-level keys in `objectIdentifiers`.
+- For draft payloads, use `updateDataProperty: 'data'`.
+
+Treat a screen as an editable list when:
+
+- The UI uses `v-for` and each row has editable fields.
+- Users edit many rows inline in one table/config/admin view.
+- Autosave should persist changes row-by-row.
+- Backend actions require shared list context plus row-specific keys.
+
+For these cases, create one `synchronizedList(...)` and edit row fields through `syncList.value`.
+Do not maintain a separate `id -> synchronized(...)` map for list rows.
+
+```js
+const sync = synchronized({
+  source: sourceRef,
+  update: actions.service.updateThing,
+  identifiers: { thing: thingId },
+  recursive: true,
+  autoSave: true,
+  debounce: 600
+})
+
+const syncList = synchronizedList({
+  source: rowsRef,
+  update: actions.service.updateRow,
+  delete: actions.service.deleteRow,
+  identifiers: { object, objectType },
+  objectIdentifiers: row => ({ row: row.to, object, objectType }),
+  recursive: true
+})
+```
+
+Typical list flows:
+
+- role/permission editors,
+- dictionary/configuration tables,
+- multi-row settings pages with inline edits.
+
 ## Form validation feedback
 
 Every field in a form using `editorData` or `actionData` **must** show validation errors. Never use bare `InputText`, `Dropdown`, or other PrimeVue inputs without error feedback.
@@ -234,6 +302,34 @@ path.blog.articles({})
 
 Access: `article.authorProfile?.firstName`. Works with both `live()` and `RangeViewer`.
 
+## Range lists with reactive filters
+
+If range list `pathFunction` depends on reactive filters (month/status/search/company), prefer `ReactiveRangeViewer`.
+
+Guidelines:
+
+- do not rely on mutating `pathFunction` in `RangeViewer`
+- avoid page-local workaround patterns with ad-hoc `:key`
+- use `sourceKey` as an explicit reload trigger
+- if layout stability matters, set `preserveHeightOnReload`
+
+```vue
+<ReactiveRangeViewer
+  :pathFunction="transactionsPathRange"
+  :sourceKey="JSON.stringify({ accountId, month: filterByMonth ? month : null })"
+  :preserveHeightOnReload="true"
+  :canLoadTop="false"
+  canDropBottom
+/>
+```
+
+## Range cursor guardrails (`RangeViewer` / `rangeBuckets`)
+
+- For index-backed list views, backend should expose `sortedIndexRangePath`-based range views.
+- Never override `range.gt/gte/lt/lte` inside frontend `pathFunction`.
+- Keep cursor fields from RangeViewer intact; pass domain filters (`month`, `year`, `status`) as separate params.
+- If filtering seems to require manual cursor rewriting, move logic to backend index design (or `prefixRange` fallback), not frontend hacks.
+
 ## WorkingZone for async actions
 
 `ViewRoot` wraps every page in `<WorkingZone>`. Use `inject('workingZone')` for non-form button actions:
@@ -306,12 +402,12 @@ export const sitemap = sitemapEntry(App, createRouter, routerSitemap, config)
 
 ## Discovering views and actions with `describe`
 
-Use the CLI `describe` command to find available views (for `live()`) and actions (for `api.command` / `editorData` / `actionData`):
+Use the CLI `describe` command to find available views (for `live()`) and actions (for `api.command` / `editorData` / `actionData`). From the app root, use **fnm exec** so Node matches `.node-version` / `.nvmrc` (see `live-change-node-toolchain-fnm`).
 
 ```bash
-node server/start.js describe --service blog
-node server/start.js describe --service blog --view articlesByCreatedAt --output yaml
-node server/start.js describe --service blog --action createMyUserArticle --output yaml
+fnm exec -- node server/start.js describe --service blog
+fnm exec -- node server/start.js describe --service blog --view articlesByCreatedAt --output yaml
+fnm exec -- node server/start.js describe --service blog --action createMyUserArticle --output yaml
 ```
 
 This is the fastest way to discover what paths and actions are available, including those auto-generated by relations.

package/.claude/rules/live-change-node-toolchain-fnm.md

@@ -0,0 +1,39 @@
+---
+description: Run Node, npm, npx, tsx with fnm exec using project .node-version or .nvmrc
+---
+
+# Node.js toolchain – use `fnm exec`
+
+Do **not** rely on whatever Node.js version the agent sandbox or shell happens to use. That often differs from the project and breaks the LiveChange stack, tests, and `describe`.
+
+Use **fnm** so the version from the project dotfiles (`.node-version` or `.nvmrc`) is selected.
+
+## Required pattern
+
+Work in the directory that contains the relevant `.node-version` or `.nvmrc` (app or package root). Prefix **every** `node`, `npm`, `npx`, `corepack`, or `tsx` invocation with:
+
+```bash
+fnm exec -- <command and arguments>
+```
+
+Examples:
+
+```bash
+fnm exec -- node server/start.js describe --service myService --output yaml
+fnm exec -- npm test
+fnm exec -- npm run build
+fnm exec -- npx eslint .
+fnm exec -- tsx scripts/example.ts
+```
+
+If the dotfile lives only under a subfolder (e.g. `auto-firma/app/`), `cd` there first, then run `fnm exec -- ...`.
+
+## When this applies
+
+- Tests, CI scripts, linters, builds
+- Framework CLI: `describe`, dev servers, migrations, anything touching `@live-change/*`
+- Any `npm` / `node` / `npx` / `tsx` for this monorepo or its subprojects
+
+## If `fnm` is unavailable
+
+Tell the user to install fnm or align the environment; do not proceed assuming an arbitrary `node` on `PATH` is correct.

package/.claude/skills/create-skills-and-rules/SKILL.md

@@ -137,6 +137,22 @@ globs: **/front/src/**/*.{vue,js,ts}
 | `description` | What this rule covers (used for matching) |
 | `globs` | File patterns that trigger this rule (e.g. `**/*.js`, `**/services/**/*.js`) |
 
+### Backend / LiveChange service rules — standard `globs`
+
+Rules for **server-side** LiveChange code (models, actions, triggers, service layout) should use a **comma-separated** `globs` line so they still match when a project stores services under different folder names (many teams copy `.cursor/rules` into other repos):
+
+```yaml
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
+```
+
+| Pattern | Covers |
+|---|---|
+| `**/services/**/*.js` | Trees such as `live-change-stack/services/<service>/` |
+| `**/server/**/*.js` | Any nested `server/` directory (e.g. `app/server/`, `packages/foo/server/`) |
+| `server/**/*.js` | Backend rooted at top-level `server/` |
+
+Frontend rules keep their own globs (e.g. `**/front/src/**/*.{vue,js,ts}`). Do not drop the `server` variants for backend-only rules — otherwise Cursor will miss files after a layout change.
+
 ### Body structure
 
 ```markdown
@@ -181,6 +197,7 @@ alwaysApply: false
 - Do NOT quote glob patterns in frontmatter
 - Keep rules short (target 25 lines, max 50 lines for best Cursor performance)
 - The `.mdc` extension is required for Cursor
+- For **backend** LiveChange rules, use the same **`globs`** standard as in Claude rules: `**/services/**/*.js, **/server/**/*.js, server/**/*.js`
 
 ## Step 5 – Register rules in OpenCode (`opencode.json`)
 
@@ -198,8 +215,12 @@ OpenCode reads `.claude/skills/<name>/SKILL.md` natively for skills (no extra st
 
 When you **create a new rule**, add its path to the `instructions` array in `opencode.json`.
 
+Project rule **`live-change-node-toolchain-fnm`** should stay **first** (or early) in `instructions` so agents always load the requirement to run `node`, `npm`, `npx`, and `tsx` via `fnm exec` using `.node-version` / `.nvmrc`.
+
 When you **create a new skill**, no `opencode.json` change is needed — OpenCode discovers skills from `.claude/skills/<name>/SKILL.md` automatically.
 
+When a skill or rule shows shell examples that invoke **`node`**, **`npm`**, **`npx`**, or **`tsx`**, use the **`fnm exec -- …`** form (see `.claude/rules/live-change-node-toolchain-fnm.md` and skill `live-change-node-toolchain-fnm`).
+
 **Important:** OpenCode ignores the `globs` frontmatter from Claude Code rules. All instructions listed in `opencode.json` are always loaded.
 
 ## Step 6 – Mirror Cursor skills (`.cursor/skills/<name>.md`)
@@ -239,10 +260,12 @@ done
 
 ## Checklist
 
+- [ ] Shell examples for Node/npm use `fnm exec --` per `live-change-node-toolchain-fnm`
 - [ ] Directory created: `.claude/skills/<name>/SKILL.md`
 - [ ] Frontmatter has both `name` (matching dir) and `description`
 - [ ] `.cursor/skills/<name>.md` mirrored (flat file, same content)
 - [ ] `.claude/rules/*.md` created (if rule)
 - [ ] `.cursor/rules/*.mdc` created with `globs` + `alwaysApply` (if rule)
+- [ ] Backend rules use standard `globs`: `**/services/**/*.js, **/server/**/*.js, server/**/*.js` (when the rule targets LiveChange server code)
 - [ ] `opencode.json` `instructions` array updated (if new rule)
 - [ ] Sub-projects updated (automation, auto-firma)

package/.claude/skills/live-change-design-actions-views-triggers/SKILL.md

@@ -7,6 +7,12 @@ description: Design actions, views, triggers with indexes and batch processing p
 
 Use this skill to design **actions, views, and triggers** in LiveChange services while making good use of indexes and avoiding full-table scans.
 
+## Reads vs writes (CQRS-like)
+
+**Frontend (Vue):** load data with `usePath` + `live` / `useFetch` on **views**. Do **not** use `api.command` or `useActions()` only to fetch, preview, or compute display-only values — add a `definition.view` on the server and read it on the client.
+
+**Backend (services):** **`definition.view`** is the read surface (including computed or preview data). From triggers/actions use **`app.viewGet`** / **`app.serviceViewGet`** when you need the same view layer as the client, or direct model/index reads where appropriate. **Actions and triggers** change state via **`emit`** / **`trigger`** / **`triggerService`**, not via fake “read-only actions.”
+
 ## When to use
 
 - You add or change actions on existing models.

package/.claude/skills/live-change-frontend-command-forms/SKILL.md

@@ -19,15 +19,16 @@ Before using this skill, pick the right approach:
 |---|---|
 | `editorData` | **Editing model records** (create/update). Drafts, validation, `AutoField`. See `live-change-frontend-editor-form` skill. |
 | `actionData` | **One-shot action forms** (not CRUD). Submit once → done. See `live-change-frontend-action-form` skill. |
-| `api.command` | **Single button or programmatic calls** (no form fields). This skill, Step 1. |
+| `api.command` | **Mutations only** — single button or programmatic calls that **change persisted state** (no form fields). This skill, Step 1. Not for loading or previewing data (use views + `live` / `useFetch`; see `live-change-frontend-data-views`). |
 | `<command-form>` | **Avoid.** Legacy. Only for trivial prototypes without drafts or `AutoField`. This skill, Step 2. |
 
 **Decision flow:**
 
-1. Does the user fill in form fields? → **No**: use `api.command` (this skill).
-2. Is it editing a model record? → **Yes**: use `editorData`.
-3. Is it a one-shot action? → **Yes**: use `actionData`.
-4. Only use `<command-form>` for the simplest throwaway cases.
+1. Do you only need to **read** data (including previews)? → **Use views** (`live` / `useFetch`), not this skill.
+2. Does the user fill in form fields? → **No**: use `api.command` (this skill) **only if** the operation **mutates** state.
+3. Is it editing a model record? → **Yes**: use `editorData`.
+4. Is it a one-shot action? → **Yes**: use `actionData`.
+5. Only use `<command-form>` for the simplest throwaway cases.
 
 ## Step 1 – Use `api.command` directly
 

package/.claude/skills/live-change-frontend-data-views/SKILL.md

@@ -14,6 +14,8 @@ Use this skill when you build **reactive data views** using `usePath`, `live`, `
 - You need to load related objects alongside the main data.
 - You need to restrict data loading for unauthenticated users.
 
+**Do not use `api.command` / `useActions()` to load data.** Commands are for **mutations**. For every read (lists, details, previews, “next number”), use **views** with `live` or `useFetch` as in this skill.
+
 ## Step 1 – Basic data loading with computed paths
 
 When paths depend on reactive values (route params, props), wrap them in `computed()`:

package/.claude/skills/live-change-frontend-e2e-lifecycle/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: live-change-frontend-e2e-lifecycle
+description: Set up stable node:test E2E lifecycle with env, withBrowser and e2eSuite
+---
+
+# Skill: live-change-frontend-e2e-lifecycle
+
+Use this skill when creating or refactoring LiveChange frontend E2E tests.
+
+## Goal
+
+Avoid flaky teardown where only the first test file runs because shared env teardown calls `process.exit`.
+
+## Step 1 - Build shared env helper
+
+Create `e2e/env.ts` with:
+
+- `getTestEnv()` that starts `TestServer` once and memoizes with `envPromise`
+- `disposeTestEnv()` that resets memoized state and disposes server
+- fallback cleanup:
+
+```ts
+process.on('beforeExit', () => {
+  void disposeTestEnv()
+})
+```
+
+Keep startup failure `process.exit(1)` inside `getTestEnv()` catch.
+
+Do not add `after(...process.exit(...))` to this file.
+
+## Step 2 - Isolate browser per test
+
+Create `e2e/withBrowser.ts` with Playwright setup/teardown in `try/finally`:
+
+- call `getTestEnv()` once per test execution
+- open browser/context/page
+- close context and browser in `finally`
+
+## Step 3 - Add suite-level teardown
+
+Create `e2e/e2eSuite.ts`:
+
+```ts
+import { after, describe } from 'node:test'
+import { disposeTestEnv } from './env.js'
+
+export function e2eSuite(name: string, define: () => void): void {
+  describe(name, () => {
+    after(async () => {
+      await disposeTestEnv()
+      process.exit(0)
+    })
+    define()
+  })
+}
+```
+
+## Step 4 - Wrap tests
+
+Each `e2e/*.test.ts` file should use one wrapper:
+
+```ts
+import test from 'node:test'
+import { e2eSuite } from './e2eSuite.js'
+
+e2eSuite('example-suite', () => {
+  test('renders page', async () => {
+    // test body
+  })
+})
+```
+
+## Step 5 - Verify
+
+Run from project root with `fnm exec`:
+
+```bash
+fnm exec -- npm run e2e
+```
+
+Confirm multiple test files execute and process exits only after full suite teardown.

package/.claude/skills/live-change-node-toolchain-fnm/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: live-change-node-toolchain-fnm
+description: Run node, npm, npx, tsx and framework CLI with fnm exec so .node-version and .nvmrc are respected
+---
+
+# Skill: Node toolchain with fnm
+
+Use this skill whenever you run **Node**, **npm**, **npx**, **tsx**, or **corepack** in this repo (tests, `describe`, dev servers, scripts). Agents must not use the default sandbox Node; use **fnm exec** so the version from dotfiles applies.
+
+## When to use
+
+- Running `npm test`, `npm run …`, linters, builds
+- `node server/start.js describe` or any framework entry
+- `tsx` for TypeScript scripts
+- Any subprocess that would invoke `node` or `npm` for a project with `.node-version` / `.nvmrc`
+
+## Step 1 – Find the right directory
+
+Locate the nearest project root that has `.node-version` or `.nvmrc` for the task (often the app folder, e.g. `auto-firma/app/`).
+
+`cd` to that directory before running commands so fnm reads the correct file.
+
+## Step 2 – Prefix with fnm exec
+
+```bash
+fnm exec -- node server/start.js describe --service myService --output yaml
+fnm exec -- npm test
+fnm exec -- npx vitest
+fnm exec -- tsx ./tools/something.ts
+```
+
+The part after `--` is the same command you would run manually with the correct Node active.
+
+## Step 3 – Nested monorepo paths
+
+If you are in the repo root but the dotfile is only under `some-app/`:
+
+```bash
+cd some-app && fnm exec -- npm test
+```
+
+## If fnm is missing
+
+Do not fall back to bare `node` / `npm` for framework work. Report that fnm is required (or document a one-off alternative the user approved).

package/.cursor/rules/live-change-backend-actions-views-triggers.mdc

@@ -138,6 +138,41 @@ definition.view({
 })
 ```
 
+### Widoki zakresowe: prefiksy indeksów i opcjonalne filtry
+
+W `sortedIndexRangePath(indexName, keyPrefix, range)` najpierw działa `keyPrefix`, a dopiero potem `range` (`gt/gte/lt/lte`) na pełnym kluczu indeksu.
+
+To oznacza:
+
+- nie przekazuj surowych wartości pola (np. samej daty miesiąca) do `gt/lt`, jeśli klucz zaczyna się od innych części
+- filtr domenowy (`month`, `state`, `company`) przekazuj jako osobny parametr widoku
+- `range` zostaw do paginacji/cursora (RangeViewer i podobne mechanizmy)
+
+```js
+definition.view({
+  name: 'bankTransactionsByBankAccountAndDate',
+  properties: {
+    bankAccount: { type: String },
+    month: { type: String },
+    ...App.rangeProperties
+  },
+  async daoPath({ bankAccount, month, ...props }) {
+    const range = App.extractRange(props)
+    if(month) {
+      const prefix = [bankAccount, month].map(v => JSON.stringify(v)).join(':')
+      return BankTransaction.rangePath(App.utils.prefixRange(range, prefix, prefix + ':'))
+    }
+    return BankTransaction.sortedIndexRangePath('byBankAccountAndDate', [bankAccount], range)
+  }
+})
+```
+
+Jeśli filtr po miesiącu jest częsty, lepiej dodać indeks z bucketem miesiąca (`byBankAccountAndMonthAndDate`) i użyć:
+
+```js
+BankTransaction.sortedIndexRangePath('byBankAccountAndMonthAndDate', [bankAccount, month], range)
+```
+
 ## Triggery – online/offline i batchowanie
 
 - Triggery są do reakcji na zdarzenia (np. zmiana stanu sesji, start serwera).