@markdy/mcp-server 1.0.28 → 1.0.30

package/dist/index.js

@@ -717,6 +717,289 @@ function canonicalNodeKind(kind) {
   return NODE_ALIASES[kind] ?? kind;
 }
 
+// ../core/src/themes.ts
+var ROLE_COLORS = {
+  compute: "#38bdf8",
+  code: "#38bdf8",
+  client: "#f59e0b",
+  data: "#22c55e",
+  messaging: "#a78bfa",
+  network: "#60a5fa",
+  platform: "#c084fc",
+  security: "#fb7185",
+  delivery: "#facc15",
+  observability: "#2dd4bf",
+  flow: "#e879f9",
+  distributed: "#94a3b8"
+};
+var EDGE_COLORS = {
+  request: "#38bdf8",
+  response: "#a78bfa",
+  event: "#f59e0b",
+  dependency: "#64748b"
+};
+var THEMES = {
+  midnight: {
+    name: "midnight",
+    canvas: "#070d18",
+    surface: "#0e1a2c",
+    surfaceRaised: "#152538",
+    border: "#28384f",
+    text: "#f4f7fb",
+    textMuted: "#93a4bb",
+    gridMinor: "rgba(148, 163, 184, 0.10)",
+    gridMajor: "rgba(148, 163, 184, 0.16)",
+    vignette: "rgba(2, 6, 23, 0.7)",
+    accent: "#38bdf8",
+    nodeSurface: "#111f33",
+    nodeSurfaceRaised: "#1a2c44",
+    hairline: "rgba(148, 163, 184, 0.16)",
+    shadow: "rgba(2, 6, 23, 0.6)",
+    labelPlate: "#0f1c2e",
+    roles: { ...ROLE_COLORS },
+    edges: { ...EDGE_COLORS }
+  },
+  paper: {
+    name: "paper",
+    canvas: "#f6f8fc",
+    surface: "#ffffff",
+    surfaceRaised: "#f0f4f9",
+    border: "#cbd5e1",
+    text: "#0f1c2e",
+    textMuted: "#475569",
+    gridMinor: "rgba(15, 23, 42, 0.06)",
+    gridMajor: "rgba(15, 23, 42, 0.10)",
+    vignette: "rgba(226, 232, 240, 0.6)",
+    accent: "#0284c7",
+    nodeSurface: "#ffffff",
+    nodeSurfaceRaised: "#f7fafd",
+    hairline: "rgba(15, 23, 42, 0.10)",
+    shadow: "rgba(15, 23, 42, 0.14)",
+    labelPlate: "#ffffff",
+    roles: { ...ROLE_COLORS },
+    edges: { ...EDGE_COLORS },
+    series: ["#7c8f6f", "#5e7a9b", "#b8915a", "#9c6b50", "#6e6479"]
+  },
+  blueprint: {
+    name: "blueprint",
+    canvas: "#0a1a3a",
+    surface: "#10214a",
+    surfaceRaised: "#182c5c",
+    border: "#2c477f",
+    text: "#eaf1ff",
+    textMuted: "#9fb6e0",
+    gridMinor: "rgba(125, 170, 255, 0.12)",
+    gridMajor: "rgba(125, 170, 255, 0.2)",
+    vignette: "rgba(4, 12, 34, 0.72)",
+    accent: "#5ba3ff",
+    nodeSurface: "#122452",
+    nodeSurfaceRaised: "#1b3068",
+    hairline: "rgba(125, 170, 255, 0.18)",
+    shadow: "rgba(3, 10, 30, 0.6)",
+    labelPlate: "#10214a",
+    roles: { ...ROLE_COLORS },
+    edges: { ...EDGE_COLORS }
+  },
+  graphite: {
+    name: "graphite",
+    canvas: "#111317",
+    surface: "#191c22",
+    surfaceRaised: "#22262e",
+    border: "#343a45",
+    text: "#eef1f5",
+    textMuted: "#9aa3b1",
+    gridMinor: "rgba(160, 170, 185, 0.08)",
+    gridMajor: "rgba(160, 170, 185, 0.14)",
+    vignette: "rgba(0, 0, 0, 0.6)",
+    accent: "#2dd4bf",
+    nodeSurface: "#1c2028",
+    nodeSurfaceRaised: "#262b34",
+    hairline: "rgba(160, 170, 185, 0.14)",
+    shadow: "rgba(0, 0, 0, 0.55)",
+    labelPlate: "#191c22",
+    roles: { ...ROLE_COLORS },
+    edges: { ...EDGE_COLORS }
+  },
+  editorial: {
+    name: "editorial",
+    canvas: "#fafafa",
+    surface: "#ffffff",
+    surfaceRaised: "#f8fafc",
+    border: "#e2e8f0",
+    text: "#0f172a",
+    textMuted: "#475569",
+    paper: "#fafafa",
+    ink: "#0f172a",
+    muted: "#6b7280",
+    rule: "#e2e8f0",
+    soft: "#94a3b8",
+    link: "#047857",
+    gridMinor: "rgba(15, 23, 42, 0.06)",
+    gridMajor: "rgba(15, 23, 42, 0.10)",
+    vignette: "rgba(226, 232, 240, 0.5)",
+    accent: "#047857",
+    accentTint: "rgba(4, 120, 87, 0.08)",
+    nodeSurface: "#ffffff",
+    nodeSurfaceRaised: "#f8fafc",
+    hairline: "#e2e8f0",
+    shadow: "rgba(15, 23, 42, 0.08)",
+    labelPlate: "#fafafa",
+    flatCards: true,
+    roles: { ...ROLE_COLORS, compute: "#0f172a", client: "#64748b", data: "#64748b" },
+    edges: {
+      request: "#334155",
+      response: "#64748b",
+      event: "#047857",
+      dependency: "#94a3b8"
+    },
+    fonts: {
+      title: "Georgia, Times New Roman, serif",
+      nodeName: "ui-sans-serif, system-ui, sans-serif",
+      mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    },
+    radiusMd: 6,
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 },
+    series: ["#7c8f6f", "#5e7a9b", "#b8915a", "#9c6b50", "#6e6479"]
+  },
+  nebula: {
+    name: "nebula",
+    canvas: "#090b1a",
+    surface: "#111735",
+    surfaceRaised: "#1a2250",
+    border: "rgba(167, 139, 250, 0.28)",
+    text: "#eef2ff",
+    textMuted: "#a5b4fc",
+    paper: "#090b1a",
+    ink: "#eef2ff",
+    muted: "#818cf8",
+    rule: "rgba(129, 140, 248, 0.32)",
+    soft: "#67e8f9",
+    link: "#67e8f9",
+    gridMinor: "rgba(129, 140, 248, 0.08)",
+    gridMajor: "rgba(103, 232, 249, 0.16)",
+    vignette: "rgba(3, 5, 18, 0.86)",
+    accent: "#c4b5fd",
+    accentTint: "rgba(196, 181, 253, 0.14)",
+    nodeSurface: "#111735",
+    nodeSurfaceRaised: "#202a5b",
+    hairline: "rgba(196, 181, 253, 0.32)",
+    shadow: "rgba(3, 5, 18, 0.72)",
+    labelPlate: "#12183b",
+    roles: {
+      ...ROLE_COLORS,
+      compute: "#67e8f9",
+      client: "#f9a8d4",
+      data: "#a7f3d0",
+      network: "#93c5fd",
+      flow: "#c4b5fd"
+    },
+    edges: {
+      request: "#67e8f9",
+      response: "#c4b5fd",
+      event: "#f9a8d4",
+      dependency: "#818cf8"
+    },
+    fonts: {
+      title: "Georgia, Times New Roman, serif",
+      nodeName: "ui-sans-serif, system-ui, sans-serif",
+      mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    },
+    radiusMd: 12,
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 }
+  },
+  terminal: {
+    name: "terminal",
+    canvas: "#0a0a0a",
+    surface: "#141414",
+    surfaceRaised: "#1e1e1e",
+    border: "#2b2b2b",
+    text: "#f5f5f5",
+    textMuted: "#9a9a9a",
+    paper: "#141414",
+    ink: "#f5f5f5",
+    muted: "#9a9a9a",
+    rule: "#2b2b2b",
+    soft: "#5c5c5c",
+    link: "#ff5a36",
+    gridMinor: "rgba(255, 255, 255, 0.04)",
+    gridMajor: "rgba(255, 255, 255, 0.08)",
+    vignette: "rgba(0, 0, 0, 0.8)",
+    accent: "#ff5a36",
+    accentTint: "rgba(255, 90, 54, 0.15)",
+    nodeSurface: "#141414",
+    nodeSurfaceRaised: "#222222",
+    hairline: "#333333",
+    shadow: "rgba(0, 0, 0, 0.8)",
+    labelPlate: "#141414",
+    flatCards: true,
+    roles: {
+      ...ROLE_COLORS,
+      compute: "#ff5a36",
+      client: "#f5f5f5",
+      data: "#9a9a9a",
+      network: "#38bdf8"
+    },
+    edges: {
+      request: "#ff5a36",
+      response: "#9a9a9a",
+      event: "#facc15",
+      dependency: "#5c5c5c"
+    },
+    fonts: {
+      title: "ui-monospace, SFMono-Regular, Menlo, monospace",
+      nodeName: "ui-monospace, SFMono-Regular, Menlo, monospace",
+      mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    },
+    radiusMd: 6,
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 }
+  },
+  sketchy: {
+    name: "sketchy",
+    canvas: "#fbfaf8",
+    surface: "#ffffff",
+    surfaceRaised: "#f6f3eb",
+    border: "#2d3142",
+    text: "#2d3142",
+    textMuted: "#4f5d75",
+    paper: "#fbfaf8",
+    ink: "#2d3142",
+    muted: "#4f5d75",
+    rule: "rgba(45, 49, 66, 0.18)",
+    soft: "#7a8399",
+    link: "#eb6c36",
+    gridMinor: "rgba(45, 49, 66, 0.05)",
+    gridMajor: "rgba(45, 49, 66, 0.08)",
+    vignette: "rgba(0, 0, 0, 0.06)",
+    accent: "#eb6c36",
+    accentTint: "rgba(235, 108, 54, 0.10)",
+    nodeSurface: "#ffffff",
+    nodeSurfaceRaised: "#fbfaf8",
+    hairline: "rgba(45, 49, 66, 0.35)",
+    shadow: "rgba(45, 49, 66, 0.08)",
+    labelPlate: "#ffffff",
+    flatCards: true,
+    roles: {
+      ...ROLE_COLORS,
+      compute: "#2d3142",
+      client: "#4f5d75",
+      data: "#4f5d75"
+    },
+    edges: {
+      request: "#2d3142",
+      response: "#4f5d75",
+      event: "#eb6c36",
+      dependency: "#7a8399"
+    },
+    fonts: {
+      title: "Georgia, Times New Roman, serif",
+      nodeName: "ui-sans-serif, system-ui, sans-serif",
+      mono: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    },
+    radiusMd: 4,
+    spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 40 }
+  }
+};
+
 // ../core/src/parser.ts
 var ParseError = class extends Error {
   line;
@@ -2074,56 +2357,1437 @@ function classifyTechnology(id, label = "") {
   };
 }
 
