cabloy 5.1.50 → 5.1.52

package/cabloy-docs/editions/cabloy-start.md

@@ -0,0 +1,55 @@
+# Cabloy Start
+
+Cabloy Start is the private commercial edition. It is a sibling private repository that shares the Cabloy fullstack direction while intentionally differing from Cabloy Basic.
+
+## Repository marker
+
+The Cabloy Start root contains:
+
+- `__CABLOY_START__`
+
+Use that marker before choosing examples, UI assumptions, or automation behavior.
+
+## Typical role
+
+Use Cabloy Start as the edition-aware target when work depends on:
+
+- direct use of the licensed private repository source
+- Vuetify-specific frontend workflows
+- Cabloy Start flavor names in frontend scripts
+- modules that exist in the private Start repository but not in Basic
+- licensed private-repo structure and Start-specific project composition
+- Start-specific SSR site baselines and project assets
+
+## Get access and initialize
+
+Cabloy Start is the private commercial edition. It does not use the default `npm create cabloy` project route.
+
+To use Cabloy Start:
+
+1. purchase a license and obtain repository access
+2. clone the private repository source directly
+3. run the edition initialization flow in the cloned project
+
+Access surfaces:
+
+- Purchase page: `https://cabloy.com/module/cabloy-start`
+- Repository: `https://github.com/cabloy/cabloy-start`
+
+Clone the repository:
+
+```bash
+git clone git@github.com:cabloy/cabloy-start.git
+```
+
+After cloning, run:
+
+```bash
+npm run init
+```
+
+This initializes the project and installs dependencies.
+
+## Relationship to this docs site
+
+This unified docs site treats Cabloy Start as a supported edition, not as a clone of Cabloy Basic. Shared architecture should remain shared, but any Start-specific script, module path, or UI workflow must be labeled explicitly.

package/cabloy-docs/editions/choosing-between-basic-and-start.md

@@ -0,0 +1,84 @@
+# Choosing Between Cabloy Basic and Cabloy Start
+
+This guide helps you choose the right Cabloy edition before you start a new project, adopt a frontend UI strategy, or prepare AI workflow guidance.
+
+## Short answer
+
+Choose **Cabloy Basic** when you want the public framework/reference edition, the default `npm create cabloy` project route, and a faster path for open, community-oriented, or small-to-medium system development.
+
+Choose **Cabloy Start** when you want the private commercial edition, purchase-based access to the licensed private repository source, and a stronger baseline for more complex business systems built around the Start-specific suites, SSR sites, project assets, and Vuetify UI layer.
+
+## What stays the same in both editions
+
+Both editions share the same Cabloy fullstack core:
+
+- **Vona** as the backend framework
+- **Zova** as the frontend framework
+- suite-based modular architecture
+- CLI-first workflows
+- shared frontend engineering direction built around Vue, Vite, Quasar tooling, and related libraries
+
+So the decision is not about choosing two unrelated products. It is about choosing the edition baseline that fits your delivery goals best.
+
+## Choose Cabloy Basic when
+
+Cabloy Basic is usually the better fit when you want:
+
+- the public framework/reference edition
+- the default project route created by `npm create cabloy`
+- open-source visibility and community-friendly workflows
+- public examples and docs that match your repo directly
+- a UI layer aligned with DaisyUI + Tailwind CSS
+- a faster path for small-to-medium system development
+
+## Choose Cabloy Start when
+
+Cabloy Start is usually the better fit when you want:
+
+- the private commercial edition
+- purchase-based access to the licensed private repository source
+- direct cloning of the Start repository after authorization
+- Start-specific suites, flavors, SSR site baselines, and project assets
+- a UI layer aligned with Vuetify
+- a stronger starting point for more complex business systems
+- edition-specific rules, skills, and docs optimized for the Start repo assumptions
+
+## The most practical decision factors
+
+### Project creation path
+
+- **Cabloy Basic**: create the project with `npm create cabloy`
+- **Cabloy Start**: purchase access, clone the licensed private repository source directly, then run `npm run init`
+
+### UI strategy
+
+- **Cabloy Basic**: DaisyUI + Tailwind CSS
+- **Cabloy Start**: Vuetify
+
+### Repo and asset model
+
+- **Cabloy Basic**: public repository and public reference materials
+- **Cabloy Start**: private repository with Start-specific suites, SSR sites, and project assets
+
+### AI workflow assumptions
+
+- **Cabloy Basic**: use Basic-specific examples, flavors, modules, and UI assumptions
+- **Cabloy Start**: use Start-specific examples, flavors, modules, SSR site baselines, and UI assumptions
+
+This is why edition detection matters so much for AI vibe coding.
+
+## A simple recommendation rule
+
+Use this rule when you need a fast decision:
+
+1. If you want the public, default, `npm create cabloy` path, choose **Cabloy Basic**.
+2. If you want the licensed private repo with Start-specific assets, a Vuetify-based business-system baseline, and a clone-plus-`npm run init` onboarding path, choose **Cabloy Start**.
+3. If AI workflow accuracy matters for UI generation, SSR site assumptions, or flavor-specific commands, confirm the edition before writing prompts, rules, skills, or docs.
+
+## Read together with
+
+- [Editions Overview](/editions/overview)
+- [Cabloy Basic](/editions/cabloy-basic)
+- [Cabloy Start](/editions/cabloy-start)
+- [Edition Detection](/editions/detection)
+- [Fullstack Quickstart](/fullstack/quickstart)

