@arnilo/prism 0.2.8 → 0.3.0

package/docs/providers/deepseek.md

@@ -0,0 +1,147 @@
+# DeepSeek provider package
+
+## What it does
+
+`@arnilo/prism-provider-deepseek` provides explicit, side-effect-free setup for the
+DeepSeek Chat Completions API (`POST /chat/completions`) with official thinking
+mode, reasoning-effort mapping, tool-turn `reasoning_content` replay, and
+implicit prefix caching.
+
+The package registers a provider, featured V4 model metadata, and an `api_key`
+auth method through `createExtensionKernel().load([...])`.
+
+## When to use it
+
+Use it when a host app wants DeepSeek V4 Flash / Pro through Prism's
+`AgentSession` runtime with official `thinking` / `reasoning_effort` mapping
+and automatic KV prefix cache.
+
+Do not use it for the Anthropic-compatible route, automatic credential
+discovery, setup-time catalog fetches, or real-network tests.
+
+## Inputs / request
+
+```ts
+import {
+  createDeepSeekProviderPackage,
+  defineDeepSeekModel,
+  listDeepSeekModels,
+} from "@arnilo/prism-provider-deepseek";
+
+createDeepSeekProviderPackage(options: DeepSeekProviderPackageOptions): ProviderPackage
+defineDeepSeekModel(config: DeepSeekModelConfig): ModelConfig
+listDeepSeekModels(options?: ListDeepSeekModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides the DeepSeek base URL (default `https://api.deepseek.com`). |
+| `id` | `string` | Overrides the provider id (default `deepseek`). |
+| `models` | `readonly ModelConfig[]` | Overrides featured `deepseekModels` defaults. |
+
+### Thinking / reasoning compat
+
+Official body fields (request `options.compat` wins over `model.compat`):
+
+| Compat / body field | Wire shape | Notes |
+| --- | --- | --- |
+| `thinking` | `boolean` or `{ type: "enabled" \| "disabled" }` | Default **enabled**. Boolean `true`/`false` maps to those types. |
+| `reasoning_effort` | `low` \| `high` \| `max` | Default `high`. Portable `medium` and `xhigh` map to `high`. Omitted when thinking is disabled. |
+
+`applyThinkingLevel(..., "thinking_type")` toggles `thinking.type`. Set
+`reasoning_effort` in `compat` for effort. `ProviderRequestOptions.cacheRetention: "none"`
+forces `thinking: { type: "disabled" }`.
+
+Thinking mode ignores `temperature`, `top_p`, `presence_penalty`, and
+`frequency_penalty`; this adapter strips them so they cannot break the cache prefix.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (`delta.reasoning_content`), tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Block preservation | Text; thinking → `reasoning_content` on tool-turn assistants (otherwise dropped, never flattened into text); assistant `tool_call` → `tool_calls`; `tool_result` → role `tool`. |
+| Auth method | `api_key` for the configured provider id, credential name `apiKey`. |
+| Usage | `prompt_cache_hit_tokens` → `Usage.cacheReadTokens` via `mapOpenAIChatUsage`. |
+
+Unsupported media blocks fail before fetch. Text-only input.
+
+## Request/response example
+
+```json
+{
+  "model": "deepseek-v4-flash",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true,
+  "thinking": { "type": "enabled" },
+  "reasoning_effort": "high"
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createDeepSeekProviderPackage, listDeepSeekModels } from "@arnilo/prism-provider-deepseek";
+
+const kernel = createExtensionKernel();
+await kernel.load([createDeepSeekProviderPackage({ apiKey: "fake-deepseek-key" })]);
+
+const live = await listDeepSeekModels({ apiKey: "fake-deepseek-key" });
+await kernel.load([createDeepSeekProviderPackage({ apiKey: "fake-deepseek-key", models: live })]);
+```
+
+Per-turn thinking override:
+
+```ts
+await session.prompt("Plan the refactor", {
+  providerOptions: {
+    compat: {
+      thinking: { type: "enabled" },
+      reasoning_effort: "low",
+    },
+  },
+});
+```
+
+## Extension and configuration notes
+
+- Default base URL is `https://api.deepseek.com`. The Anthropic-compatible
+  route is not implemented.
+- Featured `deepseekModels` are offline bootstrap aliases (`deepseek-v4-flash`,
+  `deepseek-v4-pro`) with 1M context / 384k max output, `cache.kind: "implicit"`,
+  and documented USD-per-million cost including cache-read.
+- `listDeepSeekModels()` is caller-gated `GET {base}/models`. Setup never fetches.
+- Tool JSON Schema keys (`properties` / `required`) are sorted before send so the
+  implicit prefix stays stable.
+- Tool-turn assistants must replay `reasoning_content` or the API returns 400.
+  Non-tool multi-turn may omit it (the API ignores it).
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded transport helpers.
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- API keys are resolved per request and redacted from errors (including discovery).
+- Provider-owned headers (`content-type`, `authorization`) win over caller headers.
+- One POST per generate. No provider retry loop.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus `DEEPSEEK_API_KEY`.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, per-turn thinking.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable
+  `applyThinkingLevel` → DeepSeek `thinking.type` / `reasoning_effort`.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider caching](../provider-caching.md): implicit DeepSeek prefix cache.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.
+
+## Official evidence
+
+- [Thinking Mode](https://api-docs.deepseek.com/guides/thinking_mode)
+- [KV Cache](https://api-docs.deepseek.com/guides/kv_cache)
+- [Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)

package/docs/providers/openai.md

@@ -54,7 +54,7 @@ uses official Responses `reasoning: { effort, summary? }` via
 | Continuation | An incomplete Responses stream self-resumes at most eight HTTP hops using opaque `previous_response_id`; a cursor is at most 4 KiB, is never replayed, and is observable as `continuation_required`. |
 | Realtime | `createOpenAIRealtimeSession()` exposes server-session creation, audio in/out, transcript deltas, provider-hosted calls, interrupt, and idempotent close through the neutral `RealtimeSession` seam. |
 | Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant host `tool_call` → top-level `function_call` with `call_id`; provider-hosted calls are not replayed; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
-| Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. This is Prism's only first-party subscription OAuth flow in 0.0.12. |
+| Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. xAI SuperGrok is the other first-party subscription OAuth flow ([xAI](xai.md)). |
 
 Unsupported block placements or unclaimed images fail before `fetch`. Provider-hosted calls are telemetry only: Prism never dispatches them as host tools or sends a `tool_result`.
 

package/docs/providers/xai.md

@@ -0,0 +1,138 @@
+# xAI provider package
+
+## What it does
+
+`@arnilo/prism-provider-xai` provides explicit, side-effect-free setup for the
+xAI Grok Chat Completions API (`POST https://api.x.ai/v1/chat/completions`)
+with implicit prefix caching via a sanitized `x-grok-conv-id` header, reasoning
+replay, and host-invoked SuperGrok / X Premium OAuth.
+
+The package registers a provider, featured Completions models, an `api_key`
+auth method, and an `oauth` auth method (`createXaiOAuthProvider`, id `xai`).
+
+## When to use it
+
+Use it when a host wants Grok 4.6 / 4.3 / Build through Prism with either an
+xAI API key or a SuperGrok / X Premium subscription login.
+
+Do not use it for Responses-only `grok-4.5`, PKCE loopback, `cli-chat-proxy.grok.com`,
+`~/.grok` credential import, or setup-time catalog fetches.
+
+## Inputs / request
+
+```ts
+import {
+  createXaiOAuthProvider,
+  createXaiProviderPackage,
+  listXaiModels,
+} from "@arnilo/prism-provider-xai";
+
+createXaiProviderPackage(options: XaiProviderPackageOptions): ProviderPackage
+createXaiOAuthProvider(options?: XaiOAuthOptions): OAuthProvider
+listXaiModels(options?: ListXaiModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | API key **or** SuperGrok access token (host wires after `login` / `refreshOAuthCredential`). |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Default `https://api.x.ai/v1`. |
+| `id` | `string` | Provider id (default `xai`). |
+| `models` | `readonly ModelConfig[]` | Overrides featured `xaiModels`. |
+| `oauth` | `XaiOAuthOptions` | Optional client id / endpoints / referrer overrides. |
+
+### Cache header
+
+`x-grok-conv-id` is `sanitizeCacheKey(cache.key ?? cacheKey ?? sessionId, 128)`.
+Omitted when `cache.mode` is `off`, `cacheRetention` is `none`, or the key sanitizes empty.
+
+### SuperGrok OAuth
+
+RFC 8628 device-code. Default public client id
+`b1a00492-073a-47ea-816f-4c329264a828` is **not a secret**. Scope
+`openid profile email offline_access grok-cli:access api:access`. Referrer
+default `prism`. Endpoints: `https://auth.x.ai/oauth2/device/code`,
+`/token`, `/revoke`. Form-urlencoded bodies. `verification_uri` /
+`verification_uri_complete` must be `https:`. Refresh keeps the previous
+`refresh_token` when omitted and applies a 5-minute expiry skew. Revoke is
+best-effort; `revokeOAuthCredential` still deletes the local store.
+
+No PKCE loopback. Login requires `onDeviceCode`. Setup never logs in.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (`delta.reasoning_content` / `delta.reasoning`), tool-call, `usage`, `done`, redacted `error`. |
+| Cache usage | `prompt_tokens_details.cached_tokens` → `cacheReadTokens`. If `cached_tokens > prompt_tokens` (exclusive report), values are kept as-is; unused input is not invented. |
+| Auth | `api_key` and `oauth` (`getCredential` → `{ type: "bearer", value: access }`). |
+| Images | Allowed when `capabilities.input` includes `image`. Rejected otherwise. |
+
+## Request/response example
+
+```json
+{
+  "model": "grok-4.6",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true
+}
+```
+
+Header: `x-grok-conv-id: sess-1`.
+
+## Implementation example
+
+```ts
+import { createExtensionKernel, refreshOAuthCredential } from "@arnilo/prism";
+import { createXaiOAuthProvider, createXaiProviderPackage } from "@arnilo/prism-provider-xai";
+
+const kernel = createExtensionKernel();
+await kernel.load([createXaiProviderPackage({ apiKey: "fake-xai-key" })]);
+
+const oauth = createXaiOAuthProvider();
+const creds = await oauth.login({
+  onDeviceCode: ({ userCode, verificationUri }) => {
+    console.log(`Open ${verificationUri} and enter ${userCode}`);
+  },
+});
+await store.set("xai", creds);
+
+await kernel.load([
+  createXaiProviderPackage({
+    apiKey: async () => {
+      const current = await store.get("xai");
+      return (await refreshOAuthCredential({ provider: oauth, credentials: current, store })).access;
+    },
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Featured Completions: `grok-4.6` (500k), `grok-4.3` (1M), `grok-build-0.1` (256k). All image + reasoning, `cache.kind: "implicit"`.
+- `grok-4.5` / Responses API is not implemented.
+- `listXaiModels()` is caller-gated `GET {base}/models`. Setup never fetches.
+- Reasoning models replay `reasoning_content` and do not flatten thinking into text.
+- Generate always hits `https://api.x.ai/v1/chat/completions` (same backend for API key and SuperGrok access).
+
+## Security and performance notes
+
+- Public client id is documented as not a secret. Device/user/access/refresh codes are redacted.
+- HTTPS verification URI only. No PKCE loopback. No `~/.grok/**` or env scan.
+- Provider-owned headers (`authorization`, `content-type`) win. Conv-id is never a credential.
+- Bounded OAuth and API error bodies. No retry loop. No refresh timer.
+- Live API-key smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `XAI_API_KEY`. SuperGrok login is operator-only (`PRISM_LIVE_XAI_OAUTH=1`).
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): OAuth support matrix.
+- [Credentials and redaction](../credentials-and-redaction.md): SuperGrok is authorized; Claude/Gemini are not.
+- [Credential storage](../credential-storage.md): host-owned store after explicit `login`.
+- [Provider caching](../provider-caching.md): implicit xAI prefix cache + conv-id.
+- [Thinking and reasoning](../thinking-and-reasoning.md): xAI reasoning replay.
+- [OpenAI Codex](openai.md): the other first-party subscription OAuth flow.
+
+## Official evidence
+
+- [Prompt caching](https://docs.x.ai/developers/advanced-api-usage/prompt-caching)
+- [OIDC discovery](https://auth.x.ai/.well-known/openid-configuration)

package/docs/release-and-install.md

@@ -2,22 +2,22 @@
 
 ## What it does
 
-Prism is published as **51 publishable manifests**: the root `@arnilo/prism` core package plus **50 workspace packages** — 14 provider adapters, 9 `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 51st manifest is the 0.2.8 plan 028 spawnable ACP agent package `@arnilo/prism-acp-agent` (thin stdio wiring over `@arnilo/prism-ag-ui`; new packages land only when a closeout demands them). 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.0** line has **57 publishable manifests**: the root `@arnilo/prism` core package plus **56 workspace packages** — 17 provider adapters, 10 `prism-*` family/profile packages, and 29 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.) This final lockstep cut adds the host-owned `@arnilo/prism-computer-use-linux` wrapper and `@arnilo/prism-antigravity-agent`; after the cut, Decision B publishes changed packages independently inside `^0.3.0`. 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.8` 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@^0.3.0` peer; profiles are pure manifests. Installation activates no provider, listener, database, browser, credential, or tool capability.
 
-Current **51** publishable manifests (root + 50 workspace packages):
+Current **57** publishable manifests (root + 56 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-ponytail`, `@arnilo/prism-providers`, `@arnilo/prism-sdk`, `@arnilo/prism-provider-ai-sdk`
+`@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-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-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-computer-use-linux`, `@arnilo/prism-antigravity-agent`
 
-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 eleven `@arnilo/prism-provider-*` packages.
+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`).
 
 ## When to use it
 
@@ -31,7 +31,7 @@ Consumers install the core package for the runtime and add first-party packages
 | --- | --- |
 | 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 (11 of 14) | `npm install @arnilo/prism @arnilo/prism-providers` |
+| 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` |
@@ -46,16 +46,14 @@ Consumers install the core package for the runtime and add first-party packages
 | 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).
 
@@ -94,7 +92,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.8.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.2.8.tgz` / `arnilo-prism-compaction-<name>-0.2.8.tgz` / `arnilo-prism-coding-agent-0.2.8.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.2.8.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.0.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.3.0.tgz` / `arnilo-prism-compaction-<name>-0.3.0.tgz` / `arnilo-prism-coding-agent-0.3.0.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.3.0.tgz`. 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 +111,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 +123,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 +156,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 +173,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 +346,46 @@ 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.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**.
+
+**Rollback notes.** Rollback = restore the 0.2.8 manifests/tag. No persisted 0.2.8 shape changed; the added packages simply disappear.
+
+```bash
+node scripts/release.mjs bump --from 0.2.8 --to 0.2.9   # already applied by Task 10; idempotent
+npm test
+PRISM_CLIENT_NAMES=<names> node scripts/check-client-neutrality.mjs
+npm run sdk:ready
+node scripts/release.mjs gate --version 0.2.9
+npm run pack:dry-run
+npm audit --audit-level=moderate
+node scripts/scan-secrets.mjs && npm sbom --sbom-format spdx > security-artifacts/sbom.spdx.json && node scripts/verify-sbom.mjs
+npm run release:check -- --version 0.2.9 --report /tmp/prism-0.2.9-preflight.json
+npm run release:publish -- --version 0.2.9 --dry-run --allow-dirty --allow-untagged --report /tmp/prism-0.2.9-dry-run.json
+```
+
+Protected evidence stays the same classes as 0.2.8 plus SuperGrok live login (`PRISM_LIVE_XAI_OAUTH`) — always `protected`, never a silent pass. Publication remains the operator handoff (signed `v0.2.9` tag + npm OIDC).
+
 ### 0.2.8 publish handoff (plan 028 Task 18)
 
 **Decision: GO when the operator prerequisites below are recorded.** Release **0.2.8** (plan 028) is the ACP adoption-fixes cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.8: expected deltas are the version literal plus the plan 028 additive exports — `ToolKind`/`kind` on `ToolDefinition`, `AgentFinishReason`, `createCodingToolProjection`/`AgUiProjectedImage`/`AgUiProjectedToolResult`, `AcpCommand`/`AcpCommandsSeam`, `ERR_PRISM_ACP_RUN`, `acpImageBytes`/`acpCommandsPerUpdate`, and the new `@arnilo/prism-acp-agent` package; zero removals; baselines regenerated with `--update-baseline`, no `--allow-break`). Client names are scrubbed; `scripts/check-client-neutrality.mjs` is part of `release:gate`. ACP B1–B5 and F1–F10 as recorded in `plans/028-Release-0-2-8-ACP-Adoption-Fixes.md`. Release graph is **51** publishable manifests at exact **0.2.8** (root + 50 workspace). Store compatibility with 0.2.7: **compatible, no migration**.
@@ -838,10 +876,10 @@ 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.8` 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 51 manifests (root + 50 workspace packages: 44 code packages + 6 pure-manifest family/profile packages — the 9 `prism-*` family/profile set is the 6 pure-manifest profiles plus the 3 code packages `prism-caveman`, `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.0` peer (`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.
 - **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
@@ -1013,7 +1051,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 44 of the 50 workspace packages (21 direct + 23 transitive); the deliberate Caveman/Ponytail 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 56 workspace packages (21 direct + 26 transitive); the deliberate Caveman/Ponytail/Impeccable/computer-use-linux/antigravity-agent opt-outs and the other non-closure packages (document-reader, OpenAPI tools, NATS) 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. |
@@ -1025,11 +1063,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/thinking-and-reasoning.md

@@ -49,8 +49,8 @@ Core maps only shapes shared by ≥2 packages (or an explicit no-op). Unique kno
 | Family | Compat patch | Used by (official fields) |
 | --- | --- | --- |
 | `openai_reasoning` | `{ reasoning: { effort } }` | OpenAI Responses `reasoning.effort`; OpenRouter `reasoning.effort` |
-| `reasoning_effort` | `{ reasoning_effort }` | Z.AI `reasoning_effort`; NeuralWatt `reasoning_effort`; Kimi K3 `reasoning_effort` |
-| `thinking_type` | `{ thinking: { type: "enabled" \| "disabled" } }` | Z.AI `thinking.type`; Kimi K2.x `thinking.type` (`none` → `disabled`) |
+| `reasoning_effort` | `{ reasoning_effort }` | Z.AI `reasoning_effort`; NeuralWatt `reasoning_effort`; Kimi K3 `reasoning_effort`; DeepSeek `reasoning_effort`; ClinePass `reasoning_effort` |
+| `thinking_type` | `{ thinking: { type: "enabled" \| "disabled" } }` | Z.AI `thinking.type`; Kimi K2.x `thinking.type` (`none` → `disabled`); DeepSeek `thinking.type` |
 | `noop` | `{}` | AI SDK / host-owned adapters — effort is host-model settings |
 
 `applyThinkingLevel` defaults `family` to `reasoning_effort` when omitted. For `openai_reasoning`, an existing `compat.reasoning.summary` (or other reasoning keys) is preserved when merging `effort`.
@@ -66,6 +66,9 @@ Core maps only shapes shared by ≥2 packages (or an explicit no-op). Unique kno
 | `@arnilo/prism-provider-kimi` | K3: `reasoning_effort`; K2.x: `thinking_type` | K2.7-code thinking is always on; do not send conflicting `thinking` + `reasoning_effort` |
 | `@arnilo/prism-provider-opencode-go` | Anthropic route: thinking blocks (`thinking_type` family); OpenAI route: `reasoning_content` preserve + optional `thinking`/`reasoning_effort`/`reasoning` passthrough | Official dual endpoints; MiniMax/Qwen → Anthropic, others → OpenAI |
 | `@arnilo/prism-provider-ai-sdk` | `noop` | Host `LanguageModelV4` owns reasoning settings |
+| `@arnilo/prism-provider-deepseek` | `thinking_type` + `reasoning_effort` | Thinking on by default (`high`). `cacheRetention: "none"` or `thinking: false` disables. Tool turns must replay `reasoning_content` or the API returns 400. |
+| `@arnilo/prism-provider-xai` | replay only | Featured Completions do not send `reasoning_effort`. Reasoning models must replay `reasoning_content` or the prefix cache breaks. Do not flatten thinking into text. |
+| `@arnilo/prism-provider-clinepass` | `reasoning_effort` | Per-model `compat.thinkingLevelMap`. GLM `xhigh` passthrough (never send `max`). K3 `high` → `max`. Unsupported slots omit the field. |
 
 `thinkingFamilyForModel` infers family from existing `compat` shape, then safe provider heuristics (`openai*` → `openai_reasoning`, `neuralwatt` → `reasoning_effort`), then `capabilities.reasoning` → `reasoning_effort`, else `noop`. Docs and packages may map other provider ids explicitly; core avoids provider-specific literals beyond those heuristics.
 
@@ -91,7 +94,7 @@ LLM compaction and observational memory accept `thinkingLevel?: string`. They ca
 
 - [Use-case model selection](use-case-model-selection.md) — session vs worker/summary model binding
 - [Provider packages](provider-packages.md) — package boundaries and discovery
-- [Provider caching](provider-caching.md) — cache retention can disable thinking on some providers (e.g. Z.AI when `cacheRetention: "none"`)
+- [Provider caching](provider-caching.md) — cache retention can disable thinking on some providers (e.g. Z.AI / DeepSeek when `cacheRetention: "none"`)
 - [Provider request policies](provider-request-policies.md) — `mergeProviderRequestOptions`
 - [Agent/session runtime](agent-session-runtime.md) — prior-reasoning preservation across turns
 - Per-provider pages under [docs/providers](providers/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -139,7 +139,9 @@
     "packages/browser",
     "packages/ag-ui",
     "packages/acp-agent",
+    "packages/computer-use-linux",
     "packages/document-reader",
+    "packages/antigravity-agent",
     "packages/prism-*"
   ],
   "scripts": {
@@ -148,7 +150,7 @@
     "build": "npm run build:core && npm run build --workspaces --if-present",
     "typecheck": "npm run build && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
     "sweep:unused": "node scripts/sweep-unused.mjs --json",
-    "test": "npm run build && node scripts/with-build-lock.mjs node --test dist/__tests__/*.test.js && node scripts/with-build-lock.mjs node --test scripts/release-gate.test.mjs scripts/tooling-gate.test.mjs scripts/budget-gate.test.mjs scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase11-freeze.test.mjs scripts/phase12-freeze.test.mjs scripts/phase13-freeze.test.mjs scripts/phase14-freeze.test.mjs scripts/phase15-freeze.test.mjs scripts/phase16-freeze.test.mjs scripts/phase17-freeze.test.mjs scripts/phase18-freeze.test.mjs scripts/phase19-freeze.test.mjs scripts/phase20-freeze.test.mjs scripts/phase21-freeze.test.mjs scripts/benchmark-0.1.0.test.mjs scripts/sweep-unused.test.mjs scripts/e2e-enterprise-journey.test.mjs scripts/e2e-coding-journey.test.mjs scripts/phase23-quality-gates.test.mjs scripts/phase24-truth.test.mjs scripts/phase25-bounded-accumulation.test.mjs scripts/phase26-freeze.test.mjs scripts/phase27-freeze.test.mjs scripts/phase27-ha.test.mjs scripts/phase27-erp-journey.test.mjs scripts/phase27-release.test.mjs scripts/phase26-index-benchmark.test.mjs && node --test scripts/phase23-build-race.test.mjs && npm run test --workspaces --if-present",
+    "test": "npm run build && node scripts/with-build-lock.mjs node --test dist/__tests__/*.test.js && node scripts/with-build-lock.mjs node --test scripts/release-gate.test.mjs scripts/tooling-gate.test.mjs scripts/budget-gate.test.mjs scripts/phase8-conformance.test.mjs scripts/phase9-conformance.test.mjs scripts/phase10-conformance.test.mjs scripts/phase11-conformance.test.mjs scripts/phase11-freeze.test.mjs scripts/phase12-freeze.test.mjs scripts/phase13-freeze.test.mjs scripts/phase14-freeze.test.mjs scripts/phase15-freeze.test.mjs scripts/phase16-freeze.test.mjs scripts/phase17-freeze.test.mjs scripts/phase18-freeze.test.mjs scripts/phase19-freeze.test.mjs scripts/phase20-freeze.test.mjs scripts/phase21-freeze.test.mjs scripts/benchmark-0.1.0.test.mjs scripts/sweep-unused.test.mjs scripts/e2e-enterprise-journey.test.mjs scripts/e2e-coding-journey.test.mjs scripts/phase23-quality-gates.test.mjs scripts/phase24-truth.test.mjs scripts/phase25-bounded-accumulation.test.mjs scripts/phase26-freeze.test.mjs scripts/phase27-freeze.test.mjs scripts/phase27-ha.test.mjs scripts/phase27-erp-journey.test.mjs scripts/phase27-release.test.mjs scripts/phase29-freeze.test.mjs scripts/phase30-freeze.test.mjs scripts/phase30-release.test.mjs scripts/phase26-index-benchmark.test.mjs && node --test scripts/phase23-build-race.test.mjs && npm run test --workspaces --if-present",
     "test:coverage": "node scripts/with-build-lock.mjs node --test --experimental-test-coverage --test-coverage-lines=60 --test-coverage-functions=70 --test-coverage-branches=75 --test-coverage-exclude='**/__tests__/**' --test-coverage-exclude='**/node_modules/**' --test-coverage-exclude='**/scripts/**' --test-coverage-exclude='**/packages/**' --test-coverage-exclude='**/examples/**' dist/__tests__/*.test.js && node scripts/with-build-lock.mjs node scripts/coverage-summary.mjs && node --test scripts/phase23-coverage.test.mjs && node --test scripts/phase23-skip-manifest.test.mjs",
     "coverage:summary": "node scripts/with-build-lock.mjs node scripts/coverage-summary.mjs",
     "lint": "biome lint . --reporter=sarif --reporter-file=scripts/lint-report.sarif",