docs-config-readme-struct-drift

Answer

Root cause. The README "Configuration Reference" documented 11 YAML keys that have no matching yaml struct tag in internal/config/config.go. Because the decoder runs with yaml.v3 KnownFields(true), any such key turns into CONFIG_LOAD_ERROR at startup — reproduced before the fix: exit=1 with 11 field not found in type config.* errors, so copy-pasting the README sample crashed the server on first run.

Fix. The struct tags in internal/config/config.go are the single source of truth. I synced the README sample to them: - Removed the 11 phantom keys: server.keep_alive_timeout, server.max_header_bytes, database.ssl_mode, database.pool_size, redis.default_ttl, redis.pipeline_window, queue.retry_delay, queue.batch_size, logging.format, metrics.push_gateway, auth.jwt_issuer. - Added the missing llm section (provider, model, api_key, base_url, timeout, max_tokens, temperature, retries). - Kept the legit substring-collision key redis.runtime_default_ttl (which a bare default_ttl grep would false-positive on).

The strict loader (unchanged, already correct):

func Decode(r io.Reader) (*Config, error) {
    dec := yaml.NewDecoder(r)
    dec.KnownFields(true) // unknown key -> error -> CONFIG_LOAD_ERROR
    cfg := Defaults()
    if err := dec.Decode(cfg); err != nil {
        return nil, fmt.Errorf("%w: %v", ErrLoad, err)
    }
    return cfg, nil
}

I also added a regression test that enforces the single-source-of-truth rule mechanically — a reflection walker collects dotted paths from the struct tags, a YAML walker collects dotted paths from the README block, and they must match exactly (map-field children allowed):

for p := range structPaths {            // every struct tag path
    if !readme[p] {
        t.Errorf("struct tag path %q is missing from the README sample", p)
    }
}
for p := range readme {                 // every README path
    if structPaths[p] { continue }
    if !descendantOfMapField(p, mapFields) {
        t.Errorf("README sample declares phantom key %q ...", p)
    }
}