cabloy 5.1.59 → 5.1.60

package/.claude/skills/cabloy-resource-field-update/references/field-update-decision-tree.md

@@ -0,0 +1,120 @@
+# Field Update Decision Tree
+
+Use this reference with `cabloy-resource-field-update` when a request is about an existing backend resource field.
+
+## 1. Is this an existing-resource update?
+
+Use the skill when the task is about:
+
+- adding a field to an existing resource
+- refining validation for an existing field
+- adding enum-like constraints
+- changing `ZovaRender.field(...)` or `ZovaRender.cell(...)`
+- deciding whether an existing resource field change needs a `fileVersion` bump
+
+Do not use it when the request is really about:
+
+- creating a new CRUD/resource thread
+- generic frontend page/component scaffolding
+- stale contract diagnosis
+
+## 2. Persisted field or metadata-only change?
+
+### Persisted field
+
+Examples:
+
+- add `level: number`
+- add `status: string`
+- add a stored relation key
+
+Actions:
+
+- ask whether `vonaModule.fileVersion` should be incremented
+- inspect `meta.version.ts`
+- inspect module `package.json`
+- plan fresh install and upgrade behavior
+
+### Metadata-only change
+
+Examples:
+
+- add enum validation to an existing field
+- add `ZovaRender.field(...)`
+- add `ZovaRender.cell(...)`
+- refine locale labels
+- tighten validation without changing storage
+
+Actions:
+
+- usually keep `fileVersion` unchanged
+- focus on entity metadata, locale, tests, and optional renderer follow-up
+
+## 3. What is the source of truth?
+
+Check these surfaces first:
+
+- entity
+- model
+- DTOs
+- controller
+- service
+- `meta.version.ts`
+- module `package.json`
+- locale files
+- tests
+
+Prefer:
+
+- entity-first field definition
+- inferred DTO flow if the source already uses `$Dto.create(...)`, `$Dto.update(...)`, or `$Dto.get(...)`
+
+## 4. Renderer branch
+
+### Shared renderer reuse
+
+Default to shared reuse first, especially for enum-like fields.
+
+Typical Cabloy Basic select-style pair:
+
+- `basic-select:formFieldSelect`
+- `basic-select:select`
+
+Default AI behavior:
+
+- provide a user-visible `placeholder` for field-rendering select components unless the UX clearly requires an always-preselected value
+- in Cabloy Basic, prefer `placeholder` over artificial empty-item injection when the goal is to keep the field initially unchosen
+- in Cabloy Start, do not assume the same placeholder or empty-item behavior from `start-select`; verify the wrapper and underlying component semantics before reusing the Basic pattern
+
+### Custom renderer demo
+
+Use only when the task explicitly wants to demonstrate the full custom-renderer workflow.
+
+Required pieces:
+
+- module-local FormField component
+- module-local `@TableCell(...)` bean
+- metadata regeneration
+- frontend build
+- `deps:vona`
+- Vona typecheck and targeted backend test
+
+Important:
+
+- a plain component alone is not enough for backend `ZovaRender.cell(...)`
+- backend table-cell rendering should point to a registered table-cell key backed by `@TableCell(...)`
+
+## 5. Must-close follow-up layers
+
+- locale labels
+- invalid-value test for constrained enum-like fields
+- migration safety if persistence changed
+- narrow verification first, then broader checks if needed
+
+## 6. Migration warning
+
+If you add a new persisted field in a version-bump workflow:
+
+- do not add the same new column in both an older create path and a new migration branch
+- fresh install may run version branches sequentially
+- duplicate introduction paths can cause duplicate-column failures

package/.claude/skills/cabloy-resource-field-update/references/follow-up-checklist.md

