@markusylisiurunen/tau 0.3.49 → 0.3.50

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

@@ -0,0 +1,264 @@
+# Nook
+
+Nook is Tau's optional platform for publishing small static applications at path-based URLs. It combines built front-end assets with per-site JSON KV, while keeping deployment and authenticated management under Tau's host-owned Nook client.
+
+Nook is intentionally narrow in V0. It is a Cloudflare-only static host, not a general application runtime. Build an app before deploying it. Nook does not run per-site server code, provision custom domains per app, provide rollback history, or turn a source repository into a build pipeline.
+
+## V0 at a glance
+
+A Nook deployment has one configured hostname and many sites:
+
+```text
+https://apps.example.net/roadmap/
+https://apps.example.net/release-notes/
+```
+
+Each site has one active static deployment, a visibility of `private` or `public`, and independent JSON KV that survives redeploys. Templates are separately stored editable directory snapshots. They can be copied to a working directory, changed and built with ordinary tools, then deployed explicitly.
+
+V0 does not provide dashboards, wildcard subdomain site URLs, deploy rollback, audit logs, ownership roles, realtime APIs, AI proxy APIs, ignore files, or provider abstraction. `.gitignore` and `.nookignore` have no special meaning. The deploy directory itself must contain only the files intended for publication.
+
+## Ownership and apply boundaries
+
+Nook crosses three Tau boundaries:
+
+- Cloudflare owns the deployed Worker, route, R2 assets, Durable Object state, DNS, and Access application.
+- The Tau CLI or session host owns Nook credentials and authenticated management HTTP.
+- A session execution environment owns any paths read or written by the `nook` agent tool.
+
+`tau nook` CLI paths are local to the process running the command. Agent-tool paths belong to the session execution environment, even when the host is on another machine. Generated code never receives the Access secret, ambient filesystem, process environment, arbitrary network access, or `fetch`.
+
+The `nook` config block can appear at global or project scope, and the most-specific complete object wins. A session picks it up on creation or `/reload`. CLI commands load the effective config for the command's startup working directory. See [configuration](configuration.md) and [ownership and scope](ownership-and-scope.md) before operating Nook from an attached or hosted session.
+
+## Set up the Cloudflare deployment
+
+Before setup, prepare:
+
+- a Cloudflare account and zone for the chosen hostname
+- Wrangler installed on `PATH`
+- `CLOUDFLARE_API_TOKEN` available for non-interactive Wrangler authentication
+- npm and network access so Tau can prepare the bundled Worker package
+- a Cloudflare Access self-hosted application design for the control plane
+
+Run:
+
+```sh
+tau nook setup \
+  --domain apps.example.net \
+  --zone-name example.net \
+  --access-team-domain https://engineering.cloudflareaccess.com \
+  --access-aud 7f20d9d8c3a14f1fa8c3a5513b91d440
+```
+
+The command deploys the bundled Worker as `tau-nook`, creates or reuses the `tau-nook-assets` R2 bucket, and configures a route for `apps.example.net/*`. It writes the Access team domain and application audience into the Worker configuration so the Worker can validate Access identity.
+
+The same inputs can come from `NOOK_DOMAIN`, `NOOK_ZONE_NAME`, `NOOK_ACCESS_TEAM_DOMAIN`, and `NOOK_ACCESS_AUD`. Explicit flags replace the corresponding environment values.
+
+Setup does **not** create DNS records, an Access application, Access policies, or a service token. Complete those steps in Cloudflare after deployment.
+
+## Configure the Access topology
+
+Create one self-hosted Cloudflare Access application for exactly:
+
+```text
+https://apps.example.net/__nook/*
+```
+
+Do not protect the entire hostname. Public site assets must be able to reach the Worker anonymously, while management stays behind the control plane.
+
+For that Access application:
+
+1. Use the audience passed to `--access-aud`.
+2. Disable the **Cookie Path Attribute**, allowing the Access cookie to apply to the hostname rather than only `/__nook/*`.
+3. Add user Allow policies for people who may open private sites.
+4. Add a Service Auth policy for a Cloudflare Access service token used by Tau.
+5. Configure DNS for the chosen hostname and verify it routes to the Worker.
+
+This topology has two distinct paths:
+
+- `/__nook/*` is the Access-protected management and authentication control plane.
+- `/<site>/*` is the site plane. Public sites are anonymous; private sites redirect browser navigation through `/__nook/auth` and then rely on the hostname-scoped Access identity.
+
+Tau sends service-token headers only to pass Cloudflare Access. The Worker authorizes requests by validating the Access JWT, not by trusting those raw headers directly.
+
+## Configure Tau
+
+Create the Access service token, then add one Nook target to the effective Tau config:
+
+```json
+{
+  "nook": {
+    "domain": "apps.example.net",
+    "accessClientId": "service-token-id.access",
+    "accessClientSecretEnv": "NOOK_ACCESS_CLIENT_SECRET"
+  }
+}
+```
+
+`domain` is required and must be a DNS hostname without a path, port, query, or fragment. The remaining fields are optional in the schema, but an Access-protected management plane normally requires both a client ID and a resolvable secret.
+
+The secret resolves in this order:
+
+1. a non-empty environment variable named by `accessClientSecretEnv`
+2. inline `accessClientSecret`
+
+There is no separate standard-variable override for ordinary Nook operations. `NOOK_ACCESS_CLIENT_SECRET` has special meaning only when the config names it, and as a destroy-command input described later. Keep the secret on the process performing the operation: the invoking CLI process for `tau nook`, or the session host for the agent tool. See [credentials](credentials.md).
+
+Restart a CLI process after changing its environment. For a live session, run `/reload` while idle after changing the config visible from its execution-environment working directory.
+
+## Deploy and inspect sites
+
+Deploy a finished static directory:
+
+```sh
+tau nook deploy ./dist --site roadmap
+tau nook list
+```
+
+CLI deployments are private by default. Add `--public` only when anonymous access, including anonymous browser KV writes, is intended:
+
+```sh
+tau nook deploy ./dist --site roadmap --public
+```
+
+Every successful deploy replaces the complete active asset set and sets visibility from that command. Omitting `--public` on the next deploy makes the site private again. Per-site KV survives either change.
+
+Site slugs are 2 to 63 lowercase letters, digits, or hyphens, and must start and end with a letter or digit. Tau reserves `admin`, `api`, `assets`, `login`, `logout`, `nook`, `quick`, `static`, and `www`.
+
+A site is served at `https://<domain>/<slug>/`. A request to `/<slug>` redirects to the trailing-slash URL. When an extensionless site path is absent, Nook serves root `index.html` as a single-page-app fallback; missing paths with file extensions return not found. Apps should use relative asset URLs or be built with a base path of `/<slug>/`.
+
+To recover the active deployment files into a local working directory:
+
+```sh
+mkdir restored-roadmap
+tau nook copy roadmap ./restored-roadmap
+```
+
+The destination must already exist and be empty. Tau downloads the complete active manifest and verifies file sizes and hashes before writing. Copy does not include the site's KV data.
+
+Delete a site only when both its active assets and managed site state are no longer needed:
+
+```sh
+tau nook delete roadmap
+```
+
+Site deletion is destructive and Nook V0 has no rollback history.
+
+## Artifact rules and limits
+
+A deploy directory must contain root `index.html`. Tau walks the complete directory and rejects it if any path violates these rules:
+
+- hidden files or directories are forbidden, including `.env`, `.git`, and `.DS_Store`
+- symlinks are forbidden
+- paths under `/__nook` are reserved
+- traversal, absolute filesystem paths, null bytes, duplicate paths, and non-normalized paths are forbidden
+- at most 1,000 files may be deployed
+- each file may be at most 10 MiB
+- total content may be at most 100 MiB
+- each deployed path may be at most 512 characters
+
+Tau chooses common content types from file extensions and uses `application/octet-stream` otherwise. Uploads are checked against their declared size and SHA-256 digest. Stable asset URLs require cache revalidation, so replacing a deployment does not rely on content-hashed URLs for freshness.
+
+Nook does not apply ignore files. Build into a clean output directory rather than deploying a repository root. In particular, do not work around the hidden-file rejection by copying credentials into visible files.
+
+## Templates
+
+Templates are reusable directory snapshots in the configured Nook deployment. They are not sites, do not perform substitution, and do not run installs or builds.
+
+```sh
+tau nook template save vite-static ./starter
+tau nook template list
+mkdir next-app
+tau nook template copy vite-static ./next-app
+```
+
+`save` creates or replaces the named template. `copy` requires an existing empty destination and verifies all downloaded files before writing. A template follows the same path, hidden-file, symlink, file-count, and byte limits as a deployment, but it does not require root `index.html`.
+
+Template names use the same 2 to 63 character lowercase path-label format as site slugs. Site-reserved names are not reserved for templates.
+
+Delete a template only when its stored editable snapshot is no longer needed:
+
+```sh
+tau nook template delete vite-static
+```
+
+Deleting a template does not delete sites that were built from it.
+
+## Manage per-site KV
+
+Nook KV is scoped to one site and stores JSON values. The CLI provides direct operations:
+
+```sh
+tau nook kv put roadmap settings '{"theme":"dark"}'
+tau nook kv get roadmap settings
+tau nook kv list roadmap --prefix releases/
+tau nook kv delete roadmap settings
+```
+
+The `put` value must be valid JSON. Keys are 1 to 256 characters. Each value is limited to 64 KiB, and each site is limited to 1,000 keys and 5 MiB total JSON storage.
+
+Browser applications use same-origin per-site KV. Public deployments expose both the static app and browser KV anonymously, which means the KV is **public-writable**. Do not store secrets, access tokens, private user data, or integrity-critical state in a public site's KV. Private deployments require a valid Cloudflare Access identity for site navigation and browser KV.
+
+CLI and agent management operations use the Access-protected control plane rather than the browser route. The browser SDK contract and code examples belong to the deployment's version-matched Nook skill and are intentionally not duplicated here.
+
+## Use the host tool
+
+The assistant-facing `nook` tool appears only when both conditions hold:
+
+- the current persona selects `nook`
+- effective session configuration contains a valid `nook` block
+
+The tool is host-owned. It performs authenticated Nook HTTP outside generated code and uses the session execution backend for deploy, copy, template, and file-backed KV paths. It should be invoked only for an explicit Nook, publishing, hosting, or Nook KV task.
+
+The tool has two separate documentation stages:
+
+1. Its first call for a task prints and reads the built-in `docs`, which describe the installed management API.
+2. Before authoring or modifying a Nook app, a separate documentation-only call retrieves and prints `nook.skill()`. The agent reads that deployment-provided guide before writing files in later calls.
+
+Do not combine skill retrieval with management operations, and do not guess either API from this page. The deployed skill owns browser SDK and app-authoring behavior so it stays version-matched to that Nook deployment. General tool eligibility and code-mode behavior are covered in [tools](tools.md).
+
+## Verify a deployment
+
+Verify from both management and browser perspectives:
+
+1. Run `tau nook list` from a directory whose effective config contains the intended target.
+2. Deploy a small nonsensitive private site with root `index.html`.
+3. Open its trailing-slash URL in a browser and complete Access login.
+4. Confirm that its assets resolve beneath the site path.
+5. Exercise a disposable KV key through the app or CLI, then delete it.
+6. If public access is required, redeploy with `--public` and test from a browser without an Access session.
+
+A successful Worker deployment alone does not prove that DNS, Access cookie scope, user policy, service-token policy, or Tau credentials are correct.
+
+## Common errors
+
+**`nook is not configured`.** Add the `nook` block at a config level visible to the command or session. For an agent session, run `/reload` while idle or create a new session.
+
+**A CLI command receives an Access login page or authorization error.** Confirm that Access protects only `/__nook/*`, the service token has a Service Auth policy, both token fields resolve in the invoking process, and the configured domain matches the deployed hostname.
+
+**A private site repeatedly redirects or browser KV reports authentication required.** Disable the Access application's Cookie Path Attribute and confirm the user Allow policy and audience. The cookie must be valid across the hostname so the Worker can authorize `/<site>/*` after `/__nook/auth`.
+
+**A public site still asks for Access.** The Access application probably covers the whole hostname rather than only `/__nook/*`, or the latest deploy omitted `--public` and made the site private again.
+
+**Assets work at `/` during local development but fail after deploy.** Build for the `/<site>/` base path or use relative URLs. Nook does not rewrite arbitrary absolute asset references.
+
+**Deploy rejects hidden files or symlinks.** Use a clean build output. Ignore files do not change Nook's manifest walk.
+
+**Copy refuses the destination.** Create an empty directory first. Tau will not merge downloaded files into existing contents.
+
+**The agent cannot see the tool.** Check both the persona's tool list and effective `nook` config. A config block alone does not override persona tool eligibility.
+
+## Destroy the platform
+
+Destroy removes platform data and infrastructure, not just one site. It first calls the authenticated cleanup endpoint to delete site Durable Object data and Nook R2 objects, then attempts to delete the `tau-nook` Worker and `tau-nook-assets` bucket.
+
+Use environment variables for cleanup credentials so secrets do not enter shell history:
+
+```sh
+tau nook destroy --domain apps.example.net --yes
+```
+
+The command reads `NOOK_ACCESS_CLIENT_ID` and `NOOK_ACCESS_CLIENT_SECRET`; flags with the same names are also accepted but expose values more easily. It also accepts `NOOK_DOMAIN` instead of `--domain`, and requires `CLOUDFLARE_API_TOKEN` for Wrangler.
+
+This operation is destructive. Confirm that all sites, templates, and KV are disposable or separately preserved before running it. If authenticated data cleanup fails, Tau stops before deleting infrastructure. Worker or bucket deletion failures are reported separately and can leave a partial deployment, so inspect every result line.
+
+Destroy does not remove external DNS records, the Cloudflare Access application, its policies, or service tokens. Remove those separately after confirming the Nook hostname is no longer serving needed data, then remove obsolete Tau config and credentials.

