cabloy 5.1.49 → 5.1.51

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

@@ -0,0 +1,230 @@
+---
+name: cabloy-frontend-scaffold
+description: Use this skill whenever the user wants the Zova frontend path in this Cabloy repo: create or extend pages, components, api or model beans, route/query/params work, metadata refresh, SSR-sensitive frontend work, or component props, v-model, and generic refactors. Trigger for questions about which npm run zova create or refactor command to use and what frontend follow-up is required after generation, especially when the user wants the Zova way instead of generic Vue advice. Prefer it for frontend-first requests, even if backend context exists in the story. Do not use it for pure Vona scaffolding or backend/frontend contract-sync diagnosis.
+---
+
+# Cabloy Frontend Scaffold
+
+Use this skill when the user wants to add or extend a Zova frontend feature thread.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. stay frontend-first unless the request clearly becomes a broader fullstack contract or backend workflow
+3. prefer Zova CLI generation and refactor tools over manual scaffolding
+4. always perform a frontend follow-up review so route metadata, API/model integration, SSR behavior, style/theme/icon implications, and metadata regeneration are not forgotten
+5. add a backend-contract reminder only when the frontend change clearly depends on backend OpenAPI or DTO contract changes
+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:
+
+- **frontend-only** if the task is about Zova pages, components, API services, models, routing, params/query, metadata, icons, styles, or SSR behavior
+- **fullstack** only if the task clearly requires backend contract changes, SDK regeneration, or broader cross-stack contract work
+
+Default to frontend-first. Only escalate mentally to a broader fullstack workflow when the frontend task 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 Zova CLI and repo entrypoints
+
+Inspect these surfaces before proposing implementation:
+
+- the repository or workspace `package.json` that owns the scripts
+- `npm run zova`
+- Zova command families such as `create:*`, `init:*`, `refactor:*`, `tools:*`, `openapi:*`, and `bin:*`
+- `cabloy-docs/frontend/` for the relevant frontend thread
+
+For deeper reference material, read:
+
+- `references/frontend-thread-map.md`
+- `references/follow-up-checklist.md`
+
+## Step 3: Choose the correct frontend scaffolding path
+
+### Path A: create a new frontend structural piece
+
+Use `create:*` when the user needs a new structural piece such as:
+
+- page
+- component
+- api
+- model
+- module
+- mock
+- bean
+
+Typical examples:
+
+- `npm run zova :create:page ...`
+- `npm run zova :create:component ...`
+- `npm run zova :create:bean api ...`
+- `npm run zova :create:bean model ...`
+
+### Path B: add framework capabilities to an existing page or component
+
+Use `refactor:*` when the user is extending an existing Zova structure rather than creating a new one.
+
+Typical examples:
+
+- `npm run zova :refactor:pageQuery ...`
+- `npm run zova :refactor:pageParams ...`
+- `npm run zova :refactor:componentProps ...`
+- `npm run zova :refactor:componentModel ...`
+- `npm run zova :refactor:componentGeneric ...`
+
+Choose this path when the user already has a page or component and wants to add framework-native structure to it.
+
+### Path C: refresh metadata or generated contract output
+
+Use `tools:*` or `openapi:*` when the task is about generation rather than hand-authored frontend code.
+
+Typical examples:
+
+- `npm run zova :tools:metadata ...`
+- `npm run zova :openapi:config ...`
+- `npm run zova :openapi:generate ...`
+
+## Step 4: Inspect the generated or transformed frontend thread
+
+After generation or refactor, inspect what the CLI created and keep it as the baseline.
+
+Typical frontend thread pieces may include:
+
+- page or component controller
+- wrapper component
+- route record implications
+- API service or model bean
+- query/params schema additions
+- generated metadata-dependent artifacts
+
+Do not throw away the generated structure and rewrite it from scratch unless the generator clearly does not match the task.
+
+## Step 5: Apply frontend follow-up logic deliberately
+
+Frontend scaffolding is rarely complete after generation alone. Treat this follow-up review as mandatory.
+
+### Route and metadata follow-up
+
+Check whether the feature needs:
+
+- page route review
+- params/query schema alignment
+- alias or guard review
+- metadata regeneration
+
+### Data and contract follow-up
+
+Check whether the feature needs:
+
+- API service updates
+- model-managed remote state
+- SSR init-data updates
+- OpenAPI SDK regeneration
+- schema-driven UI or `$apiSchema` review
+
+### Component and interaction follow-up
+
+Check whether the feature needs:
+
+- props contract review
+- `v-model` review
+- generic component conversion
+- style/theme/icon updates
+- wrapper usage review
+- async-loading or controllerRef implications
+
+### Verification
+
+Check whether the feature needs:
+
+- typecheck
+- build
+- metadata regeneration verification
+- SSR or route-path verification
+- edition-specific flavor verification
+
+### Optional backend-contract reminder
+
+Stay frontend-first, but if the frontend task clearly depends on backend contract output, add a reminder such as:
+
+- backend OpenAPI output may need refresh or inspection
+- backend DTO/controller response shape may be the real source of truth
+- frontend SDK or schema-driven layers should be regenerated from contract output rather than hand-patched
+
+Do not turn the skill into a backend 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 frontend thread still needs.
+
+Especially relevant pages include:
+
+- `cabloy-docs/frontend/page-guide.md`
+- `cabloy-docs/frontend/page-query-guide.md`
+- `cabloy-docs/frontend/page-params-guide.md`
+- `cabloy-docs/frontend/page-route-guide.md`
+- `cabloy-docs/frontend/route-alias-guide.md`
+- `cabloy-docs/frontend/navigation-guards-guide.md`
+- `cabloy-docs/frontend/component-guide.md`
+- `cabloy-docs/frontend/component-props-guide.md`
+- `cabloy-docs/frontend/component-v-model-guide.md`
+- `cabloy-docs/frontend/generic-component-guide.md`
+- `cabloy-docs/frontend/api-guide.md`
+- `cabloy-docs/frontend/model-architecture.md`
+- `cabloy-docs/frontend/model-state-guide.md`
+- `cabloy-docs/frontend/openapi-sdk-guide.md`
+- `cabloy-docs/frontend/api-schema-guide.md`
+- `cabloy-docs/frontend/sdk-guide.md`
+- `cabloy-docs/frontend/ssr-overview.md`
+- `cabloy-docs/frontend/ssr-init-data.md`
+- `cabloy-docs/frontend/ssr-client-only.md`
+- `cabloy-docs/frontend/ssr-seo-meta.md`
+- `cabloy-docs/frontend/ssr-env.md`
+- `cabloy-docs/frontend/css-in-js-guide.md`
+- `cabloy-docs/frontend/theme-guide.md`
+- `cabloy-docs/frontend/icon-engine-guide.md`
+
+## Step 7: Verification guidance
+
+Always end with a verification path that matches the scope of the frontend change.
+
+Typical shared checks include:
+
+- `npm run tsc`
+- `npm run build:zova`
+
+If the task is inside `zova/` rather than the monorepo root wrapper path, use the smallest correct `zova/` script surface for the affected flavor or generation path.
+
+Narrower checks may include:
+
+- metadata refresh verification
+- page route verification
+- component wrapper or `v-model` behavior verification
+- SSR or flavor-specific build verification
+- edition-specific frontend script verification
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. frontend-first or clearly fullstack-sensitive classification
+3. recommended Zova CLI path
+4. required frontend follow-up layers to check
+5. optional backend-contract reminder if applicable
+6. verification steps
+
+Keep the response practical. The value of this skill is turning Cabloy frontend requests into the right generation + refactor + verification workflow, not writing more prose than necessary.

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

