@arnilo/prism 0.5.4 → 0.5.5

package/docs/index.md

@@ -1,175 +1,190 @@
 # Prism Docs
 
-Prism is a TypeScript/Node.js agent harness. Host apps and extension packages own providers, tools, resources, credentials, storage, UI, and business behavior. Prism supplies contracts, registries, streaming events, and replaceable runtime primitives.
+Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credentials, storage, and behavior; Prism supplies contracts, registries, events, and replaceable runtime primitives.
 
-## Current line (0.5.4)
+## Current line (0.5.5)
 
-- **Tool result content on the wire**: content-only `ToolResult`s fold into `tool_result.result`; adapters join sibling text so the model sees tool output instead of JSON `"null"`.
-- **Stream token coalesce**: adjacent `text`/`thinking` deltas merge on persist; replay serializers join with `""` so multi-turn tool loops do not grow interstitial newlines.
-- **Provider request construction**: Prism stamps `sessionId`/`cacheKey` on every owned generate site, default cache breakpoints on `cache_control` / explicit-breakpoint models, and `thinkingLevel` on `AgentConfig` / `RunOptions`. Host policies are overlays. OpenCode Go missing session fails closed with `ProviderRequirementError` before fetch.
-- **10 publishable packages**: lockstep `0.5.4` (plans 055–067); family packages use explicit subpaths.
-- **Linux desktop control**: optional `@arnilo/prism-coding-tools/computer-use-linux` wraps a host-owned `computer-use-linux` MCP binary; DeviceAdapter admission is deny-by-default and the package is omitted from umbrellas.
-- **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.
+- **Run limits**: HARD caps are request/response bytes only; policy axes accept `null` (plan 067).
+- **Tool-result fold**: content-only `ToolResult`s fold into `tool_result.result` (0.5.3).
+- **Stream token coalesce**: adjacent text/thinking deltas merge on persist (0.5.2).
+- **Provider request construction**: kernel session/cache/thinking defaults; hosts overlay (0.5.1).
+- **10 publishable packages** at current **0.5.5** lockstep — inventory below.
 
 ## Public contracts
-- [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`).
+
+- [Public contracts](public-contracts.md): canonical message, agent, tool, store, resource, credential, and event shapes.
+- [Coding tools, sandboxing, and personas](coding-tools.md): `@arnilo/prism-coding-tools` family subpaths — agent, security, document-reader, openapi, computer-use-linux, dev, personas.
+- [Core runtime, sessions, and governance](core.md): `@arnilo/prism-core` family subpaths — runtime, sessions, governance, credentials, enterprise, work, validation.
 
 ## 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-core/credentials/node/oidc` — pinned issuer/audience/JWKS, bounded claims, fail closed).
-- [Policy and audit](policy-and-audit.md): optional `@arnilo/prism-core/governance/policy` decision ledger (allow/deny/modify/approval), evidence refs only, cursor-paginated WORM export, durable PostgreSQL composition, and multi-party approvals — immutable requests with role/quorum requirements, requester/approver separation, expiry, revocation, bounded delegation, rejection, policy-revision pins, and atomic grant consumption via a host `ApprovalAuthority` (NIST AC-5 applied as control guidance, not certification); 0.0.28 adds the OPA REST evaluator (`@arnilo/prism-core/governance/policy/opa` — pinned SSRF-checked endpoint, redacted input, fail-closed deny, optional bundle-revision pin); 0.2.1 makes the OPA decision fetch DNS-pinned (core `pinnedFetch`).
-- [Signed, hash-chained audit export](audit-export.md): `@arnilo/prism-core/governance/policy` exports tenant-scoped audit records as signed, hash-chained batches — canonical RFC 8785 envelopes, SHA-256 record chain, host-signed manifests, WORM acknowledgement gating cursor advance, SIEM mirroring with replayable pending status, redaction/legal-hold provenance, and independent `verifyAuditBatch`/CLI verification with no key storage or vendor SDKs in Prism.
-- [Model routing](model-routing.md): optional `@arnilo/prism-core/governance/model-router` allow-list/residency/budget/rate/circuit/fallback governance with redacted diagnostics; budget admission reserves per-request caps atomically (commit/release/TTL reconciliation); durable state requires awaited identity-scoped calls; host-configurable selection policies (reference cost/latency policy ranks by `ModelCost` then in-memory latency EMA fed from `recordOutcome`).
+
+- [Agent identity](agent-identity.md): host-verified `Principal`/`AgentIdentity`, delegation narrowing, redacted telemetry refs, optional OIDC verifier.
+- [Policy and audit](policy-and-audit.md): allow/deny/modify/approval decision ledger, multi-party approvals, OPA evaluator — evidence refs only.
+- [Signed, hash-chained audit export](audit-export.md): tenant-scoped signed, hash-chained audit batches with independent verification; no key storage.
+- [Model routing](model-routing.md): allow-list/residency/budget/rate/circuit/fallback governance with atomic budget reservation.
 
 ## Agent/session runtime
