@markusylisiurunen/tau 0.3.81 → 0.3.83

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

@@ -1,73 +1,75 @@
 # Terminal interface
 
-Tau’s terminal interface is both a local chat client and a remote session client. The same editor, commands, and review workflow are available in either mode, but their ownership matters: the session host owns conversation state and model work, while the TUI owns terminal presentation and client-local features such as themes, clipboard access, speech, and the diff-tool process.
+Tau's terminal interface works both for local sessions and for sessions on a remote host. The editor, commands, and review workflow are the same in both. The session host holds the conversation and runs the model, while the TUI handles the terminal and local features such as themes, the clipboard, speech, and the diff tool.
 
 ## Start the TUI
 
-Run `tau` in the project directory for a new local session:
+Run `tau` in the project directory to start a new local session:
 
 ```sh
 cd ~/Code/tau
 tau
 ```
 
-Tau creates a local execution environment rooted at that directory. A startup persona and reasoning level can be selected together:
+The agent works in that directory. You can choose a persona and reasoning level at startup:
 
 ```sh
 tau --persona gpt-6.1-sol-coder:high
 ```
 
-`-p` is the short form. `--no-agent-context-files` omits `AGENTS.md` injection and the descendant context-file scan, and `--no-client-tools` prevents the TUI from advertising its built-in and configured [client tools](client-tools.md).
+`-p` is the short form. `--no-agent-context-files` turns off `AGENTS.md` loading and the scan for nested `AGENTS.md` files. `--no-client-tools` stops the TUI from offering its built-in and configured [client tools](client-tools.md).
 
-Piped stdin becomes the first message in a local TUI session:
+Piped stdin becomes the first message of a local session:
 
 ```sh
 printf 'summarize the current changes' | tau
 ```
 
-Use `tau attach` for a session hosted elsewhere. The terminal, themes, clipboard, speech commands, built-in diff review tool, and command-backed client tools still belong to the attaching machine. Bash tools, file access, project configuration, and model work use the session’s execution environment. See [remote sessions](remote-sessions.md) for transport and creation examples.
+Use `tau attach` for a session hosted elsewhere. The terminal, themes, clipboard, speech commands, built-in diff review tool, and command client tools stay on the attaching machine. Bash tools, file access, project configuration, and model calls use the session's execution environment. See [remote sessions](remote-sessions.md) for connecting and creating sessions.
 
-The startup summary lists discovered skills, project context files, configured client tools, and enabled MCP server names. MCP servers are labeled configured, not connected: connections open lazily on first use. In attached sessions, the MCP list comes from the session host. Empty sections are omitted.
+The startup summary lists discovered skills, project context files, configured client tools, and enabled MCP servers. MCP servers are shown as configured, not connected, because connections open on first use. In attached sessions, the MCP list comes from the host. Empty sections are left out.
 
 ## Work in the editor
 
-Enter submits the editor. Shift+Enter or Ctrl+J inserts a newline. Up and Down move through the editor and recall prior submissions when the editor is empty.
+Enter submits. Shift+Enter or Ctrl+J inserts a newline. Up and Down move within the editor, and recall earlier submissions when the editor is empty.
 
-Tau recognizes these mention forms and offers Tab completion:
+Tau recognizes these mentions and completes them with Tab:
 
 - `@src/main.ts` mentions a file in the execution environment.
 - `@@skill:code-review` explicitly activates an available skill.
 
-The older `@file:`, `@skill:`, and `@agent:` forms are not mention syntax. Paths and available skill names come from the hosted session, not from the attaching TUI’s filesystem.
+Other forms, such as `@file:`, `@skill:`, or `@agent:`, are not mentions. File paths and skill names come from the session, not from the attaching machine's filesystem.
 
-Typing `/` at the start of a line opens command completion. Slash commands are recognized only for single-line submissions. A multiline input beginning with `/`, or an unknown slash-prefixed input, is sent to the agent as an ordinary message.
+Typing `/` at the start of a line opens command completion. Slash commands work only in single-line submissions. Multiline input that starts with `/`, and unknown slash commands, are sent to the agent as ordinary messages.
 
 ## Submit, queue, and steer
 