package/cabloy-docs/editions/detection.md

@@ -0,0 +1,31 @@
+# Edition Detection
+
+Edition detection is a first-class requirement for documentation, rules, and skills.
+
+## Repository markers
+
+Use these root markers:
+
+- `__CABLOY_BASIC__` → Cabloy Basic
+- `__CABLOY_START__` → Cabloy Start
+
+## Why this matters
+
+The two editions share many concepts but differ in important operational details, especially around:
+
+- frontend UI library assumptions
+- flavor-specific frontend scripts
+- module availability
+- value-add project content in the private Start repository
+
+If an agent skips edition detection, it may generate the wrong instructions, recommend the wrong module, or use the wrong UI stack.
+
+## Recommended rule for skills and repo guidance
+
+Before suggesting a cross-stack implementation path:
+
+1. check the repository marker
+2. verify the relevant root scripts or package scripts
+3. only then choose the edition-specific example or workflow branch
+
+When neither marker is present, fall back to code inspection and ask the user before making a strong edition-specific assumption.

package/cabloy-docs/editions/overview.md

@@ -0,0 +1,107 @@
+# Editions Overview
+
+Cabloy currently supports two related but distinct editions:
+
+- **Cabloy Basic**
+- **Cabloy Start**
+
+They share one Cabloy fullstack architecture, but they are distributed, composed, and optimized differently.
+
+If you need a recommendation path, start with [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start).
+
+## Shared fullstack core
+
+Both editions are built around the same core direction:
+
+- **Vona** as the backend framework
+- **Zova** as the frontend framework
+- suite-based modules across the stack
+- root-level `npm run vona` and `npm run zova` entrypoints
+- CLI-backed workflows for generation, refactoring, metadata, and verification
+
+This means the editions are related fullstack baselines, not unrelated products.
+
+## What "Basic" means
+
+Cabloy Basic is the public framework/reference edition.
+
+- this public repository is marked with `__CABLOY_BASIC__`
+- projects created with `npm create cabloy` follow the Cabloy Basic route
+- the public docs and examples in this repo use Cabloy Basic as the default baseline
+
+Cabloy Basic is the open-source community edition and is optimized for public reference, learning, and fast development workflows.
+
+## What "Start" means
+
+Cabloy Start is the private commercial edition.
+
+- the private repository is marked with `__CABLOY_START__`
+- users first purchase a license and obtain repository access, then clone the private repository source directly
+- after cloning, the project is initialized through the Start edition workflow
+- Start provides its own suites, flavors, SSR sites, and project assets for that edition
+
+Cabloy Start is optimized as a commercial baseline for more complex business systems while staying on the same Cabloy fullstack direction.
+
+## Architecture layering
+
+Most of the frontend engineering layer is shared, while the edition-specific UI layer differs.
+
+### Shared frontend engineering layer
+
+Across editions, Zova uses the same frontend framework direction and engineering tooling, including:
+
+- Vue
+- Vite
+- Quasar tooling such as `quasar dev` and `quasar build`
+- TanStack libraries where applicable
+
+Here, Quasar is used for engineering tooling rather than as the edition UI component library.
+
+### Edition-specific UI layer
+
+The UI component strategy diverges by edition:
+
+- **Cabloy Basic**: DaisyUI + Tailwind CSS
+- **Cabloy Start**: Vuetify
+
+This difference affects not only UI code, but also module composition, frontend flavor assumptions, SSR site baselines, examples, and AI workflow guidance.
+
+## Edition-specific assets
+
+The editions intentionally diverge in several surfaces:
+
+- UI layer assumptions
+- frontend flavor names
+- suite and module composition
+- admin/web SSR site baselines
+- licensed private-repo structure and Start-specific project assets
+- rules, skills, and docs used for AI vibe coding
+
+For example:
+
+- **Cabloy Basic** provides the `cabloy-basic` suites and the `cabloyBasicAdmin` / `cabloyBasicWeb` Zova flavors
+- **Cabloy Start** provides the `cabloy-start` suites and the `cabloyStartAdmin` / `cabloyStartWeb` Zova flavors
+
+## Why the repo markers matter
+
+The edition markers are not just labels for humans.
+
+`__CABLOY_BASIC__` and `__CABLOY_START__` help tools, docs, and AI workflows choose the correct assumptions for:
+
+- UI component usage
+- flavor selection
+- module availability
+- SSR site expectations
+- rules, skills, and verification guidance
+
+This is why the two editions should be identified explicitly instead of being treated as interchangeable.
+
+## Documentation rule
+
+Write shared explanations once. Split or annotate only when a workflow changes because of:
+
+- UI library assumptions
+- frontend flavor names
+- different modules or assets
+- distribution and authorization model
+- edition-specific scripts, generated outputs, or AI workflow guidance

