cabloy 5.1.115 → 5.1.117

package/.cabloy-version

@@ -1 +1 @@
-5.1.115
+5.1.117

package/.claude/skills/cabloy-contract-loop/SKILL.md

@@ -117,6 +117,7 @@ For deeper reference material, read:
 - `references/contract-loop-map.md`
 - `references/verification-checklist.md`
 - `references/resource-custom-state-pattern.md`
+- `../../../cabloy-docs/fullstack/admin-resource-and-web-self-service.md`
 
 ## Step 3: Identify the contract source of truth deliberately
 
@@ -237,9 +238,14 @@ After generation, inspect whether the frontend still needs follow-up in:
 Keep frontend follow-up thin:
 
 - use thin semantic model facades over generated consumers instead of re-declaring the contract
-- if a custom endpoint still belongs to an existing resource, prefer one resource-state owner instead of letting a module-local model create a second cache tree
+- if a custom endpoint still belongs to an existing Admin Resource state boundary, prefer one resource-state owner instead of letting a module-local model create a second cache tree
 
-Reuse the resource-owned custom state pattern in `references/resource-custom-state-pattern.md`.
+For one persisted domain with both Admin Resource and Web self-service consumers, choose the state boundary deliberately after backend contract truth and regeneration are established:
+
+- **Admin/custom-resource branch:** the endpoint remains part of the Admin Resource authority, projection, and generic page state, so reuse `rest-resource.model.resource` through a thin semantic facade.
+- **Separate Web self-service branch:** the consumer has different authority, server-derived owner scope, DTO projection, operation names, UX, or SSR behavior, so expose explicit self-service operations and use a dedicated Web model and purpose-built pages.
+
+Share domain persistence and lifecycle logic, not necessarily HTTP projections or frontend state ownership. Read `../../../cabloy-docs/fullstack/admin-resource-and-web-self-service.md` for the complete architecture. Reuse the resource-owned custom state pattern in `references/resource-custom-state-pattern.md` for the Admin/custom-resource branch.
 
 ## Step 6: Keep edition-aware differences explicit
 

package/.claude/skills/cabloy-contract-loop/evals/evals.json

@@ -24,6 +24,12 @@
       "prompt": "The frontend model and generated SDK in Cabloy Basic look stale after a backend response change, but I am not sure whether the real bug is in backend OpenAPI output or in skipped frontend regeneration. Diagnose the contract loop the Cabloy way.",
       "expected_output": "Handles reverse stale-consumer detection, checks backend source-of-truth first, avoids hand-patching frontend types as the primary fix, and proposes regeneration or backend correction based on the contract path.",
       "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "One persisted Order domain needs read-only Admin select/view operations through presetResource and customer Web list/detail reads. Should Admin and Web share one API and ModelResource, or should I use mine/viewMine-style Web operations and a separate Web model? Include the Cabloy contract-loop steps.",
+      "expected_output": "Keeps one domain and persistence boundary while separating Admin select/view and explicit owner-scoped Web operations with audience-specific DTOs. Keeps ModelResource as the Admin Resource owner and accepts a dedicated Web model/pages only for the distinct self-service state. Requires backend-first OpenAPI inspection, constrained regeneration for all owned operations, and verification of Admin authorization, Web owner scope before pagination, SSR admission where relevant, and both consumer paths. Rejects forcing Web through presetResource and rejects a parallel Admin cache owner for an ordinary custom Admin action.",
+      "files": []
     }
   ]
 }

package/.claude/skills/cabloy-contract-loop/references/contract-loop-map.md

@@ -92,6 +92,19 @@ Practical check after generation:
 - confirm the generated API files only contain the intended resource operations
 - confirm the module metadata and exports were not polluted by unrelated APIs
 
+### Dual-audience resource ownership
+
+One persisted domain may deliberately own both conventional Admin Resource operations and explicit Web self-service operations. Include every intended operation in the constrained `operations.match` slice; this remains one forward-chain contract, not competing generated contracts or consumer drift.
+
+After generation, choose the consumer shape by boundary:
+
+| Consumer | Generated-contract follow-up |
+| --- | --- |
+| Admin custom operation with the same authority, projection, and Resource page semantics | thin module facade → `rest-resource.model.resource` → schema-driven Resource UI |
+| Web self-service operation with different authority, server-derived owner scope, DTO projection, or page/SSR semantics | dedicated Web model → purpose-built self-service pages |
+
+The Web model is valid only for the separate self-service state domain. It must not become a parallel owner for Admin `select`/`view`, schemas, permissions, or generic Resource page state. See `../../../../cabloy-docs/fullstack/admin-resource-and-web-self-service.md` for the complete architecture.
+
 ## Forward chain artifact map
 
 1. backend contract source

