cabloy 5.1.51 → 5.1.53

package/cabloy-docs/fullstack/cli.md

@@ -0,0 +1,118 @@
+# Fullstack CLI
+
+This guide explains the shared CLI workflow for Cabloy in the monorepo.
+
+Use this page to understand the cross-stack mental model first, then go deeper into the backend, frontend, and reference pages as needed.
+
+## Why the fullstack CLI matters
+
+Cabloy treats many common tasks as framework workflows rather than ad hoc manual steps.
+
+That matters across the full stack because:
+
+- Vona and Zova already expose framework-aware generators and tooling
+- the monorepo already exposes shared root scripts for development and verification
+- backend and frontend work stay more consistent when contributors start from the existing command surface instead of inventing manual scaffolding
+
+A practical default is: inspect the CLI first, run the matching workflow if it already exists, then make only the minimal follow-up edits the task actually needs.
+
+## Shared repo entrypoints
+
+In this repository, the two main CLI entrypoints are:
+
+```bash
+npm run vona
+npm run zova
+```
+
+Use them as the shared terminal-first entrypoints for framework-aware workflows.
+
+At the same time, the repo root also exposes shared scripts for broader development tasks such as dev, build, test, and typecheck.
+
+Use this distinction consistently:
+
+- use the CLI when you are discovering commands, generating framework resources, running framework-specific tooling, or inspecting workflow families
+- use root scripts when you are running broader repository workflows such as development, builds, or verification
+
+For the broader Reference landing page, see [Reference Introduction](/reference/introduction). For the compact root-script lookup surface, see [Repo Scripts](/reference/repo-scripts).
+
+## Shared discovery pattern
+
+Vona and Zova follow the same discovery model.
+
+### 1. List command groups and commands
+
+```bash
+npm run vona :
+npm run zova :
+```
+
+### 2. Narrow to a command family
+
+```bash
+npm run vona :create
+npm run zova :create
+```
+
+### 3. Inspect help for one command
+
+```bash
+npm run vona :create:bean --help
+npm run zova :create:component --help
+```
+
+This discovery pattern should be the default contributor workflow before creating files by hand.
+
+## How to choose the right surface
+
+A practical rule is:
+
+- start with `npm run vona` when the task is backend-oriented
+- start with `npm run zova` when the task is frontend-oriented
+- start with root scripts when the task is about repo-wide development, build, or verification
+
+In practice, that usually means:
+
+- **Vona CLI** for backend generation and backend-specific tooling
+- **Zova CLI** for frontend generation, refactors, and frontend-specific tooling
+- **Root scripts** for broader runtime and verification flows
+
+For side-specific depth, see:
+
+- [Backend CLI](/backend/cli)
+- [Frontend CLI](/frontend/cli)
+- [CLI Reference](/reference/cli-reference)
+
+## Scripts, CLI, and VS Code extensions
+
+Use these three surfaces for different jobs:
+
+| Surface            | Best for                                                           | Typical examples                                                                         |
+| ------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Root scripts       | Repo-wide development, build, and verification workflows           | `npm run dev`, `npm run build`, `npm run test`                                           |
+| CLI                | Framework-aware generation, refactors, initialization, and tooling | `npm run vona :create`, `npm run zova :refactor`, `npm run zova :openapi`                |
+| VS Code extensions | In-editor discovery of the same framework workflow families        | Explorer right-click menus for `Create`, `Init`, `Refactor`, `Tools`, and related groups |
+
+## CLI and VS Code extensions
+
+The CLI is the authoritative workflow surface.
+
+The VS Code extensions are the editor-side discovery layer for those same workflows.
+
+A practical rule is:
+
+- use the CLI when you want explicit, scriptable, reproducible execution
+- use VS Code menus when you want faster in-editor discovery of the same workflow families
+
+For the editor-side counterpart, see [VS Code Extensions](/fullstack/vscode-extensions).
+
+## Recommended workflow rule
+
+Before creating or refactoring framework-managed files by hand:
+
+1. inspect the relevant CLI family
+2. run the matching generator, initializer, refactor, or tooling workflow
+3. inspect the generated or transformed result
+4. apply only the minimal manual follow-up edits that are still necessary
+
+This keeps fullstack work aligned with Cabloy conventions and reduces avoidable manual scaffolding.

package/cabloy-docs/fullstack/comparison-with-other-frameworks.md

