cabloy 5.1.131 → 5.1.133

package/.cabloy-version

@@ -1 +1 @@
-5.1.131
+5.1.133

package/.claude/skills/cabloy-worktree-environment/SKILL.md

@@ -44,7 +44,7 @@ After validation, immediately generate the standard core tuple. Do not ask which
 
 For user-facing summaries, write exactly:
 
-> 环境隔离信息：Vona 开发 + Zova 开发
+> Environment isolation: Vona development + Zova development
 
 Admin and Web use this same Zova environment. The user may later run either frontend command, but must not run both concurrently in one worktree. Use another linked worktree for concurrent development of the other flavor. Do not create a flavor-specific local override.
 
@@ -52,11 +52,11 @@ Admin and Web use this same Zova environment. The user may later run either fron
 
 Recommendation generation uses Git worktree metadata and the fixed constants below only. It must not inspect any `.env`, `.env.local`, `.env.*.local`, sibling worktree configuration, process environment, listener table, `lsof` output, process command line, or external service. Do not use `Read`, `cat`, `grep`, `source`, `dotenv`, `printenv`, `env`, or diagnostics that expose env-file content for this workflow.
 
-This means the proposal is deterministic convenience, not a live port reservation. If an application later reports a port collision, the user may say **“再换一批”** before setup or create another linked worktree; the actual application bind remains authoritative.
+This means the proposal is deterministic convenience, not a live port reservation. If an application later reports a port collision, the user may say **“Try another batch”** before setup or create another linked worktree; the actual application bind remains authoritative.
 
 ### Deterministic proposal
 
-Treat the primary checkout as ordinal `0`. From the validated `git worktree list --porcelain -z` order, assign each linked worktree the next ordinal: the first linked worktree is `1`, the second is `2`, and so on. Let `batch` be `0` for the first proposal, and increase it only when the user says **“再换一批”**.
+Treat the primary checkout as ordinal `0`. From the validated `git worktree list --porcelain -z` order, assign each linked worktree the next ordinal: the first linked worktree is `1`, the second is `2`, and so on. Let `batch` be `0` for the first proposal, and increase it only when the user says **“Try another batch”**.
 
 Use one shared offset for every generated listener:
 
@@ -92,7 +92,7 @@ DEV_SERVER_HMR_PORT = <24679 + offset>
 
 All generated listener ports must be integers from `1` through `65535` and distinct within the tuple. If a batch would exceed that range, stop and require a different linked-worktree arrangement.
 
-When the user says **“再换一批”**, set `batch = batch + 1`, recompute the entire tuple, and show it again. Every recommended listener advances by exactly `+1`, and `API_BASE_URL` is regenerated from the new Vona port. Do not write during a batch change. This deterministic setup does not accept user-substituted values.
+When the user says **“Try another batch”**, set `batch = batch + 1`, recompute the entire tuple, and show it again. Every recommended listener advances by exactly `+1`, and `API_BASE_URL` is regenerated from the new Vona port. Do not write during a batch change. This deterministic setup does not accept user-substituted values.
 
 A unique `APP_NAME` separates ordinary framework-managed test database names and framework Redis prefixes. It does not isolate explicitly named databases, unprefixed custom Redis keys, mail, payment, webhooks, object storage, or other external services. Require a separate explicit design before claiming that any of those resources are isolated.
 
@@ -100,7 +100,7 @@ A unique `APP_NAME` separates ordinary framework-managed test database names and
 
 Before making any edit:
 
-1. show `环境隔离信息：Vona 开发 + Zova 开发`, the worktree ordinal, batch, and exact non-secret identity/port tuple
+1. show `Environment isolation: Vona development + Zova development`, the worktree ordinal, batch, and exact non-secret identity/port tuple
 2. show a file-by-file preview containing only the managed assignments that will be written to both broad local files
 3. run one independent `git check-ignore -v -- "$target"` command for each target and require each command to succeed with a matching ignore rule
 4. recheck current root, linked-worktree identity, edition, ordinal, generated port range, tuple uniqueness, and both target states
@@ -199,7 +199,7 @@ git status --short
 When this skill completes a stage, report:
 
 1. validated worktree root and detected edition
-2. `环境隔离信息：Vona 开发 + Zova 开发`
+2. `Environment isolation: Vona development + Zova development`
 3. worktree ordinal, batch, and generated non-secret identity/ports
 4. both exact broad local files proposed or changed
 5. the privacy boundary and external resources that still require separate isolation

