@plumbus/core 0.6.3 → 0.6.5

package/instructions/README.md

@@ -0,0 +1,38 @@
+# @plumbus/core — Agent Instructions
+
+This folder ships with the npm tarball. It is the entry point for AI coding agents working in a Plumbus consumer app. Read these files when implementing framework primitives, CLI workflows, security, testing, or optional add-on integration.
+
+For conceptual reference, see `docs/` in the Plumbus monorepo. These files are **prescriptive** (do this, don't do that).
+
+| File | When to read |
+|------|--------------|
+| [guardrails.md](./guardrails.md) | First. Framework-first rules, forbidden escape hatches, git safety. |
+| [framework.md](./framework.md) | Core abstractions, `ctx`, consumption surfaces, project layout, server hooks. |
+| [capabilities.md](./capabilities.md) | `defineCapability()`, kinds, access, effects, MCP/API exposure. |
+| [entities.md](./entities.md) | `defineEntity()`, fields, classification, tenant scoping. |
+| [events.md](./events.md) | `defineEvent()`, outbox pattern, consumers. |
+| [flows.md](./flows.md) | `defineFlow()`, steps, triggers, retries. |
+| [prompts.md](./prompts.md) | `definePrompt()`, `system`/`description`, model resolution. |
+| [ai.md](./ai.md) | `ctx.ai` operations, cost tracking, env-based provider config. |
+| [translations.md](./translations.md) | `defineTranslation()`, `ctx.translations`. |
+| [security.md](./security.md) | Access policies, tenant isolation, auth adapters. |
+| [governance.md](./governance.md) | Advisory rules, `plumbus verify`, compliance profiles. |
+| [testing.md](./testing.md) | `runCapability`, `simulateFlow`, `mockAI`, security asserts. |
+| [patterns.md](./patterns.md) | Naming conventions, do's/don'ts, common recipes. |
+| [cli.md](./cli.md) | CLI commands (dev, migrate, generate, test, etc.). |
+| [mcp.md](./mcp.md) | Core MCP surface (`exposeAs`, `plumbus mcp *`). |
+| [api.md](./api.md) | Core partner API surface (`exposeAs: ['api']`). |
+| [deployment.md](./deployment.md) | Production deployment, workers, health, env vars. |
+| [peer-dependencies.md](./peer-dependencies.md) | **Before editing add-on `peerDependencies`** — copy literals exactly. |
+| [upgrading-0.5-capabilities.md](./upgrading-0.5-capabilities.md) | Canonical capability names, invoke policy, flow auth snapshot. |
+
+Package quickstart: [../README.md](../README.md).
+
+## Critical rules
+
+- **Primitives are mandatory architecture** — business logic belongs in capabilities, flows, entities, events, prompts, and translations.
+- **Use `ctx.*` subsystems** — do not bypass the framework with ad hoc infrastructure unless documented.
+- **Never edit `.plumbus/generated/`** — regenerate with `plumbus generate`.
+- **Do not install framework-provided deps** — import Zod from `@plumbus/core/zod`; run tests with `plumbus test`.
+- **Mock AI by operation** — `mockAI({ generate, extract, classify, retrieve })`, not by prompt name.
+- **MCP tool names are canonical** — `<domain>.<name>` (e.g. `billing.getRefund`).

package/instructions/ai.md

@@ -27,7 +27,7 @@ export const summarizeTicket = definePrompt({
 });
 ```
 
-Prompts should NOT hardcode `provider` or model `name`. These are resolved at runtime through the configuration chain (see below). Only set `temperature` and `maxTokens` in the prompt definition.
+Prompts should NOT hardcode `provider` or model `name` unless you have a deliberate per-prompt override. Prefer env-based resolution (`AI_DEFAULT_*`, `PROMPT_{NAME}_*`) or `resolveAiOverrides` in `app/server.ts`. Only set `temperature` and `maxTokens` in the prompt definition when tuning is part of the contract. See `prompts.md` for `system`/`description` content.
 
 ## `ctx.ai` Operations
 
@@ -74,15 +74,63 @@ const docs = await ctx.ai.retrieve({ query: "refund policy for enterprise custom
 // docs: Array<{ content: string, source: string, score: number, metadata?: Record<string, unknown> }>
 ```
 
+Ingest documents with `plumbus rag ingest <path>` (see `cli.md`).
+
+### Generate With Usage
+
+Returns validated output plus token counts and per-request cost:
+
+```ts
+const { data, usage, model, provider, cost } = await ctx.ai.generateWithUsage({
+  prompt: "summarizeTicket",
+  input: { ticketText: input.text, customerTier: "enterprise" },
+});
+```
+
+### Stream Generate
+
+Stream partial output for long-running generations:
+
+```ts
+for await (const event of ctx.ai.streamGenerate({
+  prompt: "writeChapter",
+  input: { topic: input.topic },
+})) {
+  if (event.type === "delta") process.stdout.write(event.text);
+}
+```
+
+### Multi-turn messages
+
+Pass explicit chat messages instead of a named prompt:
+
+```ts
+await ctx.ai.generate({
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: input.question },
+  ],
+});
+```
+
+### Cost helpers
+
+- `ctx.ai.checkProviderCostBudget()` — pre-flight budget check before provider calls
+- `ctx.ai.recordProviderCost()` — record spend from external provider usage APIs
+
 ## Output Validation
 
 All AI responses are validated against the prompt's output Zod schema. On failure, the framework retries generation (configurable). If retries are exhausted, a structured error is raised.
 
 ## Cost Tracking
 
-Every AI invocation records: model used, input/output token counts, latency, and prompt name. Token counts come directly from provider responses and are always accurate.
+Every AI invocation records: model used, input/output token counts, latency, and prompt name. Token counts come directly from provider responses.
+
+**Per-request cost** is computed automatically from a built-in pricing table (`calculateModelCost`) covering major OpenAI and Anthropic models. Unknown models (Ollama, custom endpoints) return cost `$0`. Cached-token and long-context adjustments are applied when providers return cache metadata.
 
-**Actual costs** are fetched from provider usage APIs — the framework never guesses or hardcodes pricing. Use `createUsageAPIClient()` to configure OpenAI and Anthropic billing API access:
+`generateWithUsage()` and `streamGenerate()` expose `cost` on each call. Budget limits (`BudgetConfig`) can gate requests by tokens or dollar amounts.
+
+**Optional billing reconciliation:** use `createUsageAPIClient()` + `createCostTracker().syncCosts()` to pull actual invoices from provider billing APIs — this supplements, but does not replace, per-request cost from the pricing table:
 
 ```ts
 import { createUsageAPIClient, createCostTracker } from "@plumbus/core";
@@ -92,24 +140,10 @@ const openaiUsage = createUsageAPIClient({
   apiKey: process.env.AI_OPENAI_API_KEY,
 });
 
-const anthropicUsage = createUsageAPIClient({
-  provider: "anthropic",
-  apiKey: process.env.AI_ANTHROPIC_API_KEY,
-});
-
-const costTracker = createCostTracker(budgetConfig, [openaiUsage, anthropicUsage]);
-
-// Fetch actual costs from billing APIs
+const costTracker = createCostTracker(budgetConfig, [openaiUsage]);
 const result = await costTracker.syncCosts();
-if (!result.synced) {
-  console.warn("Cost sync failed:", result.error);
-}
 ```
 
-If the usage API is not configured or unavailable, `cost` on each record is `null` and dollar-based budget limits cannot be enforced. Token-based budget limits always work.
-
-Budget limits (per-request token limit, daily cost limit, per-tenant daily limit) are enforced via `BudgetConfig`.
-
 ## Configuration via Environment Variables
 
 Use `loadConfig()` from `@plumbus/core` in your `config/app.config.ts` — it reads AI provider settings from env vars automatically.
@@ -125,7 +159,7 @@ AI_MODEL=gpt-4o-mini
 
 ### Multi-Provider
 
-Set `AI_DEFAULT_PROVIDER` to enable multi-provider mode. Providers are discovered from `AI_{NAME}_API_KEY` patterns:
+Set `AI_DEFAULT_PROVIDER` to enable multi-provider mode. Env-based discovery supports **only** `AI_OPENAI_*` and `AI_ANTHROPIC_*` slots — other `AI_{NAME}_API_KEY` values are ignored with a warning. Wire additional providers programmatically via `createProviderAdapter` / `createAIService`.
 
 ```bash
 AI_DEFAULT_PROVIDER=openai
@@ -204,6 +238,20 @@ The framework calls this hook before each `generate()`, `generateWithUsage()`, a
 
 ## Security
 
-- Classified fields in prompt inputs are detected and warn/redact based on entity field classifications
+Classified-field scanning is **opt-in**. It runs only when `aiProviders.security` is set in config or via `AI_SECURITY_*` env vars. Omit the block entirely to leave AI calls unscanned (capability `access` policies still apply).
+
+When configured:
+
+| Mode | Behavior |
+|------|----------|
+| `redact` (default) | Warn at `warnThreshold`; replace fields at/above `redactThreshold` with `[REDACTED]` and continue |
+| `block` | Abort the AI call when any field at/above `warnThreshold` is detected (`AISecurityBlockedError`) |
+
+Entity definitions are merged from the registry when the `security` block is present. Thresholds: `warnThreshold` / `redactThreshold` on config, or `AI_SECURITY_WARN_THRESHOLD` / `AI_SECURITY_REDACT_THRESHOLD`. Invalid `AI_SECURITY_MODE` values warn at load and fall back to `redact`.
+
+Also:
+
 - Tenant isolation is enforced — prompts cannot access cross-tenant data
 - All AI invocations are recorded in the audit trail
+
+See `docs/ai/ai-integration.md` and `docs/upgrading-contract-alignment.md` §12.

package/instructions/api.md

@@ -16,4 +16,6 @@ Plumbus capabilities can be exposed to partners on versioned HTTP routes. **Cont
 - **`plumbus api validate` / `generate` / `diff` / `test-fixtures validate`** — CLI entry points; dynamic import of `@plumbus/api`.
 - **`registerApiRoutes()`** — mount partner routes at app bootstrap (requires `@plumbus/api` install).
 
+`plumbus api validate` exits `1` only on hard findings by default; pass `--fail-on-governance` to also fail on advisory API governance signals. Details: `node_modules/@plumbus/api/instructions/manifest-and-cli.md`.
+
 Install the runtime when serving partners: `pnpm add @plumbus/api` (optional peer of `@plumbus/core`, version-locked `0.1.x`).

package/instructions/capabilities.md

@@ -119,6 +119,22 @@ Every capability must declare its side effects in the `effects` field:
 
 Effects are used by governance rules to analyze the system.
 
+## Transactional outbox (default ON)
+
+For `kind: 'action'` and `kind: 'eventHandler'`, handler execution and output validation run inside a single database transaction by default. Entity writes via `ctx.data.*` and `ctx.events.emit()` outbox inserts commit or roll back together.
+
+**Auto-excluded** (non-transactional): `kind: 'job'`, `effects.ai: true`, non-empty `effects.external`, and other kinds (e.g. `query`).
+
+**Recommended:** keep the default ON and fix handlers that assumed partial commits. There is no framework-wide legacy/soft mode.
+
+**Opt out (per app or capability — not the long-term default):**
+- Globally: `execution.transactionalOutbox: false` in config, or `PLUMBUS_TRANSACTIONAL_OUTBOX=false`
+- Per capability: `transactional: false` on `defineCapability({ ... })`
+
+Inside an active transaction, `ctx.flows.start()` and `ctx.jobs.enqueue()` defer until after commit (pre-allocated ids). Nested success audits also defer until commit. Prefer `transactional: false` on parents that invoke AI capabilities — otherwise the parent transaction is held open for the LLM call (one-time warn).
+
+See `docs/upgrading-contract-alignment.md` (Migration stance + §1) and `docs/architecture/execution-lifecycle.md`.
+
 ## Capability-to-capability invocation
 
 The only sanctioned path for synchronous composition is `ctx.capabilities.invoke`:
@@ -205,7 +221,9 @@ export const getRefund = defineCapability({
 ```
 
 **Rules when MCP-exposed:**
-- Only `kind: "query"` and `kind: "action"` may be exposed. `job` and `eventHandler` are rejected at `defineCapability()` time.
+- `kind: "query"` and `kind: "action"` are standard MCP tools.
+- `kind: "job"` is exposed via MCP Tasks (`tools/call` + `_meta.taskMetadata`). Register `mcpTaskEntity` in the app entity list.
+- Only `kind: "eventHandler"` is rejected at `defineCapability()` time for MCP exposure.
 - Either `description`, `mcp.description`, or `explanation.summary` is required.
 - Agent identity is controlled via `access.serviceAccounts` and `access.scopes`. Deny-by-default still holds.
 

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