@tendrilapp/cli 0.1.25 → 0.1.27

package/dist/SKILL.md

@@ -137,11 +137,15 @@ Batch runs (several components in one session):
      name what kind of control it is.
    FEASIBILITY, before the first recording call: the plan output
    states the call arithmetic for this queue (poses × calls per pose).
-   Turn it into a verdict with one free check — call the Figma
-   `whoami` tool, which names the seat and plan and is exempt from
-   Figma's tool-call limits, then divide the queue's call count by the
-   daily allowance that seat carries. Never quote an allowance from
-   memory; use the one whoami reports. If the set fits inside one
+   Turn it into a verdict with one free check — IF your Figma server
+   exposes a `whoami` tool, call it: it names the seat and plan and is
+   exempt from Figma's tool-call limits. Then divide the queue's call
+   count by the daily allowance that seat carries. Never quote an
+   allowance from memory; use the one whoami reports. Not every
+   transport has it — the remote Figma MCP server does, the local Dev
+   Mode server does not — so if yours does not, say the allowance is
+   UNKNOWN and show the plan's own hint as the unverified figure it is
+   marked as, rather than presenting a guess as a checked number. If the set fits inside one
    day, record and say nothing about cost — a set that comfortably
    fits is not worth the user's attention. If it does NOT fit, stop
    and tell the user in plain numbers before recording anything:

package/dist/tendril.js

