securenow 8.9.0 → 8.11.0

package/NPM_README.md

@@ -306,6 +306,36 @@ X-SecureNow-App-Key: <app-uuid>
 
 CLI: `npx securenow event send auth.login.failure --user u_1 --ip 1.2.3.4 --attrs reason=bad_token`
 
+### Build alert SQL from the installed telemetry contract
+
+The NPM package ships the exact ClickHouse table/field contract used for alert-rule authoring.
+Agents should read it instead of guessing SQL columns:
+
+```bash
+# Offline: installed SDK schema, tenant scope, timestamp types, event mappings, and templates
+npx securenow telemetry schema --json
+
+# Connected app: names/types/counts observed in real telemetry (never attribute values)
+npx securenow telemetry fields --app <app-key> --env production --since 24h --json
+
+# Prove candidate SQL against the backend before creating anything
+npx securenow alerts rules validate --sql @rule.sql --app <app-key>
+```
+
+The same local contract is available programmatically:
+
+```js
+const telemetrySchema = require('securenow/telemetry-schema');
+```
+
+Use the installed schema to draft SQL, live field discovery to verify that optional/custom
+fields are actually emitted, and `alerts rules validate` to prove the query compiles and runs.
+A field absent from the selected live window is **unverified**, not necessarily unsupported.
+Mark detections `NEEDS_INSTRUMENTATION` when the repository must add a `track()` event,
+`NEEDS_BASELINE` when only the threshold remains unknown, and `READY` only after field
+verification plus SQL validation. See `node_modules/securenow/TELEMETRY-SQL.md` for tables,
+timestamp handling, privacy rules, templates, and the full test-to-production lifecycle.
+
 ```bash
 # Create a custom detection rule from your own SQL (new in 8.1)
 npx securenow alerts rules create \