create-flowdular 0.5.1 → 0.6.1

package/agent-template/.claude/skills/workflow-development/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: workflow-development
 description: >-
-  Build, publish, invoke, and test a workflows.core DAG through its typed graph
-  and public execution capability without bypassing agent, action, tenant, or
-  audit boundaries.
+  Author module-owned action templates, or build, publish, invoke, and test a
+  workflows.core DAG through its typed graph and public execution capability.
 ---
 # Build and integrate an agentic workflow
 
@@ -12,18 +11,22 @@ pinned agent revisions, deterministic gates, schema validators, registered
 module actions, data mappings, and terminal output. It does not own schedules or
 webhook secrets. Those remain optional concerns of `automations.core`.
 
-Read `docs/adr/0006-agentic-workflows.md`, the approved
-`modules/workflows/spec/module.yaml`, and the contracts in
-`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+At the repository root, read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the owning public contracts before
+changing a workflow surface. In the Sandbox, read the approved active-module
+specification and the relevant public contract under `reference/sdk` when it is
+installed. A missing public contract is a core blocker, not a reason to invent
+one or search beyond the session workspace.
 
 ## Pick the correct extension point
 
 - A workflow definition belongs in `workflows.core` and is edited through its
   API or canvas. Do not hardcode a tenant workflow in source.
 - A business operation that a workflow may call is a versioned agent action.
-  Register it through the agents action catalog. If missing, implement it in a
-  separate `agent-tool-design` phase with permission, input, output, timeout,
-  idempotency and audit tests before returning to workflow integration.
+  Register one ordinary `AgentTool` with `context.agentTools`. Optional
+  `workflowTemplate` metadata makes that action a named palette choice through
+  `agents.actions.v2`; it creates no second handler or node kind. Use the
+  authoring recipe below when the action is part of this task.
 - A business module that starts a workflow resolves
   `workflows.execution.v1` from `context.capabilities`. It never imports a
   workflow repository or database.
@@ -33,6 +36,87 @@ Read `docs/adr/0006-agentic-workflows.md`, the approved
 - If the workflow module is absent, the capability registry returns `null`.
   Hide an optional feature or return a clear stable refusal.
 
+## Author a module-owned workflow node template
+
+An action-backed template is module source, not graph source. The business
+manager first records its stable action id, permission, named inputs and
+validation rules, output, effect, replay behavior, and success and refusal
+scenarios in the owning module's specification. In a Sandbox session, the
+operator must approve the hash of that exact spec before implementation. A
+later edit requires renewed approval. If any of these decisions are absent,
+hand the spec delta to `business-manager`; do not infer a field, permission,
+external effect, or idempotency rule from the brief.
+
+Work inside the existing role boundaries:
+
+1. `backend-engineer` owns the tenant-bound service, code-level validator,
+   endpoint or CLI target, and durable target ledger for a mutation. Validation
+   runs before any write and returns a stable bounded refusal. A repeated
+   idempotency key returns its first result; the same key with different input
+   conflicts. Ask backend to supply a missing service rather than writing in
+   `src/services/**` or `src/api/**` from the agentic role.
+2. `agentic-engineer` defines the tool under `src/agent/**`, registers it once
+   from `createServerComposition` in `src/platform.ts`, and adds behavioral
+   tests. `defineApiAgentTool` or `defineCliAgentTool` carries the existing
+   public target. `agents.core` exposes the registered action through
+   `agents.actions.v2`; the business module does not register that capability
+   or access the workflow database.
+3. Give the tool a stable dotted id, positive `contractVersion`, required
+   permission, bounded input and output JSON Schemas, `risk: 'read'` or
+   `'workspace-write'`, `idempotency: 'required'`, cancellation policy, and
+   timeout. A workspace write also needs
+   `idempotencyProtection: 'target-ledger'` backed by the service's real ledger.
+   The handler receives trusted tenant, actor, permission snapshot,
+   idempotency key, and `AbortSignal` from `AgentToolContext`; none comes from
+   graph input. Its output must satisfy its declared schema.
+4. Add static `workflowTemplate: { label, description, effect }` on that same
+   tool. The label is at most 80 characters, the description at most 240, and
+   effect is `local` or `connector-egress`. Metadata contains no code,
+   credential, or tenant value. Invalid or duplicate metadata must fail
+   composition with a safe diagnostic. A workflow-eligible tool without the
+   metadata remains in the generic action editor.
+
+The selected template becomes a normal `action` node with input, success, and
+failure ports. It pins the action id, contract version, schemas, permissions,
+risk, idempotency protection, timeout, cancellation, and effect. Changing any
+of those or the handler's behavior requires a new action identity or contract
+version. The current registry keeps one version per action id, so retain the
+old id and register a distinct id when published graphs must keep running;
+label and description may change without rebinding a published graph.
+
+Graph bindings may never supply a raw secret. `writeOnly` and
+`x-flowdular-secret` apply at every schema depth, including array items and
+alternatives. A marked field cannot carry `default`, `const`, `enum`,
+`example`, or `examples` data. A template requiring
+a raw secret input is ineligible. Accept a nonsecret opaque reference and let
+the owning module resolve a credential from its tenant-bound vault or a
+declared capability. Never put secret values in fixtures, graph definitions,
+events, audit, or error text.
+
+For `connector-egress`, the consumer module declares `connectors.core` and
+`connectors.calls.v1`, uses `caller: 'workflow'`, checks the instance's
+`allowWorkflows` consent, and passes the stable workflow side-effect key to
+the connector. Credentials remain in `connectors.core`. A replay-stable
+output may contain the recorded call id and outcome, not a response body the
+connector replay does not return. Propagate `CALL_OUTCOME_UNKNOWN` as a
+terminal failure when the remote mutation may have happened but no call was
+recorded; never send a second request just to rebuild output. A separate
+provider contract with remote idempotency or readback is required before
+retrying an uncertain mutation.
+
+Prove the module behavior at its public service or action boundary: valid
+input, structural and business validation refusal before mutation, missing
+permission, foreign tenant, same-key replay, different-input conflict,
+cancellation, and recovery around the target commit. Connector actions also
+prove absent consent and `CALL_OUTCOME_UNKNOWN` with a recorded fixture. Run a
+deterministic workflow simulation on invented, reviewed fixtures for success,
+failure, and refusal edges. Assert semantic attempts and edge outcomes, not
+real timestamps; simulation must never invoke the handler, connector, or
+network. Inspect the named template and safe run trail in Sandbox preview,
+then run scoped gates, exact-source `auto-review`, and host eject. The agent
+cannot approve the spec, install code into the running server, or push a
+repository from the Sandbox.
+
 ## Graph contract
 
 Version one is a bounded DAG. The graph contains:
@@ -41,9 +125,11 @@ Version one is a bounded DAG. The graph contains:
 - `agent`: calls one exact immutable agent revision and validates structured
   output.
 - `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `typed-decision`: routes one bounded typed answer through `pass` or `fail`.
 - `gate`: evaluates the versioned allowlisted logic language.
 - `validator`: validates an envelope against a pinned JSON schema.
 - `action`: calls one exact registered action contract version.
+- `human-approval`: waits for an `approvals.core` request to resolve.
 - `merge`: waits for all declared incoming paths.
 - `output`: settles the workflow with a typed result.
 

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/adr/0007-module-owned-agents.md

@@ -266,6 +266,39 @@ existing bindings in one transaction:
 - a definition absent from the sealed registry is unavailable for new work;
   retained revisions and historical runs remain untouched.
 
+Amendment (2026-10-05, `agents.core` 0.15.2): reconciliation no longer runs at
+runtime start, and a lower revision no longer fails boot.
+
+- `agents.core` opens once in every role, before its first request, capability
+  call or `startWorker()`. Opening runs its migrations, then reconciles the
+  registered definitions into the durable catalogue. When every definition
+  matches its stored revision and content hash, opening costs one catalogue read
+  and writes nothing. Otherwise it takes the advisory lock
+  `agents.core.module-catalog`, reads the catalogue again under it and writes
+  only what is still missing or behind, so roles that open together never fail
+  with a duplicate key. A failed opening fails only the request or worker start
+  that triggered it, and the next one opens again.
+- Opening never reads or writes a tenant binding. A request that lists, reads or
+  runs a module agent advances that tenant's stale binding first, inside its own
+  tenant transaction, under the binding row lock and a share lock on the
+  catalogue row, so concurrent requests advance it once. Configuring a binding
+  writes it at the served revision under the same locks. After its execution
+  workers start, the worker advances the bindings no request has touched, in
+  pages of at most 100 tenants, and logs a failing tenant without tenant data.
+  That pass never gates worker readiness.
+- Tenant-created definitions saved before the retained revision ledger are
+  adopted once. A request adopts its own tenant's owed definitions in its own
+  transaction, and the worker adopts the rest in pages after it starts.
+- An instance that registers a lower revision than the catalogue holds, such as
+  an older deployment during a rolling deploy, is superseded for that agent and
+  keeps running. It writes nothing for the agent, lists it unavailable with
+  `MODULE_AGENT_REVISION_SUPERSEDED`, refuses a binding change or a run of it
+  with status 409 and logs a warning once per process and agent. Queued runs and
+  workflow references pinned to a retained executable revision keep the
+  exact-revision contract.
+- The same revision with different content is still refused, by preparation and
+  by the opening, as `MODULE_AGENT_REVISION_DRIFT`.
+
 An old retained revision remains executable after a newer module definition is
 registered only while the owning module is still present, the selected provider
 is usable, and every required registered tool still exists. Module removal is
@@ -327,7 +360,8 @@ not change shape.
 - Business-agent definition content is immutable within one definition
   revision.
 - Duplicate ids, late registration, revision downgrade and same-revision content
-  drift fail platform boot before workers start.
+  drift fail platform boot before workers start. Since the 2026-10-05
+  amendment, a revision downgrade supersedes the agent instead.
 - Module behavior cannot be edited or deleted through tenant APIs.
 - Tenant bindings cannot enable a tool outside the code allowlist.
 - Every execution is tenant-scoped and uses the initiating Actor and trusted

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

@@ -14,11 +14,11 @@ Use the already selected task skill. Consult `.ai/references/catalog` for implem
 3. Identifiers: module, permission and capability ids match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`. `inventory.core` lives in `modules/inventory` as `@flowdular/module-inventory`; permissions are `<module>.<entity>.read` and `<module>.<entity>.manage`.
 4. A module is created only from a spec with `status: approved`. An agent never initiates, infers, or grants approval from its own judgment. After a current, explicit user instruction naming the spec, a host coding agent may record that decision mechanically by following `spec-approval`; a sandbox specialist can only request approval, and the operator route records the exact approved hash. Spec `permissions[].id` equal the constants in `src/acl/permissions.ts`: the spec is what `auth sync-scopes` grants.
 5. Every endpoint is `defineEndpoint` from `@flowdular/sdk/server` with `access: { kind: 'permission', permission }` and `resolveIdentity: endpointIdentityFromContext`. Deny by default; a public endpoint needs a written reason. No raw `new ServerRoute` outside `modules/auth`.
-6. The tenant id comes only from `principalFromContext(octane)!.tenantId`, never from the body, query or headers. Every query on a tenant-owned table filters by `tenant_id`; unique constraints and indexes start with `tenant_id`; SQL uses bound parameters. PostgreSQL tenant tables also enable and force row-level security with `USING` and `WITH CHECK` policies bound to transaction-local `coreloom.tenant_id`. Every repository operation runs through `database.transaction(..., { tenantId, access })`; the runtime role is never a superuser and never has `BYPASSRLS`, while a separate migration lease may own DDL. `WHERE tenant_id = ...` remains defense in depth.
+6. The tenant id comes only from `principalFromContext(octane)!.tenantId`, never from the body, query or headers. Every query on a tenant-owned table filters by `tenant_id`; unique constraints and indexes start with `tenant_id`; SQL uses bound parameters. PostgreSQL tenant tables also enable and force row-level security with `USING` and `WITH CHECK` policies bound to transaction-local `flowdular.tenant_id`. Every repository operation runs through `database.transaction(..., { tenantId, access })`; the runtime role is never a superuser and never has `BYPASSRLS`, while a separate migration lease may own DDL. `WHERE tenant_id = ...` remains defense in depth.
 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.
@@ -26,7 +26,7 @@ Use the already selected task skill. Consult `.ai/references/catalog` for implem
 15. One screen, form, table or stateful region per named component. Records own the page; create and edit happen in a `Drawer`. Every screen shows loading, empty, error, populated and denied.
 16. Tests live in `tests/*.test.ts`: identity, tenant isolation, uniqueness, one 401 and one 403 per endpoint, each validation bound. Repository behavior uses `createTestDatabaseProvider()` from `@flowdular/sdk/database-testing`: PGlite locally and isolated server PostgreSQL in CI. Open one provider per test file, migrate once, and truncate module tables between cases (`modules/profile/tests/support/database.ts`). Tenancy tests use two tenants, prove `TENANT_CONTEXT_REQUIRED` without a transaction tenant id, prove RLS prevents cross-tenant reads and writes under the non-bypass runtime role, and cover `WITH CHECK`. Tenant fixture work also supplies tenant context on a migration connection. The sandbox `tests` gate passes with zero tests, so an empty suite is a defect.
 17. Translations are live. Every module contribution registers all declared `translations/*.json` bundles, user-facing copy uses fully qualified `t('<module>.<key>')` keys, navigation labels are lazy getters, locale-aware formatting uses `activeLocale()`, and every locale has the same key set, where a plural family (`<key>.one`/`.other`, plus `.few`/`.many` in `pl`, read as `t(key, { count })`) counts as one key. `module validate` rejects missing files, key drift, and missing static translation keys.
-18. Numbered migration SQL is immutable source. `migrations/000N_<module>_<name>.up.sql` and `.down.sql` are PostgreSQL and the only schema source; there is no dialect subdirectory. `src/services/migration.ts` mirrors every `.up.sql` byte for byte as `databaseMigrations: readonly DatabaseMigration[]` with `sql: { postgresql: ... }`, and the runtime calls `runDatabaseMigrations` through its provider lease. The namespaced `_coreloom_migrations_v2` ledger records the checksum, adopts only an explicit complete `inspectExisting` result (`postgresTenantTableState` is the standard check), and refuses drift, duplicates, or partial schema. Add a new numbered, additive migration instead of changing existing bytes. A tenant table's migration includes enabled and forced RLS plus a tenant policy, with the policy behavior covered by tests.
+18. Numbered migration SQL is immutable source. `migrations/000N_<module>_<name>.up.sql` and `.down.sql` are PostgreSQL and the only schema source; there is no dialect subdirectory. `src/services/migration.ts` mirrors every `.up.sql` byte for byte as `databaseMigrations: readonly DatabaseMigration[]` with `sql: { postgresql: ... }`, and the runtime calls `runDatabaseMigrations` through its provider lease. The namespaced `_flowdular_migrations_v2` ledger records the checksum, adopts only an explicit complete `inspectExisting` result (`postgresTenantTableState` is the standard check), and refuses drift, duplicates, or partial schema. Add a new numbered, additive migration instead of changing existing bytes. A tenant table's migration includes enabled and forced RLS plus a tenant policy, with the policy behavior covered by tests.
 19. Module CLI commands live in `src/cli/commands.json` and `src/cli/index.ts`, metadata-identical, inside the module namespace.
 20. Passwords, session tokens and provider credentials never leave `auth.core` (or the `agents.core` vault) and never appear in logs, audit metadata or responses.
 21. `setup quick` and `auth greenfield` are destructive local resets. Preview first, stop the app, never point them at a custom or deployed database.

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

@@ -47,8 +47,29 @@ flowdular database restore --input <dir> --apply --confirm restore-database
 flowdular setup check                              # alias of doctor
 flowdular setup quick [--apply --confirm reset-local-auth]
 flowdular setup migrate-state [--apply --confirm migrate-legacy-state]
+flowdular deploy targets                            # runtime support and launch modes
+flowdular deploy plan <target> [--json]              # read-only provider preflight
+flowdular deploy start docker [--apply]              # local Compose launch; without --apply returns plan
+flowdular deploy start vercel [--apply]              # provision and deploy to Vercel Production; without --apply returns plan
 ```
 
+`deploy start docker --apply` prints a one-time setup token, so it refuses
+`--json` and redirected output and must run in a private interactive terminal. The deployment targets are
+documented in [infra/README.md](../infra/README.md). `deploy plan vercel`
+checks the build source and links to Vercel import when the branch is pushed.
+
+`deploy start vercel --apply` drives the signed-in Vercel CLI: it provisions
+Neon PostgreSQL and its roles, writes the stable keys to
+`.flowdular/deploy/vercel-<project id>.env` (mode 0600) before uploading them
+through stdin, connects a private Blob store and deploys to Production. While
+the database has no workspace it prints a one-time token for `/setup`, where the
+first workspace and owner are created in the browser; Vercel holds only the
+token's SHA-256. That gives it the same terminal rules as the Docker launch.
+`--database-url-env NAME` takes the owner URL from a variable instead of Neon;
+`--plan hobby|pro` overrides the plan read from `vercel whoami --json`;
+`--project`, `--scope`, `--origin` and `--cron` are optional. A rerun resumes
+without regenerating keys. See [infra/vercel/README.md](../infra/vercel/README.md).
+
 ### Authoring a migration
 
 `migration new` writes exactly two files,
@@ -59,7 +80,7 @@ already filled in. Replace the placeholder columns with the real schema.
 `migration verify` then checks that every applied ledger checksum still matches,
 that every tenant table a migration leaves behind has `ENABLE ROW LEVEL
 SECURITY`, `FORCE ROW LEVEL SECURITY` and a tenant policy declared after the
-last statement that puts the table in place, that a `coreloom_background` policy
+last statement that puts the table in place, that a `flowdular_background` policy
 grants no more than `FOR SELECT`, and that every `migrations/*.up.sql` file has
 a matching id in `databaseMigrations` and the other way round.
 
@@ -113,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)
 
@@ -176,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
@@ -198,6 +235,6 @@ per-package seconds in `scripts/test-weights.json`. A new package without a
 weight counts as 30 seconds; refresh the file from a CI run when the shards
 drift apart.
 
-## Official module distribution
+## Module Studio distribution
 
-`module search`, `module info`, `module install`, `module update`, `module recover`, and `module validate --locked` manage reviewed external source. See [the distribution contract](module-distribution.md) for flags, trust, activation and recovery.
+`module source`, `module search`, `module info`, `module plan`, `module apply`, `module recover`, and `module validate --locked` manage reviewed external source. See [Module Studio](module-distribution.md) for flags, trust, activation and recovery.

package/agent-template/docs/configuration.md

@@ -11,18 +11,56 @@ deployments must set the secret keys.
 | `FD_ENV`             | `NODE_ENV`, else `development`    | Environment the CLI and destructive guards check                           |
 | `FD_PORT`            | `3000`                            | Host port published by the container                                       |
 | `FD_TRUST_PROXY`     | `false`                           | Trust `X-Forwarded-*` behind a reverse proxy                               |
+| `FD_RUNTIME_ROLE`    | `combined`                        | `combined` serves HTTP and runs module workers; `web` or `tick`, see below |
 | `FD_CSP`             | built-in policy                   | Override the Content Security Policy                                       |
 | `FD_CSP_REPORT_ONLY` | `true` outside production         | Report CSP violations instead of enforcing them                            |
 | `FD_LOG_FORMAT`      | `json` in production, else `text` | `json` (one object per line) or `text`; see [operations.md](operations.md) |
 | `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
+a `combined` or a `tick` process on the same database, object storage and keys.
+A `tick` process runs the module workers only inside a tick request that
+presents `FD_WORKER_TICK_SECRET` (at least 32 characters) as a bearer token, for
+at most `FD_WORKER_TICK_WINDOW_MS` (default 50000), and drains them before it
+answers.
+A Vercel deployment works this way; see
+[infra/vercel/README.md](../infra/vercel/README.md).
 
 ## Branding
 
 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.
@@ -289,6 +327,7 @@ message was not delivered.
 | `FD_AGENT_RUN_GRANT_KEY`           | generated dev key | Base64 32-byte key signing run grants                |
 | `FD_AGENT_WORKER_CONCURRENCY`      | `2` (1 to 16)     | Parallel run workers                                 |
 | `FD_AGENT_WORKER_LEASE_MS`         | `30000`           | Run lease before recovery reclaims it                |
+| `FD_AGENT_WORKER_DRAIN_MS`         | `0` (0 to 720000) | Time a stopping worker lets claimed runs finish      |
 | `FD_AGENT_PROVIDER_HOST_ALLOWLIST` | empty             | Hostnames an external provider may be called on      |
 
 Outside production the keys are generated once under `.flowdular/data`. The
@@ -610,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
@@ -658,7 +698,7 @@ an object moved into another tenant's prefix does not open.
 
 | Variable                             | Default                             | Purpose                                                                      |
 | ------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------- |
-| `FD_STORAGE_ADAPTER`                 | `s3` in production, else `local`    | `local` or `s3`; `local` is refused in production                            |
+| `FD_STORAGE_ADAPTER`                 | `s3` in production, else `local`    | `local`, `s3` or `vercel-blob`; `local` is refused in production             |
 | `FD_STORAGE_LOCAL_DIRECTORY`         | `.flowdular/data/storage`           | Object directory of the local adapter                                        |
 | `FD_STORAGE_S3_BUCKET`               | none                                | Bucket name; required by the S3 adapter                                      |
 | `FD_STORAGE_S3_REGION`               | none                                | Signing region; required by the S3 adapter                                   |
@@ -666,10 +706,23 @@ an object moved into another tenant's prefix does not open.
 | `FD_STORAGE_S3_ACCESS_KEY_ID`        | none                                | Access key id; required by the S3 adapter                                    |
 | `FD_STORAGE_S3_SECRET_ACCESS_KEY`    | none                                | Secret access key; required by the S3 adapter                                |
 | `FD_STORAGE_S3_FORCE_PATH_STYLE`     | `false`                             | `<endpoint>/<bucket>/<key>` instead of a bucket subdomain                    |
+| `BLOB_STORE_ID`                      | set by Vercel                       | Blob store of the `vercel-blob` adapter, authenticated with Vercel OIDC      |
+| `BLOB_READ_WRITE_TOKEN`              | none                                | Blob read-write token for the `vercel-blob` adapter outside Vercel           |
 | `FD_STORAGE_MAX_OBJECT_BYTES`        | `26214400` (25 MiB)                 | Per-object limit, 1024 to 268435456; a stream is cut off at it               |
 | `FD_STORAGE_ENCRYPTION_KEY`          | derived dev key                     | Base64 32-byte key sealing every object and read URL; required in production |
 | `FD_STORAGE_ENCRYPTION_KEY_PREVIOUS` | empty                               | Retired object keys, comma separated, read only                              |
 
+`vercel-blob` keeps the encrypted objects in a private Vercel Blob store, so a
+Vercel deployment needs no separate bucket. Connecting a Blob store to the
+Vercel project sets `BLOB_STORE_ID`, and the SDK authenticates with the
+deployment's OIDC token, so nothing else is configured there. Outside Vercel,
+set `BLOB_READ_WRITE_TOKEN`. The platform refuses to start when neither is
+present. Reads bypass the Blob cache, so a re-sealed or deleted object is never
+served from an older copy. A Vercel Function accepts at most 4.5 MB of request
+or response body, so set `FD_STORAGE_MAX_OBJECT_BYTES` to at most `4194304`
+there. Lowering the limit makes an existing larger object unreadable through
+this adapter, and a key rotation leaves it sealed under its old key.
+
 A module writes through `context.storage` and never sees an adapter, a bucket or
 a path. Only these content types are stored, and the bytes are verified against
 the declared type before the write: PDF, PNG, JPEG, GIF, WebP, plain text, CSV,
@@ -746,7 +799,9 @@ acquires a lease from the platform provider configured above, so the
 openssl rand -base64 32
 ```
 
-For containers, copy `infra/docker/.env.example` to `infra/docker/.env` and fill
-in every empty value: every encryption key above, including the connectors
-and audit anchor keys, the object store settings and the four PostgreSQL role
-passwords. See [../infra/README.md](../infra/README.md).
+For a local Docker installation, run `node infra/docker/start.mjs`. It creates
+`infra/docker/.env` with missing secrets, starts PostgreSQL and the bundled
+object store, then opens the first-run web setup. Keep that file with database
+and object-store backups; changing its keys or passwords later does not rotate
+existing data or PostgreSQL roles. Other deployments supply these values through
+their own secret manager. See [../infra/README.md](../infra/README.md).

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,18 +77,21 @@ 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
 
 The embedded adapter creates the same roles a deployment configures, so a local
 run enforces the isolation a deployment enforces instead of approximating it.
 
-| Role                  | Owns                                        | Constraints                                                                                 |
-| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `coreloom_migrator`   | The schema. Serves the `migration` purpose. | Owns every table the migrations create.                                                     |
-| `coreloom_runtime`    | Request-time reads and writes.              | No `SUPERUSER`, no `BYPASSRLS`, and every handle it lends requires a transaction tenant id. |
-| `coreloom_background` | Cross-tenant polls.                         | Read-only, and no blanket table grant.                                                      |
+| Role                   | Owns                                        | Constraints                                                                                 |
+| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `flowdular_migrator`   | The schema. Serves the `migration` purpose. | Owns every table the migrations create.                                                     |
+| `flowdular_runtime`    | Request-time reads and writes.              | No `SUPERUSER`, no `BYPASSRLS`, and every handle it lends requires a transaction tenant id. |
+| `flowdular_background` | Cross-tenant polls.                         | Read-only, and no blanket table grant.                                                      |
 
 ## Leases
 
@@ -100,13 +108,13 @@ const lease = await context.databases.acquire({
 });
 ```
 
-| Purpose      | Role                  | Used for                                            |
-| ------------ | --------------------- | --------------------------------------------------- |
-| `migration`  | `coreloom_migrator`   | Applying migrations and resetting a database        |
-| `runtime`    | `coreloom_runtime`    | The deployed application                            |
-| `preview`    | `coreloom_runtime`    | A local run and the sandbox preview                 |
-| `test`       | `coreloom_runtime`    | A test suite                                        |
-| `background` | `coreloom_background` | A scheduler poll or recovery that precedes a tenant |
+| Purpose      | Role                   | Used for                                            |
+| ------------ | ---------------------- | --------------------------------------------------- |
+| `migration`  | `flowdular_migrator`   | Applying migrations and resetting a database        |
+| `runtime`    | `flowdular_runtime`    | The deployed application                            |
+| `preview`    | `flowdular_runtime`    | A local run and the sandbox preview                 |
+| `test`       | `flowdular_runtime`    | A test suite                                        |
+| `background` | `flowdular_background` | A scheduler poll or recovery that precedes a tenant |
 
 A runtime acquires its leases lazily, one per runtime, and releases them from
 composition `dispose()`. `modules/profile/src/server/runtime.ts` is the shape:
@@ -164,14 +172,14 @@ codes.
 
 Every tenant table enables and forces row-level security and carries a policy
 whose `USING` and `WITH CHECK` compare `tenant_id` with the transaction-local
-`coreloom.tenant_id` setting:
+`flowdular.tenant_id` setting:
 
 ```sql
 ALTER TABLE profile_records ENABLE ROW LEVEL SECURITY;
 ALTER TABLE profile_records FORCE ROW LEVEL SECURITY;
 CREATE POLICY profile_records_tenant_policy ON profile_records
-  USING (tenant_id = current_setting('coreloom.tenant_id', true))
-  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+  USING (tenant_id = current_setting('flowdular.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('flowdular.tenant_id', true));
 ```
 
 `database.transaction(body, { tenantId, access })` sets that value for the
@@ -201,7 +209,7 @@ repository.
 
 ## Migrations
 
-The ledger is `_coreloom_migrations_v2`. It carries the module namespace because
+The ledger is `_flowdular_migrations_v2`. It carries the module namespace because
 every module shares one database. Checksums cover the exact SQL, and a mismatch
 is checked before any outstanding migration runs.
 
@@ -257,7 +265,7 @@ schema.
 `migration verify` checks that every applied ledger checksum still matches, that
 every tenant table a migration leaves behind has `ENABLE ROW LEVEL SECURITY`,
 `FORCE ROW LEVEL SECURITY` and a tenant policy declared after the last statement
-that puts the table in place, that a `coreloom_background` policy grants no more
+that puts the table in place, that a `flowdular_background` policy grants no more
 than `FOR SELECT`, and that every `migrations/*.up.sql` file has a matching id in
 `databaseMigrations` and the other way round.
 
@@ -272,10 +280,10 @@ A table it may poll says so itself, in its own migration:
 
 ```sql
 CREATE POLICY <table>_background_policy ON <table>
-  FOR SELECT TO coreloom_background
+  FOR SELECT TO flowdular_background
   USING (<the narrowest predicate that still finds the work>);
-REVOKE SELECT ON <table> FROM coreloom_background;
-GRANT SELECT (<only the columns the poll reads>) ON <table> TO coreloom_background;
+REVOKE SELECT ON <table> FROM flowdular_background;
+GRANT SELECT (<only the columns the poll reads>) ON <table> TO flowdular_background;
 ```
 
 A table that forgets to is invisible to that role, and every column outside the

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
@@ -270,7 +273,7 @@ them; outside the shell the English defaults and the host locale apply.
 | `Tabs`             | Accessible tablist: required `id`, `items` (`id`, `label`, `disabled`), `active`, `onChange`, `label`; arrows, Home and End move roving focus, an `active` that names no enabled tab selects the first enabled one, and the caller renders the panel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `SortableList`     | Reorderable list: required `id`, `label`, `items` (`id`, `label`), `onReorder(ids)`, `handleLabel(item)`, `instructions`, `announce(event)`, `renderItem(item, index)`, `disabled`; a grip per item drags with a pointer or picks up, moves and drops from the keyboard, with a polite live region                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `ToastHost`        | Renders the toast queue: `label`, `closeLabel`, optional `store`. Raise toasts with `toasts.success/error/info(message)`; `createToastStore` makes a scoped queue                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions, which move under the title and wrap onto more rows when the header is too narrow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `EmptyState`       | `icon`, `title`, children, optional `code`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `Alert`            | Inline message: `tone` danger (default), warning, info                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `Drawer`           | Editor panel over the records: `open`, `title`, `subtitle`, `width` md/lg, `onClose`; traps Tab and restores focus to the opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -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`),