docs: add stateless validator guide

[flyq]

Summary

• Adds docs/stateless/stateless-validator.md — a guide for operators running a MegaETH stateless validator (system requirements, installation, first-run bootstrap via --genesis-file + --start-block, CLI flags mirrored by env vars, logging config, background deployment, Prometheus metrics, trust model, and troubleshooting).
• Introduces Stateless Validator as a new top-level chapter in docs/SUMMARY.md, alongside User Guide and Developer Docs.
• Content fact-checked against the upstream stateless-validator source: clap flag definitions in bin/stateless-validator/src/main.rs, LogArgs in crates/stateless-common/src/logging.rs, and the metric names exposed by the running binary.

Test plan

• GitBook preview renders the new chapter under the correct section
• Internal links resolve (../architecture.md, ../mini-block.md)
• External links resolve (stateless-validator repo, SALT repo, scripts/validator-status.sh)
• Frontmatter description appears as SEO meta
• Hint blocks ({% hint style="info" %}) render correctly

[claude]

Heading case violation — sentence case required per docs/AGENTS.md.

Suggested change

	## Related Pages
	## Related pages

[claude]

Missing comma after e.g. — standard usage is e.g.,.

Suggested change

	Pick any recent block hash you trust (e.g. copied from a known explorer or from another operator already running the validator).
	Pick any recent block hash you trust (e.g., copied from a known explorer or from another operator already running the validator).

[claude]

The script always passes --genesis-file, but the prose above (line 83) says to omit it on subsequent runs. If the binary errors when --genesis-file is given but the DB is already initialized, this script will break on restart. Either:

• Confirm the binary silently ignores --genesis-file on re-runs (and add a note), or
• Make the flag conditional: ${GENESIS_FILE:+--genesis-file "$GENESIS_FILE" \}

[claude]

This link goes to the GitHub org root, not a specific repo or file. An operator following these steps can't actually find the genesis file from this link. Point to the specific file or repo (e.g., the stateless-validator repo's README or a releases page).

[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]

The example output is incorrect. In Prometheus text format, # marks HELP/TYPE metadata lines — gauge values are emitted on lines without #. This grep would actually return both the metadata lines and the bare value lines; what's shown here omits the values entirely.

Suggested change

	# stateless_validator_local_chain_height 13592258
	# stateless_validator_remote_chain_height 13592262
	# stateless_validator_validation_lag 4
	stateless_validator_local_chain_height 13592258
	stateless_validator_remote_chain_height 13592262
	stateless_validator_validation_lag 4

[claude]

Terminology violation — per docs/AGENTS.md, the term is always mini-block (lowercase).

Suggested change

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

[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