@arnilo/prism 0.2.9 → 0.3.1

package/docs/release-and-install.md

@@ -2,11 +2,11 @@
 
 ## What it does
 
-Prism is published as **55 publishable manifests**: the root `@arnilo/prism` core package plus **54 workspace packages** — 17 provider adapters, 10 `prism-*` family/profile packages, and 27 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 0.2.9 plan 029 cut adds DeepSeek, xAI, ClinePass, and `@arnilo/prism-impeccable` on the 0.2.8 51-package graph. This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer dependency, 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.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).
 
-Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package has a required `@arnilo/prism@0.2.9` peer; profiles are pure manifests. 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 — 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.
 
-Current **55** publishable manifests (root + 54 workspace packages):
+Current **58** publishable manifests (root + 57 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`
@@ -15,7 +15,7 @@ Current **55** publishable manifests (root + 54 workspace packages):
 `@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-work-tools`, `@arnilo/prism-workflows`, `@arnilo/prism-document-reader`
+`@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`
 
 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`).
 
@@ -41,21 +41,20 @@ Consumers install the core package for the runtime and add first-party packages
 | 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` |
 | 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` |
 | Dry-run pack core + every package | `npm run pack:dry-run` |
 | Local mirror of the release verify gate | `npm run release:dry-run` |
-| Validate clean tag/version/ranges and reject registry collisions | `npm run release:check -- --version 0.1.0` |
-| Preview deterministic publish order | `npm run release:publish -- --version 0.1.0 --dry-run --allow-dirty --allow-untagged` |
-| Resume interrupted tagged publication | `npm run release:publish -- --version 0.1.0 --resume --report release-artifacts/publish-report.json` |
+| Validate independent versions/ranges and reject registry collisions | `npm run release:check -- --allow-dirty --allow-untagged` |
+| Preview deterministic changed-package publication | `npm run release:publish -- --dry-run --allow-dirty --allow-untagged` |
+| Resume interrupted package-tag publication | `npm run release:publish -- --resume --report release-artifacts/publish-report.json` |
 | Protected PostgreSQL enterprise suite | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres` |
 | Full SDK readiness gate (typecheck + offline tests + pack) | `npm run sdk:ready` |
 | Non-blocking unused-code sweep (report to `scripts/unused-sweep-report.txt`, always exits 0) | `npm run sweep:unused` |
 
-> **Build notes (0.1.1+).** `npm run build` no longer runs `npm run clean` first: concurrent builds/tests (`npm test`, `npm run typecheck`) are now race-free because the only destructive step was the `rm -rf` clean, and concurrent `tsc` is write-only and idempotent on identical input (two processes emitting the same files end byte-identical regardless of interleaving).
->
-> `ponytail:` concurrent `tsc` is idempotent on identical input, so no single-flight lock is needed; orphaned `dist/` files from deleted sources fail loudly on the next `node --test` (broken imports) and are filtered from tarballs by the `files` allowlists; run `npm run clean` after source deletions or branch switches; `tsc --build` (0.2.0 Module F) auto-cleans orphans.
+> **Build notes (0.2.3+).** `npm run build` no longer runs `npm run clean` first. Emit-producing and dist-consuming leaves are serialized by `scripts/with-build-lock.mjs`, so concurrent builds/tests cannot expose partial `dist/`; run `npm run clean` after source deletions or branch switches for orphan cleanup. Direct `tsc` outside the wrapper remains an external-writer caveat.
 
 Run `npm run clean` explicitly after deleting source files or switching branches: a deleted `src/__tests__/*.test.ts` leaves an orphan `dist/__tests__/*.test.js` (tsc never auto-cleans). If the orphan's import chain still resolves it keeps running as a stale test — silent staleness, which is exactly what the explicit clean prevents — and if the chain is broken the next `node --test dist/__tests__/*.test.js` fails loudly (`ERR_MODULE_NOT_FOUND`), never silently swallowed. A fresh `npm run clean && npm run build` and the new `npm run build` from a clean state produce byte-identical `dist/` (tsc overwrites per-file outputs).
 
@@ -65,6 +64,7 @@ Run `npm run clean` explicitly after deleting source files or switching branches
 | `@arnilo/prism/providers/openai-compatible` | `dist/providers/openai-compatible.{js,d.ts}` |
 | `@arnilo/prism/providers/transport` | `dist/providers/transport.{js,d.ts}` |
 | `@arnilo/prism/providers/openai` | `dist/providers/openai-primitives.{js,d.ts}` |
+| `@arnilo/prism/providers/schema` | `dist/providers/schema.{js,d.ts}` |
 | `@arnilo/prism/providers/media` | `dist/providers/media.{js,d.ts}` |
 | `@arnilo/prism/testing/provider-conformance` | `dist/testing/provider-conformance.{js,d.ts}` |
 | `@arnilo/prism/testing/agent-event-source-conformance` | `dist/testing/agent-event-source-conformance.{js,d.ts}` |
@@ -94,7 +94,7 @@ A packed tarball contains only public compiled output and release files:
 - 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`.
 - `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.2.9.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.2.9.tgz` / `arnilo-prism-compaction-<name>-0.2.9.tgz` / `arnilo-prism-coding-agent-0.2.9.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.2.9.tgz`. 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.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).
 
 Excluded from every tarball by `files` negation:
 
@@ -113,9 +113,9 @@ Excluded from every tarball by `files` negation:
   "name": "host-app",
   "type": "module",
   "dependencies": {
-    "@arnilo/prism": "0.1.0",
-    "@arnilo/prism-enterprise-postgres": "0.1.0",
-    "@arnilo/prism-provider-openai": "0.1.0"
+    "@arnilo/prism": "^0.3.0",
+    "@arnilo/prism-enterprise-postgres": "^0.3.0",
+    "@arnilo/prism-provider-openai": "^0.3.0"
   }
 }
 ```
@@ -125,7 +125,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.0.17" from @arnilo/prism-provider-openai@0.0.17
+npm error peer @arnilo/prism@"^0.3.0" from @arnilo/prism-provider-openai@0.3.0
 ```
 
 ## Implementation example
@@ -158,11 +158,11 @@ For SDK readiness, run the same one-command gate directly. It composes existing
 npm run sdk:ready
 ```
 
-Release publication derives all **49** manifests from the workspace once, validates exact `0.1.0` manifest/lockfile/internal ranges, then uses deterministic dependency order. `release:check` requires a clean commit tagged `v0.1.0` and rejects any existing registry version. `release:publish --resume` skips only registry versions whose internal dependency fingerprint matches the local manifest; conflicting versions fail closed. Each attempted package is written immediately to the JSON report, so a failed job can rerun safely. `--dry-run` performs registry availability checks and invokes `npm publish --dry-run` with explicit public access, provenance, and `latest` tag, but does not publish.
+Release publication derives the workspace graph from manifests. The final `v0.3.0` cut validates the 56-package lockstep graph; later `release:check` and `release:publish` default to independent changed-package validation/publication under package tags. Resume skips only registry versions whose internal dependency fingerprint matches the local manifest; conflicting versions fail closed. Each attempted package is written immediately to the JSON report, so a failed job can rerun safely. `--dry-run` performs registry availability checks and invokes `npm publish --dry-run` with explicit public access, provenance, and `latest` tag, but does not publish.
 
 ```bash
-npm run release:check -- --version 0.1.0
-npm run release:publish -- --version 0.1.0 --dry-run --allow-dirty --allow-untagged
+npm run release:check -- --allow-dirty --allow-untagged
+npm run release:publish -- --dry-run --allow-dirty --allow-untagged
 ```
 
 `--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.
@@ -175,7 +175,7 @@ PRISM_LIVE_PROVIDER_TESTS=1 npm run test --workspaces --if-present
 
 ### GitHub Actions pipeline (0.0.27+)
 
-`.github/workflows/release.yml` is the single pipeline: **push to `main`** runs CI (`verify` = `npm run sdk:ready`, `node20-compat`, `postgres-integration`, `supply-chain`), **push of a `v*` tag** additionally runs `codeql-release` and the `publish` job (deterministic `release:publish` in dependency order with provenance attestation). `security.yml` adds CodeQL/dependency-review/SBOM on push and PR; `live-canaries.yml` and `sandbox-browser.yml` are scheduled. All actions are SHA-pinned (2026-08-06 fix: CodeQL pins were invalid 404 refs and `workflow_dispatch` was missing — re-verified every pin against its upstream repo). Prerequisites outside the repo: Actions enabled in repository settings, and the `NPM_TOKEN` secret (with `id-token: write` for provenance). To re-cut a tag after a fix commit, delete and recreate it (`git push origin :v0.0.28 && git push origin v0.0.28`) so the tag creation event fires.
+`.github/workflows/release.yml` is the single pipeline: **push to `main`** runs CI (`verify` = `npm run sdk:ready`, `node20-compat`, `postgres-integration`, `supply-chain`), **`v0.3.0` or `@arnilo/*@*` package tags** additionally run `codeql-release` and the `publish` job (deterministic `release:publish` in dependency order with provenance attestation). `security.yml` adds CodeQL/dependency-review/SBOM on push and PR; `live-canaries.yml` and `sandbox-browser.yml` are scheduled. All actions are SHA-pinned (2026-08-06 fix: CodeQL pins were invalid 404 refs and `workflow_dispatch` was missing — re-verified every pin against its upstream repo). Prerequisites outside the repo: Actions enabled in repository settings, and the `NPM_TOKEN` secret (with `id-token: write` for provenance). To re-cut a tag after a fix commit, delete and recreate it (`git push origin :v0.0.28 && git push origin v0.0.28`) so the tag creation event fires.
 
 ### 0.1.0 publish handoff (plan 012 Task 7)
 
@@ -348,6 +348,60 @@ npm run release:publish -- --version 0.2.6 --dry-run --allow-dirty --allow-untag
 
 Protected evidence (never a passing skip): the durable recovery/workspace conformance legs (real Postgres two-replica split-brain fence, cross-replica cancellation, terminal-before-recovery), the protected PTY leg (real PTY host adapter), the protected real coding journey (`scripts/phase26-coding-journey-report.json` — pass/blocked/protected, never a passing skip; runs in `.github/workflows/coding-journey.yml` with real provider/Docker/Playwright/GitHub/Postgres/PTY services), and the live canaries (provider OIDC/OPA, MCP, A2A, Brave — always `protected` rows in the manifest, never `pass`). The release skip manifest names every skip class with its required env; missing protected evidence records 0.2.6 as **blocked**, never a passing skip.
 
+### 0.3.0 lockstep cut and independent publication (plan 030 Task 9)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.3.0** is the last lockstep cut: all **56** publishable manifests are `0.3.0`, and every internal `@arnilo/*` dependency, optional dependency, and peer dependency uses `^0.3.0`. This cut adds the optional host-owned `@arnilo/prism-computer-use-linux` wrapper, `read.findText`, loud edit fuzzy matches/miss context, and ACP editor-buffer wiring; the desktop package stays outside umbrella profiles. Peer policy is now **Decision B**: packages may move independently inside the 0.x caret window (`>=0.3.0 <0.4.0`).
+
+After the signed `v0.3.0` cut, publication is package-tag driven: `@arnilo/<package>@<version>` publishes only changed packages at that version. The lockstep core artifact is `arnilo-prism-0.3.0.tgz`; later package artifacts carry their own name and version. A generic `v*` tag is not a publication trigger after this cut. The one emergency lockstep path remains explicit: `--lockstep --version 0.3.0`.
+
+```bash
+# one manifest bump + one lockfile regeneration for the final cut
+node scripts/release.mjs bump --from 0.2.9 --to 0.3.0 --ranges caret
+node scripts/package-truth.mjs
+node scripts/release.mjs check --lockstep --version 0.3.0 --allow-dirty --allow-untagged
+# later checks default to independent mode
+npm run release:check -- --allow-dirty --allow-untagged
+```
+
+For a later coding-agent-only patch, bump its manifest with `bump --package @arnilo/prism-coding-agent --type patch`, regenerate the lockfile, commit, and push `@arnilo/prism-coding-agent@0.3.1`. The default independent check validates the mixed graph; the package tag publishes only that package in dependency order. Resume skips only a matching already-published manifest and refuses a same-version registry collision with different internal release fields.
+
+**Rollback notes.** Before publication, restore the 0.2.9 manifests/tag. After publication, roll forward with an additive 0.3.x package patch; npm unpublish is not a rollback strategy.
+
+### 0.3.1 independent RAG engine patch (plan 034 Task 12)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.3.1** is the first Decision B independent patch: only `@arnilo/prism-memory`, `@arnilo/prism-rag`, and `@arnilo/prism-observability-opentelemetry` move `0.3.0 → 0.3.1`. Internal `^0.3.0` ranges stay. Root current line remains **0.3.0**.
+
+```bash
+node scripts/release.mjs bump --package @arnilo/prism-memory --type patch
+node scripts/release.mjs bump --package @arnilo/prism-rag --type patch
+node scripts/release.mjs bump --package @arnilo/prism-observability-opentelemetry --type patch
+node scripts/release.mjs gate --update-baseline --skip-tarball   # review Embedder.id; scanner is additive-only
+node scripts/release.mjs check --allow-dirty --allow-untagged
+# publish tags (operator handoff; not this task):
+#   git tag @arnilo/prism-memory@0.3.1 && git tag @arnilo/prism-rag@0.3.1
+#   git tag @arnilo/prism-observability-opentelemetry@0.3.1 && git push --tags
+```
+
+**Compat.** Baselines regenerated with `--update-baseline`. Expected deltas are additive exports (`createPostgresVectorStore`, `createTeiReranker`, `createRagTelemetry`, multi-scope `scopes`, `HARD_RETRIEVE_SCOPE_CAP`, fusion/hash/generation helpers). `Embedder.id` is a TypeScript implementer break documented in `docs/migration.md` `0.3.0 → 0.3.1`; the name-level scanner does not see interface members, so `--allow-break` is not required. `RagProvenance` gained `tenantId`/`resourceId`/`corpusId` (additive interface members, invisible to scanner). **Store:** additive Postgres DDL; 0.3.0 rows remain readable. **Rollback:** restore the 0.3.0 package versions. Publication remains the operator handoff — this task does not publish.
+
+### 0.3.1 changed-package cut (plan 039 Task 8)
+
+**Decision: GO when the operator prerequisites below are recorded.** The plan 039 cut is the first Decision B **root** patch: the baseline is the plan 035 completion parent `c600eaa`; 30 packages publish in dependency order — root `@arnilo/prism` plus 27 changed workspace packages move to **0.3.1** (`@arnilo/prism-rag` moves 0.3.1 → 0.3.2), and `@arnilo/prism-obscura` publishes new at its reviewed initial **0.3.0**. Every unchanged package stays byte-identical (peers keep the `^0.3.0` window; republished packages carry `^0.3.1` root peers — both satisfy the root). Additive-only compat (version literal + plan 036/037 additive exports + the obscura CDP/browser surface; baselines regenerated with `--update-baseline`, no `--allow-break`, no migration).
+
+```bash
+node scripts/release.mjs changed --baseline c600eaa18f65b56764ec2fb408ec813536eff6f7   # 30 packages
+# per-package: node scripts/release.mjs bump --package <name> --type patch (applied by plan 039 task 8)
+node scripts/release.mjs gate --update-baseline --skip-tarball
+node scripts/release.mjs check --independent --baseline c600eaa18f65b56764ec2fb408ec813536eff6f7
+node scripts/release.mjs publish --independent --baseline c600eaa18f65b56764ec2fb408ec813536eff6f7 --dry-run
+# publish tags (operator handoff; not this task): push the 30 annotated
+# `<name>@<version>` package tags (e.g. @arnilo/prism@0.3.1,
+# @arnilo/prism-obscura@0.3.0, @arnilo/prism-rag@0.3.2) — release.yml's publish
+# job runs deterministic release:publish in dependency order with OIDC provenance.
+```
+
+**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.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**.
@@ -859,10 +913,11 @@ 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 **exact** `@arnilo/prism@0.2.9` peer (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). **Peer-version policy (plan 024, Decision A — exact pins):** the peer spec is the bare exact current version — no `~`/`^`/`>=` range, no `*` — for the whole 0.2.x line, and all `@arnilo/prism-*` packages move at the same version (the **atomic-upgrade rule**). A partial upgrade (e.g. `@arnilo/prism@0.2.8` installed with a package peering `@arnilo/prism@0.2.9`) is unsupported and fails clearly at install time with `ERESOLVE unable to resolve dependency tree` naming the conflicting peer — never a silent install of a pair that was never tested together. A third-party `@arnilo/prism-*` adapter declares the same exact peer on the documented current version; an unsupported mixture fails at install time, not at runtime. The range widens to `^1.0.0` at the 1.x stable release (the 1.0 readiness gates go operator-green on the 0.2.x line); rollback of a release moves the pins back atomically with the manifests/tag. 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 55 manifests (root + 54 workspace packages: 48 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.
+- **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.
+- **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).
-- **Release workflow.** `.github/workflows/release.yml` has six jobs. `verify` runs network-free SDK readiness on Node 24; `node20-compat` builds/imports every public root `exports` default target on Node 20 for declared `engines.node >=20` (docs examples need Node >=22.6 native TypeScript stripping); `postgres-integration` uses `pgvector/pgvector:pg16`; `supply-chain` runs high-severity audit, SPDX/license policy, and tracked-source secret scanning; and tag-only `codeql-release` runs SAST. Tag-only `publish` needs all five gates, preserves clean exact-tag/version/topological publication, and alone receives `NPM_TOKEN`, `id-token: write`, and `attestations: write`. Before npm publish it packs all current tarballs, generates checksums plus SPDX, scans unpacked public artifacts, creates GitHub attestations for tarballs and SBOM, then retains artifacts for 30 days. Registry state remains the resumable journal. Local `npm run release:dry-run` remains network-free SDK readiness; local PostgreSQL coverage is `PRISM_TEST_POSTGRES_URL=... npm run test:postgres`.
+- **Release workflow.** `.github/workflows/release.yml` has six jobs. `verify` runs network-free SDK readiness on Node 24; `node20-compat` builds/imports every public root `exports` default target on Node 20 for declared `engines.node >=20` (docs examples need Node >=22.6 native TypeScript stripping); `postgres-integration` uses `pgvector/pgvector:pg16`; `supply-chain` runs high-severity audit, SPDX/license policy, and tracked-source secret scanning; and tag-only `codeql-release` runs SAST. `publish` runs on `v0.3.0` for the one lockstep cut and on `@arnilo/*@*` package tags afterward; it needs all five gates, preserves clean tagged/version/topological publication, and alone receives `NPM_TOKEN`, `id-token: write`, and `attestations: write`. Before npm publish it packs all current tarballs, generates checksums plus SPDX, scans unpacked public artifacts, creates GitHub attestations for tarballs and SBOM, then retains artifacts for 30 days. Registry state remains the resumable journal. Local `npm run release:dry-run` remains network-free SDK readiness; local PostgreSQL coverage is `PRISM_TEST_POSTGRES_URL=... npm run test:postgres`.
 - **Adding a package.** New workspace packages are picked up automatically by `npm run build --workspaces`, `npm test --workspaces`, `npm run pack:dry-run`, the packaging guard (`src/__tests__/packaging.test.ts`), and the install-smoke test (`src/__tests__/install-smoke.test.ts`) via the workspace glob; add the package to both tests' config arrays for explicit per-package assertions.
 
 ## Security and performance notes
@@ -1034,7 +1089,7 @@ 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 54 workspace packages (21 direct + 26 transitive); the deliberate Caveman/Ponytail/Impeccable opt-outs and the other non-closure packages (document-reader, OpenAPI tools, NATS) are not in its install set. |
+| 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. |
 | 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. |
@@ -1046,11 +1101,36 @@ Every release gate maps to an exact enforcement test or command, so the checklis
 
 A change that adds a public persistence/runtime surface, a new package, or a new example must extend the matching row's enforcement (add the page to `apiPages`, the package to the `packages` array, or the example to the demos list) so the checklist stays self-maintaining.
 
+## Independent package versioning (default after the 0.3.0 cut)
+
+`scripts/release.mjs` now defaults `check`, `publish`, and `gate` to **independent** (Decision B). Each package bumps only when it changes, internal pins stay in `^0.3.0`, and publication targets only changed packages at their own `name@version`. The final lockstep path is explicit: `--lockstep --version 0.3.0`.
+
+| Action | Command |
+| --- | --- |
+| List packages changed since a baseline tag | `node scripts/release.mjs changed [--baseline <tag>]` |
+| Bump one package (patch/minor/major) | `node scripts/release.mjs bump --package @arnilo/<name> --type patch` |
+| Validate current/mixed versions | `node scripts/release.mjs check --allow-dirty --allow-untagged` |
+| Validate the final lockstep cut | `node scripts/release.mjs check --lockstep --version 0.3.0 --allow-dirty --allow-untagged` |
+| Dry-run independent publish | `node scripts/release.mjs publish --dry-run --allow-dirty --allow-untagged` |
+| Resume interrupted package-tag publish | `node scripts/release.mjs publish --resume --report release-artifacts/publish-report.json` |
+| Convert the final cut to caret ranges | `node scripts/release.mjs bump --ranges caret --from 0.3.0 --to 0.3.0` |
+
+**Independent validate rules** (`validateReleaseIndependent`):
+
+- Every internal `@arnilo/*` range must satisfy the target package's actual version. On 0.x, `^` and `~` both mean `>=min <next-minor` (npm rule); exact pins must match. A `^0.3.0` pin does **not** satisfy `0.4.0`.
+- A changed package (git diff vs the baseline tag, or new at baseline) must have a version greater than the baseline; a changed package still at the baseline version fails with `bump required`.
+- An unchanged package must keep its version; an unchanged package with a bumped version fails with `was <baseline>`.
+- The lockfile per-package version must match each manifest version.
+
+**Independent publish** walks topological order over changed packages only and publishes each at its own version, skipping any `name@version` already on the registry whose internal dependency fingerprint matches the local manifest (resume-safe); a same-version manifest with different release fields fails closed (`already exists on the registry`). Real publication requires a clean tree and the package tag `@arnilo/<name>@<version>` pointing at HEAD. A generic `v*` tag is not a publish trigger after `v0.3.0`.
+
+No Changesets. No new runtime dependency. The 0.x caret window (`^0.3.0` = `>=0.3.0 <0.4.0`) is the independent band; the next coordinated peer bump is the 0.4.0 line.
+
 ## Pre-publish compatibility gates (`release:gate`)
 
-`npm run release:gate` (also run inside `npm run sdk:ready`) is the offline gate that must pass before `release:check`/`release:publish`. It runs three stages over the exact version graph (version defaults to the root manifest; no git or registry access):
+`npm run release:gate` (also run inside `npm run sdk:ready`) is the offline gate that must pass before `release:check`/`release:publish`. It runs three stages over the exact version graph; independent mode reads local git history for changed-package validation but never contacts the registry:
 
-- **ranges**: reuses `validateRelease` — exact internal version ranges and lockfile entries.
+- **ranges**: reuses `validateReleaseIndependent` by default, or `validateRelease` for explicit `--lockstep --version 0.3.0`; both verify internal ranges and lockfile entries.
 - **compat**: diffs every package's packed `.d.ts` surface (exported names + normalized declaration signatures, `export *` resolved within the package) against `scripts/compat-baseline/<pkg>.txt`. Removed or changed exports fail unless `--allow-break` is passed **and** `docs/migration.md` mentions the target version. Manifest-only profiles (no `main`/`types`/`exports`) are skipped. Regenerate baselines after a deliberate reviewed change with `node scripts/release.mjs gate --update-baseline`.
 - **tarball**: `npm pack --dry-run --json` file lists must not match the deny list (`code-reviews/`, `bug-reports/`, `plans/`, `scripts/benchmark-*`, `docs/review-coverage-*`, `__tests__/`, `*.map`). Root `files` excludes `docs/review-coverage-*` historical reviews.
 

package/docs/server.md

@@ -173,6 +173,7 @@ A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-super
 - [MCP client and server exposure](mcp-tools.md): selected MCP capabilities and web-standard MCP transport.
 - [Host security guide](host-security.md): remote-boundary checklist.
 - [A2A interoperability](a2a.md): separately mounted A2A 1.0 handler/client.
+- [Obscura browser engine](obscura.md): optional binary-backed generic tools for hosted agents.
 - [Conversations](conversations.md): durable user-scoped conversation service, replay, branches, export, deletion.
 - [Work artifacts and review](work-artifacts-and-review.md): durable artifact review service, revisions, approvals, authorized expiring delivery links.
 - [Frontend interoperability (AG-UI and ACP)](ag-ui.md): separately installed authorized AG-UI Web handler.

package/docs/supervisors.md

@@ -17,11 +17,11 @@ Use a supervisor when a host or agent must choose a child dynamically. Use `@arn
 | `delegate({ childId, input, threadId?, limits?, signal? })` | Invokes one allow-listed child. Input is text and byte-bounded. |
 | `hooks.before` | May reject, modify redacted input, or narrow limits/policy. |
 | `hooks.after` | Observes redacted terminal summary; failures cannot alter settled result. |
-| `limits` | Depth 4/16, active children 4/32, input 64 KiB/1 MiB, steps 8/64, tools 32/256, tokens 20k/1m, timeout 60s/30m, event queue 128/4096 default/hard. |
+| `limits` | Depth 4/16, active children 4/32, input 64 KiB/1 MiB, steps 8/64, tools 32/256, tokens 20k/1m, timeout 60s/30m, event queue 128/4096 default/hard. Over-cap `delegate()` throws `SupervisorLimitError` before incrementing `activeChildren`. Hook rejection and timeout decrement the count exactly once (no leaked timers). |
 
 ## Outputs / response / events
 
-`delegate()` returns the child's `AgentRunResult` or throws its `AgentRunError`/a supervisor denial or limit error. `subscribe()` emits bounded `delegation_started`, `delegation_finished`, `delegation_rejected`, and `delegation_error` metadata events. Hosts may project those events through observability `handleDelegation()` using the parent Prism run ID; no OpenTelemetry dependency enters this package.
+`delegate()` returns the child's `AgentRunResult` or throws its `AgentRunError`/a supervisor denial or limit error. `subscribe()` emits bounded `delegation_started`, `delegation_finished`, `delegation_rejected`, and `delegation_error` metadata events. Graceful close drains already-queued terminal events before the iterator completes (same core multiplexer contract). Hosts may project those events through observability `handleDelegation()` using the parent Prism run ID; no OpenTelemetry dependency enters this package.
 
 ## Request/response example
 
@@ -77,3 +77,4 @@ Supervisors propagate parent `identity` and `effectStore` to every child agent/r
 - [Workflows](workflows.md): preferred deterministic orchestration.
 - [Working and semantic memory](working-and-semantic-memory.md): child scope construction.
 - [Host security](host-security.md): permission and credential boundaries.
+- [Obscura browser engine](obscura.md): optional binary-backed generic tools for child agents.

package/docs/system-prompts.md

@@ -45,7 +45,7 @@ Known `source` order is deterministic: `user`, `package`, `app`, then `run`. Unk
 
 ## Outputs / response / events
 
-`composeSystemPrompt()` returns the composed prompt string or `undefined` when no prompt text remains. The agent/session runtime passes that string to `assembleProviderInput()` as `systemInstructions`; it does not emit a separate event or store prompt layers.
+`composeSystemPrompt()` returns the composed prompt string or `undefined` when no prompt text remains. The agent/session runtime passes that string to `assembleProviderInput()` as `systemInstructions`; it does not emit a separate event or store prompt layers. With the default `cache_aware` layout, this composed system message is emitted before dynamic context, skills, history, tool results, and current input; set `inputLayout: "legacy"` to retain the prior whole-prompt order.
 
 ## Request/response example
 

package/docs/tools.md

@@ -216,7 +216,7 @@ By default tools without `parameters` skip schema validation (`missingSchema: "a
 
 ### Parallel tool execution (single-shot loop)
 
-Opt in through `loop.toolConcurrency` on `AgentConfig` / `RunOptions` (single-shot strategy only). Default is `1` (sequential). Independent calls from one provider turn run concurrently up to the limit; transcript rows and `appendMessage` stay in original call order. Each call still uses `dispatchToolCall` (permission, validation, abort signal). See [Agent loops](agent-loops.md).
+Opt in through `loop.toolConcurrency` on `AgentConfig` / `RunOptions` (single-shot strategy only). Default is `1` (sequential). Independent calls from one provider turn run concurrently up to the limit; transcript rows and `appendMessage` stay in original call order. Each call still uses `dispatchToolCall` (permission, validation, abort signal). If a worker throws or the run aborts, workers stop claiming new calls, already-claimed calls settle, buffered tool-result rows are not appended, and the first failure is rethrown. Already-claimed side effects are not rolled back; the shared abort signal is still passed to each dispatch. The round-level `chargeToolRound` approval gate runs before any worker starts. See [Agent loops](agent-loops.md).
 
 ```ts
 await session.run(input, {

package/docs/web-tools.md

@@ -8,6 +8,8 @@
 
 Use when agent needs explicit public-web discovery or host-approved document retrieval/extraction. Keep search separate from fetch/extract so model cannot select provider, credential, API origin, extraction schema, or cost path.
 
+**Obscura-backed alternative**: the optional [`@arnilo/prism-obscura`](obscura.md) package provides `web_search`/`web_fetch` behavior backed by a host-installed Obscura headless browser through its CLI (one replaceable HTML search profile instead of an API key), plus explicit native `obscura_fetch`/`obscura_scrape` batch tools. It reuses this package's normalized citation/untrusted shapes (`provider: "obscura"`) but does not require credentials; the API-backed Brave/Exa/Firecrawl adapters here remain the preferred path when an API key is available.
+
 ## Inputs / request
 
 | Tool | Model-visible input | Host-only construction input |

package/docs/wiki.md

@@ -0,0 +1,140 @@
+# LLM Wiki (@arnilo/prism-wiki)
+
+## What it does
+
+`@arnilo/prism-wiki` implements Andrej Karpathy's **LLM Wiki Pattern** for the Prism agent ecosystem. It acts as a knowledge compiler that transforms raw, immutable sources (source code, AST symbols, notes, markdown clips, transcripts, journal entries) into a persistent, compounding, cross-linked Markdown knowledge base (`.wiki/`).
+
+It integrates Tobias Lütke's [`qmd`](https://github.com/tobi/qmd) on-device hybrid search engine (BM25, vector search, and LLM reranking) and hydrates search results with Context7-inspired hierarchical breadcrumbs (`# Category > ## Topic`) and live clickable source line anchors (`file:///path/to/file#Lxx-Lyy` format), enabling agents and humans to navigate code and notes directly without blind regex loops (`grep`/`rg`).
+
+## When to use it
+
+- **Codebase Knowledge Compilation**: Ingesting modules, architecture patterns, and decision records (ADRs) with exact AST and line anchors that track code drift.
+- **Personal Knowledge Management (PKM)**: Ingesting research papers, meeting notes, book summaries, and journal entries into an interlinked knowledge graph.
+- **Context7-Style Navigation**: Allowing agents to query concepts and immediately jump to exact file and line locations without broad repository scans.
+- **Compounding Q&A**: Persisting valuable answers, analyses, and architectural comparisons back into the wiki for future sessions.
+
+## Architecture
+
+The Karpathy LLM Wiki pattern is structured into 3 distinct tiers:
+
+1. **Raw Sources (Immutable)**: Source code files, design docs, transcripts, journals, and Markdown notes. Raw sources are strictly read-only and never mutated.
+2. **Compiled Wiki (`.wiki/`)**: Persistent, cross-linked Markdown documents containing synthesized architecture models, entity descriptions, decision records, and line-anchored claims.
+3. **Schema & Protocols (`SCHEMA.md`)**: Operational guidelines governing entity categorization, link formatting (`[[wikilink]]`), citation rules (`file:///path#Lxx-Lyy`), catalog indexing (`index.md`), and chronological change logging (`log.md`).
+
+## Inputs / request
+
+### `createWikiExtension(options)`
+
+| Field | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `wikiRoot` | `string` | No | `".wiki"` | Path to the compiled wiki directory. |
+| `rawRoots` | `readonly string[]` | No | `["."]` | Directories containing raw source files (code, notes, docs). |
+| `profile` | `"codebase" \| "pkm" \| "hybrid" \| "auto"` | No | `"auto"` | Operating strategy for parsing and symbol indexing. |
+| `qmdPath` | `string` | No | `"qmd"` | Path or executable name for the `qmd` CLI binary. |
+| `workspaceRoot` | `string` | No | `process.cwd()` | Workspace root for resolving relative paths and `.agents/skills/`. |
+| `autoDeploySkills` | `boolean` | No | `true` | Auto-deploys `wiki-maintainer` and `wiki-searcher` skills to `.agents/skills/` on init. |
+
+### Tools
+
+- `wiki_search`: `{ query: string, mode?: "search" | "vsearch" | "query", maxResults?: number }`
+- `wiki_read_page`: `{ pagePath: string }` — `pagePath` must resolve inside the wiki root (lexical + `fs.realpath` containment). Traversal (sibling-prefix, `..`, absolute paths) and symlinks pointing outside the wiki throw an access-denied error; a missing contained page returns `found: false`.
+- `wiki_record_insight`: `{ title: string, content: string, category?: "decision" | "concept" | "entity" }` — title and content must be non-empty; titles are capped at 200 characters, content at 65,536 bytes, and control characters/newlines in titles are collapsed to spaces so titles cannot inject Markdown headings, index entries, or log entries.
+
+### Slash Commands
+
+- `/wiki-init`: Scaffolds `.wiki/`, instantiates `SCHEMA.md`, `index.md`, and `log.md`, deploys skills, and adds the `qmd` collection.
+- `/wiki-refresh`: Detects modified source files via SHA-256 Merkle diffing, compiles updates to affected entity pages, reconciles contradictions in `log.md`, and runs `qmd update`.
+- `/wiki-lint`: Checks for broken `[[wikilinks]]`, dead line anchors, orphan pages, and unindexed symbols.
+
+### Standalone CLI Commands
+
+```bash
+# Initialize wiki in project
+npx prism-wiki init --profile codebase
+
+# Refresh wiki after code edits
+npx prism-wiki refresh
+
+# Check wiki health and dead anchors
+npx prism-wiki lint
+
+# Search wiki from terminal
+npx prism-wiki search "How does authentication work?" --mode query
+```
+
+## Outputs / response / events
+
+- `wiki_search` returns a structured markdown payload containing section breadcrumbs, conceptual summaries, and clickable source line links (`file:///path#Lxx-Lyy`).
+- Lifecycle commands return status objects (`{ status: "initialized" | "refreshed" | "clean", ok: boolean }`).
+
+## Request/response example
+
+### `wiki_search` Query:
+```json
+{
+  "query": "How is authentication handled?",
+  "mode": "query",
+  "maxResults": 2
+}
+```
+
+### Response Content:
+```markdown
+### Match 1: Authentication Architecture > Token Verification
+- **Wiki Page:** [[entities/authentication.md]]
+- **Category:** Core Module
+- **Freshness:** Current (Source hash matches manifest)
+
+**Synthesized Summary:**
+The authentication layer uses asymmetric Ed25519 JWT verification in middleware, backed by a persistent token-revocation denylist stored in PostgreSQL.
+
+**Code & Source Anchors (Clickable):**
+- Token verification: `verifyToken()` (`file:///src/auth/jwt.ts#L45-L89`)
+- Revocation check: `assertNotRevoked()` (`file:///src/auth/session-store.ts#L112-L138`)
+- Architecture Decision: [[decisions/ADR-004-ed25519-migration.md]]
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createWikiExtension, initWiki, refreshWiki, lintWiki } from "@arnilo/prism-wiki";
+
+const kernel = createExtensionKernel();
+
+const wiki = createWikiExtension({
+  wikiRoot: ".wiki",
+  profile: "codebase",
+});
+
+await kernel.load([wiki]);
+```
+
+## Skills and Auto-Deployment
+
+`@arnilo/prism-wiki` includes two specialized skills formatted according to `.agents/skills/skill-creator`:
+
+1. **`wiki-maintainer`**: Ingestion, compilation, line-anchor validation, and contradiction reconciliation rules.
+2. **`wiki-searcher`**: Context7 hierarchical breadcrumb query resolution, zero-grep instructions, and compounding insight recording.
+
+When initialized (`wiki-init` or `createWikiExtension`), these skills are automatically deployed to the host workspace's `.agents/skills/` folder so any compatible agent can leverage them immediately.
+
+## Extension and configuration notes
+
+- `@arnilo/prism-wiki` registers tools (`wiki_search`, `wiki_read_page`, `wiki_record_insight`), commands (`wiki-init`, `wiki-refresh`, `wiki-lint`), skills (`wiki-maintainer`, `wiki-searcher`), and instruction injectors (`wiki-guidance`) into Prism registries.
+- It operates with zero core modifications and can be used with any `@arnilo/prism` agent.
+- `qmd` is optional but recommended. When `@tobilu/qmd` is not installed, the search engine falls back to catalog matching against `index.md`.
+
+## Security and performance notes
+
+- **Source Immutability**: Raw source files are read-only and never modified by wiki operations.
+- **Subprocess Safety**: All `qmd` subprocess calls use argument arrays (`execFile`) to prevent shell injection.
+- **Path Containment**: Wiki and raw source paths are confined to the workspace root; directory traversal (`../`) is rejected.
+- **Bounded Token Consumption**: Incremental Merkle hashing ensures only modified files and 1-hop dependent wiki pages are processed during refresh passes.
+
+## Related APIs
+
+- [`@arnilo/prism-rag`](rag.md): Bounded document chunking and vector context injection.
+- [`@arnilo/prism-memory`](working-and-semantic-memory.md): Embedder and VectorStore primitives.
+- [`@arnilo/prism-coding-agent`](coding-agent-tools.md): Code manipulation and reading tools.
+- [`Contribution registries`](contribution-registries.md): Extension contribution model.

package/docs/workflows.md

@@ -78,7 +78,7 @@ A function node returns `suspend({ reason, data?, resumeSchema? })` to persist `
 
 Coding-agent ask-user glue (opt-in, no Goal DB): `suspendAskUserDecision(request)` wraps `suspend` with durable question/options/`selectionMode`/`allowCustom` data + resume schema; resume with `createAskUserDecisionResumeValidator()` or `validateAskUserDecisionResume`. Goal→verify: `runCodingGoalVerify` / `createCodingGoalVerifyWorkflow` compose plan Markdown → named checks → approve suspend → bounded handoff over the same primitives (`examples/coding-goal-verify.ts`). When a workflow node wraps a durable agent run, that run's shared pending-decision batch (Task 2) is the approval authority — workflow `suspend`/`resume` stay workflow-scoped and do not mint a parallel decision store.
 
-Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.updateState(patch, { mode: "merge" | "replace" })`. Updates serialize, validate, redact, and snapshot before checkpoint save. `workflowNode({ workflow })` runs its child with the same ownership, agent/tool registries, execution policy, redactor, signal, checkpoints, and event bus; child state replaces parent state after success.
+Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.updateState(patch, { mode: "merge" | "replace" })`. Updates serialize, validate, redact, and snapshot before checkpoint save. A rejected state or checkpoint write stays rejected (nothing committed) and recovers the per-run chain so a later valid write can run. `workflowNode({ workflow })` runs its child with the same ownership, agent/tool registries, execution policy, redactor, signal, checkpoints, and event bus; child state replaces parent state after success.
 
 `replayWorkflow(workflow, { sourceRunId, fromNodeId, runId? }, options)` requires a succeeded source/node, creates a new checkpoint, copies terminal evidence outside the selected node's downstream closure, restores selected-node pre-state, and records `{ sourceRunId, fromNodeId, rootRunId, depth }`. Source evidence is untouched. Copying any prior nested/tool approval is rejected; replay from that approval node or earlier so Phase 8 approval executes again.
 
@@ -304,7 +304,7 @@ runRpcServer({
 
 - Workflow semantics stay in this optional package; generic checkpoint persistence and bounded event fan-in live in core.
 - `ProductionPersistenceStore.checkpoints` and `.leases` are optional generic capabilities. First-party SQLite/PostgreSQL adapters own `prism_checkpoints` / `prism_leases`; workflows only adapt them. Sagas use the same `WorkflowCheckpointAdapter` and `LeaseStore`; they add no SQL table or scheduler.
-- `createWorkflowEventBus()` delegates queueing, source fan-in, overflow, abort, and close behavior to core `createEventMultiplexer()`, including its single-consumer contract: a second concurrent `subscribe()` is rejected with `EventMultiplexerError` (`ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER`) instead of silently splitting the stream.
+- `createWorkflowEventBus()` delegates queueing, source fan-in, overflow, abort, and close behavior to core `createEventMultiplexer()`, including its single-consumer contract: a second concurrent `subscribe()` is rejected with `EventMultiplexerError` (`ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER`) instead of silently splitting the stream. Graceful `close()` stops new emits/sources and drains already-queued events (in `(sequence, nodeId)` order) before the subscriber completes; overflow `close` still emits one `workflow_event_overflow` notice and terminates.
 - The in-process active-run registry (`registerActiveWorkflowRun` / `getActiveWorkflowRun` / `abortActiveWorkflowRun`) is **non-durable, in-process only — it does not survive restart**; durable active-run recovery is a later milestone. It is bounded: every register sweeps aborted/leaked entries (runs whose promise never settled) and the registry fails closed at `MAX_ACTIVE_WORKFLOW_RUNS` (512) rather than evicting a live run; `sweepActiveWorkflowRuns()` is available for hosts. Cross-tenant lookups stay ownership-isolated.
 - `createWorkflowCommands()` is optional; hosts can drive `workflow.start` / `enqueue` / `replay` / `status` / `list` / `cancel` / `resume`. The six `schedule.*` commands appear only when a scoped `schedules` service is supplied.
 - Hosts may bridge `WorkflowEvent` into OpenTelemetry or custom sinks; there is no built-in TUI.
@@ -314,7 +314,7 @@ runRpcServer({
 ## Security and performance notes
 
 - Definitions require a non-empty host-authored `revision` and fail closed on cycles, unknown edges, self-edges, invalid limits, and `maxNodes` overflow. Revision and every nested revision enter the deterministic definition hash; hosts must bump revision when function/tool behavior changes.
-- Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`; every count/byte/runtime option has a finite hard cap.
+- Fan-out length is bounded by `maxFanOut`. Independent `map` items run in a local worker pool capped by the resolved workflow `maxConcurrency` (and `options.concurrency`); output stays in input order. Abort or the first map failure stops further items. There is no extra global admission service.
 - Node outputs, shared state/history, schedule input/records, and checkpoints are byte/count/depth bounded. Checkpoint size remains the final aggregate ceiling.
 - Event buses use a bounded buffer (default 2048) with `close` / `drop_oldest` / `drop_newest` overflow.
 - Checkpoints redact suspension/resume payloads via `SecretRedactor` / `secrets` before save; resume rejects tenant, schema, definition-hash, and expected-version mismatch.
@@ -342,6 +342,7 @@ Use workflows for known, durable, replayable graphs. Use optional supervisor del
 - [Agent/session runtime](agent-session-runtime.md): `AgentSession.run()`/`stream()`, abort, subscribe
 - [Guardrails](guardrails.md): `RunWorkflowOptions.guardrails` routes tool nodes through core dispatch before policy and side effects.
 - [Supervisor delegation](supervisors.md): bounded dynamic child selection.
+- [Obscura browser engine](obscura.md): optional binary-backed generic tools for `toolNode`/`agentNode` composition.
 - [A2A interoperability](a2a.md): hosts may adapt existing exact-owner workflow status/list/cancel/checkpoint/event surfaces to `A2ATaskLifecycle`; A2A package adds no workflow worker, queue, or schema.
 - [Agent events](agent-events.md): core `AgentEvent` wrapped by `agent_event`
 - [Session stores and branching](session-stores-and-branching.md): session `leafId` reuse on resume

package/docs/working-and-semantic-memory.md

@@ -155,6 +155,24 @@ const memory = createMemory({
 });
 ```
 
+Standalone durable vector store for RAG:
+
+```ts
+import { createPostgresVectorStore, createHashEmbedder } from "@arnilo/prism-memory";
+
+const store = await createPostgresVectorStore({
+  connectionString: process.env.DATABASE_URL!,
+  schema: "prism_memory", // default
+  table: "semantic_memory", // default
+  dimension: 32, // optional; pins the embedding column width (HNSW + drift guard)
+}); // PostgresVectorStoreOptions; dimension must match the embedder's dimensions
+// store implements rag's VectorStore/TransactionalVectorStore contract: upsert,
+// query, getBySource, transaction, lexicalQuery (fts, when available), and
+// getCurrentGeneration/setCurrentGeneration. close() ends adapter-owned pools.
+```
+
+`createPostgresVectorStore()` is the production counterpart to `createMemoryVectorStore()` used by `@arnilo/prism-rag`; `createPostgresMemoryStores()` reuses the same vector implementation internally.
+
 ## Extension and configuration notes
 
 - Hosts wire the context provider into `AgentConfig.context` or `resolveContextProviders()`.
@@ -162,6 +180,8 @@ const memory = createMemory({
 - `createHashEmbedder()` is for tests/demos only; production hosts supply a real `Embedder`.
 - Observational memory (`@arnilo/prism-compaction-observational-memory`) remains unchanged and composable.
 - Consent is enforced at the single `recall()` gate, so both direct recall and `createContextProvider()` injection honor it; `visible: false` (or a revoked grant) keeps an entry out of prompts, events, exports, and telemetry. `setConsent`/`correct` re-upsert in place (consent change does not re-embed); `forget`/`applyRetention` are real deletes, not tombstones. Retention uses indexed oldest-first pages plus a scoped count, deleting one default-500/hard-5000 batch without reading a corpus into memory. The PostgreSQL adapter persists consent in a `consent JSONB` column added by `buildMemoryDdl`.
+- The PostgreSQL vector path owns its DDL in Prism (`buildMemoryDdl`/`buildVectorSearchDdl` exported): the `<table>_rag_scope_generations` per-scope generation pointer table, `text_tsv` tsvector column + GIN index for the lexical RAG leg, and an HNSW index when the embedding dimension is pinned. DDL runs against the host's **knowledge database** — the host names `schema`/`table` (defaults `prism_memory`/`semantic_memory`), owns backup/retention of that database, and can run migrations manually with `skipMigrations: true`. Identifiers are validated/quoted; values stay parameterized.
+- `createPostgresVectorStore({ dimension })` pins the embedding column width before building indexes: pgvector can only build HNSW over `vector(N)` columns, and dimension mismatch fails closed instead of drifting.
 - `exportMemory()` requires an exact `{ tenantId, resourceId, threadId }` identity equal to its `createMemory()` scope. It excludes legacy consent-less, invisible, and revoked records even when normal recall allows legacy entries. It returns a stable sequence cursor page, redacted before response, with defaults/hard caps of 100/200 entries, 4/32 MiB, and 10/60 seconds. `rebuildIndex()` uses the same stable cursor shape to re-embed one 32/128-record page under a 10/60-second cap; save the cursor durably to resume. Both APIs require a store implementing bounded `listByThread()`; retention also requires `countByThread()`. PostgreSQL/pgvector and the in-memory reference adapter conform; SQLite persistence stores sessions, not semantic vectors.
 - Profile bundles do not include this package yet.