@arnilo/prism 0.3.2 → 0.4.0

package/docs/index.md

@@ -10,7 +10,9 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - **Coding/ACP closeouts**: `read.findText`, visible fuzzy edit outcomes and miss context, ACP editor-buffer operations, per-session spawnable coding registries, and delete/move projections.
 
 ## Public contracts
-- [Public contracts](public-contracts.md): type shapes for messages, agents, tools, stores, generic `CheckpointStore`, atomic `LeaseStore`, bounded single-consumer `EventMultiplexer`, resources, credentials, and events.
+- [Public contracts](public-contracts.md):
+- [Coding tools, sandboxing, and personas](coding-tools.md): `@arnilo/prism-coding-tools` family package subpaths for coding tools (`/agent`), security sandboxing (`/security`), document reading (`/document-reader`), OpenAPI (`/openapi`), Linux desktop (`/computer-use-linux`), Dev inspector (`/dev`), and personas (`/caveman`, `/ponytail`, `/impeccable`). type shapes for messages, agents, tools, stores, generic `CheckpointStore`, atomic `LeaseStore`, bounded single-consumer `EventMultiplexer`, resources, credentials, and events.
+- [Core runtime, sessions, and governance](core.md): `@arnilo/prism-core` family package subpaths for runtime (`/runtime/{server,supervisor,workflows}`), sessions (`/sessions/{codecs,sqlite,postgres,nats}`), governance (`/governance/{policy,evals,prompts,model-router,observability}`), credentials (`/credentials/node`), enterprise PostgreSQL persistence (`/enterprise/postgres`), and integrations (`/integrations/work`, `/validation/json-schema`).
 
 ## Identity and governance
 - [Agent identity](agent-identity.md): host-verified `Principal` / `AgentIdentity`, delegation narrowing, ownership projection, and redacted telemetry refs for enterprise runs/tools/MCP/A2A/workflows; optional OIDC/JWKS verifier adapter (`@arnilo/prism-credentials-node/oidc` — pinned issuer/audience/JWKS, bounded claims, fail closed).
@@ -28,16 +30,16 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Operations runbook](operations.md): the high-availability/failover runbook for plan 027 Task 6 — LeaseStore/CheckpointStore fencing model, local-registry limitations, uncertain-commit replay rules, the recorded two-replica drill (`scripts/phase27-ha.test.mjs`, evidence in `docs/_evidence/phase27-ha-evidence.json`), failover ceiling, and the prohibition on manual lease unlocks.
 - [Disaster recovery and backup operations](disaster-recovery.md): the plan 027 Task 7 runbook — standard-tool backup/restore/migration-rollback/PITR/DR drill (`scripts/phase27-dr.test.mjs`), guarded commands, app-level verification, the rollback decision tree, and measured RPO/RTO in `docs/_evidence/phase27-dr-evidence.json`.
 - [Data classification and field-level redaction](data-classification.md): the plan 027 Task 8 contract — `applyFieldPolicy` walking JSON-like values with allow/redact/tokenize/deny decisions, the fail-closed protected default, per-boundary `labelFor` hints (no auto-discovery), sparse-copy overhead, and the ERP-T9 leak matrix incl. egress/audit/telemetry seams.
