@live-change/frontend-template 0.9.203 → 0.9.205

package/.claude/skills/live-change-frontend-synchronized/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: live-change-frontend-synchronized
+description: Use synchronized and synchronizedList for autosave editing in LiveChange Vue frontends, including object vs list decision flow, identifiers mapping, and save/delete patterns
+---
+
+# Skill: live-change-frontend-synchronized (Claude Code)
+
+Use this skill when implementing or refactoring frontend editing flows that should keep local form state synchronized with backend data.
+
+## When to use
+
+- Editing one object loaded from `live(...)` with autosave or manual save.
+- Editing list items inline (for example access roles) with per-row identifiers.
+- Replacing custom `watch + api.command` autosave logic with a standard helper.
+- Choosing between `synchronized`, `synchronizedList`, and `editorData`.
+
+## Decision flow
+
+1. **One editable object** (`profile`, `note`, `settings`) -> use `synchronized`.
+2. **Editable list rows** (`accesses`, `invitations`, `requests`) -> use `synchronizedList`.
+3. **Definition-driven CRUD form with validation UI** -> use `editorData` from auto-form stack.
+
+## What counts as "editable list rows"
+
+Treat the feature as a list flow (`synchronizedList`) when most of these are true:
+
+- The UI renders rows with `v-for` and each row has editable fields.
+- Users can edit many rows inline in one screen (table/config/admin list).
+- Autosave should happen per row while the list stays reactive.
+- Each row needs its own action payload keys in addition to shared list context.
+
+In this case, wire one `synchronizedList(...)` and edit fields directly on `syncList.value`.
+Do not build a parallel `id -> synchronized(...)` map for rows.
+
+## `synchronized` pattern (object)
+
+```javascript
+import { synchronized } from '@live-change/vue3-components'
+
+const sync = synchronized({
+  source: sourceRef,
+  update: actions.service.updateThing,
+  identifiers: computed(() => ({ thing: thingId.value })),
+  recursive: true,
+  autoSave: true,
+  debounce: 600
+})
+
+const { value: editable, changed, saving, save } = sync
+```
+
+### Rules
+
+- `source` should come from `live(...)` or a computed source.
+- Keep identifiers stable and pass them through `identifiers` (plain object or `computed`).
+- Use `updateDataProperty: 'data'` for draft-like payloads where backend expects nested data.
+- Use `autoSave: false` when save must happen only after explicit confirmation.
+
+## `synchronizedList` pattern (list)
+
+```javascript
+import { synchronizedList } from '@live-change/vue3-components'
+
+const syncList = synchronizedList({
+  source: accesses,
+  update: actions.accessControl.updateSessionOrUserAndObjectOwnedAccess,
+  delete: actions.accessControl.resetSessionOrUserAndObjectOwnedAccess,
+  identifiers: { object, objectType },
+  objectIdentifiers: ({ to, sessionOrUser, sessionOrUserType }) => ({
+    access: to, sessionOrUser, sessionOrUserType, object, objectType
+  }),
+  recursive: true
+})
+
+const editableRows = syncList.value
+await syncList.delete(editableRows.value[0])
+```
+
+### Rules
+
+- `source` should be a list from `live(...)`.
+- Every item should have stable `id`.
+- Put shared context in `identifiers`, and row-specific keys in `objectIdentifiers`.
+- Edit rows through `syncList.value`; call `syncList.delete(...)` / `syncList.insert(...)` on the helper object.
+- Prefer this pattern for configuration lists, permission tables, dictionaries, and other multi-row settings editors.
+
+## Project examples to follow
+
+- `speed-dating/front/src/components/notes/NoteEditor.vue` (`synchronized` with autosave)
+- `speed-dating/front/src/components/profile/ProfileSettings.vue` (`synchronized` + `updateDataProperty: 'data'`)
+- `family-tree/front/src/components/AgreementDialog.vue` (`synchronized` with manual save)
+- `rcstreamer/front/src/configuration/AccessRequests.vue` (`synchronizedList`)
+- `rcstreamer/front/src/configuration/AccessInvitations.vue` (`synchronizedList`)
+- `rcstreamer/front/src/configuration/AccessList.vue` (`synchronizedList`)
+
+## Common mistakes
+
+- Using `synchronized` for a list of rows instead of `synchronizedList`.
+- Forgetting `objectIdentifiers` when backend update/delete actions need per-row keys.
+- Mutating raw `live(...)` list data instead of `synchronizedList(...).value`.
+- Mixing autosave helper patterns with unrelated one-shot action form patterns.

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
 