@@ -0,0 +1,35 @@
+{
+  "skill_name": "cabloy-frontend-scaffold",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to add a new frontend page for invoice management in Cabloy. Please tell me the right Zova workflow and what I should generate first.",
+      "expected_output": "Chooses a frontend scaffolding path, prefers Zova page generation or closely related CLI generation, and mentions follow-up layers like route/query/params, model/API, metadata, or verification.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Please help me add page params and page query support to an existing Zova page. I do not want generic Vue Router advice; I want the Cabloy way.",
+      "expected_output": "Routes to the Zova frontend refactor thread, recommends the right refactor path, and includes metadata or route follow-up instead of generic framework advice.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I changed a route and component structure in Cabloy Basic and now I am not sure what else I should update. What should Claude check before saying the frontend work is done?",
+      "expected_output": "Identifies likely frontend follow-up such as metadata regeneration, page/component/API/model or SSR impact, and verification commands.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I updated a Zova page and component contract, but I do not want backend implementation help yet. Keep this frontend-first and only mention backend if it is truly a contract reminder.",
+      "expected_output": "Stays frontend-first, covers page/component/metadata or model follow-up, and only adds a light backend-contract reminder if frontend work depends on backend OpenAPI or SDK output.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Help me add a new frontend page thread in Cabloy Start. I want the Zova way first, including what frontend follow-up review is mandatory after generation.",
+      "expected_output": "Detects Start or Start-sensitive edition handling, recommends Zova scaffolding first, and treats metadata, routing, API/model or SSR checks, and verification as mandatory frontend follow-up rather than optional extras.",
+      "files": []
+    }
+  ]
+}

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

