📝 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>

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)