create-flowdular 0.2.3 → 0.2.5

package/agent-template/.ai/references/catalog/tests/support/database.ts

@@ -0,0 +1,76 @@
+import type { DatabaseHandle, DatabaseProvider } from '@flowdular/sdk/database';
+import { createTestDatabaseProvider } from '@flowdular/sdk/database-testing';
+import {
+	DatabaseCatalogRepository,
+	migrateCatalogDatabase,
+} from '../../src/services/database-repository.ts';
+
+const TENANT_TABLES = [
+	'catalog_items',
+	'catalog_items_history',
+	'catalog_items_history_v2',
+	'catalog_idempotency_ledger',
+];
+
+export interface CatalogTestDatabase {
+	readonly provider: DatabaseProvider;
+	readonly runtime: DatabaseHandle;
+	readonly repository: DatabaseCatalogRepository;
+	dispose(): Promise<void>;
+}
+
+/* Booting an embedded PostgreSQL costs about two seconds, so a test file shares
+   one migrated cluster and every fixture starts from truncated tables instead.
+   Call closeCatalogTestDatabases() from the file's afterAll. */
+let shared: Promise<DatabaseProvider> | undefined;
+
+/** The file's migrated provider, with every catalog table emptied. */
+export async function catalogTestProvider(): Promise<DatabaseProvider> {
+	shared ??= (async () => {
+		const provider = createTestDatabaseProvider();
+		const lease = await provider.acquire({
+			namespace: 'catalog.core',
+			purpose: 'migration',
+		});
+		try {
+			await migrateCatalogDatabase(lease.database);
+		} finally {
+			await lease.release();
+		}
+		return provider;
+	})();
+	const provider = await shared;
+	const migration = await provider.acquire({
+		namespace: 'catalog.core',
+		purpose: 'migration',
+	});
+	try {
+		await migration.database.execute({
+			text: `TRUNCATE ${TENANT_TABLES.join(', ')} RESTART IDENTITY CASCADE`,
+		});
+	} finally {
+		await migration.release();
+	}
+	return provider;
+}
+
+/** An empty catalog database with a tenant-scoped runtime handle. */
+export async function createCatalogTestDatabase(): Promise<CatalogTestDatabase> {
+	const provider = await catalogTestProvider();
+	const lease = await provider.acquire({
+		namespace: 'catalog.core',
+		purpose: 'test',
+	});
+	return {
+		provider,
+		runtime: lease.database,
+		repository: new DatabaseCatalogRepository(lease.database),
+		dispose: () => lease.release(),
+	};
+}
+
+export async function closeCatalogTestDatabases(): Promise<void> {
+	const provider = shared;
+	shared = undefined;
+	if (provider) await (await provider).dispose();
+}

package/agent-template/.ai/references/catalog/translations/en.json

