@flowdular/sdk 0.1.0

package/AGENTS.md

@@ -0,0 +1,59 @@
+<!-- Source: .ai/rules/flowdular.md. Run pnpm rules:generate; never edit generated copies. -->
+
+# Flowdular
+
+An agentic foundation that businesses extend with their own modules.
+
+## One task, one skill
+
+Choose the most specific task in `.ai/skills/README.md` and read only that
+`.ai/skills/<name>/SKILL.md`. Announce the choice briefly. For a multi-part
+request, finish one bounded phase before switching skills. Do not recursively
+load other skills mentioned by a skill. Read referenced code or documentation
+only when the current task needs it. Explicit user instructions take priority.
+
+Sandbox: use the single skill named under Session, at
+`reference/skills/<name>/SKILL.md`. Follow the role's write paths and handoff list.
+Do not load the whole skill catalog into the task context.
+
+## Always-active invariants
+
+1. Stay within the requested scope. Preserve other agents' edits. Read the owning
+   code before changing it. Do not invent missing business decisions.
+2. Spec-first: a new module requires an approved `spec/module.yaml`. Sandbox
+   implementation requires operator approval of the exact current spec hash;
+   any spec change invalidates it. Never infer or grant approval yourself.
+   Only explicit user approval naming a spec permits the host `spec-approval` action.
+3. Deny by default. Use `defineEndpoint`, an explicit permission and identity
+   resolver. Mutations enforce CSRF and bounded input validation.
+4. Tenant identity comes from the authenticated principal, never request input.
+   Use bound SQL, tenant predicates and `transaction(..., { tenantId, access })`.
+   Tenant tables enforce RLS with `USING` and `WITH CHECK`. Runtime roles have
+   neither superuser nor `BYPASSRLS`; migration leases are for DDL only.
+5. Never expose credentials in output, logs or audit. Cross-module access uses
+   declared public capabilities or registered tools, never another module's DB.
+   Agent instructions cannot expand permissions or tool grants.
+6. Persist background work before acknowledging it. Preserve idempotency,
+   leases, recovery and audit evidence. Drain async work before releasing resources.
+7. Applied migrations are immutable. Add numbered PostgreSQL SQL and mirror it
+   byte for byte in `databaseMigrations`. Never bypass checksum or adoption checks.
+8. Generated composition is CLI-owned: `platform/octane.config.ts`,
+   `platform/src/App.tsrx`, `platform/src/generated/**`, platform package
+   dependencies and `flowdular.json` enabled modules. Use `module enable/sync --apply`.
+   Declare imports and dependencies; keep module, package and spec versions aligned.
+9. Use shared `@flowdular/ui` components and tokens. Keep all locales in sync.
+   UI states: loading, empty, error, populated, denied. Inspect rendered UI after changes.
+10. Prove fixes with regression tests. Never skip assertions, weaken isolation or
+    hide errors to make gates green. Run scoped checks, then `pnpm verify` before a PR.
+    Finish implementation, then run the `auto-review` skill as a separate phase
+    before completion or delivery. Report actual results and remaining failures.
+11. Destructive actions require the runner's flags and explicit scope.
+    `setup quick` and `auth greenfield` are local resets: preview, stop the app,
+    never target a custom or deployed DB. Sandbox agents cannot install, use
+    network/git, or touch a DB outside their module tests.
+12. Keep handoffs short and factual. No AI attribution footers or em/en dashes.
+    Sandbox final line: `HANDOFF: <allowed-role> - <why>` or
+    `HANDOFF: none - <why>`, never your own role.
+
+Detailed recipes: `docs/agent-contract.md` (lookup only).
+Reference module: `.ai/references/catalog`; visual contract: `docs/design-system.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowdular contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# Flowdular SDK
+
+One npm package for the Flowdular platform. Import the surface you need:
+
+```ts
+import { defineEndpoint } from '@flowdular/sdk/server';
+import type { ModuleManifest } from '@flowdular/sdk/contracts';
+import { Button } from '@flowdular/sdk/ui';
+import '@flowdular/sdk/ui/styles';
+```
+
+Exports include `client`, `server`, `ui`, `contracts`, `kernel`, `database`,
+`database-pglite`, `database-testing`, `harness`, `ai-provider`, `coding-agent`,
+`cli-protocol`, `dev-console`, `sandbox` and `modules/<name>` for bundled core modules.
+Subpaths retain their own exports, such as `modules/auth/server` and `client/i18n`.
+There is no root barrel importing server code into browser entrypoints.
+
+The SDK ships TypeScript and TSRX source for the Flowdular/Octane build toolchain.
+Create a configured workspace with `npm create flowdular@latest my-app`.
+The CLI is published separately as `flowdular`.
+
+Source packages remain separate private workspaces in the repository. Release
+assembly copies the declared members, rewrites internal imports to SDK subpaths,
+and exposes their original entrypoints. Only the assembled SDK is published.

package/docs/agent-contract.md

@@ -0,0 +1,45 @@
+# Agent implementation reference
+
+Lookup only. The always-active contract lives in `.ai/rules/flowdular.md`.
+Use one task skill; consult only the relevant section here, not the whole file.
+
+Flowdular is an agentic foundation framework. It ships the foundation platform (accounts, workspaces, permissions, modules, agents runtime, CLI, sandbox) and people build their own platform on top of it: in the sandbox with AI specialists, or with the skills in `.ai/skills` inside their own coding tool. This contract and the skills are the shared RuleSync sources for every supported coding agent. Spec-first is a working rule here: a module is created only from an approved `spec/module.yaml`.
+
+Use the already selected task skill. Consult `.ai/references/catalog` for implementation examples and `docs/design-system.md` for visual work only when the current task needs them.
+
+## Rules
+
+1. Read the owning code end to end before changing it. Copy the shape of `.ai/references/catalog`; do not invent architecture, permissions, entities, routes, or dependencies. Stop when required input is missing or contradictory and say exactly what you need.
+2. Write only inside the paths your role or blueprint names. In the sandbox these paths are advisory; a reviewer treats a write elsewhere as a defect.
+3. Identifiers: module, permission and capability ids match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`. `inventory.core` lives in `modules/inventory` as `@flowdular/module-inventory`; permissions are `<module>.<entity>.read` and `<module>.<entity>.manage`.
+4. A module is created only from a spec with `status: approved`. An agent never initiates, infers, or grants approval from its own judgment. After a current, explicit user instruction naming the spec, a host coding agent may record that decision mechanically by following `spec-approval`; a sandbox specialist can only request approval, and the operator route records the exact approved hash. Spec `permissions[].id` equal the constants in `src/acl/permissions.ts`: the spec is what `auth sync-scopes` grants.
+5. Every endpoint is `defineEndpoint` from `@flowdular/sdk/server` with `access: { kind: 'permission', permission }` and `resolveIdentity: endpointIdentityFromContext`. Deny by default; a public endpoint needs a written reason. No raw `new ServerRoute` outside `modules/auth`.
+6. The tenant id comes only from `principalFromContext(octane)!.tenantId`, never from the body, query or headers. Every query on a tenant-owned table filters by `tenant_id`; unique constraints and indexes start with `tenant_id`; SQL uses bound parameters. PostgreSQL tenant tables also enable and force row-level security with `USING` and `WITH CHECK` policies bound to transaction-local `coreloom.tenant_id`. Every repository operation runs through `database.transaction(..., { tenantId, access })`; the runtime role is never a superuser and never has `BYPASSRLS`, while a separate migration lease may own DDL. `WHERE tenant_id = ...` remains defense in depth.
+7. Every mutation calls `sessionMutationDenial(octane, auth)` first and reads its body with `readJsonObject` plus `requiredString`, `optionalString`, `requiredInteger`. Clients send `content-type: application/json`, `x-csrf-token`, and `credentials: 'same-origin'`.
+8. Routes mount only through `src/platform.ts` exporting `createServerComposition(context)` with `platform.server: true` in `module.json` and a `./platform` export in `package.json`; the context carries `auth`, `settings`, `agentTools`, `agentDefinitions`, `capabilities` and `databases`. A database module passes `context.databases` into one runtime, which acquires and releases one provider lease lazily; `prepare` stays read-only and never opens a database. A composition may return `settings`, read-only `prepare`, `start`, background-work `stop`, and final `dispose`. Client contributions mount only through `createClientContribution(context)` in `src/client/index.ts` with `platform.client: true`. `pnpm flowdular module validate` fails on a missing entry (`PLATFORM_*`).
+9. Never edit the composition by hand: `platform/octane.config.ts`, `platform/src/App.tsrx`, `platform/src/generated/**`, `platform/package.json` dependencies and `modules.enabled` in `flowdular.json` are written by `pnpm flowdular module enable <id> --apply` and `pnpm flowdular module sync --apply`.
+10. `pnpm flowdular module enable <id> --apply` grants the spec permissions to every tenant owner as its last step; `pnpm flowdular auth sync-scopes --module <id> --apply` re-grants later (new permission, another database). Members receive scopes only through `MEMBER_SCOPES` in `modules/auth/src/acl/scopes.ts`, a core change.
+11. Declare every imported package in the module `package.json`; the sandbox `dependencies` gate and the eject fail otherwise. Every relative import carries its `.ts` or `.tsrx` extension.
+12. Use the CLI for discovery, validation and scaffolding: `doctor`, `spec validate`, `module validate`, `module new`, `module enable`, `auth sync-scopes`. Run destructive, external or production capabilities only with what the runner demands (`--apply`, `--confirm`, `--spec`) and never work around a refusal.
+13. Gates are `spec-schema`, `module-schema`, `dependencies`, `typecheck`, `tests`, `format`. The sandbox runs `dependencies` plus the ones your role lists after every turn, per draft module, and feeds a failure back to you; with a shell you may run the module's own gate commands yourself, never installs, network or git. From a checkout run them yourself and `pnpm verify` before any pull request.
+14. Build UI only from `@flowdular/sdk/ui` components, `ui-*` classes and tokens (`docs/design-system.md`). No hardcoded colors, fonts or sizes; never restyle a `ui-*` class; `glyph` and `Icon name` are `ICON_PATHS` keys. Modules use the shared `Table` and `TableCard`, which are backed by the official Octane TanStack adapter; they never import `@octanejs/tanstack-table` directly. A missing primitive becomes a module-local component on tokens, flagged as a promotion candidate. Guard UX: no visual artifacts. A card head is one line (title left; search and the `Filters` dropdown right), filters live inside `Filters` not loose in the head, form rows top-align so a `help` line never drops its neighbour, a field is labelled once, no decorative tags, long values use `ui-mono`/`ui-table-wrap`, adjacent top-level nodes go in a fragment. Look at the rendered screen before handing off and fix any alignment, wrapping, padding or duplicated-label glitch.
+15. One screen, form, table or stateful region per named component. Records own the page; create and edit happen in a `Drawer`. Every screen shows loading, empty, error, populated and denied.
+16. Tests live in `tests/*.test.ts`: identity, tenant isolation, uniqueness, one 401 and one 403 per endpoint, each validation bound. Repository behavior uses `createTestDatabaseProvider()` from `@flowdular/sdk/database-testing`: PGlite locally and isolated server PostgreSQL in CI. Open one provider per test file, migrate once, and truncate module tables between cases (`modules/profile/tests/support/database.ts`). Tenancy tests use two tenants, prove `TENANT_CONTEXT_REQUIRED` without a transaction tenant id, prove RLS prevents cross-tenant reads and writes under the non-bypass runtime role, and cover `WITH CHECK`. Tenant fixture work also supplies tenant context on a migration connection. The sandbox `tests` gate passes with zero tests, so an empty suite is a defect.
+17. Translations are live. Every module contribution registers all declared `translations/*.json` bundles, user-facing copy uses fully qualified `t('<module>.<key>')` keys, navigation labels are lazy getters, locale-aware formatting uses `activeLocale()`, and every locale has the same key set. `module validate` rejects missing files, key drift, and missing static translation keys.
+18. Numbered migration SQL is immutable source. `migrations/000N_<module>_<name>.up.sql` and `.down.sql` are PostgreSQL and the only schema source; there is no dialect subdirectory. `src/services/migration.ts` mirrors every `.up.sql` byte for byte as `databaseMigrations: readonly DatabaseMigration[]` with `sql: { postgresql: ... }`, and the runtime calls `runDatabaseMigrations` through its provider lease. The namespaced `_coreloom_migrations_v2` ledger records the checksum, adopts only an explicit complete `inspectExisting` result (`postgresTenantTableState` is the standard check), and refuses drift, duplicates, or partial schema. Add a new numbered, additive migration instead of changing existing bytes. A tenant table's migration includes enabled and forced RLS plus a tenant policy, with the policy behavior covered by tests.
+19. Module CLI commands live in `src/cli/commands.json` and `src/cli/index.ts`, metadata-identical, inside the module namespace.
+20. Passwords, session tokens and provider credentials never leave `auth.core` (or the `agents.core` vault) and never appear in logs, audit metadata or responses.
+21. `setup quick` and `auth greenfield` are destructive local resets. Preview first, stop the app, never point them at a custom or deployed database.
+22. Agent workers reach ERP data only through registered API or CLI tools. A module defines them with `defineApiAgentTool` or `defineCliAgentTool` from `@flowdular/sdk/harness/tool-adapters` and registers them inside `createServerComposition` with `context.agentTools.register([...])`; nothing else registers a tool. A module may also ship business agents with `defineAgent()` from `@flowdular/sdk/modules/agents/server` and `context.agentDefinitions.register([...])` after declaring an `agents.core` dependency. Their code allowlist is only a maximum: effective tools are the exact intersection of that allowlist, the tenant binding reduction, invocation grants, registered tool permissions, the actor's saved permission ceiling, and live authorization. Sandbox coding specialists are not business agents.
+23. A background run is persisted before enqueue returns; idempotency, leases, recovery, tenant scoping and append-only audit evidence for every fire-and-forget run.
+24. Module settings are declared with `defineModuleSettings` from `@flowdular/sdk/kernel`, returned as `settings` from the composition, read live with `context.settings.get(tenantId, '<module>.core', key)`, and rendered in that module's drawer under Administration, Modules. User-facing setting copy declares fully qualified `labelKey` and `descriptionKey` present in every module locale, with English `label` and `description` literals as compatibility fallbacks. Values, identifiers and secrets are never translated. Administration, Settings is only for workspace and organization settings. A cross-module setting read needs a declared dependency and a `shared`, non-secret setting. Cross-module operations use a typed public service registered in `context.capabilities` by the owning module and resolved by a declared dependent, never the other module's database.
+25. `Development` navigation is owner-only in the client; server permissions remain authoritative.
+26. Generated files are production code: no placeholders, silent fallbacks or skipped tests. `module.json` `version`, spec `specVersion` and `package.json` `version` move together.
+27. Commits and pull requests: short body, one line on verification, no AI attribution footers, generated files only through the CLI. Never use em or en dashes in anything you write.
+28. End a sandbox turn with one line: `HANDOFF: <role-id> - <why>` or `HANDOFF: none - <why>`. The role must be in your role's `handoff` list and never yourself; otherwise the sandbox routing decides.
+
+## Sequence
+
+Sandbox: brief, planner picks all affected modules and the first role, specification or spec delta per module, operator approval of each exact spec hash, specialist turns with gates per changed module, scaffold when needed, eject (fresh spec-hash check, gates, copy and removals, `pnpm install`, `module enable` with scope grant for new modules, `auth sync-scopes`, platform typecheck, restart note), pull request. A host agent may invoke the operator approval action only after the user explicitly delegates that exact approval through `spec-approval`.
+
+Checkout: read the skill, approved spec, `module new` dry run then `--apply`, implement, gates, `module enable --apply` (grants scopes), `pnpm verify`, pull request.

