@markusylisiurunen/tau 0.3.82 → 0.3.84

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

@@ -1,6 +1,6 @@
 # Configuration
 
-Tau builds configuration from a working directory, not from one universal file. It combines shipped defaults, an eligible global level, and every project level on the path to that working directory. Knowing whose working directory is in use is as important as knowing the field name.
+Tau builds configuration for a working directory. It combines the shipped defaults, the global level when it applies, and every project level on the path to that directory. The same field can therefore have different values on different machines or in different directories, so first find out which working directory applies.
 
 This page explains how the layers behave. Use [configuration reference](config-reference.md) for the fields themselves and [ownership and scope](ownership-and-scope.md) when more than one machine is involved.
 
@@ -16,7 +16,7 @@ Tau recognizes these `config.json` locations:
 
 When `cwd` is inside home, discovery stops at home. When it is outside home, the global level is omitted and project discovery continues to the filesystem root.
 
-Tau recognizes a project level when that ancestor contains either `.tau/` or `.agents/skills/`. A `config.json` file is optional at a recognized level. This allows skill-only levels to participate in content discovery without requiring an empty config file.
+A directory counts as a project level when it contains `.tau/` or `.agents/skills/`. The level does not need a `config.json` file, so a directory with only skills still takes part in content discovery.
 
 For this layout:
 
