@markusylisiurunen/tau 0.3.78 → 0.3.80

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

@@ -345,7 +345,7 @@ The handler receives `sessionId`, owning `agentId`, `callId`, an `AbortSignal`,
 
 `describe` is optional. When present, the SDK calls it with the arguments and a reduced context containing `sessionId`, `agentId`, `callId`, and `signal` before acknowledgement. This context deliberately has no execution-environment facade. It may return a partial running presentation containing `subject`, `subjectWrap`, `details`, or `metadata`. Tau owns action and operation, fills every omitted field, and acknowledges the resolved presentation before calling `execute`.
 
-The execution result may independently include the same partial shape for the terminal card. Return a string or `{ content, presentation? }` for success, or `{ ok: false, error, presentation? }` for a structured failure. Omitted presentation fields use Tau's terminal defaults; empty detail or metadata arrays suppress those defaults. If `describe` throws, the SDK reports a preparation error without calling `execute`. If the client never returns a result because of cancellation, timeout, detach, or another failure, the host produces a complete fallback presentation.
+The execution result may independently include the same partial shape for the terminal card. Return a string or `{ content, presentation? }` for success, or `{ ok: false, error, presentation? }` for a structured failure. Successful `content` may be a string or an ordered array of text/image blocks. Strings are delivered as one text block. Omitted presentation fields use Tau's terminal defaults; empty detail or metadata arrays suppress those defaults. If `describe` throws, the SDK reports a preparation error without calling `execute`. If the client never returns a result because of cancellation, timeout, detach, or another failure, the host produces a complete fallback presentation.
 
 Tau preserves every explicit presentation field up to the protocol safety limits; it does not apply display truncation or normalize client text. `truncateTauClientToolText` provides optional caller-controlled line, character, and head or middle truncation. Use its result directly for a subject. For a block of detail text, split the result on `\n` and map each line to one `details` entry; use `maxLines: 1` when assigning it directly to one detail or metadata entry. The helper shapes text but does not replace protocol validation. The SDK aborts handlers on host cancellation, client close, or terminal transport failure. `client.close()` waits for active handlers to settle.
 
@@ -375,7 +375,9 @@ const tickets = createTauCodeModeClientTool({
 });
 ```
 
-Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, console output, 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`, 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.
+
+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).
 
 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.
 

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.

package/dist/core/static/tau_docs/ownership-and-scope.md

@@ -16,11 +16,13 @@ The **host** creates, observes, persists, and recovers sessions. It owns model c
 
 The host's home owns data such as session snapshots, authentication storage, usage logs, and the local history database. Use Tau commands and session operations to manage these stores rather than editing their files directly.
 
+MCP connections are host-owned. Configure servers on the host; stdio servers run there, with host credentials and host resource access, not in the session execution environment.
+
 The intrinsic `tau_docs` tool is also host-owned. It reads documentation packaged with the installed host version.
 
 ### Execution environment
 
-The **execution environment** is the machine the agent can act on. It owns the agent-visible working directory (`cwd`), home, platform, environment, filesystem, processes, project repository, project configuration and content, `AGENTS.md` files, model overlays, skills, and command resolution.
+The **execution environment** is the machine the agent can act on. It owns the agent-visible working directory (`cwd`), home, platform, environment, filesystem, processes, project repository, project configuration and content, `AGENTS.md` files, skills, and command resolution.
 
 Tau asks the execution environment to read or execute against those resources. The host must not treat its own filesystem as a shortcut, even when a local execution environment happens to share it.
 
@@ -50,9 +52,9 @@ A Fly Sprite can place the execution environment on another target while the hos
 | Resource or behavior | Canonical owner | Consequence |
 | --- | --- | --- |
 | Agent `cwd`, home, repository, files, and commands | Execution environment | Use target paths in prompts, `session.create`, and agent tool calls. |
-| `.tau/config.json`, `.tau/models.json`, personas, prompts, skills, and `AGENTS.md` used by a session | Execution environment | Edit them on the target and relative to the session `cwd`. |
+| `.tau/config.json`, personas, prompts, skills, and `AGENTS.md` used by a session | Execution environment | Edit them on the target and relative to the session `cwd`. |
 | Global runtime content for a session | Execution-environment home | `~/.config/tau` is the target user's home when runtime content is collected. |
