@tendrilapp/cli 0.1.28 → 0.1.30

package/dist/SKILL.md

@@ -29,7 +29,13 @@ settings file the host merges — the project's
 user's `~/.claude/settings.json` — contains tendril MCP entries
 (plugin installs use `mcp__plugin_tendril_tendril__*`; direct
 `claude mcp add` installs use `mcp__<server-name>__*`) AND shell-
-surface entries (`Bash(ls:*)`-style prefixes plus `Write`/`Edit`).
+surface entries (`Bash(ls:*)`-style prefixes plus `Write`/`Edit`)
+AND Figma entries under the prefix THIS session's Figma tools
+actually carry — take a Figma tool you can see (e.g. get_metadata)
+and check its full `mcp__…` name against the allowlist; entries
+under a different server's prefix are dead and DO NOT count (a
+measured session held six such entries while every Figma call
+prompted).
 THE MCP LIST ALONE IS NOT "PERMISSIONS ARE FINE": a run is mostly
 shell — mkdir, evidence reads, log writes, the printed npx commands —
 and a measured session whose every MCP call was covered still put
@@ -40,17 +46,22 @@ and offer `tendril_permissions` with `write: true` — it merges the
 per-tool allowlist PLUS the run's shell surface and project-scoped
 Write/Edit (with deny guards so that grant can never touch
 `./.claude/**` or `./.git/**`) into the project's