@@ -0,0 +1,117 @@
+# Comparison with Other Frameworks
+
+This page shows how **Cabloy** differs from several common framework choices, so readers can quickly see where Cabloy stands out as a Node.js fullstack framework system and which strengths come from the fullstack system as a whole versus the backend layer provided by **Vona**.
+
+## What is being compared
+
+Cabloy is a **Node.js fullstack framework system**.
+
+That means the comparison is not only about a backend runtime or only about a frontend stack. It is about how **Vona** on the backend and **Zova** on the frontend stay aligned through shared conventions, shared scripts, SSR-aware delivery modes, and cross-stack generation workflows.
+
+For the broader Cabloy model, start with these pages:
+
+- [Fullstack Introduction](/fullstack/introduction)
+- [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+
+## Comparison lens
+
+The sections below use the same comparison lens each time:
+
+- **System center** — what the framework treats as the main architectural center
+- **Backend model** — how much backend structure and infrastructure the framework provides by default
+- **Frontend and admin model** — how the UI side is expected to evolve
+- **Cross-stack workflow** — how backend/frontend contracts and generation workflows stay aligned
+- **Best fit** — the kind of team or project the framework fits most naturally
+
+## Cabloy vs Next.js
+
+| Perspective              | Cabloy                                                                                         | Next.js                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| System center            | One framework system with Vona on the backend and Zova on the frontend                         | Frontend-centric fullstack framework                                   |
+| Backend model            | Dedicated backend framework with its own runtime, contracts, infrastructure, and CLI workflows | Backend capabilities are typically centered around the web app runtime |
+| Frontend and admin model | Shared conventions across SSR, SPA, Web, and Admin applications                                | Strong fit for React-based web application delivery                    |
+| Cross-stack workflow     | Explicit backend OpenAPI output, frontend SDK generation, and frontend metadata feedback loops | Usually chosen per project or ecosystem tooling                        |
+| Best fit                 | Teams that want a coordinated fullstack system with a stronger dedicated backend layer         | Teams that want a React-centered fullstack web application path        |
+
+Cabloy and Next.js both target fullstack application development, but they organize the stack differently.
+
+Cabloy keeps the backend and frontend as **separate but coordinated framework layers**. That makes it a strong fit when a team wants one framework system with a dedicated backend layer and a dedicated frontend layer, without stitching together unrelated tools by hand.
+
+Representative Cabloy strengths in this comparison include:
+
+- a clear backend/frontend collaboration model rather than a single frontend-centered runtime
+- explicit contract workflows from backend OpenAPI output to frontend SDK generation
+- frontend-generated metadata that can flow back into backend-side tooling
+- shared delivery conventions for SSR, SPA, Web, and Admin applications
+
+If your main goal is a React-centered fullstack web app, Next.js may feel more direct. If your main goal is a **coordinated fullstack framework system** with a stronger backend layer and explicit cross-stack workflows, Cabloy is the better fit.
+
+## Cabloy vs NestJS
+
+| Perspective              | Cabloy                                                                                                | NestJS                                                                                  |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| System center            | Fullstack system                                                                                      | Backend framework                                                                       |
+| Backend model            | Vona provides backend runtime, contracts, infrastructure, and CLI workflows                           | NestJS focuses on backend application structure                                         |
+| Frontend and admin model | Frontend collaboration is built into the broader Cabloy system through Zova and shared docs/workflows | Usually paired with a separate frontend choice                                          |
+| Cross-stack workflow     | Backend contracts can feed frontend SDK generation inside the same framework system                   | Typically assembled from separate backend and frontend tooling choices                  |
+| Best fit                 | Teams that want backend strength inside a shared fullstack system                                     | Teams that want a backend-first framework and will choose the frontend stack separately |
+
+The most important difference here is **scope**.
+
+NestJS is primarily a backend framework. Cabloy is a **fullstack framework system**. So this comparison is not only “backend versus backend.” It is also “backend-first framework” versus “backend + frontend framework system with a shared collaboration model.”
+
+Within Cabloy, the backend-specific capabilities come from **Vona**. That is where backend-oriented strengths such as these belong:
+
+- unified validation and OpenAPI-oriented schema workflows
+- DTO inference and generation workflows
+- built-in multi-tenant, multi-database, and multi-datasource capabilities
+- broader infrastructure features such as queues, broadcast, schedule, and redlock
+- AOP-oriented backend programming capabilities
+
+If a team only needs a backend framework and wants to choose the frontend stack separately, NestJS remains a natural option. If a team wants those backend capabilities to live inside a **shared fullstack system** with Zova, SSR-aware delivery modes, and contract-loop workflows, Cabloy is the better fit.
+
+## Cabloy vs Django Admin
+
+| Perspective              | Cabloy                                                                                                                    | Django Admin                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| System center            | Typed Node.js fullstack framework system                                                                                  | Python server-centered admin framework experience                                        |
+| Backend model            | Dedicated backend runtime and infrastructure through Vona                                                                 | Django backend conventions centered on the admin stack                                   |
+| Frontend and admin model | Modern frontend layer through Zova with SSR, SPA, Web, and Admin delivery modes                                           | Admin experience is centered on server-rendered templates and built-in admin conventions |
+| Cross-stack workflow     | Backend and frontend stay aligned through generated contracts, metadata, and shared workflows                             | The default model is more tightly centered on the server-side admin stack                |
+| Best fit                 | Teams that want rapid admin development in Node.js without giving up typed frontend flexibility and richer UI interaction | Teams that want a fast server-centered admin path in the Python ecosystem                |
+
+This comparison is worth keeping even though the language ecosystems are different.
+
+In the Python ecosystem, **Django Admin** has long been one of the strongest choices for rapidly building CRUD-oriented admin systems. In the Node.js ecosystem, there has historically been no equally established framework that combines rapid admin development, full backend infrastructure, and a modern fullstack architecture in the same way.
+
+Cabloy is designed to fill that gap in the Node.js ecosystem.
+
+That is why this comparison matters: it is not only comparing features, but also explaining Cabloy’s **ecosystem role**. For teams that want Django-Admin-like development speed for admin systems but want to stay in Node.js, Cabloy aims to provide that missing fullstack option.
+
+At the same time, Cabloy does not stop at reproducing the server-centered admin model. With Vona on the backend and Zova on the frontend, Cabloy gives teams:
+
+- a typed modern frontend layer instead of relying only on server-rendered templates
+- richer interaction patterns for Admin and Web applications
+- a smoother path for deeper customization as business systems become more complex
+- a development experience that stays closer to modern Node.js fullstack workflows
+
+So although Django Admin remains a benchmark for rapid admin development, Cabloy aims to offer a stronger long-term fit for teams that want both **rapid CRUD-oriented admin delivery** and a more modern fullstack development and interaction model inside Node.js.
+
+For Cabloy’s frontend/runtime side of this comparison, see:
+
+- [Frontend SSR Overview](/frontend/ssr-overview)
+- [Editions Overview](/editions/overview)
+
+## How to read these comparisons
+
+These comparisons are most useful when your decision depends on questions like:
+
+- do you want one coordinated framework system instead of stitching backend and frontend frameworks together?
+- do you need a stronger dedicated backend layer inside a fullstack architecture?
+- do you want explicit contract-loop workflows between backend and frontend?
+- do you need shared conventions across SSR, SPA, Web, and Admin delivery modes?
+- do you want Django-Admin-like rapid admin development inside the Node.js ecosystem, but with a more modern frontend and interaction model?
+
+If those questions matter, Cabloy’s value is not just one isolated feature. It is the way **Vona**, **Zova**, shared scripts, and cross-stack workflows stay aligned as one framework system.

package/cabloy-docs/fullstack/edition-collaboration-differences.md

@@ -22,10 +22,11 @@ Both editions share the same broad collaboration loop:
 
 The most important differences show up in:
 
-- frontend UI stack assumptions
+- frontend UI layer assumptions
 - frontend flavor names
 - frontend module composition
-- private value-add content in Cabloy Start
+- admin/web SSR site baselines
+- edition-specific private value-add content and project assets in Cabloy Start
 - potentially different generated output paths or integration details
 
 ## Cabloy Basic

package/cabloy-docs/fullstack/introduction.md

@@ -1,6 +1,57 @@
 # Fullstack Introduction
 
-Cabloy is a fullstack framework built around a single source tree where backend and frontend development stay close enough for code sharing, workflow reuse, and AI-assisted implementation.
+Cabloy is a Node.js fullstack framework for AI vibe coding.
+
+Use one fullstack framework instead of stitching together separate backend and frontend stacks.
+
+With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding.
+
+## What Cabloy emphasizes
+
+- **One framework system** — build backend and frontend in one fullstack architecture
+- **Vona + Zova** — use aligned backend and frontend frameworks for code sharing, workflow reuse, and cross-stack consistency
+- **Suite-based modular system** — organize capabilities as suites and modules so services, features, metadata, and tooling evolve in composable units
+- **Multiple delivery modes** — deliver SSR, SPA, Web, and Admin applications with shared conventions across the stack
+- **CLI-first workflows for AI vibe coding** — turn common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding
+- **Monorepo-native development** — keep framework source, docs, and tooling aligned in one monorepo workflow
+
+## How to approach fullstack work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the root `package.json` and shared monorepo scripts first
+2. inspect `npm run vona`, `npm run zova`, and the shared fullstack CLI workflow before inventing custom steps
+3. detect the active edition before making UI-sensitive or flavor-sensitive assumptions
+4. explain shared cross-stack concepts once, then isolate edition-specific notes only where the editions intentionally diverge
+
+## Fullstack reading paths
+
+Use this page as the main fullstack hub, then choose the path that matches your task.
+
+### Getting started path
+
+Start here when you want the shortest route to a working monorepo mental model:
+
+- [Quickstart](/fullstack/quickstart)
+- [CLI](/fullstack/cli)
+- [VS Code Extensions](/fullstack/vscode-extensions)
+
+### Architecture and integration path
+
+Use this path when the task is about how backend and frontend stay aligned inside one framework system:
+
+- [Comparison with Other Frameworks](/fullstack/comparison-with-other-frameworks)
+- [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+
+### Edition-aware collaboration path
+
+Use this path when the task depends on edition boundaries, UI assumptions, or cross-repo delivery differences:
+
+- [Edition Collaboration Differences](/fullstack/edition-collaboration-differences)
+- [Editions Overview](/editions/overview)
+- [Choosing Basic vs Start](/editions/choosing-between-basic-and-start)
 
 ## Shared architecture
 
@@ -8,62 +59,61 @@ Cabloy is a fullstack framework built around a single source tree where backend
 - **Zova** provides the frontend framework capabilities.
 - The root repository coordinates the two through shared scripts, shared terminology, and a shared release story.
 
-In the current monorepo root, the main command entrypoints are:
+This combination keeps backend and frontend development close enough for code sharing, workflow reuse, and AI vibe coding workflows.
 
-- `npm run vona`
-- `npm run zova`
-- `npm run dev`
-- `npm run build`
-- `npm run test`
-- `npm run tsc`
+## How the fullstack system stays connected
 
-These are defined in the root `package.json` and should be the first place an agent or contributor checks before inventing a custom workflow.
+At the repository level, shared scripts, shared terminology, and CLI-first workflows keep Vona and Zova aligned as one framework system.
 
-## Why the monorepo matters for workflow selection
+For the shared terminal-first workflow model, see [Fullstack CLI](/fullstack/cli).
 
-The monorepo makes it possible to answer cross-stack questions from source rather than memory, for example:
+## Why the monorepo matters
+
+The monorepo makes it possible to keep backend and frontend concepts, tooling, and generated outputs aligned from source rather than memory, for example:
 
 - how frontend routes and components are reflected back into backend type hints
 - how backend OpenAPI and DTO output feeds frontend SDK generation
-- how edition-specific scripts differ between Cabloy Basic and Cabloy Start
-- how Vona and Zova CLI commands can be reused instead of writing scaffolding manually
+- how common concepts can be documented once before edition-specific notes branch out
+- how Vona and Zova CLI capabilities can be reused instead of rebuilding scaffolding by hand
 
 ## Technology Stack
 
 ### General
 
-| Package    | Version   |
-| ---------- | --------- |
-| TypeScript | `^5.9.3`  |
-| Zod        | `^4.3.6`  |
+| Package    | Version  |
+| ---------- | -------- |
+| TypeScript | `^5.9.3` |
+| Zod        | `^4.3.6` |
 
 ### Backend (Vona)
 
-| Package                            | Version   |
-| ---------------------------------- | --------- |
-| Koa                                | `^3.2.0`  |
-| Knex                               | `^3.2.9`  |
-| Redis Client (`ioredis`)           | `^5.10.1` |
-| SQLite Driver (`better-sqlite3`)   | `^12.9.0` |
+| Package                          | Version   |
+| -------------------------------- | --------- |
+| Koa                              | `^3.2.0`  |
+| Knex                             | `^3.2.9`  |
+| Redis Client (`ioredis`)         | `^5.10.1` |
+| SQLite Driver (`better-sqlite3`) | `^12.9.0` |
 
 ### Frontend (Zova)
 
-| Package          | Version     |
-| ---------------- | ----------- |
-| Vue              | `^3.5.32`   |
-| Vite             | `^8.0.14`   |
-| Quasar           | `^2.19.3`   |
-| TanStack Query   | `^5.100.10` |
-| TanStack Form    | `^1.32.0`   |
-| TanStack Table   | `^8.21.3`   |
+| Package        | Version     |
+| -------------- | ----------- |
+| Vue            | `^3.5.32`   |
+| Vite           | `^8.0.14`   |
+| Quasar         | `^2.19.3`   |
+| TanStack Query | `^5.100.10` |
+| TanStack Form  | `^1.32.0`   |
+| TanStack Table | `^8.21.3`   |
 
 ### Edition-specific UI Stack
 
 - **Cabloy Basic**: DaisyUI + Tailwind CSS
 - **Cabloy Start**: Vuetify
 
-## Common-first, edition-aware
+## Edition impact
+
+Most framework concepts are shared across Cabloy Basic and Cabloy Start because both editions follow the same Cabloy fullstack core. The documentation prefers a common-first explanation, then adds edition-specific notes only where the editions intentionally diverge.
 
-Most framework concepts are shared across Cabloy Basic and Cabloy Start. The new documentation prefers a common-first explanation, then adds edition-specific notes only where the repos intentionally diverge.
+Across editions, the frontend engineering layer stays mostly shared through Zova, Vue, Vite, Quasar tooling, and related libraries. The edition-specific UI layer then diverges between DaisyUI + Tailwind CSS for Cabloy Basic and Vuetify for Cabloy Start.
 
-Use the [Editions Overview](/editions/overview) page whenever a task depends on UI library, module composition, or private-value project boundaries.
+Use the [Editions Overview](/editions/overview) page whenever a task depends on UI library assumptions, flavor names, module composition, SSR site baselines, distribution boundaries, or AI workflow guidance.

package/cabloy-docs/fullstack/quickstart.md

@@ -24,7 +24,7 @@ Before creating a new Cabloy project, make sure your environment has:
 npm create cabloy
 ```
 
-The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. Open this project in Claude Code and start coding immediately with project-specific guidance.
+The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. This path creates a Cabloy Basic project baseline. Open this project in Claude Code and start coding immediately with project-specific guidance.
 
 ## 3. Start the backend
 
@@ -46,10 +46,13 @@ npm run dev:zova:web   # http://localhost:9000/
 
 ### Cabloy Start
 
-Use the frontend commands provided by your project edition. Do not assume the Cabloy Basic flavor names apply to Cabloy Start.
+Cabloy Start is the private commercial edition. Instead of `npm create cabloy`, purchase access to the licensed private repository, clone that source directly, and run `npm run init`. Then use the frontend commands provided by that edition. Do not assume the Cabloy Basic flavor names apply to Cabloy Start.
 
-If you are not sure which edition you are using, read:
+For the full Start onboarding details, including the access and initialization flow, read [Cabloy Start](/editions/cabloy-start).
 
+If you are not sure which edition you are using or which one to choose, read:
+
+- [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
 - [Edition Detection](/editions/detection)
 - [Cabloy Basic](/editions/cabloy-basic)
 - [Cabloy Start](/editions/cabloy-start)
@@ -64,7 +67,7 @@ npm run upgrade
 
 If you are contributing to framework-aware workflows or using Cabloy CLI generation directly, prefer CLI-backed generation over manual scaffolding.
 
-Instead of creating framework files by hand, start with:
+Read [Fullstack CLI](/fullstack/cli) for the shared cross-stack workflow model, then start with:
 
 ```bash
 npm run vona :create

package/cabloy-docs/fullstack/vona-zova-integration.md

@@ -49,14 +49,14 @@ cd zova && npm run build:rest:cabloyBasicWeb
 
 ## Cabloy Start
 
-Cabloy Start is a sibling private repository rather than a subdirectory here, but the same integration idea applies.
+Cabloy Start is the private commercial edition. It lives in a licensed sibling repository rather than a subdirectory here, but the same integration idea applies.
 
 Its root script surface uses Start-specific flavors such as:
 
 - `cabloyStartAdmin`
 - `cabloyStartWeb`
 
-Because Start differs in UI stack and module composition, do not reuse Basic integration examples without first confirming:
+Because Start can differ in UI layer, module composition, SSR site baselines, and project assets, do not reuse Basic integration examples without first confirming:
 
 1. the `__CABLOY_START__` marker
 2. the Start repo’s `package.json`

package/cabloy-docs/fullstack/vscode-extensions.md

@@ -0,0 +1,126 @@
+# VS Code Extensions
+
+Cabloy provides two official VS Code extensions so you can discover and run framework workflows directly from the editor.
+
+These extensions surface Vona and Zova CLI capabilities through Explorer right-click menus. They make common workflows easier to discover and reduce the mental burden of remembering command names, while still keeping the CLI as the authoritative workflow surface.
+
+## Official extensions
+
+- [Vona - Official](https://marketplace.visualstudio.com/items?itemName=cabloy.vona-vscode)
+- [Zova - Official](https://marketplace.visualstudio.com/items?itemName=cabloy.zova-vscode)
+
+## Why the extensions matter
+
+In Cabloy, many common tasks are already modeled as framework workflows instead of ad hoc manual edits.
+
+Typical examples include:
+
+- creating suites and modules
+- generating backend or frontend skeletons
+- initializing config, locale, constants, assets, and related support files
+- refreshing metadata or other generated output
+- running focused refactor workflows when the framework already provides one
+
+The VS Code extensions make those workflows easier to discover inside the editor.
+
+## Shared interaction model
+
+The two extensions follow the same basic model:
+
+- open a Cabloy workspace in VS Code
+- right-click the relevant folder or file in the Explorer
+- choose the matching Vona or Zova menu group
+- run the workflow from the menu instead of typing the full command first
+
+This keeps editor-side discovery aligned with CLI execution.
+
+## Shared menu groups
+
+Both extensions organize their workflows around the same top-level menu vocabulary:
+
+- `Create`
+- `Aspect`
+- `Bean`
+- `Meta`
+- `Init`
+- `Refactor`
+- `Tools`
+
+This shared structure helps you move between backend and frontend work without learning two unrelated menu systems.
+
+## Menus and CLI are two entrypoints to the same workflow
+
+A practical rule is:
+
+- use VS Code menus when you want fast discovery and editor ergonomics
+- use the CLI when you want explicit, scriptable, reproducible execution
+
+In this repository, the shared CLI entrypoints are:
+
+```bash
+npm run vona
+npm run zova
+```
+
+To inspect the available command families directly, start with:
+
+```bash
+npm run vona :
+npm run zova :
+```
+
+These are not competing workflow systems. They are two entrypoints to the same underlying framework workflows.
+
+For the shared terminal-first workflow model behind these menus, see [Fullstack CLI](/fullstack/cli).
+
+## What Vona emphasizes
+
+The Vona extension is backend-oriented.
+
+Its menus focus on workflows such as:
+
+- backend code generation for suites, modules, DTOs, entities, models, services, controllers, and tests
+- backend aspect and bean creation
+- metadata and initialization workflows
+- backend runtime-oriented capabilities such as SSR, socket, queue, schedule, cache, auth, and related infrastructure beans
+- tooling workflows such as metadata generation and CRUD generation
+
+This makes the extension especially useful when you are working inside the backend framework tree and want to stay aligned with Vona conventions.
+
+## What Zova emphasizes
+
+The Zova extension is frontend-oriented.
+
+Its menus focus on workflows such as:
+
+- frontend generation for suites, modules, pages, components, APIs, models, services, and mocks
+- page- and component-oriented bean workflows
+- initialization workflows for frontend config, assets, locale, icons, and support files
+- focused refactors for pages and components
+- OpenAPI-related tooling and metadata generation
+
+This makes the extension especially useful when you are building or evolving frontend structure and want to reuse the framework’s existing generators and refactors.
+
+## One important difference
+
+Although both extensions expose the same top-level menu vocabulary, their workflow depth is not identical.
+
+In practice:
+
+- Zova provides substantial refactor coverage for page and component workflows
+- Vona keeps the same overall menu shape, but its current value is concentrated more heavily in backend generation, bean, meta, init, and tooling workflows
+
+So when you are reshaping frontend structure, the Zova extension is more likely to surface direct refactor actions.
+
+## Recommended workflow rule
+
+Before creating files by hand, first check whether Vona or Zova already provides the generator, initializer, metadata task, or refactor you need.
+
+A good default workflow is:
+
+1. discover the workflow from the VS Code menu or the CLI command list
+2. run the matching framework command
+3. inspect the generated or transformed result
+4. apply only the minimal follow-up edits that are still necessary
+
+This keeps fullstack work aligned with Cabloy conventions and reduces avoidable manual scaffolding.