@@ -0,0 +1,41 @@
+# Follow-up Checklist
+
+After generating or extending a frontend thread, check which follow-up layers apply.
+
+## Structural follow-up
+
+- page/controller structure
+- component wrapper usage
+- route record implications
+- params/query schema alignment
+
+## Data and contract follow-up
+
+- API service or model alignment
+- SSR init-data needs
+- OpenAPI SDK or schema-driven layer impact
+- backend contract reminder if frontend depends on generated backend contract output
+
+## Interaction and UI follow-up
+
+- props contract
+- `v-model`
+- generic typing
+- style / theme / icon implications
+
+## Metadata follow-up
+
+- `:tools:metadata`
+- route/component/icon regeneration-sensitive changes
+- edition-specific generated output review
+
+## Verification follow-up
+
+- `npm run tsc`
+- `npm run build:zova`
+- flavor-specific checks
+- route or SSR verification
+
+## Escalation rule
+
+If the request clearly changes backend contract output or requires SDK regeneration from backend changes, mentally escalate to a fullstack workflow instead of pretending it is frontend-only.

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

@@ -0,0 +1,54 @@
+# Frontend Thread Map
+
+Use this reference when a frontend request needs to be turned into the right Zova thread.
+
+## Common request -> likely thread
+
+### “Add a new page”
+
+Usually means:
+
+- page generation
+- route review
+- params/query additions if needed
+- API/model integration
+- metadata refresh if routing changes affect typed artifacts
+
+### “Add a new component”
+
+Usually means:
+
+- component generation
+- props/v-model/generic follow-up if needed
+- wrapper-based usage review
+- style/theme/icon review if UI behavior changes
+
+### “Add data access to a page”
+
+Usually means:
+
+- API service or model bean
+- possible OpenAPI SDK usage
+- possible SSR init-data follow-up
+- metadata or route refresh if the page shape changes too
+
+### “Change route/query/params behavior”
+
+Usually means:
+
+- page route review
+- `refactor:*` path first
+- metadata regeneration
+- route alias / guard / SSR review
+
+### “Change UI contract of a component”
+
+Usually means:
+
+- component props
+- `v-model`
+- generic component or wrapper behavior
+
+## Generation-first rule
+
+If a Zova generator or refactor command exists for the frontend thread, use it first and refine second.

