cabloy 5.1.49 → 5.1.51

package/.claude/skills/cabloy-backend-scaffold/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: cabloy-backend-scaffold
+description: Use this skill whenever the user wants the Vona backend path in this Cabloy repo: scaffold or extend modules, beans, controllers, services, models, entities, DTOs, CRUD resources, migrations, indexes, validation, OpenAPI-facing backend files, or backend tests. Trigger for questions about which npm run vona generator or CRUD command to use and what backend follow-up is required after generation, especially when the user mentions create:bean, CRUD, meta.version, field indexes, DTOs, or tests. Prefer it for backend-first requests, even if they may later require frontend contract regeneration. Do not use it for frontend-first Zova work or stale generated consumer diagnosis.
+---
+
+# Cabloy Backend Scaffold
+
+Use this skill when the user wants to add or extend a Vona backend feature thread.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. stay backend-first unless the request clearly becomes a larger fullstack workflow
+3. prefer Vona CLI generation and CRUD tools over manual scaffolding
+4. always perform a backend follow-up review so migration, field indexes, DTO/OpenAPI contracts, and tests are not forgotten
+5. add a frontend-contract reminder only when the backend change likely affects OpenAPI consumers or generated SDK flows
+6. finish with verification guidance that matches the scope of the change
+
+## Step 1: Detect repo and task scope
+
+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 nearby scripts and ask before making edition-specific assumptions
+
+Then classify the request:
+
+- **backend-only** if the task is about Vona modules, beans, models, entities, DTOs, CRUD, migration, tests, or backend contracts
+- **fullstack** only if the task clearly requires frontend SDK regeneration, frontend page/component work, or a broader cross-stack contract loop
+
+Default to backend-first. Only escalate mentally to a broader fullstack workflow when the backend change obviously crosses the contract boundary.
+
+If the task is really a broad cross-stack workflow, consider whether the root `cabloy-workflow` skill is the better primary router.
+
+## Step 2: Start from Vona CLI and repo entrypoints
+
+Inspect these surfaces before proposing implementation:
+
+- the repository or workspace `package.json` that owns the scripts
+- `npm run vona`
+- Vona command families such as `create:*`, `init:*`, `tools:*`, and `bin:*`
+- `cabloy-docs/backend/` for the relevant backend thread
+
+For deeper reference material, read:
+
+- `references/backend-thread-map.md`
+- `references/follow-up-checklist.md`
+
+## Step 3: Choose the correct scaffolding path
+
+### Path A: create one backend bean or module piece
+
+Use `create:*` when the user needs one structural piece such as:
+
+- module
+- bean
+- controller
+- service
+- model
+- entity
+- dto
+- test
+
+Typical examples:
+
+- `npm run vona :create:module ...`
+- `npm run vona :create:bean controller ...`
+- `npm run vona :create:bean dto ...`
+- `npm run vona :create:test ...`
+
+### Path B: create a full CRUD thread
+
+Use `tools:*` when the user needs a whole backend thread rather than one isolated file.
+
+Typical example:
+
+- `npm run vona :tools:crud ...`
+
+Choose this path when the user asks for a CRUD feature, an admin-style backend resource thread, or a connected set of controller/service/model/entity/dto/test files.
+
+### Path C: initialize supporting module resources
+
+Use `init:*` when the task is really about module support files rather than business logic itself.
+
+Typical areas include:
+
+- config
+- locale
+- constant
+- asset
+- types
+
+## Step 4: Inspect the generated backend thread
+
+After generation, inspect what the CLI created and keep it as the baseline.
+
+Typical backend thread pieces include:
+
+- controller
+- service
+- model
+- entity
+- dto
+- migration/meta files
+- locale files
+- tests
+
+Do not throw away the generated structure and rewrite it from scratch unless the generator clearly does not match the task.
+
+## Step 5: Apply backend follow-up logic deliberately
+
+Backend scaffolding is rarely complete after file generation alone. Treat this follow-up review as mandatory.
+
+Check which of these concerns apply:
+
+### Contract and validation
+
+Check whether the feature needs:
+
+- request validation
+- DTO design
+- OpenAPI metadata
+- inferred DTO generation
+
+### Persistence and schema lifecycle
+
+Check whether the feature needs:
+
+- migration/version updates
+- `meta.version`
+- field indexes
+- relation definitions
+- datasource or cache considerations
+
+### Verification
+
+Check whether the feature needs:
+
+- unit tests
+- `db:reset` or migration verification
+- controller action testing
+- broader `test` / `tsc` / `build` checks
+
+### Optional frontend-contract reminder
+
+Stay backend-first, but if the backend change likely affects frontend contract consumers, add a reminder such as:
+
+- OpenAPI output may have changed
+- frontend SDK or schema-driven layers may need regeneration
+- the active edition and frontend flavor may matter for the regeneration path
+
+Do not turn the skill into a full frontend workflow. Only surface the reminder when the contract boundary is clearly involved.
+
+## Step 6: Use docs to avoid missing layers
+
+Use the docs to decide what the generated backend thread still needs.
+
+Especially relevant pages include:
+
+- `cabloy-docs/backend/controller-guide.md`
+- `cabloy-docs/backend/service-guide.md`
+- `cabloy-docs/backend/model-guide.md`
+- `cabloy-docs/backend/entity-guide.md`
+- `cabloy-docs/backend/dto-guide.md`
+- `cabloy-docs/backend/crud-workflow.md`
+- `cabloy-docs/backend/migration-and-changes.md`
+- `cabloy-docs/backend/field-indexes.md`
+- `cabloy-docs/backend/unit-testing.md`
+- `cabloy-docs/backend/validation-guide.md`
+- `cabloy-docs/backend/openapi-guide.md`
+- `cabloy-docs/backend/dto-infer-generation.md`
+
+## Step 7: Verification guidance
+
+Always end with a verification path that matches the scope of the backend change.
+
+Typical shared checks include:
+
+- `npm run test`
+- `npm run tsc`
+- `npm run build`
+
+Narrower checks may include:
+
+- module test updates
+- route/controller action verification
+- migration reset flow
+- CRUD workflow test coverage
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. backend-first or clearly fullstack-sensitive classification
+3. recommended Vona CLI path
+4. required backend follow-up layers to check
+5. optional frontend-contract reminder if applicable
+6. verification steps
+
+Keep the response practical. The value of this skill is turning Cabloy backend requests into the right generation + refinement + verification workflow, not writing more prose than necessary.

