cabloy 5.1.51 → 5.1.52

package/cabloy-docs/ai/virtual-decorator-guidance.md

@@ -0,0 +1,206 @@
+# Virtual Decorator Guidance
+
+Use this page when deciding whether a backend class should use `@Virtual()`, or when AI needs to understand what `@Virtual()` changes in Vona bean behavior.
+
+The goal is to preserve real runtime semantics, keep class placement intentional, and prevent `@Virtual()` from being reused as a shorthand or registration filter.
+
+## Short definition
+
+`@Virtual()` marks a container-managed class as a virtual inherited runtime node.
+
+Its core effect is to make bean registration inherit `moduleBelong` from the parent bean chain instead of treating the current class as a new independent runtime ownership center.
+
+## What `@Virtual()` does not mean
+
+`@Virtual()` does **not** mean any of the following:
+
+- suppress bean registration
+- remove a bean-scene class from `IBeanRecordGlobal`
+- act as a shorthand-registration filter
+- compensate for incorrect class placement
+- mean only that a class is abstract or internal
+
+If a class should not appear on the global shorthand surface, fix placement instead.
+
+For related guidance, also read:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+
+## Runtime effect
+
+`@Virtual()` matters at registration time and then keeps affecting runtime scope resolution.
+
+### 1. Decorator stage
+
+The decorator writes virtual metadata on the class.
+
+Conceptually:
+
+```text
+@Virtual()
+ -> metadata(SymbolDecoratorVirtual = true)
+```
+
+### 2. Registration stage
+
+When the bean is registered, Vona reads that metadata and computes `moduleBelong`.
+
+- non-virtual bean -> `moduleBelong` stays equal to the current module
+- virtual bean -> `moduleBelong` is inherited from the nearest parent bean that already has one
+
+Conceptually:
+
+```text
+@Virtual()
+ -> addBean()
+ -> _parseModuleBelong()
+ -> inherited moduleBelong
+```
+
+### 3. Runtime stage
+
+Bean instances then resolve runtime scope resources from that inherited `moduleBelong`.
+
+This directly affects access to:
+
+- `this.scope`
+- `this.module`
+- `this.config`
+- `this.constant`
+- `this.error`
+- `this.locale`
+- `this.util`
+- `this.model`
+- `this.entity`
+- module meta and scene resources
+
+Short version:
+
+> `@Virtual()` changes runtime ownership resolution, not registration existence.
+
+## Relationship to `@Bean()` and `@Service()`
+
+These decorators solve different problems.
+
+- `@Bean()` / `@Service()` / `@Controller()` decide which scene the class registers into
+- `@Virtual()` decides how runtime ownership is resolved
+
+They are orthogonal.
+
+Examples:
+
+- `@Service() + @Virtual()`
+  - service-scene bean
+  - runtime ownership follows the parent bean chain
+- `@Bean() + @Virtual()`
+  - bean-scene bean
+  - still a virtual bridge node rather than a new independent ownership center
+
+## When to use `@Virtual()`
+
+Use `@Virtual()` when a class is still container-managed, but is not intended to become a new independent runtime ownership center.
+
+Typical cases:
+
+### 1. Runtime-anchor bases
+
+These classes still need bean lifecycle, class-token lookup, selector-aware behavior, or framework-managed context.
+
+Representative examples:
+
+- `vona/src/suite-vendor/a-vona/modules/a-orm/src/service/databaseDialectBase_.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-cache/src/service/cacheMemBase_.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-cache/src/service/cacheRedisBase_.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-summer/src/service/summerCacheBase_.ts`
+
+### 2. Bean facade or bridge nodes
+
+These classes remain intentionally visible on the bean-scene shorthand surface, but still behave as inherited bridge nodes rather than independent runtime ownership centers.
+
+Representative example:
+
+- `vona/src/suite-vendor/a-vona/modules/a-orm/src/bean/bean.model.ts`
+
+### 3. Compatibility or variant nodes
+
+These classes extend an existing bean hierarchy and should keep runtime ownership aligned with the parent chain.
+
+Representative example:
+
+- `vona/src/suite-vendor/a-vona/modules/a-ormdialect/src/bean/databaseDialect.mysql3.ts`
+
+## When not to use `@Virtual()`
+
+Do **not** use `@Virtual()` for these cases.
+
+### 1. Independent business services
+
+If a class is the real business owner of its own runtime boundary, it should usually keep its own `moduleBelong` and should not be virtual.
+
+### 2. Misplaced bean-scene classes
+
+Do not keep a class in `src/bean` and try to hide it with `@Virtual()`.
+
+If it should not be a global shorthand bean, move it instead:
+
+- pure helper or subclass-only base -> `src/lib`
+- runtime-anchor base -> `src/service`, often `src/service/*_.ts`
+
+### 3. Pure helpers or superclass convenience classes
+
+If a class does not need container-managed behavior, it usually belongs in `src/lib` and should not use `@Virtual()`.
+
+## Decision table
+
+| Scenario | Use `@Virtual()` | Recommended placement | Reason |
+| --- | --- | --- | --- |
+| independent business service | No | `src/service` | it should own its own runtime resource boundary |
+| runtime-anchor base with container behavior | Yes | `src/service` or `src/service/*_.ts` | it is container-managed but belongs logically to the parent bean system |
+| bean-scene facade that intentionally stays on shorthand surface | Yes, if it is a bridge node | `src/bean` | it participates in shorthand lookup but is not a new ownership center |
+| compatibility / dialect / variant node built on a parent bean | Yes | same scene as the concrete variant type | runtime ownership should inherit from the parent chain |
+| pure helper or superclass convenience class | No | `src/lib` | no bean ownership semantics are needed |
+| class kept in `src/bean` only to expose shortcut lookup | Usually no | re-evaluate placement | `@Virtual()` is not a shorthand filter |
+| misplaced bean-scene class that should not be globally visible | No | move to `src/lib` or `src/service` | fix placement, not metadata |
+
+## Worked examples
+
+### Example: runtime-anchor dialect base
+
+`databaseDialectBase_.ts` is virtual because it remains container-managed and is used as the runtime base for dialect resolution, but it is not meant to become a separate public shorthand ownership center.
+
+### Example: bean-scene bridge node
+
+`bean.model.ts` is still in bean-scene because it intentionally participates in the global shorthand surface, but `@Virtual()` preserves its bridge-node semantics.
+
+### Example: derived dialect variant
+
+`databaseDialect.mysql3.ts` combines `$Class.extend(...)` and `@Virtual()` because those two features solve different problems:
+
+- `$Class.extend(...)` expresses a framework-managed derived-class relationship
+- `@Virtual()` preserves inherited runtime ownership semantics
+
+## Quick checklist
+
+Ask these questions in order:
+
+1. Does the class still need container-managed behavior?
+   - if no, do not use `@Virtual()`
+2. Is it a runtime extension of a parent bean system rather than a new business ownership center?
+   - if yes, `@Virtual()` may be appropriate
+3. Are you using `@Virtual()` only to hide the class from shorthand or metadata surfaces?
+   - if yes, do not use it; fix placement instead
+4. Will inherited `moduleBelong` produce the correct `scope` / `config` / `model` / `entity` behavior at runtime?
+   - if no, do not use `@Virtual()`
+
+## Related guidance
+
+Read these pages together:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+- [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)
+
+For maintainer-level rationale, also read:
+
+- `.docs-internal/architecture/virtual-decorator-runtime-semantics.md`