-// ../core/src/ai-healing.ts
-function analyzeAndBuildRepairPrompt(sourceCode) {
-  const syntaxErrors = [];
-  let ast = null;
+// ../core/src/syntax-diagnostics.ts
+function damerauLevenshteinDistance(a, b) {
+  const al = a.length;
+  const bl = b.length;
+  if (al === 0) return bl;
+  if (bl === 0) return al;
+  const matrix = [];
+  for (let i = 0; i <= al; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= bl; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= al; i++) {
+    for (let j = 1; j <= bl; j++) {
+      const cost = a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1;
+      let min = Math.min(
+        matrix[i - 1][j] + 1,
+        // deletion
+        matrix[i][j - 1] + 1,
+        // insertion
+        matrix[i - 1][j - 1] + cost
+        // substitution
+      );
+      if (i > 1 && j > 1 && a[i - 1].toLowerCase() === b[j - 2].toLowerCase() && a[i - 2].toLowerCase() === b[j - 1].toLowerCase()) {
+        min = Math.min(min, matrix[i - 2][j - 2] + cost);
+      }
+      matrix[i][j] = min;
+    }
+  }
+  return matrix[al][bl];
+}
+var COMMON_CONTRACTIONS = {
+  svc: "service",
+  srv: "service",
+  gw: "gateway",
+  db: "database",
+  app: "application",
+  msg: "message",
+  repo: "repository",
+  cfg: "config",
+  auth: "authenticator",
+  mgr: "manager",
+  fn: "function"
+};
+function splitIdentifierIntoTokens(s) {
+  return s.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_\-.]+/g, " ").toLowerCase().trim().split(/\s+/).filter(Boolean);
+}
+function expandContractions(s) {
+  const norm = s.toLowerCase().trim();
+  const tokens = splitIdentifierIntoTokens(s);
+  if (tokens.length === 0) return norm;
+  const expandedTokens = tokens.map((t) => COMMON_CONTRACTIONS[t] ?? t);
+  let res = expandedTokens.join("");
+  if (tokens.length === 1) {
+    for (const [k, v] of Object.entries(COMMON_CONTRACTIONS)) {
+      if (k.length >= 2 && norm.length > k.length + 2 && norm.endsWith(k)) {
+        res = norm.slice(0, -k.length) + v;
+        break;
+      }
+    }
+  }
+  return res;
+}
+function findClosestMatch(word, candidates, maxDistance = 4) {
+  const normalized = word.toLowerCase().trim();
+  if (!normalized || !/^[a-zA-Z_][\w.-]*$/.test(normalized)) return null;
+  const expandedWord = expandContractions(normalized);
+  let bestMatch = null;
+  let bestDistance = Infinity;
+  const wordConsonants = normalized.replace(/[aeiou_-]/g, "");
+  for (const candidate of candidates) {
+    const candNorm = candidate.toLowerCase().trim();
+    const expandedCand = expandContractions(candNorm);
+    if (candNorm === normalized || expandedCand === expandedWord) {
+      return { match: candidate, distance: 0 };
+    }
+    if (candNorm.startsWith(normalized) || normalized.startsWith(candNorm) || expandedCand.startsWith(expandedWord) || expandedWord.startsWith(expandedCand)) {
+      const dist2 = Math.abs(candNorm.length - normalized.length);
+      if (dist2 < bestDistance) {
+        bestDistance = dist2;
+        bestMatch = candidate;
+        continue;
+      }
+    }
+    if (wordConsonants.length >= 3) {
+      const candConsonants = candNorm.replace(/[aeiou_-]/g, "");
+      if (candConsonants.startsWith(wordConsonants) || wordConsonants.startsWith(candConsonants)) {
+        const dist2 = 1;
+        if (dist2 < bestDistance) {
+          bestDistance = dist2;
+          bestMatch = candidate;
+          continue;
+        }
+      }
+    }
+    const dist = Math.min(
+      damerauLevenshteinDistance(normalized, candNorm),
+      damerauLevenshteinDistance(expandedWord, expandedCand)
+    );
+    const dynamicMax = Math.max(2, Math.min(maxDistance, Math.floor(Math.max(candidate.length, word.length) * 0.5)));
+    if (dist <= dynamicMax && dist < bestDistance) {
+      bestDistance = dist;
+      bestMatch = candidate;
+    }
+  }
+  return bestMatch ? { match: bestMatch, distance: bestDistance } : null;
+}
+var TOP_LEVEL_KEYWORDS = [
+  "scene",
+  "layout",
+  "player",
+  "var",
+  "group",
+  "beat",
+  "style",
+  "pattern",
+  "edge",
+  "annotation",
+  "use"
+];
+var CUE_KEYWORDS = [
+  "show",
+  "hide",
+  "glow",
+  "focus",
+  "frame",
+  "use",
+  "pulse",
+  "highlight",
+  "emphasize"
+];
+var LAYOUT_DIRECTIONS = ["LR", "RL", "TB", "BT"];
+var THEME_NAMES = Object.keys(THEMES);
+var ALL_NODE_KINDS = Array.from(
+  /* @__PURE__ */ new Set([...Array.from(NODE_KINDS), ...Object.keys(NODE_ALIASES)])
+);
+var FOREIGN_SYNTAX_PATTERNS = [
+  {
+    type: "Mermaid",
+    pattern: /^\s*(graph\s+(TB|TD|BT|RL|LR)|flowchart\s+(TB|TD|BT|RL|LR)|classDiagram|sequenceDiagram|erDiagram|stateDiagram|pie\s+title|gitGraph)/i,
+    hint: `Mermaid syntax detected. Convert using 'transpile_to_markdy(source, format="mermaid")'.`
+  },
+  {
+    type: "PlantUML",
+    pattern: /^\s*(@startuml|@startmindmap|@startgantt|@startwbs)/i,
+    hint: "PlantUML syntax detected. Markdy uses declarative 'scene', node declarations, and 'beat' blocks."
+  },
+  {
+    type: "Graphviz DOT",
+    pattern: /^\s*(digraph|strict\s+digraph|graph)\s+\w*\s*\{/i,
+    hint: `Graphviz DOT syntax detected. Markdy uses 'scene', '<kind> <Id> ["Label"]', and 'beat' blocks.`
+  },
+  {
+    type: "D2",
+    pattern: /^\s*(direction\s*:|vars\s*:|classes\s*:)/i,
+    hint: "D2 syntax detected. Markdy uses 'layout LR|TB' and 'beat <id>:' blocks."
+  }
+];
+var INVALID_FLOW_OP_MAP = {
+  "-->": "->",
+  "->>": "->",
+  "==>": "->",
+  "<--": "<-",
+  "<<-": "<-",
+  "<==": "<-",
+  "~~>": "~>",
+  "~>>": "~>",
+  "---": "--",
+  "--->": "->",
+  "-.-": "--",
+  "-..->": "~>",
+  ">--": "->",
+  ">-": "->"
+};
+function diagnoseMarkdyCode(code, options = {}) {
+  const issues = [];
+  const lines = code.replace(/\r\n/g, "\n").split("\n");
+  const declaredNodes = /* @__PURE__ */ new Set();
+  const referencedNodes = /* @__PURE__ */ new Set();
+  const checkArchitecture = options.checkArchitecture ?? true;
+  for (const foreign of FOREIGN_SYNTAX_PATTERNS) {
+    if (foreign.pattern.test(code)) {
+      issues.push({
+        line: 1,
+        severity: "error",
+        code: "FOREIGN_DIAGRAM_SYNTAX",
+        message: `${foreign.type} syntax detected instead of MarkdyScript.`,
+        snippet: lines.slice(0, 3).join("\n"),
+        suggestion: foreign.hint,
+        ruleExplanation: `MarkdyScript diagrams begin with 'scene [theme=paper layout=LR]', followed by node declarations ('<kind> <Id> ["Label"]') and dynamic 'beat' blocks.`
+      });
+      break;
+    }
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith("//") || line.startsWith("#")) continue;
+    const nodeMatch = line.match(/^(\w[\w.-]*)\s+(\w[\w.-]*)/);
+    if (nodeMatch) {
+      const head = nodeMatch[1].toLowerCase();
+      const id = nodeMatch[2];
+      if (!TOP_LEVEL_KEYWORDS.includes(head) && !CUE_KEYWORDS.includes(head) && !["show", "hide", "glow", "focus", "frame"].includes(head)) {
+        declaredNodes.add(id);
+      }
+    }
+  }
+  let insideBeat = false;
+  let insideGroup = false;
+  let insidePattern = false;
+  let beatIndent = 0;
+  for (let idx = 0; idx < lines.length; idx++) {
+    const rawLine = lines[idx];
+    const lineNo = idx + 1;
+    const trimmed = rawLine.trim();
+    if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("#")) {
+      continue;
+    }
+    const indent = rawLine.match(/^\s*/)?.[0].length ?? 0;
+    if (insideBeat && indent <= beatIndent && !trimmed.startsWith("&")) {
+      insideBeat = false;
+    }
+    if (insideGroup && indent === 0) {
+      insideGroup = false;
+    }
+    if (insidePattern && indent === 0) {
+      insidePattern = false;
+    }
+    const tokens = trimmed.split(/\s+/);
+    const firstWord = tokens[0];
+    const firstWordLower = firstWord.toLowerCase();
+    if (firstWordLower.startsWith("scen") || firstWordLower === "secne" || firstWordLower === "scence") {
+      if (firstWord !== "scene") {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "TYPO_KEYWORD",
+          message: `Unknown keyword '${firstWord}'. Did you mean 'scene'?`,
+          snippet: trimmed,
+          suggestion: `Replace '${firstWord}' with 'scene'.`,
+          didYouMean: "scene",
+          ruleExplanation: "Every Markdy diagram starts with a 'scene' directive: 'scene theme=paper width=1280 height=720'.",
+          fix: { original: firstWord, replacement: "scene" }
+        });
+      }
+      const themeMatch = trimmed.match(/\btheme=(\w+)/);
+      if (themeMatch) {
+        const themeVal = themeMatch[1].toLowerCase();
+        if (!THEME_NAMES.includes(themeVal)) {
+          const closeTheme = findClosestMatch(themeVal, THEME_NAMES);
+          issues.push({
+            line: lineNo,
+            severity: "warning",
+            code: "UNKNOWN_THEME_OR_PROPERTY",
+            message: `Unknown theme '${themeMatch[1]}'. Available themes: ${THEME_NAMES.join(", ")}.`,
+            snippet: trimmed,
+            suggestion: closeTheme ? `Use theme '${closeTheme.match}'.` : `Choose from: ${THEME_NAMES.join(", ")}.`,
+            didYouMean: closeTheme?.match,
+            ruleExplanation: "Supported themes: paper, editorial, midnight, blueprint, graphite, nebula, sketchy, terminal.",
+            fix: closeTheme ? { original: themeMatch[0], replacement: `theme=${closeTheme.match}` } : void 0
+          });
+        }
+      }
+      const layoutMatch = trimmed.match(/\blayout\s*=?\s*(\w+)/i);
+      if (layoutMatch) {
+        const layoutVal = layoutMatch[1].toUpperCase();
+        if (!LAYOUT_DIRECTIONS.includes(layoutVal)) {
+          issues.push({
+            line: lineNo,
+            severity: "warning",
+            code: "UNKNOWN_THEME_OR_PROPERTY",
+            message: `Invalid layout direction '${layoutMatch[1]}'. Must be one of: LR, RL, TB, BT.`,
+            snippet: trimmed,
+            suggestion: "Use layout LR (left-to-right) or TB (top-to-bottom).",
+            didYouMean: "LR",
+            ruleExplanation: "Layout directions must be LR (Left-to-Right), RL, TB (Top-to-Bottom), or BT.",
+            fix: { original: layoutMatch[0], replacement: "layout LR" }
+          });
+        }
+      }
+      continue;
+    }
+    if (firstWordLower === "layput" || firstWordLower === "layour" || firstWordLower === "layuot" || firstWordLower === "directon") {
+      issues.push({
+        line: lineNo,
+        severity: "error",
+        code: "TYPO_KEYWORD",
+        message: `Typo in layout directive '${firstWord}'. Did you mean 'layout'?`,
+        snippet: trimmed,
+        suggestion: `Change '${firstWord}' to 'layout'.`,
+        didYouMean: "layout",
+        ruleExplanation: "Use 'layout LR' or 'layout TB' to define the diagram orientation.",
+        fix: { original: firstWord, replacement: "layout" }
+      });
+      continue;
+    }
+    if (firstWordLower.startsWith("beat") || firstWordLower === "bea" || firstWordLower === "beats") {
+      insideBeat = true;
+      beatIndent = indent;
+      if (firstWord !== "beat") {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "TYPO_KEYWORD",
+          message: `Unknown keyword '${firstWord}'. Did you mean 'beat'?`,
+          snippet: trimmed,
+          suggestion: `Replace '${firstWord}' with 'beat'.`,
+          didYouMean: "beat",
+          ruleExplanation: `Storyboard narrative steps start with 'beat <id> ["Caption"]:' followed by indented cues.`,
+          fix: { original: firstWord, replacement: "beat" }
+        });
+      }
+      if (!trimmed.endsWith(":") && !trimmed.endsWith("{")) {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "MISSING_COLON",
+          message: `Missing colon ':' at the end of beat header.`,
+          snippet: trimmed,
+          suggestion: `Append ':' to the beat declaration: '${trimmed}:'`,
+          ruleExplanation: "Every beat block must end with a colon ':', e.g. `beat checkout \"Process Payment\":`.",
+          fix: { original: trimmed, replacement: `${trimmed}:` }
+        });
+      }
+      continue;
+    }
+    if (firstWordLower === "group" || firstWordLower === "groop" || firstWordLower === "grp") {
+      insideGroup = true;
+      if (firstWord !== "group") {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "TYPO_KEYWORD",
+          message: `Typo in group keyword '${firstWord}'. Did you mean 'group'?`,
+          snippet: trimmed,
+          suggestion: `Change '${firstWord}' to 'group'.`,
+          didYouMean: "group",
+          fix: { original: firstWord, replacement: "group" }
+        });
+      }
+      if (!trimmed.includes(":")) {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "MISSING_COLON",
+          message: `Missing colon ':' in group definition.`,
+          snippet: trimmed,
+          suggestion: `Add a colon before group members: e.g. 'group <id> "Label": Node1 Node2'`,
+          ruleExplanation: 'Groups require a colon: `group clients "User Tier": WebApp MobileApp`.'
+        });
+      } else {
+        const colonIdx = trimmed.indexOf(":");
+        const membersRaw = trimmed.slice(colonIdx + 1).trim();
+        if (membersRaw) {
+          const members = membersRaw.split(/\s+/).filter((m) => m && !m.includes("=") && !m.startsWith("$") && /^[a-zA-Z_][\w.-]*$/.test(m));
+          for (const mem of members) {
+            referencedNodes.add(mem);
+            if (declaredNodes.size > 0 && !declaredNodes.has(mem)) {
+              const closest = findClosestMatch(mem, declaredNodes);
+              issues.push({
+                line: lineNo,
+                severity: "warning",
+                code: "UNDEFINED_NODE_REFERENCE",
+                message: `Group references undefined node '${mem}'.${closest ? ` Did you mean '${closest.match}'?` : ""}`,
+                snippet: trimmed,
+                suggestion: closest ? `Replace '${mem}' with declared node '${closest.match}'.` : `Ensure node '${mem}' is declared before adding it to a group.`,
+                didYouMean: closest?.match,
+                fix: closest ? { original: mem, replacement: closest.match } : void 0
+              });
+            }
+          }
+        }
+      }
+      continue;
+    }
+    if (firstWordLower === "annotation") {
+      const targetMatch = trimmed.match(/\btarget=([\w.-]+)/i);
+      if (targetMatch) {
+        const target = targetMatch[1];
+        referencedNodes.add(target);
+        if (declaredNodes.size > 0 && !declaredNodes.has(target)) {
+          const closest = findClosestMatch(target, declaredNodes);
+          issues.push({
+            line: lineNo,
+            severity: "warning",
+            code: "UNDEFINED_NODE_REFERENCE",
+            message: `Annotation targets undefined node '${target}'.${closest ? ` Did you mean '${closest.match}'?` : ""}`,
+            snippet: trimmed,
+            suggestion: closest ? `Replace target='${target}' with target='${closest.match}'.` : void 0,
+            didYouMean: closest?.match,
+            fix: closest ? { original: target, replacement: closest.match } : void 0
+          });
+        }
+      }
+      continue;
+    }
+    if (!insideBeat) {
+      const isCueWord = CUE_KEYWORDS.includes(firstWordLower) || firstWordLower === "shwo" || firstWordLower === "fram" || firstWordLower === "focsu" || firstWordLower === "gloww";
+      const isFlowLine = /(-->|->|<-|<--|~>|--)/.test(trimmed);
+      if (isCueWord || isFlowLine) {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "CUE_OUTSIDE_BEAT",
+          message: `Action cue or flow line '${trimmed}' found at top-level outside a 'beat' block.`,
+          snippet: trimmed,
+          suggestion: `Wrap this line inside an indented beat block:
+beat main "System Flow":
+  ${trimmed}`,
+          ruleExplanation: "In MarkdyScript, top-level code is reserved for Directives, Nodes, and Groups. Animated flow transitions and visual cues (show, hide, glow, frame, focus) must reside inside a 'beat <name>:' block."
+        });
+        continue;
+      }
+    }
+    for (const [invalidOp, validOp] of Object.entries(INVALID_FLOW_OP_MAP)) {
+      if (trimmed.includes(invalidOp)) {
+        issues.push({
+          line: lineNo,
+          severity: "error",
+          code: "INVALID_FLOW_OPERATOR",
+          message: `Invalid flow operator '${invalidOp}'. Did you mean '${validOp}'?`,
+          snippet: trimmed,
+          suggestion: `Replace '${invalidOp}' with '${validOp}'.`,
+          didYouMean: validOp,
+          ruleExplanation: "Markdy uses 4 clean flow operators: '->' (request/call), '<-' (response/return), '~>' (asynchronous/event), and '--' (static dependency).",
+          fix: { original: invalidOp, replacement: validOp }
+        });
+      }
+    }
+    if (!insideBeat && !insideGroup && !insidePattern) {
+      const match = trimmed.match(/^(\w[\w.-]*)\s+(\w[\w.-]*)(.*)$/);
+      if (match) {
+        const rawKind = match[1];
+        const rawKindLower = rawKind.toLowerCase();
+        const id = match[2];
+        const rest = match[3].trim();
+        if (!TOP_LEVEL_KEYWORDS.includes(rawKindLower)) {
+          const canonical = canonicalNodeKind(rawKindLower);
+          if (!NODE_KINDS.has(canonical)) {
+            const matchKind = findClosestMatch(rawKindLower, ALL_NODE_KINDS);
+            const resolvedKind = matchKind ? canonicalNodeKind(matchKind.match) : void 0;
+            issues.push({
+              line: lineNo,
+              severity: "error",
+              code: "TYPO_NODE_KIND",
+              message: `Unknown node kind '${rawKind}'.${resolvedKind ? ` Did you mean '${resolvedKind}'?` : ""}`,
+              snippet: trimmed,
+              suggestion: resolvedKind ? `Change '${rawKind}' to '${resolvedKind}': '${resolvedKind} ${id} ...'` : `Use a valid node kind: service, database, cache, gateway, browser, mobile, worker, cloud, queue, storage, cluster, etc.`,
+              didYouMean: resolvedKind,
+              ruleExplanation: "Markdy requires semantic node kinds (e.g. browser, gateway, service, database, cache, queue, worker, cloud, storage, pod, cluster).",
+              fix: resolvedKind ? { original: rawKind, replacement: resolvedKind } : void 0
+            });
+          }
+          if (rest && !rest.startsWith('"') && !rest.startsWith("style=") && !rest.startsWith("icon=")) {
+            const hasMultipleWords = rest.split(/\s+/).length > 1;
+            if (hasMultipleWords && !rest.includes("=")) {
+              issues.push({
+                line: lineNo,
+                severity: "error",
+                code: "UNQUOTED_STRING_LABEL",
+                message: `Unquoted multi-word label '${rest}'. String labels with spaces must be enclosed in double quotes.`,
+                snippet: trimmed,
+                suggestion: `Wrap the label in quotes: '${rawKind} ${id} "${rest}"'`,
+                ruleExplanation: 'String labels containing spaces must be enclosed in double quotes `"..."`.',
+                fix: { original: `${id} ${rest}`, replacement: `${id} "${rest}"` }
+              });
+            }
+          }
+          const quoteCount = (rest.match(/"/g) || []).length;
+          if (quoteCount % 2 !== 0) {
+            issues.push({
+              line: lineNo,
+              severity: "error",
+              code: "UNTERMINATED_STRING",
+              message: `Unterminated string quote in node declaration.`,
+              snippet: trimmed,
+              suggestion: `Add closing quote: '${trimmed}"'`,
+              fix: { original: trimmed, replacement: `${trimmed}"` }
+            });
+          }
+        }
+      }
+    }
+    if (insideBeat) {
+      if (trimmed.includes("->") || trimmed.includes("<-") || trimmed.includes("~>") || trimmed.includes("--")) {
+        const cleanFlow = trimmed.replace(/"[^"]*"/g, " ");
+        const flowTokens = cleanFlow.split(/->|<-|~>|--|&|\s+/).filter(Boolean);
+        for (const token of flowTokens) {
+          if (token.includes("=") || token.startsWith("$") || !/^[a-zA-Z_][\w.-]*$/.test(token) || ["and", "show", "hide", "glow", "focus", "frame", "pulse", "use"].includes(token.toLowerCase())) {
+            continue;
+          }
+          referencedNodes.add(token);
+          if (declaredNodes.size > 0 && !declaredNodes.has(token)) {
+            const closest = findClosestMatch(token, declaredNodes);
+            issues.push({
+              line: lineNo,
+              severity: "error",
+              code: "UNDEFINED_NODE_REFERENCE",
+              message: `Flow references undefined node '${token}'.${closest ? ` Did you mean '${closest.match}'?` : ""}`,
+              snippet: trimmed,
+              suggestion: closest ? `Replace '${token}' with declared node '${closest.match}'.` : `Declare node '${token}' at top of diagram before referencing it.`,
+              didYouMean: closest?.match,
+              ruleExplanation: "All nodes used in flow transitions must be declared beforehand (e.g. `service ${token}`).",
+              fix: closest ? { original: token, replacement: closest.match } : void 0
+            });
+          }
+        }
+      }
+      const cueMatch = trimmed.match(/^(show|hide|glow|focus|frame)\s+(.+)$/i);
+      if (cueMatch) {
+        const cueKind = cueMatch[1].toLowerCase();
+        const targetsRaw = cueMatch[2].replace(/\b\w+=[^\s]+/g, "").trim();
+        const targets = targetsRaw.split(/\s+/).filter((t) => t && !t.startsWith("$") && !t.startsWith('"') && /^[a-zA-Z_][\w.-]*$/.test(t));
+        for (const target of targets) {
+          referencedNodes.add(target);
+          if (declaredNodes.size > 0 && !declaredNodes.has(target)) {
+            const closest = findClosestMatch(target, declaredNodes);
+            issues.push({
+              line: lineNo,
+              severity: "warning",
+              code: "UNDEFINED_NODE_REFERENCE",
+              message: `${cueKind} cue targets undefined node '${target}'.${closest ? ` Did you mean '${closest.match}'?` : ""}`,
+              snippet: trimmed,
+              suggestion: closest ? `Replace '${target}' with '${closest.match}'.` : `Ensure node '${target}' is declared before targeting it.`,
+              didYouMean: closest?.match,
+              fix: closest ? { original: target, replacement: closest.match } : void 0
+            });
+          }
+        }
+      }
+    }
+  }
   try {
-    ast = parse(sourceCode);
+    const ast = parse(code);
+    if (checkArchitecture) {
+      const archViolations = validateArchitecture(ast);
+      for (const v of archViolations) {
+        issues.push({
+          line: v.line ?? 1,
+          severity: v.severity === "error" ? "error" : "warning",
+          code: "ARCH_RULE_VIOLATION",
+          message: `[${v.ruleName}] ${v.message}`,
+          suggestion: `Refactor architecture to comply with Well-Architected governance: ${v.ruleName}.`,
+          ruleExplanation: `Architecture Rule Preset: ${v.ruleName}`
+        });
+      }
+    }
+    for (const d of ast.diagnostics) {
+      if (d.message.includes("flow cycle detected")) {
+        issues.push({
+          line: d.line,
+          severity: "warning",
+          code: "FLOW_CYCLE_RETURN_EDGE",
+          message: d.message,
+          suggestion: "Use '<-' for return/response edges instead of '->' or '~>'.",
+          ruleExplanation: "Cycle Safety: Always use '<-' when returning calls to callers to prevent cyclical layout rank collisions."
+        });
+      } else {
+        const isDuplicate = issues.some((iss) => iss.line === d.line && iss.message === d.message);
+        if (!isDuplicate) {
+          issues.push({
+            line: d.line,
+            severity: d.severity === "error" ? "error" : "warning",
+            code: "SYNTAX_ERROR",
+            message: d.message
+          });
+        }
+      }
+    }
   } catch (err) {
-    syntaxErrors.push(err instanceof Error ? err.message : String(err));
+    const errMsg = err instanceof Error ? err.message : String(err);
+    const lineMatch = errMsg.match(/line\s+(\d+):\s*(.*)/);
+    const errLine = lineMatch ? Number(lineMatch[1]) : 1;
+    const cleanMsg = lineMatch ? lineMatch[2] : errMsg;
+    const alreadyCaptured = issues.some((iss) => iss.line === errLine && iss.severity === "error");
+    if (!alreadyCaptured) {
+      issues.push({
+        line: errLine,
+        severity: "error",
+        code: "SYNTAX_ERROR",
+        message: cleanMsg,
+        snippet: lines[errLine - 1] ?? "",
+        suggestion: "Review Markdy 4-step structure: Directives -> Semantic Nodes -> Groups -> Beats."
+      });
+    }
   }
-  if (!ast) {
-    return {
-      isValid: false,
-      syntaxErrors,
-      archViolations: [],
-      repairPrompt: [
-        "The following MarkdyScript failed to parse with syntax errors:",
-        ...syntaxErrors.map((e) => `  - ${e}`),
-        "",
-        "Please fix the code below to follow valid MarkdyScript syntax:",
-        "```markdy",
-        sourceCode,
-        "```"
-      ].join("\n")
-    };
+  const autoRepair = repairMarkdyCode(code, {
+    transpileMermaid: options.transpileMermaid,
+    precomputedIssues: issues
+  });
+  const repairPrompt = buildAIHealingPrompt(code, issues, autoRepair.repairedCode);
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  const isValid = errorCount === 0;
+  const summary = isValid ? `\u2705 Markdy code is valid with ${warningCount} warning(s).` : `\u274C Markdy code has ${errorCount} syntax error(s) and ${warningCount} warning(s).`;
+  return {
+    isValid,
+    errorCount,
+    warningCount,
+    issues,
+    repairedCode: autoRepair.repairedCode !== code ? autoRepair.repairedCode : void 0,
+    repairPrompt,
+    summary,
+    declaredNodes: Array.from(declaredNodes),
+    referencedNodes: Array.from(referencedNodes)
+  };
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function repairMarkdyCode(code, options) {
+  const changes = [];
+  if (options?.transpileMermaid && /^\s*(graph\s+(TB|TD|BT|RL|LR)|flowchart\s+(TB|TD|BT|RL|LR))/i.test(code)) {
+    try {
+      const transpiledCode = options.transpileMermaid(code);
+      changes.push("Transpiled Mermaid flowchart to canonical MarkdyScript.");
+      return {
+        repairedCode: transpiledCode,
+        changes,
+        isFixed: true
+      };
+    } catch {
+    }
+  }
+  const lines = code.replace(/\r\n/g, "\n").split("\n");
+  const repairedLines = [];
+  const declaredNodes = /* @__PURE__ */ new Set();
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const nodeMatch = trimmed.match(/^(\w[\w.-]*)\s+(\w[\w.-]*)/);
+    if (nodeMatch && !TOP_LEVEL_KEYWORDS.includes(nodeMatch[1].toLowerCase())) {
+      declaredNodes.add(nodeMatch[2]);
+    }
   }
-  const archViolations = validateArchitecture(ast);
-  if (ast.diagnostics.length === 0 && archViolations.length === 0) {
-    return { isValid: true, syntaxErrors: [], archViolations: [] };
+  let inBeat = false;
+  let beatIndent = 0;
+  let hasBareCues = false;
+  const bareCuesBuffer = [];
+  for (let idx = 0; idx < lines.length; idx++) {
+    let line = lines[idx];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("#")) {
+      repairedLines.push(line);
+      continue;
+    }
+    const indent = line.match(/^\s*/)?.[0] ?? "";
+    const indentLen = indent.length;
+    let processed = trimmed;
+    if (inBeat && indentLen <= beatIndent && !trimmed.startsWith("&") && !trimmed.startsWith("beat ") && !trimmed.startsWith("bea ")) {
+      inBeat = false;
+    }
+    processed = processed.replace(/^scen\b|^secne\b|^scence\b/i, "scene");
+    processed = processed.replace(/^layput\b|^layour\b|^layuot\b/i, "layout");
+    processed = processed.replace(/^groop\b|^grp\b/i, "group");
+    processed = processed.replace(/^bea\b|^beats\b/i, "beat");
+    processed = processed.replace(/^patern\b/i, "pattern");
+    for (const [inv, valid] of Object.entries(INVALID_FLOW_OP_MAP)) {
+      if (processed.includes(inv)) {
+        processed = processed.replaceAll(inv, valid);
+        changes.push(`Line ${idx + 1}: Fixed invalid flow operator '${inv}' -> '${valid}'.`);
+      }
+    }
+    if (/^beat\s+/i.test(processed)) {
+      inBeat = true;
+      beatIndent = indentLen;
+      if (/^beat\s+[\w.-]+(\s+"[^"]*")?\s*$/i.test(processed)) {
+        processed = `${processed}:`;
+        changes.push(`Line ${idx + 1}: Added missing colon ':' to beat header.`);
+      }
+    }
+    if (/^group\s+/i.test(processed)) {
+      if (!processed.includes(":")) {
+        const groupMatch = processed.match(/^group\s+([\w.-]+)(?:\s+"([^"]*)")?\s+(.+)$/i);
+        if (groupMatch) {
+          const gid = groupMatch[1];
+          const label = groupMatch[2] ? ` "${groupMatch[2]}"` : "";
+          const rest = groupMatch[3];
+          processed = `group ${gid}${label}: ${rest}`;
+          changes.push(`Line ${idx + 1}: Added missing colon ':' to group header.`);
+        }
+      }
+    }
+    if (!inBeat && !processed.startsWith("scene") && !processed.startsWith("layout") && !processed.startsWith("group")) {
+      const match = processed.match(/^(\w[\w.-]*)\s+(\w[\w.-]*)(.*)$/);
+      if (match) {
+        const rawKind = match[1];
+        const rawKindLower = rawKind.toLowerCase();
+        const id = match[2];
+        let rest = match[3].trim();
+        const canonical = canonicalNodeKind(rawKindLower);
+        if (!NODE_KINDS.has(canonical)) {
+          const matchKind = findClosestMatch(rawKindLower, ALL_NODE_KINDS);
+          if (matchKind) {
+            const canonicalFix = canonicalNodeKind(matchKind.match);
+            changes.push(`Line ${idx + 1}: Repaired node kind '${rawKind}' -> '${canonicalFix}'.`);
+            processed = `${canonicalFix} ${id}${rest ? ` ${rest}` : ""}`;
+          }
+        }
+        if (rest && !rest.startsWith('"') && !rest.startsWith("style=") && !rest.startsWith("icon=") && rest.split(/\s+/).length > 1 && !rest.includes("=")) {
+          changes.push(`Line ${idx + 1}: Enclosed multi-word label in quotes: "${rest}".`);
+          processed = `${canonicalNodeKind(rawKindLower)} ${id} "${rest}"`;
+        }
+      }
+    }
+    if ((inBeat || processed.startsWith("group ")) && declaredNodes.size > 0) {
+      if (processed.includes("->") || processed.includes("<-") || processed.includes("~>") || processed.includes("--") || processed.startsWith("group ")) {
+        const cleanFlow = processed.replace(/"[^"]*"/g, '""');
+        const flowTokens = cleanFlow.split(/->|<-|~>|--|&|:|\s+/).filter(Boolean);
+        for (const tok of flowTokens) {
+          if (!tok.startsWith("$") && !tok.includes("=") && /^[a-zA-Z_][\w.-]*$/.test(tok) && tok !== '""' && tok !== "group" && !["and", "show", "hide", "glow", "focus", "frame", "pulse", "use"].includes(tok.toLowerCase()) && !declaredNodes.has(tok)) {
+            const match = findClosestMatch(tok, declaredNodes);
+            if (match) {
+              const regex = new RegExp(`\\b${escapeRegex(tok)}\\b`, "g");
+              processed = processed.replace(regex, match.match);
+              changes.push(`Line ${idx + 1}: Corrected typo in node reference '${tok}' -> '${match.match}'.`);
+            }
+          }
+        }
+      }
+    }
+    if (!inBeat) {
+      const isCue = CUE_KEYWORDS.includes(processed.split(/\s+/)[0].toLowerCase());
+      const isFlow = /(-->|->|<-|<--|~>|--)/.test(processed);
+      if (isCue || isFlow) {
+        hasBareCues = true;
+        bareCuesBuffer.push(`  ${processed}`);
+        changes.push(`Line ${idx + 1}: Wrapped bare cue '${processed}' into 'beat main'.`);
+        continue;
+      }
+    }
+    repairedLines.push(`${indent}${processed}`);
   }
+  if (hasBareCues && !lines.some((l) => l.trim().startsWith("beat "))) {
+    repairedLines.push('\nbeat main "Flow":');
+    repairedLines.push(...bareCuesBuffer);
+  }
+  const repairedCode = repairedLines.join("\n");
+  let isFixed = false;
+  try {
+    parse(repairedCode);
+    isFixed = true;
+  } catch {
+    isFixed = false;
+  }
+  return {
+    repairedCode,
+    changes,
+    isFixed
+  };
+}
+function buildAIHealingPrompt(sourceCode, issues, suggestedRepair) {
+  if (issues.length === 0) {
+    return "The MarkdyScript diagram is completely valid. No healing required.";
+  }
+  const errorIssues = issues.filter((i) => i.severity === "error" && i.code !== "ARCH_RULE_VIOLATION");
+  const warningIssues = issues.filter((i) => i.severity === "warning" && i.code !== "ARCH_RULE_VIOLATION");
+  const archIssues = issues.filter((i) => i.code === "ARCH_RULE_VIOLATION");
   const promptSections = [
-    "The MarkdyScript diagram has the following compiler diagnostics and architectural rule violations:",
-    "",
-    "### Diagnostics:",
-    ...ast.diagnostics.map((d) => `  - Line ${d.line}: ${d.message}`),
-    "",
-    "### Architectural Violations:",
-    ...archViolations.map((v) => `  - [${v.severity.toUpperCase()}] ${v.ruleName}: ${v.message}`),
-    "",
-    "Please revise the diagram code to resolve all issues while preserving semantic nodes and beats:",
-    "```markdy",
-    sourceCode,
-    "```"
+    "### Markdy Diagram Syntax & Architectural Diagnostics",
+    ""
   ];
+  if (errorIssues.length > 0) {
+    promptSections.push("The following MarkdyScript failed to parse with syntax errors:");
+    promptSections.push("");
+    promptSections.push("### Diagnostics & Critical Errors:");
+    for (const err of errorIssues) {
+      const lineStr = err.line ? `  - Line ${err.line}: ` : "  - ";
+      promptSections.push(`${lineStr}${err.message}`);
+      if (err.snippet) {
+        promptSections.push(`    *Problem:* \`${err.snippet}\``);
+      }
+      if (err.suggestion) {
+        promptSections.push(`    *Recommendation:* ${err.suggestion}`);
+      }
+      if (err.didYouMean) {
+        promptSections.push(`    *Did you mean:* \`${err.didYouMean}\`?`);
+      }
+    }
+    promptSections.push("");
+  }
+  if (archIssues.length > 0) {
+    promptSections.push("### Architectural Violations:");
+    for (const v of archIssues) {
+      const lineStr = v.line ? ` (line ${v.line})` : "";
+      promptSections.push(`  - [${v.severity.toUpperCase()}] ${v.message}${lineStr}`);
+      if (v.suggestion) {
+        promptSections.push(`    *Recommendation:* ${v.suggestion}`);
+      }
+    }
+    promptSections.push("");
+  } else if (warningIssues.length > 0) {
+    promptSections.push("### Diagnostics & Warnings:");
+    for (const w of warningIssues) {
+      const lineStr = w.line ? `  - Line ${w.line}: ` : "  - ";
+      promptSections.push(`${lineStr}${w.message}`);
+      if (w.suggestion) {
+        promptSections.push(`    *Recommendation:* ${w.suggestion}`);
+      }
+    }
+    promptSections.push("");
+  }
+  promptSections.push("### Canonical Markdy Mental Model Guidelines:");
+  promptSections.push("1. **Directives**: `scene theme=paper width=1280 height=720` and `layout LR` (or TB).");
+  promptSections.push('2. **Nodes**: `<kind> <Id> ["Human Label"]` (e.g. `service Orders "Order Service"`, `database DB "PostgreSQL"`). Labels with spaces MUST be in double quotes.');
+  promptSections.push('3. **Groups**: `group <id> "<Label>": Node1 Node2`');
+  promptSections.push('4. **Beats**: `beat <id> "<Caption>":` with indented flows and cues.');
+  promptSections.push("5. **Cycle Safety**: Always use `<-` for response/return edges to prevent layout rank cycles. Never use `->` to return to a previous node.");
+  promptSections.push("");
+  if (suggestedRepair && suggestedRepair !== sourceCode) {
+    promptSections.push("### Proposed Repaired MarkdyScript:");
+    promptSections.push("```markdy");
+    promptSections.push(suggestedRepair);
+    promptSections.push("```");
+    promptSections.push("");
+  }
+  promptSections.push("Please revise the diagram code to resolve all issues while preserving semantic nodes and beats:");
+  promptSections.push("```markdy");
+  promptSections.push(sourceCode);
+  promptSections.push("```");
+  return promptSections.join("\n");
+}
+
+// ../core/src/intellicode.ts
+var POPULAR_TECHS = [
+  // Databases
+  { name: "PostgreSQL", aliases: ["postgres", "postgresql", "psql"], kind: "database", defaultId: "Postgres", label: "PostgreSQL 16", desc: "ACID relational SQL database", category: "database" },
+  { name: "MySQL", aliases: ["mysql", "mariadb"], kind: "database", defaultId: "MySQL", label: "MySQL 8.0", desc: "Relational database", category: "database" },
+  { name: "MongoDB", aliases: ["mongo", "mongodb"], kind: "database", defaultId: "MongoDB", label: "MongoDB Atlas", desc: "Document NoSQL database", category: "database" },
+  { name: "DynamoDB", aliases: ["dynamo", "dynamodb"], kind: "database", defaultId: "DynamoDB", label: "AWS DynamoDB", desc: "Serverless key-value NoSQL", category: "database" },
+  { name: "ClickHouse", aliases: ["clickhouse"], kind: "database", defaultId: "ClickHouse", label: "ClickHouse OLAP", desc: "Real-time columnar analytics", category: "database" },
+  { name: "Snowflake", aliases: ["snowflake"], kind: "database", defaultId: "Snowflake", label: "Snowflake Data Warehouse", desc: "Cloud data warehouse", category: "database" },
+  { name: "Neo4j", aliases: ["neo4j", "graphdb"], kind: "database", defaultId: "Neo4j", label: "Neo4j Graph Database", desc: "Property graph engine", category: "database" },
+  { name: "Pinecone", aliases: ["pinecone", "weaviate", "qdrant", "chroma"], kind: "database", defaultId: "Pinecone", label: "Pinecone Vector DB", desc: "Vector similarity search for AI/RAG", category: "ai" },
+  // Caching
+  { name: "Redis", aliases: ["redis", "valkey", "dragonfly"], kind: "cache", defaultId: "Redis", label: "Redis Cluster", desc: "In-memory sub-millisecond cache", category: "cache" },
+  { name: "Memcached", aliases: ["memcached"], kind: "cache", defaultId: "Memcached", label: "Memcached", desc: "Distributed memory object cache", category: "cache" },
+  // Messaging & Streams
+  { name: "Kafka", aliases: ["kafka", "redpanda", "confluent"], kind: "queue", defaultId: "Kafka", label: "Kafka Event Stream", desc: "High-throughput event bus", category: "queue" },
+  { name: "RabbitMQ", aliases: ["rabbitmq", "amqp"], kind: "queue", defaultId: "RabbitMQ", label: "RabbitMQ Broker", desc: "AMQP message queue", category: "queue" },
+  { name: "AWS SQS", aliases: ["sqs"], kind: "queue", defaultId: "SQS", label: "Amazon SQS", desc: "Managed queue service", category: "queue" },
+  { name: "NATS", aliases: ["nats"], kind: "queue", defaultId: "NATS", label: "NATS JetStream", desc: "Lightweight cloud native pub/sub", category: "queue" },
+  // Ingress & Gateways
+  { name: "Kong", aliases: ["kong"], kind: "gateway", defaultId: "KongGateway", label: "Kong API Gateway", desc: "Cloud native API gateway", category: "gateway" },
+  { name: "Envoy", aliases: ["envoy"], kind: "gateway", defaultId: "EnvoyProxy", label: "Envoy Service Proxy", desc: "High-performance edge/service proxy", category: "gateway" },
+  { name: "Nginx", aliases: ["nginx"], kind: "gateway", defaultId: "Nginx", label: "Nginx Ingress", desc: "Reverse proxy & load balancer", category: "gateway" },
+  { name: "Traefik", aliases: ["traefik"], kind: "gateway", defaultId: "Traefik", label: "Traefik Proxy", desc: "Dynamic reverse proxy for microservices", category: "gateway" },
+  { name: "Cloudflare", aliases: ["cloudflare"], kind: "cdn", defaultId: "Cloudflare", label: "Cloudflare Edge / WAF", desc: "Edge CDN & security perimeter", category: "security" },
+  // Clients & Frontends
+  { name: "React Web App", aliases: ["react", "next", "nextjs", "frontend", "webapp"], kind: "browser", defaultId: "WebApp", label: "Next.js Web Client", desc: "React / Next.js web application", category: "client" },
+  { name: "Mobile App", aliases: ["ios", "android", "flutter", "reactnative", "mobile"], kind: "mobile", defaultId: "MobileApp", label: "iOS / Android Mobile App", desc: "Native mobile client application", category: "client" },
+  // Compute & Microservices
+  { name: "API Service", aliases: ["service", "api", "backend", "microservice"], kind: "service", defaultId: "ApiService", label: "API Core Service", desc: "Backend REST/gRPC microservice", category: "compute" },
+  { name: "Auth Service", aliases: ["auth", "auth0", "keycloak", "clerk", "cognito"], kind: "service", defaultId: "AuthService", label: "Auth & Identity Provider", desc: "OAuth2 / OIDC authentication service", category: "security" },
+  { name: "Order Service", aliases: ["order", "ordersvc"], kind: "service", defaultId: "OrderService", label: "Order Processing Service", desc: "Transactional order service", category: "compute" },
+  { name: "Payment Gateway", aliases: ["payment", "stripe", "paypal"], kind: "service", defaultId: "PaymentService", label: "Stripe Payment Gateway", desc: "Payment processing integration", category: "compute" },
+  { name: "Async Worker", aliases: ["worker", "celery", "sidekiq"], kind: "worker", defaultId: "AsyncWorker", label: "Background Job Worker", desc: "Asynchronous task consumer worker", category: "compute" },
+  { name: "Serverless Function", aliases: ["lambda", "function", "cloudfunction"], kind: "lambda", defaultId: "LambdaFunc", label: "AWS Lambda / Cloud Function", desc: "Event-driven serverless function", category: "compute" },
+  { name: "Kubernetes Pod", aliases: ["k8s", "pod", "kubernetes"], kind: "pod", defaultId: "AppPod", label: "Kubernetes Pod Cluster", desc: "Containerized workload pod", category: "compute" },
+  // AI & LLMs
+  { name: "Gemini / LLM Engine", aliases: ["gemini", "openai", "gpt", "claude", "llm", "ai"], kind: "service", defaultId: "AIEngine", label: "Gemini 2.5 Flash / AI Core", desc: "Large Language Model inference engine", category: "ai" },
+  // Storage & Backend as a Service
+  { name: "S3 Object Storage", aliases: ["s3", "storage", "gcs", "blob", "r2"], kind: "storage", defaultId: "S3Storage", label: "AWS S3 / Cloud Storage", desc: "Object storage bucket", category: "storage" },
+  { name: "Supabase", aliases: ["supabase"], kind: "database", defaultId: "SupabaseDB", label: "Supabase PostgreSQL", desc: "Open-source Firebase alternative with Postgres", category: "database" },
+  { name: "Firebase Firestore", aliases: ["firebase", "firestore"], kind: "database", defaultId: "Firestore", label: "Firebase Firestore", desc: "Serverless real-time document database", category: "database" },
+  // Observability & Telemetry
+  { name: "Prometheus", aliases: ["prometheus", "metrics"], kind: "metric", defaultId: "Prometheus", label: "Prometheus Metrics", desc: "Time-series metrics monitoring engine", category: "compute" },
+  { name: "Grafana", aliases: ["grafana", "dashboard"], kind: "surface", defaultId: "GrafanaUI", label: "Grafana Dashboard", desc: "Visualization & telemetry analytics dashboard", category: "compute" },
+  { name: "OpenSearch / Elasticsearch", aliases: ["opensearch", "elasticsearch", "elastic"], kind: "database", defaultId: "OpenSearch", label: "OpenSearch Cluster", desc: "Distributed search & log analytics engine", category: "database" },
+  { name: "Sentry", aliases: ["sentry", "errors"], kind: "service", defaultId: "Sentry", label: "Sentry Error Tracker", desc: "Application monitoring and error tracking", category: "compute" }
+];
+function extractDiagramContext(text, cursorLine = 0, cursorCol = 0) {
+  const lines = text.split(/\r?\n/);
+  const declaredNodes = [];
+  const declaredGroups = [];
+  const declaredBeats = [];
+  let theme;
+  let layout;
+  let diagramType;
+  let insideBeat = false;
+  let currentBeatName;
+  let insideGroup = false;
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const trimmed = rawLine.trim();
+    if (!trimmed || trimmed.startsWith("//")) continue;
+    const themeMatch = /theme\s*=\s*([a-zA-Z0-9_-]+)/.exec(trimmed);
+    if (themeMatch) theme = themeMatch[1];
+    const layoutMatch = /layout\s+([A-Z]{2})/.exec(trimmed);
+    if (layoutMatch) layout = layoutMatch[1];
+    const typeMatch = /type\s*=\s*([a-zA-Z0-9_-]+)/.exec(trimmed);
+    if (typeMatch) diagramType = typeMatch[1];
+    const beatMatch = /^beat\s+([\w.-]+)(?:\s+"([^"]*)")?:/i.exec(trimmed);
+    if (beatMatch) {
+      declaredBeats.push({ id: beatMatch[1], label: beatMatch[2] || beatMatch[1], line: i });
+      if (i <= cursorLine) {
+        insideBeat = true;
+        currentBeatName = beatMatch[1];
+      }
+      continue;
+    }
+    if (insideBeat && i === cursorLine && !rawLine.startsWith(" ") && !rawLine.startsWith("	") && trimmed) {
+      if (!trimmed.startsWith("beat")) {
+        insideBeat = false;
+        currentBeatName = void 0;
+      }
+    }
+    const groupMatch = /^group\s+([\w.-]+)(?:\s+"([^"]*)")?:\s*(.*)$/i.exec(trimmed);
+    if (groupMatch) {
+      const members = groupMatch[3] ? groupMatch[3].trim().split(/\s+/) : [];
+      declaredGroups.push({ id: groupMatch[1], label: groupMatch[2] || groupMatch[1], members, line: i });
+      continue;
+    }
+    const nodeMatch = /^(\w[\w.-]*)\s+(\w[\w.-]*)(?:\s+"([^"]*)")?/i.exec(trimmed);
+    if (nodeMatch) {
+      const kind = nodeMatch[1].toLowerCase();
+      const id = nodeMatch[2];
+      const label = nodeMatch[3] || humanizeId(id);
+      if (!["scene", "layout", "group", "beat", "style", "pattern", "use", "var", "edge", "theme"].includes(kind) && (NODE_KINDS.has(kind) || NODE_KINDS.has(canonicalNodeKind(kind)) || TECHNICAL_NODE_TYPES.includes(kind))) {
+        declaredNodes.push({ id, kind, label, line: i });
+      }
+    }
+  }
+  const currentLineText = lines[cursorLine] ?? "";
+  const linePrefix = currentLineText.slice(0, cursorCol);
+  const tokenMatch = /[\w$.-><~]*$/.exec(linePrefix);
+  const tokenPrefix = tokenMatch ? tokenMatch[0] : "";
+  let cursorInsideBeat = false;
+  for (let i = cursorLine; i >= 0; i--) {
+    const l = lines[i] ?? "";
+    const trimL = l.trim();
+    if (trimL.startsWith("//") || !trimL) continue;
+    if (/^beat\s+[\w.-]+.*:/i.test(trimL)) {
+      cursorInsideBeat = true;
+      break;
+    }
+    if (/^(scene|layout|group|style|pattern|service|database|cache|queue|gateway|browser|mobile|client|worker|storage|cdn|pod|lambda|user)\b/i.test(trimL)) {
+      cursorInsideBeat = false;
+      break;
+    }
+  }
   return {
-    isValid: false,
-    syntaxErrors: [],
-    archViolations,
-    repairPrompt: promptSections.join("\n")
+    declaredNodes,
+    declaredGroups,
+    declaredBeats,
+    theme,
+    layout,
+    diagramType,
+    insideBeat: cursorInsideBeat,
+    currentBeatName,
+    insideGroup,
+    lineNo: cursorLine,
+    lineText: currentLineText,
+    linePrefix,
+    tokenPrefix
   };
 }