package/.claude/skills/cabloy-backend-scaffold/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "cabloy-backend-scaffold",
+  "evals": [
+    {
+      "id": 11,
+      "prompt": "I want to add an invoice backend feature in Cabloy. Please do not give me a generic architecture essay — tell me exactly whether I should start with create:bean commands or the CRUD generator, and what backend layers are mandatory to review after generation.",
+      "expected_output": "Must explicitly choose the CRUD generator or the precise Vona generator path first, must state that backend follow-up review is mandatory, and must mention at least migration/version plus DTO/OpenAPI or tests.",
+      "files": []
+    },
+    {
+      "id": 12,
+      "prompt": "I already changed a Vona DTO and controller response for an admin endpoint. I am not asking for frontend implementation help yet. Give me backend-first closure guidance and only mention frontend if it is truly just a contract reminder.",
+      "expected_output": "Must remain backend-first, must not turn into a full frontend workflow, must include backend contract checks, and any frontend mention must be clearly framed as a limited reminder only.",
+      "files": []
+    },
+    {
+      "id": 13,
+      "prompt": "I need to add order settlement in Cabloy Start. I care about the Vona backend thread first. Please tell me the exact generation path and the non-optional backend follow-up checklist after scaffolding.",
+      "expected_output": "Must detect Start-sensitivity, still lead with the Vona backend generation path, and explicitly frame migration/index/DTO/OpenAPI/tests as non-optional backend review items.",
+      "files": []
+    },
+    {
+      "id": 14,
+      "prompt": "I changed a model relation and some entity fields in Cabloy Basic. Before you tell me anything else, I want the Cabloy backend done-checklist, not a broad explanation of ORM theory.",
+      "expected_output": "Must give a concrete backend completion checklist, must include relation-aware follow-up and metadata or migration review, and must stay practical rather than drifting into generic ORM explanation.",
+      "files": []
+    }
+  ]
+}

