@flowdular/sdk 0.2.3 → 0.3.0

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.0",
 	"repository": "Flowdular/official-modules",
-	"sourceCommit": "8ed1e780ba7405d0bdf5082882b92d130b72d081",
-	"artifactSha256": "9010086822aa5f4d13176e465022fd2118c5dd0cb157200b31c2940fec1f3513",
+	"sourceCommit": "b8281b38498b1e3164e6619ec9e8fe922ad7dc10",
+	"artifactSha256": "6c98785c10fac14cb1a913c6462cb42e18fe824a7d0dd7620746605fd351441d",
 	"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": "1b512c9b97bdec2155103f521a6545e558e50491f90c74a93d33cc74511d2125",
+		"package.json": "67d50dc95723d21bb44bbab54ae14fe89641c52b9f62ba065908f67ebcf0ed7a",
+		"spec/module.yaml": "ec931c78f351c7fc53f43fdd5ec9cd1a46db485f642648329bf1612883a3c958",
 		"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/deploy-operate/SKILL.md

@@ -0,0 +1,114 @@
+---
+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
+```
+
+The trap: **the encryption keys live outside the database.** Agent provider credentials, agent run grants, workflow payloads and cursors, automation secrets and MFA secrets 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. 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.
+
+## 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.
+
+## 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.
 ---
 

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

@@ -0,0 +1,120 @@
+---
+name: spec-interview
+description: >-
+  Turn a business request into a schema-valid v2 module specification by
+  proposing a platform default for every decision and asking only what cannot be
+  inferred, so implementation never has to guess or scan the repository.
+roles:
+  - business-manager
+  - spec-author
+  - module-executor
+when: A request describes a module or a change and no approved specification covers it.
+---
+
+# Interview a request into a specification
+
+The specification is the contract implementation reads instead of the repository. Everything an engineer would otherwise have to guess belongs in it: entities, fields, screens, actions, settings, tools, and what was deliberately left out. A missing decision costs a round trip later, so surface it now.
+
+Work closed-world. `.ai/platform-capabilities.md` is the complete list of what the platform can deliver. Anything outside it is `outOfScope` with the business decision that replaces it, never a promise.
+
+## 1. Read exactly this
+
+1. `.ai/platform-capabilities.md`, the capability card (in a session: `reference/platform-capabilities.md`).
+2. `packages/contracts/schemas/module-spec.schema.json`, the shape and the enums (in a session: `reference/packages/contracts/schemas/module-spec.schema.json`).
+3. `.ai/references/catalog/spec/module.yaml`, a written example (in a session: `reference/example-module/spec/module.yaml`).
+
+For an edit, also read the module's current `spec/module.yaml` and write the smallest delta. Do not open `modules/` or `packages/` for anything else; the card carries what you need, and a fact it lacks is a question, not a search.
+
+## 2. Decision checklist
+
+One pass, in this order. For each row, write the default from the card into the spec and record it as a `decisions[]` entry with `decidedBy: default`. Ask only where the answer is a business fact that no default can supply.
+
+| Decision               | Default to propose                                                                          | Lands in                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Actors                 | Owner manages, member reads                                                                 | `permissions`, `invariants`              |
+| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name     | `entities[]`                             |
+| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                           | `entities[].fields[].unique`             |
+| States and transitions | `active` and `archived`, every transition behind the manage permission                      | `entities[].states`                      |
+| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope   | `permissions`, `screens[]`, `invariants` |
+| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing              | `acceptanceScenarios`                    |
+| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                | `invariants`, `acceptanceScenarios`      |
+| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency | `dependencies`, `dataOwnership`          |
+| Screens                | One `list` screen with the entity's identifying columns                                     | `screens[]`                              |
+| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it              | `widgets[]`                              |
+| Settings               | None. A number the business may change later is `scope: tenant` with a stated default       | `settings[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`            | `agentTools[]`                           |
+| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope  | `outOfScope[]`                           |
+| Out of scope           | Every item from the card's gap list the request touched, each with its business decision    | `outOfScope[]`, `decisions[]`            |
+
+A default you propose is still a decision: it goes into `decisions[]` so the operator can see and overturn it, and so the next agent never re-derives it.
+
+## 3. Ask only what you cannot infer
+
+Ask when the answer is a business fact: who may see a price, whether a code is unique across the company or per branch, what happens to an order whose customer is deleted. Never ask what the card already answers, and never ask two questions where one choice settles both. Keep it under about six questions per turn.
+
+In the sandbox, end the reply with exactly one fenced block tagged `questions`, nothing after it:
+
+````text
+```questions
+{
+	"questions": [
+		{
+			"id": "Q-1",
+			"question": "Is the item code unique for the whole workspace or per warehouse?",
+			"options": ["Unique per workspace", "Unique per warehouse"],
+			"recommended": "Unique per workspace",
+			"allowFreeText": true
+		}
+	]
+}
+```
+````
+
+The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
+
+When the answers come back, copy each one into `decisions[]` with `decidedBy: user` and the answer text, and update whatever the answer changed.
+
+## 4. Write the specification
+
+`modules/<dir>/spec/module.yaml`, `schemaVersion: 2`, `status: draft`. Keep the v1 keys (`id`, `specVersion`, `name`, `description`, `profile`, `capabilities`, `dependencies`, `tenancy`, `locales`, `invariants`, `permissions`, `dataOwnership`, `acceptanceScenarios`) and add the v2 arrays:
+
+- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
+- `screens[]`: `{ id, kind: list|record|form|dashboard, entity?, title?, columns?, filters?, navigationGroup? }`. `navigationGroup` is one of the six values on the card.
+- `actions[]`: `{ id, entity?, permission, kind: create|update|delete|custom, risk, idempotent, description }`. `risk: external` is refused by the platform, so an action may not declare it.
+- `widgets[]`: `{ id, slot, entity?, description }`; `slot` is one of the four workspace slots.
+- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, default?, values?, description }`.
+- `agentTools[]`: `{ id, permission, description, risk: read|workspace-write }`.
+- `outOfScope[]`: plain sentences, each naming the gap and the decision taken instead.
+- `decisions[]`: `{ id, question, answer, decidedBy: user|default }`; ids match `^[A-Z][A-Z0-9-]+$`, for example `D-UNIQUE-SKU`.
+
+Put the primary entity's read and manage permissions first: the scaffold builds that entity and later permissions become constants only. Every `acceptanceScenarios[]` entry stays observable (given, when, then) and covers success, denial and the cross-tenant case, because each one becomes at least one test. The schema rejects unknown keys.
+
+## 5. Validate
+
+```bash
+pnpm flowdular spec validate --all --json
+```
+
+In the sandbox this is the `spec-schema` gate and runs for you. Fix every issue before ending the turn; a spec that does not validate cannot be approved.
+
+## 6. Close the turn
+
+End with the decision list: each decision, the answer, and whether it came from the user or from a platform default. Then state plainly that implementation cannot start until the operator approves this exact specification, and that any later edit invalidates that approval. In the sandbox the operator approves the exact hash; on a host, approval is recorded only through `spec-approval` after an explicit user instruction.
+
+Sandbox handoff: `HANDOFF: none - <the open questions>` while questions are outstanding, otherwise the next specialist with the reason.
+
+## Refusals
+
+- Never write `status: approved`, and never claim a spec is approved. Approval is the operator's act.
+- Never write TypeScript, `module.json`, `package.json` or any implementation file. This skill produces `spec/module.yaml` and, where the role allows, `translations/**`.
+- Never invent a business fact. An unanswered question is `decisions[]` left open plus a question, not a plausible answer.
+- Never promise a capability the card lists as missing. It goes to `outOfScope[]`.
+
+## Pitfalls
+
+- A field nobody asked for is a cost forever. If the request did not name it, leave it out and record the omission.
+- `unique: tenant` without a stated conflict behaviour produces an undefined error path; pair it with an acceptance scenario.
+- `states` without `transitions` lets any state reach any other. Name the legal moves and their permission.
+- A screen with no `columns` gives the engineer nothing to build; list the identifying fields in display order.
+- An `enum` field with values that are really a lookup table wants its own entity instead.
+- Bumping `specVersion` is part of an edit, not an afterthought; the delivery gate compares it.

package/.ai/skills/test-hardening/SKILL.md

@@ -9,6 +9,7 @@ roles:
   - frontend-engineer
   - reviewer
   - module-executor
+  - agentic-engineer
 when: A module has few or tautological tests, a bug escaped the suite, or a reviewer asks whether the tests guard the change.
 ---