-| Model and host-tool credentials | Host | Set environment secrets where the host process runs. Runtime `apiKeys` may be loaded from execution-environment config and consumed by the host. |
+| Model and host-tool credentials | Host | Set environment secrets where the host process runs. API keys come from the host environment or private global host configuration. |
 | Codex OAuth accounts | Host home | Run `tau auth …` on the host machine. Do not edit auth storage. |
 | Session snapshots | Host home | Local defaults live under the host's Tau config directory. Do not edit session files. |
 | Local transcript history and remote history outbox | Host home | History follows the host, not an attached TUI or execution target. |

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

@@ -1,12 +1,12 @@
 # Personas
 
-A persona is Tau's complete model-facing working profile. It chooses a provider and model, supplies the base system prompt, sets reasoning and service behavior, and selects tools and skills. Changing persona changes how future turns run without creating a new session.
+A persona is Tau's complete model-facing working profile. It chooses a provider and model, supplies the base system prompt, sets reasoning and service behavior, and selects tools. Changing persona changes how future turns run without creating a new session.
 
 Tau ships generated built-in personas and discovers custom persona Markdown from the execution environment. The effective list is version-specific and scope-specific, so inspect the current catalog rather than relying on a memorized list of names.
 
 ## Built-in and effective personas
 
-Built-in personas are generated from Tau's current model catalog. Most model families have separate chat and coder variants; some families expose only the variants Tau supports. Built-ins carry Tau-maintained prompts, defaults, tool selections, skills, and subagent supervision tools.
+Built-in personas are generated from Tau's current model catalog. Most model families have separate chat and coder variants; some families expose only the variants Tau supports. Built-ins carry Tau-maintained prompts, defaults, tool selections and subagent supervision tools.
 
 The Opus 5.5 chat and coder personas are available only when `anthropic/claude-opus-5-5` is present in the effective model catalog. The Sonnet 5.5 variants (`sonnet-5.5-chat` and `sonnet-5.5-coder`) likewise require `anthropic/claude-sonnet-5-5`.
 
@@ -44,7 +44,7 @@ These locations belong to the execution environment. An attached TUI does not co
 
 ## Persona file contract
 