package/docs/design-system.md

@@ -0,0 +1,217 @@
+# Flowdular design system
+
+Identity 1.0 (2026-08-31). The implementation reference for humans and agents:
+shared primitives, tokens, and the rules for using them.
+
+## Where things live
+
+- `packages/ui` (`@flowdular/sdk/ui`): the only source of visual primitives.
+  Design tokens (`src/styles/tokens.css`), base styles, `ui-*` component
+  classes, TSRX components, icons, and the brand mark. Fonts (IBM Plex Sans
+  Variable, IBM Plex Mono) are self-hosted through `@fontsource` packages.
+- `packages/client`: the application shell (sidebar, topbar, command palette,
+  dashboard, contribution outlets). Shell-only layout lives in
+  `src/shell/shell.css`.
+- Modules: compose screens from `@flowdular/sdk/ui`. Module CSS may only add
+  module-specific composites built on the tokens (example:
+  `modules/agents/src/client/agents.css`).
+- `platform/public`: `favicon.svg`, `og.png` (1200x630 Open Graph image).
+- Brand mark geometry is generated: `node packages/ui/scripts/gen-mark.mjs`
+  rewrites `packages/ui/src/brand/mark.ts` from the weave parameters.
+
+## Rules
+
+1. Primitives first. Use a `ui-*` class or an exported component before
+   writing any new visual code.
+2. Colors, fonts, sizes, radii, and shadows come only from tokens
+   (`var(--...)`). No hex values in shell or module CSS.
+3. Never restyle or override a `ui-*` class outside `packages/ui`.
+4. A missing primitive is added per use case as a module-local component built
+   on the tokens, and flagged as a promotion candidate for `packages/ui`.
+5. Blue means action and selection. Green, amber, and red mean state. Copper
+   is reserved for the brand (mark, splash, sign-in) and is never a button or
+   a state color.
+6. Minimum text size is 12 px (`--text-sm`); labels use `--text-xs` uppercase.
+   Numbers in tables and KPIs are tabular (`.num`, `ui-kpi__value`).
+7. Layout containment is owned by the primitives, not by the screen. Children
+   of `ui-view`, `ui-two-col`, `ui-grid-2`, and `ui-kpi-grid` are shrinkable
+   tracks, long words wrap, and the workspace never scrolls horizontally. Wide
+   content scrolls inside its own container (`ui-table-wrap`), so one long
+   value can never push the page sideways.
+8. `Kpi` is a stat tile. Its value is a number or a short state word; addresses,
+   identifiers, and paths belong in `note` or a `ui-mono` line.
+9. A screen never splits its width between records and a form. Records own the
+   page; creating and editing happens in a `Drawer`.
+10. `Tag` carries state or a value with meaning (a status, a count, a scope).
+    Never decoration: no "Secure", "Master data", or "Suggested setup" badges.
+    A card head is a title, a one-line description in its `small`, and at most
+    one right-aligned cluster (`ui-card__actions`: a count, a state, buttons).
+11. A row is title and description on the left and its controls on one line on
+    the right, vertically centered (`SettingRow`). The row title is the label;
+    the control inside carries `aria-label`, never a second visible label.
+12. Large sets are summarized where they are read (`ScopeSummary`, grouped by
+    module) and edited in full only inside the drawer (`CheckGrid`).
+13. Destructive actions close a drawer in their own `ui-form__section--danger`:
+    one title, one line of consequence, one `Button variant="danger"`. They are
+    never mixed into a status row.
+14. Menus (workspace switcher, account menu, session actions) are `ui-menu`
+    with `ui-menu__item` rows: 40 px, 10 px inset, the same hover and selected
+    background, a 32 px avatar, two lines of text, and the trailing check
+    pushed to the right edge.
+
+## Screen pattern
+
+Every record screen is built the same way, so a user who learns one learns all
+of them:
+
+```text
+PageHeader        eyebrow, title, description, [Refresh] [+ New ...]
+Alert             only when the last action failed
+TableCard
+  ui-card__head   title, count, SearchField and Filters on one line
+  Table           the records, full width
+  ui-note         the constraint worth stating (permissions, boundaries)
+Drawer            the create or edit form, opened from the header or a row
+```
+
+`TableCard` is the default for a record screen. It owns the card, the one-line
+head (title, `count`, and the `search` and `filters` slots inside
+`ui-card__filters`), the `Table`, and the optional `ui-note` footer, so every
+screen shows the same head, loading row, empty state, and filtered-empty
+message. A screen passes data and slots, never table markup. Row actions are
+compact, visible buttons in a narrow trailing column with an accessible but
+visually empty header. The column is part of the same `colgroup` in loading,
+empty and populated states, so widths do not drift. `Table` on its own covers
+what needs a bare table, such as the list side of a master-detail screen.
+
+`Table` is backed by the official `@octanejs/tanstack-table` adapter. Modules
+still use the smaller Flowdular `Table` and `TableCard` contract from
+`@flowdular/sdk/ui`; they never import TanStack directly. The shared primitive owns
+the TanStack features, row model, header model and cell rendering so every
+screen keeps the same states, widths and actions.
+
+Every column declares a semantic CSS `width`. Give the primary record and its
+description the largest share, medium shares to dates and identifiers, and the
+smallest share to counts and lifecycle state. In a table with row actions, data
+columns normally add up to about 90 percent; the shared 160 px action column
+uses the rest. In a read-only table, data columns add up to 100 percent. The
+table keeps these widths in loading, empty and populated states and scrolls
+horizontally below its minimum readable width.
+
+The drawer holds one `ui-drawer__form`: fields scroll inside
+`ui-drawer__body`, and the primary action stays pinned in `ui-drawer__foot`.
+Escape and the scrim close it. Master-detail screens that only read (agent runs,
+the playground) keep `ui-two-col`; the list side is a `ui-table` whose open
+record carries `is-selected`.
+
+A drawer that edits several independent things (a member, a module) stacks
+`ui-form__section` blocks inside its `ui-form`: an uppercase title and one-line
+description in `ui-form__section-head`, then the fields and a right-aligned
+`ui-form__actions` row with one primary per section. An input paired with one
+action (a temporary password and its Reset) sits in a `ui-control-row`. The
+danger section comes last, and the foot then keeps only Close.
+
+Administration > Settings holds only workspace settings: full-width cards
+(Workspace, Preferences), each `SettingRow` one setting. A module's declared
+settings are edited in its Drawer under Administration > Modules, as
+`SettingRow`s inside the drawer's Settings `ui-form__section`; a module
+without settings shows a one-line empty state there.
+
+## Components
+
+| Component          | Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Button`           | Actions: `variant` primary, secondary (default), ghost, danger; `size` sm, md, lg; `block`                                                                                                                                                                                                                                                                                                                                                                                |
+| `FormField`        | Label + control + help or error. Put `ui-input`, `ui-select`, or `ui-textarea` inside                                                                                                                                                                                                                                                                                                                                                                                     |
+| `VariableTextarea` | Multiline template field: `value`, `onInput`, `variables` (scope-filtered `VariableDefinition[]`), `sampleValues`, `label`, `name`; a `braces` menu inserts `{{ key }}` and tokens highlight as pills (error pill when unknown). Presentational, never fetches                                                                                                                                                                                                            |
+| `VariableInput`    | Single-line variant of `VariableTextarea` with the same props                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `VariableSelect`   | Native select that stores either a literal option value or one allowed `{{ key }}` token. Takes scope-filtered `variables`, `sampleValues`, literal `options`, `value`, `onInput`, `name`, `label`, and native required/disabled state. It preserves keyboard, validation, accessibility, and `FormData` semantics and never fetches or resolves data                                                                                                                     |
+| `Tag`              | Status and metadata: `tone` neutral, success, warning, danger, info, ink; `dot` adds a state dot; `mono`                                                                                                                                                                                                                                                                                                                                                                  |
+| `Kpi`              | Stat tile: `label`, `value`, `unit`, `badge`, `note`, `href`, `linkLabel`                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `Chart`            | Token-driven Chart.js wrapper on a client-only canvas: `type` area, bar, line; `data`, `series` (`key`, `label`, `token`), `xKey`, `height`, `title`, `xTickFormatter`; series colors come from `--chart-1..5`; shows an EmptyState for empty or all-zero data                                                                                                                                                                                                            |
+| `Table`            | The one data table, backed by `@octanejs/tanstack-table`: `columns` (`key`, `header`, required `width`, `numeric`, `cell`), `rows`, `rowKey`, `status` idle/loading, `loadingLabel`, `empty` and `emptyFiltered` picked by `filtered`, `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px by default, 280 px for two actions), `onSelect` with `selectedKey`, `caption`; fixed layout and `colgroup` keep columns stable across states |
+| `TableCard`        | The record card around `Table`: `title`, `count`, the `head`, `search`, and `filters` head slots, `before` and `after` around the table, `note` with `noteIcon` as the footer                                                                                                                                                                                                                                                                                             |
+| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions                                                                                                                                                                                                                                                                                                                                                                       |
+| `EmptyState`       | `icon`, `title`, children, optional `code`                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `Alert`            | Inline message: `tone` danger (default), warning, info                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `Drawer`           | Editor panel over the records: `open`, `title`, `subtitle`, `width` md/lg, `onClose`                                                                                                                                                                                                                                                                                                                                                                                      |
+| `SearchField`      | Filter control for a panel head: `value`, `placeholder`, `label`, `onInput`                                                                                                                                                                                                                                                                                                                                                                                               |
+| `CheckGrid`        | Grouped multi-select for scopes, tools, and long option sets: `groups` (`label`, `options` of `value`, `label`, `hint`), `value`, `mono`, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                          |
+| `ScopeSummary`     | Read-only summary of `module.entity.action` scopes: one row per module, one chip per entity with its actions: `scopes`, `labels` (module id to display name)                                                                                                                                                                                                                                                                                                              |
+| `SettingRow`       | One setting: `label`, `description` (node, one line), `scopeLabel` (small neutral tag), `status` (`ok`, `message` of the last save), children as the control cluster                                                                                                                                                                                                                                                                                                      |
+| `Avatar`           | Initials from `name`: `square` for organizations, round for people; `large` in profile and account headers                                                                                                                                                                                                                                                                                                                                                                |
+| `Switch`           | Boolean setting that applies on its own (no form submit): `checked`, `label` as the accessible name, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                                                               |
+| `ConfirmDialog`    | One question before an irreversible action: `open`, `title`, children, `confirmLabel`, `tone` danger (default) or primary, `busy`, `onConfirm`, `onCancel`                                                                                                                                                                                                                                                                                                                |
+| `Icon`             | Stroke icon by `name` from `ICON_PATHS`; `size` 18 default, 16 in controls, 14 in `Button size="sm"`; `strokeWidth` 1.75 default                                                                                                                                                                                                                                                                                                                                          |
+| `BrandMark`        | The weave: `size`, `signature` (copper weft, large brand moments only), `tone` brand, current, inverse                                                                                                                                                                                                                                                                                                                                                                    |
+
+`Drawer` takes one child, a `ui-drawer__form` (fields in `ui-drawer__body`, actions in `ui-drawer__foot`) or a plain `ui-drawer__body`; it closes on Escape and on the scrim. `SearchField` carries no visible label, so pass `label` as its accessible name. `FormField` renders `error` in place of `help` and marks it `role="alert"`. `SettingRow` is presentation only: the caller owns the draft value, the save call, and passes the result back as `status`. `ScopeSummary` is the read side of `CheckGrid`; both keep the first-seen module order, and `summarizeScopes` is exported for callers that need the grouping without the markup.
+
+Icon names (`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` without a warning; a new icon is one 24x24 stroke path added there.
+
+## Classes
+
+- Layout: `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`,
+  `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (an `h2` with actions
+  inside a view)
+- Surfaces: `ui-card` (+`__head`, `__title` with a `small` description,
+  `__actions` for the right-aligned cluster, `__body`), `ui-toolbar`
+  (+`__spacer` to push actions right; a bare `ui-input` or `ui-select` inside
+  it takes the button height and an `aria-label`)
+- Data: `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__actions`
+  for the component-owned trailing button column, `ui-table__state` for a dot plus label,
+  `ui-table__placeholder` for the loading and empty rows inside the table,
+  `.num`, row states `is-clickable` and `is-selected`), `ui-cell`
+  (+`ui-cell__muted`), `ui-mono`, `ui-code`
+- Forms: `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`, `__section`
+  with `__section-head` (`b` title, `small` description) and
+  `__section--danger`), `ui-control-row` (a growing control beside one fixed
+  button), `ui-choices` (a short wrapping row of `ui-checkbox`), `ui-input`
+  (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`,
+  `ui-label`, `ui-help` (+`--error`)
+- Drawer: `ui-drawer__form` (scrolling body plus pinned footer),
+  `ui-drawer__body`, `ui-drawer__foot`
+- Settings rows inside a `ui-card` or a drawer `ui-form__section`, rendered
+  by `SettingRow`: `ui-setting`
+  (+`__text` for title, scope tag, and help, `__control` for the one-line
+  control cluster, `__status` (+`--error`) for the inline result)
+- Buttons: `ui-btn` with `--primary`, `--secondary`, `--ghost`, `--danger`,
+  `--sm`, `--lg`, `--block`, and `--icon` for an icon-only square button
+  (the `Button` component renders all but `--icon`)
+- Bits: `ui-kbd`, `ui-dot` (+`--muted`), `ui-note`, `ui-menu` (+`__label`,
+  `__section` for a static identity or connection block, `__item`,
+  `__item--active`, `__item--danger`, `__sep`), `ui-icon`
+
+Rendered by components, not written by hand: `ui-page-head*`, `ui-search`,
+`ui-field`, `ui-switch` (+`--on`), `ui-dialog` (+`__panel`, `__title`,
+`__body`, `__actions`), `ui-empty` (+`__icon`), `ui-alert` (+`--danger`, `--warning`,
+`--info`), `ui-tag` (+tone and `--mono`), `ui-kpi` (+`__label`, `__value`,
+`__note`, `__link`), `ui-avatar` (+`--sq`, `--lg`), `ui-checks` (+`__group`,
+`__head`, `__count`, `__all`, `__items`, `__option`), `ui-scopes` (+`__row`,
+`__chip`), `ui-drawer-slot`, `ui-drawer` (+`__panel`, `__panel--lg`, `__head`,
+`__close`), `ui-varfield` (+`__control`, `__highlight`, `__input`, `__pill`
+(+`--error`), `__trigger`, `__menu`, `__value`, `__empty`; the overlay layer
+that highlights `{{ key }}` tokens, rendered by `VariableTextarea` and
+`VariableInput`).
+
+## Token cheat sheet
+
+- Surfaces: `--bg`, `--surface`, `--surface-2`; lines: `--line`, `--line-2`
+- Text: `--ink`, `--ink-2` (labels), `--ink-3` (descriptions), `--ink-4`
+  (placeholders only, below AA for text)
+- Action: `--primary`, `--primary-hover`, `--primary-soft`, `--primary-tint`,
+  `--focus`
+- State: `--success`, `--warning`, `--danger` with `-bg` and `-line` pairs
+- Brand: `--brand`, `--brand-weft` (copper)
+- Type: `--font-sans`, `--font-mono`, `--text-xs` 11 to `--text-display` 36
+- Dimensions: `--sidebar-w` 260, `--rail-w` 60, `--topbar-h` 52, `--control-h`
+  36, `--button-h` 32, `--row-h` 44, radii `--r-sm` 4, `--r` 6, `--r-md` 8,
+  `--r-lg` 12
+
+Components reference the semantic layer only, so a dark theme is one token
+override block, not a rewrite.

package/modules/agents/migrations/0001_agents_core.down.sql

@@ -0,0 +1,4 @@
+DROP TABLE IF EXISTS agent_audit_events;
+DROP TABLE IF EXISTS agent_run_events;
+DROP TABLE IF EXISTS agent_runs;
+DROP TABLE IF EXISTS agent_definitions;

package/modules/agents/migrations/0001_agents_core.up.sql

@@ -0,0 +1,106 @@
+CREATE TABLE IF NOT EXISTS agent_definitions (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  agent_key TEXT NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT NOT NULL,
+  instructions TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  model TEXT NOT NULL,
+  allowed_tools_json TEXT NOT NULL,
+  max_steps INTEGER NOT NULL CHECK (max_steps BETWEEN 1 AND 32),
+  timeout_ms BIGINT NOT NULL CHECK (timeout_ms BETWEEN 250 AND 300000),
+  temperature_milli INTEGER NOT NULL CHECK (temperature_milli BETWEEN 0 AND 2000),
+  status TEXT NOT NULL CHECK (status IN ('draft', 'active', 'paused', 'archived')),
+  revision INTEGER NOT NULL CHECK (revision >= 1),
+  created_by TEXT NOT NULL,
+  created_at BIGINT NOT NULL,
+  updated_by TEXT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, agent_key)
+);
+CREATE INDEX IF NOT EXISTS agent_definitions_tenant_name_idx ON agent_definitions (tenant_id, name, id);
+
+CREATE TABLE IF NOT EXISTS agent_runs (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  agent_name TEXT NOT NULL,
+  agent_revision INTEGER NOT NULL,
+  instructions_snapshot TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  model TEXT NOT NULL,
+  allowed_tools_json TEXT NOT NULL,
+  max_steps INTEGER NOT NULL,
+  timeout_ms BIGINT NOT NULL,
+  temperature_milli INTEGER NOT NULL,
+  trigger TEXT NOT NULL CHECK (trigger IN ('playground', 'workflow', 'service', 'schedule')),
+  status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')),
+  input TEXT NOT NULL,
+  output TEXT,
+  requested_by TEXT NOT NULL,
+  permission_snapshot_json TEXT NOT NULL,
+  tool_grants_json TEXT NOT NULL,
+  usage_json TEXT,
+  failure_code TEXT,
+  failure_message TEXT,
+  idempotency_key TEXT,
+  attempt INTEGER NOT NULL DEFAULT 0,
+  queued_at BIGINT NOT NULL,
+  started_at BIGINT,
+  completed_at BIGINT,
+  lease_owner TEXT,
+  lease_expires_at BIGINT,
+  FOREIGN KEY (agent_id) REFERENCES agent_definitions(id),
+  UNIQUE (tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS agent_runs_tenant_queued_idx ON agent_runs (tenant_id, queued_at DESC, id);
+CREATE INDEX IF NOT EXISTS agent_runs_recovery_idx ON agent_runs (status, lease_expires_at, queued_at);
+
+CREATE TABLE IF NOT EXISTS agent_run_events (
+  run_id TEXT NOT NULL REFERENCES agent_runs(id) ON DELETE CASCADE,
+  tenant_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  event_type TEXT NOT NULL,
+  message TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  PRIMARY KEY (run_id, sequence)
+);
+
+CREATE TABLE IF NOT EXISTS agent_audit_events (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  subject_type TEXT NOT NULL CHECK (subject_type IN ('agent', 'agent-run')),
+  subject_id TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  previous_hash TEXT,
+  event_hash TEXT NOT NULL,
+  UNIQUE (tenant_id, sequence),
+  UNIQUE (tenant_id, event_hash)
+);
+CREATE INDEX IF NOT EXISTS agent_audit_tenant_time_idx ON agent_audit_events (tenant_id, occurred_at DESC, sequence DESC);
+ALTER TABLE agent_definitions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_definitions FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_definitions_tenant_policy ON agent_definitions
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+ALTER TABLE agent_runs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_runs FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_runs_tenant_policy ON agent_runs
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+ALTER TABLE agent_run_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_run_events FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_run_events_tenant_policy ON agent_run_events
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+ALTER TABLE agent_audit_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_audit_events FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_audit_events_tenant_policy ON agent_audit_events
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/agents/migrations/0002_provider_connections.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_provider_connections;

package/modules/agents/migrations/0002_provider_connections.up.sql

@@ -0,0 +1,34 @@
+CREATE TABLE IF NOT EXISTS agent_provider_connections (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  provider_key TEXT NOT NULL,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('vercel', 'azure', 'openai', 'openai-compatible', 'anthropic')),
+  enabled INTEGER NOT NULL CHECK (enabled IN (0, 1)),
+  resource_name TEXT,
+  base_url TEXT,
+  models_json TEXT NOT NULL,
+  credential_key_id TEXT NOT NULL,
+  credential_iv TEXT NOT NULL,
+  credential_tag TEXT NOT NULL,
+  credential_ciphertext TEXT NOT NULL,
+  credential_revision INTEGER NOT NULL CHECK (credential_revision >= 1),
+  readiness_status TEXT NOT NULL CHECK (readiness_status IN ('unknown', 'healthy', 'unhealthy')),
+  readiness_model TEXT,
+  readiness_latency_ms BIGINT,
+  readiness_error_code TEXT,
+  readiness_checked_at BIGINT,
+  revision INTEGER NOT NULL CHECK (revision >= 1),
+  created_by TEXT NOT NULL,
+  created_at BIGINT NOT NULL,
+  updated_by TEXT NOT NULL,
+  updated_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, provider_key)
+);
+CREATE INDEX IF NOT EXISTS agent_provider_connections_tenant_name_idx
+  ON agent_provider_connections (tenant_id, name, id);
+ALTER TABLE agent_provider_connections ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_provider_connections FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_provider_connections_tenant_policy ON agent_provider_connections
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/agents/migrations/0003_resource_audit.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_audit_events_v2;

