17d7b72c37
WIP checkpoint committed by Claude while Atlas was still in its final verification wave. Committed early deliberately: 11 files were sitting uncommitted with two of them untracked, and untracked files in this tree have been destroyed twice today by agent git cleanup -- the user's multi-provider-support plan and a config.local.yaml holding their tariff. Protecting the work cost nothing; losing it would have cost a whole plan. Deployment-specific values previously lived as an UNCOMMITTED modification to the tracked config/config.yaml. That arrangement failed seven times in one session: three agent checkout/stash/restore calls, two `git commit -am` sweeps that each needed a history rewrite, one ordinary branch switch, and one cleanup during this very plan. Once a value is correctly absent from git, every checkout, switch, pull and rebase wipes it -- that is the intended fix behaving as designed, which is what makes the arrangement itself the bug. load_config now deep-merges an optional config/config.local.yaml over the base before validation, so every consumer inherits it (poller, feedback, eval_proficiency, seed_local_dispatch_energy, admin, dispatcher). Mappings deep-merge; lists replace wholesale; the MERGED result is validated once so extra="forbid" still catches an overlay typo. The admin portal now writes to the overlay and never to config/config.yaml. An operator changing a knob in a loopback-only portal is making a local operational decision, not a project decision -- someone changing a project default edits config.yaml and commits it through git. This also removes the shadowing trap by construction rather than guarding against it. config/config.yaml stops being dirty in normal operation, which removes the condition behind every clobbering above. NOTE: final verification wave had not reported when this was committed. The suite was green at 1155 before it started; Atlas may amend or add commits on top. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VRQXz5SYZYVWscxS1QqF6U
34 lines
1.3 KiB
Markdown
34 lines
1.3 KiB
Markdown
# Local Overlay (`config/config.local.yaml`)
|
|
|
|
`config.local.yaml` is a gitignored, deep-merged overlay on top of the
|
|
tracked `config/config.yaml`. Anything placed in the overlay takes
|
|
precedence when `load_config()` merges the two files — the overlay only
|
|
needs the keys you want to change; everything else falls through to the
|
|
base.
|
|
|
|
## What belongs in the overlay
|
|
|
|
Values that are specific to your machine or deployment and would turn
|
|
`config/config.yaml` dirty if tracked:
|
|
|
|
- `local_energy.enabled` + `local_energy.tariff_usd_per_kwh` — metering
|
|
per-machine, tariff often differs between sites.
|
|
- `classifier.base_url` / `verification.base_url` — Ollama may live on a
|
|
different host or VPN address on each box.
|
|
- Any tuning knob you change between machines (`num_ctx` overrides,
|
|
per-host profile tweaks).
|
|
|
|
## What does NOT belong here
|
|
|
|
**Secrets.** Secrets (`NEURALWATT_API_KEY`, etc.) stay in `.env`. The
|
|
overlay is YAML loaded as configuration, not as a credential store.
|
|
|
|
## A dirty `config/config.yaml` is a smell
|
|
|
|
If your working copy of `config/config.yaml` is modified, someone edited
|
|
the shared defaults by hand. Move those edits into a new entry in
|
|
`config.local.yaml` — the base file should stay clean enough to commit
|
|
and share.
|
|
|
|
See `config/config.local.yaml.example` for concrete key examples.
|