-A persona is Markdown with YAML frontmatter. `id`, `provider`, and `model` are required. The Markdown body is the persona's base system prompt.
+A persona is Markdown with YAML frontmatter. `id`, `provider`, and `model` are required. A non-empty Markdown body is required and supplies the persona's own base system prompt.
 
 ```markdown
 ---
@@ -58,8 +58,6 @@ allowedReasoningLevels:
   - medium
   - high
   - xhigh
-skills:
-  - release-check
 tools:
   - bash
   - write
@@ -82,55 +80,27 @@ The frontmatter must be a YAML object between valid delimiters. Unknown fields a
 | `provider` | Non-empty provider ID from the installed [model catalog](models.md). |
 | `model` | Non-empty model ID for that provider. The ID may be unbundled when the provider is known. |
 
-`provider` and `model` are required even when the persona extends a built-in. Tau does not inherit them because selecting a model is the persona's central explicit contract.
+Each custom persona is self-contained: it supplies its provider, model, prompt, and optional settings.
 
 ### Optional fields
 
 | Field | Contract |
 | --- | --- |
-| `extends` | ID of a shipped built-in persona whose optional behavior is used as a base. |
-| `label` | Display label. A blank or omitted label falls back to the base label or `custom`. |
+| `label` | Display label. A blank or omitted label falls back to `custom`. |
 | `description` | Short catalog description. |
 | `reasoning` | Default effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
 | `serviceTier` | `priority` or `flex`. Currently meaningful for `openai` and `openai-codex`. |
 | `allowedReasoningLevels` | Array of reasoning efforts offered by the TUI selector. |
-| `skills` | `"*"`, a list of discovered skill names, or `[]`. |
 | `tools` | Explicit list of persona-controlled tools. |
 
-If a standalone custom persona omits `skills`, Tau selects all discovered skills with `"*"`. If it omits `tools`, Tau enables the ordinary host tools plus subagent supervision tools. An explicit `tools` list without `spawn_agent` prevents subagent launches. See [skills](skills.md) and [subagents](subagents.md) for those contracts.
+Every persona exposes all discovered skills. If a custom persona omits `tools`, Tau enables the ordinary host tools plus subagent supervision tools. An explicit `tools` list without `spawn_agent` prevents subagent launches. See [skills](skills.md) and [subagents](subagents.md) for those contracts.
 
 The persona-controlled tool names are:
 
-- `bash`, `write`, `edit`, `view_image`, `web`, `nook`, and `history`;
+- `bash`, `write`, `edit`, `view_image`, `web`, `nook`, `history`, and `mcp`;
 - `spawn_agent`, `send_input_to_agent`, `wait_for_agents`, `list_agents`, and `interrupt_agent`.
 
-An explicit `tools` array replaces defaults. Names are normalized to lowercase, duplicates are removed, and unknown names reject the persona. `tools: []` leaves the persona without these persona-controlled tools. Some host capabilities, such as goal management, are supplied independently of this list. Listing `nook` does not make it usable without effective Nook configuration. [Tools](tools.md) explains eligibility and ownership.
-
-## Extending a built-in
-
-`extends` reuses one shipped built-in persona as a base while still requiring an explicit provider and model:
-
-```markdown
----
-id: concise-haiku-coder
-extends: opus-5.5-coder
-provider: anthropic
-model: claude-haiku-4-5
-reasoning: low
----
-```
-
-Because the body is empty, this persona inherits the built-in's base prompt. It also inherits the base label, description, settings not explicitly overridden, allowed reasoning levels, skills, tools, and subagent map.
-
-Important boundaries are:
-
-- `extends` resolves shipped built-ins, not another custom persona.
-- Lookup of the built-in ID is case-insensitive.
-- A non-empty Markdown body replaces the inherited base prompt.
-- Explicit `skills` or `tools` replaces the inherited selection.
-- `reasoning` and `serviceTier` override their individual inherited settings; omitted settings remain inherited.
-
-Extending a built-in is useful when Tau's maintained behavior is the desired base. A standalone body is more stable when the persona must not change as Tau updates its built-in prompts.
+An explicit `tools` array replaces defaults. Names are normalized to lowercase, duplicates are removed, and unknown names reject the persona. `tools: []` leaves the persona without these persona-controlled tools. Some host capabilities, such as goal management, are supplied independently of this list. Listing `nook` does not make it usable without effective Nook configuration. Listing `mcp` requires enabled MCP servers configured on the host. [Tools](tools.md) explains eligibility and ownership.
 
 ## Selecting a persona
 
@@ -166,13 +136,13 @@ The TUI resolves that command against the session catalog case-insensitively. `C
 
 `allowedReasoningLevels` controls which values the TUI cycles for that persona. It is a presentation allowlist, not a protocol-level prohibition. When omitted, the TUI offers the standard reasoning enum for a reasoning-capable model. For a model whose catalog entry says `reasoning: false`, the selector resolves to `none`.
 
-An empty `allowedReasoningLevels` does not create an empty selector. For an extending persona it falls back to inherited levels; otherwise the TUI uses its normal model-aware choices.
+An empty `allowedReasoningLevels` does not create an empty selector. The TUI uses its normal model-aware choices.
 
 `serviceTier` is passed with supported OpenAI and OpenAI Codex requests. `priority` requests the provider's priority service and `flex` requests flex service. Availability, billing, and rejection behavior remain provider-account concerns. Other providers do not currently use this setting.
 
 ## Reloading changes
 
-Run `/reload` while the TUI session is idle after editing personas, `models.json`, skills, or project context. Reload re-discovers the effective catalog and rebuilds the current session prompt and tools.
+Run `/reload` while the TUI session is idle after editing personas, skills, or project context. Reload re-discovers the effective catalog and rebuilds the current session prompt and tools.
 
 If the current persona ID still exists, Tau applies its newly loaded definition. This can reset runtime settings such as reasoning or service tier to the definition's values. If the ID disappeared, Tau selects the first effective persona. Existing session messages remain; changing a persona does not rewrite prior model-facing history.
 
