create-flowdular 0.2.4 → 0.2.5

package/agent-template/.agents/skills/database-adapter/references/first-run-and-matrix.md

@@ -0,0 +1,105 @@
+# Adapter setup and delivery matrix
+
+Read this reference when adding a driver adapter, exposing database setup, or
+preparing an adapter-backed module for eject or a pull request.
+
+## Adapter descriptor
+
+A platform adapter descriptor owns the complete first-run contract:
+
+- an open `adapterId` and `dialectId`;
+- a machine-readable configuration schema;
+- UI hints such as labels, descriptions, groups, order, and input kind;
+- an explicit list of secret fields;
+- configuration validation without opening module databases;
+- a connectivity probe with bounded time and sanitized errors;
+- optional provisioning for infrastructure the adapter actually owns;
+- connection creation that returns the shared adapter contract;
+- advertised database capabilities.
+
+The registry is open. Core code resolves a descriptor by id and negotiates its
+capabilities rather than switching over known adapter ids, so an adapter package
+can join without changing module business ports or the setup screen.
+
+Configuration UI is generated by the platform from descriptor metadata. A
+module never implements database setup UI and never asks for a DSN.
+
+## First run
+
+The embedded PostgreSQL is the zero-configuration local default: PGlite runs in
+process, so a workstation starts with nothing installed and still exercises the
+same forced row-level security a deployment enforces. Its data root comes from
+the platform provider, not from each module.
+
+Before selecting another adapter, setup:
+
+1. validates descriptor configuration and required secrets;
+2. probes the target with a strict timeout and no secret echo;
+3. lists every enabled database-owning module;
+4. verifies that each module declares an implementation for the target
+   `dialectId` and that the adapter supplies its required capabilities;
+5. refuses activation with the exact incompatible modules and capabilities;
+6. provisions only after explicit operator confirmation when provisioning
+   changes external state;
+7. runs migrations through a migration lease before runtime leases are served;
+8. verifies readiness under the non-bypass runtime role.
+
+Secret values live in environment-backed or encrypted platform secret storage.
+`flowdular.json`, module manifests, setup responses, logs, audit metadata, run
+snapshots, and pull request descriptions contain only secret references or
+redacted presence state.
+
+## Switching an adapter with existing data
+
+Changing an adapter id never points modules at an empty database and never
+copies storage files. The only supported switch is an explicit operation:
+
+1. stop writes and acquire an export snapshot;
+2. export through module-owned portable records, preserving ids and versions;
+3. provision and migrate the target;
+4. import in dependency-safe batches under tenant context;
+5. verify counts, checksums, referential expectations, and module invariants;
+6. probe reads and writes through the target runtime role;
+7. activate the target only after verification succeeds;
+8. retain the source for rollback until the operator closes the window.
+
+A failed import or verification leaves the source active. There is no silent
+fallback to another database, because that would split writes.
+
+## Module declarations
+
+Each database-owning module declares:
+
+- supported open dialect ids;
+- the required capability set, such as transactions, transactional DDL,
+  schema introspection, returning values, or an isolation level;
+- its module-owned persistence implementation and migrations;
+- one adapter-neutral repository behavior suite.
+
+The platform compatibility check consumes these declarations before first run,
+adapter change, sandbox eject, and deployment validation.
+
+## Delivery matrix
+
+Every turn runs against a real PostgreSQL, because the embedded one starts in
+process. The sandbox and the test suites use `createTestDatabaseProvider()` from
+`@flowdular/sdk/database-testing`, which brings the `coreloom_runtime` and
+`coreloom_background` roles and forced row-level security with it.
+
+A target run covers tenant A and B fixtures, operations without tenant context,
+forged cross-tenant inserts, direct row-security bypass probes, concurrent
+writes, and cleanup. Where a module polls across tenants, it also proves the
+background role reads only the routing columns.
+
+Before eject or a pull request the matrix additionally runs the same suite
+against a server PostgreSQL when one is configured, using a unique schema and a
+role that holds neither `SUPERUSER` nor `BYPASSRLS`. Test credentials are
+short-lived and never enter the transcript. If that target is unavailable the
+session may continue editing, and delivery states the exact missing target.
+
+Server selection is explicit: `FD_TEST_DATABASE_ADAPTER=postgresql`,
+`FD_TEST_POSTGRES_URL` (migrator), `FD_TEST_POSTGRES_RUNTIME_URL` and
+`FD_TEST_POSTGRES_BACKGROUND_URL`. All three URLs are required. Missing or
+unreachable configuration never falls back to PGlite. `.github/workflows/ci.yml`
+runs this matrix, including auth and agents. Keep role separation intact in
+fixtures: even the migration owner must supply tenant context for tenant data.

package/agent-template/.agents/skills/migration-authoring/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: migration-authoring
+description: >-
+  Add an immutable PostgreSQL module migration through @flowdular/sdk/database,
+  with the namespaced v2 ledger, safe schema adoption, forced row-level
+  security, and tenant isolation tests.
+---
+# Author a database migration
+
+An adapter conversion is a separate phase using `database-adapter`. For this phase, read
+`packages/database/src/migrations.ts` and the converted `modules/profile`
+migration as the reference. Flowdular has a migration runner. Do not add
+constructor-owned `DatabaseSync.exec()` guards around it.
+
+## 1. Source layout and compatibility
+
+Migration SQL is checked in and immutable after release:
+
+- `migrations/NNNN_<module>_<name>.up.sql` holds the PostgreSQL source and is
+  byte-exact. Never move, renumber or reformat a released file.
+- `src/services/migration.ts` mirrors every `.up.sql` file as a literal and
+  exports `databaseMigrations: readonly DatabaseMigration[]`, one entry per
+  file. No code translates or rewrites SQL.
+- `.down.sql` documents a reverse operation. Flowdular never executes it.
+
+## 2. What the v2 runner guarantees
+
+`runDatabaseMigrations(database, namespace, databaseMigrations)` uses the
+namespaced `_coreloom_migrations_v2` ledger. A row records namespace, migration
+id, dialect id, checksum, and applied time. The checksum covers the selected
+dialect's exact SQL.
+
+Before applying outstanding work, the runner checks every existing ledger row.
+It refuses checksum drift, a missing script, duplicate ids, a wrong ledger
+dialect, partial adoption, and adapters without transactional DDL. It opens one
+serializable transaction, takes a transaction advisory lock, and commits DDL
+plus ledger rows together. Dry run writes nothing.
+
+The runner selects scripts by the provider's open `dialectId`. Do not add a core
+switch over known dialects. A new driver advertises capabilities and a module
+opts into it by supplying reviewed SQL and tests.
+
+## 3. Explicit adoption proof
+
+Every migration that may predate v2 defines `inspectExisting(database)`. Use
+adapter-owned, capability-checked schema introspection such as `hasTable`,
+`hasColumn`, and `hasIndex` with fixed identifiers.
+
+Return `complete` only when every table, column, index, constraint, data effect,
+and security policy exists. Return `absent` only when none exists. Return
+`partial` for every mixed state. If an adapter cannot inspect a required object,
+extend its introspection capability or supply a narrow module-owned inspection.
+Never guess `complete` and never parse another dialect's catalog directly in
+shared code.
+
+## 4. SQL rules shared by dialects
+
+- Tenant tables carry `tenant_id TEXT NOT NULL`.
+- Tenant uniqueness and lookup indexes start with `tenant_id`; ordered indexes
+  end with `id` for stable results.
+- IDs are text UUIDs generated by the service. Times are integer milliseconds.
+- Money is integer minor units plus a currency code, never floating point.
+- Enums and ranges have database check constraints.
+- Cross-module foreign keys do not exist. Use the owner's capability or API.
+- Additive changes are the default. Destructive or locking changes need an
+  operator-approved rollout, compatibility window, and rollback plan.
+
+Write PostgreSQL directly: its types, conflict syntax, indexes and policies.
+Never rewrite placeholders or DDL text.
+
+## 5. PostgreSQL row-level security
+
+Every PostgreSQL tenant table includes:
+
+```sql
+ALTER TABLE inventory_locations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE inventory_locations FORCE ROW LEVEL SECURITY;
+CREATE POLICY inventory_locations_tenant_policy ON inventory_locations
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+```
+
+The runtime role is not a superuser and has no `BYPASSRLS`. DDL and policy
+ownership use `purpose: 'migration'`. Runtime repository calls use
+`database.transaction(operation, { tenantId, access })`; the adapter sets
+transaction-local `coreloom.tenant_id` on the pinned connection. Queries still
+include `WHERE tenant_id = ...` as defense in depth.
+
+## 6. Add one migration
+
+Scaffold instead of writing from memory:
+
+```bash
+pnpm flowdular migration new <name> --module <id>          # dry run
+pnpm flowdular migration new <name> --module <id> --apply  # writes both files
+```
+
+The scaffold emits the `.up.sql` and `.down.sql` pair with the tenant table, its
+index, and the `ENABLE` + `FORCE` + policy block already correct. Replace the
+placeholder columns with the real schema; keep the row-security block unless the
+table is not tenant owned.
+
+1. Never renumber released files. The scaffold picks the next id.
+2. Mirror every `.up.sql` byte for byte and append one `DatabaseMigration` with
+   the same id.
+3. Add exact `inspectExisting` logic with `migrationObjectState` and
+   `postgresTenantTableState` from `@flowdular/sdk/database`. Pass thunks, never
+   ready promises: adoption runs inside a transaction pinned to one connection,
+   and eager promises issue overlapping queries on it.
+4. Extend repository SQL, row mapping, service validation, endpoint, client,
+   approved spec scenario, and all three module versions.
+
+### Column types that bite
+
+PostgreSQL returns `BIGINT` as a string. Normalize every integer read in the
+repository through a local `integer()` helper; a raw value concatenates where it
+should add, and `enabled === 1` is false against `'1'`.
+
+Widen timestamps, durations and sequences to `BIGINT`. Leave boolean flags,
+counters and version columns `INTEGER`, or every comparison against them has to
+be normalized too.
+
+Money is integer minor units in `BIGINT` plus a currency code.
+
+Never test against a workspace database. `createTestDatabaseProvider()` from
+`@flowdular/sdk/database-testing` gives the suite its own PGlite by default or an
+isolated PostgreSQL schema in server CI. Tenant fixture reads and writes still
+need transaction-local tenant context, including on the migration connection.
+
+## 7. Tests and gates
+
+`pnpm flowdular migration verify` checks the ledger and every module's migration
+set: a missing script, a tenant table without forced row security, and a policy
+lost to a table rebuild.
+
+The migration suite proves byte parity and id order, empty apply, complete
+adoption without row loss, partial refusal, checksum refusal before later SQL,
+dry run without writes, and a clean second start.
+
+Every gate runs against a real PostgreSQL, because the embedded one starts in
+process. Cover tenant A and B isolation, a forged tenant `WITH CHECK` refusal, a
+missing-context `TENANT_CONTEXT_REQUIRED` test, and direct row-security bypass
+probes under a role that holds neither `SUPERUSER` nor `BYPASSRLS`. Where the
+module polls across tenants, prove the background role reads only the routing
+columns.
+
+## Refuse
+
+- Editing, moving, reordering, or removing released migration bytes.
+- A PostgreSQL tenant table without enabled and forced RLS plus both policy
+  clauses.
+- A runtime role with superuser or `BYPASSRLS`.
+- DDL through a runtime lease or request data through `executeScript()`.
+- Automatic SQL translation or a closed core switch over known dialects.
+- Forcing past checksum or partial-adoption refusal.
+- A production-support claim based on a fake driver alone.
+
+## Verification
+
+Run the module typecheck and tests, module validation,
+`pnpm flowdular migration verify`, and `pnpm verify`.