package/.claude/skills/cabloy-backend-scaffold/references/backend-thread-map.md

@@ -0,0 +1,52 @@
+# Backend Thread Map
+
+Use this reference when a backend request needs to be turned into the right Vona thread.
+
+## Common request -> likely thread
+
+### “Add a controller action”
+
+Usually means:
+
+- controller update
+- service update
+- DTO and validation check
+- OpenAPI contract check
+- test update
+
+### “Add a new backend resource”
+
+Usually means:
+
+- controller
+- service
+- model
+- entity
+- dto
+- migration/version
+- test
+
+Consider whether `npm run vona :tools:crud ...` is a better fit than piecemeal creation.
+
+### “Add a model or entity change”
+
+Usually means:
+
+- model/entity update
+- migration/version update
+- possibly field indexes
+- possibly DTO/OpenAPI changes
+- possibly cache or relation review
+
+### “Just add a DTO”
+
+Usually means:
+
+- DTO creation or inference decision
+- validation rule alignment
+- OpenAPI contract alignment
+- controller/service usage updates
+
+## Generation-first rule
+
+If a Vona generator exists for the thread, use it first and refine second.

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -0,0 +1,39 @@
+# Follow-up Checklist
+
+After generating or extending a backend thread, check which follow-up layers apply.
+
+## Structural follow-up
+
+- controller path and action shape
+- service ownership of business logic
+- model/entity pairing
+- DTO design
+
+## Contract follow-up
+
+- validation rules
+- OpenAPI metadata
+- inferred DTO opportunities
+- frontend contract impact
+
+## Persistence follow-up
+
+- migration/version changes
+- `meta.version`
+- field indexes
+- relations
+- datasource choice
+- cache behavior
+- transaction behavior
+
+## Verification follow-up
+
+- unit tests
+- `db:reset` or migration verification
+- `npm run test`
+- `npm run tsc`
+- `npm run build`
+
+## Escalation rule
+
+If the request clearly affects frontend SDK, schema, or page logic too, hand off mentally to a fullstack workflow instead of pretending it is backend-only.

