docs: restructure Mintlify site and refresh architecture diagrams
Merged
BN
6d ago+6767+6767+0123456789012345678901234567890123456789-17900-17900-01234567890123456789012345678901234567890123456789
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
.dotsources 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 validatemint broken-links --check-anchorsmint a11yjust docs-diagramsgit diff --checkcargo check --locked -p preloop-runner-server -p preloop-cli -p preloop-runner -p preloop-vm -p preloop-conformance -p preloop-gha-parsercargo test --locked -p runner-watchcargo test --locked -p preloop-gha-parser --libcargo check --locked -p preloop-vm --tests
All checks passed. Mintlify reported only existing brand-color contrast warnings; no accessibility issues remained.