@markusylisiurunen/tau 0.3.79 → 0.3.81

package/dist/core/static/tau_docs/credentials.md

@@ -2,7 +2,7 @@
 
 Tau can read secrets from configuration, process environments, and managed OAuth storage. The correct location depends on which process performs the authenticated operation. In a remote session, the attached terminal is usually not that process.
 
-Treat credentials separately from model definitions. [Models](models.md) describes providers, model metadata, and `models.json`; this page describes how authenticated requests obtain secrets.
+Treat credentials separately from model definitions. [Models](models.md) describes providers and model metadata; this page describes how authenticated requests obtain secrets.
 
 ## Credential ownership
 
@@ -20,13 +20,13 @@ Common cases are:
 | Fly Sprite API | Session host startup |
 | `/listen` and `/speak` | TUI client |
 | Telegram transcription and voice responses | Telegram runner |
-| `tau tool pdf-unpack`, `image-generate`, and `speech-generate` | The process running that command |
+| Standalone `tau tool` commands | The process running that command |
 
 With local `tau`, these roles normally share one machine. With `tau attach`, setting a key only in the attached client's shell does not authenticate the remote host. Run `tau auth` on the host machine and set host-owned environment variables where `tau serve` or the SDK host actually runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
 
 ## Provider API keys
 
-Tau accepts provider API keys in the effective runtime configuration:
+Tau accepts provider API keys in private global configuration:
 
 ```json
 {
@@ -38,36 +38,25 @@ Tau accepts provider API keys in the effective runtime configuration:
 }
 ```
 
-Keys are provider IDs, not model IDs. `apiKeys` merges by provider across configuration levels, so a nearer project value replaces the same provider's broader value while unrelated provider entries remain. Global and project discovery is defined in [configuration](configuration.md).
+Keys are provider IDs, not model IDs. `apiKeys` is global-only, in the owning process's `~/.config/tau/config.json`; project values are rejected. Configuration strings are literal and do not expand environment variables.
 
-Configuration files contain literal strings. Tau does not expand `$NAME` or `${NAME}` inside JSON. A key placed in `.tau/config.json` is project data and may be committed accidentally. Prefer host process environment variables or private global configuration when the credential should not live with the project.
+For model API-key authentication, provider-supported environment credentials take precedence over global `apiKeys`. Supported cloud and workload identity authentication remains available. OpenAI uses `OPENAI_API_KEY`; Anthropic also supports `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_OAUTH_TOKEN` according to its provider contract. Managed Codex OAuth is separate and always uses the explicitly active stored account.
 
-For model authentication, Tau resolves credentials in this order:
-
-1. A managed stored credential for the provider, when one exists.
-2. `apiKeys.<provider>` from the session's effective runtime configuration.
-3. The provider runtime's ambient authentication, such as its standard API-key environment variable or supported cloud credential mechanism.
-
-This means `apiKeys.openai` wins over `OPENAI_API_KEY` for model calls. If the config entry is absent, OpenAI can use `OPENAI_API_KEY`. Similar conventional variables include `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and `MISTRAL_API_KEY`. Anthropic's ambient resolution also supports bearer and OAuth token variables, with `ANTHROPIC_AUTH_TOKEN` before `ANTHROPIC_OAUTH_TOKEN` and `ANTHROPIC_API_KEY`.
-
-Other bundled providers define their own ambient authentication. A provider being present in the bundled [model catalog](models.md) does not prove that the host currently has usable credentials.
-
-Changes to `apiKeys` are picked up when an idle session runs `/reload`, or when a new session is created. Environment changes generally require restarting the owning process because an already-running process does not receive later shell exports.
+Set model credentials where the host runs. Restart the owning process after changing environment variables or its global API-key configuration.
 
 ## Feature-specific keys
 
-Several Tau features share provider credentials but intentionally prefer a fixed environment variable over configuration. Their precedence is:
+Feature helpers use environment variables first, then global configuration:
 
 | Feature | Resolution order |
 | --- | --- |
 | Exa web search and fetch | `EXA_API_KEY`, then `apiKeys.exa` |
 | Google image generation, speech-to-text, and Telegram transcription | `GEMINI_API_KEY`, then `apiKeys.google` |
 | Mistral PDF OCR | `MISTRAL_API_KEY`, then `apiKeys.mistral` |
+| OpenRouter decisions and chat | `OPENROUTER_API_KEY`, then `apiKeys.openrouter` |
 | OpenAI image generation, speech rewriting, and transcription spelling hints | `OPENAI_API_KEY`, then `apiKeys.openai` |
 | ElevenLabs speech generation, `/speak` synthesis, Telegram voice synthesis, and voice listing | `ELEVENLABS_API_KEY`, then `apiKeys.elevenlabs` |
 
-The Google, Mistral, OpenAI, and ElevenLabs rows describe feature-specific helpers. Model calls follow the general model-authentication order instead, where the configured provider key wins over ambient environment authentication.
-
 `web.discover` does not require Exa. `web.search` and `web.fetch` do. `/speak` and Telegram `/tts_on` voice responses require OpenAI for text rewriting and ElevenLabs for synthesis. `/listen` and incoming Telegram voice notes use Google, with optional OpenAI spelling hints. PDF OCR through `tau tool pdf-unpack` uses Mistral.
 
 Set these variables on the process that owns the feature. For example, a remote TUI's `/speak` reads the attached client's `OPENAI_API_KEY` and `ELEVENLABS_API_KEY`, while a Google model selected by the session reads credentials at the host.
@@ -84,35 +73,20 @@ tau auth login codex
 
 The flow opens or prints a browser URL and may fall back to a device code or pasted redirect. Tau stores the result under the host user's `~/.config/tau/auth.json` with private file permissions. Do not edit this file directly. The auth commands coordinate concurrent access, refresh tokens when needed, and preserve account state safely.
 
-Multiple Codex accounts may be present. Inspect account identities, enabled state, usage windows, and the account Tau would currently prefer without displaying tokens:
+Multiple Codex accounts may be stored, with at most one active account. `tau auth list` displays identities, marks the active account, and shows informational usage windows without revealing tokens.
 
 ```sh
