@diagrammo/dgmo 0.8.1 → 0.8.3

package/docs/language-reference.md

@@ -31,1491 +31,1252 @@ Syntax changes introduced in the consistency cleanup. Old forms now produce erro
 
 ---
 
-## Common Patterns
+## Table of Contents
+
+1. [Universal Constructs](#1-universal-constructs)
+2. [Sequence Diagrams](#2-sequence-diagrams)
+3. [Infrastructure Diagrams](#3-infrastructure-diagrams)
+4. [Flowchart Diagrams](#4-flowchart-diagrams)
+5. [State Diagrams](#5-state-diagrams)
+6. [Org Charts](#6-org-charts)
+7. [C4 Architecture Diagrams](#7-c4-architecture-diagrams)
+8. [Entity-Relationship Diagrams](#8-entity-relationship-diagrams)
+9. [Class Diagrams](#9-class-diagrams)
+10. [Kanban Boards](#10-kanban-boards)
+11. [Initiative-Status Diagrams](#11-initiative-status-diagrams)
+12. [Sitemap Diagrams](#12-sitemap-diagrams)
+13. [Gantt Charts](#13-gantt-charts)
+14. [Timeline Diagrams](#14-timeline-diagrams)
+15. [Data Charts](#15-data-charts)
+16. [Visualizations](#16-visualizations)
+17. [Colon Usage Summary](#17-colon-usage-summary)
 
-Every `.dgmo` file starts with a chart type keyword as the first line, optionally followed by a title. Directives follow on subsequent lines.
+---
 
-### First Line
+## 1. Universal Constructs
 
-```
-bar Revenue by Region
-```
+These patterns are shared across all or most diagram types.
 
-The chart type keyword (`bar`, `sequence`, `gantt`, etc.) is the first token. Everything after it on the same line becomes the title. If the content is unambiguous, the chart type is auto-detected and can be omitted.
-
-### Directives
+### 1.1 Chart Type Declaration (First Line)
 
 ```
-palette nord
-theme dark
-xlabel Category
-ylabel Count
+<chart-type> [Title]
 ```
 
-Directives are `keyword value` (no colon). They appear after the first line, before data.
+- Space-separated, NO colon
+- Title is optional
+- Examples: `bar Treasure Hauls`, `sequence Auth Flow`, `gantt Product Launch`
 
-### Comments
+### 1.2 Comments
 
 ```
-// This is a comment (only // is supported)
+// comment text
 ```
 
-### Inline Colors
+- Full-line only (no inline comments after code)
+- `#` is NOT a comment character
 
-Append `(colorname)` to labels, nodes, or data points:
+### 1.3 Tag Declarations
 
 ```
-Port Royal(red) 850
-[Process(blue)]
+tag GroupName [alias X]
+  Value1(color)
+  Value2(color) [default]
 ```
 
-Named colors only: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `teal`, `cyan`, `gray`. Palette-specific colors also available. Hex color codes (e.g. `#ff0000`) are **not** supported — use named colors instead.
+- `tag` keyword, NO colon
+- Alias: 1-4 lowercase letters
+- Inline values also supported: `tag Priority p Low(green), High(red)`
+- First entry is default unless another is marked `default`
+- Must appear before diagram content
 
-### Palettes and Themes
+**Diagram types that support tags**: sequence, infra, org, c4, er, kanban, gantt, initiative-status, sitemap, timeline
 
-8 palettes: `nord` (default), `solarized`, `catppuccin`, `rose-pine`, `gruvbox`, `tokyo-night`, `one-dark`, `bold`
+### 1.4 Pipe Metadata
 
-3 themes per palette: `light`, `dark`, `transparent`
+```
+EntityName | key: value, key2: value2
+```
 
-Set via CLI: `dgmo diagram.dgmo --palette catppuccin --theme dark`
+- Colons ARE required within pipe segments (`key: value`)
+- Items separated by commas
+- Tag aliases resolve: `| c: Caching` resolves to `concern: Caching` (if `tag Concern alias c` is defined)
+- One pipe per line only
 
-### Inline Markdown
+### 1.5 Color Suffixes
 
-Text fields support: `*italic*`, `**bold**`, `` `code` ``, `[link text](url)`. Bare URLs are auto-linked.
+```
+Label(colorName)
+```
 
-### Multi-line Values
+- Named palette colors only (no hex codes)
+- Appears at end of labels, node names, tag values, series names
+- Color is stripped from display text
 
-Properties that accept comma-separated lists (`series`, `columns`, `rows`, `x-axis`, `y-axis`) also accept an indented multi-line format. Leave the value empty and list each value on its own indented line:
+### 1.6 Indentation
 
-```
-// Single-line (still works)
-series Rum, Spices, Silk, Gold
+- Spaces or tabs (1 tab = 4 spaces)
+- Determines hierarchy and block scope
 
-// Multi-line equivalent
-series
-  Rum
-  Spices
-  Silk
-  Gold
-```
-
-Multi-line blocks support blank lines and `//` comments within the block. Trailing commas on values are stripped for convenience.
+### 1.7 Groups / Containers
 
 ```
-series
-  Rum (red)
-  Spices (green)
-  // gold last
-  Gold (yellow)
+[Group Name]
+[Group Name](color)
+[Group Name] | key: value
 ```
 
-Works with `columns` and `rows` in heatmaps:
+- Bracket-enclosed name
+- Optional color suffix
+- Optional pipe metadata (outside brackets)
+- Indented content below belongs to the group
+
+### 1.8 Boolean Options
 
 ```
-columns
-  January
-  February
-  March
+option-name          // on
+no-option-name       // off
 ```
 
+- Bare keyword = on; `no-` prefix = off
+- Must appear before diagram content
+
 ---
 
-## Chart Types
+## 2. Sequence Diagrams
 
-### bar
+### 2.1 Participants
 
-**Syntax:** `bar [Title]`
+```
+Name is a <type> [aka Alias] [position N]
+Name | key: value
+```
 
-**Options:** `series`, `xlabel`, `ylabel`, `orientation` (`horizontal`/`vertical`), `labels` (`name`/`value`/`percent`/`full`), `color`
+Types: `service`, `database`, `actor`, `queue`, `cache`, `gateway`, `external`, `networking`, `frontend`
 
-**Data format:** `Label value` — one row per category
+**Inference rules** — the parser infers the type (and shape) from the participant name. Only use `is a` when the name does not match or you want to override:
 
-**Example:**
+| Inferred Type | Shape | Name Patterns (examples) |
+|--------------|-------|--------------------------|
+| actor | Stick figure | `User`, `Customer`, `Client`, `Admin`, `Agent`, `Person`, `Buyer`, `Seller`, `Guest`, `Visitor`, `Operator`, Alice, Bob, Charlie, `*User`, `*Actor`, `*Analyst`, `*Staff` |
+| service | Rounded rectangle | `*Service`, `*Svc`, `*API`, Lambda, `*Function`, `*Fn`, `*Job`, Cron, Auth, SSO, OAuth, Stripe, Twilio, S3, Vercel, Docker, K8s, Vault, KMS, IAM, LLM, GPT, Claude, `*Pipeline`, `*Engine`, and many `-er`/`-or` suffixes (Scheduler, Handler, Processor, Worker, etc.) |
+| database | Cylinder (vertical) | `*DB`, `Database`, `*Store`, `Storage`, `*Repo`, `SQL`, Postgres, MySQL, Mongo, Dynamo, Aurora, Spanner, Supabase, Firebase, BigQuery, Redshift, Snowflake, Cassandra, Neo4j, ClickHouse, Elastic, OpenSearch, Pinecone, Weaviate, `*Table` |
+| cache | Dashed cylinder | `*Cache`, Redis, Memcache, KeyDB, Dragonfly, Hazelcast, Valkey |
+| queue | Horizontal cylinder (pipe) | `*Queue`, `*MQ`, SQS, Kafka, RabbitMQ, `EventBus`, `*Bus`, `Topic`, `*Stream`, SNS, PubSub, NATS, Pulsar, Kinesis, EventBridge, Celery, Sidekiq, `*Channel`, `*Broker` |
+| networking | Hexagon | `*Router`, `*Balancer`, `Gateway`, `Proxy`, `LB`, `CDN`, `Firewall`, `WAF`, `DNS`, `Ingress`, Nginx, Traefik, Envoy, Istio, Kong, Akamai, Cloudflare, `*Mesh` |
+| frontend | Monitor (screen + stand) | `*App`, `Application`, `Mobile`, iOS, Android, `Web`, `Browser`, `Frontend`, `*UI`, `Dashboard`, `*CLI`, `Terminal`, React, Vue, Angular, Svelte, NextJS, Electron, Tauri, `*Widget`, `Portal`, `*Console`, SPA, PWA |
+| gateway | Rectangle (same as default) | matched via `is a gateway` only |
+| external | Dashed rectangle | `External`, `*Ext`, `ThirdParty`, `*3P`, `Vendor`, `Webhook`, `Upstream`, `Downstream`, `Callback`, AWS, GCP, Azure |
+| default | Rectangle | Everything else (no `is a` needed) |
 
+**Inference handles it (skip `is a`):**
+```
+AuthService          // service (matches *Service)
+PostgresDB           // database (matches *DB)
+Redis                // cache (exact match)
+User                 // actor (exact match)
+Kafka                // queue (exact match)
+API Gateway          // networking (matches Gateway)
+WebApp               // frontend (matches *App)
+Stripe               // service (exact match)
 ```
-bar Revenue by Region
-series Revenue
 
-North 850
-South 620
-East 1100
-West 430
+**Inference would miss (use `is a`):**
+```
+Payments is a service       // "Payments" matches no rule
+Vault is a database         // "Vault" infers as service, but you want database
+Notifications is a queue    // "Notifications" matches no rule
+Analytics is a frontend     // "Analytics" matches no rule
 ```
 
-Colors per item: `North(red) 850`
+### 2.2 Participant Groups
 
-### line
+```
+[Group Name]
+  Participant1
+  Participant2
+```
 
-**Syntax:** `line [Title]` or `multi-line [Title]`
+- Pipe metadata goes outside brackets: `[Backend] | t: Eng`
+- Invalid: `[Backend | t: Eng]` (pipe inside brackets)
 
-**Options:** `series`, `xlabel`, `ylabel`, `labels`
+### 2.3 Messages (Arrows)
 
-**Data format:** `Label value` (single series) or `Label v1, v2, v3` (multi-series matching `series` list)
+| Type | Syntax | Example |
+|------|--------|---------|
+| Sync (labeled) | `A -label-> B` | `Client -login-> API` |
+| Sync (bare) | `A -> B` | `Client -> API` |
+| Async (labeled) | `A ~label~> B` | `API ~notify~> Queue` |
+| Async (bare) | `A ~> B` | `API ~> Queue` |
 
-**Example:**
+- Whitespace around arrows is optional: `A-label->B` works
+- Labels can contain spaces, hyphens, special chars
+- Labels cannot contain arrow chars (`->`, `~>`)
+- Pipe metadata: `A -msg-> B | c: Caching`
 
-```
-line Quarterly Performance
-series Sales(red), Costs(blue)
+### 2.4 Section Dividers
 
-Q1 100, 50
-Q2 120, 55
-Q3 110, 60
-Q4 130, 58
+```
+== Label ==
+== Label
 ```
 
-Multi-series: comma-separated values matching the `series` list. Single series omits `series` directive. Also works as `multi-line`.
+Trailing `==` is optional.
 
-**Era bands** — annotate named time periods with background shading:
+### 2.5 Notes
 
 ```
-line U.S. Strategic Petroleum Reserve
-ylabel Million Barrels
+note Text
+note right Text
+note left of ParticipantID Text
+```
 
-era '81 -> '89 Reagan (red)
-era '89 -> '93 Bush (red)
-era '93 -> '01 Clinton (blue)
+**Multi-line notes** use an indented body below the `note` heading:
 
-'81 230
-'85 493
-'89 580
-'93 587
-'01 550
+```
+note right of API
+  - First bullet point
+  - Second bullet point
+  **Bold text** and *italic text*
+  `inline code`
+  [link text](https://example.com)
+  https://example.com
 ```
 
-Syntax: `era <start> -> <end> <label> [(<color>)]`
-
-- `start` and `end` must exactly match category labels in the data
-- Color is optional; defaults to the palette's blue
-- Band label is hidden if the era spans fewer than 3 category slots
-- Works on `line`, `multi-line`, and `area` charts
-- Era boundary labels are always pinned visible on the x-axis even when auto-skip is active
+Content formatting:
+- `- ` prefix on indented lines = bullet points
+- Inline markdown: `**bold**`, `*italic*`, `` `code` ``
+- Links: `[text](url)` and bare URLs (auto-truncated in display)
 
-### area
+### 2.6 Structural Blocks
 
-**Syntax:** `area [Title]`
+```
+if condition
+  messages...
+else if condition
+  messages...
+else
+  messages...
 
-**Options:** same as `line`, including era bands
+loop condition
+  messages...
 
-**Data format:** same as `line`
+parallel label
+  messages...
+```
 
-Same syntax as `line`, including era bands. Renders as a filled area chart.
+- `parallel` requires a label
+- Blocks nest via indentation
 
-### pie
+### 2.7 Sequence Options
 
-**Syntax:** `pie [Title]`
+- `activations` / `no-activations`
+- `collapse-notes` / `no-collapse-notes`
+- `active-tag GroupName`
 
-**Options:** `labels` (`name`/`value`/`percent`/`full`)
+---
 
-**Data format:** `Label value`
+## 3. Infrastructure Diagrams
 
-**Example:**
+### 3.1 Declaration
 
 ```
-pie Market Share
-labels percent
-
-Company A 40
-Company B 35
-Company C 25
+infra [Title]
 ```
 
-### doughnut
-
-**Syntax:** `doughnut [Title]`
-
-**Options:** same as `pie`
-
-**Data format:** same as `pie`
+### 3.2 Nodes
 
-Same syntax as `pie`. Renders as a doughnut (ring) chart.
-
-### polar-area
+```
+NodeName
+NodeName | key: value
+```
 
-**Syntax:** `polar-area [Title]`
+Nodes are plain names. Capabilities come from properties (see 3.3), not type declarations.
 
-**Options:** same as `pie`
+### 3.3 Node Properties (Indented, Space-Separated, NO Colon)
 
-**Data format:** same as `pie`
+```
+NodeName
+  latency-ms 50
+  max-rps 8000
+  uptime 99.99%
+  cache-hit 75%
+  description My API gateway
+  firewall-block 10%
+  instances 3
+```
 
-Same syntax as `pie`. Renders as a polar area (rose) chart.
+Properties use a known schema with space-separated values:
 
-### radar
+| Property | Capability | Effect |
+|----------|-----------|--------|
+| `cache-hit` | Cache | % requests served from cache, reduces downstream RPS |
+| `firewall-block` | Firewall/WAF | % requests blocked, reduces downstream RPS |
+| `ratelimit-rps` | Rate limiter | Max RPS passed through |
+| `latency-ms` | Latency | Adds to path latency |
+| `uptime` | Availability | Multiplied along path for SLO |
+| `instances` | Horizontal scaling | Multiplies capacity |
+| `max-rps` | Capacity ceiling | Max RPS node handles |
+| `cb-error-threshold` | Circuit breaker | Error rate trip threshold |
+| `cb-latency-threshold-ms` | Circuit breaker | Latency trip threshold |
+| `concurrency` | Concurrency limit | Max concurrent requests |
+| `duration-ms` | Processing time | Time spent processing |
+| `cold-start-ms` | Serverless | Cold start penalty |
+| `buffer` | Queue | Buffer size |
+| `drain-rate` | Queue | Consumption rate |
+| `retention-hours` | Queue | Message retention |
+| `partitions` | Queue | Partition count |
+| `description` | Display | Description text |
 
-**Syntax:** `radar [Title]`
+### 3.4 Connections
 
-**Options:** (none)
+| Type | Syntax |
+|------|--------|
+| Sync (bare) | `-> Target` |
+| Sync (labeled) | `-/api-> Target` |
+| Async (bare) | `~> Target` |
+| Async (labeled) | `~event~> Target` |
 
-**Data format:** `Label value`
+- Connection metadata: `| split: 50%, fanout: 3` (colons in pipe metadata)
+- Indented under source node
 
-**Example:**
+### 3.5 Groups
 
 ```
-radar Team Skills
-
-Frontend 85
-Backend 70
-DevOps 60
-Design 90
-Testing 75
+[Group Name]
+[Group Name](color)
+[Group Name] | key: value
 ```
 
-### bar-stacked
-
-**Syntax:** `bar-stacked [Title]`
+Bracket syntax only. Optional color and pipe metadata.
 
-**Options:** `series` (required), `xlabel`, `ylabel`, `orientation`
+### 3.6 Infra Options (Space-Separated, NO Colon)
 
-**Data format:** `Label v1, v2, v3` — comma-separated values matching the `series` list
+- `direction-tb` (boolean; default is LR)
+- `default-latency-ms N`
+- `default-rps N`
+- `default-uptime DECIMAL`
+- `slo-availability DECIMAL`
+- `slo-p90-latency-ms N`
+- `animate` / `no-animate`
 
-**Example:**
+### 3.7 Edge Nodes
 
 ```
-bar-stacked Budget Allocation
-series Engineering, Marketing, Sales
-
-Q1 100, 50, 30
-Q2 110, 55, 35
-Q3 105, 60, 40
+edge
+internet
 ```
 
-### scatter
+Special top-level entry points. `internet` only accepts `rps` property.
 
-**Syntax:** `scatter [Title]`
-
-**Options:** `labels` (`on`/`off`), `xlabel`, `ylabel`, `sizelabel`
+---
 
-**Data format:** `Label x, y` or `Label x, y, size` (bubble chart). Group with `[GroupName]` blocks.
+## 4. Flowchart Diagrams
 
-**Example:**
+### 4.1 Declaration
 
 ```
-scatter Performance Metrics
-labels on
-xlabel Experience (years)
-ylabel Output
-
-Alice 3, 85
-Bob 7, 92
-Carol 2, 70
+flowchart [Title]
 ```
 
-Tag groups (`[GroupName](color)`) create colored clusters:
+### 4.2 Node Shapes
 
-```
-scatter Startup Funding vs Revenue
-labels on
-xlabel Funding ($M)
-ylabel Annual Revenue ($M)
+| Shape | Syntax | Example |
+|-------|--------|---------|
+| Terminal | `(Label)` | `(Start)` |
+| Process | `[Label]` | `[Do Task]` |
+| Decision | `<Label>` | `<Check?>` |
+| I/O | `/Label/` | `/Read Input/` |
+| Subroutine | `[[Label]]` | `[[Validate]]` |
+| Document | `[Label~]` | `[Report~]` |
 
-[SaaS](blue)
-  Acme Cloud 12, 8.5
-  DataSync 5.2, 3.1
+- Color suffix: `(Start(green))`
 
-[Fintech](green)
-  PayFlow 45, 32
-  LendTech 18, 12.5
-```
+### 4.3 Arrows
 
-### heatmap
+| Type | Syntax |
+|------|--------|
+| Unlabeled | `->` |
+| Labeled | `-label->` |
+| Colored | `-(color)->` |
+| Labeled + colored | `-label(color)->` |
 
-**Syntax:** `heatmap [Title]`
+- Color inference: `yes/success/ok/true` infers green; `no/fail/error/false` infers red
 
-**Options:** `columns` (required)
-
-**Data format:** `Row Label v1, v2, v3` — comma-separated values matching the `columns` list
-
-**Example:**
+### 4.4 Groups
 
 ```
-heatmap Activity by Month
-columns Jan, Feb, Mar, Apr, May, Jun
-
-Team A 5, 4, 5, 3, 4, 5
-Team B 2, 3, 2, 4, 3, 2
-Team C 3, 2, 1, 2, 3, 4
+[GroupName]
+  [Child nodes...]
 ```
 
-### sankey
-
-**Syntax:** `sankey [Title]`
-
-**Options:** (none)
+Bracket syntax only.
 
-**Data format:** Arrow syntax (`Source -> Target value`) or indentation syntax (`Target value` indented under parent)
-
-**Arrow syntax:**
+### 4.5 Inline Chains
 
 ```
-sankey Resource Flow
-
-Source A -> Processing 300
-Source B -> Processing 200
-Processing -> Output X 350
-Processing -> Output Y 150
+(Start) -> [Step 1] -> [Step 2] -> (End)
 ```
 
-**Indentation syntax:**
+### 4.6 Options
 
-```
-sankey Resource Flow
+- `direction-tb` (boolean; default is LR)
+- `orientation-vertical` (boolean; default is horizontal)
 
-Source A
-  Processing 300
-Source B
-  Processing 200
-Processing
-  Output X 350
-  Output Y 150
-```
+---
 
-Both syntaxes can be mixed in the same diagram.
+## 5. State Diagrams
 
-**Node colors** — `(color)` after a node name:
+### 5.1 Declaration
 
 ```
-Revenue (green)
-  Costs (red) 600
-  Profit (blue) 400
-
-// or with arrows
-Revenue (green) -> Costs (red) 600
+state [Title]
 ```
 
-**Link colors** — `(color)` after the value:
+### 5.2 States
 
 ```
-Revenue
-  Costs 600 (orange)
-
-// or with arrows
-Revenue -> Costs 600 (orange)
+StateName
+StateName(color)
+[*]                    // initial/final pseudostate
 ```
 
-### chord
-
-**Syntax:** `chord [Title]`
-
-**Options:** (none)
+### 5.3 Transitions
 
-**Data format:** same as `sankey` (arrow syntax)
+| Type | Syntax |
+|------|--------|
+| Unlabeled | `Idle -> Active` |
+| Labeled | `Idle -submit-> Processing` |
+| Colored | `Idle -(blue)-> Active` |
 
-Same syntax as `sankey`. Renders as a circular chord diagram.
-
-**Example:**
+### 5.4 Groups
 
 ```
-chord Inter-Department Collaboration
-
-Engineering -> Design 85
-Engineering -> Product 72
-Design -> Marketing 45
-Product -> Sales 42
+[Group Name]
+[Group Name](color)
 ```
 
-### funnel
+### 5.5 Options
 
-**Syntax:** `funnel [Title]`
+- `direction-tb` (boolean; default is LR)
 
-**Options:** (none)
+---
 
-**Data format:** `Label value`
+## 6. Org Charts
 
-**Example:**
+### 6.1 Declaration
 
 ```
-funnel Conversion Pipeline
-
-Visitors 1000
-Signups 500
-Trials 200
-Customers 100
+org [Title]
 ```
 
-### function
-
-**Syntax:** `function [Title]`
-
-**Options:** `x` (required, `start to end`), `xlabel`, `ylabel`
-
-**Data format:** `Name (color) expression` — math expressions using `x`
-
-**Example:**
+### 6.2 Nodes (Indentation = Hierarchy)
 
 ```
-function Mathematical Functions
-xlabel x
-ylabel f(x)
-
-x -6 to 6
-f(x) (blue) sin(x)
-g(x) (red) x^2 / 10
-h(x) (green) cos(x) * 2
+CEO
+  CTO
+    Engineer1
+    Engineer2
+  CFO
 ```
 
-Expressions support: `+`, `-`, `*`, `/`, `^`, `sin`, `cos`, `sqrt`, `abs`, `log`, `exp`, `pi`, `e`.
-
-### slope
-
-**Syntax:** `slope [Title]`
-
-**Options:** `orientation` (`horizontal`/`vertical`)
-
-**Data format:** First data line defines period labels. Subsequent lines: `Item (color) v1, v2, ...`
+- Color suffix: `Alice(blue)`
+- Pipe metadata: `Alice | role: CEO, t: Exec`
 
-**Example:**
+### 6.3 Metadata (Indented, Colon REQUIRED)
 
 ```
-slope Programming Language Popularity
-
-2020, 2022, 2025
-Python (blue) 3, 1, 1
-JavaScript (yellow) 1, 2, 2
-TypeScript (cyan) 7, 4, 3
-Rust (orange) 18, 12, 5
+Alice
+  role: Senior Engineer
+  location: NYC
 ```
 
-### wordcloud
-
-**Syntax:** `wordcloud [Title]`
-
-**Options:** `rotate` (`none`/`mixed`/`angled`), `max` (word limit), `size` (`min, max` font range)
+This is key-value metadata assignment, consistent with pipe metadata syntax.
 
-**Data format:** `word weight` (higher = larger)
-
-**Example:**
+### 6.4 Containers
 
 ```
-wordcloud Top Terms
-
-kubernetes 95
-docker 80
-terraform 65
-ansible 50
+[Team Name]
+  members...
 ```
 
-### arc
+### 6.5 Options
 
-**Syntax:** `arc [Title]`
+- `direction-tb` (boolean; default is LR)
+- `sub-node-label Text`
+- `show-sub-node-count`
+- `hide`
 
-**Options:** `order:` (`appearance`/`name`/`group`/`degree`), `orientation`
+---
 
-**Data format:** `Source -> Target weight`. Group nodes with `[GroupName]` blocks.
+## 7. C4 Architecture Diagrams
 
-**Example:**
+### 7.1 Declaration
 
 ```
-arc Team Collaboration
-order: group
-
-[Frontend]
-  WebApp -> API Gateway 5
-  MobileApp -> API Gateway 3
-
-[Core Services]
-  API Gateway -> AuthService 4
-  API Gateway -> UserService 5
+c4 [Title]
 ```
 
-### venn
-
-**Syntax:** `venn [Title]`
-
-**Options:** `values` (`on`/`off`)
-
-**Data format:** Sets: `id(color) alias shortname`. Overlaps: `id1 + id2 Label`.
-
-**Example:**
+### 7.2 Elements
 
 ```
-venn Skill Overlap
-
-Frontend(blue) alias fe
-Backend(green) alias be
-DevOps(orange) alias de
-
-fe + be Web Systems
-be + de Platform Ops
-fe + de Dev Tools
-fe + be + de Full Stack
+Name is a <type>
+Name is a container is a database     // shape override
 ```
 
-### quadrant
+Types: `person`, `system`, `container`, `component`
+Shape overrides: `database`, `cache`, `queue`, `cloud`, `external`
 
-**Syntax:** `quadrant [Title]`
-
-**Options:** `x-axis` (`low label, high label`), `y-axis` (`low label, high label`)
-
-**Data format:** Quadrant labels: `top-right Label`, `top-left Label`, etc. Data points: `Label (color) x, y` where x,y are 0-1.
-
-**Example:**
+### 7.3 Element Metadata (Indented, Colon REQUIRED)
 
 ```
-quadrant Priority Matrix
-x-axis Low Impact, High Impact
-y-axis Low Effort, High Effort
-
-top-right Quick Wins(green)
-top-left Big Bets(yellow)
-bottom-left Skip(red)
-bottom-right Reconsider(gray)
-
-Task A 0.9, 0.8
-Task B 0.2, 0.3
-Task C 0.7, 0.4
+Web App is a container
+  description: SPA built with React
+  tech: React
 ```
 
-### timeline
-
-**Syntax:** `timeline [Title]`
-
-**Options:** `scale` (`on`/`off`), `sort` (`time`/`group`/`tag`/`tag:GroupName`), `swimlanes` (`on`/`off`)
+Indented metadata uses colon-separated `key: value`, consistent with org charts and pipe metadata.
 
-**Data format:** Ranges: `start->end Label | tag: Value`. Points: `date Label | tag: Value`.
-
-**Example:**
+### 7.4 Pipe Metadata (Colons in pipes)
 
 ```
-timeline Project History
-
-tag Team
-  Team A(blue)
-  Team B(green)
-
-era 2023->2024 Phase 1
-marker 2023-06 Launch(orange)
-
-2023-01->2023-06 Planning | Team: Team A
-2023-06->2024-01 Development | Team: Team A
-2024-02 Release | Team: Team A
-
-2023-03->2023-09 Research | Team: Team B
-2023-09->2024-03? Implementation | Team: Team B
+Web App is a container | description: SPA, tech: React
 ```
 
-Date formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`. Ranges: `start->end`. Durations: `start->1y`, `start->6m`, `start->2w`, `start->30d`. Uncertain end: append `?` (e.g., `2024-03?`).
+### 7.5 Relationships
 
-Elements: `era start->end Label(color)`, `marker date Label(color)`, `tag` groups for interactive coloring.
+| Type | Syntax |
+|------|--------|
+| Sync labeled | `-Makes API calls-> API` |
+| Sync with tech | `-Uses [HTTPS]-> API` |
+| Async labeled | `~Sends emails~> Email` |
 
-Tag groups for interactive coloring and swimlanes:
+### 7.6 Sections
 
 ```
-timeline Sprint Plan
-sort tag:Team
-
-tag Team
-  Engineering(blue)
-  Design(green)
-
-2024-01->2024-06 Build API | Team: Engineering
-2024-03->2024-05 UX Review | Team: Design
+containers
+  ...
+components
+  ...
+deployment
+  container Web App    // reference existing container
 ```
 
-Tag groups add interactive color and swimlane controls. `sort tag` uses the first tag group for swimlanes; `sort tag:GroupName` specifies which group (aliases work: `sort tag:p` resolves to `sort tag:Pirate`).
-
----
-
-## Diagram Types
+### 7.7 Options
 
-### sequence
+- `direction-tb` (boolean; default is LR)
 
-**Syntax:** `sequence [Title]`
-
-**Options:** `activations` (`on`/`off`), `collapse-notes` (`yes`/`no`), `active-tag GroupName`
+---
 
-**Data format:** Messages between participants with arrow syntax
+## 8. Entity-Relationship Diagrams
 
-Minimal example:
+### 8.1 Declaration
 
 ```
-User -login-> API
-API -findUser-> DB
-DB -user-> API
-API -token-> User
+er [Title]
 ```
 
-Full example:
+### 8.2 Tables
 
 ```
-sequence Authentication Flow
-
-// participant declarations (optional)
-User is an actor
-API is a service
-DB is a database
-NotifyQueue is a queue aka Notifications
-
-User -Login request-> API
-API -Find user by email-> DB
-DB -user record-> API
-note on DB
-  Indexed lookup on email column
-
-if credentials valid
-  API -Create session-> DB
-  DB -session token-> API
-  API ~session.created~> NotifyQueue
-  API -200 OK + token-> User
-else
-  API -401 Unauthorized-> User
-
-== Logout ==
-
-User -Logout-> API
-API -Delete session-> DB
-API -200 OK-> User
+users
+users(blue)
+users | domain: Core
 ```
 
-**Participants**: Auto-inferred from message names. Declare explicitly for type/positioning:
-- `Name is a [actor|service|database|queue|cache|gateway|external|networking|frontend]`
-- `Name aka Display Label` — alias for display
-- `Name at position 2` — manual left-to-right ordering (0-based; negative from right)
-
-**Messages**:
-- Sync call: `A -label-> B` or `A -> B` (unlabeled) — always left-to-right
-- Async call: `A ~label~> B` or `A ~> B` (unlabeled)
-
-**Blocks** (indentation-scoped):
-- `if condition` ... `else` ... (no explicit `end` needed — indentation closes blocks)
-- `loop label` ...
-- `parallel label` ...
-
-**Notes**:
-- `note text` — standalone
-- `note on Participant` followed by indented text — anchored
-- Multi-line: indent continuation lines under `note`
-
-**Sections**: `== Section Title ==`
-
-**Groups**: `[Group Name]` or `[Group Name | key: value]` — visual grouping box around participants
+- Pipe metadata on declaration line only
+- Indented lines are columns or relationships
 
-**Tag groups** — define color-coded metadata dimensions for interactive recoloring:
+### 8.3 Columns (Indented, Space-Separated, NO Colon)
 
 ```
-tag Concern alias c
-  Caching(blue)
-  Auth(green)
-  BusinessLogic(purple) default
+users
+  id int pk
+  name varchar
+  email string unique
+  created_at timestamp nullable
 ```
 
-- `tag Name` declares a tag group; `alias x` adds a shorthand
-- Each entry: `Value(color)` — named color for that value
-- `default` on an entry applies it to untagged elements when the group is active
+Format: `name [type] [constraints...]`
+Constraints: `pk`, `fk`, `unique`, `nullable`
 
-**Pipe metadata** — attach tag values to participants, messages, and groups:
+### 8.4 Relationships (Indented Under Source Table)
 
 ```
-API is a service | concern: Caching, team: Platform
-User -login-> API | concern: Auth
-[Backend | concern: BusinessLogic]
-  OrderAPI
-  DB
+ships
+  1-aboard-* crew_members
+  ?-frequents-1 ports
 ```
 
-- `| key: value` after participant declarations, message lines, or group headers
-- Multiple tags: `| key1: val1, key2: val2`
-- Aliases work: `| c: Caching` (if `alias c` was declared)
-
-**Tag resolution priority** (when a tag group is active):
-1. Explicit metadata on the participant
-2. Group propagation (participant inherits from its group)
-3. Receiver inheritance (all incoming tagged messages agree on same value)
-4. `default` entry value
-5. Neutral (no color)
-
-**Legend** — rendered automatically above participants when tag groups exist. The active group expands to show colored entry dots. Click a group pill to activate it (in the desktop app).
+Cardinality symbols: `1` (one), `*` (many), `?` (optional)
 
-### flowchart
+### 8.5 Options
 
-**Syntax:** `flowchart [Title]`
+- `notation chen` / `notation crow`
 
-**Options:** (none beyond `palette`, `theme`)
+---
 
-**Data format:** Node chains with arrow connections
+## 9. Class Diagrams
 
-Minimal example:
+### 9.1 Declaration
 
 ```
-(Start) -> [Process] -> (End)
+class [Title]
 ```
 
-Full example:
+### 9.2 Classes
 
 ```
-flowchart Decision Process
-
-(Start) -> <Valid Input?>
-  -yes-> [Process Data] -> [[Run Subroutine]]
-  -no-> /Get User Input/ -> <Valid Input?>
-[[Run Subroutine]] -> [Document~] -> (Done)
+Ship
+abstract Vessel
+interface Serializable
+Ship extends Vessel
+Galleon implements Serializable
+ShipType enum
 ```
 
-**Node shapes**:
-- `(Terminal)` — oval
-- `[Process]` — rectangle
-- `<Decision?>` — diamond
-- `/Input Output/` — parallelogram
-- `[[Subroutine]]` — double-bordered rectangle
-- `[Document~]` — document (wavy bottom)
-
-**Arrows**: `-label-> Target`, `-(color)-> Target`, `-label(color)-> Target`
-
-**Inferred arrow colors** — when a label matches a well-known keyword, the arrow color is set automatically:
-
-| Label | Inferred Color |
-|---|---|
-| yes, success, ok, true | green |
-| no, fail, error, false | red |
-| maybe, warning | orange |
-
-Colors on nodes: `[Process(blue)]`
-
-### state
-
-**Syntax:** `state [Title]`
-
-**Options:** `direction` (`TB` or `LR`), `color` (`off` for monochrome)
-
-**Data format:** States connected by transitions
-
-Minimal example:
+### 9.3 Members (Indented, Colon for Types)
 
+**Fields:**
 ```
-[*] -> Idle -> Active -> [*]
++ name: string
+- speed: number
+# protectedField: int
 ```
 
-Full example:
-
+**Methods:**
 ```
-state Order Lifecycle
-direction LR
-
-[Processing(blue)]
-  Validating -valid-> Approved
-  Validating -invalid-> Rejected(red)
-
-[*] -> Pending -submit-> Validating
-Approved -ship-> Shipped -> [*]
-Rejected -> [*]
-Shipped -return-> Pending
++ sail(): void
+- calculate(x: number): boolean
++ getName() {static}: string
 ```
 
-**States**: bare text — `Idle`, `Active`, `Processing`. Optional color suffix: `Active(green)`.
+Visibility: `+` public, `-` private, `#` protected
 
-**Pseudostates**: `[*]` — rendered as a filled circle. Use for start and end points.
+**Enum values:**
+```
+ShipType enum
+  Galleon
+  Sloop
+```
 
-**Transitions**: `->`, `-label->`, `-(color)->`, `-label(color)->`.
+### 9.4 Relationships (Indented Under Source Class)
 
-**Chains**: `A -> B -> C` on a single line creates two transitions.
+| Relationship | Arrow |
+|-------------|-------|
+| Inheritance | `--|>` |
+| Implementation | `..\|>` |
+| Composition | `*--` |
+| Aggregation | `o--` |
+| Dependency | `..>` |
+| Association | `->` |
 
-**Indentation**: indented lines use the parent as implicit source:
+Relationships are indented under the source class:
 
 ```
-Idle
-  -start-> Running
-  -configure-> Configuring
+Ship
+  --|> Vessel
+  *-- Cannon
 ```
 
-is equivalent to `Idle -start-> Running` and `Idle -configure-> Configuring`.
+Optional label: `--|> Vessel : extends` (colon optional before label)
 
-**Groups**: `[GroupName]` or `[GroupName(color)]` — groups subsequent indented states visually.
+`extends` and `implements` on class declarations still work as part of the declaration syntax.
 
-**Self-loops**: `Running -retry-> Running` — a state transitioning to itself.
+### 9.5 Options
 
-### class
+- `no-auto-color` (boolean; auto-coloring is on by default)
 
-**Syntax:** `class [Title]`
-
-**Options:** (none beyond `palette`, `theme`)
+---
 
-**Data format:** Class declarations with indented members
+## 10. Kanban Boards
 
-Minimal example:
+### 10.1 Declaration
 
 ```
-Animal
-  + name: string
-  + speak(): void
-
-Dog extends Animal
-  + breed: string
-
-Cat extends Animal
-  + indoor: boolean
+kanban [Title]
 ```
 
-Full example:
+### 10.2 Columns
 
 ```
-class Type Hierarchy
-
-Printable [interface]
-  + print(): void
-
-Shape implements Printable [abstract]
-  # x: number
-  # y: number
-  + area(): number
-  count: number {static}
-
-Circle extends Shape
-  - radius: number
-  + area(): number
-
-Rectangle extends Shape
-  - width: number
-  - height: number
-
-Shape *-- Circle : contains
+[Column Name]
+[Column Name](color) | wip: 3
 ```
 
-**Class modifiers**: `[abstract]`, `[interface]`, `[enum]`
+### 10.3 Cards (Indented Under Columns)
 
-**Inheritance**: `ClassName extends Parent` or `ClassName implements Interface` — declared inline in the class header. Members are indented below.
-
-**Member visibility**: `+` public, `#` protected, `-` private. Static: `{static}`.
-
-**Relationships** (arrow syntax):
-- Inheritance: `A --|> B`
-- Implementation: `A ..|> B`
-- Composition: `A *-- B`
-- Aggregation: `A o-- B`
-- Dependency: `A ..> B`
-- Association: `A -> B`
-- Optional label: `A *-- B : description`
+```
+[To Do]
+  Card title | priority: High, c: Owner
+    Detail text (indented deeper)
+```
 
-### er
+### 10.4 Options
 
-**Syntax:** `er [Title]`
+- `no-auto-color` (boolean; auto-coloring is on by default)
+- `hide`
 
-**Options:** (none beyond `palette`, `theme`)
+---
 
-**Data format:** Entity declarations with indented columns and relationships
+## 11. Initiative-Status Diagrams
 
-Minimal example:
+### 11.1 Declaration
 
 ```
-users
-  id: int [pk]
-  name: varchar
-  1-* posts
-
-posts
-  id: int [pk]
-  user_id: int [fk]
+initiative-status [Title]
 ```
 
-Full example:
+### 11.2 Nodes
 
 ```
-er Blog Schema
-
-users
-  id: int [pk]
-  email: varchar [unique]
-  name: varchar
-  1-writes-* posts
-  ?-moderates-* categories
-
-posts
-  id: int [pk]
-  title: varchar
-  body: text
-  author_id: int [fk]
-  category_id: int [fk, nullable]
-
-categories
-  id: int [pk]
-  name: varchar [unique]
-  1-* posts
+NodeLabel | status, key: value
+NodeLabel | done, t: Team1
 ```
 
-**Columns**: `name: type [constraints]`. Constraints: `pk`, `fk`, `unique`, `nullable`. Multiple: `[fk, nullable]`.
-
-**Relationships** — indented under the source table (preferred):
-- `1-* target` — one-to-many
-- `1-1 target` — one-to-one
-- `?-1 target` — zero-or-one to one
-- `?-* target` — zero-or-more
-- Labeled: `1-writes-* target` (label between dashes)
-
-Columns and relationships can be mixed under the same table. The parser distinguishes them by the leading cardinality character (`1`, `*`, `?`).
-
-**Flat relationships** — at indent 0 (also supported):
-- `table1 1--* table2` — one-to-many
-- `table1 1--* table2 : label` — with label
+Status values and equivalences:
 
-### c4
+| User writes | Canonical | Display |
+|------------|-----------|---------|
+| `done` | `done` | Done |
+| `doing` | `doing` | In Progress |
+| `wip` | `doing` | In Progress |
+| `blocked` | `blocked` | Blocked |
+| `paused` | `blocked` | Blocked |
+| `waiting` | `blocked` | Blocked |
+| `todo` | `todo` | To Do |
+| `na` | `na` | N/A |
+| (omitted) | `na` | N/A |
 
-**Syntax:** `c4 [Title]`
-
-**Options:** (none beyond `palette`, `theme`)
-
-**Data format:** Element declarations with `Name is a type`, relationships with arrows
-
-Minimal example:
+### 11.3 Edges
 
 ```
-c4
-
-User is a person
-MyApp is a system | description: The main application
-  -Uses-> User
+Source -> Target
+Source -label-> Target
+Source -> Target | status
 ```
 
-Auto-detection: C4 diagrams are auto-detected when `Name is a person/system/container/component` declarations are present — `c4` is optional.
-
-Full example:
-
+Indented shorthand (source from preceding node):
+```
+Captain | t: Bridge
+  -issueOrders-> CrewApp | na
 ```
-c4 Banking System
 
-tag Scope alias sc
-  Internal(blue) default
-  External(gray)
+### 11.4 Groups
 
-Customer is a person | description: A customer of the bank
+```
+[Group Name]
+  indented nodes...
+```
 
-Internet Banking is a system | description: Online banking portal
-  -Delivers content-> Customer | tech: HTTPS
-  -Sends emails-> Email | tech: SMTP
+### 11.5 Options
 
-  containers
-    Web App is a container | description: SPA, tech: React
-      -API calls-> API | tech: JSON/HTTPS
+- `active-tag GroupName`
+- `hide phase:Planning, phase:Review` (colon syntax for tag:value)
 
-    API is a container | description: Backend, tech: Node.js
-      -Reads/writes-> Database | tech: SQL
+---
 
-    Database is a container | description: Data store, tech: PostgreSQL
+## 12. Sitemap Diagrams
 
-Email is a system | description: Email delivery, sc: External
-  ~Sends emails~> Customer
+### 12.1 Declaration
 
-deployment
-  Vercel is a cloud
-    container Web App
-  Railway
-    container API
-  Neon is a database
-    container Database
+```
+sitemap [Title]
 ```
 
-**Element types** — declared with `Name is a <type>`:
-- `Name is a person` — human actor
-- `Name is a system` — software system
-- `Name is a container` — application/service within a system
-- `Name is a component` — component within a container
-- `Name is a external` — external system
-- `Name is a database` — database element
+### 12.2 Pages (Indentation = Hierarchy)
 
-**Metadata** (pipe-delimited): `Name is a system | description: text, tech: stack, tagalias: value`
+```
+Home
+  About
+  Pricing | Auth: Public
+    Enterprise
+  Blog
+```
 
-**Sections**: `containers` (inside system), `components` (inside container), `deployment`
+### 12.3 Arrows
 
-**Deployment nodes**: `NodeName is a [cloud|database|cache|queue|external]`
+```
+Home
+  -pricing-> Pricing
+  -login-> Login
+```
 
-**Relationships**:
-- Sync: `-> Target` or `-label-> Target`
-- Async: `~> Target` or `~label~> Target`
-- With technology metadata: `-label-> Target | tech: HTTPS`
+### 12.4 Containers
 
-**Tag groups**: See tag group syntax below.
+```
+[Marketing]
+  Pricing | Auth: Public
+```
 
-### org
+### 12.5 Options
 
-**Syntax:** `org [Title]`
+- `direction-tb` (boolean; default is LR)
 
-**Options:** `sub-node-label`, `show-sub-node-count` (flag, no value needed)
+---
 
-**Data format:** Hierarchy via indentation
+## 13. Gantt Charts
 
-Minimal example:
+### 13.1 Declaration
 
 ```
-org
-
-CEO
-  VP Engineering
-    Team Lead
-  VP Marketing
+gantt [Title]
 ```
 
-Full example:
+### 13.2 Options (Space-Separated, NO Colon)
 
 ```
-org Engineering Org
-sub-node-label Reports
-show-sub-node-count
-
-tag Level alias lv
-  Director(red)
-  Manager(blue)
-  IC(green) default
-
-CTO | lv: Director
-  VP Engineering | lv: Director
-    [Platform]
-      Lead | lv: Manager
-        Dev 1
-        Dev 2
-    [Product]
-      Lead | lv: Manager
-        Dev 3
+start 2026-03-15
+today-marker
+today-marker 2026-03-27
+critical-path
+no-dependencies
+sort tag:Team
 ```
 
-Hierarchy via indentation. `[Group Name]` creates collapsible sub-groups.
+### 13.3 Holidays
 
-**Metadata**: `Name | tagalias: value, tag2: value2`
-
-**Imports**: `import path/to/file.dgmo` (indented under a parent node), `tags path/to/tags.dgmo` (top-level).
+```
+holiday
+  2024-02-19 Presidents Day
+  2024-05-27 -> 2024-05-29 Memorial Weekend
+```
 
-### kanban
+### 13.4 Workweek
 
-**Syntax:** `kanban [Title]`
+```
+workweek mon-fri
+workweek sun-thu
+```
 
-**Options:** (none beyond `palette`, `theme`)
+Top-level directive (not nested under `holiday`).
 
-**Data format:** `[Column]` headers with card items below
+### 13.5 Eras
 
-Minimal example:
+**Flat form:**
+```
+era 2026-04-06 -> 2026-04-10 Conference (purple)
+```
 
+**Block form:**
+```
+era
+  2026-04-06 -> 2026-04-10 Conference (purple)
+  2026-06-01 -> 2026-06-05 Sprint Review (blue)
 ```
-kanban
 
-[To Do]
-Task 1
-Task 2
+### 13.6 Markers
 
-[Done]
-Task 3
+**Flat form:**
+```
+marker 2026-03-27 Board Review
 ```
 
-Full example:
-
+**Block form:**
+```
+marker
+  2026-03-27 Board Review
+  2026-06-15 Release (green)
 ```
-kanban Sprint Board
 
-tag Priority
-  Critical(red)
-  High(orange)
-  Low(green) default
+### 13.7 Groups (Swimlanes)
 
-tag Owner alias o
-  Alice(blue)
-  Bob(green)
+```
+[Backend] | t: Engineering
+```
 
-[Backlog(gray)]
-Research API options | priority: High, o: Alice
+Bracket syntax only.
 
-[In Progress(orange)] | wip: 3
-Build auth module | priority: Critical, o: Bob
-  Integrate OAuth2
-  Add session management
+### 13.8 Tasks
 
-[Done(green)]
-Setup CI pipeline | priority: High, o: Alice
+```
+20bd Database Schema | p: Foundation, 100%
+10bd API Integration | t: Engineering
+0d Launch Day
+2026-03-15 -> 30d Setup
 ```
 
-**Columns**: `[Column Name]`, `[Column Name(color)]`, `[Column Name] | wip: N`
+Duration units: `min`, `h`, `d`, `bd` (business days), `w`, `m`, `q`, `y`
+Uncertain: `10bd?` (trailing `?`)
+Progress: `| 80%` in pipe metadata
 
-**Cards**: `Card Title | tag: value`. Indented lines below become card details.
+### 13.9 Dependencies (Indented Under Tasks)
 
-**Group metadata cascading**: `[Column Name] | key: value` — pipe metadata on column headers cascades to all cards in the column.
+```
+10bd API Integration
+  -> E2E Testing
+  -> Launch Day | offset: 10bd
+```
 
-### initiative-status
+### 13.10 Parallel Block
 
-**Syntax:** `initiative-status [Title]`
+```
+parallel
+  [Backend]
+    20bd Schema
+  [Frontend]
+    10bd Wireframes
+```
 
-**Options:** (none beyond `palette`, `theme`)
+---
 
-**Data format:** Nodes with status, connected by dependency arrows
+## 14. Timeline Diagrams
 
-Minimal example:
+### 14.1 Declaration
 
 ```
-initiative-status
-
-Auth | done
-  -> UserService | doing
-  -> NotifyService | todo
-UserService | doing
-NotifyService | todo
+timeline [Title]
 ```
 
-Full example:
+### 14.2 Events
 
+**Point event:**
 ```
-initiative-status Platform Roadmap
-
-Auth | done
-  -depends-> UserService | doing
-  -feeds-> Dashboard | todo
-Dashboard | todo
-UserService | doing
-  -calls-> DBLayer | done
-DBLayer | done
-
-[External]
-  PaymentGW | na
-  EmailProvider | na
+1718-05 Blockades Charleston | p: Blackbeard
 ```
 
-**Status values**: `done`, `doing`, `blocked`, `todo`, `na`
-
-**Status aliases**: `wip` maps to `doing`; `paused` and `waiting` map to `blocked`. Aliases are accepted in input but the canonical values are preferred.
-
-**Relationships**: `-label-> Target | status` or indented children.
-
-**Groups**: `[Group Name]` for visual grouping. `[Group Name] | key: value` — pipe metadata cascades to contained nodes.
-
-### sitemap
+**Range event:**
+```
+1716 -> 1717 Sails under Hornigold | p: Blackbeard
+```
 
-**Syntax:** `sitemap [Title]`
+**Duration event:**
+```
+2026-03-20 -> 30d Sprint 1
+```
 
-**Options:** `direction` (`TB` or `LR`), `orientation` (alias for `direction`)
+**Uncertain ending:**
+```
+1718 -> 1719? Rackham builds crew
+```
 
-**Data format:** Page labels with arrows and metadata
+Date formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DD HH:MM`
+Duration units: `min`, `h`, `d`, `w`, `m`, `y`
 
-Minimal example:
+### 14.3 Eras
 
+**Flat form:**
 ```
-sitemap
-
-Home
-  -about-> About
-  -blog-> Blog
-
-[Content]
-  About
-  Blog
-    -read-> Post
-  Post
+era 1716 -> 1718 Nassau Republic
 ```
 
-Full example:
-
+**Block form:**
+```
+era
+  1716 -> 1718 Nassau Republic
+  1718 -> 1720 Woodes Rogers Era (orange)
 ```
-sitemap SaaS Platform
-direction TB
-
-tag Auth
-  Public(green)
-  Required(blue)
-  Admin(red)
 
-tag Type
-  Landing(purple)
-  Form(orange)
-  Content(cyan)
+### 14.4 Markers
 
-Home
-  Auth: Public
-  Type: Landing
-  -pricing-> Pricing
-  -login-> Login
-  -docs-> Docs
+**Flat form:**
+```
+marker 1718-07 Woodes Rogers arrives (orange)
+```
 
-[Marketing]
-  Pricing
-    Auth: Public
-    Type: Content
-    -sign up-> Register
+**Block form:**
+```
+marker
+  1718-07 Woodes Rogers arrives (orange)
+  1720-01 End of Golden Age (red)
+```
 
-  Docs
-    Auth: Public
-    Type: Content
+### 14.5 Groups
 
-[Auth]
-  Login
-    Auth: Public
-    Type: Form
-    -success-> Dashboard
-    -forgot-> Reset Password
+```
+[Royal Navy]
+  1718-07 Woodes Rogers arrives
+```
 
-  Register
-    Auth: Public
-    Type: Form
-    -success-> Dashboard
+---
 
-  Reset Password
-    Auth: Public
-    Type: Form
-    -submitted-> Login
+## 15. Data Charts
 
-[App]
-  Dashboard
-    Auth: Required
-    Type: Landing
-    -projects-> Projects
-    -settings-> Settings
+### 15.1 Simple Charts (bar, line, pie, doughnut, area, polar-area, radar, bar-stacked)
 
-  Projects
-    Auth: Required
-    Type: Content
+**Declaration:** `bar [Title]`, `line [Title]`, etc.
 
-  Settings
-    Auth: Required
-    Type: Form
-    -saved-> Dashboard
+**Series:**
+```
+series Name1 Name2
+series
+  Name1
+  Name2(color)
 ```
 
-**Pages**: Plain labels at any indent level become page nodes.
-
-**Groups**: `[Group Name]` wraps indented children in a container.
-
-**Arrows**: `-label-> Target`, `-(color)-> Target`, `-label(color)-> Target` — cross-link between any pages. Arrow colors are inferred from well-known labels (see flowchart section).
+Commas between series names are optional.
 
-**Metadata**: `Key: Value` lines attach to the parent page (displayed as card rows).
+**Data rows (space-separated, NO colon):**
+```
+Label 100
+Label 100 200 300
+Label(color) 100
+```
 
-**Tag groups**: `tag Name` with colored entries — same syntax as org charts.
+Commas between values are optional. Thousands commas are supported (`3,984,078.65` is a valid number).
 
-**Direction**: `direction TB` (top-to-bottom, default) or `direction LR` (left-to-right). `orientation` is accepted as an alias for `direction`.
+**Options (space-separated, NO colon):**
+```
+title My Chart
+xlabel X Label
+ylabel Y Label
+orientation-horizontal
+stacked
+```
 
-**Group metadata cascading**: `[Group Name] | key: value` — pipe metadata on group headers cascades to all pages in the group.
+- `orientation-horizontal` (boolean; default is vertical bars)
+- `stacked` (boolean; default is off)
+- Legend is always shown (no option needed)
 
-**Collapsible groups**: Groups can be collapsed/expanded in the app — arrows to hidden pages re-terminate at the group boundary.
+**Labels** default to showing all parts (name + value + percent for pie-family). Disable parts individually:
+- `no-label-name` — hide name
+- `no-label-value` — hide value
+- `no-label-percent` — hide percent
 
-### infra
+**Eras (line/area only):**
+```
+era Day 1 -> Day 3 Rough Seas (red)
+```
 
-**Syntax:** `infra [Title]`
+### 15.2 Scatter / Bubble Charts
 
-**Options:** `direction` (`LR` or `TB`), `orientation` (alias for `direction`)
+**Data rows (space-separated, NO colon):**
+```
+Name x y
+Name x y size
+```
 
-**Data format:** Component declarations with indented properties and connections
+Commas between values are optional. Thousands commas supported.
 
-Minimal example:
+**Categories:**
+```
+[Caribbean](red)
+  Blackbeard 90 8500
+```
 
+**Options:**
+```
+xlabel Weight
+ylabel Height
+sizelabel Crew
+no-labels
 ```
-infra
 
-edge
-  rps: 1000
-  -> CDN
+Labels are on by default. Use `no-labels` to hide point names.
 
-CDN
-  cache-hit: 80%
-  -> API
+### 15.3 Heatmap
 
-API
-  instances: 2
-  max-rps: 400
-  latency-ms: 30
+**Columns:**
+```
+columns Jan Feb Mar
 ```
 
-Full example:
+Commas between column names are optional.
 
+**Data rows (space-separated, NO colon):**
+```
+RowLabel 5 4 3
 ```
-infra Production Traffic Flow
-direction LR
 
-tag Team alias t
-  Backend(blue)
-  Platform(teal)
+Commas between values are optional. Thousands commas supported.
 
-edge
-  rps: 10000
-  -> CloudFront
+### 15.4 Function Charts (Colon REQUIRED)
 
-CloudFront | t: Platform
-  cache-hit: 80%
-  -> CloudArmor
+```
+function Trajectories
+xlabel Distance
+ylabel Height
+x 0 to 250
 
-CloudArmor | t: Platform
-  firewall-block: 5%
-  -> ALB
+15 degrees(blue): -0.001*x^2 + 0.27*x
+45 degrees(red): -0.003*x^2 + 0.75*x
+```
 
-ALB | t: Platform
-  -/api-> [API Pods] | split: 60%
-  -/purchase-> [Commerce Pods] | split: 30%
-  -/static-> StaticServer | split: 10%
+The colon between name and expression is **required** — both sides can contain spaces, so colon is the unambiguous delimiter.
 
-[API Pods]
-  APIServer | t: Backend
-    instances: 3
-    max-rps: 500
-    latency-ms: 45
-    cb-error-threshold: 50%
+**Options:**
+- `shade` (boolean; off by default, shades area below curves when enabled)
 
-[Commerce Pods]
-  PurchaseMS
-    instances: 1-8
-    max-rps: 300
-    latency-ms: 120
+### 15.5 Sankey Charts
 
-StaticServer | t: Platform
-  latency-ms: 5
+**Tree structure (indented, space-separated):**
+```
+Sugar Plantations(green)
+  Tortuga Distillery(orange) 3000
+  Nassau Distillery 2500
 ```
 
-**Entry point**: The `edge` block declares the external traffic source with `rps:` (requests per second). All downstream rps are computed automatically.
+**Explicit links:**
+```
+Source -> Target 3500
+Source -- Target 2000
+```
 
-**Components**: Bare labels at indent 0 define infrastructure components. Properties are indented below:
-- `cache-hit: N%` — percentage of traffic served from cache (reduces downstream flow)
-- `firewall-block: N%` — percentage of traffic blocked (reduces downstream flow)
-- `ratelimit-rps: N` — maximum rps allowed through (excess dropped)
-- `max-rps: N` — maximum rps capacity per instance
-- `instances: N` or `instances: N-M` — fixed or auto-scaling instance count
-- `latency-ms: N` — per-request latency in milliseconds
-- `cb-error-threshold: N%` — circuit breaker opens when overload exceeds this ratio
-- `cb-latency-threshold-ms: N` — circuit breaker opens when cumulative latency exceeds this
+`->` = directed, `--` = undirected. Thousands commas supported in values.
 
-**Type declarations**: `NodeName is a <type>` — declare a component's infrastructure role:
-- `database`, `cache`, `queue`, `service`, `gateway`, `storage`, `function`, `network`
-- Example: `Redis is a cache`, `SQS is a queue`
+### 15.6 Chord Charts
 
-**Connections**:
-- Sync: `-> Target` (unlabeled), `-label-> Target` (labeled)
-- Async: `~> Target` (unlabeled), `~label~> Target` (labeled)
-- Pipe metadata for splits: `-> Target | split: N%`
-- Fan-out multiplier: `-> Target | fanout: 5` or `-> Target | split: 50%, fanout: 5`
+```
+Blackbeard -- Bonnet 150        // undirected
+Roberts -> Rackham 20           // directed
+```
 
-**Fan-out**: Use `| fanout: N` metadata to model request multiplication — one inbound request triggers N outbound calls to the target. The target receives `inbound x N` RPS. Fan-out is applied after split: `-> Shards | split: 60%, fanout: 8` means the target receives `inbound x 0.60 x 8` RPS. Fan-out compounds naturally through multi-hop chains.
+Thousands commas supported in values.
 
-**Branching**: Multiple outbound connections with `split: N%` metadata. Splits must sum to 100%. Undeclared splits are evenly distributed from the remaining percentage.
+### 15.7 Funnel Charts
 
-**Groups**: `[Group Name]` with indented children — rendered as dashed-border containers. Edges targeting a group route to all children.
+**Data rows (space-separated, NO colon):**
+```
+Visits 1200
+Signups 800
+Purchases 200
+```
 
-**Roles**: Inferred automatically from behavior properties or `is a` type declarations. Components with `cache-hit` get a Cache role, `firewall-block` gets Firewall, etc. Explicit declarations (`Redis is a cache`) set the role directly. Roles appear as colored dots on nodes and in the legend.
+Thousands commas supported.
 
-**Overload**: When computed rps exceeds `max-rps x instances`, the node turns red. Dynamic scaling (`instances: 1-8`) auto-scales within the range before overloading.
+---
 
-**Group metadata cascading**: `[Group Name] | key: value` — pipe metadata on group headers cascades to all children, providing default tag values for contained nodes.
+## 16. Visualizations
 
-**Tag groups**: Same syntax as org/kanban/sitemap — `tag Name alias x` with colored entries.
+### 16.1 Slope Charts (Colon REQUIRED for data)
 
-### gantt
+```
+slope Fleet Strength
 
-**Syntax:** `gantt [Title]`
+1715 1725
 
-**Options:** `start` (required, `YYYY-MM-DD`), `today-marker` (`on`/`off` or `YYYY-MM-DD`), `sort` (`time`/`group`/`tag`/`tag:GroupName`), `critical-path`, `dependencies`
+Blackbeard: 40 4
+Roberts: 12 52
+```
 
-**Data format:** `duration Task Name` — tasks with optional dependency arrows
+- Period labels on their own line, commas optional
+- Data rows: `Label: value1 value2` — colon required, commas between values optional
+- Thousands commas supported in values
 
-Minimal example:
+### 16.2 Wordcloud
 
 ```
-start 2024-01-01
+wordcloud Pirate Skills
+rotate none
+max 50
+size 14 80
 
-10bd Design
-  -> Implementation
-20bd Implementation
-  -> Testing
-5bd Testing
+swordsmanship 95
+navigation 88
 ```
 
-Auto-detection: Gantt charts are auto-detected when duration patterns like `10bd Design` are present — `gantt` is optional.
+- Data: space-separated only (`word value`)
+- Options: `rotate none|mixed|angled`, `max N`, `size min max`
 
-Full example:
+### 16.3 Arc Diagrams (Colon Before Weight)
 
 ```
-gantt Project Schedule
-start 2024-01-01
-today-marker on
+arc Pirate Alliances
 
-tag Team alias t
-  Frontend(blue)
-  Backend(green)
+[Caribbean](red)
+  Blackbeard -> Bonnet: 8
+  Blackbeard -> Vane: 5
 
-holidays
-  2024-01-15: MLK Day
-  2024-02-19: Presidents Day
-
-era 2024-01 -> 2024-03 Phase 1(blue)
-marker 2024-02-15 Sprint Review(orange)
-
-[Design]
-  5bd UX Research | t: Frontend
-  10bd Wireframes | t: Frontend
-    -informs-> API Design
-
-[Engineering]
-  15bd API Design | t: Backend
-    -> Frontend Build | offset: 2bd
-  20bd Frontend Build | t: Frontend
-  10bd Integration Testing
+order group
 ```
 
-**Start date**: `start YYYY-MM-DD` (required) — project start date for computing all task dates.
-
-**Tasks**: `<duration> <name>` — duration units: `bd` (business days), `d` (days), `w` (weeks), `m` (months), `q` (quarters), `y` (years), `h` (hours), `min` (minutes).
+- Link: `Source -> Target: weight` — colon before optional weight
+- Options: `order appearance|name|group|degree`
 
-**Explicit dates**: `YYYY-MM-DD Task Name` or `YYYY-MM-DD -> 30d Task Name` (date with duration).
+### 16.4 Venn Diagrams
 
-**Uncertain end**: Append `?` to duration (e.g., `10bd? Task`) — renders with a fading tail.
-
-**Dependencies**: `-label-> Target` or `-> Target` — indented under the source task. The target task starts after the source completes.
-
-**Dependency offsets**: `-> Target | offset: 2bd` — positive offset adds a gap; `-> Target | offset: -3d` — negative offset creates overlap (lead time).
-
-**Labeled dependency arrows**: `-label-> Target` — the label text appears on the rendered arrow.
-
-**Groups**: `[Group Name]` wraps indented tasks in a collapsible section.
-
-**Group metadata cascading**: `[Group Name] | key: value` — pipe metadata cascades to all tasks in the group.
-
-**Eras**: `era YYYY-MM -> YYYY-MM Label(color)` — background shading bands.
-
-**Markers**: `marker YYYY-MM-DD Label(color)` — vertical milestone lines.
-
-**Holidays**: `holidays` block with `YYYY-MM-DD: Name` entries or `YYYY-MM-DD -> YYYY-MM-DD: Name` ranges. Holiday dates skip business-day counting.
-
-**Tag groups**: Same syntax as other diagrams — `tag Name alias x` with colored entries.
+```
+venn Skill Overlap
 
----
+Swordsmanship(red) alias sw
+Navigation(blue) alias nav
+Leadership(green) alias lead
 
-## Tag Groups
+sw + nav Sea Raiders
+sw + nav + lead Legendary Pirates
+```
 
-Define reusable metadata categories for sequence, org, kanban, C4, sitemap, infra, gantt, initiative-status, and timeline diagrams:
+- Set declaration: `Name(color) alias X`
+- Intersections: `Set1 + Set2 Label` — label follows the last set reference (no colon)
 
-```
-tag Priority
-  Critical(red)
-  High(orange)
-  Medium(yellow)
-  Low(green) default
+### 16.5 Quadrant Diagrams (Colon REQUIRED)
 
-tag Team alias t
-  Frontend(blue)
-  Backend(green)
 ```
+quadrant Crew Assessment
+x-axis: Low Skill, High Skill
+y-axis: Low Loyalty, High Loyalty
 
-- `tag` keyword (case-insensitive)
-- Optional `alias` for shorthand in metadata: `| t: Frontend`
-- `default` keyword marks the fallback value
-- Indented entries with `Value(color)`
-
-Assign to elements via pipe metadata: `Element Name | priority: High, t: Frontend`
+top-right: Promote (green)
+top-left: Train (yellow)
+bottom-left: Maroon (red)
+bottom-right: Watch Closely (purple)
 
----
+Quartermaster: 0.9 0.95
+Navigator: 0.85 0.8
+```
 
-## Anti-Patterns
-
-**Common mistakes to avoid:**
-
-- `# comment` — wrong. Use `// comment`
-- `chart: bar` + `title: Revenue` — wrong. Use `bar Revenue` (single first line)
-- `Label: value` in ECharts data — wrong. Use `Label value` (no colon)
-- `async A -> B: msg` — wrong. Use `A ~msg~> B`
-- `parallel else` — not supported. Use separate `parallel` blocks
-- Hex colors `#ff0000` — wrong. Use named colors only: `red`, `green`, `blue`, etc.
-- `->` inside labeled arrows `A -routes to /api-> B` — ambiguous. Rephrase the label
-- Missing chart type for ambiguous content — when auto-detection picks the wrong type, add an explicit chart type keyword
-- `end` keyword in sequence blocks — not needed. Indentation closes blocks
-- `== Column ==` in kanban — removed. Use `[Column]`
-- `person Name` in C4 — removed. Use `Name is a person`
-- `A <-> B` bidirectional arrows — removed. Use two separate lines
-- `-> Target x5` fan-out — removed. Use `-> Target | fanout: 5`
-- `lag: 5d` / `lead: 3d` in gantt — removed. Use `offset: 5d` / `offset: -3d`
-- `Name(color)` in sequence participants — removed. Use `tag` groups for coloring
+- Axis labels: `x-axis: Low, High` — colon required
+- Position labels: `top-right: Label` — colon required
+- Data points: `Label: x y` — colon required, commas between values optional
+- Thousands commas supported in values
 
 ---
 
-## CLI Usage
-
-```bash
-dgmo diagram.dgmo                              # PNG output (default)
-dgmo diagram.dgmo -o output.svg                # SVG output
-dgmo diagram.dgmo -o url                        # Shareable URL
-dgmo diagram.dgmo --palette catppuccin --theme dark
-dgmo diagram.dgmo -o output.png --palette bold
-```
+## 17. Colon Usage Summary
+
+### Constructs Where Colons Are REQUIRED
+
+| Construct | Diagram Type | Example |
+|-----------|-------------|---------|
+| Pipe metadata | all | `\| key: value, key2: value2` |
+| Org metadata (indented) | org | `role: Manager` |
+| C4 metadata (indented) | c4 | `description: SPA built with React` |
+| Class field types | class | `+ name: string` |
+| Class method returns | class | `+ sail(): void` |
+| Function expressions | function | `f(x): x^2 + 1` |
+| Slope data rows | slope | `Blackbeard: 40 4` |
+| Quadrant axes | quadrant | `x-axis: Low, High` |
+| Quadrant positions | quadrant | `top-right: Promote` |
+| Quadrant data points | quadrant | `Quartermaster: 0.9 0.8` |
+| Arc link weight | arc | `Source -> Target: 8` |
+| Hide tag values | initiative-status | `hide phase:Planning` |
+
+### Colons OPTIONAL
+
+| Construct | Diagram Type | Example |
+|-----------|-------------|---------|
+| Class relationship label | class | `--|> Vessel : extends` or `--|> Vessel extends` |
+
+### Colons NOT USED
+
+| Construct | Diagram Type | Example |
+|-----------|-------------|---------|
+| Chart type declaration | all | `bar Title` |
+| Tag declarations | all | `tag Name alias x` |
+| Boolean options | all | `activations`, `no-activations` |
+| Key-value options | all | `start 2026-03-15`, `active-tag Team` |
+| Series declarations | data charts | `series A B C` |
+| Data rows | bar/line/pie/etc | `Label 100` |
+| Infra node properties | infra | `latency-ms 50` |
+| ER columns | er | `id int pk` |
+| Sequence messages | sequence | `A -msg-> B` |
+| Groups/containers | all | `[Group Name]` |
+| Section dividers | sequence | `== Phase ==` |
+| Comments | all | `// comment` |
+| Wordcloud data | wordcloud | `swordsmanship 95` |
+| Venn intersections | venn | `sw + nav Sea Raiders` |
+
+### The Rule
+
+**Colons appear in two contexts:**
+1. **Value assignment** — `key: value` in pipe metadata, indented tag/metadata assignment (org, c4), and hide directives
+2. **Type/expression separation** — where labels can contain spaces and a delimiter is needed (function expressions, slope data, quadrant data, arc weights, class members)
+
+**Exception**: Known-schema properties (infra node properties, ER columns) remain space-separated even though they are indented. The colon rule applies to open-ended metadata, not fixed property schemas.
+
+**Colons never appear in:**
+- Directives and options (space-separated)
+- Tag declarations
+- Chart type declarations
+- Data rows for simple charts (space or comma delimited)
+- Structural syntax (groups, sections, arrows, comments)