Document Hermes API_SERVER_KEY restart, rebuild, and retrieval lifecycle

[ericksoa]

Description

Document the Hermes API_SERVER_KEY lifecycle so operators can distinguish ordinary restart stability from expected rebuild rotation.

The field report claimed the token rotates on every gateway start, but current main and likely deployed v0.0.83 do not reproduce that defect:

• agents/hermes/runtime-config-guard.py:4811-4825 preserves an existing valid 64-character generated key.
• agents/hermes/start.sh:2660,2683 uses that idempotent helper for root and non-root startup.
• test/hermes-runtime-api-key.test.ts:447 proves ordinary restart preservation.
• Missing/malformed values are intentionally replaced, and different sandbox homes receive different keys.
• Rebuild replaces the sandbox home; .hermes/.env is user-managed rather than durable state, so a rebuilt sandbox mints a new key.
• nemoclaw <sandbox> gateway-token --quiet is the sanctioned machine-readable retrieval path and is already implemented/documented, but its lifecycle is not explained.

Expected contract:

Operation	Key behavior
Hermes gateway restart	Preserve
Sandbox stop/start	Preserve for the same sandbox filesystem
Host OpenShell gateway restart	Preserve
Sandbox rebuild/replacement	Generate a new key
Missing/malformed key	Generate a new key
Different sandbox	Different key

If a plain restart changes the value without sandbox replacement, that remains a bug and should include before/after sandbox identity plus redacted mint logs.

Affected Page

docs/reference/commands.mdx (gateway-token), rebuild documentation, and the planned headless/server deployment guide.

Issue Type

Missing documentation

Suggested Fix

• State that the key is generated once per sandbox home and preserved across ordinary gateway/sandbox/host-gateway restarts.

• State that missing/malformed values and rebuild/replacement generate a new key.

• Give the copyable retrieval command:

  TOKEN=$(nemoclaw <sandbox> gateway-token --quiet)

• Explain that the sandbox must be running, the value is a password, and implementation-owned .env files must not be scraped or edited.

• Add a rebuild warning that the Hermes API bearer token will change and point to gateway-token --quiet.

• Add a docs-contract test plus rebuild-level rotation/retrieval coverage; preserve the ordinary-restart negative test.

Acceptance Criteria

• Docs clearly distinguish restart from rebuild.
• Operators have a supported programmatic retrieval path.
• Exact rotation conditions are documented.
• Rebuild output points to retrieval.
• Regression coverage proves ordinary restart preservation and rebuild rotation.

No open duplicate was found. Related closed issues #5249 and #3180 predate the current token retrieval contract.

[miyoungc]

PR #7212 addresses this issue, and the documentation updates look good to me. The PR also adds E2E coverage for the Hermes token lifecycle, which falls outside my review area. Could someone from the development team please review the implementation and test coverage?