@arnilo/prism 0.0.5 → 0.0.6

package/docs/providers/kimi.md

@@ -2,132 +2,195 @@
 
 ## What it does
 
-`@arnilo/prism-provider-kimi` provides explicit, side-effect-free setup for Kimi For
-Coding using an Anthropic-compatible `/messages` endpoint with
-`User-Agent: KimiCLI/1.5` (unless overridden). Moonshot/Open Platform model
-metadata is optional.
+`@arnilo/prism-provider-kimi` provides two distinct, side-effect-free routes:
 
-The package registers the `kimi-coding` provider, default Kimi Coding model
-metadata, and an `api_key` auth method through `createExtensionKernel().load([...])`.
+1. **Kimi For Coding** (default) — Anthropic-compatible `POST /messages` on
+   `https://api.kimi.com/coding` with `User-Agent: KimiCLI/1.5` (unless overridden).
+2. **Moonshot Open Platform** (opt-in) — OpenAI-compatible `POST /chat/completions`
+   on `https://api.moonshot.ai/v1` (or `api.moonshot.cn/v1`), registered only when
+   `includeMoonshotModels: true`.
+
+Official model ids differ by route. Coding uses `kimi-for-coding`,
+`kimi-for-coding-highspeed`, and `k3`. Open Platform uses `kimi-k2.7-code`,
+`kimi-k3`, and related catalog ids. Pi's `k2p7` alias is **not** used.
+
+Caller-gated discovery via `listKimiModels()` hits the official Moonshot
+`GET /v1/models` endpoint. Package setup never fetches.
 
 ## When to use it
 
-Use it when a host app wants the Kimi For Coding endpoint through Prism's
-`AgentSession` runtime with Kimi-specific serializer behavior.
+Use it when a host app wants Kimi For Coding and/or Moonshot Open Platform through
+Prism's `AgentSession` runtime with Kimi-specific serializers, thinking controls,
+and cache policy.
 
-Do not use it for Moonshot Open Platform default registration, automatic
-credential discovery, catalog fetches, or real-network tests.
+Do not use it for automatic credential discovery, setup-time catalog fetches, or
+real-network tests (live tests stay opt-in).
 
 ## Inputs / request
 
 ```ts
-import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+import {
+  createKimiProviderPackage,
+  listKimiModels,
+  defineKimiModel,
+} from "@arnilo/prism-provider-kimi";
 
 createKimiProviderPackage(options: KimiProviderPackageOptions): ProviderPackage
-defineKimiModel(config: KimiModelConfig): KimiModelConfig
+listKimiModels(options?: ListKimiModelsOptions): Promise<ModelConfig[]>
+defineKimiModel(config: KimiModelConfig): ModelConfig
 ```
 
 | Field | Type | Purpose |
 | --- | --- | --- |
-| `kimiApiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source for Kimi. |
+| `kimiApiKey` | `CredentialValueSource` | Kimi For Coding API key. |
+| `moonshotApiKey` | `CredentialValueSource` | Moonshot Open Platform API key (not interchangeable with Coding keys). |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
-| `baseUrl` | `string` | Overrides the Kimi base URL. |
-| `id` | `string` | Overrides the provider id (default `kimi-coding`). |
-| `userAgent` | `string` | Overrides `User-Agent: KimiCLI/1.5`. |
-| `models` | `readonly ModelConfig[]` | Overrides `kimiCodingModels` defaults. |
-| `includeMoonshotModels` | `boolean` | Registers Moonshot models when `true` (default off). |
-| `moonshotModels` | `readonly ModelConfig[]` | Overrides `moonshotKimiModels` when included. |
+| `baseUrl` | `string` | Overrides the Coding base URL. |
+| `moonshotBaseUrl` | `string` | Overrides Moonshot base URL (default `https://api.moonshot.ai/v1`). |
+| `id` / `moonshotId` | `string` | Provider ids (defaults `kimi-coding` / `moonshot`). |
+| `userAgent` | `string` | Overrides Coding `User-Agent: KimiCLI/1.5`. |
+| `models` | `readonly ModelConfig[]` | Overrides featured Coding models. |
+| `includeMoonshotModels` | `boolean` | Registers callable Moonshot provider + models when `true`. |
+| `moonshotModels` | `readonly ModelConfig[]` | Overrides featured Moonshot models when included. |
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
-| Provider stream | Prism text, thinking (preserved only when `model.compat.preserveThinking` is true, otherwise downgraded to text), tool-call delta/final, `usage`, `done`, redacted `error`. |
-| Block preservation | Text, thinking, assistant `tool_call` → `tool_use`, `tool_result` → `tool_result`, images when `capabilities.input` includes `"image"`. |
-| Auth method | `api_key` for `kimi-coding`, credential name `apiKey`. |
+| Coding stream | Prism text, thinking deltas, tool-call delta/final, `usage` (`cache_read_input_tokens` / `cache_creation_input_tokens`), `done`, redacted `error`. |
+| Moonshot stream | Same, with `delta.reasoning_content` → thinking; OpenAI-style usage cache details when present. |
+| Block preservation | Coding: Anthropic `thinking` / `tool_use` / `tool_result`. Moonshot: `reasoning_content` on assistant replay when `preserveThinking`. |
+| Auth methods | `api_key` for `kimi-coding`; also `moonshot` when opted in. |
 
 Unsupported block placements or unclaimed images fail before fetch.
 