package/.claude/skills/cabloy-contract-loop/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: cabloy-contract-loop
+description: Use this skill whenever a Cabloy task crosses the Vona-to-Zova contract boundary: backend DTO, controller, validation, entity, inferred DTO, or OpenAPI changes that should drive SDK, schema, api, model, or rest-output regeneration, or stale generated frontend consumers that may be out of sync with backend truth. Trigger for requests about stale home-api output, OpenAPI regeneration, whether to regenerate instead of hand-patching types, or how to verify the Cabloy Basic or Cabloy Start contract loop end to end. Prefer it when the main problem is backend/frontend sync or diagnosis, not initial backend scaffolding or frontend page/component scaffolding.
+---
+
+# Cabloy Contract Loop
+
+Use this skill when a backend contract change needs to be reflected in frontend consumers, or when frontend consumers appear stale and you need to diagnose whether the backend contract loop is the real source of drift.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify whether the task truly crosses the backend/frontend contract boundary
+3. support both forward contract changes and reverse stale-consumer detection
+4. keep the workflow contract-first instead of hand-patching generated frontend types or services
+5. prefer CLI-first regeneration paths on both Vona and Zova sides
+6. finish with end-to-end verification guidance that checks both contract production and consumption
+
+## Step 1: Detect repo and contract scope
+
+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 nearby scripts and ask before making edition-specific assumptions
+
+Then classify whether the task is really a contract-loop task.
+
+Use this skill in two common entry modes.
+
+### Mode A: forward contract change
+
+The user already changed or plans to change backend contract surfaces such as:
+
+- controller request or response shape
+- DTO shape
+- entity field shape that feeds API-facing contracts
+- validation rules
+- OpenAPI metadata
+- inferred DTO or ORM DTO output that affects API consumers
+
+### Mode B: reverse stale-consumer detection
+
+The user reports symptoms on the frontend side such as:
+
+- stale SDK types
+- stale schema-driven UI behavior
+- API/model consumers no longer matching backend reality
+- hand-patched frontend types that seem to drift from backend truth
+
+In this mode, first diagnose whether the frontend is stale because the backend contract changed and the regeneration loop was skipped.
+
+If the task is only backend scaffolding or only frontend scaffolding, the more specialized scaffold skills may be the better primary choice.
+
+## Step 2: Start from the contract source of truth
+
+Inspect these surfaces before proposing workflow:
+
+- the repository or workspace `package.json` that owns the scripts
+- backend contract-defining code in Vona
+- `npm run zova`
+- frontend generation or consumption path in Zova
+- relevant docs in `cabloy-docs/fullstack/`, `cabloy-docs/backend/`, and `cabloy-docs/frontend/`
+
+For deeper reference material, read:
+
+- `references/contract-loop-map.md`
+- `references/verification-checklist.md`
+
+## Step 3: Identify the contract source of truth deliberately
+
+In Cabloy, the backend is often the source of truth for the contract. Treat that as the default unless the codebase clearly shows a generated or schema-owned frontend artifact that should be regenerated from backend output.
+
+### If this is a forward change
+
+Start with the backend side and update the contract deliberately.
+
+Typical backend layers to inspect or change include:
+
+- controller action signatures and annotations
+- DTO classes
+- entity field metadata
+- validation rules and `v` helpers
+- inferred DTO generation paths
+- OpenAPI configuration or metadata annotations
+
+The key rule is:
+
+- do **not** patch frontend consumers first if the backend contract is the real source of truth
+
+### If this is reverse stale-consumer detection
+
+Do not assume the frontend is the right place to fix the problem.
+
+Instead:
+
+1. inspect what frontend artifact looks stale
+2. identify whether that artifact is generated, schema-driven, or hand-authored
+3. inspect the backend contract source that should feed it
+4. only then decide whether the fix is regeneration, backend correction, or a genuine frontend bug
+
+## Step 4: Verify backend contract output before touching frontend consumers
+
+Before regenerating frontend artifacts, confirm the backend-side contract is actually correct.
+
+That may include:
+
+- reviewing controller return contracts
+- confirming DTO and validation alignment
+- checking Swagger/OpenAPI output
+- confirming that the changed endpoint or schema now reflects the intended contract
+
+If the backend contract output is wrong, frontend regeneration will only spread the mistake.
+
+## Step 5: Choose the right frontend regeneration path
+
+Once the backend contract is correct, decide how the frontend should consume it.
+
+### Path A: OpenAPI / SDK regeneration
+
+Use this when the frontend consumes generated API contracts.
+
+Typical Zova commands include:
+
+- `npm run zova :openapi:config ...`
+- `npm run zova :openapi:generate ...`
+
+### Path B: REST/type generation by flavor
+
+Use the edition-specific Zova REST/type build path when the workflow depends on the built flavor outputs.
+
+Typical examples in Cabloy Basic include:
+
+- `cd zova && npm run build:rest:cabloyBasicAdmin`
+- `cd zova && npm run build:rest:cabloyBasicWeb`
+
+For Cabloy Start, verify the exact Start-specific flavor names and paths in the Start repo.
+
+### Path C: Downstream frontend alignment
+
+After generation, inspect whether the frontend still needs follow-up in:
+
+- API services
+- model-managed remote state
+- schema-driven UI
+- page or component assumptions
+
+## Step 6: Keep edition-aware differences explicit
+
+The collaboration model is shared across Basic and Start, but the operational details may differ.
+
+Especially verify:
+
+- active repo marker
+- affected frontend flavor
+- whether the change affects Admin, Web, or both
+- whether the generated output path is edition-specific
+
+Do not silently reuse Basic-specific examples in Start workflows.
+
+## Step 7: End-to-end verification
+
+A fullstack contract loop is not done until both sides are checked.
+
+### Backend-side verification
+
+Typical checks may include:
+
+- controller-level tests
+- OpenAPI inspection
+- `npm run test`
+- `npm run tsc`
+- `npm run build`
+
+### Frontend-side verification
+
+Typical checks may include:
+
+- SDK or metadata regeneration success
+- `npm run tsc:zova`
+- `npm run build:zova`
+- flavor-specific or route-specific checks
+- schema-driven consumer alignment
+
+## Step 8: Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. why this is a contract-loop task
+3. backend source-of-truth layer to change first
+4. frontend regeneration path to run second
+5. edition-specific operational notes
+6. end-to-end verification steps
+
+Keep the response practical. The value of this skill is to prevent contract drift between Vona and Zova by guiding the user through the right backend-first, regeneration-second, verification-third workflow.

