@diagrammo/dgmo 0.6.1 → 0.6.2

package/docs/ai-integration.md

@@ -1,14 +1,16 @@
 # DGMO AI Integration Guide
 
-Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code, Copilot, Cursor, and other AI tools.
+Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code, Copilot, Cursor, Windsurf, and any tool with an MCP client.
 
-## MCP Server
+---
 
-`@diagrammo/dgmo-mcp` provides an MCP server that exposes DGMO rendering, sharing, and documentation tools. Works with Claude Desktop, Claude Code, and any MCP-compatible client.
+## MCP Server (recommended for Claude)
 
-5 tools: `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`.
+`@diagrammo/dgmo-mcp` provides an MCP server that gives Claude the ability to render, share, and look up DGMO diagrams directly — no file management needed.
 
-Setup (Claude Code — add to `.claude/settings.local.json`):
+**5 tools:** `render_diagram`, `share_diagram`, `open_in_app`, `list_chart_types`, `get_language_reference`
+
+Add to `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project):
 
 ```json
 {
@@ -23,60 +25,46 @@ Setup (Claude Code — add to `.claude/settings.local.json`):
 
 See `dgmo-mcp/README.md` for full configuration options.
 
-## Claude Code — Skills
-
-Copy the `.claude/skills/dgmo-*` directories from this repo into your project's `.claude/skills/` directory. This gives you four slash commands:
+---
 
-| Command | What it does |
-|---------|-------------|
-| `/dgmo-generate <description>` | Picks the best diagram type automatically |
-| `/dgmo-sequence <flow>` | Generates a sequence diagram |
-| `/dgmo-flowchart <process>` | Generates a flowchart |
-| `/dgmo-chart <data description>` | Generates a data chart |
+## Claude Code — Skill (slash command)
 
-### Setup
+Installs a `/dgmo` slash command that gives Claude full dgmo context — all chart types, CLI flags, workflow, and tips.
 
 ```bash
-# Copy skills into your project
-cp -r node_modules/@diagrammo/dgmo/.claude/skills/dgmo-* .claude/skills/
-
-# Or if dgmo is installed globally
-cp -r $(npm root -g)/@diagrammo/dgmo/.claude/skills/dgmo-* .claude/skills/
+dgmo --install-claude-skill
 ```
 
-### Usage examples
+This copies a skill file into `~/.claude/commands/`, making `/dgmo` available in every Claude Code session.
 
-```
-/dgmo-generate an ER diagram for a blog with users, posts, and comments
-/dgmo-sequence the OAuth2 authorization code flow
-/dgmo-flowchart CI/CD pipeline with build, test, and deploy stages
-/dgmo-chart quarterly revenue: Q1 100, Q2 120, Q3 110, Q4 130
-```
+---
 
 ## Claude Code — CLAUDE.md snippet
 
-Add this to your project's `CLAUDE.md` to teach Claude about DGMO without installing skills:
+To teach Claude about DGMO in a specific project without the global skill, add this to your `CLAUDE.md`:
 
 ```markdown
 ## DGMO Diagrams
 
-When the user asks for a diagram, generate a `.dgmo` file. DGMO is a text-based diagram language.
+When the user asks for a diagram, generate a `.dgmo` file.
 
 Quick reference:
-- Sequence: `A -> B: message` or `A -message-> B`
+- Sequence: `A -message-> B` or `A <-response- B`
 - Flowchart: `(Start) -> [Process] -> <Decision?> -yes-> (End)`
 - Bar chart: `chart: bar` then `Label: value` lines
 - ER diagram: `chart: er` then table definitions and `table1 1--* table2` relationships
 - Org chart: `chart: org` then indented hierarchy
 
-Full reference: see `node_modules/@diagrammo/dgmo/docs/language-reference.md`
+Full reference: `node_modules/@diagrammo/dgmo/docs/language-reference.md`
 
-Render with: `dgmo file.dgmo -o output.svg` or `dgmo file.dgmo -o url` for shareable link.
+Render with: `dgmo file.dgmo` (PNG) or `dgmo file.dgmo -o url` (shareable link).
 ```
 
+---
+
 ## Other AI Tools — Prompt Files
 
-DGMO ships prompt files for popular AI coding tools. These are included in the npm package:
+DGMO ships context files for popular AI coding tools, included in the npm package and auto-loaded when present in a project root.
 
 | File | Tool | How it works |
 |------|------|-------------|
@@ -84,42 +72,37 @@ DGMO ships prompt files for popular AI coding tools. These are included in the n
 | `.cursorrules` | Cursor | Auto-loaded when present in project root |
 | `.windsurfrules` | Windsurf | Auto-loaded when present in project root |
 
-### Setup
-
 Copy the relevant file into your project root:
 
 ```bash
-# From node_modules
+# From node_modules (if installed as a dependency)
 cp node_modules/@diagrammo/dgmo/.cursorrules .
 cp node_modules/@diagrammo/dgmo/.windsurfrules .
 mkdir -p .github && cp node_modules/@diagrammo/dgmo/.github/copilot-instructions.md .github/
 
-# Or from global install
+# From global npm install
 cp $(npm root -g)/@diagrammo/dgmo/.cursorrules .
 ```
 
-Each file contains a condensed DGMO syntax reference with examples for the most common diagram types, all 29 chart types listed, rendering commands, and common mistakes to avoid.
+Each file contains a condensed DGMO syntax reference with examples, all chart types listed, rendering commands, and common mistakes to avoid.
 
-## Rendering
+---
 
-If the `dgmo` CLI is installed, diagrams can be rendered:
+## Rendering commands
 
 ```bash
-# Install
-npm install -g @diagrammo/dgmo   # or: brew install diagrammo/dgmo/dgmo
-
-# Render
 dgmo diagram.dgmo                # PNG output
 dgmo diagram.dgmo -o output.svg  # SVG output
-dgmo diagram.dgmo -o url         # Shareable URL
-
-# AI-friendly JSON output
-dgmo diagram.dgmo -o output.svg --json
-dgmo --chart-types --json         # List all chart types
+dgmo diagram.dgmo -o url         # Shareable diagrammo.app URL
+dgmo diagram.dgmo -o url --copy  # URL copied to clipboard
+dgmo --chart-types               # List all supported chart types
+dgmo --chart-types --json        # Machine-readable chart type list
 ```
 
+---
+
 ## Supported chart types
 
 Run `dgmo --chart-types` for the full list, or see `docs/language-reference.md`.
 
-32 types: bar, line, area, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, state, class, er, org, kanban, c4, initiative-status, sitemap, infra.
+29 types: bar, line, area, multi-line, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, class, er, org, kanban, c4, initiative-status, infra.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
     "dist",
     "src",
     "docs",
-    ".claude/skills",
+    ".claude/commands",
     ".github/copilot-instructions.md",
     ".cursorrules",
     ".windsurfrules"
@@ -39,7 +39,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "gallery": "pnpm build && node scripts/generate-gallery.mjs",
-    "check:duplication": "jscpd ./src"
+    "check:duplication": "jscpd ./src",
+    "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\""
   },
   "dependencies": {
     "@dagrejs/dagre": "^2.0.4",

package/src/c4/layout.ts

@@ -109,17 +109,31 @@ const LEGEND_CAPSULE_PAD = 4;
 // Post-Layout Crossing Reduction
 // ============================================================
 
+interface NodeGeometry {
+  y: number;
+  width: number;
+  height: number;
+}
+
+// Large penalty per edge-node collision — dominates the distance term so the
+// sifter strongly prefers orderings where edges don't pass through other nodes.
+const EDGE_NODE_COLLISION_WEIGHT = 5000;
+
 /**
  * Compute penalty for an edge ordering. Uses degree-weighted edge distance:
  * long edges to high-degree nodes are penalized more than to low-degree nodes.
  * This places shared/important nodes closer to their neighbors, reducing
  * visual edge congestion.
  *
+ * When nodeGeometry is provided, also adds a heavy penalty for each case where
+ * a straight-line edge bounding box overlaps another node — driving the sifter
+ * to prefer orderings that avoid edge-node collisions.
  */
 function computeEdgePenalty(
   edgeList: { source: string; target: string }[],
   nodePositions: Map<string, number>,
-  degrees: Map<string, number>
+  degrees: Map<string, number>,
+  nodeGeometry?: Map<string, NodeGeometry>
 ): number {
   let penalty = 0;
 
@@ -135,6 +149,48 @@ function computeEdgePenalty(
     penalty += dist * weight;
   }
 
+  // Edge-node collision penalty: for each edge A→B, check if any other node C
+  // has its bounding box inside the straight-line bounding box of the edge.
+  // Uses x from nodePositions (updated per permutation) and y/size from nodeGeometry.
+  if (nodeGeometry) {
+    for (const edge of edgeList) {
+      const geomA = nodeGeometry.get(edge.source);
+      const geomB = nodeGeometry.get(edge.target);
+      if (!geomA || !geomB) continue;
+
+      const ax = nodePositions.get(edge.source) ?? 0;
+      const bx = nodePositions.get(edge.target) ?? 0;
+      const ay = geomA.y;
+      const by = geomB.y;
+
+      // Skip edges within the same rank — they have no vertical span to check
+      if (ay === by) continue;
+
+      const edgeMinX = Math.min(ax, bx);
+      const edgeMaxX = Math.max(ax, bx);
+      const edgeMinY = Math.min(ay, by);
+      const edgeMaxY = Math.max(ay, by);
+
+      for (const [name, geomC] of nodeGeometry) {
+        if (name === edge.source || name === edge.target) continue;
+        const cx = nodePositions.get(name) ?? 0;
+        const cy = geomC.y;
+        const hw = geomC.width / 2;
+        const hh = geomC.height / 2;
+
+        // AABB overlap: node C's box intersects the edge's straight-line bounding box
+        if (
+          cx + hw > edgeMinX &&
+          cx - hw < edgeMaxX &&
+          cy + hh > edgeMinY &&
+          cy - hh < edgeMaxY
+        ) {
+          penalty += EDGE_NODE_COLLISION_WEIGHT;
+        }
+      }
+    }
+  }
+
   return penalty;
 }
 
@@ -160,6 +216,13 @@ function reduceCrossings(
     degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + 1);
   }
 