+## Route differences
+
+| | Kimi For Coding | Moonshot Open Platform |
+| --- | --- | --- |
+| Base URL | `https://api.kimi.com/coding` | `https://api.moonshot.ai/v1` (or `.cn`) |
+| Wire API | Anthropic `/messages` | OpenAI `/chat/completions` |
+| Featured ids | `kimi-for-coding`, `kimi-for-coding-highspeed`, `k3` | `kimi-k2.7-code`, `kimi-k3` (+ discovery) |
+| Discovery | No public list API — curated featured aliases | Official `GET /v1/models` via `listKimiModels()` |
+| Cache | Implicit by default; opt-in Anthropic `cache_control` | Implicit only — never emits Anthropic `cache_control` |
+| Thinking | Block replay + body `thinking` / `reasoning_effort` | `reasoning_content` replay + body `thinking` / `reasoning_effort` |
+
+The Anthropic `/messages` request/response contract for Kimi remains under-documented
+upstream ([MoonshotAI/Kimi-K2#129](https://github.com/MoonshotAI/Kimi-K2/issues/129));
+Prism treats official Chat Completions thinking fields as best-effort passthrough on
+the Coding route.
+
+## Thinking / reasoning
+
+Official fields (Open Platform docs; Coding docs for `k3` effort mapping):
+
+| Model family | Official control | Prism `compat` |
+| --- | --- | --- |
+| K3 / Coding `k3` | top-level `reasoning_effort` (`max` on Open Platform; Coding also `low`/`high`) | `compat.reasoning_effort` — use Task 4 family `reasoning_effort` |
+| K2.7-code / Coding | thinking always on; Preserved Thinking always on | omit `thinking` by default; `preserveThinking: true` for replay; do not send `disabled` |
+| K2.6 / K2.5 | `thinking.type` enabled/disabled; K2.6 optional `keep: "all"` | `compat.thinking` — Task 4 family `thinking_type` |
+
+Per-turn `ProviderRequestOptions.compat` wins over `ModelConfig.compat`. Helpers:
+`kimiThinking`, `kimiReasoningEffort`, `kimiPreserveThinking`.
+
 ## Request/response example
 
-Example request (Anthropic-compatible `/messages` shape):
+Coding (Anthropic-compatible `/messages`):
 
 ```json
 {
-  "model": "kimi-latest",
-  "messages": [{ "role": "user", "content": "Hello" }],
+  "model": "kimi-for-coding",
+  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "Hello" }] }],
   "stream": true
 }
 ```
 
+Moonshot (Chat Completions):
+
+```json
+{
+  "model": "kimi-k3",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true,
+  "reasoning_effort": "max"
+}
+```
+
 ## Implementation example
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+import {
+  createKimiProviderPackage,
+  listKimiModels,
+} from "@arnilo/prism-provider-kimi";
 
 const kernel = createExtensionKernel();
 await kernel.load([
-  createKimiProviderPackage({ kimiApiKey: "fake-kimi-key", includeMoonshotModels: false }),
+  createKimiProviderPackage({ kimiApiKey: "fake-kimi-key" }),
 ]);
-```
-
-Register Moonshot/Open Platform metadata explicitly:
 
-```ts
-import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+// Opt-in Moonshot Open Platform (callable provider + featured models)
+await kernel.load([
+  createKimiProviderPackage({
+    kimiApiKey: "fake-kimi-key",
+    includeMoonshotModels: true,
+    moonshotApiKey: "fake-moonshot-key",
+  }),
+]);
 
+// Caller-gated discovery — never runs during setup
+const latest = await listKimiModels({ apiKey: "fake-moonshot-key", fetch });
 await kernel.load([
-  createKimiProviderPackage({ kimiApiKey: "fake", includeMoonshotModels: true }),
+  createKimiProviderPackage({
+    includeMoonshotModels: true,
+    moonshotApiKey: "fake-moonshot-key",
+    moonshotModels: latest.filter((m) => m.model.startsWith("kimi-")),
+  }),
 ]);
 ```
 
 ## Extension and configuration notes
 
-- Hosts choose base URL, provider id, `User-Agent`, model list, credential source,
+- Hosts choose base URLs, provider ids, `User-Agent`, model lists, credential sources,
   and `fetch` impl.
-- Moonshot/Open Platform metadata is registered only with
-  `includeMoonshotModels: true`; it is not core behavior.
-- Package contributes models via the extension `api` and an `api_key` auth method.
+- Moonshot is registered only with `includeMoonshotModels: true` (provider + models + auth).
+- Featured catalogs are offline bootstrap only; refresh Open Platform via `listKimiModels()`.
 
 ### Cache behavior
 
-- Default catalog models (e.g. `kimi-k2.7-code` on the Anthropic-compatible
-  `/messages` route) use **implicit caching** and send no explicit `cache_control`
-  fields. `ProviderRequestOptions.cache` / `cacheKey` / `cacheRetention` have no
-  effect on the request body unless the model opts in.
-- Hosts may opt a model into Anthropic-style `cache_control` by declaring
-  `ModelConfig.cache.kind: "cache_control"` on the Anthropic route. When opted in,
-  `cache_control: { type: "ephemeral" }` markers are applied only to the
-  caller-selected `ProviderRequestOptions.cache.breakpoints` (resolved with the
-  shared `applyCacheControl()` helper) on the last content block of each selected
-  message — not to every block. `cacheRetention: "long"` adds `ttl: "1h"` when the
-  model allows long retention (`ModelConfig.cache.longRetention !== false`).
-- The Moonshot Open Platform route (`compat.route: "openai"`) never receives
-  Anthropic `cache_control` fields.
-- Usage accounting is preserved: Anthropic-route `cache_read_input_tokens` maps to
-  `Usage.cacheReadTokens` and `cache_creation_input_tokens` maps to
-  `Usage.cacheWriteTokens`.
+- Default Coding catalog models use **implicit caching** and send no explicit
+  `cache_control` fields unless the model opts in with
+  `ModelConfig.cache.kind: "cache_control"`.
+- When opted in, `cache_control: { type: "ephemeral" }` markers apply only to
+  caller-selected `ProviderRequestOptions.cache.breakpoints` on the last content
+  block of each selected message. `cacheRetention: "long"` adds `ttl: "1h"` when
+  the model allows long retention.
+- The Moonshot Open Platform route never receives Anthropic `cache_control` fields.
+- Coding usage: `cache_read_input_tokens` → `Usage.cacheReadTokens`,
+  `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
 
 ## Security and performance notes
 
-- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
 - No network calls during import, setup, build, or default tests.
 - No automatic environment, file, keychain, or shell credential lookup.
-- Kimi credentials are resolved per request from caller-supplied values or resolvers
-  and redacted from errors.
+- Credentials are resolved per request from caller-supplied values or resolvers
+  and redacted from errors (including discovery failures).
 - Caller-supplied `ProviderRequest.options.headers` can add non-owned headers,
   but provider-owned headers (`content-type`, `user-agent`, `authorization`)
   are applied last and cannot be overridden by caller headers.
-- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
-  provider-specific env names; default tests are network-free.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus provider-specific
+  env names; default tests are network-free.
 
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
-  `ModelConfig`/`compat`, Anthropic-compatible routes.
+  caller-gated discovery, Anthropic/OpenAI routes.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable `ThinkingLevel`
+  helpers and Kimi family mapping.
 - [Credentials and redaction](../credentials-and-redaction.md):
   `resolveCredentialValue`, `redactSecrets`.
-- [Provider layer](../provider-layer.md): `ProviderRequest.options` and usage
-  mapping.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix.
 - [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/neuralwatt.md

@@ -9,7 +9,7 @@ and implicit prefix caching.
 
 The package registers a provider, default model metadata for the featured NeuralWatt
 aliases (`glm-5.2`, `glm-5.2-fast`, `glm-5.2-short`, `glm-5.2-short-fast`,
-`kimi-k2.6`, `kimi-k2.6-fast`, `kimi-k2.7-code`, `qwen3.5-397b`,
+`gemma-4-31b`, `kimi-k2.6`, `kimi-k2.6-fast`, `kimi-k2.7-code`, `qwen3.5-397b`,
 `qwen3.5-397b-fast`, `qwen3.6-35b`, `qwen3.6-35b-fast`), and an `api_key` auth
 method through `createExtensionKernel().load([...])`.
 
@@ -79,13 +79,15 @@ The endpoint is rate-limited to **1 request per second per customer** (429 with
 from `generate()` or package setup; the caller owns throttling.
 
 NeuralWatt-specific request fields flow through the generic `ProviderRequestOptions.compat`
-/ `extra` escape hatches: `compat.reasoning_effort` (`"low" | "medium" | "high"`),
-`compat.thinking_token_budget`, `compat.chat_template_kwargs` (including `enable_thinking`),
-`compat.preserve_thinking`, `compat.clear_thinking`, and `compat.tool_choice`.
-`preserve_thinking: true` keeps prior assistant reasoning in request history so
-multi-turn reasoning continues with the earlier chain of thought; `clear_thinking:
-true` drops it for the next turn, resetting the chain. `options.extra` spreads after
-`compat` so per-call values and overrides win.
+/ `extra` escape hatches: `compat.reasoning_effort` (OpenAI-style scale; GLM-5.2 defaults
+unset to `max` per official docs), `compat.thinking_token_budget`,
+`compat.chat_template_kwargs` (including `enable_thinking`, `preserve_thinking`, and
+`clear_thinking` per official gateway docs), and `compat.tool_choice`.
+`preserve_thinking` / `clear_thinking` compat flags are routed into `chat_template_kwargs`
+on the wire (not top-level body fields). Prism also uses these flags for client-side
+message serialization: `preserve_thinking: true` keeps prior assistant reasoning in
+request history; `clear_thinking: true` drops it for the next turn. `options.extra` spreads
+after resolved fields so per-call values and overrides win.
 
 ## Outputs / response / events
 
@@ -112,7 +114,7 @@ Example request body (OpenAI-compatible Chat Completions shape):
   "messages": [{ "role": "user", "content": "Hello" }],
   "stream": true,
   "stream_options": { "include_usage": true },
-  "reasoning_effort": "medium",
+  "reasoning_effort": "max",
   "thinking_token_budget": 8192
 }
 ```
@@ -192,6 +194,7 @@ validation. The caller owns throttling/caching — the helper makes one explicit
 | `glm-5.2-fast` | 1024K | Tools, fast/no reasoning |
 | `glm-5.2-short` | 195K | Tools, reasoning |
 | `glm-5.2-short-fast` | 195K | Tools, fast/no reasoning |
+| `gemma-4-31b` | 256K | Tools, vision, JSON mode |
 | `kimi-k2.6` | 256K | Tools, reasoning, vision, JSON mode |
 | `kimi-k2.6-fast` | 256K | Tools, vision, JSON mode, fast/no reasoning |
 | `kimi-k2.7-code` | 256K | Tools, reasoning, vision, JSON mode |
@@ -255,15 +258,18 @@ so multi-turn sessions continue the earlier chain of thought:
 
 - Prior `thinking` content blocks on an assistant message are serialized under a
   `reasoning_content` field on that message (matching the streaming
-  `delta.reasoning_content` field). They are **not** flattened into text `content`, so
+  `delta.reasoning_content` field; the gateway also accepts `reasoning` as an alias).
+  They are **not** flattened into text `content`, so
   the model sees reasoning and answer as distinct.
 - Preservation is gated on `model.capabilities.reasoning === true` **or**
   `compat.preserve_thinking: true`. Non-reasoning models receive no `reasoning_content`
   field and prior `thinking` blocks are dropped — they never leak into text content for
   providers/models that do not support reasoning.
-- `compat.clear_thinking: true` drops prior reasoning for the next turn even on
-  reasoning-capable models, resetting the chain of thought. `clear_thinking` takes
-  precedence over `preserve_thinking`.
+- `compat.preserve_thinking` / `compat.clear_thinking` map into `chat_template_kwargs`
+  on the request body per official NeuralWatt docs (Kimi K2.6 `preserve_thinking`, GLM
+  `clear_thinking: false` for full-history). Prism also uses `clear_thinking: true` to
+  drop prior reasoning client-side even on reasoning-capable models; `clear_thinking`
+  takes precedence over `preserve_thinking`.
 - The provider only echoes caller-provided `thinking` blocks; it never synthesizes new
   reasoning.
 

package/docs/providers/openai.md

@@ -36,16 +36,22 @@ createOpenAIProviderPackage(options: OpenAIProviderPackageOptions): ProviderPack
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
 | `baseUrl` | `string` | Overrides `https://api.openai.com/v1`. |
 | `codexBaseUrl` | `string` | Overrides `https://chatgpt.com/backend-api/codex`. |
+| `models` | `readonly ModelConfig[]` | Optional override for registered OpenAI Responses models (defaults to featured `openAIModels`). |
+| `codexModels` | `readonly ModelConfig[]` | Optional override for registered Codex models (defaults to featured `openAICodexModels`). |
 
 `ProviderRequest.options.sessionId`, `cacheKey`, `cacheRetention`, `headers`,
-`compat`, and `extra` map to request headers/payload fields.
+`compat`, and `extra` map to request headers/payload fields. Per-turn reasoning
+uses official Responses `reasoning: { effort, summary? }` via
+`ModelConfig.compat.reasoning` defaults merged with
+`ProviderRequestOptions.compat.reasoning` (request wins). Prefer
+`applyThinkingLevel(..., "openai_reasoning")` from `@arnilo/prism`.
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
 | Provider stream | Prism text, thinking (downgraded to text), `tool_call` deltas/finals, `usage`, `done`, redacted `error` events. |
-| Block preservation | Text, thinking (downgraded), assistant `tool_call` → `function_call` input items, `tool_result` → `function_call_output` input items, images when `capabilities.input` includes `"image"`. |
+| Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant `tool_call` → top-level `function_call` with `call_id`; `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`; `oauth` for `openai-codex`. |
 
 Unsupported block placements or unclaimed images fail before `fetch`.
@@ -56,10 +62,17 @@ Responses request body (Codex subscription shape, abbreviated):
 
 ```json
 {
-  "model": "gpt-5-codex",
-  "instructions": "You are a coding agent.",
-  "input": [{ "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Hello" }] }],
-  "stream": true
+  "model": "gpt-5.1",
+  "input": [
+    { "role": "user", "content": [{ "type": "input_text", "text": "Hello" }] },
+    { "role": "assistant", "content": [{ "type": "output_text", "text": "Calling lookup" }] },
+    { "type": "function_call", "call_id": "call_1", "name": "lookup", "arguments": "{\"q\":\"x\"}" },
+    { "type": "function_call_output", "call_id": "call_1", "output": "{\"ok\":true}" }
+  ],
+  "reasoning": { "effort": "high" },
+  "prompt_cache_key": "session-1",
+  "stream": true,
+  "store": false
 }
 ```
 
@@ -73,13 +86,13 @@ https://auth.openai.com/authorize?response_type=code&client_id=...&code_challeng
 
 ```ts
 import { createExtensionKernel, createEnvCredentialResolver } from "@arnilo/prism";
-import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+import { createOpenAIProviderPackage, listOpenAIModels } from "@arnilo/prism-provider-openai";
 
+const apiKey = createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" });
+const models = await listOpenAIModels({ apiKey }); // caller-gated; never runs during setup
 const kernel = createExtensionKernel();
 await kernel.load([
-  createOpenAIProviderPackage({
-    apiKey: createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" }),
-  }),
+  createOpenAIProviderPackage({ apiKey, models }),
 ]);
 ```
 
@@ -115,25 +128,55 @@ const challenge = computeS256Challenge(verifier);
 
 ### Cache behavior
 
+Official: [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).
+
 - `prompt_cache_key` is derived from `ProviderRequestOptions.cacheKey` (falling
   back to `sessionId`) and sanitized + clamped to 64 characters via the shared
   `sanitizeCacheKey()` helper. Cache keys are session/customer identifiers only;
   never credentials or raw prompts.
-- `prompt_cache_retention` accepts only `"24h"` on the OpenAI Responses API
+- `prompt_cache_retention` accepts only `"24h"` on pre-GPT-5.6 Responses models
   (extended caching). Prism `cacheRetention: "short"` and `"none"` omit the field
   so default automatic/implicit caching applies and no invalid literal is sent.
   `cacheRetention: "long"` maps to `prompt_cache_retention: "24h"` only when the
   model declares `ModelConfig.cache.longRetention === true`; models without that
-  metadata omit the field. The catalog `gpt-5.1` model declares
+  metadata omit the field. Featured `gpt-5.1` declares
   `cache: { kind: "openai_key", longRetention: true, maxKeyLength: 64 }`.
+- GPT-5.6+ official docs prefer `prompt_cache_options` / explicit breakpoints;
+  `listOpenAIModels` sets `longRetention: false` for those ids so Prism does not
+  emit deprecated `prompt_cache_retention` for them. Breakpoint helpers are not
+  shipped in this package yet — hosts may pass `prompt_cache_options` through
+  `compat` / `extra` when needed.
 - Cache accounting is preserved in normalized `Usage`: OpenAI
   `input_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`. OpenAI
-  Responses does not report a cache-write token field.
+  Responses does not report a cache-write token field on older models.
 - Provider-owned headers (`content-type`, `authorization`, `x-client-request-id`)
   are applied after caller `ProviderRequestOptions.headers` so caller config
   cannot replace credentials, content type, or the session request id; non-owned
   caller headers are kept.
 
+### Model discovery
+
+- `listOpenAIModels({ apiKey, fetch, baseUrl, signal, headers })` calls official
+  [`GET /models`](https://developers.openai.com/api/reference/resources/models/methods/list)
+  and maps sparse `{ id, created, owned_by }` entries to `ModelConfig` with
+  `cache.kind: "openai_key"` and heuristic `longRetention` / `capabilities.reasoning`.
+- `createOpenAIProviderPackage` never calls discovery; pass results via `models:`.
+- Codex subscription models are **not** listed by `api.openai.com` — keep using
+  featured `openAICodexModels` or `codexModels:` override.
+- Static `openAIModels` / `openAICodexModels` are offline bootstrap / featured aliases only.
+
+### Reasoning
+
+Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reasoning).
+
+- Body field is top-level `reasoning: { effort, summary?, mode?, context? }`.
+- Model defaults: `ModelConfig.compat.reasoning`; per-turn override:
+  `ProviderRequestOptions.compat.reasoning` (shallow-merged; request wins).
+- Portable helper: `applyThinkingLevel(options, level, "openai_reasoning")`.
+- Streaming tool args follow official
+  `response.output_item.added` + `response.function_call_arguments.delta`
+  (string `delta`), not Chat Completions object deltas.
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).