package/dist/core/static/tau_docs/ownership-and-scope.md

@@ -0,0 +1,104 @@
+# Ownership and scope
+
+Tau separates terminal interaction, session orchestration, and agent-visible execution even when all three happen in one process. This is the most important fact to establish before changing a path or configuration file. In an attached session, “local” can refer to three different machines.
+
+## The four operating roles
+
+### Client
+
+The **client** is the interface attached to a session host. The terminal client owns the TUI, editor state, terminal colors, active theme, local speech commands, the diff-review process, and configured command client tools. An SDK program or Telegram adapter can also be a client.
+
+Client tools execute on the client machine, not wherever the agent's Bash tool runs. Client-local configuration is discovered from the client's startup working directory and home.
+
+### Host
+
+The **host** creates, observes, persists, and recovers sessions. It owns model calls, credentials, session orchestration, tool binding, history storage, and execution-environment lifecycle. Local `tau` creates an in-process host. `tau serve` and `tau rpc` are standalone host entry points.
+
+The host's home owns data such as session snapshots, authentication storage, usage logs, and the local history database. Use Tau commands and session operations to manage these stores rather than editing their files directly.
+
+The intrinsic `tau_docs` tool is also host-owned. It reads documentation packaged with the installed host version.
+
+### Execution environment
+
+The **execution environment** is the machine the agent can act on. It owns the agent-visible working directory (`cwd`), home, platform, environment, filesystem, processes, project repository, project configuration and content, `AGENTS.md` files, model overlays, skills, and command resolution.
+
+Tau asks the execution environment to read or execute against those resources. The host must not treat its own filesystem as a shortcut, even when a local execution environment happens to share it.
+
+A session has one authoritative execution-environment snapshot. Paths shown to the agent and paths passed to agent tools are execution-environment paths.
+
+### Telegram runner
+
+The **Telegram runner** owns Telegram polling, chat routing, attachments, outbound messages, project selection, and Telegram-specific persisted runner state. It is a client of local in-process Tau sessions and also starts their host on the runner machine.
+
+For repository and composite projects it prepares managed workspaces. A configured persistent directory project reuses the specified directory. Those workspaces become local execution environments for their sessions. The separate file passed to `tau telegram --config-file` is runner configuration, not a Tau `config.json` level.
+
+## Where each mode runs
+
+| Mode | Client | Host | Execution environment |
+| --- | --- | --- | --- |
+| `tau` | Local TUI process | In-process on the same machine | Local `cwd` where Tau started |
+| `tau attach … ws://…` | Machine running `tau attach` | Machine running `tau serve` | Environment selected or restored by that host |
+| `tau attach … -- <command>` | Machine running `tau attach` | Machine running the protocol command, often reached through SSH | Environment selected or restored by that host |
+| `tau rpc` or `tau serve` | A separate protocol client | The server process | Local or configured hosted environment chosen by the client |
+| Default Node SDK client | SDK caller | In-process with the SDK caller | Usually a local environment supplied at session creation |
+| SDK over WebSocket or stdio | SDK caller | Remote server or command process | Environment selected or restored by that host |
+| `tau telegram` | Telegram runner | In-process on the runner machine | Prepared project workspace or persistent directory |
+
+A Cloudflare Sandbox or Fly Sprite can place the execution environment on another target while the host stays on its own machine. The host keeps provider credentials and orchestration authority; the target owns its paths and commands.
+
+## Who owns common paths and behavior
+
+| Resource or behavior | Canonical owner | Consequence |
+| --- | --- | --- |
+| Agent `cwd`, home, repository, files, and commands | Execution environment | Use target paths in prompts, `session.create`, and agent tool calls. |
+| `.tau/config.json`, `.tau/models.json`, personas, prompts, skills, and `AGENTS.md` used by a session | Execution environment | Edit them on the target and relative to the session `cwd`. |
+| Global runtime content for a session | Execution-environment home | `~/.config/tau` is the target user's home when runtime content is collected. |
+| Model and host-tool credentials | Host | Set environment secrets where the host process runs. Runtime `apiKeys` may be loaded from execution-environment config and consumed by the host. |
+| Codex OAuth accounts | Host home | Run `tau auth …` on the host machine. Do not edit auth storage. |
+| Session snapshots | Host home | Local defaults live under the host's Tau config directory. Do not edit session files. |
+| Local transcript history and remote history outbox | Host home | History follows the host, not an attached TUI or execution target. |
+| Terminal theme and `/theme` | TUI client | An attached client uses themes loaded on the client machine. Themes are not session state. |
+| `/diff` process | TUI client | `diffTool.command` must exist on the client machine. Repository capture still runs through the session execution environment. |
+| Configured command client tools | Owning client | Commands and their environment are client-local; their execution-environment facade reaches the session target explicitly. |
+| `/listen` and `/speak` capture or playback | TUI client | Required programs, devices, and media credentials belong on the client machine. |
+| Host execution-environment targets | Host startup | Cloudflare bridge and Fly Sprite API definitions must be available to the host before it accepts sessions using them. |
+| Telegram bot token, routing, workspaces, and generated runner state | Telegram runner | Manage these through the Telegram config and runner commands, not project `config.json`. |
+
+## Decide where to edit configuration
+
+Start from the behavior that consumes the setting:
+
+1. If it changes what the agent sees or can do in the project, edit configuration or content in the execution environment's discovery path.
+2. If it changes terminal rendering, `/diff`, `/listen`, or a command client tool, edit the TUI client's configuration and restart that client.
+3. If it changes credentials, session persistence, remote history, or available hosted-environment resolvers, edit or export it for the host process and restart the host when required.
+4. If it changes Telegram routing or workspace preparation, edit the runner's `--config-file` on the runner machine.
+
+For a local `tau` session these locations often collapse to one home and repository. The ownership rule still predicts remote behavior and prevents configuration from being placed on the wrong machine.
+
+## A remote configuration example
+
+Suppose a laptop runs:
+
+```sh
+tau attach --new --cwd /srv/ledger ws://devbox.example:8787
+```
+
+The path `/srv/ledger` is interpreted by the host and its local execution environment. Project personas and `.tau/config.json` are read from `/srv/ledger` and its ancestors on `devbox.example`. The laptop's current directory does not influence that session runtime.
+
+The laptop still loads its own theme, `diffTool`, and command client tools before attaching. If `/diff` launches `review-ui`, that executable must exist on the laptop. Git snapshot commands for the review run through the session and therefore see `/srv/ledger` on the execution environment.
+
+If the selected persona needs a provider credential, the host on `devbox.example` makes the model call. Export the provider environment variable for `tau serve` there, or make the appropriate runtime configuration available to that host. Setting it only in the laptop shell does not authenticate the remote host.
+
+## Home has a boundary too
+
+Tau includes global configuration only when the relevant `cwd` is equal to or below that component's home. For execution runtime discovery, both values belong to the execution environment. For client-local startup discovery, they belong to the client.
+
+This matters when a remote or hosted environment uses a project outside its configured home. In that case Tau walks project levels to the filesystem root but does not inject `~/.config/tau` from some other machine or home.
+
+## What `tau_docs` can and cannot tell you
+
+`tau_docs` documents contracts shipped with the host. It can explain valid fields, paths, precedence, and supported behavior for that installed host version.
+
+It cannot inspect effective configuration, current environment variables, loaded client tools, the active TUI theme, attached-client versions, or files on a client machine. An attached client can be a different Tau version from the host. Use client commands and direct inspection on the owning machine for client-local questions, and use session-visible warnings or host-side inspection for effective runtime questions.
+
+See [configuration](configuration.md) for level discovery and change boundaries, [remote sessions](remote-sessions.md) for attach and server operation, and [security](security.md) for trust implications.

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