+tau auth login codex
 tau auth list
-```
-
-Manage one account by the account ID or email shown in that output:
-
-```sh
-tau auth disable codex --account developer@example.com
-tau auth enable codex --account developer@example.com
+tau auth use codex --account developer@example.com
 tau auth logout codex --account developer@example.com
 ```
 
-Login adds a new account or refreshes the matching account. Disable keeps the account stored but removes it from automatic selection. Logout removes it.
-
-### Account selection and failover
-
-Without an override, Tau chooses among enabled accounts with usable quota and keeps the selected account stable for a session. If a provider error reveals that the selected account's tracked quota is exhausted, Tau clears that session selection so a later attempt can choose another usable account. Disabled accounts, accounts whose credentials cannot be refreshed, and accounts with exhausted quota are not suitable candidates.
-
-Set `TAU_CODEX_ACCOUNT` in the host process environment to force one stored account by email or account ID:
-
-```sh
-TAU_CODEX_ACCOUNT=developer@example.com tau
-```
+First login activates the account only when no accounts are stored. Later logins add or refresh an account without changing the active selection. If stored accounts remain but none is active, use `tau auth use` explicitly. Account IDs and email matching are case-insensitive.
 
-Matching is case-insensitive. A missing or disabled match fails with an explicit error. A forced account disables automatic failover, so use it when deterministic account selection matters more than continuity.
+`auth use` replaces the previous active account. Logout removes the account; logging out the active account leaves no account active even if others remain. With no active account, requests fail with instructions to log in or select one. Failed or exhausted accounts surface failures without automatic switching. Usage never determines selection.
 
-Auth storage is reloaded when credentials are resolved. Login, enable, disable, and logout therefore affect later credential resolutions without a host restart. They do not rewrite a model request already in flight. A changed `TAU_CODEX_ACCOUNT` still requires restarting the host process.
+Auth storage is reloaded for later requests across sessions. Switching accounts does not alter a request already in flight and needs no host restart.
 
 ## History and Nook indirection
 
@@ -153,31 +127,27 @@ If the named `accessClientSecretEnv` has a non-empty value, it wins over inline
 
 ## Hosted execution credentials
 
-Fly Sprite APIs are host-owned resolver configuration. They must be available when the host starts, before a client asks it to create a Sprite session. Each API requires a token:
+The Fly Sprite connection is host-owned configuration. They must be available when the host starts, before a client asks it to create a Sprite session. The connection requires a token:
 
 ```json
 {
   "flySprites": {
-    "apis": {
-      "engineering": {
-        "baseURL": "https://api.sprites.dev",
-        "tokenEnv": "FLY_SPRITES_TOKEN"
-      }
-    }
+    "baseURL": "https://api.sprites.dev",
+    "tokenEnv": "FLY_SPRITES_TOKEN"
   }
 }
 ```
 
 For Fly, inline `token` wins when present; `tokenEnv` is the fallback. Session creation fails if neither resolves.
 
-These target definitions are read from the host's startup configuration, not from an attached client. `/reload` refreshes session runtime content but does not rebuild the host's execution-environment resolvers. Restart the host after changing Sprite API definitions or their environment.
+These target definitions are read from the host's startup configuration, not from an attached client. `/reload` refreshes session runtime content but does not rebuild the host's execution-environment resolvers. Restart the host after changing Sprite connection settings or their environment.
 
 ## Safe verification
 
 Verify credentials through the operation that owns them, without printing secret values:
 
-- Run `tau auth list` to check Codex identities, enabled state, refresh health, and quota windows.
-- Run `/reload` while the session is idle after changing runtime `apiKeys`; review every configuration warning.
+- Run `tau auth list` to check Codex identities, active selection, refresh health, and informational usage windows.
+- Restart the owning process after changing global `apiKeys`.
 - Make a small request with the intended persona to verify model authentication and endpoint access.
 - Exercise the specific feature after setting Exa, speech, History, Nook or Fly credentials. Their missing-credential errors name the accepted source.
 - For remote sessions, first confirm which machine is the host and which process owns the feature.

package/dist/core/static/tau_docs/history.md

@@ -54,7 +54,7 @@ Because composite values are comma-delimited, a substring repository filter can
 
 ## Agent access is explicit and read-only
 
-An eligible persona can expose the read-only `history` code-mode tool. It searches and reads the configured history collection across repositories and execution environments. Because that collection has broad visibility, the tool description limits use to requests or active instructions that directly call for historical transcripts rather than speculative retrieval of possibly relevant earlier work.
+An eligible persona can expose the read-only `tau.history` capability in the `code` tool. It searches and reads the configured history collection across repositories and execution environments. Because that collection has broad visibility, the tool description limits use to requests or active instructions that directly call for historical transcripts rather than speculative retrieval of possibly relevant earlier work.
 
 Automatic compaction archives serve a different purpose. They capture the current session’s pre-compaction model context in the execution environment, while `history` queries a separate host-owned transcript collection that may be stale, truncated, unavailable, or remotely replicated. Compaction continuation guidance therefore directs recovery of removed current-session details to the supplied archive paths. History transcript entry ids are unrelated to archive lookup.
 
@@ -95,7 +95,7 @@ Open the configured service origin, for example `https://history.example.net/`,
 
 The index lists recently updated sessions with generated titles, summaries, timestamps, attributes, and a server-rendered search form. Repository and source inputs filter metadata by case-sensitive substring match; both filters combine with text search and remain active across pages. The Older sessions button loads the next index page; the index never advances automatically. A digest can be pending or stale while the underlying transcript is already available. Session pages initially show an empty transcript, then automatically fetch bounded batches and append them in chronological order without scrolling or pagination controls. The Copy conversation button at the top stays disabled until the full transcript has loaded. Failed loads show a retry button and keep copying disabled. The adjacent copy selector defaults to Messages only, which omits tool entries. Include tool calls adds tool names, arguments, and outcomes without results; Include everything includes results too. These options do not depend on whether tool cards are expanded. Individual entry Copy buttons still copy the complete entry. Omitting tools or results reduces noise, but does not sanitize sensitive content in messages or arguments. API reads remain paginated. Tool entries are collapsed by default. Text and metadata are escaped rather than interpreted as HTML or Markdown. Valid PNG, JPEG, GIF, and WebP content blocks render as inline images; other structured content falls back to escaped text.
 
