From dd398178f0868ab19ac90eb0e6b9499a00e36610 Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Mon, 30 Mar 2026 21:44:12 +0200
Subject: [PATCH] docs: add route-control command to HOWTO and CLAUDE.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 2 +-
 HOWTO.md  | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 278d99c0..de52438b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,7 +36,7 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar
 - Spring Boot 3.4.3 parent POM
 - Depends on `com.cameleer3:cameleer3-common` from Gitea Maven registry
 - Jackson `JavaTimeModule` for `Instant` deserialization
-- Communication: receives HTTP POST data from agents (executions, diagrams, metrics, logs), serves SSE event streams for config push/commands
+- Communication: receives HTTP POST data from agents (executions, diagrams, metrics, logs), serves SSE event streams for config push/commands (config-update, deep-trace, replay, route-control)
 - Maintains agent instance registry with states: LIVE → STALE → DEAD
 - Storage: PostgreSQL (TimescaleDB) for structured data, OpenSearch for full-text search and application log storage
 - Security: JWT auth with RBAC (AGENT/VIEWER/OPERATOR/ADMIN roles), Ed25519 config signing, bootstrap token for registration
diff --git a/HOWTO.md b/HOWTO.md
index 3f88a6b6..8cc74f76 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -325,6 +325,12 @@ curl -s -X POST http://localhost:8081/api/v1/agents/groups/order-service-prod/co
   -H "Authorization: Bearer $TOKEN" \
   -d '{"type":"deep-trace","payload":{"routeId":"route-1","durationSeconds":60}}'
 
+# Send route control command to agent group (start/stop/suspend/resume)
+curl -s -X POST http://localhost:8081/api/v1/agents/groups/order-service-prod/commands \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"type":"route-control","payload":{"routeId":"route-1","action":"stop","nonce":"unique-uuid"}}'
+
 # Broadcast command to all live agents
 curl -s -X POST http://localhost:8081/api/v1/agents/commands \
   -H "Content-Type: application/json" \
@@ -338,7 +344,7 @@ curl -s -X POST http://localhost:8081/api/v1/agents/agent-1/commands/{commandId}
 
 **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.
+**SSE events:** `config-update`, `deep-trace`, `replay`, `route-control` commands pushed in real time. Server sends ping keepalive every 15s.
 
 **Command expiry:** Unacknowledged commands expire after 60 seconds.