Skip to content
Dashecorp Rig Docs

AGENTS.md (rig-docs)

Canonical source at AGENTS.md in the repo root. This is the wiki-navigable copy.

Purpose

Section titled “Purpose”

dashecorp/rig-docs is the static documentation site for the rig, built with Astro Starlight and deployed to Cloudflare Pages at https://rig-research.pages.dev.

  • User stories — markdown under src/content/docs/user-stories/, one file per story, frontmatter github_issue: points to the GitHub issue
  • Research — markdown under src/content/docs/research/, one file per focused question
  • Proposals — markdown under src/content/docs/proposals/, one file per decision
  • Reference — durable material under src/content/docs/reference/ (AGENTS.md, facts)
  • Diagrams — Mermaid source inline in markdown. .mmd sources under public/diagrams/ for direct linking. No PNG or SVG committed.

Authoring rules

Section titled “Authoring rules”
  1. Every file has YAML frontmatter with at minimum title, description, type, audience, created, updated, topic. Schema enforced in src/content.config.ts.
  2. User stories, research, and proposals are dated (YYYY-MM-DD-slug.md).
  3. Linkage is required, bidirectional, and rendered. Declare in frontmatter:
    • User story: research_docs: [paths] + proposal: path + github_issue: url
    • Research / proposal: user_story: path
    • Proposal: source_research: [paths] for multi-research synthesis
    • Superseding: supersedes: path + superseded_by: path
  4. A RelatedDocs panel renders above every page body showing the declared graph, plus backlinks from other pages. Agents consuming the rendered HTML (or /llms.txt) see the full relationship tree.
  5. Diagrams: Mermaid source as fenced code blocks. The remark-mermaid plugin wraps them in a <figure> containing both the rendered SVG (client-side) AND the source inside <details class="mermaid-source"> — so agents reading post-JS HTML keep access to the source.

Flow

Section titled “Flow”
flowchart LR
  H["Human (mobile/desktop)"] -->|GitHub issue| I["user-stories/YYYY-MM-DD-slug.md<br/>(github_issue: url)"]
  I -->|research_docs:| R1["research/YYYY-MM-DD-slug.md"]
  I -->|research_docs:| R2["research/YYYY-MM-DD-slug.md"]
  R1 -->|user_story:| I
  R2 -->|user_story:| I
  I -->|proposal:| P["proposals/YYYY-MM-DD-decision.md"]
  R1 -.->|source_research:| P
  R2 -.->|source_research:| P
  P -->|Review-E + human gate| M["merged to main"]
  M -->|Cloudflare Pages deploy| S["rig-research.pages.dev"]
View Mermaid source
flowchart LR
  H["Human (mobile/desktop)"] -->|GitHub issue| I["user-stories/YYYY-MM-DD-slug.md<br/>(github_issue: url)"]
  I -->|research_docs:| R1["research/YYYY-MM-DD-slug.md"]
  I -->|research_docs:| R2["research/YYYY-MM-DD-slug.md"]
  R1 -->|user_story:| I
  R2 -->|user_story:| I
  I -->|proposal:| P["proposals/YYYY-MM-DD-decision.md"]
  R1 -.->|source_research:| P
  R2 -.->|source_research:| P
  P -->|Review-E + human gate| M["merged to main"]
  M -->|Cloudflare Pages deploy| S["rig-research.pages.dev"]

Local dev

Section titled “Local dev”
Terminal window
npm install
npm run dev

Deploy

Section titled “Deploy”

Merges to main publish via .github/workflows/deploy.yml. The deploy job is skipped when CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID secrets are missing.