-Remote history search and read results include a stable `webUrl` for each session. The `history` tool can return this URL when asked for a conversation link. The URL alone does not grant access; the browser still needs the viewer credential. Local-only history has no web URL.
+Remote history search and read results include a stable `webUrl` for each session. The `tau.history` capability can return this URL when asked for a conversation link. The URL alone does not grant access; the browser still needs the viewer credential. Local-only history has no web URL.
 
 ## Develop the browser view locally
 

package/dist/core/static/tau_docs/index.md

@@ -16,7 +16,7 @@ The intrinsic `tau_docs` tool reads one exact Markdown path at a time. It does n
 - [Configuration](configuration.md) explains discovery, precedence, safe edits, reload behavior, and common scope mistakes.
 - [Configuration reference](config-reference.md) defines every current top-level `config.json` field and its apply boundary.
 - [Credentials](credentials.md) covers API keys, Codex OAuth accounts, secret precedence, and credential ownership.
-- [Models](models.md) explains the model catalog and layered `models.json` overrides.
+- [Models](models.md) explains the bundled and remotely refreshed model catalog.
 - [Personas](personas.md) covers model-facing behavior, reasoning, tools, and persona files.
 - [Subagents](subagents.md) explains available subagents, launch policy, model overrides, and supervision.
 - [Skills](skills.md) covers discovery, frontmatter, trigger sensitivity, and tool eligibility.
@@ -45,3 +45,4 @@ The intrinsic `tau_docs` tool reads one exact Markdown path at a time. It does n
 - [PDF unpacking](pdf-unpacking.md) covers PDF OCR with Mistral, Markdown extraction, and page-image patches.
 - [Image generation](image-generation.md) covers image generation and reference editing with Google and OpenAI.
 - [Speech generation](speech-generation.md) covers caller-chunked narration and dialogue, ElevenLabs voices, and long-form WAV assembly.
+- [OpenRouter](openrouter.md) covers standalone typed decisions and text, image, audio, and video understanding with fixed model choices.

package/dist/core/static/tau_docs/manifest.json

@@ -15,6 +15,7 @@
     "pdf-unpacking.md",
     "image-generation.md",
     "speech-generation.md",
+    "openrouter.md",
     "client-tools.md",
     "tui.md",
     "sessions.md",

package/dist/core/static/tau_docs/models.md

@@ -2,169 +2,31 @@
 
 A model definition tells Tau how to call a provider model and how to reason about its capabilities, limits, and cost. A persona selects one provider and model, while credentials authorize the resulting request. Keeping those layers separate makes it possible to update model metadata without rewriting persona behavior.
 
-Tau ships a versioned catalog, refreshes compatible model metadata from `pi.dev`, and lets the execution environment overlay it with `models.json`. The effective catalog for a session therefore depends on the installed Tau version, the host's cached remote catalog, and the session working directory.
+Tau ships a versioned catalog and refreshes compatible model metadata from `pi.dev`. The effective catalog for a session therefore depends on the installed Tau version and the host's cached remote catalog.
 
 ## Providers, models, and personas
 
