@arnilo/prism 0.3.2 → 0.5.0

package/docs/live-testing.md

@@ -0,0 +1,126 @@
+# Live and end-to-end testing
+
+## What it does
+
+Prism ships three network-free test tiers by default (`npm test`, per-package `node --test` suites, and packed-consumer journeys) plus an opt-in **live matrix** that runs the same public surface against real credentials. This page documents how to run the live matrix, which credentials each suite needs, and the guarantees the harness gives you: a missing credential skips its suite (never fails), and secrets never enter the repo, logs, or reports.
+
+## When to use it
+
+- Before a release: prove every public export subpath still works over a real wire or real process, not just against fakes.
+- After adding a provider or protocol adapter: add a live suite, register it in `scripts/live-matrix.json`, and the coverage gate + doc-check keep the docs honest.
+- In CI: scheduled canaries probe deployed endpoints; strict mode is available for release gates.
+
+## Coverage definition (what "100%" means)
+
+- **Functional-surface 100%:** every public export subpath across the ten first-party packages (98 subpaths, tracked in `scripts/e2e-coverage.json`) is exercised by at least one suite — a hermetic unit test, a real-wire live test, a real-binary leg, or the full-surface packed journey (`scripts/e2e-full-surface.test.mjs`). The gate is `node scripts/e2e-coverage-gate.mjs` (baseline mode fails only on regressions).
+- **Line-ratchet caveat:** the per-package line-coverage thresholds in `scripts/coverage-thresholds.json` are measured by the network-free `npm test` run only. Live suites intentionally do not contribute to line coverage; 100% functional-surface coverage does not mean 100% line coverage of every branch under live conditions.
+
+## Running the matrix
+
+```sh
+npm run test:live                 # run active suites whose credentials are present
+node scripts/live-matrix.mjs --check   # validate manifest + per-suite skip/run table (no spawns)
+```
+
+| knob | effect |
+|---|---|
+| `PRISM_LIVE_ENV_FILE` | credential file, loaded with Node `--env-file` semantics. Default: `scripts/live.env` when present. Copy `scripts/live.env.example` to start. |
+| `PRISM_LIVE_FILTER=<sub>` | only suites whose id contains `<sub>` |
+| `PRISM_LIVE_STRICT=1` | any skip fails the **run** (exit 1), not the suite — for release gates |
+| `PRISM_LIVE_DRY_RUN=1` | accounting only, no spawns |
+| `PRISM_LIVE_CONCURRENCY=n` | parallel suites (default 1, sequential) |
+| `PRISM_LIVE_SUITE_TIMEOUT_MS` | per-suite kill timer (default 600000) |
+
+### Skip-not-fail contract
+
+A suite whose required credentials are absent is **skipped with a reason**, never failed. `scripts/live-matrix.json` encodes the contract per suite (`requires` all-of, `requiresAny` any-of, `optional` extras); `resolveSuiteState()` is the pure implementation the runner and the `--check` table share. Strict mode inverts the semantics deliberately: with `PRISM_LIVE_STRICT=1` a skip fails the run, because a release gate wants proof the credentials were present and the wires were exercised.
+
+### Model selection
+
+Every provider suite reads `PRISM_LIVE_<PROVIDER>_MODEL` to pin the model under test (multi-probe suites suffix `_CHAT_MODEL` / `_MESSAGES_MODEL` / `_GPT_MODEL`). Each manifest row records the wired env var and its cost-bounded default, so cost stays predictable. `wired: false` means the suite does not read that env var yet.
+
+### Report
+
+Each run writes `docs/_evidence/live-matrix-report.{json,md}`: per-suite status/duration/detail, totals, a filter/strict/dry-run annotation, and an e2e surface-coverage summary. The report contains env var **names** and model ids — never secret values.
+
+## Credential matrix
+
+Set only the rows you want to run; everything else skips. Least-privilege scope is mandatory per row: issue the narrowest credential that satisfies the named probe. Credentials live in `scripts/live.env` (gitignored) or `~/.config/prism/live.env` (out-of-repo), never in the repository, test fixtures, or CI logs; the journey suites assert the `assertNoSecretLeak` convention (from `@arnilo/prism/testing/*`) over every transcript they produce, and the manifest validator rejects secret-shaped values.
+
+<!-- generated:live-matrix:start -->
+| suite | status | required credentials | model override | least-privilege scope | cost |
+|---|---|---|---|---|---|
+| `providers/openai` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_OPENAI_MODEL` (default `gpt-5.1`) | Project-scoped chat-completion key; least privilege: restrict to chat models. | 2 requests (1 text, 1 tool-call) on the configured model. |
+| `providers/anthropic` | active | `PRISM_LIVE_PROVIDER_TESTS` + `ANTHROPIC_API_KEY` | `PRISM_LIVE_ANTHROPIC_MODEL` (default `claude-haiku-4-5`) | Chat-completion key. | 2 requests. |
+| `providers/google` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `GEMINI_API_KEY` / `GOOGLE_API_KEY` | `PRISM_LIVE_GOOGLE_MODEL` (default `gemini-2.5-flash-lite`) | Gemini API key (either var). | 2 requests. |
+| `providers/alibaba` | active | `PRISM_LIVE_PROVIDER_TESTS` + `PRISM_LIVE_DASHSCOPE_KEY` | `PRISM_LIVE_DASHSCOPE_MODEL` (default `text-embedding-v4`) | DashScope key. | 2 requests (embedding/roundtrip class). |
+| `providers/clinepass` | active | `PRISM_LIVE_PROVIDER_TESTS` + `CLINE_API_KEY` | `PRISM_LIVE_CLINEPASS_MODEL` (default `cline-pass/deepseek-v4-flash`) | Cline provider key. | 2 requests. |
+| `providers/commandcode` | active | `PRISM_LIVE_PROVIDER_TESTS` + `COMMAND_CODE_API_KEY` | `PRISM_LIVE_COMMANDCODE_CHAT_MODEL` (default `Qwen/Qwen3.8-Flash`), `PRISM_LIVE_COMMANDCODE_MESSAGES_MODEL` (default `claude-haiku-4-5-20251001`), `PRISM_LIVE_COMMANDCODE_GPT_MODEL` (default `gpt-5.6-luna`) | Command Code key; probes three cheap routed models. | 3-4 requests on cheap models. |
+| `providers/deepseek` | active | `PRISM_LIVE_PROVIDER_TESTS` + `DEEPSEEK_API_KEY` | `PRISM_LIVE_DEEPSEEK_MODEL` (default `deepseek-v4-flash`) | DeepSeek key. | 2 requests on flash-class model. |
+| `providers/hyper` | active | `PRISM_LIVE_PROVIDER_TESTS` + `HYPER_API_KEY` | `PRISM_LIVE_HYPER_CHAT_MODEL` (default `deepseek-v4-pro`), `PRISM_LIVE_HYPER_MESSAGES_MODEL` (default `qwen3.6-plus`) | Hyper key; second model probes the exact-prefix cache. | ~4 requests incl. ~1 KiB prefix cache write; sub-cent. |
+| `providers/kimi` | active | `PRISM_LIVE_PROVIDER_TESTS` + `KIMI_API_KEY` | `PRISM_LIVE_KIMI_MODEL` (default `kimi-for-coding`) | Kimi coding-plan credential. | 2 requests. |
+| `providers/neuralwatt` | active | `PRISM_LIVE_PROVIDER_TESTS` + `NEURALWATT_API_KEY` | `PRISM_LIVE_NEURALWATT_MODEL` (default `glm-5.2`) | NeuralWatt key. | 2 requests. |
+| `providers/opencode-go` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENCODE_API_KEY` | `PRISM_LIVE_OPENCODE_MODEL` (default `mimo-v2.5`) | OpenCode Go key. | 2 requests. |
+| `providers/openrouter` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENROUTER_API_KEY` | `PRISM_LIVE_OPENROUTER_MODEL` (default `anthropic/claude-sonnet-4`) | OpenRouter key (any routed model id). | 2 requests. |
+| `providers/xai` | active | `PRISM_LIVE_PROVIDER_TESTS` + `XAI_API_KEY`; optional: `PRISM_LIVE_XAI_OAUTH` | `PRISM_LIVE_XAI_MODEL` (default `grok-4.6`) | xAI key; OAuth leg additionally needs PRISM_LIVE_XAI_OAUTH=1. | 2-3 requests. |
+| `providers/zai` | active | `PRISM_LIVE_PROVIDER_TESTS` + `ZAI_API_KEY` | `PRISM_LIVE_ZAI_MODEL` (default `glm-5.2`) | Z.ai key. | 2 requests. |
+| `web-tools/brave` | active | `PRISM_LIVE_WEB` + `PRISM_BRAVE_SEARCH_TOKEN` | — | Brave Search token, least-privilege plan; 1 result per query. | 1 search request. |
+| `web-tools/exa` | active | `PRISM_LIVE_WEB` + `PRISM_EXA_API_KEY` | — | Exa key; 1 result per query. | 1 search request. |
+| `web-tools/firecrawl` | active | `PRISM_LIVE_WEB` + `PRISM_FIRECRAWL_API_KEY` | — | Firecrawl key; bounded 64 KiB markdown fetch. | 1 fetch request. |
+| `web-tools/browser-live` | active | any of: `PRISM_LIVE_PLAYWRIGHT` / `PRISM_TEST_PLAYWRIGHT` | — | Real Chromium, no secret; needs Playwright browsers installed. | Local browser session, no API spend. |
+| `web-tools/obscura-live` | active | `PRISM_LIVE_OBSCURA` + `PRISM_OBSCURA_BIN` | — | Local obscura CLI binary; suite fails closed if flag set without binary. | Local process, no API spend. |
+| `memory/observational-live` | active | `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_OPENAI_MODEL` (not wired yet) | Reuses the OpenAI key as the compaction worker provider. | A few small summarization requests. |
+| `memory/compaction-llm-live` | active | `PRISM_LIVE_COMPACTION_TESTS` | — | Stub leg today: live summary-provider checks are wired by plans/064 Task 6 (provider key + model env TBD there). | n/a until wired. |
+| `office/libreoffice-golden` | active | `PRISM_TEST_LIBREOFFICE` | — | Local LibreOffice binary renders golden documents; no secret. | Local process, no API spend. |
+| `office/drawio-live` | active | any of: `PRISM_LIVE_DRAWIO_URL` / `PRISM_TEST_DRAWIO_URL` | — | Operator-hosted drawio export service URL (not a secret). | 1-2 export requests to your own service. |
+| `core/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Throwaway PostgreSQL database URL (sessions + enterprise + event-source + memory vector legs). | Local/container DB, no API spend. |
+| `core/nats` | active | `PRISM_TEST_NATS_URL` | — | NATS server URL with JetStream enabled. | Local/container server, no API spend. |
+| `coding-tools/docker-sandbox` | active | `PRISM_TEST_DOCKER_SANDBOX` + `PRISM_TEST_DOCKER_BIN` + `PRISM_TEST_DOCKER_IMAGE` + `PRISM_TEST_DOCKER_USER` | — | Local Docker daemon + pinned minimal sandbox image; no secret. | Local containers, no API spend. |
+| `core/keychain` | active | `PRISM_TEST_KEYCHAIN` | — | Real OS keychain; writes throwaway test entries only. | Local, no API spend. |
+| `acp/client-smoke` | active | `PRISM_TEST_ACP_CLIENT` | — | Real ACP SDK client over stdio in a subprocess; sandboxed, policy never disabled. | Local process, no API spend. |
+| `canaries/deployed` | active | `PRISM_LIVE_CANARIES`; optional: `PRISM_CANARY_TIMEOUT_MS` `PRISM_CANARY_REPORT` | — | Deployed prism provider/MCP/A2A endpoints; script itself validates all PRISM_CANARY_* URL/token vars and credential-free HTTPS. | 1-4 bounded requests (64 KiB JSON cap) against your deployments. |
+| `providers/azure` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_API_KEY` + `PRISM_LIVE_AZURE_MODEL` | `PRISM_LIVE_AZURE_MODEL` (default `gpt-5.1`) | Azure OpenAI resource key. | 3-4 requests on the configured deployment. |
+| `providers/bedrock` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` | `PRISM_LIVE_BEDROCK_MODEL` (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`) | AWS access key + secret (SigV4). | 3-4 requests on haiku-class model. |
+| `providers/vertex` | active | `PRISM_LIVE_PROVIDER_TESTS` + `GOOGLE_VERTEX_PROJECT` + `PRISM_VERTEX_ACCESS_TOKEN` | `PRISM_LIVE_VERTEX_MODEL` (default `gemini-2.5-flash`) | Pre-minted Vertex bearer token (e.g. gcloud auth print-access-token). | 3-4 requests on flash-class model. |
+| `providers/ollama` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OLLAMA_BASE_URL` | `PRISM_LIVE_OLLAMA_MODEL` (default `(first model served by OLLAMA_BASE_URL)`) | No credential for local ollama serve; Ollama Cloud key optional via provider options. | 3-4 requests on the first locally pulled model. |
+| `providers/ai-sdk` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_AISDK_MODEL` (default `gpt-5.1`) | Reuses OPENAI_API_KEY through the real @ai-sdk/openai provider. | 3 requests on gpt-5.1. |
+| `providers/model-discovery` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `OPENAI_API_KEY` / `GEMINI_API_KEY` | — | Reuses OPENAI_API_KEY or GEMINI_API_KEY for a real listing request. | 2 GET /models requests (second cached in TTL). |
+| `cli/live-journey` | planned | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | — | Packed CLI: init/provider-add/print/json/rpc over a real provider; transcript secret-scanned. | 1 pack + install, offline scaffold tests, <=3 wire prompts on the selected provider model (wire legs skip on 401/403). |
+| `memory/rag-rerankers-live` | active | any of: `PRISM_TEST_TEI_RERANKER_URL` / `PRISM_TEST_HOSTED_RERANK_URL`; optional: `PRISM_TEST_HOSTED_RERANK_URL` | `PRISM_LIVE_TEI_RERANKER_MODEL` (default `(endpoint default model)`), `PRISM_LIVE_HOSTED_RERANK_MODEL` (default `(endpoint default model)`) | Real TEI / OpenAI-compatible rerank endpoints; each leg self-skips when its endpoint env is unset. | 1 rerank request per configured endpoint (≤2 total). |
+| `coding-tools/openapi-live` | active | `PRISM_LIVE_OPENAPI_TOOLS` | — | Real public OpenAPI 3.1 spec (warnely.com) + real GET tool calls; no credential. | 3 HTTP requests against example.com-class public hosts (plan budget ≤5). |
+| `coding-tools/computer-use-live` | active | `PRISM_TEST_COMPUTER_USE` + `PRISM_COMPUTER_USE_BIN` | — | Real host computer-use-linux MCP binary over stdio; real tool inventory + one bounded read-only screenshot. | Local desktop only; ≤30s ceiling. |
+| `mcp/client-smoke` | active | `PRISM_TEST_MCP_CLIENT` | — | Real @modelcontextprotocol/client SDK over a real stdio subprocess serving createPrismMcpServer. | Local only; ≤30s. |
+| `core/opa-live` | active | `PRISM_TEST_OPA_URL` | — | Operator-hosted OPA REST endpoint (optionally token-gated). | <=3 decision requests to the operator OPA endpoint; fail-closed probe never reaches the wire. |
+| `core/oidc-live` | active | `PRISM_TEST_OIDC_ISSUER` + `PRISM_TEST_OIDC_AUDIENCE` + `PRISM_TEST_OIDC_TOKEN` | — | Real IdP issuer/JWKS + short-lived test bearer token. | 1 JWKS fetch (cached) + 3 local verify calls; no token endpoint traffic. |
+| `core/webhooks-live` | active | `PRISM_TEST_WEBHOOK_URL` | — | Operator-controlled signed webhook receiver. | <=3 webhook deliveries (1 signed target + 1 loopback retry receiver). |
+| `core/artifact-bodies-s3-live` | active | `PRISM_TEST_S3_ENDPOINT` + `PRISM_TEST_S3_KEY` + `PRISM_TEST_S3_SECRET` + `PRISM_TEST_S3_BUCKET` | — | Dedicated throwaway S3-compatible bucket. | <=5 S3 requests (put/get/presign/delete x2). |
+| `cli/journey` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `KIMI_API_KEY` / `ZAI_API_KEY` / `OPENCODE_API_KEY` / `NEURALWATT_API_KEY` / `DASHSCOPE_API_KEY` / `OLLAMA_API_KEY` | — | First init-catalog provider credential present in the environment. | 4-5 one-shot requests on the default catalog model. |
+| `memory/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Postgres memory store + pgvector index round-trips on the operator database. | Bounded insert/query cycles against the configured Postgres. |
+| `memory/graft` | active | — (hermetic leg) | — | Graft upstream CLI child-process protocol (real binary spawns against the in-repo fixture graft bin). | Hermetic; no network. |
+| `memory/wiki` | active | — (hermetic leg) | — | Wiki lifecycle over real fs trees (init/refresh/lint/search fallback; qmd child-process client degrades without the binary). | Hermetic; no network. |
+| `coding-tools/lsp-forge` | active | — (hermetic leg) | — | LSP/language-intelligence + forge suites: real child-process spawns over the real LSP/forge wire protocols against fixture binaries. | Hermetic; no network. |
+| `ag-ui/conformance` | active | — (hermetic leg) | — | AG-UI + ACP conformance suites: real-event replay over the acp/a2a/ag-ui protocol surfaces (fixture agents, real event-source wire semantics). | Hermetic; no network. |
+| `prism-providers/conformance` | active | — (hermetic leg) | — | Plan-065 machine-checked thinking coverage: every first-party reasoning catalog model declares capabilities.thinkingLevels + a compat.thinkingFamily stamp and emits a legal effort field on the wire (14 catalogs walked hermetically). | free |
+<!-- generated:live-matrix:end -->
+
+## Strict CI workflow
+
+The scheduled [`live-canaries` workflow](../.github/workflows/live-canaries.yml) (Tuesdays 05:43 UTC, plus `workflow_dispatch`) runs four restricted protocol canaries — provider, MCP, A2A, and Brave search — from a GitHub `live-canaries` environment, with every value supplied through repository secrets and a 15 s per-canary timeout. It runs `scripts/live-canary.mjs` (gated on `PRISM_LIVE_CANARIES=1`, which requires **all** canary credentials together so A2A never runs standalone) and uploads the status report as a workflow artifact. The full live matrix runs on a weekly schedule (and on demand) via the [`live-matrix` workflow](../.github/workflows/live-matrix.yml): strict-mode filtered run (default `providers/opencode-go`, the credentialed suites) with the report + e2e-coverage evidence uploaded as artifacts; operators also run it from a credentialed checkout with `npm run test:live`, optionally `PRISM_LIVE_STRICT=1` when gating a release.
+
+## Security and performance notes
+
+- Credentials never enter the repo, test fixtures, logs, or reports; only env var names and model ids are persisted. `assertNoSecretLeak` (exported from `@arnilo/prism/testing/*`) runs over live transcripts, and secret-shaped values in `scripts/live-matrix.json` are rejected by the manifest validator.
+- Suite costs are bounded and recorded per row; provider model defaults are the cheapest cost-bounded models that satisfy each probe.
+- Per-suite `PRISM_LIVE_SUITE_TIMEOUT_MS` kill timers and opt-in `PRISM_LIVE_CONCURRENCY` parallelism keep a stuck wire from stalling the run.
+- Packaging tests run under `scripts/with-build-lock.mjs` so parallel suites never race the TypeScript build.
+
+## Extension and configuration notes
+
+- Add a suite: write the env-gated test (skip-not-fail), register it in `scripts/live-matrix.json` (`id`, `package`, `status`, `source`, `command`, `cwd`, `requires`/`requiresAny`, model wiring, least-privilege `scope`, `cost`), then run `node scripts/generate-live-docs.mjs --write` to refresh the table above. `scripts/live-doc-check.test.mjs` fails `npm test` when the doc drifts.
+- Add a credential: extend `scripts/live.env.example` and the relevant manifest `requires` list. Prefer `requiresAny` when a probe accepts several interchangeable providers.
+
+## Related APIs
+
+- `@arnilo/prism/testing/*` conformance helpers (`assertProviderStreamConforms`, `assertNoSecretLeak`): the assertion vocabulary live suites reuse.
+- `scripts/e2e-coverage-gate.mjs` + `scripts/e2e-coverage.json`: the functional-surface coverage ledger this matrix satisfies.
+- [Provider conformance](provider-conformance.md): the network-free contract checks every provider adapter must pass before a live suite is worth running.

package/docs/mcp-tools.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-mcp` has two explicit directions. Its client bridge connects hosts to remote [Model Context Protocol](https://modelcontextprotocol.io) servers and maps discovered tools to ordinary `ToolDefinition`s. Its server API registers selected Prism `ToolDefinition` and `CommandDefinition` values on the official SDK `McpServer`, with required authorization and a bounded optional Web-standard Streamable HTTP handler. The package pins `@modelcontextprotocol/sdk` **1.30.0** (MCP protocol negotiation remains SDK-owned) and adds no MCP branch to core Prism.
+`@arnilo/prism-mcp` has two explicit directions. Its client bridge connects hosts to remote [Model Context Protocol](https://modelcontextprotocol.io) servers and maps discovered tools to ordinary `ToolDefinition`s. Its server API registers selected Prism `ToolDefinition` and `CommandDefinition` values on the official SDK `McpServer`, with required authorization and a bounded optional Web-standard Streamable HTTP handler. The package pins the modular TypeScript SDK v2 packages `@modelcontextprotocol/client` and `@modelcontextprotocol/server` **2.0.0** (MCP protocol negotiation remains SDK-owned; the 2026-07-28 adoption is tracked in plan 063) and adds no MCP branch to core Prism.
 
 Primary API:
 
@@ -32,19 +32,25 @@ const app = await bridge.apps!.readResource("ui://weather/card");
 
 `bridge.apps` exposes reviewed UI metadata, linked bounded `ui://` HTML, and same-server app tools for a host renderer/proxy; it never creates an iframe or executes HTML.
 
+**Conformance and verification record (plan 063 task 7):** the official `@modelcontextprotocol/conformance` suite runs against the dual-era serving stack via `node scripts/mcp-conformance-2026.mjs` — the 20 expressible scenarios pass and the 14 scenarios requiring surface Prism does not expose (server-initiated sampling/elicitation/logging/progress from tool callbacks, `resources/subscribe`, completion capability, session-based SSE polling, non-text tool content blocks) are recorded as documented boundaries in `scripts/mcp-conformance-2026-baseline.yaml`. The CLI publishes scenarios only up to spec version 2025-11-25; the run is repeated when 2026-07-28 scenarios ship upstream. Measured on the loopback fixture (single process): legacy connect ~60ms, auto connect (with the one discovery probe) ~40ms, pinned modern connect ~20ms, steady-state bridge tool call ~4ms, uncached list walk ~5ms, cached list refresh ~2ms — the only added connect cost versus 1.x is the single negotiation probe plus SDK codec work. Security regression coverage lives in the package suites: malformed envelopes/headers, auth mix-up (`ERR_PRISM_MCP_OAUTH_ORIGIN`), SSRF/DNS-rebinding, oversized JSON/schema/results, MRTR round/replay, subscription exhaustion caps, cross-principal cache/session isolation, timeouts, cancellation, and redaction.
+
+**Extension status (revalidated 2026-09-05 against the modular SDK v2, plan 063 task 6):** MCP Apps (`io.modelcontextprotocol/ui`) is the only extension Prism negotiates — on both the 2025 legacy handshake and 2026-07-28 (modern capabilities ride per request in `params._meta`); resource reads/pagination now go through SDK v2 `listResources`/`readResource` with the same per-descriptor byte bounds, item caps, cursor-loop detection, and linked-HTML validation as before. **Tasks (`io.modelcontextprotocol/tasks`) is intentionally not advertised and not supported in this release**: neither the bridge client nor `createPrismMcpServer` declares it, draft-era `task` members on tool results fail closed (`McpBridgeError` surfaced as a `ToolResult.error`, never read as tool output; modern `resultType: "task"` fails SDK decode), and task handles are not accepted without a supported extension codec plus a durable ownership model. Re-evaluate Tasks when the official TypeScript client/server extension codec supports task result dispatch, polling/update/cancel, and subscription notifications with green conformance.
+
 ```ts
 const bridge = await connectMcpCapabilities({
   serverId: "research",
   transport: { type: "streamable-http", url, allowedOrigins: [origin] },
-  roots: () => [{ uri: "file:///workspace", name: "workspace" }],
-  sampling: hostSampling,       // host selects model/provider/credentials
-  elicitation: hostElicitation, // URL mode returns approval; Prism never opens/fetches URL
+  roots: () => [{ uri: "file:///workspace", name: "workspace" }], // deprecated: kept for legacy callers only
+  sampling: hostSampling,       // deprecated: kept for legacy callers only
+  elicitation: hostElicitation, // active; URL mode returns approval; Prism never opens/fetches URL
 });
 await bridge.listResources();
 await bridge.getPrompt("review", { topic: "security" });
 ```
 
-Server capability matrix for SDK 1.30.0: tools/resources/prompts and their list-change notifications are supported through official registrations; roots/sampling/form+URL elicitation are supported as explicit client callbacks. Missing server resources/prompts throw `McpUnsupportedCapabilityError` with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`. Resource/prompt results and sampling/elicitation inputs/results are bounded JSON. Accepted form/URL elicitation requires host-only `humanInteraction: true`; bridge strips marker before protocol output and fails closed when absent. Automatic root discovery/consent, model selection, credential resolution, URL navigation, generic command proxying, and custom JSON-RPC are unsupported.
+Roots and sampling callbacks are **deprecated with MCP 2026-07-28 (SEP-2577)** and kept only for existing legacy callers; Synapta adds nothing on those surfaces and they may be removed when the protocol revision does (earliest per spec: a revision released on or after 2027-07-28). Elicitation is the active capability: on the modern era a server answering a tool call with `input_required` is fulfilled by the SDK's MRTR driver against the same `elicitation` callback, capped by `maxMrtrRounds` (default 10, the SDK's own bound — the option can only tighten it) with the call timeout as the outer ceiling; on the legacy era the same handler serves direct `elicitation/create` requests. `humanInteraction: true` remains mandatory for accepted elicitation, and no hand-written retry/state machinery exists on either path.
+
+Server capability matrix for the modular TypeScript SDK v2 (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0): tools/resources/prompts and their list-change notifications are supported through official registrations; roots/sampling/form+URL elicitation are supported as explicit client callbacks. Missing server resources/prompts throw `McpUnsupportedCapabilityError` with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`. Resource/prompt results and sampling/elicitation inputs/results are bounded JSON. Accepted form/URL elicitation requires host-only `humanInteraction: true`; bridge strips marker before protocol output and fails closed when absent. Automatic root discovery/consent, model selection, credential resolution, URL navigation, generic command proxying, and custom JSON-RPC are unsupported.
 
 Server direction:
 
@@ -66,18 +72,22 @@ const handleMcp = await createPrismMcpWebHandler(server, {
   resolveAuthInfo: authenticateRequest,
   allowedHosts: ["api.example.test"],
   allowedOrigins: ["https://app.example.test"],
-  // Omit these two for bounded stateless JSON mode.
+  // Omit these two for dual-era serving without legacy sessions.
   sessionIdGenerator: crypto.randomUUID,
   resolveIdentity: (_request, auth) => auth ? { id: validatedPrincipalId(auth) } : false,
 });
 ```
 
-`McpServer.connect(transport)` remains available for SDK stdio or in-memory transports. The helper uses SDK `WebStandardStreamableHTTPServerTransport`; it does not start a listener. Default remains bounded stateless JSON-response mode. Supplying `sessionIdGenerator` enables SDK `MCP-Session-Id` POST/GET/DELETE/SSE lifecycle and requires exact `allowedOrigins` plus host `resolveIdentity`. Every request re-authenticates, and a different principal receives non-disclosing 404. SDK owns protocol-version/session headers and SSE semantics. SDK 1.30.0's in-memory event store is not enabled, so `Last-Event-ID` replay is explicitly unsupported; reconnect starts only through SDK-supported active session GET.
+`createPrismMcpWebHandler()` is dual-era on the modular SDK v2 serving entries. Default (factory, no `sessionIdGenerator`): modern 2026-07-28 serving through SDK `createMcpHandler` — one fresh `McpServer` per request, SDK-generated `server/discover`, result metadata, cancellation and modern headers — with the SDK stateless fallback answering 2025-era traffic; modern responses carry no `Mcp-Session-Id`. Supplying `sessionIdGenerator` keeps documented legacy `MCP-Session-Id` POST/GET/DELETE/SSE lifecycle on a sessionful `WebStandardStreamableHTTPServerTransport` beside a strict modern handler (classified legacy traffic routes separately), and still requires exact `allowedOrigins` plus host `resolveIdentity`; every request re-authenticates, and a different principal receives non-disclosing 404. `Last-Event-ID` replay remains explicitly unsupported.
+
+Security gates run in front of the SDK entries because `createMcpHandler` intentionally provides none: exact Host/Origin allowlist checks execute before body parsing, auth, and dispatch; bounded body parsing feeds `parsedBody`; verified `AuthInfo` is passed explicitly; authorization and identity checks run on every request; modern serving state never trusts a transport session id. A bare `McpServer` instance with sessions keeps legacy-only behavior; stateless mode requires a factory (one fresh server per request). The returned value stays callable and carries SDK lifecycle properties: `fetch` (same function), `close()` (tears down both eras), `notify.toolsChanged()/promptsChanged()/resourcesChanged()/resourceUpdated(uri)`, and `bus` for `subscriptions/listen`. `maxSubscriptions` (SDK default 1024) and `keepAliveMs` (SDK default 15000, 0 disables) bound modern subscription streams.
+
+`servePrismMcpStdio(factory, options)` serves dual-era stdio: the opening exchange pins the era (one factory instance per connection; `legacy: "serve"` default keeps 2025 openings working, `"reject"` answers them with the unsupported-protocol-version error), and stdout stays protocol-only. `McpServer.connect(transport)` remains available for in-memory transports; direct `server.connect()` over HTTP is legacy-only. `createPrismMcpServer({ cacheHints })` emits SEP-2549 cache hints on cacheable 2026-07-28 results (default `ttlMs: 0`, `private`). Neither HTTP nor stdio helper starts a listener or process lifecycle for you.
 
 ## When to use it
 
 - **Integrate external MCP tool servers** (filesystem, databases, SaaS adapters) without reimplementing JSON-RPC transports in your app.
-- **Bridge a specific upstream server through a reviewed adapter** — e.g. the optional [`@arnilo/prism-obscura`](obscura.md) wraps `connectMcpTools` with Obscura-specific command validation and conservative effect classification for the complete advertised tool surface.
+- **Bridge a specific upstream server through a reviewed adapter** — e.g. the optional [`@arnilo/prism-web-tools/obscura`](obscura.md) subpath wraps `connectMcpTools` with Obscura-specific command validation and conservative effect classification for the complete advertised tool surface.
 - **Keep core dispatch gates** — register returned tools and let `dispatchToolCall` enforce permission, JSON Schema validation (`ToolValidator`), middleware, abort, and parallel execution (Plan 055 Tasks 1–2).
 - **Explicit lifecycle** — connect, refresh on `notifications/tools/list_changed`, and `close()` when the session ends.
 - **Expose selected capabilities** — register a reviewed tool/command allow-list for MCP clients without a custom JSON-RPC server.
@@ -92,7 +102,7 @@ Do **not** use this package as a sandbox, permission engine, or auto-discovery l
 
 `McpToolBridge` exposes `tools`, optional `apps`, `refresh()`, and `close()`. Normal tools are Prism `ToolDefinition`s. Apps requires server acknowledgement; nested resource metadata wins over flat/deprecated and app-only tools stay outside `tools`. Resource reads require linked bounded `ui://` HTML5 with exact MIME; content metadata wins over list defaults.
 
-`createPrismMcpServer()` returns the SDK `McpServer`. It lists only passed tools/commands and explicitly selected `agentRuns` lifecycle tools; JSON Schema parameters are converted through installed Zod v4 for SDK validation, then Prism tool calls still pass through `dispatchToolCall` permission/validator/redactor gates. Command definitions support explicitly selected direct/background/replay workflow operations and optional ownership-scoped schedule operations from `createWorkflowCommands()`; none are registered unless the host passes those command definitions. Calls return bounded MCP text content and `isError` on denial/failure. `createPrismMcpWebHandler()` returns `(Request) => Promise<Response>`.
+`createPrismMcpServer()` returns the SDK `McpServer`. It lists only passed tools/commands and explicitly selected `agentRuns` lifecycle tools; JSON Schema parameters are converted through installed Zod v4 for SDK validation, then Prism tool calls still pass through `dispatchToolCall` permission/validator/redactor gates. Command definitions support explicitly selected direct/background/replay workflow operations and optional ownership-scoped schedule operations from `createWorkflowCommands()`; none are registered unless the host passes those command definitions. Calls return bounded MCP text content and `isError` on denial/failure. `createPrismMcpWebHandler()` remains callable for source compatibility and additionally carries `fetch`, `close`, `notify`, and `bus` from the SDK serving entry.
 
 ## Request/response example
 
@@ -241,15 +251,27 @@ import { createMcpClientAuth } from "@arnilo/prism-mcp";
 const auth = createMcpClientAuth(
   {
     state, // required persistence seam: load/save tokens, discovery, client info, code verifier
-    strategy: { kind: "static", clientId: "prism", clientSecret: "..." }, // or { kind: "dcr", clientMetadata }
+    strategy: { kind: "cimd", clientMetadataUrl: "https://client.example/oauth/metadata.json" }, // preferred
+    // or { kind: "static", clientId: "prism", clientSecret: "..." }
+    // or { kind: "dcr", clientMetadata } — deprecated (RFC 7591), application_type defaults to "native"
     redirectUri: "http://localhost:33418/callback",
     onRedirectRequired: (url) => openBrowser(url), // interactive flows
+    onInsufficientScope: "reauthorize", // or "throw" to surface SDK InsufficientScopeError instead
   },
   { serverUrl: "https://mcp.example.com/api", fetch },
 );
 ```
 
-The flow reuses the MCP SDK's `auth()` helper (401 → protected-resource metadata → RFC 8414 discovery → PKCE S256 → token exchange/refresh) wrapped in Prism policy: discovery URLs are SSRF-checked, https-only (loopback http opt-in), DNS-pinned, zero-redirect, and byte-bounded; RFC 8707 resource binding is enforced on every token request (`ERR_PRISM_MCP_OAUTH_AUDIENCE` on origin drift); issuer origin must match the discovered authorization server (`ERR_PRISM_MCP_OAUTH_ORIGIN`); bearer tokens are only ever attached to the allow-listed server origin. `McpClientAuthState` has no default implementation — production hosts back it with an encrypted/keychain store (refresh tokens must not live in plaintext persistence).
+The flow reuses the MCP SDK's `auth()` helper (401 → protected-resource metadata → RFC 8414 discovery → PKCE S256 → token exchange/refresh) wrapped in Prism policy: discovery URLs are SSRF-checked, https-only (loopback http opt-in), DNS-pinned, zero-redirect, and byte-bounded; RFC 8707 resource binding is enforced on every token request (`ERR_PRISM_MCP_OAUTH_AUDIENCE` on origin drift); issuer origin must match the discovered authorization server (`ERR_PRISM_MCP_OAUTH_ORIGIN`); bearer tokens are only ever attached to the allow-listed server origin.
+
+2026-07-28 authorization conformance (plan 063 task 5):
+
+- **Callback completion takes the full query**: `await auth.finishAuth(new URL(callbackUrl).searchParams)`. The persisted OAuth `state` is validated first (fail-closed `ERR_PRISM_MCP_OAUTH_STATE` when absent or mismatched), then the RFC 9207 `iss` parameter is checked against the persisted authorization server; the SDK independently validates `iss` against the recorded issuer (RFC 9207 §2.4) and the callback-leg AS binding (SEP-2352) before redeeming the code. Callback `error`/`error_description` fields are never surfaced after an issuer mismatch. A bare code string is accepted as the legacy form (no state/iss validation).
+- **Issuer-keyed credential storage**: persisted token/client records are SDK issuer-stamped (`StoredOAuthTokens`/`StoredOAuthClientInformation`); `McpClientAuthState` credential methods take the validated `issuer` so partitioned stores can key on it. Records stamped for a different issuer are never served, and ambiguous un-stamped pre-upgrade records are refused on issuer-keyed reads rather than guessed — re-authorization runs once and every persisted record is stamped thereafter.
+- **Registration strategy**: CIMD (SEP-991 URL-based client ids) is preferred, `static` remains supported, and `dcr` is deprecated; the DCR metadata defaults `application_type` to `"native"` when the host omits it.
+- **Insufficient-scope policy**: `onInsufficientScope: "reauthorize"` (default) runs the SDK's bounded step-up flow; `"throw"` surfaces the typed SDK `InsufficientScopeError` (with the challenge scope) instead of redirecting. Hosts gate interactive consent either way.
+
+`McpClientAuthState` has no default implementation — production hosts back it with an encrypted/keychain store (refresh tokens must not live in plaintext persistence).
 
 **Server** — advertise protected-resource metadata and challenge unauthenticated requests:
 
@@ -264,12 +286,22 @@ const handler = await createPrismMcpWebHandler(factory, {
 });
 ```
 
-The handler serves `GET /.well-known/oauth-protected-resource` and returns `401 WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"` on rejected requests. Token verification remains entirely host-owned via `resolveIdentity`; Prism only advertises and challenges.
+The handler serves `GET /.well-known/oauth-protected-resource` and returns `401 WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource", scope="<configured scopes>"` on rejected requests. Token verification remains entirely host-owned via `resolveIdentity` — the host token verifier must validate the token audience (`aud`) against the protected resource and enforce the challenged scopes; Prism only advertises and challenges.
 
 ## Vendor web MCP prototype boundary
 
 Official Exa/Firecrawl MCP servers may be tested only as explicit hardened prototypes: pin endpoint/origin/auth, inspect declared capabilities, allow-list individual tools/resources, retain all MCP bounds, and never expose generic remote passthrough. Production web research uses direct host-selected `@arnilo/prism-web-tools` adapters so provider choice, credentials, schema, and costs remain outside model control.
 
+## Real-client smoke (plans/064 Task 8)
+
+An operator-gated smoke drives `createPrismMcpServer` through the real `@modelcontextprotocol/client` SDK over a real stdio subprocess — the same shape a production MCP host uses:
+
+```bash
+PRISM_TEST_MCP_CLIENT=1 node scripts/mcp-client-smoke.mjs
+```
+
+The scenario stays sandboxed (read-only echo tool, authorize-gated denial, no policy bypass) and covers: modern auto + legacy handshakes, `tools/list` of registered capabilities, `tools/call` round-trip, the authorize gate enforced over the wire, and malformed-frame fail-closed (the transport tears the connection down instead of answering garbage). Server-initiated `elicitation/create` is a documented Prism boundary (`scripts/mcp-conformance-2026-baseline.yaml`); the bridge-side MRTR elicitation round-trip is covered over real HTTP by the package's modern-bridge tests. Registered in `scripts/live-matrix.json` as `mcp/client-smoke`.
+
 ## Related APIs
 
 - [Agent identity](agent-identity.md): optional verified identity on MCP authorize results
@@ -278,7 +310,6 @@ Official Exa/Firecrawl MCP servers may be tested only as explicit hardened proto
 - [Tool execution primitives](tool-execution-primitives.md): Plan 055 design and conformance matrix
 - [Host security guide](host-security.md): permission, trust, validation checklist
 - [Web-standard server handler](server.md): agent/workflow HTTP routes and shared remote-boundary rules
-- [Antigravity delegated agent](antigravity-agent.md): per-run loopback HTTP MCP server exposure for the official Antigravity CLI.
 - [ACP coding-host interop](acp.md): ACP clients may attach MCP servers to sessions — bounded configs (8/32 servers, 16 KiB/256 KiB config, 4 KiB/64 KiB header values), http/sse only when advertised, stdio accepted behind the gate, UNSTABLE `acp` always rejected, and every server approved by host `mcp.select` before the bridge connects.
 
 ## Testing

package/docs/middleware-hooks.md

@@ -101,7 +101,7 @@ export const extension: Extension = {
 - `retry` middleware may stop retrying or adjust delay, but runtime still owns retry event emission, abort-aware waiting, and provider-turn boundaries.
 - The registry does not discover packages, read manifests, load config, call providers, execute tools, read resources, or start sessions.
 - Hosts may pass a middleware registry into `createExtensionKernel({ middleware })` to share it with direct host code.
-- For OpenTelemetry export, prefer `session.subscribe()` + `@arnilo/prism-observability-opentelemetry` (see [Observability](observability.md)) rather than adding a parallel event bus. Middleware hooks remain for transforming payloads at named boundaries.
+- For OpenTelemetry export, prefer `session.subscribe()` + `@arnilo/prism-core/governance/observability` (see [Observability](observability.md)) rather than adding a parallel event bus. Middleware hooks remain for transforming payloads at named boundaries.
 
 ## Security and performance notes
 

package/docs/migrate-to-0.4.md

@@ -0,0 +1,312 @@
+# Migrate legacy 0.3 packages to Prism 0.4
+
+> **Status: 0.4 release draft.** Follow this guide only after the 0.4 packages are published.
+> Until then, stay on your current 0.3.x package set. This page is the permanent destination of
+> npm's legacy-package warnings.
+
+## What changes
+
+Prism 0.4 replaces 62 separate 0.3 package manifests with 10 active packages and explicit
+subpaths. The code and behavior move; this is not a database/data migration. It is a **package
+name and import-specifier migration**.
+
+- Existing applications pinned to 0.3.x continue to work.
+- Retired packages are not unpublished. Their final release remains on npm with its `latest`
+  tag and gains a `legacy` tag plus an install-time deprecation warning.
+- `npm install` cannot automatically replace one package name with another. Upgrade each package
+  dependency and its imports together.
+- There are no 0.4 compatibility wrappers. New packages never import old package names, so the
+  package graph cannot form a wrapper cycle.
+- `@arnilo/prism` stays small and dependency-free. Runtime, sessions, governance, and optional
+  drivers live in `@arnilo/prism-core`, not root-package subpaths.
+
+## Before you start
+
+1. Commit or lock your working 0.3.x application.
+2. Record installed Prism packages and direct imports:
+
+   ```bash
+   npm ls --all @arnilo/prism @arnilo/prism-*
+   rg -n 'from "@arnilo/prism|import\("@arnilo/prism' src test
+   ```
+
+3. Classify each package using the tables below. Leave unchanged interop packages in place.
+4. Upgrade package dependencies and imports in one pull request; then run your normal typecheck,
+   tests, and packed-install smoke test.
+5. Add optional peers only for subpaths you use. Do not add a database, browser, parser, or host
+   binary merely because a family package is installed.
+
+## Active 0.4 packages
+
+| Package | Use it for |
+|---|---|
+| `@arnilo/prism` | Contracts, agent APIs, CLI, root `node/*` and `testing/*` exports. |
+| `@arnilo/prism-core` | Runtime, sessions, governance, credentials, persistence, work integration, JSON Schema validation. |
+| `@arnilo/prism-providers` | All first-party provider adapters as explicit subpaths. |
+| `@arnilo/prism-coding-tools` | Coding agent/security, document reader, OpenAPI, desktop control, Dev inspector, Caveman, Ponytail, Impeccable. |
+| `@arnilo/prism-web-tools` | Generic web tools plus browser and Obscura subpaths. |
+| `@arnilo/prism-memory` | Memory, RAG, compaction, Graft, Wiki. |
+| `@arnilo/prism-office` | Documents, sheets, and diagrams. |
+| `@arnilo/prism-mcp` | MCP interop. |
+| `@arnilo/prism-acp-agent` | ACP interop. |
+| `@arnilo/prism-ag-ui` | AG-UI/A2A/A2UI interop. |
+
+`@arnilo/prism-antigravity-agent` has no 0.4 successor. Remove it and keep delegated CLI execution in the host, composed through generic process, tool, MCP, or A2A contracts as needed.
+
+## Package and import mapping
+
+Replace the package name in `package.json` and every corresponding source import. The tables map
+root package entrypoints. Any documented non-root entrypoint keeps its feature suffix under the
+new family path; the 0.4 API page for that family is authoritative for exact nested exports.
+
+### Providers
+
+Install `@arnilo/prism-providers` once, then import only the provider subpath used by the host.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-provider-ai-sdk` | `@arnilo/prism-providers/ai-sdk` |
+| `@arnilo/prism-provider-alibaba` | `@arnilo/prism-providers/alibaba` |
+| `@arnilo/prism-provider-anthropic` | `@arnilo/prism-providers/anthropic` |
+| `@arnilo/prism-provider-azure` | `@arnilo/prism-providers/azure` |
+| `@arnilo/prism-provider-bedrock` | `@arnilo/prism-providers/bedrock` |
+| `@arnilo/prism-provider-clinepass` | `@arnilo/prism-providers/clinepass` |
+| `@arnilo/prism-provider-deepseek` | `@arnilo/prism-providers/deepseek` |
+| `@arnilo/prism-provider-google` | `@arnilo/prism-providers/google` |
+| `@arnilo/prism-provider-kimi` | `@arnilo/prism-providers/kimi` |
+| `@arnilo/prism-provider-neuralwatt` | `@arnilo/prism-providers/neuralwatt` |
+| `@arnilo/prism-provider-ollama` | `@arnilo/prism-providers/ollama` |
+| `@arnilo/prism-provider-openai` | `@arnilo/prism-providers/openai` |
+| `@arnilo/prism-provider-opencode-go` | `@arnilo/prism-providers/opencode-go` |
+| `@arnilo/prism-provider-openrouter` | `@arnilo/prism-providers/openrouter` |
+| `@arnilo/prism-provider-vertex` | `@arnilo/prism-providers/vertex` |
+| `@arnilo/prism-provider-xai` | `@arnilo/prism-providers/xai` |
+| `@arnilo/prism-provider-zai` | `@arnilo/prism-providers/zai` |
+
+```ts
+// Before
+import * as openai from "@arnilo/prism-provider-openai";
+
+// After
+import * as openai from "@arnilo/prism-providers/openai";
+```
+
+### Runtime, sessions, governance, and work integration
+
+Install `@arnilo/prism-core`, then choose the specific subpath. This family does not add
+optional drivers to your host automatically.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-server` | `@arnilo/prism-core/runtime/server` |
+| `@arnilo/prism-supervisor` | `@arnilo/prism-core/runtime/supervisor` |
+| `@arnilo/prism-workflows` | `@arnilo/prism-core/runtime/workflows` |
+| `@arnilo/prism-session-store-codecs` | `@arnilo/prism-core/sessions/codecs` |
+| `@arnilo/prism-session-store-nats` | `@arnilo/prism-core/sessions/nats` |
+| `@arnilo/prism-session-store-postgres` | `@arnilo/prism-core/sessions/postgres` |
+| `@arnilo/prism-session-store-sqlite` | `@arnilo/prism-core/sessions/sqlite` |
+| `@arnilo/prism-policy` | `@arnilo/prism-core/governance/policy` |
+| `@arnilo/prism-evals` | `@arnilo/prism-core/governance/evals` |
+| `@arnilo/prism-prompts` | `@arnilo/prism-core/governance/prompts` |
+| `@arnilo/prism-model-router` | `@arnilo/prism-core/governance/model-router` |
+| `@arnilo/prism-observability-opentelemetry` | `@arnilo/prism-core/governance/observability` |
+| `@arnilo/prism-credentials-node` | `@arnilo/prism-core/credentials/node` |
+| `@arnilo/prism-enterprise-postgres` | `@arnilo/prism-core/enterprise/postgres` |
+| `@arnilo/prism-work-tools` | `@arnilo/prism-core/integrations/work` |
+| `@arnilo/prism-tool-validator-json-schema` | `@arnilo/prism-core/validation/json-schema` |
+
+`work-tools` belongs to core because enterprise Postgres composes its work-idempotency store.
+It is not part of coding tools.
+
+### Coding tools and personas
+
+Install `@arnilo/prism-coding-tools`; import the smallest needed subpath. The `prism-dev` binary
+continues to be named `prism-dev` after migration.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-coding-agent` | `@arnilo/prism-coding-tools/agent` |
+| `@arnilo/prism-coding-security` | `@arnilo/prism-coding-tools/security` |
+| `@arnilo/prism-document-reader` | `@arnilo/prism-coding-tools/document-reader` |
+| `@arnilo/prism-openapi-tools` | `@arnilo/prism-coding-tools/openapi` |
+| `@arnilo/prism-computer-use-linux` | `@arnilo/prism-coding-tools/computer-use-linux` |
+| `@arnilo/prism-dev` | `@arnilo/prism-coding-tools/dev` |
+| `@arnilo/prism-caveman` | `@arnilo/prism-coding-tools/caveman` |
+| `@arnilo/prism-ponytail` | `@arnilo/prism-coding-tools/ponytail` |
+| `@arnilo/prism-impeccable` | `@arnilo/prism-coding-tools/impeccable` |
+
+### Web, browser, and Obscura
+
+`@arnilo/prism-web-tools` keeps its root entrypoint for generic research tools. Browser and
+Obscura become explicit subpaths; neither activates a browser or process on import.
+
+| Legacy 0.3 package | 0.4 import |
+|---|---|
+| `@arnilo/prism-browser` | `@arnilo/prism-web-tools/browser` |
+| `@arnilo/prism-obscura` | `@arnilo/prism-web-tools/obscura` |
+
+### Memory, RAG, compaction, and context
+
+`@arnilo/prism-memory` retains its root memory entrypoint and gains explicit subpaths. The
+`prism-wiki` binary remains named `prism-wiki` and continues to ship Wiki skills.
+
+| Legacy 0.3 package | 0.4 import or install |
+|---|---|
+| `@arnilo/prism-rag` | `@arnilo/prism-memory/rag` |
+| `@arnilo/prism-compaction-llm` | `@arnilo/prism-memory/compaction/llm` |
+| `@arnilo/prism-compaction-observational-memory` | `@arnilo/prism-memory/compaction/observational-memory` |
+| `@arnilo/prism-graft` | `@arnilo/prism-memory/graft` |
+| `@arnilo/prism-wiki` | `@arnilo/prism-memory/wiki` |
+| `@arnilo/prism-compaction` | Install `@arnilo/prism-memory`; choose one or both compaction subpaths. No direct import replacement: it was a profile-only manifest. |
+
+### Office suite
+
+Plans 051–053 drafted three separate packages. They were never published to npm.
+Install `@arnilo/prism-office` and import the subpath:
+
+| Draft 0.3 name | 0.4 import |
+|---|---|
+| `@arnilo/prism-documents` | `@arnilo/prism-office/documents` |
+| `@arnilo/prism-sheets` | `@arnilo/prism-office/sheets` |
+| `@arnilo/prism-diagrams` | `@arnilo/prism-office/diagrams` |
+
+```ts
+import { generateDocument } from "@arnilo/prism-office/documents";
+import { parseCsv } from "@arnilo/prism-office/sheets";
+```
+
+`@office-open/{docx,xlsx,pptx,xml}` are exact-pinned regular dependencies of the
+office tarball. The diagrams live-embed optionally peers `playwright-core`; XML
+canonicalization does not.
+
+### Removed profile packages
+
+Profiles were dependency lists, not runtime APIs. Choose the families your host uses; do not look
+for a 0.4 profile replacement package.
+
+| Legacy 0.3 profile | 0.4 starting recipe |
+|---|---|
+| `@arnilo/prism-base` | `npm i @arnilo/prism@^0.4.0 @arnilo/prism-core@^0.4.0 @arnilo/prism-memory@^0.4.0` |
+| `@arnilo/prism-code` | Base recipe + `@arnilo/prism-coding-tools@^0.4.0 @arnilo/prism-mcp@^0.4.0` |
+| `@arnilo/prism-sdk` | Base recipe + `@arnilo/prism-mcp@^0.4.0`; Core contains credentials, observability, and workflows. |
+| `@arnilo/prism-all` | Select required families explicitly. Begin with Core, Providers, Coding tools, Web tools, Memory, and required interop; add Office only if needed. |
+
+### Names that remain
+
+These package names remain valid. Review their imports if they now consume one of the new family
+subpaths, but do not rename the dependency merely because of 0.4.
+
+| Package | 0.4 status |
+|---|---|
+| `@arnilo/prism` | Unchanged root package; remains dependency-free. |
+| `@arnilo/prism-providers` | Same name, now code family; provider imports use `/provider-name`. |
+| `@arnilo/prism-web-tools` | Same name; root web tools unchanged, browser/Obscura use subpaths. |
+| `@arnilo/prism-memory` | Same name; RAG/compaction/Graft/Wiki use subpaths. |
+| `@arnilo/prism-mcp` | Unchanged interop package. |
+| `@arnilo/prism-acp-agent` | Unchanged interop package. |
+| `@arnilo/prism-ag-ui` | Unchanged interop package. |
+
+## Optional peers, host binaries, and trust boundaries
+
+Installing a family does not install or activate its optional capabilities. Add the peer only for
+the subpath you use and preserve its existing host policy.
+
+| Feature | Required host dependency / action | Do not weaken |
+|---|---|---|
+| SQLite sessions or prompt store | Install `better-sqlite3`; use only the selected `prism-core` session/governance subpath. | Database ownership, migration checks, and file permissions. |
+| PostgreSQL sessions, prompts, or enterprise state | Install `pg`; use the selected `prism-core` subpath. | TLS, roles, checksummed migrations, and tenant boundaries. |
+| NATS sessions | Install/configure the NATS client required by the sessions NATS subpath. | Stream/consumer ownership and durable cursor isolation. |
+| Browser tools | Install `playwright-core` and provide the approved host browser/context. | Egress, upload/download, screenshot, and side-effect policies. |
+| Obscura | Install/configure `playwright-core`, `@arnilo/prism-mcp`, and an approved host Obscura binary. | Absolute shell-free command, SSRF controls, process limits, MCP authorization. |
+| Document reader | Install `mammoth` and/or `pdf-parse` for used formats. | Magic-byte format gating, input/page/text caps, and no embedded-content execution. |
+| Graft | Install/configure `@nanonets/graft` or approved host CLI. | Workspace confinement, output/time limits, and no implicit process start. |
+| Wiki | Provide the documented host `qmd`/Context7 setup when using Wiki commands. | Workspace path, process, and untrusted-content limits. |
+| Computer Use Linux | Provide the approved `computer-use-linux` MCP host binary. | Consent, sandbox, approval, serialized input, and redaction. |
+
+## Recommended upgrade sequence
+
+1. **Move root/version first.** Set `@arnilo/prism` to `^0.4.0`; retain the Node version required
+   by the release.
+2. **Replace retired dependency names.** Use the appropriate family package in `package.json`.
+3. **Replace imports.** Apply the tables above. Do not keep both old and new imports in the same
+   runtime path.
+4. **Add only needed peers.** Follow the previous table; subpath import failures should name the
+   missing peer rather than fall back to an unsafe implementation.
+5. **Recheck host wiring.** Re-register tools/providers/extensions explicitly. Package install
+   remains inert; it must not activate providers, listeners, database connections, browsers,
+   credentials, or tools.
+6. **Run verification.**
+
+   ```bash
+   npm run typecheck
+   npm test
+   npm pack --dry-run
+   ```
+
+   Run protected PostgreSQL, browser, Obscura, MCP, or host-binary checks separately when your
+   application uses those integrations.
+
+## Legacy warning and lifecycle
+
+Each retired package's final 0.3 release is marked with npm's `legacy` dist-tag and a deprecation
+warning like:
+
+```text
+npm warn deprecated @arnilo/prism-browser@0.3.x:
+Legacy 0.3 package. Prism 0.4+: @arnilo/prism-web-tools/browser.
+https://github.com/ashiqrniloy/prism/blob/main/docs/migrate-to-0.4.md#web-browser-and-obscura
+```
+
+The warning is informational: it does not delete the package or rewrite your dependency. `latest`
+continues to point at the final 0.3 release because npm dist-tags cannot redirect one package name
+to a different package. New 0.4 development must use the successor listed above.
+
+The markers are generated and applied from one reviewed registry plan — never hand-copied. Run
+`node scripts/phase54-legacy-registry.mjs --dry-run` to resolve every retired name's final
+published version, verify the anchors above exist in this guide, and print the exact
+`npm dist-tag add ... legacy` and `npm deprecate ..."<0.4.0"` commands without mutating the
+registry. After the 0.4 packages and this guide are public (Task 9 cutover),
+`node scripts/phase54-legacy-registry.mjs --apply --confirm` pre-flights every entry and fails
+closed — zero mutations — on any mismatch, then applies the tags and warnings idempotently:
+already-correct entries are skipped on resume, and per-entry status is written to
+`release-artifacts/legacy-registry-plan.json` for safe resume. Two retired names
+(`@arnilo/prism-prompts`, `@arnilo/prism-dev`) were never published; they are recorded in the
+plan with no registry action.
+
+## Rollback
+
+If the 0.4 migration fails before deployment:
+
+1. Restore the committed 0.3.x `package.json` and lockfile.
+2. Restore old imports from the mapping table.
+3. Reinstall with the lockfile (`npm ci`).
+4. Do not unpublish any package or remove the `legacy` marker; those are registry metadata, not a
+   runtime migration.
+
+The package reorganization itself does not change persisted store schemas. If the same deployment
+also adopted a separate database/session feature release, follow that feature's migration and
+rollback instructions; do not assume package rollback reverses a forward-only database migration.
+
+## FAQ
+
+**Can I install `@arnilo/prism-all` in 0.4?** No. It was a pure manifest and is retired. Install
+only the family packages your host needs.
+
+**Why is `@arnilo/prism-core` separate from `@arnilo/prism`?** Root Prism remains dependency-free.
+Database drivers, optional Node integrations, and governance/runtime modules must not become
+implicit root dependencies.
+
+**Why not keep old packages as wrappers?** Wrappers preserve 54 active manifests and create a
+cycle if a new family imports the old implementation while the old package re-exports the family.
+The direct migration is smaller and unambiguous.
+
+**Do unchanged interop packages need changes?** No package-name change. Keep MCP, ACP, AG-UI, or
+Antigravity installed only when your host uses that protocol; update imports only if their own 0.4
+API page says so.
+
+## Related APIs
+
+- [Release and install](release-and-install.md): package contents, peer rules, and publication.
+- [Migration guide](migration.md): migration history for prior releases.
+- [Provider packages](provider-packages.md): provider adapter behavior.
+- [Host security guide](host-security.md): preserve host trust boundaries while upgrading.