@flowdular/sdk 0.2.4 → 0.3.1

package/.ai/references/catalog/tests/data-classes.test.ts

@@ -0,0 +1,157 @@
+import { createDataClassRegistry, type Actor } from '@flowdular/sdk/kernel';
+import { afterAll, afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+	CatalogService,
+	EXPORT_PAGE,
+} from '../src/services/catalog-service.ts';
+import { catalogDataClasses } from '../src/services/data-classes.ts';
+import {
+	closeCatalogTestDatabases,
+	createCatalogTestDatabase,
+	type CatalogTestDatabase,
+} from './support/database.ts';
+
+const ACTOR: Actor = { kind: 'user', id: 'account-1', label: 'Ada' };
+
+let database: CatalogTestDatabase;
+let service: CatalogService;
+
+beforeEach(async () => {
+	database = await createCatalogTestDatabase();
+	service = new CatalogService(database.repository);
+});
+
+afterEach(() => database.dispose());
+afterAll(closeCatalogTestDatabases);
+
+function declarations() {
+	return catalogDataClasses(() => Promise.resolve(service));
+}
+
+function declared(key: string) {
+	const declaration = declarations().find((entry) => entry.key === key);
+	if (!declaration) throw new Error(`No data class ${key}.`);
+	return declaration;
+}
+
+async function exported(key: string, tenantId: string) {
+	const rows: Record<string, unknown>[] = [];
+	const summary = await declared(key).export!({
+		tenantId,
+		sink: { write: async (row) => void rows.push(row) },
+	});
+	return { rows, summary };
+}
+
+function create(tenantId: string, sku: string) {
+	return service.create(
+		tenantId,
+		{
+			sku,
+			name: `Item ${sku}`,
+			kind: 'product',
+			unit: 'pcs',
+			basePriceMinor: 1_000,
+			currency: 'PLN',
+		},
+		ACTOR,
+	);
+}
+
+describe('catalog data classes', () => {
+	it('declares one class per owned table the platform registry accepts', () => {
+		const registry = createDataClassRegistry();
+		registry.declare('catalog.core', declarations());
+		registry.seal();
+
+		const entry = registry
+			.list()
+			.find((module) => module.moduleId === 'catalog.core');
+		expect(entry?.classes.map((declaration) => declaration.key)).toEqual([
+			'items',
+			'history',
+			'idempotency-ledger',
+		]);
+		for (const key of ['items', 'history']) {
+			const declaration = declared(key);
+			expect(declaration.exportable).toBe(true);
+			expect(declaration.export).toBeTypeOf('function');
+			expect(declaration.defaultRetentionDays).toBeNull();
+			expect(declaration.sweep).toBeUndefined();
+			expect(declaration.erase).toBeUndefined();
+		}
+		const ledger = declared('idempotency-ledger');
+		expect(ledger.exportable).toBe(false);
+		expect(ledger.excludedReason).toBeTruthy();
+		expect(ledger.export).toBeUndefined();
+		expect(ledger.sweep).toBeUndefined();
+	});
+
+	it('exports the items and history of one tenant and none of another', async () => {
+		const kept = await create('tenant-a', 'A-1');
+		const archived = await create('tenant-a', 'A-2');
+		await service.archive('tenant-a', archived.id, ACTOR);
+		await create('tenant-b', 'B-1');
+
+		const items = await exported('items', 'tenant-a');
+		expect(items.rows.map((row) => row.sku)).toEqual(['A-1', 'A-2']);
+		expect(items.rows[0]).toEqual({
+			id: kept.id,
+			sku: 'A-1',
+			name: 'Item A-1',
+			kind: 'product',
+			unit: 'pcs',
+			basePriceMinor: 1_000,
+			currency: 'PLN',
+			status: 'active',
+			createdAt: new Date(kept.createdAt).toISOString(),
+		});
+		expect(items.summary).toEqual({
+			rows: 2,
+			from: new Date(kept.createdAt),
+			to: new Date(archived.createdAt),
+		});
+
+		const history = await exported('history', 'tenant-a');
+		expect(
+			history.rows.map((row) => [row.recordId, row.action, row.version]),
+		).toEqual([
+			[kept.id, 'created', 1],
+			[archived.id, 'created', 1],
+			[archived.id, 'archived', 2],
+		]);
+		expect(history.rows[2]).toMatchObject({
+			actor: ACTOR,
+			changes: { status: { from: 'active', to: 'archived' } },
+		});
+		expect(history.summary.rows).toBe(3);
+		expect(history.summary.from).toBeInstanceOf(Date);
+		expect(history.summary.to).toBeInstanceOf(Date);
+	});
+
+	it('walks past one page and stays inside the tenant', async () => {
+		const total = EXPORT_PAGE + 1;
+		for (let index = 0; index < total; index += 1) {
+			await create('tenant-a', `P-${String(index).padStart(3, '0')}`);
+		}
+		await create('tenant-b', 'B-1');
+
+		const items = await exported('items', 'tenant-a');
+		expect(items.summary.rows).toBe(total);
+		expect(new Set(items.rows.map((row) => row.id)).size).toBe(total);
+		expect(items.rows.some((row) => row.sku === 'B-1')).toBe(false);
+
+		const history = await exported('history', 'tenant-a');
+		expect(history.summary.rows).toBe(total);
+		expect(new Set(history.rows.map((row) => row.id)).size).toBe(total);
+	});
+
+	it('reports an empty tenant without writing a row', async () => {
+		await create('tenant-b', 'B-1');
+		for (const key of ['items', 'history']) {
+			const { rows, summary } = await exported(key, 'tenant-empty');
+			expect(rows).toEqual([]);
+			expect(summary).toEqual({ rows: 0, from: null, to: null });
+		}
+	});
+});

