Skip to content

Docs Architecture

This section is the source of truth for how rig docs work — where they live, how they get to the live site, how URLs are structured, and how to add a new one.

rig.dashecorp.com is the entry point. Everything below either powers it or feeds into it.

Why this exists

Until 2026-04-21, rig docs lived in four Pages projects (rig-research, rig-docs, conductor-e-docs, mac-executor-docs), with overlapping content, manual deploys, and ad-hoc URLs. People couldn't tell which site to use or whether a page they wrote would ever appear on a public URL.

Target state: one consumer-facing surface (rig.dashecorp.com), one aggregator that pulls from every component repo on a fixed schedule, and a single rule for where any new doc goes.

Topology — current

flowchart LR
  subgraph Sources["Source repos"]
    RD[dashecorp/rig-docs<br/>Astro Starlight + facts/]
    RG[dashecorp/rig-gitops<br/>docs-site/ + AGENTS.md + scripts/build-docs.sh]
    RC[dashecorp/rig-conductor<br/>docs/]
    RAR[dashecorp/rig-agent-runtime<br/>docs/]
    RMM[dashecorp/rig-memory-mcp<br/>docs/]
    RT[dashecorp/rig-tools<br/>docs/]
    INF[dashecorp/infra<br/>docs/]
  end

  subgraph Pages["Cloudflare Pages projects"]
    P_RR[research.rig.dashecorp.com<br/>Astro — research, BRAIN.md, user stories]
    P_RD[docs.rig.dashecorp.com<br/>MkDocs aggregator — engineering reference]
  end

  subgraph Front["Public surface"]
    R[rig.dashecorp.com<br/>Cloudflare Worker router]
  end

  RD -- "Astro build + wrangler deploy<br/>(per-repo CI)" --> P_RR

  RG -- "scripts/build-docs.sh<br/>(deploy-docs.yml: push + hourly)" --> P_RD
  RC -- "docs/ pulled by aggregator<br/>via gh api on every deploy" --> P_RD
  RAR -- " " --> P_RD
  RMM -- " " --> P_RD
  RT -- " " --> P_RD
  INF -- " " --> P_RD

  R -- "/docs/* + /docs/brain/<br/>(works — relative assets)" --> P_RD
  R -- "/research/*<br/>(broken CSS — absolute /_astro paths)" --> P_RR

Two retired sites — conductor-e-docs and mac-executor-docs — are still deployed but redundant; their content lives under /docs/components/rig-conductor/ and /docs/components/rig-agent-runtime/. Removed from the router 2026-04-21; deletion of the Pages projects is a follow-up.

Topology — current (final)

Three subdomains, no path-prefix proxying. Each backend serves at its own root, so absolute asset paths Just Work.

URL Backend Purpose
rig.dashecorp.com tiny landing Worker (managed in dashecorp/infra/cloudflare/dashecorp.com/workers/rig-router.js) Discoverable index — cards + deep links
docs.rig.dashecorp.com docs.rig.dashecorp.com (MkDocs aggregator) Engineering reference, brain, components, whitepaper
research.rig.dashecorp.com research.rig.dashecorp.com (Astro Starlight) Research notes, proposals, user stories

Legacy rig.dashecorp.com/docs/* URLs 301-redirect to docs.rig.dashecorp.com/* — bookmarks survive the cutover.

Why subdomains for everything: Astro emits absolute asset paths (/_astro/...) that broke under the original path-prefix proxy. We could have rebuilt the Astro source with a base config, but the all-subdomains pattern is simpler and standard. Adding a 4th backend later is one Tofu resource, no Worker edits.

See also