@markusylisiurunen/tau 0.3.82 → 0.3.83

package/dist/core/static/tau_docs/pdf-unpacking.md

@@ -15,24 +15,24 @@ The command requires `pdftoppm` from Poppler on `PATH`. On macOS, install it wit
 
 ## Input and examples
 
-Supply one readable local PDF path, resolved from the command's current working directory. Quote paths containing spaces:
+Give one local PDF path, relative to the current directory. Quote paths containing spaces:
 
 ```bash
 tau tool pdf-unpack './docs/design review.pdf'
 ```
 
-The command uploads the PDF to Mistral for OCR and renders page-image patches locally. Do not use it for a sensitive document unless sending it to Mistral and retaining derived local artifacts are both permitted.
+The command uploads the PDF to Mistral for OCR and renders page images locally. Use it for a sensitive document only if you may send it to Mistral and keep the extracted files locally.
 
 ## Outputs and recovery
 
-On success, stdout reports the persistent temporary output directory and a complete artifact list. The directory contains:
+On success, stdout prints the output directory, which is temporary but not deleted automatically, and lists every file. The directory contains:
 
 - `document.md`: the complete OCR document with recognized tables inlined.
 - `pages/page-0001.md` and later numbered files: one Markdown file per PDF page.
 - `images/page-0001/patch-0001.png` and later numbered patches: images for visual verification.
 
-OCR text can contain recognition mistakes. Embedded visuals that are not represented in Markdown are marked with placeholders pointing to the corresponding page patches. Read `document.md` for the whole document, use `pages/` for page-level work, and inspect `images/` before trusting or correcting uncertain OCR.
+OCR text can contain mistakes. Images and figures that are not captured in Markdown are marked with placeholders that point to the matching page patches. Read `document.md` for the whole document, use `pages/` for page-level work, and inspect `images/` before trusting or correcting uncertain OCR.
 
-The command attempts to delete the remote upload after OCR. A deletion failure is reported in the command output. Successful local artifacts remain on disk for follow-up use; delete them when they are no longer needed. If processing fails, Tau attempts to remove the partial local output directory. The error identifies the failed stage and reports whether partial output was removed or cleanup failed. Partial output is not a complete result. Failures after the OCR request starts warn that another OCR request may incur another charge.
+After OCR, the command tries to delete the uploaded file from Mistral and reports if that fails. The local output stays on disk; delete it when you no longer need it. If processing fails, Tau tries to remove the partial output directory. The error names the step that failed and says whether the partial output was removed. Partial output is never a complete result. If the failure happens after the OCR request started, the error warns that running the command again may be charged again.
 
-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.

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

@@ -1,12 +1,12 @@
 # Personas
 
-A persona is Tau's complete model-facing working profile. It chooses a provider and model, supplies the base system prompt, sets reasoning and service behavior, and selects tools. Changing persona changes how future turns run without creating a new session.
+A persona defines how the agent works. It chooses a provider and model, supplies the base system prompt, sets reasoning and service tier, and selects tools. Switching persona changes how later turns run, in the same session.
 
-Tau ships generated built-in personas and discovers custom persona Markdown from the execution environment. The effective list is version-specific and scope-specific, so inspect the current catalog rather than relying on a memorized list of names.
+Tau ships built-in personas and loads custom persona files from the execution environment. The available list depends on the Tau version and on where the session runs, so check the current list instead of relying on remembered names.
 
 ## Built-in and effective personas
 
-Built-in personas are generated from Tau's current model catalog. Most model families have separate chat and coder variants; some families expose only the variants Tau supports. Built-ins carry Tau-maintained prompts, defaults, tool selections and subagent supervision tools.
+Built-in personas are generated from Tau's current model catalog. Most model families have separate chat and coder variants, and some have only the variants Tau supports. Built-ins come with Tau's own prompts, defaults, tool selections, and subagent tools.
 
 The Opus 5.5 chat and coder personas are available only when `anthropic/claude-opus-5-5` is present in the effective model catalog. The Sonnet 5.5 variants (`sonnet-5.5-chat` and `sonnet-5.5-coder`) likewise require `anthropic/claude-sonnet-5-5`.
 
