cabloy 5.1.162 → 5.1.164

package/.cabloy-version

@@ -1 +1 @@
-5.1.162
+5.1.164

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 5.1.164
+
+### Features
+
+- Enhance resource selection and CRUD CLI tools.
+
+### Improvements
+
+- Include demonstration suites in the documentation.
+
+## 5.1.163
+
+### Improvements
+
+- Update the Basic homepage end-to-end assertion.
+
 ## 5.1.162
 
 ### Features

package/README.md

@@ -74,6 +74,8 @@ For fuller guidance on choosing an edition and working in an existing checkout,
 | E-commerce                  | A complete Admin site, Web site, personal center, payment flows, Markdown editing, and related capabilities.                               | ✅           | —            |
 | System Management           | User management, role management, department management, RBAC authorization, and menu authorization.                                       | —            | ✅           |
 
+Included demonstration suites give AI vibe coding agents high-quality, project-native code examples. They improve development efficiency while reducing token use. For production deployments, set `PROJECT_DISABLED_SUITES` to a comma-separated list of unneeded suite names to disable them; see the [Environment and Config Guide](https://cabloy.com/frontend/environment-config-guide#built-in-env-variables).
+
 > “Not included” means that the suite is not part of the default edition baseline. It does not limit what can be built with Cabloy.
 
 ## Highlights

package/package.json

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

package/repo-docs/backend/shared-rbac-architecture.md

@@ -129,6 +129,10 @@ After guard admission, a controller must consume the current typed scope. The co
 | Bulk mutation      | `checkEntries(entries)`  | Ensure every intended target is inside scope                          |
 | Create             | `ownerValues()`          | Derive trusted owner/scope fields instead of accepting widening input |
 
+For an atomic multi-ID Resource command, have the command DTO validate its request-list maximum and use `a-rbac` to validate that the list is nonempty and has no duplicate normalized identities. Then load every requested record through the ordinary instance-scoped model boundary. Require complete one-for-one resolution before calling `checkEntries(entries)` and before any mutation. This treats missing, soft-deleted, and other-instance records uniformly as absent; do not use an unscoped query merely to distinguish them. Run the full preflight and mutation inside the domain transaction.
+
+`a-rbac` exposes `this.bean.rbacResourceBulk.entries(...)` for the reusable integrity and authorization sequence. Pass the facade a fresh, ordinary instance-scoped loader (rather than a cache-backed lookup) from the domain transaction. It preserves the requested order, invokes `checkEntries(...)` only after complete normal-scoped loading, and emits localized `a-rbac` scoped errors for invalid ID lists and absent entries.
+
 A representative list shape is:
 
 ```typescript

package/repo-docs/blogs/ai-spec-driven-development/index.md

@@ -0,0 +1,217 @@
+---
+title: CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts
+titleZh: AI Spec 驱动开发：用 CabloyJS 的两个 Skills 把 Spec 变成可核验交付
+titleEn: CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts
+subtitle: From specification generation to bounded execution, see how CabloyJS helps AI work within explicit business boundaries, technical contracts, and acceptance evidence.
+summary: CabloyJS provides two complementary AI Skills—cabloy-spec-generation and cabloy-spec-execution. The first establishes a suite’s specification and traceability authority; the second delivers one confirmed WBS increment and records verification evidence. Using a-commerce as an example, this article explains the generated Spec files, the two derived charts, and how they connect.
+tags:
+  - AI Spec-Driven Development
+  - AI Coding
+  - Spec-Driven Development
+  - Cabloy
+  - Vona
+  - Zova
+  - Software Architecture
+  - Fullstack
+slug: ai-spec-driven-development-en
+cover: ./cover-en-v1.png
+date: 2026-09-11
+---
+
+# CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts
+
+The easiest way to start AI coding is to describe a page or an API in a chat window. But once a project has multiple modules, multiple audiences, and an evolving frontend-backend contract, the genuinely difficult questions become: where does this change belong? Which boundaries have already been confirmed? How can we prove that it is actually complete?
+
+CabloyJS includes two complementary Claude Code Skills that divide the work into two phases: first establish specification authority inside the repository, then execute a bounded delivery increment. This article introduces the two Skills, explains the Spec files they produce and consume, and uses real charts from the built-in `a-commerce` suite to show the result.
+
+## Meet the two Skills first
+
+The two Skills are invoked as follows:
+
+- `cabloy-spec-generation`: creates or maintains the suite planning records under `repo-specs/<suite>/`, establishing traceability among product, technical, delivery, and acceptance concerns.
+- `cabloy-spec-execution`: works from an existing specification to execute one explicit `WBS-*` item—or a finite, approved phase with a closed boundary—and records the actual verification results.
+
+The following table summarizes the difference:
+
+| Dimension           | `cabloy-spec-generation`                                                                        | `cabloy-spec-execution`                                                                                        |
+| ------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Problem addressed   | What should be built, and how should boundaries and acceptance be recorded?                     | How should one approved item be implemented and proven complete?                                               |
+| Input               | A new suite description or a request to maintain an existing specification                      | An explicit `WBS-*` item, or a finite and approved phase                                                       |
+| Primary outputs     | PRD, SRS, PDP/WBS, ATP, ADRs, derived status, and charts                                        | Source changes, test results, Evidence, derived progress, and charts                                           |
+| Confirmation gate   | Confirms identity, scope, topology, site strategy, and more before planning records are written | Confirms the execution dossier, dependencies, scope, commands, and evidence requirements before implementation |
+| What it does not do | Does not write business source code or treat planning as implementation                         | Does not invent requirements, replace specification generation, or automatically expand into adjacent tasks    |
+
+### 1. Establish a specification baseline with generation
+
+In Claude Code, begin with a business description:
+
+```text
+/cabloy-spec-generation Plan an equipment-maintenance suite for field technicians and operations managers: include equipment records, work orders, asset history, role-based access control, and an Admin dashboard.
+```
+
+The Skill first performs read-only discovery and asks for missing inputs. Its typical steps are:
+
+1. inspect the repository root, `package.json`, `CLAUDE.md`, and the edition marker;
+2. distinguish a new suite from an extension of an existing suite, and check whether `repo-specs/<suite>/` already exists;
+3. independently evaluate whether Web and Admin should reuse an existing site or use a dedicated site;
+4. collect product goals, roles, scope, module topology, tenancy and authorization, states, transactions, verification, and release constraints;
+5. show a generation confirmation gate before writing planning records;
+6. generate files in authority order, run exact-ID traceability checks, and produce two derived charts.
+
+### 2. Execute a bounded increment with execution
+
+Once the specification is ready and a task’s dependencies are satisfied, invoke execution:
+
+```text
+/cabloy-spec-execution WBS-40-03
+```
+
+`WBS-40-03` is only an example. A real project should use an ID that actually exists in the target suite. The AI then follows this process:
+
+1. read `README.md`, the PRD, SRS, applicable ADRs, the complete WBS, ATP/test plan, progress, Evidence, and derived charts;
+2. check the edition, current revision, workspace state, dependencies, blockers, unresolved `TODO`s, and whether previous evidence is still valid;
+3. prepare an execution dossier listing the objective, scope, exclusions, authority IDs, source ownership, specialist-Skill routing, verification commands, and evidence format;
+4. obtain explicit confirmation before routing into backend, frontend, or Contract Loop specialist workflows;
+5. run the narrowest meaningful check first, followed by the ATP-required verification;
+6. save Evidence containing the revision, environment, steps, results, and locations of sanitized artifacts;
+7. update derived `progress.md`, regenerate and check the charts, and leave one unambiguous next action.
+
+```text
+/cabloy-spec-execution Execute the next task in the equipment-maintenance suite
+```
+
+If the next incremental WBS ID is unknown, ask the AI to first read the suite’s `progress.md` and combine it with the WBS, ATP, and existing Evidence to list executable `WBS-*` IDs whose dependencies are satisfied. The user can then confirm the specific item to execute next.
+
+## What generation produces: a connected set of Spec files
+
+For a long-lived business suite, the default core output of `cabloy-spec-generation` is located at:
+
+```text
+repo-specs/<suite>/
+├── README.md
+├── prd.md
+├── srs.md
+├── pdp-wbs.md
+├── test-plan.md
+├── progress.md
+├── implementation-gantt.svg
+├── implementation-burndown.svg
+└── decisions/
+    └── 0001-<suite-boundary-slug>.md
+```
+
+This is not simply one large document split into several files. It is a model of **separated authority**: each record owns one kind of fact, while the others refer to it through stable IDs and links.
+
+| File                          | Facts it owns                                                                                                                                                          | What it should not replace                                      |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `README.md`                   | Index, reading order, suite baseline, topology summary, and authority map                                                                                              | Detailed PRD, SRS, or WBS content                               |
+| `prd.md`                      | Product goals, roles, scope, journeys, business rules, product requirements, and product acceptance                                                                    | Table names, DTO syntax, routes, or test commands               |
+| `srs.md`                      | Technical contracts; data and capability ownership; tenancy; identity; authorization; states; transactions; concurrency; APIs/DTOs; SSR; and non-functional boundaries | API authority or authorization determined by a UI layout        |
+| `pdp-wbs.md`                  | Delivery phases, WBS tasks, dependencies, completion checks, and delivery traceability                                                                                 | Upstream product requirements or technical contracts            |
+| `test-plan.md`                | ATP acceptance scenarios, test levels, fixtures, verification procedures, Evidence format, and release gates                                                           | Planned commands presented as results that have already passed  |
+| `progress.md`                 | WBS state, blockers, Evidence pointers, decisions, and the next proof                                                                                                  | Requirements, contracts, or acceptance rules                    |
+| `decisions/*.md`              | Long-lived scope, architecture, security, ownership, or integration decisions                                                                                          | A duplicate SRS or status log                                   |
+| `implementation-gantt.svg`    | A WBS-derived view of phases, task order, dependencies, and status                                                                                                     | Planning authority, date commitments, or duration commitments   |
+| `implementation-burndown.svg` | A scope-and-status-derived count of remaining items                                                                                                                    | A velocity trend or forecast when no historical snapshots exist |
+
+## From business intent to evidence: how the files connect
+
+The core traceability chain is:
+
+```text
+PRD requirement
+      ↓
+SRS contract
+      ↓
+PDP/WBS task
+      ↓
+ATP scenario
+      ↓
+observed Evidence
+```
+
+It can also be written more compactly:
+
+```text
+PRD → SRS → WBS → ATP → Evidence
+```
+
+For example, a product requirement that “an authorized operator can view orders in the current tenant” must be made concrete in the SRS as identity, tenancy, authorization, data ownership, and API contracts. The WBS then defines the implementation boundary and dependencies; the ATP provides executable happy-path, unauthorized, and cross-tenant scenarios; finally, the actual runtime observations are saved as sanitized evidence.
+
+When a task is executed, the document-state update order is:
+
+```text
+Upstream authority changes
+  → traceability matrix
+  → WBS dependencies and completion checks
+  → ATP procedures and expected Evidence
+  → progress / Evidence
+  → two derived charts
+```
+
+`progress.md` and both SVGs are downstream derived outputs. They help people and AI understand the current state quickly.
+
+## How to read the two charts
+
+The charts are automatically generated by built-in scripts from `pdp-wbs.md`, `test-plan.md`, and `progress.md`.
+
+### Gantt: inspect delivery order, not a calendar schedule
+
+The Gantt chart reads the formal phases, WBS tasks, dependencies, and progress statuses. It is useful for answering: what delivery packages exist? What is their approximate order? Which tasks depend on preceding phases?
+
+The current chart for the built-in `a-commerce` suite contains 23 formal WBS tasks, all shown as 23/23 `verified`.
+
+![A-Commerce implementation roadmap: WBS phases, dependencies, and derived status](./implementation-gantt.png)
+
+### Burndown: inspect scope counts, not velocity forecasts
+
+In the current `a-commerce` snapshot, the Burndown chart shows 23 active WBS items, 23 `verified`, 0 remaining, and 0 deferred.
+
+![A-Commerce WBS scope-count burndown: approved scope and remaining-item counts](./implementation-burndown.png)
+
+## When this approach is worthwhile
+
+This approach is best suited to enterprise systems that evolve over time, span modules, involve multiple collaborators, and include both Vona backend and Zova Admin/Web/SSR work—especially where tenancy, authorization, transactions, concurrency, auditability, or external integrations are important.
+
+For a one-off page, a simple website, or a very small utility, a lightweight prompt-to-code workflow may be more economical.
+
+## Start with a small increment
+
+Choose one clearly bounded capability rather than trying to plan an entire system at once:
+
+1. Use generation to plan the requirement.
+   - Record goals, scope, and exclusions.
+   - Confirm technical contracts, ownership, dependencies, and ATP.
+2. Use execution to deliver one WBS ID.
+   - Run applicable verification and save sanitized Evidence.
+   - Update progress and the derived charts.
+3. Proceed to the next increment.
+
+Create a Cabloy project from the public scaffolding:
+
+```bash
+npm create cabloy
+npm run dev
+npm run dev:zova:admin
+npm run dev:zova:web
+```
+
+## Conclusion
+
+AI Spec-Driven Development in CabloyJS is not another way of saying “prompts become code.” It is a more concrete delivery path:
+
+```text
+Business intent → specification authority → bounded WBS → acceptance procedure → observed Evidence
+```
+
+`cabloy-spec-generation` organizes intent into a traceable planning chain. `cabloy-spec-execution` advances one increment within confirmed boundaries. Together, they reduce the AI’s need to guess about business scope, technical ownership, and the definition of done.
+
+## Further reading
+
+- [AI Spec-Driven Development](https://cabloy.com/ai/ai-spec-driven-development)
+- [Generate a Cabloy Suite Specification](https://cabloy.com/ai/playbook-spec-generation)
+- [Execute an Approved Cabloy Specification Increment](https://cabloy.com/ai/playbook-spec-execution)
+- [Verification](https://cabloy.com/ai/verification)
+- [Contract Loop Playbook](https://cabloy.com/fullstack/contract-loop-playbook)
+- [Vona + Zova Integration](https://cabloy.com/fullstack/vona-zova-integration)
+- [Cabloy Fullstack Quick Start Tutorials](https://cabloy.com/fullstack/tutorials-overview)

package/repo-docs/blogs/index.md

@@ -9,6 +9,21 @@ aside: false
 Selected articles on Cabloy, Vona, Zova, and the architectural questions that shape full-stack applications.
 
 <div class="cabloy-blog-grid">
+  <article class="cabloy-blog-card">
+    <a class="cabloy-blog-card__cover" href="/blogs/ai-spec-driven-development/" aria-label="Read CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts">
+      <img src="/blogs/ai-spec-driven-development/cover-en-v1.png" alt="CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts" />
+    </a>
+    <div class="cabloy-blog-card__content">
+      <p class="cabloy-blog-card__date">September 11, 2026</p>
+      <h2><a href="/blogs/ai-spec-driven-development/">CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts</a></h2>
+      <p>Learn how two CabloyJS Skills establish specification authority, execute bounded WBS increments, and derive Gantt and Burndown status views from the same traceability chain.</p>
+      <div class="cabloy-blog-card__tags" aria-label="Article topics">
+        <span>AI Spec-Driven Development</span><span>AI Coding</span><span>Specification Workflow</span><span>Fullstack</span>
+      </div>
+      <a class="cabloy-blog-card__read" href="/blogs/ai-spec-driven-development/">Read article <span aria-hidden="true">→</span></a>
+    </div>
+  </article>
+
   <article class="cabloy-blog-card">
     <a class="cabloy-blog-card__cover" href="/blogs/nextjs-integrated-fullstack-cabloy-contract-loop/" aria-label="Read Next.js Integrated Full Stack and Cabloy’s Bidirectional Contract Loop">
       <img src="/blogs/nextjs-integrated-fullstack-cabloy-contract-loop/cover-en-v1.png" alt="Next.js Integrated Full Stack and Cabloy’s Bidirectional Contract Loop" />

package/repo-docs/editions/overview.md

@@ -33,6 +33,8 @@ Both editions share Vona + Zova, suite-based modular delivery, CLI-first workflo
 | E-commerce                  | A complete Admin site, Web site, personal center, payment flows, Markdown editing, and related capabilities.                               | ✅           | —            |
 | System Management           | User management, role management, department management, RBAC authorization, and menu authorization.                                       | —            | ✅           |
 
+Included demonstration suites give AI vibe coding agents high-quality, project-native code examples. They improve development efficiency while reducing token use. For production deployments, set `PROJECT_DISABLED_SUITES` to a comma-separated list of unneeded suite names to disable them; see the [Environment and Config Guide](https://cabloy.com/frontend/environment-config-guide#built-in-env-variables).
+
 > “Not included” means that the suite is not part of the default edition baseline. It does not limit what can be built with Cabloy.
 
 ## Choosing an edition

package/repo-docs/frontend/environment-config-guide.md

@@ -196,16 +196,49 @@ This distinction is central to writing Zova code that behaves correctly across b
 
 ## Built-in env variables
 
-Zova exposes built-in variables covering areas such as:
-
-- app identity
-- router mode
-- dev-server settings
-- project-disabled suites/modules
-- build output settings
-- API/proxy configuration
-- SSR-specific values
-- mock configuration
+Zova provides the following built-in environment variables. Configure them in `zova/env/.env` or in an applicable meta-specific env file.
+
+### App identity and presentation
+
+`SITE_ID`, `APP_NAME`, `APP_TITLE`, `APP_DESCRIPTION`, `APP_VERSION`, `APP_META_VIEWPORT`, `APP_PUBLIC_PATH`, `APP_LOCALE_DEFAULT`, `APP_LOCALE_HEADER_KEY`, `APP_TZ_HEADER_KEY`
+
+### Router settings
+
+`ROUTER_MODE`, `ROUTER_PAGE_HOME`, `ROUTER_PAGE_LOGIN`, `ROUTER_KEY_RETURNTO`
+
+### Development-server settings
+
+`DEV_SERVER_HOSTNAME`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`
+
+### Project-disabled suites and modules
+
+`PROJECT_DISABLED_SUITES`, `PROJECT_DISABLED_MODULES`
+
+`PROJECT_DISABLED_SUITES` disables entire suites, including every module in each disabled suite. `PROJECT_DISABLED_MODULES` disables individual modules without disabling their containing suite. Both accept comma-separated relative names.
+
+For example, a production deployment that does not need the e-commerce demonstration suite can set:
+
+```dotenv
+PROJECT_DISABLED_SUITES=a-commerce
+```
+
+### Build output settings
+
+`LOGGER_CLIENT_DEFAULT`, `BUILD_OUTDIR`, `BUILD_MINIFY`, `BUILD_SOURCEMAP`, `BUILD_TARGET_BROWSER`, `BUILD_TARGET_NODE`, `BUILD_ANALYZE`, `BUILD_COPY_DIST`, `BUILD_COPY_RELEASE`, `BUILD_REST_COPY_DIST`
+
+### API and proxy configuration
+
+`API_BASE_URL`, `API_PREFIX`, `API_JWT`, `OPENAPI_BASE_URL_DEFAULT`, `OPENAPI_BASE_URL_<MODULE>`, `PROXY_API_ENABLED`, `PROXY_API_BASE_URL`, `PROXY_API_PREFIX`
+
+Use `OPENAPI_BASE_URL_<MODULE>` to override the OpenAPI base URL for a specific module. Replace `<MODULE>` with the module's uppercase underscore-separated name, such as `OPENAPI_BASE_URL_HOME_API`.
+
+### SSR-specific values
+
+`SSR_API_BASE_URL`, `SSR_PROD_PORT`, `SSR_PROD_PROTOCOL`, `SSR_PROD_HOST`, `SSR_WITH_VONA`, `SSR_PROFILE`, `SSR_PROFILE_PUBLIC_RESPONSE_CACHE_EXPIRES`, `SSR_PROFILE_SESSION_RESPONSE_CACHE_EXPIRES`, `SSR_COOKIE_THEMEDARK_DEFAULT`
+
+### Mock-server configuration
+
+`MOCK_ENABLED`, `MOCK_LOGGER`, `MOCK_BASE_NAME`, `MOCK_BUILD`, `MOCK_BUILD_PORT`, `MOCK_BUILD_OUTPUT`, `MOCK_BUILD_CORS`
 
 That means many common project-level knobs already exist and should be reused before inventing project-specific patterns.
 

package/repo-docs/frontend/resource-list-page-deep-dive.md

@@ -151,6 +151,15 @@ This controller becomes the deeper owner for:
 - `schemaFilter`, `schemaRow`, and `permissions`
 - the shared page JSX/render context (`$$page`)
 - permission-driven table-meta refresh through `tableRef.refreshMeta()`
+- transient selected IDs and snapshots of selected loaded rows
+
+### Page-owned row selection
+
+Selection is page-local interaction state, not `ModelResource` cache state. `blockPage` keeps canonical selected IDs and loaded-row snapshots, while `ZTable` receives only a controlled TanStack selection map for the current page.
+
+Consequently, normal paging and same-query refetches preserve selected IDs and refresh a snapshot when its row reappears. The header checkbox selects or clears only **currently loaded** rows; it never selects all rows matching a server-side filter. Selection clears when the result universe materially changes: fixed query, submitted/reset filter, sort, page size, resource identity, or a successful selected-row mutation. Page-size changes also return to page 1, and **Done** clears selection before hiding the selection column.
+
+Snapshots exist for browser UX only. A selected-row command sends IDs; the backend reloads and authorizes every persisted target through the normal instance-scoped model boundary.
 
 This is the second key architectural boundary:
 
@@ -184,8 +193,12 @@ This controller consumes `$$page` and passes the canonical page-owned values int
 - `data`
 - `schemaRow`
 - `tableScope`
+- controlled sorting
+- controlled row selection
+
+It captures the table controller ref back onto `$$page.tableRef`; it does not configure selection policy.
 
-It also captures the table controller ref back onto `$$page.tableRef`.
+`blockPage.selectionPolicy` is the page-owned configuration: `undefined` is automatic, `'always'` shows checkboxes immediately, `'onDemand'` exposes **Select / Done** even without a selected action, and `false` prevents selection. With the automatic policy, a sibling bulk-toolbar action that declares `requiresSelection: true` makes **Select / Done** available. The toolbar's action requirement remains independent from page policy.
 
 This is the clearest proof that `blockTable` is a bridge into table runtime, not the main owner of list state.
 

package/repo-docs/frontend/table-action-visibility-permission-flow-guide.md

@@ -169,6 +169,24 @@ This is the clearest source-confirmed bulk-action rule:
 - bulk action visibility is permission-driven
 - it is resolved in the bulk-toolbar block
 
+### Selected-action enablement is stricter than discovery
+
+A bulk action with `requiresSelection: true` remains visible when its coarse permission check succeeds, but it is disabled unless all of these conditions hold:
+
+1. at least one ID is selected;
+2. every selected ID still has a loaded row snapshot; and
+3. `$passport.checkPermission(...)` permits **every** selected snapshot with the action's permission hint.
+
+The final condition is intentionally an all-record check. A constrained RBAC projection may allow an action for some rows while denying it for others; a mixed selection must not appear enabled.
+
+The bulk action contract separates authored metadata from toolbar runtime props:
+
+- DTO authors configure static `requiresSelection`, `selectedMaxIds`, and optional unconditional `disabled` in action `options`.
+- `blockToolbarBulk` supplies current-page runtime values as `dynamicSelection`, `dynamicDisabled`, and `dynamicDisabledReason`.
+- A component disables itself when either static `disabled` or toolbar-owned `dynamicDisabled` is true. Custom action components consume the `dynamic*` values as UI state; command implementations should not depend on them as mutation policy.
+
+This is still only a browser projection. Direct selected-row API requests must reload the targets and enforce authorization on the server.
+
 ## Row action hints vs bulk action hints
 
 The permission hint contracts live in:
@@ -240,6 +258,8 @@ If a list-page action is missing unexpectedly, ask:
 5. for row actions, is the operations-row cell bean actually resolving a visible renderer set?
 6. for bulk actions, is the bulk toolbar reading the expected action config?
 7. are you accidentally expecting entry-page `formScene` behavior in a list-page action surface?
+8. for a selected action, is selection nonempty, complete, and permitted for every selected snapshot?
+9. does the backend endpoint independently reload and authorize all submitted IDs?
 
 ## Where to read next
 

package/repo-docs/frontend/table-guide.md

@@ -119,6 +119,48 @@ A practical reading takeaway is:
 - **the visible wrapper component is thin**
 - **the controller bean is the real runtime owner**
 
+## Row selection and selected actions
+
+Row selection is opt-in. Direct `ZTable` use remains unchanged unless it receives the controlled TanStack selection surface:
+
+```tsx
+<ZTable
+  data={this.students}
+  schema={this.schemaRow}
+  enableRowSelection={true}
+  rowSelection={this.rowSelection}
+  onRowSelectionChange={updater => {
+    this.rowSelection = functionalUpdate(updater, this.rowSelection);
+  }}
+/>
+```
+
+The framework-owned selection column is not a schema field: it is left-pinned, non-sortable, and uses the stable `getRowId(...)` identity. The header checkbox selects only rows currently loaded in the table; under server pagination it never means every row matching the filter.
+
+For standard resource list pages, `basic-page:blockPage` owns selected IDs, loaded row snapshots, and the `selectionPolicy` configuration. Its default `undefined` policy is automatic: a `tableActionBulk` action that opts in with `requiresSelection: true` makes the localized **Select** control available:
+
+```ts
+ZovaRender.block('basic-page:blockPage', {
+  blocks: [
+    ZovaRender.block('basic-page:blockToolbarBulk', {
+      actions: [
+        ZovaRender.tableActionBulk('basic-table:actionCreate'),
+        ZovaRender.tableActionBulk('basic-table:actionDeleteBulk', {
+          requiresSelection: true,
+        }),
+      ],
+    }),
+    ZovaRender.block('basic-page:blockTable'),
+  ],
+});
+```
+
+Use `selectionPolicy: 'onDemand'` to expose **Select / Done** without a selected action, `'always'` to show row selection continuously, or `false` to disable row selection for the page. In automatic and on-demand modes, **Select** keeps the checkbox column hidden until the user enters selection mode; **Done** clears the selection and hides the column. Required actions remain discoverable but disabled until every selected row has a current snapshot and passes the projected row-permission check.
+
+Schema metadata remains declarative: author `requiresSelection`, `selectedMaxIds`, and an unconditional `disabled` in action options. A custom bulk-action component receives current toolbar state through `dynamicSelection`, `dynamicDisabled`, and `dynamicDisabledReason`; it should disable when either `disabled` or `dynamicDisabled` is true. Frontend snapshots provide UX only—server actions must reload and authorize all submitted IDs.
+
+Selection persists while paging the same result universe and during ordinary refetches. It clears on a material fixed-query change, filter submit/reset, sorting, page-size change, resource change, or a successful selection-consuming mutation. Page-size changes also return to page 1.
+
 ## Step 3: Let schema metadata drive the default columns
 
 In the default path, `ZTable` reads table-scene metadata from the row schema.

package/repo-docs/frontend/table-resource-crud-cookbook.md

@@ -165,6 +165,7 @@ Its controller is responsible for:
 - creating query state
 - loading schema and paged data
 - exposing `data`, `schemaRow`, `schemaFilter`, `permissions`, and `paged`
+- owning selected IDs, loaded-row snapshots, and the page-level `selectionPolicy`
 - refreshing table metadata when permissions change
 
 This is one of the most important architecture facts about CRUD pages.
@@ -258,6 +259,26 @@ A practical rule is:
 - if the page only needs standard create or other bulk actions, keep the existing block and adjust the metadata
 - if an action is reusable, prefer a reusable action render resource rather than page-local ad hoc code
 
+### Declare selected-row actions explicitly
+
+`tableActionBulk` describes toolbar placement, not necessarily a batch mutation. Keep Create selection-independent. An action that consumes selected rows must declare `requiresSelection: true`:
+
+```ts
+ZovaRender.block('basic-page:blockToolbarBulk', {
+  actions: [
+    ZovaRender.tableActionBulk('basic-table:actionCreate'),
+    ZovaRender.tableActionBulk('basic-table:actionDeleteBulk', {
+      requiresSelection: true,
+      selectedMaxIds: 100,
+    }),
+  ],
+});
+```
+
+With `blockPage`'s default automatic `selectionPolicy`, this exposes an on-demand **Select** control. It reveals the checkbox column; **Done** clears selection before hiding it. Coarse permission controls action discoverability. A selected action is disabled until the selection is nonempty, all selected IDs have loaded snapshots, and every snapshot passes the browser permission matcher. `selectedMaxIds` is optional action policy: when declared, the toolbar disables only that action after the configured count is exceeded; when omitted for a selection-requiring action, the frontend fallback applies.
+
+The DTO declares static policy only. Custom bulk-action components receive the current selection and eligibility as `dynamicSelection`, `dynamicDisabled`, and `dynamicDisabledReason`. Those snapshots are only UX evidence: the command must reload, authorize, and mutate every submitted ID atomically on the backend.
+
 ## Step 6: Let `blockTable` bridge page state into `ZTable`
 
 The standard table block is:
@@ -271,10 +292,13 @@ Its bridge role is very clear:
 - pass row schema into `schema`
 - pass the resource order schema into `schemaOrder`
 - pass controlled `sorting` and `onSortingChange`
+- pass controlled `rowSelection` and `onRowSelectionChange`
 - pass page CEL scope into `tableScope`
 - capture the table controller through `controllerRef`
 
-That means `blockTable` does not own list fetching or pagination logic.
+`blockPage.selectionPolicy` controls row-selection behavior: `undefined` uses automatic behavior, `'always'` shows selection immediately, `'onDemand'` exposes Select/Done without a selected action, and `false` disables selection. `blockTable` only consumes the resulting page state. The header checkbox operates only on the loaded page under server pagination.
+
+That means `blockTable` does not own list fetching, pagination, or selection policy.
 
 It owns the handoff from page resource state to the reusable table runtime.
 

package/repo-e2e/docs/specs/blogs-index.spec.ts

@@ -25,6 +25,7 @@ interface IArticleGeometry {
 }
 
 const blogArticlePaths = [
+  '/blogs/ai-spec-driven-development/',
   '/blogs/ai-react-nextjs-enterprise-architecture-cabloy/',
   '/blogs/cabloy-fullstack-resource-addressing/',
   '/blogs/nextjs-integrated-fullstack-cabloy-contract-loop/',
@@ -118,29 +119,46 @@ test(
     await expect(page.locator('.VPDoc.has-aside')).toHaveCount(0);
 
     const cards = page.locator('.cabloy-blog-card');
-    await expect(cards).toHaveCount(4);
-    for (let index = 0; index < 4; index++) {
+    await expect(cards).toHaveCount(5);
+    for (let index = 0; index < 5; index++) {
       await expect(cards.nth(index)).toBeVisible();
       await expect(cards.nth(index).locator('.cabloy-blog-card__cover img')).toBeVisible();
     }
+    await expect(
+      cards.nth(0).getByRole('link', {
+        name: 'CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts',
+        exact: true,
+      }),
+    ).toBeVisible();
+    await expect(cards.nth(0).locator('.cabloy-blog-card__date')).toHaveText('September 11, 2026');
+    await expect(cards.nth(0).locator('.cabloy-blog-card__cover')).toHaveAttribute(
+      'href',
+      '/blogs/ai-spec-driven-development/',
+    );
 
     const geometry = await getBlogsGeometry(page);
     expect(geometry.grid.display).toBe('grid');
-    expect(geometry.cards).toHaveLength(4);
+    expect(geometry.cards).toHaveLength(5);
 
-    const [firstCard, ...remainingCards] = geometry.cards;
+    const [firstCard, secondCard, thirdCard, fourthCard, fifthCard] = geometry.cards;
+    const firstRow = [firstCard, secondCard, thirdCard, fourthCard];
     expect(firstCard.width).toBeGreaterThanOrEqual(279);
-    for (const card of remainingCards) {
+    for (const card of firstRow) {
       expect(Math.abs(card.top - firstCard.top)).toBeLessThanOrEqual(1);
       expect(Math.abs(card.width - firstCard.width)).toBeLessThanOrEqual(1);
-      expect(card.left).toBeGreaterThan(firstCard.left);
       expect(card.left).toBeGreaterThanOrEqual(geometry.grid.left - 1);
       expect(card.right).toBeLessThanOrEqual(geometry.grid.right + 1);
       expect(card.right).toBeLessThanOrEqual(1441);
     }
-    expect(firstCard.left).toBeGreaterThanOrEqual(geometry.grid.left - 1);
-    expect(firstCard.right).toBeLessThanOrEqual(geometry.grid.right + 1);
-    expect(firstCard.right).toBeLessThanOrEqual(1441);
+    expect(secondCard.left).toBeGreaterThan(firstCard.left);
+    expect(thirdCard.left).toBeGreaterThan(secondCard.left);
+    expect(fourthCard.left).toBeGreaterThan(thirdCard.left);
+    expect(fifthCard.top).toBeGreaterThan(firstCard.bottom);
+    expect(fifthCard.left).toBeCloseTo(firstCard.left, 0);
+    expect(fifthCard.width).toBeCloseTo(firstCard.width, 0);
+    expect(fifthCard.left).toBeGreaterThanOrEqual(geometry.grid.left - 1);
+    expect(fifthCard.right).toBeLessThanOrEqual(geometry.grid.right + 1);
+    expect(fifthCard.right).toBeLessThanOrEqual(1441);
 
     await expect.poll(() => getDocumentHorizontalOverflow(page)).toBeLessThanOrEqual(1);
     expect(pageErrors).toEqual([]);
@@ -163,6 +181,24 @@ test(
       await expect(page.locator('.VPDoc.has-sidebar')).toHaveCount(0);
       await expect(page.locator('.VPDoc.has-aside')).toHaveCount(1);
       await expect(page.locator('.aside')).toBeVisible();
+      if (path === '/blogs/ai-spec-driven-development/') {
+        await expect(
+          page.getByRole('heading', {
+            name: 'CabloyJS AI Spec-Driven Development Automatically Generates Gantt and Burndown Charts',
+            level: 1,
+          }),
+        ).toBeVisible();
+        await expect(
+          page.getByAltText(
+            'A-Commerce implementation roadmap: WBS phases, dependencies, and derived status',
+          ),
+        ).toBeVisible();
+        await expect(
+          page.getByAltText(
+            'A-Commerce WBS scope-count burndown: approved scope and remaining-item counts',
+          ),
+        ).toBeVisible();
+      }
 
       const geometry = await getArticleGeometry(page);
       expect(geometry.container.width).toBeCloseTo(1216, 0);