@arnilo/prism 0.3.1 → 0.4.0

package/docs/release-and-install.md

@@ -2,22 +2,20 @@
 
 ## What it does
 
-Prism's current **0.3.1** line has **60 publishable manifests**: the root `@arnilo/prism` core package plus **59 workspace packages** — 17 provider adapters, 10 `prism-*` family/profile packages, and 32 capability packages. (Generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json` — the manifest-derived single source for counts, provider membership, umbrella closures, and profile closures.) The last lockstep cut was 0.3.0; Decision B now publishes changed packages independently inside `^0.3.0` — the plan 039 changed-package cut moved root `@arnilo/prism` and every plan-035+ changed package to **0.3.1** (obscura joined at its reviewed initial 0.3.0), and independent publication continues inside `^0.3.0` ranges (which satisfy 0.3.1). This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer range, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
+Prism's current **0.4.0** line has **11 publishable manifests**: the root `@arnilo/prism` core package plus **10 workspace packages** — 17 provider adapter subpaths (inside the `@arnilo/prism-providers` family), 3 `prism-*` family/profile packages, and 7 capability packages. (Generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json` — the manifest-derived single source for counts, provider membership, umbrella closures, and profile closures.) The last lockstep cut was 0.3.0; Decision B now publishes changed packages independently inside `^0.3.0` — the plan 039 changed-package cut moved root `@arnilo/prism` and every plan-035+ changed package to **0.3.1**, and the plan 050 changed-package cut moved root plus four changed packages to **0.3.2**; the plan 041-044 changed-package cut moves root to **0.3.3** with `@arnilo/prism-memory@0.3.2` (composite recall scoring), `@arnilo/prism-evals@0.3.1` (trace-to-dataset curation), the three session-store packages at **0.3.1** (run-ledger `promptVersion` provenance), and the initial `@arnilo/prism-prompts@0.0.1` (independent opt-in, outside `prism-all`); plan 054 consolidation then folded `@arnilo/prism-browser` and `@arnilo/prism-obscura` into the `@arnilo/prism-web-tools` family as `/browser` and `/obscura` subpaths, folded `@arnilo/prism-rag`, both compaction strategies, `@arnilo/prism-graft`, and `@arnilo/prism-wiki` into the `@arnilo/prism-memory` family as `/rag`, `/compaction/llm`, `/compaction/observational-memory`, `/graft`, and `/wiki` subpaths (deleting the `@arnilo/prism-compaction` profile), and folded all 17 `@arnilo/prism-provider-*` packages into the `@arnilo/prism-providers` family as `/<adapter>` subpaths (Azure/Bedrock/Vertex stop being special all-only manifests); independent publication continues inside `^0.3.0` ranges (which satisfy 0.3.1, 0.3.2, and 0.3.3). This page describes how they are packed, what each tarball contains, how to install them, the required non-optional **caret** `@arnilo/prism@^0.4.0` peer range, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
 
-Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package has a required `@arnilo/prism` peer inside the Decision B window — packages republishing in the plan 039 cut carry `^0.3.1`; unchanged packages keep their `^0.3.0` peer (both satisfy `@arnilo/prism@0.3.1`); profiles are pure manifests. The plan 039 republished set declares the required `@arnilo/prism@^0.3.1` peer; unchanged packages keep `^0.3.0`. Installation activates no provider, listener, database, browser, credential, or tool capability.
+Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package has a required `@arnilo/prism` peer inside the Decision B window — the caret current spec is `@arnilo/prism@^0.3.3` and every declared window peer satisfies it: packages republishing in the plan 050 cut carry `^0.3.2`; the plan 039 set keeps `^0.3.1`; unchanged packages keep their `^0.3.0` peer; profiles are pure manifests. The plan 050 republished set declares the required `@arnilo/prism@^0.3.2` peer; the plan 041-044 republished set keeps its existing `^0.3.0` window peer; unchanged packages keep their prior window. Installation activates no provider, listener, database, browser, credential, or tool capability.
 
-Current **58** publishable manifests (root + 57 workspace packages):
+Current **11** publishable manifests (root + 10 workspace packages):
 