@@ -183,12 +153,10 @@ A reload does not alter a turn already in progress, and the TUI refuses the oper
 An invalid persona is skipped and reported as a configuration warning. Other valid personas still load. Frequent causes are:
 
 - malformed YAML, missing frontmatter delimiters, or frontmatter that is not an object;
-- missing `id`, `provider`, or `model`;
+- missing `id`, `provider`, `model`, or a non-empty prompt body;
 - an `id` that does not exactly match the filename;
 - an unknown provider or an unresolved model;
-- an `extends` target that is not a shipped built-in;
 - an invalid reasoning effort or service tier;
-- `skills` that is neither `"*"` nor a string list, or contains a blank entry;
 - an unknown persona tool.
 
 `/reload` surfaces warning paths directly in the transcript. For a new local TUI session, `tau --debug --persona <id>` shows the selected model, settings, skills, subagents, tools, and complete effective prompt. If a remote edit appears to have no effect, confirm the session execution environment and `cwd` before changing another copy of the file. [Troubleshooting](troubleshooting.md) covers that check in more detail.

package/dist/core/static/tau_docs/prompts-and-project-context.md

@@ -1,8 +1,8 @@
 # Prompts and project context
 
-Tau has several ways to provide instructions or reusable text, and they enter a session at different points. Prompt templates fill the editor on demand. `AGENTS.md` files provide standing project instructions. Additional context files extend that `AGENTS.md` set. Leading hidden system blocks attach model-facing instructions to one user message.
+Tau has several ways to provide instructions or reusable text, and they enter a session at different points. Prompt templates fill the editor on demand. `AGENTS.md` files provide standing project instructions. Leading hidden system blocks attach model-facing instructions to one user message.
 
-These mechanisms do not choose models or tool access. [Personas](personas.md) own the base system prompt, model settings, skill selection, and tool allowlist. Model-specific system notices are configured separately in the [configuration reference](config-reference.md).
+These mechanisms do not choose models or tool access. [Personas](personas.md) own the base system prompt, model settings and tool allowlist. Model-specific system notices are configured separately in the [configuration reference](config-reference.md).
 
 ## Prompt templates fill the editor
 
@@ -17,27 +17,19 @@ Tau discovers prompt files from:
 
 The global location is in scope only when the execution-environment working directory is inside its home directory. Tau walks project levels from the working directory toward home, or toward the filesystem root when outside home. The nearest project definition wins over parent and global definitions. Prompt IDs are compared case-insensitively for precedence and lookup.
 
-A prompt file needs YAML frontmatter with an `id` that exactly matches its filename without `.md`:
+A prompt's ID is its filename without `.md`. Each file requires YAML frontmatter with a non-empty display `label`. For example, `release-summary.md`:
 
 ```markdown
 ---
-id: release-summary
 label: release summary
-description: Summarize changes for a release announcement.
 ---
 
 Summarize the changes since the previous release. Separate user-visible changes from internal maintenance, and call out any migration steps.
 ```
 
-The fields are:
+The required `label` appears in TUI autocomplete and the Telegram prompt picker. Unknown frontmatter fields are discarded. The Markdown body is the text inserted into the editor.
 
-- `id`: required, non-empty, and exactly equal to the filename stem.
-- `label`: optional display label.
-- `description`: optional catalog and autocomplete description.
-
-Unknown fields are discarded. The Markdown body is the text inserted into the editor.
-
-Only files ending in lowercase `.md` are discovered. Invalid YAML, non-object frontmatter, a missing `id`, or an ID/filename mismatch causes Tau to skip the file and report a warning.
+Only files ending in lowercase `.md` are discovered. Invalid YAML, non-object frontmatter, or a missing or invalid label causes Tau to skip the file and report a warning.
 
 ### Invoke a prompt
 