@@ -16,18 +16,18 @@ All built-in personas default to medium reasoning. The startup default is `sonne
 
 After a remote catalog refresh, `/reload` adopts the updated catalog for an existing session.
 
-Built-in personas are always included in the catalog. Custom personas can replace a built-in by using the same ID.
+Built-in personas are always included. A custom persona replaces a built-in by using the same ID.
 
-Use one of these to inspect the current effective list:
+To see the current list:
 
 ```sh
 tau --help
 tau --debug
 ```
 
-`tau --debug` also prints full effective prompts and project context. Use it only where that output is appropriate.
+`tau --debug` also prints the full prompts and project context, so be careful where you share its output.
 
-If no personas remain, session creation fails. Reload also fails rather than leaving a running session without a persona.
+If no personas are left, session creation fails. Reload also fails, so a running session never ends up without a persona.
 
 ## Discovery and precedence
 
@@ -36,15 +36,15 @@ Custom persona files are loaded from:
 - `~/.config/tau/personas/<id>.md` when the session `cwd` is inside the execution environment's home;
 - every ancestor `.tau/personas/<id>.md` from the broadest project level to the nearest.
 
-Personas are keyed case-insensitively for overlay precedence. Built-ins form the base, global custom personas override them, and the nearest project definition wins. The `id` inside each file must still exactly match its case-sensitive filename without `.md`.
+Built-ins come first, global custom personas override them, and the nearest project definition wins. IDs are compared case-insensitively when deciding which definition overrides which. The `id` inside a file must still match its filename without `.md` exactly, including case.
 
 For a session in `~/code/ledger/apps/api`, a project file at `~/code/ledger/apps/.tau/personas/release-coder.md` overrides the same ID from `~/code/ledger/.tau/personas/` or `~/.config/tau/personas/`.
 
-These locations belong to the execution environment. An attached TUI does not contribute persona files to a remote session. See [configuration](configuration.md) and [ownership and scope](ownership-and-scope.md).
+These locations are on the execution environment. An attached TUI does not add persona files to a remote session. See [configuration](configuration.md) and [ownership and scope](ownership-and-scope.md).
 
 ## Persona file contract
 
-A persona is Markdown with YAML frontmatter. `id`, `provider`, and `model` are required. A non-empty Markdown body is required and supplies the persona's own base system prompt.
+A persona is a Markdown file with YAML frontmatter. `id`, `provider`, and `model` are required. The Markdown body is required, must not be empty, and becomes the persona's base system prompt.
 
 ```markdown
 ---
