create-flowdular 0.2.4 → 0.2.6

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

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

@@ -0,0 +1,86 @@
+---
+name: test-hardening
+description: >-
+  Make a module test suite prove behaviour: where tests live and run, the route
+  recipe, the embedded PostgreSQL provider, the denial and isolation cases every
+  endpoint needs, and the break-the-implementation check.
+roles:
+  - backend-engineer
+  - frontend-engineer
+  - reviewer
+  - module-executor
+when: A module has few or tautological tests, a bug escaped the suite, or a reviewer asks whether the tests guard the change.
+---
+
+# Harden a test suite
+
+## 1. Where tests live and run
+
+- `tests/module.test.ts` (one file per module today; more files are fine). `tsconfig.json` includes `src/**/*` and `tests/**/*.ts`, so a test file is `.ts`; `.tsrx` components are not compiled by vitest here. Testable client logic (formatting, filtering, mapping, state transitions) goes into a `.ts` helper next to the view and is imported by the test.
+- Runner: `vitest run` (`pnpm --filter @flowdular/module-<dir> test`). In the sandbox the `tests` gate runs `vitest run --passWithNoTests` inside the module directory, so a module with no tests passes the gate. Treat an empty or trivial suite as a defect, not a pass.
+- New modules use vitest 4.1.11, typescript 5.9.3 and `@types/node` 24.13.3. The catalog reference is an immutable older release; use the current scaffold dependency versions for new code.
+
+## 2. Repositories on an embedded PostgreSQL
+
+`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `coreloom_runtime` and `coreloom_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
+
+## 3. Route recipe (from `modules/auth/tests/endpoints.test.ts`)
+
+```ts
+import { createContext } from '@octanejs/app-core';
+import { createAuthenticationMiddleware } from '@flowdular/sdk/modules/auth/server';
+// build an AuthRuntime around a DatabaseAuthRepository on a createPgliteTestProvider() lease and a cheap scrypt cost,
+// sign up through the auth sign-up route to obtain a cookie and csrfToken, then:
+const routes = createCatalogRoutes(auth, runtime);
+const create = routes.find(
+	(route) =>
+		route.path === '/api/catalog/items' && route.methods.includes('POST'),
+)!;
+const response = await create.handler(
+	createContext(
+		new Request('https://erp.example/api/catalog/items', {
+			method: 'POST',
+			headers: {
+				'content-type': 'application/json',
+				origin: 'https://erp.example',
+				cookie,
+				'x-csrf-token': csrfToken,
+			},
+			body: JSON.stringify(input),
+		}),
+		{},
+	),
+);
+```
+
+The auth middleware must have set the principal for `endpointIdentityFromContext` to find it: either run `auth.middleware(context, next)` before the handler or resolve the session and set `AUTH_PRINCIPAL_STATE_KEY` on `context.state` (both exported from `@flowdular/sdk/modules/auth/server`). Read `modules/auth/tests/endpoints.test.ts` for the runtime shape (`cookie`, `settings`, `service`, `middleware`).
+
+## 4. Cases every endpoint needs
+
+- 401 `UNAUTHENTICATED`: no cookie, no bearer token.
+- 403 `FORBIDDEN`: a principal whose scopes lack the permission.
+- 403 on a mutation without `x-csrf-token` (`CSRF_REJECTED`) and without `origin` (`ORIGIN_REQUIRED`).
+- 400 with the stable code for each validation bound (`INVALID_INPUT`, module codes such as `INVALID_ITEM_KIND`).
+- 409 for the tenant-scoped uniqueness rule, and success for the same key in another tenant.
+- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `coreloom_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
+- Identity: `moduleDefinition.manifest.id` equals the module id (keeps `module.json` and `src/index.ts` aligned). The scaffold writes this and the isolation case; everything else in this list is yours.
+
+Assert at the observation boundary: status code, `error.code`, returned record fields. Do not assert internal helper names, call order, or SQL text.
+
+## 5. Break the implementation
+
+A regression test that never failed proves nothing. For each new test: comment out the guard it protects (`if (denial) return denial;`, the `WHERE tenant_id = $1`, the `UNIQUE` constraint), run the suite, confirm the test fails, restore the code. Record in the handoff which tests were verified this way.
+
+## 6. Flake sources here
+
+`Date.now()` in `createdAt` (sort by `sku`, not by time); `randomUUID()` ids (never assert them); scrypt with the default cost is slow, so tests pass `passwordHash: { cost: 2 ** 12, ... }` as `modules/auth/tests/endpoints.test.ts` does; two tests sharing one provider see each other's rows unless the tables are truncated between them, so take a fresh fixture per test from the file's `tests/support/database.ts` helper.
+
+## 7. Landing
+
+Sandbox: the `tests` gate output appears in the chat after your turn. Repository root: `pnpm --filter @flowdular/module-<dir> test`, then `pnpm verify` before a PR.
+
+## Pitfalls
+
+- `expect(() => service.create(...)).toThrowError(/active tenant/)` pins a message; prefer the error `code` (`DUPLICATE_SKU`) when the class exposes one.
+- A test that imports `@flowdular/sdk/ui` pulls fonts and CSS; keep client tests to `.ts` helpers.
+- `vitest run` picks up `tests/**/*.test.ts`; a `.spec.ts` name also works but keep one convention.

package/agent-template/.ai/skills/translations-i18n/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: translations-i18n
+description: >-
+  Add or review Flowdular UI translations through the shared client runtime,
+  module bundles, locale-aware formatting, and validation gates.
+roles:
+  - business-manager
+  - frontend-engineer
+  - ux-designer
+  - module-executor
+when: A module adds user-facing copy, a locale changes, a raw translation key appears, or UI must support another language.
+---
+
+# Translate Flowdular UI
+
+Flowdular loads translations at runtime. The shell owns locale selection and the fallback chain; each module owns its copy.
+
+## Runtime contract
+
+- `packages/client/src/i18n` registers the shell bundle and every enabled module bundle. Resolution is active locale, then `en`, then the key itself so a missing key stays visible.
+- A module contribution imports `translations/en.json` and every declared locale, then returns `translations: { en, pl }` with its `moduleId`.
+- Use fully qualified keys with `t()`, for example `t('catalog.items.title')`. In `.tsrx`, import from `@flowdular/sdk/client`. In plain `.ts` helpers, import from `@flowdular/sdk/client/i18n` so tests do not pull the TSRX shell entry.
+- Navigation and account-menu labels use getters. Contributions are created before their bundles are registered, so eager `label: t(...)` can paint a raw key.
+- Locale-sensitive dates, numbers and currency use `activeLocale()` with `Intl.DateTimeFormat` or `Intl.NumberFormat`.
+- The personal locale selector lives in Profile and applies immediately. The tenant default remains an Administration setting and is the fallback when the browser has no personal choice.
+
+## Module workflow
+
+1. Keep the same locale list in `spec/module.yaml`, `module.json` and `flowdular.json`. Every module ships `en`.
+2. Put all user-facing labels, hints, empty states, errors and accessible names in `translations/<locale>.json`. Keep flat, module-local keys such as `items.form.save`; the runtime adds the module namespace.
+3. Add the same key to every locale in the same change. Write natural copy in each language.
+4. Import the bundles in `src/client/contribution.tsrx` and expose them through `translations`.
+5. Replace literals with `t('<module>.<key>')`. Dynamic families such as `t('expenses.status.' + status)` require every possible suffix in every bundle.
+6. For a new locale-sensitive helper, add a test that changes the active locale and proves both the text and formatting.
+
+Navigation pattern:
+
+```ts
+import { t, type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+
+return {
+	moduleId: 'inventory.core',
+	translations: { en: translationsEn, pl: translationsPl },
+	navigation: [
+		{
+			get label() {
+				return t('inventory.navigation.label');
+			},
+			get description() {
+				return t('inventory.navigation.description');
+			},
+			// remaining contribution fields
+		},
+	],
+};
+```
+
+## Validation
+
+Run:
+
+```bash
+pnpm flowdular module validate --module <module-id>
+pnpm --filter @flowdular/module-<dir> typecheck
+pnpm --filter @flowdular/module-<dir> test
+pnpm format:check
+```
+
+`module validate` rejects a missing locale file, mismatched locale key sets, and a static `t('module.key')` whose module bundle does not contain the key. A dynamic key cannot be proven statically, so test its complete value set.
+
+When a raw key appears in the UI, check in this order:
+
+1. The key exists in `translations/en.json` and the active locale.
+2. The contribution exposes the bundle under the correct `moduleId` namespace.
+3. Navigation copy is lazy through getters.
+4. The running dev server has rebuilt after the contribution changed.
+
+## Do not
+
+- Add a module-local translation runtime or import JSON directly in each view.
+- Leave English fallbacks in client API helpers. Use a translated fallback and preserve server messages when present.
+- Translate identifiers, provider names, currency codes, shortcuts or stable error codes.
+- Hide a missing key with an empty string.

package/agent-template/.ai/skills/ux-design/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: ux-design
+description: >-
+  Design a module screen on the shared design system, with the record-screen
+  recipe, the five states, the component and class inventory, and the icon keys.
+roles:
+  - ux-designer
+  - frontend-engineer
+when: A screen, drawer form, dashboard widget, or copy is being designed or reviewed.
+---
+
+# Design a screen
+
+`docs/design-system.md` (in a session: `reference/design-system.md`) is the only source of visual decisions. Primitives live in `packages/ui` (`reference/packages/ui/components/*.tsrx` and `components.css`). The reference screen is `.ai/references/catalog/src/client/CatalogView.tsrx` with `CatalogItemForm.tsrx`.
+
+## 1. Rules (design-system.md, section Rules)
+
+1. Primitives first: a `ui-*` class or an exported component before any new visual code.
+2. Colors, fonts, sizes, radii and shadows only from tokens (`var(--...)`); no hex in module CSS.
+3. Never restyle or override a `ui-*` class outside `packages/ui`.
+4. A missing primitive becomes a module-local component on tokens, flagged as a promotion candidate for `packages/ui`.
+5. Blue is action and selection; green, amber and red are state; copper is the brand only.
+6. Minimum text size 12 px; labels `--text-xs` uppercase; numbers tabular (`.num`, `ui-kpi__value`).
+7. Containment is owned by the primitives: children of `ui-view`, `ui-two-col`, `ui-grid-2`, `ui-kpi-grid` shrink, long words wrap, wide content scrolls inside `ui-table-wrap`.
+8. `Kpi` is a stat tile: the value is a number or a short state word; identifiers, addresses and paths go into `note` or a `ui-mono` line.
+9. Records own the page; creating and editing happens in a `Drawer`. Never split the width between a table and a form.
+
+## 2. Record screen recipe
+
+```text
+div.ui-view
+  PageHeader eyebrow title description      actions: Button sm [Icon refresh 14] Refresh, Button sm primary [Icon plus 14] New ...
+  Alert                                     only when error && !formOpen
+  TableCard title count                     head is one line: title with its count left, SearchField and Filters right
+    search  SearchField                     value placeholder label onInput
+    filters Filters                         open onToggle activeCount; the controls live inside the dropdown
+    columns rows rowKey                     columns is a module-level readonly TableColumn<Row>[] outside the component
+    status  'loading' | 'idle'              'loading' only while status === 'loading' && rows.length === 0
+    empty emptyFiltered filtered            filtered picks which of the two the table renders
+    actions actionsLabel                    visible compact buttons; undefined when the scope is missing
+    note                                    one constraint worth stating
+  Drawer open title subtitle onClose        form keyed by 'form-' + formSession
+```
+
+`TableCard` is the record card and `Table` is the only table in the product: never hand-roll `table.ui-table` again, and never rebuild the head, the loading row or the empty state that these already own. `actions(row)` returns `TableAction[]`; the component renders visible compact buttons in its narrow trailing column. Do not build a dropdown or module-owned action markup. Fixed column widths apply through loading, empty and populated states. A cell returns nodes: `span.ui-cell` (`<b>` primary, `<small>` secondary), `ui-mono` for an identifier, `Tag` for state, `numeric: true` on the column for tabular figures.
+
+The shared `Table` is backed by the official `@octanejs/tanstack-table` adapter. A module never imports TanStack directly. It supplies the Flowdular columns, rows and actions above, while `@flowdular/sdk/ui` owns the features, row model, header model and cell rendering.
+
+Every column declares `width`. Primary identity and descriptions get the largest share, dates and identifiers a medium share, and counts or status the smallest. For a table with actions, data widths normally add up to about 90 percent because the shared action column is 160 px. Without actions they add up to 100 percent. Do not leave all columns unspecified: equal distribution wastes space and weakens the hierarchy.
+
+Drawer form: `form.ui-drawer__form > div.ui-drawer__body > div.ui-form > div.ui-form__row > FormField label required help` wrapping a native `input.ui-input`, `select.ui-select` or `textarea.ui-textarea`; `Alert` inside the body for the submit error; `div.ui-drawer__foot` with `<small>` for the constraint and `div.ui-form__actions` (Cancel, primary submit with `disabled={busy}` and a progressive label `Creating…`). `Drawer width="lg"` when rows have two columns or an editor.
+
+Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`). Admin overviews use `ui-kpi-grid` with several `Kpi`; a module dashboard widget is one `Kpi` with `href` and `linkLabel`, rendered by the shell in `dashboard.metrics`.
+
+## 3. Five states
+
+- Loading: `Table status="loading"` while `status === 'loading' && rows.length === 0`, so a refresh never blanks rows the user is reading.
+- Empty: `empty` with an icon and a sentence that names the first action; `emptyFiltered` says no match and is chosen by `filtered`.
+- Error: `Alert` (tone `danger` default) under the header, or inside the drawer while the form is open.
+- Populated: the `Table` rows, or a list where records are not tabular.
+- Denied: the shell already hides navigation and widgets whose `scope` the principal lacks. Inside a view, pass booleans derived from `ModuleClientContext.scopes` (`canManage={options.scopes.includes(X_PERMISSIONS.manage)}` in `contribution.tsrx`, as `modules/agents` does) and do not render the action. A 403 from the server still becomes an `Alert`; it is never a crash.
+
+## 4. Component and prop inventory (`packages/ui/src/components`)
+
+- `Button`: `variant` primary, secondary (default), ghost, danger; `size` sm, md, lg; `type` button, submit; `block`; `disabled`; `onClick`.
+- `FormField`: `label`, `required`, `help`, `error`; one control child with `ui-input`, `ui-select` or `ui-textarea`.
+- `SearchField`: `value`, `placeholder`, `label` (accessible name), `onInput(value)`.
+- `Table`: `columns: TableColumn<Row>[]` (`key`, `header`, required `width`, `cell(row)`, `numeric`), `rows`, `rowKey(row)`, `status`, `loadingLabel`, `empty`, `emptyFiltered`, `filtered`, `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px default, 280 px for two actions), `onSelect(row)`, `selectedKey`, `caption`.
+- `TableCard`: every `Table` prop plus `title`, `count`, `head`, `search`, `filters`, `before`, `after`, `note`, `noteIcon`.
+- `Filters`: `open`, `onToggle`, `activeCount`, `label`; children are the filter controls, which belong in the dropdown and nowhere else.
+- `CheckGrid`: `groups: { label, options: { value, label, hint? }[] }[]`, `value: string[]`, `mono`, `disabled`, `onChange(next)`.
+- `Drawer`: `open`, `title`, `subtitle`, `width` md or lg, `onClose`; child is `ui-drawer__form` or `ui-drawer__body`. Escape and the scrim close it.
+- `Tag`: `tone` neutral, success, warning, danger, info, ink; `dot`; `mono`.
+- `Kpi`: `label`, `value` (string), `unit`, `badge`, `note`, `href`, `linkLabel`.
+- `PageHeader`: `eyebrow`, `title`, `description`; children are the right-side actions.
+- `EmptyState`: `icon`, `title`, `code`, children as the sentence.
+- `Alert`: `tone` danger (default), warning, info.
+- `Avatar`: `name`, `square` (organizations), `large`.
+- `Icon`: `name`, `size` (18 default, 16 in controls, 14 in `Button size="sm"`), `strokeWidth`.
+- `BrandMark`: `size`, `signature`, `tone`; brand moments only.
+
+Icon keys (`ICON_PATHS`, `packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog`, `user`, `users`, `shield`, `code`, `modules`, `file-text`, `play`, `bot`, `flask`, `activity`, `plug`, `search`, `chevron-down`, `chevrons-up-down`, `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`, `alert`, `x`, `sign-out`, `refresh`, `help`, `key`, `settings`, `braces`. An unknown name renders `modules` silently, so check the list.
+
+## 5. Classes a module writes by hand (`packages/ui/src/styles/components.css`)
+
+Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (h2 plus actions inside a view), `ui-toolbar` (+`__spacer`). Surfaces `ui-card` (+`__head`, `__title`, `__body`). Data `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__state` for a dot plus label, `.num`), `ui-cell` (+`ui-cell__muted`), `ui-mono`, `ui-code`, `ui-dot` (+`--muted`). Row action classes are component-owned and are never written by a module. Forms `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`), `ui-input` (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`, `ui-label`, `ui-help` (+`--error`). Drawer `ui-drawer__form`, `ui-drawer__body`, `ui-drawer__foot`. Bits `ui-kbd`, `ui-note`, `ui-menu` (+`__label`, `__item`, `__item--active`, `__item--danger`, `__sep`), `ui-btn ui-btn--icon` for an icon-only button. Classes rendered by components (`ui-drawer__panel`, `ui-search`, `ui-page-head*`, `ui-field`, `ui-empty*`, `ui-alert*`, `ui-tag*`, `ui-kpi__*`, `ui-checks*`, `ui-avatar*`) are not written by hand.
+
+## 6. Copy
+
+User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
+
+## Pitfalls
+
+- `Kpi value={items.length}` does not typecheck; use `String(items.length)`.
+- A `Tag` for a lifecycle state uses `success` for active and `neutral` for archived, with `dot`.
+- An `Icon` inside `Button size="sm"` is 14, not 18.
+- A new component file per screen, form, table, or stateful region; a page composes them.