docs: add architecture diagram, demo quickstart, screenshot, and changelog

README gains a Mermaid diagram, a one-command demo section up top, a
genuine screenshot of the Service Health dashboard rendered from the
running demo, run/check/alerting docs, and a design-decisions section.
CHANGELOG.md starts the release history at v0.1.0.

Author: simonvanlierde

CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+Notable changes to this stack. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/).
+
+## [0.1.0] - 2026-07-03
+
+First tagged release: the stack is runnable, demoable, and validated in CI.
+
+### Added
+
+- `just demo`: one-command demo — an auto-instrumented FastAPI service under
+  constant load populates Grafana with correlated traces, metrics, and logs.
+- `just check`: validation gate (compose syntax, Prometheus config + alert
+  rules, collector config, YAML, workflows, dashboard JSON), all in pinned
+  containers. Run by GitHub Actions on every push/PR, plus a `just smoke`
+  boot test.
+- Provisioned **Service Health (RED)** dashboard driven by Tempo span
+  metrics — works for any service that sends traces.
+- Prometheus alert rules: target down, OTel export failures, high span
+  error rate.
+- README: architecture diagram, demo quickstart, screenshot, design
+  decisions.
+
+### Changed
+
+- `cloudflared` moved to an optional `compose.tunnel.yml` overlay and pinned
+  (was `:latest`); the core stack no longer needs a tunnel token to run.
+
+### Fixed
+
+- OTLP metrics ingestion: Prometheus 3.x renamed the OTLP receiver flag,
+  so the collector's metrics export 404ed and OTLP metrics were dropped.
+
+## [0.0.1] - 2026-06-30
+
+Initial stack: OTel Collector → Loki / Tempo / Prometheus → Grafana wired
+for cross-signal correlation, exposed via Cloudflare Tunnel, with RELab
+dashboards.

README.md

@@ -4,15 +4,55 @@ Central Grafana + Loki + Tempo + Prometheus + OTel Collector, wired together
 with logs ↔ traces ↔ metrics correlation. Meant to run on one host and
 receive telemetry from multiple projects over OTLP.
 
+```mermaid
+flowchart LR
+    apps["Project apps<br/>(OTLP gRPC 4317 / HTTP 4318)"] --> otel["OTel Collector<br/>(ingestion gateway)"]
+    otel -- logs --> loki[Loki]
+    otel -- traces --> tempo[Tempo]
+    otel -- metrics --> prom[Prometheus]
+    tempo -- "span metrics (RED)" --> prom
+    loki --> grafana[Grafana]
+    tempo --> grafana
+    prom --> grafana
+    grafana --- cf["Cloudflare Tunnel<br/>(optional overlay)"]
+```
+
+## Demo: see it work in one command
+
+```sh
+cp .env.example .env
+just demo
+```
+
+This starts the full stack plus a small auto-instrumented FastAPI service
+under constant load (`compose.demo.yml`). Give it a minute, then open
+Grafana at <http://localhost:3000> (admin / change-me):
+
+- **Dashboards → Service Health (RED)** — request rate, error rate, and
+  latency for the demo service. Latency dots are exemplars: click one to
+  open that exact trace in Tempo.
+- **Explore → Loki** — `{service_name="demo-api"}`; expand an error line
+  and follow its `trace_id` to the trace.
+- **Alerting → Alert rules** — stack-health and error-rate rules,
+  evaluated by Prometheus.
+
+![Service Health (RED) dashboard](docs/img/service-health.png)
+
+Tear it down with `just demo-down`.
+
 ## Layout
 
 ```
-compose.yml             # all services
+compose.yml             # core services
+compose.tunnel.yml      # production overlay: Cloudflare Tunnel
+compose.demo.yml        # demo overlay: sample telemetry source
+demo/                   # the demo FastAPI service
 config/
   otel-collector.yaml   # ingestion gateway (OTLP in → Loki/Tempo/Prometheus out)
   loki.yaml             # logs
   tempo.yaml            # traces
   prometheus.yaml       # metrics
+  alerts/               # Prometheus alert rules
   grafana/              # provisioned datasources + dashboard loader
 dashboards/             # drop JSON dashboards here; Grafana auto-loads them
 ```
@@ -21,11 +61,18 @@ dashboards/             # drop JSON dashboards here; Grafana auto-loads them
 
 ```sh
 cp .env.example .env    # set GRAFANA_ADMIN_PASSWORD
-just up
+just up                 # core stack, local only
+just up-tunnel          # core stack + Cloudflare Tunnel (needs CLOUDFLARE_TUNNEL_TOKEN)
 ```
 
 Grafana: <http://localhost:3000> (admin / whatever you set).
 
+`just check` validates everything (compose files, Prometheus config and
+alert rules, collector config, YAML, workflows, dashboard JSON) in pinned
+containers — no host installs. CI runs the same command on every push and
+PR, plus a smoke test that boots the stack and waits for Grafana to report
+healthy.
+
 ## Sending telemetry from a project
 
 ### Traces + metrics (OTLP)
@@ -64,8 +111,30 @@ Logs carry labels for `service`, `env`, and `host` so you can filter in
 Grafana. Keep label cardinality low — don't add `user_id`, `request_id`,
 etc. as labels; use LogQL filters for those.
 
+## Alerting
+
+Prometheus evaluates the rules in `config/alerts/` (target down, OTel
+export failures, >5% span error rate) and Grafana surfaces them under
+Alerting → Alert rules. There is deliberately no Alertmanager: on a
+single-host stack, another service buys routing complexity before anyone
+needs it. Add one (or a Grafana contact point) when alerts must page
+someone.
+
 ## Storage
 
 Everything persists to local Docker volumes (`loki_data`, `tempo_data`,
 `prometheus_data`, `grafana_data`). Swap Loki / Tempo storage to S3-compatible
 (Backblaze B2, Cloudflare R2, Hetzner, MinIO) when you outgrow local disk.
+
+## Design decisions
+
+Everything enters through **one OTLP gateway** (the collector), so projects
+configure a single endpoint and the backends can be swapped without touching
+any app. The stack is **single-host by design** — CML's telemetry volume
+doesn't justify distributed ingest, and one compose file is auditable — with
+a documented scale-out path (S3-backed Loki/Tempo above) when it stops
+fitting. Logs keep **label cardinality low** (`service`, `env`, `host` only;
+everything else is query-time filtering) because high-cardinality labels are
+how Loki installs fall over. RED metrics are **derived from traces** by
+Tempo's metrics generator, so any service that sends traces gets the
+Service Health dashboard for free, instrumented or not.