@@ -70,7 +70,7 @@ tools:
 Work as a release engineer. Inspect repository policy before changing release state.
 ```
 
-The frontmatter must be a YAML object between valid delimiters. Unknown fields are discarded.
+The frontmatter must be a YAML object between `---` lines. Unknown fields are ignored.
 
 ### Required fields
 
@@ -78,9 +78,9 @@ The frontmatter must be a YAML object between valid delimiters. Unknown fields a
 | --- | --- |
 | `id` | Non-empty persona ID. It must exactly match the filename without `.md`. |
 | `provider` | Non-empty provider ID from the installed [model catalog](models.md). |
-| `model` | Non-empty model ID for that provider. The ID may be unbundled when the provider is known. |
+| `model` | Non-empty model ID for that provider. It may be an ID missing from the catalog, as long as the provider is known. |
 
-Each custom persona is self-contained: it supplies its provider, model, prompt, and optional settings.
+Each custom persona is complete on its own. It does not inherit a provider, model, prompt, or settings from another persona.
 
 ### Optional fields
 
@@ -89,18 +89,20 @@ Each custom persona is self-contained: it supplies its provider, model, prompt,
 | `label` | Display label. A blank or omitted label falls back to `custom`. |
 | `description` | Short catalog description. |
 | `reasoning` | Default effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
-| `serviceTier` | `priority` or `flex`. Currently meaningful for `openai` and `openai-codex`. |
+| `serviceTier` | `priority` or `flex`. Used only by `openai` and `openai-codex`. |
 | `allowedReasoningLevels` | Array of reasoning efforts offered by the TUI selector. |
-| `tools` | Explicit list of persona-controlled tools. |
+| `tools` | List of persona-selectable tools. |
 
-Every persona exposes all discovered skills. If a custom persona omits `tools`, Tau enables the ordinary host tools plus subagent supervision tools. An explicit `tools` list without `spawn_agent` prevents subagent launches. See [skills](skills.md) and [subagents](subagents.md) for those contracts.
+Every persona can use all discovered skills. If a custom persona omits `tools`, Tau enables the standard tools and the subagent tools. A `tools` list without `spawn_agent` prevents the agent from starting subagents. See [skills](skills.md) and [subagents](subagents.md) for those contracts.
 
-The persona-controlled tool names are:
+The selectable tool names are:
 
 - `bash`, `write`, `edit`, `view_image`, `web`, `nook`, `history`, `mcp`, and `models`;
 - `spawn_agent`, `send_input_to_agent`, `wait_for_agents`, `list_agents`, and `interrupt_agent`.
 
-The service selectors enable capabilities within `code`; `bash` also enables `tau.bash`. The `code` tool is assembled automatically from selected eligible capabilities. An explicit `tools` array replaces defaults. Names are normalized to lowercase, duplicates are removed, and unknown names reject the persona. `tools: []` leaves the persona without these persona-controlled tools. Intrinsic `tau_docs` is supplied independently of this list. Listing `nook` does not make it usable without effective Nook configuration. Listing `mcp` requires enabled MCP servers configured on the host. [Tools](tools.md) explains eligibility and ownership.
+Names such as `web`, `nook`, `history`, `mcp`, and `models` enable capabilities inside the `code` tool, and `bash` also enables `tau.bash`. Tau builds the `code` tool from whichever of these capabilities are selected and usable.
+
+A `tools` list replaces the defaults. Names are lowercased and duplicates removed. An unknown name makes the persona invalid. `tools: []` gives the persona none of these tools. The built-in `tau_docs` tool is always available, independent of this list. `nook` works only when Nook is configured, and `mcp` only when the host has enabled MCP servers. [Tools](tools.md) explains eligibility and ownership.
 
 ## Selecting a persona
 
@@ -112,7 +114,7 @@ The service selectors enable capabilities within `code`; `bash` also enables `ta
 }
 ```
 
-The most specific configured `defaultPersona` wins. Startup references are exact and case-sensitive. An unknown configured default produces a warning and Tau falls back to the first effective persona.
+The most specific `defaultPersona` wins. The ID must match exactly, including case. An unknown default produces a warning, and Tau uses the first available persona.
 
 Override the default for one TUI launch:
 
@@ -128,25 +130,25 @@ Inside the TUI, switch while idle with:
 /persona:release-coder
 ```
 
-The TUI resolves that command against the session catalog case-insensitively. `Ctrl+P` cycles effective personas. A persona switch reloads runtime content from the execution environment, selects the requested definition, rebuilds project and skill context, updates the tool registry, and persists the new session settings. The TUI refuses to switch while a turn is running.
+This command matches the ID case-insensitively. `Ctrl+P` cycles through the available personas. A switch reloads configuration and content from the execution environment, applies the new persona, rebuilds project and skill context and the tool set, and saves the new session settings. The TUI refuses to switch while a turn is running.
 
 ## Reasoning and service tier
 
-`reasoning` is the persona's default effort. A startup suffix, the session reasoning command, or `Shift+Tab` can override it. Reasoning changes are allowed while a turn is running, but the active logical turn keeps the complete model and tool specification captured when it began. The new effort applies to the next independently submitted or queued turn.
+`reasoning` is the persona's default effort. A startup suffix, the session reasoning command, or `Shift+Tab` can override it. You can change reasoning while a turn is running, but the running turn keeps the model and tool settings it started with. The new effort applies from the next submitted or queued turn.
 
-`allowedReasoningLevels` controls which values the TUI cycles for that persona. It is a presentation allowlist, not a protocol-level prohibition. When omitted, the TUI offers the standard reasoning enum for a reasoning-capable model. For a model whose catalog entry says `reasoning: false`, the selector resolves to `none`.
+`allowedReasoningLevels` sets which values the TUI cycles through for the persona. It limits only the TUI selector; protocol clients can still set other levels. When it is omitted, the TUI offers all standard levels for a model that supports reasoning. For a model whose catalog entry says `reasoning: false`, the selector shows only `none`.
 
 An empty `allowedReasoningLevels` does not create an empty selector. The TUI uses its normal model-aware choices.
 
