docs: add stateless validator guide

[flyq]

Summary

Adds a new Stateless Validator documentation layer at docs/stateless/, targeting node operators running the upstream stateless-validator Rust client.

Changes

• New page: docs/stateless/stateless-validator.md — end-to-end operator reference, covering:

  • Motivation (independent verification, SALT witnesses, low hardware cost, auditable TCB)
  • Installation from source
  • Quick start (first run anchoring with --genesis-file / --start-block; subsequent runs)
  • CLI flag and environment variable reference, mirrored from upstream clap definitions
  • Log configuration (LogArgs: filters, formats, rotation)
  • Prometheus metric reference from metrics::names
  • Background deployment patterns (systemd, Docker)
  • Trust model and pairing with op-node / replica nodes
  • Troubleshooting common failure modes (lag, reorgs, RPC errors)

• New layer rules: docs/stateless/AGENTS.md — writing conventions for the stateless layer (reference tone, copy-pasteable commands, placeholder style, verification-against-source requirement before editing flag/metric tables).

• docs/SUMMARY.md — adds the "Stateless Validator" section so GitBook navigation picks up the new page.

• AGENTS.md (root) — registers the new layer in the architecture table and the project tree.

• docs/AGENTS.md — adds stateless/ to the list of layers that use the terse reference tone.

Test plan

• Spot-check CLI flag / env var / metric tables against upstream stateless-validator source

[claude]

Review

Good addition — well-structured, thorough CLI reference, and the metrics table is genuinely useful. A few things to address before merging.

Missing AGENTS.md for the stateless/ layer
docs/AGENTS.md says each layer has its own AGENTS.md with layer-specific writing rules, and CLAUDE.md repeats this. The new docs/stateless/ directory doesn't have one. Either add a minimal AGENTS.md (audience: node operators; tone: terse reference, same as dev layer) or document why this layer shares conventions with an existing one.

Four inline comments on specific lines — see the diff for details:

• Line 60: genesis file link points to the org root, not a usable download location
• Line 62: e.g. → e.g.,
• Line 178: start_validator.sh always passes --genesis-file but the prose says to omit it on subsequent runs — needs clarification or a conditional
• Line 279: ## Related Pages → ## Related pages (sentence case)

[claude]

Good overall — well-structured, covers the full operator lifecycle, and the CLI flag tables are thorough. A few issues to resolve before merging:

4 existing threads still open (not yet addressed):

• ## Related Pages → sentence case (## Related pages)
• Missing comma: e.g. → e.g.,
• Background launch script passes --genesis-file unconditionally, but subsequent runs should omit it
• Genesis file link points to GitHub org root (https://github.com/megaeth-labs) — needs a specific repo/file

2 new issues (inline comments added):

• Prometheus example output (lines 191–193): the #-prefixed lines shown are Prometheus metadata, not gauge values — the actual grep output would show bare metric_name value lines
• Terminology (line 264): Mini-Blocks → mini-blocks per docs/AGENTS.md terminology table

[claude]

Review

The stateless validator guide is well-structured and thorough — the systemd deployment section, flag/metric tables, and troubleshooting entries are exactly right for this audience.

Must fix before merge:

• temp.md at repo root must be deleted. It's a stale scratch file that should not ship. It also uses the legacy STATELESS_VALIDATOR_LOG_* env var names that the guide itself says are deprecated, so it would actively mislead operators who copy from the wrong place.

Prior threads still unresolved — please address:

1. Prometheus output example is wrong (thread open on line 243) — the #-prefixed lines in the curl output block are HELP/TYPE metadata, not values; the actual gauge lines have no # prefix. The suggestion in the thread is correct.

2. STATELESS_VALIDATOR_GENESIS_FILE in the systemd env file (thread on genesis/start-block) — the env file sets this on every run, but the "Subsequent runs" section says to omit --genesis-file once the DB is initialised. Either confirm the binary silently ignores it on re-runs (and add a note), or remove it from the env file and document the one-time ExecStartPre bootstrap pattern.

3. Heading case — ## Related Pages → ## Related pages (sentence case per docs/AGENTS.md).

4. Missing comma — e.g. copied → e.g., copied.

5. mini-blocks link — the Related Pages section was previously flagged as missing a [mini-blocks](../mini-block.md) entry; the term was removed but the link was never added.

Resolved this round: genesis file link (now correctly points to the specific file in the repo) and systemd example request (now fully addressed).

[claude]

Good progress — the systemd rewrite and temp.md removal clean up the main structural concerns from the last round.

Two remaining items:

1. Open thread still unresolved — ## Related Pages (line 357) needs sentence case: ## Related pages. That thread has been open since the first review pass.

2. mini-block link was dropped rather than fixed — the previous review flagged Mini-blocks capitalisation; the response was to remove the link entirely. The cross-reference to mini-block.md is genuinely useful for operators who want to understand what block types the validator re-executes. Please restore it with the correct casing:

   - [mini-blocks](../mini-block.md) — the two block types the validator re-executes
   

[claude]

Review

Solid, well-structured guide — covers the full operator lifecycle from first-run anchoring through systemd hardening and monitoring. The layer AGENTS.md is a good addition and the flag/env-var tables are clear.

Resolved stale threads — the three open threads (heading case, trailing backslash, e.g., comma) are all fixed in the current file; resolved them above.

One remaining issue — see inline comment on the monitoring section: the grep example output omits the # HELP / # TYPE metadata lines that Prometheus includes and the current pattern would match. A grep -v '^#' stage fixes it.

Minor suggestion — the [mini-blocks](../mini-block.md) cross-link was present in an earlier revision and appears to have been dropped when the capitalization thread was resolved. The page exists at docs/mini-block.md and is directly relevant to operators (validators re-execute mini-blocks). Worth adding back.

Otherwise this is ready.

[claude]

Review: LGTM with no blocking issues

All previous threads have been addressed and resolved.

What's here:
The guide covers the full operator journey end-to-end: installation from source, first-run anchoring, subsequent restarts, systemd unit, monitoring via Prometheus, trust model, and troubleshooting. The layer AGENTS.md is well-structured and enforces the verify-against-source discipline for the flag/metric tables.

Specifically confirmed:

• The grep -v '^#' Prometheus fix is in the current diff — the output example now accurately reflects pipe behavior. (Thread resolved.)
• ../architecture.md and ../mini-block.md both exist in docs/, so all relative links are valid.
• One-sentence-per-line convention is followed throughout the prose.
• SUMMARY.md, root AGENTS.md, and docs/AGENTS.md are all updated consistently.
• No stale temp.md scratch file remains.

Ready to merge once the requested reviewers sign off.