@@ -1028,6 +1028,14 @@ function planSet(setDir, component, symbols, opts = {}) {
     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`))));
+    const scopeUpgraded = opts.variantScope === "component-set" && existing.variantScope !== "component-set";
+    if (opts.variantScope === "component-set") {
+      raw["variantScope"] = "component-set";
+      const variants = symbols.map((s) => s.name).filter((n) => n.includes("="));
+      if (variants.length > 0 && (scopeUpgraded || variants.length > (existing.latticeNames ?? []).length)) {
+        raw["latticeNames"] = variants;
+      }
+    }
     if (!wantsNewDefaults || anythingRecorded) {
       if (opts.sample !== true) {
         const known = new Set(existing.reps.map((r) => r.nodeId));
@@ -1049,6 +1057,10 @@ function planSet(setDir, component, symbols, opts = {}) {
           return { manifest: manifest2, plan: { reps: [], notRecorded: [] }, resumed: true, toppedUp: appended.map((a) => ({ slug: a.slug, nodeId: a.nodeId })) };
         }
       }
+      if (scopeUpgraded) {
+        const manifest2 = writeManifest(setDir, raw);
+        return { manifest: manifest2, plan: { reps: [], notRecorded: [] }, resumed: true };
+      }
       return { manifest: existing, plan: { reps: [], notRecorded: [] }, resumed: true };
     }
   }
@@ -1058,6 +1070,7 @@ function planSet(setDir, component, symbols, opts = {}) {
     version: 1,
     component,
     ...opts.sourceFrames !== void 0 ? { sourceFrames: opts.sourceFrames } : {},
+    ...opts.variantScope !== void 0 ? { variantScope: opts.variantScope } : {},
     ...opts.defaults !== void 0 && Object.keys(opts.defaults).length > 0 ? { defaults: opts.defaults } : {},
     ...(() => {
       const variants = symbols.map((s) => s.name).filter((n) => n.includes("="));
@@ -1184,6 +1197,31 @@ var init_session = __esm({
        * domains: the API must cover the lattice even where only a subset
        * is recorded. */
       latticeNames: z4.array(z4.string()).optional(),
+      /**
+       * WHETHER `latticeNames` IS A DENOMINATOR AT ALL.
+       *
+       * The lattice is derived from the metadata handed to `record plan`,
+       * so when that metadata is a bare list of variant nodes the count is
+       * the SELECTION, not the component set. Field case (run 17): four
+       * node ids that were 2 of 5 columns of a 5×2 set. Planning them would
+       * have recorded a set silently missing three variants — and the
+       * plan's own cross-check would have passed, because it validates
+       * against the same metadata it was handed. Downstream that reads as
+       * `latticeConfigs: 4 / unrecordedConfigs: 0`: an affirmative COMPLETE
+       * claim over 40% of a missing axis, on the trust anchor's own
+       * coverage disclosure.
+       *
+       * The signal is whether the metadata carried ENCLOSING CONTEXT: a
+       * per-variant `get_metadata` returns the `<symbol>` as the root with
+       * no ancestor, while a page- or set-level call nests the variants
+       * under the named component set. "component-set" therefore means the
+       * planner saw the set's own children; "selection" means it saw what
+       * it was given and cannot know what else exists.
+       *
+       * Absent on sets planned before this field — treated as unknown, not
+       * as complete, because that is what it was.
+       */
+      variantScope: z4.enum(["component-set", "selection"]).optional(),
       /** Which planning mode produced this queue. Absent = planned before
        * the full-matrix default (i.e. sampled) — resume uses this to
        * top-up rather than silently perpetuating a sampled queue. */
@@ -1894,6 +1932,10 @@ function tendrilInvocation() {
 function tendrilCommand(args) {
   return `${tendrilInvocation()} ${args}`;
 }
+function quoteArg(value) {
+  if (/["`$]/.test(value)) throw new Error(`refusing to emit a shell argument containing a double quote, backtick or $: ${value}`);
+  return /[\s'*?[\]()&;|<>#~]/.test(value) ? `"${value}"` : value;
+}
 var NPX_INVOCATION, cached;
 var init_invocation = __esm({
   "packages/cli/src/invocation.ts"() {
@@ -3450,6 +3492,112 @@ var init_paths = __esm({
   }
 });
 
+// packages/verify/src/font-collection.ts
+function isCollection(bytes) {
+  return bytes.length >= 12 && new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0) === TTC_TAG;
+}
+function nameTableStrings(view, bytes, nameOffset, nameLength) {
+  const out = /* @__PURE__ */ new Map();
+  if (nameOffset + 6 > bytes.length) return out;
+  const count = view.getUint16(nameOffset + 2);
+  const stringOffset = nameOffset + view.getUint16(nameOffset + 4);
+  for (let i = 0; i < count; i++) {
+    const rec = nameOffset + 6 + i * 12;
+    if (rec + 12 > bytes.length) break;
+    const platformId = view.getUint16(rec);
+    const encodingId = view.getUint16(rec + 2);
+    const nameId = view.getUint16(rec + 6);
+    const length = view.getUint16(rec + 8);
+    const offset = stringOffset + view.getUint16(rec + 10);
+    if (offset + length > bytes.length || offset + length > nameOffset + nameLength) continue;
+    const slice = bytes.subarray(offset, offset + length);
+    const isUtf16 = platformId === 3 || platformId === 0 || encodingId === 1;
+    let value = "";
+    if (isUtf16) {
+      for (let j = 0; j + 1 < slice.length; j += 2) value += String.fromCharCode(slice[j] << 8 | slice[j + 1]);
+    } else {
+      for (const b of slice) value += String.fromCharCode(b);
+    }
+    if (value !== "" && !out.has(nameId)) out.set(nameId, value);
+  }
+  return out;
+}
+function listCollectionFaces(bytes) {
+  if (!isCollection(bytes)) return [];
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const numFonts = view.getUint32(8);
+  const faces = [];
+  for (let i = 0; i < numFonts; i++) {
+    const dirOffset = view.getUint32(12 + i * 4);
+    if (dirOffset + SFNT_HEADER_SIZE > bytes.length) continue;
+    const numTables = view.getUint16(dirOffset + 4);
+    let names = /* @__PURE__ */ new Map();
+    for (let t = 0; t < numTables; t++) {
+      const rec = dirOffset + SFNT_HEADER_SIZE + t * TABLE_RECORD_SIZE;
+      if (rec + TABLE_RECORD_SIZE > bytes.length) break;
+      const tag = String.fromCharCode(bytes[rec], bytes[rec + 1], bytes[rec + 2], bytes[rec + 3]);
+      if (tag !== "name") continue;
+      names = nameTableStrings(view, bytes, view.getUint32(rec + 8), view.getUint32(rec + 12));
+      break;
+    }
+    const family = names.get(1);
+    const subfamily = names.get(2);
+    faces.push({ index: i, ...family !== void 0 ? { family } : {}, ...subfamily !== void 0 ? { subfamily } : {} });
+  }
+  return faces;
+}
+function extractCollectionFace(bytes, index) {
+  if (!isCollection(bytes)) throw new Error("not a TrueType Collection");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const numFonts = view.getUint32(8);
+  if (index < 0 || index >= numFonts) throw new Error(`face index ${index} out of range \u2014 the collection holds ${numFonts}`);
+  const dirOffset = view.getUint32(12 + index * 4);
+  const numTables = view.getUint16(dirOffset + 4);
+  const records = [];
+  for (let t = 0; t < numTables; t++) {
+    const rec = dirOffset + SFNT_HEADER_SIZE + t * TABLE_RECORD_SIZE;
+    const checksum = view.getUint32(rec + 4);
+    const offset = view.getUint32(rec + 8);
+    const length = view.getUint32(rec + 12);
+    if (offset + length > bytes.length) throw new Error(`collection table ${t} runs past the end of the file`);
+    records.push({ tag: bytes.subarray(rec, rec + 4), checksum, data: bytes.subarray(offset, offset + length) });
+  }
+  const aligned = (n) => n + 3 & ~3;
+  const bodySize = records.reduce((sum, r) => sum + aligned(r.data.length), 0);
+  const out = new Uint8Array(SFNT_HEADER_SIZE + records.length * TABLE_RECORD_SIZE + bodySize);
+  const outView = new DataView(out.buffer);
+  outView.setUint32(0, view.getUint32(dirOffset));
+  outView.setUint16(4, records.length);
+  const pow2 = Math.floor(Math.log2(Math.max(1, records.length)));
+  outView.setUint16(6, 16 * 2 ** pow2);
+  outView.setUint16(8, pow2);
+  outView.setUint16(10, records.length * 16 - 16 * 2 ** pow2);
+  let cursor = SFNT_HEADER_SIZE + records.length * TABLE_RECORD_SIZE;
+  records.forEach((r, i) => {
+    const rec = SFNT_HEADER_SIZE + i * TABLE_RECORD_SIZE;
+    out.set(r.tag, rec);
+    outView.setUint32(rec + 4, r.checksum);
+    outView.setUint32(rec + 8, cursor);
+    outView.setUint32(rec + 12, r.data.length);
+    out.set(r.data, cursor);
+    cursor += aligned(r.data.length);
+  });
+  return out;
+}
+function facesForFamily(bytes, family) {
+  const want = family.toLowerCase().replace(/\s+/g, "");
+  return listCollectionFaces(bytes).filter((f) => (f.family ?? "").toLowerCase().replace(/\s+/g, "") === want);
+}
+var TTC_TAG, TABLE_RECORD_SIZE, SFNT_HEADER_SIZE;
+var init_font_collection = __esm({
+  "packages/verify/src/font-collection.ts"() {
+    "use strict";
+    TTC_TAG = 1953784678;
+    TABLE_RECORD_SIZE = 16;
+    SFNT_HEADER_SIZE = 12;
+  }
+});
+
 // packages/verify/src/font-resolve.ts
 import { createHash } from "node:crypto";
 import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
@@ -3538,18 +3686,33 @@ async function resolveFonts(family, weights, cacheDir = DEFAULT_FONT_CACHE) {
 `);
   return { resolved, failures };
 }
-function addLocalFont(family, weight, filePath, cacheDir = DEFAULT_FONT_CACHE) {
+function addLocalFont(family, weight, filePath, cacheDir = DEFAULT_FONT_CACHE, faceIndex) {
   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`);
+  if (![".woff2", ".woff", ".ttf", ".otf", ".ttc"].includes(ext)) {
+    throw new Error(`unsupported font file "${ext}" \u2014 use .woff2 (preferred), .woff, .ttf, .otf or .ttc`);
   }
-  const bytes = new Uint8Array(readFileSync3(src));
+  let bytes = new Uint8Array(readFileSync3(src));
   if (bytes.length === 0) throw new Error(`font file is empty: ${src}`);
+  let storedExt = ext;
+  if (isCollection(bytes)) {
+    const candidates = facesForFamily(bytes, family);
+    const chosen = faceIndex ?? (candidates.length === 1 ? candidates[0].index : void 0);
+    if (chosen === void 0) {
+      const all = listCollectionFaces(bytes);
+      const shown = (candidates.length > 0 ? candidates : all).map((f) => `  --face ${f.index}  ${f.family ?? "(unnamed)"}${f.subfamily !== void 0 ? ` ${f.subfamily}` : ""}`).join("\n");
+      throw new Error(
+        `${path10.basename(src)} is a collection of ${all.length} faces and ${candidates.length === 0 ? `none is named "${family}"` : `${candidates.length} match "${family}"`} \u2014 name the one you mean with --face <index>:
+${shown}`
+      );
+    }
+    bytes = new Uint8Array(extractCollectionFace(bytes, chosen));
+    storedExt = ".ttf";
+  }
   mkdirSync2(cacheDir, { recursive: true });
   const sha256 = createHash("sha256").update(bytes).digest("hex");
-  const file = path10.join(cacheDir, `${family.toLowerCase().replace(/\s+/g, "-")}-${weight}${ext}`);
+  const file = path10.join(cacheDir, `${family.toLowerCase().replace(/\s+/g, "-")}-${weight}${storedExt}`);
   writeFileSync3(file, bytes);
   const face = { family, weight, source: `local:${path10.basename(src)}`, sha256, file, license: "unknown" };
   const mPath = path10.join(cacheDir, "manifest.json");
@@ -3639,6 +3802,7 @@ var DEFAULT_FONT_CACHE, UA, FONT_LICENSES, GOOGLE_LICENSE_IDS, GOOGLE_FONT_FILE_
 var init_font_resolve = __esm({
   "packages/verify/src/font-resolve.ts"() {
     "use strict";
+    init_font_collection();
     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"];
@@ -4157,15 +4321,44 @@ async function runSteps(page, spec, renderPose) {
         const verdict = await page.evaluate(
           `(() => {
             const needle = ${JSON.stringify(step.assertTextVisible)};
-            const els = [...document.querySelectorAll('#root *')];
-            const holders = els.filter((el) => [...el.childNodes].some((n) => n.nodeType === 3 && (n.textContent ?? '').includes(needle)));
-            if (holders.length === 0) return 'text not in the DOM at all';
-            for (const el of holders) {
+            // Attributes a user actually perceives, whether by eye or
+            // through assistive tech. Deliberately NOT every attribute:
+            // a data-* or a name= is a place to park a string, which is
+            // the dodge this check exists to catch.
+            const PERCEIVED = ['placeholder', 'alt', 'aria-label', 'title', 'value'];
+            // 'value' counts ONLY where the platform RENDERS it as the
+            // control's text: text-entry inputs, textarea, and the
+            // input-typed buttons whose value IS their label. Nearly
+            // every element carries a value PROPERTY \u2014 a visible
+            // checkbox or <button> with value={sentinel} would satisfy
+            // an unrestricted check while no user ever perceives the
+            // string, which reopens the exact dodge this check exists
+            // to close (post-release review, 2026-08-14). password is
+            // excluded because its value renders as dots, not as the
+            // string. Fail-closed allowlist, not a blocklist.
+            const VALUE_RENDERS = ['text', 'search', 'email', 'url', 'tel', 'number', 'submit', 'reset', 'button'];
+            const valueRenders = (el) =>
+              el instanceof HTMLTextAreaElement || (el instanceof HTMLInputElement && VALUE_RENDERS.includes(el.type));
+            const visible = (el) => {
               const r = el.getBoundingClientRect();
               const cs = getComputedStyle(el);
-              if (r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' && Number(cs.opacity) > 0) return true;
-            }
-            return 'text present but not visibly rendered (hidden/zero-size/transparent node)';
+              return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.display !== 'none' && Number(cs.opacity) > 0;
+            };
+            const els = [...document.querySelectorAll('#root *')];
+            const textHolders = els.filter((el) => [...el.childNodes].some((n) => n.nodeType === 3 && (n.textContent ?? '').includes(needle)));
+            for (const el of textHolders) if (visible(el)) return true;
+            const attrHolders = els.filter((el) =>
+              PERCEIVED.some((a) => {
+                // The LIVE value for form controls: React's defaultValue
+                // sets the property, and the attribute may never appear.
+                if (a === 'value' && !valueRenders(el)) return false;
+                const v = a === 'value' ? el.value : el.getAttribute(a);
+                return typeof v === 'string' && v.includes(needle);
+              }),
+            );
+            for (const el of attrHolders) if (visible(el)) return true;
+            if (textHolders.length === 0 && attrHolders.length === 0) return 'text not in the DOM at all, and not in a placeholder/alt/aria-label/title/value either';
+            return 'present but not visibly rendered (hidden/zero-size/transparent node)';
           })()`
         );
         if (verdict !== true) return { id: spec.id, pass: false, detail: `sentinel "${step.assertTextVisible}": ${String(verdict)}` };
@@ -4430,7 +4623,7 @@ function definedVars(tokensCss) {
   for (const m of tokensCss.matchAll(/(--[\w-]+)\s*:/g)) names.add(m[1]);
   return names;
 }
-function recordedTokenMapEmpty(setDir, reps) {
+function recordedTokenMapState(setDir, reps) {
   const readMap = (file) => {
     if (!existsSync10(file)) return void 0;
     try {
@@ -4441,15 +4634,15 @@ function recordedTokenMapEmpty(setDir, reps) {
     }
   };
   const setLevel = readMap(path15.join(setDir, "get_variable_defs.json"));
-  if (setLevel !== void 0) return Object.keys(setLevel).length === 0;
+  if (setLevel !== void 0) return Object.keys(setLevel).length === 0 ? "empty" : "populated";
   let recorded = false;
   for (const rep of reps) {
     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;
+    if (Object.keys(m).length > 0) return "populated";
   }
-  return recorded;
+  return recorded ? "empty" : "never-recorded";
 }
 function scannable(css) {
   const blank = (m) => m.replace(/[^\n]/g, " ");
@@ -4536,10 +4729,17 @@ async function checkBundleQuality(bundleDir, entry, set, fontManifest) {
     }
   }
   if (css !== "") {
-    const recordedEmpty = set !== void 0 && recordedTokenMapEmpty(set.dir, set.reps);
-    for (const v of (await runTokenLint(css, "styles.css", definedVars(tokensCss), recordedEmpty)).violations) {
+    const mapState = set === void 0 ? void 0 : recordedTokenMapState(set.dir, set.reps);
+    for (const v of (await runTokenLint(css, "styles.css", definedVars(tokensCss), mapState !== void 0 && mapState !== "populated")).violations) {
       findings.push({ kind: "token-lint", file: "styles.css", line: v.line, message: v.message });
     }
+    if (mapState === "never-recorded") {
+      findings.push({
+        kind: "token-lint",
+        file: "styles.css",
+        message: "the recording set has NO design-token map (no get_variable_defs envelope at set or rep level), so whether these literals have kit tokens is UNKNOWN, not answered \u2014 the brief's empty token table means 'never recorded', not 'this kit has none'. Record it with `record next` on the set (it asks for get_variable_defs once, at set level) and re-run to get real token guidance."
+      });
+    }
   }
   return { findings, tokensAbsent: tokensCss === void 0 && !/var\(\s*--/.test(css) };
 }
@@ -5519,6 +5719,7 @@ var init_src4 = __esm({
     init_tasks();
     init_prelude();
     init_mount_limits();
+    init_font_collection();
     init_font_faces();
     init_font_resolve();
     init_paths();
@@ -5770,6 +5971,15 @@ import { spawnSync } from "node:child_process";
 import { existsSync as existsSync18, readFileSync as readFileSync14, readdirSync as readdirSync3 } from "node:fs";
 import os4 from "node:os";
 import path23 from "node:path";
+function withDeadline(work, ms) {
+  return Promise.race([
+    work,
+    new Promise((_resolve, reject) => {
+      const timer = setTimeout(() => reject(new McpProbeTimeout(ms)), ms);
+      timer.unref?.();
+    })
+  ]);
+}
 async function runDoctorChecks(options) {
   const checks = [];
   const mcpUrl = options.mcpUrl ?? DEFAULT_MCP_URL;
@@ -5778,19 +5988,26 @@ async function runDoctorChecks(options) {
     ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
   });
   try {
-    const info = await client.initialize();
-    const tools = await client.listTools();
+    const info = await withDeadline(client.initialize(), MCP_PROBE_DEADLINE_MS);
+    const tools = await withDeadline(client.listTools(), MCP_PROBE_DEADLINE_MS);
     checks.push({
       name: "figma-desktop-mcp",
       ok: true,
-      detail: `${info.name} ${info.version} (protocol ${info.protocolVersion}), ${tools.length} tools: ${tools.map((t) => t.name).join(", ")}`
+      // WHOSE capability this tested. Run 16 read a green tick here as
+      // permission to start recording, and could not: the CLI reaches
+      // this server with its own localhost client, while the AGENT held
+      // no Figma MCP tools at all, and `record` is agent-driven with no
+      // CLI path. The operator wrote a 100-line MCP client in the first
+      // ten minutes of a paid run. A check consumed by one party about
+      // another party's capability has to say so out loud.
+      detail: `${info.name} ${info.version} (protocol ${info.protocolVersion}), ${tools.length} tools: ${tools.map((t) => t.name).join(", ")} \u2014 this is THIS CLI's own connection. It does NOT test whether your agent session holds Figma MCP tools, and recording needs the AGENT to make those calls: confirm with one real get_metadata call before planning.`
     });
   } catch (err) {
     checks.push({
       name: "figma-desktop-mcp",
       ok: false,
       detail: err instanceof Error ? err.message : String(err),
-      remediation: err instanceof McpUnavailableError ? "Open the Figma desktop app, sign in, then Figma menu \u2192 Preferences \u2192 Enable local MCP server (Dev or Full seat on a paid plan)." : "The server answered but the exchange failed \u2014 check the signed-in account's seat, then retry."
+      remediation: err instanceof McpUnavailableError ? "Open the Figma desktop app, sign in, then Figma menu \u2192 Preferences \u2192 Enable local MCP server (Dev or Full seat on a paid plan)." : err instanceof McpProbeTimeout ? "Quit and reopen the Figma desktop app, then re-run doctor. If it answers again, nothing else is wrong \u2014 the server was reachable but stalled." : "The server answered but the exchange failed \u2014 check the signed-in account's seat, then retry."
     });
   }
   const openrouterKey = resolveCredential("OPENROUTER_API_KEY");
@@ -5929,7 +6146,7 @@ async function runDoctor(flags) {
   });
   if (!report.ok) process.exit(1);
 }
-var DEFAULT_MCP_URL, DOCTOR_DESCRIPTION;
+var DEFAULT_MCP_URL, DOCTOR_DESCRIPTION, MCP_PROBE_DEADLINE_MS, McpProbeTimeout;
 var init_doctor = __esm({
   "packages/cli/src/commands/doctor.ts"() {
     "use strict";
@@ -5957,6 +6174,15 @@ var init_doctor = __esm({
       exitCodes: { 0: "healthy", 1: "one or more required checks failed" },
       examples: ["tendril doctor", "tendril doctor --json"]
     };
+    MCP_PROBE_DEADLINE_MS = 1e4;
+    McpProbeTimeout = class extends Error {
+      constructor(ms) {
+        super(
+          `the Figma MCP server accepted the connection but did not answer within ${ms / 1e3}s. It is reachable and not responding \u2014 usually a Figma desktop app that needs restarting (this state has been seen after an in-place app update).`
+        );
+        this.name = "McpProbeTimeout";
+      }
+    };
   }
 });
 
@@ -7457,6 +7683,7 @@ function runRecordPlan(opts) {
     }
   }
   const setNames = [...new Set(symbols.map((s) => s.setName).filter((n) => n !== void 0))];
+  const variantScope = setNames.length > 0 ? "component-set" : "selection";
   if (opts.componentSet !== void 0) {
     const filtered = symbols.filter((s) => s.setName === opts.componentSet);
     if (filtered.length === 0) {
@@ -7514,7 +7741,11 @@ function runRecordPlan(opts) {
   if (metadataTruncated) {
     warn(opts, "get_metadata response appears TRUNCATED (unclosed structure) \u2014 the variant list below may be incomplete. Cross-check variantsFound against the variant count Figma shows for this component set; re-fetch the metadata if lower.");
   }
-  const { manifest, plan, resumed, toppedUp } = planSet(opts.setDir, opts.component, symbols, { ...Object.keys(defaults).length > 0 ? { defaults } : {}, ...opts.sample === true ? { sample: true } : {} });
+  const { manifest, plan, resumed, toppedUp } = planSet(opts.setDir, opts.component, symbols, {
+    ...Object.keys(defaults).length > 0 ? { defaults } : {},
+    ...opts.sample === true ? { sample: true } : {},
+    variantScope
+  });
   const defaultReports = reportAxisDefaults(symbols, Object.keys(defaults).length > 0 ? defaults : void 0);
   const toConfirm = resumed ? [] : defaultReports.filter((r) => (r.rule === "non-interaction" || r.rule === "frequency") && r.domain.length > 1);
   const interactionStatesToConfirm = recordsInteractionState(defaultReports) ? void 0 : interactionDisclosure(manifest.component, defaultReports);
@@ -7532,7 +7763,7 @@ function runRecordPlan(opts) {
     callsWorstCase: posesRemaining * FIGMA_CALLS_PER_REP_WORST,
     posesToRecord: posesRemaining,
     callsPerPose: FIGMA_CALLS_PER_REP,
-    instruction: "BEFORE the first recording call, call the Figma MCP `whoami` tool \u2014 it names the seat and plan and is EXEMPT from Figma's tool-call limits, so this check costs nothing and spends no quota. Read the daily tool-call allowance for that seat/plan and divide: callsNeeded \xF7 allowance = days this set needs. Tendril owns the multiplication above; the allowance is Figma's and is theirs to change, so take it from whoami and never from memory.",
+    instruction: "BEFORE the first recording call, IF your Figma server exposes a `whoami` tool, call it \u2014 it names the seat and plan and is EXEMPT from Figma's tool-call limits, so the check costs nothing and spends no quota. Read the daily tool-call allowance for that seat/plan and divide: callsNeeded \xF7 allowance = days this set needs. Tendril owns the multiplication above; the allowance is Figma's and theirs to change, so take it from whoami and never from memory. NOT EVERY TRANSPORT HAS IT: the remote Figma MCP server does; the local Dev Mode server exposes six tools and `whoami` is not among them (measured 2026-08-14). If yours does not, say so plainly, treat the allowance as UNKNOWN, and use limitHintIfWhoamiIsSilent below \u2014 which is unverified and dated, and must be shown as such. Do not report a guessed allowance as a checked one.",
     surface: multiDay ? "This set exceeds every daily allowance we have heard of, so it CANNOT finish in one day. State the verdict to the user in plain numbers BEFORE recording anything and let them choose from `options` \u2014 do not start on the assumption it will fit." : "Say nothing about cost if the division fits inside one day's allowance \u2014 a set that comfortably fits is not worth the user's attention. Surface the verdict and `options` only when it does not fit.",
     verdictTemplate: `${callSentence}. Your <seat> seat on <plan> allows <allowance>/day. This set needs about <days> day(s) at that rate.`,
     options: [
@@ -7548,7 +7779,7 @@ function runRecordPlan(opts) {
         // a CLI flag and the MCP surface has no parameter for it.
         decidedBy: "HUMAN ONLY \u2014 offer it, never choose it, and you cannot run it",
         text: "Record a reduced pose set (anchor + one-factor sweeps + conflict crosses) instead of the full variant matrix. This buys calls with coverage \u2014 sampling is blind to multi-axis interactions and the report discloses the poses it skipped \u2014 so only the user may accept that trade. There is no tool parameter for it; the user runs it themselves in their own terminal, before any pose is recorded.",
-        userRuns: [`rm ${path26.join(opts.setDir, "recording-set.json")}`, `${tendrilCommand(`record plan --set ${opts.setDir} --component ${manifest.component}`)} --sample`]
+        userRuns: [`rm ${quoteArg(path26.join(opts.setDir, "recording-set.json"))}`, `${tendrilCommand(`record plan --set ${quoteArg(opts.setDir)} --component ${quoteArg(manifest.component)}`)} --sample`]
       },
       {
         id: "larger-allowance",
@@ -7569,6 +7800,13 @@ function runRecordPlan(opts) {
       // the one check that catches parse/transfer losses this pipeline
       // cannot detect from the envelope alone.
       variantsFound: symbols.length,
+      // WHAT variantsFound IS A COUNT OF. The comment above tells the
+      // reader to hold it against Figma's own variant count — a check
+      // run 17 proved an agent cannot perform, because it cannot see
+      // the user's screen. So the pipeline must say when the number is
+      // merely the selection it was handed.
+      variantScope,
+      ...variantScope === "selection" ? { variantCoverageUnknown: SELECTION_SCOPE_DISCLOSURE } : {},
       planMode: manifest.planMode ?? "sample",
       ...metadataTruncated ? { metadataTruncated: true } : {},
       ...toppedUp !== void 0 ? { toppedUp } : {},
@@ -7673,7 +7911,19 @@ function nextPayload(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 };
   }
-  return instruction === null ? { complete: true, progress } : { ...instruction, note: `${instruction.note}. ${ENVELOPE_HELP}`, progress };
+  return instruction === null ? { complete: true, progress } : {
+    ...instruction,
+    note: `${instruction.note}. ${ENVELOPE_HELP}`,
+    // RESUME POINTER, NOT A WORK ASSIGNMENT. This is the globally
+    // first unrecorded rep, so under parallel recorders it hands the
+    // same rep to everyone: run 18 measured 8 of 10 ingests pointing
+    // a recorder at `anchor`, which was another agent's job. Correct
+    // for picking a set back up, wrong as a loop driver, and it was
+    // labelled as neither.
+    scope: "resume-pointer",
+    parallelWarning: "This is the first unrecorded rep in the WHOLE set, not your next one. If several recorders are working this set at once, ignore it and follow your own assigned rep list \u2014 otherwise every recorder converges on the same rep.",
+    progress
+  };
 }
 function runRecordNext(opts) {
   const payload = nextPayload(opts.setDir);
@@ -8081,7 +8331,7 @@ function runRecordFinish(opts) {
 `);
   }
 }
-var FIGMA_CALLS_PER_REP, FIGMA_CALLS_PER_REP_WORST, MULTI_DAY_CALL_THRESHOLD, LIMIT_HINT, stateTokens, MAX_SPOKEN_VALUES, andList, ENVELOPE_HELP, isAutoFetchAssetUrl, describeRoleLoss;
+var FIGMA_CALLS_PER_REP, FIGMA_CALLS_PER_REP_WORST, MULTI_DAY_CALL_THRESHOLD, SELECTION_SCOPE_DISCLOSURE, LIMIT_HINT, stateTokens, MAX_SPOKEN_VALUES, andList, ENVELOPE_HELP, isAutoFetchAssetUrl, describeRoleLoss;
 var init_record = __esm({
   "packages/cli/src/commands/record.ts"() {
     "use strict";
@@ -8094,6 +8344,7 @@ var init_record = __esm({
     FIGMA_CALLS_PER_REP = 3;
     FIGMA_CALLS_PER_REP_WORST = 4;
     MULTI_DAY_CALL_THRESHOLD = 600;
+    SELECTION_SCOPE_DISCLOSURE = "variantsFound counts the nodes you passed, NOT the component set: this metadata carried no enclosing set, so nothing here can tell whether the set holds more variants. Do NOT report the lattice as complete on this basis. To establish the real denominator, call get_metadata WITHOUT a nodeId (a page-level listing), find the component set these nodes sit under, and re-run plan against it \u2014 re-planning is free until the first envelope is ingested. If you proceed as-is, say plainly that coverage is unestablished.";
     LIMIT_HINT = {
       status: "UNVERIFIED \u2014 recorded 2026-08-14 from Figma's published documentation and one field report; Figma changes these at will.",
       use: "Use ONLY if whoami states no allowance, and say it is unverified when you show it. The allowance whoami reports always wins.",
@@ -8692,7 +8943,13 @@ function authorComponentApi(opts) {
   const provided = opts.fonts ?? [];
   const recorded = opts.recordedFonts ?? [];
   const unprovided = recorded.filter((r) => !provided.some((p) => p.toLowerCase() === r.toLowerCase()));
-  const fontsLine = (provided.length > 0 ? `Fonts provided by the harness: ${provided.map((f) => `'${f}'`).join(", ")}. ` : "") + (recorded.length > 0 ? `The recording's declared famil${recorded.length === 1 ? "y is" : "ies are"} ${recorded.map((f) => `'${f}'`).join(", ")}${unprovided.length > 0 ? ` \u2014 ${unprovided.map((f) => `'${f}'`).join(", ")} ${unprovided.length === 1 ? "is" : "are"} NOT provided: the mount will substitute a provided face, scoring reflects the recorded one, and the residual glyph delta is not closable from CSS \u2014 do not chase it` : ""}. ` : "");
+  const faceGaps = (opts.providedFaces ?? []).map((f) => {
+    const need = (opts.recordedFaces ?? []).find((r) => r.family.toLowerCase() === f.family.toLowerCase());
+    const missing = (need?.weights ?? []).filter((w) => !f.weights.includes(w));
+    return { family: f.family, has: f.weights, missing };
+  }).filter((f) => f.missing.length > 0);
+  const weightsLine = (opts.providedFaces ?? []).length > 0 ? `Weights the harness can actually serve: ${(opts.providedFaces ?? []).map((f) => `'${f.family}' (${[...f.weights].sort((a, b) => a - b).join(", ")})`).join("; ")}. ` + (faceGaps.length > 0 ? `WEIGHT GAP \u2014 ${faceGaps.map((g) => `'${g.family}' is recorded at ${g.missing.join(", ")} which the cache does NOT hold`).join("; ")}. CSS binds the FAMILY before the weight and font-synthesis: none blocks the fall-through, so text at a missing weight renders in a weight this family DOES have, silently and at full score-cost. Do not lead a font stack with a family that cannot serve the weight you are setting; put a family that has it first, or report the gap rather than chasing the difference as geometry. ` : "") : "";
+  const fontsLine = weightsLine + (provided.length > 0 ? `Fonts provided by the harness: ${provided.map((f) => `'${f}'`).join(", ")}. ` : "") + (recorded.length > 0 ? `The recording's declared famil${recorded.length === 1 ? "y is" : "ies are"} ${recorded.map((f) => `'${f}'`).join(", ")}${unprovided.length > 0 ? ` \u2014 ${unprovided.map((f) => `'${f}'`).join(", ")} ${unprovided.length === 1 ? "is" : "are"} NOT provided: the mount will substitute a provided face, scoring reflects the recorded one, and the residual glyph delta is not closable from CSS \u2014 do not chase it` : ""}. ` : "");
   const forcingCanon = forcedStates.length > 0 ? `Interactive states are REAL (:hover, :focus-visible) AND statically forceable via the data-tendril-state attribute (a DOCUMENTED token-list attribute; tokens: ${forcedStates.map((t) => `"${t}"`).join(" | ")}) spread onto the root; forced and real selectors must share ONE declaration block, e.g. :is(:hover, [data-tendril-state~="hover"]) \u2014 match with ~= so compound states ("hover selected") work. ` : "";
   const systemApi = `Prescribed API (the harness mounts exactly this; deviation scores 0):
 export function ${componentIdent}(props: {
@@ -8992,8 +9249,8 @@ function recordedTextSlots(setDir, repSlugs) {
 }
 function authorTaskFromSet(setDir, opts = {}) {
   if (opts.fonts === void 0) {
-    const resolved = resolvedFontFamilies().map((f) => f.family);
-    if (resolved.length > 0) opts = { ...opts, fonts: resolved };
+    const resolvedFaces = resolvedFontFamilies();
+    if (resolvedFaces.length > 0) opts = { ...opts, fonts: resolvedFaces.map((f) => f.family), providedFaces: resolvedFaces.map((f) => ({ family: f.family, weights: [...f.weights] })) };
   }
   const manifest = loadManifest(setDir);
   const poses = [];
@@ -9025,6 +9282,15 @@ function authorTaskFromSet(setDir, opts = {}) {
     poses,
     ...latticeNames !== void 0 ? { latticeNames } : {},
     ...opts.fonts !== void 0 ? { fonts: opts.fonts } : {},
+    ...opts.providedFaces !== void 0 ? { providedFaces: opts.providedFaces } : {},
+    ...(() => {
+      try {
+        const needs = recordedFontNeeds(setDir);
+        return needs.length > 0 ? { recordedFaces: needs } : {};
+      } catch {
+        return {};
+      }
+    })(),
     ...recordedFonts.length > 0 ? { recordedFonts } : {},
     ...Object.keys(defaults).length > 0 ? { defaults } : {},
     ...textSlots.length > 0 ? { textSlots } : {},
@@ -9522,7 +9788,9 @@ function countLatticeSymbols(setDir) {
   const manifestFile = path30.join(setDir, "recording-set.json");
   if (existsSync24(manifestFile)) {
     try {
-      const lattice = JSON.parse(readFileSync20(manifestFile, "utf8")).latticeNames;
+      const stored = JSON.parse(readFileSync20(manifestFile, "utf8"));
+      if (stored.variantScope !== "component-set") return null;
+      const lattice = stored.latticeNames;
       if (lattice !== void 0 && lattice.length > 0) return lattice.length;
     } catch {
     }
@@ -10091,10 +10359,76 @@ var init_src7 = __esm({
   }
 });
 
+// packages/cli/src/font-guidance.ts
+import path31 from "node:path";
+function fontsUnprovenRemediation(setDir) {
+  const set = setDir === void 0 ? void 0 : path31.resolve(setDir);
+  if (set !== void 0) {
+    try {
+      const needs = recordedFontNeeds(set);
+      if (needs.length > 0) {
+        const families = needs.map((n) => `"${n.family}"`).join(", ");
+        return `Run \`${tendrilCommand(`fonts resolve --set ${set}`)}\` \u2014 the recording declares ${families}; faces land in ${DEFAULT_FONT_CACHE}.`;
+      }
+    } catch {
+    }
+  }
+  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 {
+    const families = recordedFontFamilies(setDir);
+    return families.length > 0 ? families : null;
+  } catch {
+    return null;
+  }
+}
+function unprovisionedFamilies(setDir, cacheDir) {
+  const declared = taskFontFamilies(setDir);
+  if (declared === null) return [];
+  const provided = new Set(verifiedFontFamilies(cacheDir).map((f) => f.family.toLowerCase()));
+  return declared.filter((f) => !provided.has(f.toLowerCase()));
+}
+function unprovisionedFaces(setDir, cacheDir) {
+  return [
+    ...unprovisionedFamilies(setDir, cacheDir),
+    ...missingWeights(setDir, cacheDir).map((g) => {
+      const missing = g.declared.filter((w) => !g.provided.includes(w));
+      return `${g.family} (${missing.length === 1 ? "weight" : "weights"} ${missing.join(", ")})`;
+    })
+  ];
+}
+function missingWeights(setDir, cacheDir) {
+  let needs;
+  try {
+    needs = recordedFontNeeds(setDir, { pairedOnly: true });
+  } catch {
+    return [];
+  }
+  const provided = new Map(verifiedFontFamilies(cacheDir).map((f) => [f.family.toLowerCase(), f.weights]));
+  const gaps = [];
+  for (const n of needs) {
+    const have = provided.get(n.family.toLowerCase());
+    if (have === void 0) continue;
+    if (n.weights.some((w) => !have.includes(w))) gaps.push({ family: n.family, declared: n.weights, provided: have });
+  }
+  return gaps;
+}
+var init_font_guidance = __esm({
+  "packages/cli/src/font-guidance.ts"() {
+    "use strict";
+    init_src4();
+    init_src7();
+    init_invocation();
+  }
+});
+
 // packages/cli/src/commands/fonts.ts
 var fonts_exports = {};
 __export(fonts_exports, {
   DEFAULT_FONT_CACHE: () => DEFAULT_FONT_CACHE,
+  familyMismatch: () => familyMismatch,
   runFontsAdd: () => runFontsAdd,
   runFontsRequired: () => runFontsRequired,
   runFontsResolve: () => runFontsResolve,
@@ -10102,7 +10436,7 @@ __export(fonts_exports, {
   runFontsStatus: () => runFontsStatus
 });
 import { existsSync as existsSync25, readFileSync as readFileSync21 } from "node:fs";
-import path31 from "node:path";
+import path32 from "node:path";
 async function runFontsResolve(opts) {
   const result = await resolveFonts(opts.family, opts.weights, opts.cacheDir);
   emitData(opts, result, () => {
@@ -10117,7 +10451,7 @@ async function runFontsResolve(opts) {
   }
 }
 async function runFontsResolveSet(opts) {
-  const setDir = path31.resolve(process.env["INIT_CWD"] ?? process.cwd(), opts.set);
+  const setDir = path32.resolve(process.env["INIT_CWD"] ?? process.cwd(), opts.set);
   let needs = [];
   try {
     needs = recordedFontNeeds(setDir);
@@ -10190,7 +10524,7 @@ async function runFontsResolveSet(opts) {
   }
 }
 function runFontsStatus(opts) {
-  const manifestPath2 = path31.join(opts.cacheDir, "manifest.json");
+  const manifestPath2 = path32.join(opts.cacheDir, "manifest.json");
   if (!existsSync25(manifestPath2)) {
     fail(opts, ExitCode.FontsUnproven, {
       error: `no font cache at ${opts.cacheDir}`,
@@ -10199,7 +10533,7 @@ function runFontsStatus(opts) {
     });
   }
   const faces = JSON.parse(readFileSync21(manifestPath2, "utf8"));
-  const lockVerdicts = opts.lock !== void 0 ? checkFontLock(path31.resolve(opts.lock), opts.cacheDir) : null;
+  const lockVerdicts = opts.lock !== void 0 ? checkFontLock(path32.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)
 `);
@@ -10222,10 +10556,45 @@ function runFontsRequired(opts) {
   });
   if (missing.length > 0) process.exit(ExitCode.FontsUnproven);
 }
+function editDistance(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const row = new Array(b.length + 1).fill(0);
+  for (let i = 1; i <= a.length; i++) {
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = row[j];
+  }
+  return prev[b.length];
+}
+function familyMismatch(family, declared) {
+  if (declared.length === 0) return void 0;
+  if (declared.some((d) => d.toLowerCase() === family.toLowerCase())) return void 0;
+  const ranked = declared.map((d) => ({ d, score: editDistance(family.toLowerCase(), d.toLowerCase()) })).sort((a, b) => a.score - b.score);
+  const best = ranked[0];
+  return best.score <= Math.max(3, Math.floor(family.length / 3)) ? { nearest: best.d } : {};
+}
 function runFontsAdd(opts) {
+  if (opts.set !== void 0) {
+    const declared = taskFontFamilies(path32.resolve(opts.set)) ?? [];
+    const mismatch = familyMismatch(opts.family, declared);
+    if (mismatch !== void 0) {
+      fail(opts, ExitCode.InputValidation, {
+        error: `the recording set does not declare a family named "${opts.family}" \u2014 it declares ${declared.map((d) => `"${d}"`).join(", ")}. Adding it under this name would cache a face the mount never matches, and scoring would keep refusing for the family that is still missing.`,
+        code: "font-family-not-declared",
+        remediation: mismatch.nearest !== void 0 ? `Did you mean "${mismatch.nearest}"? ${tendrilCommand(`fonts add "${mismatch.nearest}" ${opts.weight} ${opts.file} --set ${path32.resolve(opts.set)}`)}` : `Use one of the declared families exactly as the recording spells it, or drop --set to add a family this set does not declare.`
+      });
+    }
+  } else {
+    warn(
+      opts,
+      `family "${opts.family}" was NOT checked against a recording \u2014 pass --set <recording-dir> to have the spelling verified, since a face cached under a name the mount does not match leaves scoring refusing for a family that still looks provided`
+    );
+  }
   let face;
   try {
-    face = addLocalFont(opts.family, opts.weight, opts.file, opts.cacheDir);
+    face = addLocalFont(opts.family, opts.weight, opts.file, opts.cacheDir, opts.face);
   } catch (err) {
     fail(opts, ExitCode.InputValidation, {
       error: err instanceof Error ? err.message : String(err),
@@ -10248,71 +10617,7 @@ 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) {
-  const set = setDir === void 0 ? void 0 : path32.resolve(setDir);
-  if (set !== void 0) {
-    try {
-      const needs = recordedFontNeeds(set);
-      if (needs.length > 0) {
-        const families = needs.map((n) => `"${n.family}"`).join(", ");
-        return `Run \`${tendrilCommand(`fonts resolve --set ${set}`)}\` \u2014 the recording declares ${families}; faces land in ${DEFAULT_FONT_CACHE}.`;
-      }
-    } catch {
-    }
-  }
-  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 {
-    const families = recordedFontFamilies(setDir);
-    return families.length > 0 ? families : null;
-  } catch {
-    return null;
-  }
-}
-function unprovisionedFamilies(setDir, cacheDir) {
-  const declared = taskFontFamilies(setDir);
-  if (declared === null) return [];
-  const provided = new Set(verifiedFontFamilies(cacheDir).map((f) => f.family.toLowerCase()));
-  return declared.filter((f) => !provided.has(f.toLowerCase()));
-}
-function unprovisionedFaces(setDir, cacheDir) {
-  return [
-    ...unprovisionedFamilies(setDir, cacheDir),
-    ...missingWeights(setDir, cacheDir).map((g) => {
-      const missing = g.declared.filter((w) => !g.provided.includes(w));
-      return `${g.family} (${missing.length === 1 ? "weight" : "weights"} ${missing.join(", ")})`;
-    })
-  ];
-}
-function missingWeights(setDir, cacheDir) {
-  let needs;
-  try {
-    needs = recordedFontNeeds(setDir, { pairedOnly: true });
-  } catch {
-    return [];
-  }
-  const provided = new Map(verifiedFontFamilies(cacheDir).map((f) => [f.family.toLowerCase(), f.weights]));
-  const gaps = [];
-  for (const n of needs) {
-    const have = provided.get(n.family.toLowerCase());
-    if (have === void 0) continue;
-    if (n.weights.some((w) => !have.includes(w))) gaps.push({ family: n.family, declared: n.weights, provided: have });
-  }
-  return gaps;
-}
-var init_font_guidance = __esm({
-  "packages/cli/src/font-guidance.ts"() {
-    "use strict";
-    init_src4();
-    init_src7();
+    init_font_guidance();
     init_invocation();
   }
 });
@@ -10328,6 +10633,7 @@ __export(verify_exports, {
   failureTally: () => failureTally,
   foldConfigStatus: () => foldConfigStatus,
   interactionCoverage: () => interactionCoverage,
+  latticeCoverage: () => latticeCoverage,
   occlusionReport: () => occlusionReport,
   operabilityLine: () => operabilityLine,
   operabilityReport: () => operabilityReport,
@@ -10425,6 +10731,21 @@ function checkSummarySegments(input) {
   const operability = "short" in input.operability ? `operability UNVERIFIED (${input.operability.short})` : `operability ${input.operability.passed}/${input.operability.checks} interaction`;
   return ` \xB7 ${operability} \xB7 ${composition} \xB7 ${occlusion}`;
 }
+function latticeCoverage(setManifest, scoredConfigs) {
+  const lattice = setManifest.latticeNames?.length;
+  const established = setManifest.variantScope === "component-set";
+  const notRecorded = setManifest.notRecorded !== void 0 && setManifest.notRecorded !== "" ? { notRecorded: setManifest.notRecorded } : {};
+  if (lattice === void 0) return { latticeConfigs: null, ...notRecorded };
+  if (established) return { latticeConfigs: lattice, unrecordedConfigs: Math.max(0, lattice - scoredConfigs), ...notRecorded };
+  return {
+    latticeConfigs: null,
+    // The count is still worth reporting — it is just not a
+    // denominator, and the name has to stop implying that it is.
+    variantsPlanned: lattice,
+    latticeUnestablished: setManifest.variantScope === "selection" ? "the recording was planned from a node SELECTION, not from a component set \u2014 the plan counted the nodes it was handed and could not see whether the set holds more variants, so the number of unrecorded poses is UNKNOWN, not zero" : "this set was planned before variant scope was recorded, so whether its lattice came from a component set or from a handed-in selection was never established \u2014 the number of unrecorded poses is unknown, not zero",
+    ...notRecorded
+  };
+}
 function occlusionReport(occlusion) {
   if (occlusion.length === 0) {
     return {
@@ -10685,12 +11006,7 @@ async function runVerify(opts) {
       // itself — not only in a long-gone plan output.
       ...(() => {
         try {
-          const setManifest = loadManifest(task.set);
-          const lattice = setManifest.latticeNames?.length;
-          return {
-            ...lattice !== void 0 ? { latticeConfigs: lattice, unrecordedConfigs: Math.max(0, lattice - statuses.length) } : { latticeConfigs: null },
-            ...setManifest.notRecorded !== void 0 && setManifest.notRecorded !== "" ? { notRecorded: setManifest.notRecorded } : {}
-          };
+          return latticeCoverage(loadManifest(task.set), statuses.length);
         } catch {
           return { latticeConfigs: null };
         }
@@ -10991,6 +11307,7 @@ ${notRecorded}` : "";
 === TASK PAYLOAD (recorded truth, verbatim) ===
 ${segments}`;
   const payloadFile = path34.resolve(callerCwd, opts.out ?? `tendril-out/${name}-brief.md`);
+  const candidateDirSuggestion = path34.resolve(callerCwd, `tendril-out/${name}-candidate`);
   mkdirSync8(path34.dirname(payloadFile), { recursive: true });
   writeFileSync12(payloadFile, payload);
   emitData(
@@ -11019,8 +11336,16 @@ ${segments}`;
       protocol: [
         "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 \`${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.`,
+        `Write the complete bundle files (${task.entry}, styles.css, optional tokens.css) into ${quoteArg(candidateDirSuggestion)} (create it with a bare \`mkdir -p\`), or into another directory if you were handed one.`,
+        // Both paths quoted, and the candidate directory NAMED rather
+        // than left as `<candidateDir>`: run 18 worked in a folder
+        // called "Test 2", where the unquoted form split into two
+        // arguments, and a placeholder is the other half of the same
+        // defect — a command the reader has to finish is one they can
+        // finish wrongly.
+        `Run \`${tendrilCommand(
+          `engine score ${quoteArg(ref)} ${quoteArg(candidateDirSuggestion)} --bar ${opts.bar} --model ${opts.model ?? "<declared-model>"} --json`
+        )}\` \u2014 the CLI is the sole judge, and it refuses to score an undeclared model. If you wrote the bundle elsewhere, pass that directory instead.`,
         "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."
       ]
@@ -11144,7 +11469,21 @@ METRIC DEADBAND (read before iterating on near-misses): the scored similarity/in
     {
       task: name,
       bar: opts.bar,
-      objective: { passCount: obj[0], total, floor: obj[1], mean: obj[2] },
+      // `total` is pixel configs PLUS behaviour checks, and nothing said
+      // so: run 18's operator relayed "6/16" for two rounds without
+      // knowing it meant ZERO configs passing — materially worse than it
+      // sounds, and the number a human decides whether to keep paying on.
+      objective: {
+        passCount: obj[0],
+        total,
+        pixelConfigs: scores.length,
+        pixelConfigsPassing: scores.filter((s) => s.pass).length,
+        behaviorChecks: behaviors.length,
+        behaviorChecksPassing: behaviors.filter((b) => b.pass).length,
+        note: `passCount/total counts ${scores.length} pixel config(s) AND ${behaviors.length} behaviour check(s) together \u2014 read pixelConfigsPassing to see how many CONFIGS pass`,
+        floor: obj[1],
+        mean: obj[2]
+      },
       scores,
       behaviors,
       feedback,
@@ -13278,11 +13617,19 @@ function buildProgram() {
       await runFontsResolve2({ ...flags, family, weights: local["weights"].map(Number), cacheDir });
     }
   });
-  fonts.command("add").description("Register a font file you already license, so a kit using a proprietary face can be scored.").argument("<family>", 'font family name as the design uses it, e.g. "S\xF6hne"').argument("<weight>", "numeric weight, e.g. 400").argument("<file>", "path to a .woff2/.woff/.ttf/.otf you are licensed to use").option("--cache <dir>", "cache directory (default: the per-user font cache)").action(async (family, weight, file, _o, cmd) => {
+  fonts.command("add").description("Register a font file you already license, so a kit using a proprietary face can be scored.").argument("<family>", 'font family name as the design uses it, e.g. "S\xF6hne"').argument("<weight>", "numeric weight, e.g. 400").argument("<file>", "path to a .woff2/.woff/.ttf/.otf you are licensed to use").option("--cache <dir>", "cache directory (default: the per-user font cache)").option("--set <dir>", "recording set to verify the family spelling against \u2014 a face cached under a name the mount never matches leaves scoring refusing").option("--face <index>", "which face to lift out of a .ttc collection (the error lists them)").action(async (family, weight, file, _o, cmd) => {
     const flags = globalFlags(cmd.parent.parent);
     const local = cmd.opts();
     const { runFontsAdd: runFontsAdd2 } = await Promise.resolve().then(() => (init_fonts(), fonts_exports));
-    runFontsAdd2({ ...flags, family, weight: Number(weight), file, cacheDir: local["cache"] ?? DEFAULT_FONT_CACHE });
+    runFontsAdd2({
+      ...flags,
+      family,
+      weight: Number(weight),
+      file,
+      cacheDir: local["cache"] ?? DEFAULT_FONT_CACHE,
+      ...local["set"] !== void 0 ? { set: local["set"] } : {},
+      ...local["face"] !== void 0 ? { face: Number(local["face"]) } : {}
+    });
   });
   fonts.command("status").option("--lock <file>", "hash lock to verify against (e.g. packages/verify/fixtures/fonts.lock.json)").option("--cache <dir>", "cache directory (default: the per-user font cache)").action(async (_o, cmd) => {
     const flags = globalFlags(cmd.parent.parent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tendrilapp/cli",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Figma design systems → verified React components. CLI ruler + MCP server.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",