-`serviceTier` is passed with supported OpenAI and OpenAI Codex requests. `priority` requests the provider's priority service and `flex` requests flex service. Availability, billing, and rejection behavior remain provider-account concerns. Other providers do not currently use this setting.
+`serviceTier` is sent with OpenAI and OpenAI Codex requests. `priority` requests the provider's priority service, and `flex` requests flex service. Whether the tier is available, how it is billed, and whether requests are rejected depend on your provider account. Other providers ignore this setting.
 
 ## Reloading changes
 
-Run `/reload` while the TUI session is idle after editing personas, skills, or project context. Reload re-discovers the effective catalog and rebuilds the current session prompt and tools.
+After editing personas, skills, or project context, run `/reload` while the session is idle. Reload finds personas again and rebuilds the session's prompt and tools.
 
-If the current persona ID still exists, Tau applies its newly loaded definition. This can reset runtime settings such as reasoning or service tier to the definition's values. If the ID disappeared, Tau selects the first effective persona. Existing session messages remain; changing a persona does not rewrite prior model-facing history.
+If the current persona ID still exists, Tau applies its newly loaded definition. This can reset settings such as reasoning or service tier to the definition's values. If the ID is gone, Tau selects the first available persona. Existing messages stay as they are; a persona change never rewrites earlier history.
 
-A reload does not alter a turn already in progress, and the TUI refuses the operation while one is running. Existing live subagent threads retain the runtime with which they were created; newly spawned subagents inherit the reloaded persona. See [subagents](subagents.md).
+The TUI refuses to reload while a turn is running. Subagents that are already running keep the setup they started with. Subagents started after the reload use the reloaded persona. See [subagents](subagents.md).
 
 ## Validation and common mistakes
 
@@ -159,4 +161,4 @@ An invalid persona is skipped and reported as a configuration warning. Other val
 - an invalid reasoning effort or service tier;
 - an unknown persona tool.
 
-`/reload` surfaces warning paths directly in the transcript. For a new local TUI session, `tau --debug --persona <id>` shows the selected model, settings, skills, subagents, tools, and complete effective prompt. If a remote edit appears to have no effect, confirm the session execution environment and `cwd` before changing another copy of the file. [Troubleshooting](troubleshooting.md) covers that check in more detail.
+`/reload` shows warnings, with file paths, in the transcript. For a new local session, `tau --debug --persona <id>` shows the selected model, settings, skills, subagents, tools, and the complete prompt. If an edit seems to have no effect in a remote session, confirm the session's execution environment and `cwd` before editing another copy of the file. [Troubleshooting](troubleshooting.md) covers that check in more detail.

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

@@ -1,12 +1,16 @@
 # Prompts and project context
 
-Tau has several ways to provide instructions or reusable text, and they enter a session at different points. Prompt templates fill the editor on demand. `AGENTS.md` files provide standing project instructions. Leading hidden system blocks attach model-facing instructions to one user message.
+Tau has three ways to add instructions or reusable text to a session, and each enters at a different point:
 
-These mechanisms do not choose models or tool access. [Personas](personas.md) own the base system prompt, model settings and tool allowlist. Model-specific system notices are configured separately in the [configuration reference](config-reference.md).
+- Prompt templates fill the editor when you ask for them.
+- `AGENTS.md` files give standing project instructions.
+- Hidden system blocks at the start of a user message add instructions for that one message.
+
+None of these choose models or tools. [Personas](personas.md) set the base system prompt, model settings, and tools. Model-specific system notices are configured separately in the [configuration reference](config-reference.md).
 
 ## Prompt templates fill the editor
 
-A prompt template is saved Markdown that Tau inserts into the TUI editor for review and submission. It is not added to the system prompt and does not run automatically.
+A prompt template is saved Markdown that Tau inserts into the TUI editor, where you can review and send it. It is never added to the system prompt and never runs by itself.
 
 Tau discovers prompt files from:
 
@@ -15,9 +19,9 @@ Tau discovers prompt files from:
 | Global  | `~/.config/tau/prompts/<id>.md` |
 | Project | `<level>/.tau/prompts/<id>.md`  |
 