@@ -101,32 +93,6 @@ When scanning directly from the execution home, Tau also skips direct children m
 
 It additionally skips the direct `Library` child on macOS and `snap` on Linux. A project directory with one of these names is still scanned when it is not a direct child of home.
 
-The limits and exclusions apply only to automatic descendant discovery. They do not constrain explicitly configured context files.
-
-## Add explicit context files
-
-`agentContextFiles` adds specific text files to the full injected context. The files can use any name:
-
-```json
-{
-  "agentContextFiles": ["docs/AI_GUIDE.md", "services/api/AGENTS.md"]
-}
-```
-
-Paths are resolved from the level that declares them:
-
-- A global path in `~/.config/tau/config.json` is relative to home.
-- A project path in `<project>/.tau/config.json` is relative to `<project>`, the directory containing `.tau/`.
-- Absolute paths remain absolute.
-
-Values are additive across configuration levels, from global through the nearest project level. Tau resolves them to paths and removes exact duplicates while preserving order.
-
-An explicit path must resolve to a real file whose directory is an ancestor or descendant of the working directory. An in-home session cannot escape home through a path or symlink. Sibling files, missing files, and ineligible files are not injected.
-
-Explicit files bypass the automatic child scan's depth, directory-count, and excluded-directory rules. Tau still discovers only `AGENTS.md` automatically; every other filename must be configured explicitly.
-
-Use this setting when important project instructions live outside the ordinary `AGENTS.md` hierarchy. Every included file is sent to the model as project context, so do not include secrets or unrelated content.
-
 ## Disable project context
 
 Start Tau with:
@@ -135,7 +101,7 @@ Start Tau with:
 tau --no-agent-context-files
 ```
 
-This disables ancestor `AGENTS.md` injection, configured `agentContextFiles`, and the descendant paths-only scan. It does not disable personas, prompt templates, or [skills](skills.md).
+This disables ancestor `AGENTS.md` injection and the descendant paths-only scan. It does not disable personas, prompt templates, or [skills](skills.md).
 
 The option applies to local TUI sessions and to hosts started with `tau serve`. For the Node SDK, `noAgentContextFiles: true` provides the same host-level behavior. An attached client cannot retroactively change how an existing remote host session was created.
 
@@ -146,10 +112,10 @@ A subagent normally inherits the parent session's working directory and composed
 The alternate directory controls:
 
 - target environment and repository metadata,
-- target applicable `AGENTS.md` and `agentContextFiles`,
-- target-discovered skills filtered by the parent persona.
+- target applicable `AGENTS.md`,
+- all target-discovered skills.
 
-The parent session remains the source of truth for the selected persona, model catalog, model settings, and tool policy. Tau filters skills discovered at the alternate directory through the parent persona's skill selection. It does not replace the source persona with a persona found in the target directory. See [subagents](subagents.md) for the full launch contract.
+The parent session remains the source of truth for the selected persona, model catalog, model settings, and tool policy. It does not replace the source persona with a persona found in the target directory. See [subagents](subagents.md) for the full launch contract.
 
 ## Leading hidden system blocks
 
@@ -176,4 +142,4 @@ tau --debug --persona release-coder
 
 Add `--no-agent-context-files` to verify the context-free variant. Debug mode is TUI startup functionality and is not available with `tau serve`.
 
-If expected context is missing, verify the execution-environment `cwd` and `home`, not just the attached client's current directory. Then check exact filenames, canonical path eligibility, configuration-level path bases, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.
+If expected context is missing, verify the execution-environment `cwd` and `home`, not just the attached client's current directory. Then check exact filenames, canonical path eligibility, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.

package/dist/core/static/tau_docs/remote-sessions.md

@@ -105,19 +105,18 @@ The host process executes agent-visible filesystem and command operations on its
 
 ### Fly Sprite
 
-The host must already have a named API target in `flySprites.apis`, and the Sprite must already exist:
+The host must already have a connection configured in `flySprites`, and the Sprite must already exist:
 
 ```sh
 tau attach \
   --new \
   --execution-kind fly-sprite \