@@ -0,0 +1,101 @@
+{
+	"module.name": "Product Catalog Core",
+	"nav.description": "Products and services",
+	"nav.label": "Catalog",
+	"drawer.subtitle": "Product or service",
+	"drawer.title": "New catalog item",
+	"drawer.editTitle": "Edit catalog item",
+	"action.edit": "Edit",
+	"action.history": "History",
+	"delete.title": "Delete catalog item",
+	"delete.description": "Delete {name} permanently? This cannot be undone.",
+	"delete.drawerDescription": "This permanently removes the archived catalog item.",
+	"delete.confirm": "Delete item",
+	"error.create": "Could not create the catalog item.",
+	"error.update": "Could not update the catalog item.",
+	"error.lifecycle": "Could not change the catalog item lifecycle.",
+	"error.delete": "Could not delete the catalog item.",
+	"error.history": "Could not load catalog item history.",
+	"error.load": "Could not load catalog items.",
+	"error.request": "The catalog operation failed.",
+	"form.cancel": "Cancel",
+	"form.currency": "Currency",
+	"form.kind": "Kind",
+	"form.name": "Name",
+	"form.note": "The SKU is tenant-scoped and cannot change later.",
+	"form.editNote": "SKU is tenant-scoped and cannot change after creation.",
+	"form.price": "Price, minor units",
+	"form.priceHelp": "1000 is 10.00 in the currency below.",
+	"form.sku": "SKU",
+	"form.submit": "Create item",
+	"form.submitting": "Creating…",
+	"form.save": "Save changes",
+	"form.saving": "Saving…",
+	"form.unit": "Unit",
+	"kind.product": "Product",
+	"kind.service": "Service",
+	"status.active": "Active",
+	"status.archived": "Archived",
+	"filters.label": "Filters",
+	"filters.includeArchived": "Include archived items",
+	"lifecycle.title": "Lifecycle",
+	"lifecycle.description": "Archive an item before deleting it permanently.",
+	"lifecycle.history": "View history",
+	"lifecycle.archive": "Archive item",
+	"lifecycle.restore": "Restore item",
+	"lifecycle.delete": "Delete item",
+	"page.action.new": "New item",
+	"page.action.refresh": "Refresh",
+	"page.description": "Products and services with stable tenant-scoped SKUs.",
+	"page.eyebrow": "Commercial master data",
+	"page.title": "Catalog",
+	"price.fallback": "{amount} {currency} minor",
+	"table.caption": "Catalog items",
+	"table.column.item": "Item",
+	"table.column.kind": "Kind",
+	"table.column.price": "Price",
+	"table.column.status": "Status",
+	"table.column.actions": "Actions",
+	"table.count.one": "1 item",
+	"table.count.other": "items: {count}",
+	"table.empty.hint": "Create the first product or service.",
+	"table.empty.title": "No catalog items yet",
+	"table.emptyFiltered.hint": "No item in this workspace matches the current filter.",
+	"table.emptyFiltered.title": "No matching items",
+	"table.loading": "Loading catalog items…",
+	"table.search.label": "Filter catalog items",
+	"table.search.placeholder": "Filter by name or SKU",
+	"table.title": "Products & services",
+	"history.title": "Item history",
+	"history.tableTitle": "Revisions",
+	"history.count": "{count} revisions",
+	"history.caption": "Catalog item revision history",
+	"history.loading": "Loading item history…",
+	"history.emptyTitle": "No revisions yet",
+	"history.emptyHint": "Changes to this item appear here.",
+	"history.emptyValue": "Empty",
+	"history.column.version": "Version",
+	"history.column.action": "Action",
+	"history.column.actor": "Actor",
+	"history.column.changes": "Changes",
+	"history.column.date": "Date",
+	"history.action.created": "Created",
+	"history.action.updated": "Updated",
+	"history.action.archived": "Archived",
+	"history.action.restored": "Restored",
+	"history.action.deleted": "Deleted",
+	"history.actor.user": "User",
+	"history.actor.agent": "Agent",
+	"history.actor.service": "Service",
+	"history.actor.serviceConfiguredBy": "Service, configured by {name}",
+	"history.field.sku": "SKU",
+	"history.field.name": "Name",
+	"history.field.kind": "Kind",
+	"history.field.unit": "Unit",
+	"history.field.basePriceMinor": "Price",
+	"history.field.currency": "Currency",
+	"history.field.status": "Status",
+	"widget.label": "Catalog items",
+	"widget.link": "Open catalog",
+	"widget.note": "Active catalog entries with tenant-scoped SKUs."
+}

package/agent-template/.ai/references/catalog/translations/pl.json