-The global location is in scope only when the execution-environment working directory is inside its home directory. Tau walks project levels from the working directory toward home, or toward the filesystem root when outside home. The nearest project definition wins over parent and global definitions. Prompt IDs are compared case-insensitively for precedence and lookup.
+The global location applies only when the session's working directory is inside the execution environment's home directory. Tau searches project levels from the working directory up to home, or up to the filesystem root when outside home. The nearest project definition wins over parent and global ones. Prompt IDs are compared case-insensitively, both for precedence and for lookup.
 
-A prompt's ID is its filename without `.md`. Each file requires YAML frontmatter with a non-empty display `label`. For example, `release-summary.md`:
+A prompt's ID is its filename without `.md`. Each file needs YAML frontmatter with a non-empty `label`. For example, `release-summary.md`:
 
 ```markdown
 ---
@@ -27,9 +31,9 @@ label: release summary
 Summarize the changes since the previous release. Separate user-visible changes from internal maintenance, and call out any migration steps.
 ```
 
-The required `label` appears in TUI autocomplete and the Telegram prompt picker. Unknown frontmatter fields are discarded. The Markdown body is the text inserted into the editor.
+The `label` appears in TUI autocomplete and in the Telegram prompt picker. Unknown frontmatter fields are ignored. The Markdown body is the text inserted into the editor.
 
-Only files ending in lowercase `.md` are discovered. Invalid YAML, non-object frontmatter, or a missing or invalid label causes Tau to skip the file and report a warning.
+Only files ending in lowercase `.md` are found. Tau skips a file with a warning if its YAML is invalid, its frontmatter is not an object, or its label is missing or invalid.
 
 ### Invoke a prompt
 
