create-flowdular 0.6.0 → 0.6.1

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

@@ -45,8 +45,12 @@ is a new spec-authoring step and needs approval after that edit.
 ## 3. Sandbox path
 
 In the sandbox, use the operator approval action for the selected session module.
-The live route is POST /sandbox/api/sessions/:id/approve, exposed by
-approveSpecification in packages/sandbox/src/client/api.ts.
+The live route is POST /sandbox/api/sessions/:id/approve with
+{ "module", "specHash" }, exposed by approveSpecification in
+packages/sandbox/src/client/api.ts. specHash is the SHA-256 the review card
+shows for the text it renders. The route refuses with 409 SPEC_CHANGED when the
+current text has another hash, and with 409 QUESTIONS_PENDING while the module
+has unanswered questions; it records nothing then.
 
 The route changes the status presentation and records the SHA-256 hash of the
 exact approved text in the session. Do not patch the session workspace file to

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

@@ -68,7 +68,7 @@ In the sandbox, end the reply with exactly one fenced block tagged `questions`,
 ```
 ````
 
-The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
+The sandbox enforces the bounds: at most 12 questions, each 1 to 400 characters; at most 8 options per question, each 1 to 120 characters; `recommended` is one of the options; no line breaks inside a value; the whole block at most 8000 characters. A block outside them comes back to you once with the reason. The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
 
 When the answers come back, copy each one into `decisions[]` with `decidedBy: user` and the answer text, and update whatever the answer changed.
 
@@ -86,7 +86,7 @@ A number the case needs (a score, a premium, a price per square metre) is an `ac
 
 `modules/<dir>/spec/module.yaml`, `schemaVersion: 2`, `status: draft`. Keep the v1 keys (`id`, `specVersion`, `name`, `description`, `profile`, `capabilities`, `dependencies`, `tenancy`, `locales`, `invariants`, `permissions`, `dataOwnership`, `acceptanceScenarios`) and add the v2 arrays:
 
-- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
+- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. A field never repeats a column every tenant table owns (`id`, `tenantId`, `createdAt`; a screen may still list `createdAt`), and its key in snake case is never a PostgreSQL reserved word (`order`, `user`, `currentUser`): `spec-schema` refuses either with `SPEC_FIELD_RESERVED`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
 - `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.

package/agent-template/.ai/agents/sandbox/business-manager.md

@@ -14,9 +14,9 @@ handoff:
 
 You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/platform-capabilities.md, reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
 
-Write schemaVersion 2: entities with typed fields and states, screens, actions, widgets, settings, agentTools, plus outOfScope and decisions. Fill decisions for every choice, including the platform defaults you proposed. The capability card is closed: anything it lists as missing goes to outOfScope with the business decision, never into a scenario. v1 specs stay valid.
+Write schemaVersion 2: entities with typed fields (never id, tenantId or createdAt) and states, screens, actions, widgets, settings, agentTools, plus outOfScope and decisions. Fill decisions for every choice, including the platform defaults you proposed. The capability card is closed: anything it lists as missing goes to outOfScope with the business decision, never into a scenario. v1 specs stay valid.
 
-When a decision is missing, end the reply with exactly one fenced block tagged questions holding {"questions":[{"id":"Q-1","question":"...","options":["..."],"recommended":"...","allowFreeText":true}]} and nothing after it. The operator answers in a form and the replies arrive next turn as a Decisions section.
+When a decision is missing, end the reply with exactly one fenced block tagged questions holding {"questions":[{"id":"Q-1","question":"...","options":["..."],"recommended":"...","allowFreeText":true}]} and nothing after it. Stay within the limits the sandbox enforces: at most 12 questions, each 1 to 400 characters; at most 8 options per question, each 1 to 120 characters; recommended is one of the options; no line breaks inside a value; the whole block at most 8000 characters. A block outside them comes back to you once with the reason. The operator answers in a form and the replies arrive next turn as a Decisions section.
 
 For an edit, compare against base/modules/<dir>/spec/module.yaml and make the smallest delta covering the brief. Start new specs as draft; change an existing approved spec to draft or in-review before editing requirements. Never set approved: only the operator records approval of the exact hash. Later edits invalidate it.
 

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

@@ -24,11 +24,11 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Background work.** A module that polls its own routing table runs one loop per job through `createJobRunner` (`packages/server/src/jobs/`), taking `{ name, intervalMs, claim, perform, heartbeat?, heartbeatEveryMs?, staleAfterMs, backoff?, batchLimit?, logger, now?, onEvent? }`. The runner owns the loop and nothing else: the timer and its `unref`, the guard that keeps two passes from overlapping, at most `batchLimit` claims per pass, per-item isolation so one failing item never stops the pass, a renewal timer that calls `heartbeat` while `perform` runs and aborts its `AbortSignal` with the stable code `CLAIM_LOST` when the fence answers false, exponential `backoff` after a pass that raised and a reset by one that did not, and `start`, `tick`, `stop`, `quiesce` and `dispose`. It opens no database handle: the table, the routing read, the claim statement with its stale window, the renewal statement and every outcome recorded stay the module's own, `claim` answering null ends the pass, and a stage that observes the abort stops without settling anything. `onEvent` is a trace hook that costs nothing when nobody listens. A composition starts it from `startWorker: () => runner.start()` and wires `stop: () => runner.quiesce()` and `dispose: () => runner.dispose()`. `start` is for registration only (sealing a registry, reading what other modules registered): the platform calls it in every process, and calls `startWorker` only where workers run, never with `FD_RUNTIME_ROLE=web`. A worker host may call `startWorker` and `stop` many times on one composition, so the loop restarts after a stop and a failed database open is not cached: the next `startWorker` opens again. `runner.wake()` runs a pass even on a stopped runner, so a request path that wakes the loop after it enqueues checks a flag set in `startWorker` and cleared in `stop` first (`workerActive` in `modules/adapters/src/server/runtime.ts`). `import.core` is the first adopter and `packages/server/src/jobs/index.ts` carries the recipe for the rest.
 
-**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. A primed snapshot is at most 5 seconds behind a write another process made. Every write appends one row to auth.core's change log, which names the setting and never its value: `context.settings.changesAfter({ after, limit, moduleId?, key? })` pages it from an opaque cursor (`after: null` is the start, 1 to 500 changes a page, the newest change of every setting kept whatever its age) and answers `{ expired: true }` for a cursor past retention, whose holder reads from the start again; `prime(tenantId, { revision })` then reflects at least a revision read there. `onChange` fires only in the process that wrote, so work that must see every change or survive a crash follows the log instead, as `automations.core` does for the workspace time zone.
+**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 `scope: 'platform'` value is one for every workspace, so only the operator workspace changes it: any other workspace sees the row locked and its write is refused with 403 `PLATFORM_SETTING_OPERATOR_ONLY`. The operator workspace is the one auth.core records (the first workspace of an empty database, recorded by first-run setup, `auth workspace-create`, `sandbox provision` or `setup quick` in the transaction that creates it; changed only by `pnpm flowdular auth operator-set`), unless `FD_OPERATOR_TENANT` is set, which then decides alone. system.core resolves it per request through `authService.operatorStanding(tenantId)` (`own`, `other` or `none`, never naming another workspace); while none is known every platform row is locked with `system.settings.platformOperatorUnset`. 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. A primed snapshot is at most 5 seconds behind a write another process made. Every write appends one row to auth.core's change log, which names the setting and never its value: `context.settings.changesAfter({ after, limit, moduleId?, key? })` pages it from an opaque cursor (`after: null` is the start, 1 to 500 changes a page, the newest change of every setting kept whatever its age) and answers `{ expired: true }` for a cursor past retention, whose holder reads from the start again; `prime(tenantId, { revision })` then reflects at least a revision read there. `onChange` fires only in the process that wrote, so work that must see every change or survive a crash follows the log instead, as `automations.core` does for the workspace time zone.
 
 **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.
+**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` in the operator workspace (the recorded one, or `FD_OPERATOR_TENANT` when set) 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.
 
