diagram

name	diagram
description	Show Mermaid diagrams in Mission Control's diagram viewer instead of dumping raw syntax in the terminal. Use when the user asks for a diagram, flowchart, sequence diagram, architecture sketch, state machine, ER diagram, or any visual that Mermaid can render — and whenever a diagram would clarify a complex flow. Requires a Mission Control agent session (MC_API_URL and MC_API_TOKEN are injected automatically). Not for ASCII art in chat, image generation, or projects running outside Mission Control.
user-invocable	true

Mission Control agent sessions receive env vars automatically:

• MC_API_URL — loopback API base (e.g. http://127.0.0.1:54321)
• MC_API_TOKEN — bearer token for that API
• MC_TASK_ID — the active task/session id
• MC_THEME — Mission Control UI theme: dark or light

Do not print Mermaid to the user and stop. POST it to Mission Control so the app opens an interactive viewer modal. The viewer applies Mission Control theme colors automatically — your job is to avoid fighting that styling.

When to use

• User asks for a diagram, flowchart, sequence diagram, architecture map, or state chart
• You are explaining a multi-step system and a diagram would land faster than prose
• You already drafted Mermaid and would otherwise paste it in the terminal

Skip when Mission Control env vars are missing (plain shell outside MC) — fall back to inline Mermaid in markdown.

API contract

POST $MC_API_URL/api/diagram?taskId=$MC_TASK_ID
Authorization: Bearer $MC_API_TOKEN
Content-Type: application/json

{
  "source": "<mermaid source>",
  "title": "Optional title shown in the modal",
  "format": "mermaid",
  "theme": "dark"
}

theme is optional metadata — pass "$MC_THEME" when set so Mission Control knows which UI theme was active. The viewer still re-renders using the live app theme; you do not need to bake colors into source for MC.

Success (200): { "ok": true, "id": "<uuid>" } — Mission Control opens the viewer automatically.

Common errors:

• 400 — missing/invalid body, empty source, or taskId query param missing
• 401 — bad or missing bearer token
• 404 — unknown taskId

Theme rules (critical)

Mission Control runs in dark mode by default. Diagrams fail when agents embed colors that disappear on dark backgrounds (dark gray boxes, faint borders, #111 fills).

1. Do not override Mermaid theme in source. Never use %%{init: {'theme':'dark'}}%%, %%{init: {'theme':'base', 'themeVariables': ...}}%%, YAML frontmatter theme blocks, or classDef / style with hardcoded hex/rgb fills.
2. Use plain Mermaid syntax. Let Mission Control's viewer apply accent, surface, text, and border tokens from the active UI theme.
3. Read $MC_THEME. When it is dark, avoid near-black node/participant fills. When it is light, avoid near-white fills on white backgrounds.
4. Sequence diagrams: use default participant boxes — do not set actor background colors inline. Example:

sequenceDiagram
  participant U as User
  participant MC as Mission Control
  U->>MC: POST /api/diagram
  MC-->>U: Open themed viewer

5. Flowcharts: prefer unstyled nodes (A[Step], B{Decision?}) over A["Step"]:::darkClass.

Rules

1. Always send valid Mermaid in source. No markdown fences — raw diagram text only.
2. Keep diagrams focused. Prefer one concern per diagram; split large maps into multiple POSTs with distinct titles.
3. Set a short title when the diagram has a clear name (e.g. "Auth flow", "Worktree lifecycle").
4. Pass "theme": "$MC_THEME" in the JSON body when $MC_THEME is set.
5. Tell the user briefly that the diagram opened in Mission Control — don't repeat the full source unless they ask.
6. On HTTP failure, show the error and paste the Mermaid source as a fallback.
7. Verify env vars before POSTing. If MC_API_URL, MC_API_TOKEN, or MC_TASK_ID is empty, tell the user the session is not running inside Mission Control.

Examples

Minimal POST (preferred — no jq required)

curl -sS -X POST "$MC_API_URL/api/diagram?taskId=$MC_TASK_ID" \
  -H "Authorization: Bearer $MC_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "source": "flowchart LR\n  A[Draft Mermaid] --> B[POST /api/diagram]\n  B --> C[Modal opens]",
  "title": "Diagram pipeline",
  "format": "mermaid",
  "theme": "${MC_THEME:-dark}"
}
EOF

Sequence diagram

curl -sS -X POST "$MC_API_URL/api/diagram?taskId=$MC_TASK_ID" \
  -H "Authorization: Bearer $MC_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg source 'sequenceDiagram
  participant U as User
  participant MC as Mission Control
  participant A as Agent CLI
  U->>MC: Start session
  MC->>A: Spawn PTY + env
  A->>MC: POST /api/diagram
  MC-->>U: Open diagram modal' \
    --arg title 'Session diagram flow' \
    --arg theme "${MC_THEME:-dark}" \
    '{source:$source,title:$title,format:"mermaid",theme:$theme}')"

Flowchart (minimal)

curl -sS -X POST "$MC_API_URL/api/diagram?taskId=$MC_TASK_ID" \
  -H "Authorization: Bearer $MC_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg source 'flowchart LR
  A[Draft Mermaid] --> B[POST /api/diagram]
  B --> C[Modal opens]' \
    --arg title 'Diagram pipeline' \
    --arg theme "${MC_THEME:-dark}" \
    '{source:$source,title:$title,format:"mermaid",theme:$theme}')"

Mermaid tips

• Prefer flowchart TD/LR, sequenceDiagram, stateDiagram-v2, and erDiagram — they render reliably.
• Quote node labels with special characters: A["Step (retry)"]
• Avoid click directives and HTML labels — the viewer runs in strict mode.
• Avoid inline colors — Mission Control themes diagrams to match the app.