@@ -39,42 +43,42 @@ In the TUI, invoke a prompt by ID:
 /prompt:release-summary
 ```
 
-Tau replaces the current editor text with the template body. It does not submit the text, so it can be edited before sending. Prompt lookup is case-insensitive.
+Tau replaces the editor text with the template body. It does not send the text, so you can edit it first. Lookup is case-insensitive.
 
-The session catalog stores only prompt metadata. Tau loads the body lazily from the execution environment when `/prompt:<id>` runs. This has two practical effects:
+The session stores only each prompt's ID and label. Tau reads the body from the execution environment each time `/prompt:<id>` runs. As a result:
 
-- Editing the body of an already-cataloged prompt can affect its next invocation without embedding that body in the session snapshot.
-- Adding, removing, renaming, or changing the metadata of a prompt requires `/reload` before the TUI catalog and autocomplete reflect it.
+- An edit to the body of a known prompt takes effect on its next use, without `/reload`.
+- After adding, removing, or renaming a prompt, or changing its label, run `/reload` before autocomplete shows the change.
 
-If the file is missing or invalid when Tau resolves it, invocation fails instead of using a stale body. Remote clients ask the host to resolve the prompt from the session's execution environment; they do not read a same-named file on the client machine.
+If the file is missing or invalid when Tau reads it, the command fails. Tau never falls back to an older copy of the body. An attached client always gets the prompt from the session's execution environment, never from a file with the same name on the client machine.
 
 ### Telegram prompt picker
 
-In [Telegram](telegram.md), `/prompt` lists the active session’s saved prompts, with pages for larger catalogs. Selecting a prompt resolves its current body through the session and records it as a committed user message. Selection is allowed only while the session is idle; otherwise wait for Tau to finish or use `/interrupt` first.
+In [Telegram](telegram.md), `/prompt` lists the active session's saved prompts, split into pages when there are many. Selecting one reads its current body and adds it to the session as a user message, without starting a turn. You can select a prompt only while the session is idle. Otherwise, wait for Tau to finish or use `/interrupt` first.
 
-After recording succeeds, the picker becomes non-actionable and shows the prompt text, continued in additional messages when needed. Send a normal message (for example, details or “go”) to start the next turn with the prompt in context. In groups, that message must mention the bot as usual. Selecting another prompt appends another message rather than replacing the previous one. Recorded prompts survive session recovery.
+After a prompt is added, the picker's buttons stop working and it shows the prompt text, split across more messages if needed. Send a normal message, such as details or “go”, to start the next turn with the prompt in context. In groups, that message must mention the bot as usual. Selecting another prompt adds another message; it does not replace the first. Added prompts survive session recovery.
 
-Only the newest picker in a chat is active. Pickers are bound to the session that opened them and expire after selection, session replacement, or runner restart. Duplicate taps do not record the same picker twice. Prompt selection does not consume pending attachments or group context.
+Only the newest picker in a chat works. A picker belongs to the session that opened it and expires after a selection, when the session is replaced, or when the runner restarts. Tapping twice does not add the prompt twice. Selecting a prompt does not use up pending attachments or group context.
 
 ## `AGENTS.md` provides standing context
 
-`AGENTS.md` is project context injected into the effective system prompt. It is suitable for repository conventions, architectural boundaries, verification commands, and instructions that should apply to every relevant request.
+`AGENTS.md` files are added to the system prompt as project context. Use them for repository conventions, architecture boundaries, verification commands, and other instructions that apply to every request in the project.
 
-Tau resolves `AGENTS.md` through the execution environment. Client and host filesystem access is not used as a shortcut, even for a local session.
+Tau always reads `AGENTS.md` from the execution environment, also in a local session.
 
 ### Ancestor files are included in full
 
 Starting at the session working directory, Tau checks each ancestor for `AGENTS.md`. When the working directory is inside home, the walk stops at home and includes home itself. Otherwise it stops at the filesystem root.
 
-Existing eligible files are included in full. The nearest file is injected first, followed by its ancestors. This lets the agent see both local and broader instructions; when instructions conflict, the active instruction hierarchy and the more specific project guidance determine behavior.
+Each file found is included in full, nearest first, followed by those in parent directories. The agent sees both local and broader instructions. When they conflict, the more specific project guidance takes priority, within the agent's overall instruction hierarchy.
 
-A candidate must resolve to a real file whose basename is exactly `AGENTS.md`. Its directory must be either an ancestor or a descendant of the current working directory. When the working directory is inside home, the canonical file must also remain inside home. These checks prevent a symlink from silently importing unrelated context outside the session's path boundary.
+A file is included only if it resolves to a real file named exactly `AGENTS.md`, in a directory that is a parent or a subdirectory of the working directory. When the working directory is inside home, the resolved file must also be inside home. These checks stop a symlink from pulling in unrelated instructions from outside the session's directories.
 
 ### Descendant files are listed by path
 
-Tau also scans below the current working directory for nested `AGENTS.md` files. Their contents are not injected automatically. Tau includes only their paths so the agent knows that more specific instructions exist and can read the relevant file before working in that subtree.
+Tau also looks below the working directory for nested `AGENTS.md` files. Their contents are not added automatically. Tau lists only their paths, so the agent knows more specific instructions exist and can read the right file before working in that subdirectory.
 
-The scan is breadth-first, visits at most 8,192 directories, and descends at most 16 levels below the working directory. It follows only directory paths that canonically remain under that directory and avoids symlink cycles.
+The scan is breadth-first, visits at most 8,192 directories, and goes at most 16 levels deep. It follows only directories whose resolved path stays under the working directory, and it does not loop on symlink cycles.
 
 Tau skips these directory names at every level:
 
@@ -84,14 +88,14 @@ Tau skips these directory names at every level:
 target  vendor  venv
 ```
 
-When scanning directly from the execution home, Tau also skips direct children managed by common tools:
+When the scan starts at the home directory itself, Tau also skips these tool-managed directories directly under home:
 
 ```text
 .bun  .cargo  .config  .deno  .gradle  .local  .m2  .npm  .nvm
 .pnpm-store  .rustup  .sdkman  .yarn
 ```
 
-It additionally skips the direct `Library` child on macOS and `snap` on Linux. A project directory with one of these names is still scanned when it is not a direct child of home.
+It also skips `Library` directly under home on macOS, and `snap` on Linux. A directory with one of these names elsewhere is still scanned.
 
 ## Disable project context
 
