@diagrammo/dgmo 0.34.0 → 0.36.0

package/docs/ai-integration.md

@@ -4,44 +4,58 @@ Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code,
 
 ---
 
-## MCP Server (recommended for Claude)
+## One-step setup (recommended)
 
-`@diagrammo/dgmo-mcp` provides an MCP server that gives Claude the ability to render, share, and look up DGMO diagrams directly — no file management needed.
+Install the `dgmo` CLI, then run one command:
 
-**5 tools:** `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`
+```bash
+brew install diagrammo/dgmo/dgmo   # or: npm install -g @diagrammo/dgmo
+dgmo install                       # auto-detects every AI assistant you have
+```
+
+`dgmo install` with **no target** scans for Claude Code, Codex, Claude Desktop, Cursor, Windsurf, and Copilot, then configures each one non-interactively — no prompts, no second package to install. The only binary you ever need is `dgmo`; it provides the MCP server through its own `dgmo mcp` subcommand.
+
+Target a single assistant, or pick a scope, when you want to:
+
+```bash
+dgmo install claude-code              # just one surface
+dgmo install codex --scope project    # write config into the current repo
+dgmo install --dry-run                # preview every change, write nothing
+```
+
+For Claude Code this copies the `/dgmo` skill into `~/.claude/commands/` (full dgmo context — all chart types, CLI flags, workflow, and tips) and adds the MCP server to `~/.claude/settings.json`. Restart the assistant afterward.
+
+**Keeping it current:**
+- **Homebrew** bundles the MCP server, so `brew upgrade dgmo` upgrades the CLI *and* the server together. Re-run `dgmo install` afterward only to refresh the **skill files** (those are copies in your home dir).
+- **npm global**: a plain `dgmo` upgrade doesn't touch the server or skill copies — re-run `dgmo install`, which overwrites the skills and upgrades the server to the latest.
+- Either way, `DGMO_MCP_LATEST=1` in the environment makes `dgmo mcp` always fetch the newest server at launch (network round-trip on start), so it's never stale.
+
+---
+
+## Manual MCP configuration
 
-Add to `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project):
+`dgmo install` is the easy path. To wire the MCP server by hand, point any MCP client at the `dgmo` binary's `mcp` subcommand:
 
 ```json
 {
   "mcpServers": {
     "dgmo": {
-      "command": "npx",
-      "args": ["-y", "@diagrammo/dgmo-mcp"]
+      "command": "dgmo",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-See `dgmo-mcp/README.md` for full configuration options.
+**Tools:** `check_app_installed`, `suggest_chart_type`, `get_language_reference`, `get_examples`, `validate_diagram`, `open_in_app`, `share_diagram`, `render_diagram`, `preview_diagram`, `generate_report`, `list_chart_types`. `dgmo mcp` execs the installed server, or fetches it on demand via `npx` if it isn't installed yet — so no separate `dgmo-mcp` step is required. (If you'd rather not install the CLI at all, `{ "command": "npx", "args": ["-y", "@diagrammo/dgmo-mcp"] }` still works.) See `dgmo-mcp/README.md` for full options.
 
----
-
-## Claude Code — Skill (slash command)
-
-Installs a `/dgmo` slash command that gives Claude full dgmo context — all chart types, CLI flags, workflow, and tips.
-
-```bash
-dgmo --install-claude-skill
-```
-
-This copies a skill file into `~/.claude/commands/`, making `/dgmo` available in every Claude Code session.
+Output default is app-aware: `check_app_installed` decides it — when the Diagrammo desktop app is installed, the diagram source is saved and opened live in the app (`open_in_app` with the saved file path); otherwise an online share URL is opened. A PNG/SVG is rendered only when the user explicitly asks.
 
 ---
 
 ## Claude Code — CLAUDE.md snippet
 
-To teach Claude about DGMO in a specific project without the global skill, paste the generated core below into your `CLAUDE.md`. It is the same single-sourced anti-patterns + 45-type index that every DGMO AI surface carries (see "How the AI core is generated"). Render with `dgmo file.dgmo` (PNG) or `dgmo file.dgmo -o url` (shareable link); full per-type syntax lives in `node_modules/@diagrammo/dgmo/docs/language-reference.md`.
+To teach Claude about DGMO in a specific project without the global skill, paste the generated core below into your `CLAUDE.md`. It is the same single-sourced anti-patterns + 45-type index that every DGMO AI surface carries (see "How the AI core is generated"). Render with `dgmo file.dgmo` (PNG) or `dgmo share file.dgmo` (shareable link); full per-type syntax lives in `node_modules/@diagrammo/dgmo/docs/language-reference.md`.
 
 <!-- GENERATED by dgmo/scripts/gen-ai-core.mjs from docs/language-reference.md — DO NOT EDIT between the DGMO-AI-CORE markers; run `node scripts/gen-ai-core.mjs` (or sync-language-ref.sh) to regenerate. -->
 <!-- DGMO-AI-CORE:START -->
@@ -477,7 +491,15 @@ DGMO ships context files for popular AI coding tools, included in the npm packag
 | `.cursorrules` | Cursor | Auto-loaded when present in project root |
 | `.windsurfrules` | Windsurf | Auto-loaded when present in project root (byte-identical to `.cursorrules`) |
 
-Copy the relevant file into your project root:
+The easiest way to set these up is `dgmo install` — it does the right thing per tool:
+
+```bash
+dgmo install cursor      # wires MCP (~/.cursor/mcp.json) + drops .cursorrules
+dgmo install windsurf    # wires MCP (~/.codeium/windsurf/mcp_config.json) + .windsurfrules
+dgmo install copilot     # writes ./.github/copilot-instructions.md (Copilot has no MCP)
+```
+
+Cursor and Windsurf speak MCP, so `dgmo install` gives them the full render/share tools (pointed at `dgmo mcp`), plus the inline rules file. Copilot is guidance-only. `dgmo install` with no target also writes Copilot's file automatically when the current repo has a `.github` directory. To set the context files up by hand instead:
 
 ```bash
 # From node_modules (if installed as a dependency)
@@ -510,14 +532,14 @@ Regeneration runs inside `sync-language-ref.sh`; a Vitest gate parses every emit
 ```bash
 dgmo diagram.dgmo                # PNG output
 dgmo diagram.dgmo -o output.svg  # SVG output
-dgmo diagram.dgmo -o url         # Shareable diagrammo.app URL
-dgmo diagram.dgmo -o url --copy  # URL copied to clipboard
-dgmo --chart-types               # List all supported chart types
-dgmo --chart-types --json        # Machine-readable chart type list
+dgmo share diagram.dgmo          # Shareable diagrammo.app URL (copied to clipboard)
+dgmo share diagram.dgmo --no-copy  # Print URL without touching the clipboard
+dgmo types                       # List all supported chart types
+dgmo types --json                # Machine-readable chart type list
 ```
 
 ---
 
 ## Supported chart types
 
-Run `dgmo --chart-types` for the full, authoritative list, call the MCP `list_chart_types` tool, or see the 45-type index in `docs/language-reference.md` (§0 AI Core). The list is intentionally not duplicated here — it drifts every time a chart type is added.
+Run `dgmo types` for the full, authoritative list, call the MCP `list_chart_types` tool, or see the 45-type index in `docs/language-reference.md` (§0 AI Core). The list is intentionally not duplicated here — it drifts every time a chart type is added.

package/docs/language-reference.md

@@ -3188,7 +3188,7 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 <!-- TYPE:map -->
 
 <!-- TIPS start -->
-**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
+**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map-search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
 <!-- TIPS end -->
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
@@ -3332,7 +3332,7 @@ cove -> hav l: March    # the LINE turns green
   - The redundant `Georgia US-GA` still works but isn't needed (a mismatched code like `Georgia US-CA` is rejected). A bare ambiguous `Georgia` follows the inferred US-scope signal and warns with both fixes named.
 - **IATA airport codes** resolve to airport coordinates — `poi JFK`, `route JFK -> LAX` — with no new syntax (large international hubs + all US scheduled-commercial airports). Case-insensitive (`jfk`/`JFK`). Airports are the **lowest-precedence** identifier: a token that is both a city and a code resolves to the **city** (`Ufa` → the city, not UFA airport), with a hint naming the airport. Resolution is by **code only** (never by airport name); the POI label is the typed code. An unknown three-letter code errors with an `as <CODE>` coordinates hint.
 - **A city name must match the gazetteer's canonical form** — `New York City`, not `New York`; `Washington, D.C.`, not `Washington`. An unrecognized name is dropped (with a did-you-mean note) and the map reframes around the places that *did* resolve, so the result can look complete but be missing a point. Use the exact name or coordinates.
-- **Discover the exact token** with the lookup surface rather than guessing — `dgmo map search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
+- **Discover the exact token** with the lookup surface rather than guessing — `dgmo map-search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
 - Positional coordinates are the escape hatch for anything missing/ambiguous (including forcing an airport over a colliding city: `poi 54.56 55.87 as UFA`).
 
 ### Directives & reserved keys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {
@@ -140,7 +140,7 @@
     "check:publish": "publint",
     "check:size": "pnpm build && du -sh dist/ && echo '---' && ls -lh dist/*.js dist/*.cjs",
     "check:types": "attw --pack . --ignore-rules no-resolution false-export-default",
-    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\"",
+    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo install claude-code\\n')\"",
     "prepare": "husky"
   },
   "dependencies": {

package/src/advanced.ts

@@ -797,15 +797,3 @@ export { themes, type Theme } from './themes';
 
 // Public-API alias for parseDgmo (also exported from the public root as `validate`)
 export { parseDgmo as validate } from './dgmo-router';
-
-// `dgmo migrate` — programmatic access to the 0.18.0 legacy `|` → §1.4
-// migration. Consumed by `@diagrammo/dgmo-mcp`'s `migrate_diagram` tool
-// and by external authoring tools that want to offer in-place migration.
-export {
-  migrateContent,
-  formatLineDiff,
-  isLegacyMetadataLine,
-  findUnsafePipePositions,
-  transformLine,
-} from './migrate';
-export type { ContentMigration, TransformResult } from './migrate';

package/src/c4/parser.ts

@@ -516,7 +516,7 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
           } else {
             pushError(
               lineNumber,
-              `"container ${refName}" must be inside a deployment node`
+              `"container ${refName}" must be indented under a deployment node (e.g. under 'Prod is a deployment-node')`
             );
           }
           continue;
@@ -585,7 +585,10 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
           indent,
         });
       } else {
-        pushError(lineNumber, `"${sectionType}" must be inside an element`);
+        pushError(
+          lineNumber,
+          `"${sectionType}" must be indented under an element (e.g. under 'Web App is a container')`
+        );
       }
       continue;
     }
@@ -618,7 +621,10 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
           indent,
         });
       } else {
-        pushError(lineNumber, `Group [${groupName}] must be inside an element`);
+        pushError(
+          lineNumber,
+          `Group [${groupName}] must be indented under an element (e.g. under 'Web App is a container')`
+        );
       }
       continue;
     }
@@ -1049,7 +1055,10 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
       }
       desc.push(descResult.text);
     } else {
-      pushError(lineNumber, `Unexpected content: "${trimmed}"`);
+      pushError(
+        lineNumber,
+        `Unexpected content: "${trimmed}". Expected an element ('Web App is a container'), a relationship ('-Uses-> Database'), indented metadata ('tech: React'), or a group ('[Backend]'). (§8)`
+      );
     }
   }
 
@@ -1154,7 +1163,7 @@ function validateRelationshipTargets(
     for (const el of elements) {
       for (const rel of el.relationships) {
         if (!knownNames.has(normalizeName(rel.target))) {
-          let msg = `Relationship target "${rel.target}" not found`;
+          let msg = `Relationship target "${rel.target}" not found — declare it first (e.g. '${rel.target} is a container'), then reference it in the arrow`;
           const hint = suggest(normalizeName(rel.target), allNames);
           if (hint) msg += `. ${hint}`;
           pushWarning(rel.lineNumber, msg, 'warning');
@@ -1193,7 +1202,7 @@ function validateDeploymentRefs(
     for (const node of nodes) {
       for (const ref of node.containerRefs) {
         if (!knownNames.has(normalizeName(ref))) {
-          let msg = `Deployment reference "container ${ref}" not found`;
+          let msg = `Deployment reference "container ${ref}" not found — declare the container element first, then reference it under the deployment node`;
           const hint = suggest(normalizeName(ref), allNames);
           if (hint) msg += `. ${hint}`;
           pushWarning(node.lineNumber, msg, 'warning');

package/src/chart.ts

@@ -174,7 +174,7 @@ export function parseChart(
       result.diagnostics.push(
         makeDgmoError(
           lineNumber,
-          `'${trimmed}' — ## syntax is no longer supported. Use [Group] containers instead`
+          `'${trimmed}' removed — use a bracket container '[${trimmed.replace(/^#+\s*/, '')}]' instead (## headers are no longer supported).`
         )
       );
       continue;

package/src/class/parser.ts

@@ -308,7 +308,7 @@ export function parseClassDiagram(
         result.diagnostics.push(
           makeDgmoError(
             lineNumber,
-            '"no-auto-color" has been removed.',
+            '"no-auto-color" was removed — colors are always auto-assigned from the palette; delete this line.',
             'warning'
           )
         );
@@ -458,7 +458,11 @@ export function parseClassDiagram(
 
     // Catch-all: nothing matched this line
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, 'warning')
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. Classes start uppercase at indent 0 ('Ship'); members are indented and colon-typed ('+ name: string', '+ sail(): void'); relationships are indented arrows ('--|> Vessel'). (§10)`,
+        'warning'
+      )
     );
   }
 

package/src/cli-banner.ts

@@ -7,9 +7,8 @@
 // sampled from the default `slate` palette (corporate blue → teal →
 // steel cyan) so the wordmark matches the brand.
 //
-// Honors the same guards as `dgmo cat`: color only when stdout is a TTY
-// and NO_COLOR is unset; otherwise prints plain ASCII so pipes/CI stay
-// clean.
+// Color only when stdout is a TTY and NO_COLOR is unset; otherwise prints
+// plain ASCII so pipes/CI stay clean.
 
 import { getPalette } from './palettes';