Skip to content
Rig Docs

Brain map

One page, two diagrams. Both auto-derived — the architecture map from facts/*.yaml, the linkage graph from every doc’s frontmatter. Refresh your memory of what the rig knows about itself without reading every file.

1. Two-brain architecture

Section titled “1. Two-brain architecture”

The rig runs on one rig brain (this site) shared across tenants, and one project brain per product portfolio. Every agent fetches both at session start — rig brain first (platform), project brain second (what the project is).

flowchart LR
    ISSUE[/"📮 Issue<br/><small>e.g. rig-agent-runtime#N</small>"/]
    subgraph AGENTS["🤖 Live agents"]
        direction TB
        A_DEVE["Dev-E<br/><small>writes code</small>"]
        A_REVIEWE["Review-E<br/><small>reviews PRs</small>"]
        A_IBUILDE["iBuild-E<br/><small>macOS / iOS builds</small>"]
        A_PLANNERE["Planner-E<br/><small>plans sprints, manages backlog, assigns issues to agents</small>"]
    end
    subgraph BRAINS["🧠 The brain (markdown hub)"]
        direction TB
        RB["rig BRAIN.md<br/><small>indexes: repos · agents · surfaces · per-repo docs · events · gaps</small>"]
        PB_DASHE["dashecorp-docs BRAIN<br/><small>portfolio-specific</small>"]
    end
    subgraph TARGETS["📚 Pointed-to by BRAIN — what the agent actually reads"]
        direction TB
        T_REPO["docs.rig.dashecorp.com/components/&lt;repo&gt;/<br/><small>per-repo engineering docs</small>"]
        T_USERSTORY["research.rig.dashecorp.com/user-stories/<br/><small>why is this being built</small>"]
        T_RESEARCH["research.rig.dashecorp.com/research/<br/><small>investigation notes, prior art</small>"]
        T_WHITEPAPER["research.rig.dashecorp.com/whitepapers/<br/><small>design principles, constraints</small>"]
        T_PROPOSAL["research.rig.dashecorp.com/proposals/<br/><small>chosen approach, ADRs</small>"]
    end
    subgraph REPOS["📦 Rig source repos"]
        direction TB
        R_RIGGITOPS["rig-gitops"]
        R_RIGAGENTRUNTIME["rig-agent-runtime"]
        R_RIGMEMORYMCP["rig-memory-mcp"]
        R_RIGCONDUCTOR["rig-conductor"]
        R_RIGDOCS["rig-docs"]
        R_RIGTOOLS["rig-tools"]
        R_INFRA["infra"]
    end
    ISSUE ==>|"1 · dispatch"| A_DEVE
    A_DEVE ==>|"2 · WebFetch at session start"| RB
    A_REVIEWE ==>|"2 · WebFetch at session start"| RB
    A_IBUILDE ==>|"2 · WebFetch at session start"| RB
    A_PLANNERE ==>|"2 · WebFetch at session start"| RB
    RB ==>|"3 · per-repo doc index"| T_REPO
    RB ==>|"3 · user stories index"| T_USERSTORY
    RB ==>|"3 · research topic index"| T_RESEARCH
    RB ==>|"3 · whitepaper catalog"| T_WHITEPAPER
    RB ==>|"3 · proposals list"| T_PROPOSAL
    A_DEVE -.->|"if portfolio=Dashecorp"| PB_DASHE
    R_RIGDOCS -->|"facts/*.yaml · user stories<br/>research · whitepapers"| RB
    R_RIGDOCS -->|"src/content/docs/"| T_USERSTORY
    R_RIGDOCS -->|"src/content/docs/"| T_RESEARCH
    R_RIGDOCS -->|"src/content/docs/"| T_WHITEPAPER
    R_RIGDOCS -->|"src/content/docs/"| T_PROPOSAL
    R_RIGGITOPS -->|"docs/"| T_REPO
    R_RIGAGENTRUNTIME -->|"docs/"| T_REPO
    R_RIGMEMORYMCP -->|"docs/"| T_REPO
    R_RIGCONDUCTOR -->|"docs/"| T_REPO
    R_RIGTOOLS -->|"docs/"| T_REPO
    R_INFRA -->|"docs/"| T_REPO
    classDef brain stroke:#1976d2,stroke-width:3px
    classDef projectBrain stroke:#c2185b,stroke-width:3px
    classDef agent stroke:#7b1fa2,stroke-width:3px
    classDef repo stroke:#388e3c,stroke-width:2px
    classDef target stroke:#f57c00,stroke-width:3px
    classDef issue stroke:#c62828,stroke-width:3px
    class ISSUE issue
    class RB brain
    class PB_DASHE,PB_TZ projectBrain
    class A_DEVE,A_REVIEWE,A_IBUILDE,A_PLANNERE agent
    class R_RIGGITOPS,R_RIGAGENTRUNTIME,R_RIGMEMORYMCP,R_RIGCONDUCTOR,R_RIGDOCS,R_RIGTOOLS,R_INFRA repo
    class T_REPO,T_USERSTORY,T_RESEARCH,T_WHITEPAPER,T_PROPOSAL target

Follow the numbers. An issue lands on a rig repo (1) → the responsible agent picks it up and WebFetches BRAIN.md (2) → BRAIN's indexes (3) point at the specific per-repo docs, user stories, research notes, whitepapers, and proposals the agent needs. Everything an agent ever reads starts from BRAIN.
Auto-derived: agents from facts/agents.yaml, repos from facts/repos.yaml.

2. Doc linkage graph

Section titled “2. Doc linkage graph”

Every user story, research doc, proposal, and whitepaper declares its relationships in YAML frontmatter. The graph below is compiled from those declarations — change the frontmatter, change the graph.

110 docs · 218 links. Drag to pan · scroll to zoom · click a node to open its page · hover an edge to isolate. whitepaper story research proposal

Why this exists

Section titled “Why this exists”

Two audiences:

  • Fresh agents — one look at the architecture map answers “what knowledge sources exist, where are they, which do I fetch when assigned to repo X?”
  • Humans browsing — one look at the linkage graph answers “where did this idea come from, what stories fell out of this whitepaper, which PRs close this story?”

Both are derived from the same frontmatter that powers /llms.txt and the per-page RelatedDocs + SpawnedUserStories panels. No hand-maintenance.