feat: enhance agent and board APIs with role-based tags and improved documentation

backend/templates/HEARTBEAT_AGENT.md

@@ -12,6 +12,37 @@ Goal: do real work with low noise while sharing useful knowledge across the boar
 
 If any required input is missing, stop and request a provisioning update.
 
+## API source of truth (OpenAPI)
+Use OpenAPI for endpoint/payload details instead of relying on static examples.
+
+```bash
+curl -s "$BASE_URL/openapi.json" -o /tmp/openapi.json
+```
+
+List operations with role tags:
+```bash
+jq -r '
+  .paths | to_entries[] | .key as $path
+  | .value | to_entries[]
+  | select(any((.value.tags // [])[]; startswith("agent-")))
+  | ((.value.summary // "") | gsub("\\s+"; " ")) as $summary
+  | ((.value.description // "") | split("\n")[0] | gsub("\\s+"; " ")) as $desc
+  | "\(.key|ascii_upcase)\t\([(.value.tags // [])[] | select(startswith("agent-"))] | join(","))\t\($path)\t\($summary)\t\($desc)"
+' /tmp/openapi.json | sort
+```
+
+Worker-focused filter (no path regex needed):
+```bash
+jq -r '
+  .paths | to_entries[] | .key as $path
+  | .value | to_entries[]
+  | select((.value.tags // []) | index("agent-worker"))
+  | ((.value.summary // "") | gsub("\\s+"; " ")) as $summary
+  | ((.value.description // "") | split("\n")[0] | gsub("\\s+"; " ")) as $desc
+  | "\(.key|ascii_upcase)\t\($path)\t\($summary)\t\($desc)"
+' /tmp/openapi.json | sort
+```
+
 ## Schedule
 - Schedule is controlled by gateway heartbeat config (default: every 10 minutes).
 - Keep cadence conservative unless there is a clear latency need.
@@ -71,36 +102,18 @@ If any required input is missing, stop and request a provisioning update.
 
 ## Heartbeat checklist (run in order)
 1) Check in:
-```bash
-curl -s -X POST "$BASE_URL/api/v1/agent/heartbeat" \
-  -H "X-Agent-Token: {{ auth_token }}" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "'$AGENT_NAME'", "board_id": "'$BOARD_ID'", "status": "online"}'
-```
+- Use `POST /api/v1/agent/heartbeat`.
 
 2) Pull execution context:
-```bash
-curl -s "$BASE_URL/api/v1/agent/agents?board_id=$BOARD_ID" \
-  -H "X-Agent-Token: {{ auth_token }}"
-```
-```bash
-curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&assigned_agent_id=$AGENT_ID&limit=5" \
-  -H "X-Agent-Token: {{ auth_token }}"
-```
-```bash
-curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&assigned_agent_id=$AGENT_ID&limit=10" \
-  -H "X-Agent-Token: {{ auth_token }}"
-```
+- Use `agent-worker` endpoints from OpenAPI for:
+  - board agents list,
+  - assigned `in_progress` tasks,
+  - assigned `inbox` tasks.
 
 3) Pull shared knowledge before execution:
-```bash
-curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/memory?is_chat=false&limit=50" \
-  -H "X-Agent-Token: {{ auth_token }}"
-```
-```bash
-curl -s "$BASE_URL/api/v1/boards/$BOARD_ID/group-memory?limit=50" \
-  -H "X-Agent-Token: {{ auth_token }}"
-```
+- Use `agent-worker` endpoints from OpenAPI for:
+  - board memory (`is_chat=false`),
+  - group memory (if grouped).
 - If the board is not in a group, group-memory may return no group; continue.
 
 4) Choose work:
@@ -162,12 +175,7 @@ If there is no high-value assist available, write one non-chat board memory note
 
 If there are no pending tasks to assist (no meaningful `in_progress`/`review` opportunities):
 1) Ask `@lead` for new work on board chat:
-```bash
-curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/memory" \
-  -H "X-Agent-Token: {{ auth_token }}" \
-  -H "Content-Type: application/json" \
-  -d '{"content":"@lead I have no actionable tasks/assists right now. Please add/assign next work.","tags":["chat"]}'
-```
+   - Post to board chat memory endpoint with `tags:["chat"]` and include `@lead`.
 2) In the same message (or a short follow-up), suggest 1-3 concrete next tasks that would move the board forward.
 3) Keep suggestions concise and outcome-oriented (title + why it matters + expected artifact).