@diagrammo/dgmo 0.8.3 → 0.8.4

package/.claude/commands/dgmo-diagram-this.md

@@ -0,0 +1,60 @@
+# /dgmo-diagram-this — Generate Diagrams from Code
+
+You are reading the user's code and generating DGMO diagrams that document what it does. Don't ask what kind of diagram — figure it out from the code.
+
+## Prerequisites
+
+Verify DGMO MCP tools are available by calling `mcp__dgmo__list_chart_types`. If not available, tell the user to run `/dgmo` first to set up the MCP server.
+
+## Step 1 — Determine Scope
+
+The user may provide:
+- **A file path** — diagram that specific file
+- **A function/class name** — diagram that specific piece
+- **A directory** — diagram the module/package
+- **Nothing** — look at the current working directory and diagram the overall project structure
+
+If scope is unclear, read the project root (`package.json`, `README.md`, `src/` listing) and pick the most interesting thing to diagram.
+
+## Step 2 — Read the Code
+
+Read the relevant source files. Look for:
+- Function signatures and call chains
+- API endpoints and request handlers
+- Database models, schemas, ORM entities
+- State machines, status enums, workflow transitions
+- Service-to-service calls, message passing
+- Infrastructure config (Docker, k8s, terraform)
+- Import graphs and module dependencies
+
+## Step 3 — Pick the Diagram Type
+
+| What you found | Diagram type |
+|---|---|
+| API handler calling other services/DB | `sequence` |
+| Multiple models with relationships | `er` |
+| Service/module dependency graph | `c4` (container level) |
+| State enum, FSM, workflow transitions | `state` |
+| Decision logic, branching control flow | `flowchart` |
+| Docker/k8s/cloud infra config | `infra` |
+| Class hierarchy with methods | `class` |
+| Team/org structure data | `org` |
+
+If a single file contains multiple diagrammable things (e.g., models AND an API handler), generate multiple diagrams.
+
+## Step 4 — Generate
+
+1. Call `mcp__dgmo__get_language_reference("<type>")` for syntax.
+2. Call `mcp__dgmo__get_examples("<type>")` for idiomatic patterns.
+3. Write the DGMO using **real names from the code** — actual function names, model names, service names, field types.
+4. Call `mcp__dgmo__validate_diagram(dgmo)` — fix any errors.
+5. Call `mcp__dgmo__preview_diagram([{dgmo, title}])` to show the result.
+6. Save to `<descriptive-name>.dgmo` in the project.
+
+## Rules
+
+- **Use real names** — `UserService`, `orders` table, `POST /api/auth/login` — not generic placeholders
+- **Keep it focused** — a sequence diagram with 5-8 messages is better than one with 30. Show the main flow, not every edge case.
+- **Lean on inference** — don't declare `PostgresDB is a database` (the name auto-infers). Only use `is a` when the name doesn't match.
+- **No colons in directives** — `sequence Auth Flow`, not `chart: sequence`
+- **Multiple diagrams are fine** — if the code has both a schema and an API flow, generate both and use `preview_diagram` with multiple entries

package/.claude/commands/dgmo-document-project.md

