yoloyolo/.planning/milestones/v1.1-phases/06-config-package-and-sound-overrides/06-CONTEXT.md

# Phase 6: Config Package and Sound Overrides - Context

**Gathered:** 2026-03-26
**Status:** Ready for planning

<domain>
## Phase Boundary

Add a TOML-based configuration system that lets users override frequency and waveform per traffic class, with auto-discovery from standard paths, explicit `--config` flag, partial override semantics (only specified fields change), and strict unknown-key validation. Wire the merged config into the synthesis pipeline via the injection seam created in Phase 5.

Requirements covered: CFG-01 through CFG-05.

</domain>

<decisions>
## Implementation Decisions

### TOML Schema Design
- **D-01:** Use keyed TOML tables `[sounds.<classname>]` for per-class overrides. Each table supports `frequency` (float64, Hz) and `waveform` (string: "sine", "square", "sawtooth", "triangle"). Class names match `classify.TrafficClass` string values (e.g., `[sounds.ICMP]`, `[sounds.HTTPS]`).
- **D-02:** Top-level structure is flat — no deeply nested hierarchies. Future phases (custom rules) will add `[[rules]]` array-of-tables at the top level.

### Config Merge Semantics
- **D-03:** Per-field overlay merge — only fields explicitly set in TOML override defaults. Unspecified fields retain their built-in values. For example, setting only `frequency` for ICMP leaves its waveform and harmonics unchanged. This satisfies CFG-04 (partial override without replicating entire config).
- **D-04:** Merge produces a `map[classify.TrafficClass]FreqConfig` that is passed to `synth.NewBank()` via the injection seam from Phase 5. The default map is `synth.ClassFreqConfigs`.

### Auto-Discovery and Precedence
- **D-05:** Discovery order (most-specific wins): `--config <path>` > `./netsynth.toml` > `~/.config/netsynth/config.toml`. If `--config` is specified and the file does not exist, exit with a clear error before capture begins (CFG-03). If no config is found via auto-discovery, proceed silently with defaults (CFG-02).
- **D-06:** Only one config file is loaded — no multi-file merge. The first found in precedence order wins entirely.

### Validation and Error Reporting
- **D-07:** Unknown keys cause an immediate startup error naming the unrecognized key (CFG-05). Use TOML strict decoding to detect unknown keys. Suggest the closest valid key name if edit distance is small (nice-to-have, Claude's discretion on implementation).
- **D-08:** Type mismatches (e.g., `frequency = "not a number"`) produce a clear error with field name and expected type, before capture begins.
- **D-09:** Unknown class names in `[sounds.<classname>]` produce a warning (not error) — this prepares for Phase 7 where user-defined class names are valid.

### Pipeline Wiring
- **D-10:** `encode.RunSynthesis` signature changes to accept the merged config map (or loads config internally). The `--config` flag is added to the Cobra root command in `cmd/netsynth/main.go`.
- **D-11:** Config loading happens once at startup, before any capture begins — fail fast on all config errors.

### Claude's Discretion
- TOML library choice (BurntSushi/toml vs pelletier/go-toml) — researcher should evaluate both
- Whether to create a dedicated `config` package or keep loading in `cmd/netsynth`
- Waveform string-to-WaveformType mapping implementation details
- Edit distance algorithm for typo suggestions (or skip if complexity isn't justified)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Injection Seam (Phase 5 output)
- `synth/bank.go` — `NewBank(tau float64, cfgs map[classify.TrafficClass]FreqConfig)` — the injection point for merged config
- `synth/config.go` — `ClassFreqConfigs` default map, `FreqConfig` struct with `WaveformType` field, `WaveformPresetHarmonics()` function
- `encode/mp3.go` — `RunSynthesis()` calls `synth.NewBank(1.0, synth.ClassFreqConfigs)` — the call site to modify

### CLI Entry Point
- `cmd/netsynth/main.go` — Cobra command setup, flag definitions, `run()` function that dispatches to live/pcap modes

### Requirements
- `.planning/REQUIREMENTS.md` — CFG-01 through CFG-05 acceptance criteria

### Prior Context
- `.planning/phases/05-waveform-types-and-bank-decoupling/05-CONTEXT.md` — Phase 5 decisions (D-02 WaveformType, D-05 bank injection seam)

No external specs — requirements fully captured in decisions above.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `synth.ClassFreqConfigs` — Default config map (14 entries), serves as base for merge
- `synth.WaveformType` enum — Maps to TOML waveform strings (sine/square/sawtooth/triangle)
- `synth.NewBank(tau, cfgs)` — Already accepts injected config map (Phase 5)
- `classify.TrafficClass` (string type) — Keys for config map, matches TOML section names
- `classify.AllClasses()` — Returns all 14 built-in class names for validation

### Established Patterns
- Cobra for CLI flags — add `--config` flag in same pattern as existing flags
- `encode.RunSynthesis` is the single call site for synthesis — modification point is narrow
- Package-level vars (`ClassFreqConfigs`, `DefaultRules`) serve as defaults — config system overlays on top

### Integration Points
- `cmd/netsynth/main.go:run()` — Config loading inserts between flag parsing and capture start
- `encode.RunSynthesis()` — Must receive merged config map (currently hardcoded to `synth.ClassFreqConfigs`)
- `synth.FreqConfig.WaveformType` field — Set from TOML waveform string after parsing

</code_context>

<specifics>
## Specific Ideas

No specific requirements — standard TOML config pattern with partial merge semantics.

</specifics>

<deferred>
## Deferred Ideas

- `--print-config` command (CFG-06) — scoped to Phase 7
- Custom classification rules (`[[rules]]` TOML blocks) — scoped to Phase 7
- Config hot-reload — explicitly out of scope per REQUIREMENTS.md

</deferred>

---

*Phase: 06-config-package-and-sound-overrides*
*Context gathered: 2026-03-26*