package/.claude/skills/cabloy-contract-loop/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "cabloy-contract-loop",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I changed a Vona DTO and controller response for an admin API in Cabloy Basic. What is the correct fullstack contract loop to get the frontend back in sync?",
+      "expected_output": "Treats the task as a contract-loop workflow, changes the backend contract first, verifies OpenAPI output, then recommends the correct frontend regeneration path and verification.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Our frontend SDK types look stale after a backend entity and validation change. I do not want hand-patched frontend types. Tell me the Cabloy way to fix the contract loop.",
+      "expected_output": "Rejects hand-patching as the primary fix, identifies backend contract source-of-truth, recommends regeneration, and includes both backend and frontend verification.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "We are working in Cabloy Start and changed an API shape that affects the admin frontend. What should Claude do so the backend and frontend contracts stay aligned?",
+      "expected_output": "Detects Start sensitivity, keeps the backend-first contract path clear, then gives Start-aware frontend regeneration and verification guidance.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The frontend model and generated SDK in Cabloy Basic look stale after a backend response change, but I am not sure whether the real bug is in backend OpenAPI output or in skipped frontend regeneration. Diagnose the contract loop the Cabloy way.",
+      "expected_output": "Handles reverse stale-consumer detection, checks backend source-of-truth first, avoids hand-patching frontend types as the primary fix, and proposes regeneration or backend correction based on the contract path.",
+      "files": []
+    }
+  ]
+}

package/.claude/skills/cabloy-contract-loop/references/contract-loop-map.md

@@ -0,0 +1,47 @@
+# Contract Loop Map
+
+Use this reference when a task crosses the backend/frontend contract boundary.
+
+## Typical triggers
+
+### Backend contract changed
+
+Common examples:
+
+- DTO shape changed
+- controller request/response changed
+- validation changed
+- `@Api.field` or OpenAPI metadata changed
+- inferred DTO output changed
+
+Likely next step:
+
+- verify backend OpenAPI output
+- regenerate the frontend consumer path
+
+### Frontend consumer drift
+
+Common examples:
+
+- generated SDK no longer matches backend
+- schema-driven UI expects old shape
+- model or API service types are stale
+
+Likely next step:
+
+- confirm whether backend contract really changed
+- regenerate instead of hand-patching
+
+## Shared rule
+
+The sequence is usually:
+
+1. change backend contract
+2. verify backend contract output
+3. regenerate frontend artifacts
+4. inspect frontend consumers
+5. verify end to end
+
+## Anti-pattern
+
+Do not patch frontend generated artifacts first when the backend contract is the real source of truth.

package/.claude/skills/cabloy-contract-loop/references/verification-checklist.md

@@ -0,0 +1,32 @@
+# Verification Checklist
+
+After a contract-loop change, check both sides.
+
+## Backend verification
+
+- controller action contract is correct
+- DTO and validation align
+- OpenAPI output reflects the intended shape
+- backend tests pass
+- `npm run test`
+- `npm run tsc`
+- `npm run build`
+
+## Frontend verification
+
+- regeneration commands completed successfully
+- generated SDK/schema outputs are updated
+- API/model/page/component consumers still typecheck
+- `npm run tsc:zova`
+- `npm run build:zova`
+- relevant flavor-specific or route-specific checks
+
+## Edition verification
+
+- Basic or Start marker confirmed
+- affected flavor confirmed
+- generation path matches the active edition
+
+## Done rule
+
+A contract-loop task is not done when only the backend compiles or only the frontend builds. It is done when the contract source and the generated consumer path agree.