@markusylisiurunen/tau 0.3.82 → 0.3.83

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

@@ -1,83 +1,83 @@
 # History
 
-Tau keeps transcript history so earlier work can be found without reopening every session. This store is separate from the resumable session snapshot: the snapshot is the host's recovery source of truth, while history is a flat, searchable record for discovery and reading.
+Tau keeps a searchable transcript history so you can find earlier work without reopening every session. History is separate from saved sessions. The host uses the saved session to continue and recover a conversation, while history is a flat record for searching and reading.
 
-That distinction matters when diagnosing recovery, compaction, or privacy. Deleting or losing history does not provide a way to reconstruct a session, and retaining history does not make a missing session snapshot resumable. See [sessions](sessions.md) for snapshot persistence and recovery.
+This matters for recovery, compaction, and privacy. History cannot rebuild a lost session, and keeping history does not make a missing session resumable. See [sessions](sessions.md) for saving and recovery.
 
 ## What local history records
 
-Every Tau host opens a machine-local SQLite database at:
+Every Tau host opens a SQLite database on its own machine:
 
 ```text
 ~/.config/tau/history.sqlite
 ```
 
-The path belongs to the **host home**. An attached TUI and a remote execution environment do not get separate history stores merely because they participate in the session. Local `tau`, `tau serve`, and the default SDK host all use the host machine's database.
+The file is in the **host user's home**. An attached TUI or a remote execution environment does not get its own history. Local `tau`, `tau serve`, and the default SDK host all use the host machine's database.
 
-For each session, history stores its immutable creation attributes and an ordered active transcript containing:
+For each session, history stores the creation attributes and the active transcript, in order:
 