-- [Agent/session runtime](agent-session-runtime.md): create explicit or opt-in secure agents/sessions, get direct `AgentRunResult` values from `run`/`prompt`, mid-run `steer` (turn-boundary or softInterrupt), use integrated `stream()`/`resumeAgentRunStream()`, shared batch pending-decisions / sticky run-scope approvals, subscribe to normalized events, and expose opted-in durable lifecycle capabilities (0.1.6 plan 018 closeout `checkpoint-bodies`: optional `includeSkillBodies` persists the exact loaded-skill instructions with the names-only `persistSessionState`, so resume re-renders bodies registry-independently; ≤64 bodies, `maxStateBytes` refuses oversize; 0.2.0 plan 020 Task 2: durable resume input is validated in core before any side effect — fail-closed durable resume rejects unknown legacy decisions and malformed batches with zero checkpoint writes, tool calls, or resumed events).
-- [Agent definitions](agent-definitions.md): resolve declarative `AgentDefinition` values via `resolveAgentDefinition`, and turn app-config `<configRoot>/agents/<name>/AGENT.md` bundles into runnable agents via `discoverAgentBundles` / `resolveAgentBundle` (explicit tool/skill activation by name, fail-closed omitted capabilities, migration-only `activateAllCapabilities`, strict duplicate scope checks, configurable prompt layers, no auto-discovery).
-- [Agent loops](agent-loops.md): replaceable per-run control loops — `singleShotLoop` default, opt-in bounded artifact-loop tool rounds, and durable custom-loop `revision`/`snapshot`/`restore` hooks with fail-closed resume.
-- [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with buffered provider output and redacted decision records.
-- [Agent events](agent-events.md): live `session.subscribe` plus durable `AgentEventSource` page/subscribe/resume for cross-replica reconnect; message/progress deltas never create spans. Durable sources: PostgreSQL `LISTEN`/`NOTIFY` (reference, `@arnilo/prism-core/sessions/postgres` root export) and NATS JetStream (`@arnilo/prism-core/sessions/nats`, FR-5) with restart-stable durable consumer identity (`prism_<hmac16>`) for cursor resume across crash/restart.
-- [Observability](observability.md): OTel GenAI agent/provider/tool hierarchy, RAG span tree (`createRagTelemetry()`), host context parenting, bounded trace linkage, safe evaluation events, controlled metrics, and exporter isolation.
-- [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, 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, immutable run/trace feedback, host-raisable `RunLimits` with `null` per-axis disable (bytes stay process-HARD), and the host-supplied `CostCatalog` pricing adapter (usage-only without one).
-- [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.
+
+- [Agent/session runtime](agent-session-runtime.md): create agents/sessions, `run`/`prompt`/`steer`/`stream`, durable resume, batch approvals.
+- [Agent definitions](agent-definitions.md): declarative `AgentDefinition` resolution and `AGENT.md` bundle discovery, fail-closed activation.
+- [Agent loops](agent-loops.md): replaceable loops with `limits.maxToolRounds` budgets and durable revision/restore hooks.
+- [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with redacted decision records.
+- [Agent events](agent-events.md): `turn_started`/`tool_call_delta` stream plus durable page/resume sources for reconnect.
+- [Observability](observability.md): OTel GenAI span hierarchy, RAG span tree, bounded trace linkage, exporter isolation.
+- [Operations runbook](operations.md): high-availability fencing model, failover drill, replay rules; never unlock leases manually.
+- [Disaster recovery and backup operations](disaster-recovery.md): backup/restore/PITR/DR-drill runbook with guarded commands and RPO/RTO.
+- [Data classification and field-level redaction](data-classification.md): `applyFieldPolicy` allow/redact/tokenize/deny walks with fail-closed protected default.
+- [Evaluations](evaluations.md): deterministic bounded trace/model-judge/pairwise scoring with CI thresholds and trace linkage.
+- [Runs and usage ledger](runs-and-usage.md): durable run/event/usage persistence, host-raisable `RunLimits`, `CostCatalog` pricing.
+- [Performance limits](performance.md): frozen 0.1.0 capacity envelopes and network-free benchmark evidence — the performance contract.
+- [Structured output](structured-output.md): `Artifact*` seam plus provider-native `StructuredOutputOptions` 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 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. Summary generate uses the **agent session id** so it can hit the same prompt cache.
-- [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). Worker generate uses derived `om:{session.id}`, separate from the agent 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-core/runtime/server/artifact-bodies` S3-compatible adapter (hand-rolled SigV4, native fetch + WebCrypto, optional host KMS callback); delivery links resolve through `bodies.presign` when wired.
-- [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference (kept for compatibility; links back to the canonical atomic append / branch-handle sections).
-- [Database persistence](database-persistence.md): production persistence contracts, shared checksummed migration/full-shape catalog primitives (`@arnilo/prism/testing/persistence-schema`), conditional append, indexes, `readBranchPath`, reference relational schema, retention/legal-hold/quota lifecycle (`lifecycle`), and NoSQL mapping. `appendSession` gains version/CAS (migration `008_session_version`); durable adapters must pass `assertStateConcurrencyConforms` (`@arnilo/prism/testing/state-concurrency-conformance`: approval/checkpoint-CAS/cursor/idempotency/reservation/conversation-metadata/unknown-outcome probes; memory leg in `npm test`, durable legs in `test:postgres`/`test:nats`, `scripts/phase22-conformance.test.mjs` gate accounting).
-- [SQLite persistence](sqlite-persistence.md): optional `better-sqlite3` adapter with session/run storage, checkpoints/leases, feedback, FTS `searchSessions` (migration-v4), and transactionally verified/backfilled migration metadata.
-- [PostgreSQL persistence](postgres-persistence.md): optional pooled `pg` adapter with session/run/checkpoint/lease/feedback storage, FTS `searchSessions` (migration-v4), advisory-locked checksummed/full-shape migrations, and opt-in live conformance. Semantic vectors live in `@arnilo/prism-memory`'s pgvector path (`createPostgresVectorStore`, documented on the working-and-semantic-memory page); RAG durable storage uses that store, never this session-store adapter.
-- [Enterprise PostgreSQL state](enterprise-postgres-state.md): optional `@arnilo/prism-core/enterprise/postgres` composition for durable policy/evaluation/work-idempotency/model-router/`toolEffects` state, transactional ERP outbox/inbox messaging, and multi-party approval records (`createPostgresApprovalStore`, migration 005 — one locked row per request, revision-checked terminal transitions, caller-transaction grant consumption), exact tenant ownership, checksummed migrations (001-005; 003 adds router budget reservation slots; 004 adds bounded at-least-once dispatch), and explicit cleanup.
-- [Migration guide](migration.md): **0.1.4 → 0.1.5** documented breaking cut — deprecated-option removal (the inert provider request knobs, `maxToolRounds` alias, observational-memory flat keys/worker aliases, `autoResizeImages`, `INIT_PROVIDERS`) with exact replacement table, before/after examples, and fail-closed refusal behavior; **0.0.28 → 0.1.0** release-candidate hardening (no migration); **0.0.17 → 0.1.0 upgrade matrix** (store compatibility per release line: compatible / tested migration / tested refusal, plus breaking-default callouts); **0.0.27** ACP coding-host interop (capability advertise-when, session modes/config, MCP select, lifecycle events, elicitation); **0.0.26** coding intelligence, managed processes, forge, and safe egress; **0.0.25** durable custom loops and shared human-in-the-loop decisions; **0.0.24** distributed events and recoverable tool effects; **0.0.23** enterprise PostgreSQL state adapters (async router and work reconciliation); **0.0.22** third-party behavior integrations (Caveman, Ponytail); **0.0.21** coding-tool capability gaps (`outputMode`, glob, read-before-write, delete/move, aggregator 9/4); **0.0.20** progressive skill disclosure, empty registry default, `load_skill`, priority budget demotion, optional tool-result fold; **0.0.19** observational memory lifecycle; **0.0.15** OpenAI hosted tools/continuation/Realtime, exact AI SDK v4 matrix, RAG lifecycle/reranking/trust/status, and memory export/rebuild; **0.0.14** conversations, memory consent/lifecycle, artifact co-work review, AG-UI co-work events, scoped M365/GWS OAuth connectors, browser checkpoints, device contracts, and Alibaba/Ollama providers; plus prior release migrations.
-- [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL file adapter for single-process Node hosts; no cross-process safety; `searchSessions` throws `SessionSearchUnsupportedError`.
-- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 inventory — session/run-ledger/persistence contracts, credential/OAuth seams, content/resource/model capabilities, package dependency matrix, conformance matrix, and threat model for production adapters.
+
+- [Compaction and retry policies](compaction-and-retry.md): host-replaceable summarize/retry policies with deprecated-option removals fail closed.
+- [LLM compaction subpath](compaction-llm.md): provider-backed summarization with finite `model.parameters.maxTokens` and coding handoff strategy.
+- [Observational memory compaction subpath](compaction-observational-memory.md): observations/reflections with `appendEntry`, exact-id recall, nested-only settings.
+- [Working and semantic memory](working-and-semantic-memory.md): working-memory store, semantic recall, pgvector path, consent lifecycle.
+- [Session stores](session-stores.md): `SessionStore` contract, append options, branches, bounded search — start here for persistence.
+- [Conversations](conversations.md): durable user-scoped threads with versioned metadata and legal-hold-aware deletion.
+- [Work artifacts and review](work-artifacts-and-review.md): artifact attach, revision compare, approve/reject, expiring delivery links.
+- [Session stores and branching](session-stores-and-branching.md): branch-semantics helper reference (compatibility stub for session-stores.md).
+- [Database persistence](database-persistence.md): production persistence contracts, migrations, retention, and adapter conformance harnesses.
+- [SQLite persistence](sqlite-persistence.md): optional `better-sqlite3` adapter with FTS search and verified migrations.
+- [PostgreSQL persistence](postgres-persistence.md): optional pooled `pg` adapter with advisory-locked migrations and live conformance.
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable governance/router/ERP state, outbox/inbox messaging, approval records.
+- [Migration guide](migration.md): current 0.5.x migration cuts with replacement tables and rollback notes.
+- [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL adapter, single-process, no cross-process safety.
 
 ## Provider and model connection
-- [Embeddings](embeddings.md): provider-neutral `EmbeddingsProvider` one-shot batch contract (`embedMany` with usage, per-item typed errors, `capabilities.embeddings` flag), OpenAI-compatible and DashScope adapters, strict provider batch caps (callers chunk), and offline `runEmbeddingsConformance` — structural bridge to memory's dependency-free `Embedder` seam.
-- [Speech and transcription](speech.md): provider-neutral `SpeechProvider` (`synthesize` bytes + `synthesizeStream` first-chunk streaming, `capabilities.speech` flag) and `TranscriptionProvider` (`transcribe` + `transcribeStream` partials sharing the Realtime `transcript_delta` naming, `capabilities.transcription` flag), OpenAI audio adapters with byte caps and typed errors, and offline `runSpeechConformance`/`runTranscriptionConformance`.
-- [Image generation and editing](image-generation.md): provider-neutral `ImageGenerationProvider` (`generate`/`edit` returning `Uint8Array` bytes with `provider`/`model` provenance, hosts own persistence, `capabilities.imageGeneration` flag), OpenAI `b64_json` routes + DashScope wanx async-task adapter, `pinnedFetch` URL resolution, and offline `runImageGenerationConformance`.
-- [Moderation](moderation.md): provider-neutral `ModerationProvider` classification (`moderate` → per-category `{ score, flagged }` under a neutral vocabulary with raw passthrough; scores are provider output — no core policy, `capabilities.moderation` flag), OpenAI `/v1/moderations` adapter with data-driven category mapping, and offline `runModerationConformance`.
-- [Batch jobs](batch-jobs.md): provider-neutral `BatchJobsProvider` (`submit`/`status`/`cancel`/paged `results`, opaque job ids, typed job-state union, `capabilities.batchJobs` flag), OpenAI Files-API + `/v1/batches` adapter, standalone `pollBatch` backoff utility, and offline `runBatchJobsConformance`.
-- [Provider primitives](provider-primitives.md): shared bounded transport and OpenAI serialization helpers — migrated across first-party providers; bounded success-body reader for all non-stream JSON endpoints; native structured-output and observability contracts.
-- [Provider layer](provider-layer.md): register and resolve host-owned providers/models, choose replace-or-error duplicate policy, create provider events, stream/reconstruct tool-call deltas, use generic provider request options, and test with the mock provider; deprecated provider-level timeout/retry hints point to runtime abort/retry.
-- [Model registry](model-registry.md): register and resolve `ModelConfig` records with capabilities, limits, cost, cache support metadata, compat data, and duplicate policy.
-- [Provider caching](provider-caching.md): use `PromptCacheHints`, `PromptCacheBreakpoint`, `ModelCacheCapabilities`, cache-aware stable-prefix guidance, and shared cache diagnostics helpers; includes the complete per-provider explicit/implicit cache matrix plus no-Prism-cache entries (including Anthropic, Google, Alibaba, Ollama, cloud adapters, and host-owned AI SDK); cache hints are best-effort and cache keys are never secrets; `createCacheTelemetry()` aggregates per-provider/model hit rate and cache-token totals from the `usage` event stream for tuning the `cache_aware` layout — the `__overflow__` bucket reports requests/token totals only, never mixed-model cost.
-- [Thinking and reasoning](thinking-and-reasoning.md): session entry point is `AgentConfig.thinkingLevel` / `RunOptions.thinkingLevel`; `applyThinkingLevelForModel` snaps the level to the model's declared `capabilities.thinkingLevels` and merges the patch — with `google` and `output_config_effort` families, per-provider legality in the coverage evidence matrix (`docs/_evidence/thinking-coverage-2026-09-05.md`), and per-provider declared-level tables.
-- [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): kernel `applyDefaultProviderRequestOptions` constructs session/cache/thinking; `createSessionCachePolicy` and other `ProviderRequestPolicy` hooks are overlays; merge legacy/structured cache options safely.
-- [Provider packages](provider-packages.md): all provider adapters ship as `@arnilo/prism-providers/<adapter>` subpaths (importing one adapter never evaluates another); define explicit provider packages, model metadata, auth descriptors, request/cache overlays, 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. Prism constructs valid requests (session correlation, cache defaults, thinking intent); hosts own credentials/OAuth/env/overlays. 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/hyper`](providers/hyper.md) (Charm Hyper, dual-route Anthropic/OpenAI plus explicit `/v1/responses` pass-through, `reasoning_effort`, caller-gated `listHyperModels`, Hypercredit cost telemetry, `402` billing semantics), [`@arnilo/prism-providers/commandcode`](providers/commandcode.md) (Command Code Provider API, server-enforced dual-route Anthropic/OpenAI, optional ZDR, caller-gated `listCommandCodeModels`, off-peak/deal pricing caveats), [`@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, plus the cross-vendor `@arnilo/prism-providers/model-discovery` model-list/capability discovery adapters (OpenAI-compatible + Google, provenance + TTL cache, see model-registry.md).
-  - 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).
+
+- [Embeddings](embeddings.md): provider-neutral batch `embedMany` contract with OpenAI-compatible and DashScope adapters.
+- [Speech and transcription](speech.md): provider-neutral synthesis and transcription contracts with streaming variants.
+- [Image generation and editing](image-generation.md): provider-neutral generate/edit contract with OpenAI and DashScope adapters.
+- [Moderation](moderation.md): provider-neutral classification under a neutral vocabulary; scores are provider output.
+- [Batch jobs](batch-jobs.md): provider-neutral submit/status/cancel/results contract with OpenAI Files-API adapter.
+- [Provider primitives](provider-primitives.md): shared bounded transport and OpenAI serialization helpers across providers.
+- [Provider layer](provider-layer.md): register host-owned providers/models, duplicate policy, streaming, mock provider.
+- [Model registry](model-registry.md): register `ModelConfig` records with capabilities, limits, cost, cache metadata.
+- [Provider caching](provider-caching.md): `PromptCacheHints`, stable-prefix guidance, per-provider cache matrix, cache telemetry.
+- [Thinking and reasoning](thinking-and-reasoning.md): `thinkingLevel` snapping to per-model capability families with legality evidence.
+- [Use-case model selection](use-case-model-selection.md): bind models for compaction, memory, and other non-session LLM jobs.
+- [Provider request policies](provider-request-policies.md): kernel request-option defaults with host `ProviderRequestPolicy` overlays.
+- [Provider packages](provider-packages.md): all adapters as `@arnilo/prism-providers/<adapter>` subpaths; tool_result and event wire shapes stay provider-neutral.
+  - First-party adapters: [`openai`](providers/openai.md), [`anthropic`](providers/anthropic.md), [`google`](providers/google.md), [`opencode-go`](providers/opencode-go.md), [`openrouter`](providers/openrouter.md), [`zai`](providers/zai.md), [`deepseek`](providers/deepseek.md), [`xai`](providers/xai.md), [`clinepass`](providers/clinepass.md), [`hyper`](providers/hyper.md), [`commandcode`](providers/commandcode.md), [`kimi`](providers/kimi.md), [`alibaba`](providers/alibaba.md), [`ollama`](providers/ollama.md), [`neuralwatt`](providers/neuralwatt.md), plus the cross-vendor `model-discovery` listing adapters on the same page.
+  - Enterprise cloud (workload identity): [`azure`](providers/azure.md) (Entra/Foundry), [`bedrock`](providers/bedrock.md) (IAM/SigV4), [`vertex`](providers/vertex.md) (ADC/Vertex).
+  - Optional AI SDK adapter: [`ai-sdk`](providers/ai-sdk.md) maps host-owned pinned `LanguageModelV4` models onto Prism streams.
+- [OpenAI-compatible provider](providers/openai-compatible.md): base Chat Completions subpath with strict-completion default and vendor hooks.
 
 ## Input, prompt, and context assembly
-- [SDK customization guide](customization.md): map provider resolution, middleware, context, builders, injectors, loops, compaction, retry, stores, and skills to explicit host-wired APIs.
-- [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 (now including `"video"`), typed video generation contract + DashScope adapter, 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-core/governance/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-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.
+
+- [SDK customization guide](customization.md): map every replaceable seam — providers, middleware, loops, stores — to explicit host wiring.
+- [Input and prompt assembly](input-and-prompt-assembly.md): input-to-message builders, cache-aware ordering, optional context-budget eviction.
+- [Multimodal content](multimodal-content.md): media resolution, SSRF/MIME policy, capability tags, video generation contract.
+- [System prompts](system-prompts.md): layered system prompts plus trust-gated `AGENTS.md`/`SYSTEM.md` file auto-load.
+- [Versioned prompt registry](prompt-registry.md): immutable content-hashed prompt assets with durable stores and bounded diff.
+- [Instruction injection](instruction-injection.md): package injectors layer redacted instructions without granting capabilities.
+- [Context and skills](context-and-skills.md): ordered context providers, progressive skill disclosure, fail-closed activation.
+- [LLM Wiki](wiki.md): optional knowledge compiler emitting OKF bundles with on-device hybrid search.
+- [Retrieval-augmented generation](rag.md): bounded source lifecycle, hybrid retrieval, reranking, citations, inert 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, 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-coding-tools/openapi` `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/prism-core/README.md): optional `@arnilo/prism-core/validation/json-schema` adapter for `tool.parameters`.
-- [MCP client bridge and server exposure](mcp-tools.md): modular TypeScript SDK v2 (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0) dual-era 2026-07-28/2025 client bridge and serving — bounded tools/resources/prompts, host-owned elicitation/sampling callbacks (roots/sampling deprecated with SEP-2577), exact-origin DNS-pinned client transport, MRTR auto-fulfilment, modern subscriptions and cache hints. 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 `@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-core/integrations/work` 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-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-coding-tools/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-coding-tools/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-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-coding-tools/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-tools/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).
+
+- [Recoverable tool effects](tool-effects.md): effect declarations, claim/CAS store, unknown reconciliation classifications.
+- [Tools](tools.md): host-owned tool registration, allow/deny filtering, bounded artifact-loop dispatch, progressive loading.
+- [OpenAPI tools adapter](openapi-tools.md): compile allow-listed OpenAPI 3.1 operations into bounded, approval-gated tools.
+- [Tool execution primitives](tool-execution-primitives.md): bounded JSON Schema validation, parallel dispatch, MCP bridge mapping.
+- [Tool validator JSON Schema package](../packages/prism-core/README.md): optional `@arnilo/prism-core/validation/json-schema` adapter.
+- [MCP client bridge and server exposure](mcp-tools.md): SDK v2 bridge and serving with OAuth transports and DNS-pinned transport.
+- [Web search, fetch, and extraction](web-tools.md): Brave/Exa/Firecrawl tools with finite limits and untrusted-content boundaries.
+- [Work tools](work-tools.md): identity-scoped M365/GWS connectors — draft-then-approve, isolated subprocess environments.
+- [Work connectors](work-connectors.md): connector principles, capability gates, scoped OAuth establishment, out-of-scope boundaries.
+- [Browser automation](browser-automation.md): Playwright-backed browser tools with egress policy, caps, and verified checkpoints.
+- [Device adapters](device-adapters.md): deny-by-default realtime voice/desktop-control contract with consent and sandbox gating.
+- [Linux desktop control](computer-use-linux.md): optional `computer-use-linux` MCP wrapper — doctor-first, approval-gated mutators.
+- [Obscura browser engine](obscura.md): optional host-binary browser engine adapter with fail-closed lifecycle and CDP composition.
+- [Coding agent tools](coding-agent-tools.md): shell/read/write/edit/search toolset with caps, document reader, and optional Git awareness.
+- [Document reader](document-reader.md): bounded PDF/DOCX text extraction behind `createReadTool({ documentReader })`.
+- [Indexed code search](indexed-code-search.md): host-owned incremental index seam; results labeled `untrusted_index`.
+- [Coding workspaces](coding-workspaces.md): worktree lifecycle with CheckpointStore CAS records and LeaseStore fencing.
+- [Coding review and diagnostics](coding-review-and-diagnostics.md): bounded patch-review manifests and normalized LSP diagnostics.
+- [Language intelligence](language-intelligence.md): bounded LSP client with lazy spawn, URI confinement, policy-gated rename.
+- [Process sessions](process-sessions.md): long-running process registry with durable recovery and fail-closed ownership.
+- [Forge integration](forge-integration.md): reference GitHub adapter — every mutation policy-gated and effect-recorded.
+- [Coding execution approval and sandboxing](coding-security.md): path/command approval, workspace modes, Docker/native sandboxes, egress allow-listing.
 
 ## 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).
+
+- [Documents, spreadsheets, and presentations](documents.md): OOXML generation, parsing, patching, and bounded preview for Office formats.
+- [Spreadsheets and CSV data](sheets.md): fail-closed XLSX/CSV ingestion with decimal-safety guarantees.
+- [Diagrams and mxGraph embed](diagrams.md): origin-enforced draw.io embed client with XXE-safe XML validation.
 
 ## 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.
-- [Extension kernel and event bus](extensions.md): load host-provided extensions in order, register contributions, emit lifecycle events, and isolate extension errors.
-- [Extension authoring guide](extension-authoring.md): publish third-party extension packages that register inert contributions and show host-owned activation, trust, permissions, redaction, and no-sandbox boundaries.
-- [Middleware hooks](middleware-hooks.md): ordered hook registry for provider, input, context, tool, retry, compaction, and session lifecycle boundaries.
+
+- [Contribution discovery (workspace)](contribution-discovery.md): realpath-contained `SKILL.md`/manifest scanner producing inert envelopes.
+- [Contribution registries](contribution-registries.md): explicit host-owned registries with strict duplicate shadowing prevention.
+- [Extension kernel and event bus](extensions.md): ordered extension loading, registration, lifecycle events, error isolation.
+- [Extension authoring guide](extension-authoring.md): publish third-party extensions with host-owned activation and trust boundaries.
+- [Middleware hooks](middleware-hooks.md): ordered hooks for provider, input, tool, retry, compaction, and session boundaries.
 
 ## Configuration/manifests
-- [Configuration and manifests](configuration-and-manifests.md): merge in-memory JSON config layers and validate data-only package manifests with prototype-pollution key rejection.
-- [Node filesystem config loader](node-filesystem-config.md): explicitly read caller-named JSON config files in Node hosts.
-- [Resource loading](resource-loading.md): decode text, JSON, binary, and manifests through caller-provided loaders; bridge host-authorized artifacts to bounded RAG document loading.
+
+- [Configuration and manifests](configuration-and-manifests.md): layered JSON config merge with data-only manifest validation.
+- [Node filesystem config loader](node-filesystem-config.md): explicitly read caller-named JSON config files in Node.
+- [Resource loading](resource-loading.md): decode text/JSON/binary through caller-provided loaders; RAG bridge.
 
 ## 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, HMAC-signed DNS-pinned outbound webhooks, plus health/drain/rate-limit/replay/deployment-lease seams; explicit bounds and zero default exposure.
+
+- [Web-standard server handler](server.md): framework-free authorized agent/SSE handler with durable reconnect and webhook seams.
 
 ## 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.
-- [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).
-- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional `@arnilo/prism-ag-ui` full AG-UI 0.0.59 input/event/capability mapper, authorized Web handler/distributed source follow, opt-in A2UI painting middleware, explicit hardened MCP/MCP Apps/remote A2A adapters, a framework-free reference renderer subpath (`@arnilo/prism-ag-ui/renderer`, 0.0.26), and stable ACP sibling over shared redacted event and durable-approval seams; 0.0.14 adds reconnectable co-work events.
-- [ACP coding-host interop](acp.md): stable ACP v1 `createPrismAcpAgent()`/`createAcpEventMapper()` over `@agentclientprotocol/sdk@1.3.0` — capability advertisement is a pure function of host seams (sessions load/list/delete/resume/dirs, close always, prompt media/embedded, MCP http/sse), client fs/terminal adapters, modes and config options as host overlays, `CodingLifecycleEvent` mapping, four-outcome approvals with elicitation, and frozen caps (0.0.27); 0.1.1 adds ownership-scoped persistence guidance for host-persisted modes/config (plan 013 Task 5 — the agent never persists them); 0.1.6 adds the optional host-owned `AcpSessionStore` durability seam — live registry (modes/config/cwd/ownership) survives agent restart, restore is ownership-scoped and fail-closed (plan 018 Task 2). 0.2.6 adds durable run recovery (plan 026 Task 5): bounded `activeRun` refs on persisted sessions, restart re-resolution against `AgentRunLifecycle` (suspended → pending approval ids, terminal → terminal, unprovable in-flight → unknown, never a restarted prompt), and durable ownership/version/fence-checked cancellation that never replays tools; docs/migration.md records the additive-field decision and the 0.2.5 → 0.2.6 downgrade rules. 0.2.8 (plan 028) adds `session/load`/`session/resume` transcript replay (bounded, redacted chunks from the `sessions.transcript` seam), truthful `usage_update`, per-type `set_config_option` gates, explicit tool `kind` metadata, run-level error mapping, permission wire alignment, `agent_thought_chunk`, and the spawnable entrypoint; UNSTABLE-gated `plan_update`/`plan_removed` from coding plan lifecycle events (F5, client must advertise `ClientCapabilities.plan`); host-owned `session_info_update` titles and title pass-through in `session/list` (F6, `sessions.title` seam); opt-in `createCodingToolProjection()` for first-party edit/write diffs+locations (F7, deny-by-default unchanged); projected `toolResult` images as ACP content/image blocks (F8, `acpImageBytes` cap); host-owned slash commands as `available_commands_update` (F9, `acpCommandsPerUpdate` cap).
-- [Spawnable ACP agent](acp-agent.md): `@arnilo/prism-acp-agent` — a ~200-line bin serving `createPrismAcpAgent` over stdio from a validated config file (single local user, coding tools bound to one workspace, sqlite/memory session store, MCP allow-list, modes/config options, mock provider by default; 0.2.8 plan 028 Task 10).
-- [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.
+
+- [Multi-agent patterns (handoff/crew/supervisor/A2A)](multi-agent-patterns.md): decision table for handoff, crew, supervisor, and A2A.
+- [Supervisor delegation](supervisors.md): child allow-lists, narrowed permissions, finite budgets, nested delegation.
+- [A2A interoperability](a2a.md): A2A 1.0 cards, durable task seams, verified client, AG-UI fronting.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): AG-UI event mapping, A2UI middleware, hardened MCP/A2A adapters, ACP sibling.
+- [ACP coding-host interop](acp.md): stable ACP v1 agent with capability advertisement, approvals, durability, and projections.
+- [Spawnable ACP agent](acp-agent.md): stdio bin serving `createPrismAcpAgent` from a validated config file.
+- [AG-UI adoption evaluation](ag-ui-adoption.md): official AG-UI matrix and shipped handshake boundaries.
 
 ## CLI/RPC
-- [Dev inspector](dev-inspector.md): optional `@arnilo/prism-coding-tools/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-core/runtime/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.
+
+- [Dev inspector](dev-inspector.md): loopback-only local playground over a configured agent; `prism dev` composition.
+- [CLI/RPC](cli-rpc.md): print/json modes, LF-delimited RPC, `prism init` scaffold, provider scaffolding.
+- [Workflows](workflows.md): typed bounded DAG orchestration with durable suspend/resume, schedules, sagas.
 
 ## Security and credentials
-- [Host security guide](host-security.md): fail-closed checklist for supply-chain/attestation/canary isolation, bounded credentials, AG-UI/ACP/A2A/web remote boundaries, untrusted external content, settings, redaction, trust roots, workflow ownership, coding I/O, permissions, PostgreSQL TLS/roles/cleanup, persistence, extensions, and tool validation; **0.1.0 security evidence** (plan 012 Task 6): moderate audit policy, named threat-suites leg (`npm run security:threat-suites`), supply-chain negative fixtures, blocked-gate canary semantics.
-- [Security/auth/trust](settings-auth-trust-security.md): settings providers, credential helpers, trust/permission policies, redaction controls, host-owned settings/credentials wiring outside `AgentConfig`, and security-boundary hardening summary.
-- [Credentials and redaction](credentials-and-redaction.md): compose explicit credential resolver order, use caller-supplied env objects/OAuth refresh + revoke helpers, resolve credentials only at the provider edge, redact known secret values, and follow the provider-authorized subscription OAuth matrix; 0.2.1 adds the shared bounded device/token flow (core `pollDeviceCodeToken`, fail-closed token shape) behind both the OpenAI Codex and OAuth 2.0 providers.
-- [Credential storage](credential-storage.md): optional `@arnilo/prism-core/credentials/node` adapter with strict bounded AES-GCM envelopes, async finite scrypt, restrictive Unix files, abort-aware bounded system-keychain calls, optional host-KMS wrap (`encryptWithHostKms`), and 0.0.14 Microsoft 365 / Google Workspace OAuth providers (PKCE/device-code, least-privilege scope bundles, per-identity work-token bridge); `./oidc` subpath adds the OIDC/JWKS identity verifier; 0.2.1 makes the JWKS fetch DNS-pinned (core `pinnedFetch`, redirect-free, byte-bounded).
+
+- [Host security guide](host-security.md): fail-closed checklist across supply chain, boundaries, redaction, trust, persistence.
+- [Security/auth/trust](settings-auth-trust-security.md): settings providers, trust/permission policies, host-owned wiring.
+- [Credentials and redaction](credentials-and-redaction.md): resolver order, env/OAuth helpers, provider-edge resolution, secret redaction.
+- [Credential storage](credential-storage.md): bounded AES-GCM adapter, system keychain, host-KMS wrap, work/OIDC subpaths.
 
 ## Testing and examples
-- [Live and end-to-end testing](live-testing.md): run the opt-in live matrix (`npm run test:live`) against real credentials with a skip-not-fail contract, per-provider model overrides, strict release-gate mode, the full suite → env-var → least-privilege-scope → cost credential table (generated from `scripts/live-matrix.json` and kept in sync by `scripts/live-doc-check.test.mjs`), the scheduled strict CI canaries, and the functional-surface 100% coverage definition with its line-ratchet caveat.
+
+- [Live and end-to-end testing](live-testing.md): opt-in live matrix with skip-not-fail contract and credential scoping table.
 - Provider test doubles: `createMockProvider()` and provider event helpers are documented on the canonical Provider layer page above.
-- [Provider conformance](provider-conformance.md): run network-free provider adapter assertions (stream order, abort, tool-call reconstruction, cache usage, content coverage, protected header ownership, secret leak) from `@arnilo/prism/testing/provider-conformance`.
-- [Session store conformance](session-store-conformance.md): assert any `SessionStore` adapter satisfies append/idempotency/conflict/branch invariants from `@arnilo/prism/testing/session-store-conformance`.
-- [Run ledger conformance](run-ledger-conformance.md): assert durable run/event/tool/usage writes and reopen survival; batch-wrapper FIFO/bounds/flush checks remain separate. Run-feedback stores use `@arnilo/prism/testing/feedback` for append/query/delete/ownership linkage conformance.
-- [Compaction conformance](compaction-conformance.md): assert any `CompactionStrategy` returns a non-empty redacted summary and observes abort from `@arnilo/prism/testing/compaction-conformance`.
-- [Tool conformance](tool-conformance.md): assert the tool-dispatch blocked-reason matrix (unknown/denied/invalid/permission/validator) and success path from `@arnilo/prism/testing/tool-conformance`.
-- [Extension conformance](extension-conformance.md): assert an `Extension` setup runs, contributions stay inert, and setup errors are redacted or rethrown from `@arnilo/prism/testing/extension-conformance`.
-- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, [`examples/ag-ui-server.ts`](../examples/ag-ui-server.ts), [`examples/ag-ui-a2ui.ts`](../examples/ag-ui-a2ui.ts), [`examples/ag-ui-mcp-apps.ts`](../examples/ag-ui-mcp-apps.ts), [`examples/enterprise-identity.ts`](../examples/enterprise-identity.ts), [`examples/enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`examples/enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`examples/enterprise-postgres-state.ts`](../examples/enterprise-postgres-state.ts), [`examples/conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`examples/artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`examples/server-deployment-seams.ts`](../examples/server-deployment-seams.ts), cache-aware prompt assembly, NeuralWatt agent run ([`examples/neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts)), [`examples/provider-deepseek.ts`](../examples/provider-deepseek.ts), [`examples/provider-xai.ts`](../examples/provider-xai.ts), [`examples/provider-xai-oauth.ts`](../examples/provider-xai-oauth.ts), [`examples/provider-clinepass.ts`](../examples/provider-clinepass.ts), [`examples/impeccable.ts`](../examples/impeccable.ts), [`examples/coding-compaction.ts`](../examples/coding-compaction.ts), [`examples/acp-coding-host.ts`](../examples/acp-coding-host.ts), [`examples/caveman-ponytail.ts`](../examples/caveman-ponytail.ts), [`examples/graft-extension.ts`](../examples/graft-extension.ts), [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts), stores/branching, structured-output/artifact-loop, CLI, RPC, workflow orchestration).
+- [Provider conformance](provider-conformance.md): network-free adapter assertions from `@arnilo/prism/testing/provider-conformance`.
+- [Session store conformance](session-store-conformance.md): assert append/idempotency/conflict/branch invariants for any store.
+- [Run ledger conformance](run-ledger-conformance.md): assert durable run/usage writes and reopen survival.
+- [Compaction conformance](compaction-conformance.md): assert redacted non-empty summaries and abort observation.
+- [Tool conformance](tool-conformance.md): assert blocked-reason matrix and success-path dispatch behavior.
+- [Extension conformance](extension-conformance.md): assert inert contributions and redacted setup errors.
+- `examples/`: compile-checked typed examples ([`conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`enterprise-identity.ts`](../examples/enterprise-identity.ts), [`enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`server-deployment-seams.ts`](../examples/server-deployment-seams.ts), [`neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts), [`cache-aware-prompt-assembly.ts`](../examples/cache-aware-prompt-assembly.ts), [`ag-ui-server.ts`](../examples/ag-ui-server.ts), [`acp-coding-host.ts`](../examples/acp-coding-host.ts), and more), plus runnable mock demos.
 
 ## Third-party integrations
-- [Caveman behavior integration](caveman.md): optional `@arnilo/prism-coding-tools/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-coding-tools/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-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.16.0` or `packageRoot`/`cliPath`; opt-in (not in code/sdk profiles or the `prism-all` umbrella).
-- [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-coding-tools/impeccable` — host `upstreamPath` to compiled Impeccable `SKILL.md`, skill + `/impeccable` → `load_skill`; no detector CLI, no live browser, not in code/sdk/all.
+
+- [Caveman behavior integration](caveman.md): upstream Caveman skills with injector, persistence, and progressive catalog.
+- [Ponytail behavior integration](ponytail.md): upstream Ponytail skills with injector and peer resolution; opt-in.
+- [Graft context-graph integration](graft.md): graft CLI pull tools, retrieval-pack context provider, blast-radius middleware.
+- [Impeccable behavior integration](impeccable.md): upstream Impeccable skill behind `load_skill`; host supplies the compiled `SKILL.md`.
 
 ## Release and install
-- [Release and install](release-and-install.md): current **0.5.4** package graph — generated inventory in the [package-inventory section](#package-inventory) and the release page — 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 0.4 to 0.5](migrate-to-0.5.md): the complete 0.5.x migration guide (plans 055–066) — 0.5.0 lockstep plus **0.5.1** additive request construction (`thinkingLevel` field, kernel session/cache defaults, OpenCode Go `ProviderRequirementError`) — plus rollback.
-- [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.
 
+- [Release and install](release-and-install.md): install rules, package graph, and deterministic resumable publication.
+- [Migrate 0.5](migrate-to-0.5.md): 0.4 → 0.5 migration guide with per-release sections and rollback.
+- [Documentation archive](history/README.md): frozen migration/history records — not read on the hot path.
+- [Review coverage archive](_evidence/): per-phase evidence freezes — audit trail, excluded from tarballs.
 
 ## Package inventory
 
@@ -180,15 +195,14 @@ The generated inventory below derives from [`scripts/package-truth.json`](../scr
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.5.4 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.5.4 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.5.4 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.5.4 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.5.4 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.5.4 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.5.4 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.5.4 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.5.4 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.5.4 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism` | 0.5.5 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-coding-tools` | 0.5.5 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.5.5 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
+| `@arnilo/prism-providers` | 0.5.5 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.5.5 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.5.5 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.5.5 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.5.5 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
+| `@arnilo/prism-office` | 0.5.5 | capability — /documents, /sheets, /diagrams subpaths |
+| `@arnilo/prism-web-tools` | 0.5.5 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
 <!-- generated:package-truth:inventory end -->
-

package/docs/migrate-to-0.5.md

@@ -1,6 +1,6 @@
 # Migrate Prism 0.4 to 0.5
 
-> **Status: 0.5.4** (run-limit HARD split from host policy on the 2026-09-08 `v0.5.3` tag). 0.5.0 covers plans 055–065. 0.5.1 adds kernel provider-request construction. 0.5.2 coalesces stream tokens. 0.5.3 folds content-only tool results.
+> **Status: 0.5.4** (run-limit HARD split from host policy, plan 067). 0.5.0 covers plans 055–065. 0.5.1 adds kernel provider-request construction. 0.5.2 coalesces stream tokens. 0.5.3 folds content-only tool results.
 
 ## What changes