package/cabloy-docs/frontend/api-guide.md

@@ -0,0 +1,93 @@
+# API Guide
+
+This guide explains how `$api` works in Zova within the Cabloy monorepo.
+
+## What `$api` is for
+
+Zova provides business-oriented API services on top of lower-level request access.
+
+That means frontend code does not need to scatter raw request details everywhere. Instead, API calls can be encapsulated into named services that match business intent.
+
+## Create an API service
+
+Example: create an API service named `menu` in module `demo-student`.
+
+```bash
+npm run zova :create:bean api menu -- --module=demo-student
+```
+
+## API definition
+
+Representative pattern:
+
+```typescript
+export interface ApiMenuRetrieveMenusResult {
+  title: string;
+  link: string;
+}
+
+@Api()
+export class ApiMenu extends BeanApiBase {
+  retrieveMenus() {
+    return this.$fetch.get<any, ApiMenuRetrieveMenusResult>('/home/base/menu/');
+  }
+}
+```
+
+This shows the intended layering clearly:
+
+- `$fetch` handles the lower-level request
+- the API service exposes a business-oriented method such as `retrieveMenus()`
+
+API is also one of the core module-scope resource categories; see [Module Scope](/frontend/module-scope).
+
+## Using the API through module scope
+
+Typical pattern:
+
+```typescript
+class ControllerTest {
+  async retrieveMenus() {
+    const menus = await this.scope.api.menu.retrieveMenus();
+  }
+}
+```
+
+## Cross-module API access
+
+Cross-module usage is also supported through scope injection.
+
+Representative pattern:
+
+```typescript
+@UseScope()
+$$scopeDemoStudent: ScopeModuleDemoStudent;
+
+const menus = await this.$$scopeDemoStudent.api.menu.retrieveMenus();
+```
+
+## Built-in `$api` access
+
+The framework also supports accessing certain API services through `this.$api` on bean instances.
+
+Representative pattern:
+
+```typescript
+const menus = await this.$api.homeBaseMenu.retrieveMenus({
+  params: { publicPath: '' },
+});
+```
+
+## Implementation checks for frontend data-access changes
+
+When adding frontend data access, avoid jumping straight from UI code to ad hoc request logic.
+
+A better default is:
+
+1. decide whether the request belongs in a named API service
+2. create or reuse that API service
+3. let pages, components, or models consume the API service instead of duplicating request details
+
+That keeps the frontend code more business-oriented and easier to evolve.
+
+When the backend contract is not ready yet, a temporary frontend-side mock route may be the right bridge; see [Mock Guide](/frontend/mock-guide).

package/cabloy-docs/frontend/api-schema-guide.md

