@flowdular/sdk 0.1.0

package/.ai/skills/auth-security-review/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: auth-security-review
+description: >-
+  Review a module or platform change for authorization, tenancy, CSRF, input
+  bounds, secrets, and destructive CLI use, with the exact checks and tests the
+  platform relies on.
+roles:
+  - reviewer
+  - backend-engineer
+  - module-executor
+when: Any endpoint, scope, token, credential, or CLI capability is added or changed, or a review asks whether a change is safe.
+---
+
+# Authentication and security review
+
+## 1. Threat surface of a module endpoint
+
+Check every route in `src/api/endpoints.ts` against `.ai/references/catalog/src/api/endpoints.ts`:
+
+1. `defineEndpoint` (`packages/server/src/endpoint.ts`) with `access: { kind: 'permission', permission }` and `resolveIdentity: endpointIdentityFromContext`. `access: { kind: 'public' }` is allowed only with a written reason (health, sign-in). A raw `new ServerRoute` from `@octanejs/app-core` bypasses all of this; outside `modules/auth` and `packages/server` it is a finding.
+2. Non-GET handlers call `sessionMutationDenial(octane, auth)` before any work. Order inside it (`modules/auth/src/server/session-security.ts`): API token principal (403 `TOKEN_MUTATION_DENIED`), `assertSameOrigin` (`sec-fetch-site`, then `origin`, then `referer`; 403 `CROSS_ORIGIN_REQUEST` or `ORIGIN_REQUIRED`), session cookie (401), `x-csrf-token` compared with `timingSafeEqual` (403 `CSRF_REJECTED`).
+3. Body through `readJsonObject` (415 without `application/json`, 413 above 16 KB) and `requiredString`, `optionalString`, `requiredInteger` with `min` and `max`. A handler that calls `request.json()` itself has no size limit.
+4. Tenant id only from `principalFromContext(octane)!.tenantId`. A `tenantId` read from the body, query or headers is a blocker (`.ai/examples/bad/tenant-from-body`).
+5. Repository: every query on a tenant-owned table has `WHERE tenant_id = ?`; parameters are bound, never interpolated; unique constraints start with `tenant_id`.
+6. Errors return `{ error: { code, message } }` with stable codes and safe messages; no stack, path, or SQL text reaches the client.
+
+## 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.
+
+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?
+
+### Unified audit read surface
+
+Three tenant-scoped trails are readable over HTTP, each a GET behind a read scope with the tenant taken from the principal: `GET /api/auth/audit` (`auth.audit.read`), `GET /api/agent-audit` (`agents.runs.read`), and `GET /api/sandbox/audit` (`sandbox.sessions.read`). They are surfaced together in `auth.core`'s Administration > Audit view, whose source selector is derived from `ModuleClientContext.scopes` so a reader is never offered a source it cannot read. The agent and sandbox trails are hash-chained; `GET /api/agent-audit/verify` and `GET /api/sandbox/audit/verify` (same read scopes) recompute the chain and return `{ verified, brokenAt }` through the same repository walk the `flowdular <module> audit-verify` CLI uses, so CLI and endpoint cannot drift. Reviewing an audit change: the read scope guards both list and verify, the list cursor is `(occurred_at, sequence)` and the sequence is trusted from storage (never from input), and no chain field or metadata may carry a credential, token, or request body.
+
+## 3. API tokens
+
+`Authorization: Bearer clat_...` (`API_TOKEN_PREFIX` in `auth-service.ts`), 256-bit random, stored as SHA-256, scopes intersected with the live membership, max lifetime one year, resolved only when no session cookie is present (`modules/auth/src/middleware/authentication.ts`). Tokens are refused for session-guarded mutations. A module endpoint that should be callable by a token (read for the sandbox bridge) must be a GET behind a permission.
+
+## 4. Secrets
+
+Passwords: scrypt `N=2^17, r=8, p=1`, 64-byte key (`modules/auth/src/services/password.ts`). Sessions: 32 random bytes, CSRF 24 bytes, SHA-256 at rest. Cookies: `HttpOnly; SameSite=Strict; Path=/`, `Secure` and the `__Host-` prefix when `FD_AUTH_SECURE_COOKIE` is true (default in production), 12 hour TTL (`modules/auth/src/server/runtime.ts`). Provider credentials: AES-256-GCM in `modules/agents/src/services/credential-vault.ts`, key from `FD_AGENT_CREDENTIAL_KEY` (required in production). `redactSecrets` in `packages/ai-provider/src/errors.ts` scrubs provider messages; there is no general redacting logger, and a raw driver error can carry the failing statement, so a handler maps it to a Flowdular error code and logs that instead of `console.error(..., error)` with the driver message. A module never logs a principal, a token, or a request body.
+
+## 5. Greps to run
+
+```bash
+grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth          # raw routes outside auth
+grep -rn "tenantId" modules/*/src/api | grep -v principalFromContext      # tenant from input
+grep -rn "request.json()" modules/*/src                                   # unbounded body reads
+grep -rn "console\.\(log\|error\)" modules/*/src                          # logging of principals or bodies
+grep -rn "kind: 'public'" modules/*/src                                   # public endpoints need a reason
+grep -rn "\${" modules/*/src/services/database-repository.ts              # interpolation into SQL
+```
+
+## 6. Destructive and external CLI capabilities
+
+`packages/cli/src/runner.ts`: `external` risk and non-local `destructive` capabilities fail with `APPROVAL_VERIFIER_REQUIRED`; `localOnly` runs only when `FD_ENV` or `NODE_ENV` is `development` or `test` (unset counts as development); `requiresApprovedSpec` needs `--spec` pointing at an approved spec; `destructive` with `--apply` needs `--confirm <token>` equal to the descriptor's `confirmation`. `setup quick` is `auth greenfield` (`--apply --confirm reset-local-auth`) and resets `.flowdular/data/auth.db`. Never point it at `FD_AUTH_DATABASE` of a deployment.
+
+## 7. Required tests per endpoint
+
+Recipe in `modules/auth/tests/endpoints.test.ts`: build the runtime with a `DatabaseAuthRepository` on a `createPgliteTestProvider()` lease, call `route.handler(createContext(new Request(...), {}))`.
+
+- 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).
+- Mutation without `x-csrf-token` returns 403 `CSRF_REJECTED`; without `origin` returns 403.
+- Each validation bound returns 400 with its code.
+
+## 7b. Compliance table and report
+
+Fill one row per endpoint before writing findings; a blank cell is a finding.
+
+| Endpoint                        | Permission                   | Identity                      | Tenant source          | Mutation guard                | Body bounds                               | Tests               |
+| ------------------------------- | ---------------------------- | ----------------------------- | ---------------------- | ----------------------------- | ----------------------------------------- | ------------------- |
+| `POST /api/inventory/locations` | `inventory.locations.manage` | `endpointIdentityFromContext` | `principalFromContext` | `sessionMutationDenial` first | `readJsonObject`, `requiredString` max 32 | 401, 403, CSRF, 400 |
+
+Report each finding as: severity (`blocker`, `should-fix`, `taste`), claim, `file:line`, the concrete scenario (who sends what, what happens), the rule (`AGENTS.md` number), the fix. Finish with a verdict: `approved` or `changes-required`. Do not fix code in the review run.
+
+```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.
+```
+
+## 8. Known platform gaps to keep in mind (not module defects)
+
+The sandbox server (`packages/sandbox/src/server/routes.ts`) has routes without authorization or CSRF, and the session id parameter is joined into paths unvalidated; the sign-in limiter is keyed on email plus `user-agent` (`modules/auth/src/server/endpoints.ts`, `limiterKey`); `users.members.manage` can create an owner because `role` comes from the body (`modules/users/src/api/endpoints.ts`); `emailConfirmation` does not gate sign-in; there are no security headers or a global body limit. A module review does not fix these; name them when a change touches the same area.
+
+## Pitfalls
+
+- `principalFromContext(octane)!` before `resolveIdentity` ran is a null dereference on a public route.
+- A GET that mutates skips `sessionMutationDenial`; mutations are POST or PUT.
+- A `secret: true` setting is write-only through `/api/settings/update`; a module never returns a setting value to the client unless its declaration says `client: true`.
+- Matching a unique violation by message text is the accepted pattern, but the string must include the table name (`<table>.tenant_id`).
+- An `Alert` with the raw server message is fine because the server already returns safe messages; never include the response body of a 500 verbatim.

