@tendrilapp/cli 0.1.21 → 0.1.24

package/dist/tendril.js

@@ -939,14 +939,25 @@ function manifestMains(manifest) {
 function requiredToolsFor(manifest, slug) {
   return manifestMains(manifest).includes(slug) ? [...REQUIRED_TOOLS, INTERIOR_TOOL] : REQUIRED_TOOLS;
 }
-function loadManifest(setDir) {
+function readManifestFile(setDir) {
   const p = manifestPath(setDir);
   if (!existsSync(p)) throw new Error(`no recording-set.json in ${setDir} \u2014 run \`tendril record plan\` first`);
-  return SessionManifestSchema.parse(JSON.parse(readFileSync(p, "utf8")));
+  const raw = JSON.parse(readFileSync(p, "utf8"));
+  return { manifest: SessionManifestSchema.parse(raw), raw };
+}
+function loadManifest(setDir) {
+  return readManifestFile(setDir).manifest;
+}
+function writeManifest(setDir, raw) {
+  const manifest = SessionManifestSchema.parse(raw);
+  mkdirSync(setDir, { recursive: true });
+  writeFileSync(manifestPath(setDir), `${JSON.stringify(raw, null, 1)}
+`);
+  return manifest;
 }
 function planSet(setDir, component, symbols, opts = {}) {
   if (existsSync(manifestPath(setDir))) {
-    const existing = loadManifest(setDir);
+    const { manifest: existing, raw } = readManifestFile(setDir);
     const wantsNewDefaults = opts.defaults !== void 0 && JSON.stringify(opts.defaults) !== JSON.stringify(existing.defaults ?? {});
     const anythingRecorded = existing.reps.some((r) => RECORD_TOOLS.some((t) => existsSync(path.join(setDir, r.slug, `${t}.json`))));
     if (!wantsNewDefaults || anythingRecorded) {
@@ -963,12 +974,11 @@ function planSet(setDir, component, symbols, opts = {}) {
             usedSlugs.add(slug);
             return { slug, nodeId: r.nodeId, ...r.sourceFrame !== void 0 ? { sourceFrame: r.sourceFrame } : {} };
           });
-          existing.reps.push(...appended);
-          existing.planMode = "full";
-          delete existing.notRecorded;
-          writeFileSync(manifestPath(setDir), `${JSON.stringify(existing, null, 1)}
-`);
-          return { manifest: existing, plan: { reps: [], notRecorded: [] }, resumed: true, toppedUp: appended.map((a) => ({ slug: a.slug, nodeId: a.nodeId })) };
+          raw["reps"].push(...appended);
+          raw["planMode"] = "full";
+          delete raw["notRecorded"];
+          const manifest2 = writeManifest(setDir, raw);
+          return { manifest: manifest2, plan: { reps: [], notRecorded: [] }, resumed: true, toppedUp: appended.map((a) => ({ slug: a.slug, nodeId: a.nodeId })) };
         }
       }
       return { manifest: existing, plan: { reps: [], notRecorded: [] }, resumed: true };
@@ -989,9 +999,7 @@ function planSet(setDir, component, symbols, opts = {}) {
     planMode: opts.sample === true ? "sample" : "full",
     ...plan.notRecorded.length > 0 ? { notRecorded: plan.notRecorded.map((n) => `${n.name} (${n.nodeId}): ${n.reason}`).join("; ") } : {}
   };
-  mkdirSync(setDir, { recursive: true });
-  writeFileSync(manifestPath(setDir), `${JSON.stringify(manifest, null, 1)}
-`);
+  writeManifest(setDir, manifest);
   return { manifest, plan, resumed: false };
 }
 function sessionStatus(setDir) {
@@ -1216,8 +1224,8 @@ var init_src = __esm({
 function variableNameToPath(name) {
   return name.split("/").map(canonicalCssIdentPart).filter((part) => part.length > 0);
 }
-function tokenPathToCssVar(path38) {
-  return `--${path38.join("-")}`;
+function tokenPathToCssVar(path40) {
+  return `--${path40.join("-")}`;
 }
 function toDtcgToken(variable, defaultMode) {
   const modes = Object.keys(variable.valuesByMode);
@@ -1261,11 +1269,11 @@ function toDtcgToken(variable, defaultMode) {
 }
 function mapVariablesToDtcg(variables, defaultMode = "light") {
   const entries = variables.map((variable) => {
-    const path38 = variableNameToPath(variable.name);
-    if (path38.length === 0) {
+    const path40 = variableNameToPath(variable.name);
+    if (path40.length === 0) {
       throw new DtcgMappingError("empty-name", `Figma variable ${variable.id} has an empty name`);
     }
-    return { variable, path: path38 };
+    return { variable, path: path40 };
   });
   const groupPrefixes = /* @__PURE__ */ new Set();
   for (const e of entries) {
@@ -1286,21 +1294,21 @@ function mapVariablesToDtcg(variables, defaultMode = "light") {
   }
   const tokens = {};
   const flat = [];
-  for (const { variable, path: path38 } of entries) {
+  for (const { variable, path: path40 } of entries) {
     const token = toDtcgToken(variable, defaultMode);
     let group = tokens;
-    for (const segment of path38.slice(0, -1)) {
+    for (const segment of path40.slice(0, -1)) {
       const existing = group[segment];
       group = existing ?? (group[segment] = {});
     }
-    const leaf = path38[path38.length - 1];
+    const leaf = path40[path40.length - 1];
     if (group[leaf] !== void 0) {
-      throw new DtcgMappingError("duplicate-path", `Duplicate token path "${path38.join(".")}" (variable ${variable.id})`);
+      throw new DtcgMappingError("duplicate-path", `Duplicate token path "${path40.join(".")}" (variable ${variable.id})`);
     }
     group[leaf] = token;
     flat.push({
-      path: path38.join("."),
-      cssVar: tokenPathToCssVar(path38),
+      path: path40.join("."),
+      cssVar: tokenPathToCssVar(path40),
       type: token.$type,
       value: token.$value
     });
@@ -1489,9 +1497,9 @@ function boundId(value) {
   return isObject(value) && typeof value["boundVariableId"] === "string" ? value["boundVariableId"] : void 0;
 }
 function resolveBinding(ctx, id) {
-  const path38 = ctx.pathById.get(id);
-  if (path38 === void 0) ctx.unresolved.add(id);
-  return path38;
+  const path40 = ctx.pathById.get(id);
+  if (path40 === void 0) ctx.unresolved.add(id);
+  return path40;
 }
 function parseVariantProps(name) {
   if (!name.includes("=")) return void 0;
@@ -1526,8 +1534,8 @@ function walk(ctx, raw) {
       if (!isObject(paint) || paint["visible"] === false) continue;
       const id = boundId(paint);
       if (id !== void 0) {
-        const path38 = resolveBinding(ctx, id);
-        if (path38 !== void 0) tokens.add(path38);
+        const path40 = resolveBinding(ctx, id);
+        if (path40 !== void 0) tokens.add(path40);
       } else if (typeof paint["color"] === "string") {
         ctx.hardcoded.push({ node: name, property, value: paint["color"] });
       }
@@ -1535,8 +1543,8 @@ function walk(ctx, raw) {
   }
   const radiusId = boundId(raw["cornerRadius"]);
   if (radiusId !== void 0) {
-    const path38 = resolveBinding(ctx, radiusId);
-    if (path38 !== void 0) tokens.add(path38);
+    const path40 = resolveBinding(ctx, radiusId);
+    if (path40 !== void 0) tokens.add(path40);
   } else if (typeof raw["cornerRadius"] === "number" && raw["cornerRadius"] !== 0) {
     ctx.hardcoded.push({ node: name, property: "border-radius", value: `${raw["cornerRadius"]}px` });
   }
@@ -1546,10 +1554,10 @@ function walk(ctx, raw) {
     layout = { mode: layoutMode === "HORIZONTAL" ? "flex-row" : "flex-column" };
     const gapId = boundId(raw["itemSpacing"]);
     if (gapId !== void 0) {
-      const path38 = resolveBinding(ctx, gapId);
-      if (path38 !== void 0) {
-        layout.gap = path38;
-        tokens.add(path38);
+      const path40 = resolveBinding(ctx, gapId);
+      if (path40 !== void 0) {
+        layout.gap = path40;
+        tokens.add(path40);
       }
     } else if (typeof raw["itemSpacing"] === "number" && raw["itemSpacing"] !== 0) {
       ctx.hardcoded.push({ node: name, property: "gap", value: `${raw["itemSpacing"]}px` });
@@ -1558,10 +1566,10 @@ function walk(ctx, raw) {
     for (const field of PADDING_FIELDS) {
       const id = boundId(raw[field]);
       if (id !== void 0) {
-        const path38 = resolveBinding(ctx, id);
-        if (path38 !== void 0) {
-          paddingPaths.push(path38);
-          tokens.add(path38);
+        const path40 = resolveBinding(ctx, id);
+        if (path40 !== void 0) {
+          paddingPaths.push(path40);
+          tokens.add(path40);
         }
       } else if (typeof raw[field] === "number" && raw[field] !== 0) {
         ctx.hardcoded.push({ node: name, property: field, value: `${raw[field]}px` });
@@ -1768,20 +1776,72 @@ var init_src3 = __esm({
   }
 });
 
+// packages/cli/src/invocation.ts
+import { existsSync as existsSync3, realpathSync } from "node:fs";
+import path3 from "node:path";
+import { fileURLToPath } from "node:url";
+function findPathTendril(pathEnv, platform) {
+  const dirs = pathEnv.split(path3.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 = path3.join(dir, name);
+      if (existsSync3(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+function packageRootOf(file) {
+  let dir = path3.dirname(file);
+  for (; ; ) {
+    if (existsSync3(path3.join(dir, "package.json"))) return dir;
+    const parent = path3.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function resolveInvocation(pathEnv, platform, selfFile = fileURLToPath(import.meta.url)) {
+  const binary = findPathTendril(pathEnv, platform);
+  if (binary === null) return NPX_INVOCATION;
+  try {
+    const onPath = packageRootOf(realpathSync(binary));
+    const self = packageRootOf(realpathSync(selfFile));
+    if (onPath === null || self === null) return NPX_INVOCATION;
+    return realpathSync(onPath) === realpathSync(self) ? "tendril" : NPX_INVOCATION;
+  } catch {
+    return NPX_INVOCATION;
+  }
+}
+function tendrilInvocation() {
+  cached ??= resolveInvocation(process.env["PATH"] ?? "", process.platform);
+  return cached;
+}
+function tendrilCommand(args) {
+  return `${tendrilInvocation()} ${args}`;
+}
+var NPX_INVOCATION, cached;
+var init_invocation = __esm({
+  "packages/cli/src/invocation.ts"() {
+    "use strict";
+    NPX_INVOCATION = "npx -y -p @tendrilapp/cli@latest tendril";
+    cached = null;
+  }
+});
+
 // packages/verify/src/browser.ts
 import { execFileSync } from "node:child_process";
-import { existsSync as existsSync3, readdirSync } from "node:fs";
-import path3 from "node:path";
+import { existsSync as existsSync4, readdirSync } from "node:fs";
+import path4 from "node:path";
 function resolveChrome() {
   const fromEnv = process.env["TENDRIL_CHROME"] ?? process.env["CHROME_PATH"];
   if (fromEnv !== void 0 && fromEnv !== "") {
-    if (!existsSync3(fromEnv)) {
+    if (!existsSync4(fromEnv)) {
       throw new Error(`CHROME_PATH points at ${fromEnv}, which does not exist \u2014 fix the variable or unset it to use discovery`);
     }
     return fromEnv;
   }
   const candidates = process.platform === "darwin" ? MAC_CANDIDATES : process.platform === "win32" ? WIN_CANDIDATES : [];
-  for (const c of candidates) if (existsSync3(c)) return c;
+  for (const c of candidates) if (existsSync4(c)) return c;
   if (process.platform !== "win32") {
     for (const name of PATH_NAMES) {
       try {
@@ -1795,7 +1855,7 @@ function resolveChrome() {
 }
 function versionFromInstallDir(exePath) {
   try {
-    const builds = readdirSync(path3.dirname(exePath), { withFileTypes: true }).filter((e) => e.isDirectory() && /^\d+(\.\d+){3}$/.test(e.name)).map((e) => e.name.split(".").map(Number));
+    const builds = readdirSync(path4.dirname(exePath), { withFileTypes: true }).filter((e) => e.isDirectory() && /^\d+(\.\d+){3}$/.test(e.name)).map((e) => e.name.split(".").map(Number));
     builds.sort((a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2] || a[3] - b[3]);
     return builds.length === 0 ? null : builds[builds.length - 1].join(".");
   } catch {
@@ -1807,7 +1867,7 @@ function windowsBrowserName(exePath) {
   if (p.includes("\\google\\chrome\\")) return "Google Chrome";
   if (p.includes("\\microsoft\\edge\\")) return "Microsoft Edge";
   if (p.includes("chromium")) return "Chromium";
-  return path3.win32.basename(exePath, ".exe");
+  return path4.win32.basename(exePath, ".exe");
 }
 function chromeVersion() {
   if (_version !== void 0) return _version;
@@ -1842,32 +1902,32 @@ var init_browser = __esm({
 });
 
 // packages/verify/src/runtime.ts
-import { existsSync as existsSync4, mkdtempSync, symlinkSync } from "node:fs";
+import { existsSync as existsSync5, mkdtempSync, symlinkSync } from "node:fs";
 import { createRequire } from "node:module";
 import os from "node:os";
-import path4 from "node:path";
-import { fileURLToPath } from "node:url";
+import path5 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 function runtimePackageRoot() {
   const env = process.env["TENDRIL_PACKAGE_ROOT"];
-  if (env !== void 0 && env !== "") return path4.resolve(env);
-  return path4.resolve(path4.dirname(fileURLToPath(import.meta.url)), "..");
+  if (env !== void 0 && env !== "") return path5.resolve(env);
+  return path5.resolve(path5.dirname(fileURLToPath2(import.meta.url)), "..");
 }
 function runtimeNodeModules() {
   const root = runtimePackageRoot();
-  for (let dir = root; ; dir = path4.dirname(dir)) {
-    const candidate = path4.basename(dir) === "node_modules" ? dir : path4.join(dir, "node_modules");
-    if (existsSync4(path4.join(candidate, "react"))) return candidate;
-    if (path4.dirname(dir) === dir) break;
+  for (let dir = root; ; dir = path5.dirname(dir)) {
+    const candidate = path5.basename(dir) === "node_modules" ? dir : path5.join(dir, "node_modules");
+    if (existsSync5(path5.join(candidate, "react"))) return candidate;
+    if (path5.dirname(dir) === dir) break;
   }
   throw new Error(
     `Tendril's installed dependencies are missing: no node_modules containing react found at or above ${root}. This is an INSTALLATION problem, not a component error \u2014 reinstall with \`npm install -g @tendrilapp/cli\` (or \`tendrilapp\`) and retry.`
   );
 }
 function newScratchDir(prefix) {
-  const dir = mkdtempSync(path4.join(os.tmpdir(), `tendril-${prefix}-`));
+  const dir = mkdtempSync(path5.join(os.tmpdir(), `tendril-${prefix}-`));
   const nodeModules = runtimeNodeModules();
   try {
-    symlinkSync(nodeModules, path4.join(dir, "node_modules"), "junction");
+    symlinkSync(nodeModules, path5.join(dir, "node_modules"), "junction");
   } catch (err) {
     throw new Error(
       `Tendril could not link its dependencies into the scratch dir (${nodeModules} -> ${dir}): ${err instanceof Error ? err.message : String(err)}. This is an environment problem, not a component error.`
@@ -1876,7 +1936,7 @@ function newScratchDir(prefix) {
   return dir;
 }
 function reactPinPlugin() {
-  const req = createRequire(path4.join(runtimePackageRoot(), "package.json"));
+  const req = createRequire(path5.join(runtimePackageRoot(), "package.json"));
   return {
     name: "tendril-react-pin",
     setup(b) {
@@ -1929,9 +1989,9 @@ var init_gates = __esm({
 
 // packages/verify/src/tsc-check.ts
 import ts from "typescript";
-import path5 from "node:path";
+import path6 from "node:path";
 function runTscStrict(files) {
-  const program = ts.createProgram(files.map((f) => path5.resolve(f)), STRICT_OPTIONS);
+  const program = ts.createProgram(files.map((f) => path6.resolve(f)), STRICT_OPTIONS);
   const diagnostics = ts.getPreEmitDiagnostics(program);
   const mapped = diagnostics.map((d) => {
     const file = d.file?.fileName;
@@ -2090,7 +2150,7 @@ var init_token_lint = __esm({
 
 // packages/verify/src/loop.ts
 import { rmSync, writeFileSync as writeFileSync2 } from "node:fs";
-import path6 from "node:path";
+import path7 from "node:path";
 async function runChecks(componentName, files, extraFiles, definedVars2) {
   const findings = [];
   for (const violation of scanForbiddenPatterns(files.tsx)) {
@@ -2105,10 +2165,10 @@ async function runChecks(componentName, files, extraFiles, definedVars2) {
   }
   const workDir = newScratchDir("loop");
   try {
-    const tsxPath = path6.join(workDir, `${componentName}.tsx`);
+    const tsxPath = path7.join(workDir, `${componentName}.tsx`);
     writeFileSync2(tsxPath, files.tsx);
     for (const [name, content] of Object.entries(extraFiles ?? {})) {
-      writeFileSync2(path6.join(workDir, name), content);
+      writeFileSync2(path7.join(workDir, name), content);
     }
     const tsc = runTscStrict([tsxPath]);
     for (const d of tsc.diagnostics) {
@@ -2275,11 +2335,11 @@ var init_report = __esm({
 });
 
 // packages/verify/src/mount-limits.ts
-function lcdTextDisabled() {
-  return process.env["TENDRIL_DISABLE_LCD_TEXT"] === "1";
+function lcdTextEnabled() {
+  return process.env["TENDRIL_ENABLE_LCD_TEXT"] === "1";
 }
 function mountArgs() {
-  return [MEMORY_CAP_ARG, ...lcdTextDisabled() ? ["--disable-lcd-text"] : []];
+  return [MEMORY_CAP_ARG, ...lcdTextEnabled() ? [] : ["--disable-lcd-text"]];
 }
 function raceMountDeadline(work, deadlineMs, onDeadline) {
   return Promise.race([
@@ -2750,8 +2810,8 @@ var init_image_diff = __esm({
 });
 
 // packages/verify/src/visual-facts.ts
-import path7 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import path8 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { build } from "esbuild";
 import { chromium } from "playwright-core";
 function resolveAxisValue(declared, props, axis, value) {
@@ -3295,7 +3355,7 @@ var init_visual_facts = __esm({
     init_browser();
     init_mount_limits();
     init_image_diff();
-    RESOLVE_DIR = path7.resolve(path7.dirname(fileURLToPath2(import.meta.url)), "..");
+    RESOLVE_DIR = path8.resolve(path8.dirname(fileURLToPath3(import.meta.url)), "..");
     TOLERANCE_PX = 2;
     WIDTH_SLACK = 0.25;
     IMAGE_SIMILARITY_FLOOR = 0.8;
@@ -3304,26 +3364,41 @@ var init_visual_facts = __esm({
 });
 
 // packages/verify/src/paths.ts
-import path8 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import path9 from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 var VERIFY_PKG_DIR, REPO_ROOT;
 var init_paths = __esm({
   "packages/verify/src/paths.ts"() {
     "use strict";
-    VERIFY_PKG_DIR = path8.resolve(path8.dirname(fileURLToPath3(import.meta.url)), "..");
-    REPO_ROOT = path8.resolve(VERIFY_PKG_DIR, "..", "..");
+    VERIFY_PKG_DIR = path9.resolve(path9.dirname(fileURLToPath4(import.meta.url)), "..");
+    REPO_ROOT = path9.resolve(VERIFY_PKG_DIR, "..", "..");
   }
 });
 
 // packages/verify/src/font-resolve.ts
 import { createHash } from "node:crypto";
-import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import os2 from "node:os";
-import path9 from "node:path";
+import path10 from "node:path";
 function fontCacheDir() {
   const env = process.env["TENDRIL_FONT_CACHE"];
-  if (env !== void 0 && env !== "") return path9.resolve(env);
-  return path9.join(os2.homedir(), ".tendril", "fonts");
+  if (env !== void 0 && env !== "") return path10.resolve(env);
+  return path10.join(os2.homedir(), ".tendril", "fonts");
+}
+function normalizeFontLicense(value) {
+  return typeof value === "string" && FONT_LICENSES.includes(value) ? value : "unknown";
+}
+async function googleFontMetadata(queryName) {
+  try {
+    const res = await fetch(`https://fonts.google.com/metadata/fonts/${encodeURIComponent(queryName)}`, { headers: { "User-Agent": UA } });
+    if (!res.ok) return { license: "unknown", family: null };
+    const parsed = JSON.parse((await res.text()).replace(/^\)\]\}'\s*/, ""));
+    const family = typeof parsed.family === "string" && parsed.family !== "" ? parsed.family : null;
+    if (parsed.isOpenSource !== true || typeof parsed.license !== "string") return { license: "unknown", family };
+    return { license: GOOGLE_LICENSE_IDS.get(parsed.license.toLowerCase()) ?? "unknown", family };
+  } catch {
+    return { license: "unknown", family: null };
+  }
 }
 function googleQueryCandidates(family) {
   const stripped = family.replace(/\s+(Variable|VF)$/i, "");
@@ -3335,12 +3410,14 @@ async function resolveFonts(family, weights, cacheDir = DEFAULT_FONT_CACHE) {
   const failures = [];
   let css = null;
   let lastStatus = 0;
+  let servedName = family;
   try {
     for (const queryName of googleQueryCandidates(family)) {
       const cssUrl = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(queryName).replace(/%20/g, "+")}:wght@${weights.join(";")}&display=swap`;
       const res = await fetch(cssUrl, { headers: { "User-Agent": UA } });
       if (res.ok) {
         css = await res.text();
+        servedName = queryName;
         break;
       }
       lastStatus = res.status;
@@ -3354,6 +3431,7 @@ async function resolveFonts(family, weights, cacheDir = DEFAULT_FONT_CACHE) {
   } catch (err) {
     return { resolved, failures: weights.map((weight) => ({ family, weight, reason: `offline or fetch failed: ${err instanceof Error ? err.message : String(err)}` })) };
   }
+  const meta = await googleFontMetadata(servedName);
   for (const weight of weights) {
     const blocks = [...css.matchAll(/@font-face\s*{[^}]*}/g)].map((m) => m[0]);
     const block = blocks.find((b) => b.includes(`font-weight: ${weight}`) && /unicode-range:[^;]*U\+0000/.test(b));
@@ -3370,25 +3448,25 @@ async function resolveFonts(family, weights, cacheDir = DEFAULT_FONT_CACHE) {
       }
       const bytes = new Uint8Array(await fileRes.arrayBuffer());
       const sha256 = createHash("sha256").update(bytes).digest("hex");
-      const file = path9.join(cacheDir, `${family.toLowerCase().replace(/\s+/g, "-")}-${weight}.woff2`);
+      const file = path10.join(cacheDir, `${family.toLowerCase().replace(/\s+/g, "-")}-${weight}.woff2`);
       writeFileSync3(file, bytes);
-      resolved.push({ family, weight, source: url, sha256, file });
+      resolved.push({ family, weight, source: url, sha256, file, license: meta.license, ...meta.family !== null ? { servedFamily: meta.family } : {} });
     } catch (err) {
       failures.push({ family, weight, reason: `download failed: ${err instanceof Error ? err.message : String(err)}` });
     }
   }
-  const mPath = path9.join(cacheDir, "manifest.json");
-  const prior = existsSync5(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
-  const portable2 = resolved.map((m) => ({ ...m, file: path9.basename(m.file) }));
+  const mPath = path10.join(cacheDir, "manifest.json");
+  const prior = existsSync6(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
+  const portable2 = resolved.map((m) => ({ ...m, file: path10.basename(m.file) }));
   const merged = [...prior.filter((p) => !resolved.some((m) => m.family === p.family && m.weight === p.weight)), ...portable2];
   if (resolved.length > 0) writeFileSync3(mPath, `${JSON.stringify(merged, null, 2)}
 `);
   return { resolved, failures };
 }
 function addLocalFont(family, weight, filePath, cacheDir = DEFAULT_FONT_CACHE) {
-  const src = path9.resolve(filePath);
-  if (!existsSync5(src)) throw new Error(`font file not found: ${src}`);
-  const ext = path9.extname(src).toLowerCase();
+  const src = path10.resolve(filePath);
+  if (!existsSync6(src)) throw new Error(`font file not found: ${src}`);
+  const ext = path10.extname(src).toLowerCase();
   if (![".woff2", ".woff", ".ttf", ".otf"].includes(ext)) {
     throw new Error(`unsupported font file "${ext}" \u2014 use .woff2 (preferred), .woff, .ttf or .otf`);
   }
@@ -3396,20 +3474,20 @@ function addLocalFont(family, weight, filePath, cacheDir = DEFAULT_FONT_CACHE) {
   if (bytes.length === 0) throw new Error(`font file is empty: ${src}`);
   mkdirSync2(cacheDir, { recursive: true });
   const sha256 = createHash("sha256").update(bytes).digest("hex");
-  const file = path9.join(cacheDir, `${family.toLowerCase().replace(/\s+/g, "-")}-${weight}${ext}`);
+  const file = path10.join(cacheDir, `${family.toLowerCase().replace(/\s+/g, "-")}-${weight}${ext}`);
   writeFileSync3(file, bytes);
-  const face = { family, weight, source: `local:${path9.basename(src)}`, sha256, file };
-  const mPath = path9.join(cacheDir, "manifest.json");
-  const prior = existsSync5(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
-  const merged = [...prior.filter((p) => !(p.family === family && p.weight === weight)), { ...face, file: path9.basename(file) }];
+  const face = { family, weight, source: `local:${path10.basename(src)}`, sha256, file, license: "unknown" };
+  const mPath = path10.join(cacheDir, "manifest.json");
+  const prior = existsSync6(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
+  const merged = [...prior.filter((p) => !(p.family === family && p.weight === weight)), { ...face, file: path10.basename(file) }];
   writeFileSync3(mPath, `${JSON.stringify(merged, null, 2)}
 `);
   return face;
 }
 function checkFontLock(lockPath, cacheDir = DEFAULT_FONT_CACHE) {
   const lock = JSON.parse(readFileSync3(lockPath, "utf8"));
-  const mPath = path9.join(cacheDir, "manifest.json");
-  const manifest = existsSync5(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
+  const mPath = path10.join(cacheDir, "manifest.json");
+  const manifest = existsSync6(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
   return lock.map((l) => {
     const m = manifest.find((x) => x.family === l.family && x.weight === l.weight);
     if (m === void 0) return { family: l.family, weight: l.weight, status: "missing" };
@@ -3417,8 +3495,8 @@ function checkFontLock(lockPath, cacheDir = DEFAULT_FONT_CACHE) {
   });
 }
 function resolvedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
-  const mPath = path9.join(cacheDir, "manifest.json");
-  if (!existsSync5(mPath)) return [];
+  const mPath = path10.join(cacheDir, "manifest.json");
+  if (!existsSync6(mPath)) return [];
   let entries;
   try {
     entries = JSON.parse(readFileSync3(mPath, "utf8"));
@@ -3435,14 +3513,35 @@ function resolvedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
   return [...byFamily.entries()].map(([family, w]) => ({ family, weights: [...w].sort((a, b) => a - b) }));
 }
 function requiredFontsManifest(families, cacheDir = DEFAULT_FONT_CACHE) {
-  const mPath = path9.join(cacheDir, "manifest.json");
-  const manifest = existsSync5(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
+  const mPath = path10.join(cacheDir, "manifest.json");
+  const manifest = existsSync6(mPath) ? JSON.parse(readFileSync3(mPath, "utf8")) : [];
   const wanted = new Set(families.map((f) => f.toLowerCase()));
-  return manifest.filter((f) => wanted.has(f.family.toLowerCase()));
+  return manifest.filter((f) => wanted.has(f.family.toLowerCase())).map((f) => ({
+    family: f.family,
+    weight: f.weight,
+    source: f.source,
+    sha256: f.sha256,
+    file: f.file,
+    license: normalizeFontLicense(f.license),
+    ...typeof f.servedFamily === "string" && f.servedFamily !== "" ? { servedFamily: f.servedFamily } : {}
+  }));
+}
+function facesMissingLicense(cacheDir = DEFAULT_FONT_CACHE) {
+  const mPath = path10.join(cacheDir, "manifest.json");
+  if (!existsSync6(mPath)) return [];
+  let entries;
+  try {
+    entries = JSON.parse(readFileSync3(mPath, "utf8"));
+  } catch {
+    return [];
+  }
+  return entries.filter(
+    (e) => typeof e.family === "string" && typeof e.weight === "number" && typeof e.source === "string" && e.source.startsWith(GOOGLE_FONT_FILE_PREFIX) && !(typeof e.license === "string" && FONT_LICENSES.includes(e.license))
+  ).map((e) => ({ family: e.family, weight: e.weight, sha256: e.sha256 }));
 }
 function verifiedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
-  const mPath = path9.join(cacheDir, "manifest.json");
-  if (!existsSync5(mPath)) return [];
+  const mPath = path10.join(cacheDir, "manifest.json");
+  if (!existsSync6(mPath)) return [];
   let entries;
   try {
     entries = JSON.parse(readFileSync3(mPath, "utf8"));
@@ -3452,8 +3551,8 @@ function verifiedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
   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;
+    const file = path10.isAbsolute(e.file) && existsSync6(e.file) ? e.file : path10.resolve(cacheDir, path10.basename(e.file));
+    if (!existsSync6(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);
@@ -3461,67 +3560,86 @@ function verifiedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
   }
   return [...byFamily.entries()].map(([family, w]) => ({ family, weights: [...w].sort((a, b) => a - b) }));
 }
-var DEFAULT_FONT_CACHE, UA;
+var DEFAULT_FONT_CACHE, UA, FONT_LICENSES, GOOGLE_LICENSE_IDS, GOOGLE_FONT_FILE_PREFIX;
 var init_font_resolve = __esm({
   "packages/verify/src/font-resolve.ts"() {
     "use strict";
     DEFAULT_FONT_CACHE = fontCacheDir();
     UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36";
+    FONT_LICENSES = ["OFL-1.1", "Apache-2.0", "UFL-1.0", "proprietary", "unknown"];
+    GOOGLE_LICENSE_IDS = /* @__PURE__ */ new Map([
+      ["ofl", "OFL-1.1"],
+      ["apache2", "Apache-2.0"],
+      ["apache", "Apache-2.0"],
+      ["ufl", "UFL-1.0"]
+    ]);
+    GOOGLE_FONT_FILE_PREFIX = "https://fonts.gstatic.com/";
   }
 });
 
 // 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 "";
+import { existsSync as existsSync7, readFileSync as readFileSync4 } from "node:fs";
+import path11 from "node:path";
+function injectedGroups(manifestPath2) {
+  if (!existsSync7(manifestPath2)) return { groups: [], shared: false };
   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));
-  };
+  const resolveFile = (f) => path11.isAbsolute(f) && existsSync7(f) ? f : path11.resolve(path11.dirname(manifestPath2), path11.basename(f));
   const byFile = /* @__PURE__ */ new Map();
-  for (const f of manifest) {
+  for (const f of claimed) {
+    const file = resolveFile(f.file);
+    if (!existsSync7(file)) continue;
+    if (createHash2("sha256").update(readFileSync4(file)).digest("hex") !== f.sha256) continue;
     const k = `${f.family}:${f.file}`;
-    const e = byFile.get(k) ?? { family: f.family, weights: [], file: resolveFile(f.file) };
+    const e = byFile.get(k) ?? { family: f.family, weights: [], file };
     e.weights.push(f.weight);
     byFile.set(k, e);
   }
-  const files = new Set([...byFile.values()].map((e) => e.file));
-  const shared = files.size < byFile.size;
-  return [...byFile.values()].map((e) => {
-    const weight = shared || e.weights.length > 1 ? "100 700" : String(e.weights[0]);
+  const groups = [...byFile.values()];
+  return { groups, shared: new Set(groups.map((e) => e.file)).size < groups.length };
+}
+function fontFaceCss(manifestPath2 = path11.join(fontCacheDir(), "manifest.json")) {
+  const { groups, shared } = injectedGroups(manifestPath2);
+  return groups.map((e) => {
+    const weight = shared || e.weights.length > 1 ? `${SPAN[0]} ${SPAN[1]}` : String(e.weights[0]);
     return `@font-face { font-family: '${e.family}'; font-weight: ${weight}; font-style: normal; src: url(data:font/woff2;base64,${readFileSync4(e.file).toString("base64")}) format('woff2'); }`;
   }).join("\n");
 }
+function injectedFamilyWeights(manifestPath2 = path11.join(fontCacheDir(), "manifest.json")) {
+  const { groups, shared } = injectedGroups(manifestPath2);
+  const out = /* @__PURE__ */ new Map();
+  for (const g of groups) {
+    const key = g.family.toLowerCase();
+    const e = out.get(key) ?? { weights: /* @__PURE__ */ new Set(), span: false };
+    for (const w of g.weights) e.weights.add(w);
+    if (shared || g.weights.length > 1) e.span = true;
+    out.set(key, e);
+  }
+  return out;
+}
+function servesWeight(coverage, weight) {
+  return coverage.weights.has(weight) || coverage.span && weight >= SPAN[0] && weight <= SPAN[1];
+}
+var SPAN;
 var init_font_faces = __esm({
   "packages/verify/src/font-faces.ts"() {
     "use strict";
     init_font_resolve();
+    SPAN = [100, 700];
   }
 });
 
 // packages/verify/src/admission.ts
-import { readFileSync as readFileSync5, readdirSync as readdirSync2, existsSync as existsSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import path11 from "node:path";
+import { readFileSync as readFileSync5, readdirSync as readdirSync2, existsSync as existsSync8, writeFileSync as writeFileSync4 } from "node:fs";
+import path12 from "node:path";
 import { build as build2 } from "esbuild";
 import postcss from "postcss";
 import tailwindcss from "tailwindcss";
 import { chromium as chromium2 } from "playwright-core";
 function fontWeightsByFamily() {
-  const mPath = path11.join(fontCacheDir(), "manifest.json");
+  const mPath = path12.join(fontCacheDir(), "manifest.json");
   const out = /* @__PURE__ */ new Map();
-  if (!existsSync7(mPath)) return out;
+  if (!existsSync8(mPath)) return out;
   for (const f of JSON.parse(readFileSync5(mPath, "utf8")))
     out.set(f.family, [...out.get(f.family) ?? [], f.weight]);
   return out;
@@ -3542,7 +3660,7 @@ var init_admission = __esm({
 });
 
 // packages/verify/src/tasks.ts
-import path12 from "node:path";
+import path13 from "node:path";
 var CALENDAR_CONFIGS, CALENDAR_API, CALENDAR_BEHAVIORS, BUTTON_CONFIGS, BUTTON_API, COMBO_FIX, COMBO_CONFIGS, COMBO_API, MODAL_CONFIGS, MODAL_API, BUTTON_BEHAVIORS, COMBO_BEHAVIORS, MODAL_BEHAVIORS, TASKS;
 var init_tasks = __esm({
   "packages/verify/src/tasks.ts"() {
@@ -3702,7 +3820,7 @@ BEHAVIORAL CONTRACT (machine-verified, gating): the primary action and close con
     ];
     TASKS = {
       calendar: {
-        set: path12.join(REPO_ROOT, "examples/recordings/shadcn-poc-calendar"),
+        set: path13.join(REPO_ROOT, "examples/recordings/shadcn-poc-calendar"),
         entry: "Calendar.tsx",
         configs: CALENDAR_CONFIGS,
         systemApi: CALENDAR_API,
@@ -3710,7 +3828,7 @@ BEHAVIORAL CONTRACT (machine-verified, gating): the primary action and close con
         prelude: { controls: ['[data-tendril-part="day"]'], textInputs: [] }
       },
       "shadcn-button": {
-        set: path12.join(REPO_ROOT, "examples/recordings/shadcn-poc-button"),
+        set: path13.join(REPO_ROOT, "examples/recordings/shadcn-poc-button"),
         entry: "Button.tsx",
         configs: BUTTON_CONFIGS,
         systemApi: BUTTON_API,
@@ -3718,7 +3836,7 @@ BEHAVIORAL CONTRACT (machine-verified, gating): the primary action and close con
         prelude: { controls: ["> *"], textInputs: [] }
       },
       combobox: {
-        set: path12.join(REPO_ROOT, "examples/recordings/carbon-poc-combobox"),
+        set: path13.join(REPO_ROOT, "examples/recordings/carbon-poc-combobox"),
         entry: "ComboBox.tsx",
         configs: COMBO_CONFIGS,
         systemApi: COMBO_API,
@@ -3726,7 +3844,7 @@ BEHAVIORAL CONTRACT (machine-verified, gating): the primary action and close con
         prelude: { controls: ['[role="option"]'], textInputs: ["input"], popover: { selector: '[role="listbox"]', trigger: "input" } }
       },
       modal: {
-        set: path12.join(REPO_ROOT, "examples/recordings/carbon-poc-modal"),
+        set: path13.join(REPO_ROOT, "examples/recordings/carbon-poc-modal"),
         entry: "Modal.tsx",
         configs: MODAL_CONFIGS,
         systemApi: MODAL_API,
@@ -3744,8 +3862,8 @@ __export(behavior_exports, {
   compileMount: () => compileMount,
   recordingIsDark: () => recordingIsDark
 });
-import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
-import path13 from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
+import path14 from "node:path";
 import { build as build3 } from "esbuild";
 import { chromium as chromium3 } from "playwright-core";
 import { PNG as PNG2 } from "pngjs";
@@ -3754,12 +3872,12 @@ function getFontFaces() {
   return _fontFaces;
 }
 async function compileMount(task, bundleDir) {
-  const entryTsx = path13.join(bundleDir, task.entry);
-  if (!existsSync8(entryTsx)) return { error: `${task.entry} missing` };
+  const entryTsx = path14.join(bundleDir, task.entry);
+  if (!existsSync9(entryTsx)) return { error: `${task.entry} missing` };
   const mountSrc = `
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
-import * as B from ${JSON.stringify(path13.resolve(entryTsx))};
+import * as B from ${JSON.stringify(path14.resolve(entryTsx))};
 const cfg = (window as unknown as { __cfg: { component: string; props: Record<string, unknown>; spyProps?: string[] } }).__cfg;
 const C = (B as Record<string, unknown>)[cfg.component] as Parameters<typeof createElement>[0] | undefined;
 // Callbacks cannot ride the JSON config: specs NAME spy props and the
@@ -4011,8 +4129,8 @@ async function runSteps(page, spec, renderPose) {
 function recordingIsDark(task) {
   const rep = task.configs[0]?.rep;
   if (rep === void 0) return false;
-  const f = path13.join(task.set, rep, "get_screenshot.json");
-  if (!existsSync8(f)) return false;
+  const f = path14.join(task.set, rep, "get_screenshot.json");
+  if (!existsSync9(f)) return false;
   try {
     const env = JSON.parse(readFileSync6(f, "utf8")).content.find((c) => c.type === "image");
     if (env?.data === void 0) return false;
@@ -4086,7 +4204,7 @@ async function checkBehaviors(task, bundleDir, opts = {}) {
   const deadlineMs = timeoutMs + 1e4;
   const js = await compileMount(task, bundleDir);
   if (typeof js !== "string") return task.behaviors.map((b) => ({ id: b.id, pass: false, detail: js.error }));
-  const css = ["tokens.css", "styles.css"].map((f) => path13.join(bundleDir, f)).filter((f) => existsSync8(f)).map((f) => readFileSync6(f, "utf8")).join("\n");
+  const css = ["tokens.css", "styles.css"].map((f) => path14.join(bundleDir, f)).filter((f) => existsSync9(f)).map((f) => readFileSync6(f, "utf8")).join("\n");
   const server = await chromium3.launchServer({ executablePath: resolveChrome(), headless: true, args: mountArgs() });
   const browser = await chromium3.connect(server.wsEndpoint());
   const results = [];
@@ -4229,8 +4347,8 @@ var init_behavior = __esm({
 });
 
 // packages/verify/src/bundle-quality.ts
-import { readFileSync as readFileSync7, rmSync as rmSync2, writeFileSync as writeFileSync5, existsSync as existsSync9 } from "node:fs";
-import path14 from "node:path";
+import { readFileSync as readFileSync7, rmSync as rmSync2, writeFileSync as writeFileSync5, existsSync as existsSync10 } from "node:fs";
+import path15 from "node:path";
 function definedVars(tokensCss) {
   if (tokensCss === void 0) return void 0;
   const names = /* @__PURE__ */ new Set();
@@ -4239,7 +4357,7 @@ function definedVars(tokensCss) {
 }
 function recordedTokenMapEmpty(setDir, reps) {
   const readMap = (file) => {
-    if (!existsSync9(file)) return void 0;
+    if (!existsSync10(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 : {};
@@ -4247,28 +4365,93 @@ function recordedTokenMapEmpty(setDir, reps) {
       return {};
     }
   };
-  const setLevel = readMap(path14.join(setDir, "get_variable_defs.json"));
+  const setLevel = readMap(path15.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"));
+    const m = readMap(path15.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) {
+function scannable(css) {
+  const blank = (m) => m.replace(/[^\n]/g, " ");
+  return css.replace(/\/\*[^]*?\*\//g, blank).replace(/@font-face\s*{[^}]*}/g, blank);
+}
+function usedWeights(css) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of css.matchAll(/font-weight\s*:\s*([^;}]+)/g)) {
+    const v = declValue(m[1]).toLowerCase();
+    if (v === "bold") out.add(700);
+    else if (v === "normal") out.add(400);
+    else if (/^\d{1,4}$/.test(v)) out.add(Number(v));
+  }
+  return [...out].sort((a, b) => a - b);
+}
+function fontStacks(css) {
+  const out = [];
+  for (const m of css.matchAll(/font-family\s*:\s*([^;}]+)/g)) {
+    const text = declValue(m[1]);
+    const families = text.split(",").map((f) => f.trim().replace(/^['"]|['"]$/g, "")).filter((f) => f !== "");
+    if (families.length > 0) out.push({ families, line: css.slice(0, m.index).split("\n").length, text });
+  }
+  return out;
+}
+function fontStackFindings(sheets, coverage) {
+  if (coverage.size === 0) return [];
+  const scanned = sheets.map((s) => ({ file: s.file, css: scannable(s.css) }));
+  const weights = [...new Set(scanned.flatMap((s) => usedWeights(s.css)))].sort((a, b) => a - b);
+  if (weights.length === 0) return [];
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const sheet of scanned) {
+    for (const stack of fontStacks(sheet.css)) {
+      if (seen.has(stack.text)) continue;
+      seen.add(stack.text);
+      const family = stack.families[0];
+      const bound = coverage.get(family.toLowerCase());
+      if (bound === void 0) continue;
+      const unserved = weights.filter((w) => !servesWeight(bound, w));
+      if (unserved.length === 0) continue;
+      const rescue = stack.families.slice(1).find((f) => {
+        const c = coverage.get(f.toLowerCase());
+        return c !== void 0 && unserved.every((w) => servesWeight(c, w));
+      });
+      const has = bound.span ? "100\u2013700" : [...bound.weights].sort((a, b) => a - b).join(", ");
+      const list = unserved.join(", ");
+      const renders = !bound.span && bound.weights.size === 1 ? `renders in the ${[...bound.weights][0]} face` : "renders in whichever of those faces is nearest";
+      findings.push({
+        kind: "font-stack",
+        file: sheet.file,
+        line: stack.line,
+        message: `font-family ${stack.text} binds to '${family}', which the font kit provides at ${has} \u2014 CSS matches the FAMILY first and picks a weight only inside it (a later family is never consulted for a missing weight, and the prelude's font-synthesis: none rules out faux-bold), so text at weight ${list} ${renders}, silently. ` + (rescue !== void 0 ? `'${rescue}' in this same stack provides ${list}: list it first.` : `No family in this stack provides ${list} \u2014 if the recording shows ${unserved.length === 1 ? "that weight" : "those weights"}, run \`tendril fonts resolve "${family}" --weights ${unserved.join(" ")}\` and re-score.`) + " ADVISORY: quality feedback only \u2014 it never moves a score, a tier, or the verdict."
+      });
+    }
+  }
+  return findings;
+}
+async function checkBundleQuality(bundleDir, entry, set, fontManifest) {
   const findings = [];
-  const entryPath = path14.join(bundleDir, entry);
-  const cssPath = path14.join(bundleDir, "styles.css");
-  const tokensPath = path14.join(bundleDir, "tokens.css");
-  const css = existsSync9(cssPath) ? readFileSync7(cssPath, "utf8") : "";
-  const tokensCss = existsSync9(tokensPath) ? readFileSync7(tokensPath, "utf8") : void 0;
-  if (existsSync9(entryPath)) {
+  const entryPath = path15.join(bundleDir, entry);
+  const cssPath = path15.join(bundleDir, "styles.css");
+  const tokensPath = path15.join(bundleDir, "tokens.css");
+  const css = existsSync10(cssPath) ? readFileSync7(cssPath, "utf8") : "";
+  const tokensCss = existsSync10(tokensPath) ? readFileSync7(tokensPath, "utf8") : void 0;
+  findings.push(
+    ...fontStackFindings(
+      [
+        { file: "styles.css", css },
+        ...tokensCss === void 0 ? [] : [{ file: "tokens.css", css: tokensCss }]
+      ],
+      injectedFamilyWeights(fontManifest)
+    )
+  );
+  if (existsSync10(entryPath)) {
     const workDir = newScratchDir("quality");
     try {
-      const tsxPath = path14.join(workDir, entry);
+      const tsxPath = path15.join(workDir, entry);
       writeFileSync5(tsxPath, readFileSync7(entryPath, "utf8"));
       for (const d of runTscStrict([tsxPath]).diagnostics) {
         findings.push({ kind: "tsc", file: entry, ...d.line === void 0 ? {} : { line: d.line }, message: `TS${d.code}: ${d.message}` });
@@ -4285,13 +4468,16 @@ async function checkBundleQuality(bundleDir, entry, set) {
   }
   return { findings, tokensAbsent: tokensCss === void 0 && !/var\(\s*--/.test(css) };
 }
+var declValue;
 var init_bundle_quality = __esm({
   "packages/verify/src/bundle-quality.ts"() {
     "use strict";
     init_src();
+    init_font_faces();
     init_runtime();
     init_tsc_check();
     init_token_lint();
+    declValue = (raw) => raw.trim().replace(/\s*!important$/i, "").trim();
   }
 });
 
@@ -4334,8 +4520,8 @@ var init_effect_geometry = __esm({
 });
 
 // packages/verify/src/bundle-score.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
-import path15 from "node:path";
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
+import path16 from "node:path";
 import { build as build4 } from "esbuild";
 import { chromium as chromium4 } from "playwright-core";
 function getFontFaces2() {
@@ -4389,7 +4575,7 @@ function chooseSeat(cropAt, ref, padW, padH, backdrop, origin, extents) {
 }
 function metadataRoot(set, rep) {
   try {
-    const text = JSON.parse(readFileSync8(path15.join(set, rep, "get_metadata.json"), "utf8")).content.map((c) => c.text ?? "").join("\n");
+    const text = JSON.parse(readFileSync8(path16.join(set, rep, "get_metadata.json"), "utf8")).content.map((c) => c.text ?? "").join("\n");
     return parseMetadataStructure(text);
   } catch {
     return void 0;
@@ -4444,17 +4630,17 @@ function smallSemanticNodes(set, rep, maxArea = 1024) {
   });
 }
 function repMeta(set, rep) {
-  const text = JSON.parse(readFileSync8(path15.join(set, rep, "get_metadata.json"), "utf8")).content.map((c) => c.text ?? "").join("\n");
+  const text = JSON.parse(readFileSync8(path16.join(set, rep, "get_metadata.json"), "utf8")).content.map((c) => c.text ?? "").join("\n");
   const root = parseMetadataStructure(text);
   return { w: Math.round(root.width ?? 100), h: Math.round(root.height ?? 40) };
 }
 function repRef(set, rep) {
-  const env = JSON.parse(readFileSync8(path15.join(set, rep, "get_screenshot.json"), "utf8")).content.find((c) => c.type === "image");
+  const env = JSON.parse(readFileSync8(path16.join(set, rep, "get_screenshot.json"), "utf8")).content.find((c) => c.type === "image");
   return Uint8Array.from(Buffer.from(env?.data ?? "", "base64"));
 }
 function repEffectExtents(set, rep) {
-  const file = path15.join(set, rep, "get_design_context.json");
-  if (!existsSync10(file)) return void 0;
+  const file = path16.join(set, rep, "get_design_context.json");
+  if (!existsSync11(file)) return void 0;
   try {
     const text = JSON.parse(readFileSync8(file, "utf8")).content.map((c) => c.text ?? "").join("\n");
     const extents = shadowExtents(text);
@@ -4467,13 +4653,13 @@ async function scoreBundleForTask(task, bundleDir, bar = BAR, opts = {}) {
   if (opts.evidenceDir !== void 0) mkdirSync3(opts.evidenceDir, { recursive: true });
   const CONFIGS2 = task.configs;
   const timeoutMs = opts.mountDeadlineMs ?? ENGINE_MOUNT_DEADLINE_MS;
-  const entryTsx = path15.join(bundleDir, task.entry);
-  if (!existsSync10(entryTsx)) return CONFIGS2.map((c) => ({ rep: c.rep, similarity: 0, inkRecall: 0, exact: { similarity: 0, inkRecall: 0 }, pass: false, error: `${task.entry} missing` }));
-  const css = ["tokens.css", "styles.css"].map((f) => path15.join(bundleDir, f)).filter((f) => existsSync10(f)).map((f) => readFileSync8(f, "utf8")).join("\n");
+  const entryTsx = path16.join(bundleDir, task.entry);
+  if (!existsSync11(entryTsx)) return CONFIGS2.map((c) => ({ rep: c.rep, similarity: 0, inkRecall: 0, exact: { similarity: 0, inkRecall: 0 }, pass: false, error: `${task.entry} missing` }));
+  const css = ["tokens.css", "styles.css"].map((f) => path16.join(bundleDir, f)).filter((f) => existsSync11(f)).map((f) => readFileSync8(f, "utf8")).join("\n");
   const mountSrc = `
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
-import * as B from ${JSON.stringify(path15.resolve(entryTsx))};
+import * as B from ${JSON.stringify(path16.resolve(entryTsx))};
 const cfg = (window as unknown as { __cfg: { component: string; props: Record<string, unknown> } }).__cfg;
 const C = (B as Record<string, unknown>)[cfg.component] as Parameters<typeof createElement>[0] | undefined;
 const root = document.getElementById("root");
@@ -4568,12 +4754,12 @@ body{margin:0;background:rgb(${backdrop.join(",")})}
             return name === void 0 ? c : { ...c, name };
           });
           if (opts.evidenceDir !== void 0) {
-            writeFileSync6(path15.join(opts.evidenceDir, `${cfg.rep}-render.png`), scored);
-            writeFileSync6(path15.join(opts.evidenceDir, `${cfg.rep}-ref.png`), ref);
-            writeFileSync6(path15.join(opts.evidenceDir, `${cfg.rep}-diff.png`), diffPng(scored, ref));
+            writeFileSync6(path16.join(opts.evidenceDir, `${cfg.rep}-render.png`), scored);
+            writeFileSync6(path16.join(opts.evidenceDir, `${cfg.rep}-ref.png`), ref);
+            writeFileSync6(path16.join(opts.evidenceDir, `${cfg.rep}-diff.png`), diffPng(scored, ref));
             for (const [i, c] of absent.slice(0, 3).entries()) {
-              writeFileSync6(path15.join(opts.evidenceDir, `${cfg.rep}-absent-${i}-ref.png`), zoomCrop(ref, c));
-              writeFileSync6(path15.join(opts.evidenceDir, `${cfg.rep}-absent-${i}-render.png`), zoomCrop(scored, c));
+              writeFileSync6(path16.join(opts.evidenceDir, `${cfg.rep}-absent-${i}-ref.png`), zoomCrop(ref, c));
+              writeFileSync6(path16.join(opts.evidenceDir, `${cfg.rep}-absent-${i}-render.png`), zoomCrop(scored, c));
             }
           }
           return {
@@ -4672,7 +4858,7 @@ var init_prelude = __esm({
     "use strict";
     PRELUDE_CONTRACT = `BUNDLE PRELUDE (machine-verified on computed styles \u2014 the harness page provides NONE of this; your CSS must):
 - Containment reset on the component subtree: margin 0, box-sizing border-box, line-height/letter-spacing/font-family inherited from the root (host globals must not leak in).
-- Component root: -webkit-font-smoothing: antialiased and -moz-osx-font-smoothing: grayscale (recorded rasterization); font-synthesis: none (a missing font weight must fall back visibly, never fake-bold); color-scheme MATCHING YOUR RECORDING (light for a light capture, dark for a dark one) and direction: ltr \u2014 pin them, so the render cannot follow the viewer OS preference and drift from the capture it is graded against; isolation: isolate (own stacking context; overlay z-indexes never fight the host).
+- Component root: -webkit-font-smoothing: antialiased and -moz-osx-font-smoothing: grayscale (recorded rasterization); font-synthesis: none (no faux bold or italic \u2014 text renders in the face your stack actually binds, so a weight the kit cannot serve reaches the score instead of being faked; it does NOT fall through to the next family in the stack); color-scheme MATCHING YOUR RECORDING (light for a light capture, dark for a dark one) and direction: ltr \u2014 pin them, so the render cannot follow the viewer OS preference and drift from the capture it is graded against; isolation: isolate (own stacking context; overlay z-indexes never fight the host).
 - Interactive controls (buttons, options): touch-action: manipulation and user-select: none. Text inputs stay selectable (never user-select: none on them).
 - Scrollable popovers/menus: overscroll-behavior: contain.
 - Focus indicators bind to :focus-visible, never bare :focus. If the recording contains a focus pose, style the indicator from that recorded truth. If NO focus pose is recorded, do NOT invent ring colors/widths/offsets \u2014 an invented ring is unrecorded pixels; keep the browser's default indicator for keyboard focus and state the gap in your report. Text inputs match :focus-visible even on mouse click BY SPEC; the ONE permitted refinement is suppressing the indicator on a POSITIVELY OBSERVED pointer press, fail-safe toward showing it (programmatic focus, restored focus, and assistive tech all count as keyboard and keep the ring \u2014 WCAG 2.4.7 binds keyboard operation). Never suppress more broadly than an observed press, and never restyle what you kept.
@@ -4681,8 +4867,8 @@ var init_prelude = __esm({
 });
 
 // packages/verify/src/parity.ts
-import { existsSync as existsSync11, readFileSync as readFileSync9 } from "node:fs";
-import path16 from "node:path";
+import { existsSync as existsSync12, readFileSync as readFileSync9 } from "node:fs";
+import path17 from "node:path";
 import { chromium as chromium6 } from "playwright-core";
 function getFontFaces3() {
   _fontFaces3 ??= fontFaceCss();
@@ -4711,7 +4897,7 @@ async function checkHoverParity(task, bundleDir, opts = {}) {
   const deadlineMs = timeoutMs + 1e4;
   const js = await compileMount(task, bundleDir);
   if (typeof js !== "string") return configs.map((c) => ({ id: `parity:${c.rep}`, pass: false, detail: js.error }));
-  const css = ["tokens.css", "styles.css"].map((f) => path16.join(bundleDir, f)).filter((f) => existsSync11(f)).map((f) => readFileSync9(f, "utf8")).join("\n");
+  const css = ["tokens.css", "styles.css"].map((f) => path17.join(bundleDir, f)).filter((f) => existsSync12(f)).map((f) => readFileSync9(f, "utf8")).join("\n");
   const server = await chromium6.launchServer({ executablePath: resolveChrome(), headless: true, args: mountArgs() });
   const browser = await chromium6.connect(server.wsEndpoint());
   const results = [];
@@ -4791,8 +4977,8 @@ var init_parity = __esm({
 
 // packages/verify/src/composition.ts
 import { createRequire as createRequire2 } from "node:module";
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
-import path17 from "node:path";
+import { existsSync as existsSync13, readFileSync as readFileSync10 } from "node:fs";
+import path18 from "node:path";
 import { build as build6 } from "esbuild";
 import { chromium as chromium7 } from "playwright-core";
 function getFontFaces4() {
@@ -4800,9 +4986,9 @@ function getFontFaces4() {
   return _fontFaces4;
 }
 async function compileInstrumentedMount(task, bundleDir) {
-  const entryTsx = path17.join(bundleDir, task.entry);
-  if (!existsSync12(entryTsx)) return { error: `${task.entry} missing` };
-  const requireFromVerify = createRequire2(path17.join(VERIFY_PKG_DIR, "package.json"));
+  const entryTsx = path18.join(bundleDir, task.entry);
+  if (!existsSync13(entryTsx)) return { error: `${task.entry} missing` };
+  const requireFromVerify = createRequire2(path18.join(VERIFY_PKG_DIR, "package.json"));
   let realJsxPath;
   try {
     realJsxPath = requireFromVerify.resolve("react/jsx-runtime");
@@ -4813,7 +4999,7 @@ async function compileInstrumentedMount(task, bundleDir) {
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
 import { __registerParts } from "react/jsx-runtime";
-import * as B from ${JSON.stringify(path17.resolve(entryTsx))};
+import * as B from ${JSON.stringify(path18.resolve(entryTsx))};
 const cfg = (window as unknown as { __cfg: { component: string; props: Record<string, unknown>; partComponents: string[] } }).__cfg;
 const pairs: Array<[unknown, string]> = [];
 for (const name of cfg.partComponents) {
@@ -4868,7 +5054,7 @@ function expectedParts(task, roles, mainSlug) {
 }
 function interiorRegions(setDir, roles) {
   const mains = roles.main;
-  const withInterior = mains.filter((m) => existsSync12(path17.join(setDir, m, "get_metadata_interior.json")));
+  const withInterior = mains.filter((m) => existsSync13(path18.join(setDir, m, "get_metadata_interior.json")));
   if (withInterior.length === 0) {
     return { unavailable: "no interior geometry recorded for any main (pre-obligation set) \u2014 re-record with `tendril record` to enable crop checks" };
   }
@@ -4885,7 +5071,7 @@ async function checkCropComposition(task, bundleDir, regions, opts = {}) {
   if (typeof js !== "string") {
     return regions.map((r) => ({ id: cropId(r), pass: false, similarity: 0, inkRecall: 0, detail: js.error }));
   }
-  const css = ["tokens.css", "styles.css"].map((f) => path17.join(bundleDir, f)).filter((f) => existsSync12(f)).map((f) => readFileSync10(f, "utf8")).join("\n");
+  const css = ["tokens.css", "styles.css"].map((f) => path18.join(bundleDir, f)).filter((f) => existsSync13(f)).map((f) => readFileSync10(f, "utf8")).join("\n");
   const server = await chromium7.launchServer({ executablePath: resolveChrome(), headless: true, args: mountArgs() });
   const browser = await chromium7.connect(server.wsEndpoint());
   const PAD = 4;
@@ -4990,7 +5176,7 @@ async function checkStructuralComposition(task, bundleDir, roles, opts = {}) {
   const deadlineMs = timeoutMs + 1e4;
   const js = await compileInstrumentedMount(task, bundleDir);
   if (typeof js !== "string") return [...results, ...mains.map((m) => ({ id: `composition:${m}`, pass: false, detail: js.error }))];
-  const css = ["tokens.css", "styles.css"].map((f) => path17.join(bundleDir, f)).filter((f) => existsSync12(f)).map((f) => readFileSync10(f, "utf8")).join("\n");
+  const css = ["tokens.css", "styles.css"].map((f) => path18.join(bundleDir, f)).filter((f) => existsSync13(f)).map((f) => readFileSync10(f, "utf8")).join("\n");
   const server = await chromium7.launchServer({ executablePath: resolveChrome(), headless: true, args: mountArgs() });
   const browser = await chromium7.connect(server.wsEndpoint());
   try {
@@ -5080,17 +5266,17 @@ export const jsxs = (t, p, k) => real.jsxs(t, inject(t, p), k);
 });
 
 // packages/verify/src/occlusion.ts
-import { existsSync as existsSync13 } from "node:fs";
-import path18 from "node:path";
+import { existsSync as existsSync14 } from "node:fs";
+import path19 from "node:path";
 import { build as build7 } from "esbuild";
 import { chromium as chromium8 } from "playwright-core";
 async function compileTwoUp(task, bundleDir) {
-  const entryTsx = path18.join(bundleDir, task.entry);
-  if (!existsSync13(entryTsx)) return { error: `${task.entry} missing` };
+  const entryTsx = path19.join(bundleDir, task.entry);
+  if (!existsSync14(entryTsx)) return { error: `${task.entry} missing` };
   const src = `
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
-import * as B from ${JSON.stringify(path18.resolve(entryTsx))};
+import * as B from ${JSON.stringify(path19.resolve(entryTsx))};
 const cfg = (window as unknown as { __cfg: { component: string; props: Record<string, unknown> } }).__cfg;
 const C = (B as Record<string, unknown>)[cfg.component] as Parameters<typeof createElement>[0] | undefined;
 for (const id of ["first", "second"]) {
@@ -5268,21 +5454,21 @@ 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 { existsSync as existsSync15, readFileSync as readFileSync11 } from "node:fs";
+import path20 from "node:path";
 import { createHash as createHash3 } from "node:crypto";
-import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
 function cliVersion() {
   try {
-    return JSON.parse(readFileSync11(path19.join(path19.dirname(fileURLToPath4(import.meta.url)), "..", "package.json"), "utf8")).version ?? "dev";
+    return JSON.parse(readFileSync11(path20.join(path20.dirname(fileURLToPath5(import.meta.url)), "..", "package.json"), "utf8")).version ?? "dev";
   } catch {
     return "dev";
   }
 }
 function environmentStamp(taskFamilies) {
-  const manifestPath2 = path19.join(fontCacheDir(), "manifest.json");
+  const manifestPath2 = path20.join(fontCacheDir(), "manifest.json");
   let fontsHash = null;
-  if (existsSync14(manifestPath2)) {
+  if (existsSync15(manifestPath2)) {
     try {
       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()));
@@ -5298,8 +5484,8 @@ function environmentStamp(taskFamilies) {
   } catch {
   }
   const ver = chrome === "unavailable" ? null : chromeVersion();
-  const lcdOff = lcdTextDisabled() ? " (lcd-text-disabled)" : "";
-  return { chrome, chromeVersion: ver === null ? null : ver + lcdOff, fontsManifestSha256: fontsHash };
+  const lcdSuffix = lcdTextEnabled() ? " (lcd-text-enabled)" : "";
+  return { chrome, chromeVersion: ver === null ? null : ver + lcdSuffix, fontsManifestSha256: fontsHash };
 }
 var init_environment = __esm({
   "packages/cli/src/environment.ts"() {
@@ -5328,8 +5514,8 @@ var init_describe = __esm({
 });
 
 // packages/cli/src/env.ts
-import { existsSync as existsSync15, readFileSync as readFileSync12 } from "node:fs";
-import path20 from "node:path";
+import { existsSync as existsSync16, readFileSync as readFileSync12 } from "node:fs";
+import path21 from "node:path";
 function parseEnv(content) {
   const entries = /* @__PURE__ */ new Map();
   for (const line of content.split("\n")) {
@@ -5341,8 +5527,8 @@ function parseEnv(content) {
 function resolveCredential(name) {
   const fromProcess = process.env[name];
   if (fromProcess) return fromProcess;
-  const envPath = path20.resolve(process.env["INIT_CWD"] ?? process.cwd(), ".env");
-  if (!existsSync15(envPath)) return void 0;
+  const envPath = path21.resolve(process.env["INIT_CWD"] ?? process.cwd(), ".env");
+  if (!existsSync16(envPath)) return void 0;
   return parseEnv(readFileSync12(envPath, "utf8")).get(name);
 }
 var init_env = __esm({
@@ -5403,15 +5589,15 @@ var init_output = __esm({
 });
 
 // packages/cli/src/entitlement.ts
-import { chmodSync, existsSync as existsSync16, mkdirSync as mkdirSync4, readFileSync as readFileSync13, writeFileSync as writeFileSync7 } from "node:fs";
+import { chmodSync, existsSync as existsSync17, mkdirSync as mkdirSync4, readFileSync as readFileSync13, writeFileSync as writeFileSync7 } from "node:fs";
 import crypto from "node:crypto";
 import os3 from "node:os";
-import path21 from "node:path";
+import path22 from "node:path";
 function entitlementPath() {
-  return process.env["TENDRIL_ENTITLEMENT_PATH"] ?? path21.join(os3.homedir(), ".tendril", "entitlement.json");
+  return process.env["TENDRIL_ENTITLEMENT_PATH"] ?? path22.join(os3.homedir(), ".tendril", "entitlement.json");
 }
 function readStoredEntitlement(file = entitlementPath()) {
-  if (!existsSync16(file)) return void 0;
+  if (!existsSync17(file)) return void 0;
   try {
     const parsed = JSON.parse(readFileSync13(file, "utf8"));
     if (typeof parsed.token !== "string" || typeof parsed.lastRefreshAt !== "number") return void 0;
@@ -5421,7 +5607,7 @@ function readStoredEntitlement(file = entitlementPath()) {
   }
 }
 function writeStoredEntitlement(stored, file = entitlementPath()) {
-  mkdirSync4(path21.dirname(file), { recursive: true });
+  mkdirSync4(path22.dirname(file), { recursive: true });
   writeFileSync7(file, `${JSON.stringify(stored, null, 2)}
 `);
   chmodSync(file, 384);
@@ -5447,11 +5633,11 @@ function checkEntitlement(opts = {}) {
   const now = opts.now ?? Date.now();
   const stored = "stored" in opts ? opts.stored : readStoredEntitlement();
   if (stored === void 0) {
-    return { ok: false, code: "entitlement-required", error: "no entitlement on this machine \u2014 record and generate need an active Tendril plan (verify stays free, always)", remediation: ACTIVATE_REMEDIATION };
+    return { ok: false, code: "entitlement-required", error: "no entitlement on this machine \u2014 record and generate need an active Tendril plan (verify stays free, always)", remediation: activateRemediation() };
   }
   const parsed = parseEntitlementToken(stored.token);
   if ("error" in parsed) {
-    return { ok: false, code: "entitlement-invalid", error: `stored entitlement is unreadable: ${parsed.error}`, remediation: ACTIVATE_REMEDIATION };
+    return { ok: false, code: "entitlement-invalid", error: `stored entitlement is unreadable: ${parsed.error}`, remediation: activateRemediation() };
   }
   const pem = keys[parsed.claims.kid];
   const valid = pem !== void 0 && (() => {
@@ -5462,14 +5648,14 @@ function checkEntitlement(opts = {}) {
     }
   })();
   if (!valid) {
-    return { ok: false, code: "entitlement-invalid", error: "stored entitlement failed signature verification", remediation: ACTIVATE_REMEDIATION };
+    return { ok: false, code: "entitlement-invalid", error: "stored entitlement failed signature verification", remediation: activateRemediation() };
   }
   if (now > parsed.claims.exp + TOLERANCE_MS) {
     return {
       ok: false,
       code: "entitlement-expired",
       error: "entitlement expired (and the offline tolerance window has passed)",
-      remediation: `Reconnect and ${ACTIVATE_REMEDIATION}`
+      remediation: `Reconnect and ${activateRemediation()}`
     };
   }
   if (now < stored.lastRefreshAt - CLOCK_ROLLBACK_MS) {
@@ -5477,7 +5663,7 @@ function checkEntitlement(opts = {}) {
       ok: false,
       code: "entitlement-clock",
       error: "system clock sits more than a day before the last entitlement refresh",
-      remediation: `Fix the system clock, then ${ACTIVATE_REMEDIATION}`
+      remediation: `Fix the system clock, then ${activateRemediation()}`
     };
   }
   return { ok: true, mode: "active", claims: parsed.claims, stale: now > parsed.claims.exp };
@@ -5488,26 +5674,27 @@ function requireEntitlement(flags) {
     fail(flags, ExitCode.Auth, { error: status.error, code: status.code, remediation: status.remediation });
   }
 }
-var ENT_PREFIX, PUBLIC_KEYS, TOLERANCE_MS, CLOCK_ROLLBACK_MS, b64urlDecode, ACTIVATE_REMEDIATION;
+var ENT_PREFIX, PUBLIC_KEYS, TOLERANCE_MS, CLOCK_ROLLBACK_MS, b64urlDecode, activateRemediation;
 var init_entitlement = __esm({
   "packages/cli/src/entitlement.ts"() {
     "use strict";
     init_src3();
+    init_invocation();
     init_output();
     ENT_PREFIX = "tendril-ent.v1.";
     PUBLIC_KEYS = {};
     TOLERANCE_MS = 24 * 60 * 60 * 1e3;
     CLOCK_ROLLBACK_MS = 24 * 60 * 60 * 1e3;
     b64urlDecode = (s) => Buffer.from(s, "base64url");
-    ACTIVATE_REMEDIATION = "Run `tendril activate` in your terminal (a browser approval \u2014 never paste license material into an agent chat).";
+    activateRemediation = () => `Run \`${tendrilCommand("activate")}\` in your terminal (a browser approval \u2014 never paste license material into an agent chat).`;
   }
 });
 
 // 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 { existsSync as existsSync18, readFileSync as readFileSync14, readdirSync as readdirSync3 } from "node:fs";
 import os4 from "node:os";
-import path22 from "node:path";
+import path23 from "node:path";
 async function runDoctorChecks(options) {
   const checks = [];
   const mcpUrl = options.mcpUrl ?? DEFAULT_MCP_URL;
@@ -5537,12 +5724,12 @@ async function runDoctorChecks(options) {
       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."
+      remediation: `Run \`${tendrilCommand("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"}${lcdTextDisabled() ? " \u2014 EXPERIMENT override active (lcd-text-disabled): scores not comparable to default runs" : ""} at ${chrome}` });
+    checks.push({ name: "browser", ok: true, detail: `${chromeVersion() ?? "version unknown"}${lcdTextEnabled() ? " \u2014 EXPERIMENT override active (lcd-text-enabled): scores not comparable to canonical greyscale runs" : ""} at ${chrome}` });
   } catch (err) {
     checks.push({
       name: "browser",
@@ -5551,17 +5738,17 @@ async function runDoctorChecks(options) {
       remediation: "Install Google Chrome (or Chromium), or set CHROME_PATH to a Chromium-family browser binary."
     });
   }
-  const fontManifest = path22.join(fontCacheDir(), "manifest.json");
+  const fontManifest = path23.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)` } : {
+    existsSync18(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."
+      remediation: `Nothing to do now: \`${tendrilCommand("fonts resolve --set <recording-dir>")}\` fetches exactly what a recording declares, and generate/verify name that command \u2014 with the set filled in \u2014 when they need it.`
     }
   );
-  const pluginRoot = path22.join(os4.homedir(), ".claude", "plugins", "cache", "tendrilapp", "tendril");
-  if (existsSync17(pluginRoot)) {
+  const pluginRoot = path23.join(os4.homedir(), ".claude", "plugins", "cache", "tendrilapp", "tendril");
+  if (existsSync18(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];
@@ -5605,17 +5792,6 @@ async function runDoctorChecks(options) {
   });
   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" });
@@ -5687,6 +5863,7 @@ var init_doctor = __esm({
     init_describe();
     init_env();
     init_environment();
+    init_invocation();
     init_output();
     init_entitlement();
     DEFAULT_MCP_URL = "http://127.0.0.1:3845/mcp";
@@ -6676,7 +6853,64 @@ var init_extract = __esm({
 
 // packages/metadata/src/recording-set.ts
 import { z as z9 } from "zod";
-var RECORDING_SET_VERSION, EnvelopeSchema, RepEntrySchema, RolesSchema, RecordingSetManifestSchema;
+function roleLossToken(loss) {
+  return loss.kind === "main" ? `main:${loss.main}` : `part:${loss.part}${EDGE_ARROW}${loss.main}`;
+}
+function parseRoleLossToken(token) {
+  if (token.startsWith("main:")) {
+    const main2 = token.slice("main:".length);
+    return main2 === "" ? void 0 : { kind: "main", main: main2 };
+  }
+  if (!token.startsWith("part:")) return void 0;
+  const [part, main, ...rest] = token.slice("part:".length).split(EDGE_ARROW);
+  if (rest.length > 0 || part === void 0 || part === "" || main === void 0 || main === "") return void 0;
+  return { kind: "edge", part, main };
+}
+function validateRecordingSet(manifest, fileExists) {
+  const issues = [];
+  const parsed = RecordingSetManifestSchema.safeParse(manifest);
+  if (!parsed.success) {
+    return {
+      issues: [
+        {
+          severity: "error",
+          message: `manifest does not match recording-set layout v${RECORDING_SET_VERSION}: ${parsed.error.issues.slice(0, 3).map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+        }
+      ]
+    };
+  }
+  const m = parsed.data;
+  const slugs = /* @__PURE__ */ new Set();
+  for (const rep of m.reps) {
+    if (slugs.has(rep.slug)) issues.push({ severity: "error", message: `duplicate rep slug "${rep.slug}"` });
+    slugs.add(rep.slug);
+    for (const f of REQUIRED_REP_FILES) {
+      if (!fileExists(`${rep.slug}/${f}`)) issues.push({ severity: "error", message: `${rep.slug}: missing ${f}` });
+    }
+    if (rep.sourceFrame !== void 0 && m.sourceFrames?.[rep.sourceFrame] === void 0)
+      issues.push({ severity: "warning", message: `${rep.slug}: sourceFrame ${rep.sourceFrame} not described in sourceFrames` });
+  }
+  if (m.roles !== void 0) {
+    for (const slug of m.roles.main)
+      if (!slugs.has(slug)) issues.push({ severity: "error", message: `roles.main references unknown slug "${slug}"` });
+    for (const [slug, part] of Object.entries(m.roles.parts)) {
+      if (!slugs.has(slug)) issues.push({ severity: "error", message: `roles.parts references unknown slug "${slug}"` });
+      for (const of of part.partOf)
+        if (!m.roles.main.includes(of)) issues.push({ severity: "error", message: `roles.parts["${slug}"].partOf references non-main "${of}"` });
+    }
+    for (const token of m.roles.narrowingAccepted ?? []) {
+      const loss = parseRoleLossToken(token);
+      if (loss === void 0) {
+        issues.push({ severity: "error", message: `roles.narrowingAccepted entry "${token}" is not "main:<slug>" or "part:<part-slug>-><main-slug>"` });
+        continue;
+      }
+      for (const slug of loss.kind === "main" ? [loss.main] : [loss.part, loss.main])
+        if (!slugs.has(slug)) issues.push({ severity: "error", message: `roles.narrowingAccepted "${token}" references unknown slug "${slug}"` });
+    }
+  }
+  return { manifest: m, issues };
+}
+var RECORDING_SET_VERSION, EnvelopeSchema, RepEntrySchema, RolesSchema, EDGE_ARROW, RecordingSetManifestSchema, REQUIRED_REP_FILES;
 var init_recording_set = __esm({
   "packages/metadata/src/recording-set.ts"() {
     "use strict";
@@ -6709,10 +6943,21 @@ var init_recording_set = __esm({
        * derivation — disclosed, never silently dropped (Calendar's Icon
        * Buttons; unrecorded base variants). */
       external: z9.array(z9.string()).optional(),
-      /** True when a human override changed derived roles (surfaced in
-       * provenance downstream). */
-      humanOverride: z9.boolean().optional()
+      /** Where this graph came from. A graph with empty `parts` makes the
+       * structural composition check return an affirmative PASS, so a
+       * human-authored override and a derived graph must never be
+       * indistinguishable in a report. The CLI stamps this itself — a
+       * supplied roles file cannot claim "derived" for itself. */
+      rolesSource: z9.enum(["derived", "human-override"]).optional(),
+      /** Losses in the DERIVED relation a human override deliberately
+       * accepts, one token per loss (`roleLossToken`). Named one by one on
+       * purpose: emptying out what composition measures — by dropping a
+       * main, or by dropping/re-pointing a part→main edge — is exactly what
+       * turns composition into a vacuous pass, so it is an acceptance
+       * someone signs rather than an omission nobody notices. */
+      narrowingAccepted: z9.array(z9.string()).optional()
     });
+    EDGE_ARROW = "->";
     RecordingSetManifestSchema = z9.object({
       version: z9.literal(RECORDING_SET_VERSION),
       /** Human-readable component/system name. */
@@ -6724,6 +6969,7 @@ var init_recording_set = __esm({
       notRecorded: z9.string().optional(),
       roles: RolesSchema.optional()
     });
+    REQUIRED_REP_FILES = ["get_design_context.json", "get_metadata.json", "get_screenshot.json"];
   }
 });
 
@@ -6930,7 +7176,7 @@ async function runActivate(flags) {
     fail(flags, ExitCode.Auth, {
       error: `could not start activation: ${err instanceof Error ? err.message : String(err)}`,
       code: "entitlement-service-unreachable",
-      remediation: "Check your connection and retry `tendril activate`."
+      remediation: `Check your connection and retry \`${tendrilCommand("activate")}\`.`
     });
   }
   process.stderr.write(`To activate Tendril, visit:
@@ -6957,7 +7203,7 @@ Waiting for approval\u2026
       fail(flags, ExitCode.Auth, {
         error: `activation was not approved (HTTP ${res.status})`,
         code: "entitlement-denied",
-        remediation: "Retry `tendril activate`; if it persists, check the account's plan in the portal."
+        remediation: `Retry \`${tendrilCommand("activate")}\`; if it persists, check the account's plan in the portal.`
       });
     }
     token = (await res.json()).token;
@@ -6967,7 +7213,7 @@ Waiting for approval\u2026
     fail(flags, ExitCode.Auth, {
       error: "activation timed out before the browser approval arrived",
       code: "entitlement-timeout",
-      remediation: "Run `tendril activate` again and complete the browser step within the shown window."
+      remediation: `Run \`${tendrilCommand("activate")}\` again and complete the browser step within the shown window.`
     });
   }
   const parsed = parseEntitlementToken(token);
@@ -6975,7 +7221,7 @@ Waiting for approval\u2026
     fail(flags, ExitCode.Auth, {
       error: `service returned an unusable token: ${parsed.error}`,
       code: "entitlement-invalid",
-      remediation: "Retry `tendril activate`; report this if it persists \u2014 it is a service-side fault."
+      remediation: `Retry \`${tendrilCommand("activate")}\`; report this if it persists \u2014 it is a service-side fault.`
     });
   }
   if (Object.keys(PUBLIC_KEYS).length > 0) {
@@ -6994,6 +7240,7 @@ var init_activate = __esm({
     "use strict";
     init_src3();
     init_entitlement();
+    init_invocation();
     init_output();
     ENTITLEMENT_SERVICE_URL = void 0;
   }
@@ -7005,6 +7252,7 @@ __export(record_exports, {
   instanceLeads: () => instanceLeads,
   isFigmaAssetUrl: () => isFigmaAssetUrl,
   isLocalAssetUrl: () => isLocalAssetUrl,
+  narrowedRoles: () => narrowedRoles,
   nextPayload: () => nextPayload,
   runRecordAsset: () => runRecordAsset,
   runRecordFetch: () => runRecordFetch,
@@ -7015,9 +7263,9 @@ __export(record_exports, {
   runRecordPlan: () => runRecordPlan,
   runRecordStatus: () => runRecordStatus
 });
-import { existsSync as existsSync19, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readdirSync as readdirSync5 } from "node:fs";
+import { existsSync as existsSync20, mkdtempSync as mkdtempSync2, readFileSync as readFileSync16, readdirSync as readdirSync5 } from "node:fs";
 import os5 from "node:os";
-import path25 from "node:path";
+import path26 from "node:path";
 import { writeFileSync as writeFileSync9 } from "node:fs";
 function symbolsFromMetadataEnvelope(file, sourceFrame) {
   const env = JSON.parse(readFileSync16(file, "utf8"));
@@ -7078,7 +7326,7 @@ function runRecordPlan(opts) {
   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");
+      const tmp = path26.join(mkdtempSync2(path26.join(os5.tmpdir(), "tendril-plan-meta-")), "get_metadata.json");
       writeFileSync9(tmp, JSON.stringify(envelope));
       metadataEntries.push({ file: tmp });
     } catch (err) {
@@ -7100,7 +7348,7 @@ function runRecordPlan(opts) {
   let metadataTruncated = false;
   for (const { file, frame } of metadataEntries) {
     try {
-      const parsed = symbolsFromMetadataEnvelope(path25.resolve(file), frame);
+      const parsed = symbolsFromMetadataEnvelope(path26.resolve(file), frame);
       symbols.push(...parsed.symbols);
       if (parsed.truncated) metadataTruncated = true;
     } catch (err) {
@@ -7133,7 +7381,7 @@ function runRecordPlan(opts) {
   if (symbols.length === 0) {
     const leads = metadataEntries.flatMap(({ file }) => {
       try {
-        const env = JSON.parse(readFileSync16(path25.resolve(file), "utf8"));
+        const env = JSON.parse(readFileSync16(path26.resolve(file), "utf8"));
         return instanceLeads(env.content.map((c) => c.text ?? "").join("\n"));
       } catch {
         return [];
@@ -7238,7 +7486,7 @@ function nextPayload(setDir) {
   const instruction = nextInstruction(setDir);
   const status = sessionStatus(setDir);
   const progress = { recordedReps: status.reps.filter((x) => x.missing.length === 0).length, totalReps: status.reps.length };
-  if (instruction === null && !existsSync19(path25.join(setDir, "get_variable_defs.json"))) {
+  if (instruction === null && !existsSync20(path26.join(setDir, "get_variable_defs.json"))) {
     const manifest = loadManifest(setDir);
     const frameNode = Object.keys(manifest.sourceFrames ?? {})[0] ?? manifest.reps[0]?.nodeId ?? "";
     return { slug: "__set__", nodeId: frameNode, tool: "get_variable_defs", note: `SET-LEVEL: call get_variable_defs on the component frame and ingest with --rep __set__. ${ENVELOPE_HELP}`, progress };
@@ -7255,7 +7503,7 @@ function runRecordNext(opts) {
     const progress = payload["progress"];
     process.stdout.write(`[${progress.recordedReps}/${progress.totalReps} reps] ${payload["tool"]} for ${payload["slug"]} (node ${payload["nodeId"]})
   \u2192 ${payload["note"]}
-  \u2192 then: tendril record ingest --set <dir> --rep ${payload["slug"]} --tool ${payload["tool"]} --file <envelope.json>
+  \u2192 then: ${tendrilCommand(`record ingest --set ${path26.resolve(opts.setDir)} --rep ${payload["slug"]} --tool ${payload["tool"]} --file <envelope.json>`)}
 `);
   });
 }
@@ -7329,7 +7577,7 @@ async function autoFetchAssets(setDir, rep, envelopeText2) {
   const skipped = [];
   const failed = [];
   for (const { url, name } of assetUrlsFromEnvelopeText(envelopeText2)) {
-    if (existsSync19(path25.join(setDir, rep, name))) {
+    if (existsSync20(path26.join(setDir, rep, name))) {
       skipped.push(name);
       continue;
     }
@@ -7351,16 +7599,16 @@ async function autoFetchAssets(setDir, rep, envelopeText2) {
 }
 function rawEnvelopeFromFile(file, parts) {
   if (parts) {
-    const blocks = JSON.parse(readFileSync16(path25.resolve(file), "utf8"));
+    const blocks = JSON.parse(readFileSync16(path26.resolve(file), "utf8"));
     if (!Array.isArray(blocks) || blocks.length === 0 || blocks.some((p) => typeof p !== "string")) throw new Error("parts file must be a non-empty JSON array of strings");
     return { content: blocks.map((text) => ({ type: "text", text })) };
   }
-  return { content: [{ type: "text", text: readFileSync16(path25.resolve(file), "utf8") }] };
+  return { content: [{ type: "text", text: readFileSync16(path26.resolve(file), "utf8") }] };
 }
 async function runRecordIngest(opts) {
   let payload;
   try {
-    payload = opts.rawParts === true || opts.raw === true ? rawEnvelopeFromFile(opts.file, opts.rawParts === true) : JSON.parse(readFileSync16(path25.resolve(opts.file), "utf8"));
+    payload = opts.rawParts === true || opts.raw === true ? rawEnvelopeFromFile(opts.file, opts.rawParts === true) : JSON.parse(readFileSync16(path26.resolve(opts.file), "utf8"));
   } catch (err) {
     fail(opts, ExitCode.InputValidation, {
       error: `cannot read envelope file: ${err instanceof Error ? err.message : String(err)}`,
@@ -7372,7 +7620,7 @@ async function runRecordIngest(opts) {
     fail(opts, ExitCode.InputValidation, {
       error: "--raw is for text tool responses; screenshots are binary",
       code: "envelope-invalid",
-      remediation: "Use `tendril record fetch` with the image_url instead."
+      remediation: `Use \`${tendrilCommand(`record fetch --set ${path26.resolve(opts.setDir)} --rep ${opts.rep} --tool ${opts.tool} --url <image_url>`)}\` instead.`
     });
   }
   if (opts.rep === "__set__" && opts.tool === "get_variable_defs") {
@@ -7384,7 +7632,7 @@ async function runRecordIngest(opts) {
         remediation: "Save the get_variable_defs response verbatim as a text envelope."
       });
     }
-    writeFileSync9(path25.join(opts.setDir, "get_variable_defs.json"), `${JSON.stringify(payload, null, 1)}
+    writeFileSync9(path26.join(opts.setDir, "get_variable_defs.json"), `${JSON.stringify(payload, null, 1)}
 `);
     emitData(opts, { ingested: "get_variable_defs", rep: "__set__", setLevel: true, next: nextPayload(opts.setDir) }, () => {
       process.stdout.write("set-level get_variable_defs ingested\n");
@@ -7400,7 +7648,7 @@ async function runRecordIngest(opts) {
       if (assets !== void 0) {
         for (const a of assets.fetched) process.stdout.write(`  asset fetched ${a}
 `);
-        for (const f of assets.failed) process.stdout.write(`  ASSET FAILED ${f.name}: ${f.reason} \u2014 download it and run tendril record asset
+        for (const f of assets.failed) process.stdout.write(`  ASSET FAILED ${f.name}: ${f.reason} \u2014 download it, then: ${tendrilCommand(`record asset --set ${path26.resolve(opts.setDir)} --rep ${opts.rep} --name ${f.name} --file <downloaded-file>`)}
 `);
       }
     });
@@ -7473,14 +7721,14 @@ async function runRecordIngestRep(opts) {
     if (assets !== void 0) {
       for (const a of assets.fetched) process.stdout.write(`  asset fetched ${a}
 `);
-      for (const f of assets.failed) process.stdout.write(`  ASSET FAILED ${f.name}: ${f.reason} \u2014 download it and run tendril record asset
+      for (const f of assets.failed) process.stdout.write(`  ASSET FAILED ${f.name}: ${f.reason} \u2014 download it, then: ${tendrilCommand(`record asset --set ${path26.resolve(opts.setDir)} --rep ${opts.rep} --name ${f.name} --file <downloaded-file>`)}
 `);
     }
   });
 }
 function runRecordAsset(opts) {
   if (opts.dir !== void 0) {
-    const dir = path25.resolve(opts.dir);
+    const dir = path26.resolve(opts.dir);
     const names = readdirSync5(dir).filter((f) => /^asset-[\w.-]+\.(svg|png|jpe?g|webp|gif)$/i.test(f));
     if (names.length === 0) {
       fail(opts, ExitCode.InputValidation, {
@@ -7492,7 +7740,7 @@ function runRecordAsset(opts) {
     const ingested = [];
     try {
       for (const name of names) {
-        ingestAsset(opts.setDir, opts.rep, name, readFileSync16(path25.join(dir, name)));
+        ingestAsset(opts.setDir, opts.rep, name, readFileSync16(path26.join(dir, name)));
         ingested.push(name);
       }
     } catch (err) {
@@ -7512,11 +7760,11 @@ function runRecordAsset(opts) {
     fail(opts, ExitCode.InputValidation, {
       error: "pass --name and --file for a single asset, or --dir for a batch",
       code: "asset-rejected",
-      remediation: "tendril record asset --set <dir> --rep <slug> --dir <downloads-dir>"
+      remediation: tendrilCommand(`record asset --set ${path26.resolve(opts.setDir)} --rep ${opts.rep} --dir <downloads-dir>`)
     });
   }
   try {
-    ingestAsset(opts.setDir, opts.rep, opts.name, readFileSync16(path25.resolve(opts.file)));
+    ingestAsset(opts.setDir, opts.rep, opts.name, readFileSync16(path26.resolve(opts.file)));
     emitData(opts, { rep: opts.rep, asset: opts.name }, () => {
       process.stdout.write(`ingested ${opts.rep}/${opts.name}
 `);
@@ -7541,11 +7789,66 @@ ${status.reps.filter((r) => r.missing.length > 0).length} rep(s) pending
 `);
   });
 }
+function narrowedRoles(derived, override) {
+  const losses = [];
+  const mains = new Set(override.main);
+  for (const main of derived.main) if (!mains.has(main)) losses.push({ kind: "main", main });
+  for (const [part, entry] of Object.entries(derived.parts))
+    for (const main of entry.partOf) if (override.parts[part]?.partOf.includes(main) !== true) losses.push({ kind: "edge", part, main });
+  return losses.sort((a, b) => roleLossToken(a) < roleLossToken(b) ? -1 : 1);
+}
+function rolesFromFile(opts, file, derived) {
+  let json;
+  try {
+    json = JSON.parse(readFileSync16(path26.resolve(file), "utf8"));
+  } catch (err) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `cannot read roles file ${file}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+      code: "roles-file-unreadable",
+      remediation: 'The roles file is JSON: {"main":["<slug>"],"parts":{"<slug>":{"partOf":["<main-slug>"]}}}.'
+    });
+  }
+  const parsed = RolesSchema.safeParse(json);
+  if (!parsed.success) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `roles file rejected: ${parsed.error.issues.slice(0, 3).map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
+      code: "roles-file-invalid",
+      remediation: 'The roles file is JSON: {"main":["<slug>"],"parts":{"<slug>":{"partOf":["<main-slug>"]}},"external":["\u2026"]}.'
+    });
+  }
+  const accepted = parsed.data.narrowingAccepted ?? [];
+  const unaccepted = narrowedRoles(derived, parsed.data).filter((loss) => !accepted.includes(roleLossToken(loss)));
+  if (unaccepted.length > 0) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `roles file narrows what this set's derivation found: it ${unaccepted.map(describeRoleLoss).join("; ")} \u2014 a main the graph never names is not composition-checked at all, and a main whose graph names no parts passes the check vacuously`,
+      code: "roles-file-narrows",
+      remediation: `Keep the derived mains and part edges in the graph, or accept each loss by name: add "narrowingAccepted": ${JSON.stringify(
+        [.../* @__PURE__ */ new Set([...accepted, ...unaccepted.map(roleLossToken)])].sort()
+      )} to the roles file.`
+    });
+  }
+  return {
+    main: parsed.data.main,
+    parts: parsed.data.parts,
+    ...parsed.data.external !== void 0 ? { external: parsed.data.external } : {},
+    ...accepted.length > 0 ? { narrowingAccepted: accepted } : {},
+    // Stamped by the CLI, never read from the file: a supplied graph
+    // does not get to describe itself as derived.
+    rolesSource: "human-override"
+  };
+}
 function runRecordFinish(opts) {
-  const manifest = loadManifest(opts.setDir);
+  if (!existsSync20(path26.join(opts.setDir, "recording-set.json"))) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `no recording-set.json in ${opts.setDir}`,
+      code: "no-recording-set",
+      remediation: `Run \`${tendrilCommand(`record plan --set ${path26.resolve(opts.setDir)} --component <name> --metadata <envelope.json>`)}\` first \u2014 \`record finish\` closes a set the planner opened.`
+    });
+  }
+  const { manifest, raw } = readManifestFile(opts.setDir);
   const derived = deriveRoles(opts.setDir, manifest);
-  const roles = opts.rolesFile !== void 0 ? { ...JSON.parse(readFileSync16(path25.resolve(opts.rolesFile), "utf8")), humanOverride: true } : { main: derived.main, parts: derived.parts, external: derived.external, humanOverride: false };
-  emitData(opts, { derived, confirmed: opts.confirmRoles }, () => {
+  const roles = opts.rolesFile !== void 0 ? rolesFromFile(opts, opts.rolesFile, derived) : { main: derived.main, parts: derived.parts, external: derived.external, rolesSource: "derived" };
+  emitData(opts, { derived, confirmed: opts.confirmRoles, rolesSource: roles.rolesSource, narrowingAccepted: roles.narrowingAccepted ?? [] }, () => {
     process.stdout.write(`derived mains: ${derived.main.join(", ") || "(none)"}
 `);
     for (const [slug, part] of Object.entries(derived.parts)) process.stdout.write(`  part ${slug} \u2192 ${part.partOf.join(", ")}
@@ -7567,24 +7870,40 @@ function runRecordFinish(opts) {
     fail(opts, ExitCode.ConfirmationRequired, {
       error: "--confirm-roles (and --roles-file) require an interactive terminal \u2014 this confirmation is human-only",
       code: "roles-confirmation-not-interactive",
-      remediation: "A human runs `tendril record finish --set <dir> --confirm-roles` in their own terminal. Agents: show the proposal to your operator instead of confirming it."
+      remediation: `A human runs \`${tendrilCommand(`record finish --set ${path26.resolve(opts.setDir)} --confirm-roles`)}\` in their own terminal. Agents: show the proposal to your operator instead of confirming it.`
+    });
+  }
+  const merged = { ...raw, roles };
+  const { issues } = validateRecordingSet(merged, (rel) => existsSync20(path26.join(opts.setDir, rel)));
+  const errors = issues.filter((i) => i.severity === "error");
+  if (errors.length > 0) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `recording set rejected \u2014 roles NOT written: ${errors.map((e) => e.message).join("; ")}`,
+      code: "recording-set-invalid",
+      remediation: `Fix the set (\`${tendrilCommand(`record status --set ${path26.resolve(opts.setDir)}`)}\` lists missing envelopes) or the roles graph, then re-run \`record finish\`.`
     });
   }
-  const updated = { ...manifest, roles };
-  writeFileSync9(path25.join(opts.setDir, "recording-set.json"), `${JSON.stringify(updated, null, 1)}
+  for (const issue of issues) if (issue.severity === "warning") warn(opts, issue.message);
+  writeManifest(opts.setDir, merged);
+  if (!opts.json) {
+    const accepted = roles.narrowingAccepted ?? [];
+    process.stdout.write(`roles written to recording-set.json (source: ${roles.rolesSource})${accepted.length > 0 ? ` \u2014 narrowing accepted by name: ${accepted.join(", ")}` : ""}
 `);
-  if (!opts.json) process.stdout.write("roles written to recording-set.json\n");
+  }
 }
-var ENVELOPE_HELP, isAutoFetchAssetUrl;
+var ENVELOPE_HELP, isAutoFetchAssetUrl, describeRoleLoss;
 var init_record = __esm({
   "packages/cli/src/commands/record.ts"() {
     "use strict";
     init_src3();
     init_src();
+    init_src6();
     init_output();
     init_entitlement();
-    ENVELOPE_HELP = 'Envelope format: text tools save {"content":[{"type":"text","text":"<VERBATIM response text incl. any Currently-selected-nodes block>"}]}; get_screenshot: do NOT download the image yourself \u2014 pass its image_url to `tendril record fetch` (MCP: tendril_record_fetch), which pulls the bytes to disk directly. That keeps the pixel ground truth out of your context and costs one approval instead of a shell command per asset. Assets are asset-<first-8-hex-of-figma-uuid>.<ext>; their URLs appear as const declarations inside the design-context text and also expire.';
+    init_invocation();
+    ENVELOPE_HELP = `Envelope format: text tools save {"content":[{"type":"text","text":"<VERBATIM response text incl. any Currently-selected-nodes block>"}]}; get_screenshot: do NOT download the image yourself \u2014 pass its image_url to \`${tendrilCommand("record fetch")}\` (MCP: tendril_record_fetch), which pulls the bytes to disk directly. That keeps the pixel ground truth out of your context and costs one approval instead of a shell command per asset. Assets are asset-<first-8-hex-of-figma-uuid>.<ext>; their URLs appear as const declarations inside the design-context text and also expire.`;
     isAutoFetchAssetUrl = (url) => isFigmaAssetUrl(url) || isLocalAssetUrl(url);
+    describeRoleLoss = (loss) => loss.kind === "main" ? `drops main "${loss.main}"` : `stops "${loss.part}" being a part of main "${loss.main}"`;
   }
 });
 
@@ -7775,8 +8094,8 @@ var init_engine_curated = __esm({
 });
 
 // packages/generate/src/loop.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync6, readFileSync as readFileSync17, renameSync, writeFileSync as writeFileSync10 } from "node:fs";
-import path26 from "node:path";
+import { existsSync as existsSync21, mkdirSync as mkdirSync6, readFileSync as readFileSync17, renameSync, writeFileSync as writeFileSync10 } from "node:fs";
+import path27 from "node:path";
 import { z as z11 } from "zod";
 function objective(scores, behaviors) {
   const vals = scores.map((s) => Math.min(s.similarity, s.inkRecall));
@@ -7810,12 +8129,12 @@ ${preludeLines.join("\n")}` : ""}${absentLines.length > 0 ? `
 MISSING FEATURES (absent-ink clusters \u2014 recorded marks your render leaves out or paints invisibly; GATING at the cert bar. Fix the named node's ink \u2014 a config carrying one cannot certify):
 ${absentLines.join("\n")}` : ""}
 
-Fix the FAIL configs (region coordinates are in the recorded screenshot's frame; ink<1 means recorded foreground pixels your render does not cover). Reading the pair: ink=1 with LOW sim means nothing is missing \u2014 shapes or positions are wrong, do not chase missing ink; LOW ink with high sim means recorded marks are absent or painted invisibly. Do not regress PASS configs. ${mode === "files" ? "Update the files in your candidate directory and re-run the score." : "Reply with the complete corrected files in the same FILE format."}`;
+Fix the FAIL configs (region coordinates are in the recorded screenshot's frame; ink<1 means recorded foreground pixels your render does not cover). Reading the pair: ink=1 with LOW sim means nothing is MISSING (do not chase missing ink) \u2014 the same pixels are being painted wrong, and there are TWO causes. GEOMETRY: wrong position/size/radius; the diff shows shifted edges and bands. WRONG TEXT WEIGHT OR FACE: the diff shows a uniform haze over glyph runs; CSS binds the font FAMILY before the weight, a later family in the stack is never consulted for a weight the first one lacks, and font-synthesis: none rules out faux-bold \u2014 so a stack led by a family the kit holds at one weight renders every other weight in that face, silently. Check the font stack against the kit's cached faces before concluding geometry is at fault. LOW ink with high sim means recorded marks are absent or painted invisibly. Do not regress PASS configs. ${mode === "files" ? "Update the files in your candidate directory and re-run the score." : "Reply with the complete corrected files in the same FILE format."}`;
 }
 function archivePriorRun(outDir) {
-  if (!existsSync20(path26.join(outDir, "run-log.json")) && !existsSync20(path26.join(outDir, "loop-state.json"))) return void 0;
+  if (!existsSync21(path27.join(outDir, "run-log.json")) && !existsSync21(path27.join(outDir, "loop-state.json"))) return void 0;
   let n = 1;
-  while (existsSync20(`${outDir}-prev-${n}`)) n += 1;
+  while (existsSync21(`${outDir}-prev-${n}`)) n += 1;
   renameSync(outDir, `${outDir}-prev-${n}`);
   return `${outDir}-prev-${n}`;
 }
@@ -7824,14 +8143,14 @@ async function runEngineLoop(opts) {
   const plateau = opts.plateau ?? 2;
   const progress = opts.onProgress ?? (() => {
   });
-  const statePath = path26.join(opts.outDir, "loop-state.json");
-  const resuming = opts.resume === true && existsSync20(statePath);
+  const statePath = path27.join(opts.outDir, "loop-state.json");
+  const resuming = opts.resume === true && existsSync21(statePath);
   if (!resuming) {
     const archived = archivePriorRun(opts.outDir);
     if (archived !== void 0) progress(`previous run archived to ${archived}`);
   }
   mkdirSync6(opts.outDir, { recursive: true });
-  const scratch = path26.join(opts.outDir, ".candidate");
+  const scratch = path27.join(opts.outDir, ".candidate");
   let attempts = [];
   let log = [];
   let best;
@@ -7859,7 +8178,7 @@ async function runEngineLoop(opts) {
   };
   const writeCandidate = (files) => {
     mkdirSync6(scratch, { recursive: true });
-    for (const [name, content] of Object.entries(files)) writeFileSync10(path26.join(scratch, name), content);
+    for (const [name, content] of Object.entries(files)) writeFileSync10(path27.join(scratch, name), content);
   };
   const scoreCandidate = async (candidate, iter, usd, modelMs) => {
     writeCandidate(candidate.files);
@@ -7917,8 +8236,8 @@ async function runEngineLoop(opts) {
       const usd = candidate.usage?.usd ?? 0;
       spentUsd += usd;
       if (candidate.raw !== void 0) {
-        mkdirSync6(path26.join(opts.outDir, "responses"), { recursive: true });
-        writeFileSync10(path26.join(opts.outDir, "responses", `iter-${iter}.md`), candidate.raw);
+        mkdirSync6(path27.join(opts.outDir, "responses"), { recursive: true });
+        writeFileSync10(path27.join(opts.outDir, "responses", `iter-${iter}.md`), candidate.raw);
       }
       if (candidate.files[opts.entry] === void 0 || candidate.files["styles.css"] === void 0) {
         const finish = candidate.usage?.finishReason ?? "?";
@@ -7944,10 +8263,10 @@ async function runEngineLoop(opts) {
       }
     }
   }
-  if (best !== void 0) for (const [name, content] of Object.entries(best.files)) writeFileSync10(path26.join(opts.outDir, name), content);
+  if (best !== void 0) for (const [name, content] of Object.entries(best.files)) writeFileSync10(path27.join(opts.outDir, name), content);
   const final = best !== void 0 ? await opts.score(opts.outDir) : { scores: [], behaviors: [] };
   writeFileSync10(
-    path26.join(opts.outDir, "run-log.json"),
+    path27.join(opts.outDir, "run-log.json"),
     `${JSON.stringify(
       {
         ...opts.meta,
@@ -8014,8 +8333,8 @@ var init_loop2 = __esm({
 });
 
 // packages/generate/src/brief.ts
-import { existsSync as existsSync21, readFileSync as readFileSync18 } from "node:fs";
-import path27 from "node:path";
+import { existsSync as existsSync22, readFileSync as readFileSync18 } from "node:fs";
+import path28 from "node:path";
 function singleAxes2(name) {
   const parsed = parseVariantAxes(name);
   if (parsed === void 0) return void 0;
@@ -8254,8 +8573,8 @@ function envelopeText(file) {
 }
 function dismissEvidence(setDir, repSlugs) {
   for (const slug of repSlugs) {
-    const f = path27.join(setDir, slug, "get_design_context.json");
-    if (!existsSync21(f)) continue;
+    const f = path28.join(setDir, slug, "get_design_context.json");
+    if (!existsSync22(f)) continue;
     const text = envelopeText(f);
     const propHit = /[{,]\s*(\w*dismiss\w*)\s*=\s*(?:true|false)\b/i.exec(text) ?? /\b(\w*dismiss\w*)\??\s*:\s*boolean\b/i.exec(text);
     if (propHit !== null) return `emission prop "${propHit[1]}"`;
@@ -8299,13 +8618,13 @@ function recordedFontNeeds(setDir, opts = {}) {
     }
   };
   const manifest = loadManifest(setDir);
-  const setDefs = path27.join(setDir, "get_variable_defs.json");
-  if (existsSync21(setDefs)) fromDefs(envelopeText(setDefs));
+  const setDefs = path28.join(setDir, "get_variable_defs.json");
+  if (existsSync22(setDefs)) fromDefs(envelopeText(setDefs));
   for (const rep of manifest.reps) {
-    const ctx = path27.join(setDir, rep.slug, "get_design_context.json");
-    if (existsSync21(ctx)) fromEmission(envelopeText(ctx));
-    const defs = path27.join(setDir, rep.slug, "get_variable_defs.json");
-    if (existsSync21(defs)) fromDefs(envelopeText(defs));
+    const ctx = path28.join(setDir, rep.slug, "get_design_context.json");
+    if (existsSync22(ctx)) fromEmission(envelopeText(ctx));
+    const defs = path28.join(setDir, rep.slug, "get_variable_defs.json");
+    if (existsSync22(defs)) fromDefs(envelopeText(defs));
   }
   return [...byFamily.entries()].map(([family, paired]) => {
     const weights = /* @__PURE__ */ new Set([...paired, ...opts.pairedOnly === true ? [] : unpaired]);
@@ -8316,8 +8635,8 @@ function symbolFontGlyphCount(setDir, reps) {
   const PUA = /[\uE000-\uF8FF\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]/u;
   const glyphs = /* @__PURE__ */ new Set();
   for (const rep of reps) {
-    const file = path27.join(setDir, rep, "get_metadata.json");
-    if (!existsSync21(file)) continue;
+    const file = path28.join(setDir, rep, "get_metadata.json");
+    if (!existsSync22(file)) continue;
     try {
       const text = JSON.parse(readFileSync18(file, "utf8")).content.map((c) => c.text ?? "").join("\n");
       for (const m of text.matchAll(/<text\s[^>]*name="([^"]*)"/g)) {
@@ -8345,8 +8664,8 @@ function recordedTextSlots(setDir, repSlugs) {
   const propRep = [];
   const perRep = [];
   for (const slug of repSlugs) {
-    const f = path27.join(setDir, slug, "get_design_context.json");
-    if (!existsSync21(f)) continue;
+    const f = path28.join(setDir, slug, "get_design_context.json");
+    if (!existsSync22(f)) continue;
     const code = envelopeText(f);
     const props = /* @__PURE__ */ new Map();
     for (const m of code.matchAll(/[{,]\s*(\w+)\s*=\s*"((?:[^"\\]|\\.)*)"/g)) {
@@ -8371,8 +8690,8 @@ function recordedTextSlots(setDir, repSlugs) {
   }
   const axisValuesBySlug = /* @__PURE__ */ new Map();
   for (const slug of repSlugs) {
-    const metaFile = path27.join(setDir, slug, "get_metadata.json");
-    if (!existsSync21(metaFile)) continue;
+    const metaFile = path28.join(setDir, slug, "get_metadata.json");
+    if (!existsSync22(metaFile)) continue;
     const name = symbolName(envelopeText(metaFile));
     if (name === void 0) continue;
     const values = /* @__PURE__ */ new Set();
@@ -8471,8 +8790,8 @@ function authorTaskFromSet(setDir, opts = {}) {
   const poses = [];
   const missing = [];
   for (const rep of manifest.reps) {
-    const metaFile = path27.join(setDir, rep.slug, "get_metadata.json");
-    if (!existsSync21(metaFile)) {
+    const metaFile = path28.join(setDir, rep.slug, "get_metadata.json");
+    if (!existsSync22(metaFile)) {
       missing.push(rep.slug);
       continue;
     }
@@ -8486,8 +8805,8 @@ function authorTaskFromSet(setDir, opts = {}) {
   if (missing.length > 0) {
     throw new Error(`recording set ${setDir} is missing metadata for ${missing.length} rep(s): ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", \u2026" : ""}`);
   }
-  const setMeta = path27.join(setDir, "get_metadata.json");
-  const latticeNames = manifest.latticeNames ?? (existsSync21(setMeta) ? [...envelopeText(setMeta).matchAll(/name="([^"]*)"/g)].map((m) => decodeXmlEntities(m[1])) : void 0);
+  const setMeta = path28.join(setDir, "get_metadata.json");
+  const latticeNames = manifest.latticeNames ?? (existsSync22(setMeta) ? [...envelopeText(setMeta).matchAll(/name="([^"]*)"/g)].map((m) => decodeXmlEntities(m[1])) : void 0);
   const defaults = { ...manifest.defaults ?? {}, ...opts.defaults ?? {} };
   const recordedFonts = recordedFontFamilies(setDir);
   const textSlots = recordedTextSlots(setDir, manifest.reps.map((r) => r.slug));
@@ -8661,10 +8980,10 @@ var init_brief = __esm({
 });
 
 // packages/generate/src/segments.ts
-import { existsSync as existsSync22, readFileSync as readFileSync19, readdirSync as readdirSync6 } from "node:fs";
-import path28 from "node:path";
+import { existsSync as existsSync23, readFileSync as readFileSync19, readdirSync as readdirSync6 } from "node:fs";
+import path29 from "node:path";
 function repText(set, rep, tool) {
-  const env = JSON.parse(readFileSync19(path28.join(set, rep, `${tool}.json`), "utf8"));
+  const env = JSON.parse(readFileSync19(path29.join(set, rep, `${tool}.json`), "utf8"));
   return tool === "get_design_context" ? envelopeFirstTextPart(env) : envelopeTextContent(env);
 }
 function stripFigmaInstructions(emission) {
@@ -8725,16 +9044,16 @@ DROPPED from the map, untrustworthy in the source export \u2014 for these, each
 function buildSegments(task, mode = "fenced") {
   const SET = task.set;
   let rawDefs = {};
-  if (existsSync22(path28.join(SET, "get_variable_defs.json"))) {
-    const text = envelopeFirstTextPart(JSON.parse(readFileSync19(path28.join(SET, "get_variable_defs.json"), "utf8"))) || "{}";
+  if (existsSync23(path29.join(SET, "get_variable_defs.json"))) {
+    const text = envelopeFirstTextPart(JSON.parse(readFileSync19(path29.join(SET, "get_variable_defs.json"), "utf8"))) || "{}";
     try {
       rawDefs = JSON.parse(text);
     } catch {
     }
   } else {
     for (const cfg of task.configs) {
-      const f = path28.join(SET, cfg.rep, "get_variable_defs.json");
-      if (!existsSync22(f)) continue;
+      const f = path29.join(SET, cfg.rep, "get_variable_defs.json");
+      if (!existsSync23(f)) continue;
       const text = envelopeFirstTextPart(JSON.parse(readFileSync19(f, "utf8"))) || "{}";
       try {
         for (const [k, v] of Object.entries(JSON.parse(text))) rawDefs[k] ??= v;
@@ -8743,8 +9062,8 @@ function buildSegments(task, mode = "fenced") {
     }
   }
   const emissionTexts = task.configs.map((cfg) => {
-    const f = path28.join(SET, cfg.rep, "get_design_context.json");
-    return existsSync22(f) ? envelopeFirstTextPart(JSON.parse(readFileSync19(f, "utf8"))) : "";
+    const f = path29.join(SET, cfg.rep, "get_design_context.json");
+    return existsSync23(f) ? envelopeFirstTextPart(JSON.parse(readFileSync19(f, "utf8"))) : "";
   });
   const { map, note } = cleanTokenMap(rawDefs, emissionTexts);
   const defs = JSON.stringify(map, null, 1);
@@ -8759,9 +9078,9 @@ ${defs}
   for (const cfg of task.configs) {
     const meta = stripFigmaInstructions(repText(SET, cfg.rep, "get_metadata"));
     const emission = stripFigmaInstructions(repText(SET, cfg.rep, "get_design_context"));
-    const assets = readdirSync6(path28.join(SET, cfg.rep)).filter((f) => f.startsWith("asset-") && f.endsWith(".svg")).map((f) => `asset ${f}:
+    const assets = readdirSync6(path29.join(SET, cfg.rep)).filter((f) => f.startsWith("asset-") && f.endsWith(".svg")).map((f) => `asset ${f}:
 \`\`\`svg
-${readFileSync19(path28.join(SET, cfg.rep, f), "utf8")}
+${readFileSync19(path29.join(SET, cfg.rep, f), "utf8")}
 \`\`\``).join("\n");
     parts.push(`
 ## Config ${cfg.rep} \u2192 ${cfg.component} ${JSON.stringify(cfg.props)}
@@ -8786,7 +9105,7 @@ Optionally a third block with \`/* FILE: tokens.css */\`.`);
   } else {
     parts.push(`
 ## Output format
-Write the COMPLETE files (${task.entry}, styles.css, optional tokens.css) into your candidate directory. Do not paste file contents into chat \u2014 the scorer reads the directory.`);
+Write the COMPLETE files (${task.entry}, styles.css, optional tokens.css) into ONE candidate directory: \`tendril-out/${path29.basename(task.set)}-candidate/\` unless you were handed another path. Pass that same directory to \`tendril engine score\` every round and keep writing into it \u2014 the scorer stamps the bundle there, writes its evidence beside your files, and appends its score-history.jsonl lines there (one when a round starts, one when it scores); a fresh directory each round throws all of that away. Do not paste file contents into chat \u2014 the scorer reads the directory.`);
   }
   return parts.join("\n");
 }
@@ -8854,8 +9173,8 @@ var init_adapter = __esm({
 
 // packages/generate/src/bundle-emit.ts
 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";
+import { copyFileSync, existsSync as existsSync24, mkdirSync as mkdirSync7, readFileSync as readFileSync20, readdirSync as readdirSync7, rmSync as rmSync3, writeFileSync as writeFileSync11 } from "node:fs";
+import path30 from "node:path";
 function pinFromConfigs(configs) {
   const domains = /* @__PURE__ */ new Map();
   const kinds = /* @__PURE__ */ new Map();
@@ -8903,6 +9222,11 @@ function cssFontFamilies(css) {
   }
   return [...out];
 }
+function upstreamAttribution(face) {
+  if (!face.source.startsWith(GOOGLE_FONT_FILE_PREFIX)) return face.source;
+  if (face.servedFamily === void 0) return `the Google Fonts specimen for "${face.family.replace(/[\r\n]+/g, " ")}"`;
+  return `https://fonts.google.com/specimen/${encodeURIComponent(face.servedFamily).replace(/%20/g, "+")}/license`;
+}
 function fontsCssFor(faces, bundleDir, cacheDir = DEFAULT_FONT_CACHE, substitutedFamilies = []) {
   const header = [
     "/* tendril fonts.css \u2014 the exact faces this bundle was scored with (sha-pinned in",
@@ -8916,32 +9240,78 @@ function fontsCssFor(faces, bundleDir, cacheDir = DEFAULT_FONT_CACHE, substitute
     ] : []
   ];
   const lines = [];
+  const notices = [];
+  const licenseTexts = /* @__PURE__ */ new Map();
   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 src = path30.join(cacheDir, path30.basename(face.file));
+    const target = `./fonts/${path30.basename(face.file)}`;
+    const format = FONT_FORMATS[path30.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} */`
+    const license = normalizeFontLicense(face.license);
+    const terms = REDISTRIBUTABLE.get(license);
+    if (terms === void 0) {
+      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 (license === "unknown") {
+        lines.push(
+          `/* '${family}' ${face.weight}: no licence on record (sha256 ${face.sha256.slice(0, 16)}\u2026). That is a gap`,
+          "   in the font cache, not a statement about your rights \u2014 Tendril copies font bytes into a",
+          "   bundle only under a licence it can name, so this face is declared here instead. Establish",
+          `   the licence with \`tendril fonts resolve "${family}" --weights ${face.weight}\``,
+          "   (or `tendril fonts resolve --set <recording-dir>`) and re-emit. If it is a face you licence",
+          `   rather than one free to redistribute, place your copy at ${target} and uncomment: */`,
+          `/* ${decl} */`
+        );
+      } else {
+        lines.push(
+          `/* '${family}' ${face.weight} is recorded as ${license} (sha256 ${face.sha256.slice(0, 16)}\u2026), which does`,
+          "   not permit redistribution \u2014 Tendril never copies such bytes. Place your licensed copy",
+          `   at ${target} and uncomment: */`,
+          `/* ${decl} */`
+        );
+      }
+    } else if (existsSync24(src) && createHash4("sha256").update(readFileSync20(src)).digest("hex") === face.sha256) {
+      mkdirSync7(path30.join(bundleDir, "fonts"), { recursive: true });
+      copyFileSync(src, path30.join(bundleDir, "fonts", path30.basename(face.file)));
+      licenseTexts.set(terms.file, terms.text);
+      const upstream = upstreamAttribution(face);
+      notices.push(
+        "",
+        `${face.family.replace(/[\r\n]+/g, " ")} ${face.weight} \u2014 ./${path30.basename(face.file)}`,
+        `  licence:   ${terms.title} \u2014 full text in ./${terms.file}`,
+        `  source:    ${face.source}`,
+        `  sha256:    ${face.sha256}`,
+        "  copyright: this face's upstream copyright statement is published with its",
+        `             original release \u2014 ${upstream}`
       );
-    } 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")}
+  if (lines.length === 0) return null;
+  if (notices.length > 0) {
+    const fontsDir = path30.join(bundleDir, "fonts");
+    for (const [file, text] of licenseTexts) writeFileSync11(path30.join(fontsDir, file), text);
+    writeFileSync11(path30.join(fontsDir, "NOTICE.txt"), `${[NOTICE_PREAMBLE, ...notices].join("\n")}
+`);
+    header.push(
+      "/* REDISTRIBUTION: the face files in ./fonts/ are redistributed under the licences",
+      `   recorded in ./fonts/NOTICE.txt; full texts in ${[...licenseTexts.keys()].map((f) => `./fonts/${f}`).join(", ")}.`,
+      "   Keep NOTICE.txt and the licence texts with the font files wherever they travel. */"
+    );
+  }
+  return `${[...header, ...lines].join("\n")}
 `;
 }
 function countLatticeSymbols(setDir) {
-  const manifestFile = path29.join(setDir, "recording-set.json");
-  if (existsSync23(manifestFile)) {
+  const manifestFile = path30.join(setDir, "recording-set.json");
+  if (existsSync24(manifestFile)) {
     try {
       const lattice = JSON.parse(readFileSync20(manifestFile, "utf8")).latticeNames;
       if (lattice !== void 0 && lattice.length > 0) return lattice.length;
@@ -8949,9 +9319,9 @@ function countLatticeSymbols(setDir) {
     }
   }
   const files = [
-    path29.join(setDir, "get_metadata.json"),
-    ...existsSync23(setDir) ? readdirSync7(setDir).filter((f) => /^get_metadata-.*\.json$/.test(f)).map((f) => path29.join(setDir, f)) : []
-  ].filter((f) => existsSync23(f));
+    path30.join(setDir, "get_metadata.json"),
+    ...existsSync24(setDir) ? readdirSync7(setDir).filter((f) => /^get_metadata-.*\.json$/.test(f)).map((f) => path30.join(setDir, f)) : []
+  ].filter((f) => existsSync24(f));
   if (files.length === 0) return null;
   let count = 0;
   for (const f of files) {
@@ -8963,21 +9333,21 @@ function countLatticeSymbols(setDir) {
 function recordingSetHash(setDir, configs) {
   const relPaths = [];
   for (const name of ["recording-set.json", "completeness-manifest.json", "get_variable_defs.json", "get_metadata.json"]) {
-    if (existsSync23(path29.join(setDir, name))) relPaths.push(name);
+    if (existsSync24(path30.join(setDir, name))) relPaths.push(name);
   }
   for (const cfg of configs) {
     for (const f of ["get_design_context.json", "get_metadata.json", "get_screenshot.json", "get_variable_defs.json"]) {
-      if (existsSync23(path29.join(setDir, cfg.rep, f))) relPaths.push(`${cfg.rep}/${f}`);
+      if (existsSync24(path30.join(setDir, cfg.rep, f))) relPaths.push(`${cfg.rep}/${f}`);
     }
-    if (existsSync23(path29.join(setDir, cfg.rep))) {
-      for (const asset of readdirSync7(path29.join(setDir, cfg.rep)).filter((f) => f.startsWith("asset-"))) {
+    if (existsSync24(path30.join(setDir, cfg.rep))) {
+      for (const asset of readdirSync7(path30.join(setDir, cfg.rep)).filter((f) => f.startsWith("asset-"))) {
         relPaths.push(`${cfg.rep}/${asset}`);
       }
     }
   }
   return hashRecordingSet(
     relPaths,
-    (p) => new Uint8Array(readFileSync20(path29.join(setDir, p))),
+    (p) => new Uint8Array(readFileSync20(path30.join(setDir, p))),
     (chunks) => {
       const h = createHash4("sha256");
       for (const c of chunks) h.update(c);
@@ -9000,7 +9370,7 @@ function emitBundleV1(opts) {
   const lattice = countLatticeSymbols(opts.task.set);
   const interaction = opts.behaviors.filter((b) => !b.id.startsWith("prelude:"));
   const prelude = opts.behaviors.filter((b) => b.id.startsWith("prelude:"));
-  const cssFiles = ["styles.css", "tokens.css"].map((f) => path29.join(opts.bundleDir, f)).filter((f) => existsSync23(f));
+  const cssFiles = ["styles.css", "tokens.css"].map((f) => path30.join(opts.bundleDir, f)).filter((f) => existsSync24(f));
   const families = cssFontFamilies(cssFiles.map((f) => readFileSync20(f, "utf8")).join("\n"));
   const requiredFonts = requiredFontsManifest(families, opts.fontCacheDir).map((f) => ({
     family: f.family,
@@ -9030,7 +9400,7 @@ function emitBundleV1(opts) {
         // resolvable via verify's --set override).
         path: (() => {
           const base = process.env["INIT_CWD"] ?? process.cwd();
-          const rel = path29.relative(base, opts.task.set);
+          const rel = path30.relative(base, opts.task.set);
           return rel !== "" && !rel.startsWith("..") ? rel : opts.task.set;
         })(),
         component: opts.componentName,
@@ -9054,12 +9424,12 @@ function emitBundleV1(opts) {
     })
   };
   const written = [];
-  const manifestPath2 = path29.join(opts.bundleDir, "component.json");
+  const manifestPath2 = path30.join(opts.bundleDir, "component.json");
   writeFileSync11(manifestPath2, `${JSON.stringify(manifest, null, 2)}
 `);
   written.push(manifestPath2);
-  const stylesPath = path29.join(opts.bundleDir, "styles.css");
-  if (existsSync23(stylesPath)) {
+  const stylesPath = path30.join(opts.bundleDir, "styles.css");
+  if (existsSync24(stylesPath)) {
     const comment = cssProvenanceComment({ pass, scored: statuses.length, certified, latticeConfigs: lattice });
     const current = readFileSync20(stylesPath, "utf8");
     const stripped = current.replace(/^\/\* tendril bundle v\d+ [^]*?\*\/\n/, "");
@@ -9067,8 +9437,8 @@ 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 });
+  const fontsCssPath = path30.join(opts.bundleDir, "fonts.css");
+  rmSync3(path30.join(opts.bundleDir, "fonts"), { recursive: true, force: true });
   rmSync3(fontsCssPath, { force: true });
   const fontsCss = fontsCssFor(requiredFontsManifest(families, opts.fontCacheDir), opts.bundleDir, opts.fontCacheDir, opts.substitutedFamilies ?? []);
   if (fontsCss !== null) {
@@ -9079,7 +9449,7 @@ ${stripped}`);
   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 FONT_FORMATS, BARS;
+var FONT_FORMATS, BARS, NOTICE_PREAMBLE, OFL_1_1_TEXT, UFL_1_0_TEXT, APACHE_2_0_TEXT, REDISTRIBUTABLE;
 var init_bundle_emit = __esm({
   "packages/generate/src/bundle-emit.ts"() {
     "use strict";
@@ -9091,6 +9461,408 @@ var init_bundle_emit = __esm({
       pass: { sim: 0.95, ink: 0.95 },
       cert: { sim: 0.97, ink: 0.95 }
     };
+    NOTICE_PREAMBLE = [
+      "Font redistribution notice \u2014 tendril bundle",
+      "===========================================",
+      "",
+      "The font files in this directory were copied into the bundle because the",
+      "licence they are served under permits redistribution. Each entry below names",
+      "that licence, the exact file the bytes came from, and the sha256 the bundle",
+      "was scored against. Full licence texts sit beside this file \u2014 keep them, and",
+      "this notice, with the font files wherever they travel."
+    ].join("\n");
+    OFL_1_1_TEXT = `-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+`;
+    UFL_1_0_TEXT = `-------------------------------
+UBUNTU FONT LICENCE Version 1.0
+-------------------------------
+
+PREAMBLE
+This licence allows the licensed fonts to be used, studied, modified and
+redistributed freely. The fonts, including any derivative works, can be
+bundled, embedded, and redistributed provided the terms of this licence
+are met. The fonts and derivatives, however, cannot be released under
+any other licence. The requirement for fonts to remain under this
+licence does not require any document created using the fonts or their
+derivatives to be published under this licence, as long as the primary
+purpose of the document is not to be a vehicle for the distribution of
+the fonts.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this licence and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Original Version" refers to the collection of Font Software components
+as received under this licence.
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to
+a new environment.
+
+"Copyright Holder(s)" refers to all individuals and companies who have a
+copyright ownership of the Font Software.
+
+"Substantially Changed" refers to Modified Versions which can be easily
+identified as dissimilar to the Font Software by users of the Font
+Software comparing the Original Version with the Modified Version.
+
+To "Propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification and with or without charging
+a redistribution fee), making available to the public, and in some
+countries other activities as well.
+
+PERMISSION & CONDITIONS
+This licence does not grant any rights under trademark law and all such
+rights are reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of the Font Software, to propagate the Font Software, subject to
+the below conditions:
+
+1) Each copy of the Font Software must contain the above copyright
+notice and this licence. These can be included either as stand-alone
+text files, human-readable headers or in the appropriate machine-
+readable metadata fields within text or binary files as long as those
+fields can be easily viewed by the user.
+
+2) The font name complies with the following:
+(a) The Original Version must retain its name, unmodified.
+(b) Modified Versions which are Substantially Changed must be renamed to
+avoid use of the name of the Original Version or similar names entirely.
+(c) Modified Versions which are not Substantially Changed must be
+renamed to both (i) retain the name of the Original Version and (ii) add
+additional naming elements to distinguish the Modified Version from the
+Original Version. The name of such Modified Versions must be the name of
+the Original Version, with "derivative X" where X represents the name of
+the new work, appended to that name.
+
+3) The name(s) of the Copyright Holder(s) and any contributor to the
+Font Software shall not be used to promote, endorse or advertise any
+Modified Version, except (i) as required by this licence, (ii) to
+acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with
+their explicit written permission.
+
+4) The Font Software, modified or unmodified, in part or in whole, must
+be distributed entirely under this licence, and must not be distributed
+under any other licence. The requirement for fonts to remain under this
+licence does not affect any document created using the Font Software,
+except any version of the Font Software extracted from a document
+created using the Font Software may only be distributed under this
+licence.
+
+TERMINATION
+This licence becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER
+DEALINGS IN THE FONT SOFTWARE.
+`;
+    APACHE_2_0_TEXT = `
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+`;
+    REDISTRIBUTABLE = /* @__PURE__ */ new Map([
+      ["OFL-1.1", { title: "SIL Open Font License 1.1", file: "LICENSE-OFL-1.1.txt", text: OFL_1_1_TEXT }],
+      ["Apache-2.0", { title: "Apache License 2.0", file: "LICENSE-Apache-2.0.txt", text: APACHE_2_0_TEXT }],
+      ["UFL-1.0", { title: "Ubuntu Font Licence 1.0", file: "LICENSE-UFL-1.0.txt", text: UFL_1_0_TEXT }]
+    ]);
   }
 });
 
@@ -9120,8 +9892,8 @@ __export(fonts_exports, {
   runFontsResolveSet: () => runFontsResolveSet,
   runFontsStatus: () => runFontsStatus
 });
-import { existsSync as existsSync24, readFileSync as readFileSync21 } from "node:fs";
-import path30 from "node:path";
+import { existsSync as existsSync25, readFileSync as readFileSync21 } from "node:fs";
+import path31 from "node:path";
 async function runFontsResolve(opts) {
   const result = await resolveFonts(opts.family, opts.weights, opts.cacheDir);
   emitData(opts, result, () => {
@@ -9136,7 +9908,7 @@ async function runFontsResolve(opts) {
   }
 }
 async function runFontsResolveSet(opts) {
-  const setDir = path30.resolve(process.env["INIT_CWD"] ?? process.cwd(), opts.set);
+  const setDir = path31.resolve(process.env["INIT_CWD"] ?? process.cwd(), opts.set);
   let needs = [];
   try {
     needs = recordedFontNeeds(setDir);
@@ -9144,57 +9916,81 @@ async function runFontsResolveSet(opts) {
     fail(opts, ExitCode.InputValidation, {
       error: `cannot read font needs from ${setDir}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
       code: "font-needs-unreadable",
-      remediation: 'Point --set at a directory recorded with `tendril record` (it carries recording-set.json), or resolve a family explicitly: tendril fonts resolve "<Family>" --weights 400 500 600.'
+      remediation: `Point --set at a directory recorded with \`${tendrilCommand("record plan")}\` (it carries recording-set.json), or resolve a family explicitly: ${tendrilCommand('fonts resolve "<Family>" --weights 400 500 600')}.`
     });
   }
   if (needs.length === 0) {
     fail(opts, ExitCode.InputValidation, {
       error: `recording set ${setDir} declares no detectable font families`,
       code: "font-needs-empty",
-      remediation: 'Resolve the family the design uses explicitly: tendril fonts resolve "<Family>" --weights 400 500 600.'
+      remediation: `Resolve the family the design uses explicitly: ${tendrilCommand('fonts resolve "<Family>" --weights 400 500 600')}.`
     });
   }
   const inCache = new Set(resolvedFontFamilies(opts.cacheDir).flatMap((f) => f.weights.map((w) => `${f.family.toLowerCase()}:${w}`)));
-  const cached = [];
+  const unstamped = new Map(facesMissingLicense(opts.cacheDir).map((f) => [`${f.family.toLowerCase()}:${f.weight}`, f.sha256]));
+  const cached2 = [];
   const resolved = [];
   const failures = [];
+  const relicensed = [];
+  const unlicensed = [];
+  const byteDrift = [];
   for (const need of needs) {
     const missing = [];
+    const toStamp = [];
     for (const w of need.weights) {
-      if (inCache.has(`${need.family.toLowerCase()}:${w}`)) cached.push({ family: need.family, weight: w });
-      else missing.push(w);
+      const key = `${need.family.toLowerCase()}:${w}`;
+      if (!inCache.has(key)) missing.push(w);
+      else if (unstamped.has(key)) toStamp.push(w);
+      else cached2.push({ family: need.family, weight: w });
+    }
+    if (missing.length > 0) {
+      const result = await resolveFonts(need.family, missing, opts.cacheDir);
+      resolved.push(...result.resolved);
+      failures.push(...result.failures);
+    }
+    if (toStamp.length > 0) {
+      const result = await resolveFonts(need.family, toStamp, opts.cacheDir);
+      for (const face of result.resolved) {
+        if (face.license === "unknown") unlicensed.push({ family: face.family, weight: face.weight, reason: "the foundry's metadata named no licence for this family" });
+        else relicensed.push({ family: face.family, weight: face.weight, license: face.license });
+        if (unstamped.get(`${face.family.toLowerCase()}:${face.weight}`) !== face.sha256) byteDrift.push({ family: face.family, weight: face.weight });
+      }
+      unlicensed.push(...result.failures);
     }
-    if (missing.length === 0) continue;
-    const result = await resolveFonts(need.family, missing, opts.cacheDir);
-    resolved.push(...result.resolved);
-    failures.push(...result.failures);
   }
-  emitData(opts, { set: setDir, needs, cached, resolved, failures }, () => {
+  emitData(opts, { set: setDir, needs, cached: cached2, resolved, relicensed, unlicensed, failures }, () => {
     process.stdout.write(`set declares: ${needs.map((n) => `${n.family} (${n.weights.join(", ")})`).join(" \xB7 ")}
 `);
-    for (const f of cached) process.stdout.write(`cached   ${f.family} ${f.weight}
+    for (const f of cached2) process.stdout.write(`cached   ${f.family} ${f.weight}
 `);
     for (const f of resolved) process.stdout.write(`resolved ${f.family} ${f.weight} (${f.sha256.slice(0, 12)}\u2026)
+`);
+    for (const f of relicensed) process.stdout.write(`licence  ${f.family} ${f.weight}: ${f.license} \u2014 recorded now; bundles may ship these bytes with the licence text
+`);
+    for (const f of unlicensed) process.stdout.write(`licence  ${f.family} ${f.weight}: still not on record (${f.reason}) \u2014 the cached face renders as always; bundles declare it instead of copying it
 `);
     for (const f of failures) process.stdout.write(`FAILED   ${f.family} ${f.weight}: ${f.reason}
 `);
   });
+  if (byteDrift.length > 0) {
+    warn(opts, `${byteDrift.map((f) => `${f.family} ${f.weight}`).join(", ")}: the foundry now serves different bytes than the cache held \u2014 the faces were re-fetched to record their licence, so re-pin any font lock deliberately`);
+  }
   if (failures.length > 0) {
     warn(opts, `${failures.length} face(s) unresolved \u2014 verification will refuse to score under substitution`);
     process.exitCode = ExitCode.FontsUnproven;
   }
 }
 function runFontsStatus(opts) {
-  const manifestPath2 = path30.join(opts.cacheDir, "manifest.json");
-  if (!existsSync24(manifestPath2)) {
+  const manifestPath2 = path31.join(opts.cacheDir, "manifest.json");
+  if (!existsSync25(manifestPath2)) {
     fail(opts, ExitCode.FontsUnproven, {
       error: `no font cache at ${opts.cacheDir}`,
       code: "fonts-unresolved",
-      remediation: 'Run `tendril fonts resolve --set <recording-dir>` (or `tendril fonts resolve "<Family>" --weights 400 500 600`) first.'
+      remediation: `Run \`${tendrilCommand("fonts resolve --set <recording-dir>")}\` (or \`${tendrilCommand('fonts resolve "<Family>" --weights 400 500 600')}\`) first.`
     });
   }
   const faces = JSON.parse(readFileSync21(manifestPath2, "utf8"));
-  const lockVerdicts = opts.lock !== void 0 ? checkFontLock(path30.resolve(opts.lock), opts.cacheDir) : null;
+  const lockVerdicts = opts.lock !== void 0 ? checkFontLock(path31.resolve(opts.lock), opts.cacheDir) : null;
   emitData(opts, { faces, lockVerdicts }, () => {
     for (const f of faces) process.stdout.write(`cached ${f.family} ${f.weight} (${f.sha256.slice(0, 12)}\u2026)
 `);
@@ -9225,7 +10021,10 @@ function runFontsAdd(opts) {
     fail(opts, ExitCode.InputValidation, {
       error: err instanceof Error ? err.message : String(err),
       code: "font-add-failed",
-      remediation: 'Pass a font file you are licensed to use: tendril fonts add "S\xF6hne" 400 ./fonts/soehne-400.woff2'
+      // The face file is the user's own licensed asset: this command
+      // can name every argument but that one, so it stays a marked
+      // blank rather than a fabricated path that looks real.
+      remediation: `Pass a font file you are licensed to use, by absolute path: ${tendrilCommand(`fonts add "${opts.family}" ${opts.weight} <absolute-path-to-face.woff2>`)}`
     });
   }
   emitData(opts, face, () => {
@@ -9240,22 +10039,26 @@ var init_fonts = __esm({
     init_src4();
     init_src7();
     init_output();
+    init_invocation();
   }
 });
 
 // packages/cli/src/font-guidance.ts
+import path32 from "node:path";
 function fontsUnprovenRemediation(setDir) {
-  if (setDir !== void 0) {
+  const set = setDir === void 0 ? void 0 : path32.resolve(setDir);
+  if (set !== void 0) {
     try {
-      const needs = recordedFontNeeds(setDir);
+      const needs = recordedFontNeeds(set);
       if (needs.length > 0) {
         const families = needs.map((n) => `"${n.family}"`).join(", ");
-        return `Run \`tendril fonts resolve --set ${setDir}\` \u2014 the recording declares ${families}; faces land in ${DEFAULT_FONT_CACHE}.`;
+        return `Run \`${tendrilCommand(`fonts resolve --set ${set}`)}\` \u2014 the recording declares ${families}; faces land in ${DEFAULT_FONT_CACHE}.`;
       }
     } catch {
     }
   }
-  return `Run \`tendril fonts resolve --set <recording-dir>\` (or \`tendril fonts resolve "<Family>" --weights 400 500 600\`) to populate the font cache \u2014 the cache read is ${DEFAULT_FONT_CACHE}.`;
+  const target = set ?? "<recording-dir>";
+  return `Run \`${tendrilCommand(`fonts resolve --set ${target}`)}\` (or \`${tendrilCommand('fonts resolve "<Family>" --weights 400 500 600')}\`) to populate the font cache \u2014 the cache read is ${DEFAULT_FONT_CACHE}.`;
 }
 function taskFontFamilies(setDir) {
   try {
@@ -9301,18 +10104,27 @@ var init_font_guidance = __esm({
     "use strict";
     init_src4();
     init_src7();
+    init_invocation();
   }
 });
 
 // packages/cli/src/commands/verify.ts
 var verify_exports = {};
 __export(verify_exports, {
+  NO_ROLE_MANIFEST: () => NO_ROLE_MANIFEST,
+  ROLES_NOT_RESOLVED: () => ROLES_NOT_RESOLVED,
+  checkSummarySegments: () => checkSummarySegments,
+  compositionReport: () => compositionReport,
+  eyeCheck: () => eyeCheck,
+  failureTally: () => failureTally,
   foldConfigStatus: () => foldConfigStatus,
   interactionCoverage: () => interactionCoverage,
+  occlusionReport: () => occlusionReport,
+  resolveComposition: () => resolveComposition,
   runVerify: () => runVerify
 });
-import { existsSync as existsSync25, readFileSync as readFileSync22 } from "node:fs";
-import path31 from "node:path";
+import { existsSync as existsSync26, readFileSync as readFileSync22 } from "node:fs";
+import path33 from "node:path";
 function interactionCoverage(behaviors) {
   const interaction = behaviors.filter((b) => !b.id.startsWith("prelude:"));
   return {
@@ -9342,12 +10154,68 @@ function foldConfigStatus(s, failDemotions, substitutedFamilies) {
     absentInkDemoted
   };
 }
+function resolveComposition(raw) {
+  if (raw === void 0) return NO_ROLE_MANIFEST;
+  const parsed = RolesSchema.safeParse(raw);
+  if (parsed.success) return { roles: parsed.data };
+  const why = parsed.error.issues.slice(0, 3).map((i) => `${i.path.join(".") === "" ? "roles" : i.path.join(".")}: ${i.message}`).join("; ");
+  return {
+    short: "roles block REJECTED",
+    unavailable: `the recording set's roles block was REJECTED by the schema (${why}) \u2014 composition (structural + crop) was NEVER CHECKED`,
+    warn: `recording set roles block REJECTED (${why}) \u2014 the composition checks (structural + crop) did NOT run, while the set still reads as role-confirmed. This is an instrument failure, not a clean bill. Repair the set's roles block and re-verify.`
+  };
+}
+function rolesSourceLabel(roles) {
+  return roles.rolesSource === "human-override" ? "HUMAN-OVERRIDE" : roles.rolesSource ?? UNSTAMPED_ROLES;
+}
+function checkSummarySegments(input) {
+  const tally = (rows) => `${rows.filter((r) => r.pass).length}/${rows.length}`;
+  const { availability } = input;
+  const composition = availability.unavailable !== void 0 ? `composition NOT CHECKED (${availability.short})` : `composition ${tally(input.structural)} structural, ${input.crops !== void 0 ? `${tally(input.crops)} crops` : "crops unavailable"} (roles: ${rolesSourceLabel(availability.roles)}${(availability.roles.narrowingAccepted ?? []).length > 0 ? `, ${(availability.roles.narrowingAccepted ?? []).length} narrowing(s) accepted: ${(availability.roles.narrowingAccepted ?? []).join(", ")}` : ""})`;
+  const occ = occlusionReport(input.occlusion);
+  const occlusion = "unavailable" in occ ? `occlusion not applicable (${NO_OVERLAY_DECLARED})` : `occlusion ${tally(input.occlusion)}`;
+  return ` \xB7 ${composition} \xB7 ${occlusion}`;
+}
+function occlusionReport(occlusion) {
+  if (occlusion.length === 0) {
+    return {
+      unavailable: "the bundle declares no overlay (no open-state config and no prelude popover) \u2014 the sibling-occlusion check DOES NOT APPLY and nothing about overlay stacking was measured; an empty check list is this state, not a clean bill"
+    };
+  }
+  return { checks: occlusion.length, passed: occlusion.filter((o) => o.pass).length };
+}
+function compositionReport(input) {
+  const { availability, regions } = input;
+  if (availability.unavailable !== void 0) return { unavailable: availability.unavailable };
+  const cropsUnavailable = regions !== void 0 && "unavailable" in regions ? regions.unavailable : "interior geometry was never computed for this run";
+  return {
+    rolesSource: availability.roles.rolesSource ?? UNSTAMPED_ROLES,
+    // Each token is a derived main, or a part→main edge, that a human
+    // signed away at confirm time. Every one of them REMOVES something
+    // the structural check would otherwise have had to satisfy, so the
+    // list belongs beside the pass it enabled — not only in the manifest
+    // that recorded it.
+    narrowingAccepted: availability.roles.narrowingAccepted ?? [],
+    structural: input.structural,
+    crops: input.crops ?? { unavailable: cropsUnavailable }
+  };
+}
+function eyeCheck(bundleDir) {
+  return {
+    command: tendrilCommand(`inspect "${bundleDir}"`),
+    sheetPath: path33.join(bundleDir, "verify-evidence", "inspect.html"),
+    note: "magnified recorded-vs-rendered crops of every small node; scores cannot see shape. The command WRITES/refreshes the sheet at sheetPath \u2014 re-run it after every verify; an existing sheet may show stale crops."
+  };
+}
+function failureTally(t) {
+  return `${t.configs.length} config(s), ${t.behaviors.length} behavior(s), ${t.structural.length + t.crops.length} composition check(s), ${t.occlusion.length} occlusion check(s) below the ${t.bar} bar${t.evidenceUnverified ? "; PLUS the interaction-evidence instrument gate failed (operability could not be verified \u2014 see FAIL interaction-evidence above)" : ""} \u2014 bundle written, verdict honest (Q4)`;
+}
 function taskFromManifest(opts, manifest, setDir) {
   const recordedSlugs = loadManifest(setDir).reps.map((r) => r.slug);
   const adapterSlugs = Object.keys(manifest.propAdapter);
   const unmapped = recordedSlugs.filter((s) => !adapterSlugs.includes(s));
   const adapterOnly = adapterSlugs.filter((s) => !recordedSlugs.includes(s));
-  const registry = Object.values(TASKS).find((t) => path31.resolve(t.set) === path31.resolve(setDir));
+  const registry = Object.values(TASKS).find((t) => path33.resolve(t.set) === path33.resolve(setDir));
   const authored = (() => {
     if (registry !== void 0) return void 0;
     try {
@@ -9356,7 +10224,7 @@ function taskFromManifest(opts, manifest, setDir) {
       fail(opts, ExitCode.InputValidation, {
         error: `cannot author the verification task from ${setDir}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
         code: "AUTHORING_FAILED",
-        remediation: "Fix the recording set (duplicate/colliding poses fail authoring by design \u2014 check `tendril record status` and the set's variant names)."
+        remediation: `Fix the recording set (duplicate/colliding poses fail authoring by design \u2014 check \`${tendrilCommand(`record status --set ${setDir}`)}\` and the set's variant names).`
       });
     }
   })();
@@ -9379,18 +10247,18 @@ function taskFromManifest(opts, manifest, setDir) {
 }
 async function runVerify(opts) {
   const callerCwd = process.env["INIT_CWD"] ?? process.cwd();
-  const setOverride = opts.set !== void 0 ? path31.resolve(callerCwd, opts.set) : void 0;
-  opts = { ...opts, bundleDir: path31.resolve(callerCwd, opts.bundleDir), ...setOverride !== void 0 ? { set: setOverride } : {} };
-  if (!existsSync25(opts.bundleDir)) {
+  const setOverride = opts.set !== void 0 ? path33.resolve(callerCwd, opts.set) : void 0;
+  opts = { ...opts, bundleDir: path33.resolve(callerCwd, opts.bundleDir), ...setOverride !== void 0 ? { set: setOverride } : {} };
+  if (!existsSync26(opts.bundleDir)) {
     fail(opts, ExitCode.InputValidation, {
       error: `bundle directory not found: ${opts.bundleDir}`,
       code: "bundle-missing",
       remediation: "Point at a generated bundle directory (containing component.json, the entry module, and styles.css)."
     });
   }
-  const manifestPath2 = path31.join(opts.bundleDir, "component.json");
+  const manifestPath2 = path33.join(opts.bundleDir, "component.json");
   let manifest;
-  if (existsSync25(manifestPath2)) {
+  if (existsSync26(manifestPath2)) {
     const { manifest: parsed, issues } = readBundleManifest(readFileSync22(manifestPath2, "utf8"));
     if (issues.length > 0) {
       fail(opts, ExitCode.InputValidation, {
@@ -9405,7 +10273,7 @@ async function runVerify(opts) {
   let unmapped = [];
   let interactionEvidence = [];
   let unmappedInteractionEvidence = [];
-  let roles;
+  let availability = ROLES_NOT_RESOLVED;
   if (opts.task !== void 0) {
     const registry = TASKS[opts.task];
     if (registry === void 0) {
@@ -9418,21 +10286,21 @@ async function runVerify(opts) {
     task = registry;
   } else if (manifest !== void 0) {
     const resolveSetDir = (p) => {
-      if (path31.isAbsolute(p)) return p;
-      const fromRepo = path31.resolve(REPO_ROOT, p);
-      if (existsSync25(fromRepo)) return fromRepo;
-      return path31.resolve(callerCwd, p);
+      if (path33.isAbsolute(p)) return p;
+      const fromRepo = path33.resolve(REPO_ROOT, p);
+      if (existsSync26(fromRepo)) return fromRepo;
+      return path33.resolve(callerCwd, p);
     };
     const setDir = opts.set ?? resolveSetDir(manifest.provenance.recordingSet.path);
-    if (!existsSync25(path31.join(setDir, "recording-set.json")) && !Object.values(TASKS).some((t) => path31.resolve(t.set) === path31.resolve(setDir))) {
+    if (!existsSync26(path33.join(setDir, "recording-set.json")) && !Object.values(TASKS).some((t) => path33.resolve(t.set) === path33.resolve(setDir))) {
       fail(opts, ExitCode.RecordingIncomplete, {
         error: `recording set not found or unmanifested: ${setDir}`,
         code: "recording-set-missing",
         remediation: "Pass --set <dir> pointing at the recording set this bundle was generated from."
       });
     }
-    const registry = Object.values(TASKS).find((t) => path31.resolve(t.set) === path31.resolve(setDir));
-    if (registry !== void 0 && !existsSync25(path31.join(setDir, "recording-set.json"))) {
+    const registry = Object.values(TASKS).find((t) => path33.resolve(t.set) === path33.resolve(setDir));
+    if (registry !== void 0 && !existsSync26(path33.join(setDir, "recording-set.json"))) {
       const recordedSlugs = registry.configs.map((c) => c.rep);
       const adapterSlugs = Object.keys(manifest.propAdapter);
       unmapped = recordedSlugs.filter((s) => !adapterSlugs.includes(s));
@@ -9448,16 +10316,16 @@ async function runVerify(opts) {
       interactionEvidence = built.interactionEvidence;
       unmappedInteractionEvidence = built.unmappedInteractionEvidence;
       for (const s of built.adapterOnly) warn(opts, `prop adapter maps "${s}" which is not in the recording set \u2014 ignored`);
-      const rolesParse = RolesSchema.safeParse(loadManifest(setDir).roles);
-      if (rolesParse.success) roles = rolesParse.data;
+      availability = resolveComposition(loadManifest(setDir).roles);
+      if (availability.warn !== void 0) warn(opts, availability.warn);
     }
     const hash = recordingSetHash(setDir, task.configs);
     if (hash !== manifest.provenance.recordingSet.hash) {
       warn(opts, `recording set content differs from the bundle's provenance stamp (${hash.slice(0, 12)}\u2026 vs ${manifest.provenance.recordingSet.hash.slice(0, 12)}\u2026) \u2014 scores apply to the CURRENT set`);
     }
     for (const name of [manifest.entry, "styles.css", "tokens.css"]) {
-      const p = path31.join(opts.bundleDir, name);
-      if (!existsSync25(p)) continue;
+      const p = path33.join(opts.bundleDir, name);
+      if (!existsSync26(p)) continue;
       const issues = checkBundleSourceFile(name, new Uint8Array(readFileSync22(p)));
       if (issues.length > 0) {
         fail(opts, ExitCode.InputValidation, {
@@ -9474,6 +10342,7 @@ async function runVerify(opts) {
       remediation: `Regenerate the bundle (bundle v1 carries its prop manifest), or pass --task <${Object.keys(TASKS).join("|")}> for legacy bundles.`
     });
   }
+  const roles = availability.roles;
   if (!fontsResolved()) {
     fail(opts, ExitCode.FontsUnproven, {
       error: "resolved font cache absent \u2014 verification under system font substitution is refused",
@@ -9481,8 +10350,8 @@ async function runVerify(opts) {
       remediation: fontsUnprovenRemediation(task.set)
     });
   }
-  if (lcdTextDisabled()) {
-    warn(opts, "EXPERIMENT override active (TENDRIL_DISABLE_LCD_TEXT=1): text renders greyscale \u2014 scores are NOT comparable to default runs; the environment stamp and report are marked");
+  if (lcdTextEnabled()) {
+    warn(opts, "EXPERIMENT override active (TENDRIL_ENABLE_LCD_TEXT=1): text renders with platform LCD antialiasing instead of canonical greyscale \u2014 scores are NOT comparable to default runs; the environment stamp and report are marked");
   }
   const substitutedFamilies = unprovisionedFamilies(task.set);
   if (substitutedFamilies.length > 0) {
@@ -9495,7 +10364,7 @@ async function runVerify(opts) {
     warn(opts, `font weights (advisory): the recording implies weights ${g.declared.join(", ")} for "${g.family}" \u2014 cache provides ${g.provided.join(", ")}; nearest-weight rendering may shift stroke density (certification stays family-gated; implied weights can leak across families)`);
   }
   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"))
+    (c) => !existsSync26(path33.join(task.set, c.rep, "get_screenshot.json")) || !existsSync26(path33.join(task.set, c.rep, "get_metadata.json"))
   );
   if (missing.length > 0) {
     fail(opts, ExitCode.RecordingIncomplete, {
@@ -9505,10 +10374,10 @@ async function runVerify(opts) {
     });
   }
   const bar = BARS2[opts.bar];
-  const evidenceDir = path31.join(opts.bundleDir, "verify-evidence");
+  const evidenceDir = path33.join(opts.bundleDir, "verify-evidence");
   const scores = await scoreBundleForTask(task, opts.bundleDir, bar, { evidenceDir, onProgress: emitProgress });
   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 bundleCss = ["tokens.css", "styles.css"].map((f) => path33.join(opts.bundleDir, f)).filter((f) => existsSync26(f)).map((f) => readFileSync22(f, "utf8")).join("\n");
   const occlusion = await checkSiblingOcclusion(task, opts.bundleDir, bundleCss);
   const parity = await checkHoverParity(task, opts.bundleDir);
   const behaviors = [...await checkBehaviors(task, opts.bundleDir), ...parity];
@@ -9548,7 +10417,10 @@ async function runVerify(opts) {
     ...opts.task !== void 0 ? { task: opts.task } : {},
     ...manifest !== void 0 ? { bundleManifest: { name: manifest.name, bundleVersion: manifest.bundleVersion, recordingSetHash: manifest.provenance.recordingSet.hash } } : {},
     targetBar: opts.bar,
-    environment: environmentStamp(taskFontFamilies(task.set)),
+    // Canonical mount semantics are VERSION-scoped (0.1.22 review: the
+    // greyscale flip changed Windows pixels under an identical-looking
+    // stamp) — the ruler version is part of the comparability key.
+    environment: { ...environmentStamp(taskFontFamilies(task.set)), ruler: cliVersion() },
     coverage: {
       scoredConfigs: statuses.length,
       certified,
@@ -9590,31 +10462,22 @@ async function runVerify(opts) {
     // silently inherited neither.
     quality: { findings: quality.findings, tokensAbsent: quality.tokensAbsent },
     occlusion,
+    // The rows' STATE, which the rows alone cannot carry (see
+    // occlusionReport): the agent channel had no counterpart to the
+    // human line's "occlusion not applicable (no overlay declared)".
+    occlusionCheck: occlusionReport(occlusion),
     configs: statuses,
     behaviors,
     evidence: { dir: evidenceDir, files: "per config: <rep>-render.png, <rep>-ref.png, <rep>-diff.png" },
-    ...roles !== void 0 ? {
-      composition: {
-        structural,
-        crops: crops ?? { unavailable: regionsOut !== void 0 && "unavailable" in regionsOut ? regionsOut.unavailable : "no role manifest" }
-      }
-    } : {},
+    composition: compositionReport({ availability, structural, crops, regions: regionsOut }),
     verdict: ok ? "verified" : "verification-failed",
     // Machine-readable cause (adversarial review): a cert-bar failure
     // with zero pixel/behavior/composition failures was only
     // explainable from stderr prose.
     ...certBlockedByAbsentInk.length > 0 ? { certBlockedByAbsentInk } : {},
     ...weightGaps.length > 0 ? { fontWeightGaps: weightGaps } : {},
-    ...lcdTextDisabled() ? { environmentOverrides: ["disable-lcd-text"] } : {},
-    // Run 13 finding 1: the eye-check nudge lived only in the human
-    // footer, so MCP-driven agents — the documented path — were never
-    // told the check exists and shipped without ever opening a sheet.
-    // Structured here so every consumer sees it.
-    eyeCheck: {
-      command: `tendril inspect "${opts.bundleDir}"`,
-      sheetPath: path31.join(opts.bundleDir, "verify-evidence", "inspect.html"),
-      note: "magnified recorded-vs-rendered crops of every small node; scores cannot see shape. The command WRITES/refreshes the sheet at sheetPath \u2014 re-run it after every verify; an existing sheet may show stale crops."
-    }
+    ...lcdTextEnabled() ? { environmentOverrides: ["enable-lcd-text"] } : {},
+    eyeCheck: eyeCheck(opts.bundleDir)
   };
   emitData(opts, report, () => {
     for (const s of statuses) {
@@ -9636,17 +10499,22 @@ async function runVerify(opts) {
       process.stdout.write(`${o.pass ? "PASS" : "FAIL"}      ${o.id}${o.detail !== void 0 ? `  [${o.detail}]` : ""}
 `);
     }
-    if (crops !== void 0) {
+    if (availability.unavailable !== void 0) {
+      process.stdout.write(`UNAVAILABLE composition \u2014 ${availability.unavailable}
+`);
+    } else if (crops !== void 0) {
       for (const c of crops) process.stdout.write(`${c.pass ? "PASS" : "FAIL"}      ${c.id} sim=${c.similarity} ink=${c.inkRecall}${c.detail !== void 0 ? `  [${c.detail}]` : ""}
 `);
-    } else if (roles !== void 0 && regionsOut !== void 0 && "unavailable" in regionsOut) {
+    } else if (regionsOut !== void 0 && "unavailable" in regionsOut) {
       process.stdout.write(`UNAVAILABLE composition crops \u2014 ${regionsOut.unavailable}
 `);
     }
     const ic = interactionCoverage(behaviors);
     process.stdout.write(
       `
-${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuses.length} \u2265 pass bar \xB7 behaviors ${behaviors.length - behaviorFailures.length}/${behaviors.length}${roles !== void 0 ? ` \xB7 composition ${structural.length - structuralFailures.length}/${structural.length} structural${crops !== void 0 ? `, ${crops.length - cropFailures.length}/${crops.length} crops` : ", crops unavailable"}` : ""}
+${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuses.length} \u2265 pass bar \xB7 behaviors ${behaviors.length - behaviorFailures.length}/${behaviors.length}${checkSummarySegments(
+        { availability, structural, crops, occlusion }
+      )}
 `
     );
     const QUALITY_SHOWN = 8;
@@ -9703,18 +10571,20 @@ ${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")));
+    const shippedFonts = requiredFontsManifest(cssFontFamilies(["styles.css", "tokens.css"].map((f) => path33.join(opts.bundleDir, f)).filter((f) => existsSync26(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)
 `);
     }
     for (const g of weightGaps) {
-      process.stdout.write(`fonts (weight gap): "${g.family}" declares ${g.declared.join(", ")} \u2014 cache provides ${g.provided.join(", ")}; nearest-weight rendering may shift stroke density (advisory, never a gate). Fix: tendril fonts resolve --set ${task.set}
-`);
+      process.stdout.write(
+        `fonts (weight gap): "${g.family}" declares ${g.declared.join(", ")} \u2014 cache provides ${g.provided.join(", ")}; nearest-weight rendering may shift stroke density (advisory, never a gate). Fix: ${tendrilCommand(`fonts resolve --set ${task.set}`)}
+`
+      );
     }
     process.stdout.write(`evidence: ${evidenceDir} (render/ref/diff per config)
 `);
-    process.stdout.write(`eye check: tendril inspect "${opts.bundleDir}" \u2014 magnified recorded-vs-rendered crops of every small node; scores cannot see shape (re-run after every verify)
+    process.stdout.write(`eye check: ${report.eyeCheck.command} \u2014 magnified recorded-vs-rendered crops of every small node; scores cannot see shape (re-run after every verify)
 `);
   });
   if (opts.bar === "cert" && substitutedFamilies.length > 0) {
@@ -9741,12 +10611,20 @@ ${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuse
   if (!okExceptDemotion) {
     warn(
       opts,
-      `${pixelFailures.length} config(s), ${behaviorFailures.length} behavior(s), ${structuralFailures.length + cropFailures.length + occlusionFailures.length} composition check(s) below the ${opts.bar} bar${evidenceUnverified ? "; PLUS the interaction-evidence instrument gate failed (operability could not be verified \u2014 see FAIL interaction-evidence above)" : ""} \u2014 bundle written, verdict honest (Q4)`
+      failureTally({
+        configs: pixelFailures,
+        behaviors: behaviorFailures,
+        structural: structuralFailures,
+        crops: cropFailures,
+        occlusion: occlusionFailures,
+        bar: opts.bar,
+        evidenceUnverified
+      })
     );
     process.exitCode = ExitCode.VerificationFailed;
   }
 }
-var BARS2;
+var BARS2, NO_ROLE_MANIFEST, ROLES_NOT_RESOLVED, UNSTAMPED_ROLES, NO_OVERLAY_DECLARED;
 var init_verify = __esm({
   "packages/cli/src/commands/verify.ts"() {
     "use strict";
@@ -9757,11 +10635,22 @@ var init_verify = __esm({
     init_src4();
     init_environment();
     init_font_guidance();
+    init_invocation();
     init_output();
     BARS2 = {
       pass: { sim: 0.95, ink: 0.95 },
       cert: { sim: 0.97, ink: 0.95 }
     };
+    NO_ROLE_MANIFEST = Object.freeze({
+      short: "no role manifest",
+      unavailable: "the recording set declares no role manifest \u2014 composition (structural + crop) was NEVER CHECKED; nothing here says the main renders the SHIPPED part modules rather than a pixel-identical re-implementation"
+    });
+    ROLES_NOT_RESOLVED = Object.freeze({
+      short: "roles never resolved on this path",
+      unavailable: "this run never resolved a role manifest \u2014 the legacy --task adapter and pre-manifest reference sets skip the set's roles block entirely, so composition (structural + crop) was NEVER CHECKED and the set was never asked what it declares; nothing here says the main renders the SHIPPED part modules rather than a pixel-identical re-implementation"
+    });
+    UNSTAMPED_ROLES = "unstamped";
+    NO_OVERLAY_DECLARED = "no overlay declared";
   }
 });
 
@@ -9771,36 +10660,36 @@ __export(engine_exports, {
   runEngineBrief: () => runEngineBrief,
   runEngineScore: () => runEngineScore
 });
-import { appendFileSync, existsSync as existsSync26, mkdirSync as mkdirSync8, readFileSync as readFileSync23, writeFileSync as writeFileSync12 } from "node:fs";
-import path32 from "node:path";
+import { appendFileSync, existsSync as existsSync27, mkdirSync as mkdirSync8, readFileSync as readFileSync23, writeFileSync as writeFileSync12 } from "node:fs";
+import path34 from "node:path";
 function resolveEngineTask(opts, callerCwd) {
-  const asPath = path32.resolve(callerCwd, opts.taskOrSet);
-  const isSet = existsSync26(path32.join(asPath, "recording-set.json"));
+  const asPath = path34.resolve(callerCwd, opts.taskOrSet);
+  const isSet = existsSync27(path34.join(asPath, "recording-set.json"));
   const registry = TASKS[opts.taskOrSet];
-  if (registry !== void 0 && !isSet) return { task: registry, name: opts.taskOrSet, disclosures: [], interactionEvidence: [] };
+  if (registry !== void 0 && !isSet) return { task: registry, name: opts.taskOrSet, ref: opts.taskOrSet, disclosures: [], interactionEvidence: [] };
   if (isSet) {
     try {
       const authored = authorTaskFromSet(asPath);
       for (const d of authored.disclosures) warn(opts, d);
-      return { task: authored.task, name: path32.basename(asPath), disclosures: authored.disclosures, interactionEvidence: authored.api.interactionEvidence, apiPin: { props: authored.api.apiPin.props, forcedStates: authored.api.apiPin.forcedStates } };
+      return { task: authored.task, name: path34.basename(asPath), ref: asPath, disclosures: authored.disclosures, interactionEvidence: authored.api.interactionEvidence, apiPin: { props: authored.api.apiPin.props, forcedStates: authored.api.apiPin.forcedStates } };
     } catch (err) {
       fail(opts, ExitCode.InputValidation, {
         error: `cannot author a task from ${asPath}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
         code: "AUTHORING_FAILED",
-        remediation: "Complete the recording set (tendril record status) or use a reference task name."
+        remediation: `Complete the recording set (${tendrilCommand(`record status --set ${asPath}`)}) or use a reference task name.`
       });
     }
   }
   fail(opts, ExitCode.InputValidation, {
     error: `"${opts.taskOrSet}" is neither a reference task nor a recorded set`,
     code: "UNKNOWN_RECORDED_INPUT",
-    remediation: `Pick a task (${Object.keys(TASKS).join(", ")}) or point at a set recorded with \`tendril record\`.`
+    remediation: `Pick a task (${Object.keys(TASKS).join(", ")}) or point at a set recorded with \`${tendrilCommand("record plan")}\`.`
   });
 }
 function runEngineBrief(opts) {
   requireEntitlement(opts);
   const callerCwd = process.env["INIT_CWD"] ?? process.cwd();
-  const { task, name, disclosures } = resolveEngineTask(opts, callerCwd);
+  const { task, name, ref, disclosures } = resolveEngineTask(opts, callerCwd);
   const bar = BARS3[opts.bar];
   const disclosureBlock = disclosures.length > 0 ? `
 
@@ -9809,8 +10698,8 @@ ${disclosures.map((d) => `- ${d}`).join("\n")}` : "";
   const brief = buildBrief(task.systemApi, bar, { colorScheme: recordingIsDark(task) ? "dark" : "light" }) + disclosureBlock;
   const segments = buildSegments(task, "files");
   let notRecorded;
-  const manifestPath2 = path32.join(task.set, "recording-set.json");
-  if (existsSync26(manifestPath2)) {
+  const manifestPath2 = path34.join(task.set, "recording-set.json");
+  if (existsSync27(manifestPath2)) {
     notRecorded = JSON.parse(readFileSync23(manifestPath2, "utf8")).notRecorded;
   }
   const unverified = notRecorded !== void 0 && notRecorded !== "" ? `
@@ -9819,7 +10708,7 @@ ${disclosures.map((d) => `- ${d}`).join("\n")}` : "";
 DO NOT INVENT PIXELS FOR THESE POSES. Implement them ONLY as the composition of recorded per-axis truth (the custom-property composition rule: one paint axis sets variables, the other consumes) and list every such pose in your report as UNRECORDED-COMPOSED. Recording them is the real fix: re-plan the set (full matrix is the default) and record the missing poses.
 ${notRecorded}` : "";
   let fontProvisioning;
-  if (existsSync26(manifestPath2)) {
+  if (existsSync27(manifestPath2)) {
     const missingFams = unprovisionedFamilies(task.set);
     const unprovided = unprovisionedFaces(task.set);
     const weightOnly = missingFams.length === 0;
@@ -9827,16 +10716,17 @@ ${notRecorded}` : "";
       const names = unprovided.map((f) => `'${f}'`).join(", ");
       const PROPRIETARY = /^(sf pro|sf compact|sf mono|new york|pingfang|segoe ui|helvetica neue|proxima nova|avenir)/i;
       const allProprietary = unprovided.every((f) => PROPRIETARY.test(f.trim()));
+      const resolveCommand = tendrilCommand(`fonts resolve --set ${task.set}`);
       fontProvisioning = {
         unprovided,
         question: {
           prompt: weightOnly ? `This design implies font ${unprovided.length === 1 ? "weight" : "weights"} the local kit lacks: ${names} (the ${missingFams.length === 0 && unprovided.length === 1 ? "family itself is" : "families themselves are"} provisioned). How should it be handled?` : `This design's text uses ${names}, which is not in the local font kit. How should it be handled?`,
           options: [
-            allProprietary && !weightOnly ? `(Recommended) ${names} ${unprovided.length === 1 ? "is a proprietary face" : "are proprietary faces"} \u2014 Google Fonts cannot serve ${unprovided.length === 1 ? "it" : "them"}, so skip \`fonts resolve\`: run \`tendril fonts add "<Family>" <weight> <file>\` with the .woff2/.ttf/.otf you hold a licence for (the file never leaves this machine), then re-run this brief \u2014 exact text fidelity.` : `(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.`,
+            allProprietary && !weightOnly ? `(Recommended) ${names} ${unprovided.length === 1 ? "is a proprietary face" : "are proprietary faces"} \u2014 Google Fonts cannot serve ${unprovided.length === 1 ? "it" : "them"}, so skip \`fonts resolve\`: run \`${tendrilCommand('fonts add "<Family>" <weight> <file>')}\` with the .woff2/.ttf/.otf you hold a licence for (the file never leaves this machine), then re-run this brief \u2014 exact text fidelity.` : `(Recommended) Run \`${resolveCommand}\` \u2014 open-source families are fetched automatically. Any face that fails there is one you license privately: run \`${tendrilCommand('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.`,
             weightOnly ? "Continue with nearest-weight rendering: the family is provisioned, certification remains possible, and the gap rides the report as an advisory (fontWeightGaps); resolving removes it." : '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: weightOnly ? `Run \`tendril fonts resolve --set ${task.set}\` if quick, or continue \u2014 the weight gap is an advisory, never a gate.` : 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."
+        nonInteractive: weightOnly ? `Run \`${resolveCommand}\` if quick, or continue \u2014 the weight gap is an advisory, never a gate.` : opts.bar === "cert" ? `Resolve the families first (\`${resolveCommand}\`) \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."
       };
     }
   }
@@ -9844,8 +10734,8 @@ ${notRecorded}` : "";
 
 === TASK PAYLOAD (recorded truth, verbatim) ===
 ${segments}`;
-  const payloadFile = path32.resolve(callerCwd, opts.out ?? `tendril-out/${name}-brief.md`);
-  mkdirSync8(path32.dirname(payloadFile), { recursive: true });
+  const payloadFile = path34.resolve(callerCwd, opts.out ?? `tendril-out/${name}-brief.md`);
+  mkdirSync8(path34.dirname(payloadFile), { recursive: true });
   writeFileSync12(payloadFile, payload);
   emitData(
     opts,
@@ -9874,7 +10764,7 @@ ${segments}`;
         "Settle the proposer model (see modelSelection \u2014 ask the user when one is present), then:",
         `Read ${payloadFile} completely \u2014 it is the system brief plus every recorded config's emission, box, and assets.`,
         `Write the complete bundle files (${task.entry}, styles.css, optional tokens.css) into a candidate directory.`,
-        `Run \`tendril engine score ${name} <candidateDir> --bar ${opts.bar} --model ${opts.model ?? "<declared-model>"} --json\` \u2014 the CLI is the sole judge, and it refuses to score an undeclared model.`,
+        `Run \`${tendrilCommand(`engine score ${ref} <candidateDir> --bar ${opts.bar} --model ${opts.model ?? "<declared-model>"} --json`)}\` \u2014 the CLI is the sole judge, and it refuses to score an undeclared model.`,
         "Apply the returned feedback and re-score. Stop when all checks pass or two consecutive scores fail to improve.",
         "Never edit recording sets; never claim scores yourself \u2014 only the score command's output counts."
       ]
@@ -9887,18 +10777,23 @@ ${segments}`;
     }
   );
 }
+function appendScoreHistory(candidateDir, entry) {
+  appendFileSync(path34.join(candidateDir, "score-history.jsonl"), `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
+`);
+}
 async function runEngineScore(opts) {
   requireEntitlement(opts);
   const callerCwd = process.env["INIT_CWD"] ?? process.cwd();
-  const candidateDir = path32.resolve(callerCwd, opts.candidateDir);
+  const candidateDir = path34.resolve(callerCwd, opts.candidateDir);
   const { task, name, apiPin, interactionEvidence } = resolveEngineTask(opts, callerCwd);
-  if (!existsSync26(candidateDir)) {
+  if (!existsSync27(candidateDir)) {
     fail(opts, ExitCode.InputValidation, {
       error: `candidate directory not found: ${candidateDir}`,
       code: "candidate-missing",
       remediation: `Write ${task.entry} and styles.css into a directory and pass it.`
     });
   }
+  appendScoreHistory(candidateDir, { event: "round-start", bar: opts.bar });
   if (!fontsResolved()) {
     fail(opts, ExitCode.FontsUnproven, {
       error: "resolved font cache absent \u2014 scoring under system font substitution is refused",
@@ -9906,8 +10801,8 @@ async function runEngineScore(opts) {
       remediation: fontsUnprovenRemediation(task.set)
     });
   }
-  if (lcdTextDisabled()) {
-    warn(opts, "EXPERIMENT override active (TENDRIL_DISABLE_LCD_TEXT=1): text renders greyscale \u2014 scores are NOT comparable to default runs; the environment stamp and report are marked");
+  if (lcdTextEnabled()) {
+    warn(opts, "EXPERIMENT override active (TENDRIL_ENABLE_LCD_TEXT=1): text renders with platform LCD antialiasing instead of canonical greyscale \u2014 scores are NOT comparable to default runs; the environment stamp and report are marked");
   }
   const substitutedFamilies = unprovisionedFamilies(task.set);
   if (substitutedFamilies.length > 0) {
@@ -9916,10 +10811,10 @@ async function runEngineScore(opts) {
   for (const g of missingWeights(task.set)) {
     warn(opts, `font weights (advisory): the recording implies weights ${g.declared.join(", ")} for "${g.family}" \u2014 cache provides ${g.provided.join(", ")}; nearest-weight rendering may shift stroke density (certification stays family-gated; implied weights can leak across families)`);
   }
-  if (opts.rebind !== true && existsSync26(path32.join(candidateDir, "component.json"))) {
+  if (opts.rebind !== true && existsSync27(path34.join(candidateDir, "component.json"))) {
     const prior = (() => {
       try {
-        const read = readBundleManifest(readFileSync23(path32.join(candidateDir, "component.json"), "utf8"));
+        const read = readBundleManifest(readFileSync23(path34.join(candidateDir, "component.json"), "utf8"));
         return read.manifest === void 0 ? { unreadable: true } : { hash: read.manifest.provenance.recordingSet.hash, path: read.manifest.provenance.recordingSet.path };
       } catch {
         return { unreadable: true };
@@ -9941,7 +10836,7 @@ async function runEngineScore(opts) {
     }
   }
   const bar = BARS3[opts.bar];
-  const evidenceDir = path32.join(candidateDir, "verify-evidence");
+  const evidenceDir = path34.join(candidateDir, "verify-evidence");
   const scores = await scoreBundleForTask(task, candidateDir, bar, { evidenceDir, onProgress: emitProgress });
   const parity = await checkHoverParity(task, candidateDir);
   const behaviors = [...await checkBehaviors(task, candidateDir), ...parity];
@@ -9984,11 +10879,7 @@ METRIC DEADBAND (read before iterating on near-misses): the scored similarity/in
     environment: environmentStamp(taskFontFamilies(task.set)),
     substitutedFamilies
   });
-  appendFileSync(
-    path32.join(candidateDir, "score-history.jsonl"),
-    `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), bar: opts.bar, pass: obj[0], total, certified: certifiedReps.length, floor: obj[1], mean: obj[2] })}
-`
-  );
+  appendScoreHistory(candidateDir, { event: "round-scored", bar: opts.bar, pass: obj[0], total, certified: certifiedReps.length, floor: obj[1], mean: obj[2] });
   emitData(
     opts,
     {
@@ -10008,7 +10899,8 @@ METRIC DEADBAND (read before iterating on near-misses): the scored similarity/in
       bundleManifest: emitted.written[0],
       note: "styles.css was stamped with the bundle provenance comment on line 1 \u2014 preserve it in any post-score edit",
       allPass,
-      ...lcdTextDisabled() ? { environmentOverrides: ["disable-lcd-text"] } : {},
+      environment: { ...environmentStamp(taskFontFamilies(task.set)), ruler: cliVersion() },
+      ...lcdTextEnabled() ? { environmentOverrides: ["enable-lcd-text"] } : {},
       // Run 11: generators read allPass:true and reported success on
       // bundles verify then FAILED on the interaction-evidence gate —
       // the oracle must say what verify will say, including this.
@@ -10062,6 +10954,7 @@ var init_engine2 = __esm({
     init_font_guidance();
     init_src4();
     init_output();
+    init_invocation();
     init_entitlement();
     init_verify();
     init_src4();
@@ -10077,11 +10970,11 @@ var codeconnect_exports = {};
 __export(codeconnect_exports, {
   runCodeConnect: () => runCodeConnect
 });
-import { existsSync as existsSync27, readFileSync as readFileSync24, writeFileSync as writeFileSync13 } from "node:fs";
-import path33 from "node:path";
+import { existsSync as existsSync28, readFileSync as readFileSync24, writeFileSync as writeFileSync13 } from "node:fs";
+import path35 from "node:path";
 function runCodeConnect(opts) {
   const callerCwd = process.env["INIT_CWD"] ?? process.cwd();
-  const bundleDir = path33.resolve(callerCwd, opts.bundleDir);
+  const bundleDir = path35.resolve(callerCwd, opts.bundleDir);
   let url;
   try {
     url = new URL(opts.figmaUrl);
@@ -10097,7 +10990,7 @@ function runCodeConnect(opts) {
   }
   let manifest;
   try {
-    const read = readBundleManifest(readFileSync24(path33.join(bundleDir, "component.json"), "utf8"));
+    const read = readBundleManifest(readFileSync24(path35.join(bundleDir, "component.json"), "utf8"));
     if (read.manifest === void 0) throw new Error(read.issues.map((i) => i.message).join("; ") || "no component.json");
     manifest = read.manifest;
   } catch (err) {
@@ -10107,8 +11000,8 @@ function runCodeConnect(opts) {
       remediation: "Point at a bundle produced by the Tendril pipeline (it carries component.json), and verify it first."
     });
   }
-  const setDir = path33.resolve(callerCwd, opts.set ?? manifest.provenance.recordingSet.path);
-  if (!existsSync27(path33.join(setDir, "recording-set.json"))) {
+  const setDir = path35.resolve(callerCwd, opts.set ?? manifest.provenance.recordingSet.path);
+  if (!existsSync28(path35.join(setDir, "recording-set.json"))) {
     fail(opts, ExitCode.InputValidation, {
       error: `recording set not found at ${setDir}`,
       code: "codeconnect-no-set",
@@ -10122,15 +11015,15 @@ function runCodeConnect(opts) {
     fail(opts, ExitCode.InputValidation, {
       error: `cannot author the API from ${setDir}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
       code: "codeconnect-authoring-failed",
-      remediation: "The set must be a complete protocol recording (tendril record status)."
+      remediation: `The set must be a complete protocol recording (${tendrilCommand(`record status --set ${setDir}`)}).`
     });
   }
   const api = authored.api;
   const component = api.component;
   const recManifest = loadManifest(setDir);
   const poseNames = recManifest.latticeNames ?? recManifest.reps.map((r) => {
-    const meta = path33.join(setDir, r.slug, "get_metadata.json");
-    if (!existsSync27(meta)) return void 0;
+    const meta = path35.join(setDir, r.slug, "get_metadata.json");
+    if (!existsSync28(meta)) return void 0;
     try {
       return /name="([^"]*)"/.exec(envelopeFirstTextPart(JSON.parse(readFileSync24(meta, "utf8"))))?.[1];
     } catch {
@@ -10149,7 +11042,7 @@ function runCodeConnect(opts) {
     fail(opts, ExitCode.InputValidation, {
       error: "the recording set's content no longer matches the hash this bundle was scored against \u2014 its verification claims describe a different recording",
       code: "codeconnect-set-drift",
-      remediation: "Re-run `tendril verify` (or engine score) against the current set, then re-emit."
+      remediation: `Re-run \`${tendrilCommand(`verify ${bundleDir} --set ${setDir}`)}\` (or engine score) against the current set, then re-emit.`
     });
   }
   const boolProps = api.props.filter((p) => p.kind === "boolean");
@@ -10190,7 +11083,7 @@ function runCodeConnect(opts) {
     axisLines.push(`const ${varName} = instance.getEnum(${q(axis)}, { ${entries.join(", ")} })`);
     fragmentVars.push(varName);
   }
-  const entryRel = path33.relative(callerCwd, path33.join(bundleDir, manifest.entry));
+  const entryRel = path35.relative(callerCwd, path35.join(bundleDir, manifest.entry));
   const trust = manifest.trustStatement.split("\n")[0] ?? "";
   const lines = [
     `// url=${opts.figmaUrl}`,
@@ -10211,7 +11104,7 @@ function runCodeConnect(opts) {
     `}`,
     ``
   ].join("\n");
-  const outFile = path33.resolve(callerCwd, opts.out ?? path33.join(bundleDir, `${component}.figma.ts`));
+  const outFile = path35.resolve(callerCwd, opts.out ?? path35.join(bundleDir, `${component}.figma.ts`));
   writeFileSync13(outFile, lines);
   emitData(
     opts,
@@ -10242,6 +11135,7 @@ var init_codeconnect = __esm({
     init_src7();
     init_src();
     init_src6();
+    init_invocation();
     init_output();
     kebab4 = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
     q = (s) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")}'`;
@@ -10250,17 +11144,17 @@ var init_codeconnect = __esm({
 
 // 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 { existsSync as existsSync29, 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 path36 from "node:path";
+import { fileURLToPath as fileURLToPath6 } from "node:url";
 import { z as z12 } from "zod";
 function sourceHash() {
-  const dir = path34.dirname(fileURLToPath5(import.meta.url));
+  const dir = path36.dirname(fileURLToPath6(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)));
+    h.update(readFileSync25(path36.join(dir, f)));
   }
   return h.digest("hex").slice(0, 16);
 }
@@ -10268,10 +11162,10 @@ 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] };
+    REPO_ROOT3 = path36.resolve(path36.dirname(fileURLToPath6(import.meta.url)), "..", "..", "..");
+    CLI_BIN = path36.join(REPO_ROOT3, "packages", "cli", "src", "bin.ts");
+    BUNDLED_CLI = path36.join(path36.dirname(fileURLToPath6(import.meta.url)), "tendril.js");
+    CLI_SPAWN = existsSync29(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 = [
@@ -10301,7 +11195,7 @@ var init_server = __esm({
           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");
+            const tmp = path36.join(mkdtempSync3(path36.join(os6.tmpdir(), "tendril-envelope-")), "response.txt");
             if (single !== void 0) {
               writeFileSync14(tmp, single);
               argvOut.push("--metadata-raw-file", tmp);
@@ -10372,7 +11266,7 @@ var init_server = __esm({
           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");
+            const tmp = path36.join(mkdtempSync3(path36.join(os6.tmpdir(), "tendril-envelope-")), "response.txt");
             if (single !== void 0) {
               writeFileSync14(tmp, single);
               argvOut.push(`--${label}-file`, tmp);
@@ -10415,7 +11309,7 @@ var init_server = __esm({
           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");
+          const tmp = path36.join(mkdtempSync3(path36.join(os6.tmpdir(), "tendril-envelope-")), "response.txt");
           if (text !== void 0) {
             writeFileSync14(tmp, text);
             return [...base, "--file", tmp, "--raw"];
@@ -10570,12 +11464,12 @@ __export(permissions_exports, {
   mergeAllowlist: () => mergeAllowlist,
   runPermissions: () => runPermissions
 });
-import { existsSync as existsSync29, mkdirSync as mkdirSync9, readFileSync as readFileSync26, writeFileSync as writeFileSync15 } from "node:fs";
+import { existsSync as existsSync30, mkdirSync as mkdirSync9, readFileSync as readFileSync26, writeFileSync as writeFileSync15 } from "node:fs";
 import os7 from "node:os";
-import path35 from "node:path";
+import path37 from "node:path";
 function mergeAllowlist(file, entries) {
   let settings = {};
-  if (existsSync29(file) && readFileSync26(file, "utf8").trim() !== "") {
+  if (existsSync30(file) && readFileSync26(file, "utf8").trim() !== "") {
     settings = JSON.parse(readFileSync26(file, "utf8"));
     if (settings === null || typeof settings !== "object" || Array.isArray(settings)) throw new Error("settings root is not an object");
   }
@@ -10588,7 +11482,7 @@ function mergeAllowlist(file, entries) {
   const alreadyPresent = entries.filter((e) => present.has(e));
   if (added.length > 0) {
     allow.push(...added);
-    mkdirSync9(path35.dirname(file), { recursive: true });
+    mkdirSync9(path37.dirname(file), { recursive: true });
     writeFileSync15(file, `${JSON.stringify(settings, null, 2)}
 `);
   }
@@ -10624,7 +11518,7 @@ async function runPermissions(flags) {
   const result = await buildPermissions({ ...flags.mcpUrl ? { mcpUrl: flags.mcpUrl } : {} });
   if (flags.write) {
     const base = process.env["INIT_CWD"] ?? process.cwd();
-    const file = flags.user ? path35.join(os7.homedir(), ".claude", "settings.json") : path35.join(base, ".claude", "settings.local.json");
+    const file = flags.user ? path37.join(os7.homedir(), ".claude", "settings.json") : path37.join(base, ".claude", "settings.local.json");
     if (flags.dryRun) {
       emitData(flags, { file, wouldAdd: result.toolEntries }, () => {
         process.stdout.write(`dry-run: would merge ${result.toolEntries.length} per-tool entries into ${file}
@@ -10657,7 +11551,7 @@ async function runPermissions(flags) {
       `Claude Code allowlist for the Tendril pipeline.
 One command installs it (project-local, idempotent):
 
-    tendril permissions --claude --write
+    ${tendrilCommand("permissions --claude --write")}
 
 Or paste into .claude/settings.json under permissions.allow:
 
@@ -10682,6 +11576,7 @@ var init_permissions = __esm({
     init_src();
     init_server();
     init_describe();
+    init_invocation();
     init_output();
     init_doctor();
     FIGMA_TOOL_FALLBACK = ["get_metadata", "get_design_context", "get_screenshot", "get_variable_defs", "get_motion_context", "get_figjam"];
@@ -10717,21 +11612,21 @@ __export(inspect_exports, {
   INSPECT_DESCRIPTION: () => INSPECT_DESCRIPTION,
   runInspect: () => runInspect
 });
-import { existsSync as existsSync30, readFileSync as readFileSync27, writeFileSync as writeFileSync16 } from "node:fs";
-import path36 from "node:path";
+import { existsSync as existsSync31, readFileSync as readFileSync27, writeFileSync as writeFileSync16 } from "node:fs";
+import path38 from "node:path";
 async function runInspect(opts) {
   if (opts.describe) {
     printDescription(INSPECT_DESCRIPTION);
     return;
   }
-  const bundleDir = path36.resolve(opts.bundleDir);
-  const evidenceDir = path36.join(bundleDir, "verify-evidence");
-  const manifestPath2 = path36.join(bundleDir, "component.json");
-  if (!existsSync30(evidenceDir) || !existsSync30(manifestPath2)) {
+  const bundleDir = path38.resolve(opts.bundleDir);
+  const evidenceDir = path38.join(bundleDir, "verify-evidence");
+  const manifestPath2 = path38.join(bundleDir, "component.json");
+  if (!existsSync31(evidenceDir) || !existsSync31(manifestPath2)) {
     fail(opts, ExitCode.InputValidation, {
-      error: `nothing to inspect in ${bundleDir} \u2014 ${existsSync30(manifestPath2) ? "no verify-evidence directory" : "no component.json"}`,
+      error: `nothing to inspect in ${bundleDir} \u2014 ${existsSync31(manifestPath2) ? "no verify-evidence directory" : "no component.json"}`,
       code: "no-evidence",
-      remediation: "Run `tendril verify <bundleDir>` first \u2014 inspect reads the ref/render evidence that run writes."
+      remediation: `Run \`${tendrilCommand(`verify ${bundleDir}`)}\` first \u2014 inspect reads the ref/render evidence that run writes.`
     });
   }
   const { manifest } = readBundleManifest(readFileSync27(manifestPath2, "utf8"));
@@ -10742,27 +11637,27 @@ async function runInspect(opts) {
       remediation: "Re-emit the bundle (score/verify rewrite component.json), then re-run inspect."
     });
   }
-  const setDir = path36.resolve(opts.set ?? manifest.provenance.recordingSet.path);
-  const reps = Object.keys(manifest.propAdapter).filter((rep) => existsSync30(path36.join(evidenceDir, `${rep}-ref.png`)) && existsSync30(path36.join(evidenceDir, `${rep}-render.png`)));
+  const setDir = path38.resolve(opts.set ?? manifest.provenance.recordingSet.path);
+  const reps = Object.keys(manifest.propAdapter).filter((rep) => existsSync31(path38.join(evidenceDir, `${rep}-ref.png`)) && existsSync31(path38.join(evidenceDir, `${rep}-render.png`)));
   if (reps.length === 0) {
     fail(opts, ExitCode.InputValidation, {
       error: "verify-evidence holds no ref/render pairs for this bundle's configs",
       code: "no-evidence",
-      remediation: "Run `tendril verify <bundleDir>` first \u2014 inspect reads the ref/render evidence that run writes."
+      remediation: `Run \`${tendrilCommand(`verify ${bundleDir}`)}\` first \u2014 inspect reads the ref/render evidence that run writes.`
     });
   }
   let crops = 0;
   const sections = [];
   for (const rep of reps) {
-    const ref = new Uint8Array(readFileSync27(path36.join(evidenceDir, `${rep}-ref.png`)));
-    const render = new Uint8Array(readFileSync27(path36.join(evidenceDir, `${rep}-render.png`)));
+    const ref = new Uint8Array(readFileSync27(path38.join(evidenceDir, `${rep}-ref.png`)));
+    const render = new Uint8Array(readFileSync27(path38.join(evidenceDir, `${rep}-render.png`)));
     const nodes = smallSemanticNodes(setDir, rep, opts.maxArea ?? 1024).slice(0, 12);
     const cells = [];
     for (const [i, n] of nodes.entries()) {
       const rect = { x: n.x, y: n.y, w: n.w, h: n.h };
       try {
-        writeFileSync16(path36.join(evidenceDir, `${rep}-inspect-${i}-ref.png`), zoomCrop(ref, rect));
-        writeFileSync16(path36.join(evidenceDir, `${rep}-inspect-${i}-render.png`), zoomCrop(render, rect));
+        writeFileSync16(path38.join(evidenceDir, `${rep}-inspect-${i}-ref.png`), zoomCrop(ref, rect));
+        writeFileSync16(path38.join(evidenceDir, `${rep}-inspect-${i}-render.png`), zoomCrop(render, rect));
       } catch {
         continue;
       }
@@ -10775,7 +11670,7 @@ async function runInspect(opts) {
       `<section><h2>${esc(rep)}</h2><div class="full"><span><em>recorded</em><img src="./${rep}-ref.png"></span><span><em>rendered</em><img src="./${rep}-render.png"></span><span><em>diff</em><img src="./${rep}-diff.png"></span></div>` + (cells.length > 0 ? `<div class="grid">${cells.join("")}</div>` : `<p class="none">no small recorded nodes in this config's sweep</p>`) + `</section>`
     );
   }
-  const sheet = path36.join(evidenceDir, "inspect.html");
+  const sheet = path38.join(evidenceDir, "inspect.html");
   writeFileSync16(
     sheet,
     `<!doctype html><meta charset="utf-8"><title>${esc(manifest.name)} \u2014 tendril inspect</title><style>
@@ -10806,6 +11701,7 @@ var init_inspect = __esm({
     init_src6();
     init_src4();
     init_describe();
+    init_invocation();
     init_output();
     INSPECT_DESCRIPTION = {
       name: "inspect",
@@ -10852,17 +11748,17 @@ __export(generate_recorded_exports, {
   runGenerateRecorded: () => runGenerateRecorded
 });
 import { confirm as confirm3, isCancel as isCancel3 } from "@clack/prompts";
-import { existsSync as existsSync31, readFileSync as readFileSync28 } from "node:fs";
-import path37 from "node:path";
+import { existsSync as existsSync32, readFileSync as readFileSync28 } from "node:fs";
+import path39 from "node:path";
 async function runGenerateRecorded(opts) {
   const callerCwd = process.env["INIT_CWD"] ?? process.cwd();
-  const outDirAbs = path37.resolve(callerCwd, opts.out);
-  const recordedAsPath = path37.resolve(callerCwd, opts.recorded);
+  const outDirAbs = path39.resolve(callerCwd, opts.out);
+  const recordedAsPath = path39.resolve(callerCwd, opts.recorded);
   let task;
   let taskName;
   let authoredApi;
   let composition;
-  const isSet = existsSync31(path37.join(recordedAsPath, "recording-set.json"));
+  const isSet = existsSync32(path39.join(recordedAsPath, "recording-set.json"));
   const registry = TASKS[opts.recorded];
   if (registry !== void 0 && !isSet) {
     task = registry;
@@ -10871,7 +11767,7 @@ async function runGenerateRecorded(opts) {
     try {
       const authored = authorTaskFromSet(recordedAsPath);
       task = authored.task;
-      taskName = path37.basename(recordedAsPath);
+      taskName = path39.basename(recordedAsPath);
       authoredApi = authored.api;
       const roles = RolesSchema.safeParse(loadManifest(recordedAsPath).roles);
       if (roles.success) composition = roles.data;
@@ -10880,14 +11776,14 @@ async function runGenerateRecorded(opts) {
       fail(opts, ExitCode.InputValidation, {
         error: `cannot author a task from ${recordedAsPath}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
         code: "AUTHORING_FAILED",
-        remediation: "Complete the recording set (tendril record status) or use a reference-corpus task name."
+        remediation: `Complete the recording set (${tendrilCommand(`record status --set ${recordedAsPath}`)}) or use a reference-corpus task name.`
       });
     }
   } else {
     fail(opts, ExitCode.InputValidation, {
       error: `"${opts.recorded}" is neither a reference task nor a recorded set (no recording-set.json found)`,
       code: "UNKNOWN_RECORDED_INPUT",
-      remediation: `Pick a task (${Object.keys(TASKS).join(", ")}) or point at a set recorded with \`tendril record\`.`
+      remediation: `Pick a task (${Object.keys(TASKS).join(", ")}) or point at a set recorded with \`${tendrilCommand("record plan")}\`.`
     });
   }
   if (!fontsResolved()) {
@@ -10905,13 +11801,13 @@ async function runGenerateRecorded(opts) {
     warn(opts, `font weights (advisory): the recording implies weights ${g.declared.join(", ")} for "${g.family}" \u2014 cache provides ${g.provided.join(", ")}; nearest-weight rendering may shift stroke density (certification stays family-gated; implied weights can leak across families)`);
   }
   const missing = task.configs.filter(
-    (c) => !existsSync31(path37.join(task.set, c.rep, "get_screenshot.json")) || !existsSync31(path37.join(task.set, c.rep, "get_metadata.json")) || !existsSync31(path37.join(task.set, c.rep, "get_design_context.json"))
+    (c) => !existsSync32(path39.join(task.set, c.rep, "get_screenshot.json")) || !existsSync32(path39.join(task.set, c.rep, "get_metadata.json")) || !existsSync32(path39.join(task.set, c.rep, "get_design_context.json"))
   );
   if (missing.length > 0) {
     fail(opts, ExitCode.RecordingIncomplete, {
       error: `recording set ${task.set} is missing envelopes for ${missing.length} rep(s): ${missing.slice(0, 3).map((c) => c.rep).join(", ")}${missing.length > 3 ? ", \u2026" : ""}`,
       code: "recording-incomplete",
-      remediation: "Resume the recording session (`tendril record next`) until `tendril record status` reports the set complete."
+      remediation: `Resume the recording session (\`${tendrilCommand(`record next --set ${task.set}`)}\`) until \`${tendrilCommand(`record status --set ${task.set}`)}\` reports the set complete.`
     });
   }
   const modelId = opts.model ?? DEFAULT_MODEL_CONFIG.curatedDefault ?? DEFAULT_MODEL_CONFIG.bulk;
@@ -10932,7 +11828,7 @@ async function runGenerateRecorded(opts) {
     fail(opts, ExitCode.Auth, {
       error: "OPENROUTER_API_KEY is not configured \u2014 the curated engine needs an OpenRouter-compatible key.",
       code: "MISSING_OPENROUTER_KEY",
-      remediation: "Two paths: run `tendril init` to store your OpenRouter key (BYOK \u2014 your key, your inference), or drive the agent-harness engine explicitly with your own agent host."
+      remediation: `Two paths: run \`${tendrilCommand("init")}\` to store your OpenRouter key (BYOK \u2014 your key, your inference), or drive the agent-harness engine explicitly with your own agent host.`
     });
   }
   const bar = BARS4[opts.bar];
@@ -10975,8 +11871,8 @@ async function runGenerateRecorded(opts) {
 ` : `${line}
 `);
   if (opts.dryRun) {
-    emitData(opts, { dryRun: true, task: taskName, model: modelId, consent, wouldWrite: path37.join(outDirAbs, taskName) }, () => {
-      process.stdout.write(`dry-run: nothing sent, nothing written (would write ${path37.join(outDirAbs, taskName)})
+    emitData(opts, { dryRun: true, task: taskName, model: modelId, consent, wouldWrite: path39.join(outDirAbs, taskName) }, () => {
+      process.stdout.write(`dry-run: nothing sent, nothing written (would write ${path39.join(outDirAbs, taskName)})
 `);
     });
     return;
@@ -10999,10 +11895,10 @@ async function runGenerateRecorded(opts) {
       });
     }
   }
-  const bundleDir = path37.join(outDirAbs, taskName);
-  if (existsSync31(path37.join(bundleDir, "component.json"))) {
+  const bundleDir = path39.join(outDirAbs, taskName);
+  if (existsSync32(path39.join(bundleDir, "component.json"))) {
     try {
-      const prior = readBundleManifest(readFileSync28(path37.join(bundleDir, "component.json"), "utf8")).manifest;
+      const prior = readBundleManifest(readFileSync28(path39.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`,
@@ -11139,6 +12035,7 @@ var init_generate_recorded = __esm({
     init_env();
     init_environment();
     init_font_guidance();
+    init_invocation();
     init_output();
     BARS4 = {
       pass: { sim: 0.95, ink: 0.95 },
@@ -11149,11 +12046,13 @@ var init_generate_recorded = __esm({
 
 // packages/cli/src/bin.ts
 init_src3();
+init_invocation();
 import { CommanderError } from "commander";
 
 // packages/cli/src/program.ts
 init_src3();
 init_environment();
+init_invocation();
 init_doctor();
 import { Command } from "commander";
 
@@ -11161,10 +12060,11 @@ import { Command } from "commander";
 init_src3();
 init_describe();
 init_env();
+init_invocation();
 init_output();
 import { intro, isCancel, outro, password } from "@clack/prompts";
 import fs from "node:fs";
-import path23 from "node:path";
+import path24 from "node:path";
 var INIT_DESCRIPTION = {
   name: "init",
   summary: "Configure Figma and OpenRouter credentials in .env (idempotent).",
@@ -11201,7 +12101,7 @@ async function runInit(flags) {
     printDescription(INIT_DESCRIPTION);
     return;
   }
-  const envPath = path23.resolve(process.cwd(), ".env");
+  const envPath = path24.resolve(process.cwd(), ".env");
   const existing = fs.existsSync(envPath) ? parseEnv(fs.readFileSync(envPath, "utf8")) : /* @__PURE__ */ new Map();
   let figmaToken = flags.figmaToken ?? existing.get(ENV_KEYS.figma);
   let openrouterKey = flags.openrouterKey ?? existing.get(ENV_KEYS.openrouter);
@@ -11210,7 +12110,7 @@ async function runInit(flags) {
     fail(flags, ExitCode.InputValidation, {
       error: "Missing credentials and prompts are disabled.",
       code: "MISSING_CREDENTIALS",
-      remediation: "Pass --figma-token <token> and --openrouter-key <key>, or run `tendril init` in an interactive terminal."
+      remediation: `Pass --figma-token <token> and --openrouter-key <key>, or run \`${tendrilCommand("init")}\` in an interactive terminal.`
     });
   }
   if (interactive) {
@@ -11222,7 +12122,7 @@ async function runInit(flags) {
   next.set(ENV_KEYS.figma, figmaToken);
   next.set(ENV_KEYS.openrouter, openrouterKey);
   const changed = existing.get(ENV_KEYS.figma) !== next.get(ENV_KEYS.figma) || existing.get(ENV_KEYS.openrouter) !== next.get(ENV_KEYS.openrouter);
-  const gitignorePath = path23.resolve(process.cwd(), ".gitignore");
+  const gitignorePath = path24.resolve(process.cwd(), ".gitignore");
   const gitignore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
   const gitignoreCoversEnv = gitignore.split("\n").some((line) => [".env", ".env", ".env*"].includes(line.trim()));
   if (flags.dryRun) {
@@ -11274,17 +12174,18 @@ init_src5();
 init_src2();
 init_describe();
 init_env();
+init_invocation();
 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";
+import { readFileSync as readFileSync15, readdirSync as readdirSync4, existsSync as existsSync19 } from "node:fs";
 
 // packages/cli/src/pipeline.ts
 init_src2();
 init_src4();
 init_src6();
 import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync8 } from "node:fs";
-import path24 from "node:path";
+import path25 from "node:path";
 
 // packages/cli/src/assets-module.ts
 init_src();
@@ -11620,7 +12521,7 @@ async function runGenerationPipeline(input) {
   });
   const written = [];
   if (!input.dryRun) {
-    const dir = path24.resolve(input.outDir, semantics.componentName);
+    const dir = path25.resolve(input.outDir, semantics.componentName);
     mkdirSync5(dir, { recursive: true });
     const files = {
       // Bundle-local tokens: THE emission the component's CSS resolves
@@ -11644,13 +12545,13 @@ async function runGenerationPipeline(input) {
 `
     };
     for (const [name, content] of Object.entries(files)) {
-      const filePath = path24.join(dir, name);
+      const filePath = path25.join(dir, name);
       writeFileSync8(filePath, content);
       written.push(filePath);
     }
     for (const artifact of emitTokenArtifacts(input.mapping)) {
-      const filePath = path24.resolve(input.outDir, artifact.path);
-      mkdirSync5(path24.dirname(filePath), { recursive: true });
+      const filePath = path25.resolve(input.outDir, artifact.path);
+      mkdirSync5(path25.dirname(filePath), { recursive: true });
       writeFileSync8(filePath, artifact.content);
       written.push(filePath);
     }
@@ -11714,7 +12615,7 @@ function resolveProvidedSource(flags, contextFile) {
     fail(flags, ExitCode.InputValidation, {
       error: `Cannot read context file "${contextFile}".`,
       code: "CONTEXT_UNREADABLE",
-      remediation: "Pass a readable JSON file via --context; run `tendril generate --describe` for the payload shape."
+      remediation: `Pass a readable JSON file via --context; run \`${tendrilCommand("generate --describe")}\` for the payload shape.`
     });
   }
   try {
@@ -11723,7 +12624,7 @@ function resolveProvidedSource(flags, contextFile) {
     fail(flags, ExitCode.InputValidation, {
       error: `Context file "${contextFile}" is not a valid design-context payload: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
       code: "CONTEXT_INVALID",
-      remediation: "The payload must match { nodeTree, variables[], metadata, screenshotBase64? } \u2014 see `tendril generate --describe` and docs/adr/003-figma-access-strategy.md."
+      remediation: `The payload must match { nodeTree, variables[], metadata, screenshotBase64? } \u2014 see \`${tendrilCommand("generate --describe")}\` and docs/adr/003-figma-access-strategy.md.`
     });
   }
 }
@@ -11733,7 +12634,7 @@ function resolveSource(flags, url) {
     fail(flags, ExitCode.General, {
       error: "Live Figma transports (desktop MCP / REST) are not wired up yet.",
       code: "NOT_IMPLEMENTED",
-      remediation: "Use `tendril generate --context <file>` with an agent-fetched payload, or mock://button for the offline fixture; live transports are task 1.2 in docs/PLAN.md."
+      remediation: `Use \`${tendrilCommand("generate --context <file>")}\` with an agent-fetched payload, or mock://button for the offline fixture; live transports are task 1.2 in docs/PLAN.md.`
     });
   }
   fail(flags, ExitCode.InputValidation, {
@@ -11752,7 +12653,7 @@ async function runGenerate(url, flags) {
     fail(flags, ExitCode.InputValidation, {
       error: "Missing input: pass a recording set or reference task (recorded truth, the default), mock://button, or --context <file>.",
       code: "MISSING_ARGUMENT",
-      remediation: "Run `tendril generate --describe` to see arguments and examples."
+      remediation: `Run \`${tendrilCommand("generate --describe")}\` to see arguments and examples.`
     });
   }
   url ??= `provided://${flags.context}`;
@@ -11829,10 +12730,10 @@ token mapping (${mapping.flat.length} variables):
   let initialCode;
   let initialSemantics;
   try {
-    if (existsSync18(flags.out)) {
+    if (existsSync19(flags.out)) {
       for (const entry of readdirSync4(flags.out)) {
         const cjPath = `${flags.out}/${entry}/component.json`;
-        if (!existsSync18(cjPath)) continue;
+        if (!existsSync19(cjPath)) continue;
         const cj = JSON.parse(readFileSync15(cjPath, "utf8"));
         if (cj.name !== void 0 && Array.isArray(cj.props)) {
           previousApi = JSON.stringify({
@@ -11841,13 +12742,13 @@ token mapping (${mapping.flat.length} variables):
           });
           const tsxPath = `${flags.out}/${entry}/${cj.name}.tsx`;
           const cssPath = `${flags.out}/${entry}/${cj.name}.css`;
-          if (flags.refine && existsSync18(tsxPath) && existsSync18(cssPath)) {
+          if (flags.refine && existsSync19(tsxPath) && existsSync19(cssPath)) {
             initialCode = {
               tsx: readFileSync15(tsxPath, "utf8"),
               css: readFileSync15(cssPath, "utf8")
             };
             const semPath = `${flags.out}/${entry}/semantics.json`;
-            if (existsSync18(semPath)) {
+            if (existsSync19(semPath)) {
               initialSemantics = JSON.parse(readFileSync15(semPath, "utf8"));
             }
           }
@@ -11877,7 +12778,7 @@ token mapping (${mapping.flat.length} variables):
       fail(flags, ExitCode.Auth, {
         error: "OPENROUTER_API_KEY is not configured.",
         code: "MISSING_OPENROUTER_KEY",
-        remediation: "Run `tendril init` to store your OpenRouter key in .env (BYOK \u2014 your key, your inference)."
+        remediation: `Run \`${tendrilCommand("init")}\` to store your OpenRouter key in .env (BYOK \u2014 your key, your inference).`
       });
     }
     genModel = new OpenRouterGenerationModel(new OpenRouterClient({ apiKey }), model.id, {
@@ -12100,7 +13001,7 @@ function buildProgram() {
       fail2(flags, ExitCode.InputValidation, {
         error: family === void 0 ? "nothing to resolve \u2014 pass a family name or --set <recording-dir>" : "pass a family name OR --set, not both \u2014 --set derives families from the recording itself",
         code: "INPUT_VALIDATION",
-        remediation: 'tendril fonts resolve --set <recording-dir>, or tendril fonts resolve "<Family>" --weights 400 500 600'
+        remediation: `${tendrilCommand("fonts resolve --set <recording-dir>")}, or ${tendrilCommand('fonts resolve "<Family>" --weights 400 500 600')}`
       });
     }
     if (set !== void 0) {
@@ -12254,7 +13155,7 @@ try {
     const cliError2 = {
       error: err.message,
       code: "INPUT_VALIDATION",
-      remediation: "Run `tendril --help` or `<command> --describe` for usage."
+      remediation: `Run \`${tendrilCommand("--help")}\` or \`${tendrilCommand("<command> --describe")}\` for usage.`
     };
     process.stderr.write(`${JSON.stringify(cliError2)}
 `);