create-flowdular 0.4.1 → 0.4.3

package/agent-template/.agents/skills/module-new/SKILL.md

@@ -20,25 +20,26 @@ Every `acceptanceScenarios[]` entry maps to at least one test in `tests/`. A sce
 
 Each spec element maps to files:
 
-| Spec element                  | Files it produces                                                                                                                                       |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts` |
-| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                |
-| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                     |
-| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                      |
-| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                       |
-| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                               |
-| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                          |
-| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                    |
-| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                             |
-| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`                                                                         |
-| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                |
-| `research`                    | `src/research.ts`, `research-fixtures.json`, `requires` of the capabilities, the evidence attach where the `evidenceOwner` record is written            |
-| `adapters[]`                  | `src/adapters/<name>.ts`, the port, the adapter registration, `adapters/<name>.recorded.json`, as a separate `integration-adapter` phase                |
-| `templates[]`                 | `templates/<name>.md`, `templates` in `package.json` `files`, `src/templates.ts` registered through `documents.templates.v1` in `src/platform.ts`       |
-| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                          |
-| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                         |
-| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                    |
+| Spec element                  | Files it produces                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts`                                           |
+| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                                                          |
+| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                                                               |
+| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                                                                |
+| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                                                                 |
+| `design/<screen>.html`        | the approved look of that screen: mirror its structure and keep its copy. Render it with `pnpm ui:preview <path>`; absent, design it first with `ux-design`                                       |
+| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                                                                         |
+| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                                                                    |
+| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                                                              |
+| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                                                                       |
+| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`; a `kind: flag` entry keeps `kind: 'flag'` there, so owners switch it on the Flags tab of Administration, Modules |
+| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                                                          |
+| `research`                    | `src/research.ts`, `research-fixtures.json`, `requires` of the capabilities, the evidence attach where the `evidenceOwner` record is written                                                      |
+| `adapters[]`                  | `src/adapters/<name>.ts`, the port, the adapter registration, `adapters/<name>.recorded.json`, as a separate `integration-adapter` phase                                                          |
+| `templates[]`                 | `templates/<name>.md`, `templates` in `package.json` `files`, `src/templates.ts` registered through `documents.templates.v1` in `src/platform.ts`                                                 |
+| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                                                                    |
+| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                                                                   |
+| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                                                              |
 
 A v1 spec stays valid and carries none of these arrays. Then the requirements are `invariants`, `permissions` and `acceptanceScenarios`, and everything the spec leaves open is still a question rather than a guess.
 

package/agent-template/.agents/skills/module-update/SKILL.md

@@ -16,7 +16,7 @@ The spec-element to file mapping is the table in `module-new`; the change classe
 
 ## 1. Read first
 
-Read the whole module before changing it: `spec/module.yaml`, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
+Read the whole module before changing it: `spec/module.yaml`, `design/*.html` when the change touches a screen, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
 
 Sandbox facts for an edit session (`packages/sandbox/src/server/sessions.ts`): the module is copied to `workspace/modules/<dir>` and a pristine copy to `base/modules/<dir>`; the diff shown to the operator and the eject plan compare the two. The workspace is a pnpm workspace of its own (declared dependencies install for real; a `package.json` change triggers a reinstall that counts as the `dependencies` gate). The business manager updates the spec before implementation. The operator approves the exact spec hash for every affected module; editing that spec, requesting changes, or adding another module reopens its approval gate. A sandbox specialist never writes `status: approved`; a host agent may invoke approval only after an explicit current user request through `spec-approval`. Delivery checks the recorded hash again.
 
@@ -55,9 +55,11 @@ New screen or widget:
 3. `src/client/index.ts`: re-export the view.
 4. Add user-facing copy to every declared `translations/*.json` bundle and resolve it with fully qualified `t()` keys. Navigation copy uses getters because contributions exist before bundles are registered.
 
+New feature flag: a setting with `kind: 'flag'`, `type: 'boolean'`, `scope: 'tenant'` and a `defaultValue`. It reads like any other setting, `context.settings.get<boolean>(tenantId, '<module>.core', 'key')`, and appears on the Flags tab of Administration, Modules beside the module's other flags; a change is audited as `settings.flag.changed`. Declare it in the spec as `kind: flag` too, and state in an invariant what the module does while it is off. Before changing behaviour a workspace already relies on, removing a step, or adding an outward-facing or costly path, propose a flag and let the operator decide: ship the new path behind it, default off, and keep the old path working while it is off. A flag is on or off for one workspace; there is no percentage rollout and no targeting.
+
 New setting:
 
-1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
+1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', kind?: 'flag', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
 2. `src/platform.ts`: return `settings: X_MODULE_SETTINGS` next to `routes`; the platform declares it at boot and Administration, Modules renders it in the module's drawer (`modules/system/src/client/ModuleSettingsSection.tsrx`, behind `system.settings.read` and `system.settings.manage`; the API is `GET /api/settings` and `POST /api/settings/update` in `modules/system/src/server/endpoints.ts`).
 3. Read it live where it is used: `context.settings.get<number>(tenantId, '<module>.core', 'key')` at request time, never cached at boot; pass `context.settings` into the runtime or service that needs it (`modules/agents/src/settings.ts`, `agentSettings`, shows the pattern with an environment fallback).
 4. `spec/module.yaml`: an invariant or scenario naming the setting and its bounds; `specVersion` bump. Cross-module reads of a setting need `visibility: 'shared'` and a declared dependency.

package/agent-template/.agents/skills/spec-interview/SKILL.md

@@ -23,25 +23,26 @@ For an edit, also read the module's current `spec/module.yaml` and write the sma
 
 One pass, in this order. For each row, write the default from the card into the spec and record it as a `decisions[]` entry with `decidedBy: default`. Ask only where the answer is a business fact that no default can supply.
 
-| Decision               | Default to propose                                                                          | Lands in                                 |
-| ---------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| Actors                 | Owner manages, member reads                                                                 | `permissions`, `invariants`              |
-| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name     | `entities[]`                             |
-| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                           | `entities[].fields[].unique`             |
-| States and transitions | `active` and `archived`, every transition behind the manage permission                      | `entities[].states`                      |
-| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope   | `permissions`, `screens[]`, `invariants` |
-| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing              | `acceptanceScenarios`                    |
-| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                | `invariants`, `acceptanceScenarios`      |
-| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency | `dependencies`, `dataOwnership`          |
-| Screens                | One `list` screen with the entity's identifying columns                                     | `screens[]`                              |
-| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it              | `widgets[]`                              |
-| Settings               | None. A number the business may change later is `scope: tenant` with a stated default       | `settings[]`                             |
-| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`            | `agentTools[]`                           |
-| Outside sources        | None. A named public source is `research`, with the entity its findings attach to           | `research`                               |
-| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                 | `adapters[]`                             |
-| Documents              | None. A named document is one `templates[]` entry on the record it describes                | `templates[]`                            |
-| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope  | `outOfScope[]`                           |
-| Out of scope           | Every item from the card's gap list the request touched, each with its business decision    | `outOfScope[]`, `decisions[]`            |
+| Decision               | Default to propose                                                                                                                                                                                  | Lands in                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Actors                 | Owner manages, member reads                                                                                                                                                                         | `permissions`, `invariants`              |
+| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name                                                                                                             | `entities[]`                             |
+| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                                                                                                                                   | `entities[].fields[].unique`             |
+| States and transitions | `active` and `archived`, every transition behind the manage permission                                                                                                                              | `entities[].states`                      |
+| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope                                                                                                           | `permissions`, `screens[]`, `invariants` |
+| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing                                                                                                                      | `acceptanceScenarios`                    |
+| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                                                                                                                        | `invariants`, `acceptanceScenarios`      |
+| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency                                                                                                         | `dependencies`, `dataOwnership`          |
+| Screens                | One `list` screen with the entity's identifying columns                                                                                                                                             | `screens[]`                              |
+| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it                                                                                                                      | `widgets[]`                              |
+| Settings               | None. A number the business may change later is `scope: tenant` with a stated default                                                                                                               | `settings[]`                             |
+| Feature flags          | Ask for one whenever a change alters behaviour a workspace already relies on, or is hard to undo: `kind: flag`, boolean, `scope: tenant`, a stated default, and the behaviour named in an invariant | `settings[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`                                                                                                                    | `agentTools[]`                           |
+| Outside sources        | None. A named public source is `research`, with the entity its findings attach to                                                                                                                   | `research`                               |
+| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                                                                                                                         | `adapters[]`                             |
+| Documents              | None. A named document is one `templates[]` entry on the record it describes                                                                                                                        | `templates[]`                            |
+| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope                                                                                                          | `outOfScope[]`                           |
+| Out of scope           | Every item from the card's gap list the request touched, each with its business decision                                                                                                            | `outOfScope[]`, `decisions[]`            |
 
 A default you propose is still a decision: it goes into `decisions[]` so the operator can see and overturn it, and so the next agent never re-derives it.
 
@@ -89,7 +90,7 @@ A number the case needs (a score, a premium, a price per square metre) is an `ac
 - `screens[]`: `{ id, kind: list|record|form|dashboard, entity?, title?, columns?, filters?, navigationGroup? }`. `navigationGroup` is one of the six values on the card.
 - `actions[]`: `{ id, entity?, permission, kind: create|update|delete|custom, risk, idempotent, description }`. `risk: external` is refused by the platform, so an action may not declare it.
 - `widgets[]`: `{ id, slot, entity?, description }`; `slot` is one of the four workspace slots.
-- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, default?, values?, description }`.
+- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, kind?: setting|flag, default?, values?, description }`. A `flag` is boolean, `scope: tenant` and carries a default; owners switch it per workspace on the Flags tab of Administration, Modules, and every change is audited. Ask whether the new behaviour ships behind one: a change to something a workspace already does, an outward-facing action, a costly or slow path, or anything a business would want to turn off without a deployment. Say what the module does with the flag off, as an invariant.
 - `agentTools[]`: `{ id, permission, description, risk: read|workspace-write }`.
 - `outOfScope[]`: plain sentences, each naming the gap and the decision taken instead.
 - `decisions[]`: `{ id, question, answer, decidedBy: user|default }`; ids match `^[A-Z][A-Z0-9-]+$`, for example `D-UNIQUE-SKU`.