package/.claude/skills/cabloy-worktree-environment/evals/evals.json

@@ -4,7 +4,7 @@
     {
       "id": 1,
       "prompt": "I explicitly invoke /cabloy-worktree-environment in the first linked Cabloy Basic worktree. Configure the local environment.",
-      "expected_output": "Validates that the current checkout is a linked Cabloy Basic worktree before any write. Without asking which processes or frontend flavor will run, it uses Git worktree metadata only and recommends APP_NAME from the worktree basename, SERVER_LISTEN_PORT 7103, DEV_SERVER_PORT 9001, DEV_SERVER_HMR_PORT 24680, and API_BASE_URL http://localhost:7103. It labels the configuration as 环境隔离信息：Vona 开发 + Zova 开发, previews both vona/env/.env.local and zova/env/.env.local, waits for final confirmation before writing, and separately asks whether to run npm run init after success.",
+      "expected_output": "Validates that the current checkout is a linked Cabloy Basic worktree before any write. Without asking which processes or frontend flavor will run, it uses Git worktree metadata only and recommends APP_NAME from the worktree basename, SERVER_LISTEN_PORT 7103, DEV_SERVER_PORT 9001, DEV_SERVER_HMR_PORT 24680, and API_BASE_URL http://localhost:7103. It labels the configuration as Environment isolation: Vona development + Zova development, previews both vona/env/.env.local and zova/env/.env.local, waits for final confirmation before writing, and separately asks whether to run npm run init after success.",
       "files": []
     },
     {
@@ -45,7 +45,7 @@
     },
     {
       "id": 8,
-      "prompt": "I explicitly invoke /cabloy-worktree-environment in the first linked Cabloy Basic worktree. The initial proposal is 7103, 9001, and 24680. 再换一批。",
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in the first linked Cabloy Basic worktree. The initial proposal is 7103, 9001, and 24680. Try another batch.",
       "expected_output": "Keeps the same worktree APP_NAME, increases the shared batch by one, and proposes SERVER_LISTEN_PORT 7104, DEV_SERVER_PORT 9002, DEV_SERVER_HMR_PORT 24681, and API_BASE_URL http://localhost:7104. It does not write, inspect ports, inspect environment files, or treat either batch as reserved before final confirmation.",
       "files": []
     },

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

@@ -35,7 +35,7 @@ jobs:
       - name: init
         run: npm run init
       - name: run A-Pay focused gate
-        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
+        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
         working-directory: vona
       - name: run Commerce stock contention gate
         run: |

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

@@ -28,7 +28,7 @@ jobs:
       - name: init
         run: npm run init
       - name: run A-Pay focused gate
-        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
+        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
         working-directory: vona
       - name: run Commerce payment, shipment, and refund 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 commerce-trade/test/refundLifecycle.test.ts --flavor=normal

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 5.1.133
+
+### Features
+
+- Add SSR profiles for core and commerce applications.
+- Add payment UUIDs, refund support, and refunded-payment handling.
+- Add administrative semantic presentations for addresses, orders, stock, and SKUs.
+- Add payment capabilities and PayPal payment lifecycle coverage.
+- Add SSR site title support and a home-page base.
+- Preserve DTO OpenAPI schema scenarios.
+- Add custom Zod error handling.
+- Ensure passport availability for authenticated flows.
+
+### Bug Fixes
+
+- Preserve SSR locale cookie typings.
+- Harden PayPal refund recovery.
+
+### Improvements
+
+- Upgrade Lerna to v10.
+
+## 5.1.132
+
+### Features
+
+- Update functionality.
+
 ## 5.1.131
 
 ### Features

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

