@markusylisiurunen/tau 0.3.82 → 0.3.83

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

@@ -1,8 +1,8 @@
 # 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 Tau's optional platform for publishing small static apps, each at its own path under one hostname. Each site has its built front-end files and its own JSON KV store. Tau deploys and manages sites with its own authenticated 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.
+Nook V0 is deliberately small. It hosts static files on Cloudflare only and does not run applications. Build an app before deploying it. Nook does not run server code for a site, set up custom domains per app, keep a rollback history, or build a source repository for you.
 
 ## V0 at a glance
 
@@ -13,21 +13,21 @@ 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.
+Each site has one active deployment of static files, a visibility of `private` or `public`, and its own JSON KV store that survives redeploys. Templates are stored copies of editable directories. You can copy one into a working directory, change and build it with your usual tools, and then deploy it.
 
-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.
+V0 has no dashboards, subdomain site URLs, deploy rollback, audit logs, ownership roles, realtime APIs, AI proxy APIs, ignore files, or support for providers other than Cloudflare. `.gitignore` and `.nookignore` have no effect, so the deploy directory must contain only the files you mean to publish.
 
 ## Ownership and apply boundaries
 
-Nook crosses three Tau boundaries:
+Nook involves three parties:
 
-- 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 `tau.nook` capability.
+- Cloudflare runs the deployed Worker and holds its route, R2 files, Durable Object state, DNS, and Access application.
+- The Tau CLI, or the session host, holds the Nook credentials and makes the authenticated management requests.
+- The session's execution environment holds the files that the `tau.nook` capability reads or writes.
 
-`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`.
+Paths given to the `tau nook` CLI are on the machine running the command. Paths used by the agent are in the session's execution environment, even when the host is on another machine. The model's code never receives the Access secret, files, environment variables, 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.
+The `nook` config block can be set at global or project level, and the most specific complete object wins. A session reads it when created and on `/reload`. CLI commands read the configuration for the directory they are started in. 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
 
@@ -35,9 +35,9 @@ 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
+- `CLOUDFLARE_API_TOKEN` available, so Wrangler authenticates without prompts
+- npm and network access, so Tau can prepare the Worker package it ships
+- a plan for a Cloudflare Access self-hosted application that protects the control plane
 
 Run:
 
@@ -49,9 +49,9 @@ tau nook setup \
   --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 command deploys the Worker as `tau-nook`, creates or reuses the `tau-nook-assets` R2 bucket, and adds a route for `apps.example.net/*`. It writes the Access team domain and application audience into the Worker's configuration so the Worker can validate Access identities.
 
-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.
+The same values can come from `NOOK_DOMAIN`, `NOOK_ZONE_NAME`, `NOOK_ACCESS_TEAM_DOMAIN`, and `NOOK_ACCESS_AUD`. Flags win over these variables.
 
 Setup does **not** create DNS records, an Access application, Access policies, or a service token. Complete those steps in Cloudflare after deployment.
 
@@ -63,26 +63,26 @@ Create one self-hosted Cloudflare Access application for exactly:
 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.
+Do not protect the whole hostname. Requests for public sites must reach the Worker without signing in, while management stays behind Access.
 
 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/*`.
+2. Disable the **Cookie Path Attribute**, so the Access cookie applies to the whole hostname and not only to `/__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:
+This gives two kinds of 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.
+- `/__nook/*` is the control plane for management and sign-in, protected by Access.
+- `/<site>/*` serves the sites. Public sites need no sign-in. A browser opening a private site is sent through `/__nook/auth` to sign in, and then uses the Access identity that is valid for the whole hostname.
 
-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.
+Tau sends service-token headers only to get past Cloudflare Access. The Worker decides what a request may do by validating the Access JWT, never by trusting those headers.
 
 ## Configure Tau
 
-Create the Access service token, then add one Nook target to the effective Tau config:
+Create the Access service token, then add one Nook target to your Tau config:
 
 ```json
 {
@@ -94,16 +94,16 @@ Create the Access service token, then add one Nook target to the effective Tau c
 }
 ```
 
-`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.
+`domain` is required and must be a DNS hostname without a path, port, query, or fragment. The other fields are optional in the schema, but because the control plane is behind Access you normally need both a client ID and a 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).
+No fixed environment variable overrides these for ordinary Nook operations. `NOOK_ACCESS_CLIENT_SECRET` is used only when the config names it, and by the destroy command described below. Keep the secret on the process that performs the operation: the CLI process for `tau nook`, or the session host for the agent's capability. 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.
+A new CLI command picks up environment changes. For a running session, run `/reload` while idle after changing the config that applies to its working directory.
 
 ## Deploy and inspect sites
 
@@ -114,38 +114,38 @@ 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:
+CLI deployments are private by default. Add `--public` only when anyone should be able to open the site, which also lets anyone write its browser KV:
 
 ```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.
+Every successful deploy replaces all of the site's files and sets its visibility from that command. Leaving out `--public` on the next deploy makes the site private again. The site's 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>/`.
+A site is served at `https://<domain>/<slug>/`, and `/<slug>` redirects to that URL. For a missing path without a file extension, Nook serves the root `index.html`, so single-page apps work. A missing path with a file extension returns not found. Use relative asset URLs, or build the app with the base path `/<slug>/`.
 
-To recover the active deployment files into a local working directory:
+To download a site's current files into a local 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.
+The destination must already exist and be empty. Tau downloads every file and checks sizes and hashes before writing. The site's KV data is not included.
 
-Delete a site only when both its active assets and managed site state are no longer needed:
+Delete a site only when you no longer need its files or its stored state:
 
 ```sh
 tau nook delete roadmap
 ```
 
-Site deletion is destructive and Nook V0 has no rollback history.
+Deleting a site cannot be undone, and V0 keeps no earlier versions.
 
 ## 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:
+A deploy directory must contain `index.html` at its root. Tau checks every path in the directory and rejects the deploy if any breaks these rules:
 
 - hidden files or directories are forbidden, including `.env`, `.git`, and `.DS_Store`
 - symlinks are forbidden
@@ -156,13 +156,13 @@ A deploy directory must contain root `index.html`. Tau walks the complete direct
 - 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.
+Tau sets common content types from file extensions and uses `application/octet-stream` for the rest. Each upload is checked against its declared size and SHA-256 digest. Browsers must revalidate cached files, so a new deployment shows up even when file names do not contain content hashes.
 
-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.
+Nook ignores ignore files. Build into a clean output directory instead of deploying a repository root. Never work around the hidden-file rule by copying credentials into files without a leading dot.
 
 ## 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.
+Templates are reusable directory copies stored in your Nook deployment. They are not sites. Tau does not fill in placeholders or run installs or builds for them.
 
 ```sh
 tau nook template save vite-static ./starter
@@ -171,11 +171,11 @@ 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`.
+`save` creates or replaces the named template. `copy` needs an existing empty destination and checks all downloaded files before writing. Templates follow the same rules and limits as deployments for paths, hidden files, symlinks, file count, and size, but do not need a 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.
+Template names follow the same format as site slugs. The names reserved for sites are allowed for templates.
 
-Delete a template only when its stored editable snapshot is no longer needed:
+Delete a template only when you no longer need it:
 
 ```sh
 tau nook template delete vite-static
@@ -185,7 +185,7 @@ 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:
+Each site has its own KV store of JSON values. The CLI can read and change it directly:
 
 ```sh
 tau nook kv put roadmap settings '{"theme":"dark"}'
@@ -196,69 +196,75 @@ 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.
+Apps in the browser use their site's KV from the same origin. On a public site, anyone can open the app and use its KV, so the KV is **writable by anyone**. Never store secrets, access tokens, private user data, or data whose integrity matters in a public site's KV. A private site requires a valid Cloudflare Access identity both to open the site and to use its 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.
+The CLI and the agent manage KV through the control plane behind Access, not through the browser path. The browser API and its examples are documented in the Nook skill that each deployment provides, so they match that deployment's version.
 
-## Use the host tool
+## Use the agent capability
 
-The `tau.nook` capability in the assistant-facing `code` tool is available only when both conditions hold:
+The `tau.nook` capability in the agent's `code` tool is available only when:
 
-- the current persona selects `nook`
-- effective session configuration contains a valid `nook` block
+- the current persona selects `nook`, and
+- the session's 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 host makes the authenticated Nook requests, outside the model's code. Files for deploys, copies, templates, and KV come from the session's execution environment. The agent uses the capability only when asked to work with Nook, publish or host a site, or manage Nook KV.
 
-The tool has two separate documentation stages:
+The agent reads documentation in two separate steps:
 
-1. The management stage requires the built-in `docs` to be visible before API use. When they are absent, the first call only prints them; after the agent reads that result, later calls use the management API normally. Already-visible documentation is reused rather than reloaded.
-2. The app-authoring stage requires a separate documentation-only call that retrieves and prints `nook.skill()`. The agent reads that deployment-provided guide before writing files in later calls.
+1. Before using the management API, it reads the built-in `docs`. If it has not seen them, its first call only prints them, and later calls use the API. Documentation already in the conversation is reused.
+2. Before writing an app, it makes a separate call that only prints `nook.skill()`, the authoring guide that the deployment provides, and reads it before writing files.
 
-Skill retrieval and management operations remain separate calls, and this page does not specify either API. 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).
+This page does not describe either API. The deployed skill covers the browser API and app authoring, so it always matches that deployment's version. General tool eligibility and code-mode behavior are covered in [tools](tools.md).
 
 ## Verify a deployment
 
-Verify from both management and browser perspectives:
+Check both management and the browser:
 
-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`.
+1. Run `tau nook list` from a directory whose config contains the intended target.
+2. Deploy a small private site with a root `index.html` and nothing sensitive in it.
 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.
+5. Write a throwaway KV key through the app or the 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.
+A successful Worker deployment does not prove that DNS, the Access cookie scope, user policies, the service token policy, or Tau's credentials are right.
 
 ## 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.
+**`nook is not configured`.** Add the `nook` block at a config level that applies 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 CLI command gets an Access login page or an authorization error.** Confirm that Access protects only `/__nook/*`, the service token has a Service Auth policy, both token fields are available to the process running the command, the configured domain matches the deployed hostname, and the Worker was set up with the right Access team domain and audience.
 
-**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 private site keeps redirecting, or browser KV says authentication is required.** Disable the Access application's Cookie Path Attribute, and check the user Allow policy and the audience. The cookie must be valid for the whole hostname so the Worker can accept `/<site>/*` requests 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.
+**A public site still asks for Access.** The Access application probably covers the whole hostname instead of only `/__nook/*`, or the latest deploy left out `--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.
+**Files load at `/` during local development but fail after deploy.** Build for the `/<site>/` base path or use relative URLs. Nook does not rewrite absolute asset URLs.
 
-**Deploy rejects hidden files or symlinks.** Use a clean build output. Ignore files do not change Nook's manifest walk.
+**Deploy rejects hidden files or symlinks.** Use a clean build output. Ignore files have no effect on what Nook deploys.
 
-**Copy refuses the destination.** Create an empty directory first. Tau will not merge downloaded files into existing contents.
+**Copy refuses the destination.** Create an empty directory first. Tau never merges downloaded files into existing content.
 
-**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.
+**The agent does not have the capability.** Check both the persona's tools and the `nook` config in the session's execution environment, then `/reload` while idle and start a new turn. The config block alone is not enough if the persona does not select `nook`. Subagents get Nook only when the main persona has it.
+
+**The CLI works but the agent does not, or the other way around.** The CLI uses the configuration and credentials of the machine running it, and the agent's capability uses the session's configuration and the host's credentials. Start with `tau nook --help` and `tau nook list`, which shows URLs and visibility without printing secrets.
+
+**A site has the wrong visibility.** Check it with `tau nook list`, then redeploy reviewed content with or without `--public`. If something sensitive was public, rotate exposed credentials right away and remove sensitive KV entries with `tau nook kv delete`, because KV survives redeploys. Use `tau nook delete` only when you mean to take the site offline.
+
+**Setup or destroy fails before reaching Cloudflare.** Both need Wrangler on `PATH` and `CLOUDFLARE_API_TOKEN`, so Wrangler can sign in without prompts. Compare this page and `tau nook --help` with the deployed Worker's version before upgrading or changing infrastructure.
 
 ## 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.
+Destroy removes all Nook data and infrastructure, not just one site. It first calls the authenticated cleanup endpoint to delete every site's Durable Object data and Nook's R2 objects, then tries to delete the `tau-nook` Worker and the `tau-nook-assets` bucket.
 
-Use environment variables for cleanup credentials so secrets do not enter shell history:
+Pass the cleanup credentials as environment variables, so the secrets stay out of 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.
+The command reads `NOOK_ACCESS_CLIENT_ID` and `NOOK_ACCESS_CLIENT_SECRET`. Flags with the same names also work, but expose the values more easily. It accepts `NOOK_DOMAIN` instead of `--domain`, and needs `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.
+This deletes data permanently. Before running it, make sure every site, template, and KV store is either disposable or saved elsewhere. If the data cleanup fails, Tau stops before deleting any infrastructure. Worker and bucket deletion failures are reported separately and can leave a partial deployment, so read 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.
+Destroy does not remove DNS records, the Cloudflare Access application, its policies, or service tokens. Remove those yourself once the Nook hostname no longer serves anything you need, then remove the Tau config and credentials you no longer use.

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

@@ -1,12 +1,12 @@
 # OpenRouter
 
-`tau tool openrouter` provides standalone, single-request utilities for typed decisions and text or media understanding. They work from a shell inside or outside Tau, without a session, persona, conversation, tools, or session accounting. Only explicitly supplied content is sent to OpenRouter and its selected provider. Judgments are advisory model output, not a security or permission boundary.
+`tau tool openrouter` makes single requests for typed decisions and for understanding text or media. It works from any shell, inside or outside Tau, without a session, persona, conversation, tools, or session cost tracking. Only the content you pass is sent to OpenRouter and its chosen provider. Its judgments are model output; never use them as a security or permission check.
 
 ## Credentials and requirements
 
 Install Tau and configure `OPENROUTER_API_KEY`, or put `apiKeys.openrouter` in the global `~/.config/tau/config.json` on the machine running the command. A nonblank environment key takes precedence. Project configuration cannot supply API keys. There is no key flag.
 
-Tau's local Bash removes inherited credential-shaped environment variables. When invoking through Bash, configure the key on that machine through global configuration or its own supported environment setup. See [credentials](credentials.md) and [tools](tools.md).
+The agent's Bash tool removes inherited variables that look like credentials. When the agent runs the command, put the key in global configuration on that machine, or set it some other way that machine supports. See [credentials](credentials.md) and [tools](tools.md).
 
 Audio and video require `ffprobe` from FFmpeg on `PATH`: `brew install ffmpeg` on macOS or `apt install ffmpeg` on Debian/Ubuntu. Text and images do not require FFmpeg. Media is validated locally, not transcoded.
 
@@ -22,30 +22,31 @@ Help and model listing require neither credentials nor network access and never
 
 ## Fixed model choices
 
-An actual request requires an exact `--model` ID from this table. There is no default, arbitrary-ID escape hatch, live discovery, refresh, or automatic model substitution. A versioned ID is not necessarily an immutable provider snapshot; output records the returned model separately.
+Every request needs an exact `--model` ID from this table. There is no default, no way to use other IDs, no model discovery or refresh, and no automatic substitution. A versioned ID is not necessarily an immutable provider snapshot; output records the returned model separately.
 
 | Operation | Model | Inputs and suggested role | Reasoning efforts |
 | --- | --- | --- | --- |
-| `decisions` | `typesafe/jev-1.13` | Structured state and questions; classification, scoring, verification with probabilities | Not supported |
+| `decisions` | `openai/gpt-6-luna-decisions` | Questions about text, structured state, or images; recommended first choice for decisions | Not supported |
+| `decisions` | `typesafe/jev-1.13` | Questions about text or structured state; use for high-volume decisions when cost is the priority | Not supported |
 | `chat` | `google/gemini-3.8-flash` | Text, images, audio, video; first choice for audio/video and image-heavy analysis | `low`, `medium`, `high` |
 | `chat` | `openai/gpt-6-luna` | Text and images; cheap everyday extraction, summarization, and routine questions | `none`, `low`, `medium`, `high`, `xhigh`, `max` |
 | `chat` | `openai/gpt-6.1-sol` | Text and images; coding, debugging, technical reasoning | `low`, `medium`, `high`, `xhigh`, `max` |
 | `chat` | `anthropic/claude-opus-5.5` | Text and images; premium generalist for writing, synthesis, difficult reasoning, and second opinions | `low`, `medium`, `high`, `xhigh`, `max` |
 
-Roles are selection guidance, not benchmark guarantees or restrictions on tasks. Unsupported settings and modalities fail locally rather than switching models, transcribing audio, or extracting video frames.
+Roles are guidance for choosing, not guarantees or limits on what a model may be used for. Unsupported settings and media types fail locally; the command never switches models, transcribes audio, or extracts video frames instead.
 
 ## Input and examples
 
 ### Decisions
 
 ```sh
-tau tool openrouter decisions --model typesafe/jev-1.13 --input ./decision.json
+tau tool openrouter decisions --model openai/gpt-6-luna-decisions --input ./decision.json
 ```
 
 `--input` is required. A file path reads a UTF-8 JSON document. Exactly `--input -` reads one complete document from stdin until EOF:
 
 ```sh
-tau tool openrouter decisions --model typesafe/jev-1.13 --input - <<'JSON'
+tau tool openrouter decisions --model openai/gpt-6-luna-decisions --input - <<'JSON'
 {
   "state": { "ticket": "The checkout page crashes when I click Pay." },
   "questions": {
@@ -81,14 +82,28 @@ The input contains exactly `state` and `questions`. The model belongs only in `-
 
 Instructions and criterion guidance accept strings, JSON objects, or arrays; choice criterion values may also be `null`. Unknown question fields and the reserved question/category name `__proto__` are rejected. Arbitrary keys within state and guidance are preserved. Several independent questions can share one state; dependent questions require separate calls.
 
-The command posts once to OpenRouter's alpha Decisions endpoint. It validates answer names, types, categories, rubric ranges, and probability bounds. Successful output is one JSON object:
+Luna Decisions supports at most 200 questions, 255 categories per choice question, and 2–10 rubric levels per score question. Tau checks these limits before sending the request. Jev also accepts a single-level score rubric. Both models use the same JSON input format.
+
+Luna also accepts up to 16 ordered local PNG/JPEG/WebP images using repeatable `--image <path>` flags:
+
+```sh
+tau tool openrouter decisions \
+  --model openai/gpt-6-luna-decisions \
+  --input ./visual-checks.json --image ./checkout.png
+```
+
+Describe what to check in `questions` and supply images with `--image`. Images follow `state` in flag order and retain their original bytes. Objects and arrays in `state` are sent as JSON text, so image URLs inside `state` are treated as text.
+
+Images use the [same validation and limits as chat images](#outputs-and-recovery). Only local files are accepted; external URLs and file IDs are unsupported. Jev accepts no images. Neither decision model accepts audio or video.
+
+The command posts once to OpenRouter's alpha Decisions endpoint. It validates answer names, types, categories, rubric ranges, and probability bounds. Refusals and malformed answers fail the command. Successful output is one JSON object:
 
 ```json
 {
-  "requested_model": "typesafe/jev-1.13",
-  "model": "typesafe/jev-1.13-20260917",
+  "requested_model": "openai/gpt-6-luna-decisions",
+  "model": "openai/gpt-6-luna-decisions-20261006",
   "answers": { "is_bug": { "type": "noul", "noul": 0.96 } },
-  "usage": { "input_tokens": 100, "output_tokens": 10, "cost": 0.00001 }
+  "usage": { "input_tokens": 100, "output_tokens": 0, "cost": 0.00001 }
 }
 ```
 
@@ -142,7 +157,7 @@ These are successful exchanges with distinguishable outcomes; scripts must inspe
 
 ## Outputs and recovery
 
-These are conservative utility safety limits, not promises of every provider's maximum capacity. All byte limits use decimal bytes.
+These are cautious safety limits set by Tau, not the providers' maximum capacities. Byte limits use decimal units.
 
 | Resource | Limit |
 | --- | --- |
@@ -162,4 +177,4 @@ Oversized or unsupported inputs fail before sending. Audio/video validation uses
 
 Diagnostics go to stderr and failures exit nonzero. Authentication, insufficient credits, permission failures, rate limits, and provider/service failures report distinct status diagnostics without dumping provider bodies. There are no automatic retries, including after timeouts or interrupted connections: the provider may already have charged for an unknown outcome. A response exceeding the safety bound can fail after a billable request.
 
-No paid inference compatibility guarantee follows from local validation. OpenRouter's alpha Decisions contract and provider availability can change independently of Tau. Review the actual output and current service errors rather than treating model judgments as verified facts.
+Passing local validation does not guarantee the provider accepts the request. OpenRouter's alpha Decisions API and provider availability can change independently of Tau. Read the actual output and errors, and never treat model judgments as verified facts.

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

@@ -1,6 +1,6 @@
 # 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.
+Tau splits a session into three parts: the terminal or other interface you use, the host that runs the session, and the machine the agent works on. They stay separate even when all three run in one process. Know which part owns a path or setting before you change it. In an attached session, “local” can mean any of three machines.
 
 ## The four operating roles
 
@@ -8,31 +8,29 @@ Tau separates terminal interaction, session orchestration, and agent-visible exe
 
 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.
+Client tools run on the client machine, which may differ from the machine where the agent's Bash tool runs. Client configuration is found 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` is the standalone host entry point.
 
-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.
+Session snapshots, authentication storage, usage logs, and the local history database live in the host user's home. Manage them with Tau commands and session operations. Do not edit their files directly.
 
-MCP connections are host-owned. Configure servers on the host; stdio servers run there, with host credentials and host resource access, not in the session execution environment.
+MCP connections belong to the host. Configure servers on the host. Stdio servers run there, with the host's credentials and access to the host's resources. They do not run in the session's execution environment.
 
-The intrinsic `tau_docs` tool is also host-owned. It reads documentation packaged with the installed host version.
+The built-in `tau_docs` tool also belongs to the host. It reads the documentation installed with the host's Tau 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, 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.
+Tau reads files and runs commands through the execution environment, even when it is on the same machine as the host. Each session has exactly one execution environment. Paths shown to the agent and paths passed to its tools are always paths on that environment.
 
 ### 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.
+The **Telegram runner** owns Telegram polling, chat routing, attachments, outbound messages, project selection, and Telegram-specific persisted runner state. It is a client of in-process Tau sessions and 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.
+For repository and composite projects it prepares managed workspaces. A persistent-directory project reuses the configured directory. Each workspace becomes the local execution environment of its session. The file passed to `tau telegram --config-file` is runner configuration. It is not one of Tau's `config.json` levels.
 
 ## Where each mode runs
 
@@ -45,11 +43,11 @@ For repository and composite projects it prepares managed workspaces. A configur
 | SDK over WebSocket | SDK caller | Remote server | Environment selected or restored by that host |
 | `tau telegram` | Telegram runner | In-process on the runner machine | Prepared project workspace or persistent directory |
 
-A 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.
+A Fly Sprite puts the execution environment on another machine while the host stays on its own. The host keeps the provider credentials and runs the session. The Sprite owns its paths and commands.
 
 ## Who owns common paths and behavior
 
-| Resource or behavior | Canonical owner | Consequence |
+| Resource or behavior | 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`, personas, prompts, skills, and `AGENTS.md` used by a session | Execution environment | Edit them on the target and relative to the session `cwd`. |
@@ -60,9 +58,9 @@ A Fly Sprite can place the execution environment on another target while the hos
 | 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 selects from Tau’s built-in themes. Themes are not session state. |
 | `/diff` process | TUI client | Tau’s built-in browser tool runs 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. |
+| Configured command client tools | Owning client | Commands and their environment are on the client. File access they make on behalf of the session goes to the execution environment. |
 | `/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 | Fly Sprite API definitions must be available to the host before it accepts sessions using them. |
+| Host execution-environment targets | Host startup | Fly Sprite connection settings must be in the host's configuration before it accepts sessions that use 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
@@ -70,11 +68,11 @@ A Fly Sprite can place the execution environment on another target while the hos
 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.
+2. If it changes the TUI's theme, speech, or command client tools, edit the TUI client's configuration and restart that client.
+3. If it changes credentials, session storage, remote history, or hosted execution environment connections, set 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.
+For a local `tau` session these locations are often the same home and repository. Following the ownership rule anyway means the configuration still works when the session becomes remote.
 
 ## A remote configuration example
 
@@ -84,22 +82,22 @@ Suppose a laptop runs:
 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 host and its local execution environment resolve `/srv/ledger`. Project personas and `.tau/config.json` are read from `/srv/ledger` and its parent directories on `devbox.example`. The laptop's current directory has no effect on the session.
 
 The laptop still loads its own theme and command client tools before attaching. `/diff` launches Tau’s built-in browser tool 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.
+The host on `devbox.example` makes the model calls, so it needs the provider credential. Export the provider's environment variable for `tau serve` there, or put the key in that host's global configuration. Setting it only in the laptop shell does not reach 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.
+Tau includes global configuration only when the relevant `cwd` is the home directory or inside it. For session configuration, both the `cwd` and the home are on the execution environment. For client startup configuration, both are on 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.
+This matters when a remote or hosted environment uses a project outside its home. Tau then reads project levels up to the filesystem root but does not add `~/.config/tau`, from that machine or any other.
 
 ## 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.
+`tau_docs` reads the documentation installed with the host. It can explain valid fields, paths, precedence, and supported behavior for that host's Tau 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.
+It cannot see effective configuration, environment variables, loaded client tools, the active TUI theme, the versions of attached clients, or files on a client machine. An attached client can run a different Tau version from the host. For client questions, use client commands and look on the client machine. For questions about the running session, use the warnings the session reports or inspect the host.
 
 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.