node-facts.sh: operator-verified rewrite (python; parallel; fixture self-test) - see ansible_showcase/node-facts-plan.md

README.md

@@ -833,6 +833,20 @@ debugging reference, see [VIBE.md](VIBE.md).
 | `restore-volumes.sh <name>` | Restore from backup |
 | `node-facts.sh` | Emit JSON node facts documents for monitoring and inventory |
 
+### node-facts.sh — one JSON facts document per node
+
+`./node-facts.sh [node_path ...] [--pretty]` prints one JSON line per node (schema v1): running client
+image/tag and reported version, peer count + peer version histogram + `newer_than_us`, the protocol
+upgrade schedule the running config knows (chain config / rollup config / beacon spec / avalanche
+`info.upgrades`), chain signals (avalanche ACPs), head, and for OP-stack / beacon pairs a `consensus`
+block with the same fields for the consensus client. Every field is present; anything a client cannot
+provide is `null` with a `reason`. Read-only: compose files + `docker ps` + HTTP through the local
+traefik routes (`/<node>`, `/<node>/node`, `/<node>/eth`), parallel over nodes and calls, ~200 ms per
+host. Exit 2 with one error line if `.env`/`COMPOSE_FILE` is unreadable. Consumers: JobServer verb
+`node-facts`, controller `node-facts-collect` (CouchDB `node_facts:*`), Checkmk `node_facts_check.py`.
+Self-test (no network, no docker): `./test-node-facts.sh` runs the real main body against
+`node-facts-test/` fixtures via `NODE_FACTS_FIXTURES`.
+
 ---
 
 ## 16. Learning More