create-flowdular 0.4.3 → 0.6.0

package/README.md

@@ -17,16 +17,19 @@ npm create flowdular@latest my-app
 cd my-app
 ```
 
-For this new local application, initialize demo authentication and start the development server:
+Start the development server:
 
 ```sh
-pnpm flowdular setup
 pnpm dev
 ```
 
-Open [localhost:4310](http://localhost:4310). `setup` opens an interactive wizard for a local demo, PostgreSQL settings or a configuration check. It asks before resetting the local demo database.
+The browser opens the first-run setup automatically. If it cannot open, visit
+[localhost:4310/setup](http://localhost:4310/setup). Enter the token printed in
+the terminal, then create your workspace and owner account. Embedded PostgreSQL
+is already configured. Restart `pnpm dev` when setup finishes, then sign in with
+the owner account you chose.
 
-The starter enables all nine platform modules: system, authentication, users, profile, agents, automations, workflows, their integration, and sandbox access. Local demo setup grants their declared permissions to demo owners. The example module stays available as a starting point; business modules from Official Modules are optional downloads.
+The starter enables all nine platform modules: system, authentication, users, profile, agents, automations, workflows, their integration, and sandbox access. First-run setup grants their declared permissions to the new owner. The example module stays available as a starting point. Module Studio can later connect a catalog, a pinned Git repository or local releases; Sandbox helps create your own modules.
 
 `npm create` launches the generator. The generated application uses **pnpm workspaces**. If pnpm is unavailable during installation, the generator invokes its pinned version through `npm exec`.
 
@@ -50,12 +53,15 @@ The generator installs dependencies and initializes Git by default. Local develo
 
 ## Ready for coding agents
 
-Every app includes `.ai` rules, skills, role prompts, blueprints, policies and
-reference examples, plus `AGENTS.md`, `CLAUDE.md`, `.agents/skills` and
-`.claude/skills`. These files are bundled with the generator and are available
-with `--no-install`. Personal agent settings and credentials are never copied.
+Every app includes `.ai` rules, skills, role prompts, subagents, blueprints,
+policies and reference examples, plus `AGENTS.md`, `CLAUDE.md`, `.agents/skills`,
+`.claude/skills` and the spec author, module executor and reviewer as subagents in
+`.claude/agents` and `.codex/agents`. The chat-first sandbox is installed with the
+app, so `pnpm sandbox` starts it without a download. These files are bundled with
+the generator and are available with `--no-install`. Personal agent settings and
+credentials are never copied.
 
-Edit `.ai/rules` or `.ai/skills`, then run `pnpm rules:generate`. `pnpm verify`
+Edit `.ai/rules`, `.ai/skills` or `.ai/subagents`, then run `pnpm rules:generate`. `pnpm verify`
 checks that the generated instructions are in sync. The instructions explain
 where to find the installed SDK and how to extend the application's modules.
 
@@ -93,7 +99,7 @@ pnpm verify
 pnpm flowdular help
 ```
 
