Data

{
  "owner": "mirendev",
  "repo": "runtime",
  "number": 963,
  "verdict": "ready",
  "event": "comment",
  "summary": "This draft adds the new `distributed-runners.md` page and two glossary entries (`Coordinator`, `Distributed Runner`) in `terminology.md`, with small cross-reference tweaks in `workload-identity.md` and `disks.md`, plus a sidebar entry. The docs are ready to hand off to human review.\n\n**Accuracy against the rest of the codebase.** The new page's claims are consistent with what the other docs already say. The \"disks pin to coordinator\" rule is confirmed by the `disks.md` text and its Limitations section. The workload-identity section on distributed runners (in `workload-identity.md`) already existed and matches the new page's description of token issuance routing through the coordinator. The scheduler preference for runners and the overlay network ranges (`10.8.0.0/16`, `10.10.0.0/16`) are stated as fact; I can't verify them from doc files alone, but they read like deliberate product details rather than guesses.\n\n**Security guidance is sound.** The :::warning and :::danger admonitions around join tokens are well-placed. The reusable-token section rightly emphasises keeping the secret in a secret manager and the cloud-init idempotency guard (`systemctl cat`) is a practical and correct pattern.\n\n**A few minor things worth noting:**\n\n- Line 58 of `distributed-runners.md`: the token is described as having \"the coordinator's address baked in\" — this is useful, but it isn't explained anywhere how a runner that has no pre-existing network path to the coordinator would resolve or reach it. That's probably fine for a high-level doc, but operators running across cloud VPCs may hit this and find no guidance. Worth a one-liner note or a follow-up issue.\n- The `--force` flag in the cloud-init bash snippet (line 135) is used alongside `--skip-system-check`, but `--force` semantics aren't described anywhere in the doc or referenced command. If `--force` implies something operationally significant (e.g. overwriting an existing config), that deserves a brief inline callout.\n- The sidebar addition puts `distributed-runners` in \"Run \u0026 Scale\" between `scaling` and `admin-interface` — that ordering is logical.\n\nOverall the prose is clear, internally consistent, and the structure (how it works → adding a runner → automating → operating → caveats → next steps) follows a natural operator journey. Nothing here blocks graduation to human review.",
  "comments": [
    {
      "path": "docs/docs/distributed-runners.md",
      "line": 135,
      "side": "RIGHT",
      "body": "The `--force` flag is used here but isn't described anywhere in this page or referenced to a command doc. If it has any destructive or surprising behavior (e.g. overwriting an existing config or bypassing a safety check), a brief inline explanation would help operators understand what they're opting into.",
      "ai_prompt": "In docs/docs/distributed-runners.md, line 135, the bash snippet passes --force to `miren runner install` without explanation. Add a short inline comment or a sentence in the surrounding prose that describes what --force does in this context (e.g. 'overwrites any partially written config from a previous attempt') so operators know what they are opting into. If the flag is benign in this specific context, say so explicitly."
    },
    {
      "path": "docs/docs/distributed-runners.md",
      "line": 58,
      "side": "RIGHT",
      "body": "The doc says the token has \"the coordinator's address baked in\", which implies the runner must be able to route to that address out of the box. Operators in multi-cloud or VPC scenarios may need to ensure connectivity before running `join`. A brief note here — even just \"ensure the runner machine can reach the coordinator's address on the required ports before joining\" — would save confusion.",
      "ai_prompt": "In docs/docs/distributed-runners.md around line 58, after stating that the token has the coordinator's address baked in, add a short note reminding operators that the runner machine must have network connectivity to the coordinator at that address before running `miren runner join`. This is particularly relevant for multi-cloud or private-network setups. One or two sentences is enough."
    }
  ],
  "posted_to_pr": true,
  "draft": true
}