Document module lifecycle states in machine status (Module Status API)

[btshrewsbury-viam]

Feature

Module Status API (announced 2026-07-14). Machine status now surfaces real-time, per-module lifecycle state through GetMachineStatus, so it is easy to tell whether a module downloaded, started, or crashed. Each module reports its state plus a last-updated timestamp and (on failure) an error message.

Accurate state names (verified against source)

The announcement email used friendly names ("pending, first run, running, failed, exiting"). The actual proto enum (viamrobotics/api#867, robot.v1.ModuleStatus.State) is:

Enum	Meaning
STATE_UNSPECIFIED	Unset
STATE_PENDING	Queued / not yet started
STATE_STARTING	Starting up (first run)
STATE_READY	Running normally
STATE_UNHEALTHY	Failed / errored
STATE_CLOSING	Exiting

Docs must use the real enum names, not the email's paraphrase.

Current docs coverage

Not documented for the new lifecycle states. Only the base GetMachineStatus appears, in the auto-generated robot API reference (static/include/robot/apis/generated/robot.md). The new per-module ModuleStatus / state enrichment is not surfaced anywhere.

Verified state / source PRs

• viamrobotics/rdk#6120 — "RSDK-13904 Add module status to machine status" (merged)
• viamrobotics/api#867 — "RSDK-14057 add module status to GetMachineStatusResponse" (merged)

Note: docs PR #5184 (GetStatus across component/service APIs) is a different API (per-resource GetStatus) and does not cover this.

Proposed docs work

• Type (Diátaxis): reference (the state enum + fields) + a short how-to/troubleshooting note (use module status to diagnose a module that failed to start).
• Placement: module lifecycle / troubleshooting docs under docs/build-modules/ (and confirm whether the generated robot API reference picks up ModuleStatus automatically — if so, do not hand-edit the generated file; add the explanatory/troubleshooting content in the hand-authored module docs).
• Draft learning objectives — users will be able to:
  1. [Apply] Read a module's lifecycle state from machine status to determine whether it is pending, starting, ready, unhealthy, or closing.
  2. [Diagnose] Use the state, last-updated timestamp, and error message to diagnose a module that failed to start.
  3. [Understand] Map each state to what the module is doing at that point in its lifecycle.

Target PR: additive edits to module docs (not the generated reference).