create-flowdular 0.2.4 → 0.2.6

package/agent-template/docs/adr/0007-module-owned-agents.md

@@ -0,0 +1,429 @@
+# ADR 0007: Module-owned business agents
+
+- Status: accepted
+- Date: 2026-09-02
+- Approval gate: `modules/agents/spec/module.yaml` 0.7.0
+
+## Problem
+
+Modules can register tools, but they cannot ship the business-agent behavior
+that uses those tools. An operator must recreate the same instructions and tool
+allowlist as tenant data. That copy drifts when the module changes and prevents
+an enabled module from being agentic by itself.
+
+Every agent managed by `agents.core` is a business agent. "Module-owned" and
+"tenant-created" describe who owns its definition, not two different kinds of
+runtime. Sandbox coding specialists are a separate development system and are
+not registered through this contract.
+
+The concrete consumers are:
+
+1. A business module such as `catalog.core`, which ships a catalog curation
+   agent next to its tools.
+2. `agents.core`, which lists, configures and executes module-owned agents next
+   to tenant-created agents.
+3. `workflows.core`, which publishes a graph against an exact executable agent
+   revision and must keep that revision after the module publishes a newer one.
+4. Any module that invokes an agent through the public run capability using a
+   trusted tenant, actor and permission snapshot.
+
+## Decision
+
+Build module-owned business agents, but keep module-owned behavior separate
+from tenant-owned execution configuration.
+
+- A module registers a frozen definition with `defineAgent()` during server
+  composition.
+- The platform carries a generic agent definition registry in the composition
+  context. It is created and sealed by the platform, not by `agents.core`.
+- `defineAgent()` and the semantic agent types are exported by
+  `@flowdular/sdk/modules/agents/server`. A module using them declares `agents.core`
+  as a module dependency and `@flowdular/sdk/modules/agents` as a package dependency.
+- Module source owns identity, display copy, instructions, maximum tool
+  allowlist and execution limits.
+- Each tenant owns a binding that selects an available provider and model,
+  chooses active or paused state, and may reduce the code tool allowlist.
+- Module-owned behavior is read-only in the Agents UI. Tenant binding fields
+  remain editable under `agents.definitions.manage`.
+- Tenant-created definitions keep their current lifecycle and appear separately
+  from module-owned agents.
+
+The 0.7.0 specification is approved. Runtime, migrations, UI, and module
+integrations implement this contract together.
+
+## Consumer call sites
+
+### A module defines and registers an agent
+
+```ts
+// modules/catalog/src/agent/agents.ts
+import { defineAgent } from '@flowdular/sdk/modules/agents/server';
+
+export const catalogCurator = defineAgent({
+	moduleId: 'catalog.core',
+	key: 'catalog-curator',
+	definitionRevision: 1,
+	name: 'Catalog curator',
+	description: 'Normalizes and enriches catalog items.',
+	instructions:
+		'Review the requested catalog records. Use only the tools available to you.',
+	allowedTools: ['catalog.item.create', 'catalog.item.list'],
+	limits: {
+		maxSteps: 8,
+		timeoutMs: 120_000,
+		temperature: 0.2,
+		maxOutputTokens: 4_096,
+	},
+});
+```
+
+```ts
+// modules/catalog/src/platform.ts
+context.agentDefinitions.register([catalogCurator]);
+```
+
+The module does not choose credentials, a provider connection or a model. Those
+are tenant deployment choices and never belong in a distributable business
+agent definition.
+
+### agents.core consumes the sealed registry
+
+```ts
+const runtime = createAgentRuntime({
+	moduleAgents: () => context.agentDefinitions.list(),
+	tools: () => context.agentTools.list(),
+	// existing options
+});
+```
+
+The registry is read when `start()` runs, after every module has composed and
+the platform has sealed both registries.
+
+### A module invokes an agent
+
+```ts
+await runQueue.enqueue(
+	{
+		agentId,
+		trigger: 'service',
+		input,
+		toolGrants: ['catalog.item.list'],
+		idempotencyKey,
+	},
+	{
+		tenantId: principal.tenantId,
+		actor,
+		permissionSnapshot: principal.scopes,
+	},
+);
+```
+
+The tenant and authority are trusted context, never input fields. An omitted
+`toolGrants` list means no tools, not every tool.
+
+## Public contract
+
+The semantic surface belongs to `@flowdular/sdk/modules/agents/server`:
+
+```ts
+export interface ModuleAgentDefinitionInput {
+	readonly moduleId: string;
+	readonly key: string;
+	readonly definitionRevision: number;
+	readonly name: string;
+	readonly description: string;
+	readonly instructions: string;
+	readonly allowedTools: readonly string[];
+	readonly limits: {
+		readonly maxSteps: number;
+		readonly timeoutMs: number;
+		readonly temperature: number;
+		readonly maxOutputTokens: number;
+	};
+}
+
+export interface ModuleAgentDefinition
+	extends Readonly<ModuleAgentDefinitionInput> {
+	readonly id: string;
+	readonly ownership: {
+		readonly kind: 'module';
+		readonly moduleId: string;
+		readonly definitionRevision: number;
+	};
+}
+
+export function defineAgent(
+	input: ModuleAgentDefinitionInput,
+): ModuleAgentDefinition;
+```
+
+`id` is derived as `module-agent:<moduleId>:<key>` and is limited to 128
+characters. The prefix is reserved and tenant-created agents cannot use it.
+Callers never supply or parse this id. They treat it as opaque after
+registration.
+
+The generic registry belongs to `@flowdular/sdk/kernel` so auth and the composition
+contract do not import `agents.core`:
+
+```ts
+export interface PlatformAgentRegistry<T = unknown> {
+	register(definitions: readonly T[]): void;
+	list(): readonly T[];
+}
+
+export interface MutablePlatformAgentRegistry<T>
+	extends PlatformAgentRegistry<T> {
+	seal(): void;
+}
+
+export function createPlatformAgentRegistry<
+	T extends { readonly id: string },
+>(): MutablePlatformAgentRegistry<T>;
+```
+
+`PlatformServerContext` gains:
+
+```ts
+readonly agentDefinitions: PlatformAgentRegistry;
+```
+
+The platform creates the registry before module composition and calls `seal()`
+after every module has composed but before any module `start()` hook. Duplicate
+ids fail registration. Registration after sealing fails. A sealed `list()` is
+sorted by id and returns an immutable snapshot.
+
+## Ownership and served state
+
+The API exposes ownership as a discriminated union:
+
+```ts
+export type AgentOwnership =
+	| { readonly kind: 'tenant' }
+	| {
+			readonly kind: 'module';
+			readonly moduleId: string;
+			readonly definitionRevision: number;
+	  };
+```
+
+A tenant-created agent keeps its positive `revision`. A module-owned agent also
+has a tenant-local positive executable `revision` after binding. Before binding,
+it is served with `status: 'unconfigured'` and no executable revision. Workflow
+catalogs exclude unconfigured agents.
+
+The Agents screen presents two explicit groups:
+
+- Module agents: module, definition revision, provider binding, model, status,
+  enabled tools and unavailable reasons. Behavior fields are read-only.
+- Custom agents: the existing tenant-created agent table and full create,
+  update, archive and eligible-delete lifecycle.
+
+Calling the current tenant-agent update, archive or delete operation with a
+module-owned id returns `MODULE_AGENT_READ_ONLY`. Binding changes use a separate
+operation so a careless client cannot replace module behavior while appearing
+to edit deployment configuration.
+
+## Tenant binding and executable revisions
+
+The tenant binding contains:
+
+```ts
+export interface ModuleAgentBinding {
+	readonly tenantId: string;
+	readonly agentId: string;
+	readonly provider: string;
+	readonly model: string;
+	readonly enabledTools: readonly string[];
+	readonly status: 'active' | 'paused';
+	readonly moduleDefinitionRevision: number;
+	readonly executableRevision: number;
+	readonly revision: number;
+	readonly updatedBy: string;
+	readonly updatedAt: number;
+}
+```
+
+`revision` is the optimistic concurrency revision of the mutable binding.
+`executableRevision` is the monotonic revision referenced by runs and workflows.
+Creating a binding, changing provider or model, changing enabled tools, or
+receiving a higher module definition revision creates a new immutable executable
+snapshot. Pausing alone changes availability and audit state without rewriting
+an existing snapshot.
+
+The immutable snapshot extends the existing retained revision with ownership and
+module definition revision. It contains the resolved provider, model,
+instructions, exact enabled tools and limits. It is the only source for an
+exact-revision run.
+
+At runtime start, `agents.core` reconciles registered definitions against
+existing bindings in one transaction:
+
+- same definition revision and same content hash is unchanged;
+- higher definition revision creates the next executable revision for each
+  existing binding;
+- same definition revision with a different hash fails boot;
+- a lower definition revision fails boot;
+- a definition absent from the sealed registry is unavailable for new work;
+  retained revisions and historical runs remain untouched.
+
+An old retained revision remains executable after a newer module definition is
+registered only while the owning module is still present, the selected provider
+is usable, and every required registered tool still exists. Module removal is
+not promised to keep new workflow executions alive.
+
+## Tool authority
+
+Agent access is a capability intersection, not an instruction convention.
+
+For a tenant-created agent:
+
+```text
+effective tools = definition allowedTools
+  intersect invocation toolGrants
+  intersect registered tools allowed by actor permissions
+```
+
+For a module-owned business agent:
+
+```text
+effective tools = code allowedTools
+  intersect tenant binding enabledTools
+  intersect invocation toolGrants
+  intersect registered tools allowed by actor permissions
+```
+
+The permission term means every `requiredPermissions` entry declared by the
+tool exists in the trusted permission snapshot captured at enqueue. Tool ids are
+exact identifiers. `*`, prefix patterns and implicit all-tools defaults are
+invalid. A grant outside the agent maximum is refused. A missing permission
+removes the tool before provider execution and a later invocation is denied
+before the tool body runs.
+
+The model never receives `PlatformCapabilityRegistry`. Platform capabilities
+are typed module-to-module services. Model-visible authority is only the
+registered tool surface enforced by the harness.
+
+Every run persists the effective tool ids and permission digest used for that
+decision. The existing short-lived run grant remains bound to both digests.
+
+## Workflow compatibility
+
+`agents.run-execution.v2` continues to use `{ agentId, revision }`. For a
+module-owned agent, `revision` means the tenant executable revision, not the code
+definition revision or mutable binding revision.
+
+Workflow publication receives only configured active executable revisions. A
+published workflow keeps its exact retained snapshot after a module publishes a
+higher code revision or a tenant changes the current provider binding. Newly
+published workflows select the new current executable revision.
+
+Changing the ownership discriminator is additive for list consumers. Existing
+tenant revisions are adopted as `{ kind: 'tenant' }`. Existing workflow rows do
+not change shape.
+
+## Guarantees
+
+- Module agent identity is stable for one module id and key.
+- Business-agent definition content is immutable within one definition
+  revision.
+- Duplicate ids, late registration, revision downgrade and same-revision content
+  drift fail platform boot before workers start.
+- Module behavior cannot be edited or deleted through tenant APIs.
+- Tenant bindings cannot enable a tool outside the code allowlist.
+- Every execution is tenant-scoped and uses the initiating Actor and trusted
+  permission snapshot.
+- Workflow execution uses the exact retained executable revision it published.
+- Completed runs, revisions and audit evidence survive module removal.
+- No credentials or provider secrets enter a code definition, binding response,
+  run event or audit payload.
+
+## Deliberately unspecified
+
+- The database table layout and whether reconciliation uses one or several
+  internal transactions.
+- The visual grouping control used by the Agents screen.
+- Internal hashes and serialization used to detect definition content drift.
+- Whether a future release offers bulk binding APIs or module installation
+  defaults.
+- Ordering before the registry is sealed. Consumers may rely only on the sealed
+  id order.
+- Automatic migration of a binding when its selected provider or a required
+  tool disappears. Version one reports the agent unavailable and requires an
+  operator decision.
+
+## Lifecycle and errors
+
+- `defineAgent()` validates and freezes one value. Calling it has no I/O.
+- Registration is valid only during module composition.
+- Double registration and registration after seal are programmer errors and
+  throw synchronously.
+- `list()` after seal is read-only and repeatable.
+- Binding mutations use optimistic concurrency and audit the user actor.
+- Runs already durably queued continue from their snapshot when a binding is
+  paused or the module reloads.
+- New runs refuse `unconfigured`, `paused`, missing-provider, stale-readiness,
+  missing-tool and missing-permission states with stable codes.
+- Shutdown disposes workers as it does today. The registry owns no timers,
+  connections or callbacks.
+
+## Stability and evolution
+
+This surface is experimental with `agents.core` 0.7.0. Identity and revision
+semantics are one-way serialized contracts because workflows and run history
+store them. They require compatibility tests before the surface can become
+stable.
+
+Additive fields belong in the options object. New binding controls must default
+to further restriction, never broader authority. Wildcard grants are excluded
+from future compatibility.
+
+## Challenge result
+
+### Strongest case for the feature
+
+The feature removes a real manual copy between a module and tenant data. It lets
+a module ship a ready business agent and its tools together while keeping
+credentials and tenant authority outside the distributable definition. Catalog
+and workflows are current, concrete consumers.
+
+### Alternatives rejected
+
+1. Module migrations insert rows into `agents.core`. This crosses a module
+   database boundary, needs tenant enumeration, creates unclear uninstall
+   behavior and lets code mutate another module's storage.
+2. `module.json` embeds agent definitions. This turns long instructions into
+   manifest data, duplicates runtime validation, and still needs a registry and
+   tenant provider binding.
+3. A module ships a tenant-agent template with a Copy button. This is simpler,
+   but the copy immediately loses module ownership, safe upgrades and exact
+   revision lineage. It does not solve the stated problem.
+4. Code pins provider and model. This avoids a binding table but makes modules
+   non-portable and can name a connection that does not exist in another tenant.
+
+### Cost and failure modes
+
+Boot registration is O(d) time and O(d) memory for d current module definitions.
+Tenant listing is O(d + a) for d module definitions and a tenant agents. Storage
+grows O(b \* r) for bindings b and retained executable revisions r, which is the
+same deliberate append-only cost already accepted for exact workflow revisions.
+
+The largest blast radius is a bad reconciliation that advances many tenant
+bindings during boot. The mitigation is content-addressed comparison, a
+transactional repository operation, same-revision drift refusal, fault-injection
+rollback tests and no deletion of retained rows.
+
+The strongest surviving objection is operational setup: a module-owned agent is
+not runnable until each tenant binds a provider and model. That friction is
+intentional. Silent provider selection would make behavior non-portable and
+would change published workflows without a new executable revision.
+
+### Verdict
+
+Build the split definition and binding design. Do not build direct database
+seeding or a code-pinned provider shortcut.
+
+The falsifying experiment is a thin implementation with one catalog agent and
+two tenants using different provider bindings. It must prove distinct tool
+reductions, immutable workflow revisions across a code bump, and boot refusal
+for same-revision content drift. If that cannot be done without module database
+access or mutable workflow behavior, revise this ADR before expanding adoption.