+function isClientRole(kind) {
+  return nodeRole(kind) === "client";
+}
+function isGatewayRole(kind) {
+  const c = canonicalNodeKind(kind);
+  return ["gateway", "api_gateway", "proxy", "load_balancer", "cdn", "firewall", "waf"].includes(c);
+}
+function isComputeRole(kind) {
+  return nodeRole(kind) === "compute";
+}
+function isDatabaseKind(kind) {
+  const c = canonicalNodeKind(kind);
+  return ["database", "db", "sql", "nosql", "warehouse", "table", "lake"].includes(c);
+}
+function isCacheKind(kind) {
+  const c = canonicalNodeKind(kind);
+  return ["cache"].includes(c);
+}
+function isQueueRole(kind) {
+  return nodeRole(kind) === "messaging";
+}
+function getIntelliCodeCompletions(docText, cursorLine, cursorCol) {
+  const ctx = extractDiagramContext(docText, cursorLine, cursorCol);
+  const items = [];
+  const flowMatch = /([\w.-]+)\s*(->|<-|~>|<->|\.\.>)\s*([\w.-]*)$/.exec(ctx.linePrefix);
+  if (flowMatch) {
+    const sourceNodeId = flowMatch[1];
+    const op = flowMatch[2];
+    const filter = flowMatch[3].toLowerCase();
+    const sourceNode = ctx.declaredNodes.find((n) => n.id === sourceNodeId);
+    const sourceKind = sourceNode ? sourceNode.kind : "service";
+    for (const node of ctx.declaredNodes) {
+      if (node.id === sourceNodeId && op !== "<->") continue;
+      let boost = 2;
+      if (isClientRole(sourceKind)) {
+        if (isGatewayRole(node.kind)) boost = 10;
+        else if (isComputeRole(node.kind)) boost = 8;
+        else boost = 2;
+      } else if (isGatewayRole(sourceKind)) {
+        if (isComputeRole(node.kind)) boost = 10;
+        else boost = 3;
+      } else if (isComputeRole(sourceKind)) {
+        if (isDatabaseKind(node.kind) || isCacheKind(node.kind) || isQueueRole(node.kind)) boost = 10;
+        else if (isComputeRole(node.kind)) boost = 7;
+        else boost = 3;
+      } else if (isQueueRole(sourceKind)) {
+        if (isComputeRole(node.kind)) boost = 10;
+        else boost = 2;
+      }
+      if (op === "<-") {
+        boost = isClientRole(node.kind) || isGatewayRole(node.kind) ? 10 : 3;
+      }
+      items.push({
+        label: node.id,
+        insertText: `${node.id} `,
+        kind: "node",
+        detail: `${node.kind} \xB7 "${node.label}"`,
+        documentation: `Connect flow ${sourceNodeId} ${op} ${node.id}`,
+        boost
+      });
+    }
+    if (!filter || filter.startsWith('"')) {
+      const sourceRole = nodeRole(sourceKind);
+      const sampleLabels = getCommonEdgeLabels(sourceRole, op);
+      for (const lbl of sampleLabels) {
+        items.push({
+          label: `"${lbl}"`,
+          insertText: `"${lbl}"`,
+          kind: "snippet",
+          detail: "Flow description label",
+          boost: 1
+        });
+      }
+    }
+    return items;
+  }
+  const nodeStartMatch = /^\s*([\w.-]+)\s+$/.exec(ctx.linePrefix);
+  if (nodeStartMatch) {
+    const candidateId = nodeStartMatch[1];
+    const isDeclared = ctx.declaredNodes.some((n) => n.id === candidateId);
+    if (isDeclared) {
+      items.push(
+        { label: "->", insertText: "-> ", kind: "flowOp", detail: "Sync request / call", documentation: "Synchronous HTTP, gRPC, or RPC call.", boost: 10 },
+        { label: "~>", insertText: "~> ", kind: "flowOp", detail: "Async event / pub-sub", documentation: "Asynchronous event stream or message queue dispatch.", boost: 9 },
+        { label: "<-", insertText: "<- ", kind: "flowOp", detail: "Response / return payload", documentation: "Synchronous return response payload.", boost: 8 },
+        { label: "<->", insertText: "<-> ", kind: "flowOp", detail: "Bidirectional streaming / mTLS", documentation: "Two-way streaming WebSocket or mutual TLS socket.", boost: 7 },
+        { label: "..>", insertText: "..> ", kind: "flowOp", detail: "Weak dependency link", documentation: "Dashed architectural dependency relationship.", boost: 6 }
+      );
+      return items;
+    }
+  }
+  if (/(theme\s*=\s*|theme\s+)\w*$/i.test(ctx.linePrefix)) {
+    const themeEntries = [
+      { name: "paper", desc: "Warm editorial white canvas with crisp modern typography" },
+      { name: "midnight", desc: "Deep OLED dark theme with vibrant neon kinetic pulses" },
+      { name: "blueprint", desc: "Architectural blueprint cyan graph styling" },
+      { name: "nebula", desc: "Futuristic cosmic purple & indigo glow palette" },
+      { name: "editorial", desc: "High-contrast serif luxury publication layout" },
+      { name: "graphite", desc: "Sleek slate monochrome engineering aesthetic" },
+      { name: "terminal", desc: "Retro phosphor CRT hacker terminal green on black" },
+      { name: "sketchy", desc: "Hand-drawn sketchy whiteboard marker design" }
+    ];
+    for (const t of themeEntries) {
+      items.push({
+        label: t.name,
+        insertText: t.name,
+        kind: "theme",
+        detail: `theme=${t.name}`,
+        documentation: t.desc,
+        boost: 10
+      });
+    }
+    return items;
+  }
+  if (/(layout\s+|direction\s*=\s*)\w*$/i.test(ctx.linePrefix)) {
+    items.push(
+      { label: "LR", insertText: "LR", kind: "layout", detail: "Left-to-Right", documentation: "Horizontal left-to-right system flow layout.", boost: 10 },
+      { label: "TB", insertText: "TB", kind: "layout", detail: "Top-to-Bottom", documentation: "Vertical top-to-bottom hierarchy layout.", boost: 9 },
+      { label: "RL", insertText: "RL", kind: "layout", detail: "Right-to-Left", documentation: "Right-to-left reverse topology layout.", boost: 5 },
+      { label: "BT", insertText: "BT", kind: "layout", detail: "Bottom-to-Top", documentation: "Bottom-to-top inverted stack layout.", boost: 5 }
+    );
+    return items;
+  }
+  if (/type\s*=\s*\w*$/i.test(ctx.linePrefix)) {
+    for (const t of DIAGRAM_TYPES) {
+      items.push({
+        label: t,
+        insertText: t,
+        kind: "diagramType",
+        detail: `type=${t}`,
+        documentation: `Specialized layout engine: ${t}`,
+        boost: 8
+      });
+    }
+    return items;
+  }
+  const cueMatch = /^\s*(show|glow|pulse|focus|frame|hide)\s+([\w$]*)$/i.exec(ctx.linePrefix);
+  if (cueMatch) {
+    const cueName = cueMatch[1].toLowerCase();
+    items.push(
+      { label: "$nodes", insertText: "$nodes stagger=60ms", kind: "selector", detail: "All diagram nodes", documentation: "Selects all semantic nodes in the scene.", boost: 10 },
+      { label: "$title", insertText: "$title", kind: "selector", detail: "Diagram title banner", documentation: "Selects the title node.", boost: 8 },
+      { label: "$edges", insertText: "$edges", kind: "selector", detail: "All edge connectors", documentation: "Selects all flow connectors.", boost: 7 }
+    );
+    for (const node of ctx.declaredNodes) {
+      items.push({
+        label: node.id,
+        insertText: `${node.id} `,
+        kind: "node",
+        detail: `${node.kind} \xB7 "${node.label}"`,
+        boost: 9
+      });
+    }
+    for (const group of ctx.declaredGroups) {
+      items.push({
+        label: group.id,
+        insertText: cueName === "frame" ? `${group.id} zoom=1.2 dur=600ms` : `${group.id} `,
+        kind: "group",
+        detail: `group "${group.label}"`,
+        documentation: `Group boundary with ${group.members.length} nodes.`,
+        boost: 8
+      });
+    }
+    if (cueName === "show" || cueName === "hide") {
+      items.push({ label: "stagger=60ms", insertText: "stagger=60ms", kind: "attribute", detail: "Stagger delay", boost: 5 });
+    } else if (cueName === "glow" || cueName === "pulse") {
+      items.push(
+        { label: "color=#38bdf8", insertText: "color=#38bdf8", kind: "attribute", detail: "Sky blue kinetic glow", boost: 5 },
+        { label: "color=#e11d48", insertText: "color=#e11d48", kind: "attribute", detail: "Alert crimson pulse", boost: 5 },
+        { label: "color=#10b981", insertText: "color=#10b981", kind: "attribute", detail: "Success emerald glow", boost: 5 }
+      );
+    } else if (cueName === "frame") {
+      items.push(
+        { label: "zoom=1.2 dur=600ms", insertText: "zoom=1.2 dur=600ms", kind: "attribute", detail: "Camera focus & zoom", boost: 5 }
+      );
+    }
+    return items;
+  }
+  if (ctx.insideBeat) {
+    for (const cue of BEAT_CUE_KEYWORDS) {
+      const aliasTarget = cue === "pulse" ? "focus" : cue === "highlight" ? "glow" : cue;
+      items.push({
+        label: cue,
+        insertText: cue === "show" ? "show $nodes stagger=60ms" : `${cue} `,
+        kind: "cue",
+        detail: `Choreography cue (${aliasTarget})`,
+        documentation: `Execute kinetic choreography action: ${cue}`,
+        boost: 8
+      });
+    }
+    for (const node of ctx.declaredNodes) {
+      items.push({
+        label: node.id,
+        insertText: `${node.id} -> `,
+        kind: "node",
+        detail: `Start flow from ${node.kind} "${node.label}"`,
+        boost: 9
+      });
+    }
+    items.push(
+      { label: "$nodes", insertText: "$nodes", kind: "selector", detail: "Selector for all nodes", boost: 6 },
+      { label: "$title", insertText: "$title", kind: "selector", detail: "Diagram title", boost: 5 }
+    );
+    return items;
+  }
+  items.push(
+    { label: "scene", insertText: "scene theme=paper layout=LR\n", kind: "keyword", detail: "Scene directive", documentation: "Declare scene configuration, theme, and layout direction.", boost: 10 },
+    { label: "layout LR", insertText: "layout LR\n", kind: "directive", detail: "Horizontal layout", documentation: "Left-to-right topology layout.", boost: 10 },
+    { label: "layout TB", insertText: "layout TB\n", kind: "directive", detail: "Vertical hierarchy layout", documentation: "Top-to-bottom hierarchy layout.", boost: 9 },
+    { label: "theme midnight", insertText: "theme=midnight\n", kind: "directive", detail: "Dark theme", documentation: "High-contrast dark mode with neon accents.", boost: 8 },
+    { label: "theme paper", insertText: "theme=paper\n", kind: "directive", detail: "Editorial light theme", documentation: "Clean light mode with high-legibility typography.", boost: 8 },
+    { label: "group", insertText: 'group ${1:subsystem} "${2:Subsystem Perimeter}": ${3:Node1} ${4:Node2}\n', kind: "snippet", isSnippet: true, detail: "Group boundary", documentation: "Perimeter enclosing related subsystems.", boost: 8 },
+    { label: "beat", insertText: 'beat ${1:main} "${2:System Flow}":\n  show $nodes stagger=60ms\n  ${0}\n', kind: "snippet", isSnippet: true, detail: "Kinetic narrative beat", documentation: "Defines an animated step in the diagram choreography.", boost: 9 },
+    { label: "pattern", insertText: 'pattern ${1:retry_flow} "${2:Retry Pattern}":\n  ${3:Service} -> ${4:Queue} "retry"\n', kind: "snippet", isSnippet: true, detail: "Reusable flow pattern", documentation: "Defines a reusable architectural interaction pattern.", boost: 6 },
+    { label: "use pattern", insertText: "use pattern=${1:retry_flow}\n", kind: "directive", detail: "Instantiate pattern", documentation: "Reuses a declared flow pattern in the current scope.", boost: 6 },
+    { label: "style", insertText: "style ${1:NodeId} fill=${2:#38bdf8} stroke=${3:#0284c7}\n", kind: "snippet", isSnippet: true, detail: "Custom node styling", boost: 5 },
+    { label: "var", insertText: "var ${1:key} = ${2:value}\n", kind: "snippet", isSnippet: true, detail: "Declare variable", boost: 4 }
+  );
+  const nodeKindsList = [
+    { kind: "service", id: "ApiService", label: "API Service", desc: "Microservice / REST / gRPC backend" },
+    { kind: "database", id: "Database", label: "PostgreSQL Database", desc: "Relational or NoSQL database store" },
+    { kind: "cache", id: "RedisCache", label: "In-Memory Cache", desc: "High-speed in-memory cache" },
+    { kind: "queue", id: "MessageQueue", label: "Kafka Event Stream", desc: "Pub/Sub message broker or event stream" },
+    { kind: "gateway", id: "ApiGateway", label: "API Gateway", desc: "Ingress proxy and perimeter router" },
+    { kind: "browser", id: "WebApp", label: "Web Client", desc: "End-user web browser application" },
+    { kind: "mobile", id: "MobileApp", label: "Mobile Application", desc: "iOS / Android native mobile app" },
+    { kind: "worker", id: "BackgroundWorker", label: "Async Task Worker", desc: "Background job execution worker" },
+    { kind: "storage", id: "ObjectStorage", label: "S3 Object Store", desc: "Blob / document cloud storage" },
+    { kind: "cdn", id: "EdgeCDN", label: "Cloudflare Edge", desc: "Global content delivery network" },
+    { kind: "firewall", id: "WAF", label: "Security Perimeter", desc: "Web application firewall & DDoS shield" },
+    { kind: "lambda", id: "ServerlessFunc", label: "Serverless Function", desc: "Event-driven serverless function" },
+    { kind: "pod", id: "AppPod", label: "Kubernetes Pod", desc: "Containerized workload pod" },
+    { kind: "user", id: "Customer", label: "End User", desc: "Human user / customer actor" }
+  ];
+  for (const n of nodeKindsList) {
+    items.push({
+      label: n.kind,
+      insertText: `${n.kind} \${1:${n.id}} "\${2:${n.label}}"`,
+      kind: "nodeKind",
+      isSnippet: true,
+      detail: `Node kind \u2192 ${n.kind}`,
+      documentation: n.desc,
+      boost: 7
+    });
+  }
+  for (const vp of VISUAL_PRIMITIVE_TYPES) {
+    items.push({
+      label: vp,
+      insertText: `${vp} \${1:${humanizeId(vp).replace(/\s+/g, "")}} "\${2:${humanizeId(vp)}}"`,
+      kind: "nodeKind",
+      isSnippet: true,
+      detail: `Visual primitive \u2192 ${vp}`,
+      boost: 4
+    });
+  }
+  for (const tech of POPULAR_TECHS) {
+    items.push({
+      label: tech.name,
+      insertText: `${tech.kind} ${tech.defaultId} "${tech.label}"
+`,
+      kind: "tech",
+      detail: `\u26A1 ${tech.kind} \xB7 ${tech.name}`,
+      documentation: `${tech.desc}
+
+Inserts semantic ${tech.kind} node definition.`,
+      filterText: `${tech.name} ${tech.aliases.join(" ")} ${tech.kind}`,
+      boost: 6
+    });
+  }
+  for (const node of ctx.declaredNodes) {
+    items.push({
+      label: node.id,
+      insertText: node.id,
+      kind: "node",
+      detail: `${node.kind} \xB7 "${node.label}"`,
+      boost: 5
+    });
+  }
+  return items;
+}
+function getCommonEdgeLabels(sourceKind, op) {
+  if (op === "<-") {
+    return ["200 OK", "201 Created", "Cached Response", "Result Payload", "JWT Token"];
+  }
+  if (op === "~>") {
+    return ["order.created", "user.signup", "event.published", "telemetry.metric", "task.enqueue"];
+  }
+  if (op === "<->") {
+    return ["WebSocket / Streaming", "mTLS Bidirectional", "gRPC Bidirectional Stream"];
+  }
+  if (op === "..>") {
+    return ["depends on", "reads schema", "replicates to", "monitors"];
+  }
+  if (isClientRole(sourceKind)) {
+    return ["POST /api/v1/checkout", "GET /api/v1/user", "POST /auth/login", "GraphQL Query"];
+  }
+  if (isGatewayRole(sourceKind)) {
+    return ["Route /v1/orders", "Authorize & Forward", "Proxy Request"];
+  }
+  if (isComputeRole(sourceKind)) {
+    return ["SELECT * FROM orders", "SET cache:key", "GET cache:key", "Publish Event", "Verify Token"];
+  }
+  if (isQueueRole(sourceKind)) {
+    return ["Consume Message", "Process Batch", "Deliver Payload"];
+  }
+  return ["call", "request", "query", "sync"];
+}
+function predictNextLineSuggestion(docText, cursorLine) {
+  const ctx = extractDiagramContext(docText, cursorLine, 0);
+  const totalNodes = ctx.declaredNodes.length;
+  if (totalNodes === 0) {
+    return {
+      text: 'browser WebApp "Web Application"',
+      insertText: 'browser WebApp "Web Application"\nservice ApiGw "API Gateway Service"\n\nbeat main "System Entrance":\n  show $nodes stagger=60ms\n  WebApp -> ApiGw "POST /api"\n',
+      description: "Start with an entry client and API Gateway with entrance choreography",
+      type: "next-node"
+    };
+  }
+  if (totalNodes >= 2 && ctx.declaredBeats.length === 0 && !ctx.insideBeat) {
+    const n1 = ctx.declaredNodes[0];
+    const n2 = ctx.declaredNodes[1];
+    return {
+      text: `beat main "System Flow":
+  show $nodes stagger=60ms
+  ${n1.id} -> ${n2.id} "call"`,
+      insertText: `beat main "System Flow":
+  show $nodes stagger=60ms
+  ${n1.id} -> ${n2.id} "call"
+`,
+      description: "Initialize choreography with entrance animation and primary flow",
+      type: "init-beat"
+    };
+  }
+  if (ctx.insideBeat) {
+    const lines = docText.split(/\r?\n/);
+    const prevLine = lines[cursorLine - 1]?.trim() ?? "";
+    const reqMatch = /^([\w.-]+)\s*->\s*([\w.-]+)(?:\s+"([^"]*)")?/i.exec(prevLine);
+    if (reqMatch) {
+      const src = reqMatch[1];
+      const tgt = reqMatch[2];
+      return {
+        text: `  ${src} <- ${tgt} "200 OK"`,
+        insertText: `  ${src} <- ${tgt} "200 OK"
+`,
+        description: `Add response flow returning from ${tgt} to ${src}`,
+        type: "next-flow"
+      };
+    }
+    const eventMatch = /^([\w.-]+)\s*~>\s*([\w.-]+)/i.exec(prevLine);
+    if (eventMatch) {
+      const queueId = eventMatch[2];
+      const worker = ctx.declaredNodes.find((n) => nodeRole(n.kind) === "compute" && n.id !== eventMatch[1]);
+      if (worker) {
+        return {
+          text: `  ${queueId} ~> ${worker.id} "process"`,
+          insertText: `  ${queueId} ~> ${worker.id} "process"
+`,
+          description: `Deliver queued event from ${queueId} to worker ${worker.id}`,
+          type: "next-flow"
+        };
+      }
+    }
+    const keyNode = ctx.declaredNodes.find((n) => nodeRole(n.kind) === "compute" || nodeRole(n.kind) === "database") || ctx.declaredNodes[0];
+    if (keyNode) {
+      return {
+        text: `  pulse ${keyNode.id} color=#38bdf8`,
+        insertText: `  pulse ${keyNode.id} color=#38bdf8
+`,
+        description: `Add kinetic highlight pulse to ${keyNode.id}`,
+        type: "beat-cue"
+      };
+    }
+  }
+  const hasClient = ctx.declaredNodes.some((n) => isClientRole(n.kind));
+  const hasCompute = ctx.declaredNodes.some((n) => isComputeRole(n.kind) || isGatewayRole(n.kind));
+  const hasDB = ctx.declaredNodes.some((n) => isDatabaseKind(n.kind));
+  const hasCache = ctx.declaredNodes.some((n) => isCacheKind(n.kind));
+  const hasQueue = ctx.declaredNodes.some((n) => isQueueRole(n.kind));
+  if (hasCompute && !hasDB) {
+    return {
+      text: 'database Postgres "PostgreSQL 16"',
+      insertText: 'database Postgres "PostgreSQL 16"\n',
+      description: "Add a database tier to persist state for your services",
+      type: "next-node"
+    };
+  }
+  if (hasCompute && hasDB && !hasCache) {
+    return {
+      text: 'cache Redis "Redis Cluster"',
+      insertText: 'cache Redis "Redis Cluster"\n',
+      description: "Add an in-memory caching tier to accelerate query latency",
+      type: "next-node"
+    };
+  }
+  if (hasCompute && hasDB && !hasQueue) {
+    return {
+      text: 'queue Kafka "Kafka Event Stream"',
+      insertText: 'queue Kafka "Kafka Event Stream"\nworker AsyncWorker "Background Worker"\n',
+      description: "Add an asynchronous event queue and worker for decoupled processing",
+      type: "next-node"
+    };
+  }
+  return null;
+}
+function getArchitectureSuggestions(docText) {
+  const ctx = extractDiagramContext(docText, 0, 0);
+  const recommendations = [];
+  const nodeCount = ctx.declaredNodes.length;
+  if (nodeCount === 0) return recommendations;
+  const hasClient = ctx.declaredNodes.some((n) => isClientRole(n.kind));
+  const hasGateway = ctx.declaredNodes.some((n) => isGatewayRole(n.kind));
+  const hasServices = ctx.declaredNodes.filter((n) => isComputeRole(n.kind));
+  const hasDatabases = ctx.declaredNodes.filter((n) => isDatabaseKind(n.kind));
+  const hasCache = ctx.declaredNodes.some((n) => isCacheKind(n.kind));
+  const hasQueue = ctx.declaredNodes.some((n) => isQueueRole(n.kind));
+  const hasGroups = ctx.declaredGroups.length > 0;
+  const hasBeats = ctx.declaredBeats.length > 0;
+  if (hasClient && (hasServices.length > 0 || hasDatabases.length > 0) && !hasGateway) {
+    recommendations.push({
+      id: "add-gateway",
+      title: "Add API Gateway Perimeter",
+      desc: "Direct client-to-service connections bypass centralized rate-limiting and auth. Insert an API Gateway.",
+      snippet: 'gateway ApiGateway "Kong / Envoy Gateway"\n\nbeat route:\n  WebApp -> ApiGateway "HTTPS"\n',
+      category: "security",
+      actionLabel: "Insert Gateway"
+    });
+  }
+  if (hasDatabases.length > 0 && !hasCache) {
+    recommendations.push({
+      id: "add-cache",
+      title: "Add In-Memory Cache (Redis)",
+      desc: "Offload frequent read queries from your database with a sub-millisecond Redis cluster.",
+      snippet: 'cache Redis "Redis Cluster"\n\nbeat cache_layer:\n  ApiService -> Redis "cache.get"\n',
+      category: "performance",
+      actionLabel: "Insert Redis Cache"
+    });
+  }
+  if (hasServices.length >= 2 && !hasGroups) {
+    const memberIds = hasServices.map((s) => s.id).join(" ");
+    recommendations.push({
+      id: "add-group-boundary",
+      title: "Enclose Microservices in Group Boundary",
+      desc: "Group related backend microservices inside a secure VPC boundary perimeter.",
+      snippet: `group backend "Backend Microservices VPC": ${memberIds}
+`,
+      category: "structure",
+      actionLabel: "Add Group Boundary"
+    });
+  }
+  if (!hasBeats && nodeCount >= 2) {
+    const firstTwo = ctx.declaredNodes.slice(0, 2);
+    recommendations.push({
+      id: "add-entrance-beat",
+      title: "Add Animated Entrance Choreography",
+      desc: "Bring your architecture to life with staggered node reveals and motion flows.",
+      snippet: `beat reveal "System Entrance":
+  show $nodes stagger=60ms
+  ${firstTwo[0].id} -> ${firstTwo[1].id} "GET /api"
+`,
+      category: "choreography",
+      actionLabel: "Add Narrative Beat"
+    });
+  }
+  if (hasServices.length >= 2 && !hasQueue) {
+    recommendations.push({
+      id: "add-event-queue",
+      title: "Decouple Services with Event Queue",
+      desc: "Use an asynchronous event stream (Kafka/SQS) for resilient pub/sub event handling.",
+      snippet: 'queue Kafka "Kafka Event Bus"\nworker Worker "Event Consumer"\n\nbeat async_event:\n  ApiService ~> Kafka "event.published"\n  Kafka ~> Worker "process"\n',
+      category: "reliability",
+      actionLabel: "Add Kafka Queue"
+    });
+  }
+  return recommendations;
+}
 
 // ../compat/src/mermaid/mermaid-transpiler.ts
 function sanitizeId(id) {
@@ -3075,7 +4739,10 @@ function handleValidateMarkdy(code, checkArchitecture = true) {
       content: [{ type: "text", text: lines.join("\n") }]
     };
   } catch (error) {
-    const repairBundle = analyzeAndBuildRepairPrompt(code);
+    const report = diagnoseMarkdyCode(code, {
+      checkArchitecture,
+      transpileMermaid: (src) => transpileMermaidToMarkdy(src, "Imported Scene").code
+    });
     return {
       isError: true,
       content: [
@@ -3084,12 +4751,87 @@ function handleValidateMarkdy(code, checkArchitecture = true) {
           text: `\u274C Parse Error: ${error.message}
 
 Suggested AI Healing Prompt:
-${repairBundle.repairPrompt}`
+${report.repairPrompt}`
         }
       ]
     };
   }
 }
+function handleDiagnoseMarkdy(code, checkArchitecture = true) {
+  const report = diagnoseMarkdyCode(code, {
+    checkArchitecture,
+    transpileMermaid: (src) => transpileMermaidToMarkdy(src, "Imported Scene").code
+  });
+  const lines = [];
+  lines.push(report.summary);
+  if (report.issues.length > 0) {
+    const errors = report.issues.filter((i) => i.severity === "error");
+    const warnings = report.issues.filter((i) => i.severity === "warning");
+    if (errors.length > 0) {
+      lines.push("\n### \u274C Syntax Errors & Typos:");
+      for (const e of errors) {
+        lines.push(`- **[${e.code}]** Line ${e.line}: ${e.message}`);
+        if (e.snippet) lines.push(`  - *Problem:* \`${e.snippet}\``);
+        if (e.suggestion) lines.push(`  - *Recommendation:* ${e.suggestion}`);
+        if (e.didYouMean) lines.push(`  - *Did you mean:* \`${e.didYouMean}\`?`);
+      }
+    }
+    if (warnings.length > 0) {
+      lines.push("\n### \u26A0\uFE0F Warnings & Governance:");
+      for (const w of warnings) {
+        lines.push(`- **[${w.code}]** Line ${w.line}: ${w.message}`);
+        if (w.suggestion) lines.push(`  - *Recommendation:* ${w.suggestion}`);
+      }
+    }
+  }
+  if (report.repairedCode) {
+    lines.push("\n### \u{1F6E0}\uFE0F Proposed Auto-Repaired Code:");
+    lines.push("```markdy");
+    lines.push(report.repairedCode);
+    lines.push("```");
+  }
+  lines.push("\n### \u{1F4A1} AI Self-Healing Prompt for LLMs / Agents:");
+  lines.push(report.repairPrompt);
+  return {
+    isError: !report.isValid,
+    content: [{ type: "text", text: lines.join("\n") }]
+  };
+}
+function handleFixMarkdy(code) {
+  const result = repairMarkdyCode(code, {
+    transpileMermaid: (src) => transpileMermaidToMarkdy(src, "Imported Scene").code
+  });
+  const lines = [];
+  if (result.isFixed) {
+    lines.push(`\u2705 Markdy Code Repaired Successfully (${result.changes.length} change(s) applied):
+`);
+    for (const c of result.changes) {
+      lines.push(`- ${c}`);
+    }
+    lines.push("\n```markdy");
+    lines.push(result.repairedCode);
+    lines.push("```");
+  } else {
+    lines.push(`\u26A0\uFE0F Applied ${result.changes.length} automated repair(s), but additional manual corrections may be needed:
+`);
+    for (const c of result.changes) {
+      lines.push(`- ${c}`);
+    }
+    lines.push("\n```markdy");
+    lines.push(result.repairedCode);
+    lines.push("```");
+    const diag = diagnoseMarkdyCode(result.repairedCode);
+    if (!diag.isValid) {
+      lines.push("\nRemaining issues to resolve:");
+      for (const iss of diag.issues) {
+        lines.push(`- Line ${iss.line}: ${iss.message}`);
+      }
+    }
+  }
+  return {
+    content: [{ type: "text", text: lines.join("\n") }]
+  };
+}
 async function handleTranspileToMarkdy(source, format, title = "Imported Scene") {
   try {
     let markdyCode = "";
@@ -3211,6 +4953,45 @@ function handleGetArchitectureCatalog(filterCategory) {
     content: [{ type: "text", text }]
   };
 }
+function handleIntelliCode(code, line, column) {
+  const lines = code.split(/\r?\n/);
+  const targetLine = line !== void 0 ? line : Math.max(0, lines.length - 1);
+  const targetCol = column !== void 0 ? column : lines[targetLine]?.length ?? 0;
+  const completions = getIntelliCodeCompletions(code, targetLine, targetCol);
+  const nextLinePrediction = predictNextLineSuggestion(code, targetLine);
+  const archRecommendations = getArchitectureSuggestions(code);
+  const output = {
+    cursor: { line: targetLine, column: targetCol },
+    completionsCount: completions.length,
+    topCompletions: completions.slice(0, 20).map((c) => ({
+      label: c.label,
+      insertText: c.insertText,
+      kind: c.kind,
+      detail: c.detail,
+      documentation: c.documentation
+    })),
+    nextLinePrediction: nextLinePrediction ? {
+      suggestedText: nextLinePrediction.text,
+      description: nextLinePrediction.description,
+      type: nextLinePrediction.type
+    } : null,
+    architectureRecommendations: archRecommendations.map((r) => ({
+      id: r.id,
+      title: r.title,
+      description: r.desc,
+      category: r.category,
+      actionSnippet: r.snippet
+    }))
+  };
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(output, null, 2)
+      }
+    ]
+  };
+}
 function handleReadResource(uri) {
   switch (uri) {
     case "markdy://spec/agent-reference":
@@ -3248,6 +5029,30 @@ Cycle Safety: Always use <- for responses back to callers to prevent layout rank
           }
         ]
       };
