Skip to content

Document global YAML defaults vs per-agent overrides in settings docs #33

@rosspeili

Description

@rosspeili

Problem Statement

Per-agent timeout is documented in README and docs/EXAMPLES.md, but it is not obvious that defaults.timeout, defaults.litellm_model, and defaults.temperature in rooms.settings.yaml apply to shipped personas and the orchestrator unless overridden in the wizard. New users may edit only per-agent fields in-session and miss the global settings file.

Proposed Solution

  • Add a short subsection (EXAMPLES or ARCHITECTURE): “Global defaults vs per-agent overrides”.
  • Include a small table: defaults.litellm_model, defaults.timeout, defaults.temperature, defaults.orchestrator_model, and when the wizard overrides them.
  • Cross-link rooms.settings.example.yaml, python cli.py config init, and built-in fallbacks when no file exists.
  • No code changes required unless a one-line CLI hint on startup is desired (optional, separate commit).

Alternatives Considered

  • Rely on example YAML comments only — insufficient; example file is not read by everyone before first run.
  • Duplicate full settings schema in README — too heavy; link to example + one cheat-sheet table is enough.

Priority

Low 🟢

Additional Context

Complements #28; no dependency on presets or auto_select_first issues. Good good-first-issue for contributors comfortable with Markdown only.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomers
    No fields configured for Feature.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions