docs: simplify and correct Node Operators procedures

[pgarciagon]

Summary

Reworks Node Operators into clear procedures for operating the official koinos/koinos Docker Compose deployment directly. It targets Ubuntu production servers, keeps platform scope explicit, and does not introduce documentation-owned helper scripts or operator tooling.

This revision also simplifies the operator language and restores concise information that was useful in the published documentation without restoring stale tables, historical burn amounts, or unsafe quick starts.

What changed

• added a clearly identified new-node quick path for configure, validate, start, inspect, and stop;
• corrected the peer check so only entries below Connected peers count, never the node's own My address;
• replaced the permanent zero-restart requirement with a 30-second comparison that rejects an increasing restart count, a restart loop, a missing service, or container recreation;
• completed the UFW procedure with recovery SSH verification, explicit activation, status/listener checks, and external exposure verification;
• made update activation and rollback executable from /opt/koinos and /opt/koinos-next by using the explicit Compose project name koinos;
• restored Ubuntu/macOS/Windows scope, synchronization-log meanings, the non-ETA meaning of block time remaining, and a concise Proof-of-Burn/VHP explanation;
• added versioned discovery links and direct commands for Compose environment, profiles, services, service options, and multiaddr information;
• replaced audit-oriented role and process terminology with established operator language;
• removed the operator-facing “Safety classes” and “How commands are verified” sections.

Safety preserved

• no --profile all quick start;
• no executable KOIN burn, producer registration, or other irreversible transaction;
• Harbinger is explicitly not described as the current public testnet;
• backup checksum and archive-path checks, chain-ID verification, block verification, rollback copies, data preservation, and key/P2P identity separation remain in place;
• update, restore, reindex, and resync procedures retain executable rollback paths;
• no public helper scripts or batch files were added.

Upstream comparison

Reviewed against:

• the published docs.koinos.io/validators/ section;
• the current master branch;
• koinos/koinos@821674672e699bf56e94d7c0e8bce122e83d1482 for Compose profiles, configuration, environment variables, services, and command behavior.

Validation evidence

Passed locally on 2026-07-25:

• node --check scripts/verify-node-operator-commands.mjs;
• npm run node-commands:verify: 90 command blocks and 455 assertions, including negative fixtures for own-address-only peer logs, increasing restart counts, restart-loop state, missing UFW confirmation, and activation/rollback Compose paths;
• npm run examples:verify: 50 documentation examples and 50 manifest entries;
• npm run examples:syntax: 22 JavaScript files;
• npm run examples:test: 23 tests passed;
• npm run examples:start: 7 projects;
• npm run examples:smoke: 7 projects;
• npm run docs:links;
• MkDocs build;
• git diff --check.

Every page changed in this revision was reviewed locally at 1440×900 and 390×844. All 11 pages rendered with visible headings, readable 16 px mobile body text, no document-level horizontal overflow, no broken images, and no browser console errors. Long command lines and wide tables remained horizontally scrollable inside their own containers.

The MkDocs build still reports the two documented pre-existing warnings outside this scope: the missing exchanges/jsonrpc.md nav target and the missing interacting/koilib.md link from docs/index.md.

Checks that require a real synchronized node, recovery SSH path, public firewall, DNS, TLS certificate, or irreversible transaction remain explicit operator/test-server checks; CI does not claim to have executed those against production infrastructure.

PR state

This PR intentionally remains open as a draft targeting dev.

[netlify]

✅ Deploy Preview for koinos-documentation ready!

Name	Link
🔨 Latest commit	8d1ccfd
🔍 Latest deploy log	https://app.netlify.com/projects/koinos-documentation/deploys/6a646792feb9b40008b1bfe6
😎 Deploy Preview	https://deploy-preview-235--koinos-documentation.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pgarciagon]

Superseded by draft PR #238, which consolidates Node Operators, Architecture, Resources, and the complete four-chapter baseline report for a single review and merge into dev. The original branch and commits remain available; no content was discarded.