-A **provider** owns authentication and one or more request APIs. A **model** is addressed by a provider ID and an exact model ID, such as `openai/gpt-6.1-sol`. A [persona](personas.md) binds that pair to a system prompt, settings, tools, skills, and subagents.
+A **provider** owns authentication and one or more request APIs. A **model** is addressed by a provider ID and an exact model ID, such as `openai/gpt-6.1-sol`. A [persona](personas.md) binds that pair to a system prompt, settings, tools, and subagents.
 
 The bundled catalog comes from Tau's model runtime. It supplies known provider IDs, bundled model IDs, request API names, endpoints, capability flags, token limits, and pricing. Bundled does not mean currently usable: a provider may still lack credentials, an account may not expose a model, or a configured endpoint may reject it. See [credentials](credentials.md).
 
-Tau applies `models.json` overlays before resolving built-in or custom personas. A bundled persona therefore uses overridden metadata when its provider and model are patched.
-
 ## Remote catalog
 
 A model-owning Tau host restores provider catalogs from `~/.config/tau/models-store.json` during startup, then checks `pi.dev` asynchronously when the cache is older than four hours. This is a startup freshness check, not a recurring timer. Set `TAU_OFFLINE` to skip the automatic network check.
 
 Tau requests one catalog shard for every provider included in its installed `pi-ai` version. Each request has a 15-second timeout and is independent: successful shards are cached even when another provider fails, while failed providers retain their previous valid shard or fall back to bundled metadata. Run `tau models refresh` on the host to bypass the freshness window and force a best-effort refresh. The command exits nonzero if any provider fails after preserving successful updates.
 
-Remote data replaces complete matching `pi-ai` model records and may add model IDs. Execution-environment `models.json` remains the highest-precedence layer. Tau identifies the installed `pi-ai` version to `pi.dev` so the service can select compatible records. Cached data older than the catalog bundled into `pi-ai` is ignored.
+Remote data replaces complete matching `pi-ai` model records and may add model IDs. Tau identifies the installed `pi-ai` version to `pi.dev` so the service can select compatible records. Cached data older than the catalog bundled into `pi-ai` is ignored.
 
 A session captures the available remote catalog when it is created. A background refresh does not change that session. Run `/reload` to adopt the latest host cache; ordinary persona switching keeps the session's captured catalog.
 
