@bridge-ds/mcp 0.4.1 → 0.5.0

package/dist/{chunk-MXMMPO7F.js → chunk-MHCXMHCL.js}

@@ -1921,6 +1921,17 @@ var GitHubClient = class _GitHubClient {
     this.assertToken("Updating a branch from main");
     await this.request("PUT", `${this.repoPath}/pulls/${n}/update-branch`, { expected_head_sha: expectedHeadSha });
   }
+  /**
+   * Merges the branch `head` into the branch `base` (GitHub's merges API): a merge commit on `base`, or nothing when
+   * `base` already has every commit of `head`. A conflict throws a GitHubError with status 409. Refuses protected
+   * branches and, with a branch prefix, a `base` without it.
+   */
+  async mergeIntoBranch(base, head, message) {
+    this.assertToken("Merging a branch into another");
+    this.assertWritableBranch(base);
+    const r = await this.request("POST", `${this.repoPath}/merges`, { base, head, commit_message: message });
+    return r?.sha ? { status: "merged", sha: r.sha } : { status: "up-to-date", sha: null };
+  }
   /** Posts a comment on an issue or pull request and returns its id and link. */
   async createIssueComment(n, body) {
     this.assertToken("Commenting");
@@ -2084,8 +2095,8 @@ function firstParagraph(text) {
   if (!text) return "";
   const cleaned = text.replace(/<!--[\s\S]*?-->/g, "");
   for (const para of cleaned.split(/\r?\n\s*\r?\n/)) {
-    const lines = para.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#{1,6}\s/.test(l) && !/^\s*[-*]\s*\[[ xX]\]/.test(l) && !/^\s*(Co-Authored-By|Claude-Session|Signed-off-by):/i.test(l));
-    const s = lines.join(" ").replace(/\s+/g, " ").trim();
+    const lines2 = para.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#{1,6}\s/.test(l) && !/^\s*[-*]\s*\[[ xX]\]/.test(l) && !/^\s*(Co-Authored-By|Claude-Session|Signed-off-by):/i.test(l));
+    const s = lines2.join(" ").replace(/\s+/g, " ").trim();
     if (s && !/^\|/.test(s)) return s.length > 400 ? `${s.slice(0, 397)}...` : s;
   }
   return "";
@@ -2251,11 +2262,11 @@ function modeLabel(modes) {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
 function tokenHistory(entries, path, config) {
-  const names2 = /* @__PURE__ */ new Set([path]);
+  const names3 = /* @__PURE__ */ new Set([path]);
   const out = [];
   const sorted = [...entries].sort((a, b) => Date.parse(b.date) - Date.parse(a.date));
   for (const e of sorted) {
-    const hits = e.changes.filter((c) => names2.has(c.path));
+    const hits = e.changes.filter((c) => names3.has(c.path));
     for (const c of hits) {
       const modes = config ? fileModes(config, c.file) : {};
       out.push({
@@ -2283,7 +2294,7 @@ function tokenHistory(entries, path, config) {
         ...c.descriptionAfter !== void 0 ? { descriptionAfter: c.descriptionAfter } : {}
       });
     }
-    for (const c of hits) if (c.kind === "renamed" && c.from) names2.add(c.from);
+    for (const c of hits) if (c.kind === "renamed" && c.from) names3.add(c.from);
   }
   return out;
 }
@@ -2413,7 +2424,7 @@ function planRevert(input) {
   }
   const prLink = entry.pr ? entry.pr.url ? `[#${entry.pr.number}](${entry.pr.url})` : `#${entry.pr.number}` : `commit ${entry.sha.slice(0, 7)}`;
   const title = `Revert: ${entry.title}`;
-  const lines = [
+  const lines2 = [
     `Reverts ${prLink} ("${entry.title}"), merged ${entry.date.slice(0, 10)} by ${entry.author}.`,
     "",
     `Original reason: ${entry.why}`,
@@ -2421,11 +2432,11 @@ function planRevert(input) {
     "Bridge computed the inverse token edits against the current base branch, not a blind git revert: tokens that changed again since are listed as conflicts and kept unless a reviewer chose to restore them."
   ];
   if (conflicts.length) {
-    lines.push("", "### Conflicts", "", "| Token | File | Why | Decision |", "| --- | --- | --- | --- |");
-    for (const k of conflicts) lines.push(`| \`${k.path}\` | ${k.file} | ${k.message.replace(/\|/g, "\\|")}${k.later.length ? ` Later: ${k.later.map((l) => l.pr ? `#${l.pr}` : l.id).join(", ")}.` : ""} | ${k.resolution === "use-before" ? "restore the old value" : "keep current"} |`);
+    lines2.push("", "### Conflicts", "", "| Token | File | Why | Decision |", "| --- | --- | --- | --- |");
+    for (const k of conflicts) lines2.push(`| \`${k.path}\` | ${k.file} | ${k.message.replace(/\|/g, "\\|")}${k.later.length ? ` Later: ${k.later.map((l) => l.pr ? `#${l.pr}` : l.id).join(", ")}.` : ""} | ${k.resolution === "use-before" ? "restore the old value" : "keep current"} |`);
   }
-  if (skipped.length) lines.push("", `${skipped.length} change(s) were already undone on the base branch and are left alone.`);
-  return finishPlan({ ...input, kind: "revert", title, prTitle: title, summary: lines.join("\n"), planned, conflicts, skipped, source: entry });
+  if (skipped.length) lines2.push("", `${skipped.length} change(s) were already undone on the base branch and are left alone.`);
+  return finishPlan({ ...input, kind: "revert", title, prTitle: title, summary: lines2.join("\n"), planned, conflicts, skipped, source: entry });
 }
 function planRestore(input) {
   const { current, path } = input;
@@ -3598,7 +3609,7 @@ function explorationPrBody(e, ctx) {
   const branch = `${EXPLORATION_PREFIX}${slug2}`;
   const uc = useCaseLabel(e.useCase);
   const experimental = (e.experimental ?? []).map((x) => x.trim()).filter(Boolean);
-  const lines = [
+  const lines2 = [
     `## Exploration: ${e.name.trim()}`,
     "",
     `> Not mergeable as is. This draft pull request is a sandbox on \`${branch}\`: promote it to a normal review when the idea is validated, or close it.`,
@@ -3614,14 +3625,14 @@ function explorationPrBody(e, ctx) {
     "### Try it in a product staging branch",
     ""
   ];
-  lines.push(
+  lines2.push(
     'In the product repo, on a branch that deploys to staging (production keeps the released version), install the snapshot with the command in the "Try this exploration in your product" comment below. It appears a few minutes after each push and always matches the latest commit.'
   );
-  lines.push("", "### Previews", "");
+  lines2.push("", "### Previews", "");
   const links = previewLinks(ctx.apps, { branch, ...ctx.pr ? { pr: ctx.pr } : {} });
-  if (links.length) lines.push("| App | Preview |", "| --- | --- |", ...links.map((l) => `| ${l.label} | ${l.url} |`));
-  else lines.push("Preview deploys are not set up: add `previews.apps` to `bridge.config.json` (docs/PREVIEWS.md).");
-  lines.push(
+  if (links.length) lines2.push("| App | Preview |", "| --- | --- |", ...links.map((l) => `| ${l.label} | ${l.url} |`));
+  else lines2.push("Preview deploys are not set up: add `previews.apps` to `bridge.config.json` (docs/PREVIEWS.md).");
+  lines2.push(
     "",
     "### When it is done",
     "",
@@ -3630,7 +3641,7 @@ function explorationPrBody(e, ctx) {
     "",
     `<!-- ${MARK} ${JSON.stringify({ name: e.name.trim(), purpose: e.purpose.trim(), slug: slug2, ...e.useCase ? { useCase: e.useCase } : {}, ...experimental.length ? { experimental } : {}, ...e.author ? { author: e.author } : {}, ...e.startedAt ? { startedAt: e.startedAt } : {}, ...e.source ? { source: e.source } : {}, ...e.agent ? { agent: e.agent } : {} }).replace(/-->/g, "--\\u003e")} -->`
   );
-  return lines.join("\n");
+  return lines2.join("\n");
 }
 function parseExplorationBody(body) {
   if (!body) return void 0;
@@ -3955,9 +3966,9 @@ function mergeDraftResults(p, results, at = /* @__PURE__ */ new Date()) {
       continue;
     }
     const clean = sanitizeDraftText(r);
-    const lines = sanitizeResultLines(item2, r.lines);
-    if (!clean.title && !clean.summary && !lines.length) throw new Error(`The result for "${r.id}" has no title and no summary, and no line.`);
-    next.set(r.id, { id: r.id, title: clean.title, summary: clean.summary, ...lines.length ? { lines } : {}, by: "claude", at: at.toISOString() });
+    const lines2 = sanitizeResultLines(item2, r.lines);
+    if (!clean.title && !clean.summary && !lines2.length) throw new Error(`The result for "${r.id}" has no title and no summary, and no line.`);
+    next.set(r.id, { id: r.id, title: clean.title, summary: clean.summary, ...lines2.length ? { lines: lines2 } : {}, by: "claude", at: at.toISOString() });
   }
   const merged = p.items.map((i) => next.get(i.id)).filter((r) => !!r);
   return { ...p, results: merged, status: merged.length === p.items.length ? "drafted" : "pending" };
@@ -3975,24 +3986,24 @@ function draftItemBrief(i) {
   }
   const kind = i.kind ? REQUEST_KINDS.find((k) => k.value === i.kind)?.label : void 0;
   const cell3 = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
-  const lines = [`Item ${i.id}: ${i.scope === "request" ? "a component change request (a GitHub issue developers implement)" : "the description of a pull request with design token (variable) edits from Figma"}.`];
-  if (i.component) lines.push(`Component: ${i.component}`);
-  if (kind) lines.push(`Kind: ${kind}`);
-  if (i.components?.length) lines.push(`Components with a change request: ${i.components.join(", ")}`);
-  if (i.changes.length) lines.push("", "| What | Now | In Figma |", "| --- | --- | --- |", ...i.changes.map((c) => `| ${cell3(c.field)} | ${cell3(c.before) || "none"} | ${cell3(c.after) || "removed"} |`));
-  if (i.variables?.length) lines.push("", "| Token | Now | In Figma |", "| --- | --- | --- |", ...i.variables.map((v) => `| ${cell3(v.path)} | ${cell3(v.before) || "none"} | ${cell3(v.after) || "removed"} |`));
-  if (!i.changes.length && !i.variables?.length && !i.lines?.length) lines.push("", "No change detected: rely on the notes and the images.");
-  if (i.draft.title || i.draft.summary) lines.push("", "Starting draft, written from the changes only:", `Title: ${i.draft.title}`, `Summary: ${i.draft.summary}`);
-  if (i.notes?.trim()) lines.push("", "The designer's notes (keep their intent):", i.notes.trim());
+  const lines2 = [`Item ${i.id}: ${i.scope === "request" ? "a component change request (a GitHub issue developers implement)" : "the description of a pull request with design token (variable) edits from Figma"}.`];
+  if (i.component) lines2.push(`Component: ${i.component}`);
+  if (kind) lines2.push(`Kind: ${kind}`);
+  if (i.components?.length) lines2.push(`Components with a change request: ${i.components.join(", ")}`);
+  if (i.changes.length) lines2.push("", "| What | Now | In Figma |", "| --- | --- | --- |", ...i.changes.map((c) => `| ${cell3(c.field)} | ${cell3(c.before) || "none"} | ${cell3(c.after) || "removed"} |`));
+  if (i.variables?.length) lines2.push("", "| Token | Now | In Figma |", "| --- | --- | --- |", ...i.variables.map((v) => `| ${cell3(v.path)} | ${cell3(v.before) || "none"} | ${cell3(v.after) || "removed"} |`));
+  if (!i.changes.length && !i.variables?.length && !i.lines?.length) lines2.push("", "No change detected: rely on the notes and the images.");
+  if (i.draft.title || i.draft.summary) lines2.push("", "Starting draft, written from the changes only:", `Title: ${i.draft.title}`, `Summary: ${i.draft.summary}`);
+  if (i.notes?.trim()) lines2.push("", "The designer's notes (keep their intent):", i.notes.trim());
   if (i.lines?.length) {
-    lines.push("", `Change lines to write (one sentence each, at most ${DRAFT_LINE_MAX} characters, from the before and after images), each with the title of its request (at most ${DRAFT_TITLE_MAX} characters):`);
+    lines2.push("", `Change lines to write (one sentence each, at most ${DRAFT_LINE_MAX} characters, from the before and after images), each with the title of its request (at most ${DRAFT_TITLE_MAX} characters):`);
     for (const l of i.lines) {
-      lines.push(`- Line ${l.id}${l.component ? `, ${l.component}` : ""}${l.kind ? ` (${REQUEST_KINDS.find((k) => k.value === l.kind)?.label ?? l.kind})` : ""}. Starting line: ${l.line || "(none)"}${l.title ? `. Starting title: ${l.title}` : ""}`);
-      for (const c of l.changes) lines.push(`  - ${c.field}: ${c.before || "none"} -> ${c.after || "removed"}`);
+      lines2.push(`- Line ${l.id}${l.component ? `, ${l.component}` : ""}${l.kind ? ` (${REQUEST_KINDS.find((k) => k.value === l.kind)?.label ?? l.kind})` : ""}. Starting line: ${l.line || "(none)"}${l.title ? `. Starting title: ${l.title}` : ""}`);
+      for (const c of l.changes) lines2.push(`  - ${c.field}: ${c.before || "none"} -> ${c.after || "removed"}`);
     }
   }
-  if (i.images?.length) lines.push("", `Images: ${i.images.map((m) => `${m.label}${m.line ? ` (line ${m.line})` : ""} ${m.url}`).join(", ")}`);
-  return lines.join("\n");
+  if (i.images?.length) lines2.push("", `Images: ${i.images.map((m) => `${m.label}${m.line ? ` (line ${m.line})` : ""} ${m.url}`).join(", ")}`);
+  return lines2.join("\n");
 }
 var isConflict = (err) => err instanceof GitHubError ? err.status === 409 || err.status === 422 && /sha/i.test(`${err.detail ?? ""} ${err.message}`) : err?.status === 409;
 async function readPendingDrafts(client2, sessionId, branch = REQUESTS_BRANCH) {
@@ -4380,14 +4391,14 @@ function conflictRoute(o, opts = {}) {
   return { kind: "tokens", files: o.tokenFiles };
 }
 function resolutionMessage(input) {
-  const lines = input.conflicts.map((c) => `- ${c.path} (${c.file}): ${choiceFor(c, input.choices) === "theirs" ? `used the ${input.library} value` : "kept this change"}`);
+  const lines2 = input.conflicts.map((c) => `- ${c.path} (${c.file}): ${choiceFor(c, input.choices) === "theirs" ? `used the ${input.library} value` : "kept this change"}`);
   const title = input.conflicts.length ? `Bring in the latest ${input.library} and resolve ${plural(input.conflicts.length, "token conflict")}` : `Bring in the latest ${input.library}`;
   const by = input.who ? `
 
 Resolved in Bridge by @${input.who.replace(/^@/, "")}.` : "\n\nResolved in Bridge.";
-  return `${title}${lines.length ? `
+  return `${title}${lines2.length ? `
 
-${lines.join("\n")}` : ""}${by}`;
+${lines2.join("\n")}` : ""}${by}`;
 }
 function freshness(input) {
   const behindBy = typeof input.compare?.behind_by === "number" ? input.compare.behind_by : null;
@@ -4576,11 +4587,11 @@ function canAddTo(p, viewer, write) {
   return write || sameLogin(p.user?.login, viewer);
 }
 function addedComment(paths, viewer, from = "the Bridge token editor") {
-  const lines = paths.slice(0, 20).map((p) => `- \`${p}\``);
-  if (paths.length > 20) lines.push(`- and ${paths.length - 20} more`);
+  const lines2 = paths.slice(0, 20).map((p) => `- \`${p}\``);
+  if (paths.length > 20) lines2.push(`- and ${paths.length - 20} more`);
   return `${viewer ? `@${viewer} added` : "Added"} token edits from ${from}:
 
-${lines.join("\n")}`;
+${lines2.join("\n")}`;
 }
 
 // ../core/src/jira.ts
@@ -4687,10 +4698,10 @@ async function continueDocsProposalOnGitHub(gh, open, edit, opts = {}) {
 function docsProposal(edits, opts) {
   const origin = opts.origin ?? DOCS_EDITOR_ORIGIN;
   if (!edits.length) throw new Error("No docs edits in the draft.");
-  const names2 = edits.map((e) => e.component);
-  const list = names2.length === 1 ? names2[0] : `${names2.slice(0, -1).join(", ")} and ${names2[names2.length - 1]}`;
-  const title = opts.title?.trim() || `docs(${names2.length === 1 ? edits[0].slug : "components"}): usage guidance for ${list}`;
-  const slug2 = docsSlug(names2.length === 1 ? edits[0].slug : `${edits[0].slug}-and-${names2.length - 1}-more`);
+  const names3 = edits.map((e) => e.component);
+  const list = names3.length === 1 ? names3[0] : `${names3.slice(0, -1).join(", ")} and ${names3[names3.length - 1]}`;
+  const title = opts.title?.trim() || `docs(${names3.length === 1 ? edits[0].slug : "components"}): usage guidance for ${list}`;
+  const slug2 = docsSlug(names3.length === 1 ? edits[0].slug : `${edits[0].slug}-and-${names3.length - 1}-more`);
   const branch = `docs/${slug2}-${slugDate(opts.date)}-${opts.date.getTime().toString(36).slice(-4)}`;
   const csPath = `${opts.changesetDir ?? ".changeset"}/docs-${slug2}-${opts.date.getTime().toString(36)}.md`;
   const pkg = opts.packageName ?? "@bridge-ds/react";
@@ -4873,9 +4884,9 @@ var COMBINE_COMPARE_LIMIT = 300;
 async function readCombineBranch(gh, pull, opts) {
   const compare = await gh.compareDetailed(opts.base, pull.headSha);
   const files = compare.files;
-  const names2 = files.flatMap((f) => f.previous_filename ? [f.filename, f.previous_filename] : [f.filename]);
+  const names3 = files.flatMap((f) => f.previous_filename ? [f.filename, f.previous_filename] : [f.filename]);
   const start = compare.mergeBase;
-  if (!start || files.length >= COMBINE_COMPARE_LIMIT || !onlyTokens(names2, opts.tokensRoot)) return { number: pull.number, title: pull.title, tokens: false, edits: null };
+  if (!start || files.length >= COMBINE_COMPARE_LIMIT || !onlyTokens(names3, opts.tokensRoot)) return { number: pull.number, title: pull.title, tokens: false, edits: null };
   const root = opts.tokensRoot.replace(/^\/+|\/+$/g, "");
   const tokenFiles = files.filter((f) => tokenFilesOf([f.filename], root).length);
   const source = { number: pull.number, base: {}, head: {}, files: tokenFiles.map((f) => tokenFilesOf([f.filename], root)[0]) };
@@ -4889,6 +4900,433 @@ async function readCombineBranch(gh, pull, opts) {
   return { number: pull.number, title: pull.title, tokens: true, edits: changeEdits(source) };
 }
 
+// ../core/src/prod-branch.ts
+var PIECES_MARK = "bridge-pieces";
+var NEEDED_MARK = "bridge-needed-by";
+var SECTION = "### Missing from the library";
+var NEEDED_BY_LABEL = "needed-by-product";
+var hiddenJson = (mark, data) => `<!-- ${mark} ${JSON.stringify(data).replace(/-->/g, "--\\u003e")} -->`;
+var readHidden = (mark, body) => {
+  if (!body) return void 0;
+  const m = new RegExp(`<!-- ${mark} (\\{[\\s\\S]*?\\}) -->`).exec(body);
+  if (!m) return void 0;
+  try {
+    return JSON.parse(m[1]);
+  } catch {
+    return void 0;
+  }
+};
+var KIND_WORD = { "token-change": "token change", exploration: "library exploration", request: "component request" };
+function parsePiecesRecord(body) {
+  const r = readHidden(PIECES_MARK, body);
+  if (!r || !Array.isArray(r.pieces) || !Array.isArray(r.links) || typeof r.checkedAt !== "string") return void 0;
+  return r;
+}
+function piecesSection(r) {
+  const link = (p) => r.links.find((l) => l.piece === p.id);
+  const lines2 = r.pieces.length ? r.pieces.map((p) => {
+    const l = link(p);
+    return `- **${p.title}**: ${p.summary}${l ? ` ${cap(KIND_WORD[l.kind])}: #${l.number}.` : " No library branch yet."}`;
+  }) : ["- Nothing: every value and component comes from the library."];
+  return [SECTION, "", `Checked ${r.checkedAt.slice(0, 10)}${r.headSha ? ` on ${r.headSha.slice(0, 7)}` : ""} by Bridge.`, "", ...lines2, "", hiddenJson(PIECES_MARK, r)].join("\n");
+}
+function withPiecesRecord(body, r) {
+  const b = (body ?? "").trimEnd();
+  const start = b.indexOf(SECTION);
+  const markAt = b.indexOf(`<!-- ${PIECES_MARK} `);
+  if (start >= 0 && markAt > start) {
+    const end = b.indexOf("-->", markAt);
+    return `${b.slice(0, start)}${piecesSection(r)}${end >= 0 ? b.slice(end + 3) : ""}`.trimEnd();
+  }
+  return `${b}${b ? "\n\n" : ""}${piecesSection(r)}`;
+}
+function mergePiecesRecord(prev, next) {
+  const links = [...prev?.links ?? []];
+  for (const l of next.links ?? []) {
+    const at = links.findIndex((x) => x.piece === l.piece);
+    if (at >= 0) links[at] = l;
+    else links.push(l);
+  }
+  return { ...next, links };
+}
+function withLink(r, l) {
+  return { ...r, links: [...r.links.filter((x) => x.piece !== l.piece), l] };
+}
+function neededBySection(n) {
+  const who = n.author ? ` for @${n.author}` : "";
+  const near = n.nearest ? ` The closest the library has today is ${n.nearest}${n.nearestToken ? ` (\`${n.nearestToken}\`)` : ""}.` : "";
+  return [`**Needed by:** [${n.title}](${n.url}) (#${n.pr}) in ${n.productName}${who}.${near}`, "", hiddenJson(NEEDED_MARK, n)].join("\n");
+}
+function withNeededBy(body, n) {
+  let b = (body ?? "").trim();
+  const at = b.indexOf("**Needed by:**");
+  const mark = b.indexOf(`<!-- ${NEEDED_MARK} `);
+  if (at >= 0 && mark > at) {
+    const end = b.indexOf("-->", mark);
+    b = `${b.slice(0, at)}${b.slice(end + 3)}`.trim();
+  }
+  return `${neededBySection(n)}${b ? `
+
+${b}` : ""}`;
+}
+var cap = (s) => s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+var forLine = (b) => `${b.productName} needs it for "${b.title.replace(/"/g, "'")}" (#${b.pr})`;
+function libraryBranchPlan(piece, branch, opts = {}) {
+  const neededBy = {
+    pr: branch.pr,
+    title: branch.title,
+    branch: branch.branch,
+    url: branch.url,
+    product: branch.productKey,
+    productName: branch.productName,
+    ...branch.author ? { author: branch.author } : {},
+    piece: piece.id,
+    pieceTitle: piece.title,
+    ...piece.nearest ? { nearest: piece.nearest.label, nearestToken: piece.nearest.token } : {}
+  };
+  const near = piece.nearest ? ` The closest the library has today is ${piece.nearest.label} (${piece.nearest.token}, ${piece.nearest.value}).` : "";
+  if (piece.kind === "token" && piece.token) {
+    const t = piece.token;
+    const files = t.files.length ? t.files : [void 0];
+    const edits = files.map((file) => ({
+      op: "add",
+      path: t.path,
+      type: t.type,
+      value: t.value,
+      description: `${cap(piece.name)}: ${forLine(branch)}.${files.length > 1 ? " Same value in every theme: review it in each." : ""}`,
+      ...file ? { file } : {}
+    }));
+    return { kind: "token-change", title: `Add ${t.path}`, summary: `${forLine(branch)}: ${piece.summary}${near}`, edits, neededBy };
+  }
+  if (piece.kind === "variant" && piece.component) {
+    const values = piece.values.map((v) => `${v.property ?? v.category} ${v.value}`).join(", ");
+    const exploration = {
+      name: piece.title,
+      purpose: `${forLine(branch)}: ${/^[aeiou]/i.test(piece.name) ? "an" : "a"} ${piece.name} ${piece.aspect ?? "style"} on ${piece.component} (${values}).${near}`,
+      useCase: "terminal",
+      experimental: [piece.title],
+      source: opts.source === "figma" ? "figma" : opts.source ?? "mcp"
+    };
+    const brief = [
+      `Add the ${piece.name} ${piece.aspect ?? "style"} to ${piece.component} in the library, on this exploration branch.`,
+      `The product branch writes it by hand: ${values}. Express it with tokens (a component or semantic token per value), add it to the component's props, docs and examples, and keep every existing ${piece.component} unchanged.`,
+      piece.nearest ? `Say in the pull request why ${piece.nearest.label} is not enough, or recommend it instead.` : ""
+    ].filter(Boolean).join(" ");
+    return { kind: "exploration", title: piece.title, exploration, neededBy, brief };
+  }
+  const name = piece.component ?? cap(piece.name);
+  const request = {
+    component: name,
+    kind: "new-component",
+    title: `Add ${name}`,
+    summary: `${forLine(branch)}: ${piece.summary}${near}`,
+    changes: piece.values.slice(0, 6).map((v) => ({ field: v.property ?? v.category, after: v.value })),
+    source: opts.source ?? "mcp",
+    ...opts.requestedBy ? { requestedBy: opts.requestedBy } : {}
+  };
+  return { kind: "request", title: `New component: ${name}`, request, neededBy };
+}
+var STATUS_LABEL = {
+  draft: "Draft",
+  "in-review": "In review",
+  changes: "Changes requested",
+  approved: "Approved",
+  shipped: "Shipped",
+  closed: "Closed",
+  exploring: "Being built",
+  requested: "Requested",
+  "in-progress": "In progress",
+  done: "Done",
+  declined: "Declined"
+};
+var names2 = (people2) => people2.length <= 2 ? people2.map((p) => `@${p}`).join(" and ") : `@${people2[0]} and ${people2.length - 1} more`;
+function linkStatus(x) {
+  const make = (key, people2 = [], verb = "reviews") => {
+    const label = STATUS_LABEL[key];
+    const tail = people2.length ? ` \xB7 ${names2(people2)} ${people2.length === 1 ? verb : verb.replace(/s$/, "")}` : "";
+    return { key, label, people: people2, line: `${label}${tail}` };
+  };
+  if (x.kind === "request") {
+    if (x.state === "closed") return make(x.stateReason === "not_planned" ? "declined" : "done");
+    return x.implemented ? make("in-progress", [...x.assignees ?? []], "builds") : make("requested", [...x.assignees ?? []], "builds");
+  }
+  if (x.state === "merged") return make("shipped");
+  if (x.state !== "open") return make("closed");
+  if ((x.labels ?? []).includes("exploration")) return make("exploring");
+  if (x.draft) return make("draft");
+  const latest = /* @__PURE__ */ new Map();
+  for (const r of x.reviews ?? []) if (r.user && r.state !== "COMMENTED") latest.set(r.user, r.state);
+  const states = [...latest.values()];
+  if (states.includes("CHANGES_REQUESTED")) return make("changes", [...latest].filter(([, s]) => s === "CHANGES_REQUESTED").map(([u]) => u), "asks");
+  const waiting = [...x.requestedReviewers ?? []];
+  if (states.includes("APPROVED") && !waiting.length) return make("approved");
+  return make("in-review", waiting);
+}
+function libraryPreviewState(x) {
+  if (x.kind === "request") {
+    if (x.lifecycle === "closed") return { key: "declined", sentence: `The library declined this request.${x.nearest ? ` Ask Claude to use ${x.nearest} instead.` : ""}`, action: null };
+    if (x.lifecycle === "merged") return x.behindMain === 0 ? { key: "switched", sentence: "Your branch uses the published version.", action: null } : { key: "published", sentence: "The library built it. Switch your branch to the published version, then ask Claude to use it.", action: { kind: "switch", label: "Switch to the published version" } };
+    return { key: "nothing-yet", sentence: "Nothing to preview yet: the library builds it first. Your branch keeps its own version until then.", action: null };
+  }
+  if (x.lifecycle === "merged") {
+    if (x.behindMain === 0) return { key: "switched", sentence: "Your branch uses the published version.", action: null };
+    return { key: "published", sentence: "The library published it. Switch your branch to the published version.", action: { kind: "switch", label: "Switch to the published version" } };
+  }
+  if (x.lifecycle === "closed") return { key: "declined", sentence: `The library closed it without shipping.${x.nearest ? ` Ask Claude to use ${x.nearest} instead.` : ""}`, action: null };
+  if (!x.hasChanges) return { key: "nothing-yet", sentence: "The library branch has no change yet. Claude adds it there, then your branch can use its preview.", action: null };
+  if (x.missing === 0) return { key: "preview", sentence: "Your branch uses a preview of the library branch. When the library publishes it, switch to the real version here in one click.", action: null };
+  if (x.missing !== null && x.total !== null && x.missing < x.total) return { key: "outdated", sentence: "The library branch changed since your branch took its preview.", action: { kind: "refresh-preview", label: "Get the latest preview" } };
+  return { key: "not-used", sentence: "Your branch does not use the library branch yet.", action: { kind: "use-preview", label: "Use its preview in my branch" } };
+}
+var nPieces = (n) => `${n} ${n === 1 ? "piece" : "pieces"}`;
+function productBranchSentence(r, opts = {}) {
+  if (!r) return { lead: "Not checked against the library yet.", strong: "", rest: " Ask Claude what is missing from the library." };
+  const n = r.pieces.length;
+  if (!n) return { lead: "Built with the library.", strong: " Nothing is missing", rest: ": every value and component comes from it." };
+  const linked = r.pieces.filter((p) => r.links.some((l) => l.piece === p.id));
+  const openers = [...new Set(linked.map((p) => r.links.find((l) => l.piece === p.id)).map((l) => l.agent ? opts.agentName ?? "Claude AI" : l.openedBy && l.openedBy === opts.viewer ? "you" : l.openedBy ? `@${l.openedBy}` : "someone"))];
+  const by = openers.length === 1 ? openers[0] : "your team";
+  const was = n === 1 ? "was" : "were";
+  if (linked.length === n) {
+    const what = n === 1 ? "a library branch for it" : "library branches for them";
+    return { lead: "Built with the library. ", strong: `${nPieces(n)} ${was} missing`, rest: `, and ${by} opened ${what}.` };
+  }
+  if (!linked.length) return { lead: "Built with the library. ", strong: `${nPieces(n)} ${n === 1 ? "is" : "are"} missing`, rest: n === 1 ? ": open a library branch for it." : ": open a library branch for each." };
+  return { lead: "Built with the library. ", strong: `${nPieces(n)} ${was} missing`, rest: `: ${linked.length} ${linked.length === 1 ? "has" : "have"} a library branch, ${n - linked.length} still ${n - linked.length === 1 ? "needs" : "need"} one.` };
+}
+function pieceId(parts) {
+  return slugify(parts.filter(Boolean).join(" "), 48);
+}
+var TONE_WORDS = ["neutral", "success", "warning", "danger", "info", "error", "critical", "accent", "brand", "primary", "secondary"];
+function tokenLabel(path) {
+  const parts = path.split(".");
+  const tone = parts.find((p) => TONE_WORDS.includes(p));
+  if (tone) return tone;
+  const meaningful = parts.filter((p) => !/^(color|bg|fg|text|border|default|base|value|\d+)$/.test(p));
+  return meaningful[meaningful.length - 1] ?? parts[parts.length - 1] ?? path;
+}
+function proposedTokenPath(nearest, name, category) {
+  const slug2 = slugify(name, 32);
+  if (!nearest) return `${category === "color" ? "color" : category}.${slug2}`;
+  const parts = nearest.split(".");
+  const toneAt = parts.findIndex((p) => TONE_WORDS.includes(p));
+  if (toneAt > 0) return [...parts.slice(0, toneAt), slug2, ...parts.slice(toneAt + 1)].join(".");
+  return [...parts.slice(0, -1), slug2].join(".");
+}
+
+// ../core/src/prod-branch-github.ts
+var PRODUCT_FILE = /\.(css|scss|sass|less|tsx|jsx|ts|js|mjs|cjs|mts|cts|astro|vue|svelte)$/;
+var SKIP_FILE = /\.d\.[cm]?ts$|\.(test|spec|stories|story)\.[cm]?[jt]sx?$|\.min\.(css|js)$/;
+var PIECES_FILE_LIMIT = 40;
+var cleanPath = (p) => p.trim().replace(/^\.?\/+|\/+$/g, "");
+function productOf(products, pull, files) {
+  const product = productOfBranch(products, { labels: pull.labels, files });
+  if (product.key === defaultProduct(products).key) throw new GitHubError(422, `This branch is a library branch (${product.name}), not a product branch: missing pieces are checked on a branch started for a product.`);
+  return product;
+}
+async function readProductBranchOnGitHub(gh, pr, opts) {
+  const pull = await gh.getPullRequest(pr);
+  const cmp = await gh.compareDetailed(pull.baseRef, pull.headSha);
+  const product = productOf(opts.products, pull, cmp.files.map((f) => f.filename));
+  const dir = product.path ? `${cleanPath(product.path)}/` : "";
+  const changed = cmp.files.filter((f) => f.status !== "removed" && (!dir || f.filename.startsWith(dir)) && PRODUCT_FILE.test(f.filename) && !SKIP_FILE.test(f.filename) && !f.filename.split("/").includes("node_modules"));
+  const read = changed.slice(0, PIECES_FILE_LIMIT);
+  const start = cmp.mergeBase ?? pull.baseRef;
+  const files = await Promise.all(
+    read.map(async (f) => {
+      const [before, after] = await Promise.all([f.status === "added" ? Promise.resolve(void 0) : gh.getFileText(f.previous_filename ?? f.filename, start), gh.getFileText(f.filename, pull.headSha)]);
+      return { path: f.filename, before: before ?? null, after: after ?? null };
+    })
+  );
+  return { pull, product, files, skipped: changed.length - read.length, record: parsePiecesRecord(pull.body) };
+}
+async function recordPiecesOnGitHub(gh, pr, check) {
+  const pull = await gh.getPullRequest(pr);
+  const record = mergePiecesRecord(parsePiecesRecord(pull.body), { checkedAt: check.checkedAt ?? (/* @__PURE__ */ new Date()).toISOString(), headSha: check.headSha ?? pull.headSha, pieces: check.pieces, fixes: check.fixes });
+  await gh.updatePullRequest(pr, { body: withPiecesRecord(pull.body, record) });
+  return record;
+}
+var productWriter = (gh, branch) => isExplorationBranch(branch) ? gh.withBranchPrefix(EXPLORATION_PREFIX) : gh;
+async function useLibraryPreviewOnGitHub(gh, input) {
+  const message = `chore(bridge): use the preview of ${input.libraryBranch} (#${input.libraryNumber})
+
+The product branch takes the library branch before it ships. Switch to the published version once it does.`;
+  try {
+    const r = await productWriter(gh, input.productBranch).mergeIntoBranch(input.productBranch, input.libraryBranch, message);
+    return { ...r, said: r.status === "merged" ? "Your branch now uses the preview of the library branch." : "Your branch already has the latest preview." };
+  } catch (err) {
+    if (err instanceof GitHubError && err.status === 409) return { status: "conflict", sha: null, said: `Your branch and the library branch change the same lines. A developer merges ${input.libraryBranch} into ${input.productBranch} by hand.` };
+    throw err;
+  }
+}
+function productBranchRef(pull, product) {
+  const name = /<!-- bridge-exploration (\{[\s\S]*?\}) -->/.exec(pull.body ?? "");
+  let title = pull.title.replace(/^[A-Z][A-Z0-9_]*-\d+\s+/, "").replace(/^Exploration:\s*/i, "");
+  let author = pull.author;
+  if (name) {
+    try {
+      const e = JSON.parse(name[1]);
+      if (e.name) title = e.name;
+      if (e.author) author = e.author;
+    } catch {
+    }
+  }
+  return { pr: pull.number, title: title.charAt(0).toUpperCase() + title.slice(1), branch: pull.headRef, url: pull.url, productKey: product.key, productName: product.name, ...author ? { author } : {} };
+}
+async function openLibraryBranchOnGitHub(gh, input) {
+  const pull = await gh.getPullRequest(input.pr);
+  const record = parsePiecesRecord(pull.body);
+  const piece = record?.pieces.find((p) => p.id === input.piece);
+  if (!record || !piece) throw new GitHubError(404, record ? `No piece "${input.piece}" on #${input.pr}. Pieces: ${record.pieces.map((p) => p.id).join(", ") || "none"}.` : `#${input.pr} was not checked yet: find its missing pieces first (bridge_missing_pieces with record, or \`bridge pieces ${input.pr} --record\`).`);
+  const product = productOf(input.products, pull, await gh.listPullRequestFiles(input.pr).then((f) => f.map((x) => x.filename), () => []));
+  const plan = libraryBranchPlan(piece, productBranchRef(pull, product), { source: input.source, requestedBy: input.openedBy });
+  const existing = record.links.find((l) => l.piece === piece.id);
+  if (existing) return { status: "already-linked", plan, link: existing, preview: null, warnings: [] };
+  if (input.dryRun) return { status: "dry-run", plan, link: null, preview: null, warnings: [] };
+  if (!gh.canWrite) throw new GitHubError(401, "Opening a library branch needs a GitHub token (contents, pull requests and issues: write).");
+  const warnings = [];
+  const at = (/* @__PURE__ */ new Date()).toISOString();
+  const who = { ...input.openedBy ? { openedBy: input.openedBy } : {}, ...input.agent ? { agent: input.agent } : {} };
+  let link;
+  if (plan.kind === "token-change") {
+    if (!input.writeTokens) throw new GitHubError(422, "This piece is a token: open it where the token files are read (Bridge Studio, bridge_open_library_branch or `bridge pieces open`).");
+    const r = await input.writeTokens(plan);
+    link = { piece: piece.id, kind: "token-change", number: r.number, url: r.url, title: plan.title, branch: r.branch, at, ...who };
+  } else if (plan.kind === "exploration") {
+    const r = await startExplorationOnGitHub(gh, { ...plan.exploration, ...input.openedBy ? { author: input.openedBy } : {}, ...input.agent ? { agent: input.agent } : {} }, { base: input.base, ...input.exploration, labels: [NEEDED_BY_LABEL] });
+    link = { piece: piece.id, kind: "exploration", number: r.pr, url: r.url, title: plan.title, branch: r.branch, at, ...who };
+  } else {
+    const issue = composeRequestIssue(plan.request, { labels: [NEEDED_BY_LABEL] });
+    const r = await gh.createIssue(issue);
+    link = { piece: piece.id, kind: "request", number: r.number, url: r.url, title: plan.title, at, ...who };
+  }
+  try {
+    if (link.kind === "request") {
+      const issue = await gh.getIssue(link.number);
+      await gh.updateIssue(link.number, { body: withNeededBy(issue.body, plan.neededBy) });
+    } else {
+      const lib = await gh.getPullRequest(link.number);
+      await gh.updatePullRequest(link.number, { body: withNeededBy(lib.body, plan.neededBy) });
+      await gh.addLabels(link.number, [NEEDED_BY_LABEL]);
+    }
+  } catch (err) {
+    if (err instanceof GitHubError && err.auth === "rejected") throw err;
+    warnings.push(`The library side does not say who needs it yet (${err.message}). Add "Needed by #${input.pr}" to #${link.number} on GitHub.`);
+  }
+  const fresh = await gh.getPullRequest(input.pr);
+  const next = withLink(parsePiecesRecord(fresh.body) ?? record, link);
+  await gh.updatePullRequest(input.pr, { body: withPiecesRecord(fresh.body, next) });
+  let preview = null;
+  if ((input.usePreview ?? true) && link.kind === "token-change" && link.branch) {
+    preview = await useLibraryPreviewOnGitHub(gh, { productBranch: pull.headRef, libraryBranch: link.branch, libraryNumber: link.number }).catch((err) => {
+      warnings.push(`Your branch does not use the preview yet: ${err.message}`);
+      return null;
+    });
+  }
+  return { status: "opened", plan, link, preview, warnings };
+}
+var isNote = (path) => path.startsWith(`${EXPLORATION_NOTES_DIR}/`);
+async function linkedLibraryBranchOnGitHub(gh, link, product, piece) {
+  const nearest = piece?.nearest?.label;
+  if (link.kind === "request") {
+    const issue = await gh.getIssue(link.number);
+    const status2 = linkStatus({ kind: "request", state: issue.state, stateReason: issue.stateReason });
+    const lifecycle2 = issue.state === "closed" ? issue.stateReason === "not_planned" ? "closed" : "merged" : "open";
+    const behindMain2 = lifecycle2 === "merged" ? await gh.compare(product.baseRef, product.headSha).then((c) => c.behindBy, () => null) : null;
+    const preview2 = libraryPreviewState({ kind: "request", lifecycle: lifecycle2, hasChanges: false, missing: null, total: null, behindMain: behindMain2, nearest });
+    return { link, piece, status: status2, preview: preview2, people: status2.people };
+  }
+  const lib = await gh.getPullRequest(link.number);
+  const reviews = await gh.listReviews(link.number).catch(() => []);
+  const status = linkStatus({ kind: link.kind, state: lib.state, draft: lib.draft, labels: lib.labels, requestedReviewers: lib.requestedReviewers, reviews: reviews.map((r) => ({ user: r.user, state: r.state })) });
+  const lifecycle = lib.state === "merged" ? "merged" : lib.state === "open" ? "open" : "closed";
+  let missing = null;
+  let total = null;
+  let behindMain = null;
+  let hasChanges = true;
+  if (lifecycle === "open") {
+    const [files, own, inProduct] = await Promise.all([
+      gh.listPullRequestFiles(link.number).catch(() => null),
+      gh.compare(lib.baseRef, lib.headSha).catch(() => null),
+      gh.compare(product.headSha, lib.headSha).catch(() => null)
+    ]);
+    hasChanges = files ? files.some((f) => !isNote(f.filename)) : true;
+    total = own?.aheadBy ?? null;
+    missing = inProduct?.aheadBy ?? null;
+  } else if (lifecycle === "merged") {
+    behindMain = await gh.compare(product.baseRef, product.headSha).then((c) => c.behindBy, () => null);
+  }
+  const preview = libraryPreviewState({ kind: link.kind, lifecycle, hasChanges, missing, total, behindMain, nearest });
+  return { link, piece, status, preview, people: status.people };
+}
+async function productBranchViewOnGitHub(gh, pr, opts) {
+  const pull = await gh.getPullRequest(pr);
+  const files = await gh.listPullRequestFiles(pr).then((f) => f.map((x) => x.filename), () => []);
+  const product = productOf(opts.products, pull, files);
+  const record = parsePiecesRecord(pull.body);
+  const linked = await Promise.all(
+    (record?.links ?? []).map((l) => linkedLibraryBranchOnGitHub(gh, l, { headSha: pull.headSha, baseRef: pull.baseRef }, record?.pieces.find((p) => p.id === l.piece)))
+  );
+  const open = (record?.pieces ?? []).filter((p) => !record.links.some((l) => l.piece === p.id));
+  return { pull, product, record, sentence: productBranchSentence(record, { viewer: opts.viewer, agentName: opts.agentName }), linked, open };
+}
+async function switchToPublishedOnGitHub(gh, pr) {
+  if (!gh.canWrite) throw new GitHubError(401, "Switching needs a GitHub token (contents and pull requests: write).");
+  const pull = await gh.getPullRequest(pr);
+  if (pull.state !== "open") throw new GitHubError(422, `#${pr} is ${pull.state}: only an open branch switches.`);
+  const cmp = await gh.compare(pull.baseRef, pull.headSha);
+  if (cmp.behindBy === 0) return { status: "up-to-date", said: "Your branch already uses the published version." };
+  try {
+    await gh.updatePullRequestBranch(pr, pull.headSha);
+  } catch (err) {
+    if (err instanceof GitHubError && err.status === 422) throw new GitHubError(422, `Your branch and ${pull.baseRef} change the same lines, so Bridge cannot switch it alone. Use "Update from main" to pick the token values, or ask a developer.`, err.detail);
+    throw err;
+  }
+  return { status: "switched", said: `Your branch now uses the published version from ${pull.baseRef}.` };
+}
+
+// ../core/src/token-proposal.ts
+var issueKey2 = (i) => `${i.code}|${i.path ?? ""}|${i.file ?? ""}|${i.message}`;
+function planTokenProposal(input) {
+  const { before, config } = input;
+  const r = applyTokenEdits(before, input.edits);
+  const after = new LayeredTokenSet(before.config, r.files);
+  const changes = diffLayered(before, after);
+  if (!changes.length) return null;
+  const prevErrors = new Set(validateLayered(before).map(issueKey2));
+  const newErrors = validateLayered(after).filter((i) => i.level === "error" && !prevErrors.has(issueKey2(i)));
+  const modes = config.contrast?.modes;
+  const contrast = input.pairs.length ? contrastDelta(runLayeredContrast(before, input.pairs, modes), runLayeredContrast(after, input.pairs, modes)) : [];
+  const newFailures = contrast.filter((d) => d.passBefore && !d.passAfter);
+  const impact = layeredImpact(before, after, changes);
+  const tier = classifyLayered(changes, [], config);
+  const summary2 = input.summary?.trim() || input.title;
+  const body = [composeProposalBody({ summary: summary2, changes, contrast, impact, tier, validationErrors: newErrors.length, tool: input.tool ?? "Bridge MCP" }), ...input.bodyExtra ?? []].filter(Boolean).join("\n\n");
+  const slug2 = slugify(input.title, 48) || "change";
+  const changesetPath = `${config.changesets?.dir ?? ".changeset"}/bridge-${slug2}.md`;
+  const touched = r.touched.map((f) => after.repoPath(f));
+  const files = [
+    ...r.touched.map((f) => ({ path: after.repoPath(f), content: after.files.get(f) })),
+    ...config.changesets ? [{ path: changesetPath, content: formatChangeset(config.changesets.package, tier.bump, summary2) }] : []
+  ];
+  const blocked = newErrors.length || newFailures.length ? [newErrors.length ? `${newErrors.length} new validation error(s)` : "", newFailures.length ? `${newFailures.length} contrast pair(s) would fail` : ""].filter(Boolean).join(" and ") : null;
+  return { title: input.title, summary: summary2, before, after, changes, tier, contrast, newFailures, newErrors, impact, notes: r.notes, touched, files, body, slug: slug2, blocked };
+}
+async function writeTokenProposalOnGitHub(gh, plan, opts) {
+  if (plan.blocked) throw new Error(`Not opened: ${plan.blocked}. Bridge never opens a branch that breaks the gate.`);
+  const jira = opts.jira ?? null;
+  let branch = branchWithJiraKey(`${opts.branchPrefix}${plan.slug}`, jira);
+  for (let i = 2; await gh.getBranchSha(branch).then(Boolean, () => false); i++) branch = branchWithJiraKey(`${opts.branchPrefix}${plan.slug}-${i}`, jira);
+  const commit = await gh.commitToNewBranch({ base: opts.base, branch, message: `feat(tokens): ${plan.title}
+
+Proposed through ${opts.tool ?? "Bridge MCP"}. Tier ${plan.tier.tier}.`, files: plan.files });
+  const labels = [.../* @__PURE__ */ new Set([...opts.labels ?? [], `tier: ${plan.tier.tier}`, ...plan.tier.tier === 3 ? ["tokens"] : [], ...plan.tier.bump === "major" ? ["breaking"] : [], ...opts.labelsAfter ?? []])];
+  const draft = plan.tier.tier >= 2;
+  const pr = await gh.createPullRequest({ base: opts.base, head: branch, title: titleWithJiraKey(`feat(tokens): ${plan.title}`, jira), body: plan.body, draft });
+  await gh.addLabels(pr.number, labels);
+  return { branch, commit: commit.sha, pr: pr.number, url: pr.url, labels, draft };
+}
+
 // ../core/src/node/git-history.ts
 var US = "";
 var RS = "";
@@ -5744,8 +6182,8 @@ function tailwindFindings(hits, offset, pos, ds) {
     else if (cat === "font") cat = /^\d{3}$/.test(v) ? "font-weight" : "font-family";
     if (cat === "color" && !isColor) continue;
     const suggestion = ds.suggest(cat, v);
-    const cap = h.kind === "palette" && suggestion && suggestion.confidence > 0.6 ? { ...suggestion, confidence: 0.6, level: "medium" } : suggestion;
-    findings.push({ ...pos(offset + h.index), category: cat, value: h.cls, source: "tailwind", ...cap ? { suggestion: cap } : {} });
+    const cap2 = h.kind === "palette" && suggestion && suggestion.confidence > 0.6 ? { ...suggestion, confidence: 0.6, level: "medium" } : suggestion;
+    findings.push({ ...pos(offset + h.index), category: cat, value: h.cls, source: "tailwind", ...cap2 ? { suggestion: cap2 } : {} });
   }
   return { findings, themeRefs };
 }
@@ -6753,9 +7191,9 @@ var DesignSystemIndex = class {
         return generic ? this.make(generic, 1, 0.3) : void 0;
       }
       case "shadow": {
-        const norm2 = (s) => s.replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim().toLowerCase();
+        const norm3 = (s) => s.replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim().toLowerCase();
         const cands = this.entries(["shadow"]);
-        const exact = cands.find((e) => norm2(e.css) === norm2(value));
+        const exact = cands.find((e) => norm3(e.css) === norm3(value));
         if (exact) return this.make(exact, 0, 1);
         const t = shadowNums(value);
         const scored = cands.map((e) => {
@@ -7181,11 +7619,11 @@ async function listComponentNames(source, config) {
 }
 var findFamily = (stories) => stories ? /title:\s*['"]([^'"/]+)\//.exec(stories)?.[1] : void 0;
 async function listComponents(source, config, withSummaries) {
-  const names2 = await listComponentNames(source, config);
-  if (!withSummaries) return names2.map((n) => ({ name: n.name }));
+  const names3 = await listComponentNames(source, config);
+  if (!withSummaries) return names3.map((n) => ({ name: n.name }));
   const dir = config.components.dir;
   return Promise.all(
-    names2.map(async ({ name, files }) => {
+    names3.map(async ({ name, files }) => {
       const docsPath = `${dir}/${name}/${name}${config.components.docsSuffix}`;
       const storiesPath = files.find((f) => /\.stories\.\w+$/.test(f));
       const [docs, stories] = await Promise.all([files.includes(docsPath) ? source.read(docsPath) : null, storiesPath ? source.read(storiesPath) : null]);
@@ -7480,6 +7918,7 @@ __export(ops_exports, {
   auditOp: () => auditOp,
   auditUi: () => auditUi,
   checkContrast: () => checkContrast,
+  designSystemIndex: () => designSystemIndex,
   draftDocsOp: () => draftDocsOp,
   getComponentOp: () => getComponentOp,
   getConfig: () => getConfig,
@@ -7503,6 +7942,247 @@ import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:f
 import { mkdir as mkdir2, writeFile as writeFile2, access } from "node:fs/promises";
 import { dirname as dirname3, isAbsolute, join as join4, resolve as resolve3 } from "node:path";
 
+// ../core/src/audit/missing-pieces.ts
+var lines = (text) => text.split(/\r?\n/);
+function lineBag(text) {
+  const bag = /* @__PURE__ */ new Map();
+  for (const l of text ? lines(text) : []) {
+    const k = l.trim();
+    if (k) bag.set(k, (bag.get(k) ?? 0) + 1);
+  }
+  return bag;
+}
+var offsetOf = (text, line, column) => {
+  let off = 0;
+  const ls = text.split("\n");
+  for (let i = 0; i < line - 1 && i < ls.length; i++) off += ls[i].length + 1;
+  return off + Math.max(0, column - 1);
+};
+function enclosingTag(text, offset) {
+  for (let i = offset - 1; i >= Math.max(0, offset - 4e3); i--) {
+    if (text[i] !== "<" || !/[A-Za-z]/.test(text[i + 1] ?? "")) continue;
+    let depth = 0;
+    let closed = false;
+    for (let j = i + 1; j < offset; j++) {
+      const c = text[j];
+      if (c === "{") depth++;
+      else if (c === "}") depth--;
+      else if (c === ">" && depth <= 0 && text[j - 1] !== "=") {
+        closed = true;
+        break;
+      }
+    }
+    if (closed) return null;
+    const m = /^<([A-Za-z][\w.]*)/.exec(text.slice(i));
+    return m ? { name: m[1], start: i } : null;
+  }
+  return null;
+}
+function childText(text, tagStart) {
+  let depth = 0;
+  for (let j = tagStart + 1; j < text.length; j++) {
+    const c = text[j];
+    if (c === "{") depth++;
+    else if (c === "}") depth--;
+    else if (c === ">" && depth <= 0 && text[j - 1] !== "=") {
+      if (text[j - 1] === "/") return null;
+      const rest = /^([^<{]*)</.exec(text.slice(j + 1));
+      const t = rest?.[1]?.trim() ?? "";
+      return t && t.split(/\s+/).length <= 3 && t.length <= 30 ? t : null;
+    }
+  }
+  return null;
+}
+function ruleClasses(text, offset) {
+  const open = text.lastIndexOf("{", offset);
+  if (open < 0) return [];
+  const prev = Math.max(text.lastIndexOf("}", open), text.lastIndexOf(";", open));
+  const selector = text.slice(prev + 1, open);
+  return [...selector.matchAll(/\.([A-Za-z_][\w-]*)/g)].map((m) => m[1]);
+}
+var GENERIC = /* @__PURE__ */ new Set(["status", "badge", "tag", "pill", "chip", "style", "styles", "root", "wrapper", "container", "item", "label", "text", "color", "bg", "is", "has", "variant", "tone", "custom", "new"]);
+function nameFromClass(cls, component) {
+  const words = cls.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[\s_-]+/).map((w) => w.toLowerCase()).filter(Boolean);
+  const comp = component?.toLowerCase();
+  const kept = words.filter((w) => w !== comp && !GENERIC.has(w));
+  return kept[kept.length - 1] ?? words[words.length - 1] ?? cls;
+}
+var ASPECT = { color: "tone", radius: "shape", spacing: "size", size: "size", "font-size": "size", "line-height": "size" };
+function aspectOf(values) {
+  for (const a of ["tone", "shape", "size"]) if (values.some((v) => ASPECT[v.category] === a)) return a;
+  return "style";
+}
+var norm2 = (f) => f.category === "color" ? f.value.toLowerCase() : f.value.replace(/\s+/g, "");
+function nearestOf(s) {
+  if (!s) return void 0;
+  return { token: s.token, cssVar: s.cssVar, value: s.value, level: s.level, label: tokenLabel(s.token) };
+}
+var TOKEN_TYPE = { color: "color", duration: "duration", "font-weight": "fontWeight", "line-height": "number", "z-index": "number", "font-family": "fontFamily", shadow: "shadow", easing: "cubicBezier" };
+var valueTitle = (category, value) => {
+  const v = category === "color" && /^#[0-9a-f]+$/i.test(value) ? value.toUpperCase() : value;
+  const word = { color: "color", radius: "radius", spacing: "spacing", size: "size", "font-size": "text size", "font-weight": "font weight", "line-height": "line height", shadow: "shadow", duration: "duration", easing: "easing", "z-index": "layer", "border-width": "border width", "font-family": "font" };
+  return `New ${word[category] ?? category} ${v}`;
+};
+function missingPieces(input) {
+  const { ds } = input;
+  const files = input.files.filter((f) => f.after !== null && isAuditable(f.path));
+  const fixes = [];
+  const variants = /* @__PURE__ */ new Map();
+  const tokens = /* @__PURE__ */ new Map();
+  const foreign = /* @__PURE__ */ new Map();
+  const classUse = (cls) => {
+    const re = new RegExp(`<([A-Z][\\w.]*)\\b[^<]*?styles(?:\\.${cls}\\b|\\[['"]${cls}['"]\\])`);
+    for (const f of files) {
+      const m = re.exec(f.after);
+      if (m && ds.components.has(m[1].split(".")[0])) return { component: m[1].split(".")[0], text: childText(f.after, m.index) };
+    }
+    return null;
+  };
+  for (const f of files) {
+    const after = f.after;
+    const report = auditFile(f.path, after, ds);
+    const before = lineBag(f.before);
+    const afterLines = lines(after);
+    const added = (line) => {
+      const k = afterLines[line - 1]?.trim() ?? "";
+      const n = before.get(k) ?? 0;
+      if (n > 0) {
+        before.set(k, n - 1);
+        return false;
+      }
+      return true;
+    };
+    const addedLines = /* @__PURE__ */ new Map();
+    const isNew = (line) => {
+      if (!addedLines.has(line)) addedLines.set(line, added(line));
+      return addedLines.get(line);
+    };
+    const css = report.lang === "css" || report.lang === "scss" || report.lang === "less";
+    for (const finding of report.findings) {
+      if (!isNew(finding.line)) continue;
+      const s = finding.suggestion;
+      const at = { file: f.path, line: finding.line };
+      if (s?.level === "exact" || s?.level === "high" && finding.category !== "color") {
+        fixes.push({ ...at, what: finding.value, use: s.token });
+        continue;
+      }
+      const offset = offsetOf(after, finding.line, finding.column);
+      let component = null;
+      let name = null;
+      if (css) {
+        const classes = ruleClasses(after, offset);
+        for (const cls of [...classes].reverse()) {
+          const use = classUse(cls);
+          if (use) {
+            component = use.component;
+            name = nameFromClass(cls, use.component);
+            break;
+          }
+        }
+        if (!component && classes.length) name = nameFromClass(classes[classes.length - 1]);
+      } else {
+        const tag = enclosingTag(after, offset);
+        const root = tag?.name.split(".")[0];
+        if (tag && root && ds.components.has(root)) {
+          component = root;
+          name = childText(after, tag.start);
+          const cls = /className=\{?["'`]?([\w-]+)/.exec(after.slice(tag.start, offset))?.[1];
+          if (!name && cls) name = nameFromClass(cls, root);
+        }
+      }
+      const hit = { ...at, finding };
+      if (component) {
+        const label = (name ?? "custom").toLowerCase();
+        const key2 = `${component}|${label}`;
+        const v = variants.get(key2) ?? { component, name: label, hits: [] };
+        v.hits.push(hit);
+        variants.set(key2, v);
+        continue;
+      }
+      const key = `${finding.category}|${norm2(finding)}`;
+      const t = tokens.get(key) ?? { category: finding.category, value: finding.value, name, hits: [] };
+      if (!t.name && name) t.name = name;
+      t.hits.push(hit);
+      tokens.set(key, t);
+    }
+    for (const c of report.components) {
+      if (!isNew(c.line)) continue;
+      if (c.suggestion) {
+        fixes.push({ file: f.path, line: c.line, what: c.name, use: c.suggestion });
+        continue;
+      }
+      if (c.kind !== "foreign") continue;
+      const e = foreign.get(c.name) ?? { finding: c, hits: [] };
+      e.hits.push({ file: f.path, line: c.line });
+      foreign.set(c.name, e);
+    }
+  }
+  const where = (hits) => hits.slice(0, 5).map((h) => ({ file: h.file, line: h.line }));
+  const pieces = [];
+  for (const v of variants.values()) {
+    const values = [];
+    for (const h of v.hits) {
+      const pv = { category: h.finding.category, ...h.finding.property ? { property: h.finding.property } : {}, value: h.finding.value };
+      if (!values.some((x) => x.category === pv.category && x.property === pv.property && norm2(x) === norm2(pv))) values.push(pv);
+    }
+    const aspect = aspectOf(values);
+    const bg = v.hits.find((h) => /background/.test(h.finding.property ?? ""))?.finding.suggestion;
+    const nearest = nearestOf(bg ?? v.hits.find((h) => h.finding.suggestion)?.finding.suggestion);
+    const shown = values.map((x) => `${x.property ?? x.category} ${x.value}`).join(", ");
+    pieces.push({
+      id: pieceId([v.component, v.name, aspect]),
+      kind: "variant",
+      title: `${v.component}: ${v.name} ${aspect}`,
+      summary: `${v.component} restyled by hand (${shown}).${nearest ? ` ${nearest.level === "high" ? "It looks a lot like" : "The closest in the library is"} ${nearest.label}.` : ""}`,
+      name: v.name,
+      component: v.component,
+      aspect,
+      values,
+      ...nearest ? { nearest } : {},
+      where: where(v.hits)
+    });
+  }
+  for (const [name, e] of foreign) {
+    pieces.push({
+      id: pieceId(["component", name]),
+      kind: "component",
+      title: `New component: ${name}`,
+      summary: `${name} comes from ${e.finding.library}, and the library has nothing like it.`,
+      name,
+      component: name.split(".").pop(),
+      values: [],
+      where: where(e.hits)
+    });
+  }
+  for (const t of tokens.values()) {
+    const nearest = nearestOf(t.hits[0].finding.suggestion);
+    const pname = t.name ?? `${t.category === "color" ? "custom" : t.category}`;
+    const path = proposedTokenPath(nearest?.token, pname, t.category);
+    const tokenFiles = nearest && input.set ? [...new Set(input.set.defs.filter((d) => d.path === nearest.token).map((d) => d.file))] : [];
+    const n = t.hits.length;
+    pieces.push({
+      id: pieceId([t.category, t.name ?? t.value.replace(/^#/, "")]),
+      kind: "token",
+      title: valueTitle(t.category, t.value),
+      summary: `Written by hand in ${n === 1 ? "one place" : `${n} places`}.${nearest ? ` ${nearest.level === "high" ? "It looks a lot like" : "The closest in the library is"} ${nearest.label} (${nearest.value}).` : " The library has nothing close."}`,
+      name: pname,
+      values: [{ category: t.category, ...t.hits[0].finding.property ? { property: t.hits[0].finding.property } : {}, value: t.value }],
+      ...nearest ? { nearest } : {},
+      where: where(t.hits),
+      token: { path, type: TOKEN_TYPE[t.category] ?? "dimension", value: t.value, files: tokenFiles }
+    });
+  }
+  const order = { variant: 0, component: 1, token: 2 };
+  const seen = /* @__PURE__ */ new Set();
+  const out = pieces.sort((a, b) => order[a.kind] - order[b.kind]).map((p) => {
+    let id = p.id;
+    for (let i = 2; seen.has(id); i++) id = `${p.id}-${i}`;
+    seen.add(id);
+    return id === p.id ? p : { ...p, id };
+  });
+  return { pieces: out, fixes, files: files.length };
+}
+
 // src/audit.ts
 var PROPERTY_HINTS = [
   [/^(color|fill|stroke)$/, /(^|\.)(text|fg|icon|foreground|link)(\.|-|$)/],
@@ -7523,8 +8203,8 @@ function auditSnippet(set, code2, max = 3) {
   });
   const rank2 = (tier) => tier === "semantic" ? 0 : tier === "component" ? 1 : tier === "density" ? 2 : tier === "brand" ? 3 : 4;
   const findings = [];
-  const lines = code2.split("\n");
-  lines.forEach((line, i) => {
+  const lines2 = code2.split("\n");
+  lines2.forEach((line, i) => {
     if (/var\(--/.test(line) && !/#[0-9a-f]{3,8}\b|\d(px|rem|ms)\b/i.test(line.replace(/var\([^)]*\)/g, ""))) return;
     const stripped = line.replace(/var\([^)]*\)/g, "");
     const propAt = (idx) => /([a-zA-Z-]+)['"]?\s*:[^;:,{]*$/.exec(stripped.slice(0, idx))?.[1]?.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).toLowerCase();
@@ -7592,17 +8272,17 @@ function auditSnippet(set, code2, max = 3) {
 // src/markdown.ts
 var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 function sections(md) {
-  const lines = md.split("\n");
+  const lines2 = md.split("\n");
   const heads = [];
   let fence = false;
-  lines.forEach((l, i) => {
+  lines2.forEach((l, i) => {
     if (/^\s*(```|~~~)/.test(l)) fence = !fence;
     const m = !fence && /^(#{1,4})\s+(.+?)\s*#*\s*$/.exec(l);
     if (m) heads.push({ level: m[1].length, title: m[2], line: i });
   });
   return heads.map((h, i) => {
     const next = heads.slice(i + 1).find((x) => x.level <= h.level);
-    return { level: h.level, title: h.title, slug: slug(h.title), body: lines.slice(h.line, next ? next.line : lines.length).join("\n").trim() };
+    return { level: h.level, title: h.title, slug: slug(h.title), body: lines2.slice(h.line, next ? next.line : lines2.length).join("\n").trim() };
   });
 }
 function toc(md) {
@@ -7634,6 +8314,7 @@ __export(explorations_exports, {
   installOf: () => installOf,
   listExplorations: () => listExplorations,
   promoteExploration: () => promoteExploration,
+  settingsOf: () => settingsOf,
   startExploration: () => startExploration,
   toExplorationBranch: () => toExplorationBranch,
   writeToExploration: () => writeToExploration
@@ -7658,13 +8339,16 @@ __export(branches_exports, {
   listProducts: () => listProducts,
   mergeBranch: () => mergeBranch,
   productMarks: () => productMarks,
+  reader: () => reader,
   reopenBranch: () => reopenBranch,
   resolveProduct: () => resolveProduct,
   reviewBranch: () => reviewBranch,
   sendForReview: () => sendForReview,
   tryBranch: () => tryBranch,
   updateFromMain: () => updateFromMain,
-  whatNeedsMe: () => whatNeedsMe
+  viewerOf: () => viewerOf,
+  whatNeedsMe: () => whatNeedsMe,
+  writer: () => writer
 });
 import { relative as relative2 } from "node:path";
 var RIGHTS = {
@@ -7976,11 +8660,11 @@ async function commentOnBranch(ctx, a) {
 async function listComments(ctx, a) {
   const n = branchNumber(a.pr);
   const gh = await reader(ctx);
-  const [conversation, lines] = await Promise.all([gh.listIssueComments(n), gh.listReviewComments(n).catch(() => [])]);
+  const [conversation, lines2] = await Promise.all([gh.listIssueComments(n), gh.listReviewComments(n).catch(() => [])]);
   return {
     pr: n,
     conversation: conversation.filter((c) => !c.body.includes("<!-- bridge-branch-preview -->")).map((c) => ({ id: c.id, author: c.author, body: c.body, at: c.updatedAt })),
-    threads: lines.filter((c) => !c.inReplyTo).map((c) => ({ id: c.id, author: c.author, file: c.path, line: c.line, body: c.body, url: c.url, replies: lines.filter((r) => r.inReplyTo === c.id).map((r) => ({ id: r.id, author: r.author, body: r.body })) })),
+    threads: lines2.filter((c) => !c.inReplyTo).map((c) => ({ id: c.id, author: c.author, file: c.path, line: c.line, body: c.body, url: c.url, replies: lines2.filter((r) => r.inReplyTo === c.id).map((r) => ({ id: r.id, author: r.author, body: r.body })) })),
     howToReply: "bridge_comment with replyTo: the thread id."
   };
 }
@@ -8432,7 +9116,7 @@ async function checkContrast(ctx, a) {
   const delta2 = core.contrastDelta(beforeRes, afterRes);
   return { ...base, edits: a.edits.length, notes, changed: delta2, newFailures: delta2.filter((d) => d.passBefore && !d.passAfter) };
 }
-var issueKey2 = (i) => `${i.code}|${i.path ?? ""}|${i.file ?? ""}|${i.message}`;
+var issueKey3 = (i) => `${i.code}|${i.path ?? ""}|${i.file ?? ""}|${i.message}`;
 async function validateTokens(ctx, a) {
   const { before, after, notes } = await withEdits(ctx, a.edits);
   const issues = core.validate(after);
@@ -8448,8 +9132,8 @@ async function validateTokens(ctx, a) {
     ...a.includeWarnings ? { warnings } : warnings.length ? { warningSample: warnings.slice(0, 5) } : {}
   };
   if (!a.edits?.length) return res;
-  const prev = new Set(core.validate(before).map(issueKey2));
-  return { ...res, notes, newErrors: errors.filter((i) => !prev.has(issueKey2(i))) };
+  const prev = new Set(core.validate(before).map(issueKey3));
+  return { ...res, notes, newErrors: errors.filter((i) => !prev.has(issueKey3(i))) };
 }
 async function listComponentsOp(ctx, a) {
   const { config } = await ctx.config();
@@ -8602,25 +9286,13 @@ async function proposeTokenChange(ctx, a) {
   const target = a.branch ? await explorationContext(ctx, a.branch, { requireCheckout: !a.dryRun }) : null;
   if (target) ctx = target.ctx;
   const { config } = await ctx.config();
-  const { before, after, touched, notes } = await withEdits(ctx, a.edits);
-  const changes = core.diff(before, after);
-  if (!changes.length) return { status: "no-change", message: "The edits leave every token as it was." };
-  const prevErrors = new Set(core.validate(before).map(issueKey2));
-  const newErrors = core.validate(after).filter((i) => i.level === "error" && !prevErrors.has(issueKey2(i)));
+  const before = await ctx.tokens();
   const pairs = await core.readContrastPairs(ctx.source, config).catch(() => []);
-  const delta2 = pairs.length ? core.contrastDelta(core.runContrast(before, pairs, config.contrast?.modes), core.runContrast(after, pairs, config.contrast?.modes)) : [];
-  const newFailures = delta2.filter((d) => d.passBefore && !d.passAfter);
-  const imp = core.impact(before, after, changes);
-  const tier = core.classify(changes, [], config);
-  const summary2 = a.summary?.trim() || a.title;
   const marks = productMarks(productsOf(config), product);
-  const body = [core.prBody({ summary: summary2, changes, contrast: delta2, impact: imp, tier, validationErrors: newErrors.length, tool: "Bridge MCP" }), marks.line].filter(Boolean).join("\n\n");
-  const slugTitle = core.slugify(a.title);
-  const changesetPath = `${config.changesets?.dir ?? ".changeset"}/bridge-${slugTitle}.md`;
-  const files = [
-    ...touched.map((f) => ({ path: prefixPath(after, f), content: after.files.get(f) })),
-    ...config.changesets ? [{ path: changesetPath, content: core.changeset(config.changesets.package, tier.bump, summary2) }] : []
-  ];
+  const plan = planTokenProposal({ before, pairs, edits: a.edits, title: a.title, summary: a.summary, config, tool: "Bridge MCP", bodyExtra: [marks.line] });
+  if (!plan) return { status: "no-change", message: "The edits leave every token as it was." };
+  const { after, changes, tier, contrast: delta2, newFailures, newErrors, impact: imp, notes, files, body, slug: slugTitle } = plan;
+  const summary2 = plan.summary;
   const report = {
     title: a.title,
     tier: tier.tier,
@@ -8669,15 +9341,12 @@ Tier ${tier.tier}. Proposed through Bridge MCP (source: mcp).`;
   }
   const gh = await ctx.github();
   if (!ctx.canWriteRemote) return { status: "preview", message: "Read-only: set GITHUB_TOKEN to open this as a pull request.", ...preview, fileContents: files };
-  const commitMsg = `feat(tokens): ${a.title}
-
-Proposed through Bridge MCP (source: mcp). Tier ${tier.tier}.`;
   const base = ctx.ref ?? baseBranchOf(config);
-  for (let i = 2; await gh.getBranchSha(branch).then(Boolean, () => false); i++) branch = branchWithJiraKey(`${config.governance.branchPrefix}${slugTitle}-${i}`, jira);
-  const commit = await gh.commitToNewBranch({ base, branch, message: commitMsg, files });
-  const labels = [...config.governance.labels, `tier: ${tier.tier}`, ...tier.tier === 3 ? ["tokens"] : [], ...tier.bump === "major" ? ["breaking"] : [], ...marks.labels];
-  const pr = await gh.createPullRequest({ base, head: branch, title: titleWithJiraKey(`feat(tokens): ${a.title}`, jira), body, draft: tier.tier >= 2 });
-  await gh.addLabels(pr.number, labels);
+  const opened = await writeTokenProposalOnGitHub(gh, plan, { base, branchPrefix: config.governance.branchPrefix, jira, labels: config.governance.labels, labelsAfter: marks.labels, tool: "Bridge MCP (source: mcp)" });
+  branch = opened.branch;
+  const commit = { sha: opened.commit };
+  const pr = { number: opened.pr, url: opened.url };
+  const labels = opened.labels;
   return { status: "pr-opened", ...preview, branch, commit: commit.sha, pr: pr.number, url: pr.url, labels, draft: tier.tier >= 2, product: product.name };
 }
 async function addToBranch(ctx, a) {
@@ -8688,8 +9357,8 @@ async function addToBranch(ctx, a) {
   const { before, after, touched, notes } = await withEdits(at, a.edits);
   const changes = core.diff(before, after);
   if (!changes.length) return { status: "no-change", pr: n, message: `#${n} already has these values.` };
-  const prevErrors = new Set(core.validate(before).map(issueKey2));
-  const newErrors = core.validate(after).filter((i) => i.level === "error" && !prevErrors.has(issueKey2(i)));
+  const prevErrors = new Set(core.validate(before).map(issueKey3));
+  const newErrors = core.validate(after).filter((i) => i.level === "error" && !prevErrors.has(issueKey3(i)));
   const pairs = await core.readContrastPairs(at.source, config).catch(() => []);
   const delta2 = pairs.length ? core.contrastDelta(core.runContrast(before, pairs, config.contrast?.modes), core.runContrast(after, pairs, config.contrast?.modes)) : [];
   const newFailures = delta2.filter((d) => d.passBefore && !d.passAfter);
@@ -8786,7 +9455,7 @@ async function getReview(ctx, a) {
   const changes = core.diff(before, after);
   const pairs = await core.readContrastPairs(headSrc, config).catch(() => []);
   const delta2 = pairs.length ? core.contrastDelta(core.runContrast(before, pairs, config.contrast?.modes), core.runContrast(after, pairs, config.contrast?.modes)) : [];
-  const prevErrors = new Set(core.validate(before).map(issueKey2));
+  const prevErrors = new Set(core.validate(before).map(issueKey3));
   const errors = core.validate(after).filter((i) => i.level === "error");
   const tokenRoot = config.tokens.root.replace(/\/$/, "");
   const otherFiles = changedFiles.filter((f) => !f.startsWith(`${tokenRoot}/`) && !f.startsWith(`${config.changesets?.dir ?? ".changeset"}/`));
@@ -8804,7 +9473,7 @@ async function getReview(ctx, a) {
     diffTable: core.tokenTable(changes.map((c) => ({ ...c, file: prefixPath(after, c.file) }))),
     contrastTable: core.contrastTable(delta2),
     contrastNewFailures: delta2.filter((d) => d.passBefore && !d.passAfter).length,
-    validation: { errors: errors.length, newErrors: errors.filter((i) => !prevErrors.has(issueKey2(i))) },
+    validation: { errors: errors.length, newErrors: errors.filter((i) => !prevErrors.has(issueKey3(i))) },
     impact: imp
   };
 }
@@ -9632,8 +10301,142 @@ async function figmaCoverage(ctx, a = {}) {
   };
 }
 
+// src/pieces.ts
+var pieces_exports = {};
+__export(pieces_exports, {
+  missingPiecesOp: () => missingPiecesOp,
+  openLibraryBranchOp: () => openLibraryBranchOp,
+  productBranchOp: () => productBranchOp,
+  switchToPublishedOp: () => switchToPublishedOp,
+  useLibraryPreviewOp: () => useLibraryPreviewOp
+});
+var NEED = "Contents, Pull requests and Issues: read and write";
+var short = (p) => ({
+  id: p.id,
+  kind: p.kind,
+  title: p.title,
+  summary: p.summary,
+  ...p.component ? { component: p.component } : {},
+  ...p.nearest ? { nearest: `${p.nearest.label} (${p.nearest.token}, ${p.nearest.value})` } : {},
+  ...p.token ? { token: p.token.path } : {},
+  where: p.where.map((w) => `${w.file}:${w.line}`),
+  opens: p.kind === "token" ? "a token change" : p.kind === "variant" ? "a library exploration" : "a component request"
+});
+async function missingPiecesOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const gh = a.record ? await writer(ctx, "Recording the missing pieces", NEED) : await reader(ctx);
+  const { config } = await ctx.config();
+  const read = await readProductBranchOnGitHub(gh, n, { products: productsOf(config) });
+  const [ds, set] = await Promise.all([designSystemIndex(ctx), ctx.tokens()]);
+  const r = missingPieces({ files: read.files, ds, set });
+  const recorded = a.record ? await recordPiecesOnGitHub(gh, n, { pieces: r.pieces, fixes: r.fixes.length, headSha: read.pull.headSha }) : null;
+  const linked = recorded?.links ?? read.record?.links ?? [];
+  return {
+    pr: n,
+    branch: read.pull.headRef,
+    product: read.product.name,
+    files: r.files,
+    ...read.skipped ? { skipped: `${read.skipped} more product files were not read (limit ${r.files}).` } : {},
+    pieces: r.pieces.map((p) => ({ ...short(p), ...linked.some((l) => l.piece === p.id) ? { linked: linked.find((l) => l.piece === p.id).number } : {} })),
+    fixes: { count: r.fixes.length, sample: r.fixes.slice(0, 10).map((f) => `${f.file}:${f.line} ${f.what} -> use ${f.use}`) },
+    recorded: Boolean(recorded),
+    next: r.pieces.length ? `${a.record ? "" : "Record them (record: true) so Studio shows them, then "}open a library branch for each with bridge_open_library_branch { pr: ${n}, piece: "<id>" }. Fixes are values and components the library already has: use them in the product code instead.` : "Nothing is missing from the library. Fix the values that equal a token, if any."
+  };
+}
+function tokenWriter(ctx, gh, source) {
+  return async (plan) => {
+    const { config } = await ctx.config();
+    const [before, pairs] = await Promise.all([ctx.tokens(), core.readContrastPairs(ctx.source, config).catch(() => [])]);
+    const p = planTokenProposal({ before, pairs, edits: plan.edits, title: plan.title, summary: plan.summary, config, tool: source === "mcp" ? "Bridge MCP" : "the bridge CLI" });
+    if (!p) throw new Error("The token already exists with that value: nothing to add.");
+    if (p.blocked) throw new Error(`The library branch was not opened: ${p.blocked}. Change the value (bridge_propose_token_change with dryRun shows why).`);
+    const opened = await writeTokenProposalOnGitHub(gh, p, { base: baseBranchOf(config), branchPrefix: config.governance.branchPrefix, labels: config.governance.labels, labelsAfter: [NEEDED_BY_LABEL], tool: source === "mcp" ? "Bridge MCP (source: mcp)" : "the bridge CLI" });
+    return { number: opened.pr, url: opened.url, branch: opened.branch };
+  };
+}
+async function openLibraryBranchOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const source = a.source ?? "mcp";
+  const gh = a.dryRun ? await reader(ctx) : await writer(ctx, "Opening a library branch", NEED);
+  const { config } = await ctx.config();
+  const viewer = await viewerOf(ctx, gh);
+  const s = settingsOf(config);
+  const r = await openLibraryBranchOnGitHub(gh, {
+    pr: n,
+    piece: a.piece,
+    base: s.base,
+    products: productsOf(config),
+    exploration: { packages: s.packages, apps: s.apps },
+    writeTokens: tokenWriter(ctx, gh, source),
+    ...viewer ? { openedBy: viewer } : {},
+    ...source === "mcp" ? { agent: "claude" } : {},
+    source,
+    usePreview: a.usePreview,
+    dryRun: a.dryRun
+  });
+  const plan = r.plan;
+  const what = plan.kind === "token-change" ? "token change" : plan.kind === "exploration" ? "library exploration" : "component request";
+  const next = r.status === "dry-run" ? `Run it without dryRun to open the ${what}.` : plan.kind === "exploration" ? `Build it on ${r.link?.branch}: ${plan.brief} Then bridge_use_library_preview { pr: ${n}, piece: "${a.piece}" } so the product branch shows it.` : plan.kind === "request" ? "A person or Claude builds the component from the request (bridge_get_request). The product branch keeps its own version until it ships." : r.preview?.status === "conflict" ? r.preview.said : "Design and tech owners review the token change. Once it ships, bridge_switch_to_published moves the product branch to the real version.";
+  return {
+    status: r.status,
+    pr: n,
+    piece: a.piece,
+    opens: what,
+    title: plan.title,
+    ...plan.kind === "token-change" ? { edits: plan.edits } : {},
+    ...plan.kind === "exploration" ? { exploration: plan.exploration.name, brief: plan.brief } : {},
+    ...plan.kind === "request" ? { request: plan.request.title } : {},
+    neededBy: `${plan.neededBy.title} (#${plan.neededBy.pr}) in ${plan.neededBy.productName}`,
+    ...r.link ? { library: { kind: r.link.kind, number: r.link.number, url: r.link.url, ...r.link.branch ? { branch: r.link.branch } : {} } } : {},
+    ...r.preview ? { preview: r.preview } : {},
+    ...r.warnings.length ? { warnings: r.warnings } : {},
+    next
+  };
+}
+async function productBranchOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const gh = await reader(ctx);
+  const { config } = await ctx.config();
+  const viewer = await viewerOf(ctx, gh);
+  const v = await productBranchViewOnGitHub(gh, n, { products: productsOf(config), viewer });
+  return {
+    pr: n,
+    title: v.pull.title,
+    product: v.product.name,
+    said: `${v.sentence.lead}${v.sentence.strong}${v.sentence.rest}`,
+    checked: v.record ? v.record.checkedAt : null,
+    linked: v.linked.map((l) => ({
+      piece: l.piece?.title ?? l.link.piece,
+      library: { kind: l.link.kind, number: l.link.number, url: l.link.url },
+      status: l.status.line,
+      preview: l.preview.sentence,
+      ...l.preview.action ? { action: l.preview.action.label, tool: l.preview.action.kind === "switch" ? `bridge_switch_to_published { pr: ${n} }` : `bridge_use_library_preview { pr: ${n}, piece: "${l.link.piece}" }` } : {}
+    })),
+    notLinked: v.open.map(short),
+    ...v.record ? {} : { next: `Find its missing pieces: bridge_missing_pieces { pr: ${n}, record: true }.` }
+  };
+}
+async function useLibraryPreviewOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const gh = await writer(ctx, "Using a library preview", "Contents: read and write");
+  const { config } = await ctx.config();
+  const v = await productBranchViewOnGitHub(gh, n, { products: productsOf(config) });
+  const l = v.linked.find((x) => x.link.piece === a.piece);
+  if (!l) throw new Error(`No library branch for "${a.piece}" on #${n}. Open one first: bridge_open_library_branch.`);
+  if (l.link.kind === "request" || !l.link.branch) throw new Error(`"${l.link.title}" is a request: there is nothing to preview until it is built.`);
+  if (l.status.key === "shipped") throw new Error("The library already shipped it: use bridge_switch_to_published instead.");
+  if (l.status.key === "closed") throw new Error("The library branch is closed: there is nothing to preview.");
+  const r = await useLibraryPreviewOnGitHub(gh, { productBranch: v.pull.headRef, libraryBranch: l.link.branch, libraryNumber: l.link.number });
+  return { pr: n, piece: a.piece, library: l.link.number, ...r };
+}
+async function switchToPublishedOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const gh = await writer(ctx, "Switching to the published version", "Contents and Pull requests: read and write");
+  return { pr: n, ...await switchToPublishedOnGitHub(gh, n) };
+}
+
 // src/server.ts
-var VERSION = true ? "0.4.1" : "dev";
+var VERSION = true ? "0.5.0" : "dev";
 var ok = (data) => ({ content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] });
 var fail = (e) => ({ content: [{ type: "text", text: `Error: ${e.message ?? String(e)}` }], isError: true });
 var run = (fn) => async (a) => {
@@ -9673,6 +10476,7 @@ function createServer(ctx) {
         `Change texts from Figma and docs from Bridge Studio: when the user says "${DRAFT_PHRASE}" (or asks you to draft their Bridge changes or docs), call bridge_pending_drafts. For change items, look at the before and after images and write each title, summary and change line in the Bridge voice. For docs items (scope "docs"), follow the brief: write only the sections it asks for, grounded in the props, CSS module classes and source it quotes, never an invented prop or behavior, never anatomy. Then call bridge_write_drafts. The designer reviews them in the DS Bridge Figma plugin or on the Library page.`,
         "Studio parity: a designer can do in Claude what they do in Bridge Studio. Branches in review: bridge_what_needs_me (the queue), bridge_branch_status, bridge_send_for_review, bridge_back_to_draft, bridge_review_branch, bridge_ask_someone_else, bridge_comment, bridge_update_from_main (token conflicts too), bridge_try_branch (try it in a product, share it), bridge_combine_branches, bridge_close_branch, bridge_reopen_branch, bridge_merge_branch (same gate as Studio, owner override with a reason). Docs: bridge_save_docs. Writes act under the person's GitHub token: only do them when the person asked, and merge only when they explicitly asked to merge.",
         'Products: work starts for a product (bridge_list_products). Tools that start work take "product"; without it Bridge uses the product of the current folder or repo. Ask the person when it is not obvious.',
+        "Product branches and the library: when a designer explores a product feature with you (an exploration for a product), check it with bridge_missing_pieces (record: true) before they share it; for each piece the library lacks, offer bridge_open_library_branch, which opens the library side linked to their branch. bridge_product_branch says where each library branch stands; bridge_switch_to_published moves the product branch to the real version once the library ships.",
         'Explorations try experimental variables and components in a product staging branch without touching main: an explore/<slug> branch with a draft pull request labeled exploration, previews and a snapshot package. bridge_start_exploration starts one, bridge_list_explorations lists them. To work on one, pass "branch": "explore/<slug>" to bridge_propose_token_change, bridge_draft_docs and bridge_get_request, and never open a pull request to main from it: a person promotes it to review or closes it.'
       ].join(" ")
     }
@@ -10170,6 +10974,57 @@ function createServer(ctx) {
   const Pr = z.union([z.number().int().positive(), z.string().min(1)]).describe('The branch number Studio shows (12 or "#12"), or its GitHub link.');
   const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
   const READ = { readOnlyHint: true, openWorldHint: true };
+  const Piece = z.string().min(1).describe('The piece id bridge_missing_pieces returned ("badge-overdue-tone").');
+  server.registerTool(
+    "bridge_missing_pieces",
+    {
+      title: "Find what a product branch adds outside the library",
+      description: 'Check a product branch (an exploration started for a product) against the library: the adoption audit on each product file it changes, at its start and at its head, keeps what the branch added. New hardcoded values become token pieces beside the closest token, values written on a library component become a variant of it ("Badge: overdue tone"), components from another UI library with no library equivalent become new components. Values equal to a token and components the library has are fixes, not pieces. With record: true, saves the result in the branch description, where Bridge Studio shows it (needs GITHUB_TOKEN, pull requests: write). Run it when a designer finishes exploring with you, then offer to open a library branch for each piece.',
+      inputSchema: { pr: Pr, record: z.boolean().optional().describe("Save the pieces in the product branch description (Studio reads them there). Keeps the library branches already opened.") },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    run((a) => missingPiecesOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_open_library_branch",
+    {
+      title: "Open a library branch for a missing piece",
+      description: 'Turn one recorded missing piece into a library branch linked to the product branch, as Bridge Studio does: a token piece opens a token change (same gate and body as bridge_propose_token_change, a draft for design and tech review) and the product branch takes its preview; a variant opens a library exploration with the brief to build it (build it there, then bridge_use_library_preview); a new component opens a component request. Both sides link: the library side says "Needed by" the product branch (label needed-by-product), the product branch records it. Needs GITHUB_TOKEN (contents, pull requests and issues: write). dryRun shows what it would open. Only when the person asked.',
+      inputSchema: { pr: Pr, piece: Piece, usePreview: z.boolean().optional().describe("Merge the new library branch into the product branch when it already changes something (default true)."), dryRun: z.boolean().optional() },
+      annotations: WRITE
+    },
+    run((a) => openLibraryBranchOp(ctx, { ...a, source: "mcp" }))
+  );
+  server.registerTool(
+    "bridge_product_branch",
+    {
+      title: "Product branch and its library branches",
+      description: "A product branch as Studio shows it: the summary sentence, each linked library branch with its status and reviewers, what its preview means for the product branch and the next action, and the pieces with no library branch yet.",
+      inputSchema: { pr: Pr },
+      annotations: READ
+    },
+    run((a) => productBranchOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_use_library_preview",
+    {
+      title: "Use a library branch preview in a product branch",
+      description: "The product branch takes the latest commits of the library branch of a piece (Bridge merges it in), so the product preview shows the real library change before it ships. A conflict is left to a developer. Needs GITHUB_TOKEN (contents: write). Only when the person asked.",
+      inputSchema: { pr: Pr, piece: Piece },
+      annotations: WRITE
+    },
+    run((a) => useLibraryPreviewOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_switch_to_published",
+    {
+      title: "Switch a product branch to the published version",
+      description: "Once its library branches shipped, bring main into the product branch (GitHub update branch): it stops carrying the library change and uses the shipped one. Token conflicts go through bridge_update_from_main. Needs GITHUB_TOKEN (contents and pull requests: write). Only when the person asked.",
+      inputSchema: { pr: Pr },
+      annotations: WRITE
+    },
+    run((a) => switchToPublishedOp(ctx, a))
+  );
   server.registerTool(
     "bridge_list_products",
     {
@@ -10406,8 +11261,8 @@ function createServer(ctx) {
     new ResourceTemplate("bridge://components/{name}", {
       list: async () => {
         const { config } = await ctx.config();
-        const names2 = await listComponentNames(ctx.source, config);
-        return { resources: names2.map((n) => ({ uri: `bridge://components/${n.name}`, name: n.name, mimeType: "application/json" })) };
+        const names3 = await listComponentNames(ctx.source, config);
+        return { resources: names3.map((n) => ({ uri: `bridge://components/${n.name}`, name: n.name, mimeType: "application/json" })) };
       },
       complete: {
         name: async (value) => {
@@ -10595,6 +11450,7 @@ export {
   requests_exports,
   drafts_exports,
   studio_exports,
+  pieces_exports,
   VERSION,
   createServer,
   serveStdio,