cabloy 5.1.207 → 5.1.209

package/.cabloy-version

@@ -1 +1 @@
-5.1.207
+5.1.209

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.1.209
+
+### Features
+
+- Add draft recovery.
+
+## 5.1.208
+
+### Improvements
+
+- Update the README and quickstart documentation.
+- Update the changelog for version 5.1.207.
+
 ## 5.1.207
 
 ### Features

package/README.md

@@ -134,6 +134,7 @@ Use the root [package.json](https://github.com/cabloy/cabloy/blob/main/package.j
 
 ```bash
 npm run init
+npm run db:reset
 npm run dev
 npm run tsc
 npm run test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.207",
+  "version": "5.1.209",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-agent-governance/managed-assets.json

@@ -256,7 +256,7 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "0d1901134f7222902cfc702275ed7bd83a4e3a1d72c3543a77c8ab5d7cabaa55",
+      "sha256": "900d9c74bd44f746990046c3ea142d653da740b156a648c573992134b5cc1b9f",
       "source": "skills/cabloy-workflow/evals/evals.json",
       "target": ".agents/skills/cabloy-workflow/evals/evals.json"
     },
@@ -277,7 +277,7 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "eccad69c3969f97e80a3766fc2149b9f3e0bf2acd0c8586ed7bed0418f6878a9",
+      "sha256": "b9414b99bc7ad83d4db2dccfd14e9dfa5281bdd78dd2df524080129dd032b750",
       "source": "skills/cabloy-workflow/SKILL.md",
       "target": ".agents/skills/cabloy-workflow/SKILL.md"
     },
@@ -592,7 +592,7 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "0d1901134f7222902cfc702275ed7bd83a4e3a1d72c3543a77c8ab5d7cabaa55",
+      "sha256": "900d9c74bd44f746990046c3ea142d653da740b156a648c573992134b5cc1b9f",
       "source": "skills/cabloy-workflow/evals/evals.json",
       "target": ".claude/skills/cabloy-workflow/evals/evals.json"
     },
@@ -613,7 +613,7 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "eccad69c3969f97e80a3766fc2149b9f3e0bf2acd0c8586ed7bed0418f6878a9",
+      "sha256": "b9414b99bc7ad83d4db2dccfd14e9dfa5281bdd78dd2df524080129dd032b750",
       "source": "skills/cabloy-workflow/SKILL.md",
       "target": ".claude/skills/cabloy-workflow/SKILL.md"
     },
@@ -683,7 +683,7 @@
     {
       "adapter": "cursor",
       "category": "policy",
-      "sha256": "e2784a08d355455da0da0cfb7c83ff1df4db69566012a1b4a33a5d591764f730",
+      "sha256": "2948516f964a13242178b4f5969756d469f60cc1766616a53e899c5551cf443d",
       "source": "policies/repository.md",
       "target": ".cursor/rules/cabloy-governance.mdc"
     },
@@ -942,7 +942,7 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "0d1901134f7222902cfc702275ed7bd83a4e3a1d72c3543a77c8ab5d7cabaa55",
+      "sha256": "900d9c74bd44f746990046c3ea142d653da740b156a648c573992134b5cc1b9f",
       "source": "skills/cabloy-workflow/evals/evals.json",
       "target": ".cursor/skills/cabloy-workflow/evals/evals.json"
     },
@@ -963,7 +963,7 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "eccad69c3969f97e80a3766fc2149b9f3e0bf2acd0c8586ed7bed0418f6878a9",
+      "sha256": "b9414b99bc7ad83d4db2dccfd14e9dfa5281bdd78dd2df524080129dd032b750",
       "source": "skills/cabloy-workflow/SKILL.md",
       "target": ".cursor/skills/cabloy-workflow/SKILL.md"
     },
@@ -1005,14 +1005,14 @@
     {
       "adapter": "codex",
       "category": "policy",
-      "sha256": "d5f4d8fb331147baa92aa68d8579ac604d2a34bf872efc594393ff1e52e8cd79",
+      "sha256": "f4f6c2584bd58846e315ecf2c0772a47735ef0d1f24a72213d2d6ea13673db71",
       "source": "policies/repository.md",
       "target": "AGENTS.md"
     },
     {
       "adapter": "claude",
       "category": "policy",
-      "sha256": "d5f4d8fb331147baa92aa68d8579ac604d2a34bf872efc594393ff1e52e8cd79",
+      "sha256": "f4f6c2584bd58846e315ecf2c0772a47735ef0d1f24a72213d2d6ea13673db71",
       "source": "policies/repository.md",
       "target": "CLAUDE.md"
     }

package/repo-agent-governance/policies/repository.md

@@ -71,7 +71,7 @@ Before inventing a custom implementation path:
 - Treat hooks, permissions, local settings, credentials, MCP registration, command discovery, and automatic command execution as platform-specific integrations, not portable rule or skill capabilities.
 - After implementation, do not launch broad reviews automatically; when review is needed, scope it to the current diff and report only high-confidence issues.
 - Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `repo-docs/fullstack/parallel-worktree-environment.md`; otherwise wait for the shared resource or ask the user. Create or change worktree-local environment overrides only through the explicitly invoked `cabloy-worktree-environment` skill and its confirmation phase, and only in `vona/env/.env.local` and `zova/env/.env.local`; never modify flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files. The skill derives the standard `APP_NAME`, `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`, and API-derived `API_BASE_URL` tuple only from Git worktree metadata and fixed port baselines; never read or expose `.env*` content while recommending values. Admin and Web are alternative commands using this shared tuple and must not run concurrently in one worktree; use another linked worktree for concurrent use. Detect the active edition before choosing scripts, and never run `npm run init` as an automatic follow-up.
-- In Cabloy Basic, root `npm run test` and `npm run test:e2e` always allocate an isolated same-checkout test run: disposable run-specific database and Redis namespaces, runtime/public paths, and listener. This protects ordinary development business data, including when a dev server is active in the same checkout. Shared preparation writes (such as builds or dependency generation) are separate accepted prerequisites, not test cleanup of dev business data; do not treat the test isolation as permission to run manual resets or change shared configuration. Check the active edition's scripts before extending this guarantee to Cabloy Start. See `repo-docs/reference/repo-scripts.md`.
+- In Cabloy Basic and Cabloy Start, root `npm run test` and `npm run test:e2e` allocate an isolated same-checkout test run: disposable run-specific database and Redis namespaces, runtime/public paths, and listener. Ordinary same-checkout dev-process presence alone is not a blocker; do not require dev shutdown, another worktree, or environment changes solely to run these tests. Judge conflicts by actual overlap with effective test resources or shared preparation writes, not process names. Builds and dependency installation/generation remain shared prerequisites; coordinate overlapping writes, and check custom external resources separately. This guarantee does not cover raw test commands or authorize manual resets, process killing, or shared configuration changes. See `repo-docs/reference/repo-scripts.md`.
 - For isolated E2E through Vona integrated SSR, do not edit Zova `API_BASE_URL` environment values or rebuild solely to match the test port: Vona supplies runtime server/browser API origins. On an origin mismatch, check explicit SSR Site and module-specific API URL overrides first; follow the active repository's scripts for changed SSR/REST artifacts and dependency synchronization. Do not generalize this handoff to Zova standalone SSR or SPA. See [Runtime API origins](repo-docs/fullstack/ssr-entry-modes.md#runtime-api-origins-in-vona-integrated-ssr).
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.

package/repo-agent-governance/skills/cabloy-workflow/SKILL.md

@@ -105,9 +105,11 @@ For deeper reference material, read:
 
 The reason is simple: these files are where Cabloy already encodes its real workflows.
 
-### Parallel worktree environment setup
+### Isolated tests versus parallel worktree environment setup
 
-When a request involves a second worktree, concurrent Vona/Zova development, isolated ordinary tests, or managed E2E, classify it as fullstack workflow setup. Read [Parallel Worktree Environment](../../../repo-docs/fullstack/parallel-worktree-environment.md), the canonical shared recipe maintained in Cabloy Basic for both editions.
+In Cabloy Basic and Cabloy Start, root `npm run test` and `npm run test:e2e` isolate their runtime and framework-managed data from ordinary dev in the same checkout. A running Vona or Zova dev process alone is not a blocker and does not require dev shutdown, another worktree, or `/cabloy-worktree-environment`. For tests-only requests, use the active edition's root scripts and the [test-isolation guidance](../../../repo-docs/reference/repo-scripts.md#test-isolation-and-development-data); do not route them into environment setup. Check actual overlap with runner-owned test resources, coordinate shared build/dependency writes, and assess custom external resources separately. Process names alone do not establish a conflict.
+
+When a request actually involves a second ordinary development runtime or worktree-local environment configuration, classify it as fullstack workflow setup. Read [Parallel Worktree Environment](../../../repo-docs/fullstack/parallel-worktree-environment.md), the canonical shared recipe maintained in Cabloy Basic for both editions.
 
 This routing skill provides read-only guidance only. Do not infer an `APP_NAME` or ports, edit local overrides, or run `npm run init` from a generic worktree request. When the user wants confirmation-gated local environment setup, ask them to explicitly invoke `/cabloy-worktree-environment`.
 

package/repo-agent-governance/skills/cabloy-workflow/evals/evals.json

@@ -46,7 +46,7 @@
     {
       "id": 8,
       "prompt": "I created a linked Cabloy Basic worktree and only need backend tests. What should I do for local environment isolation?",
-      "expected_output": "Keeps generic routing read-only and directs the user to the canonical guide plus explicit /cabloy-worktree-environment invocation. It explains that the invoked skill still generates the universal APP_NAME, SERVER_LISTEN_PORT, DEV_SERVER_PORT, DEV_SERVER_HMR_PORT, and derived API_BASE_URL tuple in both broad local files after confirmation; it does not provide a backend-only one-file path.",
+      "expected_output": "Recognizes that Basic root npm run test already allocates isolated runtime and framework-managed data, including in a linked worktree. Does not require /cabloy-worktree-environment, local environment changes, another worktree, or dev shutdown for tests alone. Points to Repo Scripts, checks actual test-resource overlap and custom external resources, and coordinates any shared build/dependency preparation writes.",
       "files": []
     },
     {
@@ -54,6 +54,18 @@
       "prompt": "I am in a Cabloy checkout where repo-docs-internal exists, but the named architecture record I expected is not available in this edition. I need shared agent guidance and some maintainer rationale. Where should each part go?",
       "expected_output": "Recognizes repo-docs-internal as the internal documentation home, routes shared operational guidance to public docs and Claude rules or skills, and treats the missing named record as non-blocking rather than inventing a replacement or moving rationale into public docs automatically.",
       "files": []
+    },
+    {
+      "id": 10,
+      "prompt": "Vona dev is running in this Cabloy Basic checkout. Can I run root npm run test:e2e here, or must I stop dev or create another worktree?",
+      "expected_output": "Explains that root managed E2E allocates run-owned database and Redis namespaces, runtime/public paths, and a listener, so ordinary same-checkout dev presence alone is not a blocker. Does not stop dev, change ports/env, request a new worktree, or invoke environment setup. Coordinates actual shared build/dependency writes and checks real test-resource or custom external-resource overlap without treating process names as proof. Does not extend isolation to raw test commands or infer reset/cleanup authorization.",
+      "files": []
+    },
+    {
+      "id": 11,
+      "prompt": "In Cabloy Start, Vona dev and Zova Web dev are already active. I only need root npm run test and npm run test:e2e. Is their presence an isolation conflict?",
+      "expected_output": "Applies the same root managed-test isolation guarantee as Cabloy Basic while selecting Start's actual scripts and artifact prerequisites. Ordinary dev presence alone is not a conflict and does not require another worktree, dev shutdown, or environment changes. Distinguishes actual test-owned resource collisions, shared preparation writes, and custom external resources; preserves ownership and authorization checks.",
+      "files": []
     }
   ]
 }

package/repo-docs/backend/unit-testing.md

@@ -53,7 +53,7 @@ A typical Vona test flow includes:
 5. run the test files
 6. close the shared application after the test run
 
-In Cabloy Basic, root `npm run test` delegates to `vona/`'s `npm run test`; both allocate an isolated test identity, database and Redis namespace, Vona generated/runtime/public paths, and loopback listener. They can run in the same checkout as an ordinary development server without resetting or mutating that server's business data. Even a targeted run performs the test-mode setup. The Vona `npm run cov` script uses the same isolation; raw `:bin:test` commands do not. Shared build/dependency preparation may still write to shared artifacts, and custom external resources need separate isolation. See [Repo Scripts](/reference/repo-scripts#test-isolation-and-development-data-in-cabloy-basic).
+In Cabloy Basic and Cabloy Start, root `npm run test` delegates to `vona/`'s `npm run test`; both allocate an isolated test identity, database and Redis namespace, Vona generated/runtime/public paths, and loopback listener. They can run in the same checkout as an ordinary development server without resetting or mutating that server's business data. Even a targeted run performs the test-mode setup. The Vona `npm run cov` script uses the same isolation; raw `:bin:test` commands do not. Shared build/dependency preparation may still write to shared artifacts, and custom external resources need separate isolation. See [Repo Scripts](/reference/repo-scripts#test-isolation-and-development-data).
 
 The runner owns this application lifecycle. Test files import the shared app from `vona-mock` and must not create or close it themselves:
 

package/repo-docs/frontend/form-guide.md

@@ -239,7 +239,15 @@ The callback receives the current `ControllerFormField` instance. It is a field-
 Zova invokes it in two important situations:
 
 1. after the field controller has created its field binding and finished its initialization;
-2. after a schema-property change updates the field options and calls `resetField(this.name)`.
+2. after a material schema or field-configuration change updates the field options and calls `resetField(this.name)`. Parent validation changes, such as `required[]`, count even when the field property itself is unchanged.
+
+Field refresh always resets field state; there is no blanket reset-suppression option. A form can opt into `localePresentationRefresh` with a stable owner identity when supported schema annotations are display-only for that form. Generic Basic resource entry forms provide their resource/record/scene identity automatically. On a compatible locale transition, the field installs current validators, resets, silently restores its current raw live value, refreshes applicable local validation, and only then invokes `onFieldStateReady`.
+
+Compatibility is conservative: resolved value/validation truth, defaults, references, canonical bindings, and the field's own renderer/options/readonly metadata must remain unchanged. Only recognized schema titles/descriptions, validation-message strings, and titles in the known Basic Form Layout tab/group grammar can differ. Unknown metadata, explicit effects or opaque validation do not authorize restoration. Unrelated static sibling renderer labels do not invalidate an independent field; a field whose own renderer options change still follows normal reset semantics. The known Basic Details renderer owns a nested form, including its exact hidden `_name` auxiliary row schema; descendant behavior stays within that boundary. Arbitrary hidden fields and direct cross-field effects do not receive this exception. This policy assumes permitted annotations are presentation-only, not that arbitrary custom renderers or CEL programs have been proven equivalent.
+
+Replacing an inline `slotDefault` or `onFieldStateReady` closure during ordinary rendering is not itself a material schema change. The latest readiness callback is used when a real refresh occurs. Custom slots remain opaque for automatic value replay; the canonical Basic Input renderer's internal binding slot is a narrowly supported exception, not permission for arbitrary custom slots.
+
+Cold schema loading does not consume the previous comparison facts; a remounted field finalizes after its binding is mounted and behavior initialization is complete. Explicit `reset(...)`, incoming-data replacement, or owner/scene changes invalidate preservation. No stored draft is read or replayed during a locale refresh, and standalone forms retain ordinary reset behavior unless they opt in. TanStack's ordinary reset may retain a value when neither the field nor form has a defined default; ineligibility means no extra value replay, not guaranteed erasure.
 
 The second timing is important: write the external value in the callback **after** the reset, because a write made before `resetField(...)` can be overwritten. If an external API later creates or refreshes the value, synchronize that API result explicitly as well; `onFieldStateReady` does not fetch, retry, or observe external resources for you.
 
@@ -722,6 +730,14 @@ This Student pattern is recommended because:
 
 This is also why Cabloy can provide complete CRUD-style form pages with a strong schema-driven surface instead of requiring every page to hand-build form wiring from scratch.
 
+### Unsaved resource drafts
+
+In Cabloy Basic's generic resource entry pages, create and edit forms enable IndexedDB draft recovery by default. After a full browser reload, Recover applies eligible unsaved input to the form without submitting or writing a business record. Successful submission, explicit discard, ordinary Back and task/workspace close delete the corresponding draft; switching between still-open tasks retains it. Standalone `ZForm` forms are not automatically opted into this resource capability.
+
+Draft policy comes from the current schema: normal declared editable fields are included, while readonly, sensitive, file/upload and unsupported values are excluded. Use `@Api.field(ZovaRender.draft(false))` for additional sensitive fields or subtrees, or a scene-specific exclusion such as `ZovaRender.draft(false, 'form-create')`. Resource/global opt-outs and a configurable 24-hour default retention are available.
+
+See [Resource Entry Page Deep Dive: Recovering unsaved create/edit drafts](/frontend/resource-entry-page-deep-dive#recovering-unsaved-create-edit-drafts) for the configuration examples, lifecycle, nested-detail behavior and browser-storage boundaries. Draft storage is not encryption, and two browser tabs with the same resource/task identity share a draft key rather than receiving independent draft sessions.
+
 Read together with:
 
 - [Tutorial 2: Create Your First CRUD](/fullstack/tutorial-2-first-crud)

package/repo-docs/frontend/model-architecture.md

@@ -236,6 +236,10 @@ Representative source files:
 
 A key design detail is that persistence is treated as an extension of model-owned query state rather than as a separate unrelated subsystem.
 
+DB records have a physical application/environment namespace: application name plus `[instanceId, siteId, userId]`. Passport supplies instance/user identity using the same rule on server and client; before a Passport user exists, both values are null. The site value comes independently from `SITE_ID`, and missing values normalize to null. This is persistence isolation, not a change to business query keys or sync local/cookie storage.
+
+The app-owned `$modelPersistence` context also coordinates DB-backed query state on an identity change. It invalidates obsolete work and clears old in-memory values in place while keeping live observers usable. Initial SSR-hydrated query data can be adopted once; a later login does not promote old or pre-user data into the new scope. `$clear()` remains a full-store clear. See [IndexedDB environment isolation](./model-state-guide.md#indexeddb-environment-isolation) for the lifecycle and upgrade boundaries.
+
 ## SSR behavior
 
 Zova Model is SSR-aware.

package/repo-docs/frontend/model-state-guide.md

@@ -284,7 +284,7 @@ This is useful for larger persisted client state that should outlive a page sess
 
 ### Initialize and ensure async-local state
 
-Assign the state property before awaiting it. When later initialization depends on the restored value, establish an explicit restore boundary with `$ensureStateLocalAsync(...)`. It waits for the pending initial restore to settle; it does not force another load and does not guarantee a defined result:
+Assign the state property before awaiting it. When later initialization depends on the restored value, establish an explicit restore boundary with `$ensureStateLocalAsync(...)`. It waits for the pending restore to settle; it does not force another load and does not guarantee a defined result:
 
 ```typescript
 protected async __init__() {
@@ -302,7 +302,9 @@ protected async __init__() {
 }
 ```
 
-`meta.defaultData` is a fallback: it initializes the state only when no persisted value is restored. If neither provides a value, the ensured result can still be `undefined`. The router-tabs model follows this assign-then-ensure sequence before it continues with route initialization.
+`meta.defaultData` is a fallback: it initializes the state only when no persisted value is restored. If neither provides a value, the ensured result can still be `undefined`. For async-local state, prefer a factory such as `defaultData: () => []` for mutable defaults that must be fresh on each restore. Do not carry that function into an SSR-dehydrated memory query: query metadata is transferred with its state and must remain serializable. Use a serializable default value for that branch.
+
+Readiness is not permanent: an IndexedDB persistence-scope reset can make an already initialized async-local state pending again. Consumers must wait for the current restore before acting on its value; `$ensureStateLocalAsync(...)` does not pin an earlier scope or turn future reads into synchronous ones. For synchronous render consumers, keep the persisted backing state separate from a neutral current-scope projection and coordinate restore completion in the owning model. Do not persist that neutral projection or retain the previous scope's value while waiting. The router-tabs model uses this boundary for its writable array facade and route initialization.
 
 Persisted local and async-local state should be updated by replacing or assigning the model field so its custom-ref setter can update query state and persist the new value:
 
@@ -351,6 +353,25 @@ Representative behaviors include:
 
 This is why model helpers are better understood as state-runtime helpers, not only convenience wrappers.
 
+### IndexedDB environment isolation
+
+DB persistence automatically namespaces each physical record by application name and the environment tuple `[instanceId, siteId, userId]`, followed by the model-owned query identity. This applies to `$useStateLocalAsync(...)` and to remote queries whose effective persister uses `db`. Selectors and custom/simplified storage keys remain business keys; they cannot bypass the environment namespace. Logical Query Cache keys and SSR hydration keys do not acquire these dimensions. Sync `local` and `cookie` storage, `mem`, and `persister: false` keep their existing behavior.
+
+The Passport model supplies instance and user identity through the neutral `$modelPersistence` context. Both server and client use the same rule:
+
+- before Passport supplies a user, `instanceId` and `userId` are `null`;
+- after Passport supplies a user, use the response's top-level `instanceId` and that user's `id`;
+- `siteId` comes from the current SSR site's `SITE_ID`, independently of Passport;
+- absent values normalize to `null`; non-null IDs normalize to strings, including valid zero values.
+
+The backend composes Passport `instanceId` from the active Vona instance. No separate bootstrap request or special instance-only SSR handoff is needed. A null scope is usable immediately, not a pending state. A business that needs instance isolation before Passport has a user must include that extra distinction in its own key.
+
+A real tuple change invalidates old DB-backed in-memory state as well as changing disk keys. Existing query observers stay attached, active remote queries refetch under the new identity, and async-local state reloads on its next read/ensure. Obsolete asynchronous work cannot publish into the new identity. A same-scope Passport refresh does not reset state. The initial scope installation preserves eligible query data transferred through SSR; later login or identity switches do not adopt old data. Do not copy pre-user state into an authenticated scope implicitly.
+
+`$clear()` deliberately still clears the **entire** shared IndexedDB store, not only the current tuple. Accepted writes are ordered before clear and obsolete pending persistence work cannot repopulate it. This is useful for logout in a user-facing browser, but is not a server-side authorization boundary or cross-tab session protocol.
+
+Unscoped legacy DB records are not read or automatically migrated. After upgrading, previously persisted DB state starts fresh; changing a business selector likewise does not migrate its old records. Keep using stable resource inputs in logical keys rather than repeating the environment tuple there.
+
 ## SSR-sensitive state choices
 
 Model state choices can affect SSR behavior.

package/repo-docs/frontend/resource-entry-page-deep-dive.md

@@ -228,6 +228,125 @@ Inside `blockPageEntry`:
 
 This is why the entry-page runtime should be read together with [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) and [Page Meta Guide](/frontend/page-meta-guide).
 
+## Recovering unsaved create/edit drafts
+
+Cabloy Basic's generic resource entry runtime enables draft recovery by default for **create and edit** forms. View forms do not save drafts, and this capability does not automatically extend to standalone `ZForm` usages such as login or password-change forms.
+
+Eligible input is saved silently through a Zova Model using asynchronous IndexedDB persistence: ordinary saves do not show a saved-draft banner. On page entry or after a browser reload, an initial persisted candidate offers **Recover** and **Discard** controls once client hydration and form initialization have finished. This is a one-shot recovery decision, not an active-draft toolbar. Successful recovery dismisses the banner and changes the live form only: it never creates or updates a business record and never submits the form automatically.
+
+The ownership boundaries remain separate:
+
+- `ModelResource` owns current server data, schema and mutations.
+- `basic-pageentry`'s selector-backed `ModelDraft` owns each local snapshot and its persistence status.
+- `BeanDraftCoordinator` owns draft identities, session invalidation and explicit route/task-close cleanup. Client application initialization registers this coordinator without preloading draft Models or browser snapshots, so even unopened inactive tasks can be cleaned up.
+- `ZForm` owns editable values and validation.
+- `blockPageEntry` coordinates recovery, submission and explicit abandonment through the coordinator.
+
+### Draft lifecycle
+
+| Action                                       | Draft behavior                                                                                             |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Edit eligible fields                         | Silently save the complete current local unsaved snapshot.                                                 |
+| Enter new parent-form input with a candidate | Dismiss the candidate and replace it with the current form snapshot, without merging old candidate values. |
+| Recover a candidate successfully             | Apply it to the live form and dismiss the banner; subsequent saves stay silent.                            |
+| Switch between still-open tasks              | Retain input and draft state without reopening a dismissed banner.                                         |
+| Reload the browser                           | Retain the draft and offer recovery on returning to the same form.                                         |
+| Ordinary Back                                | Delete the outgoing form's draft.                                                                          |
+| Explicitly close a task or its workspace     | Delete the drafts of the removed tasks, including inactive tasks.                                          |
+| Successfully submit                          | Delete the corresponding create/edit draft.                                                                |
+| Validation or submission fails               | Retain the draft.                                                                                          |
+| Discard a recovery candidate                 | Delete that candidate and leave the current baseline form unchanged.                                       |
+| Component unmount or cache pruning           | Not, by itself, an explicit draft discard.                                                                 |
+
+Reloading while the list or another task is active preserves the inactive form's draft too. Returning through its restored create/edit task offers recovery after the current schema and page route are ready; restored workspace metadata does not restore the live form values or imply automatic recovery.
+
+A new parent `onChanged` event takes over an undecided recovery candidate. The next snapshot contains the complete current live form, not a field-by-field merge with the old candidate. Input entered before asynchronous candidate discovery wins too: discovery must not reopen the old banner or replace that newer input. To recover the replacement later, reload and explicitly choose Recover.
+
+There is no active-draft Discard button, toolbar or other UI entry after recovery or new-input takeover. The internal `discardDraft()` reset method remains available to the runtime; candidate Discard is the visible recovery action, and ordinary Back or explicit task/workspace close still performs abandonment cleanup.
+
+Edit recovery checks the current accessible record at the interaction boundary: a changed, deleted or inaccessible record must not receive stale recovered values. Recovery errors remain with the candidate controls; storage failures use a separate compact inline status rather than a saved-draft banner. Expired or structurally incompatible snapshots are not applied. Locale-only label changes do not invalidate compatible drafts.
+
+### Locale refresh is not draft recovery
+
+The resource form enables `ZForm`'s narrow `localePresentationRefresh` policy with a stable resource/record/scene identity. Schema refresh still updates field options and **always resets field state**. A compatible language change can then restore the current live value before the readiness callback; it does not read IndexedDB, replay a recovery candidate, preserve old validation errors, or skip new validation rules.
+
+Compatibility includes complete resolved validation truth and strict field renderer/options metadata. For example, Student `name` can survive a label/message translation, while Student `level` has localized renderer options and follows normal reset behavior rather than receiving extra value replay. Supported Basic Form Layout tab/group titles are display-only; arbitrary renderer metadata is not. Explicit reset, data replacement, record/scene changes, changed constraints/defaults, and opaque effects invalidate preservation. Read [Form Guide](/frontend/form-guide#initialize-external-state-with-onfieldstateready) for the policy boundaries.
+
+Draft projection supports `anyOf` and `oneOf` unions whose branches are all safe primitives or null, including Student `level` (`1 | 2 | 3`). Eligible branches declare string, boolean, number, integer or null types (including nonempty arrays of these types), or provide an untyped primitive/null `const` or nonempty primitive/null `enum`; defaults and renderer options do not establish eligibility. Safe unfinished values are persisted without enum-membership validation, coercion or branch selection.
+
+Every branch is checked, including null branches, reference wrappers and resolved targets. A sensitive, readonly, write-only, file/upload/binary or `draft: false` branch, an unresolved or cyclic reference, or any unsupported branch excludes the **entire field**; unsafe alternatives are never dropped to persist the remainder. Multi-member unions containing objects or arrays remain excluded, as do `allOf` and simultaneous composition operators. Nullable objects and arrays with a single non-null branch retain their existing nested projection support.
+
+Explicit draft recovery can therefore restore stored Student `level: 2` over server baseline `1`. A later locale refresh with incompatible translated renderer options still resets the live level normally, and an already-dirty draft then saves that current reset value. Primitive-union support does not weaken the locale reset policy. Union operators and every branch's structural contract participate in the draft signature; old incompatible snapshots are rejected rather than migrated or silently replayed.
+
+After field readiness callbacks settle, `ZForm` coalesces an `onSchemaRefreshed` notification using current live values. `blockForm` forwards it to the entry owner, which updates an already-dirty draft so values changed by normal field reset do not leave a stale snapshot. This notification does not mark a clean form dirty, manufacture an input-change event, or overwrite an undecided recovery candidate.
+
+### Disable recovery or change retention
+
+The `basic-pageentry` module configuration defaults to:
+
+```ts
+draft: {
+  enabled: true,
+  maxAge: 24 * 60 * 60 * 1000,
+  resources: {},
+}
+```
+
+Use the application's `config.modules` overrides to disable recovery globally, disable it for selected resources, or change the retention period:
+
+```ts
+config.modules = {
+  'basic-pageentry': {
+    draft: {
+      enabled: true,
+      maxAge: 24 * 60 * 60 * 1000,
+      resources: {
+        'training-student:student': false,
+      },
+    },
+  },
+};
+```
+
+Set `enabled: false` to disable the capability globally. A resource-entry `basic-pageentry:blockPageEntry` block can also specify `draft: false`, and root form `rest.draft: false` metadata disables the whole form. These are opt-outs from the default capability, not a requirement to manually enable every resource.
+
+### Control which fields are persisted
+
+Declared, editable, supported fields are included by default, including nested objects and arrays. The current form scene's effective schema controls projection: create uses `form-create`, while edit uses `form`. Unknown fields and unsafe runtime values are excluded.
+
+Automatic exclusions include readonly fields, passwords and write-only values, obvious secret/key/token/credential/verification-code fields, file/upload/binary fields and unsupported objects such as `File`, `Blob` or DOM nodes. Drafts may hold incomplete safe input without passing submit validation. Nested detail recovery preserves existing row identity and deletion/order semantics rather than turning existing rows into new inserts; excluded server-owned values come from the current baseline.
+
+#### Date-time fields and nested detail dialogs
+
+For an eligible schema field declared as `type: 'string'` with `format: 'date-time'`, a valid runtime `Date` is projected to its ISO string. This is a schema-directed `Date` → ISO conversion, not a general object serializer or submit-time validation: incomplete safe primitive input is preserved without date parsing or coercion. Invalid `Date` instances, `Date` values on ordinary non-date-time fields, and unsupported non-date objects remain excluded.
+
+The draft recovery projection intentionally restores the ISO **string**, without adding a Date reviver. The existing model persistence parser may revive ISO strings before recovery; the projection normalizes eligible Dates back to ISO. Basic Date accepts both runtime Dates and ISO strings, so reopening a recovered Training Record dialog displays the stored Training Time through the same native date control. Its date-only input represents midnight in the browser's local timezone; the projected ISO value expresses that instant in UTC. Clearing an optional date preserves the explicit absence so recovery does not silently restore the server's date.
+
+A nested Details dialog has its own local form. Edits enter the parent resource form—and therefore its draft—only after the dialog's **OK** action. Cancel does not copy them into the parent. Dialog OK is not a business-resource submission: draft persistence and recovery do not create or update server records. Incompatible old snapshots are rejected through the schema signature rather than migrated or revived.
+
+For business-sensitive content that cannot be reliably identified by automatic metadata, declare an explicit exclusion on the backend contract:
+
+```ts
+@Api.field(ZovaRender.draft(false))
+privateNote: string;
+
+// Exclude this field only in create-form drafts.
+@Api.field(ZovaRender.draft(false, 'form-create'))
+verificationCode: string;
+```
+
+Applied to an object or array field, `draft(false)` excludes the entire subtree. Scene-specific metadata follows the existing shared-form and exact-scene overlay rules. An explicit `draft(true)` does not override automatic sensitive, readonly or unsupported-value exclusions.
+
+`ZovaRender` is generated from frontend-owned metadata. After changing that authoring surface, follow the [Contract Loop Playbook](/fullstack/contract-loop-playbook): build the affected paired SSR/REST flavor outputs before synchronizing Vona dependencies; do not patch generated consumers manually.
+
+### Browser storage boundaries
+
+Drafts use the generic [Model IndexedDB environment isolation](./model-state-guide.md#indexeddb-environment-isolation): application name and `[instanceId, siteId, userId]` belong to the persistence layer, not the draft business selector. The selector contains only `[resource, mode, id ?? null, path]`. Passport supplies the authoritative instance/user identity; draft discovery still requires an authenticated, non-anonymous user. A captured scope/epoch token invalidates old editors and queued cleanup after an instance, site or user switch, including switching away and back. Logout deliberately clears the entire shared Model DB store; it does not transfer another account's drafts into the new form. There is no draft-specific database adapter or legacy-key migration.
+
+IndexedDB is **not encryption**. Automatic exclusions are defensive defaults, not a guarantee that every business-sensitive field can be recognized; exclude additional fields or disable sensitive resources deliberately. Storage failure is nonfatal and does not prevent normal editing or submission, but unfinished writes cannot be guaranteed durable if the browser terminates immediately.
+
+There are no application-level draft-count or byte limits. Browser storage availability and native quota still apply. The same resource/task identity in two browser tabs shares one draft key; independent simultaneous create drafts and cross-tab conflict coordination are not provided.
+
 ## What this guide does not re-explain
 
 This page does **not** fully re-explain:

package/repo-docs/frontend/scripts.md

@@ -68,7 +68,7 @@ npm run deps:vona
 npm run test:e2e cabloy-basic home-user-account
 ```
 
-The sole managed `npm run test:e2e` command starts a fresh local Vona worker with `--workers=1 --flavor=normal --mode=test`, then runs the selected specs against Vona integrated SSR. Test-mode startup initializes test resources without a separate `db:reset`; browser commands consume already-built artifacts and do not rebuild them. Confirm exclusive ownership of the effective test database, `_local` Redis namespace, public/runtime paths, `APP_NAME`, API origin, and listener before startup; a free port alone is insufficient.
+The sole managed `npm run test:e2e` command starts a fresh local Vona worker with `--workers=1 --flavor=normal --mode=test`, then runs the selected specs against Vona integrated SSR. Test-mode startup initializes test resources without a separate `db:reset`; browser commands consume already-built artifacts and do not rebuild them. In both Cabloy Basic and Cabloy Start, the root wrapper allocates run-owned test identity, database and Redis namespaces, generated/runtime/public paths, and a loopback listener independently of ordinary dev. A running same-checkout dev process alone is not a blocker. Check actual overlap with those test resources and custom external resources, and coordinate overlapping shared build/dependency writes; do not require dev shutdown or worktree/environment setup solely for these tests. See [Test isolation and development data](/reference/repo-scripts#test-isolation-and-development-data) for the ownership and preparation boundaries.
 
 Place flat spec basenames directly after the npm script name. Use npm's `--` delimiter before Playwright options. With no names, every spec in `repo-e2e/specs` runs. Native `--grep` and `--grep-invert` remain available, and repeatable `--tag` values require all listed tags:
 
@@ -95,7 +95,7 @@ Cabloy Start does not expose the Basic Commerce wrapper family.
 
 ## Start SSR browser acceptance
 
-The Start Web and Admin browser baseline exercises Vona integrated SSR dispatch at the effective local test-mode server port. Prepare current SSR and REST artifacts, then use the managed local command:
+The Start Web and Admin browser baseline exercises Vona integrated SSR dispatch at the managed run's dynamically allocated loopback listener, independently of the ordinary dev listener. Prepare current SSR and REST artifacts, then use the managed local command:
 
 ```bash
 npm run build:zova
@@ -118,7 +118,7 @@ npm run test:e2e cabloy-admin -- --tag @admin --tag @cabloy-admin
 npm run test:e2e cabloy-start -- --grep ATP-START-FLOW-01
 ```
 
-Start does not support externally managed E2E targets: `E2E_BASE_URL` must be unset. The command requires the configured local port to be available and starts one Vona worker with `--flavor=normal --mode=test`; Playwright does not reuse an existing process. Test-mode startup initializes test state. Confirm exclusive ownership of the test database, Redis namespace, and public/runtime paths before running it. The command does not replace the paired build/dependency-sync prerequisite; do not change shared environment identity or ports to avoid a busy resource.
+Start does not support externally managed E2E targets: `E2E_BASE_URL` must be unset. Like Basic, its root wrapper allocates run-specific test identity, database and Redis namespaces, generated/runtime/public paths, and a loopback listener, then starts one Vona worker with `--workers=1 --flavor=normal --mode=test`; Playwright does not reuse an existing process. It can run alongside ordinary same-checkout dev without requiring the configured dev port to be free. Test-mode startup initializes test state without a separate `db:reset`. Apply the same [test-resource ownership and shared-preparation checks](/reference/repo-scripts#test-isolation-and-development-data); the command does not replace the paired build/dependency-sync prerequisite or authorize shared environment/port changes.
 
 ## Zova script model
 

package/repo-docs/frontend/zova-form-under-the-hood.md

@@ -318,11 +318,16 @@ Its callback receives the current `ControllerFormField<TParentData>` instance. T
 _getFormFieldOptions()
   -> _formField.api.update(options)
   -> form.resetField(name)
+  -> optional compatible-locale live-value restoration and current validation
   -> onFieldStateReady(formField)
 ```
 
 The callback must follow `resetField(...)`. A custom field may hold a value outside the form controller—for example, a widget value or an externally created challenge object—and a value written before the reset can be replaced by the reset's default value. The callback provides the replay point where the custom field can write its current external value back through `formField.setValue(...)` or the owning form setter.
 
+The form owns detached, last-ready comparison facts keyed by canonical field name. Fields observe the current resolved form contract as well as their declared configuration, so parent `required[]` or reference-target changes refresh validators even when a projected property is unchanged. Loading gaps do not overwrite those facts. A previously known field remount defers finalization until its binding has mounted and its behavior initialization has completed; provisional creation does not seed over an existing empty value.
+
+`localePresentationRefresh` is an explicit presentation-only policy, not permission to skip reset. Eligible refreshes restore only the current raw value, including `undefined`, without firing input listeners or `onChanged`; old errors and field metadata are never replayed. Explicit reset/data replacement changes the preservation epoch. The compatibility helper resolves current references and compares complete value/validation truth, with strict field renderer/options and ancestor behavior checks. See [Form Guide](/frontend/form-guide#initialize-external-state-with-onfieldstateready) for the supported display exceptions and conservative limits.
+
 This lifecycle is separate from external data changes. If an API creates or refreshes the external value later, synchronize that result in the API completion path too. Likewise, user input should continue to update the field through `formField.setValue(...)`, while value-change effects belong to the normal field effect/input surfaces. `onFieldStateReady` is not a per-value-change listener and does not fetch, retry, or wait for a renderer DOM node.
 
 For the public authoring shape and a renderer-neutral example, see [Initialize external state with `onFieldStateReady`](/frontend/form-guide#initialize-external-state-with-onfieldstateready).

package/repo-docs/fullstack/parallel-worktree-environment.md

@@ -1,6 +1,6 @@
 # Parallel Worktree Environment
 
-Use worktree-local environment overrides when two Cabloy Basic or Cabloy Start worktrees need to run ordinary local development at the same time. In Cabloy Basic, root `npm run test` and `npm run test:e2e` already isolate their test-mode runtime and data on every run, including alongside ordinary dev in the **same** checkout; they do not require this worktree setup for that purpose.
+Use worktree-local environment overrides when two Cabloy Basic or Cabloy Start worktrees need to run ordinary local development at the same time. In Cabloy Basic and Cabloy Start, root `npm run test` and `npm run test:e2e` already isolate their test-mode runtime and data on every run, including alongside ordinary dev in the **same** checkout; they do not require this worktree setup for that purpose.
 
 This Cabloy Basic page is the canonical shared recipe for both editions. Detect the active edition before selecting commands, but keep the same two-file environment model for worktree-local development.
 
@@ -82,11 +82,11 @@ Use commands from the active repository root.
 | Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
 | Cabloy Start | `__CABLOY_START__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
 
-Run one frontend command, not both, in each worktree. In Cabloy Basic, root `npm run test` and `npm run test:e2e` allocate a fresh run-specific identity, test database and Redis namespace, generated/runtime/public paths, and loopback listener independently of the worktree's development environment. Managed E2E starts a fresh Vona test-mode worker, and startup initializes test resources and module seeds without a separate dev-mode reset. This also isolates tests from a dev process in the same checkout. Cabloy Start's managed E2E uses the effective local test-mode Vona listener and its own ownership rules; inspect its root scripts before relying on Basic's isolation. Leave `E2E_BASE_URL` unset: externally managed targets are unsupported. Do not change shared identity or ports merely to bypass a busy development resource.
+Run one frontend development command, not both, in each worktree. In Cabloy Basic and Cabloy Start, root `npm run test` and `npm run test:e2e` allocate a fresh run-specific identity, test database and Redis namespace, generated/runtime/public paths, and loopback listener independently of the worktree's development environment. Managed E2E starts a fresh Vona test-mode worker, and startup initializes test resources and module seeds without a separate dev-mode reset. Ordinary dev presence alone is not a test-resource conflict and does not require another worktree, dev shutdown, or environment changes. Coordinate actual shared build/dependency writes and assess custom external resources separately; see [Test isolation and development data](/reference/repo-scripts#test-isolation-and-development-data). Leave `E2E_BASE_URL` unset: externally managed targets are unsupported. Do not change shared identity or ports merely to bypass a busy development resource.
 
 ## What this isolates
 
-A unique worktree `APP_NAME` separates the identity of ordinary development resources across worktrees, including framework-managed development database names and Redis-related key prefixes. Worktree-local generated files, runtime files, build output, and coverage output are already separated by their worktree paths. Cabloy Basic root tests use a separate run-specific identity even when invoked inside a worktree; they do not clean its ordinary development business data.
+A unique worktree `APP_NAME` separates the identity of ordinary development resources across worktrees, including framework-managed development database names and Redis-related key prefixes. Worktree-local generated files, runtime files, build output, and coverage output are already separated by their worktree paths. Cabloy Basic and Cabloy Start root tests use a separate run-specific identity even when invoked inside a worktree; they do not clean its ordinary development business data.
 
 The generated Vona, Zova development HTTP, and Zova HMR ports let worktrees run their ordinary local processes concurrently. The matching Zova API URL prevents the frontend in one worktree from calling the Vona process in another. Builds, dependency generation, and other shared preparation writes remain accepted prerequisites rather than part of test data cleanup.
 

package/repo-docs/fullstack/quickstart.md

@@ -63,12 +63,22 @@ pnpm_config_minimum_release_age=0 npm create cabloy
 
 ## 3. Start Vona integrated SSR
 
-Run the root CLI command to start the Vona server:
+Before the first start, run the root command below to prepare the development databases and seed data:
+
+```bash
+npm run db:reset
+```
+
+`npm run db:reset` is destructive: it clears application-owned Redis prefixes and drops and recreates the managed development databases, then runs migrations, initialization, and seeds. Use it only when you intend to reset those resources. Do not run it while a development server is using the same databases and Redis namespace.
+
+Then start the Vona server:
 
 ```bash
 npm run dev
 ```
 
+For subsequent starts, run `npm run dev` directly. It reuses existing databases and does not create or seed missing databases; if a required database is missing, run `npm run db:reset` explicitly before starting again.
+
 In the Cabloy Basic default environment, Vona listens on `7102` and serves the following SSR sites:
 
 | SSR Site       | URL                                   |