# DGMO Diagram Language

When the user asks for a diagram, visualization, or chart, generate a `.dgmo` file. DGMO is a text-based diagram markup language that renders to SVG/PNG.

<!-- GENERATED by dgmo/scripts/gen-ai-core.mjs from docs/language-reference.md — DO NOT EDIT between the DGMO-AI-CORE markers; run `node scripts/gen-ai-core.mjs` (or sync-language-ref.sh) to regenerate. -->
<!-- DGMO-AI-CORE:START -->
## DGMO AI Core

_Generated from `language-reference.md` — the anti-patterns and 45-type index below are identical across every DGMO AI surface._

### Disambiguation — where DGMO diverges from LLM priors

LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the most common parse errors:

- **No colons in declarations, directives, tags, or data rows.** `bar Revenue` (not `bar: Revenue`); `series Cloud blue, Legacy red` (not `series: ...`); `North 850` (not `North: 850`); `tag Team as t` (not `tag: Team`). A colon binds a value only in metadata (`key: value`), class/function type separators, and a few scoped spots — see §26.
- **No Mermaid arrow-labels.** Put the label *between* the dashes: `A -Login-> B`, never `A -> B: Login`. Sequence: `->` sync, `~>` async; left-to-right only — no `<-` / `<~`.
- **No `|` metadata delimiter** (removed 0.18.0 → `E_PIPE_OPERATOR_REMOVED`). Use same-line `Name key: value, k2: v2` or indented `key: value`. (`|` survives only in wireframe `{A | B}` dropdowns, in-arrow label text, and quoted names.)
- **No removed participant keywords.** Do not write `X is a service` / `external` / `frontend` / `networking` / `gateway` — these were removed and error. A bare name renders the default shape; for a typed glyph use `is a person` / `is a database` / `is a queue`.
- **No hex colors.** Named palette colors only: `red, orange, yellow, green, blue, purple, teal, cyan, gray, black, white`. Trailing token (`Done green`) or parenthesized suffix (`North(red) 850`).
- **Show-everything is the default.** Every label / value / percent renders by default. Emit `no-name` / `no-value` / `no-percent` / `no-*` ONLY when the user explicitly asks to hide something — never defensively.
- **`//` comments only** (never `#`). **Indentation closes blocks** — never `end`.
- **Declare before reference.** An edge target must be declared on a prior line; put metadata and edges on/under one declaration to avoid `Duplicate node` warnings.

Two traps in the *other* direction (DGMO wants a colon / a space where you might not expect):

- **Infra node properties REQUIRE the colon** — `cache-hit: 80%`, `instances: 3`, `max-rps: 8000`, `latency-ms: 45`. But top-level infra **options** are space-separated (`default-rps 100`). Don't conflate them.
- **ER columns are space-separated** — `id int pk`, `email varchar` (the one SQL-DDL carve-out; everything else indented-typed uses a colon).

Idiomatic example — color via tags, metadata on the declaration line, indented edges:

```dgmo
boxes-and-lines Service Map
tag Team as t
  Platform blue
  Product green
active-tag Team

API Gateway t: Platform
  -routes-> Orders
  -routes-> Billing
Orders t: Product
Billing t: Product
```

### Chart-type index (45) — pick the type, then fetch its section

