@diagrammo/dgmo 0.34.0 → 0.36.0

package/src/cli.ts

@@ -1,9 +1,8 @@
 /* eslint-disable no-console */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { execSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 import { homedir, platform } from 'node:os';
-import { resolve, join, basename, extname } from 'node:path';
-import { createInterface } from 'node:readline';
+import { resolve, join, dirname, basename, extname } from 'node:path';
 import { Resvg } from '@resvg/resvg-js';
 import { render } from './render';
 import {
@@ -18,13 +17,6 @@ import { DEFAULT_FONT_NAME } from './fonts';
 import { encodeDiagramUrl } from './sharing';
 import { resolveOrgImports } from './org/resolver';
 import { normalizePertSourceForShare } from './pert/share-normalize';
-import {
-  collectDgmoFiles,
-  collectEmbeddedFiles,
-  formatLineDiff,
-  migrateFile,
-} from './migrate';
-import { migrateEmbedded } from './migrate/embedded';
 import { renderBanner } from './cli-banner';
 import { searchMapLocations } from './map/completion';
 import { loadMapData } from './map/load-data';
@@ -34,430 +26,37 @@ const PALETTES = getAvailablePalettes().map((p) => p.id);
 
 const THEMES = ['light', 'dark', 'transparent'] as const;
 
-const CLAUDE_SKILL_CONTENT = `# dgmo — Diagrammo Diagram Assistant
-
-You are helping the user author, render, and share diagrams using the \`dgmo\` CLI and \`.dgmo\` file format.
-
-## What is dgmo?
-
-\`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"
-    }
+// The Claude Code skill (~/.claude/commands/dgmo.md) and the Codex skill
+// (SKILL.md — gen-ai-core covered, with a gate-enforced COMPLETE chart-type
+// index) are SHIPPED in this package via the "files" allowlist and are the
+// single source of truth. The installers below read those files rather than
+// carrying inline copies, so the chart-type list and syntax can never drift
+// from the maintained originals (the stale inline table was the root cause of
+// agents wrongly reporting that a chart type "does not exist").
+const PKG_ROOT = resolve(__dirname, '..');
+
+function readPackagedFile(...parts: string[]): string {
+  const p = join(PKG_ROOT, ...parts);
+  try {
+    return readFileSync(p, 'utf-8');
+  } catch {
+    console.error(`Could not read packaged file: ${p}`);
+    console.error(
+      'Your @diagrammo/dgmo install may be incomplete — try reinstalling it.'
+    );
+    process.exit(1);
   }
 }
-\`\`\`
-
-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
-
-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. **Save the source file** (if working in a project) — write it to \`<name>.dgmo\` so the user has an editable file.
-4. **Render and show** — pick the right output based on what the user wants (see below).
-
-### Output options — always offer these proactively after creating a diagram
-
-| 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) |
-| **Browser preview with theme toggle** | \`mcp__dgmo__preview_diagram([{dgmo, title}])\` — opens HTML in browser |
-| **View in macOS Preview (or default image viewer)** | \`mcp__dgmo__render_diagram(dgmo, format:"png")\` → get temp path → \`open <path>\` |
-| **View SVG in browser** | \`mcp__dgmo__render_diagram(dgmo, format:"svg")\` → write SVG to a temp \`.svg\` file → \`open <path>\` |
-| **Save as PNG** | \`mcp__dgmo__render_diagram(dgmo, format:"png")\` → returns temp path; offer to copy to their preferred location. Or CLI: \`dgmo file.dgmo -o out.png\` |
-| **Save as SVG** | \`mcp__dgmo__render_diagram(dgmo, format:"svg")\` returns SVG text — write it to the desired path. Or CLI: \`dgmo file.dgmo -o out.svg\` |
-| **Shareable URL** | \`mcp__dgmo__share_diagram(dgmo)\` or CLI: \`dgmo file.dgmo -o url --copy\` |
-
-**After creating a diagram, always present these options to the user** — don't just render silently and stop. A good response ends with something like: *"I've saved the file as \`diagram.dgmo\`. Want me to open it in the app, export it as a PNG, or generate a shareable link?"*
-
-## CLI Reference
-
-\`\`\`
-dgmo <input.dgmo> [options]
-cat input.dgmo | dgmo [options]
-\`\`\`
-
-Key options:
-- \`-o <file>\` — output file; format inferred from extension (\`.svg\` → SVG, else PNG)
-- \`-o url\` — output a shareable diagrammo.app URL
-- \`--theme <theme>\` — \`light\` (default), \`dark\`, \`transparent\`
-- \`--palette <name>\` — \`slate\` (default), \`atlas\`, \`blueprint\`, \`nord\`, \`tidewater\`, \`catppuccin\`, \`tokyo-night\`
-- \`--copy\` — copy the URL to clipboard (use with \`-o url\`)
-- \`--chart-types\` — list all supported chart types
-
-## Supported Chart Types
-
-| Type | Use case |
-|------|----------|
-| \`bar\` | Categorical comparisons |
-| \`line\` / \`multi-line\` / \`area\` | Trends over time |
-| \`pie\` / \`doughnut\` | Part-to-whole |
-| \`radar\` / \`polar-area\` | Multi-dimensional metrics |
-| \`bar-stacked\` | Multi-series categorical |
-| \`scatter\` | 2D data points or bubble chart |
-| \`sankey\` | Flow / allocation |
-| \`chord\` | Circular flow relationships |
-| \`function\` | Mathematical expressions |
-| \`heatmap\` | Matrix intensity |
-| \`funnel\` | Conversion pipeline |
-| \`slope\` | Change between two periods |
-| \`wordcloud\` | Term frequency |
-| \`arc\` | Network relationships |
-| \`timeline\` | Events, eras, date ranges |
-| \`venn\` | Set overlaps |
-| \`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) |
-| \`sitemap\` | Website / app navigation structure |
-| \`infra\` | Infrastructure traffic flow with rps computation |
-| \`gantt\` | Project scheduling with dependencies |
-| \`boxes-and-lines\` | General-purpose node-edge diagrams with groups and tags |
-
-## Key Syntax Patterns
-
-### Common to all diagrams
-
-\`\`\`
-sequence               // explicit type (optional — auto-detected)
-title: My Diagram
-palette: catppuccin    // override palette
-
-// This is a comment (only // syntax — not #)
-\`\`\`
-
-Inline colors on most elements: append the color name as the trailing token — e.g. \`North red 850\`, \`[Process] blue\`. To use a color word as a literal label, capitalize it (\`Red\` stays as the word Red).
-Named colors: \`red\`, \`orange\`, \`yellow\`, \`green\`, \`blue\`, \`purple\`, \`teal\`, \`cyan\`, \`gray\`, \`black\`, \`white\`.
-
-### sequence (most commonly used)
-
-\`\`\`
-chart: sequence
-title: Auth Flow
-
-// Participants auto-inferred, or declare explicitly:
-User is an actor
-DB is a database
-Cache is a cache
-
-User -Login-> API
-API -Find user-> DB
-DB -user record-> API
-
-if credentials valid
-  API -200 OK + token-> User
-else
-  API -401 Unauthorized-> User
-
-== Logout ==
-
-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: \`note on API: text\` or \`note: text\`
-- 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
-
-// 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
-\`\`\`
-
-## Tips
-
-- Default theme: \`light\`, default palette: \`slate\` — ask the user their preference before a final export.
-- 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.
-`;
-
-const CODEX_SKILL_FRONTMATTER = `---
-name: dgmo-diagramming
-description: Use when the user asks for a diagram, chart, sequence diagram, flowchart, ER diagram, org chart, kanban, sitemap, infra/architecture diagram, or any visual based on the DGMO diagram markup language. Provides syntax, MCP tool guidance, and rendering/sharing workflows.
----
-
-`;
-
-const CODEX_SKILL_CONTENT = `# DGMO Diagram Language
-
-Use dgmo tools to create, render, and share diagrams. dgmo is a text-based diagram markup language that renders to SVG/PNG.
-
-## MCP Tools — preferred order
-
-When the \`dgmo\` MCP server is configured, prefer tools in this order:
-1. \`open_in_app\` — opens the diagram in the Diagrammo desktop app (macOS). **Best UX** — chart + editor side-by-side, full editing.
-2. \`share_diagram\` — returns a \`https://online.diagrammo.app/...\` URL. Tell the user to open it; same chart + editor view in the browser. **Preferred fallback** when the desktop app is not available.
-3. \`render_diagram\` — renders to PNG or SVG and returns a file path. Use when the user wants an image artifact (export, embed, attach).
-4. \`generate_report\` — renders multiple diagrams into an HTML report with table of contents.
-5. \`preview_diagram\` — local HTML preview in the browser. Last resort — only when none of the above fit.
-6. \`list_chart_types\` / \`get_language_reference\` — discovery; call \`get_language_reference\` before generating an unfamiliar chart type.
-
-## 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
-\`\`\`
-sequence Auth Flow
-
-User -Login-> API
-API -Find user-> DB
-DB -user-> API
-  if valid
-    API -200 OK-> User
-  else
-    API -401-> User
-\`\`\`
-
-### Flowchart
-\`\`\`
-flowchart Process
-
-(Start) -> <Valid?>
-  -yes-> [Process] -> (Done)
-  -no-> /Get Input/ -> <Valid?>
-\`\`\`
-
-### Bar chart
-\`\`\`
-bar Revenue
-series USD
-
-North 850
-South 620
-East 1100
-\`\`\`
 
-### ER diagram
-\`\`\`
-er Schema
+// Claude Code skill source. Carries NO static chart-type table — it directs the
+// agent to query list_chart_types (MCP) / dgmo types (CLI) for the
+// authoritative, complete list.
+const readClaudeSkill = (): string =>
+  readPackagedFile('.claude', 'commands', 'dgmo.md');
 
-users
-  id int pk
-  email varchar
-
-posts
-  id int pk
-  user_id int fk
-
-users 1-writes-* posts
-\`\`\`
-
-### Org chart
-\`\`\`
-org
-
-CEO
-  VP Engineering
-    Team Lead A
-    Team Lead B
-  VP Marketing
-\`\`\`
-
-### Infra chart
-\`\`\`
-infra
-
-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 31 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, sitemap, infra
-
-## Common patterns
-
-- First line: chart type keyword (e.g. \`sequence\`, \`flowchart\`, \`bar\`), optionally followed by a title (\`bar Revenue\`)
-- \`// comment\` — only \`//\` comments (not \`#\`)
-- Trailing color name — inline colors on data series, tag values, kanban columns: \`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
-- Start the file with the chart type keyword 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
-`;
+// Codex skill source. Already includes the dgmo-diagramming frontmatter and the
+// gen-ai-core 45-type index.
+const readCodexSkill = (): string => readPackagedFile('SKILL.md');
 
 const CODEX_AGENTS_NOTE_MARKER = '<!-- dgmo-integration -->';
 const CODEX_AGENTS_NOTE = `${CODEX_AGENTS_NOTE_MARKER}
@@ -468,39 +67,25 @@ For architecture diagrams, sequence diagrams, flowcharts, and charts, use the \`
 
 function printHelp(): void {
   console.log(renderBanner());
-  console.log(`Usage: dgmo <input> [options]
-       cat input.dgmo | dgmo [options]
-       dgmo cat <file>          Display file with syntax highlighting
-       dgmo migrate <path>      Convert legacy "|" metadata to §1.4 grammar
-       dgmo map search <query>  Find the map place token (city or IATA code)
-
-Render a .dgmo file to PNG (default) or SVG.
-
-Options:
+  console.log(`Usage: dgmo <input> [options]          Render a .dgmo file to PNG (default) or SVG
+       cat input.dgmo | dgmo [options]  Render from stdin
+
+Commands:
+  dgmo share <input>       Print a shareable diagrammo.app URL (copies to clipboard)
+  dgmo types               List all supported chart types
+  dgmo install [target]    Set up AI assistants (auto-detects all if no target).
+                           Targets: claude-code, codex, claude-desktop,
+                           cursor, windsurf, copilot. --scope user|project
+  dgmo mcp                 Run the MCP server (invoked by AI client configs)
+  dgmo map-search <query>  Find the map place token (city or IATA code)
+
+Render options:
   -o <file>            Output file (default: <input>.png in cwd)
                        Format inferred from extension: .svg → SVG, else PNG
-                       Use -o url to output a shareable diagrammo.app URL
                        With stdin and no -o, PNG is written to stdout
   --theme <theme>      Theme: ${THEMES.join(', ')} (default: light)
   --palette <name>     Palette: ${PALETTES.join(', ')} (default: slate)
-  --copy               Copy URL to clipboard (only with -o url)
   --json               Output structured JSON to stdout
-  --chart-types        List all supported chart types
-  --install-claude-code-integration
-                       Full Claude Code setup: install the /dgmo skill and configure
-                       the dgmo MCP server — installs @diagrammo/dgmo-mcp if needed,
-                       then writes .mcp.json (project) or ~/.claude/settings.json (global)
-  --install-claude-skill  Install only the /dgmo skill to ~/.claude/commands/dgmo.md
-  --install-codex-integration
-                       Full Codex CLI setup: install the dgmo-diagramming skill at
-                       ~/.codex/skills/dgmo-diagramming/SKILL.md, configure the dgmo MCP
-                       server in .codex/config.toml (project) or ~/.codex/config.toml (global),
-                       and append a non-destructive note to AGENTS.md if one already exists.
-  --install-claude-desktop-integration
-                       Full Claude Desktop setup: install @diagrammo/dgmo-mcp if needed,
-                       then merge the dgmo MCP entry into Claude Desktop's config file
-                       (~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
-                       %APPDATA%/Claude/... on Windows, ~/.config/Claude/... on Linux)
   --help               Show this help
   --version            Show version`);
 }
@@ -519,15 +104,7 @@ function parseArgs(argv: string[]): {
   palette: string;
   help: boolean;
   version: boolean;
-  copy: boolean;
   json: boolean;
-  chartTypes: boolean;
-  cat: boolean;
-  noColor: boolean;
-  installClaudeSkill: boolean;
-  installClaudeCodeIntegration: boolean;
-  installCodexIntegration: boolean;
-  installClaudeDesktopIntegration: boolean;
 } {
   const result = {
     input: undefined as string | undefined,
@@ -536,15 +113,7 @@ function parseArgs(argv: string[]): {
     palette: 'slate',
     help: false,
     version: false,
-    copy: false,
     json: false,
-    chartTypes: false,
-    cat: false,
-    noColor: false,
-    installClaudeSkill: false,
-    installClaudeCodeIntegration: false,
-    installCodexIntegration: false,
-    installClaudeDesktopIntegration: false,
   };
 
   const args = argv.slice(2); // skip node + script
@@ -553,13 +122,7 @@ function parseArgs(argv: string[]): {
   while (i < args.length) {
     const arg = args[i];
 
-    if (arg === 'cat' && !result.cat && !result.input) {
-      result.cat = true;
-      i++;
-    } else if (arg === '--no-color') {
-      result.noColor = true;
-      i++;
-    } else if (arg === '--help' || arg === '-h') {
+    if (arg === '--help' || arg === '-h') {
       result.help = true;
       i++;
     } else if (arg === '--version' || arg === '-v') {
@@ -591,24 +154,6 @@ function parseArgs(argv: string[]): {
     } else if (arg === '--json') {
       result.json = true;
       i++;
-    } else if (arg === '--chart-types') {
-      result.chartTypes = true;
-      i++;
-    } else if (arg === '--install-claude-code-integration') {
-      result.installClaudeCodeIntegration = true;
-      i++;
-    } else if (arg === '--install-claude-skill') {
-      result.installClaudeSkill = true;
-      i++;
-    } else if (arg === '--install-codex-integration') {
-      result.installCodexIntegration = true;
-      i++;
-    } else if (arg === '--install-claude-desktop-integration') {
-      result.installClaudeDesktopIntegration = true;
-      i++;
-    } else if (arg === '--copy') {
-      result.copy = true;
-      i++;
     } else if (!result.input) {
       result.input = arg;
       i++;
@@ -621,10 +166,7 @@ function parseArgs(argv: string[]): {
   return result;
 }
 
-function inferFormat(outputPath: string | undefined): 'svg' | 'png' | 'url' {
-  if (outputPath === 'url') {
-    return 'url';
-  }
+function inferFormat(outputPath: string | undefined): 'svg' | 'png' {
   if (outputPath && extname(outputPath).toLowerCase() === '.svg') {
     return 'svg';
   }
@@ -688,193 +230,33 @@ function noInput(): never {
   process.exit(0);
 }
 
-interface MigrateCommandOpts {
-  path: string | undefined;
-  dryRun: boolean;
-  apply: boolean;
-  diff: boolean;
-  noBackup: boolean;
-  embedded: boolean;
-  help: boolean;
-}
-
-function parseMigrateArgs(args: string[]): MigrateCommandOpts {
-  const opts: MigrateCommandOpts = {
-    path: undefined,
-    dryRun: true,
-    apply: false,
-    diff: false,
-    noBackup: false,
-    embedded: false,
-    help: false,
-  };
-  let i = 0;
-  while (i < args.length) {
-    const arg = args[i]!;
-    if (arg === '--help' || arg === '-h') {
-      opts.help = true;
-      i++;
-    } else if (arg === '--dry-run') {
-      opts.dryRun = true;
-      opts.apply = false;
-      i++;
-    } else if (arg === '--apply') {
-      opts.apply = true;
-      opts.dryRun = false;
-      i++;
-    } else if (arg === '--diff') {
-      opts.diff = true;
-      i++;
-    } else if (arg === '--backup') {
-      opts.noBackup = false;
-      i++;
-    } else if (arg === '--no-backup') {
-      opts.noBackup = true;
-      i++;
-    } else if (arg === '--embedded') {
-      opts.embedded = true;
-      i++;
-    } else if (!opts.path) {
-      opts.path = arg;
-      i++;
+// Best-effort clipboard copy across platforms. Returns true on success.
+function copyToClipboard(text: string): boolean {
+  try {
+    if (process.platform === 'darwin') {
+      execSync('pbcopy', { input: text });
+    } else if (process.platform === 'win32') {
+      execSync('clip', { input: text });
     } else {
-      console.error(`Error: Unexpected argument "${arg}"`);
-      process.exit(1);
+      execSync('xclip -selection clipboard', { input: text });
     }
+    return true;
+  } catch {
+    return false;
   }
-  return opts;
-}
-
-function printMigrateHelp(): void {
-  console.log(`Usage: dgmo migrate <path> [options]
-
-Convert legacy "|" metadata syntax to the unified §1.4 same-line form
-("Foo k: v, k: v" — no pipe). Handles bare-positional promotions:
-  - gantt   "| 80%"        → "progress: 80"
-  - journey "| 4 Delighted" → "score: 4, emotion: Delighted"
-  - pyramid "| description" → "description: ..."
-  - ring    "| description" → "description: ..."
-
-Wireframe option braces "{A | B}", arrow-label "|" characters (§1.10),
-and quoted-string content are preserved.
-
-Options:
-  --dry-run        Print proposed changes; do not write (default)
-  --apply          Write migrated files to disk
-  --diff           Print per-file unified-style diffs
-  --backup         Write "<file>.bak" before applying (default with --apply)
-  --no-backup      Skip writing .bak sidecars
-  --embedded       Walk .md/.mdx files; migrate fenced \`\`\`dgmo blocks
-                   atomically per file (single parse-error block aborts file)
-  -h, --help       Show this help`);
 }
 
-async function runMigrateCommand(args: string[]): Promise<void> {
-  const opts = parseMigrateArgs(args);
-
-  if (opts.help) {
-    printMigrateHelp();
-    return;
-  }
-
-  if (!opts.path) {
-    console.error('Error: dgmo migrate requires a path argument');
-    console.error('Try: dgmo migrate --help');
-    process.exit(1);
-  }
-
-  const resolvedPath = resolve(opts.path);
-  if (!existsSync(resolvedPath)) {
-    console.error(`Error: Path not found: ${resolvedPath}`);
-    process.exit(1);
-  }
-
-  if (opts.embedded) {
-    const files = collectEmbeddedFiles(resolvedPath);
-    if (files.length === 0) {
-      console.error('No .md / .mdx files found at the given path.');
-      process.exit(1);
-    }
-    let migrated = 0;
-    let skipped = 0;
-    let unchanged = 0;
-    for (const file of files) {
-      const result = migrateEmbedded(file, {
-        dryRun: opts.dryRun,
-        noBackup: opts.noBackup,
-      });
-      if (result.skipped) {
-        console.log(`SKIP  ${file}  — ${result.skipReason}`);
-        skipped++;
-        continue;
-      }
-      if (!result.changed) {
-        unchanged++;
-        continue;
-      }
-      migrated++;
-      const verb = result.written ? 'MIGRATE' : 'DRY-RUN';
-      console.log(
-        `${verb}  ${file}  — ${result.changedBlocks}/${result.blockCount} blocks changed`
-      );
-      if (opts.diff) {
-        console.log(formatLineDiff(file, result.original, result.migrated));
-      }
-    }
-    console.log('');
-    console.log(
-      `Done. ${migrated} file(s) ${opts.dryRun ? 'would migrate' : 'migrated'}; ${unchanged} unchanged; ${skipped} skipped.`
-    );
-    return;
-  }
-
-  const files = collectDgmoFiles(resolvedPath);
-  if (files.length === 0) {
-    console.error('No .dgmo files found at the given path.');
-    process.exit(1);
-  }
-  let migrated = 0;
-  let unchanged = 0;
-  for (const file of files) {
-    const result = migrateFile(file, {
-      dryRun: opts.dryRun,
-      noBackup: opts.noBackup,
-    });
-    if (!result.changed) {
-      unchanged++;
-      continue;
-    }
-    migrated++;
-    const verb = result.written ? 'MIGRATE' : 'DRY-RUN';
-    console.log(
-      `${verb}  ${file}  — ${result.changedLines.length} line(s) changed`
-    );
-    if (opts.diff) {
-      console.log(formatLineDiff(file, result.original, result.migrated));
-    }
-  }
-  console.log('');
-  console.log(
-    `Done. ${migrated} file(s) ${opts.dryRun ? 'would migrate' : 'migrated'}; ${unchanged} unchanged.`
-  );
-  if (opts.dryRun && migrated > 0) {
-    console.log('Re-run with --apply to write changes.');
-  }
-}
-
-// `dgmo map search <query>` — discover the exact place token the map resolver
+// `dgmo map-search <query>` — discover the exact place token the map resolver
 // expects (city name or bundled IATA airport code), so authors never guess
 // (e.g. "New York" → `New York City`; "kennedy" → `JFK`). Searches cities +
 // the bundled airport set; `--json` for machine output, `--limit N` to widen.
-async function runMapCommand(args: string[]): Promise<void> {
-  const sub = args[0];
+async function runMapSearchCommand(args: string[]): Promise<void> {
   const json = args.includes('--json');
   const limFlag = args.indexOf('--limit');
   const limit =
     limFlag >= 0 ? Math.max(1, Number(args[limFlag + 1]) || 20) : 20;
   // The query is the positional args (allow unquoted multi-word: `... New York`).
   const query = args
-    .slice(1)
     .filter(
       (a, i, arr) =>
         a !== '--json' && a !== '--limit' && arr[i - 1] !== '--limit'
@@ -882,18 +264,18 @@ async function runMapCommand(args: string[]): Promise<void> {
     .join(' ')
     .trim();
 
-  if (sub !== 'search' || !query) {
-    console.log('Usage: dgmo map search <query> [--json] [--limit N]');
+  if (!query) {
+    console.log('Usage: dgmo map-search <query> [--json] [--limit N]');
     console.log(
       '  Find the place token the map resolver expects (city or IATA airport code).'
     );
     console.log('  Examples:');
     console.log(
-      '    dgmo map search "new york"     # → New York City (+ JFK/LGA/EWR airports)'
+      '    dgmo map-search "new york"     # → New York City (+ JFK/LGA/EWR airports)'
     );
-    console.log('    dgmo map search kennedy        # → JFK by airport name');
-    console.log('    dgmo map search heathrow --json');
-    if (sub === 'search' && !query) process.exitCode = 1;
+    console.log('    dgmo map-search kennedy        # → JFK by airport name');
+    console.log('    dgmo map-search heathrow --json');
+    process.exitCode = 1;
     return;
   }
 
@@ -922,537 +304,519 @@ async function runMapCommand(args: string[]): Promise<void> {
   }
 }
 
-async function main(): Promise<void> {
-  // Subcommand dispatch — `dgmo migrate` is parsed independently from
-  // the rendering flags so its surface doesn't pollute `parseArgs`.
-  if (process.argv[2] === 'migrate') {
-    await runMigrateCommand(process.argv.slice(3));
-    return;
+// `dgmo types [--json]` — list every supported chart type. Was the
+// `--chart-types` render flag; promoted to a subcommand since it's a
+// query, not a rendering option.
+function runTypesCommand(args: string[]): void {
+  const json = args.includes('--json');
+  const types = getAllChartTypes();
+  if (json) {
+    const chartTypes = types.map((id) => ({
+      id,
+      description: CHART_TYPE_DESCRIPTIONS[id] ?? id,
+    }));
+    process.stdout.write(JSON.stringify({ chartTypes }, null, 2) + '\n');
+  } else {
+    for (const id of types) {
+      const desc = CHART_TYPE_DESCRIPTIONS[id];
+      console.log(desc ? `${id} — ${desc}` : id);
+    }
   }
+}
 
-  if (process.argv[2] === 'map') {
-    await runMapCommand(process.argv.slice(3));
-    return;
+// `dgmo share <input> [--no-copy] [--json]` — encode the diagram into a
+// shareable diagrammo.app URL. Replaces the old `-o url [--copy]` pair: the
+// URL is printed to stdout (pipeable) and copied to the clipboard by default
+// unless --no-copy is given.
+async function runShareCommand(args: string[]): Promise<void> {
+  const json = args.includes('--json');
+  const noCopy = args.includes('--no-copy');
+  const inputArg = args.find((a) => a !== '-' && !a.startsWith('-'));
+
+  let content: string;
+  if (inputArg) {
+    try {
+      content = readFileSync(resolve(inputArg), 'utf-8');
+    } catch {
+      console.error(`Error: Cannot read file "${resolve(inputArg)}"`);
+      process.exit(1);
+    }
+  } else if (!process.stdin.isTTY) {
+    try {
+      content = readFileSync(0, 'utf-8');
+    } catch {
+      console.error('Error: No input provided to dgmo share');
+      console.error('Usage: dgmo share <input> [--no-copy] [--json]');
+      process.exit(1);
+    }
+  } else {
+    console.error('Error: dgmo share requires an input file or piped stdin');
+    console.error('Usage: dgmo share <input> [--no-copy] [--json]');
+    process.exit(1);
   }
 
-  const opts = parseArgs(process.argv);
+  // eslint-disable-next-line no-control-regex
+  content = content.replace(/\x1b\[[0-9;]*m/g, '');
 
-  if (opts.help) {
-    printHelp();
-    return;
+  const chartType = parseDgmoChartType(content);
+  // PERT diagrams may contain `start-date now`; resolve to today before
+  // encoding so the share-link captures authoring intent (spec D9).
+  const sourceForUrl =
+    chartType === 'pert' ? normalizePertSourceForShare(content) : content;
+  const result = encodeDiagramUrl(sourceForUrl);
+
+  if (result.error) {
+    const msg = `Error: Diagram too large for URL sharing (${result.compressedSize} bytes, limit ${result.limit} bytes)`;
+    if (json) {
+      process.stdout.write(
+        JSON.stringify({ success: false, error: msg }, null, 2) + '\n'
+      );
+    } else {
+      console.error(msg);
+    }
+    process.exit(1);
   }
 
-  if (opts.version) {
-    printVersion();
-    return;
+  if (!noCopy) {
+    console.error(
+      copyToClipboard(result.url)
+        ? 'URL copied to clipboard'
+        : 'Warning: Could not copy to clipboard'
+    );
   }
 
-  if (opts.chartTypes) {
-    const types = getAllChartTypes();
-    if (opts.json) {
-      const chartTypes = types.map((id) => ({
-        id,
-        description: CHART_TYPE_DESCRIPTIONS[id] ?? id,
-      }));
-      process.stdout.write(JSON.stringify({ chartTypes }, null, 2) + '\n');
-    } else {
-      for (const id of types) {
-        const desc = CHART_TYPE_DESCRIPTIONS[id];
-        console.log(desc ? `${id} — ${desc}` : id);
-      }
-    }
-    return;
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        { success: true, url: result.url, ...(chartType ? { chartType } : {}) },
+        null,
+        2
+      ) + '\n'
+    );
+  } else {
+    process.stdout.write(result.url + '\n');
   }
+}
 
-  if (opts.cat) {
-    const useColor =
-      !opts.noColor &&
-      !process.env['NO_COLOR'] &&
-      process.stdout.isTTY === true;
+// Single source of truth for how every AI client launches the MCP server: the
+// `dgmo` binary the user already has, plus the `mcp` subcommand. No generated
+// config ever references a separate `dgmo-mcp` command — the user installs one
+// binary and that's it. (The server itself still lives in the
+// @diagrammo/dgmo-mcp package, which depends on this library; `dgmo mcp` locates
+// and execs it, so there's no dependency cycle and no extra deps bundled here.)
+const MCP_LAUNCH = { command: 'dgmo', args: ['mcp'] } as const;
+
+const INSTALL_TARGETS = [
+  'claude-code',
+  'codex',
+  'claude-desktop',
+  'cursor',
+  'windsurf',
+  'copilot',
+] as const;
+type InstallTarget = (typeof INSTALL_TARGETS)[number];
+
+interface InstallOpts {
+  scope: 'user' | 'project';
+  dryRun: boolean;
+}
 
-    let catContent: string;
-    if (opts.input && opts.input !== '-') {
-      const inputPath = resolve(opts.input);
-      try {
-        catContent = readFileSync(inputPath, 'utf-8');
-      } catch {
-        console.error(`Error: Cannot read file "${inputPath}"`);
-        process.exit(1);
-      }
-    } else {
-      // Read from stdin
-      try {
-        catContent = readFileSync(0, 'utf-8');
-      } catch {
-        console.error('Error: No input file specified');
-        console.error('Usage: dgmo cat <file>');
-        process.exit(1);
-      }
-    }
+// `dgmo mcp` — run the MCP server. This is what AI client configs invoke. It
+// execs the installed `dgmo-mcp` binary if present, otherwise fetches and runs
+// it on demand via npx so a config pointing at `dgmo mcp` works even before the
+// server package has been installed. stdio is inherited so the stdio MCP
+// transport is fully transparent.
+function runMcpCommand(args: string[]): never {
+  const onWin = process.platform === 'win32';
+  const run = (cmd: string, cmdArgs: string[]) =>
+    spawnSync(cmd, cmdArgs, { stdio: 'inherit', shell: onWin });
+  // npx path is pinned to @latest so the on-demand server is never stale.
+  const npx = () => run('npx', ['-y', '@diagrammo/dgmo-mcp@latest', ...args]);
+  // Default: prefer the installed binary — fast, works offline, and
+  // `dgmo install` keeps it on @latest. Set DGMO_MCP_LATEST=1 to always fetch
+  // the newest server via npx instead (needs network; adds cold-start).
+  const res =
+    process.env['DGMO_MCP_LATEST'] === '1'
+      ? npx()
+      : commandExists('dgmo-mcp')
+        ? run('dgmo-mcp', args)
+        : npx();
+  if (res.error) {
+    console.error(
+      'Could not launch the dgmo MCP server. Install it with: npm install -g @diagrammo/dgmo-mcp'
+    );
+    process.exit(1);
+  }
+  process.exit(res.status ?? 0);
+}
 
-    const { highlightDgmo, renderAnsi } =
-      await import('./editor/highlight-api');
-    const tokens = highlightDgmo(catContent);
-    process.stdout.write(renderAnsi(tokens, useColor));
-    return;
+// Cross-platform "is this command on PATH?" check.
+function commandExists(cmd: string): boolean {
+  try {
+    const probe =
+      process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+    execSync(probe, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
   }
+}
 
-  if (
-    opts.installClaudeCodeIntegration ||
-    opts.installClaudeSkill ||
-    opts.installCodexIntegration ||
-    opts.installClaudeDesktopIntegration
-  ) {
-    console.log(renderBanner());
+// Claude Desktop config path for the current platform. macOS/Windows use the
+// documented locations; Linux follows the XDG convention community builds use.
+function claudeDesktopConfigPath(): string {
+  const os = platform();
+  if (os === 'darwin') {
+    return join(
+      homedir(),
+      'Library',
+      'Application Support',
+      'Claude',
+      'claude_desktop_config.json'
+    );
+  }
+  if (os === 'win32') {
+    const appData =
+      process.env['APPDATA'] ?? join(homedir(), 'AppData', 'Roaming');
+    return join(appData, 'Claude', 'claude_desktop_config.json');
   }
+  return join(homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+}
 
-  if (opts.installClaudeCodeIntegration) {
-    const claudeDir = join(homedir(), '.claude');
-    if (!existsSync(claudeDir)) {
-      console.error('~/.claude directory not found.');
-      console.error('Install Claude Code first: https://claude.ai/code');
-      process.exit(1);
-    }
+// Best-effort, NON-fatal pre-install of the MCP server so the first tool call
+// has no cold-start. Not required for correctness — `dgmo mcp` falls back to
+// npx — so any failure is a note, not an error. Memoized: in auto mode we set
+// up several surfaces in one run and only need to check once.
+// True when this CLI is running from a Homebrew install (its files live under
+// a Cellar prefix). Homebrew owns the MCP server in that case.
+function isHomebrewManaged(): boolean {
+  return PKG_ROOT.includes('/Cellar/') || PKG_ROOT.includes('/homebrew/');
+}
 
-    function ask(prompt: string): Promise<string> {
-      return new Promise((resolve) => {
-        const rl = createInterface({
-          input: process.stdin,
-          output: process.stdout,
-        });
-        rl.question(prompt, (answer) => {
-          rl.close();
-          resolve(answer);
-        });
-      });
-    }
+let mcpEnsured = false;
+function ensureDgmoMcp(opts: InstallOpts): void {
+  if (mcpEnsured) return;
+  mcpEnsured = true;
+  // Homebrew vendors and upgrades the MCP server alongside the CLI (the formula
+  // installs `dgmo-mcp` into the same prefix). Don't npm-install a second global
+  // copy that would shadow brew's — `brew upgrade dgmo` keeps it current.
+  if (isHomebrewManaged()) {
+    console.log(
+      commandExists('dgmo-mcp')
+        ? '✓ MCP server managed by Homebrew (upgrades with `brew upgrade dgmo`)'
+        : '  MCP server not found — it will be fetched on first use via npx.'
+    );
+    return;
+  }
+  if (opts.dryRun) {
+    console.log('  [dry-run] would install/upgrade @diagrammo/dgmo-mcp@latest');
+    return;
+  }
+  // Always pull @latest, not just install-if-absent: the MCP tools live in a
+  // separately-versioned package, so re-running `dgmo install` (e.g. after a
+  // `dgmo` upgrade) is what refreshes the server. Non-fatal — `dgmo mcp` falls
+  // back to `npx …@latest`.
+  try {
+    const verb = commandExists('dgmo-mcp') ? 'Updating' : 'Installing';
+    console.log(`${verb} the MCP server (@diagrammo/dgmo-mcp@latest)…`);
+    execSync('npm install -g @diagrammo/dgmo-mcp@latest', { stdio: 'inherit' });
+    console.log('✓ MCP server up to date');
+  } catch {
+    console.log(
+      '  Could not install now — it will be fetched on first use via npx.'
+    );
+  }
+}
 
-    // --- Step 1: Install skill ---
-    const commandsDir = join(claudeDir, 'commands');
-    const skillPath = join(commandsDir, 'dgmo.md');
-    const skillExists = existsSync(skillPath);
-    let installSkill = true;
-    if (skillExists) {
-      const ans = await ask(
-        '~/.claude/commands/dgmo.md already exists. Overwrite? [y/N] '
-      );
-      installSkill = ans.toLowerCase() === 'y' || ans.toLowerCase() === 'yes';
-    }
-    if (installSkill) {
-      if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
-      writeFileSync(skillPath, CLAUDE_SKILL_CONTENT, 'utf-8');
-      console.log('✓ Skill installed: ~/.claude/commands/dgmo.md');
-    } else {
-      console.log('  Skipped skill install.');
-    }
+// Write helper that honors --dry-run and creates parent dirs.
+function writeOut(
+  opts: InstallOpts,
+  path: string,
+  content: string,
+  label: string
+): void {
+  if (opts.dryRun) {
+    console.log(`  [dry-run] would write ${label}`);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, 'utf-8');
+  console.log(`✓ ${label}`);
+}
 
-    // --- Step 2: Check / install dgmo-mcp binary ---
-    let dgmoMcpInstalled = false;
-    try {
-      execSync('which dgmo-mcp', { stdio: 'pipe' });
-      dgmoMcpInstalled = true;
-    } catch {
-      /* not found */
-    }
-    if (!dgmoMcpInstalled) {
-      const ans = await ask(
-        '\ndgmo-mcp not found. Install @diagrammo/dgmo-mcp globally now? [Y/n] '
-      );
-      const yes =
-        ans === '' || ans.toLowerCase() === 'y' || ans.toLowerCase() === 'yes';
-      if (yes) {
-        console.log('Installing @diagrammo/dgmo-mcp...');
-        execSync('npm install -g @diagrammo/dgmo-mcp', { stdio: 'inherit' });
-        console.log('✓ @diagrammo/dgmo-mcp installed');
-      } else {
-        console.log(
-          '  Skipped. Install later with: npm install -g @diagrammo/dgmo-mcp'
+// Merge `{ mcpServers: { dgmo: dgmo mcp } }` into a JSON config (Claude Code /
+// Claude Desktop style), preserving any other entries.
+function upsertJsonMcp(opts: InstallOpts, path: string): void {
+  let cfg: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    const raw = readFileSync(path, 'utf-8');
+    if (raw.trim().length > 0) {
+      try {
+        cfg = JSON.parse(raw);
+      } catch {
+        console.error(
+          `Error: ${path} is not valid JSON — fix it and re-run (skipping it for now).`
         );
+        return;
       }
-    } else {
-      console.log('✓ dgmo-mcp already installed');
     }
+  }
+  const servers =
+    (cfg['mcpServers'] as Record<string, unknown> | undefined) ?? {};
+  servers['dgmo'] = MCP_LAUNCH;
+  cfg['mcpServers'] = servers;
+  writeOut(opts, path, JSON.stringify(cfg, null, 2) + '\n', `MCP server → ${path}`);
+}
 
-    // --- Step 3: Configure MCP server ---
-    console.log('\nWhere should the MCP server be configured?');
-    console.log('  1) This project only — write .mcp.json here [default]');
-    console.log(
-      '  2) Globally — add to ~/.claude/settings.json (works in all projects)'
-    );
-    const scopeAns = await ask('\nChoice [1]: ');
-    const useGlobal = scopeAns.trim() === '2';
-    const mcpEntry = { command: 'dgmo-mcp' };
-
-    if (useGlobal) {
-      const settingsPath = join(claudeDir, 'settings.json');
-      let settings: Record<string, unknown> = {};
-      if (existsSync(settingsPath)) {
-        try {
-          settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        } catch {
-          /* use empty */
-        }
-      }
-      const mcpServers =
-        (settings['mcpServers'] as Record<string, unknown> | undefined) ?? {};
-      mcpServers['dgmo'] = mcpEntry;
-      settings['mcpServers'] = mcpServers;
-      writeFileSync(
-        settingsPath,
-        JSON.stringify(settings, null, 2) + '\n',
-        'utf-8'
-      );
-      console.log('✓ MCP server added to ~/.claude/settings.json');
-    } else {
-      const mcpPath = join(process.cwd(), '.mcp.json');
-      let mcp: Record<string, unknown> = {};
-      if (existsSync(mcpPath)) {
-        try {
-          mcp = JSON.parse(readFileSync(mcpPath, 'utf-8'));
-        } catch {
-          /* use empty */
-        }
-      }
-      const mcpServers =
-        (mcp['mcpServers'] as Record<string, unknown> | undefined) ?? {};
-      mcpServers['dgmo'] = mcpEntry;
-      mcp['mcpServers'] = mcpServers;
-      writeFileSync(mcpPath, JSON.stringify(mcp, null, 2) + '\n', 'utf-8');
-      console.log(
-        `✓ MCP server configured: ${join(process.cwd(), '.mcp.json')}`
-      );
-    }
+// Which AI surfaces are present on this machine? Drives zero-prompt auto setup.
+function detectSurfaces(): InstallTarget[] {
+  const found: InstallTarget[] = [];
+  if (existsSync(join(homedir(), '.claude'))) found.push('claude-code');
+  if (existsSync(join(homedir(), '.codex')) || commandExists('codex'))
+    found.push('codex');
+  if (existsSync(dirname(claudeDesktopConfigPath())))
+    found.push('claude-desktop');
+  if (existsSync(join(homedir(), '.cursor'))) found.push('cursor');
+  if (
+    existsSync(join(homedir(), '.windsurf')) ||
+    existsSync(join(homedir(), '.codeium'))
+  )
+    found.push('windsurf');
+  // Copilot is project-scoped: only when the current repo has a .github dir.
+  if (existsSync(join(process.cwd(), '.github'))) found.push('copilot');
+  return found;
+}
 
-    console.log('\nRestart Claude Code to activate the MCP server.');
-    console.log('Then type /dgmo in any session to start creating diagrams.');
-    return;
+async function runOneInstall(
+  target: InstallTarget,
+  opts: InstallOpts
+): Promise<void> {
+  switch (target) {
+    case 'claude-code':
+      return installClaudeCode(opts);
+    case 'codex':
+      return installCodex(opts);
+    case 'claude-desktop':
+      return installClaudeDesktop(opts);
+    case 'cursor':
+      return installCursor(opts);
+    case 'windsurf':
+      return installWindsurf(opts);
+    case 'copilot':
+      return installCopilot(opts);
   }
+}
 
-  if (opts.installClaudeSkill) {
-    const claudeDir = join(homedir(), '.claude');
-    if (!existsSync(claudeDir)) {
-      console.error('~/.claude directory not found.');
-      console.error('Install Claude Code first: https://claude.ai/code');
-      process.exit(1);
-    }
-    const commandsDir = join(claudeDir, 'commands');
-    const destPath = join(commandsDir, 'dgmo.md');
-    const alreadyExists = existsSync(destPath);
-    const prompt = alreadyExists
-      ? `~/.claude/commands/dgmo.md already exists. Overwrite? [y/N] `
-      : `Install dgmo Claude Code skill to ~/.claude/commands/dgmo.md? [Y/n] `;
-    await new Promise<void>((done) => {
-      const rl = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-      });
-      rl.question(prompt, (answer) => {
-        rl.close();
-        const yes = alreadyExists
-          ? answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes'
-          : answer === '' ||
-            answer.toLowerCase() === 'y' ||
-            answer.toLowerCase() === 'yes';
-        if (!yes) {
-          console.error('Aborted.');
-          process.exit(0);
-        }
-        done();
-      });
-    });
-    if (!existsSync(commandsDir)) {
-      mkdirSync(commandsDir, { recursive: true });
-    }
-    writeFileSync(destPath, CLAUDE_SKILL_CONTENT, 'utf-8');
-    console.log(`Installed: ${destPath}`);
-    console.log('Use /dgmo in Claude Code to activate the skill.');
+function printInstallHelp(): void {
+  console.log(`Usage: dgmo install [target] [--scope user|project] [--dry-run]
+
+With no target, auto-detects every installed AI assistant and sets up each one
+(no prompts). The only binary you ever install is \`dgmo\` — it provides the MCP
+server via \`dgmo mcp\`.
+
+Targets:   ${INSTALL_TARGETS.join(', ')}
+--scope    user = configure globally for all projects (default)
+           project = write config into the current directory
+--dry-run  print what would change without writing anything`);
+}
+
+// `dgmo install [target] [--scope ...] [--dry-run]`. No target → auto-detect.
+async function runInstallCommand(args: string[]): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    printInstallHelp();
     return;
   }
+  const scopeIdx = args.indexOf('--scope');
+  const scope: 'user' | 'project' =
+    scopeIdx >= 0 && args[scopeIdx + 1] === 'project' ? 'project' : 'user';
+  const opts: InstallOpts = { scope, dryRun: args.includes('--dry-run') };
 
-  if (opts.installCodexIntegration) {
-    // Validate Codex CLI is installed
-    try {
-      execSync('which codex', { stdio: 'pipe' });
-    } catch {
-      console.error(
-        'codex not found. Install Codex CLI first: https://openai.com/codex'
-      );
-      process.exit(1);
-    }
+  const positional = args.filter(
+    (a, i) => !a.startsWith('-') && args[i - 1] !== '--scope'
+  );
+  const target = positional[0] as InstallTarget | undefined;
 
-    const ask = (prompt: string): Promise<string> =>
-      new Promise((resolve) => {
-        const rl = createInterface({
-          input: process.stdin,
-          output: process.stdout,
-        });
-        rl.question(prompt, (answer) => {
-          rl.close();
-          resolve(answer);
-        });
-      });
-
-    // Check / install dgmo-mcp binary
-    let dgmoMcpInstalled = false;
-    try {
-      execSync('which dgmo-mcp', { stdio: 'pipe' });
-      dgmoMcpInstalled = true;
-    } catch {
-      /* not found */
-    }
-    if (!dgmoMcpInstalled) {
-      const ans = await ask(
-        '\ndgmo-mcp not found. Install @diagrammo/dgmo-mcp globally now? [Y/n] '
-      );
-      const yes =
-        ans === '' || ans.toLowerCase() === 'y' || ans.toLowerCase() === 'yes';
-      if (yes) {
-        console.log('Installing @diagrammo/dgmo-mcp...');
-        try {
-          execSync('npm install -g @diagrammo/dgmo-mcp', { stdio: 'inherit' });
-          console.log('✓ @diagrammo/dgmo-mcp installed');
-        } catch {
-          console.error('Error: Failed to install @diagrammo/dgmo-mcp.');
-          console.error('Try manually: npm install -g @diagrammo/dgmo-mcp');
-        }
-      } else {
-        console.log(
-          '  Skipped. Install later with: npm install -g @diagrammo/dgmo-mcp'
-        );
-      }
-    } else {
-      console.log('✓ dgmo-mcp already installed');
+  console.log(renderBanner());
+
+  if (target) {
+    if (!INSTALL_TARGETS.includes(target)) {
+      console.error(`Error: Unknown install target "${target}".`);
+      console.error(`Valid targets: ${INSTALL_TARGETS.join(', ')}`);
+      process.exit(1);
     }
+    await runOneInstall(target, opts);
+    console.log('\nRestart the assistant to activate the dgmo tools.');
+    console.log('(Re-run `dgmo install` after upgrading dgmo to refresh.)');
+    return;
+  }
 
-    // Configure MCP server
-    console.log('\nWhere should the MCP server be configured?');
-    console.log(
-      '  1) This project only — write .codex/config.toml here [default]'
-    );
+  const detected = detectSurfaces();
+  if (detected.length === 0) {
     console.log(
-      '  2) Globally — add to ~/.codex/config.toml (works in all projects)'
+      'No AI assistants detected (looked for Claude Code, Codex, Claude Desktop, Cursor, Windsurf, a .github dir).'
     );
-    const scopeAns = await ask('\nChoice [1]: ');
-    if (
-      scopeAns.trim() !== '' &&
-      scopeAns.trim() !== '1' &&
-      scopeAns.trim() !== '2'
-    ) {
-      console.log(
-        `  Unrecognized input "${scopeAns.trim()}", defaulting to option 1.`
-      );
-    }
-    const useGlobal = scopeAns.trim() === '2';
-    const tomlEntry = '[mcp_servers.dgmo]\ncommand = "dgmo-mcp"\n';
-
-    if (useGlobal) {
-      const configPath = join(homedir(), '.codex', 'config.toml');
-      mkdirSync(join(homedir(), '.codex'), { recursive: true });
-      const existing = existsSync(configPath)
-        ? readFileSync(configPath, 'utf-8')
-        : '';
-      if (existing.includes('[mcp_servers.dgmo]')) {
-        console.log('✓ MCP server already configured in ~/.codex/config.toml');
-      } else {
-        const separator = existing.length > 0 ? '\n' : '';
-        writeFileSync(configPath, existing + separator + tomlEntry, 'utf-8');
-        console.log('✓ MCP server added to ~/.codex/config.toml');
-      }
-    } else {
-      const codexDir = join(process.cwd(), '.codex');
-      const configPath = join(codexDir, 'config.toml');
-      mkdirSync(codexDir, { recursive: true });
-      const existing = existsSync(configPath)
-        ? readFileSync(configPath, 'utf-8')
-        : '';
-      if (existing.includes('[mcp_servers.dgmo]')) {
-        console.log(`✓ MCP server already configured in .codex/config.toml`);
-      } else {
-        const separator = existing.length > 0 ? '\n' : '';
-        writeFileSync(configPath, existing + separator + tomlEntry, 'utf-8');
-        console.log(`✓ MCP server configured: ${configPath}`);
-      }
-    }
-
-    // Install the dgmo-diagramming skill at ~/.codex/skills/dgmo-diagramming/SKILL.md
-    const skillDir = join(homedir(), '.codex', 'skills', 'dgmo-diagramming');
-    const skillPath = join(skillDir, 'SKILL.md');
-    const skillBody = CODEX_SKILL_FRONTMATTER + CODEX_SKILL_CONTENT;
-    if (existsSync(skillPath)) {
-      const existingSkill = readFileSync(skillPath, 'utf-8');
-      if (existingSkill === skillBody) {
-        console.log('✓ dgmo-diagramming skill already up to date');
-      } else {
-        const ans = await ask(
-          '\n~/.codex/skills/dgmo-diagramming/SKILL.md exists. Overwrite? [Y/n] '
-        );
-        const yes =
-          ans === '' ||
-          ans.toLowerCase() === 'y' ||
-          ans.toLowerCase() === 'yes';
-        if (yes) {
-          writeFileSync(skillPath, skillBody, 'utf-8');
-          console.log(`✓ Skill updated: ${skillPath}`);
-        } else {
-          console.log('  Skipped skill update.');
-        }
-      }
-    } else {
-      mkdirSync(skillDir, { recursive: true });
-      writeFileSync(skillPath, skillBody, 'utf-8');
-      console.log(`✓ Skill installed: ${skillPath}`);
-    }
-
-    // Non-destructive AGENTS.md handling: append a marked note only if AGENTS.md
-    // already exists and doesn't already contain the marker. Never create it.
-    const agentsPath = join(process.cwd(), 'AGENTS.md');
-    if (existsSync(agentsPath)) {
-      const existingAgents = readFileSync(agentsPath, 'utf-8');
-      if (existingAgents.includes(CODEX_AGENTS_NOTE_MARKER)) {
-        console.log('✓ AGENTS.md already mentions dgmo');
-      } else {
-        const separator = existingAgents.endsWith('\n') ? '\n' : '\n\n';
-        writeFileSync(
-          agentsPath,
-          existingAgents + separator + CODEX_AGENTS_NOTE,
-          'utf-8'
-        );
-        console.log(`✓ Appended dgmo note to: ${agentsPath}`);
-      }
-    } else {
-      console.log(
-        '  No AGENTS.md found in cwd — skipped (the skill is enough).'
-      );
-    }
-
-    console.log('\nRestart Codex to activate the skill and MCP server.');
+    console.log('Install one and re-run `dgmo install`, or name a target:');
+    console.log(`  dgmo install <${INSTALL_TARGETS.join('|')}>`);
     return;
   }
+  console.log(`Detected: ${detected.join(', ')} — setting up each.\n`);
+  for (const t of detected) {
+    console.log(`── ${t} ──`);
+    await runOneInstall(t, opts);
+    console.log('');
+  }
+  console.log('Done. Restart your AI assistant(s) to activate the dgmo tools.');
+  console.log('(Re-run `dgmo install` after upgrading dgmo to refresh.)');
+}
 
-  if (opts.installClaudeDesktopIntegration) {
-    const ask = (prompt: string): Promise<string> =>
-      new Promise((resolve) => {
-        const rl = createInterface({
-          input: process.stdin,
-          output: process.stdout,
-        });
-        rl.question(prompt, (answer) => {
-          rl.close();
-          resolve(answer);
-        });
-      });
-
-    // Check / install dgmo-mcp binary
-    let dgmoMcpInstalled = false;
-    try {
-      execSync('which dgmo-mcp', { stdio: 'pipe' });
-      dgmoMcpInstalled = true;
-    } catch {
-      /* not found */
-    }
-    if (!dgmoMcpInstalled) {
-      const ans = await ask(
-        '\ndgmo-mcp not found. Install @diagrammo/dgmo-mcp globally now? [Y/n] '
-      );
-      const yes =
-        ans === '' || ans.toLowerCase() === 'y' || ans.toLowerCase() === 'yes';
-      if (yes) {
-        console.log('Installing @diagrammo/dgmo-mcp...');
-        try {
-          execSync('npm install -g @diagrammo/dgmo-mcp', { stdio: 'inherit' });
-          console.log('✓ @diagrammo/dgmo-mcp installed');
-        } catch {
-          console.error('Error: Failed to install @diagrammo/dgmo-mcp.');
-          console.error('Try manually: npm install -g @diagrammo/dgmo-mcp');
-        }
-      } else {
-        console.log(
-          '  Skipped. Install later with: npm install -g @diagrammo/dgmo-mcp'
-        );
-      }
-    } else {
-      console.log('✓ dgmo-mcp already installed');
-    }
+async function installClaudeCode(opts: InstallOpts): Promise<void> {
+  const claudeDir = join(homedir(), '.claude');
+  // Skill — single-sourced and always refreshed to the maintained latest.
+  writeOut(
+    opts,
+    join(claudeDir, 'commands', 'dgmo.md'),
+    readClaudeSkill(),
+    'Skill → ~/.claude/commands/dgmo.md'
+  );
+  ensureDgmoMcp(opts);
+  if (opts.scope === 'user') {
+    upsertJsonMcp(opts, join(claudeDir, 'settings.json'));
+    console.log('  (scope: all projects)');
+  } else {
+    upsertJsonMcp(opts, join(process.cwd(), '.mcp.json'));
+    console.log('  (scope: this project)');
+  }
+  console.log('  Then type /dgmo in any Claude Code session.');
+}
 
-    // Resolve the Claude Desktop config path for the current platform.
-    // macOS and Windows use the documented Claude Desktop paths; Linux
-    // doesn't have a first-party build yet, but community installs follow
-    // the XDG config convention.
-    const os = platform();
-    let configPath: string;
-    if (os === 'darwin') {
-      configPath = join(
-        homedir(),
-        'Library',
-        'Application Support',
-        'Claude',
-        'claude_desktop_config.json'
-      );
-    } else if (os === 'win32') {
-      const appData =
-        process.env['APPDATA'] ?? join(homedir(), 'AppData', 'Roaming');
-      configPath = join(appData, 'Claude', 'claude_desktop_config.json');
-    } else {
-      configPath = join(
-        homedir(),
-        '.config',
-        'Claude',
-        'claude_desktop_config.json'
-      );
-    }
+async function installCodex(opts: InstallOpts): Promise<void> {
+  ensureDgmoMcp(opts);
+
+  // MCP config (TOML). The block migrates in place if a legacy entry exists.
+  const tomlEntry = '[mcp_servers.dgmo]\ncommand = "dgmo"\nargs = ["mcp"]\n';
+  const configPath =
+    opts.scope === 'user'
+      ? join(homedir(), '.codex', 'config.toml')
+      : join(process.cwd(), '.codex', 'config.toml');
+  const existing = existsSync(configPath)
+    ? readFileSync(configPath, 'utf-8')
+    : '';
+  let next: string;
+  if (existing.includes('[mcp_servers.dgmo]')) {
+    next = existing.replace(/\[mcp_servers\.dgmo\][^[]*/, tomlEntry);
+  } else {
+    const sep = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    next = existing + sep + tomlEntry;
+  }
+  writeOut(opts, configPath, next, `MCP server → ${configPath}`);
 
-    // Read existing config (or start fresh). Non-JSON contents are treated
-    // as corruption and we bail — the user needs to resolve it manually so
-    // we don't silently overwrite something they care about.
-    type ClaudeDesktopConfig = {
-      mcpServers?: Record<
-        string,
-        { command: string; args?: string[]; env?: Record<string, string> }
-      >;
-      [key: string]: unknown;
-    };
-    let config: ClaudeDesktopConfig = {};
-    if (existsSync(configPath)) {
-      const raw = readFileSync(configPath, 'utf-8');
-      if (raw.trim().length > 0) {
-        try {
-          config = JSON.parse(raw) as ClaudeDesktopConfig;
-        } catch {
-          console.error(
-            `Error: ${configPath} exists but is not valid JSON. Fix it manually and re-run, or remove the file to regenerate.`
-          );
-          process.exit(1);
-        }
-      }
-    }
+  // Skill — single-sourced, always refreshed.
+  writeOut(
+    opts,
+    join(homedir(), '.codex', 'skills', 'dgmo-diagramming', 'SKILL.md'),
+    readCodexSkill(),
+    'Skill → ~/.codex/skills/dgmo-diagramming/SKILL.md'
+  );
 
-    const existingDgmo = config.mcpServers?.['dgmo'];
-    if (existingDgmo?.command === 'dgmo-mcp') {
-      console.log(`✓ dgmo MCP server already configured in ${configPath}`);
-    } else {
-      if (existingDgmo) {
-        const ans = await ask(
-          `\nA "dgmo" entry already exists in ${configPath}. Overwrite? [y/N] `
-        );
-        if (ans.toLowerCase() !== 'y' && ans.toLowerCase() !== 'yes') {
-          console.log('  Skipped.');
-          return;
-        }
-      }
-      config.mcpServers = {
-        ...(config.mcpServers ?? {}),
-        dgmo: { command: 'dgmo-mcp' },
-      };
-      mkdirSync(join(configPath, '..'), { recursive: true });
+  // Non-destructive AGENTS.md note: only append to an existing file, never create.
+  const agentsPath = join(process.cwd(), 'AGENTS.md');
+  if (!opts.dryRun && existsSync(agentsPath)) {
+    const existingAgents = readFileSync(agentsPath, 'utf-8');
+    if (!existingAgents.includes(CODEX_AGENTS_NOTE_MARKER)) {
+      const separator = existingAgents.endsWith('\n') ? '\n' : '\n\n';
       writeFileSync(
-        configPath,
-        JSON.stringify(config, null, 2) + '\n',
+        agentsPath,
+        existingAgents + separator + CODEX_AGENTS_NOTE,
         'utf-8'
       );
-      console.log(`✓ dgmo MCP server configured: ${configPath}`);
+      console.log('✓ Appended dgmo note to AGENTS.md');
     }
+  }
+}
+
+async function installClaudeDesktop(opts: InstallOpts): Promise<void> {
+  ensureDgmoMcp(opts);
+  // Claude Desktop config is always the per-user app config (scope is N/A).
+  upsertJsonMcp(opts, claudeDesktopConfigPath());
+}
+
+// Cursor speaks MCP via ~/.cursor/mcp.json (user) or .cursor/mcp.json (project),
+// using the same { mcpServers } schema as Claude — so it gets the full tools,
+// not just syntax guidance. We also drop the shipped .cursorrules so the model
+// has inline context without a tool round-trip.
+function installCursor(opts: InstallOpts): void {
+  ensureDgmoMcp(opts);
+  const path =
+    opts.scope === 'project'
+      ? join(process.cwd(), '.cursor', 'mcp.json')
+      : join(homedir(), '.cursor', 'mcp.json');
+  upsertJsonMcp(opts, path);
+  writeOut(
+    opts,
+    join(process.cwd(), '.cursorrules'),
+    readPackagedFile('.cursorrules'),
+    'Cursor rules → .cursorrules'
+  );
+}
+
+// Windsurf (Codeium) reads MCP from ~/.codeium/windsurf/mcp_config.json.
+function installWindsurf(opts: InstallOpts): void {
+  ensureDgmoMcp(opts);
+  upsertJsonMcp(
+    opts,
+    join(homedir(), '.codeium', 'windsurf', 'mcp_config.json')
+  );
+  writeOut(
+    opts,
+    join(process.cwd(), '.windsurfrules'),
+    readPackagedFile('.windsurfrules'),
+    'Windsurf rules → .windsurfrules'
+  );
+}
+
+// Copilot has no MCP path — ship the project-root instructions file it auto-loads.
+function installCopilot(opts: InstallOpts): void {
+  writeOut(
+    opts,
+    join(process.cwd(), '.github', 'copilot-instructions.md'),
+    readPackagedFile('.github', 'copilot-instructions.md'),
+    'Copilot context → .github/copilot-instructions.md'
+  );
+}
 
-    console.log('\nRestart Claude Desktop to activate the MCP server.');
+async function main(): Promise<void> {
+  // Subcommand dispatch — each is parsed independently from the rendering
+  // flags so their surface doesn't pollute `parseArgs`.
+  const sub = process.argv[2];
+  if (sub === 'map-search') {
+    await runMapSearchCommand(process.argv.slice(3));
+    return;
+  }
+  if (sub === 'share') {
+    await runShareCommand(process.argv.slice(3));
+    return;
+  }
+  if (sub === 'types') {
+    runTypesCommand(process.argv.slice(3));
+    return;
+  }
+  if (sub === 'install') {
+    await runInstallCommand(process.argv.slice(3));
+    return;
+  }
+  if (sub === 'mcp') {
+    runMcpCommand(process.argv.slice(3));
+  }
+
+  const opts = parseArgs(process.argv);
+
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  if (opts.version) {
+    printVersion();
     return;
   }
 
@@ -1502,15 +866,16 @@ async function main(): Promise<void> {
     content = resolved.content;
   }
 
-  // Determine output format early to handle URL before rendering
-  const format = inferFormat(opts.output);
-
-  // Validate --copy flag
-  if (opts.copy && format !== 'url') {
-    console.error('Error: --copy can only be used with -o url');
+  // `-o url` was replaced by `dgmo share`; catch the old usage with a helpful
+  // redirect instead of writing a file literally named "url".
+  if (opts.output === 'url') {
+    console.error('Error: `-o url` was replaced by `dgmo share <input>`.');
+    console.error(`Try: dgmo share ${opts.input ?? '<input>'}`);
     process.exit(1);
   }
 
+  const format = inferFormat(opts.output);
+
   const chartType = parseDgmoChartType(content);
 
   // Helper for JSON error output
@@ -1534,55 +899,6 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  // URL output — encode DSL directly, no rendering needed.
-  // PERT diagrams may contain `start-date now`; resolve to today's
-  // date BEFORE encoding so the share-link captures authoring intent
-  // (per spec D9). Cheap to call on non-PERT content — the regex
-  // matches nothing.
-  if (format === 'url') {
-    const sourceForUrl =
-      chartType === 'pert' ? normalizePertSourceForShare(content) : content;
-    const result = encodeDiagramUrl(sourceForUrl);
-    if (result.error) {
-      exitWithJsonError(
-        `Error: Diagram too large for URL sharing (${result.compressedSize} bytes, limit ${result.limit} bytes)`
-      );
-    }
-
-    if (opts.copy) {
-      try {
-        const platform = process.platform;
-        if (platform === 'darwin') {
-          execSync('pbcopy', { input: result.url });
-        } else if (platform === 'win32') {
-          execSync('clip', { input: result.url });
-        } else {
-          execSync('xclip -selection clipboard', { input: result.url });
-        }
-        console.error('URL copied to clipboard');
-      } catch {
-        console.error('Warning: Could not copy to clipboard');
-      }
-    }
-
-    if (opts.json) {
-      process.stdout.write(
-        JSON.stringify(
-          {
-            success: true,
-            url: result.url,
-            ...(chartType ? { chartType } : {}),
-          },
-          null,
-          2
-        ) + '\n'
-      );
-    } else {
-      process.stdout.write(result.url + '\n');
-    }
-    return;
-  }
-
   const paletteColors = getPalette(opts.palette)[
     opts.theme === 'dark' ? 'dark' : 'light'
   ];
@@ -1595,7 +911,7 @@ async function main(): Promise<void> {
   // Print warnings even if rendering succeeds
   if (!opts.json) {
     for (const w of warnings) {
-      console.error(`\u26A0 ${formatDgmoError(w)}`);
+      console.error(`⚠ ${formatDgmoError(w)}`);
     }
   }
 
@@ -1606,7 +922,7 @@ async function main(): Promise<void> {
       exitWithJsonError(formatDgmoError(firstError), firstError.line);
     }
     for (const e of errors) {
-      console.error(`\u2716 ${formatDgmoError(e)}`);
+      console.error(`✖ ${formatDgmoError(e)}`);
     }
   }