docs: add stateless validator guide

AGENTS.md

@@ -12,11 +12,12 @@ For GitBook syntax, custom blocks, configuration, and best practices, follow the
 
 The site is organized into layers, each targeting a different audience:
 
-| Layer              | Directory                                                 | Audience                        | Tone                               |
-| ------------------ | --------------------------------------------------------- | ------------------------------- | ---------------------------------- |
-| **User Guide**     | `docs/user/`                                              | End users (wallets, DeFi users) | Plain language, no code            |
-| **Developer Docs** | `docs/dev/`                                               | Dapp/contract builders          | Practical guidance, code examples  |
-| **Specification**  | [mega-evm repo](https://github.com/megaeth-labs/mega-evm) | Protocol implementers, auditors | Normative (MUST/SHALL), exhaustive |
+| Layer                   | Directory                                                 | Audience                        | Tone                               |
+| ----------------------- | --------------------------------------------------------- | ------------------------------- | ---------------------------------- |
+| **User Guide**          | `docs/user/`                                              | End users (wallets, DeFi users) | Plain language, no code            |
+| **Developer Docs**      | `docs/dev/`                                               | Dapp/contract builders          | Practical guidance, code examples  |
+| **Stateless Validator** | `docs/stateless/`                                         | Node operators                  | Reference, copy-paste commands     |
+| **Specification**       | [mega-evm repo](https://github.com/megaeth-labs/mega-evm) | Protocol implementers, auditors | Normative (MUST/SHALL), exhaustive |
 
 Each layer has its own `AGENTS.md` with layer-specific writing rules.
 The Specification layer is maintained in the [mega-evm repository](https://github.com/megaeth-labs/mega-evm) and synced into the same GitBook site via Git Sync.
@@ -36,12 +37,15 @@ It does not live in this repo — do not create or edit `docs/spec/` files here.
 │   ├── user/                  # User Guide layer
 │   │   ├── AGENTS.md          # User layer writing rules
 │   │   └── *.md
-│   └── dev/                   # Developer Docs layer
-│       ├── AGENTS.md          # Developer layer writing rules
-│       ├── send-tx/           # Submitting transactions
-│       ├── read/              # Reading from MegaETH (RPC, realtime API)
-│       │   └── rpc/           # RPC method reference pages
-│       └── execution/         # EVM differences, gas model, resource limits
+│   ├── dev/                   # Developer Docs layer
+│   │   ├── AGENTS.md          # Developer layer writing rules
+│   │   ├── send-tx/           # Submitting transactions
+│   │   ├── read/              # Reading from MegaETH (RPC, realtime API)
+│   │   │   └── rpc/           # RPC method reference pages
+│   │   └── execution/         # EVM differences, gas model, resource limits
+│   └── stateless/             # Stateless Validator layer
+│       ├── AGENTS.md          # Stateless layer writing rules
+│       └── *.md
 ├── .sisyphus/plans/           # Restructure planning docs
 └── .github/workflows/
     └── claude.yml             # Claude Code Action: PR review, interactive assistance

docs/AGENTS.md

@@ -10,7 +10,7 @@ The documentation has two tonal registers depending on where a page lives:
   Build an argument. Walk the reader through reasoning. Explain _why_ things are the way they are.
   These pages read like a well-written technical blog post — engaging, flowing prose that tells a story.
 
-- **Layer pages** (`user/`, `dev/`, `spec/`) use a **terse, reference tone**.
+- **Layer pages** (`user/`, `dev/`, `stateless/`, `spec/`) use a **terse, reference tone**.
   Short declarative sentences. Sentence fragments in table cells. Facts first, explanation second.
   Optimized for scanning and quick lookup. Each layer's `AGENTS.md` has additional tone rules.
 

docs/SUMMARY.md

@@ -37,3 +37,7 @@
 - [Build with AI](dev/build-with-ai.md)
 - [Tooling & Infrastructure](dev/tooling.md)
 - [Developer FAQ](dev/faq.md)
+
+## Stateless Validator
+
+- [Stateless Validator](stateless/stateless-validator.md)

docs/stateless/AGENTS.md

@@ -0,0 +1,43 @@
+# Stateless Validator — Writing Rules
+
+This layer targets **node operators** running the upstream [`stateless-validator`](https://github.com/megaeth-labs/stateless-validator) Rust client.
+Readers are comfortable on the Linux command line, know how to read a systemd unit, and want authoritative reference material they can copy-paste into a deployment.
+
+## Tone & Language
+
+- **Reference tone.** Short declarative sentences, facts first.
+- **Copy-pasteable commands.** Every shell block should run as shown against a real deployment (modulo placeholders).
+- **Verify against source.** Every CLI flag, env var, default value, and metric name must match the upstream repo. Before editing the flag or metric tables, fetch the current `bin/stateless-validator/src/main.rs`, `crates/stateless-common/src/logging.rs`, and `bin/stateless-validator/src/metrics.rs` and compare.
+- **Placeholders use angle brackets.** `<TRUSTED_BLOCK_HASH>`, `<HOST>` — not `0x1234...` or `...`.
+- **No marketing.** State what the validator does; skip "honest", "trust-minimized", "fastest".
+
+## What Belongs Here
+
+- Installation from source, system requirements, and supported platforms.
+- CLI flag and environment variable reference, mirrored from the upstream `clap` definitions.
+- Log configuration (filters, formats, rotation) from `LogArgs`.
+- Prometheus metric reference from `metrics::names`.
+- Background deployment patterns (systemd, Docker, PID-file scripts).
+- Trust model and pairing with `op-node` / replica nodes.
+- Troubleshooting the operator's day-to-day failure modes (lag, reorgs, RPC errors).
+
+## What Does NOT Belong Here
+
+- End-user wallet or bridging instructions → `docs/user/`.
+- Dapp / contract developer guidance → `docs/dev/`.
+- Normative protocol specification → [mega-evm repo](https://github.com/megaeth-labs/mega-evm).
+- Internal architecture of the validator crate (module layout, trait design) → the upstream repo README.
+
+## Formatting Preferences
+
+- Use `{% hint style="info" %}` for optional guidance (e.g., "prefer systemd over `nohup`").
+- Use `{% hint style="warning" %}` for operator-facing hazards (e.g., resetting the anchor wipes the DB).
+- Use tables for every flag / env-var / metric reference.
+- Use fenced code blocks with language identifiers (` ```bash `, ` ```toml `, ` ```ini `).
+
+## Before Changing a Flag, Env Var, or Metric
+
+1. Pull the current upstream file (`gh api repos/megaeth-labs/stateless-validator/contents/<path>`).
+2. Diff the upstream field names and defaults against the table on the page.
+3. Update the table — including the defaults, required-ness, and description.
+4. If the flag or metric was added or removed upstream, record the change in the PR description so reviewers can spot-check.