package/.ai/skills/auto-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: auto-review
+description: >-
+  Review a finished core or module change against its requirements, public
+  contracts and executable regression evidence before delivery. Report defects
+  with failure scenarios; never approve an unverified change.
+roles:
+  - module-executor
+  - reviewer
+  - backend-engineer
+  - frontend-engineer
+  - ux-designer
+  - agentic-engineer
+when: Implementation is complete, before final handoff, sandbox eject, or a core PR.
+---
+
+# Auto-review
+
+This is a separate review phase after implementation. Read the owning code, the
+complete change including additions and deletions, its callers, requirements and
+tests. Preserve unrelated edits. Do not load other skills during this phase.
+Do not modify production code, tests, specifications or generated files. Findings
+return to the implementation phase; every later edit requires another review.
+Review is a model assessment, not a guarantee of correctness or spec approval.
+
+## Required checks
+
+For every check, cite the relevant files and concrete evidence. Use a reasoned
+not-applicable explanation only after inspecting the change. Generic "looks good"
+or "tests pass" is not evidence. A missing check blocks a passing verdict.
+
+1. **Correctness:** map each requested behavior and acceptance scenario to code
+   and an observable test. Trace invalid inputs, empty results, boundaries and
+   failure paths. Check existing behavior outside the requested change. Find
+   sibling call sites and copies that need the same fix.
+2. **Security:** trusted principal and tenant identity, explicit permissions,
+   denial tests, CSRF for mutations, input bounds, parameterized SQL, tenant
+   predicates and forced RLS, secret redaction and cross-module authority.
+   Test unauthenticated, denied and cross-tenant requests where applicable.
+3. **Compatibility:** exports, signatures, optional fields, errors, dependency
+   direction and every consumer affected by the contract. Check manifests,
+   declared dependencies, spec/package versions and CLI-generated composition.
+   Applied migrations must remain byte-identical; check new migrations, fresh
+   apply, adoption and tenant isolation through the actual database provider.
+4. **Lifecycle:** concurrency, cancellation, cleanup, bounded memory, resource
+   ownership, durable background work, retries, idempotency and recovery. State
+   the cost of changed loops or queries; investigate new unbounded work.
+5. **Tests:** assertions must observe behavior, not duplicate implementation.
+   A regression test must fail with the defect restored and pass with the fix.
+   Cover relevant negative and failure cases. No skipped assertions, empty
+   suites, mocked-away ownership boundary or weakened existing checks. Record
+   actual commands, results and failures, and distinguish tests not yet run.
+6. **UI:** when rendered behavior changes, inspect the rendered result, keyboard
+   interaction, shared components, translated copy and loading/empty/error/
+   populated/denied states. Record the inspected scenario; otherwise explain
+   why the diff has no rendered effect.
+
+## Core and host module changes
+
+Review only the requested change while accounting for existing workspace edits.
+Run scoped checks first, then `pnpm verify`. For a core change also run `pnpm build`
+(the CLI smoke and platform build exercise integration). Do not waive a failing,
+missing or skipped required check; list unrelated existing failures separately
+and leave verification incomplete. Re-read the final diff after generated output
+or formatting changes. Save a concise report with files reviewed, scenario-to-test
+mapping, commands/results, unresolved findings and remaining risks. Finish with
+pass only when all applicable checks have evidence and no actionable defect
+remains. Root instructions require this phase before declaring the work complete;
+there is no host-side runtime enforcement of a model's review verdict.
+
+## Sandbox
+
+The orchestrator routes a failed `auto-review` gate to this skill. The turn is
+read-only and retains the current role and active module. Inspect the whole module
+change relative to `reference/auto-review-base/`, including deleted files, not
+just your last edit. Preserve the intended next-specialist handoff from the
+implementation turn after a passing review. Use the provided
+reference code and recorded gate output. The orchestrator runs schema, dependency,
+typecheck, tests and format gates; never claim you ran a command it ran later.
+Report verification still pending when needed. Deterministic checks are independent
+of your assessment and must all pass before eject.
+
+Return exactly one fenced `auto-review` JSON object in the closing response,
+followed by the normal handoff line. Each check is a string of 20 to 4000 characters
+with actual evidence or a specific not-applicable explanation. Keep the response
+under 32000 characters. The structure is:
+
+```auto-review
+{
+  "verdict": "fail",
+  "checks": {
+    "correctness": "Files, acceptance scenarios and observed behavior.",
+    "security": "Relevant authorization and tenant denial evidence.",
+    "compatibility": "Public consumers and migration or manifest evidence.",
+    "lifecycle": "Resource ownership and failure-path evidence.",
+    "tests": "Test paths, assertions, actual gate results or pending checks.",
+    "ui": "Rendered inspection evidence or a specific reason not applicable."
+  },
+  "findings": ["Severity; file:line; input/state; wrong outcome; required fix."]
+}
+```
+
+Use `pass` and an empty findings array only when no actionable defect remains.
+Do not copy the example evidence. Include every actionable finding, not taste
+preferences. A failing review returns to implementation; never repair files in
+this turn. A passing record is written by the orchestrator outside the workspace
+and bound to all module file bytes. Subsequent edits invalidate it. Old sessions
+without a current report must run auto-review before eject. Eject rejects skipped
+and missing gates as well as failures; a test suite with no tests fails.
+
+Owning code: `packages/sandbox/src/server/auto-review.ts`, `turns.ts`, `gates.ts`,
+`delivery/steps.ts`, and `packages/coding-agent/src/roles/skills.ts`.

