@flowdular/sdk 0.2.4 → 0.3.0

package/.ai/agents/sandbox/business-manager.md

@@ -12,7 +12,11 @@ handoff:
   - ux-designer
 ---
 
-You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
+You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/platform-capabilities.md, reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
+
+Write schemaVersion 2: entities with typed fields and states, screens, actions, widgets, settings, agentTools, plus outOfScope and decisions. Fill decisions for every choice, including the platform defaults you proposed. The capability card is closed: anything it lists as missing goes to outOfScope with the business decision, never into a scenario. v1 specs stay valid.
+
+When a decision is missing, end the reply with exactly one fenced block tagged questions holding {"questions":[{"id":"Q-1","question":"...","options":["..."],"recommended":"...","allowFreeText":true}]} and nothing after it. The operator answers in a form and the replies arrive next turn as a Decisions section.
 
 For an edit, compare against base/modules/<dir>/spec/module.yaml and make the smallest delta covering the brief. Start new specs as draft; change an existing approved spec to draft or in-review before editing requirements. Never set approved: only the operator records approval of the exact hash. Later edits invalidate it.
 

package/.ai/blueprints/author-spec/README.md

@@ -2,4 +2,4 @@
 
 Turn an agreed business request into `modules/<dir>/spec/module.yaml`. In the sandbox this is the first turn of a `new-module` session, taken by `business-manager`; at the repository root it is `spec-author` following `.ai/agents/spec-author.md`. The blueprint creates or revises the specification only. It never creates implementation files and never sets `status: approved`; approval belongs to a human owner (the sandbox approve button, or an edit in the pull request).
 
-The result must validate against `packages/contracts/schemas/module-spec.schema.json` (`pnpm flowdular spec validate --all --json`) and be decision complete: permissions with one read and one manage id per entity, invariants for tenancy and uniqueness, data ownership, and acceptance scenarios that include a denial and a tenant isolation case. Unknown business decisions stay explicit questions in the handoff, never guesses. `templates/module.yaml` is a starting point with the keys the schema knows; `.ai/agents/sandbox/business-manager.md` carries a complete minimal example.
+The result is a `schemaVersion: 2` document that validates against `packages/contracts/schemas/module-spec.schema.json` (`pnpm flowdular spec validate --all --json`, including the cross checks between actions, permissions, entities and fields) and is decision complete: permissions with one read and one manage id per entity, entities with typed fields and tenant uniqueness, screens and actions, invariants for tenancy and uniqueness, data ownership, acceptance scenarios that include a denial and a tenant isolation case, `outOfScope` for everything `.ai/platform-capabilities.md` lists as missing, and `decisions` recording every choice and who made it. The procedure is the `spec-interview` skill: propose a platform default per decision and ask only what cannot be inferred, through the questions protocol described in `.ai/agents/sandbox/business-manager.md`. Unknown business decisions stay explicit questions, never guesses. `templates/module.yaml` is a starting point with the keys the schema knows. Version 1 specs stay valid for existing modules.

package/.ai/blueprints/author-spec/spec-requirements.yaml

@@ -1,5 +1,9 @@
 schemaVersion: 1
 # Keys below exist in packages/contracts/schemas/module-spec.schema.json.
+# A new specification is authored at specSchemaVersion 2: it carries the domain
+# model, so the implementing agent reads the spec instead of the repository.
+# An existing version 1 specification stays valid and is not rewritten.
+specSchemaVersion: 2
 status:
   initial: draft
   allowed:
@@ -22,14 +26,54 @@ requiredKeys:
   - permissions
   - dataOwnership
   - acceptanceScenarios
+  - decisions
+  - outOfScope
+byCapability:
+  database:
+    entities: at least one, with every persisted field typed and one field unique inside the tenant
+  client:
+    screens: at least one list screen whose columns and filters are field ids of its entity
+  api:
+    actions: one per mutation, each naming a permission the spec declares
 identifiers:
   id: ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$
   permissions: <module>.<entity>.read and <module>.<entity>.manage
   acceptanceScenarios: ^[A-Z][A-Z0-9-]+$
+  entities: ^[a-z][a-z0-9-]*$
+  fields: ^[a-z][a-zA-Z0-9]*$
+  screens, actions, widgets: ^[a-z][a-z0-9-]*$
+  settings: ^[a-z][a-zA-Z0-9]*$
+  agentTools: <module>.<entity>.<verb>, the dotted tool identity the registry uses
+  decisions: ^[A-Z][A-Z0-9-]+$
+entities:
+  fieldTypes:
+    - string
+    - text
+    - integer
+    - decimal
+    - boolean
+    - date
+    - datetime
+    - enum
+    - reference
+    - json
+  rules:
+    - an enum field declares values; a reference field names an entity of this
+      spec or <moduleId>.<entityId> of a declared dependency
+    - 'the first entity drives the scaffold: fields become the domain type, the
+      0001 migration columns, the repository mapping and the create input'
+    - states.field names the enum field that declares exactly states.values
+    - no field is called id, tenantId or createdAt; every tenant table owns them
+    - no field is a PostgreSQL reserved word such as order, user, group or end
 acceptanceScenarios:
   minimum: 3
   mustInclude:
     - denial
     - tenant isolation
+decisions:
+  policy: every answered question is recorded, decidedBy user when the operator
+    answered and default when a platform default was applied instead
+outOfScope:
+  policy: what the business excluded, and what the platform does not provide yet
 openQuestions:
   policy: stay in the handoff message; never guessed into the file

package/.ai/blueprints/author-spec/steps.yaml

@@ -2,17 +2,17 @@ schemaVersion: 1
 steps:
   - id: collect
     role: business-manager
-    action: Validate the brief against input.schema.json (module id, outcome, actors); list the business facts still missing.
-    inputs: [brief]
-    outputs: [open questions]
+    action: Validate the brief against input.schema.json (module id, outcome, actors); walk the spec-interview decision checklist against .ai/platform-capabilities.md, propose a platform default for every decision and list the ones that cannot be inferred.
+    inputs: [brief, platform-capabilities.md]
+    outputs: [proposed decisions, open questions]
   - id: ask
     role: business-manager
-    action: Stop and ask for every unresolved business or security decision instead of guessing.
+    action: Ask every unresolved decision through the questions protocol (one fenced questions block in the sandbox, the question tool in Claude Code) instead of guessing; each answer becomes a decisions[] entry.
     inputs: [open questions]
     outputs: [answers]
   - id: draft
     role: business-manager
-    action: Write spec/module.yaml from templates/module.yaml with status draft; permissions, invariants, dataOwnership, acceptanceScenarios complete.
+    action: Write spec/module.yaml (schemaVersion 2) from templates/module.yaml with status draft; permissions, invariants, dataOwnership, acceptanceScenarios, entities with typed fields, screens, actions, outOfScope and decisions complete.
     inputs: [answers]
     outputs: [spec/module.yaml]
     gates: [spec-schema]

package/.ai/blueprints/author-spec/templates/module.yaml