+    case "markdy://spec/grammar-rules":
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: `# MarkdyScript Grammar & Diagnostic Rules
+
+### 1. The 4-Step Mental Model
+1. **Directives**: \`scene theme=paper width=1280 height=720\` and \`layout LR\` (or TB).
+2. **Nodes**: \`<kind> <Id> ["Human Label"]\` (e.g. \`browser Client "Shopper"\`, \`gateway GW "API Gateway"\`, \`service Orders\`, \`database DB\`).
+3. **Groups**: \`group <id> "<Label>": Node1 Node2\`
+4. **Beats**: \`beat <id> "<Caption>":\` containing indented flow lines and cues.
+
+### 2. Common Syntax Errors & Corrections
+- **Keyword typos**: \`scen\` -> \`scene\`, \`layput\` -> \`layout\`, \`groop\` -> \`group\`, \`bea\` -> \`beat\`.
+- **Node kind typos**: \`servce\` -> \`service\`, \`databse\` -> \`database\`, \`gateawy\` -> \`gateway\`, \`cach\` -> \`cache\`.
+- **Missing colons**: Always terminate \`beat <id> ["Caption"]:\` and \`group <id> ["Label"]:\` with a colon.
+- **Unquoted strings**: Labels containing spaces MUST be wrapped in double quotes (\`"...\`\`).
+- **Cycle safety**: NEVER use \`->\` for response or return paths. Use \`<-\` for return calls to prevent cycle overlap rank collapse.
+- **Cue placement**: Visual cues (\`show $nodes\`, \`glow\`, \`frame\`, \`focus\`) and flows must reside INSIDE an indented beat block.`
+          }
+        ]
+      };
     default:
       throw new Error(`Resource not found: ${uri}`);
   }