package/.claude/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md

@@ -14,13 +14,13 @@ Typical examples:
 
 ## The ownership rule
 
-Prefer one owner for all resource-bound server state.
+Prefer one owner for all server state in the same Admin Resource boundary.
 
-In this codebase, the preferred owner is:
+In this codebase, the preferred Admin Resource owner is:
 
 - `rest-resource.model.resource`
 
-Do not let a module-local model become a second state owner for the same resource rows unless the boundary is explicitly intentional.
+Do not let a module-local model become a second state owner for the same Admin resource rows unless the boundary is explicitly intentional.
 
 ## The split to avoid
 
@@ -136,6 +136,19 @@ A separate owner may still be fine when the data is not really part of the resou
 
 Even then, be explicit about the boundary.
 
+## Admin Resource and Web self-service boundary
+
+A dedicated Web model is also valid when one persisted domain exposes a genuinely separate, customer-scoped self-service contract.
+
+Use that branch only when all of these are true:
+
+- the Web operations and DTOs are distinct from Admin `select`/`view` semantics;
+- the server derives owner scope from the authenticated user and preserves normal instance scope;
+- the Web model owns only its self-service query keys and purpose-built page state, not Admin Resource schemas, permissions, or generic page state;
+- Web UX or private SSR behavior needs a dedicated admission and post-hydration boundary.
+
+This does not justify a parallel owner for a custom Admin endpoint. It establishes a separate Web state domain beside the Admin Resource boundary. Read `../../../../cabloy-docs/fullstack/admin-resource-and-web-self-service.md` for the complete cross-stack pattern.
+
 ## Quick checklist
 
 1. confirm whether the resource pages already use `rest-resource.model.resource`

package/.claude/skills/cabloy-contract-loop/references/verification-checklist.md

@@ -21,6 +21,18 @@ After a contract-loop change, verify the branch that actually applies.
 - `npm run tsc`
 - `npm run build`
 
+### Dual-audience resource verification
+
+When one persisted domain has both Admin Resource and Web self-service consumers, also verify:
+
+- every intended Admin and Web operation appears in emitted OpenAPI and the constrained generated SDK slice
+- Admin controller authorization and the intended read-only or CRUD action surface remain independent of menu visibility
+- Web requests cannot choose owner or tenant scope; the service applies owner and visibility predicates before count, sorting, and pagination
+- Web DTOs omit owner, tenant, and operational-only fields
+- Admin custom state remains in `ModelResource`; a dedicated Web model owns only the distinct self-service cache domain
+- private Web SSR keeps a hydration-equivalent neutral shell until an explicit admission or post-hydration boundary
+- targeted Admin and authenticated Web flow checks cover both audiences when both contracts changed
+
 ## Reverse chain verification
 
 - frontend-owned source is correct

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

@@ -35,16 +35,12 @@ jobs:
       - name: init
         run: npm run init
       - name: run Commerce lifecycle gate
-        run: >-
-          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test --
-          commerce-trade/test/stockBalance.test.ts
-          commerce-trade/test/stockReservation.test.ts
-          commerce-trade/test/stockAudit.test.ts
-          commerce-promotion/test/couponReservation.test.ts
-          commerce-payment/test/paymentAttempt.test.ts
-          commerce-trade/test/checkoutReservation.test.ts
-          commerce-trade/test/reservationExpiry.test.ts
-          --flavor=normal
+        run: |
+          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test -- commerce-trade/test/stockBalance.test.ts commerce-trade/test/stockReservation.test.ts commerce-trade/test/stockAudit.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test -- commerce-promotion/test/couponReservation.test.ts commerce-payment/test/paymentAttempt.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test -- commerce-trade/test/checkoutReservation.test.ts commerce-trade/test/checkoutTransaction.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test -- commerce-trade/test/orderSnapshot.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run vona :bin:test -- commerce-trade/test/reservationExpiry.test.ts --flavor=normal
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run test
         working-directory: vona

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