@@ -0,0 +1,80 @@
+# Follow-up Checklist
+
+After updating or refining a field on an existing backend resource, check which follow-up layers apply.
+
+## Classification follow-up
+
+- is this a new persisted field or a metadata-only refinement?
+- does the task require a `fileVersion` decision before persistence edits?
+- is the request purely backend-first, or does it explicitly branch into renderer-aware frontend follow-up?
+
+## Backend thread follow-up
+
+- entity field definition
+- model/entity alignment
+- inferred DTO flow vs manual DTO edits
+- controller/service still match the resource contract
+- locale updates for visible field text
+
+## Persistence follow-up
+
+Apply when storage shape changes:
+
+- `meta.version.ts`
+- module `package.json` `fileVersion`
+- fresh install vs upgrade behavior
+- duplicate-column risk across historical and new migration branches
+
+## Validation and contract follow-up
+
+- required vs optional behavior
+- explicit enum-like allowed-value schema when needed
+- `ZovaRender.order(...)`
+- `ZovaRender.field(...)`
+- `ZovaRender.cell(...)`
+- invalid-value test coverage
+
+## Renderer follow-up
+
+### Shared renderer path
+
+- confirm an existing shared renderer already fits
+- keep option shapes aligned with the shared renderer baseline
+- avoid custom frontend code when reuse is sufficient
+
+### Custom renderer demo path
+
+Apply when the user explicitly wants to demonstrate custom renderer development:
+
+- module-local FormField component exists
+- module-local `@TableCell(...)` bean exists
+- backend `ZovaRender.cell(...)` points to the registered table-cell key, not just a plain component
+- metadata regeneration is included
+- frontend build is included
+- `deps:vona` is included
+
+## Verification follow-up
+
+### If persistence changed
+
+- `npm run test`
+
+### If the change is narrower
+
+- `cd vona && npm run tsc`
+- `cd vona && npm test -- <resource-test>.test.ts`
+
+### If custom frontend renderers were introduced
+
+- `npm run zova :tools:metadata <module-name>`
+- `npm run build:zova:admin`
+- `npm run deps:vona`
+- `cd vona && npm run tsc`
+- `cd vona && npm test -- <resource-test>.test.ts`
+
+## Common recovery rule
+
+If generated `.zova-rest` output already contains the new renderer keys but Vona still behaves as if old types are installed:
+
+- suspect a stale `vona/node_modules` installation state
+- rebuild `vona/node_modules` and reinstall dependencies if normal `deps:vona` sync did not recover the local file-package installation state

package/.claude/skills/cabloy-resource-field-update/references/verification-checklist.md

@@ -0,0 +1,97 @@
+# Verification Checklist
+
+Use this reference with `cabloy-resource-field-update` to choose the right verification path for an existing resource field change.
+
+## 1. If persistence changed
+
+This means the task changed storage shape, such as:
+
+- a new persisted field
+- a schema migration path
+- `meta.version.ts`
+- module `fileVersion`
+
+Run:
+
+```bash
+npm run test
+```
+
+Reason:
+
+- the test database should be reinitialized so schema/version mismatches surface early
+
+## 2. If the change is narrower
+
+Start with the narrowest meaningful checks first.
+
+Typical sequence:
+
+```bash
+cd vona && npm run tsc
+cd vona && npm test -- <resource-test>.test.ts
+```
+
+Use this for:
+
+- validation-only refinement
+- locale updates for a field
+- renderer metadata changes on an existing persisted field
+
+## 3. If custom frontend renderers were introduced
+
+Run the synchronization chain in order:
+
+1. regenerate frontend metadata
+2. build the relevant frontend SSR/rest target
+3. run `deps:vona`
+4. run Vona typecheck
+5. run the narrow backend resource test
+
+Representative Cabloy Basic admin flow:
+
+```bash
+npm run zova :tools:metadata <module-name>
+npm run build:zova:admin
+npm run deps:vona
+cd vona && npm run tsc
+cd vona && npm test -- <resource-test>.test.ts
+```
+
+If web SSR also matters, add the web build and then repeat dependency sync as needed.
+
+## 4. What to verify in the result
+
+### Backend contract
+
+Confirm:
+
+- field create/update/view/select behavior still works
+- invalid enum-like values are rejected when applicable
+- inferred DTO surfaces still line up with the entity/model chain
+
+### Renderer integration
+
+Confirm:
+
+- generated metadata contains the new component or table-cell registrations
+- generated `.zova-rest` or related type surfaces contain the new renderer keys
+- backend `ZovaRender.field(...)` / `ZovaRender.cell(...)` references pass typecheck
+
+## 5. Common recovery rule for stale local file dependencies
+
+If all of these are true:
+
+- generated `.zova-rest` files already contain the new renderer keys
+- `deps:vona` was run
+- Vona still behaves as if old renderer types are installed
+
+Then suspect a stale or unhealthy local installation state in `vona/node_modules`.
+
+Recovery action:
+
+```bash
+cd vona && rm -rf node_modules && pnpm install
+```
+
+Use this as a recovery path when the normal sync steps did not restore the local file-package installation state cleanly.

