create-flowdular 0.4.1 → 0.5.1

package/README.md

@@ -50,12 +50,15 @@ The generator installs dependencies and initializes Git by default. Local develo
 
 ## Ready for coding agents
 
-Every app includes `.ai` rules, skills, role prompts, blueprints, policies and
-reference examples, plus `AGENTS.md`, `CLAUDE.md`, `.agents/skills` and
-`.claude/skills`. These files are bundled with the generator and are available
-with `--no-install`. Personal agent settings and credentials are never copied.
-
-Edit `.ai/rules` or `.ai/skills`, then run `pnpm rules:generate`. `pnpm verify`
+Every app includes `.ai` rules, skills, role prompts, subagents, blueprints,
+policies and reference examples, plus `AGENTS.md`, `CLAUDE.md`, `.agents/skills`,
+`.claude/skills` and the spec author, module executor and reviewer as subagents in
+`.claude/agents` and `.codex/agents`. The chat-first sandbox is installed with the
+app, so `pnpm sandbox` starts it without a download. These files are bundled with
+the generator and are available with `--no-install`. Personal agent settings and
+credentials are never copied.
+
+Edit `.ai/rules`, `.ai/skills` or `.ai/subagents`, then run `pnpm rules:generate`. `pnpm verify`
 checks that the generated instructions are in sync. The instructions explain
 where to find the installed SDK and how to extend the application's modules.
 

package/agent-template/.agents/skills/auth-security-review/SKILL.md

@@ -74,7 +74,7 @@ Report each finding as: severity (`blocker`, `should-fix`, `taste`), claim, `fil
 ```text
 blocker  Tenant id read from body   modules/inventory/src/api/endpoints.ts:41
          A member of tenant A posts { tenantId: "B" } and creates a location in B.
-         AGENTS.md 6. Fix: principalFromContext(octane)!.tenantId; drop the field.
+         AGENTS.md 4. Fix: principalFromContext(octane)!.tenantId; drop the field.
 ```
 
 ## 8. Known platform gaps to keep in mind (not module defects)

package/agent-template/.agents/skills/bug-hunt/SKILL.md

@@ -29,7 +29,7 @@ description: >-
 | View falls back to the dashboard                                                                           | `ApplicationShell.tsrx` renders `overview` for a view id that no visible navigation or account menu entry reaches                                                                                                                                                                               |
 | Icon renders as a grid                                                                                     | `glyph` or `Icon name` is not an `ICON_PATHS` key (`packages/ui/src/icons/Icon.tsrx` falls back to `modules`)                                                                                                                                                                                   |
 | Stale data after a change                                                                                  | each component owns a store instance (`useMemo(() => createXClientState(), [])`); check the `store.act` that should have written it. `store.commits(cb)` and `store.stats()` from `segment-state` show what was committed                                                                       |
-| Schema error on start                                                                                      | `runModuleMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_OBJECTS` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                             |
+| Schema error on start                                                                                      | `runDatabaseMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_MIGRATION` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                         |
 
 ## 2b. Reproduction snippets
 

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                | A named report is one provider on `reports.v1` returning tiles and series; a named list export is one `defineListExport`; named records are findable through `search.providers.v1`. None of the three has a specification key, so each needs a decision naming the screen or the `actions[]` entry that registers it | `actions[]`, `invariants`                |
+| 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

@@ -81,7 +81,7 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Alert`: `tone` danger (default), warning, info.
 - `Avatar`: `name`, `square` (organizations), `large`.
 - `Icon`: `name`, `size` (18 default, 16 in controls, 14 in `Button size="sm"`), `strokeWidth`.