@@ -3290,6 +5095,38 @@ function createMarkdyMcpServer() {
             required: ["code"]
           }
         },
+        {
+          name: "diagnose_markdy_syntax",
+          description: "Deep diagnostic tool that analyzes MarkdyScript diagram syntax, detects typos in keywords/node kinds/operators/nodes, identifies flow cycle overlaps, unquoted strings, and provides 'Did you mean?' suggestions with auto-repaired code.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              code: {
+                type: "string",
+                description: "The MarkdyScript (.markdy) diagram code to inspect."
+              },
+              checkArchitecture: {
+                type: "boolean",
+                description: "Whether to include Well-Architected governance rules in the report. Default: true."
+              }
+            },
+            required: ["code"]
+          }
+        },
+        {
+          name: "fix_markdy_code",
+          description: "Automatically repairs common MarkdyScript syntax errors, typos, missing colons, invalid flow operators, unquoted strings, cycle return edges, and wraps top-level bare cues into a valid scene.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              code: {
+                type: "string",
+                description: "The broken or draft MarkdyScript diagram code to automatically repair."
+              }
+            },
+            required: ["code"]
+          }
+        },
         {
           name: "transpile_to_markdy",
           description: "Converts external infrastructure or diagram code (Mermaid, Docker Compose, Kubernetes manifests, Terraform state, or Draw.io XML) into animated MarkdyScript scenes.",
@@ -3353,6 +5190,28 @@ function createMarkdyMcpServer() {
               }
             }
           }
