Decision: Astro/rig-docs is the canonical home for the Rig whitepaper (2026-04-24)

Decision

Option A — dashecorp/rig-docs (Astro Starlight) is the single source of truth for the main Rig whitepaper.

dashecorp/rig-gitops/docs/whitepaper/ is the secondary surface. It MUST NOT diverge from rig-docs. The mechanism for keeping it in sync (build-step pull vs. redirect vs. deletion) is a follow-on implementation concern tracked in #190.

Context

The whitepaper existed in two repos with independent edit histories:

Surface	Repo	Path	Chapter count
research.rig.dashecorp.com/whitepaper/	rig-docs	src/content/docs/whitepaper/*.md	22 (includes 3 unique to Astro)
docs.rig.dashecorp.com/whitepaper/	rig-gitops	docs/whitepaper/*.md	19 chapters + large index.md

Files present in rig-docs but absent from rig-gitops: the-autonomous-engineering-rig.md, 2026-04-19-brain-and-memory.md, 2026-04-20-whats-next.md. Both repos share 19 common chapter files, several of which have diverged in content (different file sizes for the same filename).

Options considered

	Option A (chosen)	Option B	Option C
Canonical	rig-docs (Astro)	rig-gitops (MkDocs)	—
Secondary	rig-gitops syncs from rig-docs	rig-docs redirects	One site dropped entirely
Pros	richer frontmatter, Starlight search, active toolchain, already has more content	where 13-chapter whitepaper originated	simplest long-term
Cons	rig-gitops sync mechanism needs implementation	MkDocs in maintenance mode; Astro is chosen platform	breaks existing public URLs

Rationale

1. Consistent with existing tooling decision. decisions/2026-04-18-docs-tooling-decision.md already established Astro Starlight at research.rig.dashecorp.com as the primary docs surface. Treating rig-gitops/MkDocs as canonical would work against that decision.

2. rig-docs already has more content. Three chapters exist only in rig-docs. Canonicalising rig-gitops would require migrating those files backward — net negative.

3. MkDocs toolchain is in maintenance. Per the 2026-04-18 tooling decision, Material for MkDocs entered maintenance mode in November 2025. New authoring effort should not land there.

4. Starlight frontmatter schema is richer. rig-docs enforces type, audience, updated fields that the CI docs-check.yml validates. MkDocs ignores these fields, so canonicalising MkDocs would weaken schema enforcement.

5. Option C is ruled out because both docs.rig.dashecorp.com/whitepaper/ and research.rig.dashecorp.com/whitepaper/ have inbound links. Dropping one entirely causes broken URLs and loses rig-gitops MkDocs context (glossary, nav structure) that operator tooling may rely on.

What changes

rig-docs (canonical — source of truth)

• All whitepaper edits happen here, in src/content/docs/whitepaper/.
• PR review enforces the Starlight frontmatter schema (docs-check.yml).
• This is where new chapters are added.

rig-gitops (secondary — read-only)

• docs/whitepaper/ becomes a synced read-only copy OR a set of redirects to research.rig.dashecorp.com/whitepaper/.
• A clear “source” banner or link is added to every chapter page on docs.rig.dashecorp.com.
• Direct edits to rig-gitops/docs/whitepaper/ are blocked (enforcement mechanism TBD in #190).

CI divergence check (required by issue acceptance criteria)

• A new CI job must fail if any chapter file differs between rig-docs/src/content/docs/whitepaper/ and rig-gitops/docs/whitepaper/ (after stripping Starlight-only frontmatter).
• Implementation tracked in #190.

What this decision does not cover

• Sync mechanism. Whether rig-gitops pulls files via a build step, uses HTTP redirects, or deletes its copy and proxies — that is an implementation choice for #190.
• URL migration. If chapters are removed from docs.rig.dashecorp.com/whitepaper/, redirects must be configured. Not decided here.
• Non-whitepaper docs in rig-gitops. docs/ in rig-gitops contains many files that are NOT part of the whitepaper (runbooks, architecture docs, etc.). This decision only covers the docs/whitepaper/ subtree.

Rollback

If rig-docs Astro proves wrong, all chapter files are standard markdown with frontmatter. They can be served from MkDocs or any other SSG with minor config changes. Content portability is maintained.