📝 docs: cherry-pick 6 focused guides from PR #17 (option c) (#87)

Co-authored-by: Gabriel Radureau <arcodange@gmail.com>
Co-committed-by: Gabriel Radureau <arcodange@gmail.com>

documentation/CLI.md

@@ -0,0 +1,251 @@
+# CLI Management Guide
+
+Complete reference for the `dance-lessons-coach` CLI, server lifecycle, and configuration. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.
+
+## Cobra CLI (Recommended)
+
+`dance-lessons-coach` includes a modern CLI built with Cobra:
+
+```bash
+# Show help and available commands
+./bin/dance-lessons-coach --help
+
+# Show version information
+./bin/dance-lessons-coach version
+
+# Greet someone by name
+./bin/dance-lessons-coach greet John
+
+# Start the server
+./bin/dance-lessons-coach server
+```
+
+**Available Commands:**
+
+- `version` — Print version information
+- `server` — Start the dance-lessons-coach server
+- `greet [name]` — Greet someone by name
+- `help` — Built-in help system
+- `completion` — Generate shell completion scripts
+
+**Server Command Flags:**
+
+- `--config` — Config file path
+- `--env` — Environment (`dev`, `staging`, `prod`)
+- `--debug` — Enable debug logging
+
+## Version Information
+
+The server provides runtime version information:
+
+```bash
+# Check version using new CLI
+./bin/dance-lessons-coach version
+
+# Check version using server binary
+./bin/server --version
+
+# Output:
+dance-lessons-coach Version Information:
+  Version:   1.0.0
+  Commit:    abc1234
+  Built:     2026-04-05T10:00:00+0000
+  Go:        go1.26.1
+```
+
+For full version management workflow (bump, release, build with version), see [`version-management-guide.md`](version-management-guide.md).
+
+## Server Control Script
+
+A shell script manages the server lifecycle:
+
+```bash
+cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
+
+./scripts/start-server.sh start     # Start the server
+./scripts/start-server.sh status    # Check server status
+./scripts/start-server.sh test      # Test API endpoints
+./scripts/start-server.sh logs      # View server logs
+./scripts/start-server.sh stop      # Stop the server
+./scripts/start-server.sh restart   # Restart
+```
+
+**Available subcommands:**
+
+- `start` — Start the server in background with proper logging
+- `stop` — Stop the server gracefully
+- `restart` — Restart the server
+- `status` — Check if server is running
+- `logs` — Show recent server logs
+- `test` — Test all API endpoints
+
+## Manual Server Management
+
+For direct control:
+
+```bash
+cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
+./scripts/start-server.sh start
+```
+
+**Expected output:**
+
+```
+Server running on :8080
+[INF] Starting HTTP server on :8080
+[TRC] Registering greet routes
+[TRC] Greet routes registered
+```
+
+**Features:**
+
+- Context-aware server initialization
+- Graceful shutdown handling
+- Signal-based termination (`SIGINT`, `SIGTERM`)
+- 30-second shutdown timeout
+- Proper resource cleanup
+
+## Configuration
+
+Configuration via environment variables with `DLC_` prefix:
+
+| Option | Environment Variable | Default | Description |
+|---|---|---|---|
+| Host | `DLC_SERVER_HOST` | `0.0.0.0` | Server bind address |
+| Port | `DLC_SERVER_PORT` | `8080` | Server listening port |
+| Shutdown Timeout | `DLC_SHUTDOWN_TIMEOUT` | `30s` | Graceful shutdown timeout |
+| JSON Logging | `DLC_LOGGING_JSON` | `false` | Enable JSON format logging |
+| Log Output | `DLC_LOGGING_OUTPUT` | `""` | Log output file path (empty for stderr) |
+
+**Examples:**
+
+```bash
+# Custom port
+export DLC_SERVER_PORT=9090
+./scripts/start-server.sh start
+
+# Custom host and port
+export DLC_SERVER_HOST="127.0.0.1"
+export DLC_SERVER_PORT=8081
+./scripts/start-server.sh start
+
+# Custom shutdown timeout
+export DLC_SHUTDOWN_TIMEOUT=45s
+
+# Enable JSON logging
+export DLC_LOGGING_JSON=true
+
+# Log to file
+export DLC_LOGGING_OUTPUT="server.log"
+
+# Combined: JSON logging to file
+export DLC_LOGGING_JSON=true
+export DLC_LOGGING_OUTPUT="server.json.log"
+```
+
+**Configuration File Support:**
+
+A `config.example.yaml` file is provided as a template. By default, the application looks for `config.yaml` in the current working directory.
+
+To specify a custom config file path, set the `DLC_CONFIG_FILE` environment variable:
+
+```bash
+DLC_CONFIG_FILE="/path/to/config.yaml" go run ./cmd/server
+```
+
+Example `config.yaml`:
+
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+shutdown:
+  timeout: 30s
+
+logging:
+  json: false
+```
+
+**Configuration Loading Precedence:**
+
+1. **File-based configuration** (highest precedence)
+2. **Environment variables** (override defaults, overridden by config file)
+3. **Default values** (fallback)
+
+All configuration is validated on startup. Invalid configurations cause server startup failure. Configuration values and source are logged at startup.
+
+**Verification:**
+
+```bash
+DLC_SERVER_PORT=9090 DLC_SERVER_HOST="127.0.0.1" ./scripts/start-server.sh start
+
+curl http://127.0.0.1:9090/api/health
+# Expected: {"status":"healthy"}
+```
+
+## Server Status
+
+```bash
+# Check health endpoint
+curl -s http://localhost:8080/api/health
+
+# Check readiness endpoint
+curl -s http://localhost:8080/api/ready
+```
+
+**Expected responses:**
+
+- Health: `{"status":"healthy"}`
+- Readiness (normal): `{"ready":true}`
+- Readiness (during shutdown): `{"ready":false}` (HTTP 503)
+
+**Endpoint Differences:**
+
+- **Health endpoint** (`/api/health`): Indicates if the application is running and functional
+- **Readiness endpoint** (`/api/ready`): Indicates if the application is ready to accept traffic
+
+**Use Cases:**
+
+- **Health**: Used by load balancers to check if the app is alive
+- **Readiness**: Used by Kubernetes / service meshes to determine if the app can accept new requests
+
+**During Graceful Shutdown:**
+
+- Health endpoint continues to return `{"status":"healthy"}`
+- Readiness endpoint returns `{"ready":false}` with HTTP 503 Service Unavailable
+- This allows existing requests to complete while preventing new requests
+
+## Stopping the Server
+
+To stop the server gracefully:
+
+```bash
+# Send SIGTERM for graceful shutdown
+kill -TERM $(lsof -ti :8080)
+
+# Or send SIGINT (Ctrl+C equivalent)
+pkill -INT -f "go run"
+```
+
+**Graceful shutdown process:**
+
+1. Server receives termination signal
+2. Logs shutdown message
+3. Stops accepting new connections
+4. Waits up to 30 seconds for active requests to complete
+5. Closes all connections cleanly
+6. Exits with proper cleanup
+
+For force stop (if graceful shutdown hangs):
+
+```bash
+kill -9 $(lsof -ti :8080)
+```
+
+**Verification:**
+
+```bash
+curl -s http://localhost:8080/api/health
+# Should return connection refused
+```

documentation/CODE_EXAMPLES.md

@@ -0,0 +1,59 @@
+# Code Examples
+
+Snippets and patterns used across the `dance-lessons-coach` codebase. Extracted from the original `AGENTS.md` (Tâche 6 restructure).
+
+## Adding a New API Endpoint
+
+```go
+// 1. Add to interface
+func (h *apiV1GreetHandler) RegisterRoutes(router chi.Router) {
+    router.Get("/", h.handleGreetQuery)
+    router.Get("/{name}", h.handleGreetPath)
+    router.Post("/custom", h.handleCustomGreet) // New endpoint
+}
+
+// 2. Implement handler
+func (h *apiV1GreetHandler) handleCustomGreet(w http.ResponseWriter, r *http.Request) {
+    // Parse request
+    // Call service
+    // Return JSON response
+}
+```
+
+## Logging with Zerolog
+
+```go
+// Trace level logging
+log.Trace().Ctx(ctx).Str("key", "value").Msg("message")
+
+// Info level
+log.Info().Msg("Important event")
+
+// Error level
+log.Error().Err(err).Msg("Error occurred")
+```
+
+For the full logging strategy (when to use Trace vs Info, performance considerations), see [ADR-0003 — Zerolog Logging](../adr/0003-zerolog-logging.md).
+
+## Using `context.Context`
+
+```go
+// Pass context through calls
+func handler(w http.ResponseWriter, r *http.Request) {
+    result := service.Greet(r.Context(), "John")
+    // ...
+}
+
+// Create context with values
+ctx := context.WithValue(r.Context(), "key", "value")
+
+// Create context with timeout
+ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+defer cancel()
+```
+
+For the rationale behind context-aware services, see [ADR-0004 — Interface-Based Design](../adr/0004-interface-based-design.md).
+
+## Best Practices Reminders
+
+For higher-level guidance on code organization, error handling, performance, and testing, see [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md#best-practices) section "Best Practices".

documentation/HISTORY.md

@@ -0,0 +1,83 @@
+# Development History
+
+This document records the historical development phases of `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe (128k context).
+
+All phases below are **completed** ✅. They are kept here for traceability and onboarding context — refer to ADRs (`adr/`) for the technical decisions behind each phase.
+
+## Phase 1: Foundation
+
+- Go 1.26.1 environment setup
+- Project structure with `cmd/` and `pkg/` directories
+- Core Greet service implementation
+- CLI interface
+- Unit tests
+
+## Phase 2: Web API
+
+- Chi router integration
+- Versioned API endpoints (`/api/v1`)
+- Health endpoint (`/api/health`)
+- JSON responses with proper headers
+
+## Phase 3: Logging & Architecture
+
+- Zerolog integration with Trace level
+- Context-aware logging
+- Interface-based design patterns
+- Dependency injection
+
+## Phase 4: Documentation & Testing
+
+- Comprehensive `AGENTS.md`
+- `README.md` with usage instructions
+- Server management guide
+- API endpoint documentation
+
+## Phase 5: Configuration Management
+
+- Viper integration for configuration
+- Environment variable support with `DLC_` prefix
+- Customizable server host/port
+- Configurable shutdown timeout
+- Configuration validation and logging
+- Example configuration file
+
+## Phase 6: Graceful Shutdown
+
+- Context-aware server initialization
+- Signal-based termination (`SIGINT`, `SIGTERM`)
+- Configurable shutdown timeout
+- Readiness endpoint for Kubernetes/service mesh integration
+- Proper resource cleanup during shutdown
+- Health endpoint remains healthy during graceful shutdown
+
+## Phase 7: OpenTelemetry Integration
+
+- OpenTelemetry Go libraries integration
+- Jaeger compatibility for distributed tracing
+- Middleware-only approach using `otelhttp.NewHandler`
+- Configurable sampling strategies
+- Graceful shutdown of tracer provider
+- OTLP exporter with gRPC support
+
+## Phase 8: Build System & Documentation
+
+- Build script for binary compilation
+- Binary output to `bin/` directory
+- Comprehensive commit conventions with gitmoji reference
+- Updated documentation with Jaeger integration guide
+- Cleaned up configuration files
+- Enhanced logging configuration with file output support
+
+## Phase 9: Final Refinements
+
+- Removed unnecessary `time.Sleep` for log flushing
+- Changed server operational logs from Info to Trace level
+- Moved all logging setup logic to config package
+- Simplified server entrypoint to 27 lines
+- Verified all functionality with comprehensive testing
+- Updated documentation to reflect final architecture
+
+## Beyond Phase 9
+
+Subsequent work (CI/CD, BDD scenarios, ADR audit, JWT, config hot-reloading) is tracked in the [Changelog](../CHANGELOG.md) and the corresponding [ADRs](../adr/).