@@ -0,0 +1,101 @@
+{
+	"module.name": "Katalog produktów i usług",
+	"nav.description": "Produkty i usługi",
+	"nav.label": "Katalog",
+	"drawer.subtitle": "Produkt lub usługa",
+	"drawer.title": "Nowa pozycja katalogu",
+	"drawer.editTitle": "Edytuj pozycję katalogu",
+	"action.edit": "Edytuj",
+	"action.history": "Historia",
+	"delete.title": "Usuń pozycję katalogu",
+	"delete.description": "Usunąć trwale pozycję {name}? Tej operacji nie można cofnąć.",
+	"delete.drawerDescription": "Ta operacja trwale usuwa zarchiwizowaną pozycję katalogu.",
+	"delete.confirm": "Usuń pozycję",
+	"error.create": "Nie udało się utworzyć pozycji katalogu.",
+	"error.update": "Nie udało się zaktualizować pozycji katalogu.",
+	"error.lifecycle": "Nie udało się zmienić cyklu życia pozycji katalogu.",
+	"error.delete": "Nie udało się usunąć pozycji katalogu.",
+	"error.history": "Nie udało się wczytać historii pozycji katalogu.",
+	"error.load": "Nie udało się wczytać pozycji katalogu.",
+	"error.request": "Operacja na katalogu nie powiodła się.",
+	"form.cancel": "Anuluj",
+	"form.currency": "Waluta",
+	"form.kind": "Rodzaj",
+	"form.name": "Nazwa",
+	"form.note": "SKU obowiązuje w tej przestrzeni roboczej i później nie da się go zmienić.",
+	"form.editNote": "SKU obowiązuje w tej przestrzeni roboczej i nie można go zmienić po utworzeniu.",
+	"form.price": "Cena w groszach",
+	"form.priceHelp": "1000 to 10,00 w wybranej niżej walucie.",
+	"form.sku": "SKU",
+	"form.submit": "Utwórz pozycję",
+	"form.submitting": "Tworzenie…",
+	"form.save": "Zapisz zmiany",
+	"form.saving": "Zapisywanie…",
+	"form.unit": "Jednostka",
+	"kind.product": "Produkt",
+	"kind.service": "Usługa",
+	"status.active": "Aktywna",
+	"status.archived": "Zarchiwizowana",
+	"filters.label": "Filtry",
+	"filters.includeArchived": "Pokaż zarchiwizowane pozycje",
+	"lifecycle.title": "Cykl życia",
+	"lifecycle.description": "Zarchiwizuj pozycję przed jej trwałym usunięciem.",
+	"lifecycle.history": "Zobacz historię",
+	"lifecycle.archive": "Archiwizuj pozycję",
+	"lifecycle.restore": "Przywróć pozycję",
+	"lifecycle.delete": "Usuń pozycję",
+	"page.action.new": "Nowa pozycja",
+	"page.action.refresh": "Odśwież",
+	"page.description": "Produkty i usługi ze stałym SKU w obrębie przestrzeni roboczej.",
+	"page.eyebrow": "Dane podstawowe sprzedaży",
+	"page.title": "Katalog",
+	"price.fallback": "{amount} {currency} w groszach",
+	"table.caption": "Pozycje katalogu",
+	"table.column.item": "Pozycja",
+	"table.column.kind": "Rodzaj",
+	"table.column.price": "Cena",
+	"table.column.status": "Status",
+	"table.column.actions": "Akcje",
+	"table.count.one": "1 pozycja",
+	"table.count.other": "pozycje: {count}",
+	"table.empty.hint": "Dodaj pierwszy produkt lub usługę.",
+	"table.empty.title": "Nie ma jeszcze pozycji katalogu",
+	"table.emptyFiltered.hint": "Żadna pozycja w tej przestrzeni roboczej nie pasuje do filtra.",
+	"table.emptyFiltered.title": "Brak pasujących pozycji",
+	"table.loading": "Wczytywanie pozycji katalogu…",
+	"table.search.label": "Filtruj pozycje katalogu",
+	"table.search.placeholder": "Filtruj po nazwie lub SKU",
+	"table.title": "Produkty i usługi",
+	"history.title": "Historia pozycji",
+	"history.tableTitle": "Wersje",
+	"history.count": "Liczba wersji: {count}",
+	"history.caption": "Historia zmian pozycji katalogu",
+	"history.loading": "Wczytywanie historii pozycji…",
+	"history.emptyTitle": "Brak wersji",
+	"history.emptyHint": "Zmiany tej pozycji pojawią się tutaj.",
+	"history.emptyValue": "Puste",
+	"history.column.version": "Wersja",
+	"history.column.action": "Akcja",
+	"history.column.actor": "Aktor",
+	"history.column.changes": "Zmiany",
+	"history.column.date": "Data",
+	"history.action.created": "Utworzono",
+	"history.action.updated": "Zmieniono",
+	"history.action.archived": "Zarchiwizowano",
+	"history.action.restored": "Przywrócono",
+	"history.action.deleted": "Usunięto",
+	"history.actor.user": "Użytkownik",
+	"history.actor.agent": "Agent",
+	"history.actor.service": "Usługa",
+	"history.actor.serviceConfiguredBy": "Usługa skonfigurowana przez: {name}",
+	"history.field.sku": "SKU",
+	"history.field.name": "Nazwa",
+	"history.field.kind": "Rodzaj",
+	"history.field.unit": "Jednostka",
+	"history.field.basePriceMinor": "Cena",
+	"history.field.currency": "Waluta",
+	"history.field.status": "Status",
+	"widget.label": "Pozycje katalogu",
+	"widget.link": "Otwórz katalog",
+	"widget.note": "Aktywne pozycje katalogu z SKU w obrębie przestrzeni roboczej."
+}

