@markusylisiurunen/tau 0.3.49 → 0.3.50

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

@@ -0,0 +1,181 @@
+# Prompts and project context
+
+Tau has several ways to provide instructions or reusable text, and they enter a session at different points. Prompt templates fill the editor on demand. `AGENTS.md` files provide standing project instructions. Additional context files extend that `AGENTS.md` set. Leading hidden system blocks attach model-facing instructions to one user message.
+
+These mechanisms do not choose models or tool access. [Personas](personas.md) own the base system prompt, model settings, skill selection, and tool allowlist. Model-specific system notices are configured separately in the [configuration reference](config-reference.md).
+
+## 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.
+
+Tau discovers prompt files from:
+
+| Scope   | Location                        |
+| ------- | ------------------------------- |
+| 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.
+
+A prompt file needs YAML frontmatter with an `id` that exactly matches its filename without `.md`:
+
+```markdown
+---
+id: release-summary
+label: release summary
+description: Summarize changes for a release announcement.
+---
+
+Summarize the changes since the previous release. Separate user-visible changes from internal maintenance, and call out any migration steps.
+```
+
+The fields are:
+
+- `id`: required, non-empty, and exactly equal to the filename stem.
+- `label`: optional display label.
+- `description`: optional catalog and autocomplete description.
+
+Unknown fields are discarded. The Markdown body is the text inserted into the editor.
+
+Only files ending in lowercase `.md` are discovered. Invalid YAML, non-object frontmatter, a missing `id`, or an ID/filename mismatch causes Tau to skip the file and report a warning.
+
+### Invoke a prompt
+
+In the TUI, invoke a prompt by ID:
+
+```text
+/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.
+
+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:
+
+- 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.
+
+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.
+
+### Install starter prompts
+
+Use `tau install` to copy Tau's starter content:
+
+```bash
+tau install --prompt commit-staged
+```
+
+The default target is `.tau/prompts/` under the current directory. Add `--global` for `~/.config/tau/prompts/`. Existing prompt files are skipped unless `--force` is supplied. Running `tau install` without `--prompt` or `--skill` installs all starter prompts and skills.
+
+## `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.
+
+Tau resolves `AGENTS.md` through the execution environment. Client and host filesystem access is not used as a shortcut, even for 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.
+
+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.
+
+### 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.
+
+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.
+
+Tau skips these directory names at every level:
+
+```text
+.cache  .git  .hg  .jj  .next  .nuxt  .parcel-cache  .svn  .turbo
+.venv  .vite  __pycache__  build  coverage  dist  node_modules  out
+target  vendor  venv
+```
+
+When scanning directly from the execution home, Tau also skips direct children managed by common tools:
+
+```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.
+
+The limits and exclusions apply only to automatic descendant discovery. They do not constrain explicitly configured context files.
+
+## Add explicit context files
+
+`agentContextFiles` adds specific text files to the full injected context. The files can use any name:
+
+```json
+{
+  "agentContextFiles": ["docs/AI_GUIDE.md", "services/api/AGENTS.md"]
+}
+```
+
+Paths are resolved from the level that declares them:
+
+- A global path in `~/.config/tau/config.json` is relative to home.
+- A project path in `<project>/.tau/config.json` is relative to `<project>`, the directory containing `.tau/`.
+- Absolute paths remain absolute.
+
+Values are additive across configuration levels, from global through the nearest project level. Tau resolves them to paths and removes exact duplicates while preserving order.
+
+An explicit path must resolve to a real file whose directory is an ancestor or descendant of the working directory. An in-home session cannot escape home through a path or symlink. Sibling files, missing files, and ineligible files are not injected.
+
+Explicit files bypass the automatic child scan's depth, directory-count, and excluded-directory rules. Tau still discovers only `AGENTS.md` automatically; every other filename must be configured explicitly.
+
+Use this setting when important project instructions live outside the ordinary `AGENTS.md` hierarchy. Every included file is sent to the model as project context, so do not include secrets or unrelated content.
+
+## Disable project context
+
+Start Tau with:
+
+```bash
+tau --no-agent-context-files
+```
+
+This disables ancestor `AGENTS.md` injection, configured `agentContextFiles`, and the descendant paths-only scan. It does not disable personas, prompt templates, or [skills](skills.md).
+
+The option applies to local TUI sessions and to hosts started with `tau rpc` or `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.
+
+## 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:
+
+- target environment and repository metadata,
+- target applicable `AGENTS.md` and `agentContextFiles`,
+- target-discovered skills filtered by the parent persona.
+
+The parent session remains the source of truth for the selected persona, subagent definition, model catalog, model settings, and tool policy. Tau filters skills discovered at the alternate directory through the parent persona's skill selection. It does not replace the source persona with a persona found in the target directory. See [subagents](subagents.md) for the full launch contract.
+
+## 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:
+
+```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.
+
+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.
+
+## 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.
+
+For a new local TUI session, debug mode prints discovered content, loaded context-file paths, tool schemas, and the effective 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 rpc` or `tau serve`.
+
+If expected context is missing, verify the execution-environment `cwd` and `home`, not just the attached client's current directory. Then check exact filenames, canonical path eligibility, configuration-level path bases, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.

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

