create-flowdular 0.2.6 → 0.3.1

package/agent-template/docs/sandbox.md

@@ -0,0 +1,212 @@
+# Sandbox
+
+The sandbox is a separate, chat-first application that builds a change in an
+isolated workspace, drives the coding agent your team already uses, runs the
+same gates the platform runs, and previews the result inside the real
+application shell. A session carries as many modules as the work touches.
+
+Full documentation lives with the package:
+[packages/sandbox/README.md](https://github.com/flowdular/flowdular/blob/main/packages/sandbox/README.md).
+
+## Start it
+
+```bash
+pnpm sandbox            # from this repository
+npx @flowdular/sandbox   # from any Flowdular workspace
+```
+
+The launcher walks up to `flowdular.json` to find the workspace and opens
+`http://127.0.0.1:4320`. `--port`, `--workspace`, `--host` and `--mode` override
+the defaults.
+
+## Connect it to a running application
+
+The sandbox is a client of a running Flowdular application and never opens the
+platform database. The preview gets its own embedded PostgreSQL under the
+session data directory, with the same roles and the same forced row-level
+security a deployment has, and it is thrown away with the session.
+
+1. In the application, open Administration, API tokens, and issue a token with
+   `sandbox.access.use` plus the read scopes the preview should see. Add
+   `sandbox.preview.data` for live data and `sandbox.modules.eject` for eject.
+2. Grant sandbox access to the account, in the app under Development, Sandbox,
+   or from the CLI:
+
+```bash
+pnpm flowdular sandbox grant --email admin@example.com --tenant operations-demo --apply
+pnpm flowdular sandbox access --tenant operations-demo
+```
+
+3. Paste the token and the application address into the sandbox connect screen.
+
+The token is encrypted at rest under `.flowdular/sandbox/secret.key` and is never
+returned to the browser. The application may run anywhere: locally on
+`http://127.0.0.1:4310` or a deployment.
+
+## Modes
+
+| Mode          | Binding              | Coding agents                       |
+| ------------- | -------------------- | ----------------------------------- |
+| `loopback`    | loopback interface   | local `claude` and `codex`, or BYOK |
+| `self-hosted` | configured interface | bring your own key only             |
+
+A non-loopback `--host` forces `self-hosted`. A sandbox that cannot prove it is
+loopback never offers a local binary, because a local binary carries the
+operator's own login.
+
+## How a session works
+
+A planner names the modules the brief touches and the first specialist role.
+Business, UX, backend, frontend and agentic roles hand off inside one session;
+each turn writes only in its own allowed paths and is followed by the gates that
+role declares. The roles live in [`.ai/agents/sandbox`](../.ai/agents/sandbox),
+so a workspace can change them.
+
+When the work is done, eject it into `modules/` and enable it, or open a pull
+request with the gate evidence attached.
+
+## Deliver as a pull request
+
+The eject route (`POST /sandbox/api/sessions/:id/eject`) takes `target:
+'workspace' | 'git-pr'`. `workspace` copies the session modules into `modules/`
+of this checkout. `git-pr` (`packages/sandbox/src/server/delivery/git-pr.ts`)
+commits the same change on a branch and opens a pull request; the operator's
+working tree and index stay untouched because the work happens in a detached
+worktree under `.flowdular/sandbox/worktrees/<session id>`, removed afterwards.
+
+### Configuration
+
+Project settings live in `flowdular.json` under `sandbox.delivery`, read at
+request time (`delivery/configuration.ts`): `targets`, `default`,
+`maxChangedFiles` and `git` with `remote`
+(`origin`), `repository` (`owner/name`, derived from the remote when null),
+`baseBranch` (`main`), `branchPrefix` (`sandbox`), `provider` (`github` or
+`none`), `mode` (`auto`, `direct` or `fork`), `forkOwner` and `reviewers`.
+
+Operator settings live in the sandbox configuration
+(`.flowdular/sandbox/config.json`, `GitHubDeliveryConfiguration` in
+`server/config.ts`) and are set from the sandbox settings screen, not from
+environment variables: `enabled`, `overridesProject`, `remote`, `repository`,
+`baseBranch`, `branchPrefix`, `mode`, `forkOwner`, `reviewers` (settings
+request fields `githubEnabled`, `githubOverridesProject`, `githubRemote` and so
+on). With `overridesProject` the operator values replace the project `git`
+block except `provider`. `enabled: false` disables the target with
+`EJECT_TARGET_DISABLED`. A provider token (`githubToken` in the settings
+request, stored sealed as `gitProviderToken`) is handed to `gh` as `GH_TOKEN`
+and to `git` as a redacted authorization header; it never appears in command
+arguments, remote URLs or step output.
+
+### Branch and pull request
+
+The branch is `<branchPrefix>/<module directory>-<first 8 characters of the
+session id>`, created from `<remote>/<baseBranch>`. In the worktree the sandbox
+stages the modules, runs `pnpm install`, `module enable` for each new module and
+the platform typecheck, then checks the guardrails: changed paths limited to the
+session modules, the lockfile and the CLI-owned composition files, the file
+count within `maxChangedFiles` (else `.ai/policies/task-budgets.yaml`), new
+packages within `maxNewDependencies` from `.ai/policies/task-budgets.yaml`
+(default 0, per-kind overrides). Owners and the cross-owner reviewer
+requirement (`crossOwnerChanges.requireReviewer`) come from
+`.ai/policies/path-ownership.yaml`. The commit reads
+`sandbox: add|update <module id>` with the session id and the gate summary; the
+push uses `--force-with-lease`. A branch that exists but was not created for
+this session is refused (`GIT_BRANCH_CONFLICT`).
+
+With `provider: github` and a working `gh auth status`, `gh pr create` opens the
+pull request against `baseBranch` with `--reviewer` from `reviewers`; when a
+pull request for the branch is already open, the push updates it. `mode: auto`
+uses a direct push only after GitHub confirms push access and otherwise asks the
+operator to choose `direct` or `fork`; only an explicit `fork` creates or reuses
+`<forkOwner>/<name>`. Without `gh`, without a login, or with `provider: none`,
+the branch is still pushed; the plan shows a GitHub compare link when
+`repository` is configured or derived from a GitHub remote URL, otherwise the
+remote and branch name.
+`.flowdular/sandbox/sessions/<id>/delivery.json` keeps the branch and the URL.
+
+### Gates as evidence
+
+Delivery reruns every gate from `delivery/plan.ts` (`spec-schema`,
+`module-schema`, `dependencies`, `typecheck`, `tests`, `format`, `auto-review`)
+before anything is committed; a missing, failed or skipped result stops it
+(`EJECT_GATES_MISSING`, `EJECT_GATES_FAILED`), and each module needs a current
+review record (`EJECT_REVIEW_REQUIRED`) and an approved spec hash. The pull
+request body carries the spec version and status per module, a table of gate,
+module and result, the files added, modified and removed, the risks the
+guardrails noticed, and the post-merge `auth sync-scopes` command. The table is
+what the sandbox measured on the delivered bytes; `pnpm verify` on the branch
+and a human review remain the repository's own gate.
+
+## Decisions the specialist needs
+
+A specialist that cannot continue without a business decision ends its reply
+with one fenced block tagged `questions` holding a single JSON object:
+
+````
+```questions
+{
+	"questions": [
+		{
+			"id": "Q-1",
+			"question": "Who may cancel a booking?",
+			"options": ["Only the owner", "Any team member"],
+			"recommended": "Only the owner",
+			"allowFreeText": true
+		}
+	]
+}
+```
+````
+
+The sandbox parses it server side and bounds it: at most 12 questions, unique
+ids shaped `Q-1`, a question of 1 to 400 characters, at most 8 distinct options
+of 1 to 120 characters, and a recommendation that must be one of those options.
+`allowFreeText` defaults to false, and a question with neither an option nor
+free text cannot be answered, so it is refused. The block has to be the last
+thing in the reply apart from the mandatory handoff line, and a reply carries at
+most one. A block the sandbox cannot read is a warning on that turn, never a
+failed turn: the words of the reply still stand and the transcript says why the
+block was ignored.
+
+A readable block is stored on the session as `pendingQuestions`, with the
+transcript sequence of the message that asked, the role that asked and the
+module it asked about. Records written before the field existed read as `null`.
+Every turn rewrites it, so the form only ever shows what the newest specialist
+is waiting on.
+
+The session view shows the questions as a list rather than as JSON, and offers a
+form below the open handoff: one radio group per question with the
+recommendation preselected, a free-text field where the specialist allowed one,
+and an optional note. Submitting posts
+
+```
+POST /sandbox/api/sessions/:id/answers
+{ "answers": [{ "id": "Q-1", "answer": "Only the owner" }], "message": "optional" }
+```
+
+behind the same origin, header and ownership checks as every other mutation. It
+clears `pendingQuestions` and starts the next turn in the role that asked, in
+the module it asked about, with the decisions leading the request text:
+
+```
+Decisions:
+- Q-1: Who may cancel a booking? -> Only the owner
+
+<the operator's optional message>
+```
+
+The response is the turn stream, exactly as `POST /sandbox/api/sessions/:id/turn`
+answers. Refusals, each a stable error code: `409 NO_PENDING_QUESTIONS` when
+nothing is waiting, `409 SESSION_ARCHIVED`, `409 SESSION_DELIVERED`, and `400
+INVALID_INPUT` for a body that leaves a question unanswered, names a question
+the session did not ask, exceeds 400 characters, or gives an answer that is not
+one of the offered options when the specialist allowed no free text.
+
+## Operator commands
+
+```bash
+pnpm flowdular sandbox sessions --tenant <tenant>
+pnpm flowdular sandbox session-archive --tenant <tenant> --id <session-id> --apply
+pnpm flowdular sandbox session-delete --tenant <tenant> --id <session-id> --apply
+pnpm flowdular sandbox revoke --email <email> --tenant <tenant> --apply
+pnpm flowdular sandbox audit-verify --tenant <tenant>
+```

package/agent-template/platform/scripts/build.mjs

@@ -17,13 +17,24 @@ const environment = {
 	   throwaway state directory below; runtime still reads its real adapter. */
 	FD_ENV: 'development',
 	FD_INTERNAL_BUILD: 'true',
+	/* The bundler evaluates the server composition. It must not open a trace or
+	   error egress to the deployment's collector while building. */
+	FD_TRACE_EXPORTER: 'none',
+	FD_ERROR_SINK: 'none',
 	FD_DATABASE_ADAPTER: 'pglite',
 	FD_DATABASE_PGLITE_DIRECTORY: join(stateDirectory, 'pglite'),
 	FD_AGENT_CREDENTIAL_KEY: buildSecret(),
 	FD_AGENT_RUN_GRANT_KEY: buildSecret(),
+	FD_APPROVAL_GRANT_KEY: buildSecret(),
 	FD_AUTOMATIONS_CREDENTIAL_KEY: buildSecret(),
+	FD_NOTIFICATIONS_SECRET_KEY: buildSecret(),
 	FD_WORKFLOWS_PAYLOAD_KEY: buildSecret(),
 	FD_WORKFLOWS_CURSOR_KEY: buildSecret(),
+	FD_STORAGE_ADAPTER: 'local',
+	FD_STORAGE_LOCAL_DIRECTORY: join(stateDirectory, 'storage'),
+	FD_STORAGE_ENCRYPTION_KEY: buildSecret(),
+	FD_CONNECTORS_SECRET_KEY: buildSecret(),
+	FD_AUDIT_ANCHOR_KEY: buildSecret(),
 };
 
 try {

package/dist/bin.js

@@ -36,6 +36,11 @@ function checkProjectName(name) {
   }
   return { valid: true };
 }
+function applicationSlug(name) {
+  const slug = name.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (slug.length === 0) return "app";
+  return /^[a-z]/.test(slug) ? slug : `app-${slug}`;
+}
 function checkTargetPath(target) {
   if (target.length === 0) return { valid: false, reason: "path is empty" };
   if (target.trim() !== target) {
@@ -314,6 +319,9 @@ function renderNextSteps(input, color = false) {
       `     ${paint(step, "bold")}`,
       ""
     ]),
+    `  ${paint("Build a module by chat", "dim")}  ${paint(runScript(input.packageManager, "sandbox"), "bold")}`,
+    `  ${paint("Agent guidance", "dim")}          AGENTS.md, CLAUDE.md, .ai/skills`,
+    "",
     `  ${paint("Local URL", "dim")}   ${paint(DEV_URL, "cyan")}`,
     `  ${paint("Demo login", "dim")}  admin@example.com`,
     `  ${paint("Demo account is created only with local demo setup.", "dim")}`,
@@ -347,8 +355,14 @@ import { randomBytes } from "node:crypto";
 var SECRET_KEYS = [
   "FD_AGENT_CREDENTIAL_KEY",
   "FD_AGENT_RUN_GRANT_KEY",
+  "FD_APPROVAL_GRANT_KEY",
+  "FD_AUTOMATIONS_CREDENTIAL_KEY",
+  "FD_NOTIFICATIONS_SECRET_KEY",
   "FD_WORKFLOWS_PAYLOAD_KEY",
   "FD_WORKFLOWS_CURSOR_KEY",
+  "FD_STORAGE_ENCRYPTION_KEY",
+  "FD_CONNECTORS_SECRET_KEY",
+  "FD_AUDIT_ANCHOR_KEY",
   "FD_AUTH_MFA_KEY"
 ];
 function generateSecrets() {
@@ -457,6 +471,20 @@ async function rewritePackageName(directory, name) {
   manifest.name = name;
   await writeFile(path, JSON.stringify(manifest, void 0, "	") + "\n");
 }
+var APPLICATION_SPEC_ID = "application.app-name";
+async function rewriteApplicationSpecId(directory, name) {
+  const path = join2(directory, "specs", "application.yaml");
+  const spec = await readFile(path, "utf8");
+  if (!spec.includes(APPLICATION_SPEC_ID)) {
+    throw new ScaffoldError(
+      `The template spec ${path} no longer carries the "${APPLICATION_SPEC_ID}" placeholder.`
+    );
+  }
+  await writeFile(
+    path,
+    spec.replace(APPLICATION_SPEC_ID, `application.${applicationSlug(name)}`)
+  );
+}
 async function scaffold(request) {
   const directory = resolve2(request.cwd, request.target);
   const name = basename(directory);
@@ -478,6 +506,7 @@ async function scaffold(request) {
   await assertTemplateExists(agentTemplate, "agent guidance");
   const files = await copyTemplate(template, directory) + await copyTemplate(agentTemplate, directory);
   await rewritePackageName(directory, name);
+  await rewriteApplicationSpecId(directory, name);
   await writeFile(
     join2(directory, ".env"),
     renderEnvironmentFile(request.secrets ?? generateSecrets())

package/package.json

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

package/template/default/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.github
+.DS_Store
+# Matched against the whole context-relative path, so a root-anchored .env*
+# would still copy infra/docker/.env into the builder image.
+**/.env
+**/.env.*
+!**/.env.example
+**/node_modules
+**/dist
+**/coverage
+**/.flowdular
+.flowdular/
+*.log

package/template/default/.env.example

@@ -0,0 +1,96 @@
+# Production configuration for this Flowdular app. Copy it, fill in every value
+# and keep the copy out of git. The .env this scaffold generated is the local
+# development file and already carries working keys for embedded PostgreSQL.
+#
+# Generate each 32 byte key with: openssl rand -base64 32
+# For FD_AUTH_MFA_KEY use the URL-safe alphabet: openssl rand -base64 32 | tr '+/' '-_'
+
+NODE_ENV=production
+FD_PORT=3000
+
+# One PostgreSQL database, three roles. The migrator owns the schema, the
+# runtime role holds neither SUPERUSER nor BYPASSRLS so the row-level security
+# every tenant table forces actually binds the app, and the background role
+# serves the cross-tenant scheduler poll. pglite is refused in production.
+FD_DATABASE_ADAPTER=postgresql
+FD_DATABASE_URL=postgresql://coreloom_runtime:REPLACE_ME@postgres:5432/flowdular
+FD_DATABASE_MIGRATOR_URL=postgresql://coreloom_migrator:REPLACE_ME@postgres:5432/flowdular
+FD_DATABASE_BACKGROUND_URL=postgresql://coreloom_background:REPLACE_ME@postgres:5432/flowdular
+FD_DATABASE_TLS=verify-full
+FD_DATABASE_TLS_CA_FILE=/tls/server.crt
+
+# TLS terminates in front of the app. Set this to false only for a plain-HTTP
+# run on a workstation: the session cookie then loses the Secure flag and the
+# __Host- prefix.
+FD_AUTH_SECURE_COOKIE=true
+FD_AUTH_ALLOW_SIGN_UP=false
+
+# Trust x-forwarded-for and x-forwarded-proto. Keep false unless a proxy you
+# control terminates TLS in front of the app and overwrites those headers; on a
+# directly reachable port a client can forge the address the sign-in limiter
+# and the audit trail record. The compose sample publishes the port directly.
+FD_TRUST_PROXY=false
+
+# agents.core, automations.core and workflows.core each refuse to boot in
+# production without their key.
+FD_AGENT_CREDENTIAL_KEY=
+FD_AGENT_RUN_GRANT_KEY=
+FD_APPROVAL_GRANT_KEY=
+FD_APPROVAL_GRANT_KEY_PREVIOUS=
+FD_AUTOMATIONS_CREDENTIAL_KEY=
+FD_NOTIFICATIONS_SECRET_KEY=
+FD_WORKFLOWS_PAYLOAD_KEY=
+FD_WORKFLOWS_CURSOR_KEY=
+
+# Object storage. The local adapter is refused in production, so a deployment
+# points at an S3-compatible bucket (AWS, MinIO, R2). Objects are encrypted with
+# AES-256-GCM under this key before they are written, and the key is required in
+# production: without it stored objects cannot be read back.
+FD_STORAGE_ADAPTER=s3
+FD_STORAGE_S3_BUCKET=
+FD_STORAGE_S3_REGION=
+FD_STORAGE_S3_ENDPOINT=
+FD_STORAGE_S3_ACCESS_KEY_ID=
+FD_STORAGE_S3_SECRET_ACCESS_KEY=
+FD_STORAGE_S3_FORCE_PATH_STYLE=false
+FD_STORAGE_MAX_OBJECT_BYTES=26214400
+FD_STORAGE_ENCRYPTION_KEY=
+FD_CONNECTORS_SECRET_KEY=
+FD_AUDIT_ANCHOR_KEY=
+
+# Retired keys, comma separated, at most eight each. Rotation replaces a key
+# without losing what it sealed: move the old key here, put the new one above,
+# deploy, re-seal the stored rows with the matching "<module> secrets-rotate
+# --apply", then empty the entry. Full procedure in docs/operations.md.
+FD_AGENT_CREDENTIAL_KEY_PREVIOUS=
+FD_AUTOMATIONS_CREDENTIAL_KEY_PREVIOUS=
+FD_NOTIFICATIONS_SECRET_KEY_PREVIOUS=
+FD_WORKFLOWS_PAYLOAD_KEY_PREVIOUS=
+FD_WORKFLOWS_CURSOR_KEY_PREVIOUS=
+FD_STORAGE_ENCRYPTION_KEY_PREVIOUS=
+FD_CONNECTORS_SECRET_KEY_PREVIOUS=
+FD_AUDIT_ANCHOR_KEY_PREVIOUS=
+
+# Base64url 32 byte key encrypting MFA secrets. Without it the app runs and only
+# MFA enrollment is unavailable. It rotates the same way, through
+# "flowdular auth secrets-rotate --apply".
+FD_AUTH_MFA_KEY=
+FD_AUTH_MFA_KEY_PREVIOUS=
+
+# Outgoing mail. With none, workspace invitations are refused and password reset
+# messages are never delivered. Set smtp and both values below to send them; the
+# URL carries the relay password, so treat the filled copy as a secret.
+FD_AUTH_MAIL_TRANSPORT=none
+FD_AUTH_SMTP_URL=
+FD_AUTH_MAIL_FROM=
+
+# Read by infra/docker/compose.yaml only. It builds the three URLs above from
+# these passwords and publishes the container port on FD_PORT.
+FD_POSTGRES_SUPERUSER_PASSWORD=
+FD_DATABASE_MIGRATOR_PASSWORD=
+FD_DATABASE_RUNTIME_PASSWORD=
+FD_DATABASE_BACKGROUND_PASSWORD=
+
+# Prometheus exposition on GET /api/metrics. Leave FD_METRICS unset to keep it off.
+FD_METRICS=false
+FD_METRICS_TOKEN=

package/template/default/README.md

@@ -24,8 +24,11 @@ install. Data lives under `.flowdular/data`.
 | ----------------- | ------------------------------------------------------------ |
 | `platform`        | The deployable composition root and the application shell    |
 | `modules/example` | A tenant-scoped record module: API, migration, screen, tests |
+| `specs`           | The platform spec of this application                        |
+| `infra`           | Dockerfile, compose stack and Kubernetes base                |
 | `flowdular.json`  | Enabled modules and locales, owned by the CLI                |
 | `.env`            | The keys generated for this app. Never commit it             |
+| `.env.example`    | Every key a production deployment reads                      |
 
 ## Work with coding agents
 
@@ -56,11 +59,44 @@ tests.
 `modules.enabled` in `flowdular.json` are written by the CLI. Never edit them by
 hand.
 
+## Build a module by chat
+
+```bash
+pnpm sandbox
+```
+
+The sandbox is a chat-first builder on `http://127.0.0.1:4320`. You describe the
+change, it writes the module in an isolated workspace, runs the same gates this
+repository runs, and previews the result inside the real application shell.
+`--port`, `--workspace`, `--host` and `--mode` override the defaults.
+
+It is a client of a running application and never opens its database. Connect it
+once: in the app open Administration, API tokens, issue a token with
+`sandbox.access.use` plus the read scopes the preview should see, grant the
+account access, then paste the token and the application address into the
+connect screen.
+
+```bash
+pnpm flowdular sandbox grant --email admin@example.com --tenant operations-demo --apply
+```
+
+## Deploy
+
+```bash
+cp .env.example infra/docker/.env   # then fill in every value
+docker compose -f infra/docker/compose.yaml up --build
+```
+
+`.env.example` lists every key the server reads in production. `infra/README.md`
+covers the container image, the PostgreSQL roles and TLS, migrations on rollout,
+and the Kubernetes base.
+
 ## Commands
 
 ```bash
 pnpm dev              # platform with HMR on http://localhost:4310
-pnpm verify           # typecheck, tests, module validation, format
+pnpm sandbox          # chat-first module builder on http://127.0.0.1:4320
+pnpm verify           # typecheck, tests, spec and module validation, format
 pnpm flowdular doctor  # workspace health
 ```
 

package/template/default/flowdular.json

@@ -11,14 +11,25 @@
 		"enabled": [
 			"system.core",
 			"auth.core",
+			"access.core",
+			"reports.core",
+			"metering.core",
 			"agents.core",
-			"automations.core",
+			"approvals.core",
+			"audit.core",
 			"workflows.core",
-			"automations-workflows.integration",
-			"example.core",
+			"automations.core",
+			"connectors.core",
+			"directory.core",
+			"documents.core",
+			"exports.core",
+			"import.core",
+			"notifications.core",
 			"profile.core",
 			"sandbox.core",
-			"users.core"
+			"search.core",
+			"users.core",
+			"example.core"
 		]
 	},
 	"locales": ["en", "pl"],

package/template/default/infra/README.md

@@ -0,0 +1,116 @@
+# Deployment
+
+The production artifact is the server built from `platform`. It runs as a
+non-root user and serves two public probes from
+`platform/src/server/health.ts`: `GET /api/health` answers as soon as the
+process is up and touches nothing else, so it is the liveness probe, and
+`GET /api/ready` calls the database provider, checks that the runtime and
+background roles hold neither `SUPERUSER` nor `BYPASSRLS`, and answers 503 with
+`retry-after: 1` while the database is unavailable.
+
+## Local container
+
+```bash
+cp .env.example infra/docker/.env   # then fill in every value
+docker compose -f infra/docker/compose.yaml up --build
+```
+
+Compose refuses to start while a key or a database password is empty, and the
+owning module would refuse at boot anyway. The app is published on
+`http://localhost:3000`; set `FD_PORT` to change the host port.
+
+The build stage runs `pnpm install --frozen-lockfile`, so commit
+`pnpm-lock.yaml` before building.
+
+Compose also starts PostgreSQL. A one-shot `postgres-tls` service generates a
+self-signed server certificate for `CN=postgres` on first run, Postgres serves
+TLS with it, and the app verifies it through `FD_DATABASE_TLS_CA_FILE` under
+`verify-full`. First cluster initialization creates three roles:
+`coreloom_migrator` owns the schema, `coreloom_runtime` holds neither
+`SUPERUSER` nor `BYPASSRLS`, so the row-level security tenant tables force
+actually binds the application, and `coreloom_background` serves the
+cross-tenant scheduler poll with no default table grant at all.
+
+Public sign-up is disabled. The session cookie is Secure (`__Host-` prefix)
+because the container expects TLS in front of it. For a plain-HTTP run on a
+workstation set `FD_AUTH_SECURE_COOKIE=false` in `infra/docker/.env`; do not do
+this for anything reachable from a network.
+
+The runtime image contains only `platform/dist` and `platform/package.json`. The
+server bundle imports node built-ins exclusively, so no `node_modules` directory
+ships with it.
+
+## Migrations on rollout
+
+Every module owns its migrations and applies them itself, inside a migration
+lease that connects as `FD_DATABASE_MIGRATOR_URL`, the first time its runtime is
+used. A rollout therefore needs no apply step: start the new image and the
+schema catches up under the schema-owning role, while requests keep running as
+the runtime role.
+
+What a rollout should do is fail before the new image serves traffic when an
+already applied migration no longer matches the code being deployed. That is the
+one-shot `migration-check` service in `infra/docker/compose.yaml`: it runs
+`flowdular migration status --json`, reports what is pending, and exits non-zero
+on a checksum mismatch. `app` starts only after it completes successfully.
+
+```bash
+docker compose -f infra/docker/compose.yaml run --rm migration-check
+```
+
+Outside compose, run the same check from a checkout with the deployment's
+`FD_DATABASE_*` values in the environment. On Kubernetes it belongs in a
+pre-upgrade Job or in the pipeline step ahead of `kubectl apply`. After the
+rollout, `flowdular migration verify` should come back clean.
+
+`flowdular migration apply` exists, but it is not part of a rollout. It takes one
+module at a time (`--module <id> --apply`; there is no `--all` flag) and the
+capability is local-only: the runner refuses it unless `FD_ENV` or `NODE_ENV` is
+`development` or `test`. Use it on a workstation against a local database:
+
+```bash
+pnpm flowdular migration status                       # pending work, per module
+pnpm flowdular migration apply --module example.core  # dry run
+pnpm flowdular migration apply --module example.core --apply
+```
+
+Repeat the last two lines for each module `migration status` reports.
+
+Applied migrations are immutable. To change schema, add a numbered migration;
+never edit one the ledger already recorded.
+
+## Published image
+
+Build and publish the image from `infra/docker/Dockerfile`, then set the name in
+`infra/kubernetes/kustomization.yaml` and `deployment.yaml`, which ship with an
+`ghcr.io/OWNER/REPOSITORY` placeholder.
+
+```bash
+kubectl create secret generic flowdular-secrets \
+  --from-literal=agentCredentialKey="$(openssl rand -base64 32)" \
+  --from-literal=agentRunGrantKey="$(openssl rand -base64 32)" \
+  --from-literal=automationsCredentialKey="$(openssl rand -base64 32)" \
+  --from-literal=workflowsPayloadKey="$(openssl rand -base64 32)" \
+  --from-literal=workflowsCursorKey="$(openssl rand -base64 32)"
+kubectl create secret generic flowdular-database \
+  --from-literal=migratorUrl='postgresql://coreloom_migrator:...@postgres:5432/flowdular' \
+  --from-literal=runtimeUrl='postgresql://coreloom_runtime:...@postgres:5432/flowdular' \
+  --from-literal=backgroundUrl='postgresql://coreloom_background:...@postgres:5432/flowdular'
+kubectl apply -k infra/kubernetes
+```
+
+`secrets.example.yaml` and `database-secret.example.yaml` show both Secret shapes
+with placeholders and are deliberately not part of the kustomization. Rotate
+`agentCredentialKey` and `workflowsPayloadKey` through the `*_KEY_PREVIOUS`
+variables rather than by replacing the value: the retired key keeps opening the
+stored rows until `flowdular agents secrets-rotate --apply` and
+`flowdular workflows secrets-rotate --apply` have re-sealed them. Replacing a key
+outright does lose what it sealed, so follow the key rotation section of
+`docs/operations.md`.
+
+The Kubernetes base carries no volume for application data: the deployment is
+stateless and every module writes to PostgreSQL. Scaling writers across nodes
+needs nothing beyond the database they already share.
+
+`.env.example` at the repository root lists every key the server reads,
+including the optional mail transport settings.

package/template/default/infra/docker/Dockerfile

@@ -0,0 +1,37 @@
+# syntax=docker/dockerfile:1.7
+FROM node:24-bookworm-slim AS builder
+
+ENV PNPM_HOME=/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+WORKDIR /workspace
+
+RUN corepack enable && corepack prepare pnpm@11.17.0 --activate
+
+COPY . .
+RUN pnpm install --frozen-lockfile
+RUN pnpm verify && pnpm build
+
+FROM node:24-bookworm-slim AS runtime
+
+ENV NODE_ENV=production
+ENV PORT=3000
+WORKDIR /app
+
+RUN groupadd --system --gid 1001 flowdular \
+	&& useradd --system --uid 1001 --gid flowdular flowdular \
+	&& mkdir -p /data \
+	&& chown flowdular:flowdular /data
+
+# The server bundle is self-contained: platform/dist/server/entry.js imports
+# only node:* built-ins, so no node_modules (and no devDependencies) ship.
+COPY --from=builder --chown=flowdular:flowdular /workspace/platform/dist ./platform/dist
+COPY --from=builder --chown=flowdular:flowdular /workspace/platform/package.json ./platform/package.json
+
+USER flowdular
+EXPOSE 3000
+VOLUME ["/data"]
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+	CMD node -e "fetch('http://127.0.0.1:3000/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
+
+CMD ["node", "platform/dist/server/entry.js"]