-Read the [module guide](https://github.com/Flowdular/flowdular/blob/main/docs/modules.md) to extend the application. Business modules from [Official Modules](https://github.com/Flowdular/official-modules) are installed as source through the CLI.
+Read the [module guide](https://github.com/Flowdular/flowdular/blob/main/docs/modules.md) to extend the application and the [Module Studio guide](https://github.com/Flowdular/flowdular/blob/main/docs/module-distribution.md) to install reviewed module source.
 
 ## Packages and support
 

package/agent-template/.agents/skills/agent-tool-design/SKILL.md

@@ -19,7 +19,7 @@ also ship a ready business agent through `defineAgent()`, read
 ## 1. The contract in code
 
 - Composition: `PlatformServerContext` (`modules/auth/src/server/composition.ts`) carries `agentTools: PlatformToolRegistry` (`register(tools)`, `list()`; `packages/kernel/src/tool-registry.ts`; a duplicate tool id throws at boot), `settings: ModuleSettingsRuntime`, and `capabilities: PlatformCapabilityRegistry` (`register(id, service)`, `get(id)`, `has(id)`; `packages/kernel/src/capability-registry.ts`). `platform/octane.config.ts` creates the registries, passes them to every module's `createServerComposition`, declares each `settings`, owns each `dispose`, then calls each `start`.
-- Ordering is a non-issue: `agents.core` (`modules/agents/src/platform.ts`) passes `tools: () => context.agentTools.list()` into `createAgentRuntime`, and the harness is built lazily in `start()`, which runs after every module has composed. Tools any module registers during its own compose are therefore visible, whatever the module order.
+- Ordering is a non-issue: `agents.core` (`modules/agents/src/platform.ts`) passes `tools: () => context.agentTools.list()` into `createAgentRuntime`, and the harness is built when `agents.core` opens, on its first request, capability call or `startWorker()`, all of which run after every module has composed. Tools any module registers during its own compose are therefore visible, whatever the module order.
 - Helpers: import `defineApiAgentTool` from `@flowdular/sdk/harness/tool-adapters` and the types `AgentTool`, `AgentToolContext` from `@flowdular/sdk/harness/runtime`. Both subpaths are free of the Vercel AI SDK; only the harness root (`@flowdular/sdk/harness`) and `@flowdular/sdk/modules/agents/server` pull it. `defineApiAgentTool` returns a frozen `AgentTool { id, transport: 'api', target, description, requiredPermissions, inputSchema?, execute }`. `defineCliAgentTool({ id, capability: { id, risk }, ... })` wraps a CLI capability and throws at definition time for `external` or `destructive` risk.
 - Skills inside `agents.core` are tenant database records behind `agents.skills.*`, appended to agent instructions. They are unrelated to `.ai/skills/**`, which are files for coding agents.
 - A read tool's output can also become a resolvable `{{ variable }}` for variable-aware fields: the tool's `requiredPermissions` is the variable's scope mask. Register a source on `platformVariableRegistry(context.capabilities)`, require an explicit record binding, and invoke the tool with the trusted tenant, actor permission snapshot, and signal. See the `variables` skill for the complete refusal contract.

package/agent-template/.agents/skills/auth-security-review/SKILL.md

@@ -57,7 +57,7 @@ Recipe in `modules/auth/tests/endpoints.test.ts`: build the runtime with a `Data
 
 - 401 without a cookie or token.
 - 403 with a principal that lacks the permission.
-- Cross-tenant read returns an empty list (service level, on the suite's test provider under the non-bypass `coreloom_runtime` role).
+- Cross-tenant read returns an empty list (service level, on the suite's test provider under the non-bypass `flowdular_runtime` role).
 - Mutation without `x-csrf-token` returns 403 `CSRF_REJECTED`; without `origin` returns 403.
 - Each validation bound returns 400 with its code.
 
@@ -74,7 +74,7 @@ Report each finding as: severity (`blocker`, `should-fix`, `taste`), claim, `fil
 ```text
 blocker  Tenant id read from body   modules/inventory/src/api/endpoints.ts:41
          A member of tenant A posts { tenantId: "B" } and creates a location in B.
-         AGENTS.md 6. Fix: principalFromContext(octane)!.tenantId; drop the field.
+         AGENTS.md 4. Fix: principalFromContext(octane)!.tenantId; drop the field.
 ```
 
 ## 8. Known platform gaps to keep in mind (not module defects)

package/agent-template/.agents/skills/bug-hunt/SKILL.md

@@ -29,7 +29,7 @@ description: >-
 | View falls back to the dashboard                                                                           | `ApplicationShell.tsrx` renders `overview` for a view id that no visible navigation or account menu entry reaches                                                                                                                                                                               |
 | Icon renders as a grid                                                                                     | `glyph` or `Icon name` is not an `ICON_PATHS` key (`packages/ui/src/icons/Icon.tsrx` falls back to `modules`)                                                                                                                                                                                   |
 | Stale data after a change                                                                                  | each component owns a store instance (`useMemo(() => createXClientState(), [])`); check the `store.act` that should have written it. `store.commits(cb)` and `store.stats()` from `segment-state` show what was committed                                                                       |
-| Schema error on start                                                                                      | `runModuleMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_OBJECTS` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                             |
+| Schema error on start                                                                                      | `runDatabaseMigrations`: `CHECKSUM_MISMATCH` means applied SQL bytes changed; `PARTIAL_MIGRATION` means only part of a pending migration exists. Never delete or bypass the database to hide either condition; restore the shipped bytes or diagnose the partial schema                         |
 
 ## 2b. Reproduction snippets
 

package/agent-template/.agents/skills/database-adapter/SKILL.md

@@ -88,12 +88,12 @@ PostgreSQL tenant-owned tables also use database-enforced isolation:
 
 - enable and force row-level security on the table;
 - define a policy whose `USING` and `WITH CHECK` clauses compare `tenant_id`
-  with `current_setting('coreloom.tenant_id', true)`;
+  with `current_setting('flowdular.tenant_id', true)`;
 - run application traffic under a role that is neither a superuser nor granted
   `BYPASSRLS`;
 - use a separate migration role for DDL or policy ownership when required.
 
-The adapter sets `coreloom.tenant_id` with parameterized `set_config(..., true)`
+The adapter sets `flowdular.tenant_id` with parameterized `set_config(..., true)`
 after `BEGIN` on the pinned connection. Never use an unpinned root query.
 Explicit tenant predicates remain required as defense in depth.
 
@@ -133,7 +133,7 @@ transactions without `tenantId`, fail with `TENANT_CONTEXT_REQUIRED`.
 
 Use `DatabaseMigration` and `runDatabaseMigrations` from `@flowdular/sdk/database`.
 Each migration has one immutable id and its PostgreSQL SQL. The ledger is
-`_coreloom_migrations_v2`, keyed by module namespace and migration id; its
+`_flowdular_migrations_v2`, keyed by module namespace and migration id; its
 checksum covers that exact SQL.
 
 `inspectExisting(database)` is the only pre-ledger adoption proof. Use
@@ -157,8 +157,8 @@ constant. A migration-only task uses `migration-authoring` in a separate phase.
 ## 7. Tests run on a real PostgreSQL
 
 `createTestDatabaseProvider()` from `@flowdular/sdk/database-testing` gives a suite its
-own PostgreSQL in process by default, with the same `coreloom_runtime` and
-`coreloom_background` roles and the same forced row-level security a deployment
+own PostgreSQL in process by default, with the same `flowdular_runtime` and
+`flowdular_background` roles and the same forced row-level security a deployment
 enforces. There is no server to start and no second dialect to keep green, so
 the isolation assertions run on every turn rather than behind an environment
 flag. CI selects server PostgreSQL with `FD_TEST_DATABASE_ADAPTER=postgresql`

package/agent-template/.agents/skills/database-adapter/references/first-run-and-matrix.md

@@ -83,8 +83,8 @@ adapter change, sandbox eject, and deployment validation.
 
 Every turn runs against a real PostgreSQL, because the embedded one starts in
 process. The sandbox and the test suites use `createTestDatabaseProvider()` from
-`@flowdular/sdk/database-testing`, which brings the `coreloom_runtime` and
-`coreloom_background` roles and forced row-level security with it.
+`@flowdular/sdk/database-testing`, which brings the `flowdular_runtime` and
+`flowdular_background` roles and forced row-level security with it.
 
 A target run covers tenant A and B fixtures, operations without tenant context,
 forged cross-tenant inserts, direct row-security bypass probes, concurrent

package/agent-template/.agents/skills/deploy-operate/SKILL.md

@@ -48,7 +48,7 @@ Set `FD_TRUST_PROXY` behind a load balancer. `FD_DATABASE_BACKGROUND_URL` gives
 
 ## 3. Migrations at rollout
 
-Migrations are module-owned, numbered, immutable once applied, and verified by checksum against the `_coreloom_migrations_v2` ledger. The commands (`packages/cli/src/runner.ts`):
+Migrations are module-owned, numbered, immutable once applied, and verified by checksum against the `_flowdular_migrations_v2` ledger. The commands (`packages/cli/src/runner.ts`):
 
 ```bash
 pnpm flowdular migration status [--module <id>]      # what the ledger holds

package/agent-template/.agents/skills/migration-authoring/SKILL.md

@@ -26,7 +26,7 @@ Migration SQL is checked in and immutable after release:
 ## 2. What the v2 runner guarantees
 
 `runDatabaseMigrations(database, namespace, databaseMigrations)` uses the
-namespaced `_coreloom_migrations_v2` ledger. A row records namespace, migration
+namespaced `_flowdular_migrations_v2` ledger. A row records namespace, migration
 id, dialect id, checksum, and applied time. The checksum covers the selected
 dialect's exact SQL.
 
@@ -76,14 +76,14 @@ Every PostgreSQL tenant table includes:
 ALTER TABLE inventory_locations ENABLE ROW LEVEL SECURITY;
 ALTER TABLE inventory_locations FORCE ROW LEVEL SECURITY;
 CREATE POLICY inventory_locations_tenant_policy ON inventory_locations
-  USING (tenant_id = current_setting('coreloom.tenant_id', true))
-  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+  USING (tenant_id = current_setting('flowdular.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('flowdular.tenant_id', true));
 ```
 
 The runtime role is not a superuser and has no `BYPASSRLS`. DDL and policy
 ownership use `purpose: 'migration'`. Runtime repository calls use
 `database.transaction(operation, { tenantId, access })`; the adapter sets
-transaction-local `coreloom.tenant_id` on the pinned connection. Queries still
+transaction-local `flowdular.tenant_id` on the pinned connection. Queries still
 include `WHERE tenant_id = ...` as defense in depth.
 
 ## 6. Add one migration

package/agent-template/.agents/skills/module-new/SKILL.md

@@ -142,7 +142,7 @@ export function createServerComposition(
 
 `PlatformServerContext` also carries `databases: DatabaseProvider`, `settings: ModuleSettingsRuntime`, `agentTools: PlatformToolRegistry`, `agentDefinitions: PlatformAgentRegistry`, and `capabilities: PlatformCapabilityRegistry`. The runtime shares one lazy database initialization, uses separate migration and runtime leases, and releases the runtime lease from `dispose()`; `prepare()` remains read-only. A composition may return module settings, lifecycle hooks, agent registrations, and typed cross-module capabilities as described in the focused skills.
 
-Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('coreloom.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
+Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('flowdular.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
 
 Errors: `{ error: { code, message } }`; service errors `class XServiceError extends Error { constructor(readonly code: string, message: string, readonly status = 400) }`; a `failure(error)` helper routes them to `jsonResponse(..., error.status)` and everything else to `problemResponse(error, 'The <module> operation failed.')`.
 

package/agent-template/.agents/skills/spec-interview/SKILL.md

@@ -23,26 +23,26 @@ For an edit, also read the module's current `spec/module.yaml` and write the sma
 
 One pass, in this order. For each row, write the default from the card into the spec and record it as a `decisions[]` entry with `decidedBy: default`. Ask only where the answer is a business fact that no default can supply.
 
-| Decision               | Default to propose                                                                                                                                                                                  | Lands in                                 |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| Actors                 | Owner manages, member reads                                                                                                                                                                         | `permissions`, `invariants`              |
-| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name                                                                                                             | `entities[]`                             |
-| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                                                                                                                                   | `entities[].fields[].unique`             |
-| States and transitions | `active` and `archived`, every transition behind the manage permission                                                                                                                              | `entities[].states`                      |
-| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope                                                                                                           | `permissions`, `screens[]`, `invariants` |
-| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing                                                                                                                      | `acceptanceScenarios`                    |
-| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                                                                                                                        | `invariants`, `acceptanceScenarios`      |
-| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency                                                                                                         | `dependencies`, `dataOwnership`          |
-| Screens                | One `list` screen with the entity's identifying columns                                                                                                                                             | `screens[]`                              |
-| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it                                                                                                                      | `widgets[]`                              |
-| Settings               | None. A number the business may change later is `scope: tenant` with a stated default                                                                                                               | `settings[]`                             |
-| Feature flags          | Ask for one whenever a change alters behaviour a workspace already relies on, or is hard to undo: `kind: flag`, boolean, `scope: tenant`, a stated default, and the behaviour named in an invariant | `settings[]`                             |
-| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`                                                                                                                    | `agentTools[]`                           |
-| Outside sources        | None. A named public source is `research`, with the entity its findings attach to                                                                                                                   | `research`                               |
-| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                                                                                                                         | `adapters[]`                             |
-| Documents              | None. A named document is one `templates[]` entry on the record it describes                                                                                                                        | `templates[]`                            |
-| Reports                | None. There is no export, no PDF and no search; a report is a screen or it is out of scope                                                                                                          | `outOfScope[]`                           |
-| Out of scope           | Every item from the card's gap list the request touched, each with its business decision                                                                                                            | `outOfScope[]`, `decisions[]`            |
+| Decision               | Default to propose                                                                                                                                                                                                                                                                                                   | Lands in                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Actors                 | Owner manages, member reads                                                                                                                                                                                                                                                                                          | `permissions`, `invariants`              |
+| Entities and fields    | One primary entity; `name` required, `maxLength` 120; no field the request did not name                                                                                                                                                                                                                              | `entities[]`                             |
+| Uniqueness             | The human-facing code is `unique: tenant`; everything else `none`                                                                                                                                                                                                                                                    | `entities[].fields[].unique`             |
+| States and transitions | `active` and `archived`, every transition behind the manage permission                                                                                                                                                                                                                                               | `entities[].states`                      |
+| Who sees what          | Both permissions in the same navigation entry; the manage action hidden without the scope                                                                                                                                                                                                                            | `permissions`, `screens[]`, `invariants` |
+| What is denied         | Unauthenticated 401, missing permission 403, cross-tenant read returns nothing                                                                                                                                                                                                                                       | `acceptanceScenarios`                    |
+| Failure behaviour      | A duplicate returns a stable conflict and changes nothing; bounds return 400                                                                                                                                                                                                                                         | `invariants`, `acceptanceScenarios`      |
+| Cross-module reads     | None. A read of another module goes through its public capability and a declared dependency                                                                                                                                                                                                                          | `dependencies`, `dataOwnership`          |
+| Screens                | One `list` screen with the entity's identifying columns                                                                                                                                                                                                                                                              | `screens[]`                              |
+| Widgets                | None. A count belongs on `dashboard.metrics` only when the request asks for it                                                                                                                                                                                                                                       | `widgets[]`                              |
+| Settings               | None. A number the business may change later is `scope: tenant` with a stated default                                                                                                                                                                                                                                | `settings[]`                             |
+| Feature flags          | Ask for one whenever a change alters behaviour a workspace already relies on, or is hard to undo: `kind: flag`, boolean, `scope: tenant`, a stated default, and the behaviour named in an invariant                                                                                                                  | `settings[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`                                                                                                                                                                                                                                     | `agentTools[]`                           |
+| Outside sources        | None. A named public source is `research`, with the entity its findings attach to                                                                                                                                                                                                                                    | `research`                               |
+| Other systems          | None. A named system is one `source` adapter per record kind, run on demand                                                                                                                                                                                                                                          | `adapters[]`                             |
+| Documents              | None. A named document is one `templates[]` entry on the record it describes                                                                                                                                                                                                                                         | `templates[]`                            |
+| Reports                | A named report is one provider on `reports.v1` returning tiles and series; a named list export is one `defineListExport`; named records are findable through `search.providers.v1`. None of the three has a specification key, so each needs a decision naming the screen or the `actions[]` entry that registers it | `actions[]`, `invariants`                |
+| Out of scope           | Every item from the card's gap list the request touched, each with its business decision                                                                                                                                                                                                                             | `outOfScope[]`, `decisions[]`            |
 
 A default you propose is still a decision: it goes into `decisions[]` so the operator can see and overturn it, and so the next agent never re-derives it.
 

package/agent-template/.agents/skills/test-hardening/SKILL.md

@@ -15,7 +15,7 @@ description: >-
 
 ## 2. Repositories on an embedded PostgreSQL
 
-`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `coreloom_runtime` and `coreloom_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
+`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `flowdular_runtime` and `flowdular_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
 
 ## 3. Route recipe (from `modules/auth/tests/endpoints.test.ts`)
 
@@ -55,7 +55,7 @@ The auth middleware must have set the principal for `endpointIdentityFromContext
 - 403 on a mutation without `x-csrf-token` (`CSRF_REJECTED`) and without `origin` (`ORIGIN_REQUIRED`).
 - 400 with the stable code for each validation bound (`INVALID_INPUT`, module codes such as `INVALID_ITEM_KIND`).
 - 409 for the tenant-scoped uniqueness rule, and success for the same key in another tenant.
-- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `coreloom_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
+- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `flowdular_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
 - Identity: `moduleDefinition.manifest.id` equals the module id (keeps `module.json` and `src/index.ts` aligned). The scaffold writes this and the isolation case; everything else in this list is yours.
 
 Assert at the observation boundary: status code, `error.code`, returned record fields. Do not assert internal helper names, call order, or SQL text.

package/agent-template/.agents/skills/ux-design/SKILL.md

@@ -81,7 +81,7 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Alert`: `tone` danger (default), warning, info.
 - `Avatar`: `name`, `square` (organizations), `large`.
 - `Icon`: `name`, `size` (18 default, 16 in controls, 14 in `Button size="sm"`), `strokeWidth`.
-- `BrandMark`: `size`, `signature`, `tone`; brand moments only.
+- `BrandMark`: `size`, `tone`; three bars with a copper accent bar, brand moments only.
 
 Icon keys (`ICON_PATHS`, `packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog`, `user`, `users`, `shield`, `code`, `modules`, `file-text`, `play`, `bot`, `flask`, `activity`, `plug`, `search`, `chevron-down`, `chevron-left`, `chevron-right`, `chevrons-up-down`, `sort`, `calendar`, `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`, `alert`, `x`, `sign-out`, `refresh`, `help`, `info`, `key`, `settings`, `braces`, `copy`. An unknown name renders `modules` silently, so check the list.
 

package/agent-template/.agents/skills/workflow-development/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: workflow-development
 description: >-
-  Build, publish, invoke, and test a workflows.core DAG through its typed graph
-  and public execution capability without bypassing agent, action, tenant, or
-  audit boundaries.
+  Author module-owned action templates, or build, publish, invoke, and test a
+  workflows.core DAG through its typed graph and public execution capability.
 ---
 # Build and integrate an agentic workflow
 
@@ -12,18 +11,22 @@ pinned agent revisions, deterministic gates, schema validators, registered
 module actions, data mappings, and terminal output. It does not own schedules or
 webhook secrets. Those remain optional concerns of `automations.core`.
 
-Read `docs/adr/0006-agentic-workflows.md`, the approved
-`modules/workflows/spec/module.yaml`, and the contracts in
-`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+At the repository root, read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the owning public contracts before
+changing a workflow surface. In the Sandbox, read the approved active-module
+specification and the relevant public contract under `reference/sdk` when it is
+installed. A missing public contract is a core blocker, not a reason to invent
+one or search beyond the session workspace.
 
 ## Pick the correct extension point
 
 - A workflow definition belongs in `workflows.core` and is edited through its
   API or canvas. Do not hardcode a tenant workflow in source.
 - A business operation that a workflow may call is a versioned agent action.
-  Register it through the agents action catalog. If missing, implement it in a
-  separate `agent-tool-design` phase with permission, input, output, timeout,
-  idempotency and audit tests before returning to workflow integration.
+  Register one ordinary `AgentTool` with `context.agentTools`. Optional
+  `workflowTemplate` metadata makes that action a named palette choice through
+  `agents.actions.v2`; it creates no second handler or node kind. Use the
+  authoring recipe below when the action is part of this task.
 - A business module that starts a workflow resolves
   `workflows.execution.v1` from `context.capabilities`. It never imports a
   workflow repository or database.
@@ -33,6 +36,87 @@ Read `docs/adr/0006-agentic-workflows.md`, the approved
 - If the workflow module is absent, the capability registry returns `null`.
   Hide an optional feature or return a clear stable refusal.
 
+## Author a module-owned workflow node template
+
+An action-backed template is module source, not graph source. The business
+manager first records its stable action id, permission, named inputs and
+validation rules, output, effect, replay behavior, and success and refusal
+scenarios in the owning module's specification. In a Sandbox session, the
+operator must approve the hash of that exact spec before implementation. A
+later edit requires renewed approval. If any of these decisions are absent,
+hand the spec delta to `business-manager`; do not infer a field, permission,
+external effect, or idempotency rule from the brief.
+
+Work inside the existing role boundaries:
+
+1. `backend-engineer` owns the tenant-bound service, code-level validator,
+   endpoint or CLI target, and durable target ledger for a mutation. Validation
+   runs before any write and returns a stable bounded refusal. A repeated
+   idempotency key returns its first result; the same key with different input
+   conflicts. Ask backend to supply a missing service rather than writing in
+   `src/services/**` or `src/api/**` from the agentic role.
+2. `agentic-engineer` defines the tool under `src/agent/**`, registers it once
+   from `createServerComposition` in `src/platform.ts`, and adds behavioral
+   tests. `defineApiAgentTool` or `defineCliAgentTool` carries the existing
+   public target. `agents.core` exposes the registered action through
+   `agents.actions.v2`; the business module does not register that capability
+   or access the workflow database.
+3. Give the tool a stable dotted id, positive `contractVersion`, required
+   permission, bounded input and output JSON Schemas, `risk: 'read'` or
+   `'workspace-write'`, `idempotency: 'required'`, cancellation policy, and
+   timeout. A workspace write also needs
+   `idempotencyProtection: 'target-ledger'` backed by the service's real ledger.
+   The handler receives trusted tenant, actor, permission snapshot,
+   idempotency key, and `AbortSignal` from `AgentToolContext`; none comes from
+   graph input. Its output must satisfy its declared schema.
+4. Add static `workflowTemplate: { label, description, effect }` on that same
+   tool. The label is at most 80 characters, the description at most 240, and
+   effect is `local` or `connector-egress`. Metadata contains no code,
+   credential, or tenant value. Invalid or duplicate metadata must fail
+   composition with a safe diagnostic. A workflow-eligible tool without the
+   metadata remains in the generic action editor.
+
+The selected template becomes a normal `action` node with input, success, and
+failure ports. It pins the action id, contract version, schemas, permissions,
+risk, idempotency protection, timeout, cancellation, and effect. Changing any
+of those or the handler's behavior requires a new action identity or contract
+version. The current registry keeps one version per action id, so retain the
+old id and register a distinct id when published graphs must keep running;
+label and description may change without rebinding a published graph.
+
+Graph bindings may never supply a raw secret. `writeOnly` and
+`x-flowdular-secret` apply at every schema depth, including array items and
+alternatives. A marked field cannot carry `default`, `const`, `enum`,
+`example`, or `examples` data. A template requiring
+a raw secret input is ineligible. Accept a nonsecret opaque reference and let
+the owning module resolve a credential from its tenant-bound vault or a
+declared capability. Never put secret values in fixtures, graph definitions,
+events, audit, or error text.
+
+For `connector-egress`, the consumer module declares `connectors.core` and
+`connectors.calls.v1`, uses `caller: 'workflow'`, checks the instance's
+`allowWorkflows` consent, and passes the stable workflow side-effect key to
+the connector. Credentials remain in `connectors.core`. A replay-stable
+output may contain the recorded call id and outcome, not a response body the
+connector replay does not return. Propagate `CALL_OUTCOME_UNKNOWN` as a
+terminal failure when the remote mutation may have happened but no call was
+recorded; never send a second request just to rebuild output. A separate
+provider contract with remote idempotency or readback is required before
+retrying an uncertain mutation.
+
+Prove the module behavior at its public service or action boundary: valid
+input, structural and business validation refusal before mutation, missing
+permission, foreign tenant, same-key replay, different-input conflict,
+cancellation, and recovery around the target commit. Connector actions also
+prove absent consent and `CALL_OUTCOME_UNKNOWN` with a recorded fixture. Run a
+deterministic workflow simulation on invented, reviewed fixtures for success,
+failure, and refusal edges. Assert semantic attempts and edge outcomes, not
+real timestamps; simulation must never invoke the handler, connector, or
+network. Inspect the named template and safe run trail in Sandbox preview,
+then run scoped gates, exact-source `auto-review`, and host eject. The agent
+cannot approve the spec, install code into the running server, or push a
+repository from the Sandbox.
+
 ## Graph contract
 
 Version one is a bounded DAG. The graph contains:
@@ -41,9 +125,11 @@ Version one is a bounded DAG. The graph contains:
 - `agent`: calls one exact immutable agent revision and validates structured
   output.
 - `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `typed-decision`: routes one bounded typed answer through `pass` or `fail`.
 - `gate`: evaluates the versioned allowlisted logic language.
 - `validator`: validates an envelope against a pinned JSON schema.
 - `action`: calls one exact registered action contract version.
+- `human-approval`: waits for an `approvals.core` request to resolve.
 - `merge`: waits for all declared incoming paths.
 - `output`: settles the workflow with a typed result.
 

package/agent-template/.ai/README.md

@@ -10,6 +10,7 @@ Flowdular is an agentic foundation framework. The platform under `packages/`, `m
 | `rules/*.md`                                                 | Canonical cross-agent instructions. RuleSync generates the root `AGENTS.md` and `CLAUDE.md` from these files; `pnpm rules:check` rejects drift.                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `agents/sandbox/*.md`                                        | Loaded at sandbox start by `packages/coding-agent/src/roles/registry.ts` (`loadAgentRoles`); `gates`, `handoff` and `allowedPaths` are enforced. `dependencies` always runs, a `HANDOFF:` line must name a role from the list and never the role itself, and writes outside the active role allowlist are quarantined and restored before validation. Defaults in `packages/coding-agent/src/roles/defaults.ts` are regenerated from these files by `pnpm --filter @flowdular/coding-agent sync-roles`, and `tests/sync.test.ts` fails when they drift. |
 | `agents/{module-executor,reviewer,spec-author}.md`           | Read by people and coding tools at the repository root; named in `blueprints/*/blueprint.json`. Not loaded by code.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `subagents/*.md`                                             | The same three root roles as delegable subagents. RuleSync generates `.claude/agents/<name>.md` and `.codex/agents/<name>.toml` from them, so Claude Code and Codex can hand a phase to the role; each body points at its `agents/<id>.md` prompt and its one task skill.                                                                                                                                                                                                                                                                               |
 | `skills/*/SKILL.md`                                          | Canonical cross-agent procedures. They are copied into every sandbox session as `reference/skills/` (`packages/sandbox/src/server/reference.ts`) and RuleSync generates the discovery copies under `.agents/skills` and `.claude/skills`.                                                                                                                                                                                                                                                                                                               |
 | `blueprints/*/blueprint.json`                                | `pnpm flowdular blueprint list` and `blueprint validate --all` (`packages/cli/src/runner.ts`, discovery in `packages/cli/src/validation.ts` `findNamedFiles`) validate every `blueprint.json` against `packages/contracts/schemas/blueprint.schema.json` and check the companion files exist; `pnpm validate` runs it in CI. The sandbox labels sessions `new-module@1.0.0` and `edit-module@1.0.0`.                                                                                                                                                    |
 | `blueprints/*/*.yaml`, `*.schema.json`, `examples/`          | Existence-checked by `validateBlueprint`; otherwise documentation for agents and reviewers. Nothing executes `steps.yaml` or `gates.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -17,7 +18,7 @@ Flowdular is an agentic foundation framework. The platform under `packages/`, `m
 | `policies/task-budgets.yaml`, `policies/path-ownership.yaml` | Read by the `git-pr` delivery target (`packages/sandbox/src/server/delivery/policies.ts`): the changed-file and new-dependency budget per session kind, and path owners plus `crossOwnerChanges.requireReviewer` for the pull request body. Review guidance otherwise.                                                                                                                                                                                                                                                                                  |
 | `examples/**`                                                | Reference shapes for agents; not compiled or tested.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
-`AGENTS.md` and `docs/design-system.md` are copied into each session's `reference/` as well (`packages/sandbox/src/server/reference.ts`). `AGENTS.md`, `CLAUDE.md`, `.agents/skills` and `.claude/skills` are generated compatibility outputs. Edit `.ai/rules` or `.ai/skills`, then run `pnpm rules:generate`.
+`AGENTS.md` and `docs/design-system.md` are copied into each session's `reference/` as well (`packages/sandbox/src/server/reference.ts`). `AGENTS.md`, `CLAUDE.md`, `.agents/skills`, `.claude/skills`, `.claude/agents` and `.codex/agents` are generated compatibility outputs. Edit `.ai/rules`, `.ai/skills` or `.ai/subagents`, then run `pnpm rules:generate`.
 
 ## Using the skills from your own tool
 
@@ -27,8 +28,8 @@ sandbox turn receives one Task skill from `packages/coding-agent/src/roles/skill
 not the entire catalog. Character-budget and routing tests guard against prompt
 growth; characters are a stable size proxy, not a tokenizer-specific cost estimate.
 
-- Claude Code reads the generated `CLAUDE.md` and discovers the generated `.claude/skills` copies.
-- Codex reads the generated `AGENTS.md` and discovers the generated `.agents/skills` copies.
+- Claude Code reads the generated `CLAUDE.md` and discovers the generated `.claude/skills` copies and the `.claude/agents` subagents.
+- Codex reads the generated `AGENTS.md` and discovers the generated `.agents/skills` copies and the `.codex/agents` subagents.
 - Any other tool: paste `AGENTS.md` and the skill into the instruction.
 
 Both paths land the same way: gates, then `pnpm flowdular module enable <id> --apply` for a new module (it grants the module's scopes as its last step; `auth sync-scopes` re-grants later), `pnpm verify`, pull request (`skills/release-eject-pr`). A sandbox session is a pnpm workspace of its own with the draft modules as projects, so declared dependencies resolve for real and the `dependencies` gate runs after every turn.
@@ -39,6 +40,7 @@ Both paths land the same way: gates, then `pnpm flowdular module enable <id> --a
 - Skill: edit `skills/<kebab-name>/SKILL.md` with `name`, `description`, `roles`, `when`; keep it focused, verify API claims against the cited code, add a row in `skills/README.md`, then run `pnpm rules:generate`.
 - Blueprint: a directory under `blueprints/` with `blueprint.json` valid against `packages/contracts/schemas/blueprint.schema.json` plus `README.md`, `input.schema.json`, `plan.schema.json`, `spec-requirements.yaml`, `allowed-paths.yaml`, `required-files.yaml`, `steps.yaml`, `gates.yaml` (all required by `validateBlueprint`), and `examples/valid`, `examples/invalid` (`input*.json` validate against `input.schema.json`, `plan*.json` against `plan.schema.json`). `agentRoles` use the role ids from `agents/`; `executorProfiles` use the profile ids in `policies/model-routing.yaml`; gate ids for module blueprints come from `packages/sandbox/src/server/gates.ts`.
 - Sandbox role: `agents/sandbox/<id>.md` with the front matter `id`, `name`, `purpose`, `allowedPaths`, `gates`, `handoff` (see `agents/README.md`), then regenerate the bundled defaults: `pnpm --filter @flowdular/coding-agent sync-roles` (the script provided by `packages/coding-agent`; it rewrites `src/roles/defaults.ts` from these files) and run `pnpm --filter @flowdular/coding-agent test`.
+- Root subagent: `subagents/<name>.md` with the front matter `name`, `targets`, `description` and an optional `claudecode` block, a body that names the `agents/<id>.md` prompt and the one task skill, then `pnpm rules:generate`. Keep the procedure in the role prompt; the subagent file stays a pointer so the two cannot drift.
 - Policy: keep it truthful about what code enforces; name the file that does.
 
 Formatting: `npx prettier --write .ai docs`, then `pnpm rules:generate`. No em or en dashes anywhere.

package/agent-template/.ai/agents/README.md

@@ -17,7 +17,7 @@ The five roles and who takes the first turn: `business-manager` for both a new m
 
 ## Root roles run at the repository root
 
-`module-executor.md`, `reviewer.md`, `spec-author.md` describe the same jobs for an agent working in a checkout with a shell (Claude Code, Codex, a person). No code loads them; `.ai/blueprints/*/blueprint.json` names them in `agentRoles` and `requiredReviewers`. Their `allowedPaths` are relative to the repository root and they run the gates themselves with the commands listed in each blueprint's `gates.yaml`.
+`module-executor.md`, `reviewer.md`, `spec-author.md` describe the same jobs for an agent working in a checkout with a shell (Claude Code, Codex, a person). No code loads them; `.ai/blueprints/*/blueprint.json` names them in `agentRoles` and `requiredReviewers`, and `.ai/subagents/<id>.md` exposes each one as a delegable subagent that points back here (RuleSync writes `.claude/agents` and `.codex/agents`). Their `allowedPaths` are relative to the repository root and they run the gates themselves with the commands listed in each blueprint's `gates.yaml`.
 
 ## Adding or changing a role
 

package/agent-template/.ai/agents/sandbox/agentic-engineer.md

@@ -13,6 +13,7 @@ gates:
   - spec-schema
   - module-schema
   - dependencies
+  - module-rules
   - typecheck
   - tests
 handoff:

package/agent-template/.ai/agents/sandbox/backend-engineer.md

@@ -24,6 +24,7 @@ allowedPaths:
 gates:
   - module-schema
   - dependencies
+  - module-rules
   - typecheck
   - tests
   - format

package/agent-template/.ai/agents/sandbox/frontend-engineer.md

@@ -8,6 +8,7 @@ allowedPaths:
   - 'package.json'
 gates:
   - dependencies
+  - module-rules
   - typecheck
   - tests
   - format

package/agent-template/.ai/blueprints/add-migration/README.md

@@ -1,5 +1,5 @@
 # add-migration
 
-Add a table, column, index or constraint through the numbered migration runner. The `.up.sql` file is the source, `src/services/migration.ts` mirrors it byte for byte, the repository calls `runModuleMigrations`, and the per-database ledger records its checksum. Existing databases adopt complete pre-ledger schema without replaying it. Procedure: `.ai/skills/migration-authoring/SKILL.md`.
+Add a table, column, index or constraint through the numbered migration runner. The `.up.sql` file is the source, `src/services/migration.ts` mirrors it byte for byte, the repository calls `runDatabaseMigrations`, and the per-database ledger records its checksum. Existing databases adopt complete pre-ledger schema without replaying it. Procedure: `.ai/skills/migration-authoring/SKILL.md`.
 
 Additive only. A destructive change (drop, type change, tightened check) is refused by this blueprint's input schema and needs an operator decision.

package/agent-template/.ai/blueprints/add-migration/required-files.yaml

@@ -11,7 +11,7 @@ rules:
   - PostgreSQL only; CREATE TABLE IF NOT EXISTS
   - tenant_id TEXT NOT NULL on tenant-owned tables
   - UNIQUE and indexes start with tenant_id, indexes end with id
-  - a new tenant table enables and forces row-level security and adds a <table>_tenant_policy on current_setting('coreloom.tenant_id', true)
+  - a new tenant table enables and forces row-level security and adds a <table>_tenant_policy on current_setting('flowdular.tenant_id', true)
   - ALTER TABLE ADD COLUMN runs once through the ledger; inspectExisting detects an existing column
   - applied migration bytes are immutable; a change always gets a new number
   - inspectExisting returns complete only for every effect, absent only for none, partial for anything mixed

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

@@ -26,7 +26,7 @@ manifest:
       - ./server
       - ./platform
   src/platform.ts:
-    - createServerComposition(context) returns routes, optional settings (defineModuleSettings), optional start() and optional dispose()
+    - createServerComposition(context) returns routes, optional settings (defineModuleSettings), optional start() for registration only, optional startWorker() that starts every poll loop and background worker, optional stop() and optional dispose()
     - context carries auth, settings (ModuleSettingsRuntime), agentTools (PlatformToolRegistry), agentDefinitions (PlatformAgentRegistry) and capabilities (PlatformCapabilityRegistry)
 conditional:
   api:

package/agent-template/.ai/examples/bad/client-imports-server/README.md

@@ -2,7 +2,7 @@
 
 `api.ts` sits under `src/client` and imports `../services/database-repository.ts`, which pulls in `@flowdular/sdk/database` and its `node:fs`, `node:path` and `node:async_hooks` imports. The Vite client build fails on the Node built-ins, and even where it compiled the browser would hold a database handle and a `tenantId` parameter chosen by the caller, bypassing every endpoint check.
 
-Violated rules: `AGENTS.md` 5 and 6 (data reaches the client only through an endpoint that resolves identity and takes the tenant from the principal) and the layering in `.ai/skills/core-extend/SKILL.md` (client code imports `@flowdular/sdk/client`, `@flowdular/sdk/ui`, `octane`, `segment-state`, and the module's own `src/client` and `src/domain` types; never `src/services` or `src/server`).
+Violated rules: `AGENTS.md` 3 and 4 (data reaches the client only through an endpoint that resolves identity and takes the tenant from the principal) and the layering in `.ai/skills/core-extend/SKILL.md` (client code imports `@flowdular/sdk/client`, `@flowdular/sdk/ui`, `octane`, `segment-state`, and the module's own `src/client` and `src/domain` types; never `src/services` or `src/server`).
 
 Repair with the `bug-fix` blueprint: replace the import with a `fetch` in `src/client/api.ts` as in `.ai/references/catalog/src/client/api.ts`:
 

package/agent-template/.ai/examples/bad/missing-acl/README.md

@@ -2,7 +2,7 @@
 
 `endpoints.ts` mounts `/api/customers` with `new ServerRoute` from `@octanejs/app-core`. Nothing resolves an identity, nothing checks a permission, and `listAll()` has no tenant. Anyone who can reach the server reads every tenant's customers.
 
-Violated rules: `AGENTS.md` 5 (every endpoint is `defineEndpoint` with `access: { kind: 'permission' }` and `resolveIdentity: endpointIdentityFromContext`) and 6 (tenant id from the principal). The security skill's first grep (`grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth`) finds it.
+Violated rules: `AGENTS.md` 3 (every endpoint is `defineEndpoint` with `access: { kind: 'permission' }` and `resolveIdentity: endpointIdentityFromContext`) and 4 (tenant id from the principal). The security skill's first grep (`grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth`) finds it.
 
 Repair with the `bug-fix` blueprint (or `edit-module`, change class `endpoint`):
 

package/agent-template/.ai/examples/bad/tenant-from-body/README.md

@@ -2,7 +2,7 @@
 
 `endpoints.ts` has a permission and an identity resolver, and still lets a member of tenant A create a customer in tenant B by posting `{ "tenantId": "B", "name": "..." }`. The permission check passes because the principal holds `customers.records.manage` in its own tenant; the body decides where the row lands. The mutation also skips `sessionMutationDenial`, so a cross-site form post with a valid cookie would be accepted.
 
-Violated rules: `AGENTS.md` 6 (tenant id only from `principalFromContext(octane)!.tenantId`) and 7 (`sessionMutationDenial(octane, auth)` first on every mutation). The security skill's grep `grep -rn tenantId modules/*/src/api | grep -v principalFromContext` finds it.
+Violated rules: `AGENTS.md` 4 (tenant id only from `principalFromContext(octane)!.tenantId`) and 3 (an explicit permission and an identity resolver on every endpoint). The security skill's grep `grep -rn tenantId modules/*/src/api | grep -v principalFromContext` finds it.
 
 Repair with the `bug-fix` blueprint: remove the body field, take `auth: AuthRuntime` in `createCustomerRoutes`, and write