-When Tau is idle, Enter and Ctrl+Enter both start a normal turn. While a turn is active:
+When Tau is idle, Enter and Ctrl+Enter both start a normal turn. While a turn is running:
 
-- Ctrl+Enter queues the text as a new turn to run when the session becomes idle.
-- Enter steers the active turn. Tau applies steering at a safe continuation boundary rather than injecting it into a model response or tool execution in progress.
-- Alt+Up cancels all pending queued messages and steering that has not yet been applied, then restores their text to the editor. Multiple messages are separated with `---`. Hidden guidance, such as transcription warnings, stays hidden in the pending list and editor. Restoring messages preserves their guidance in order after any guidance already attached to the draft. Submission places all guidance at the beginning of the combined message. Editing a non-empty draft preserves it; clearing the draft clears it.
+- Ctrl+Enter queues the text as a new turn that runs when the session becomes idle.
+- Enter steers the running turn. Tau applies steering at the next safe point, never in the middle of a model response or tool call.
+- Alt+Up cancels all queued messages and steering not yet applied, and puts their text back in the editor, separated by `---`.
 
-Pending input is session state shared by attached clients while the host remains alive. It is not durable across host restart or session recovery. A queued turn captures the persona, reasoning, tools, and model settings when that turn actually starts. Steering remains part of the active logical turn and keeps the settings captured when that turn began.
+Some messages carry hidden guidance, such as a note that text was transcribed from speech. Hidden guidance stays hidden in the pending list and the editor. When messages are restored, their guidance is kept, in order, after any guidance the draft already has. On submission, all guidance goes at the start of the combined message. Editing a non-empty draft keeps its guidance, and clearing the draft removes it.
 
-Escape interrupts foreground client work or the main session’s active work. If a local diff review, voice input, or speech playback task owns the foreground, Escape stops that task first; otherwise it requests main-session interruption from the host, including cancellation of a running manual compaction. Once compaction has replaced model context, a late interruption does not undo it or turn successful persistence into a failure. It does not stop independently running supervised subagents; select one with Alt+Down and use Ctrl+G. Press Escape twice to clear the current editor text.
+Pending input is shared by all clients attached to the session while the host keeps running. It is not saved and is lost when the host restarts. A queued turn uses the persona, reasoning, tools, and model settings current when it actually starts. Steering belongs to the running turn and uses the settings that turn started with.
 
-Press Enter twice on an empty editor to retry from the current session history. Retry does not rewind or duplicate the last user message. Goal-controlled turns cannot be retried; resume a blocked goal instead.
+Escape interrupts work. If local work is in the foreground, such as diff review, voice input, or speech playback, Escape stops that first. Otherwise it asks the host to interrupt the session, which also cancels a running manual compaction. Once compaction has replaced the context, a late interruption does not undo it or turn the saved result into a failure. Escape does not stop subagents; select one with Alt+Down and press Ctrl+G. Press Escape twice to clear the editor.
+
+Press Enter twice on an empty editor to retry from the current history. Retry does not rewind or repeat the last user message.
 
 ## Choose persona, reasoning, and thought visibility
 
-The current persona and reasoning level appear in the editor header.
+The editor header shows the current persona and reasoning level.
 
-- `/persona:<id>` selects a persona by id.
+- `/persona:<id>` selects a persona by ID.
 - Ctrl+P cycles through available personas.
-- Shift+Tab cycles through the current persona’s allowed reasoning levels.
-- Ctrl+T shows or hides stored and streamed assistant thinking in this TUI.
+- Shift+Tab cycles through the persona's allowed reasoning levels.
+- Ctrl+T shows or hides the assistant's thinking in this TUI.
 
-Persona changes require the session to be idle because they can change the model, instructions, skills, and tools. Reasoning can be changed while a turn is running, but the active turn and its steering continuations keep their captured settings. The new reasoning level applies to the next independently started or queued turn.
+Persona changes require an idle session, because they can change the model, instructions, skills, and tools. Reasoning can change while a turn is running, but that turn and its steering keep their settings. The new level applies from the next turn.
 
-Thought visibility is client-local presentation. Ctrl+T does not enable model reasoning, change its effort, or alter the session history.
+Ctrl+T affects only what this TUI displays. It does not turn on reasoning, change its effort, or change the session history.
 
 For example:
 
@@ -75,35 +77,34 @@ For example:
 /persona:opus-5.5-coder
 ```
 
-Then use Shift+Tab to select an allowed reasoning level. Newly added personas do not appear until session content has been reloaded.
+Then use Shift+Tab to choose a reasoning level. A newly added persona appears only after `/reload`.
 
 ## Slash commands
 
-`/help` prints the commands, keybindings, loaded skills, and context-file paths visible to the current session.
+`/help` prints the commands, keybindings, loaded skills, and context file paths for the current session.
 
 | Command | Behavior |
 | --- | --- |
 | `/help` | Show commands, keys, skills, and context paths. |
-| `/new` | Create a fresh session in the same execution environment, carrying over the current persona, reasoning, and conventional repository attribute. |
-| `/exit` | Close this TUI. It detaches from a long-running remote host rather than deleting the session. |
-| `/rewind` | Pick an earlier user message, remove it and everything after it, and return its text to the editor. |
-| `/diff [git diff args...]` | Open the client-local diff review tool for a snapshot captured from the execution environment. |
-| `/goal [objective\|resume\|clear]` | Show, start, resume, or clear the persistent session goal. |
-| `/compact-all [guidance]` | Replace model context with a generated summary. |
-| `/compact-keep-last [guidance]` | Generate a summary that also includes the previous last assistant response when available. |
-| `/reload` | Reload session-owned configuration and content from the execution environment. |
-| `/listen [retry/discard]` | Record speech, retry a retained failed recording, or discard it on macOS. |
-| `/speak` | Read the last assistant response aloud on macOS. |
-| `/auto-speak [on | off]` | Toggle automatic reading of final responses, or explicitly enable or disable it. |
+| `/new` | Create a new session in the same execution environment, keeping the current persona, reasoning, and `repository` attribute. |
+| `/exit` | Close this TUI. On a long-running remote host, this detaches; the session is not deleted. |
+| `/rewind` | Pick an earlier user message, remove it and everything after it, and put its text back in the editor. |
+| `/diff [git diff args...]` | Open the local diff review tool on a snapshot taken from the execution environment. |
+| `/compact-all [guidance]` | Replace the model's context with a generated summary. |
+| `/compact-keep-last [guidance]` | Same, and include the last assistant response in the summary when there is one. |
+| `/reload` | Reload session configuration and content from the execution environment. |
+| `/listen [retry/discard]` | Record speech, or retry or discard a failed recording. macOS only. |
+| `/speak` | Read the last assistant response aloud. macOS only. |
+| `/auto-speak [on | off]` | Toggle automatic reading of final responses, or turn it on or off. |
 | `/copy-text` | Copy the last assistant response as plain text. |
-| `/copy-code` | Copy code blocks from the last assistant response. |
+| `/copy-code` | Copy the code blocks from the last assistant response. |
 | `/persona:<id>` | Switch persona while idle. |
-| `/prompt:<id>` | Resolve a prompt from the execution environment and place it in the editor without submitting it. |
-| `/theme:<id>` | Switch this TUI’s theme for the current run. |
+| `/prompt:<id>` | Load a prompt from the execution environment into the editor without sending it. |
+| `/theme:<id>` | Switch this TUI's theme until it exits. |
 
-Commands that mutate context, such as persona changes, compaction, rewind, and reload, should be run while idle. `/goal` display and clear, `/auto-speak`, `/listen`, `/prompt:<id>`, and `/exit` have limited useful behavior during a running turn. Ordinary command submissions are otherwise held back until Tau is idle.
+Run commands that change the context, such as persona changes, compaction, rewind, and reload, while idle. `/auto-speak`, `/listen`, `/prompt:<id>`, and `/exit` do little during a running turn. Other commands wait until Tau is idle.
 
-Compaction, rewind, goals, recovery, and retry are described in [sessions](sessions.md). Prompt discovery and insertion are covered in [prompts and project context](prompts-and-project-context.md).
+[Sessions](sessions.md) describes compaction, rewind, recovery, and retry. [Prompts and project context](prompts-and-project-context.md) covers prompt files.
 
 ## Keyboard shortcuts
 
@@ -111,80 +112,103 @@ Compaction, rewind, goals, recovery, and retry are described in [sessions](sessi
 | --- | --- |
 | Shift+Tab | Cycle reasoning effort. |
 | Ctrl+P | Cycle persona while idle. |
-| Ctrl+T | Toggle thought visibility in this TUI. |
-| Ctrl+S | Copy the expanded editor contents to the local clipboard, then clear the editor. |
+| Ctrl+T | Show or hide thinking in this TUI. |
+| Ctrl+S | Copy the expanded editor contents to the clipboard, then clear the editor. |
 | Ctrl+Y | Start or stop voice recording without submitting. |
-| Enter | Steer an active turn, or submit normally while idle. |
-| Ctrl+Enter | Queue another turn, or submit normally while idle. |
-| Alt+Up | Cancel pending input and restore it to the editor. |
-| Alt+Down | Cycle the selected active subagent. |
-| Ctrl+G | Interrupt the selected active subagent. |
-| Enter twice | Retry when the editor is empty and the session is idle. |
-| Escape | Interrupt foreground client or main-session work. |
-| Escape twice | Clear the current editor text. |
+| Enter | Steer a running turn, or submit while idle. |
+| Ctrl+Enter | Queue another turn, or submit while idle. |
+| Alt+Up | Cancel pending input and put it back in the editor. |
+| Alt+Down | Select the next running subagent. |
+| Ctrl+G | Interrupt the selected subagent. |
+| Enter twice | Retry, when the editor is empty and the session is idle. |
+| Escape | Interrupt local work or the session. |
+| Escape twice | Clear the editor. |
 | Ctrl+C twice | Exit the TUI. |
 
-Ctrl+C once asks for confirmation rather than interrupting the assistant. Use Escape for interruption.
+A single Ctrl+C asks for confirmation; it does not interrupt the assistant. Use Escape to interrupt.
 
-## Run direct Bash commands
+## Run Bash commands directly
 
-A leading `!` runs a fresh non-interactive login Bash in the session execution environment without asking the model to create a tool call:
+A leading `!` runs a command in a fresh non-interactive login Bash in the execution environment, without going through the model:
 
 ```text
 !git status --short
 ```
 
-The command and result are added to session context, so the agent can use them later. A double prefix runs the command without adding it to model context:
+The command and its output are added to the session, so the agent can use them later. A double `!!` runs the command without adding it to the model's context:
 
 ```text
 !!git diff --stat
 ```
 
-`!!` is useful for checks that should not consume context. Its transient card is still visible in the current TUI, but the command and output are not recorded as session conversation state.
+Use `!!` for checks that should not use up context. Its card still appears in the current TUI, but the command and output are not saved in the conversation.
 
-Direct commands require the session to be idle. In an attached TUI, `!pwd` reports the execution environment’s directory, not the attaching machine’s directory. Command-backed [client tools](client-tools.md) are different: their processes run on the client machine and can explicitly request execution-environment commands through the session.
+Direct commands require an idle session. In an attached TUI, `!pwd` shows the execution environment's directory, not the attaching machine's. Command [client tools](client-tools.md) are different: they run on the client machine and can ask the session to run commands in the execution environment.
 
 ## Use themes
 
-Themes belong to the TUI process and never become session state. Tau’s built-in themes adapt to detected terminal appearance.
+Themes belong to the TUI and are never saved in the session. Tau's built-in themes adapt to the terminal's light or dark appearance.
 
-Set the startup theme with `defaultTheme` in the attaching client’s [configuration](configuration.md), or switch for the current run:
+Set the startup theme with `defaultTheme` in the client's [configuration](configuration.md), or switch for the current run:
 
 ```text
 /theme:gold
 ```
 
-Theme ids are exact and case-sensitive. `/theme` does not persist the selection. Restart the TUI to apply a new `defaultTheme`. A remote host’s theme selection does not affect an attached client.
+Theme IDs are exact and case-sensitive. `/theme` does not save the choice. Restart the TUI to apply a new `defaultTheme`. A remote host's theme setting does not affect attached clients.
 
 ## Review a diff
 
-`/diff` captures a Git snapshot through the session execution environment, then launches a diff-tool process on the TUI machine. The built-in browser tool is the review interface. `tau diff-tool` is its process entry point. `tau diff-tool --help` shows its help, while `/diff` supplies the environment required for normal reviews. Arguments are passed as Git diff arguments, for example:
+`/diff` takes a Git snapshot in the execution environment, then opens the built-in browser review tool on the TUI machine. Arguments are passed to `git diff`, for example:
 
 ```text
 /diff --staged
 ```
 
-Captured snapshot patches are limited to 16 MiB. Narrow the Git arguments when a larger scope is rejected. A plain working-tree snapshot includes non-binary untracked files up to 4 MiB each within that aggregate limit.
+`tau diff-tool` is the tool's own command, and `tau diff-tool --help` shows its help, but normal reviews start from `/diff`, which sets up its environment.
+
+A snapshot's patch can be at most 16 MiB. Narrow the Git arguments if a larger diff is rejected. A plain working-tree snapshot includes non-binary untracked files of up to 4 MiB each, within that total.
 
-The built-in tool opens in Guide mode and starts preparing reviewer orientation, focused topics, and likely questions as soon as its shared review context is ready. Reviewers can comment on that guide, ask for another topic or question, or switch to Diff mode for file and line-level review threads. Guide comments and unresolved diff threads are included in self-contained returned Markdown that identifies the reviewed scope, gives change-level comments their relevant context, and explains the participants and roles in review discussions. Submit first opens the exact return-text preview, where included feedback can be excluded and the full review can be copied before submission. Approve returns immediately when no feedback remains; if feedback appears while approval is being checked, the preview opens instead.
+The tool opens in **Guide** mode and starts preparing an orientation, focused topics, and likely reviewer questions as soon as the review context is ready. You can comment on the guide, ask for another topic or question, or switch to **Diff** mode for review threads on files and lines.
 
-The session host supplies ephemeral review agents, while the local tool owns its browser or interface process. Returned review feedback is recorded as a user entry in the session so it remains available, but Tau does not automatically start an assistant turn after the tool closes. Submit a follow-up message when the review should drive more work.
+Guide comments and unresolved diff threads go into the returned Markdown, which stands on its own: it names the reviewed scope, gives change-level comments their context, and explains who took part in each discussion and in what role. **Submit** first opens a preview of the exact text to be returned, where you can exclude feedback and copy the full review before submitting. **Approve** returns right away when no feedback remains. If feedback appears while approval is being checked, the preview opens instead.
 
-The TUI also advertises diff review as a client tool unless `--no-client-tools` is set. Manual `/diff` remains a TUI command even when model-facing client tools are disabled. See [client tools](client-tools.md) for attachment and multiple-client implications.
+The session host provides temporary review agents, and the local tool runs the browser interface. The returned review is added to the session as a user message, but Tau does not start an assistant turn when the tool closes. Send a follow-up message when the review should lead to more work.
+
+The TUI also offers diff review to the agent as a client tool, unless `--no-client-tools` is set. `/diff` works either way. See [client tools](client-tools.md) for what this means with several clients.
 
 ## Use speech
 
-`/listen` and Ctrl+Y are currently macOS-only. Recording uses local `ffmpeg` with the AVFoundation audio input and stops when Ctrl+Y is pressed again or at the 9-minute recording limit. The Gemini limit leaves time for setup and finalization within its 10-minute live session. Startup fails if the microphone produces no audio within 15 seconds. Pressing Enter or Ctrl+Enter while recording stops capture, finishes transcription, and submits the finalized editor text. While a turn is active, Enter steers it and Ctrl+Enter queues another turn, just like normal editor submission. Pressing Ctrl+Y again or reaching the recording limit finishes transcription and inserts the transcript at the cursor for review without submitting it.
+### Dictation
+
+`/listen` and Ctrl+Y work only on macOS. Recording uses the local `ffmpeg` with AVFoundation audio input. It stops when you press Ctrl+Y again or after 9 minutes, which leaves time to finish within Gemini's 10-minute live session. Startup fails if the microphone gives no audio within 15 seconds.
+
+- Enter or Ctrl+Enter while recording stops capture, finishes transcription, and submits the editor text. While a turn is running, Enter steers and Ctrl+Enter queues, as usual.
+- Ctrl+Y, or reaching the time limit, finishes transcription and inserts the transcript at the cursor without submitting it.
+
+The shortcut can be changed with [`speech.recordingShortcut`](config-reference.md#speech), including single-press or double-tap printable keys such as `§`. The editor hint shows the configured gesture. Starting a recording stops speech playback.
+
+While you speak, Gemini shows a live preview in muted italics at the cursor. During pauses, Gemini finalizes segments of speech while recording continues. Tau keeps finalized segments and replaces only the current preview. After recording stops:
+
+- Tau tells Gemini the audio has ended. It finishes right away if a finalized segment ends exactly at the end of the audio and generation is complete.
+- Otherwise it keeps receiving results until two seconds pass with no updates. If new speech is detected after stopping, Tau signals the end of audio again to flush it.
+- The final transcript comes from the live stream. Normal recordings are not uploaded again for a second transcription.
+- Unfinished speech must be finalized before Tau accepts the result. Finalization has a 30-second deadline, and Escape cancels the wait.
 
-The recording shortcut is configurable with [`speech.recordingShortcut`](config-reference.md#speech), including single-press and double-tap printable keys such as `§`. The editor hint shows the configured gesture. Starting a recording stops speech playback.
+The final transcript replaces the preview in normal text, without duplication. An empty transcript inserts nothing. Tau does not detect silence locally, and the end of one speech segment does not count as the end of the recording.
 
-`/auto-speak` toggles automatic reading of successful final answers. `/auto-speak on` and `/auto-speak off` explicitly select the mode; turning it off also stops current playback. It starts off and applies only to the current session in this TUI, including when attached remotely. `/new` resets it. It does not change other clients or replay historical answers. Commentary, tool activity, and failed or interrupted answers are not automatically spoken. Responses arriving while recording or playing speech are not queued for later playback. Escape stops playback without disabling the mode. Automatic playback uses the same voice, credentials, and rewriting as `/speak`; it does not open the microphone or automatically submit dictation.
+A submitted draft that contains dictation carries hidden guidance saying that some or all of the message may have been transcribed from speech and may contain errors. The guidance survives edits and is removed when the draft is emptied.
 
-Gemini displays a replaceable live preview in muted italic text at the original cursor position. Finalized dictation uses normal text once transcription settles. Its final transcript replaces the preview without duplication. Submitting a draft containing finalized dictation includes hidden guidance that some or all of the message may have been transcribed from speech and may contain transcription errors. The guidance remains after edits and clears when the draft is emptied. Editing stays disabled from recording startup through finalization. Escape cancels voice input during startup, recording, microphone shutdown, transcription, or retry. Cancellation immediately removes the preview, restores the original draft, and re-enables editing without inserting or submitting speech. The cancelled recording is deleted after pending capture or file work settles. Failure also restores the original draft. Recording and retries cannot start while another editor update is pending.
+The editor is locked from the start of recording until finalization. Escape cancels voice input at any stage: startup, recording, microphone shutdown, transcription, or retry. Cancelling removes the preview at once, restores the original draft, and unlocks the editor without inserting or submitting anything. The cancelled recording is deleted once pending file work finishes. A failure also restores the original draft. A recording or retry cannot start while another editor update is pending.
 
-A completed empty transcription inserts nothing. Tau does not detect silence locally or infer completion from Gemini’s activity-end notification. If Gemini does not complete transcription, Tau waits up to 30 seconds after the live session is ready before reporting failure; Escape cancels this wait.
+For live transcription, GPT-6 Luna, with reasoning disabled, extracts spelling hints from the recent conversation while recording starts. Tau buffers audio until the transcription session is ready, then streams it. Gemini uses `gemini-3.5-transcribe-live` in verbatim mode with English (`en-US`) and Finnish (`fi-FI`) language hints. Missing OpenAI credentials or a failed hint extraction do not stop transcription.
 
-If transcription fails, Tau retains the local WAV and reports its path. Run `/listen retry` to transcribe the same audio again with Gemini and the current conversation context, or `/listen discard` to delete it. Retained recordings longer than 20 minutes are rejected rather than sent to the provider. A replacement recording deletes the retained file only after the new capture starts producing audio. Tau keeps at most one failed recording, and exiting leaves that file at the reported path for manual recovery. For live transcription, GPT-6 Luna extracts spelling hints from recent conversation while recording begins, with reasoning disabled. Tau buffers audio until the transcription session is ready and then streams subsequent audio. Gemini uses `gemini-3.5-transcribe-live` in verbatim mode with English (`en-US`) and Finnish (`fi-FI`) language hints. Missing OpenAI credentials or hint extraction failure does not fail transcription. On retry, Gemini uploads the retained recording for `gemini-3.5-transcribe` verbatim transcription with the same language hints and attempts to delete the remote file afterward.
+If transcription fails, Tau keeps the local WAV file and reports its path:
+
+- `/listen retry` transcribes the same audio again with Gemini and the current conversation context. Gemini uploads the file for `gemini-3.5-transcribe` verbatim transcription with the same language hints, and Tau tries to delete the uploaded file afterward. Recordings longer than 20 minutes are rejected instead of being sent.
+- `/listen discard` deletes the file.
+
+Tau keeps at most one failed recording. A new recording deletes it only once the new capture is producing audio. Exiting leaves the file at the reported path so you can recover it.
 
 Install `ffmpeg`:
 
@@ -192,22 +216,41 @@ Install `ffmpeg`:
 brew install ffmpeg
 ```
 