@@ -35,16 +35,15 @@ jobs:
       - name: init
         run: npm run init
       - name: run Commerce stock contention gate
-        run: >-
-          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test --
-          commerce-trade/test/stockBalance.test.ts
-          commerce-trade/test/stockReservation.test.ts
-          commerce-trade/test/stockAudit.test.ts
-          commerce-promotion/test/couponReservation.test.ts
-          commerce-payment/test/paymentAttempt.test.ts
-          commerce-trade/test/checkoutReservation.test.ts
-          commerce-trade/test/reservationExpiry.test.ts
-          --flavor=normal
+        run: |
+          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/stockBalance.test.ts commerce-trade/test/stockReservation.test.ts commerce-trade/test/stockAudit.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-promotion/test/couponReservation.test.ts commerce-payment/test/paymentAttempt.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/checkoutReservation.test.ts commerce-trade/test/checkoutTransaction.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/orderSnapshot.test.ts --flavor=normal
+          DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/reservationExpiry.test.ts --flavor=normal
+        working-directory: vona
+      - name: run Commerce payment and shipment lifecycle gate
+        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts --flavor=normal
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=pg npm run test
         working-directory: vona

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

@@ -27,6 +27,9 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
+      - name: run Commerce payment and shipment lifecycle gate
+        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts --flavor=normal
+        working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run test
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run build -- --flavor=ci

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 5.1.117
+
+### Features
+
+- Add detailed CLI output.
+- Add telemetry support, including secure ingress propagation.
+- Add tracing capabilities.
+- Add Redis-backed rate limiting.
+- Add dual-audience resource guidance.
+
+### Bug Fixes
+
+- Fix REST module subpath bundle declarations.
+- Complete Commerce payment flow validation and evidence coverage.
+
+### Improvements
+
+- Simplify the Redis rate-limit command implementation.
+- Clarify the Vona AOP request path documentation.
+- Update dependency lockfiles and package metadata.
+
+## 5.1.116
+
+### Features
+
+- Update platform capabilities and integrations.
+
+### Bug Fixes
+
+- Stabilize Commerce trade transactions and associated tests.
+
+### Improvements
+
+- Update address ownership test coverage.
+
 ## 5.1.115
 
 ### Improvements

package/CLAUDE.md

@@ -46,6 +46,7 @@ Before inventing a custom implementation path:
 - Treat contract-loop work as one of four branches: forward chain, reverse chain, consumer drift, or local dependency drift.
 - For the forward chain, change backend contract truth first and regenerate frontend consumers rather than hand-patching them.
 - After forward regeneration, keep frontend follow-up thin: prefer semantic model facades and reuse the existing resource-owner when the custom API still belongs to the same resource.
+- When one persisted business resource serves both Admin Resource and Web self-service consumers, keep one domain and persistence boundary; where audience authority or experience differs, split API/DTO contracts, server-side scope, frontend state ownership, and page architecture—reuse the generic Resource owner for Admin and use dedicated state/pages for a genuinely distinct Web self-service contract.
 - For the reverse chain, always run the relevant Zova build first, then run `npm run deps:vona`: use `npm run build:zova:admin` for Admin changes, and also run `npm run build:zova:web` when the Web flavor is affected. Do not treat `build:rest:*` alone as sufficient, because the SSR bundle and rest output must move together.
 - If the generated `.zova-rest` artifacts already contain the expected changes but Vona consumers still see stale types after `npm run deps:vona`, treat it as local dependency drift: delete `vona/node_modules` and reinstall dependencies before further debugging or hand-patching dependency links.
 - For Cabloy Start, apply the same reverse-chain logic but resolve the Start-specific flavor names and generated-output paths from the active Start repo before recommending commands.
@@ -57,6 +58,7 @@ Before inventing a custom implementation path:
 - Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
 - In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
+- Do not modify `APP_NAME` in environment files unless the user explicitly requests it. When another worktree holds shared test resources, wait and retry later rather than changing application identity or related environment settings.
 - 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.

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

