create-flowdular 0.2.6 → 0.3.1

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

@@ -119,7 +119,7 @@ Dependencies: `package.json` gets `"@flowdular/sdk/harness": "workspace:*"`. You
 - A mutating tool with `idempotency: 'required'` is executable only after the target module implements a durable ledger and the definition declares `idempotencyProtection: 'target-ledger'`. The harness derives a stable key from the durable run id and deterministic tool-call ordinal. The target ledger binds `(tenant, tool id, key)` to a canonical input hash and the first result. A replay returns that result without another mutation; the same key with another tool or input fails closed. Provider tool-call ids are audit metadata only. Never add the declaration before the target migration, repository transaction, and crash-recovery test exist.
 - Each call has a deadline (`tool.timeoutMs`, default 30 s, range 250 to 600000) and the harness caps serialized output at 32 KB (`boundToolOutput`), marking `truncated`. Still page or limit your rows so one call cannot dominate the run window.
 - Events per call land in the run's persisted audit chain: `tool.started`, then `tool.completed` (metadata `tool`, `outputCharacters`, `truncated`) on success, `tool.failed` (reason) on error, or `tool.denied` (reason) when not granted or input-invalid.
-- Runs are enqueued by `POST /api/agent-runs` behind `agents.runs.execute`, claimed by `AgentWorker` with a lease, observed through `GET /api/agent-runs` and the SSE stream. The registered tool ids surface in `GET /api/agents` `tools`, which the Agents form reads to build the allowed-tools grid. Never make a tool block on user input.
+- Runs are enqueued by `POST /api/agent-runs` behind `agents.runs.execute`, claimed by `AgentWorker` with a lease, observed through `GET /api/agent-runs` and the SSE stream. The registered tool ids surface in `GET /api/agents/context` `tools`, which the Agents form reads to build the allowed-tools grid. Never make a tool block on user input.
 
 ## 4. Deliverables for a module
 

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