package/agent-template/.agents/skills/ux-design/SKILL.md

@@ -93,7 +93,28 @@ Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `u
 
 User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
 
-## 7. Inspect the rendered screen
+## 7. Design the screen as a preview first
+
+A design is a file, not a description: `modules/<dir>/design/<screen>.html`, beside the spec. It is markup only, dressed by the platform's own stylesheets, so it shows what the screen will look like before a component exists and long before the application boots. An implementation phase reads it the way it reads the spec.
+
+```bash
+pnpm ui:preview modules/<dir>/design/<screen>.html --scaffold   # the record recipe in all five states
+pnpm ui:preview modules/<dir>/design/<screen>.html              # renders it, prints a file:// address
+pnpm ui:preview modules/<dir>/design/<screen>.html --shot .flowdular/ui-preview/<screen>.png
+pnpm ui:preview modules/<dir>/design/<screen>.html --open           # shows it to the person asking
+```
+
+Rules that keep a preview honest:
+
+- Markup only. No `<style>`, no CSS rule, no `<html>` or `<body>`; the command refuses a fragment that carries one. Every visual decision comes from `packages/ui`, which is what stops a preview from becoming a second source of truth.
+- One `<section class="ui-view" data-state="...">` per state: `populated`, `loading`, `empty`, `error`, `denied`. The command labels each one, so a single page answers for all five.
+- Real content. The longest realistic name, a real identifier, the copy the screen will actually carry. A preview of `Lorem ipsum` proves nothing about overflow or alignment.
+- Only classes a stylesheet declares. `pnpm ui-classes:check` fails on a class nothing defines, in a preview and in a `.tsrx` alike, which is the one mistake that compiles, passes its tests and renders unstyled. A class a module needs and the design system lacks is declared in the module's own CSS, as rule 4 says.
+- `--shot` writes a PNG, which is how an agent with no browser looks at its own work. `--open` opens the preview in the person's browser, which is how a design is shown for approval; a correction loop renders without it rather than throwing a window at whoever is at the keyboard.
+
+Hand off the path, not a description. An implementation phase opens the preview, mirrors its structure with the components in section 4, and keeps the copy.
+
+## 8. Inspect the rendered screen
 
 A screen is not finished until it has been looked at. Typecheck and tests say nothing about overflow, alignment, a duplicate label or a column that collapses.
 
@@ -117,6 +138,7 @@ Check the drawer form in the same pass: one label per field, fields top-aligned,
 
 ## Pitfalls
 
+- A preview that renders unstyled is a class nothing declares, not a broken harness; run `pnpm ui-classes:check`.
 - `Kpi value={items.length}` does not typecheck; use `String(items.length)`.
 - A `Tag` for a lifecycle state uses `success` for active and `neutral` for archived, with `dot`.
 - An `Icon` inside `Button size="sm"` is 14, not 18.

package/agent-template/.ai/platform-capabilities.md

@@ -8,7 +8,11 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Tenant identity.** Every request carries a principal resolved by `modules/auth`. `principalFromContext(octane)!.tenantId` is the only tenant authority; a tenant id from a body, query or header is a defect. Row-level security binds the same id inside the transaction.
 
-**Authorization.** `defineEndpoint` (`packages/server/src/endpoint.ts`) takes `id`, `path`, `methods`, `handler` and `access`. `access` is either `{ kind: 'public' }` or `{ kind: 'permission', permission }` with `resolveIdentity: endpointIdentityFromContext`. A protected endpoint answers 401 `UNAUTHENTICATED` without an identity and 403 `FORBIDDEN` without the permission. Permission ids match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$` and are declared in the spec `permissions`, in `src/acl/permissions.ts` and on the endpoint. CSRF and input bounds are not endpoint options: mutations call `sessionMutationDenial(octane, auth)` first (`modules/auth/src/server/session-security.ts`) and parse the body through `readJsonObject`, `requiredString`, `optionalString`, `requiredInteger` (`packages/server/src/http.ts`, 415 without JSON, 413 over 16 KB).
+**Authorization.** `defineEndpoint` (`packages/server/src/endpoint.ts`) takes `id`, `path`, `methods`, `handler` and `access`. `access` is either `{ kind: 'public' }` or `{ kind: 'permission', permission }` with `resolveIdentity: endpointIdentityFromContext`. A protected endpoint answers 401 `UNAUTHENTICATED` without an identity and 403 `FORBIDDEN` without the permission. Permission ids match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$` and are declared in the spec `permissions`, in `src/acl/permissions.ts` and on the endpoint. CSRF and input bounds are not endpoint options: mutations call `sessionMutationDenial(octane, auth)` first (`modules/auth/src/server/session-security.ts`) and parse the body through `readJsonObject`, `requiredString`, `optionalString`, `requiredInteger` (`packages/server/src/http.ts`, 415 without JSON, 413 over 16 KB). That same guard is what admits a machine caller: it passes a browser session with a same origin and a valid CSRF token, or an API token the workspace issued with writes allowed, and answers 403 `TOKEN_MUTATION_DENIED` to a token issued without them. A mutation that shapes who may reach the workspace calls `browserSessionMutationDenial` instead, which refuses every token; auth.core's own routes are the ones that do.
+
+**External API.** Every endpoint records itself in the process endpoint catalogue as it is defined (`packages/server/src/endpoint-catalog.ts`), so a module is described without declaring anything twice. `defineEndpoint` takes an optional `documentation` with `summary`, `description`, `parameters`, `body` and `responses`, validated at definition time and bounded (160-character summary, 32 parameters, 16 responses, 16 KB per JSON Schema); an endpoint that declares none is still described by its address, its methods and the permission it demands. `GET /api/openapi.json` (`platform/src/server/openapi.ts`) answers OpenAPI 3.1 built for the presented credential: it needs a browser session or an API token, and leaves out every operation whose permission the caller does not hold and every operation of a module inactive in its workspace. Each operation carries `x-flowdular-module`, `x-flowdular-permission` and `x-flowdular-token-write`. The Administration screen `system.core` API lists the same document. A module adds nothing to be included; it is in the document as soon as it composes.
+
+**API tokens and cross-origin access.** A workspace owner issues a token in Administration, API tokens, with the scopes it may use, an optional expiry, whether it may write, and the browser origins it may be presented from (`modules/auth/src/server/token-endpoints.ts`). Its authority is the intersection of its recorded scopes with the live membership at every request. Writes are off unless the owner asked; a token that names no origin is refused from every browser origin and is meant for a server-side caller; a token that names some is refused from anywhere else with 403 `TOKEN_ORIGIN_DENIED`. A cross-origin preflight carries no credential, so `createCorsMiddleware` (`packages/server/src/cors.ts`, composed in `platform/octane.config.ts`) answers it from the union of the origins the deployment's live tokens declare, and never sends `access-control-allow-credentials`, so no cross-origin page can read an API response with the dashboard's session cookie. A token also carries the requests per minute it may spend, and one issued with none spends the platform setting `auth.core.apiTokenRateLimit` (default 600, 0 removes the ceiling); the request over it is answered 429 `TOKEN_RATE_LIMITED` with `retry-after`, every answer to a limited token carries `x-ratelimit-limit`, `-remaining` and `-reset`, and every request a token made, refused ones included, plus the refused subset, are counted as auth.core module metrics on `/api/metrics`. The window is a fixed minute per token in each process (`modules/auth/src/middleware/rate-limit.ts`), bounded to 4096 credentials, so it guards against one integration running away rather than accounting for usage. Nothing here is an environment variable; issuing or revoking a token, or changing the setting, takes effect live.
 
 **Record policies.** A permission answers who may act on a kind of record; a policy answers whether this record allows it. `definePolicy` (`packages/kernel/src/acl.ts`) declares `{ id, permission, evaluate }`, where `evaluate({ principal, permission, record, action })` returns `{ allowed: true }` or `{ allowed: false, reason, requiresApproval? }`; `requiresApproval.requirement` carries `roleKey`, `scope`, `decisions` and `expiresInDays`, and nothing more: resolving a role to people, collecting their decisions and keeping the receipt belong to `approvals.core`, described below. Policies are registered into a `createPolicyRegistry()` while the module composes, at most 256, one registration per id, and the registry is sealed before requests run. An endpoint calls `authorizeRecord(registry, principal, permission, record, action?)`, which checks the permission scope first and then the policies of that permission in registration order, answering the first denial. A permission with no policy is allowed by the scope alone, and a policy that throws denies. The platform does not hand a module a shared registry yet, so a module that wants record conditions today owns its registry inside its own composition.
 
@@ -22,7 +26,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Module settings.** `defineModuleSettings` (`packages/kernel/src/module-settings.ts`) declares `{ moduleId, settings }`. A setting has `type: 'string' | 'number' | 'boolean'`, `defaultValue`, `visibility: 'private' | 'shared'`, `client: boolean`, and optionally `kind: 'flag'`, `scope: 'platform' | 'tenant'`, `secret`, `labelKey`, `descriptionKey`, `label`, `description`, `enum` (string type only), `min`, `max`, `pattern`, `multiline`. Keys match `^[a-z][a-zA-Z0-9]*$`. The allowed-values field is `enum`, not `values`. A `secret` setting can be neither `client: true` nor `visibility: 'shared'`. Values are read live with `context.settings.get(tenantId, moduleId, key)` and edited in Administration, Modules behind `system.settings.read` and `system.settings.manage` (`GET /api/settings`, `POST /api/settings/update`, `modules/system/src/server/endpoints.ts`). A read needs the tenant primed first (`await context.settings.prime(tenantId)`): the authenticated request path and the platform composition prime, a background path primes itself, and `set` is awaited.
 
-**Feature flags.** A flag is a module setting declared `kind: 'flag'`: a non-secret `boolean` with a `defaultValue`, a `label`, a `description` and `scope: 'tenant'`, which is the default and the only scope a flag may take; `defineModuleSettings` refuses anything else, a platform-scoped flag included. There is no flag store, no flag endpoint and no flag registry. A module reads one on the request path with the ordinary settings read, `context.settings.get<boolean>(tenantId, moduleId, key)`: a lookup of the declaration, a lookup of the cached per `(tenant, module)` value set under a key the read builds, the touch that keeps that entry at the head of the cache, the property read and one `typeof` check. No query of its own, and nothing beyond what any setting already costs: a declared `pattern` is compiled once with the declaration, never per read. There is deliberately no `context.flags`; the read is the settings read, and the module id is the one the module already knows. An override is per workspace behind `system.settings.manage` on the Flags tab of Administration, Modules, which groups every declared flag by its owning module and links the audit trail. Every change appends one `settings.flag.changed` auth audit event with the module, the key, the previous and next values and the actor (`settings.updated` stays the event for every other setting). No percentage rollout and no targeting: a flag is on or off for a workspace.
+**Feature flags.** A flag is a module setting declared `kind: 'flag'`: a non-secret `boolean` with a `defaultValue`, a `label`, a `description` and `scope: 'tenant'`, which is the default and the only scope a flag may take; `defineModuleSettings` refuses anything else, a platform-scoped flag included. There is no flag store, no flag endpoint and no flag registry. A module reads one on the request path with the ordinary settings read, `context.settings.get<boolean>(tenantId, moduleId, key)`: a lookup of the declaration, a lookup of the cached per `(tenant, module)` value set under a key the read builds, the touch that keeps that entry at the head of the cache, the property read and one `typeof` check. No query of its own, and nothing beyond what any setting already costs: a declared `pattern` is compiled once with the declaration, never per read. There is deliberately no `context.flags`; the read is the settings read, and the module id is the one the module already knows. An override is per workspace behind `system.settings.manage` on the Flags tab of Administration, Modules, which groups every declared flag by its owning module and links the audit trail. Every change appends one `settings.flag.changed` auth audit event with the module, the key, the previous and next values and the actor (`settings.updated` stays the event for every other setting). No percentage rollout and no targeting: a flag is on or off for a workspace. A specification declares one as a `settings[]` entry with `kind: flag`, which `spec validate` holds to boolean, `scope: tenant` and a stated default; `research.core` ships the first one, `allowAgents`.
 
 **Module activation.** The composed module set is CLI-owned and baked at build; what an owner changes from Administration, Modules is per-workspace activation of the modules the application already composes. `system.core` keeps it in `system_module_activations` (a composed module without a row is active), lists it through `GET /api/system/modules` (every catalog row with `active`, `optional` and `dependents`) and `GET /api/system/modules/active` (the active composed ids, for any member holding `system.workspace.access`), and changes it through `POST /api/system/modules/activate` and `/api/system/modules/deactivate` behind `system.settings.manage` with CSRF first. `system.core`, `auth.core`, `users.core` and `profile.core` (`REQUIRED_MODULE_IDS` in `@flowdular/sdk/contracts`) are never deactivated; a module another active module depends on, through a declared module dependency or a required capability, is refused with 409 `MODULE_HAS_ACTIVE_DEPENDENTS` naming the dependents, a required one with 409 `MODULE_REQUIRED`, and activating a module whose dependency is inactive with 409 `MODULE_DEPENDENCY_INACTIVE`. Every change appends one `system.module.activated` or `system.module.deactivated` auth audit event. The state is one per-tenant snapshot memoised for 30 seconds and published as the public capability `system.modules.v1` (`isActive(tenantId, moduleId)`, `activeIds(tenantId)`, `modules/system/src/server/capability.ts`). Enforcement costs a module nothing: the generated composition binds every route to its module id (`bindModuleCompositions`, `packages/server/src/module-activation.ts`), `defineEndpoint` answers 403 `MODULE_INACTIVE` after the permission check for an endpoint of an inactive module in the principal's workspace (`EndpointIdentity.tenantId` comes from `endpointIdentityFromContext`), and the application shell reads the active ids before it renders and hides the navigation, views, widgets and command search of an inactive module (`contributionsForActiveModules`, `packages/client/src/shell/modules.ts`; a failed read shows everything). Not covered yet: the agent tools of an inactive module are still offered, because the harness registry has no per-tenant module hook.
 
@@ -56,13 +60,13 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Translations.** The shipped locales are `en` and `pl`. A module keeps a flat bundle per locale in `translations/<locale>.json`, imports them in `src/client/contribution.tsrx` and returns `translations: { en, pl }`. Keys resolve fully qualified as `<first module segment>.<key>` through `t()`. A count is a plural family (`<key>.one`/`.other` in `en`, `<key>.one`/`.few`/`.many`/`.other` in `pl`) read as `t(key, { count })`. `flowdular module validate` reports `TRANSLATION_FILE_MISSING`, `TRANSLATION_PARSE_ERROR`, `TRANSLATION_KEYS_MISMATCH`, `TRANSLATION_PLURAL_INCOMPLETE` and `TRANSLATION_KEY_MISSING`.
 
-**Web surfaces.** A module may own public, server-rendered website pages separate from the authenticated shell (`packages/server/src/web.ts`). `defineWebSurface` declares `{ id, pages }` with at most 128 pages; a page has `id`, `path`, `entry`, optional `layout`, a `load` function and `access`, which is one of `{ kind: 'public' }`, `{ kind: 'authenticated' }` or `{ kind: 'permission', permission }`. The operator, not the module, mounts a surface at a tenant-scoped path; `setup`, `health`, `ready`, `assets`, `app`, `api`, `auth`, `sign-in`, `sign-up`, `forgot-password`, `reset-password` and `accept-invitation` are reserved.
+**Web surfaces.** A module may own public, server-rendered website pages separate from the authenticated shell (`packages/server/src/web.ts`). `defineWebSurface` declares `{ id, pages }` with at most 128 pages; a page has `id`, `path`, `entry`, optional `layout`, a `load` function and `access`, which is one of `{ kind: 'public' }`, `{ kind: 'authenticated' }` or `{ kind: 'permission', permission }`. The operator, not the module, mounts a surface at a tenant-scoped path with `pnpm flowdular web mount <module id> <surface id> --path <path> --tenant <id> --apply`, which writes `flowdular.json` and regenerates the composition (`web list` and `web unmount <mount id>` are its siblings); `setup`, `health`, `ready`, `assets`, `app`, `api`, `auth`, `sign-in`, `sign-up`, `forgot-password`, `reset-password` and `accept-invitation` are reserved (`RESERVED_WEB_SEGMENTS` in `@flowdular/sdk/contracts`), and a mount naming a surface its module does not declare stops the composition rather than answering 404.
 
 **Public capabilities registry.** Cross-module access goes through `context.capabilities.register(id, value)` in the owning module and `context.capabilities.get<T>(id)` in the consumer (`packages/kernel/src/capability-registry.ts`). The owning module lists the id under `provides` in `module.json`; the consumer lists it under `requires` (`{ "id", "optional": true }` when it handles a null `get`). The composition gives each module a registry view that accepts only its declared ids, the kernel orders required providers first and refuses a missing provider, and the installer resolves a required capability to a release that provides it. A type import from the provider's package still needs the module and package dependency (`"range": "^0.11.0"`). A module never opens another module's database or imports its `src/` path.
 
 **Notifications.** `notifications.core` (optional, enabled by default) owns a per-member in-app inbox with preferences, per-tenant outbound webhook subscriptions signed with the inbound automations scheme, and e-mail delivery of inbox items, all three sharing one delivery ledger with bounded retry and a dead letter. A module publishes through the public capability `notifications.publish.v1` obtained lazily with `context.capabilities.get` and tolerates its absence; the input is `{ tenantId, kind, sourceModule, sourceRef, title, body?, recipients }` with the kinds `agent-run-completed`, `agent-run-failed`, `workflow-run-completed`, `workflow-run-failed`, `webhook-dead-letter` (`modules/notifications/src/domain/publish.ts`). A new kind is a `notifications.core` spec edit, not a publisher's decision. A publisher never chooses a channel: the member does, with the per-kind switch that decides whether an item exists at all and the `emailDelivery` switch (off by default) that also mails the items they receive, through the platform mail port and the address `auth.core` holds. `ToastHost` and `toasts` remain the in-screen confirmation for what the reader just did.
 
-**Mail.** A module sends through `context.mail` (`packages/server/src/mail/`) and never selects a transport, a relay or a provider SDK. `send({ to, subject, text, html?, locale?, headers? })` takes at most 16 recipients, a 200 character single-line subject, 64 KB of text, 256 KB of HTML and 16 extra headers whose names the envelope does not own; CR and LF are refused everywhere a header could be opened, so header injection is the port's problem and not each sender's. It rejects with a `MailError` carrying `MAIL_NOT_CONFIGURED` (no transport composed), `MAIL_MESSAGE_REJECTED` (a bound) or `MAIL_DELIVERY_FAILED` (the relay, whose words never travel with it); `mail.configured` is the flag a feature gates on instead of provoking a refusal. `renderMailTemplate({ subject, text, html? }, values)` fills `{{ name }}` holes in one pass and escapes every value for the HTML part. The deployment picks the adapter with `FD_MAIL_TRANSPORT`: `none` (refuses), `development` (an in-memory outbox of the last 100 messages, refused in production) or `smtp` (`FD_MAIL_SMTP_URL`, `FD_MAIL_FROM`; the retired `FD_AUTH_MAIL_*` names still work with a deprecation line). `auth.core` sends invitations, resets and confirmations through it, `notifications.core` mails inbox items; a module that wants to reach a person publishes a notification rather than composing mail of its own.
+**Mail.** A module sends through `context.mail` (`packages/server/src/mail/`) and never selects a transport, a relay or a provider SDK. `send({ to, subject, text, html?, locale?, headers? })` takes at most 16 recipients, a 200 character single-line subject, 64 KB of text, 256 KB of HTML and 16 extra headers whose names the envelope does not own; CR and LF are refused everywhere a header could be opened, so header injection is the port's problem and not each sender's. It rejects with a `MailError` carrying `MAIL_NOT_CONFIGURED` (no transport composed), `MAIL_MESSAGE_REJECTED` (a bound) or `MAIL_DELIVERY_FAILED` (the relay, whose words never travel with it); `mail.configured` is the flag a feature gates on instead of provoking a refusal. `renderMailTemplate({ subject, text, html? }, values)` fills `{{ name }}` holes in one pass and escapes every value for the HTML part. The deployment picks the adapter with `FD_MAIL_TRANSPORT`: `none` (refuses), `development` (an in-memory outbox of the last 100 messages, refused in production) or `smtp` (`FD_MAIL_SMTP_URL`, `FD_MAIL_FROM`; the retired `FD_AUTH_MAIL_*` names still work with a deprecation line). An installation may instead store the relay in the platform-scoped `auth.core` settings `mailTransport`, `mailSmtpUrl` (secret), `mailFrom`, `mailRequireTls` and `mailRejectUnauthorized`; a stored transport of `none` or `smtp` wins over the environment for every sender and is resolved per message, while the default `environment` leaves `FD_MAIL_*` in effect and is the only way to reach the development adapter. `auth.core` sends invitations, resets and confirmations through it, `notifications.core` mails inbox items; a module that wants to reach a person publishes a notification rather than composing mail of its own.
 
 **Object storage.** A module writes files through `context.storage` (`packages/storage/src/index.ts`) and never sees an adapter, a bucket or a path. `put`, `get`, `delete`, `stat` and `readUrl` take `{ tenantId, moduleId, objectId }`; the key is `<tenantId>/<moduleId>/<objectId>` and the tenant id comes from the principal, never from the request, because no row-level security reaches an object store. Development and test use a local directory, a deployment uses an S3-compatible bucket (`FD_STORAGE_ADAPTER=local|s3`, `local` refused in production). Every object is encrypted with AES-256-GCM under `FD_STORAGE_ENCRYPTION_KEY` before it is written, with the key id and the metadata authenticated alongside it. An object is at most 25 MB (`FD_STORAGE_MAX_OBJECT_BYTES`) and must be one of PDF, PNG, JPEG, GIF, WebP, plain text, CSV, `.docx`, `.xlsx`, `.pptx`, `application/msword` or `application/vnd.ms-excel`, verified against the bytes; archives and executables are refused. A malware scanner is a deployment seam, so the stored verdict is `clean`, `infected` (refused) or `unscanned` (the default). `readUrl` returns `/api/storage/objects/<token>`, a signed platform route that expires in at most an hour and streams the decrypted body as an attachment, never a presigned URL to the ciphertext. Upload, metadata and the attachment table belong to `documents.core`, described next; a module never puts bytes of its own through `context.storage` when a document fits.
 

package/agent-template/.ai/policies/capabilities.yaml

@@ -104,6 +104,7 @@ commandsWithoutDescriptor:
   - pnpm flowdular capability list|describe <id>|run <id>
   - pnpm flowdular blueprint list
   - pnpm flowdular module list
+  - pnpm flowdular web list
   - pnpm flowdular module sync [--apply]
   - pnpm flowdular module enable <id> [--apply] (with --apply also runs auth.scopes.sync; result field scopes, failure code MODULE_SCOPES_SYNC_FAILED)
   - pnpm flowdular module disable <id> [--apply]

package/agent-template/.ai/skills/module-new/SKILL.md

@@ -26,25 +26,26 @@ Every `acceptanceScenarios[]` entry maps to at least one test in `tests/`. A sce
 
 Each spec element maps to files:
 
-| Spec element                  | Files it produces                                                                                                                                       |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts` |
-| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                |
-| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                     |
-| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                      |
-| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                       |
-| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                               |
-| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                          |
-| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                    |
-| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                             |
-| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`                                                                         |
-| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                |
-| `research`                    | `src/research.ts`, `research-fixtures.json`, `requires` of the capabilities, the evidence attach where the `evidenceOwner` record is written            |
-| `adapters[]`                  | `src/adapters/<name>.ts`, the port, the adapter registration, `adapters/<name>.recorded.json`, as a separate `integration-adapter` phase                |
-| `templates[]`                 | `templates/<name>.md`, `templates` in `package.json` `files`, `src/templates.ts` registered through `documents.templates.v1` in `src/platform.ts`       |
-| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                          |
-| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                         |
-| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                    |
+| Spec element                  | Files it produces                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts`                                           |
+| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                                                          |
+| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                                                               |
+| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                                                                |
+| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                                                                 |
+| `design/<screen>.html`        | the approved look of that screen: mirror its structure and keep its copy. Render it with `pnpm ui:preview <path>`; absent, design it first with `ux-design`                                       |
+| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                                                                         |
+| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                                                                    |
+| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                                                              |
+| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                                                                       |
+| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`; a `kind: flag` entry keeps `kind: 'flag'` there, so owners switch it on the Flags tab of Administration, Modules |
+| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                                                          |
+| `research`                    | `src/research.ts`, `research-fixtures.json`, `requires` of the capabilities, the evidence attach where the `evidenceOwner` record is written                                                      |
+| `adapters[]`                  | `src/adapters/<name>.ts`, the port, the adapter registration, `adapters/<name>.recorded.json`, as a separate `integration-adapter` phase                                                          |
+| `templates[]`                 | `templates/<name>.md`, `templates` in `package.json` `files`, `src/templates.ts` registered through `documents.templates.v1` in `src/platform.ts`                                                 |
+| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                                                                    |
+| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                                                                   |
+| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                                                              |
 
 A v1 spec stays valid and carries none of these arrays. Then the requirements are `invariants`, `permissions` and `acceptanceScenarios`, and everything the spec leaves open is still a question rather than a guess.
 

package/agent-template/.ai/skills/module-update/SKILL.md

@@ -23,7 +23,7 @@ The spec-element to file mapping is the table in `module-new`; the change classe
 
 ## 1. Read first
 
-Read the whole module before changing it: `spec/module.yaml`, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
+Read the whole module before changing it: `spec/module.yaml`, `design/*.html` when the change touches a screen, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
 
 Sandbox facts for an edit session (`packages/sandbox/src/server/sessions.ts`): the module is copied to `workspace/modules/<dir>` and a pristine copy to `base/modules/<dir>`; the diff shown to the operator and the eject plan compare the two. The workspace is a pnpm workspace of its own (declared dependencies install for real; a `package.json` change triggers a reinstall that counts as the `dependencies` gate). The business manager updates the spec before implementation. The operator approves the exact spec hash for every affected module; editing that spec, requesting changes, or adding another module reopens its approval gate. A sandbox specialist never writes `status: approved`; a host agent may invoke approval only after an explicit current user request through `spec-approval`. Delivery checks the recorded hash again.
 
@@ -62,9 +62,11 @@ New screen or widget:
 3. `src/client/index.ts`: re-export the view.
 4. Add user-facing copy to every declared `translations/*.json` bundle and resolve it with fully qualified `t()` keys. Navigation copy uses getters because contributions exist before bundles are registered.
 
+New feature flag: a setting with `kind: 'flag'`, `type: 'boolean'`, `scope: 'tenant'` and a `defaultValue`. It reads like any other setting, `context.settings.get<boolean>(tenantId, '<module>.core', 'key')`, and appears on the Flags tab of Administration, Modules beside the module's other flags; a change is audited as `settings.flag.changed`. Declare it in the spec as `kind: flag` too, and state in an invariant what the module does while it is off. Before changing behaviour a workspace already relies on, removing a step, or adding an outward-facing or costly path, propose a flag and let the operator decide: ship the new path behind it, default off, and keep the old path working while it is off. A flag is on or off for one workspace; there is no percentage rollout and no targeting.
+
 New setting:
 
-1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
+1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', kind?: 'flag', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
 2. `src/platform.ts`: return `settings: X_MODULE_SETTINGS` next to `routes`; the platform declares it at boot and Administration, Modules renders it in the module's drawer (`modules/system/src/client/ModuleSettingsSection.tsrx`, behind `system.settings.read` and `system.settings.manage`; the API is `GET /api/settings` and `POST /api/settings/update` in `modules/system/src/server/endpoints.ts`).
 3. Read it live where it is used: `context.settings.get<number>(tenantId, '<module>.core', 'key')` at request time, never cached at boot; pass `context.settings` into the runtime or service that needs it (`modules/agents/src/settings.ts`, `agentSettings`, shows the pattern with an environment fallback).
 4. `spec/module.yaml`: an invariant or scenario naming the setting and its bounds; `specVersion` bump. Cross-module reads of a setting need `visibility: 'shared'` and a declared dependency.

package/agent-template/.ai/skills/spec-interview/SKILL.md

@@ -29,25 +29,26 @@ For an edit, also read the module's current `spec/module.yaml` and write the sma
 
 One pass, in this order. For each row, write the default from the card into the spec and record it as a `decisions[]` entry with `decidedBy: default`. Ask only where the answer is a business fact that no default can supply.
 
-| Decision               | Default to propose                                                                          | Lands in                                 |
-| ---------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| Actors                 | Owner manages, member reads                                                                 | `permissions`, `invariants`              |
-| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name     | `entities[]`                             |
-| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                           | `entities[].fields[].unique`             |
-| States and transitions | `active` and `archived`, every transition behind the manage permission                      | `entities[].states`                      |
-| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope   | `permissions`, `screens[]`, `invariants` |
-| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing              | `acceptanceScenarios`                    |
-| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                | `invariants`, `acceptanceScenarios`      |
-| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency | `dependencies`, `dataOwnership`          |
-| Screens                | One `list` screen with the entity's identifying columns                                     | `screens[]`                              |
-| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it              | `widgets[]`                              |
-| Settings               | None. A number the business may change later is `scope: tenant` with a stated default       | `settings[]`                             |
-| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`            | `agentTools[]`                           |
-| Outside sources        | None. A named public source is `research`, with the entity its findings attach to           | `research`                               |
-| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                 | `adapters[]`                             |
-| Documents              | None. A named document is one `templates[]` entry on the record it describes                | `templates[]`                            |
-| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope  | `outOfScope[]`                           |
-| Out of scope           | Every item from the card's gap list the request touched, each with its business decision    | `outOfScope[]`, `decisions[]`            |
+| Decision               | Default to propose                                                                                                                                                                                  | Lands in                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Actors                 | Owner manages, member reads                                                                                                                                                                         | `permissions`, `invariants`              |
+| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name                                                                                                             | `entities[]`                             |
+| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                                                                                                                                   | `entities[].fields[].unique`             |
+| States and transitions | `active` and `archived`, every transition behind the manage permission                                                                                                                              | `entities[].states`                      |
+| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope                                                                                                           | `permissions`, `screens[]`, `invariants` |
+| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing                                                                                                                      | `acceptanceScenarios`                    |
+| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                                                                                                                        | `invariants`, `acceptanceScenarios`      |
+| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency                                                                                                         | `dependencies`, `dataOwnership`          |
+| Screens                | One `list` screen with the entity's identifying columns                                                                                                                                             | `screens[]`                              |
+| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it                                                                                                                      | `widgets[]`                              |
+| Settings               | None. A number the business may change later is `scope: tenant` with a stated default                                                                                                               | `settings[]`                             |
+| Feature flags          | Ask for one whenever a change alters behaviour a workspace already relies on, or is hard to undo: `kind: flag`, boolean, `scope: tenant`, a stated default, and the behaviour named in an invariant | `settings[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`                                                                                                                    | `agentTools[]`                           |
+| Outside sources        | None. A named public source is `research`, with the entity its findings attach to                                                                                                                   | `research`                               |
+| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                                                                                                                         | `adapters[]`                             |
+| Documents              | None. A named document is one `templates[]` entry on the record it describes                                                                                                                        | `templates[]`                            |
+| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope                                                                                                          | `outOfScope[]`                           |
+| Out of scope           | Every item from the card's gap list the request touched, each with its business decision                                                                                                            | `outOfScope[]`, `decisions[]`            |
 
 A default you propose is still a decision: it goes into `decisions[]` so the operator can see and overturn it, and so the next agent never re-derives it.
 
@@ -95,7 +96,7 @@ A number the case needs (a score, a premium, a price per square metre) is an `ac
 - `screens[]`: `{ id, kind: list|record|form|dashboard, entity?, title?, columns?, filters?, navigationGroup? }`. `navigationGroup` is one of the six values on the card.
 - `actions[]`: `{ id, entity?, permission, kind: create|update|delete|custom, risk, idempotent, description }`. `risk: external` is refused by the platform, so an action may not declare it.
 - `widgets[]`: `{ id, slot, entity?, description }`; `slot` is one of the four workspace slots.
-- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, default?, values?, description }`.
+- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, kind?: setting|flag, default?, values?, description }`. A `flag` is boolean, `scope: tenant` and carries a default; owners switch it per workspace on the Flags tab of Administration, Modules, and every change is audited. Ask whether the new behaviour ships behind one: a change to something a workspace already does, an outward-facing action, a costly or slow path, or anything a business would want to turn off without a deployment. Say what the module does with the flag off, as an invariant.
 - `agentTools[]`: `{ id, permission, description, risk: read|workspace-write }`.
 - `outOfScope[]`: plain sentences, each naming the gap and the decision taken instead.
 - `decisions[]`: `{ id, question, answer, decidedBy: user|default }`; ids match `^[A-Z][A-Z0-9-]+$`, for example `D-UNIQUE-SKU`.

package/agent-template/.ai/skills/ux-design/SKILL.md

@@ -98,7 +98,28 @@ Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `u
 
 User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
 
-## 7. Inspect the rendered screen
+## 7. Design the screen as a preview first
+
+A design is a file, not a description: `modules/<dir>/design/<screen>.html`, beside the spec. It is markup only, dressed by the platform's own stylesheets, so it shows what the screen will look like before a component exists and long before the application boots. An implementation phase reads it the way it reads the spec.
+
+```bash
+pnpm ui:preview modules/<dir>/design/<screen>.html --scaffold   # the record recipe in all five states
+pnpm ui:preview modules/<dir>/design/<screen>.html              # renders it, prints a file:// address
+pnpm ui:preview modules/<dir>/design/<screen>.html --shot .flowdular/ui-preview/<screen>.png
+pnpm ui:preview modules/<dir>/design/<screen>.html --open           # shows it to the person asking
+```
+
+Rules that keep a preview honest:
+
+- Markup only. No `<style>`, no CSS rule, no `<html>` or `<body>`; the command refuses a fragment that carries one. Every visual decision comes from `packages/ui`, which is what stops a preview from becoming a second source of truth.
+- One `<section class="ui-view" data-state="...">` per state: `populated`, `loading`, `empty`, `error`, `denied`. The command labels each one, so a single page answers for all five.
+- Real content. The longest realistic name, a real identifier, the copy the screen will actually carry. A preview of `Lorem ipsum` proves nothing about overflow or alignment.
+- Only classes a stylesheet declares. `pnpm ui-classes:check` fails on a class nothing defines, in a preview and in a `.tsrx` alike, which is the one mistake that compiles, passes its tests and renders unstyled. A class a module needs and the design system lacks is declared in the module's own CSS, as rule 4 says.
+- `--shot` writes a PNG, which is how an agent with no browser looks at its own work. `--open` opens the preview in the person's browser, which is how a design is shown for approval; a correction loop renders without it rather than throwing a window at whoever is at the keyboard.
+
+Hand off the path, not a description. An implementation phase opens the preview, mirrors its structure with the components in section 4, and keeps the copy.
+
+## 8. Inspect the rendered screen
 
 A screen is not finished until it has been looked at. Typecheck and tests say nothing about overflow, alignment, a duplicate label or a column that collapses.
 
@@ -122,6 +143,7 @@ Check the drawer form in the same pass: one label per field, fields top-aligned,
 
 ## Pitfalls
 
+- A preview that renders unstyled is a class nothing declares, not a broken harness; run `pnpm ui-classes:check`.
 - `Kpi value={items.length}` does not typecheck; use `String(items.length)`.
 - A `Tag` for a lifecycle state uses `success` for active and `neutral` for archived, with `dot`.
 - An `Icon` inside `Button size="sm"` is 14, not 18.

package/agent-template/.claude/skills/module-new/SKILL.md

@@ -20,25 +20,26 @@ Every `acceptanceScenarios[]` entry maps to at least one test in `tests/`. A sce
 
 Each spec element maps to files:
 
-| Spec element                  | Files it produces                                                                                                                                       |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts` |
-| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                |
-| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                     |
-| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                      |
-| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                       |
-| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                               |
-| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                          |
-| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                    |
-| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                             |
-| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`                                                                         |
-| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                |
-| `research`                    | `src/research.ts`, `research-fixtures.json`, `requires` of the capabilities, the evidence attach where the `evidenceOwner` record is written            |
-| `adapters[]`                  | `src/adapters/<name>.ts`, the port, the adapter registration, `adapters/<name>.recorded.json`, as a separate `integration-adapter` phase                |
-| `templates[]`                 | `templates/<name>.md`, `templates` in `package.json` `files`, `src/templates.ts` registered through `documents.templates.v1` in `src/platform.ts`       |
-| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                          |
-| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                         |
-| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                    |
+| Spec element                  | Files it produces                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts`                                           |
+| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                                                          |
+| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                                                               |
+| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                                                                |
+| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                                                                 |
+| `design/<screen>.html`        | the approved look of that screen: mirror its structure and keep its copy. Render it with `pnpm ui:preview <path>`; absent, design it first with `ux-design`                                       |
+| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                                                                         |
+| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                                                                    |
+| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                                                              |
+| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                                                                       |
+| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`; a `kind: flag` entry keeps `kind: 'flag'` there, so owners switch it on the Flags tab of Administration, Modules |
+| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                                                          |
+| `research`                    | `src/research.ts`, `research-fixtures.json`, `requires` of the capabilities, the evidence attach where the `evidenceOwner` record is written                                                      |
+| `adapters[]`                  | `src/adapters/<name>.ts`, the port, the adapter registration, `adapters/<name>.recorded.json`, as a separate `integration-adapter` phase                                                          |
+| `templates[]`                 | `templates/<name>.md`, `templates` in `package.json` `files`, `src/templates.ts` registered through `documents.templates.v1` in `src/platform.ts`                                                 |
+| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                                                                    |
+| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                                                                   |
+| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                                                              |
 
 A v1 spec stays valid and carries none of these arrays. Then the requirements are `invariants`, `permissions` and `acceptanceScenarios`, and everything the spec leaves open is still a question rather than a guess.
 

package/agent-template/.claude/skills/module-update/SKILL.md

@@ -16,7 +16,7 @@ The spec-element to file mapping is the table in `module-new`; the change classe
 
 ## 1. Read first
 
-Read the whole module before changing it: `spec/module.yaml`, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
+Read the whole module before changing it: `spec/module.yaml`, `design/*.html` when the change touches a screen, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
 
 Sandbox facts for an edit session (`packages/sandbox/src/server/sessions.ts`): the module is copied to `workspace/modules/<dir>` and a pristine copy to `base/modules/<dir>`; the diff shown to the operator and the eject plan compare the two. The workspace is a pnpm workspace of its own (declared dependencies install for real; a `package.json` change triggers a reinstall that counts as the `dependencies` gate). The business manager updates the spec before implementation. The operator approves the exact spec hash for every affected module; editing that spec, requesting changes, or adding another module reopens its approval gate. A sandbox specialist never writes `status: approved`; a host agent may invoke approval only after an explicit current user request through `spec-approval`. Delivery checks the recorded hash again.
 
@@ -55,9 +55,11 @@ New screen or widget:
 3. `src/client/index.ts`: re-export the view.
 4. Add user-facing copy to every declared `translations/*.json` bundle and resolve it with fully qualified `t()` keys. Navigation copy uses getters because contributions exist before bundles are registered.
 
+New feature flag: a setting with `kind: 'flag'`, `type: 'boolean'`, `scope: 'tenant'` and a `defaultValue`. It reads like any other setting, `context.settings.get<boolean>(tenantId, '<module>.core', 'key')`, and appears on the Flags tab of Administration, Modules beside the module's other flags; a change is audited as `settings.flag.changed`. Declare it in the spec as `kind: flag` too, and state in an invariant what the module does while it is off. Before changing behaviour a workspace already relies on, removing a step, or adding an outward-facing or costly path, propose a flag and let the operator decide: ship the new path behind it, default off, and keep the old path working while it is off. A flag is on or off for one workspace; there is no percentage rollout and no targeting.
+
 New setting:
 
-1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
+1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', kind?: 'flag', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
 2. `src/platform.ts`: return `settings: X_MODULE_SETTINGS` next to `routes`; the platform declares it at boot and Administration, Modules renders it in the module's drawer (`modules/system/src/client/ModuleSettingsSection.tsrx`, behind `system.settings.read` and `system.settings.manage`; the API is `GET /api/settings` and `POST /api/settings/update` in `modules/system/src/server/endpoints.ts`).
 3. Read it live where it is used: `context.settings.get<number>(tenantId, '<module>.core', 'key')` at request time, never cached at boot; pass `context.settings` into the runtime or service that needs it (`modules/agents/src/settings.ts`, `agentSettings`, shows the pattern with an environment fallback).
 4. `spec/module.yaml`: an invariant or scenario naming the setting and its bounds; `specVersion` bump. Cross-module reads of a setting need `visibility: 'shared'` and a declared dependency.

package/agent-template/.claude/skills/spec-interview/SKILL.md

@@ -23,25 +23,26 @@ For an edit, also read the module's current `spec/module.yaml` and write the sma
 
 One pass, in this order. For each row, write the default from the card into the spec and record it as a `decisions[]` entry with `decidedBy: default`. Ask only where the answer is a business fact that no default can supply.
 
-| Decision               | Default to propose                                                                          | Lands in                                 |
-| ---------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| Actors                 | Owner manages, member reads                                                                 | `permissions`, `invariants`              |
-| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name     | `entities[]`                             |
-| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                           | `entities[].fields[].unique`             |
-| States and transitions | `active` and `archived`, every transition behind the manage permission                      | `entities[].states`                      |
-| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope   | `permissions`, `screens[]`, `invariants` |
-| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing              | `acceptanceScenarios`                    |
-| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                | `invariants`, `acceptanceScenarios`      |
-| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency | `dependencies`, `dataOwnership`          |
-| Screens                | One `list` screen with the entity's identifying columns                                     | `screens[]`                              |
-| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it              | `widgets[]`                              |
-| Settings               | None. A number the business may change later is `scope: tenant` with a stated default       | `settings[]`                             |
-| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`            | `agentTools[]`                           |
-| Outside sources        | None. A named public source is `research`, with the entity its findings attach to           | `research`                               |
-| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                 | `adapters[]`                             |
-| Documents              | None. A named document is one `templates[]` entry on the record it describes                | `templates[]`                            |
-| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope  | `outOfScope[]`                           |
-| Out of scope           | Every item from the card's gap list the request touched, each with its business decision    | `outOfScope[]`, `decisions[]`            |
+| Decision               | Default to propose                                                                                                                                                                                  | Lands in                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Actors                 | Owner manages, member reads                                                                                                                                                                         | `permissions`, `invariants`              |
+| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name                                                                                                             | `entities[]`                             |
+| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                                                                                                                                   | `entities[].fields[].unique`             |
+| States and transitions | `active` and `archived`, every transition behind the manage permission                                                                                                                              | `entities[].states`                      |
+| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope                                                                                                           | `permissions`, `screens[]`, `invariants` |
+| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing                                                                                                                      | `acceptanceScenarios`                    |
+| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                                                                                                                        | `invariants`, `acceptanceScenarios`      |
+| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency                                                                                                         | `dependencies`, `dataOwnership`          |
+| Screens                | One `list` screen with the entity's identifying columns                                                                                                                                             | `screens[]`                              |
+| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it                                                                                                                      | `widgets[]`                              |
+| Settings               | None. A number the business may change later is `scope: tenant` with a stated default                                                                                                               | `settings[]`                             |
+| Feature flags          | Ask for one whenever a change alters behaviour a workspace already relies on, or is hard to undo: `kind: flag`, boolean, `scope: tenant`, a stated default, and the behaviour named in an invariant | `settings[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`                                                                                                                    | `agentTools[]`                           |
+| Outside sources        | None. A named public source is `research`, with the entity its findings attach to                                                                                                                   | `research`                               |
+| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                                                                                                                         | `adapters[]`                             |
+| Documents              | None. A named document is one `templates[]` entry on the record it describes                                                                                                                        | `templates[]`                            |
+| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope                                                                                                          | `outOfScope[]`                           |
+| Out of scope           | Every item from the card's gap list the request touched, each with its business decision                                                                                                            | `outOfScope[]`, `decisions[]`            |
 
 A default you propose is still a decision: it goes into `decisions[]` so the operator can see and overturn it, and so the next agent never re-derives it.
 
@@ -89,7 +90,7 @@ A number the case needs (a score, a premium, a price per square metre) is an `ac
 - `screens[]`: `{ id, kind: list|record|form|dashboard, entity?, title?, columns?, filters?, navigationGroup? }`. `navigationGroup` is one of the six values on the card.
 - `actions[]`: `{ id, entity?, permission, kind: create|update|delete|custom, risk, idempotent, description }`. `risk: external` is refused by the platform, so an action may not declare it.
 - `widgets[]`: `{ id, slot, entity?, description }`; `slot` is one of the four workspace slots.
-- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, default?, values?, description }`.
+- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, kind?: setting|flag, default?, values?, description }`. A `flag` is boolean, `scope: tenant` and carries a default; owners switch it per workspace on the Flags tab of Administration, Modules, and every change is audited. Ask whether the new behaviour ships behind one: a change to something a workspace already does, an outward-facing action, a costly or slow path, or anything a business would want to turn off without a deployment. Say what the module does with the flag off, as an invariant.
 - `agentTools[]`: `{ id, permission, description, risk: read|workspace-write }`.
 - `outOfScope[]`: plain sentences, each naming the gap and the decision taken instead.
 - `decisions[]`: `{ id, question, answer, decidedBy: user|default }`; ids match `^[A-Z][A-Z0-9-]+$`, for example `D-UNIQUE-SKU`.

package/agent-template/.claude/skills/ux-design/SKILL.md

@@ -93,7 +93,28 @@ Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `u
 
 User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
 
-## 7. Inspect the rendered screen
+## 7. Design the screen as a preview first
+
+A design is a file, not a description: `modules/<dir>/design/<screen>.html`, beside the spec. It is markup only, dressed by the platform's own stylesheets, so it shows what the screen will look like before a component exists and long before the application boots. An implementation phase reads it the way it reads the spec.
+
+```bash
+pnpm ui:preview modules/<dir>/design/<screen>.html --scaffold   # the record recipe in all five states
+pnpm ui:preview modules/<dir>/design/<screen>.html              # renders it, prints a file:// address
+pnpm ui:preview modules/<dir>/design/<screen>.html --shot .flowdular/ui-preview/<screen>.png
+pnpm ui:preview modules/<dir>/design/<screen>.html --open           # shows it to the person asking
+```
+
+Rules that keep a preview honest:
+
+- Markup only. No `<style>`, no CSS rule, no `<html>` or `<body>`; the command refuses a fragment that carries one. Every visual decision comes from `packages/ui`, which is what stops a preview from becoming a second source of truth.
+- One `<section class="ui-view" data-state="...">` per state: `populated`, `loading`, `empty`, `error`, `denied`. The command labels each one, so a single page answers for all five.
+- Real content. The longest realistic name, a real identifier, the copy the screen will actually carry. A preview of `Lorem ipsum` proves nothing about overflow or alignment.
+- Only classes a stylesheet declares. `pnpm ui-classes:check` fails on a class nothing defines, in a preview and in a `.tsrx` alike, which is the one mistake that compiles, passes its tests and renders unstyled. A class a module needs and the design system lacks is declared in the module's own CSS, as rule 4 says.
+- `--shot` writes a PNG, which is how an agent with no browser looks at its own work. `--open` opens the preview in the person's browser, which is how a design is shown for approval; a correction loop renders without it rather than throwing a window at whoever is at the keyboard.
+
+Hand off the path, not a description. An implementation phase opens the preview, mirrors its structure with the components in section 4, and keeps the copy.
+
+## 8. Inspect the rendered screen
 
 A screen is not finished until it has been looked at. Typecheck and tests say nothing about overflow, alignment, a duplicate label or a column that collapses.
 
@@ -117,6 +138,7 @@ Check the drawer form in the same pass: one label per field, fields top-aligned,
 
 ## Pitfalls
 
+- A preview that renders unstyled is a class nothing declares, not a broken harness; run `pnpm ui-classes:check`.
 - `Kpi value={items.length}` does not typecheck; use `String(items.length)`.
 - A `Tag` for a lifecycle state uses `success` for active and `neutral` for archived, with `dot`.
 - An `Icon` inside `Button size="sm"` is 14, not 18.

package/agent-template/docs/cli.md

@@ -33,6 +33,9 @@ flowdular module version <id>                      # version, platformApi range,
 flowdular module version bump <id> <level> [--apply] # patch|minor|major across module.json, package.json, specVersion and dependent ranges
 flowdular module new <id> --spec <path> [--apply]  # scaffold from an approved spec
 flowdular module enable|disable <id> [--apply]     # composition and scope grants
+flowdular web list                                 # the addresses this workspace serves module pages at
+flowdular web mount <module id> <surface id> --path <path> --tenant <id> [--id <mount id>] [--apply]
+flowdular web unmount <mount id> [--apply]         # stop serving that site
 flowdular migration status [--module <id>]         # migration ledger
 flowdular migration apply --module <id> [--apply]
 flowdular migration verify                         # checksum drift, row security, file and constant parity

package/agent-template/docs/configuration.md

@@ -583,6 +583,23 @@ deployment on the old names keeps working and the server logs one
 replacement. The platform name wins when both are set, and every refusal names
 the variable the deployment actually set.
 
+The relay is also five platform-scoped `auth.core` settings, edited under
+Administration, Modules: `mailTransport` (`environment`, `none` or `smtp`),
+`mailSmtpUrl` (secret, write only), `mailFrom`, `mailRequireTls` and
+`mailRejectUnauthorized`. `mailTransport` decides which source wins. It is
+`environment` by default, and while it stays there the `FD_MAIL_*`
+configuration above is in effect exactly as described, deprecation warnings
+included; storing `none` or `smtp` overrides the environment for every sender of
+the installation. `development` is reachable only through the environment and is
+never settable from the UI. A stored relay is resolved when a message is sent,
+so a change carries the next message without a restart, and the built transport
+is cached by a digest of the effective configuration. Storing `smtp` without a
+relay URL or without a sender is refused, as is a URL that is not `smtp://` or
+`smtps://` and a sender the sender rule rejects; the refusal names the setting
+and never carries its value. Administration, Settings states which source and
+which transport are in effect and sends a test message to the signed-in
+address.
+
 `none` refuses every message with `MAIL_NOT_CONFIGURED` and sends nothing.
 `development` keeps the last 100 messages in memory for a local run and a test
 and is refused at boot in production, where it would be silent data loss.

package/agent-template/docs/design-system.md

@@ -17,6 +17,12 @@ shared primitives, tokens, and the rules for using them.
 - Modules: compose screens from `@flowdular/sdk/ui`. Module CSS may only add
   module-specific composites built on the tokens (example:
   `modules/agents/src/client/agents.css`).
+- `modules/<dir>/design/*.html`: a screen as markup, rendered with the
+  stylesheets above by `pnpm ui:preview <path>` (`--scaffold` writes the record
+  recipe in all five states, `--shot <file.png>` captures it). It is where a
+  screen is designed and agreed before it is a component, and it carries no CSS
+  of its own, so it cannot drift from the platform. `pnpm ui-classes:check`
+  refuses a class no stylesheet declares, there and in every `.tsrx`.
 - `platform/public`: `favicon.svg`, `og.png` (1200x630 Open Graph image).
 - Brand mark geometry is generated: `node packages/ui/scripts/gen-mark.mjs`
   rewrites `packages/ui/src/brand/mark.ts` from the weave parameters.
@@ -407,7 +413,8 @@ Icon names (`packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog
 - Drawer: `ui-drawer__form` (scrolling body plus pinned footer),
   `ui-drawer__body`, `ui-drawer__foot`
 - Settings rows inside a `ui-card` or a drawer `ui-form__section`, rendered
-  by `SettingRow`: `ui-setting`
+  by `SettingRow`: `ui-setting`, grouped in a card by `ui-setting-group` with
+  `ui-setting-group__head` (the group's name on the rows' own inset)
   (+`__text` for title, scope tag, and help, `__control` for the one-line
   control cluster, `__status` (+`--error`) for the inline result)
 - Buttons: `ui-btn` with `--primary`, `--secondary`, `--ghost`, `--danger`,

package/agent-template/docs/module-web-surfaces.md

@@ -63,7 +63,27 @@ runtime and the module's existing bundles when localization is needed.
 
 ## Operator configuration
 
-Add the optional `web` section in the installation's `flowdular.json`:
+One command writes the mount and regenerates the composition:
+
+```bash
+pnpm flowdular web mount example.core public --path /blog --tenant <tenant id>          # preview
+pnpm flowdular web mount example.core public --path /blog --tenant <tenant id> --apply
+pnpm flowdular web list
+pnpm flowdular web unmount acme-public --apply
+```
+
+It refuses before it writes what the platform would refuse at boot: a module
+this workspace has not enabled, a reserved address, the configured backoffice
+path, an address overlapping a site already mounted, and a mount naming no
+workspace. The mount id defaults to the module's first segment; `--id` names it
+when one module serves several addresses, and mounting the same id again moves
+that site rather than adding a second one.
+
+The tenant is the workspace whose pages are served, so it exists before the
+mount does: run `flowdular setup` first and use the id it reports.
+
+The same section can be written by hand in the installation's
+`flowdular.json`:
 
 ```json
 {
@@ -82,7 +102,8 @@ Add the optional `web` section in the installation's `flowdular.json`:
 }
 ```
 
-Run `pnpm flowdular module sync --apply`, then rebuild/redeploy production or
+A hand-written section needs `pnpm flowdular module sync --apply` afterwards;
+the `web` commands run it themselves. Then rebuild or redeploy production, or
 restart development. Configuration is generated into the server composition;
 changing it requires regeneration. It is not read from a process-local settings
 cache or an anonymous query parameter. Verify the tenant ID before publishing.
@@ -91,7 +112,14 @@ paths. `/records/:slug` above becomes `/blog/records/:slug`.
 
 The root `/` can host a public storefront, alongside more specific mounts such as
 `/blog`. Reserved platform prefixes such as `/app`, `/auth`, `/api`, `/setup` and
-the configured backoffice path cannot be claimed by modules. Other overlapping
+the configured backoffice path cannot be claimed by modules; the list is
+`RESERVED_WEB_SEGMENTS` in `@flowdular/sdk/contracts`, which the composition and the
+CLI both read. A segment may carry dots inside it, so a page answers at
+`/rss.xml`, `/sitemap.xml` or `/robots.txt` as a reader or a crawler expects;
+each dot separates two non-empty groups, which keeps `..`, a leading dot and a
+trailing dot out of every address. A mount naming a surface its module does not declare stops the
+composition with that sentence, rather than answering 404 at the address for the
+life of the deployment. Other overlapping
 mounts and equivalent route patterns are rejected. Custom paths such as `/blog`, `/portal` and `/forms/contact` work without a
 tenant ID in the URL. `/sites/` is an optional convention for multiple sites;
 unknown sites under that prefix return 404. A disabled binding

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-flowdular",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"type": "module",
 	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
 	"license": "MIT",

package/template/default/modules/example/module.json

@@ -14,7 +14,7 @@
 	"dependencies": [
 		{
 			"id": "auth.core",
-			"range": "^0.13.0"
+			"range": "^0.14.0"
 		}
 	],
 	"tenancy": "required",

package/template/default/modules/example/package.json

@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.1",
-		"@flowdular/sdk": "0.4.1"
+		"@flowdular/sdk": "0.4.3"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/template/default/modules/example/spec/module.yaml

@@ -12,7 +12,7 @@ capabilities:
   - translations
 dependencies:
   - id: auth.core
-    range: ^0.13.0
+    range: ^0.14.0
 tenancy: required
 locales:
   - en

package/template/default/package.json

@@ -25,7 +25,7 @@
 	"devDependencies": {
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.4.1",
+		"flowdular": "0.4.3",
 		"rulesync": "16.21.0"
 	}
 }

package/template/default/platform/octane.config.ts

@@ -1,8 +1,10 @@
 import {
 	assertRouteConflicts,
+	createCorsMiddleware,
 	createModuleMetrics,
 	createModuleWebRoutes,
 	createApplicationRoutes,
+	createOpenApiRoutes,
 	serverTracer,
 	validateApplicationPath,
 	createMailPort,
@@ -17,6 +19,7 @@ import { defineConfig, RenderRoute } from '@octanejs/vite-plugin';
 import {
 	authRuntimeOptionsFromEnvironment,
 	createAuthRoutes,
+	endpointIdentityFromContext,
 	isTokenPrincipal,
 	mfaEnrolmentSatisfied,
 	principalFromContext,
@@ -123,7 +126,10 @@ const moduleCompositions = composeModuleServer({
 	dataClasses,
 	databases,
 	storage,
-	mail,
+	/* The relay auth.core resolves per message from its stored settings, falling
+	   back to the environment port above, so every module of the installation
+	   sends through the same one. */
+	mail: authRuntime.mail,
 	/* Rebound to the composing module by the generated composition; this binding
 	   is what a series the platform itself records would carry. */
 	metrics: createModuleMetrics('platform'),