| id | when to use |
| -- | ----------- |
| `sequence` | message / interaction flows over time |
| `flowchart` | decision trees and process flows |
| `state` | state-machine / lifecycle transitions |
| `class` | UML class hierarchies |
| `er` | database schemas and relationships |
| `c4` | system architecture (context / container / component / deployment) |
| `infra` | infrastructure traffic flow with RPS computation |
| `boxes-and-lines` | general-purpose node-edge diagrams with groups and tags |
| `sitemap` | site / app navigation structure |
| `mindmap` | radial hierarchy of ideas from a central topic |
| `org` | reporting hierarchy |
| `kanban` | task-board columns |
| `gantt` | project scheduling with task dependencies and milestones |
| `pert` | project network with three-point estimates and critical path |
| `timeline` | events, eras, and date ranges |
| `journey-map` | UX flow with emotion scores, phases, annotations |
| `cycle` | cyclical process (PDCA, OODA, DevOps loops) |
| `raci` | tasks × roles responsibility matrix (`R A C I`) |
| `rasci` | RACI variant adding Support (`R A S C I`) |
| `daci` | decision matrix (Driver, Approver, Contributor, Informed) |
| `tech-radar` | technology adoption quadrants (adopt / trial / assess / hold) |
| `quadrant` | 2×2 positioning matrix |
| `pyramid` | stacked hierarchy of layers (Maslow, DIKW) |
| `ring` | concentric rings of nested categories |
| `map` | geographic concept map: regions, points, routes |
| `wireframe` | low-fidelity UI layout with panels and controls |
| `bar` | categorical comparisons |
| `bar-stacked` | multi-series categorical |
| `line` | trends over time |
| `multi-line` | multiple-series trends over time |
| `area` | filled line chart |
| `pie` | part-to-whole proportions |
| `doughnut` | ring-style pie chart |
| `radar` | multi-dimensional metrics |
| `polar-area` | radial bar chart |
| `scatter` | 2D points or bubble chart |
| `heatmap` | matrix intensity |
| `funnel` | conversion pipeline |
| `sankey` | flow / allocation |
| `chord` | circular flow relationships |
| `arc` | network relationships on a line |
| `slope` | change between two periods |
| `venn` | set overlaps |
| `wordcloud` | term-frequency |
| `function` | mathematical expressions (colon required: `f(x): x^2`) |

**Need more than the index gives you?** Fetch the per-type section: MCP `get_language_reference(type)` / `get_examples(type)`, or read that type's section below. The `suggest_chart_type` tool returns the chosen type's section automatically.

### Common examples (curated, parse-clean)

_The most common types, inline so you can generate them without a fetch. For the other 37, get the per-type section (see below)._

#### journey-map

```dgmo
journey-map A Cabin Boy's First Voyage
solid-fill

persona Squidlips Sam color: blue
  Greenhorn cabin boy, first time at sea
  Sworn to the crew but quietly terrified

[Signing On]
  Sign the articles score: 4, emotion: Hopeful
    description: Captain reads the code aloud — pay shares, no women aboard, lights out at 8

[The Tempest]
  Caught in a squall off the reef score: 1, emotion: Terrified
    pain: Two crewmates lost overboard before dawn
    thought: Maybe the merchant fleet wasn't so bad after all
  Dawn, and she still floats score: 3, emotion: Relieved

[The Prize]
  Strike the colors score: 5, emotion: Triumphant
    description: Heavy with silver from the Veracruz mines

[Homecoming]
  Bury a share on the island score: 5, emotion: Proud
    thought: Three doubloons hidden where only he can find them
  Back to the Rusty Anchor score: 4, emotion: Content
    opportunity: Next time he signs on as a full hand, not a boy
```
#### c4

```dgmo
c4 Pirate Treasure Map System
solid-fill

tag Scope as sc
  Crew blue
  External gray

Captain is a person description Commands the fleet and plans raids

TreasureMap is a system description Tracks buried treasure locations and raid intelligence
  -Views treasure locations-> Captain
  -Sends raid alerts [carrier pigeon]-> Lookout

  containers
    ChartRoom is a container description Interactive sea chart with treasure markers, tech Parchment
      -Queries treasure data [secret code]-> Vault

    Vault is a container description Encrypted treasure ledger and coordinates, tech Iron Chest
      -Reads/writes [quill and ink]-> TreasureLog

    TreasureLog is a container description Stores locations, guard counts, and loot inventories, tech Leather-Bound Tome

Lookout is an external description Crow's nest spotter on allied ships, sc: External
  ~Relays sightings to~> Captain

deployment
  Flagship
    container ChartRoom
    container Vault
  SecretCave
    container TreasureLog
```
#### er

```dgmo
er Pirate Fleet

ships
  id int pk
  name varchar
  ship_type varchar
  cannons int
  1-aboard-* crew_members
  1-1 captains
  1-carries-* treasure

captains
  id int pk
  name varchar
  ship_id int fk
  bounty int
  ?-frequents-1 ports
  *-has-1 crew_members 

crew_members
  id int pk
  name varchar
  ship_id int fk
  role varchar nullable

treasure
  id int pk
  name varchar
  value int
  ship_id int fk, nullable

ports
  id int pk
  name varchar
  region varchar unique
  1-docks-* ships
```
#### class