-`@arnilo/prism`, `@arnilo/prism-ag-ui`, `@arnilo/prism-browser`, `@arnilo/prism-coding-agent`, `@arnilo/prism-coding-security`, `@arnilo/prism-compaction-llm`
-`@arnilo/prism-compaction-observational-memory`, `@arnilo/prism-credentials-node`, `@arnilo/prism-enterprise-postgres`, `@arnilo/prism-evals`, `@arnilo/prism-mcp`, `@arnilo/prism-memory`
-`@arnilo/prism-model-router`, `@arnilo/prism-observability-opentelemetry`, `@arnilo/prism-policy`, `@arnilo/prism-all`, `@arnilo/prism-base`, `@arnilo/prism-caveman`
-`@arnilo/prism-code`, `@arnilo/prism-compaction`, `@arnilo/prism-impeccable`, `@arnilo/prism-ponytail`, `@arnilo/prism-providers`, `@arnilo/prism-sdk`, `@arnilo/prism-provider-ai-sdk`
-`@arnilo/prism-provider-alibaba`, `@arnilo/prism-provider-anthropic`, `@arnilo/prism-provider-azure`, `@arnilo/prism-provider-bedrock`, `@arnilo/prism-provider-google`, `@arnilo/prism-provider-kimi`
-`@arnilo/prism-provider-neuralwatt`, `@arnilo/prism-provider-ollama`, `@arnilo/prism-provider-openai`, `@arnilo/prism-provider-opencode-go`, `@arnilo/prism-provider-openrouter`, `@arnilo/prism-provider-vertex`
-`@arnilo/prism-provider-clinepass`, `@arnilo/prism-provider-deepseek`, `@arnilo/prism-provider-xai`, `@arnilo/prism-provider-zai`, `@arnilo/prism-rag`, `@arnilo/prism-server`, `@arnilo/prism-session-store-codecs`, `@arnilo/prism-session-store-nats`, `@arnilo/prism-session-store-postgres`, `@arnilo/prism-session-store-sqlite`
-`@arnilo/prism-openapi-tools`, `@arnilo/prism-supervisor`, `@arnilo/prism-tool-validator-json-schema`, `@arnilo/prism-web-tools`, `@arnilo/prism-wiki`, `@arnilo/prism-work-tools`, `@arnilo/prism-workflows`, `@arnilo/prism-document-reader`, `@arnilo/prism-computer-use-linux`, `@arnilo/prism-antigravity-agent`, `@arnilo/prism-graft`, `@arnilo/prism-obscura`
+@arnilo/prism`, `@arnilo/prism-acp-agent`, `@arnilo/prism-ag-ui`, `@arnilo/prism-antigravity-agent`
+`@arnilo/prism-coding-tools`, `@arnilo/prism-core`, `@arnilo/prism-mcp`, `@arnilo/prism-memory`, `@arnilo/prism-office`
+`@arnilo/prism-providers/ai-sdk`, `@arnilo/prism-providers/alibaba`, `@arnilo/prism-providers/anthropic`, `@arnilo/prism-providers/azure`, `@arnilo/prism-providers/bedrock`
+`@arnilo/prism-providers/clinepass`, `@arnilo/prism-providers/deepseek`, `@arnilo/prism-providers/google`, `@arnilo/prism-providers/kimi`, `@arnilo/prism-providers/neuralwatt`, `@arnilo/prism-providers/ollama`
+`@arnilo/prism-providers/openai`, `@arnilo/prism-providers/opencode-go`, `@arnilo/prism-providers/openrouter`, `@arnilo/prism-providers/vertex`, `@arnilo/prism-providers/xai`, `@arnilo/prism-providers/zai`
+`@arnilo/prism-providers`, `@arnilo/prism-web-tools`
 
-Core ships `dist`, docs, templates, and `CHANGELOG.md`; code packages ship compiled output, README, license, and changelog. Family/profile packages ship manifest, README, and changelog. `@arnilo/prism-providers` includes all fourteen `@arnilo/prism-provider-*` packages in its family (Azure/Bedrock/Vertex stay on `@arnilo/prism-all`).
+Core ships `dist`, docs, templates, and `CHANGELOG.md`; code packages ship compiled output, README, license, and changelog. Family/profile packages ship manifest, README, and changelog. `@arnilo/prism-providers` is the unified provider family: all 17 adapters ship as `dist/<adapter>` subpaths in one tarball (Azure/Bedrock/Vertex included), with the required `@arnilo/prism` peer as the only dependency and `@ai-sdk/provider` an optional peer of `/ai-sdk`. `@arnilo/prism-core` provides the unified runtime, sessions, governance, credentials, enterprise persistence, and work integration family package. `@arnilo/prism-web-tools` provides the unified web tools family: root Brave/Exa/Firecrawl research tools plus `/browser` (Playwright-peer gated) and `/obscura` (host-binary + MCP gated) subpaths. `@arnilo/prism-memory` provides the unified memory and context family: root working/vector memory plus `/rag` (with `/rag/loaders` and `/rag/parsers`), `/compaction/llm`, `/compaction/observational-memory`, `/graft` (`@nanonets/graft` optional-peer gated), and `/wiki` subpaths, including the `prism-wiki` bin and bundled skills. `@arnilo/prism-dev` is the dev-only exception: publishable independently at `0.0.1` but deliberately omitted from `@arnilo/prism-all` and every profile package (plan 040 Task 1 — developer-time inspector, not a production dependency). It ships the `prism-dev` bin (`dist/src/cli.js`, plan 040 Task 4) and is also resolvable programmatically via the `@arnilo/prism-dev/cli` export for the core CLI's `prism dev` delegation. `@arnilo/prism-prompts` (plan 042) is publishable independently (initial cut `0.0.1`) and deliberately omitted from `@arnilo/prism-all` and every profile package — unlike `@arnilo/prism-memory` (which is an umbrella member), the versioned prompt registry is an explicit host opt-in like `@arnilo/prism-computer-use-linux`, with no first-party package depending on it and only the core peer plus an optional `@arnilo/prism-evals` peer for the promotion helper. `@arnilo/prism-office` (plan 054 Task 8, absorbing plans 051–053) is the unified office family: `/documents`, `/sheets`, and `/diagrams` subpaths in one tarball with exact-pinned `@office-open/{docx,xlsx,pptx,xml}` regular dependencies and an optional `playwright-core` peer for the diagrams live embed. Importing one subpath never evaluates another. The three draft names `@arnilo/prism-documents`/`sheets`/`diagrams` were never published.
 
 ## When to use it
 
@@ -30,18 +28,26 @@ Consumers install the core package for the runtime and add first-party packages
 | Operation | Command |
 | --- | --- |
 | Install core only | `npm install @arnilo/prism` |
-| Scaffold a minimal project | `npx --package @arnilo/prism prism init my-agent [--provider openai] [--with-workflows] [--with-evals]` |
-| Install core + provider family (14 of 17) | `npm install @arnilo/prism @arnilo/prism-providers` |
-| Install minimal safe profile | `npm install @arnilo/prism-base` |
-| Install compaction strategies only | `npm install @arnilo/prism @arnilo/prism-compaction` |
-| Install coding-agent profile | `npm install @arnilo/prism-code @arnilo/prism-provider-openai` |
-| Install application SDK profile | `npm install @arnilo/prism-sdk @arnilo/prism-provider-openai @arnilo/prism-session-store-sqlite` |
-| Install the broad umbrella | `npm install @arnilo/prism-all` |
-| Install core + a single provider | `npm install @arnilo/prism @arnilo/prism-provider-openai` |
+| Scaffold a minimal project | `npx --package @arnilo/prism prism init my-agent [--provider openai] [--template <name>] [--list-templates] [--with-workflows] [--with-evals]` |
+| Install core runtime & persistence family | `npm install @arnilo/prism @arnilo/prism-core` |
+| Install core + all 17 provider adapters | `npm install @arnilo/prism @arnilo/prism-providers` (import `@arnilo/prism-providers/<adapter>`) |
+| Install minimal runtime (replaces `@arnilo/prism-base`) | `npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-memory` |
+| Install compaction strategies only | `npm install @arnilo/prism @arnilo/prism-memory` |
+| Install memory + RAG context family | `npm install @arnilo/prism @arnilo/prism-memory` (RAG: `@arnilo/prism-memory/rag`) |
+| Install coding tools (replaces `@arnilo/prism-code`) | `npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-coding-tools @arnilo/prism-mcp @arnilo/prism-providers` |
+| Install application SDK (replaces `@arnilo/prism-sdk`) | `npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-mcp @arnilo/prism-providers` |
+| Install selected families (replaces `@arnilo/prism-all`) | `npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers @arnilo/prism-coding-tools @arnilo/prism-web-tools @arnilo/prism-memory @arnilo/prism-mcp` |
+| Install core + a single provider adapter | `npm install @arnilo/prism @arnilo/prism-providers` (import `@arnilo/prism-providers/openai`) |
 | 0.0.12 AG-UI (after release) | `npm install @arnilo/prism@0.0.12 @arnilo/prism-ag-ui@0.0.12` |
-| Install bounded web research tools | `npm install @arnilo/prism @arnilo/prism-web-tools @arnilo/prism-tool-validator-json-schema` |
-| Install browser automation tools | `npm install @arnilo/prism @arnilo/prism-browser playwright-core@1.61.0` |
-| Install Obscura browser-engine tools (host supplies the binary) | `npm install @arnilo/prism @arnilo/prism-obscura` |
+| Install bounded web research tools | `npm install @arnilo/prism @arnilo/prism-web-tools @arnilo/prism-core` |
+| Install browser automation tools (Playwright-peer gated `/browser`) | `npm install @arnilo/prism @arnilo/prism-web-tools playwright-core@1.61.0` |
+| Install Obscura browser-engine tools (host supplies the binary; `/obscura`) | `npm install @arnilo/prism @arnilo/prism-web-tools @arnilo/prism-mcp` |
+| Install RAG retrieval (memory family `/rag`) | `npm install @arnilo/prism @arnilo/prism-memory` |
+| Install the Wiki CLI and skills (memory family `/wiki`) | `npm install @arnilo/prism @arnilo/prism-memory` (`npx prism-wiki --help`) |
+| Install the Graft context-graph bridge (`/graft`, host supplies the CLI) | `npm install @arnilo/prism @arnilo/prism-memory` (+ host-installed `@nanonets/graft`) |
+| Install document/spreadsheet/presentation engine | `npm install @arnilo/prism @arnilo/prism-office` (import `@arnilo/prism-office/documents`) |
+| Install spreadsheet and CSV data engine | `npm install @arnilo/prism @arnilo/prism-office` (import `@arnilo/prism-office/sheets`) |
+| Install draw.io embed client & diagram engine | `npm install @arnilo/prism @arnilo/prism-office` (import `@arnilo/prism-office/diagrams`) |
 | Build everything (core + workspaces) | `npm run build` |
 | Delete all build output (explicit one-shot, see build notes) | `npm run clean` |
 | Run the default (network-free) test suite | `npm test` |
@@ -92,9 +98,9 @@ A packed tarball contains only public compiled output and release files:
 
 - `dist/**` compiled `.js` and `.d.ts` for every exported subpath.
 - Code packages ship `README.md`, `LICENSE`, and `CHANGELOG.md`; family/profile packages ship `README.md` and `CHANGELOG.md`.
-- The core tarball additionally ships the full `docs/` directory (the docs hub) and `templates/init/` used by `prism init`.
+- The core tarball additionally ships the full `docs/` directory (the docs hub), `templates/init/`, and the `templates/` gallery (e.g. `deep-research`) used by `prism init`.
 - `dist/cli.js` and the `bin` link in core.
-- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.3.1.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.3.1.tgz` / `arnilo-prism-compaction-<name>-0.3.1.tgz` / `arnilo-prism-coding-agent-0.3.1.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.3.1.tgz`; independent Decision B tags (e.g. `@arnilo/prism-obscura@0.3.0`, the 0.3.1 RAG engine patch) carry their own package version. Later independent package tags carry their own package version. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
+- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.4.0.tgz`; first-party packages produce `arnilo-prism-providers-0.3.1.tgz` (all 17 adapters inside) / `arnilo-prism-coding-agent-0.3.2.tgz`; family/profile packages produce `arnilo-prism-{base,code,sdk,all}-0.3.x.tgz`; independent Decision B tags (e.g. `@arnilo/prism-obscura@0.3.0`, the 0.3.1 RAG engine patch) carry their own package version. Later independent package tags carry their own package version. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
 
 Excluded from every tarball by `files` negation:
 
@@ -104,7 +110,8 @@ Excluded from every tarball by `files` negation:
 
 `sideEffects` is `false` for every first-party package (their entrypoints export only types and declarations). Core sets `sideEffects: ["dist/cli.js"]` because `src/cli.ts` runs the CLI and sets `process.exitCode` at import time; every other core entrypoint is side-effect-free.
 
-`prism init` generates a private TypeScript project whose default dependency set is only `@arnilo/prism` (plus TypeScript tooling as `devDependencies`). Provider and `--with-workflows` / `--with-evals` flags add only the selected optional packages. Measured default clean install is ~27.5 MB versus the Mastra scaffold baseline of 439 MB.
+`prism init` generates a private TypeScript project. The default dependency set for standard `init` is only `@arnilo/prism` (plus TypeScript tooling as `devDependencies`). Provider and `--with-workflows` / `--with-evals` flags add only the selected optional packages. Using `--template deep-research` scaffolds a multi-step research agent wired with `@arnilo/prism-web-tools`, `@arnilo/prism-memory`, and `@arnilo/prism-workflows`. All templates ship inside the `@arnilo/prism` tarball (`templates/`), have zero credentials at init, contain no postinstall scripts, and pass secret scans. Measured default clean install is ~27.5 MB versus the Mastra scaffold baseline of 439 MB.
+
 
 ## Request/response example
 
@@ -115,7 +122,7 @@ Excluded from every tarball by `files` negation:
   "dependencies": {
     "@arnilo/prism": "^0.3.0",
     "@arnilo/prism-enterprise-postgres": "^0.3.0",
-    "@arnilo/prism-provider-openai": "^0.3.0"
+    "@arnilo/prism-providers/openai": "^0.3.0"
   }
 }
 ```
@@ -125,7 +132,7 @@ Installing the provider/compaction packages without `@arnilo/prism` present prod
 ```text
 npm error code ERESOLVE
 npm error Could not resolve dependency:
-npm error peer @arnilo/prism@"^0.3.0" from @arnilo/prism-provider-openai@0.3.0
+npm error peer @arnilo/prism@"^0.3.0" from @arnilo/prism-providers/openai@0.3.0
 ```
 
 ## Implementation example
@@ -165,6 +172,17 @@ npm run release:check -- --allow-dirty --allow-untagged
 npm run release:publish -- --dry-run --allow-dirty --allow-untagged
 ```
 
+### 0.3.2 independent workflow patch (plan 045)
+
+`@arnilo/prism-workflows@0.3.2` is the independent bounded-loop release: durable iteration checkpoints, tool-body resume, replay events, redaction/bounds, and the frozen `maxNodes`/`maxIterations` accounting rule. The root remains `@arnilo/prism@0.3.3`; no generic checkpoint-store or SQL migration is required. Publish from a clean commit tagged `@arnilo/prism-workflows@0.3.2` after the independent release gate; local preview is:
+
+```bash
+npm run release:check -- --allow-dirty --allow-untagged
+npm run release:publish -- --dry-run --allow-dirty --allow-untagged
+```
+
+Rollback restores `@arnilo/prism-workflows@0.3.1`; persisted checkpoints remain readable because iteration records are additive.
+
 `--allow-dirty` and `--allow-untagged` exist only for local preview; real publication and CI never pass them. npm registry calls occur only in these release preflight/publication commands, never build/test/package discovery.
 
 Optional live smoke tests stay separate from SDK readiness because they require credentials and network access:
@@ -402,9 +420,56 @@ node scripts/release.mjs publish --independent --baseline c600eaa18f65b56764ec2f
 
 **Compat.** Baselines regenerated (`--update-baseline`): version literal, obscura `connectObscuraCdp`/`createObscuraWebTools` types, plan 036/037 additive exports. **Rollback:** restore the pre-cut manifests/tags. Publication remains the operator handoff — this task does not publish.
 
+### 0.3.2 changed-package cut (plan 050 Task 12)
+
+**Decision: GO when the operator prerequisites below are recorded.** The plan 050 cut covers the clay-integration-findings remediation and the OKF wiki adoption: baseline `edb4fcf` (the parent of the plan 050 implementation work); five packages publish in dependency order — root `@arnilo/prism` (FEATURE-1 agent-definition model override fallback, FEATURE-3 command driver hooks, FEATURE-2/6 docs+example, DOCS-1 contracts), `@arnilo/prism-coding-agent` (BUG-1 `allowCustom` default + optional `toolCallId`), `@arnilo/prism-supervisor` (BUG-2 child-factory `Agent` guard, FEATURE-4 opt-in child event passthrough), `@arnilo/prism-wiki` (OKF v0.2 bundle emission, 0.0.2 → 0.0.3), and `@arnilo/prism-acp-agent` (sqlite `:memory:` pass-through fix, 0.0.x-style patch 0.3.1 → 0.3.2). Every unchanged package stays byte-identical; docs-only packages (`@arnilo/prism-workflows`, `@arnilo/prism-compaction-observational-memory`) do not bump. Republished packages carry `^0.3.2` root peers; unchanged packages keep their window peers. Docs-only change on the root: none of the deltas are breaking (additive fields and fail-closed guards), compat additive-only, no migration.
+
+```bash
+node scripts/release.mjs changed --baseline edb4fcf   # 5 packages
+# per-package: node scripts/release.mjs bump --package <name> --type patch (regenerates the lockfile)
+npm run sdk:ready   # blocked only by the protected PRISM_TEST_POSTGRES_URL row (pre-existing)
+node scripts/release.mjs check --independent --baseline edb4fcf --allow-dirty --allow-untagged
+node scripts/release.mjs publish --independent --baseline edb4fcf --dry-run
+# publish tags (operator handoff; not this task): push the 5 annotated
+# `<name>@<version>` package tags (e.g. @arnilo/prism@0.3.2,
+# @arnilo/prism-wiki@0.0.3) — release.yml's publish job runs deterministic
+# release:publish in dependency order with OIDC provenance.
+```
+
+**Rollback:** restore the pre-cut manifests/tags. No persisted shape changed (BUG-1/BUG-2 guards and the acp-agent `:memory:` fix are fail-closed tightenings). Publication remains the operator handoff — this task does not publish.
+
+### 0.4.0 publish handoff (plan 054 Task 9)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.4.0** is the package-consolidation lockstep cut: 11 active manifests (root + 10 workspace families/interop/office) at **0.4.0** with `@arnilo/prism@^0.4.0` peers. 54 retired 0.3 names are not republished as shims. After the 0.4 tarballs and `docs/migrate-to-0.4.md` are public, `node scripts/phase54-legacy-registry.mjs --apply --confirm` tags each retired name `legacy` and deprecates `<0.4.0`. Store compatibility with 0.3.3: **compatible, no persisted-shape migration**. Rollback = exact 0.3 pins.
+
+```bash
+npm run sdk:ready
+npm run release:check -- --lockstep --version 0.4.0 --allow-dirty --allow-untagged
+npm run release:publish -- --lockstep --version 0.4.0 --dry-run --allow-dirty --allow-untagged --report release-artifacts/publish-dry-run.json
+node scripts/phase54-legacy-registry.mjs --dry-run
+# operator: clean tree, tag v0.4.0, publish, then --apply --confirm
+```
+
+**Rollback notes.** Rollback = restore 0.3.x exact pins. No store migration.
+
+### 0.3.3 publish handoff (plans 041-044 Task 3)
+
+**Decision: GO when the operator prerequisites below are recorded.** The plan 041-044 cut covers the four outstanding feature plans on the 0.3.x line: baseline `1171575` (the plan-040 commit, parent of all four plans' uncommitted implementation work). Six publishable changes in dependency order — root `@arnilo/prism` **0.3.2 → 0.3.3** (progressive tool loading `search_tools` disclosure + `toolsSearch`/`toolsDisclosure` config, run-ledger `promptVersion` ref with `PERSISTENCE_SCHEMA_VERSION` 8 → 9, docs for the prompt registry and composite memory scoring, memory package truth), `@arnilo/prism-session-store-codecs` / `@arnilo/prism-session-store-sqlite` / `@arnilo/prism-session-store-postgres` **0.3.0 → 0.3.1** (nullable `prompt_version` column + additive checked migrations), `@arnilo/prism-evals` **0.3.0 → 0.3.1** (trace-to-dataset curation `datasetFromRuns`), and `@arnilo/prism-memory` **0.3.1 → 0.3.2** (composite recall scoring `RecallOptions.scoring`, `importance` record field + ADD COLUMN, `importanceFrom` write hook). `@arnilo/prism-prompts` publishes new at its reviewed initial **0.0.1** (independent host opt-in like the versioned prompt registry — not in `prism-all`, no first-party dependency). Unchanged packages stay byte-identical; `@arnilo/prism-dev`/`@arnilo/prism-graft`/`@arnilo/prism-ponytail` stay at their reviewed initial versions. Republished set keeps the `^0.3.0` Decision B root-peer window; unchanged packages keep their window peers. Additive-only compat (new exports + the two documented literal changes: `PERSISTENCE_SCHEMA_VERSION` literal and the CLI `usage` string; baselines regenerated with `--update-baseline`, no `--allow-break`, no migration).
+
+```bash
+node scripts/release.mjs changed --baseline 1171575   # root + memory + evals + 3 stores (+ prompts as new)
+PRISM_TEST_POSTGRES_URL=... node scripts/release-skip-manifest.mjs
+PRISM_TEST_POSTGRES_URL=... npm run release:gate
+node scripts/release.mjs check --independent --baseline 1171575 --allow-dirty --allow-untagged
+node scripts/release.mjs publish --independent --baseline 1171575 --dry-run --allow-dirty --allow-untagged
+# publish tags (operator handoff; not this task): push the annotated
+# `<name>@<version>` package tags — release.yml's publish job runs
+# deterministic release:publish in dependency order with OIDC provenance.
+```
+
 ### 0.2.9 publish handoff (plan 029 Task 10)
 
-**Decision: GO when the operator prerequisites below are recorded.** Release **0.2.9** (plan 029) is the provider-adoption and behavior-packages cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.9: expected deltas are the version literal plus the new provider/OAuth/impeccable exports and the form-urlencoded `pollDeviceCodeToken` options; zero removals; baselines regenerated with `--update-baseline`, no `--allow-break`). Ships `@arnilo/prism-provider-deepseek`, `@arnilo/prism-provider-xai` (API key + SuperGrok RFC 8628), `@arnilo/prism-provider-clinepass`, and `@arnilo/prism-impeccable`. Ponytail peer `^4.9.0` (bare `/ponytail` reports status). Caveman registers extra `SKILL.md`. SuperGrok is host-invoked; Cline WorkOS, DeepSeek `/anthropic`, grok-cli file scan, harness/Cordis/Muse, Caveman 2 engine, and Impeccable live detector stay out. Release graph is **55** publishable manifests at exact **0.2.9** (root + 54 workspace). Store compatibility with 0.2.8: **compatible, no migration**.
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.2.9** (plan 029) is the provider-adoption and behavior-packages cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.9: expected deltas are the version literal plus the new provider/OAuth/impeccable exports and the form-urlencoded `pollDeviceCodeToken` options; zero removals; baselines regenerated with `--update-baseline`, no `--allow-break`). Ships `@arnilo/prism-providers/deepseek`, `@arnilo/prism-providers/xai` (API key + SuperGrok RFC 8628), `@arnilo/prism-providers/clinepass`, and `@arnilo/prism-impeccable`. Ponytail peer `^4.9.0` (bare `/ponytail` reports status). Caveman registers extra `SKILL.md`. SuperGrok is host-invoked; Cline WorkOS, DeepSeek `/anthropic`, grok-cli file scan, harness/Cordis/Muse, Caveman 2 engine, and Impeccable live detector stay out. Release graph is **55** publishable manifests at exact **0.2.9** (root + 54 workspace). Store compatibility with 0.2.8: **compatible, no migration**.
 
 **Rollback notes.** Rollback = restore the 0.2.8 manifests/tag. No persisted 0.2.8 shape changed; the added packages simply disappear.
 
@@ -854,25 +919,25 @@ Default `npm test`, `npm run sdk:ready`, and `benchmark-0.0.15` are network-free
 
 | Surface | Gate and credential | Checked-in/protected command | Canary scope |
 | --- | --- | --- | --- |
-| OpenAI Responses baseline | `PRISM_LIVE_PROVIDER_TESTS=1` + `OPENAI_API_KEY` | `npm test -w @arnilo/prism-provider-openai` | Bounded text/tool/abort smoke; key never enters events. |
+| OpenAI Responses baseline | `PRISM_LIVE_PROVIDER_TESTS=1` + `OPENAI_API_KEY` | `npm test -w @arnilo/prism-providers/openai` | Bounded text/tool/abort smoke; key never enters events. |
 | OpenAI hosted tools + Realtime | `OPENAI_API_KEY`; protected release harness additionally supplies host-owned safety identifier and hosted-tool entitlement | No generic fixture; record result with the release evidence | Provider-hosted `web_search`/similar execution and Realtime audio/interruption need account-specific availability, so fake transport coverage remains default gate. |
 | AI SDK adapter | Host-selected AI SDK v4 model factory plus its provider credential | No generic fixture; run host integration in protected release environment | Exact `@ai-sdk/provider@4.0.4` mapping/version check; Prism does not own upstream model credentials. |
-| Kimi / Moonshot | `PRISM_LIVE_PROVIDER_TESTS=1` + `KIMI_API_KEY` | `npm test -w @arnilo/prism-provider-kimi` | Coding route; Moonshot entitlement is account-specific. |
-| Z.AI | `PRISM_LIVE_PROVIDER_TESTS=1` + `ZAI_API_KEY` | `npm test -w @arnilo/prism-provider-zai` | GLM stream/tool/reasoning smoke. |
-| OpenRouter | `PRISM_LIVE_PROVIDER_TESTS=1` + `OPENROUTER_API_KEY` | `npm test -w @arnilo/prism-provider-openrouter` | Routed stream/model metadata smoke; host chooses permitted route. |
-| OpenCode Go | `PRISM_LIVE_PROVIDER_TESTS=1` + `OPENCODE_API_KEY` | `npm test -w @arnilo/prism-provider-opencode-go` | OpenAI/Anthropic route selection smoke. |
+| Kimi / Moonshot | `PRISM_LIVE_PROVIDER_TESTS=1` + `KIMI_API_KEY` | `npm test -w @arnilo/prism-providers/kimi` | Coding route; Moonshot entitlement is account-specific. |
+| Z.AI | `PRISM_LIVE_PROVIDER_TESTS=1` + `ZAI_API_KEY` | `npm test -w @arnilo/prism-providers/zai` | GLM stream/tool/reasoning smoke. |
+| OpenRouter | `PRISM_LIVE_PROVIDER_TESTS=1` + `OPENROUTER_API_KEY` | `npm test -w @arnilo/prism-providers/openrouter` | Routed stream/model metadata smoke; host chooses permitted route. |
+| OpenCode Go | `PRISM_LIVE_PROVIDER_TESTS=1` + `OPENCODE_API_KEY` | `npm test -w @arnilo/prism-providers/opencode-go` | OpenAI/Anthropic route selection smoke. |
 | Alibaba DashScope | Alibaba least-privilege API key | No generic fixture; host compatibility probe in protected release environment | Region/preset/catalog entitlement varies; offline serializer and catalog tests remain default gate. |
 | Ollama Cloud/local | Cloud API key or host-local authenticated endpoint | No generic fixture; host compatibility probe in protected release environment | Cloud account and local daemon/model availability are host-owned; no daemon starts during Prism tests. |
-| NeuralWatt | `PRISM_LIVE_PROVIDER_TESTS=1` + `NEURALWATT_API_KEY` | `npm test -w @arnilo/prism-provider-neuralwatt` | Stream/retry/quota telemetry smoke. |
-| Anthropic | `PRISM_LIVE_PROVIDER_TESTS=1` + `ANTHROPIC_API_KEY` | `npm test -w @arnilo/prism-provider-anthropic` | Restricted one-turn provider smoke. |
-| Google | `PRISM_LIVE_PROVIDER_TESTS=1` + `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `npm test -w @arnilo/prism-provider-google` | Restricted one-turn provider smoke. |
+| NeuralWatt | `PRISM_LIVE_PROVIDER_TESTS=1` + `NEURALWATT_API_KEY` | `npm test -w @arnilo/prism-providers/neuralwatt` | Stream/retry/quota telemetry smoke. |
+| Anthropic | `PRISM_LIVE_PROVIDER_TESTS=1` + `ANTHROPIC_API_KEY` | `npm test -w @arnilo/prism-providers/anthropic` | Restricted one-turn provider smoke. |
+| Google | `PRISM_LIVE_PROVIDER_TESTS=1` + `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `npm test -w @arnilo/prism-providers/google` | Restricted one-turn provider smoke. |
 | Memory PostgreSQL/pgvector | `PRISM_TEST_POSTGRES_URL` with `vector` extension | `npm run test:postgres -w @arnilo/prism-memory` | Shared memory conformance, export/rebuild pagination, and finite-vector boundary. |
 
 The scheduled/manual `live-canaries` workflow uses protected environment `live-canaries`; release validation uses its protected release environment. Neither workflow receives a broad workspace key. A successful offline benchmark is never evidence that a live row ran; each protected invocation must record its enabled matrix rows and skipped/missing prerequisites.
 
 ### Historical release notes
 
-Older 0.0.10–0.0.15 handoffs are summarized in [migration](migration.md); historical 43-package evidence remains there. The publishable package catalog includes `@arnilo/prism-provider-alibaba`, `@arnilo/prism-provider-ollama`, and `@arnilo/prism-session-store-codecs`; current publication uses the 47-manifest handoff above.
+Older 0.0.10–0.0.15 handoffs are summarized in [migration](migration.md); historical 43-package evidence remains there. The publishable package catalog includes `@arnilo/prism-providers/alibaba`, `@arnilo/prism-providers/ollama`, and `@arnilo/prism-session-store-codecs`; current publication uses the 47-manifest handoff above.
 
 ## 0.1.x compatibility and support matrix
 
@@ -885,7 +950,7 @@ Frozen by Phase 12 Task 0 in `scripts/phase12-freeze-manifest.json` (schema gate
 | Node | 20, 24 (`engines.node >=20`) | `release.yml`: `verify` runs SDK readiness on Node 24; `node20-compat` builds and imports every public root export on Node 20. Docs examples need Node >=22.6 native TypeScript stripping. Node 22 is engines-supported but not measured in CI at freeze. |
 | PostgreSQL | 16 | `release.yml` `postgres-integration` job with image `pgvector/pgvector:pg16`; driver `pg@^8.22.0`; schema version 6. The pgvector extension is required only by the `@arnilo/prism-memory` path. Range claims beyond 16 need an added protected leg before they may be documented. |
 | Platform | linux-x64 | Every CI leg runs on `ubuntu-latest` (x64). All other OS/arch combinations are untested: run `npm run sdk:ready` on the target platform before production adoption. |
-| Providers | every published `@arnilo/prism-provider-*` plus the OpenAI-compatible transport | Per-package conformance suites in the default network-free `npm test`; live canaries stay credential-gated (`PRISM_LIVE_PROVIDER_TESTS=1`). |
+| Providers | all 17 `@arnilo/prism-providers/<adapter>` subpaths plus the OpenAI-compatible transport | Per-package conformance suites in the default network-free `npm test`; live canaries stay credential-gated (`PRISM_LIVE_PROVIDER_TESTS=1`). |
 | Protocol SDKs | exact pins below | MCP 38-test suite, AG-UI/ACP/A2A protocol conformance, NATS JetStream event-source conformance. |
 
 | Package | Frozen pin |
@@ -913,7 +978,7 @@ Audit fixes, dependency updates, and security patches land only for the supporte
 
 ## Extension and configuration notes
 
-- **Required `@arnilo/prism` peer.** Every first-party code package declares a non-optional **caret** `@arnilo/prism@^0.3.1` peer (plan 039 republished set; unchanged packages keep the prior `^0.3.0` window peer — both satisfy the root) (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). **Peer-version policy (plan 030, Decision B — independent packages):** internal ranges stay inside the 0.x `^0.3.0` window, so a package may patch independently while consumers remain on a compatible 0.3.x line. A package outside that window (for example `0.4.0`) is refused by the release gate until the next coordinated peer bump. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
+- **Required `@arnilo/prism` peer.** Every first-party code package declares a non-optional **caret** `@arnilo/prism@^0.3.3` peer (plan 041-044 republished set; the plan 039 set keeps `^0.3.1` and unchanged packages keep the prior `^0.3.0` window peer — all satisfy the root) (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). **Peer-version policy (plan 030, Decision B — independent packages):** internal ranges stay inside the 0.x `^0.3.0` window, so a package may patch independently while consumers remain on a compatible 0.3.x line. A package outside that window (for example `0.4.0`) is refused by the release gate until the next coordinated peer bump. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
 - **Public access.** All 56 manifests (root + 55 workspace packages: 49 code packages + 6 pure-manifest family/profile packages — the 10 `prism-*` family/profile set is the 6 pure-manifest profiles plus the 4 code packages `prism-caveman`, `prism-impeccable`, `prism-openapi-tools`, `prism-ponytail`) declare `"publishConfig": { "access": "public" }`; the publisher also passes `--access public` explicitly because scoped packages otherwise default to restricted on first publish.
 - **Shipped vs repository docs.** The npm tarball ships `docs/` pages linked from `docs/index.md` (public API, security, migration, providers, install). It excludes `docs/_evidence/` (per-phase evidence freezes, including `release-0.2.7-evidence.md`), `docs/release-*-evidence.md`, and `docs/api-page-template.md`. Those files remain in git for audit. `dist/__tests__` and `*.map` stay excluded.
 - **Map retention knob.** Source maps are emitted locally but stripped from tarballs by `!dist/**/*.map`. Removing that `files` negation ships maps in releases (larger tarballs, better consumer stack traces).
@@ -924,13 +989,13 @@ Audit fixes, dependency updates, and security patches land only for the supporte
 
 - **No secrets or fixtures in tarballs.** Tests, fixtures, `src/`, `plans/`, `.agents/`, `roadmap.md`, and `tsconfig` files are excluded. The `docs avoid real-looking secret examples` docs check and the packaging guard's deny list prevent secret-bearing fixtures from shipping.
 - **Live tests stay opt-in.** The default `npm test` is network-free by construction and never sets these vars. Provider/compaction live gates stay credential-gated and are not set by default or during `sdk:ready`. The PostgreSQL adapter live matrix is the exception that runs in CI via the dedicated `postgres-integration` job (still skipped in the default suite).
-  - `PRISM_LIVE_PROVIDER_TESTS=1` — gates the eight provider packages' `src/__tests__/live.test.ts` (`@arnilo/prism-provider-anthropic`, `provider-google`, `provider-openai`, `provider-opencode-go`, `provider-openrouter`, `provider-zai`, `provider-kimi`, `provider-neuralwatt`). Each provider live test also requires its own API key env var and skips safely when it is missing:
-    - `OPENAI_API_KEY` for `@arnilo/prism-provider-openai`
-    - `OPENROUTER_API_KEY` for `@arnilo/prism-provider-openrouter`
-    - `KIMI_API_KEY` for `@arnilo/prism-provider-kimi`
-    - `ZAI_API_KEY` for `@arnilo/prism-provider-zai`
-    - `NEURALWATT_API_KEY` for `@arnilo/prism-provider-neuralwatt`
-    - `OPENCODE_API_KEY` for `@arnilo/prism-provider-opencode-go`
+  - `PRISM_LIVE_PROVIDER_TESTS=1` — gates the eight provider packages' `src/__tests__/live.test.ts` (`@arnilo/prism-providers/anthropic`, `provider-google`, `provider-openai`, `provider-opencode-go`, `provider-openrouter`, `provider-zai`, `provider-kimi`, `provider-neuralwatt`). Each provider live test also requires its own API key env var and skips safely when it is missing:
+    - `OPENAI_API_KEY` for `@arnilo/prism-providers/openai`
+    - `OPENROUTER_API_KEY` for `@arnilo/prism-providers/openrouter`
+    - `KIMI_API_KEY` for `@arnilo/prism-providers/kimi`
+    - `ZAI_API_KEY` for `@arnilo/prism-providers/zai`
+    - `NEURALWATT_API_KEY` for `@arnilo/prism-providers/neuralwatt`
+    - `OPENCODE_API_KEY` for `@arnilo/prism-providers/opencode-go`
   - `PRISM_LIVE_WEB=1` — gates `@arnilo/prism-web-tools` restricted live tests; provider calls additionally require `PRISM_BRAVE_SEARCH_TOKEN`, `PRISM_EXA_API_KEY`, or `PRISM_FIRECRAWL_API_KEY`. Run `npm run test:live -w @arnilo/prism-web-tools`; default tests use injected fake fetch only.
   - `PRISM_TEST_PLAYWRIGHT=1` or `PRISM_LIVE_PLAYWRIGHT=1` — gates `@arnilo/prism-browser` protected Playwright adversarial matrix (`npm run test:live -w @arnilo/prism-browser`). Host must supply a pinned Chromium binary via `playwright-core`. Default tests use fake Playwright APIs only; enabled but missing browser fails closed.
   - `PRISM_TEST_DOCKER_SANDBOX=1` — gates `@arnilo/prism-coding-security` protected Docker matrix. Requires host-preloaded digest-pinned `PRISM_TEST_DOCKER_IMAGE` and absolute `PRISM_TEST_DOCKER_BIN` (optional `PRISM_TEST_DOCKER_USER`). Prism never pulls/builds the image during default tests. Missing prerequisites fail closed when the gate is enabled; disabled gate skips safely.
@@ -963,7 +1028,7 @@ A deleted tracked feature-request markdown was intentionally not restored by rel
 
 ### 0.0.11 dependency audit decision (2026-07-22)
 
-`npm audit --audit-level=high` reports 0 vulnerabilities and `npm ls --all --depth=0` resolves the exact 34-package `0.0.11` graph (including `@arnilo/prism-provider-anthropic`, `@arnilo/prism-provider-google`, and `@arnilo/prism-browser`). Locked-install SPDX and `scripts/verify-sbom.mjs` pass. Browser keeps `playwright-core@1.61.0` as an optional peer and ships no browser binary/image; no Office package/binary enters the graph. Host mode never claims disposable containment.
+`npm audit --audit-level=high` reports 0 vulnerabilities and `npm ls --all --depth=0` resolves the exact 34-package `0.0.11` graph (including `@arnilo/prism-providers/anthropic`, `@arnilo/prism-providers/google`, and `@arnilo/prism-browser`). Locked-install SPDX and `scripts/verify-sbom.mjs` pass. Browser keeps `playwright-core@1.61.0` as an optional peer and ships no browser binary/image; no Office package/binary enters the graph. Host mode never claims disposable containment.
 
 
 ### 0.0.11 release-candidate verification — 2026-07-22
@@ -1089,11 +1154,12 @@ Every release gate maps to an exact enforcement test or command, so the checklis
 | Root SDK export surface freeze | `public-export-contract.test.ts` `root export surface is frozen` snapshots every value and type export of `src/index.ts` (107 value + 69 type) so any add/remove is a deliberate test update; `every frozen value export resolves at runtime` rebuilds `dist/index.js` and asserts each value export is present (catches build drift), and `every frozen type export appears in the built type declarations` asserts each type export is in `dist/index.d.ts`. |
 | Examples compile and are listed; runnable demos execute | `npm run typecheck` runs `tsc -p examples --noEmit`; `docs.test.ts` checks every `examples/*.ts` file is listed in `examples/README.md`, then runs demos offline and scans output for secrets. |
 | Examples run to completion with no secret leakage | `docs.test.ts` `examples_demos_run_to_completion_and_emit_no_secret` runs each demo (Node strips TypeScript types natively) with exit-0 and real-secret scans; `external_app_example_*` pins the DB-backed adapter reference exercising the `RunLedger`, branch-handle checkout, fork, and prior-run resume. |
-| Tarball excludes built tests, source maps, and source | `packaging.test.ts` rejects `dist/__tests__/`, `*.map`, `src/`, `plans/`, and internal files; confirms every package ships README/changelog (and code packages ship LICENSE), core ships docs + CLI, and every export target exists. `prism-all` reaches 47 of the 59 workspace packages (21 direct + 26 transitive); the deliberate Caveman/Ponytail/Impeccable/computer-use-linux/antigravity-agent/Graft/Obscura opt-outs and the other non-closure packages (document-reader, OpenAPI tools, NATS, wiki) are not in its install set. |
-| NeuralWatt package/docs/examples release gate | `packaging.test.ts` pins `@arnilo/prism-provider-neuralwatt` package exports/type declarations and `@arnilo/prism-providers`/`@arnilo/prism-all` membership; `docs.test.ts` asserts `docs/index.md` links `providers/neuralwatt.md` and `provider-caching.md`, and that `examples/cache-aware-prompt-assembly.ts` plus `examples/neuralwatt-agent-run.ts` exist and are listed. |
+| Tarball excludes built tests, source maps, and source | `packaging.test.ts` rejects `dist/__tests__/`, `*.map`, `src/`, `plans/`, and internal files; confirms every package ships README/changelog (and code packages ship LICENSE), core ships docs + CLI, and every export target exists. Profile manifests (`prism-base`/`prism-code`/`prism-sdk`/`prism-all`) are retired; hosts install explicit family packages. `@arnilo/prism-office` ships `/documents`, `/sheets`, `/diagrams`. |
+| NeuralWatt package/docs/examples release gate | `packaging.test.ts` pins `@arnilo/prism-providers/neuralwatt` package exports/type declarations and `@arnilo/prism-providers`/`@arnilo/prism-all` membership; `docs.test.ts` asserts `docs/index.md` links `providers/neuralwatt.md` and `provider-caching.md`, and that `examples/cache-aware-prompt-assembly.ts` plus `examples/neuralwatt-agent-run.ts` exist and are listed. |
 | Enterprise PostgreSQL package/docs/example gate | Packaging/install/public-contract tests include `@arnilo/prism-enterprise-postgres`; `docs.test.ts` pins its API page, four-store migration/ownership/unknown-outcome/async-router guidance, and `examples/enterprise-postgres-state.ts`; `npm run test:postgres` exercises migration, restart, contention, and cleanup with an explicit database URL. |
 | Version graph and resumable publication | `release.test.ts` covers exact package/lock/range validation, topological order, registry collisions, dry-run, interrupted reports/resume, clean tagged git state, provenance/public/tag arguments, and token-safe errors. `release:check` and `release:publish` derive the workspace graph without a manual package list. |
 | Pre-publish compatibility gates | `release:gate` (in `sdk:ready`) fails on removed/changed `.d.ts` exports vs `scripts/compat-baseline/` (unless `--allow-break` + migration note), version-range/lockfile drift, and tarball deny-list violations (`plans/`, `code-reviews/`, `docs/review-coverage-*`, `*.map`, `__tests__/`); unit-tested in `scripts/release-gate.test.mjs`. |
+| Legacy registry markers (plan 054 Task 7) | `scripts/phase54-legacy-registry.mjs --dry-run` verifies every retired name's final published version exists and `latest` is unchanged, and that each deprecation URL anchor exists in `docs/migrate-to-0.4.md`, without mutating the registry; `--apply --confirm` pre-flights all 54 entries and fails closed (zero mutations) on any mismatch, then idempotently adds the `legacy` dist-tag and `<0.4.0` deprecation warning (already-correct entries skipped; per-entry status in `release-artifacts/legacy-registry-plan.json` for safe resume). `packaging.test.ts` asserts the generated plan covers all 54 retired names with uniform messages and valid guide anchors; the offline fixture suite `scripts/phase54-legacy-registry.test.mjs` proves the dry-run/apply/resume behavior without network or tokens. |
 | Formatting, linting, and coverage thresholds | `npm run lint` and `npm run format:check` run Biome (single root `biome.json`, workspaces inherit) and fail on any lint error or unformatted file; `npm run test:coverage` uses Node's built-in `--experimental-test-coverage` with enforced minimums (lines 60 / functions 70 / branches 75) and no third-party service. All three run inside `sdk:ready`. |
 | Supply-chain and live-canary policy | `supply-chain-security.test.ts` verifies SPDX allow/deny behavior, bounded source/artifact secret detection, credential-free canary reports, timeout/redacted failures, immutable action revisions, no `pull_request_target`, protected live environment, attestation paths, and publish dependency on `supply-chain`; CI adds CodeQL and PR dependency review. |
 | Network-free + offline test budget | `network-free-guard.test.ts` keeps the default suite network-free; budget pinned `< 60s` (measured baseline above). Install-smoke is offline (`--offline --no-audit --no-fund`, zero registry fetches). |

package/docs/runs-and-usage.md

@@ -125,6 +125,19 @@ The adapter receives these record shapes:
 | `usage` | `Usage` shape: input/output/total/cache tokens, cost, currency. |
 | `recordedAt` | ISO timestamp. |
 
+## Prompt provenance
+
+Hosts that resolve prompts from the [versioned prompt registry](prompt-registry.md) can stamp each run with the resolved version's identity. `RunOptions.promptVersion` takes `{ name, version, hash }` — an opaque [ref](#related-apis): `name` is the prompt name (1–256 UTF-8 bytes), `version` the immutable version number (integer in `[1, 2147483647]`), and `hash` the prompt store's SHA-256 body hash (`sha256:` plus 64 lowercase hex). The ref is copied verbatim onto the run's start and finish ledger records; when it is omitted nothing is added and behavior is byte-identical. Malformed refs fail closed with a `TypeError` before the run starts.
+
+```ts
+const resolved = await promptStore.resolve({ tenantId, name: "support-agent" });
+await session.run(input, {
+  promptVersion: { name: resolved.name, version: resolved.version, hash: resolved.hash },
+});
+```
+
+Provenance is identity, not content: never put prompt bodies in the ref or in `metadata` — the body is recoverable from the store via `hash`, and ledger records/exports run through the existing secret redaction and field-policy boundaries. OTel spans deliberately carry no prompt attribute; the durable ledger record is the provenance of record.
+
 ## Run/trace feedback
 
 `RunFeedbackStore.append()` accepts an immutable record only when `resolveRun` finds the same `runId` under the exact `{ tenantId, accountId?, userId? }` scope. A tenant plus account or user is mandatory. Records contain `sessionId`, optional `traceId`, finite `rating` in `[-1, 1]`, comment, tags, scorer IDs, evaluation IDs, timestamp, creator, and metadata. Correction appends a new ID; records are never updated in place. `delete()` is the explicit privacy/retention operation.
@@ -272,7 +285,7 @@ console.log(cacheUsageReport(aggregate?.usage));
 - Billing queries must filter `scope = "provider_turn"`; presentation queries normally read the single `run_total`. `UsageQuery.scope`, `turn`, and `attempt` are explicit filters.
 - Adapters that need upsert semantics can use `RunRecord.id` (== `runId`) as the stable key.
 - Use `cacheUsageReport(record.usage, model)` for cache diagnostics from normalized usage. It works when a provider reports `cacheReadTokens` without `cacheWriteTokens`; missing write tokens are reported as `0`, and unavailable hit rate/savings stay `undefined`.
-- **Provider-specific telemetry is package-owned.** Core `Usage` carries token counts and `cost`/`currency`; it has no energy or detailed cost-breakdown fields. Providers that surface extra telemetry (e.g. `@arnilo/prism-provider-neuralwatt` exposes `neuralWattEventsWithTelemetry()`, `parseNeuralWattComment()`, and `mapNeuralWattTelemetry()` for `: energy`/`: cost` SSE comments and non-streaming top-level fields) keep that data in package-specific helpers/types. Telemetry never enters `RunLedger` usage rows unless the host explicitly copies it in; it carries usage/cost numbers only — never prompts, API keys, or headers. Account-level quota is likewise package-owned: `@arnilo/prism-provider-neuralwatt` exports an explicit `getNeuralWattQuota()` helper that the host calls on demand (never during generation); NeuralWatt rate-limits that endpoint to 1 request per second per customer, so the caller owns throttling.
+- **Provider-specific telemetry is package-owned.** Core `Usage` carries token counts and `cost`/`currency`; it has no energy or detailed cost-breakdown fields. Providers that surface extra telemetry (e.g. `@arnilo/prism-providers/neuralwatt` exposes `neuralWattEventsWithTelemetry()`, `parseNeuralWattComment()`, and `mapNeuralWattTelemetry()` for `: energy`/`: cost` SSE comments and non-streaming top-level fields) keep that data in package-specific helpers/types. Telemetry never enters `RunLedger` usage rows unless the host explicitly copies it in; it carries usage/cost numbers only — never prompts, API keys, or headers. Account-level quota is likewise package-owned: `@arnilo/prism-providers/neuralwatt` exports an explicit `getNeuralWattQuota()` helper that the host calls on demand (never during generation); NeuralWatt rate-limits that endpoint to 1 request per second per customer, so the caller owns throttling.
 - **Live timing metadata.** `provider_turn_*` events and `ToolExecutionMetadata` on terminal `tool_execution_*` events expose latency, retry `attempt`, and tool `durationMs` for subscribers and ledger replay — see [Observability](observability.md).
 
 ## Security and performance notes

package/docs/server.md

@@ -128,6 +128,95 @@ Default/hard ceilings:
 | drain admit cutoff | 30 s | 5 min |
 | replay page / cursor | 100 / 4 KiB | 500 / 16 KiB |
 
+## Outbound webhooks
+
+### What it does
+
+`createWebhookNotifier()` posts selected terminal agent/workflow events to host-registered HTTPS endpoints. Every JSON envelope is redacted before HMAC-SHA-256 signing; `X-Prism-Signature` is `sha256=<hex>` and `X-Prism-Timestamp` carries the signed envelope timestamp.
+
+### When to use it
+
+Use it for host-owned PagerDuty, Slack, or application hooks after a run completes, fails, or suspends. Omit targets when no outbound notification is wanted: no target means no queued delivery or network activity.
+
+### Inputs / request
+
+| Field | Meaning |
+| --- | --- |
+| `targets` | Host-configured `{ url, events }` entries. URLs must be public HTTPS, without credentials/fragments; private and metadata literals fail during registration. |
+| `allowLoopbackHttp` | Explicit opt-in permitting `http:` for loopback hostnames (development receivers only); never combined with private or metadata targets. Default false. |
+| `signer.key` | Host-held `Uint8Array` HMAC key, at least 32 bytes. |
+| `redactor` | Required `SecretRedactor`; its result is placed in `redactedPayload` before signing. |
+| `limits.maxQueuedEvents` | Global outbound queue cap; default 128, hard cap 4,096. Overflow drops newest and increments `diagnostics().dropped`. |
+| `limits.timeoutMs` / `maxEventBytes` | Per-attempt timeout (5 s default, 30 s hard) and JSON envelope byte cap (64 KiB default, 1 MiB hard). |
+| `limits.retries` / `retryBaseDelayMs` / `retryMaxDelayMs` / `retryJitter` | Retries after the first attempt (3 default, 10 hard); exponential 100 ms→5 s delays (30 s hard), with ±25% jitter by default. Set jitter to `0` only for deterministic tests. |
+| `limits.maxFailureRecords` | Redacted terminal failure-record ring buffer; 32 default, 256 hard. |
+
+`notify()` accepts `run.completed`, `run.failed`, `run.suspended`, `workflow.completed`, `workflow.failed`, or `workflow.suspended`. `onAgentEvent()` and `onWorkflowEvent()` translate Prism lifecycle events into those names.
+
+### Outputs / response / events
+
+`notify()` returns immediately after bounded enqueue. Pass `{ signal }` as its second argument to cancel queued or retrying delivery for that run. `diagnostics()` returns `{ queued, delivered, failed, dropped, retries, cancelled, failures, lastError? }`: `failed` is the `prism.webhook.failed` terminal-failure counter, `failures` is bounded and redacted, and `lastError` is its latest redacted error.
+
+A `2xx` delivery succeeds. `4xx` is terminal except `429`; `429`, `5xx`, and transport failures retry within the configured cap. `Retry-After` is honored within `retryMaxDelayMs`. Delivery is at-least-once: receiver timeouts after processing can yield duplicates.
+
+```json
+{
+  "id": "01d2...",
+  "event": "run.failed",
+  "runId": "run-42",
+  "status": "failed",
+  "redactedPayload": { "error": "[REDACTED]" },
+  "timestamp": "2026-01-01T00:00:00.000Z"
+}
+```
+
+### Request/response example
+
+Receivers verify the raw request body, not a parsed/re-serialized object:
+
+```ts
+const expected = createHmac("sha256", hostHmacKey).update(rawBody).digest("hex");
+const valid = request.headers.get("x-prism-signature") === `sha256=${expected}`;
+```
+
+### Implementation example
+
+```ts
+import { createSecretRedactor, type AgentSession } from "@arnilo/prism";
+import { createWebhookNotifier } from "@arnilo/prism-server";
+
+const notifier = createWebhookNotifier({
+  targets: [{ url: "https://ops.example.test/prism", events: ["run.failed", "workflow.suspended"] }],
+  signer: { key: Buffer.from(process.env.PRISM_WEBHOOK_HMAC!, "hex") },
+  redactor: createSecretRedactor([process.env.PRISM_WEBHOOK_HMAC]),
+});
+
+export function wireWebhookAgentSession(session: AgentSession): AgentSession {
+  void (async () => {
+    for await (const event of session.subscribe()) notifier.onAgentEvent(event);
+  })();
+  return session;
+}
+
+export const webhookWorkflowRunOptions = { onEvent: notifier.onWorkflowEvent };
+```
+
+The agent `sessionFactory` is the server-handler adapter. Workflow `onEvent` receives the same events emitted through its event bus, including `workflow_finished` and `workflow_suspended`.
+
+### Extension and configuration notes
+
+Targets are static host configuration, never request JSON, tool output, or extension discovery. Event filters are exact. The notifier is a server-package export; it neither starts a listener nor owns a durable queue, auth provider, or webhook receiver.
+
+### Security and performance notes
+
+Delivery uses core `pinnedFetch` only: every attempt DNS-pins a public address and rejects all redirects, including redirects toward private targets. The HMAC key, signature, and delivery errors are never logged by the notifier; bounded failure records redact error text before retention. HTTPS is mandatory; plaintext HTTP is allowed only with explicit `allowLoopbackHttp: true` and a loopback hostname, and still pins/validates DNS. Queue overflow deliberately drops newest deliveries so earlier accepted lifecycle events retain order; use `diagnostics()` to observe loss. The in-memory queue does not survive restart; a durable outbox is required when cross-restart delivery matters. The outbound-webhook threat leg lives in `npm run security:threat-suites` (`scripts/phase46-webhooks-security.test.mjs` plus the package and pinned-fetch fixtures).
+
+### Related APIs
+
+- [Multimodal content](multimodal-content.md): shared DNS-pinned outbound fetch primitive.
+- [Workflows](workflows.md): workflow event-bus and `onEvent` lifecycle seam.
+- [Host security guide](host-security.md): remote-boundary controls.
+
 ## Deployment seams (optional)
 
 Compose beside `createPrismHandler` — Prism starts no listener, container orchestrator, or queue worker.
@@ -158,7 +247,7 @@ Network-free demo: [`examples/server-deployment-seams.ts`](../examples/server-de
 - Health endpoints reveal process/liveness only by default; detail flags require host authorize and must omit secrets/tenant dumps.
 - Drain and event replay require the same ownership/authorize boundary as other routes; replay never invokes providers or tools. Durable event routes exist only on object `PrismAgentExposure` entries with both `events` and `resolveRun`; every reconnect authorizes again, resolves public run ID to exact internal session/run IDs, and opens the shared source without `sessionFactory`.
 - SSE uses bounded upstream subscriber queues. Consumer cancellation aborts owned work by default and releases concurrency; set `disconnectAborts: false` only when the host deliberately owns background completion.
-- Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Server package does not fetch URLs.
+- Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Apart from explicitly configured `WebhookNotifier` targets, server package features do not fetch URLs.
 - Schedule routes never accept ownership from JSON. Services carry mandatory ownership and explicit workflow/calculator registries; route authorization cannot broaden either. Replay applies workflow ownership/hash/approval checks.
 - Agent status/resume routes exist only for keys in `agentRuns`. Supply one core `createAgentRunLifecycle({ checkpoints, resolveAgent })` capability per selected agent; its resolver returns current `{ agent, definitionRevision }`. It reuses core checkpoint parsing/CAS/fingerprint checks, returns only public state/version, and needs a durable `SessionStore` as well as checkpoints for restart-safe resume. Empty/default configuration adds no agent lifecycle route, polling, or server cache.