@@ -88,6 +88,10 @@ const fullstackGroups = [
       { text: 'Framework Performance', link: '/fullstack/framework-performance' },
       { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
       { text: 'Contract Loop Playbook', link: '/fullstack/contract-loop-playbook' },
+      {
+        text: 'Admin Resource and Web Self-Service',
+        link: '/fullstack/admin-resource-and-web-self-service',
+      },
       {
         text: 'Backend Metadata to Frontend Table Actions',
         link: '/fullstack/backend-metadata-to-frontend-table-actions',
@@ -225,6 +229,7 @@ export default defineConfig({
           items: [
             { text: 'Auth Guide', link: '/backend/auth-guide' },
             { text: 'Captcha Guide', link: '/backend/captcha-guide' },
+            { text: 'Rate Limit Guide', link: '/backend/rate-limit-guide' },
             { text: 'User Access Guide', link: '/backend/user-access-guide' },
             { text: 'JWT Guide', link: '/backend/jwt-guide' },
             { text: 'Validation Guide', link: '/backend/validation-guide' },
@@ -238,6 +243,7 @@ export default defineConfig({
             { text: 'Error Guide', link: '/backend/error-guide' },
             { text: 'Event Guide', link: '/backend/event-guide' },
             { text: 'Logger Guide', link: '/backend/logger-guide' },
+            { text: 'Telemetry Guide', link: '/backend/telemetry-guide' },
             { text: 'Upload Guide', link: '/backend/upload-guide' },
             { text: 'Image Guide', link: '/backend/image-guide' },
             { text: 'File Guide', link: '/backend/file-guide' },

package/cabloy-docs/ai/docs-skills-rules-mapping.md

@@ -143,6 +143,13 @@ Use this quick rule:
 - full explanation → [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - workflow steering → skill and rules can point to the docs and choose the right CLI path
 
+### Example: “How should one persisted resource serve Admin and Web users?”
+
+- full architecture explanation → [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service)
+- concise repo-wide default → `CLAUDE.md`
+- contract regeneration, consumer-boundary choice, and verification routing → `cabloy-contract-loop`
+- extend the existing contract-loop skill references and evals; do not create an Order-specific skill
+
 ### Example: “How should AI remove an existing module cleanly?”
 
 - public operational explanation → [Playbook: Module Removal](/ai/playbook-module-removal)

package/cabloy-docs/backend/aop-overview.md

@@ -28,39 +28,31 @@ These families work together to shape request execution, parameter handling, err
 
 ## Execution model
 
-Two controller AOP families use an onion-style execution model:
+Middleware and interceptors use onion-style execution: they can run logic before `next()` and after downstream controller work returns. Guards check access preconditions, pipes transform or validate request values, and filters handle exceptions on the error path.
 
-- **middleware**
-- **interceptor**
-
-That means they can run logic both before and after the controller action.
-
-Other controller AOP families participate in more specialized stages:
-
-- **guard** checks access or execution preconditions
-- **pipe** transforms or validates request values
-- **filter** handles exceptions and logging behavior
+For a matched controller route, the inbound order is:
 
-A practical controller-path mental model is:
+1. **system middleware** before route matching
+2. **route matching**
+3. **global middleware** after a route matches and before authentication
+4. **guards**, including Passport authentication and authorization
+5. **interceptors**
+6. **argument extraction and pipes**
+7. **local middleware**
+8. **controller action**
 
-1. system middleware runs before route matching
-2. route matching happens
-3. global and local middleware wrap the matched route
-4. guards enforce access preconditions
-5. pipes transform and validate incoming values
-6. interceptors wrap controller execution
-7. the controller action runs
-8. filters handle thrown exceptions and logging customization when failures occur
+After the action, middleware and interceptor after-`next()` work unwinds in reverse: local middleware, interceptors, then global middleware. Filters are not another successful inbound stage; they compose the exception-handling path when request execution throws.
 
-That model is the fastest way to decide which aspect family should own a change.
+Choose the family by the state the concern needs: use system middleware for route-independent transport behavior, global middleware for matched-route work before authentication, a global interceptor for post-auth admission before body parsing, and local middleware for action-side wrapping after pipes.
 
 ## System, global, and local scope
 
 Controller AOP also varies by scope:
 
-- **system** middleware runs before route matching
-- **global** aspects are auto-loaded and can be applied broadly with runtime filters such as `match`, `ignore`, `mode`, or `flavor`
-- **local** aspects are attached directly to a controller class or action
+- **system middleware** runs before route matching and has no matched-route metadata
+- **global middleware** is auto-loaded after route matching but before guards; it can use runtime filters such as `match`, `ignore`, `mode`, or `flavor`
+- **local middleware** is attached directly to a controller class or action and runs after pipes, immediately around the action-side suffix
+- **global/local guards, interceptors, pipes, and filters** remain in their own family stages rather than sharing middleware placement
 
 Built-in aspects and shorthand decorators sit on top of the same general model.
 

package/cabloy-docs/backend/backend-source-reading-roadmap.md

@@ -77,6 +77,30 @@ Start here when your question is about:
 - if the question is “which scripts drive normal backend dev/build/start/test workflows?” -> read [Backend Scripts](/backend/scripts)
 - if the question is “which source files should I open first?” -> read [Vona Source Reading Map](/backend/vona-source-reading-map)
 
+## Topic cluster: controller request path and controller AOP
+
+Start here when your question is about:
+
+- what runs before route matching, after route matching, or after Passport authentication
+- whether a concern belongs in system/global/local middleware, a guard, an interceptor, a pipe, or a filter
+- why a global-onion decorator configures a route without changing its execution stage
+- how controller/action options merge with application, instance, and dynamic onion configuration
+- why an error is transformed or logged through filters
+
+### Concept pages first
+
+- [AOP Overview](/backend/aop-overview)
+- [Controller Guide](/backend/controller-guide)
+- [Controller AOP Guide](/backend/controller-aop-guide)
+- [Rate Limit Guide](/backend/rate-limit-guide) when request admission or quotas are involved
+
+### Best next step
+
+- if the question is “how can this run before route matching?” -> read the system-middleware path in [Vona Source Reading Map](/backend/vona-source-reading-map)
+- if the question is “does this run before or after Passport?” -> read the controller request pipeline path in [Vona Source Reading Map](/backend/vona-source-reading-map)
+- if the question is “why does a route override retain other settings?” -> trace onion option composition in [Vona Source Reading Map](/backend/vona-source-reading-map)
+- if the question is “why is an error transformed or logged?” -> follow the filter error-path follow-up in [Vona Source Reading Map](/backend/vona-source-reading-map)
+
 ## Topic cluster: resource and module CRUD chain
 
 Start here when your question is about:
@@ -110,11 +134,11 @@ It does **not** try to become the new entry page for every backend subsystem suc
 - workers
 - queues
 - websockets
-- auth
+- the complete auth subsystem
 - cache
 - distributed runtime internals
 
-Those topics already have their own concept docs. This roadmap is only the first navigation layer for common source-reading tasks.
+The controller request-path cluster covers where guards and Passport sit in route execution, not the complete authentication subsystem. Those topics already have their own concept docs. This roadmap is only the first navigation layer for common source-reading tasks.
 
 ## Final rule
 

package/cabloy-docs/backend/controller-aop-guide.md

@@ -32,15 +32,25 @@ These commands all go through the shared `:create:bean` entrypoint, but they tar
 
 ### Scope variants
 
-- **system middleware** runs before route matching
-- **global middleware** is auto-loaded and applied broadly
-- **local middleware** is attached directly to a controller class or action
+- **system middleware** runs before route matching and has no matched-route metadata
+- **global middleware** is auto-loaded after a route matches but before guards and Passport authentication
+- **local middleware** is attached directly to a controller class or action and runs after pipes, around the action-side suffix
+
+### Inbound execution order
+
+For a matched controller route, Vona enters these stages in order:
+
+```text
+system middleware → route matching → global middleware → guard → interceptor → pipe → local middleware → action
+```
+
+Middleware and interceptors use onion execution. Their after-`next()` work unwinds in reverse, so local middleware returns before interceptors, which return before global middleware. Filters are selected from the error path when request execution throws; they are not a normal inbound stage.
 
 ### Why system middleware is different
 
 System middleware executes before route matching, so it is the earliest controller-facing interception stage.
 
-This is where Vona places concerns such as not-found handling, request override behavior, app initialization, instance initialization, HTTP logging, CORS, and static-resource handling.
+This is where Vona places concerns such as not-found handling, request override behavior, app initialization, instance initialization, HTTP logging, CORS, and static-resource handling. Use global middleware instead when the concern needs a matched route but must still run before authentication. Use local middleware when the concern is controller/action-specific and should see pipe-processed arguments.
 
 ### Representative local usage
 
@@ -54,6 +64,8 @@ This is where Vona places concerns such as not-found handling, request override
 @Aspect.middlewareGlobal('training-student:logger', { prefix: 'elapsed' })
 ```
 
+`@Aspect.middlewareGlobal(...)` writes route options for an already registered global middleware. It does not add a local middleware or change that middleware’s pre-guard execution stage. The same distinction applies to `@Aspect.interceptorGlobal(...)`: it configures an existing global interceptor for the controller/action while the interceptor remains in the post-guard stage.
+
 ### Representative built-in usage
 
 ```typescript
@@ -125,8 +137,10 @@ Typical jobs include:
 
 ### Scope variants
 
-- **global interceptor** is auto-loaded and broadly configurable
-- **local interceptor** is attached directly to a controller class or action
+- **global interceptor** is auto-loaded after guards and before pipes, local middleware, and controller execution
+- **local interceptor** is attached directly to a controller class or action, runs inside global interceptors, and still precedes pipes
+
+A global interceptor is the correct placement for post-auth admission that must reject before body parsing. For example, [`a-ratelimit:rateLimit`](/backend/rate-limit-guide) uses Passport-resolved identity, then runs before the request-body interceptor, pipes, local middleware, and action code.
 
 ### Representative local usage
 
@@ -140,7 +154,7 @@ Built-in interceptors can be used for framework-level response behavior, such as
 
 ## Pipe
 
-Pipes transform or validate request values before they reach controller logic.
+Pipes transform or validate request values after interceptor entry and before local middleware and controller logic.
 
 ### Scope variants
 
@@ -190,7 +204,7 @@ For broader validation guidance, see [Validation Guide](/backend/validation-guid
 
 ## Filter
 
-Filters handle exceptions and logging behavior.
+Filters handle exceptions and logging behavior on the error path. They are selected when request execution throws, rather than forming another successful inbound stage after the action.
 
 This is where request-path error customization becomes explicit.
 
@@ -230,15 +244,25 @@ Most controller aspect families support the same configuration ideas:
 
 That consistency is one of the most important reasons controller AOP stays scalable in Vona.
 
-### Representative precedence model
+### Global-onion override and option ownership
+
+A local use decorator such as `@Aspect.interceptor(...)` adds an onion to the local execution chain. A global use decorator such as `@Aspect.interceptorGlobal(...)` or `@Core.rateLimit(...)` instead writes controller/action route options for the named, already-global onion. It does not move that onion into a local stage.
+
+Put concern-specific fields under the exact onion that consumes them. For example, `rateLimit` belongs to `a-ratelimit:rateLimit` options; putting that object in another middleware or interceptor’s options does not transfer the quota policy or activate the limiter.
 
-A representative precedence pattern is:
+### Effective option precedence
 
-- usage-site override
-- then app-config override in `config.onions`
-- then decorator default values
+For normal object-valued onion options, lower-precedence values are deep-merged with later values in this order:
+
+```text
+aspect defaults and application config.onions
+→ active-instance config.onions
+→ controller route options
+→ action route options
+→ controlled dynamic request or test overrides
+```
 
-For example, global middleware can define defaults in the bean, be overridden in app config, and then be overridden again at a specific controller action.
+An action can therefore override only `rateLimit.limit` and inherit the rest of the controller or application policy. An action `enable: false` is an explicit exemption from a globally or controller-enabled onion. Primitive option scenes use the highest-precedence value instead of deep merging.
 
 ### Representative inspect patterns
 

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

@@ -210,6 +210,7 @@ Logging is closely connected to:
 
 - [Internal AOP Guide](/backend/internal-aop-guide) through built-in AOP helpers such as `@Core.log(...)`
 - [Runtime and Flavors](/backend/runtime-and-flavors) because log location, level, and operational behavior often vary by environment
+- [Telemetry Guide](/backend/telemetry-guide) for distributed trace and span correlation in log entries; continue to use `$logger` and `$loggerChild(...)` as the logging APIs
 
 ## Implementation checks for backend logging changes
 

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

@@ -73,7 +73,7 @@ In the current repo implementation, the out-of-the-box menu controller is public
 - Omit `roles`, or use `roles: []`, to make an item visible to anonymous and authenticated callers.
 - A nonempty `roles` array is visible when the current Passport has at least one matching role name.
 - `roles` is server-only declaration metadata. It is filtered out before the API response and is not part of `IMenuItem`, OpenAPI, or generated frontend clients.
-- This controls navigation disclosure only. It never grants access to a page, controller action, API, or resource; those boundaries retain their own route and Passport/permission guards.
+- This controls navigation disclosure only. It never grants access to a page, controller action, API, or resource; those boundaries retain their own route and Passport/permission guards. For the fullstack pattern that pairs an Admin `presetResource` entry with independently authorized Admin APIs and separately scoped Web self-service APIs, see [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service).
 
 SSR Site menu definitions are cached structurally by Site and locale. The framework keeps static role policy in that prepared cache, then creates a filtered response for each request without mutating the cached definition.
 

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

@@ -29,6 +29,32 @@ await this.scope.model.post.delete({ id: 1 });
 
 These operations are the clearest fit when the caller already knows the exact write intent.
 
+## Field presence in insert and update
+
+For normal writable fields, insert and update intentionally interpret field presence differently:
+
+| Field state                | `insert`                                           | `update`                         |
+| -------------------------- | -------------------------------------------------- | -------------------------------- |
+| Field is absent            | Leave the column to normal insert/default behavior | Leave the stored value unchanged |
+| Own field with `undefined` | Leave the column to normal insert/default behavior | Write SQL `NULL`                 |
+| `null`                     | Write SQL `NULL`                                   | Write SQL `NULL`                 |
+
+An own `undefined` means the property exists on the JavaScript object but its value is `undefined`, such as `{ title: undefined }`. This lets an update distinguish an omitted field from an intentional clear:
+
+```typescript
+await this.scope.model.post.update({
+  id,
+  title: undefined, // write SQL NULL
+  // stars is absent, so its stored value is unchanged
+});
+```
+
+### JSON columns
+
+JSON columns follow the same field-presence rules. Non-null values are persisted as JSON. An explicit `null` writes SQL `NULL`, not a JSON literal `null`. On update, an own `undefined` also clears the column to SQL `NULL`.
+
+A JSON request body normally omits object properties whose value is `undefined`. This distinction therefore most often applies to in-process TypeScript model calls or server-side payload construction.
+
 ## Conditional update and delete paths
 
 Write operations do not have to target one row only by primary key.
@@ -56,7 +82,7 @@ await this.scope.model.post.delete({
 });
 ```
 
-That matters because the mutation layer still participates in the same structured query language used by select operations.
+That matters because the mutation layer still participates in the same structured query language used by select operations. In `options.where`, an absent field, an own `undefined`, and `Op.omit` all omit that condition; `null` requests SQL `IS NULL`. See [ORM Select Guide](/backend/orm-select-guide#absent-undefined-and-null-in-where) for the detailed query contract.
 
 ## Bulk mutation operations
 
@@ -87,9 +113,12 @@ Instead of forcing callers to choose insert/update/delete up front, Vona can inf
 
 Representative logic:
 
-- no `id` → insert
-- `id` present → update
-- `id` present and `deleted: true` → delete
+- `id` absent, `undefined`, or `null` → insert
+- non-nullish `id` → update
+- non-nullish `id` and `deleted: true` → delete
+- `deleted: true` without a non-nullish `id` → ignore the item because no deletion target exists
+
+A non-nullish identity is neither `null` nor `undefined`. `mutate` chooses by that usable identity value, not merely by whether the `id` key exists.
 
 Representative pattern:
 
@@ -182,13 +211,10 @@ The important rule is:
 
 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:
+- default `eq` magic methods such as `getByName()` or `selectByName()` treat an omitted or `undefined` argument as `null`
+- non-`eq` magic methods such as `getByNameEqI()` require a concrete value and throw when the argument is omitted or `undefined`
 
-- `Op.omit` means omit a condition explicitly
-- `null` means SQL `IS NULL`
+This is argument adaptation performed by the convenience method. It differs from a direct structured `where` object, where `{ name: undefined }` omits the condition. Use `Op.omit` to make direct condition omission explicit, and use `null` to request SQL `IS NULL`.
 
 That means mutation should stay conceptually grounded in the standard model methods even when convenience wrappers are present.