@@ -0,0 +1,274 @@
+# Remote sessions
+
+Remote sessions let the terminal stay close to the user while the session host and execution environment run elsewhere. Tau does not turn remote work into a second product mode: `tau attach` uses the same TUI over a WebSocket or stdio transport. The important choice is which process should stay alive, who owns credentials and persistence, and where agent-visible commands run.
+
+## Choose the connection shape
+
+Use the smallest shape that matches the lifecycle you need.
+
+| Shape | Best for | Lifetime and ownership |
+| --- | --- | --- |
+| `tau serve` plus WebSocket attach | Long-running hosts, reconnects, and multiple observers | The server owns the host independently of any one TUI. |
+| `tau attach -- ssh … tau rpc` | Ad hoc access through SSH without exposing a listener | The attachment owns one remote RPC process. Closing it shuts that host down. |
+| `tau rpc` directly | Editors, automation, and custom protocol clients over NDJSON | The parent process owns the RPC host and its stdin/stdout. |
+| Node SDK with its default client | Applications that want an in-process host | The SDK client owns the host and closes it with the client. |
+| Node SDK over WebSocket | Applications sharing a long-running `tau serve` host | The server owns sessions; the SDK observes them remotely. |
+
+Use `tau serve` when a turn should continue after a laptop disconnects. Use stdio/SSH when SSH is already the desired security and process boundary and it is acceptable for closing the TUI to stop remote work. The [session protocol](session-protocol.md) and [Node SDK](node-sdk.md) cover developer APIs and wire details; this page stays at the operational level.
+
+## Host sessions over WebSocket
+
+Start a server on the host:
+
+```sh
+tau serve
+```
+
+The default listener is `127.0.0.1:8787`. This is suitable for local clients or a reverse proxy on the same machine. To listen on another interface, set it explicitly and require a strong token:
+
+```sh
+export TAU_WS_AUTH_TOKEN="$(openssl rand -hex 32)"
+tau serve --host 0.0.0.0 --port 8787 --auth-token "$TAU_WS_AUTH_TOKEN"
+```
+
+From the client machine:
+
+```sh
+export TAU_WS_AUTH_TOKEN='the-same-token'
+tau attach ws://buildbox.example:8787
+```
+
+`tau attach` uses `TAU_WS_AUTH_TOKEN` when `--auth-token` is absent. An explicit form is also valid:
+
+```sh
+tau attach --auth-token "$TAU_WS_AUTH_TOKEN" ws://buildbox.example:8787
+```
+
+A server token authorizes full access to hosted sessions. Without `--auth-token` or `TAU_WS_AUTH_TOKEN`, the listener is unauthenticated. Tau’s server terminates plain WebSocket traffic and does not accept certificate options. On an untrusted network, put it behind a trusted TLS reverse proxy and attach with `wss://`, or keep it bound to loopback and use an SSH tunnel. Treat proxy logs and WebSocket handshake metadata as sensitive because the authentication token is carried during connection setup.
+
+A typical tunnel keeps Tau bound to loopback:
+
+```sh
+ssh -N -L 8787:127.0.0.1:8787 dev@buildbox.example
+```
+
+Then attach locally:
+
+```sh
+tau attach ws://127.0.0.1:8787
+```
+
+## Attach through stdio and SSH
+
+Anything after `--` is launched as a local child process and must speak Tau’s session protocol over stdin and stdout. SSH makes that child a remote `tau rpc` process:
+
+```sh
+tau attach -- ssh dev@buildbox.example tau rpc
+```
+
+A login shell or project-specific host configuration can be selected in the remote command:
+
+```sh
+tau attach -- ssh dev@buildbox.example 'cd /srv/tau-host && tau rpc'
+```
+
+The remote process’s stdin and stdout are protocol traffic. Shell startup files and wrapper scripts must not print banners to stdout. Put diagnostics on stderr.
+
+This is a one-shot host. When the TUI exits or the transport fails, the local child is terminated, `tau rpc` shuts down its host, active work is interrupted, and durable state is recovered on the next process. Do not use this shape when work must continue through client disconnects; run `tau serve` instead.
+
+## List, select, create, or attach
+
+Without `--session` or `--new`, `tau attach` asks the host for its session list and opens an interactive selector:
+
+```sh
+tau attach ws://127.0.0.1:8787
+```
+
+The selector shows each session id and whether it is currently idle or running. It can also create a session. If stdin or stdout is not a TTY, selection is unavailable, so specify `--session` or `--new`.
+
+Attach directly when the session id is known:
+
+```sh
+tau attach \
+  --session 0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3 \
+  ws://127.0.0.1:8787
+```
+
+The equivalent SSH form is:
+
+```sh
+tau attach \
+  --session 0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3 \
+  -- ssh dev@buildbox.example tau rpc
+```
+
+Create a new session with an absolute cwd in the selected execution environment:
+
+```sh
+tau attach \
+  --new \
+  --cwd /srv/workspaces/tau \
+  ws://127.0.0.1:8787
+```
+
+For stdio/SSH:
+
+```sh
+tau attach \
+  --new \
+  --cwd /srv/workspaces/tau \
+  -- ssh dev@buildbox.example tau rpc
+```
+
+For the default `local` execution kind, this path is on the host machine, not the attaching machine. It must already be a usable directory with the desired repository or workspace. Tau creates the session, not the directory or repository.
+
+Remote `--new` supplies the conventional creation attribute `source: "tui"`. It does not infer repository metadata by inspecting the remote cwd. Clients that need repository provenance should create through the SDK or protocol and provide complete immutable attributes. See [sessions](sessions.md).
+
+`tau attach` does not accept the normal local startup persona flags. Select the server’s default at host startup, for example `tau serve --persona opus-5-coder`, or switch the newly created session with `/persona:<id>` after attaching.
+
+## Select an execution environment
+
+A session can use a local host directory, an already-provisioned Cloudflare Sandbox, or an already-provisioned Fly Sprite. In all cases, the execution cwd is an absolute path inside that environment.
+
+### Host-local directory
+
+`local` is the default:
+
+```sh
+tau attach --new --cwd /srv/workspaces/tau ws://host.example:8787
+```
+
+The host process executes agent-visible filesystem and command operations on its own machine. Tau does not clone, pull, or provision a repository.
+
+### Cloudflare Sandbox
+
+The host must already have a named bridge in `cloudflareSandbox.bridges`, and the sandbox must already exist:
+
+```sh
+tau attach \
+  --new \
+  --execution-kind cloudflare-sandbox \
+  --cloudflare-bridge production \
+  --cloudflare-sandbox sandbox-42 \
+  --cwd /workspace/tau \
+  wss://tau.example.com
+```
+
+`--cloudflare-bridge` identifies host configuration. `--cloudflare-sandbox` identifies an existing sandbox reachable through that bridge. Tau does not create the sandbox or copy a repository into it.
+
+### Fly Sprite
+
+The host must already have a named API target in `flySprites.apis`, and the Sprite must already exist:
+
+```sh
+tau attach \
+  --new \
+  --execution-kind fly-sprite \
+  --fly-api production \
+  --fly-sprite tau-build-7 \
+  --cwd /home/sprite/tau \
+  wss://tau.example.com
+```
+
+`--fly-api` identifies host configuration. `--fly-sprite` names an existing Sprite. Tau does not provision it or prepare its repository.
+
+Bridge URLs, API targets, home paths, and credential environment variables are host-owned [configuration](configuration.md). Session creation resolves Tau project configuration and content from the execution cwd through the selected environment. The execution environment itself remains a generic filesystem and process target; it does not own Tau’s configuration precedence or session policy.
+
+## Keep the ownership boundaries clear
+
+An attached session spans three logical machines even when two happen to share one operating system.
+
+### The attaching client owns
+
+- terminal rendering, editor drafts, clipboard operations, and local notifications
+- loaded themes and `defaultTheme`
+- `/listen`, `/speak`, and their local credentials and OS commands
+- the built-in or configured diff-tool process
+- configured command-backed client-tool processes
+- the client’s Tau binary and TUI behavior
+
+### The session host owns
+
+- session orchestration, persistence, and recovery
+- provider credential resolution and model execution
+- WebSocket authentication and listener lifetime
+- execution-environment resolver definitions and credentials
+- pending input while the session remains live
+- the host’s Tau binary and built-in agent documentation
+
+### The execution environment owns
+
+- the agent-visible cwd, home, files, and repository
+- project `.tau` content, model overlays, prompts, skills, and AGENTS.md files
+- command execution, platform, PATH, and runtime dependencies
+- automatic-compaction archives and other target-side temporary files
+
+This is why changing a host theme does not affect a remote TUI, why `!git status` runs against the execution environment, and why a custom diff application opens on the attaching machine. [Ownership and scope](ownership-and-scope.md) applies the same model across Tau.
+
+## Reload or restart the correct process
+
+Different changes have different owners:
+
+| Change | Action |
+| --- | --- |
+| Project config, model overlays, personas, prompts, skills, or AGENTS.md in the execution environment | Wait for idle, then run `/reload`. |
+| Effective model `apiKeys` in execution-environment or session configuration | Wait for idle, then run `/reload`; new sessions also resolve the current values. |
+| Managed Codex auth changed with `tau auth` | No host restart; auth storage is read again on later credential resolutions. |
+| Attaching themes, diff launcher, speech config, or configured client tools | Restart `tau attach`. |
+| Host process environment variables, history target, WebSocket listener, Cloudflare bridge, Fly API target, or host startup flags | Restart `tau serve` or the `tau rpc` process. |
+| Host Tau package, built-in tools, protocol, session recovery code, or built-in documentation | Upgrade and restart the host. |
+| TUI package, keybindings, rendering, local speech, or client-tool implementation | Upgrade and restart the attaching client. |
+
+`/reload` is a session operation. It asks the host to resolve session-owned content, including configured model `apiKeys`, from the execution environment and does not reload either process’s executable code or environment. Managed Codex auth storage is separate and is read again on later credential resolutions. For a long-running WebSocket host, restarting only the client cannot update the model-facing built-in docs or host tools. For an old client against a new host, restarting only the host cannot update local TUI behavior. See [credentials](credentials.md) for complete precedence and apply boundaries.
+
+## Reconnect and observe safely
+
+A WebSocket connection observes a hosted session; it does not own or delete it. If a TUI disconnects while a turn runs, the host keeps working. Reattach with the same session id to obtain the current persisted state and continue receiving updates.
+
+A clean `tau serve` shutdown interrupts active work, persists live sessions, and closes clients. On restart, the host lists sessions whose execution environments it can restore. Recovery returns sessions idle, drops pending queued and steering messages, discards live subagents, and changes an active persistent goal to blocked. Use `/goal resume` only after checking why the host stopped.
+
+A stdio/SSH connection is different because its RPC process is the host. Closing the connection ends that process. The session remains stored under the remote host user’s `~/.config/tau/sessions` and can be observed by a later `tau rpc` process using the same home and compatible resolver configuration.
+
+## Use multiple observers carefully
+
+Multiple WebSocket clients can observe the same live session and receive the same committed updates and pending-message state. They can also submit, queue, steer, interrupt, or mutate that session, so coordinate human or automation ownership rather than treating observers as read-only.
+
+Each ordinary TUI advertises client-owned `diff_review` and `prefill_input` tools plus enabled configured client tools. Only one observing client may advertise a given client-tool name for a session. Start additional observers with:
+
+```sh
+tau attach --no-client-tools --session 0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3 ws://host.example:8787
+```
+
+The host captures the available client-tool set when a turn starts. If the owning client detaches before a delegated call, that tool becomes unavailable; an active delegated call is cancelled. Client tools are not recovered after host restart until a client advertising them attaches again. See [client tools](client-tools.md).
+
+## Troubleshoot connection and recovery
+
+### The client reports an unsupported protocol version
+
+Tau’s current session protocol uses an exact version, not a compatibility negotiation. Upgrade the host and attaching client to the same Tau release, restart both processes, and reconnect. The host-facing agent uses tools and documentation from the host installation, while TUI behavior comes from the client installation.
+
+Avoid downgrading a host that has already written sessions with a newer storage format. Newer Tau versions migrate supported older session documents during normal recovery; older versions are not expected to understand newer documents.
+
+### A session is missing from the selector
+
+The host lists only stored sessions whose execution-environment kind it can currently restore. Confirm that:
+
+- the connection uses the same host user and home directory as the original process
+- the Cloudflare bridge id or Fly API id still exists in host configuration
+- host credentials are available to the restarted process
+- the target sandbox, Sprite, or local directory still exists
+- the session was created on this host rather than another machine with a different store
+
+Do not edit the session JSON to change environment identity. Restore the owning configuration or target instead.
+
+### WebSocket attachment is unauthorized
+
+Verify that server and client use the same token and that a reverse proxy preserves the WebSocket request path and query string. `TAU_WS_AUTH_TOKEN` can silently supply either side, so inspect the environment as well as command-line flags. Do not print the token in shared logs.
+
+### SSH attachment fails before the TUI opens
+
+Run the remote command directly and confirm that `tau rpc` is installed and can start. Protocol stdout must contain only NDJSON. Login banners, shell startup output, or wrapper diagnostics on stdout corrupt the transport; redirect them to stderr or remove them.
+
+### A reconnect shows an interrupted turn
+
+A client disconnect alone does not stop a WebSocket-hosted turn, but server shutdown does. Stdio/SSH attachment shutdown also ends its host. Review the last assistant and tool states, verify the execution environment with `!!pwd` and `!!git status --short`, then retry or resume a blocked goal intentionally. [Sessions](sessions.md) explains recovery and safe verification.

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

