cabloy 5.1.51 → 5.1.52

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 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
+- 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,19 @@
 # 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
 
 ## Shared architecture
 
@@ -8,54 +21,51 @@ 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.
+
+## How the fullstack system stays connected
 
-- `npm run vona`
-- `npm run zova`
-- `npm run dev`
-- `npm run build`
-- `npm run test`
-- `npm run tsc`
+At the repository level, shared scripts, shared terminology, and CLI-first workflows keep Vona and Zova aligned as one framework system.
 
-These are defined in the root `package.json` and should be the first place an agent or contributor checks before inventing a custom workflow.
+For the shared terminal-first workflow model, see [Fullstack CLI](/fullstack/cli).
 
-## Why the monorepo matters for workflow selection
+## Why the monorepo matters
 
-The monorepo makes it possible to answer cross-stack questions from source rather than memory, for example:
+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
 
@@ -64,6 +74,8 @@ The monorepo makes it possible to answer cross-stack questions from source rathe
 
 ## Common-first, edition-aware
 
-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.
+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.
+
+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 differs 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.

package/cabloy-docs/index.md

@@ -3,8 +3,8 @@ layout: home
 
 hero:
   name: 'Cabloy'
-  text: 'Unified fullstack framework documentation'
-  tagline: Build SSR, SPA, Web, and Admin applications with monorepo-native guidance for Cabloy, Vona, Zova, and AI-assisted development.
+  text: 'Node.js fullstack framework for AI vibe coding'
+  tagline: Build backend and frontend with one fullstack framework. Vona, Zova, suites, and CLI-first workflows make AI vibe coding faster and more accurate.
   actions:
     - theme: brand
       text: Get Started
@@ -17,57 +17,56 @@ hero:
       link: /ai/introduction
 
 features:
-  - title: Fullstack by design
-    details: Understand how Cabloy combines the Vona backend and the Zova frontend in one source tree so humans and AI agents can work from the same ground truth.
-  - title: Edition-aware workflows
-    details: Distinguish what is common across Cabloy Basic and Cabloy Start, and what changes because of UI library, module composition, or private value-add features.
-  - title: CLI-first automation
-    details: Reuse Vona and Zova CLI capabilities for scaffolding, refactoring, metadata, and verification instead of re-deriving framework conventions from scratch.
-  - title: AI-ready knowledge system
-    details: Connect public docs, internal architecture notes, Claude rules, and skills so AI-assisted development stays accurate, efficient, and maintainable.
+  - title: One framework system
+    details: Build backend and frontend in one fullstack architecture.
+  - title: Vona + Zova
+    details: Use aligned backend and frontend frameworks for code sharing, workflow reuse, and cross-stack consistency.
+  - title: Suite-based modular system
+    details: Organize capabilities as suites and modules so services, features, metadata, and tooling evolve in composable units.
+  - title: Multiple delivery modes
+    details: Deliver SSR, SPA, Web, and Admin applications with shared conventions across the stack.
+  - title: CLI-first workflows for AI vibe coding
+    details: Turn scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding.
+  - title: Monorepo-native development
+    details: Keep framework source, docs, and tooling aligned in one monorepo workflow.
 ---
 
 # Cabloy Documentation
 
-This site is the new documentation home for the Cabloy monorepo.
+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.
 
-It is designed around four practical goals:
+Start here to learn the shared Cabloy architecture, see how Vona and Zova fit together, understand how Cabloy Basic and Cabloy Start share one fullstack core but diverge by edition, and follow CLI-first workflows grounded in the current source tree.
 
-1. explain the shared architecture across Cabloy, Vona, and Zova
-2. document the real monorepo workflows used in current source code
-3. distinguish Cabloy Basic and Cabloy Start clearly
-4. provide durable guidance for AI-assisted development
+## What you can do here
 
-## What is covered here
-
-- **Fullstack**: monorepo setup, shared workflows, and cross-stack architecture
-- **Backend (Vona)**: backend concepts, infrastructure, and CLI-backed workflows
-- **Frontend (Zova)**: frontend concepts, SSR, UI-stack considerations, and CLI-backed workflows
-- **Editions**: how Cabloy Basic and Cabloy Start relate and where they differ
-- **AI Development**: how docs, skills, rules, commands, and internal engineering notes work together
-- **Reference**: scripts, CLI command families, package layout, and terminology
-
-## Documentation scope labels
-
-Use these labels throughout the site:
-
-<Badge type="tip" text="Common" /> applies to both Cabloy Basic and Cabloy Start.
-
-<Badge type="info" text="Basic" /> applies only to Cabloy Basic.
-
-<Badge type="warning" text="Start" /> applies only to Cabloy Start.
+- **Get started quickly** with the fullstack quickstart and core Cabloy concepts
+- **Learn the shared fullstack architecture** across Cabloy, Vona, and Zova
+- **Explore backend and frontend workflows** without losing the cross-stack picture
+- **See how Cabloy Basic and Cabloy Start differ by edition** when UI assumptions, flavors, modules, SSR sites, or AI workflow guidance matter
+- **Follow source-grounded AI vibe coding guidance** for prompting, workflow selection, and verification
 
 ## First reading path
 
-### For project users
+### For getting started
 
 1. [Fullstack Quickstart](/fullstack/quickstart)
 2. [Editions Overview](/editions/overview)
-3. [Fullstack Introduction](/fullstack/introduction)
+3. [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
+4. [Fullstack Introduction](/fullstack/introduction)
 
-### For framework contributors and AI workflows
+### For contributors and AI vibe coding workflows
 
 1. [Fullstack Introduction](/fullstack/introduction)
-2. [AI Development Introduction](/ai/introduction)
-3. [Repo Scripts Reference](/reference/repo-scripts)
-4. [Editions Overview](/editions/overview)
+2. [Fullstack CLI](/fullstack/cli)
+3. [VS Code Extensions](/fullstack/vscode-extensions)
+4. [AI Development Introduction](/ai/introduction)
+5. [Repo Scripts Reference](/reference/repo-scripts)
+6. [Editions Overview](/editions/overview)
+
+## Documentation scope labels
+
+Use these labels throughout the site:
+
+- <Badge type="tip" text="Common" /> applies to both Cabloy Basic and Cabloy Start.
+- <Badge type="info" text="Basic" /> applies only to Cabloy Basic.
+- <Badge type="warning" text="Start" /> applies only to Cabloy Start.