@@ -73,11 +73,13 @@ class DtoStudentCreate {
 }
 ```
 
-When mixing helper metadata and an explicit zod schema in `@Api.field(...)`, apply the same ordering rule used by entities:
+When mixing helper metadata and a structure-defining schema-like argument in `@Api.field(...)`, apply the same ordering rule used by entities:
 
-- place `z.xxx(...)` as the **last argument** because it returns the zod schema instance
-- keep helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
-- otherwise helpers written after the zod schema may stop taking effect
+- place the final structure-defining argument, such as `z.xxx(...)`, `v.object(...)`, or `v.array(...)`, **last**
+- keep helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before it
+- optionality, nullability, defaults, and preprocess/transform wrappers are also structure-shaping; do not assume their order is interchangeable
+
+Framework DTO composition preserves inherited OpenAPI metadata, but that preservation does not make structure-shaping schema-like composition order-independent. Verify emitted schema/OpenAPI output after changing those arguments.
 
 For query-oriented DTOs, another important distinction is optional vs nullable:
 
@@ -86,6 +88,39 @@ For query-oriented DTOs, another important distinction is optional vs nullable:
 
 That becomes especially important for DTO query filters. A field declared with `v.optional(), v.nullable()` can preserve real `null` through query parsing so the downstream ORM filter can express SQL `IS NULL` instead of silently treating the value as omitted.
 
+## DTO schema scenes
+
+A DTO can declare the contract scene that its schema represents:
+
+```typescript
+@Dto({
+  schemaScene: 'filter',
+  fields: {
+    status: $makeSchema(v.optional(), z.string()),
+  },
+})
+export class DtoOrderFilter extends $Dto.query(EntityOrder, ['status']) {}
+```
+
+The shared scene vocabulary is:
+
+- `table`
+- `form`
+- `form-view`
+- `form-create`
+- `filter`
+
+`schemaScene` is emitted through Cabloy's `rest.schemaScene` OpenAPI extension metadata. It is not a standard OpenAPI field. The same metadata can therefore guide Vona request validation and Zova schema-driven consumers.
+
+The inferred mutation helpers already declare the usual write intent:
+
+- `$Dto.create(...)` uses `form-create`
+- `$Dto.update(...)` uses `form`
+
+Use `@Dto({ schemaScene })` when a named DTO has a deliberately different request-contract scene. Do not restate the normal create or update scene only because a DTO wraps one of those helpers.
+
+Choose the scene from the API contract, not from the particular screen that happens to call it. A scene does not decide which fields the DTO contains: use `$Dto.*`, `columns`, `include`, and `dtoClass` to define the supported projection first. For the inferred authoring sequence, see [DTO Infer and Generation](/backend/dto-infer-generation); for scene-aware write handling, see [Validation Guide](/backend/validation-guide) and [OpenAPI Guide](/backend/openapi-guide).
+
 ## DTO options
 
 Three especially important DTO option areas are:

package/cabloy-docs/backend/dto-infer-generation.md

@@ -191,6 +191,8 @@ export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [
 
 `$makeSchema(...)` applies schema-like arguments right-to-left. Keep the final structure-defining schema, such as `z.string()`, `z.number()`, `v.object(...)`, or `v.array(...)`, last in authoring order. Treat optionality, nullability, defaults, preprocess/transform wrappers, objects, and arrays as structure-shaping rather than metadata-only, and verify emitted schema/OpenAPI output after changing them.
 
+Framework DTO composition preserves inherited OpenAPI metadata when a field schema is refined. That includes metadata such as titles, render information, and scene identity. It does **not** make structure-shaping schema-like arguments order-independent: keep the final structure-defining argument last and verify the effective schema rather than assuming a metadata merge can repair a reordered schema.
+
 `@Dto({ fields })` changes the runtime contract and metadata. It does not rewrite the TypeScript property type inferred from the `$Dto.*` base class. Do not add a duplicate `declare` field or a second field decorator solely to mirror a runtime schema restriction unless a separate static contract is genuinely required and is type-compatible with the inferred base.
 
 ### Layer 3: add contract-only fields
@@ -244,6 +246,33 @@ Representative source facts:
 
 These are good examples of **named DTO classes that wrap inference**.
 
+The mutation helpers also carry their conventional schema-scene identity into the DTO's Cabloy OpenAPI metadata:
+
+| Helper             | Effective schema scene | Practical effect                                                    |
+| ------------------ | ---------------------- | ------------------------------------------------------------------- |
+| `$Dto.create(...)` | `form-create`          | Create-specific field metadata applies after the shared form layer. |
+| `$Dto.update(...)` | `form`                 | Shared form field metadata applies directly.                        |
+
+For `form-view`, `form-create`, and `filter`, field metadata resolves in this order: base `rest`, then the shared `rest.form` overlay, then the exact scene overlay. `table` has no shared-form overlay. For example, a field can remain read-only in normal form contracts while being enabled specifically for creation:
+
+```typescript
+@Dto({
+  fields: {
+    referenceNo: $makeMetadata(
+      v.openapi({
+        rest: {
+          'form': { readonly: true },
+          'form-create': { readonly: false },
+        },
+      }),
+    ),
+  },
+})
+export class DtoOrderCreate extends $Dto.create(() => ModelOrder) {}
+```
+
+The effective `form-create` rule makes `referenceNo` writable for this create contract. An update DTO using the shared `form` scene keeps it read-only unless its own scene metadata changes that result. DTO options such as `fields`, `blocks`, `openapi`, and `schemaScene` merge with metadata supplied by inferred helpers or inheritance; they do not erase the helper-provided scene identity.
+
 Why this is a good fit:
 
 - the contracts are operation-specific and worth naming

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

@@ -60,6 +60,22 @@ That means:
 
 This tight linkage is one of the reasons the Cabloy contract story can stay productive at scale.
 
+## Schema scenes are Cabloy contract metadata
+
+A DTO can emit its semantic schema scene through Cabloy's `rest.schemaScene` extension metadata. The scene vocabulary is `table`, `form`, `form-view`, `form-create`, and `filter`. This is Cabloy metadata carried by the emitted schema, not a field defined by the OpenAPI specification itself.
+
+The same emitted metadata has coordinated but distinct consumers:
+
+| Consumer                 | Responsibility                                                                                           |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| Vona validation          | Resolves a field's effective scene metadata and removes read-only properties from validated write input. |
+| OpenAPI emission         | Carries DTO and field scene metadata through the backend contract.                                       |
+| Zova schema/form runtime | Applies shared-form and exact-scene property overlays while loading fields for the active schema scene.  |
+
+For the form-derived scenes `form-view`, `form-create`, and `filter`, a field's base `rest` metadata is followed by the shared `rest.form` overlay and then the exact scene overlay. This lets one contract describe common form behavior while still declaring a create- or filter-specific exception.
+
+The end-to-end rule is therefore not “the frontend hides a field.” Vona uses the DTO contract to sanitize read-only request input, while Zova uses compatible metadata to render the relevant scene. See [DTO Guide](/backend/dto-guide) for declaring a DTO scene, [Validation Guide](/backend/validation-guide) for server-side readonly handling, [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood) for Zova schema loading, and [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) for frontend form-scene flow.
+
 ## Controllers, DTOs, entities, and examples all contribute
 
 OpenAPI output is not owned by one layer only.

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

@@ -44,6 +44,49 @@ Inferred schemas can also be extended through helper tools like:
 
 That is important because many real validation cases need augmentation rather than total replacement.
 
+## Scene-aware readonly input sanitization
+
+DTO and field OpenAPI metadata can identify a Cabloy schema scene and its scene-specific field behavior. After a schema parses successfully, Vona removes each known property whose **effective** `rest` metadata resolves to `readonly: true` for that scene.
+
+This is server-side input sanitization, not a browser-only disabled control and not a validation error. A caller cannot turn a read-only field into a write channel by bypassing a Zova form.
+
+For `form-view`, `form-create`, and `filter`, Vona resolves field metadata in this order:
+
+1. base `rest` metadata
+2. shared `rest.form` metadata
+3. the exact scene metadata, such as `rest['form-create']`
+
+For `table` and `form`, only the base metadata and exact-scene metadata apply. A nested DTO inherits the containing scene unless it declares its own `rest.schemaScene`.
+
+The sanitization traverses nested DTO/object values and array elements, including framework lazy and chained schema composition. For example, a create request can prevent callers from supplying a line-item price while still accepting its quantity:
+
+```typescript
+class DtoLineItem {
+  @Api.field(v.openapi({ rest: { form: { readonly: true } } }))
+  price: number;
+
+  @Api.field()
+  quantity: number;
+}
+
+export class DtoOrderCreate extends $Dto.create(() => ModelOrder) {
+  @Api.field(v.array(DtoLineItem))
+  items: DtoLineItem[];
+}
+
+// request input
+{
+  items: [{ price: 99, quantity: 2 }];
+}
+
+// validated value delivered to the handler
+{
+  items: [{ quantity: 2 }];
+}
+```
+
+Use DTO projection to omit a field that the API must never accept or return. Use scene-aware `readonly` when a field belongs to the schema but must be removed from write input for one contract scene. This sanitization is not response serialization; response payload shaping remains a separate concern in the [Serialization Guide](/backend/serialization-guide). General object parsing and unknown-key behavior still belong to the supplied Zod schema; readonly sanitization removes known protected fields only after successful parsing.
+
 A useful distinction is:
 
 - `v.optional` means the field may be omitted
@@ -82,6 +125,8 @@ When changing request contracts, ask:
 2. does the contract need explicit extension through the `v` helpers?
 3. does the same validation surface also feed OpenAPI and DTO behavior?
 4. is the validation logic better expressed at the controller, DTO, or entity layer?
+5. for a scene-aware DTO, what is its effective schema scene and does each protected field resolve to read-only there?
+6. when protected fields can be nested, have object and array inputs been tested separately?
 
 That produces more consistent backend contracts.
 

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

@@ -103,29 +103,22 @@ The config side follows the same merge pattern with `config.ts`, `config.[meta].
 
 Different SSR flavors can intentionally expose different runtime capabilities rather than behaving identically.
 
