docs(validate): operator runbook pages (MTN-116)

[JohnnyWyles]

Validate section: node/validator operational runbooks (MTN-116, under the MTN-111 content umbrella).

Operator review required. These are safety-critical (downtime and double-signing are slashable). I drafted the content that can be grounded in canonical sources (Cosmovisor, pruning/config, Prometheus instrumentation) and left explicit TODO(operator) markers + :::caution/:::danger admonitions for the validator-specific bits that must be confirmed before publishing. Search the diff for TODO(operator) to find every spot needing your input.

Review links point at this PR's Vercel preview build.

New pages

• Chain Upgrades and Cosmovisor — how governance upgrades work, Cosmovisor layout/env, pre-staging binaries. TODO: exact per-upgrade procedure + missed-upgrade recovery.
• Sync Options — snapshot vs state sync vs genesis, pruning vs archive, choosing by use case. TODO: current snapshot providers / state-sync RPCs.
• Node Configuration and Maintenance — app.toml / config.toml tuning. TODO: current seeds/peers.
• Monitoring and Alerting — Prometheus instrumentation, what to alert on. TODO: team Grafana dashboards / alert rules.
• Validator Security and Recovery — key security, sentry architecture, backup/DR. The double-signing hazard is stated unambiguously; the sentry topology and the exact backup/DR runbook are TODO (must not be guessed).

The Validate sidebar was reordered into a logical operator flow (install -> join -> upgrades -> sync -> config -> monitoring -> performance -> security -> tmkms -> validating -> relayer).

Safety-critical items to confirm before merge

• Per-upgrade procedure and missed-upgrade recovery (upgrades page)
• Current snapshot providers and state-sync servers (sync-options)
• Current seeds / persistent peers (node-configuration)
• Sentry topology + firewall/DDoS posture (security)
• Backup contents + failover runbook + priv_validator_state.json handling (security)

Cross-branch note

node-configuration references the network base fee but links the Integrate section generally rather than /integrate/fees (that page is on the unmerged MTN-114 branch, #338). Can be pointed at /integrate/fees once #338 merges.

---

Accuracy sweep (added after initial review)

A full multi-agent, adversarially-verified audit of the Validate section followed the initial runbooks (live-chain checks where relevant). 8 files changed.

Verified fixes:

• Blocker (financial): node-configuration.md minimum-gas-prices example was 0.025uosmo, below the 0.03 base fee and contradicting its own instruction → 0.03uosmo with a fee-market query pointer.
• validating-mainnet/testnet: create-validator narration corrected (example uses 400 OSMO, bullets said 500); invalid wosmongton@osmosis.labs contact domain → osmosis.team; gas-prices described as price-per-gas; malformed query staking validators flag order; KEY_NAME consistency; H1 casing; --chain-id dropped from read-only signing-info queries; testnet chain-id note.
• joining-mainnet/testnet: added --chain-id to init; reconciled RAM (32 GB minimum, 64 GB recommended for validators); added a caution that testnet seeds/peers rotate and must be confirmed against the chain registry.
• performance: fixed the benchstat example (step 2 checked out master instead of the feature branch); sanitized a leaked host/home path; dropped the invalid heap ?seconds param; converted en-dash glyphs to markdown bullets; removed a duplicate line.
• relayer-guide: matched the hermes sample output (1.13.3) to the build tag; replaced filler memo_prefix.
• index: extended the landing prose to cover the operations guides.

Still needs operator input: 6 TODO(operator) markers remain (snapshot providers, seeds/peers, sentry topology, backup/DR runbook, monitoring dashboards, missed-upgrade recovery).

Build passes.

---

Note

Low Risk
Documentation-only changes; no runtime or application code. Residual risk is publishing unverified operator guidance until TODO(operator) items are filled in.

Overview
Adds five new Validate operator runbooks (MTN-116): Chain Upgrades and Cosmovisor, Sync Options, Node Configuration and Maintenance, Monitoring and Alerting, and Validator Security and Recovery. Together they cover governance upgrades, sync/pruning choices, app.toml/config.toml tuning, Prometheus alerting, and double-signing / sentry / DR guidance, with cross-links into existing install, TMKMS, and performance pages.

Sidebar order on existing Validate docs is updated (sidebar_position only on performance, TMKMS, validating mainnet/testnet, relayer) so the section reads as an operator flow: install → join → upgrades → sync → config → monitoring → performance → security → TMKMS → validating → relayer.

Several spots are explicitly draft / operator-verify: TODO(operator) for live seeds, snapshot URLs, Grafana rules, sentry topology, and backup runbooks; :::caution / :::danger on values that must not be guessed before publish.

^{Reviewed by Cursor Bugbot for commit ad87df8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 18, 2026 10:48am