@@ -20,7 +20,7 @@ Check every route in `src/api/endpoints.ts` against `.ai/references/catalog/src/
 
 ## 2. Scope model
 
-`modules/auth/src/acl/scopes.ts`: `AUTH_SCOPES`, `PLATFORM_SCOPES` (`system.workspace.access` gates the shell in `platform/src/App.tsrx`; `system.settings.read` and `system.settings.manage` guard `GET /api/settings` and `POST /api/settings/update` in `modules/auth/src/server/settings-endpoints.ts`), `BUNDLED_MODULE_SCOPES`, `OWNER_SCOPES` (all of them), `MEMBER_SCOPES` (read scopes plus `agents.runs.execute`). Sign-up creates an owner with `OWNER_SCOPES`; member creation copies `OWNER_SCOPES` or `MEMBER_SCOPES` by role (`modules/auth/src/services/auth-service.ts`). A module's scopes reach existing owners through `pnpm flowdular module enable <id> --apply` (which runs the grant) or `pnpm flowdular auth sync-scopes --module <id> --apply` for a re-grant. Navigation in the `Development` group is owner-only in the client (`packages/client/src/shell/navigation.ts`); the server permission stays authoritative.
+`modules/auth/src/acl/scopes.ts`: `AUTH_SCOPES`, `PLATFORM_SCOPES` (`system.workspace.access` gates the shell in `platform/src/App.tsrx`; `system.settings.read` and `system.settings.manage` guard `GET /api/settings` (`system.settings.list`) and `POST /api/settings/update` (`system.settings.update`) in `modules/system/src/server/endpoints.ts`, from `SYSTEM_PERMISSIONS` in `modules/system/src/acl/permissions.ts`), `BUNDLED_MODULE_SCOPES`, `OWNER_SCOPES` (all of them), `MEMBER_SCOPES` (read scopes plus `agents.runs.execute`). Sign-up creates an owner with `OWNER_SCOPES`; member creation copies `OWNER_SCOPES` or `MEMBER_SCOPES` by role (`modules/auth/src/services/auth-service.ts`). A module's scopes reach existing owners through `pnpm flowdular module enable <id> --apply` (which runs the grant) or `pnpm flowdular auth sync-scopes --module <id> --apply` for a re-grant. Navigation in the `Development` group is owner-only in the client (`packages/client/src/shell/navigation.ts`); the server permission stays authoritative.
 
 Review question: does every new scope appear in the spec `permissions`, in `src/acl/permissions.ts`, on the endpoint, and on the client contribution that exposes it?
 

package/agent-template/.agents/skills/cli-extension/SKILL.md

@@ -85,7 +85,7 @@ export default cliExtension;
 
 ## 4. What the runner does with the descriptor (`packages/cli/src/runner.ts`, `runExtensionCommand`)
 
-- `risk: 'external'`: refused with `APPROVAL_VERIFIER_REQUIRED`. `risk: 'destructive'` without `localOnly`: the same.
+- `risk: 'external'`, or `'destructive'` without `localOnly`: refused with `APPROVAL_VERIFIER_REQUIRED` unless `--grant <token> --tenant <id>` carries a verified approval grant for this capability and invocation digest (`APPROVAL_GRANT_INVALID`, `APPROVAL_GRANT_EXPIRED`, `APPROVAL_GRANT_MISMATCH` otherwise).
 - `localOnly: true`: refused with `LOCAL_ONLY_CAPABILITY` unless `FD_ENV` or `NODE_ENV` is `development` or `test` (unset counts as development).
 - `requiresApprovedSpec: true`: needs `--spec <path>` to a schema-valid spec with `status: approved`, otherwise `APPROVED_SPEC_REQUIRED`, `SPEC_VALIDATION_FAILED` or `SPEC_NOT_APPROVED`.
 - `destructive` with `--apply`: needs `--confirm <confirmation>` (`CONFIRMATION_REQUIRED`).

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

@@ -0,0 +1,114 @@
+---
+name: deploy-operate
+description: >-
+  Build, configure, roll out and operate a Flowdular application: the container
+  image, the production environment keys, migrations at rollout, health and
+  readiness, backup and restore, and rollback.
+---
+# Deploy and operate
+
+This is host work, not sandbox work. A sandbox specialist has no network, no git and no deployment.
+
+## 1. Container build
+
+`infra/docker/Dockerfile` is a two-stage build on `node:24-bookworm-slim`. The builder enables corepack, pins `pnpm@11.17.0`, runs `pnpm install --frozen-lockfile`, then `pnpm verify && pnpm build`, so a failing gate fails the image. The runtime stage copies only `platform/dist` and `platform/package.json`, runs as the non-root user `octane` (uid 1001), exposes 3000, declares the `/data` volume and starts `node platform/dist/server/entry.js`. Its `HEALTHCHECK` polls `/api/health`.
+
+```bash
+docker compose -f infra/docker/compose.yaml up --build   # local stack: postgres-tls, postgres 17 with ssl=on, app
+```
+
+The compose `app` service runs `read_only: true` with a `tmpfs` on `/tmp` and publishes `${FD_PORT:-3000}`. Tagging `v*.*.*` (or running the workflow by hand) builds and pushes the same Dockerfile to `ghcr.io/<repository>` through `.github/workflows/container.yml`. Kubernetes manifests live in `infra/kubernetes` and apply with `kubectl apply -k infra/kubernetes`; the secrets they expect have examples in the same directory. `infra/README.md` carries the local and cluster walkthrough.
+
+## 2. Production environment
+
+`docs/configuration.md` is the reference. The keys a production deployment must set:
+
+| Key                             | Why                                                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `NODE_ENV=production`           | Turns on every production refusal below; `FD_ENV=production` only gates the CLI local-only commands |
+| `FD_DATABASE_ADAPTER`           | Must not be `pglite`; production refuses the embedded adapter                                       |
+| `FD_DATABASE_URL`               | Runtime role, neither `SUPERUSER` nor `BYPASSRLS`                                                   |
+| `FD_DATABASE_MIGRATOR_URL`      | Separate DDL role; required in production                                                           |
+| `FD_DATABASE_TLS=verify-full`   | The only value production accepts, with `FD_DATABASE_TLS_CA[_FILE]`                                 |
+| `FD_AUTH_PUBLIC_ORIGIN`         | Same-origin checks and cookie scope                                                                 |
+| `FD_AUTH_SECURE_COOKIE`         | `Secure` and the `__Host-` cookie prefix; defaults on in production                                 |
+| `FD_AUTH_MFA_KEY`               | Decrypts stored MFA secrets                                                                         |
+| `FD_AGENT_CREDENTIAL_KEY`       | `agents.core` refuses to boot without it                                                            |
+| `FD_AGENT_RUN_GRANT_KEY`        | `agents.core` refuses to boot without it                                                            |
+| `FD_WORKFLOWS_PAYLOAD_KEY`      | `workflows.core` refuses to boot without it                                                         |
+| `FD_WORKFLOWS_CURSOR_KEY`       | `workflows.core` refuses to boot without it                                                         |
+| `FD_AUTOMATIONS_CREDENTIAL_KEY` | `automations.core` refuses to boot without it                                                       |
+| `FD_NOTIFICATIONS_SECRET_KEY`   | `notifications.core` refuses to boot without it                                                     |
+| `FD_CONNECTORS_SECRET_KEY`      | `connectors.core` refuses to boot without it                                                        |
+| `FD_AUDIT_ANCHOR_KEY`           | `audit.core` refuses to seal or verify without it in production                                     |
+
+Every key above is base64 of 32 random bytes where it names a key. `FD_AUTOMATIONS_CREDENTIAL_KEY` is read by `modules/automations/src/services/secret-vault.ts`, which throws `FD_AUTOMATIONS_CREDENTIAL_KEY is required in production.`; in development it generates and persists a local key file instead, so a deployment that never set it fails only at the production boot. Set it whenever `automations.core` is enabled in `flowdular.json`.
+
+Set `FD_TRUST_PROXY` behind a load balancer. `FD_DATABASE_BACKGROUND_URL` gives worker traffic its own pool. Everything else in `docs/configuration.md` has a working default.
+
+## 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`):
+
+```bash
+pnpm flowdular migration status [--module <id>]      # what the ledger holds
+pnpm flowdular migration verify                      # checksums against the shipped SQL
+pnpm flowdular migration apply --module <id>         # dry run, one module at a time
+pnpm flowdular migration apply --module <id> --apply # writes
+```
+
+`migration apply` carries the `migration.apply.local` capability, which is `localOnly`: the runner refuses it with `LOCAL_ONLY_CAPABILITY` unless `FD_ENV` or `NODE_ENV` is `development` or `test`. It is therefore a local and staging tool as the code stands, not a production rollout step. In production the application applies its own module migrations at boot under a migration lease using `FD_DATABASE_MIGRATOR_URL`, so the rollout order is: apply the new image, let it migrate, then verify. A new module needs `pnpm flowdular module enable <id> --apply` (which grants its scopes) in the workspace before the image is built.
+
+Never edit an applied `.up.sql`, not even whitespace: the checksum changes and the next boot refuses to start.
+
+## 4. Health and readiness
+
+- `GET /api/health` is public and static. It proves the process is up and nothing else. Use it as the liveness probe.
+- `GET /api/ready` is public and calls the database provider: it checks the runtime and background roles are neither superuser nor `BYPASSRLS`, then runs a statement on the migrator pool. It answers 503 with `retry-after: 1` when the database is unavailable. Use it as the readiness probe.
+
+Both are served by `platform/src/server/health.ts`. The shipped Docker and Kubernetes probes all point at `/api/health`; moving the readiness probe to `/api/ready` is the improvement worth making. Before the database is configured the application runs in setup mode and `/api/ready` is not routed at all, so a first-run container answers 404 there rather than 503.
+
+## 5. Backup, restore, and the key trap
+
+`docs/operations.md` is the runbook. Read it before touching production data; this skill does not restate it. The commands:
+
+```bash
+pnpm flowdular database backup --output <dir>                            # dry run
+pnpm flowdular database backup --output <dir> --apply
+pnpm flowdular database restore --input <dir> --apply --confirm restore-database
+pnpm flowdular database restore-production --input <dir> --target <db> --grant <token> --tenant <id> [--platform-url <origin>|--platform-stopped] --apply --confirm restore-database
+```
+
+Production restores run `database.restore.production`: an approval grant bound to the exact flags, `--target` equal to the migrator DSN database, a separate migrator DSN, a key mismatch refused unless the approval included `--allow-key-mismatch`, and a refusal while the health endpoint answers. PITR for the compose stack is `infra/docker/pitr.sh` (see `infra/README.md`); in Kubernetes it is the managed provider's job.
+
+The trap: **the encryption keys live outside the database.** Agent provider credentials, agent run grants, workflow payloads and cursors, automation secrets, MFA secrets, stored objects and connector credentials are all stored as ciphertext, and the keys are environment variables (`FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`, `FD_WORKFLOWS_PAYLOAD_KEY`, `FD_WORKFLOWS_CURSOR_KEY`, `FD_AUTOMATIONS_CREDENTIAL_KEY`, `FD_AUTH_MFA_KEY`, `FD_NOTIFICATIONS_SECRET_KEY`, `FD_STORAGE_ENCRYPTION_KEY`, `FD_CONNECTORS_SECRET_KEY`, `FD_AUDIT_ANCHOR_KEY`). A database backup without the matching keys restores rows nobody can read, and rotating a key without re-encrypting orphans everything encrypted under the old one; every sealing key has a `secrets-rotate` command in the runbook's rotation table, the storage key two (`documents` and `exports`). Back the keys up separately, restore them together with the dump, and record which key version a dump belongs to.
+
+## 6. Rollback
+
+1. Redeploy the previous image tag. Module migrations are additive (`CREATE TABLE IF NOT EXISTS`, `ADD COLUMN`), so an older image runs against a newer schema; it ignores columns it does not know.
+2. Never run a `.down.sql` to roll back a release. They document the reverse for review, and applying one against live data is data loss.
+3. To take one module out of service without a redeploy: `pnpm flowdular module disable <id> --apply` (it is a dry run without `--apply`), then rebuild the composition and redeploy. Its tables stay.
+4. If the rollback is because of a key change, restore the previous key first; the image alone will not fix unreadable ciphertext.
+
+- For data loss between two dumps use PITR (`pitr.sh restore --target-time`), never a `.down.sql`.
+
+## 7. Production checklist
+
+- `pnpm verify` and `pnpm build` pass on the commit being shipped (the image build runs both).
+- `NODE_ENV=production`, a PostgreSQL adapter, `FD_DATABASE_TLS=verify-full` with its CA.
+- Runtime role has neither `SUPERUSER` nor `BYPASSRLS`; the migrator role is separate.
+- Every encryption key set, stored outside the database, and backed up with a recorded version.
+- `FD_AUTOMATIONS_CREDENTIAL_KEY` set whenever `automations.core` is enabled in `flowdular.json`, `FD_NOTIFICATIONS_SECRET_KEY` whenever `notifications.core` is, `FD_CONNECTORS_SECRET_KEY` whenever `connectors.core` is, and `FD_AUDIT_ANCHOR_KEY` whenever `audit.core` is.
+- `FD_AUTH_PUBLIC_ORIGIN` matches the public URL; `FD_AUTH_SECURE_COOKIE` on; `FD_TRUST_PROXY` set behind a proxy.
+- Sign-up closed (`FD_AUTH_ALLOW_SIGN_UP`) unless the deployment is public; the first owner created with `flowdular auth workspace-create` (see `docs/cli.md`).
+- Liveness on `/api/health`, readiness on `/api/ready`.
+- `pnpm flowdular migration verify` clean after rollout, and `pnpm flowdular doctor --json` reports `status: healthy`.
+- A restore has been rehearsed once, keys included, and a PITR restore once from the newest base backup.
+
+## Pitfalls
+
+- `setup quick` and `auth greenfield` are local resets that wipe auth data. They refuse outside `development` and `test`; never point them at a deployment.
+- `pglite` is the local and test adapter. A production boot with it is refused, not degraded.
+- A module added to the workspace but not enabled is absent from the built image: `module enable` writes the generated composition, and `pnpm build` bakes it in.
+- Scopes for a new permission reach existing owners only after `flowdular auth sync-scopes --module <id> --apply`; an endpoint can be live while every user gets 403.
+- Rotating `FD_AUTH_MFA_KEY` locks out every enrolled user, not just new enrolments.

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

