create-flowdular 0.4.3 → 0.6.0

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/.codex/agents/module-executor.toml

@@ -0,0 +1,17 @@
+name = "module-executor"
+description = "Implement one Flowdular blueprint end to end at the repository root: scaffold from an approved spec, write the module, run the gates and join it to the platform through the CLI. Use once a spec is approved and the change is ready to be built."
+developer_instructions = '''
+Your role prompt is `.ai/agents/module-executor.md`. Read it with the blueprint
+under `.ai/blueprints/<id>/` and the one matching skill in
+`.ai/skills/<name>/SKILL.md` before changing anything.
+
+Implement only what the approved spec's acceptance scenarios describe, inside the
+blueprint's `allowed-paths.yaml`. Join the platform through
+`pnpm flowdular module enable <id> --apply` and `auth sync-scopes`; never edit
+`flowdular.json`, `platform/package.json`, `platform/src/generated/**` or
+`platform/octane.config.ts` by hand.
+
+Run the module gates and `pnpm verify` yourself and report their exact commands
+and results. Never waive a gate. End with `HANDOFF: reviewer - <what to review>`
+or `HANDOFF: none - <blocker>`.
+'''

package/agent-template/.codex/agents/reviewer.toml

@@ -0,0 +1,14 @@
+name = "reviewer"
+description = "Review a finished Flowdular change against its approved spec, the blueprint, the invariants and the executable evidence, and report findings by severity. Use as a separate phase before delivery or a pull request. Reports defects and fixes nothing."
+developer_instructions = '''
+Your role prompt is `.ai/agents/reviewer.md` and the one task skill for this
+phase is `.ai/skills/auto-review/SKILL.md`. Read both before reviewing.
+
+You write no production code. Review the complete requested change, its
+requirements, callers and tests; report concrete findings by severity with file,
+line and failure scenario. Never waive missing or failing verification, and never
+approve a change whose evidence you have not seen run.
+
+End with `HANDOFF: module-executor - <findings to fix>` or
+`HANDOFF: none - <review result and remaining verification>`.
+'''

package/agent-template/.codex/agents/spec-author.toml

@@ -0,0 +1,15 @@
+name = "spec-author"
+description = "Turn a business request into a schema-valid Flowdular module specification at the repository root. Use before any implementation, for a new module spec or a change to an existing one. Writes only modules/<dir>/spec/module.yaml and never approves it."
+developer_instructions = '''
+Your role prompt is `.ai/agents/spec-author.md` and the one task skill for this
+phase is `.ai/skills/spec-interview/SKILL.md`. Read both before writing.
+
+You write only `modules/<dir>/spec/module.yaml`. Propose a platform default for
+every decision and ask the user for what cannot be inferred; never guess a
+business fact. Never set `status: approved`: approval is the user's, recorded by
+the `spec-approval` skill.
+
+`pnpm flowdular spec validate --all --json` must report the file valid before you
+report. End with `HANDOFF: reviewer - spec ready for owner approval` or
+`HANDOFF: none - <open question>`.
+'''

package/agent-template/AGENTS.md

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

package/agent-template/CLAUDE.md

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

package/agent-template/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,7 +14,7 @@ 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`.
@@ -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.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.
 
@@ -198,6 +219,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,6 +11,7 @@ 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) |
@@ -18,6 +19,43 @@ deployments must set the secret keys.
 | `FD_METRICS`         | `false`                           | Expose `GET /api/metrics`; see [operations.md](operations.md)              |
 | `FD_METRICS_TOKEN`   | none                              | Bearer token a metrics scrape must present                                 |
 
+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
+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.
+
+An address is stored only as a path on this deployment (`/brand/logo.svg`) or an
+https URL; `javascript:`, `data:` and protocol-relative values are refused when
+they are written. Every https branding image origin is added to `img-src` of the
+policy this deployment serves, including an `FD_CSP` of your own, so the browser
+loads it; an `FD_CSP` without an `img-src` directive is left alone and then has
+to name the origin itself. The label an authenticator lists an enrolled account
+under is the same name, decided by the server, so a member who enrols after a
+rename sees the new one.
+
+An application scaffolded before this release owns its own `platform/src/App.tsrx`
+and `platform/index.html`, so its head does not follow the settings until it
+adopts two changes the template now carries: `configureBrandingFromPage(props)`
+plus the `Seo`, `Link` and `Meta` block in the entry, and the removal of the
+static `<link rel="icon">` and `<meta name="theme-color">` from the page, which
+would otherwise compete with the rendered ones. `pnpm flowdular doctor` reports
+both as the `platform.branding` check. The navigation, the mobile header and the
+sign-in screen follow the settings without any change.
+
 ## Observability
 
 Spans are always recorded into a bounded in-process buffer and the logger always
@@ -262,6 +300,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
@@ -631,7 +670,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                                   |
@@ -639,10 +678,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,
@@ -719,7 +771,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

@@ -79,11 +79,11 @@ memory.
 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 +100,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 +164,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 +201,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 +257,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 +272,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

@@ -25,7 +25,7 @@ shared primitives, tokens, and the rules for using them.
   refuses a class no stylesheet declares, there and in every `.tsrx`.
 - `platform/public`: `favicon.svg`, `og.png` (1200x630 Open Graph image).
 - Brand mark geometry is generated: `node packages/ui/scripts/gen-mark.mjs`
-  rewrites `packages/ui/src/brand/mark.ts` from the weave parameters.
+  rewrites `packages/ui/src/brand/mark.ts` from the bar parameters.
 
 ## Rules
 
@@ -270,7 +270,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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -282,7 +282,7 @@ them; outside the shell the English defaults and the host locale apply.
 | `Switch`           | Boolean setting that applies on its own (no form submit): `checked`, `label` as the accessible name, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `ConfirmDialog`    | One question before an irreversible action: `open`, `title`, children, `confirmLabel`, `tone` danger (default) or primary, `busy`, `onConfirm`, `onCancel`; traps Tab and restores focus to the opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `Icon`             | Stroke icon by `name` from `ICON_PATHS`; `size` 18 default, 16 in controls, 14 in `Button size="sm"`; `strokeWidth` 1.75 default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `BrandMark`        | The weave: `size`, `signature` (copper weft, large brand moments only), `tone` brand, current, inverse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `BrandMark`        | Three bars, the short one copper: `size`, `tone` brand, current, inverse (`signature` is accepted and changes nothing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 `Drawer` takes one child, a `ui-drawer__form` (fields in `ui-drawer__body`, actions in `ui-drawer__foot`) or a plain `ui-drawer__body`; it closes on Escape and on the scrim. `SearchField` carries no visible label, so pass `label` as its accessible name. `FormField` renders `error` in place of `help` and marks it `role="alert"`. `SettingRow` is presentation only: the caller owns the draft value, the save call, and passes the result back as `status`. `ScopeSummary` is the read side of `CheckGrid`; both keep the first-seen module order, and `summarizeScopes` is exported for callers that need the grouping without the markup.