+        },
+        {
+          name: "get_markdy_intellicode",
+          description: "Provides zero-dependency intelligent code completion, predictive ghost-text next-line suggestions, and Well-Architected proactive recommendations for MarkdyScript diagrams.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              code: {
+                type: "string",
+                description: "The MarkdyScript diagram code."
+              },
+              line: {
+                type: "number",
+                description: "Optional 0-indexed line number where the cursor is positioned."
+              },
+              column: {
+                type: "number",
+                description: "Optional 0-indexed column character where the cursor is positioned."
+              }
+            },
+            required: ["code"]
+          }
         }
       ]
     };
@@ -3366,6 +5225,13 @@ function createMarkdyMcpServer() {
           String(safeArgs.code ?? ""),
           safeArgs.checkArchitecture !== false
         );
+      case "diagnose_markdy_syntax":
+        return handleDiagnoseMarkdy(
+          String(safeArgs.code ?? ""),
+          safeArgs.checkArchitecture !== false
+        );
+      case "fix_markdy_code":
+        return handleFixMarkdy(String(safeArgs.code ?? ""));
       case "transpile_to_markdy":
         return await handleTranspileToMarkdy(
           String(safeArgs.source ?? ""),
@@ -3378,6 +5244,12 @@ function createMarkdyMcpServer() {
         return handleGenerateMarkdyPrompt(String(safeArgs.userGoal ?? ""));
       case "get_architecture_catalog":
         return handleGetArchitectureCatalog(safeArgs.filterCategory ? String(safeArgs.filterCategory) : void 0);
+      case "get_markdy_intellicode":
+        return handleIntelliCode(
+          String(safeArgs.code ?? ""),
+          typeof safeArgs.line === "number" ? safeArgs.line : void 0,
+          typeof safeArgs.column === "number" ? safeArgs.column : void 0
+        );
       default:
         throw new Error(`Unknown tool: ${name}`);
     }
@@ -3391,6 +5263,12 @@ function createMarkdyMcpServer() {
           description: "Canonical reference for MarkdyScript syntax, closed node vocabularies, and cycle-safety rules.",
           mimeType: "text/markdown"
         },
+        {
+          uri: "markdy://spec/grammar-rules",
+          name: "MarkdyScript Grammar & Diagnostic Rules",
+          description: "Grammar conventions, typo resolution guides, and cycle-safe routing rules.",
+          mimeType: "text/markdown"
+        },
         {
           uri: "markdy://templates/catalog",
           name: "Markdy Architecture Templates Catalog",
@@ -3434,6 +5312,17 @@ function createMarkdyMcpServer() {
             }
           ]
         },
