ADR-0012 phase 1 + phase 2 are wired (BFF + SPA), so the
"Observability dev-loop" placeholder in the roadmap table now has
real content to point at. Promote it from §9 (was §8) future-work
list to a full §5 walkthrough sitting between "Daily commands"
and "Dependency updates".
What §5 covers:
- Bringing up the observability stack (`./infra/local/dev.sh up
observability`) with the endpoint table.
- Reading a trace in Jaeger — service-dropdown filter, span
attribute keys to look at, the trace-id-as-pivot pattern.
- Correlating a trace with the BFF Pino logs via `trace_id` and
`request_id` (the latter the per-request UUID nestjs-cls
provides).
- Reading SPA spans from the browser (DevTools Network +
Jaeger UI cross-check).
- Common gotchas — observability profile not active, CORS
pre-flight on `/v1/traces`, `propagateTraceHeaderCorsUrls`
mismatches, NODE_ENV mis-set, EADDRINUSE.
- Pointer at the "wired as features land" deltas (CLS keys for
session/user/audience, redact list, custom domain spans, prod
backend) so a contributor knows what's intentionally not yet
there.
Renumber the rest of the doc accordingly (5→6 / 6→7 / 7→8 / 8→9)
and drop the now-implemented "Observability dev-loop" line from
the §9 roadmap table.
`docs/README.md` cross-link updated to mention the new section.
Julien Gautier