cabloy 5.1.52 → 5.1.54

package/.claude/skills/cabloy-frontend-scaffold/SKILL.md

@@ -156,6 +156,16 @@ Check whether the feature needs:
 - SSR or route-path verification
 - edition-specific flavor, SSR site baseline, and project-asset verification
 
+### SSR theme review reminder
+
+If the frontend change is SSR theme-sensitive, apply this short review before finishing:
+
+- detect the active edition marker and UI library before assuming SSR theme behavior
+- do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff
+- in Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth
+- keep theme-finalization logic inside the active theme handler or client boot path instead of duplicating it in page or component code
+- verify both server handoff and client hydration behavior for the active adapter
+
 ### Optional backend-contract reminder
 
 Stay frontend-first, but if the frontend task clearly depends on backend contract output, add a reminder such as:

package/.github/workflows/docs-pages.yml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - uses: actions/setup-node@v6
         with:
           node-version: 24

package/.github/workflows/vona-cov-pg.yml

@@ -29,7 +29,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - name: cov

package/.github/workflows/vona-test-crud.yml

@@ -22,7 +22,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: npm run vona :create:module demo-student -- --suite --ci

package/.github/workflows/vona-test-mysql.yml

@@ -29,7 +29,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run test

package/.github/workflows/vona-test-pg.yml

@@ -29,7 +29,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: DATABASE_DEFAULT_CLIENT=pg npm run test

package/.github/workflows/vona-test-sqlite3.yml

@@ -22,7 +22,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run test

package/.github/workflows/vona-tsc.yml

@@ -17,7 +17,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - name: tsc

package/.github/workflows/zova-ui.yml

@@ -17,7 +17,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - name: suite

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 5.1.54
+
+### Features
+
+- Add a set of incremental feature updates across the codebase to expand supported functionality and behavior.
+
+### Bug Fixes
+
+- Support `src/module` test targets.
+- Support module-relative test targets.
+
+### Improvements
+
+- Clarify ORM omit semantics in tests and documentation.
+- Refine query and model-related internals, including updates to post handling, `where` building, and model cache behavior.
+
+## 5.1.53
+
+### Features
+
+- Update application functionality across core feature areas.
+- Update configuration behavior and related integration points.
+- Update theme configuration and controller handling.
+
+### Improvements
+
+- Remove the generated `$useLocale` helper.
+- Refresh project configuration files and internal implementation details.
+
+### Breaking Changes
+
+- Rename the SSR cookie-disabled server flag and update related documentation.
+
 ## 5.1.52
 
 ### Features

package/CLAUDE.md

@@ -44,6 +44,9 @@ Before inventing a custom implementation path:
 - Prefer CLI-backed workflows over manual scaffolding whenever Vona or Zova already provides a generator, refactor, metadata, or verification command.
 - Treat legacy docs as input material, not as unquestioned truth. When docs conflict with source code, prefer current source code.
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
+- For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
+- In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.
+- Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff. Verify the active theme handler and client hydration path before changing SSR theme behavior.
 - Reuse existing repo terminology: Cabloy, Vona, Zova, suite, module, bean, SSR, SPA, Web, Admin.
 - For backend base-class placement, use the A / B1 / B2 rule from `cabloy-docs/ai/class-placement-rule.md`.
 - Pure helper bases belong in `src/lib`; subclass-only bases should be evaluated case by case and often belong in `src/lib`.

package/README.md

@@ -20,14 +20,14 @@ With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns comm
 
 Before creating a new Cabloy project, make sure your environment has:
 
-| Name       | Version     |
-| ---------- | ----------- |
-| pnpm       | `>=10.19.0` |
-| Node.js    | `>=24.4.0`  |
-| Redis      | `>=7.2.6`   |
-| SQLite3    | `Built-in`  |
-| MySQL      | `>=8`       |
-| PostgreSQL | `>=16`      |
+| Name       | Version    |
+| ---------- | ---------- |
+| pnpm       | `>=11.5.2` |
+| Node.js    | `>=24.4.0` |
+| Redis      | `>=7.2.6`  |
+| SQLite3    | `Built-in` |
+| MySQL      | `>=8`      |
+| PostgreSQL | `>=16`     |
 
 - `Redis`: powers queue, schedule, startup, broadcast, caching, two-layer cache, and redlock
 - `SQLite3`: if you use `better-sqlite3`, set up `node-gyp` before installing dependencies

