Conventions
Conventions
All doc authors in this repo follow these rules. They are short, opinionated, and load-bearing. If a rule here conflicts with something you're tempted to do, the rule wins unless you open an ADR to change it.
Language
English for every architecture and operations page. Spanish is reserved for Ansuz-produced KB content and user-facing product copy.
Page frontmatter
Every page declares:
---
title: <short nav label>
description: <one-sentence summary, used for SEO and sidebar previews>
navigation:
icon: i-lucide-<icon-name>
---
title and description are required. navigation.icon is optional but strongly preferred — it lightens the sidebar. Icons must come from the Lucide set (i-lucide-*). Additional Docus frontmatter fields (seo, navigation.title, hidden) are fine when they serve a purpose.
Page structure
Every page opens with a single paragraph summarizing what it covers, placed between the H1 and the first ##. Prose is active voice, present tense: "Sigrun validates the token," not "The token will be validated."
Avoid version numbers in prose unless they are load-bearing. Link to the source-of-truth manifest (pyproject.toml, package.json) instead.
Code blocks carry language tags. Use filename labels when the filename clarifies context.
Cross-linking
Root-relative paths only:
[Ingestion pipeline](/sigrun/runtime/ingestion-pipeline)
Never ../ relative paths — they break when pages move. Never include the .md extension — Docus routes strip it.
Links to source code use the full repo URL with a deep file path. Line anchors are fine for stable symbols; avoid them for volatile code.
Callouts (MDC components)
Reserve callouts for things a reader would miss in flat text. Don't decorate prose.
::note— neutral context.::tip— actionable shortcut.::warning— something that will bite you (stale data, footguns).::caution— destructive if ignored (data loss, security).
Diagrams
Every runtime, deployment, and integration page includes at least one diagram. Every diagram is referenced from prose — no drop-and-walk. No ASCII art, whiteboard photos, or unsourced PNGs; if a diagram exists, its source exists in-repo.
Mermaid
Flows, sequence diagrams, simple ERs. Fenced inline:
```mermaid
sequenceDiagram
User ->> Sigrun: POST /chat
Sigrun -->> User: SSE stream
```
PlantUML
Structural (C4 L1/L2) and deployment diagrams. Source at content/assets/diagrams/<product>/<name>.puml, pre-rendered SVG committed alongside as <name>.svg. Embed with:
.puml files manually with plantuml -tsvg and commit both files together.When to reach for PlantUML
Prefer Mermaid. Reach for PlantUML only when its layout control actually matters: C4 diagrams that use C4-PlantUML, deployment diagrams with node stacks, or component maps with explicit swimlanes.
Folder structure
The repo is organized by concern:
content/1.platform/— cross-cutting primitives, consumed by ≥2 products.content/<N>.<product>/— per-product slices. New products copy the2.sigrun/shape.content/4.meta/— conventions, templates.content/assets/diagrams/— PlantUML sources and rendered SVGs.
Numeric prefixes order the sidebar; Docus strips them from routes.
Promoting to platform
A concern stays per-product until at least two products actually use it. Only then does it move to 1.platform/. Resist the urge to preemptively generalize.
ADRs
Per-product ADRs live at content/<product>/<N>.decisions/YYYY-MM-DD-<slug>.md. Cross-cutting ADRs live at content/1.platform/5.decisions/YYYY-MM-DD-<slug>.md. Use the template at /meta/adr-template.
Status values: proposed, accepted, superseded-by <link>. superseded-by carries a root-relative link to the replacing ADR so the chain stays navigable.