From 65ff2d551218aa5c3ffd3a17efe1e03a695fc660 Mon Sep 17 00:00:00 2001
From: stacknil <stacknil@proton.me>
Date: Sun, 17 May 2026 23:09:55 +0800
Subject: [PATCH] Refresh validation docs

---
 README.md             | 21 ++++++++++++++-------
 docs/roadmap.md       |  1 +
 docs/sample-output.md |  1 +
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index b19ab29..dac009f 100644
--- a/README.md
+++ b/README.md
@@ -106,8 +106,15 @@ Required fields for both formats on every row or record:
 - `source`
 - `target`
 - `status`
-
-Cooldown behavior:
+
+Input and output validation:
+
+- config paths, event inputs, and plot CSV inputs must point to files
+- required event fields must be present and non-empty
+- custom timestamp columns cannot reuse required event field names
+- plot input tables validate required columns, datetime values, numeric ranges, and window bounds
+
+Cooldown behavior:
 
 - repeated alerts are keyed by `(rule_name, scope)`
 - scope prefers the first available entity-like field in this order: `entity`, `source`, `target`, `host`
@@ -123,11 +130,11 @@ Cooldown behavior:
 - [`data/processed/richer_sample/summary.json`](data/processed/richer_sample/summary.json) captures the richer scenario pack
 - [`tests/`](tests/) keeps regression coverage close to the CLI behavior and windowing logic
 
-## Next Demo Directions
-
-- strengthen JSONL and CSV validation so ingestion failures are clearer
-- keep reducing repeated alert noise while preserving simple rule-based behavior
-- keep sample-output docs and public repo presentation aligned with the checked-in demo state
+## Next Demo Directions
+
+- add a focused auth/login anomaly triage walkthrough on top of the existing window features
+- add a compact config-change drift follow-up scenario using the current deterministic evidence model
+- keep sample-output docs and public repo presentation aligned with the checked-in demo state
 
 ## Scope
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
index bbcc581..ea9be9b 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -6,6 +6,7 @@ Recently added:
 
 - [rule-evaluation-and-dedup-demo](../demos/rule-evaluation-and-dedup-demo/README.md) now shows raw rule hits, retained alerts, and suppression reasons side by side.
 - [config-change-investigation-demo](../demos/config-change-investigation-demo/README.md) now shows risky configuration changes, bounded evidence attachment, and deterministic investigation summaries.
+- Core telemetry-window validation now gives clearer failures for malformed inputs, invalid run configs, rule parameters, plot CSV values, and output window bounds.
 
 ## 1. Auth/Login Anomaly Triage Demo
 
diff --git a/docs/sample-output.md b/docs/sample-output.md
index 68865da..744cb3a 100644
--- a/docs/sample-output.md
+++ b/docs/sample-output.md
@@ -1,6 +1,7 @@
 # Sample Output
 
 The committed sample artifacts are intended to be reproducible from the bundled inputs and configs.
+The CLI validates plot CSV inputs before rendering: required columns must be present, timestamps must parse, counts and rates must stay in range, and each output row must have coherent window bounds.
 
 ## Default Sample