-- `BrandMark`: `size`, `signature`, `tone`; brand moments only.
+- `BrandMark`: `size`, `tone`; three bars with a copper accent bar, brand moments only.
 
 Icon keys (`ICON_PATHS`, `packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog`, `user`, `users`, `shield`, `code`, `modules`, `file-text`, `play`, `bot`, `flask`, `activity`, `plug`, `search`, `chevron-down`, `chevron-left`, `chevron-right`, `chevrons-up-down`, `sort`, `calendar`, `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`, `alert`, `x`, `sign-out`, `refresh`, `help`, `info`, `key`, `settings`, `braces`, `copy`. An unknown name renders `modules` silently, so check the list.
 
@@ -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/README.md

@@ -10,6 +10,7 @@ Flowdular is an agentic foundation framework. The platform under `packages/`, `m
 | `rules/*.md`                                                 | Canonical cross-agent instructions. RuleSync generates the root `AGENTS.md` and `CLAUDE.md` from these files; `pnpm rules:check` rejects drift.                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `agents/sandbox/*.md`                                        | Loaded at sandbox start by `packages/coding-agent/src/roles/registry.ts` (`loadAgentRoles`); `gates`, `handoff` and `allowedPaths` are enforced. `dependencies` always runs, a `HANDOFF:` line must name a role from the list and never the role itself, and writes outside the active role allowlist are quarantined and restored before validation. Defaults in `packages/coding-agent/src/roles/defaults.ts` are regenerated from these files by `pnpm --filter @flowdular/coding-agent sync-roles`, and `tests/sync.test.ts` fails when they drift. |
 | `agents/{module-executor,reviewer,spec-author}.md`           | Read by people and coding tools at the repository root; named in `blueprints/*/blueprint.json`. Not loaded by code.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `subagents/*.md`                                             | The same three root roles as delegable subagents. RuleSync generates `.claude/agents/<name>.md` and `.codex/agents/<name>.toml` from them, so Claude Code and Codex can hand a phase to the role; each body points at its `agents/<id>.md` prompt and its one task skill.                                                                                                                                                                                                                                                                               |
 | `skills/*/SKILL.md`                                          | Canonical cross-agent procedures. They are copied into every sandbox session as `reference/skills/` (`packages/sandbox/src/server/reference.ts`) and RuleSync generates the discovery copies under `.agents/skills` and `.claude/skills`.                                                                                                                                                                                                                                                                                                               |
 | `blueprints/*/blueprint.json`                                | `pnpm flowdular blueprint list` and `blueprint validate --all` (`packages/cli/src/runner.ts`, discovery in `packages/cli/src/validation.ts` `findNamedFiles`) validate every `blueprint.json` against `packages/contracts/schemas/blueprint.schema.json` and check the companion files exist; `pnpm validate` runs it in CI. The sandbox labels sessions `new-module@1.0.0` and `edit-module@1.0.0`.                                                                                                                                                    |
 | `blueprints/*/*.yaml`, `*.schema.json`, `examples/`          | Existence-checked by `validateBlueprint`; otherwise documentation for agents and reviewers. Nothing executes `steps.yaml` or `gates.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -17,7 +18,7 @@ Flowdular is an agentic foundation framework. The platform under `packages/`, `m
 | `policies/task-budgets.yaml`, `policies/path-ownership.yaml` | Read by the `git-pr` delivery target (`packages/sandbox/src/server/delivery/policies.ts`): the changed-file and new-dependency budget per session kind, and path owners plus `crossOwnerChanges.requireReviewer` for the pull request body. Review guidance otherwise.                                                                                                                                                                                                                                                                                  |
 | `examples/**`                                                | Reference shapes for agents; not compiled or tested.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
-`AGENTS.md` and `docs/design-system.md` are copied into each session's `reference/` as well (`packages/sandbox/src/server/reference.ts`). `AGENTS.md`, `CLAUDE.md`, `.agents/skills` and `.claude/skills` are generated compatibility outputs. Edit `.ai/rules` or `.ai/skills`, then run `pnpm rules:generate`.
+`AGENTS.md` and `docs/design-system.md` are copied into each session's `reference/` as well (`packages/sandbox/src/server/reference.ts`). `AGENTS.md`, `CLAUDE.md`, `.agents/skills`, `.claude/skills`, `.claude/agents` and `.codex/agents` are generated compatibility outputs. Edit `.ai/rules`, `.ai/skills` or `.ai/subagents`, then run `pnpm rules:generate`.
 
 ## Using the skills from your own tool
 
@@ -27,8 +28,8 @@ sandbox turn receives one Task skill from `packages/coding-agent/src/roles/skill
 not the entire catalog. Character-budget and routing tests guard against prompt
 growth; characters are a stable size proxy, not a tokenizer-specific cost estimate.
 
-- Claude Code reads the generated `CLAUDE.md` and discovers the generated `.claude/skills` copies.
-- Codex reads the generated `AGENTS.md` and discovers the generated `.agents/skills` copies.
+- Claude Code reads the generated `CLAUDE.md` and discovers the generated `.claude/skills` copies and the `.claude/agents` subagents.
+- Codex reads the generated `AGENTS.md` and discovers the generated `.agents/skills` copies and the `.codex/agents` subagents.
 - Any other tool: paste `AGENTS.md` and the skill into the instruction.
 
 Both paths land the same way: gates, then `pnpm flowdular module enable <id> --apply` for a new module (it grants the module's scopes as its last step; `auth sync-scopes` re-grants later), `pnpm verify`, pull request (`skills/release-eject-pr`). A sandbox session is a pnpm workspace of its own with the draft modules as projects, so declared dependencies resolve for real and the `dependencies` gate runs after every turn.
@@ -39,6 +40,7 @@ Both paths land the same way: gates, then `pnpm flowdular module enable <id> --a
 - Skill: edit `skills/<kebab-name>/SKILL.md` with `name`, `description`, `roles`, `when`; keep it focused, verify API claims against the cited code, add a row in `skills/README.md`, then run `pnpm rules:generate`.
 - Blueprint: a directory under `blueprints/` with `blueprint.json` valid against `packages/contracts/schemas/blueprint.schema.json` plus `README.md`, `input.schema.json`, `plan.schema.json`, `spec-requirements.yaml`, `allowed-paths.yaml`, `required-files.yaml`, `steps.yaml`, `gates.yaml` (all required by `validateBlueprint`), and `examples/valid`, `examples/invalid` (`input*.json` validate against `input.schema.json`, `plan*.json` against `plan.schema.json`). `agentRoles` use the role ids from `agents/`; `executorProfiles` use the profile ids in `policies/model-routing.yaml`; gate ids for module blueprints come from `packages/sandbox/src/server/gates.ts`.
 - Sandbox role: `agents/sandbox/<id>.md` with the front matter `id`, `name`, `purpose`, `allowedPaths`, `gates`, `handoff` (see `agents/README.md`), then regenerate the bundled defaults: `pnpm --filter @flowdular/coding-agent sync-roles` (the script provided by `packages/coding-agent`; it rewrites `src/roles/defaults.ts` from these files) and run `pnpm --filter @flowdular/coding-agent test`.
+- Root subagent: `subagents/<name>.md` with the front matter `name`, `targets`, `description` and an optional `claudecode` block, a body that names the `agents/<id>.md` prompt and the one task skill, then `pnpm rules:generate`. Keep the procedure in the role prompt; the subagent file stays a pointer so the two cannot drift.
 - Policy: keep it truthful about what code enforces; name the file that does.
 
 Formatting: `npx prettier --write .ai docs`, then `pnpm rules:generate`. No em or en dashes anywhere.

package/agent-template/.ai/agents/README.md

@@ -17,7 +17,7 @@ The five roles and who takes the first turn: `business-manager` for both a new m
 
 ## Root roles run at the repository root
 
-`module-executor.md`, `reviewer.md`, `spec-author.md` describe the same jobs for an agent working in a checkout with a shell (Claude Code, Codex, a person). No code loads them; `.ai/blueprints/*/blueprint.json` names them in `agentRoles` and `requiredReviewers`. Their `allowedPaths` are relative to the repository root and they run the gates themselves with the commands listed in each blueprint's `gates.yaml`.
+`module-executor.md`, `reviewer.md`, `spec-author.md` describe the same jobs for an agent working in a checkout with a shell (Claude Code, Codex, a person). No code loads them; `.ai/blueprints/*/blueprint.json` names them in `agentRoles` and `requiredReviewers`, and `.ai/subagents/<id>.md` exposes each one as a delegable subagent that points back here (RuleSync writes `.claude/agents` and `.codex/agents`). Their `allowedPaths` are relative to the repository root and they run the gates themselves with the commands listed in each blueprint's `gates.yaml`.
 
 ## Adding or changing a role
 

package/agent-template/.ai/agents/sandbox/agentic-engineer.md

@@ -13,6 +13,7 @@ gates:
   - spec-schema
   - module-schema
   - dependencies
+  - module-rules
   - typecheck
   - tests
 handoff:

package/agent-template/.ai/agents/sandbox/backend-engineer.md

@@ -24,6 +24,7 @@ allowedPaths:
 gates:
   - module-schema
   - dependencies
+  - module-rules
   - typecheck
   - tests
   - format

package/agent-template/.ai/agents/sandbox/frontend-engineer.md

@@ -8,6 +8,7 @@ allowedPaths:
   - 'package.json'
 gates:
   - dependencies
+  - module-rules
   - typecheck
   - tests
   - format

package/agent-template/.ai/blueprints/add-migration/README.md

@@ -1,5 +1,5 @@
 # add-migration
 
-Add a table, column, index or constraint through the numbered migration runner. The `.up.sql` file is the source, `src/services/migration.ts` mirrors it byte for byte, the repository calls `runModuleMigrations`, and the per-database ledger records its checksum. Existing databases adopt complete pre-ledger schema without replaying it. Procedure: `.ai/skills/migration-authoring/SKILL.md`.
+Add a table, column, index or constraint through the numbered migration runner. The `.up.sql` file is the source, `src/services/migration.ts` mirrors it byte for byte, the repository calls `runDatabaseMigrations`, and the per-database ledger records its checksum. Existing databases adopt complete pre-ledger schema without replaying it. Procedure: `.ai/skills/migration-authoring/SKILL.md`.
 
 Additive only. A destructive change (drop, type change, tightened check) is refused by this blueprint's input schema and needs an operator decision.

package/agent-template/.ai/examples/bad/client-imports-server/README.md

@@ -2,7 +2,7 @@
 
 `api.ts` sits under `src/client` and imports `../services/database-repository.ts`, which pulls in `@flowdular/sdk/database` and its `node:fs`, `node:path` and `node:async_hooks` imports. The Vite client build fails on the Node built-ins, and even where it compiled the browser would hold a database handle and a `tenantId` parameter chosen by the caller, bypassing every endpoint check.
 
-Violated rules: `AGENTS.md` 5 and 6 (data reaches the client only through an endpoint that resolves identity and takes the tenant from the principal) and the layering in `.ai/skills/core-extend/SKILL.md` (client code imports `@flowdular/sdk/client`, `@flowdular/sdk/ui`, `octane`, `segment-state`, and the module's own `src/client` and `src/domain` types; never `src/services` or `src/server`).
+Violated rules: `AGENTS.md` 3 and 4 (data reaches the client only through an endpoint that resolves identity and takes the tenant from the principal) and the layering in `.ai/skills/core-extend/SKILL.md` (client code imports `@flowdular/sdk/client`, `@flowdular/sdk/ui`, `octane`, `segment-state`, and the module's own `src/client` and `src/domain` types; never `src/services` or `src/server`).
 
 Repair with the `bug-fix` blueprint: replace the import with a `fetch` in `src/client/api.ts` as in `.ai/references/catalog/src/client/api.ts`:
 

package/agent-template/.ai/examples/bad/missing-acl/README.md

@@ -2,7 +2,7 @@
 
 `endpoints.ts` mounts `/api/customers` with `new ServerRoute` from `@octanejs/app-core`. Nothing resolves an identity, nothing checks a permission, and `listAll()` has no tenant. Anyone who can reach the server reads every tenant's customers.
 
-Violated rules: `AGENTS.md` 5 (every endpoint is `defineEndpoint` with `access: { kind: 'permission' }` and `resolveIdentity: endpointIdentityFromContext`) and 6 (tenant id from the principal). The security skill's first grep (`grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth`) finds it.
+Violated rules: `AGENTS.md` 3 (every endpoint is `defineEndpoint` with `access: { kind: 'permission' }` and `resolveIdentity: endpointIdentityFromContext`) and 4 (tenant id from the principal). The security skill's first grep (`grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth`) finds it.
 
 Repair with the `bug-fix` blueprint (or `edit-module`, change class `endpoint`):
 

package/agent-template/.ai/examples/bad/tenant-from-body/README.md

@@ -2,7 +2,7 @@
 
 `endpoints.ts` has a permission and an identity resolver, and still lets a member of tenant A create a customer in tenant B by posting `{ "tenantId": "B", "name": "..." }`. The permission check passes because the principal holds `customers.records.manage` in its own tenant; the body decides where the row lands. The mutation also skips `sessionMutationDenial`, so a cross-site form post with a valid cookie would be accepted.
 
-Violated rules: `AGENTS.md` 6 (tenant id only from `principalFromContext(octane)!.tenantId`) and 7 (`sessionMutationDenial(octane, auth)` first on every mutation). The security skill's grep `grep -rn tenantId modules/*/src/api | grep -v principalFromContext` finds it.
+Violated rules: `AGENTS.md` 4 (tenant id only from `principalFromContext(octane)!.tenantId`) and 3 (an explicit permission and an identity resolver on every endpoint). The security skill's grep `grep -rn tenantId modules/*/src/api | grep -v principalFromContext` finds it.
 
 Repair with the `bug-fix` blueprint: remove the body field, take `auth: AuthRuntime` in `createCustomerRoutes`, and write
 

package/agent-template/.ai/guides/application-development.md

@@ -84,11 +84,13 @@ spec approval or production access.
 
 ## Maintain the agent guidance
 
-Edit `.ai/rules` and `.ai/skills`, then run `pnpm rules:generate` and
-`pnpm rules:check`. Codex reads `AGENTS.md` and `.agents/skills`; Claude Code reads
-`CLAUDE.md` and `.claude/skills`. Keep generated copies synchronized. `.ai/agents`
-contains reusable role instructions; `.ai/blueprints` and `.ai/policies` are
-project-local inputs referenced by `flowdular.json`.
+Edit `.ai/rules`, `.ai/skills` and `.ai/subagents`, then run `pnpm rules:generate`
+and `pnpm rules:check`. Codex reads `AGENTS.md`, `.agents/skills` and
+`.codex/agents`; Claude Code reads `CLAUDE.md`, `.claude/skills` and
+`.claude/agents`. Keep generated copies synchronized. `.ai/agents` contains
+reusable role instructions, and `.ai/subagents` exposes the root roles as
+delegable subagents; `.ai/blueprints` and `.ai/policies` are project-local inputs
+referenced by `flowdular.json`.
 
 Split a skill when it contains independent procedures with different owning
 files, write scopes or verification commands. Keep shared requirements in the

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,9 @@ 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`.
+
+**Branding.** The identity one deployment is served with is seven platform-scoped `system.core` settings (`appName`, `documentTitle`, `description`, `ogImageUrl`, `faviconUrl`, `themeColor`, `logoUrl`, `modules/system/src/settings.ts`), edited by a principal with `system.settings.manage` on the Administration screen `branding` and audited like any other setting. They are one value for the whole installation, because the sign-in screen and a shared link are rendered before a workspace is known. The application route resolves them once per request through the provider `system.core` installs with `installApplicationBranding` (`packages/server/src/application-branding.ts`), hands the server render page state and the browser one JSON data block, and the client reads both with `configureBrandingFromPage` plus `applicationBranding` (`packages/client/src/branding.ts`); the shell wordmark, the mobile header, the sign-in screen, the boot splash, the document title, the description, the icon, the theme colour, the social image and the label an authenticator lists a TOTP enrolment under all come from that one read, so no module fetches branding and nothing disagrees. Every value is bounded by its declaration: a name carries no markup or quote, an address is a same-origin absolute path or an https URL (`javascript:`, `data:` and protocol-relative values are refused at the write), a colour is six hex digits, and a stored value that no longer fits falls back to the product's own. Every https branding image origin an operator stores is added to `img-src` of the content security policy for that deployment, so the icon, the logo and the screen's own preview load. A logo is an address, never an upload, and there is no per-workspace branding, no colour theme and no custom CSS. An application whose own entry predates this and renders none of it, or still declares a static icon or theme colour beside the rendered one, is reported by `pnpm flowdular doctor` as the `platform.branding` check.
 
 **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 +62,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/policies/task-budgets.yaml

@@ -33,7 +33,7 @@ sandbox:
     messageLength: 1 to 20000 characters (packages/sandbox/src/server/turns.ts)
     briefLength: at least 8 characters (planning.ts assertBrief)
     gateTimeout: 5 minutes per gate, output capped at 12000 characters (gates.ts)
-    gateFailure: the same role repairs; no automatic limit on repair turns
+    gateFailure: the same role repairs; at most maxRepairLoops consecutive repair turns per chain, then the chain returns to the operator
     byokReads: 400 listed files, 128 KB per read (packages/coding-agent/src/drivers/byok.ts)
   review:
     chainedTurns: stop and read the transcript after four automatic handoffs on one brief

package/agent-template/.ai/rules/flowdular.md

@@ -87,5 +87,6 @@ made in the Flowdular repository and released before this application uses it.
 The skills and examples use @flowdular/sdk subpath imports. For pnpm --filter,
 read the actual module package name from its package.json. Use pnpm verify and
 pnpm build for this application. Root .ai files are editable project guidance;
-run pnpm rules:generate after changing rules or skills, then pnpm rules:check.
-AGENTS.md, CLAUDE.md, .agents/skills and .claude/skills are generated copies.
+run pnpm rules:generate after changing rules, skills or subagents, then pnpm
+rules:check. AGENTS.md, CLAUDE.md, .agents/skills, .claude/skills, .claude/agents
+and .codex/agents are generated copies.

package/agent-template/.ai/skills/auth-security-review/SKILL.md

@@ -80,7 +80,7 @@ Report each finding as: severity (`blocker`, `should-fix`, `taste`), claim, `fil
 ```text
 blocker  Tenant id read from body   modules/inventory/src/api/endpoints.ts:41
          A member of tenant A posts { tenantId: "B" } and creates a location in B.
-         AGENTS.md 6. Fix: principalFromContext(octane)!.tenantId; drop the field.
+         AGENTS.md 4. Fix: principalFromContext(octane)!.tenantId; drop the field.
 ```
 
 ## 8. Known platform gaps to keep in mind (not module defects)

package/agent-template/.ai/skills/bug-hunt/SKILL.md

@@ -35,7 +35,7 @@ when: A report, failing gate, wrong status code, blank screen, or unexpected 4xx
 | View falls back to the dashboard                                                                           | `ApplicationShell.tsrx` renders `overview` for a view id that no visible navigation or account menu entry reaches                                                                                                                                                                               |
 | Icon renders as a grid                                                                                     | `glyph` or `Icon name` is not an `ICON_PATHS` key (`packages/ui/src/icons/Icon.tsrx` falls back to `modules`)                                                                                                                                                                                   |
 | Stale data after a change                                                                                  | each component owns a store instance (`useMemo(() => createXClientState(), [])`); check the `store.act` that should have written it. `store.commits(cb)` and `store.stats()` from `segment-state` show what was committed                                                                       |
-| Schema error on start                                                                                      | `runModuleMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_OBJECTS` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                             |
+| Schema error on start                                                                                      | `runDatabaseMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_MIGRATION` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                         |
 
 ## 2b. Reproduction snippets