package/agent-template/.ai/references/catalog/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx",
+		"jsxImportSource": "octane",
+		"types": ["node"],
+		"plugins": [{ "name": "@tsrx/typescript-plugin" }]
+	},
+	"include": ["src/**/*", "tests/**/*.ts"]
+}

package/agent-template/.ai/references/catalog/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+
+/* Booting the embedded PostgreSQL a suite runs against takes seconds under
+   parallel load, well past the 5s vitest default.
+
+   Deliberately self-contained. A sandbox session copies this module into its
+   own workspace and runs these gates there, so importing a shared preset from
+   another workspace package would leave vitest unable to load its config in
+   that copy. The duplication is the price of that isolation; keep it. */
+export default defineConfig({
+	test: {
+		maxWorkers: 2,
+		testTimeout: 30_000,
+		hookTimeout: 30_000,
+	},
+});

package/agent-template/.ai/references/catalog.provenance.json

@@ -0,0 +1,55 @@
+{
+	"id": "catalog.core",
+	"version": "0.6.1",
+	"repository": "Flowdular/official-modules",
+	"sourceCommit": "8ed1e780ba7405d0bdf5082882b92d130b72d081",
+	"artifactSha256": "9010086822aa5f4d13176e465022fd2118c5dd0cb157200b31c2940fec1f3513",
+	"files": {
+		"LICENSE": "155d722071bad9d0d832482e06fd5a47f7034389cb63aabcb39f4282aa3499fc",
+		"migrations/0001_catalog_core.down.sql": "0962a1edf0bde959cd4facccf77bd5b634d6cc25f125a0c79a61770c8871093f",
+		"migrations/0001_catalog_core.up.sql": "602ed9c1852b729cf278cf8536f79e3f7432f23a5a60c50d8826f5c1b9442d18",
+		"migrations/0002_catalog_history.down.sql": "7f163e11ca9033101e3bb1de61481b1a8043c204e65aa2bb508a13b065e98c78",
+		"migrations/0002_catalog_history.up.sql": "3aa30993b1676cf357c2ef87f19a7d4b64b77041c0e4bc743fced04521471c28",
+		"migrations/0003_catalog_history_service_actors.down.sql": "f20ecc8d7d753af3d2b6fdbff9d637fd938884cfbd88b08a30958e6aa000132b",
+		"migrations/0003_catalog_history_service_actors.up.sql": "7caae787ca2fc1e331ccbfda4df5982beec76136e8dc486aab5532ccd338a722",
+		"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",
+		"src/acl/permissions.ts": "3375521a5a229736ffac5a948140ec347dc7a7e4fba80e778c0baaf9e0622590",
+		"src/agent/tools.ts": "3204d20886d2b864482adc1ed3303c653aebd207e16c4fce0c67a4979ea8db07",
+		"src/api/endpoints.ts": "34f1036e759353550be2acf67c6fa254afc790942d09489db2e76a082df5c3a3",
+		"src/client/CatalogHistoryDrawer.tsrx": "6cdba5249be81e70da703cb34c1a2210943ce5e5fb596ee77cf7952e2acf3ee3",
+		"src/client/CatalogItemForm.tsrx": "7dafa4149975d9e7d5784c8a5391b5b64c2405991aaead713d94b61c41168c2c",
+		"src/client/CatalogView.tsrx": "7c507931f33afea8414b002e3ad815740c8db75016c53d8a81effc6427bd958d",
+		"src/client/api.ts": "5f404f6b25777bc8fe2eab5a35424593abc8e879fb83fa2ae4d637fc23fdce4b",
+		"src/client/contribution.tsrx": "e95f755882005ee090c99a119ce2dda2ec70420daed4ce06021193905858c62f",
+		"src/client/index.ts": "03eb0664cdafccb66cb25f2e1b07e6959c2dfa9bdbfffc3e7edf9b535ba4949a",
+		"src/client/navigation-copy.ts": "9a8757e64f4001a93e2bc2861c686a19f791f9d67a396d9e658023b1ec4cea8f",
+		"src/client/state.ts": "bc054bc269026b6abf60d99a2fc5dd94eb8a488fc1ce4c81a1ae1065d9db576b",
+		"src/domain/types.ts": "4b26be80954d792b09a3a34d29d845b9f6119640be505daba325fec820e06ef6",
+		"src/domain/variables.ts": "131130e57838235b1f3fcb799da44baeae16522bb346d522827e022305c110b5",
+		"src/index.ts": "5b27943018db9a18651d62add7d6f8397d7c492a204381fae74547b99b91990d",
+		"src/platform.ts": "3bdc15a5749cceeca4e86388fad13aebcbc151bb4226852d46ed7845248c4efe",
+		"src/server/index.ts": "90eae107d863418124e5d10c4d1fe8a119bd14da605b36de708c18d8500c4b5e",
+		"src/server/runtime.ts": "5f4389a6adf8265f6737c489baf686f63cc3550662103d28b2da9800dd9f5b63",
+		"src/services/catalog-service.ts": "e5ffa703f6a87e4e2e762f5beb87952be40b3b5847d10b373033a9b01fa4a378",
+		"src/services/database-repository.ts": "b513a9459fb3fc1362e9dcd98c10a104b02dbb748ae23c59c6768c2f0e7a1466",
+		"src/services/index.ts": "a08aefe5101814538666f861536287fc382e6c655d62ba9b9ef4bbfbc6ede4af",
+		"src/services/migration.ts": "89c8e333482c80bc819deba0cf4f4e37e94137933af0f6503f4f9ebcb4f5f371",
+		"src/services/repository.ts": "df0f1364cb05031972993c873faf6bcb7fbe4c92d05a04ae980497d9a732dd7f",
+		"src/services/target-idempotency.ts": "7111b56a30b691eaaaa64f5691895ac94b6e0735b0079794835bbbeba5102cb0",
+		"tests/agent-tools.test.ts": "3cdda30b5454d58c6e8791a98e3daf6fe58b9852cd5c437b3614c3f6123baa91",
+		"tests/endpoints.test.ts": "24d05c7dd52820f90c777a1b814529f5188a9a5a9daeaacda07314f17b7483cc",
+		"tests/idempotency.test.ts": "f2e0896635bcd95271b66181daa2c084411913cdf864ae8b4814f2beeb8c2943",
+		"tests/migrations.test.ts": "47d3d741eddde8677be287730d2f96af556b4b7bf0d8378f9a12a7309af17d78",
+		"tests/module.test.ts": "01bedfa1540470cc87c808c75120f6ede7c3b8e3d81e340d2076af0a66f1c7ab",
+		"tests/support/database.ts": "f108cf6390da7669f8935301fac125a7e5653f06ba75327f4bdc28fdd409ba73",
+		"translations/en.json": "406a40b77e3778e83cd4d30e7b3aee8f89c75baf7bc52f1befc6d16f3b877ab3",
+		"translations/pl.json": "db6325b4980d978e1a3098758b5259a68e32469baa09d194b9d6746462776d27",
+		"tsconfig.json": "140bb4775df421146563d13d2f78ff74cb3c2decab6737db32938339248a92ba",
+		"vitest.config.ts": "d13725b13c3712ec91c1646e9226fb172eec2599f72f4e6608bece9912e2bd81"
+	}
+}