```dgmo
class Ship Class Hierarchy

interface Vessel
  + sail(): void
  + anchor(): void

abstract Ship implements Vessel
  # name: string
  # crew: number
  + getName(): string

Galleon extends Ship
  - cannons: number
  + fire(): void

Sloop extends Ship
  - speed: number
  + flee(): void

enum ShipType
  Galleon
  Sloop
  Frigate

Ship
  -> ShipType has type
```
#### sequence

```dgmo
sequence Treasure Hunt App

tag Concern as c
  Search blue
  Claims green
  Notifications orange

User is an actor

[Treasure Service]
  TreasureAPI
  MapDB is a database
  NotifyQueue is a queue

User -Search nearby loot-> WebApp
WebApp -GET /treasures?nearby-> TreasureAPI c: Search
TreasureAPI -Find within 5nm-> MapDB c: Search
note
  - check location
  - use compass
MapDB -3 results-> TreasureAPI
TreasureAPI -locations-> WebApp
WebApp -Show treasure map-> User

== Claim ==

User -Claim chest #42-> WebApp
WebApp -POST /claim-> TreasureAPI c: Claims
if chest available
  TreasureAPI -Set status = claimed-> MapDB c: Claims
  MapDB -OK-> TreasureAPI
  TreasureAPI ~treasure.claimed~> NotifyQueue c: Notifications
  TreasureAPI -Claim accepted-> WebApp
  WebApp -500 doubloons earned!-> User
else
  TreasureAPI -409 Already claimed-> WebApp
  WebApp -Too slow, matey!-> User
```
#### state

```dgmo
state Ship Battle Lifecycle
solid-fill

[*] -> Sailing

Sailing
  -enemy spotted-> BattleStations

BattleStations
  -in range-> Engaging
  -enemy retreats-> Sailing

[Combat]
  Engaging
    -alongside-> Boarding
    -hull breach-> Sinking
    -outgunned-> Retreating

  Boarding
    -crew wins-> Victorious
    -crew loses-> Captured

[Aftermath]
  Victorious
    -loot taken-> Sailing

  Retreating
    -escaped-> Sailing
    -caught-> Captured

Captured -> [*]
Sinking -> [*]
```
#### infra

```dgmo
infra Pirate Communication Network

tag Fleet as f
  Blackbeard red
  Bonny purple
  Rackham blue

Edge
  rps: 200
  -> SignalFlags

SignalFlags f: Blackbeard
  description: Flag semaphore relay — ship-to-ship messaging
  latency-ms: 30000
  -> Flagship
  -> ScoutShip

Flagship f: Blackbeard
  description: Command vessel — decrypts and routes all intelligence
  instances: 1
  max-rps: 50
  latency-ms: 5000
  -> CarrierPigeons
  -> RumRunner

ScoutShip f: Bonny
  description: Fast sloop for reconnaissance
  instances: 2
  max-rps: 30
  latency-ms: 8000
  -> Flagship

CarrierPigeons f: Rackham
  description: Long-range bird relay — messages to allied ports
  buffer: 100
  drain-rate: 12
  retention-hours: 72
  -> TavernNetwork

[Allied Ports]
  instances: 3

  TavernNetwork f: Rackham
    description: Dockside tavern informants across the Caribbean
    max-rps: 20
    latency-ms: 86400000

RumRunner f: Bonny
  description: Smuggler supply line — moves coded messages in rum barrels
  concurrency: 4
  duration-ms: 172800000
  -> TavernNetwork
```
#### gantt

```dgmo
gantt Blackbeard's Blockade — 1718

start 1718-05-01
today-marker 1718-05-15

tag Role as r
  Command red
  Crew blue
  Captives orange

marker 1718-05-14 Ransom Deadline red
era 1718-05-08 -> 1718-05-17 Blockade Active blue

[Preparation] r: Command
  Provision Ship 3d r: Crew, progress: 100
    -> Anchor Fleet 2d r: Crew, progress: 100
  Scout Harbor 3d r: Crew, progress: 100
    -> Position Cannons 3d r: Crew, progress: 100
  Recruit Hands 5d r: Crew, progress: 100

+7d [Blockade] r: Crew
  Seize Merchants 4d progress: 100
    -> Hold Hostages 5d r: Captives, progress: 60
  Patrol Perimeter 9d progress: 75
  Demand Medicine 4d r: Command, progress: 100
    -> Threaten Executions 3d? r: Command, progress: 90

+17d [Resolution] r: Command
  Receive Ransom 2d r: Captives
    -> Release Prisoners 1d r: Captives
      -> Set Sail 0d
  Burn Evidence 2d r: Crew
```

