@diagrammo/dgmo 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

package/src/advanced.ts

@@ -174,6 +174,9 @@ export type {
 } from './graph/types';
 
 export type { TagGroup, TagEntry } from './utils/tag-groups';
+// The canonical categorical auto-color rotation (RGB-seeded, max-contrast,
+// neutrals excluded) — so app/editor swatch cyclers share dgmo's exact order.
+export { autoTagColorCycle } from './utils/tag-groups';
 
 export { parseInlineMarkdown, truncateBareUrl } from './utils/inline-markdown';
 export type { InlineSpan } from './utils/inline-markdown';

package/src/boxes-and-lines/layout-search.ts

@@ -1016,6 +1016,217 @@ export function layoutBoxesAndLinesSearch(
     Math.abs(p.x - rect.x) <= rect.w / 2 &&
     Math.abs(p.y - rect.y) <= rect.h / 2;
 
+  // ── Pinned-layout bypass (Canvas Editor spike, Decisions 3/7) ──
+  // When a `layout` block positions EVERY node, place nodes directly from the
+  // stored coordinates and skip the whole dagre search. Edges become
+  // border-clipped straight connectors (no obstacle avoidance — honest-but-ugly).
+  // FLAT, EXPANDED groups are honored: each group's container rect is computed
+  // from its members' pinned positions (canvas group editing). A FLAT group can
+  // also be COLLAPSED while pinned — it renders as a plain box at its members'
+  // bbox-centre (so collapse no longer forces a full dagre reflow). Nested groups
+  // still fall back to dagre (deferred).
+  const pinned = parsed.nodePositions;
+  const groupLabelSet = new Set(parsed.groups.map((g) => g.label));
+  const groupsAreFlat = parsed.groups.every(
+    (g) => !g.parentGroup && !g.children.some((c) => groupLabelSet.has(c))
+  );
+  // A collapsed group can stay pinned only when it's FLAT (top-level, no
+  // sub-groups) and every one of its members has a pinned coord — otherwise we
+  // can't place its box without a search, so fall back to dagre.
+  const allOriginalGroupLabels = new Set(
+    (collapseInfo?.originalGroups ?? parsed.groups).map((g) => g.label)
+  );
+  const collapsedAreFlatPinned =
+    collapsedGroupLabels.size === 0 ||
+    (pinned !== undefined &&
+      collapseInfo !== undefined &&
+      [...collapsedGroupLabels].every((label) => {
+        const og = collapseInfo.originalGroups.find((g) => g.label === label);
+        if (!og || og.parentGroup) return false;
+        return og.children.every(
+          (c) => pinned.has(c) && !allOriginalGroupLabels.has(c)
+        );
+      }));
+  const allPinned =
+    pinned !== undefined &&
+    (parsed.nodes.length > 0 || collapsedGroupLabels.size > 0) &&
+    parsed.nodes.every((n) => pinned.has(n.label)) &&
+    groupsAreFlat &&
+    collapsedAreFlatPinned;
+  function placePinned(pins: ReadonlyMap<string, Pt>): BLLayoutResult {
+    // Collapsed flat groups → a plain NODE-sized box at the bbox-centre of the
+    // group's (now-hidden) members' pinned coords. The collapse transform
+    // redirected their incident edges to `__group_<label>`, so register that id
+    // in the position/rect lookups too.
+    const collapsedPosByGid = new Map<string, Pt>();
+    const collapsedBoxes: Array<{
+      label: string;
+      lineNumber: number;
+      childCount: number;
+      x: number;
+      y: number;
+    }> = [];
+    if (collapseInfo)
+      for (const label of collapsedGroupLabels) {
+        const og = collapseInfo.originalGroups.find((g) => g.label === label);
+        if (!og) continue;
+        let cx0 = Infinity,
+          cy0 = Infinity,
+          cx1 = -Infinity,
+          cy1 = -Infinity;
+        for (const c of og.children) {
+          const p = pins.get(c);
+          if (!p) continue;
+          cx0 = Math.min(cx0, p.x);
+          cx1 = Math.max(cx1, p.x);
+          cy0 = Math.min(cy0, p.y);
+          cy1 = Math.max(cy1, p.y);
+        }
+        if (!Number.isFinite(cx0)) continue;
+        const cx = (cx0 + cx1) / 2;
+        const cy = (cy0 + cy1) / 2;
+        collapsedPosByGid.set(`__group_${label}`, { x: cx, y: cy });
+        collapsedBoxes.push({
+          label,
+          lineNumber: og.lineNumber,
+          childCount:
+            collapseInfo.collapsedChildCounts.get(label) ?? og.children.length,
+          x: cx,
+          y: cy,
+        });
+      }
+    const posOf = (label: string): Pt | undefined =>
+      pins.get(label) ?? collapsedPosByGid.get(label);
+    const rectOf = (label: string) => {
+      const p = posOf(label)!;
+      const s = sizes.get(label) ?? { width: NODE_WIDTH, height: NODE_HEIGHT };
+      return { x: p.x, y: p.y, w: s.width, h: s.height };
+    };
+    const nodes = parsed.nodes.map((n) => {
+      const r = rectOf(n.label);
+      return { label: n.label, x: r.x, y: r.y, width: r.w, height: r.h };
+    });
+    const edges: BLLayoutEdge[] = parsed.edges.flatMap((e) => {
+      const sp = posOf(e.source);
+      const tp = posOf(e.target);
+      if (!sp || !tp) return [];
+      const srcRect = rectOf(e.source);
+      const tgtRect = rectOf(e.target);
+      const p0 = rectBorderPoint(srcRect, tp);
+      const p1 = rectBorderPoint(tgtRect, sp);
+      return [
+        {
+          source: e.source,
+          target: e.target,
+          ...(e.label !== undefined && { label: e.label }),
+          bidirectional: e.bidirectional,
+          lineNumber: e.lineNumber,
+          points: [p0, p1],
+          yOffset: 0,
+          parallelCount: 1,
+          metadata: e.metadata,
+          straight: true,
+        },
+      ];
+    });
+    // Fit the canvas around the pinned content with a uniform margin on every
+    // side. Crucially, content must never fall off the TOP/LEFT (the viewBox
+    // origin is 0,0): if a node was dragged past the margin we shift everything
+    // back on-canvas by `max(0, M - min)` — clamped so in-bounds diagrams keep
+    // their exact pinned coords (shift 0) and only off-canvas ones are nudged.
+    // Flat-group container rects: bbox of the group's members + side/bottom
+    // padding, with a label zone reserved at the top (mirrors the renderer).
+    const GROUP_PAD = 16;
+    const nodeByLabel = new Map(nodes.map((n) => [n.label, n]));
+    const groups: BLLayoutResult['groups'][number][] = [];
+    for (const grp of parsed.groups) {
+      let gx0 = Infinity,
+        gy0 = Infinity,
+        gx1 = -Infinity,
+        gy1 = -Infinity;
+      for (const c of grp.children) {
+        const n = nodeByLabel.get(c);
+        if (!n) continue;
+        gx0 = Math.min(gx0, n.x - n.width / 2);
+        gx1 = Math.max(gx1, n.x + n.width / 2);
+        gy0 = Math.min(gy0, n.y - n.height / 2);
+        gy1 = Math.max(gy1, n.y + n.height / 2);
+      }
+      if (!Number.isFinite(gx0)) continue; // members not pinned / empty group
+      const x0 = gx0 - GROUP_PAD;
+      const x1 = gx1 + GROUP_PAD;
+      const y0 = gy0 - GROUP_LABEL_ZONE;
+      const y1 = gy1 + GROUP_PAD;
+      groups.push({
+        label: grp.label,
+        lineNumber: grp.lineNumber,
+        x: (x0 + x1) / 2,
+        y: (y0 + y1) / 2,
+        width: x1 - x0,
+        height: y1 - y0,
+        collapsed: false,
+        childCount: grp.children.length,
+      });
+    }
+    // Collapsed flat groups: a plain box at the members' centre.
+    for (const cb of collapsedBoxes) {
+      groups.push({
+        label: cb.label,
+        lineNumber: cb.lineNumber,
+        x: cb.x,
+        y: cb.y,
+        width: NODE_WIDTH,
+        height: NODE_HEIGHT,
+        collapsed: true,
+        childCount: cb.childCount,
+      });
+    }
+
+    const M = 40;
+    let minX = Infinity,
+      minY = Infinity,
+      maxX = -Infinity,
+      maxY = -Infinity;
+    const acc = (x: number, y: number) => {
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+    };
+    for (const n of nodes) {
+      acc(n.x - n.width / 2, n.y - n.height / 2);
+      acc(n.x + n.width / 2, n.y + n.height / 2);
+    }
+    for (const e of edges) for (const p of e.points) acc(p.x, p.y);
+    for (const gr of groups) {
+      acc(gr.x - gr.width / 2, gr.y - gr.height / 2);
+      acc(gr.x + gr.width / 2, gr.y + gr.height / 2);
+    }
+    // Only correct genuinely off-canvas content — a small tolerance ignores the
+    // sub-pixel jitter from rounding coords near the margin, so an already
+    // on-canvas diagram keeps its exact pinned positions (no creeping drift).
+    const TOL = 2;
+    const sx = minX < M - TOL ? M - minX : 0;
+    const sy = minY < M - TOL ? M - minY : 0;
+    const shifted = sx !== 0 || sy !== 0;
+    return {
+      nodes: shifted
+        ? nodes.map((n) => ({ ...n, x: n.x + sx, y: n.y + sy }))
+        : nodes,
+      edges: shifted
+        ? edges.map((e) => ({
+            ...e,
+            points: e.points.map((p) => ({ x: p.x + sx, y: p.y + sy })),
+          }))
+        : edges,
+      groups: shifted
+        ? groups.map((gr) => ({ ...gr, x: gr.x + sx, y: gr.y + sy }))
+        : groups,
+      width: maxX + sx + M,
+      height: maxY + sy + M,
+    };
+  }
+
   function place(cfg: {
     ranker: string;
     nodesep: number;
@@ -1173,6 +1384,9 @@ export function layoutBoxesAndLinesSearch(
     } as BLLayoutResult;
   }
 
+  // Pinned mode short-circuits the entire search.
+  if (allPinned) return placePinned(pinned!);
+
   const n = parsed.nodes.length;
   // ~500ms budget: search a larger pool, then refine the top few exactly.
   const seedCount =

package/src/boxes-and-lines/layout.ts

@@ -66,6 +66,10 @@ export interface BLLayoutEdge {
   /** Marker for renderer: draw with linear curve, not curveBasis (ELK gives
    * us orthogonal polylines and curveBasis would smooth corners into waves) */
   readonly deferred?: boolean;
+  /** Pinned-layout connector: a border-clipped straight 2-point segment (Canvas
+   *  Editor spike, Decision 7). Renderer draws it with a linear generator —
+   *  curveBasis collapses a 2-point polyline. */
+  readonly straight?: boolean;
 }
 
 export interface BLLayoutGroup {

package/src/boxes-and-lines/parser.ts

@@ -127,6 +127,8 @@ export function parseBoxesAndLines(
   const nodes: MutBLNode[] = [];
   const edges: MutBLEdge[] = [];
   const groups: MutBLGroup[] = [];
+  // Trailing `layout` block (Canvas Editor spike): node-id → absolute {x,y}.
+  const nodePositions = new Map<string, { x: number; y: number }>();
   const result: Writable<ParsedBoxesAndLines> = {
     type: 'boxes-and-lines',
     title: null,
@@ -178,6 +180,11 @@ export function parseBoxesAndLines(
 
   // Tag block state
   let contentStarted = false;
+  // `layout` coordinate-block state (Canvas Editor spike). Unlike tag blocks,
+  // this is a TRAILING appendix — it may appear after diagram content.
+  let inLayoutBlock = false;
+  const LAYOUT_ENTRY_RE =
+    /^(.+?):\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$/;
   let currentTagGroup: Writable<TagGroup> | null = null;
   // metaAliasMap: tag-group metadata-key aliases (per A1).
   const metaAliasMap = new Map<string, string>();
@@ -436,6 +443,52 @@ export function parseBoxesAndLines(
       currentTagGroup = null;
     }
 
+    // `layout` coordinate block (Canvas Editor spike). A bare `layout` heading
+    // at indent 0 opens the block; indented `<node-id>: <x>, <y>` entries map a
+    // node to an absolute position. Any non-indented line closes it. Quarantined
+    // before group/node/edge matching so the entries don't parse as nodes.
+    if (!inLayoutBlock && indent === 0 && trimmed === 'layout') {
+      // Disambiguate from a node legitimately NAMED `layout`: only treat this as
+      // the coordinate appendix when the next non-blank line is an indented
+      // `<id>: <x>, <y>` entry. Otherwise fall through and parse `layout` as a
+      // normal node (no silent data loss).
+      let isBlock = false;
+      for (let j = i + 1; j < lines.length; j++) {
+        const peek = lines[j]!;
+        if (!peek.trim()) continue;
+        isBlock = measureIndent(peek) > 0 && LAYOUT_ENTRY_RE.test(peek.trim());
+        break;
+      }
+      if (isBlock) {
+        flushDescription();
+        closeGroupsToIndent(0);
+        inLayoutBlock = true;
+        continue;
+      }
+    }
+    if (inLayoutBlock) {
+      if (indent > 0) {
+        const lm = trimmed.match(LAYOUT_ENTRY_RE);
+        if (lm) {
+          nodePositions.set(lm[1]!.trim(), {
+            x: Number(lm[2]),
+            y: Number(lm[3]),
+          });
+        } else {
+          result.diagnostics.push(
+            makeDgmoError(
+              lineNum,
+              `Invalid layout entry "${trimmed}" — expected "<node-id>: <x>, <y>"`,
+              'warning'
+            )
+          );
+        }
+        continue;
+      }
+      // indent 0 → block ends; fall through to process this line normally.
+      inLayoutBlock = false;
+    }
+
     // Description collection: indented non-edge lines under a node
     if (descState !== null) {
       if (indent > descState.indent) {
@@ -762,6 +815,31 @@ export function parseBoxesAndLines(
   // passed to extractColor above), so auto colors match for consistency.
   finalizeAutoTagColors(result.tagGroups as Writable<TagGroup>[]);
 
+  // Attach parsed `layout` positions. Validate coverage: unknown ids warn; a
+  // PARTIAL block (some nodes unpositioned) is honored by neither pin nor seed —
+  // the layout engine ignores it and auto-lays-out (Decision 3, AC12), so emit a
+  // single diagnostic naming the gap.
+  if (nodePositions.size > 0) {
+    const nodeLabelSet = new Set(result.nodes.map((n) => n.label));
+    for (const id of nodePositions.keys()) {
+      if (!nodeLabelSet.has(id)) {
+        pushWarning(0, `layout entry for unknown node "${id}" (ignored)`);
+      }
+    }
+    const unpositioned = result.nodes
+      .filter((n) => !nodePositions.has(n.label))
+      .map((n) => n.label);
+    if (unpositioned.length > 0) {
+      pushWarning(
+        0,
+        `layout block is partial — ${unpositioned.length} node(s) without coordinates ` +
+          `(${unpositioned.slice(0, 5).join(', ')}${unpositioned.length > 5 ? '…' : ''}); ` +
+          `ignoring the block and auto-laying-out`
+      );
+    }
+    result.nodePositions = nodePositions;
+  }
+
   // Post-parse: inject default tag metadata and validate tag values
   if (result.tagGroups.length > 0) {
     injectDefaultTagMetadata(result.nodes, result.tagGroups);

package/src/boxes-and-lines/renderer.ts

@@ -56,9 +56,13 @@ const DIAGRAM_PADDING = 20;
 const NODE_FONT_SIZE = 11;
 const MIN_NODE_FONT_SIZE = 9;
 const EDGE_LABEL_FONT_SIZE = 11;
-const EDGE_STROKE_WIDTH = 1.5;
-const NODE_STROKE_WIDTH = 1.5;
+import {
+  EDGE_STROKE_WIDTH,
+  NODE_STROKE_WIDTH,
+} from '../utils/visual-conventions'; // shared (Story 111.1)
 const NODE_RX = 8;
+// Intentional deviation (conventions §3): boxes-and-lines uses a 4px collapse
+// bar (and 4px separator gap in layout.ts) — denser than the 6px default.
 const COLLAPSE_BAR_HEIGHT = 4;
 const ARROWHEAD_W = 5;
 const ARROWHEAD_H = 4;
@@ -89,6 +93,15 @@ const lineGeneratorTB = d3Shape
   .y((d) => d.y)
   .curve(d3Shape.curveBasis);
 
+// Straight (linear) generator for pinned-layout connectors (Canvas Editor
+// spike). curveBasis collapses a 2-point polyline, so border-clipped straight
+// edges must draw linearly.
+const lineGeneratorStraight = d3Shape
+  .line<{ x: number; y: number }>()
+  .x((d) => d.x)
+  .y((d) => d.y)
+  .curve(d3Shape.curveLinear);
+
 // ── Text fitting ───────────────────────────────────────────
 
 function splitCamelCase(word: string): string[] {
@@ -614,8 +627,43 @@ export function renderBoxesAndLines(
   const scaleY = height / (contentH + sDiagramPadding * 2);
   const scale = Math.min(scaleX, scaleY, 3);
 
-  const offsetX = (width - contentW * scale) / 2;
-  const offsetY = sDiagramPadding + titleOffset + legendH;
+  // Pinned (`layout`-block) coordinates can leave the content's real extent
+  // sitting off-centre inside layout.width/height — e.g. nodes pinned far from
+  // the origin bake a wide gap on one side. Re-centre the content within its
+  // own box by equalizing opposite margins. Gated to pinned diagrams so the
+  // auto-layout path (and its snapshots) stays byte-identical: that path
+  // already produces symmetric margins.
+  let centerShiftX = 0;
+  let centerShiftY = 0;
+  if (parsed.nodePositions && parsed.nodePositions.size > 0) {
+    let bMinX = Infinity,
+      bMinY = Infinity,
+      bMaxX = -Infinity,
+      bMaxY = -Infinity;
+    const accB = (x: number, y: number) => {
+      if (x < bMinX) bMinX = x;
+      if (x > bMaxX) bMaxX = x;
+      if (y < bMinY) bMinY = y;
+      if (y > bMaxY) bMaxY = y;
+    };
+    for (const n of layout.nodes) {
+      accB(n.x - n.width / 2, n.y - n.height / 2);
+      accB(n.x + n.width / 2, n.y + n.height / 2);
+    }
+    for (const g of layout.groups) {
+      accB(g.x - g.width / 2, g.y - g.height / 2);
+      accB(g.x + g.width / 2, g.y + g.height / 2);
+    }
+    for (const e of layout.edges) for (const p of e.points) accB(p.x, p.y);
+    if (Number.isFinite(bMinX)) {
+      centerShiftX = (layout.width - bMaxX - bMinX) / 2;
+      centerShiftY = (layout.height - bMaxY - bMinY) / 2;
+    }
+  }
+
+  const offsetX = (width - contentW * scale) / 2 + centerShiftX * scale;
+  const offsetY =
+    sDiagramPadding + titleOffset + legendH + centerShiftY * scale;
 
   const svg: D3Svg = d3Selection
     .select(container)
@@ -896,7 +944,11 @@ export function renderBoxesAndLines(
     edgeGroups.set(i, edgeG as unknown as D3G);
 
     const markerId = `bl-arrow-${color.replace('#', '')}`;
-    const gen = parsed.direction === 'TB' ? lineGeneratorTB : lineGeneratorLR;
+    const gen = le.straight
+      ? lineGeneratorStraight
+      : parsed.direction === 'TB'
+        ? lineGeneratorTB
+        : lineGeneratorLR;
     const path = edgeG
       .append('path')
       .attr('class', 'bl-edge')

package/src/boxes-and-lines/types.ts

@@ -42,6 +42,15 @@ export interface ParsedBoxesAndLines {
   readonly notes?: readonly DiagramNote[];
   readonly initialHiddenTagValues: ReadonlyMap<string, ReadonlySet<string>>;
   readonly direction: 'LR' | 'TB';
+  /** Optional per-node absolute positions, parsed from a trailing `layout`
+   *  block (`<node-id>: <x>, <y>`). Diagram-space coordinates. When present and
+   *  covering EVERY node, the layout engine bypasses auto-placement and pins
+   *  nodes here (see Decision 3 — two clean modes). A partial block is ignored
+   *  with a diagnostic (AC12). Experimental — Canvas Editor spike. */
+  readonly nodePositions?: ReadonlyMap<
+    string,
+    { readonly x: number; readonly y: number }
+  >;
   /** `box-metric <label> [low] [high]` — names the value-ramp dimension and
    *  optionally sets its endpoint colours. One color = high hue over a neutral
    *  low; two = explicit `low high`. Mirror of map's `region-metric`. */

package/src/c4/renderer.ts

@@ -37,16 +37,18 @@ const DESC_FONT_SIZE = 11;
 const DESC_LINE_HEIGHT = 16;
 const EDGE_LABEL_FONT_SIZE = 11;
 const TECH_FONT_SIZE = 10;
-const EDGE_STROKE_WIDTH = 1.5;
-const NODE_STROKE_WIDTH = 1.5;
-const CARD_RADIUS = 6;
+import {
+  EDGE_STROKE_WIDTH,
+  NODE_STROKE_WIDTH,
+  CARD_RADIUS,
+  META_FONT_SIZE,
+  META_LINE_HEIGHT,
+} from '../utils/visual-conventions'; // shared (Story 111.1)
 const CARD_H_PAD = 20;
 const CARD_V_PAD = 14;
 const TYPE_LABEL_HEIGHT = 18;
 const DIVIDER_GAP = 6;
 const NAME_HEIGHT = 20;
-const META_FONT_SIZE = 11;
-const META_LINE_HEIGHT = 16;
 const BOUNDARY_LABEL_FONT_SIZE = 12;
 const BOUNDARY_STROKE_WIDTH = 1.5;
 const BOUNDARY_RADIUS = 8;

package/src/chart-types.ts

@@ -125,7 +125,7 @@ export const chartTypes: readonly ChartTypeMeta[] = [
   {
     id: 'map',
     description:
-      'Geographic concept map: highlight/score regions, drop points of interest, connect with routes or edges',
+      'Geographic map: a value or count per country, state, or region (choropleth); points of interest; routes. Use when categories are real-world places.',
   },
 
   // ── Tier 3 — Specialized analytical charts ────────────────
@@ -143,7 +143,7 @@ export const chartTypes: readonly ChartTypeMeta[] = [
   },
   {
     id: 'slope',
-    description: 'Change between two periods',
+    description: 'Change for multiple things between exactly two periods',
   },
   {
     id: 'sankey',

package/src/class/renderer.ts

@@ -47,8 +47,10 @@ const MAX_SCALE = 3;
 const CLASS_FONT_SIZE = 13;
 const MEMBER_FONT_SIZE = 11;
 const EDGE_LABEL_FONT_SIZE = 11;
-const EDGE_STROKE_WIDTH = 1.5;
-const NODE_STROKE_WIDTH = 1.5;
+import {
+  EDGE_STROKE_WIDTH,
+  NODE_STROKE_WIDTH,
+} from '../utils/visual-conventions'; // shared (Story 111.1)
 const MEMBER_LINE_HEIGHT = 18;
 const COMPARTMENT_PADDING_Y = 8;
 const MEMBER_PADDING_X = 10;

package/src/cli-banner.ts

@@ -0,0 +1,107 @@
+// ============================================================
+// CLI Banner — colorful ASCII logo for `dgmo`
+// ============================================================
+//
+// Rendered as the header of `dgmo --help` and at the end of the
+// install/init flows. Uses a horizontal true-color (24-bit) gradient
+// 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.
+
+import { getPalette } from './palettes';
+
+// ANSI Shadow letterform for "dgmo" (6 rows) + tagline.
+const ART = [
+  '██████╗  ██████╗ ███╗   ███╗ ██████╗ ',
+  '██╔══██╗██╔════╝ ████╗ ████║██╔═══██╗',
+  '██║  ██║██║  ███╗██╔████╔██║██║   ██║',
+  '██║  ██║██║   ██║██║╚██╔╝██║██║   ██║',
+  '██████╔╝╚██████╔╝██║ ╚═╝ ██║╚██████╔╝',
+  '╚═════╝  ╚═════╝ ╚═╝     ╚═╝ ╚═════╝ ',
+];
+
+const TAGLINE = 'diagrams as code';
+
+// Gradient stops, pulled by name from the live slate palette (light) so the
+// wordmark tracks any palette edit instead of drifting from a hardcoded copy.
+// blue → teal → green → amber: a vivid sweep across the categorical hues.
+const GRADIENT_COLOR_NAMES = ['blue', 'teal', 'green', 'orange'] as const;
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '');
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+const STOPS: Array<[number, number, number]> = (() => {
+  const colors = getPalette('slate').light.colors;
+  return GRADIENT_COLOR_NAMES.map((name) => hexToRgb(colors[name]));
+})();
+
+function lerp(a: number, b: number, t: number): number {
+  return Math.round(a + (b - a) * t);
+}
+
+/** Interpolate the multi-stop gradient at position t ∈ [0, 1]. */
+function gradientAt(t: number): [number, number, number] {
+  const clamped = Math.max(0, Math.min(1, t));
+  const span = STOPS.length - 1;
+  const scaled = clamped * span;
+  const i = Math.min(span - 1, Math.floor(scaled));
+  const local = scaled - i;
+  const [r1, g1, b1] = STOPS[i]!;
+  const [r2, g2, b2] = STOPS[i + 1]!;
+  return [lerp(r1, r2, local), lerp(g1, g2, local), lerp(b1, b2, local)];
+}
+
+function fg(r: number, g: number, b: number): string {
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+const RESET = '\x1b[0m';
+
+export interface BannerOptions {
+  /** Force-disable color regardless of TTY (default honors stdout TTY + NO_COLOR). */
+  color?: boolean;
+}
+
+/**
+ * Build the dgmo banner string. Colorized with a horizontal gradient when
+ * `color` is true; otherwise returns plain ASCII.
+ */
+export function renderBanner(opts: BannerOptions = {}): string {
+  const useColor =
+    opts.color ?? (process.stdout.isTTY === true && !process.env['NO_COLOR']);
+
+  const width = Math.max(...ART.map((line) => line.length));
+
+  const lines = ART.map((line) => {
+    if (!useColor) return line;
+    let out = '';
+    for (let col = 0; col < line.length; col++) {
+      const ch = line[col];
+      // Don't paint spaces — keeps escape sequences minimal.
+      if (ch === ' ') {
+        out += ch;
+        continue;
+      }
+      const [r, g, b] = gradientAt(col / (width - 1));
+      out += fg(r, g, b) + ch;
+    }
+    return out + RESET;
+  });
+
+  // Right-align the tagline under the wordmark, muted.
+  const pad = Math.max(0, width - TAGLINE.length);
+  const tagline = useColor
+    ? `${' '.repeat(pad)}\x1b[2;3m${TAGLINE}${RESET}`
+    : `${' '.repeat(pad)}${TAGLINE}`;
+
+  return ['', ...lines, tagline, ''].join('\n');
+}

package/src/cli.ts

@@ -25,6 +25,7 @@ import {
   migrateFile,
 } from './migrate';
 import { migrateEmbedded } from './migrate/embedded';
+import { renderBanner } from './cli-banner';
 
 // Derived from the palette registry so new palettes are auto-included.
 const PALETTES = getAvailablePalettes().map((p) => p.id);
@@ -464,6 +465,7 @@ 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
@@ -648,10 +650,12 @@ function svgToPng(svg: string, background?: string): Buffer {
 }
 
 function noInput(): never {
+  console.error(renderBanner());
   const samplePath = resolve('sample.dgmo');
   if (existsSync(samplePath)) {
     console.error('Error: No input file specified');
     console.error(`Try: dgmo ${basename(samplePath)}`);
+    console.error('Run dgmo --help for all options.');
     process.exit(1);
   }
   writeFileSync(
@@ -925,6 +929,15 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (
+    opts.installClaudeCodeIntegration ||
+    opts.installClaudeSkill ||
+    opts.installCodexIntegration ||
+    opts.installClaudeDesktopIntegration
+  ) {
+    console.log(renderBanner());
+  }
+
   if (opts.installClaudeCodeIntegration) {
     const claudeDir = join(homedir(), '.claude');
     if (!existsSync(claudeDir)) {