package/agent-template/.ai/rules/flowdular.md

@@ -0,0 +1,86 @@
+---
+root: true
+targets:
+  - '*'
+globs:
+  - '**/*'
+description: Flowdular agent contract
+---
+
+<!-- Source: .ai/rules/flowdular.md. Run pnpm rules:generate; never edit generated copies. -->
+
+# Flowdular
+
+An agentic foundation that businesses extend with their own modules.
+
+## One task, one skill
+
+Choose the most specific task in `.ai/skills/README.md` and read only that
+`.ai/skills/<name>/SKILL.md`. Announce the choice briefly. For a multi-part
+request, finish one bounded phase before switching skills. Do not recursively
+load other skills mentioned by a skill. Read referenced code or documentation
+only when the current task needs it. Explicit user instructions take priority.
+
+Sandbox: use the single skill named under Session, at
+`reference/skills/<name>/SKILL.md`. Follow the role's write paths and handoff list.
+Do not load the whole skill catalog into the task context.
+
+## Always-active invariants
+
+1. Stay within the requested scope. Preserve other agents' edits. Read the owning
+   code before changing it. Do not invent missing business decisions.
+2. Spec-first: a new module requires an approved `spec/module.yaml`. Sandbox
+   implementation requires operator approval of the exact current spec hash;
+   any spec change invalidates it. Never infer or grant approval yourself.
+   Only explicit user approval naming a spec permits the host `spec-approval` action.
+3. Deny by default. Use `defineEndpoint`, an explicit permission and identity
+   resolver. Mutations enforce CSRF and bounded input validation.
+4. Tenant identity comes from the authenticated principal, never request input.
+   Use bound SQL, tenant predicates and `transaction(..., { tenantId, access })`.
+   Tenant tables enforce RLS with `USING` and `WITH CHECK`. Runtime roles have
+   neither superuser nor `BYPASSRLS`; migration leases are for DDL only.
+5. Never expose credentials in output, logs or audit. Cross-module access uses
+   declared public capabilities or registered tools, never another module's DB.
+   Agent instructions cannot expand permissions or tool grants.
+6. Persist background work before acknowledging it. Preserve idempotency,
+   leases, recovery and audit evidence. Drain async work before releasing resources.
+7. Applied migrations are immutable. Add numbered PostgreSQL SQL and mirror it
+   byte for byte in `databaseMigrations`. Never bypass checksum or adoption checks.
+8. Generated composition is CLI-owned: `platform/octane.config.ts`,
+   `platform/src/App.tsrx`, `platform/src/generated/**`, platform package
+   dependencies and `flowdular.json` enabled modules. Use `module enable/sync --apply`.
+   Declare imports and dependencies; keep module, package and spec versions aligned.
+9. Use shared `@flowdular/sdk/ui` components and tokens. Keep all locales in sync.
+   UI states: loading, empty, error, populated, denied. Inspect rendered UI after changes.
+10. Prove fixes with regression tests. Never skip assertions, weaken isolation or
+    hide errors to make gates green. Run scoped checks, then `pnpm verify` before a PR.
+    Finish implementation, then run the `auto-review` skill as a separate phase
+    before completion or delivery. Report actual results and remaining failures.
+11. Destructive actions require the runner's flags and explicit scope.
+    `setup quick` and `auth greenfield` are local resets: preview, stop the app,
+    never target a custom or deployed DB. Sandbox agents cannot install, use
+    network/git, or touch a DB outside their module tests.
+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.
+
+Detailed recipes: `docs/agent-contract.md` (lookup only).
+Reference module: `.ai/references/catalog`; visual contract: `docs/design-system.md`.
+
+## Application workspace
+
+For application work, use the path and task map in
+.ai/guides/application-development.md.
+
+This is a generated application consuming the published Flowdular SDK. Extend
+this application's modules; never edit installed dependencies. Upstream paths
+such as packages/server and core modules/auth refer to the read-only SDK under
+platform/node_modules/@flowdular/sdk after installation. Sandbox implementation
+sources belong to the separate @flowdular/sandbox package. A core change must be
+made in the Flowdular repository and released before this application uses it.
+
+The skills and examples use @flowdular/sdk subpath imports. For pnpm --filter,
+read the actual module package name from its package.json. Use pnpm verify and
+pnpm build for this application. Root .ai files are editable project guidance;
+run pnpm rules:generate after changing rules or skills, then pnpm rules:check.
+AGENTS.md, CLAUDE.md, .agents/skills and .claude/skills are generated copies.

