create-flowdular 0.2.5 → 0.3.0

package/agent-template/.ai/references/catalog/src/platform.ts

@@ -4,6 +4,7 @@ import type {
 } from '@flowdular/sdk/modules/auth/server';
 import { platformVariableRegistry } from '@flowdular/sdk/kernel';
 import { registerCatalogVariableSource } from './domain/variables.ts';
+import { catalogDataClasses } from './services/data-classes.ts';
 import {
 	catalogAgentTools,
 	createCatalogRoutes,
@@ -28,6 +29,7 @@ export function createServerComposition(
 		platformVariableRegistry(context.capabilities),
 		tools,
 	);
+	context.dataClasses.declare(catalogDataClasses(() => runtime.service()));
 	return {
 		routes: createCatalogRoutes(context.auth, runtime),
 		dispose: () => runtime.dispose(),

package/agent-template/.ai/references/catalog/src/services/catalog-service.ts

@@ -2,6 +2,8 @@ import { randomUUID } from 'node:crypto';
 import {
 	normalizeActor,
 	type Actor,
+	type DataClassExportSink,
+	type DataClassExportSummary,
 	type HistoryPage,
 	type HistoryRequest,
 } from '@flowdular/sdk/kernel';
@@ -11,7 +13,11 @@ import type {
 	CreateCatalogItemInput,
 	UpdateCatalogItemInput,
 } from '../domain/types.ts';
-import { DuplicateSkuError, type CatalogRepository } from './repository.ts';
+import {
+	DuplicateSkuError,
+	type CatalogRepository,
+	type ExportCursor,
+} from './repository.ts';
 import {
 	canonicalDigest,
 	TargetIdempotencyConflictError,
@@ -22,6 +28,9 @@ export interface CatalogIdempotencyRequest {
 	readonly operationId: string;
 }
 
+/** Rows one export read carries; the whole tenant is walked page by page. */
+export const EXPORT_PAGE = 200;
+
 export class CatalogServiceError extends Error {
 	constructor(
 		readonly code: string,
@@ -271,6 +280,60 @@ export class CatalogService {
 		});
 	}
 
+	async exportItemsTo(
+		tenantId: string,
+		sink: DataClassExportSink,
+	): Promise<DataClassExportSummary> {
+		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		return await exportPaged(
+			(cursor) =>
+				this.repository.listItemsForExport(
+					trustedTenantId,
+					cursor,
+					EXPORT_PAGE,
+				),
+			(item) => item.createdAt,
+			(item) => ({
+				id: item.id,
+				sku: item.sku,
+				name: item.name,
+				kind: item.kind,
+				unit: item.unit,
+				basePriceMinor: item.basePriceMinor,
+				currency: item.currency,
+				status: item.status,
+				createdAt: new Date(item.createdAt).toISOString(),
+			}),
+			sink,
+		);
+	}
+
+	async exportHistoryTo(
+		tenantId: string,
+		sink: DataClassExportSink,
+	): Promise<DataClassExportSummary> {
+		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		return await exportPaged(
+			(cursor) =>
+				this.repository.listHistoryForExport(
+					trustedTenantId,
+					cursor,
+					EXPORT_PAGE,
+				),
+			(entry) => entry.occurredAt,
+			(entry) => ({
+				id: entry.id,
+				recordId: entry.recordId,
+				version: entry.version,
+				action: entry.action,
+				actor: entry.actor,
+				changes: entry.changes,
+				occurredAt: new Date(entry.occurredAt).toISOString(),
+			}),
+			sink,
+		);
+	}
+
 	private async item(tenantId: string, id: string): Promise<CatalogItem> {
 		const item = await this.repository.find(
 			tenantId,
@@ -304,3 +367,28 @@ export class CatalogService {
 		return item;
 	}
 }
+
+async function exportPaged<T extends { readonly id: string }>(
+	page: (after: ExportCursor | null) => Promise<readonly T[]>,
+	at: (record: T) => number,
+	row: (record: T) => Record<string, unknown>,
+	sink: DataClassExportSink,
+): Promise<DataClassExportSummary> {
+	let cursor: ExportCursor | null = null;
+	let rows = 0;
+	let from: Date | null = null;
+	let to: Date | null = null;
+	for (;;) {
+		const records = await page(cursor);
+		for (const record of records) {
+			await sink.write(row(record));
+			rows += 1;
+			from ??= new Date(at(record));
+			to = new Date(at(record));
+		}
+		if (records.length < EXPORT_PAGE) break;
+		const last = records[records.length - 1]!;
+		cursor = { at: at(last), id: last.id };
+	}
+	return { rows, from, to };
+}

package/agent-template/.ai/references/catalog/src/services/data-classes.ts

@@ -0,0 +1,47 @@
+import type { DataClassDeclaration } from '@flowdular/sdk/kernel';
+import type { CatalogService } from './catalog-service.ts';
+
+/** The class ids are `catalog.core.<key>`. */
+export const CATALOG_DATA_CLASS_KEYS = {
+	items: 'items',
+	history: 'history',
+	idempotencyLedger: 'idempotency-ledger',
+} as const;
+
+/**
+ * What this module holds, for the workspace's data class catalogue. Items and
+ * their history are master data: no retention period, no sweep, no erasure. A
+ * row leaves only when a person deletes it. The idempotency ledger is the
+ * replay guard of the mutating tools and workflow actions; it stays out of the
+ * export because the item it points at is already in the items class.
+ */
+export function catalogDataClasses(
+	service: () => Promise<CatalogService>,
+): readonly DataClassDeclaration[] {
+	return [
+		{
+			key: CATALOG_DATA_CLASS_KEYS.items,
+			label: 'Catalog items',
+			defaultRetentionDays: null,
+			exportable: true,
+			export: async ({ tenantId, sink }) =>
+				(await service()).exportItemsTo(tenantId, sink),
+		},
+		{
+			key: CATALOG_DATA_CLASS_KEYS.history,
+			label: 'Catalog item history',
+			defaultRetentionDays: null,
+			exportable: true,
+			export: async ({ tenantId, sink }) =>
+				(await service()).exportHistoryTo(tenantId, sink),
+		},
+		{
+			key: CATALOG_DATA_CLASS_KEYS.idempotencyLedger,
+			label: 'Catalog idempotency ledger',
+			defaultRetentionDays: null,
+			exportable: false,
+			excludedReason:
+				'Operational replay ledger of mutating tools and workflow actions; the catalog items it points at are exported by catalog.core.items.',
+		},
+	];
+}

package/agent-template/.ai/references/catalog/src/services/database-repository.ts

@@ -11,13 +11,20 @@ import {
 import {
 	diffFields,
 	type Actor,
+	type HistoryEntry,
 	type HistoryPage,
 	type HistoryQuery,
+	type RecordChanges,
 	type TrackedFields,
+	type UserActor,
 } from '@flowdular/sdk/kernel';
 import type { CatalogItem } from '../domain/types.ts';
 import { databaseMigrations } from './migration.ts';
-import { DuplicateSkuError, type CatalogRepository } from './repository.ts';
+import {
+	DuplicateSkuError,
+	type CatalogRepository,
+	type ExportCursor,
+} from './repository.ts';
 import {
 	canonicalDigest,
 	TargetIdempotencyCorruptionError,
@@ -36,6 +43,18 @@ const COLUMNS = `id, tenant_id, sku, name, kind, unit, base_price_minor,
 const LIST = `SELECT ${COLUMNS} FROM catalog_items
 			 WHERE tenant_id = $1 ORDER BY sku_normalized, id`;
 
+const LIST_FOR_EXPORT = `SELECT ${COLUMNS} FROM catalog_items
+			 WHERE tenant_id = $1
+			   AND ($2::bigint IS NULL OR (created_at, id) > ($2::bigint, $3::text))
+			 ORDER BY created_at, id LIMIT $4`;
+
+const LIST_HISTORY_FOR_EXPORT = `SELECT id, record_id, version, action, actor_kind,
+			  actor_id, actor_label, run_id, configured_by_json, changes_json, occurred_at
+			 FROM ${HISTORY_TABLE}
+			 WHERE tenant_id = $1
+			   AND ($2::bigint IS NULL OR (occurred_at, id) > ($2::bigint, $3::text))
+			 ORDER BY occurred_at, id LIMIT $4`;
+
 const FIND = `SELECT ${COLUMNS} FROM catalog_items WHERE tenant_id = $1 AND id = $2`;
 
 const INSERT = `INSERT INTO catalog_items
@@ -74,6 +93,20 @@ interface CatalogItemRow {
 	created_at: number | bigint | string;
 }
 
+interface HistoryRow {
+	id: string;
+	record_id: string;
+	version: number | bigint | string;
+	action: string;
+	actor_kind: Actor['kind'];
+	actor_id: string;
+	actor_label: string;
+	run_id: string | null;
+	configured_by_json: string | null;
+	changes_json: string;
+	occurred_at: number | bigint | string;
+}
+
 interface IdempotencyRow {
 	operation_id: string;
 	input_digest: string;
@@ -119,6 +152,36 @@ function fromRow(row: CatalogItemRow): CatalogItem {
 	};
 }
 
+function actorFromRow(row: HistoryRow): Actor {
+	const identity = { id: row.actor_id, label: row.actor_label };
+	if (row.actor_kind === 'user') return { kind: 'user', ...identity };
+	if (row.actor_kind === 'agent' && row.run_id !== null) {
+		return { kind: 'agent', ...identity, runId: row.run_id };
+	}
+	if (row.actor_kind === 'service' && row.configured_by_json !== null) {
+		return {
+			kind: 'service',
+			...identity,
+			configuredBy: JSON.parse(row.configured_by_json) as UserActor,
+		};
+	}
+	throw new Error(
+		`The catalog history table returned an invalid actor for "${row.id}".`,
+	);
+}
+
+function historyFromRow(row: HistoryRow): HistoryEntry {
+	return {
+		id: row.id,
+		recordId: row.record_id,
+		version: integer(row.version, 'version'),
+		action: row.action,
+		actor: actorFromRow(row),
+		changes: JSON.parse(row.changes_json) as RecordChanges,
+		occurredAt: integer(row.occurred_at, 'timestamp'),
+	};
+}
+
 /* The fields a history version reports on. Identity, tenancy and creation time
    cannot change and are never part of a diff. */
 function tracked(item: CatalogItem): TrackedFields {
@@ -159,6 +222,40 @@ export class DatabaseCatalogRepository implements CatalogRepository {
 		return result.rows.map(fromRow);
 	}
 
+	async listItemsForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly CatalogItem[]> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<CatalogItemRow>({
+					text: LIST_FOR_EXPORT,
+					parameters: [tenantId, after?.at ?? null, after?.id ?? null, limit],
+				}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+
+	async listHistoryForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly HistoryEntry[]> {
+		await this.readyPromise;
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<HistoryRow>({
+					text: LIST_HISTORY_FOR_EXPORT,
+					parameters: [tenantId, after?.at ?? null, after?.id ?? null, limit],
+				}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(historyFromRow);
+	}
+
 	async find(tenantId: string, id: string): Promise<CatalogItem | null> {
 		await this.readyPromise;
 		const result = await this.database.transaction(

package/agent-template/.ai/references/catalog/src/services/repository.ts

@@ -1,4 +1,9 @@
-import type { Actor, HistoryPage, HistoryQuery } from '@flowdular/sdk/kernel';
+import type {
+	Actor,
+	HistoryEntry,
+	HistoryPage,
+	HistoryQuery,
+} from '@flowdular/sdk/kernel';
 import type { CatalogItem } from '../domain/types.ts';
 import type { TargetIdempotencyRequest } from './target-idempotency.ts';
 
@@ -9,9 +14,25 @@ export class DuplicateSkuError extends Error {
 	}
 }
 
+/** Keyset position of an export page: the record time and id of its last row. */
+export interface ExportCursor {
+	readonly at: number;
+	readonly id: string;
+}
+
 /** The database-agnostic business port. No driver type crosses it. */
 export interface CatalogRepository {
 	list(tenantId: string): Promise<readonly CatalogItem[]>;
+	listItemsForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly CatalogItem[]>;
+	listHistoryForExport(
+		tenantId: string,
+		after: ExportCursor | null,
+		limit: number,
+	): Promise<readonly HistoryEntry[]>;
 	find(tenantId: string, id: string): Promise<CatalogItem | null>;
 	create(
 		item: CatalogItem,

package/agent-template/.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/agent-template/.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/agent-template/.ai/rules/flowdular.md

@@ -63,6 +63,10 @@ Do not load the whole skill catalog into the task context.
 12. Keep handoffs short and factual. No AI attribution footers or em/en dashes.
     Sandbox final line: `HANDOFF: <allowed-role> - <why>` or
     `HANDOFF: none - <why>`, never your own role.
+13. Flow: request, `spec-interview`, approval, `module-new`/`module-update`,
+    `auto-review`. Implement from the approved spec and its touch list; do not
+    scan `modules/` or `packages/`. First lookup is `.ai/platform-capabilities.md`.
+    What the spec lacks is a spec defect to report, never a guess.
 
 Detailed recipes: `docs/agent-contract.md` (lookup only).
 Reference module: `.ai/references/catalog`; visual contract: `docs/design-system.md`.

package/agent-template/.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/agent-template/.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/agent-template/.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/agent-template/.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.
 ---