package/agent-template/docs/adr/0008-database-adapter-contract.md

@@ -0,0 +1,90 @@
+# ADR 0008: asynchronous database adapter contract
+
+Status: accepted; the SQLite half is superseded (2026-09)
+
+> Superseded in part (2026-09): the contract, the leased provider and the v2
+> ledger stand, but SQLite is no longer an adapter and the synchronous
+> compatibility path is gone. Flowdular runs on PostgreSQL everywhere, embedded
+> through PGlite outside production. See `docs/database-adapters.md`.
+
+## Decision
+
+Flowdular uses the asynchronous, dialect-explicit contract in
+`@flowdular/sdk/database` for new database adapter work. SQLite is the local adapter.
+PostgreSQL is the first production adapter target through a structural driver
+port owned by platform composition.
+
+Transactions receive a callback-scoped session pinned to one connection.
+Adapters own placeholder style, schema introspection, migration locking,
+cancellation capability, pooling, and disposal. Modules own repository ports,
+queries, and SQL for every dialect they support. The platform owns credentials
+and gives modules leased handles through `DatabaseProvider`.
+
+The existing synchronous SQLite repositories and kernel migration runner remain
+supported during conversion. They are a compatibility path, not the contract
+for PostgreSQL.
+
+The package depends on `@flowdular/sdk/kernel` only for the existing checksum
+algorithm, so v1 and v2 ledgers calculate identical hashes for identical SQL.
+The kernel does not import `@flowdular/sdk/database`. A future
+`PlatformServerContext` type may import the provider from this package at the
+module composition layer without creating a package cycle.
+
+## Consumer call sites
+
+The immediate consumers are existing SQLite module repositories. They can move
+to `SqliteDatabaseAdapter` one module at a time without changing storage. The
+named next consumer is a PostgreSQL deployment, which supplies a pool bridge and
+the same `DatabaseHandle` to an asynchronous repository.
+
+Migration authors provide an explicit SQL script per supported dialect and an
+optional adapter-backed adoption inspection. The runner owns the namespaced
+ledger, checksums, transaction, and migration lock.
+
+## Guarantees
+
+- Query values are separate from SQL text.
+- SQL is never translated between placeholder styles.
+- A transaction uses one connection and its session cannot escape the callback.
+- Migration checksum drift is checked before new SQL runs.
+- Migration DDL and ledger rows commit or roll back together.
+- Disposal is idempotent and drains accepted work.
+- Capabilities describe cancellation, isolation, DDL, lock, and returning
+  behavior without version sniffing.
+
+## Deliberately unspecified
+
+The contract does not standardize SQL syntax, database error codes, generated
+identifier values, query planning, physical pool behavior, or row type parsing.
+Repositories translate database-specific errors into domain errors at their own
+boundary.
+
+## Challenge record
+
+The strongest argument against this addition is conversion cost. Current
+services and repositories are synchronous, so the adapter does not make the
+existing application PostgreSQL-ready by itself. A narrow seam still earns its
+cost because the production target is already PostgreSQL and retaining a
+synchronous public port would make that target impossible.
+
+Rejected alternatives:
+
+1. Extend the current structural `MigrationDatabase`. Its implementation relies
+   on `sqlite_master`, `PRAGMA`, `STRICT`, and `BEGIN IMMEDIATE`, and every method
+   is synchronous. Calling it neutral would preserve a false contract.
+2. Rewrite `?` placeholders to `$1`. SQL strings contain comments, literals,
+   operators, DDL types, and dialect features. Text replacement would corrupt
+   valid queries while hiding the real compatibility work.
+3. Put `pg` pools and DSNs in modules. That duplicates pools, exposes secrets,
+   and makes teardown and production policy impossible to enforce centrally.
+4. Adopt an ORM now. It would add a second query and migration system before one
+   reference module proves that abstraction is needed.
+
+## Follow-up required for production PostgreSQL
+
+Add `pg` to the deployable platform, create the secret-backed provider, inject
+it into server composition, convert a reference module to asynchronous
+repositories, add PostgreSQL integration tests, and run its migrations against
+an empty database plus an upgraded snapshot. Until that work lands, PostgreSQL
+is an implemented adapter seam rather than the application's selected production
+database.

package/agent-template/docs/agent-contract.md

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