package/agent-template/.ai/skills/README.md

@@ -0,0 +1,36 @@
+# Skills
+
+Flowdular is an agentic foundation framework: the platform is the foundation, and these skills are how a coding agent (a sandbox specialist or your own tool) builds on it correctly. Each `SKILL.md` is a procedure plus pitfalls, verified against the code it cites, with front matter `name` (equals the directory), `description`, `roles` (who reads it) and `when` (one line).
+
+| Skill                   | One line                                                                                                              |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `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.          |
+| `auto-review`           | Review finished changes against requirements, contracts and regression evidence before delivery.                      |
+| `core-extend`           | Change a platform package without breaking modules, generated files, or the copies sandbox sessions read.             |
+| `bug-hunt`              | Reproduce with the gate runner, map the symptom to its layer, fix there with a failing test, hunt siblings.           |
+| `perf-audit`            | Hot paths of server, client, bundle and agent runtime; measure before changing anything.                              |
+| `ux-design`             | The record-screen recipe, five states, component and class inventory, icon keys, copy rules.                          |
+| `auth-security-review`  | Endpoint threat surface, scope model, API tokens, secrets, greps, destructive CLI rules, required tests.              |
+| `test-hardening`        | Where tests run, the route recipe, the embedded PostgreSQL provider, required cases, break-the-implementation check.  |
+| `migration-authoring`   | Numbered SQL, byte-identical constants, the checksum ledger, safe adoption, and immutable applied migrations.         |
+| `database-adapter`      | Build a repository on the async provider contract: PostgreSQL SQL, provider leases, forced RLS, isolation tests.      |
+| `translations-i18n`     | Live module bundles, fully qualified keys, locale-aware formatting, parity checks, and raw-key diagnosis.             |
+| `cli-extension`         | Module CLI commands through `commands.json` and `defineCliExtension`, with the runner's approval rules.               |
+| `agent-tool-design`     | Register module tools through the live composition registry with tenant, permission, input, output, and audit bounds. |
+| `business-agent-design` | Ship a module-owned business agent with an exact tool ceiling, tenant binding, revisions, and access tests.           |
+| `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.                          |
+
+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.
+
+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.
+- Claude Code: RuleSync generates `.claude/skills` from this directory.
+- Codex: RuleSync generates `.agents/skills` from this directory.
+- Other tools: use the canonical skill here or add another RuleSync target in `rulesync.jsonc`.
+
+Adding a skill: create `.ai/skills/<kebab-name>/SKILL.md` with the four front matter keys, keep the instructions focused, cite the owning code, add a row above and update the sandbox routing when applicable. Run `pnpm rules:generate` after formatting. `pnpm rules:check` verifies every generated copy.