create-flowdular 0.3.1 → 0.4.0

package/agent-template/.ai/blueprints/agentic-module/plan.schema.json

@@ -0,0 +1,35 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["blueprint", "moduleId", "specDigest", "steps", "gates"],
+	"properties": {
+		"blueprint": { "const": "agentic-module@1.0.0" },
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"specDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+		"steps": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "type": "string" }
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"enum": [
+					"spec-schema",
+					"module-schema",
+					"dependencies",
+					"typecheck",
+					"tests",
+					"format",
+					"auto-review"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/agent-template/.ai/blueprints/agentic-module/required-files.yaml

@@ -0,0 +1,28 @@
+schemaVersion: 1
+# In addition to the new-module file set; the scaffold writes the first three
+# kinds from the spec sections.
+conditional:
+  research:
+    whenSpecSection: research
+    required:
+      - src/research.ts
+      - research-fixtures.json
+      - the evidence attach in the service that stores a finding
+      - tests for a finding without evidence and for another tenant's evidence
+  adapters:
+    whenSpecSection: adapters
+    required:
+      - src/adapters/<name>.ts for every adapter
+      - the recorded fixture, adapters/<name>.recorded.json unless the entry names another path
+      - tests replaying the recorded fixture
+  templates:
+    whenSpecSection: templates
+    required:
+      - templates/<name>.md for every template body
+      - templates in package.json files
+  agent:
+    whenSpecSection: agentTools
+    required:
+      - src/agent/tools.ts with evidenceIds on every tool that stores a finding
+      - src/agent/agents.ts
+      - tests/agent-tools.test.ts

package/agent-template/.ai/blueprints/agentic-module/spec-requirements.yaml

@@ -0,0 +1,33 @@
+schemaVersion: 1
+# Every key below exists in packages/contracts/schemas/module-spec.schema.json.
+specSchemaVersion: 2
+status:
+  allowed:
+    - approved
+requiredKeys:
+  - entities
+  - actions
+  - agentTools
+  - acceptanceScenarios
+  - outOfScope
+  - decisions
+sections:
+  research:
+    evidenceOwner: the case entity, the record findings attach to
+    adapter: recorded in a sandbox session; the adapter the owner picks after delivery is a decision
+  adapters:
+    port: a source writes through an import port of this module, <module id>.<key>
+    recorded: required in a sandbox session, whose spec-schema gate refuses a live adapter with SANDBOX_LIVE_ADAPTER_REFUSED
+  templates:
+    inputEntity: the case entity
+    render: the module registers the body through documents.templates.v1 and renders it for the case record
+actions:
+  compute: one custom action per computed figure, idempotent, naming the rule version it applies
+acceptanceScenarios:
+  mustInclude:
+    - a finding without evidence is refused before any write
+    - a finding citing evidence of another tenant is refused
+    - the computed figure is the same for the same inputs and names its rule version
+    - an agent run without research consent is refused with TOOL_NOT_CONSENTED
+    - nothing leaves the workspace before the approval is granted
+    - tenant isolation

package/agent-template/.ai/blueprints/agentic-module/steps.yaml

@@ -0,0 +1,68 @@
+schemaVersion: 1
+steps:
+  - id: spec
+    role: business-manager
+    action: Interview the brief with spec-interview, including outside sources, other systems and documents; write research, adapters and templates with recorded fixtures in a sandbox session; stop for approval.
+    inputs: [brief]
+    outputs: [spec/module.yaml]
+    gates: [spec-schema]
+  - id: approve
+    role: operator
+    action: Approve the exact specification. No agent does this.
+    inputs: [spec/module.yaml]
+    outputs: [spec/module.yaml]
+  - id: scaffold
+    role: orchestrator
+    action: pnpm flowdular module new <id> --spec modules/<dir>/spec/module.yaml --apply, which also writes src/research.ts, research-fixtures.json, src/adapters/<name>.ts, adapters/<name>.recorded.json and templates/<name>.md.
+    inputs: [spec/module.yaml]
+    outputs:
+      [
+        src/research.ts,
+        research-fixtures.json,
+        src/adapters/*.ts,
+        adapters/*.recorded.json,
+        templates/*.md,
+      ]
+  - id: server
+    role: backend-engineer
+    action: The case entity, the compute actions with their rule version, and the service that stores findings with evidence ids, per module-new.
+    inputs: [spec/module.yaml]
+    outputs:
+      [
+        src/services/*.ts,
+        src/api/endpoints.ts,
+        migrations/*.sql,
+        tests/*.test.ts,
+      ]
+    gates: [module-schema, dependencies, typecheck, tests, format]
+  - id: adapters
+    role: backend-engineer
+    action: Every adapters[] entry per integration-adapter, on its recorded fixture.
+    inputs: [spec/module.yaml, src/adapters/*.ts]
+    outputs: [src/adapters/*.ts, adapters/*.recorded.json, tests/*.test.ts]
+    gates: [dependencies, typecheck, tests, format]
+  - id: agent-surface
+    role: agentic-engineer
+    action: Tools that store findings with evidence ids and call the compute actions, and the business agent that lists research.search and research.fetch, per agent-tool-design and business-agent-design.
+    inputs: [spec/module.yaml, src/api/endpoints.ts]
+    outputs:
+      [src/agent/tools.ts, src/agent/agents.ts, tests/agent-tools.test.ts]
+    gates: [spec-schema, module-schema, dependencies, typecheck, tests]
+  - id: workflow
+    role: agentic-engineer
+    action: The case workflow ending in a human-approval node before anything leaves the workspace, per workflow-development.
+    inputs: [src/agent/agents.ts]
+    outputs: [tests/*.test.ts]
+    gates: [typecheck, tests]
+  - id: client
+    role: frontend-engineer
+    action: The case record screen with its evidence list and the five states, per ux-design.
+    inputs: [src/api/endpoints.ts]
+    outputs: [src/client/*.tsrx, src/client/*.ts, translations/*.json]
+    gates: [dependencies, typecheck, tests, format]
+  - id: review
+    role: reviewer
+    action: auto-review against the spec, with the evidence, computation and approval scenarios checked first.
+    inputs: [diff, gate evidence]
+    outputs: [review report]
+    gates: [auto-review]

package/agent-template/.ai/platform-capabilities.md

@@ -14,7 +14,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **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.
+**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; the same capability answers `find(id)` with the registered declaration or null, for a module that pages a list itself under a principal holding the list's permission. `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`.)
 
@@ -24,7 +24,9 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **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`):
+**Module activation.** The composed module set is CLI-owned and baked at build; what an owner changes from Administration, Modules is per-workspace activation of the modules the application already composes. `system.core` keeps it in `system_module_activations` (a composed module without a row is active), lists it through `GET /api/system/modules` (every catalog row with `active`, `optional` and `dependents`) and `GET /api/system/modules/active` (the active composed ids, for any member holding `system.workspace.access`), and changes it through `POST /api/system/modules/activate` and `/api/system/modules/deactivate` behind `system.settings.manage` with CSRF first. `system.core`, `auth.core`, `users.core` and `profile.core` (`REQUIRED_MODULE_IDS` in `@flowdular/sdk/contracts`) are never deactivated; a module another active module depends on, through a declared module dependency or a required capability, is refused with 409 `MODULE_HAS_ACTIVE_DEPENDENTS` naming the dependents, a required one with 409 `MODULE_REQUIRED`, and activating a module whose dependency is inactive with 409 `MODULE_DEPENDENCY_INACTIVE`. Every change appends one `system.module.activated` or `system.module.deactivated` auth audit event. The state is one per-tenant snapshot memoised for 30 seconds and published as the public capability `system.modules.v1` (`isActive(tenantId, moduleId)`, `activeIds(tenantId)`, `modules/system/src/server/capability.ts`). Enforcement costs a module nothing: the generated composition binds every route to its module id (`bindModuleCompositions`, `packages/server/src/module-activation.ts`), `defineEndpoint` answers 403 `MODULE_INACTIVE` after the permission check for an endpoint of an inactive module in the principal's workspace (`EndpointIdentity.tenantId` comes from `endpointIdentityFromContext`), and the application shell reads the active ids before it renders and hides the navigation, views, widgets and command search of an inactive module (`contributionsForActiveModules`, `packages/client/src/shell/modules.ts`; a failed read shows everything). Not covered yet: the agent tools of an inactive module are still offered, because the harness registry has no per-tenant module hook.
+
+**Navigation groups.** A navigation contribution picks exactly one group (`NavigationGroup`, `packages/client/src/contributions.ts`): An Administration item also names a section (`NavigationSection`: `people`, `identity`, `compliance`, `integrations`, `platform`), and the panel renders that group as five short labelled lists in that order with unsectioned items last (`navigationSections`, `packages/client/src/shell/navigation.ts`). In the sidebar a sectioned group shows one entry per section (`NAVIGATION_SECTION_ICONS`), and while a sectioned view is open a context rail beside the sidebar lists that section's screens and the workspace makes room for it (`ContextRail`, `sectionOfView`, `sectionItems`); on a phone the same screens nest under the section entry in the drawer instead.
 
 <!-- capabilities:navigation-groups -->
 
@@ -42,7 +44,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **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.
+**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. A tool the model provider executes itself, such as a web search, is registered with `context.agentTools.registerNative({ id, kind: 'web-search', config, requiredPermissions, consent?, resolveConfig?, record? })` (`AgentNativeTool`, `packages/harness/src/runtime.ts`): it shares the tool id space, a definition allows and a run grants it by exact id, the harness asks its consent gate once when the run starts and hands the admitted ones to the provider as `AgentProviderContext.nativeTools`, and the provider reports citations through `reportNative`, which the harness bounds, records on the run as a `tool.native` event and passes to `record`; a `NATIVE_TOOL_UNSUPPORTED` report reaches `record` too, as `{ query: null, results: [], unsupported: { code, detail } }` after the same live permission check, and a refused check only withholds it, never failing the run. The local simulation provider answers a native web search from the `research-fixtures.json` named by `AgentExecutionRequest.nativeFixturesPath`. The Vercel AI SDK provider passes one granted web search to the model provider's own tool (`packages/ai-provider/src/web-search.ts`): Anthropic `web_search_20250305` with `maxUses` from the config (default 5, at most 16) and OpenAI `web_search` with `max_tool_calls` set the same way, both with `allowedDomains` sent alone or else `blockedDomains`. It reports each search with its URLs, titles, cited text and page age (`source` is the provider kind) when the model call's stream ends, before any tool the model called in that call runs, at most 16 reports per run with the overflow merged into the last. Azure, OpenAI-compatible and Vercel AI Gateway models report `NATIVE_TOOL_UNSUPPORTED` and the run goes on. So does an Anthropic or OpenAI request the provider refuses over the web search tool itself (a 400 or 403 request or permission error whose message names web search): the model call is retried once without the tool, the tool stays out for the rest of the run, and the `tool.native` event carries `detail: PROVIDER_WEB_SEARCH_DISABLED`; any other provider error fails the run as before.
 
 **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.
 
@@ -52,7 +54,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **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` and non-local `destructive` commands unless `--grant <token> --tenant <id>` carries a verified approval grant for the capability and the invocation digest, 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`.
+**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()`. A count is a plural family (`<key>.one`/`.other` in `en`, `<key>.one`/`.few`/`.many`/`.other` in `pl`) read as `t(key, { count })`. `flowdular module validate` reports `TRANSLATION_FILE_MISSING`, `TRANSLATION_PARSE_ERROR`, `TRANSLATION_KEYS_MISMATCH`, `TRANSLATION_PLURAL_INCOMPLETE` 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.
 
@@ -64,17 +66,21 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **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.
+**Connectors.** `connectors.core` (optional) is the governed way out to an external system; its egress policy is also the public capability `connectors.egress.v1` for a module that opens one public URL of its own (`modules/connectors/src/domain/egress.ts`). 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, answering `retryAfterMs` from a 429 or 503 `Retry-After` header; `consented(tenantId, instanceId, caller)` answers admission alone. A module keeps its own instance of its own definition through `connectors.instances.v1` (`modules/connectors/src/domain/instances.ts`): `upsertModuleInstance({ tenantId, moduleId, key, definition, baseUrl, credentials?, allowedHosts, allowAgents, allowWorkflows, actor })` creates or updates the one instance per workspace, module and key (absent credentials keep the sealed one; a definition of another module answers `DEFINITION_FOREIGN`), and `describeModuleInstance({ tenantId, moduleId, key })` answers it with `hasCredentials` and never a credential. 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.
+
+**Research.** `research.core` (optional) searches the web and reads public pages for agents, workflows and members, and keeps what they read as citeable evidence. A search runs an ordered chain of adapters: `model-native` (reached only by an Anthropic or OpenAI model inside an agent run through the native tool `research.web-search`), `searxng` (a self-hosted SearXNG, `GET /search` with `format=json`), `firecrawl` (the Firecrawl API, `POST /v2/search`), `connector` (the `connectors.core` instance named by `connectorInstanceId`, operation `search`, input `{ q, limit }`) and `recorded` (a `research-fixtures.json` file `{ queries: { [query]: ResearchResult[] }, pages: { [url]: { title, text } } }` at the absolute or workspace-relative `recordedFixturesPath`, for tests and the sandbox). The owner orders and switches them on the Search adapters tab behind `research.settings.manage` (settings `searchOrder` and `<key>Enabled`; while `searchOrder` is empty the single setting `research.core.adapter`, default `model-native`, decides), with `<key>MaxAttempts` (1 to 5), `<key>TimeoutMs`, full jitter backoff `retryBackoffMs` capped at 5 s, `Retry-After` honoured on a 429, `fallback` (`next-adapter` or `fail`), `fallbackOnEmpty`, and a per-workspace circuit breaker (`circuitFailureThreshold`, `circuitCooldownMs`, one half open probe); every attempt is a `research_attempts` row. A fetch runs `fetchOrder` over `direct` (the module's own reader) and `firecrawl` (`POST /v2/scrape`, JavaScript rendered to markdown), and a domain rule, robots.txt, the egress policy or the size cap never falls back. A provider that reports the native web search unsupported marks `model-native` Unsupported on the tab and makes its read back a permanent failure the chain passes over. SearXNG and Firecrawl are reached only through module-owned `connectors.core` instances (definitions `research-searxng` and `research-firecrawl`) whose credentials connectors.core seals and whose consent follows `allowAgents`. A module resolves `research.search.v1` (`search({ tenantId, query, limit?, freshness?, site?, caller, callerRef? })` answering `{ results, adapter, attempts }`, the adapter being the one that answered), `research.fetch.v1` (`fetch({ tenantId, url, caller, callerRef? })` answering `{ evidenceId, title, text, truncated, contentSha256, retrievedAt }`) and `research.evidence.v1` (`attach(tenantId, ownerModule, recordRef, evidenceIds)`, `list(tenantId, ownerModule, recordRef)`, `get(tenantId, id)`), all in `modules/research/src/domain/capability.ts`. Every answered search counts one unit, whatever the chain tried, against `monthlyQueryBudget` under a per-workspace lock and the meter `research.core.queries`, and past it answers `RESEARCH_BUDGET_EXCEEDED` (429); the allow and deny domain lists filter results and refuse fetches with `RESEARCH_DOMAIN_DENIED`. A fetch reaches the network only through `connectors.egress.v1` (`check(url)` answering the verified addresses and a lookup pinned to them), honours `robots.txt` (cached per host for an hour), follows one redirect, stops at `fetchMaxBytes` and `fetchTimeoutMs`, turns HTML into text with its own extractor, reads a PDF the direct reader downloaded through `documents.text.v1` `extractBytes` when documents.core is composed and answers `RESEARCH_CONTENT_UNSUPPORTED` for it otherwise, caches pages for 24 hours and allows 64 fetches per run. Every kept result and fetched page is a `research_evidence` row with the sha256 and a 4 KB excerpt, the full text only while `storeFullText` is on. The agent tools `research.search` and `research.fetch` are `workspace-write` behind the consent gate `research.consent` (setting `allowAgents`, off by default, refusing with `TOOL_NOT_CONSENTED`). The Research screen (Administration, section compliance) lists Evidence and Queries (a query opens its attempts) and, for owners, Search adapters, and another module links to one piece of evidence with `workspaceViewHref('research-evidence') + '?id=' + id`. Not covered yet: full text stored as a document.
 
 **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. A request whose `subjectRef` is `encodeCapabilitySubjectRef({ capabilityId, inputDigest })` yields, once approved, a signed token through `grant(tenantId, id, subjectModule)`, handed only to the module that opened it; the CLI runner takes it as `--grant` (valid until expiry) and the harness as `AgentExecutionRequest.grants` (one tool call per grant), both bound to the tenant, the capability id and `approvalInputDigest` of the input.
 
-**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.
+**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. The text of a document comes from the public capability `documents.text.v1` (`modules/documents/src/domain/text.ts`): `extract(tenantId, ownerModule, recordRef, id, { pages? })` for a document of the caller's reference pair (null for every reference `open` answers null for) and `extractBytes({ contentType, bytes, pages?, signal? })` for bytes that are not stored, both answering `{ status: 'ok' | 'unscanned' | 'unsupported' | 'too-large' | 'pending', reason, text, pages, from, to, truncated, contentSha256 }` with the pages of the text separated by a form feed and `pages` a 1-based `{ from, to }` range. A PDF is read from its text layer page by page (pdf.js through `unpdf`, nothing executed or fetched), a PPTX slide by slide, an XLSX as one block per sheet with tab separated rows, and a DOCX, a CSV or a plain text file in pages of at most 10000 characters; the legacy `.doc` and `.xls` answer `unsupported`. At most 200 pages and 2 MiB of text are kept (`truncated` beyond), input over 25 MiB answers `too-large`, and an OOXML package stops at 32 MiB of bytes actually inflated. A PDF without a text layer and an image answer `unscanned` unless the deployment sets `FD_DOCUMENTS_OCR_URL` (and `FD_DOCUMENTS_OCR_TOKEN`), which receives the bytes through the `connectors.egress.v1` address rules. The text of a stored document is kept in `documents_text` by document and checksum, so a second read parses nothing; a document over 2 MiB or one sent to OCR answers `pending` until the text runner settles it. `POST /api/documents/text` (behind `documents.files.read`) and `POST /api/documents/text/retry` (behind `documents.files.manage`, unscanned text while OCR is available) serve the Text tab of the document details, and the agent tool `documents.read-text` (risk `read`, `documents.files.read`) answers a page range of a record's document cut to 20000 UTF-8 bytes. Documents from templates come from the public capability `documents.templates.v1` (`modules/documents/src/domain/templates.ts`): a module calls `register(moduleId, [{ key, title, format, body, inputSchema, locale, layout }])` while it composes (`key` is `<module id>.<name>`, `format` `pdf` or `docx`, `locale` `en` or `pl`, at most 256 templates, every template validated at once and refused at boot with `TEMPLATE_REGISTRATION_INVALID` naming the line, the catalogue sealed when documents.core starts), then `render({ tenantId, principal: { accountId, scopes }, ownerModule, recordRef, templateKey, input, format? })` for its own record after checking its own record permission, answering `{ jobId, status, documentId, errorCode, templateKey, version, format }` with `status` `queued`, `running`, `succeeded` or `failed`, and `status(tenantId, jobId)` later; `render` refuses a principal without `documents.files.manage` with `FORBIDDEN`. A body is Markdown restricted to headings 1 to 3, paragraphs with bold, italic, inline code and links (printed as the text and the URL in parentheses), bulleted and numbered lists one level deep, block quotes, a rule, the line `---pagebreak---` and pipe tables, plus HTML comments on lines of their own, which are dropped; HTML, images, footnotes, reference links, code blocks, setext and level 4 headings are refused with a stable code and the line. The body is parsed first and `{{ path }}` is substituted into text nodes after, so an input value is printed as text and never read as Markdown. The formatters are `money: currency` (minor units and an ISO 4217 field or quoted code), `number: 0..6`, `date` and `datetime` (the workspace zone from `system.core.timeZone` and the template locale; a `YYYY-MM-DD` date is not shifted), `upper` and `yesno`, one per placeholder; `{{#each path}}` repeats table rows or blocks with `this`, `@index` (from 0) and `@number` (from 1), `{{#if path}} {{else}} {{/if}}` keeps rows or blocks, each block tag on a line of its own, and a path is searched from the innermost item outwards through own properties of the input only. The input schema is a JSON Schema subset (an object root; object, string with `maxLength` and `enum`, number, integer, boolean, array of an object or a scalar; `required`, `title`, `description`; at most 4 levels and 64 properties per object), every placeholder is checked against it at validation (`TEMPLATE_FIELD_UNKNOWN`, `TEMPLATE_FIELD_TYPE`), and a render validates the input first (`TEMPLATE_INPUT_INVALID` with up to 20 issues naming the path). `templateInputSchemaFromFields(fields)` builds the schema from a spec entity. A layout is the page size `A4` or `Letter`, margins of 5 to 60 mm, a one-line header and footer with placeholders plus `{{page}}` and `{{pages}}`, and a title that also names the stored file. Bounds: a body of 65536 characters and 8 nested blocks, 2000 repeated rows or blocks (`TEMPLATE_ROWS_EXCEEDED`), 1000000 printed characters (`TEMPLATE_OUTPUT_TOO_LARGE`), 200 PDF pages (`TEMPLATE_PAGES_EXCEEDED`), an input of 256 KiB, strings of 10000 characters and arrays of 2000 items. A workspace uses the module default until it renders or edits a template; then `document_template_versions` keeps the default as version 1 and `document_templates` names the current version. A save appends an immutable version (`TEMPLATE_VERSION_CONFLICT` on a stale expected version, `TEMPLATE_UNCHANGED` when nothing changed), a restore appends a copy of an earlier version and a revert a copy of the module default; a workspace whose current version came from the default or a revert follows a changed default on its next render, an edited one keeps its edit. A render is a `document_renders` row unique by workspace, template key, version, owner module, record reference, format and input digest, so a repeated render answers the same row, a failed one is queued again and one whose document was deleted renders again under the next generation; the input is kept until the render settles. A render of at most 50 repeated rows and 16 KiB of input runs within the call, any other on the job runner `documents.core.render` (heartbeat, five minute stale takeover, `CLAIM_LOST`, three attempts before `TEMPLATE_RENDER_FAILED`); the bytes go through the storage port under an object id derived from the render id and the `documents_files` row of the owning record is inserted in the transaction that marks the render succeeded while the claim holds, so a process that dies mid render repeats it without a second document, and the workspace quota applies (`QUOTA_EXCEEDED`). PDF is rendered by pdfmake 0.3.11 over pdfkit with the Roboto family embedded (Latin Extended, so Polish renders), tables repeating their header row across pages and a header and footer on every page, with every URL and file access refused; DOCX by docx 9.5.1 with a repeated header row and page number fields; both behind a renderer interface, server side only. `GET /api/documents/templates`, `/detail`, `/versions` (keyset paged) and `/version` and `POST /api/documents/templates/preview` (the draft rendered to bytes, nothing stored, at most two at a time per process, `TEMPLATE_PREVIEW_BUSY` 429 beyond) sit behind `documents.templates.read` (members), `POST /api/documents/templates/save` and `/revert` behind `documents.templates.manage` (owners), every POST CSRF first. The agent tool `documents.render` (risk `workspace-write`, `idempotency: 'required'`, `target-ledger`) requires `documents.templates.read` and `documents.files.manage`; its harness key is bound in `document_render_keys` to the render it first reached with the request digest, so a retry answers that render even after the template gained a version and a key reused for another request is refused with `TEMPLATE_RENDER_KEY_REUSED`, and `documents.render-status` (risk `read`, `documents.templates.read`) reads a job by id. Versions are the data class `documents.core.templates` (kept) and renders `documents.core.renders` (90 days, settled rows only, exported without the input). The Templates screen (Administration, section platform) lists the registered templates and opens an editor with line numbers, layout fields, a sample input, a preview in the browser's own PDF viewer or a DOCX download, and the version history with a diff, Restore and Revert.
 
 **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/sdk/modules/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.
+**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/sdk/modules/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. A module that already holds rows writes them without a CSV or a job through `import.write.v1` (`modules/import/src/domain/write.ts`): `describe(moduleId, portKey)` answers the port's fields, natural key, permission and the platform `batchSize`, and `validate` and `write({ tenantId, principal, moduleId, portKey, rows, mode, sourceRef })` take at most one batch, refuse a principal of another workspace (`PRINCIPAL_TENANT_MISMATCH`) or without the port's permission (`TARGET_FORBIDDEN`) before any port code runs, check the field shapes (`FIELD_UNKNOWN`, `FIELD_REQUIRED`, `FIELD_TYPE`) and a natural key repeated in the call, run the port's `validate` and then its `write`, and answer one outcome per row in the order given (`created`, `updated`, `skipped`, `invalid`, `failed`); nothing is recorded by import.core.
+
+**Adapters.** `adapters.core` (optional) runs the source and sink adapters a module's spec declares, so a module pulls records from another system into an import port or pushes a list export out to it without a run table, job or timer of its own. A module registers them while it composes through `adapters.sources.v1` or `adapters.sinks.v1` (`modules/adapters/src/domain/registry.ts`): `register(moduleId, [{ id, direction, label, connector, operation, port, schedule?, mapping, recorded?, input?, items?, paging?, mode?, batchSize? }])`, where `id` starts with the module id, `input` is the operation input every call starts from, `items` the answer path of a source's record array or the input path of a sink's batch, `paging` either `{ kind: 'cursor', param, next }` or `{ kind: 'page', param, start? }`, `mode` a source's import mode (`update-existing` by default), `batchSize` a sink's rows per push (1 to 200, default 50), and `recorded` the parsed `adapters/<name>.recorded.json` `{ adapter, operation, calls: [{ input, body }] }`; a sink pushes a list of the registering module only, anything malformed throws `ADAPTER_REGISTRATION_INVALID` at boot, and the registry is sealed when adapters.core starts. An owner binds each adapter on the Data adapters screen (Administration, section integrations) behind `adapters.runs.manage` (owners; `adapters.runs.read` to read): a `connectors.core` instance of the declared definition, the enabled switch, a schedule override (the declared five-field cron, on demand, or another cron in the workspace zone) and a mapping override stored as data, checked against the port's fields or the list's columns. Mapping rules are `rename`, `constant`, `format` (`trim`, `lower`, `upper`, `integer`, `decimal`, `boolean`, `iso-date`, `date:<layout>`) and `lookup` through a table stored with the rule (the port contract has no lookup of its own), refusing a row with `MAPPING_VALUE_INVALID`, `MAPPING_FORMAT_INVALID` or `MAPPING_LOOKUP_UNMATCHED`. `POST /api/adapters/dry-run` reads the first page, maps up to 20 rows and runs the port's `validate` without writing. A run (`POST /api/adapters/runs/start`, a schedule, or `resume` of the latest failed or cancelled run from its cursor) is an `adapter_runs` row claimed by the shared job runner with a renewed lease: every call goes through `connectors.calls.v1` with caller `workflow` after `consented`, as the account that started it or last saved the binding, resolved live, a source writes through `import.write.v1` and a sink walks `exports.lists.v1` under that account, each page is tried three times with full jitter and `Retry-After`, the outcomes, counts and next cursor commit once per page fenced by the claim, a dead process is taken over from the stored cursor, a sink stores its row position rather than the list's own cursor (a list signs cursors per process) and pushes under an idempotency key per run chain, row position and slot, and every record ends as one `adapter_run_rows` outcome. One run per adapter is queued or running at a time (`ADAPTER_RUN_ACTIVE`), a due schedule while one is active is skipped and recorded, runs stop at 1000 pages and pages at 1000 records. An unbound adapter answers from its recorded fixture outside production (exact input first, then a contained one) and is `ADAPTER_NOT_BOUND` in production. Binding, enabling, run start, resume, cancel and a skipped schedule append `adapter_audit_events`; the meter `adapters.core.rows` counts rows written; data classes `runs` (90 days), `run-rows` (30 days), `bindings` and `audit` (kept); the run list is the export `adapters.core.runs`. Not covered: an adapter caller kind of its own in connectors.core, a lookup against the target module's records, and a sink over a query rather than a list export.
 
 **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/sdk/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.
 
@@ -98,13 +104,13 @@ 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`
+`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`, `CellCode`, `CellMuted`, `CellNumber`, `CellStack`, `CellTag`, `CellText`, `CellTime`, `Table`, `DEFAULT_TABLE_LOCALE`, `TableLocaleContext`, `TableCard`, `Pagination`, `pageRange`, `keysetPage`, `Kpi`, `Chart`, `PageHeader`, `EmptyState`, `Alert`, `Avatar`, `Switch`, `ConfirmDialog`, `focusableElements`, `trapFocus`, `Filters`, `Tabs`, `SortableList`, `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.
+`ICON_PATHS`, `MARK_*`, `DATE_PRESET_IDS`, `summarizeScopes`, `initials`, `pageRange`, `keysetPage`, `formatDateValue`, `dateRangeReversed`, `datePresetRange`, `fileRefusal`, `createToastStore`, `toasts`, `DEFAULT_TABLE_LOCALE` and `TableLocaleContext` 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.
+`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. A table cell is one of the typed cells (`CellText`, `CellStack`, `CellTime`, `CellCode`, `CellTag`, `CellNumber`, `CellMuted`), which never break inside a word and end a long value in an ellipsis with the value as its title; a `TableColumn` takes `priority` 1, 2 or 3, a narrow card hides columns one at a time (priority 3 before 2, the last declared first) before the table scrolls, and each row then expands to list the hidden columns. More than two row actions, or two in a narrow card, fold into one More menu, and a clickable row opens from a button in its first cell. The shell provides the table copy and locale through `TableLocaleContext`; a screen passes neither (`docs/design-system.md`, section Tables). `SortableList` is the reorderable list (`items`, `onReorder(ids)` once per committed drop, `handleLabel`, `instructions`, `announce(event)`, `renderItem`): a grip per item drags with a pointer or, from the keyboard, Space picks up, the arrows move, Space drops and Escape cancels, each step announced in a polite live region.
 
 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`.
 
@@ -115,7 +121,6 @@ None of the following is available. A specification that needs one records it un
 - 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`.

package/agent-template/.ai/references/catalog/migrations/0005_catalog_list_indexes.down.sql

@@ -0,0 +1,3 @@
+DROP INDEX IF EXISTS catalog_items_tenant_updated_idx;
+DROP INDEX IF EXISTS catalog_items_tenant_name_idx;
+ALTER TABLE catalog_items DROP COLUMN IF EXISTS updated_at;

package/agent-template/.ai/references/catalog/migrations/0005_catalog_list_indexes.up.sql

@@ -0,0 +1,11 @@
+ALTER TABLE catalog_items ADD COLUMN IF NOT EXISTS updated_at BIGINT NOT NULL DEFAULT 0;
+-- The backfill runs as the migrator, which forced row security keeps out of
+-- every row without a tenant setting; lift the flag for the statement only.
+ALTER TABLE catalog_items NO FORCE ROW LEVEL SECURITY;
+UPDATE catalog_items SET updated_at = created_at WHERE updated_at = 0;
+ALTER TABLE catalog_items FORCE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items ALTER COLUMN updated_at DROP DEFAULT;
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_name_idx
+  ON catalog_items (tenant_id, lower(name), id);
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_updated_idx
+  ON catalog_items (tenant_id, updated_at, id);

package/agent-template/.ai/references/catalog/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "catalog.core",
 	"package": "@flowdular/module-catalog",
-	"version": "0.7.1",
+	"version": "0.8.1",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations"],
 	"platform": {
@@ -13,11 +13,21 @@
 	"dependencies": [
 		{
 			"id": "system.core",
-			"range": "^0.7.0"
+			"range": "^0.8.0"
 		},
 		{
 			"id": "auth.core",
 			"range": "^0.13.0"
+		},
+		{
+			"id": "exports.core",
+			"range": "^0.2.0"
+		}
+	],
+	"requires": [
+		{
+			"id": "exports.lists.v1",
+			"optional": true
 		}
 	],
 	"tenancy": "required",

package/agent-template/.ai/references/catalog/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-catalog",
-	"version": "0.7.1",
+	"version": "0.8.1",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.0",
-		"@flowdular/sdk": "0.3.0"
+		"@flowdular/sdk": "0.3.2"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/agent-template/.ai/references/catalog/spec/module.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 1
 id: catalog.core
-specVersion: 0.7.1
+specVersion: 0.8.1
 status: approved
 name: Product Catalog Core
 description: Provides tenant-scoped products and services with stable SKUs, units, prices, currencies, and lifecycle state.
@@ -12,9 +12,14 @@ capabilities:
   - translations
 dependencies:
   - id: system.core
-    range: ^0.7.0
+    range: ^0.8.0
   - id: auth.core
     range: ^0.13.0
+  - id: exports.core
+    range: ^0.2.0
+requires:
+  - id: exports.lists.v1
+    optional: true
 tenancy: required
 locales:
   - en
@@ -30,6 +35,10 @@ invariants:
   - One tenant-scoped durable target ledger is shared by mutating agent tools and workflow actions; each entry binds an idempotency key to the exact tool identifier or versioned workflow action identifier, canonical input digest, and first persisted result in the same transaction as the catalog mutation.
   - Replaying the same idempotency key for the same operation and canonical input returns the original result without another catalog item or history row, while reuse for another operation or input fails with a stable conflict.
   - Idempotency ledger entries remain after a catalog item is deleted, and audit metadata records identifiers, input digests, and outcomes without raw tool input, credentials, secrets, or result payloads.
+  - The items list is answered one page at a time on the shared signed cursor, at most 200 rows per read and 50 by default, ordered by lower-cased name, by normalized SKU or by the last update time, each order ending in the item id, narrowed in SQL by kind, by status and by a substring of the name or the SKU, and read as one index range over the matching (tenant_id, sort expression, id) index. A cursor is bound to the workspace, the sort, the direction and a digest of the filters, and a cursor of another listing or another workspace is refused with CURSOR_INVALID. No unbounded read of a workspace's items exists; the agent list tool and the dashboard widget read one bounded page.
+  - Every item carries the time of its last accepted mutation, set when it is created, edited, archived or restored, so the list can be ordered by recency.
+  - The items list export registered with exports.lists.v1 as catalog.core.items declares the SKU, name, kind, unit, base price in minor units, currency and status columns, is behind catalog.items.read, and is walked by exports.core under the principal that started the job through the same paged read the list endpoint answers, in SKU order. A deployment without exports.core still composes catalog.core and registers nothing.
+  - The bulk archive and bulk restore routes are siblings of the single-row lifecycle routes under the same permission and CSRF rule. Each names 1 to 100 unique item ids and executes the single-row path per id, so every accepted transition keeps its own history row and the idempotency ledger is untouched; an id that is missing or of another workspace answers not-found and a refused id answers refused with its stable code, and neither fails the other ids.
   - catalog.core declares three data classes to the platform registry while it composes and performs their export itself on its own lease under its own tenant transaction. catalog.core.items and catalog.core.history are master data, and each export walks every row of one workspace by keyset in bounded pages, and neither class carries a retention period, a sweep, or an erasure, so a row leaves only when a person deletes it. catalog.core.idempotency-ledger is operational, is never swept, and is excluded from the export with a stated reason because the item it points at is already exported.
 permissions:
   - id: catalog.items.read
@@ -37,15 +46,27 @@ permissions:
   - id: catalog.items.manage
     description: Create and update products and services in the active tenant.
 dataOwnership:
-  - catalog.core owns SKU, item identity, kind, unit, base price, currency, and lifecycle status.
+  - catalog.core owns SKU, item identity, kind, unit, base price, currency, lifecycle status, and the last update time.
   - catalog.core owns the idempotency ledger for its mutating agent tools and workflow actions; callers supply the key but do not maintain a second target ledger.
   - catalog.core declares the data classes catalog.core.items (catalog_items), catalog.core.history (catalog_items_history_v2, which holds every row of the superseded catalog_items_history) and catalog.core.idempotency-ledger (catalog_idempotency_ledger); items and history are exported per workspace, the ledger is excluded with a stated reason.
   - Sales and purchasing modules reference catalog item identifiers and snapshot commercial terms when required by their specs.
 acceptanceScenarios:
   - id: CATALOG-LIST
     given: Tenant-scoped products and services exist.
-    when: An authorized principal lists catalog items.
-    then: Only items owned by the active tenant are returned in deterministic SKU order.
+    when: An authorized principal lists catalog items with a sort, a direction, filters and a page size.
+    then: Only items owned by the active tenant are returned, in the requested order ending in the item id, narrowed by kind, status and search in SQL, one page at a time with a cursor only on a full page, and two consecutive pages neither overlap nor leave a gap.
+  - id: CATALOG-LIST-CURSOR
+    given: A page cursor was issued for one listing of one workspace.
+    when: It is presented tampered, by another workspace, with other filters or with another sort, or an unknown sort is requested.
+    then: The server answers 400 with CURSOR_INVALID for the cursor and INVALID_INPUT for the sort, before any repository read.
+  - id: CATALOG-LIST-EXPORT
+    given: exports.core composed and registered its list capability.
+    when: catalog.core composes and a principal with catalog.items.read starts an export of catalog.core.items.
+    then: The catalogue lists the export with its declared columns and the job streams every item of the principal's workspace in SKU order, page by page, and no item of another workspace.
+  - id: CATALOG-BULK-LIFECYCLE
+    given: A principal with catalog.items.manage selects several items on the list.
+    when: The principal archives or restores the selection, naming a missing id and an id of another workspace beside existing ones.
+    then: Each existing item transitions with its own history row, the missing and foreign ids answer not-found, the call answers one outcome per id, the screen tells the counts, and a body without ids, with more than 100 ids, with a repeated id or without a valid CSRF token is refused.
   - id: CATALOG-CREATE
     given: An authorized principal supplies a unique SKU and valid product or service data.
     when: The catalog item is created.

package/agent-template/.ai/references/catalog/src/agent/tools.ts

@@ -8,7 +8,10 @@ import { agentActor, type Actor } from '@flowdular/sdk/kernel';
 import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
 import type { CatalogItemKind } from '../domain/types.ts';
 import type { CatalogRuntime } from '../server/runtime.ts';
-import { CatalogServiceError } from '../services/catalog-service.ts';
+import {
+	CatalogServiceError,
+	FIRST_LIST_PAGE,
+} from '../services/catalog-service.ts';
 
 const MAX_TOOL_ROWS = 200;
 const CREATE_OPERATION = 'catalog.item.create@1';
@@ -39,6 +42,7 @@ const CATALOG_ITEM_OUTPUT_SCHEMA = {
 		currency: { type: 'string' },
 		status: { type: 'string', enum: ['active', 'archived'] },
 		createdAt: { type: 'integer' },
+		updatedAt: { type: 'integer' },
 	},
 } as const;
 
@@ -91,15 +95,20 @@ export function catalogAgentTools(
 				const query = normalized(
 					(input as Record<string, unknown> | null)?.query,
 				);
-				return (await (await runtime.service()).list(context.tenantId))
-					.filter(
-						(item) =>
-							query === '' ||
-							item.id.toLocaleLowerCase('en-US') === query ||
-							item.sku.toLocaleLowerCase('en-US').includes(query) ||
-							item.name.toLocaleLowerCase('en-US').includes(query),
-					)
-					.slice(0, MAX_TOOL_ROWS);
+				const service = await runtime.service();
+				/* An exact id answers one row before any search, so the variable
+				   resolver that binds an item id never reads a page. */
+				const exact =
+					query === '' ? null : await service.get(context.tenantId, query);
+				if (exact) return [exact];
+				return (
+					await service.listPage(context.tenantId, {
+						...FIRST_LIST_PAGE,
+						sort: 'sku',
+						search: query,
+						limit: MAX_TOOL_ROWS,
+					})
+				).items;
 			},
 		}),
 		defineApiAgentTool({