@markusylisiurunen/tau 0.3.82 → 0.3.83

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

@@ -1,171 +1,182 @@
 # Sessions
 
-A Tau session is the durable home of one conversation and its execution environment. It keeps enough state to continue after detaching or restarting the host, while deliberately leaving short-lived client and process state out. Understanding that boundary makes interruption, recovery, compaction, and remote work predictable.
+A Tau session holds one conversation and the execution environment it works in. It saves enough state to continue after you detach or the host restarts. Short-lived client and process state is not saved. This page explains what is kept, so interruption, recovery, compaction, and remote work behave as you expect.
 
 ## Create a session
 
-Running `tau` creates a fresh local session with the current directory as its execution cwd. The host resolves [configuration](configuration.md), models, [personas](personas.md), [skills](skills.md), prompts, and project context from that execution environment before the first turn.
+Running `tau` creates a new local session whose working directory is the current directory. Before the first turn, the host loads [configuration](configuration.md), models, [personas](personas.md), [skills](skills.md), prompts, and project context from that execution environment.
 
-The session also receives immutable creation attributes. They are bounded string pairs used for provenance and [history](history.md), not mutable runtime settings. Conventional attributes are:
+A session also gets creation attributes, which never change. They are short string pairs that record where the session came from and are used by [history](history.md). They are not settings. Common attributes are:
 
-- `source`, identifying the creating client, such as `tui` or `sdk`.
-- `repository`, using a normalized `host/owner/repository` value. Composite workspaces use comma-delimited repository values.
+- `source`: the client that created the session, such as `tui` or `sdk`.
+- `repository`: a normalized `host/owner/repository` value. Composite workspaces use a comma-separated list.
 
-For a local TUI, Tau can derive `repository` before creation because that client directly manages the local execution environment. A remote host does not inspect an execution path to infer attributes. Remote TUI creation supplies `source: "tui"`; SDK and protocol clients should provide complete authoritative attributes themselves.
+A local TUI can fill in `repository` before creating the session, because it manages the local execution environment directly. A remote host never inspects a path to work out attributes. The remote TUI sends `source: "tui"`. SDK and protocol clients should send complete attributes themselves.
 
-A session’s execution-environment identity and cwd are fixed at creation. `/new` creates another session in the same environment with the current persona and reasoning settings. It does not clear or reuse the existing session.
+A session's execution environment and working directory are fixed when it is created. `/new` creates another session in the same environment, with the current persona and reasoning settings. The existing session is kept, unchanged.
 
 ## Know what owns the session
 
-Three components can be physically colocated but remain logically separate:
+Three parts can run on one machine but stay separate:
 
-- The TUI or SDK client submits input, observes updates, and may provide client-local tools.
-- The session host orchestrates turns, resolves credentials, persists sessions, and supervises execution environments.
-- The execution environment owns the agent-visible cwd, files, repository, project configuration, commands, platform, and runtime tools.
+- The TUI or SDK client sends input, receives updates, and may offer client tools.
+- The session host runs turns, resolves credentials, saves sessions, and manages execution environments.
+- The execution environment holds the agent's working directory, files, repository, project configuration, commands, platform, and tools.
 
-The host persists ordinary sessions under `~/.config/tau/sessions` for the host user. These versioned documents are managed storage, not an editing interface. Never modify them directly. Use Tau’s session operations, normal project configuration, and recovery path instead.
+The host saves sessions under `~/.config/tau/sessions` in the host user's home. These are versioned files that Tau manages. Never edit them directly. Use Tau's session operations, project configuration, and recovery instead.
 
