docs: update configuration, sandbox, tools, Go SDK, and MCP catalog docs

docs/configuration/models/index.md

@@ -57,6 +57,27 @@ models:
 | `track_usage`         | boolean    | ✗        | Track and report token usage for this model                                           |
 | `routing`             | array      | ✗        | Rule-based routing to different models. See [Model Routing]({{ '/configuration/routing/' | relative_url }}). |
 | `provider_opts`       | object     | ✗        | Provider-specific options (see provider pages)                                        |
+| `title_model`         | string     | ✗        | Model used for session-title generation. Can be a named model from the `models:` section or an inline `provider/model` string. When omitted, the agent's primary model generates titles. Cannot be combined with `first_available`. |
+
+## Delegating Session-Title Generation
+
+The `title_model` field lets a heavyweight primary model hand off the cheap
+title-generation call to a smaller, faster model:
+
+```yaml
+model: anthropic/claude-opus-4-7
+title_model: anthropic/claude-haiku-4-5
+```
+
+The value can be a named entry from the `models` stanza or an inline
+`provider/model` string. When omitted, the agent's primary model generates
+titles.
+
+<div class="callout callout-warning" markdown="1">
+<div class="callout-title">Constraint
+</div>
+  <p><code>title_model</code> cannot be combined with <code>first_available</code> model selection — the combination is rejected at validation time.</p>
+</div>
 
 ## First Available Models
 

docs/configuration/sandbox/index.md