@@ -173,6 +173,19 @@ Jeśli filtr po miesiącu jest częsty, lepiej dodać indeks z bucketem miesiąc
 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).
@@ -271,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,13 @@ 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`.

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-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

@@ -6,10 +6,6 @@ alwaysApply: false
 
 # Frontend na live-change-stack – Vue 3 + PrimeVue + Tailwind
 
-## i18n i `front/locales`
-
-Za każdym razem gdy dodajesz lub zmieniasz teksty pod tłumaczenia, stosuj **`live-change-frontend-i18n-locales`**: te same klucze muszą trafić do **wszystkich** plików w **`front/locales/`** danej aplikacji (każdy język / wariant — nie tylko jeden plik).
-
 ## Stack
 
 - Vue 3 + TypeScript
@@ -23,6 +19,8 @@ Za każdym razem gdy dodajesz lub zmieniasz teksty pod tłumaczenia, stosuj **`l
 - **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:
 
@@ -68,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
@@ -187,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
@@ -211,6 +255,21 @@ 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`.
@@ -232,6 +291,13 @@ Zasady:
 />
 ```
 
+## 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-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/live-change-backend-change-triggers.md

@@ -112,6 +112,21 @@ definition.trigger({
 
 This means: when a user creates a Schedule via the UI or API, the timer is automatically set up. When they update it, the old timer is canceled and a new one created. When they delete it, the timer is canceled.
 
+## Cron-service — planning and admin UI guardrails
+
+When the domain needs **wall-clock schedules** or **fixed repeating intervals** that run a **trigger**, default to **`@live-change/cron-service`** (models **Schedule** / **Interval**, internal **timer** + **changeCron_*** lifecycle), not ad-hoc timers only.
+
+**Backend:** define the **target `definition.trigger`** in your service; put **Schedule** / **Interval** rows in **cron** with **`trigger: { name, service, properties, returnTask }`**. Rely on **`changeCron_Schedule`** / **`changeCron_Interval`** for timer repair (already implemented in cron-service).
+
+**Admin / task-frontend-style UI:** use the same integration as the reference pages:
+
+- **Create:** `ActionForm` with `service="cron"` and `action="setSchedule"` or `action="setInterval"` (relations-driven forms).
+- **List:** `RangeViewer` + `path.cron.schedules` / `path.cron.intervals` with **`reverseRange(range)`** as needed.
+- **Per row:** `.with()` → `scheduleInfo` / `intervalInfo`, `runState` (`jobType` **`cron_Schedule`** or **`cron_Interval`**, **`job`** = id), and `task.tasksByCauseAndCreatedAt` for recent runs.
+- **Delete:** `api.actions.cron.deleteSchedule` / `deleteInterval`.
+
+See **server doc** `15-cron-and-intervals.md` → section **“API used by task-frontend”** for path examples and **Schedule** field semantics (**`NaN`** = “every” for that field).
+
 ## Step 4 – Specific lifecycle triggers (alternative)
 
 If you only care about one lifecycle event, use the specific variant:

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

@@ -79,6 +79,57 @@ definition.action({
    - use model paths (`Model.path`, `Model.rangePath`, `Model.sortedIndexRangePath`, `Model.indexObjectPath`)
    - use `...App.rangeProperties` + `App.extractRange(props)` for range views
 
+### Step 2a – RangeViewer/rangeBuckets compatibility
+
+When a view is consumed by `RangeViewer` or `rangeBuckets`:
+
+- prefer `Model.sortedIndexRangePath(...)` for index-backed list views,
+- keep `App.extractRange(props)` as pagination cursor input,
+- do not reinterpret `gt/gte/lt/lte` as domain filters.
+
+Anti-patterns:
+
+- using `indexRangePath` for frontend bucket pagination flow,
+- injecting custom month/year bounds into cursor fields in frontend,
+- rewriting cursor values in backend with unrelated filter semantics.
+
+Preferred filtering strategy:
+
+1. design index prefix for frequent filters,
+2. use `App.utils.prefixRange` only as backend fallback,
+3. keep string min/max hacks as last resort.
+
+### Step 2b – Standalone indexes for union/equal sources
+
+When index rows are built from multiple equal tables (union-like flow), do not force the index into one model definition.
+
+Use `definition.index(...)` at service level (typically `indexes.js`) when:
+
+- index combines rows from two or more source tables,
+- source tables are peer entities (no natural single owner model),
+- index is a projection layer for cross-table reads.
+
+Example:
+
+```js
+definition.index({
+  name: 'Urls',
+  function: async (input, output) => {
+    await input.table('url_Redirect').onChange((obj, oldObj) =>
+      output.change(obj && mapRedirect(obj), oldObj && mapRedirect(oldObj))
+    )
+    await input.table('url_Canonical').onChange((obj, oldObj) =>
+      output.change(obj && mapCanonical(obj), oldObj && mapCanonical(oldObj))
+    )
+  }
+})
+```
+
+Decision rule:
+
+- model-local index -> `definition.model({ indexes: ... })`,
+- union/peer-source index -> standalone `definition.index(...)` in `indexes.js`.
+
 ### Example: `daoPath` (preferred, DAO-backed)
 
 ```js

package/.cursor/skills/live-change-design-models-relations.md

@@ -62,6 +62,25 @@ properties: {
 }
 ```
 
+## Step 2b – Relation arity rules (critical)
+
+Treat arity on two levels:
+
+- **Annotation arity**: can the annotation itself be a list of configs?
+- **Parent tuple arity**: can one config point to multiple parents/dimensions?
+
+| Relation | Annotation arity | Parent tuple arity |
+|---|---|---|
+| `propertyOf`, `itemOf`, `boundTo` | single config only | `what` can be one model or `[A, B, ...]` |
+| `relatedTo` | single config or config list | each config uses `what` with one model or `[A, B, ...]` |
+| `propertyOfAny`, `itemOfAny`, `boundToAny` | single config only | `to` can contain one or many names |
+| `relatedToAny` | single config or config list | each config uses `to` with one or many names |
+
+Guardrail:
+
+- valid: `propertyOf: { what: [A, B] }`
+- invalid: `propertyOf: [configA, configB]`
+
 ## Step 3 – Configure the relation
 
 ### `userItem`
@@ -110,7 +129,7 @@ so the relations/CRUD generator can treat it as a relation rather than a plain `
 
 Notes:
 
-- Usually you’ll have 1–2 parents, but the `propertyOf` list may contain **any number** of parent models (including 3+).
+- Usually you’ll have 1–2 parents, but `what` may contain **any number** of parent models (including 3+).
 - If the entity is a relation, avoid adding manual `...Id` fields in `properties` just to represent the link — CRUD generators won’t treat it as a relation.
 
 Example:
@@ -124,10 +143,9 @@ definition.model({
   properties: {
     // optional extra fields
   },
-  propertyOf: [
-    { what: CostInvoice },
-    { what: Contractor }
-  ]
+  propertyOf: {
+    what: [CostInvoice, Contractor]
+  }
 })
 ```
 

package/.cursor/skills/live-change-frontend-data-views.md

@@ -38,6 +38,21 @@ const [article, comments] = await Promise.all([
 ])
 ```
 
+- Call `usePath()` **once** at the top of `setup` (synchronously). Inside `computed`, use only the returned `path` object to build paths — **never** call `usePath()` or the legacy `path()` inside the getter (there is often no active component instance, which breaks `getCurrentInstance()` / `appContext`).
+
+Wrong:
+
+```javascript
+computed(() => usePath().blog.article({ article: id }))
+```
+
+Right:
+
+```javascript
+const path = usePath()
+const articlePath = computed(() => path.blog.article({ article: id }))
+```
+
 In templates access `.value`:
 
 ```vue