add swarm-metrics, an agent CLI for the metrics store

swarm-metrics reads the swarm's VictoriaMetrics from inside an agent
container: query, query-range, series, labels and label-values, each one
GET against the store's Prometheus read API through the gateway, printing
the store's JSON. It authenticates the way swarm-logs does, with the
agent's own queue secret read from bao under the agent's leaf, sent as
a swarm-agent bearer.

On the metrics store's host the read API's auth map gains an agent arm
ahead of the Grafana one. It routes to swarm-metrics-agent-auth, a
swarm-logs-auth instance logged in under the existing swarm-metrics-auth
leaf, whose bao grant now includes swarm/agents/+/queue read. The check is
rate-limited per address like the log store's
(deploy.victoriametrics.agentAuth{Rate,Burst,VerdictTtl}).

nix/agent-modules/metrics.nix installs the wrapped binary when the hive
forwards HIVE_AGENT_METRICS_URL (from swarm.victoriametrics.domain) and a
store address, the same gate as swarm-logs. Adds the base:swarm-metrics
skill and the CLI reference with its freshness check.

Fixes #5395

docs/tools/swarm-metrics-cli.md

@@ -0,0 +1,123 @@
+# Command-Line Help for `swarm-metrics`
+
+This document contains the help content for the `swarm-metrics` command-line program.
+
+**Command Overview:**
+
+* [`swarm-metrics`↴](#swarm-metrics)
+* [`swarm-metrics query`↴](#swarm-metrics-query)
+* [`swarm-metrics query-range`↴](#swarm-metrics-query-range)
+* [`swarm-metrics series`↴](#swarm-metrics-series)
+* [`swarm-metrics labels`↴](#swarm-metrics-labels)
+* [`swarm-metrics label-values`↴](#swarm-metrics-label-values)
+
+## `swarm-metrics`
+
+query the swarm's metrics store from an agent
+
+**Usage:** `swarm-metrics <COMMAND>`
+
+###### **Subcommands:**
+
+* `query` — Evaluate a `MetricsQL` (`PromQL`) expression at one instant
+* `query-range` — Evaluate an expression over a window, one point per step
+* `series` — List the series that match one or more selectors
+* `labels` — List label names, optionally only those on matching series
+* `label-values` — List one label's values; `__name__` lists every metric name
+
+
+
+## `swarm-metrics query`
+
+Evaluate a `MetricsQL` (`PromQL`) expression at one instant
+
+**Usage:** `swarm-metrics query [OPTIONS] <PROMQL>`
+
+###### **Arguments:**
+
+* `<PROMQL>` — The expression. Quote it: `{`, `|` and `"` are the shell's too.
+
+   OTLP metric names keep their dots, so match them by `{__name__="jobq.nodes"}` rather than as a bare name.
+
+###### **Options:**
+
+* `--time <TIME>` — The instant: RFC 3339, a unix timestamp, or relative (`-5m`). Unset means now
+
+
+
+## `swarm-metrics query-range`
+
+Evaluate an expression over a window, one point per step
+
+**Usage:** `swarm-metrics query-range [OPTIONS] --start <START> <PROMQL>`
+
+###### **Arguments:**
+
+* `<PROMQL>` — The expression, quoted as for `query`
+
+###### **Options:**
+
+* `--start <START>` — Start of the window: RFC 3339, a unix timestamp, or relative (`-1h`). Required, so a range is always bounded
+* `--end <END>` — End of the window, in the same forms. Unset means now
+* `--step <STEP>` — Seconds or a duration (`1m`) between points. Unset means the store's default
+
+
+
+## `swarm-metrics series`
+
+List the series that match one or more selectors
+
+**Usage:** `swarm-metrics series [OPTIONS] <MATCHERS>...`
+
+###### **Arguments:**
+
+* `<MATCHERS>` — A series selector, such as `{"service.name"="nats"}`. Repeatable
+
+###### **Options:**
+
+* `--start <START>` — Start of the window: RFC 3339, a unix timestamp, or relative (`-1h`).
+
+   Unset means the store's default: the last day, from 00:00 UTC.
+* `--end <END>` — End of the window, in the same forms. Unset means now
+* `--limit <LIMIT>` — Return at most this many entries
+
+
+
+## `swarm-metrics labels`
+
+List label names, optionally only those on matching series
+
+**Usage:** `swarm-metrics labels [OPTIONS]`
+
+###### **Options:**
+
+* `--match <MATCHERS>` — A series selector to narrow to. Repeatable
+* `--start <START>` — Start of the window: RFC 3339, a unix timestamp, or relative (`-1h`).
+
+   Unset means the store's default: the last day, from 00:00 UTC.
+* `--end <END>` — End of the window, in the same forms. Unset means now
+* `--limit <LIMIT>` — Return at most this many entries
+
+
+
+## `swarm-metrics label-values`
+
+List one label's values; `__name__` lists every metric name
+
+**Usage:** `swarm-metrics label-values [OPTIONS] <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — The label name
+
+###### **Options:**
+
+* `--match <MATCHERS>` — A series selector to narrow to. Repeatable
+* `--start <START>` — Start of the window: RFC 3339, a unix timestamp, or relative (`-1h`).
+
+   Unset means the store's default: the last day, from 00:00 UTC.
+* `--end <END>` — End of the window, in the same forms. Unset means now
+* `--limit <LIMIT>` — Return at most this many entries
+
+
+