@@ -10,6 +10,35 @@ The reference module is `.ai/references/catalog` (in a sandbox session: `referen
 
 Two ways to land the same module: the sandbox (a brief, specialist turns, gates after every turn, preview, eject) or the direct path (this skill in your own coding tool, the gates by hand, `pnpm verify`, a pull request). The sections below mark the differences.
 
+## Spec is the contract
+
+With an approved `schemaVersion: 2` spec, the specification is the requirement document and you do not go looking for one. Read the spec, the files on this skill's touch list, and `.ai/references/catalog` for shape. Do not scan `modules/` or `packages/`; `.ai/platform-capabilities.md` answers what the platform provides, and the reference module answers what the code looks like.
+
+Anything the spec does not say is a spec defect, not a decision you make. A missing field, an unstated conflict behaviour, an undefined state transition, a screen without columns: report it back. In the sandbox that is `HANDOFF: business-manager - <what is missing>`; on a host it is a question to the user. Never fill the gap with a plausible guess, and never implement anything listed in `outOfScope[]`.
+
+Every `acceptanceScenarios[]` entry maps to at least one test in `tests/`. A scenario with no test is unfinished work, and the scenario id belongs in the test name so the mapping is readable.
+
+Each spec element maps to files:
+
+| Spec element                  | Files it produces                                                                                                                                       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities[]`                  | `src/domain/types.ts`, `migrations/000N_<module>_<name>.{up,down}.sql`, `src/services/migration.ts`, `src/services/{repository,database-repository}.ts` |
+| `entities[].fields[]`         | the columns and row mapping above, the validation bounds in `src/api/endpoints.ts`, the form field and table cell in `src/client/*.tsrx`                |
+| `fields[].unique: tenant`     | a `(tenant_id, <field>)` unique index in the migration plus the stable conflict code in the service                                                     |
+| `entities[].states`           | the status column, the transition guard in the service, the `Tag` tone in the view                                                                      |
+| `screens[]`                   | `src/client/<Pascal>View.tsrx`, a `views` entry and a `navigation` entry in `src/client/contribution.tsrx`, `translations/*.json`                       |
+| `screens[].columns`/`filters` | the `TableColumn[]` outside the component, and the controls inside the `Filters` dropdown                                                               |
+| `screens[].navigationGroup`   | the navigation entry's `group`                                                                                                                          |
+| `actions[]`                   | the service method with its error code, the `defineEndpoint` route, the fetch in `src/client/api.ts`                                                    |
+| `widgets[]`                   | a widget component plus a `widgets` entry with its `slot` in `src/client/contribution.tsrx`                                                             |
+| `settings[]`                  | `src/settings.ts` (`defineModuleSettings`) and `settings:` in `src/platform.ts`                                                                         |
+| `agentTools[]`                | `src/agent/tools.ts` and the `context.agentTools.register` call, as a separate `agent-tool-design` phase                                                |
+| `permissions[]`               | `src/acl/permissions.ts`, the endpoint `access.permission`, the client `scope`                                                                          |
+| `acceptanceScenarios[]`       | `tests/module.test.ts` and its siblings, at least one case each                                                                                         |
+| `outOfScope[]`, `decisions[]` | no code. Read them so you do not rebuild a decision or implement a deferred feature.                                                                    |
+
+A v1 spec stays valid and carries none of these arrays. Then the requirements are `invariants`, `permissions` and `acceptanceScenarios`, and everything the spec leaves open is still a question rather than a guess.
+
 ## 1. Preconditions
 
 - `pnpm flowdular doctor --json` reports `status: healthy` (repository root only; the sandbox runs gates for you).

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

@@ -6,6 +6,14 @@ description: >-
 ---
 # Update an existing module
 
+## Spec is the contract
+
+With an approved `schemaVersion: 2` spec delta, the specification is the requirement document. Read the spec, the module itself, the touch list for the change class below, and `.ai/references/catalog` for shape. Do not scan `modules/` or `packages/`: `.ai/platform-capabilities.md` answers what the platform provides.
+
+Anything the delta does not say is a spec defect, not your decision. Report it back (`HANDOFF: business-manager - <what is missing>` in the sandbox, a question to the user on a host) instead of guessing, and never implement an item the spec parks in `outOfScope[]`. Every new or changed `acceptanceScenarios[]` entry maps to at least one test, with the scenario id in the test name.
+
+The spec-element to file mapping is the table in `module-new`; the change classes below are the same mapping arranged by what you are changing.
+
 ## 1. Read first
 
 Read the whole module before changing it: `spec/module.yaml`, `src/index.ts`, `src/acl/permissions.ts`, `src/api/endpoints.ts`, `src/services/*`, `src/client/*`, `tests/`. Keep every exported name in `src/index.ts`, `src/server/index.ts` and `src/client/index.ts` stable: other modules import them (`modules/users` uses `AuthRuntime` from `@flowdular/sdk/modules/auth/server`), and the generated composition imports `createServerComposition` and `createClientContribution`.
@@ -62,7 +70,7 @@ Business agent: use `business-agent-design` as a separate phase; add the approve
 
 ## 3. Versions and spec
 
-Bump `spec/module.yaml` `specVersion`, `module.json` `version` and `package.json` `version` together (patch for a fix, minor for a new endpoint, screen or column). Add an acceptance scenario for every new behaviour and an invariant for every new rule; the scenario id matches `^[A-Z][A-Z0-9-]+$`. In the sandbox the business manager leaves the changed spec in `draft` or `in-review`; only the operator approval route records the approved hash and permits implementation.
+Bump `spec/module.yaml` `specVersion`, `module.json` `version` and `package.json` `version` together with `pnpm flowdular module version bump <id> <patch|minor|major> --apply` (patch for a fix, minor for a new endpoint, screen or column); it also retargets every dependent `^` range that stops matching. A new `context.capabilities.register` id goes under `provides` in `module.json`; a new `context.capabilities.get` id goes under `requires`. Add an acceptance scenario for every new behaviour and an invariant for every new rule; the scenario id matches `^[A-Z][A-Z0-9-]+$`. In the sandbox the business manager leaves the changed spec in `draft` or `in-review`; only the operator approval route records the approved hash and permits implementation.
 
 ## 4. Gates
 

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

@@ -0,0 +1,114 @@
+---
+name: spec-interview
+description: >-
+  Turn a business request into a schema-valid v2 module specification by
+  proposing a platform default for every decision and asking only what cannot be
+  inferred, so implementation never has to guess or scan the repository.
+---
+# Interview a request into a specification
+
+The specification is the contract implementation reads instead of the repository. Everything an engineer would otherwise have to guess belongs in it: entities, fields, screens, actions, settings, tools, and what was deliberately left out. A missing decision costs a round trip later, so surface it now.
+
+Work closed-world. `.ai/platform-capabilities.md` is the complete list of what the platform can deliver. Anything outside it is `outOfScope` with the business decision that replaces it, never a promise.
+
+## 1. Read exactly this
+
+1. `.ai/platform-capabilities.md`, the capability card (in a session: `reference/platform-capabilities.md`).
+2. `packages/contracts/schemas/module-spec.schema.json`, the shape and the enums (in a session: `reference/packages/contracts/schemas/module-spec.schema.json`).
+3. `.ai/references/catalog/spec/module.yaml`, a written example (in a session: `reference/example-module/spec/module.yaml`).
+
+For an edit, also read the module's current `spec/module.yaml` and write the smallest delta. Do not open `modules/` or `packages/` for anything else; the card carries what you need, and a fact it lacks is a question, not a search.
+
+## 2. Decision checklist
+
+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[]`                             |
+| Agent tools            | None. A tool is a later phase and `risk` may only be `read` or `workspace-write`            | `agentTools[]`                           |
+| 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[]`            |
+
+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.
+
+## 3. Ask only what you cannot infer
+
+Ask when the answer is a business fact: who may see a price, whether a code is unique across the company or per branch, what happens to an order whose customer is deleted. Never ask what the card already answers, and never ask two questions where one choice settles both. Keep it under about six questions per turn.
+
+In the sandbox, end the reply with exactly one fenced block tagged `questions`, nothing after it:
+
+````text
+```questions
+{
+	"questions": [
+		{
+			"id": "Q-1",
+			"question": "Is the item code unique for the whole workspace or per warehouse?",
+			"options": ["Unique per workspace", "Unique per warehouse"],
+			"recommended": "Unique per workspace",
+			"allowFreeText": true
+		}
+	]
+}
+```
+````
+
+The sandbox renders it as a form and the answers return in the next turn as a `Decisions` section. Outside the sandbox: in Claude Code ask through the question tool with the same options, and in Codex ask in plain text with the options numbered. In every host, `recommended` is the default from the card, and an unanswered question stays a question, never a guess.
+
+When the answers come back, copy each one into `decisions[]` with `decidedBy: user` and the answer text, and update whatever the answer changed.
+
+## 4. Write the specification
+
+`modules/<dir>/spec/module.yaml`, `schemaVersion: 2`, `status: draft`. Keep the v1 keys (`id`, `specVersion`, `name`, `description`, `profile`, `capabilities`, `dependencies`, `tenancy`, `locales`, `invariants`, `permissions`, `dataOwnership`, `acceptanceScenarios`) and add the v2 arrays:
+
+- `entities[]`: `{ id, name, fields[], states? }`. A field is `{ id, type, required?, unique?, maxLength?, values?, reference?, description? }`. `type` is one of `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference`, `json`; `unique` is `tenant` or `none`. `enum` needs `values`, `reference` needs `reference`. Entity and screen ids are `^[a-z][a-z0-9-]*$`; field and setting keys are `^[a-z][a-zA-Z0-9]*$`. Money is `integer` minor units plus an explicit currency field, never `decimal`.
+- `screens[]`: `{ id, kind: list|record|form|dashboard, entity?, title?, columns?, filters?, navigationGroup? }`. `navigationGroup` is one of the six values on the card.
+- `actions[]`: `{ id, entity?, permission, kind: create|update|delete|custom, risk, idempotent, description }`. `risk: external` is refused by the platform, so an action may not declare it.
+- `widgets[]`: `{ id, slot, entity?, description }`; `slot` is one of the four workspace slots.
+- `settings[]`: `{ key, type: string|integer|boolean|enum, scope: tenant|platform, default?, values?, description }`.
+- `agentTools[]`: `{ id, permission, description, risk: read|workspace-write }`.
+- `outOfScope[]`: plain sentences, each naming the gap and the decision taken instead.
+- `decisions[]`: `{ id, question, answer, decidedBy: user|default }`; ids match `^[A-Z][A-Z0-9-]+$`, for example `D-UNIQUE-SKU`.
+
+Put the primary entity's read and manage permissions first: the scaffold builds that entity and later permissions become constants only. Every `acceptanceScenarios[]` entry stays observable (given, when, then) and covers success, denial and the cross-tenant case, because each one becomes at least one test. The schema rejects unknown keys.
+
+## 5. Validate
+
+```bash
+pnpm flowdular spec validate --all --json
+```
+
+In the sandbox this is the `spec-schema` gate and runs for you. Fix every issue before ending the turn; a spec that does not validate cannot be approved.
+
+## 6. Close the turn
+
+End with the decision list: each decision, the answer, and whether it came from the user or from a platform default. Then state plainly that implementation cannot start until the operator approves this exact specification, and that any later edit invalidates that approval. In the sandbox the operator approves the exact hash; on a host, approval is recorded only through `spec-approval` after an explicit user instruction.
+
+Sandbox handoff: `HANDOFF: none - <the open questions>` while questions are outstanding, otherwise the next specialist with the reason.
+
+## Refusals
+
+- Never write `status: approved`, and never claim a spec is approved. Approval is the operator's act.
+- Never write TypeScript, `module.json`, `package.json` or any implementation file. This skill produces `spec/module.yaml` and, where the role allows, `translations/**`.
+- Never invent a business fact. An unanswered question is `decisions[]` left open plus a question, not a plausible answer.
+- Never promise a capability the card lists as missing. It goes to `outOfScope[]`.
+
+## Pitfalls
+
+- A field nobody asked for is a cost forever. If the request did not name it, leave it out and record the omission.
+- `unique: tenant` without a stated conflict behaviour produces an undefined error path; pair it with an acceptance scenario.
+- `states` without `transitions` lets any state reach any other. Name the legal moves and their permission.
+- A screen with no `columns` gives the engineer nothing to build; list the identifying fields in display order.
+- An `enum` field with values that are really a lookup table wants its own entity instead.
+- Bumping `specVersion` is part of an edit, not an afterthought; the delivery gate compares it.

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

@@ -60,8 +60,17 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Button`: `variant` primary, secondary (default), ghost, danger; `size` sm, md, lg; `type` button, submit; `block`; `disabled`; `onClick`.
 - `FormField`: `label`, `required`, `help`, `error`; one control child with `ui-input`, `ui-select` or `ui-textarea`.
 - `SearchField`: `value`, `placeholder`, `label` (accessible name), `onInput(value)`.
-- `Table`: `columns: TableColumn<Row>[]` (`key`, `header`, required `width`, `cell(row)`, `numeric`), `rows`, `rowKey(row)`, `status`, `loadingLabel`, `empty`, `emptyFiltered`, `filtered`, `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px default, 280 px for two actions), `onSelect(row)`, `selectedKey`, `caption`.
+- `Table`: `columns: TableColumn<Row>[]` (`key`, `header`, required `width`, `cell(row)`, `numeric`, `value(row)` for the comparable and searchable value behind the cell), `rows`, `rowKey(row)`, `status`, `loadingLabel`, `empty`, `emptyFiltered`, `filtered`, `sorting` with `sortingState` and `onSortingChange`, `globalFilter`, `pagination` (`pageIndex`, `pageSize`, `onPageChange`, `totalRows` when the module paged in SQL), `actions(row): TableAction[]`, `actionsLabel`, optional stable `actionsWidth` (160 px default, 280 px for two actions), `onSelect(row)`, `selectedKey`, `caption`. Only a column with `value` is sortable and searched. Multi-row selection: `selection` (`selectedKeys: ReadonlySet<string>`, `onSelectionChange(keys)`, `label` of the header checkbox, `rowLabel(row)`, optional `selectable(row)` and `clearLabel`) adds a leading checkbox column whose header toggles the rows on screen; `bulkActions: TableBulkAction[]` (`id`, `label`, `icon`, `tone`, `disabled`, `reason`, `onSelect(keys)`) render in the bar above the table while something is selected, and `selectionSummary(count)` translates "N selected". The screen keeps the keys in its own state and resets them on a page, sort or filter change; the header checkbox touches only the rows on screen, while the clear button empties the whole set through `onSelectionChange`.
 - `TableCard`: every `Table` prop plus `title`, `count`, `head`, `search`, `filters`, `before`, `after`, `note`, `noteIcon`.
