@flowdular/sdk 0.1.0

package/.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.
+- Pinned: vitest 4.1.10, typescript 5.9.3, `@types/node` 24.13.3 (`.ai/references/catalog/package.json`).
+
+## 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/.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/.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.

package/.ai/skills/variables/SKILL.md

@@ -0,0 +1,164 @@
+---
+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.
+roles:
+  - frontend-engineer
+  - ux-designer
+  - agentic-engineer
+  - backend-engineer
+  - module-executor
+when: A field must let a value embed {{ variable }} tokens filled from other fields, the request context, or another module.
+---
+
+# 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.

package/.ai/skills/workflow-development/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: workflow-development
+description: >-
+  Build, publish, invoke, and test a workflows.core DAG through its typed graph
+  and public execution capability without bypassing agent, action, tenant, or
+  audit boundaries.
+roles:
+  - agentic-engineer
+  - backend-engineer
+  - frontend-engineer
+  - module-executor
+when: A brief asks for a workflow, pipeline, canvas node, workflow action, or a module feature that starts a workflow.
+---
+
+# Build and integrate an agentic workflow
+
+`workflows.core` owns durable directed acyclic workflows. A workflow coordinates
+pinned agent revisions, deterministic gates, schema validators, registered
+module actions, data mappings, and terminal output. It does not own schedules or
+webhook secrets. Those remain optional concerns of `automations.core`.
+
+Read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the contracts in
+`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+
+## Pick the correct extension point
+
+- A workflow definition belongs in `workflows.core` and is edited through its
+  API or canvas. Do not hardcode a tenant workflow in source.
+- A business operation that a workflow may call is a versioned agent action.
+  Register it through the agents action catalog. If missing, implement it in a
+  separate `agent-tool-design` phase with permission, input, output, timeout,
+  idempotency and audit tests before returning to workflow integration.
+- A business module that starts a workflow resolves
+  `workflows.execution.v1` from `context.capabilities`. It never imports a
+  workflow repository or database.
+- A schedule or signed webhook remains in `automations.core`. Its optional
+  bridge invokes the workflow capability with a service actor and a separate
+  schedule or webhook origin.
+- If the workflow module is absent, the capability registry returns `null`.
+  Hide an optional feature or return a clear stable refusal.
+
+## Graph contract
+
+Version one is a bounded DAG. The graph contains:
+
+- `input`: accepts the invocation envelope.
+- `agent`: calls one exact immutable agent revision and validates structured
+  output.
+- `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `gate`: evaluates the versioned allowlisted logic language.
+- `validator`: validates an envelope against a pinned JSON schema.
+- `action`: calls one exact registered action contract version.
+- `merge`: waits for all declared incoming paths.
+- `output`: settles the workflow with a typed result.
+
+Every port names a schema. Every edge connects compatible ports. Mappings are
+declarative literals, JSON pointer paths, or templates with explicit variable
+bindings. Never add JavaScript, dynamic imports, shell commands, downloaded
+code, arbitrary expressions, or hidden provider decisions to graph data.
+
+The hard limits live in `WORKFLOW_LIMITS` in
+`modules/workflows/src/domain/types.ts`. Validation must reject a cycle,
+dangling edge, unreachable node, missing terminal output, incompatible port,
+missing exact dependency, oversized graph, or unsupported action risk before
+publication.
+
+## Revisions and publication
+
+Draft saves use optimistic concurrency through `expectedRevision`. A successful
+save creates the next draft revision. A conflict never overwrites another
+editor.
+
+Publication:
+
+1. Validates and compiles the graph.
+2. Resolves exact agent revisions and exact action contract versions.
+3. Rejects missing, archived, incompatible, external, or destructive
+   dependencies.
+4. Stores an immutable content-addressed published revision.
+5. Leaves earlier revisions and their run evidence unchanged.
+
+Never replace a pinned dependency with its latest version during execution.
+Editing after publication creates another draft.
+
+## Execution modes
+
+Use the smallest mode that proves the change:
+
+- Dry-run validates a draft and returns issues, compiled order, references,
+  permissions, checksum, and limits. It creates no run and invokes nothing.
+- Simulation persists a run history but uses fixtures for nondeterministic
+  nodes. It advances virtual time without sleeping and never calls a provider,
+  action, or business mutation.
+- Live runs only published revisions. It may call pinned agents and approved
+  read or workspace-write actions under the initiating permission snapshot.
+
+Do not disguise simulation as live execution. Do not use live mode to test an
+invalid draft.
+
+## Invoke a published workflow from a module
+
+Resolve the capability at request or service call time, after platform
+composition has completed:
+
+```ts
+import {
+	WORKFLOW_EXECUTION_CAPABILITY,
+	type WorkflowExecutionCapability,
+} from '@flowdular/sdk/modules/workflows/server';
+
+const workflows = context.capabilities.get<WorkflowExecutionCapability>(
+	WORKFLOW_EXECUTION_CAPABILITY,
+);
+if (!workflows) throw new ModuleError('WORKFLOWS_UNAVAILABLE');
+
+const accepted = await workflows.enqueue(
+	{
+		workflowKey: 'catalog-enrichment',
+		input: { itemId },
+		idempotencyKey: `catalog:${itemId}:${version}`,
+	},
+	{
+		tenantId,
+		actor,
+		origin: {
+			kind: 'module',
+			moduleId: 'catalog.core',
+			operationId: 'catalog.enrichment.start',
+		},
+		permissionSnapshot,
+	},
+);
+```
+
+The module manifest declares `workflows.core` only when workflow support is a
+required feature. An optional integration belongs in a small bridge module that
+depends on both sides. Do not duplicate the capability interface locally to
+avoid a dependency declaration.
+
+Trusted context and business input are separate. Tenant, actor, origin, and
+permission snapshot never come from the request body. The idempotency key is
+stable for one logical operation. Reusing it with different input is a
+conflict, not a second run.
+
+## Actor and permission rules
+
+- A user action uses the real user actor.
+- A tool invoked by an agent uses the real agent actor and child run
+  correlation supplied by `AgentToolContext`.
+- A schedule or webhook uses a service actor whose `configuredBy` is the real
+  user who configured it. Origin stays `schedule` or `webhook`.
+- A workflow definition grants no scope. Live execution intersects the caller
+  snapshot with each node's agent or action requirements.
+- A cross-tenant id, foreign cursor, missing scope, absent dependency, or
+  mismatched action version is refused before data or provider work.
+
+## History, recovery, and cancellation
+
+The browser observes execution. It never owns execution. Enqueue persists the
+run before returning. Workers use leases and recover expired work from stored
+node state, child ids, and stable side-effect idempotency keys.
+
+Every transition appends an ordered schema-versioned event. Run, node,
+attempt, and edge states are separate projections. `pass` and `fail` are normal
+outcome ports, not technical statuses.
+
+Cancellation is durable and cooperative. It prevents new nodes, asks the
+current child agent or action to cancel, records whether it acknowledged, and
+ignores late output for routing while keeping its safe evidence.
+
+History responses contain redacted bounded evidence. They never expose provider
+credentials, session tokens, hidden reasoning, encrypted payload blobs, or
+unrestricted request bodies.
+
+## Required tests
+
+For a graph or runtime change, prove:
+
+1. Deterministic compile order and rejection of cycles, dangling edges,
+   incompatible ports, unreachable nodes, and missing output.
+2. Tenant isolation plus one unauthenticated and one unscoped refusal for every
+   endpoint group.
+3. Exact agent and action revision refusal with no latest-version fallback.
+4. Dry-run produces no run, provider call, action call, or business write.
+5. Simulation uses fixtures and virtual duration with no real wait.
+6. Live enqueue is idempotent and persists before acceptance.
+7. Recovery before and after child enqueue does not duplicate work.
+8. Retry records the chosen delay before waiting and reuses the side-effect
+   idempotency key.
+9. Cancellation prevents downstream work and records late results safely.
+10. Event replay, cursor binding, payload redaction, retention, usage, cost,
+    and audit hash-chain integrity.
+11. The canvas shows validation, loading, empty, error, denied, simulation,
+    live, cancelled, and recovered states, including small-screen read mode.
+
+Run the module typecheck and tests, `pnpm flowdular module validate`, then the
+full `pnpm verify`. For a new module integration, update its approved spec and
+move `specVersion`, `module.json` version, and package version together.