-## Where `models.json` is loaded
-
-Tau uses the same level discovery as runtime configuration:
-
-- `~/.config/tau/models.json` is the global overlay when the session `cwd` is inside the execution environment's home.
-- Every ancestor `.tau/models.json` is a project overlay.
-- When `cwd` is inside home, project discovery stops at home. Otherwise it continues to the filesystem root.
-
-Merge order is bundled catalog, global overlay, then project overlays from the farthest parent to the nearest. The nearest value wins for the same field.
-
-These paths belong to the execution environment. In an attached session, edit `models.json` on the session target, not on the TUI machine. The general path rules and reload boundary are covered in [configuration](configuration.md).
-
-## File shape
-
-A `models.json` file has one required `providers` object. Provider keys are normalized to lowercase and must already be known to the bundled catalog.
-
-```json
-{
-  "providers": {
-    "openai": {
-      "baseUrl": "https://models.internal.example/v1",
-      "headers": {
-        "x-tenant": "payments"
-      },
-      "models": [
-        {
-          "id": "gpt-6.1-sol",
-          "contextWindow": 300000,
-          "maxTokens": 48000
-        },
-        {
-          "id": "gpt-5.7-preview",
-          "name": "GPT-5.7 preview",
-          "reasoning": true,
-          "input": ["text", "image"],
-          "contextWindow": 200000,
-          "maxTokens": 32000,
-          "cost": {
-            "input": 3,
-            "output": 18,
-            "cacheRead": 0.3,
-            "cacheWrite": 3.75
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-Unknown object fields are discarded. A malformed JSON document or invalid schema rejects that whole file and produces a configuration warning. An unknown provider produces a warning for that provider entry; Tau can still process valid entries from the same file.
-
-## Provider fields
-
-A provider entry accepts these optional defaults:
-
-| Field | Contract |
-| --- | --- |
-| `api` | Non-empty request API name. It must correspond to an API implementation available in the installed model runtime. |
-| `baseUrl` | Non-empty endpoint URL string used for provider models unless a model overrides it. |
-| `headers` | String-to-string map merged into model request headers. |
-| `compat` | Provider-specific compatibility value. Objects shallow-merge; another JSON value replaces the prior value. |
-| `models` | Array of model patches or definitions. |
-
-Provider defaults apply to every effective model for that provider. Across levels, `headers` merge by key and `compat` objects merge one level deep. Other provider fields use the nearest defined value.
-
-Headers are literal strings, not environment references. Prefer the mechanisms in [credentials](credentials.md) for secrets. If a proxy requires a routing header, keep the containing file private and remember that a project overlay may be committed.
-
-## Model fields
-
-Each model entry requires `id`. Its value is trimmed but otherwise exact and case-sensitive. All remaining fields are optional patches:
-
-| Field | Contract |
-| --- | --- |
-| `id` | Required non-empty model ID. It forms the key with the normalized provider ID. |
-| `name` | Non-empty display name. |
-| `api` | Non-empty request API name, overriding the provider or bundled value. |
-| `baseUrl` | Non-empty endpoint string, overriding the provider or bundled value. |
-| `headers` | String-to-string map. Model headers merge over provider headers by key. |
-| `reasoning` | Boolean indicating whether the model supports reasoning controls. |
-| `input` | Array containing `text`, `image`, or both. The array replaces the prior value. |
-| `contextWindow` | Positive integer context-window size in tokens. Tau uses it for context pressure and compaction decisions. |
-| `maxTokens` | Positive integer maximum output-token setting. |
-| `cost` | Partial rates object described below. Fields merge into prior cost metadata. |
-| `compat` | Provider-adapter compatibility value. Objects shallow-merge; another JSON value replaces the prior value. |
-
-A model-level value always overrides the effective provider-level value, even when the model patch came from a broader configuration level. Among model patches for the same provider and ID, the nearest level wins field by field. `headers`, object `compat`, and individual `cost` fields merge; `input` and `cost.tiers` replace their previous arrays.
-
-`compat` is intentionally adapter-specific and is not structurally validated by Tau. Use only keys understood by the selected API implementation. An accepted but unsupported `api` or `compat` value can still fail when a request is made.
-
-## Cost and tiered pricing
-
-Base cost rates are US dollars per million tokens:
-
-```json
-{
-  "cost": {
-    "input": 2,
-    "output": 12,
-    "cacheRead": 0.2,
-    "cacheWrite": 2.5
-  }
-}
-```
-
-Each base field is optional in a patch because omitted values inherit. For a newly synthesized model, inherited provider defaults remain unless replaced.
-
-`cost.tiers` is an array of complete request-wide rates. Every tier requires all five fields:
-
-```json
-{
-  "cost": {
-    "tiers": [
-      {
-        "inputTokensAbove": 272000,
-        "input": 4,
-        "output": 18,
-        "cacheRead": 0.4,
-        "cacheWrite": 5
-      }
-    ]
-  }
-}
-```
-
-Tau totals input, cache-read, and cache-write usage for the request. When that total is greater than a tier's `inputTokensAbove`, the entire request uses that tier's rates. If several thresholds match, the highest threshold wins. The threshold comparison is strict, so a total exactly equal to the threshold stays on the lower rate.
-
-Keep pricing metadata accurate. Tau uses it for displayed and recorded cost, not only documentation.
-
 ## Unbundled model IDs
 
-Custom personas and subagent launch allowlists may name an unbundled model ID when the provider is known. Tau handles it in one of two ways:
-
-1. If merged `models.json` contains the provider and ID, Tau derives a model from that provider's bundled template and applies provider and model patches.
-2. Otherwise, general model resolution synthesizes the requested ID from that provider's bundled template and applies provider-level patches.
-
-This supports newly released IDs before Tau bundles them. It does not discover capabilities or prices from the provider. The synthesized definition inherits the first bundled template for that provider, so explicitly define any differing `api`, endpoint, inputs, reasoning support, token limits, compatibility settings, and cost.
-
-A completely new provider cannot be introduced through `models.json`; provider keys must be known to the installed runtime. Also note that `modelSystemNotices` requires a **configured** model. An unbundled ID used only through synthesis must first be listed in `models.json` before a notice can target it.
+Custom personas and subagent launch allowlists may name an unbundled model ID when the provider is known. General model resolution synthesizes the requested ID from that provider's bundled template. This supports newly released IDs but does not discover their capabilities or prices. Prefer IDs present in the bundled or refreshed catalog when accurate metadata matters.
 
 ## Model system notices
 
-`modelSystemNotices` belongs in `config.json`, but its keys are validated against the merged configured model catalog, so it is closely tied to model configuration:
+`modelSystemNotices` belongs in `config.json`, but its keys are validated against the bundled and refreshed model catalog, so it is closely tied to model configuration:
 
 ```json
 {
@@ -174,7 +36,7 @@ A completely new provider cannot be introduced through `models.json`; provider k
 }
 ```
 
-Keys use exact `<provider>/<model>` form. Provider IDs must be known. Model IDs are case-sensitive and must be bundled or listed in layered `models.json`. Values must be non-empty strings. The map merges by key across configuration levels, with the nearest notice winning.
+Keys use exact `<provider>/<model>` form. Provider IDs must be known. Model IDs are case-sensitive and must be bundled or present in the refreshed catalog. Values must be non-empty strings. The map merges by key across configuration levels, with the nearest notice winning.
 
 When Tau commits input for a main agent or subagent using that model, it prepends the notice as a hidden model-facing system block. The block is persisted with the user message and later compaction sees it as source history. Tau does not add a fresh current notice to maintenance prompts or synthetic compaction messages. Ephemeral agents do not receive model system notices.
 
@@ -182,7 +44,7 @@ Use notices for model-specific operational guidance, not credentials or transien
 
 ## Applying and verifying changes
 
-Run `/reload` in an idle TUI session after changing `models.json` or `modelSystemNotices`. Reload resolves runtime content again, reapplies the active persona when its ID still exists, and reports model or configuration warnings. The TUI refuses to reload during an active turn.
+Run `/reload` in an idle TUI session after refreshing the model catalog or changing `modelSystemNotices`. Reload resolves runtime content again, reapplies the active persona when its ID still exists, and reports model or configuration warnings. The TUI refuses to reload during an active turn.
 
 For a new local session, this command verifies that the intended persona resolves to the expected provider and model ID without starting the TUI:
 
@@ -192,17 +54,4 @@ tau --debug --persona release-coder
 
 Debug output shows effective persona IDs and selected model IDs, not every model metadata field. It also prints the full effective system prompt and project context, so treat its output accordingly. A small real request is the final check for endpoint, API compatibility, model availability, and credentials.
 
-Common warnings and failures include:
-
-- invalid JSON or a missing `providers` object;
-- an unknown provider;
-- an empty model ID, API, endpoint, or name;
-- non-string headers;
-- unsupported values in `input`;
-- non-positive or non-integer token limits;
-- negative cost rates or an incomplete tier;
-- a persona that references a provider with no bundled template;
-- a notice targeting a model that was never bundled or configured; and
-- a syntactically accepted API or compatibility setting that the runtime adapter cannot use.
-
-Warnings identify the exact `models.json` or `config.json` path. In a remote session, that path is in the execution environment. See [troubleshooting](troubleshooting.md) when the edited file and the warning path do not match.
+Unknown providers, unresolved persona models, and notices targeting IDs absent from the catalog produce configuration warnings. In a remote session, warnings identify files on the session target. See [troubleshooting](troubleshooting.md).

package/dist/core/static/tau_docs/node-sdk.md

@@ -375,11 +375,13 @@ const tickets = createTauCodeModeClientTool({
 });
 ```
 
-Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, console output, the asynchronous `image(block)` output helper, live `Date` and `Math`, and agent-scoped scratch files when invoked as a client tool. API calls cross a bounded JSON bridge. The submitted code appears, concisely truncated and character-wrapped, as the running and terminal tool-card subject. The tool description remains explicit caller input; the builder is optional.
+Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, `printText`, the asynchronous `printImage` output helper, `truncate` and `truncateLines`, and live `Date` and `Math`. API calls cross a bounded JSON bridge. The submitted code appears, concisely truncated and character-wrapped, as the running and terminal tool-card subject. The tool description remains explicit caller input; the builder is optional.
 
-Use `await image({ type: "image", data, mimeType })` to forward a base64 image. Successful code-mode results contain an ordered `content` array of text/image blocks. SDK client tools preserve that order: adjacent console writes form one text block, and each awaited image separates the preceding and following text. The helper validates and prepares JPEG, PNG, or WebP images outside the sandbox, creates no files, and shares the limits described in [tools](tools.md).
+Use `await printImage({ data, mimeType })` to forward a base64 image. Successful code-mode results contain an ordered `content` array of text/image blocks. SDK client tools preserve that order: adjacent text writes form one text block, and each awaited image separates the preceding and following text. The helper validates and prepares JPEG, PNG, or WebP images outside the sandbox, creates no files, and shares the limits described in [tools](tools.md).
 
-The SDK also exports `executeTauCodeMode` for standalone execution. The separate `@markusylisiurunen/tau/code-mode` entry point additionally exports file-capability types, `runTauClientToolCommand`, and `runTauCodeModeCommand` for command-backed tools. Use the helpers instead of implementing their framing manually.
+Code-mode tool calls and standalone execution accept optional `maxOutputTokens` (1 through 65,536), with an 8,192-token default text budget. Output persistence is opt-in through the definition's `persistOutput` callback.
+
+The SDK also exports `executeTauCodeMode` for standalone execution. The separate `@markusylisiurunen/tau/code-mode` entry point additionally exports `runTauClientToolCommand`, and `runTauCodeModeCommand` for command-backed tools. Use the helpers instead of implementing their framing manually.
 
 ## Cancel and close deliberately
 

package/dist/core/static/tau_docs/nook.md

@@ -23,7 +23,7 @@ Nook crosses three Tau boundaries:
 
 - Cloudflare owns the deployed Worker, route, R2 assets, Durable Object state, DNS, and Access application.
 - The Tau CLI or session host owns Nook credentials and authenticated management HTTP.
-- A session execution environment owns any paths read or written by the `nook` agent tool.
+- A session execution environment owns any paths read or written by the `tau.nook` capability.
 
 `tau nook` CLI paths are local to the process running the command. Agent-tool paths belong to the session execution environment, even when the host is on another machine. Generated code never receives the Access secret, ambient filesystem, process environment, arbitrary network access, or `fetch`.
 
@@ -202,7 +202,7 @@ CLI and agent management operations use the Access-protected control plane rathe
 
 ## Use the host tool
 
-The assistant-facing `nook` tool appears only when both conditions hold:
+The `tau.nook` capability in the assistant-facing `code` tool is available only when both conditions hold:
 
 - the current persona selects `nook`
 - effective session configuration contains a valid `nook` block

package/dist/core/static/tau_docs/openrouter.md