+- `Pagination`: the pager for the `TableCard` `after` slot: `pageIndex`, `pageSize`, `totalRows` (after the screen's own filtering), `onPageChange(pageIndex)`, `pageSizes` with `onPageSizeChange(pageSize)` (both or neither), `label`, `previousLabel`, `nextLabel`, `pageSizeLabel`, `summary(range)` that the screen translates. It reads "1 of 1" over an empty set, so it is rendered unconditionally.
+- `Select`: the labelled native select: required `id`, `label`, `options` (`value`, `label`, `disabled`), `value`, `onChange(value)`, `placeholder`, `name` (defaults to `id`), `required`, `disabled`, `invalid`, `help`, `error`.
+- `DateField`: required `id`, `label`, ISO `value` (`YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` for `kind="datetime"`), `onChange(value)`, `kind`, `locale` from `activeLocale()`, `min`, `max`, `name`, `required`, `disabled`, `invalid`, `help`, `error`, `describedBy` for a message a group around it owns. The reading beside the input repeats the value in the reader's locale.
+- `DateRangeField`: required `id`, `legend`, `fromLabel`, `toLabel`, `value` (`from`, `to`), `onChange(value)`, `kind`, `locale`, `min`, `max`, `required`, `disabled`, `reversedMessage`, `help`, `error`; each side bounds the other and a reversed range is reported, never swapped.
+- `Tabs`: required `id`, `items` (`id`, `label`, `disabled`), `active`, `onChange(id)`, `label`; it renders only the tablist, and the caller renders `<id>-panel-<active>` labelled by `<id>-tab-<active>`.
+- `ToastHost`: `label`, `closeLabel`, optional `store`. One per screen that raises toasts, rendered even while empty; `toasts.success`, `.error` and `.info` raise them and `createToastStore` makes a scoped queue.
+
+`Select`, `DateField` and `DateRangeField` own their label, so they go straight into a `ui-form__row` and never inside a `FormField`.
+
 - `Filters`: `open`, `onToggle`, `activeCount`, `label`; children are the filter controls, which belong in the dropdown and nowhere else.
 - `CheckGrid`: `groups: { label, options: { value, label, hint? }[] }[]`, `value: string[]`, `mono`, `disabled`, `onChange(next)`.
 - `Drawer`: `open`, `title`, `subtitle`, `width` md or lg, `onClose`; child is `ui-drawer__form` or `ui-drawer__body`. Escape and the scrim close it.
@@ -74,16 +83,38 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Icon`: `name`, `size` (18 default, 16 in controls, 14 in `Button size="sm"`), `strokeWidth`.
 - `BrandMark`: `size`, `signature`, `tone`; 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`, `chevrons-up-down`, `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`, `alert`, `x`, `sign-out`, `refresh`, `help`, `key`, `settings`, `braces`. An unknown name renders `modules` silently, so check the list.
+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`. An unknown name renders `modules` silently, so check the list.
 
 ## 5. Classes a module writes by hand (`packages/ui/src/styles/components.css`)
 
-Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (h2 plus actions inside a view), `ui-toolbar` (+`__spacer`). Surfaces `ui-card` (+`__head`, `__title`, `__body`). Data `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__state` for a dot plus label, `.num`), `ui-cell` (+`ui-cell__muted`), `ui-mono`, `ui-code`, `ui-dot` (+`--muted`). Row action classes are component-owned and are never written by a module. Forms `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`), `ui-input` (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`, `ui-label`, `ui-help` (+`--error`). Drawer `ui-drawer__form`, `ui-drawer__body`, `ui-drawer__foot`. Bits `ui-kbd`, `ui-note`, `ui-menu` (+`__label`, `__item`, `__item--active`, `__item--danger`, `__sep`), `ui-btn ui-btn--icon` for an icon-only button. Classes rendered by components (`ui-drawer__panel`, `ui-search`, `ui-page-head*`, `ui-field`, `ui-empty*`, `ui-alert*`, `ui-tag*`, `ui-kpi__*`, `ui-checks*`, `ui-avatar*`) are not written by hand.
+Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `ui-tag-cloud`, `ui-section-head` (h2 plus actions inside a view), `ui-toolbar` (+`__spacer`). Surfaces `ui-card` (+`__head`, `__title`, `__body`). Data `ui-table` (+`ui-table-wrap`, `ui-table__empty`, `ui-table__state` for a dot plus label, `.num`), `ui-cell` (+`ui-cell__muted`), `ui-mono`, `ui-code`, `ui-dot` (+`--muted`). Row action classes are component-owned and are never written by a module. Forms `ui-form` (+`__row`, `__row--4`, `__foot`, `__actions`), `ui-input` (+`--error`), `ui-select`, `ui-textarea` (+`--error`), `ui-checkbox`, `ui-label`, `ui-help` (+`--error`). Drawer `ui-drawer__form`, `ui-drawer__body`, `ui-drawer__foot`. Bits `ui-kbd`, `ui-note`, `ui-menu` (+`__label`, `__item`, `__item--active`, `__item--danger`, `__sep`), `ui-btn ui-btn--icon` for an icon-only button. Classes rendered by components (`ui-drawer__panel`, `ui-search`, `ui-page-head*`, `ui-field`, `ui-empty*`, `ui-alert*`, `ui-tag*`, `ui-kpi__*`, `ui-checks*`, `ui-avatar*`, `ui-table__sort`, `ui-pagination` (+`__summary`, `__size`, `__pages`), `ui-datefield` (+`__reading`), `ui-daterange` (+`__row`), `ui-tabs` (+`__tab`), `ui-toasts` with `ui-toast`) are not written by hand.
 
 ## 6. Copy
 
 User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
 
+## 7. Inspect the rendered screen
+
+A screen is not finished until it has been looked at. Typecheck and tests say nothing about overflow, alignment, a duplicate label or a column that collapses.
+
+Where to look:
+
+- Repository root: `pnpm dev`, then `http://localhost:4310`. `pnpm flowdular setup quick --apply --confirm reset-local-auth` (stop `pnpm dev` first; local only) seeds two demo tenants and two logins: `admin@example.com` / `Owner!23456789` owns both tenants, `user@example.com` / `Member!2345678` is a reduced-scope member. Navigate to the entry's navigation group and open the view.
+- Sandbox: the session preview panel renders the draft module. Use it; a specialist has no shell and no dev server.
+- No browser at hand: a headless Chrome screenshot (`--headless --window-size=1440,900 --screenshot=<file>`) captures what a fresh, signed-out session sees, which covers sign-in and public pages only. A protected screen needs a real session, so drive it with whatever browser automation the host offers rather than a bare screenshot flag.
+
+Record one piece of evidence per state before handing off. A state you could not reach is stated as such, not assumed:
+
+| State     | How to reach it                                                       | What to check                                                                         |
+| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Loading   | First paint before the fetch resolves, or a throttled network profile | Column widths match the populated table, the head does not jump, a refresh keeps rows |
+| Empty     | A tenant with no records                                              | The icon renders, the sentence names the first action, `emptyFiltered` differs        |
+| Error     | Make the request fail (sign out in a second tab, or drop the scope)   | `Alert` under the header, no blank screen, no raw stack or SQL in the message         |
+| Populated | Several real records, including the longest realistic value           | No horizontal page scroll, identifiers in `ui-mono`, numbers tabular, actions aligned |
+| Denied    | Sign in as `user@example.com`                                         | The manage action is absent, navigation is hidden, a forced request still returns 403 |
+
+Check the drawer form in the same pass: one label per field, fields top-aligned, the footer constraint visible, the submit button disabled while busy.
+
 ## Pitfalls
 
 - `Kpi value={items.length}` does not typecheck; use `String(items.length)`.

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

@@ -6,6 +6,7 @@ Flowdular is an agentic foundation framework. The platform under `packages/`, `m
 
 | Path                                                         | Consumer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `platform-capabilities.md`                                   | The closed capability card: what the platform provides and what it does not. `spec-interview` and both module skills read it instead of scanning `modules/` and `packages/`. `pnpm capabilities:check` (`scripts/platform-capabilities.mjs`, run by `pnpm verify`) fails when its UI export, navigation group or workspace slot lists drift from the code.                                                                                                                                                                                              |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -13,7 +14,7 @@ Flowdular is an agentic foundation framework. The platform under `packages/`, `m
 | `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`.                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `policies/capabilities.yaml`, `policies/model-routing.yaml`  | Existence-checked by `pnpm flowdular doctor`. The real policy is code: `packages/cli/src/capabilities.ts`, `modules/*/src/cli/commands.json`, `packages/cli/src/runner.ts`, `packages/sandbox/src/server/planning.ts`.                                                                                                                                                                                                                                                                                                                                  |
-| `policies/task-budgets.yaml`, `policies/path-ownership.yaml` | Review guidance only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `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`.

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

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

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

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

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

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

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

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