cabloy 5.1.59 → 5.1.61

package/.claude/skills/cabloy-resource-field-update/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "skill_name": "cabloy-resource-field-update",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Please add a new persisted level field to the existing student resource in Cabloy Basic. Before doing anything else, tell me whether fileVersion needs a decision and what layers must be updated.",
+      "expected_output": "Must classify the task as a new persisted field on an existing resource, must require a fileVersion decision before migration edits, and must mention entity, meta.version, package.json, locale, and tests as relevant follow-up layers.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I want to add a new persisted field to an existing Cabloy resource, but do not bump fileVersion — fold it into the current version path. What workflow should Claude follow?",
+      "expected_output": "Must recognize the no-bump branch, keep the current fileVersion, avoid creating a new migration version branch, and still mention schema-path, entity, locale, and tests as required follow-up surfaces.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The level field already exists in storage. I only want to tighten it to an enum-like 1/2/3 field and attach select-style render metadata. Keep this as a field refinement workflow, not a migration plan.",
+      "expected_output": "Must classify the task as metadata-only or validation/render-only refinement, must avoid unnecessary fileVersion escalation, and must mention explicit validation, renderer metadata, locale, and invalid-value testing.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "In Cabloy Basic, please update the existing student resource field so it uses the best existing shared renderer first. I want the Cabloy way, not a custom component unless it is really needed.",
+      "expected_output": "Must prefer shared renderer reuse first, should mention basic-select as the default Cabloy Basic select-style baseline for enum-like fields, and should not jump straight into custom renderer creation.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I know the shared renderer would work, but I explicitly want a custom renderer demo for this existing backend field so future AI can learn the workflow. What should Claude do?",
+      "expected_output": "Must branch into the custom renderer demo workflow, must mention a module-local FormField component plus a module-local @TableCell bean, and must include metadata generation, frontend build, deps:vona, and Vona verification steps.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Create a brand new CRUD resource for courses in Cabloy and tell me the best generation path.",
+      "expected_output": "Must not treat this as an existing-resource field-update workflow. It should indicate that initial CRUD/resource creation belongs to the backend scaffold or a broader workflow, not this skill.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "In Cabloy Basic, the level field already exists and I want select-style field rendering for it. Claude should use the shared renderer path, and unless the UX truly requires a preselected value, I want the field to start unchosen with a visible hint. What guidance should Claude follow?",
+      "expected_output": "Must classify this as an existing-field refinement, prefer the shared Cabloy Basic select renderer path, default to providing a user-visible placeholder for the field-rendering select component unless the UX clearly requires a preselected value, and prefer placeholder over artificial empty-item injection for Cabloy Basic rather than assuming the same behavior in Cabloy Start.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "In Cabloy Start, the level field already exists and now needs select-style field rendering. I want Claude to reuse the right shared renderer path if possible, and I also care about how an initially unchosen state should work. What guidance should Claude follow?",
+      "expected_output": "Must classify this as an existing-field refinement, must detect that this is Cabloy Start, must still prefer shared renderer reuse first rather than jumping straight to a custom renderer, must not jump straight to Cabloy Basic renderer keys such as basic-select, and must say to inspect the Start-side select wrapper and underlying component semantics before deciding renderer keys or copying Cabloy Basic placeholder or empty-item behavior.",
+      "files": []
+    }
+  ]
+}

package/.claude/skills/cabloy-resource-field-update/references/custom-renderer-demo-checklist.md

