Skip to content

Project separation

When you have a new doc to write, the question is which repo's docs/ does it belong in? The answer depends on what the doc is about, not who's writing it.

Decision tree

What is the doc about?

├── A specific rig component's internals (a service, runtime, or CLI tool)
│       → that component's repo, in docs/
│       e.g. rig-agent-runtime/docs/claude-oauth-token.md
│
├── How the rig works as a whole (architecture, conventions, processes,
│   AGENTS.md, whitepaper)
│       → rig-gitops/docs/   (or rig-gitops/docs/whitepaper/)
│       e.g. rig-gitops/docs/onboarding.md
│
├── A research note, proposal, user story, or experiment
│       → rig-docs/src/content/docs/{research,proposals,user-stories}/
│       (Astro Starlight repo — the research.rig.dashecorp.com backend)
│
├── Rig-wide reference data (the BRAIN — repos, surfaces, agents, flows)
│       → rig-docs/facts/*.yaml + npm run brain (compiles BRAIN.md)
│
├── Infrastructure / DevOps for shared dashecorp platform (CF, GCP, GitHub)
│       → infra/docs/  (this repo)
│
└── Something completely outside rig (Tablez, Invotek, an iOS app)
        → that product's repo / docs site (out of scope here)

If you can't decide, default to the component repo. The aggregator pulls them all anyway; the distinction matters more for who maintains it than for where it ends up rendered.

Naming & frontmatter

Every doc needs YAML frontmatter:

---
title: <human title>
description: <one sentence — surfaces in nav and search>
---

Filenames: lowercase, kebab-case, .md. No spaces, no underscores.

What gets aggregated

scripts/build-docs.sh in rig-gitops walks these sources on every deploy:

Source Lands at
rig-gitops/docs/architecture-*.md /architecture/
rig-gitops/docs/onboarding.md etc. /guides/
rig-gitops/docs/whitepaper/*.md /whitepaper/
rig-gitops/AGENTS.md /reference/agents-md/
rig-docs/BRAIN.md /brain/
<component>/README.md /components/<component>/
<component>/docs/*.md /components/<component>/<file>/

If you put a doc somewhere not on this list, it won't appear on the live site. Either move it, or open a PR extending build-docs.sh to pull from the new location.

Per-repo docs/ — what's in scope

The aggregator pulls docs/*.md flat — no recursion into subdirectories. If you need nested docs (e.g. docs/runbooks/incident-foo.md), either flatten the layout or extend build-docs.sh to recurse.

This is a deliberate constraint to keep the aggregator simple and the URLs predictable.

Cross-repo references

Need to link from one component's docs to another's? Use the rendered URL, not a relative path:

See the [conductor API reference](/components/rig-conductor/api/) for details.

This survives the aggregator's flattening and renders correctly under the router (rig.dashecorp.com/docs/components/rig-conductor/api/).

For cross-references out of the aggregator (to research, to BRAIN, to a Pages site that's still standalone), use the absolute URL — https://rig.dashecorp.com/docs/brain/ or https://research.rig.dashecorp.com/research/.... Don't use raw GitHub blob URLs in published docs; they bypass the published surface.

Anti-patterns

  • Don't add a new top-level doc site for one feature. Five sites was already too many; we're consolidating to two backends.
  • Don't publish docs by enabling GitHub Pages on a component repo. The aggregator owns rendering; per-repo Pages publishing breaks the single-URL story.
  • Don't edit BRAIN.md by hand. Edit rig-docs/facts/*.yaml and run npm run brain. CI's brain:check rejects drift.
  • Don't commit a doc whose only purpose is to redirect a moved page. Use mkdocs' redirects plugin or accept the broken link warning during the transition.