Formalize and document `config.toml` (defaults sensatos, override surface)
- Dominant language
- Rust
- Stars
- 3
- Forks
- 1
- Avg merge
- 4h 50m
- Merged PRs (30d)
- 1
Description
Several features reference a global `config.toml` at `~/.config/dotagent/config.toml`: the daily-summary command mentions it as a TODO, the observability guide hints at it for OTel/retention, the rate-limit issue (sibling) needs it for `[notify_policy]`. But there is no single doc that says what fields exist, where defaults come from, and what overrides what.
The principle in [`CLAUDE.md`](CLAUDE.md) is "defaults sensatos out-of-the-box" — `config.toml` is only for *override*, never for activation. That principle deserves to be codified.
## Proposal
Formalize and document `config.toml`:
1. Pick the canonical path (`~/.config/dotagent/config.toml`).
2. Define every section that exists or is planned: `[telemetry]` (OTel endpoint, retention), `[metrics]` (Prometheus, sibling issue), `[notify_policy]` (sibling issue), `[paths]` (state dir, log dir overrides).
3. Document the precedence chain: env var > `config.toml` > built-in default.
4. Write [`docs/reference/config.md`](docs/reference/config.md) as the single source of truth.
Parsing is already partially implemented somewhere — this issue is about consolidating and documenting.
## Acceptance criteria
- [ ] `docs/reference/config.md` exists and lists every field, type, default, env override.
- [ ] `dotagent doctor` reports the resolved config (which fields came from defaults vs file vs env).
- [ ] Missing `config.toml` is NEVER an error. dotagent runs fully with defaults.
- [ ] Sample `config.toml` checked into the repo as `examples/config.toml.sample`.
- [ ] Every other doc that mentions config (`observability.md`, `notifications.md`, etc.) links here.
## Where to start
- `crates/dotagent-core/src/config.rs` — partial existing config struct.
- `crates/dotagent-telemetry/src/lib.rs` — telemetry config consumers.
- [`docs/guides/observability.md`](docs/guides/observability.md) — sets the pattern to follow ("out of the box" first, "customizing" as appendix).
## Non-goals
- Per-agent overrides (those go in `agent.toml`).
- Hot-reload of `config.toml` mid-daemon-run. Reload happens via SIGHUP, same as manifest reload.
Contributor guide
Research direction
Start with crates/dotagent-core/src/config.rs to inventory the existing config fields and parsing behavior, then trace consumers in crates/dotagent-telemetry/src/lib.rs. Use docs/guides/observability.md as the documentation pattern. Done means the reference, sample file, resolved-config reporting, default behavior, and cross-links cover the stated acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100