package/agent-template/.agents/skills/module-new/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: module-new
+description: >-
+  Create a Flowdular module from an approved spec, from scaffold to enabled and
+  granted, with the file set and APIs .ai/references/catalog uses.
+---
+# Create a module
+
+The reference module is `.ai/references/catalog` (in a sandbox session: `reference/example-module`). When this skill and the code disagree, the code wins; tell the operator.
+
+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.
+
+## 1. Preconditions
+
+- `pnpm flowdular doctor --json` reports `status: healthy` (repository root only; the sandbox runs gates for you).
+- `modules/<dir>/spec/module.yaml` exists, validates (`pnpm flowdular spec validate --all --json`) and has `status: approved`. `pnpm flowdular module new` refuses a draft with `A module can only be created from an approved specification.` In the sandbox the operator approves the spec after the business manager's turn, and the orchestrator runs the scaffold itself. Outside the sandbox, a host agent may record approval only after an explicit current user request and only through `spec-approval`.
+- Ids: module id and every permission id match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`. `inventory.core` lives in `modules/inventory` as `@flowdular/module-inventory` (`packages/cli/src/module-scaffold.ts`, `packageSuffix`). Module environment variables use the upper-case directory (`modules/auth` reads `FD_AUTH_SECURE_COOKIE`); the database is platform-owned, so a module never gets one of its own.
+
+## 2. Scaffold
+
+```bash
+pnpm flowdular module new inventory.core --spec modules/inventory/spec/module.yaml          # dry run, lists files
+pnpm flowdular module new inventory.core --spec modules/inventory/spec/module.yaml --apply
+```
+
+`packages/cli/src/module-templates.ts` (`planScaffold`) writes a module the generated composition can import, formatted with the workspace Prettier: `module.json` with `platform.{server,client}` from the capabilities, `package.json` with the `.`, `./client`, `./server`, `./platform` exports and pinned versions, `tsconfig.json` with `types: ["node"]`, the spec copy, `src/index.ts`, `src/acl/permissions.ts` (`X_PERMISSIONS` built from the spec `permissions`), `src/domain/types.ts`, `src/services/{repository,<suffix>-service,index}.ts`, `src/api/endpoints.ts`, and then by capability: `database` gives `src/services/{migration,database-repository}.ts` plus the PostgreSQL `migrations/0001_<snake>_core.{up,down}.sql`, otherwise `src/services/memory-repository.ts`; `api` gives `src/server/{runtime,index}.ts` and `src/platform.ts` with `createServerComposition`; `client` gives `src/client/{index.ts,contribution.tsrx,<Pascal>View.tsrx}` plus `api.ts` and `state.ts` when a read permission exists; `cli` gives `src/cli/{commands.json,index.ts}`; always `tests/module.test.ts` (identity and tenant isolation) and `translations/<locale>.json` (`pl` gets the placeholder `Moduł <name>`).
+
+The scaffold is PostgreSQL from the first commit. `database-repository.ts`
+exports `Database<Name>Repository` and `migrate<Name>Database`, takes a
+`DatabaseHandle`, wraps every async method in
+`database.transaction(..., { tenantId, access })`, binds `$1`, `$2` parameters,
+and normalizes integer columns through a local `integer()` helper because
+PostgreSQL returns `BIGINT` as a string. `migrations/0001_<snake>_core.up.sql`
+creates the table with forced row-level security and a tenant policy. The
+runtime takes `context.databases`, acquires a `migration` lease, runs the
+migrations, releases it, then acquires the runtime lease requiring
+`DATABASE_DIALECT_IDS.postgresql`. `tests/module.test.ts` runs on
+`createPgliteTestProvider()` and asserts tenant isolation. The business repository port
+stays async and database-agnostic, and persistence stays on
+`@flowdular/sdk/database`.
+
+The first entity is the middle segment of the first permission id (`inventory.locations.read` gives `locations`, table `inventory_locations`, type `InventoryLocation`); it gets the list endpoint (`.read`), the create endpoint (`.manage`), the table, the view and the tests. Every other permission becomes a constant in `X_PERMISSIONS` only; its entity is `module-update` work. A directory that already holds `spec/module.yaml` and `translations/**` (the business manager's files) is extended, and those files win over the scaffold's; a directory with sources is refused. In the sandbox the orchestrator runs the scaffold once the spec is approved.
+
+What is still yours after the scaffold: the real fields of the entity beyond `name`, validation bounds and stable error codes, uniqueness rules and their indexes, further endpoints and entities, screen columns and the drawer form, tests beyond identity and isolation. A business agent is a separate phase using `business-agent-design`; the scaffold does not invent one.
+
+## 3. Server file set
+
+Copy the HTTP and domain layout of `.ai/references/catalog/src`, and the persistence shape of `modules/profile/src/services/database-repository.ts`. Keep three layers: an async database-agnostic repository port, module-owned persistence and PostgreSQL SQL, and the platform-owned driver provider. Exact endpoint signatures:
+
+```ts
+// src/api/endpoints.ts
+import {
+	defineEndpoint,
+	HttpProblem,
+	jsonResponse,
+	problemResponse,
+	readJsonObject,
+	requiredInteger,
+	requiredString,
+} from '@flowdular/sdk/server';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import {
+	endpointIdentityFromContext,
+	principalFromContext,
+	sessionMutationDenial,
+} from '@flowdular/sdk/modules/auth/server';
+
+const create = defineEndpoint({
+	id: 'inventory.locations.create',
+	path: '/api/inventory/locations',
+	methods: ['POST'],
+	access: { kind: 'permission', permission: INVENTORY_PERMISSIONS.manage },
+	resolveIdentity: endpointIdentityFromContext,
+	handler: async ({ octane }) => {
+		const denial = sessionMutationDenial(octane, auth);
+		if (denial) return denial;
+		try {
+			const value = await readJsonObject(octane.request);
+			const input = { code: requiredString(value, 'code', { max: 32 }) };
+			const tenantId = principalFromContext(octane)!.tenantId;
+			return jsonResponse(
+				{ location: await runtime.service().create(tenantId, input) },
+				201,
+			);
+		} catch (error) {
+			return failure(error);
+		}
+	},
+});
+```
+
+`createXRoutes(auth: AuthRuntime, runtime: XRuntime)` returns `[list.serverRoute, create.serverRoute] as const`. `src/platform.ts` (the scaffold writes this; extend it):
+
+```ts
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createInventoryRuntime({ databases: context.databases });
+	return {
+		routes: createInventoryRoutes(context.auth, runtime),
+		dispose: () => runtime.dispose(),
+	};
+}
+```
+
+`PlatformServerContext` also carries `databases: DatabaseProvider`, `settings: ModuleSettingsRuntime`, `agentTools: PlatformToolRegistry`, `agentDefinitions: PlatformAgentRegistry`, and `capabilities: PlatformCapabilityRegistry`. The runtime shares one lazy database initialization, uses separate migration and runtime leases, and releases the runtime lease from `dispose()`; `prepare()` remains read-only. A composition may return module settings, lifecycle hooks, agent registrations, and typed cross-module capabilities as described in the focused skills.
+
+Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('coreloom.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
+
+Errors: `{ error: { code, message } }`; service errors `class XServiceError extends Error { constructor(readonly code: string, message: string, readonly status = 400) }`; a `failure(error)` helper routes them to `jsonResponse(..., error.status)` and everything else to `problemResponse(error, 'The <module> operation failed.')`.
+
+## 4. Client file set
+
+`src/client/{index.ts,contribution.tsrx,api.ts,state.ts,XView.tsrx,XForm.tsrx}`. The canonical entry:
+
+```ts
+// src/client/index.ts
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createInventoryClientContribution as canonicalContribution } from './contribution.tsrx';
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({ csrfToken: context.csrfToken });
+}
+```
+
+Contribution rules (`packages/client/src/contributions.ts`): `navigation[].group` in `Workspace`, `Operations`, `Agents`, `Administration`, `Development` (`Agents` only with an `agents.core` dependency, `Development` is owner-only in the shell); `widgets[].slot` in `WORKSPACE_SLOTS` (`dashboard.metrics`, `dashboard.main`, `dashboard.aside`, `topbar.actions`); `glyph` an `ICON_PATHS` key (`packages/ui/src/icons/Icon.tsrx`, list in `ux-design`); ids `<module>.navigation`, `<module>.dashboard.<name>`, view id equals the URL slug; `accountMenu` for personal screens (`modules/profile`). Duplicate ids or a navigation entry pointing at a missing view throw at boot.
+
+State and data: `useMemo(() => createXClientState(), [])` per component, `cell<T>()` for typed fields, `const [items] = useValue(state.items)`, `store.act((transaction) => transaction.set(state.items, records), 'inventory/loaded')`. Mutations send `content-type: application/json`, `x-csrf-token`, `credentials: 'same-origin'`. `Kpi.value` is a string. Screen and form pattern: `ux-design`.
+
+## 5. Tests and local gates
+
+`tests/module.test.ts` (vitest): identity, tenant isolation and uniqueness against a `createPgliteTestProvider()` lease, and one denial per endpoint through `route.handler(createContext(request, {}))` (`test-hardening`). Then, from the repository root:
+
+```bash
+pnpm --filter @flowdular/module-inventory typecheck     # tsrx-tsc --noEmit -p tsconfig.json
+pnpm --filter @flowdular/module-inventory test          # vitest run
+pnpm flowdular module validate --json
+pnpm flowdular spec validate --all --json
+pnpm format:check
+```
+
+`module validate` (`packages/cli/src/module-validate.ts`) also checks the composition contract: `PLATFORM_SERVER_ENTRY_MISSING` and `PLATFORM_EXPORT_MISSING` (no `src/platform.ts` or `./platform` export behind `platform.server`), `PLATFORM_CLIENT_ENTRY_MISSING` and `PLATFORM_CLIENT_EXPORT_MISSING`, `PACKAGE_NAME_MISMATCH`, `SPEC_ID_MISMATCH`, `TRANSLATION_FILE_MISSING`, `TRANSLATION_KEYS_MISMATCH`, and the warnings `SPEC_VERSION_DRIFT` and `LOCALE_NOT_IN_PROJECT`.
+
+Sandbox gates (`packages/sandbox/src/server/gates.ts`): `spec-schema` and `module-schema` once per session workspace; `dependencies`, `typecheck`, `tests` (`vitest run --passWithNoTests`, so no tests still passes) and `format` (`prettier --check .`) once per draft module with the module's own binaries. The session workspace is a real pnpm workspace that installs what each draft `package.json` declares, so an undeclared import fails the `dependencies` gate, which runs after every turn that changed files. A driver with a shell may run the same commands from the module directory; the sandbox runs them again after the turn and feeds a failure back into the fix prompt.
+
+## 6. Enable
+
+```bash
+pnpm flowdular module enable inventory.core --apply
+```
+
+One command (`packages/cli/src/runner.ts`, `module enable`): adds the id to `flowdular.json` `modules.enabled`, adds the package to `platform/package.json`, runs `pnpm install` when the package is not linked, regenerates `platform/src/generated/modules.{server,client}.ts`, and then runs `auth sync-scopes` for the module, reporting the grant as `scopes` in the result; a failed grant is `MODULE_SCOPES_SYNC_FAILED` with the module already enabled. Never edit those files by hand. `pnpm flowdular auth sync-scopes --module inventory.core --apply` stays the way to re-grant later (a new permission, a new owner, a deployment database): it grants the spec's `permissions[].id` to the owners of every tenant (`modules/auth/src/services/auth-service.ts`, `grantModuleScopes`). Members never receive new scopes automatically; a module bundled with the platform also adds its scopes to `BUNDLED_MODULE_SCOPES` and, for read scopes, `MEMBER_SCOPES` in `modules/auth/src/acl/scopes.ts` (a core change). The sandbox eject runs enable for each new module and sync-scopes for each module (`packages/sandbox/src/server/delivery/local.ts`).
+
+## Pitfalls
+
+- 415 on every POST: the client did not send `content-type: application/json` (`readJsonObject`).
+- 403 `CSRF_REJECTED` or `ORIGIN_REQUIRED`: `x-csrf-token` missing or the request is not same-origin.
+- Module enabled but no navigation: scopes not granted, or `platform.client` missing.
+- Routes 404: `platform.server` missing, no `./platform` export, or `src/platform.ts` absent; `pnpm flowdular module validate` names it (`PLATFORM_*`).
+- `Kpi` typecheck error: `value` must be a string.
+- Register every `translations/*.json` bundle in the client contribution, put all user-facing copy there with matching key sets, and resolve it with `t()` as described by `translations-i18n`.
+- Every relative import needs its `.ts` or `.tsrx` extension.
+- `module.json` `version`, `spec` `specVersion` and `package.json` `version` are one number.

package/agent-template/.agents/skills/module-update/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: module-update
+description: >-
+  Change an existing module (endpoint, table, screen, permission, widget) with
+  the fixed touch list per change class and the version bump rules.
+---
+# Update an existing module
+
+## 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`.
+
+Sandbox facts for an edit session (`packages/sandbox/src/server/sessions.ts`): the module is copied to `workspace/modules/<dir>` and a pristine copy to `base/modules/<dir>`; the diff shown to the operator and the eject plan compare the two. The workspace is a pnpm workspace of its own (declared dependencies install for real; a `package.json` change triggers a reinstall that counts as the `dependencies` gate). The business manager updates the spec before implementation. The operator approves the exact spec hash for every affected module; editing that spec, requesting changes, or adding another module reopens its approval gate. A sandbox specialist never writes `status: approved`; a host agent may invoke approval only after an explicit current user request through `spec-approval`. Delivery checks the recorded hash again.
+
+## 2. Classify the change and use its touch list
+
+Change classes: endpoint, table, column, screen, widget, permission, setting, cross-module read, agent tool, business agent, fix.
+
+New endpoint:
+
+1. `src/services/<name>-service.ts`: the method with validation and a stable error code.
+2. `src/services/repository.ts` and `database-repository.ts`: the async interface method and SQL with `$1`, `$2` parameters, `WHERE tenant_id = $1` on every tenant-owned query, inside `database.transaction(..., { tenantId, access })`.
+3. `src/api/endpoints.ts`: `defineEndpoint` with `access`, `resolveIdentity: endpointIdentityFromContext`, `sessionMutationDenial(octane, auth)` first on mutations, `readJsonObject` plus `requiredString`/`requiredInteger`/`optionalString`; add the route to the returned tuple and its id to `endpoints`.
+4. `src/client/api.ts`: the fetch (`content-type: application/json`, `x-csrf-token`, `credentials: 'same-origin'`).
+5. `tests/module.test.ts`: service rule tests plus a 401 and a 403 through `route.handler(createContext(...))`, and a tenant isolation case.
+6. `spec/module.yaml`: an acceptance scenario, `specVersion` bump.
+
+New column or table:
+
+1. Write `migrations/000N_<module>_<name>.up.sql` first and its documented reverse in `.down.sql`. Never edit, reorder, or remove a migration that shipped. A new table uses `CREATE TABLE IF NOT EXISTS`; a new column uses `ALTER TABLE ... ADD COLUMN` once under the ledger.
+2. `src/services/migration.ts`: append `X_MIGRATION_00N` mirroring the `.up.sql` file byte for byte and append its `{ id, sql: { postgresql: X_MIGRATION_00N }, inspectExisting }` entry to `databaseMigrations`. Build `inspectExisting` from `postgresTenantTableState(...)` so a mixed state returns `partial`.
+3. `database-repository.ts`: extend the row interface and `fromRow`, the `INSERT`, `UPDATE` and `SELECT` lists, and the `integer()` normalization for a new integer column. Migrations run from the runtime's `migration` lease, not from the repository. Add the migration tests required by `migration-authoring`.
+4. `src/domain/types.ts`, service, endpoint validation, client form and table column.
+5. Tests against the module's `tests/support/database.ts` provider for the new rule; `spec/module.yaml` invariant or scenario, `specVersion` bump.
+
+New permission:
+
+1. `spec/module.yaml` `permissions`: the new `{ id, description }`.
+2. `src/acl/permissions.ts`: the constant with the same string.
+3. Endpoint `access.permission` and client `scope` on the navigation entry, widget or `canManage` flag.
+4. After eject or enable: `pnpm flowdular auth sync-scopes --module <id> --apply` grants it to owners. Members and bundled defaults require a core change in `modules/auth/src/acl/scopes.ts` (`BUNDLED_MODULE_SCOPES`, `MEMBER_SCOPES`); say so in the handoff instead of editing another module.
+
+New screen or widget:
+
+1. `src/client/XView.tsrx` (and `XForm.tsrx` for a drawer) following the pattern in `ux-design`.
+2. `src/client/contribution.tsrx`: a `views` entry, a `navigation` entry with a unique id, `viewId`, `group`, `glyph` from `ICON_PATHS`, `scope`, `order`; or a `widgets` entry with a `WORKSPACE_SLOTS` slot. Widget state is its own store instance.
+3. `src/client/index.ts`: re-export the view.
+4. Add user-facing copy to every declared `translations/*.json` bundle and resolve it with fully qualified `t()` keys. Navigation copy uses getters because contributions exist before bundles are registered.
+
+New setting:
+
+1. `src/settings.ts`: `export const X_MODULE_SETTINGS = defineModuleSettings({ moduleId: '<module>.core', settings: { key: { type: 'string' | 'number' | 'boolean', defaultValue, visibility: 'private' | 'shared', client: boolean, scope: 'tenant' | 'platform', labelKey, label, descriptionKey, description, min?, max?, enum?, secret? } } })` from `@flowdular/sdk/kernel` (`packages/kernel/src/module-settings.ts`; setting keys match `^[a-z][a-zA-Z0-9]*$`). `labelKey` and `descriptionKey` are fully qualified module translation keys present in every locale. Keep the English literals as compatibility fallbacks; values, ids and secrets are never translated.
+2. `src/platform.ts`: return `settings: X_MODULE_SETTINGS` next to `routes`; the platform declares it at boot and Administration, Modules renders it in the module's drawer (`modules/system/src/client/ModuleSettingsSection.tsrx`, behind `system.settings.read` and `system.settings.manage`; the API is `GET /api/settings` and `POST /api/settings/update` in `modules/system/src/server/endpoints.ts`).
+3. Read it live where it is used: `context.settings.get<number>(tenantId, '<module>.core', 'key')` at request time, never cached at boot; pass `context.settings` into the runtime or service that needs it (`modules/agents/src/settings.ts`, `agentSettings`, shows the pattern with an environment fallback).
+4. `spec/module.yaml`: an invariant or scenario naming the setting and its bounds; `specVersion` bump. Cross-module reads of a setting need `visibility: 'shared'` and a declared dependency.
+
+Cross-module read: import the other module's runtime or service type from its public entry (`@flowdular/module-<x>` or `@flowdular/module-<x>/server`), declare `{ "id": "<x>.core", "range": "^0.1.0" }` in `module.json` `dependencies` and the spec, and add the package to `package.json`. Never open its database or import from its `src/` path.
+
+Agent tool: use `agent-tool-design` as a separate phase; add the approved scenario, `src/agent/tools.ts`, the `context.agentTools.register(...)` call, target-side idempotency for writes, and denial tests.
+
+Business agent: use `business-agent-design` as a separate phase; add the approved behavior and refusal scenarios, declare the `agents.core` module and package dependencies, define it in `src/agent/agents.ts`, and register it with `context.agentDefinitions.register(...)`. A code definition owns behavior and a maximum exact tool allowlist. Provider, model, active state, and the reduced enabled tools remain tenant binding data.
+
+## 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.
+
+## 4. Gates
+
+Sandbox: the role's gates run after the turn. Repository root:
+
+```bash
+pnpm --filter @flowdular/module-<dir> typecheck
+pnpm --filter @flowdular/module-<dir> test
+pnpm flowdular spec validate --all --json
+pnpm flowdular module validate --json
+pnpm format:check
+```
+
+The `dependencies` gate (sandbox) scans imports under `src/`; declare any new package before you import it.
+
+## 5. Landing
+
+Sandbox: eject runs the gates per module, copies added and changed files over the workspace copy and removes the files the session deleted (`packages/sandbox/src/server/delivery/steps.ts`, `removeModuleFiles`), runs `pnpm install`, `auth sync-scopes` for the module, and a platform typecheck; any failed step stops the delivery there. `module enable` runs only for a new module. A session may carry several modules (`modules[]` in `session.json`); each is diffed against its own base and delivered in the same eject. Repository root: `pnpm verify`, then a PR (`release-eject-pr`).
+
+## Pitfalls
+
+- Renaming `createServerComposition`, `createClientContribution` or a permission constant breaks the platform typecheck or another module.
+- Editing an applied `.up.sql` file, even only its whitespace, changes its checksum and blocks startup. Add a new numbered migration.
+- `ORDER BY` on a new list must be covered by a `(tenant_id, <column>, id)` index.
+- A new `Tag` tone or `Icon` name must exist in `@flowdular/sdk/ui`; there is no fallback warning.
+- Editing `platform/**`, `flowdular.json`, or another module from a module change is out of scope; hand off with the exact core change needed.

package/agent-template/.agents/skills/perf-audit/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: perf-audit
+description: >-
+  Find the hot paths of a module or platform package, state their cost, and
+  change only what a measurement justifies.
+---
+# Performance audit
+
+Measure first. A micro-rewrite without a number is not a performance change and does not belong in the diff.
+
+## 1. Inventory the hot paths
+
+Server (per request):
+
+- Queries are asynchronous and pooled, so the cost is round trips, not a blocked event loop. A query inside a loop, an N+1 read after a list, or one transaction per row multiplies the round trip by the row count; do the work in one statement. A list endpoint that returns a tenant's whole table is still O(rows) per request, so paginate or filter in SQL, never in JavaScript after the rows arrive.
+- A lease or a transaction held longer than the work needs starves the pool. Open the transaction around the statements it protects and release it; never hold one across a fetch, an agent call, or a sleep.
+- `list(tenantId)` orders by a column: the index must cover `(tenant_id, <order column>, id)` (`.ai/references/catalog/src/services/migration.ts` has `catalog_items_tenant_sku_idx`). Without it PostgreSQL adds a sort node over the tenant's rows on every call.
+- `readJsonObject` caps bodies at 16 KB and reads the whole text once; do not raise the cap for one field, add an endpoint.
+- `defineEndpoint` allocates a request id and a Set of permissions per request through `endpointIdentityFromContext` (`new Set(principal.scopes)`); this is fine at current sizes and not a target.
+- The runtime checks the migration ledger once, behind a short `purpose: 'migration'` lease, and then holds one runtime lease for the repository (`src/server/runtime.ts` shares a single initialization promise). Acquiring a lease or building a repository per request adds a ledger read and a pool acquisition to every request.
+
+Client (per render):
+
+- `items.filter(...)` and `toLocaleLowerCase` run on every render in `CatalogView.tsrx`. With a few hundred rows this is invisible; past that, derive once with `store.derive((get) => ...)` from `segment-state` or filter in the effect that loads data.
+- One store per component (`useMemo(() => createXClientState(), [])`) is the intended shape; a shared module-level store would leak between screens.
+- Widgets in `dashboard.metrics` each fetch on mount. Five widgets are five requests on the dashboard; a widget that needs a count should not load the whole list once an endpoint can count.
+
+Bundle:
+
+- `packages/ui/src/index.ts` imports the Plex fonts and `styles/index.css` at the top, so every consumer of `@flowdular/sdk/ui` pulls them once. A module must not import fonts or global CSS again.
+- Module CSS is allowed only for module-specific composites (`modules/agents/src/client/agents.css`).
+
+Agent runtime (`modules/agents`, `packages/harness`):
+
+- Bounds that exist: `maxSteps` 1 to 32 and `timeoutMs` 250 to 86400000 per agent definition (`modules/agents/src/services/agent-service.ts`), worker concurrency `FD_AGENT_WORKER_CONCURRENCY` (1 to 16, default 2) and lease `FD_AGENT_WORKER_LEASE_MS` (`modules/agents/src/server/runtime.ts`).
+- Tool calls have a deadline (`timeoutMs`, default 30 seconds, bounded from 250 to 600000 ms) and serialized output is capped at 32 KB by the harness. A list tool must still page or limit rows so useful data fits inside that cap.
+
+## 2. Measure
+
+- Server: a vitest `bench` or a script against the module's `tests/support/database.ts` provider seeded with 10k rows for one tenant and 10k for another; time `list(tenantId)` before and after an index. `await database.query({ text: 'EXPLAIN (ANALYZE, BUFFERS) SELECT ...' })` shows an `Index Scan` or the `Seq Scan` plus `Sort` pair that means the index is not covering the order.
+- Client: count renders with a counter in the component during development, or `store.stats()` for commit counts. Remove the instrumentation before the handoff.
+- Bundle: `pnpm --filter @flowdular/platform build` prints chunk sizes.
+
+Record the number, the input size and the machine in the handoff or PR body.
+
+## 2b. Bench recipe
+
+```ts
+// tests/list.bench.ts (vitest bench; run with: pnpm --filter @flowdular/module-catalog exec vitest bench)
+import { bench, describe } from 'vitest';
+import { CatalogService } from '../src/services/catalog-service.ts';
+import { createCatalogTestDatabase } from './support/database.ts';
+
+const database = await createCatalogTestDatabase();
+const service = new CatalogService(database.repository);
+for (let index = 0; index < 10_000; index += 1) {
+	for (const tenant of ['tenant-a', 'tenant-b']) {
+		await service.create(tenant, {
+			sku: `SKU-${index}`,
+			name: `Item ${index}`,
+			kind: 'product',
+			unit: 'each',
+			basePriceMinor: index,
+			currency: 'EUR',
+		});
+	}
+}
+
+describe('catalog list', () => {
+	bench('list one tenant (10k of 20k rows)', async () => {
+		await service.list('tenant-a');
+	});
+});
+```
+
+Keep bench files out of `tests/**/*.test.ts` so the `tests` gate does not run them; name them `*.bench.ts`. Delete the file or keep it only when the number is worth tracking.
+
+## 2c. Report template
+
+```text
+Path:        GET /api/catalog/items -> CatalogService.list -> DatabaseCatalogRepository.list
+Complexity:  O(rows of tenant) time and space per request; ORDER BY covered by catalog_items_tenant_sku_idx
+Measurement: 10k rows per tenant, embedded PGlite, Node 24: 3.1 ms per call before, 3.0 ms after (no change)
+Decision:    no code change; add pagination when a tenant exceeds ~50k items
+```
+
+## 3. Change only what the number justifies
+
+Allowed without a benchmark: adding a missing covering index; moving a filter from JavaScript into the SQL `WHERE`; removing a duplicate fetch. Everything else (loop style, hoisting, memoization of cheap values, replacing `Array.prototype` calls) needs a before and after measurement in the same environment.
+
+Complexity to state in the review: for each new data structure and loop on a request or render path, its time and space in terms of rows, tenants, or items. Unbounded growth (a Map keyed by tenant that is never pruned, a list of listeners never detached) is a defect even when each entry is small.
+
+## Pitfalls
+
+- `LIKE` or `=` against `lower(column)` cannot use a plain `(tenant_id, column)` index; store a normalized column (`sku_normalized`) as `.ai/references/catalog` does, or add an expression index on `lower(column)`.
+- `ORDER BY lower(name)` (`Flowdular/official-modules`, `modules/parties`) cannot use the `(tenant_id, name, id)` index for the sort; acceptable at current sizes, name it if parties grow.
+- A `Kpi` that shows `items.length` after loading the full list is O(rows) network per dashboard load.
+- Never change behaviour in a performance commit; keep the functional tests green and add none that assert internal call counts.