avelino / avelino/dotagent

Formalize and document `config.toml` (defaults sensatos, override surface)

Open
#32 0 comments 0 reactions 0 assignees View on GitHub
area: telemetry type: docs type: feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.