Skip to content

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

Merged
dgageot merged 7 commits into
mainfrom
docs/auto-update
Jun 11, 2026
Merged

docs: update configuration, sandbox, tools, Go SDK, and MCP catalog docs#3068
dgageot merged 7 commits into
mainfrom
docs/auto-update

Conversation

@aheritier

Copy link
Copy Markdown
Contributor

Documentation updates

This PR updates the docs to reflect five code changes merged into main in the last 36 hours.

Commit Source PR What changed
52f5b9d0 #3051 Document title_model config field for delegated session-title generation
6e2154af #3041 Note models.dev is always allowlisted in the sandbox network proxy
767067da #3046 Document checksum verification and version_overrides resolution in tool auto-install
e613b784 #3059 Document exported TUI embedding packages (toolconfirm, StaticSessionState, Stopper)
6fc01903 #3048 Note that MCP catalog membership changes between releases (Supabase and Tally removed)

Details

docs/configuration/models/index.mdtitle_model field (#3051)

Added a row to the Properties Reference table and a new "Delegating Session-Title Generation" section with a YAML example showing how to delegate title generation to a cheaper model (e.g. Opus → Haiku). Includes a warning callout that title_model cannot be combined with first_available.

docs/configuration/sandbox/index.mdmodels.dev allowlist (#3041)

The sandbox network proxy now always opens models.dev so the in-sandbox agent can resolve model metadata (context limits, pricing, capabilities). Without this, the first catalog lookup fails with 403 Blocked by network policy. Added models.dev to the auto-opened hosts in the network allowlist prose.

docs/configuration/tools/index.md — auto-install integrity and compatibility (#3046)

Added two subsections to the Auto-Installing Tools section:

  • Checksum Verification: downloaded binaries are now verified against the aqua registry checksum manifest before installation. Fails closed on advertised-but-mismatching checksums.
  • version_overrides Resolution: aqua registry version_overrides entries are now resolved correctly, fixing silent install failures for many common tools (e.g. fzf).

docs/guides/go-sdk/index.md — TUI embedding packages (#3059)

Added three packages to the Core Packages table (pkg/tui/components/toolconfirm, pkg/tui/service, pkg/tui/animation) and a new "Embedding TUI Components" section explaining the embedding contract: use toolconfirm for the shared permission policy, StaticSessionState as a stub SessionStateReader, and animation.Stopper to avoid tick leaks.

docs/tools/mcp-catalog/index.md — catalog membership note (#3048)

Added a bullet to Notes and Limitations: the catalog list changes between releases as integrations are added or removed (Supabase and Tally were removed in this cycle as their OAuth flows were unreliable).

PRs reviewed and found up to date

Source PR Reason
#3057 Internal TUI bug fix (skill loop), no user-facing behaviour change
#3053 Claude Fable 5 / fallbacks — anthropic docs updated in the same PR
#3052 Improved error message internals, no config/API change
#3050 Internal Anthropic max_tokens floor, no user-facing config change
#3049 TUI sidebar flicker fix, no user-facing behaviour change
#3047 Internal TUI refactor
#3045 Internal TUI refactor
#3042 Compaction bug fix — already documented by #3044
#3040 Internal TUI toast fix
#3036 1Password integration — secrets guide updated in the same PR
#3060 Test-only fix
#3039 Dependency bump

@aheritier aheritier requested a review from a team as a code owner June 11, 2026 04:07
@aheritier aheritier added the kind/docs Documentation-only changes label Jun 11, 2026

@docker-agent docker-agent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

Reviewed 5 documentation files (98 diff lines). Two LIKELY findings in newly added content:

Severity File Issue
🟡 MEDIUM docs/configuration/models/index.md:68 New example uses claude-opus-4-5; all other Opus refs in same file use claude-opus-4-7
🔵 LOW docs/configuration/tools/index.md:170 "Checksum-verified" bold claim overstates guarantee when weak/unsupported checksums are warn-skipped

Comment thread docs/configuration/models/index.md Outdated
title-generation call to a smaller, faster model:

```yaml
model: anthropic/claude-opus-4-5

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Likely incorrect Anthropic model identifier: claude-opus-4-5

The newly added YAML example uses anthropic/claude-opus-4-5, but every other Opus reference in this same file uses claude-opus-4-7 (lines 214, 227, 264). The Haiku model in this same example (claude-haiku-4-5) is consistent with line 382, suggesting the Opus suffix was inadvertently set to -4-5 instead of -4-7.

Users who copy this example verbatim may end up with an invalid model identifier. Consider changing to:

model: anthropic/claude-opus-4-7
title_model: anthropic/claude-haiku-4-5

Comment thread docs/configuration/tools/index.md Outdated

### Checksum Verification

Downloaded binaries are **checksum-verified** before installation. Verification fails closed: if a checksum is advertised in the aqua registry manifest but does not match the downloaded archive (or the manifest is missing entirely), the install is aborted and an error is returned. Checksum types that are unsupported or too weak are skipped with a warning rather than causing a hard failure.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LOW] "Checksum-verified" framing overstates the security guarantee

The bold checksum-verified claim in the opening sentence could mislead security-conscious readers: the same paragraph immediately documents that downloads with unsupported or weak checksum types are silently skipped with only a warning (no hard failure). A user relying on the "verified" label for security assurance would not realise that some downloads bypass hard verification entirely.

Consider qualifying the opening sentence, for example:

Downloaded binaries are verified against the aqua registry checksum manifest where supported. Verification fails closed on mismatches...

@aheritier aheritier added area/api For features/issues/fixes related to the usage of the cagent API area/config For configuration parsing, YAML, environment variables area/mcp MCP protocol, MCP tool servers, integration area/tools For features/issues/fixes related to the usage of built-in and MCP tools labels Jun 11, 2026
@dgageot dgageot merged commit 8c6a029 into main Jun 11, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/api For features/issues/fixes related to the usage of the cagent API area/config For configuration parsing, YAML, environment variables area/mcp MCP protocol, MCP tool servers, integration area/tools For features/issues/fixes related to the usage of built-in and MCP tools kind/docs Documentation-only changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants