@diagrammo/dgmo 0.6.2 → 0.6.3

package/.claude/commands/dgmo.md

@@ -4,7 +4,94 @@ You are helping the user author, render, and share diagrams using the `dgmo` CLI
 
 ## What is dgmo?
 
-`dgmo` is a CLI tool that renders `.dgmo` diagram files to PNG, SVG, or shareable URLs. Diagrams are written in a plain-text DSL.
+`dgmo` is a CLI tool and library that renders `.dgmo` diagram files to PNG, SVG, or shareable URLs. Diagrams are written in a plain-text DSL.
+
+## Setup Check — Run This First
+
+**Before doing anything else**, check whether the MCP tools are available in this session by attempting to call `mcp__dgmo__list_chart_types`. If that tool exists and succeeds, skip this section entirely.
+
+If the MCP tools are **not** available, run the setup flow below — do not ask the user, just do it:
+
+### Step 1 — Install the CLI (if missing)
+
+```bash
+which dgmo || npm install -g @diagrammo/dgmo
+```
+
+### Step 2 — Install the MCP server (if missing)
+
+```bash
+which dgmo-mcp || npm install -g @diagrammo/dgmo-mcp
+```
+
+### Step 3 — Configure the MCP server
+
+Ask the user:
+
+> "Where should I configure the MCP server?
+> 1) This project only — write `.mcp.json` here [default]
+> 2) Globally — add to `~/.claude/settings.json` (works in all projects)"
+
+**Option 1 (default):** Create or update `.mcp.json` in the current working directory:
+
+```json
+{
+  "mcpServers": {
+    "dgmo": {
+      "command": "dgmo-mcp"
+    }
+  }
+}
+```
+
+If `.mcp.json` already exists and has other servers, merge the `dgmo` entry in — do not overwrite the file.
+
+**Option 2 (global):** Add the `dgmo` entry to the `mcpServers` object in `~/.claude/settings.json`. Read the file first and merge — do not overwrite other keys.
+
+### Step 4 — Prompt restart
+
+Tell the user:
+
+> "Done. **Restart Claude Code** to activate the MCP server — diagram preview and rendering will be available in the next session."
+
+Then proceed with the user's original request using CLI fallback (see "Other output options" below).
+
+> **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.
+
+## Getting Syntax Help
+
+**Always use the MCP tool first** if it's available in this session:
+
+```
+mcp__dgmo__get_language_reference            // full reference
+mcp__dgmo__get_language_reference("sequence") // specific chart type
+```
+
+This is the authoritative, always-up-to-date syntax reference. Use it before guessing syntax.
+
+## 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.
+
+Do not ask the user how they want to view the diagram. Just open it. They can ask for other formats if they want.
+
+### Other output options (only when explicitly requested)
+
+| What the user wants | How to do it |
+|---|---|
+| **Quick look in the desktop app** | `mcp__dgmo__open_in_app(dgmo)` — opens directly in Diagrammo (macOS) |
+| **View in macOS Preview** | `mcp__dgmo__render_diagram(dgmo, format:"png", theme:"dark", palette:"nord")` → get temp path → `open <path>` |
+| **Save as PNG** | `mcp__dgmo__render_diagram(dgmo, format:"png", theme:"dark", palette:"nord")` → returns temp path; offer to copy to their preferred location. Or CLI: `dgmo file.dgmo -o out.png --theme dark --palette nord` |
+| **Save as SVG** | `mcp__dgmo__render_diagram(dgmo, format:"svg", theme:"dark", palette:"nord")` returns SVG text — write it to the desired path. Or CLI: `dgmo file.dgmo -o out.svg --theme dark --palette nord` |
+| **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` |
 
 ## CLI Reference
 
@@ -45,32 +132,163 @@ Key options:
 | `quadrant` | 2x2 positioning matrix |
 | `sequence` | Message / interaction flows |
 | `flowchart` | Decision trees, process flows |
+| `state` | State machine / lifecycle |
 | `class` | UML class hierarchies |
 | `er` | Database schemas |
 | `org` | Hierarchical tree structures |
 | `kanban` | Task / workflow columns |
 | `c4` | System architecture (context → container → component → deployment) |
 | `initiative-status` | Project roadmap with dependency tracking |
+| `sitemap` | Website / app navigation structure |
+| `infra` | Infrastructure traffic flow with rps computation |
 
-## Your Workflow
+## Key Syntax Patterns
 
-When the user asks you to create or edit a diagram:
+### Common to all diagrams
 
-1. **Write or edit the `.dgmo` file** with the appropriate chart type and data.
-2. **Render it** with `dgmo <file>.dgmo -o <file>.png` to verify it produces output without errors.
-3. **Show the user** what was created and suggest a shareable URL with `dgmo <file>.dgmo -o url --copy` if they want to share it.
+```
+chart: sequence        // explicit type (optional — auto-detected)
+title: My Diagram
+palette: catppuccin    // override palette
 
-When the user asks for a **shareable link**, run:
+// This is a comment (only // syntax — not #)
 ```
-dgmo <file>.dgmo -o url --copy
+
+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
 
-## Getting Syntax Help
+// Participants auto-inferred, or declare explicitly:
+User is an actor
+API is a service
+DB is a database
+
+User -Login-> API
+API -Find user-> DB
+DB -user record-> API
+note:
+  Indexed lookup on email column
+
+if credentials valid
+  API -200 OK + token-> User
+else
+  API -401 Unauthorized-> User
+
+== Logout ==
+
+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
+- Sections: `== Title ==`
+- Groups: `[Group Name]` with indented participants
+
+### flowchart
+
+```
+(Start) -> <Valid Input?>
+  -yes-> [Process Data] -> (Done)
+  -no-> /Get Input/ -> <Valid Input?>
+```
+
+Shapes: `(oval)` `[rect]` `<diamond>` `/parallelogram/` `[[subroutine]]` `[document~]`
+
+### bar / line / pie (data charts)
+
+```
+// bar
+title: Revenue by Region
+series: Revenue
+North: 850
+South: 620
+
+// line (multi-series)
+series: Sales(red), Costs(blue)
+Q1: 100, 50
+Q2: 120, 55
 
-Run `dgmo --chart-types` to list types. For detailed syntax of a specific chart type, the best reference is the diagrammo.app documentation or existing `.dgmo` files in the project.
+// pie
+chart: pie
+labels: percent
+Company A: 40
+Company B: 35
+```
+
+### er
+
+```
+users
+  id: int [pk]
+  email: varchar [unique]
+  1-writes-* posts
+
+posts
+  id: int [pk]
+  author_id: int [fk]
+```
+
+### org
+
+```
+CEO
+  VP Engineering
+    [Platform Team]
+      Lead
+        Dev 1
+        Dev 2
+  VP Marketing
+```
+
+### infra
+
+```
+chart: infra
+edge
+  rps: 10000
+  -> CDN
+
+CDN
+  cache-hit: 80%
+  -> API
+
+API
+  instances: 3
+  max-rps: 500
+  latency-ms: 45
+```
+
+## Anti-Patterns
+
+```
+# comment          ❌  use // comment
+async A -> B: msg  ❌  use A ~msg~> B
+A <- B             ❌  left-pointing arrows removed — use B -> A
+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
+```
 
 ## Tips
 
-- Default theme is `light` and default palette is `nord` — ask the user if they have a preference before rendering a final export.
-- For C4 diagrams, use `--c4-level` to drill from context → containers → components → deployment.
-- Stdin mode is useful for quick one-off renders: `echo "..." | dgmo -o out.png`
+- Default theme: `dark`, default palette: `nord` (nord dark mode) — use these unless the user requests otherwise.
+- 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.
+- `mcp__dgmo__preview_diagram` accepts multiple diagrams at once — useful for showing variants side by side.

package/AGENTS.md

@@ -0,0 +1,148 @@
+# DGMO Diagram Language — Codex Integration
+
+Use dgmo tools to create, render, and share diagrams. dgmo is a text-based diagram markup language that renders to SVG/PNG.
+
+## Quick setup
+
+If the MCP server is not yet configured:
+
+```bash
+dgmo --install-codex-integration
+```
+
+This installs the MCP server and writes the dgmo config to `.codex/config.toml`. Restart Codex to activate.
+
+## MCP Tools
+
+When the `dgmo` MCP server is configured, use these tools directly:
+- `preview_diagram` — renders diagram(s) and opens a live HTML preview in the browser (default for showing diagrams)
+- `render_diagram` — renders to PNG or SVG, returns file path
+- `share_diagram` — creates a shareable diagrammo.app URL
+- `open_in_app` — opens diagram in Diagrammo desktop app (macOS)
+- `list_chart_types` — lists all 32 supported chart types with descriptions
+- `get_language_reference` — fetches full syntax for any chart type (call this before generating an unfamiliar chart type)
+- `generate_report` — renders multiple diagrams into an HTML report with table of contents
+
+## When to use 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
+```
+chart: sequence
+title: Auth Flow
+
+User -Login-> API
+API -Find user-> DB
+DB -user-> API
+  if valid
+    API -200 OK-> User
+  else
+    API -401-> User
+```
+
+### Flowchart
+```
+chart: flowchart
+title: Process
+
+(Start) -> <Valid?>
+  -yes-> [Process] -> (Done)
+  -no-> /Get Input/ -> <Valid?>
+```
+
+### Bar chart
+```
+chart: bar
+title: Revenue
+series: USD
+
+North: 850
+South: 620
+East: 1100
+```
+
+### ER diagram
+```
+chart: er
+title: Schema
+
+users
+  id: int [pk]
+  email: varchar [unique]
+
+posts
+  id: int [pk]
+  user_id: int [fk]
+
+users 1--* posts : writes
+```
+
+### Org chart
+```
+chart: org
+
+CEO
+  VP Engineering
+    Team Lead A
+    Team Lead B
+  VP Marketing
+```
+
+### Infra chart
+```
+chart: infra
+direction: LR
+
+edge
+  rps: 10000
+  -> CDN
+
+CDN
+  cache-hit: 80%
+  -> LB
+
+LB
+  -> API | split: 70%
+  -> Web | split: 30%
+
+API
+  instances: 3
+  max-rps: 500
+  latency-ms: 45
+```
+
+## 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
+
+## Common patterns
+
+- `chart: type` — explicit chart type (auto-detected if unambiguous)
+- `title: text` — diagram title
+- `// comment` — only `//` comments (not `#`)
+- `(colorname)` — inline colors: `Label(red): 100`
+- `series: A(red), B(blue)` — multi-series with colors
+
+## Rendering via CLI
+
+```bash
+dgmo file.dgmo -o output.svg       # SVG
+dgmo file.dgmo -o url              # shareable link
+dgmo file.dgmo --json              # structured JSON output
+```
+
+## 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 in section headers — use named colors
+- Don't forget `chart:` directive when content is ambiguous
+- Sequence arrows: `->` (sync), `~>` (async) — always left-to-right
+
+Full reference: call `get_language_reference` MCP tool or visit diagrammo.app/docs