📝 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/0002-chi-router.md

@@ -0,0 +1,72 @@
+# Use Chi router for HTTP routing
+
+* Status: Accepted
+* Deciders: Gabriel Radureau, AI Agent
+* Date: 2026-04-02
+
+## Context and Problem Statement
+
+We needed to choose an HTTP router for the DanceLessonsCoach web service that provides:
+- Good performance characteristics
+- Flexible routing capabilities
+- Middleware support
+- Active maintenance and community support
+- Compatibility with our interface-based design
+
+## Decision Drivers
+
+* Need for performant HTTP routing
+* Desire for clean, idiomatic Go API
+* Requirement for middleware support
+* Long-term maintainability
+* Good documentation and examples
+
+## Considered Options
+
+* Chi router - Lightweight, fast router with good middleware support
+* Gorilla Mux - Well-established but heavier
+* Gin - High performance but more opinionated
+* Standard library - Simple but limited features
+
+## Decision Outcome
+
+Chosen option: "Chi router" because it provides excellent performance, clean API, good middleware support, and active maintenance while remaining lightweight and unopinionated.
+
+## Pros and Cons of the Options
+
+### Chi router
+
+* Good, because lightweight and fast
+* Good, because excellent middleware support
+* Good, because clean, idiomatic Go API
+* Good, because actively maintained
+* Good, because good documentation and examples
+* Bad, because slightly less feature-rich than some alternatives
+
+### Gorilla Mux
+
+* Good, because very mature and stable
+* Good, because feature-rich
+* Bad, because heavier and more complex
+* Bad, because less performant than Chi
+
+### Gin
+
+* Good, because extremely high performance
+* Good, because good ecosystem
+* Bad, because more opinionated framework
+* Bad, because different from standard library patterns
+
+### Standard library
+
+* Good, because no external dependencies
+* Good, because simple and familiar
+* Bad, because limited routing capabilities
+* Bad, because no built-in middleware support
+
+## Links
+
+* [Chi Router GitHub](https://github.com/go-chi/chi)
+* [Chi Documentation](https://go-chi.io/#/)
+* [Gorilla Mux](https://github.com/gorilla/mux)
+* [Gin Web Framework](https://github.com/gin-gonic/gin)