Mermaid Diagrams In Generated Wiki Pages

Diagrams are part of high-quality wiki generation, not decoration. Where a flow, lifecycle, or data model is easier to grasp visually, embed a Mermaid diagram in a fenced ```mermaid block on the most relevant page.

Choosing a diagram type

• sequenceDiagram for runtime and request flows across components (auth flows, request lifecycles, agent tool loops).
• stateDiagram-v2 for lifecycles and state machines (job states, connection states, run phases).
• erDiagram for the data model: entities and their relationships.
• flowchart TD for branching control flow and decision logic.

Discipline

• Ground every diagram in inspected source. Do not invent participants, states, entities, or relationships the code does not support.
• Cover the high-value cases: add a diagram wherever a page documents a request or runtime flow, a call sequence, a lifecycle or state machine, or a data model. A repository wiki usually has several such diagrams, not one overall. Skip pages that are navigation, reference tables, or pure configuration.
• Still prefer a few strong diagrams over decorating every page: one accurate diagram on the page that needs it beats a diagram forced onto every page.
• Give each diagram a one-line caption directly below it stating what it shows.
• OpenWiki validates every mermaid fence after your run and converts fences that fail to parse into plain text fences. A degraded diagram is a quality failure; follow the syntax rules below so it does not happen.

Syntax safety

These rules prevent the most common render breakages. When in doubt, rephrase the label.