-  --fly-api production \
   --fly-sprite tau-build-7 \
   --cwd /home/sprite/tau \
   wss://tau.example.com
 ```
 
-`--fly-api` identifies host configuration. `--fly-sprite` names an existing Sprite. Tau does not provision it or prepare its repository.
+`--fly-sprite` names an existing Sprite. Tau does not provision it or prepare its repository.
 
 Bridge URLs, API targets, home paths, and credential environment variables are host-owned [configuration](configuration.md). Session creation resolves Tau project configuration and content from the execution cwd through the selected environment. The execution environment itself remains a generic filesystem and process target; it does not own Tau’s configuration precedence or session policy.
 
@@ -146,7 +145,7 @@ An attached session spans three logical machines even when two happen to share o
 ### The execution environment owns
 
 - the agent-visible cwd, home, files, and repository
-- project `.tau` content, model overlays, prompts, skills, and AGENTS.md files
+- project `.tau` content, prompts, skills, and AGENTS.md files
 - command execution, platform, PATH, and runtime dependencies
 - automatic-compaction archives and other target-side temporary files
 
@@ -158,15 +157,15 @@ Different changes have different owners:
 
 | Change | Action |
 | --- | --- |
-| Project config, model overlays, personas, prompts, skills, or AGENTS.md in the execution environment | Wait for idle, then run `/reload`. |
-| Effective model `apiKeys` in execution-environment or session configuration | Wait for idle, then run `/reload`; new sessions also resolve the current values. |
+| Project config, personas, prompts, skills, or AGENTS.md in the execution environment | Wait for idle, then run `/reload`. |
+| Global model `apiKeys` on the host | Restart the host. |
 | Managed Codex auth changed with `tau auth` | No host restart; auth storage is read again on later credential resolutions. |
 | Attaching themes, speech config, or configured client tools | Restart `tau attach`. |
 | Host process environment variables, history target, WebSocket listener, Fly API target, or host startup flags | Restart `tau serve`. |
 | Host Tau package, built-in tools, protocol, session recovery code, or built-in documentation | Upgrade and restart the host. |
 | TUI package, keybindings, rendering, local speech, or client-tool implementation | Upgrade and restart the attaching client. |
 
-`/reload` is a session operation. It asks the host to resolve session-owned content, including configured model `apiKeys`, from the execution environment and does not reload either process’s executable code or environment. Managed Codex auth storage is separate and is read again on later credential resolutions. For a long-running WebSocket host, restarting only the client cannot update the model-facing built-in docs or host tools. For an old client against a new host, restarting only the host cannot update local TUI behavior. See [credentials](credentials.md) for complete precedence and apply boundaries.
+`/reload` is a session operation. It asks the host to resolve session-owned content, from the execution environment and does not reload either process’s executable code or environment. Managed Codex auth storage is separate and is read again on later credential resolutions. For a long-running WebSocket host, restarting only the client cannot update the model-facing built-in docs or host tools. For an old client against a new host, restarting only the host cannot update local TUI behavior. See [credentials](credentials.md) for complete precedence and apply boundaries.
 
 ## Reconnect and observe safely
 

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

@@ -22,26 +22,25 @@ Interruption, timeouts, output limits, and process-group termination bound execu
 
 ## Treat project content as executable policy
 
-The execution environment supplies more than source files. Tau can load project `.tau/config.json`, `.tau/models.json`, personas, prompts, skills, `.agents/skills`, and `AGENTS.md` from the working directory and its discovery path. This content can change model endpoints and headers, select tools, add instructions, define workflows, or alter which globally trusted client tools are advertised.
+The execution environment supplies more than source files. Tau can load project `.tau/config.json`, personas, prompts, skills, `.agents/skills`, and `AGENTS.md` from the working directory and its discovery path. This content can select models and tools, add instructions, define workflows, or alter which globally trusted client tools are advertised.
 
 A repository checkout is therefore part of Tau's trust boundary. Before using it with meaningful credentials or write access, inspect relevant `.tau/`, `.agents/`, and `AGENTS.md` content, including nearer nested levels. Pay particular attention to:
 
 - persona system prompts, tool lists, and model launch allowlists;
 - skill instructions and any scripts they direct the agent to run;
-- model overlays that replace endpoints, headers, capabilities, or token limits;
 - project configuration that supplies API keys, Nook targets, model notices, or hosted-environment definitions;
 - `enabledClientTools`, which can select commands previously trusted in the user's global configuration; and
 - provision scripts or other repository automation used by integrations such as Telegram.
 
 Project configuration cannot define a command client-tool executable. It can only select definitions from global configuration. That restriction prevents a checkout from directly introducing a new client process, but it does not make a selected command harmless.
 
-`--no-agent-context-files` disables `AGENTS.md` and configured context injection. It does not disable project configuration, personas, skills, model overlays, or tools. `--no-client-tools` disables TUI-provided tools, not host tools. Use the appropriate control rather than treating either flag as a general safe mode.
+`--no-agent-context-files` disables automatic `AGENTS.md` injection and descendant path discovery. It does not disable project configuration, personas, skills, or tools. `--no-client-tools` disables TUI-provided tools, not host tools. Use the appropriate control rather than treating either flag as a general safe mode.
 
 Prompt templates are inserted into the editor for review rather than submitted automatically. Leading `<system>` blocks, persona prompts, model notices, and committed session messages are model-facing and may become durable session content. Do not place secrets in instructions, prompts, or model notices.
 
 ## Trust remote model metadata as routing configuration
 
-A model-owning Tau host refreshes compatible provider catalogs from `pi.dev` and caches them in `~/.config/tau/models-store.json`. This is a trusted software-update channel, not informational discovery: a remote model record can replace its API adapter, endpoint, headers, compatibility behavior, limits, and pricing before execution-environment `models.json` overlays are applied. Compromise or misconfiguration of that service could redirect provider requests and credentials. Set `TAU_OFFLINE` to disable automatic catalog requests, and use a reviewed `models.json` overlay when a provider must stay on a fixed endpoint.
+A model-owning Tau host refreshes compatible provider catalogs from `pi.dev` and caches them in `~/.config/tau/models-store.json`. This is a trusted software-update channel, not informational discovery: a remote model record can replace its API adapter, endpoint, headers, compatibility behavior, limits, and pricing. Compromise or misconfiguration of that service could redirect provider requests and credentials. Set `TAU_OFFLINE` to disable automatic catalog requests.
 
 ## Keep secrets with the process that needs them
 
@@ -53,7 +52,7 @@ Prefer host process environment variables or private global configuration over p
 
 Never put credentials in:
 
-- committed `.tau/config.json` or `.tau/models.json` files;
+- committed project files;
 - persona, prompt, skill, `AGENTS.md`, or model-notice text;
 - Bash command lines likely to enter shell history or process listings;
 - tool results, session messages, issue comments, or debug output; or
@@ -104,7 +103,7 @@ The TUI's built-in diff review tool is also a client-local process.
 
 ## Use code mode as a capability boundary
 
-The generated JavaScript used by `web`, `history`, `nook`, and code-mode client tools runs in Tau's bounded worker runtime. It receives only a declared API, `docs`, console output, live `Date`, `Math.random()`, and, when configured, agent-scoped UTF-8 scratch files. Generated code has no direct imports, process, environment, credentials, timers, `fetch`, or arbitrary network access.
+The generated JavaScript used by `web`, `history`, `nook`, `mcp`, and code-mode client tools runs in Tau's bounded worker runtime. It receives only a declared API, `docs`, console output, the asynchronous `image(block)` output helper, live `Date`, `Math.random()`, and, when configured, agent-scoped UTF-8 scratch files. Generated code has no direct imports, process, environment, credentials, timers, `fetch`, or arbitrary network access.
 
 API handlers run outside that worker and retain the authority deliberately exposed by the tool. The boundary therefore limits generated code to declared capabilities, but it does not make an overpowered API safe. Tool authors should validate every argument, expose narrow operations, keep credentials in the parent, enforce cancellation, and avoid returning secrets.
 
@@ -112,6 +111,18 @@ Scratch files live in a private execution-environment temporary directory derive
 
 The `history` code-mode API is read-only, but it can see transcripts across repositories and execution environments in the configured collection. Its agent policy requires a direct user or active-instruction request before use. That policy does not replace access control on the history service.
 
+## Trust MCP servers
+
+MCP server definitions come from the host launch directory's global and ancestor/project configuration layers. Launching a host inside a repository trusts those layers to introduce host commands and use host credentials; there is no approval dialog. MCP capabilities apply to all sessions on that host whose persona allows `mcp`, and their supervised subagents; they are not isolated per repository or client. Session execution-environment configuration cannot introduce servers.
+
+A stdio MCP server is trusted host code. It runs outside the code-mode sandbox with the host account's filesystem and process permissions and full inherited environment, including credentials. Review executables and arguments before configuring them. HTTP servers receive configured headers and the arguments sent to their tools. Use HTTPS for remote services and grant only the access needed.
+
+MCP does not add a confirmation layer. Tools can mutate external systems or host resources immediately. Interrupting a call cannot undo a completed effect, and an unknown outcome does not make retrying a mutation safe. Server descriptions, instructions, annotations, and results are untrusted data. Annotations such as `readOnlyHint` are not enforced permissions.
+
+Stdio shutdown depends on the MCP transport. Descendants that ignore `SIGTERM` can survive when the server process exits first; do not rely on shutdown to contain untrusted server processes.
+
+The execution environment does not sandbox a host-run MCP server. A server that exposes host files or commands gives the agent that host authority even when Bash runs in a remote sandbox. Disable `mcp` in the persona or disable the server if that authority is inappropriate. Connections and credentials stay outside the generated JavaScript, but the configured server remains responsible for what its tools return.
+
 ## Protect remote session transports
 
 `tau serve` binds to loopback by default. Keep that default unless remote network access is required. A WebSocket server without `--auth-token` or `TAU_WS_AUTH_TOKEN` is unauthenticated, and any connected client can observe and mutate hosted sessions.

package/dist/core/static/tau_docs/session-protocol-methods.md

@@ -1,6 +1,6 @@
 # Session protocol method reference
 
-This page defines every request method in protocol version 14. It is the compact wire reference for clients that already understand connection, observation, and delta application from the [session protocol](session-protocol.md).
+This page defines every request method in protocol version 15. It is the compact wire reference for clients that already understand connection, observation, and delta application from the [session protocol](session-protocol.md).
 
 Every request uses `{ version, type: "request", id, method, params }`. Every successful response uses `{ version, type: "response", id, ok: true, result }`. `params` is required even when empty, and unknown object fields are stripped.
 
@@ -47,7 +47,7 @@ params: {
 }
 
 result: {
-  protocolVersion: 14;
+  protocolVersion: 15;
   methods: string[];
   alreadyInitialized: boolean;
 }
@@ -65,7 +65,6 @@ params: {
     | { kind: "local"; cwd: string; env?: Record<string, string> }
     | {
         kind: "fly-sprite";
-        apiId: string;
         spriteName: string;
         cwd: string;
       };
@@ -594,7 +593,10 @@ params:
       sessionId: string;
       callId: string;
       ok: true;
-      content: string;
+      content: Array<
+        | { type: "text"; text: string; textSignature?: string }
+        | { type: "image"; data: string; mimeType: "image/jpeg" | "image/png" | "image/webp" }
+      >;
       presentation?: PresentationOverride;
     }
   | {
@@ -607,6 +609,8 @@ params:
 result: { accepted: boolean };
 ```
 
+`content` preserves text/image block order in the model-facing result, snapshots, and deltas. It may be empty and allows at most 1,024 blocks, including at most 16 images with valid padded base64 representing at most 3.5 MiB each. Image bytes are not presentation content.
+
 The optional result presentation applies only to the reported terminal state and is resolved independently from the running presentation. The host preserves explicit fields unchanged after safety validation and supplies canonical display-truncated defaults for omitted fields. If no client result arrives, the host uses a complete fallback for timeout, cancellation, detach, or another terminal outcome.
 
 A successful result is accepted only after the host has accepted the acknowledgement. An error sent before acknowledgement records a preparation failure, such as an error from `describe`, without authorizing execution. An error sent afterward records an execution failure.