docs: update HOWTO with agent registry and SSE endpoints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

HOWTO.md

@@ -114,6 +114,49 @@ curl -s http://localhost:8081/api/v1/diagrams/{contentHash}/render \
 
 **Additional POST filters:** `durationMin`, `durationMax`, `text` (global full-text), `textInBody`, `textInHeaders`, `textInErrors`
 
+### Agent Registry & SSE (Phase 3)
+
+```bash
+# Register an agent
+curl -s -X POST http://localhost:8081/api/v1/agents/register \
+  -H "Content-Type: application/json" \
+  -d '{"agentId":"agent-1","name":"Order Service","group":"order-service-prod","version":"1.0.0","routeIds":["route-1","route-2"],"capabilities":["deep-trace","replay"]}'
+
+# Heartbeat (call every 30s)
+curl -s -X POST http://localhost:8081/api/v1/agents/agent-1/heartbeat
+
+# List agents (optionally filter by status)
+curl -s "http://localhost:8081/api/v1/agents"
+curl -s "http://localhost:8081/api/v1/agents?status=LIVE"
+
+# Connect to SSE event stream (agent receives commands here)
+curl -s -N http://localhost:8081/api/v1/agents/agent-1/events
+
+# Send command to single agent
+curl -s -X POST http://localhost:8081/api/v1/agents/agent-1/commands \
+  -H "Content-Type: application/json" \
+  -d '{"type":"config-update","payload":{"samplingRate":0.5}}'
+
+# Send command to agent group
+curl -s -X POST http://localhost:8081/api/v1/agents/groups/order-service-prod/commands \
+  -H "Content-Type: application/json" \
+  -d '{"type":"deep-trace","payload":{"routeId":"route-1","durationSeconds":60}}'
+
+# Broadcast command to all live agents
+curl -s -X POST http://localhost:8081/api/v1/agents/commands \
+  -H "Content-Type: application/json" \
+  -d '{"type":"config-update","payload":{"samplingRate":1.0}}'
+
+# Acknowledge command delivery
+curl -s -X POST http://localhost:8081/api/v1/agents/agent-1/commands/{commandId}/ack
+```
+
+**Agent lifecycle:** LIVE (heartbeat within 90s) → STALE (missed 3 heartbeats) → DEAD (5min after STALE). DEAD agents kept indefinitely.
+
+**SSE events:** `config-update`, `deep-trace`, `replay` commands pushed in real time. Server sends ping keepalive every 15s.
+
+**Command expiry:** Unacknowledged commands expire after 60 seconds.
+
 ### Backpressure
 
 When the write buffer is full (default capacity: 50,000), ingestion endpoints return **503 Service Unavailable**. Already-buffered data is not lost.
@@ -129,6 +172,11 @@ Key settings in `cameleer3-server-app/src/main/resources/application.yml`:
 | `ingestion.batch-size` | 5000 | Items per ClickHouse batch insert |
 | `ingestion.flush-interval-ms` | 1000 | Buffer flush interval (ms) |
 | `ingestion.data-ttl-days` | 30 | ClickHouse TTL for auto-deletion |
+| `agent-registry.heartbeat-interval-seconds` | 30 | Expected heartbeat interval |
+| `agent-registry.stale-threshold-seconds` | 90 | Time before agent marked STALE |
+| `agent-registry.dead-threshold-seconds` | 300 | Time after STALE before DEAD |
+| `agent-registry.command-expiry-seconds` | 60 | Pending command TTL |
+| `agent-registry.keepalive-interval-seconds` | 15 | SSE ping keepalive interval |
 
 ## Running Tests