-Speech transcription uses Gemini and requires `GEMINI_API_KEY` or `apiKeys.google`. Credentials are read by the TUI process, including during remote attachment.
+Transcription uses Gemini and needs `GEMINI_API_KEY` or `apiKeys.google`. The TUI process reads these credentials, also when attached to a remote host.
+
+### Reading responses aloud
+
+`/speak` also works only on macOS. It rewrites the last assistant response with GPT-6 Luna (reasoning disabled), streams Eleven v4 Turbo audio, and plays it at 1.15× speed through `ffplay`, which comes with `ffmpeg`.
+
+- It needs `OPENAI_API_KEY` or `apiKeys.openai` for rewriting, and `ELEVENLABS_API_KEY` or `apiKeys.elevenlabs` for synthesis.
+- It runs only while the session is idle. Escape stops it.
+- Longer responses are split into balanced parts, each aiming for at most two minutes of speech.
+- The source and rewritten text are limited to 10,000 Unicode characters, and generation stops after 32 MiB of raw audio.
+- Voice lookups and synthesis requests have a two-minute deadline.
+
+See [`speech` configuration](config-reference.md#speech) for the default Maisie and Caleb voices and for choosing your own.
+
+`/auto-speak` toggles automatic reading of successful final answers, and briefly confirms the new mode. `/auto-speak on` and `/auto-speak off` set it explicitly, and turning it off also stops current playback.
 
-`/speak` is also macOS-only. It rewrites the last assistant response with GPT-6 Luna (reasoning disabled), streams Eleven v4 Turbo audio, and plays it at 1.15× speed through the local `ffplay` command included with `ffmpeg`. It requires both `OPENAI_API_KEY` or `apiKeys.openai` for rewriting and `ELEVENLABS_API_KEY` or `apiKeys.elevenlabs` for synthesis, runs only while the session is idle, and can be stopped with Escape. Longer responses are divided into balanced segments targeting at most two minutes of generated speech each. Speech source and rewritten text are limited to 10,000 Unicode characters, and generation stops after 32 MiB of raw audio. Voice lookups and synthesis requests have a two-minute deadline. See [`speech` configuration](config-reference.md#speech) for the default Maisie/Caleb lookup and custom voice selection.
+- It starts off and applies only to the current session in this TUI, also when attached remotely. `/new` turns it off.
+- It does not affect other clients or read earlier answers.
+- Commentary, tool activity, and failed or interrupted answers are not read.
+- Answers that arrive while recording or playing speech are not saved for later playback.
+- Escape stops playback without turning the mode off.
+- It uses the same voice, credentials, and rewriting as `/speak`. It never opens the microphone or submits dictation.
 
 ## Reload the right component
 
-Run `/reload` while idle after changing session-owned configuration, personas, prompts, skills, or AGENTS.md content in the execution environment. The host resolves them again from the session cwd, keeps the current persona when it still exists, and otherwise selects the first available persona. Warnings are shown in the transcript.
+Run `/reload` while idle after changing configuration, personas, prompts, skills, or `AGENTS.md` content in the execution environment. The host reads them again from the session's working directory, keeps the current persona if it still exists, and otherwise selects the first available persona. Warnings appear in the transcript.
 
-Restart the TUI instead after changing client-owned themes, the diff launcher, speech settings, or configured client tools. Effective model `apiKeys` in session configuration can update through `/reload`, and managed Codex auth storage is read again on later credential resolutions. Restart the host after changing its binary, process environment variables, WebSocket listener, or hosted execution-environment resolver configuration. [Credentials](credentials.md) has the canonical apply boundaries, and [remote sessions](remote-sessions.md) explains the component split.
+Restart the TUI instead after changing themes, speech settings, or configured client tools. Codex auth storage is read again on every new request. Restart the host after changing its Tau version, environment variables, `apiKeys`, WebSocket listener, or hosted execution environment settings. [Credentials](credentials.md) and [remote sessions](remote-sessions.md) explain which process owns what.
 
 ## Common mistakes
 
-- `!` and `!!` run in the execution environment, not on the attaching client.
+- `!` and `!!` run in the execution environment, not on the attaching machine.
 - Enter during a turn steers it. Use Ctrl+Enter to queue another turn.
-- Ctrl+T changes visibility only. Use Shift+Tab to change reasoning effort.
-- `/prompt:<id>` fills the editor but does not submit it.
-- `/diff` records returned feedback but does not automatically ask the assistant to act on it.
+- Ctrl+T changes only what is displayed. Use Shift+Tab to change reasoning effort.
+- `/prompt:<id>` fills the editor but does not send it.
+- `/diff` adds the returned review to the session but does not ask the assistant to act on it.
 - `/reload` does not reload client themes or client tools.
-- Exiting a WebSocket attachment does not delete or necessarily stop the hosted session. Exiting a local TUI shuts down its owned host, so active work is interrupted and persisted before recovery where possible.
+- Exiting a WebSocket attachment does not delete the session and does not necessarily stop it. Exiting a local TUI shuts down its host, so running work is interrupted and saved where possible.

package/dist/core/telegram/adapter.js

@@ -328,16 +328,11 @@ function formatSessionStatus(session, project, snapshot, preferredProjectId) {
     if (!snapshot) {
         return `${status}${preferenceStatus}`;
     }
-    const goalStatus = snapshot.goal
-        ? snapshot.goal.status === "active"
-            ? " it is pursuing a goal."
-            : " its goal is blocked."
-        : "";
     const model = snapshot.bootstrap.model.name || snapshot.bootstrap.model.id;
     const reasoning = snapshot.settings.reasoning ?? "none";
     const context = formatTelegramContextUsage(snapshot);
     const cost = formatTelegramSessionCost(getTelegramSessionCostTotal(snapshot));
-    return `${status}${goalStatus} it is using ${model} with ${reasoning} reasoning. context usage is ${context}. cumulative cost is ${cost}.${preferenceStatus}`;
+    return `${status} it is using ${model} with ${reasoning} reasoning. context usage is ${context}. cumulative cost is ${cost}.${preferenceStatus}`;
 }
 function ensureTerminalPunctuation(text) {
     const trimmed = text.trim();