@live-change/frontend-template 0.9.201 → 0.9.204

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

@@ -1,6 +1,6 @@
 ---
 description: Rules for implementing actions, views, and triggers in LiveChange services
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 alwaysApply: false
 ---
 
@@ -54,9 +54,9 @@ definition.action({
 
 ## Widoki – ogólne zasady
 
-- Widok ma być prostym, czytelnym wejściem do danych:
-  - korzystaj z indeksów (`indexObjectGet`, `indexRangeGet`),
-  - nie implementuj skomplikowanej logiki w widokach, jeśli można ją przenieść do akcji.
+- Widok ma być **kanałem odczytu** (DAO, indeksy, agregacje, wyliczenia). Logika odczytu należy do widoku (ew. funkcji pomocniczej wywołanej z `daoPath` / `get`), a nie do akcji „tylko po to, żeby zwrócić dane bez zmiany stanu”.
+- W implementacji ścieżek korzystaj z indeksów (`indexObjectGet`, `indexRangeGet`) zamiast pełnych skanów.
+- Odczyt vs zapis (CQRS-like): [live-change-backend-views-vs-triggers-for-reads-writes.mdc](./live-change-backend-views-vs-triggers-for-reads-writes.mdc).
 
 ## Widoki – reguła: `get` + `observable` zawsze razem
 
@@ -138,6 +138,54 @@ 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)
+```
+
+### Guardrails dla widoków pod RangeViewer/rangeBuckets
+
+- Dla list paginowanych po indeksie preferuj `Model.sortedIndexRangePath(indexName, keyPrefix, App.extractRange(props))`.
+- Nie stosuj semantyki `indexRangePath` dla widoków konsumowanych przez bucketowe UI zakresowe.
+- `gt/gte/lt/lte` zostaw wyłącznie jako kursor paginacji, nie jako filtry domenowe.
+- Dla filtrów typu miesiąc/rok/status najpierw projektuj indeks z odpowiednim prefiksem.
+- `App.utils.prefixRange` traktuj jako fallback backendowy, gdy zmiana indeksu nie jest możliwa.
+
+### Guardrail dla indeksów standalone
+
+- Gdy indeks łączy równorzędne strumienie danych (union wielu tabel), definiuj go jako serwisowy `definition.index(...)` (najlepiej w osobnym `indexes.js`), a nie jako `model.indexes` przypisany do przypadkowego modelu.
+- `model.indexes` stosuj tylko wtedy, gdy semantycznym właścicielem indeksu jest jeden model.
+
 ## Triggery – online/offline i batchowanie
 
 - Triggery są do reakcji na zdarzenia (np. zmiana stanu sesji, start serwera).
@@ -236,6 +284,12 @@ definition.trigger({
 
 Sprawdzaj `data`/`oldData`: oba obecne = update, tylko `data` = create, tylko `oldData` = delete.
 
+## Cron-service — harmonogramy, interwały i UI admina
+
+- Dla wykonywania **triggerów** wg **czasu ściennego** lub **stałego interwału** używaj **`@live-change/cron-service`** (**Schedule** / **Interval**) wraz z **task-service** — nie planuj „tylko timera” bez modeli cron i cyklu życia **`changeCron_Schedule`** / **`changeCron_Interval`**.
+- Wzorzec admina (jak **task-frontend**): **`setSchedule`** / **`setInterval`** przez **`ActionForm`**, listy przez **`path.cron.schedules`** / **`path.cron.intervals`**, wzbogacanie wierszy **`.with()`** o **`scheduleInfo`** / **`intervalInfo`**, **`runState`** (`jobType` **`cron_Schedule`** lub **`cron_Interval`**), **`task.tasksByCauseAndCreatedAt`**; usuwanie przez **`deleteSchedule`** / **`deleteInterval`**.
+- Pola czasu **Schedule** (**minute**, **hour**, **day**, **dayOfWeek**, **month**): **`NaN`** = „każdy” na danym poziomie — szczegóły w **`15-cron-and-intervals.md`** (sekcja **API used by task-frontend**).
+
 ## Wzorzec „pending + resolve” (asynchroniczny wynik)
 
 - Używaj, gdy akcja w serwisie musi poczekać na wynik z zewnętrznego procesu (np. urządzenie, worker).

package/.cursor/rules/live-change-backend-architecture.mdc

@@ -1,6 +1,6 @@
 ---
 description: Rules for LiveChange backend service architecture and directory structure
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 alwaysApply: false
 ---
 

package/.cursor/rules/live-change-backend-event-sourcing.mdc

@@ -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
 alwaysApply: false
 ---
 

package/.cursor/rules/live-change-backend-models-and-relations.mdc

@@ -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
 alwaysApply: false
 ---
 
@@ -36,6 +36,29 @@ properties: {
 }
 ```
 
+## Arity relacji (bardzo ważne)
+
+Rozróżniaj dwa poziomy:
+
+- **arity adnotacji** — czy można podać listę konfiguracji
+- **arity rodziców w konfiguracji** — `what: [A, B]` lub `to: ['owner', 'topic']`
+
+| Relacja | Arity adnotacji | Arity rodziców |
+|---|---|---|
+| `propertyOf` | jedna konfiguracja | `what` może być pojedyncze lub tablica modeli |
+| `itemOf` | jedna konfiguracja | `what` może być pojedyncze lub tablica modeli |
+| `boundTo` | jedna konfiguracja | `what` może być pojedyncze lub tablica modeli |
+| `relatedTo` | jedna lub wiele konfiguracji | w każdej konfiguracji `what` może być pojedyncze lub tablica modeli |
+| `propertyOfAny` | jedna konfiguracja | `to` może mieć jedną lub wiele nazw |
+| `itemOfAny` | jedna konfiguracja | `to` może mieć jedną lub wiele nazw |
+| `boundToAny` | jedna konfiguracja | `to` może mieć jedną lub wiele nazw |
+| `relatedToAny` | jedna lub wiele konfiguracji | w każdej konfiguracji `to` może mieć jedną lub wiele nazw |
+
+Przykłady:
+
+- poprawnie: `propertyOf: { what: [A, B] }`
+- niepoprawnie: `propertyOf: [configA, configB]`
+
 ## `userItem` – zasób należący do użytkownika
 
 Używaj, gdy model należy do zalogowanego użytkownika.
@@ -123,7 +146,7 @@ Wtedy:
 
 - **nie** przechowuj „drugiej strony” jako zwykłego `contractorId` (albo ogólnie `someId`) w `properties`
 - **nie** dodawaj ręcznie pól `...Id` w modelu relacyjnym, jeśli to ma być relacja – to utrudnia generatorowi CRUD/relacji poprawne wnioskowanie o powiązaniach
-- zamiast tego zdefiniuj relacje jako `propertyOf` do **każdego** z modeli, które mają być rodzicami relacji
+- zamiast tego zdefiniuj jedną relację `propertyOf` z `what: [ModelA, ModelB, ...]`
 
 To jest istotne, bo generator CRUD/relacji rozumie wtedy, że encja jest powiązaniem pomiędzy dwiema encjami, a nie „zwykłym obiektem z polem id”.
 
@@ -138,10 +161,9 @@ definition.model({
   properties: {
     // dodatkowe pola relacji (opcjonalnie)
   },
-  propertyOf: [
-    { what: CostInvoice },
-    { what: Contractor }
-  ]
+  propertyOf: {
+    what: [CostInvoice, Contractor]
+  }
 })
 ```
 
@@ -186,7 +208,7 @@ Relacje automatycznie dodają **pola identyfikatorów** i **indeksy** do modelu.
 | `propertyOfAny: { ownerTypes: [...] }` | `ownerType`, `owner` | `byOwner` (hash) |
 | `boundTo: { what: Device }` | `device` | `byDevice` (hash) |
 
-Dla relacji z wieloma rodzicami (np. `propertyOf: [{ what: A }, { what: B }]`) tworzone są wszystkie kombinacje indeksów (`byA`, `byB`, `byAAndB`).
+Dla relacji z wieloma rodzicami (np. `propertyOf: { what: [A, B] }`) tworzone są wszystkie kombinacje indeksów (`byA`, `byB`, `byAAndB`).
 
 ## `propertyOfAny` — typy rodzica (`{name}Types`)
 
@@ -249,6 +271,46 @@ indexes: {
 
 Poza serwisem indeks bywa widoczny pod nazwą z prefiksem serwisu, np. `myService_Model_byDeviceAndStatus`.
 
+### Kiedy indeks ma być poza modelem
+
+Jeśli indeks jest unią/projekcją danych z kilku równorzędnych tabel (bez jednego naturalnego właściciela), nie wciskaj go do `model.indexes`.
+
+- Użyj serwisowego `definition.index(...)`, najlepiej w osobnym `indexes.js`.
+- To dotyczy szczególnie indeksów łączących różne typy encji w jeden strumień odczytu.
+
+### Indeksy `function` dla pól wyliczanych
+
+Gdy część klucza indeksu nie istnieje jako zwykłe pole modelu (np. `month` wyliczany z `date`), użyj indeksu `function` zamiast `property`.
+
+Zasady:
+
+- buduj stabilny klucz jako `JSON.stringify(part1):JSON.stringify(part2):... + '_' + id`
+- zwracaj obiekty `{ id, to }`, gdzie `to` wskazuje źródłowy rekord
+- preferuj `table.map(mapper).to(output)` zamiast ręcznego `.onChange(...output.change...)`
+- `map()` automatycznie odfiltrowuje `null`, więc mapper może zwracać tylko docelowy obiekt
+
+```js
+indexes: {
+  byBankAccountAndMonthAndDate: {
+    function: async (input, output, { tableName }) => {
+      const table = await input.table(tableName)
+      const mapper = obj => ({
+        id: [
+          obj.bankAccount,
+          obj.date?.slice(0, 7),
+          obj.date
+        ].map(v => JSON.stringify(v)).join(':') + '_' + obj.id,
+        to: obj.id
+      })
+      await table.map(mapper).to(output)
+    },
+    parameters: {
+      tableName: definition.name + '_BankTransaction'
+    }
+  }
+}
+```
+
 ## Access control na relacjach
 
 - Zawsze ustawiaj `readAccessControl` i `writeAccessControl` na relacjach (`userItem`, `itemOf`, `propertyOf`), zamiast polegać na domyślnym zachowaniu.

package/.cursor/rules/live-change-backend-views-vs-triggers-for-reads-writes.mdc

@@ -0,0 +1,28 @@
+---
+description: LiveChange backend — views/viewGet for reads; actions/triggers + emit for writes (CQRS-like)
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend — widoki do odczytu, akcja/trigger do zapisu
+
+Na serwerze **inne ścieżki niż na froncie**: nie ma `live` / `useFetch` — odczyt definiujesz jako **`definition.view`** i ewentualnie wywołujesz go z kodu przez **`app.viewGet`** / **`app.serviceViewGet`**.
+
+## Odczyt
+
+- **Widok** (`definition.view`) — jedyny kanał wystawienia danych do klienta (DAO, indeksy, wyliczenia, `fetch` zewnętrzny). Może zwracać dane złożone lub wyliczone (np. podgląd „następnego numeru”).
+- **Z kodu serwera** (trigger, akcja, batch):
+  - `await app.viewGet('viewName', { ...properties })` — widok **w tym samym** serwisie co `app`.
+  - `await app.serviceViewGet('otherService', 'viewName', { ...properties })` — widok w **innym** serwisie.
+- Bezpośredni odczyt modelu (`Model.get`, `indexObjectGet`, …) jest OK tam, gdzie nie potrzebujesz warstwy widoku/access control widoku — ale **nie** zamieniaj tego na „akcję tylko po to, żeby coś zwrócić”.
+
+## Zapis / zmiana stanu
+
+- **Akcja** (`definition.action`) i **trigger** (`definition.trigger`) — walidacja, orchestracja, **`emit`** do eventów, **`trigger`** / **`triggerService`** do zapisu zgodnie z [live-change-backend-event-sourcing.mdc](./live-change-backend-event-sourcing.mdc).
+- Nie dodawaj `definition.action`, której jedynym celem jest zwrócenie danych **bez** trwałej zmiany stanu — użyj **widoku**.
+
+## Antywzorzec
+
+- Akcja/command po stronie klienta tylko po to, żeby pobrać podgląd — błąd projektu po obu stronach: na backendzie powinien być **widok**, na froncie `live`/`useFetch` (reguła frontendowa).
+
+Szczegóły: `live-change-stack/docs/docs/server/07-views.md`, `06-actions.md`, `08-triggers.md`. API klienta (Vue) — `live-change-stack/docs/docs/frontend/04-logic-and-data-layer.md`, nie ta reguła.

package/.cursor/rules/live-change-dao-protocol.mdc

@@ -0,0 +1,47 @@
+---
+description: Zasady komunikacji przez surowy protokół DAO (C++, Python, inne klienty)
+globs: *.cpp, *.py, *.rs, *.go
+---
+
+# LiveChange DAO Protocol Arguments
+
+When communicating with the LiveChange framework using the raw `@live-change/dao` protocol (e.g., from C++, Python, Rust, Go, or any other non-JS client), you MUST ALWAYS pass arguments as an **array**.
+
+The framework treats DAO request and observable arguments like function arguments and uses the spread operator (`...args`) to pass them to the underlying action or view functions. If you pass an object instead of an array, the server will throw a `TypeError: Spread syntax requires ...iterable[Symbol.iterator] to be a function`.
+
+Even if an action or view expects a single object as its parameter, that object MUST be wrapped in a single-element array.
+
+## C++ Example (using nlohmann/json)
+
+### Incorrect ❌
+```cpp
+nlohmann::json args = {
+  {"pairingKey", "123"},
+  {"connectionType", "device"}
+};
+connection->request({"serviceName", "actionName"}, args, settings);
+```
+
+### Correct ✅
+```cpp
+// Wrap the object in an array
+auto args = {
+  nlohmann::json::object({
+    {"pairingKey", "123"},
+    {"connectionType", "device"}
+  })
+};
+connection->request({"serviceName", "actionName"}, args, settings);
+```
+
+Or explicitly:
+```cpp
+nlohmann::json args = nlohmann::json::array({
+  nlohmann::json::object({
+    {"pairingKey", "123"},
+    {"connectionType", "device"}
+  })
+});
+```
+
+Always double-check that your `args` payload is an array before sending it over the DAO connection.

package/.cursor/rules/live-change-frontend-e2e-lifecycle.mdc

@@ -0,0 +1,15 @@
+---
+description: Stable node:test E2E lifecycle with env, withBrowser and e2eSuite
+globs: **/e2e/**/*.{js,ts}
+alwaysApply: false
+---
+
+# Frontend E2E lifecycle
+
+- Keep teardown out of shared `e2e/env.ts`.
+- Never use `after(...process.exit(...))` in `env.ts`.
+- Add `disposeTestEnv()` in `env.ts` and call it from `process.on('beforeExit', ...)`.
+- Put `after(async () => { await disposeTestEnv(); process.exit(0) })` in `e2eSuite.ts`.
+- Wrap each `e2e/*.test.ts` file in one `e2eSuite('<suite-name>', () => { ... })`.
+- Keep startup failure `process.exit(1)` in `getTestEnv()` catch.
+- Run test commands with `fnm exec -- ...`.

package/.cursor/rules/live-change-frontend-i18n-locales.mdc

@@ -0,0 +1,26 @@
+---
+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}
+alwaysApply: false
+---
+
+# 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/.cursor/rules/live-change-frontend-views-not-commands-for-reads.mdc

@@ -0,0 +1,30 @@
+---
+description: LiveChange frontend — use views (live/useFetch) for reads; commands only for mutations
+globs: **/front/**/*.{vue,js,ts}
+alwaysApply: false
+---
+
+# LiveChange frontend — odczyt przez widoki, nie przez command
+
+Ten sam **model mentalny** co na backendzie (odczyt vs zapis), ale **inne API**: na froncie nie ma `app.viewGet` — klient korzysta ze **ścieżek widoków** z `usePath()`.
+
+## Odczyt danych
+
+- Buduj ścieżkę: `usePath()` (tylko synchronicznie w `setup`) → `path.<service>.<viewName>({ ...params })`; w `computed` używaj już utworzonego obiektu `path`, nie wywołuj ponownie `usePath()` / `path()`.
+- Subskrypcja: `live(computed(() => path...))` albo `await Promise.all([live(...), ...])`.
+- Jednorazowo: `useFetch(path.service.view({ ... }))` (np. w handlerze, po uploadzie).
+- Dla niezależnych odczytów uruchamiaj `live(...)` równolegle (`Promise.all`), a sekwencyjnie tylko gdy drugi path zależy od wyniku pierwszego.
+- W `Path.with(...)` buduj deklaratywnie ścieżki; do branchingu po typie/polu używaj `$switch`, nie runtime `if` na callbacku `.with`.
+
+Nie używaj `api.command` ani `useActions()` do „załadowania” danych, podglądu, wyliczenia tylko do UI, ani „jakiego będzie następny numer” — to **zawsze** powinno iść przez **widok** (`definition.view` po stronie serwera) i `live` / `useFetch` po stronie klienta.
+
+## Mutacja stanu
+
+- `api.command(['service', 'actionName'], props)` lub `useActions()` → wywołanie **akcji** zmieniającej trwały stan (create/update/delete przez eventy itd.).
+- `workingZone` i spinner przy commandach mają sens przy **zapisie**, nie przy odczycie.
+
+## Antywzorzec
+
+- Wywołanie akcji/command tylko po to, żeby dostać zwrócony string (np. podgląd numeru faktury) **bez** zmiany bazy — **źle**. Zamiast tego dodaj **widok** zwracający ten podgląd i pobierz go przez `live` / `useFetch`.
+
+Szczegóły API: `live-change-stack/docs/docs/frontend/04-logic-and-data-layer.md`. Backend (`app.viewGet`, triggery): reguła `live-change-backend-views-vs-triggers-for-reads-writes.mdc` — nie stosuj jej w plikach Vue.

package/.cursor/rules/live-change-frontend-vue-primevue.mdc

@@ -19,6 +19,8 @@ alwaysApply: false
 - **Nie** używaj `ref(null)` + `onMounted` do ładowania danych.
 - Dane ładuj w `setup`/`script setup` przez `await Promise.all(...)` na `live(path()....)`.
 - Rodzic powinien owijać stronę w `<Suspense>` (w projektach live-change robi to zazwyczaj `ViewRoot` globalnie).
+- Sekwencyjnego `await live(...)` używaj tylko wtedy, gdy drugi path zależy od wyniku pierwszego.
+- Gdy zależność da się opisać przez `.with(...)`, preferuj jedno zapytanie Path DSL zamiast imperatywnego łączenia wyników.
 
 Przykład:
 
@@ -64,6 +66,50 @@ Schemat decyzji:
 2. Edytuje rekord modelu (create/update)? → **Tak**: użyj `editorData`. **Nie**: użyj `actionData`.
 3. `<command-form>` tylko do najprostszych jednorazowych przypadków.
 
+## Autosave helpery – `synchronized` i `synchronizedList`
+
+Używaj helperów dla danych z `live(...)`:
+
+- `synchronized` dla pojedynczego obiektu do edycji.
+- `synchronizedList` dla edytowalnych list (wierszy).
+- Kontekst wspólny przekazuj przez `identifiers`, a identyfikatory wiersza przez `objectIdentifiers`.
+- Dla draftów z payloadem zagnieżdżonym używaj `updateDataProperty: 'data'`.
+
+Kiedy traktować ekran jako listę:
+
+- UI ma `v-for` z wieloma edytowalnymi wierszami (tabela/lista konfiguracji/admin).
+- Użytkownik edytuje wiele rekordów inline, a zapis ma działać per wiersz.
+- Akcje backendowe potrzebują wspólnego kontekstu listy i kluczy konkretnego wiersza.
+
+W takich przypadkach stosuj jeden `synchronizedList(...)` i edytuj dane bezpośrednio przez `syncList.value`.
+Dla takich list nie buduj osobnej mapy `id -> synchronized(...)`.
+
+```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
+})
+```
+
+Przykłady ekranów, gdzie to dotyczy:
+
+- listy uprawnień i ról,
+- słowniki i konfiguracje wielowierszowe,
+- tabele administracyjne z inline edycją pól.
+
 ### `api.command`
 
 ```js
@@ -183,6 +229,8 @@ const articlePath = computed(() => path.blog.article({ article: unref(articleId)
 const [article] = await Promise.all([live(articlePath)])
 ```
 
+`usePath()` wywołuj synchronicznie w `setup` i zapisz wynik w zmiennej `path`. W getterze `computed` buduj tylko `path.<service>.<view>(...)` — nie wywołuj ponownie `usePath()` ani aliasu `path()` w środku `computed` (brak aktywnej instancji → błąd przy `appContext`).
+
 Dla warunkowego ładowania (np. tylko gdy zalogowany), zwróć wartość falsy:
 
 ```js
@@ -207,6 +255,49 @@ path.blog.articles({})
 
 Dostęp: `article.authorProfile?.firstName`. Działa zarówno z `live()` jak i `RangeViewer`.
 
+### Guardrails Path DSL (`.with`, `$switch`)
+
+- Callback `.with(item => ...)` traktuj jako deklarację query DSL, nie jako kod biznesowy wykonywany na realnym rekordzie.
+- W callbacku `.with` nie rób side effects, `api.command`, ani imperatywnego `if/else` porównującego pola proxy.
+- Dla warunkowego wyboru ścieżki używaj `item.field.$switch({...}).$bind('target')`.
+
+```js
+path.accounting.settlementsByTransaction({ transactionType, transaction, range })
+  .with(settlement => settlement.subjectType.$switch({
+    invoice_CostInvoice: path.invoice.costInvoice({ costInvoice: settlement.subject }),
+    invoice_IncomeInvoice: path.invoice.incomeInvoice({ incomeInvoice: settlement.subject }),
+    hr_CivilContract: path.hr.civilContract({ civilContract: settlement.subject })
+  }).$bind('subjectDoc'))
+```
+
+## Listy zakresowe z reaktywnymi filtrami
+
+Jeśli `pathFunction` dla listy zakresowej zależy od reaktywnych filtrów (np. miesiąc/status/szukaj), preferuj `ReactiveRangeViewer`.
+
+Zasady:
+
+- nie polegaj na samej zmianie `pathFunction` w `RangeViewer`
+- nie rozrzucaj workaroundów typu ręczne `:key` po stronach
+- użyj `sourceKey` jako jawnego triggera przeładowania
+- gdy UX wymaga stabilności układu, ustaw `preserveHeightOnReload`
+
+```vue
+<ReactiveRangeViewer
+  :pathFunction="transactionsPathRange"
+  :sourceKey="JSON.stringify({ accountId, month: filterByMonth ? month : null })"
+  :preserveHeightOnReload="true"
+  :canLoadTop="false"
+  canDropBottom
+/>
+```
+
+## Guardrails dla kursora zakresu (`RangeViewer` / `rangeBuckets`)
+
+- Dla list opartych o indeks backend powinien udostępniać widoki oparte o `sortedIndexRangePath`.
+- Nigdy nie nadpisuj `range.gt/gte/lt/lte` we frontendowym `pathFunction`.
+- Pole `range` zostaw jako kursor paginacji; filtry domenowe (`month`, `year`, `status`) przekazuj osobno.
+- Jeśli pojawia się pokusa ręcznego przepisywania kursora, przenieś logikę do projektu indeksu po stronie backendu (ew. fallback `prefixRange`), nie do hacków we froncie.
+
 ## WorkingZone dla akcji asynchronicznych
 
 `ViewRoot` opakowuje każdą stronę w `<WorkingZone>`. Używaj `inject('workingZone')` dla akcji przycisków poza formularzami:

package/.cursor/rules/live-change-node-toolchain-fnm.mdc

@@ -0,0 +1,40 @@
+---
+description: Run Node, npm, npx, tsx with fnm exec using project .node-version or .nvmrc
+alwaysApply: true
+---
+
+# 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/.cursor/rules/live-change-service-structure.mdc

@@ -1,6 +1,6 @@
 ---
 description: LiveChange service file structure — every service must be a directory with separate definition.js, index.js, etc.
-globs: server/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 alwaysApply: true
 ---
 

package/.cursor/skills/create-skills-and-rules.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)