cabloy 5.1.51 → 5.1.53

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. [Reference Introduction](/reference/introduction)
+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.

package/cabloy-docs/reference/frontend-directory-structure.md

@@ -0,0 +1,125 @@
+# Frontend Directory Structure
+
+This page gives a compact reference view of the frontend tree under `zova/`.
+
+## Why this page exists
+
+The package map explains the architectural meaning of package, module, and suite boundaries.
+
+This page complements that by showing the practical frontend tree layout used in the Cabloy repository.
+
+## Simplified frontend tree
+
+Representative frontend structure:
+
+```text
+zova/
+├── packages-cli/
+├── packages-utils/
+├── packages-zova/
+├── env/
+├── public/
+├── src-ssr/
+└── src/
+   ├── boot/
+   ├── css/
+   ├── front/
+   │  ├── config/
+   │  └── typing/
+   ├── module/
+   ├── module-vendor/
+   ├── suite/
+   └── suite-vendor/
+```
+
+## Meaning of the main directories
+
+| Path                      | Meaning                                        |
+| ------------------------- | ---------------------------------------------- |
+| `zova/packages-cli/`      | Zova CLI entrypoints and command sets          |
+| `zova/packages-utils/`    | shared frontend-side utilities                 |
+| `zova/packages-zova/`     | framework packages                             |
+| `zova/env/`               | frontend env files and runtime/build inputs    |
+| `zova/public/`            | public static assets                           |
+| `zova/src-ssr/`           | SSR entrypoints and SSR-related project source |
+| `zova/src/boot/`          | app bootstrapping and startup registration     |
+| `zova/src/css/`           | project-level CSS and theme entry assets       |
+| `zova/src/front/config/`  | project-level frontend config overrides        |
+| `zova/src/front/typing/`  | project-level frontend type definitions        |
+| `zova/src/module/`        | first-party standalone frontend modules        |
+| `zova/src/module-vendor/` | vendor-provided standalone frontend modules    |
+| `zova/src/suite/`         | first-party frontend suites and their modules  |
+| `zova/src/suite-vendor/`  | vendor-provided frontend suites and modules    |
+
+## Project-level frontend areas
+
+Within the frontend application layer, contributors should also know these practical areas:
+
+| Path                     | Meaning                                            |
+| ------------------------ | -------------------------------------------------- |
+| `zova/env/`              | frontend env files and runtime/build inputs        |
+| `zova/public/`           | project-level public static assets                 |
+| `zova/src-ssr/`          | project-level SSR entry and SSR middleware wiring  |
+| `zova/src/boot/`         | project-level boot registration and startup hooks  |
+| `zova/src/css/`          | project-level CSS, theme, and style entry assets   |
+| `zova/src/front/config/` | project-level frontend config and override surface |
+| `zova/src/front/typing/` | project-level frontend typing definitions          |
+
+## Edition note
+
+The high-level Zova tree above is intentionally stable across Cabloy Basic and Cabloy Start.
+
+A practical rule is:
+
+- use the shared tree as the structural reference
+- treat suite names and UI-layer examples as edition-sensitive details
+- in Cabloy Basic, public examples may include suites such as `cabloy-basic` and `a-devui`
+- in Cabloy Start, examples may include suites such as `cabloy-start` and `a-vuetify`
+
+Cabloy Start is a sibling repository, not a subdirectory of this monorepo.
+
+## Practical development reading of the tree
+
+A useful rule is:
+
+- start in `zova/src/module/` when the work belongs to a standalone frontend module
+- start in `zova/src/suite/` when the work belongs to a suite-composed business area
+- inspect `zova/packages-cli/` when the task is about command discovery, generation behavior, or refactor behavior
+- inspect `zova/src/front/config/` when the task is about project-level frontend config overrides rather than module-local defaults
+- inspect `zova/src/boot/` or `zova/src-ssr/` when the task is about startup flow or SSR behavior
+- inspect `zova/src/css/` and `zova/public/` when the task is about project-level styling or static assets
+
+A practical generator-oriented reading is:
+
+- `create:*` commands choose the structural target before placing frontend resources
+- `init:*` commands create project-level or module-level support assets
+- `refactor:*` commands reshape existing frontend patterns without requiring manual rework from scratch
+- `openapi:*` commands affect generated SDK-related frontend surfaces
+
+## Relationship to other reference pages
+
+Read this page together with:
+
+- [Package Map](/reference/package-map)
+- [Frontend (Zova)](/frontend/introduction)
+- [Modules and Suites](/frontend/modules-and-suites)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+- [Frontend CLI](/frontend/cli)
+
+A practical split is:
+
+- [Frontend (Zova)](/frontend/introduction) is the broader frontend hub
+- [Package Map](/reference/package-map) explains architecture boundaries and package metadata
+- this page explains the practical directory tree contributors navigate
+
+## Implementation checks for frontend file-location changes
+
+When changing frontend code, ask:
+
+1. does this change belong to a standalone module, a suite-contained module, or a project-level frontend area?
+2. is the task about generation behavior under `packages-cli/`, startup behavior under `src/boot` or `src-ssr`, or feature code under `src/`?
+3. should the example use a shared structural path, a Cabloy Basic example, or a public Cabloy Start example note?
+
+That helps keep frontend file references aligned with the actual monorepo layout.

