docs: restructure Mintlify site and refresh architecture diagrams

Merged
BN
6d ago
+6767-17900

Summary

  • Restructure the Mintlify site into Overview, Control plane, and Runner tabs.
  • Replace long pasted design documents with shorter task-oriented pages.
  • Refresh public architecture diagrams with Graphviz .dot sources and SVG exports.
  • Document the current main-branch microVM pool (preloop-orchestrator โ†’ preloop-vm โ†’ SmolVM/AgentENV providers).
  • Restore and embed the repository's demo recordings in the introduction, quickstart, and debugging guide.
  • Move contributor-only trackers and implementation plans under docs/contributing/ and exclude them from Mintlify.
  • Correct stale documentation links in runtime help, runner-watch, contributor docs, migrations, and repository guidance.

The unmerged sandbox-service draft is preserved locally on the docs/site-rework-open-prs branch and is intentionally not included in this PR.

Diagram scope

Included:

  • system overview
  • control plane
  • runner protocol
  • job lifecycle
  • workflow parser
  • expression engine
  • microVM pool
  • observability
  • debug sessions
  • runner listener/worker

Intentionally excluded: sandbox-service, hosted-plane diagrams, hosted job lifecycle, container-build, and provider-internal SOMAC/VOWIN details.

Source of truth

Published docs describe public/main only. Unmerged PR-only behavior such as the sandbox-service CLI, actions policy, and JIT runner configuration was removed from the active docs.

Review fixes

  • Retargeted runtime error/help paths to the new documentation locations.
  • Fixed runner-watch's relocated fidelity tracker path and README link generation.
  • Converted contributor-doc links to repository-relative paths.
  • Restored deleted demo media and attached it to the relevant docs.

Verification

  • mint validate
  • mint broken-links --check-anchors
  • mint a11y
  • just docs-diagrams
  • git diff --check
  • cargo check --locked -p preloop-runner-server -p preloop-cli -p preloop-runner -p preloop-vm -p preloop-conformance -p preloop-gha-parser
  • cargo test --locked -p runner-watch
  • cargo test --locked -p preloop-gha-parser --lib
  • cargo check --locked -p preloop-vm --tests

All checks passed. Mintlify reported only existing brand-color contrast warnings; no accessibility issues remained.