+  // Build geometry map for edge-node collision scoring
+  const nodeGeometry = new Map<string, NodeGeometry>();
+  for (const name of g.nodes()) {
+    const pos = g.node(name);
+    if (pos) nodeGeometry.set(name, { y: pos.y, width: pos.width, height: pos.height });
+  }
+
   // Group nodes by rank
   const rankMap = new Map<number, string[]>();
   for (const name of g.nodes()) {
@@ -216,7 +279,7 @@ function reduceCrossings(
       }
 
       // Current penalty
-      const currentPenalty = computeEdgePenalty(edgeList, basePositions, degrees);
+      const currentPenalty = computeEdgePenalty(edgeList, basePositions, degrees, nodeGeometry);
 
       // Try permutations (feasible for partition sizes ≤ 8)
       let bestPerm = [...partition];
@@ -229,7 +292,7 @@ function reduceCrossings(
           for (let i = 0; i < perm.length; i++) {
             testPositions.set(perm[i]!, xSlots[i]!);
           }
-          const penalty = computeEdgePenalty(edgeList, testPositions, degrees);
+          const penalty = computeEdgePenalty(edgeList, testPositions, degrees, nodeGeometry);
           if (penalty < bestPenalty) {
             bestPenalty = penalty;
             bestPerm = [...perm];
@@ -248,14 +311,14 @@ function reduceCrossings(
             for (let k = 0; k < workingOrder.length; k++) {
               testPositions.set(workingOrder[k]!, xSlots[k]!);
             }
-            const before = computeEdgePenalty(edgeList, testPositions, degrees);
+            const before = computeEdgePenalty(edgeList, testPositions, degrees, nodeGeometry);
 
             [workingOrder[i], workingOrder[i + 1]] = [workingOrder[i + 1]!, workingOrder[i]!];
             const testPositions2 = new Map(basePositions);
             for (let k = 0; k < workingOrder.length; k++) {
               testPositions2.set(workingOrder[k]!, xSlots[k]!);
             }
-            const after = computeEdgePenalty(edgeList, testPositions2, degrees);
+            const after = computeEdgePenalty(edgeList, testPositions2, degrees, nodeGeometry);
 
             if (after < before) {
               improved = true;

package/src/cli.ts

@@ -1,6 +1,8 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { resolve, basename, extname } from 'node:path';
+import { homedir } from 'node:os';
+import { resolve, join, basename, extname } from 'node:path';
+import { createInterface } from 'node:readline';
 import { Resvg } from '@resvg/resvg-js';
 import { render } from './render';
 import { parseDgmo, getAllChartTypes } from './dgmo-router';
@@ -57,6 +59,84 @@ const CHART_TYPE_DESCRIPTIONS: Record<string, string> = {
   infra: 'Infra chart — infrastructure traffic flow with rps computation',
 };
 
+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 that renders \`.dgmo\` diagram files to PNG, SVG, or shareable URLs. Diagrams are written in a plain-text DSL.
+
+## 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>\` — \`nord\` (default), \`solarized\`, \`catppuccin\`, \`rose-pine\`, \`gruvbox\`, \`tokyo-night\`, \`one-dark\`, \`bold\`
+- \`--copy\` — copy the URL to clipboard (use with \`-o url\`)
+- \`--no-branding\` — omit diagrammo.app branding from exports
+- \`--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 |
+| \`class\` | UML class hierarchies |
+| \`er\` | Database schemas |
+| \`org\` | Hierarchical tree structures |
+| \`kanban\` | Task / workflow columns |
+| \`c4\` | System architecture (context → container → component → deployment) |
+| \`initiative-status\` | Project roadmap with dependency tracking |
+
+## Your Workflow
+
+When the user asks you to create or edit a diagram:
+
+1. **Write or edit the \`.dgmo\` file** with the appropriate chart type and data.
+2. **Render it** with \`dgmo <file>.dgmo -o <file>.png\` to verify it produces output without errors.
+3. **Show the user** what was created and suggest a shareable URL with \`dgmo <file>.dgmo -o url --copy\` if they want to share it.
+
+When the user asks for a **shareable link**, run:
+\`\`\`
+dgmo <file>.dgmo -o url --copy
+\`\`\`
+
+## Getting Syntax Help
+
+Run \`dgmo --chart-types\` to list types. For detailed syntax of a specific chart type, the best reference is the diagrammo.app documentation or existing \`.dgmo\` files in the project.
+
+## Tips
+
+- Default theme is \`light\` and default palette is \`nord\` — ask the user if they have a preference before rendering a final export.
+- For C4 diagrams, use \`--c4-level\` to drill from context → containers → components → deployment.
+- Stdin mode is useful for quick one-off renders: \`echo "..." | dgmo -o out.png\`
+`;
+
 function printHelp(): void {
   console.log(`Usage: dgmo <input> [options]
        cat input.dgmo | dgmo [options]
@@ -78,6 +158,7 @@ Options:
   --copy               Copy URL to clipboard (only with -o url)
   --json               Output structured JSON to stdout
   --chart-types        List all supported chart types
+  --install-claude-skill  Install the dgmo Claude Code skill to ~/.claude/commands/
   --help               Show this help
   --version            Show version`);
 }
@@ -100,6 +181,7 @@ function parseArgs(argv: string[]): {
   copy: boolean;
   json: boolean;
   chartTypes: boolean;
+  installClaudeSkill: boolean;
   c4Level: 'context' | 'containers' | 'components' | 'deployment';
   c4System: string | undefined;
   c4Container: string | undefined;
@@ -116,6 +198,7 @@ function parseArgs(argv: string[]): {
     copy: false,
     json: false,
     chartTypes: false,
+    installClaudeSkill: false,
     c4Level: 'context' as 'context' | 'containers' | 'components' | 'deployment',
     c4System: undefined as string | undefined,
     c4Container: undefined as string | undefined,
@@ -185,6 +268,9 @@ function parseArgs(argv: string[]): {
     } else if (arg === '--chart-types') {
       result.chartTypes = true;
       i++;
+    } else if (arg === '--install-claude-skill') {
+      result.installClaudeSkill = true;
+      i++;
     } else if (arg === '--copy') {
       result.copy = true;
       i++;
@@ -288,6 +374,42 @@ async function main(): Promise<void> {
     return;
   }
 
+  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.');
+    return;
+  }
+
   // Determine input source
   let content: string;
   let inputBasename: string | undefined;

package/src/er/classify.ts

@@ -0,0 +1,206 @@
+// ============================================================
+// ER Diagram Entity Classification
+// ============================================================
+//
+// Classifies each ER entity into a structural role using heuristics
+// derived from column constraints, FK patterns, relationship in-degree,
+// and naming conventions.
+//
+// Only used when no explicit colors or tag groups are defined.
+
+import type { ERTable, ERRelationship } from './types';
+import type { PaletteColors } from '../palettes/types';
+
+export type EntityRole =
+  | 'core'
+  | 'dependent'
+  | 'junction'
+  | 'ambiguous'
+  | 'lookup'
+  | 'hub'
+  | 'self-referential'
+  | 'unclassified';
+
+/** Maps each role to a key in PaletteColors['colors'] */
+export const ROLE_COLORS: Record<EntityRole, keyof PaletteColors['colors']> = {
+  core: 'green',
+  dependent: 'blue',
+  junction: 'red',
+  ambiguous: 'purple',
+  lookup: 'yellow',
+  hub: 'orange',
+  'self-referential': 'teal',
+  unclassified: 'gray',
+};
+
+/** Human-readable legend labels per role */
+export const ROLE_LABELS: Record<EntityRole, string> = {
+  core: 'Core entity',
+  dependent: 'Dependent',
+  junction: 'Junction / M:M',
+  ambiguous: 'Bridge',
+  lookup: 'Lookup / Reference',
+  hub: 'Hub',
+  'self-referential': 'Self-referential',
+  unclassified: 'Unclassified',
+};
+
+/** Stable display order for the semantic legend */
+export const ROLE_ORDER: EntityRole[] = [
+  'core',
+  'dependent',
+  'junction',
+  'ambiguous',
+  'lookup',
+  'hub',
+  'self-referential',
+  'unclassified',
+];
+
+const LOOKUP_NAME_SUFFIXES = ['_type', '_status', '_code', '_category'];
+
+/**
+ * Classify each ER entity into a structural role.
+ *
+ * Returns a Map of tableId → EntityRole.
+ * Pure logic — no palette or DOM dependencies.
+ */
+export function classifyEREntities(
+  tables: ERTable[],
+  relationships: ERRelationship[]
+): Map<string, EntityRole> {
+  const result = new Map<string, EntityRole>();
+  if (tables.length === 0) return result;
+
+  // ── Pre-compute graph metrics ─────────────────────────────────────────────
+
+  // indegreeMap: how many other tables have FK references pointing to this table.
+  // A table's indegree increments when it is on the exclusive '1' side of a 1:* or 1:?
+  // relationship. 1:1 relationships are skipped on both sides to avoid double-counting.
+  const indegreeMap: Record<string, number> = {};
+  for (const t of tables) indegreeMap[t.id] = 0;
+  for (const rel of relationships) {
+    if (rel.source === rel.target) continue; // skip self-loops
+    if (rel.cardinality.from === '1' && rel.cardinality.to !== '1') {
+      indegreeMap[rel.source] = (indegreeMap[rel.source] ?? 0) + 1;
+    }
+    if (rel.cardinality.to === '1' && rel.cardinality.from !== '1') {
+      indegreeMap[rel.target] = (indegreeMap[rel.target] ?? 0) + 1;
+    }
+  }
+
+  // mmParticipants: tables with '*' cardinality connecting to 2+ distinct other tables.
+  // Catches wide junction tables (e.g. with surrogate PKs) that the FK-ratio alone misses.
+  const tableStarNeighbors = new Map<string, Set<string>>();
+  for (const rel of relationships) {
+    if (rel.source === rel.target) continue;
+    if (rel.cardinality.from === '*') {
+      if (!tableStarNeighbors.has(rel.source)) tableStarNeighbors.set(rel.source, new Set());
+      tableStarNeighbors.get(rel.source)!.add(rel.target);
+    }
+    if (rel.cardinality.to === '*') {
+      if (!tableStarNeighbors.has(rel.target)) tableStarNeighbors.set(rel.target, new Set());
+      tableStarNeighbors.get(rel.target)!.add(rel.source);
+    }
+  }
+  const mmParticipants = new Set<string>();
+  for (const [id, neighbors] of tableStarNeighbors) {
+    if (neighbors.size >= 2) mmParticipants.add(id);
+  }
+
+  // Hub outlier statistics
+  const indegreeValues = Object.values(indegreeMap);
+  const mean = indegreeValues.reduce((a, b) => a + b, 0) / indegreeValues.length;
+  const variance = indegreeValues.reduce((a, b) => a + (b - mean) ** 2, 0) / indegreeValues.length;
+  const stddev = Math.sqrt(variance);
+
+  // Median indegree (for lookup detection: table must be referenced above-median)
+  const sorted = [...indegreeValues].sort((a, b) => a - b);
+  const median =
+    sorted.length % 2 === 0
+      ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+      : sorted[Math.floor(sorted.length / 2)];
+
+  // ── Per-table classification ──────────────────────────────────────────────
+
+  for (const table of tables) {
+    const id = table.id;
+    const cols = table.columns;
+    const fkCols = cols.filter((c) => c.constraints.includes('fk'));
+    const pkFkCols = cols.filter(
+      (c) => c.constraints.includes('pk') && c.constraints.includes('fk')
+    );
+    const fkCount = fkCols.length;
+    const fkRatio = cols.length === 0 ? 0 : fkCount / cols.length;
+    const indegree = indegreeMap[id] ?? 0;
+    const nameLower = table.name.toLowerCase();
+
+    // External relationships (exclude self-loops)
+    const externalRels = relationships.filter(
+      (r) => (r.source === id || r.target === id) && r.source !== r.target
+    );
+    const hasSelfRef = relationships.some((r) => r.source === id && r.target === id);
+
+    // Distinct external tables this table relates to
+    const externalTargets = new Set<string>();
+    for (const rel of externalRels) {
+      externalTargets.add(rel.source === id ? rel.target : rel.source);
+    }
+
+    // ── Decision tree (priority order) ─────────────────────────────────────
+
+    // 1. Self-referential: has a self-loop relationship AND no external relationships
+    if (hasSelfRef && externalRels.length === 0) {
+      result.set(id, 'self-referential');
+      continue;
+    }
+
+    // 2. Junction: any one of three signals qualifies.
+    //    Inheritance exception: composite PK FKs all pointing to a single parent → skip ratio signal.
+    const isInheritancePattern = pkFkCols.length >= 2 && externalTargets.size === 1;
+    const junctionByRatio = fkRatio >= 0.6 && !isInheritancePattern;
+    const junctionByCompositePk = pkFkCols.length >= 2 && externalTargets.size >= 2;
+    const junctionByMm = mmParticipants.has(id);
+    if (junctionByRatio || junctionByCompositePk || junctionByMm) {
+      result.set(id, 'junction');
+      continue;
+    }
+
+    // 3. Ambiguous: FK ratio 0.4–0.59, no composite PK FKs, not M:M participant
+    if (fkRatio >= 0.4 && fkRatio < 0.6 && pkFkCols.length < 2 && !mmParticipants.has(id)) {
+      result.set(id, 'ambiguous');
+      continue;
+    }
+
+    // 4. Lookup: naming convention match + structural guards
+    //    Naming only applies when cols ≤ 6 AND fkCount ≤ 1; structure overrides for larger tables.
+    const nameMatchesLookup = LOOKUP_NAME_SUFFIXES.some((s) => nameLower.endsWith(s));
+    if (nameMatchesLookup && cols.length <= 6 && fkCount <= 1 && indegree > median) {
+      result.set(id, 'lookup');
+      continue;
+    }
+
+    // 5. Hub: in-degree outlier in a schema of ≥ 6 tables.
+    //    Dual condition: > mean + 1.5σ AND ≥ 2× mean (guards against near-zero mean edge cases).
+    if (
+      tables.length >= 6 &&
+      indegree > 0 &&
+      indegree > mean + 1.5 * stddev &&
+      indegree >= 2 * mean
+    ) {
+      result.set(id, 'hub');
+      continue;
+    }
+
+    // 6. Dependent: has FK columns
+    if (fkCount > 0) {
+      result.set(id, 'dependent');
+      continue;
+    }
+
+    // 7. Core: no FK columns (always true at this point)
+    result.set(id, 'core');
+  }
+
+  return result;
+}