package/.ai/skills/bug-hunt/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: bug-hunt
+description: >-
+  Reproduce a defect with the gate runner, map the symptom to the owning layer,
+  fix it there with a failing test first, then hunt its siblings.
+roles:
+  - backend-engineer
+  - frontend-engineer
+  - module-executor
+when: A report, failing gate, wrong status code, blank screen, or unexpected 4xx/5xx needs a root cause rather than a patch.
+---
+
+# Hunt a bug
+
+## 1. Reproduce with the tools the gates use
+
+- Server: a vitest case in `tests/module.test.ts` that builds the route and calls it directly. Recipe: `const routes = createXRoutes(auth, runtime); const route = routes.find(...)`, then `await route.handler(createContext(new Request('https://erp.example/api/x', { method: 'POST', headers: { 'content-type': 'application/json', origin: 'https://erp.example', cookie, 'x-csrf-token': csrf }, body }), {}))`. `createContext` comes from `@octanejs/app-core`; a full example with sign-up, cookie and CSRF is `modules/auth/tests/endpoints.test.ts`.
+- Service or repository: `new XService((await createXTestDatabase()).repository)` from the module's `tests/support/database.ts` and await the method.
+- Client logic: move the pure part into a `.ts` helper and test it; `.tsrx` files are outside `tests/**/*.ts`.
+- Run: `pnpm --filter @flowdular/module-<dir> test` (repository root) or ask for the `tests` gate (sandbox). Keep the failing test; it becomes the regression test.
+
+## 2. Symptom to layer
+
+| Symptom                                                                                                    | Where it is decided                                                                                                                                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 401 `UNAUTHENTICATED`                                                                                      | `packages/server/src/endpoint.ts` (no identity from `resolveIdentity`) or `modules/auth/src/server/session-security.ts` (no session cookie on a mutation)                                                                                                                                       |
+| 403 `FORBIDDEN`                                                                                            | `endpoint.ts`: the permission string is not in the principal's scopes. Check `src/acl/permissions.ts` against the spec and whether `auth sync-scopes` ran                                                                                                                                       |
+| 403 `TOKEN_MUTATION_DENIED`, `CSRF_REJECTED`, `ORIGIN_REJECTED`, `CROSS_ORIGIN_REQUEST`, `ORIGIN_REQUIRED` | `sessionMutationDenial` order: API token, `assertSameOrigin` (`modules/auth/src/api/origin.ts`), cookie session, `x-csrf-token`                                                                                                                                                                 |
+| 415 `CONTENT_TYPE_REQUIRED`, 413 `PAYLOAD_TOO_LARGE`, 400 `INVALID_JSON` or `INVALID_INPUT`                | `packages/server/src/http.ts` `readJsonObject` (16 KB cap) and `requiredString`, `requiredInteger`, `optionalString`                                                                                                                                                                            |
+| 409 on create                                                                                              | the repository maps the unique violation by SQLSTATE `23505` plus the constraint name (`.ai/references/catalog/src/services/database-repository.ts`, `create`); match the code, never the driver message text, and remember that renaming the unique index breaks the constraint check silently |
+| 500 `INTERNAL_ERROR`                                                                                       | the handler threw; `endpoint.ts` logs `[requestId] endpoint <id> failed` with the error                                                                                                                                                                                                         |
+| 404 on a module route                                                                                      | route not mounted: `module.json` `platform.server`, `./platform` export, `src/platform.ts`, `flowdular.json` `modules.enabled`, `platform/src/generated/modules.server.ts` regenerated by `pnpm flowdular module sync --apply`                                                                  |
+| Blank shell or boot error                                                                                  | `packages/client/src/contributions.ts` throws on a duplicate contribution id, a navigation entry whose `viewId` has no view, or an unknown widget slot                                                                                                                                          |
+| Navigation entry missing                                                                                   | scope not granted (`navigationForIdentity` in `packages/client/src/shell/navigation.ts`), or `Development` group for a non-owner                                                                                                                                                                |
+| 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                             |
+
+## 2b. Reproduction snippets
+
+Service level, no HTTP:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { CatalogService } from '../src/services/catalog-service.ts';
+import { createCatalogTestDatabase } from './support/database.ts';
+
+it('rejects a sku above 64 characters with a stable code', async () => {
+	const service = new CatalogService(
+		(await createCatalogTestDatabase()).repository,
+	);
+	await expect(
+		service.create('tenant-a', {
+			sku: 'x'.repeat(70),
+			name: 'Too long',
+			kind: 'product',
+			unit: 'each',
+			basePriceMinor: 100,
+			currency: 'EUR',
+		}),
+	).rejects.toThrowError(/between 1 and 64/);
+});
+```
+
+HTTP level, the denial path only needs the route and a bare request:
+
+```ts
+import { createContext } from '@octanejs/app-core';
+
+const [list] = createCatalogRoutes(auth, runtime);
+const response = await list.handler(
+	createContext(new Request('https://erp.example/api/catalog/items'), {}),
+);
+expect(response.status).toBe(401);
+expect(await response.json()).toMatchObject({
+	error: { code: 'UNAUTHENTICATED' },
+});
+```
+
+For a 403 or a mutation you need a principal; the recipe with sign-up, cookie and CSRF is in `test-hardening`.
+
+## 2c. Reading gate output
+
+- `typecheck`: the first error is usually the cause; later ones cascade. `TS2307 Cannot find module` inside a module means an undeclared package or a missing `.ts` extension.
+- `tests`: vitest prints the failing assertion with `Expected` and `Received`; a driver error naming a column type is a value that does not fit the column (`Number.isSafeInteger` at the service boundary), and a comparison that fails on a count or a flag is usually a `BIGINT` returned as a string that skipped the repository's `integer()` helper.
+- `format`: run `pnpm format` (or the sandbox format action); never hand-format.
+- `dependencies`: the message lists the undeclared packages; add them to `package.json` dependencies (the session installs what `package.json` declares and nothing else). A failed `pnpm install` after a `package.json` change is reported under the same gate with the installer output.
+- `module-schema`: `SCHEMA_ADDITIONALPROPERTIES` names a key `module.json` does not know; `MODULE_ENABLED_MISSING` means `flowdular.json` names a module without a manifest; `PLATFORM_SERVER_ENTRY_MISSING`, `PLATFORM_EXPORT_MISSING`, `PLATFORM_CLIENT_ENTRY_MISSING`, `PLATFORM_CLIENT_EXPORT_MISSING` name a composition entry the flags promise but the module lacks; `TRANSLATION_KEYS_MISMATCH` and `TRANSLATION_FILE_MISSING` are locale drift; `SPEC_VERSION_DRIFT` and `LOCALE_NOT_IN_PROJECT` are warnings.
+
+## 3. Fix at the owning layer
+
+Validation belongs to the HTTP helpers and the service, not to the client. Tenant scoping belongs to the repository query and the endpoint's `principalFromContext`. Presentation belongs to the view. A fix that adds a second check in a different layer hides the defect; move it instead.
+
+Smallest change: write the failing test, make it pass, run `pnpm --filter @flowdular/module-<dir> typecheck` and `test`, and `pnpm format` when the format gate complains (the sandbox has a format action for that).
+
+## 4. Hunt siblings
+
+The bundled modules share one shape. After fixing `modules/<dir>`, grep the same pattern in `.ai/references/catalog`, `modules/users`, `modules/profile`, `modules/agents`, `modules/sandbox`: `grep -rn '<pattern>' modules/*/src`. Report siblings you did not fix.
+
+## 5. Reporting
+
+State the root cause (input and state to wrong outcome), the file and line, the regression test name, and the siblings. Do not claim a fix without the test passing where it failed before.
+
+## Pitfalls
+
+- The sandbox `tests` gate passes with zero tests; a green gate is not evidence.
+- A test never points at a running deployment; it takes its database from `createPgliteTestProvider()` through the module's `tests/support/database.ts`, which runs PostgreSQL inside the test process.
+- `principalFromContext(octane)!` is only safe after `resolveIdentity`; a public endpoint has no principal.
+- Do not add `try/catch` that swallows the error to make a 500 disappear; map it to a stable code or let it surface.

package/.ai/skills/business-agent-design/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: business-agent-design
+description: >-
+  Ship a module-owned business agent with defineAgent, an exact tool ceiling,
+  tenant provider binding, retained revisions, and tests. Use for business
+  automation delivered by a module, not for sandbox coding specialists.
+roles:
+  - agentic-engineer
+  - backend-engineer
+  - module-executor
+when: A module should provide a ready business agent that tenants can configure and run.
+---
+
+# Design a module-owned business agent
+
+`defineAgent()` describes a business agent shipped by a module. It is the same
+kind of business agent that appears in `agents.core`, but its behavior is owned
+by module source. It is not a sandbox specialist, coding role, `.ai` skill, or
+permission grant. Read `docs/adr/0007-module-owned-agents.md` and the approved
+module spec before editing.
+
+If a required tool is missing, pause this phase and hand it off as a separate
+`agent-tool-design` task. A business agent can use only registered tools.
+
+## Ownership split
+
+The module owns:
+
+- the stable module id and agent key;
+- name, description, instructions, and positive definition revision;
+- the maximum exact tool allowlist;
+- maximum steps, timeout, temperature, and output-token limits.
+
+The tenant owns a separate binding in `agents.core`:
+
+- provider connection and model;
+- active or paused state;
+- an enabled-tool subset that can narrow the module allowlist;
+- optimistic binding revision and the resulting executable revision.
+
+Never put provider ids, model ids, credentials, tenant ids, or tenant-specific
+instructions in module source. The Agents UI presents module behavior as
+read-only and lets an authorized tenant manager configure only the binding.
+
+## Define and register
+
+Declare `agents.core` in both `spec/module.yaml` and `module.json` dependencies,
+and add `"@flowdular/sdk/modules/agents": "workspace:*"` to `package.json`. Keep the
+import server-only.
+
+```ts
+// src/agent/agents.ts
+import { defineAgent } from '@flowdular/sdk/modules/agents/server';
+
+export const catalogCurator = defineAgent({
+	moduleId: 'catalog.core',
+	key: 'catalog-curator',
+	definitionRevision: 1,
+	name: 'Catalog curator',
+	description: 'Reviews and normalizes catalog records.',
+	instructions:
+		'Review the requested catalog records. Use only the tools available to you.',
+	allowedTools: ['catalog.item.create', 'catalog.item.list'],
+	limits: {
+		maxSteps: 8,
+		timeoutMs: 120_000,
+		temperature: 0.2,
+		maxOutputTokens: 4_096,
+	},
+});
+
+export const catalogBusinessAgents = [catalogCurator] as const;
+```
+
+```ts
+// src/platform.ts, during createServerComposition
+context.agentDefinitions.register(catalogBusinessAgents);
+```
+
+Registration happens during composition. The platform seals
+`agentDefinitions` before any module `start()` hook. A malformed definition,
+duplicate id, wildcard tool, registration after sealing, code downgrade, or
+same-revision content drift fails boot. Do not catch and hide these errors.
+
+`defineAgent()` derives the opaque id
+`module-agent:<moduleId>:<key>`, validates the fields, sorts the exact tool ids,
+and freezes the result. Callers do not construct or parse the derived id.
+
+## Authority is an intersection
+
+For a module-owned agent, the tools visible to a run are exactly:
+
+```text
+code allowedTools
+  intersect tenant binding enabledTools
+  intersect invocation toolGrants
+  intersect registered tools allowed by the actor's saved ceiling
+  intersect registered tools allowed by the actor's live permissions
+```
+
+Every id is exact. An omitted grant means no tools. `*`, prefixes, and implicit
+all-tools behavior are invalid. Every tool independently declares its
+`requiredPermissions`; instructions and skills never grant authority. A scope
+revoked after enqueue is rechecked before the tool body runs. The model never
+receives `PlatformCapabilityRegistry` or direct service, repository, database,
+shell, filesystem, or credential access.
+
+The module allowlist is a permanent ceiling for that definition revision. The
+tenant may reduce it, and each caller may reduce it again. A caller cannot
+broaden it. Keep the list to the smallest surface needed for the stated job.
+
+Mutating tools also follow the durable idempotency contract in
+`agent-tool-design`. Do not add a write tool to a business agent until the tool
+has its target-side ledger, transaction, replay test, and
+`idempotencyProtection: 'target-ledger'` declaration.
+
+## Revisions and workflows
+
+Increase `definitionRevision` whenever any executable module-owned content
+changes: instructions, display copy, allowed tools, or limits. Never reuse a
+revision with different content and never decrement it.
+
+Binding a provider or model, changing enabled tools, or reconciling a higher
+module definition creates a new immutable tenant executable revision. Runs and
+published workflows pin that executable revision, not the code definition or
+mutable binding revision. Old retained revisions and audit evidence survive an
+upgrade or module removal. A removed module-owned agent becomes unavailable for
+new work.
+
+An unconfigured module agent remains visible but cannot run or be published in
+a workflow. Do not choose a provider or model automatically to make setup look
+complete.
+
+## Spec and files
+
+The approved spec states:
+
+- the business outcome and refusal conditions;
+- each exact tool and required permission;
+- that tenant binding cannot broaden the module ceiling;
+- unavailable, unconfigured, revision, and module-removal behavior where
+  relevant.
+
+Typical files are:
+
+- `src/agent/agents.ts` for definitions;
+- `src/agent/tools.ts` for module tools;
+- `src/platform.ts` for both registry calls;
+- `tests/business-agents.test.ts` and `tests/agent-tools.test.ts`;
+- `spec/module.yaml`, `module.json`, and `package.json` for dependencies and
+  the coordinated version bump.
+
+## Tests
+
+The business module proves:
+
+1. The definition has the expected derived id, ownership, revision, limits,
+   and exact sorted tool ceiling, and is frozen.
+2. Every allowed tool is registered by the module or a declared dependency.
+
+The shared `agents.core` integration suite proves:
+
+1. A tenant binding can reduce tools but cannot add one outside the code
+   ceiling.
+2. A run without an invocation grant or required live scope never calls the
+   tool body and records a denial.
+3. Two tenants can bind different providers, models, and tool subsets without
+   seeing each other's binding or runs.
+4. A higher definition revision retains the old executable revision; a
+   downgrade and same-revision drift refuse startup.
+5. Module absence blocks new runs while retained run and workflow evidence
+   remains readable.
+
+Use the module's isolated test provider for persistence tests. The end-to-end access intersection
+belongs in `modules/agents/tests`, while a business module proves its own
+definition and tool behavior locally. Do not edit `agents.core` merely to
+duplicate its platform contract tests. Run the module tests, typecheck, spec
+and module validation, then `pnpm verify` before delivery.
+
+## Refuse
+
+- Treating a sandbox coding specialist as a business agent definition.
+- Letting a tenant edit module-owned instructions or the code tool ceiling.
+- Wildcard tools, tenant ids in model input, or authority derived from prompts.
+- Code-pinned provider connections, models, credentials, or secrets.
+- Registration outside `createServerComposition` or after registry sealing.
+- A write tool without target-side durable idempotency.
+- Reusing a definition revision after changing executable content.

package/.ai/skills/cli-extension/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: cli-extension
+description: >-
+  Add a module-owned CLI command through commands.json and defineCliExtension,
+  with the namespace, risk, approval, and dry-run rules the runner enforces.
+roles:
+  - backend-engineer
+  - module-executor
+  - reviewer
+when: A module needs an operator command (status, export, grant, verify) reachable as pnpm flowdular <namespace> <action>.
+---
+
+# Add a module CLI command
+
+Examples to copy: `modules/agents/src/cli/{commands.json,index.ts}` (read plus a `localOnly` verifier) and `modules/auth/src/cli/{commands.json,index.ts}` (`process` with dry run, `destructive` with confirmation). Small template: `.ai/examples/customer-cli-extension`.
+
+## 1. Declare the capability
+
+`module.json`: add `"cli"` to `capabilities` and
+
+```json
+"cli": { "catalog": "src/cli/commands.json", "entry": "src/cli/index.ts" }
+```
+
+`packages/contracts/schemas/module.schema.json` requires the `cli` block when the capability is present and the capability when the block is present. The spec `capabilities` list gets `cli` too.
+
+## 2. Catalog: `src/cli/commands.json`
+
+```json
+{
+	"protocolVersion": 1,
+	"moduleId": "inventory.core",
+	"commands": [
+		{
+			"path": ["inventory", "export"],
+			"capability": {
+				"id": "inventory.export",
+				"version": 1,
+				"summary": "Export tenant-scoped stock locations to a workspace path.",
+				"risk": "workspace-write",
+				"requiresApprovedSpec": true,
+				"supportsDryRun": true
+			}
+		}
+	]
+}
+```
+
+Rules enforced by `packages/cli/src/extensions.ts` (`validateCliCatalog`, `loadCliExtensions`):
+
+- `moduleId` equals `module.json` `id`; the module must be enabled in `flowdular.json`, otherwise its commands do not load.
+- `path` has at least two segments matching `^[a-z][a-z0-9-]*$`; the first segment equals the first segment of the module id (`inventory` for `inventory.core`) and is not a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `setup`).
+- `capability.id` starts with `<namespace>.`, is unique across all enabled modules, `version` is an integer >= 1, `summary` 1 to 240 characters.
+- `risk` is one of `read`, `workspace-write`, `process`, `external`, `destructive`. A `destructive` capability with `localOnly: true` must also set `confirmation` (`^[a-z][a-z0-9-]{2,63}$`) and `supportsDryRun: true` (schema `allOf` in `cli-extension.schema.json`).
+
+## 3. Implementation: `src/cli/index.ts`
+
+```ts
+import { defineCliExtension } from '@flowdular/sdk/cli-protocol';
+
+export const cliExtension = defineCliExtension({
+	protocolVersion: 1,
+	moduleId: 'inventory.core',
+	commands: [
+		{
+			path: ['inventory', 'export'],
+			capability: {
+				id: 'inventory.export',
+				version: 1,
+				summary: 'Export tenant-scoped stock locations to a workspace path.',
+				risk: 'workspace-write' as const,
+				requiresApprovedSpec: true,
+				supportsDryRun: true,
+			},
+			execute: async (context) => ({
+				data: {
+					applied: context.apply,
+					target: context.arguments[0] ?? 'json',
+				},
+				evidence: ['modules/inventory/spec/module.yaml'],
+				warnings: context.apply ? [] : ['Dry run only.'],
+			}),
+		},
+	],
+});
+
+export default cliExtension;
+```
+
+`execute(context: { workspaceRoot, moduleRoot, apply, flags: ReadonlyMap<string, string | boolean>, arguments: readonly string[] })` returns `{ data, evidence?, warnings? }` (`packages/cli-protocol/src/index.ts`). The loader (`loadCliCommand`) imports the entry only when the command runs, accepts a `default` or `cliExtension` export, and refuses when `path` or the whole `capability` object differs from the catalog (`commandKey` compares the JSON). Keep both files metadata-identical, down to the summary text. Declare `@flowdular/sdk/cli-protocol` in `package.json`. Read module data through the module's own runtime (`xRuntimeOptionsFromEnvironment(process.env, context.workspaceRoot)` then the service), as `modules/agents/src/cli/index.ts` does; never through another module's database.
+
+## 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.
+- `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`).
+- Non-read without `supportsDryRun` and without `--apply`: `EXPLICIT_APPLY_REQUIRED`. Non-read with dry run support and no `--apply` runs with `apply: false` and appends the warning `Dry run only. No writes were authorized.`
+- Invocation: `pnpm flowdular inventory export --apply` or `pnpm flowdular capability run inventory.export --apply`; `arguments` are the positionals after the path (or after `capability run <id>`); flags are `--name value`, `--name=value`, or `--flag` (`packages/cli/src/arguments.ts`). `pnpm flowdular capability list` and `describe <id>` show the descriptor; `pnpm flowdular help` lists module paths.
+
+## 5. Tests
+
+`packages/cli/tests/extensions.test.ts` shows the style: call `validateCliCatalog(catalog, manifest)` with a good catalog and with a path that claims a reserved group, assert the error text. In the module, test `execute` directly with a hand-built context (`apply: false` returns the dry-run shape, `apply: true` writes inside `context.workspaceRoot` only). Then `pnpm flowdular module validate --json` and `pnpm flowdular help` (the new path appears once the module is enabled).
+
+## 6. Landing
+
+Sandbox sessions strip `cli` from other modules' manifests and do not run module commands; the CLI parts of a module are exercised after eject or at the repository root. Both paths end with `pnpm verify` and a PR; `.ai/policies/capabilities.yaml` lists module capabilities, add yours.
+
+## Pitfalls
+
+- A `summary` edited in one file only: `CLI implementation for "inventory export" does not match its catalog.`
+- Two enabled modules claiming the same `path` or capability id: `CLI command collision`.
+- `risk: 'read'` commands run without `--apply`; anything that writes must not be `read`.
+- Commands run in the developer's process with the full environment; never print secrets in `data`.