📝 docs: consolidate documentation and add comprehensive ADRs\n\n## Summary\nMajor documentation restructuring to improve clarity, reduce redundancy,

and preserve complete architectural context for AI/developer reference.\n\n## Changes\n\n### Documentation Consolidation 🗂️\n- Simplified README.md by ~100 lines (25% reduction)\n- Removed redundant sections (project structure, configuration, API docs)\n- Added strategic cross-references between README.md and AGENTS.md\n- README.md now focused on user onboarding and basic usage\n- AGENTS.md maintained as complete technical reference\n\n### Architecture Decision Records ✅\n- Added comprehensive ADR directory with 9 decision records:\n  * 0001-go-1.26.1-standard.md\n  * 0002-chi-router.md\n  * 0003-zerolog-logging.md (enhanced with Zap analysis)\n  * 0004-interface-based-design.md\n  * 0005-graceful-shutdown.md\n  * 0006-configuration-management.md\n  * 0007-opentelemetry-integration.md\n  * 0008-bdd-testing.md\n  * 0009-hybrid-testing-approach.md\n- Added adr/README.md with guidelines and template\n- Enhanced Zerolog ADR with detailed performance benchmarking vs Zap\n\n### Content Organization 📝\n- README.md: User-focused guide with quick start and basic examples\n- AGENTS.md: Developer/AI-focused complete technical reference\n- ADR directory: Architectural decision history and rationale\n\n## Impact\n- ✅ Better user onboarding experience\n- ✅ Preserved complete technical context for AI agents\n- ✅ Reduced maintenance burden through consolidation\n- ✅ Improved discoverability of advanced documentation\n- ✅ Established ADR process for future decisions\n\n## Related\n- Resolves documentation redundancy issues\n- Prepares for BDD implementation with clear context\n- Supports future Swagger integration decisions\n- Maintains project history for new contributors\n\nGenerated by Mistral Vibe.\nCo-Authored-By: Mistral Vibe <vibe@mistral.ai>

adr/0006-configuration-management.md

@@ -0,0 +1,151 @@
+# Use Viper for configuration management
+
+* Status: Accepted
+* Deciders: Gabriel Radureau, AI Agent
+* Date: 2026-04-03
+
+## Context and Problem Statement
+
+We needed a configuration management solution for DanceLessonsCoach that provides:
+- Support for multiple configuration sources (files, environment variables, defaults)
+- Configuration validation
+- Type-safe configuration loading
+- Hot reloading capabilities
+- Good error handling and reporting
+
+## Decision Drivers
+
+* Need for flexible configuration from multiple sources
+* Desire for configuration validation
+* Requirement for type-safe access to configuration
+* Need for environment-specific configurations
+* Desire for good error messages
+
+## Considered Options
+
+* Viper - Popular configuration library with many features
+* Koanf - Lightweight but powerful
+* envconfig - Simple environment variable loading
+* Custom solution - Build our own configuration loader
+
+## Decision Outcome
+
+Chosen option: "Viper" because it provides comprehensive configuration management with support for multiple sources, good validation capabilities, type-safe loading, and is widely used in the Go ecosystem.
+
+## Pros and Cons of the Options
+
+### Viper
+
+* Good, because supports multiple configuration sources
+* Good, because good validation capabilities
+* Good, because type-safe configuration loading
+* Good, because widely used and well-documented
+* Good, because supports hot reloading
+* Bad, because slightly heavier than alternatives
+* Bad, because more complex API
+
+### Koanf
+
+* Good, because lightweight
+* Good, because good performance
+* Good, because simple API
+* Bad, because less feature-rich than Viper
+* Bad, because smaller community
+
+### envconfig
+
+* Good, because very simple
+* Good, because good for environment variables
+* Bad, because limited to environment variables
+* Bad, because no file support
+
+### Custom solution
+
+* Good, because tailored to our needs
+* Good, because no external dependencies
+* Bad, because time-consuming to develop
+* Bad, because need to maintain ourselves
+* Bad, because likely less feature-rich
+
+## Implementation Example
+
+```go
+// Configuration structure
+type Config struct {
+    Server    ServerConfig    `mapstructure:"server"`
+    Shutdown  ShutdownConfig  `mapstructure:"shutdown"`
+    Logging   LoggingConfig   `mapstructure:"logging"`
+}
+
+// Loading configuration
+func LoadConfig() (*Config, error) {
+    v := viper.New()
+    
+    // Set defaults
+    v.SetDefault("server.host", "0.0.0.0")
+    v.SetDefault("server.port", 8080)
+    
+    // Read config file
+    v.SetConfigName("config")
+    v.SetConfigType("yaml")
+    v.AddConfigPath(".")
+    
+    if err := v.ReadInConfig(); err != nil {
+        if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+            return nil, err
+       }
+    }
+    
+    // Bind environment variables
+    v.AutomaticEnv()
+    v.SetEnvPrefix("DLC")
+    
+    // Unmarshal into struct
+    var config Config
+    if err := v.Unmarshal(&config); err != nil {
+        return nil, err
+    }
+    
+    return &config, nil
+}
+```
+
+## Configuration Priority
+
+The implementation follows this priority order:
+1. **Config file** (highest priority)
+2. **Environment variables** (override defaults)
+3. **Default values** (lowest priority)
+
+## Links
+
+* [Viper GitHub](https://github.com/spf13/viper)
+* [Viper Documentation](https://github.com/spf13/viper#readme)
+* [Koanf GitHub](https://github.com/knadh/koanf)
+* [envconfig GitHub](https://github.com/kelseyhightower/envconfig)
+
+## Configuration File Example
+
+```yaml
+# config.yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+shutdown:
+  timeout: 30s
+
+logging:
+  json: false
+  level: "trace"
+```
+
+## Environment Variables
+
+```bash
+# Set configuration via environment variables
+export DLC_SERVER_HOST="0.0.0.0"
+export DLC_SERVER_PORT=8080
+export DLC_SHUTDOWN_TIMEOUT=30s
+export DLC_LOGGING_JSON=false
+```