-A concrete example in the current Cabloy Basic frontend setup is SSR theme resolution:
+A concrete example in the current Cabloy Basic frontend setup is the default SSR profile:
 
-- Web SSR uses a cookie-disabled path
-- Admin SSR uses a cookie-capable path
+- Web defaults to `SSR_PROFILE=public`
+- Admin defaults to `SSR_PROFILE=session`
 
-That means the two flavors should not be treated as providing the same guarantee for theme-sensitive SSR output.
+The effective profile is request-local: the active flavor's `SSR_PROFILE` supplies its default, and `route.meta.ssrProfile` can override it after route resolution. `public` keeps cookie-derived identity and theme state out of the server render; `session` permits normal cookie-backed Passport recovery and theme resolution, while forcing a private, non-storable response. Profiles define request-cookie capability, not a locale source: existing `route.meta.locale` controls URL-locale participation.
 
-In practice:
+That means flavor selection is not only a packaging choice. It establishes the default capability boundary, while individual routes remain able to select the profile their rendering contract requires.
 
-- Web SSR is the stricter path and should treat theme-sensitive SSR reads as lower-authority
-- Admin SSR can provide a stronger server/client theme match guarantee
+Before assuming how SSR theme state is handed off and finalized, combine:
 
-This is exactly why flavor selection is not only a packaging choice. It can also define the supported capability boundary for runtime-sensitive behavior.
-
-A second practical rule is that flavor alone is not the full story. Contributors should combine:
-
-- flavor and `SSR_COOKIE` capability
+- the effective SSR profile
 - edition marker
 - active UI-library adapter
 