package/.claude/skills/cabloy-workflow/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: cabloy-workflow
+description: Use this skill first when a Cabloy request is about choosing the right path before implementation: whether the work belongs to Vona backend scaffolding, Zova frontend scaffolding, backend/frontend contract sync, or docs, .docs-internal, CLAUDE.md, commands, or skills; which Cabloy Basic or Cabloy Start assumptions apply; or where Cabloy guidance should live. Trigger on requests that ask to route, classify, choose a workflow, choose an edition-specific path, or decide between docs, rules, and skills. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
+---
+
+# Cabloy Workflow
+
+Use this skill to choose the right workflow before making Cabloy changes.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. choose the correct layer of work: fullstack, backend, frontend, docs, or AI-enablement
+3. prefer Vona or Zova CLI capabilities over manual scaffolding whenever possible
+4. keep public docs, internal docs, rules, and skills in the correct locations
+5. finish with verification guidance that matches the scope of the task
+
+## 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 the user before making a strong edition-specific assumption
+
+This matters most for frontend work, UI-library assumptions, flavor names, and edition-specific modules.
+
+## Step 2: Identify the task layer
+
+Classify the request before proposing a workflow.
+
+### Fullstack
+
+Use the fullstack path when the task spans backend and frontend or touches shared scripts, integration, docs architecture, or cross-stack generation.
+
+Typical signals:
+
+- "fullstack"
+- "Cabloy"
+- backend + frontend in one request
+- OpenAPI + SDK + DTO + page generation
+- docs/rules/skills that must support both Vona and Zova
+
+### Backend (Vona)
+
+Use the backend path when the task is about:
+
+- suite, module, bean, service, controller, model, entity, DTO
+- CRUD generation
+- ORM, cache, queue, worker, schedule, auth, permissions
+- backend tests, build, play, or database reset
+
+### Frontend (Zova)
+
+Use the frontend path when the task is about:
+
+- page, component, mock, bean
+- SSR, Web, Admin, SPA
+- UI-library-sensitive work
+- OpenAPI SDK generation
+- frontend refactors such as page params, page query, component props, or model helpers
+
+### Docs and AI-enablement
+
+Use the docs/AI path when the task is about:
+
+- `cabloy-docs/`
+- `.docs-internal/`
+- `CLAUDE.md`
+- `.claude/commands/`
+- `.claude/skills/`
+- repo guidance for AI development
+
+## Step 3: Start from shared entrypoints
+
+Before inventing a workflow, inspect these shared surfaces:
+
+- the repository or workspace `package.json` that owns the active scripts
+- `npm run vona`
+- `npm run zova`
+- root `CLAUDE.md` if present
+- `cabloy-docs/` for public guidance
+- `.docs-internal/` for maintainer rationale
+
+If the request spans backend and frontend, classify it as fullstack by default unless the user clearly wants only one side.
+
+If edition markers are missing or the repo shape is ambiguous, inspect the nearby scripts and ask the user before making a strong edition-specific assumption.
+
+For deeper reference material, read:
+
+- `references/edition-detection.md`
+- `references/cli-strategy.md`
+
+The reason is simple: these files are where Cabloy already encodes its real workflows.
+
+## Step 4: Prefer CLI-first workflows
+
+Whenever the task maps to an existing generator, initializer, refactor, or metadata command, prefer the CLI.
+
+### Vona CLI families
+
+Typical families:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `tools:*`
+
+Typical use cases:
+
+- scaffold suite/module/bean/test resources
+- initialize config/locale/constant/error/assets/types
+- generate CRUD-related artifacts
+- refresh metadata or dependency-related output
+- run backend verification flows
+
+### Zova CLI families
+
+Typical families:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `refactor:*`
+- `tools:*`
+- `openapi:*`
+
+Typical use cases:
+
+- scaffold suite/module/page/component/mock/bean resources
+- initialize app/system assets and typing helpers
+- run focused refactors for page/component patterns
+- generate OpenAPI-related output
+- refresh metadata or dependency-related output
+
+## Step 5: Choose where the knowledge belongs
+
+When the user is asking for guidance or automation assets, route the work to the correct home.
+
+### Public docs
+
+Use `cabloy-docs/` for:
+
+- user-facing explanations
+- reusable AI-facing workflow guidance
+- edition-aware public documentation
+
+### Internal engineering docs
+
+Use `.docs-internal/` for:
+
+- ADRs
+- architecture notes
+- maintainer rationale
+- invariants and design boundaries
+
+### Root rules and commands
+
+Use `CLAUDE.md` and `.claude/commands/` for:
+
+- concise operational guidance
+- named recurring workflows
+- repo-wide behavior for Claude
+
+### Skills
+
+Use `.claude/skills/` for:
+
+- procedural workflows that benefit from reusable instructions
+- edition-aware decision trees
+- CLI-first orchestration paths
+- future bundled references or deterministic helper scripts
+
+### Class-placement questions
+
+When the request is about whether a backend base class belongs in `src/lib`, `src/service`, or the global bean shorthand surface, apply the A / B1 / B2 rule.
+
+- **A**: pure helper base -> `src/lib`
+- **B1**: subclass-only base -> evaluate case by case, often `src/lib`
+- **B2**: runtime-anchor base that still needs container-managed or selector/class-token behavior but should not be a global bean -> prefer `src/service` with `@Service()`
+
+For these requests:
+
+- put the durable operational explanation in `cabloy-docs/`
+- put rationale and invariants in `.docs-internal/`
+- keep `CLAUDE.md` short and behavioral
+- do not treat `@Service()` as a business-layer naming decision only; for B2 it is a runtime-anchor placement choice
+
+### Service underscore files
+
+When a backend base class should move into `src/service`, do not treat the file name as a cosmetic choice.
+
+Prefer `src/service/*_.ts` when the class:
+
+- should remain container-managed
+- mainly acts as a runtime-anchor base, selector anchor, or class-token contract
+- should not participate in the general full-name registration surface
+- may need to keep meaningful `@Virtual()` semantics
+
+Prefer a normal `src/service/*.ts` file when the service-scene class itself should remain part of the general full-name surface.
+
+Do not apply this mechanically to all concrete beans or all abstract classes. Judge by runtime role and registration surface.
+
+### Bean-scene and global shorthand
+
+Treat `src/bean` as the structural definition of the global shorthand surface.
+
+For these requests:
+
+- do not treat `@Virtual()` as a reason to exclude a bean-scene class from `IBeanRecordGlobal`
+- if a class in `src/bean` should not be global shorthand, re-evaluate placement first
+- prefer B1/B2 relocation over metadata exceptions or manual `IBeanRecordGlobal` patching
+- use `IBeanRecordGlobal` as the static authoring-surface registry for global shorthand, not as a full runtime-container inventory
+
+### Global bean lookup workflow
+
+When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, prefer this lookup sequence:
+
+1. check `IBeanRecordGlobal` in the relevant module `src/.metadata/index.ts`
+2. map the shorthand name to the generated bean type
+3. jump from the generated type to the source file in `src/bean`
+4. only if the shorthand is not found, re-evaluate whether the target is actually a general full-name bean, a service-scene runtime-anchor, or a lib/helper class
+
+Use `IBeanRecordGeneral` for general full-name beans and `src/service` or service metadata for runtime-anchor/service-scene lookup. Do not treat `IBeanRecordGlobal` as a full container inventory.
+
+## Step 6: Apply edition-aware branching
+
+When the task is frontend-sensitive or examples differ between editions, branch explicitly.
+
+### Cabloy Basic
+
+Bias toward:
+
+- current public monorepo source
+- public docs examples
+- the Basic repo marker
+- current Basic frontend flavors and module layout
+
+### Cabloy Start
+
+Bias toward:
+
+- the Start repo marker
+- Vuetify-sensitive examples
+- Start-specific frontend flavor names
+- Start-specific modules and private-value repo structure
+
+Do not silently reuse Basic examples when Start-specific assumptions matter.
+
+## Step 7: Verification
+
+Always finish with a verification plan that matches the work.
+
+### For docs or AI-asset changes
+
+Verify:
+
+- referenced paths exist
+- command names still exist
+- public docs, internal docs, and rules tell a consistent story
+- edition-specific notes point to the right repo assumptions
+
+### For backend/frontend workflow changes
+
+Prefer the narrowest useful checks first, then broader checks when needed.
+
+Typical shared checks include:
+
+- root scripts such as `npm run tsc`, `npm run test`, `npm run build`
+- command help or discovery output from `npm run vona` / `npm run zova`
+- targeted build/dev/typecheck flows for the affected side
+
+## Response pattern
+
+When you use this skill, structure the response around these points when helpful:
+
+1. detected edition
+2. detected task layer
+3. recommended CLI or repo entrypoint
+4. files or directories likely involved
+5. verification steps
+
+Keep the response practical. The value of this skill is not extra prose. The value is choosing the right Cabloy workflow quickly and accurately.

