@plumbus/core 0.6.4 → 0.6.5

package/instructions/cli.md

@@ -11,7 +11,8 @@ plumbus create <project-name> [--auth jwt|auth0|clerk] [--ai openai|anthropic] [
 # Create a monorepo project (backend / frontend / libs)
 plumbus create <project-name> --monorepo [--auth jwt|auth0|clerk] [--ai openai|anthropic] [--compliance GDPR|HIPAA] [--skip-install] [--git]
 
-# Initialize AI agent wiring (copilot, cursor, or agents-md)
+# Initialize AI agent wiring (all formats by default; use --agent to narrow)
+plumbus init
 plumbus init --agent copilot
 
 # Check project health
@@ -83,8 +84,31 @@ plumbus generate
 # Run governance checks (advisory signals, not hard blocks)
 plumbus verify
 plumbus verify --json
+
+# Partner API contract validation (requires @plumbus/api)
+plumbus api validate
+plumbus api validate --fail-on-governance   # also fail on advisory apiRules
+
+# Compliance profile assessment
+plumbus certify policy soc2
+plumbus certify policy gdpr --json
+```
+
+`plumbus verify` and `plumbus api validate` are both advisory for governance by default. Use `--fail-on-governance` on `api validate` when CI should gate on advisory API rules.
+
+## Testing
+
+Consumer apps run tests through the framework — do not install vitest directly.
+
+```bash
+plumbus test
+plumbus test --watch
+plumbus test --all          # unit tests, then e2e
+plumbus e2e                 # Playwright browser suites
 ```
 
+Full command reference: `docs/cli/commands.md` in the framework repo (or browse the published docs).
+
 ## Database Management
 
 **All database operations must go through the framework. Never use manual SQL DDL queries.**
@@ -117,6 +141,10 @@ plumbus migrate push --create-db
 
 # Rollback the last applied migration
 plumbus migrate rollback
+
+# Adopt migration history when the live schema already matches (drift recovery)
+plumbus migrate reconcile
+plumbus migrate reconcile --dry-run
 ```
 
 All migration commands accept `--json` for machine-readable output.
@@ -125,7 +153,8 @@ All migration commands accept `--json` for machine-readable output.
 1. Define entities in `app/entities/` using `defineEntity()`
 2. Run `plumbus migrate generate` to produce SQL migration files in `drizzle/`
 3. Run `plumbus migrate apply` to execute pending migrations
-4. For rapid development, use `plumbus migrate push` to sync schema directly (no migration files)
+4. If schema already exists but history is missing: `plumbus migrate reconcile` (use `--dry-run` to preview)
+5. For rapid development, use `plumbus migrate push` to sync schema directly (no migration files)
 
 **Never run `drizzle-kit` manually** — the framework wraps it programmatically.
 
@@ -147,6 +176,15 @@ plumbus start --port 8080 --host 127.0.0.1
 
 Behind a load balancer set `TRUST_PROXY=true` (or a specific IP/CIDR) so Fastify trusts `X-Forwarded-*` headers. `app/server.ts` extension hooks (`onRoutesRegistered`, `resolveAiOverrides`, `onCapabilityError`, `onProcessError`, `onAICostRecorded`, `onFlowError`, `enableStrictStructuredOutputs`) are loaded automatically.
 
+## Background work
+
+```bash
+plumbus worker start              # split deployments
+plumbus events status             # outbox / queue health
+plumbus flow dead-letter list     # failed flow executions
+plumbus seed                      # populate initial data
+```
+
 ## Translations
 
 ```bash
@@ -205,6 +243,34 @@ export default async function (ctx: { sql: any; args: string[] }) {
 }
 ```
 
+## RAG ingestion
+
+```bash
+plumbus rag ingest <path>              # Ingest a document into the RAG pipeline
+plumbus rag ingest ./docs/guide.md --source support-docs --tenant-id <uuid>
+```
+
+Requires AI provider credentials in config/env. See `docs/ai/ai-integration.md` for corpus retrieval from capabilities.
+
+## Framework upgrades
+
+```bash
+plumbus upgrade                         # Migrate legacy UI artifacts after @plumbus/core / @plumbus/ui bumps
+plumbus upgrade --dry-run               # Report stale artifacts without writing
+```
+
+`plumbus doctor` suggests `plumbus upgrade` when it detects stale generated frontend layout.
+
+## Agent brief sync
+
+```bash
+plumbus agent sync                      # Regenerate .plumbus/briefs/project.md from discovered contracts
+plumbus agent brief capability getUser  # One-off brief for a single resource
+plumbus agent brief entity User
+```
+
+Run `plumbus agent sync` after adding capabilities/entities so coding agents see an up-to-date project brief. `plumbus init` creates wiring files but skips refreshing an existing brief — use sync for that.
+
 ## Important Notes
 
 - **Run from project root**: All commands must be executed from the consumer project directory where `package.json` lives.

package/instructions/events.md

@@ -47,6 +47,8 @@ handler: async (ctx, input) => {
 
 Events are **not** dispatched immediately. They are written to an outbox table in the **same database transaction** as the capability's data changes. This guarantees at-least-once delivery with no data/event inconsistency.
 
+For `action` / `eventHandler` capabilities this is the default (**transactional outbox ON**). Opt out with `execution.transactionalOutbox: false`, `PLUMBUS_TRANSACTIONAL_OUTBOX=false`, or per-capability `transactional: false`. Auto-excluded: `kind: 'job'`, `effects.ai: true`, non-empty `effects.external`. See `capabilities.md` § Transactional outbox.
+
 A background dispatcher polls the outbox and publishes events to the queue system for delivery.
 
 ## Event Envelope

package/instructions/framework.md

@@ -1,6 +1,6 @@
 # Plumbus Framework
 
-Plumbus is an AI-native, contract-driven TypeScript application framework. You build applications by composing six primitives — **Capabilities**, **Entities**, **Events**, **Flows**, **Prompts**, and **Translations** — through a controlled execution context (`ctx`). Two opt-in companion packages extend the surface: `@plumbus/chat` for conversational runtimes (the `Chat` primitive lives there) and `@plumbus/mcp` for serving capabilities to AI agents.
+Plumbus is an AI-native, contract-driven TypeScript application framework. You build applications by composing six primitives — **Capabilities**, **Entities**, **Events**, **Flows**, **Prompts**, and **Translations** — through a controlled execution context (`ctx`). Optional add-on packages extend the surface when installed explicitly: `@plumbus/api` (partner HTTP API), `@plumbus/mcp` (AI agent tools), `@plumbus/chat` (+ `@plumbus/chat-ui`), `@plumbus/voice`, `@plumbus/knowledge-base`, `@plumbus/ui` (web UI generation), and `@plumbus/browser-extension`.
 
 ## Non-Negotiable Guardrails
 
@@ -39,6 +39,7 @@ Every capability handler receives `ctx` — the scoped runtime context:
 | `ctx.config` | Read-only application configuration |
 | `ctx.security` | Security service — policy evaluation and access enforcement |
 | `ctx.translations` | Localized string resolution — `ctx.translations.t("errors.notFound")` |
+| `ctx.capabilities` | Cross-capability invocation — `ctx.capabilities.invoke('domain.name', input)` |
 
 ## Consumption Surfaces
 
@@ -47,6 +48,7 @@ Capabilities can be consumed by:
 | Surface | Default | Opt-in |
 |---------|---------|--------|
 | **HTTP** (REST) | Auto-generated for every `query` / `action` / `job` capability | — |
+| **Partner API** | Off | `exposeAs: ['api']` + `@plumbus/api` + `registerApiRoutes()` in `app/server.ts` |
 | **Typed TS clients** (`@plumbus/ui`) | Generated by `plumbus ui generate` | — |
 | **MCP** (Model Context Protocol) | Off | Add `exposeAs: ['mcp']` to selected capabilities; install `@plumbus/mcp`; run `plumbus mcp serve` |
 
@@ -143,6 +145,8 @@ The optional `app/server.ts` file exports hooks that customize server behavior.
 | `onFlowError` | After a flow fails permanently (retries exhausted) | Logging flow failures to a system log table |
 | `onProcessError` | On uncaught exceptions, unhandled rejections, and Fastify-level errors | Logging process-level crashes that bypass capability/flow hooks |
 | `resolveAiOverrides` | Before each AI call | Dynamic model/provider configuration from DB |
+| `onAICostRecorded` | After each AI cost record is written | Custom cost analytics or billing hooks |
+| `enableStrictStructuredOutputs` | Server bootstrap | Global toggle for strict structured-output mode |
 
 ### Error Capture Coverage
 

package/instructions/governance.md

@@ -2,6 +2,8 @@
 
 Plumbus governance is **advisory, not blocking** — "guardrails, not gates." Rules produce warnings that inform developers; they don't prevent deployment.
 
+The same model applies to `plumbus api validate`: governance signals print to stderr but do not fail the command unless you pass `--fail-on-governance`. Hard contract findings (manifest, policy, path params, fixtures) still exit `1` without that flag.
+
 ## Governance Signals
 
 ```ts

package/instructions/patterns.md

@@ -17,7 +17,7 @@ These rules are non-negotiable. They are architecture constraints, not style pre
 | Event | domain.pastTense | `order.placed`, `refund.requested`, `user.updated` |
 | Flow | camelCase noun | `refundApproval`, `orderFulfillment` |
 | Prompt | camelCase verb+noun | `summarizeTicket`, `classifyIntent` |
-| Domain | lowercase singular | `users`, `billing`, `fulfillment` |
+| Domain | lowercase, one word (plural is common) | `users`, `billing`, `fulfillment` |
 
 ## File Structure
 

package/instructions/peer-dependencies.md

@@ -4,27 +4,39 @@ Read this file **before** editing `peerDependencies` in any `packages/*/package.
 
 ## CRITICAL rules
 
-1. **Copy literals — do not derive ranges.** Never compute semver ranges from intuition. Copy the exact string from the table below or from a canonical `package.json` (`packages/mcp/package.json`, `packages/api/package.json`).
+1. **Copy literals — do not derive ranges.** Never compute semver ranges from intuition. Copy the exact string from the table below or from a canonical `package.json` (`packages/mcp/package.json`, `packages/api/package.json`, `packages/voice/package.json`).
 2. **Never use `^0.x` caret ranges** on `@plumbus/core` peers in add-on packages. npm treats `^0.5.0` as **0.5.x only** (`>=0.5.0 <0.6.0`), not "0.5 and above."
 3. **pnpm passing locally does not prove peers are correct.** Backend Docker images install production deps with **npm** (`deployment.md` Rule 7). Wrong peers break Docker builds even when `pnpm install` succeeds.
 4. **Do not copy from CHANGELOG history.** Older releases documented incorrect ranges (`^0.5.0 <0.7.0` claimed to support 0.6.x — it does not under npm). Use this file and the canonical `package.json` files instead.
 
-## Canonical `@plumbus/core` peer strings
+## Canonical `@plumbus/core` peer strings (add-ons → core)
 
 | Package kind | `peerDependencies["@plumbus/core"]` | Canonical copy-from |
 |---|---|---|
 | Most add-ons (chat, chat-ui, knowledge-base, mcp, api, browser-extension) | `"0.5.x \|\| 0.6.x"` | `packages/mcp/package.json` |
-| Voice only (requires core 0.6+ media/cost APIs) | `"^0.6.0 <0.7.0"` | `packages/voice/package.json` |
+| Voice only (requires core 0.6+ media/cost APIs) | `"0.6.x"` | `packages/voice/package.json` |
 
 When adding a **new** publishable add-on under `packages/`, use `"0.5.x || 0.6.x"` unless the package genuinely requires core 0.6+ only (then use the voice pattern).
 
+## Other publishable peer strings
+
+| Declaring package | Peer target | Literal | Required? | Canonical copy-from |
+|---|---|---|---|---|
+| `@plumbus/core` | `@plumbus/mcp` | `"0.5.x \|\| 0.6.x"` | optional | `packages/plumbus-core/package.json` |
+| `@plumbus/core` | `@plumbus/api` | `"0.1.x"` | optional | `packages/plumbus-core/package.json` |
+| `@plumbus/chat` | `@plumbus/knowledge-base` | `"^0.1.0"` | optional | `packages/chat/package.json` |
+| `@plumbus/chat-ui` | `@plumbus/chat` | `"0.1.x"` | required | `packages/chat-ui/package.json` |
+| `@plumbus/chat-ui` | `@plumbus/core` | `"0.5.x \|\| 0.6.x"` | required | `packages/chat-ui/package.json` |
+
+**Peering direction:** add-ons declare `@plumbus/core` as a peer — consumer apps install both. `@plumbus/core` optionally peers `@plumbus/mcp` and `@plumbus/api` when those packages are present. `@plumbus/chat` optionally peers `@plumbus/knowledge-base` for registry-backed context sources — **not** the reverse. `@plumbus/knowledge-base` only peers `@plumbus/core`.
+
 ## Forbidden patterns
 
 | Range | Why it is wrong |
 |---|---|
 | `"^0.5.0 <0.7.0"` | npm resolves `^0.5.0` to 0.5.x only — **rejects `@plumbus/core@0.6.0`** |
 | `"^0.5.0 <0.6.0"` | 0.5.x only — rejects 0.6.x |
-| `"^0.6.x"` or `"^0.6.0"` alone | Too loose or wrong syntax for multi-line support; use the table literals |
+| `"^0.6.0 <0.7.0"` or `"^0.6.x"` on voice | Use the voice literal `"0.6.x"` from `packages/voice/package.json` |
 | Widening an upper bound on a caret range | e.g. changing `<0.6.0` to `<0.7.0` on `^0.5.0` does **not** add 0.6.x support |
 
 ## When `@plumbus/core` gets a new minor line (e.g. 0.7.0)
@@ -43,4 +55,4 @@ See also: `.agents/skills/bump-version/SKILL.md` (core **minor** bump checklist)
 
 - `deployment.md` Rule 7 — backend `proddeps` uses `npm install --omit=dev`
 - `.agents/skills/new-package-instructions/SKILL.md` — new package `package.json` peers
-- `packages/mcp/package.json` / `packages/api/package.json` — canonical examples
+- `packages/mcp/package.json` / `packages/api/package.json` / `packages/voice/package.json` — canonical examples

package/instructions/prompts.md

@@ -0,0 +1,84 @@
+# Prompts
+
+Prompts are structured AI interaction templates defined with `definePrompt()`. They pair typed Zod `input`/`output` schemas with prompt text and model tuning.
+
+## Prompt content
+
+The actual instructions sent to the provider live in two optional string fields:
+
+| Field | Purpose |
+|-------|---------|
+| `system` | Stable provider system instructions (role, rules, output format) |
+| `description` | User/data prompt content (the main task text) |
+
+Both support simple top-level `{{key}}` substitution from the prompt `input` object.
+
+```ts
+import { definePrompt } from "@plumbus/core";
+import { z } from "@plumbus/core/zod";
+
+export const classifyTicket = definePrompt({
+  name: "classifyTicket",
+  domain: "support",
+  system: "You classify support tickets. Return only the requested JSON fields.",
+  description: "Ticket text:\n{{ticketText}}\n\nCustomer tier: {{customerTier}}",
+  input: z.object({
+    ticketText: z.string(),
+    customerTier: z.enum(["free", "pro", "enterprise"]).optional(),
+  }),
+  output: z.object({
+    category: z.enum(["billing", "technical", "general"]),
+    priority: z.enum(["low", "medium", "high"]),
+  }),
+  model: {
+    temperature: 0.2,
+    maxTokens: 300,
+  },
+});
+```
+
+When `system` is omitted, the framework uses the prior single user-message behavior (description only).
+
+### Unsubstituted input
+
+By default, any input keys not referenced as `{{key}}` in `system`/`description` are appended to the user message. Set `appendUnsubstitutedInput: false` to disable that behavior.
+
+## Model configuration
+
+`model` is an optional `ModelConfig` object:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `provider` | string? | Routes to a named provider in multi-provider config |
+| `name` | string? | Model id (e.g. `gpt-4o-mini`) |
+| `temperature` | number? | Sampling temperature |
+| `maxTokens` | number? | Max output tokens |
+
+**Recommended convention:** omit `provider` and `name` in the prompt definition and resolve them via env (`AI_DEFAULT_PROVIDER`, `AI_DEFAULT_MODEL`, `PROMPT_{NAME}_*`) or the `resolveAiOverrides` hook in `app/server.ts`. Set only `temperature` and `maxTokens` in the prompt when you want per-prompt tuning baked into the contract.
+
+Resolution order: `resolveAiOverrides` → per-prompt env vars → prompt `model` fields → `AI_DEFAULT_MODEL` / `AI_DEFAULT_PROVIDER`.
+
+## Structured output and streaming flags
+
+| Field | Effect |
+|-------|--------|
+| `disableStrictStructuredOutputs` | Opt out of strict JSON-schema mode for this prompt |
+| `requireStrictStructuredOutputs` | Refuse to run unless a provider JSON Schema can be sent (no silent prompt-only JSON fallback) |
+| `structuredOutputTransport` | How structured output is requested from the provider |
+| `skipStreamValidationFallback` | On `streamGenerate`, do not fall back to non-streaming retry on validation failure |
+| `disableTextModeBrevityHint` | Skip the automatic brevity hint for text-mode prompts |
+
+See `docs/ai/ai-integration.md` for strict structured outputs and streaming behavior.
+
+## Invoking prompts
+
+From capabilities, use `ctx.ai`:
+
+```ts
+const result = await ctx.ai.generate({
+  prompt: "classifyTicket",
+  input: { ticketText: input.body, customerTier: "enterprise" },
+});
+```
+
+Also available: `generateWithUsage` (returns tokens + cost), `streamGenerate` (async iterator), `extract`, `classify`, `retrieve`. See `ai.md` for the full `ctx.ai` surface.

package/instructions/security.md

@@ -15,12 +15,14 @@ access: {
 ```
 
 ### Evaluation Order
-1. If `public: true` → allow
-2. Authenticate identity → populate `ctx.auth`
-3. Check `roles` — user must have at least one matching role
-4. Check `scopes` — user must have all required scopes
-5. If `tenantScoped: true` — verify `ctx.auth.tenantId` matches target data
-6. Check `serviceAccounts` — for service-to-service calls
+
+1. If no `access` policy → **deny**
+2. If `public: true` → allow
+3. Authenticate identity → populate `ctx.auth` (`userId` required for non-public)
+4. If `serviceAccounts` is set and `auth.userId` matches → **allow** (short-circuit; skips roles, scopes, and tenant checks)
+5. If `tenantScoped: true` on the capability → caller must have `tenantId` in `ctx.auth`
+6. Check `roles` — user must have at least one matching role (when `roles` is set)
+7. Check `scopes` — user must have all required scopes (when `scopes` is set)
 
 If any check fails → **403 Forbidden** with audit record.
 
@@ -47,17 +49,22 @@ If flow steps return **403** after upgrading to 0.5.x, audit `access.roles` on s
 
 ## Tenant Isolation
 
-When `tenantScoped: true`:
-- All repository queries automatically inject `WHERE tenantId = ctx.auth.tenantId`
-- Cross-tenant data access is blocked at the framework level
-- Events carry `tenantId` and are only delivered to matching consumers
+**Entity-level filtering:** when an entity declares `tenantScoped: true`, repository queries automatically inject `WHERE tenantId = ctx.auth.tenantId`. Cross-tenant data access is blocked at the framework level.
+
+**Capability-level gate:** the capability's `access.tenantScoped` flag requires the caller to carry a `tenantId` in `ctx.auth`. It does not turn on repository filtering by itself — that follows the entity definition.
+
+**Cross-tenant admin bypass:** capabilities with `access.tenantScoped: false` pass `bypassTenantScope: true` into `createDependencies()`, allowing explicitly cross-tenant admin routes while role/scope checks still apply.
+
+Events carry `tenantId` and are only delivered to matching consumers.
 
 ## Field Classification & Edit Zones
 
 Entity fields with `classification: "sensitive"` or `"highly_sensitive"`:
 - Are masked in logs and audit records
 - Trigger governance warnings if used in AI prompts
-- Can be flagged for encryption at rest
+- Can be flagged for encryption at rest (`encrypted: true` + `PLUMBUS_ENCRYPTION_KEY`)
+
+**AI prompt scanning** is separate and **opt-in**: configure `aiProviders.security` (or `AI_SECURITY_*` env) to warn/redact/block classified fields in `ctx.ai.*` inputs. Without that config, classification alone does not scan prompts. See `ai.md` § Security.
 
 ### Edit Zones
 
@@ -69,11 +76,16 @@ Entity fields with `classification: "sensitive"` or `"highly_sensitive"`:
 
 ## Authentication Adapters
 
-Plumbus uses pluggable auth adapters. The default is JWT validation. The adapter normalizes tokens into `AuthContext`:
+Plumbus uses pluggable auth adapters. The adapter normalizes tokens into `AuthContext`:
+
+- **JWT (default)** — `createJwtAdapter()` verifies HMAC-SHA256 tokens (`secret`, optional `issuer`/`audience`, `claimMapping`)
+- **OIDC** — `createOidcAdapter()` verifies RS256/ES256 via JWKS (`issuer`, `audience`, optional `jwksUri`/`jwksCacheTtl`)
+- **SAML 2.0** — `createSamlAdapter()` validates SAML assertions (`idpCertificate`, `issuer`, `audience`)
+- **SCIM 2.0 provisioning** — `createScimService()` for IdP-driven user lifecycle (`createUser`, `patchUser`, etc.)
+- **JWT signing** — `signJwt()` for first-party token issuance
+- **Custom** — implement the `AuthAdapter` interface
 
-- JWT (default) — validates JWT tokens, extracts claims
-- Auth0, Clerk, Cognito — provider-specific adapters (community)
-- Custom — implement the adapter interface
+See `docs/security/security-model.md` for full adapter examples.
 
 ## Password Utilities
 

package/instructions/testing.md

@@ -15,15 +15,19 @@ import { runCapability, simulateFlow, mockAI, createTestContext } from "@plumbus
 Execute a capability in an isolated test environment:
 
 ```ts
-const result = await runCapability(getUser, {
-  input: { userId: "usr_123" },
-  auth: { userId: "admin_1", roles: ["admin"], scopes: [], provider: "test" },
-  data: {
-    User: [{ id: "usr_123", name: "Alice", email: "alice@test.com" }],
+const result = await runCapability(
+  getUser,
+  { userId: "usr_123" },
+  {
+    auth: { userId: "admin_1", roles: ["admin"], scopes: [], provider: "test" },
+    data: {
+      User: [{ id: "usr_123", name: "Alice", email: "alice@test.com" }],
+    },
   },
-});
+);
 
-expect(result.name).toBe("Alice");
+expect(result.success).toBe(true);
+expect(result.data?.name).toBe("Alice");
 ```
 
 ### Paginated list capabilities
@@ -37,8 +41,10 @@ When testing `kind: 'query'` list endpoints that paginate via `findMany` + `coun
 ```ts
 const page1 = await runCapability(listStaff, { page: 1, limit: 2 }, { ctx });
 const page2 = await runCapability(listStaff, { page: 2, limit: 2 }, { ctx });
-expect(page1.items).not.toEqual(page2.items);
-expect(page1.total).toBeGreaterThan(page1.limit);
+expect(page1.success && page1.data).toBeTruthy();
+expect(page2.success && page2.data).toBeTruthy();
+expect(page1.data.items).not.toEqual(page2.data.items);
+expect(page1.data.total).toBeGreaterThan(page1.data.limit);
 ```
 
 ### `simulateFlow`
@@ -46,16 +52,21 @@ expect(page1.total).toBeGreaterThan(page1.limit);
 Simulate flow execution and inspect step history:
 
 ```ts
-const execution = await simulateFlow("refundApproval", {
-  input: { refundId: "rf_1", amount: 50 },
-  events: {
-    "refund.approved": { refundId: "rf_1", approvedBy: "mgr_1" },
+import { refundApproval } from "../refundApproval/flow.js";
+
+const execution = await simulateFlow(
+  refundApproval,
+  { refundId: "rf_1", amount: 50 },
+  {
+    capabilityResults: {
+      "billing.validateRefund": { valid: true },
+    },
   },
-});
+);
 
 expect(execution.status).toBe("completed");
-expect(execution.steps).toHaveLength(4);
-expect(execution.steps[0].name).toBe("validateRefund");
+expect(execution.history.length).toBeGreaterThan(0);
+expect(execution.history[0]?.stepName).toBe("validateRefund");
 ```
 
 ### `mockAI`
@@ -65,7 +76,7 @@ Mock AI provider responses:
 ```ts
 const ctx = createTestContext({
   ai: mockAI({
-    summarizeTicket: { summary: "Customer wants refund", priority: "high", sentiment: "negative" },
+    generate: { summary: "Customer wants refund", priority: "high", sentiment: "negative" },
   }),
 });
 
@@ -73,6 +84,8 @@ const result = await ctx.ai.generate({ prompt: "summarizeTicket", input: { ticke
 expect(result.priority).toBe("high");
 ```
 
+`mockAI` keys responses by **operation** (`generate`, `extract`, `classify`, `retrieve`), not by prompt name. All prompts share the configured response for each operation.
+
 ### `createTestContext`
 
 Build a test `ctx` with controllable mocks:
@@ -101,21 +114,21 @@ const execution = await simulateFlow(myFlow, input, {
 ## Security Test Patterns
 
 ```ts
-// Assert unauthorized access is rejected
-await expect(
-  runCapability("deleteUser", {
-    input: { userId: "usr_1" },
-    auth: { roles: ["viewer"], scopes: [], provider: "test" },
-  })
-).rejects.toMatchObject({ code: "forbidden" });
-
-// Assert cross-tenant access is blocked
-await expect(
-  runCapability("getUser", {
-    input: { userId: "usr_1" },
-    auth: { tenantId: "other_tenant", roles: ["admin"], scopes: [], provider: "test" },
-  })
-).rejects.toMatchObject({ code: "forbidden" });
+import { assertCapabilityDenied } from "@plumbus/core/testing";
+
+// Assert unauthorized access is rejected (returns { success: false }, does not throw)
+const denied = await runCapability(
+  deleteUser,
+  { userId: "usr_1" },
+  { auth: { roles: ["viewer"], scopes: [], provider: "test" } },
+);
+expect(denied.success).toBe(false);
+expect(denied.error?.code).toBe("forbidden");
+
+// Or use the helper
+await assertCapabilityDenied(deleteUser, { userId: "usr_1" }, {
+  auth: { roles: ["viewer"], scopes: [], provider: "test" },
+});
 ```
 
 ## Governance Test Patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,8 @@
   },
   "files": [
     "dist",
-    "instructions"
+    "instructions",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "plumbus",
@@ -95,8 +96,8 @@
     "esbuild": "^0.25.12",
     "typescript": "^5.7.0",
     "@plumbus/api": "0.1.2",
-    "@plumbus/mcp": "0.5.1",
-    "@plumbus/voice": "0.3.0"
+    "@plumbus/voice": "0.3.0",
+    "@plumbus/mcp": "0.5.1"
   },
   "scripts": {
     "build": "tsc -b",