**Fetch more:** the full per-type reference is at https://diagrammo.app/docs — fetch a type's section when the index + anti-patterns above aren't enough.
<!-- DGMO-AI-CORE:END -->

## When to suggest DGMO

- Architecture diagrams, sequence diagrams, flowcharts
- Data charts (bar, line, pie, scatter, heatmap, etc.)
- ER diagrams, class diagrams, org charts
- Project roadmaps, kanban boards, timelines

## Quick syntax reference

### Sequence diagram
```dgmo
sequence Auth Flow

User -Login-> API
API -Find user-> DB
DB -user-> API
  if valid
    API -200 OK-> User
  else
    API -401-> User
```

### Flowchart
```dgmo
flowchart Process

(Start) -> <Valid?>
  -yes-> [Process] -> (Done)
  -no-> /Get Input/ -> <Valid?>
```

### Bar chart
```dgmo
bar Revenue
series USD

North 850
South 620
East 1100
```

### ER diagram
```dgmo
er Schema

users
  id int pk
  email varchar

posts
  id int pk
  user_id int fk

users 1-writes-* posts
```

### Org chart
```dgmo
org

CEO
  VP Engineering
    Team Lead A
    Team Lead B
  VP Marketing
```

### C4 architecture
```dgmo
c4 System

User is a person
  -Browses-> Web App
Web App is a container description: SPA, tech: React
  -Uses-> API
API is a container description: REST backend, tech: Node
```

### Infra chart
```dgmo
infra

edge
  rps: 10000
  -> CDN

CDN
  cache-hit: 80%
  -> LB

LB
  -/api-> API split: 70%
  -/web-> Web split: 30%

API
  instances: 3
  max-rps: 500
  latency-ms: 45
```

Properties (colon required): `cache-hit`, `firewall-block`, `ratelimit-rps`, `max-rps`, `instances` (N or N-M), `latency-ms`, `cb-error-threshold`. Groups: `[Name]` with children. Roles are inferred from behavior.

### Boxes and lines
```dgmo
boxes-and-lines Architecture
tag Team as t
  Backend blue
  Frontend green
active-tag Team
direction LR

API Gateway t: Backend
  -routes-> AuthService
  -queries-> DB

[Cloud]
  API Gateway
  AuthService
```

Nodes: implicit from edges or explicit with same-line metadata (`Name key: value`). Edges: `A -label-> B`, `A <-label-> B` (bidi). Groups: `[Name]` with indented children (max 2 levels). Tags: `tag Name as alias` with indented values, `active-tag`, `hide`. Options: `direction LR|TB`.

## Supported chart types

If the dgmo MCP server is configured, call `list_chart_types` for the authoritative list (with descriptions) and `suggest_chart_type({ prompt })` to pick the best match for a request. Otherwise run `dgmo --chart-types` in a terminal. The static list previously here drifted with every new chart type — the MCP tool / CLI is the source of truth.

## Common patterns

- `TYPE Title` — first line declares chart type and optional title (no colon)
- `directive value` — directives are space-separated (no colon)
- `// comment` — only `//` comments (not `#`)
- `(colorname)` — inline colors: `Label(red) 100`
- `series A(red), B(blue)` — multi-series with colors
- `tag Group as g` with indented values — universal tag declaration

## Rendering

```bash
dgmo file.dgmo -o output.svg       # SVG
dgmo file.dgmo -o url              # shareable link
dgmo file.dgmo --json              # structured JSON output
```

Install: `brew install diagrammo/dgmo/dgmo` or `npm install -g @diagrammo/dgmo`

## Mistakes to avoid

- Don't use `#` for comments — use `//`
- Don't use `end` to close sequence blocks — indentation closes them
- Don't use hex colors — use named colors from the palette (red, orange, yellow, green, blue, purple, teal, cyan, gray, black, white)
- Don't use colons in chart type, title, directives, or data rows — use spaces
- Don't use `|` to delimit metadata — it was removed in 0.18.0; use same-line `key: value` per the universal metadata grammar
- Don't use `tag Name alias` or bare `tag Name x` — use `tag Name as alias`
- Sequence arrows: `->` (sync), `~>` (async) — always left-to-right; no leftward `<-` or `<~`

Full reference: `docs/language-reference.md`