@@ -0,0 +1,165 @@
+# OpenRouter
+
+`tau tool openrouter` provides standalone, single-request utilities for typed decisions and text or media understanding. They work from a shell inside or outside Tau, without a session, persona, conversation, tools, or session accounting. Only explicitly supplied content is sent to OpenRouter and its selected provider. Judgments are advisory model output, not a security or permission boundary.
+
+## Credentials and requirements
+
+Install Tau and configure `OPENROUTER_API_KEY`, or put `apiKeys.openrouter` in the global `~/.config/tau/config.json` on the machine running the command. A nonblank environment key takes precedence. Project configuration cannot supply API keys. There is no key flag.
+
+Tau's local Bash removes inherited credential-shaped environment variables. When invoking through Bash, configure the key on that machine through global configuration or its own supported environment setup. See [credentials](credentials.md) and [tools](tools.md).
+
+Audio and video require `ffprobe` from FFmpeg on `PATH`: `brew install ffmpeg` on macOS or `apt install ffmpeg` on Debian/Ubuntu. Text and images do not require FFmpeg. Media is validated locally, not transcoded.
+
+```sh
+tau tool openrouter --help
+tau tool openrouter decisions --help
+tau tool openrouter chat --help
+tau tool openrouter decisions --list-models
+tau tool openrouter chat --list-models
+```
+
+Help and model listing require neither credentials nor network access and never read stdin. `--list-models` is a separate mode, incompatible with request flags, and prints one JSON object containing `models`, with each model's `id`, `inputs`, `reasoning` settings, and `role` guidance. `--help` and `-h` print text help.
+
+## Fixed model choices
+
+An actual request requires an exact `--model` ID from this table. There is no default, arbitrary-ID escape hatch, live discovery, refresh, or automatic model substitution. A versioned ID is not necessarily an immutable provider snapshot; output records the returned model separately.
+
+| Operation | Model | Inputs and suggested role | Reasoning efforts |
+| --- | --- | --- | --- |
+| `decisions` | `typesafe/jev-1.13` | Structured state and questions; classification, scoring, verification with probabilities | Not supported |
+| `chat` | `google/gemini-3.8-flash` | Text, images, audio, video; first choice for audio/video and image-heavy analysis | `low`, `medium`, `high` |
+| `chat` | `openai/gpt-6-luna` | Text and images; cheap everyday extraction, summarization, and routine questions | `none`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `chat` | `openai/gpt-6.1-sol` | Text and images; coding, debugging, technical reasoning | `low`, `medium`, `high`, `xhigh`, `max` |
+| `chat` | `anthropic/claude-opus-5.5` | Text and images; premium generalist for writing, synthesis, difficult reasoning, and second opinions | `low`, `medium`, `high`, `xhigh`, `max` |
+
+Roles are selection guidance, not benchmark guarantees or restrictions on tasks. Unsupported settings and modalities fail locally rather than switching models, transcribing audio, or extracting video frames.
+
+## Input and examples
+
+### Decisions
+
+```sh
+tau tool openrouter decisions --model typesafe/jev-1.13 --input ./decision.json
+```
+
+`--input` is required. A file path reads a UTF-8 JSON document. Exactly `--input -` reads one complete document from stdin until EOF:
+
+```sh
+tau tool openrouter decisions --model typesafe/jev-1.13 --input - <<'JSON'
+{
+  "state": { "ticket": "The checkout page crashes when I click Pay." },
+  "questions": {
+    "is_bug": {
+      "type": "noul",
+      "instructions": "Does this report describe broken product behavior?"
+    },
+    "team": {
+      "type": "choice",
+      "instructions": "Which team should own this ticket?",
+      "criteria": {
+        "payments": "Checkout or billing problems",
+        "other": "Problems unrelated to payments"
+      }
+    },
+    "urgency": {
+      "type": "score",
+      "instructions": "How urgent is the issue?",
+      "criteria": ["Can wait", "Fix soon", "Blocking revenue"]
+    }
+  }
+}
+JSON
+```
+
+Stdin must not be a terminal and must reach EOF within 30 seconds. Empty input, malformed JSON, multiple documents, invalid UTF-8, and oversized input fail before any request.
+
+The input contains exactly `state` and `questions`. The model belongs only in `--model`, not the document. `state` is a string, JSON object, or array. `questions` is a nonempty map of nonempty names to questions:
+
+- `noul`: required `instructions`; optional `criteria` with both `true` and `false`. The answer's `noul` is a probability from zero to one, not a boolean.
+- `choice`: required `instructions` and a nonempty `criteria` object mapping category names to guidance. The answer's `choice` names a supplied category; optional `probabilities` and `confidence` retain provider probabilities.
+- `score`: required `instructions` and a nonempty ordered `criteria` array. The answer's `score` is a numeric position from zero to the last rubric index, possibly fractional. Optional `legend`, `probabilities`, and `confidence` retain distribution details.
+
+Instructions and criterion guidance accept strings, JSON objects, or arrays; choice criterion values may also be `null`. Unknown question fields and the reserved question/category name `__proto__` are rejected. Arbitrary keys within state and guidance are preserved. Several independent questions can share one state; dependent questions require separate calls.
+
+The command posts once to OpenRouter's alpha Decisions endpoint. It validates answer names, types, categories, rubric ranges, and probability bounds. Successful output is one JSON object:
+
+```json
+{
+  "requested_model": "typesafe/jev-1.13",
+  "model": "typesafe/jev-1.13-20260917",
+  "answers": { "is_bug": { "type": "noul", "noul": 0.96 } },
+  "usage": { "input_tokens": 100, "output_tokens": 10, "cost": 0.00001 }
+}
+```
+
+This illustrates a single-question response; every submitted question must have an answer. Provider `id` and `provider` are included when supplied. Usage contains reported token counts and optional reported cost, never an estimated cost. Negative judgments and low confidence still exit successfully. No thresholds or prose explanations are invented.
+
+### Chat
+
+```sh
+tau tool openrouter chat \
+  --model openai/gpt-6.1-sol \
+  --system 'Review carefully. Separate observations from assumptions.' \
+  --prompt-file ./review-context.txt \
+  --image ./error.png \
+  --reasoning high
+```
+
+Flags belong after `chat`. No positional arguments are accepted.
+
+| Flag | Contract |
+| --- | --- |
+| `--model <id>` | Required exact shipped chat model ID |
+| `--prompt <text>` or `--prompt-file <path>` | Exactly one required; nonblank UTF-8 user prompt |
+| `--system <text>` or `--system-file <path>` | Optional, mutually exclusive, nonblank explicit system instructions |
+| `--image <path>` | Repeatable local PNG, JPEG, or WebP image |
+| `--audio <path>` | Repeatable local WAV or MP3 audio; Gemini only |
+| `--video <path>` | Local MP4 video; Gemini only |
+| `--reasoning <effort>` | Optional model-supported effort from the table |
+
+All file paths resolve relative to the invoking working directory. Prompt/system files name regular files; `-` has special stdin meaning only for decisions. Omitting system instructions sends no system message. Omitting reasoning leaves that parameter to the provider, not necessarily disabled. Effort does not request a written reasoning trace.
+
+Media flags may be mixed; the request contains the prompt first, followed by attachments in command-line order. Files are embedded inline as data URLs or base64 audio, not uploaded to public hosting. There are no remote URL inputs, generated media, automatic resizing, clipping, conversion, chunking, conversation history, or tool execution.
+
+```sh
+tau tool openrouter chat \
+  --model google/gemini-3.8-flash \
+  --prompt 'Compare this recording with the reference and spoken requirements.' \
+  --video ./recording.mp4 \
+  --image ./reference.png \
+  --audio ./requirements.wav > ./analysis.json
+```
+
+Chat sends one non-streaming completion request. It imposes no output token cap: neither `max_tokens` nor `max_completion_tokens` is sent, and there is no `--max-tokens` flag. Provider defaults, remaining context, and model limits still apply; omission does not mean unlimited output.
+
+Successful stdout contains one JSON object with `requested_model`, returned `model`, `answer` (text or `null`), and `finish_reason`. Reported `id`, `provider`, `usage` (including cost and token details), `native_finish_reason`, and `refusal` appear when supplied. Missing optional metadata is not fabricated. Reasoning is never substituted for the answer or returned as answer text.
+
+- `stop` with no refusal is a complete answer.
+- `length` is truncated output, even if answer text is empty.
+- `content_filter` or a nonempty `refusal` indicates refusal, not a complete answer.
+
+These are successful exchanges with distinguishable outcomes; scripts must inspect them. Provider errors, malformed responses, unexpected tool calls, and a normal stop with neither answer nor refusal fail instead of masquerading as an answer.
+
+## Outputs and recovery
+
+These are conservative utility safety limits, not promises of every provider's maximum capacity. All byte limits use decimal bytes.
+
+| Resource | Limit |
+| --- | --- |
+| Decisions JSON, each prompt or system input | 1,000,000 UTF-8 bytes |
+| Attachments per request | 16 total, including at most 4 audio files and 1 video |
+| Each image | 5,000,000 bytes, 8,000 pixels per edge, 32 megapixels; one frame |
+| Each audio or video | 12,000,000 bytes |
+| Audio formats | Single-stream PCM 16-bit little-endian WAV or MP3 |
+| Video format | H.264 MP4 up to 3840×2160 with optional AAC audio |
+| Audio/video duration | Known positive duration; 600 seconds combined |
+| Complete encoded JSON request | 20,000,000 bytes, including base64 expansion and text |
+| Response | 8,000,000 bytes |
+| Local media probe | 15 seconds per file |
+| HTTP request and response | 10 minutes |
+
+Oversized or unsupported inputs fail before sending. Audio/video validation uses private temporary copies of the exact bytes being submitted and removes those copies after probing. Keep FFmpeg current when handling untrusted media.
+
+Diagnostics go to stderr and failures exit nonzero. Authentication, insufficient credits, permission failures, rate limits, and provider/service failures report distinct status diagnostics without dumping provider bodies. There are no automatic retries, including after timeouts or interrupted connections: the provider may already have charged for an unknown outcome. A response exceeding the safety bound can fail after a billable request.
+
+No paid inference compatibility guarantee follows from local validation. OpenRouter's alpha Decisions contract and provider availability can change independently of Tau. Review the actual output and current service errors rather than treating model judgments as verified facts.