package/.github/workflows/docs-pages.yml

@@ -21,6 +21,8 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     steps:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v5

package/.github/workflows/vona-cov-pg.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-test-crud.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest
@@ -25,11 +27,11 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
-      - run: npm run vona :create:module demo-student -- --suite --ci
+      - run: npm run vona :create:module demo-student2 -- --suite --ci
         working-directory: vona
       - run: npm run vona :tools:deps
         working-directory: vona
-      - run: npm run vona :tools:crud student -- --module=demo-student
+      - run: npm run vona :tools:crud student2 -- --module=demo-student2
         working-directory: vona
       - run: npm run test
         working-directory: vona

package/.github/workflows/vona-test-mysql.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-test-pg.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-test-sqlite3.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-tsc.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6

package/.github/workflows/zova-ui.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6

package/.gitignore

@@ -62,7 +62,6 @@ zova/.quasar
 **/.vitepress/cache
 **/.rollup.cache
 **/.temp-dynamic-*
-/.cabloy-version
 vona/package.json
 zova/package.json
 vona/docker-compose.yml
@@ -76,6 +75,3 @@ vona/src/suite/cabloy-basic/modules/basic-siteadmin/assets/site
 vona/src/suite/cabloy-basic/modules/basic-siteadmin/zovaRest
 vona/src/suite/cabloy-basic/modules/basic-siteweb/assets/site
 vona/src/suite/cabloy-basic/modules/basic-siteweb/zovaRest
-
-/vona/src/module/demo-student
-/zova/src/module/demo-student

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 5.1.60
+
+### Features
+
+- Add a mobile field to the demo-student example.
+- Add demo-student summary and force-delete flows.
+- Add a level renderer workflow to the demo-student example.
+- Initialize test data automatically after setup.
+- Refine router tab insertion order.
+
+### Improvements
+
+- Add SSR architecture and workflow guides.
+- Add a Web Socket documentation set.
+- Add a Zova Behavior guide.
+- Add router tabs documentation.
+- Add advanced bean scene authoring guides and document boilerplate variants.
+- Add a fullstack quick start tutorial series and document core fullstack principles.
+- Refactor the fullstack AI tutorial series and streamline quick start guidance.
+- Clarify helper placement and strengthen contract loop examples with reusable patterns.
+- Simplify and polish tutorial prompts, verification steps, and user workflow guidance.
+- Unify resource-owned custom item state handling.
+- Update `tmp` to `0.2.7` and `tar` to `7.5.16`.
+- Disable `pnpm` `minimumReleaseAge` in CI workflows.
+
+### Bug Fixes
+
+- Make contract loop examples more resilient.
+- Refine select placeholder guidance.
+
 ## 5.1.59
 
 ### Features

package/CLAUDE.md

@@ -54,9 +54,11 @@ Before inventing a custom implementation path:
 - Service-scene runtime-anchor bases that should not register in `IBeanRecordGeneral` should prefer the `src/service/*_.ts` form.
 - `src/bean` defines the global shorthand surface; classes that should not appear in `IBeanRecordGlobal` should move to `src/lib` or `src/service` rather than being filtered by `@Virtual()`.
 - When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, use `IBeanRecordGlobal` and module `src/.metadata/index.ts` as the first static lookup surface; use `IBeanRecordGeneral` or `src/service` only when the target is not a global shorthand.
+- When adding a persisted field to an existing backend resource, ask the user whether `vonaModule.fileVersion` should be incremented before changing `meta.version.ts` or the module schema path. If yes, add a new migration version and bump `fileVersion`. If no, keep the current `fileVersion` and fold the schema change into the current version path. Do not assume the versioning strategy without confirmation.
 
 ## Verification expectations
 
 - For docs changes: run the docs build and verify links/navigation where practical.
 - For code-generation or workflow guidance changes: verify that the referenced scripts and command families still exist.
 - For code changes: prefer the narrowest meaningful verification first, then use shared root scripts when broader confidence is needed.
+- Any change to `meta.version.ts` requires running `npm run test` so the test database is reinitialized and schema/data consistency issues surface early.

package/README.md