@@ -0,0 +1,188 @@
+# Security
+
+Tau gives an agent real tools for changing files, running processes, and calling configured services. Those tools execute when the model calls them. Tau does not insert a confirmation dialog, repository fence, or universal sandbox between a tool call and its owner.
+
+Safe operation therefore starts with authority: decide which machine may be changed, which credentials it may hold, and which project content is trusted before starting a session. The [ownership and scope](ownership-and-scope.md) page defines the client, host, execution environment, and Telegram runner used below.
+
+## Direct execution and operating-system authority
+
+Host tools such as `bash`, `write`, and `edit` act through the session execution environment. They inherit the operating-system permissions of that environment and are not confined to the repository root. Absolute paths are accepted when the operating system permits them. File and process side effects persist even if tool output is later truncated, a turn is interrupted, or the model request fails.
+
+Client tools are a separate authority. A command client tool runs as the owning client user, with that process's current directory and inherited environment. Its execution-environment facade can additionally request commands on the session target. A remote session can therefore expose two independent operating-system authorities to one logical turn.
+
+Use the narrowest practical authority for each role:
+
+- Run Tau and its execution environment as a dedicated, unprivileged user when the workspace does not need access to a personal home directory.
+- Use a container, virtual machine, or separately provisioned hosted environment when work should be isolated from the host. Tau preserves that external boundary, but it does not claim that every configured backend is a security sandbox.
+- Mount or copy only the repositories and files the task needs. Do not point an execution environment at a broad home directory for convenience.
+- Give the host only the provider and service credentials needed for its sessions. Give client-tool processes only the client-local credentials they need.
+- Use a persona with a narrower `tools` list for work that should not modify files or invoke external services. Remember that main-session goal tools and intrinsic `tau_docs` do not come from that list.
+
+Interruption, timeouts, output limits, and process-group termination bound execution. They are not approval controls and cannot undo an operation that already completed. Review destructive commands and use Tau's normal session operations instead of asking an agent to manipulate internal state.
+
+## Treat project content as executable policy
+
+The execution environment supplies more than source files. Tau can load project `.tau/config.json`, `.tau/models.json`, personas, prompts, skills, `.agents/skills`, and `AGENTS.md` from the working directory and its discovery path. This content can change model endpoints and headers, select tools, add instructions, define workflows, or alter which globally trusted client tools are advertised.
+
+A repository checkout is therefore part of Tau's trust boundary. Before using it with meaningful credentials or write access, inspect relevant `.tau/`, `.agents/`, and `AGENTS.md` content, including nearer nested levels. Pay particular attention to:
+
+- persona system prompts, tool lists, subagent definitions, and model launch allowlists;
+- skill instructions and any scripts they direct the agent to run;
+- model overlays that replace endpoints, headers, capabilities, or token limits;
+- project configuration that supplies API keys, Nook targets, model notices, or hosted-environment definitions;
+- `enabledClientTools`, which can select commands previously trusted in the user's global configuration; and
+- provision scripts or other repository automation used by integrations such as Telegram.
+
+Project configuration cannot define a command client-tool executable. It can only select definitions from global configuration. That restriction prevents a checkout from directly introducing a new client process, but it does not make a selected command harmless.
+
+`--no-agent-context-files` disables `AGENTS.md` and configured context injection. It does not disable project configuration, personas, skills, model overlays, or tools. `--no-client-tools` disables TUI-provided tools, not host tools. Use the appropriate control rather than treating either flag as a general safe mode.
+
+Prompt templates are inserted into the editor for review rather than submitted automatically. Leading `<system>` blocks, persona prompts, model notices, and committed session messages are model-facing and may become durable session content. Do not place secrets in instructions, prompts, or model notices.
+
+## Keep secrets with the process that needs them
+
+Most model and service credentials belong to the host because the host performs model calls, web search, history replication, and host-tool Nook requests. TUI speech credentials and command client-tool credentials belong to the client. Telegram bot and transcription credentials belong to the Telegram runner. Hosted-environment bridge and API credentials belong to host startup.
+
+In a remote attachment, a credential exported on the laptop does not authenticate the remote host. Conversely, putting a host credential into the execution target's shell environment unnecessarily exposes it to target processes. Follow [credentials](credentials.md) for exact resolution precedence.
+
+Prefer host process environment variables or private global configuration over project files for personal secrets. Some integrations support a configuration field that names an environment variable, which keeps the secret value out of JSON. Telegram currently stores each bot token in its separate runner configuration file, so protect that file as secret material.
+
+Never put credentials in:
+
+- committed `.tau/config.json` or `.tau/models.json` files;
+- persona, prompt, skill, `AGENTS.md`, or model-notice text;
+- Bash command lines likely to enter shell history or process listings;
+- tool results, session messages, issue comments, or debug output; or
+- Nook static assets or browser KV.
+
+Do not diagnose authentication by dumping an environment, configuration file, `auth.json`, or service response containing headers. Check whether the expected source is configured on the owning process, then exercise a small operation that uses it. `tau auth list` reports Codex account identity and health without displaying tokens.
+
+If a credential appears in a session, log, shell history, repository, Nook deployment, Telegram message, or transcript history, treat it as exposed. Revoke or rotate it at the provider first, replace the stored value through the supported configuration or auth command, restart the owning process when needed, and remove the exposed copy from systems where retention policy permits. Redaction is not a substitute for rotation.
+
+## Understand environment sanitization
+
+Local execution-environment commands start from a sanitized copy of the Tau process environment. Tau removes inherited variables whose names end in `_KEY`, `_SECRET`, `_TOKEN`, or `_PASSWORD`, and the exact name `API_KEY`. This reduces accidental leakage from a local host into ordinary agent Bash commands.
+
+The filter is deliberately limited:
+
+- It is name-based, so a secret under another name is not recognized.
+- Explicit execution-environment overrides are applied after sanitization and can reintroduce a value.
+- Hosted execution backends start from the target environment supplied by that backend.
+- Command client tools inherit the client process environment unchanged.
+- Host-owned model and service code can access the host credentials it is designed to consume.
+
+Do not rely on sanitization as a secret store or authorization boundary. Avoid broad environment inspection, and keep secrets out of any process that does not need them.
+
+## Keep login shells automation-safe
+
+Tau command execution uses a fresh non-interactive login Bash. The execution environment's `HOME` controls login startup discovery. Bash can read `/etc/profile`, the first available user login file, and `BASH_ENV`; a login file may also source `.bashrc`.
+
+These files execute with the same operating-system authority as every tool command. A compromised or overly broad startup file can change `PATH`, run commands, disclose data, terminate the shell, or corrupt protocol output. Review startup files in each execution environment, especially targets created from shared images or user homes.
+
+Startup files must not print banners, prompt for input, read stdin, require a TTY, launch an editor, or exit the shell unexpectedly. Tau does not suppress their output. There is no TTY, and ordinary agent Bash calls have no stdin, so interactive authentication and terminal prompts fail or wait until timeout. Configure Git, SSH, package managers, and cloud CLIs for deliberate noninteractive use.
+
+`tau rpc` has an additional constraint: stdout is the NDJSON protocol. Shell banners and wrapper diagnostics on stdout break the transport. Send diagnostics to stderr.
+
+## Trust command client tools as local programs
+
+Command client tools are defined only in user-owned global configuration, then selected for a project. Tau starts the configured executable directly, without a shell, and validates model arguments against its configured object schema. The command still runs as trusted local code with the client's full inherited environment and filesystem permissions.
+
+Before enabling one:
+
+1. Review the executable and pin or control how it is updated.
+2. Use a narrow schema and describe side effects accurately for the model.
+3. Avoid building shell source from model-provided strings. Prefer fixed commands and argument arrays.
+4. Honor cancellation and set a bounded execution timeout.
+5. Return only the data the model needs, with diagnostics on stderr.
+6. Use the execution-environment facade only for work that truly belongs on the session target.
+
+A project `enabledClientTools` list is permission to select an already trusted global definition. Unknown selected names are ignored, so verify effective advertisement after changes. Start an untrusted project with `--no-client-tools` until its selection has been reviewed.
+
+The TUI's diff launcher is also a client-local process. A custom `diffTool.command` and its configured environment should be treated as trusted code.
+
+## Use code mode as a capability boundary
+
+The generated JavaScript used by `web`, `history`, `nook`, and code-mode client tools runs in Tau's bounded worker runtime. It receives only a declared API, `docs`, console output, live `Date`, `Math.random()`, and, when configured, agent-scoped UTF-8 scratch files. Generated code has no direct imports, process, environment, credentials, timers, `fetch`, or arbitrary network access.
+
+API handlers run outside that worker and retain the authority deliberately exposed by the tool. The boundary therefore limits generated code to declared capabilities, but it does not make an overpowered API safe. Tool authors should validate every argument, expose narrow operations, keep credentials in the parent, enforce cancellation, and avoid returning secrets.
+
+Scratch files live in a private execution-environment temporary directory derived from the agent id. They are shared across code-mode tools for that agent, are not persisted in the session snapshot, and are not a durable secret store. Their limits and temporary lifetime are described in [tools](tools.md).
+
+The `history` code-mode API is read-only, but it can see transcripts across repositories and execution environments in the configured collection. Its agent policy requires a direct user or active-instruction request before use. That policy does not replace access control on the history service.
+
+## Protect remote session transports
+
+`tau serve` binds to loopback by default. Keep that default unless remote network access is required. A WebSocket server without `--auth-token` or `TAU_WS_AUTH_TOKEN` is unauthenticated, and any connected client can observe and mutate hosted sessions.
+
+The server's token grants full session access. Tau places it in the WebSocket connection URL as the `tau_token` query parameter. Use a strong random value, avoid command-line literals that enter shell history, and ensure reverse proxies and access logs do not record it.
+
+Tau's listener is plain WebSocket and has no certificate configuration. Across an untrusted network, use one of these patterns:
+
+- bind Tau to loopback and forward it through SSH;
+- place it behind a trusted TLS reverse proxy and connect with `wss://`; or
+- keep it on a private network whose access controls and confidentiality are understood.
+
+A reverse proxy must preserve WebSocket upgrade behavior and the request query string while protecting both. Restrict who can reach the listener even when a token is configured. Multiple observers are active participants, not read-only viewers: they can submit, steer, interrupt, rewind, and advertise client tools. See [remote sessions](remote-sessions.md).
+
+Stdio attachment relies on the security of the launched command, commonly SSH. Closing that transport also closes its one-shot host. Use a long-running authenticated WebSocket host when work must survive client disconnects.
+
+## Secure Telegram access and workspaces
+
+A Telegram runner is both a network-facing client and a local Tau host. Its bot configuration determines who can create turns that may execute tools in configured workspaces.
+
+Set `allowedUserIds` for authorized senders and `allowedChatIds` for authorized chats. If these lists are absent, private chats are not restricted by that dimension. Group chats are ignored unless their chat id is explicitly present in `allowedChatIds`, and group turns require an explicit bot mention. Messages, attachments, audio transcripts, and processing errors from an allowed group can become pending context for a later triggering turn, so membership and chat history are part of the trust decision.
+
+Each bot's `allowedProjectIds` should expose only intended projects. Telegram chat sessions are scoped by bot and chat, but a persistent-directory project deliberately reuses one existing directory across all of that project's sessions. Work in one session is visible to later sessions and to other authorized chats selecting the same project. Do not configure a personal home, credential directory, or unrelated shared tree as a persistent project.
+
+Repository and composite projects use managed workspaces and persistent bare caches. New or reconstructed repositories may execute an executable `.tau/scripts/provision` asynchronously. Review that script as trusted project automation. Persistent-directory projects are not provisioned and are never deleted by Tau.
+
+Protect the runner configuration, generated session state, project-preference state, managed workspace root, and attachment temporary storage with an appropriate OS account and filesystem permissions. Do not run two Telegram runners against the same state. Operational details are in [Telegram](telegram.md).
+
+## Know what history retains
+
+Tau writes a flat transcript history in the host home independently of recoverable session snapshots. It contains committed user entries, assistant text, and completed tool entries. Compaction does not remove it. Rewind truncates entries after the selected boundary, but history is not an ephemeral cache.
+
+Without remote history configuration, this collection stays in the host's local SQLite database. The `history` tool can search the complete machine-local collection, subject to its persona and invocation policy. Protect the host account and database as transcript data.
+
+When global `history` configuration is present, local SQLite remains the first durable write and a persistent outbox replicates operations to the configured service asynchronously. Remote entry projections are byte-bounded and large payloads are middle-truncated, but they can still contain source code, tool output, instructions, and personal data. The deployed service also generates semantic digests from transcript content through its configured Cloudflare AI service.
+
+Before enabling remote replication, confirm the service owner, retention policy, region, access-key distribution, and acceptable project scope. One service credential can query the shared remote collection. Rotate it if exposed, and do not assume removing the client configuration deletes data already replicated. See [history](history.md) for storage and service behavior.
+
+## Treat Nook output as published content
+
+Nook deploys static files to path-based HTTPS URLs. Deployments are private by default; `--public` makes the site assets anonymously reachable. Review the built output, not just source files, before deployment. Static assets must never contain provider keys, source maps with secrets, private configuration, or data that should remain on the execution environment.
+
+Each site has browser JSON KV that survives redeploys. Public-site KV is anonymously readable and writable. Private-site KV requires Cloudflare Access identity, but it is still application data available to authorized browser users and site code. It is not a credential vault.
+
+Cloudflare Access should protect only the root `/__nook/*` control plane. Public site paths must remain reachable without Access, while private navigation authenticates through `/__nook/auth`. The Nook Worker validates Access JWTs; raw service-token headers only pass the outer Access policy. Follow the exact Access application, audience, cookie, and service-auth setup in [Nook](nook.md).
+
+The host-owned Nook tool and `tau nook` CLI can deploy, delete, copy, and modify KV without a separate confirmation layer. Code-mode JavaScript never receives Access credentials directly, but the parent Nook client acts with them on approved API calls.
+
+## Edit configuration without widening authority accidentally
+
+Configuration changes can redirect network traffic, expose tools, or move credentials across trust boundaries. Use this sequence:
+
+1. Identify the consuming component and its machine, `cwd`, home, and Tau version.
+2. Read the exact version-matched field contract in [configuration](configuration.md) and [configuration reference](config-reference.md).
+3. Inspect nearer configuration levels that may replace or merge the field.
+4. Back up only the user-authored file being changed, with permissions no broader than the original.
+5. Make the smallest edit at the narrowest valid scope. Keep secrets out of project files.
+6. Validate JSON or frontmatter without printing the whole file into a shared transcript.
+7. For a local startup, use `tau --debug` from the relevant directory when its potentially sensitive prompt output can remain private. For a live session, use `/reload` while idle and read every warning.
+8. Restart the owning client, host, or runner when the field is startup-owned. Test one small operation before resuming broader work.
+
+Unknown configuration fields are stripped, so syntactically valid JSON can still have no effect. Invalid nearer values may be skipped, leaving a broader value effective. Verify behavior rather than assuming the edited value won.
+
+## Do not edit durable internals
+
+Tau's durable files are implementation-owned recovery state, not configuration surfaces. Do not directly edit or casually delete:
+
+- `~/.config/tau/auth.json`;
+- files under `~/.config/tau/sessions`;
+- `~/.config/tau/history.sqlite` and its SQLite side files;
+- Telegram runner session and project-preference state;
+- managed Telegram workspaces or repository caches as a first-line repair;
+- code-mode or compaction temporary files as if they were durable state; or
+- Nook R2 or Durable Object records outside supported Nook operations.
+
+Use `tau auth` for Codex accounts, session protocol and TUI operations for sessions, normal configuration for behavior, and documented service commands for History and Nook. If recovery reports corruption, preserve the original data, stop competing writers, record the exact error and installed version, and investigate through normal recovery before considering any destructive repair.