From f79b0e601fcc4c5302be70115e90a9e8995d27bb Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 16:14:47 +0200
Subject: [PATCH] docs(dashboard): add descriptions field to tool-groups +
 capabilities API response shape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GET /api/tool-groups and GET /api/capabilities both return a
descriptions map (name → short string) added in feat(#1082). The
map drives native browser tooltips on column headers in the
P3RM1SS10NS tab. The API docs still showed the old 2-field shape.
---
 docs/web-ui/dashboard.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md
index a6ec9f87..da8a20bf 100644
--- a/docs/web-ui/dashboard.md
+++ b/docs/web-ui/dashboard.md
@@ -805,19 +805,25 @@ that's a browser-level decision, not ours.
 - `POST /retry-reminder/{id}` — re-arm a reminder whose delivery
   failed (clears the failure state so the scheduler retries).
 - `GET /api/tool-groups` — returns `{ groups: Vec<String>,
-  assignments: BTreeMap<String, Vec<String>> }`. `groups` is the
+  assignments: BTreeMap<String, Vec<String>>,
+  descriptions: BTreeMap<String, String> }`. `groups` is the
   ordered list of all known tool-group names (drives the column
   headers in the P3RM1SS10NS tab); `assignments` is the per-agent
-  override map (absent agents use the role default).
+  override map (absent agents use the role default); `descriptions`
+  maps each group name to a short human-readable string surfaced as
+  a column-header tooltip on hover.
 - `POST /api/tool-groups/{agent}` — body `{ groups: ["name", …] }`.
   Writes the tool-group set for `{agent}` to
   `/var/lib/hyperhive/meta/tool-groups.json` and queues a rebuild so
   `HIVE_TOOL_GROUPS` takes effect. Agent name validated;
   `guard_agent_name` applied.
 - `GET /api/capabilities` — returns `{ caps: Vec<String>,
-  assignments: BTreeMap<String, Vec<String>> }`. `caps` is the
+  assignments: BTreeMap<String, Vec<String>>,
+  descriptions: BTreeMap<String, String> }`. `caps` is the
   ordered list of all known capability names; `assignments` is the
-  per-agent grant map (absent agents have no extra capabilities).
+  per-agent grant map (absent agents have no extra capabilities);
+  `descriptions` maps each capability name to a short human-readable
+  string surfaced as a column-header tooltip on hover.
 - `POST /api/capabilities/{agent}` — body `{ caps: ["name", …] }`.
   Writes the capability set for `{agent}` to
   `/var/lib/hyperhive/meta/capabilities.json` and queues a rebuild so