@@ -37,11 +37,11 @@ starting from `/home/ada/work/ledger/packages/api` loads, from least to most spe
 /home/ada/work/ledger/packages/api/.tau/config.json
 ```
 
-In a remote session, the session runtime uses the execution environment's `cwd` and home. An attached TUI separately loads client-local settings from the attach process's `cwd` and home.
+In a remote session, the session uses the `cwd` and home of the execution environment. An attached TUI loads its own client settings from the `cwd` and home of the `tau attach` process.
 
 ## How levels combine
 
-Most scalar or whole-object settings use **most-specific wins**. A value in the nearest project level replaces the corresponding value from broader levels.
+For most fields, **the most specific level wins**. A value in the nearest project level replaces the same field from broader levels, including whole objects.
 
 In `~/.config/tau/config.json`:
 
@@ -61,7 +61,7 @@ In `~/work/ledger/.tau/config.json`:
 
 Within the project, the effective default persona is `gpt-6.1-sol-coder:high`.
 
-A few fields intentionally use other rules:
+A few fields use other rules:
 
 - `apiKeys` is global-only; project values are rejected.
 - `modelSystemNotices` merges by normalized `<provider>/<model>` key.
@@ -70,7 +70,7 @@ A few fields intentionally use other rules:
 - `clientTools` is defined only at global scope. `enabledClientTools` at the most-specific project level is an exact selection from those definitions.
 - `history` is accepted only at global scope.
 
-An empty project `enabledClientTools` list deliberately disables all configured command client tools for that project:
+An empty `enabledClientTools` list in a project disables all command client tools for that project:
 
 ```json
 {
@@ -82,20 +82,20 @@ Without `enabledClientTools`, Tau selects global client tools whose `defaultEnab
 
 ## How relative paths resolve
 
-Relative path bases belong to the level that declares the value:
+A relative path resolves from the level that declares it:
 
 - A global `clientTools[].command` containing a slash resolves from home.
 - A bare command such as `git` is left bare and resolves through the owning process's `PATH`.
 
-Other strings that happen to contain paths are not automatically rebased unless their field contract says so. In particular, hosted execution-environment `home` values are passed as configured.
+Other fields that contain paths are used as written, unless the field's reference entry says otherwise. For example, the `home` value of a hosted execution environment is passed on unchanged.
 
 ## Invalid and unknown fields
 
 Each `config.json` must contain a JSON object. Malformed JSON, wrong types, invalid enum values, unknown model targets, and fields used at a forbidden scope produce configuration warnings. Tau keeps valid fields from the same file and continues merging other levels. Run `/reload` in an idle session to see the current warnings.
 
-If a more-specific field is invalid, it is skipped rather than replacing a valid broader value. This can make the broader value remain effective, so do not treat a warning as if the requested override took effect.
+An invalid field is skipped. If a broader level sets the same field validly, that broader value stays in effect. A warning therefore means your override did not apply.
 
-Unknown object fields are accepted and stripped without a warning. This applies at the top level and in validated nested objects. It makes newer configuration tolerable to an older binary, but it also means misspelled fields have no effect:
+Unknown fields are removed without a warning, both at the top level and inside nested objects. This lets an older Tau version read configuration written for a newer one. It also means a misspelled field silently has no effect:
 
 ```json
 {
@@ -103,16 +103,16 @@ Unknown object fields are accepted and stripped without a warning. This applies
 }
 ```
 
-The example is valid JSON and produces no setting because `defaultPersnoa` is unknown. Compare edited keys against [configuration reference](config-reference.md), especially when no warning appears.
+This is valid JSON but sets nothing, because `defaultPersnoa` is not a known field. Check edited keys against the [configuration reference](config-reference.md), especially when no warning appears.
 
 ## Make a safe edit
 
-First identify the consumer and its `cwd`, home, and machine. Then choose the narrowest valid scope:
+First find out what reads the setting, and on which machine, `cwd`, and home. Then choose the narrowest level that works:
 
-- Personal defaults and secrets usually belong in eligible global configuration.
-- Repository behavior shared by collaborators belongs in a project `.tau/config.json` when it contains no secrets or machine-local commands.
-- Nested project levels are appropriate only when that subtree genuinely needs a different value.
-- Client-only commands should not be placed in a remote execution environment and expected to appear on an attached laptop.
+- Personal defaults and secrets usually belong in global configuration.
+- Settings for a repository that collaborators share belong in the project's `.tau/config.json`, as long as they contain no secrets or machine-specific commands.
+- Use a nested project level only when that subdirectory needs a different value.
+- Client commands belong on the client. Defining them in a remote execution environment does not make them appear on an attached laptop.
 
 Keep examples small and edit only the intended field. Validate JSON before asking Tau to load it:
 
@@ -121,65 +121,69 @@ node -e 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"))' \
   ~/.config/tau/config.json
 ```
 
-That check proves syntax only. Start Tau from the relevant `cwd` to validate field contracts and content references:
+That check covers syntax only. To validate fields and content references, start Tau from the relevant `cwd`:
 
 ```sh
 cd ~/work/ledger
 tau --debug
 ```
 
-`--debug` is appropriate for a local startup and can reveal project instructions in its output. It does not query an already running host, remote execution environment, or attached client's state. For a live session runtime, use `/reload` and read its configuration warnings. There is no command that serializes the complete effective configuration.
+`--debug` inspects a local startup, and its output can include project instructions. It cannot show the state of a running host, a remote execution environment, or an attached client. For a running session, use `/reload` and read its configuration warnings. No command prints the complete effective configuration.
 
-Never verify a secret by printing the full config or environment into a shared transcript. Test the operation that needs the credential, and use the auth commands for Codex OAuth accounts.
+Never check a secret by printing the full config or environment into a shared transcript. Instead, run the operation that needs the credential. For Codex OAuth accounts, use the auth commands.
 
 ## When changes take effect
 
 ### New local or client process
 
-Tau loads startup configuration and content before opening the TUI. Restart the local TUI or `tau attach` to apply client-owned changes such as:
+Tau loads client configuration before opening the TUI. Restart the local TUI or `tau attach` to apply client changes such as:
 
 - `defaultTheme`
 - `clientTools` and `enabledClientTools`
 - client environment variables
 
-Changing `/theme:<id>` updates only the current client presentation. Themes are not persisted in session snapshots.
+`/theme:<id>` changes only the current client's appearance. Themes are not saved in the session.
 
 ### Current session runtime
 
-Run `/reload` when no session turn is active to recollect runtime configuration and content from the execution environment. Reload updates the current session's runtime config, model catalog, personas, prompts, skills, selected persona definition, and project context. It reports warnings and refreshes the session catalog.
+When no turn is running, `/reload` reads configuration and content again from the execution environment. It updates the session's runtime configuration, model catalog, personas, prompts, skills, the selected persona's definition, and project context. It also reports warnings and refreshes the session catalog.
 
-The current persona id is retained if it still exists; otherwise Tau chooses the first available persona. Changing `defaultPersona` does not by itself switch an existing session during reload. It selects new sessions unless a CLI or creation request overrides it.
+The session keeps its current persona if that persona still exists. Otherwise Tau picks the first available persona. Changing `defaultPersona` does not switch an existing session on reload. It applies to new sessions, unless a CLI flag or creation request chooses another persona.
 
-A logical turn captures its persona, model settings, and tools when it starts. Reload is blocked while a turn is active, and reloaded behavior applies to later turns.
+A turn keeps the persona, model settings, and tools it started with. Reload is refused while a turn is running, and reloaded settings apply to later turns.
 
 ### Host startup
 
-Restart the host process to apply settings used to construct host-wide services, including:
+Restart the host process to apply settings that the host reads once at startup, including:
 
 - `flySprites`
 - `history`
-- host environment variables and Codex account forcing
+- host environment variables
 
-For `tau serve`, make the changes on the host machine and restart the server. Restarting only an attached TUI does not rebuild the host.
+For `tau serve`, make the changes on the host machine and restart the server. Restarting an attached TUI does not restart the host.
 
 ### New session or runner
 
-Some settings are choices rather than live mutations. `defaultPersona` and startup persona flags select a new session. Execution-environment kind, identity, `cwd`, and home are fixed when the session is created or recovered.
+Some settings apply only when something new is created. `defaultPersona` and startup persona flags choose the persona of a new session. The execution environment's kind, identity, `cwd`, and home are fixed when the session is created or recovered.
 
-The Telegram runner loads its speech provider and separate runner config at startup. Restart it for speech, project, routing, or workspace-preparation changes. Workspace-preparation changes apply when a managed workspace is created or reconstructed; restarting does not retrofit a preserved workspace. Command client tools are selected when a Telegram session client is created, so configuration changes apply to new sessions; restarting the runner also rebuilds clients while recovering its sessions. Existing sessions retain their recorded execution environment unless the documented recovery behavior reconstructs a managed workspace.
+The Telegram runner loads its speech provider and its runner config at startup. Restart it after changing speech, projects, routing, or workspace preparation.
+
+- Workspace-preparation changes apply when a managed workspace is created or reconstructed. Restarting does not change a preserved workspace.
+- Command client tools are chosen when the runner creates the client for a session. Changes apply to new sessions, and also to existing sessions when a runner restart recovers them.
+- Existing sessions keep their recorded execution environment, unless recovery has to reconstruct a missing managed workspace (see [Telegram projects and workspaces](telegram-projects.md)).
 
 ## Common precedence mistakes
 
-**Editing global config for a project outside home.** The global level is omitted when the relevant `cwd` is outside home. Add an appropriate project level or change the environment's configured home rather than assuming `~/.config/tau` is always included.
+**Editing global config for a project outside home.** The global level is skipped when the relevant `cwd` is outside home. Add a project level, or change the environment's configured home.
 
-**Editing the laptop for host behavior.** An attached TUI cannot provide credentials, session storage, hosted-environment definitions, or runtime project config to a remote host merely by having them locally.
+**Editing the laptop for host behavior.** Credentials, session storage, hosted-environment definitions, and project configuration on the laptop do not reach a remote host through an attached TUI.
 
-**Editing the host filesystem for target content.** A hosted execution environment owns its project files and home. Put project `.tau` content on that target, not in a similarly named path on the host.
+**Editing the host's files for a hosted environment.** A hosted execution environment has its own project files and home. Put project `.tau` content on that environment, not at a similar path on the host.
 
-**Expecting nested objects to deep-merge.** A project Sprite API entry replaces the complete entry with the same id. Repeat any credentials and settings needed by that API.
+**Expecting nested objects to deep-merge.** A nearer `mcpServers` entry replaces the whole entry with the same name, including its credentials, and a nearer `nook` object replaces the broader one completely. Repeat every setting the entry needs.
 
-**Expecting `/reload` to rebuild the client or server.** Reload is a current-session runtime operation. Restart the component that owns startup-only behavior.
+**Expecting `/reload` to restart the client or server.** Reload affects only the current session. Restart the process that reads the setting at startup.
 
-**Using a project file for global-only fields.** `clientTools` and `history` are rejected outside global config. `enabledClientTools` is rejected outside project config.
+**Using a project file for global-only fields.** `apiKeys`, `clientTools`, and `history` are rejected outside global config. `enabledClientTools` is rejected outside project config.
 
-**Trusting a silent typo.** Unknown fields are stripped. Check exact names and observe the resulting operation rather than assuming valid JSON means valid Tau configuration.
+**Trusting a silent typo.** Unknown fields are removed without a warning. Valid JSON is not necessarily valid Tau configuration, so check exact names and confirm the setting changed behavior.

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

@@ -1,16 +1,14 @@
 # Credentials
 
-Tau can read secrets from configuration, process environments, and managed OAuth storage. The correct location depends on which process performs the authenticated operation. In a remote session, the attached terminal is usually not that process.
+Tau reads secrets from configuration, environment variables, and its own OAuth storage. Put each secret on the process that makes the authenticated request. In a remote session, that is usually not the attached terminal.
 
-Treat credentials separately from model definitions. [Models](models.md) describes providers and model metadata; this page describes how authenticated requests obtain secrets.
+This page covers where secrets come from. [Models](models.md) covers providers and model metadata.
 
 ## Credential ownership
 
-The host performs model calls and runs host-owned services such as web search and remote history. Its home and process environment therefore own most credentials. The execution environment still owns the `config.json` files used by a session, so a provider key loaded from project configuration crosses into the host for use in model calls.
+The host makes model calls and runs services such as web search and remote history, so most credentials belong in the host's environment or the host user's global configuration. Common cases:
 
-Common cases are:
-
-| Operation | Credential owner |
+| Operation | Where the credential belongs |
 | --- | --- |
 | Main-agent, subagent, sampling, and maintenance model calls | Session host |
 | OpenAI Codex OAuth accounts | Session host home |
@@ -22,11 +20,11 @@ Common cases are:
 | Telegram transcription and voice responses | Telegram runner |
 | Standalone `tau tool` commands | The process running that command |
 
-With local `tau`, these roles normally share one machine. With `tau attach`, setting a key only in the attached client's shell does not authenticate the remote host. Run `tau auth` on the host machine and set host-owned environment variables where `tau serve` or the SDK host actually runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
+With local `tau`, all of these are usually one machine. With `tau attach`, a key set only in the attached client's shell does not reach the remote host. Run `tau auth` on the host machine, and set host environment variables where `tau serve` or the SDK host runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
 
 ## Provider API keys
 
-Tau accepts provider API keys in private global configuration:
+Tau accepts provider API keys in global configuration:
 
 ```json
 {
@@ -38,15 +36,15 @@ Tau accepts provider API keys in private global configuration:
 }
 ```
 
-Keys are provider IDs, not model IDs. `apiKeys` is global-only, in the owning process's `~/.config/tau/config.json`; project values are rejected. Configuration strings are literal and do not expand environment variables.
+The keys of the map are provider IDs, such as `openai`, not model IDs. `apiKeys` is allowed only in the global `~/.config/tau/config.json` of the process that uses it. Project values are rejected. Values are literal strings and do not expand environment variables.
 
-For model API-key authentication, provider-supported environment credentials take precedence over global `apiKeys`. Supported cloud and workload identity authentication remains available. OpenAI uses `OPENAI_API_KEY`; Anthropic also supports `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_OAUTH_TOKEN` according to its provider contract. Managed Codex OAuth is separate and always uses the explicitly active stored account.
+For model requests, a provider's environment variable wins over its entry in `apiKeys`. Cloud and workload identity authentication that the provider supports still works. OpenAI uses `OPENAI_API_KEY`. Anthropic also accepts `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_OAUTH_TOKEN`. Codex OAuth is separate and always uses the active stored account.
 
-Set model credentials where the host runs. Restart the owning process after changing environment variables or its global API-key configuration.
+Set model credentials where the host runs. Restart that process after changing its environment variables or its `apiKeys`.
 
 ## Feature-specific keys
 
-Feature helpers use environment variables first, then global configuration:
+Features check the environment variable first, then global configuration:
 
 | Feature | Resolution order |
 | --- | --- |
@@ -59,9 +57,9 @@ Feature helpers use environment variables first, then global configuration:
 
 `web.discover` does not require Exa. `web.search` and `web.fetch` do. `/speak` and Telegram `/tts_on` voice responses require OpenAI for text rewriting and ElevenLabs for synthesis. `/listen` and incoming Telegram voice notes use Google, with optional OpenAI spelling hints. PDF OCR through `tau tool pdf-unpack` uses Mistral.
 
-Set these variables on the process that owns the feature. For example, a remote TUI's `/speak` reads the attached client's `OPENAI_API_KEY` and `ELEVENLABS_API_KEY`, while a Google model selected by the session reads credentials at the host.
+Set these on the process that runs the feature. For example, `/speak` in an attached TUI reads `OPENAI_API_KEY` and `ELEVENLABS_API_KEY` on the client machine, while a session that uses a Google model reads its key on the host.
 
-For `tau tool` commands, credentials and configuration belong to the machine running the command. Tau's agent Bash removes inherited API-key environment variables, so commands invoked through it may need keys in private configuration on that machine. See [configuration](configuration.md) for configuration file locations and [security](security.md) for command environment handling.
+For `tau tool` commands, credentials and configuration belong to the machine that runs the command. The agent's Bash tool removes inherited API-key environment variables, so a command the agent runs may need its key in global configuration on that machine. See [configuration](configuration.md) for configuration file locations and [security](security.md) for command environment handling.
 
 ## OpenAI Codex OAuth
 
@@ -71,9 +69,9 @@ The `openai-codex` provider uses ChatGPT Plus or Pro OAuth accounts managed by T
 tau auth login codex
 ```
 
-The flow opens or prints a browser URL and may fall back to a device code or pasted redirect. Tau stores the result under the host user's `~/.config/tau/auth.json` with private file permissions. Do not edit this file directly. The auth commands coordinate concurrent access, refresh tokens when needed, and preserve account state safely.
+The flow opens or prints a browser URL. It may instead ask for a device code or a pasted redirect URL. Tau stores the result in the host user's `~/.config/tau/auth.json` with private file permissions. Do not edit this file directly. The auth commands handle concurrent access and token refresh.
 
-Multiple Codex accounts may be stored, with at most one active account. `tau auth list` displays identities, marks the active account, and shows informational usage windows without revealing tokens.
+Tau can store several Codex accounts, and at most one is active. `tau auth list` shows each identity, marks the active one, and shows usage windows for information, without revealing tokens.
 
 ```sh
 tau auth login codex
@@ -82,11 +80,14 @@ tau auth use codex --account developer@example.com
 tau auth logout codex --account developer@example.com
 ```
 
-First login activates the account only when no accounts are stored. Later logins add or refresh an account without changing the active selection. If stored accounts remain but none is active, use `tau auth use` explicitly. Account IDs and email matching are case-insensitive.
-
-`auth use` replaces the previous active account. Logout removes the account; logging out the active account leaves no account active even if others remain. With no active account, requests fail with instructions to log in or select one. Failed or exhausted accounts surface failures without automatic switching. Usage never determines selection.
+- A login activates the account only when no other accounts are stored. Later logins add or refresh an account without changing which one is active.
+- `auth use` makes an account active and deactivates the previous one.
+- Logout removes the account. Logging out the active account leaves no account active, even if others remain. Choose one with `tau auth use`.
+- With no active account, requests fail with instructions to log in or select an account.
+- Tau never switches accounts automatically, whether an account fails or runs out of usage. Usage never affects selection.
+- Account IDs and emails match case-insensitively.
 
-Auth storage is reloaded for later requests across sessions. Switching accounts does not alter a request already in flight and needs no host restart.
+Every new request reads the current auth storage, in every session. Switching accounts takes effect without a host restart and does not affect a request already in progress.
 
 ## History and Nook indirection
 
@@ -109,7 +110,7 @@ History resolves its API key in this order:
 2. The host environment variable named by `history.apiKeyEnv`
 3. Inline `history.apiKey`
 
-If `history` is configured but none resolves, host setup fails for the remote target. Without `history` configuration, transcripts remain machine-local. See [history](history.md) for service behavior.
+If `history` is configured but no key is found, the host fails to start. Without `history`, history stays on the host machine. See [history](history.md) for service behavior.
 
 A Nook Access service token uses an ID plus a secret:
 
@@ -123,11 +124,11 @@ A Nook Access service token uses an ID plus a secret:
 }
 ```
 
-If the named `accessClientSecretEnv` has a non-empty value, it wins over inline `accessClientSecret`; otherwise Tau falls back to the inline value. The process performing the Nook operation resolves it. For a session tool that is the host, while `tau nook` commands use the invoking CLI process. Nook setup and destruction also accept their documented command flags and environment variables. See [Nook](nook.md).
+If the variable named by `accessClientSecretEnv` has a non-empty value, it wins over inline `accessClientSecret`. Otherwise Tau uses the inline value. The process that performs the Nook operation reads the secret: the host for the session tool, and the CLI process for `tau nook` commands. Nook setup and destroy also accept the command flags and environment variables listed in [Nook](nook.md). See [Nook](nook.md).
 
 ## Hosted execution credentials
 
-The Fly Sprite connection is host-owned configuration. They must be available when the host starts, before a client asks it to create a Sprite session. The connection requires a token:
+The Fly Sprite connection is host configuration. It must be in place when the host starts, before a client asks for a Sprite session. The connection needs a token:
 
 ```json
 {
@@ -138,18 +139,18 @@ The Fly Sprite connection is host-owned configuration. They must be available wh
 }
 ```
 
-For Fly, inline `token` wins when present; `tokenEnv` is the fallback. Session creation fails if neither resolves.
+An inline `token` wins when present. Otherwise Tau reads the variable named by `tokenEnv`. Session creation fails if neither gives a token.
 
-These target definitions are read from the host's startup configuration, not from an attached client. `/reload` refreshes session runtime content but does not rebuild the host's execution-environment resolvers. Restart the host after changing Sprite connection settings or their environment.
+The host reads these settings from its own startup configuration, never from an attached client. `/reload` does not reload them. Restart the host after changing the Sprite connection or its environment variables.
 
 ## Safe verification
 
-Verify credentials through the operation that owns them, without printing secret values:
+Check a credential by using it, without printing its value:
 
-- Run `tau auth list` to check Codex identities, active selection, refresh health, and informational usage windows.
-- Restart the owning process after changing global `apiKeys`.
+- Run `tau auth list` to check Codex identities, the active account, refresh status, and usage windows.
+- Restart the process that uses `apiKeys` after changing them.
 - Make a small request with the intended persona to verify model authentication and endpoint access.
-- Exercise the specific feature after setting Exa, speech, History, Nook or Fly credentials. Their missing-credential errors name the accepted source.
-- For remote sessions, first confirm which machine is the host and which process owns the feature.
+- After setting Exa, speech, history, Nook, or Fly credentials, use that feature. If a credential is missing, the error names where Tau looks for it.
+- For remote sessions, first confirm which machine is the host and which process runs the feature.
 
-Do not verify by printing the process environment, dumping `config.json`, or reading `auth.json` into a transcript. If a secret was exposed in shell history, logs, a session, or version control, rotate it at the provider and replace the compromised value. Broader handling guidance is in [security](security.md) and failure checks are in [troubleshooting](troubleshooting.md).
+Do not check by printing the environment, `config.json`, or `auth.json` into a transcript. If a secret ends up in shell history, logs, a session, or version control, rotate it at the provider and replace it. Broader handling guidance is in [security](security.md) and failure checks are in [troubleshooting](troubleshooting.md).

package/dist/core/static/tau_docs/getting-started.md

@@ -1,18 +1,18 @@
 # Getting started
 
-Tau is a terminal chat client that gives model-backed agents tools for working in a project. A local session is the shortest path to understanding it: the terminal client, session host, and execution environment all run on the same machine, while retaining the same boundaries used by remote sessions.
+Tau is a terminal chat client that gives AI agents tools for working in a project. The quickest way to learn it is a local session, where the terminal client, the session host, and the agent's execution environment all run on your machine. Remote sessions use the same three parts on different machines.
 
 ## Requirements
 
 Tau supports macOS and Linux. Windows is not supported.
 
-The published package requires Node.js 24 or newer. Tau runs commands through fresh non-interactive login Bash processes, so verify that environment from the account that will run Tau before installing:
+The published package requires Node.js 24 or newer. Tau runs every command in a fresh non-interactive login Bash process. Before installing, check that environment from the account that will run Tau:
 
 ```sh
 bash -lc 'command -v node && node --version && command -v npm && npm --version'
 ```
 
-The command should resolve both executables and finish without prompts, terminal errors, or unrelated startup output. Use the same check for other executables you expect the agent to use.
+The command should find both executables and finish without prompts, terminal errors, or extra startup output. Use the same check for any other executable you expect the agent to use.
 
 ## Install or upgrade Tau
 
@@ -22,14 +22,14 @@ Install the latest published version globally:
 npm install -g @markusylisiurunen/tau@latest
 ```
 
-Run the same command to upgrade. Then confirm which executable and version npm installed:
+Run the same command to upgrade. Then check which executable and version npm installed:
 
 ```sh
 command -v tau
 npm list -g @markusylisiurunen/tau --depth=0
 ```
 
-The built-in documentation is packaged with Tau. Upgrading the package upgrades the documentation read by `tau_docs` on that host. Tau also refreshes compatible model metadata asynchronously when a model-owning host starts. To force that refresh without upgrading Tau, run:
+The built-in documentation is part of the package, so upgrading Tau also upgrades the documentation its agent reads. Tau also refreshes compatible model metadata in the background when a host that runs models starts. To refresh it without upgrading Tau, run:
 
 ```sh
 tau models refresh
@@ -37,14 +37,14 @@ tau models refresh
 
 ## Set up a provider
 
-A session needs credentials for the provider selected by its persona. API-key providers accept ordinary provider environment variables. For example:
+A session needs credentials for the provider that its persona uses. Providers that use API keys read their usual environment variables. For example:
 
 ```sh
 export ANTHROPIC_API_KEY='sk-ant-...'
 tau
 ```
 
-Common built-in choices are `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. Keys may instead be placed in `apiKeys` in Tau configuration:
+Common choices are `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. You can also put keys in `apiKeys` in Tau configuration:
 
 ```json
 {
@@ -54,29 +54,29 @@ Common built-in choices are `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_A
 }
 ```
 
-Put personal secrets in the global config at `~/.config/tau/config.json`, not in a project file likely to be committed. Environment variables and feature-specific key precedence are covered in [credentials](credentials.md).
+Put personal secrets in the global config at `~/.config/tau/config.json`. A project file is likely to be committed. [Credentials](credentials.md) covers environment variables and which key wins for each feature.
 
-The `openai-codex` provider uses ChatGPT subscription OAuth rather than `OPENAI_API_KEY` or `apiKeys.openai`:
+The `openai-codex` provider signs in with a ChatGPT subscription through OAuth. It does not use `OPENAI_API_KEY` or `apiKeys.openai`:
 
 ```sh
 tau auth login codex
 tau auth list
 ```
 
-Use the auth commands to manage this storage. Do not edit `~/.config/tau/auth.json` directly.
+Manage this storage with the auth commands. Do not edit `~/.config/tau/auth.json` directly.
 
 ## Start a local session
 
-Change to the project directory that should become the execution environment's working directory, then run Tau:
+Change to the project directory you want the agent to work in, then run Tau:
 
 ```sh
 cd ~/Code/ledger-service
 tau
 ```
 
-Tau discovers project configuration and content from that directory upward, loads the selected persona, creates a durable local session, and opens the TUI. The agent's file and command tools operate in this execution environment, initially rooted at the selected working directory.
+Tau finds project configuration and content from that directory upward, loads the selected persona, creates a local session that is saved automatically, and opens the TUI. The agent's file and command tools start in this directory.
 
-Type a request and press Enter. Useful first requests are concrete and scoped:
+Type a request and press Enter. Good first requests are concrete and limited in scope:
 
 ```text
 Explain the request flow through this service and point to the key files.
