@hegemonart/get-design-done 1.53.0 → 1.55.0

package/sdk/cli/index.js

@@ -850,6 +850,1082 @@ var require_incremental_discover = __commonJS({
   }
 });
 
+// scripts/lib/detect/rules/ban-01.cjs
+var require_ban_01 = __commonJS({
+  "scripts/lib/detect/rules/ban-01.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "border-left:\\s*[2-9][0-9]*px|border-right:\\s*[2-9][0-9]*px";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-01",
+      category: "decoration",
+      name: "Side-Stripe Borders",
+      description: "A thick (>=2px) left/right accent border \u2014 a dated, decorative side-stripe.",
+      references: ["reference/anti-patterns.md#BAN-01"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-02.cjs
+var require_ban_02 = __commonJS({
+  "scripts/lib/detect/rules/ban-02.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "background-clip:\\s*text|text-fill-color:\\s*transparent";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-02",
+      category: "decoration",
+      name: "Gradient Text",
+      description: "Gradient-filled text via background-clip:text \u2014 low legibility, an AI-era cliche.",
+      references: ["reference/anti-patterns.md#BAN-02"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-03.cjs
+var require_ban_03 = __commonJS({
+  "scripts/lib/detect/rules/ban-03.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "cubic-bezier\\(.*-[0-9]|bounce|elastic|spring\\(";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-03",
+      category: "motion",
+      name: "Bounce/Elastic Easing",
+      description: "Bounce/elastic/spring easing \u2014 playful overshoot that reads as unserious for product UI.",
+      references: ["reference/anti-patterns.md#BAN-03"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-05.cjs
+var require_ban_05 = __commonJS({
+  "scripts/lib/detect/rules/ban-05.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "background.*#000000|background.*rgb\\(0,\\s*0,\\s*0\\)";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-05",
+      category: "color",
+      name: "Pure Black Dark Mode",
+      description: "Pure #000 dark-mode background \u2014 harsh contrast + halation; use a near-black surface.",
+      references: ["reference/anti-patterns.md#BAN-05"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-06.cjs
+var require_ban_06 = __commonJS({
+  "scripts/lib/detect/rules/ban-06.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "user-scalable=no|maximum-scale=1";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-06",
+      category: "accessibility",
+      name: "Disabling Zoom",
+      description: "Viewport meta that disables pinch-zoom \u2014 a WCAG 1.4.4 failure.",
+      references: ["reference/anti-patterns.md#BAN-06"],
+      severity: "error",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-07.cjs
+var require_ban_07 = __commonJS({
+  "scripts/lib/detect/rules/ban-07.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = ":focus\\s*\\{[^}]*outline:\\s*(none|0)";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-07",
+      category: "accessibility",
+      name: "Naked outline: none",
+      description: "Removing the focus outline without a replacement \u2014 a keyboard-a11y failure.",
+      references: ["reference/anti-patterns.md#BAN-07"],
+      severity: "error",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-08.cjs
+var require_ban_08 = __commonJS({
+  "scripts/lib/detect/rules/ban-08.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "transition:\\s*all\\s";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-08",
+      category: "motion",
+      name: "transition: all",
+      description: "transition: all animates layout-triggering properties \u2014 jank; name the exact properties.",
+      references: ["reference/anti-patterns.md#BAN-08"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-09.cjs
+var require_ban_09 = __commonJS({
+  "scripts/lib/detect/rules/ban-09.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "transform:\\s*scale\\(\\s*0\\s*\\)|scale\\(\\s*0\\s*\\)";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-09",
+      category: "motion",
+      name: "scale(0) Animation Entry",
+      description: "Entering from scale(0) \u2014 nothing materializes from nothing; start at scale(0.95)+opacity.",
+      references: ["reference/anti-patterns.md#BAN-09"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-11.cjs
+var require_ban_11 = __commonJS({
+  "scripts/lib/detect/rules/ban-11.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "outline-(slate|zinc|neutral|gray|stone|blue|red|green|yellow|purple)-\\d+|img\\s*\\{[^}]*outline:\\s*[^}]*#[0-9a-fA-F]{3,8}";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-11",
+      category: "decoration",
+      name: "Tinted Image Outline",
+      description: "A colored outline on an image \u2014 color contamination; use low-opacity black/white.",
+      references: ["reference/anti-patterns.md#BAN-11"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-12.cjs
+var require_ban_12 = __commonJS({
+  "scripts/lib/detect/rules/ban-12.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "transition:\\s*all|transition-property:\\s*all";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-12",
+      category: "motion",
+      name: "transition: all (property)",
+      description: "transition: all / transition-property: all \u2014 recalculates layout every transition.",
+      references: ["reference/anti-patterns.md#BAN-12"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/ban-13.cjs
+var require_ban_13 = __commonJS({
+  "scripts/lib/detect/rules/ban-13.cjs"(exports2, module2) {
+    "use strict";
+    var PATTERN = "will-change:\\s*all";
+    function matcher(ctx) {
+      const out = [];
+      const re = new RegExp(PATTERN, "gi");
+      const text = String(ctx && ctx.content || "");
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        const upto = text.slice(0, m.index);
+        const line = upto.split("\n").length;
+        const lastNl = upto.lastIndexOf("\n");
+        const column = lastNl < 0 ? m.index + 1 : m.index - lastNl;
+        out.push({ line, column, match: m[0] });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      return out;
+    }
+    module2.exports = {
+      id: "BAN-13",
+      category: "performance",
+      name: "will-change: all",
+      description: "will-change: all promotes every property to its own GPU layer \u2014 huge texture memory.",
+      references: ["reference/anti-patterns.md#BAN-13"],
+      severity: "warn",
+      pattern: PATTERN,
+      matcher
+    };
+  }
+});
+
+// scripts/lib/detect/rules/index.cjs
+var require_rules = __commonJS({
+  "scripts/lib/detect/rules/index.cjs"(exports2, module2) {
+    "use strict";
+    var r0 = require_ban_01();
+    var r1 = require_ban_02();
+    var r2 = require_ban_03();
+    var r3 = require_ban_05();
+    var r4 = require_ban_06();
+    var r5 = require_ban_07();
+    var r6 = require_ban_08();
+    var r7 = require_ban_09();
+    var r8 = require_ban_11();
+    var r9 = require_ban_12();
+    var r10 = require_ban_13();
+    var RULES = [r0, r1, r2, r3, r4, r5, r6, r7, r8, r9, r10];
+    var EXEMPT = Object.freeze(["BAN-04", "BAN-10"]);
+    module2.exports = { RULES, EXEMPT };
+  }
+});
+
+// scripts/lib/detect/engine.cjs
+var require_engine = __commonJS({
+  "scripts/lib/detect/engine.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("node:fs");
+    var path = require("node:path");
+    var { RULES, EXEMPT } = require_rules();
+    var SCANNABLE_EXT = /* @__PURE__ */ new Set([".html", ".htm", ".css", ".scss", ".jsx", ".tsx", ".js", ".ts", ".vue", ".svelte"]);
+    var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", ".design", ".planning"]);
+    function walk(root) {
+      const out = [];
+      if (!fs.existsSync(root)) return out;
+      const st = fs.statSync(root);
+      if (st.isFile()) {
+        if (SCANNABLE_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+        return out;
+      }
+      const stack = [root];
+      while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+          entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          continue;
+        }
+        for (const e of entries) {
+          const full = path.join(dir, e.name);
+          if (e.isDirectory()) {
+            if (!SKIP_DIRS.has(e.name)) stack.push(full);
+          } else if (e.isFile() && SCANNABLE_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+        }
+      }
+      return out;
+    }
+    function selectRules(ruleId) {
+      if (!ruleId) return RULES;
+      const id = String(ruleId).toUpperCase();
+      return RULES.filter((r) => r.id === id);
+    }
+    function scanContent(content, ctx, rules) {
+      const findings = [];
+      for (const rule of rules) {
+        let hits = [];
+        try {
+          hits = rule.matcher({ content, ext: ctx.ext, path: ctx.path }) || [];
+        } catch {
+          hits = [];
+        }
+        for (const h of hits) {
+          findings.push({
+            ruleId: rule.id,
+            category: rule.category,
+            name: rule.name,
+            severity: rule.severity,
+            file: ctx.path,
+            line: h.line,
+            column: h.column,
+            match: h.match,
+            references: rule.references
+          });
+        }
+      }
+      return findings;
+    }
+    function run6(root, opts) {
+      const o = opts || {};
+      const rules = selectRules(o.ruleId);
+      const cwd = o.cwd || process.cwd();
+      const files = walk(root);
+      const findings = [];
+      let errors = 0;
+      for (const abs of files) {
+        let content;
+        try {
+          content = fs.readFileSync(abs, "utf8");
+        } catch {
+          errors++;
+          continue;
+        }
+        const rel = path.relative(cwd, abs).split(path.sep).join("/");
+        findings.push(...scanContent(content, { path: rel || abs, ext: path.extname(abs).toLowerCase() }, rules));
+      }
+      findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId));
+      return { findings, filesScanned: files.length, errors, rules: rules.length };
+    }
+    module2.exports = { run: run6, walk, scanContent, selectRules, RULES, EXEMPT, SCANNABLE_EXT, SKIP_DIRS };
+  }
+});
+
+// scripts/lib/detect/stack.cjs
+var require_stack = __commonJS({
+  "scripts/lib/detect/stack.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("node:fs");
+    var path = require("node:path");
+    var { walk, SKIP_DIRS } = require_engine();
+    function readDeps(root) {
+      const pkgPath = path.basename(String(root || "")) === "package.json" ? root : path.join(root || ".", "package.json");
+      let raw;
+      try {
+        raw = fs.readFileSync(pkgPath, "utf8");
+      } catch {
+        return { deps: {}, present: false, error: null };
+      }
+      let pkg;
+      try {
+        pkg = JSON.parse(raw);
+      } catch (e) {
+        return { deps: {}, present: true, error: "package.json is not valid JSON" + (e && e.message ? `: ${e.message}` : "") };
+      }
+      if (!pkg || typeof pkg !== "object") {
+        return { deps: {}, present: true, error: "package.json did not parse to an object" };
+      }
+      const deps = {};
+      for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const m = pkg[field];
+        if (m && typeof m === "object" && !Array.isArray(m)) {
+          for (const k of Object.keys(m)) deps[k] = m[k];
+        }
+      }
+      return { deps, present: true, error: null };
+    }
+    function hasDep(deps, name) {
+      return Object.prototype.hasOwnProperty.call(deps, name);
+    }
+    function hasDepPrefix(deps, prefix) {
+      for (const k of Object.keys(deps)) {
+        if (k === prefix || k.startsWith(prefix)) return true;
+      }
+      return false;
+    }
+    function hasTopLevelFile(root, names) {
+      let entries;
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        return false;
+      }
+      const set = new Set(entries.filter((e) => e.isFile()).map((e) => e.name));
+      for (const n of names) if (set.has(n)) return true;
+      return false;
+    }
+    function hasTopLevelConfig(root, stem) {
+      let entries;
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        return false;
+      }
+      const prefix = stem + ".";
+      for (const e of entries) {
+        if (e.isFile() && e.name.startsWith(prefix)) return true;
+      }
+      return false;
+    }
+    function hasTopLevelDir(root, name) {
+      try {
+        const st = fs.statSync(path.join(root, name));
+        return st.isDirectory();
+      } catch {
+        return false;
+      }
+    }
+    function findFileMatching(root, re) {
+      let files;
+      try {
+        files = walk(root);
+      } catch {
+        return null;
+      }
+      for (const abs of files) {
+        if (re.test(path.basename(abs))) return relish(root, abs);
+      }
+      return null;
+    }
+    function findContentMatching(root, re, fileFilter) {
+      let files;
+      try {
+        files = walk(root);
+      } catch {
+        return null;
+      }
+      for (const abs of files) {
+        if (fileFilter && !fileFilter(abs)) continue;
+        let text;
+        try {
+          text = fs.readFileSync(abs, "utf8");
+        } catch {
+          continue;
+        }
+        const m = re.exec(text);
+        if (m) return { file: relish(root, abs), match: m[0] };
+      }
+      return null;
+    }
+    function relish(root, abs) {
+      const rel = path.relative(root, abs);
+      return (rel || abs).split(path.sep).join("/");
+    }
+    var DS_PROBES = [
+      {
+        id: "shadcn",
+        // shadcn is a tailwind super-set: detect it FIRST so a shadcn project (which also
+        // ships tailwind) is labeled shadcn rather than the more generic tailwind.
+        detect(root, deps) {
+          const hasComponentsJson = hasTopLevelFile(root, ["components.json"]);
+          const cnHit = hasComponentsJson ? null : findContentMatching(root, /\bcn\s*\(/, (abs) => /utils\.(t|j)sx?$/.test(abs.split(path.sep).join("/")));
+          if (hasComponentsJson) return { ev: "components.json present (shadcn/ui)" };
+          if (cnHit) return { ev: `cn() helper in ${cnHit.file} (shadcn/ui)` };
+          return null;
+        }
+      },
+      {
+        id: "tailwind",
+        detect(root, deps) {
+          if (hasDep(deps, "tailwindcss")) return { ev: "tailwindcss in dependencies" };
+          if (hasTopLevelConfig(root, "tailwind.config")) return { ev: "tailwind.config.* present" };
+          const themeHit = findContentMatching(root, /@theme\b/, (abs) => /\.css$/.test(abs));
+          if (themeHit) return { ev: `@theme directive in ${themeHit.file} (tailwind v4)` };
+          return null;
+        }
+      },
+      {
+        id: "radix-themes",
+        detect(root, deps) {
+          if (hasDep(deps, "@radix-ui/themes")) return { ev: "@radix-ui/themes in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "mui",
+        detect(root, deps) {
+          if (hasDep(deps, "@mui/material")) return { ev: "@mui/material in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "chakra",
+        detect(root, deps) {
+          if (hasDep(deps, "@chakra-ui/react")) return { ev: "@chakra-ui/react in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "vanilla-extract",
+        detect(root, deps) {
+          if (hasDep(deps, "@vanilla-extract/css")) return { ev: "@vanilla-extract/css in dependencies" };
+          const cssTs = findFileMatching(root, /\.css\.ts$/);
+          if (cssTs) return { ev: `*.css.ts file ${cssTs} (vanilla-extract)` };
+          return null;
+        }
+      },
+      {
+        id: "styled-components",
+        detect(root, deps) {
+          if (hasDep(deps, "styled-components")) return { ev: "styled-components in dependencies" };
+          return null;
+        }
+      },
+      {
+        id: "css-modules",
+        // Weakest signal (a plain file pattern, no dep). Last so any explicit DS wins over it.
+        detect(root, deps) {
+          const mod = findFileMatching(root, /\.module\.css$/);
+          if (mod) return { ev: `*.module.css file ${mod} (CSS Modules)` };
+          return null;
+        }
+      }
+    ];
+    function detectDs(root, deps) {
+      for (const probe of DS_PROBES) {
+        let res = null;
+        try {
+          res = probe.detect(root, deps);
+        } catch {
+          res = null;
+        }
+        if (res) return { ds: probe.id, evidence: res.ev };
+      }
+      return { ds: null, evidence: "no design-system signal (no known DS dep, config file, or file pattern)" };
+    }
+    function detectFramework(root, deps) {
+      if (hasDep(deps, "next")) {
+        const router = hasTopLevelDir(root, "app") ? "app-router" : hasTopLevelDir(root, "pages") ? "pages-router" : hasTopLevelDir(root, "src") && hasTopLevelDir(path.join(root, "src"), "app") ? "app-router (src/)" : "router undetermined";
+        return { framework: "nextjs", evidence: `next in dependencies (${router})` };
+      }
+      if (hasDepPrefix(deps, "@remix-run/")) {
+        return { framework: "remix", evidence: "@remix-run/* in dependencies" };
+      }
+      if (hasDep(deps, "astro") || hasTopLevelConfig(root, "astro.config")) {
+        return { framework: "astro", evidence: hasDep(deps, "astro") ? "astro in dependencies" : "astro.config.* present" };
+      }
+      if (hasDep(deps, "@sveltejs/kit") || hasTopLevelConfig(root, "svelte.config")) {
+        return {
+          framework: "sveltekit",
+          evidence: hasDep(deps, "@sveltejs/kit") ? "@sveltejs/kit in dependencies" : "svelte.config.* present"
+        };
+      }
+      if (hasDep(deps, "storybook") || hasDepPrefix(deps, "@storybook/")) {
+        return { framework: "storybook", evidence: "storybook / @storybook/* in dependencies" };
+      }
+      if ((hasDep(deps, "vite") || hasTopLevelConfig(root, "vite.config")) && (hasDep(deps, "react") || hasDep(deps, "react-dom"))) {
+        return { framework: "vite-react", evidence: "vite + react in dependencies (no next/remix/astro/sveltekit)" };
+      }
+      return { framework: null, evidence: "no framework signal (no next/remix/vite-react/astro/sveltekit/storybook)" };
+    }
+    var MOTION_PROBES = [
+      {
+        id: "framer-motion",
+        detect(deps) {
+          if (hasDep(deps, "framer-motion")) return "framer-motion in dependencies";
+          if (hasDep(deps, "motion")) return "motion in dependencies (framer-motion v11+)";
+          return null;
+        }
+      },
+      {
+        id: "gsap",
+        detect(deps) {
+          if (hasDep(deps, "gsap")) return "gsap in dependencies";
+          return null;
+        }
+      },
+      {
+        id: "motion-one",
+        detect(deps) {
+          if (hasDepPrefix(deps, "@motionone/")) return "@motionone/* in dependencies";
+          return null;
+        }
+      },
+      {
+        id: "react-spring",
+        detect(deps) {
+          if (hasDep(deps, "react-spring") || hasDepPrefix(deps, "@react-spring/")) return "react-spring / @react-spring/* in dependencies";
+          return null;
+        }
+      }
+    ];
+    function detectMotion(deps) {
+      const libs = [];
+      const evidence = [];
+      for (const probe of MOTION_PROBES) {
+        let ev = null;
+        try {
+          ev = probe.detect(deps);
+        } catch {
+          ev = null;
+        }
+        if (ev) {
+          libs.push(probe.id);
+          evidence.push(`${probe.id}: ${ev}`);
+        }
+      }
+      return { motion_libs: libs, evidence };
+    }
+    function detectStack2(root) {
+      const dir = root || process.cwd();
+      const evidence = {};
+      let exists = false;
+      try {
+        exists = fs.existsSync(dir);
+      } catch {
+        exists = false;
+      }
+      if (!exists) {
+        return {
+          ds: null,
+          framework: null,
+          motion_libs: [],
+          evidence: { note: `root path does not exist: ${dir}` }
+        };
+      }
+      const { deps, present, error } = readDeps(dir);
+      if (!present) evidence.note = "no package.json at root \u2014 relying on config-file + file-pattern probes only";
+      else if (error) evidence.note = `${error} \u2014 relying on config-file + file-pattern probes only`;
+      let ds = null;
+      let framework = null;
+      let motion_libs = [];
+      try {
+        const dsr = detectDs(dir, deps);
+        ds = dsr.ds;
+        evidence.ds = dsr.evidence;
+      } catch (e) {
+        evidence.ds = "ds detection error: " + (e && e.message ? e.message : String(e));
+      }
+      try {
+        const fwr = detectFramework(dir, deps);
+        framework = fwr.framework;
+        evidence.framework = fwr.evidence;
+      } catch (e) {
+        evidence.framework = "framework detection error: " + (e && e.message ? e.message : String(e));
+      }
+      try {
+        const mr = detectMotion(deps);
+        motion_libs = mr.motion_libs;
+        evidence.motion = mr.evidence;
+      } catch (e) {
+        evidence.motion = ["motion detection error: " + (e && e.message ? e.message : String(e))];
+      }
+      return { ds, framework, motion_libs, evidence };
+    }
+    var HELP = `gdd stack detection \u2014 fingerprint a project's design-system / framework / motion stack.
+
+Usage:
+  detect-stack [root] [options]
+
+Arguments:
+  [root]            Project directory to scan (defaults to the current directory).
+
+Options:
+  --json            Machine-readable JSON (default).
+  --pretty          Pretty-printed human summary.
+  -h, --help        This help.
+
+Always exits 0 \u2014 an undetected stack is reported, not an error.`;
+    function parseArgs2(argv) {
+      const opts = { root: null, json: true, pretty: false, help: false };
+      for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json") opts.json = true;
+        else if (a === "--pretty") {
+          opts.pretty = true;
+          opts.json = false;
+        } else if (a === "-h" || a === "--help") opts.help = true;
+        else if (!a.startsWith("-") && opts.root === null) opts.root = a;
+      }
+      return opts;
+    }
+    function renderPretty(res) {
+      const lines = [];
+      lines.push("gdd stack:");
+      lines.push(`  design-system : ${res.ds || "(none detected)"}`);
+      lines.push(`  framework     : ${res.framework || "(none detected)"}`);
+      lines.push(`  motion        : ${res.motion_libs.length ? res.motion_libs.join(", ") : "(none detected)"}`);
+      if (res.evidence && res.evidence.note) lines.push(`  note          : ${res.evidence.note}`);
+      return lines.join("\n");
+    }
+    function main2(argv, io) {
+      const o = io || {};
+      const log = o.log || ((s) => process.stdout.write(s + "\n"));
+      const opts = parseArgs2(argv);
+      if (opts.help) {
+        log(HELP);
+        return 0;
+      }
+      const root = opts.root || o.cwd || process.cwd();
+      const res = detectStack2(root);
+      if (opts.pretty) log(renderPretty(res));
+      else log(JSON.stringify(res, null, 2));
+      return 0;
+    }
+    module2.exports = {
+      detectStack: detectStack2,
+      main: main2,
+      // internals exported for unit reuse / introspection (kept stable for executors B & F).
+      readDeps,
+      hasDep,
+      hasDepPrefix,
+      detectDs,
+      detectFramework,
+      detectMotion,
+      parseArgs: parseArgs2,
+      HELP,
+      SKIP_DIRS
+    };
+    if (require.main === module2) process.exit(main2(process.argv.slice(2)));
+  }
+});
+
+// scripts/lib/mapper-spawn.cjs
+var require_mapper_spawn = __commonJS({
+  "scripts/lib/mapper-spawn.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("node:fs");
+    var path = require("node:path");
+    var BLOCK_HEADER = "## Stack-specific guidance";
+    var ADDENDUM_SEPARATOR = "\n\n---\n\n";
+    var CATEGORY_ORDER = ["system", "framework", "motion"];
+    function normKey(value) {
+      return typeof value === "string" ? value.trim().toLowerCase() : "";
+    }
+    function baseNameNoExt(p) {
+      if (typeof p !== "string" || p.length === 0) return "";
+      const tail2 = p.replace(/\\/g, "/").split("/").pop() || "";
+      return tail2.replace(/\.md$/i, "");
+    }
+    function classifyEntry(entry) {
+      let category = null;
+      const explicitKind = normKey(entry.kind || entry.category);
+      if (explicitKind === "system" || explicitKind === "ds" || explicitKind === "design-system") {
+        category = "system";
+      } else if (explicitKind === "framework") {
+        category = "framework";
+      } else if (explicitKind === "motion") {
+        category = "motion";
+      } else if (typeof entry.path === "string") {
+        const p = entry.path.replace(/\\/g, "/");
+        if (/(^|\/)reference\/systems\//i.test(p) || /(^|\/)systems\//i.test(p)) category = "system";
+        else if (/(^|\/)reference\/frameworks\//i.test(p) || /(^|\/)frameworks\//i.test(p)) category = "framework";
+        else if (/(^|\/)reference\/motion\//i.test(p) || /(^|\/)motion\//i.test(p)) category = "motion";
+      }
+      let key = normKey(entry.stack);
+      if (key === "") key = normKey(baseNameNoExt(entry.path));
+      if (key === "") {
+        const nameParts = normKey(entry.name).split("-").filter(Boolean);
+        key = nameParts.length > 0 ? nameParts[nameParts.length - 1] : "";
+      }
+      return { category, key };
+    }
+    function composesInto(entry, mapperName) {
+      if (!entry || entry.type !== "stack-addendum") return false;
+      const list = entry.composes_into;
+      if (!Array.isArray(list)) return false;
+      return list.some((m) => normKey(m) === normKey(mapperName));
+    }
+    function readAddendumBody(entry, refDir) {
+      if (typeof entry.path !== "string" || entry.path.length === 0) return null;
+      const rel = entry.path.replace(/\\/g, "/");
+      const candidates = [];
+      if (path.isAbsolute(rel)) {
+        candidates.push(rel);
+      } else {
+        candidates.push(path.resolve(refDir, rel));
+        const stripped = rel.replace(/^reference\//i, "");
+        if (stripped !== rel) candidates.push(path.resolve(refDir, stripped));
+      }
+      for (const abs of candidates) {
+        let body;
+        try {
+          body = fs.readFileSync(abs, "utf8");
+        } catch {
+          continue;
+        }
+        const trimmed = body.replace(/\s+$/, "").replace(/^/, "");
+        if (trimmed.trim().length > 0) return trimmed;
+      }
+      return null;
+    }
+    function composeAddendums(mapperName, stack, opts) {
+      const used = [];
+      const missing = [];
+      const empty = () => ({ block: "", used, missing });
+      const o = opts || {};
+      const cap = Number.isInteger(o.cap) && o.cap >= 0 ? o.cap : 3;
+      const refDir = typeof o.refDir === "string" && o.refDir.length > 0 ? o.refDir : process.cwd();
+      if (!stack || typeof stack !== "object" || cap === 0) return empty();
+      const registry = o.registry;
+      const entries = registry && Array.isArray(registry.entries) ? registry.entries : [];
+      const detected = {
+        system: normKey(stack.ds),
+        framework: normKey(stack.framework),
+        // motion is a list; take the first non-empty entry (cap allows only one
+        // motion addendum, so the leading detected lib wins).
+        motion: Array.isArray(stack.motion_libs) ? normKey(stack.motion_libs.find((m) => normKey(m) !== "")) : ""
+      };
+      const candidates = [];
+      for (const entry of entries) {
+        if (!composesInto(entry, mapperName)) continue;
+        const { category, key } = classifyEntry(entry);
+        if (category === null || key === "") continue;
+        candidates.push({ entry, category, key });
+      }
+      const bodies = [];
+      for (const category of CATEGORY_ORDER) {
+        if (used.length >= cap) break;
+        const want = detected[category];
+        if (want === "") continue;
+        const hit = candidates.find((c) => c.category === category && c.key === want);
+        if (!hit) {
+          missing.push(want);
+          continue;
+        }
+        const body = readAddendumBody(hit.entry, refDir);
+        if (body === null) {
+          missing.push(want);
+          continue;
+        }
+        bodies.push(body);
+        used.push(typeof hit.entry.name === "string" && hit.entry.name.length > 0 ? hit.entry.name : hit.key);
+      }
+      if (bodies.length === 0) return empty();
+      const block = `${BLOCK_HEADER}
+
+${bodies.join(ADDENDUM_SEPARATOR)}`;
+      return { block, used, missing };
+    }
+    function applyAddendums2(spec, stack, opts) {
+      if (!spec || typeof spec !== "object") {
+        return { spec, block: "", used: [], missing: [] };
+      }
+      const mapperName = typeof spec.name === "string" ? spec.name : "";
+      const { block, used, missing } = composeAddendums(mapperName, stack, opts);
+      if (block !== "") {
+        const base = typeof spec.prompt === "string" ? spec.prompt : "";
+        spec.prompt = base === "" ? block : `${base}
+
+${block}`;
+      }
+      return { spec, block, used, missing };
+    }
+    module2.exports = {
+      composeAddendums,
+      applyAddendums: applyAddendums2,
+      // Exported for unit-level coverage + reuse by the runner wiring (executor F).
+      classifyEntry,
+      composesInto,
+      BLOCK_HEADER
+    };
+  }
+});
+
+// scripts/lib/reference-registry.cjs
+var require_reference_registry = __commonJS({
+  "scripts/lib/reference-registry.cjs"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var REPO_ROOT2 = path.resolve(__dirname, "..", "..");
+    var DEFAULT_REGISTRY_PATH = path.join(REPO_ROOT2, "reference", "registry.json");
+    var _cache = null;
+    var _cachePath = null;
+    function loadRegistry({ cwd } = {}) {
+      const p = cwd ? path.join(cwd, "reference", "registry.json") : DEFAULT_REGISTRY_PATH;
+      if (_cache && _cachePath === p) return _cache;
+      _cachePath = p;
+      _cache = JSON.parse(fs.readFileSync(p, "utf8"));
+      return _cache;
+    }
+    function list({ type, cwd } = {}) {
+      const reg = loadRegistry({ cwd });
+      if (!type) return reg.entries.slice();
+      return reg.entries.filter((e) => e.type === type);
+    }
+    function find(name, { cwd } = {}) {
+      const reg = loadRegistry({ cwd });
+      return reg.entries.find((e) => e.name === name) || null;
+    }
+    function validateRegistry({ cwd } = {}) {
+      const root = cwd || REPO_ROOT2;
+      const refDir = path.join(root, "reference");
+      const reg = (() => {
+        try {
+          return JSON.parse(fs.readFileSync(path.join(refDir, "registry.json"), "utf8"));
+        } catch {
+          return { entries: [] };
+        }
+      })();
+      const onDisk = /* @__PURE__ */ new Set();
+      for (const leaf of walk(refDir)) {
+        const rel = path.relative(root, leaf).replace(/\\/g, "/");
+        if (rel === "reference/registry.json") continue;
+        if (rel.endsWith(".schema.json")) continue;
+        if (rel.startsWith("reference/schemas/")) continue;
+        if (rel.startsWith("reference/data/")) continue;
+        if (!/\.(md|json)$/.test(rel)) continue;
+        onDisk.add(rel);
+      }
+      const registryPaths = new Set(reg.entries.map((e) => e.path));
+      const missingInRegistry = [...onDisk].filter((p) => !registryPaths.has(p)).sort();
+      const danglingInRegistry = reg.entries.filter((e) => !fs.existsSync(path.join(root, e.path))).map((e) => ({ name: e.name, path: e.path }));
+      const nameCount = {}, pathCount = {};
+      for (const e of reg.entries) {
+        nameCount[e.name] = (nameCount[e.name] || 0) + 1;
+        pathCount[e.path] = (pathCount[e.path] || 0) + 1;
+      }
+      const duplicates = [];
+      for (const [k, v] of Object.entries(nameCount)) if (v > 1) duplicates.push({ kind: "name", key: k, count: v });
+      for (const [k, v] of Object.entries(pathCount)) if (v > 1) duplicates.push({ kind: "path", key: k, count: v });
+      return {
+        ok: missingInRegistry.length === 0 && danglingInRegistry.length === 0 && duplicates.length === 0,
+        missingInRegistry,
+        danglingInRegistry,
+        duplicates
+      };
+    }
+    function* walk(dir) {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) yield* walk(full);
+        else if (e.isFile()) yield full;
+      }
+    }
+    module2.exports = { list, find, validateRegistry, loadRegistry };
+  }
+});
+
 // sdk/cli/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -5884,6 +6960,8 @@ var import_node_path14 = require("node:path");
 var import_node_path12 = require("node:path");
 var import_concurrency_tuner = __toESM(require_concurrency_tuner());
 var import_incremental_discover = __toESM(require_incremental_discover());
+var import_stack = __toESM(require_stack());
+var import_mapper_spawn = __toESM(require_mapper_spawn());
 
 // scripts/lib/explore-parallel-runner/mappers.ts
 var import_node_fs12 = require("node:fs");
@@ -6221,11 +7299,67 @@ var DEFAULT_MAPPERS = Object.freeze([
     prompt: "Describe z-order, focal points, and attention grammar. Output to .design/map/visual-hierarchy.md \u2014 one section per surface describing layering, emphasis, and scan path."
   })
 ]);
+function agentNameOf(spec) {
+  const base = spec.agentPath.replace(/\\/g, "/").split("/").pop()?.replace(/\.md$/i, "");
+  return base && base.length > 0 ? base : spec.name;
+}
+function composeMapperSpecs(specs, cwd, addendumOpts, logger) {
+  const missingByMapper = {};
+  const opt = addendumOpts ?? {};
+  if (opt.enabled === false) return { specs, missingByMapper };
+  try {
+    const root = typeof opt.root === "string" ? opt.root : cwd;
+    const detect = typeof opt.detectStack === "function" ? opt.detectStack : import_stack.detectStack;
+    const stack = detect(root);
+    let registry = opt.registry;
+    const refDir = typeof opt.refDir === "string" ? opt.refDir : (0, import_node_path12.resolve)(cwd, "reference");
+    if (registry === void 0) {
+      try {
+        const { loadRegistry } = require_reference_registry();
+        registry = loadRegistry({ cwd });
+      } catch {
+        registry = void 0;
+      }
+    }
+    let anyChanged = false;
+    const recomposed = specs.map((spec) => {
+      const agentName = agentNameOf(spec);
+      const carrier = { name: agentName, prompt: spec.prompt };
+      const { block, missing } = (0, import_mapper_spawn.applyAddendums)(carrier, stack, {
+        registry,
+        refDir
+      });
+      if (Array.isArray(missing) && missing.length > 0) {
+        missingByMapper[agentName] = missing;
+      }
+      if (block && block.length > 0 && carrier.prompt !== spec.prompt) {
+        anyChanged = true;
+        return Object.freeze({ ...spec, prompt: carrier.prompt });
+      }
+      return spec;
+    });
+    if (anyChanged) {
+      logger.info("explore.runner.addendums_composed", {
+        mappers_augmented: recomposed.filter((s, i) => s !== specs[i]).length,
+        ds: stack && stack.ds ? stack.ds : null,
+        framework: stack && stack.framework ? stack.framework : null,
+        motion_libs: stack && Array.isArray(stack.motion_libs) ? stack.motion_libs.length : 0
+      });
+      return { specs: Object.freeze(recomposed), missingByMapper };
+    }
+    return { specs, missingByMapper };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.warn("explore.runner.addendums_failed", { message });
+    return { specs, missingByMapper };
+  }
+}
 async function run3(opts) {
-  const specs = opts.mappers ?? DEFAULT_MAPPERS;
+  const baseSpecs = opts.mappers ?? DEFAULT_MAPPERS;
   const cwd = opts.cwd ?? process.cwd();
   const concurrency = opts.concurrency ?? (0, import_concurrency_tuner.resolveConcurrency)();
   const logger = getLogger().child("explore.runner");
+  const { specs } = composeMapperSpecs(baseSpecs, cwd, opts.addendums, logger);
   const outputPath = (0, import_node_path12.resolve)(cwd, ".design/DESIGN-PATTERNS.md");
   let batching = void 0;
   if (opts.incremental && opts.incremental.graph !== void 0 && opts.incremental.graph !== null) {
@@ -8448,6 +9582,252 @@ ${BUILD_USAGE}`);
   return typeof res.status === "number" ? res.status : 3;
 }
 
+// sdk/cli/commands/dashboard.ts
+var import_node_child_process2 = require("node:child_process");
+var import_node_module4 = require("node:module");
+var import_node_http = require("node:http");
+var import_node_fs23 = require("node:fs");
+var import_node_path21 = require("node:path");
+var DASHBOARD_FLAGS = [
+  ...COMMON_FLAGS,
+  { name: "web", type: "boolean", default: false },
+  { name: "once", type: "boolean", default: false },
+  { name: "no-open", type: "boolean", default: false },
+  { name: "root", type: "string" }
+];
+var DASHBOARD_USAGE = `gdd-sdk dashboard [flags]
+
+Open the GDD dashboard. Read-only. Dep-free (Node builtins only).
+
+Default (no --web) launches the terminal UI (bin/gdd-dashboard). With --web it
+emits a self-contained HTML graph of the design-context, serves it on an ephemeral
+local port, and opens your browser.
+
+Flags:
+  --web            Web mode: build + serve the design-context graph as HTML.
+  --once           Write the HTML to .design/dashboard.html and exit (no server). Implies --web.
+  --no-open        Web mode: serve + print the URL but do NOT open a browser (headless/CI).
+  --root <dir>     Project root to read .design/ from (default: GDD_PROJECT_ROOT or walk-up).
+  -h, --help       Show this help.
+
+Exit codes: 0 ok \xB7 3 arg error / TUI not found \xB7 (TUI exit code forwarded otherwise)
+`;
+function anchorDirs() {
+  const out = [];
+  const entry = process.argv[1];
+  if (typeof entry === "string" && entry.length > 0) out.push((0, import_node_path21.dirname)(entry));
+  out.push(process.cwd());
+  return out;
+}
+function climbToMarker(startDir) {
+  const req = (0, import_node_module4.createRequire)((0, import_node_path21.join)(startDir, "noop.js"));
+  let dir = startDir;
+  let firstWithPkg = null;
+  for (let i = 0; i < 12; i++) {
+    const pkgPath = (0, import_node_path21.join)(dir, "package.json");
+    if ((0, import_node_fs23.existsSync)(pkgPath)) {
+      if (firstWithPkg === null) firstWithPkg = dir;
+      try {
+        const pkg = req(pkgPath);
+        if (pkg && pkg.name === "get-design-done") return { root: dir, firstWithPkg };
+      } catch {
+      }
+    }
+    const parent = (0, import_node_path21.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { root: null, firstWithPkg };
+}
+var _cachedPkgRoot = null;
+function findPackageRoot() {
+  if (_cachedPkgRoot !== null) return _cachedPkgRoot;
+  let fallback = null;
+  for (const anchor of anchorDirs()) {
+    const { root, firstWithPkg } = climbToMarker(anchor);
+    if (root) {
+      _cachedPkgRoot = root;
+      return root;
+    }
+    if (fallback === null && firstWithPkg !== null) fallback = firstWithPkg;
+  }
+  _cachedPkgRoot = fallback ?? process.cwd();
+  return _cachedPkgRoot;
+}
+function requireFromRoot(relPath) {
+  const root = findPackageRoot();
+  const req = (0, import_node_module4.createRequire)((0, import_node_path21.join)(root, "noop.js"));
+  return req((0, import_node_path21.join)(root, relPath));
+}
+function resolveRoot(deps, flags) {
+  if (typeof deps.root === "string" && deps.root.length > 0) return deps.root;
+  const flagRoot = flags["root"];
+  if (typeof flagRoot === "string" && flagRoot.length > 0) return flagRoot;
+  if (process.env["GDD_PROJECT_ROOT"]) return process.env["GDD_PROJECT_ROOT"];
+  return findPackageRoot();
+}
+function loadGraphGraceful(root, stderr) {
+  const graphPath = (0, import_node_path21.join)(root, ".design", "context-graph.json");
+  try {
+    const query = requireFromRoot("scripts/lib/design-context-query.cjs");
+    if (typeof query.load === "function") return query.load(graphPath);
+  } catch (err) {
+    stderr.write(
+      `gdd-sdk dashboard: no design-context graph at ${graphPath} (${errMsg(err)}); rendering an empty graph.
+`
+    );
+  }
+  return { nodes: [], edges: [] };
+}
+function buildDashboardHtml(root, stderr) {
+  const graph = loadGraphGraceful(root, stderr);
+  const htmlLib = requireFromRoot("scripts/lib/dashboard/graph-html.cjs");
+  return htmlLib.buildGraphHtml(graph, { title: "GDD Design Context Graph" });
+}
+function isHeadless(deps, flags) {
+  if (typeof deps.headless === "boolean") return deps.headless;
+  if (flags["no-open"] === true) return true;
+  if (process.env["CI"]) return true;
+  if (process.platform === "linux") {
+    return !process.env["DISPLAY"] && !process.env["WAYLAND_DISPLAY"];
+  }
+  return false;
+}
+function defaultOpenBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      (0, import_node_child_process2.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
+    } else if (process.platform === "win32") {
+      (0, import_node_child_process2.spawn)("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+    } else {
+      (0, import_node_child_process2.spawn)("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function serveHtml(html) {
+  return new Promise((resolve11, reject) => {
+    const server = (0, import_node_http.createServer)((_req, res) => {
+      res.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store"
+      });
+      res.end(html);
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr === null || typeof addr === "string") {
+        server.close();
+        reject(new Error("could not determine the ephemeral server port"));
+        return;
+      }
+      const port = addr.port;
+      resolve11({ server, port, url: `http://127.0.0.1:${port}/` });
+    });
+  });
+}
+function errMsg(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+async function dashboardCommand(parsed, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  if (parsed.flags["help"] === true || parsed.flags["h"] === true) {
+    stdout.write(DASHBOARD_USAGE);
+    return 0;
+  }
+  let flags;
+  try {
+    flags = coerceFlags(parsed, DASHBOARD_FLAGS);
+  } catch {
+    stderr.write(`gdd-sdk dashboard: invalid flags
+${DASHBOARD_USAGE}`);
+    return 3;
+  }
+  const once = flags["once"] === true;
+  const web = flags["web"] === true || once;
+  if (!web) {
+    return runTui(deps, stdout, stderr);
+  }
+  const root = resolveRoot(deps, flags);
+  const html = buildDashboardHtml(root, stderr);
+  if (once) {
+    const designDir = (0, import_node_path21.join)(root, ".design");
+    try {
+      (0, import_node_fs23.mkdirSync)(designDir, { recursive: true });
+    } catch {
+    }
+    const outFile = (0, import_node_path21.join)(designDir, "dashboard.html");
+    try {
+      (0, import_node_fs23.writeFileSync)(outFile, html, "utf8");
+    } catch (err) {
+      stderr.write(`gdd-sdk dashboard: could not write ${outFile}: ${errMsg(err)}
+`);
+      return 3;
+    }
+    stdout.write(`Wrote dashboard HTML to ${outFile}
+`);
+    return 0;
+  }
+  let served;
+  try {
+    served = await serveHtml(html);
+  } catch (err) {
+    stderr.write(`gdd-sdk dashboard: could not start the web server: ${errMsg(err)}
+`);
+    return 3;
+  }
+  const headless = isHeadless(deps, flags);
+  const opener = deps.openBrowser ?? defaultOpenBrowser;
+  stdout.write(`GDD dashboard serving at ${served.url}
+`);
+  if (headless) {
+    stdout.write("Headless environment detected \u2014 open the URL above in a browser.\n");
+    stdout.write("Press Ctrl+C to stop the server.\n");
+  } else {
+    const launched = opener(served.url);
+    if (!launched) {
+      stdout.write("Could not auto-open a browser \u2014 open the URL above manually.\n");
+    }
+    stdout.write("Press Ctrl+C to stop the server.\n");
+  }
+  await new Promise((resolve11) => {
+    const shutdown = () => {
+      served.server.close(() => resolve11());
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    served.server.on("close", () => resolve11());
+  });
+  return 0;
+}
+function runTui(deps, _stdout, stderr) {
+  let bin = deps.tuiBin;
+  if (!bin) {
+    const root = findPackageRoot();
+    const candidate = (0, import_node_path21.join)(root, "bin", "gdd-dashboard");
+    bin = (0, import_node_fs23.existsSync)(candidate) ? candidate : void 0;
+  }
+  if (!bin || !(0, import_node_fs23.existsSync)(bin)) {
+    stderr.write(
+      "gdd-sdk dashboard: could not locate bin/gdd-dashboard (the terminal UI).\nTry `gdd dashboard --web` for the browser graph instead.\n"
+    );
+    return 3;
+  }
+  const stdio = deps.tuiStdio ?? "inherit";
+  const res = (0, import_node_child_process2.spawnSync)(process.execPath, [bin], { stdio });
+  if (res.error) {
+    stderr.write(`gdd-sdk dashboard: failed to launch the TUI: ${res.error.message}
+`);
+    return 3;
+  }
+  return typeof res.status === "number" ? res.status : 0;
+}
+
 // sdk/cli/index.ts
 var USAGE6 = `gdd-sdk <command> [flags]
 
@@ -8458,6 +9838,7 @@ Commands:
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
   build skills     Compile per-harness skill bundles from source/skills/.
+  dashboard        Open the GDD dashboard (TUI; --web for the browser graph).
 
 Use 'gdd-sdk <command> -h' for command-specific flags.
 
@@ -8476,7 +9857,8 @@ async function dispatch(parsed, deps = {}) {
     query: deps.commands?.query ?? queryCommand,
     audit: deps.commands?.audit ?? auditCommand,
     init: deps.commands?.init ?? initCommand,
-    build: deps.commands?.build ?? buildCommand
+    build: deps.commands?.build ?? buildCommand,
+    dashboard: deps.commands?.dashboard ?? dashboardCommand
   };
   if (parsed.subcommand === null) {
     stdout.write(USAGE6);
@@ -8502,6 +9884,8 @@ async function dispatch(parsed, deps = {}) {
       return await commands.init(parsed, { stdout, stderr });
     case "build":
       return await commands.build(parsed, { stdout, stderr });
+    case "dashboard":
+      return await commands.dashboard(parsed, { stdout, stderr });
     default:
       stderr.write(
         `gdd-sdk: unknown subcommand "${parsed.subcommand}"
@@ -8516,7 +9900,8 @@ var KNOWN_SUBCOMMANDS = /* @__PURE__ */ new Set([
   "query",
   "audit",
   "init",
-  "build"
+  "build",
+  "dashboard"
 ]);
 async function main(argv = process.argv.slice(2), deps = {}) {
   const parsed = parseArgs(argv);