-before assuming how SSR theme state is handed off and finalized.
-
-For the theme-side contract and edition-aware checklist, see [Theme Guide](/frontend/theme-guide). For the env-side explanation of `SSR_COOKIE`, see [SSR Environment Variables](/frontend/ssr-env).
+For the theme-side contract and edition-aware checklist, see [Theme Guide](/frontend/theme-guide). For the env-side explanation of `SSR_PROFILE`, see [SSR Environment Variables](/frontend/ssr-env).
 
 ## Scripts and runtime variants
 

package/cabloy-docs/frontend/navigation-guards-guide.md

@@ -25,7 +25,7 @@ class ServiceRouterGuards {
   protected onRouterGuards(router: BeanRouter) {
     router.beforeEach(async to => {
       if (to.meta.requiresAuth === false) return;
-      if (this.sys.config.ssr.cookieDisabledOnServer) return;
+      if (process.env.SERVER && this.$ssr.profile === 'public') return;
 
       if (!this.$passport.isAuthenticated) {
         const [_res, err] = await catchError(() => this.$passport.ensurePassport());
@@ -57,9 +57,9 @@ That means route configuration and guard behavior should be read together, not a
 
 ## SSR-sensitive detail
 
-The example also references SSR-related configuration such as cookie handling on the server side.
+The example uses the request-local `$ssr.profile` selected after route resolution and before the SSR app initializes.
 
-When `SSR_COOKIE=false`, `cookieDisabledOnServer` is true only during server rendering. The guard deliberately allows the protected route's neutral SSR entry, then the browser restores Passport state and applies the same admission policy after hydration. This preserves equivalent server and hydration-time initial rendering without weakening Client-side protection.
+When the effective profile is `public`, the server deliberately allows the protected route's neutral SSR entry. The browser restores Passport state and applies the same admission policy after hydration. A `session` profile permits the server to recover Passport and make the normal redirect or access-denied decision during the initial render. This preserves equivalent server and hydration-time initial rendering without weakening Client-side protection.
 
 For cookie-enabled SSR, a rejected request must still use `$redirect(...)` so the SSR layer returns its HTTP redirect response. On the Client, return a route path or route-location object from the guard instead of using an imperative `$goto...()` helper.
 

package/cabloy-docs/frontend/page-route-guide.md

@@ -59,10 +59,10 @@ The route meta surface includes important behavior such as:
 - absolute-path behavior
 - layout choice
 - authentication requirement
-- locale handling
+- URL-locale handling through `meta.locale`
 - component key behavior
 - keepAlive behavior
-- SSR transfer-cache behavior
+- SSR profile and nested `meta.ssrProfileOptions.responseCache` behavior
 
 This is one reason route records matter so much: they are not just URL declarations. They are an application-behavior surface.
 
@@ -148,6 +148,6 @@ It should also check whether the route change affects:
 - params typing
 - auth behavior
 - layout behavior
-- locale behavior
-- SSR behavior
+- whether `meta.locale` should participate in URL-locale behavior
+- SSR profile and nested `meta.ssrProfileOptions.responseCache` behavior
 - metadata regeneration

package/cabloy-docs/frontend/ssr-env.md

@@ -12,54 +12,47 @@ Zova exposes SSR-related environment variables so the framework can configure ke
 
 Representative variables include:
 
-- `SSR_COOKIE`
+- `SSR_PROFILE`
 - `SSR_COOKIE_THEMEDARK_DEFAULT`
-- `SSR_BODYREADYOBSERVER`
 - `SSR_API_BASE_URL`
 - `SSR_PROD_PORT`
-- `SSR_TRANSFERCACHE`
-- `SSR_TRANSFERCACHE_EXPIRES`
 
-These affect areas such as cookie-driven SSR behavior, theme defaults, body-load observation, server-side API targeting, and SSR production port behavior.
+These affect SSR profile selection, theme defaults, server-side API targeting, and SSR production port behavior. Response-cache defaults are resolved from the selected request-local profile; body-ready behavior is an opt-in of the selected layout module, not an environment or profile switch.
 
-## SSR response cache control
+## SSR profile
 
-`SSR_TRANSFERCACHE` and `SSR_TRANSFERCACHE_EXPIRES` control the `Cache-Control` response header that Zova adds after an SSR page is rendered.
+`SSR_PROFILE` is the standalone-flavor default for request-local SSR behavior:
 
-- `SSR_TRANSFERCACHE=false` disables this header path.
-- Any other value enables it in the current configuration normalization.
-- `SSR_TRANSFERCACHE_EXPIRES=0` emits `Cache-Control: no-cache, no-store, must-revalidate`.
-- A positive number of seconds or an `ms`-style duration such as `10m` emits `Cache-Control: public, max-age=<seconds>`.
+- `public`: the server renders without request-cookie credentials or cookie-backed theme resolution. Output must be anonymous-safe and may use public response caching.
+- `session`: the server may recover request-cookie session state for normal route admission and authorized rendering. The response is always `Cache-Control: private, no-store`.
 
-Cabloy Basic uses different flavor defaults:
+For Vona-backed SSR, `SSR_PROFILE` supplies the flavor default. After the frontend route is resolved, `route.meta.ssrProfile` can override that default before `serverEntry` runs. The resolved profile controls request-cookie capability and related SSR behavior; locale-aware URL handling remains the existing `route.meta.locale` contract. A profile never grants authentication, site admission, or API authorization; `requiresAuth` and Vona guards remain responsible for those decisions.
 
-| Flavor | Settings                                                  | SSR response header                   |
-| ------ | --------------------------------------------------------- | ------------------------------------- |
-| Web    | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=10m` | `public, max-age=600`                 |
-| Admin  | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=0`   | `no-cache, no-store, must-revalidate` |
+The selected layout owns sidebar restoration. A layout that enables `layout.sidebar.bodyReadyObserver` queues a request-local hidden-body metadata entry during SSR, registers its readiness condition and restoration callback, and then injects the generic browser observer. The observer restores browser-local sidebar state after the relevant layout DOM exists and reveals the body before hydration. Admin enables this path; Web and Empty disable it. Therefore, a Web route using `ssrProfile: 'session'` remains `private, no-store` without gaining the Admin sidebar observer.
 
-A route can override the flavor default through its SSR route metadata. For Cloudflare cache-rule alignment that preserves these origin headers, see [Docker + Cloudflare Deployment](/fullstack/deploy-cloudflare-docker).
+The selected layout also supplies its own desktop sidebar fallback and responsive breakpoint: the Admin layout defaults to open and the Web layout defaults to closed, and both currently use `1023px` as their independently configured breakpoint. Browser-local sidebar preference can override that fallback. The selected layout passes its breakpoint to the SSR browser handoff; it is not profile-specific. SSR profile selection does not change a layout's sidebar behavior.
 
-## Theme implications of `SSR_COOKIE`
+## SSR response cache control
 
-`SSR_COOKIE` is not only a storage choice. It also changes what SSR can guarantee about theme-sensitive output.
+After Zova resolves the route profile, a `session` response immediately receives `Cache-Control: private, no-store`, before router guards or rendering can terminate it. A successfully rendered public route receives the profile default cache header, which `meta.ssrProfileOptions.responseCache` can refine.
 
-A practical split is:
+Cabloy Basic uses different flavor defaults:
 
-- `SSR_COOKIE=true`: the server can resolve theme state from cookies during SSR
-- `SSR_COOKIE=false`: the server cannot guarantee that theme-sensitive SSR reads match the browser's eventual selected theme
+| Flavor | Default profile | SSR response header                  |
+| ------ | --------------- | ------------------------------------ |
+| Web    | `public`        | `public, max-age=600` when cacheable |
+| Admin  | `session`       | `private, no-store`                  |
 
-In practice, this means Web SSR and Admin SSR can intentionally expose different theme capabilities.
+A route can override the flavor profile through `meta.ssrProfile` and can define a public response-cache policy through `meta.ssrProfileOptions.responseCache`. Set the nested value to `false` to disable public cache-header generation for that route. For Cloudflare cache-rule alignment that preserves these origin headers, see [Docker + Cloudflare Deployment](/fullstack/deploy-cloudflare-docker).
 
-- In a cookie-capable SSR path, theme-sensitive server rendering can rely on a stronger server/client match guarantee.
-- In a cookie-disabled SSR path, SSR should treat theme-sensitive reads as non-authoritative for the browser's final theme and prefer hydration-tolerant or client-finalized decisions when exact matching matters.
+## Theme implications of `SSR_PROFILE`
 
-A practical development rule is:
+`SSR_PROFILE` determines whether the server can use cookie-backed theme state for the current request.
 
-- use `SSR_COOKIE` to determine the capability level
-- use the active edition and UI library to determine how that capability is implemented
+- `session`: the server can resolve theme state from request cookies during SSR.
+- `public`: server theme reads are not authoritative for the browser's final theme. Keep theme-sensitive rendering hydration-tolerant and use the established browser-finalization path.
 
-That matters because Cabloy Basic and Cabloy Start share the same theme architecture but do not use the same adapter-level SSR handoff strategy.
+Use the active edition and UI library to determine the adapter-level implementation. Cabloy Basic and Cabloy Start share the profile contract but do not necessarily use the same SSR theme handoff.
 
 For the broader theme usage contract and edition-aware checklist, see [Theme Guide](/frontend/theme-guide). For the runtime/flavor selection model behind these env choices, see [Environment and Config Guide](/frontend/environment-config-guide).
 

package/cabloy-docs/frontend/theme-guide.md

@@ -166,13 +166,13 @@ A practical split is:
 - Web SSR is usually the lower-authority path for final browser theme when cookie-backed SSR resolution is unavailable
 - Admin SSR is the stronger path for SSR-stable theme-sensitive rendering when cookie-backed SSR resolution is available
 
-In practice, always check `SSR_COOKIE` and the active adapter behavior before assuming that server-rendered theme-sensitive output can exactly match the hydrated client state.
+In practice, check the request-local `$ssr.profile` and the active adapter behavior before assuming that server-rendered theme-sensitive output can exactly match the hydrated client state.
 
-With `SSR_COOKIE=false`, server reads of `$theme.dark`, `$theme.darkMode`, and `$token` should be treated as non-authoritative for the browser's final theme unless the active adapter explicitly documents a stronger guarantee.
+With a `public` profile, server reads of `$theme.dark`, `$theme.darkMode`, and `$token` should be treated as non-authoritative for the browser's final theme unless the active adapter explicitly documents a stronger guarantee.
 
-With `SSR_COOKIE=true`, SSR theme-sensitive branching can rely on a stronger server/client match guarantee, but should still stay inside the established theme handler and hydration pipeline.
+With a `session` profile, SSR theme-sensitive branching can use cookie-backed state and rely on a stronger server/client match guarantee, but should still stay inside the established theme handler and hydration pipeline.
 
-For the env-side explanation of `SSR_COOKIE`, see [SSR Environment Variables](/frontend/ssr-env). For the flavor/runtime selection model, see [Environment and Config Guide](/frontend/environment-config-guide).
+For the env-side explanation of `SSR_PROFILE`, see [SSR Environment Variables](/frontend/ssr-env). For the flavor/runtime selection model, see [Environment and Config Guide](/frontend/environment-config-guide).
 
 ## Shared development rules
 

package/cabloy-docs/frontend/zova-router-under-the-hood.md

@@ -355,7 +355,7 @@ The framework service focuses on routing mechanics such as:
 The `home-base` service focuses on application policy such as:
 
 - auth enforcement through `meta.requiresAuth`
-- locale initialization through `meta.locale`
+- URL-locale participation and initialization through `meta.locale`
 
 A practical reading takeaway is:
 

package/cabloy-docs/fullstack/deploy-cloudflare-docker.md

@@ -111,12 +111,12 @@ For current Cache Rule settings, see [Cache Rules settings](https://developers.c
 
 ## SSR cache contract
 
-Zova SSR writes the cache contract during rendering through `SSR_TRANSFERCACHE` and `SSR_TRANSFERCACHE_EXPIRES`. The current public Cabloy Basic baseline uses these defaults:
+Zova SSR writes the public response-cache contract during rendering from the resolved profile and any public route-level `meta.ssrProfileOptions.responseCache` override. The effective SSR profile is authoritative: a `session` response always sets `Cache-Control: private, no-store` before route or profile response-cache policy is considered.
 
-| Flavor | Default settings                                          | SSR response header                                  | Cloudflare result with this rule                                |
-| ------ | --------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
-| Web    | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=10m` | `Cache-Control: public, max-age=600`                 | Eligible to cache for ten minutes, subject to Cloudflare policy |
-| Admin  | `SSR_TRANSFERCACHE=true`, `SSR_TRANSFERCACHE_EXPIRES=0`   | `Cache-Control: no-cache, no-store, must-revalidate` | Not stored                                                      |
+| Flavor | Default profile | SSR response header                                 | Cloudflare result with this rule                                |
+| ------ | --------------- | --------------------------------------------------- | --------------------------------------------------------------- |
+| Web    | `public`        | `Cache-Control: public, max-age=600` when cacheable | Eligible to cache for ten minutes, subject to Cloudflare policy |
+| Admin  | `session`       | `Cache-Control: private, no-store`                  | Not stored                                                      |
 
 For Cabloy Start, verify the effective Web and Admin values in the licensed Start repository before creating the Cloudflare rule. The rule design remains the same: preserve and follow the origin `Cache-Control` response instead of replacing it.
 
@@ -132,5 +132,5 @@ After the origin is running, verify the following before relying on Cloudflare t
 2. Each configured subdomain resolves to its expected enabled instance.
 3. Nginx forwards the browser hostname instead of the literal value `localhost`.
 4. Web SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `public, max-age=600`.
-5. Admin SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `no-cache, no-store, must-revalidate`.
+5. Admin SSR returns the `Cache-Control` header expected from the active edition and flavor configuration. In the current Basic baseline, it is `private, no-store`.
 6. After Cloudflare proxying is enabled, responses intended to be public-cacheable can be cached at the edge while responses marked `no-store` are not stored.

package/cabloy-docs/fullstack/parallel-worktree-environment.md

@@ -50,9 +50,9 @@ DEV_SERVER_HMR_PORT = 24680
 
 The user-facing summary is:
 
-> 环境隔离信息：Vona 开发 + Zova 开发
+> Environment isolation: Vona development + Zova development
 
-If the proposal is unsuitable, say **“再换一批”**. The skill increases every listener port by exactly `+1`, regenerates `API_BASE_URL` from the new Vona port, and presents the next tuple for confirmation. It never writes during this step.
+If the proposal is unsuitable, say **“Try another batch”**. The skill increases every listener port by exactly `+1`, regenerates `API_BASE_URL` from the new Vona port, and presents the next tuple for confirmation. It never writes during this step.
 
 This deterministic scheme is not a port reservation or a live collision check. If an application later reports that a port is occupied, request another batch before setup or create another linked worktree; successful application startup remains the final authority.