@flowdular/sdk 0.1.0

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

@@ -0,0 +1,180 @@
+---
+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.
+roles:
+  - business-manager
+  - backend-engineer
+  - frontend-engineer
+  - ux-designer
+  - agentic-engineer
+  - module-executor
+when: A brief asks for a module that does not exist yet, or a sandbox session is labelled new-module.
+---
+
+# 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/.ai/skills/module-update/SKILL.md

@@ -0,0 +1,100 @@
+---
+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.
+roles:
+  - backend-engineer
+  - frontend-engineer
+  - ux-designer
+  - business-manager
+  - agentic-engineer
+  - module-executor
+when: A brief names an existing module, or a sandbox session is labelled edit-module.
+---
+
+# Update an existing module
+
+## 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/.ai/skills/perf-audit/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: perf-audit
+description: >-
+  Find the hot paths of a module or platform package, state their cost, and
+  change only what a measurement justifies.
+roles:
+  - backend-engineer
+  - frontend-engineer
+  - module-executor
+  - reviewer
+when: A screen or endpoint is slow, a list grows, or a review asks whether the change scales.
+---
+
+# 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.

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

@@ -0,0 +1,113 @@
+---
+name: release-eject-pr
+description: >-
+  Land a module or core change: the sandbox eject sequence, the repository
+  verification gates, the git branch and PR conventions, and the post-merge
+  scope grant.
+roles:
+  - module-executor
+  - reviewer
+  - backend-engineer
+when: A change is ready to leave a sandbox session or a working tree and reach the platform.
+---
+
+# Eject, verify, deliver
+
+Two paths reach the same place. The sandbox path is chat, gates, preview, eject. The direct path is a skill in your own coding tool, `pnpm verify`, a pull request. Both end with the module enabled through the CLI and its scopes granted.
+
+## 1. Sandbox eject (`packages/sandbox/src/server/delivery/{local,steps}.ts`, `routes.ts`)
+
+`POST /sandbox/api/sessions/:id/eject` with `{ apply: false }` returns the plan: for every module of the session the files that land in `modules/<dir>`, the files that would be overwritten, the files the session deleted and the eject will remove, packages a module declares that the workspace cannot resolve yet, the gates, and whether the connected application has to restart. With `{ apply: true }` the sandbox streams the steps:
+
+1. Gates: `spec-schema` and `module-schema` once, then `dependencies`, `typecheck`, `tests`, `format` per draft module. Any failure stops the eject before a file is written (`EJECT_GATES_FAILED`).
+2. Copy of each session module into `modules/<dir>`, then removal of the files an edit deleted (`removeModuleFiles`, empty directories included).
+3. `pnpm install` at the workspace root.
+4. `pnpm flowdular module enable <id> --apply --json` for each new module (writes `flowdular.json`, `platform/package.json`, `platform/src/generated/*`, and grants the module's scopes itself).
+5. `pnpm flowdular auth sync-scopes --module <id> --apply --json` for each module (idempotent re-grant, needed for edited modules that added a permission).
+6. `pnpm --filter @flowdular/platform typecheck`.
+7. Optionally `pnpm build`.
+8. A restart note: the connected application loads the new composition and runs new schema constants only at start, so a local `pnpm dev` restarts and a remote deployment redeploys.
+
+A failing step stops the delivery there with the step's output; the session is marked delivered only when every step passed. Eject requires the connected grant to hold `sandbox.modules.eject`. Delivery targets sit behind one interface (`delivery/types.ts`); the request names one with `target: 'workspace' | 'git-pr'` (default from `flowdular.json`), `workspace` is the one above, `git-pr` is section 2.
+
+## 2. Git delivery from a sandbox (`target: 'git-pr'`, `packages/sandbox/src/server/delivery/git-pr.ts`)
+
+The pull request is the unit of a delivery: one session, one branch, one PR, every module the session touched. Nothing in the operator's working tree or index changes; the work happens in a detached worktree under `.flowdular/sandbox/worktrees/<session>` that is removed afterwards, whatever the outcome.
+
+- Available when the workspace is a git work tree with at least one commit, `.flowdular/` is ignored, and the configured remote exists (`git rev-parse --verify HEAD`, `git remote get-url <remote>`); a repository without commits answers "make the first commit before delivering as a pull request". A PR is opened when `gh auth status` succeeds (a provider token sealed in the sandbox configuration is handed to gh as `GH_TOKEN`); otherwise the branch is pushed and the compare link shown.
+- Branch `<branchPrefix>/<module-dir>-<session id first 8>` from `<remote>/<baseBranch>`: `git fetch`, `git worktree add --detach`, `git switch -C`.
+- In the worktree: the copy and the removals, `pnpm install --offline` (fallback `--prefer-offline`), `pnpm flowdular module enable <id> --apply` for each new module with the worktree as `--dir`, the platform typecheck.
+- Guardrails before the commit: `git status --porcelain` in the worktree may list only `modules/<dir>/**` of the session's modules and `pnpm-lock.yaml`. A delivery with a new module may also change `flowdular.json`, `platform/package.json` and `platform/src/generated/**`. The count stays within `sandbox.delivery.maxChangedFiles` or, unset, the `.ai/policies/task-budgets.yaml` figure for the session kind (`new-module` 30, `edit-module` 12, default 18); new packages within `maxNewDependencies` (0). Owners come from `.ai/policies/path-ownership.yaml`; with `crossOwnerChanges.requireReviewer` a cross-owner change asks for a reviewer from each owner in the body. A violation lists the offending paths and stops before anything is committed; the branch is deleted.
+- Commit `sandbox: add|update <module id>` (author from git config) with the session id and the gate summary, `git push -u --force-with-lease <remote> <branch>`, `gh pr create --base <baseBranch> --head <branch> --title "Add|Update <module id>" --body-file <tmp>` (`--reviewer` from `git.reviewers`). A second delivery of the same session updates the branch and keeps the open PR.
+- PR body, plain: two or three sentences from the brief and the last review handoff, `Session <id>.`, the gate table (gate, module, result), the file list grouped as added, modified, removed, `Post-merge: pnpm flowdular auth sync-scopes --module <id> --apply` per module, the reviewer note. No attribution footers, no dashes.
+- `sync-scopes` does not run in the worktree: it is a runtime action against the deployment database, so it stays the post-merge step. Deploy, run it with `FD_AUTH_DATABASE` pointing at that database, verify the navigation entry appears for an owner.
+- Configuration in `flowdular.json`, all optional and validated by `packages/contracts/schemas/project.schema.json`: `sandbox.delivery { default: 'workspace' | 'git-pr', targets: ['workspace', 'git-pr'], git: { remote: 'origin', baseBranch: 'main', branchPrefix: 'sandbox', provider: 'github' | 'none', mode: 'auto' | 'direct' | 'fork', forkOwner: null, reviewers: [] }, maxChangedFiles }`. Read at request time. `auto` never creates a fork: it uses direct delivery only after GitHub confirms push access and otherwise asks the operator to choose `direct` or `fork`. Only an explicit `fork` choice authorizes fork creation.
+- The screen: "Into this workspace" / "As a pull request", offered only when both are usable here; an unusable target says why. The git plan shows branch, base, changed files against the budget, new packages, owners touched and the guardrail verdict; done shows the PR or compare link. `.flowdular/sandbox/sessions/<id>/delivery.json` keeps the branch and the URL.
+
+## 3. Direct path from a working tree
+
+```bash
+pnpm flowdular module enable <id> --apply          # new module only; also grants its scopes (result: scopes)
+pnpm flowdular auth sync-scopes --module <id> --apply   # re-grant after a new permission, or against another database
+pnpm verify                                    # typecheck, test, validate, format:check
+pnpm build                                     # cli build and smoke, module sync --apply, platform build
+pnpm audit --prod --audit-level high           # what CI runs (.github/workflows/ci.yml)
+```
+
+`pnpm validate` runs `spec validate --all`, `blueprint validate --all` (every `.ai/blueprints/*/blueprint.json` plus its companion files) and `module validate`. It checks manifests and schemas, not behaviour; typecheck and tests are the evidence.
+
+Branch names: `feat/<module>-<topic>`, `fix/<module>-<topic>`, `core/<package>-<topic>`. Commit one logical change per commit; generated files travel with the command that produced them.
+
+## 4. PR conventions (repository rules)
+
+- Short body: what changed and why in a few sentences, gotchas, one line on verification (`pnpm verify passes; pnpm build passes`). No file tables, no design essays, no restating the diff.
+- No AI attribution: no AI `Co-Authored-By` line and no `Generated with` footer.
+- No em or en dashes anywhere in commits, PR titles or bodies.
+- Generated files and `modules.enabled` change only through the CLI, and the PR says which command produced them.
+- Changes to `packages/**` name the consumers that were migrated (`core-extend`).
+
+## 4b. Pull request body template
+
+```text
+Adds inventory.core: tenant-scoped stock locations with read and manage scopes,
+a list and create endpoint, a Locations screen with a drawer form, and a
+dashboard KPI. Covers INVENTORY-LIST, INVENTORY-CREATE, INVENTORY-DENY,
+INVENTORY-ISOLATION.
+
+Generated by the CLI in this PR: flowdular.json and platform/package.json
+(pnpm flowdular module enable inventory.core --apply), platform/src/generated/*
+(module sync), pnpm-lock.yaml (pnpm install).
+
+Gates: spec-schema, module-schema, dependencies, typecheck, tests (7), format
+all passed in the sandbox eject; pnpm verify and pnpm build pass locally.
+
+Post-merge: pnpm flowdular auth sync-scopes --module inventory.core --apply against
+the deployment database.
+```
+
+## 4c. Pre-flight checklist
+
+- `git status` shows only `modules/<dir>/**` plus the CLI-generated files named above.
+- `module.json` `version`, `spec/module.yaml` `specVersion` and `package.json` `version` are equal.
+- `spec/module.yaml` is `approved`; the PR does not change its status.
+- No `console.log` left in module code; no secrets or tokens in tests.
+- The PR title is under 70 characters and names the module (`inventory.core: stock locations`).
+
+## 5. Container and tags
+
+CI builds the image from `infra/docker/Dockerfile` on every PR (no push). A release tag `v*.*.*` is the trigger for publishing (workflow owned by the platform team). The image runs `node platform/dist/server/entry.js` with `/data` as the database volume. Compose and Kubernetes provide `FD_AUTH_DATABASE`, `FD_AGENTS_DATABASE`, and `FD_WORKFLOWS_DATABASE`. Production also requires `FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`, `FD_WORKFLOWS_PAYLOAD_KEY`, and `FD_WORKFLOWS_CURSOR_KEY`; generate every key independently with `openssl rand -base64 32` and supply it through the deployment secret.
+
+## Pitfalls
+
+- An eject removes the files a session deleted; a rename shows up as one removal and one addition in the plan.
+- `module enable` runs `pnpm install` when the package is not linked; a failing install is reported as `pnpm install failed while linking the module package`. A failed scope grant after a successful enable is `MODULE_SCOPES_SYNC_FAILED`; rerun `auth sync-scopes`.
+- `platform/.generated/` is a stale ignore entry; the live generated directory is `platform/src/generated/`.
+- `pnpm flowdular module sync --apply` is also run by `pnpm dev` and `pnpm build`; a dirty generated file after a checkout means the enabled list and the files disagree.
+
+## Required auto-review
+
+Before delivery, complete the separate `auto-review` phase. Sandbox eject requires
+a current per-module review record and passing schema, dependency, typecheck,
+test and format gates. Missing, skipped and empty-suite results block delivery.
+Any module edit invalidates its review. Host changes also need the auto-review
+report and full verification described by that skill before completion.

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

@@ -0,0 +1,112 @@
+---
+name: spec-approval
+description: >-
+  Apply an explicit user approval to the exact current Flowdular module
+  specification. Use only when the user directly asks to approve one or more
+  named current specs, never to infer or initiate approval.
+roles:
+  - spec-author
+  - module-executor
+  - reviewer
+when: The user explicitly says to approve a specific module specification or every current specification in a named sandbox session.
+---
+
+# Approve a module specification
+
+Approval is a user decision that an agent may record only as a mechanical
+delegate. Never decide that a specification is good enough, treat a review
+verdict as approval, or infer approval from requests such as "continue", "looks
+good", or "build it".
+
+## 1. Required authority
+
+Proceed only when the current user message explicitly approves:
+
+- one named module;
+- the clearly active module referred to as "this module"; or
+- every current module in one named sandbox session.
+
+The instruction must refer to the current specification. An approval copied from
+an earlier conversation, a different hash, or an earlier session is not
+authority for changed content.
+
+If the target is ambiguous, ask which module. If the user approves several
+modules, process and report each separately.
+
+## 2. Review the exact input
+
+Before recording approval:
+
+1. Read the entire spec/module.yaml.
+2. Confirm its module id and current specVersion.
+3. Run pnpm flowdular spec validate --all --json.
+4. Check the current diff or sandbox review for the requirements, permissions,
+   data ownership and acceptance scenarios being approved.
+5. Stop if validation fails, the module cannot be resolved, or the spec changed
+   while it was being reviewed.
+
+Do not rewrite requirements while applying approval. A requested content change
+is a new spec-authoring step and needs approval after that edit.
+
+## 3. Sandbox path
+
+In the sandbox, use the operator approval action for the selected session module.
+The live route is POST /sandbox/api/sessions/:id/approve, exposed by
+approveSpecification in packages/sandbox/src/client/api.ts.
+
+The route changes the status presentation and records the SHA-256 hash of the
+exact approved text in the session. Do not patch the session workspace file to
+bypass that route. Do not forge browser cookies or sandbox request headers. If
+the operator route is unavailable, report the blocker and leave the spec
+unapproved.
+
+A multi-module session requires an approval record for every affected module.
+Approving one module does not unblock another.
+
+## 4. Repository checkout path
+
+Outside the sandbox, after the explicit current user instruction:
+
+1. Change only the top-level status value to approved.
+2. Format the file without changing its requirements.
+3. Run pnpm flowdular spec validate --all --json again.
+4. Compute shasum -a 256 modules/<dir>/spec/module.yaml.
+5. Report the module id, version and exact approved hash.
+
+Do not combine approval with implementation changes in the same edit. Once the
+approved state and hash are reported, implementation follows module-new or
+module-update.
+
+## 5. Staleness
+
+Approval applies only to the exact content that was approved.
+
+- In a sandbox session, the recorded hash is authoritative. Any later edit,
+  request for changes, or added module reopens the approval gate.
+- In a checkout, any later requirement change must return the status to draft
+  or in-review before authoring continues, then receive a new explicit user
+  approval.
+- A version bump alone is still a content change and needs fresh approval.
+- Never copy an approved status line into another module or session.
+
+## 6. Refuse
+
+Refuse to approve when:
+
+- no current user instruction explicitly grants approval;
+- the user asked only for review, implementation or continuation;
+- validation fails;
+- unresolved business questions remain in the spec;
+- the target module or session is ambiguous;
+- the content changed after the user's decision;
+- a sandbox role attempts to approve its own output.
+
+A sandbox business manager may request approval in its handoff. That request is
+not approval and cannot satisfy this skill's authority requirement.
+
+## 7. Handoff
+
+After approval, state exactly what was approved and which hash now represents
+it. Do not claim that implementation or delivery also passed. Continue to
+implementation only when the user's request includes it and the matching skill
+allows it.