Summary

Document the configuration subsystem in common_system including hot-reload file watching, unified configuration management, and CLI argument parsing.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (#325)

Background (Why)

common_system provides a rich configuration subsystem at include/kcenon/common/config/ with 10 header files, but only config_loader.h is partially referenced in existing docs. Key features like hot-reload via file watching, unified multi-source configuration, and CLI parsing are undocumented.

Source files:

• include/kcenon/common/config/config_watcher.h — File system monitoring for config hot-reload
• include/kcenon/common/config/unified_config.h — Unified configuration from multiple sources (7 sub-structs)
• include/kcenon/common/config/cli_config_parser.h — Command-line argument parser
• include/kcenon/common/config/config_loader.h — Configuration file loading

Scope (What)

Create docs/CONFIG_GUIDE.md covering:

1. Configuration Architecture

• Configuration source hierarchy (CLI > env > file > defaults)
• How unified_config merges multiple sources
• Hot-reload mechanism via config_watcher

2. Unified Config (unified_config.h)

• All 7 sub-structs and their fields
• Default values for each setting
• Configuration file format (JSON/YAML/TOML)
• Programmatic configuration

3. Config Watcher (config_watcher.h)

• File system event monitoring
• Debouncing and rate limiting
• Callback registration for config changes
• Watched path management
• Thread safety of hot-reload

4. CLI Config Parser (cli_config_parser.h)

• Argument format (--key=value, -k value)
• Boolean flags, list arguments
• Help text generation
• Required vs optional arguments
• Subcommand support (if any)

5. Config Loader (config_loader.h)

• File format support
• Error handling for malformed configs
• Schema validation

6. Usage Example

auto config = unified_config::create()
    .from_file("config.json")
    .from_cli(argc, argv)
    .from_env("APP_")
    .with_watcher(config_watcher{
        .paths = {"config.json"},
        .on_change = [](auto& new_config) { /* hot-reload */ }
    })
    .build();

Acceptance Criteria

• Configuration architecture documented with priority diagram
• unified_config sub-structs fully documented
• config_watcher hot-reload mechanism explained
• cli_config_parser argument parsing documented
• Complete usage example with all sources
• Hot-reload callback patterns documented