-settings.local.json (idempotent, touches nothing else; note it
-writes PLUGIN-prefixed names — a direct-install user should run
-`tendril permissions --claude` and adapt the prefix instead). These
-are CONVENIENCE grants, not a security boundary — the command's
-output names what they trade (read verbs read any file without
-prompting; host Bash patterns are best-effort prefix matches; the
-CLI subcommand grants carry the CLI's own write surface). RELAY that
-note to the user with the offer, never soften it, and say the user
-must reload the session to apply. Offer ONCE per session; never run
-it unoffered (it edits the user's settings), and if declined,
-proceed without mentioning it again.
+settings.local.json (idempotent, touches nothing else). PREFIXES:
+pass `figmaPrefix` (and `tendrilPrefix` for non-plugin installs)
+spelled exactly as THIS session names those tools — the part before
+`__get_metadata` — whenever they differ from the plugin defaults; a
+measured figma-remote session got six entries that could never
+match because the write assumed the plugin shape. These are
+CONVENIENCE grants, not a security boundary — the command's output
+names what they trade (read verbs read any file without prompting;
+host Bash patterns are best-effort prefix matches; the CLI
+subcommand grants carry the CLI's own write surface). RELAY that
+note to the user with the offer, never soften it, and say BOTH that
+a reload is required AND that the current session keeps prompting
+until then — the savings land next session; that is expected, not a
+failure. Offer ONCE per session; never run it unoffered (it edits
+the user's settings), and if declined, proceed without mentioning
+it again.
 
 Long generator/score waits: silence is not a health signal, and POLL
 cadence is not RELAY cadence (run 13: rounds landed 6–11 minutes apart,
@@ -243,8 +254,13 @@ Batch runs (several components in one session):
    CSS. Import every React API you use.
 3. `tendril_engine_score` → read the per-config results and feedback.
    Fix FAIL configs without regressing PASS configs; re-score.
-4. Stop when `allPass` is true, or after two consecutive rounds with
-   no improvement — then report the honest final state.
+4. Stop when `allPass` is true. Two consecutive rounds with no
+   improvement is a TRIGGER TO INSPECT, not to stop: open the
+   verify-evidence diff images for the worst configs and look before
+   deciding (a measured run scored byte-identical twice, inspected
+   the diffs, and round 3 went 27/27 certified — a stop rule would
+   have shipped 5/27). Stop only after an inspection round produced
+   no fix hypothesis — then report the honest final state.
 5. MODEL SELECTION — mechanical AND asked. `engine brief` and
    `engine score` refuse to run without a declared model, so the
    choice must be settled first. When a user is present, ask before

package/dist/tendril-mcp.js

@@ -66,11 +66,19 @@ var TOOLS = [
   },
   {
     name: "tendril_permissions",
-    description: "Install the Claude Code permission allowlist for the Tendril pipeline (write: true \u2014 merges the MCP per-tool entries, the run's shell surface, and project-scoped Write/Edit with deny guards for ./.claude and ./.git into the project's .claude/settings.local.json, idempotent, never touches other keys), or list the entries without writing. The shell/Write grants are CONVENIENCE, not a security boundary \u2014 the output's note names exactly what they trade; RELAY it with the offer. OFFER THIS AT PIPELINE START whenever NO merged Claude settings file (project .claude/settings.local.json or .claude/settings.json, or user ~/.claude/settings.json) contains tendril MCP entries \u2014 plugin installs use mcp__plugin_tendril_tendril__*, direct claude-mcp-add installs use mcp__<server>__* (for those, write:true installs PLUGIN-prefixed names that will not match: list without writing and adapt the prefix instead). A FILE check, never prompt-watching \u2014 agents cannot observe permission prompts. ONE approval here replaces a prompt per pipeline call. Never run it unoffered; the user must reload the session for new settings to apply \u2014 say so.",
+    description: "Install the Claude Code permission allowlist for the Tendril pipeline (write: true \u2014 merges the MCP per-tool entries, the run's shell surface, and project-scoped Write/Edit with deny guards for ./.claude and ./.git into the project's .claude/settings.local.json, idempotent, never touches other keys), or list the entries without writing. The shell/Write grants are CONVENIENCE, not a security boundary \u2014 the output's note names exactly what they trade; RELAY it with the offer. OFFER THIS AT PIPELINE START whenever NO merged Claude settings file (project .claude/settings.local.json or .claude/settings.json, or user ~/.claude/settings.json) contains tendril MCP entries \u2014 plugin installs use mcp__plugin_tendril_tendril__*, direct claude-mcp-add installs use mcp__<server>__* \u2014 when this session's tool names differ from the plugin defaults, pass figmaPrefix/tendrilPrefix with the prefixes you actually see, or the written entries never match. A FILE check, never prompt-watching \u2014 agents cannot observe permission prompts. ONE approval here replaces a prompt per pipeline call. Never run it unoffered; the user must reload the session for new settings to apply \u2014 say so.",
     schema: z.object({
-      write: z.boolean().optional().describe("true = install into .claude/settings.local.json (the point of this tool); false/absent = just return the entries")
+      write: z.boolean().optional().describe("true = install into .claude/settings.local.json (the point of this tool); false/absent = just return the entries"),
+      figmaPrefix: z.string().optional().describe("The Figma server's entry prefix AS THIS SESSION NAMES ITS TOOLS \u2014 the part before __get_metadata (e.g. mcp__figma-remote, mcp__plugin_figma_figma). Pass it whenever the session's Figma tools are not mcp__plugin_figma_figma__* \u2014 entries written under the wrong prefix never match anything (measured: six dead entries in a figma-remote session)."),
+      tendrilPrefix: z.string().optional().describe("Same for the tendril server when this session's tendril tools are not mcp__plugin_tendril_tendril__* (e.g. mcp__tendril for claude mcp add installs).")
     }),
-    argv: (i) => ["permissions", "--claude", ...i["write"] === true ? ["--write"] : []]
+    argv: (i) => [
+      "permissions",
+      "--claude",
+      ...i["write"] === true ? ["--write"] : [],
+      ...typeof i["figmaPrefix"] === "string" ? ["--figma-prefix", i["figmaPrefix"]] : [],
+      ...typeof i["tendrilPrefix"] === "string" ? ["--tendril-prefix", i["tendrilPrefix"]] : []
+    ]
   },
   {
     name: "tendril_doctor",
@@ -195,7 +203,7 @@ var TOOLS = [
   {
     name: "tendril_record_status",
     annotations: { readOnlyHint: true },
-    description: "Recording-set completeness: per-rep recorded/missing tools.",
+    description: "Recording-set completeness: per-rep recorded/missing tools, files that exist but are unusable (invalid \u2014 re-record those), and whether the set-level token map is recorded. `complete` means USABLE by the next pipeline step, including the set-level get_variable_defs.",
     schema: z.object({ setDir: str("recording set directory") }),
     argv: (i) => ["record", "status", "--set", i["setDir"]]
   },

package/dist/tendril.js

@@ -1083,14 +1083,54 @@ function planSet(setDir, component, symbols, opts = {}) {
   writeManifest(setDir, manifest);
   return { manifest, plan, resumed: false };
 }
+function usableEnvelope(file, tool) {
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return { ok: false, reason: "the recorded file is not JSON" };
+  }
+  const schema = tool === "get_screenshot" ? ImageEnvelopeSchema : TextEnvelopeSchema;
+  if (!schema.safeParse(payload).success) {
+    return { ok: false, reason: "not a verbatim tool envelope (structure the ingest boundary would refuse)" };
+  }
+  const content = checkEnvelopeContent(tool, payload);
+  if (!content.ok) return { ok: false, reason: content.reason };
+  if (tool === "get_metadata" && !/name="/.test(envelopeTextContent(payload))) {
+    return { ok: false, reason: "node markup carries no name attribute \u2014 task authoring cannot derive the pose" };
+  }
+  return { ok: true };
+}
 function sessionStatus(setDir) {
   const manifest = loadManifest(setDir);
   const reps = manifest.reps.map((rep) => {
-    const recorded = RECORD_TOOLS.filter((t) => existsSync(path.join(setDir, rep.slug, `${t}.json`)));
-    const missing = byProtocolOrder(requiredToolsFor(manifest, rep.slug).filter((t) => !recorded.includes(t)));
-    return { slug: rep.slug, nodeId: rep.nodeId, recorded, missing };
+    const required = requiredToolsFor(manifest, rep.slug);
+    const invalid = [];
+    const recorded = RECORD_TOOLS.filter((t) => {
+      const file = path.join(setDir, rep.slug, `${t}.json`);
+      if (!existsSync(file)) return false;
+      const usable = usableEnvelope(file, t);
+      if (!usable.ok) {
+        invalid.push({
+          tool: t,
+          reason: required.includes(t) ? usable.reason : `${usable.reason} (optional for this rep \u2014 not counted against completeness; re-record only if you need this evidence)`
+        });
+        return false;
+      }
+      return true;
+    });
+    const missing = byProtocolOrder(required.filter((t) => !recorded.includes(t)));
+    return { slug: rep.slug, nodeId: rep.nodeId, recorded, missing, ...invalid.length > 0 ? { invalid } : {} };
   });
-  return { reps, complete: reps.every((r) => r.missing.length === 0) };
+  const setDefsFile = path.join(setDir, "get_variable_defs.json");
+  const setDefs = existsSync(setDefsFile) ? usableEnvelope(setDefsFile, "get_variable_defs") : { ok: false, reason: "never recorded" };
+  const setTokenMapRecorded = setDefs.ok;
+  return {
+    reps,
+    setTokenMapRecorded,
+    ...!setDefs.ok && setDefs.reason !== "never recorded" ? { setTokenMapInvalid: setDefs.reason } : {},
+    complete: reps.every((r) => r.missing.length === 0) && setTokenMapRecorded
+  };
 }
 function nextInstruction(setDir) {
   const { reps } = sessionStatus(setDir);
@@ -2192,6 +2232,8 @@ async function runTokenLint(css, fileLabel = "generated.css", definedVars2, reco
         property: "custom-property-ident",
         message: `var(${name}) is not a legal custom property reference \u2014 the browser drops the whole declaration`
       });
+    } else if (name.startsWith("--tendril-")) {
+      continue;
     } else if (definedVars2 !== void 0 && !definedVars2.has(name) && !ownDefs.has(name)) {
       violations.push({
         file: fileLabel,
@@ -3615,9 +3657,12 @@ function weightFromSubfamily(subfamily) {
   return void 0;
 }
 function systemFaceRefusal(family) {
-  if (/^\.?SF([ -]|$)/i.test(family) || /^San Francisco/i.test(family) || /^\.?Apple/i.test(family) || /^\.?New York$/i.test(family)) {
+  if (/^\.?SF(NS|[ -]|$)/i.test(family) || /^San Francisco/i.test(family) || /^\.?Apple/i.test(family) || /^\.?New York\b/i.test(family) || /^\.?System Font\b/i.test(family)) {
     return "Apple's bundled system faces (San Francisco, New York, the Apple-named families) are licensed only for mock-ups of interfaces running on Apple operating systems, by registered Apple developers \u2014 a grant Tendril cannot verify, so these faces are never cached (ROADMAP 0i).";
   }
+  if (/^\./.test(family)) {
+    return "dot-prefixed families are the operating system's own hidden UI faces (macOS marks internal faces with a leading dot) \u2014 not user-licensable, so they are never cached (ROADMAP 0i).";
+  }
   if (/^Segoe UI Variable/i.test(family)) {
     return "Segoe UI Variable cannot be licensed for use outside Microsoft products at all \u2014 an 'I have the rights' assertion has nothing it could attach to, so it is never cached (ROADMAP 0i).";
   }
@@ -3943,7 +3988,7 @@ function verifiedFontFamilies(cacheDir = DEFAULT_FONT_CACHE) {
   return [...byFamily.entries()].map(([family, w]) => ({ family, weights: [...w].sort((a, b) => a - b) }));
 }
 function addSystemFamily(family, opts = {}) {
-  const refusal = systemFaceRefusal(family);
+  const refusal = systemFaceRefusal(family.trim());
   if (refusal !== void 0) return { added: [], skipped: [], overwrote: [], refusal };
   const plainStyle = (sub) => weightFromSubfamily(sub) !== void 0 || /^(regular|plain|)$/i.test(sub.trim());
   const faces = [...systemFacesForFamily(family, opts.dirs)].sort((a, b) => {
@@ -3961,6 +4006,11 @@ function addSystemFamily(family, opts = {}) {
   const taken = /* @__PURE__ */ new Set();
   for (const face of faces) {
     const skip = (reason) => skipped.push({ subfamily: face.subfamily, weight: face.weight, reason });
+    const faceRefusal = systemFaceRefusal(face.family.trim());
+    if (faceRefusal !== void 0) {
+      skip(`refusal-class family \u2014 ${faceRefusal}`);
+      continue;
+    }
     if (opts.weights !== void 0 && !opts.weights.includes(face.weight)) continue;
     if (face.italic) {
       skip("italic \u2014 the cache cannot represent italic faces end to end yet; the upright face serves the family");
@@ -8129,10 +8179,11 @@ 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 && !existsSync21(path27.join(setDir, "get_variable_defs.json"))) {
+  if (instruction === null && !status.setTokenMapRecorded) {
     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 };
+    const invalidNote = status.setTokenMapInvalid !== void 0 ? ` (the existing set-level file is UNUSABLE \u2014 ${status.setTokenMapInvalid} \u2014 re-record it)` : "";
+    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__.${invalidNote} ${ENVELOPE_HELP}`, progress };
   }
   return instruction === null ? { complete: true, progress } : {
     ...instruction,
@@ -8152,7 +8203,7 @@ function runRecordNext(opts) {
   const payload = nextPayload(opts.setDir);
   emitData(opts, payload, () => {
     if (payload["complete"] === true) {
-      process.stdout.write("set complete \u2014 every planned rep has its required envelopes\n");
+      process.stdout.write("set complete \u2014 every planned rep has its required envelopes, all usable, and the set-level token map is recorded\n");
       return;
     }
     const progress = payload["progress"];
@@ -8446,10 +8497,21 @@ function runRecordStatus(opts) {
     for (const r of status.reps) {
       process.stdout.write(`${r.missing.length === 0 ? "DONE " : "TODO "} ${r.slug.padEnd(24)} recorded=[${r.recorded.join(",")}]${r.missing.length > 0 ? ` missing=[${r.missing.join(",")}]` : ""}
 `);
-    }
-    process.stdout.write(status.complete ? "\nset complete\n" : `
-${status.reps.filter((r) => r.missing.length > 0).length} rep(s) pending
+      for (const inv of r.invalid ?? []) {
+        process.stdout.write(`         ${r.slug}/${inv.tool}: recorded file is UNUSABLE \u2014 ${inv.reason} (re-record this call)
 `);
+      }
+    }
+    const pending = status.reps.filter((r) => r.missing.length > 0).length;
+    process.stdout.write(
+      status.complete ? "\nset complete\n" : pending > 0 ? `
+${pending} rep(s) pending
+` : status.setTokenMapInvalid !== void 0 ? `
+all reps recorded, but the SET-LEVEL token map file is UNUSABLE (${status.setTokenMapInvalid}) \u2014 re-record it via \`record next\`
+` : `
+all reps recorded, but the SET-LEVEL token map is missing \u2014 run \`record next\` for the get_variable_defs step (without it briefs ship an empty token table)
+`
+    );
   });
 }
 function narrowedRoles(derived, override) {
@@ -9260,6 +9322,9 @@ function authorBehaviors(api, extras = {}) {
 function envelopeText(file) {
   return envelopeFirstTextPart(JSON.parse(readFileSync19(file, "utf8")));
 }
+function metadataText(file) {
+  return envelopeTextContent(JSON.parse(readFileSync19(file, "utf8")));
+}
 function dismissEvidence(setDir, repSlugs) {
   for (const slug of repSlugs) {
     const f = path29.join(setDir, slug, "get_design_context.json");
@@ -9381,7 +9446,7 @@ function recordedTextSlots(setDir, repSlugs) {
   for (const slug of repSlugs) {
     const metaFile = path29.join(setDir, slug, "get_metadata.json");
     if (!existsSync23(metaFile)) continue;
-    const name = symbolName(envelopeText(metaFile));
+    const name = symbolName(metadataText(metaFile));
     if (name === void 0) continue;
     const values = /* @__PURE__ */ new Set();
     for (const part of name.split(",")) {
@@ -9484,7 +9549,7 @@ function authorTaskFromSet(setDir, opts = {}) {
       missing.push(rep.slug);
       continue;
     }
-    const name = symbolName(envelopeText(metaFile));
+    const name = symbolName(metadataText(metaFile));
     if (name === void 0) {
       missing.push(rep.slug);
       continue;
@@ -9495,7 +9560,7 @@ function authorTaskFromSet(setDir, opts = {}) {
     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 = path29.join(setDir, "get_metadata.json");
-  const latticeNames = manifest.latticeNames ?? (existsSync23(setMeta) ? [...envelopeText(setMeta).matchAll(/name="([^"]*)"/g)].map((m) => decodeXmlEntities(m[1])) : void 0);
+  const latticeNames = manifest.latticeNames ?? (existsSync23(setMeta) ? [...metadataText(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));
@@ -9951,7 +10016,7 @@ function fontsCssFor(faces, bundleDir, cacheDir = DEFAULT_FONT_CACHE, substitute
     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}'); }`;
     const license = normalizeFontLicense(face.license);
-    const terms = face.source.startsWith("system:") ? void 0 : REDISTRIBUTABLE.get(license);
+    const terms = face.source.startsWith("system:") || face.source.startsWith("local:") ? void 0 : REDISTRIBUTABLE.get(license);
     if (terms === void 0) {
       if (face.source.startsWith("system:")) {
         lines.push(
@@ -10677,11 +10742,17 @@ import { existsSync as existsSync26, readFileSync as readFileSync22 } from "node
 import path33 from "node:path";
 async function runFontsResolve(opts) {
   const result = await resolveFonts(opts.family, opts.weights, opts.cacheDir);
-  emitData(opts, result, () => {
+  const queryRefusal = systemFaceRefusal(opts.family.trim());
+  emitData(opts, { ...result, ...queryRefusal !== void 0 ? { queryRefusal } : {} }, () => {
     for (const f of result.resolved) process.stdout.write(`resolved ${f.family} ${f.weight} (${f.sha256.slice(0, 12)}\u2026)
 `);
     for (const f of result.failures) process.stdout.write(`FAILED  ${f.family} ${f.weight}: ${f.reason}
 `);
+    if (queryRefusal !== void 0 && result.failures.length > 0) {
+      process.stdout.write(`        "${opts.family}" is a refusal-class family: ${queryRefusal}
+        Options: proceed under a disclosed substitute (rules out certification), or register a file you license yourself: ${tendrilCommand(`fonts add ${quoteArg(opts.family)} <weight> <file>`)} \u2014 bundles declare the face and never carry its bytes.
+`);
+    }
   });
   if (result.failures.length > 0) {
     warn(opts, `${result.failures.length} face(s) unresolved \u2014 verification will refuse to score under substitution`);
@@ -10739,7 +10810,8 @@ async function runFontsResolveSet(opts) {
       unlicensed.push(...result.failures);
     }
   }
-  emitData(opts, { set: setDir, needs, cached: cached2, resolved, relicensed, unlicensed, failures }, () => {
+  const refusals = [...new Set(failures.map((f) => f.family))].map((family) => ({ family, reason: systemFaceRefusal(family.trim()) })).filter((r) => r.reason !== void 0);
+  emitData(opts, { set: setDir, needs, cached: cached2, resolved, relicensed, unlicensed, failures, ...refusals.length > 0 ? { refusals } : {} }, () => {
     process.stdout.write(`set declares: ${needs.map((n) => `${n.family} (${n.weights.join(", ")})`).join(" \xB7 ")}
 `);
     for (const f of cached2) process.stdout.write(`cached   ${f.family} ${f.weight}
@@ -10753,8 +10825,11 @@ async function runFontsResolveSet(opts) {
     for (const f of failures) process.stdout.write(`FAILED   ${f.family} ${f.weight}: ${f.reason}
 `);
     for (const fam of [...new Set(failures.map((f) => f.family))]) {
+      const refusal = systemFaceRefusal(fam);
       process.stdout.write(
-        `         if "${fam}" is installed on this machine: ${tendrilCommand(`fonts discover ${quoteArg(fam)}`)} then ${tendrilCommand(`fonts add-system ${quoteArg(fam)} --set ${quoteArg(setDir)}`)} (licence stays unknown; bundles declare, never copy)
+        refusal !== void 0 ? `         "${fam}" is a refusal-class family: ${refusal}
+         Options: proceed and let the mount substitute a provided face (disclosed; rules out certification), or register a file you license yourself: ${tendrilCommand(`fonts add ${quoteArg(fam)} <weight> <file>`)} \u2014 licensing is yours to judge; bundles declare the face and never carry its bytes.
+` : `         if "${fam}" is installed on this machine: ${tendrilCommand(`fonts discover ${quoteArg(fam)}`)} then ${tendrilCommand(`fonts add-system ${quoteArg(fam)} --set ${quoteArg(setDir)}`)} (licence stays unknown; bundles declare, never copy)
 `
       );
     }
@@ -10855,12 +10930,20 @@ function runFontsAdd(opts) {
   });
 }
 function runFontsDiscover(opts) {
-  const faces = opts.family !== void 0 ? systemFacesForFamily(opts.family) : discoverSystemFaces();
+  const faces = opts.family !== void 0 ? systemFacesForFamily(opts.family, opts.dirs) : discoverSystemFaces(opts.dirs);
   const rows = faces.map((f) => ({ ...f, ...systemFaceRefusal(f.family) !== void 0 ? { refused: systemFaceRefusal(f.family) } : {} }));
-  emitData(opts, { faces: rows, dirs: systemFontDirs() }, () => {
+  const queryRefusal = opts.family !== void 0 ? systemFaceRefusal(opts.family) : void 0;
+  emitData(opts, { faces: rows, dirs: opts.dirs ?? systemFontDirs(), ...queryRefusal !== void 0 ? { queryRefusal } : {} }, () => {
     if (rows.length === 0) {
-      process.stdout.write(`no matching system faces found (scanned: ${systemFontDirs().join(", ")})
+      process.stdout.write(`no matching system faces found (scanned: ${(opts.dirs ?? systemFontDirs()).join(", ")})
 `);
+      if (queryRefusal !== void 0) {
+        process.stdout.write(
+          `note: "${opts.family}" is a refusal-class family regardless \u2014 ${queryRefusal}
+      A file you license yourself can still be registered for local scoring: ${tendrilCommand(`fonts add ${quoteArg(opts.family ?? "")} <weight> <file>`)} \u2014 licensing is yours to judge, and bundles declare the face but never carry its bytes.
+`
+        );
+      }
       return;
     }
     for (const f of rows) {
@@ -11065,14 +11148,15 @@ 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 };
+  const 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" : setManifest.variantScope === "component-set" ? "the planner saw the component set and it declares no variant axes \u2014 the planned pose(s) are the whole set as Figma showed it, but there is no variant lattice to count" : "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";
+  if (lattice === void 0) return { latticeConfigs: null, latticeUnestablished, ...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",
+    latticeUnestablished,
     ...notRecorded
   };
 }
@@ -11472,9 +11556,14 @@ ${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuse
           `INCOMPLETE  ${cov.unrecordedConfigs} of ${cov.latticeConfigs} lattice poses were NEVER RECORDED \u2014 nothing verifies them; any implementation of those poses is inference, not verified truth. Re-plan the set (full matrix is the default) and record the missing poses.
 `
         );
-      } else if (cov.latticeConfigs === null) {
-        process.stdout.write(`COVERAGE  denominator unknown (set predates lattice tracking) \u2014 scored configs are verified; completeness is not established
+      } else if (typeof cov.latticeConfigs === "number") {
+        process.stdout.write(`LATTICE   all ${cov.latticeConfigs} poses of the component set's own lattice are recorded and scored \u2014 the denominator is the set's, not the recorded subset's
 `);
+      } else if (cov.latticeConfigs === null) {
+        process.stdout.write(
+          `COVERAGE  denominator unknown \u2014 ${cov.latticeUnestablished ?? "set predates lattice tracking"} \u2014 scored configs are verified; completeness is not established
+`
+        );
       }
     }
     process.stdout.write(`environment: chrome=${report.environment.chromeVersion ?? report.environment.chrome} fonts=${report.environment.fontsManifestSha256 ?? "UNRESOLVED"}
@@ -11683,7 +11772,7 @@ ${segments}`;
         `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.",
+        "Apply the returned feedback and re-score. Stop when all checks pass. Two consecutive non-improving scores mean INSPECT the verify-evidence diffs before deciding \u2014 stop only when inspection yields no fix hypothesis (a measured run was byte-identical twice, then went 27/27 after reading the diffs).",
         "Never edit recording sets; never claim scores yourself \u2014 only the score command's output counts."
       ]
     },
@@ -11696,7 +11785,10 @@ ${segments}`;
   );
 }
 function appendScoreHistory(candidateDir, entry) {
-  appendFileSync(path35.join(candidateDir, "score-history.jsonl"), `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
+  const file = path35.join(candidateDir, "score-history.jsonl");
+  const starts = existsSync28(file) ? readFileSync24(file, "utf8").split("\n").filter((l) => l.includes('"event":"round-start"')).length : 0;
+  const round = entry.event === "round-start" ? starts + 1 : Math.max(1, starts);
+  appendFileSync(file, `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), round, ...entry })}
 `);
 }
 async function runEngineScore(opts) {
@@ -11784,7 +11876,10 @@ ${absentFindings.join("\n")}` : "";
 
 CERTIFICATION: ${certifiedReps.length}/${scores.length} configs at the certification bar (sim \u2265${certBar.sim} AND ink \u2265${certBar.ink}, exact values, after parity demotion \u2014 composition checks at verify can demote further).${certifiedReps.length < scores.length ? ` Below cert: ${scores.filter((sc) => !certifiedSet.has(sc.rep)).map((sc) => sc.rep).join(", ")}.` : ""}
 METRIC DEADBAND (read before iterating on near-misses): the scored similarity/ink deliberately tolerate \xB11px edge shift and antialiased-edge differences \u2014 cross-rasterizer noise absorption. A change entirely inside that band moves these numbers by EXACTLY ZERO (working as designed, not a stuck scorer). The per-config \`exact\` fields in the JSON are tolerance-free and move first: compare exact across rounds to confirm a small fix landed, and stop iterating when only exact moves \u2014 the bar reads the tolerant numbers.`;
-  const feedback = buildFeedback(scores, behaviors, bar, "files") + certificationFeedback + qualityFeedback;
+  const stampNotice = `
+
+PROVENANCE STAMP: this scoring call itself (the Tendril CLI) just wrote/refreshed a comment on line 1 of styles.css carrying these scores, marked non-authoritative. If your editor or host reports styles.css was modified externally, that modification is this scorer \u2014 expected, not tampering. Keep the comment; it self-invalidates on any edit and \`tendril verify\` recomputes it.`;
+  const feedback = buildFeedback(scores, behaviors, bar, "files") + certificationFeedback + stampNotice + qualityFeedback;
   const emitted = emitBundleV1({
     bundleDir: candidateDir,
     task,
@@ -11849,7 +11944,7 @@ METRIC DEADBAND (read before iterating on near-misses): the scored similarity/in
       parityCoverage,
       evidenceDir,
       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",
+      note: "the Tendril CLI (this scoring call) wrote the bundle provenance comment onto styles.css line 1 \u2014 an EXPECTED external modification, not tampering; preserve it in any post-score edit (it self-invalidates on edit and verify recomputes it)",
       allPass,
       environment: { ...environmentStamp(taskFontFamilies(task.set)), ruler: cliVersion() },
       ...lcdTextEnabled() ? { environmentOverrides: ["enable-lcd-text"] } : {},
@@ -11977,7 +12072,7 @@ function runCodeConnect(opts) {
     const meta = path36.join(setDir, r.slug, "get_metadata.json");
     if (!existsSync29(meta)) return void 0;
     try {
-      return /name="([^"]*)"/.exec(envelopeFirstTextPart(JSON.parse(readFileSync25(meta, "utf8"))))?.[1];
+      return /name="([^"]*)"/.exec(envelopeTextContent(JSON.parse(readFileSync25(meta, "utf8"))))?.[1];
     } catch {
       return void 0;
     }
@@ -12164,11 +12259,19 @@ var init_server = __esm({
       },
       {
         name: "tendril_permissions",
-        description: "Install the Claude Code permission allowlist for the Tendril pipeline (write: true \u2014 merges the MCP per-tool entries, the run's shell surface, and project-scoped Write/Edit with deny guards for ./.claude and ./.git into the project's .claude/settings.local.json, idempotent, never touches other keys), or list the entries without writing. The shell/Write grants are CONVENIENCE, not a security boundary \u2014 the output's note names exactly what they trade; RELAY it with the offer. OFFER THIS AT PIPELINE START whenever NO merged Claude settings file (project .claude/settings.local.json or .claude/settings.json, or user ~/.claude/settings.json) contains tendril MCP entries \u2014 plugin installs use mcp__plugin_tendril_tendril__*, direct claude-mcp-add installs use mcp__<server>__* (for those, write:true installs PLUGIN-prefixed names that will not match: list without writing and adapt the prefix instead). A FILE check, never prompt-watching \u2014 agents cannot observe permission prompts. ONE approval here replaces a prompt per pipeline call. Never run it unoffered; the user must reload the session for new settings to apply \u2014 say so.",
+        description: "Install the Claude Code permission allowlist for the Tendril pipeline (write: true \u2014 merges the MCP per-tool entries, the run's shell surface, and project-scoped Write/Edit with deny guards for ./.claude and ./.git into the project's .claude/settings.local.json, idempotent, never touches other keys), or list the entries without writing. The shell/Write grants are CONVENIENCE, not a security boundary \u2014 the output's note names exactly what they trade; RELAY it with the offer. OFFER THIS AT PIPELINE START whenever NO merged Claude settings file (project .claude/settings.local.json or .claude/settings.json, or user ~/.claude/settings.json) contains tendril MCP entries \u2014 plugin installs use mcp__plugin_tendril_tendril__*, direct claude-mcp-add installs use mcp__<server>__* \u2014 when this session's tool names differ from the plugin defaults, pass figmaPrefix/tendrilPrefix with the prefixes you actually see, or the written entries never match. A FILE check, never prompt-watching \u2014 agents cannot observe permission prompts. ONE approval here replaces a prompt per pipeline call. Never run it unoffered; the user must reload the session for new settings to apply \u2014 say so.",
         schema: z12.object({
-          write: z12.boolean().optional().describe("true = install into .claude/settings.local.json (the point of this tool); false/absent = just return the entries")
+          write: z12.boolean().optional().describe("true = install into .claude/settings.local.json (the point of this tool); false/absent = just return the entries"),
+          figmaPrefix: z12.string().optional().describe("The Figma server's entry prefix AS THIS SESSION NAMES ITS TOOLS \u2014 the part before __get_metadata (e.g. mcp__figma-remote, mcp__plugin_figma_figma). Pass it whenever the session's Figma tools are not mcp__plugin_figma_figma__* \u2014 entries written under the wrong prefix never match anything (measured: six dead entries in a figma-remote session)."),
+          tendrilPrefix: z12.string().optional().describe("Same for the tendril server when this session's tendril tools are not mcp__plugin_tendril_tendril__* (e.g. mcp__tendril for claude mcp add installs).")
         }),
-        argv: (i) => ["permissions", "--claude", ...i["write"] === true ? ["--write"] : []]
+        argv: (i) => [
+          "permissions",
+          "--claude",
+          ...i["write"] === true ? ["--write"] : [],
+          ...typeof i["figmaPrefix"] === "string" ? ["--figma-prefix", i["figmaPrefix"]] : [],
+          ...typeof i["tendrilPrefix"] === "string" ? ["--tendril-prefix", i["tendrilPrefix"]] : []
+        ]
       },
       {
         name: "tendril_doctor",
@@ -12293,7 +12396,7 @@ var init_server = __esm({
       {
         name: "tendril_record_status",
         annotations: { readOnlyHint: true },
-        description: "Recording-set completeness: per-rep recorded/missing tools.",
+        description: "Recording-set completeness: per-rep recorded/missing tools, files that exist but are unusable (invalid \u2014 re-record those), and whether the set-level token map is recorded. `complete` means USABLE by the next pipeline step, including the set-level get_variable_defs.",
         schema: z12.object({ setDir: str("recording set directory") }),
         argv: (i) => ["record", "status", "--set", i["setDir"]]
       },
@@ -12451,6 +12554,13 @@ function mergeAllowlist(file, entries, denyEntries = []) {
 }
 async function buildPermissions(options) {
   const LEGAL_TOOL_NAME = /^[A-Za-z0-9_-]+$/;
+  for (const [flag, value] of [["--figma-prefix", options.figmaPrefix], ["--tendril-prefix", options.tendrilPrefix]]) {
+    if (value !== void 0 && !LEGAL_MCP_PREFIX.test(value)) {
+      throw new Error(`${flag} must look like mcp__<server-name> (letters, digits, _ and - only) \u2014 got ${JSON.stringify(value)}`);
+    }
+  }
+  const figmaPrefix = options.figmaPrefix ?? FIGMA_PLUGIN_PREFIX;
+  const tendrilPrefix = options.tendrilPrefix ?? TENDRIL_PLUGIN_PREFIX;
   const pipeline = new Set(FIGMA_TOOL_FALLBACK);
   let figmaTools = FIGMA_TOOL_FALLBACK;
   try {
@@ -12462,10 +12572,10 @@ async function buildPermissions(options) {
   }
   return {
     host: "claude",
-    serverEntries: [TENDRIL_PLUGIN_PREFIX, FIGMA_PLUGIN_PREFIX],
+    serverEntries: [tendrilPrefix, figmaPrefix],
     toolEntries: [
-      ...TOOLS.map((t) => t.name).filter((n) => LEGAL_TOOL_NAME.test(n)).map((n) => `${TENDRIL_PLUGIN_PREFIX}__${n}`),
-      ...figmaTools.map((name) => `${FIGMA_PLUGIN_PREFIX}__${name}`)
+      ...TOOLS.map((t) => t.name).filter((n) => LEGAL_TOOL_NAME.test(n)).map((n) => `${tendrilPrefix}__${n}`),
+      ...figmaTools.map((name) => `${figmaPrefix}__${name}`)
     ],
     shellEntries: [...SHELL_READONLY_ENTRIES, ...SHELL_PIPELINE_ENTRIES],
     projectFileEntries: PROJECT_FILE_ENTRIES,
@@ -12473,7 +12583,7 @@ async function buildPermissions(options) {
     manualCautionEntries: MANUAL_CAUTION_ENTRIES,
     shellEntriesNote: "These are CONVENIENCE grants replacing the ~300 prompts a measured run costs \u2014 not a security boundary. What they trade, named: (1) the read verbs (cat/grep/head/\u2026) let the agent read ANY file without a prompt, secrets included \u2014 remove those entries if that is unacceptable; (2) Claude Code Bash patterns are prefix matches and redirection is not a command separator (`cat x > file` rides `Bash(cat:*)`) \u2014 the host's docs call argument patterns best-effort, not an enforcement boundary (pipes and `&&`/`;` chains do decompose, each piece prompting on its own); (3) the per-subcommand CLI grants carry those subcommands' own write surface (recordings, bundles, score history, --out paths) and the npx form trusts future @latest publishes. Never auto-written: a blanket `tendril` grant (an agent could silently widen this very allowlist via `tendril permissions --write`), `find` (arbitrary delete/exec via -delete/-exec), clobber verbs \u2014 those stay a manual, deliberate addition. Write/Edit are project-scoped, written only to the project-local file, with deny entries for ./.claude/** and ./.git/** so the grant can never rewrite this settings file or plant git hooks. Every entry is removable any time.",
     serverEntriesCaution: "The server-wide entries allow EVERY tool those servers serve \u2014 for tendril that includes tendril_generate_curated (spends your OpenRouter budget when configured), and for Figma every tool the desktop server exposes, beyond the read tools this pipeline uses. The per-tool list is the recommended default.",
-    directConfigNote: `Installed via claude mcp add instead of the plugin? Replace the prefixes: ${TENDRIL_PLUGIN_PREFIX}__<tool> becomes mcp__<your-server-name>__<tool> (same for Figma).`
+    directConfigNote: `Prefixes default to the plugin install shape. A different install (claude mcp add, the remote Figma server, \u2026) names its tools mcp__<server-name>__<tool> \u2014 pass the real prefixes with --figma-prefix / --tendril-prefix (MCP: figmaPrefix / tendrilPrefix) so the written entries actually match; run 20 measured six Figma entries that could never fire because the session's server was figma-remote.`
   };
 }
 function writeSelection(result, user) {
@@ -12484,7 +12594,21 @@ async function runPermissions(flags) {
     printDescription(PERMISSIONS_DESCRIPTION);
     return;
   }
-  const result = await buildPermissions({ ...flags.mcpUrl ? { mcpUrl: flags.mcpUrl } : {} });
+  let result;
+  try {
+    result = await buildPermissions({
+      ...flags.mcpUrl ? { mcpUrl: flags.mcpUrl } : {},
+      ...flags.figmaPrefix !== void 0 ? { figmaPrefix: flags.figmaPrefix } : {},
+      ...flags.tendrilPrefix !== void 0 ? { tendrilPrefix: flags.tendrilPrefix } : {}
+    });
+  } catch (err) {
+    fail(flags, ExitCode.InputValidation, {
+      error: err instanceof Error ? err.message : String(err),
+      code: "bad-prefix",
+      remediation: "Pass the prefix exactly as the session names its MCP tools: the part before the final __<tool> (e.g. mcp__figma-remote, mcp__plugin_figma_figma)."
+    });
+    return;
+  }
   if (flags.write) {
     const base = process.env["INIT_CWD"] ?? process.cwd();
     const file = flags.user ? path38.join(os8.homedir(), ".claude", "settings.json") : path38.join(base, ".claude", "settings.local.json");
@@ -12559,7 +12683,7 @@ ${result.directConfigNote}
     );
   });
 }
-var FIGMA_TOOL_FALLBACK, SHELL_READONLY_ENTRIES, SHELL_PIPELINE_ENTRIES, PROJECT_FILE_ENTRIES, PROJECT_DENY_ENTRIES, MANUAL_CAUTION_ENTRIES, PERMISSIONS_DESCRIPTION, TENDRIL_PLUGIN_PREFIX, FIGMA_PLUGIN_PREFIX;
+var FIGMA_TOOL_FALLBACK, SHELL_READONLY_ENTRIES, SHELL_PIPELINE_ENTRIES, PROJECT_FILE_ENTRIES, PROJECT_DENY_ENTRIES, MANUAL_CAUTION_ENTRIES, PERMISSIONS_DESCRIPTION, TENDRIL_PLUGIN_PREFIX, FIGMA_PLUGIN_PREFIX, LEGAL_MCP_PREFIX;
 var init_permissions = __esm({
   "packages/cli/src/commands/permissions.ts"() {
     "use strict";
@@ -12610,6 +12734,8 @@ var init_permissions = __esm({
         { flag: "--write", description: "Merge the pipeline allowlist (MCP tools + shell surface + project Write/Edit, with deny guards for ./.claude and ./.git) into .claude/settings.local.json in the current project (idempotent; creates the file; never touches other keys)" },
         { flag: "--user", description: "With --write: target ~/.claude/settings.json instead \u2014 MCP tool entries ONLY; shell and Write/Edit grants stay project-local, never every-project" },
         { flag: "--mcp-url <url>", description: "Figma MCP endpoint to list live tool names from", default: DEFAULT_MCP_URL },
+        { flag: "--figma-prefix <prefix>", description: "The session's real Figma MCP entry prefix (e.g. mcp__figma-remote) \u2014 the plugin-install default cannot match other install shapes" },
+        { flag: "--tendril-prefix <prefix>", description: "The session's real tendril MCP entry prefix (e.g. mcp__tendril for claude mcp add installs)" },
         { flag: "--json", description: "Machine-readable output" }
       ],
       output: {
@@ -12624,6 +12750,7 @@ var init_permissions = __esm({
     };
     TENDRIL_PLUGIN_PREFIX = "mcp__plugin_tendril_tendril";
     FIGMA_PLUGIN_PREFIX = "mcp__plugin_figma_figma";
+    LEGAL_MCP_PREFIX = /^mcp__[A-Za-z0-9_-]+$/;
   }
 });
 
@@ -14114,7 +14241,7 @@ function buildProgram() {
       ...local["out"] !== void 0 ? { out: local["out"] } : {}
     });
   });
-  program.command("permissions").description("Install (or print) the Claude Code permission allowlist for the Tendril pipeline (tendril + Figma MCP tools) \u2014 no more transcribing tool names from prompts.").option("--claude", "Claude Code settings format (the default and currently only format)").option("--write", "merge the per-tool entries into .claude/settings.local.json in the current project (idempotent; never touches other keys)").option("--user", "with --write: target ~/.claude/settings.json (every project) instead").option("--mcp-url <url>", "Figma MCP endpoint to list live tool names from").action(async (_o, cmd) => {
+  program.command("permissions").description("Install (or print) the Claude Code permission allowlist for the Tendril pipeline (tendril + Figma MCP tools) \u2014 no more transcribing tool names from prompts.").option("--claude", "Claude Code settings format (the default and currently only format)").option("--write", "merge the per-tool entries into .claude/settings.local.json in the current project (idempotent; never touches other keys)").option("--user", "with --write: target ~/.claude/settings.json \u2014 MCP tool entries only; shell and Write/Edit grants stay project-local").option("--mcp-url <url>", "Figma MCP endpoint to list live tool names from").option("--figma-prefix <prefix>", "the session's real Figma MCP entry prefix (e.g. mcp__figma-remote) when it is not the plugin default").option("--tendril-prefix <prefix>", "the session's real tendril MCP entry prefix (e.g. mcp__tendril for claude mcp add installs)").action(async (_o, cmd) => {
     const flags = globalFlags(cmd.parent);
     const local = cmd.opts();
     const { runPermissions: runPermissions2 } = await Promise.resolve().then(() => (init_permissions(), permissions_exports));
@@ -14122,7 +14249,9 @@ function buildProgram() {
       ...flags,
       ...local["write"] !== void 0 ? { write: local["write"] } : {},
       ...local["user"] !== void 0 ? { user: local["user"] } : {},
-      ...local["mcpUrl"] !== void 0 ? { mcpUrl: local["mcpUrl"] } : {}
+      ...local["mcpUrl"] !== void 0 ? { mcpUrl: local["mcpUrl"] } : {},
+      ...local["figmaPrefix"] !== void 0 ? { figmaPrefix: local["figmaPrefix"] } : {},
+      ...local["tendrilPrefix"] !== void 0 ? { tendrilPrefix: local["tendrilPrefix"] } : {}
     });
   });
   program.command("inspect").description("Build an eye-verifiable detail sheet from verify evidence: magnified recorded-vs-rendered crops of every small recorded node (icons, controls, marks) plus full-frame triples, in one static HTML page.").argument("<bundleDir>", "bundle directory with component.json and verify-evidence").option("--set <dir>", "recording set override (default: the bundle's provenance path)").option("--max-area <px2>", "node area ceiling for the detail sweep", "1024").action(async (bundleDir, _o, cmd) => {

package/package.json

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