package/cabloy-docs/.vitepress/config.mjs

@@ -31,12 +31,60 @@ const aiItems = [
   { text: 'Verification', link: '/ai/verification' },
 ];
 
-const referenceItems = [
-  { text: 'Repo Scripts', link: '/reference/repo-scripts' },
-  { text: 'CLI Reference', link: '/reference/cli-reference' },
-  { text: 'Package Map', link: '/reference/package-map' },
-  { text: 'Backend Directory Structure', link: '/reference/backend-directory-structure' },
-  { text: 'Glossary', link: '/reference/glossary' },
+const fullstackGroups = [
+  {
+    text: 'Fullstack / Getting Started',
+    items: [
+      { text: 'Introduction', link: '/fullstack/introduction' },
+      { text: 'Quickstart', link: '/fullstack/quickstart' },
+    ],
+  },
+  {
+    text: 'Tooling & Workflow',
+    items: [
+      { text: 'CLI', link: '/fullstack/cli' },
+      { text: 'VS Code Extensions', link: '/fullstack/vscode-extensions' },
+    ],
+  },
+  {
+    text: 'Architecture & Integration',
+    items: [
+      {
+        text: 'Comparison with Other Frameworks',
+        link: '/fullstack/comparison-with-other-frameworks',
+      },
+      { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
+      { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
+      {
+        text: 'Frontend Metadata Back to Backend',
+        link: '/fullstack/frontend-metadata-to-backend',
+      },
+      {
+        text: 'Edition Collaboration Differences',
+        link: '/fullstack/edition-collaboration-differences',
+      },
+    ],
+  },
+];
+
+const referenceGroups = [
+  {
+    text: 'Reference / Workflow Entry',
+    items: [
+      { text: 'Introduction', link: '/reference/introduction' },
+      { text: 'Repo Scripts', link: '/reference/repo-scripts' },
+      { text: 'CLI Reference', link: '/reference/cli-reference' },
+    ],
+  },
+  {
+    text: 'Structure & Lookup',
+    items: [
+      { text: 'Package Map', link: '/reference/package-map' },
+      { text: 'Backend Directory Structure', link: '/reference/backend-directory-structure' },
+      { text: 'Frontend Directory Structure', link: '/reference/frontend-directory-structure' },
+      { text: 'Glossary', link: '/reference/glossary' },
+    ],
+  },
 ];
 
 const GA_MEASUREMENT_ID = process.env.GA_MEASUREMENT_ID;
@@ -74,46 +122,27 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Fullstack', link: '/fullstack/introduction', activeMatch: '^/fullstack/' },
-      { text: 'Backend', link: '/backend/introduction', activeMatch: '^/backend/' },
-      { text: 'Frontend', link: '/frontend/introduction', activeMatch: '^/frontend/' },
+      { text: 'Backend (Vona)', link: '/backend/introduction', activeMatch: '^/backend/' },
+      { text: 'Frontend (Zova)', link: '/frontend/introduction', activeMatch: '^/frontend/' },
       { text: 'Editions', link: '/editions/overview', activeMatch: '^/editions/' },
       { text: 'AI Development', link: '/ai/introduction', activeMatch: '^/ai/' },
-      { text: 'Reference', link: '/reference/repo-scripts', activeMatch: '^/reference/' },
+      { text: 'Reference', link: '/reference/introduction', activeMatch: '^/reference/' },
     ],
     sidebar: {
-      '/fullstack/': [
-        {
-          text: 'Fullstack',
-          items: [
-            { text: 'Introduction', link: '/fullstack/introduction' },
-            {
-              text: 'Comparison with Other Frameworks',
-              link: '/fullstack/comparison-with-other-frameworks',
-            },
-            { text: 'Quickstart', link: '/fullstack/quickstart' },
-            { text: 'CLI', link: '/fullstack/cli' },
-            { text: 'VS Code Extensions', link: '/fullstack/vscode-extensions' },
-            { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
-            { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
-            {
-              text: 'Frontend Metadata Back to Backend',
-              link: '/fullstack/frontend-metadata-to-backend',
-            },
-            {
-              text: 'Edition Collaboration Differences',
-              link: '/fullstack/edition-collaboration-differences',
-            },
-          ],
-        },
-      ],
+      '/fullstack/': fullstackGroups,
       '/backend/': [
         {
-          text: 'Backend (Vona)',
+          text: 'Backend (Vona) / Getting Started',
           items: [
             { text: 'Introduction', link: '/backend/introduction' },
             { text: 'Foundation', link: '/backend/foundation' },
             { text: 'Backend Essentials', link: '/backend/backend-essentials' },
             { text: 'Quickstart', link: '/backend/quickstart' },
+          ],
+        },
+        {
+          text: 'Tooling & Runtime',
+          items: [
             { text: 'CLI', link: '/backend/cli' },
             { text: 'Scripts', link: '/backend/scripts' },
             { text: 'Runtime and Flavors', link: '/backend/runtime-and-flavors' },
@@ -123,18 +152,34 @@ export default defineConfig({
               text: 'Multi-Instance and Instance Resolution',
               link: '/backend/multi-instance-and-instance-resolution',
             },
+          ],
+        },
+        {
+          text: 'Security & Access',
+          items: [
             { text: 'Auth Guide', link: '/backend/auth-guide' },
             { text: 'Captcha Guide', link: '/backend/captcha-guide' },
             { text: 'User Access Guide', link: '/backend/user-access-guide' },
+            { text: 'JWT Guide', link: '/backend/jwt-guide' },
+            { text: 'Validation Guide', link: '/backend/validation-guide' },
+          ],
+        },
+        {
+          text: 'Application Basics',
+          items: [
             { text: 'Menu Guide', link: '/backend/menu-guide' },
             { text: 'I18n Guide', link: '/backend/i18n-guide' },
             { text: 'Error Guide', link: '/backend/error-guide' },
-            { text: 'JWT Guide', link: '/backend/jwt-guide' },
             { text: 'Event Guide', link: '/backend/event-guide' },
             { text: 'Logger Guide', link: '/backend/logger-guide' },
             { text: 'Upload Guide', link: '/backend/upload-guide' },
             { text: 'Mail Guide', link: '/backend/mail-guide' },
             { text: 'Serialization Guide', link: '/backend/serialization-guide' },
+          ],
+        },
+        {
+          text: 'Core Programming Model',
+          items: [
             { text: 'AOP Overview', link: '/backend/aop-overview' },
             { text: 'Controller Guide', link: '/backend/controller-guide' },
             { text: 'Controller AOP Guide', link: '/backend/controller-aop-guide' },
@@ -144,10 +189,14 @@ export default defineConfig({
             { text: 'Model Guide', link: '/backend/model-guide' },
             { text: 'Entity Guide', link: '/backend/entity-guide' },
             { text: 'DTO Guide', link: '/backend/dto-guide' },
+          ],
+        },
+        {
+          text: 'Data & CRUD',
+          items: [
             { text: 'CRUD Workflow', link: '/backend/crud-workflow' },
             { text: 'Migration and Changes', link: '/backend/migration-and-changes' },
             { text: 'Field Indexes', link: '/backend/field-indexes' },
-            { text: 'Unit Testing', link: '/backend/unit-testing' },
             { text: 'ORM Guide', link: '/backend/orm-guide' },
             { text: 'ORM Configuration Guide', link: '/backend/orm-configuration-guide' },
             { text: 'ORM Select Guide', link: '/backend/orm-select-guide' },
@@ -155,6 +204,11 @@ export default defineConfig({
             { text: 'ORM Aggregate and Group Guide', link: '/backend/orm-aggregate-group-guide' },
             { text: 'Relations Guide', link: '/backend/relations-guide' },
             { text: 'Transaction Guide', link: '/backend/transaction-guide' },
+          ],
+        },
+        {
+          text: 'Infrastructure & Distributed',
+          items: [
             { text: 'Cache Guide', link: '/backend/cache-guide' },
             {
               text: 'Multi-Database and Datasource Guide',
@@ -169,55 +223,100 @@ export default defineConfig({
             { text: 'Worker Guide', link: '/backend/worker-guide' },
             { text: 'Broadcast Guide', link: '/backend/broadcast-guide' },
             { text: 'Redlock Guide', link: '/backend/redlock-guide' },
-            { text: 'Validation Guide', link: '/backend/validation-guide' },
+          ],
+        },
+        {
+          text: 'API & Testing',
+          items: [
             { text: 'OpenAPI Guide', link: '/backend/openapi-guide' },
             { text: 'DTO Infer and Generation', link: '/backend/dto-infer-generation' },
+            { text: 'Unit Testing', link: '/backend/unit-testing' },
           ],
         },
       ],
       '/frontend/': [
         {
-          text: 'Frontend (Zova)',
+          text: 'Frontend (Zova) / Getting Started',
           items: [
             { text: 'Introduction', link: '/frontend/introduction' },
             { text: 'Quickstart', link: '/frontend/quickstart' },
             { text: 'Foundation', link: '/frontend/foundation' },
+          ],
+        },
+        {
+          text: 'Architecture & Modules',
+          items: [
             { text: 'IoC and Beans', link: '/frontend/ioc-and-beans' },
             { text: 'Modules and Suites', link: '/frontend/modules-and-suites' },
             { text: 'Module Scope', link: '/frontend/module-scope' },
+            { text: 'Design Principles', link: '/frontend/design-principles' },
+          ],
+        },
+        {
+          text: 'Environment & Startup',
+          items: [
             { text: 'Environment and Config Guide', link: '/frontend/environment-config-guide' },
             { text: 'App Startup Guide', link: '/frontend/app-startup-guide' },
             { text: 'System Startup Guide', link: '/frontend/system-startup-guide' },
+          ],
+        },
+        {
+          text: 'Tooling',
+          items: [
+            { text: 'CLI', link: '/frontend/cli' },
+            { text: 'Scripts', link: '/frontend/scripts' },
+            { text: 'Mock Guide', link: '/frontend/mock-guide' },
+          ],
+        },
+        {
+          text: 'Pages & Routing',
+          items: [
             { text: 'Page Guide', link: '/frontend/page-guide' },
             { text: 'Page Query Guide', link: '/frontend/page-query-guide' },
             { text: 'Page Params Guide', link: '/frontend/page-params-guide' },
-            { text: 'Page Route Guide', link: '/frontend/page-route-guide' },
             { text: 'Zod Guide', link: '/frontend/zod-guide' },
+            { text: 'Page Route Guide', link: '/frontend/page-route-guide' },
             { text: 'Route Alias Guide', link: '/frontend/route-alias-guide' },
             { text: 'Navigation Guards Guide', link: '/frontend/navigation-guards-guide' },
+          ],
+        },
+        {
+          text: 'Components & UI',
+          items: [
             { text: 'Component Guide', link: '/frontend/component-guide' },
             { text: 'Component Props Guide', link: '/frontend/component-props-guide' },
             { text: 'Component v-model Guide', link: '/frontend/component-v-model-guide' },
             { text: 'Generic Component Guide', link: '/frontend/generic-component-guide' },
-            { text: 'CLI', link: '/frontend/cli' },
-            { text: 'Scripts', link: '/frontend/scripts' },
-            { text: 'Mock Guide', link: '/frontend/mock-guide' },
             { text: 'CSS-in-JS Guide', link: '/frontend/css-in-js-guide' },
             { text: 'Theme Guide', link: '/frontend/theme-guide' },
             { text: 'Icon Engine Guide', link: '/frontend/icon-engine-guide' },
+          ],
+        },
+        {
+          text: 'Data & State',
+          items: [
             { text: 'Server Data', link: '/frontend/server-data' },
             { text: 'API Guide', link: '/frontend/api-guide' },
             { text: 'Model Architecture', link: '/frontend/model-architecture' },
             { text: 'Model State Guide', link: '/frontend/model-state-guide' },
+          ],
+        },
+        {
+          text: 'API Contract & SDK',
+          items: [
             { text: 'OpenAPI SDK Guide', link: '/frontend/openapi-sdk-guide' },
             { text: 'API Schema Guide', link: '/frontend/api-schema-guide' },
             { text: 'SDK Guide', link: '/frontend/sdk-guide' },
+          ],
+        },
+        {
+          text: 'SSR',
+          items: [
             { text: 'SSR Overview', link: '/frontend/ssr-overview' },
             { text: 'SSR Init Data', link: '/frontend/ssr-init-data' },
             { text: 'SSR ClientOnly', link: '/frontend/ssr-client-only' },
             { text: 'SSR SEO Meta', link: '/frontend/ssr-seo-meta' },
             { text: 'SSR Env', link: '/frontend/ssr-env' },
-            { text: 'Design Principles', link: '/frontend/design-principles' },
           ],
         },
       ],
@@ -233,12 +332,7 @@ export default defineConfig({
           items: aiItems,
         },
       ],
-      '/reference/': [
-        {
-          text: 'Reference',
-          items: referenceItems,
-        },
-      ],
+      '/reference/': referenceGroups,
     },
     socialLinks: [{ icon: 'github', link: 'https://github.com/cabloy/cabloy' }],
     search: {

package/cabloy-docs/ai/introduction.md

@@ -23,6 +23,15 @@ The goal is to make AI **reuse the repo’s existing conventions directly**, esp
 - internal architecture notes
 - shared public documentation
 
+## How to approach AI work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
+2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
+3. use public docs for durable user-facing guidance and `.docs-internal/` for maintainer rationale
+4. encode repeatable behavior in Claude rules, commands, or skills instead of relying on unstated habits
+
 ## The knowledge layers
 
 ### Public docs
@@ -43,6 +52,41 @@ Use root `CLAUDE.md` and `.claude/commands/` for concise operational behavior an
 
 Use `.claude/skills/` for procedural workflows that benefit from reusable instructions, bundled references, or future deterministic scripts.
 
+## AI reading paths
+
+Use this page as the main AI-development hub, then choose the path that matches your task.
+
+### Repo workflow path
+
+Start here when the task is about choosing the right repo surface, docs location, or automation boundary:
+
+- [Repo Guidance](/ai/repo-guidance)
+- [Docs / Skills Mapping](/ai/docs-skills-rules-mapping)
+- [CLI to Skill Map](/ai/cli-to-skill-map)
+- [Skills](/ai/skills)
+- [Rules and Config](/ai/rules-and-config)
+
+### Framework implementation path
+
+Use this path when the task is about implementing or reviewing Cabloy code with repo-aware rules:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+- [Playbook: Backend Module](/ai/playbook-backend-module)
+- [Playbook: Frontend Page](/ai/playbook-frontend-page)
+- [Playbook: Contract Regeneration](/ai/playbook-contract-regeneration)
+- [Playbook: Metadata Refresh](/ai/playbook-metadata-refresh)
+
+### Verification and roadmap path
+
+Use this path when the task is about consistency checks, verification, or future workflow planning:
+
+- [Edition Detection](/ai/edition-detection)
+- [Edition Consistency Checklist](/ai/edition-consistency-checklist)
+- [Verification](/ai/verification)
+- [Future Skill Roadmap](/ai/future-skill-roadmap)
+- [CLI for Agents](/ai/cli-for-agents)
+
 ## Recommended AI lookup rules
 
 For backend shorthand lookup, prefer these surfaces in order:

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

@@ -105,6 +105,13 @@ return await this.scope.model.student.deleteById(id);
 
 These methods are also part of the generated CRUD thread; see [CRUD Workflow](/backend/crud-workflow).
 
+When using magic methods, keep one semantic detail in mind:
+
+- default `eq` methods can treat an omitted argument as `null`
+- non-`eq` methods require an explicit argument
+
+For omission inside structured `where` objects, prefer `Op.omit`; for SQL null checks, use `null`.
+
 ## Query-builder support
 
 Vona models are built on Knex, so the model layer also supports lower-level query builder access when needed.

package/cabloy-docs/backend/orm-mutation-guide.md

@@ -180,6 +180,16 @@ The important rule is:
 - the underlying write semantics still come from the standard ORM mutation surface
 - custom model methods take precedence when business-specific behavior is needed
 
+There is also a useful argument-handling rule to remember:
+
+- default `eq` magic methods such as `getByName()` or `selectByName()` treat an omitted argument as `null`
+- non-`eq` magic methods such as `getByNameEqI()` require an explicit value and throw if the argument is omitted
+
+This aligns magic-method behavior with the current ORM `where` semantics:
+
+- `Op.omit` means omit a condition explicitly
+- `null` means SQL `IS NULL`
+
 That means mutation should stay conceptually grounded in the standard model methods even when convenience wrappers are present.
 
 ## Implementation checks for ORM mutation changes

package/cabloy-docs/backend/orm-select-guide.md

@@ -110,7 +110,6 @@ The operator model is broad and includes examples like:
 - `_includes_`
 - case-insensitive variants
 - `_ref_`
-- `_skip_`
 
 That operator vocabulary is part of the Cabloy data language and should be reused consistently.
 
@@ -121,15 +120,17 @@ A practical operator-family reading is:
 - null checks: `_is_`, `_isNot_`
 - string matching: `_startsWith_`, `_endsWith_`, `_includes_`, and case-insensitive variants
 - composition/subquery: `_and_`, `_or_`, `_not_`, `_exists_`, `_notExists_`
-- identifier or composition helpers: `_ref_`, `_skip_`
+- identifier helper: `_ref_`
 
-### `_skip_`
+### Omitting a condition with `Op.omit`
 
-`_skip_` is especially useful when building query objects compositionally.
+Use `Op.omit` when you want to express omission explicitly at the call site. `Op.omit` is defined as `undefined`, but using the named constant makes the business meaning of the query object clearer.
 
 Representative pattern:
 
 ```typescript
+import { Op } from 'vona-module-a-orm';
+
 const where = {
   title: { _includes_: 'ai' },
   stars: { _gt_: 20 },
@@ -138,12 +139,12 @@ const where = {
 await this.scope.model.post.select({
   where: {
     ...where,
-    stars: '_skip_' as const,
+    stars: Op.omit,
   },
 });
 ```
 
-This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand.
+This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand, while `null` remains available for SQL `IS NULL` semantics.
 
 ## Joint operators and subqueries
 

package/cabloy-docs/backend/quickstart.md

@@ -16,14 +16,14 @@ Use this page when you are contributing backend work in the framework repository
 
 ## Prerequisites
 
-| Name       | Version   |
-| ---------- | --------- |
-| pnpm       | >=10.19.0 |
-| Node.js    | >=24.8.0  |
-| Redis      | >=7.2.6   |
-| Sqlite3    | Built-in  |
-| MySQL      | >=8       |
-| Postgresql | >=16      |
+| Name       | Version  |
+| ---------- | -------- |
+| pnpm       | >=11.5.2 |
+| Node.js    | >=24.8.0 |
+| Redis      | >=7.2.6  |
+| Sqlite3    | Built-in |
+| MySQL      | >=8      |
+| Postgresql | >=16     |
 
 Notes:
 
@@ -87,7 +87,7 @@ Legacy Vona docs described creating projects from templates such as `cabloy-basi
 That history still matters, because it explains why the Cabloy ecosystem now supports two editions:
 
 - **Cabloy Basic**: the public framework/reference edition, including the project route created by `npm create cabloy`, with a shared frontend engineering layer and a DaisyUI + Tailwind CSS oriented UI layer in the current public examples
-- **Cabloy Start**: the private commercial edition, accessed by cloning the licensed private repository source, with Vuetify-oriented frontend modules plus Start-specific SSR site baselines and project assets
+- **Cabloy Start**: the private commercial edition, accessed by cloning the licensed private repository source, with a Vuetify-oriented UI layer plus edition-specific SSR site baselines and project assets
 
 In the current monorepo docs, do not treat these as just template names. Treat them as edition boundaries that affect frontend integration, scripts, UI assumptions, and examples.