@@ -0,0 +1,199 @@
+# 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, skills, and subagents. Changing persona changes how future turns run without creating a new 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.
+
+## 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, skills, and the built-in `default` subagent.
+
+Set `disableBuiltinPersonas: true` in `config.json` to omit built-ins from the effective catalog. Custom personas can also replace a built-in by using the same ID. A shipped built-in is therefore not necessarily available in a particular session.
+
+Use one of these to inspect the current effective list:
+
+```sh
+tau --help
+tau --debug
+```
+
+`tau --debug` also prints full effective prompts and project context. Use it only where that output is appropriate.
+
+If no personas remain, session creation fails. Reload also fails rather than leaving a running session without a persona.
+
+## Discovery and precedence
+
+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`.
+
+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).
+
+## Persona file contract
+
+A persona is Markdown with YAML frontmatter. `id`, `provider`, and `model` are required. The Markdown body is the persona's base system prompt.
+
+```markdown
+---
+id: release-coder
+label: release coder
+description: Prepares and verifies repository releases.
+provider: anthropic
+model: claude-opus-5
+reasoning: high
+allowedReasoningLevels:
+  - medium
+  - high
+  - xhigh
+skills:
+  - release-check
+tools:
+  - bash
+  - write
+  - edit
+  - view_image
+  - web
+  - history
+subagents:
+  default: false
+  verifier:
+    description: Verify release state independently. Trigger: balanced.
+    systemPrompt: Verify the requested release state and report concrete blockers.
+    tools:
+      - bash
+      - history
+---
+
+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.
+
+### Required fields
+
+| Field | Contract |
+| --- | --- |
+| `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. |
+
+`provider` and `model` are required even when the persona extends a built-in. Tau does not inherit them because selecting a model is the persona's central explicit contract.
+
+### Optional fields
+
+| Field | Contract |
+| --- | --- |
+| `extends` | ID of a shipped built-in persona whose optional behavior is used as a base. |
+| `label` | Display label. A blank or omitted label falls back to the base label or `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`. |
+| `allowedReasoningLevels` | Array of reasoning efforts offered by the TUI selector. |
+| `skills` | `"*"`, a list of discovered skill names, or `[]`. |
+| `tools` | Explicit list of persona-controlled tools. |
+| `subagents` | Map of enabled subagent definitions. |
+
+If a standalone custom persona omits `skills`, Tau selects all discovered skills with `"*"`. If it omits `subagents`, Tau enables the built-in `default` subagent. Tool defaults then include the ordinary host tools plus subagent supervision tools. See [skills](skills.md) and [subagents](subagents.md) for those contracts.
+
+The persona-controlled tool names are:
+
+- `bash`, `write`, `edit`, `view_image`, `web`, `nook`, and `history`;
+- `spawn_agent`, `send_input_to_agent`, `wait_for_agents`, `list_agents`, and `interrupt_agent`.
+
+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. Some host capabilities, such as goal management, are supplied independently of this list. Listing `nook` does not make it usable without effective Nook configuration. [Tools](tools.md) explains eligibility and ownership.
+
+## Extending a built-in
+
+`extends` reuses one shipped built-in persona as a base while still requiring an explicit provider and model:
+
+```markdown
+---
+id: concise-haiku-coder
+extends: opus-5-coder
+provider: anthropic
+model: claude-haiku-4-5
+reasoning: low
+---
+```
+
+Because the body is empty, this persona inherits the built-in's base prompt. It also inherits the base label, description, settings not explicitly overridden, allowed reasoning levels, skills, tools, and subagent map.
+
+Important boundaries are:
+
+- `extends` resolves shipped built-ins, not another custom persona.
+- Lookup of the built-in ID is case-insensitive.
+- It remains available as an inheritance base even when `disableBuiltinPersonas` hides built-ins from the effective catalog.
+- A non-empty Markdown body replaces the inherited base prompt.
+- Explicit `skills` or `tools` replaces the inherited selection.
+- Explicit `subagents` builds a new subagent map rather than merging custom entries into the inherited map. Unless that map contains `default: false`, Tau adds the built-in `default` subagent.
+- `reasoning` and `serviceTier` override their individual inherited settings; omitted settings remain inherited.
+
+Extending a built-in is useful when Tau's maintained behavior is the desired base. A standalone body is more stable when the persona must not change as Tau updates its built-in prompts.
+
+## Selecting a persona
+
+`defaultPersona` in `config.json` selects the startup default. It accepts an exact persona ID or an ID plus reasoning override:
+
+```json
+{
+  "defaultPersona": "release-coder:high"
+}
+```
+
+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.
+
+Override the default for one TUI launch:
+
+```sh
+tau --persona release-coder:xhigh
+```
+
+`-p` is the short form. The same `<id>:<effort>` syntax and reasoning enum apply.
+
+Inside the TUI, switch while idle with:
+
+```text
+/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.
+
+## 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.
+
+`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`.
+
+An empty `allowedReasoningLevels` does not create an empty selector. For an extending persona it falls back to inherited levels; otherwise 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.
+
+## Reloading changes
+
+Run `/reload` while the TUI session is idle after editing personas, `models.json`, skills, or project context. Reload re-discovers the effective catalog and rebuilds the current session 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.
+
+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 use the reloaded persona definition. See [subagents](subagents.md).
+
+## Validation and common mistakes
+
+An invalid persona is skipped and reported as a configuration warning. Other valid personas still load. Frequent causes are:
+
+- malformed YAML, missing frontmatter delimiters, or frontmatter that is not an object;
+- missing `id`, `provider`, or `model`;
+- an `id` that does not exactly match the filename;
+- an unknown provider or an unresolved model;
+- an `extends` target that is not a shipped built-in;
+- an invalid reasoning effort or service tier;
+- `skills` that is neither `"*"` nor a string list, or contains a blank entry;
+- an unknown persona tool;
+- an invalid subagent name, missing custom `systemPrompt`, unsupported subagent tool, or invalid launch model; and
+- attempting to override the built-in `default` subagent instead of using `default: false`.
+
+`/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.