Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

demo: add runnable feature playbooks + smoke-tests

xerj-org6a4a6923efac
diff --git a/demo/playbooks/README.md b/demo/playbooks/README.md
new file mode 100644
index 000000000..73526e186
--- /dev/null
+++ b/demo/playbooks/README.md
@@ -0,0 +1,48 @@
+# Xerj feature playbooks & smoke-tests
+
+Real, runnable smoke-tests for every major Xerj use case — each one a
+sequence of **actual commands against a live binary with their captured
+output**, so the same material doubles as:
+
+- **docs** — copy a step's `curl` + JSON straight into a docs page, and
+- **screencast scripts** — drive an AISE scene from `playbooks.json`.
+
+## Run
+
+```bash
+# 1. start xerj (ES-compat on :9200, native ops on :8080)
+xerj --insecure --data-dir /tmp/xerj/data
+
+# 2. run the suite (Node ≥18, uses curl)
+node demo/playbooks/run.mjs
+```
+
+It rebuilds its own fixtures, executes every step, asserts pass/fail, and
+writes the artifacts below. Re-running against a fresh `--data-dir` is
+deterministic.
+
+## Artifacts
+
+| file | purpose |
+|---|---|
+| `SMOKE_REPORT.md` | coverage table + pass/fail + the doc-vs-binary gaps |
+| `casts/<id>.md` | human-readable cast per use case (`$ curl …` → real output) — for docs & screencasts |
+| `playbooks.json` | structured `{label, cmd, status, output}` per step — for generating AISE scenes |
+
+## Use cases covered
+
+boot/health · quickstart CRUD · bulk ingest · full-text query families ·
+aggregations · vector/kNN · analyzers · mappings/templates/aliases ·
+log-analytics · ES migration parity · native ops (health/metrics) ·
+embedded Console UX.
+
+## Known gaps (captured by the suite, not silently skipped)
+
+The ES-compat API (:9200) is comprehensive and green. The **native `/v1`
+API (:8080)** currently implements only `/v1/health` and `/v1/metrics`;
+the other documented endpoints (`/v1/health/ready`, `/v1/cluster/health`,
+`/v1/admin/flush`, `/v1/admin/backup`, `/v1/indices/:name/turbo-ingest`,
+etc.) return 404/405 in this build. They show up as ⚠️ in the report so the
+docs and the binary can be reconciled. Per-index `_cat/indices/{name}` and
+the global `_stats`/`POST /_refresh` also differ from ES (use
+`_cat/indices`, `_count`, and per-index `_refresh`).
diff --git a/demo/playbooks/SMOKE_REPORT.md b/demo/playbooks/SMOKE_REPORT.md
new file mode 100644
index 000000000..cf8fe66b8
--- /dev/null
+++ b/demo/playbooks/SMOKE_REPORT.md
@@ -0,0 +1,29 @@
+# Xerj feature smoke-tests — coverage & results
+
+Generated by `demo/playbooks/run.mjs` against a live xerj (ES-compat :9200 + native :8080).
+
+**57/61 steps passing across 12 use cases.**
+
+| # | use case | doc | steps | pass | cast |
+|---|---|---|---|---|---|
+| 01 | Boot & health — one binary is up | install / quickstart | 5 | ✅ 5/5 | [cast](casts/01-boot-health.md) |
+| 02 | Quickstart — index, document, get, search | quickstart | 4 | ✅ 4/4 | [cast](casts/02-quickstart-crud.md) |
+| 03 | Bulk ingest — ES /_bulk wire protocol | ingest | 4 | ✅ 4/4 | [cast](casts/03-ingest-bulk.md) |
+| 04 | Full-text search — the ES query families | queries / playbooks/full-text | 10 | ✅ 10/10 | [cast](casts/04-full-text.md) |
+| 05 | Aggregations — the boardroom view | aggregations | 9 | ✅ 9/9 | [cast](casts/05-aggregations.md) |
+| 06 | Vector search — kNN, no Pinecone | vectors / playbooks/vector-search | 4 | ✅ 4/4 | [cast](casts/06-vector-search.md) |
+| 07 | Analyzers — _analyze | analyzers | 3 | ✅ 3/3 | [cast](casts/07-analyzers.md) |
+| 08 | Mappings, templates & aliases | config / operations | 4 | ✅ 4/4 | [cast](casts/08-mappings-templates-aliases.md) |
+| 09 | Log analytics — Splunk/Kibana workload | playbooks/log-analytics | 5 | ✅ 5/5 | [cast](casts/09-log-analytics.md) |
+| 10 | Migration from Elasticsearch — drop-in parity | migration-from-es | 4 | ✅ 4/4 | [cast](casts/10-migration-es.md) |
+| 11 | Native ops API (:8080) — health & metrics | metrics / operations / api-native | 6 | ⚠️ 2/6 | [cast](casts/11-native-ops.md) |
+| 12 | Embedded Console UX | Xerj Console (xerj-ux) | 3 | ✅ 3/3 | [cast](casts/12-console-ux.md) |
+
+## Failures / documented-but-unimplemented
+
+- **11-native-ops** · DOC GAP: /v1/health/ready → HTTP 404
+- **11-native-ops** · DOC GAP: /v1/cluster/health → HTTP 404
+- **11-native-ops** · DOC GAP: /v1/admin/flush → HTTP 404
+- **11-native-ops** · DOC GAP: /v1/admin/backup → HTTP 404
+
+_Each cast under `casts/` shows the exact `curl` + real response — copy into docs or drive an AISE screencast scene. Structured form in `playbooks.json`._
diff --git a/demo/playbooks/casts/01-boot-health.md b/demo/playbooks/casts/01-boot-health.md
new file mode 100644
index 000000000..2fd3ee55e
--- /dev/null
+++ b/demo/playbooks/casts/01-boot-health.md
@@ -0,0 +1,138 @@
+# Boot & health — one binary is up
+
+_Use case doc: install / quickstart_
+
+Prove the single binary is serving the ES-compatible API (:9200) and the native ops API (:8080).
+
+### ✅ cluster identity (ES-wire)
+
+```bash
+curl -s "http://localhost:9200/"
+```
+
+```json
+{
+ "name": "xerj-node-0bf25a5f",
+ "cluster_name": "xerj",
+ "cluster_uuid": "xerj-cluster-0000-0000-0000-000000000000",
+ "version": {
+ "number": "8.13.0",
+ "build_flavor": "default",
+ "build_type": "tar",
+ "build_hash": "00000000",
+ "build_date": "2024-03-22T00:00:00.000Z",
+ "build_snapshot": false,
+ "lucene_version": "9.10.0",
+ "minimum_wire_compatibility_version": "7.17.0",
+ "minimum_index_compatibility_version": "7.0.0"
+ },
+ "tagline": "You Know, for Search"
+}
+```
+
+_HTTP 200_
+
+### ✅ cluster health is green
+
+```bash
+curl -s "http://localhost:9200/_cluster/health"
+```
+
+```json
+{
+ "active_primary_shards": 14,
+ "active_shards": 14,
+ "active_shards_percent_as_number": 100,
+ "cluster_name": "xerj",
+ "delayed_unassigned_shards": 0,
+ "initializing_shards": 0,
+ "number_of_data_nodes": 1,
+ "number_of_in_flight_fetch": 0,
+ "number_of_nodes": 1,
+ "number_of_pending_tasks": 0,
+ "relocating_shards": 0,
+ "status": "green",
+ "task_max_waiting_in_queue_millis": 0,
+ "timed_out": false,
+ "unassigned_primary_shards": 0,
+ "unassigned_shards": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ nodes listing
+
+```bash
+curl -s "http://localhost:9200/_cat/nodes?v"
+```
+
+```json
+127.0.0.1 10 50 0 0.00 0.00 0.00 cdfhilmrstw * xerj-node-1
+```
+
+_HTTP 200_
+
+### ✅ native health (:8080)
+
+```bash
+curl -s "http://localhost:8080/v1/health"
+```
+
+```json
+{
+ "data": {
+ "status": "yellow",
+ "index_count": 14,
+ "total_docs": 1,
+ "version": "1.0.0-rc.1"
+ },
+ "took_ms": 0,
+ "request_id": "13729407-95fb-4967-a3a3-627fc76028cd"
+}
+```
+
+_HTTP 200_
+
+### ✅ prometheus metrics (:8080)
+
+```bash
+curl -s "http://localhost:8080/v1/metrics"
+```
+
+```json
+# HELP xerj_active_searches Number of searches currently in flight
+# TYPE xerj_active_searches gauge
+xerj_active_searches 0
+# HELP xerj_bytes_read_total Total bytes read from segment files (uncompressed)
+# TYPE xerj_bytes_read_total counter
+xerj_bytes_read_total 0
+# HELP xerj_bytes_written_total Total bytes written to segment files (uncompressed)
+# TYPE xerj_bytes_written_total counter
+xerj_bytes_written_total 0
+# HELP xerj_doc_count Total live documents across all indices
+# TYPE xerj_doc_count gauge
+xerj_doc_count 0
+# HELP xerj_docs_indexed_total Total number of documents successfully indexed
+# TYPE xerj_docs_indexed_total counter
+xerj_docs_indexed_total 0
+# HELP xerj_flush_duration_seconds Time to flush an in-memory buffer to a segment
+# TYPE xerj_flush_duration_seconds histogram
+xerj_flush_duration_seconds_bucket{le="0.01"} 0
+xerj_flush_duration_seconds_bucket{le="0.02"} 0
+xerj_flush_duration_seconds_bucket{le="0.04"} 0
+xerj_flush_duration_seconds_bucket{le="0.08"} 0
+xerj_flush_duration_seconds_bucket{le="0.16"} 0
+xerj_flush_duration_seconds_bucket{le="0.32"} 0
+xerj_flush_duration_seconds_bucket{le="0.64"} 0
+xerj_flush_duration_seconds_bucket{le="1.28"} 0
+xerj_flush_duration_seconds_bucket{le="2.56"} 0
+xerj_flush_duration_seconds_bucket{le="5.12"} 0
+xerj_flush_duration_seconds_bucket{le="10.24"} 0
+xerj_flush_duration_seconds_bucket{le="20.48"} 0
+xerj_flush_duration_seconds_b
+… (4626 more bytes)
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/02-quickstart-crud.md b/demo/playbooks/casts/02-quickstart-crud.md
new file mode 100644
index 000000000..49e0c4193
--- /dev/null
+++ b/demo/playbooks/casts/02-quickstart-crud.md
@@ -0,0 +1,118 @@
+# Quickstart — index, document, get, search
+
+_Use case doc: quickstart_
+
+Create an index with a mapping, write a document, read it back, and search it.
+
+### ✅ create index w/ mapping
+
+```bash
+curl -s -XPUT "http://localhost:9200/articles" \
+ -H 'content-type: application/json' \
+ -d '{"mappings":{"properties":{"title":{"type":"text"},"body":{"type":"text"},"views":{"type":"integer"},"tag":{"type":"keyword"}}}}'
+```
+
+```json
+{
+ "acknowledged": true,
+ "shards_acknowledged": true,
+ "index": "articles"
+}
+```
+
+_HTTP 200_
+
+### ✅ index a document
+
+```bash
+curl -s -XPUT "http://localhost:9200/articles/_doc/1" \
+ -H 'content-type: application/json' \
+ -d '{"title":"Hello Xerj","body":"one binary for search","views":42,"tag":"intro"}'
+```
+
+```json
+{
+ "_index": "articles",
+ "_id": "1",
+ "_version": 1,
+ "result": "created",
+ "_shards": {
+ "total": 1,
+ "successful": 1,
+ "failed": 0
+ },
+ "_seq_no": 1,
+ "_primary_term": 1
+}
+```
+
+_HTTP 201_
+
+### ✅ get the document
+
+```bash
+curl -s "http://localhost:9200/articles/_doc/1"
+```
+
+```json
+{
+ "_index": "articles",
+ "_id": "1",
+ "_version": 1,
+ "_seq_no": 1,
+ "_primary_term": 1,
+ "found": true,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+}
+```
+
+_HTTP 200_
+
+### ✅ search it
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"match":{"body":"binary"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "1",
+ "_index": "articles",
+ "_score": 0.28768211603164673,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+ }
+ ],
+ "max_score": 0.28768211603164673,
+ "total": {
+ "relation": "eq",
+ "value": 1
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/03-ingest-bulk.md b/demo/playbooks/casts/03-ingest-bulk.md
new file mode 100644
index 000000000..e379c5320
--- /dev/null
+++ b/demo/playbooks/casts/03-ingest-bulk.md
@@ -0,0 +1,146 @@
+# Bulk ingest — ES /_bulk wire protocol
+
+_Use case doc: ingest_
+
+Point any ES collector (Logstash/Filebeat/SDK) at Xerj — /_bulk works unchanged.
+
+### ✅ bulk index 4 docs
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_bulk" \
+ -H 'content-type: application/x-ndjson' \
+ --data-binary $'{"index":{}}\n{"title":"A","body":"alpha vector","views":10,"tag":"a"}\n{"index":{}}\n{"title":"B","body":"beta search","views":20,"tag":"b"}\n{"index":{}}\n{"title":"C","body":"gamma logs","views":30,"tag":"a"}\n{"index":{}}\n{"title":"D","body":"delta agg","views":40,"tag":"b"}\n'
+```
+
+```json
+{
+ "errors": false,
+ "items": [
+ {
+ "index": {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_primary_term": 1,
+ "_seq_no": 1782796632748670,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "118126af-ff27-4207-9dd4-8f92a18e963e",
+ "_index": "articles",
+ "_primary_term": 1,
+ "_seq_no": 1782796632748670,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "93f7e5c2-629e-4cc2-a884-7c09d50f07f0",
+ "_index": "articles",
+ "_primary_term": 1,
+ "_seq_no": 1782796632748670,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "b4adabc9-73d7-4c67-a166-2b8c29556617",
+ "_index": "articles",
+ "_primary_term": 1,
+ "_seq_no": 1782796632748670,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+
+… (111 more bytes)
+```
+
+_HTTP 200_
+
+### ✅ refresh to make searchable
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_refresh"
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ }
+}
+```
+
+_HTTP 200_
+
+### ✅ count documents
+
+```bash
+curl -s "http://localhost:9200/articles/_count"
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "count": 5
+}
+```
+
+_HTTP 200_
+
+### ✅ cat indices
+
+```bash
+curl -s "http://localhost:9200/_cat/indices?v"
+```
+
+```json
+green open .xerj_cluster_state 13562e00-3e53-4abc-93e1-485daa33ab7d 1 0 0 0
+green open .xerj_api_tokens 1b99a488-5e3d-4577-91f1-d550cebadd16 1 0 0 0
+green open .xerj_prefs 3b2f09ba-b628-4709-892d-36838e7bcc95 1 0 0 0
+green open articles 035aa409-ffd4-4900-bc11-f1ce1362704a 1 0 5 0
+green open .xerj_dashboards bf82e004-fe5e-4e3b-981f-ae7f6d9761ea 1 0 0 0
+green open .xerj_users f8914758-f9f4-4643-89f0-8cb1b6b60f7e 1 0 0 0
+green open .xerj_passkeys c12ab029-b81d-4897-bb2e-c2b044fd55df 1 0 0 0
+green open .xerj_alert_rules 0a55c41b-1850-4430-89cb-7b334bd32538 1 0 0 0
+green open .xerj_magic_links 24ca4002-e3be-4fe2-908c-bd67d6f7114e 1 0 1 0
+green open .xerj_idp_config 0b17a3f0-41d8-437b-b0ff-d8ed0b945830 1 0 0 0
+green open .xerj_sessions 37411c10-15bc-45bc-a542-b99ec41dd52a 1 0 0 0
+green open .xerj_audit 9f87223e-af48-489a-8c41-259e96006144 1 0 0 0
+green open .xerj_connections a9d1fa85-c2c0-431b-87d4-e3019f093076 1 0 0 0
+green open .xerj_alert_fires 14e14403-4005-4218-8494-c56c486ae3ae 1 0 0 0
+green open .xerj_views bfce567b-a259-4083-a8cb-02d9604e2dd3 1 0 0 0
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/04-full-text.md b/demo/playbooks/casts/04-full-text.md
new file mode 100644
index 000000000..ed6d3cc1b
--- /dev/null
+++ b/demo/playbooks/casts/04-full-text.md
@@ -0,0 +1,573 @@
+# Full-text search — the ES query families
+
+_Use case doc: queries / playbooks/full-text_
+
+The query DSL your Discover muscle memory already knows.
+
+### ✅ match
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"match":{"body":"search"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "1",
+ "_index": "articles",
+ "_score": 0.6099694967269897,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+ },
+ {
+ "_id": "118126af-ff27-4207-9dd4-8f92a18e963e",
+ "_index": "articles",
+ "_score": 0.28768211603164673,
+ "_source": {
+ "body": "beta search",
+ "tag": "b",
+ "title": "B",
+ "views": 20
+ }
+ }
+ ],
+ "max_score": 0.6099694967269897,
+ "total": {
+ "relation": "eq",
+ "value": 2
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ match_phrase
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"match_phrase":{"body":"alpha vector"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "alpha vector",
+ "tag": "a",
+ "title": "A",
+ "views": 10
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 1
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ term (keyword)
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"term":{"tag":"a"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 1.6931471824645996,
+ "_source": {
+ "body": "alpha vector",
+ "tag": "a",
+ "title": "A",
+ "views": 10
+ }
+ },
+ {
+ "_id": "93f7e5c2-629e-4cc2-a884-7c09d50f07f0",
+ "_index": "articles",
+ "_score": 1.6931471824645996,
+ "_source": {
+ "body": "gamma logs",
+ "tag": "a",
+ "title": "C",
+ "views": 30
+ }
+ }
+ ],
+ "max_score": 1.6931471824645996,
+ "total": {
+ "relation": "eq",
+ "value": 2
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ terms
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"terms":{"tag":["a","b"]}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "alpha vector",
+ "tag": "a",
+ "title": "A",
+ "views": 10
+ }
+ },
+ {
+ "_id": "118126af-ff27-4207-9dd4-8f92a18e963e",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "beta search",
+ "tag": "b",
+ "title": "B",
+ "views": 20
+ }
+ },
+ {
+ "_id": "93f7e5c2-629e-4cc2-a884-7c09d50f07f0",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "gamma logs",
+ "tag": "a",
+ "title": "C",
+ "views": 30
+ }
+ },
+ {
+ "_id": "b4adabc9-73d7-4c67-a166-2b8c29556617",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "delta agg",
+ "tag": "b",
+ "title": "D",
+ "views": 40
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 4
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ range
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"range":{"views":{"gte":20}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "1",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+ },
+ {
+ "_id": "118126af-ff27-4207-9dd4-8f92a18e963e",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "beta search",
+ "tag": "b",
+ "title": "B",
+ "views": 20
+ }
+ },
+ {
+ "_id": "93f7e5c2-629e-4cc2-a884-7c09d50f07f0",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "gamma logs",
+ "tag": "a",
+ "title": "C",
+ "views": 30
+ }
+ },
+ {
+ "_id": "b4adabc9-73d7-4c67-a166-2b8c29556617",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "delta agg",
+ "tag": "b",
+ "title": "D",
+ "views": 40
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 4
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ bool must+filter
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"bool":{"must":[{"match":{"body":"logs"}}],"filter":[{"term":{"tag":"a"}}]}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "93f7e5c2-629e-4cc2-a884-7c09d50f07f0",
+ "_index": "articles",
+ "_score": 0.9741763472557068,
+ "_source": {
+ "body": "gamma logs",
+ "tag": "a",
+ "title": "C",
+ "views": 30
+ }
+ }
+ ],
+ "max_score": 0.9741763472557068,
+ "total": {
+ "relation": "eq",
+ "value": 1
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ prefix
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"prefix":{"body":"alp"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "alpha vector",
+ "tag": "a",
+ "title": "A",
+ "views": 10
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 1
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ wildcard
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"wildcard":{"body":"sea*"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "1",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+ },
+ {
+ "_id": "118126af-ff27-4207-9dd4-8f92a18e963e",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "beta search",
+ "tag": "b",
+ "title": "B",
+ "views": 20
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 2
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ exists
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"exists":{"field":"title"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "1",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+ },
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "alpha vector",
+ "tag": "a",
+ "title": "A",
+ "views": 10
+ }
+ },
+ {
+ "_id": "118126af-ff27-4207-9dd4-8f92a18e963e",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "beta search",
+ "tag": "b",
+ "title": "B",
+ "views": 20
+ }
+ },
+ {
+ "_id": "93f7e5c2-629e-4cc2-a884-7c09d50f07f0",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "gamma logs",
+ "tag": "a",
+ "title": "C",
+ "views": 30
+ }
+ },
+ {
+ "_id": "b4adabc9-73d7-4c67-a166-2b8c29556617",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "delta agg",
+ "tag": "b",
+ "title": "D",
+ "views": 40
+ }
+ }
+ ],
+ "max_score
+… (108 more bytes)
+```
+
+_HTTP 200_
+
+### ✅ highlight + sort + _source
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"match":{"body":"vector"}},"highlight":{"fields":{"body":{}}},"sort":[{"views":"desc"}],"_source":["title","views"]}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 0.28768211603164673,
+ "_source": {
+ "title": "A",
+ "views": 10
+ },
+ "sort": [
+ 10
+ ]
+ }
+ ],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 1
+ }
+ },
+ "timed_out": false,
+ "took": 1
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/05-aggregations.md b/demo/playbooks/casts/05-aggregations.md
new file mode 100644
index 000000000..d869b77d7
--- /dev/null
+++ b/demo/playbooks/casts/05-aggregations.md
@@ -0,0 +1,418 @@
+# Aggregations — the boardroom view
+
+_Use case doc: aggregations_
+
+Metric + bucket aggregations over the live index.
+
+### ✅ terms
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"by_tag":{"terms":{"field":"tag"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "by_tag": {
+ "buckets": [
+ {
+ "doc_count": 2,
+ "key": "a"
+ },
+ {
+ "doc_count": 2,
+ "key": "b"
+ },
+ {
+ "doc_count": 1,
+ "key": "intro"
+ }
+ ],
+ "doc_count_error_upper_bound": 0,
+ "sum_other_doc_count": 0
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ stats
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"v":{"stats":{"field":"views"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "v": {
+ "avg": 28.4,
+ "count": 5,
+ "max": 42,
+ "min": 10,
+ "sum": 142
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ sum / avg / max / min
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"s":{"sum":{"field":"views"}},"a":{"avg":{"field":"views"}},"mx":{"max":{"field":"views"}},"mn":{"min":{"field":"views"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "a": {
+ "value": 28.4
+ },
+ "mn": {
+ "value": 10
+ },
+ "mx": {
+ "value": 42
+ },
+ "s": {
+ "value": 142
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ cardinality
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"uniq":{"cardinality":{"field":"tag"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "uniq": {
+ "value": 3
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ value_count
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"c":{"value_count":{"field":"views"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "c": {
+ "value": 5
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ histogram
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"h":{"histogram":{"field":"views","interval":10}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "h": {
+ "buckets": [
+ {
+ "doc_count": 1,
+ "key": 10
+ },
+ {
+ "doc_count": 1,
+ "key": 20
+ },
+ {
+ "doc_count": 1,
+ "key": 30
+ },
+ {
+ "doc_count": 2,
+ "key": 40
+ }
+ ]
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ range
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"r":{"range":{"field":"views","ranges":[{"to":20},{"from":20}]}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "r": {
+ "buckets": [
+ {
+ "doc_count": 1,
+ "key": "*-20.0",
+ "to": 20
+ },
+ {
+ "doc_count": 4,
+ "from": 20,
+ "key": "20.0-*"
+ }
+ ]
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ percentiles
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"p":{"percentiles":{"field":"views"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "p": {
+ "values": {
+ "1.0": 10.4,
+ "25.0": 20,
+ "5.0": 12,
+ "50.0": 30,
+ "75.0": 40,
+ "95.0": 41.6,
+ "99.0": 41.92
+ }
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ terms + nested avg
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"by_tag":{"terms":{"field":"tag"},"aggs":{"avg_views":{"avg":{"field":"views"}}}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "by_tag": {
+ "buckets": [
+ {
+ "avg_views": {
+ "value": 20
+ },
+ "doc_count": 2,
+ "key": "a"
+ },
+ {
+ "avg_views": {
+ "value": 30
+ },
+ "doc_count": 2,
+ "key": "b"
+ },
+ {
+ "avg_views": {
+ "value": 42
+ },
+ "doc_count": 1,
+ "key": "intro"
+ }
+ ],
+ "doc_count_error_upper_bound": 0,
+ "sum_other_doc_count": 0
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/06-vector-search.md b/demo/playbooks/casts/06-vector-search.md
new file mode 100644
index 000000000..efe63d5f2
--- /dev/null
+++ b/demo/playbooks/casts/06-vector-search.md
@@ -0,0 +1,183 @@
+# Vector search — kNN, no Pinecone
+
+_Use case doc: vectors / playbooks/vector-search_
+
+dense_vector field + kNN retrieval are first-class in the same engine.
+
+### ✅ create vector index
+
+```bash
+curl -s -XPUT "http://localhost:9200/vstore" \
+ -H 'content-type: application/json' \
+ -d '{"mappings":{"properties":{"text":{"type":"text"},"embedding":{"type":"dense_vector","dims":4}}}}'
+```
+
+```json
+{
+ "acknowledged": true,
+ "shards_acknowledged": true,
+ "index": "vstore"
+}
+```
+
+_HTTP 200_
+
+### ✅ bulk index vectors
+
+```bash
+curl -s -XPOST "http://localhost:9200/vstore/_bulk" \
+ -H 'content-type: application/x-ndjson' \
+ --data-binary $'{"index":{}}\n{"text":"red apple","embedding":[0.9,0.1,0.0,0.1]}\n{"index":{}}\n{"text":"green pear","embedding":[0.1,0.9,0.1,0.0]}\n{"index":{}}\n{"text":"blue car","embedding":[0.0,0.1,0.9,0.1]}\n'
+```
+
+```json
+{
+ "errors": false,
+ "items": [
+ {
+ "index": {
+ "_id": "f11a9068-5187-409d-ace8-75612532fe81",
+ "_index": "vstore",
+ "_primary_term": 1,
+ "_seq_no": 1782796632941008,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "07c6f744-6e83-4bee-97ed-a258df49532d",
+ "_index": "vstore",
+ "_primary_term": 1,
+ "_seq_no": 1782796632941008,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "34647d96-e2fa-4dcb-952f-182cc70bacd8",
+ "_index": "vstore",
+ "_primary_term": 1,
+ "_seq_no": 1782796632941008,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ }
+ ],
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ refresh
+
+```bash
+curl -s -XPOST "http://localhost:9200/vstore/_refresh"
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ }
+}
+```
+
+_HTTP 200_
+
+### ✅ kNN nearest to [0.9,0.1,0,0.1]
+
+```bash
+curl -s -XPOST "http://localhost:9200/vstore/_search" \
+ -H 'content-type: application/json' \
+ -d '{"knn":{"field":"embedding","query_vector":[0.9,0.1,0,0.1],"k":2,"num_candidates":10}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "f11a9068-5187-409d-ace8-75612532fe81",
+ "_index": "vstore",
+ "_score": 1,
+ "_source": {
+ "embedding": [
+ 0.9,
+ 0.1,
+ 0,
+ 0.1
+ ],
+ "text": "red apple"
+ }
+ },
+ {
+ "_id": "07c6f744-6e83-4bee-97ed-a258df49532d",
+ "_index": "vstore",
+ "_score": 0.608433723449707,
+ "_source": {
+ "embedding": [
+ 0.1,
+ 0.9,
+ 0.1,
+ 0
+ ],
+ "text": "green pear"
+ }
+ },
+ {
+ "_id": "34647d96-e2fa-4dcb-952f-182cc70bacd8",
+ "_index": "vstore",
+ "_score": 0.5120481848716736,
+ "_source": {
+ "embedding": [
+ 0,
+ 0.1,
+ 0.9,
+ 0.1
+ ],
+ "text": "blue car"
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 3
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/07-analyzers.md b/demo/playbooks/casts/07-analyzers.md
new file mode 100644
index 000000000..327551ad7
--- /dev/null
+++ b/demo/playbooks/casts/07-analyzers.md
@@ -0,0 +1,120 @@
+# Analyzers — _analyze
+
+_Use case doc: analyzers_
+
+Inspect tokenization the way ES does.
+
+### ✅ standard analyzer
+
+```bash
+curl -s -XPOST "http://localhost:9200/_analyze" \
+ -H 'content-type: application/json' \
+ -d '{"analyzer":"standard","text":"The Quick, Brown Fox!"}'
+```
+
+```json
+{
+ "tokens": [
+ {
+ "end_offset": 3,
+ "position": 0,
+ "start_offset": 0,
+ "token": "the",
+ "type": "word"
+ },
+ {
+ "end_offset": 9,
+ "position": 1,
+ "start_offset": 4,
+ "token": "quick",
+ "type": "word"
+ },
+ {
+ "end_offset": 16,
+ "position": 2,
+ "start_offset": 11,
+ "token": "brown",
+ "type": "word"
+ },
+ {
+ "end_offset": 20,
+ "position": 3,
+ "start_offset": 17,
+ "token": "fox",
+ "type": "word"
+ }
+ ]
+}
+```
+
+_HTTP 200_
+
+### ✅ keyword analyzer
+
+```bash
+curl -s -XPOST "http://localhost:9200/_analyze" \
+ -H 'content-type: application/json' \
+ -d '{"analyzer":"keyword","text":"The Quick, Brown Fox!"}'
+```
+
+```json
+{
+ "tokens": [
+ {
+ "end_offset": 21,
+ "position": 0,
+ "start_offset": 0,
+ "token": "The Quick, Brown Fox!",
+ "type": "word"
+ }
+ ]
+}
+```
+
+_HTTP 200_
+
+### ✅ whitespace analyzer
+
+```bash
+curl -s -XPOST "http://localhost:9200/_analyze" \
+ -H 'content-type: application/json' \
+ -d '{"analyzer":"whitespace","text":"The Quick, Brown Fox!"}'
+```
+
+```json
+{
+ "tokens": [
+ {
+ "end_offset": 3,
+ "position": 0,
+ "start_offset": 0,
+ "token": "The",
+ "type": "word"
+ },
+ {
+ "end_offset": 10,
+ "position": 1,
+ "start_offset": 4,
+ "token": "Quick,",
+ "type": "word"
+ },
+ {
+ "end_offset": 16,
+ "position": 2,
+ "start_offset": 11,
+ "token": "Brown",
+ "type": "word"
+ },
+ {
+ "end_offset": 21,
+ "position": 3,
+ "start_offset": 17,
+ "token": "Fox!",
+ "type": "word"
+ }
+ ]
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/08-mappings-templates-aliases.md b/demo/playbooks/casts/08-mappings-templates-aliases.md
new file mode 100644
index 000000000..5f04e96a5
--- /dev/null
+++ b/demo/playbooks/casts/08-mappings-templates-aliases.md
@@ -0,0 +1,100 @@
+# Mappings, templates & aliases
+
+_Use case doc: config / operations_
+
+Schema introspection + index templates + aliases — ES-identical.
+
+### ✅ get mapping
+
+```bash
+curl -s "http://localhost:9200/articles/_mapping"
+```
+
+```json
+{
+ "articles": {
+ "mappings": {
+ "properties": {
+ "body": {
+ "type": "text"
+ },
+ "tag": {
+ "type": "keyword"
+ },
+ "title": {
+ "type": "text"
+ },
+ "views": {
+ "type": "integer"
+ }
+ }
+ }
+ }
+}
+```
+
+_HTTP 200_
+
+### ✅ put index template
+
+```bash
+curl -s -XPUT "http://localhost:9200/_index_template/logs_tpl" \
+ -H 'content-type: application/json' \
+ -d '{"index_patterns":["logs-*"],"template":{"mappings":{"properties":{"@timestamp":{"type":"date"},"level":{"type":"keyword"},"msg":{"type":"text"}}}}}'
+```
+
+```json
+{
+ "acknowledged": true
+}
+```
+
+_HTTP 200_
+
+### ✅ add alias
+
+```bash
+curl -s -XPOST "http://localhost:9200/_aliases" \
+ -H 'content-type: application/json' \
+ -d '{"actions":[{"add":{"index":"articles","alias":"articles_live"}}]}'
+```
+
+```json
+{
+ "acknowledged": true
+}
+```
+
+_HTTP 200_
+
+### ✅ search via alias
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles_live/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"query":{"match_all":{}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/09-log-analytics.md b/demo/playbooks/casts/09-log-analytics.md
new file mode 100644
index 000000000..86fe27ab1
--- /dev/null
+++ b/demo/playbooks/casts/09-log-analytics.md
@@ -0,0 +1,246 @@
+# Log analytics — Splunk/Kibana workload
+
+_Use case doc: playbooks/log-analytics_
+
+Template-driven log index, time-series + level breakdown aggregations.
+
+### ✅ bulk ingest logs (template applies)
+
+```bash
+curl -s -XPOST "http://localhost:9200/logs-2026-04/_bulk" \
+ -H 'content-type: application/x-ndjson' \
+ --data-binary $'{"index":{}}\n{"@timestamp":"2026-04-26T19:47:24Z","level":"info","msg":"request ok","svc":"api"}\n{"index":{}}\n{"@timestamp":"2026-04-26T19:47:24Z","level":"error","msg":"timeout","svc":"api"}\n{"index":{}}\n{"@timestamp":"2026-04-26T19:47:24Z","level":"error","msg":"5xx upstream","svc":"web"}\n{"index":{}}\n{"@timestamp":"2026-04-26T19:47:24Z","level":"warn","msg":"slow query","svc":"db"}\n'
+```
+
+```json
+{
+ "errors": false,
+ "items": [
+ {
+ "index": {
+ "_id": "b91fb60d-4139-4f60-b77f-f8fd8f7b1b08",
+ "_index": "logs-2026-04",
+ "_primary_term": 1,
+ "_seq_no": 1782796633012746,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "68a7e704-14b3-49b7-8fff-6360046c5b93",
+ "_index": "logs-2026-04",
+ "_primary_term": 1,
+ "_seq_no": 1782796633012746,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "6bb266ed-93fe-41ce-9d66-136ab8fe87ba",
+ "_index": "logs-2026-04",
+ "_primary_term": 1,
+ "_seq_no": 1782796633012746,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "_version": 1,
+ "result": "created",
+ "status": 201
+ }
+ },
+ {
+ "index": {
+ "_id": "39294ad5-3bc2-4f8a-94b4-4a318573d130",
+ "_index": "logs-2026-04",
+ "_primary_term": 1,
+ "_seq_no": 1782796633012746,
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "
+… (127 more bytes)
+```
+
+_HTTP 200_
+
+### ✅ refresh
+
+```bash
+curl -s -XPOST "http://localhost:9200/logs-2026-04/_refresh"
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "successful": 1,
+ "total": 1
+ }
+}
+```
+
+_HTTP 200_
+
+### ✅ errors only (bool filter)
+
+```bash
+curl -s -XPOST "http://localhost:9200/logs-2026-04/_search" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"term":{"level":"error"}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "68a7e704-14b3-49b7-8fff-6360046c5b93",
+ "_index": "logs-2026-04",
+ "_score": 1.6931471824645996,
+ "_source": {
+ "@timestamp": "2026-04-26T19:47:24Z",
+ "level": "error",
+ "msg": "timeout",
+ "svc": "api"
+ }
+ },
+ {
+ "_id": "6bb266ed-93fe-41ce-9d66-136ab8fe87ba",
+ "_index": "logs-2026-04",
+ "_score": 1.6931471824645996,
+ "_source": {
+ "@timestamp": "2026-04-26T19:47:24Z",
+ "level": "error",
+ "msg": "5xx upstream",
+ "svc": "web"
+ }
+ }
+ ],
+ "max_score": 1.6931471824645996,
+ "total": {
+ "relation": "eq",
+ "value": 2
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ count by level
+
+```bash
+curl -s -XPOST "http://localhost:9200/logs-2026-04/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"aggs":{"by_level":{"terms":{"field":"level"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "by_level": {
+ "buckets": [
+ {
+ "doc_count": 2,
+ "key": "error"
+ },
+ {
+ "doc_count": 1,
+ "key": "info"
+ },
+ {
+ "doc_count": 1,
+ "key": "warn"
+ }
+ ],
+ "doc_count_error_upper_bound": 0,
+ "sum_other_doc_count": 0
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 4
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ errors over time (date_histogram)
+
+```bash
+curl -s -XPOST "http://localhost:9200/logs-2026-04/_search" \
+ -H 'content-type: application/json' \
+ -d '{"size":0,"query":{"term":{"level":"error"}},"aggs":{"t":{"date_histogram":{"field":"@timestamp","calendar_interval":"day"}}}}'
+```
+
+```json
+{
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "aggregations": {
+ "t": {
+ "buckets": [
+ {
+ "doc_count": 2,
+ "key": 1777161600000,
+ "key_as_string": "2026-04-26T00:00:00.000Z"
+ }
+ ]
+ }
+ },
+ "hits": {
+ "hits": [],
+ "max_score": null,
+ "total": {
+ "relation": "eq",
+ "value": 2
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/10-migration-es.md b/demo/playbooks/casts/10-migration-es.md
new file mode 100644
index 000000000..7a91d3c1f
--- /dev/null
+++ b/demo/playbooks/casts/10-migration-es.md
@@ -0,0 +1,143 @@
+# Migration from Elasticsearch — drop-in parity
+
+_Use case doc: migration-from-es_
+
+The exact ES request bodies return ES-shaped responses — clients, Logstash, Kibana keep working.
+
+### ✅ ES version handshake (Kibana checks this)
+
+```bash
+curl -s "http://localhost:9200/"
+```
+
+```json
+{
+ "name": "xerj-node-66d6c077",
+ "cluster_name": "xerj",
+ "cluster_uuid": "xerj-cluster-0000-0000-0000-000000000000",
+ "version": {
+ "number": "8.13.0",
+ "build_flavor": "default",
+ "build_type": "tar",
+ "build_hash": "00000000",
+ "build_date": "2024-03-22T00:00:00.000Z",
+ "build_snapshot": false,
+ "lucene_version": "9.10.0",
+ "minimum_wire_compatibility_version": "7.17.0",
+ "minimum_index_compatibility_version": "7.0.0"
+ },
+ "tagline": "You Know, for Search"
+}
+```
+
+_HTTP 200_
+
+### ✅ _cat/indices (ops tooling)
+
+```bash
+curl -s "http://localhost:9200/_cat/indices?v"
+```
+
+```json
+green open .xerj_cluster_state 96c36337-d6b1-47f9-9905-e356b6cecb04 1 0 0 0
+green open .xerj_api_tokens 1899253e-420a-40a1-af69-6bee59291936 1 0 0 0
+green open .xerj_prefs 12f27538-0e09-44e0-aa4b-a0bf44914b23 1 0 0 0
+green open logs-2026-04 f00d351d-25ca-465f-99d6-945449e0985e 1 0 4 0
+green open articles 1d2028e5-ec5e-4841-bb85-3dc07ba0ee45 1 0 5 0
+green open .xerj_dashboards c1be10bb-e64c-4474-bb9b-1314b7a507b4 1 0 0 0
+green open .xerj_users c8abbbd2-e317-4e87-9ee4-1cb3f76a8bd5 1 0 0 0
+green open .xerj_passkeys ab84e4b4-c7f5-477a-8adc-bcdd2a46822c 1 0 0 0
+green open vstore a0fc834d-e792-43ad-ab29-ab698d0d7124 1 0 3 0
+green open .xerj_alert_rules 175ed6ba-f804-4b85-b402-b28d4c02ff8d 1 0 0 0
+green open .xerj_magic_links 5d8ee201-a207-4952-ae6f-f9d013978b41 1 0 1 0
+green open .xerj_idp_config 9c1e2518-68ef-495e-8e9f-70588dac66cc 1 0 0 0
+green open .xerj_sessions 239d4dc1-fa8a-49de-8e5c-36d451fc3907 1 0 0 0
+green open .xerj_audit 3fd87f94-f6a7-4dda-b7c0-5ee14d7b0c3a 1 0 0 0
+green open .xerj_connections 776f68be-7795-4db5-8c7c-029ce4d03fcd 1 0 0 0
+green open .xerj_alert_fires e5705c2b-ee99-4d42-b04a-0733bbc0b421 1 0 0 0
+green open .xerj_views 3293e930-eb61-4342-88b7-d2ac2347ee69 1 0 0 0
+```
+
+_HTTP 200_
+
+### ✅ scroll API (pagination)
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_search?scroll=1m" \
+ -H 'content-type: application/json' \
+ -d '{"size":2,"query":{"match_all":{}}}'
+```
+
+```json
+{
+ "_scroll_id": "56506e1c-84f3-4665-88f1-f7fcf5ddedfa",
+ "_shards": {
+ "failed": 0,
+ "skipped": 0,
+ "successful": 1,
+ "total": 1
+ },
+ "hits": {
+ "hits": [
+ {
+ "_id": "1",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "one binary for search",
+ "tag": "intro",
+ "title": "Hello Xerj",
+ "views": 42
+ }
+ },
+ {
+ "_id": "aab064f6-eecd-4b53-a75c-bf507f99edae",
+ "_index": "articles",
+ "_score": 1,
+ "_source": {
+ "body": "alpha vector",
+ "tag": "a",
+ "title": "A",
+ "views": 10
+ }
+ }
+ ],
+ "max_score": 1,
+ "total": {
+ "relation": "eq",
+ "value": 5
+ }
+ },
+ "timed_out": false,
+ "took": 0
+}
+```
+
+_HTTP 200_
+
+### ✅ _delete_by_query
+
+```bash
+curl -s -XPOST "http://localhost:9200/articles/_delete_by_query" \
+ -H 'content-type: application/json' \
+ -d '{"query":{"term":{"tag":"b"}}}'
+```
+
+```json
+{
+ "batches": 1,
+ "deleted": 2,
+ "failures": [],
+ "noops": 0,
+ "requests_per_second": -1,
+ "throttled_millis": 0,
+ "throttled_until_millis": 0,
+ "timed_out": false,
+ "took": 0,
+ "total": 2,
+ "version_conflicts": 0
+}
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/casts/11-native-ops.md b/demo/playbooks/casts/11-native-ops.md
new file mode 100644
index 000000000..d88e2fd58
--- /dev/null
+++ b/demo/playbooks/casts/11-native-ops.md
@@ -0,0 +1,118 @@
+# Native ops API (:8080) — health & metrics
+
+_Use case doc: metrics / operations / api-native_
+
+The native v1 surface for ops. NOTE: this binary implements health + metrics; the rest of the documented /v1 API is not yet live (captured as gaps).
+
+### ✅ native health
+
+```bash
+curl -s "http://localhost:8080/v1/health"
+```
+
+```json
+{
+ "data": {
+ "status": "yellow",
+ "index_count": 17,
+ "total_docs": 11,
+ "version": "1.0.0-rc.1"
+ },
+ "took_ms": 0,
+ "request_id": "d64f1a4e-098c-4b04-8e97-586c978341c2"
+}
+```
+
+_HTTP 200_
+
+### ✅ prometheus scrape
+
+```bash
+curl -s "http://localhost:8080/v1/metrics"
+```
+
+```json
+# HELP xerj_active_searches Number of searches currently in flight
+# TYPE xerj_active_searches gauge
+xerj_active_searches 0
+# HELP xerj_bytes_read_total Total bytes read from segment files (uncompressed)
+# TYPE xerj_bytes_read_total counter
+xerj_bytes_read_total 0
+# HELP xerj_bytes_written_total Total bytes written to segment files (uncompressed)
+# TYPE xerj_bytes_written_total counter
+xerj_bytes_written_total 0
+# HELP xerj_doc_count Total live documents across all indices
+# TYPE xerj_doc_count gauge
+xerj_doc_count 0
+# HELP xerj_docs_indexed_by_index_total Documents indexed, labelled by index name
+# TYPE xerj_docs_indexed_by_index_total counter
+xerj_docs_indexed_by_index_total{index="articles"} 1
+# HELP xerj_docs_indexed_total Total number of documents successfully indexed
+# TYPE xerj_docs_indexed_total counter
+xerj_docs_indexed_total 1
+# HELP xerj_flush_duration_seconds Time to flush an in-memory buffer to a segment
+# TYPE xerj_flush_duration_seconds histogram
+xerj_flush_duration_seconds_bucket{le="0.01"} 0
+xerj_flush_duration_seconds_bucket{le="0.02"} 0
+xerj_flush_duration_seconds_bucket{le="0.04"} 0
+xerj_flush_duration_seconds_bucket{le="0.08"} 0
+xerj_flush_duration_seconds_bucket{le="0.16"} 0
+xerj_flush_duration_seconds_bucket{le="0.32"} 0
+xerj_flush_duration_seconds_bucket{le="0.64"} 0
+xerj_flush_duration_seconds_bucket{le="1.28"} 0
+xerj_flush_duration_seconds_bucket{le="2
+… (5150 more bytes)
+```
+
+_HTTP 200_
+
+### ❌ DOC GAP: /v1/health/ready
+
+```bash
+curl -s "http://localhost:8080/v1/health/ready"
+```
+
+```json
+
+```
+
+_HTTP 404_
+
+### ❌ DOC GAP: /v1/cluster/health
+
+```bash
+curl -s "http://localhost:8080/v1/cluster/health"
+```
+
+```json
+
+```
+
+_HTTP 404_
+
+### ❌ DOC GAP: /v1/admin/flush
+
+```bash
+curl -s -XPOST "http://localhost:8080/v1/admin/flush"
+```
+
+```json
+
+```
+
+_HTTP 404_
+
+### ❌ DOC GAP: /v1/admin/backup
+
+```bash
+curl -s -XPOST "http://localhost:8080/v1/admin/backup" \
+ -H 'content-type: application/json' \
+ -d '{}'
+```
+
+```json
+
+```
+
+_HTTP 404_
+
diff --git a/demo/playbooks/casts/12-console-ux.md b/demo/playbooks/casts/12-console-ux.md
new file mode 100644
index 000000000..55b002fd8
--- /dev/null
+++ b/demo/playbooks/casts/12-console-ux.md
@@ -0,0 +1,133 @@
+# Embedded Console UX
+
+_Use case doc: Xerj Console (xerj-ux)_
+
+The console SPA ships inside the binary and is served at /_xerj-console/.
+
+### ✅ console SPA shell
+
+```bash
+curl -s "http://localhost:9200/_xerj-console/"
+```
+
+```json
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Xerj Console · typography-first observability for Xerj</title>
+<meta name="color-scheme" content="dark light">
+<script>
+ // Theme bootstrap — runs before CSS to prevent a flash of wrong theme.
+ (function () {
+ var t = localStorage.getItem('xerj.theme');
+ if (t !== 'day' && t !== 'night') t = 'night';
+ document.documentElement.setAttribute('data-theme', t);
+ })();
+</script>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Big+Shoulders+Display:wght@400;700;800;900&family=JetBrains+Mono:wght@400;500;700&family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="assets/tokens.css">
+<link rel="stylesheet" href="assets/base.css">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='13' font-family='monospace' font-size='14' font-weight='900' fill='%23EEBB00'%3Ez%3C/text%3E%3C/svg%3E">
+</head>
+<body>
+<div id="app" aria-busy="true"></div>
+<!--
+ Auth guard. Hits /_xerj-console/api/v1/me before app.js runs. On 401 we
+ redirect to /_xerj-console/login (or /_xerj-console/setup when this is a fresh
+ install — th
+… (2291 more bytes)
+```
+
+_HTTP 200_
+
+### ✅ console app bundle
+
+```bash
+curl -s "http://localhost:9200/_xerj-console/src/app.js"
+```
+
+```json
+// ============================================================
+// XERJ.ai — Bootstrap + router + layout engine
+//
+// One render loop. Edit mode layers drag/resize/remove/add on
+// top of the same render — no separate editor routes.
+// ============================================================
+
+import { registry, defaults, SECTIONS, DASHBOARD_GROUPS, dashboardsInSection } from './dashboards/registry.js';
+import { Nav, SceneHeader, TimeCtrl, RefreshCtrl, FilterBar, ClusterCtrl, SavedViews, Footer, MobileCtrl } from './ux/chrome.js';
+import { query, dataSourceStatus } from './data/query.js';
+import { chartTypes, chartTypeList } from './ux/chart-types.js';
+import { esc } from './ux/text.js';
+import { mockSearch } from './data/mock.js';
+import { hitsToCsv, downloadText, svgToPng } from './data/export.js';
+import {
+ mergedDashboards, renameDashboard, reorderDashboards, setHidden,
+ createUserDashboard, deleteUserDashboard, isUserDash, resetAll as resetDashboards,
+} from './data/dashboard-store.js';
+import {
+ listClusters, listIndices, listFields, listClustersSync,
+ defaultClusterId, setDefaultCluster,
+} from './data/data-sources.js';
+
+// ---------- state -----------------------------------------
+const LS = {
+ theme: 'xerj.theme',
+ time: 'xerj.time',
+ edit: 'xerj.edit',
+ search: 'xerj.search',
+ refresh: 'xerj.refresh',
+ cluster: 'xerj.cluster',
+ views: 'xerj.vi
+… (47867 more bytes)
+```
+
+_HTTP 200_
+
+### ✅ first-launch setup page
+
+```bash
+curl -s "http://localhost:9200/_xerj-console/setup"
+```
+
+```json
+<!doctype html>
+<html lang="en" data-theme="night">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Xerj Console · setup</title>
+<meta name="color-scheme" content="dark light">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Big+Shoulders+Display:wght@800;900&family=JetBrains+Mono:wght@400;500&family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="assets/tokens.css">
+<link rel="stylesheet" href="assets/base.css">
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='13' font-family='monospace' font-size='14' font-weight='900' fill='%23EEBB00'%3Ez%3C/text%3E%3C/svg%3E">
+<style>
+ body {
+ min-height: 100vh; display: flex; align-items: center; justify-content: center;
+ padding: 2rem;
+ }
+ .auth-card {
+ background: var(--bg-surface, #15171a);
+ border: 1px solid var(--border, #2a2d33);
+ border-radius: 8px; padding: 2rem;
+ max-width: 480px; width: 100%;
+ color: var(--fg, #e6e8eb);
+ }
+ .auth-card h1 {
+ font-family: 'Big Shoulders Display', sans-serif;
+ font-weight: 900; font-size: 2.25rem; letter-spacing: -0.02em;
+ margin: 0 0 .5rem; color: #EEBB00;
+ }
+ .auth-card
+… (6914 more bytes)
+```
+
+_HTTP 200_
+
diff --git a/demo/playbooks/playbooks.json b/demo/playbooks/playbooks.json
new file mode 100644
index 000000000..54d52e42c
--- /dev/null
+++ b/demo/playbooks/playbooks.json
@@ -0,0 +1,513 @@
+[
+ {
+ "id": "01-boot-health",
+ "doc": "install / quickstart",
+ "title": "Boot & health — one binary is up",
+ "steps": [
+ {
+ "label": "cluster identity (ES-wire)",
+ "cmd": "curl -s \"http://localhost:9200/\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"name\": \"xerj-node-0bf25a5f\",\n \"cluster_name\": \"xerj\",\n \"cluster_uuid\": \"xerj-cluster-0000-0000-0000-000000000000\",\n \"version\": {\n \"number\": \"8.13.0\",\n \"build_flavor\": \"default\",\n \"build_type\": \"tar\",\n \"build_hash\": \"00000000\",\n \"build_date\": \"2024-03-22T00:00:00.000Z\",\n \"build_snapshot\": false,\n \"lucene_version\": \"9.10.0\",\n \"minimum_wire_compatibility_version\": \"7.17.0\",\n \"minimum_index_compatibility_version\": \"7.0.0\"\n },\n \"tagline\": \"You Know, for Search\"\n}"
+ },
+ {
+ "label": "cluster health is green",
+ "cmd": "curl -s \"http://localhost:9200/_cluster/health\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"active_primary_shards\": 14,\n \"active_shards\": 14,\n \"active_shards_percent_as_number\": 100,\n \"cluster_name\": \"xerj\",\n \"delayed_unassigned_shards\": 0,\n \"initializing_shards\": 0,\n \"number_of_data_nodes\": 1,\n \"number_of_in_flight_fetch\": 0,\n \"number_of_nodes\": 1,\n \"number_of_pending_tasks\": 0,\n \"relocating_shards\": 0,\n \"status\": \"green\",\n \"task_max_waiting_in_queue_millis\": 0,\n \"timed_out\": false,\n \"unassigned_primary_shards\": 0,\n \"unassigned_shards\": 0\n}"
+ },
+ {
+ "label": "nodes listing",
+ "cmd": "curl -s \"http://localhost:9200/_cat/nodes?v\"",
+ "status": 200,
+ "pass": true,
+ "output": "127.0.0.1 10 50 0 0.00 0.00 0.00 cdfhilmrstw * xerj-node-1"
+ },
+ {
+ "label": "native health (:8080)",
+ "cmd": "curl -s \"http://localhost:8080/v1/health\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"data\": {\n \"status\": \"yellow\",\n \"index_count\": 14,\n \"total_docs\": 1,\n \"version\": \"1.0.0-rc.1\"\n },\n \"took_ms\": 0,\n \"request_id\": \"13729407-95fb-4967-a3a3-627fc76028cd\"\n}"
+ },
+ {
+ "label": "prometheus metrics (:8080)",
+ "cmd": "curl -s \"http://localhost:8080/v1/metrics\"",
+ "status": 200,
+ "pass": true,
+ "output": "# HELP xerj_active_searches Number of searches currently in flight\n# TYPE xerj_active_searches gauge\nxerj_active_searches 0\n# HELP xerj_bytes_read_total Total bytes read from segment files (uncompressed)\n# TYPE xerj_bytes_read_total counter\nxerj_bytes_read_total 0\n# HELP xerj_bytes_written_total Total bytes written to segment files (uncompressed)\n# TYPE xerj_bytes_written_total counter\nxerj_bytes_written_total 0\n# HELP xerj_doc_count Total live documents across all indices\n# TYPE xerj_doc_count gauge\nxerj_doc_count 0\n# HELP xerj_docs_indexed_total Total number of documents successfully indexed\n# TYPE xerj_docs_indexed_total counter\nxerj_docs_indexed_total 0\n# HELP xerj_flush_duration_seconds Time to flush an in-memory buffer to a segment\n# TYPE xerj_flush_duration_seconds histogram\nxerj_flush_duration_seconds_bucket{le=\"0.01\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.02\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.04\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.08\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.16\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.32\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.64\"} 0\nxerj_flush_duration_seconds_bucket{le=\"1.28\"} 0\nxerj_flush_duration_seconds_bucket{le=\"2.56\"} 0\nxerj_flush_duration_seconds_bucket{le=\"5.12\"} 0\nxerj_flush_duration_seconds_bucket{le=\"10.24\"} 0\nxerj_flush_duration_seconds_bucket{le=\"20.48\"} 0\nxerj_flush_duration_seconds_bucket{le=\"40.96\"} 0\nxerj_flush_duration_seconds_bucket{le=\"81.92\"} 0\nxerj_flush_duration_seconds_bucket{le=\"163.84\"} 0\nxerj_flush_duration_seconds_bucket{le=\"+Inf\"} 0\nxerj_flush_duration_seconds_sum 0\nxerj_flush_duration_seconds_count 0\n# HELP xerj_index_latency_seconds End-to-end document indexing latency\n# TYPE xerj_index_latency_seconds histogram\nxerj_index_latency_seconds_bucket{le=\"0.0005\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.001\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.002\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.004\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.008\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.016\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.032\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.064\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.128\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.256\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.512\"} 0\nxerj_index_latency_seconds_bucket{le=\"1.024\"} 0\nxerj_index_latency_seconds_bucket{le=\"2.048\"} 0\nxerj_index_latency_seconds_bucket{le=\"4.096\"} 0\nxerj_index_latency_seconds_bucket{le=\"8.192\"} 0\nxerj_index_latency_seconds_bucket{le=\"+Inf\"} 0\nxerj_index_latency_seconds_sum 0\nxerj_index_latency_seconds_count 0\n# HELP xerj_memory_usage_bytes Approximate engine memory usage in bytes\n# TYPE xerj_memory_usage_bytes gauge\nxerj_memory_usage_bytes 0\n# HELP xerj_merge_duration_seconds Time to complete a segment merge operation\n# TYPE xerj_merge_duration_seconds histogram\nxerj_merge_duration_seconds_bucket{le=\"0.01\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.02\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.04\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.08\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.16\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.32\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.64\"} 0\nxerj_merge_duration_seconds_bucket{le=\"1.28\"} 0\nxerj_merge_duration_seconds_bucket{le=\"2.56\"} 0\nxerj_merge_duration_seconds_bucket{le=\"5.12\"} 0\nxerj_merge_duration_seconds_bucket{le=\"10.24\"} 0\nxerj_merge_duration_seconds_bucket{le=\"20.48\"} 0\nxerj_merge_duration_seconds_bucket{le=\"40.96\"} 0\nxerj_merge_duration_seconds_bucket{le=\"81.92\"} 0\nxerj_merge_duration_seconds_bucket{le=\"163.84\"} 0\nxerj_merge_duration_seconds_bucket{le=\"+Inf\"} 0\nxerj_merge_duration_seconds_sum 0\nxerj_merge_duration_seconds_count 0\n# HELP xerj_queries_executed_total Total number of search queries executed\n# TYPE xerj_queries_executed_total counter\nxerj_queries_executed_total 0\n# HELP xerj_query_latency_seconds End-to-end query latency\n# TYPE xerj_query_latency_seconds histogram\nxerj_query_latency_seconds_bucket{le=\"0.0005\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.001\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.002\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.004\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.008\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.016\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.032\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.064\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.128\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.256\"} 0\nxerj_query_latency_seconds_bucket{le=\"0.512\"} 0\nxerj_query_latency_seconds_bucket{le=\"1.024\"} 0\nxerj_query_latency_seconds_bucket{le=\"2.048\"} 0\nxerj_query_latency_seconds_bucket{le=\"4.096\"} 0\nxerj_query_latency_seconds_bucket{le=\"8.192\"} 0\nxerj_query_latency_seconds_bucket{le=\"+Inf\"} 0\nxerj_query_latency_seconds_sum 0\nxerj_query_latency_seconds_count 0\n# HELP xerj_segment_count Number of open segments across all indices\n# TYPE xerj_segment_count gauge\nxerj_segment_count 0\n# HELP xerj_wal_size_bytes Current WAL size on disk in bytes\n# TYPE xerj_wal_size_bytes gauge\nxerj_wal_size_bytes 0\n# HELP xerj_wal_write_latency_seconds WAL write latency\n# TYPE xerj_wal_write_latency_seconds histogram\nxerj_wal_write_latency_seconds_bucket{le=\"0.0005\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.001\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.002\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.004\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.008\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.016\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.032\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.064\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.128\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.256\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.512\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"1.024\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"2.048\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"4.096\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"8.192\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"+Inf\"} 0\nxerj_wal_write_latency_seconds_sum 0\nxerj_wal_write_latency_seconds_count 0"
+ }
+ ]
+ },
+ {
+ "id": "02-quickstart-crud",
+ "doc": "quickstart",
+ "title": "Quickstart — index, document, get, search",
+ "steps": [
+ {
+ "label": "create index w/ mapping",
+ "cmd": "curl -s -XPUT \"http://localhost:9200/articles\" \\\n -H 'content-type: application/json' \\\n -d '{\"mappings\":{\"properties\":{\"title\":{\"type\":\"text\"},\"body\":{\"type\":\"text\"},\"views\":{\"type\":\"integer\"},\"tag\":{\"type\":\"keyword\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"acknowledged\": true,\n \"shards_acknowledged\": true,\n \"index\": \"articles\"\n}"
+ },
+ {
+ "label": "index a document",
+ "cmd": "curl -s -XPUT \"http://localhost:9200/articles/_doc/1\" \\\n -H 'content-type: application/json' \\\n -d '{\"title\":\"Hello Xerj\",\"body\":\"one binary for search\",\"views\":42,\"tag\":\"intro\"}'",
+ "status": 201,
+ "pass": true,
+ "output": "{\n \"_index\": \"articles\",\n \"_id\": \"1\",\n \"_version\": 1,\n \"result\": \"created\",\n \"_shards\": {\n \"total\": 1,\n \"successful\": 1,\n \"failed\": 0\n },\n \"_seq_no\": 1,\n \"_primary_term\": 1\n}"
+ },
+ {
+ "label": "get the document",
+ "cmd": "curl -s \"http://localhost:9200/articles/_doc/1\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_index\": \"articles\",\n \"_id\": \"1\",\n \"_version\": 1,\n \"_seq_no\": 1,\n \"_primary_term\": 1,\n \"found\": true,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n}"
+ },
+ {
+ "label": "search it",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"match\":{\"body\":\"binary\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"1\",\n \"_index\": \"articles\",\n \"_score\": 0.28768211603164673,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n }\n ],\n \"max_score\": 0.28768211603164673,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 1\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ }
+ ]
+ },
+ {
+ "id": "03-ingest-bulk",
+ "doc": "ingest",
+ "title": "Bulk ingest — ES /_bulk wire protocol",
+ "steps": [
+ {
+ "label": "bulk index 4 docs",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_bulk\" \\\n -H 'content-type: application/x-ndjson' \\\n --data-binary $'{\"index\":{}}\\n{\"title\":\"A\",\"body\":\"alpha vector\",\"views\":10,\"tag\":\"a\"}\\n{\"index\":{}}\\n{\"title\":\"B\",\"body\":\"beta search\",\"views\":20,\"tag\":\"b\"}\\n{\"index\":{}}\\n{\"title\":\"C\",\"body\":\"gamma logs\",\"views\":30,\"tag\":\"a\"}\\n{\"index\":{}}\\n{\"title\":\"D\",\"body\":\"delta agg\",\"views\":40,\"tag\":\"b\"}\\n'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"errors\": false,\n \"items\": [\n {\n \"index\": {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632748670,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"118126af-ff27-4207-9dd4-8f92a18e963e\",\n \"_index\": \"articles\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632748670,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"93f7e5c2-629e-4cc2-a884-7c09d50f07f0\",\n \"_index\": \"articles\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632748670,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"b4adabc9-73d7-4c67-a166-2b8c29556617\",\n \"_index\": \"articles\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632748670,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n }\n ],\n \"took\": 2\n}"
+ },
+ {
+ "label": "refresh to make searchable",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_refresh\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n }\n}"
+ },
+ {
+ "label": "count documents",
+ "cmd": "curl -s \"http://localhost:9200/articles/_count\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"count\": 5\n}"
+ },
+ {
+ "label": "cat indices",
+ "cmd": "curl -s \"http://localhost:9200/_cat/indices?v\"",
+ "status": 200,
+ "pass": true,
+ "output": "green open .xerj_cluster_state 13562e00-3e53-4abc-93e1-485daa33ab7d 1 0 0 0\ngreen open .xerj_api_tokens 1b99a488-5e3d-4577-91f1-d550cebadd16 1 0 0 0\ngreen open .xerj_prefs 3b2f09ba-b628-4709-892d-36838e7bcc95 1 0 0 0\ngreen open articles 035aa409-ffd4-4900-bc11-f1ce1362704a 1 0 5 0\ngreen open .xerj_dashboards bf82e004-fe5e-4e3b-981f-ae7f6d9761ea 1 0 0 0\ngreen open .xerj_users f8914758-f9f4-4643-89f0-8cb1b6b60f7e 1 0 0 0\ngreen open .xerj_passkeys c12ab029-b81d-4897-bb2e-c2b044fd55df 1 0 0 0\ngreen open .xerj_alert_rules 0a55c41b-1850-4430-89cb-7b334bd32538 1 0 0 0\ngreen open .xerj_magic_links 24ca4002-e3be-4fe2-908c-bd67d6f7114e 1 0 1 0\ngreen open .xerj_idp_config 0b17a3f0-41d8-437b-b0ff-d8ed0b945830 1 0 0 0\ngreen open .xerj_sessions 37411c10-15bc-45bc-a542-b99ec41dd52a 1 0 0 0\ngreen open .xerj_audit 9f87223e-af48-489a-8c41-259e96006144 1 0 0 0\ngreen open .xerj_connections a9d1fa85-c2c0-431b-87d4-e3019f093076 1 0 0 0\ngreen open .xerj_alert_fires 14e14403-4005-4218-8494-c56c486ae3ae 1 0 0 0\ngreen open .xerj_views bfce567b-a259-4083-a8cb-02d9604e2dd3 1 0 0 0"
+ }
+ ]
+ },
+ {
+ "id": "04-full-text",
+ "doc": "queries / playbooks/full-text",
+ "title": "Full-text search — the ES query families",
+ "steps": [
+ {
+ "label": "match",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"match\":{\"body\":\"search\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"1\",\n \"_index\": \"articles\",\n \"_score\": 0.6099694967269897,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n },\n {\n \"_id\": \"118126af-ff27-4207-9dd4-8f92a18e963e\",\n \"_index\": \"articles\",\n \"_score\": 0.28768211603164673,\n \"_source\": {\n \"body\": \"beta search\",\n \"tag\": \"b\",\n \"title\": \"B\",\n \"views\": 20\n }\n }\n ],\n \"max_score\": 0.6099694967269897,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 2\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "match_phrase",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"match_phrase\":{\"body\":\"alpha vector\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"alpha vector\",\n \"tag\": \"a\",\n \"title\": \"A\",\n \"views\": 10\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 1\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "term (keyword)",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"term\":{\"tag\":\"a\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 1.6931471824645996,\n \"_source\": {\n \"body\": \"alpha vector\",\n \"tag\": \"a\",\n \"title\": \"A\",\n \"views\": 10\n }\n },\n {\n \"_id\": \"93f7e5c2-629e-4cc2-a884-7c09d50f07f0\",\n \"_index\": \"articles\",\n \"_score\": 1.6931471824645996,\n \"_source\": {\n \"body\": \"gamma logs\",\n \"tag\": \"a\",\n \"title\": \"C\",\n \"views\": 30\n }\n }\n ],\n \"max_score\": 1.6931471824645996,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 2\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "terms",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"terms\":{\"tag\":[\"a\",\"b\"]}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"alpha vector\",\n \"tag\": \"a\",\n \"title\": \"A\",\n \"views\": 10\n }\n },\n {\n \"_id\": \"118126af-ff27-4207-9dd4-8f92a18e963e\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"beta search\",\n \"tag\": \"b\",\n \"title\": \"B\",\n \"views\": 20\n }\n },\n {\n \"_id\": \"93f7e5c2-629e-4cc2-a884-7c09d50f07f0\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"gamma logs\",\n \"tag\": \"a\",\n \"title\": \"C\",\n \"views\": 30\n }\n },\n {\n \"_id\": \"b4adabc9-73d7-4c67-a166-2b8c29556617\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"delta agg\",\n \"tag\": \"b\",\n \"title\": \"D\",\n \"views\": 40\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 4\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "range",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"range\":{\"views\":{\"gte\":20}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"1\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n },\n {\n \"_id\": \"118126af-ff27-4207-9dd4-8f92a18e963e\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"beta search\",\n \"tag\": \"b\",\n \"title\": \"B\",\n \"views\": 20\n }\n },\n {\n \"_id\": \"93f7e5c2-629e-4cc2-a884-7c09d50f07f0\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"gamma logs\",\n \"tag\": \"a\",\n \"title\": \"C\",\n \"views\": 30\n }\n },\n {\n \"_id\": \"b4adabc9-73d7-4c67-a166-2b8c29556617\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"delta agg\",\n \"tag\": \"b\",\n \"title\": \"D\",\n \"views\": 40\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 4\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "bool must+filter",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"bool\":{\"must\":[{\"match\":{\"body\":\"logs\"}}],\"filter\":[{\"term\":{\"tag\":\"a\"}}]}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"93f7e5c2-629e-4cc2-a884-7c09d50f07f0\",\n \"_index\": \"articles\",\n \"_score\": 0.9741763472557068,\n \"_source\": {\n \"body\": \"gamma logs\",\n \"tag\": \"a\",\n \"title\": \"C\",\n \"views\": 30\n }\n }\n ],\n \"max_score\": 0.9741763472557068,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 1\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "prefix",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"prefix\":{\"body\":\"alp\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"alpha vector\",\n \"tag\": \"a\",\n \"title\": \"A\",\n \"views\": 10\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 1\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "wildcard",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"wildcard\":{\"body\":\"sea*\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"1\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n },\n {\n \"_id\": \"118126af-ff27-4207-9dd4-8f92a18e963e\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"beta search\",\n \"tag\": \"b\",\n \"title\": \"B\",\n \"views\": 20\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 2\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "exists",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"exists\":{\"field\":\"title\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"1\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n },\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"alpha vector\",\n \"tag\": \"a\",\n \"title\": \"A\",\n \"views\": 10\n }\n },\n {\n \"_id\": \"118126af-ff27-4207-9dd4-8f92a18e963e\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"beta search\",\n \"tag\": \"b\",\n \"title\": \"B\",\n \"views\": 20\n }\n },\n {\n \"_id\": \"93f7e5c2-629e-4cc2-a884-7c09d50f07f0\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"gamma logs\",\n \"tag\": \"a\",\n \"title\": \"C\",\n \"views\": 30\n }\n },\n {\n \"_id\": \"b4adabc9-73d7-4c67-a166-2b8c29556617\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"delta agg\",\n \"tag\": \"b\",\n \"title\": \"D\",\n \"views\": 40\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "highlight + sort + _source",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"match\":{\"body\":\"vector\"}},\"highlight\":{\"fields\":{\"body\":{}}},\"sort\":[{\"views\":\"desc\"}],\"_source\":[\"title\",\"views\"]}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 0.28768211603164673,\n \"_source\": {\n \"title\": \"A\",\n \"views\": 10\n },\n \"sort\": [\n 10\n ]\n }\n ],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 1\n }\n },\n \"timed_out\": false,\n \"took\": 1\n}"
+ }
+ ]
+ },
+ {
+ "id": "05-aggregations",
+ "doc": "aggregations",
+ "title": "Aggregations — the boardroom view",
+ "steps": [
+ {
+ "label": "terms",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"by_tag\":{\"terms\":{\"field\":\"tag\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"by_tag\": {\n \"buckets\": [\n {\n \"doc_count\": 2,\n \"key\": \"a\"\n },\n {\n \"doc_count\": 2,\n \"key\": \"b\"\n },\n {\n \"doc_count\": 1,\n \"key\": \"intro\"\n }\n ],\n \"doc_count_error_upper_bound\": 0,\n \"sum_other_doc_count\": 0\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "stats",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"v\":{\"stats\":{\"field\":\"views\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"v\": {\n \"avg\": 28.4,\n \"count\": 5,\n \"max\": 42,\n \"min\": 10,\n \"sum\": 142\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "sum / avg / max / min",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"s\":{\"sum\":{\"field\":\"views\"}},\"a\":{\"avg\":{\"field\":\"views\"}},\"mx\":{\"max\":{\"field\":\"views\"}},\"mn\":{\"min\":{\"field\":\"views\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"a\": {\n \"value\": 28.4\n },\n \"mn\": {\n \"value\": 10\n },\n \"mx\": {\n \"value\": 42\n },\n \"s\": {\n \"value\": 142\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "cardinality",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"uniq\":{\"cardinality\":{\"field\":\"tag\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"uniq\": {\n \"value\": 3\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "value_count",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"c\":{\"value_count\":{\"field\":\"views\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"c\": {\n \"value\": 5\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "histogram",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"h\":{\"histogram\":{\"field\":\"views\",\"interval\":10}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"h\": {\n \"buckets\": [\n {\n \"doc_count\": 1,\n \"key\": 10\n },\n {\n \"doc_count\": 1,\n \"key\": 20\n },\n {\n \"doc_count\": 1,\n \"key\": 30\n },\n {\n \"doc_count\": 2,\n \"key\": 40\n }\n ]\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "range",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"r\":{\"range\":{\"field\":\"views\",\"ranges\":[{\"to\":20},{\"from\":20}]}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"r\": {\n \"buckets\": [\n {\n \"doc_count\": 1,\n \"key\": \"*-20.0\",\n \"to\": 20\n },\n {\n \"doc_count\": 4,\n \"from\": 20,\n \"key\": \"20.0-*\"\n }\n ]\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "percentiles",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"p\":{\"percentiles\":{\"field\":\"views\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"p\": {\n \"values\": {\n \"1.0\": 10.4,\n \"25.0\": 20,\n \"5.0\": 12,\n \"50.0\": 30,\n \"75.0\": 40,\n \"95.0\": 41.6,\n \"99.0\": 41.92\n }\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "terms + nested avg",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"by_tag\":{\"terms\":{\"field\":\"tag\"},\"aggs\":{\"avg_views\":{\"avg\":{\"field\":\"views\"}}}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"by_tag\": {\n \"buckets\": [\n {\n \"avg_views\": {\n \"value\": 20\n },\n \"doc_count\": 2,\n \"key\": \"a\"\n },\n {\n \"avg_views\": {\n \"value\": 30\n },\n \"doc_count\": 2,\n \"key\": \"b\"\n },\n {\n \"avg_views\": {\n \"value\": 42\n },\n \"doc_count\": 1,\n \"key\": \"intro\"\n }\n ],\n \"doc_count_error_upper_bound\": 0,\n \"sum_other_doc_count\": 0\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ }
+ ]
+ },
+ {
+ "id": "06-vector-search",
+ "doc": "vectors / playbooks/vector-search",
+ "title": "Vector search — kNN, no Pinecone",
+ "steps": [
+ {
+ "label": "create vector index",
+ "cmd": "curl -s -XPUT \"http://localhost:9200/vstore\" \\\n -H 'content-type: application/json' \\\n -d '{\"mappings\":{\"properties\":{\"text\":{\"type\":\"text\"},\"embedding\":{\"type\":\"dense_vector\",\"dims\":4}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"acknowledged\": true,\n \"shards_acknowledged\": true,\n \"index\": \"vstore\"\n}"
+ },
+ {
+ "label": "bulk index vectors",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/vstore/_bulk\" \\\n -H 'content-type: application/x-ndjson' \\\n --data-binary $'{\"index\":{}}\\n{\"text\":\"red apple\",\"embedding\":[0.9,0.1,0.0,0.1]}\\n{\"index\":{}}\\n{\"text\":\"green pear\",\"embedding\":[0.1,0.9,0.1,0.0]}\\n{\"index\":{}}\\n{\"text\":\"blue car\",\"embedding\":[0.0,0.1,0.9,0.1]}\\n'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"errors\": false,\n \"items\": [\n {\n \"index\": {\n \"_id\": \"f11a9068-5187-409d-ace8-75612532fe81\",\n \"_index\": \"vstore\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632941008,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"07c6f744-6e83-4bee-97ed-a258df49532d\",\n \"_index\": \"vstore\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632941008,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"34647d96-e2fa-4dcb-952f-182cc70bacd8\",\n \"_index\": \"vstore\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796632941008,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n }\n ],\n \"took\": 0\n}"
+ },
+ {
+ "label": "refresh",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/vstore/_refresh\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n }\n}"
+ },
+ {
+ "label": "kNN nearest to [0.9,0.1,0,0.1]",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/vstore/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"knn\":{\"field\":\"embedding\",\"query_vector\":[0.9,0.1,0,0.1],\"k\":2,\"num_candidates\":10}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"f11a9068-5187-409d-ace8-75612532fe81\",\n \"_index\": \"vstore\",\n \"_score\": 1,\n \"_source\": {\n \"embedding\": [\n 0.9,\n 0.1,\n 0,\n 0.1\n ],\n \"text\": \"red apple\"\n }\n },\n {\n \"_id\": \"07c6f744-6e83-4bee-97ed-a258df49532d\",\n \"_index\": \"vstore\",\n \"_score\": 0.608433723449707,\n \"_source\": {\n \"embedding\": [\n 0.1,\n 0.9,\n 0.1,\n 0\n ],\n \"text\": \"green pear\"\n }\n },\n {\n \"_id\": \"34647d96-e2fa-4dcb-952f-182cc70bacd8\",\n \"_index\": \"vstore\",\n \"_score\": 0.5120481848716736,\n \"_source\": {\n \"embedding\": [\n 0,\n 0.1,\n 0.9,\n 0.1\n ],\n \"text\": \"blue car\"\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 3\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ }
+ ]
+ },
+ {
+ "id": "07-analyzers",
+ "doc": "analyzers",
+ "title": "Analyzers — _analyze",
+ "steps": [
+ {
+ "label": "standard analyzer",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/_analyze\" \\\n -H 'content-type: application/json' \\\n -d '{\"analyzer\":\"standard\",\"text\":\"The Quick, Brown Fox!\"}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"tokens\": [\n {\n \"end_offset\": 3,\n \"position\": 0,\n \"start_offset\": 0,\n \"token\": \"the\",\n \"type\": \"word\"\n },\n {\n \"end_offset\": 9,\n \"position\": 1,\n \"start_offset\": 4,\n \"token\": \"quick\",\n \"type\": \"word\"\n },\n {\n \"end_offset\": 16,\n \"position\": 2,\n \"start_offset\": 11,\n \"token\": \"brown\",\n \"type\": \"word\"\n },\n {\n \"end_offset\": 20,\n \"position\": 3,\n \"start_offset\": 17,\n \"token\": \"fox\",\n \"type\": \"word\"\n }\n ]\n}"
+ },
+ {
+ "label": "keyword analyzer",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/_analyze\" \\\n -H 'content-type: application/json' \\\n -d '{\"analyzer\":\"keyword\",\"text\":\"The Quick, Brown Fox!\"}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"tokens\": [\n {\n \"end_offset\": 21,\n \"position\": 0,\n \"start_offset\": 0,\n \"token\": \"The Quick, Brown Fox!\",\n \"type\": \"word\"\n }\n ]\n}"
+ },
+ {
+ "label": "whitespace analyzer",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/_analyze\" \\\n -H 'content-type: application/json' \\\n -d '{\"analyzer\":\"whitespace\",\"text\":\"The Quick, Brown Fox!\"}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"tokens\": [\n {\n \"end_offset\": 3,\n \"position\": 0,\n \"start_offset\": 0,\n \"token\": \"The\",\n \"type\": \"word\"\n },\n {\n \"end_offset\": 10,\n \"position\": 1,\n \"start_offset\": 4,\n \"token\": \"Quick,\",\n \"type\": \"word\"\n },\n {\n \"end_offset\": 16,\n \"position\": 2,\n \"start_offset\": 11,\n \"token\": \"Brown\",\n \"type\": \"word\"\n },\n {\n \"end_offset\": 21,\n \"position\": 3,\n \"start_offset\": 17,\n \"token\": \"Fox!\",\n \"type\": \"word\"\n }\n ]\n}"
+ }
+ ]
+ },
+ {
+ "id": "08-mappings-templates-aliases",
+ "doc": "config / operations",
+ "title": "Mappings, templates & aliases",
+ "steps": [
+ {
+ "label": "get mapping",
+ "cmd": "curl -s \"http://localhost:9200/articles/_mapping\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"articles\": {\n \"mappings\": {\n \"properties\": {\n \"body\": {\n \"type\": \"text\"\n },\n \"tag\": {\n \"type\": \"keyword\"\n },\n \"title\": {\n \"type\": \"text\"\n },\n \"views\": {\n \"type\": \"integer\"\n }\n }\n }\n }\n}"
+ },
+ {
+ "label": "put index template",
+ "cmd": "curl -s -XPUT \"http://localhost:9200/_index_template/logs_tpl\" \\\n -H 'content-type: application/json' \\\n -d '{\"index_patterns\":[\"logs-*\"],\"template\":{\"mappings\":{\"properties\":{\"@timestamp\":{\"type\":\"date\"},\"level\":{\"type\":\"keyword\"},\"msg\":{\"type\":\"text\"}}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"acknowledged\": true\n}"
+ },
+ {
+ "label": "add alias",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/_aliases\" \\\n -H 'content-type: application/json' \\\n -d '{\"actions\":[{\"add\":{\"index\":\"articles\",\"alias\":\"articles_live\"}}]}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"acknowledged\": true\n}"
+ },
+ {
+ "label": "search via alias",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles_live/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"query\":{\"match_all\":{}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ }
+ ]
+ },
+ {
+ "id": "09-log-analytics",
+ "doc": "playbooks/log-analytics",
+ "title": "Log analytics — Splunk/Kibana workload",
+ "steps": [
+ {
+ "label": "bulk ingest logs (template applies)",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/logs-2026-04/_bulk\" \\\n -H 'content-type: application/x-ndjson' \\\n --data-binary $'{\"index\":{}}\\n{\"@timestamp\":\"2026-04-26T19:47:24Z\",\"level\":\"info\",\"msg\":\"request ok\",\"svc\":\"api\"}\\n{\"index\":{}}\\n{\"@timestamp\":\"2026-04-26T19:47:24Z\",\"level\":\"error\",\"msg\":\"timeout\",\"svc\":\"api\"}\\n{\"index\":{}}\\n{\"@timestamp\":\"2026-04-26T19:47:24Z\",\"level\":\"error\",\"msg\":\"5xx upstream\",\"svc\":\"web\"}\\n{\"index\":{}}\\n{\"@timestamp\":\"2026-04-26T19:47:24Z\",\"level\":\"warn\",\"msg\":\"slow query\",\"svc\":\"db\"}\\n'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"errors\": false,\n \"items\": [\n {\n \"index\": {\n \"_id\": \"b91fb60d-4139-4f60-b77f-f8fd8f7b1b08\",\n \"_index\": \"logs-2026-04\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796633012746,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"68a7e704-14b3-49b7-8fff-6360046c5b93\",\n \"_index\": \"logs-2026-04\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796633012746,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"6bb266ed-93fe-41ce-9d66-136ab8fe87ba\",\n \"_index\": \"logs-2026-04\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796633012746,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n },\n {\n \"index\": {\n \"_id\": \"39294ad5-3bc2-4f8a-94b4-4a318573d130\",\n \"_index\": \"logs-2026-04\",\n \"_primary_term\": 1,\n \"_seq_no\": 1782796633012746,\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"_version\": 1,\n \"result\": \"created\",\n \"status\": 201\n }\n }\n ],\n \"took\": 1\n}"
+ },
+ {
+ "label": "refresh",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/logs-2026-04/_refresh\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"successful\": 1,\n \"total\": 1\n }\n}"
+ },
+ {
+ "label": "errors only (bool filter)",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/logs-2026-04/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"term\":{\"level\":\"error\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"68a7e704-14b3-49b7-8fff-6360046c5b93\",\n \"_index\": \"logs-2026-04\",\n \"_score\": 1.6931471824645996,\n \"_source\": {\n \"@timestamp\": \"2026-04-26T19:47:24Z\",\n \"level\": \"error\",\n \"msg\": \"timeout\",\n \"svc\": \"api\"\n }\n },\n {\n \"_id\": \"6bb266ed-93fe-41ce-9d66-136ab8fe87ba\",\n \"_index\": \"logs-2026-04\",\n \"_score\": 1.6931471824645996,\n \"_source\": {\n \"@timestamp\": \"2026-04-26T19:47:24Z\",\n \"level\": \"error\",\n \"msg\": \"5xx upstream\",\n \"svc\": \"web\"\n }\n }\n ],\n \"max_score\": 1.6931471824645996,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 2\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "count by level",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/logs-2026-04/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"aggs\":{\"by_level\":{\"terms\":{\"field\":\"level\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"by_level\": {\n \"buckets\": [\n {\n \"doc_count\": 2,\n \"key\": \"error\"\n },\n {\n \"doc_count\": 1,\n \"key\": \"info\"\n },\n {\n \"doc_count\": 1,\n \"key\": \"warn\"\n }\n ],\n \"doc_count_error_upper_bound\": 0,\n \"sum_other_doc_count\": 0\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 4\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "errors over time (date_histogram)",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/logs-2026-04/_search\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":0,\"query\":{\"term\":{\"level\":\"error\"}},\"aggs\":{\"t\":{\"date_histogram\":{\"field\":\"@timestamp\",\"calendar_interval\":\"day\"}}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"aggregations\": {\n \"t\": {\n \"buckets\": [\n {\n \"doc_count\": 2,\n \"key\": 1777161600000,\n \"key_as_string\": \"2026-04-26T00:00:00.000Z\"\n }\n ]\n }\n },\n \"hits\": {\n \"hits\": [],\n \"max_score\": null,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 2\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ }
+ ]
+ },
+ {
+ "id": "10-migration-es",
+ "doc": "migration-from-es",
+ "title": "Migration from Elasticsearch — drop-in parity",
+ "steps": [
+ {
+ "label": "ES version handshake (Kibana checks this)",
+ "cmd": "curl -s \"http://localhost:9200/\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"name\": \"xerj-node-66d6c077\",\n \"cluster_name\": \"xerj\",\n \"cluster_uuid\": \"xerj-cluster-0000-0000-0000-000000000000\",\n \"version\": {\n \"number\": \"8.13.0\",\n \"build_flavor\": \"default\",\n \"build_type\": \"tar\",\n \"build_hash\": \"00000000\",\n \"build_date\": \"2024-03-22T00:00:00.000Z\",\n \"build_snapshot\": false,\n \"lucene_version\": \"9.10.0\",\n \"minimum_wire_compatibility_version\": \"7.17.0\",\n \"minimum_index_compatibility_version\": \"7.0.0\"\n },\n \"tagline\": \"You Know, for Search\"\n}"
+ },
+ {
+ "label": "_cat/indices (ops tooling)",
+ "cmd": "curl -s \"http://localhost:9200/_cat/indices?v\"",
+ "status": 200,
+ "pass": true,
+ "output": "green open .xerj_cluster_state 96c36337-d6b1-47f9-9905-e356b6cecb04 1 0 0 0\ngreen open .xerj_api_tokens 1899253e-420a-40a1-af69-6bee59291936 1 0 0 0\ngreen open .xerj_prefs 12f27538-0e09-44e0-aa4b-a0bf44914b23 1 0 0 0\ngreen open logs-2026-04 f00d351d-25ca-465f-99d6-945449e0985e 1 0 4 0\ngreen open articles 1d2028e5-ec5e-4841-bb85-3dc07ba0ee45 1 0 5 0\ngreen open .xerj_dashboards c1be10bb-e64c-4474-bb9b-1314b7a507b4 1 0 0 0\ngreen open .xerj_users c8abbbd2-e317-4e87-9ee4-1cb3f76a8bd5 1 0 0 0\ngreen open .xerj_passkeys ab84e4b4-c7f5-477a-8adc-bcdd2a46822c 1 0 0 0\ngreen open vstore a0fc834d-e792-43ad-ab29-ab698d0d7124 1 0 3 0\ngreen open .xerj_alert_rules 175ed6ba-f804-4b85-b402-b28d4c02ff8d 1 0 0 0\ngreen open .xerj_magic_links 5d8ee201-a207-4952-ae6f-f9d013978b41 1 0 1 0\ngreen open .xerj_idp_config 9c1e2518-68ef-495e-8e9f-70588dac66cc 1 0 0 0\ngreen open .xerj_sessions 239d4dc1-fa8a-49de-8e5c-36d451fc3907 1 0 0 0\ngreen open .xerj_audit 3fd87f94-f6a7-4dda-b7c0-5ee14d7b0c3a 1 0 0 0\ngreen open .xerj_connections 776f68be-7795-4db5-8c7c-029ce4d03fcd 1 0 0 0\ngreen open .xerj_alert_fires e5705c2b-ee99-4d42-b04a-0733bbc0b421 1 0 0 0\ngreen open .xerj_views 3293e930-eb61-4342-88b7-d2ac2347ee69 1 0 0 0"
+ },
+ {
+ "label": "scroll API (pagination)",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_search?scroll=1m\" \\\n -H 'content-type: application/json' \\\n -d '{\"size\":2,\"query\":{\"match_all\":{}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"_scroll_id\": \"56506e1c-84f3-4665-88f1-f7fcf5ddedfa\",\n \"_shards\": {\n \"failed\": 0,\n \"skipped\": 0,\n \"successful\": 1,\n \"total\": 1\n },\n \"hits\": {\n \"hits\": [\n {\n \"_id\": \"1\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"one binary for search\",\n \"tag\": \"intro\",\n \"title\": \"Hello Xerj\",\n \"views\": 42\n }\n },\n {\n \"_id\": \"aab064f6-eecd-4b53-a75c-bf507f99edae\",\n \"_index\": \"articles\",\n \"_score\": 1,\n \"_source\": {\n \"body\": \"alpha vector\",\n \"tag\": \"a\",\n \"title\": \"A\",\n \"views\": 10\n }\n }\n ],\n \"max_score\": 1,\n \"total\": {\n \"relation\": \"eq\",\n \"value\": 5\n }\n },\n \"timed_out\": false,\n \"took\": 0\n}"
+ },
+ {
+ "label": "_delete_by_query",
+ "cmd": "curl -s -XPOST \"http://localhost:9200/articles/_delete_by_query\" \\\n -H 'content-type: application/json' \\\n -d '{\"query\":{\"term\":{\"tag\":\"b\"}}}'",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"batches\": 1,\n \"deleted\": 2,\n \"failures\": [],\n \"noops\": 0,\n \"requests_per_second\": -1,\n \"throttled_millis\": 0,\n \"throttled_until_millis\": 0,\n \"timed_out\": false,\n \"took\": 0,\n \"total\": 2,\n \"version_conflicts\": 0\n}"
+ }
+ ]
+ },
+ {
+ "id": "11-native-ops",
+ "doc": "metrics / operations / api-native",
+ "title": "Native ops API (:8080) — health & metrics",
+ "steps": [
+ {
+ "label": "native health",
+ "cmd": "curl -s \"http://localhost:8080/v1/health\"",
+ "status": 200,
+ "pass": true,
+ "output": "{\n \"data\": {\n \"status\": \"yellow\",\n \"index_count\": 17,\n \"total_docs\": 11,\n \"version\": \"1.0.0-rc.1\"\n },\n \"took_ms\": 0,\n \"request_id\": \"d64f1a4e-098c-4b04-8e97-586c978341c2\"\n}"
+ },
+ {
+ "label": "prometheus scrape",
+ "cmd": "curl -s \"http://localhost:8080/v1/metrics\"",
+ "status": 200,
+ "pass": true,
+ "output": "# HELP xerj_active_searches Number of searches currently in flight\n# TYPE xerj_active_searches gauge\nxerj_active_searches 0\n# HELP xerj_bytes_read_total Total bytes read from segment files (uncompressed)\n# TYPE xerj_bytes_read_total counter\nxerj_bytes_read_total 0\n# HELP xerj_bytes_written_total Total bytes written to segment files (uncompressed)\n# TYPE xerj_bytes_written_total counter\nxerj_bytes_written_total 0\n# HELP xerj_doc_count Total live documents across all indices\n# TYPE xerj_doc_count gauge\nxerj_doc_count 0\n# HELP xerj_docs_indexed_by_index_total Documents indexed, labelled by index name\n# TYPE xerj_docs_indexed_by_index_total counter\nxerj_docs_indexed_by_index_total{index=\"articles\"} 1\n# HELP xerj_docs_indexed_total Total number of documents successfully indexed\n# TYPE xerj_docs_indexed_total counter\nxerj_docs_indexed_total 1\n# HELP xerj_flush_duration_seconds Time to flush an in-memory buffer to a segment\n# TYPE xerj_flush_duration_seconds histogram\nxerj_flush_duration_seconds_bucket{le=\"0.01\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.02\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.04\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.08\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.16\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.32\"} 0\nxerj_flush_duration_seconds_bucket{le=\"0.64\"} 0\nxerj_flush_duration_seconds_bucket{le=\"1.28\"} 0\nxerj_flush_duration_seconds_bucket{le=\"2.56\"} 0\nxerj_flush_duration_seconds_bucket{le=\"5.12\"} 0\nxerj_flush_duration_seconds_bucket{le=\"10.24\"} 0\nxerj_flush_duration_seconds_bucket{le=\"20.48\"} 0\nxerj_flush_duration_seconds_bucket{le=\"40.96\"} 0\nxerj_flush_duration_seconds_bucket{le=\"81.92\"} 0\nxerj_flush_duration_seconds_bucket{le=\"163.84\"} 0\nxerj_flush_duration_seconds_bucket{le=\"+Inf\"} 0\nxerj_flush_duration_seconds_sum 0\nxerj_flush_duration_seconds_count 0\n# HELP xerj_index_latency_seconds End-to-end document indexing latency\n# TYPE xerj_index_latency_seconds histogram\nxerj_index_latency_seconds_bucket{le=\"0.0005\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.001\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.002\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.004\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.008\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.016\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.032\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.064\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.128\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.256\"} 0\nxerj_index_latency_seconds_bucket{le=\"0.512\"} 0\nxerj_index_latency_seconds_bucket{le=\"1.024\"} 0\nxerj_index_latency_seconds_bucket{le=\"2.048\"} 0\nxerj_index_latency_seconds_bucket{le=\"4.096\"} 0\nxerj_index_latency_seconds_bucket{le=\"8.192\"} 0\nxerj_index_latency_seconds_bucket{le=\"+Inf\"} 0\nxerj_index_latency_seconds_sum 0\nxerj_index_latency_seconds_count 0\n# HELP xerj_memory_usage_bytes Approximate engine memory usage in bytes\n# TYPE xerj_memory_usage_bytes gauge\nxerj_memory_usage_bytes 0\n# HELP xerj_merge_duration_seconds Time to complete a segment merge operation\n# TYPE xerj_merge_duration_seconds histogram\nxerj_merge_duration_seconds_bucket{le=\"0.01\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.02\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.04\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.08\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.16\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.32\"} 0\nxerj_merge_duration_seconds_bucket{le=\"0.64\"} 0\nxerj_merge_duration_seconds_bucket{le=\"1.28\"} 0\nxerj_merge_duration_seconds_bucket{le=\"2.56\"} 0\nxerj_merge_duration_seconds_bucket{le=\"5.12\"} 0\nxerj_merge_duration_seconds_bucket{le=\"10.24\"} 0\nxerj_merge_duration_seconds_bucket{le=\"20.48\"} 0\nxerj_merge_duration_seconds_bucket{le=\"40.96\"} 0\nxerj_merge_duration_seconds_bucket{le=\"81.92\"} 0\nxerj_merge_duration_seconds_bucket{le=\"163.84\"} 0\nxerj_merge_duration_seconds_bucket{le=\"+Inf\"} 0\nxerj_merge_duration_seconds_sum 0\nxerj_merge_duration_seconds_count 0\n# HELP xerj_queries_by_index_total Queries executed, labelled by index name\n# TYPE xerj_queries_by_index_total counter\nxerj_queries_by_index_total{index=\"articles\"} 21\nxerj_queries_by_index_total{index=\"articles_live\"} 1\nxerj_queries_by_index_total{index=\"logs-2026-04\"} 3\nxerj_queries_by_index_total{index=\"vstore\"} 1\n# HELP xerj_queries_executed_total Total number of search queries executed\n# TYPE xerj_queries_executed_total counter\nxerj_queries_executed_total 26\n# HELP xerj_query_latency_seconds End-to-end query latency\n# TYPE xerj_query_latency_seconds histogram\nxerj_query_latency_seconds_bucket{le=\"0.0005\"} 25\nxerj_query_latency_seconds_bucket{le=\"0.001\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.002\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.004\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.008\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.016\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.032\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.064\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.128\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.256\"} 26\nxerj_query_latency_seconds_bucket{le=\"0.512\"} 26\nxerj_query_latency_seconds_bucket{le=\"1.024\"} 26\nxerj_query_latency_seconds_bucket{le=\"2.048\"} 26\nxerj_query_latency_seconds_bucket{le=\"4.096\"} 26\nxerj_query_latency_seconds_bucket{le=\"8.192\"} 26\nxerj_query_latency_seconds_bucket{le=\"+Inf\"} 26\nxerj_query_latency_seconds_sum 0.001\nxerj_query_latency_seconds_count 26\n# HELP xerj_segment_count Number of open segments across all indices\n# TYPE xerj_segment_count gauge\nxerj_segment_count 0\n# HELP xerj_wal_size_bytes Current WAL size on disk in bytes\n# TYPE xerj_wal_size_bytes gauge\nxerj_wal_size_bytes 0\n# HELP xerj_wal_write_latency_seconds WAL write latency\n# TYPE xerj_wal_write_latency_seconds histogram\nxerj_wal_write_latency_seconds_bucket{le=\"0.0005\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.001\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.002\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.004\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.008\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.016\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.032\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.064\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.128\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.256\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"0.512\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"1.024\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"2.048\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"4.096\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"8.192\"} 0\nxerj_wal_write_latency_seconds_bucket{le=\"+Inf\"} 0\nxerj_wal_write_latency_seconds_sum 0\nxerj_wal_write_latency_seconds_count 0"
+ },
+ {
+ "label": "DOC GAP: /v1/health/ready",
+ "cmd": "curl -s \"http://localhost:8080/v1/health/ready\"",
+ "status": 404,
+ "pass": false,
+ "output": ""
+ },
+ {
+ "label": "DOC GAP: /v1/cluster/health",
+ "cmd": "curl -s \"http://localhost:8080/v1/cluster/health\"",
+ "status": 404,
+ "pass": false,
+ "output": ""
+ },
+ {
+ "label": "DOC GAP: /v1/admin/flush",
+ "cmd": "curl -s -XPOST \"http://localhost:8080/v1/admin/flush\"",
+ "status": 404,
+ "pass": false,
+ "output": ""
+ },
+ {
+ "label": "DOC GAP: /v1/admin/backup",
+ "cmd": "curl -s -XPOST \"http://localhost:8080/v1/admin/backup\" \\\n -H 'content-type: application/json' \\\n -d '{}'",
+ "status": 404,
+ "pass": false,
+ "output": ""
+ }
+ ]
+ },
+ {
+ "id": "12-console-ux",
+ "doc": "Xerj Console (xerj-ux)",
+ "title": "Embedded Console UX",
+ "steps": [
+ {
+ "label": "console SPA shell",
+ "cmd": "curl -s \"http://localhost:9200/_xerj-console/\"",
+ "status": 200,
+ "pass": true,
+ "output": "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Xerj Console · typography-first observability for Xerj</title>\n<meta name=\"color-scheme\" content=\"dark light\">\n<script>\n // Theme bootstrap — runs before CSS to prevent a flash of wrong theme.\n (function () {\n var t = localStorage.getItem('xerj.theme');\n if (t !== 'day' && t !== 'night') t = 'night';\n document.documentElement.setAttribute('data-theme', t);\n })();\n</script>\n<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">\n<link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin>\n<link href=\"https://fonts.googleapis.com/css2?family=Big+Shoulders+Display:wght@400;700;800;900&family=JetBrains+Mono:wght@400;500;700&family=Inter:wght@400;500;600&display=swap\" rel=\"stylesheet\">\n<link rel=\"stylesheet\" href=\"assets/tokens.css\">\n<link rel=\"stylesheet\" href=\"assets/base.css\">\n<link rel=\"icon\" href=\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='13' font-family='monospace' font-size='14' font-weight='900' fill='%23EEBB00'%3Ez%3C/text%3E%3C/svg%3E\">\n</head>\n<body>\n<div id=\"app\" aria-busy=\"true\"></div>\n<!--\n Auth guard. Hits /_xerj-console/api/v1/me before app.js runs. On 401 we\n redirect to /_xerj-console/login (or /_xerj-console/setup when this is a fresh\n install — the bootstrap banner already pointed the user at /setup,\n but if they bookmarked / it's nicer to land on /setup than /login).\n On 200 we cache the user record on `window.__xerjConsoleMe` so app.js can\n pick it up synchronously without re-fetching, and import app.js.\n-->\n<script type=\"module\">\n (async () => {\n try {\n const r = await fetch('/_xerj-console/api/v1/me', {\n credentials: 'same-origin',\n headers: { 'accept': 'application/json' },\n });\n if (r.status === 401) {\n // Decide: setup vs login. We probe /cluster/info — its\n // `started_at_ms` tells us whether the server has been up\n // long enough that someone almost certainly set it up; on a\n // fresh boot we send the user to /setup.\n try {\n const info = await (await fetch('/_xerj-console/api/v1/cluster/info', {\n credentials: 'same-origin',\n })).json();\n // No reliable \"is bootstrapped?\" probe yet; default to /login\n // since /setup requires a magic-link token in the fragment.\n // Operators on first boot reach /setup via the stderr banner.\n void info;\n } catch {}\n window.location.href = '/_xerj-console/login';\n return;\n }\n if (!r.ok) throw new Error('HTTP ' + r.status);\n const body = await r.json();\n window.__xerjConsoleMe = body && body.data ? body.data.user : null;\n\n // Pull /prefs + /views from the engine and seed localStorage\n // BEFORE app.js boots — app.js reads localStorage at module-load\n // time, so the pull has to complete first or the SPA renders\n // with stale (or empty) state for one frame.\n try {\n const sync = await import('./src/xerj-console-sync.js');\n await sync.pullAll();\n // Start the periodic push tick once app.js has had a beat.\n Promise.resolve().then(() => sync.startPush());\n } catch (e) {\n console.warn('[xerj-console sync]', e);\n }\n } catch (e) {\n // Engine unreachable (offline dev, hot-reload mid-flight) —\n // load the SPA anyway so the user sees an error state instead\n // of a redirect loop.\n console.error('[xerj-console auth guard]', e);\n }\n await import('./src/app.js');\n })();\n</script>\n</body>\n</html>"
+ },
+ {
+ "label": "console app bundle",
+ "cmd": "curl -s \"http://localhost:9200/_xerj-console/src/app.js\"",
+ "status": 200,
+ "pass": true,
+ "output": "// ============================================================\n// XERJ.ai — Bootstrap + router + layout engine\n//\n// One render loop. Edit mode layers drag/resize/remove/add on\n// top of the same render — no separate editor routes.\n// ============================================================\n\nimport { registry, defaults, SECTIONS, DASHBOARD_GROUPS, dashboardsInSection } from './dashboards/registry.js';\nimport { Nav, SceneHeader, TimeCtrl, RefreshCtrl, FilterBar, ClusterCtrl, SavedViews, Footer, MobileCtrl } from './ux/chrome.js';\nimport { query, dataSourceStatus } from './data/query.js';\nimport { chartTypes, chartTypeList } from './ux/chart-types.js';\nimport { esc } from './ux/text.js';\nimport { mockSearch } from './data/mock.js';\nimport { hitsToCsv, downloadText, svgToPng } from './data/export.js';\nimport {\n mergedDashboards, renameDashboard, reorderDashboards, setHidden,\n createUserDashboard, deleteUserDashboard, isUserDash, resetAll as resetDashboards,\n} from './data/dashboard-store.js';\nimport {\n listClusters, listIndices, listFields, listClustersSync,\n defaultClusterId, setDefaultCluster,\n} from './data/data-sources.js';\n\n// ---------- state -----------------------------------------\nconst LS = {\n theme: 'xerj.theme',\n time: 'xerj.time',\n edit: 'xerj.edit',\n search: 'xerj.search',\n refresh: 'xerj.refresh',\n cluster: 'xerj.cluster',\n views: 'xerj.views',\n filters: (dashId) => 'xerj.filters.' + dashId,\n layout: (dashId) => 'xerj.layout.' + dashId,\n};\n\nfunction loadJSON(key, fallback) {\n try { const raw = localStorage.getItem(key); return raw ? JSON.parse(raw) : fallback; }\n catch { return fallback; }\n}\nfunction loadSearch() { return loadJSON(LS.search, null); }\nfunction loadAllFilters() {\n const out = {};\n for (const k of Object.keys(localStorage)) {\n if (k.startsWith('xerj.filters.')) {\n const id = k.slice('xerj.filters.'.length);\n try { out[id] = JSON.parse(localStorage.getItem(k)) || {}; } catch {}\n }\n }\n return out;\n}\n\nconst _initial = parseRoute();\nconst _urlState = parseUrlState();\nconst state = {\n section: _initial.section,\n route: _initial.route,\n time: _urlState.time || localStorage.getItem(LS.time) || '24H',\n timeCustom: {\n from: _urlState.tfrom || localStorage.getItem('xerj.timeFrom') || '',\n to: _urlState.tto || localStorage.getItem('xerj.timeTo') || '',\n },\n cluster: _urlState.cluster || defaultClusterId(),\n refresh: parseInt(localStorage.getItem(LS.refresh) || '0', 10), // ms; 0 = off\n refreshTimer: null,\n fetchedAt: null, // ISO string of last successful query\n fetchMs: null, // last fetch duration in ms\n fetchErr: null, // last fetch error message\n loading: false,\n filters: loadAllFilters(), // { [dashId]: { field: value } }\n theme: document.documentElement.getAttribute('data-theme') || 'night',\n edit: localStorage.getItem(LS.edit) === '1',\n mobile: localStorage.getItem('xerj.mobile') === '1',\n layouts: loadAllLayouts(),\n search: (() => {\n const loaded = loadSearch() || {};\n return {\n q: loaded.q || '',\n type: loaded.type || 'match',\n index: loaded.index || '*',\n filters: loaded.filters || {},\n sort: loaded.sort || { field: '_score', dir: 'desc' },\n showTime: loaded.showTime !== false,\n result: null,\n };\n })(),\n _focusSelector: null, // set by handlers that need focus restored\n};\n// Merge any URL-seeded filters into the current dashboard's filter set.\nif (_urlState.filters) {\n state.filters[_initial.route] = { ...(state.filters[_initial.route] || {}), ..._urlState.filters };\n saveFilters(_initial.route);\n}\n\n// ---------- filters, URL state, refresh -------------------\nfunction currentFilters() {\n return state.filters[state.route] || {};\n}\nfunction saveFilters(dashId) {\n const v = state.filters[dashId];\n if (v && Object.keys(v).length) localStorage.setItem(LS.filters(dashId), JSON.stringify(v));\n else localStorage.removeItem(LS.filters(dashId));\n}\n// Toggle a filter value. Multi-value semantics: clicking the same\n// value twice removes it; clicking a new value on an existing field\n// appends to the OR list.\nfunction setFilter(field, value) {\n const dashId = state.route;\n const cur = { ...(state.filters[dashId] || {}) };\n const existing = cur[field];\n if (existing == null) {\n cur[field] = value;\n } else if (Array.isArray(existing)) {\n const idx = existing.indexOf(value);\n if (idx >= 0) {\n const next = existing.filter((v) => v !== value);\n if (next.length === 0) delete cur[field];\n else if (next.length === 1) cur[field] = next[0];\n else cur[field] = next;\n } else {\n cur[field] = [...existing, value];\n }\n } else {\n if (existing === value) delete cur[field];\n else cur[field] = [existing, value];\n }\n state.filters[dashId] = cur;\n saveFilters(dashId);\n writeUrlState();\n}\n\n// Remove one value from a field (used by pill ✕ click on a specific\n// chip inside a multi-value filter).\nfunction removeFilterValue(field, value) {\n const dashId = state.route;\n const cur = { ...(state.filters[dashId] || {}) };\n const existing = cur[field];\n if (existing == null) return;\n if (Array.isArray(existing)) {\n const next = existing.filter((v) => v !== value);\n if (next.length === 0) delete cur[field];\n else if (next.length === 1) cur[field] = next[0];\n else cur[field] = next;\n } else if (existing === value) {\n delete cur[field];\n }\n state.filters[dashId] = cur;\n saveFilters(dashId);\n writeUrlState();\n}\n\n// KQL-lite parser: tokenize `field:value field:\"multi word\" foo`.\n// Free-text tokens become a synthetic `q` filter; repeat fields\n// turn into OR arrays.\nfunction parseKql(text) {\n const out = {};\n const add = (k, v) => {\n if (!v) return;\n if (out[k] == null) out[k] = v;\n else if (Array.isArray(out[k])) out[k].push(v);\n else out[k] = [out[k], v];\n };\n // Match field:\"quoted value\" OR field:value OR loose token\n const re = /([a-zA-Z_][\\w.]*):\"([^\"]*)\"|([a-zA-Z_][\\w.]*):(\\S+)|\"([^\"]+)\"|(\\S+)/g;\n let m;\n while ((m = re.exec(text)) !== null) {\n if (m[1] != null) add(m[1], m[2]);\n else if (m[3] != null) add(m[3], m[4]);\n else if (m[5] != null) add('q', m[5]);\n else if (m[6] != null) add('q', m[6]);\n }\n return out;\n}\n\n// Inverse of parseKql — render a filter object as a KQL string that\n// re-parses to the same shape. Used to keep the input box in sync.\nfunction serializeKql(filters) {\n const parts = [];\n for (const [k, v] of Object.entries(filters || {})) {\n const values = Array.isArray(v) ? v : [v];\n for (const x of values) {\n const needsQuote = /\\s/.test(String(x));\n if (k === 'q') {\n parts.push(needsQuote ? `\"${x}\"` : String(x));\n } else {\n parts.push(needsQuote ? `${k}:\"${x}\"` : `${k}:${x}`);\n }\n }\n }\n return parts.join(' ');\n}\n\nfunction applyKqlInput(text) {\n const dashId = state.route;\n state.filters[dashId] = parseKql(text);\n saveFilters(dashId);\n writeUrlState();\n}\nfunction clearFilters() {\n const dashId = state.route;\n state.filters[dashId] = {};\n saveFilters(dashId);\n writeUrlState();\n}\n\n// URL state: ?t=24H&f=service:auth,level:error&c=prod-us\n// Filters are encoded as repeated `f` params so URLSearchParams can\n// handle escaping cleanly: ?f=service:nginx&f=level:error. Multi-value\n// (OR) filters repeat the same key: ?f=service:auth&f=service:web.\nfunction parseUrlState() {\n const qs = location.search.slice(1);\n if (!qs) return {};\n const out = {};\n const params = new URLSearchParams(qs);\n if (params.get('t')) out.time = params.get('t').toUpperCase();\n if (params.get('tfrom')) out.tfrom = params.get('tfrom');\n if (params.get('tto')) out.tto = params.get('tto');\n if (params.get('c')) out.cluster = params.get('c');\n const all = params.getAll('f');\n if (all.length) {\n out.filters = {};\n for (const pair of all) {\n const idx = pair.indexOf(':');\n if (idx > 0) {\n const k = pair.slice(0, idx);\n const v = pair.slice(idx + 1);\n const existing = out.filters[k];\n if (existing == null) out.filters[k] = v;\n else if (Array.isArray(existing)) existing.push(v);\n else out.filters[k] = [existing, v];\n }\n }\n }\n return out;\n}\nfunction writeUrlState() {\n const params = new URLSearchParams();\n if (state.time && state.time !== '24H') params.set('t', state.time);\n if (state.time === 'CUSTOM' && state.timeCustom) {\n if (state.timeCustom.from) params.set('tfrom', state.timeCustom.from);\n if (state.timeCustom.to) params.set('tto', state.timeCustom.to);\n }\n if (state.cluster) params.set('c', state.cluster);\n for (const [k, v] of Object.entries(currentFilters())) {\n if (Array.isArray(v)) for (const x of v) params.append('f', `${k}:${x}`);\n else params.append('f', `${k}:${v}`);\n }\n const qs = params.toString();\n const url = location.pathname + (qs ? '?' + qs : '') + location.hash;\n history.replaceState(null, '', url);\n}\n\nfunction setRefreshInterval(ms) {\n state.refresh = ms;\n localStorage.setItem(LS.refresh, String(ms));\n if (state.refreshTimer) { clearInterval(state.refreshTimer); state.refreshTimer = null; }\n if (ms > 0) {\n state.refreshTimer = setInterval(() => {\n if (state.section === 'dashboards' || state.section === 'discover') render();\n }, ms);\n }\n}\n\n// ---------- saved views -----------------------------------\n// A saved view is a snapshot of (dashId, time, cluster, filters).\n// Click it to land on that dashboard with the same context.\nfunction loadViews() { return loadJSON(LS.views, []); }\nfunction saveViews(views) { localStorage.setItem(LS.views, JSON.stringify(views)); }\nfunction saveCurrentView() {\n const dashId = state.route;\n const all = loadViews();\n const name = prompt('Save view as:', 'View ' + (all.length + 1));\n if (!name) return;\n const id = 'v-' + Date.now().toString(36);\n all.push({\n id,\n name,\n dashId,\n time: state.time,\n cluster: state.cluster,\n filters: currentFilters(),\n savedAt: new Date().toISOString(),\n });\n saveViews(all);\n}\nfunction deleteView(id) {\n saveViews(loadViews().filter((v) => v.id !== id));\n}\nfunction applyView(id) {\n const v = loadViews().find((x) => x.id === id);\n if (!v) return;\n state.time = v.time;\n state.cluster = v.cluster || state.cluster;\n state.filters[v.dashId] = { ...(v.filters || {}) };\n saveFilters(v.dashId);\n localStorage.setItem(LS.time, state.time);\n location.hash = '#/dashboards/' + v.dashId;\n}\n\nfunction relTime(iso) {\n if (!iso) return '';\n const delta = Date.now() - new Date(iso).getTime();\n if (delta < 2000) return 'just now';\n if (delta < 60_000) return Math.round(delta / 1000) + 's ago';\n if (delta < 3600_000) return Math.round(delta / 60_000) + 'm ago';\n return Math.round(delta / 3600_000) + 'h ago';\n}\n\nfunction navStatus() {\n if (state.loading) return 'LOADING…';\n if (state.fetchErr) return 'ERROR · ' + state.fetchErr.slice(0, 40);\n const bits = [];\n // dataSourceStatus is a function in v0.7+ (was a const string) so\n // the nav reflects the live backend state instead of a fixed label.\n bits.push(typeof dataSourceStatus === 'function' ? dataSourceStatus() : String(dataSourceStatus));\n if (state.fetchedAt) bits.push('UPDATED ' + relTime(state.fetchedAt).toUpperCase());\n if (state.fetchMs != null) bits.push(state.fetchMs + 'MS');\n return bits.join(' · ');\n}\n\nfunction runSearchNow() {\n // Optimistic placeholder so the table doesn't blank out while\n // the live query is in flight. Replaced as soon as the engine\n // responds with real hits.\n state.search.result = mockSearch({\n q: state.search.q,\n type: state.search.type,\n index: state.search.index,\n filters: state.search.filters,\n sort: state.search.sort,\n });\n // Live xerj search: turn the SearchBox state into a real\n // `query()` ctx and overlay the live hits + facets when they\n // arrive. Falls back to the mock above on backend error so the\n // demo never serves a blank console.\n query({\n dashId: 'search-discover',\n range: state.time,\n customRange: state.time === 'CUSTOM' ? state.timeCustom : null,\n cluster: state.cluster,\n filters: state.search.filters,\n search: {\n q: state.search.q,\n type: state.search.type,\n index: state.search.index,\n },\n })\n .then((res) => {\n const live = res?.data;\n if (!live || live.error) return;\n const mock = state.search.result || {};\n state.search.result = {\n ...mock,\n hits: live.hits || mock.hits || [],\n total: live.total ?? (live.hits?.length ?? 0),\n took: live.took,\n max_score: live.max_score,\n facets: live.facets || mock.facets,\n _live: true,\n };\n state.fetchedAt = res.meta?.fetchedAt || Date.now();\n state.fetchMs = res.meta?.durationMs ?? state.fetchMs;\n // Re-render the page so the table swaps mock → live without\n // requiring user interaction.\n if (state.section === 'discover') render();\n })\n .catch(() => { /* leave the optimistic mock in place */ });\n // Persist the inputs (not the result — it rebuilds on demand)\n localStorage.setItem(LS.search, JSON.stringify({\n q: state.search.q,\n type: state.search.type,\n index: state.search.index,\n filters: state.search.filters,\n sort: state.search.sort,\n showTime: state.search.showTime,\n }));\n}\n\n/**\n * Parse the hash into { section, route }. Routes come in three shapes:\n *\n * #/ → section=dashboards, route=<first dashboard>\n * #/dashboards → section=dashboards, route=<first dashboard>\n * #/dashboards/:id → section=dashboards, route=:id\n * #/<section> → section=<section>, route=<view id for that section>\n *\n * Backward compat: legacy `#/ai-overview` (bare dashboard id) gets\n * auto-routed into `#/dashboards/ai-overview`, and legacy `#/manage`\n * redirects to `#/settings`.\n */\nfunction parseRoute() {\n const raw = (location.hash || '').replace(/^#\\/?/, '');\n const parts = raw.split('/').filter(Boolean);\n const merged = mergedDashboards(defaults, { includeHidden: true });\n\n // Helper: find the default view id for a section.\n const firstOfSection = (sectionId) => {\n const list = dashboardsInSection(sectionId, merged);\n return list[0]?.id;\n };\n\n // Empty hash → dashboards section, first dashboard\n if (!parts.length) {\n const first = firstOfSection('dashboards') || 'ai-overview';\n return { section: 'dashboards', route: first };\n }\n\n // Legacy: #/manage → settings\n if (parts[0] === 'manage') return { section: 'settings', route: 'settings' };\n\n // Section-level route: #/section or #/section/:id\n const sectionIds = new Set(SECTIONS.map((s) => s.id));\n if (sectionIds.has(parts[0])) {\n if (parts[0] === 'dashboards') {\n const id = parts[1] || firstOfSection('dashboards') || 'ai-overview';\n // Only accept real dashboards in this section\n const known = merged.find((d) => d.id === id && (d.section || 'dashboards') === 'dashboards');\n if (known) return { section: 'dashboards', route: id };\n return { section: 'dashboards', route: firstOfSection('dashboards') || 'ai-overview' };\n }\n // Non-dashboards sections have exactly one view: firstOfSection\n const first = firstOfSection(parts[0]);\n if (first) return { section: parts[0], route: first };\n }\n\n // Legacy bare route: #/ai-overview → #/dashboards/ai-overview\n if (merged.some((d) => d.id === parts[0])) {\n const d = merged.find((x) => x.id === parts[0]);\n const section = d.section || 'dashboards';\n return { section, route: parts[0] };\n }\n\n // Fallback\n return { section: 'dashboards', route: firstOfSection('dashboards') || 'ai-overview' };\n}\n\n// Build the data context that the section views (DATA / SETTINGS)\n// need. Async because real API calls will replace these mocks in one\n// step once the engine ships /v1/clusters etc.\nasync function buildSectionData(sectionId) {\n if (sectionId === 'data') {\n const clusters = await listClusters();\n const indicesByCluster = {};\n const fieldsByIndex = {};\n for (const c of clusters) {\n indicesByCluster[c.id] = await listIndices(c.id);\n }\n const active = defaultClusterId();\n for (const i of indicesByCluster[active] || []) {\n fieldsByIndex[i.name] = await listFields(i.name);\n }\n return {\n clusters,\n indicesByCluster,\n fieldsByIndex,\n activeCluster: active,\n focusIndex: state._focusIndex || (indicesByCluster[active] || [])[0]?.name,\n };\n }\n if (sectionId === 'settings') {\n return {\n dashboards: mergedDashboards(defaults, { includeHidden: true }),\n views: loadViews(),\n };\n }\n return {};\n}\n\nfunction loadAllLayouts() {\n const out = {};\n for (const id of Object.keys(registry)) {\n try {\n const raw = localStorage.getItem(LS.layout(id));\n if (raw) out[id] = JSON.parse(raw);\n } catch { /* ignore corrupt */ }\n }\n return out;\n}\nfunction saveLayout(dashId) {\n const v = state.layouts[dashId];\n if (!v) localStorage.removeItem(LS.layout(dashId));\n else localStorage.setItem(LS.layout(dashId), JSON.stringify(v));\n}\nfunction applyTheme(t) {\n state.theme = t;\n document.documentElement.setAttribute('data-theme', t);\n localStorage.setItem(LS.theme, t);\n}\n\n// ---------- layout engine ---------------------------------\n/**\n * Merge a dashboard's default panels with the user's stored override.\n * Returns a flat ordered array of panel objects ready to render.\n */\nfunction mergeLayout(defaultPanels, override) {\n if (!override) return defaultPanels.map((p) => ({ ...p, source: 'default' }));\n const byId = Object.fromEntries(defaultPanels.map((p) => [p.id, p]));\n const hidden = new Set(override.hidden || []);\n const out = [];\n const seen = new Set();\n\n const order = override.order || defaultPanels.map((p) => p.id);\n for (const id of order) {\n if (hidden.has(id)) { seen.add(id); continue; }\n const base = byId[id];\n if (base) {\n const cols = override.cols?.[id] ?? base.cols;\n out.push({ ...base, cols, source: 'default' });\n seen.add(id);\n } else {\n // Maybe a user-added panel.\n const added = (override.added || []).find((a) => a.id === id);\n if (added) {\n const cols = override.cols?.[id] ?? added.cols;\n out.push({ ...added, cols, source: 'added' });\n seen.add(id);\n }\n }\n }\n // Append defaults missing from order (new panels added since override was saved).\n for (const p of defaultPanels) {\n if (!seen.has(p.id) && !hidden.has(p.id)) {\n const cols = override.cols?.[p.id] ?? p.cols;\n out.push({ ...p, cols, source: 'default' });\n }\n }\n // Append user-added panels missing from order (freshly added).\n for (const added of (override.added || [])) {\n if (!seen.has(added.id)) {\n const cols = override.cols?.[added.id] ?? added.cols;\n out.push({ ...added, cols, source: 'added' });\n }\n }\n return out;\n}\n\nfunction ensureOverride(dashId, defaultPanels) {\n if (state.layouts[dashId]) return state.layouts[dashId];\n const fresh = {\n order: defaultPanels.map((p) => p.id),\n cols: {},\n hidden: [],\n added: [],\n };\n state.layouts[dashId] = fresh;\n return fresh;\n}\n\nfunction mutate(dashId, defaultPanels, fn) {\n const ov = ensureOverride(dashId, defaultPanels);\n fn(ov);\n saveLayout(dashId);\n}\n\n// ---------- render ----------------------------------------\nconst SIZES = [2, 3, 4, 6, 8, 12];\n\nfunction renderEditChrome(p) {\n const sizes = SIZES.map((s) =>\n `<button type=\"button\" data-panel=\"${esc(p.id)}\" data-size=\"${s}\" class=\"${p.cols === s ? 'active' : ''}\" aria-pressed=\"${p.cols === s}\">${s}</button>`\n ).join('<span class=\"sep\">·</span>');\n const frac = Math.max(0, Math.min(12, p.cols)) / 12;\n const meterFill = (frac * 96).toFixed(1);\n const meter = `\n <svg class=\"meter\" viewBox=\"0 0 96 6\" preserveAspectRatio=\"none\" aria-hidden=\"true\">\n <line x1=\"0\" y1=\"5\" x2=\"96\" y2=\"5\" stroke=\"currentColor\" stroke-width=\"1\" stroke-opacity=\"0.25\"/>\n <line x1=\"0\" y1=\"5\" x2=\"${meterFill}\" y2=\"5\" stroke=\"var(--z-accent)\" stroke-width=\"1\"/>\n </svg>`;\n return `\n <div class=\"panel-edit\" aria-label=\"Edit panel\">\n <span class=\"colsLabel\"><span class=\"max\">COL</span> ${p.cols}<span class=\"slash\">/</span><span class=\"max\">12</span></span>\n ${meter}\n <span class=\"sizes\">${sizes}</span>\n <button type=\"button\" class=\"remove\" data-panel=\"${esc(p.id)}\" data-remove aria-label=\"Remove\">✕</button>\n </div>`;\n}\n\nfunction renderPanel(p, data, editMode) {\n let inner = '';\n try {\n if (p.source === 'added') {\n const t = chartTypes[p.type] || chartTypes.markdown;\n inner = t.render(data);\n } else if (typeof p.render === 'function') {\n inner = p.render({ data });\n } else {\n inner = '';\n }\n // Empty-state fallback: if the render produced nothing meaningful,\n // show a typography-first placeholder so users see WHY the slot is\n // blank (e.g. filtered everything out) rather than a broken panel.\n const stripped = String(inner || '').replace(/<[^>]+>/g, '').trim();\n if (!stripped) {\n inner = `<div class=\"panel-empty mono faint\">NO DATA · ADJUST FILTERS OR TIME RANGE</div>`;\n }\n } catch (err) {\n inner = `<div class=\"panel-empty mono faint\">PANEL ERROR · ${esc((err.message || err) + '').slice(0, 80)}</div>`;\n }\n const editAttrs = editMode ? ' draggable=\"true\"' : '';\n const editChrome = editMode ? renderEditChrome(p) : '';\n // A panel that declares `drilldown: { to: <dashId> }` adds a\n // data attribute the global click handler uses to route clicks\n // to the target dashboard with the clicked filter preserved.\n const drillAttr = p.drilldown?.to ? ` data-drilldown-to=\"${esc(p.drilldown.to)}\"` : '';\n const drillHint = p.drilldown?.to ? `<span class=\"drill-hint mono faint\">→ ${esc(p.drilldown.to.toUpperCase())}</span>` : '';\n return `\n <section class=\"panel${editMode ? ' edit' : ''}\" data-panel=\"${esc(p.id)}\" style=\"grid-column: span ${p.cols};\"${editAttrs}${drillAttr}>\n ${editChrome}\n ${p.eyebrow ? `<div class=\"key\">${esc(p.eyebrow)}${drillHint}</div>` : ''}\n ${inner}\n </section>`;\n}\n\nfunction renderAddPicker() {\n const items = chartTypeList.map((t) =>\n `<button type=\"button\" data-add=\"${esc(t.id)}\" title=\"${esc(t.describe || '')}\">${esc(t.name)}</button>`\n ).join('<span class=\"sep\">·</span>');\n return `\n <div class=\"add-picker\">\n <span class=\"key\" style=\"color:var(--z-accent);\">+ ADD PANEL</span>\n <span class=\"types\">${items}</span>\n </div>`;\n}\n\nasync function render() {\n const app = document.getElementById('app');\n // Resolve the active dashboard from either the default registry or\n // the user metadata store. User-cloned dashboards inherit their\n // render from their clonedFrom template.\n const allDash = mergedDashboards(defaults, { includeHidden: true });\n const dash = allDash.find((d) => d.id === state.route)\n || dashboardsInSection(state.section, allDash)[0]\n || registry['ai-overview'];\n const navDash = mergedDashboards(defaults);\n const dashboardsForSection = dashboardsInSection('dashboards', navDash);\n\n // For the SEARCH dashboard, eagerly run the search so panels see hits.\n if (dash.id === 'search-discover' && !state.search.result) {\n runSearchNow();\n }\n\n const activeFilters = currentFilters();\n let data;\n let fetchErr = null;\n // Section-level views (data/settings/users/alerts) get their own\n // context builder. Everything else goes through the regular query.\n if (state.section === 'data' || state.section === 'settings') {\n try {\n data = await buildSectionData(state.section);\n } catch (err) {\n data = {};\n fetchErr = err;\n }\n } else {\n state.loading = true;\n try {\n const result = await query({\n dashId: dash.id,\n range: state.time,\n customRange: state.time === 'CUSTOM' ? state.timeCustom : null,\n cluster: state.cluster,\n filters: activeFilters,\n });\n data = result.data;\n state.fetchedAt = result.meta.fetchedAt;\n state.fetchMs = result.meta.durationMs;\n state.fetchErr = null;\n } catch (err) {\n state.fetchErr = err.message || String(err);\n fetchErr = err;\n } finally {\n state.loading = false;\n }\n if (fetchErr) {\n app.innerHTML = `\n ${Nav({ sections: SECTIONS, activeSection: state.section, dashboards: dashboardsForSection, groups: DASHBOARD_GROUPS, activeDash: dash.id, theme: state.theme, edit: state.edit, status: navStatus() })}\n <div class=\"scene\"><div class=\"key\" style=\"margin-bottom:12px;\">ERROR</div><h1 class=\"h-scene\">CANNOT LOAD</h1></div>\n <pre class=\"mono faint\" style=\"white-space:pre-wrap; font-size:var(--fs-13);\">${esc((fetchErr && fetchErr.stack) || fetchErr)}</pre>\n <div style=\"margin-top:var(--sp-6);\"><button type=\"button\" data-retry class=\"text-btn\">RETRY</button></div>`;\n return;\n }\n }\n\n const view = dash.render({ data, time: state.time, search: state.search });\n // Let a user rename override the scene title. User-cloned dashboards\n // always use the user-chosen name; defaults only override if the user\n // has explicitly set an xerj.dashboards.names entry.\n try {\n const store = JSON.parse(localStorage.getItem('xerj.dashboards') || '{}');\n if (dash.isUser || (store.names && store.names[dash.id])) {\n view.title = (dash.name || view.title || '').toUpperCase();\n }\n } catch {}\n const merged = mergeLayout(view.panels, state.layouts[dash.id]);\n const panelsHtml = merged.length\n ? merged.map((p) => renderPanel(p, data, state.edit)).join('')\n : `<div class=\"mono faint\" style=\"grid-column: span 12; padding:var(--sp-6) 0;\">All panels hidden. Click RESET to restore defaults.</div>`;\n\n // Police-strip frame: a fixed-position overlay that lives in the page's\n // existing margins, so entering edit mode never shifts content. The frame\n // itself is a 1px dashed border around the viewport; the top strip carries\n // the EDIT MODE label and tips; the bottom strip carries the column index.\n const editFrame = state.edit ? `\n <div class=\"edit-frame\" aria-hidden=\"true\"></div>\n <div class=\"edit-strip-top\" role=\"status\">\n <span class=\"marker\">EDIT MODE</span>\n <span class=\"tips\">\n DRAG PANEL TO REORDER ·\n CLICK A <span class=\"key-bind\">NUMBER</span> TO RESIZE ·\n <span class=\"key-bind\">✕</span> TO REMOVE ·\n SCROLL FOR <span class=\"key-bind\">+ ADD</span>\n </span>\n <span class=\"meta\">${esc(dash.name.toUpperCase())} · ${merged.length} PANELS</span>\n </div>\n <div class=\"edit-strip-bottom\" aria-hidden=\"true\">${\n Array.from({ length: 12 }, (_, i) => `<span>${String(i + 1).padStart(2, '0')}</span>`).join('')\n }</div>\n ` : '';\n const gridOverlay = state.edit\n ? `<div class=\"edit-grid\" aria-hidden=\"true\">${'<span></span>'.repeat(12)}</div>`\n : '';\n const addHtml = state.edit ? renderAddPicker() : '';\n\n // Section-level views (alerts, data, users, settings) don't show the\n // inline time control — the time range is a dashboards-section concept.\n const hideTimeCtrl = state.section !== 'dashboards' && state.section !== 'discover';\n const showFilterBar = state.section === 'dashboards';\n const filterBarHtml = showFilterBar\n ? FilterBar({ filters: activeFilters, kql: serializeKql(activeFilters) })\n : '';\n const refreshHtml = hideTimeCtrl\n ? ''\n : RefreshCtrl({ active: state.refresh });\n const clusterHtml = hideTimeCtrl\n ? ''\n : ClusterCtrl({ clusters: listClustersSync(), active: state.cluster });\n const savedViewsHtml = showFilterBar\n ? SavedViews({ views: loadViews(), dashId: dash.id })\n : '';\n\n app.innerHTML = `\n ${Nav({\n sections: SECTIONS,\n activeSection: state.section,\n dashboards: dashboardsForSection,\n groups: DASHBOARD_GROUPS,\n activeDash: dash.id,\n theme: state.theme,\n edit: state.edit,\n mobile: state.mobile,\n status: navStatus(),\n })}\n ${state.mobile ? '<div class=\"iphone-frame\"><div class=\"iphone-notch\"></div><div class=\"iphone-screen\">' : ''}\n ${SceneHeader({\n title: view.title, kicker: view.kicker || 'OBSERVE', meta: view.meta || [state.time],\n editable: state.edit, dashId: dash.id,\n })}\n ${view.caption ? `<p class=\"caption\">${esc(view.caption)}</p>` : ''}\n ${hideTimeCtrl ? '' : `<div class=\"dash-ctrls\">${TimeCtrl({ active: state.time, custom: state.timeCustom })}${refreshHtml}${clusterHtml}</div>`}\n ${filterBarHtml}\n ${savedViewsHtml}\n <main class=\"canvas${state.edit ? ' edit' : ''}\" aria-label=\"${esc(dash.name)}\">${gridOverlay}${panelsHtml}</main>\n ${addHtml}\n ${state.mobile ? '</div><div class=\"iphone-home-bar\"></div></div>' : ''}\n ${Footer()}\n ${editFrame}\n `;\n app.setAttribute('aria-busy', 'false');\n\n // Restore focus on the search input (if we're on the search dashboard).\n if (state._focusSelector) {\n const el = document.querySelector(state._focusSelector);\n if (el) {\n el.focus();\n if (el.tagName === 'INPUT') {\n const v = el.value;\n el.setSelectionRange(v.length, v.length);\n }\n }\n state._focusSelector = null;\n }\n}\n\n// ---------- event delegation ------------------------------\nlet dragSrcId = null;\n\ndocument.addEventListener('click', (e) => {\n // Primary nav: top-level product section\n const secA = e.target.closest('[data-section]');\n if (secA) {\n e.preventDefault();\n const sid = secA.getAttribute('data-section');\n if (sid === 'dashboards') {\n location.hash = '#/dashboards';\n } else {\n location.hash = '#/' + sid;\n }\n return;\n }\n // Secondary nav: a specific dashboard inside the dashboards section\n const dashA = e.target.closest('[data-dash]');\n if (dashA) {\n e.preventDefault();\n const id = dashA.getAttribute('data-dash');\n location.hash = '#/dashboards/' + id;\n return;\n }\n // Secondary nav: a collapsed group tab — switch groups by landing\n // on the group's first dashboard.\n const groupBtn = e.target.closest('[data-dash-group]');\n if (groupBtn) {\n e.preventDefault();\n const firstId = groupBtn.getAttribute('data-dash-group-first');\n if (firstId) location.hash = '#/dashboards/' + firstId;\n return;\n }\n // Time range\n const tb = e.target.closest('[data-time]');\n if (tb) {\n state.time = tb.getAttribute('data-time');\n localStorage.setItem(LS.time, state.time);\n // When switching INTO custom and we have no stored endpoints,\n // seed a sensible default (now − 24h → now).\n if (state.time === 'CUSTOM' && !state.timeCustom.from) {\n const now = new Date();\n const prev = new Date(now.getTime() - 24 * 3600 * 1000);\n const fmt = (d) => d.toISOString().slice(0, 16);\n state.timeCustom = { from: fmt(prev), to: fmt(now) };\n localStorage.setItem('xerj.timeFrom', state.timeCustom.from);\n localStorage.setItem('xerj.timeTo', state.timeCustom.to);\n }\n writeUrlState();\n render();\n return;\n }\n // Refresh interval\n const rf = e.target.closest('[data-refresh]');\n if (rf) {\n setRefreshInterval(parseInt(rf.getAttribute('data-refresh'), 10));\n render();\n return;\n }\n // Manual retry on error\n if (e.target.closest('[data-retry]')) {\n render();\n return;\n }\n // Global filter bar: click-to-filter (used by FilterBar pills and\n // any click-to-filter affordance inside a panel — TopN rows, Dist\n // segments, heatmap cells).\n const fAdd = e.target.closest('[data-filter-add]');\n if (fAdd) {\n const raw = fAdd.getAttribute('data-filter-add');\n const idx = raw.indexOf(':');\n if (idx > 0) {\n const field = raw.slice(0, idx);\n const value = raw.slice(idx + 1);\n // Drilldown takes precedence when the panel declares one.\n const drillHost = fAdd.closest('[data-drilldown-to]');\n if (drillHost) {\n const toId = drillHost.getAttribute('data-drilldown-to');\n // Seed the target dashboard's filters with this value before\n // navigating so the destination renders pre-filtered. The\n // search-discover dashboard has its own filter store\n // (state.search.filters) — seed that one instead.\n if (toId === 'search-discover') {\n state.search.filters = { ...(state.search.filters || {}), [field]: value };\n state.search.result = null; // force re-run on render\n } else {\n state.filters[toId] = { ...(state.filters[toId] || {}), [field]: value };\n try { localStorage.setItem(LS.filters(toId), JSON.stringify(state.filters[toId])); } catch {}\n }\n // Resolve the target's actual section — some targets (like\n // search-discover) live outside the 'dashboards' section and\n // need a different hash shape (#/discover rather than\n // #/dashboards/search-discover).\n const all = mergedDashboards(defaults, { includeHidden: true });\n const target = all.find((d) => d.id === toId);\n const sectionId = target?.section || 'dashboards';\n location.hash = sectionId === 'dashboards' ? `#/dashboards/${toId}` : `#/${sectionId}`;\n return;\n }\n setFilter(field, value);\n render();\n }\n return;\n }\n // Remove one chip from a filter pill (multi-value OR filters).\n const fRem = e.target.closest('[data-filter-remove]');\n if (fRem) {\n const raw = fRem.getAttribute('data-filter-remove');\n const idx = raw.indexOf(':');\n if (idx > 0) {\n removeFilterValue(raw.slice(0, idx), raw.slice(idx + 1));\n render();\n }\n return;\n }\n if (e.target.closest('[data-filter-clear]')) {\n clearFilters();\n render();\n return;\n }\n // Cluster selector\n const cset = e.target.closest('[data-cluster-set]');\n if (cset) {\n state.cluster = cset.getAttribute('data-cluster-set');\n setDefaultCluster(state.cluster);\n writeUrlState();\n render();\n return;\n }\n // Save current view\n if (e.target.closest('[data-view-save]')) {\n saveCurrentView();\n render();\n return;\n }\n // Apply a saved view\n const vApply = e.target.closest('[data-view-apply]');\n if (vApply) {\n applyView(vApply.getAttribute('data-view-apply'));\n return;\n }\n // Delete a saved view\n const vDel = e.target.closest('[data-view-delete]');\n if (vDel) {\n const id = vDel.getAttribute('data-view-delete');\n if (confirm('Delete this view?')) {\n deleteView(id);\n render();\n }\n return;\n }\n // Theme\n const th = e.target.closest('[data-theme-set]');\n if (th) {\n applyTheme(th.getAttribute('data-theme-set'));\n render();\n return;\n }\n // Mobile preview toggle\n if (e.target.closest('[data-mobile-toggle]')) {\n state.mobile = !state.mobile;\n localStorage.setItem('xerj.mobile', state.mobile ? '1' : '0');\n document.documentElement.classList.toggle('mobile-preview', state.mobile);\n render();\n return;\n }\n // Edit toggle\n if (e.target.closest('[data-edit-toggle]')) {\n state.edit = !state.edit;\n localStorage.setItem(LS.edit, state.edit ? '1' : '0');\n render();\n return;\n }\n // Reset layout\n if (e.target.closest('[data-reset-layout]')) {\n const id = state.route;\n delete state.layouts[id];\n saveLayout(id);\n render();\n return;\n }\n // Resize (click a size number)\n const sz = e.target.closest('[data-size]');\n if (sz) {\n const pid = sz.getAttribute('data-panel');\n const cols = parseInt(sz.getAttribute('data-size'), 10);\n const dash = registry[state.route];\n const view = dash.render({ data: {}, time: state.time });\n mutate(state.route, view.panels, (ov) => { ov.cols[pid] = cols; });\n render();\n return;\n }\n // Remove panel\n const rm = e.target.closest('[data-remove]');\n if (rm) {\n const pid = rm.getAttribute('data-panel');\n const dash = registry[state.route];\n const view = dash.render({ data: {}, time: state.time });\n mutate(state.route, view.panels, (ov) => {\n if (!ov.hidden.includes(pid)) ov.hidden.push(pid);\n const idx = (ov.added || []).findIndex((a) => a.id === pid);\n if (idx >= 0) ov.added.splice(idx, 1);\n });\n render();\n return;\n }\n // Search: query type\n const qt = e.target.closest('[data-query-type]');\n if (qt) {\n state.search.type = qt.getAttribute('data-query-type');\n runSearchNow();\n state._focusSelector = '[data-search-input]';\n render();\n return;\n }\n // Search: index\n const si = e.target.closest('[data-search-index]');\n if (si) {\n state.search.index = si.getAttribute('data-search-index');\n runSearchNow();\n state._focusSelector = '[data-search-input]';\n render();\n return;\n }\n // Facet apply (click-to-filter) — also drives the click-to-filter on Hit\n // row values and the ✕ on filter pills (clicking an active value removes).\n const fa = e.target.closest('[data-facet-apply]');\n if (fa) {\n const raw = fa.getAttribute('data-facet-apply');\n const colonIdx = raw.indexOf(':');\n const field = raw.slice(0, colonIdx);\n const value = raw.slice(colonIdx + 1);\n const cur = state.search.filters[field];\n if (cur === value) delete state.search.filters[field];\n else state.search.filters[field] = value;\n runSearchNow();\n render();\n return;\n }\n // Clear all filters\n if (e.target.closest('[data-facet-clear]')) {\n state.search.filters = {};\n runSearchNow();\n render();\n return;\n }\n // Sort a Hits column (GH#696 / GH#737)\n const sortBtn = e.target.closest('[data-sort-field]');\n if (sortBtn) {\n state.search.sort = {\n field: sortBtn.getAttribute('data-sort-field'),\n dir: sortBtn.getAttribute('data-sort-dir'),\n };\n runSearchNow();\n render();\n return;\n }\n // Toggle time-column visibility (GH#3319)\n if (e.target.closest('[data-toggle-time]')) {\n state.search.showTime = !state.search.showTime;\n runSearchNow();\n render();\n return;\n }\n // Export Hits as CSV (GH#1992 — the #1 ask of all time)\n if (e.target.closest('[data-export-csv]')) {\n const hits = state.search.result?.hits || [];\n const cols = state.search.showTime\n ? ['_index', '_id', '_score', '_ts', '_source']\n : ['_index', '_id', '_score', '_source'];\n downloadText('xerj-search-' + new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-') + '.csv',\n 'text/csv', hitsToCsv(hits, cols));\n return;\n }\n // Export a panel chart as PNG (GH#1366 — 178 reactions)\n const pngBtn = e.target.closest('[data-export-png]');\n if (pngBtn) {\n const sec = pngBtn.closest('.panel');\n const svg = sec?.querySelector('svg.chart, svg.series');\n if (svg) {\n const id = sec.getAttribute('data-panel') || 'panel';\n svgToPng(svg, { filename: 'xerj-' + id + '.png' }).catch((err) =>\n console.error('PNG export failed', err));\n }\n return;\n }\n // --- MANAGE view click handlers -------------------------\n const mgUp = e.target.closest('[data-mg-up]');\n if (mgUp) {\n const id = mgUp.getAttribute('data-mg-up');\n const list = mergedDashboards(defaults, { includeHidden: true });\n const i = list.findIndex((d) => d.id === id);\n if (i > 0) {\n const order = list.map((d) => d.id);\n [order[i - 1], order[i]] = [order[i], order[i - 1]];\n reorderDashboards(order);\n render();\n }\n return;\n }\n const mgDown = e.target.closest('[data-mg-down]');\n if (mgDown) {\n const id = mgDown.getAttribute('data-mg-down');\n const list = mergedDashboards(defaults, { includeHidden: true });\n const i = list.findIndex((d) => d.id === id);\n if (i >= 0 && i < list.length - 1) {\n const order = list.map((d) => d.id);\n [order[i + 1], order[i]] = [order[i], order[i + 1]];\n reorderDashboards(order);\n render();\n }\n return;\n }\n const mgRename = e.target.closest('[data-mg-rename]');\n if (mgRename) {\n const id = mgRename.getAttribute('data-mg-rename');\n const current = mergedDashboards(defaults, { includeHidden: true }).find((d) => d.id === id);\n const name = prompt('Rename \"' + (current?.name || id) + '\":', current?.name || '');\n if (name != null) {\n renameDashboard(id, name);\n render();\n }\n return;\n }\n const mgHide = e.target.closest('[data-mg-hide]');\n if (mgHide) {\n const id = mgHide.getAttribute('data-mg-hide');\n const list = mergedDashboards(defaults, { includeHidden: true });\n const cur = list.find((d) => d.id === id);\n setHidden(id, !cur?.hidden);\n render();\n return;\n }\n const mgClone = e.target.closest('[data-mg-clone]');\n if (mgClone) {\n const id = mgClone.getAttribute('data-mg-clone');\n const current = mergedDashboards(defaults, { includeHidden: true }).find((d) => d.id === id);\n const name = prompt('Clone \"' + (current?.name || id) + '\" as:', (current?.name || 'Untitled') + ' (copy)');\n if (name) {\n const newId = createUserDashboard({ name, fromId: id });\n location.hash = '#/dashboards/' + newId;\n }\n return;\n }\n const mgDelete = e.target.closest('[data-mg-delete]');\n if (mgDelete) {\n const id = mgDelete.getAttribute('data-mg-delete');\n if (isUserDash(id) && confirm('Delete user dashboard \"' + id + '\"? This cannot be undone.')) {\n deleteUserDashboard(id);\n if (state.route === id) {\n location.hash = '#/settings';\n } else {\n render();\n }\n }\n return;\n }\n const mgNew = e.target.closest('[data-mg-new]');\n if (mgNew) {\n const fromId = mgNew.getAttribute('data-mg-new');\n const name = prompt(fromId ? 'New dashboard from \"' + fromId + '\" · Name:' : 'New blank dashboard · Name:', 'Untitled');\n if (name) {\n const newId = createUserDashboard({ name, fromId: fromId || null });\n location.hash = '#/dashboards/' + newId;\n }\n return;\n }\n const mgCluster = e.target.closest('[data-mg-cluster]');\n if (mgCluster) {\n setDefaultCluster(mgCluster.getAttribute('data-mg-cluster'));\n state._focusIndex = null;\n render();\n return;\n }\n const mgIndex = e.target.closest('[data-mg-index]');\n if (mgIndex) {\n state._focusIndex = mgIndex.getAttribute('data-mg-index');\n render();\n return;\n }\n if (e.target.closest('[data-mg-reset-all]')) {\n if (confirm('Reset ALL saved state? This wipes dashboards, layouts, theme, filters.')) {\n for (const k of Object.keys(localStorage)) {\n if (k.startsWith('xerj.')) localStorage.removeItem(k);\n }\n resetDashboards();\n location.reload();\n }\n return;\n }\n\n // Add panel (from ADD picker)\n const add = e.target.closest('[data-add]');\n if (add) {\n const typeId = add.getAttribute('data-add');\n const t = chartTypes[typeId];\n if (!t) return;\n const dash = registry[state.route];\n const view = dash.render({ data: {}, time: state.time });\n mutate(state.route, view.panels, (ov) => {\n ov.added = ov.added || [];\n const newId = typeId + '-' + Date.now().toString(36);\n ov.added.push({\n id: newId,\n type: typeId,\n eyebrow: t.name + ' · NEW',\n cols: t.cols || 6,\n });\n ov.order = ov.order || view.panels.map((p) => p.id);\n ov.order.push(newId);\n });\n render();\n // scroll to bottom so the new panel is visible\n requestAnimationFrame(() => window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' }));\n return;\n }\n});\n\n// ---------- search input (Enter to run) -------------------\ndocument.addEventListener('keydown', (e) => {\n // KQL-lite input on dashboards\n const kq = e.target.closest && e.target.closest('[data-kql-input]');\n if (kq) {\n if (e.key === 'Enter') {\n e.preventDefault();\n applyKqlInput(kq.value);\n state._focusSelector = '[data-kql-input]';\n render();\n } else if (e.key === 'Escape') {\n e.preventDefault();\n kq.value = '';\n applyKqlInput('');\n state._focusSelector = '[data-kql-input]';\n render();\n }\n return;\n }\n const si = e.target.closest && e.target.closest('[data-search-input]');\n if (si) {\n if (e.key === 'Enter') {\n e.preventDefault();\n state.search.q = si.value;\n runSearchNow();\n state._focusSelector = '[data-search-input]';\n render();\n } else if (e.key === 'Escape') {\n si.value = '';\n state.search.q = '';\n state.search.filters = {};\n runSearchNow();\n state._focusSelector = '[data-search-input]';\n render();\n }\n return;\n }\n // Inline rename of the scene title in edit mode (contenteditable h1)\n const rn = e.target.closest && e.target.closest('[data-rename-dash]');\n if (rn) {\n if (e.key === 'Enter') {\n e.preventDefault();\n const id = rn.getAttribute('data-rename-dash');\n const name = rn.textContent.trim();\n renameDashboard(id, name);\n rn.blur();\n render();\n } else if (e.key === 'Escape') {\n e.preventDefault();\n rn.blur();\n render();\n }\n }\n});\n// Custom time range — FROM/TO datetime-local inputs\ndocument.addEventListener('change', (e) => {\n const tf = e.target.closest && e.target.closest('[data-time-from]');\n const tt = e.target.closest && e.target.closest('[data-time-to]');\n if (tf || tt) {\n state.timeCustom = {\n from: document.querySelector('[data-time-from]')?.value || '',\n to: document.querySelector('[data-time-to]')?.value || '',\n };\n localStorage.setItem('xerj.timeFrom', state.timeCustom.from);\n localStorage.setItem('xerj.timeTo', state.timeCustom.to);\n writeUrlState();\n render();\n }\n});\n\n// blur-save for inline rename (clicking outside the title also commits)\ndocument.addEventListener('blur', (e) => {\n const rn = e.target.closest && e.target.closest('[data-rename-dash]');\n if (!rn) return;\n const id = rn.getAttribute('data-rename-dash');\n const newName = rn.textContent.trim();\n renameDashboard(id, newName);\n}, true);\n\n// ---------- drag and drop ---------------------------------\ndocument.addEventListener('dragstart', (e) => {\n if (!state.edit) return;\n const sec = e.target.closest('.panel.edit');\n if (!sec) return;\n dragSrcId = sec.getAttribute('data-panel');\n sec.classList.add('dragging');\n try {\n e.dataTransfer.effectAllowed = 'move';\n e.dataTransfer.setData('text/plain', dragSrcId);\n } catch {}\n});\ndocument.addEventListener('dragover', (e) => {\n if (!state.edit || !dragSrcId) return;\n const sec = e.target.closest('.panel.edit');\n if (!sec) return;\n e.preventDefault();\n document.querySelectorAll('.drop-before, .drop-after').forEach((el) => el.classList.remove('drop-before', 'drop-after'));\n const rect = sec.getBoundingClientRect();\n const after = e.clientX > rect.left + rect.width / 2;\n sec.classList.add(after ? 'drop-after' : 'drop-before');\n});\ndocument.addEventListener('dragleave', (e) => {\n const sec = e.target.closest('.panel.edit');\n if (sec && !sec.contains(e.relatedTarget)) sec.classList.remove('drop-before', 'drop-after');\n});\ndocument.addEventListener('drop', (e) => {\n if (!state.edit || !dragSrcId) return;\n const sec = e.target.closest('.panel.edit');\n if (!sec) return;\n e.preventDefault();\n const targetId = sec.getAttribute('data-panel');\n const insertAfter = sec.classList.contains('drop-after');\n document.querySelectorAll('.drop-before, .drop-after').forEach((el) => el.classList.remove('drop-before', 'drop-after'));\n if (!targetId || targetId === dragSrcId) return;\n\n const dash = registry[state.route];\n const view = dash.render({ data: {}, time: state.time });\n mutate(state.route, view.panels, (ov) => {\n const fullOrder = ov.order && ov.order.length ? ov.order.slice() : view.panels.map((p) => p.id);\n // Make sure both src and target are in the order list (they should be).\n const have = new Set(fullOrder);\n if (!have.has(dragSrcId)) fullOrder.push(dragSrcId);\n if (!have.has(targetId)) fullOrder.push(targetId);\n const from = fullOrder.indexOf(dragSrcId);\n fullOrder.splice(from, 1);\n let to = fullOrder.indexOf(targetId);\n if (insertAfter) to += 1;\n fullOrder.splice(to, 0, dragSrcId);\n ov.order = fullOrder;\n });\n render();\n});\ndocument.addEventListener('dragend', () => {\n document.querySelectorAll('.dragging').forEach((el) => el.classList.remove('dragging'));\n document.querySelectorAll('.drop-before, .drop-after').forEach((el) => el.classList.remove('drop-before', 'drop-after'));\n dragSrcId = null;\n});\n\n// ---------- route changes ---------------------------------\nwindow.addEventListener('hashchange', () => {\n const parsed = parseRoute();\n state.section = parsed.section;\n state.route = parsed.route;\n // A URL with query string (e.g. from a share link) should reapply.\n const urlState = parseUrlState();\n if (urlState.time) state.time = urlState.time;\n if (urlState.cluster) state.cluster = urlState.cluster;\n if (urlState.filters) {\n state.filters[state.route] = { ...(state.filters[state.route] || {}), ...urlState.filters };\n saveFilters(state.route);\n }\n writeUrlState();\n render();\n});\n\n// Boot the refresh interval if the user had one saved.\nif (state.refresh > 0) setRefreshInterval(state.refresh);\n\n// Restore mobile preview class if it was active.\nif (state.mobile) document.documentElement.classList.add('mobile-preview');\n\nrender();"
+ },
+ {
+ "label": "first-launch setup page",
+ "cmd": "curl -s \"http://localhost:9200/_xerj-console/setup\"",
+ "status": 200,
+ "pass": true,
+ "output": "<!doctype html>\n<html lang=\"en\" data-theme=\"night\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Xerj Console · setup</title>\n<meta name=\"color-scheme\" content=\"dark light\">\n<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">\n<link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin>\n<link href=\"https://fonts.googleapis.com/css2?family=Big+Shoulders+Display:wght@800;900&family=JetBrains+Mono:wght@400;500&family=Inter:wght@400;500;600&display=swap\" rel=\"stylesheet\">\n<link rel=\"stylesheet\" href=\"assets/tokens.css\">\n<link rel=\"stylesheet\" href=\"assets/base.css\">\n<link rel=\"icon\" href=\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='13' font-family='monospace' font-size='14' font-weight='900' fill='%23EEBB00'%3Ez%3C/text%3E%3C/svg%3E\">\n<style>\n body {\n min-height: 100vh; display: flex; align-items: center; justify-content: center;\n padding: 2rem;\n }\n .auth-card {\n background: var(--bg-surface, #15171a);\n border: 1px solid var(--border, #2a2d33);\n border-radius: 8px; padding: 2rem;\n max-width: 480px; width: 100%;\n color: var(--fg, #e6e8eb);\n }\n .auth-card h1 {\n font-family: 'Big Shoulders Display', sans-serif;\n font-weight: 900; font-size: 2.25rem; letter-spacing: -0.02em;\n margin: 0 0 .5rem; color: #EEBB00;\n }\n .auth-card p.lead { color: var(--fg-mute, #8a8e95); margin: 0 0 1.5rem; }\n .step { display: none; }\n .step.active { display: block; }\n label { display: block; font-weight: 500; margin: 1rem 0 .25rem; font-size: 0.875rem; }\n input[type=\"email\"], input[type=\"text\"] {\n width: 100%; padding: 0.625rem 0.75rem;\n background: var(--bg, #0c0d10);\n border: 1px solid var(--border, #2a2d33);\n border-radius: 4px; color: var(--fg, #e6e8eb);\n font-family: inherit; font-size: 0.9rem;\n }\n input:focus { outline: 2px solid #EEBB00; outline-offset: 1px; }\n button {\n background: #EEBB00; color: #0c0d10;\n border: none; padding: 0.75rem 1.5rem;\n font-weight: 600; border-radius: 4px;\n cursor: pointer; margin-top: 1.5rem;\n font-family: inherit; font-size: 0.9rem;\n }\n button:disabled { opacity: 0.5; cursor: not-allowed; }\n button.secondary { background: transparent; color: var(--fg-mute); border: 1px solid var(--border); }\n .err {\n background: #3a1a1a; color: #ff8a8a;\n padding: 0.75rem 1rem; border-radius: 4px;\n margin: 1rem 0; font-size: 0.875rem;\n font-family: 'JetBrains Mono', monospace;\n }\n .ok {\n background: #1a3a1f; color: #8aff9c;\n padding: 0.75rem 1rem; border-radius: 4px;\n margin: 1rem 0; font-size: 0.875rem;\n }\n .role {\n display: inline-block;\n background: #EEBB00; color: #0c0d10;\n padding: 0.125rem 0.5rem;\n border-radius: 3px; font-size: 0.75rem;\n font-weight: 700; letter-spacing: 0.05em;\n text-transform: uppercase;\n }\n</style>\n</head>\n<body>\n <div class=\"auth-card\">\n <h1>XERJ CONSOLE</h1>\n <p class=\"lead\">First-launch setup — claim this server by enrolling a passkey.</p>\n\n <div id=\"err\" class=\"err\" hidden></div>\n <div id=\"ok\" class=\"ok\" hidden></div>\n\n <!-- Step 1: collect email + display name (token already in URL fragment) -->\n <div id=\"step-info\" class=\"step active\">\n <p>You're claiming the role <span class=\"role\" id=\"role-pill\">owner</span> on this server.</p>\n <label for=\"email\">Email</label>\n <input id=\"email\" type=\"email\" placeholder=\"[email protected]\" required autocomplete=\"email\">\n\n <label for=\"display\">Display name</label>\n <input id=\"display\" type=\"text\" placeholder=\"Your name\" autocomplete=\"name\">\n\n <label for=\"pkname\">Passkey name (visible to you only)</label>\n <input id=\"pkname\" type=\"text\" value=\"My main key\" autocomplete=\"off\">\n\n <button id=\"btn-enrol\">Enrol passkey</button>\n </div>\n\n <!-- Step 2: in-flight WebAuthn ceremony -->\n <div id=\"step-touch\" class=\"step\">\n <p style=\"font-size: 1.05rem;\">Touch your security key, biometric sensor, or platform passkey now…</p>\n <p class=\"lead\" style=\"margin-top: 1rem;\">If your browser didn't prompt automatically, click <em>Try again</em>.</p>\n <button id=\"btn-retry\" class=\"secondary\">Try again</button>\n </div>\n\n <!-- Step 3: done -->\n <div id=\"step-done\" class=\"step\">\n <p style=\"font-size: 1.05rem; color: #8aff9c;\">✓ Passkey enrolled. Logging you in…</p>\n </div>\n </div>\n\n<script type=\"module\">\nimport { redeemMagic, beginEnrol, finishEnrol, b64uToBuf, bufToB64u } from './src/xerj-console-auth.js';\n\nconst $err = document.getElementById('err');\nconst $ok = document.getElementById('ok');\nconst $rolePill = document.getElementById('role-pill');\nconst $email = document.getElementById('email');\nconst $display = document.getElementById('display');\nconst $pkname = document.getElementById('pkname');\nconst $btnEnrol = document.getElementById('btn-enrol');\nconst $btnRetry = document.getElementById('btn-retry');\n\nfunction showStep(id) {\n for (const el of document.querySelectorAll('.step')) el.classList.remove('active');\n document.getElementById(id).classList.add('active');\n}\nfunction showError(msg) {\n $err.textContent = msg; $err.hidden = false;\n $ok.hidden = true;\n}\nfunction showOk(msg) {\n $ok.textContent = msg; $ok.hidden = false;\n $err.hidden = true;\n}\n\n// Pull token from URL fragment (#token=...). Hide it from history immediately.\nfunction tokenFromHash() {\n const frag = window.location.hash.replace(/^#/, '');\n const params = new URLSearchParams(frag);\n return params.get('token');\n}\nfunction clearHash() {\n history.replaceState(null, '', window.location.pathname + window.location.search);\n}\n\nconst token = tokenFromHash();\nif (!token) {\n showError('No magic-link token in URL. The link must include #token=…');\n $btnEnrol.disabled = true;\n}\n\n// Eagerly redeem the token on page load — it's single-use; we want\n// to consume it before the user does anything else.\nlet enrollmentSession = null;\n(async () => {\n if (!token) return;\n try {\n enrollmentSession = await redeemMagic(token);\n clearHash();\n if (enrollmentSession.role) $rolePill.textContent = enrollmentSession.role;\n if (enrollmentSession.email) $email.value = enrollmentSession.email;\n } catch (e) {\n showError('Could not redeem link: ' + e.message);\n $btnEnrol.disabled = true;\n }\n})();\n\nasync function enrol() {\n $err.hidden = true;\n if (!enrollmentSession) {\n showError('Enrollment session missing — reload from the magic link.');\n return;\n }\n const email = $email.value.trim();\n const display = $display.value.trim() || email;\n const pkname = $pkname.value.trim() || 'default';\n if (!email) {\n showError('Email is required.');\n return;\n }\n\n showStep('step-touch');\n\n try {\n const begin = await beginEnrol(enrollmentSession.enrollment_session_id, email, display);\n // Decode WebAuthn binary fields from base64url to ArrayBuffer.\n const opts = JSON.parse(JSON.stringify(begin.creation_options.publicKey));\n opts.challenge = b64uToBuf(opts.challenge);\n opts.user.id = b64uToBuf(opts.user.id);\n if (opts.excludeCredentials) {\n for (const c of opts.excludeCredentials) c.id = b64uToBuf(c.id);\n }\n\n const cred = await navigator.credentials.create({ publicKey: opts });\n if (!cred) throw new Error('Browser returned no credential.');\n\n // Re-encode the credential response for transport.\n const att = cred.response;\n const credPayload = {\n id: cred.id,\n rawId: bufToB64u(cred.rawId),\n type: cred.type,\n response: {\n clientDataJSON: bufToB64u(att.clientDataJSON),\n attestationObject: bufToB64u(att.attestationObject),\n },\n extensions: cred.getClientExtensionResults ? cred.getClientExtensionResults() : {},\n };\n\n await finishEnrol(\n enrollmentSession.enrollment_session_id,\n begin.challenge_id,\n credPayload,\n pkname, email, display\n );\n\n showStep('step-done');\n showOk('Enrolled. Redirecting…');\n setTimeout(() => { window.location.href = '/_xerj-console/'; }, 800);\n } catch (e) {\n showStep('step-info');\n showError(e.message || String(e));\n }\n}\n\n$btnEnrol.addEventListener('click', enrol);\n$btnRetry.addEventListener('click', () => { showStep('step-info'); });\n</script>\n</body>\n</html>"
+ }
+ ]
+ }
+]
\ No newline at end of file
diff --git a/demo/playbooks/run.mjs b/demo/playbooks/run.mjs
new file mode 100644
index 000000000..7d2579203
--- /dev/null
+++ b/demo/playbooks/run.mjs
@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// Xerj feature smoke-tests as reusable playbooks.
+//
+// Each playbook is a named use case (mapped to a docs page) made of steps.
+// Every step is a REAL command run against a live xerj; we capture the exact
+// command + its actual output, assert pass/fail, and emit three artifacts:
+//
+// casts/<id>.md human-readable cast ($ cmd → output) — for docs + screencasts
+// playbooks.json structured steps+outputs — for AISE scene generation
+// SMOKE_REPORT.md coverage + pass/fail summary
+//
+// Usage: node run.mjs (expects xerj live on :9200 ES-compat + :8080 native)
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = path.dirname(new URL(import.meta.url).pathname);
+const ES = 'http://localhost:9200';
+const NATIVE = 'http://localhost:8080';
+const CASTS = path.join(ROOT, 'casts');
+fs.mkdirSync(CASTS, { recursive: true });
+
+// ── one step: a real curl. `expect` may be {status} and/or {body:/re/}.
+// label is the human caption; `cmd` is rendered + executed verbatim.
+function curl({ method = 'GET', url, json, ndjson, headers = [] }) {
+ const args = ['-s', '-S', '-m', '20', '-w', '\n__HTTP__%{http_code}', '-X', method];
+ for (const h of headers) args.push('-H', h);
+ let shown = `curl -s${method === 'GET' ? '' : 'X' + method === 'sXGET' ? '' : ''} `;
+ if (json !== undefined) { args.push('-H', 'content-type: application/json', '--data', JSON.stringify(json)); }
+ if (ndjson !== undefined) { args.push('-H', 'content-type: application/x-ndjson', '--data-binary', ndjson); }
+ args.push(url);
+ // Render a clean, copy-pasteable curl for the cast
+ let render = `curl -s${method === 'GET' ? '' : ' -X' + method} "${url}"`;
+ if (json !== undefined) render = `curl -s${method === 'GET' ? '' : ' -X' + method} "${url}" \\\n -H 'content-type: application/json' \\\n -d '${JSON.stringify(json)}'`;
+ if (ndjson !== undefined) render = `curl -s -X${method} "${url}" \\\n -H 'content-type: application/x-ndjson' \\\n --data-binary $'${ndjson.replace(/\n/g, '\\n')}'`;
+ let out = '';
+ try { out = execFileSync('curl', args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 }); }
+ catch (e) { out = (e.stdout || '') + (e.stderr || String(e.message)); }
+ const m = out.lastIndexOf('\n__HTTP__');
+ let status = 0, body = out;
+ if (m >= 0) { status = parseInt(out.slice(m + 9).trim(), 10) || 0; body = out.slice(0, m); }
+ // pretty-print JSON bodies for the cast; keep the raw body for assertions
+ const raw = body.trim();
+ let pretty = raw;
+ try { pretty = JSON.stringify(JSON.parse(raw), null, 2); } catch {}
+ return { render, status, raw, body: pretty };
+}
+
+function run(step) {
+ const r = curl(step);
+ const okStatus = step.expect?.status ? r.status === step.expect.status : (r.status >= 200 && r.status < 300);
+ const okBody = step.expect?.body ? step.expect.body.test(r.raw) : true;
+ const pass = okStatus && okBody;
+ return { ...step, ...r, pass };
+}
+
+// Truncate long bodies for the cast (keep them readable)
+const clip = (s, n = 1400) => (s.length > n ? s.slice(0, n) + `\n… (${s.length - n} more bytes)` : s);
+
+// ───────────────────────────── PLAYBOOKS ─────────────────────────────
+// data-driven; each step is {label, method, url, json|ndjson, expect?}
+const TS = '2026-04-26T19:47:24Z';
+const PB = [
+ { id: '01-boot-health', doc: 'install / quickstart', title: 'Boot & health — one binary is up',
+ intro: 'Prove the single binary is serving the ES-compatible API (:9200) and the native ops API (:8080).',
+ steps: [
+ { label: 'cluster identity (ES-wire)', url: `${ES}/` },
+ { label: 'cluster health is green', url: `${ES}/_cluster/health`, expect: { body: /"status":"green"/ } },
+ { label: 'nodes listing', url: `${ES}/_cat/nodes?v` },
+ { label: 'native health (:8080)', url: `${NATIVE}/v1/health` },
+ { label: 'prometheus metrics (:8080)', url: `${NATIVE}/v1/metrics` },
+ ] },
+
+ { id: '02-quickstart-crud', doc: 'quickstart', title: 'Quickstart — index, document, get, search',
+ intro: 'Create an index with a mapping, write a document, read it back, and search it.',
+ steps: [
+ { label: 'create index w/ mapping', method: 'PUT', url: `${ES}/articles`,
+ json: { mappings: { properties: { title: { type: 'text' }, body: { type: 'text' }, views: { type: 'integer' }, tag: { type: 'keyword' } } } }, expect: { body: /"acknowledged":true/ } },
+ { label: 'index a document', method: 'PUT', url: `${ES}/articles/_doc/1`,
+ json: { title: 'Hello Xerj', body: 'one binary for search', views: 42, tag: 'intro' }, expect: { body: /"result":"created"/ } },
+ { label: 'get the document', url: `${ES}/articles/_doc/1`, expect: { body: /"found":true/ } },
+ { label: 'search it', method: 'POST', url: `${ES}/articles/_search`, json: { query: { match: { body: 'binary' } } }, expect: { body: /"title":"Hello Xerj"/ } },
+ ] },
+
+ { id: '03-ingest-bulk', doc: 'ingest', title: 'Bulk ingest — ES /_bulk wire protocol',
+ intro: 'Point any ES collector (Logstash/Filebeat/SDK) at Xerj — /_bulk works unchanged.',
+ steps: [
+ { label: 'bulk index 4 docs', method: 'POST', url: `${ES}/articles/_bulk`,
+ ndjson: ['{"index":{}}', '{"title":"A","body":"alpha vector","views":10,"tag":"a"}', '{"index":{}}', '{"title":"B","body":"beta search","views":20,"tag":"b"}', '{"index":{}}', '{"title":"C","body":"gamma logs","views":30,"tag":"a"}', '{"index":{}}', '{"title":"D","body":"delta agg","views":40,"tag":"b"}', ''].join('\n'), expect: { body: /"errors":false/ } },
+ { label: 'refresh to make searchable', method: 'POST', url: `${ES}/articles/_refresh` },
+ { label: 'count documents', url: `${ES}/articles/_count`, expect: { body: /"count":5/ } },
+ { label: 'cat indices', url: `${ES}/_cat/indices?v` },
+ ] },
+
+ { id: '04-full-text', doc: 'queries / playbooks/full-text', title: 'Full-text search — the ES query families',
+ intro: 'The query DSL your Discover muscle memory already knows.',
+ steps: [
+ { label: 'match', method: 'POST', url: `${ES}/articles/_search`, json: { query: { match: { body: 'search' } } } },
+ { label: 'match_phrase', method: 'POST', url: `${ES}/articles/_search`, json: { query: { match_phrase: { body: 'alpha vector' } } } },
+ { label: 'term (keyword)', method: 'POST', url: `${ES}/articles/_search`, json: { query: { term: { tag: 'a' } } } },
+ { label: 'terms', method: 'POST', url: `${ES}/articles/_search`, json: { query: { terms: { tag: ['a', 'b'] } } } },
+ { label: 'range', method: 'POST', url: `${ES}/articles/_search`, json: { query: { range: { views: { gte: 20 } } } } },
+ { label: 'bool must+filter', method: 'POST', url: `${ES}/articles/_search`, json: { query: { bool: { must: [{ match: { body: 'logs' } }], filter: [{ term: { tag: 'a' } }] } } } },
+ { label: 'prefix', method: 'POST', url: `${ES}/articles/_search`, json: { query: { prefix: { body: 'alp' } } } },
+ { label: 'wildcard', method: 'POST', url: `${ES}/articles/_search`, json: { query: { wildcard: { body: 'sea*' } } } },
+ { label: 'exists', method: 'POST', url: `${ES}/articles/_search`, json: { query: { exists: { field: 'title' } } } },
+ { label: 'highlight + sort + _source', method: 'POST', url: `${ES}/articles/_search`, json: { query: { match: { body: 'vector' } }, highlight: { fields: { body: {} } }, sort: [{ views: 'desc' }], _source: ['title', 'views'] } },
+ ] },
+
+ { id: '05-aggregations', doc: 'aggregations', title: 'Aggregations — the boardroom view',
+ intro: 'Metric + bucket aggregations over the live index.',
+ steps: [
+ { label: 'terms', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { by_tag: { terms: { field: 'tag' } } } } },
+ { label: 'stats', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { v: { stats: { field: 'views' } } } } },
+ { label: 'sum / avg / max / min', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { s: { sum: { field: 'views' } }, a: { avg: { field: 'views' } }, mx: { max: { field: 'views' } }, mn: { min: { field: 'views' } } } } },
+ { label: 'cardinality', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { uniq: { cardinality: { field: 'tag' } } } } },
+ { label: 'value_count', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { c: { value_count: { field: 'views' } } } } },
+ { label: 'histogram', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { h: { histogram: { field: 'views', interval: 10 } } } } },
+ { label: 'range', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { r: { range: { field: 'views', ranges: [{ to: 20 }, { from: 20 }] } } } } },
+ { label: 'percentiles', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { p: { percentiles: { field: 'views' } } } } },
+ { label: 'terms + nested avg', method: 'POST', url: `${ES}/articles/_search`, json: { size: 0, aggs: { by_tag: { terms: { field: 'tag' }, aggs: { avg_views: { avg: { field: 'views' } } } } } } },
+ ] },
+
+ { id: '06-vector-search', doc: 'vectors / playbooks/vector-search', title: 'Vector search — kNN, no Pinecone',
+ intro: 'dense_vector field + kNN retrieval are first-class in the same engine.',
+ steps: [
+ { label: 'create vector index', method: 'PUT', url: `${ES}/vstore`, json: { mappings: { properties: { text: { type: 'text' }, embedding: { type: 'dense_vector', dims: 4 } } } }, expect: { body: /"acknowledged":true/ } },
+ { label: 'bulk index vectors', method: 'POST', url: `${ES}/vstore/_bulk`, ndjson: ['{"index":{}}', '{"text":"red apple","embedding":[0.9,0.1,0.0,0.1]}', '{"index":{}}', '{"text":"green pear","embedding":[0.1,0.9,0.1,0.0]}', '{"index":{}}', '{"text":"blue car","embedding":[0.0,0.1,0.9,0.1]}', ''].join('\n'), expect: { body: /"errors":false/ } },
+ { label: 'refresh', method: 'POST', url: `${ES}/vstore/_refresh` },
+ { label: 'kNN nearest to [0.9,0.1,0,0.1]', method: 'POST', url: `${ES}/vstore/_search`, json: { knn: { field: 'embedding', query_vector: [0.9, 0.1, 0.0, 0.1], k: 2, num_candidates: 10 } } },
+ ] },
+
+ { id: '07-analyzers', doc: 'analyzers', title: 'Analyzers — _analyze',
+ intro: 'Inspect tokenization the way ES does.',
+ steps: [
+ { label: 'standard analyzer', method: 'POST', url: `${ES}/_analyze`, json: { analyzer: 'standard', text: 'The Quick, Brown Fox!' } },
+ { label: 'keyword analyzer', method: 'POST', url: `${ES}/_analyze`, json: { analyzer: 'keyword', text: 'The Quick, Brown Fox!' } },
+ { label: 'whitespace analyzer', method: 'POST', url: `${ES}/_analyze`, json: { analyzer: 'whitespace', text: 'The Quick, Brown Fox!' } },
+ ] },
+
+ { id: '08-mappings-templates-aliases', doc: 'config / operations', title: 'Mappings, templates & aliases',
+ intro: 'Schema introspection + index templates + aliases — ES-identical.',
+ steps: [
+ { label: 'get mapping', url: `${ES}/articles/_mapping` },
+ { label: 'put index template', method: 'PUT', url: `${ES}/_index_template/logs_tpl`, json: { index_patterns: ['logs-*'], template: { mappings: { properties: { '@timestamp': { type: 'date' }, level: { type: 'keyword' }, msg: { type: 'text' } } } } }, expect: { body: /"acknowledged":true/ } },
+ { label: 'add alias', method: 'POST', url: `${ES}/_aliases`, json: { actions: [{ add: { index: 'articles', alias: 'articles_live' } }] }, expect: { body: /"acknowledged":true/ } },
+ { label: 'search via alias', method: 'POST', url: `${ES}/articles_live/_search`, json: { size: 0, query: { match_all: {} } } },
+ ] },
+
+ { id: '09-log-analytics', doc: 'playbooks/log-analytics', title: 'Log analytics — Splunk/Kibana workload',
+ intro: 'Template-driven log index, time-series + level breakdown aggregations.',
+ steps: [
+ { label: 'bulk ingest logs (template applies)', method: 'POST', url: `${ES}/logs-2026-04/_bulk`, ndjson: [
+ '{"index":{}}', `{"@timestamp":"${TS}","level":"info","msg":"request ok","svc":"api"}`,
+ '{"index":{}}', `{"@timestamp":"${TS}","level":"error","msg":"timeout","svc":"api"}`,
+ '{"index":{}}', `{"@timestamp":"${TS}","level":"error","msg":"5xx upstream","svc":"web"}`,
+ '{"index":{}}', `{"@timestamp":"${TS}","level":"warn","msg":"slow query","svc":"db"}`, ''].join('\n'), expect: { body: /"errors":false/ } },
+ { label: 'refresh', method: 'POST', url: `${ES}/logs-2026-04/_refresh` },
+ { label: 'errors only (bool filter)', method: 'POST', url: `${ES}/logs-2026-04/_search`, json: { query: { term: { level: 'error' } } } },
+ { label: 'count by level', method: 'POST', url: `${ES}/logs-2026-04/_search`, json: { size: 0, aggs: { by_level: { terms: { field: 'level' } } } } },
+ { label: 'errors over time (date_histogram)', method: 'POST', url: `${ES}/logs-2026-04/_search`, json: { size: 0, query: { term: { level: 'error' } }, aggs: { t: { date_histogram: { field: '@timestamp', calendar_interval: 'day' } } } } },
+ ] },
+
+ { id: '10-migration-es', doc: 'migration-from-es', title: 'Migration from Elasticsearch — drop-in parity',
+ intro: 'The exact ES request bodies return ES-shaped responses — clients, Logstash, Kibana keep working.',
+ steps: [
+ { label: 'ES version handshake (Kibana checks this)', url: `${ES}/`, expect: { body: /"version"/ } },
+ { label: '_cat/indices (ops tooling)', url: `${ES}/_cat/indices?v` },
+ { label: 'scroll API (pagination)', method: 'POST', url: `${ES}/articles/_search?scroll=1m`, json: { size: 2, query: { match_all: {} } }, expect: { body: /_scroll_id/ } },
+ { label: '_delete_by_query', method: 'POST', url: `${ES}/articles/_delete_by_query`, json: { query: { term: { tag: 'b' } } }, expect: { body: /"deleted"/ } },
+ ] },
+
+ { id: '11-native-ops', doc: 'metrics / operations / api-native', title: 'Native ops API (:8080) — health & metrics',
+ intro: 'The native v1 surface for ops. NOTE: this binary implements health + metrics; the rest of the documented /v1 API is not yet live (captured as gaps).',
+ steps: [
+ { label: 'native health', url: `${NATIVE}/v1/health`, expect: { body: /"status"/ } },
+ { label: 'prometheus scrape', url: `${NATIVE}/v1/metrics`, expect: { body: /xerj_/ } },
+ { label: 'DOC GAP: /v1/health/ready', url: `${NATIVE}/v1/health/ready`, expect: { status: 200 } },
+ { label: 'DOC GAP: /v1/cluster/health', url: `${NATIVE}/v1/cluster/health`, expect: { status: 200 } },
+ { label: 'DOC GAP: /v1/admin/flush', method: 'POST', url: `${NATIVE}/v1/admin/flush`, expect: { status: 200 } },
+ { label: 'DOC GAP: /v1/admin/backup', method: 'POST', url: `${NATIVE}/v1/admin/backup`, json: {}, expect: { status: 200 } },
+ ] },
+
+ { id: '12-console-ux', doc: 'Xerj Console (xerj-ux)', title: 'Embedded Console UX',
+ intro: 'The console SPA ships inside the binary and is served at /_xerj-console/.',
+ steps: [
+ { label: 'console SPA shell', url: `${ES}/_xerj-console/`, expect: { body: /<!doctype html>/i } },
+ { label: 'console app bundle', url: `${ES}/_xerj-console/src/app.js`, expect: { body: /./ } },
+ { label: 'first-launch setup page', url: `${ES}/_xerj-console/setup` },
+ ] },
+];
+
+// ───────────────────────────── EXECUTE ─────────────────────────────
+const results = [];
+for (const pb of PB) {
+ const steps = pb.steps.map(run);
+ results.push({ ...pb, steps });
+ const ok = steps.filter((s) => s.pass).length;
+ console.log(`${ok === steps.length ? '✅' : '⚠️ '} ${pb.id} ${ok}/${steps.length} ${pb.title}`);
+
+ // per-playbook cast (docs + screencast ready)
+ let md = `# ${pb.title}\n\n_Use case doc: ${pb.doc}_\n\n${pb.intro}\n\n`;
+ for (const s of steps) {
+ md += `### ${s.pass ? '✅' : '❌'} ${s.label}\n\n\`\`\`bash\n${s.render}\n\`\`\`\n\n`;
+ md += `\`\`\`json\n${clip(s.body)}\n\`\`\`\n\n_HTTP ${s.status}_\n\n`;
+ }
+ fs.writeFileSync(path.join(CASTS, `${pb.id}.md`), md);
+}
+
+// machine-readable (for AISE scene generation)
+fs.writeFileSync(path.join(ROOT, 'playbooks.json'), JSON.stringify(
+ results.map((p) => ({ id: p.id, doc: p.doc, title: p.title, steps: p.steps.map((s) => ({ label: s.label, cmd: s.render, status: s.status, pass: s.pass, output: s.body })) })), null, 2));
+
+// summary report
+const total = results.reduce((a, p) => a + p.steps.length, 0);
+const passed = results.reduce((a, p) => a + p.steps.filter((s) => s.pass).length, 0);
+let rep = `# Xerj feature smoke-tests — coverage & results\n\n`;
+rep += `Generated by \`demo/playbooks/run.mjs\` against a live xerj (ES-compat :9200 + native :8080).\n\n`;
+rep += `**${passed}/${total} steps passing across ${results.length} use cases.**\n\n`;
+rep += `| # | use case | doc | steps | pass | cast |\n|---|---|---|---|---|---|\n`;
+for (const p of results) {
+ const ok = p.steps.filter((s) => s.pass).length;
+ rep += `| ${p.id.split('-')[0]} | ${p.title} | ${p.doc} | ${p.steps.length} | ${ok === p.steps.length ? `✅ ${ok}/${p.steps.length}` : `⚠️ ${ok}/${p.steps.length}`} | [cast](casts/${p.id}.md) |\n`;
+}
+rep += `\n## Failures / documented-but-unimplemented\n\n`;
+for (const p of results) for (const s of p.steps) if (!s.pass) rep += `- **${p.id}** · ${s.label} → HTTP ${s.status}\n`;
+rep += `\n_Each cast under \`casts/\` shows the exact \`curl\` + real response — copy into docs or drive an AISE screencast scene. Structured form in \`playbooks.json\`._\n`;
+fs.writeFileSync(path.join(ROOT, 'SMOKE_REPORT.md'), rep);
+
+console.log(`\n${passed}/${total} steps passing → demo/playbooks/SMOKE_REPORT.md (+ casts/, playbooks.json)`);