create-flowdular 0.2.3 → 0.2.5

package/agent-template/.agents/skills/release-eject-pr/SKILL.md

@@ -0,0 +1,107 @@
+---
+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.
+---
+# 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/.agents/skills/spec-approval/SKILL.md

@@ -0,0 +1,106 @@
+---
+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.
+---
+# 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/.agents/skills/test-hardening/SKILL.md

@@ -0,0 +1,79 @@
+---
+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.
+---
+# 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/.agents/skills/translations-i18n/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: translations-i18n
+description: >-
+  Add or review Flowdular UI translations through the shared client runtime,
+  module bundles, locale-aware formatting, and validation gates.
+---
+# 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/.agents/skills/ux-design/SKILL.md

@@ -0,0 +1,92 @@
+---
+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.
+---
+# 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.

package/agent-template/.agents/skills/variables/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: variables
+description: >-
+  Build variable-aware fields and templates on the {{ }} contract, the scope
+  mask, and server-side resolution, with agents.core as the worked example.
+---
+# Variables (templating and linked fields)
+
+A variable field lets a stored value embed `{{ key }}` tokens that are filled at
+run time from context or another module's data. The contract is pure and lives
+in `@flowdular/sdk/contracts` (`packages/contracts/src/variables.ts`); the fields are
+presentational primitives in `@flowdular/sdk/ui`; resolution happens on the server
+before the consumer sees the text. `agents.core` is the worked example: an agent
+author writes instructions as a template and the run snapshot carries the
+resolved text.
+
+## The `{{ }}` contract
+
+`VariableDefinition { key, label, kind, scope?, sample?, description? }` is one
+offerable variable. `kind` is `text | number | date | money | identifier`.
+`key` is a dot path whose segments start lowercase and may continue in
+camelCase (`context.user.displayName`), matched by `VARIABLE_KEY_PATTERN` /
+`isVariableKey`.
+
+- `extractVariables(template)`: the distinct trimmed `{{ key }}` tokens, in
+  first-seen order.
+- `validateTemplate(template, available, allowedScopes?)`: `{ unknown, forbidden }`.
+  `unknown` are tokens not in `available`; `forbidden` are tokens whose def
+  declares a `scope` not present in `allowedScopes` (omit `allowedScopes` to skip
+  the scope check).
+- `resolveTemplate(template, values, { onMissing })`: substitutes each
+  `{{ key }}` with `values[key]`. `onMissing` is `keep` (default, leave the token
+  verbatim) or `blank`.
+- `tokenizeTemplate(template)`: the segments the UI overlay highlights; the
+  `text` fields concatenate back to the exact input.
+
+Rules the resolver guarantees: tokens are `{{ key }}` with optional inner spaces;
+`\{{` outputs a literal `{{`; substitution is a single pass, so a value that
+itself looks like a token is emitted verbatim (never recursive); only own,
+string keys resolve, so prototype keys (`__proto__`, `toString`) never resolve.
+No eval, no expressions, only key substitution.
+
+## The scope mask
+
+`VariableDefinition.scope` is the permission required to read the source. A
+variable is offered and resolved only when the principal holds that scope:
+
+- The UI fields never fetch and never check scopes. The caller passes
+  `variables` already filtered to what this principal may use, so a variable the
+  principal cannot read is simply absent from the menu and highlights as an error
+  pill if typed.
+- On the server, filter the definition list by the principal's scopes before
+  building `values`, or call `validateTemplate(..., allowedScopes)` and refuse a
+  template whose `forbidden` is non-empty. A scope-less variable
+  (`context.*`) is always allowed.
+
+## The UI fields (`@flowdular/sdk/ui`)
+
+`VariableTextarea` (multiline), `VariableInput` (single line), and
+`VariableSelect` (one literal option or one variable token) are presentational.
+All take `value`, `onInput`, `variables: readonly VariableDefinition[]`, optional
+`sampleValues?: Record<string,string>`, required translated `label` (accessible
+name), `name` (so a `FormData` submit still captures it), `required`, `disabled`,
+and `error`. Input and textarea also require translated `insertLabel`,
+`variablesLabel`, and `emptyLabel`; the shared primitive has no English copy to
+fall back to. Select takes `options: readonly VariableSelectLiteralOption[]` and
+requires translated `literalGroupLabel` and `variablesGroupLabel`. A caller also
+localizes every `VariableDefinition.label` before passing the definitions, since
+that label is visible in the picker.
+
+- The `braces` affordance (a `{}` icon in `ICON_PATHS`) opens a menu of the
+  available variables with label, key, and current or sample value; picking one
+  inserts `{{ key }}` at the caret. Typing `{{` opens the same menu filtered by
+  what follows; ArrowUp/Down and Enter pick, Escape closes.
+- Tokens are highlighted by an overlay layer (`tokenizeTemplate`) sitting behind
+  a transparent control, so `{{ key }}` reads as a pill while the real value
+  stays plain text; an unknown or forbidden token gets the error pill. All
+  color comes from tokens; measurement is client-only in an effect, so SSR is
+  safe. See `packages/ui/src/components/VariableField.tsrx` and its wrappers.
+- `VariableSelect` stays a native `<select>`. Literal values and allowed
+  `{{ key }}` tokens are real `<option>` values, so keyboard navigation,
+  validation, disabled state, accessible naming, and `FormData` submission keep
+  browser semantics. Samples appear only in option labels. The component never
+  resolves the selected token.
+
+Keep the fields presentational: the caller supplies `variables` and
+`sampleValues`, the component never fetches.
+
+The platform variable registry (`@flowdular/sdk/kernel`) registers definitions and
+their execution-time resolvers. Reach the shared instance with
+`platformVariableRegistry(context.capabilities)`. `list(scopes)` requires an
+explicit permission snapshot and is the only
+definition list a server sends to a field. `resolve(template, request)` takes a
+trusted tenant id, actor, immutable permission snapshot, `AbortSignal`, explicit
+record bindings and optional values owned by the consumer. It validates the
+whole template before invoking a source. An unknown token, missing scope,
+missing binding, aborted request, unavailable record, or source failure is a
+refusal. Source exceptions are replaced with a generic error so SQL, provider,
+and record details do not cross the module boundary.
+
+The source declares `requiredBindings` per variable. For example, `party.name`
+requires `partyId`; the resolver receives that id explicitly and asks the
+parties public capability or read tool under `request.tenantId`. It never infers
+a record from browser state and never reads the parties database. Local form
+values go in `request.values`, while cross-module values must come from the
+registered resolver. The resolved text is returned to the server consumer only;
+the raw template remains stored.
+
+## Server-side resolution rule
+
+Resolve the template before the consumer sees it, and keep the raw template
+stored. The stored record keeps the `{{ }}` template; the run or send snapshot
+carries the resolved text. Never resolve in the client and never store the
+resolved text back onto the definition.
+
+Worked example in `agents.core`:
+
+- `modules/agents/src/domain/context-variables.ts` declares
+  `AGENT_CONTEXT_VARIABLES` (`context.tenantName`, `context.today`,
+  `context.user.displayName`, `context.user.email`, all scope-less) and
+  `agentContextValues(input)` that builds their values from the run's
+  tenant/principal/date.
+- `AgentService.enqueueRun` (`services/agent-service.ts`) resolves
+  `agent.instructions` with `resolveTemplate` against those values before it
+  builds the instruction snapshot; the stored definition is untouched. The
+  endpoint (`api/endpoints.ts`) supplies the tenant name and principal from the
+  request; `today` comes from the queue timestamp.
+- `AgentDefinitionForm.tsrx` feeds `VariableTextarea` the context variable list
+  and sample values, so an author gets the menu and highlighting.
+
+## Adding a variable source via a capability or tool
+
+Business-data variables (for example `{{ party.name }}`) resolve through a
+public capability or an agent read tool owned by the source module:
+
+1. Declare the `VariableDefinition` with `scope` equal to the source tool's
+   `requiredPermissions` (`AgentTool` in `packages/harness/src/runtime.ts`). The
+   tool's permission is the mask: one source of truth, no parallel table.
+2. Register the source on the shared registry during module composition. Declare
+   the record id in `requiredBindings`; do not accept a tenant binding.
+3. Offer it only through `registry.list(principal.scopes)`. The UI fields take
+   this already-filtered list and never fetch.
+4. Call `registry.resolve` on the server with the trusted tenant, actor,
+   permission snapshot, signal, and explicit bindings. The source invokes only
+   its owning public capability or read tool and maps the bounded result to
+   strings. The registry refuses before the source runs if the scope or binding
+   is absent.
+
+`automations.core` is the live cross-module example. `agent.name` requires the
+schedule's explicit `agentId`, and its resolver calls the `agents.run-queue`
+capability with the active tenant. A binding containing an agent from another
+tenant resolves to no record and the run is refused. The schedule keeps the raw
+template; only the queued run receives the resolved input.
+
+Register a new tool with the `agent-tool-design` skill; this skill covers only
+how its output becomes a resolvable variable.