@@ -0,0 +1,43 @@
+# API Schema Guide
+
+This page expands the legacy `$apiSchema` placeholder into a practical guidance page for the new docs site.
+
+## What `$apiSchema` represents
+
+`$apiSchema` is the schema-oriented layer of the server-data model.
+
+While `$api` and generated SDKs focus on calling backend operations, `$apiSchema` focuses on the API metadata itself.
+
+That matters when frontend behavior needs to be driven by schema, not just by returned values.
+
+## Why schema access matters
+
+In the Cabloy/Zova model, schema metadata can support higher-level frontend behavior such as:
+
+- validation
+- automatic form rendering
+- automatic field behavior
+- metadata-driven UI logic
+
+This is one reason the server-data thread in Zova is more powerful than a plain request library.
+
+## How to think about `$apiSchema`
+
+Use `$apiSchema` when the frontend needs to inspect what the backend contract says, not just call the backend endpoint.
+
+That usually means the problem is shifting from “fetch data” to “use metadata to drive behavior.”
+
+## Read together with
+
+Use this page together with:
+
+- [Server Data](/frontend/server-data)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [SDK Guide](/frontend/sdk-guide)
+
+## Implementation checks for schema-driven UI changes
+
+When asked to build dynamic forms, metadata-driven UI, or schema-aware validation, consider whether the right source is `$apiSchema` rather than hand-authored frontend-only field definitions.
+
+That keeps the frontend closer to backend truth and reduces duplicate configuration.

package/cabloy-docs/frontend/app-startup-guide.md

@@ -0,0 +1,185 @@
+# App Startup Guide
+
+## Why app startup matters
+
+In Zova, application startup is a structured lifecycle rather than a single opaque bootstrap step.
+
+That matters because routing, guards, business initialization, and extension hooks often need to run at different startup phases.
+
+## App startup vs system startup
+
+App startup is not the same as system startup.
+
+In SSR scenarios especially, app startup can be request-scoped, while system startup is not.
+
+This guide focuses on the application lifecycle after the lower-level system wiring is already in place. For system-level lifecycle hooks such as route registration and config loading, see [System Startup Guide](/frontend/system-startup-guide).
+
+## App startup timings
+
+Zova provides three main app startup timings:
+
+- `appInitialize`
+- `appInitialized`
+- `appReady`
+
+These timings allow business modules to run initialization logic at the earliest appropriate stage.
+
+## App shutdown timing
+
+App shutdown is represented by:
+
+- `appClose`
+
+## Module load timings
+
+The app lifecycle also intersects with module loading:
+
+- `moduleLoading`
+- `moduleLoaded`
+
+These allow module-aware logic to participate before or after the app becomes fully ready.
+
+## Hook response scenarios
+
+Zova supports several implementation locations for these hooks:
+
+- **Module Main** in a module-local main file
+- **Module Monkey** in a module-local monkey file
+- **App Monkey** in the project frontend config area
+
+This makes startup behavior extensible at both module and project levels.
+
+## Hook interface model
+
+Different hooks correspond to different interfaces depending on where they are implemented.
+
+The important architectural point is not the exact interface matrix alone, but that startup behavior is typed and structured rather than improvised.
+
+A compact mental model is:
+
+- **Module Main** handles a module’s own loading lifecycle
+- **Module Monkey** lets a module participate in app-wide hook timings
+- **App Monkey** lets the project frontend config layer participate in the same hook system
+
+## Module Main
+
+A module can provide its own main lifecycle entrypoints.
+
+Representative creation command:
+
+```bash
+npm run zova :init:main demo-student
+```
+
+Representative pattern:
+
+```typescript
+export class Main extends BeanSimple implements IModuleMain {
+  async moduleLoading() {}
+  async moduleLoaded() {}
+}
+```
+
+## Module Monkey
+
+A module can also provide broader app hook behavior through a monkey entry.
+
+Representative creation command:
+
+```bash
+npm run zova :init:monkey demo-student
+```
+
+Representative pattern:
+
+```typescript
+export class Monkey
+  extends BeanSimple
+  implements
+    IMonkeyModule,
+    IMonkeyAppInitialize,
+    IMonkeyAppInitialized,
+    IMonkeyAppReady,
+    IMonkeyAppClose
+{
+  async moduleLoading(_module: IModule) {}
+  async moduleLoaded(_module: IModule) {}
+  async appInitialize() {}
+  async appInitialized() {}
+  async appReady() {}
+  async appClose() {}
+}
+```
+
+## App Monkey
+
+Project-level app lifecycle customization can be placed in the frontend config area.
+
+This is useful when startup behavior belongs to the application as a whole rather than to one module.
+
+Representative creation command:
+
+```bash
+npm run zova :init:appMonkey
+```
+
+Representative file location:
+
+```text
+src/front/config/monkey.ts
+```
+
+## Practical interpretation of the phases
+
+A useful rule of thumb is:
+
+- use the earliest timing that still satisfies the need
+- reserve later timings for behavior that depends on earlier framework or module setup already being finished
+
+That keeps initialization extensible without creating unnecessary ordering coupling.
+
+A representative lifecycle interpretation is:
+
+- `appInitialize` for the earliest app-level service setup
+- `appInitialized` when other modules should be able to react to the initialized state
+- `appReady` for behavior that depends on the app becoming operational, such as final router-facing readiness
+- `appClose` for teardown and listener cleanup
+
+## Relationship to routing and guards
+
+This page is the second half of the startup story: once system startup has registered routes and loaded config, app startup makes router services, guards, and first-screen navigation operational.
+
+Startup timing is closely related to frontend routing and guards, because route services and route-guard behavior often need to be initialized before the app is considered ready.
+
+The legacy startup docs explicitly used the router module as the core example:
+
+- `appInitialize` as an early route-guard service setup point
+- `appInitialized` as the point where route-guard events can begin involving other business modules
+- `appReady` as the point where Vue Router can be injected and initial navigation can run
+- `appClose` as the teardown point for route-guard listeners
+
+Read this guide together with [Navigation Guards Guide](/frontend/navigation-guards-guide) when route lifecycle is involved.
+
+A practical reading sequence is:
+
+1. [System Startup Guide](/frontend/system-startup-guide)
+2. this page for router/guard readiness
+3. [Page Route Guide](/frontend/page-route-guide)
+4. [Navigation Guards Guide](/frontend/navigation-guards-guide)
+
+## Relationship to environment/config selection
+
+The chosen scripts, mode, appMode, and flavor determine which config and env values are active while startup hooks run.
+
+Read this guide together with [Environment and Config Guide](/frontend/environment-config-guide).
+
+## Implementation checks for app-startup changes
+
+When editing frontend startup behavior, ask:
+
+1. does this logic belong to app startup or system startup?
+2. what is the earliest safe hook timing for this behavior?
+3. should the logic live in module main, module monkey, or app monkey?
+4. does the behavior depend on routing, SSR, or environment-specific config already being ready?
+
+That helps AI place initialization logic correctly instead of pushing everything into one late-stage bootstrap step.