@@ -0,0 +1,128 @@
+# /dgmo-document-project — Generate Diagrams for a Codebase
+
+You are generating a suite of DGMO diagrams that document the user's project. Your goal is to read the codebase, understand its architecture, and produce 3–6 diagrams that capture how the system works.
+
+## Prerequisites
+
+Before starting, verify that the DGMO MCP tools are available by calling `mcp__dgmo__list_chart_types`. If the tools are not available, tell the user to run `/dgmo` first to set up the MCP server, then come back to this command.
+
+## Step 1 — Understand the Project
+
+Read these files (skip any that don't exist):
+
+1. **README.md** or **README** — project purpose and overview
+2. **package.json** / **Cargo.toml** / **go.mod** / **pyproject.toml** / **requirements.txt** — tech stack and dependencies
+3. **docker-compose.yml** / **Dockerfile** / **k8s/** / **terraform/** — infrastructure
+4. **src/** or **app/** directory listing — code structure
+5. **.env.example** or config files — external services and integrations
+
+From this, determine:
+- What the project does (one sentence)
+- The tech stack (language, framework, database, message broker, etc.)
+- Key modules or services
+- External dependencies and integrations
+- Data models (if database-backed)
+
+## Step 2 — Decide Which Diagrams to Generate
+
+Pick 3–6 diagrams based on what the project actually has. Don't force a diagram type that doesn't fit. Use this decision matrix:
+
+| Signal in codebase | Diagram type | What to show |
+|---|---|---|
+| Multiple services, APIs, or modules | **c4** (context or container) | System components and their relationships |
+| REST/GraphQL endpoints, API handlers | **sequence** | 1–2 key request flows (e.g., auth, main business operation) |
+| Database models, ORM entities, schema files | **er** | Entity relationships and key fields |
+| Docker, k8s, cloud infra, load balancers | **infra** | Traffic flow and infrastructure components |
+| State machines, workflow engines, status fields | **state** | Key state transitions |
+| Multiple packages or layers | **flowchart** | Request lifecycle or data flow |
+| Microservices with message queues | **sequence** | Async event flow between services |
+
+**Rules:**
+- Always include a C4 context or container diagram — every project benefits from a high-level view
+- Prefer sequence diagrams for showing **behavior** (how things interact at runtime)
+- Prefer ER diagrams only if there's a real database schema to document
+- Don't generate infra diagrams for projects without infrastructure config
+- Don't generate more than 2 sequence diagrams — pick the most important flows
+
+## Step 3 — Get Syntax Help
+
+For each diagram type you'll generate, call:
+
+```
+mcp__dgmo__get_language_reference("<type>")
+```
+
+Also call `mcp__dgmo__get_examples("<type>")` to see real examples of that chart type. Use these as patterns — they show idiomatic DGMO style.
+
+## Step 4 — Generate the Diagrams
+
+Write the DGMO markup for each diagram. Follow these rules:
+
+- **Keep diagrams focused** — a C4 diagram with 5–8 components is better than one with 20
+- **Use real names from the codebase** — actual service names, model names, endpoint paths
+- **Lean on inference** — don't declare participant types unless the name doesn't match (e.g., `User` auto-infers as actor, `PostgresDB` as database)
+- **Add tags for color coding** when there are natural groupings (teams, domains, layers)
+- **Title every diagram** — the title goes on the first line after the chart type
+
+### Syntax reminders (no colons in directives or data):
+```
+sequence Auth Flow          // first line: type + title
+tag Layer alias l           // tag declaration (no colon)
+  Frontend(blue)
+  Backend(green)
+
+User -POST /login-> API     // sync arrow
+API ~publish~> Queue        // async arrow
+note Validates JWT          // note (no colon)
+```
+
+## Step 5 — Validate Before Rendering
+
+For each diagram, call `mcp__dgmo__validate_diagram(dgmo)` to check for errors. Fix any issues before proceeding.
+
+## Step 6 — Generate the Report
+
+Once all diagrams validate, bundle them into a report:
+
+```
+mcp__dgmo__generate_report({
+  title: "<Project Name> — Architecture Diagrams",
+  subtitle: "Auto-generated from codebase analysis",
+  sections: [
+    { title: "System Context (C4)", description: "High-level view of ...", dgmo: "..." },
+    { title: "Auth Flow", description: "How authentication works", dgmo: "..." },
+    ...
+  ],
+  theme: "dark",
+  palette: "nord",
+  include_source: true,
+  open: true
+})
+```
+
+## Step 7 — Save Source Files
+
+Write each diagram to a `diagrams/` directory in the project root:
+
+- `diagrams/c4-context.dgmo`
+- `diagrams/sequence-auth.dgmo`
+- `diagrams/er-schema.dgmo`
+- etc.
+
+Use descriptive filenames. Create the `diagrams/` directory if it doesn't exist.
+
+## Step 8 — Report to the User
+
+Summarize what was generated:
+
+1. List each diagram with a one-line description
+2. Mention the HTML report was opened in the browser
+3. Note the saved `.dgmo` files in `diagrams/`
+4. Suggest which diagrams might be worth expanding or adding next
+
+## Important Notes
+
+- This skill works with **any** project — not just TypeScript or JavaScript
+- Don't ask the user what diagrams to generate — make the decision based on what you find in the code. They can request changes after.
+- If the project is very small (single file, script), generate just 1–2 diagrams instead of forcing 6
+- If you can't determine the project structure, ask the user to point you at the main source directory

package/.claude/commands/dgmo.md

@@ -58,6 +58,18 @@ Then proceed with the user's original request using CLI fallback (see "Other out
 
 > **Note for future users:** To set up in one step from the terminal before starting a Claude Code session, run `dgmo --install-claude-code-integration`. It handles everything: installs `@diagrammo/dgmo-mcp`, writes the skill, and configures the MCP server.
 
+## Project Awareness
+
+At the start of a session (or when the user first invokes `/dgmo`), scan for existing `.dgmo` files:
+
+```bash
+find . -name '*.dgmo' -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null | head -20
+```
+
+If you find any, mention them briefly: "I see N diagrams in your project (e.g. `diagrams/auth-flow.dgmo`, `diagrams/er-schema.dgmo`). I can edit any of these or create new ones."
+
+Don't block on this — if no files found, just proceed.
+
 ## Getting Syntax Help
 
 **Always use the MCP tool first** if it's available in this session:
@@ -69,19 +81,89 @@ mcp__dgmo__get_language_reference("sequence") // specific chart type
 
 This is the authoritative, always-up-to-date syntax reference. Use it before guessing syntax.
 
+For **examples** of real diagrams, call `mcp__dgmo__get_examples("<type>")` — these are curated gallery fixtures that show idiomatic DGMO patterns. Use them as few-shot references when generating.
+
 ## Your Workflow
 
 **Primary goal: get the user seeing a visualization as fast as possible.**
 
-When the user asks you to create or edit a diagram:
-
-1. **Get syntax** — call `mcp__dgmo__get_language_reference("<type>")` if you're unsure of the syntax.
-2. **Write the `.dgmo` content** — compose the markup.
-3. **Open in browser immediately** — call `mcp__dgmo__preview_diagram([{dgmo, title}])` without asking. This is always the right default. The browser preview includes the dgmo source collapsed at the bottom and a dark/light toggle.
-4. **Save the source file** (if working in a project) — write it to `<name>.dgmo` so the user has an editable copy.
+### Creating a new diagram
+
+1. **Pick the right chart type** — don't ask the user. Use these heuristics:
+   - "show our API" / "how does X work" → `sequence`
+   - "architecture" / "system overview" → `c4`
+   - "database" / "schema" / "models" → `er`
+   - "infrastructure" / "deployment" / "traffic" → `infra`
+   - "process" / "decision" / "flow" → `flowchart`
+   - "states" / "lifecycle" / "transitions" → `state`
+   - "org" / "team" / "hierarchy" → `org`
+   - "roadmap" / "project status" → `initiative-status` or `gantt`
+   - "compare" / "metrics" / "data" → `bar`, `line`, `pie`, etc.
+   - If genuinely ambiguous, suggest your best guess with a one-line rationale.
+2. **Get syntax + examples** — call `mcp__dgmo__get_language_reference("<type>")` and `mcp__dgmo__get_examples("<type>")`.
+3. **Write the `.dgmo` content** — compose the markup.
+4. **Validate first** — call `mcp__dgmo__validate_diagram(dgmo)` to catch syntax errors before rendering. If errors come back, fix them and validate again.
+5. **Open in browser** — call `mcp__dgmo__preview_diagram([{dgmo, title}])` without asking. This is always the right default.
+6. **Save the source file** (if working in a project) — write it to `<name>.dgmo` so the user has an editable copy.
 
 Do not ask the user how they want to view the diagram. Just open it. They can ask for other formats if they want.
 
+### Editing an existing diagram
+
+When the user asks to modify a `.dgmo` file or says "update this diagram":
+
+1. **Read the file** — use the Read tool to get the current content.
+2. **Understand it** — identify the chart type, key elements, and structure.
+3. **Make the change** — edit the file using the Edit tool. Preserve the user's style and organization.
+4. **Validate** — call `mcp__dgmo__validate_diagram(dgmo)` on the updated content.
+5. **Preview** — call `mcp__dgmo__preview_diagram` so the user sees the result immediately.
+
+Keep the diff minimal — don't rewrite the whole file when adding one element.
+
+### Diagramming from code
+
+When the user says "diagram this", "diagram this file", or "show me how X works":
+
+1. **Read the relevant source code** — the file, function, or module they're pointing at.
+2. **Choose the best diagram type** based on what the code does:
+   - API handler / controller → `sequence` showing the request flow
+   - Database models / ORM entities → `er` showing relationships
+   - State machine / status enum → `state` showing transitions
+   - Module imports / service dependencies → `c4` or `flowchart`
+   - Infrastructure config (Docker, k8s, terraform) → `infra`
+3. **Extract real names** — use actual function names, service names, model names from the code.
+4. **Generate, validate, preview** — same as creating a new diagram.
+
+### Error recovery
+
+When `validate_diagram` or `render_diagram` returns errors:
+
+1. **Read the error messages** — they include line numbers and descriptions.
+2. **Fix the specific issues** — don't regenerate from scratch unless there are many errors.
+3. **Validate again** — loop until clean.
+4. **Then render** — only call `preview_diagram` or `render_diagram` after validation passes.
+
+Common fixes:
+- "Unknown directive" → check spelling, remove colons from directives
+- "Expected number" → data rows use spaces not colons: `Label 100` not `Label: 100`
+- Duplicate name → parentheses strip color from display name; `App (TS)` and `App (Rust)` both become `App`
+
+### Side-by-side variants
+
+When the user asks to compare layouts, themes, or approaches:
+
+```
+mcp__dgmo__preview_diagram([
+  { title: "Option A — Detailed", dgmo: "..." },
+  { title: "Option B — Simplified", dgmo: "..." }
+])
+```
+
+This opens a single page with both diagrams. Use this for:
+- Light vs dark theme comparisons
+- Different levels of detail
+- Alternative structures for the same data
+
 ### Other output options (only when explicitly requested)
 
 | What the user wants | How to do it |
@@ -93,6 +175,39 @@ Do not ask the user how they want to view the diagram. Just open it. They can as
 | **Shareable URL** | `mcp__dgmo__share_diagram(dgmo)` → returns a URL; immediately run `open <url>` — do NOT just display the URL |
 | **Copy markup to clipboard** | Run `echo '<dgmo markup>' \| pbcopy` |
 
+### Embedding diagrams in docs
+
+When the user wants a diagram in a README, PR description, or markdown file:
+
+1. **Generate a share URL** — `mcp__dgmo__share_diagram(dgmo)` returns a `diagrammo.app` URL.
+2. **Render a PNG** — `mcp__dgmo__render_diagram(dgmo, format:"png", theme:"light", palette:"nord")` returns a temp path.
+3. **Insert into markdown** — either:
+   - Copy the PNG to the project (e.g. `docs/images/auth-flow.png`) and reference it: `![Auth Flow](docs/images/auth-flow.png)`
+   - Use the share URL directly: `![Auth Flow](https://diagrammo.app/d#...)`
+4. **For PRs** — prefer share URLs (no binary file to commit). For README/docs — prefer committed PNGs (they work offline).
+
+Always generate both light and dark variants if the doc will be viewed in both modes, or use `theme:"transparent"` for universal backgrounds.
+
+### Batch rendering
+
+When the user asks to render all diagrams in a directory:
+
+```bash
+for f in diagrams/*.dgmo; do dgmo "$f" -o "${f%.dgmo}.png" --theme dark --palette nord; done
+```
+
+Or for SVG: replace `.png` with `.svg` in the output.
+
+### Share link to clipboard
+
+After generating a share link, always copy it to the clipboard automatically:
+
+```bash
+echo '<url>' | pbcopy
+```
+
+Then tell the user it's been copied.
+
 ## CLI Reference
 
 ```
@@ -141,37 +256,31 @@ Key options:
 | `initiative-status` | Project roadmap with dependency tracking |
 | `sitemap` | Website / app navigation structure |
 | `infra` | Infrastructure traffic flow with rps computation |
+| `gantt` | Project scheduling with dependencies |
 
 ## Key Syntax Patterns
 
 ### Common to all diagrams
 
 ```
-chart: sequence        // explicit type (optional — auto-detected)
-title: My Diagram
-palette: catppuccin    // override palette
+sequence Auth Flow     // first line: chart type + optional title
+palette catppuccin     // directives are space-separated (no colon)
 
 // This is a comment (only // syntax — not #)
 ```
 
-Inline colors on most elements: append `(colorname)` — e.g. `North(red): 850`, `[Process(blue)]`.
+Inline colors on most elements: append `(colorname)` — e.g. `North(red) 850`, `[Process(blue)]`.
 Named colors: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `teal`, `cyan`, `gray`.
 
 ### sequence (most commonly used)
 
 ```
-chart: sequence
-title: Auth Flow
-
-// Participants auto-inferred, or declare explicitly:
-User is an actor
-API is a service
-DB is a database
+sequence Auth Flow
 
 User -Login-> API
 API -Find user-> DB
 DB -user record-> API
-note:
+note
   Indexed lookup on email column
 
 if credentials valid
@@ -181,16 +290,17 @@ else
 
 == Logout ==
 
-note: session cleanup
+note session cleanup
 User -Logout-> API
 API -Delete session-> DB
 ```
 
 - Sync: `A -label-> B` · Async: `A ~label~> B` · Unlabeled: `A -> B`
 - Blocks: `if` / `else`, `loop`, `parallel` — closed by indentation (no `end` keyword)
-- Notes: place `note: text` after a message — it naturally associates with that position. Prefer this over `note on Participant:` anchoring; it's more compact and reads better.
-  - Single-line: `note: text`
-  - Multi-line: `note:` then indent continuation lines beneath it
+- Notes: place `note text` after a message — it naturally associates with that position.
+  - Single-line: `note text`
+  - Multi-line: `note` then indent continuation lines beneath it
+  - Anchored: `note right of API` then indent continuation lines
 - Sections: `== Title ==`
 - Groups: `[Group Name]` with indented participants
 
@@ -208,34 +318,34 @@ Shapes: `(oval)` `[rect]` `<diamond>` `/parallelogram/` `[[subroutine]]` `[docum
 
 ```
 // bar
-title: Revenue by Region
-series: Revenue
-North: 850
-South: 620
+bar Revenue by Region
+series Revenue
+North 850
+South 620
 
 // line (multi-series)
-series: Sales(red), Costs(blue)
-Q1: 100, 50
-Q2: 120, 55
+series Sales(red), Costs(blue)
+Q1 100, 50
+Q2 120, 55
 
 // pie
-chart: pie
-labels: percent
-Company A: 40
-Company B: 35
+pie Market Share
+labels percent
+Company A 40
+Company B 35
 ```
 
 ### er
 
 ```
 users
-  id: int [pk]
-  email: varchar [unique]
+  id int [pk]
+  email varchar [unique]
   1-writes-* posts
 
 posts
-  id: int [pk]
-  author_id: int [fk]
+  id int [pk]
+  author_id int [fk]
 ```
 
 ### org
@@ -253,19 +363,20 @@ CEO
 ### infra
 
 ```
-chart: infra
+infra
+
 edge
-  rps: 10000
+  rps 10000
   -> CDN
 
 CDN
-  cache-hit: 80%
+  cache-hit 80%
   -> API
 
 API
-  instances: 3
-  max-rps: 500
-  latency-ms: 45
+  instances 3
+  max-rps 500
+  latency-ms 45
 ```
 
 ## Anti-Patterns
@@ -278,17 +389,41 @@ parallel else      ❌  not supported — use separate parallel blocks
 == Foo(#ff0000) == ❌  hex colors not supported — use named colors: == Foo(red) ==
 A -routes to /api-> B  ❌  -> inside a label is ambiguous — rephrase the label
 end                ❌  not needed — indentation closes blocks in sequence diagrams
-note on API: text  ⚠️  prefer plain `note: text` after a message — anchoring to a participant is rarely needed
-note: line1\nline2  ❌  multi-line notes use indented continuation, not \n:
-                        note:
-                          line1
-                          line2
+chart: sequence    ❌  use `sequence Title` as the first line (no colon)
+title: My Diagram  ❌  title goes on the first line after chart type
+series: A, B       ❌  use `series A, B` (no colon)
+Label: 100         ❌  use `Label 100` (no colon in data rows)
+tag: Group         ❌  use `tag Group` (no colon)
+note: text         ❌  use `note text` (no colon)
 ```
 
 ## Tips
 
-- Default theme: `dark`, default palette: `nord` (nord dark mode) — use these unless the user requests otherwise.
+- Default theme: `dark`, default palette: `nord` — use these unless the user requests otherwise.
+- Always validate before rendering — `validate_diagram` is much faster than a failed render.
+- Always call `get_examples` before generating an unfamiliar chart type — real examples beat guessing.
 - Stdin mode for quick renders: `echo "..." | dgmo -o out.png`
 - For C4, `--c4-level` drills from context → containers → components → deployment.
-- When auto-detection picks the wrong chart type, add an explicit `chart:` directive.
+- When auto-detection picks the wrong chart type, add an explicit type as the first word on the first line.
 - `mcp__dgmo__preview_diagram` accepts multiple diagrams at once — useful for showing variants side by side.
+- When the user says "diagram this" while looking at code, read the code first and pick the chart type yourself — don't ask.
+
+## Related Commands
+
+Tell the user about these when relevant:
+
+- **`/dgmo-diagram-this`** — Point it at a file, function, or module and it generates the right diagram from the code. Use when the user says "diagram this" or "how does this work?"
+- **`/dgmo-document-project`** — Scans the entire codebase and generates a suite of 3–6 architecture diagrams (C4, sequence, ER, infra) as an HTML report. Use when the user wants project documentation.
+
+## AI Integrations Beyond Claude Code
+
+DGMO works with other AI tools too. If the user asks about using Diagrammo with other editors or AI assistants, point them to **https://diagrammo.app/ai** which covers:
+
+- **Cursor** — `.cursorrules` file provides DGMO syntax context to the AI
+- **Windsurf** — `.windsurfrules` file works the same way with Cascade
+- **GitHub Copilot** — `.github/copilot-instructions.md` teaches Copilot the syntax
+- **OpenAI Codex CLI** — `AGENTS.md` + `.codex/config.toml` configuration
+
+These context files are already included in the `@diagrammo/dgmo` npm package. For any project using dgmo as a dependency, the AI tool picks them up automatically.
+
+The MCP server (`@diagrammo/dgmo-mcp`) also works with **Claude Desktop** and any MCP-compatible client — not just Claude Code.

package/.cursorrules

@@ -13,8 +13,7 @@ When the user asks for a diagram, visualization, or chart, generate a `.dgmo` fi
 
 ### Sequence diagram
 ```
-chart: sequence
-title: Auth Flow
+sequence Auth Flow
 
 User -Login-> API
 API -Find user-> DB
@@ -27,8 +26,7 @@ DB -user-> API
 
 ### Flowchart
 ```
-chart: flowchart
-title: Process
+flowchart Process
 
 (Start) -> <Valid?>
   -yes-> [Process] -> (Done)
@@ -37,34 +35,32 @@ title: Process
 
 ### Bar chart
 ```
-chart: bar
-title: Revenue
-series: USD
+bar Revenue
+series USD
 
-North: 850
-South: 620
-East: 1100
+North 850
+South 620
+East 1100
 ```
 
 ### ER diagram
 ```
-chart: er
-title: Schema
+er Schema
 
 users
-  id: int [pk]
-  email: varchar [unique]
+  id int [pk]
+  email varchar [unique]
 
 posts
-  id: int [pk]
-  user_id: int [fk]
+  id int [pk]
+  user_id int [fk]
 
 users 1--* posts : writes
 ```
 
 ### Org chart
 ```
-chart: org
+org
 
 CEO
   VP Engineering
@@ -75,25 +71,24 @@ CEO
 
 ### C4 architecture
 ```
-chart: c4
-title: System
+c4 System
 
-person User
-system App | description: Main application
-  -Uses-> User
+Web App is a container | description: SPA, tech: React
+  -Uses-> API
+User is a person
+  -Browses-> Web App
 ```
 
 ### Infra chart
 ```
-chart: infra
-direction: LR
+infra
 
 edge
-  rps: 10000
+  rps 10000
   -> CDN
 
 CDN
-  cache-hit: 80%
+  cache-hit 80%
   -> LB
 
 LB
@@ -101,25 +96,25 @@ LB
   -/web-> Web | split: 30%
 
 API
-  instances: 3
-  max-rps: 500
-  latency-ms: 45
+  instances 3
+  max-rps 500
+  latency-ms 45
 ```
 
-Properties: `cache-hit`, `firewall-block`, `ratelimit-rps`, `bot-filter`, `max-rps`, `instances` (N or N-M), `latency-ms`, `cb-error-threshold`. Groups: `[Name]` with children. Roles are inferred from behavior.
+Properties: `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.
 
 ## All 32 chart types
 
-bar, line, multi-line, area, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, state, class, er, org, kanban, c4, initiative-status, sitemap, infra
+bar, line, multi-line, area, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, state, class, er, org, kanban, c4, initiative-status, sitemap, infra, gantt
 
 ## Common patterns
 
-- `chart: type` — explicit chart type (auto-detected if unambiguous)
-- `title: text` — diagram title
+- `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 alias g` — tag groups for metadata
+- `(colorname)` — inline colors: `Label(red) 100`
+- `series A(red), B(blue)` — multi-series with colors
+- `tag Group alias g` — tag groups for metadata
 
 ## Rendering
 
@@ -136,7 +131,7 @@ Install: `brew install diagrammo/dgmo/dgmo` or `npm install -g @diagrammo/dgmo`
 - Don't use `#` for comments — use `//`
 - Don't use `end` to close sequence blocks — indentation closes them
 - Don't use hex colors in section headers — use named colors
-- Don't forget `chart:` directive when content is ambiguous
+- Don't use colons in chart type, title, directives, or data rows — use spaces
 - Sequence arrows: `->` (sync), `~>` (async) — always left-to-right
 
 Full reference: `docs/language-reference.md`