package/modules/agents/migrations/0003_resource_audit.up.sql

@@ -0,0 +1,25 @@
+CREATE TABLE IF NOT EXISTS agent_audit_events_v2 (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  subject_type TEXT NOT NULL CHECK (subject_type IN ('agent', 'agent-run', 'agent-provider', 'agent-skill')),
+  subject_id TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  previous_hash TEXT,
+  event_hash TEXT NOT NULL,
+  UNIQUE (tenant_id, sequence),
+  UNIQUE (tenant_id, event_hash)
+);
+INSERT INTO agent_audit_events_v2
+  SELECT * FROM agent_audit_events ORDER BY tenant_id, sequence
+ON CONFLICT DO NOTHING;
+CREATE INDEX IF NOT EXISTS agent_audit_v2_tenant_time_idx
+  ON agent_audit_events_v2 (tenant_id, occurred_at DESC, sequence DESC);
+ALTER TABLE agent_audit_events_v2 ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_audit_events_v2 FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_audit_events_v2_tenant_policy ON agent_audit_events_v2
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/agents/migrations/0004_run_grants.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_run_grant_uses;

package/modules/agents/migrations/0004_run_grants.up.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS agent_run_grant_uses (
+  grant_id TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  tenant_id TEXT NOT NULL,
+  run_id TEXT NOT NULL REFERENCES agent_runs(id) ON DELETE CASCADE,
+  worker_id TEXT NOT NULL,
+  provider_id TEXT NOT NULL,
+  model_id TEXT NOT NULL,
+  issued_at BIGINT NOT NULL,
+  expires_at BIGINT NOT NULL,
+  consumed_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS agent_run_grant_expiry_idx
+  ON agent_run_grant_uses (expires_at);
+ALTER TABLE agent_run_grant_uses ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_run_grant_uses FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_run_grant_uses_tenant_policy ON agent_run_grant_uses
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/agents/migrations/0005_long_running_limits.down.sql

@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS agent_run_execution_limits;
+DROP TABLE IF EXISTS agent_definition_execution_limits;

package/modules/agents/migrations/0005_long_running_limits.up.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS agent_definition_execution_limits (
+  agent_id TEXT PRIMARY KEY REFERENCES agent_definitions(id) ON DELETE CASCADE,
+  timeout_ms BIGINT NOT NULL CHECK (timeout_ms BETWEEN 250 AND 86400000)
+);
+INSERT INTO agent_definition_execution_limits (agent_id, timeout_ms)
+  SELECT id, timeout_ms FROM agent_definitions
+ON CONFLICT DO NOTHING;
+CREATE TABLE IF NOT EXISTS agent_run_execution_limits (
+  run_id TEXT PRIMARY KEY REFERENCES agent_runs(id) ON DELETE CASCADE,
+  timeout_ms BIGINT NOT NULL CHECK (timeout_ms BETWEEN 250 AND 86400000)
+);
+INSERT INTO agent_run_execution_limits (run_id, timeout_ms)
+  SELECT id, timeout_ms FROM agent_runs
+ON CONFLICT DO NOTHING;

package/modules/agents/migrations/0006_agent_skills.down.sql

@@ -0,0 +1,3 @@
+DROP TABLE IF EXISTS agent_run_skill_snapshots;
+DROP TABLE IF EXISTS agent_skill_assignments;
+DROP TABLE IF EXISTS agent_skills;