diff --git a/.planning/phases/06-config-package-and-sound-overrides/06-RESEARCH.md b/.planning/phases/06-config-package-and-sound-overrides/06-RESEARCH.md
new file mode 100644
index 0000000..c37ccbd
--- /dev/null
+++ b/.planning/phases/06-config-package-and-sound-overrides/06-RESEARCH.md
@@ -0,0 +1,590 @@
+# Phase 6: Config Package and Sound Overrides - Research
+
+**Researched:** 2026-03-26
+**Domain:** Go TOML config loading, partial merge semantics, CLI flag wiring
+**Confidence:** HIGH
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+- **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.
+- **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`.
+- **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.
+- **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.
+- **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)
+
+### Deferred Ideas (OUT OF SCOPE)
+
+- `--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
+
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| CFG-01 | User can create a TOML config file that overrides default sound mappings | `[sounds.<classname>]` table pattern decodes into `map[string]SoundOverride`; per-field merge into `synth.ClassFreqConfigs` clone |
+| CFG-02 | Tool auto-discovers config from `./netsynth.toml` or `~/.config/netsynth/config.toml` (silent if absent) | `os.Stat` probe + `os.UserConfigDir()` for XDG path; `errors.Is(err, fs.ErrNotExist)` for silent miss |
+| CFG-03 | User can specify an explicit config path via `--config` flag (error if file missing) | Cobra `StringVar` flag; fail-fast `os.Stat` check returns error before capture begins |
+| CFG-04 | User can override individual values without replicating the entire default config (partial override) | Pointer fields (`*float64`, `*string`) in the TOML decode struct allow distinguishing "explicitly zero" from "not set"; overlay merge copies only non-nil fields |
+| CFG-05 | Unknown keys in config file produce a clear error with the typo'd key name | BurntSushi/toml `MetaData.Undecoded()` returns unmatched keys after decode; format as error message |
+
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 6 adds a `config` package responsible for loading a TOML config file, validating it, and merging it over the `synth.ClassFreqConfigs` default map. The merge output is a `map[classify.TrafficClass]synth.FreqConfig` that is handed to `synth.NewBank()` — the injection seam already exists from Phase 5.
+
+The core technical challenge is **partial override semantics**: a user who sets only `frequency` for ICMP must not accidentally clear its waveform. This requires the decode struct to use pointer fields (`*float64`, `*string`) so that absent keys remain `nil` at decode time. The merge loop then only copies non-nil values over the defaults.
+
+Unknown-key detection uses BurntSushi/toml v1.6.0's `MetaData.Undecoded()` method, which is reliable because it operates on the actual set of keys the parser traversed. The alternative (pelletier/go-toml v2.3.0's `DisallowUnknownFields`) is also viable but adds a dependency with a different API surface and returns human-formatted error strings rather than structured key lists — less useful for the "suggest closest valid key" nice-to-have.
+
+**Primary recommendation:** Use `github.com/BurntSushi/toml` v1.6.0. Use a dedicated `config` package. Implement partial merge with pointer fields in the TOML decode struct.
+
+## Standard Stack
+
+### Core
+
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| `github.com/BurntSushi/toml` | v1.6.0 | TOML parsing and MetaData for unknown-key detection | Simpler API than pelletier v2; `Undecoded()` returns structured `[]Key` (not formatted error strings); `DecodeFile()` is a one-liner; v1.6.0 published December 2025 |
+
+### Supporting
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| `os` (stdlib) | Go 1.24 | File existence checks, `UserConfigDir()` for XDG path | Always — no external dependency needed for discovery logic |
+| `errors`/`fs` (stdlib) | Go 1.24 | `errors.Is(err, fs.ErrNotExist)` for silent-miss on auto-discovery | Always |
+
+### Alternatives Considered
+
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| `BurntSushi/toml v1.6.0` | `pelletier/go-toml v2.3.0` | go-toml has `DisallowUnknownFields()` built-in (cleaner API) but returns `StrictMissingError` with a formatted string — harder to extract just the key name for a "did you mean?" suggestion. BurntSushi returns `[]toml.Key` which is structured. For this use case, BurntSushi is easier to work with. |
+| Pointer fields for partial override | Separate "is-set" booleans | Pointer fields are idiomatic in Go for "optional" semantics. Booleans add field count and are error-prone. |
+| Dedicated `config` package | Inline in `cmd/netsynth` | A `config` package makes the loader independently testable without a Cobra dependency. Given the complexity (validation, merge, discovery), a separate package is justified. |
+
+**Installation:**
+```bash
+go get github.com/BurntSushi/toml@v1.6.0
+```
+
+**Version verification (confirmed 2026-03-26):**
+```
+github.com/BurntSushi/toml v1.6.0   (December 18, 2025)
+github.com/pelletier/go-toml/v2 v2.3.0   (March 24, 2026 — alternative)
+```
+
+## Architecture Patterns
+
+### Recommended Project Structure
+
+```
+config/
+├── config.go        # Load(), Merge(), Validate() — public API
+└── config_test.go   # table-driven tests for all CFG requirements
+```
+
+The `config` package has one exported function signature the planner cares about:
+
+```go
+// Load finds, parses, validates, and merges a config file.
+// configPath is the --config flag value; empty string triggers auto-discovery.
+// Returns the merged FreqConfig map (defaults + overrides) ready for synth.NewBank.
+// Returns an error on: file-not-found when --config is explicit, parse errors,
+// unknown keys, type mismatches. Returns no error (uses defaults) when no config
+// is found during auto-discovery.
+func Load(configPath string) (map[classify.TrafficClass]synth.FreqConfig, error)
+```
+
+### Pattern 1: TOML Decode Struct with Pointer Fields
+
+**What:** The TOML config file maps to a Go struct where every overridable field is a pointer. `nil` means "not set by user"; non-nil means "user explicitly specified this value."
+
+**When to use:** Whenever you need to distinguish "field absent from config" from "field set to zero value" — mandatory for partial override semantics (CFG-04).
+
+```go
+// Source: BurntSushi/toml documentation + partial-override pattern
+// config/config.go
+
+// SoundOverride holds optional per-class sound parameters from TOML.
+// Pointer fields: nil = not set (keep default), non-nil = user override.
+type SoundOverride struct {
+    Frequency *float64 `toml:"frequency"`
+    Waveform  *string  `toml:"waveform"`
+}
+
+// rawConfig is the top-level TOML decode target.
+type rawConfig struct {
+    Sounds map[string]SoundOverride `toml:"sounds"`
+}
+```
+
+### Pattern 2: Unknown-Key Detection with MetaData.Undecoded()
+
+**What:** After decoding, check `md.Undecoded()` for any keys in the TOML file that did not map to a field in the decode struct. Return an error naming the first unrecognized key.
+
+**When to use:** Required for CFG-05. Also the mechanism to detect field-level typos within a `[sounds.ICMP]` block (e.g., `frequncy` vs `frequency`).
+
+```go
+// Source: pkg.go.dev/github.com/BurntSushi/toml
+// config/config.go
+
+func parse(path string) (rawConfig, error) {
+    var raw rawConfig
+    md, err := toml.DecodeFile(path, &raw)
+    if err != nil {
+        return raw, fmt.Errorf("config parse error: %w", err)
+    }
+    if undecoded := md.Undecoded(); len(undecoded) > 0 {
+        // undecoded[0] is a toml.Key ([]string); join for human-readable path
+        keyPath := strings.Join(undecoded[0], ".")
+        return raw, fmt.Errorf("config: unknown key %q — check spelling", keyPath)
+    }
+    return raw, nil
+}
+```
+
+**IMPORTANT NOTE on nested map + Undecoded():** When the decode struct uses `map[string]SoundOverride` for `[sounds]`, the TOML library cannot know what map keys are "valid" — all string keys are valid map keys. This means `Undecoded()` will NOT catch a misspelled class name like `[sounds.ICMP_typo]` (it IS decoded, just into a wrong map key). However, `Undecoded()` WILL catch field-level typos within a class block like `[sounds.ICMP]` with `frequncy = 440` because `frequncy` doesn't match any `SoundOverride` field. Class-name validation is handled separately in the merge step (D-09: log a warning for unknown class names).
+
+### Pattern 3: Per-Field Overlay Merge
+
+**What:** Iterate over the default `ClassFreqConfigs` map, copy it, then for each entry found in the TOML overrides, copy only the non-nil pointer fields into the working copy.
+
+**When to use:** This is the CFG-04 implementation. Must run after parse and validation.
+
+```go
+// config/config.go
+
+func merge(
+    defaults map[classify.TrafficClass]synth.FreqConfig,
+    overrides map[string]SoundOverride,
+) map[classify.TrafficClass]synth.FreqConfig {
+    // Deep-copy defaults
+    result := make(map[classify.TrafficClass]synth.FreqConfig, len(defaults))
+    for k, v := range defaults {
+        result[k] = v
+    }
+
+    for className, override := range overrides {
+        class := classify.TrafficClass(className)
+        cfg, known := result[class]
+        if !known {
+            // D-09: unknown class name = warning, not error (Phase 7 may define it)
+            fmt.Fprintf(os.Stderr, "Warning: config: unknown class %q (ignored)\n", className)
+            continue
+        }
+        if override.Frequency != nil {
+            cfg.BaseHz = *override.Frequency
+            // When frequency changes, regenerate harmonics if a waveform preset is active
+            if cfg.WaveformType != synth.WaveformCustom {
+                cfg.Harmonics = synth.WaveformPresetHarmonics(cfg.WaveformType, cfg.BaseHz, synth.SampleRate)
+            }
+        }
+        if override.Waveform != nil {
+            wt, err := parseWaveform(*override.Waveform)
+            if err != nil {
+                // Validation catches this before merge; this is a safety guard
+                continue
+            }
+            cfg.WaveformType = wt
+            cfg.Harmonics = synth.WaveformPresetHarmonics(wt, cfg.BaseHz, synth.SampleRate)
+        }
+        result[class] = cfg
+    }
+    return result
+}
+```
+
+### Pattern 4: Waveform String-to-Type Mapping
+
+**What:** A simple switch converts the TOML `waveform` string to `synth.WaveformType`. Validation happens before merge.
+
+```go
+// config/config.go
+
+var validWaveforms = map[string]synth.WaveformType{
+    "sine":     synth.WaveformSine,
+    "square":   synth.WaveformSquare,
+    "sawtooth": synth.WaveformSawtooth,
+    "triangle": synth.WaveformTriangle,
+}
+
+func parseWaveform(s string) (synth.WaveformType, error) {
+    if wt, ok := validWaveforms[s]; ok {
+        return wt, nil
+    }
+    valid := []string{"sine", "square", "sawtooth", "triangle"}
+    return 0, fmt.Errorf("config: invalid waveform %q — valid values: %s", s, strings.Join(valid, ", "))
+}
+```
+
+### Pattern 5: Auto-Discovery with os.UserConfigDir
+
+**What:** Check paths in precedence order. Return the path of the first file found, or `""` (empty) if none found. Never log anything for a missing auto-discovered file.
+
+```go
+// config/config.go
+
+func discoverPath() string {
+    // 1. Working directory
+    if _, err := os.Stat("netsynth.toml"); err == nil {
+        return "netsynth.toml"
+    }
+    // 2. XDG config dir
+    dir, err := os.UserConfigDir()
+    if err != nil {
+        return ""
+    }
+    p := filepath.Join(dir, "netsynth", "config.toml")
+    if _, err := os.Stat(p); err == nil {
+        return p
+    }
+    return ""
+}
+```
+
+`os.UserConfigDir()` returns `$XDG_CONFIG_HOME` or `$HOME/.config` on Linux (Go stdlib, no extra dependency). Confirmed by Go source: returns `$XDG_CONFIG_HOME` if set, else `$HOME/.config` on Unix.
+
+### Pattern 6: encode.RunSynthesis Signature Change
+
+**What:** `RunSynthesis` currently calls `synth.NewBank(1.0, synth.ClassFreqConfigs)` hardcoded. Phase 6 changes the signature to accept the merged config map.
+
+The simplest approach: pass the merged config map as a parameter (rather than loading config inside `encode`). This keeps `encode` unaware of config loading and makes testing easier.
+
+```go
+// encode/mp3.go — updated signature
+func RunSynthesis(
+    snapshots []classify.WindowSnapshot,
+    outputPath string,
+    freqCfgs map[classify.TrafficClass]synth.FreqConfig,
+) error {
+    // ...
+    bank := synth.NewBank(1.0, freqCfgs) // was: synth.ClassFreqConfigs
+    // ...
+}
+```
+
+Caller in `cmd/netsynth/main.go` passes the result of `config.Load(configPath)`.
+
+### Anti-Patterns to Avoid
+
+- **Decode into `map[string]interface{}`:** Loses type safety, makes unknown-field detection harder, requires runtime type assertions. Use typed structs.
+- **Load config inside `encode` package:** Couples audio encoding to config I/O; breaks test isolation. Config loading belongs in `cmd/netsynth/main.go` (calls `config.Load`) or a dedicated `config` package.
+- **Validate waveform strings after merge:** Validate before merging so the error is caught at startup (D-11), not silently ignored.
+- **Deep-copy using `=` assignment on map values:** `synth.FreqConfig` contains a `[]HarmonicDef` slice; a simple struct copy shares the underlying array. Use an explicit copy of the slice if you mutate `Harmonics` during merge. (The merge code above reconstructs harmonics from the preset, so this is safe — but important to be aware of.)
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| TOML parsing | Custom parser | `BurntSushi/toml` v1.6.0 | TOML 1.1 compliance, error messages, datetime support, tested at scale |
+| Unknown-key detection | Post-parse key comparison | `md.Undecoded()` from BurntSushi | Already built into the library; handles nested paths correctly |
+| XDG config path | Manual `$HOME/.config` string concat | `os.UserConfigDir()` stdlib | Handles `$XDG_CONFIG_HOME` override correctly, platform-portable |
+
+**Key insight:** The partial-override merge logic is the one piece that must be written from scratch — no library does "overlay a sparse map of optional overrides over a typed defaults map." But it is ~20 lines of straightforward Go.
+
+## Runtime State Inventory
+
+Step 2.5 SKIPPED — this is a new feature addition, not a rename/refactor/migration phase. No runtime state is being renamed or migrated.
+
+## Common Pitfalls
+
+### Pitfall 1: Undecoded() Does Not Catch Unknown Class Names
+
+**What goes wrong:** Developer assumes `md.Undecoded()` will catch `[sounds.ICMP_TYPO]` as an unknown key and provide CFG-05 coverage for class-name typos.
+
+**Why it happens:** `map[string]SoundOverride` decodes any string as a valid map key — the TOML parser has no way to know which class names are valid. `Undecoded()` only catches keys that don't match ANY field (struct field name, map key, or slice element). Since all map keys are valid, no class name is "undecodeable."
+
+**How to avoid:** Separate the two concerns. Field-level unknown keys (e.g., `frequncy`) ARE caught by `Undecoded()`. Class-name typos are caught in the merge step by checking whether `classify.TrafficClass(className)` exists in `synth.ClassFreqConfigs`. The CONTEXT.md decision D-09 says unknown class names produce a warning (not error) to allow for Phase 7 user-defined classes — so this is by design.
+
+**Warning signs:** Test for both: write a test with `[sounds.ICMP]` containing `frequncy = 440` (should error) AND a test with `[sounds.ICMP_TYPO]` containing `frequency = 440` (should warn, not error).
+
+### Pitfall 2: Partial Override Accidentally Clears WaveformType
+
+**What goes wrong:** User sets only `frequency = 300` for ICMP. After merge, ICMP's `WaveformType` is reset to `WaveformCustom` because the merge loop creates a new `FreqConfig{}` instead of starting from the default.
+
+**Why it happens:** Copy-by-value from defaults is skipped, or merge starts from a zero-value struct.
+
+**How to avoid:** Always start the merge from the DEFAULT `FreqConfig` for that class. The merge loop copies `defaults[class]` first, then overlays only non-nil pointer fields.
+
+**Warning signs:** Test case: set only `frequency` for a class with `WaveformCustom` — verify waveform field is unchanged. Test case: set only `waveform` for a class — verify frequency is unchanged.
+
+### Pitfall 3: Frequency Change Does Not Regenerate Harmonics for Preset Waveforms
+
+**What goes wrong:** User sets `frequency = 300` for HTTPS (which has `WaveformCustom` by default, so this is fine). But if a user sets `frequency = 300` for a class that was previously configured with `WaveformSine` (via an earlier config entry), the harmonics may be stale from the old frequency.
+
+**Why it happens:** `synth.WaveformPresetHarmonics` generates harmonics based on `baseHz`. If you update `BaseHz` without regenerating harmonics, the preset harmonics are anchored to the old frequency.
+
+**How to avoid:** In the merge function: when updating `Frequency`, check if `WaveformType != WaveformCustom`. If true, regenerate `Harmonics` from the new frequency. The merge example above handles this correctly.
+
+**Warning signs:** For the 14 built-in classes, all have `WaveformCustom` (hand-tuned harmonics), so this pitfall only bites if the user sets both `waveform` and `frequency` in two separate steps — or if a future phase pre-configures preset waveforms on built-ins.
+
+### Pitfall 4: --config File-Not-Found vs Auto-Discovery Silence
+
+**What goes wrong:** When `--config /path/to/missing.toml` is specified, the code returns the same "no config found, using defaults" behavior as auto-discovery silence.
+
+**Why it happens:** `os.Stat` errors are treated uniformly regardless of how the path was obtained.
+
+**How to avoid:** In the `Load` function, branch on whether `configPath` was explicitly provided: if it was, a `fs.ErrNotExist` is a user error (return error); if it came from auto-discovery, `fs.ErrNotExist` is normal (return `nil` error, use defaults).
+
+**Warning signs:** CFG-03 acceptance criterion explicitly tests this: explicit path must error, absent auto-discovery must be silent.
+
+### Pitfall 5: go.mod Tidy Drops TOML Dependency
+
+**What goes wrong:** `go mod tidy` is run after adding BurntSushi/toml to go.mod but before any `.go` file in the module actually imports it. Tidy removes it.
+
+**Why it happens:** `go mod tidy` removes unused dependencies.
+
+**How to avoid:** Add the import in `config/config.go` before running `go mod tidy`.
+
+## Code Examples
+
+### Complete config.go Skeleton
+
+```go
+// Source: BurntSushi/toml docs + project pattern
+// config/config.go
+package config
+
+import (
+    "errors"
+    "fmt"
+    "io/fs"
+    "os"
+    "path/filepath"
+    "strings"
+
+    "github.com/BurntSushi/toml"
+
+    "github.com/netsynth/netsynth/classify"
+    "github.com/netsynth/netsynth/synth"
+)
+
+type SoundOverride struct {
+    Frequency *float64 `toml:"frequency"`
+    Waveform  *string  `toml:"waveform"`
+}
+
+type rawConfig struct {
+    Sounds map[string]SoundOverride `toml:"sounds"`
+}
+
+// Load is the single public entry point.
+// configPath: value of --config flag; empty = auto-discover.
+func Load(configPath string) (map[classify.TrafficClass]synth.FreqConfig, error) {
+    path, explicit, err := resolvePath(configPath)
+    if err != nil {
+        return nil, err
+    }
+    if path == "" {
+        // No config found during auto-discovery — use defaults silently (CFG-02)
+        return copyDefaults(), nil
+    }
+
+    raw, err := parseFile(path)
+    if err != nil {
+        if explicit && errors.Is(err, fs.ErrNotExist) {
+            return nil, fmt.Errorf("config file not found: %s", path)
+        }
+        return nil, err
+    }
+
+    if err := validate(raw); err != nil {
+        return nil, err
+    }
+
+    return merge(copyDefaults(), raw.Sounds), nil
+}
+```
+
+### Example TOML Config File
+
+```toml
+# netsynth.toml — override ICMP and SSH sounds
+[sounds.ICMP]
+frequency = 80.0
+waveform = "square"
+
+[sounds.SSH]
+frequency = 400.0
+# waveform not set — SSH keeps its default waveform
+```
+
+### Test Pattern (table-driven)
+
+```go
+// config/config_test.go
+
+func TestLoadPartialOverride(t *testing.T) {
+    // Write a temp TOML file with only frequency for ICMP
+    tomlContent := `
+[sounds.ICMP]
+frequency = 100.0
+`
+    f, _ := os.CreateTemp(t.TempDir(), "*.toml")
+    f.WriteString(tomlContent)
+    f.Close()
+
+    cfgs, err := Load(f.Name())
+    if err != nil {
+        t.Fatalf("Load: %v", err)
+    }
+
+    // ICMP frequency overridden
+    if cfgs[classify.ClassICMP].BaseHz != 100.0 {
+        t.Errorf("ICMP BaseHz: got %v, want 100.0", cfgs[classify.ClassICMP].BaseHz)
+    }
+    // ICMP waveform unchanged (WaveformCustom = 0)
+    if cfgs[classify.ClassICMP].WaveformType != synth.WaveformCustom {
+        t.Errorf("ICMP WaveformType: got %v, want WaveformCustom", cfgs[classify.ClassICMP].WaveformType)
+    }
+    // DNS frequency unchanged
+    if cfgs[classify.ClassDNS].BaseHz != synth.ClassFreqConfigs[classify.ClassDNS].BaseHz {
+        t.Errorf("DNS BaseHz unexpectedly changed")
+    }
+}
+
+func TestLoadUnknownKey(t *testing.T) {
+    tomlContent := `
+[sounds.ICMP]
+frequncy = 440
+`
+    f, _ := os.CreateTemp(t.TempDir(), "*.toml")
+    f.WriteString(tomlContent)
+    f.Close()
+
+    _, err := Load(f.Name())
+    if err == nil {
+        t.Fatal("expected error for unknown key 'frequncy', got nil")
+    }
+    if !strings.Contains(err.Error(), "frequncy") {
+        t.Errorf("error should name the bad key, got: %v", err)
+    }
+}
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| `google/gopacket` | `gopacket/gopacket` v1.5.0 | 2022-2024 | N/A for this phase |
+| BurntSushi/toml v0.x | v1.6.0 (TOML 1.1 enabled by default) | December 2025 | TOML 1.1 compliance; API unchanged, same `Decode`/`DecodeFile` functions |
+| `go-audio/generator` | ARCHIVED (Feb 2026, read-only) | February 2026 | Do not use; project already avoids it |
+
+**Current versions confirmed 2026-03-26:**
+- `BurntSushi/toml` v1.6.0 (December 18, 2025) — TOML 1.1 default, stable API
+- `pelletier/go-toml/v2` v2.3.0 (March 24, 2026) — alternative if structured error needed
+
+## Open Questions
+
+1. **Typo suggestion for unknown keys (D-07 nice-to-have)**
+   - What we know: BurntSushi returns `[]toml.Key` (structured), Levenshtein distance is ~15 lines of Go or `github.com/agnivade/levenshtein` (tiny, zero-dependency)
+   - What's unclear: Is the complexity worth it for 2 valid field names per class block (`frequency`, `waveform`)?
+   - Recommendation: Skip the external library. Implement inline: for each undecoded key, if it has edit distance ≤ 2 from any valid key name, append " (did you mean: X?)" to the error. The valid key set for field names is small and static: `["frequency", "waveform"]`. This is ~10 lines of Go.
+
+2. **copyDefaults() — shallow vs deep copy of Harmonics slices**
+   - What we know: `synth.FreqConfig.Harmonics` is a `[]HarmonicDef`. Go's `map[K]V` assignment copies struct values (including slice headers) but the underlying array is shared.
+   - What's unclear: Does this matter if merge only replaces the whole slice (via `WaveformPresetHarmonics`) rather than appending to it?
+   - Recommendation: Since the merge code assigns a freshly-generated `[]HarmonicDef` from `WaveformPresetHarmonics` (never mutates the original), shallow copy is safe. No deep copy needed. Document this in a comment for future maintainers.
+
+## Environment Availability
+
+Step 2.6: This phase introduces one new external dependency:
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| `github.com/BurntSushi/toml` | config.Load() TOML parsing | ✓ (fetched via go get) | v1.6.0 | pelletier/go-toml v2.3.0 |
+| `os.UserConfigDir()` | Auto-discovery of `~/.config/netsynth/config.toml` | ✓ (Go stdlib) | Go 1.13+ | N/A — stdlib |
+| Go 1.24.1 toolchain | Module minimum | ✓ | 1.24.1 | N/A |
+| C compiler (CGo) | go-lame MP3 encoding (pre-existing) | Assumed ✓ (Phase 2+ already requires this) | — | N/A |
+
+No missing dependencies with no fallback. BurntSushi/toml confirmed fetchable from pkg.go.dev.
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| Framework | Go standard `testing` package |
+| Config file | None — `go test ./...` |
+| Quick run command | `go test ./config/...` |
+| Full suite command | `go test ./...` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| CFG-01 | TOML overrides applied to correct class | unit | `go test ./config/... -run TestLoadOverride` | Wave 0 |
+| CFG-02 | No config file → silent, uses defaults | unit | `go test ./config/... -run TestLoadNoConfig` | Wave 0 |
+| CFG-03 | `--config` explicit path → error if missing | unit | `go test ./config/... -run TestLoadExplicitMissing` | Wave 0 |
+| CFG-04 | Partial override: unset fields unchanged | unit | `go test ./config/... -run TestLoadPartialOverride` | Wave 0 |
+| CFG-05 | Unknown key → error naming the key | unit | `go test ./config/... -run TestLoadUnknownKey` | Wave 0 |
+| CFG-03 | `--config` flag wired in Cobra | integration | `go test ./cmd/netsynth/... -run TestConfigFlag` | Wave 0 |
+
+### Sampling Rate
+
+- **Per task commit:** `go test ./config/... -count=1`
+- **Per wave merge:** `go test ./... -count=1`
+- **Phase gate:** Full suite green before `/gsd:verify-work`
+
+### Wave 0 Gaps
+
+- [ ] `config/config.go` — package does not exist yet; create in Wave 1
+- [ ] `config/config_test.go` — covers CFG-01 through CFG-05
+- [ ] `cmd/netsynth/main_test.go` — add `TestConfigFlag` covering CFG-03 CLI integration
+
+*(Existing test infrastructure covers all other packages; only `config/` is new.)*
+
+## Sources
+
+### Primary (HIGH confidence)
+
+- `pkg.go.dev/github.com/BurntSushi/toml` — v1.6.0 API: `DecodeFile`, `MetaData.Undecoded()`, `[]Key` type; verified 2026-03-26
+- Go stdlib `os.UserConfigDir()` — returns `$XDG_CONFIG_HOME` or `$HOME/.config` on Linux; Go 1.13+ feature
+- `pkg.go.dev/github.com/pelletier/go-toml/v2` — v2.3.0 `DisallowUnknownFields()` / `StrictMissingError` API; verified 2026-03-26
+
+### Secondary (MEDIUM confidence)
+
+- WebSearch: BurntSushi/toml Undecoded() approach verified against official GitHub source (`toml/decode.go`)
+- WebSearch: pelletier/go-toml v2 DisallowUnknownFields verified against official docs
+- WebSearch: `os.UserConfigDir` XDG compliance — confirmed returns `$XDG_CONFIG_HOME` or `$HOME/.config` on Linux per golang/go issue #29960
+
+### Tertiary (LOW confidence)
+
+- WebSearch: edit distance typo suggestion libraries (agnivade/levenshtein, go-edlib) — not deeply evaluated; recommendation is inline 10-line implementation to avoid dependency
+
+## Metadata
+
+**Confidence breakdown:**
+
+- Standard stack: HIGH — versions confirmed via `go get` live fetch (v1.6.0 BurntSushi, v2.3.0 pelletier)
+- Architecture: HIGH — patterns derived from library documentation + existing codebase patterns
+- Pitfalls: HIGH — Undecoded() + map key limitation is a documented behavior; partial-override via pointer fields is an established Go idiom
+- TOML typo suggestion: LOW — nice-to-have from D-07; no deep investigation needed given small valid-key set
+
+**Research date:** 2026-03-26
+**Valid until:** 2026-06-26 (BurntSushi/toml is stable; go-toml v2 moves faster but is not the chosen library)