feat(#2100): add hive-metric OTLP CLI for agent-emitted custom metrics

docs/observability.md

@@ -125,6 +125,56 @@ Every agent's export includes these resource attributes automatically:
 
 Additional labels can be appended via `extraResourceAttributes`.
 
+Additional labels can be appended per-agent via `extraResourceAttributes` (see
+option reference above); custom per-data-point labels can be passed with
+`hive-metric --labels` (see below).
+
+## Agent-emitted custom metrics (`hive-metric`)
+
+Agents can push arbitrary labeled metrics to the same OTEL collector via the
+`hive-metric` CLI tool, available in every agent container when
+`services.hyperhive.otel.enable = true`.
+
+### Usage
+
+```text
+hive-metric <name> <value> [--type gauge|counter] [--labels key=value...]
+```
+
+- `<name>` — metric name (e.g. `tasks_completed`, `latency_ms`).
+- `<value>` — numeric value (f64; integers and floats both accepted).
+- `--type gauge|counter` — metric kind: `gauge` (instantaneous, default) or
+  `counter` (monotonically increasing cumulative sum).
+- `--labels key=value` — extra per-data-point labels. May be repeated.
+  The resource labels (agent, hive, swarm, service.name) are inherited
+  automatically from `OTEL_RESOURCE_ATTRIBUTES` — do not re-specify them.
+
+### Examples
+
+```text
+# Gauge: current queue depth
+hive-metric queue_depth 17
+
+# Counter: cumulative tasks finished, with a custom label
+hive-metric tasks_completed 1 --type counter --labels phase=scan
+
+# Float gauge with multiple labels
+hive-metric api_latency_ms 142.5 --labels model=sonnet --labels tier=api
+```
+
+### Error when OTEL is not configured
+
+When `services.hyperhive.otel.enable = false` (the default), the
+`OTEL_EXPORTER_OTLP_ENDPOINT` env var is not set and `hive-metric` exits
+with an informative error message. No silently-dropped metrics.
+
+### Wire format
+
+`hive-metric` always uses **OTLP HTTP/JSON** (`application/json` POST to
+`$OTEL_EXPORTER_OTLP_ENDPOINT/v1/metrics`), regardless of the
+`OTEL_EXPORTER_OTLP_PROTOCOL` setting. Auth headers from
+`OTEL_EXPORTER_OTLP_HEADERS` are forwarded verbatim.
+
 ## Metrics temporality
 
 OTEL export is always configured with **cumulative** temporality