# Phase 6: Config Package and Sound Overrides - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-03-26
**Phase:** 06-config-package-and-sound-overrides
**Areas discussed:** TOML structure, Config merge, Auto-discovery precedence, Error reporting
**Mode:** --auto (all areas auto-selected, recommended defaults chosen)

---

## TOML Structure

| Option | Description | Selected |
|--------|-------------|----------|
| Keyed table `[sounds.<classname>]` | Natural TOML pattern, matches traffic class names | ✓ |
| Flat key-value pairs | Simpler but doesn't scale to per-class overrides | |
| Nested `[sounds.<classname>.audio]` | Unnecessary nesting depth | |

**User's choice:** [auto] Keyed table `[sounds.<classname>]` (recommended default)
**Notes:** Matches classify.TrafficClass string values directly. Supports `frequency` and `waveform` fields per class.

---

## Config Merge Semantics

| Option | Description | Selected |
|--------|-------------|----------|
| Per-field overlay | Only specified fields override defaults (CFG-04) | ✓ |
| Full section replace | Setting any field in a class replaces all fields | |
| Deep merge with arrays | Overkill for flat config structure | |

**User's choice:** [auto] Per-field overlay (recommended default)
**Notes:** Satisfies CFG-04 requirement. User sets one field, everything else keeps defaults.

---

## Auto-Discovery Precedence

| Option | Description | Selected |
|--------|-------------|----------|
| Local > user > flag | Most-specific wins: --config > ./netsynth.toml > ~/.config/ | ✓ |
| Flag only | Simpler but no auto-discovery (violates CFG-02) | |
| Multi-file merge | Load and merge all found configs | |

**User's choice:** [auto] Local > user-level > flag (recommended default)
**Notes:** Standard CLI convention. Only one file loaded — no multi-file merge complexity.

---

## Error Reporting

| Option | Description | Selected |
|--------|-------------|----------|
| Fail-fast with key name + suggestion | Exit at startup, name the bad key (CFG-05) | ✓ |
| Warning and continue | Tolerant but hides mistakes | |
| Strict with no suggestions | Simpler but less helpful | |

**User's choice:** [auto] Fail-fast with key name and optional typo suggestion (recommended default)
**Notes:** Matches CFG-05 requirement. Unknown class names are warnings (not errors) to prepare for Phase 7.

---

## Claude's Discretion

- TOML library choice
- Package organization (dedicated `config` package vs inline)
- Waveform string mapping implementation
- Edit distance for typo suggestions

## Deferred Ideas

- `--print-config` (CFG-06) — Phase 7
- Custom rules `[[rules]]` — Phase 7