-Session-owned [background Bash jobs](tools.md#bash) survive turns, interruption, and client detach. Running jobs retain an otherwise unobserved live session without blocking new turns. They stop on orderly session disposal or host shutdown, and are not recovered after restart. Crash or forced-kill cleanup is not guaranteed.
+[Background Bash jobs](tools.md#bash) belong to the session. They survive turns, interruption, and clients detaching. A running job keeps a session loaded even when no client is attached, and does not block new turns. Jobs stop when the session is closed normally or the host shuts down, and are not restored after a restart. Cleanup after a crash or forced kill is not guaranteed.
 
 ## Submit, queue, and steer
 
-A normal submission is accepted and persisted before model work begins. Tau then runs model and tool subturns until the turn completes, fails, is blocked, or is interrupted. The model decides when its response is complete; Tau does not automatically start another turn after a final response. Automatic compaction can continue an unfinished turn within a new context window.
+A submitted message is accepted and saved before any model work starts. Tau then runs model calls and tool calls until the turn completes, fails, is blocked, or is interrupted. The model decides when its response is complete, and Tau does not start another turn by itself after a final response. Automatic compaction can continue an unfinished turn in a new context window.
 
-Only one logical turn runs at a time. Input sent during active work has two useful delivery modes:
+Only one turn runs at a time. While work is running, there are two ways to send more input:
 
-- A queued message waits for the session to become idle, then starts an independent turn.
-- Steering joins the active logical turn at a safe continuation boundary.
+- A queued message waits until the session is idle, then starts its own turn.
+- Steering joins the running turn at the next safe point.
 
-In the TUI, Enter steers and Ctrl+Enter queues while work is active. When idle, either starts a normal turn. Pending messages are visible to every observer of the same live hosted session. Alt+Up cancels queued messages and steering that has not been applied and restores the text to the editor.
+In the TUI, Enter steers and Ctrl+Enter queues while work is running. When idle, both start a normal turn. Pending messages are visible to every client attached to the same live session. Alt+Up cancels queued messages and steering that has not been applied yet, and puts the text back in the editor.
 
-A turn captures its model, persona, reasoning, system prompt, tools, retry policy, and compaction policy when it starts. Tool subturns and steering continuations keep that captured specification even if reasoning or host configuration changes meanwhile. A queued turn captures the then-current specification when it later starts.
+A turn fixes its model, persona, reasoning, system prompt, tools, retry policy, and compaction policy when it starts. Tool calls and steering within the turn keep these, even if reasoning or host configuration changes meanwhile. A queued turn uses the settings current when it actually starts.
 
-Pending queue and steering state survives client detach only while the hosted session remains alive in memory. It is not part of durable recovery and starts empty after a host restart.
+Queued and steering messages survive a client detaching only while the session stays loaded on the host. They are not saved and are empty after a host restart.
 
 ## Interrupt and retry
 
-Ordinary session interruption is cooperative. It requests cancellation of the main session’s active turn, all direct executions, isolated model samples, and maintenance work. An interrupted turn records an interrupted assistant result where one exists. It does not stop independently running supervised subagents; select one with Alt+Down and use Ctrl+G, or call `session.interruptSubagent` from a protocol client. Host shutdown or session disposal cleans up those child runtimes. In the TUI, Escape interrupts client-local foreground work such as diff review, recording, or speech playback before requesting main-session interruption from the host.
+Interruption asks work to stop. It cancels the main session's running turn, direct commands, standalone model calls, and maintenance work. An interrupted turn records an interrupted assistant result where there is one. Interruption does not stop subagents: select one with Alt+Down and press Ctrl+G, or call `session.interruptSubagent` from a protocol client. Host shutdown or session disposal stops subagents. In the TUI, Escape first stops local work such as diff review, recording, or speech playback, and only then asks the host to interrupt the session.
 
-Retry runs another assistant turn from the current session history. It does not remove the interrupted or failed result, rewind context, or submit the previous user text again. This lets Tau continue from completed tool results without automatically rerunning them. In the TUI, press Enter twice on an empty editor while idle.
+Retry runs another assistant turn from the current history. It does not remove the interrupted or failed result, rewind context, or send the previous user text again. Tau can therefore continue from completed tool results without running those tools again. In the TUI, press Enter twice on an empty editor while idle.
 
-Retry is unavailable when there is no prior user turn.
+Retry is unavailable when there is no earlier user turn.
 
-Detaching is not the same as interrupting. Closing one observer of a long-running host leaves the hosted turn running. By contrast, a local TUI owns its in-process host, so closing it causes that host to shut down and interrupt active work. See [remote sessions](remote-sessions.md).
+Detaching is not interrupting. Closing one client of a long-running host leaves the turn running. A local TUI, however, owns its in-process host, so closing it shuts that host down and interrupts running work. See [remote sessions](remote-sessions.md).
 
-## Change persona and reasoning safely
+## Change persona and reasoning
 
-The selected persona and reasoning level are durable session settings.
+The persona and reasoning level are saved session settings.
 
-Persona changes require idle state because they rebuild the effective model, system instructions, skills, and tools from the execution environment’s current configuration. In the TUI, use `/persona:<id>` or Ctrl+P.
+A persona change requires an idle session, because it rebuilds the model, system instructions, skills, and tools from the execution environment's current configuration. In the TUI, use `/persona:<id>` or Ctrl+P.
 
-Reasoning can be changed while work is active. The current turn keeps its captured reasoning, while the next independently started or queued turn uses the new setting. Use Shift+Tab in the TUI.
+Reasoning can change while work is running. The running turn keeps its reasoning, and the next turn uses the new setting. In the TUI, use Shift+Tab.
 
-After a host restart, recovery resolves current runtime configuration so providers and model definitions remain usable, then reapplies the session’s persisted persona and reasoning settings where possible. The effective recovered bootstrap can change when the current installation or model catalog has changed, but the session’s committed semantic content remains the recovery source of truth.
+After a host restart, recovery loads the current configuration so providers and models work, then reapplies the session's saved persona and reasoning where possible. The result can differ from before if the installation or model catalog has changed. The saved conversation stays the same.
 
 ## Detach, reattach, and recover
 
-A session is persisted throughout its lifetime, not only when the TUI exits. Reattaching to a live host returns the current state and continues receiving updates. Reattaching after host restart loads the stored session and restores its execution environment through a configured resolver.
+A session is saved throughout its life, not only when the TUI exits. Reattaching to a running host returns the current state and continues with live updates. Reattaching after a host restart loads the saved session and reconnects its execution environment, using the host's configuration for that environment type.
 
-Recovery preserves user-visible durable state including:
+Recovery keeps:
 
-- committed conversation messages and terminal tool results
-- current persona and reasoning settings
-- cumulative usage cost and context accounting needed for continuation
-- execution-environment identity, cwd, and creation attributes
-- compaction and rewind results
+- the conversation messages and finished tool results
+- the persona and reasoning settings
+- the total cost so far, and the context accounting needed to continue
+- the execution environment, working directory, and creation attributes
+- the results of compaction and rewind
 
-Recovery intentionally does not recreate every live process. It returns the session idle, settles any accepted but unfinished turn as aborted, cancels running maintenance operations, and normalizes tools whose completion cannot be proven. Supervised subagents and their live activity do not survive restart.
+Recovery does not restart live processes. The session comes back idle. A turn that was accepted but not finished is recorded as aborted, running maintenance is cancelled, and tools whose outcome is unknown are marked as such. Subagents and their activity do not survive a restart.
 
-A stored session is listed or recovered only when the current host has a resolver capable of restoring its execution-environment kind and named target. Recovery can therefore fail even when the session document is valid, for example when a Cloudflare bridge was removed, a Fly API target is no longer configured, or the underlying sandbox, Sprite, directory, or credentials are unavailable.
+The host lists or recovers a saved session only if it can reconnect that session's execution environment type and target. Recovery can therefore fail for a valid session, for example when a Fly Sprite connection is no longer configured, or when the Sprite, directory, or credentials are no longer available.
 
-Newer Tau versions preserve the openability of supported stored sessions through storage migrations and recovery normalization. This promises access to recoverable semantic data, not byte-for-byte files or identical historical presentation. A genuinely newer unsupported storage version or corrupted document can still be rejected.
+Newer Tau versions can open saved sessions from supported older versions. The conversation and other important data stay available, but the files may be rewritten and old content may display differently. Tau rejects corrupted sessions, and sessions saved by a newer Tau version that it does not support.
 
 ## Compact model context
 
-Compaction replaces model-visible conversation context with a checkpoint so the same session can continue within the model’s context window. It changes active model context, not the independent searchable transcript.
+Compaction replaces the conversation the model sees with a summary, called a checkpoint, so the session can continue within the model's context window. It changes only what the model sees. Searchable history is not affected.
 
-The working model creates the checkpoint from its native conversation context, including the base instructions, previous checkpoint, and reasoning state supported by its provider. The checkpoint covers the whole active context and does not depend on knowing which recent messages will remain. It is an isolated maintenance request with no tool execution, not a submitted user turn. Reasoning continuity depends on the provider; the checkpoint records useful conclusions and rationale rather than reproducing internal thinking.
+The session's model writes the checkpoint from its own view of the conversation, including the base instructions, any earlier checkpoint, and reasoning state where the provider supports it. The checkpoint covers the whole context and does not depend on which recent messages will be kept. It is written in a separate maintenance request that runs no tools and is not a user turn. How much reasoning carries over depends on the provider. The checkpoint records useful conclusions and their reasons instead of reproducing the model's internal thinking.
 
-The summary is intended to support both immediate continuation and recognition of earlier work. Recent and unfinished work receives the most detail; older work is compressed into its purpose, outcomes, and significant decisions. Across repeated compactions, the agent integrates the previous summary with newer conversation rather than discarding topics solely because they are old or completed. Important ongoing constraints retain precision regardless of age. Compaction is lossy: this cumulative overview does not preserve every topic or detail indefinitely.
+The summary aims both to let work continue right away and to keep earlier work recognizable. Recent and unfinished work gets the most detail. Older work is reduced to its purpose, results, and important decisions. Across repeated compactions, the model merges the previous summary with the newer conversation, and does not drop topics just because they are old or finished. Important constraints stay precise however old they are. Compaction still loses information: over time, not every topic or detail survives.
 
 ### Automatic compaction
 
-Automatic compaction runs before a model subturn when fresh provider usage plus newly added estimated context exceeds the threshold. The threshold is the model context window minus a fixed reserve of 16,384 tokens. Checkpoint generation inherits the normal model stream settings without a compaction-specific output limit. Requests whose input cannot fit fail rather than falling back to a flattened transcript. Compaction can run more than once during a long logical turn.
+Automatic compaction runs before a model call when the provider's latest token count, plus an estimate for content added since, exceeds the threshold. The threshold is the model's context window minus a fixed reserve of 16,384 tokens. Writing the checkpoint uses the normal model settings, with no special output limit.
 
-The compaction summary describes the conversation, completed work, findings, and remaining work without copying large user messages or tool output verbatim. It can identify details to revisit in the transcript archive and explain why they matter. Tau retains a contiguous recent suffix within a budget of 20,000 estimated tokens, capped by the compaction threshold. Cuts can occur within a user turn, but messages are kept whole and an assistant tool-call message stays together with all its results. Retained messages, including tool-recovery messages, are not truncated. Tau does not skip an oversized exchange to fill unused budget with earlier messages. If the latest exchange cannot fit, only the checkpoint remains. Tau records the compaction as a new active context segment.
+For both automatic and manual compaction, Tau checks that the request fits, using a valid token count from the provider plus estimates for new content and the summary instruction. Without a valid count, it estimates the whole request. If the request cannot fit, compaction fails; Tau never falls back to sending a flattened transcript. Compaction can run several times during one long turn.
 
-Before replacing context, Tau makes a best-effort transcript archive in the execution environment’s temporary directory. Each automatic compaction adds a numbered `.txt` and `.json` pair under a directory isolated by agent id. The text file supports bounded search and truncates large tool results; the JSON file retains the archived content without those tool-result truncations, excluding assistant thinking. A private `README.md` in the same directory describes the formats and adaptable lookup examples. The continuation message includes all three exact paths when archiving succeeds.
+The summary describes the conversation, completed work, findings, and remaining work, without copying long user messages or tool output word for word. It can point to details worth looking up in the transcript archive and say why they matter.
 
-These files recover details removed from the current session’s model context. The `history` tool instead queries a separate host-owned transcript collection, which may be remotely replicated, stale, truncated, or unavailable, and its transcript entry ids do not identify archive records. The continuation message identifies the execution-environment archive as the recovery source for compacted context.
+Tau keeps the most recent messages, without gaps, within a budget of 20,000 estimated tokens, and never more than the compaction threshold:
 
-The continuation includes the complete archive guide directly, so the agent does not need a separate file read before resuming. The guide also remains available on disk. Its retrieval guidance favors bounded access by known entry id or distinctive evidence, with a concise chronological overview as an optional discovery step. Earlier numbered pairs can contain details that predate the current compaction. Tau does not generate or require a fixed overview projection.
+- The cut can fall inside a user turn, but messages are kept whole, and an assistant message with tool calls stays together with all its results.
+- Kept messages, including tool-recovery messages, are never truncated.
+- Tau does not skip a large exchange to fit earlier messages into the remaining budget.
+- If the latest exchange does not fit, only the checkpoint remains.
 
-These archives are temporary recovery aids, not backups. Archive failure does not block compaction, and execution-environment cleanup may remove them.
+Tau records the compaction as the start of a new context segment.
+
+Before replacing the context, Tau tries to save a transcript archive in the execution environment's temporary directory. Each automatic compaction adds a numbered `.txt` and `.json` pair, in a directory specific to the agent. The text file is meant for searching, with large tool results shortened. The JSON file keeps the full tool results, but not assistant thinking. A `README.md` in the same directory describes both formats, with example lookups. When archiving succeeds, the continuation message includes all three paths.
+
+These files hold details removed from the session's model context. The `history` tool is different: it searches a separate collection on the host, which may be copied to a remote service, out of date, truncated, or unavailable, and its entry IDs do not match archive records. The continuation message names the archive as the place to recover compacted details.
+
+The continuation message includes the full archive guide, so the agent can continue without reading the file first. The guide also stays on disk. It recommends looking up entries by known ID or distinctive text, with a short chronological overview as an optional first step. Earlier numbered pairs can hold details from before the current compaction.
+
+Archives are temporary recovery aids, not backups. If archiving fails, compaction still runs, and the execution environment may delete archives during cleanup.
 
 ### Intermediate system instructions
 
-Tau supports plain-text system instructions in conversation history separately from the persona/base prompt. These records are hidden in the TUI, persisted for recovery, recorded as system entries in searchable transcript history, and sent to the model in conversation order. The initial persona/base prompt is not recorded in transcript history. Providers that cannot represent intermediate system messages may fold their instructions into the leading prompt through the model adapter.
+Besides the persona's base prompt, the conversation history can contain plain-text system instructions. The TUI hides them. They are saved with the session, recorded as system entries in searchable history, and sent to the model in conversation order. The persona's base prompt is never recorded in history. Providers that do not support system messages in the middle of a conversation may receive these instructions merged into the leading prompt.
 
-Compaction treats ordinary intermediate instructions as historical context: their relevant consequences can enter the summary, while instructions in the retained recent tail remain unchanged. The persona/base prompt is supplied separately and is not replaced by the summary. Structured continuation metadata identifies obsolete compaction guidance, which is excluded from both summarization and retained context. Instructions needing exact long-lived preservation must be regenerated or retained by their owning feature rather than relying on system-role authority alone. Rewind removes intermediate instructions after the selected boundary.
+Compaction treats these instructions as part of the history: what they caused can enter the summary, and instructions among the kept recent messages stay unchanged. The base prompt is sent separately and is never replaced by the summary. Instructions that only guided an earlier compaction are left out of both the summary and the kept messages. An instruction that must survive exactly for a long time cannot rely on being a system message; the feature that added it must add it again or keep it some other way. Rewind removes these instructions along with everything after the rewind point.
 
-Existing hidden `<system>` blocks and instruction producers are unchanged. Native system-message support does not promote user-authored tags into privileged instructions.
+A `<system>` block written by a user never becomes a system instruction (see [prompts and project context](prompts-and-project-context.md)).
 
 ### Manual compaction
 
-Manual compaction requires idle state and summarizes the whole active model history rather than retaining an automatic recent tail.
+Manual compaction requires an idle session. It summarizes the whole conversation and keeps no recent messages.
 
 ```text
 /compact-all preserve the deployment constraints
 ```
 
-`/compact-all` replaces context with the generated summary. `/compact-keep-last` also asks the summary to include the prior last assistant response verbatim when one is available. Text after either command is optional guidance to the compaction model, not a new conversation turn.
+`/compact-all` replaces the context with the summary. `/compact-keep-last` also asks the summary to include the last assistant response word for word, when there is one. Text after either command is optional guidance for the summary, not a new message in the conversation.
 
-A failed, skipped, or interrupted compaction leaves the previous context active. Manual compaction does not create the automatic pre-compaction archive.
+If compaction fails, is skipped, or is interrupted, the previous context stays. Manual compaction does not save a transcript archive.
 
 ## Rewind deliberately
 
-`/rewind` opens a picker of eligible user messages. Selecting one removes that selected message and everything after it from the active session, then returns the selected text to the editor so it can be revised and resubmitted.
+`/rewind` opens a list of user messages you can return to. Selecting one removes that message and everything after it from the session, and puts the selected text back in the editor so you can change and resend it.
 
-Rewind requires the session to be idle with no pending submissions. It truncates messages, tool state, turn outcomes, and searchable transcript entries from the selected boundary onward. It is not a display-only operation and has no built-in undo. If the intent is merely to correct course without deleting history, submit a new message or steer the active turn instead.
+Rewind requires an idle session with no pending messages. It removes messages, tool state, turn results, and searchable history entries from that point on. It cannot be undone. To change direction without deleting anything, send a new message or steer the running turn instead.
 
-Compaction and rewind differ in an important way: compaction preserves the flat transcript history, while rewind truncates it to match the chosen session boundary.
+Compaction keeps searchable history, while rewind cuts it back to the rewind point.
 
 ## Reload session content
 
-Run `/reload` from the TUI while the session is idle. The host rereads runtime configuration and personas, prompts, skills, and AGENTS.md context from the execution environment cwd. It keeps the current persona if that id still exists and otherwise selects the first available persona. Reload warnings appear in the transcript.
+Run `/reload` in the TUI while the session is idle. The host reads configuration, personas, prompts, skills, and `AGENTS.md` context again from the session's working directory. It keeps the current persona if its ID still exists, and otherwise selects the first available persona. Warnings appear in the transcript.
 
-Reload updates future turns. It does not rewrite committed conversation content or change the execution environment. It also does not reload client-owned themes, diff launchers, speech settings, or client tools. Restart the attaching TUI for those. Effective configured model `apiKeys` update through `/reload`, while managed Codex auth storage is read again on later credential resolutions. Restart the host for changed process environment variables, listener settings, resolver targets, or the Tau binary. [Credentials](credentials.md) has the canonical distinctions, and [remote sessions](remote-sessions.md) identifies each owner.
+Reload affects later turns. It never changes the saved conversation or the execution environment. It does not reload anything owned by the client, such as themes, speech settings, or client tools; restart the TUI for those. Codex auth storage is read again on every new request. Restart the host after changing its environment variables, `apiKeys`, listener settings, hosted environment settings, or the Tau version. [Credentials](credentials.md) and [remote sessions](remote-sessions.md) describe where each setting belongs.
 
-Protocol clients can request mutations directly, but should still wait for idle state. Mutating operations can interrupt current work and reject pending messages so the session reaches one canonical configuration.
+Protocol clients can request changes directly, but should still wait for an idle session. Some changes interrupt running work and reject pending messages, so the session ends up with one consistent configuration.
 
-## Session state and transcript history are different
+## Session state and searchable history
 
-Tau keeps two durable views for different jobs:
+Tau keeps two separate records for different purposes:
 
-- The session snapshot is the recoverable source of truth for continuing one conversation. It contains the current active model context and user-visible session state.
-- Transcript history is a flat sequence of committed user entries, intermediate system instructions, assistant text, and completed tools used for cross-session search and reading. It is stored separately in the host’s history database and may also replicate to a configured history service.
+- The saved session is what Tau uses to continue one conversation. It contains the model's current context and the session state you see.
+- Searchable history is a flat list of user messages, intermediate system instructions, assistant text, and finished tool calls, used to search and read across sessions. It is stored in the host's history database and can also be copied to a configured history service.
 
-Compaction changes the session snapshot’s active context but leaves transcript history intact. Rewind truncates both from the removed boundary. Transcript history cannot reconstruct all session runtime state and is not used to recover a session. See [history](history.md) for storage, replication, and the history tool.
+Compaction changes the saved session's model context but leaves searchable history as it was. Rewind cuts both back to the rewind point. History cannot rebuild a session and is never used to recover one. See [history](history.md) for storage, replication, and the history tool.
 
 ## Inspect model usage
 
-Tau writes host-owned usage records to daily `~/.config/tau/logs/usage-YYYY-MM-DD.jsonl` files under the host user’s home. Records cover finalized assistant model responses from main sessions, supervised subagents, and ephemeral threads. They include timestamps and session, persona, provider, model, reasoning, and agent attribution, plus input, output, cache-read, cache-write, total-token, and Tau-recorded cost values. They do not contain prompt or response text and are separate from session snapshots and transcript history.
+Tau writes usage records on the host to daily files, `~/.config/tau/logs/usage-YYYY-MM-DD.jsonl`, in the host user's home. Each record is one finished model response from a main session, subagent, or ephemeral thread. Records include the time, the session, persona, provider, model, reasoning, and agent, and the input, output, cache-read, cache-write, and total tokens with Tau's cost estimate. They do not contain prompt or response text, and they are separate from saved sessions and searchable history.
 
-Run the summary command as the user who runs the host:
+Run the summary command as the user that runs the host:
 
 ```sh
 tau usage
 ```
 
-It groups by day by default and prints request count, each token category, total tokens, cost, and an overall total. The supported options are:
+By default it groups by day and prints the request count, each token category, total tokens, cost, and an overall total. The options are:
 
 | Option | Behavior |
 | --- | --- |
-| `--since <date>` | Include entries on or after an inclusive `YYYY-MM-DD` or ISO date. |
+| `--since <date>` | Include entries on or after a `YYYY-MM-DD` or ISO date. |
 | `--persona <id>` | Match an exact persona id, case-insensitively. |
 | `--provider <name>` | Match an exact provider, case-insensitively. |
 | `--model <id>` | Match an exact model id, case-insensitively. |
-| `--group-by day\|model` | Group by calendar day or by `provider/model`; the default is `day`. |
+| `--group-by day\|model` | Group by calendar day or by `provider/model`. The default is `day`. |
 | `--help`, `-h` | Show the command help. |
 
 Filters can be combined:
@@ -174,36 +185,36 @@ Filters can be combined:
 tau usage --since 2026-08-01 --provider openai-codex --group-by model
 ```
 
-There is no `--until`, `--session`, or `--agent` filter. For a remote session, run `tau usage` on the host under the same user as `tau serve`; running it on an attaching client reads that client user’s logs instead. The command is read-only, but the raw files still reveal timestamps, session identifiers, model choices, token volume, and cost activity. Prefer the filtered aggregate output over copying raw JSONL into a shared transcript, and treat Tau-recorded costs as operational estimates rather than a provider invoice.
+There is no `--until`, `--session`, or `--agent` filter. For a remote session, run `tau usage` on the host as the user that runs `tau serve`. Running it on an attached client reads that client user's logs instead. The command only reads, but the raw files still show times, session IDs, model choices, token volumes, and costs. Share the filtered summary instead of raw JSONL, and treat Tau's costs as estimates, not an invoice.
 
-## What survives each boundary
+## What survives each event
 
-| Event | Durable session state | Pending input | Active turns and subagents | Client-local state |
+| Event | Saved session | Pending messages | Running turns and subagents | Client state |
 | --- | --- | --- | --- | --- |
-| Another client detaches from a live WebSocket host | Preserved | Preserved in host memory | Continue | Detached client tools, themes, drafts, and local tasks are lost |
-| Local TUI exits | Persisted by owned-host shutdown | Cancelled | Interrupted and settled where possible | Lost |
-| WebSocket host restarts | Recovered from storage | Lost | Returns idle; subagents are not restored | Each client reconnects separately |
-| TUI restarts while host stays live | Preserved | Preserved in host memory | Continue | Reloaded from the new client process |
-| `/new` | Old session remains stored | Not copied | New idle session | Same TUI process continues |
+| Another client detaches from a running WebSocket host | Kept | Kept in host memory | Continue | That client's tools, themes, drafts, and local tasks are gone |
+| Local TUI exits | Saved as its host shuts down | Cancelled | Interrupted and recorded where possible | Lost |
+| WebSocket host restarts | Recovered from storage | Lost | Session returns idle; subagents are not restored | Each client reconnects on its own |
+| TUI restarts while the host keeps running | Kept | Kept in host memory | Continue | Loaded again by the new client process |
+| `/new` | Old session stays saved | Not copied | New idle session | Same TUI process continues |
 
-An unsent editor draft belongs only to the TUI. Use Ctrl+S to move it to the local clipboard before restarting a client.
+An unsent draft exists only in the TUI. Press Ctrl+S to copy it to the clipboard before restarting a client.
 
-## Verify a recovered session safely
+## Check a recovered session
 
-Use normal Tau operations rather than opening or editing session files.
+Use normal Tau operations, not the session files.
 
-1. Wait for active work to finish or interrupt it intentionally.
-2. Note the session id shown in the TUI startup block.
+1. Wait for running work to finish, or interrupt it.
+2. Note the session ID shown at the top of the TUI.
 3. Exit cleanly and reattach through the same host.
-4. Confirm the expected messages, persona, and reasoning level.
-5. Run non-contextual environment checks with `!!`, for example `!!pwd` and `!!git status --short`.
-6. Submit a small read-only request before resuming destructive work.
+4. Confirm the messages, persona, and reasoning level.
+5. Check the environment without adding to the context using `!!`, for example `!!pwd` and `!!git status --short`.
+6. Send a small read-only request before continuing with work that changes things.
 
-For a local stored session, start a WebSocket host under the same user and attach from another terminal:
+To reopen a saved local session, start a WebSocket host as the same user and attach from another terminal:
 
 ```sh
 tau serve
 tau attach --session 0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3 ws://127.0.0.1:8787
 ```
 
-If recovery fails, verify the host version, execution-environment resolver configuration, target availability, and credentials before assuming the stored session is damaged. [Remote sessions](remote-sessions.md) covers those checks.
+If recovery fails, check the host version, the hosted environment configuration, whether the target is available, and credentials before assuming the session is damaged. [Remote sessions](remote-sessions.md) covers those checks.

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

@@ -1,8 +1,13 @@
 # Skills
 
-Skills are local packages of instructions and supporting material that teach an agent how to handle a particular kind of work. Tau discovers them from the execution environment, shows all discovered skills to every persona, and lets the agent open a skill only when the task calls for it.
+A skill is a directory of instructions and supporting files that teaches an agent how to handle one kind of work. Tau finds skills on the execution environment and lists all of them for every persona. The agent opens a skill only when the task calls for it.
 
-A skill is not a prompt template, a persona, or project context. A [prompt template](prompts-and-project-context.md) is text placed in the input editor. A [persona](personas.md) chooses the model, system prompt, and tools for a session. `AGENTS.md` gives standing instructions for a directory tree. A skill is a reusable, selectively activated workflow with its own directory.
+Skills differ from Tau's other content:
+
+- A [prompt template](prompts-and-project-context.md) is text you insert into the input editor.
+- A [persona](personas.md) chooses the model, system prompt, and tools for a session.
+- `AGENTS.md` gives standing instructions for a directory tree.
+- A skill is a reusable workflow that the agent loads only when it applies.
 
 ## Where Tau discovers skills
 
@@ -13,9 +18,9 @@ Tau looks for skill directories at global and project levels:
 | Global | `~/.config/tau/skills/<name>/SKILL.md` and `~/.agents/skills/<name>/SKILL.md` |
 | Project | `<level>/.tau/skills/<name>/SKILL.md` and `<level>/.agents/skills/<name>/SKILL.md` |
 
-The global level is in scope only when the session working directory is inside the execution environment's home directory. For project discovery, Tau walks from the working directory toward home, or toward the filesystem root when the working directory is outside home. A directory participates as a project level when it contains `.tau/` or `.agents/skills/`.
+The global level applies only when the session's working directory is inside the execution environment's home directory. For project levels, Tau searches from the working directory up to home, or up to the filesystem root when the working directory is outside home. A directory counts as a project level when it contains `.tau/` or `.agents/skills/`.
 
-Skills are keyed by name. Precedence runs from broadest to most specific:
+Skills are identified by name. When two levels define the same name, the more specific one wins:
 
 1. Global skills are the base layer.
 2. Parent project levels override global and more distant parent levels.
@@ -32,11 +37,11 @@ For example, with a session in `~/code/atlas/apps/api`, these definitions of `re
 
 `~/.config/tau/skills/` also overrides `~/.agents/skills/` for a same-named global skill.
 
-All discovery happens in the execution environment. A remote host does not inspect the attached client's filesystem for skills.
+Discovery happens only on the execution environment. Skills on an attached client's machine are never used.
 
 ## The skill directory contract
 
-Each skill is a directory containing an exact uppercase `SKILL.md` filename:
+Each skill is a directory that contains a file named exactly `SKILL.md`, in uppercase:
 
 ```text
 .tau/skills/release-check/
@@ -49,7 +54,7 @@ Each skill is a directory containing an exact uppercase `SKILL.md` filename:
     └── checklist.txt
 ```
 
-Only `SKILL.md` is required. `references/`, `scripts/`, and `assets/` are conventional optional directories, not separately registered content. The instructions in `SKILL.md` decide when and how to use them. Paths mentioned by a skill are relative to the skill directory unless the skill says otherwise.
+Only `SKILL.md` is required. `references/`, `scripts/`, and `assets/` are optional directories by convention; Tau does not treat them specially. The instructions in `SKILL.md` say when and how to use them. Paths in a skill are relative to the skill directory unless the skill says otherwise.
 
 `SKILL.md` starts with YAML frontmatter followed by Markdown instructions:
 
@@ -68,7 +73,7 @@ allowed-tools: bash, view_image
 Check the release branch, run the repository verification commands, and report only blocking failures.
 ```
 
-The frontmatter contract is:
+The frontmatter fields are:
 
 | Field | Requirement |
 | --- | --- |
@@ -77,15 +82,15 @@ The frontmatter contract is:
 | `license` | Optional non-empty string. |
 | `compatibility` | Optional non-empty string of at most 500 characters. |
 | `metadata` | Optional map whose keys and values are strings. |
-| `allowed-tools` | Optional non-empty string. It is accepted for skills-format compatibility but currently ignored by Tau. |
+| `allowed-tools` | Optional non-empty string. Accepted so that skills written for other tools load, but Tau ignores it. |
 
-Unknown frontmatter fields are discarded. `allowed-tools` does not enable, disable, or restrict any tool. Tool availability comes from the active persona; subagents inherit its eligible tools. See [tools](tools.md) and [subagents](subagents.md).
+Unknown frontmatter fields are ignored. `allowed-tools` does not enable, disable, or restrict any tool. Tools come from the active persona, and subagents inherit the eligible ones. See [tools](tools.md) and [subagents](subagents.md).
 
-Keep the description useful without copying the full workflow into it. Tau initially exposes the name, description, and `SKILL.md` path. The agent opens the file after activation, then reads only the referenced resources needed for the task.
+Keep the description short and useful, without the full workflow. Until a skill is activated, the agent sees only its name, description, and `SKILL.md` path. After activation the agent opens the file and reads only the referenced files the task needs.
 
 ## Skill availability
 
-Every persona exposes all discovered skills. Discovery does not run a skill on every turn; it makes the skill available to the agent under its activation policy.
+Every persona can use all discovered skills. A discovered skill does not run on every turn. The agent activates it according to its trigger sensitivity.
 
 ## Activation and trigger sensitivity
 
@@ -95,7 +100,7 @@ A skill declares trigger sensitivity in its `description`. The supported policy
 - **balanced**: activate when the request clearly matches the skill. This is the default when no trigger is stated.
 - **explicit**: activate only when the skill is explicitly named by an active instruction.
 
-Use a clear phrase such as `Trigger: eager.`, `Trigger: balanced.`, or `Trigger: explicit.` in the description. Trigger sensitivity is an agent-facing convention carried by the description, not a separate frontmatter field.
+Put a clear phrase such as `Trigger: eager.`, `Trigger: balanced.`, or `Trigger: explicit.` in the description. There is no separate frontmatter field; the agent reads the policy from the description.
 
 An exact skill reference has this form:
 
@@ -105,26 +110,26 @@ An exact skill reference has this form:
 
 A reference in the current user request, active `AGENTS.md` instructions, or an already-active skill explicitly activates that skill. Generic wording or a coincidental keyword does not activate an explicit skill.
 
-Skill references compose. If `release-check` instructs the agent to use `@@skill:dependency-audit`, Tau's activation policy allows the second skill to activate transitively. Each skill activates at most once per request, so repeated references and cycles do not reopen it.
+A skill can activate another skill. If `release-check` tells the agent to use `@@skill:dependency-audit`, that second skill activates too. Each skill activates at most once per request, so repeated references and cycles do not open it again.
 
-After activation, the agent reads `SKILL.md` from the path in the discovered index. It should load only relevant files from `references/` or `assets/`, and prefer provided scripts when they implement the required workflow. Skills are treated as read-only unless the user explicitly asks to edit them.
+After activation, the agent reads `SKILL.md` from the listed path. It loads only the relevant files from `references/` or `assets/`, and uses the skill's scripts when they do what the workflow needs. The agent does not edit skills unless the user explicitly asks.
 
 ## Applying changes and checking discovery
 
-A running TUI session keeps its current content catalog and prompt context until it reloads. Run:
+A running session keeps its current skills and prompt context until it reloads. Run:
 
 ```text
 /reload
 ```
 
-Reloading re-discovers skills and rebuilds the effective skill index. Tau refuses to reload while a session turn is running. If the active persona disappeared, reload selects the first available persona; if no personas remain, reload fails.
+Reload finds skills again and rebuilds the list the agent sees. Tau refuses to reload while a turn is running. If the active persona no longer exists, reload selects the first available persona. If no personas remain, reload fails.
 
-For a new local TUI session, `tau --debug` prints the discovered skills and the effective system prompt without starting the TUI. Combine it with `--persona` to inspect its effective prompt:
+For a new local session, `tau --debug` prints the discovered skills and the system prompt without starting the TUI. Add `--persona` to see the prompt for a specific persona:
 
 ```bash
 tau --debug --persona release-coder
 ```
 
-Invalid skills are skipped and reported as configuration warnings. Common causes are malformed YAML, non-object frontmatter, a missing required field, an invalid name, a directory/name mismatch, an unreadable file, or an unreadable skills directory. A subdirectory without `SKILL.md` is simply not a skill.
+Invalid skills are skipped and reported as configuration warnings. Common causes are malformed YAML, frontmatter that is not an object, a missing required field, an invalid name, a name that differs from the directory name, or a file or skills directory that cannot be read. A subdirectory without `SKILL.md` is not a skill and produces no warning.
 
-When troubleshooting precedence, check the session's execution-environment working directory first. Discovery is based on that path, not necessarily the filesystem where the TUI is running. Broader configuration diagnostics are covered in [troubleshooting](troubleshooting.md).
+When a skill does not resolve as expected, first check the session's working directory on the execution environment. Discovery starts from that path, which may be on a different machine from the TUI. Broader configuration diagnostics are covered in [troubleshooting](troubleshooting.md).

package/dist/core/static/tau_docs/speech-generation.md

@@ -18,11 +18,11 @@ Voice listing prints one JSON object per voice, containing `voice_id` and `name`
 
 ## Models
 
-`--model` is required; the CLI has no implicit default. Use `eleven_v4_turbo` for lower-latency speech, as shown in the examples. Use `eleven_v4` when maximum quality matters more than latency. Both support narration and multi-speaker dialogue.
+`--model` is required; there is no default. Use `eleven_v4_turbo` for lower-latency speech, as shown in the examples. Use `eleven_v4` when maximum quality matters more than latency. Both support narration and multi-speaker dialogue.
 
 ## Input and examples
 
-Supply a UTF-8 JSON document with exactly `voices` and `chunks`. `voices` maps speaker names to voice IDs; `chunks` is an ordered, nonempty array of nonempty arrays of speaker turns. Each turn contains exactly `speaker` and nonblank `text`.
+Give a UTF-8 JSON document with exactly two fields, `voices` and `chunks`. `voices` maps speaker names to voice IDs; `chunks` is an ordered, nonempty array of nonempty arrays of speaker turns. Each turn contains exactly `speaker` and nonblank `text`.
 
 ```json
 {
@@ -68,7 +68,7 @@ Single-speaker narration uses the same shape with one voice. All chunks are vali
 - Each chunk contains at most 2,000 Unicode code points across its text, including whitespace and delivery tags.
 - Every speaker must resolve to a voice. At most 10 distinct voices may be used.
 
-Tau packs consecutive whole chunks into requests of at most 2,000 characters, following the [dialogue endpoint's reliability recommendation](https://elevenlabs.io/docs/api-reference/text-to-dialogue/convert). The caller chooses chunk boundaries; text and turn order are preserved.
+Tau combines consecutive whole chunks into requests of at most 2,000 characters, as the [dialogue endpoint documentation](https://elevenlabs.io/docs/api-reference/text-to-dialogue/convert) recommends for reliability. You choose where chunks break; text and turn order are kept.
 
 ## Conversational assistant replies
 
@@ -152,7 +152,7 @@ The output parent directory must exist. Neither the requested WAV nor `<output>.
 
 Stdout on success is one JSON object with absolute `output`, `artifacts`, and the number of `batches`. The manifest contains the script text; keep artifacts private for sensitive scripts.
 
-Failures exit nonzero and identify invalid script fields, chunks, or turns before generation, or the failed batch and processing stage afterward. Existing output or artifact paths require a fresh `--output` path; preserve recovery artifacts. Errors after output preparation report the retained directory, which may be incomplete. If final publication fails, copy the completed `assembled.wav` to a fresh path instead of generating again. Requests are not automatically retried because a failed request may already have incurred a charge; another generation request may incur another charge.
+Failures exit nonzero. Before generation, the error names the invalid field, chunk, or turn. After it starts, the error names the failed batch and step. If the output or `.parts` path already exists, choose a new `--output` path, and keep the existing files in case you need them. Errors after the output directory is created give its path; it may be incomplete. If only the final copy fails, copy the finished `assembled.wav` to a new path instead of generating again. Requests are never retried automatically, because a failed request may already have been charged, and a new request may be charged again.
 
 To recover after a later batch fails, inspect the manifest's `completed` flags and chunk mapping. Generate only the unfinished chunks to a fresh output path, then assemble the completed PCM files from both runs in script order. Request stitching does not carry over between invocations.
 
@@ -178,4 +178,4 @@ Standard rates from the [ElevenLabs API pricing page](https://elevenlabs.io/pric
 
 Check current API pricing for plan and voice-specific rates. The manifest's `characterCost` preserves the provider's billing header verbatim.
 
-See [command-line tools](tools.md) for command discovery and execution ownership.
+See [command-line tools](tools.md) for the other tools and where commands run.