@@ -190,7 +190,7 @@ Every text file copied into the kit is run through [portcullis](https://github.c
 
 ### Network allowlist
 
-The sandbox templates ship with a default-deny network proxy that allows the major model providers but blocks `*.docker.com` and every package-registry / source host the auto-installer reaches for. When the agent declares MCP or LSP toolsets that have a `command` and an installable `version`, the kit build resolves each toolset's package against the [aqua](https://aquaproj.github.io/) registry and computes the minimal set of hosts the in-sandbox auto-installer will need (Go module proxy + toolchain bootstrap for `go_install` packages, GitHub release hosts for `github_release` packages, …). Those hosts — and the configured [`--models-gateway`]({{ '/features/cli/' | relative_url }}#runtime-configuration-flags) — are then allow-listed on the sandbox proxy. If a per-toolset registry lookup fails, a conservative fallback union is used so the run can still succeed; the affected toolsets are surfaced in the printed summary.
+The sandbox templates ship with a default-deny network proxy that allows the major model providers but blocks `*.docker.com` and every package-registry / source host the auto-installer reaches for. When the agent declares MCP or LSP toolsets that have a `command` and an installable `version`, the kit build resolves each toolset's package against the [aqua](https://aquaproj.github.io/) registry and computes the minimal set of hosts the in-sandbox auto-installer will need (Go module proxy + toolchain bootstrap for `go_install` packages, GitHub release hosts for `github_release` packages, …). Those hosts, `models.dev` (needed so the in-sandbox agent can resolve model metadata such as context limits, pricing, and capabilities — without it the first catalog lookup fails with a `403 Blocked by network policy` error), and the configured [`--models-gateway`]({{ '/features/cli/' | relative_url }}#runtime-configuration-flags) — are then allow-listed on the sandbox proxy. If a per-toolset registry lookup fails, a conservative fallback union is used so the run can still succeed; the affected toolsets are surfaced in the printed summary.
 
 ### Caching
 

docs/configuration/tools/index.md

@@ -165,6 +165,18 @@ toolsets:
     args: ["mcp"]
 ```
 
+### Checksum Verification
+
+Where the aqua registry includes a checksum manifest, downloaded binaries are verified against it before installation. Verification behaviour depends on the checksum type advertised:
+
+- **Strong checksums (sha256, sha512, etc.)** — verified before the binary is installed. If the downloaded archive does not match, the install is aborted and an error is returned (fails closed).
+- **Unsupported or weak checksum types (e.g. md5, sha1)** — skipped with a warning; installation proceeds without verification.
+- **No manifest** — if no checksum is advertised in the registry entry, the binary is installed without verification.
+
+### version_overrides Resolution
+
+The auto-installer correctly resolves **`version_overrides`** entries in the aqua registry. Many common tools (for example, `fzf`) keep their package configuration — including download URLs and checksums — under `version_overrides` rather than at the top level of their registry entry. These tools previously failed to install silently; they are now handled correctly.
+
 ### Disabling Auto-Install
 
 **Per toolset** — set `version` to `"false"` or `"off"`:

docs/guides/go-sdk/index.md

@@ -31,6 +31,17 @@ docker-agent can be used as a Go library, allowing you to build AI agents direct
 | `pkg/model/provider/*` | Model provider clients                   |
 | `pkg/config/latest`    | Configuration types                      |
 | `pkg/environment`      | Environment and secrets                  |
+| `pkg/tui/components/toolconfirm` | Tool-confirmation policy: `Decision` enum, `BuildPermissionPattern`, key bindings, and rejection-reason presets. Share this instead of copying the permission-pattern logic. |
+| `pkg/tui/service`      | `StaticSessionState` — a `SessionStateReader` with conservative fixed values, for rendering message/tool views outside the full TUI app. Replaces hand-rolled nine-method stubs. |
+| `pkg/tui/animation`    | `Stopper` / `StopView` — animation lifecycle contract. Call `StopAnimation` on views removed from the UI to prevent leaked tick subscriptions. |
+
+## Embedding TUI Components
+
+When building custom UIs on top of docker-agent's TUI primitives, three packages define the contracts that keep the runtime and the UI in sync:
+
+- **`pkg/tui/components/toolconfirm`** — import this package for the permission-decision policy rather than copying the pattern-building logic. The `Decision` enum, `BuildPermissionPattern` helper, and rejection-reason presets are the canonical source of truth: whatever pattern is shown to the user in the confirmation dialog is exactly the pattern granted to the runtime.
+- **`pkg/tui/service`** — use `StaticSessionState` as a stub `SessionStateReader` when rendering individual message or tool views outside the full TUI app. It returns conservative fixed values for all nine interface methods, eliminating the need for hand-rolled stubs.
+- **`pkg/tui/animation`** — implement `animation.Stopper` on any view that owns a tick-based animation. Call `StopAnimation` whenever a view is removed from the UI hierarchy to prevent leaked `time.Tick` subscriptions from firing against a dead view.
 
 ## Basic Example
 

docs/tools/mcp-catalog/index.md

@@ -102,6 +102,7 @@ A complete, runnable configuration lives in [`examples/mcp_catalog.yaml`](https:
 ## Notes and Limitations
 
 - **Streamable-http only.** The catalog deliberately excludes servers that require a local subprocess or the MCP gateway — declare those with [`type: mcp`]({{ '/configuration/tools/#mcp-tools' | relative_url }}) instead.
+- **Catalog membership changes between releases.** The set of available servers is updated with each docker-agent release as integrations are added or removed. Servers present in one release may not appear in the next.
 - **Blocking enable.** DNS, TCP, MCP handshake and any OAuth flow happen synchronously inside `enable_remote_mcp_server` so the agent gets a deterministic result in the same turn. On startup, however, the runtime probes tools non-interactively (`mcp.WithoutInteractivePrompts`); OAuth-pending servers fail fast there and are silently deferred to the next interactive turn — including the sidebar-only tool-count pass, where a dialog would be impossible.
 - **No prompt discovery.** MCP prompt lookups (`/prompts`) walk YAML-declared `mcp` toolsets directly; prompts exposed by servers activated through the catalog are not surfaced. Tools — the primary interface — work fine.
 - **Frozen at build time.** The list of servers is embedded in the binary. New entries land with each docker-agent release.