package/cabloy-docs/reference/glossary.md

@@ -14,11 +14,11 @@ The frontend framework in the Cabloy ecosystem.
 
 ## Cabloy Basic
 
-The public reference repository for the shared Cabloy architecture.
+The public framework/reference edition for the shared Cabloy architecture.
 
 ## Cabloy Start
 
-A private sibling repository with different UI and module choices, provided as a value-add edition.
+The private commercial edition, provided as a licensed sibling repository with different UI, module, and project-baseline choices.
 
 ## Edition detection
 

package/cabloy-docs/reference/introduction.md

@@ -0,0 +1,47 @@
+# Reference
+
+This page is the reference hub for shared monorepo commands, package lookup, directory lookup, and shared terminology.
+
+## What Reference is responsible for
+
+- shared monorepo command entrypoints
+- CLI lookup and command-surface discovery
+- package lookup across the repository
+- backend and frontend directory lookup
+- shared terminology and glossary support
+
+## How to approach reference work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the root `package.json` when you need the shared workflow entrypoints
+2. inspect the CLI reference before inferring command families from memory
+3. use package and directory lookup pages when the task is about locating code, modules, or shared terms
+4. pair Reference pages with Backend, Frontend, or Fullstack guides when lookup alone is not enough
+
+## Reference reading paths
+
+Use Reference as the lookup area for shared commands, package discovery, directory lookup, and shared terminology.
+
+### Workflow entry path
+
+Start here when you first need the shared monorepo command surface:
+
+- [Repo Scripts](/reference/repo-scripts)
+- [CLI Reference](/reference/cli-reference)
+- [Fullstack CLI](/fullstack/cli)
+
+### Structure and lookup path
+
+Use this path when you need to find where packages, backend directories, frontend directories, or shared terms live:
+
+- [Package Map](/reference/package-map)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+- [Frontend Directory Structure](/reference/frontend-directory-structure)
+- [Glossary](/reference/glossary)
+
+## Edition impact
+
+Cabloy Start keeps the same high-level workflow pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
+
+When documenting or automating flavor-specific commands, always confirm the active repo first.

package/cabloy-docs/reference/package-map.md

@@ -96,6 +96,8 @@ For the broader backend entry path, also see [Backend (Vona)](/backend/introduct
 
 For the frontend architectural meaning of modules, suites, scope-driven resources, and runtime/startup structure, see `/frontend/modules-and-suites`, `/frontend/module-scope`, `/frontend/ioc-and-beans`, `/frontend/environment-config-guide`, `/frontend/app-startup-guide`, and `/frontend/system-startup-guide`.
 
+For the practical frontend directory tree contributors navigate, also see [Frontend Directory Structure](/reference/frontend-directory-structure).
+
 ## Sibling edition
 
 - `cabloy-start` is a separate sibling repository, not a subdirectory of this monorepo.

package/cabloy-docs/reference/repo-scripts.md

@@ -1,5 +1,9 @@
 # Repo Scripts
 
+Use this page when you need the compact lookup surface for the shared root scripts exposed by the Cabloy Basic monorepo.
+
+For the broader Reference landing page, see [Reference Introduction](/reference/introduction).
+
 The root `package.json` is the first reference point for shared monorepo workflows.
 
 ## Current shared entrypoints in Cabloy Basic
@@ -21,9 +25,7 @@ The root `package.json` is the first reference point for shared monorepo workflo
 
 ## Edition-sensitive note
 
-Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`.
-
-### Documentation and automation guidance
+Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
 
 When documenting or automating flavor-specific commands, always confirm the active repo first.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.51",
+  "version": "5.1.53",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/README.md

@@ -1,4 +1,4 @@
-English | [简体中文](./README.zh-CN.md)
+English | [Simplified Chinese](./README.zh-CN.md)
 
 # Vona