[gold-silver-copper]

docs(rig-cli): help-agents says a settings.toml the launcher can't read exits 1

Description

rig help-agents said a RIG_HOME/settings.toml that cannot be read, is not TOML or has a table that does not read exits 2. Only a plugin's own settings table is refused by the agent with 2. The launcher reads the file and its [plugins] table itself before any agent exists (config::chosen, then FailedAt::Settings in rig-cli/src/build.rs), and main prints error: … and exits 1, with no JSON line. The text now says so, in rig help-agents and in the user guide (docs/agent.md, "Without the terminal view"), which said the same. Text change only.

Found by the 2026-11-07 architecture audit (finding f-8).

What users see change

• rig help-agents and docs/agent.md say that a settings.toml that cannot be read, is not TOML, or has a [plugins] table that does not read makes rig exit 1 with the reason on stderr and no JSON line, and that a plugin's own settings table that does not read still exits 2.

Changelog

• (rig-cli) rig help-agents and docs/agent.md give the right exit code (1, not 2) for a settings.toml the launcher cannot read.

Migration

None

Type of change

• Documentation update

Testing

• Text checked against crates/rig-cli/src/main.rs (error: and ExitCode::FAILURE), crates/rig-cli/src/build.rs (FailedAt::Settings), crates/rig-cli/src/run.rs (rebuild) and crates/rig-harness-protocol/src/config.rs (chosen).
• Real run at this head (box2, rig -p --json hi </dev/null with a fresh RIG_HOME): settings [ (not TOML), [plugins]\nenable = 3 (bad [plugins] table) and a duplicate key each exit 1, print error: <path>… on stderr and nothing on stdout.
• cargo xtask verify --affected --base origin/main at this head.

Checklist:

• I have updated READMEs and Rust docs affected by this change
• I have added tests that prove my fix is effective or that my feature works (docs only)
• I did not edit CHANGELOG.md or MIGRATING.md (they are generated at release)

Notes

Lines: production 0, docs +10 −6, tests 0.