From 1fb93c3b6e0856ca4fe9e03b2e563da750df723f Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Wed, 11 Mar 2026 17:44:56 +0100
Subject: [PATCH] docs: update HOWTO with Phase 2 search and diagram endpoints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 HOWTO.md | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/HOWTO.md b/HOWTO.md
index 354da8ad..3f3480cb 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -22,7 +22,7 @@ Start ClickHouse:
 docker compose up -d
 ```
 
-This starts ClickHouse 25.3 and automatically runs the schema init script (`clickhouse/init/01-schema.sql`).
+This starts ClickHouse 25.3 and automatically runs the schema init scripts (`clickhouse/init/01-schema.sql`, `clickhouse/init/02-search-columns.sql`).
 
 | Service    | Port | Purpose          |
 |------------|------|------------------|
@@ -79,6 +79,41 @@ curl -s http://localhost:8081/api/v1/api-docs
 open http://localhost:8081/api/v1/swagger-ui.html
 ```
 
+### Search (Phase 2)
+
+```bash
+# Search by status (GET with basic filters)
+curl -s "http://localhost:8081/api/v1/search/executions?status=COMPLETED&limit=10"
+
+# Search by time range
+curl -s "http://localhost:8081/api/v1/search/executions?timeFrom=2026-03-11T00:00:00Z&timeTo=2026-03-12T00:00:00Z"
+
+# Advanced search (POST with full-text)
+curl -s -X POST http://localhost:8081/api/v1/search/executions \
+  -H "Content-Type: application/json" \
+  -d '{"status":"FAILED","text":"NullPointerException","limit":20}'
+
+# Transaction detail (nested processor tree)
+curl -s http://localhost:8081/api/v1/executions/{executionId}
+
+# Processor exchange snapshot
+curl -s http://localhost:8081/api/v1/executions/{executionId}/processors/{index}/snapshot
+
+# Render diagram as SVG
+curl -s http://localhost:8081/api/v1/diagrams/{contentHash}/render \
+  -H "Accept: image/svg+xml"
+
+# Render diagram as JSON layout
+curl -s http://localhost:8081/api/v1/diagrams/{contentHash}/render \
+  -H "Accept: application/json"
+```
+
+**Search response format:** `{ "data": [...], "total": N, "offset": 0, "limit": 50 }`
+
+**Supported search filters (GET):** `status`, `timeFrom`, `timeTo`, `correlationId`, `limit`, `offset`
+
+**Additional POST filters:** `durationMin`, `durationMax`, `text` (global full-text), `textInBody`, `textInHeaders`, `textInErrors`
+
 ### Backpressure
 
 When the write buffer is full (default capacity: 50,000), ingestion endpoints return **503 Service Unavailable**. Already-buffered data is not lost.