@tendrilapp/cli 0.1.17 → 0.1.18

package/dist/tendril.js

@@ -1214,8 +1214,8 @@ var init_src = __esm({
 function variableNameToPath(name) {
   return name.split("/").map(canonicalCssIdentPart).filter((part) => part.length > 0);
 }
-function tokenPathToCssVar(path35) {
-  return `--${path35.join("-")}`;
+function tokenPathToCssVar(path36) {
+  return `--${path36.join("-")}`;
 }
 function toDtcgToken(variable, defaultMode) {
   const modes = Object.keys(variable.valuesByMode);
@@ -1259,11 +1259,11 @@ function toDtcgToken(variable, defaultMode) {
 }
 function mapVariablesToDtcg(variables, defaultMode = "light") {
   const entries = variables.map((variable) => {
-    const path35 = variableNameToPath(variable.name);
-    if (path35.length === 0) {
+    const path36 = variableNameToPath(variable.name);
+    if (path36.length === 0) {
       throw new DtcgMappingError("empty-name", `Figma variable ${variable.id} has an empty name`);
     }
-    return { variable, path: path35 };
+    return { variable, path: path36 };
   });
   const groupPrefixes = /* @__PURE__ */ new Set();
   for (const e of entries) {
@@ -1284,21 +1284,21 @@ function mapVariablesToDtcg(variables, defaultMode = "light") {
   }
   const tokens = {};
   const flat = [];
-  for (const { variable, path: path35 } of entries) {
+  for (const { variable, path: path36 } of entries) {
     const token = toDtcgToken(variable, defaultMode);
     let group = tokens;
-    for (const segment of path35.slice(0, -1)) {
+    for (const segment of path36.slice(0, -1)) {
       const existing = group[segment];
       group = existing ?? (group[segment] = {});
     }
-    const leaf = path35[path35.length - 1];
+    const leaf = path36[path36.length - 1];
     if (group[leaf] !== void 0) {
-      throw new DtcgMappingError("duplicate-path", `Duplicate token path "${path35.join(".")}" (variable ${variable.id})`);
+      throw new DtcgMappingError("duplicate-path", `Duplicate token path "${path36.join(".")}" (variable ${variable.id})`);
     }
     group[leaf] = token;
     flat.push({
-      path: path35.join("."),
-      cssVar: tokenPathToCssVar(path35),
+      path: path36.join("."),
+      cssVar: tokenPathToCssVar(path36),
       type: token.$type,
       value: token.$value
     });
@@ -1487,9 +1487,9 @@ function boundId(value) {
   return isObject(value) && typeof value["boundVariableId"] === "string" ? value["boundVariableId"] : void 0;
 }
 function resolveBinding(ctx, id) {
-  const path35 = ctx.pathById.get(id);
-  if (path35 === void 0) ctx.unresolved.add(id);
-  return path35;
+  const path36 = ctx.pathById.get(id);
+  if (path36 === void 0) ctx.unresolved.add(id);
+  return path36;
 }
 function parseVariantProps(name) {
   if (!name.includes("=")) return void 0;
@@ -1524,8 +1524,8 @@ function walk(ctx, raw) {
       if (!isObject(paint) || paint["visible"] === false) continue;
       const id = boundId(paint);
       if (id !== void 0) {
-        const path35 = resolveBinding(ctx, id);
-        if (path35 !== void 0) tokens.add(path35);
+        const path36 = resolveBinding(ctx, id);
+        if (path36 !== void 0) tokens.add(path36);
       } else if (typeof paint["color"] === "string") {
         ctx.hardcoded.push({ node: name, property, value: paint["color"] });
       }
@@ -1533,8 +1533,8 @@ function walk(ctx, raw) {
   }
   const radiusId = boundId(raw["cornerRadius"]);
   if (radiusId !== void 0) {
-    const path35 = resolveBinding(ctx, radiusId);
-    if (path35 !== void 0) tokens.add(path35);
+    const path36 = resolveBinding(ctx, radiusId);
+    if (path36 !== void 0) tokens.add(path36);
   } else if (typeof raw["cornerRadius"] === "number" && raw["cornerRadius"] !== 0) {
     ctx.hardcoded.push({ node: name, property: "border-radius", value: `${raw["cornerRadius"]}px` });
   }
@@ -1544,10 +1544,10 @@ function walk(ctx, raw) {
     layout = { mode: layoutMode === "HORIZONTAL" ? "flex-row" : "flex-column" };
     const gapId = boundId(raw["itemSpacing"]);
     if (gapId !== void 0) {
-      const path35 = resolveBinding(ctx, gapId);
-      if (path35 !== void 0) {
-        layout.gap = path35;
-        tokens.add(path35);
+      const path36 = resolveBinding(ctx, gapId);
+      if (path36 !== void 0) {
+        layout.gap = path36;
+        tokens.add(path36);
       }
     } else if (typeof raw["itemSpacing"] === "number" && raw["itemSpacing"] !== 0) {
       ctx.hardcoded.push({ node: name, property: "gap", value: `${raw["itemSpacing"]}px` });
@@ -1556,10 +1556,10 @@ function walk(ctx, raw) {
     for (const field of PADDING_FIELDS) {
       const id = boundId(raw[field]);
       if (id !== void 0) {
-        const path35 = resolveBinding(ctx, id);
-        if (path35 !== void 0) {
-          paddingPaths.push(path35);
-          tokens.add(path35);
+        const path36 = resolveBinding(ctx, id);
+        if (path36 !== void 0) {
+          paddingPaths.push(path36);
+          tokens.add(path36);
         }
       } else if (typeof raw[field] === "number" && raw[field] !== 0) {
         ctx.hardcoded.push({ node: name, property: field, value: `${raw[field]}px` });
@@ -1968,13 +1968,13 @@ var init_tsc_check = __esm({
 // packages/verify/src/token-lint.ts
 import strictValue from "stylelint-declaration-strict-value";
 import stylelint from "stylelint";
-async function runTokenLint(css, fileLabel = "generated.css", definedVars2) {
+async function runTokenLint(css, fileLabel = "generated.css", definedVars2, recordedMapEmpty = false) {
   const result = await stylelint.lint({
     code: css,
     codeFilename: fileLabel,
     config: STYLELINT_CONFIG
   });
-  const mapKnownEmpty = definedVars2 !== void 0 && definedVars2.size === 0;
+  const mapKnownEmpty = recordedMapEmpty || definedVars2 !== void 0 && definedVars2.size === 0;
   const violations = result.results.flatMap(
     (r) => r.warnings.filter((w) => !(mapKnownEmpty && w.rule === "scale-unlimited/declaration-strict-value")).map((w) => ({
       file: fileLabel,
@@ -3409,7 +3409,29 @@ function resolvedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
 function requiredFontsManifest(families, cacheDir = DEFAULT_FONT_CACHE) {
   const mPath = path9.join(cacheDir, "manifest.json");
   const manifest = existsSync5(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
-  return manifest.filter((f) => families.includes(f.family));
+  const wanted = new Set(families.map((f) => f.toLowerCase()));
+  return manifest.filter((f) => wanted.has(f.family.toLowerCase()));
+}
+function verifiedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
+  const mPath = path9.join(cacheDir, "manifest.json");
+  if (!existsSync5(mPath)) return [];
+  let entries;
+  try {
+    entries = JSON.parse(readFileSync3(mPath, "utf8"));
+  } catch {
+    return [];
+  }
+  const byFamily = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    if (typeof e.family !== "string" || typeof e.weight !== "number" || typeof e.file !== "string") continue;
+    const file = path9.isAbsolute(e.file) && existsSync5(e.file) ? e.file : path9.resolve(cacheDir, path9.basename(e.file));
+    if (!existsSync5(file)) continue;
+    if (createHash("sha256").update(readFileSync3(file)).digest("hex") !== e.sha256) continue;
+    const set = byFamily.get(e.family) ?? /* @__PURE__ */ new Set();
+    set.add(e.weight);
+    byFamily.set(e.family, set);
+  }
+  return [...byFamily.entries()].map(([family, w]) => ({ family, weights: [...w].sort((a, b) => a - b) }));
 }
 var DEFAULT_FONT_CACHE, UA;
 var init_font_resolve = __esm({
@@ -3421,11 +3443,21 @@ var init_font_resolve = __esm({
 });
 
 // packages/verify/src/font-faces.ts
+import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
 import path10 from "node:path";
 function fontFaceCss(manifestPath2 = path10.join(fontCacheDir(), "manifest.json")) {
   if (!existsSync6(manifestPath2)) return "";
-  const manifest = JSON.parse(readFileSync4(manifestPath2, "utf8"));
+  const claimed = JSON.parse(readFileSync4(manifestPath2, "utf8"));
+  const resolveEntry = (f) => {
+    if (path10.isAbsolute(f) && existsSync6(f)) return f;
+    return path10.resolve(path10.dirname(manifestPath2), path10.basename(f));
+  };
+  const manifest = claimed.filter((f) => {
+    const file = resolveEntry(f.file);
+    if (!existsSync6(file)) return false;
+    return createHash2("sha256").update(readFileSync4(file)).digest("hex") === f.sha256;
+  });
   const resolveFile = (f) => {
     if (path10.isAbsolute(f) && existsSync6(f)) return f;
     return path10.resolve(path10.dirname(manifestPath2), path10.basename(f));
@@ -4196,7 +4228,28 @@ function definedVars(tokensCss) {
   for (const m of tokensCss.matchAll(/(--[\w-]+)\s*:/g)) names.add(m[1]);
   return names;
 }
-async function checkBundleQuality(bundleDir, entry) {
+function recordedTokenMapEmpty(setDir, reps) {
+  const readMap = (file) => {
+    if (!existsSync9(file)) return void 0;
+    try {
+      const parsed = JSON.parse(envelopeFirstTextPart(JSON.parse(readFileSync7(file, "utf8"))) || "{}");
+      return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  };
+  const setLevel = readMap(path14.join(setDir, "get_variable_defs.json"));
+  if (setLevel !== void 0) return Object.keys(setLevel).length === 0;
+  let recorded = false;
+  for (const rep of reps) {
+    const m = readMap(path14.join(setDir, rep, "get_variable_defs.json"));
+    if (m === void 0) continue;
+    recorded = true;
+    if (Object.keys(m).length > 0) return false;
+  }
+  return recorded;
+}
+async function checkBundleQuality(bundleDir, entry, set) {
   const findings = [];
   const entryPath = path14.join(bundleDir, entry);
   const cssPath = path14.join(bundleDir, "styles.css");
@@ -4216,7 +4269,8 @@ async function checkBundleQuality(bundleDir, entry) {
     }
   }
   if (css !== "") {
-    for (const v of (await runTokenLint(css, "styles.css", definedVars(tokensCss))).violations) {
+    const recordedEmpty = set !== void 0 && recordedTokenMapEmpty(set.dir, set.reps);
+    for (const v of (await runTokenLint(css, "styles.css", definedVars(tokensCss), recordedEmpty)).violations) {
       findings.push({ kind: "token-lint", file: "styles.css", line: v.line, message: v.message });
     }
   }
@@ -4225,6 +4279,7 @@ async function checkBundleQuality(bundleDir, entry) {
 var init_bundle_quality = __esm({
   "packages/verify/src/bundle-quality.ts"() {
     "use strict";
+    init_src();
     init_runtime();
     init_tsc_check();
     init_token_lint();
@@ -5174,7 +5229,7 @@ var init_src4 = __esm({
 // packages/cli/src/environment.ts
 import { existsSync as existsSync14, readFileSync as readFileSync11 } from "node:fs";
 import path19 from "node:path";
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function cliVersion() {
   try {
@@ -5191,7 +5246,7 @@ function environmentStamp(taskFamilies) {
       const entries = JSON.parse(readFileSync11(manifestPath2, "utf8"));
       const scoped = taskFamilies === void 0 || taskFamilies === null ? entries : entries.filter((f) => taskFamilies.some((fam) => fam.toLowerCase() === f.family.toLowerCase()));
       const faces = scoped.map((f) => `${f.family}:${f.weight}:${f.sha256}`).sort();
-      fontsHash = faces.length === 0 ? null : createHash2("sha256").update(faces.join("\n")).digest("hex").slice(0, 16);
+      fontsHash = faces.length === 0 ? null : createHash3("sha256").update(faces.join("\n")).digest("hex").slice(0, 16);
     } catch {
       fontsHash = null;
     }
@@ -5210,6 +5265,25 @@ var init_environment = __esm({
   }
 });
 
+// packages/cli/src/describe.ts
+function printDescription(description) {
+  process.stdout.write(`${JSON.stringify(description, null, 2)}
+`);
+}
+var COMMON_EXIT_CODES;
+var init_describe = __esm({
+  "packages/cli/src/describe.ts"() {
+    "use strict";
+    COMMON_EXIT_CODES = {
+      0: "success",
+      1: "general error",
+      2: "authentication error",
+      3: "input validation error",
+      4: "confirmation required (re-run with --yes or answer the prompt)"
+    };
+  }
+});
+
 // packages/cli/src/env.ts
 import { existsSync as existsSync15, readFileSync as readFileSync12 } from "node:fs";
 import path20 from "node:path";
@@ -5386,6 +5460,211 @@ var init_entitlement = __esm({
   }
 });
 
+// packages/cli/src/commands/doctor.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync17, readFileSync as readFileSync14, readdirSync as readdirSync3 } from "node:fs";
+import os4 from "node:os";
+import path22 from "node:path";
+async function runDoctorChecks(options) {
+  const checks = [];
+  const mcpUrl = options.mcpUrl ?? DEFAULT_MCP_URL;
+  const client = new McpHttpClient({
+    url: mcpUrl,
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  });
+  try {
+    const info = await client.initialize();
+    const tools = await client.listTools();
+    checks.push({
+      name: "figma-desktop-mcp",
+      ok: true,
+      detail: `${info.name} ${info.version} (protocol ${info.protocolVersion}), ${tools.length} tools: ${tools.map((t) => t.name).join(", ")}`
+    });
+  } catch (err) {
+    checks.push({
+      name: "figma-desktop-mcp",
+      ok: false,
+      detail: err instanceof Error ? err.message : String(err),
+      remediation: err instanceof McpUnavailableError ? "Open the Figma desktop app, sign in, then Figma menu \u2192 Preferences \u2192 Enable local MCP server (Dev or Full seat on a paid plan)." : "The server answered but the exchange failed \u2014 check the signed-in account's seat, then retry."
+    });
+  }
+  const openrouterKey = resolveCredential("OPENROUTER_API_KEY");
+  checks.push(
+    openrouterKey ? { name: "openrouter-key", ok: true, detail: "OPENROUTER_API_KEY configured" } : {
+      name: "openrouter-key",
+      ok: false,
+      detail: "OPENROUTER_API_KEY not set \u2014 optional; only the curated API-model engine needs it",
+      remediation: "Run `tendril init` to store your OpenRouter key (BYOK) if you plan to use the curated engine."
+    }
+  );
+  try {
+    const chrome = resolveChrome();
+    checks.push({ name: "browser", ok: true, detail: `${chromeVersion() ?? "version unknown"} at ${chrome}` });
+  } catch (err) {
+    checks.push({
+      name: "browser",
+      ok: false,
+      detail: err instanceof Error ? err.message : String(err),
+      remediation: "Install Google Chrome (or Chromium), or set CHROME_PATH to a Chromium-family browser binary."
+    });
+  }
+  const fontManifest = path22.join(fontCacheDir(), "manifest.json");
+  checks.push(
+    existsSync17(fontManifest) ? { name: "font-cache", ok: true, detail: `resolved font cache at ${fontCacheDir()} (${JSON.parse(readFileSync14(fontManifest, "utf8")).length} faces)` } : {
+      name: "font-cache",
+      ok: true,
+      detail: `font cache empty at ${fontCacheDir()} \u2014 normal on a fresh machine; faces resolve per design system at first use`,
+      remediation: "Nothing to do now: `tendril fonts resolve --set <recording-dir>` fetches exactly what a recording declares, and generate/verify name that command when they need it."
+    }
+  );
+  const pluginRoot = path22.join(os4.homedir(), ".claude", "plugins", "cache", "tendrilapp", "tendril");
+  if (existsSync17(pluginRoot)) {
+    try {
+      const versions = readdirSync3(pluginRoot).filter((v) => /^\d+\.\d+\.\d+$/.test(v));
+      const newest = versions.sort((a, b) => versionIsNewer(a, b) ? 1 : -1)[0];
+      if (newest !== void 0) {
+        const skewed = versionIsNewer(newest, cliVersion());
+        checks.push(
+          skewed ? {
+            name: "plugin-skew",
+            ok: false,
+            detail: `Claude Code plugin cache holds v${newest} while this CLI is ${cliVersion()} \u2014 the plugin's skill/agents are STALE and will silently shadow current doctrine`,
+            remediation: "Update the plugin \u2014 REFRESH THE MARKETPLACE FIRST (its local clone goes stale and a reinstall faithfully reinstalls the old version): terminal Claude Code \u2014 `claude plugin marketplace update tendrilapp` then `claude plugin update tendril`; VS Code extension \u2014 /plugins panel \u2192 Marketplaces tab \u2192 refresh tendrilapp, THEN Plugins tab \u2192 uninstall + reinstall tendril, reopen the chat panel. If the refresh doesn't take, remove the tendrilapp marketplace entirely and re-add TendrilApp/claude-plugin (a fresh clone cannot be stale)."
+          } : { name: "plugin-skew", ok: true, detail: `Claude Code plugin v${newest} matches this CLI` }
+        );
+      }
+    } catch {
+    }
+  }
+  const pathBinary = cliVersion() === "0.0.0" ? null : findPathTendril(process.env["PATH"] ?? "", process.platform);
+  if (pathBinary !== null) {
+    const reported = probeVersion(pathBinary);
+    if (reported !== null) {
+      checks.push(
+        reported === cliVersion() ? { name: "path-skew", ok: true, detail: `tendril on PATH (${pathBinary}) is this CLI (${reported})` } : {
+          name: "path-skew",
+          ok: false,
+          detail: `tendril on PATH (${pathBinary}) reports ${reported} while this CLI is ${cliVersion()} \u2014 a stale global install silently shadows the current release in terminals`,
+          remediation: "npm rm -g tendrilapp (or npm install -g @tendrilapp/cli@latest) so the PATH binary matches; plugin/npx sessions already run the current release."
+        }
+      );
+    }
+  }
+  const ent = checkEntitlement();
+  checks.push(
+    ent.ok ? ent.mode === "pre-launch" ? { name: "entitlement", ok: true, detail: "pre-launch build \u2014 entitlement gates present but unarmed (no public key shipped); record/generate run freely" } : { name: "entitlement", ok: true, detail: `active plan "${ent.claims.plan}" until ${new Date(ent.claims.exp).toISOString().slice(0, 10)}${ent.stale ? " (stale \u2014 renews at next opportunity)" : ""}` } : { name: "entitlement", ok: false, detail: ent.error, remediation: ent.remediation }
+  );
+  const figmaToken = resolveCredential("FIGMA_TOKEN");
+  checks.push({
+    name: "figma-pat",
+    ok: true,
+    detail: figmaToken ? "FIGMA_TOKEN configured (REST fallback available)" : "FIGMA_TOKEN not set \u2014 optional; only needed for the REST fallback transport"
+  });
+  return { ok: checks.filter((c) => c.name !== "figma-pat" && c.name !== "openrouter-key" && c.name !== "path-skew").every((c) => c.ok), checks };
+}
+function findPathTendril(pathEnv, platform) {
+  const dirs = pathEnv.split(path22.delimiter).filter((d) => d !== "" && !/node_modules[\\/]\.bin/.test(d) && !/[\\/]_npx[\\/]/.test(d));
+  const names = platform === "win32" ? ["tendril.cmd", "tendril.bat"] : ["tendril"];
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = path22.join(dir, name);
+      if (existsSync17(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+function probeVersion(binary) {
+  const windowsShim = /\.(cmd|bat)$/i.test(binary);
+  const res = windowsShim ? spawnSync(`"${binary}" --version`, { shell: true, timeout: 5e3, encoding: "utf8" }) : spawnSync(binary, ["--version"], { timeout: 5e3, encoding: "utf8" });
+  if (res.error !== void 0 || res.status !== 0) return null;
+  const m = /^(\d+\.\d+\.\d+)\s*$/m.exec(res.stdout ?? "");
+  return m === null ? null : m[1];
+}
+function versionIsNewer(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pb[i] ?? 0) > (pa[i] ?? 0)) return true;
+    if ((pb[i] ?? 0) < (pa[i] ?? 0)) return false;
+  }
+  return false;
+}
+async function latestVersionInfo() {
+  try {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), 2500);
+    const res = await fetch("https://registry.npmjs.org/@tendrilapp%2fcli", { signal: ctl.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const doc = await res.json();
+    const latest = doc["dist-tags"]?.latest;
+    if (latest === void 0) return null;
+    const stamp = doc.time?.[latest];
+    return { latest, ...stamp !== void 0 ? { publishedAt: stamp.slice(0, 10) } : {} };
+  } catch {
+    return null;
+  }
+}
+async function runDoctor(flags) {
+  if (flags.describe) {
+    printDescription(DOCTOR_DESCRIPTION);
+    return;
+  }
+  const [report, latest] = await Promise.all([runDoctorChecks({ ...flags.mcpUrl ? { mcpUrl: flags.mcpUrl } : {} }), latestVersionInfo()]);
+  emitData(flags, { version: cliVersion(), ...latest !== null ? { latest: latest.latest, latestPublishedAt: latest.publishedAt ?? null, updateAvailable: versionIsNewer(cliVersion(), latest.latest) } : {}, ...report }, () => {
+    const version = cliVersion();
+    if (latest === null) {
+      process.stdout.write(`tendril ${version} (latest: unreachable)
+`);
+    } else if (!versionIsNewer(version, latest.latest)) {
+      process.stdout.write(`tendril ${version} (${latest.latest === version ? "latest" : `ahead of registry ${latest.latest}`}${latest.publishedAt !== void 0 ? `, published ${latest.publishedAt}` : ""})
+`);
+    } else {
+      process.stdout.write(`tendril ${version} \u2014 UPDATE AVAILABLE: ${latest.latest}${latest.publishedAt !== void 0 ? ` (published ${latest.publishedAt})` : ""}
+`);
+      process.stdout.write(`    \u2192 npm install -g @tendrilapp/cli@latest (plugin MCP users update automatically at next session; a stale npx cache clears with npm cache clean --force)
+`);
+    }
+    for (const check of report.checks) {
+      process.stdout.write(`${check.ok ? "\u2713" : "\u2717"} ${check.name}: ${check.detail}
+`);
+      if (check.remediation) process.stdout.write(`    \u2192 ${check.remediation}
+`);
+    }
+    process.stdout.write(report.ok ? "\nready to generate\n" : "\nnot ready \u2014 fix the items above\n");
+  });
+  if (!report.ok) process.exit(1);
+}
+var DEFAULT_MCP_URL, DOCTOR_DESCRIPTION;
+var init_doctor = __esm({
+  "packages/cli/src/commands/doctor.ts"() {
+    "use strict";
+    init_src4();
+    init_src();
+    init_describe();
+    init_env();
+    init_environment();
+    init_output();
+    init_entitlement();
+    DEFAULT_MCP_URL = "http://127.0.0.1:3845/mcp";
+    DOCTOR_DESCRIPTION = {
+      name: "doctor",
+      summary: "Check whether this machine can run tendril generate end to end.",
+      args: [],
+      flags: [
+        { flag: "--mcp-url <url>", description: "Figma MCP endpoint", default: DEFAULT_MCP_URL },
+        { flag: "--json", description: "Machine-readable output" }
+      ],
+      output: {
+        ok: "boolean \u2014 Figma desktop MCP reachable AND a scoring browser found (fonts resolve lazily per design system; keys are informational)",
+        checks: "[{ name, ok, detail, remediation? }]"
+      },
+      exitCodes: { 0: "healthy", 1: "one or more required checks failed" },
+      examples: ["tendril doctor", "tendril doctor --json"]
+    };
+  }
+});
+
 // packages/llm/src/model-config.ts
 import { z as z6 } from "zod";
 function resolveModel(config, requestedId) {
@@ -6687,7 +6966,8 @@ __export(record_exports, {
   runRecordPlan: () => runRecordPlan,
   runRecordStatus: () => runRecordStatus
 });
-import { existsSync as existsSync19, readFileSync as readFileSync16, readdirSync as readdirSync5 } from "node:fs";
+import { existsSync as existsSync19, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readdirSync as readdirSync5 } from "node:fs";
+import os5 from "node:os";
 import path25 from "node:path";
 import { writeFileSync as writeFileSync9 } from "node:fs";
 function symbolsFromMetadataEnvelope(file, sourceFrame) {
@@ -6734,10 +7014,42 @@ function runRecordPlan(opts) {
     }
     defaults[spec.slice(0, eq)] = spec.slice(eq + 1);
   }
+  if (opts.metadataRawFile !== void 0 && opts.metadataRawPartsFile !== void 0) {
+    fail(opts, ExitCode.InputValidation, {
+      error: "pass at most one of --metadata-raw-file and --metadata-raw-parts-file",
+      code: "bad-envelope",
+      remediation: "One get_metadata response: single block \u2192 --metadata-raw-file; multi-block \u2192 --metadata-raw-parts-file (a JSON array of the blocks)."
+    });
+  }
+  const metadataEntries = (opts.metadataFiles ?? []).map((spec) => {
+    const [file, frame] = spec.split("@");
+    return frame === void 0 ? { file } : { file, frame };
+  });
+  const rawFile = opts.metadataRawPartsFile ?? opts.metadataRawFile;
+  if (rawFile !== void 0) {
+    try {
+      const envelope = rawEnvelopeFromFile(rawFile, opts.metadataRawPartsFile !== void 0);
+      const tmp = path25.join(mkdtempSync2(path25.join(os5.tmpdir(), "tendril-plan-meta-")), "get_metadata.json");
+      writeFileSync9(tmp, JSON.stringify(envelope));
+      metadataEntries.push({ file: tmp });
+    } catch (err) {
+      fail(opts, ExitCode.InputValidation, {
+        error: `could not read raw metadata ${rawFile}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+        code: "bad-envelope",
+        remediation: "The raw file holds the get_metadata response text exactly as received (or, for --metadata-raw-parts-file, a JSON array of its blocks)."
+      });
+    }
+  }
+  if (metadataEntries.length === 0) {
+    fail(opts, ExitCode.InputValidation, {
+      error: "no metadata provided",
+      code: "bad-envelope",
+      remediation: "Pass --metadata <envelope.json> (repeatable), or the response text via --metadata-raw-file / --metadata-raw-parts-file."
+    });
+  }
   let symbols = [];
   let metadataTruncated = false;
-  for (const spec of opts.metadataFiles) {
-    const [file, frame] = spec.split("@");
+  for (const { file, frame } of metadataEntries) {
     try {
       const parsed = symbolsFromMetadataEnvelope(path25.resolve(file), frame);
       symbols.push(...parsed.symbols);
@@ -6770,8 +7082,7 @@ function runRecordPlan(opts) {
     });
   }
   if (symbols.length === 0) {
-    const leads = opts.metadataFiles.flatMap((spec) => {
-      const [file] = spec.split("@");
+    const leads = metadataEntries.flatMap(({ file }) => {
       try {
         const env = JSON.parse(readFileSync16(path25.resolve(file), "utf8"));
         return instanceLeads(env.content.map((c) => c.text ?? "").join("\n"));
@@ -8464,8 +8775,8 @@ var init_adapter = __esm({
 });
 
 // packages/generate/src/bundle-emit.ts
-import { createHash as createHash3 } from "node:crypto";
-import { existsSync as existsSync23, readFileSync as readFileSync20, readdirSync as readdirSync7, writeFileSync as writeFileSync11 } from "node:fs";
+import { createHash as createHash4 } from "node:crypto";
+import { copyFileSync, existsSync as existsSync23, mkdirSync as mkdirSync7, readFileSync as readFileSync20, readdirSync as readdirSync7, rmSync as rmSync3, writeFileSync as writeFileSync11 } from "node:fs";
 import path29 from "node:path";
 function pinFromConfigs(configs) {
   const domains = /* @__PURE__ */ new Map();
@@ -8514,6 +8825,37 @@ function cssFontFamilies(css) {
   }
   return [...out];
 }
+function fontsCssFor(faces, bundleDir, cacheDir = DEFAULT_FONT_CACHE) {
+  const header = [
+    "/* tendril fonts.css \u2014 the exact faces this bundle was scored with (sha-pinned in",
+    "   component.json requiredFonts). Load it alongside styles.css so the component",
+    "   renders in the recorded typeface \u2014 without it the browser substitutes, which is",
+    "   exactly the drift verification exists to rule out. Not read by scoring. */"
+  ];
+  const lines = [];
+  for (const face of faces) {
+    const src = path29.join(cacheDir, path29.basename(face.file));
+    const target = `./fonts/${path29.basename(face.file)}`;
+    const format = FONT_FORMATS[path29.extname(face.file).toLowerCase()] ?? "truetype";
+    const family = face.family.replace(/['\\]/g, "").replace(/\*\//g, "");
+    const decl = `@font-face { font-family: '${family}'; font-weight: ${face.weight}; font-style: normal; src: url(${target}) format('${format}'); }`;
+    if (face.source.startsWith("local:")) {
+      lines.push(
+        `/* '${family}' ${face.weight} is a user-licensed face (tendril fonts add; sha256 ${face.sha256.slice(0, 16)}\u2026).`,
+        `   Licensed bytes are never copied into bundles \u2014 place your copy at ${target} and uncomment: */`,
+        `/* ${decl} */`
+      );
+    } else if (existsSync23(src) && createHash4("sha256").update(readFileSync20(src)).digest("hex") === face.sha256) {
+      mkdirSync7(path29.join(bundleDir, "fonts"), { recursive: true });
+      copyFileSync(src, path29.join(bundleDir, "fonts", path29.basename(face.file)));
+      lines.push(decl);
+    } else {
+      lines.push(`/* '${family}' ${face.weight} (sha256 ${face.sha256.slice(0, 16)}\u2026) could not be shipped: cache bytes missing or hash mismatch \u2014 re-run \`tendril fonts resolve\` and re-emit. */`);
+    }
+  }
+  return lines.length === 0 ? null : `${[...header, ...lines].join("\n")}
+`;
+}
 function countLatticeSymbols(setDir) {
   const manifestFile = path29.join(setDir, "recording-set.json");
   if (existsSync23(manifestFile)) {
@@ -8554,7 +8896,7 @@ function recordingSetHash(setDir, configs) {
     relPaths,
     (p) => new Uint8Array(readFileSync20(path29.join(setDir, p))),
     (chunks) => {
-      const h = createHash3("sha256");
+      const h = createHash4("sha256");
       for (const c of chunks) h.update(c);
       return h.digest("hex");
     }
@@ -8564,7 +8906,11 @@ function statusOf(s) {
   return tierOf(s, BARS.cert);
 }
 function emitBundleV1(opts) {
-  const statuses = opts.scores.map((s) => ({ rep: s.rep, similarity: s.similarity, inkRecall: s.inkRecall, ...s.exact !== void 0 ? { exact: s.exact } : {}, status: statusOf(s) }));
+  const substituted = (opts.substitutedFamilies ?? []).length > 0;
+  const statuses = opts.scores.map((s) => {
+    const tier = statusOf(s);
+    return { rep: s.rep, similarity: s.similarity, inkRecall: s.inkRecall, ...s.exact !== void 0 ? { exact: s.exact } : {}, status: substituted && tier === "certified" ? "pass" : tier };
+  });
   const certified = statuses.filter((s) => s.status === "certified").length;
   const pass = statuses.filter((s) => s.status !== "fail").length;
   const lattice = countLatticeSymbols(opts.task.set);
@@ -8637,17 +8983,26 @@ function emitBundleV1(opts) {
 ${stripped}`);
     written.push(stylesPath);
   }
+  const fontsCssPath = path29.join(opts.bundleDir, "fonts.css");
+  rmSync3(path29.join(opts.bundleDir, "fonts"), { recursive: true, force: true });
+  rmSync3(fontsCssPath, { force: true });
+  const fontsCss = fontsCssFor(requiredFontsManifest(families, opts.fontCacheDir), opts.bundleDir, opts.fontCacheDir);
+  if (fontsCss !== null) {
+    writeFileSync11(fontsCssPath, fontsCss);
+    written.push(fontsCssPath);
+  }
   const unrecorded = lattice === null ? null : Math.max(0, lattice - statuses.length);
   const statusLine = `bundle: ${pass}/${statuses.length} recorded configs \u2265 pass bar (${certified} certified), ` + (interaction.length === 0 ? "interaction behaviors NONE VERIFIED" : `interaction behaviors ${interaction.filter((b) => b.pass).length}/${interaction.length}`) + (prelude.length === 0 ? "" : `, page hygiene ${prelude.filter((b) => b.pass).length}/${prelude.length}`) + (unrecorded === null ? "" : `; ${unrecorded} lattice configs UNVERIFIED`) + ` \u2014 claims in component.json, recompute with \`tendril verify\``;
   return { manifest, statusLine, written };
 }
-var BARS;
+var FONT_FORMATS, BARS;
 var init_bundle_emit = __esm({
   "packages/generate/src/bundle-emit.ts"() {
     "use strict";
     init_src6();
     init_src();
     init_src4();
+    FONT_FORMATS = { ".woff2": "woff2", ".woff": "woff", ".ttf": "truetype", ".otf": "opentype" };
     BARS = {
       pass: { sim: 0.95, ink: 0.95 },
       cert: { sim: 0.97, ink: 0.95 }
@@ -8826,6 +9181,12 @@ function taskFontFamilies(setDir) {
     return null;
   }
 }
+function unprovisionedFamilies(setDir, cacheDir) {
+  const declared = taskFontFamilies(setDir);
+  if (declared === null) return [];
+  const provided = new Set(verifiedFontFamilies(cacheDir).map((f) => f.family.toLowerCase()));
+  return declared.filter((f) => !provided.has(f.toLowerCase()));
+}
 var init_font_guidance = __esm({
   "packages/cli/src/font-guidance.ts"() {
     "use strict";
@@ -8990,6 +9351,12 @@ async function runVerify(opts) {
       remediation: fontsUnprovenRemediation(task.set)
     });
   }
+  const substitutedFamilies = unprovisionedFamilies(task.set);
+  if (substitutedFamilies.length > 0) {
+    warn(opts, `substituted fonts: cache lacks ${substitutedFamilies.map((f) => `"${f}"`).join(", ")} \u2014 scores measure a substitute face and no config can be certified under one (the stamp covers only the provisioned subset); resolve the families to certify`);
+  } else if (opts.bar === "cert" && taskFontFamilies(task.set) === null) {
+    warn(opts, "family coverage could not be established from this recording (no declared families) \u2014 the certification gate covers only cache non-emptiness here");
+  }
   const missing = task.configs.filter(
     (c) => !existsSync25(path31.join(task.set, c.rep, "get_screenshot.json")) || !existsSync25(path31.join(task.set, c.rep, "get_metadata.json"))
   );
@@ -9003,7 +9370,7 @@ async function runVerify(opts) {
   const bar = BARS2[opts.bar];
   const evidenceDir = path31.join(opts.bundleDir, "verify-evidence");
   const scores = await scoreBundleForTask(task, opts.bundleDir, bar, { evidenceDir, onProgress: emitProgress });
-  const quality = await checkBundleQuality(opts.bundleDir, task.entry);
+  const quality = await checkBundleQuality(opts.bundleDir, task.entry, { dir: task.set, reps: task.configs.map((c) => c.rep) });
   const bundleCss = ["tokens.css", "styles.css"].map((f) => path31.join(opts.bundleDir, f)).filter((f) => existsSync25(f)).map((f) => readFileSync22(f, "utf8")).join("\n");
   const occlusion = await checkSiblingOcclusion(task, opts.bundleDir, bundleCss);
   const parity = await checkHoverParity(task, opts.bundleDir);
@@ -9029,6 +9396,10 @@ async function runVerify(opts) {
         status = "pass";
         certDemote.push(...s.absentInk.map((c) => `absent ink: ${c.name ?? "unnamed region"} \u2014 ${c.px}px of recorded ink with no render ink within reach (missing or invisible feature)`));
       }
+      if (status === "certified" && substitutedFamilies.length > 0) {
+        status = "pass";
+        certDemote.push(`substituted fonts: cache lacks ${substitutedFamilies.map((f) => `"${f}"`).join(", ")} \u2014 certification never measures a substitute face`);
+      }
       const base = certDemote.length > 0 ? { ...reported, status, demotedBy: certDemote } : { ...reported, status };
       const reasons = demotions.get(s.rep);
       return reasons === void 0 ? base : { ...base, status: "fail", demotedBy: [...certDemote.length > 0 ? certDemote : [], ...reasons] };
@@ -9191,9 +9562,27 @@ ${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuse
     }
     process.stdout.write(`environment: chrome=${report.environment.chromeVersion ?? report.environment.chrome} fonts=${report.environment.fontsManifestSha256 ?? "UNRESOLVED"}
 `);
+    const shippedFonts = requiredFontsManifest(cssFontFamilies(["styles.css", "tokens.css"].map((f) => path31.join(opts.bundleDir, f)).filter((f) => existsSync25(f)).map((f) => readFileSync22(f, "utf8")).join("\n")));
+    if (shippedFonts.length > 0 && substitutedFamilies.length === 0) {
+      process.stdout.write(`fonts: scored with Tendril-cache faces \u2014 a consuming app must provision the same families (the bundle ships fonts.css when faces are shippable; sha-pinned list in component.json requiredFonts)
+`);
+    }
     process.stdout.write(`evidence: ${evidenceDir} (render/ref/diff per config)
 `);
   });
+  if (opts.bar === "cert" && substitutedFamilies.length > 0) {
+    const names = substitutedFamilies.map((f) => `"${f}"`).join(", ");
+    if (opts.json) {
+      process.stderr.write(`${JSON.stringify({ error: `font cache lacks ${names} \u2014 certification never measures a substitute face (scores above are pass-capped)`, code: "fonts-unproven", remediation: fontsUnprovenRemediation(task.set) })}
+`);
+    } else {
+      process.stderr.write(`error (fonts-unproven): font cache lacks ${names} \u2014 certification never measures a substitute face (scores above are pass-capped)
+  \u2192 ${fontsUnprovenRemediation(task.set)}
+`);
+    }
+    process.exitCode = ExitCode.FontsUnproven;
+    return;
+  }
   if (!ok) {
     warn(
       opts,
@@ -9227,7 +9616,7 @@ __export(engine_exports, {
   runEngineBrief: () => runEngineBrief,
   runEngineScore: () => runEngineScore
 });
-import { existsSync as existsSync26, mkdirSync as mkdirSync7, readFileSync as readFileSync23, writeFileSync as writeFileSync12 } from "node:fs";
+import { existsSync as existsSync26, mkdirSync as mkdirSync8, readFileSync as readFileSync23, writeFileSync as writeFileSync12 } from "node:fs";
 import path32 from "node:path";
 function resolveEngineTask(opts, callerCwd) {
   const asPath = path32.resolve(callerCwd, opts.taskOrSet);
@@ -9276,7 +9665,7 @@ DO NOT INVENT PIXELS FOR THESE POSES. Implement them ONLY as the composition of
 ${notRecorded}` : "";
   let fontProvisioning;
   if (existsSync26(manifestPath2)) {
-    const provided = resolvedFontFamilies().map((f) => f.family);
+    const provided = verifiedFontFamilies().map((f) => f.family);
     const unprovided = recordedFontFamilies(task.set).filter((r) => !provided.some((p) => p.toLowerCase() === r.toLowerCase()));
     if (unprovided.length > 0) {
       const names = unprovided.map((f) => `'${f}'`).join(", ");
@@ -9286,10 +9675,10 @@ ${notRecorded}` : "";
           prompt: `This design's text uses ${names}, which is not in the local font kit. How should it be handled?`,
           options: [
             `(Recommended) Run \`tendril fonts resolve --set ${task.set}\` \u2014 open-source families are fetched automatically. Any face that fails there is one you license privately: run \`tendril fonts add "<Family>" <weight> <file>\` with the .woff2/.ttf/.otf you hold (the file never leaves this machine). Then re-run this brief \u2014 exact text fidelity.`,
-            "Continue with a substitute face: generation proceeds in a provided family, the report discloses the substitution, and small text differences are expected and not fixable from CSS."
+            'Continue with a substitute face: generation proceeds in a provided family, no config can score "certified" under it (cert-bar runs exit fonts-unproven after their report), the substitution is disclosed, and small text differences are expected and not fixable from CSS.'
           ]
         },
-        nonInteractive: "Continue with the substitute and state the substitution in your report."
+        nonInteractive: opts.bar === "cert" ? `Resolve the families first (\`tendril fonts resolve --set ${task.set}\`) \u2014 this loop targets the cert bar, and scoring exits fonts-unproven under a substitute, so continuing without resolving is a dead end.` : "Continue with the substitute and state the substitution in your report."
       };
     }
   }
@@ -9298,7 +9687,7 @@ ${notRecorded}` : "";
 === TASK PAYLOAD (recorded truth, verbatim) ===
 ${segments}`;
   const payloadFile = path32.resolve(callerCwd, opts.out ?? `tendril-out/${name}-brief.md`);
-  mkdirSync7(path32.dirname(payloadFile), { recursive: true });
+  mkdirSync8(path32.dirname(payloadFile), { recursive: true });
   writeFileSync12(payloadFile, payload);
   emitData(
     opts,
@@ -9359,6 +9748,10 @@ async function runEngineScore(opts) {
       remediation: fontsUnprovenRemediation(task.set)
     });
   }
+  const substitutedFamilies = unprovisionedFamilies(task.set);
+  if (substitutedFamilies.length > 0) {
+    warn(opts, `substituted fonts: cache lacks ${substitutedFamilies.map((f) => `"${f}"`).join(", ")} \u2014 scores measure a substitute face and no config can be certified under one (the stamp covers only the provisioned subset); resolve the families to certify`);
+  }
   if (opts.rebind !== true && existsSync26(path32.join(candidateDir, "component.json"))) {
     const prior = (() => {
       try {
@@ -9391,7 +9784,7 @@ async function runEngineScore(opts) {
   const parityCoverage = parity.length > 0 ? `${parity.filter((p) => p.pass).length}/${parity.length} hover-forced configs` : "not applicable (no hover-forced configs in this set)";
   const obj = objective(scores, behaviors);
   const total = scores.length + behaviors.length;
-  const quality = await checkBundleQuality(candidateDir, task.entry);
+  const quality = await checkBundleQuality(candidateDir, task.entry, { dir: task.set, reps: task.configs.map((c) => c.rep) });
   const qualityFeedback = quality.findings.length === 0 && !quality.tokensAbsent ? "" : `
 
 QUALITY (does not affect the bar \u2014 fix alongside the failing configs):
@@ -9402,7 +9795,7 @@ ${[
   const allPass = obj[0] === total && total > 0;
   const certBar = BARS3["cert"];
   const parityDemoted = new Set(parity.filter((p) => !p.pass).map((p) => p.id.replace(/^parity:/, "")));
-  const certifiedReps = scores.filter((sc) => tierOf(sc, certBar) === "certified" && !parityDemoted.has(sc.rep) && (sc.absentInk === void 0 || sc.absentInk.length === 0)).map((sc) => sc.rep);
+  const certifiedReps = substitutedFamilies.length > 0 ? [] : scores.filter((sc) => tierOf(sc, certBar) === "certified" && !parityDemoted.has(sc.rep) && (sc.absentInk === void 0 || sc.absentInk.length === 0)).map((sc) => sc.rep);
   const certifiedSet = new Set(certifiedReps);
   const absentFindings = scores.flatMap((sc) => (sc.absentInk ?? []).map((c) => `- ${sc.rep}: ${c.name ?? "unnamed region"} \u2014 ${c.px}px of recorded ink with NO render ink within reach at [x ${c.x}-${c.x + c.w}, y ${c.y}-${c.y + c.h}] (missing or invisible feature; magnified crops in the evidence dir; coordinates are reference-space \u2014 subtract the config's seat for box-space). A certified-tier config with such a finding is demoted to pass.`));
   const absentBlock = absentFindings.length > 0 ? `
@@ -9423,7 +9816,8 @@ METRIC DEADBAND (read before iterating on near-misses): the scored similarity/in
     model: `${opts.model} (self-reported${opts.host !== void 0 ? ` via ${opts.host}` : ""})`,
     scores,
     behaviors,
-    environment: environmentStamp(taskFontFamilies(task.set))
+    environment: environmentStamp(taskFontFamilies(task.set)),
+    substitutedFamilies
   });
   emitData(
     opts,
@@ -9461,6 +9855,19 @@ ${obj[0]}/${total} \xB7 certified ${certifiedReps.length}/${total} \xB7 floor=${
       }
     }
   );
+  if (opts.bar === "cert" && substitutedFamilies.length > 0) {
+    const names = substitutedFamilies.map((f) => `"${f}"`).join(", ");
+    if (opts.json) {
+      process.stderr.write(`${JSON.stringify({ error: `font cache lacks ${names} \u2014 certification never measures a substitute face (scores above are pass-capped)`, code: "fonts-unproven", remediation: fontsUnprovenRemediation(task.set) })}
+`);
+    } else {
+      process.stderr.write(`error (fonts-unproven): font cache lacks ${names} \u2014 certification never measures a substitute face (scores above are pass-capped)
+  \u2192 ${fontsUnprovenRemediation(task.set)}
+`);
+    }
+    process.exitCode = ExitCode.FontsUnproven;
+    return;
+  }
   if (!allPass) process.exitCode = ExitCode.VerificationFailed;
 }
 var BARS3;
@@ -9660,9 +10067,402 @@ var init_codeconnect = __esm({
   }
 });
 
-// packages/cli/src/commands/generate-route.ts
-var generate_route_exports = {};
-__export(generate_route_exports, {
+// packages/mcp/src/server.ts
+import { createHash as createHash5 } from "node:crypto";
+import { existsSync as existsSync28, mkdtempSync as mkdtempSync3, readFileSync as readFileSync25, readdirSync as readdirSync8, writeFileSync as writeFileSync14 } from "node:fs";
+import os6 from "node:os";
+import path34 from "node:path";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
+import { z as z12 } from "zod";
+function sourceHash() {
+  const dir = path34.dirname(fileURLToPath5(import.meta.url));
+  const h = createHash5("sha256");
+  for (const f of readdirSync8(dir).filter((n) => n.endsWith(".ts")).sort()) {
+    h.update(f);
+    h.update(readFileSync25(path34.join(dir, f)));
+  }
+  return h.digest("hex").slice(0, 16);
+}
+var REPO_ROOT3, CLI_BIN, BUNDLED_CLI, CLI_SPAWN, str, optStr, TOOLS, BOOT_HASH;
+var init_server = __esm({
+  "packages/mcp/src/server.ts"() {
+    "use strict";
+    REPO_ROOT3 = path34.resolve(path34.dirname(fileURLToPath5(import.meta.url)), "..", "..", "..");
+    CLI_BIN = path34.join(REPO_ROOT3, "packages", "cli", "src", "bin.ts");
+    BUNDLED_CLI = path34.join(path34.dirname(fileURLToPath5(import.meta.url)), "tendril.js");
+    CLI_SPAWN = existsSync28(BUNDLED_CLI) ? { cmd: process.execPath, prefix: [BUNDLED_CLI] } : { cmd: "npx", prefix: ["tsx", CLI_BIN] };
+    str = (d) => z12.string().describe(d);
+    optStr = (d) => z12.string().optional().describe(d);
+    TOOLS = [
+      {
+        name: "tendril_record_plan",
+        description: "ENTRY POINT for implementing/building a React component from a Figma design or figma.com URL \u2014 start the Tendril pipeline here (after loading the tendril skill, if installed). Plans a recording session: computes the rep queue (anchor + one-factor + conflict crosses) from the verbatim get_metadata response (pass its blocks via metadataParts \u2014 no file to write) and persists the set manifest. Resumes if the set already exists. The output may carry USER QUESTIONS \u2014 defaultsToConfirm (which pose is the component's default) or a multiple-component-sets error (which set to record): render them to a present user and apply the answers via `defaults` / `componentSet`; non-interactive runs follow each question's stated fallback. Recording cost is stated in figmaCallEstimate, never asked about \u2014 proceed with what the user provided.",
+        schema: z12.object({
+          setDir: str("recording set directory to create/resume"),
+          component: str("component/system name"),
+          // Parts array FIRST, same reason as ingest_rep: real responses
+          // are usually multi-block, and the file param made plan the ONE
+          // remaining hand-built-envelope entry point (run 10: the agent
+          // wrote the file twice — once as text, once as JSON envelope).
+          metadataParts: z12.array(z12.string()).optional().describe("the frame-level get_metadata response blocks, every block in order, each verbatim \u2014 never hand-join or save them yourself; this is the NORMAL param"),
+          metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
+          metadataFiles: z12.array(z12.string()).optional().describe('saved verbatim get_metadata envelope file paths \u2014 JSON shape {"content":[{"type":"text","text":"<frame \u2026>"}]}; optionally <file>@<frameId>. Prefer metadataParts: no file to write'),
+          defaults: z12.array(z12.string()).optional().describe(`axis defaults as "Axis=Value" (from the user's defaultsToConfirm answers; may re-plan a set with nothing recorded yet)`),
+          componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)")
+        }),
+        // Texts ride temp files, never argv: Windows caps a command line at
+        // ~32 KB and metadata envelopes can exceed it.
+        argv: (i) => {
+          const argvOut = ["record", "plan", "--set", i["setDir"], "--component", i["component"]];
+          if (i["metadata"] !== void 0 && i["metadataParts"] !== void 0) throw new Error("pass at most one of `metadata` and `metadataParts`");
+          const files = i["metadataFiles"];
+          if (files !== void 0 && files.length > 0) argvOut.push("--metadata", ...files);
+          const single = i["metadata"];
+          const parts = i["metadataParts"];
+          if (single !== void 0 || parts !== void 0) {
+            const tmp = path34.join(mkdtempSync3(path34.join(os6.tmpdir(), "tendril-envelope-")), "response.txt");
+            if (single !== void 0) {
+              writeFileSync14(tmp, single);
+              argvOut.push("--metadata-raw-file", tmp);
+            } else {
+              if (parts.length === 0) throw new Error("`metadataParts` must be a non-empty array of block texts");
+              writeFileSync14(tmp, JSON.stringify(parts));
+              argvOut.push("--metadata-raw-parts-file", tmp);
+            }
+          }
+          if (argvOut.length === 6) throw new Error("nothing to plan from \u2014 pass metadataParts (normal), metadata (single-block), or metadataFiles");
+          argvOut.push(...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [], ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : []);
+          return argvOut;
+        }
+      },
+      {
+        name: "tendril_doctor",
+        annotations: { readOnlyHint: true },
+        description: "Machine readiness + version status in one shot: installed vs latest version (with publish date and update remediation), browser identity, font-cache state, Figma desktop MCP reachability. Use to self-diagnose before recording/scoring, or whenever versions are in question. Exit 1 = something not ready; the report says exactly what and how to fix it.",
+        schema: z12.object({}),
+        argv: () => ["doctor"]
+      },
+      {
+        name: "tendril_record_next",
+        annotations: { readOnlyHint: true },
+        description: "Get the next pending recording instruction (which Figma MCP tool to call for which node, and how to save it). RARELY NEEDED: every ingest/fetch response already carries `next` \u2014 use this only to resume an interrupted session. The full queue is known from plan, so independent reps may be recorded in any order (and in parallel).",
+        schema: z12.object({ setDir: str("recording set directory") }),
+        argv: (i) => ["record", "next", "--set", i["setDir"]]
+      },
+      {
+        name: "tendril_record_fetch",
+        description: "Download a Figma asset URL (from get_screenshot's image_url) straight to disk and ingest it as the rep's envelope \u2014 the fallback when only the screenshot piece needs (re-)recording; for a rep's standard three recordings PREFER tendril_record_ingest_rep. Never download the image yourself: the bytes must not pass through your context.",
+        schema: z12.object({
+          setDir: str("recording set directory"),
+          rep: str("planned rep slug"),
+          tool: z12.enum(["get_screenshot"]).describe("get_screenshot"),
+          url: str("image_url from the Figma response, verbatim")
+        }),
+        argv: (i) => ["record", "fetch", "--set", i["setDir"], "--rep", i["rep"], "--tool", i["tool"], "--url", i["url"]]
+      },
+      {
+        name: "tendril_record_ingest_rep",
+        description: "Ingest a rep's ENTIRE recording in ONE call \u2014 the get_metadata response, the get_design_context response, and the get_screenshot image_url together. Make the three Figma calls first, in protocol order (get_metadata, then get_design_context with excludeScreenshot=true, then get_screenshot), then pass all three here VERBATIM. PREFER THIS over three separate ingest/fetch calls: one approvable operation per rep instead of three. Pieces land independently: on a partial failure the error names exactly which piece(s) to re-record \u2014 the rest are already on disk. The response carries `next` and, for design context, `assets` (auto-fetched server-side; only listed failures need record_asset).",
+        schema: z12.object({
+          setDir: str("recording set directory"),
+          rep: str("planned rep slug"),
+          // Parts arrays FIRST: in the field, EVERY real Figma response is
+          // multi-block (run 6: 49/49 reps — metadata 2 blocks, design
+          // context 5-6), so the arrays are the norm and the single-string
+          // params the rare case, not the reverse.
+          metadataParts: z12.array(z12.string()).optional().describe("get_metadata response blocks, every block in order, each verbatim \u2014 never hand-join blocks yourself. Multi-block responses are common (run 6: 49/49 reps); a single block wrapped in a one-element array is equally fine."),
+          contextParts: z12.array(z12.string()).optional().describe("get_design_context response blocks, every block in order, each verbatim \u2014 the NORMAL param (real responses arrive as 5-6 blocks)"),
+          screenshotUrl: optStr("image_url from the get_screenshot response, verbatim \u2014 the CLI downloads it; the bytes never pass through your context"),
+          metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
+          context: optStr("ONLY when get_design_context genuinely returned one single block: its text verbatim (otherwise use contextParts)")
+        }),
+        // Texts ride temp files, never argv: Windows caps a command line at
+        // ~32 KB and design-context envelopes routinely exceed it.
+        argv: (i) => {
+          const argvOut = ["record", "ingest-rep", "--set", i["setDir"], "--rep", i["rep"]];
+          const bridge = (label, single, parts) => {
+            if (single !== void 0 && parts !== void 0) throw new Error(`pass at most one of \`${label}\` and \`${label}Parts\``);
+            if (single === void 0 && parts === void 0) return;
+            const tmp = path34.join(mkdtempSync3(path34.join(os6.tmpdir(), "tendril-envelope-")), "response.txt");
+            if (single !== void 0) {
+              writeFileSync14(tmp, single);
+              argvOut.push(`--${label}-file`, tmp);
+            } else {
+              const blocks = parts;
+              if (blocks.length === 0) throw new Error(`\`${label}Parts\` must be a non-empty array of block texts`);
+              writeFileSync14(tmp, JSON.stringify(blocks));
+              argvOut.push(`--${label}-parts-file`, tmp);
+            }
+          };
+          bridge("metadata", i["metadata"], i["metadataParts"]);
+          bridge("context", i["context"], i["contextParts"]);
+          if (i["screenshotUrl"] !== void 0) argvOut.push("--screenshot-url", i["screenshotUrl"]);
+          if (argvOut.length === 6) throw new Error("nothing to ingest \u2014 pass at least one of metadata/metadataParts, context/contextParts, screenshotUrl");
+          return argvOut;
+        }
+      },
+      {
+        name: "tendril_record_ingest",
+        description: "Single-piece ingest of a VERBATIM Figma tool-response \u2014 the fallback path (re-recording one failed piece, set-level get_variable_defs, get_metadata_interior for mains); for a rep's standard three recordings PREFER tendril_record_ingest_rep, which takes them all in one call. Pass `text` (single block) or `texts` (response split into multiple output blocks \u2014 each block verbatim, in order; NEVER hand-join them): the CLI constructs the envelope from the same bytes. The response includes `next` and, for get_design_context, `assets` (auto-fetched; only listed failures need manual handling).",
+        schema: z12.object({
+          setDir: str("recording set directory"),
+          rep: str("planned rep slug, or __set__ for the set-level get_variable_defs"),
+          // Enumerated, not a free string: this value reaches a file path.
+          // As a bare string it was an arbitrary relative-path overwrite
+          // (--tool "../../outside/victim" replaced a file outside the set,
+          // exit 0). The sink in session.ts now contains the path too — this
+          // is the second layer, and it makes the tool self-documenting.
+          tool: z12.enum(["get_design_context", "get_metadata", "get_screenshot", "get_variable_defs", "get_metadata_interior"]),
+          text: optStr("the tool response text VERBATIM \u2014 exactly as returned, unmodified (single-block responses; text tools only \u2014 screenshots go through record_fetch)"),
+          texts: z12.array(z12.string()).optional().describe("when the response arrived as MULTIPLE output blocks: every block, in order, each verbatim \u2014 never hand-join blocks yourself"),
+          file: optStr("path to a saved envelope JSON (alternative to text/texts)")
+        }),
+        // The text rides a temp file, never argv: Windows caps a command
+        // line at ~32 KB and design-context envelopes routinely exceed it.
+        argv: (i) => {
+          const base = ["record", "ingest", "--set", i["setDir"], "--rep", i["rep"], "--tool", i["tool"]];
+          const text = i["text"];
+          const texts = i["texts"];
+          const file = i["file"];
+          if ([text, texts, file].filter((x) => x !== void 0).length !== 1) throw new Error("pass exactly one of `text` (single-block response), `texts` (multi-block response), or `file` (a saved envelope)");
+          if (file !== void 0) return [...base, "--file", file];
+          const tmp = path34.join(mkdtempSync3(path34.join(os6.tmpdir(), "tendril-envelope-")), "response.txt");
+          if (text !== void 0) {
+            writeFileSync14(tmp, text);
+            return [...base, "--file", tmp, "--raw"];
+          }
+          writeFileSync14(tmp, JSON.stringify(texts));
+          return [...base, "--file", tmp, "--raw-parts"];
+        }
+      },
+      {
+        name: "tendril_record_asset",
+        description: "FALLBACK ONLY \u2014 ingest auto-fetches design-context assets; use this just for assets listed in an ingest response's `assets.failed`. Batch mode: pass `dir` to ingest every asset-*.<ext> in a directory in ONE call. SVGs with active content are rejected; sizes are capped.",
+        schema: z12.object({
+          setDir: str("recording set directory"),
+          rep: str("planned rep slug"),
+          name: optStr("asset-<id>.<ext> (single-asset mode)"),
+          file: optStr("downloaded asset file path (single-asset mode)"),
+          dir: optStr("batch mode: directory holding downloaded asset-*.<ext> files")
+        }),
+        argv: (i) => [
+          "record",
+          "asset",
+          "--set",
+          i["setDir"],
+          "--rep",
+          i["rep"],
+          ...i["dir"] !== void 0 ? ["--dir", i["dir"]] : ["--name", i["name"], "--file", i["file"]]
+        ]
+      },
+      {
+        name: "tendril_record_status",
+        annotations: { readOnlyHint: true },
+        description: "Recording-set completeness: per-rep recorded/missing tools.",
+        schema: z12.object({ setDir: str("recording set directory") }),
+        argv: (i) => ["record", "status", "--set", i["setDir"]]
+      },
+      {
+        name: "tendril_engine_brief",
+        description: "AGENT-HARNESS engine, step 1: emits the task payload file (system brief + every recorded config's emission, box, assets, tokens) and the protocol. YOU (the calling agent) implement the bundle; the CLI is the only judge. Read the payload file completely before proposing.",
+        schema: z12.object({
+          taskOrSet: str("a recording-set directory (from tendril_record), or a reference task name \u2014 an unknown name returns the valid list in the error"),
+          // Required by design, not convenience: the model choice must be
+          // settled BEFORE generation starts. A smoke run picked its own
+          // model silently because the ask lived in instruction text, which
+          // evaporates in non-interactive sessions; a required parameter
+          // cannot evaporate. Ask the user when one is present; otherwise
+          // choose, declare, and state the reason in your report.
+          model: str("the model that will WRITE the implementation \u2014 ask the user when interactive; declare your reasoned choice when not"),
+          bar: optStr("pass (default) or cert"),
+          out: optStr("payload file path override")
+        }),
+        argv: (i) => [
+          "engine",
+          "brief",
+          i["taskOrSet"],
+          "--model",
+          i["model"],
+          ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+          ...i["out"] !== void 0 ? ["--out", i["out"]] : []
+        ]
+      },
+      {
+        name: "tendril_engine_score",
+        description: "AGENT-HARNESS engine, step 2 (the oracle): scores a candidate bundle directory against recorded truth \u2014 per-config pixels, behaviors, hover parity \u2014 and returns feedback plus evidence artifacts. Iterate until allPass or two non-improving rounds. Only THIS tool's output counts as a score; never claim numbers yourself.",
+        schema: z12.object({
+          taskOrSet: str("reference task name or recording-set directory"),
+          candidateDir: str("directory containing the proposed bundle files"),
+          bar: optStr("pass (default) or cert"),
+          host: optStr("your host identity (e.g. claude-code, cursor, codex) \u2014 recorded as self-reported provenance"),
+          model: str("the model that proposed the candidate \u2014 REQUIRED; recorded as self-reported provenance, and the CLI refuses to score without it"),
+          rebind: z12.boolean().optional().describe("explicitly re-bind an already-bound bundle to a DIFFERENT recording set \u2014 scoring refuses this otherwise, because rebinding silently rewrites the bundle's verification identity; only pass after telling the user")
+        }),
+        argv: (i) => [
+          "engine",
+          "score",
+          i["taskOrSet"],
+          i["candidateDir"],
+          ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+          ...i["host"] !== void 0 ? ["--host", i["host"]] : [],
+          "--model",
+          i["model"],
+          ...i["rebind"] === true ? ["--rebind"] : []
+        ]
+      },
+      {
+        name: "tendril_codeconnect",
+        description: "Emit a Figma Code Connect template (.figma.ts) for a certified bundle \u2014 every Figma variant value mapped to its verified prop fragment from recorded truth, stamped with the bundle's trust statement. EXTRA VALUE step after verify passes: offer it to the user. Publishing is the USER'S action (their Figma token, Organization/Enterprise plan) \u2014 via npx @figma/code-connect connect publish, or the Figma MCP's own add_code_connect_map/send_code_connect_mappings tools if available in this session.",
+        schema: z12.object({
+          bundleDir: str("bundle directory (carries component.json)"),
+          figmaUrl: str("figma.com /design/ URL of the COMPONENT SET, with node-id (ask the user to Copy link to selection if you don't have it)"),
+          set: optStr("recording set override (default: the bundle's provenance path)"),
+          out: optStr("output file path (default: <bundle>/<Component>.figma.ts)")
+        }),
+        argv: (i) => [
+          "codeconnect",
+          i["bundleDir"],
+          "--figma-url",
+          i["figmaUrl"],
+          ...i["set"] !== void 0 ? ["--set", i["set"]] : [],
+          ...i["out"] !== void 0 ? ["--out", i["out"]] : []
+        ]
+      },
+      {
+        name: "tendril_verify",
+        description: "Verify/check that a component matches its Figma design \u2014 use when the user asks whether an implementation is faithful to the design, or to re-certify an existing Tendril bundle. Recomputes full verification (per-config status, behaviors, composition, evidence artifacts). Free, account-less, network-less \u2014 the trust anchor. Exit 5 means sub-bar with an honest report.",
+        schema: z12.object({
+          bundleDir: str("bundle directory to verify"),
+          bar: optStr("pass (default) or cert"),
+          set: optStr("recording-set directory override")
+        }),
+        argv: (i) => [
+          "verify",
+          i["bundleDir"],
+          ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+          ...i["set"] !== void 0 ? ["--set", i["set"]] : []
+        ]
+      },
+      {
+        name: "tendril_generate_curated",
+        description: "CURATED engine (explicit alternative path): generation by an allowlisted API model over the user's OpenRouter-compatible key, with cost consent, hard spend caps, and resume. Use ONLY when the user asks for API-model generation instead of implementing it yourself.",
+        schema: z12.object({
+          input: str("reference task name or recording-set directory"),
+          model: optStr("OpenRouter model id (default: allowlist pointer)"),
+          bar: optStr("pass (default) or cert"),
+          cap: optStr("spend cap in USD (default 1.50)"),
+          yes: z12.boolean().optional().describe("accept the cost consent (the user must have approved the spend)")
+        }),
+        argv: (i) => [
+          "generate",
+          i["input"],
+          ...i["model"] !== void 0 ? ["--model", i["model"]] : [],
+          ...i["bar"] !== void 0 ? ["--bar", i["bar"]] : [],
+          ...i["cap"] !== void 0 ? ["--cap", i["cap"]] : [],
+          ...i["yes"] === true ? ["--yes"] : []
+        ]
+      }
+    ];
+    BOOT_HASH = (() => {
+      try {
+        return sourceHash();
+      } catch {
+        return "unknown";
+      }
+    })();
+  }
+});
+
+// packages/cli/src/commands/permissions.ts
+var permissions_exports = {};
+__export(permissions_exports, {
+  PERMISSIONS_DESCRIPTION: () => PERMISSIONS_DESCRIPTION,
+  buildPermissions: () => buildPermissions,
+  runPermissions: () => runPermissions
+});
+async function buildPermissions(options) {
+  const LEGAL_TOOL_NAME = /^[A-Za-z0-9_-]+$/;
+  const pipeline = new Set(FIGMA_TOOL_FALLBACK);
+  let figmaTools = FIGMA_TOOL_FALLBACK;
+  try {
+    const client = new McpHttpClient({ url: options.mcpUrl ?? DEFAULT_MCP_URL, ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {} });
+    await client.initialize();
+    const live = (await client.listTools()).map((t) => t.name).filter((n) => LEGAL_TOOL_NAME.test(n) && pipeline.has(n));
+    if (live.length > 0) figmaTools = live;
+  } catch {
+  }
+  return {
+    host: "claude",
+    serverEntries: [TENDRIL_PLUGIN_PREFIX, FIGMA_PLUGIN_PREFIX],
+    toolEntries: [
+      ...TOOLS.map((t) => t.name).filter((n) => LEGAL_TOOL_NAME.test(n)).map((n) => `${TENDRIL_PLUGIN_PREFIX}__${n}`),
+      ...figmaTools.map((name) => `${FIGMA_PLUGIN_PREFIX}__${name}`)
+    ],
+    serverEntriesCaution: "The server-wide entries allow EVERY tool those servers serve \u2014 for tendril that includes tendril_generate_curated (spends your OpenRouter budget when configured), and for Figma every tool the desktop server exposes, beyond the read tools this pipeline uses. The per-tool list is the recommended default.",
+    directConfigNote: `Installed via claude mcp add instead of the plugin? Replace the prefixes: ${TENDRIL_PLUGIN_PREFIX}__<tool> becomes mcp__<your-server-name>__<tool> (same for Figma).`
+  };
+}
+async function runPermissions(flags) {
+  if (flags.describe) {
+    printDescription(PERMISSIONS_DESCRIPTION);
+    return;
+  }
+  const result = await buildPermissions({ ...flags.mcpUrl ? { mcpUrl: flags.mcpUrl } : {} });
+  emitData(flags, result, () => {
+    const quoted = (xs) => xs.map((x) => `    ${JSON.stringify(x)}`).join(",\n");
+    process.stdout.write(
+      `Claude Code allowlist for the Tendril pipeline.
+Paste into .claude/settings.json under permissions.allow:
+
+${quoted(result.toolEntries)}
+
+Shorter but broader \u2014 one entry per server:
+
+${quoted(result.serverEntries)}
+
+\u26A0 ${result.serverEntriesCaution}
+
+${result.directConfigNote}
+`
+    );
+  });
+}
+var FIGMA_TOOL_FALLBACK, PERMISSIONS_DESCRIPTION, TENDRIL_PLUGIN_PREFIX, FIGMA_PLUGIN_PREFIX;
+var init_permissions = __esm({
+  "packages/cli/src/commands/permissions.ts"() {
+    "use strict";
+    init_src();
+    init_server();
+    init_describe();
+    init_output();
+    init_doctor();
+    FIGMA_TOOL_FALLBACK = ["get_metadata", "get_design_context", "get_screenshot", "get_variable_defs", "get_motion_context", "get_figjam"];
+    PERMISSIONS_DESCRIPTION = {
+      name: "permissions",
+      summary: "Print a paste-ready Claude Code permission allowlist for the Tendril pipeline (tendril + Figma MCP tools).",
+      args: [],
+      flags: [
+        { flag: "--claude", description: "Claude Code settings.json format (the default and currently only format)" },
+        { flag: "--mcp-url <url>", description: "Figma MCP endpoint to list live tool names from", default: DEFAULT_MCP_URL },
+        { flag: "--json", description: "Machine-readable output" }
+      ],
+      output: {
+        host: '"claude"',
+        serverEntries: "string[] \u2014 one entry per MCP server (allows every tool it serves)",
+        toolEntries: "string[] \u2014 per-tool entries for selective allowlists",
+        directConfigNote: "string \u2014 prefix rewrite for non-plugin (claude mcp add) installs"
+      },
+      exitCodes: { 0: "always (informational)" },
+      examples: ["tendril permissions --claude", "tendril permissions --claude --json"]
+    };
+    TENDRIL_PLUGIN_PREFIX = "mcp__plugin_tendril_tendril";
+    FIGMA_PLUGIN_PREFIX = "mcp__plugin_figma_figma";
+  }
+});
+
+// packages/cli/src/commands/generate-route.ts
+var generate_route_exports = {};
+__export(generate_route_exports, {
   routeGenerate: () => routeGenerate
 });
 function routeGenerate(input) {
@@ -9684,17 +10484,17 @@ __export(generate_recorded_exports, {
   runGenerateRecorded: () => runGenerateRecorded
 });
 import { confirm as confirm3, isCancel as isCancel3 } from "@clack/prompts";
-import { existsSync as existsSync28, readFileSync as readFileSync25 } from "node:fs";
-import path34 from "node:path";
+import { existsSync as existsSync29, readFileSync as readFileSync26 } from "node:fs";
+import path35 from "node:path";
 async function runGenerateRecorded(opts) {
   const callerCwd = process.env["INIT_CWD"] ?? process.cwd();
-  const outDirAbs = path34.resolve(callerCwd, opts.out);
-  const recordedAsPath = path34.resolve(callerCwd, opts.recorded);
+  const outDirAbs = path35.resolve(callerCwd, opts.out);
+  const recordedAsPath = path35.resolve(callerCwd, opts.recorded);
   let task;
   let taskName;
   let authoredApi;
   let composition;
-  const isSet = existsSync28(path34.join(recordedAsPath, "recording-set.json"));
+  const isSet = existsSync29(path35.join(recordedAsPath, "recording-set.json"));
   const registry = TASKS[opts.recorded];
   if (registry !== void 0 && !isSet) {
     task = registry;
@@ -9703,7 +10503,7 @@ async function runGenerateRecorded(opts) {
     try {
       const authored = authorTaskFromSet(recordedAsPath);
       task = authored.task;
-      taskName = path34.basename(recordedAsPath);
+      taskName = path35.basename(recordedAsPath);
       authoredApi = authored.api;
       const roles = RolesSchema.safeParse(loadManifest(recordedAsPath).roles);
       if (roles.success) composition = roles.data;
@@ -9729,8 +10529,12 @@ async function runGenerateRecorded(opts) {
       remediation: fontsUnprovenRemediation(task.set)
     });
   }
+  const substitutedFamilies = unprovisionedFamilies(task.set);
+  if (substitutedFamilies.length > 0) {
+    warn(opts, `substituted fonts: cache lacks ${substitutedFamilies.map((f) => `"${f}"`).join(", ")} \u2014 scores measure a substitute face and no config can be certified under one (the stamp covers only the provisioned subset); resolve the families to certify`);
+  }
   const missing = task.configs.filter(
-    (c) => !existsSync28(path34.join(task.set, c.rep, "get_screenshot.json")) || !existsSync28(path34.join(task.set, c.rep, "get_metadata.json")) || !existsSync28(path34.join(task.set, c.rep, "get_design_context.json"))
+    (c) => !existsSync29(path35.join(task.set, c.rep, "get_screenshot.json")) || !existsSync29(path35.join(task.set, c.rep, "get_metadata.json")) || !existsSync29(path35.join(task.set, c.rep, "get_design_context.json"))
   );
   if (missing.length > 0) {
     fail(opts, ExitCode.RecordingIncomplete, {
@@ -9800,8 +10604,8 @@ async function runGenerateRecorded(opts) {
 ` : `${line}
 `);
   if (opts.dryRun) {
-    emitData(opts, { dryRun: true, task: taskName, model: modelId, consent, wouldWrite: path34.join(outDirAbs, taskName) }, () => {
-      process.stdout.write(`dry-run: nothing sent, nothing written (would write ${path34.join(outDirAbs, taskName)})
+    emitData(opts, { dryRun: true, task: taskName, model: modelId, consent, wouldWrite: path35.join(outDirAbs, taskName) }, () => {
+      process.stdout.write(`dry-run: nothing sent, nothing written (would write ${path35.join(outDirAbs, taskName)})
 `);
     });
     return;
@@ -9824,10 +10628,10 @@ async function runGenerateRecorded(opts) {
       });
     }
   }
-  const bundleDir = path34.join(outDirAbs, taskName);
-  if (existsSync28(path34.join(bundleDir, "component.json"))) {
+  const bundleDir = path35.join(outDirAbs, taskName);
+  if (existsSync29(path35.join(bundleDir, "component.json"))) {
     try {
-      const prior = readBundleManifest(readFileSync25(path34.join(bundleDir, "component.json"), "utf8")).manifest;
+      const prior = readBundleManifest(readFileSync26(path35.join(bundleDir, "component.json"), "utf8")).manifest;
       if (prior !== void 0 && prior.provenance.recordingSet.hash !== recordingSetHash(task.set, task.configs)) {
         fail(opts, ExitCode.InputValidation, {
           error: `${bundleDir} already holds a bundle bound to recording set "${prior.provenance.recordingSet.path}" \u2014 generating here against a different set would silently rewrite its verification identity`,
@@ -9859,7 +10663,7 @@ async function runGenerateRecorded(opts) {
   });
   const statuses = result.finalScores.map((s) => ({
     ...s,
-    status: s.similarity >= BARS4.cert.sim && s.inkRecall >= BARS4.cert.ink ? "certified" : s.pass ? "pass" : "fail"
+    status: s.similarity >= BARS4.cert.sim && s.inkRecall >= BARS4.cert.ink && substitutedFamilies.length === 0 ? "certified" : s.pass ? "pass" : "fail"
   }));
   const behaviorFailures = result.finalBehaviors.filter((b) => !b.pass);
   const pixelFailures = statuses.filter((s) => s.status === "fail");
@@ -9878,7 +10682,8 @@ async function runGenerateRecorded(opts) {
       scores: result.finalScores,
       behaviors: result.finalBehaviors,
       environment: environmentStamp(taskFontFamilies(task.set)),
-      spentUsd: result.spentUsd
+      spentUsd: result.spentUsd,
+      substitutedFamilies
     });
     trustStatement = emitted.manifest.trustStatement;
     process.stderr.write(opts.json ? `${JSON.stringify({ status: emitted.statusLine })}
@@ -9925,6 +10730,19 @@ ${certified}/${statuses.length} certified \xB7 ${statuses.length - pixelFailures
 `);
     }
   );
+  if (opts.bar === "cert" && substitutedFamilies.length > 0) {
+    const names = substitutedFamilies.map((f) => `"${f}"`).join(", ");
+    if (opts.json) {
+      process.stderr.write(`${JSON.stringify({ error: `font cache lacks ${names} \u2014 certification never measures a substitute face (scores above are pass-capped)`, code: "fonts-unproven", remediation: fontsUnprovenRemediation(task.set) })}
+`);
+    } else {
+      process.stderr.write(`error (fonts-unproven): font cache lacks ${names} \u2014 certification never measures a substitute face (scores above are pass-capped)
+  \u2192 ${fontsUnprovenRemediation(task.set)}
+`);
+    }
+    process.exitCode = ExitCode.FontsUnproven;
+    return;
+  }
   if (!ok) {
     warn(opts, `${pixelFailures.length} config(s) and ${behaviorFailures.length} behavior(s) below the ${opts.bar} bar \u2014 bundle written, verdict honest (Q4)`);
     process.exitCode = ExitCode.VerificationFailed;
@@ -9958,195 +10776,17 @@ import { CommanderError } from "commander";
 // packages/cli/src/program.ts
 init_src3();
 init_environment();
+init_doctor();
 import { Command } from "commander";
 
-// packages/cli/src/commands/doctor.ts
-init_src4();
-init_src();
-import { existsSync as existsSync17, readFileSync as readFileSync14, readdirSync as readdirSync3 } from "node:fs";
-import os4 from "node:os";
-import path22 from "node:path";
-
-// packages/cli/src/describe.ts
-var COMMON_EXIT_CODES = {
-  0: "success",
-  1: "general error",
-  2: "authentication error",
-  3: "input validation error",
-  4: "confirmation required (re-run with --yes or answer the prompt)"
-};
-function printDescription(description) {
-  process.stdout.write(`${JSON.stringify(description, null, 2)}
-`);
-}
-
-// packages/cli/src/commands/doctor.ts
-init_env();
-init_environment();
-init_output();
-init_entitlement();
-var DEFAULT_MCP_URL = "http://127.0.0.1:3845/mcp";
-var DOCTOR_DESCRIPTION = {
-  name: "doctor",
-  summary: "Check whether this machine can run tendril generate end to end.",
-  args: [],
-  flags: [
-    { flag: "--mcp-url <url>", description: "Figma MCP endpoint", default: DEFAULT_MCP_URL },
-    { flag: "--json", description: "Machine-readable output" }
-  ],
-  output: {
-    ok: "boolean \u2014 Figma desktop MCP reachable AND a scoring browser found (fonts resolve lazily per design system; keys are informational)",
-    checks: "[{ name, ok, detail, remediation? }]"
-  },
-  exitCodes: { 0: "healthy", 1: "one or more required checks failed" },
-  examples: ["tendril doctor", "tendril doctor --json"]
-};
-async function runDoctorChecks(options) {
-  const checks = [];
-  const mcpUrl = options.mcpUrl ?? DEFAULT_MCP_URL;
-  const client = new McpHttpClient({
-    url: mcpUrl,
-    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
-  });
-  try {
-    const info = await client.initialize();
-    const tools = await client.listTools();
-    checks.push({
-      name: "figma-desktop-mcp",
-      ok: true,
-      detail: `${info.name} ${info.version} (protocol ${info.protocolVersion}), ${tools.length} tools: ${tools.map((t) => t.name).join(", ")}`
-    });
-  } catch (err) {
-    checks.push({
-      name: "figma-desktop-mcp",
-      ok: false,
-      detail: err instanceof Error ? err.message : String(err),
-      remediation: err instanceof McpUnavailableError ? "Open the Figma desktop app, sign in, then Figma menu \u2192 Preferences \u2192 Enable local MCP server (Dev or Full seat on a paid plan)." : "The server answered but the exchange failed \u2014 check the signed-in account's seat, then retry."
-    });
-  }
-  const openrouterKey = resolveCredential("OPENROUTER_API_KEY");
-  checks.push(
-    openrouterKey ? { name: "openrouter-key", ok: true, detail: "OPENROUTER_API_KEY configured" } : {
-      name: "openrouter-key",
-      ok: false,
-      detail: "OPENROUTER_API_KEY not set \u2014 optional; only the curated API-model engine needs it",
-      remediation: "Run `tendril init` to store your OpenRouter key (BYOK) if you plan to use the curated engine."
-    }
-  );
-  try {
-    const chrome = resolveChrome();
-    checks.push({ name: "browser", ok: true, detail: `${chromeVersion() ?? "version unknown"} at ${chrome}` });
-  } catch (err) {
-    checks.push({
-      name: "browser",
-      ok: false,
-      detail: err instanceof Error ? err.message : String(err),
-      remediation: "Install Google Chrome (or Chromium), or set CHROME_PATH to a Chromium-family browser binary."
-    });
-  }
-  const fontManifest = path22.join(fontCacheDir(), "manifest.json");
-  checks.push(
-    existsSync17(fontManifest) ? { name: "font-cache", ok: true, detail: `resolved font cache at ${fontCacheDir()} (${JSON.parse(readFileSync14(fontManifest, "utf8")).length} faces)` } : {
-      name: "font-cache",
-      ok: true,
-      detail: `font cache empty at ${fontCacheDir()} \u2014 normal on a fresh machine; faces resolve per design system at first use`,
-      remediation: "Nothing to do now: `tendril fonts resolve --set <recording-dir>` fetches exactly what a recording declares, and generate/verify name that command when they need it."
-    }
-  );
-  const pluginRoot = path22.join(os4.homedir(), ".claude", "plugins", "cache", "tendrilapp", "tendril");
-  if (existsSync17(pluginRoot)) {
-    try {
-      const versions = readdirSync3(pluginRoot).filter((v) => /^\d+\.\d+\.\d+$/.test(v));
-      const newest = versions.sort((a, b) => versionIsNewer(a, b) ? 1 : -1)[0];
-      if (newest !== void 0) {
-        const skewed = versionIsNewer(newest, cliVersion());
-        checks.push(
-          skewed ? {
-            name: "plugin-skew",
-            ok: false,
-            detail: `Claude Code plugin cache holds v${newest} while this CLI is ${cliVersion()} \u2014 the plugin's skill/agents are STALE and will silently shadow current doctrine`,
-            remediation: "Update the plugin \u2014 REFRESH THE MARKETPLACE FIRST (its local clone goes stale and a reinstall faithfully reinstalls the old version): terminal Claude Code \u2014 `claude plugin marketplace update tendrilapp` then `claude plugin update tendril`; VS Code extension \u2014 /plugins panel \u2192 Marketplaces tab \u2192 refresh tendrilapp, THEN Plugins tab \u2192 uninstall + reinstall tendril, reopen the chat panel. If the refresh doesn't take, remove the tendrilapp marketplace entirely and re-add TendrilApp/claude-plugin (a fresh clone cannot be stale)."
-          } : { name: "plugin-skew", ok: true, detail: `Claude Code plugin v${newest} matches this CLI` }
-        );
-      }
-    } catch {
-    }
-  }
-  const ent = checkEntitlement();
-  checks.push(
-    ent.ok ? ent.mode === "pre-launch" ? { name: "entitlement", ok: true, detail: "pre-launch build \u2014 entitlement gates present but unarmed (no public key shipped); record/generate run freely" } : { name: "entitlement", ok: true, detail: `active plan "${ent.claims.plan}" until ${new Date(ent.claims.exp).toISOString().slice(0, 10)}${ent.stale ? " (stale \u2014 renews at next opportunity)" : ""}` } : { name: "entitlement", ok: false, detail: ent.error, remediation: ent.remediation }
-  );
-  const figmaToken = resolveCredential("FIGMA_TOKEN");
-  checks.push({
-    name: "figma-pat",
-    ok: true,
-    detail: figmaToken ? "FIGMA_TOKEN configured (REST fallback available)" : "FIGMA_TOKEN not set \u2014 optional; only needed for the REST fallback transport"
-  });
-  return { ok: checks.filter((c) => c.name !== "figma-pat" && c.name !== "openrouter-key").every((c) => c.ok), checks };
-}
-function versionIsNewer(a, b) {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((pb[i] ?? 0) > (pa[i] ?? 0)) return true;
-    if ((pb[i] ?? 0) < (pa[i] ?? 0)) return false;
-  }
-  return false;
-}
-async function latestVersionInfo() {
-  try {
-    const ctl = new AbortController();
-    const timer = setTimeout(() => ctl.abort(), 2500);
-    const res = await fetch("https://registry.npmjs.org/@tendrilapp%2fcli", { signal: ctl.signal });
-    clearTimeout(timer);
-    if (!res.ok) return null;
-    const doc = await res.json();
-    const latest = doc["dist-tags"]?.latest;
-    if (latest === void 0) return null;
-    const stamp = doc.time?.[latest];
-    return { latest, ...stamp !== void 0 ? { publishedAt: stamp.slice(0, 10) } : {} };
-  } catch {
-    return null;
-  }
-}
-async function runDoctor(flags) {
-  if (flags.describe) {
-    printDescription(DOCTOR_DESCRIPTION);
-    return;
-  }
-  const [report, latest] = await Promise.all([runDoctorChecks({ ...flags.mcpUrl ? { mcpUrl: flags.mcpUrl } : {} }), latestVersionInfo()]);
-  emitData(flags, { version: cliVersion(), ...latest !== null ? { latest: latest.latest, latestPublishedAt: latest.publishedAt ?? null, updateAvailable: versionIsNewer(cliVersion(), latest.latest) } : {}, ...report }, () => {
-    const version = cliVersion();
-    if (latest === null) {
-      process.stdout.write(`tendril ${version} (latest: unreachable)
-`);
-    } else if (!versionIsNewer(version, latest.latest)) {
-      process.stdout.write(`tendril ${version} (${latest.latest === version ? "latest" : `ahead of registry ${latest.latest}`}${latest.publishedAt !== void 0 ? `, published ${latest.publishedAt}` : ""})
-`);
-    } else {
-      process.stdout.write(`tendril ${version} \u2014 UPDATE AVAILABLE: ${latest.latest}${latest.publishedAt !== void 0 ? ` (published ${latest.publishedAt})` : ""}
-`);
-      process.stdout.write(`    \u2192 npm install -g @tendrilapp/cli@latest (plugin MCP users update automatically at next session; a stale npx cache clears with npm cache clean --force)
-`);
-    }
-    for (const check of report.checks) {
-      process.stdout.write(`${check.ok ? "\u2713" : "\u2717"} ${check.name}: ${check.detail}
-`);
-      if (check.remediation) process.stdout.write(`    \u2192 ${check.remediation}
-`);
-    }
-    process.stdout.write(report.ok ? "\nready to generate\n" : "\nnot ready \u2014 fix the items above\n");
-  });
-  if (!report.ok) process.exit(1);
-}
-
 // packages/cli/src/commands/init.ts
 init_src3();
+init_describe();
+init_env();
+init_output();
 import { intro, isCancel, outro, password } from "@clack/prompts";
 import fs from "node:fs";
 import path23 from "node:path";
-init_env();
-init_output();
 var INIT_DESCRIPTION = {
   name: "init",
   summary: "Configure Figma and OpenRouter credentials in .env (idempotent).",
@@ -10254,11 +10894,12 @@ init_src3();
 init_src();
 init_src5();
 init_src2();
-import { confirm as confirm2, isCancel as isCancel2 } from "@clack/prompts";
-import { readFileSync as readFileSync15, readdirSync as readdirSync4, existsSync as existsSync18 } from "node:fs";
+init_describe();
 init_env();
 init_output();
 init_entitlement();
+import { confirm as confirm2, isCancel as isCancel2 } from "@clack/prompts";
+import { readFileSync as readFileSync15, readdirSync as readdirSync4, existsSync as existsSync18 } from "node:fs";
 
 // packages/cli/src/pipeline.ts
 init_src2();
@@ -11005,7 +11646,7 @@ function buildProgram() {
     await runActivate2({ ...flags, serviceUrl: local["serviceUrl"] });
   });
   const record = program.command("record").description("Agent-driven recording protocol: plan the queue, get instructions, ingest verbatim envelopes, resume from disk.");
-  record.command("plan").requiredOption("--set <dir>", "recording set directory").requiredOption("--component <name>", "component/system name").requiredOption("--metadata <file...>", "verbatim get_metadata envelope(s), optionally <file>@<frameId>").option("--default <axis=value...>", "explicit axis default, e.g. --default State=Rest (repeatable; persisted to the manifest; may re-plan an unrecorded set)").option("--component-set <name>", "when the metadata holds several component sets, record only this one (name = the set label in the plan error)").option("--sample", "cost sampling: anchor + one-factor + conflict crosses only (the FULL variant matrix is the default; sampling is blind to multi-axis interactions)").action(async (_o, cmd) => {
+  record.command("plan").requiredOption("--set <dir>", "recording set directory").requiredOption("--component <name>", "component/system name").option("--metadata <file...>", "verbatim get_metadata envelope(s), optionally <file>@<frameId>").option("--metadata-raw-file <file>", "the get_metadata response TEXT exactly as received (single block); the CLI builds the envelope itself").option("--metadata-raw-parts-file <file>", "a JSON array of the get_metadata response blocks, each verbatim, in order (multi-block responses)").option("--default <axis=value...>", "explicit axis default, e.g. --default State=Rest (repeatable; persisted to the manifest; may re-plan an unrecorded set)").option("--component-set <name>", "when the metadata holds several component sets, record only this one (name = the set label in the plan error)").option("--sample", "cost sampling: anchor + one-factor + conflict crosses only (the FULL variant matrix is the default; sampling is blind to multi-axis interactions)").action(async (_o, cmd) => {
     const flags = globalFlags(cmd.parent.parent);
     const local = cmd.opts();
     const { runRecordPlan: runRecordPlan2 } = await Promise.resolve().then(() => (init_record(), record_exports));
@@ -11013,8 +11654,10 @@ function buildProgram() {
       ...flags,
       setDir: local["set"],
       component: local["component"],
-      metadataFiles: local["metadata"],
       sample: local["sample"],
+      ...local["metadata"] !== void 0 ? { metadataFiles: local["metadata"] } : {},
+      ...local["metadataRawFile"] !== void 0 ? { metadataRawFile: local["metadataRawFile"] } : {},
+      ...local["metadataRawPartsFile"] !== void 0 ? { metadataRawPartsFile: local["metadataRawPartsFile"] } : {},
       ...local["default"] !== void 0 ? { defaultSpecs: local["default"] } : {},
       ...local["componentSet"] !== void 0 ? { componentSet: local["componentSet"] } : {}
     });
@@ -11146,6 +11789,12 @@ function buildProgram() {
       ...local["out"] !== void 0 ? { out: local["out"] } : {}
     });
   });
+  program.command("permissions").description("Print a paste-ready Claude Code permission allowlist for the Tendril pipeline (tendril + Figma MCP tools) \u2014 no more transcribing tool names from prompts.").option("--claude", "Claude Code settings.json format (the default and currently only format)").option("--mcp-url <url>", "Figma MCP endpoint to list live tool names from").action(async (_o, cmd) => {
+    const flags = globalFlags(cmd.parent);
+    const local = cmd.opts();
+    const { runPermissions: runPermissions2 } = await Promise.resolve().then(() => (init_permissions(), permissions_exports));
+    await runPermissions2({ ...flags, ...local["mcpUrl"] !== void 0 ? { mcpUrl: local["mcpUrl"] } : {} });
+  });
   program.command("verify").description("Recompute verification for a generated bundle against its recording set (per-config status, behaviors, honest exit codes).").argument("<bundleDir>", "bundle directory to verify").option("--task <name>", "legacy task adapter for bundles WITHOUT component.json (bundle v1 carries its own prop manifest)").option("--set <dir>", "recording set directory (overrides the bundle's provenance path)").option("--bar <bar>", "target bar: pass (0.95) or cert (0.97)", "pass").action(async (bundleDir, _opts, cmd) => {
     const flags = globalFlags(cmd);
     const local = cmd.opts();