@@ -86,29 +86,29 @@ Explain the request flow through this service and point to the key files.
 Run the focused tests for the parser, fix the failure, and summarize the change.
 ```
 
-Use `/help` inside the TUI to see interactive commands. Press `Ctrl+C` twice to exit. Tau persists local sessions through the host, so exiting the TUI does not require manually saving a transcript.
+Use `/help` inside the TUI to see interactive commands. Press `Ctrl+C` twice to exit. Tau saves the session as you go, so there is nothing to save before exiting.
 
 ## Choose a persona and reasoning level
 
-A **persona** selects a provider and model together with instructions, tools, skills, and default model settings. Tau ships built-in chat and coder personas and can load custom persona files.
+A **persona** selects a provider and model, together with instructions, tools, skills, and default model settings. Tau ships built-in chat and coder personas and can load custom persona files.
 
-Start with a specific persona by passing its exact id:
+To start with a specific persona, pass its exact id:
 
 ```sh
 tau --persona gpt-6.1-sol-coder
 ```
 
-Append a reasoning level when the selected model supports it:
+Append a reasoning level when the model supports it:
 
 ```sh
 tau --persona gpt-6.1-sol-coder:high
 ```
 
-The accepted reasoning levels are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. A persona may expose only a subset in the TUI, and providers that do not support reasoning ignore the setting.
+The reasoning levels are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. A persona may offer only some of them in the TUI. Providers that do not support reasoning ignore the setting.
 
-During a session, `/persona:<id>` changes the persona and `Shift+Tab` cycles the available reasoning levels. A running logical turn keeps the persona, reasoning, model, and tools captured when that turn began. Changes apply to the next independently started turn.
+During a session, `/persona:<id>` changes the persona and `Shift+Tab` cycles through the available reasoning levels. A turn that is already running keeps the persona, reasoning, model, and tools it started with. Changes apply from the next turn.
 
-To choose a default for new sessions, set `defaultPersona`:
+To set a default for new sessions, use `defaultPersona`:
 
 ```json
 {
@@ -116,28 +116,28 @@ To choose a default for new sessions, set `defaultPersona`:
 }
 ```
 
-See [personas](personas.md) for custom persona files and exact inheritance behavior, and [models](models.md) for model catalog overrides.
+See [personas](personas.md) for custom persona files and how inheritance works, and [models](models.md) for model catalog overrides.
 
-## Inspect startup safely
+## Inspect startup
 
-Start with the normal help output:
+Start with the help output:
 
 ```sh
 tau --help
 ```
 
-Tau reports configuration and content warnings on stderr during startup. Warnings identify the source path and invalid field or content entry; Tau continues with the valid portions it could load.
+Tau prints configuration and content warnings to stderr at startup. Each warning names the source path and the invalid field or entry. Tau continues with everything else it could load.
 
-For a local startup, `--debug` shows the resources and tool schemas resolved for the selected working directory without opening the TUI:
+For a local startup, `--debug` shows the resources and tool schemas resolved for the current directory without opening the TUI:
 
 ```sh
 tau --debug --persona gpt-6.1-sol-coder:high
 ```
 
-Debug output can contain project instructions and other model-facing context, so review where it is captured before sharing it. It is a local startup inspection, not a query of an already running remote host or attached client's effective state.
+Debug output can include project instructions and other text sent to the model, so check where it ends up before sharing it. It inspects only a local startup. It cannot show the effective state of a running remote host or an attached client.
 
-After editing session runtime content, `/reload` refreshes it when no turn is active and reports warnings in the transcript. Client-local or host-startup changes require the owning process to restart. [Configuration](configuration.md) explains those boundaries.
+After you edit configuration or content that the session loads, `/reload` refreshes it when no turn is running and reports warnings in the transcript. Changes to client settings or host startup settings need a restart of that process. [Configuration](configuration.md) explains which changes apply where.
 
 ## Continue from here
 
-Read [ownership and scope](ownership-and-scope.md) before using `tau attach`, hosted execution environments, the SDK, or Telegram. For ordinary configuration changes, use [configuration](configuration.md) with the complete [configuration reference](config-reference.md). The [TUI](tui.md) page covers daily interaction, while [sessions](sessions.md) explains persistence, recovery, compaction, and rewind.
+Read [ownership and scope](ownership-and-scope.md) before using `tau attach`, hosted execution environments, the SDK, or Telegram. For everyday configuration, use [configuration](configuration.md) together with the [configuration reference](config-reference.md). [TUI](tui.md) covers daily use, and [sessions](sessions.md) explains saving, recovery, compaction, and rewind.