+        {
+          name: "debug_markdy_syntax",
+          description: "Diagnose, troubleshoot, and heal broken MarkdyScript syntax, typos, undefined node references, or flow cycles.",
+          arguments: [
+            {
+              name: "code",
+              description: "The broken or erroneous MarkdyScript code to diagnose and repair.",
+              required: true
+            }
+          ]
+        },
         {
           name: "audit_architecture",
           description: "Review a MarkdyScript diagram for Well-Architected governance, cycle overlap, and layer violations.",
@@ -3494,6 +5383,24 @@ Follow the canonical 4-step Markdy mental model:
           ]
         };
       }
+      case "debug_markdy_syntax": {
+        return {
+          description: "Diagnose and heal MarkdyScript syntax errors and typos",
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: `Please diagnose and repair the following MarkdyScript code. Check for keyword typos, invalid node kinds, unquoted strings, missing colons, undefined node references, and flow cycles:
+
+\`\`\`markdy
+${safeArgs.code}
+\`\`\``
+              }
+            }
+          ]
+        };
+      }
       case "audit_architecture": {
         return {
           description: "Audit Markdy diagram against Well-Architected rules",
@@ -3551,9 +5458,12 @@ if (isDirectExecution) {
 export {
   MCP_SERVER_VERSION,
   createMarkdyMcpServer,
+  handleDiagnoseMarkdy,
   handleExplainArchitecture,
+  handleFixMarkdy,
   handleGenerateMarkdyPrompt,
   handleGetArchitectureCatalog,
+  handleIntelliCode,
   handleReadResource,
   handleTranspileToMarkdy,
   handleValidateMarkdy,