documentation/OBSERVABILITY.md

@@ -0,0 +1,94 @@
+# Observability — OpenTelemetry & Jaeger Integration
+
+Tracing setup for `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.
+
+The application supports OpenTelemetry for distributed tracing with Jaeger compatibility.
+
+## Configuration
+
+Enable OpenTelemetry in your `config.yaml`:
+
+```yaml
+telemetry:
+  enabled: true
+  otlp_endpoint: "localhost:4317"
+  service_name: "dance-lessons-coach"
+  insecure: true
+  sampler:
+    type: "parentbased_always_on"
+    ratio: 1.0
+```
+
+Or via environment variables:
+
+```bash
+export DLC_TELEMETRY_ENABLED=true
+export DLC_TELEMETRY_OTLP_ENDPOINT="localhost:4317"
+export DLC_TELEMETRY_SERVICE_NAME="dance-lessons-coach"
+export DLC_TELEMETRY_INSECURE=true
+export DLC_TELEMETRY_SAMPLER_TYPE="parentbased_always_on"
+export DLC_TELEMETRY_SAMPLER_RATIO=1.0
+```
+
+## Testing with Jaeger
+
+**1. Start Jaeger in Docker:**
+
+```bash
+docker run -d --name jaeger \
+  -e COLLECTOR_OTLP_ENABLED=true \
+  -p 16686:16686 \
+  -p 4317:4317 \
+  jaegertracing/all-in-one:latest
+```
+
+**2. Start the server with OpenTelemetry enabled:**
+
+```bash
+# Using config file
+./scripts/start-server.sh start
+
+# Or with environment variables
+DLC_TELEMETRY_ENABLED=true ./scripts/start-server.sh start
+```
+
+**3. Make API requests:**
+
+```bash
+curl http://localhost:8080/api/v1/greet/John
+```
+
+**4. View traces in Jaeger UI:**
+
+Open http://localhost:16686 and select the `dance-lessons-coach` service.
+
+## Sampler Types
+
+| Sampler | Behavior |
+|---|---|
+| `always_on` | Sample all traces |
+| `always_off` | Sample no traces |
+| `traceidratio` | Sample based on trace ID ratio |
+| `parentbased_always_on` | Sample based on parent span (always on) |
+| `parentbased_always_off` | Sample based on parent span (always off) |
+| `parentbased_traceidratio` | Sample based on parent span with ratio |
+
+## Testing Script
+
+A convenience script is provided:
+
+```bash
+./scripts/test-opentelemetry.sh
+```
+
+This script:
+
+1. Starts Jaeger container
+2. Starts the server with OpenTelemetry
+3. Makes test API calls
+4. Shows Jaeger UI URL
+5. Cleans up on exit
+
+## ADR Reference
+
+See [ADR-0007 — OpenTelemetry Integration](../adr/0007-opentelemetry-integration.md) for the full architectural decision and rationale (middleware-only approach, sampling strategy, OTLP/gRPC choice).

documentation/ROADMAP.md

@@ -0,0 +1,40 @@
+# Roadmap & Future Enhancements
+
+Tracking pending features and architectural improvements. Extracted from the original `AGENTS.md` (Tâche 6 restructure). Status updated continuously — items move to "Completed Features" section once shipped.
+
+## Potential Features
+
+- [ ] Database integration
+- [ ] Authentication / Authorization
+- [ ] Rate limiting
+- [ ] Metrics and monitoring
+- [ ] Docker containerization
+- ✅ CI/CD pipeline ([ADR-0016](../adr/0016-ci-cd-pipeline-design.md), [ADR-0017](../adr/0017-trunk-based-development-workflow.md))
+- [ ] Configuration hot reload
+- [ ] Circuit breakers
+
+## Architectural Improvements
+
+- [ ] Request validation middleware
+- ✅ OpenAPI / Swagger documentation with embedded spec
+- [ ] Enhanced OpenTelemetry instrumentation
+- [ ] Metrics collection and visualization
+- [ ] Health check improvements
+- [ ] Configuration validation enhancements
+
+## Completed Features
+
+- ✅ Graceful shutdown with readiness endpoint
+- ✅ OpenTelemetry integration with Jaeger support
+- ✅ Configuration management with Viper
+- ✅ Comprehensive logging with Zerolog
+- ✅ Build system with binary output
+- ✅ Complete documentation with commit conventions
+- ✅ Version management with runtime info
+
+## How to Propose a New Feature
+
+1. Open a Gitea issue describing the use case and acceptance criteria
+2. If the feature implies an architectural decision, draft an ADR (`adr/<NNNN>-<slug>.md`) following the template
+3. Reference the ADR + issue in any PR introducing the feature
+4. Update this roadmap (move from "Potential" to "Completed" when shipped)

documentation/TROUBLESHOOTING.md

@@ -0,0 +1,107 @@
+# Troubleshooting
+
+Common issues and their resolution. Extracted from the original `AGENTS.md` and merged with relevant sections from `AGENT_USAGE_GUIDE.md` and `BDD_GUIDE.md`. Refer back to those guides for context-specific troubleshooting (agent workflows, BDD test failures).
+
+## Port Already in Use
+
+```bash
+# Find and kill process using port 8080
+kill -TERM $(lsof -ti :8080)
+
+# Force kill if graceful does not work
+kill -9 $(lsof -ti :8080)
+```
+
+## Server Not Responding
+
+```bash
+# Check if running
+curl -s http://localhost:8080/api/health
+
+# Restart server using control script
+./scripts/start-server.sh restart
+
+# View recent logs
+./scripts/start-server.sh logs
+```
+
+If health endpoint returns connection refused, the server may have crashed. Check logs in `./scripts/start-server.sh logs` for stack traces.
+
+## Dependency Issues
+
+```bash
+# Clean and rebuild
+go mod tidy
+go build ./...
+
+# If dependency version conflicts persist
+go mod download
+go mod verify
+```
+
+## Tests Failing
+
+### Unit tests
+
+```bash
+# Run with verbose output
+go test -v ./...
+
+# Check specific test
+go test ./pkg/greet/ -run TestName
+```
+
+### BDD tests
+
+See [`BDD_GUIDE.md`](BDD_GUIDE.md) for the full BDD troubleshooting workflow (Godog setup, scenario isolation, step matching). Common BDD issues:
+
+- **Step not found** → check `pkg/bdd/steps/` for the step definition file
+- **Scenario state leaking** → review [ADR-0025](../adr/0025-bdd-scenario-isolation-strategies.md) for the isolation pattern
+- **Database not reset** → ensure the test fixtures cleanup runs (BDD scenario After hooks)
+
+## Configuration Not Loading
+
+The application logs the configuration source at startup. Check logs for:
+
+```
+[INF] Configuration loaded from: file:config.yaml
+# or
+[INF] Configuration loaded from: env
+# or
+[INF] Configuration loaded from: defaults
+```
+
+If config is not loading as expected:
+
+1. Verify file exists and is readable: `ls -la config.yaml`
+2. Verify env vars are exported: `env | grep DLC_`
+3. Check for typos in keys (case-sensitive)
+4. Review [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md) section "Configuration troubleshooting"
+
+## OpenTelemetry Not Tracing
+
+1. Verify Jaeger is running: `docker ps | grep jaeger`
+2. Check `DLC_TELEMETRY_ENABLED=true` in environment or `telemetry.enabled: true` in config
+3. Verify OTLP endpoint reachable: `nc -zv localhost 4317`
+4. Check sampler is not `always_off`
+5. See [`OBSERVABILITY.md`](OBSERVABILITY.md) for full setup
+
+## Build Failures
+
+```bash
+# Clear caches
+go clean -cache -modcache
+go mod download
+
+# Rebuild
+go build ./...
+```
+
+If errors persist, see [`local-ci-cd-testing.md`](local-ci-cd-testing.md) for the CI/CD pipeline that mirrors the production build.
+
+## Where to Look Next
+
+- **Agent-specific issues** (vibe, mistral, programmer agent) → [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md)
+- **BDD-specific issues** → [`BDD_GUIDE.md`](BDD_GUIDE.md)
+- **Version/release issues** → [`version-management-guide.md`](version-management-guide.md)
+- **CI/CD issues** → [`local-ci-cd-testing.md`](local-ci-cd-testing.md)