@@ -70,7 +70,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **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). 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.
+**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). The operator workspace 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 or a private Vercel Blob store (`FD_STORAGE_ADAPTER=local|s3|vercel-blob`, `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.
 
@@ -78,7 +78,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Research.** `research.core` (optional) searches the web and reads public pages for agents, workflows and members, and keeps what they read as citeable evidence. A search runs an ordered chain of adapters: `model-native` (reached only by an Anthropic or OpenAI model inside an agent run through the native tool `research.web-search`), `searxng` (a self-hosted SearXNG, `GET /search` with `format=json`), `firecrawl` (the Firecrawl API, `POST /v2/search`), `connector` (the `connectors.core` instance named by `connectorInstanceId`, operation `search`, input `{ q, limit }`) and `recorded` (a `research-fixtures.json` file `{ queries: { [query]: ResearchResult[] }, pages: { [url]: { title, text } } }` at the absolute or workspace-relative `recordedFixturesPath`, for tests and the sandbox). The owner orders and switches them on the Search adapters tab behind `research.settings.manage` (settings `searchOrder` and `<key>Enabled`; while `searchOrder` is empty the single setting `research.core.adapter`, default `model-native`, decides), with `<key>MaxAttempts` (1 to 5), `<key>TimeoutMs`, full jitter backoff `retryBackoffMs` capped at 5 s, `Retry-After` honoured on a 429, `fallback` (`next-adapter` or `fail`), `fallbackOnEmpty`, and a per-workspace circuit breaker (`circuitFailureThreshold`, `circuitCooldownMs`, one half open probe); every attempt is a `research_attempts` row. A fetch runs `fetchOrder` over `direct` (the module's own reader) and `firecrawl` (`POST /v2/scrape`, JavaScript rendered to markdown), and a domain rule, robots.txt, the egress policy or the size cap never falls back. A provider that reports the native web search unsupported marks `model-native` Unsupported on the tab and makes its read back a permanent failure the chain passes over. SearXNG and Firecrawl are reached only through module-owned `connectors.core` instances (definitions `research-searxng` and `research-firecrawl`) whose credentials connectors.core seals and whose consent follows `allowAgents`. A module resolves `research.search.v1` (`search({ tenantId, query, limit?, freshness?, site?, caller, callerRef? })` answering `{ results, adapter, attempts }`, the adapter being the one that answered), `research.fetch.v1` (`fetch({ tenantId, url, caller, callerRef? })` answering `{ evidenceId, title, text, truncated, contentSha256, retrievedAt }`) and `research.evidence.v1` (`attach(tenantId, ownerModule, recordRef, evidenceIds)`, `list(tenantId, ownerModule, recordRef)`, `get(tenantId, id)`), all in `modules/research/src/domain/capability.ts`. Every answered search counts one unit, whatever the chain tried, against `monthlyQueryBudget` under a per-workspace lock and the meter `research.core.queries`, and past it answers `RESEARCH_BUDGET_EXCEEDED` (429); the allow and deny domain lists filter results and refuse fetches with `RESEARCH_DOMAIN_DENIED`. A fetch reaches the network only through `connectors.egress.v1` (`check(url)` answering the verified addresses and a lookup pinned to them), honours `robots.txt` (cached per host for an hour), follows one redirect, stops at `fetchMaxBytes` and `fetchTimeoutMs`, turns HTML into text with its own extractor, reads a PDF the direct reader downloaded through `documents.text.v1` `extractBytes` when documents.core is composed and answers `RESEARCH_CONTENT_UNSUPPORTED` for it otherwise, caches pages for 24 hours and allows 64 fetches per run. Every kept result and fetched page is a `research_evidence` row with the sha256 and a 4 KB excerpt, the full text only while `storeFullText` is on. The agent tools `research.search` and `research.fetch` are `workspace-write` behind the consent gate `research.consent` (setting `allowAgents`, off by default, refusing with `TOOL_NOT_CONSENTED`). The Research screen (Administration, section compliance) lists Evidence and Queries (a query opens its attempts) and, for owners, Search adapters, and another module links to one piece of evidence with `workspaceViewHref('research-evidence') + '?id=' + id`. Not covered yet: full text stored as a document.
 
-**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back. A request whose `subjectRef` is `encodeCapabilitySubjectRef({ capabilityId, inputDigest })` yields, once approved, a signed token through `grant(tenantId, id, subjectModule)`, handed only to the module that opened it; the CLI runner takes it as `--grant` (valid until expiry) and the harness as `AgentExecutionRequest.grants` (one tool call per grant), both bound to the tenant, the capability id and `approvalInputDigest` of the input.
+**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back. The request `get` answers and the one `onResolved` receives both carry `deciderAccountIds`, the accounts whose ledger rows settled the terminal state in ledger order: every approver of an approved request, the account that rejected or cancelled it, none while pending or after an expiry; account ids only, never comments. A request whose `subjectRef` is `encodeCapabilitySubjectRef({ capabilityId, inputDigest })` yields, once approved, a signed token through `grant(tenantId, id, subjectModule)`, handed only to the module that opened it; the CLI runner takes it as `--grant` (valid until expiry) and the harness as `AgentExecutionRequest.grants` (one tool call per grant), both bound to the tenant, the capability id and `approvalInputDigest` of the input.
 
 **Documents.** `documents.core` (optional) owns file attachments of any record. A screen uploads through `POST /api/documents/upload` with the raw body and the headers `x-document-filename`, `x-document-owner-module`, `x-document-record-ref` and `x-document-description`, lists with `GET /api/documents?ownerModule=&recordRef=`, opens through `POST /api/documents/read-url` (a short-lived storage URL) and deletes through `POST /api/documents/delete`, all behind `documents.files.read` or `documents.files.manage` with CSRF first. A module reads its own records' attachments through the public capability `documents.attachments.v1` (`modules/documents/src/domain/attachments.ts`): `list(tenantId, ownerModule, recordRef)`, `open(tenantId, ownerModule, recordRef, id)` answering `{ contentType, bytes, filename, body }` or null for anything not readable (unknown, another pair, deleted, infected) and `delete(tenantId, ownerModule, recordRef, id)`; the reference pair is a scope, the caller's permission on its own record is the authorization, and the storage key never leaves documents.core. Checksums, scan verdicts and the object limits come from the storage port. The text of a document comes from the public capability `documents.text.v1` (`modules/documents/src/domain/text.ts`): `extract(tenantId, ownerModule, recordRef, id, { pages? })` for a document of the caller's reference pair (null for every reference `open` answers null for) and `extractBytes({ contentType, bytes, pages?, signal? })` for bytes that are not stored, both answering `{ status: 'ok' | 'unscanned' | 'unsupported' | 'too-large' | 'pending', reason, text, pages, from, to, truncated, contentSha256 }` with the pages of the text separated by a form feed and `pages` a 1-based `{ from, to }` range. A PDF is read from its text layer page by page (pdf.js through `unpdf`, nothing executed or fetched), a PPTX slide by slide, an XLSX as one block per sheet with tab separated rows, and a DOCX, a CSV or a plain text file in pages of at most 10000 characters; the legacy `.doc` and `.xls` answer `unsupported`. At most 200 pages and 2 MiB of text are kept (`truncated` beyond), input over 25 MiB answers `too-large`, and an OOXML package stops at 32 MiB of bytes actually inflated. A PDF without a text layer and an image answer `unscanned` unless the deployment sets `FD_DOCUMENTS_OCR_URL` (and `FD_DOCUMENTS_OCR_TOKEN`), which receives the bytes through the `connectors.egress.v1` address rules. The text of a stored document is kept in `documents_text` by document and checksum, so a second read parses nothing; a document over 2 MiB or one sent to OCR answers `pending` until the text runner settles it. `POST /api/documents/text` (behind `documents.files.read`) and `POST /api/documents/text/retry` (behind `documents.files.manage`, unscanned text while OCR is available) serve the Text tab of the document details, and the agent tool `documents.read-text` (risk `read`, `documents.files.read`) answers a page range of a record's document cut to 20000 UTF-8 bytes. Documents from templates come from the public capability `documents.templates.v1` (`modules/documents/src/domain/templates.ts`): a module calls `register(moduleId, [{ key, title, format, body, inputSchema, locale, layout }])` while it composes (`key` is `<module id>.<name>`, `format` `pdf` or `docx`, `locale` `en` or `pl`, at most 256 templates, every template validated at once and refused at boot with `TEMPLATE_REGISTRATION_INVALID` naming the line, the catalogue sealed when documents.core starts), then `render({ tenantId, principal: { accountId, scopes }, ownerModule, recordRef, templateKey, input, format? })` for its own record after checking its own record permission, answering `{ jobId, status, documentId, errorCode, templateKey, version, format }` with `status` `queued`, `running`, `succeeded` or `failed`, and `status(tenantId, jobId)` later; `render` refuses a principal without `documents.files.manage` with `FORBIDDEN`. A body is Markdown restricted to headings 1 to 3, paragraphs with bold, italic, inline code and links (printed as the text and the URL in parentheses), bulleted and numbered lists one level deep, block quotes, a rule, the line `---pagebreak---` and pipe tables, plus HTML comments on lines of their own, which are dropped; HTML, images, footnotes, reference links, code blocks, setext and level 4 headings are refused with a stable code and the line. The body is parsed first and `{{ path }}` is substituted into text nodes after, so an input value is printed as text and never read as Markdown. The formatters are `money: currency` (minor units and an ISO 4217 field or quoted code), `number: 0..6`, `date` and `datetime` (the workspace zone from `system.core.timeZone` and the template locale; a `YYYY-MM-DD` date is not shifted), `upper` and `yesno`, one per placeholder; `{{#each path}}` repeats table rows or blocks with `this`, `@index` (from 0) and `@number` (from 1), `{{#if path}} {{else}} {{/if}}` keeps rows or blocks, each block tag on a line of its own, and a path is searched from the innermost item outwards through own properties of the input only. The input schema is a JSON Schema subset (an object root; object, string with `maxLength` and `enum`, number, integer, boolean, array of an object or a scalar; `required`, `title`, `description`; at most 4 levels and 64 properties per object), every placeholder is checked against it at validation (`TEMPLATE_FIELD_UNKNOWN`, `TEMPLATE_FIELD_TYPE`), and a render validates the input first (`TEMPLATE_INPUT_INVALID` with up to 20 issues naming the path). `templateInputSchemaFromFields(fields)` builds the schema from a spec entity. A layout is the page size `A4` or `Letter`, margins of 5 to 60 mm, a one-line header and footer with placeholders plus `{{page}}` and `{{pages}}`, and a title that also names the stored file. Bounds: a body of 65536 characters and 8 nested blocks, 2000 repeated rows or blocks (`TEMPLATE_ROWS_EXCEEDED`), 1000000 printed characters (`TEMPLATE_OUTPUT_TOO_LARGE`), 200 PDF pages (`TEMPLATE_PAGES_EXCEEDED`), an input of 256 KiB, strings of 10000 characters and arrays of 2000 items. A workspace uses the module default until it renders or edits a template; then `document_template_versions` keeps the default as version 1 and `document_templates` names the current version. A save appends an immutable version (`TEMPLATE_VERSION_CONFLICT` on a stale expected version, `TEMPLATE_UNCHANGED` when nothing changed), a restore appends a copy of an earlier version and a revert a copy of the module default; a workspace whose current version came from the default or a revert follows a changed default on its next render, an edited one keeps its edit. A render is a `document_renders` row unique by workspace, template key, version, owner module, record reference, format and input digest, so a repeated render answers the same row, a failed one is queued again and one whose document was deleted renders again under the next generation; the input is kept until the render settles. A render of at most 50 repeated rows and 16 KiB of input runs within the call, any other on the job runner `documents.core.render` (heartbeat, five minute stale takeover, `CLAIM_LOST`, three attempts before `TEMPLATE_RENDER_FAILED`); the bytes go through the storage port under an object id derived from the render id and the `documents_files` row of the owning record is inserted in the transaction that marks the render succeeded while the claim holds, so a process that dies mid render repeats it without a second document, and the workspace quota applies (`QUOTA_EXCEEDED`). PDF is rendered by pdfmake 0.3.11 over pdfkit with the Roboto family embedded (Latin Extended, so Polish renders), tables repeating their header row across pages and a header and footer on every page, with every URL and file access refused; DOCX by docx 9.5.1 with a repeated header row and page number fields; both behind a renderer interface, server side only. `GET /api/documents/templates`, `/detail`, `/versions` (keyset paged) and `/version` and `POST /api/documents/templates/preview` (the draft rendered to bytes, nothing stored, at most two at a time per process, `TEMPLATE_PREVIEW_BUSY` 429 beyond) sit behind `documents.templates.read` (members), `POST /api/documents/templates/save` and `/revert` behind `documents.templates.manage` (owners), every POST CSRF first. The agent tool `documents.render` (risk `workspace-write`, `idempotency: 'required'`, `target-ledger`) requires `documents.templates.read` and `documents.files.manage`; its harness key is bound in `document_render_keys` to the render it first reached with the request digest, so a retry answers that render even after the template gained a version and a key reused for another request is refused with `TEMPLATE_RENDER_KEY_REUSED`, and `documents.render-status` (risk `read`, `documents.templates.read`) reads a job by id. Versions are the data class `documents.core.templates` (kept) and renders `documents.core.renders` (90 days, settled rows only, exported without the input). The Templates screen (Administration, section platform) lists the registered templates and opens an editor with line numbers, layout fields, a sample input, a preview in the browser's own PDF viewer or a DOCX download, and the version history with a diff, Restore and Revert.
 

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

@@ -51,8 +51,12 @@ is a new spec-authoring step and needs approval after that edit.
 ## 3. Sandbox path
 
 In the sandbox, use the operator approval action for the selected session module.
-The live route is POST /sandbox/api/sessions/:id/approve, exposed by
-approveSpecification in packages/sandbox/src/client/api.ts.
+The live route is POST /sandbox/api/sessions/:id/approve with
+{ "module", "specHash" }, exposed by approveSpecification in
+packages/sandbox/src/client/api.ts. specHash is the SHA-256 the review card
+shows for the text it renders. The route refuses with 409 SPEC_CHANGED when the
+current text has another hash, and with 409 QUESTIONS_PENDING while the module
+has unanswered questions; it records nothing then.
 
 The route changes the status presentation and records the SHA-256 hash of the
 exact approved text in the session. Do not patch the session workspace file to

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

@@ -74,7 +74,7 @@ In the sandbox, end the reply with exactly one fenced block tagged `questions`,
 ```
 ````
 
-The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
+The sandbox enforces the bounds: at most 12 questions, each 1 to 400 characters; at most 8 options per question, each 1 to 120 characters; `recommended` is one of the options; no line breaks inside a value; the whole block at most 8000 characters. A block outside them comes back to you once with the reason. The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
 
 When the answers come back, copy each one into `decisions[]` with `decidedBy: user` and the answer text, and update whatever the answer changed.
 
@@ -92,7 +92,7 @@ A number the case needs (a score, a premium, a price per square metre) is an `ac
 
 `modules/<dir>/spec/module.yaml`, `schemaVersion: 2`, `status: draft`. Keep the v1 keys (`id`, `specVersion`, `name`, `description`, `profile`, `capabilities`, `dependencies`, `tenancy`, `locales`, `invariants`, `permissions`, `dataOwnership`, `acceptanceScenarios`) and add the v2 arrays:
 
-- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
+- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. A field never repeats a column every tenant table owns (`id`, `tenantId`, `createdAt`; a screen may still list `createdAt`), and its key in snake case is never a PostgreSQL reserved word (`order`, `user`, `currentUser`): `spec-schema` refuses either with `SPEC_FIELD_RESERVED`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
 - `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.

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

@@ -45,8 +45,12 @@ is a new spec-authoring step and needs approval after that edit.
 ## 3. Sandbox path
 
 In the sandbox, use the operator approval action for the selected session module.
-The live route is POST /sandbox/api/sessions/:id/approve, exposed by
-approveSpecification in packages/sandbox/src/client/api.ts.
+The live route is POST /sandbox/api/sessions/:id/approve with
+{ "module", "specHash" }, exposed by approveSpecification in
+packages/sandbox/src/client/api.ts. specHash is the SHA-256 the review card
+shows for the text it renders. The route refuses with 409 SPEC_CHANGED when the
+current text has another hash, and with 409 QUESTIONS_PENDING while the module
+has unanswered questions; it records nothing then.
 
 The route changes the status presentation and records the SHA-256 hash of the
 exact approved text in the session. Do not patch the session workspace file to

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

@@ -68,7 +68,7 @@ In the sandbox, end the reply with exactly one fenced block tagged `questions`,
 ```
 ````
 
-The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
+The sandbox enforces the bounds: at most 12 questions, each 1 to 400 characters; at most 8 options per question, each 1 to 120 characters; `recommended` is one of the options; no line breaks inside a value; the whole block at most 8000 characters. A block outside them comes back to you once with the reason. The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
 
 When the answers come back, copy each one into `decisions[]` with `decidedBy: user` and the answer text, and update whatever the answer changed.
 
@@ -86,7 +86,7 @@ A number the case needs (a score, a premium, a price per square metre) is an `ac
 
 `modules/<dir>/spec/module.yaml`, `schemaVersion: 2`, `status: draft`. Keep the v1 keys (`id`, `specVersion`, `name`, `description`, `profile`, `capabilities`, `dependencies`, `tenancy`, `locales`, `invariants`, `permissions`, `dataOwnership`, `acceptanceScenarios`) and add the v2 arrays:
 
-- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
+- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. A field never repeats a column every tenant table owns (`id`, `tenantId`, `createdAt`; a screen may still list `createdAt`), and its key in snake case is never a PostgreSQL reserved word (`order`, `user`, `currentUser`): `spec-schema` refuses either with `SPEC_FIELD_RESERVED`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
 - `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.

package/agent-template/docs/adr/0003-module-settings.md

@@ -20,3 +20,5 @@ The first setting is `auth.core.allowSignUp`. The server is authoritative and re
 - Administration: `GET /api/settings` (`system.settings.read`) lists every declaration with its current tenant value and metadata; `POST /api/settings/update` (`system.settings.manage`, session only) validates against the declaration, stores or clears the value, and appends `settings.updated` to the auth audit trail. Secrets are write-only: the API returns whether a value is set, never the value. Administration > Modules renders the selected module's declarations in its Settings drawer section. Administration > Settings contains only workspace and organization settings.
 - `emailConfirmation` cannot be enabled while no mail transport is composed; the API refuses with `MAIL_TRANSPORT_REQUIRED` and the screen shows the setting as locked.
 - The cross-module read rule (declared dependency, shared, non-secret) is not enforced by `get`; it is a review rule until a requester-aware read exists.
+- Platform-scoped writes (amendment, 2026-10-06): every workspace owner holds `system.settings.manage`, so `POST /api/settings/update` changes a platform-scoped setting only for a principal of the operator workspace, the tenant id the deployment sets in `FD_OPERATOR_TENANT`, and refuses anyone else with 403 `PLATFORM_SETTING_OPERATOR_ONLY`; `GET /api/settings` locks those rows outside it. Unset, no workspace changes one.
+- Recorded operator workspace (amendment, 2026-10-06, 0.6.1): auth.core records the operator workspace in `auth_operator_workspace`, at most one row under forced row-level security bound to the workspace it names. Any path that creates the first workspace of an empty database records it in the same transaction, a deployment with exactly one workspace and no record records it when auth.core opens the database, and `pnpm flowdular auth operator-set` is the only way to change it. `FD_OPERATOR_TENANT` becomes an override: set, it alone decides, and a value that is not a workspace id leaves no operator. system.core resolves the operator on every settings request; while none is known every platform row is locked with `system.settings.platformOperatorUnset` and the write refusal keeps `PLATFORM_SETTING_OPERATOR_ONLY`. This supersedes "unset, no workspace changes one" above.

package/agent-template/docs/agent-contract.md

@@ -18,7 +18,7 @@ Use the already selected task skill. Consult `.ai/references/catalog` for implem
 7. Every mutation calls `sessionMutationDenial(octane, auth)` first and reads its body with `readJsonObject` plus `requiredString`, `optionalString`, `requiredInteger`. Clients send `content-type: application/json`, `x-csrf-token`, and `credentials: 'same-origin'`.
 8. Routes mount only through `src/platform.ts` exporting `createServerComposition(context)` with `platform.server: true` in `module.json` and a `./platform` export in `package.json`; the context carries `auth`, `settings`, `agentTools`, `agentDefinitions`, `capabilities` and `databases`. A database module passes `context.databases` into one runtime, which acquires and releases one provider lease lazily; `prepare` stays read-only and never opens a database. A composition may return `settings`, read-only `prepare`, `start`, background-work `stop`, and final `dispose`. Client contributions mount only through `createClientContribution(context)` in `src/client/index.ts` with `platform.client: true`. `pnpm flowdular module validate` fails on a missing entry (`PLATFORM_*`).
 9. Never edit the composition by hand: `platform/octane.config.ts`, `platform/src/App.tsrx`, `platform/src/generated/**`, `platform/package.json` dependencies and `modules.enabled` in `flowdular.json` are written by `pnpm flowdular module enable <id> --apply` and `pnpm flowdular module sync --apply`.
-10. `pnpm flowdular module enable <id> --apply` grants the spec permissions to every tenant owner as its last step; `pnpm flowdular auth sync-scopes --module <id> --apply` re-grants later (new permission, another database). Members receive scopes only through `MEMBER_SCOPES` in `modules/auth/src/acl/scopes.ts`, a core change.
+10. `pnpm flowdular module enable <id> --apply` grants the spec permissions to every tenant owner as its last step; first-run setup grants every enabled module's permissions to the owner it creates, so a module enabled before the first workspace needs no extra step; `pnpm flowdular auth sync-scopes --module <id> --apply` re-grants later (new permission, another database). Members receive scopes only through `MEMBER_SCOPES` in `modules/auth/src/acl/scopes.ts`, a core change.
 11. Declare every imported package in the module `package.json`; the sandbox `dependencies` gate and the eject fail otherwise. Every relative import carries its `.ts` or `.tsrx` extension.
 12. Use the CLI for discovery, validation and scaffolding: `doctor`, `spec validate`, `module validate`, `module new`, `module enable`, `auth sync-scopes`. Run destructive, external or production capabilities only with what the runner demands (`--apply`, `--confirm`, `--spec`) and never work around a refusal.
 13. Gates are `spec-schema`, `module-schema`, `dependencies`, `typecheck`, `tests`, `format`. The sandbox runs `dependencies` plus the ones your role lists after every turn, per draft module, and feeds a failure back to you; with a shell you may run the module's own gate commands yourself, never installs, network or git. From a checkout run them yourself and `pnpm verify` before any pull request.

package/agent-template/docs/cli-extensions.md

@@ -77,6 +77,7 @@ The CLI imports this code only after the exact command or capability is invoked.
 - External and non-local destructive module capabilities remain disabled until a signed approval verifier is configured.
 - A workspace-local destructive capability must declare `localOnly` and a typed confirmation token. It remains dry-run unless both `--apply` and the exact `--confirm` value are present, and it is blocked outside development and test.
 - `capability list`, `capability describe`, and `capability run` use the same descriptors and handlers as direct commands.
+- A command refuses by throwing. An error with a stable `code` (`^[A-Z][A-Z0-9_]{0,63}$`) and a numeric HTTP `status`, the shape of every module service error, keeps its code in the envelope and the human output. So does a coded error from a platform service the runner hands the command, such as a `DatabaseError` from `context.databases` or a refused local database. Any other error is reported as `COMMAND_FAILED`. Only the code and the message are printed, never the stack, the cause or other fields.
 - Core commands may reuse an extension: `module enable <id> --apply` runs the `auth.scopes.sync` capability of `auth.core` after regenerating the composition, so a freshly enabled module is visible to workspace owners without a second command.
 
 The complete customer example is in `.ai/examples/customer-cli-extension`. New module scaffolds include the catalog and implementation files when the approved spec declares the `cli` capability.

package/agent-template/docs/cli.md

@@ -134,6 +134,8 @@ flowdular auth sync-scopes --module <id> [--apply] # re-grant a module's scopes
 flowdular auth workspaces [--limit <n>]            # workspaces of this deployment and their owners
 flowdular auth workspace-create --name <name> --owner-email <email> --owner-name <name> [--slug <id>] [--password-env <VAR>] [--actor <label>] [--apply]
 flowdular auth member-add --workspace <slug|id> --email <email> [--role <key>] [--actor <label>] [--apply]
+flowdular auth operator                            # the recorded operator workspace and whether FD_OPERATOR_TENANT overrides it
+flowdular auth operator-set <id|slug> [--actor <label>] [--apply]
 flowdular auth secrets-rotate [--apply]              # re-seal enrolled TOTP secrets with the current MFA key
 flowdular auth greenfield                          # destructive local auth reset (setup quick)
 
@@ -197,6 +199,20 @@ Both commands append an audit row to the workspace trail whose actor is
 what exists, with each workspace's owners, so the slug or id for the other
 commands is at hand.
 
+The first workspace of an empty database is recorded as the operator
+workspace, the one whose owners change the branding and the other platform
+settings. `auth operator` shows the record and says whether
+`FD_OPERATOR_TENANT` is set in that shell, which overrides the record wherever
+the deployment sets it. `auth operator-set` names another workspace, previews
+without `--apply`, and with it releases the current operator and records the
+new one, each with an audit row in that workspace's trail. If it fails between
+the two, no workspace is the operator until the same command runs again.
+
+```bash
+flowdular auth operator
+flowdular auth operator-set northwind --apply
+```
+
 ## Workspace scripts
 
 ```bash

package/agent-template/docs/configuration.md

@@ -18,6 +18,32 @@ deployments must set the secret keys.
 | `FD_LOG_LEVEL`       | `info`                            | `debug`, `info`, `warn` or `error`                                         |
 | `FD_METRICS`         | `false`                           | Expose `GET /api/metrics`; see [operations.md](operations.md)              |
 | `FD_METRICS_TOKEN`   | none                              | Bearer token a metrics scrape must present                                 |
+| `FD_OPERATOR_TENANT` | none                              | Tenant id that overrides the recorded operator workspace                   |
+
+A platform-scoped module setting has one value for every workspace: the
+branding, sign-up and session policy, the mail relay and the platform settings
+of other modules. Only the operator workspace changes them: a principal there
+holding `system.settings.manage` edits them in Administration. Every other
+workspace sees them read-only, and a write from it is refused with 403
+`PLATFORM_SETTING_OPERATOR_ONLY`.
+
+auth.core records the operator workspace. First-run setup records the workspace
+it creates, in the transaction that creates it, and so does any other path that
+creates the first workspace of an empty database (`auth workspace-create`,
+`sandbox provision`, `setup quick`). `pnpm flowdular auth operator` shows the
+record and `pnpm flowdular auth operator-set <id|slug> --apply` moves it to
+another workspace; the next request sees the change, with no restart.
+
+`FD_OPERATOR_TENANT` is an override. Set, the workspace whose tenant id it names
+is the operator and the record is not consulted; a value that is not the id of
+an existing workspace leaves no operator rather than falling back to the record.
+Leave it empty to use the record.
+
+A deployment upgraded from 0.6.0 with exactly one workspace records that
+workspace the first time it starts. With two or more nothing is recorded, every
+platform row is locked with a reason that names `auth operator-set`, and the
+stored values keep applying until the operator runs that command or sets the
+variable.
 
 A `web` process serves HTTP only: it never starts a module worker and never
 claims queued work from a request, so a deployment of `web` processes also needs
@@ -33,7 +59,8 @@ A Vercel deployment works this way; see
 
 The name, the document title, the description, the link preview image, the
 browser icon, the theme colour and the logo are not environment variables: they
-are `system.core` settings an owner with `system.settings.manage` changes under
+are platform-scoped `system.core` settings a principal with
+`system.settings.manage` in the operator workspace changes under
 Administration, Branding, and every change is audited. One value serves the
 whole deployment, so the sign-in screen and a shared link carry it too, and a
 setting nobody changed renders the product's own.
@@ -622,9 +649,10 @@ 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
+The relay is also five platform-scoped `auth.core` settings, edited from the
+operator workspace 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

package/agent-template/docs/database-adapters.md

@@ -32,7 +32,12 @@ const databases = createDatabaseProvider(config, {
 });
 ```
 
-`@flowdular/sdk/database` owns no driver, so the caller supplies both. Composition
+`@flowdular/sdk/database` owns no driver, so the caller supplies both. The provider
+listens for the `error` events node-postgres emits on a pool and on a leased
+client, so a connection the server closes (a suspended compute, a failover, a
+restart) costs at most the query or transaction it interrupts, never the
+process; a factory
+needs no listener of its own. Composition
 injects the result as `PlatformServerContext.databases`, and that is the only
 way a module reaches storage. `GET /api/ready` reports the live adapter and
 answers 503 while the database is unreachable.
@@ -72,7 +77,10 @@ maximum.
 
 With the `pglite` adapter the data directory is the only setting that applies.
 Under `NODE_ENV=test` the directory is ignored and the database is held in
-memory.
+memory. A directory is open once per process: every provider on it in that
+process shares the one embedded database (a development server composes more
+than one), and another process is refused with `LOCAL_DATABASE_LOCKED` until
+the last of them closes it.
 
 ## Three roles
 

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

@@ -233,7 +233,10 @@ or than the narrowest table beside it; more than two actions always sit in the
 More menu, and the column then keeps the width of that one button. The menu
 opens over the page, arrows, Home and End move between items, Enter or Space
 runs one, and Escape or Tab closes it and returns focus to the button. A refused
-action stays in the menu, announced as unavailable, with its `reason`.
+action stays in the menu, announced as unavailable, with its `reason`. The
+action column stays pinned to the right edge while the table scrolls, except a
+single action, which never folds: in a card narrower than three times its
+column it scrolls with the row instead of covering the cells beside it.
 
 **Clickable rows.** A table with `onSelect` makes its first cell a button, so
 Tab reaches the row and Enter or Space opens it. That column holds text, never
@@ -442,7 +445,8 @@ Rendered by components, not written by hand: `ui-page-head*`, `ui-search`,
 `ui-table__lead` with `ui-table__toggle` and `ui-table__open` (the first cell's
 expand and open buttons), `ui-table__hide-*` (a column hidden below that width),
 `ui-table__reveal-*` (the expand button, details list and detail shown below
-that width), `ui-table--fold-*` (the action fold step),
+that width), `ui-table--fold-*` (the action fold step), `ui-table--unpin-*`
+(the step below which a single action scrolls with its row),
 `ui-table__placeholder-body` (the loading and empty row content),
 `ui-table__details` (+`-list`), `ui-table__detail`,
 `ui-table-more` (+`--always`), `ui-table-menu` (+`__scrim`, `__label`),

package/agent-template/docs/getting-started.md

@@ -33,7 +33,11 @@ workspace and owner account. Embedded PostgreSQL is already configured. Restart
 Vite HMR covers TSRX, TypeScript and styles. The launcher keeps tool warnings
 quiet; use `pnpm dev -- --verbose` for full diagnostics. `pnpm dev` runs
 `module sync` first, so a composition change is picked up without a manual
-step. The session lives in an HttpOnly cookie and carries the scopes of the
+step. Ctrl+C, SIGTERM or a closed terminal stops the server after open requests
+finish and background work drains, within six seconds. A second Ctrl+C does not
+cut that short, because pnpm already delivers every Ctrl+C more than once;
+Ctrl+\ stops it at once.
+The session lives in an HttpOnly cookie and carries the scopes of the
 selected tenant membership. A bookmark pointing at another workspace you
 belong to switches the session on load.
 

package/agent-template/docs/modules.md

@@ -181,7 +181,9 @@ package is not linked yet, and regenerates
 grants the scopes declared by each newly enabled module to every workspace owner
 through `auth sync-scopes`; a failed grant is reported as
 `MODULE_SCOPES_SYNC_FAILED`, and when `auth.core` is unavailable the grant is
-skipped with a warning.
+skipped with a warning. That grant reaches only workspaces that already exist,
+so first-run setup grants the permissions of every enabled module to the owner
+it creates.
 
 `disable` refuses while another enabled module depends on the target, then
 removes it and regenerates. `system.core` and `auth.core` are protected.

package/agent-template/docs/sandbox.md

@@ -57,7 +57,18 @@ written.
 
 An application already serving on the platform port is left alone, and no
 credential is prepared for it. `--platform` and `--platform-port` say otherwise
-explicitly; `--no-platform` never starts one.
+explicitly; `--no-platform` never starts one. An application the launcher
+started stops with it, including when the terminal closes or the launcher is
+killed. It gets eight seconds to drain before it is killed, two more than the
+six the development server gives itself; both figures live in
+`@flowdular/sdk/dev-console/shutdown`. The installs, gates and Git commands the
+sandbox runs stop with it the same way.
+
+One sandbox runs per workspace. A second launcher, or `pnpm eval`, on a
+workspace whose sandbox is running exits with the PID of the process that holds
+it. The hold is the directory `.flowdular/sandbox/workspace.lock`; it goes away
+when that process ends, and one left by a process that was killed outright is
+taken over by the next start.
 
 ## The credential is prepared, not pasted
 
@@ -349,9 +360,17 @@ of 1 to 120 characters, and a recommendation that must be one of those options.
 `allowFreeText` defaults to false, and a question with neither an option nor
 free text cannot be answered, so it is refused. The block has to be the last
 thing in the reply apart from the mandatory handoff line, and a reply carries at
-most one. A block the sandbox cannot read is a warning on that turn, never a
-failed turn: the words of the reply still stand and the transcript says why the
-block was ignored.
+most one. A block the sandbox cannot read is never a failed turn and never
+dropped in silence: the transcript says why it was refused, and the specialist
+gets the reason and these limits for one repair turn. A second refusal in a row
+stops for the operator, who answers in words. A turn that asks stops for the
+answers, never for approval, and the approval route refuses a module with open
+questions (`409 QUESTIONS_PENDING`). A gate that failed in the same turn waits
+too: the handoff names it, the gates run again after the answering turn, and a
+failure that remains then goes back to the specialist. Such a session is in the
+`awaiting-answers` state, so `awaiting-approval` only ever means an approval.
+`sandbox.core` has no state for open questions, so the platform record keeps
+`awaiting-approval` for it.
 
 A readable block is stored on the session as `pendingQuestions`, with the
 transcript sequence of the message that asked, the role that asked and the

package/package.json

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

package/template/default/.env.example

@@ -84,6 +84,11 @@ FD_AUTH_MAIL_TRANSPORT=none
 FD_AUTH_SMTP_URL=
 FD_AUTH_MAIL_FROM=
 
+# Tenant id that overrides the operator workspace, the one that changes platform
+# settings such as the branding and the mail relay. Empty, the workspace auth.core
+# recorded at first-run setup decides (pnpm flowdular auth operator shows it).
+FD_OPERATOR_TENANT=
+
 # Read by infra/docker/compose.yaml only. It builds the three URLs above from
 # these passwords and publishes the container port on FD_PORT.
 FD_POSTGRES_SUPERUSER_PASSWORD=

package/template/default/infra/docker/.env.example

@@ -61,6 +61,11 @@ FD_AUTH_PUBLIC_ORIGIN=
 # behind TLS, set true and set FD_AUTH_PUBLIC_ORIGIN to its HTTPS origin.
 FD_AUTH_SECURE_COOKIE=
 
+# Tenant id that overrides the operator workspace, the one that changes platform
+# settings such as the branding and the mail relay. Empty, the workspace auth.core
+# recorded at first-run setup decides (pnpm flowdular auth operator shows it).
+FD_OPERATOR_TENANT=
+
 # Prometheus exposition on GET /api/metrics. Leave FD_METRICS unset to keep it off.
 FD_METRICS=false
 FD_METRICS_TOKEN=

package/template/default/infra/docker/Dockerfile

@@ -18,6 +18,7 @@ RUN pnpm build
 RUN mkdir -p module-plans \
 	&& if [ ! -f flowdular.modules.lock.json ]; then printf '{"schemaVersion":1,"modules":[]}\n' > flowdular.modules.lock.json; fi \
 	&& if [ ! -f flowdular.module-sources.json ]; then printf '{"schemaVersion":1,"sources":[]}\n' > flowdular.module-sources.json; fi
+RUN mkdir -p /sdk-manifests && node infra/sdk-module-manifests.mjs . /sdk-manifests
 
 FROM node:24-bookworm-slim AS runtime
 
@@ -31,7 +32,9 @@ RUN groupadd --system --gid 1001 octane \
 	&& chown octane:octane /data
 
 # The server bundle is self-contained: platform/dist/server/entry.js imports
-# only node:* built-ins, so no node_modules (and no devDependencies) ship.
+# only node:* built-ins, so no node_modules (and no devDependencies) ship. The
+# platform does read the manifests and specs of the modules @flowdular/sdk
+# ships, so the last copy puts those files alone where platform/ resolves them.
 COPY --from=builder --chown=octane:octane /workspace/platform/dist ./platform/dist
 COPY --from=builder --chown=octane:octane /workspace/platform/package.json ./platform/package.json
 COPY --chown=octane:octane infra/docker/app-entrypoint.mjs infra/docker/database-urls.mjs ./infra/docker/
@@ -40,6 +43,7 @@ COPY --from=builder --chown=octane:octane /workspace/flowdular.modules.lock.json
 COPY --from=builder --chown=octane:octane /workspace/flowdular.module-sources.json ./flowdular.module-sources.json
 COPY --from=builder --chown=octane:octane /workspace/module-plans ./module-plans
 COPY --from=builder --chown=octane:octane /workspace/modules ./modules
+COPY --from=builder --chown=octane:octane /sdk-manifests/ ./
 
 USER octane
 EXPOSE 3000

package/template/default/infra/docker/compose.yaml

@@ -124,6 +124,10 @@ services:
       FD_APPLICATION_PATH: ${FD_APPLICATION_PATH:-/app}
       FD_SETUP_AUTO_RESTART: 'true'
       FD_AUTH_ALLOW_SIGN_UP: 'false'
+      # Tenant id that overrides the operator workspace, the one that changes
+      # platform settings such as the branding and the mail relay. Empty, the
+      # workspace auth.core recorded at first-run setup decides.
+      FD_OPERATOR_TENANT: ${FD_OPERATOR_TENANT:-}
       # TLS terminates in front of this container. Only a plain-HTTP run on a
       # workstation may set FD_AUTH_SECURE_COOKIE=false in .env.
       FD_AUTH_SECURE_COOKIE: ${FD_AUTH_SECURE_COOKIE:-true}

package/template/default/infra/kubernetes/deployment.yaml

@@ -61,6 +61,11 @@ spec:
                   key: backgroundUrl
             - name: FD_AUTH_ALLOW_SIGN_UP
               value: 'false'
+            # Tenant id that overrides the operator workspace, the one that
+            # changes platform settings such as the branding and the mail relay.
+            # Empty, the workspace auth.core recorded at first-run setup decides.
+            - name: FD_OPERATOR_TENANT
+              value: ''
             - name: FD_AUTH_SECURE_COOKIE
               value: 'true'
             # With none, invitations and password resets are refused. The smtp