package/cabloy-docs/frontend/cli.md

@@ -0,0 +1,78 @@
+# Frontend CLI
+
+This guide explains how to use the Zova CLI in the Cabloy monorepo.
+
+## Why the CLI matters
+
+Zova provides a large number of CLI commands for generating code skeletons and running frontend workflows.
+
+For AI-assisted development, the CLI should be the default starting point whenever a generator or refactor command already exists.
+
+## Example
+
+Create a `component` named `test` in module `demo-student`:
+
+```bash
+npm run zova :create:component test -- --module=demo-student
+```
+
+## Command discovery pattern
+
+Zova commands follow a consistent discovery model.
+
+### 1. List all command groups and commands
+
+```bash
+npm run zova :
+```
+
+### 2. List commands for a specific group
+
+```bash
+npm run zova :create
+```
+
+### 3. Inspect help for one command
+
+```bash
+npm run zova :create:component --help
+```
+
+## High-value command families
+
+From the current source tree, the most useful Zova command families for day-to-day development are:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `refactor:*`
+- `tools:*`
+- `openapi:*`
+
+Typical use cases include:
+
+- scaffold suites, modules, pages, components, mocks, and beans
+- initialize frontend config, locale, constants, assets, and typing helpers
+- run focused refactors such as page query, page params, component props, generic component updates, and related migrations
+- generate OpenAPI-related output
+- refresh metadata and dependency-related output
+
+## VS Code menus and the CLI
+
+In practice, Zova workflows can be reached from two surfaces:
+
+- VS Code menus for discovery and ergonomics
+- the CLI for explicit, scriptable command execution
+
+A practical rule is:
+
+- use menus when you want to discover the available workflow quickly in the editor
+- use the CLI when you want reproducible automation, explicit command history, or terminal-first documentation
+
+These are not competing workflow systems. They are two entrypoints to the same underlying Zova command families.
+
+## Practical workflow rule
+
+When creating or refactoring frontend code, inspect `npm run zova :` or the relevant command family first, prefer the matching generator or refactor command, inspect the generated or transformed output, and only then make minimal follow-up edits.
+
+This keeps frontend work aligned with Zova conventions and avoids avoidable manual scaffolding.