package/.ai/references/catalog.provenance.json

@@ -1,9 +1,9 @@
 {
 	"id": "catalog.core",
-	"version": "0.6.1",
+	"version": "0.7.1",
 	"repository": "Flowdular/official-modules",
-	"sourceCommit": "8ed1e780ba7405d0bdf5082882b92d130b72d081",
-	"artifactSha256": "9010086822aa5f4d13176e465022fd2118c5dd0cb157200b31c2940fec1f3513",
+	"sourceCommit": "be391ac460e53e06a812fc9f0ea1260e2daa058f",
+	"artifactSha256": "7c645f660f44bb4c4540d32dd188d643aafb067f4c505a2722a7f2605a7b54b8",
 	"files": {
 		"LICENSE": "155d722071bad9d0d832482e06fd5a47f7034389cb63aabcb39f4282aa3499fc",
 		"migrations/0001_catalog_core.down.sql": "0962a1edf0bde959cd4facccf77bd5b634d6cc25f125a0c79a61770c8871093f",
@@ -15,9 +15,9 @@
 		"migrations/0004_catalog_idempotency_ledger.down.sql": "8ba72d8edc4d25ecf6d041888cf321690c25afdaf3723812ddd7d391d75370aa",
 		"migrations/0004_catalog_idempotency_ledger.up.sql": "41e86ba2051159c6cc9672bfae17c1d02051da975f1c43c566a2b66592673cb0",
 		"migrations/README.md": "2a15fd001713c2552a3c82b186246aa5fec136f43143cc2d9aa15bd491a09d41",
-		"module.json": "66afd7635404b565e8b86f7c5bc485c85c9d568144858bfcff8a4a9429f76081",
-		"package.json": "08b76b72f6fd7a8e3b08113c135899f6010b5fbbea8ca6be0b68b599afe75dad",
-		"spec/module.yaml": "2df3b7c2cbd20f5f5950b469b092f85ef140875bf789a69da04fb6dc68ae0ff8",
+		"module.json": "f2c66d18e3d54ef1ad8dcc3d26d1ee39a2982463dd3bc3fb26b159039933ed86",
+		"package.json": "3e05cf299b5cc5d948e4b3569bd93f2648a30b22f4f14d26bb31548a79529092",
+		"spec/module.yaml": "633a719d765d9779e2bf4ae0a608251767a62cbb4e15305dc13afcb1e52f14c9",
 		"src/acl/permissions.ts": "3375521a5a229736ffac5a948140ec347dc7a7e4fba80e778c0baaf9e0622590",
 		"src/agent/tools.ts": "3204d20886d2b864482adc1ed3303c653aebd207e16c4fce0c67a4979ea8db07",
 		"src/api/endpoints.ts": "34f1036e759353550be2acf67c6fa254afc790942d09489db2e76a082df5c3a3",
@@ -32,16 +32,18 @@
 		"src/domain/types.ts": "4b26be80954d792b09a3a34d29d845b9f6119640be505daba325fec820e06ef6",
 		"src/domain/variables.ts": "131130e57838235b1f3fcb799da44baeae16522bb346d522827e022305c110b5",
 		"src/index.ts": "5b27943018db9a18651d62add7d6f8397d7c492a204381fae74547b99b91990d",
-		"src/platform.ts": "3bdc15a5749cceeca4e86388fad13aebcbc151bb4226852d46ed7845248c4efe",
+		"src/platform.ts": "b5d809b071af812877f3fb09cce3ced4cdaed8f62611c3eb6d5fcaf6cd7333cb",
 		"src/server/index.ts": "90eae107d863418124e5d10c4d1fe8a119bd14da605b36de708c18d8500c4b5e",
 		"src/server/runtime.ts": "5f4389a6adf8265f6737c489baf686f63cc3550662103d28b2da9800dd9f5b63",
-		"src/services/catalog-service.ts": "e5ffa703f6a87e4e2e762f5beb87952be40b3b5847d10b373033a9b01fa4a378",
-		"src/services/database-repository.ts": "b513a9459fb3fc1362e9dcd98c10a104b02dbb748ae23c59c6768c2f0e7a1466",
+		"src/services/catalog-service.ts": "51f1dcd7c0335f7b417fb45ba700c0098e7193246ee91659c27cab8608282693",
+		"src/services/data-classes.ts": "ea09b1a7def59fee43d57ca7dab6fdb4d646b51df2cacb60af96676c43602b33",
+		"src/services/database-repository.ts": "e6ff61ba197899d5618a02ce743c90d4bf09ae64dcfd1bd3a9985b18a2d23e80",
 		"src/services/index.ts": "a08aefe5101814538666f861536287fc382e6c655d62ba9b9ef4bbfbc6ede4af",
 		"src/services/migration.ts": "89c8e333482c80bc819deba0cf4f4e37e94137933af0f6503f4f9ebcb4f5f371",
-		"src/services/repository.ts": "df0f1364cb05031972993c873faf6bcb7fbe4c92d05a04ae980497d9a732dd7f",
+		"src/services/repository.ts": "98d27a40ff02137ec0c6d8799d9a853d40a76eab2564dd500806c4e84f6dc3a3",
 		"src/services/target-idempotency.ts": "7111b56a30b691eaaaa64f5691895ac94b6e0735b0079794835bbbeba5102cb0",
 		"tests/agent-tools.test.ts": "3cdda30b5454d58c6e8791a98e3daf6fe58b9852cd5c437b3614c3f6123baa91",
+		"tests/data-classes.test.ts": "bea08e4d1d7380ccdebc211374b74a6034714b192fd98bfb90a2218067b35658",
 		"tests/endpoints.test.ts": "24d05c7dd52820f90c777a1b814529f5188a9a5a9daeaacda07314f17b7483cc",
 		"tests/idempotency.test.ts": "f2e0896635bcd95271b66181daa2c084411913cdf864ae8b4814f2beeb8c2943",
 		"tests/migrations.test.ts": "47d3d741eddde8677be287730d2f96af556b4b7bf0d8378f9a12a7309af17d78",

package/.ai/skills/README.md

@@ -4,6 +4,7 @@ Flowdular is an agentic foundation framework: the platform is the foundation, an
 
 | Skill                   | One line                                                                                                              |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `spec-interview`        | Interview a request into a v2 spec: capability card defaults, the questions protocol, decisions and out of scope.     |
 | `module-new`            | Create a module from an approved spec: scaffold, what the scaffold lacks, server and client file sets, enable, grant. |
 | `module-update`         | Change an existing module with a fixed touch list per change class and the version bump rules.                        |
 | `spec-approval`         | Record explicit user approval of an exact current module spec without letting an agent approve its own work.          |
@@ -23,9 +24,18 @@ Flowdular is an agentic foundation framework: the platform is the foundation, an
 | `variables`             | Variable-aware fields and templates: the `{{ }}` contract, the scope mask, server-side resolution, adding a source.   |
 | `workflow-development`  | Build, publish, invoke, simulate, and test typed durable workflows and their module integration capability.           |
 | `release-eject-pr`      | Sandbox eject sequence, repository gates, branch and PR conventions, post-merge scope grant.                          |
+| `deploy-operate`        | Container build, production env keys, migrations at rollout, health and readiness, backup and restore, rollback.      |
 
 Choose one skill per task phase: the most specific matching entry above. For ordinary module work use `module-new` or `module-update`. Finish the phase before switching; do not recursively load other SKILL.md files mentioned in a skill. Consult relevant code and supporting references only as needed. `spec-approval` is host-only and requires an explicit user approval instruction.
 
+The normal path for a module is one phase per step:
+
+```text
+request -> spec-interview -> operator approval (spec-approval) -> module-new -> auto-review
+```
+
+An existing module takes the same path with `module-update` in place of `module-new`. `spec-interview` reads `.ai/platform-capabilities.md` and asks for the decisions it cannot infer; implementation reads the approved spec and the touch list instead of scanning the repository, and reports anything the spec lacks as a spec defect.
+
 Where they are read:
 
 - Sandbox: copies are available in `reference/skills/`, but each turn receives exactly one Task skill selected by role, blueprint and request. An explicit `$skill-name` takes precedence only if installed and eligible for that role. Missing matches never load the whole catalog.

package/.ai/skills/agent-tool-design/SKILL.md

@@ -5,7 +5,6 @@ description: >-
   the real harness, permission, idempotency, audit, and test contract.
 roles:
   - agentic-engineer
-  - backend-engineer
   - module-executor
 when: A brief asks to expose a module operation as a tool to business agents or workflows.
 ---
@@ -125,7 +124,7 @@ Dependencies: `package.json` gets `"@flowdular/sdk/harness": "workspace:*"`. You
 - A mutating tool with `idempotency: 'required'` is executable only after the target module implements a durable ledger and the definition declares `idempotencyProtection: 'target-ledger'`. The harness derives a stable key from the durable run id and deterministic tool-call ordinal. The target ledger binds `(tenant, tool id, key)` to a canonical input hash and the first result. A replay returns that result without another mutation; the same key with another tool or input fails closed. Provider tool-call ids are audit metadata only. Never add the declaration before the target migration, repository transaction, and crash-recovery test exist.
 - Each call has a deadline (`tool.timeoutMs`, default 30 s, range 250 to 600000) and the harness caps serialized output at 32 KB (`boundToolOutput`), marking `truncated`. Still page or limit your rows so one call cannot dominate the run window.
 - Events per call land in the run's persisted audit chain: `tool.started`, then `tool.completed` (metadata `tool`, `outputCharacters`, `truncated`) on success, `tool.failed` (reason) on error, or `tool.denied` (reason) when not granted or input-invalid.
-- Runs are enqueued by `POST /api/agent-runs` behind `agents.runs.execute`, claimed by `AgentWorker` with a lease, observed through `GET /api/agent-runs` and the SSE stream. The registered tool ids surface in `GET /api/agents` `tools`, which the Agents form reads to build the allowed-tools grid. Never make a tool block on user input.
+- Runs are enqueued by `POST /api/agent-runs` behind `agents.runs.execute`, claimed by `AgentWorker` with a lease, observed through `GET /api/agent-runs` and the SSE stream. The registered tool ids surface in `GET /api/agents/context` `tools`, which the Agents form reads to build the allowed-tools grid. Never make a tool block on user input.
 
 ## 4. Deliverables for a module
 

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

@@ -26,7 +26,7 @@ Check every route in `src/api/endpoints.ts` against `.ai/references/catalog/src/
 
 ## 2. Scope model
 
-`modules/auth/src/acl/scopes.ts`: `AUTH_SCOPES`, `PLATFORM_SCOPES` (`system.workspace.access` gates the shell in `platform/src/App.tsrx`; `system.settings.read` and `system.settings.manage` guard `GET /api/settings` and `POST /api/settings/update` in `modules/auth/src/server/settings-endpoints.ts`), `BUNDLED_MODULE_SCOPES`, `OWNER_SCOPES` (all of them), `MEMBER_SCOPES` (read scopes plus `agents.runs.execute`). Sign-up creates an owner with `OWNER_SCOPES`; member creation copies `OWNER_SCOPES` or `MEMBER_SCOPES` by role (`modules/auth/src/services/auth-service.ts`). A module's scopes reach existing owners through `pnpm flowdular module enable <id> --apply` (which runs the grant) or `pnpm flowdular auth sync-scopes --module <id> --apply` for a re-grant. Navigation in the `Development` group is owner-only in the client (`packages/client/src/shell/navigation.ts`); the server permission stays authoritative.
+`modules/auth/src/acl/scopes.ts`: `AUTH_SCOPES`, `PLATFORM_SCOPES` (`system.workspace.access` gates the shell in `platform/src/App.tsrx`; `system.settings.read` and `system.settings.manage` guard `GET /api/settings` (`system.settings.list`) and `POST /api/settings/update` (`system.settings.update`) in `modules/system/src/server/endpoints.ts`, from `SYSTEM_PERMISSIONS` in `modules/system/src/acl/permissions.ts`), `BUNDLED_MODULE_SCOPES`, `OWNER_SCOPES` (all of them), `MEMBER_SCOPES` (read scopes plus `agents.runs.execute`). Sign-up creates an owner with `OWNER_SCOPES`; member creation copies `OWNER_SCOPES` or `MEMBER_SCOPES` by role (`modules/auth/src/services/auth-service.ts`). A module's scopes reach existing owners through `pnpm flowdular module enable <id> --apply` (which runs the grant) or `pnpm flowdular auth sync-scopes --module <id> --apply` for a re-grant. Navigation in the `Development` group is owner-only in the client (`packages/client/src/shell/navigation.ts`); the server permission stays authoritative.
 
 Review question: does every new scope appear in the spec `permissions`, in `src/acl/permissions.ts`, on the endpoint, and on the client contribution that exposes it?
 

package/.ai/skills/business-agent-design/SKILL.md

@@ -6,7 +6,6 @@ description: >-
   automation delivered by a module, not for sandbox coding specialists.
 roles:
   - agentic-engineer
-  - backend-engineer
   - module-executor
 when: A module should provide a ready business agent that tenants can configure and run.
 ---

package/.ai/skills/cli-extension/SKILL.md

@@ -91,7 +91,7 @@ export default cliExtension;
 
 ## 4. What the runner does with the descriptor (`packages/cli/src/runner.ts`, `runExtensionCommand`)
 
-- `risk: 'external'`: refused with `APPROVAL_VERIFIER_REQUIRED`. `risk: 'destructive'` without `localOnly`: the same.
+- `risk: 'external'`, or `'destructive'` without `localOnly`: refused with `APPROVAL_VERIFIER_REQUIRED` unless `--grant <token> --tenant <id>` carries a verified approval grant for this capability and invocation digest (`APPROVAL_GRANT_INVALID`, `APPROVAL_GRANT_EXPIRED`, `APPROVAL_GRANT_MISMATCH` otherwise).
 - `localOnly: true`: refused with `LOCAL_ONLY_CAPABILITY` unless `FD_ENV` or `NODE_ENV` is `development` or `test` (unset counts as development).
 - `requiresApprovedSpec: true`: needs `--spec <path>` to a schema-valid spec with `status: approved`, otherwise `APPROVED_SPEC_REQUIRED`, `SPEC_VALIDATION_FAILED` or `SPEC_NOT_APPROVED`.
 - `destructive` with `--apply`: needs `--confirm <confirmation>` (`CONFIRMATION_REQUIRED`).

package/.ai/skills/deploy-operate/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: deploy-operate
+description: >-
+  Build, configure, roll out and operate a Flowdular application: the container
+  image, the production environment keys, migrations at rollout, health and
+  readiness, backup and restore, and rollback.
+roles:
+  - module-executor
+  - reviewer
+when: An application is being deployed, upgraded, rolled back, or operated in production.
+---
+
+# Deploy and operate
+
+This is host work, not sandbox work. A sandbox specialist has no network, no git and no deployment.
+
+## 1. Container build
+
+`infra/docker/Dockerfile` is a two-stage build on `node:24-bookworm-slim`. The builder enables corepack, pins `pnpm@11.17.0`, runs `pnpm install --frozen-lockfile`, then `pnpm verify && pnpm build`, so a failing gate fails the image. The runtime stage copies only `platform/dist` and `platform/package.json`, runs as the non-root user `octane` (uid 1001), exposes 3000, declares the `/data` volume and starts `node platform/dist/server/entry.js`. Its `HEALTHCHECK` polls `/api/health`.
+
+```bash
+docker compose -f infra/docker/compose.yaml up --build   # local stack: postgres-tls, postgres 17 with ssl=on, app
+```
+
+The compose `app` service runs `read_only: true` with a `tmpfs` on `/tmp` and publishes `${FD_PORT:-3000}`. Tagging `v*.*.*` (or running the workflow by hand) builds and pushes the same Dockerfile to `ghcr.io/<repository>` through `.github/workflows/container.yml`. Kubernetes manifests live in `infra/kubernetes` and apply with `kubectl apply -k infra/kubernetes`; the secrets they expect have examples in the same directory. `infra/README.md` carries the local and cluster walkthrough.
+
+## 2. Production environment
+
+`docs/configuration.md` is the reference. The keys a production deployment must set:
+
+| Key                             | Why                                                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `NODE_ENV=production`           | Turns on every production refusal below; `FD_ENV=production` only gates the CLI local-only commands |
+| `FD_DATABASE_ADAPTER`           | Must not be `pglite`; production refuses the embedded adapter                                       |
+| `FD_DATABASE_URL`               | Runtime role, neither `SUPERUSER` nor `BYPASSRLS`                                                   |
+| `FD_DATABASE_MIGRATOR_URL`      | Separate DDL role; required in production                                                           |
+| `FD_DATABASE_TLS=verify-full`   | The only value production accepts, with `FD_DATABASE_TLS_CA[_FILE]`                                 |
+| `FD_AUTH_PUBLIC_ORIGIN`         | Same-origin checks and cookie scope                                                                 |
+| `FD_AUTH_SECURE_COOKIE`         | `Secure` and the `__Host-` cookie prefix; defaults on in production                                 |
+| `FD_AUTH_MFA_KEY`               | Decrypts stored MFA secrets                                                                         |
+| `FD_AGENT_CREDENTIAL_KEY`       | `agents.core` refuses to boot without it                                                            |
+| `FD_AGENT_RUN_GRANT_KEY`        | `agents.core` refuses to boot without it                                                            |
+| `FD_WORKFLOWS_PAYLOAD_KEY`      | `workflows.core` refuses to boot without it                                                         |
+| `FD_WORKFLOWS_CURSOR_KEY`       | `workflows.core` refuses to boot without it                                                         |
+| `FD_AUTOMATIONS_CREDENTIAL_KEY` | `automations.core` refuses to boot without it                                                       |
+| `FD_NOTIFICATIONS_SECRET_KEY`   | `notifications.core` refuses to boot without it                                                     |
+| `FD_CONNECTORS_SECRET_KEY`      | `connectors.core` refuses to boot without it                                                        |
+| `FD_AUDIT_ANCHOR_KEY`           | `audit.core` refuses to seal or verify without it in production                                     |
+
+Every key above is base64 of 32 random bytes where it names a key. `FD_AUTOMATIONS_CREDENTIAL_KEY` is read by `modules/automations/src/services/secret-vault.ts`, which throws `FD_AUTOMATIONS_CREDENTIAL_KEY is required in production.`; in development it generates and persists a local key file instead, so a deployment that never set it fails only at the production boot. Set it whenever `automations.core` is enabled in `flowdular.json`.
+
+Set `FD_TRUST_PROXY` behind a load balancer. `FD_DATABASE_BACKGROUND_URL` gives worker traffic its own pool. Everything else in `docs/configuration.md` has a working default.
+
+## 3. Migrations at rollout
+
+Migrations are module-owned, numbered, immutable once applied, and verified by checksum against the `_coreloom_migrations_v2` ledger. The commands (`packages/cli/src/runner.ts`):
+
+```bash
+pnpm flowdular migration status [--module <id>]      # what the ledger holds
+pnpm flowdular migration verify                      # checksums against the shipped SQL
+pnpm flowdular migration apply --module <id>         # dry run, one module at a time
+pnpm flowdular migration apply --module <id> --apply # writes
+```
+
+`migration apply` carries the `migration.apply.local` capability, which is `localOnly`: the runner refuses it with `LOCAL_ONLY_CAPABILITY` unless `FD_ENV` or `NODE_ENV` is `development` or `test`. It is therefore a local and staging tool as the code stands, not a production rollout step. In production the application applies its own module migrations at boot under a migration lease using `FD_DATABASE_MIGRATOR_URL`, so the rollout order is: apply the new image, let it migrate, then verify. A new module needs `pnpm flowdular module enable <id> --apply` (which grants its scopes) in the workspace before the image is built.
+
+Never edit an applied `.up.sql`, not even whitespace: the checksum changes and the next boot refuses to start.
+
+## 4. Health and readiness
+
+- `GET /api/health` is public and static. It proves the process is up and nothing else. Use it as the liveness probe.
+- `GET /api/ready` is public and calls the database provider: it checks the runtime and background roles are neither superuser nor `BYPASSRLS`, then runs a statement on the migrator pool. It answers 503 with `retry-after: 1` when the database is unavailable. Use it as the readiness probe.
+
+Both are served by `platform/src/server/health.ts`. The shipped Docker and Kubernetes probes all point at `/api/health`; moving the readiness probe to `/api/ready` is the improvement worth making. Before the database is configured the application runs in setup mode and `/api/ready` is not routed at all, so a first-run container answers 404 there rather than 503.
+
+## 5. Backup, restore, and the key trap
+
+`docs/operations.md` is the runbook. Read it before touching production data; this skill does not restate it. The commands:
+
+```bash
+pnpm flowdular database backup --output <dir>                            # dry run
+pnpm flowdular database backup --output <dir> --apply
+pnpm flowdular database restore --input <dir> --apply --confirm restore-database
+pnpm flowdular database restore-production --input <dir> --target <db> --grant <token> --tenant <id> [--platform-url <origin>|--platform-stopped] --apply --confirm restore-database
+```
+
+Production restores run `database.restore.production`: an approval grant bound to the exact flags, `--target` equal to the migrator DSN database, a separate migrator DSN, a key mismatch refused unless the approval included `--allow-key-mismatch`, and a refusal while the health endpoint answers. PITR for the compose stack is `infra/docker/pitr.sh` (see `infra/README.md`); in Kubernetes it is the managed provider's job.
+
+The trap: **the encryption keys live outside the database.** Agent provider credentials, agent run grants, workflow payloads and cursors, automation secrets, MFA secrets, stored objects and connector credentials are all stored as ciphertext, and the keys are environment variables (`FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`, `FD_WORKFLOWS_PAYLOAD_KEY`, `FD_WORKFLOWS_CURSOR_KEY`, `FD_AUTOMATIONS_CREDENTIAL_KEY`, `FD_AUTH_MFA_KEY`, `FD_NOTIFICATIONS_SECRET_KEY`, `FD_STORAGE_ENCRYPTION_KEY`, `FD_CONNECTORS_SECRET_KEY`, `FD_AUDIT_ANCHOR_KEY`). A database backup without the matching keys restores rows nobody can read, and rotating a key without re-encrypting orphans everything encrypted under the old one; every sealing key has a `secrets-rotate` command in the runbook's rotation table, the storage key two (`documents` and `exports`). Back the keys up separately, restore them together with the dump, and record which key version a dump belongs to.
+
+## 6. Rollback
+
+1. Redeploy the previous image tag. Module migrations are additive (`CREATE TABLE IF NOT EXISTS`, `ADD COLUMN`), so an older image runs against a newer schema; it ignores columns it does not know.
+2. Never run a `.down.sql` to roll back a release. They document the reverse for review, and applying one against live data is data loss.
+3. To take one module out of service without a redeploy: `pnpm flowdular module disable <id> --apply` (it is a dry run without `--apply`), then rebuild the composition and redeploy. Its tables stay.
+4. If the rollback is because of a key change, restore the previous key first; the image alone will not fix unreadable ciphertext.
+
+- For data loss between two dumps use PITR (`pitr.sh restore --target-time`), never a `.down.sql`.
+
+## 7. Production checklist
+
+- `pnpm verify` and `pnpm build` pass on the commit being shipped (the image build runs both).
+- `NODE_ENV=production`, a PostgreSQL adapter, `FD_DATABASE_TLS=verify-full` with its CA.
+- Runtime role has neither `SUPERUSER` nor `BYPASSRLS`; the migrator role is separate.
+- Every encryption key set, stored outside the database, and backed up with a recorded version.
+- `FD_AUTOMATIONS_CREDENTIAL_KEY` set whenever `automations.core` is enabled in `flowdular.json`, `FD_NOTIFICATIONS_SECRET_KEY` whenever `notifications.core` is, `FD_CONNECTORS_SECRET_KEY` whenever `connectors.core` is, and `FD_AUDIT_ANCHOR_KEY` whenever `audit.core` is.
+- `FD_AUTH_PUBLIC_ORIGIN` matches the public URL; `FD_AUTH_SECURE_COOKIE` on; `FD_TRUST_PROXY` set behind a proxy.
+- Sign-up closed (`FD_AUTH_ALLOW_SIGN_UP`) unless the deployment is public; the first owner created with `flowdular auth workspace-create` (see `docs/cli.md`).
+- Liveness on `/api/health`, readiness on `/api/ready`.
+- `pnpm flowdular migration verify` clean after rollout, and `pnpm flowdular doctor --json` reports `status: healthy`.
+- A restore has been rehearsed once, keys included, and a PITR restore once from the newest base backup.
+
+## Pitfalls
+
+- `setup quick` and `auth greenfield` are local resets that wipe auth data. They refuse outside `development` and `test`; never point them at a deployment.
+- `pglite` is the local and test adapter. A production boot with it is refused, not degraded.
+- A module added to the workspace but not enabled is absent from the built image: `module enable` writes the generated composition, and `pnpm build` bakes it in.
+- Scopes for a new permission reach existing owners only after `flowdular auth sync-scopes --module <id> --apply`; an endpoint can be live while every user gets 403.
+- Rotating `FD_AUTH_MFA_KEY` locks out every enrolled user, not just new enrolments.

package/.ai/skills/module-new/SKILL.md

@@ -6,9 +6,6 @@ description: >-
 roles:
   - business-manager
   - backend-engineer
-  - frontend-engineer
-  - ux-designer
-  - agentic-engineer
   - module-executor
 when: A brief asks for a module that does not exist yet, or a sandbox session is labelled new-module.
 ---
@@ -19,6 +16,35 @@ The reference module is `.ai/references/catalog` (in a sandbox session: `referen
 
 Two ways to land the same module: the sandbox (a brief, specialist turns, gates after every turn, preview, eject) or the direct path (this skill in your own coding tool, the gates by hand, `pnpm verify`, a pull request). The sections below mark the differences.
 
+## Spec is the contract
+
+With an approved `schemaVersion: 2` spec, the specification is the requirement document and you do not go looking for one. Read the spec, the files on this skill's touch list, and `.ai/references/catalog` for shape. Do not scan `modules/` or `packages/`; `.ai/platform-capabilities.md` answers what the platform provides, and the reference module answers what the code looks like.
+
+Anything the spec does not say is a spec defect, not a decision you make. A missing field, an unstated conflict behaviour, an undefined state transition, a screen without columns: report it back. In the sandbox that is `HANDOFF: business-manager - <what is missing>`; on a host it is a question to the user. Never fill the gap with a plausible guess, and never implement anything listed in `outOfScope[]`.
+
+Every `acceptanceScenarios[]` entry maps to at least one test in `tests/`. A scenario with no test is unfinished work, and the scenario id belongs in the test name so the mapping is readable.
+
+Each spec element maps to files:
+
+| Spec element                  | Files it produces                                                                                                                                       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts` |
+| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                |
+| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                     |
+| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                      |
+| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                       |
+| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                               |
+| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                          |
+| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                    |
+| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                             |
+| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`                                                                         |
+| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                |
+| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                          |
+| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                         |
+| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                    |
+
+A v1 spec stays valid and carries none of these arrays. Then the requirements are `invariants`, `permissions` and `acceptanceScenarios`, and everything the spec leaves open is still a question rather than a guess.
+
 ## 1. Preconditions
 
 - `pnpm flowdular doctor --json` reports `status: healthy` (repository root only; the sandbox runs gates for you).

package/.ai/skills/module-update/SKILL.md

@@ -6,15 +6,21 @@ description: >-
 roles:
   - backend-engineer
   - frontend-engineer
-  - ux-designer
   - business-manager
-  - agentic-engineer
   - module-executor
 when: A brief names an existing module, or a sandbox session is labelled edit-module.
 ---
 
 # Update an existing module
 
+## Spec is the contract
+
+With an approved `schemaVersion: 2` spec delta, the specification is the requirement document. Read the spec, the module itself, the touch list for the change class below, and `.ai/references/catalog` for shape. Do not scan `modules/` or `packages/`: `.ai/platform-capabilities.md` answers what the platform provides.
+
+Anything the delta does not say is a spec defect, not your decision. Report it back (`HANDOFF: business-manager - <what is missing>` in the sandbox, a question to the user on a host) instead of guessing, and never implement an item the spec parks in `outOfScope[]`. Every new or changed `acceptanceScenarios[]` entry maps to at least one test, with the scenario id in the test name.
+
+The spec-element to file mapping is the table in `module-new`; the change classes below are the same mapping arranged by what you are changing.
+
 ## 1. Read first
 
 Read the whole module before changing it: `spec/module.yaml`, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
@@ -71,7 +77,7 @@ Business agent: use `business-agent-design` as a separate phase; add the approve
 
 ## 3. Versions and spec
 
-Bump `spec/module.yaml` `specVersion`, `module.json` `version` and `package.json` `version` together (patch for a fix, minor for a new endpoint, screen or column). Add an acceptance scenario for every new behaviour and an invariant for every new rule; the scenario id matches `^[A-Z][A-Z0-9-]+$`. In the sandbox the business manager leaves the changed spec in `draft` or `in-review`; only the operator approval route records the approved hash and permits implementation.
+Bump `spec/module.yaml` `specVersion`, `module.json` `version` and `package.json` `version` together with `pnpm flowdular module version bump <id> <patch|minor|major> --apply` (patch for a fix, minor for a new endpoint, screen or column); it also retargets every dependent `^` range that stops matching. A new `context.capabilities.register` id goes under `provides` in `module.json`; a new `context.capabilities.get` id goes under `requires`. Add an acceptance scenario for every new behaviour and an invariant for every new rule; the scenario id matches `^[A-Z][A-Z0-9-]+$`. In the sandbox the business manager leaves the changed spec in `draft` or `in-review`; only the operator approval route records the approved hash and permits implementation.
 
 ## 4. Gates
 

package/.ai/skills/perf-audit/SKILL.md

@@ -5,7 +5,6 @@ description: >-
   change only what a measurement justifies.
 roles:
   - backend-engineer
-  - frontend-engineer
   - module-executor
   - reviewer
 when: A screen or endpoint is slow, a list grows, or a review asks whether the change scales.

package/.ai/skills/release-eject-pr/SKILL.md

@@ -7,7 +7,6 @@ description: >-
 roles:
   - module-executor
   - reviewer
-  - backend-engineer
 when: A change is ready to leave a sandbox session or a working tree and reach the platform.
 ---