hive-ag3nt + docs: extract identity prose (#716 batch 1)

docs/conventions.md

@@ -13,6 +13,44 @@ exist because something already went wrong without them.
   (8100..8999) for every agent including the manager; dashboard
   `cfg.dashboardPort` (default 7000).
 
+## Hive identity (label + domain + display names)
+
+Four env vars cover the identity surface, read by
+`hive_ag3nt::identity`:
+
+- `HIVE_LABEL` — short, hive-local agent label (`iris`,
+  `damocles`). `label()` returns it; falls back to empty string if
+  the env var is missing so downstream callers can decide how to
+  surface "unknown agent" rather than getting a panic from this
+  module.
+- `HYPERHIVE_HIVE_DOMAIN` — the hive's canonical DNS domain (e.g.
+  `darkest.space`), set by `hive-c0re.nix` from
+  `services.hyperhive.domain`. When configured, `qualified_label()`
+  returns `${label}@${domain}` (e.g. `iris@darkest.space`); when
+  unset (single-hive deployments, dev/test) it degrades to just
+  the short label so existing callers see no change. The
+  qualified form surfaces in the per-agent web UI title, the
+  system-prompt template, and `/api/state.qualified_label`.
+- `HYPERHIVE_HIVE_NAME` — human display name of this hive
+  (`pr1ma`). Read by `hive_name()`; `None` when unset.
+- `HYPERHIVE_SWARM_NAME` — human display name of the wider swarm
+  this hive belongs to (`constellat1on`). Read by `swarm_name()`;
+  federated hives at different DNS domains can share a swarm
+  name.
+
+`hive_name` + `swarm_name` are **distinct** from
+`HYPERHIVE_HIVE_DOMAIN`: the domain may carry the hive name as
+its leftmost label by convention, but the convention isn't
+machine-readable, and federated hives at different DNS domains
+can share a swarm name. Humans want both: the address
+(`@darkest.space`) AND the prose name (`pr1ma`). Matrix MXIDs
+still use the domain-based convention untouched.
+
+`qualify(label)` is the same shape as `qualified_label()` but
+applies to an arbitrary label the caller already has (e.g. a peer
+name from the broker); it's the right surface when rendering a
+peer's name when the caller knows it's hive-local.
+
 ## Identity = socket
 
 There are no auth tokens on the per-agent unix sockets. The socket