cabloy 5.1.136 → 5.1.138

package/.cabloy-version

@@ -1 +1 @@
-5.1.136
+5.1.138

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

@@ -141,6 +141,19 @@ Check whether the feature needs:
 - OpenAPI metadata
 - inferred DTO generation
 
+### Conditional RBAC metadata
+
+When the active edition and installed modules provide `@Passport.rbac(...)` and the task adds or changes a decorated action:
+
+- verify the decorator, RBAC catalog, and any policy-catalog/editor consumer in the active source before making availability claims
+- provide locale-aware `summary` metadata at both the controller and action levels; these scopes are independent and must be authored explicitly
+- add locale-aware `description` metadata only when the business or administrative experience needs explanatory text
+- keep action keys, controller bean names, action names, routes, and other authorization/integration identifiers stable and nonlocalized
+- treat summary/description as presentation metadata, not authorization identity or enforcement
+- verify the explicit server-side catalog/editor projection; do not assume OpenAPI metadata is automatically displayed by a policy editor
+
+For the authoring example and metadata boundary, read [Controller Guide](../../../cabloy-docs/backend/controller-guide.md#rbac-presentation-metadata) and [Controller AOP Guide](../../../cabloy-docs/backend/controller-aop-guide.md#rbac-presentation-metadata).
+
 ### Persistence and schema lifecycle
 
 Check whether the feature needs:

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -26,6 +26,17 @@ After generating or extending a backend thread, check which follow-up layers app
 - treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping rather than metadata-only
 - after touching structure-shaping schemaLike, verify the emitted schema/OpenAPI result explicitly
 
+### Conditional RBAC metadata follow-up
+
+When the active edition and installed modules provide `@Passport.rbac(...)` and a task adds or changes a decorated action:
+
+- verify the decorator, RBAC catalog, and any policy-catalog/editor consumer in the active source before making availability claims
+- provide locale-aware `summary` metadata at both the controller and action levels; these scopes are independent and must be authored explicitly
+- add locale-aware `description` metadata only when the business or administrative experience needs explanatory text
+- keep action keys, controller bean names, action names, routes, and other authorization/integration identifiers stable and nonlocalized
+- treat summary/description as presentation metadata, not authorization identity or enforcement
+- verify the explicit server-side catalog/editor projection; do not assume OpenAPI metadata is automatically displayed by a policy editor
+
 ## Persistence follow-up
 
 - migration/version changes

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

@@ -226,6 +226,23 @@ Important Cabloy Basic reverse-sync rule:
 
 For Cabloy Start, verify the exact Start-specific flavor names, paths, SSR site baselines, and project assets in the licensed Start repo.
 
+### Schema-driven UI decision branch
+
+When the regenerated contract feeds a form or another metadata-driven UI, decide the ownership path before adding frontend field definitions:
+
+1. Put reusable field meaning, validation, titles, ordering, and renderer metadata on the backend entity or inferred contract when those semantics are shared; put operation-specific projection or composition in the DTO.
+2. Identify the frontend consumer surface:
+   - generated `$api` for executing an operation;
+   - generated `$apiSchema` for a named schema facade;
+   - `$sdk` or `ModelResource` for dynamic schema/resource access;
+   - a direct page form for a local, non-resource workflow.
+3. Prefer automatic `ZForm` rendering when the resolved schema already carries the field metadata. A `ZForm` with `schema` and no default body slot iterates schema properties automatically; use `slotFooter` or other structural slots for page-specific actions without replacing the automatic body. A default body slot is an intentional manual/mixed-composition boundary and must render the required fields deliberately.
+4. Treat localized schemas as locale-scoped runtime state. Do not retain a `createApiSchemas(...)` facade, its `requestBody`, or an `omit`/`pick`/other transformed snapshot across a locale change. Reacquire the current schema through a getter, `$computed`, or the owning `ModelResource`; perform page-specific schema transformations inside that reactive derivation and ensure the current facade's SDK query is ready. `staleTime: Infinity` is cache behavior within a selected runtime, not cross-locale schema validity.
+5. Keep reusable query, cache, mutation, invalidation, and resource state in `ModelResource` or a model. A page-specific action may call generated `$api` directly when it has no shared state or cache ownership; do not add an infrequently used operation to a shared model only for API indirection.
+6. If the page needs a custom renderer, layout, or behavior, determine whether that resource is frontend-owned and referenced by backend metadata. If so, follow the reverse-chain flavor build and `deps:vona` handoff rather than treating the change as frontend-only.
+
+Read the [API Schema Guide](../../../cabloy-docs/frontend/api-schema-guide.md), [Form Guide](../../../cabloy-docs/frontend/form-guide.md), [A-OpenAPI Under the Hood](../../../cabloy-docs/frontend/a-openapi-under-the-hood.md), and [Model Resource Owner Pattern](../../../cabloy-docs/frontend/model-resource-owner-pattern.md) for the ownership and runtime details. Use `references/contract-loop-map.md` and `references/verification-checklist.md` for the contract-loop proof steps.
+
 ### Path C: Downstream frontend alignment
 
 After generation, inspect whether the frontend still needs follow-up in:

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

@@ -122,16 +122,50 @@ Typical frontend thread pieces may include:
 
 Do not throw away the generated structure and rewrite it from scratch unless the generator clearly does not match the task.
 
+### Relative import suffix follow-up
+
+For Zova application modules under `zova/src/module/**`, `zova/src/module-vendor/**`,
+`zova/src/suite/**/modules/**`, and `zova/src/suite-vendor/**/modules/**`, relative
+imports and exports name the emitted ESM file:
+
+- a `.ts` target uses `.js`
+- a `.tsx` target uses `.jsx`
+
+Apply this to ordinary and type-only imports, relative re-exports, and module tests.
+Keep the generated `.js`/`.jsx` specifiers as the baseline after CLI generation or
+metadata refresh; manual follow-up imports must use the same emitted suffix.
+
+Do not apply this rule globally. Preserve deliberate `.ts`/`.tsx` imports in
+`zova/packages-utils/**` and `zova/packages-zova/**`; do not normalize Vona, CLI or
+template source, dependencies, generated output, or build artifacts. Never use a
+repository-wide suffix replacement: inspect only the affected module thread.
+
 ## Step 5: Apply frontend follow-up logic deliberately
 
 Frontend scaffolding is rarely complete after generation alone. Treat this follow-up review as mandatory.
 
 ### Route and metadata follow-up
 
+Before finalizing every new or changed route, resolve the effective route defaults rather than relying on an unexamined omission:
+
+- **layout** — omitted `meta.layout` inherits the logical default layout;
+- **authentication** — omitted `requiresAuth` remains protected by the current guard, and only `requiresAuth: false` opts out;
+- **SSR profile** — omitted `meta.ssrProfile` inherits the active flavor's `SSR_PROFILE`, while route metadata overrides it.
+
+For Zova page routes, also apply these authoring defaults:
+
+- routes with dynamic params require `route.name`; static routes should omit `route.name` unless a documented named-route requirement exists;
+- ordinary business routes without `locale` params should omit app-config aliases unless a documented system, compatibility, or user-facing URL exception requires one;
+- choose `ssrProfile` from the route's rendering contract: Web remains `public` by default, while `session` is explicit for cookie-backed state, protected admission, personalized first paint, or private SSR data; a missing `locale` parameter alone does not determine the profile; anonymous admission remains an explicit `requiresAuth: false` decision.
+
+Verify the active edition and flavor before applying concrete SSR defaults, and do not add all three fields redundantly when intentional inheritance is the desired behavior.
+
 Check whether the feature needs:
 
 - page route review
 - params/query schema alignment
+- effective layout, authentication, and SSR-profile default resolution
+- static-name and ordinary-alias exception review
 - alias or guard review
 - metadata regeneration
 
@@ -175,6 +209,7 @@ Check whether the feature needs:
 - typecheck
 - build
 - metadata regeneration verification
+- scoped relative-import verification: check the affected Zova module tree for accidental `.ts`/`.tsx` relative specifiers, while excluding intentional package source under `zova/packages-utils/**` and `zova/packages-zova/**`
 - SSR or route-path verification
 - hydration-time initial-render equivalence when SSR, private state, browser-only state, or async model state changes
 - edition-specific flavor, SSR site baseline, and project-asset verification

package/.claude/skills/cabloy-frontend-scaffold/evals/evals.json

@@ -16,7 +16,7 @@
     {
       "id": 3,
       "prompt": "I changed a route and component structure in Cabloy Basic and now I am not sure what else I should update. What should Claude check before saying the frontend work is done?",
-      "expected_output": "Identifies likely frontend follow-up such as metadata regeneration, page/component/API/model or SSR impact, and verification commands.",
+      "expected_output": "Resolves the effective layout, authentication, and SSR-profile choices for each changed route; confirms static-name and ordinary-alias decisions, params/name implications, metadata regeneration, page/component/API/model or SSR impact, and route/SSR verification commands.",
       "files": []
     },
     {

package/.claude/skills/cabloy-frontend-scaffold/references/follow-up-checklist.md

@@ -8,6 +8,9 @@ After generating or extending a frontend thread, check which follow-up layers ap
 - component wrapper usage
 - route record implications
 - params/query schema alignment
+- [ ] resolve the route-default triad: effective `layout`, `requiresAuth`, and `ssrProfile`; confirm every omitted field intentionally inherits the active default
+- [ ] static routes omit `route.name` unless a documented named-route requirement exists; ordinary business routes without `locale` params omit app-config aliases unless an explicit exception applies
+- [ ] choose `ssrProfile` from the route's rendering contract (Web remains `public` by default; `session` is explicit for cookie-backed state, protected admission, personalized first paint, or private SSR data); a missing `locale` parameter alone does not determine it, and anonymous access is chosen independently with explicit `requiresAuth: false`
 
 ## Data and contract follow-up
 
@@ -35,6 +38,7 @@ After generating or extending a frontend thread, check which follow-up layers ap
 - `:tools:metadata`
 - route/component/icon regeneration-sensitive changes
 - edition-specific generated output review
+- for a `this.scope.locale` missing-key or type error: inspect `src/config/locale/`; if it is absent, run `npm run zova :init:locale <module>` (which refreshes metadata in its normal path), add the key to all required locale files, and run `npm run zova :tools:metadata <module>` if generated typing remains stale; do not cast around the error or add a local locale compatibility helper
 
 ## Verification follow-up
 

package/.claude/skills/cabloy-zova-source-reading/SKILL.md

@@ -91,6 +91,13 @@ For compact procedural summaries inside the skill bundle, also use:
 - `references/analysis-modes.md`
 - `references/core-reading-paths.md`
 
+For locale-sensitive schema/form questions, also read:
+
+- `cabloy-docs/frontend/api-schema-guide.md`
+- `cabloy-docs/frontend/a-openapi-under-the-hood.md`
+- `cabloy-docs/frontend/form-guide.md`
+- `cabloy-docs/frontend/zova-form-under-the-hood.md`
+
 ### Core architecture surfaces
 
 Use these when the question needs broader architectural context:
@@ -117,6 +124,20 @@ Use these bundled references to keep the workflow compact:
 
 Use the public `cabloy-docs/frontend/zova-source-reading-map.md` as the fuller explanation layer, but use the bundled references first when they are enough for the current task.
 
+### Locale-sensitive schema and form path
+
+When a translated schema title, renderer, or validation surface remains stale after a locale change, read in this order:
+
+1. the public API Schema Guide and A-OpenAPI Under the Hood guide;
+2. the public Form Guide and Zova Form Under the Hood guide when a `ZForm` consumes the schema;
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/monkey.ts` to verify that the active locale replaces the selected `ModelSdk`;
+4. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/model/sdk.ts` to inspect selector-scoped schema queries and `createApiSchemas(...)` facade lifetime;
+5. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/bean/sys.sdk.ts` to verify locale headers and schema caches;
+6. the generated API-schema bean and the actual page/model consumer that stores or derives the facade;
+7. `zova/src/suite-vendor/a-zova/modules/a-form/` only after confirming which schema the form owner supplies, and whether automatic body iteration was replaced by a default body slot.
+
+The key distinction is between a genuinely stale generated contract and a valid schema facade captured from an earlier locale. `$computed` is only locale-safe when its dependency path reacquires the current schema source; wrapping an old facade or transformed snapshot does not make it current.
+
 ## Step 5: Explain Zova-native meaning first
 
 When answering, explain the Zova role first, then add Vue analogies only if they help.

package/.claude/skills/cabloy-zova-source-reading/references/core-reading-paths.md

@@ -99,6 +99,32 @@ Use when the question is about:
 - layout shell implications
 - route-aware controller state
 
+## Locale-sensitive OpenAPI schema and ZForm path
+
+Read in this order:
+
+1. `cabloy-docs/frontend/api-schema-guide.md`
+2. `cabloy-docs/frontend/a-openapi-under-the-hood.md`
+3. `cabloy-docs/frontend/form-guide.md` and `cabloy-docs/frontend/zova-form-under-the-hood.md` when a form consumes the schema
+4. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/monkey.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/model/sdk.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/bean/sys.sdk.ts`
+7. the generated API-schema bean for the operation
+8. the consumer controller/model and, only then, `a-form` controller/render sources
+
+Use when the question is about:
+
+- translated form titles, descriptions, validation, or renderer metadata that remain stale after a locale switch
+- whether an `$apiSchema` facade, `requestBody`, or transformed schema may be stored across locale changes
+- whether a stale result is generated-contract drift or consumer-side capture
+- whether automatic `ZForm` rendering remains active or a default body slot intentionally replaced it
+
+Expected conclusion:
+
+- `a-openapi` selects a locale-scoped runtime, so `createApiSchemas(...)` facades created before a locale change can retain an earlier schema query
+- the consumer must reacquire the schema through a live getter/computed owner and apply schema transforms in that same derivation
+- `ZForm` resolves properties from the supplied schema; it does not refresh a stale caller-owned facade
+
 ## Model/state ownership path
 
 Read in this order:

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 5.1.138
+
+### Features
+
+- Add a role-based access control (RBAC) system with permission and scope support.
+- Add user home pages, avatar support, and activation handling.
+- Add return-to redirect support for login flows.
+- Add mail capabilities and a base authentication guard.
+- Add basic image and select field support, including boolean field values.
+- Add SKU product and identifier support.
+- Add API and model resource deletion capabilities.
+- Add SSR profile metadata localization, public session handling, and local loading support.
+
+### Bug Fixes
+
+- Fix transaction handling.
+- Fix locale handling.
+- Fix internal SSR disposal method casting.
+
+### Improvements
+
+- Enhance deletion behavior.
+- Update database dialect, controller, authentication guard, locale, and application initialization components.
+
+## 5.1.137
+
+### Improvements
+
+- Refresh the Zova lockfile after compensation rerun preparation.
+- Refresh the Vona Zova Core patch for v5.1.85.
+
 ## 5.1.136
 
 ### Features

package/CLAUDE.md

@@ -46,6 +46,9 @@ 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.
+- For schema-driven UI, treat backend entity/DTO/OpenAPI metadata as contract truth; prefer `$apiSchema` or the owning `ModelResource` with automatic `ZForm` rendering, regenerate generated consumers, and never duplicate schema metadata or hand-edit generated consumers.
+- Treat localized `$apiSchema` and `ModelResource` schemas as locale-scoped reactive state: do not retain a schema facade or derived snapshot created before a locale change; reacquire it through the current runtime and reactive owner.
+- Keep reusable query, cache, mutation, and resource state in models or `ModelResource`; a page-specific, low-reuse action may call the generated `$api` directly when no shared state or cache ownership is required.
 - 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.
@@ -54,7 +57,8 @@ Before inventing a custom implementation path:
 - 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 Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
 - For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
-- In Zova page routes, any route with dynamic `params` must define `route.name`; do not rely on unnamed path-keyed routes for typed `$params`, and regenerate page metadata after route changes.
+- In Zova application modules under `zova/src/module/**`, `zova/src/module-vendor/**`, `zova/src/suite/**/modules/**`, and `zova/src/suite-vendor/**/modules/**`, use emitted runtime suffixes for relative imports and exports: `.js` for `.ts` targets and `.jsx` for `.tsx` targets, including type-only imports and module tests. Preserve the deliberate `.ts`/`.tsx` convention in `zova/packages-utils/**` and `zova/packages-zova/**`; do not generalize this rule to Vona, CLI/templates, dependencies, generated output, or build artifacts.
+- In Zova page routes, any route with dynamic `params` must define `route.name`; do not rely on unnamed path-keyed routes for typed `$params`. Static routes should omit `route.name` unless a documented named-route requirement exists; use `$router.getPagePath(...)` for canonical static URL generation rather than adding a name or alias for convenience. Ordinary business routes without `locale` params should omit app-config aliases unless a documented system, compatibility, or user-facing URL exception requires one. Choose `ssrProfile` from the page's rendering contract: Web remains `public` by default, while `session` is an explicit choice for cookie-backed state, protected admission, personalized first paint, or private SSR data; the absence of a locale parameter alone does not select a profile. `requiresAuth` is independent, so anonymous routes must explicitly use `requiresAuth: false`. Regenerate page metadata after route changes.
 - For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
 - 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.

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

@@ -188,6 +188,7 @@ export default defineConfig({
   themeConfig: {
     nav: [
       { text: 'Home', link: '/' },
+      { text: 'Blogs', link: '/blogs/', activeMatch: '^/blogs/' },
       { text: 'Fullstack', link: '/fullstack/introduction', activeMatch: '^/fullstack/' },
       { text: 'Backend (Vona)', link: '/backend/introduction', activeMatch: '^/backend/' },
       { text: 'Frontend (Zova)', link: '/frontend/introduction', activeMatch: '^/frontend/' },

package/cabloy-docs/.vitepress/theme/custom.css

@@ -62,3 +62,127 @@
   background: #431407;
   color: #fdba74;
 }
+
+.cabloy-blog-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 1.5rem;
+  margin-top: 2rem;
+}
+
+.cabloy-blog-card {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft);
+  transition:
+    border-color 0.2s ease,
+    box-shadow 0.2s ease,
+    transform 0.2s ease;
+}
+
+.cabloy-blog-card:hover {
+  border-color: var(--vp-c-brand-1);
+  box-shadow: 0 12px 28px color-mix(in srgb, var(--vp-c-text-1) 12%, transparent);
+  transform: translateY(-2px);
+}
+
+.cabloy-blog-card__cover {
+  display: block;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  background: var(--vp-c-bg-alt);
+}
+
+.cabloy-blog-card__cover:focus-visible,
+.cabloy-blog-card h2 a:focus-visible,
+.cabloy-blog-card__read:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 3px;
+}
+
+.cabloy-blog-card__cover img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: transform 0.2s ease;
+}
+
+.cabloy-blog-card:hover .cabloy-blog-card__cover img {
+  transform: scale(1.025);
+}
+
+.cabloy-blog-card__content {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  padding: 1.25rem;
+}
+
+.cabloy-blog-card__date {
+  margin: 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.cabloy-blog-card h2 {
+  margin: 0.5rem 0 0;
+  border: 0;
+  font-size: 1.25rem;
+  line-height: 1.4;
+}
+
+.cabloy-blog-card h2 a {
+  color: var(--vp-c-text-1);
+  text-decoration: none;
+}
+
+.cabloy-blog-card h2 a:hover {
+  color: var(--vp-c-brand-1);
+}
+
+.cabloy-blog-card__content > p:not(.cabloy-blog-card__date) {
+  margin: 0.75rem 0;
+  color: var(--vp-c-text-2);
+  font-size: 0.9375rem;
+  line-height: 1.6;
+}
+
+.cabloy-blog-card__tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  margin-top: auto;
+}
+
+.cabloy-blog-card__tags span {
+  border-radius: 999px;
+  padding: 0.1875rem 0.625rem;
+  background: color-mix(in srgb, var(--vp-c-brand-1) 12%, var(--vp-c-bg));
+  color: var(--vp-c-brand-3);
+  font-size: 0.75rem;
+  font-weight: 600;
+  line-height: 1.25rem;
+}
+
+.cabloy-blog-card__read {
+  align-self: flex-start;
+  margin-top: 1rem;
+  color: var(--vp-c-brand-1);
+  font-size: 0.9375rem;
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.cabloy-blog-card__read:hover {
+  color: var(--vp-c-brand-2);
+  text-decoration: underline;
+}
+
+.dark .cabloy-blog-card__tags span {
+  background: color-mix(in srgb, var(--vp-c-brand-1) 22%, var(--vp-c-bg));
+  color: #bfdbfe;
+}

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

@@ -131,6 +131,14 @@ The `home-user` module exposes out-of-the-box Passport APIs for common account f
 
 In the current repo implementation, these flows live in `home-user/src/controller/passport.ts`, where register/login call `bean.auth.authenticate(...)`, OAuth login uses provider/module path parameters, and token-oriented follow-up endpoints stay concentrated in one controller surface.
 
+## Registration and password recovery in Cabloy Basic
+
+The Home Login experience uses the Passport registration flow for new users. Registration collects the standard username, email, password, confirmation, and CAPTCHA fields, then continues through the ordinary signed-in navigation flow after it succeeds.
+
+If a user has lost an existing local password, the Login page also provides **Forgot password?**. The request form asks for an email address and CAPTCHA. After valid CAPTCHA verification, it always shows the same generic confirmation, whether or not a reset email can be sent. This protects account privacy and avoids exposing account eligibility through the interface.
+
+When a reset email is available, its link opens a public page where the user chooses a new local password. Completing the reset signs the user out of existing server-side sessions, so they must sign in again with the new password. Password reset replaces an existing local password; it is not a way for an OAuth-only account to add its first local password. That journey remains the authenticated **Set password** account-security action.
+
 This guide focuses on the framework-level auth model. For the user/passport side, see [User Access Guide](/backend/user-access-guide).
 
 ## Relationship to controller AOP

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

@@ -218,6 +218,8 @@ A useful backend mental model is:
 
 This layered model is the safest way to reason about config changes in Cabloy.
 
+`CORS_WHITE_LIST` is an example of a deployable environment value consumed directly by a framework middleware default. Configure deployment-specific browser origins in the active env layer; it is not a `config.modules[...]` field or instance-specific config. Use explicit `a-security:cors` configuration only when the application needs middleware behavior beyond the environment-provided origin list. See [Runtime and Flavors](/backend/runtime-and-flavors#configure-browser-cors-origins) for its format, browser-origin behavior, and env-file precedence.
+
 ## Relationship to startup, model, and datasource behavior
 
 Config does not live in isolation. In many backend tasks, config interacts directly with:

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

@@ -125,6 +125,14 @@ The CRUD generator applies `@Passport.systemAdmin()` to each generated CRUD acti
 
 For the underlying auth, passport, and user-access model, see [Auth Guide](/backend/auth-guide) and [User Access Guide](/backend/user-access-guide).
 
+### RBAC presentation metadata
+
+Some Cabloy editions or module sets provide `@Passport.rbac(...)` for dynamic RBAC actions. Verify the active edition and installed modules first; this decorator is not a Basic baseline assumption.
+
+When an action uses `@Passport.rbac(...)`, provide a locale-aware `summary` on both the controller metadata and the action's `@Web.*` metadata. These scopes are independent, so the controller summary does not supply the action summary. Add locale-aware `description` values only when the business or administrative experience needs explanatory text.
+
+These fields are for human-facing documentation and optional policy-catalog or policy-editor presentation. They are not authorization identity or enforcement inputs. Keep action keys and other machine identifiers stable and nonlocalized, and verify that the active server explicitly projects summary/description into a policy catalog before expecting an editor to display them. See [Controller Guide](/backend/controller-guide#rbac-presentation-metadata) for the authoring example.
+
 ## Interceptor
 
 Interceptors provide onion-style around-execution behavior for controller actions.

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

@@ -341,6 +341,8 @@ Representative pattern:
 
 ```typescript
 @Controller('student', {
+  description: 'Student controller',
+  summary: 'Student API',
   exclude: false,
   tags: ['Student'],
 })
@@ -349,14 +351,45 @@ class ControllerStudent {}
 
 Representative controller-option areas include:
 
+- `description`
+- `summary`
 - `exclude`
 - `tags`
 - `actions`
 - `enable`
 - `meta`
 
+`description` and `summary` at the controller level are controller metadata. They are independent from the operation metadata supplied to `@Web.*`: controller values do not become defaults for an action's OpenAPI `description` or `summary`. Set those fields on the action when documenting a specific operation.
+
 This is especially important because the controller surface can also be tuned from app config through onion/config override patterns.
 
+## RBAC presentation metadata
+
+Some Cabloy editions or module sets provide `@Passport.rbac(...)` for dynamic RBAC actions. Verify that the active edition and installed modules provide this decorator before applying the following convention.
+
+For every action decorated with `@Passport.rbac(...)`, provide a locale-aware `summary` at both the controller and action levels:
+
+```typescript
+@Controller('student', {
+  summary: $locale('StudentControllerSummary'),
+})
+class ControllerStudent extends BeanBase {
+  @Web.get(':id', {
+    summary: $locale('StudentViewSummary'),
+  })
+  @Passport.rbac({ dataScope: true })
+  async view(@Arg.param('id') id: number) {
+    // ...
+  }
+}
+```
+
+Controller and action `summary` values are independent metadata. A controller summary does not automatically become the action's OpenAPI summary, so define both explicitly. Add locale-aware `description` metadata at either level when the business or administrative experience needs additional explanation; descriptions are optional.
+
+A policy catalog or editor may project these fields as localized display labels, but only through an explicit server-side projection. `summary` and `description` are presentation metadata: they do not define the RBAC action key, select a policy, change a route or `operationId`, or grant authorization. Keep action keys, controller bean names, action names, routes, and other integration identifiers stable and nonlocalized. Do not assume that OpenAPI metadata is automatically included in a policy catalog; inspect the active implementation.
+
+See [Controller AOP Guide](/backend/controller-aop-guide) for the guard boundary and edition-aware RBAC notes.
+
 ## Relationship to the backend contract loop
 
 Read this guide together with:

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

@@ -150,10 +150,10 @@ Representative examples include:
 
 - registration events
 - activation events
-- post-registration follow-up such as email confirmation
+- post-registration follow-up such as account activation-link issuance
 - role-assignment follow-up logic
 
-Mail delivery is a common downstream effect in these flows; see [Mail Guide](/backend/mail-guide).
+Mail delivery is a common downstream effect in these flows; see [Mail Guide](/backend/mail-guide). Account activation-link issuance may be owned by the account service rather than an event listener.
 
 Read this together with [User Access Guide](/backend/user-access-guide) when the event flow is tied to identity lifecycle behavior.
 
@@ -169,7 +169,7 @@ Use direct calls when:
 
 - the behavior is tightly bound to the core logic and should not be extensible as a chain
 
-A practical example from the user-access layer is registration and activation: the core user flow can stay small, while follow-up concerns such as mail confirmation or role assignment move into listeners.
+A practical example from the user-access layer is activation: the core user flow can stay small, while follow-up concerns such as role assignment move into listeners. Account-specific activation-link issuance remains owned by the home-user account service.
 
 ## Implementation checks for event-driven backend changes
 

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

@@ -165,7 +165,7 @@ Read this guide together with:
 
 Those guides explain the flows where mail often becomes a downstream effect rather than the initiating business action.
 
-In the current repo, the `a-mailconfirm` flow is a representative example: user-access events can trigger mail-confirm behavior, and that bean ultimately delegates delivery through `bean.mail.send(...)` instead of embedding transport details directly into the user workflow.
+In the current repo, the `home-user` activation flow is a representative example: its account service issues a purpose-bound activation link and delegates delivery through `bean.mail.send(...)`, keeping transport details out of the user workflow.
 
 ## When to use a dedicated mail client
 

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

@@ -181,7 +181,7 @@ Use this checklist when adding Markdown-backed content:
 3. Call `this.bean.markdown.renderHtml(...)` on every authoritative write path.
 4. Define a business policy for blank Markdown; do not assume `renderHtml('')` deletes records.
 5. Expose the source and projection separately according to the consumer's authority.
-6. Use `basic-markdown:formFieldMarkdown` for the Markdown form field.
+6. Use the edition-specific Markdown form field: `basic-markdown:formFieldMarkdown` in Cabloy Basic or `start-markdown:formFieldMarkdown` in Cabloy Start.
 7. Use `ZMarkdownHtml` only for HTML produced by the trusted server rendering path.
 8. Add tests for blank values, invalid URL schemes, task-list output, derived HTML consistency, and forged output fields.
 9. Treat external-image policy, CSP, authorization, and content lifecycle cleanup as application concerns beyond this renderer.

package/cabloy-docs/backend/runtime-and-flavors.md

@@ -120,12 +120,41 @@ The current repo uses many env variables, but these are the most important ones
 | Runtime meta           | `META_MODE`, `META_FLAVOR`, `NODE_ENV`                                                                                                       | chooses the active runtime and flavor shape                                                   |
 | Worker/runtime process | `SERVER_WORKERS`                                                                                                                             | controls worker count and is normalized by the CLI/bootstrap path                             |
 | HTTP server            | `SERVER_LISTEN_HOSTNAME`, `SERVER_LISTEN_PORT`, `SERVER_LISTEN_DISABLE`, `SERVER_SERVE_PROTOCOL`, `SERVER_SERVE_HOST`, `SERVER_GLOBALPREFIX` | controls listen/serve behavior and URL shaping                                                |
+| CORS                   | `CORS_WHITE_LIST`                                                                                                                            | supplies the default allowed-origin whitelist for the `a-security:cors` middleware            |
 | Database               | `DATABASE_DEFAULT_CLIENT`, `DATABASE_CLIENT_SQLITE3_FILENAME`, `DATABASE_CLIENT_PG_*`, `DATABASE_CLIENT_MYSQL_*`                             | controls datasource defaults and concrete client connection settings                          |
 | Redis                  | `REDIS_DEFAULT_HOST`, `REDIS_DEFAULT_PORT`, `REDIS_DEFAULT_DB`                                                                               | controls the backend Redis baseline used by queue, cache, broadcast, and related capabilities |
 | Logger                 | `LOGGER_DIR`, `LOGGER_ROTATE_*`                                                                                                              | controls log path and rotation behavior                                                       |
 
 Use this page as the runtime-facing overview, then inspect the current app config when you need to see how those values are translated into backend config.
 
+## Public server origin
+
+`SERVER_LISTEN_HOSTNAME` and `SERVER_LISTEN_PORT` control where the Vona process binds. They do not define the public URL that Vona emits.
+
+When configured, `SERVER_SERVE_PROTOCOL` and `SERVER_SERVE_HOST` define Vona's canonical public origin for backend APIs and backend-hosted SSR sites. If either serve value is not configured, Vona resolves the effective protocol and host from the current proxy-aware request context; background work that needs a stable backend public origin should configure both serve values explicitly.
+
+A browser consumer can be deployed on a different origin and pathname. Account password-set and password-reset delivery therefore does not derive its destination from `SERVER_SERVE_*`, SSR Site metadata, `publicPath`, `siteId`, `Referer`, or browser-selected mount data: Zova supplies the complete token-free absolute public page URL, and Vona validates only HTTP(S), absence of userinfo/query/fragment, and an exact trusted origin. `checkOriginExact` permits the exact current origin when protocol, host, and effective port all match; request or proxy Host values are not a general cross-origin allowlist and cannot authorize lookalike, suffix, alternate-scheme, or alternate-port destinations. Other production consumer origins must exactly match an explicit `a-security:cors` `whiteList` entry. In `dev/test`, exact credential-link authorization additionally accepts different ports only when both API and consumer hostnames are loopback (`localhost`, `127.0.0.1`, or `::1`). Vona preserves the frontend pathname and alone adds the raw token as the `token` URL query parameter. Query transport reaches the initial request; Referrer-Policy and Vona, edge, or APM query-log redaction are intentionally outside this flow's current scope. Normal CORS defaults to an empty `whiteList`; configure `CORS_WHITE_LIST` with the permitted browser origins, or explicitly configure `a-security:cors`. In `dev/test`, loopback requests may cross ports; elsewhere, cross-origin CORS requires an allowed entry. Normal CORS wildcard and suffix matching remain available when configured but are not credential-link authorization.
+
+## Configure browser CORS origins
+
+`CORS_WHITE_LIST` supplies the default `whiteList` for the app-wide `a-security:cors` middleware. It controls normal HTTP CORS and the built-in WebSocket origin check; it does not authenticate or authorize requests.
+
+Set it to a comma-separated list of allowed browser origins. Use complete origins, including the scheme and a non-default port when applicable:
+
+```dotenv
+CORS_WHITE_LIST=https://app.example.com,https://admin.example.com
+```
+
+```dotenv
+CORS_WHITE_LIST=https://app.example.com,http://localhost:5173
+```
+
+When `CORS_WHITE_LIST` is absent or empty, Vona retains the closed empty-whitelist default. The existing `dev/test` loopback exception remains available for local development, so ordinary loopback clients on different ports do not require this setting.
+
+Set deployment-specific origins in the active `vona/env/.env*` layer or inject them through the deployment environment. See [Env-file resolution and precedence](#env-file-resolution-and-precedence) for the active-file chain and precedence rules. Applications that need middleware behavior beyond this default origin list can configure `a-security:cors` explicitly.
+
+Normal CORS may use its configured wildcard or suffix matching behavior. Do not use that behavior to authorize account credential links: `checkOriginExact(...)` accepts only an exact normalized HTTP(S) origin and rejects wildcard and suffix entries.
+
 ## How to determine runtime metadata in code
 
 ### Via environment variables

package/cabloy-docs/backend/user-access-guide.md

@@ -123,7 +123,7 @@ Representative flows include:
 - registration
 - activation
 - assigning default roles
-- sending email confirmation or similar follow-up logic
+- issuing account activation links or other follow-up logic
 
 Those follow-up email behaviors often connect directly to queue-backed mail delivery; see [Mail Guide](/backend/mail-guide).
 
@@ -131,7 +131,7 @@ The framework-level user APIs stay stable while project-specific modules can cus
 
 The legacy user docs showed this especially clearly:
 
-- registration can trigger follow-up mail-confirm flows
+- registration can issue an account activation link through the account service
 - activation can assign default roles such as `admin`
 - `autoActivate` can suppress the extra activation step when the business flow allows it