docs(factory): add the Running Factory runbook (local + cloud)

Merged
KH
2mo ago
+186-5

What

A new Factory docs page, Running Factory (/docs/factory/running), in the style of the Relayfile run-locally/cloud guides: a hands-on runbook for running the loop on one machine first, then each half in the cloud.

  • Prerequisites — tool table, including the requirement that the workspace GitHub App installation covers the target repos (otherwise every write 403s with Resource not accessible by integration)
  • Local — factory init, a durable broker identity (AGENT_RELAY_STATE_DIR + AGENT_RELAY_BROKER_NAME, why restarts collide without it), dry-run, the dispatch sequence (claim → isolated worktree → implementer → PR publish → reviewer → human review, mergePolicy: never), fleetHealth tuning for large workspaces, and a crash-recovery table with the three post-crash residues and their one-line fixes
  • Cloud — CLI control plane + fleet nodes (--backend relay, enrollment, agent-relay.ts, factory.node.json, repo:<label> tags, lease-fenced takeover, one-host-per-workspace, dedicated broker isolation) and the hosted control plane via @agent-relay/factory/hosted (createHostedFactory + DurableObjectHostedFactoryStateStore, the ports table, runOnce/ingestCompletion, epoch fencing, token roles)

Also registers the page in the Run nav group and bumps the sidebar version badge from the stale 0.1.34 to the published 0.1.86.

Why

The local runbook is distilled from a verified end-to-end run today (issue → dispatch → implementer agent → app-authored PR #7 → review → human merge on AgentWorkforce/factory-test-infra), including every failure mode hit along the way. The hosted-cloud section is written against the actual src/hosted API surface, not just the README.

Verification

  • npm --workspace web run test — 31/31 pass (product-docs, docs-markdown-components, llms-txt, code-fence-meta)
  • Frontmatter, internal links, and the nav slug resolve against the content loader path (content/docs/factory/running.mdx)

Summary by cubic

Adds a Running Factory runbook covering local dispatch and cloud deployment, and registers it in the Guides nav group. The page covers prerequisites, the full local loop, crash recovery, and both cloud shapes (CLI control plane with fleet nodes, hosted control plane). Aligns Where it runs with the hosted control plane, gates node up on Agent Relay 11.3.1, and bumps the sidebar version badge from 0.1.34 to 0.1.86.