package/cabloy-docs/backend/introduction.md

@@ -1,8 +1,8 @@
 # Backend (Vona)
 
-This page is the backend hub for contributors who are documenting, designing, or extending backend work in the Cabloy repository.
+This page is the backend hub for Cabloy users, contributors, and AI vibe coding workflows that need the backend side of the framework.
 
-Vona is the backend half of the Cabloy fullstack architecture.
+Vona is the backend half of Cabloy’s one-framework-system fullstack architecture.
 
 ## What Vona is responsible for
 

package/cabloy-docs/backend/logger-guide.md

@@ -24,7 +24,7 @@ By default, the log directory changes by runtime environment.
 Representative defaults are:
 
 - test/development → `{project path}/.app/logs`
-- production → `{home}/vona/{project name}/logs`
+- production → `{home}/.vona/{project name}/logs`
 
 This can be configured through app config or environment variables such as `LOGGER_DIR`.
 

package/cabloy-docs/backend/quickstart.md

@@ -86,10 +86,10 @@ Legacy Vona docs described creating projects from templates such as `cabloy-basi
 
 That history still matters, because it explains why the Cabloy ecosystem now supports two editions:
 
-- **Cabloy Basic**: public reference repo with DaisyUI + TailwindCSS oriented frontend modules
-- **Cabloy Start**: sibling private repo with Vuetify-oriented frontend modules and different value-add composition
+- **Cabloy Basic**: the public framework/reference edition, including the project route created by `npm create cabloy`, with a shared frontend engineering layer and a DaisyUI + Tailwind CSS oriented UI layer in the current public examples
+- **Cabloy Start**: the private commercial edition, accessed by cloning the licensed private repository source, with Vuetify-oriented frontend modules plus Start-specific SSR site baselines and project assets
 
-In the current monorepo docs, do not treat these as just template names. Treat them as edition boundaries that affect frontend integration, scripts, and examples.
+In the current monorepo docs, do not treat these as just template names. Treat them as edition boundaries that affect frontend integration, scripts, UI assumptions, and examples.
 
 ## Backend configuration reminder
 

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

@@ -1,6 +1,6 @@
 # Cabloy Basic
 
-Cabloy Basic is the public monorepo you are reading right now.
+Cabloy Basic is the public framework/reference edition you are reading right now.
 
 ## Repository marker
 
@@ -12,14 +12,15 @@ This marker is the quickest safe signal for docs, skills, and rules that need to
 
 ## Typical role
 
-Use Cabloy Basic as the public reference for:
+Use Cabloy Basic as the public reference edition for:
 
 - shared architecture explanations
 - root scripts and monorepo entrypoints
 - Vona and Zova source browsing
 - public CLI-backed workflows
 - public user-facing documentation
+- projects created with `npm create cabloy`
 
 ## Frontend bias
 
-In the current source and docs, Cabloy Basic examples commonly align with a DaisyUI + TailwindCSS-oriented frontend story. That does not mean Zova is limited to that UI stack, but it does mean docs and AI outputs should not accidentally project Vuetify-specific assumptions into Cabloy Basic unless the current source explicitly requires it.
+In the current source and docs, Cabloy Basic examples commonly align with a shared frontend engineering layer built on Zova, Vue, Vite, and Quasar tooling, plus a Basic-specific UI layer built with DaisyUI + Tailwind CSS. That does not mean Zova is limited to that UI stack, but it does mean docs and AI outputs should not accidentally project Vuetify-specific assumptions into Cabloy Basic unless the current source explicitly requires it.

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

@@ -1,6 +1,6 @@
 # Cabloy Start
 
-Cabloy Start is a sibling private repository that shares the Cabloy fullstack direction while intentionally differing from Cabloy Basic.
+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
 
@@ -14,10 +14,41 @@ Use that marker before choosing examples, UI assumptions, or automation behavior
 
 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
-- private value-add project composition
+- 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
 

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/overview.md

@@ -1,44 +1,107 @@
 # Editions Overview
 
-Cabloy currently needs to support two related but distinct repositories:
+Cabloy currently supports two related but distinct editions:
 
 - **Cabloy Basic**
 - **Cabloy Start**
 
-They share the same core architectural direction, but they are not interchangeable.
+They share one Cabloy fullstack architecture, but they are distributed, composed, and optimized differently.
 
-## Shared core
+If you need a recommendation path, start with [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start).
 
-Both editions use the Cabloy fullstack model built around:
+## Shared fullstack core
 
-- Vona as the backend framework
-- Zova as the frontend framework
+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
 
-## Why the editions differ
+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
 
-The editions exist to support different product and distribution goals.
+## Why the repo markers matter
 
-### Cabloy Basic
+The edition markers are not just labels for humans.
 
-- public repository
-- baseline fullstack reference implementation
-- current default examples in this public monorepo
+`__CABLOY_BASIC__` and `__CABLOY_START__` help tools, docs, and AI workflows choose the correct assumptions for:
 
-### Cabloy Start
+- UI component usage
+- flavor selection
+- module availability
+- SSR site expectations
+- rules, skills, and verification guidance
 
-- sibling private repository
-- created from `npm create cabloy`
-- uses a different UI strategy centered on Vuetify
-- contains different Vona/Zova modules and value-add project structure
+This is why the two editions should be identified explicitly instead of being treated as interchangeable.
 
 ## Documentation rule
 
-Write shared explanations once. Only split or annotate when a workflow changes because of:
+Write shared explanations once. Split or annotate only when a workflow changes because of:
 
 - UI library assumptions
 - frontend flavor names
 - different modules or assets
-- private-value product boundaries
-- edition-specific scripts or generated outputs
+- distribution and authorization model
+- edition-specific scripts, generated outputs, or AI workflow guidance

package/cabloy-docs/frontend/foundation.md

@@ -26,8 +26,9 @@ Zova is not tied to one UI library.
 
 That flexibility matters directly for Cabloy’s edition model:
 
-- **Cabloy Basic** currently aligns with DaisyUI + TailwindCSS oriented examples
-- **Cabloy Start** aligns with Vuetify-oriented frontend modules and workflows
+- **Shared frontend engineering layer**: both editions follow the same Zova-centered frontend direction, with Vue, Vite, Quasar tooling, and related libraries
+- **Cabloy Basic UI layer**: current public docs and examples align with DaisyUI + Tailwind CSS
+- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify-oriented frontend modules, workflows, and SSR site baselines
 
 So docs and skills must separate shared Zova principles from edition-specific UI assumptions.
 

package/cabloy-docs/frontend/introduction.md

@@ -1,8 +1,8 @@
 # Frontend (Zova)
 
-This page is the frontend hub for contributors who are documenting, designing, or extending frontend work in the Cabloy repository.
+This page is the frontend hub for Cabloy users, contributors, and AI vibe coding workflows that need the frontend side of the framework.
 
-Zova is the frontend half of the Cabloy fullstack architecture.
+Zova is the frontend half of Cabloy’s one-framework-system fullstack architecture.
 
 ## What Zova is responsible for
 
@@ -26,7 +26,8 @@ For contributor and automation workflows in this repository, prefer this order:
 
 Frontend work is where Cabloy Basic and Cabloy Start differ most clearly.
 
-- **Cabloy Basic** uses a frontend stack centered on DaisyUI and TailwindCSS in the current docs and examples.
-- **Cabloy Start** uses Vuetify and ships different frontend modules as a private value-add project.
+- **Shared frontend engineering layer**: both editions follow the same Zova-centered frontend direction, with Vue, Vite, Quasar tooling, and related libraries.
+- **Cabloy Basic UI layer**: current public docs and examples align with DaisyUI + Tailwind CSS.
+- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify and ships different frontend modules, SSR site baselines, and project assets.
 
 Because of this, automation and docs should always detect the active edition before recommending page-level, component-level, or UI-library-specific work.

package/cabloy-docs/frontend/quickstart.md

@@ -28,8 +28,9 @@ When working in this framework repository, the active edition is **Cabloy Basic*
 That matters because edition choice affects:
 
 - frontend flavor names
-- UI-library assumptions
-- available modules and layouts
+- UI-layer assumptions
+- available modules, layouts, and SSR site baselines
+- project assets and examples
 - which examples in the docs match the current repo directly
 
 Read together with:

package/cabloy-docs/frontend/scripts.md

@@ -66,12 +66,12 @@ cd zova && npm run build:rest:cabloyBasicAdmin
 
 ## Cabloy Start
 
-The sibling `cabloy-start` repository uses Start-specific flavors such as:
+The sibling `cabloy-start` repository is the private commercial edition and uses Start-specific flavors such as:
 
 - `cabloyStartAdmin`
 - `cabloyStartWeb`
 
-Those commands are not driven by the current Basic repo root wrappers, so verify the Start repo’s `package.json` before documenting or automating them.
+Those commands are not driven by the current Basic repo root wrappers, so verify the Start repo’s `package.json`, suites, SSR site baselines, and project assets before documenting or automating them.
 
 ## Workflow guidance