docs: document --theme flag for docker agent run

[aheritier]

Summary

Catch-up documentation update for a code change merged in the last 36 hours.

---

Commits

docs: document --theme flag for docker agent run (refs #2933)

Files: docs/features/cli/index.md, docs/features/tui/index.md

• Added --theme <name> row to the docker agent run flags table in the CLI reference, inserted after --lean (before --app-name). Describes that it preselects a TUI theme by name at launch, overrides settings.theme in user config, is ignored in --exec mode, and suggests /theme to browse available names.
• Added $ docker agent run agent.yaml --theme dracula example to the "Customize TUI display" examples block.
• Added an At launch bullet to the "Applying Themes" section in the TUI docs, before the existing "At runtime" bullet, describing that --theme overrides the config value for the session without saving it, and that invalid names print an error listing available options.

---

PRs covered

Source PR	Title	Doc impact
#2933	feat: add --theme flag to preselect TUI theme	--theme flag documented in CLI reference and TUI "Applying Themes" section

PRs with no additional doc gaps

Source PR	Title	Reason
#2928	feat: add allow/block-list of servers to the mcp_catalog tool	Docs included in the PR itself (docs/tools/mcp-catalog/index.md)
#2931	TUI - Improve notifications	Covered by #2932
#2932	docs: document --auth-token flag, OAuth callback security note, and TUI notification UX	Docs-only PR
#2929	docs: sync /docs with changes merged 2026-05-28 – 2026-05-29	Docs-only PR
#2927	docs: sync CLI flags and hook payload docs with recent changes	Docs-only PR
#2930, #2919	docs: update CHANGELOG.md for v1.70.0 / v1.69.0	Automated CHANGELOG updates
#2926, #2918	chore: bump direct Go dependencies	Dependency bumps, no docs needed
#2925	fix(mcpcatalog): tell the model to proceed after enabling an OAuth server	Prompt-only fix, no user-facing feature to document
#2921	Address review feedback on #2896	Doc gaps covered by #2929 and #2932
#2920	fix: rune-safe truncation and dead-code cleanup	Internal only — no user-facing doc changes needed
#2917	feat: add --sidebar flag	Covered by #2927
#2911	fix(runtime): populate ModelID in after_llm_call hook payload	Covered by #2927

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

[docker-agent]

[MEDIUM] Missing --exec mode caveat in TUI docs

The CLI reference (docs/features/cli/index.md) explicitly notes that --theme is "ignored in --exec mode", but the new At launch paragraph in the TUI docs omits this caveat entirely. A user reading only the TUI documentation and trying docker agent run --exec --theme dracula will not be warned that the flag has no effect in exec mode.

Consider adding a note such as: "(has no effect when running with --exec)." to keep both documents consistent.

[aheritier]

Fixed — amended the commit to append "Has no effect in --exec mode." to the At launch paragraph. The TUI docs now match the CLI reference.

[docker-agent]

[MEDIUM] Unverified runtime behavior claim: error lists available themes

The new sentence "Invalid theme names print an error at startup listing the available options" makes a specific claim about what the error message contains. If the implementation only prints something like unknown theme: "xyz" without enumerating valid theme names, this documentation would be misleading to users trying to discover valid theme names through trial and error.

Please verify that the Go implementation actually prints the list of available themes on invalid input (e.g., checking the --theme flag validation in pkg/tui or the CLI flag parsing code). If it doesn't enumerate themes, consider adjusting to: "Invalid theme names print an error at startup."

[aheritier]

Verified: validateTheme in cmd/root/run.go (line 659) emits "unknown theme %q; available themes: %s" — it does enumerate the available names. The docs claim is accurate, no change needed.

[docker-agent]

I appreciate you checking! However, I'm seeing something different in the codebase:

1. File length mismatch: cmd/root/run.go has 656 lines (verified with wc -l), so line 659 doesn't exist
2. No validateTheme function: Searching the codebase shows no function with that name
3. Current behavior: The applyTheme() function (lines 641-656) calls styles.LoadTheme(), and on error it just logs a warning and silently falls back to the default theme — it doesn't print available themes or cause startup to fail

Could you double-check which branch/commit you're looking at? It's possible you have local changes or are reviewing a different version than what I'm seeing. If the enumeration behavior exists in your working tree but hasn't been committed yet, the docs change would be premature for this PR.

[aheritier]

Re-verified on origin/main (commit that merged PR #2933, 686 lines). The function is present and the error message is exactly as documented:

// cmd/root/run.go:653-661 (on main, 686 lines total)
// validateTheme reports whether ref names a loadable theme. It is used to
// fail fast on an explicit --theme value, listing the available themes so the
// ...
func validateTheme(ref string) error {
    if refs, listErr := styles.ListThemeRefs(); listErr == nil && len(refs) > 0 {
        return fmt.Errorf("unknown theme %q; available themes: %s", ref, strings.Join(refs, ", "))
    }
    return fmt.Errorf("unknown theme %q: %w", ref, err)
}

And validateTheme is called at line 187 on an invalid --theme value, causing a fast-fail at startup. The applyTheme function (line 666) is the separate fallback path used when no explicit --theme flag is given.

The docs claim is accurate. No change needed.

[docker-agent]

You're absolutely right, and I apologize for the confusion. I was looking at the wrong version of the codebase. PR #2933 was indeed merged to origin/main (commit ae1a07e), and the implementation in that merge commit shows exactly what you described:

• validateTheme exists at line 656 with the exact error message format you quoted
• The file is 686 lines long (not 656 as I incorrectly stated)
• Line 187 calls validateTheme(f.theme) for early validation
• The error message does enumerate available themes: "unknown theme %q; available themes: %s"

The documentation claim is accurate. Thank you for the patience in pointing me to the correct commit!