@@ -1,6 +1,9 @@
 # Replace every {placeholder}. Keys are the ones module-spec.schema.json knows;
 # nothing else is accepted. Keep status: draft; a human approves.
-schemaVersion: 1
+# schemaVersion 2 adds the domain model below, so an implementing agent never
+# has to scan the repository. Every version 2 section is optional: delete the
+# ones the module does not need, keep the ones it does.
+schemaVersion: 2
 id: '{moduleId}'
 specVersion: 0.1.0
 status: draft
@@ -14,9 +17,9 @@ capabilities:
   - translations
 dependencies:
   - id: system.core
-    range: ^0.1.0
+    range: ^0.5.0
   - id: auth.core
-    range: ^0.1.0
+    range: ^0.11.0
 tenancy: required
 locales:
   - en
@@ -30,6 +33,99 @@ permissions:
     description: Create and update {entities} in the active tenant.
 dataOwnership:
   - '{moduleId} owns {entity} identity and lifecycle status.'
+# The first entity drives the scaffold: its fields become the domain type, the
+# 0001 migration columns, the repository mapping and the create input.
+entities:
+  - id: '{entities}'
+    name: '{Entity}'
+    description: '{what one record is}'
+    fields:
+      # type: string | text | integer | decimal | boolean | date | datetime |
+      #       enum | reference | json
+      - id: '{code}'
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 64
+        description: '{business identifier}'
+      - id: '{title}'
+        type: string
+        required: true
+        maxLength: 160
+      - id: status
+        type: enum
+        required: true
+        values:
+          - active
+          - archived
+      # reference: '<entityId>' in this spec, or '<moduleId>.<entityId>'
+      - id: '{ownerId}'
+        type: reference
+        reference: auth.core.users
+    states:
+      field: status
+      values:
+        - active
+        - archived
+      transitions:
+        - from: active
+          to: archived
+          permission: '{module}.{entities}.manage'
+screens:
+  - id: '{entities}'
+    kind: list
+    entity: '{entities}'
+    title: '{Entities}'
+    columns:
+      - '{code}'
+      - '{title}'
+      - status
+    filters:
+      - status
+    navigationGroup: Operations
+actions:
+  - id: 'create-{entity}'
+    entity: '{entities}'
+    permission: '{module}.{entities}.manage'
+    kind: create
+    risk: workspace-write
+    idempotent: false
+    description: Create a {entity} in the active tenant.
+  - id: 'archive-{entity}'
+    entity: '{entities}'
+    permission: '{module}.{entities}.manage'
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Archive a {entity} without deleting its history.
+widgets:
+  - id: '{entities}-total'
+    slot: dashboard.metrics
+    entity: '{entities}'
+    description: Number of active {entities} in the active tenant.
+settings:
+  - key: '{settingKey}'
+    type: integer
+    scope: tenant
+    default: 30
+    description: '{what the number controls}'
+agentTools:
+  - id: '{module}.{entity}.list'
+    permission: '{module}.{entities}.read'
+    description: List {entities} of the active tenant.
+    risk: read
+outOfScope:
+  - '{what the platform does not provide yet, for example file attachments}'
+  - '{what the business excluded, for example e-mail notifications}'
+decisions:
+  - id: '{MODULE}-STATUS'
+    question: '{the question that was open}'
+    answer: '{the answer that was given}'
+    decidedBy: user
+  - id: '{MODULE}-RETENTION'
+    question: '{a question nobody answered}'
+    answer: '{the platform default that was applied instead}'
+    decidedBy: default
 acceptanceScenarios:
   - id: '{MODULE}-LIST'
     given: Tenant-scoped {entities} exist.

package/.ai/blueprints/edit-module/gates.yaml

@@ -28,3 +28,7 @@ gates:
     command: pnpm format:check
     sandbox: prettier --check . (cwd module)
     required: true
+  - id: auto-review
+    command: run the auto-review skill as a separate read-only phase over the finished change
+    sandbox: inspectAutoReview(paths, module) in packages/sandbox/src/server/auto-review.ts; the record must match the current module contents, and eject refuses a missing or stale review (GATES in packages/sandbox/src/server/delivery/plan.ts)
+    required: true

package/.ai/blueprints/edit-module/required-files.yaml

@@ -44,9 +44,18 @@ byChange:
     - 'src/client/XView.tsrx'
     - 'src/client/contribution.tsrx'
     - 'src/client/index.ts'
+    - 'translations/*.json'
+    - 'tests/module.test.ts'
   widget:
     - 'src/client/*.tsrx'
     - 'src/client/contribution.tsrx'
+    - 'translations/*.json'
+    - 'tests/module.test.ts'
+  translations:
+    - 'translations/*.json'
+    - 'src/client/contribution.tsrx'
+    - 'spec/module.yaml'
+    - 'module.json'
   permission:
     - 'spec/module.yaml'
     - 'src/acl/permissions.ts'

package/.ai/blueprints/new-module/gates.yaml

@@ -28,3 +28,7 @@ gates:
     command: pnpm format:check
     sandbox: prettier --check . (cwd module)
     required: true
+  - id: auto-review
+    command: run the auto-review skill as a separate read-only phase over the finished change
+    sandbox: inspectAutoReview(paths, module) in packages/sandbox/src/server/auto-review.ts; the record must match the current module contents, and eject refuses a missing or stale review (GATES in packages/sandbox/src/server/delivery/plan.ts)
+    required: true

package/.ai/blueprints/new-module/spec-requirements.yaml

@@ -19,9 +19,9 @@ byCapability:
 dependencies:
   required:
     - id: system.core
-      range: ^0.1.0
+      range: ^0.5.0
     - id: auth.core
-      range: ^0.1.0
+      range: ^0.11.0
 acceptanceScenarios:
   minimum: 4
   mustInclude:

package/.ai/blueprints/release/gates.yaml

@@ -5,6 +5,10 @@ gates:
     command: eject stream runs spec-schema and module-schema once, then dependencies, typecheck, tests, format per draft module
     required: true
     appliesTo: sandbox-eject
+  - id: auto-review
+    command: run the auto-review skill as a separate read-only phase over the finished change
+    sandbox: every draft module needs a passing auto-review record that matches its current contents; GATES in packages/sandbox/src/server/delivery/plan.ts lists it with the deterministic gates and eject stops on a missing or stale record
+    required: true
   - id: verify
     command: pnpm verify
     required: true

package/.ai/platform-capabilities.md

@@ -0,0 +1,128 @@
+# Platform capability card
+
+What a Flowdular module can be built from, and what the platform does not provide yet. This card is closed: if a capability is not listed under "What a module gets", the platform does not have it, and a specification must place the request under `outOfScope` with the business decision instead of promising it.
+
+Read this file before writing or implementing a spec. It replaces scanning `modules/` and `packages/` for the common case. When a task needs a detail this card does not carry, read the one file named here, not the tree.
+
+## What a module gets
+
+**Tenant identity.** Every request carries a principal resolved by `modules/auth`. `principalFromContext(octane)!.tenantId` is the only tenant authority; a tenant id from a body, query or header is a defect. Row-level security binds the same id inside the transaction.
+
+**Authorization.** `defineEndpoint` (`packages/server/src/endpoint.ts`) takes `id`, `path`, `methods`, `handler` and `access`. `access` is either `{ kind: 'public' }` or `{ kind: 'permission', permission }` with `resolveIdentity: endpointIdentityFromContext`. A protected endpoint answers 401 `UNAUTHENTICATED` without an identity and 403 `FORBIDDEN` without the permission. Permission ids match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$` and are declared in the spec `permissions`, in `src/acl/permissions.ts` and on the endpoint. CSRF and input bounds are not endpoint options: mutations call `sessionMutationDenial(octane, auth)` first (`modules/auth/src/server/session-security.ts`) and parse the body through `readJsonObject`, `requiredString`, `optionalString`, `requiredInteger` (`packages/server/src/http.ts`, 415 without JSON, 413 over 16 KB).
+
+**Record policies.** A permission answers who may act on a kind of record; a policy answers whether this record allows it. `definePolicy` (`packages/kernel/src/acl.ts`) declares `{ id, permission, evaluate }`, where `evaluate({ principal, permission, record, action })` returns `{ allowed: true }` or `{ allowed: false, reason, requiresApproval? }`; `requiresApproval.requirement` carries `roleKey`, `scope`, `decisions` and `expiresInDays`, and nothing more: resolving a role to people, collecting their decisions and keeping the receipt belong to `approvals.core`, described below. Policies are registered into a `createPolicyRegistry()` while the module composes, at most 256, one registration per id, and the registry is sealed before requests run. An endpoint calls `authorizeRecord(registry, principal, permission, record, action?)`, which checks the permission scope first and then the policies of that permission in registration order, answering the first denial. A permission with no policy is allowed by the scope alone, and a policy that throws denies. The platform does not hand a module a shared registry yet, so a module that wants record conditions today owns its registry inside its own composition.
+
+**List pagination.** A list endpoint pages with `readPageQuery`, `encodeCursor`, `decodeCursor`, `pageResponse` and `keysetWhere` (`packages/server/src/pagination.ts`). `readPageQuery(url, { maxLimit, defaultLimit })` answers `{ limit, cursor }`, defaults to 50, refuses a limit outside 1 to the endpoint bound with 400 `INVALID_INPUT` and a malformed cursor with 400 `CURSOR_INVALID`; the platform ceiling is 200 rows. A cursor is the keyset of the last row of the page, HMAC signed with a 32 byte secret the module owns, bounded to 1 KB, and `decodeCursor` refuses anything this server did not sign with the same `CURSOR_INVALID`. The body shape is `{ items, page: { nextCursor, limit, total? } }`, `nextCursor` is null on the last page, and `total` is only for a count that is cheap. `keysetWhere(['created_at', 'id'], values, { direction, parameterOffset })` builds the row-order predicate with bound parameters; offset paging over a tenant's rows is not a platform capability. New list endpoints use these; the list endpoints written before them still carry their own paging until their module retrofits it.
+
+**List export.** A list endpoint that already pages with the keyset helpers becomes a CSV export by declaring one: `defineListExport({ id, label, permission, columns, page })` (`packages/server/src/export/`), where `id` is the owning module id plus the list key (`users.core.members`), `permission` is the one the list endpoint itself requires, `columns` is 1 to 64 `{ key, header, value(row) }` entries and `page(principal, cursor, limit)` is the paging the endpoint already implements. The declaration is type erased at definition time, so no row object leaves the module that produced it. A module registers its declarations while it composes, through the public capability `exports.lists.v1` (`context.capabilities.get<ExportLists>(EXPORT_LISTS_CAPABILITY)?.register(moduleId, […])`, `modules/exports`); the id must sit inside the registering module's namespace and the catalogue is sealed before the first request. `exports.core` owns the rest: `POST /api/exports/start` behind `exports.lists.manage` plus the list's own permission checked on the live principal, `GET /api/exports/jobs` and `/api/exports/jobs/:id` paged behind `exports.lists.read`, `GET /api/exports/lists` behind the same permission for the catalogue of registered lists (id, label, registering module and whether the asking principal holds that list's permission, never the permission id), which is what the Exports screen's start control offers to a reader holding `exports.lists.manage`, and `POST /api/exports/jobs/read-url` for a signed storage route minted per request, which re-checks the exported list's permission on the live principal so the file is never easier to read than the list. A poll loop on the job runner walks the pages under the requester's snapshot and writes RFC 4180 with a UTF-8 byte order mark to the storage port under `exports.core`. Neither bound truncates: over `maxRows` (default 100000) or `maxBytes` (default 50 MB, both platform settings, and the storage object ceiling of 25 MB applies underneath) the job fails with `EXPORT_ROWS_EXCEEDED` or `EXPORT_BYTES_EXCEEDED` and writes no file. A list that answers a next cursor answers at least one row with it and never the cursor it was given. Cells are written as the declaration answered them and are never rewritten, so a value beginning with `=`, `+`, `-` or `@` reaches the file as data and this module neither prefixes nor quotes it against a spreadsheet reading it as a formula; a module whose column can carry such a value neutralises it in its own `value(row)`. Jobs are held 30 days by the data class `exports.core.jobs`, whose sweep deletes the file with the row.
+
+**PostgreSQL with forced row-level security.** A module receives a `DatabaseProvider` as `context.databases` and acquires a lease per purpose (`runtime`, `migration`, `background`, `preview`, `test`); it never sees a DSN or a pool. Every statement runs inside `database.transaction(fn, { tenantId, access })` with `access: 'read' | 'write'`; a runtime lease without a `tenantId` throws `TENANT_CONTEXT_REQUIRED`. The adapter sets `coreloom.tenant_id` transaction-locally, and each tenant table must `ENABLE` and `FORCE ROW LEVEL SECURITY` with a `USING` and `WITH CHECK` policy against it. Migrations are numbered, immutable once applied, mirrored byte for byte in `databaseMigrations`, and recorded in the `_coreloom_migrations_v2` ledger by checksum. The runtime role holds neither `SUPERUSER` nor `BYPASSRLS`. (`packages/database/src/{contracts,postgresql,migrations,provider}.ts`.)
+
+**Background work.** A module that polls its own routing table runs one loop per job through `createJobRunner` (`packages/server/src/jobs/`), taking `{ name, intervalMs, claim, perform, heartbeat?, heartbeatEveryMs?, staleAfterMs, backoff?, batchLimit?, logger, now?, onEvent? }`. The runner owns the loop and nothing else: the timer and its `unref`, the guard that keeps two passes from overlapping, at most `batchLimit` claims per pass, per-item isolation so one failing item never stops the pass, a renewal timer that calls `heartbeat` while `perform` runs and aborts its `AbortSignal` with the stable code `CLAIM_LOST` when the fence answers false, exponential `backoff` after a pass that raised and a reset by one that did not, and `start`, `tick`, `stop`, `quiesce` and `dispose`. It opens no database handle: the table, the routing read, the claim statement with its stale window, the renewal statement and every outcome recorded stay the module's own, `claim` answering null ends the pass, and a stage that observes the abort stops without settling anything. `onEvent` is a trace hook that costs nothing when nobody listens. A composition wires it as `start`, `stop: () => runner.quiesce()` and `dispose: () => runner.dispose()`; `import.core` is the first adopter and `packages/server/src/jobs/index.ts` carries the recipe for the rest.
+
+**Module settings.** `defineModuleSettings` (`packages/kernel/src/module-settings.ts`) declares `{ moduleId, settings }`. A setting has `type: 'string' | 'number' | 'boolean'`, `defaultValue`, `visibility: 'private' | 'shared'`, `client: boolean`, and optionally `kind: 'flag'`, `scope: 'platform' | 'tenant'`, `secret`, `labelKey`, `descriptionKey`, `label`, `description`, `enum` (string type only), `min`, `max`, `pattern`, `multiline`. Keys match `^[a-z][a-zA-Z0-9]*$`. The allowed-values field is `enum`, not `values`. A `secret` setting can be neither `client: true` nor `visibility: 'shared'`. Values are read live with `context.settings.get(tenantId, moduleId, key)` and edited in Administration, Modules behind `system.settings.read` and `system.settings.manage` (`GET /api/settings`, `POST /api/settings/update`, `modules/system/src/server/endpoints.ts`). A read needs the tenant primed first (`await context.settings.prime(tenantId)`): the authenticated request path and the platform composition prime, a background path primes itself, and `set` is awaited.
+
+**Feature flags.** A flag is a module setting declared `kind: 'flag'`: a non-secret `boolean` with a `defaultValue`, a `label`, a `description` and `scope: 'tenant'`, which is the default and the only scope a flag may take; `defineModuleSettings` refuses anything else, a platform-scoped flag included. There is no flag store, no flag endpoint and no flag registry. A module reads one on the request path with the ordinary settings read, `context.settings.get<boolean>(tenantId, moduleId, key)`: a lookup of the declaration, a lookup of the cached per `(tenant, module)` value set under a key the read builds, the touch that keeps that entry at the head of the cache, the property read and one `typeof` check. No query of its own, and nothing beyond what any setting already costs: a declared `pattern` is compiled once with the declaration, never per read. There is deliberately no `context.flags`; the read is the settings read, and the module id is the one the module already knows. An override is per workspace behind `system.settings.manage` on the Flags tab of Administration, Modules, which groups every declared flag by its owning module and links the audit trail. Every change appends one `settings.flag.changed` auth audit event with the module, the key, the previous and next values and the actor (`settings.updated` stays the event for every other setting). No percentage rollout and no targeting: a flag is on or off for a workspace.
+
+**Navigation groups.** A navigation contribution picks exactly one group (`NavigationGroup`, `packages/client/src/contributions.ts`):
+
+<!-- capabilities:navigation-groups -->
+
+`Workspace`, `Operations`, `Agents`, `Automations`, `Administration`, `Development`
+
+<!-- /capabilities:navigation-groups -->
+
+**Workspace slots.** A widget contribution targets exactly one slot (`WORKSPACE_SLOTS`, same file):
+
+<!-- capabilities:workspace-slots -->
+
+`dashboard.metrics`, `dashboard.main`, `dashboard.aside`, `topbar.actions`
+
+<!-- /capabilities:workspace-slots -->
+
+**Account menu.** A view reached from the avatar menu rather than the sidebar, for anything owned by the person instead of the workspace: `accountMenu` entries carry `id`, `viewId`, `label`, `description`, `glyph`, `scope`, `order`.
+
+**Agent tools registry.** A module registers tools during `createServerComposition` with `context.agentTools.register(tools)`. A tool is built by `defineApiAgentTool` (wraps one `endpointId`) or `defineCliAgentTool` (wraps one CLI `capability`) from `packages/harness/src/tool-adapters.ts` and declares `id`, `description`, `requiredPermissions`, `inputSchema`, `outputSchema`, `contractVersion`, `risk: 'read' | 'workspace-write' | 'external' | 'destructive'`, `idempotency`, `idempotencyProtection: 'target-ledger'`, `cancellation`, `timeoutMs`. A CLI capability with risk `external` or `destructive` cannot become an unattended agent tool.
+
+**Business agents.** `defineAgent` (`modules/agents/src/server/define-agent.ts`) declares `moduleId`, `key`, `definitionRevision`, `name`, `description`, `instructions`, `allowedTools` (at most 32, exact ids, no wildcards) and `limits` (`maxSteps` 1 to 32, `timeoutMs`, `temperature`, `maxOutputTokens`). Registered with `context.agentDefinitions.register(...)`. The definition owns behaviour and the maximum tool ceiling; provider, model, credentials, active state and the reduced enabled tools are tenant binding data.
+
+**Workflows.** `workflows.core` owns typed DAGs with exactly nine node kinds (`modules/workflows/src/domain/types.ts`): `input`, `agent`, `agent-decision`, `gate`, `validator`, `action`, `merge`, `output` and `human-approval`, which opens an approvals.core request with the run as subject, parks the run in `waiting-approval` and resumes on approval or fails it with `WORKFLOW_APPROVAL_REJECTED`, `WORKFLOW_APPROVAL_EXPIRED` or `WORKFLOW_APPROVAL_CANCELLED`; publishing such a node needs approvals.core present and the named role defined in the workspace. A module starts a run through the public `WORKFLOW_EXECUTION_CAPABILITY`; workflow trigger sources are `manual`, `module`, `schedule` and `webhook`.
+
+**Automations triggers.** Two mechanisms in `automations.core`. A schedule uses a cadence string in one of two forms (`modules/automations/src/domain/cadence.ts`): `every:N`, where `N` is whole minutes from 1 to 10080 and the unit is implicit, or `cron:<minute> <hour> <day of month> <month> <day of week>`, five fields with no seconds, at most 100 characters, each field `*`, a number, a three letter month or weekday name, a list, a range, or any of those with a step (`*/15`, `9-17/4`); both day fields restricted means either matches. A cron slot is a wall clock time in the workspace zone from the shared `system.core.timeZone` setting, stored in UTC; a wall time a daylight saving change removes is skipped and one that occurs twice fires at the first of the two. An expression the module cannot honour is refused at save with `INVALID_CADENCE`. Missed slots are skipped, never replayed. An inbound webhook posts to `POST /api/automations/triggers/:id/fire`, authenticated by an HMAC signature in `x-flowdular-signature` with `x-flowdular-timestamp` inside a 5 minute window and a 16 KB body cap, answering `202 { accepted, runId }`. Targets are pluggable through `automations.targets.v1`; the shipped kinds are `agent` and `workflow`.
+
+**CLI extensions.** A module contributes `pnpm flowdular <namespace> <action>` through `src/cli/commands.json` plus `defineCliExtension` (`packages/cli-protocol/src/index.ts`), declared in `module.json` under `cli`. The first path segment must equal the module id's first segment and may not be a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `migration`, `setup`). Each command carries a `CapabilityDescriptor` with `id`, `version`, `summary`, `risk: 'read' | 'workspace-write' | 'process' | 'external' | 'destructive'`, `requiresApprovedSpec`, `supportsDryRun`, optional `localOnly` and `confirmation`. The runner refuses `external` always and non-local `destructive` always, gates `localOnly` to `development` and `test`, and treats every write command as a dry run without `--apply`.
+
+**Translations.** The shipped locales are `en` and `pl`. A module keeps a flat bundle per locale in `translations/<locale>.json`, imports them in `src/client/contribution.tsrx` and returns `translations: { en, pl }`. Keys resolve fully qualified as `<first module segment>.<key>` through `t()`. `flowdular module validate` reports `TRANSLATION_FILE_MISSING`, `TRANSLATION_PARSE_ERROR`, `TRANSLATION_KEYS_MISMATCH` and `TRANSLATION_KEY_MISSING`.
+
+**Web surfaces.** A module may own public, server-rendered website pages separate from the authenticated shell (`packages/server/src/web.ts`). `defineWebSurface` declares `{ id, pages }` with at most 128 pages; a page has `id`, `path`, `entry`, optional `layout`, a `load` function and `access`, which is one of `{ kind: 'public' }`, `{ kind: 'authenticated' }` or `{ kind: 'permission', permission }`. The operator, not the module, mounts a surface at a tenant-scoped path; `setup`, `health`, `ready`, `assets`, `app`, `api`, `auth`, `sign-in`, `sign-up`, `forgot-password`, `reset-password` and `accept-invitation` are reserved.
+
+**Public capabilities registry.** Cross-module access goes through `context.capabilities.register(id, value)` in the owning module and `context.capabilities.get<T>(id)` in the consumer (`packages/kernel/src/capability-registry.ts`). The owning module lists the id under `provides` in `module.json`; the consumer lists it under `requires` (`{ "id", "optional": true }` when it handles a null `get`). The composition gives each module a registry view that accepts only its declared ids, the kernel orders required providers first and refuses a missing provider, and the installer resolves a required capability to a release that provides it. A type import from the provider's package still needs the module and package dependency (`"range": "^0.11.0"`). A module never opens another module's database or imports its `src/` path.
+
+**Notifications.** `notifications.core` (optional, enabled by default) owns a per-member in-app inbox with preferences, per-tenant outbound webhook subscriptions signed with the inbound automations scheme, and e-mail delivery of inbox items, all three sharing one delivery ledger with bounded retry and a dead letter. A module publishes through the public capability `notifications.publish.v1` obtained lazily with `context.capabilities.get` and tolerates its absence; the input is `{ tenantId, kind, sourceModule, sourceRef, title, body?, recipients }` with the kinds `agent-run-completed`, `agent-run-failed`, `workflow-run-completed`, `workflow-run-failed`, `webhook-dead-letter` (`modules/notifications/src/domain/publish.ts`). A new kind is a `notifications.core` spec edit, not a publisher's decision. A publisher never chooses a channel: the member does, with the per-kind switch that decides whether an item exists at all and the `emailDelivery` switch (off by default) that also mails the items they receive, through the platform mail port and the address `auth.core` holds. `ToastHost` and `toasts` remain the in-screen confirmation for what the reader just did.
+
+**Mail.** A module sends through `context.mail` (`packages/server/src/mail/`) and never selects a transport, a relay or a provider SDK. `send({ to, subject, text, html?, locale?, headers? })` takes at most 16 recipients, a 200 character single-line subject, 64 KB of text, 256 KB of HTML and 16 extra headers whose names the envelope does not own; CR and LF are refused everywhere a header could be opened, so header injection is the port's problem and not each sender's. It rejects with a `MailError` carrying `MAIL_NOT_CONFIGURED` (no transport composed), `MAIL_MESSAGE_REJECTED` (a bound) or `MAIL_DELIVERY_FAILED` (the relay, whose words never travel with it); `mail.configured` is the flag a feature gates on instead of provoking a refusal. `renderMailTemplate({ subject, text, html? }, values)` fills `{{ name }}` holes in one pass and escapes every value for the HTML part. The deployment picks the adapter with `FD_MAIL_TRANSPORT`: `none` (refuses), `development` (an in-memory outbox of the last 100 messages, refused in production) or `smtp` (`FD_MAIL_SMTP_URL`, `FD_MAIL_FROM`; the retired `FD_AUTH_MAIL_*` names still work with a deprecation line). `auth.core` sends invitations, resets and confirmations through it, `notifications.core` mails inbox items; a module that wants to reach a person publishes a notification rather than composing mail of its own.
+
+**Object storage.** A module writes files through `context.storage` (`packages/storage/src/index.ts`) and never sees an adapter, a bucket or a path. `put`, `get`, `delete`, `stat` and `readUrl` take `{ tenantId, moduleId, objectId }`; the key is `<tenantId>/<moduleId>/<objectId>` and the tenant id comes from the principal, never from the request, because no row-level security reaches an object store. Development and test use a local directory, a deployment uses an S3-compatible bucket (`FD_STORAGE_ADAPTER=local|s3`, `local` refused in production). Every object is encrypted with AES-256-GCM under `FD_STORAGE_ENCRYPTION_KEY` before it is written, with the key id and the metadata authenticated alongside it. An object is at most 25 MB (`FD_STORAGE_MAX_OBJECT_BYTES`) and must be one of PDF, PNG, JPEG, GIF, WebP, plain text, CSV, `.docx`, `.xlsx`, `.pptx`, `application/msword` or `application/vnd.ms-excel`, verified against the bytes; archives and executables are refused. A malware scanner is a deployment seam, so the stored verdict is `clean`, `infected` (refused) or `unscanned` (the default). `readUrl` returns `/api/storage/objects/<token>`, a signed platform route that expires in at most an hour and streams the decrypted body as an attachment, never a presigned URL to the ciphertext. Upload, metadata and the attachment table belong to `documents.core`, described next; a module never puts bytes of its own through `context.storage` when a document fits.
+
+**Connectors.** `connectors.core` (optional) is the governed way out to an external system. A module ships a connector definition through the public capability `connectors.definitions.v1` (`modules/connectors/src/domain/definitions.ts`): `register({ key, moduleId, label, authKinds, operations: [{ key, label, method, path, inputSchema, outputSchema }], defaultAllowedHosts, allowedPorts? })` (ports default to 443 only), and the platform ships `http-json`. An owner creates an instance behind `connectors.instances.manage` with a base URL, sealed credentials under `FD_CONNECTORS_SECRET_KEY`, a host allowlist and two consent flags, `allowWorkflows` and `allowAgents`, both off. A call goes through `connectors.calls.v1`: `call({ tenantId, instanceId, operation, input, caller: 'test' | 'workflow' | 'agent', callerRef? })`, which enforces status, consent for that caller kind, the egress policy (https, no private addresses, no redirects, timeout and size caps) and logs the call without any body; `consented(tenantId, instanceId, caller)` answers admission alone. The agent tool `connectors.call` is declared `workspace-write` with the harness consent gate `connectors.instance-consent` (`AgentToolConsent` in `packages/harness/src/runtime.ts`), carries the full action contract (`idempotency: 'required'` backed by a per-call key ledger) so workflows may use it, has no HTTP route of its own, and dials only the addresses the egress policy verified, so the ceiling is raised per instance by the owner's consent, never by a declaration.
+
+**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back.
+
+**Documents.** `documents.core` (optional) owns file attachments of any record. A screen uploads through `POST /api/documents/upload` with the raw body and the headers `x-document-filename`, `x-document-owner-module`, `x-document-record-ref` and `x-document-description`, lists with `GET /api/documents?ownerModule=&recordRef=`, opens through `POST /api/documents/read-url` (a short-lived storage URL) and deletes through `POST /api/documents/delete`, all behind `documents.files.read` or `documents.files.manage` with CSRF first. A module reads its own records' attachments through the public capability `documents.attachments.v1` (`modules/documents/src/domain/attachments.ts`): `list(tenantId, ownerModule, recordRef)`, `open(tenantId, ownerModule, recordRef, id)` answering `{ contentType, bytes, filename, body }` or null for anything not readable (unknown, another pair, deleted, infected) and `delete(tenantId, ownerModule, recordRef, id)`; the reference pair is a scope, the caller's permission on its own record is the authorization, and the storage key never leaves documents.core. Checksums, scan verdicts and the object limits come from the storage port.
+
+**Directory and SCIM.** `directory.core` (optional) gives a workspace a SCIM 2.0 endpoint at `/api/scim/v2/:workspace` (Users and Groups) authenticated by a workspace SCIM token an owner creates through `POST /api/directory/tokens`, group mappings paged through `GET /api/directory/groups` with the role keys from `GET /api/directory/groups/context`, and a provisioning ledger at `GET /api/directory/provisioning-events`. Deprovisioning disables the membership through users.core; no password ever crosses SCIM. A module does not talk to SCIM; it reads memberships through users.core as before.
+
+**Metering.** `metering.core` (optional) counts what a workspace consumes. A module declares meters at composition through the public capability `metering.meters.v1` (`modules/metering/src/domain/meters.ts`): `declare(moduleId, [{ key, label, unit, kind }])`, and at run time `record({ tenantId, meter, amount, at?, sourceRef? })`, idempotent per source reference and written by metering.core in its own tenant transaction, and `check({ tenantId, meter, amount })` answering `allowed`, `warning` or `refused` against the operator's monthly limit; a refusal carries the stable code `METER_LIMIT_EXCEEDED` and the caller records it in its own trail. Usage screens are behind `metering.usage.read`; limits are set only by the operator with `pnpm flowdular metering limits set`.
+
+**Import.** `import.core` (optional) brings CSV rows into a module's records through a port the module registers at composition with the public capability `import.ports.v1` (`modules/import/src/domain/ports.ts`, re-exported from `@flowdular/module-import`): `register(moduleId, [{ key, label, permission, fields: [{ id, label, required, type }], naturalKey, validate({ tenantId, principal, rows }), write({ tenantId, principal, rows, mode }) }])`. Rows arrive as `{ row, values }` with unmapped columns absent; `validate` returns refusals only, `write` answers one outcome per row (`created`, `updated`, `skipped`, `failed`) under the mode `create-only`, `update-existing` or `skip-existing`, in batches of at most `batchSize` inside the port's own tenant transaction, and a row it says nothing about is failed with `PORT_SILENT`. The CSV is a document stored through `documents.core`; jobs, per-row outcomes and saved mappings live behind `import.jobs.read` and `import.jobs.manage`, the target's own manage permission is checked on the live principal at start and continue, and the poll loop parses and writes a job in bounded batches. `users.core.members` is the first target.
+
+**Search.** `search.core` (optional) merges record hits from providers each module registers at composition through the public capability `search.providers.v1` (`modules/search/src/domain/providers.ts`): `register(moduleId, [{ key, label, permission, search({ tenantId, principal, query, limit, cursor?, signal? }) }])`, where `search` runs over the owner's own tables inside the owner's own tenant transaction and answers `{ hits: [{ ref, title, snippet, viewId, route, score }], nextCursor }`. `GET /api/search?q=` behind `search.records.read` fans out with a per-provider time budget, drops the providers whose permission the principal lacks, names the ones that timed out, answers a signed `page.nextCursor` a client sends back to page further, keeps the query in the member's recall only when the request carries `remember=1` (a deliberate submit, never a debounced prefix), and the command palette shows hits below navigation through the `commandSearch` client contribution (`@flowdular/client`), whose optional `onOpen(hit)` the shell calls on the contribution that answered with the opened hit, once, without awaiting it and with a throw or a rejection isolated, so search.core keeps that hit's query in recall while the record is already opening. search.core holds no index; a provider owns its index or its bounded scan.
+
+**Reports.** `reports.core` (optional) composes one workspace report out of the rollups other modules already hold. A module registers a provider at composition through the public capability `reports.v1` (`modules/reports/src/domain/providers.ts`): `register(moduleId, [{ key, label, permission, read({ tenantId, principal, range: { from, to }, signal? }) }])`, where `read` runs over the owner's own rollup inside the owner's own tenant transaction and answers `{ tiles: [{ key, label, value, unit?, delta? }], series?: [{ key, label, points: [{ at, value }] }] }`. The registry is bounded to 64 providers per deployment and an answer to 16 tiles, 8 series and 400 points, and it is sealed when reports.core starts. `GET /api/reports?from=&to=` behind `reports.workspace.read` (owners; the scope is not a member scope) resolves the range as two inclusive UTC days, defaulting to the last 30 days and bounded to 400, refuses a reversed or malformed one with `INVALID_RANGE` before any call, drops the providers whose permission the principal lacks without naming them, fans out in parallel under a per-provider time budget (the platform setting `reports.core.providerTimeoutMs`, 3000 ms by default) and names the ones that failed, timed out or answered past a bound in `unavailable`. The Reports screen in Administration renders tiles with `Kpi` and series with `Chart`, and the `reports-summary` widget on `dashboard.metrics` shows the three largest tiles. reports.core owns no table and declares an empty data class list; the shipped providers are `metering.usage` (this month per meter, the monthly limit carried as the unit's context) and `agents.runs` (runs and tokens per day over the range).
+
+**Access review.** `access.core` (optional) answers who holds what in one workspace and what changed, reading auth.core live and storing only the attestation that someone reviewed it. `GET /api/access/review` behind `access.review.read` (owners; neither scope is a member scope) lists memberships with their account and workspace status, their role and the scopes held beyond that role, the usable API tokens by label, prefix and scopes, and the identity providers with their joining rules, with exact counts beside listings capped at 500 members, 100 roles, 200 tokens and 50 providers. `GET /api/access/diff?from=&to=` and `GET /api/access/activity?from=&to=` read the platform audit trail over two inclusive UTC calendar dates, at most 366 days apart, refusing a reversed or malformed range with `RANGE_REVERSED`, `RANGE_TOO_LONG` or `INVALID_INPUT` before any read; the diff answers the changes that move access (membership, role, scope, token, provider) and the activity report adds the administrative ones (settings, flags, password and MFA resets, workspace changes). Both walk at most 8 pages of 100 events per request and answer a signed cursor for the rest, so a client pages rather than a request scanning a whole trail. `POST /api/access/attest` behind `access.review.manage` (CSRF first) appends one row to the append-only `access_attestations` ledger with the period, the note and the counts the server recomputed itself, never counts from the body, and `GET /api/access/attestations` pages it newest first; the data class `access.core.attestations` is kept, exportable and not erasable, and both lists are registered with `exports.lists.v1` when exports.core is present. The screens are Review, Access activity and Attestations in Administration. Not covered: which member is bound to which identity provider (auth.core exposes no read of that), and holds and erasures, which live in audit.core's own trail.
+
+**Audit, retention, holds and erasure.** `audit.core` (optional, enabled by default) reads the data class registry below for the Data classes screen (`GET /api/audit/data-classes`, `POST /api/audit/data-classes/set-retention` behind `audit.retention.manage`), runs the one retention sweep on the platform loop with tenant-scoped periods and a backup guard (`FD_AUDIT_BACKUP_MANIFEST`), and exports a workspace on request: `pnpm flowdular audit export --workspace --output [--apply]` records the request and the running platform writes the archive into `FD_AUDIT_EXPORT_DIRECTORY`. Its own trail is hash chained and serialized per workspace; `audit seal --workspace --output [--apply]` closes a segment into JSON Lines with an anchor signed under `FD_AUDIT_ANCHOR_KEY`, `audit verify --workspace --input` checks a workspace's segments and chain, and a sealed event is swept only once its segment file exists. Legal holds (`audit.holds.manage`, owners, for listing as well as placing and lifting; `audit holds list|place|lift` for the operator) cover an account, a workspace, a class or a date range; a held class is skipped by the sweep and refused by erasure with `HOLD_ACTIVE`. Erasure is `pnpm flowdular audit erase --workspace --account --output [--apply --confirm erase-subject] [--destroy-key]`, performed by the platform loop within a day of the request: it walks every declared data class, calls the class's optional `erase({ tenantId, subject: { accountId }, limit })` (answering `{ removed, redacted?, truncated? }`) and `count?({ tenantId, subject })`, names a class without `erase` as not erasable, and writes a JSON certificate marked complete or partial; audit events themselves are excluded from erasure and sealed per subject so `--destroy-key` makes their subject fields unreadable. A module contributes its data class declaration and, when it holds personal data, `erase` and `count` on that declaration.
+
+**Data classes.** A module that owns rows declares them while it composes with `context.dataClasses.declare('<module id>', classes)` (`packages/kernel/src/data-class-registry.ts`). A declaration carries `key` (`^[a-z][a-z0-9-]*$`, the class id is `<module id>.<key>`), `label`, `defaultRetentionDays` (1 to 36500 or null for kept until a person deletes; zero is refused), `exportable`, `excludedReason` when it is not, and four optional operations the owner runs on its own tables under its own tenant transaction: `sweep({ tenantId, cutoff, limit })` answering `{ removed }`, `export({ tenantId, sink })` writing rows through `sink.write(row)` and answering `{ rows, from, to }`, `erase({ tenantId, subject: { accountId }, limit })` answering `{ removed, redacted?, truncated? }` and `count({ tenantId, subject })` answering a number or null. `removed` is rows the erasure took out and `redacted` is rows it kept but stripped of the subject, for a class whose row cannot go, such as an append-only ledger; both are non-negative integers, the erasure loop counts them together as the batch's progress, so a class that only redacts is asked again until it is done, and the certificate carries both. A module that owns no class declares an empty list, so a workspace sees it holds none. At most 64 classes per module, one declaration per module, and the platform seals the registry after every composition ran: a later `declare` throws. `list()` answers the whole catalogue from any module's view. audit.core reads it for the retention screens, the one retention sweep and the per-workspace export, and never opens another module's database; a class without a sweep is never swept and one without an export is named in the export manifest as excluded.
+
+**Health and readiness.** `GET /api/health` is static and public. `GET /api/ready` checks the database provider and answers 503 with `retry-after: 1` when it is unavailable (`platform/src/server/health.ts`).
+
+**Metrics.** Every request served through `defineEndpoint` is counted and timed in process by `serverMetrics()` (`packages/server/src/metrics.ts`), bounded to 2000 label sets per series family. Exposing them is opt-in and the operator's decision, never the module's: `platform/src/server/metrics.ts` composes `GET /api/metrics` (Prometheus text exposition 0.0.4) only when `FD_METRICS=true`, and answers 401 without `Authorization: Bearer <token>` when `FD_METRICS_TOKEN` is set. Labels carry the endpoint id, the method and the status class, never a request path, tenant or session. A module owns counters and histograms of its own through `context.metrics`, the binder the generated composition already bound to its module id (`createModuleMetrics('<module id>')` builds the same one outside a composition): `counter(name, labels?)` adds one to `flowdular_module_<module id>_<name>_total` and `histogram(name, value, labels?)` observes into `flowdular_module_<module id>_<name>` with the request duration buckets (seconds, 0.005 to 10). The module id is lower-cased and every character outside `a-z0-9_` becomes `_`, so `agents.core` reads `flowdular_module_agents_core_`. A metric name matches `^[a-z][a-z0-9_]{0,63}$`, a call carries at most 8 labels whose names match the same shape, a label value is cut at 128 characters, a family holds at most 2000 label sets and a process opens at most 256 module families per kind; every refusal is counted in `flowdular_metrics_dropped_samples_total` and never raises into the module's work. Module series are exposed on the same `/api/metrics` behind the same token (`docs/operations.md`, Metrics). There is still no gauge.
+
+**Tracing.** Every request served through `defineEndpoint` carries a W3C trace context: the caller's `traceparent` when it sent a usable one, a new root otherwise, returned in the response `traceparent` header, present on the handler as `context.trace` and ambient for everything the handler awaits. The logger writes `traceId` and `spanId` on every line inside that scope, so a log search and a trace search answer with the same ids. A module reads the ambient trace with `currentTrace()`, captures it as a header value with `currentTraceParent()` to store on a row it enqueues, and resumes it by handing that value back as `traceparent` when it starts its own span; a row without one is a new root. `resumeJobTrace(tracer, traceparent, name, work)` is that resumption in one call: it opens the span from the stored header, keeps the trace ambient across every await inside `work`, ends the span on the outcome and rethrows what `work` threw, so a background stage and the request that enqueued it share one trace id (`import.core` performs every claimed job through it). `context.tracer` is the tracer of the process (`serverTracer()` outside a composition), and `startSpan(name, { parent?, traceparent?, kind?, attributes?, startedAt? })` answers a span with `setAttribute` and an idempotent `end(status?, message?, endedAt?)`; without a parent or a header it nests under the ambient trace. Spans land in one bounded in-process ring (`TRACE_LIMITS`): 4096 spans, oldest evicted and counted, at most 16 attributes per span and 256 characters per name, key and string value. `createJobTraceSink()` turns a job runner's `onEvent` stream into one span per pass plus one per performed, failed or lost item; a failed item has no duration in the event, so its span is recorded at the instant the runner reported it and the pass span bounds it. Every platform job runner installs it, so a module that passes an `onEvent` of its own is the one case that records no pass spans. The harness takes an optional `tracer` and wraps every provider call and every tool call, including a denial, with the failure code as the span message; `agents.core` hands it the tracer of the process, so an agent run is spans without a module asking for them. Export is the operator's decision and never runs on a request path: `FD_TRACE_EXPORTER=otlp` with `FD_TRACE_OTLP_URL` posts OTLP/HTTP JSON in batches of 512 spans or every 5 seconds, retries a batch at most 3 times and then drops it, and refuses a non-https collector in production. `FD_TRACE_SAMPLE` (0 to 1, default 1) decides a root on its trace id; an unsampled trace still propagates its header. A logged error is also reported through `FD_ERROR_SINK=webhook` with `FD_ERROR_SINK_URL` and an optional `FD_ERROR_SINK_TOKEN` bearer credential: identities only (name, message, endpoint, module, request id, trace id), never a stack, log fields or a credential, bounded to 64 queued reports, 32 per request and 8 KiB per body (`docs/configuration.md` and `docs/operations.md`, Observability).
+
+## Shared UI
+
+Every value exported from `packages/ui/src/index.ts`:
+
+<!-- capabilities:ui-exports -->
+
+`BrandMark`, `MARK_VIEWBOX`, `MARK_WARP`, `MARK_WEFT`, `Icon`, `ICON_PATHS`, `Button`, `FormField`, `Select`, `DateField`, `DateRangeField`, `dateRangeReversed`, `formatDateValue`, `DatePicker`, `DATE_PRESET_IDS`, `datePresetRange`, `FileUpload`, `fileRefusal`, `SearchField`, `CheckGrid`, `Drawer`, `ScopeSummary`, `summarizeScopes`, `SettingRow`, `Tag`, `Table`, `TableCard`, `Pagination`, `pageRange`, `keysetPage`, `Kpi`, `Chart`, `PageHeader`, `EmptyState`, `Alert`, `Avatar`, `Switch`, `ConfirmDialog`, `focusableElements`, `trapFocus`, `Filters`, `Tabs`, `ToastHost`, `createToastStore`, `toasts`, `VariableTextarea`, `VariableInput`, `VariableSelect`, `initials`
+
+<!-- /capabilities:ui-exports -->
+
+`ICON_PATHS`, `MARK_*`, `DATE_PRESET_IDS`, `summarizeScopes`, `initials`, `pageRange`, `keysetPage`, `formatDateValue`, `dateRangeReversed`, `datePresetRange`, `fileRefusal`, `createToastStore` and `toasts` are constants and helpers, not components. There is no other shared component: a screen that needs one builds it module-locally on tokens and flags it as a promotion candidate.
+
+`Drawer` and `ConfirmDialog` trap Tab inside the open panel and return focus to whatever opened it; `trapFocus(root)` is that trap for a module-owned modal (install on open, call the returned release on close) and `focusableElements(root)` lists its Tab stops. `Table` takes `mode="server"` for a list the module already sorted, narrowed and paged in SQL, and a `reason` on a `TableAction` that is read as the refused action's accessible description. `Table` also takes `selection` (`TableSelection`: controlled `selectedKeys`, `onSelectionChange`, `label`, `rowLabel`, `selectable`) for a leading checkbox column whose header toggles the rows on screen, `bulkActions` (`TableBulkAction`, `onSelect(keys)`, same `reason` pattern) in a bar above the table while something is selected, and `selectionSummary(count)` for the polite announcement.
+
+Every visual class is defined once in `packages/ui/src/styles/components.css` and prefixed `ui-` (about 180 names in `ui-block__element--modifier` form; `.num` for tabular figures is the only exception). Tokens live in `tokens.css`. A module composes `ui-*` classes and never restyles one. The writable and component-owned subsets are listed in `.ai/skills/ux-design/SKILL.md`.
+
+## What does not exist yet
+
+None of the following is available. A specification that needs one records it under `outOfScope` with the business decision that covers the gap, and never writes an acceptance scenario, screen, action or agent tool that depends on it.
+
+- E-mail templates as a platform feature. `context.mail` sends a message a module composed itself, with `renderMailTemplate` for the substitution and the escaping; there is no template registry, no per-tenant editing, no layout and no attachment.
+- Outbound HTTP calls from a module of its own. Outbound delivery is `notifications.core`'s signed webhook and a `connectors.core` instance the owner configured and consented to; `risk: 'external'` is refused by the CLI runner and by the harness, so a spec must not declare an `external` action and a module that needs an external system registers a connector definition instead.
+- Multi-row server actions. `Table` selects rows and offers `bulkActions` with the selected keys; the endpoint that acts on many keys at once, its permission and its audit are still the module's own.
+- PDF generation.
+- A tracing or metrics backend of our own. The span API, the trace context, the module-owned counters and histograms and the OTLP exporter exist and are described above; the collector, the dashboards and the alerts are the operator's, and there is no gauge, no span event, no baggage header and no OTLP logs or metrics exporter. Error reporting is one bounded webhook, not an incident tool.
+- An event bus. Modules integrate through the public capabilities registry, synchronously.
+- SAML and LDAP. Authentication is password plus the configured OIDC providers; provisioning is SCIM through `directory.core`.
+- Server-side sorting and filtering written for a module. The screen half exists: `Table` in `mode="server"` reports every sort and page change and renders the rows as they arrive, `pagination.totalRows` is optional there and `pagination.hasMore` carries a keyset page. The `ORDER BY`, the `WHERE` and the count behind them are still the module's own SQL.
+
+## The rule
+
+A specification states what the platform can deliver and nothing else. For every request that lands on the list above, the spec carries one `outOfScope` entry naming the gap and the business decision made instead ("attachments deferred; the invoice number is typed by hand"), and the matching `decisions[]` entry records who decided. Promising a missing capability in an acceptance scenario is a spec defect, and an implementation that finds one reports it back rather than inventing a substitute.
+
+`node scripts/platform-capabilities.mjs --check` (also run by `pnpm verify`) fails when the component, navigation group or slot lists above drift from the code.