fix issues TUI display reliability

README.md

@@ -371,6 +371,33 @@ to Docker or stored in the image.
 - `OTEL_CLICKHOUSE_DB` / `OTEL_CLICKHOUSE_USER` /
   `OTEL_CLICKHOUSE_PASSWORD` - optional ClickHouse connection settings
   (defaults: `otel` / `default` / empty).
+
+### Issues display
+
+The standalone `issues-tui` command is a terminal dashboard for currently
+firing alert spikes. It reads normalized error events directly from
+ClickHouse; it does not replace the web UI's persisted `/api/issues` view.
+
+Build and run it on the display computer (or use `go run`):
+
+```sh
+go build -o issues-tui ./cmd/issues-tui
+OTEL_CLICKHOUSE_ADDR=clickhouse.example.net:9000 \
+OTEL_CLICKHOUSE_DB=otel \
+OTEL_CLICKHOUSE_USER=default \
+OTEL_CLICKHOUSE_PASSWORD='…' \
+OTEL_ALERT_BASE_URL=https://otel.example.net \
+./issues-tui
+```
+
+The display computer must be able to reach ClickHouse's native TCP port. For a
+Kubernetes-only ClickHouse service, use a private network path or tunnel; the
+in-cluster service name is not reachable from an ordinary workstation. The
+dashboard refreshes using the `OTEL_ALERT_*` interval, window, baseline,
+cooldown and lag settings. Press `r` to scan immediately and `q` to quit.
+Use `-once` for a one-shot, non-interactive output suitable for a process
+supervisor health check.
+
 - `OTEL_INGEST_KEY` - optional shared key required (via `?key=` or the
   `X-Otel-Ingest-Key` header) on `/v1/traces`, `/v1/metrics` and `/v1/logs`
   over HTTP. Unset by default (no key required). This is meant to