package/.claude/skills/cabloy-workflow/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "cabloy-workflow",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I am in the cabloy-basic repo and want to add a new backend bean plus the related frontend page for an admin workflow. Please tell me the right Cabloy workflow and what command families I should inspect first.",
+      "expected_output": "Detects Cabloy Basic, classifies the work as cross-stack, recommends root package.json plus Vona/Zova CLI families instead of manual scaffolding, and mentions verification.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "We are working in cabloy-start and I need to create a new page with Vuetify-specific assumptions. Which repo checks should Claude do before recommending code changes?",
+      "expected_output": "Detects Cabloy Start, highlights the edition marker, treats the task as frontend-sensitive, and avoids reusing Cabloy Basic assumptions blindly.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Please help me decide whether this new AI guidance belongs in public docs, .docs-internal, CLAUDE.md, or a skill. The guidance is about when to use npm run zova instead of hand-written scaffolding.",
+      "expected_output": "Routes the request to the right knowledge homes, prefers public docs plus Claude rules/skills as appropriate, and reinforces the CLI-first principle.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I found a Cabloy-like repo without __CABLOY_BASIC__ or __CABLOY_START__. Before I scaffold a frontend page, what should Claude verify so it does not assume the wrong edition?",
+      "expected_output": "Does not force an edition, inspects the owning package scripts and nearby repo structure, and asks before making a strong edition-specific assumption.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I want to update the public guidance for Cabloy contributors about using CLI generators first, but I also think Claude should follow the same rule automatically. Where should each part of that knowledge live?",
+      "expected_output": "Splits the guidance across public docs and Claude rules/skills appropriately, keeping maintainer rationale out of public docs unless needed.",
+      "files": []
+    }
+  ]
+}