@@ -101,45 +105,43 @@ Start Tau with:
 tau --no-agent-context-files
 ```
 
-This disables ancestor `AGENTS.md` injection and the descendant paths-only scan. It does not disable personas, prompt templates, or [skills](skills.md).
+This turns off both the included `AGENTS.md` files and the list of nested ones. Personas, prompt templates, and [skills](skills.md) still work.
 
-The option applies to local TUI sessions and to hosts started with `tau serve`. For the Node SDK, `noAgentContextFiles: true` provides the same host-level behavior. An attached client cannot retroactively change how an existing remote host session was created.
+The option works for local TUI sessions and for hosts started with `tau serve`. In the Node SDK, `noAgentContextFiles: true` does the same for the host. An attached client cannot change this for a session that already exists on a remote host.
 
 ## Alternate subagent working directories
 
-A subagent normally inherits the parent session's working directory and composed context. When `spawn_agent` specifies a different `workingDirectory`, Tau rebuilds the subagent's target-dependent context from that directory.
-
-The alternate directory controls:
+A subagent normally uses the parent session's working directory and context. When `spawn_agent` sets a different `workingDirectory`, Tau rebuilds the parts of the context that depend on the directory:
 
-- target environment and repository metadata,
-- target applicable `AGENTS.md`,
-- all target-discovered skills.
+- environment and repository details
+- the applicable `AGENTS.md` files
+- the skills found from that directory
 
-The parent session remains the source of truth for the selected persona, model catalog, model settings, and tool policy. It does not replace the source persona with a persona found in the target directory. See [subagents](subagents.md) for the full launch contract.
+The persona, model catalog, model settings, and tool policy still come from the parent session. A persona file in the other directory is not used. See [subagents](subagents.md) for details.
 
 ## Leading hidden system blocks
 
-Tau recognizes one or more exact `<system>...</system>` blocks only when they begin a user message and each closing tag is followed by a newline:
+Tau recognizes one or more `<system>...</system>` blocks only when they start a user message and each closing tag is followed by a newline:
 
 ```text
 <system>Use the deployment checklist for this response.</system>
 Prepare the staging release.
 ```
 
-The complete raw message is persisted and remains model-visible, while Tau's user-message display omits the recognized leading blocks and shows the remaining text. A block elsewhere in the message, a malformed block, or a closing tag without the required newline is ordinary visible text.
+The whole message is saved and sent to the model. When Tau displays the message, it hides the recognized blocks and shows the rest. A block anywhere else in the message, a malformed block, or a closing tag without the newline is shown as ordinary text.
 
-This mechanism is useful for integrations that need per-message model instructions without presenting them as user prose. It is not a secret channel or a substitute for access control: the content is durable session data and is sent to the model. Project-wide guidance belongs in `AGENTS.md`; stable persona behavior belongs in the persona system prompt.
+Integrations can use this to give the model instructions for one message without showing them as the user's words. The blocks are not secret and do not control access: they are saved in the session and sent to the model. Put project-wide guidance in `AGENTS.md` and lasting persona behavior in the persona's system prompt.
 
 ## Reload and verify context
 
-Run `/reload` in an idle TUI session after changing prompts, skills, personas, configuration, or project context files. Reload re-resolves content and rebuilds the active persona's system context. It reports configuration warnings and the resulting counts. Reload is refused while a session turn is active.
+Run `/reload` in an idle session after changing prompts, skills, personas, configuration, or project context files. Reload reads everything again and rebuilds the system prompt for the active persona. It reports configuration warnings and how much content it loaded. Reload is refused while a turn is running.
 
-For a new local TUI session, debug mode prints discovered content, loaded context-file paths, tool schemas, and the effective system prompt, then exits:
+For a new local session, debug mode prints the discovered content, the paths of loaded context files, tool schemas, and the system prompt, then exits:
 
 ```bash
 tau --debug --persona release-coder
 ```
 
-Add `--no-agent-context-files` to verify the context-free variant. Debug mode is TUI startup functionality and is not available with `tau serve`.
+Add `--no-agent-context-files` to see the result without project context. Debug mode works only for TUI startup, not with `tau serve`.
 
-If expected context is missing, verify the execution-environment `cwd` and `home`, not just the attached client's current directory. Then check exact filenames, canonical path eligibility, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.
+If expected context is missing, check the `cwd` and `home` of the execution environment, not the attached client's current directory. Then check exact filenames, the path rules above, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.