@@ -172,7 +178,15 @@ if (building) {
 }
 
 export default defineConfig({
-	middlewares: [authRuntime.middleware],
+	middlewares: [
+		/* Ahead of the authentication: a cross-origin preflight carries no
+		   credential and has to be answered before anything asks for one. The
+		   origins come from the API tokens this workspace issued. */
+		createCorsMiddleware({
+			allowOrigin: (origin) => authRuntime.apiOriginAllowed(origin),
+		}),
+		authRuntime.middleware,
+	],
 	router: {
 		routes: checkedRoutes([
 			...createApplicationRoutes({
@@ -183,6 +197,12 @@ export default defineConfig({
 			healthEndpoint.serverRoute,
 			createReadinessEndpoint(databases).serverRoute,
 			...createMetricsRoutes({ environment: process.env }),
+			/* Describes every operation the presented credential may call, built
+			   from the endpoints this application composed. */
+			...createOpenApiRoutes({
+				resolveIdentity: endpointIdentityFromContext,
+				publicBaseUrl: authRuntime.publicBaseUrl,
+			}),
 			...createStorageRoutes({
 				storage,
 				keyring: storageKeyring,
@@ -194,6 +214,10 @@ export default defineConfig({
 				modules: moduleCompositions,
 				mounts: moduleWebMounts,
 				applicationPath: configuredApplicationPath,
+				/* A build composes with NODE_ENV forced to development, so the flag
+				   asks for both: only a development server serves a page whose
+				   stylesheets arrive after its markup. */
+				development: !building && process.env.NODE_ENV !== 'production',
 				resolveIdentity: async (context) => {
 					const principal = principalFromContext(context);
 					if (!principal) return null;

package/template/default/platform/package.json

@@ -15,7 +15,7 @@
 		"@octanejs/vite-plugin": "0.1.51",
 		"octane": "0.1.51",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.4.1"
+		"@flowdular/sdk": "0.4.3"
 	},
 	"devDependencies": {
 		"@octanejs/app-core": "0.0.47",