@@ -0,0 +1,102 @@
+# Custom Renderer Demo Checklist
+
+Use this checklist when the user explicitly wants to demonstrate how a backend resource field can switch from a shared renderer to a custom module-local renderer.
+
+## Goal
+
+Preserve the field’s backend business semantics while deliberately exercising the full frontend renderer registration path.
+
+## 1. Confirm the task is really instructional
+
+Use this branch when the user wants to show:
+
+- how to build a custom FormField component
+- how to build a custom backend-usable TableCell renderer
+- how to connect them back to `ZovaRender.field(...)` / `ZovaRender.cell(...)`
+
+If the user only wants the simplest production implementation, prefer shared renderer reuse instead.
+
+## 2. Keep business semantics unchanged if possible
+
+Do not rework field meaning unless the request also asks for it.
+
+Preserve existing semantics such as:
+
+- allowed values
+- locale labels
+- `items`, `itemValue`, `itemTitle`
+- backend field name and DTO flow
+
+## 3. Build the correct frontend pair
+
+### FormField
+
+Add a module-local FormField component such as:
+
+- `src/component/formFieldX/controller.tsx`
+
+Best practice:
+
+- reuse the option shape of the closest shared renderer
+- copy the data flow from the shared baseline first
+- default to providing a user-visible `placeholder` for field-rendering select components unless the UX clearly requires an always-preselected value
+- in Cabloy Basic, keep placeholder handling aligned with `basic-select` semantics instead of adding artificial empty items by default
+- in Cabloy Start, verify the `start-select` wrapper behavior before copying Basic-specific placeholder or empty-item logic
+- keep customizations minimal and clearly demo-oriented
+
+### TableCell
+
+Add a module-local `@TableCell(...)` bean such as:
+
+- `src/bean/tableCell.x.tsx`
+
+Important:
+
+- backend `ZovaRender.cell(...)` should point to a registered table-cell key
+- a plain frontend component is not enough for this role
+
+## 4. Use the best existing baseline
+
+For select-like enum fields, start from an edition-correct baseline.
+
+In Cabloy Basic, start from:
+
+- `basic-select` FormField behavior
+- `basic-select` table-cell bean behavior
+
+In Cabloy Start:
+
+- identify the Start-side select baseline first rather than reusing Basic components by name
+- verify placeholder and empty-state behavior before copying Basic-specific logic
+
+The goal is to demonstrate module-local customization, not to reinvent field-state handling.
+
+## 5. Regenerate and synchronize in the right order
+
+Recommended order:
+
+1. create or update renderer source files
+2. regenerate frontend metadata
+3. run the relevant frontend build so both bundle output and type surface update
+4. run `deps:vona`
+5. run Vona typecheck
+6. run the narrow backend resource test
+
+For Cabloy Basic admin, the representative flow is:
+
+```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
+```
+
+## 6. Recovery rule when generated keys still look stale
+
+If the generated `.zova-rest` files already contain the new renderer keys but Vona still behaves as if old types are installed:
+
+- suspect a stale or unhealthy `vona/node_modules` installation state
+- after normal `deps:vona`, rebuild `vona/node_modules` and reinstall dependencies if needed
+
+This is an installation-state recovery step, not the normal first move.

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/.claude/skills/cabloy-zova-source-reading/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: cabloy-zova-source-reading
+description: Use this skill when the user wants to read, trace, or explain Zova frontend source code rather than scaffold new code: where a page/component/model/behavior/SSR flow is implemented, how a runtime path works internally, why a plain controller field is reactive, how Zova differs from generic Vue 3 habits, or which files to read first. Trigger for requests about Zova source reading, runtime tracing, Vue-vs-Zova explanation, controller/bean/IoC mental models, or the Zova-native way to understand frontend behavior. Do not use it for normal frontend scaffolding or backend/frontend contract regeneration.
+---
+
+# Cabloy Zova Source Reading
+
+Use this skill when the task is to understand, explain, or trace Zova frontend behavior in source code.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify whether the user needs a source-entry map, a runtime-flow trace, or a Vue-vs-Zova explanation
+3. start from Zova-native public docs before diving into framework source
+4. explain Zova architecture in its own terms before translating it into Vue analogies
+5. separate source-confirmed runtime behavior from interpretive comparison
+6. finish with verification guidance that matches the analysis scope
+
+## Step 1: Detect the active edition
+
+Check the repository root for these marker files:
+
+- `__CABLOY_BASIC__`
+- `__CABLOY_START__`
+
+Interpretation:
+
+- `__CABLOY_BASIC__` present → this is Cabloy Basic
+- `__CABLOY_START__` present → this is Cabloy Start
+- neither present → inspect the repo scripts and ask before making edition-specific frontend assumptions
+
+This matters most when the analysis becomes UI-sensitive, SSR-site-sensitive, flavor-sensitive, or module-set-sensitive.
+
+## Step 2: Classify the analysis mode
+
+Before reading files deeply, decide which kind of question the user is really asking.
+
+### Mode A: source-location mode
+
+Use this mode when the user is asking questions like:
+
+- where should I start reading?
+- which files are relevant?
+- what order should I read the source in?
+- where is this implemented in Zova?
+
+### Mode B: runtime-flow mode
+
+Use this mode when the user is asking questions like:
+
+- how does this work internally?
+- why is this field reactive?
+- where does `$computed` / `$params` / `$query` come from?
+- how does page/controller/component render enter the runtime?
+
+### Mode C: Vue-vs-Zova comparison mode
+
+Use this mode when the user is asking questions like:
+
+- how should I understand this relative to Vue 3?
+- is this just Vue with classes?
+- what is the Zova way instead of the generic Vue way?
+- how do controller / bean / model / render roles map to Vue concepts?
+
+If a request spans more than one mode, answer in this order:
+
+1. source-location mode
+2. runtime-flow mode
+3. Vue-vs-Zova comparison mode
+
+That order reduces the risk of drifting into premature analogy before the source path is understood.
+
+## Step 3: Start from public Zova docs first
+
+Do not begin by forcing the problem into generic Vue terminology.
+
+Start from the public frontend reading docs in `cabloy-docs/frontend/`.
+
+### Primary reading surfaces
+
+- `cabloy-docs/frontend/reading-zova-for-vue-developers.md`
+- `cabloy-docs/frontend/zova-vs-vue3-comparison.md`
+- `cabloy-docs/frontend/zova-reactivity-under-the-hood.md`
+- `cabloy-docs/frontend/zova-source-reading-map.md`
+
+For compact procedural summaries inside the skill bundle, also use:
+
+- `references/analysis-modes.md`
+- `references/core-reading-paths.md`
+
+### Core architecture surfaces
+
+Use these when the question needs broader architectural context:
+
+- `cabloy-docs/frontend/introduction.md`
+- `cabloy-docs/frontend/foundation.md`
+- `cabloy-docs/frontend/design-principles.md`
+- `cabloy-docs/frontend/ioc-and-beans.md`
+- `cabloy-docs/frontend/page-guide.md`
+- `cabloy-docs/frontend/component-guide.md`
+- `cabloy-docs/frontend/model-architecture.md`
+- `cabloy-docs/frontend/page-route-guide.md`
+- `cabloy-docs/frontend/behavior-guide.md`
+- `cabloy-docs/frontend/ssr-architecture-overview.md`
+
+## Step 4: Choose the shortest correct source-reading path
+
+After reading the public docs, choose the smallest source path that answers the question.
+
+Use these bundled references to keep the workflow compact:
+
+- `references/analysis-modes.md`
+- `references/core-reading-paths.md`
+
+Use the public `cabloy-docs/frontend/zova-source-reading-map.md` as the fuller explanation layer, but use the bundled references first when they are enough for the current task.
+
+## Step 5: Explain Zova-native meaning first
+
+When answering, explain the Zova role first, then add Vue analogies only if they help.
+
+### Required answer posture
+
+1. identify the Zova-native role first
+   - page controller
+   - component controller
+   - render bean
+   - style bean
+   - model bean
+   - service bean
+   - behavior bean
+   - route/SSR integration layer
+
+2. explain the source-confirmed runtime path second
+
+3. only then offer Vue analogies as approximate translations
+
+Do **not** lead with statements like:
+
+- "this is basically just Vue setup with classes"
+- "this should really be a normal Vue composable"
+- "the right end state is probably `ref.value`"
+
+Those translations can erase the actual Zova architecture.
+
+For component-wrapper questions specifically, remember that `controllerRef` exposes the controller instance, not a generic DOM ref, and should not be treated as a generic Vue component-ref substitute without checking the current wrapper/controller source path.
+
+## Step 6: Distinguish source-confirmed behavior from interpretive comparison
+
+Always make the boundary explicit.
+
+### Source-confirmed behavior
+
+This includes claims you can support directly from current source files, such as:
+
+- where a controller is created
+- where a bean becomes reactive
+- where route state is refreshed
+- where render is redirected
+- which helper wraps which Vue API
+
+### Interpretive comparison
+
+This includes claims such as:
+
+- why Zova feels more object-oriented than Vue
+- how Zova growth paths differ from typical Vue growth paths
+- which analogy is the closest Vue mental model
+
+These can be useful, but they should be labeled as interpretation rather than current-source fact.
+
+## Step 7: Stay inside the right workflow boundary
+
+Use this skill for explanation and source reading.
+
+Do **not** use it as the primary workflow when the real task is:
+
+- creating or refactoring frontend structures → prefer `cabloy-frontend-scaffold`
+- diagnosing backend/frontend contract drift → prefer `cabloy-contract-loop`
+- choosing whether the work belongs to backend, frontend, fullstack, docs, or AI guidance → prefer `cabloy-workflow`
+
+## Step 8: Verification guidance
+
+Always finish with a verification path that matches the analysis task.
+
+### For source-reading answers
+
+Verify:
+
+- the cited file paths exist
+- the described runtime path is actually visible in current source
+- the answer does not contradict the public frontend docs
+
+### For Vue-vs-Zova explanation answers
+
+Verify:
+
+- the Zova-native explanation comes first
+- Vue analogies are marked as approximate, not authoritative
+- no claim quietly rewrites Zova back into generic Vue habits
+
+### For edition-sensitive frontend analysis
+
+Verify:
+
+- the active edition marker was considered
+- Basic-only or Start-only UI assumptions were not silently generalized
+- SSR, theme, and flavor-sensitive statements match the active edition context
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. analysis mode
+3. public docs to read first
+4. source path to inspect next
+5. Zova-native explanation
+6. optional Vue analogy
+7. verification notes or caveats
+
+Keep the response practical. The value of this skill is to help AI and users read Zova source accurately and in the right architectural order, not to flatten Zova into generic Vue prose.