📝 docs(restructure): split AGENTS.md into focused guides (Tâche 6 Phase B)

Création de 9 fichiers neufs pour décharger AGENTS.md (1296 lignes → ~130) en documents lazy-loadables, compatibles avec la limite de contexte 128k de Mistral Vibe (cf. ARCODANGE migration Phase 1, Tâche 6 du curriculum). Sept guides ciblés sous documentation/ : - HISTORY.md : phases historiques 1-9 du développement - CLI.md : commandes CLI, server lifecycle, config DLC_* - API.md : endpoints REST, OpenAPI, Greet v1/v2 - OBSERVABILITY.md : OpenTelemetry + Jaeger, sampler types, test - TROUBLESHOOTING.md : issues connues + pointeurs vers guides spé - CODE_EXAMPLES.md : snippets endpoint/logging/context, pointeurs ADR - ROADMAP.md : potential features, architectural improvements Deux fichiers racine : - CHANGELOG.md : user-facing, format Keep a Changelog - AGENT_CHANGELOG.md : décisions structurantes des agents AI (référencé par AGENTS.md, n'existait pas) Le contenu est extrait fidèlement d'AGENTS.md sans réinterprétation. Phase C (réécriture AGENTS.md court) suit dans le commit suivant. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 23:28:10 +02:00
parent 73a3af1552
commit 41ee8c56ac
9 changed files with 866 additions and 0 deletions
--- a/AGENT_CHANGELOG.md
+++ b/AGENT_CHANGELOG.md
@@ -0,0 +1,32 @@
+# AGENT_CHANGELOG
+
+Trace ordonnée des décisions et actions structurantes prises par les agents AI (Claude Code, Mistral Vibe, autres) sur le projet `dance-lessons-coach`. Complémentaire au [`CHANGELOG.md`](CHANGELOG.md) qui couvre les changements user-facing du produit.
+
+**Pourquoi ce fichier** : référencé dans la documentation directrice (cf. AGENTS.md), mais initialement absent du repo. Initialisé dans le cadre de la Tâche 6 du curriculum migration Claude → Mistral Vibe (ARCODANGE Phase 1).
+
+## Convention
+
+Une entrée par décision/action structurante prise par un agent AI. Format :
+
+```
+## YYYY-MM-DD — <Agent> — <Titre court>
+
+**Contexte** : 1-3 lignes — pourquoi cette action
+**Décision/Action** : ce qui a été fait
+**Conséquence** : impact sur le projet (fichiers, conventions, workflows)
+**Référence** : commit hash, PR Gitea, ADR, issue (le cas échéant)
+```
+
+Les entrées qui ne demandent pas de discussion (typo fixes, formatting, dependency bumps mineurs) ne sont **pas** loguées ici — c'est ce que fait le commit Git. Ce fichier garde uniquement les décisions où le **pourquoi** mérite une trace.
+
+---
+
+## 2026-05-02 — Mistral Vibe (intent-router) + Claude Code (Opus 4.7) — Initialisation AGENT_CHANGELOG.md
+
+**Contexte** : Tâche 6 du curriculum migration ARCODANGE Phase 1 (cf. `~/.vibe/plans/migration-claude-vers-mistral-phase-1.md`). Le fichier `AGENT_CHANGELOG.md` était mentionné dans la documentation directrice projet mais n'existait pas — friction identifiée par l'audit Phase A.
+
+**Décision/Action** : initialiser le fichier avec convention claire et pointer depuis `AGENTS.md` (Tâche 6 Phase C).
+
+**Conséquence** : tout agent qui prend une décision structurante sur le projet doit ajouter une entrée datée ici. Permet la traçabilité des choix AI au-delà des commits Git.
+
+**Référence** : Tâche 6 du plan migration. Voir aussi `~/.vibe/plans/task-6-phase-a-results.md` pour le contexte complet de la restructuration en cours.
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,57 @@
+# Changelog
+
+Notable user-facing changes to `dance-lessons-coach`. Format inspired by [Keep a Changelog](https://keepachangelog.com/), versioning follows [Semantic Versioning 2.0.0](https://semver.org/) (see [`documentation/version-management-guide.md`](documentation/version-management-guide.md)).
+
+The historical phases of foundational development (Phase 1 to Phase 9) are documented in [`documentation/HISTORY.md`](documentation/HISTORY.md).
+
+## [Unreleased]
+
+### Added
+
+_(items pending release; move to a versioned section when tagged)_
+
+### Changed
+
+### Fixed
+
+---
+
+## 2026-04-05 — Architecture Documentation
+
+- ✅ Added comprehensive ADR directory with 9 decision records
+- ✅ Enhanced Zerolog vs Zap analysis in logging ADR
+- ✅ Updated `README.md` and `AGENTS.md` with ADR references
+- ✅ Documented hybrid testing approach
+- ✅ Added BDD testing decision record
+
+## 2026-04-04 — Observability & Testing
+
+- ✅ OpenTelemetry integration with Jaeger
+- ✅ Middleware-only tracing approach
+- ✅ Comprehensive telemetry configuration
+- ✅ BDD testing framework setup
+- ✅ Hybrid testing strategy documentation
+
+## 2026-04-03 — Production Readiness
+
+- ✅ Graceful shutdown with readiness endpoints
+- ✅ Configuration management with Viper
+- ✅ JSON logging configuration
+- ✅ File output logging support
+- ✅ Comprehensive error handling
+
+## 2026-04-02 — Web API Foundation
+
+- ✅ Chi router integration
+- ✅ Versioned API endpoints (`/api/v1`)
+- ✅ Health and readiness endpoints
+- ✅ JSON responses with proper headers
+- ✅ Interface-based design patterns
+
+## 2026-04-01 — Project Foundation
+
+- ✅ Go 1.26.1 environment setup
+- ✅ Project structure with `cmd/` and `pkg/`
+- ✅ Core Greet service implementation
+- ✅ CLI interface
+- ✅ Unit tests with table-driven approach
--- a/documentation/API.md
+++ b/documentation/API.md
@@ -0,0 +1,143 @@
+# API Endpoints
+
+REST API reference for `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.
+
+## Base URL
+
+```
+http://localhost:8080
+```
+
+## OpenAPI Documentation
+
+- **Swagger UI:** `http://localhost:8080/swagger/`
+- **OpenAPI Spec:** `http://localhost:8080/swagger/doc.json`
+
+The API provides interactive documentation using Swagger UI with complete OpenAPI 2.0 specification. All endpoints, request/response models, and validation rules are documented using a **hierarchical tagging system**.
+
+**Features:**
+
+- Interactive API exploration with hierarchical organization
+- Try-it-out functionality for all endpoints
+- Model schemas with examples
+- Response examples with validation rules
+- Hierarchical tag structure for better navigation
+
+**Generation:** Documentation is auto-generated from code annotations using [swaggo/swag](https://github.com/swaggo/swag) with the command:
+
+```bash
+go generate ./pkg/server/
+```
+
+**Tag Organization:**
+
+- `API/v1/Greeting` — Version 1 greeting endpoints
+- `API/v2/Greeting` — Version 2 greeting endpoints
+- `System/Health` — Health and readiness endpoints
+
+**Hierarchical Benefits:**
+
+- Clear separation between API domains (API vs System)
+- Version organization within each domain
+- Natural hierarchy in Swagger UI
+- Scalable for future API growth
+
+**Embedded Documentation:** The OpenAPI spec is embedded in the binary using Go's `//go:embed` directive for single-binary deployment.
+
+---
+
+## Health Check
+
+```http
+GET /api/health
+```
+
+**Response:**
+
+```json
+{"status":"healthy"}
+```
+
+## Readiness Check
+
+```http
+GET /api/ready
+```
+
+**Responses:**
+
+- Normal operation: `{"ready":true}` (HTTP 200)
+- During shutdown: `{"ready":false}` (HTTP 503 Service Unavailable)
+
+**Purpose:** Indicates whether the server is ready to accept new requests. Returns false during graceful shutdown to allow existing requests to complete while preventing new ones.
+
+## Greet Service v1
+
+```http
+GET /api/v1/greet/
+GET /api/v1/greet/{name}
+```
+
+**Examples:**
+
+```bash
+# Default greeting
+curl http://localhost:8080/api/v1/greet/
+# Response: {"message":"Hello world!"}
+
+# Personalized greeting
+curl http://localhost:8080/api/v1/greet/John
+# Response: {"message":"Hello John!"}
+
+# Another example
+curl http://localhost:8080/api/v1/greet/Alice
+# Response: {"message":"Hello Alice!"}
+```
+
+## Greet Service v2 (Feature-flagged)
+
+```http
+POST /api/v2/greet
+```
+
+**Request Body:**
+
+```json
+{
+  "name": "John"
+}
+```
+
+**Examples:**
+
+```bash
+# Valid request
+curl -X POST http://localhost:8080/api/v2/greet \
+  -H "Content-Type: application/json" \
+  -d '{"name":"John"}'
+# Response: {"message":"Hello my friend John!"}
+
+# Empty name (valid, returns default)
+curl -X POST http://localhost:8080/api/v2/greet \
+  -H "Content-Type: application/json" \
+  -d '{"name":""}'
+# Response: {"message":"Hello my friend!"}
+
+# Missing name field (valid, returns default)
+curl -X POST http://localhost:8080/api/v2/greet \
+  -H "Content-Type: application/json" \
+  -d '{}'
+# Response: {"message":"Hello my friend!"}
+
+# Name too long (validation error)
+curl -X POST http://localhost:8080/api/v2/greet \
+  -H "Content-Type: application/json" \
+  -d '{"name":"ThisNameIsWayTooLongAndShouldFailValidationBecauseItExceedsTheMaximumAllowedLengthOf100Characters!!!!"}'
+# Response: {"error":"validation_failed","message":"Invalid request data","details":[{"message":"Name failed validation for 'max' (parameter: 100)"}]}
+```
+
+**Validation Rules:**
+
+- `name`: Maximum length 100 characters (optional field)
+
+**Feature Flag:** Enable with `DLC_API_V2_ENABLED=true` or in config file with `api.v2_enabled: true`.
--- a/documentation/CLI.md
+++ b/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
+```
--- a/documentation/CODE_EXAMPLES.md
+++ b/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".
--- a/documentation/HISTORY.md
+++ b/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/).
--- a/documentation/OBSERVABILITY.md
+++ b/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).
--- a/documentation/ROADMAP.md
+++ b/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)
--- a/documentation/TROUBLESHOOTING.md
+++ b/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)