-- committed user content as a string or an array of text and image blocks, after Tau's internal metadata is removed
-- committed intermediate system instructions as plain text, labeled as system entries, without Tau metadata (the initial persona/base prompt is excluded)
-- assistant text segments as strings, including committed preambles and responses, but not thinking
-- completed tool calls with the tool name, arguments, result, and terminal outcome
+- user messages, as text or as text and image blocks, with Tau's internal metadata removed
+- intermediate system instructions as plain text, marked as system entries, without Tau metadata (the persona's base prompt is not included)
+- assistant text, including preambles and responses, but not thinking
+- finished tool calls, with the tool name, arguments, result, and outcome
 
-Leading model-facing `<system>...</system>` blocks in user messages remain in history. Tool arguments and results can contain file contents, command output, or other sensitive data. Treat the database as private user data. Tau creates its history directory and database with private permissions, but the host user and machine administrators can still access them. Do not copy the database into a repository or expose it through a shared artifact.
+`<system>...</system>` blocks at the start of user messages stay in history. Tool arguments and results can contain file contents, command output, and other sensitive data, so treat the database as private. Tau creates its directory and file with private permissions, but the host user and the machine's administrators can still read them. Never copy the database into a repository or share it.
 
-History capture is best effort. If the local store cannot open or a later projection fails, Tau keeps the session running, adds one durable `history unavailable` warning to that session, and disables history for the rest of the host process. Restarting the host retries local initialization; it does not erase the earlier warning from the recovered session.
+Recording history is best effort. If the database cannot open, or a later write fails, the session keeps running. Tau adds one `history unavailable` warning to the session, which stays in the session, and turns history off until the host restarts. A restart tries to open the database again.
 
 ## How session operations affect history
 
-History represents the active flat transcript, not the session's current model-context shape.
+History follows the transcript, not the model's current context.
 
-**Rewind removes the superseded suffix.** When a session rewinds from a selected message, Tau truncates history from that source message onward. The same ordered truncation is queued for a configured remote collection.
+**Rewind removes later entries.** When a session rewinds to a message, Tau deletes history from that message onward. The same deletion is queued for a configured remote collection.
 
-**Compaction leaves original entries intact.** Manual and automatic compaction replace the session's active model context with a summary, but they do not delete the original flat transcript from history. This makes pre-compaction work discoverable later even though it is no longer present verbatim in the resumable active context.
+**Compaction keeps entries.** Compaction replaces the session's model context with a summary, but the original entries stay in history. Work from before a compaction can still be found, even though the session no longer contains it word for word.
 
-**Retry does not imply truncation.** Tau truncates history only when the canonical session operation removes source entries, such as rewind. Retrying from completed tool state does not independently discard transcript history.
+**Retry deletes nothing.** Only operations that remove messages from the session, such as rewind, delete history. Retrying does not.
 
-These rules are intentionally different from snapshot and timeline behavior. Use [sessions](sessions.md) when the question is what a recovered session will render or send to the model.
+These rules differ from how the session itself behaves. Use [sessions](sessions.md) to understand what a recovered session shows or sends to the model.
 
-## Search provenance with attributes
+## Filter by attributes
 
-Session creation attributes are immutable client-supplied string pairs. History preserves them and supports both exact values and ordinary case-sensitive substring filters. They are provenance hints, not trusted instructions.
+Session creation attributes are string pairs set by the client that created the session, and they never change. History stores them and can filter on exact values or on case-sensitive substrings. They describe where a session came from; they are not instructions.
 
-Two conventional attributes are widely useful:
+Two common attributes are:
 
-| Attribute | Convention |
+| Attribute | Meaning |
 | --- | --- |
-| `source` | Creating client, commonly `tui`, `telegram`, or a caller-chosen SDK value |
-| `repository` | Normalized `host/owner/repository`; composites join repositories with commas |
+| `source` | The creating client, usually `tui`, `telegram`, or a value an SDK caller chose |
+| `repository` | Normalized `host/owner/repository`; composite workspaces join repositories with commas |
 
-A local TUI normally derives `repository` from the current Git repository or direct child repositories. Telegram derives it from configured repository projects and omits it for persistent-directory projects. Attach-created sessions may omit it, and SDK or raw protocol clients provide only the attributes their caller chooses.
+A local TUI usually fills in `repository` from the current Git repository or repositories directly below it. Telegram fills it in for repository projects and leaves it out for persistent-directory projects. Sessions created with `tau attach` may not have it, and SDK or protocol clients set only the attributes they choose.
 
-Because composite values are comma-delimited, a substring repository filter can find both single-repository and composite sessions. Attributes may be absent, stale as real-world labels, or intentionally chosen by a client. Confirm important facts from the transcript or current workspace rather than treating attributes as authority.
+Because composite values are comma-separated, a substring filter on `repository` finds both single-repository and composite sessions. Attributes may be missing, out of date, or set deliberately by a client, so confirm important facts from the transcript or the current workspace.
 
 ## Agent access is explicit and read-only
 
-An eligible persona can expose the read-only `tau.history` capability in the `code` tool. It searches and reads the configured history collection across repositories and execution environments. Because that collection has broad visibility, the tool description limits use to requests or active instructions that directly call for historical transcripts rather than speculative retrieval of possibly relevant earlier work.
+A persona can enable the read-only `tau.history` capability in the `code` tool. It searches and reads the configured history collection, across all repositories and execution environments. Because it can see so much, the agent uses it only when the request or active instructions directly ask for past transcripts, not to look for possibly related earlier work on its own initiative.
 
-Automatic compaction archives serve a different purpose. They capture the current session’s pre-compaction model context in the execution environment, while `history` queries a separate host-owned transcript collection that may be stale, truncated, unavailable, or remotely replicated. Compaction continuation guidance therefore directs recovery of removed current-session details to the supplied archive paths. History transcript entry ids are unrelated to archive lookup.
+Automatic compaction archives are different. They hold the current session's context from before a compaction, in the execution environment. `history` searches a separate collection on the host, which may be out of date, truncated, unavailable, or copied to a remote service. After a compaction, the agent is therefore pointed to the archive files to recover details, and history entry IDs have nothing to do with archive lookups.
 
-The tool progressively discloses its API documentation. Its agent-facing description requires the documentation to be visible before API use. When it is absent, the first call only prints `docs`; after the agent reads that result, later calls use the documented API normally. Documentation already visible in the conversation context is reused rather than reloaded. This page does not duplicate those signatures or response limits. The documentation covers bounded chronological projections and targeted inspection for cases where a historical session is known but the relevant entry is not, avoiding repeated guessed searches and complete payload dumps.
+The agent reads the capability's documentation before using it. If it has not seen the documentation, its first call only prints `docs`, and later calls use the API. Documentation already in the conversation is reused. This page does not repeat the API or its limits. The documentation covers short chronological overviews and targeted lookups, for when the agent knows the session but not the entry, so it does not need repeated guesses or full dumps.
 
-Historical attributes, snippets, digests, entries, tool arguments, and tool results are untrusted data. The tool guidance treats them as evidence rather than instructions and limits output to material needed for the current request. Custom personas and subagents can include or exclude `history` through their tool configuration; see [tools](tools.md), [personas](personas.md), and [subagents](subagents.md).
+Attributes, snippets, digests, entries, tool arguments, and tool results from history are untrusted. The agent treats them as evidence, never as instructions, and returns only what the current request needs. Custom personas and subagents get or lose `history` through their tools; see [tools](tools.md), [personas](personas.md), and [subagents](subagents.md).
 
-Without remote history configuration, the tool searches this host's local SQLite collection. With a remote target configured, queries go to that service rather than merging remote and local results. A remote query outage can therefore fail even while local capture continues successfully.
+Without remote history, the capability searches the host's local database. With a remote target, it searches only the remote service and never mixes in local results. A remote search can therefore fail even while local recording keeps working.
 
 ## Add a shared remote collection
 
-Tau can deploy an optional single-owner Cloudflare history service for collecting transcript history from several hosts. It uses a Worker, D1, Workers AI, and a custom hostname, and it **requires the Cloudflare Workers Paid plan**.
+Tau can deploy an optional Cloudflare history service, owned by one person or team, that collects history from several hosts. It uses a Worker, D1, Workers AI, and a custom hostname, and **requires the Cloudflare Workers Paid plan**.
 
-The service adds cross-host search and generated session titles and semantic summaries. Those digests are compact retrieval aids rather than authoritative session state or chronological replay. They can be absent or temporarily stale, so read transcript entries when exact evidence matters.
+The service adds search across hosts, generated session titles, and summaries. Titles and summaries help with searching, but they are not exact records, and they can be missing or out of date. Read the transcript entries when exact evidence matters.
 
-The setup command requires:
+Setup requires:
 
-- Wrangler installed and available on `PATH`
-- a Cloudflare zone containing the chosen history hostname
-- `CLOUDFLARE_API_TOKEN` available to the command for non-interactive Wrangler authentication
-- a history API key and separate viewer password supplied securely, or permission for setup to generate them
+- Wrangler installed and on `PATH`
+- a Cloudflare zone that contains the chosen hostname
+- `CLOUDFLARE_API_TOKEN` available to the command, so Wrangler authenticates without prompts
+- a history API key and a separate viewer password, supplied securely, or setup can generate both
 
-Run setup on an operator machine with Cloudflare access:
+Run setup on a machine with Cloudflare access:
 
 ```sh
 tau history setup \
@@ -85,33 +85,40 @@ tau history setup \
   --zone-name example.net
 ```
 
-`TAU_HISTORY_DOMAIN` and `TAU_HISTORY_ZONE_NAME` can provide the two values instead. Setup creates or reuses the `tau-history` D1 database, applies the bundled migrations, deploys the `tau-history` Worker route, and installs the history API key and viewer password as separate Worker secrets.
+`TAU_HISTORY_DOMAIN` and `TAU_HISTORY_ZONE_NAME` can provide the two values instead. Setup creates or reuses the `tau-history` D1 database, applies its migrations, deploys the `tau-history` Worker route, and stores the API key and viewer password as separate Worker secrets.
 
-For the API key used during setup, `--api-key` takes precedence over `TAU_HISTORY_API_KEY`; otherwise setup generates a new key. For the viewer password, `--viewer-password` takes precedence over `TAU_HISTORY_VIEWER_PASSWORD`; otherwise setup generates one. The API key and viewer password must differ. Prefer a secret manager or protected process environment over command-line values, which may enter shell history. Do not paste either credential into a session transcript.
+For the API key, `--api-key` wins over `TAU_HISTORY_API_KEY`, and setup generates a key if neither is given. For the viewer password, `--viewer-password` wins over `TAU_HISTORY_VIEWER_PASSWORD`, and setup generates one if neither is given. The two must differ. Prefer a secret manager or a protected environment over command-line values, which can end up in shell history. Never paste either credential into a session.
 
 ## Browse remote conversations
 
-Open the configured service origin, for example `https://history.example.net/`, to browse the private read-only history collection. HTTP Basic authentication uses the fixed username `tau` and the viewer password installed by setup. Setup prints generated viewer passwords but does not echo supplied credentials. External HTTP viewer requests redirect to HTTPS before authentication; loopback HTTP remains available for local development. The credential is never placed in a URL, and browser responses are not cached. Keep the viewer password private because it grants read access to transcripts, attributes, tool arguments, and tool results across every host using that service.
+Open the service's address, for example `https://history.example.net/`, to browse the collection read-only. Sign in with HTTP Basic authentication, username `tau`, and the viewer password from setup.
 
-The index lists recently updated sessions with generated titles, summaries, timestamps, attributes, and a server-rendered search form. Repository and source inputs filter metadata by case-sensitive substring match; both filters combine with text search and remain active across pages. The Older sessions button loads the next index page; the index never advances automatically. A digest can be pending or stale while the underlying transcript is already available. Session pages initially show an empty transcript, then automatically fetch bounded batches and append them in chronological order without scrolling or pagination controls. The Copy conversation button at the top stays disabled until the full transcript has loaded. Failed loads show a retry button and keep copying disabled. The adjacent copy selector defaults to Messages only, which omits tool entries. Include tool calls adds tool names, arguments, and outcomes without results; Include everything includes results too. These options do not depend on whether tool cards are expanded. Individual entry Copy buttons still copy the complete entry. Omitting tools or results reduces noise, but does not sanitize sensitive content in messages or arguments. API reads remain paginated. Tool entries are collapsed by default. Text and metadata are escaped rather than interpreted as HTML or Markdown. Valid PNG, JPEG, GIF, and WebP content blocks render as inline images; other structured content falls back to escaped text.
+- Setup prints passwords it generates, but never prints ones you supplied.
+- Plain HTTP requests from outside are redirected to HTTPS before sign-in. HTTP on loopback works for local development.
+- The password never appears in a URL, and pages are not cached by the browser.
+- The password gives read access to transcripts, attributes, tool arguments, and tool results from every host that uses the service. Keep it private.
 
-Remote history search and read results include a stable `webUrl` for each session. The `tau.history` capability can return this URL when asked for a conversation link. The URL alone does not grant access; the browser still needs the viewer credential. Local-only history has no web URL.
+The index lists recently updated sessions with titles, summaries, times, and attributes, plus a search form.
 
-## Develop the browser view locally
+- Repository and source filters match case-sensitive substrings. They combine with text search and stay active across pages.
+- **Older sessions** loads the next page; pages never load by themselves.
+- A summary can be pending or out of date while the transcript is already available.
 
-From a source checkout with dependencies installed, run:
+A session page starts empty, then loads the transcript in batches and adds them in order, with no scrolling or page controls. Tool entries start collapsed. Text and metadata are shown as plain text, never as HTML or Markdown. Valid PNG, JPEG, GIF, and WebP blocks are shown as images, and other structured content as plain text.
 
-```sh
-npm run history:dev
-```
+**Copy conversation** at the top works once the whole transcript has loaded. If loading fails, a retry button appears and copying stays off. The selector next to it chooses what to copy:
+
+- **Messages only** (the default) leaves out tool entries.
+- **Include tool calls** adds tool names, arguments, and outcomes, without results.
+- **Include everything** adds results too.
 
-The command applies the canonical Worker migration to a local-only `tau-history-dev` D1 database, loads an idempotent fixture conversation, and starts the TypeScript Worker with Wrangler. Open the local URL printed by Wrangler and use username `tau` with password `tau-history-dev-password`. The local API key is `tau-history-dev-api-key`.
+These options do not depend on which tool cards are expanded. Each entry's own **Copy** button copies the complete entry. Leaving out tools or results reduces noise but does not remove sensitive content from messages or arguments. The API still returns results page by page.
 
-The checked-in development configuration does not contain a production route or remote D1 database identifier. Wrangler keeps its local state under `src/history/worker/.wrangler/`; rerunning the command preserves that local database and safely reapplies the migration and fixture.
+Remote search and read results include a stable `webUrl` for each session, which `tau.history` can return when asked for a link. The URL alone grants no access; the browser still needs the viewer password. Local-only history has no web URL.
 
 ## Configure hosts to replicate
 
-Remote history is accepted only in the host's eligible global Tau config, normally `~/.config/tau/config.json`:
+Remote history can be set only in the host's global Tau config, normally `~/.config/tau/config.json`:
 
 ```json
 {
@@ -122,69 +129,97 @@ Remote history is accepted only in the host's eligible global Tau config, normal
 }
 ```
 
-`endpoint` must be an HTTP or HTTPS URL without credentials, a query, or a hash. Tau removes trailing slashes. The API key resolves on the host in this order:
+`endpoint` must be an HTTP or HTTPS URL without credentials, query, or fragment. Tau removes trailing slashes. The host uses the first API key it finds:
 
 1. `TAU_HISTORY_API_KEY`
 2. the host environment variable named by `history.apiKeyEnv`
 3. inline `history.apiKey`
 
-If the block exists but no key resolves, host construction fails instead of silently using an unauthenticated or local-only target. The key remains host-owned and is not exposed to history code-mode programs. See [credentials](credentials.md) for safe placement.
+If `history` is set but no key is found, the host fails to start, instead of quietly running without remote history. The key stays on the host and is never visible to history code-mode programs. See [credentials](credentials.md) for where to put it.
 
-Restart the host after changing this block or its environment. `/reload` updates session runtime content but does not rebuild the host-wide history manager.
+Restart the host after changing this block or its environment variables. `/reload` does not reload it.
 
 ## Replication and outages
 
-Remote replication is local-first:
+Replication starts locally:
+
+1. Tau writes each history change to local SQLite.
+2. In the same transaction, it adds the change to a local outbox on disk.
+3. The host sends pending changes to the endpoint in the background.
+4. Changes the service accepts are removed from the outbox.
+
+A service outage does not block sessions or local recording. Pending changes stay on disk and are sent again later, including after a host restart or the next history activity. The service applies each change only once, even if it arrives twice. Changes for one session are sent in order, and each session is sent independently of the others.
+
+If the service permanently rejects a change, for example because the session's attributes conflict with what it already has, Tau stops sending changes for that session only. The pending changes and the error stay in local SQLite, later changes for that session wait, and other sessions keep replicating. Temporary network, authentication, rate-limit, and service errors leave changes pending for a later retry. Both kinds of failure produce a `history_replication_failed` host diagnostic, without the API key:
+
+- Headless Tau commands print it to stderr.
+- The TUI distinguishes blocked replication from a retryable delay in the footer. A transcript notice keeps the affected session, operation ID (when known), and error.
+- An in-process SDK host delivers it only through `onDiagnostic`, when configured.
+
+Local entries keep everything recorded. For the remote copy, an entry larger than 1 MiB keeps its ID and metadata, but oversized content, arguments, or results are truncated in the middle with a marker. The host's local entry can therefore contain details the shared copy leaves out.
+
+With a remote target configured, history searches go only to the service. Tau never falls back to local results when the service is unreachable, because that would change which collection you are searching. Do not assume sessions recorded before you added the configuration appear remotely.
 
-1. Tau commits each history mutation to local SQLite.
-2. The same transaction appends an ordered operation to a durable local outbox.
-3. The host sends pending operations to the configured endpoint asynchronously.
-4. Successful acknowledgements remove those operations from the outbox.
+## Recover blocked replication
 
-A service outage does not block session execution or local transcript capture. Pending operations remain durable and are retried when replication is scheduled again, including after host restart or later history activity. The remote service applies operations idempotently. Tau preserves operation order within each session while processing separate session lanes independently.
+A permanent rejection blocks that session until you explicitly retry it. Restarting the host does not clear the block, also called a quarantine.
 
-A permanent operation-domain rejection, such as conflicting immutable session metadata, quarantines only that session's replication lane. Its pending operations and diagnostic remain in local SQLite, later operations for that session stay blocked, and unrelated sessions continue replicating. Transient transport, authentication, rate-limit, and service failures do not quarantine a lane; they leave endpoint replication pending for a later retry. Both kinds of failure produce a structured `history_replication_failed` host diagnostic without exposing the API key. Headless Tau commands write that diagnostic to stderr, the TUI presents a concise nonfatal footer notice without writing through the active renderer, and an in-process SDK host delivers it only through `onDiagnostic` when configured.
+Run this on the affected host with its remote history configuration:
 
-Local entries retain their complete captured payloads. For remote replication, an entry larger than 1 MiB keeps its identity and metadata but middle-truncates oversized content, arguments, or results with an explicit marker. Remote history is therefore useful for retrieval, but the host's local entry can contain details that the shared copy intentionally omits.
+```sh
+tau history status
+```
+
+The command prints persisted quarantines for the configured endpoint as JSON. It does not require an API key. When a change fails, its diagnostic identifies the failed operation, even if earlier changes in the same request succeeded. Request-level and transport failures may have no operation ID.
 
-Configuring a remote target changes history-tool queries to use that service. Tau does not fall back to local query results when the service is unreachable, because that would silently change collection scope. Existing histories that were never associated with the target should not be assumed to appear remotely merely because the config block was added later.
+Fix the underlying service or data problem before retrying. If the service needs an update, deploy it with `tau history setup` using the setup requirements above and the existing credentials. Then, on the affected host, run:
+
+```sh
+tau history retry --session <session-id>
+```
+
+Retry requires the host's history API key. It clears only the named session's quarantine and sends pending changes with their original operation IDs. Local history and queued changes are preserved. The command can also send pending changes for other unblocked sessions at the same endpoint; other quarantines stay blocked.
+
+If the service permanently rejects the session again, Tau restores its quarantine. A temporary failure leaves changes pending for a later retry. The command exits unsuccessfully if the selected session remains blocked or a temporary failure prevents replication from completing.
 
 ## Verify operation
 
-Verify the owning boundary rather than inspecting credentials or dumping transcripts:
+Check that each step works, without looking at credentials or dumping transcripts:
 
-1. Confirm setup completed its D1 migration and Worker deployment without errors.
-2. Add the global config and key environment to one host, then restart it.
-3. Create a small disposable session with distinctive, nonsensitive text.
-4. Explicitly ask the agent to search history for that session, following the history tool's `docs` step.
-5. If using several hosts, repeat from another host and allow for asynchronous replication and digest generation.
+1. Confirm setup finished the D1 migration and Worker deployment without errors.
+2. Add the global config and the key's environment variable on one host, then restart it.
+3. Create a small throwaway session with distinctive, non-sensitive text.
+4. Ask the agent explicitly to search history for that session. It reads the capability's `docs` first.
+5. With several hosts, repeat from another host, and allow time for replication and summaries.
 
-A transcript can become remotely searchable before its generated digest appears. Search results without a digest are not evidence of a failed import. Open the service URL and sign in to the browser view to confirm the session card and transcript are available.
+A transcript can become searchable before its summary appears, so a missing summary does not mean replication failed. Open the service in a browser and sign in to confirm the session and its transcript are there.
 
-Cloudflare operational failures are visible through normal Worker logs, Cron Events, and D1 diagnostics. The service has no separate Tau administration dashboard or status endpoint.
+Cloudflare problems show up in the normal Worker logs, Cron Events, and D1 diagnostics. The service has no separate admin dashboard or status endpoint.
 
 ## Troubleshooting
 
-**`history` is configured but no API key is available.** Set `TAU_HISTORY_API_KEY`, populate the environment variable named by `apiKeyEnv`, or use an inline key only when the config file is appropriately protected. Restart the host.
+**`history` is configured but no API key is available.** Set `TAU_HISTORY_API_KEY`, set the variable named by `apiKeyEnv`, or use an inline key only if the config file is well protected. Restart the host.
+
+**The agent has no history capability.** The active persona must select `history`. Fix the persona and run `/reload` while idle.
 
-**The history tool returns a service error while the session still works.** Remote queries and asynchronous replication can fail independently of session execution. Check endpoint reachability and Worker logs without printing the bearer key. Local capture should continue unless the session also contains a `history unavailable` warning.
+**The history capability returns a service error while the session works.** Remote searches and replication can fail without affecting the session. Check that the endpoint is reachable and read the Worker logs, without printing the key. Local recording continues unless the session also shows a `history unavailable` warning.
 
-**The browser view repeatedly asks for credentials.** Use the fixed username `tau` and the viewer password installed by the latest setup. The history API key is a bearer credential for hosts and does not authenticate the browser.
+**The browser keeps asking for credentials.** Use username `tau` and the viewer password from the latest setup. The API key is for hosts and does not work in the browser.
 
-**A session does not appear in remote search.** Confirm that the host was restarted with the global remote config, that the session was opened while that target was active, and that later history activity has had a chance to flush the durable outbox. Check host logs for `history_replication_failed`; a quarantined failure affects only the named session, while an unquarantined endpoint failure remains retryable. Do not assume remote digests are immediate.
+**A session does not appear in remote search.** Confirm the host was restarted with the remote config, the session was used while the config was active, and enough history activity has happened to send the outbox. Check host logs for `history_replication_failed`. A permanent rejection affects only the named session, while other failures are retried. Summaries are not immediate.
 
-**Local history became unavailable.** Check host-side filesystem access, free space, and ownership for `~/.config/tau`. Restarting is required to reopen a manager disabled by an earlier local failure.
+**Local history became unavailable.** On the host, check that you are running as the expected user and home, and check file access, free space, and ownership of `~/.config/tau`, the Node version, and whether another process is using the database. A restart is needed to reopen history after a local failure. Do not open, edit, replace, or delete the SQLite files as a first repair, and do not inspect outbox rows or keys.
 
-**Search finds material removed from model context.** This is expected after compaction. It is not expected after a successful rewind of that suffix; if the remote copy lags, wait for its truncation operation to replicate.
+**Search finds material removed from the model's context.** This is expected after compaction. After a rewind, the removed entries should disappear; if the remote copy still has them, wait for the deletion to replicate.
 
 ## Destroy the remote service
 
-`tau history destroy --yes` permanently deletes the bundled `tau-history` Worker and D1 database. This removes the shared remote transcripts and digests. It does not delete each host's local `history.sqlite` database, and it is not a substitute for a retention or export plan.
+`tau history destroy --yes` permanently deletes the `tau-history` Worker and D1 database, and with them the shared transcripts and summaries. It does not delete any host's local `history.sqlite`, and it is not a substitute for a retention or export plan.
 
-Run destruction only after confirming that the service and its data are no longer needed:
+Run it only once you are sure the service and its data are no longer needed:
 
 ```sh
 tau history destroy --yes
 ```
 
-The command requires `CLOUDFLARE_API_TOKEN`. It reports each resource separately and treats already-absent Tau history resources as absent. If one deletion fails, inspect the reported partial result before retrying. Remove obsolete host `history` config and restart those hosts afterward, otherwise their remote queries and replication attempts will continue to fail.
+The command needs `CLOUDFLARE_API_TOKEN`. It reports each resource separately and treats Tau history resources that are already gone as deleted. If one deletion fails, read the partial result before retrying. Afterward, remove the `history` config from your hosts and restart them; otherwise their remote searches and replication keep failing.

package/dist/core/static/tau_docs/image-generation.md

@@ -16,18 +16,20 @@ Requires an OpenAI or Google API key for the selected model. See [feature-specif
 
 ## Models and capabilities
 
-`--model` is required; the CLI has no implicit default. Start with `gpt-image-2.5-flare` at `--quality medium` for everyday generation and editing. Increase quality or choose `gpt-image-2.5-sunburst` when precise edits justify the extra effort. See [approximate cost](#approximate-cost) before choosing settings.
+`--model` is required; there is no default. Start with `gpt-image-2.5-flare` at `--quality medium` for everyday generation and editing, balancing quality and cost.
 
-Choose size, resolution, and aspect ratio for the intended use; there is no recommended universal size. Dimensions in the examples illustrate particular use cases. Omitted controls use provider defaults, except `--format`, which defaults to `png`. Unsupported options fail before generation.
+For demanding generation and editing where image quality is the priority, choose `gemini-nano-banana-2.1` or `gpt-image-2.5-sunburst`. Nano Banana supports very wide aspect ratios and resolution tiers up to `4K`. Sunburst supports exact dimensions, transparent backgrounds, and PNG/JPEG/WebP output. See [approximate cost](#approximate-cost) before choosing settings.
+
+Choose size, resolution, and aspect ratio for the intended use; no single size fits everything. The sizes in the examples are for those particular cases. Options you leave out use the provider's defaults, except `--format`, which defaults to `png`. Unsupported options fail before anything is generated.
 
 | Model | Resolution | Aspect ratios | Thinking | Other controls |
 | --- | --- | --- | --- | --- |
-| `gemini-3-pro-image` | `1K`, `2K`, `4K` | Standard | Provider-managed | PNG |
-| `gemini-3.1-flash-image` | `512`, `1K`, `2K`, `4K` | Standard and wide | `minimal`, `high` | PNG |
-| `gemini-3.1-flash-lite-image` | `1K` | Standard and wide | `minimal`, `high` | PNG |
+| `gemini-nano-banana-2.1` | `1K`, `2K`, `4K` | Standard and wide | `minimal`, `medium`, `high` | PNG |
 | `gpt-image-2.5-flare` | Exact `--size` | Through dimensions | Not exposed | Quality, background, encoding, compression |
 | `gpt-image-2.5-sunburst` | Exact `--size` | Through dimensions | Not exposed | Quality, background, encoding, compression |
 
+Google's defaults are `1K` resolution and `medium` thinking. Use `--thinking minimal` for faster generation and lower thinking-token usage.
+
 Standard `--aspect-ratio` values are `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. Wide values additionally include `1:4`, `4:1`, `1:8`, `8:1`. Resolution tiers describe approximate output size.
 
 OpenAI controls:
@@ -42,9 +44,9 @@ Gemini does not support transparent-background generation ([Google documentation
 
 ## Input and examples
 
-Supply exactly one of `--prompt` and `--prompt-file` (UTF-8). Repeat `--reference` for local PNG, JPEG, or WebP files. References retain their order and original bytes. OpenAI reference requests use the edit endpoint.
+Give exactly one of `--prompt` and `--prompt-file` (UTF-8). Repeat `--reference` for each local PNG, JPEG, or WebP reference image. References are sent in order and unchanged. With references, OpenAI requests use the edit endpoint.
 
-Up to 16 references are accepted for OpenAI and 14 for Gemini; Flash Lite is not optimized for multiple references. Each reference is limited to 50 MB. Gemini's complete serialized request is limited to 19 MB, including the prompt, base64-encoded references, and JSON escaping.
+Up to 16 references are accepted for OpenAI and 14 for Gemini. Each reference is limited to 50 MB. Gemini's complete serialized request is limited to 19 MB, including the prompt, base64-encoded references, and JSON escaping.
 
 Create an asset:
 
@@ -69,7 +71,7 @@ Generate at a higher resolution using a reference:
 
 ```bash
 tau tool image-generate \
-  --model gemini-3-pro-image --reference ./sauna.png \
+  --model gemini-nano-banana-2.1 --reference ./sauna.png \
   --prompt 'Recreate this image at higher resolution. Preserve composition and colors; refine fine detail.' \
   --aspect-ratio 16:9 --resolution 4K --output ./sauna-4k.png
 ```
@@ -84,7 +86,7 @@ for i in 1 2 3 4; do
 done
 ```
 
-Each invocation is independent; edits use only the supplied prompt and references.
+Each run is independent; an edit sees only the prompt and references you give it.
 
 ## Outputs and recovery
 
@@ -94,13 +96,13 @@ The output's parent directory must exist. Neither the output nor `<output>.parts
 - `image.<format>`: the published image. Gemini responses are converted to PNG when needed; OpenAI bytes are saved as returned.
 - `manifest.json`: model, output path, usage, and `source` with the original filename and provider-declared MIME type (`null` when absent).
 
-Original bytes and usage remain available if conversion fails. Conversion may discard embedded metadata; use the original when provenance matters.
+The original bytes and usage are kept even if conversion fails. Conversion may drop embedded metadata, so use the original when provenance matters.
 
-Failures exit nonzero and identify the invalid option or failed processing stage. Existing output or artifact paths require a fresh `--output` path; preserve retained recovery artifacts. Once generation starts, errors report the retained directory, which may be empty or incomplete. If final publication fails, the error points to the completed image to copy to a fresh path without generating again. Requests are not automatically retried because a failed request may already have incurred a charge; another generation request may incur another charge.
+Failures exit nonzero and name the invalid option or the step that failed. If the output or `.parts` path already exists, choose a new `--output` path, and keep the existing files in case you need them. Once generation has started, errors give the path of the kept directory, which may be empty or incomplete. If only the final copy to `--output` fails, the error points to the finished image, so copy it to a new path instead of generating again. Requests are never retried automatically, because a failed request may already have been charged, and a new request may be charged again.
 
 ## Approximate cost
 
-Use Flare for fast everyday images and drafts; reserve Sunburst for demanding edits where preservation and precision matter most. Start at `medium`, use `low` for inexpensive exploration, and increase quality only when the result needs it. Explicit `--size` and `--quality` make budgeting more predictable than `auto`.
+For OpenAI models, start at `--quality medium`, use `low` for inexpensive exploration, and increase quality when the result needs it. Explicit `--size` and `--quality` make budgeting more predictable than `auto`. For Nano Banana, account for resolution and thinking usage as well as input costs.
 
 ### OpenAI: cost per image
 
@@ -121,12 +123,12 @@ For example, 100 square 1024-pixel drafts at `low` have an estimated output cost
 
 Approximate USD image-output costs from [Google pricing](https://ai.google.dev/gemini-api/docs/pricing), excluding input and text/thinking usage:
 
-| Model | 1K | 2K | 4K | When to choose it |
-| --- | --- | --- | --- | --- |
-| `gemini-3.1-flash-lite-image` | $0.034 | Unsupported | Unsupported | Simple 1K images; not optimized for multiple references |
-| `gemini-3.1-flash-image` | $0.067 | $0.101 | $0.151 | Resolution tiers and very wide aspect ratios |
-| `gemini-3-pro-image` | $0.134 | $0.134 | $0.24 | Higher-resolution reference-based work with standard aspect ratios |
+| Model                    | 1K      | 2K      | 4K     |
+| ------------------------ | ------- | ------- | ------ |
+| `gemini-nano-banana-2.1` | $0.0336 | $0.0504 | $0.113 |
+
+Input costs $1.50 per million tokens. Text and thinking output cost $7.50 per million tokens, in addition to image output. The manifest records provider-reported usage.
 
 Use OpenAI when transparent backgrounds or JPEG/WebP output are required. Compare the quality needed for the task, not just matching tier names across providers. Check [OpenAI pricing](https://developers.openai.com/api/docs/guides/image-generation#gpt-image-25-costs) and Google pricing for current rates before large batches.
 
-See [command-line tools](tools.md) for command discovery and execution ownership.
+See [command-line tools](tools.md) for the other tools and where commands run.

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

@@ -1,48 +1,47 @@
 # Tau documentation
 
-Tau ships this canonical product guide with the host so agents and people can work from the same version-matched contracts. It covers supported operation, configuration, integrations, and troubleshooting, including the machine boundaries that matter in local and remote sessions.
-
-The intrinsic `tau_docs` tool reads one exact Markdown path at a time. It does not search files, list current settings, or inspect client-local state. Start here, choose the page that matches the task, and pass its flat path exactly.
+These pages describe how to install, configure, operate, and integrate the version of Tau they ship with. Tau's agent reads the same pages through its built-in documentation tool, one page at a time.
 
 ## Start and orient
 
-- [Getting started](getting-started.md) covers installation, provider setup, and a first local session.
-- [Ownership and scope](ownership-and-scope.md) explains the client, host, execution environment, and Telegram runner. Read it before changing paths or remote-session configuration.
-- [TUI](tui.md) covers interactive commands, keybindings, themes, speech, and local presentation behavior.
-- [Troubleshooting](troubleshooting.md) provides checks for common startup, configuration, provider, tool, and remote-session failures.
+- [Getting started](getting-started.md): install Tau, set up a provider, and run a first local session.
+- [Ownership and scope](ownership-and-scope.md): which machine runs what in local and remote sessions. Read it before changing paths or remote-session configuration.
+- [TUI](tui.md): interactive commands, keybindings, themes, speech, and other terminal behavior.
+- [Troubleshooting](troubleshooting.md): checks for common startup, configuration, provider, tool, and remote-session problems.
 
 ## Configure Tau
 
-- [Configuration](configuration.md) explains discovery, precedence, safe edits, reload behavior, and common scope mistakes.
-- [Configuration reference](config-reference.md) defines every current top-level `config.json` field and its apply boundary.
-- [Credentials](credentials.md) covers API keys, Codex OAuth accounts, secret precedence, and credential ownership.
-- [Models](models.md) explains the bundled and remotely refreshed model catalog.
-- [Personas](personas.md) covers model-facing behavior, reasoning, tools, and persona files.
-- [Subagents](subagents.md) explains available subagents, launch policy, model overrides, and supervision.
-- [Skills](skills.md) covers discovery, frontmatter, trigger sensitivity, and tool eligibility.
-- [Prompts and project context](prompts-and-project-context.md) explains prompt templates, `AGENTS.md`, and additional context files.
-- [Client tools](client-tools.md) covers command-backed tools that execute on the owning client.
-- [Security](security.md) summarizes trust boundaries, secret handling, process execution, and remote access.
+- [Configuration](configuration.md): where configuration lives, which layer wins, how to edit safely, and when changes apply.
+- [Configuration reference](config-reference.md): every top-level `config.json` field and when a change takes effect.
+- [Credentials](credentials.md): API keys, Codex OAuth accounts, key precedence, and where credentials belong.
+- [Models](models.md): the bundled model catalog and how it is refreshed.
+- [Personas](personas.md): model, instructions, reasoning, tools, and custom persona files.
+- [Subagents](subagents.md): when agents can start subagents, which models they may use, and how to supervise them.
+- [Skills](skills.md): skill discovery, frontmatter, trigger sensitivity, and tool eligibility.
+- [Prompts and project context](prompts-and-project-context.md): prompt templates, `AGENTS.md`, and extra context files.
+- [Client tools](client-tools.md): command-backed tools that run on the machine of the attached client.
+- [Security](security.md): trust boundaries, secrets, process execution, and remote access.
 
 ## Build integrations
 
-- [Session protocol](session-protocol.md) explains transports, envelopes, observed state, delta application, errors, and client rules.
-- [Session protocol method reference](session-protocol-methods.md) defines the complete current request surface and result shapes.
-- [Node SDK](node-sdk.md) covers client choices, the public session facade, streamed state, client tools, cancellation, and exported types.
-- [SDK browser diff review](sdk-diff-review.md) covers hosting the built-in review UI, durable state, one-shot submission, and lifecycle ownership.
+- [Session protocol](session-protocol.md): transports, message envelopes, session state, deltas, errors, and rules for clients.
+- [Session protocol method reference](session-protocol-methods.md): every request method and its result.
+- [Node SDK](node-sdk.md): choosing a client, the session API, streamed state, client tools, cancellation, and exported types.
+- [SDK browser diff review](sdk-diff-review.md): hosting the built-in review UI from an SDK application.
 
 ## Work with sessions and services
 
-- [Tools](tools.md) explains built-in tool availability, execution, cancellation, and code-mode tools.
-- [Sessions](sessions.md) covers creation, turns, queueing, compaction, rewind, recovery, and persistence.
-- [Remote sessions](remote-sessions.md) explains `serve`, `attach`, remote paths, and transport authentication.
-- [History](history.md) covers local transcript history, optional remote replication, and the history tool.
-- [Nook](nook.md) explains configuration and operation of the optional static mini-app platform.
-- [Telegram](telegram.md) covers runner configuration, projects, workspaces, routing, and recovery.
+- [Tools](tools.md): built-in tools, when they are available, how they run and stop, and code-mode tools.
+- [Sessions](sessions.md): creating sessions, turns, queueing, compaction, rewind, recovery, and storage.
+- [Remote sessions](remote-sessions.md): `serve`, `attach`, remote paths, and authentication.
+- [History](history.md): searchable local history, optional remote replication, and the history tool.
+- [Nook](nook.md): setting up and running the optional static mini-app platform.
+- [Telegram](telegram.md): running the Telegram runner, bot access, chat commands, attachments, and recovery.
+- [Telegram projects and workspaces](telegram-projects.md): repository, persistent-directory, and composite projects, workspace lifecycle, and provision hooks.
 
 ## Run command-line tools
 
-- [PDF unpacking](pdf-unpacking.md) covers PDF OCR with Mistral, Markdown extraction, and page-image patches.
-- [Image generation](image-generation.md) covers image generation and reference editing with Google and OpenAI.
-- [Speech generation](speech-generation.md) covers caller-chunked narration and dialogue, ElevenLabs voices, and long-form WAV assembly.
-- [OpenRouter](openrouter.md) covers standalone typed decisions and text, image, audio, and video understanding with fixed model choices.
+- [PDF unpacking](pdf-unpacking.md): OCR PDFs with Mistral into Markdown and page images.
+- [Image generation](image-generation.md): generate and edit images with Google and OpenAI.
+- [Speech generation](speech-generation.md): narration and dialogue with ElevenLabs voices, assembled into long WAV files.
+- [OpenRouter](openrouter.md): typed decisions and text, image, audio, and video understanding with fixed models.

package/dist/core/static/tau_docs/manifest.json

@@ -27,6 +27,7 @@
     "history.md",
     "nook.md",
     "telegram.md",
+    "telegram-projects.md",
     "security.md",
     "troubleshooting.md"
   ]