-- [Evaluations](evaluations.md): deterministic and bounded trace/model-judge/pairwise scoring, CI thresholds, OTel trace-reference linkage, coding/browser adversarial fixtures, ID-only linkage to immutable owned run feedback, and optional durable PostgreSQL records.
+- [Evaluations](evaluations.md): deterministic and bounded trace/model-judge/pairwise scoring, CI thresholds, OTel trace-reference linkage, coding/browser adversarial fixtures, ID-only linkage to immutable owned run feedback, optional durable PostgreSQL records, and trace-to-dataset curation of production runs.
 - [Runs and usage ledger](runs-and-usage.md): durable run/event/tool/usage persistence, optional bounded FIFO durability policies, session snapshot caching, and immutable run/trace feedback.
 - [Performance limits](performance.md): **0.1.0 capacity envelopes** (frozen performance contract, 24 network-free + 16 protected p95 rows, startup/pack rows), 0.0.26 coding-intelligence/process/forge/egress network-free evidence, 0.0.25 durable-loop/HITL/A2UI network-free evidence, 0.0.24 distributed event/effect PostgreSQL evidence, 0.0.23 enterprise state evidence, 0.0.15 network-free provider/RAG/memory benchmark evidence and frozen caps, bounded evaluation traces/judges/reports, and production sizing assumptions.
 - [Structured output](structured-output.md): the `Artifact*` seam plus provider-native `StructuredOutputOptions` / `structuredOutputMode` for capable models.
 
 ## Compaction/session memory
 - [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies. Task-boundary `session.compact()` fails closed during an active run (`Error("Agent session already has an active run")`).
-- [LLM compaction package](compaction-llm.md): optional provider-backed strategy with finite summary/reserve/error caps, bounded redacted streaming retention, mandatory finite post-policy `model.parameters.maxTokens`, and `createCodingCompactionStrategy()` for coding handoff focus.
-- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory with explicit `attach()` lifecycle — **Recent exact messages**, **Observation log**, **Reflections**, **Raw-source retrieval** (exact-id recall + cursor paging); dual coverage, **nested-only settings** (pre-0.0.19 flat keys and top-level `workerProvider`/`workerModel` aliases removed in 0.1.5; removed keys fail closed naming the nested replacement), branch-isolated `appendEntry`, secrets redaction, inert import/extension, and an opt-in cross-session recall pattern (host-composed store funnel; default remains per-session).
-- [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` working-memory store, semantic recall, finite Embedder/VectorStore contracts (incl. embedder identity + generation pointers), PostgreSQL/pgvector path (`createPostgresVectorStore` standalone, HNSW/fts DDL on the host knowledge database), consent lifecycle, identity-bound redacted export, and resumable bounded rebuild.
+- [LLM compaction subpath](compaction-llm.md): optional provider-backed strategy with finite summary/reserve/error caps, bounded redacted streaming retention, mandatory finite post-policy `model.parameters.maxTokens`, and `createCodingCompactionStrategy()` for coding handoff focus.
+- [Observational memory compaction subpath](compaction-observational-memory.md): optional source-backed memory with explicit `attach()` lifecycle — **Recent exact messages**, **Observation log**, **Reflections**, **Raw-source retrieval** (exact-id recall + cursor paging); dual coverage, **nested-only settings** (pre-0.0.19 flat keys and top-level `workerProvider`/`workerModel` aliases removed in 0.1.5; removed keys fail closed naming the nested replacement), branch-isolated `appendEntry`, secrets redaction, inert import/extension, and an opt-in cross-session recall pattern (host-composed store funnel; default remains per-session).
+- [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` working-memory store, semantic recall with opt-in composite recency/importance scoring (sum-normalized weights, component-exposing hits), finite Embedder/VectorStore contracts (incl. embedder identity + generation pointers), PostgreSQL/pgvector path (`createPostgresVectorStore` standalone, HNSW/fts DDL on the host knowledge database), consent lifecycle, identity-bound redacted export, and resumable bounded rebuild.
 - [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`, optional bounded `searchSessions` / `SessionIndex` (memory linear|unsupported), and dev-vs-production branch reads — start here for session persistence.
 - [Conversations](conversations.md): durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) on session + event-ledger seams, thread-bound reconnectable replay, frozen caps, atomic metadata via version/CAS (`metadata_conflict` on stale writes), and legal-hold-aware deletion.
 - [Work artifacts and review](work-artifacts-and-review.md): durable artifact co-work review — authorized attach (MIME/hash/version, producer run, citations, preview metadata), revision compare, approve/reject with last-validated recovery, and authorized expiring delivery links; records persist as versioned checkpoints, never file bodies. 0.0.28 adds the core `ArtifactBodyStore` contract (put/get/delete/presign by opaque ownership-scoped ref, hash/size/MIME verification, legal-hold-aware idempotent delete) and the reference `@arnilo/prism-server/artifact-bodies` S3-compatible adapter (hand-rolled SigV4, native fetch + WebCrypto, optional host KMS callback); delivery links resolve through `bodies.presign` when wired.
@@ -58,10 +60,10 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Thinking and reasoning](thinking-and-reasoning.md): portable `ThinkingLevel` helpers (`applyThinkingLevel` / `thinkingCompatFor`) map per-turn effort into provider `compat` fields; model defaults stay on `ModelConfig.compat`; no second options tree.
 - [Use-case model selection](use-case-model-selection.md): bind `{ model?, provider?, thinkingLevel? }` for observational memory, LLM compaction, and other non-session LLM jobs with explicit session-model fallback via `resolveUseCaseModel`.
 - [Provider request policies](provider-request-policies.md): chain `ProviderRequestPolicy` hooks, use `createSessionCachePolicy`, and merge legacy/structured cache options safely.
-- [Provider packages](provider-packages.md): define explicit provider packages, model metadata, auth descriptors, request/cache policies, provider-owned header precedence, the provider-authorized OAuth matrix, and the Phase 10 first-party compatibility matrix without package discovery or provider-specific core behavior; includes a cache behavior summary and **caller-gated on-demand model discovery** (`list*Models`, setup zero-fetch).
-  - Phase 12 package workspaces: [`@arnilo/prism-provider-openai`](providers/openai.md) (Responses hosted-tool attribution, bounded continuation, Realtime session seam), [`@arnilo/prism-provider-anthropic`](providers/anthropic.md) (native Messages, `cache_control`, thinking, caller-gated `listAnthropicModels`), [`@arnilo/prism-provider-google`](providers/google.md) (native Gemini `generateContent` SSE, caller-gated `listGoogleModels`), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md) (official Go open models, dual-route Anthropic/OpenAI, caller-gated `listOpenCodeGoModels`, `reasoning_content`/thinking preserve), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md) (app-controlled catalog, caller-gated `listOpenRouterModels`, `reasoning` merge/preserve, `cache_control` + sticky `session_id`), [`@arnilo/prism-provider-zai`](providers/zai.md) (official `thinking`/`reasoning_effort`/`tool_stream`, implicit cache, caller-gated `listZaiModels`), [`@arnilo/prism-provider-deepseek`](providers/deepseek.md) (official `thinking` + `reasoning_effort`, implicit prefix cache, caller-gated `listDeepSeekModels`), [`@arnilo/prism-provider-xai`](providers/xai.md) (Grok Completions, `x-grok-conv-id`, SuperGrok device-code OAuth, caller-gated `listXaiModels`), [`@arnilo/prism-provider-clinepass`](providers/clinepass.md) (stream-only `cline-pass/*` catalog, implicit cache, no WorkOS), [`@arnilo/prism-provider-kimi`](providers/kimi.md), [`@arnilo/prism-provider-alibaba`](providers/alibaba.md) (Alibaba Cloud Model Studio / DashScope + Coding Plan, OpenAI-compatible, caller-gated `listAlibabaModels`, implicit + explicit `cache_control` caching, Qwen `enable_thinking`), [`@arnilo/prism-provider-ollama`](providers/ollama.md) (Ollama Cloud + local, OpenAI-compatible, caller-gated `listOllamaModels`, implicit-only caching, `reasoning_effort`), and [`@arnilo/prism-provider-neuralwatt`](providers/neuralwatt.md) with implicit vLLM prefix caching, reasoning controls (`reasoning_effort`/`thinking_token_budget`/`enable_thinking`/`preserve_thinking`/`clear_thinking`), reasoning preservation, OpenAI-style tool-call loop, quota, telemetry, and retry classification helpers.
-  - Phase 8 enterprise cloud (workload identity; separate from consumer Anthropic/Google): [`@arnilo/prism-provider-azure`](providers/azure.md) (Entra / Foundry, credential once per request), [`@arnilo/prism-provider-bedrock`](providers/bedrock.md) (IAM/IRSA + region/PrivateLink, duplicate-case-safe SigV4 signing), [`@arnilo/prism-provider-vertex`](providers/vertex.md) (ADC / Vertex OpenAPI, credential once per request).
-  - Optional AI SDK adapter: [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md) maps host-owned pinned `LanguageModelV4` models onto Prism `AIProvider` streams (offline-tested `@ai-sdk/provider` version matrix; no Prism catalog; maps metadata/tool authority/`finish.usage` cache tokens; reasoning is host-model-owned).
+- [Provider packages](provider-packages.md): all 17 first-party adapters ship as `@arnilo/prism-providers/<adapter>` subpaths (importing one adapter never evaluates another); define explicit provider packages, model metadata, auth descriptors, request/cache policies, provider-owned header precedence, the provider-authorized OAuth matrix, and the Phase 10 first-party compatibility matrix without package discovery or provider-specific core behavior; includes a cache behavior summary and **caller-gated on-demand model discovery** (`list*Models`, setup zero-fetch).
+  - Phase 12 package workspaces: [`@arnilo/prism-providers/openai`](providers/openai.md) (Responses hosted-tool attribution, bounded continuation, Realtime session seam), [`@arnilo/prism-providers/anthropic`](providers/anthropic.md) (native Messages, `cache_control`, thinking, caller-gated `listAnthropicModels`), [`@arnilo/prism-providers/google`](providers/google.md) (native Gemini `generateContent` SSE, caller-gated `listGoogleModels`), [`@arnilo/prism-providers/opencode-go`](providers/opencode-go.md) (official Go open models, dual-route Anthropic/OpenAI, caller-gated `listOpenCodeGoModels`, `reasoning_content`/thinking preserve), [`@arnilo/prism-providers/openrouter`](providers/openrouter.md) (app-controlled catalog, caller-gated `listOpenRouterModels`, `reasoning` merge/preserve, `cache_control` + sticky `session_id`), [`@arnilo/prism-providers/zai`](providers/zai.md) (official `thinking`/`reasoning_effort`/`tool_stream`, implicit cache, caller-gated `listZaiModels`), [`@arnilo/prism-providers/deepseek`](providers/deepseek.md) (official `thinking` + `reasoning_effort`, implicit prefix cache, caller-gated `listDeepSeekModels`), [`@arnilo/prism-providers/xai`](providers/xai.md) (Grok Completions, `x-grok-conv-id`, SuperGrok device-code OAuth, caller-gated `listXaiModels`), [`@arnilo/prism-providers/clinepass`](providers/clinepass.md) (stream-only `cline-pass/*` catalog, implicit cache, no WorkOS), [`@arnilo/prism-providers/kimi`](providers/kimi.md), [`@arnilo/prism-providers/alibaba`](providers/alibaba.md) (Alibaba Cloud Model Studio / DashScope + Coding Plan, OpenAI-compatible, caller-gated `listAlibabaModels`, implicit + explicit `cache_control` caching, Qwen `enable_thinking`), [`@arnilo/prism-providers/ollama`](providers/ollama.md) (Ollama Cloud + local, OpenAI-compatible, caller-gated `listOllamaModels`, implicit-only caching, `reasoning_effort`), and [`@arnilo/prism-providers/neuralwatt`](providers/neuralwatt.md) with implicit vLLM prefix caching, reasoning controls (`reasoning_effort`/`thinking_token_budget`/`enable_thinking`/`preserve_thinking`/`clear_thinking`), reasoning preservation, OpenAI-style tool-call loop, quota, telemetry, and retry classification helpers.
+  - Phase 8 enterprise cloud (workload identity; separate from consumer Anthropic/Google): [`@arnilo/prism-providers/azure`](providers/azure.md) (Entra / Foundry, credential once per request), [`@arnilo/prism-providers/bedrock`](providers/bedrock.md) (IAM/IRSA + region/PrivateLink, duplicate-case-safe SigV4 signing), [`@arnilo/prism-providers/vertex`](providers/vertex.md) (ADC / Vertex OpenAPI, credential once per request).
+  - Optional AI SDK adapter: [`@arnilo/prism-providers/ai-sdk`](providers/ai-sdk.md) maps host-owned pinned `LanguageModelV4` models onto Prism `AIProvider` streams (offline-tested `@ai-sdk/provider` version matrix; no Prism catalog; maps metadata/tool authority/`finish.usage` cache tokens; reasoning is host-model-owned).
 - [OpenAI-compatible provider](providers/openai-compatible.md): optional provider subpath using native or injected `fetch` for Chat Completions streaming (`chatCompletionsUrl` / `authStyle` overrides for enterprise adapters; `buildBodyExtra` / `mapMessages` / `mapUsage` / `extraHeaders` hooks for vendor variants; **strict completion is the shared default** — streams ending without `[DONE]` + `finish_reason` fail closed instead of emitting a successful `done`, with explicit `strictCompletion: false` as the documented opt-out).
 
 ## Input, prompt, and context assembly
@@ -69,31 +71,37 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders, provider-input assembly, cache-aware default order, opt-in legacy ordering, and optional `contextBudget` eviction + omission reports. Audio/file/document `ContentBlock` types and capability checks are documented there.
 - [Multimodal content](multimodal-content.md): complete-request media resolution and aggregate bounds, DNS-classified/address-pinned URLs, SSRF/MIME policy, `ModelCapabilities.input` tags, and first-party content-type mapping; 0.2.1 routes media URL fetches through the core DNS-pinned fetch primitive.
 - [System prompts](system-prompts.md): compose explicit user/package/app/run system prompt layers, auto-load the standard `AGENTS.md` (workspace) / `SYSTEM.md` prompt files via the Node `loadSystemPromptFiles` loader (trust-gated for `AGENTS.md`), and append `SYSTEM.md` → per-agent `AGENT.md` body → repo `AGENTS.md` layers from a discovered agent bundle via `resolveAgentBundle`.
+- [Versioned prompt registry](prompt-registry.md): optional `@arnilo/prism-prompts` immutable, content-hashed prompt assets with memory, SQLite, and PostgreSQL stores, exact ownership scoping, bounded cursor listing/diff, and no implicit system-prompt activation.
 - [Instruction injection](instruction-injection.md): register package injectors that layer redacted instructions/context blocks without granting tools, permissions, or resource escapes.
 - [Context and skills](context-and-skills.md): resolve ordered context providers; progressive skill catalog (`skillsDisclosure`, default catalog-only), `load_skill` on-demand bodies, fail-closed registry activation (`activateAllSkills` migration opt-in), `toolNames` fail closed before provider turns, priority-aware budget demotion, and optional `toolResultFold`.
-- [LLM Wiki](wiki.md): optional `@arnilo/prism-wiki` automated Karpathy-style knowledge compiler that emits OKF v0.2 bundles (GoogleCloudPlatform/open-knowledge-format), incremental Merkle change tracking, on-device `qmd` hybrid search, and Context7-style clickable line navigation for codebases and PKM.
-- [Retrieval-augmented generation](rag.md): optional bounded source lifecycle, document adapters, ATX heading-stack chunk metadata, hybrid vector+lexical retrieval with RRF fusion, multi-scope retrieve (one embed / one RRF / one rerank), embedder-identity drift guards, content-hash skip, generation visibility, host reranking, ingestion status (plus an in-cluster TEI adapter), attributable citations, telemetry seam, and inert context injection.
+- [LLM Wiki](wiki.md): optional `@arnilo/prism-memory/wiki` automated Karpathy-style knowledge compiler that emits OKF v0.2 bundles (GoogleCloudPlatform/open-knowledge-format), incremental Merkle change tracking, on-device `qmd` hybrid search, and Context7-style clickable line navigation for codebases and PKM.
+- [Retrieval-augmented generation](rag.md): optional `@arnilo/prism-memory/rag` bounded source lifecycle, document adapters, ATX heading-stack chunk metadata, hybrid vector+lexical retrieval with RRF fusion, multi-scope retrieve (one embed / one RRF / one rerank), embedder-identity drift guards, content-hash skip, generation visibility, host reranking, ingestion status (plus an in-cluster TEI adapter), attributable citations, telemetry seam, and inert context injection.
 
 ## Tools
 - [Recoverable tool effects](tool-effects.md): optional effect declarations, `ToolEffectStore` claim/CAS, unknown reconciliation (not exactly-once), and adapter classifications.
-- [Tools](tools.md): register host-owned active tools with replace-or-error duplicate policy, apply exact allow/deny filtering, dispatch normal or opt-in bounded artifact-loop calls, and optionally bound untrusted JSON Schema compilation.
+- [Tools](tools.md): register host-owned active tools with replace-or-error duplicate policy, apply exact allow/deny filtering, dispatch normal or opt-in bounded artifact-loop calls, optionally bound untrusted JSON Schema compilation, and opt-in progressive tool loading (`toolsDisclosure: "search"` — bounded top-k disclosure plus the generated `search_tools` activation tool).
 - [OpenAPI tools adapter](openapi-tools.md): optional `@arnilo/prism-openapi-tools` `createOpenApiTools` — compile host-selected OpenAPI 3.1 operationIds into bounded `ToolDefinition`s (allow-list only, pinned origin, resolved/bounded schemas, approval + effect-store idempotency on mutations, bounded body/response/retries/pagination, host credential resolver, untrusted output).
 - [Tool execution primitives](tool-execution-primitives.md): finite JSON Schema LRU validation, exclusive-aware bounded parallel dispatch, MCP bridge mapping, coding execution policy, and image-read bounds.
-- [Tool validator JSON Schema package](../packages/tool-validator-json-schema/README.md): optional `@arnilo/prism-tool-validator-json-schema` adapter for `tool.parameters`.
+- [Tool validator JSON Schema package](../packages/prism-core/README.md): optional `@arnilo/prism-core/validation/json-schema` adapter for `tool.parameters`.
 - [MCP client bridge and server exposure](mcp-tools.md): SDK-1.30.0 bounded tools/resources/prompts, host-owned roots/sampling/elicitation, exact-origin DNS-pinned client transport, and principal-bound opt-in Streamable HTTP sessions. 0.0.28 adds MCP OAuth: `createMcpOAuthTransport`/`createMcpOAuthFetch`/`createMcpClientAuth` (RFC 9728/8414 discovery, PKCE, RFC 8707 audience binding, RFC 7009 revocation, host-owned bounded state) and server `protectedResource` metadata + `WWW-Authenticate` challenges; 0.2.1 re-routes the client transport through the shared core DNS-pinned fetch primitive.
-- [Web search, fetch, and extraction](web-tools.md): optional host-selected Brave/Exa discovery and Firecrawl Markdown/schema tools with native fetch, stable citations, late credentials, finite limits, and explicit untrusted-content boundaries; the optional Obscura package (`@arnilo/prism-obscura`) adds a CLI-backed browser search/fetch adapter (`provider: "obscura"`) plus native `obscura_fetch`/`obscura_scrape` without API credentials.
+- [Web search, fetch, and extraction](web-tools.md): optional host-selected Brave/Exa discovery and Firecrawl Markdown/schema tools with native fetch, stable citations, late credentials, finite limits, and explicit untrusted-content boundaries; the optional `@arnilo/prism-web-tools/obscura` subpath adds a CLI-backed browser search/fetch adapter (`provider: "obscura"`) plus native `obscura_fetch`/`obscura_scrape` without API credentials.
 - [Work tools](work-tools.md): optional `@arnilo/prism-work-tools` identity-scoped M365 + GWS connectors (hard-coded CLI argv, draft-then-approve, state-machine idempotency, shared result shapes); 0.0.14 adds a late-bound per-identity `tokenProvider` (env-only, fail-closed); 0.2.0 plan 020 Task 3 provides an isolated subprocess environment (fixed allow-listed base + explicit env + late-bound token env, forced `HOME`/telemetry controls, 64-name/64-KiB caps) and requires host-pinned **absolute** binary/configDir paths.
 - [Work connectors](work-connectors.md): connector principles, capability gates, scoped OAuth establishment (0.0.14), and out-of-scope boundaries (Slack/Teams channels not shipped) for Microsoft 365 / Google Workspace.
-- [Browser automation](browser-automation.md): optional `@arnilo/prism-browser` with host-supplied Playwright contexts, AI-mode snapshots/refs, ordered `browser_open`/`browser_snapshot`/`browser_act`/`browser_close` plus (0.1.4) `browser_evaluate`/`browser_observe` and CDP `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions on Chromium hosts, egress/side-effect/upload/download/screenshot policy, finite page/action/snapshot/network/artifact caps, and 0.0.14 verified-state checkpoints with reload/verify-before-side-effect.
+- [Browser automation](browser-automation.md): optional `@arnilo/prism-web-tools/browser` subpath with host-supplied Playwright contexts, AI-mode snapshots/refs, ordered `browser_open`/`browser_snapshot`/`browser_act`/`browser_close` plus (0.1.4) `browser_evaluate`/`browser_observe` and CDP `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions on Chromium hosts, egress/side-effect/upload/download/screenshot policy, finite page/action/snapshot/network/artifact caps, and 0.0.14 verified-state checkpoints with reload/verify-before-side-effect.
 - [Device adapters](device-adapters.md): deny-by-default realtime voice / desktop-control contract + conformance (0.0.14); the first vendor package is the optional Linux-only `@arnilo/prism-computer-use-linux` wrapper, while admission still fails closed without explicit consent+sandbox+approval, stream bounds, shared `RunLimits`, and redacted telemetry.
 - [Linux desktop control](computer-use-linux.md): optional `@arnilo/prism-computer-use-linux` over a host-owned `computer-use-linux` MCP binary — doctor-first skill, target-window guidance, setup tools off by default, DeviceAdapter admission, high-risk mutator approval, serialized input, bounded untrusted screenshots/app state, and host redaction.
-- [Obscura browser engine](obscura.md): optional `@arnilo/prism-obscura` over a host-installed Obscura headless browser — fail-closed `spawnObscuraProcess` lifecycle (absolute shell-free command, Docker argv, bounded readiness, group close), `createObscuraMcpTools` bridging the complete advertised MCP surface (reads effect-free, mutations and unknown future tools exclusive/serialized, `obscura_` prefix, loopback-default HTTP), and `connectObscuraCdp` managed/external CDP + Playwright `connectOverCDP` composition feeding `@arnilo/prism-browser` tools directly; `browser_search` is in-page text search, not web search; omitted from umbrellas (binary not supplied by install).
+- [Obscura browser engine](obscura.md): optional `@arnilo/prism-web-tools/obscura` subpath over a host-installed Obscura headless browser — fail-closed `spawnObscuraProcess` lifecycle (absolute shell-free command, Docker argv, bounded readiness, group close), `createObscuraMcpTools` bridging the complete advertised MCP surface (reads effect-free, mutations and unknown future tools exclusive/serialized, `obscura_` prefix, loopback-default HTTP), and `connectObscuraCdp` managed/external CDP + Playwright `connectOverCDP` composition feeding the `browser` subpath tools directly; `browser_search` is in-page text search, not web search; host-binary gated (binary not supplied by install).
 - [Coding agent tools](coding-agent-tools.md): optional `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`, `glob`, `delete`, and `move` definitions plus opt-in `createGitTools()` / `coding_check`, opt-in `createAskUserDecisionTool` (single/multi/free-text + durable suspend glue), and `runCodingGoalVerify`; durable plan/todo Markdown helpers with workflow `state.coding` checkpoint metadata; streamed text pages, `repo_search` `outputMode`, bounded glob, optional read-before-write, optional Git-aware (`createGitAwareRepositoryOperations`) ignore-aware enumeration with native fallback, finite Git/check/plan/ask caps, bounded image/edit reads and write/edit payloads, finite shell wall/total-output limits, secure host-owned spill cleanup, pluggable bounded operation contracts, per-path mutation serialization, and optional `ExecutionPolicy`. 0.1.6 adds the optional [document reader](document-reader.md) slot (`@arnilo/prism-document-reader`, plan 018 closeout `doc-reader`): bounded PDF/DOCX literal-text extraction behind `createReadTool({ documentReader })` with magic-byte format gating, input/page/text caps, fail-closed optional peer parsers, and no embedded-content execution or external fetching. 0.1.6 also adds opt-in recursive `delete` (`recursive: true`, bounded fan-out, symlink children never followed) and bounded `{a,b}` glob expansion (`braceExpansion`, max 128 alternatives / 4096 bytes, fail-closed) behind plan 018 closeout `delete-glob`. No PDF/trash/PTY in the 0.0.21 baseline (0.1.6's document reader is the demand-gated optional exception); Phase 9 adds optional language intelligence (separate page). 0.2.6 adds the optional [Indexed code search](indexed-code-search.md) seam: host-owned incremental index (`update/remove/search/status/dispose`) with explicit `indexed_literal`/`semantic` modes behind `createIndexedRepositoryOperations`, literal remains the default, stale/failed/unsupported indexes fail closed with `ERR_PRISM_INDEX_*` and results are labeled `untrusted_index`. 0.2.6 also adds [Coding workspaces](coding-workspaces.md) (plan 026 Task 3): `createCodingWorkspaceLifecycle` registers host repositories and creates/lists/locks/removes linked worktrees with CheckpointStore CAS records, LeaseStore fencing, credential-free remote fingerprints, and a cleanup policy that refuses dirty/locked/unowned/mismatched trees unless the host allows it. 0.2.6 adds [Coding review and diagnostics](coding-review-and-diagnostics.md) (plan 026 Task 6): bounded patch-review manifests (`createCodingPatchReviewManifest` + `assertCodingPatchAccepted`, pending/accepted/rejected/superseded bound to patch digest + artifact revision + repository/worktree/base/head identity, composed over the server ArtifactService, never applying/committing automatically), normalized LSP/check diagnostics with deterministic added/removed/unchanged deltas, and opt-in LSP document synchronization (`syncDocument`, pull diagnostics with resultId reuse, stale-version guards). Limits do not sandbox host access—gate with permission/trust policy and `@arnilo/prism-coding-security`.
 - [Language intelligence](language-intelligence.md): optional host-activated `createLanguageIntelligence` — bounded in-package LSP 3.17 JSON-RPC client (Content-Length framing), host-selected server command/args per language, workspace symbols/definitions/references/diagnostics/hover/rename; lazy spawn; URI root confinement; rename gated by `ExecutionPolicy` + atomic write/mutation queue; frozen message/diagnostic/pending/result/timeout/server caps. No `vscode-languageserver-protocol` dependency.
 - [Process sessions](process-sessions.md): optional host-activated `createProcessSessions` — long-running process registry (start/cursor-paged output/input/wait/signal/kill/release), native or sandbox `startProcess` backend (fail closed when absent), ownership/identity + expiry sweep on access, `reconcile` / sandbox-loss → `unknown` (never fabricates exitCode), durable command fingerprint metadata, `CodingProcessEvent` host sink, `ExecutionPolicy` before spawn and on mutate, frozen session/input/lifetime/output caps; host-selected PTY (`pty: true` delegates only to the host `ptyBackend`, fails closed as unsupported when absent, bounded resize/TERM/attach caps). Durable process recovery (plan 026 Task 5): with `checkpoints`+`leases`+`ownerId`, intent is persisted before spawn and transitions are CAS/fence-written; `recover()` is attach-if-attested via a host `recoveryBackend`, otherwise starting/running records atomically become `unknown` (no fabricated exit, no PID probing), fenced so two replicas cannot both own a process.
 - [Forge integration](forge-integration.md): optional host-activated `createGitHubForge` — reference GitHub adapter (issue context, authenticated push via `BoundGitRunner` + `GIT_CONFIG_*` credential injection, PR create/update, review comments, check/status retrieval, bounded `reconcileHandoff`), every mutation gated by `ExecutionPolicy` and recorded in `ToolEffectStore` (retry never duplicates PRs/comments), typed `ForgeError` codes (auth/API/stale/rate-limit/limit/ownership), frozen page/payload/comment/concurrency/timeout caps, no octokit dependency, tokens never in argv/logs/events.
 - [Coding execution approval and sandboxing](coding-security.md): path/command approval, identity-scoped caching, shell-turn exclusivity, required `workspaceMode` (`host`/`sandbox`) with fail-closed mixed wiring, `createSandboxCodingComposition()` sandbox capability metadata — 0.2.0 plan 020 Task 4 ships explicit `SandboxCapabilities` (`workspaceCoherent`/`filesystemIsolated`/`networkIsolated`/`processIsolated`/`privilegeIsolated`/`egressRestricted`) with omission resolving false, truthful Docker/native metadata, and `containmentClaim` retained only as a deprecated conservative projection — disposable Docker/OCI sandbox reference with bounded workspace import/export (0.1.6 adds the Linux-only network-free `createNativeSandbox` backend — fresh netns per command via `unshare`, `ulimit` hard caps, cwd containment, fails closed where egress denial is impossible), optional `DisposableSandbox.startProcess` / `SandboxProcessHandle` for process-session backends, and allow-list egress (`createEgressPolicy` deny-all exact rules + frozen presets, `createAllowListEgressProxy` HTTP/CONNECT proxy with pinned-DNS rebinding defense, private/metadata IP denial, redirect re-validation + hop cap, byte/time caps, per-decision audit, `composeEgressSandboxNetwork` attestation recorded as `prism.egress.*` labels; TLS pass-through, no interception).
 
+## Documents, sheets, and diagrams
+- [Documents, spreadsheets, and presentations](documents.md): optional `@arnilo/prism-office/documents` package providing specification-compliant OOXML generation, parsing, patching, and bounded preview rendering for Word (`.docx`), Excel (`.xlsx`), and PowerPoint (`.pptx`) artifacts; pure in-memory operation, Draft-07 JSON Schema validation and slicing, typed model patch engine with undo/redo history, bounded framework-neutral preview blocks and sanitized HTML, SecretRedactor text sanitization seam, and dependency-free OpenTelemetry-compatible telemetry seam.
+- [Spreadsheets and CSV data](sheets.md): optional `@arnilo/prism-office/sheets` package providing fail-closed, high-fidelity XLSX and CSV ingestion with prefix dialect sniffing, container signature gating (`PK\x03\x04`), typed schema inference, read-only formula preservation, zero-allocation cap boundaries, and strict financial decimal-safety guarantees (exact decimal strings, zero floating-point conversions).
+- [Diagrams and mxGraph embed](diagrams.md): optional `@arnilo/prism-office/diagrams` package providing an origin-enforced draw.io embed client (`createDrawioEmbed`), XXE-safe mxGraph XML validation (`validateDrawioXml`), byte-stable deterministic XML canonicalization (`canonicalizeDrawioXml`) for content hashing, self-hosted deployment documentation, and Visio format exclusion (P12).
+
 ## Extensions/plugins
 - [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. Per-agent bundles remain app-controlled and are documented under Agent/session runtime.
 - [Contribution registries](contribution-registries.md): explicit host-owned registries for extension/package contributions without hidden globals, with `duplicate: "error"` strict mode for provider/model/tool/skill shadowing prevention.
@@ -107,9 +115,10 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Resource loading](resource-loading.md): decode text, JSON, binary, and manifests through caller-provided loaders; bridge host-authorized artifacts to bounded RAG document loading.
 
 ## Server/API
-- [Web-standard server handler](server.md): optional framework-free authorized direct/SSE agent, cross-replica durable event reconnect via `Last-Event-ID`, durable agent lifecycle/workflow routes, plus health/drain/rate-limit/replay/deployment-lease seams; explicit bounds and zero default exposure.
+- [Web-standard server handler](server.md): optional framework-free authorized direct/SSE agent, cross-replica durable event reconnect via `Last-Event-ID`, durable agent lifecycle/workflow routes, HMAC-signed DNS-pinned outbound webhooks, plus health/drain/rate-limit/replay/deployment-lease seams; explicit bounds and zero default exposure.
 
 ## Multi-agent and interoperability
+- [Multi-agent patterns (handoff/crew/supervisor/A2A)](multi-agent-patterns.md): decision table across in-session handoff (definition swap over existing seams, one transcript chain, host-authorized `handoff` allow-list tool, narrowed permissions on transfer), hierarchical crew orchestration (CrewAI process parity: manager structured output decomposition, parallel role specialists via fan-out, host reduce aggregation, conditional validation/revision), supervisor delegation, and A2A — when each applies, ownership/telemetry attribution, and carried-context redaction; documents the no-helper decision, CrewAI mapping table, and example walkthroughs.
 - [Antigravity delegated agent](antigravity-agent.md): optional `@arnilo/prism-antigravity-agent` adapter over the official host-owned Google Antigravity CLI (`agy`) — per-run ephemeral HTTP MCP server with Bearer auth, ephemeral workspace `.agents/` config backup/restore, NDJSON stream parsing, secret redaction, AG-UI timeline projection, multi-turn conversation continuation, and optional `createAntigravityDelegationTool` for supervisor delegation.
 - [Supervisor delegation](supervisors.md): optional explicit child allow-list, derived memory scopes, narrowing-only permissions, lifecycle hooks, nested delegation, cancellation, finite budgets, host-projected delegation telemetry, opt-in child event passthrough (`childEvents`), and separate A2A durable adapter boundary. Child factories return `Agent`, not `AgentSession` (`SupervisorError: child "<id>" factory must return an Agent, got <type>`); nested approvals need a stable config plus a durable store.
 - [A2A interoperability](a2a.md): A2A 1.0 JSON-RPC/HTTPS cards plus host-owned durable task get/list/cancel/subscribe, shared `AgentEventSource` task adapter, bounded rich parts/replay, principal-scoped push configs, exact-origin verified client, rich stream seam for explicit AG-UI fronting, and server-side `createAgUiA2AServer` exposure of a local AG-UI agent (0.0.26).
@@ -119,8 +128,9 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [AG-UI adoption evaluation](ag-ui-adoption.md): official 0.0.57 input/event/capability matrix and shipped hardened MCP/MCP Apps/A2A handshake boundaries.
 
 ## CLI/RPC
+- [Dev inspector](dev-inspector.md): optional `@arnilo/prism-dev` — loopback-only local playground over an already-configured agent; composition-only packaging of the server handler seams, durable event replay, the served UI page, and the `prism dev` CLI composition + scaffold `dev` script (plan 040 Task 4; no new core primitives, fails closed on non-loopback binds).
 - [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including mid-run `steer`, branch-handle results, fixed `forkSession`, and `checkout`. `prism init` scaffolds a tiny TypeScript project with one selected provider and an offline mock test; `prism providers add <name>` scaffolds an OpenAI-compatible provider package (manifest, provider, models, cache helpers, conformance test, docs stub).
-- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration plus linear durable sagas — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume (resume-aware nodes: branch on `ctx.resume` or the node re-suspends silently), schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, saga compensation/reconciliation, documented bounded iterate-until-done host-loop pattern, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Active-run registry is non-durable, in-process only, with bounded sweep/cap cleanup. Interactive TUI (C-012) deferred.
+- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration plus bounded in-graph `loopNode` refinement and linear durable sagas — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume (resume-aware nodes: branch on `ctx.resume` or the node re-suspends silently), schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, saga compensation/reconciliation, documented host-loop pattern, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Active-run registry is non-durable, in-process only, with bounded sweep/cap cleanup. Interactive TUI (C-012) deferred.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): architecture inventory — workflow adapters consume core `CheckpointStore`, `LeaseStore`, and bounded `EventMultiplexer`; run control and optional RPC commands stay package-local.
 - [Workflow/TUI scope](workflow-tui-primitives.md): records why 0.0.5 ships workflow APIs/RPC control but no interactive terminal UI.
 
@@ -143,11 +153,12 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 ## Third-party integrations
 - [Caveman behavior integration](caveman.md): optional `@arnilo/prism-caveman` — upstream Caveman skills/commands, `caveman-mode` injector, session `caveman-level` persistence, progressive catalog + `load_skill`; requires host `upstreamPath` and session attach callbacks; inert until `kernel.load`.
 - [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-ponytail` — upstream Ponytail skills/commands, `ponytail-mode` injector, session `ponytail-mode` persistence; resolves peer `@dietrichgebert/ponytail` or `upstreamPath`; opt-in (not in code/sdk profiles).
-- [Graft context-graph integration](graft.md): optional `@arnilo/prism-graft` — six graft CLI pull tools (`graft_ask`/`grep`/`callers`/`skeleton`/`map`/`blast`), push-mode retrieval-pack context provider + first-turn orientation, edit blast-radius middleware with `graft:dirty`, session `graft-state` persistence; resolves peer `@nanonets/graft@^0.13.0` or `packageRoot`/`cliPath`; opt-in (not in code/sdk profiles or the `prism-all` umbrella).
+- [Graft context-graph integration](graft.md): optional `@arnilo/prism-memory/graft` — six graft CLI pull tools (`graft_ask`/`grep`/`callers`/`skeleton`/`map`/`blast`), push-mode retrieval-pack context provider + first-turn orientation, edit blast-radius middleware with `graft:dirty`, session `graft-state` persistence; resolves peer `@nanonets/graft@^0.13.0` or `packageRoot`/`cliPath`; opt-in (not in code/sdk profiles or the `prism-all` umbrella).
 - [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-impeccable` — host `upstreamPath` to compiled Impeccable `SKILL.md`, skill + `/impeccable` → `load_skill`; no detector CLI, no live browser, not in code/sdk/all.
 
 ## Release and install
-- [Release and install](release-and-install.md): current **0.3.2** 60-package graph (root + 59 workspace packages) — plan 050 changed-package cut (clay-integration-findings fixes + OKF v0.2 wiki bundles) and independent `^0.3.0` publication; plan 030 last-lockstep cut and independent `^0.3.0` publication; plan 029 **0.2.9** provider adoption (DeepSeek, xAI SuperGrok OAuth, ClinePass), `@arnilo/prism-impeccable`, Ponytail 4.9.0, Caveman v2.1 extras; then plan 028 **0.2.8** ACP adoption fixes; then plan 026 the fully-featured coding-agent-readiness cut: **host-selected PTY** (`pty: true` delegates only to the host `ptyBackend`, fails closed as unsupported when absent, bounded resize/TERM/attach caps), **indexed code search** (host-owned incremental index seam with explicit `indexed_literal`/`semantic` modes, literal remains the default, stale/failed/untrusted indexes fail closed `ERR_PRISM_INDEX_*`, results labeled `untrusted_index`), **coding workspaces** (`createCodingWorkspaceLifecycle`: durable CheckpointStore CAS records + LeaseStore fencing, locked worktrees, credential-free fingerprints, cleanup refusal matrix), **durable recovery** (process intent/ACP `activeRun` refs over Postgres/SQLite stores with attach-if-attested `recover()` and durable fence-checked cancellation, never fabricated exits), **patch review and diagnostics** (`createCodingPatchReviewManifest` + `assertCodingPatchAccepted` with pending/accepted/rejected/superseded bound to digest + revision + identity, opt-in LSP `syncDocument`/`diagnosticDelta`), and the **protected real coding journey** (packed consumer through real provider/Docker/Postgres/GitHub/Playwright/PTY services with retained evidence report; forge breadth GitLab/Bitbucket stays demand-gated); then plan 025 the maintainability-and-bounded-performance cut: **god-module splits** (the six remaining implementation monoliths — `src/contracts-core.ts` 1,719 L, `src/agent-session.ts` 2,049 L, `workflows/src/run.ts` 1,227 L, `server/src/handler.ts` 1,005 L, `coding-agent/src/repository.ts` 974 L, `ag-ui/src/acp/agent.ts` 836 L — split into cohesive family files behind preserved barrels, compat-preserving with zero breaking deltas, no `exports`-map subpath, `RuntimeAgentSession` kept as one class with a recorded reason), **persistence-mechanics dedup** (21 pure ownership/cursor/checkpoint/lifecycle/search helpers moved into the dependency-free `session-store-codecs`; postgres/sqlite adapters shrank 273 lines; SQL dialect stays per-adapter; no schema/shape change; cross-store conformance green), **bounded accumulation removed** (per-push `Buffer.concat` in language framing + tar parsing → chunk-array readers; framing ~100–200× faster at 4,000 chunks, tar linear at 8 MiB, caps fail-closed byte-identical; CLI `collectOutput` audited already linear), **dead-code cleanup internal-only** (62 candidates triaged: 2 internal removals + 60 allow-listed in `docs/_evidence/phase25-dead-exports-triage.md`), and **coverage close** (76 behavior-backed regressions; core 90.53/84.20/90.54 → 91.43/84.80/91.60); additive-only compat (105 helper exports), no migration; then plan 024 the package-documentation-and-compatibility-truth cut: **umbrella wording matches manifests** (`@arnilo/prism-providers` installs 11 of 14 provider adapters — Azure/Bedrock/Vertex are added separately by `prism-all`; `prism-all` installs 20 direct / 43 transitive packages and omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail; membership unchanged in 0.2.x), **manifest-derived package truth** (`scripts/package-truth.mjs` → `scripts/package-truth.json` is the single source for counts, provider membership, and closures; docs literals regenerate from it and drift fails the gates), **peer-version policy Decision A** (exact `@arnilo/prism: 0.2.4` pins, atomic-upgrade rule, ERESOLVE refusal for partial upgrades, `^1.0.0` widening at 1.x), and **current-line truth** (`docs/0.1.0-readiness.md` at the 0.2.x line with 0.1.7 as the terminal 0.1.x baseline); no runtime contract delta (compat gate at 0.2.4: version literal only), no migration; then plan 023 the build-coverage-and-release-evidence-integrity cut: **build serialization** (dependency-free `scripts/with-build-lock.mjs` — one O_EXCL lockfile at `node_modules/.prism-build.lock` serializing every emit/test leaf so concurrent compilers can never expose a partial live `dist/`, stale-PID reclaim, env-overridable `PRISM_BUILD_LOCK_TIMEOUT_MS`, fail-closed; documented direct-`tsc` caveat), **corrected workspace coverage denominators** (package-local `--test-coverage-include=dist/**` so imported core `dist` no longer pollutes workspace rows — `mcp` 45.47→90.25, `rag` 19.70→94.82; evidence-based per-package thresholds in `scripts/coverage-thresholds.json` with `protectedException` for durable-leg packages shown separately, machine-readable `scripts/coverage-summary.json`), **machine-auditable release skip manifest** (`scripts/release-skip-manifest.mjs` → `scripts/release-evidence.json`: every surface recorded `pass`/`skip`/`blocked`/`protected` with reason and required env; the 33 protected/live skips named; a required surface without evidence records `blocked` and fails the release gate fail-closed — missing credentials/services can never convert into a green release), and **stabilized quality gates** (Biome 2.x `preset` config migration with zero lint diagnostics, the racy 150ms MCP bridge timing assert replaced by a deterministic barrier, load-sensitive guards carry documented `ponytail:` ceilings, machine-readable `lint-report.sarif` + `unused-report.json` retained by CI); no runtime contract delta (compat gate at 0.2.3: version literal only), no migration; then plan 022 the concurrent-state-and-durability-integrity cut: atomic model-budget reservation (`ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget` with fencing tokens, `reservationTtlMs` expiry and unknown-usage reconciliation, rate/budget key-map caps with LRU eviction that never drops a held reservation), atomic conversation metadata (`SessionRecord.version` + `appendSession` `expectedVersion` CAS across Postgres/SQLite — create-only `0`, exact-version `N>0`, legacy last-write-wins when omitted; `SessionMetadataConflictError` `metadata_conflict` with versions only, HTTP 409; concurrent create/branch/archive single-statement with branch caps inside the CAS, archive wins, deleted rows never resurrect), single-consumer `EventMultiplexer` (`EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silent queue sharing), restart-stable NATS durable consumer identity (`prism_<hmac16>` with no random suffix — crash-resumed subscribe continues from the last ack, orphaned 0.2.1 consumers reclaimed on clean stop), and bounded non-durable active-run registries (sweep + fail-closed 512 cap `ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`); new regression surface `scripts/phase22-security.test.mjs` (4 blockers + gate accounting over built public entrypoints) + packed plain-JS `security22.mjs` consumer + the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes across memory/Postgres/SQLite/NATS legs, no timing-only sleeps) + the `scripts/phase22-conformance.test.mjs` gate; additive-only compat (new exports only, no removals); forward-only migrations 008 (`prism_sessions.version`) and 003 (`prism_model_router_budgets.reservations`); migration `0.2.1 → 0.2.2`; then plan 021 the provider-completion-and-outbound-trust-boundaries cut: strict stream completion is the shared OpenAI-compatible default (truncated streams fail `incomplete_delta`, explicit `strictCompletion: false` opt-out), bounded success bodies via `readBoundedResponseJson` on all discovery/quota/embeddings/upload/OAuth JSON endpoints (65,536-byte ceiling, depth/property/shape caps), DNS-pinned OIDC JWKS/OPA/content fetches through the core `pinnedFetch` primitive with 3xx redirects rejected outright (private/metadata answers fail closed `ssrf_denied`), shared bounded OAuth device/token polling (`pollDeviceCodeToken`) across provider-openai and credentials-node, and the four edge fixes (Azure/Vertex credential-once, Bedrock duplicate-case/repeated-query SigV4 canonicalization, OpenAI upload failed-DELETE retention, cache `__overflow__` tokens-only); public-entrypoint threat-suite `scripts/phase21-security.test.mjs` + packed plain-JS consumer; additive-only compat (MCP transport helpers re-exported from core, no removals); migration `0.2.0 → 0.2.1`; then plan 020 the fail-closed runtime-and-sandbox-security cut on the 0.2.x review-remediation line: durable-resume decision validation in core (`assertValidAgentRunResume` — unknown decisions/malformed batches fail closed with `ERR_PRISM_DECISION_*` before any state claim, checkpoint write, or tool execution; server parser remains defense in depth), isolated work-tool subprocess environments (`@arnilo/prism-work-tools` — fixed base allow-list + explicit env + forced HOME/telemetry + late-bound per-identity tokens, 64-name/64-KiB caps, absolute binary/configDir, linear output capture), and explicit sandbox capabilities (`@arnilo/prism-coding-security` — `SandboxAdapter.capabilities` with omission-is-false fail-closed resolution, `SandboxCodingComposition.capabilities` from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege `false`); public-entrypoint security conformance (`scripts/phase20-security.test.mjs`, wired into `security:threat-suites`), packed plain-JS consumer regressions, and the sandbox-browser workflow's fail-loud Docker/native capability evidence gate — 0.2.0 never ships while a blocker is skipped; migration and rollback notes in `docs/migration.md` `0.1.7 → 0.2.0`, store-compatible with 0.1.7 in both directions; 0.1.7 was the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates. 0.2.6 (plan 026 Task 7) adds the protected coding journey: `scripts/phase26-coding-journey.test.mjs` runs a packed consumer through real provider calls, a digest-pinned Docker sandbox, the durable Postgres worktree lifecycle, provider-driven ACP edits with policy approval, named checks with `diagnosticDelta`, patch review over the server ArtifactService, cross-replica process recovery, durable cancellation, real GitHub PR push/reconcile/cleanup, host Playwright inspection, and the host PTY adapter (frozen profile) — the retained `scripts/phase26-coding-journey-report.json` gates release evidence (pass/blocked/protected, never a passing skip).
+- [Release and install](release-and-install.md): current **0.4.0** 11-package graph (root + 10 workspace packages) — plan 041-044 changed-package cut (progressive tool loading with `search_tools` disclosure, `@arnilo/prism-prompts` initial cut with run-ledger `promptVersion` provenance (persistence schema 9), trace-to-dataset curation in `@arnilo/prism-evals`, and composite memory-recall scoring in `@arnilo/prism-memory@0.3.2`) and independent `^0.3.0` publication; plan 050 changed-package cut (clay-integration-findings fixes + OKF v0.2 wiki bundles) and independent `^0.3.0` publication; plan 030 last-lockstep cut and independent `^0.3.0` publication; plan 029 **0.2.9** provider adoption (DeepSeek, xAI SuperGrok OAuth, ClinePass), `@arnilo/prism-impeccable`, Ponytail 4.9.0, Caveman v2.1 extras; then plan 028 **0.2.8** ACP adoption fixes; then plan 026 the fully-featured coding-agent-readiness cut: **host-selected PTY** (`pty: true` delegates only to the host `ptyBackend`, fails closed as unsupported when absent, bounded resize/TERM/attach caps), **indexed code search** (host-owned incremental index seam with explicit `indexed_literal`/`semantic` modes, literal remains the default, stale/failed/untrusted indexes fail closed `ERR_PRISM_INDEX_*`, results labeled `untrusted_index`), **coding workspaces** (`createCodingWorkspaceLifecycle`: durable CheckpointStore CAS records + LeaseStore fencing, locked worktrees, credential-free fingerprints, cleanup refusal matrix), **durable recovery** (process intent/ACP `activeRun` refs over Postgres/SQLite stores with attach-if-attested `recover()` and durable fence-checked cancellation, never fabricated exits), **patch review and diagnostics** (`createCodingPatchReviewManifest` + `assertCodingPatchAccepted` with pending/accepted/rejected/superseded bound to digest + revision + identity, opt-in LSP `syncDocument`/`diagnosticDelta`), and the **protected real coding journey** (packed consumer through real provider/Docker/Postgres/GitHub/Playwright/PTY services with retained evidence report; forge breadth GitLab/Bitbucket stays demand-gated); then plan 025 the maintainability-and-bounded-performance cut: **god-module splits** (the six remaining implementation monoliths — `src/contracts-core.ts` 1,719 L, `src/agent-session.ts` 2,049 L, `workflows/src/run.ts` 1,227 L, `server/src/handler.ts` 1,005 L, `coding-agent/src/repository.ts` 974 L, `ag-ui/src/acp/agent.ts` 836 L — split into cohesive family files behind preserved barrels, compat-preserving with zero breaking deltas, no `exports`-map subpath, `RuntimeAgentSession` kept as one class with a recorded reason), **persistence-mechanics dedup** (21 pure ownership/cursor/checkpoint/lifecycle/search helpers moved into the dependency-free `session-store-codecs`; postgres/sqlite adapters shrank 273 lines; SQL dialect stays per-adapter; no schema/shape change; cross-store conformance green), **bounded accumulation removed** (per-push `Buffer.concat` in language framing + tar parsing → chunk-array readers; framing ~100–200× faster at 4,000 chunks, tar linear at 8 MiB, caps fail-closed byte-identical; CLI `collectOutput` audited already linear), **dead-code cleanup internal-only** (62 candidates triaged: 2 internal removals + 60 allow-listed in `docs/_evidence/phase25-dead-exports-triage.md`), and **coverage close** (76 behavior-backed regressions; core 90.53/84.20/90.54 → 91.43/84.80/91.60); additive-only compat (105 helper exports), no migration; then plan 024 the package-documentation-and-compatibility-truth cut: **umbrella wording matches manifests** (`@arnilo/prism-providers` installs 11 of 14 provider adapters — Azure/Bedrock/Vertex are added separately by `prism-all`; `prism-all` installs 20 direct / 43 transitive packages and omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail; membership unchanged in 0.2.x), **manifest-derived package truth** (`scripts/package-truth.mjs` → `scripts/package-truth.json` is the single source for counts, provider membership, and closures; docs literals regenerate from it and drift fails the gates), **peer-version policy Decision A** (exact `@arnilo/prism: 0.2.4` pins, atomic-upgrade rule, ERESOLVE refusal for partial upgrades, `^1.0.0` widening at 1.x), and **current-line truth** (`docs/0.1.0-readiness.md` at the 0.2.x line with 0.1.7 as the terminal 0.1.x baseline); no runtime contract delta (compat gate at 0.2.4: version literal only), no migration; then plan 023 the build-coverage-and-release-evidence-integrity cut: **build serialization** (dependency-free `scripts/with-build-lock.mjs` — one O_EXCL lockfile at `node_modules/.prism-build.lock` serializing every emit/test leaf so concurrent compilers can never expose a partial live `dist/`, stale-PID reclaim, env-overridable `PRISM_BUILD_LOCK_TIMEOUT_MS`, fail-closed; documented direct-`tsc` caveat), **corrected workspace coverage denominators** (package-local `--test-coverage-include=dist/**` so imported core `dist` no longer pollutes workspace rows — `mcp` 45.47→90.25, `rag` 19.70→94.82; evidence-based per-package thresholds in `scripts/coverage-thresholds.json` with `protectedException` for durable-leg packages shown separately, machine-readable `scripts/coverage-summary.json`), **machine-auditable release skip manifest** (`scripts/release-skip-manifest.mjs` → `scripts/release-evidence.json`: every surface recorded `pass`/`skip`/`blocked`/`protected` with reason and required env; the 33 protected/live skips named; a required surface without evidence records `blocked` and fails the release gate fail-closed — missing credentials/services can never convert into a green release), and **stabilized quality gates** (Biome 2.x `preset` config migration with zero lint diagnostics, the racy 150ms MCP bridge timing assert replaced by a deterministic barrier, load-sensitive guards carry documented `ponytail:` ceilings, machine-readable `lint-report.sarif` + `unused-report.json` retained by CI); no runtime contract delta (compat gate at 0.2.3: version literal only), no migration; then plan 022 the concurrent-state-and-durability-integrity cut: atomic model-budget reservation (`ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget` with fencing tokens, `reservationTtlMs` expiry and unknown-usage reconciliation, rate/budget key-map caps with LRU eviction that never drops a held reservation), atomic conversation metadata (`SessionRecord.version` + `appendSession` `expectedVersion` CAS across Postgres/SQLite — create-only `0`, exact-version `N>0`, legacy last-write-wins when omitted; `SessionMetadataConflictError` `metadata_conflict` with versions only, HTTP 409; concurrent create/branch/archive single-statement with branch caps inside the CAS, archive wins, deleted rows never resurrect), single-consumer `EventMultiplexer` (`EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silent queue sharing), restart-stable NATS durable consumer identity (`prism_<hmac16>` with no random suffix — crash-resumed subscribe continues from the last ack, orphaned 0.2.1 consumers reclaimed on clean stop), and bounded non-durable active-run registries (sweep + fail-closed 512 cap `ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`); new regression surface `scripts/phase22-security.test.mjs` (4 blockers + gate accounting over built public entrypoints) + packed plain-JS `security22.mjs` consumer + the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes across memory/Postgres/SQLite/NATS legs, no timing-only sleeps) + the `scripts/phase22-conformance.test.mjs` gate; additive-only compat (new exports only, no removals); forward-only migrations 008 (`prism_sessions.version`) and 003 (`prism_model_router_budgets.reservations`); migration `0.2.1 → 0.2.2`; then plan 021 the provider-completion-and-outbound-trust-boundaries cut: strict stream completion is the shared OpenAI-compatible default (truncated streams fail `incomplete_delta`, explicit `strictCompletion: false` opt-out), bounded success bodies via `readBoundedResponseJson` on all discovery/quota/embeddings/upload/OAuth JSON endpoints (65,536-byte ceiling, depth/property/shape caps), DNS-pinned OIDC JWKS/OPA/content fetches through the core `pinnedFetch` primitive with 3xx redirects rejected outright (private/metadata answers fail closed `ssrf_denied`), shared bounded OAuth device/token polling (`pollDeviceCodeToken`) across provider-openai and credentials-node, and the four edge fixes (Azure/Vertex credential-once, Bedrock duplicate-case/repeated-query SigV4 canonicalization, OpenAI upload failed-DELETE retention, cache `__overflow__` tokens-only); public-entrypoint threat-suite `scripts/phase21-security.test.mjs` + packed plain-JS consumer; additive-only compat (MCP transport helpers re-exported from core, no removals); migration `0.2.0 → 0.2.1`; then plan 020 the fail-closed runtime-and-sandbox-security cut on the 0.2.x review-remediation line: durable-resume decision validation in core (`assertValidAgentRunResume` — unknown decisions/malformed batches fail closed with `ERR_PRISM_DECISION_*` before any state claim, checkpoint write, or tool execution; server parser remains defense in depth), isolated work-tool subprocess environments (`@arnilo/prism-work-tools` — fixed base allow-list + explicit env + forced HOME/telemetry + late-bound per-identity tokens, 64-name/64-KiB caps, absolute binary/configDir, linear output capture), and explicit sandbox capabilities (`@arnilo/prism-coding-security` — `SandboxAdapter.capabilities` with omission-is-false fail-closed resolution, `SandboxCodingComposition.capabilities` from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege `false`); public-entrypoint security conformance (`scripts/phase20-security.test.mjs`, wired into `security:threat-suites`), packed plain-JS consumer regressions, and the sandbox-browser workflow's fail-loud Docker/native capability evidence gate — 0.2.0 never ships while a blocker is skipped; migration and rollback notes in `docs/migration.md` `0.1.7 → 0.2.0`, store-compatible with 0.1.7 in both directions; 0.1.7 was the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates. 0.2.6 (plan 026 Task 7) adds the protected coding journey: `scripts/phase26-coding-journey.test.mjs` runs a packed consumer through real provider calls, a digest-pinned Docker sandbox, the durable Postgres worktree lifecycle, provider-driven ACP edits with policy approval, named checks with `diagnosticDelta`, patch review over the server ArtifactService, cross-replica process recovery, durable cancellation, real GitHub PR push/reconcile/cleanup, host Playwright inspection, and the host PTY adapter (frozen profile) — the retained `scripts/phase26-coding-journey-report.json` gates release evidence (pass/blocked/protected, never a passing skip).
+- [Migrate legacy 0.3 packages to 0.4](migrate-to-0.4.md): complete breaking package-reorganization guide — all retired package/import mappings, profile replacements, optional peers and host binaries, security boundaries, rollback, and npm `legacy`/deprecation lifecycle.
 - [0.1.0 / 1.0 readiness gates](0.1.0-readiness.md): command-per-gate 1.0 readiness table — frozen API surface + compat gate, migration/docs tripwires, budget table, live-suite matrix, security matrix, current-line status (**0.2.5** current line; 0.1.7 terminal 0.1.x baseline), signed-publication/live-canary prerequisites for 1.0, and Phase 12 demand-evidence entry criteria.
 - [Review coverage archive](_evidence/): per-phase evidence freezes (plans 067–079, releases 0.0.4–0.0.16, 0.2.7 ERP evidence) — traceability matrices, provider validation, capability/primitive/limit matrices, benchmark budgets, and artifact-diet findings; tarball-excluded, kept in-repo for audit.
 

package/docs/mcp-tools.md

@@ -77,7 +77,7 @@ const handleMcp = await createPrismMcpWebHandler(server, {
 ## 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.

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 11 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` | Antigravity interop. |
+
+## 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. |
+| `@arnilo/prism-antigravity-agent` | 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.