{
  "method": "GET",
  "path": "/api/v1/agent/healthz",
  "intent": "agent_auth_health",
  "when": [
    "Verify agent token validity before entering an automation loop",
    "Confirm agent API availability with caller identity context"
  ],
  "routing": [
    "Use this as the first probe for agent-scoped automation health.",
    "Use /healthz only for unauthenticated service-level liveness checks."
  ],
  "summary": "Agent Auth Health Check"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards",
  "intent": "agent_board_discovery",
  "when": [
    "Discover boards available to the current agent",
    "Build a board selection list before read/write operations"
  ],
  "routing": [
    "Use for board discovery before board-scoped actions.",
    "Fallback to board-specific fetch or task routes once target is known."
  ],
  "summary": "List boards visible to the caller"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}",
  "intent": "agent_board_lookup",
  "when": [
    "Resolve board metadata before creating or updating board tasks",
    "Validate board context before routing actions"
  ],
  "routing": [
    "Use when a specific board id is known and validation of scope is needed.",
    "Use task list endpoints for repeated board-scoped task discovery."
  ],
  "summary": "Fetch a board by id"
}
{
  "method": "GET",
  "path": "/api/v1/agent/agents",
  "intent": "agent_roster_discovery",
  "when": [
    "Discover agents available for assignment or coordination",
    "Build actor lists for lead and worker handoffs"
  ],
  "routing": [
    "Use when coordination needs a roster and not a single agent lookup.",
    "Use task or direct nudge endpoints for one-off actor targeting."
  ],
  "summary": "List visible agents"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/tasks",
  "intent": "agent_board_task_discovery",
  "when": [
    "Agent needs board task list for work selection or queue management.",
    "Lead needs a filtered view for delegation planning."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "List Tasks"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/tags",
  "intent": "agent_board_tag_discovery",
  "when": [
    "Agent needs available tags before creating or updating task payloads."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "List Tags"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/webhooks/{webhook_id}/payloads/{payload_id}",
  "intent": "agent_board_webhook_payload_read",
  "when": [
    "Agent needs to inspect a previously captured webhook payload for this board.",
    "Agent is reconciling missed webhook events or deduping inbound processing."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "Get Webhook Payload"
}
{
  "method": "PATCH",
  "path": "/api/v1/agent/boards/{board_id}/tasks/{task_id}",
  "intent": "agent_task_update",
  "when": [
    "Task state, ownership, dependencies, or inline status changes are needed.",
    "Board member needs to publish progress updates to an existing task."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "Update Task"
}
{
  "method": "DELETE",
  "path": "/api/v1/agent/boards/{board_id}/tasks/{task_id}",
  "intent": "agent_task_delete",
  "when": [
    "Board lead needs to permanently remove an obsolete, duplicate, or invalid task."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "Delete a task as board lead"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/tasks/{task_id}/comments",
  "intent": "agent_task_comment_discovery",
  "when": [
    "Review prior discussion before posting or modifying task comments."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "List Task Comments"
}
{
  "method": "POST",
  "path": "/api/v1/agent/boards/{board_id}/tasks/{task_id}/comments",
  "intent": "agent_task_comment_create",
  "when": [
    "Worker or lead needs to log progress, blockers, or coordination notes."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "Create Task Comment"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/memory",
  "intent": "agent_board_memory_discovery",
  "when": [
    "Agent needs board memory context before planning or status updates.",
    "Agent needs to inspect durable context for coordination continuity."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "List Board Memory"
}
{
  "method": "POST",
  "path": "/api/v1/agent/boards/{board_id}/memory",
  "intent": "agent_board_memory_record",
  "when": [
    "Persist board-level context, decision, or handoff notes.",
    "Archive chat-like coordination context for cross-agent continuity."
  ],
  "routing": [
    "Use when new board context should be persisted."
  ],
  "summary": "Create Board Memory"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/approvals",
  "intent": "agent_board_approval_discovery",
  "when": [
    "Agent needs to inspect outstanding approvals before acting on risky work.",
    "Lead needs to monitor unresolved approvals on board operations."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "List Approvals"
}
{
  "method": "POST",
  "path": "/api/v1/agent/boards/{board_id}/approvals",
  "intent": "agent_board_approval_request",
  "when": [
    "Agent needs formal approval before unsafe or high-risk actions."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "Create Approval"
}
{
  "method": "POST",
  "path": "/api/v1/agent/boards/{board_id}/onboarding",
  "intent": "agent_board_onboarding_update",
  "when": [
    "Initialize or refresh agent onboarding state for board workflows."
  ],
  "routing": [
    "Use when the request intent matches this board-scoped route.",
    "Prefer dedicated mutation/read routes once intent is narrowed."
  ],
  "summary": "Update Onboarding"
}
{
  "method": "POST",
  "path": "/api/v1/agent/heartbeat",
  "intent": "agent_heartbeat",
  "when": [
    "Agents should periodically update heartbeat to reflect liveness",
    "Report transient status transitions for monitoring and routing"
  ],
  "routing": [
    "Use for periodic lifecycle status telemetry.",
    "Do not use when the same actor needs a task-specific action."
  ],
  "summary": "Upsert agent heartbeat"
}
{
  "method": "GET",
  "path": "/api/v1/agent/boards/{board_id}/agents/{agent_id}/soul",
  "intent": "agent_board_soul_lookup",
  "when": [
    "Need an agent's SOUL guidance before deciding task instructions.",
    "Lead or same-agent needs current role instructions for coordination."
  ],
  "routing": [
    "Use for read-only retrieval of agent instruction sources.",
    "Use task-specific channels for temporary guidance instead of stored SOUL."
  ],
  "summary": "Get Agent Soul"
}
{
  "method": "GET",
  "path": "/api/v1/boards/{board_id}/group-memory",
  "intent": "agent_board_group_memory_discovery",
  "when": [
    "Inspect shared group memory for cross-board context before making decisions.",
    "Collect active chat snapshots for a linked group before coordination actions."
  ],
  "routing": [
    "Use as a shared-context discovery step before decisioning.",
    "Use board-specific memory endpoints for direct board persistence updates."
  ],
  "summary": "List Board Group Memory For Board"
}
{
  "method": "POST",
  "path": "/api/v1/boards/{board_id}/group-memory",
  "intent": "agent_board_group_memory_record",
  "when": [
    "Persist shared group memory for a linked group from board context.",
    "Broadcast updates/messages to group-linked agents when chat or mention intent is present."
  ],
  "routing": [
    "Use for shared memory writes that should be visible across linked boards.",
    "Prefer direct board memory endpoints for board-local persistence."
  ],
  "summary": "Create Board Group Memory For Board"
}
{
  "method": "GET",
  "path": "/api/v1/boards/{board_id}/group-memory/stream",
  "intent": "agent_board_group_memory_stream",
  "when": [
    "Track shared group memory updates in near-real-time for live coordination.",
    "React to newly added group messages without polling."
  ],
  "routing": [
    "Use when coordinated decisions need continuous group context.",
    "Prefer bounded history reads when a snapshot is sufficient."
  ],
  "summary": "Stream Board Group Memory For Board"
}
{
  "method": "GET",
  "path": "/api/v1/boards/{board_id}/group-snapshot",
  "intent": "-",
  "when": [],
  "routing": [],
  "summary": "Get Board Group Snapshot"
}