@@ -14,6 +14,21 @@ With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns comm
 
 [Documentation](https://docs.cabloy.com) · [npm](https://www.npmjs.com/package/cabloy) · [Web Demo](https://cabloy.com) · [Admin Demo](https://cabloy.com/admin) · [GitHub](https://github.com/cabloy/cabloy)
 
+## Fullstack Principles
+
+Cabloy’s fullstack model is built around two core principles:
+
+1. **Frontend build output participates directly in backend SSR**
+   - Zova owns the frontend application source
+   - the generated frontend bundle and SSR-related artifacts are consumed by the Vona-side SSR flow
+   - backend rendering and frontend hydration stay on one coordinated delivery path
+
+2. **Type information flows in both directions**
+   - **Backend -> Frontend**: Vona emits Swagger/OpenAPI contracts that Zova can use to generate SDKs and related schema-aware helpers
+   - **Frontend -> Backend**: Zova generates structural metadata and typing surfaces such as routes, components, and icons that can improve backend-side tooling and type hints
+
+For the complete explanation, see [Fullstack Introduction](https://docs.cabloy.com/fullstack/introduction), [Vona + Zova Integration](https://docs.cabloy.com/fullstack/vona-zova-integration), [Backend OpenAPI to Frontend SDK](https://docs.cabloy.com/fullstack/openapi-to-sdk), and [Frontend Metadata Back to Backend](https://docs.cabloy.com/fullstack/frontend-metadata-to-backend).
+
 ## Get Started
 
 ### Prerequisites

package/cabloy-docs/.vitepress/config.mjs

@@ -39,6 +39,26 @@ const fullstackGroups = [
       { text: 'Quickstart', link: '/fullstack/quickstart' },
     ],
   },
+  {
+    text: 'Fullstack / Tutorials',
+    items: [
+      { text: 'Tutorials Overview', link: '/fullstack/tutorials-overview' },
+      { text: 'Tutorial 1: First Module', link: '/fullstack/tutorial-1-first-module' },
+      { text: 'Tutorial 2: First CRUD', link: '/fullstack/tutorial-2-first-crud' },
+      {
+        text: 'Tutorial 3: Frontend Metadata Sharing',
+        link: '/fullstack/tutorial-3-frontend-metadata-sharing',
+      },
+      {
+        text: 'Tutorial 4: Backend Contract Sharing',
+        link: '/fullstack/tutorial-4-backend-contract-sharing',
+      },
+      {
+        text: 'Tutorial 5: One Contract Surface, Four Uses',
+        link: '/fullstack/tutorial-5-one-contract-four-uses',
+      },
+    ],
+  },
   {
     text: 'Tooling & Workflow',
     items: [
@@ -75,6 +95,7 @@ const referenceGroups = [
       { text: 'Introduction', link: '/reference/introduction' },
       { text: 'Repo Scripts', link: '/reference/repo-scripts' },
       { text: 'CLI Reference', link: '/reference/cli-reference' },
+      { text: 'Bean Scene Boilerplate Variants', link: '/reference/bean-scene-boilerplates' },
     ],
   },
   {
@@ -182,6 +203,7 @@ export default defineConfig({
           text: 'Core Programming Model',
           items: [
             { text: 'AOP Overview', link: '/backend/aop-overview' },
+            { text: 'Bean Scene Authoring', link: '/backend/bean-scene-authoring' },
             { text: 'Controller Guide', link: '/backend/controller-guide' },
             { text: 'Controller AOP Guide', link: '/backend/controller-aop-guide' },
             { text: 'Internal AOP Guide', link: '/backend/internal-aop-guide' },
@@ -223,6 +245,10 @@ export default defineConfig({
             { text: 'Schedule Guide', link: '/backend/schedule-guide' },
             { text: 'Worker Guide', link: '/backend/worker-guide' },
             { text: 'Broadcast Guide', link: '/backend/broadcast-guide' },
+            { text: 'Web Socket Guide', link: '/backend/websocket-guide' },
+            { text: 'Web Socket Usage Guide', link: '/backend/websocket-usage-guide' },
+            { text: 'Web Socket Protocol Guide', link: '/backend/websocket-protocol-guide' },
+            { text: 'Web Socket Call Flow', link: '/backend/websocket-call-flow' },
             { text: 'Redlock Guide', link: '/backend/redlock-guide' },
           ],
         },
@@ -248,6 +274,8 @@ export default defineConfig({
           text: 'Architecture & Modules',
           items: [
             { text: 'IoC and Beans', link: '/frontend/ioc-and-beans' },
+            { text: 'Bean Scene Authoring', link: '/frontend/bean-scene-authoring' },
+            { text: 'Behavior Guide', link: '/frontend/behavior-guide' },
             { text: 'Modules and Suites', link: '/frontend/modules-and-suites' },
             { text: 'Module Scope', link: '/frontend/module-scope' },
             { text: 'Design Principles', link: '/frontend/design-principles' },
@@ -277,6 +305,17 @@ export default defineConfig({
             { text: 'Page Params Guide', link: '/frontend/page-params-guide' },
             { text: 'Zod Guide', link: '/frontend/zod-guide' },
             { text: 'Page Route Guide', link: '/frontend/page-route-guide' },
+            { text: 'Router Tabs Introduction', link: '/frontend/router-tabs-introduction' },
+            { text: 'Router Tabs Overview', link: '/frontend/router-tabs-overview' },
+            { text: 'Router Tabs Mechanism', link: '/frontend/router-tabs-mechanism' },
+            {
+              text: 'Router Tabs Route Meta Cookbook',
+              link: '/frontend/router-tabs-route-meta-cookbook',
+            },
+            {
+              text: 'Router Tabs Admin and Web Comparison',
+              link: '/frontend/router-tabs-admin-web-comparison',
+            },
             { text: 'Route Alias Guide', link: '/frontend/route-alias-guide' },
             { text: 'Navigation Guards Guide', link: '/frontend/navigation-guards-guide' },
           ],
@@ -313,6 +352,10 @@ export default defineConfig({
         {
           text: 'SSR',
           items: [
+            { text: 'SSR Architecture Overview', link: '/frontend/ssr-architecture-overview' },
+            { text: 'SSR Build and Deploy Guide', link: '/frontend/ssr-build-deploy-guide' },
+            { text: 'SSR Troubleshooting Guide', link: '/frontend/ssr-troubleshooting-guide' },
+            { text: 'SSR Review Checklist', link: '/frontend/ssr-review-checklist' },
             { text: 'SSR Overview', link: '/frontend/ssr-overview' },
             { text: 'SSR Init Data', link: '/frontend/ssr-init-data' },
             { text: 'SSR ClientOnly', link: '/frontend/ssr-client-only' },

package/cabloy-docs/ai/class-placement-rule.md

@@ -27,6 +27,8 @@ Recommended placement:
 
 - `src/lib`
 
+For reusable module-local helper functions that are not classes, follow the same structural idea: initialize the module `src/lib` directory and place shared pure helper functions there. For the fuller backend placement context around module-local helpers, also see [Backend Foundation](/backend/foundation).
+
 ### B1: subclass-only base
 
 Use B1 when the class mainly exists as a superclass for concrete subclasses.

package/cabloy-docs/ai/cli-to-skill-map.md

@@ -145,6 +145,13 @@ Typical skill role:
 - likely CLI path: Zova `openapi:*` or REST build flows
 - skill then verifies the right edition-specific flavor path
 
+### Example: “Update a field on an existing backend resource”
+
+- skill decides this is an existing-resource field-update task
+- skill classifies persisted-field vs metadata-only refinement
+- likely CLI path: Vona persistence verification plus Zova metadata/build flows only if renderer follow-up is required
+- skill then verifies entity, locale, tests, `fileVersion` logic, and renderer/build/deps follow-up when applicable
+
 ## Anti-patterns
 
 Avoid these mistakes in skills:

package/cabloy-docs/ai/future-skill-roadmap.md

@@ -67,7 +67,22 @@ Primary dependencies:
 - Zova OpenAPI SDK and server-data docs
 - fullstack collaboration docs
 
-### 4. Metadata refresh skill
+### 4. Resource field update skill
+
+Purpose:
+
+- handle updates to fields on existing backend resources
+- force the right `fileVersion` decision for new persisted fields
+- branch correctly between shared renderer reuse and custom renderer demo follow-up
+- verify entity, locale, migration, test, metadata, build, and dependency-sync implications
+
+Primary dependencies:
+
+- Vona entity / migration / DTO workflow knowledge
+- Zova metadata/build flows when renderer follow-up is involved
+- the backend resource field workflow note in `.docs-internal/`
+
+### 5. Metadata refresh skill
 
 Purpose:
 
@@ -81,7 +96,7 @@ Primary dependencies:
 - CLI-to-skill mapping
 - edition detection docs
 
-### 5. Distributed backend workflow skill
+### 6. Distributed backend workflow skill
 
 Purpose: