@bridge-ds/mcp 0.5.0 → 0.7.0

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

@@ -14,16 +14,19 @@ import {
   __export,
   aliasOf,
   approverEntries,
+  approverLists,
   assertSafeBranch,
   baseBranchOf,
   branchExists,
   canShip,
   changeTable,
+  changesMode,
   checkLayeredPair,
   classifyLayered,
   classifyRisk,
   comboKey,
   commitToNewLocalBranch,
+  commitTree,
   composeProposalBody,
   contrastDelta,
   contrastDeltaTable,
@@ -71,8 +74,9 @@ import {
   unreadableShipTeams,
   unreadableTeams,
   validateLayered,
+  variantKeyOf,
   whoCanShipSentence
-} from "./chunk-QTO4EP6V.js";
+} from "./chunk-BZ3KXXMM.js";
 
 // src/lib.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -102,11 +106,11 @@ function parseJson(text) {
   const skipWs = () => {
     while (i < n && isWs(text[i])) i++;
   };
-  const fail2 = (msg) => {
+  const fail3 = (msg) => {
     throw new JsonParseError(`${msg} at offset ${i}`, i);
   };
   const parseString = () => {
-    if (text[i] !== '"') fail2("Expected string");
+    if (text[i] !== '"') fail3("Expected string");
     const start = i;
     i++;
     while (i < n) {
@@ -121,7 +125,7 @@ function parseJson(text) {
       }
       i++;
     }
-    return fail2("Unterminated string");
+    return fail3("Unterminated string");
   };
   const parseValue = () => {
     skipWs();
@@ -139,7 +143,7 @@ function parseJson(text) {
           skipWs();
           const key = parseString();
           skipWs();
-          if (text[i] !== ":") fail2('Expected ":"');
+          if (text[i] !== ":") fail3('Expected ":"');
           i++;
           const value = parseValue();
           entries.push({ key, value });
@@ -152,7 +156,7 @@ function parseJson(text) {
             i++;
             break;
           }
-          fail2('Expected "," or "}"');
+          fail3('Expected "," or "}"');
         }
       }
       const raw = text.slice(start, i);
@@ -175,7 +179,7 @@ function parseJson(text) {
             i++;
             break;
           }
-          fail2('Expected "," or "]"');
+          fail3('Expected "," or "]"');
         }
       }
       const raw = text.slice(start, i);
@@ -194,7 +198,7 @@ function parseJson(text) {
       node = { kind: "null", value: null, raw: "null" };
     } else {
       const m = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(i, i + 64));
-      if (!m) return fail2("Unexpected token");
+      if (!m) return fail3("Unexpected token");
       i += m[0].length;
       node = { kind: "number", value: Number(m[0]), raw: m[0] };
     }
@@ -210,7 +214,7 @@ function parseJson(text) {
   const root = parseValue();
   const trailingStart = i;
   skipWs();
-  if (i < n) fail2("Unexpected content after JSON value");
+  if (i < n) fail3("Unexpected content after JSON value");
   const trailing = text.slice(trailingStart);
   return { root, leading, trailing, style: detectStyle(text, root) };
 }
@@ -956,8 +960,8 @@ function encodePicks(picks) {
 var RISK_TIER = RISK_LABELS[3];
 function slugify(text, max = 40) {
   const s = text.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  const cut = s.length <= max ? s : s.slice(0, max + 1).replace(/-[^-]*$/, "");
-  return cut.replace(/-+$/g, "") || "update";
+  const cut2 = s.length <= max ? s : s.slice(0, max + 1).replace(/-[^-]*$/, "");
+  return cut2.replace(/-+$/g, "") || "update";
 }
 
 // ../core/src/changeset.ts
@@ -1571,10 +1575,16 @@ var GitHubClient = class _GitHubClient {
   async addComment(issueNumber, body) {
     await this.request("POST", `${this.repoPath}/issues/${issueNumber}/comments`, { body });
   }
-  /** Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early). */
+  /**
+   * Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early).
+   * `authorAssociation` is GitHub's OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE... (suggestion approvals read it).
+   */
   async listIssueComments(issueNumber) {
-    const r = await this.request("GET", `${this.repoPath}/issues/${issueNumber}/comments?per_page=100`);
-    return r.map((c) => ({ id: c.id, body: c.body ?? "", author: c.user?.login ?? "unknown", updatedAt: c.updated_at }));
+    const r = await this.request(
+      "GET",
+      `${this.repoPath}/issues/${issueNumber}/comments?per_page=100`
+    );
+    return r.map((c) => ({ id: c.id, body: c.body ?? "", author: c.user?.login ?? "unknown", updatedAt: c.updated_at, createdAt: c.created_at ?? c.updated_at, authorAssociation: c.author_association ?? "NONE" }));
   }
   // --- Issues (component change requests) ---------------------------------------------------
   async createIssue(input) {
@@ -2498,7 +2508,7 @@ function finishPlan(p) {
   const prBody = composeProposalBody({ summary: p.summary, changes, contrast, impact, tier, validationErrors: newErrors.length, tool: p.tool ?? "Bridge", ...p.author ? { author: p.author } : {} });
   const changeset = config.changesets ? { path: `${config.changesets.dir.replace(/\/$/, "")}/bridge-${slugify(p.title, 48) || p.kind}.md`, content: formatChangeset(config.changesets.package, tier.bump, p.title.replace(/\.?$/, ".")) } : void 0;
   const files = [...result.touched.map((f) => ({ path: current.repoPath(f), content: result.files.get(f) })), ...changeset ? [changeset] : []];
-  const commitMessage = `${p.kind === "revert" ? "revert(tokens)" : "fix(tokens)"}: ${p.title.replace(/^Revert: /, "")}
+  const commitMessage2 = `${p.kind === "revert" ? "revert(tokens)" : "fix(tokens)"}: ${p.title.replace(/^Revert: /, "")}
 
 ${p.source?.pr ? `Reverts #${p.source.pr.number}. ` : ""}Tier ${tier.tier}. Planned with ${p.tool ?? "Bridge"}.`;
   const blocked = newErrors.length || newFailures.length;
@@ -2513,7 +2523,7 @@ ${p.source?.pr ? `Reverts #${p.source.pr.number}. ` : ""}Tier ${tier.tier}. Plan
     tier,
     files,
     ...changeset ? { changeset } : {},
-    commitMessage,
+    commitMessage: commitMessage2,
     prBody,
     notes
   };
@@ -2741,7 +2751,7 @@ function toOklch(rgb) {
   return { L, C, h };
 }
 var isHex = (s) => typeof s === "string" && /^#[0-9a-f]{6}$/i.test(s.trim());
-var fromHex = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+var fromHex = (hex2) => [1, 3, 5].map((i) => parseInt(hex2.slice(i, i + 2), 16) / 255);
 var round3 = (x) => Math.round(x * 1e3) / 1e3;
 var toHex = (rgb) => "#" + rgb.map((x) => Math.round(x * 255).toString(16).padStart(2, "0")).join("");
 function dtcgColor(rgb, alpha) {
@@ -2763,20 +2773,20 @@ function nearestStep(rgb) {
   for (const s of STEPS) if (Math.abs(LIGHTNESS[s] - L) < Math.abs(LIGHTNESS[best] - L)) best = s;
   return best;
 }
-function anchoredRamp(hex, pinStep) {
-  const rgb = fromHex(hex);
+function anchoredRamp(hex2, pinStep) {
+  const rgb = fromHex(hex2);
   const { L, C, h } = toOklch(rgb);
   const step = pinStep ?? nearestStep(rgb);
   const peak = Math.min(0.24, Math.max(0.02, C / BELL[step]));
-  return { hue: h, peak, step, distance: Math.abs(L - LIGHTNESS[step]), ramp: generateRamp({ hue: h, chroma: bellChroma(peak), pins: { [step]: hex.toUpperCase() } }) };
+  return { hue: h, peak, step, distance: Math.abs(L - LIGHTNESS[step]), ramp: generateRamp({ hue: h, chroma: bellChroma(peak), pins: { [step]: hex2.toUpperCase() } }) };
 }
 function neutralOffset() {
   const off = {};
-  for (const [s, hex] of Object.entries(NEUTRAL_ANCHORS)) off[s] = toOklch(fromHex(hex)).L - LIGHTNESS[s];
+  for (const [s, hex2] of Object.entries(NEUTRAL_ANCHORS)) off[s] = toOklch(fromHex(hex2)).L - LIGHTNESS[s];
   return (s) => off[s] ?? 0;
 }
-function tintedNeutral(hex) {
-  const rgb = fromHex(hex);
+function tintedNeutral(hex2) {
+  const rgb = fromHex(hex2);
   const { C, h } = toOklch(rgb);
   const ref = neutralChroma()(nearestStep(rgb));
   const scale = C < 4e-3 ? 0 : Math.min(2.5, C / ref);
@@ -2850,19 +2860,19 @@ function rampFor(input, pinStep, kind) {
     const ramp = kind === "neutral" ? generateRamp({ hue: hue2, chroma: neutralChroma(), offset: neutralOffset() }) : generateRamp({ hue: hue2, chroma: bellChroma(DEFAULT_PRIMARY_CHROMA) });
     return { ramp, anchor: `OKLCH hue ${Math.round(hue2)}` };
   }
-  const hex = String(input).trim();
-  if (!isHex(hex)) throw new Error(`"${hex}" is not a color. Use #rrggbb or a hue in degrees (0 to 360).`);
+  const hex2 = String(input).trim();
+  if (!isHex(hex2)) throw new Error(`"${hex2}" is not a color. Use #rrggbb or a hue in degrees (0 to 360).`);
   if (kind === "neutral") {
-    const n = tintedNeutral(hex);
-    return { ramp: n.ramp, anchor: `${hex.toUpperCase()} (hue ${Math.round(n.hue)})` };
+    const n = tintedNeutral(hex2);
+    return { ramp: n.ramp, anchor: `${hex2.toUpperCase()} (hue ${Math.round(n.hue)})` };
   }
-  const a = anchoredRamp(hex, pinStep);
+  const a = anchoredRamp(hex2, pinStep);
   const issue = a.distance > PIN_TOLERANCE ? {
     level: "warning",
     code: "pin-off-ladder",
-    message: `${hex.toUpperCase()} is ${a.distance > 0.12 ? "much " : ""}${toOklch(fromHex(hex)).L > LIGHTNESS[a.step] ? "lighter" : "darker"} than the ${a.step} step it is pinned to, so the ramp around it will not read as one family. Primary actions use this step: pick a ${a.step >= 600 ? "deeper" : "lighter"} color.`
+    message: `${hex2.toUpperCase()} is ${a.distance > 0.12 ? "much " : ""}${toOklch(fromHex(hex2)).L > LIGHTNESS[a.step] ? "lighter" : "darker"} than the ${a.step} step it is pinned to, so the ramp around it will not read as one family. Primary actions use this step: pick a ${a.step >= 600 ? "deeper" : "lighter"} color.`
   } : void 0;
-  return { ramp: a.ramp, anchor: `${hex.toUpperCase()} pinned at ${a.step}`, ...issue ? { issue } : {} };
+  return { ramp: a.ramp, anchor: `${hex2.toUpperCase()} pinned at ${a.step}`, ...issue ? { issue } : {} };
 }
 function aliasRamp(doc, role, ramp, description) {
   const group = getAt(doc, `palette.${role}`);
@@ -3401,14 +3411,30 @@ function patchDocsJson(original, next) {
 function cleanDraftText(text) {
   return text.replace(/\s*\u2014\s*/g, ", ").replace(/,\s*,/g, ",").replace(/^,\s*/, "").replace(/[ \t]+/g, " ").trim();
 }
+var andList = (xs) => xs.length <= 1 ? xs[0] ?? "" : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`;
 var capital = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+var VARIANT_FIRST = ["variant", "tone", "intent", "appearance", "kind", "type", "style"];
+function shortVariant(key) {
+  const pairs = key.split(", ").map((p) => {
+    const at = p.indexOf("=");
+    return at < 0 ? { k: "", v: p.trim() } : { k: p.slice(0, at).trim(), v: p.slice(at + 1).trim() };
+  });
+  const kept = pairs.filter((p) => p.v && !/^default$/i.test(p.v));
+  if (!kept.length) return key;
+  const rank2 = (k) => {
+    const i = VARIANT_FIRST.indexOf(k.toLowerCase());
+    return i < 0 ? VARIANT_FIRST.length : i;
+  };
+  return kept.map((p, i) => ({ ...p, i })).sort((a, b) => rank2(a.k) - rank2(b.k) || a.i - b.i).map((p) => p.v).join(" ");
+}
+var shortVariants = (list) => list ? andList(list.split("; ").map(shortVariant)) : "every variant";
 var DRAFT_LINE_MAX = 120;
 function clipText(text, max) {
   const t = text.replace(/\s+/g, " ").trim().replace(/\.$/, "");
   if (t.length <= max) return t;
-  const cut = t.slice(0, max + 1);
-  const at = cut.lastIndexOf(" ");
-  return (at > max * 0.5 ? cut.slice(0, at) : t.slice(0, max)).replace(/[\s,;:(]+$/, "");
+  const cut2 = t.slice(0, max + 1);
+  const at = cut2.lastIndexOf(" ");
+  return (at > max * 0.5 ? cut2.slice(0, at) : t.slice(0, max)).replace(/[\s,;:(]+$/, "");
 }
 function sanitizeDraftLine(raw) {
   if (typeof raw !== "string") return "";
@@ -3445,8 +3471,8 @@ function validateDocsTask(x) {
 }
 var docsTaskKeys = (t) => t.kind === "sections" ? t.keys : [t.key];
 function parseDocsReply(text) {
-  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
-  const body = fenced ? fenced[1] : text;
+  const fenced2 = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+  const body = fenced2 ? fenced2[1] : text;
   const start = body.indexOf("{");
   const end = body.lastIndexOf("}");
   if (start < 0 || end <= start) throw new Error("The reply holds no JSON object.");
@@ -3769,6 +3795,16 @@ function parseRequestIssue(body) {
     return void 0;
   }
 }
+function declineReasonProblems(reason) {
+  const r = reason.trim();
+  if (!r) return ["Say why, in one or two sentences: the requester reads it."];
+  if (r.length < 10) return ["Say a bit more, so the requester knows why: at least 10 characters."];
+  return [];
+}
+function declineComment(reason, by) {
+  const quote2 = reason.trim().split("\n").map((l) => `> ${l}`.trimEnd()).join("\n");
+  return [`Declined${by ? ` by @${by.replace(/^@/, "")}` : ""} in Bridge Studio.`, "", quote2, "", "<sub>Closed as not planned. Reopen the issue if things change.</sub>"].join("\n");
+}
 function requestStatus(issue) {
   const prs = issue.linkedPrs ?? [];
   if (issue.state === "open") return prs.some((p) => p.state === "open") ? "in-progress" : "requested";
@@ -3905,9 +3941,9 @@ function serializePendingDrafts(p) {
 function clip(text, max) {
   const t = text.replace(/\s+/g, " ").trim().replace(/\.$/, "");
   if (t.length <= max) return t;
-  const cut = t.slice(0, max + 1);
-  const at = cut.lastIndexOf(" ");
-  return (at > max * 0.5 ? cut.slice(0, at) : t.slice(0, max)).replace(/[\s,;:]+$/, "");
+  const cut2 = t.slice(0, max + 1);
+  const at = cut2.lastIndexOf(" ");
+  return (at > max * 0.5 ? cut2.slice(0, at) : t.slice(0, max)).replace(/[\s,;:]+$/, "");
 }
 function sentences(text) {
   const t = text.replace(/\s+/g, " ").trim();
@@ -3985,13 +4021,13 @@ function draftItemBrief(i) {
     return [`Item ${i.id}: component docs${i.component ? ` of ${i.component}` : ""} from Bridge Studio (${i.docs.path ?? i.docs.slug}): ${what}.`, "", i.docs.prompt].join("\n");
   }
   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 cell4 = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
   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) lines2.push("", "| What | Now | In Figma |", "| --- | --- | --- |", ...i.changes.map((c) => `| ${cell4(c.field)} | ${cell4(c.before) || "none"} | ${cell4(c.after) || "removed"} |`));
+  if (i.variables?.length) lines2.push("", "| Token | Now | In Figma |", "| --- | --- | --- |", ...i.variables.map((v) => `| ${cell4(v.path)} | ${cell4(v.before) || "none"} | ${cell4(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());
@@ -4157,6 +4193,14 @@ async function closeExplorationOnGitHub(gh, ref) {
   return { number: p.number, url: p.url, branch: p.headRef };
 }
 
+// ../core/src/requests-github.ts
+async function declineRequestOnGitHub(gh, n, reason, by) {
+  const problems = declineReasonProblems(reason);
+  if (problems.length) throw new GitHubError(422, problems.join(" "));
+  await gh.addComment(n, declineComment(reason, by));
+  await gh.updateIssue(n, { state: "closed", state_reason: "not_planned" });
+}
+
 // ../core/src/review-gate.ts
 function parseTier(labels, body) {
   const found = [];
@@ -4614,309 +4658,325 @@ function branchWithJiraKey(branch, key) {
   return i < 0 ? `${key}-${branch}` : `${branch.slice(0, i + 1)}${key}-${branch.slice(i + 1)}`;
 }
 
-// ../core/src/docs-proposal.ts
-var DOCS_EDITOR_ORIGIN = {
-  where: "in the Bridge docs editor",
-  footer: "Written by a person in the Bridge docs editor. No AI involved in this text.",
-  label: "source: bridge-web"
-};
-var DOCS_MCP_ORIGIN = {
-  where: "with Claude through the Bridge MCP server",
-  footer: 'Proposed with the Bridge MCP server on behalf of a person. Docs Claude drafted say "draftedBy": "claude" until a reviewer accepts them.',
-  label: "source: mcp"
-};
-var EM_DASH = /\u2014/;
-function validateDocs(d) {
-  const out = [];
-  if (!d.summary.trim()) out.push({ field: "summary", message: "Add a summary: one or two sentences on what it is for." });
-  const lists = ["whenToUse", "whenNotToUse", "accessibility", "contentGuidelines"];
-  for (const k of lists) (d[k] ?? []).forEach((x, i) => !x.trim() && out.push({ field: `${k}.${i}`, message: "Fill or remove the empty item." }));
-  for (const k of ["dos", "donts"]) d[k].forEach((g, i) => (!g.title.trim() || !g.text.trim()) && out.push({ field: `${k}.${i}`, message: "Give every item a title and a sentence." }));
-  const prose = JSON.stringify([d.summary, d.whenToUse, d.whenNotToUse, d.dos, d.donts, d.accessibility, d.contentGuidelines ?? [], d.anatomy ?? {}]);
-  if (EM_DASH.test(prose)) out.push({ field: "voice", message: "Replace the em dashes with a colon, a comma or two sentences." });
-  return out;
+// ../core/src/suggestion-review.ts
+var SUGGESTION_REVIEW_MARK = "bridge-suggestion-review";
+var SUGGESTION_APPLIED_MARK = "bridge-suggestion-applied";
+var EVENTS = ["approve", "request-changes", "comment"];
+var ROLE_TEXT = { design: "for design", tech: "for tech", approval: "" };
+function composeSuggestionReviewComment(r) {
+  const who = r.by ? ` by @${r.by.replace(/^@/, "")}` : "";
+  const role = r.role ? ROLE_TEXT[r.role] : "";
+  const head = r.event === "approve" ? `Approved${role ? ` ${role}` : ""}${who} in Bridge.` : r.event === "request-changes" ? `Changes requested${who} in Bridge.` : `Comment${who} in Bridge.`;
+  const quote2 = r.message?.trim() ? r.message.trim().split("\n").map((l) => `> ${l}`.trimEnd()).join("\n") : "";
+  const record = { event: r.event, ...r.role ? { role: r.role } : {}, payloadSha: r.payloadSha, at: r.at };
+  return [head, ...quote2 ? ["", quote2] : [], "", `<sub>Applies to version \`${r.payloadSha.slice(0, 7)}\` of this suggestion.</sub>`, "", `<!-- ${SUGGESTION_REVIEW_MARK} ${JSON.stringify(record)} -->`].join("\n");
+}
+function parseSuggestionReviewComment(body) {
+  const m = new RegExp(`<!-- ${SUGGESTION_REVIEW_MARK} (\\{[^\\n]*?\\}) -->`).exec(body ?? "");
+  if (!m) return null;
+  try {
+    const r = JSON.parse(m[1]);
+    if (!r || !EVENTS.includes(r.event) || typeof r.payloadSha !== "string" || !/^[0-9a-f]{64}$/.test(r.payloadSha)) return null;
+    return {
+      event: r.event,
+      ...r.role === "design" || r.role === "tech" || r.role === "approval" ? { role: r.role } : {},
+      payloadSha: r.payloadSha,
+      at: typeof r.at === "string" ? r.at : ""
+    };
+  } catch {
+    return null;
+  }
 }
-function cleanDocs(d) {
-  const list = (xs) => (xs ?? []).map((x) => x.trim()).filter(Boolean);
-  const guide = (xs) => xs.map((g) => ({ ...g, title: g.title.trim(), text: g.text.trim() })).filter((g) => g.title || g.text);
-  return {
-    ...d,
-    summary: d.summary.trim(),
-    whenToUse: list(d.whenToUse),
-    whenNotToUse: list(d.whenNotToUse),
-    dos: guide(d.dos),
-    donts: guide(d.donts),
-    accessibility: list(d.accessibility),
-    contentGuidelines: list(d.contentGuidelines),
-    anatomy: Object.fromEntries(Object.entries(d.anatomy ?? {}).filter(([k, v]) => k.trim() && v.trim()))
-  };
+function composeSuggestionAppliedComment(r) {
+  const where2 = r.pr ? `in pull request #${r.pr}` : r.branch ? `on \`${r.branch}\`` : r.commit ? `in commit ${r.commit.slice(0, 7)}` : "locally";
+  const record = Object.fromEntries(Object.entries(r).filter(([, v]) => v !== void 0));
+  return [
+    `Being applied ${where2}${r.by ? ` by @${r.by.replace(/^@/, "")}` : ""}.${r.forced ? " Applied before every approval was in." : ""}`,
+    "",
+    `<!-- ${SUGGESTION_APPLIED_MARK} ${JSON.stringify(record)} -->`
+  ].join("\n");
 }
-var docsFileText = (d, original) => patchDocsJson(original, cleanDocs(d));
-var slugDate = (d) => d.toISOString().slice(0, 10).replace(/-/g, "");
-var docsSlug = (nameOrSlug) => nameOrSlug.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9-]+/g, "-").slice(0, 40);
-function defaultDocsFooter(edits, origin) {
-  if (origin.label !== DOCS_EDITOR_ORIGIN.label) return origin.footer;
-  const claude = edits.some((e) => {
-    try {
-      return JSON.parse(e.after).draftedBy === "claude";
-    } catch {
-      return false;
+function parseSuggestionAppliedComment(body) {
+  const m = new RegExp(`<!-- ${SUGGESTION_APPLIED_MARK} (\\{[^\\n]*?\\}) -->`).exec(body ?? "");
+  if (!m) return null;
+  try {
+    const r = JSON.parse(m[1]);
+    return r && typeof r.payloadSha === "string" ? { ...r, payloadSha: r.payloadSha, at: typeof r.at === "string" ? r.at : "" } : null;
+  } catch {
+    return null;
+  }
+}
+var norm2 = (l) => l.trim().replace(/^@/, "").toLowerCase();
+var COLLABORATOR = ["OWNER", "MEMBER", "COLLABORATOR"];
+function summarizeSuggestionApprovals(comments, gov, opts) {
+  const lists = approverLists(gov.owners, gov.rights ?? null, gov.teams);
+  const owners = new Set([...lists.design, ...lists.tech].map(norm2));
+  const anyOwner = owners.size > 0;
+  const reviews = [];
+  const latestOld = /* @__PURE__ */ new Map();
+  const ignored = /* @__PURE__ */ new Set();
+  const ordered2 = comments.map((c, i) => ({ c, i })).sort((a, b) => String(a.c.createdAt ?? "").localeCompare(String(b.c.createdAt ?? "")) || a.i - b.i);
+  ordered2.forEach(({ c }, i) => {
+    const r = parseSuggestionReviewComment(c.body);
+    if (!r || r.event === "comment" || !c.author) return;
+    const login = norm2(c.author);
+    if (opts.author && login === norm2(opts.author)) return;
+    const counts = anyOwner ? owners.has(login) : COLLABORATOR.includes((c.authorAssociation ?? "").toUpperCase());
+    if (!counts) {
+      ignored.add(c.author);
+      return;
+    }
+    const at = String(i).padStart(6, "0");
+    if (r.payloadSha !== opts.payloadSha) {
+      latestOld.set(c.author, r.event);
+      reviews.push({ user: { login: c.author }, state: "DISMISSED", submitted_at: at });
+      return;
     }
+    latestOld.delete(c.author);
+    reviews.push({ user: { login: c.author }, state: r.event === "approve" ? "APPROVED" : "CHANGES_REQUESTED", submitted_at: at });
   });
-  return claude ? `Drafted by Claude AI (the docs say "draftedBy": "claude"), sent by a person ${origin.where}.` : origin.footer;
+  const summary2 = summarizeApprovals(reviews, lists, opts.author ?? void 0);
+  const stale = [...latestOld.keys()].filter((l) => !summary2.approvers.includes(l) && !summary2.changesRequested.includes(l));
+  return { ...summary2, stale, ignored: [...ignored].filter((l) => !summary2.approvers.includes(l)) };
+}
+function suggestionReviewState(tier, approvals) {
+  if (approvals.changesRequested.length) return "changes-requested";
+  return pendingApprovals(tier, approvals).length ? "needs-review" : "approved";
 }
-function withAuthorLine(body, line) {
-  const i = body.lastIndexOf("\n---\n");
-  return i < 0 ? `${body.trimEnd()}
 
----
-${line}` : `${body.slice(0, i + 5)}${line}`;
+// ../core/src/figma-push.ts
+var where = (r) => r.allVariants ? "every variant" : shortVariants(r.variants.join("; "));
+var cap = (s) => s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+function planComponentPush(d, ctx) {
+  const issues = [...d.unknown];
+  const reasons = [];
+  const edits = /* @__PURE__ */ new Map();
+  const also = /* @__PURE__ */ new Set();
+  for (const r of d.rebinds) {
+    const label = `${cap(r.kind)} in ${where(r)}`;
+    if (!r.after.length) {
+      issues.push({ what: `${label} is no longer bound to a variable: it uses a raw value.`, todo: "Bind it to a variable, or create the variable and push it with the variables, then push again." });
+      continue;
+    }
+    const missing = r.after.filter((p) => !ctx.tierOf(p));
+    if (missing.length) {
+      issues.push({ what: `${label} uses ${missing.join(", ")}, a variable the library does not have yet.`, todo: "Push the variable first (Variables, above), then push this component again." });
+      continue;
+    }
+    if (!r.before.length) {
+      reasons.push(`${label} is bound to ${r.after.join(", ")} where code paints nothing: Claude AI adds it to the CSS.`);
+      continue;
+    }
+    if (r.before.length !== 1 || r.after.length !== 1) {
+      reasons.push(`${label} moved from ${r.before.join(", ")} to ${r.after.join(", ")}: several variables on one property, so Claude AI writes the CSS.`);
+      continue;
+    }
+    const [from, to] = [r.before[0], r.after[0]];
+    if (ctx.tierOf(from) !== "component") {
+      reasons.push(`Code paints ${r.kind} with ${from} directly, not through a ${d.component} token: Claude AI changes the CSS to ${to}.`);
+      continue;
+    }
+    const elsewhere = ctx.usedElsewhere(from, r);
+    if (elsewhere.variants.length) {
+      const v = elsewhere.variants;
+      const list2 = v.length > 3 ? `${shortVariants(v.slice(0, 3).join("; ")).replace(/ and /, ", ")} and ${v.length - 3} more` : shortVariants(v.join("; "));
+      reasons.push(`${from} also paints ${list2}: pointing it to ${to} would change them too, so Claude AI adds a token for ${where(r)}.`);
+      continue;
+    }
+    for (const c of elsewhere.components) also.add(c);
+    const prev = edits.get(from);
+    if (prev && prev.value !== `{${to}}`) {
+      reasons.push(`${from} moved to two different variables (${String(prev.value).slice(1, -1)} and ${to}): Claude AI splits it.`);
+      edits.delete(from);
+      continue;
+    }
+    edits.set(from, { op: "set", path: from, value: `{${to}}` });
+  }
+  const list = [...edits.values()];
+  if (d.needsCode || reasons.length) {
+    return {
+      route: "claude-draft",
+      said: `Claude AI drafts the code from what you changed, then a person reviews it.${list.length ? ` ${list.length === 1 ? "Its token swap goes" : "Its token swaps go"} with it.` : ""}`,
+      edits: list,
+      reasons,
+      issues,
+      alsoChanges: [...also]
+    };
+  }
+  if (list.length) {
+    const n = list.length;
+    const others = [...also];
+    const names3 = others.length > 3 ? [...others.slice(0, 3), `${others.length - 3} more`] : others;
+    const alsoLine = names3.length ? ` It also repaints ${names3.length > 1 ? `${names3.slice(0, -1).join(", ")} and ${names3[names3.length - 1]}` : names3[0]}: they use the same token${n === 1 ? "" : "s"}.` : "";
+    return { route: "token-change", said: `Exact, no AI: ${n === 1 ? `${list[0].path} points` : `${n} ${d.component} tokens point`} to the new variable${n === 1 ? "" : "s"}, checked for contrast and reviewed like any token change.${alsoLine}`, edits: list, reasons, issues, alsoChanges: others };
+  }
+  return { route: "manual", said: issues.length ? "Fix it in Figma first: nothing is sent until Bridge can read it." : "Nothing to send.", edits: [], reasons, issues, alsoChanges: [] };
+}
+function specsUsage(specs, component) {
+  const own = specs.components.find((x) => x.name === component) ?? specs.components.find((x) => x.component === component);
+  return (path, r) => {
+    const variants = [];
+    const components = [];
+    for (const c of specs.components) {
+      for (const v of c.variants) {
+        if (!Object.values(v.values).some((fields) => Object.values(fields ?? {}).includes(path))) continue;
+        const key = variantKeyOf(v.props);
+        if (c === own) {
+          if (!r.variants.includes(key)) variants.push(key);
+        } else if (!components.includes(c.name)) components.push(c.name);
+      }
+    }
+    return { variants, components };
+  };
 }
-var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-function isDocsProposalBranch(branch, component) {
-  const slugs = /* @__PURE__ */ new Set([docsSlug(component.slug ?? component.name), docsSlug(component.name), docsSlug(component.name.toLowerCase())]);
-  return [...slugs].some((s) => new RegExp(`^docs/(?:[A-Z][A-Z0-9]*-\\d+-)?${escapeRe(s)}-\\d{8}-[a-z0-9]+$`).test(branch));
+function componentContrastPairs(edits, pairs, tokens) {
+  const out = /* @__PURE__ */ new Map();
+  for (const e of edits) {
+    const target = tokens.aliasOf(e.path);
+    if (!target) continue;
+    const group = e.path.split(".")[0];
+    const sibling = (other) => tokens.paths.find((p) => p !== e.path && p.split(".")[0] === group && tokens.aliasOf(p) === other) ?? other;
+    for (const p of pairs) {
+      if (p.foreground === target) out.set(`${e.path}|${sibling(p.background)}`, { ...p, foreground: e.path, background: sibling(p.background) });
+      if (p.background === target) out.set(`${sibling(p.foreground)}|${e.path}`, { ...p, foreground: sibling(p.foreground), background: e.path });
+    }
+  }
+  return [...out.values()];
 }
-function findOpenDocsProposal(pulls, component, base) {
-  const hit = pulls.filter((p) => p.state === "open" && isDocsProposalBranch(p.headRef, component) && (!base || !p.baseRef || p.baseRef === base)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
-  return hit ? { number: hit.number, url: hit.url, branch: hit.headRef, author: hit.author, title: hit.title, updatedAt: hit.updatedAt } : null;
+var FROM_FIGMA_LABEL = "from-figma";
+var WAITING_FOR_CLAUDE_LABEL = "waiting-for-claude";
+var DRAFTED_BY_CLAUDE_LABEL = "drafted-by-claude";
+var FIGMA_SPEC_DIR = ".bridge/figma";
+var ORIGIN_MARK = "bridge-from-figma";
+var hidden = (data) => `<!-- ${ORIGIN_MARK} ${JSON.stringify(data).replace(/-->/g, "--\\u003e")} -->`;
+function parseFigmaOrigin(body) {
+  if (!body) return void 0;
+  const m = new RegExp(`<!-- ${ORIGIN_MARK} (\\{[\\s\\S]*?\\}) -->`).exec(body);
+  if (!m) return void 0;
+  try {
+    const o = JSON.parse(m[1]);
+    return typeof o.component === "string" && (o.route === "token-change" || o.route === "claude-draft") ? o : void 0;
+  } catch {
+    return void 0;
+  }
 }
-async function findOpenDocsProposalOnGitHub(gh, component, base) {
-  return findOpenDocsProposal(await gh.listPullRequests("open"), component, base);
+function figmaOriginSection(o) {
+  const design = o.url ? `[${o.figmaName}](${o.url})` : `"${o.figmaName}"`;
+  const who = o.requestedBy ? ` by @${o.requestedBy}` : "";
+  const status = o.route === "token-change" ? "Exact token change, no AI: Bridge read the token swap from the Figma component." : o.status === "drafted" ? "**Drafted by Claude AI** from the Figma spec. A person reviews it before it ships." : `**Waiting for Claude AI:** this branch carries the spec only, as a request. Claude writes the code here (\`bridge_get_figma_change\`, or \`bridge figma show <number>\`), then it is labelled ${DRAFTED_BY_CLAUDE_LABEL}.`;
+  return [`**From Figma:** ${design}${who}. Once it ships, a pull in the DS Bridge plugin rebuilds the component from this code.`, "", status, "", hidden(o)].join("\n");
 }
-async function continueDocsProposalOnGitHub(gh, open, edit, opts = {}) {
-  const message = opts.message ?? `docs(${docsSlug(edit.component)}): edit usage guidance in the Bridge docs editor`;
-  const cur = await gh.getFile(edit.path, open.branch);
-  if (cur?.text === edit.after) return "";
-  const sha = await gh.putFile({ path: edit.path, content: edit.after, branch: open.branch, message, sha: cur?.sha });
-  if (opts.authorLine) {
-    const line = opts.authorLine;
-    await gh.getPullRequest(open.number).then((pr) => gh.updatePullRequest(open.number, { body: withAuthorLine(pr.body, line) })).catch(() => void 0);
+function withFigmaOrigin(body, o) {
+  let b = (body ?? "").trim();
+  const at = b.indexOf("**From Figma:**");
+  const mark = b.indexOf(`<!-- ${ORIGIN_MARK} `);
+  if (at >= 0 && mark > at) {
+    const end = b.indexOf("-->", mark);
+    b = `${b.slice(0, at)}${b.slice(end + 3)}`.trim();
   }
-  return sha;
-}
-function docsProposal(edits, opts) {
-  const origin = opts.origin ?? DOCS_EDITOR_ORIGIN;
-  if (!edits.length) throw new Error("No docs edits in the draft.");
-  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";
-  const changeset = `---
-"${pkg}": patch
----
+  return `${figmaOriginSection(o)}${b ? `
 
-Usage guidance for ${list}.
+${b}` : ""}`;
+}
+var figmaSpecSlug = (d) => slugify(`${d.component} ${d.title}`, 48) || "component-change";
+var figmaSpecPath = (d) => `${FIGMA_SPEC_DIR}/${figmaSpecSlug(d)}.json`;
+var kindLabel2 = (k) => REQUEST_KINDS.find((x) => x.value === k)?.label ?? "Change";
+function formatFigmaSpec(d, plan) {
+  return `${JSON.stringify({ ...d, tokenEdits: plan.edits, reasons: plan.reasons, unknown: plan.issues }, null, 2)}
 `;
-  const files = [...edits.map((e) => ({ path: e.path, content: e.after })), { path: csPath, content: changeset }];
-  const risk = classifyRisk({ files: files.map((f) => ({ path: f.path, status: "modified" })) });
-  const rows = edits.map((e) => {
-    let state = "edited";
-    try {
-      const d = JSON.parse(e.after);
-      const gaps = missingProse(d);
-      state = gaps.length ? `still missing: ${gaps.join(", ")}` : "every section filled";
-    } catch {
-      state = "not valid JSON";
-    }
-    return `- \`${e.path}\` (${e.before === null ? "new" : "changed"}, ${state})`;
-  });
-  const body = [
-    `## Docs change`,
+}
+function parseFigmaSpec(text) {
+  if (!text) return void 0;
+  try {
+    const s = JSON.parse(text);
+    return s && s.v === 1 && typeof s.component === "string" && Array.isArray(s.changes) ? s : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function figmaDraftBrief(d, ctx) {
+  const dir = `${(ctx.componentsDir ?? "packages/react/src/components").replace(/\/+$/, "")}/${d.component}`;
+  const suggested = "suggestion" in ctx;
+  const variants = Object.entries(d.variantAxes).map(([axis, values]) => `${axis}: ${values.join(", ")}`);
+  const props = d.properties.filter((p) => p.type !== "VARIANT").map((p) => `${p.name} (${p.type.toLowerCase().replace("_", " ")}, default ${p.default || "empty"})`);
+  return [
+    suggested ? "Draft the code for a component change made in Figma, sent as a Bridge suggestion (this issue)." : `Draft the code for a component change made in Figma, on the library branch ${ctx.branch} (draft pull request #${ctx.pr}).`,
     "",
-    `Usage guidance for ${list}, written ${origin.where}.`,
+    d.coded ? `Component: ${d.component} (${dir})` : `New component: ${d.component} (create ${dir})`,
+    `Kind: ${kindLabel2(d.kind)}`,
+    `Change: ${d.title}`,
+    ...d.line?.trim() ? [`What changes: ${d.line.trim()}`] : [],
     "",
-    ...rows,
+    d.summary.trim(),
     "",
-    `**Risk:** ${risk.label}. Docs only: the published components do not change. Changeset: patch.`,
+    ...d.changes.length ? ["Changes in Figma:", ...d.changes.map((c) => `- ${c.field}: ${c.before ?? "(none)"} -> ${c.after ?? "(removed)"}`), ""] : [],
+    ...variants.length ? ["Variant matrix in Figma:", ...variants.map((v) => `- ${v}`), ""] : [],
+    ...props.length ? ["Properties in Figma:", ...props.map((p) => `- ${p}`), ""] : [],
+    ...d.tokenEdits?.length ? ["Token swaps to make too (exact, with bridge_propose_token_change on this branch or by hand in the token files):", ...d.tokenEdits.map((e) => `- ${e.path} -> ${String(e.value)}`), ""] : [],
+    ...d.reasons?.length ? ["Why this needs code:", ...d.reasons.map((r) => `- ${r}`), ""] : [],
+    `Spec: ${ctx.specPath} ${suggested ? "in the suggestion" : "on the branch"} has the bound variables of every variant (token paths), the layers of every variant and what code gave Figma before.`,
+    ...d.figma?.url ? [`Design: ${d.figma.url}`] : [],
+    ...d.images?.length ? ["Screenshot:", ...d.images.map((u) => `- ${u}`)] : [],
     "",
-    opts.notes?.trim() ? `## Notes
-
-${opts.notes.trim()}
-` : "",
-    "---",
-    opts.authorLine?.trim() || defaultDocsFooter(edits, origin)
-  ].filter((x, i, a) => !(x === "" && a[i - 1] === "")).join("\n");
-  return { branch, title, body, files, risk, bump: "patch", labels: ["docs", origin.label, `tier-${risk.tier}`] };
+    "Steps:",
+    "suggestion" in ctx ? "1. Apply the suggestion on a new branch: bridge apply <this issue number> (it writes the spec file), or start a branch from the default branch." : `1. git fetch origin && git checkout ${ctx.branch}`,
+    `2. Write the change in ${dir}: the TSX on Base UI, the CSS module with tokens only (the bound variables of the spec, as token paths), the stories (examples), docs.json and a changeset. Follow ${ctx.agentsFile ?? "AGENTS.md"}.`,
+    "3. Run npm run specs so component-specs.json matches the code, then npm test.",
+    "suggestion" in ctx ? '4. Commit, push and open a pull request that says "Closes #<this issue number>", so the suggestion closes when it ships. A person reviews it.' : `4. Commit and push to ${ctx.branch}, then call bridge_mark_figma_change_drafted { pr: ${ctx.pr} } (CLI: bridge figma drafted ${ctx.pr}). The branch is then labelled ${DRAFTED_BY_CLAUDE_LABEL} and a person reviews it.`,
+    "",
+    "Rules:",
+    "- Never invent a token or a value: use the variables the spec lists. A value the library lacks is a token change, said in the pull request.",
+    "- Keep every existing variant and prop unchanged unless the spec changes it.",
+    `- If the spec is unclear, comment on the ${suggested ? "suggestion" : "pull request"} instead of guessing.`
+  ].join("\n");
 }
-async function proposeDocsOnGitHub(gh, edits, opts) {
-  if (opts.continueOpen !== false && edits.length === 1) {
-    const e = edits[0];
-    const open = await findOpenDocsProposalOnGitHub(gh, { name: e.component, slug: e.slug }, opts.base).catch(() => null);
-    if (open) {
-      const sha = await continueDocsProposalOnGitHub(gh, open, e, { authorLine: opts.authorLine?.trim() || defaultDocsFooter(edits, opts.origin ?? DOCS_EDITOR_ORIGIN) });
-      return { number: open.number, url: open.url, branch: open.branch, title: open.title, continued: true, unchanged: !sha };
-    }
-  }
-  const p = docsProposal(edits, { title: opts.title, notes: opts.notes, date: opts.date ?? /* @__PURE__ */ new Date(), origin: opts.origin, authorLine: opts.authorLine });
-  const prTitle = titleWithJiraKey(p.title, opts.jira ?? null);
-  const branch = branchWithJiraKey(p.branch, opts.jira ?? null);
-  const mainSha = await gh.getBranchSha(opts.base);
-  if (!mainSha) throw new Error(`Branch ${opts.base} not found.`);
-  const tree = await gh.createTree(await gh.getCommitTree(mainSha), p.files.map((f) => ({ path: f.path, content: f.content })));
-  const commit = await gh.createCommit(`${prTitle}
-
-${opts.commitNote ?? "Proposed with the Bridge docs editor."}`, tree, [mainSha]);
-  await gh.createBranch(branch, commit);
-  const pr = await gh.createPullRequest({ title: prTitle, head: branch, base: opts.base, body: p.body, draft: false });
-  await gh.addLabels(pr.number, [...p.labels, ...opts.extraLabels ?? []]).catch(() => false);
-  return { number: pr.number, url: pr.url, branch, title: prTitle, continued: false, unchanged: false };
+function figmaDraftBody(d, plan, o) {
+  const cell4 = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+  const rows = d.changes.length ? ["| What | Code now | In Figma |", "| --- | --- | --- |", ...d.changes.map((c) => `| ${cell4(c.field)} | ${cell4(c.before ?? "")} | ${cell4(c.after ?? "")} |`), ""] : [];
+  return withFigmaOrigin(
+    [
+      `## ${d.coded ? `${kindLabel2(d.kind)} for ${d.component}` : `New component: ${d.component}`}`,
+      "",
+      d.summary.trim(),
+      "",
+      ...d.line?.trim() ? [`**What changes:** ${d.line.trim()}`, ""] : [],
+      ...rows,
+      ...d.images?.length ? [...d.images.map((u, i) => `![${d.component} in Figma ${i + 1}](${u})`), ""] : [],
+      ...plan.edits.length ? ["**Token swaps to make too:**", ...plan.edits.map((e) => `- \`${e.path}\` -> \`${String(e.value)}\``), ""] : [],
+      ...plan.reasons.length ? ["**Why this needs code:**", ...plan.reasons.map((r) => `- ${r}`), ""] : [],
+      ...plan.issues.length ? ["**Left in Figma (the designer fixes these first):**", ...plan.issues.map((i) => `- ${i.what} ${i.todo}`), ""] : [],
+      `**Spec:** \`${o.spec ?? figmaSpecPath(d)}\` (variant matrix, properties, bound variables and layers of every variant).`
+    ].join("\n"),
+    o
+  );
 }
-async function commitFileOnGitHub(gh, input) {
-  const cur = await gh.getFile(input.path, input.branch);
-  if (!cur) throw new Error(`${input.path} is not on ${input.branch}. Check the component name and the branch.`);
-  const content = input.next(cur.text);
-  if (content === cur.text) return "";
-  return gh.putFile({ path: input.path, content, branch: input.branch, message: input.message, sha: cur.sha });
+var figmaBranchTitle = (d) => requestIssueTitle(d);
+function figmaPushStatus(x) {
+  const labels = x.labels ?? [];
+  if (x.state === "merged") return { key: "shipped", label: "Shipped", sentence: "It shipped. Pull to rebuild the component from the reviewed code.", rebuild: true };
+  if (x.state !== "open") return { key: "closed", label: "Closed", sentence: "The library closed it without shipping. Pull to bring the component back to the code.", rebuild: true };
+  if (labels.includes(WAITING_FOR_CLAUDE_LABEL)) return { key: "waiting-for-claude", label: "Waiting for Claude AI", sentence: "The spec is on the library branch. Claude AI writes the code there, then a person reviews it.", rebuild: false };
+  if (labels.includes(DRAFTED_BY_CLAUDE_LABEL)) return { key: "drafted", label: "Drafted by Claude AI", sentence: "Claude AI drafted the code. A person reviews it before it ships.", rebuild: false };
+  return { key: "in-review", label: "In review", sentence: x.route === "token-change" ? "Owners review the token change." : "Owners review it.", rebuild: false };
 }
 
-// ../core/src/share-branch.ts
-var packageDir = (name) => `packages/${name.replace(/^@[^/]+\//, "")}/`;
-function touchesPackages(files, packages) {
-  const dirs = packages.map(packageDir);
-  return files.some((f) => dirs.some((d) => f.startsWith(d)));
-}
-function shareState(x) {
-  if (!touchesPackages(x.files, x.packages)) return { kind: "no-packages" };
-  const c = readPreviewComment(x.comment);
-  if (x.lifecycle === "merged" || x.lifecycle === "closed") {
-    const kind = x.lifecycle === "merged" ? "shipped" : "closed";
-    if (!c || !c.command || c.source === "none") return { kind, stillWorks: null, command: null };
-    return { kind, stillWorks: c.source === "pkg.pr.new" ? true : c.source === "release" ? false : null, command: c.command };
-  }
-  if (!c) return { kind: "building" };
-  if (c.sha7 && !x.headSha.startsWith(c.sha7)) return { kind: "building" };
-  if (!c.command || c.source === "none") return { kind: "failed" };
-  return { kind: "ready", command: c.command, source: c.source };
-}
-var stableCommand = (packages) => `npm i ${packages.map((p) => `${p}@latest`).join(" ")}`;
-function stateSentence(s) {
-  switch (s.kind) {
-    case "ready":
-      return null;
-    case "building":
-      return "The preview version is being prepared. It is usually ready a couple of minutes after each update to the branch.";
-    case "failed":
-      return "The preview version could not be prepared for the latest update. Update the branch to try again, or ask a developer to run it again on GitHub.";
-    case "no-packages":
-      return "This branch does not touch the library tokens or components, so there is no preview version to install.";
-    case "shipped":
-      return s.stillWorks === true ? "This branch was merged. Its preview version still installs, and products get it with the next library release." : s.stillWorks === false ? "This branch was merged, so its preview version was removed. Products get it with the next library release." : "This branch was merged. Products get it with the next library release.";
-    case "closed":
-      return s.stillWorks === true ? "This branch was closed without merging. Its preview version still installs, but it will not reach the library." : s.stillWorks === false ? "This branch was closed without merging, so its preview version was removed." : "This branch was closed without merging.";
-  }
-}
-var quote = (t) => `"${t.trim().replace(/"/g, "'")}"`;
-function shareMessage(x) {
-  const back = stableCommand(x.packages);
-  const s = x.state;
-  if (s.kind === "ready") {
-    const lasts = s.source === "pkg.pr.new" ? "This preview stays available. Each update to the change makes a new one: ask me for the latest command." : "This preview is replaced on each update to the change and removed when it ships or closes: ask me for the latest command if the install fails.";
-    return {
-      subject: `Try the design system change ${quote(x.title)} before it ships`,
-      body: [
-        "Hi,",
-        "",
-        `Could you try the design system change ${quote(x.title)} in our product before it ships?`,
-        ...x.tryUrl ? ["", `See it in the demo product first: ${x.tryUrl}`] : [],
-        "",
-        "Install the preview version in a staging branch (not production):",
-        s.command,
-        "",
-        lasts,
-        "",
-        "To go back to the stable version:",
-        back,
-        "",
-        `Details for developers: ${x.url}`
-      ].join("\n")
-    };
-  }
-  if ((s.kind === "shipped" || s.kind === "closed") && s.command) {
-    const what = s.kind === "shipped" ? `The design system change ${quote(x.title)} has shipped. You get it with the next library release.` : `The design system change ${quote(x.title)} was closed without shipping.`;
-    const preview = s.stillWorks === false ? "Its preview version was removed, so reinstalling it fails." : s.stillWorks === true ? "Its preview version still installs, but it is not the released version." : "";
-    return {
-      subject: `Design system change ${quote(x.title)} ${s.kind === "shipped" ? "has shipped" : "was closed"}`,
-      body: ["Hi,", "", [what, preview].filter(Boolean).join(" "), "", "If you installed its preview, go back to the stable version:", back, "", `Details for developers: ${x.url}`].join("\n")
-    };
-  }
-  return null;
-}
-
-// ../core/src/try-in-product.ts
-function tryInProductUrl(preview, pr, screen) {
-  const url = new URL(preview);
-  url.pathname = "/";
-  url.search = "";
-  url.searchParams.set("bridge", String(pr));
-  if (screen) {
-    url.searchParams.set("tenant", screen.tenant);
-    url.searchParams.set("theme", screen.theme);
-  }
-  url.hash = screen ? screen.route : "";
-  return url.href;
-}
-
-// ../core/src/combine-branches.ts
-var MIN_TOGETHER = 2;
-var MAX_TOGETHER = 4;
-function onlyTokens(files, tokensRoot) {
-  const root = `${tokensRoot.replace(/^\/+|\/+$/g, "")}/`;
-  return files.length > 0 && files.every((f) => f.startsWith(root) && f.endsWith(".tokens.json") || /contrast\.checks\.json$/.test(f) || f.startsWith(".changeset/"));
-}
-function tokenFilesOf(files, tokensRoot) {
-  const root = `${tokensRoot.replace(/^\/+|\/+$/g, "")}/`;
-  return files.filter((f) => f.startsWith(root) && f.endsWith(".tokens.json")).map((f) => f.slice(root.length));
-}
-var changeList = (numbers) => numbers.join(",");
-function tryTogetherUrl(admin, numbers, picks) {
-  const url = new URL(admin);
-  url.pathname = "/";
-  url.hash = "";
-  const use = encodePicks(picks);
-  url.search = `?bridge=${changeList(numbers)}${use ? `&bridge-use=${encodeURIComponent(use)}` : ""}`;
-  return url.href;
-}
-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 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(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]) };
-  await Promise.all(
-    tokenFiles.map(async (f) => {
-      const rel = tokenFilesOf([f.filename], root)[0];
-      source.base[rel] = f.status === "added" ? void 0 : await gh.readFile(f.previous_filename ?? f.filename, start);
-      source.head[rel] = f.status === "removed" ? void 0 : await gh.readFile(f.filename, pull.headSha);
-    })
-  );
-  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;
+// ../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" };
+var KIND_WORD = { "token-change": "token change", exploration: "library exploration", request: "component request", suggestion: "suggested token change" };
 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;
@@ -4926,7 +4986,7 @@ 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."}`;
+    return `- **${p.title}**: ${p.summary}${l ? ` ${cap2(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");
 }
@@ -4969,7 +5029,7 @@ function withNeededBy(body, n) {
 
 ${b}` : ""}`;
 }
-var cap = (s) => s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+var cap2 = (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 = {
@@ -4993,11 +5053,23 @@ function libraryBranchPlan(piece, branch, opts = {}) {
       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." : ""}`,
+      description: `${cap2(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 && opts.mode === "suggest") {
+    const request2 = {
+      component: piece.component,
+      kind: "new-variant",
+      title: piece.title,
+      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: piece.title, request: request2, neededBy };
+  }
   if (piece.kind === "variant" && piece.component) {
     const values = piece.values.map((v) => `${v.property ?? v.category} ${v.value}`).join(", ");
     const exploration = {
@@ -5014,7 +5086,7 @@ function libraryBranchPlan(piece, branch, opts = {}) {
     ].filter(Boolean).join(" ");
     return { kind: "exploration", title: piece.title, exploration, neededBy, brief };
   }
-  const name = piece.component ?? cap(piece.name);
+  const name = piece.component ?? cap2(piece.name);
   const request = {
     component: name,
     kind: "new-component",
@@ -5037,15 +5109,29 @@ var STATUS_LABEL = {
   requested: "Requested",
   "in-progress": "In progress",
   done: "Done",
-  declined: "Declined"
+  declined: "Declined",
+  outdated: "Outdated"
 };
 var names2 = (people2) => people2.length <= 2 ? people2.map((p) => `@${p}`).join(" and ") : `@${people2[0]} and ${people2.length - 1} more`;
+var SUGGESTION_LINK_STATUS = {
+  "needs-review": "in-review",
+  "changes-requested": "changes",
+  approved: "approved",
+  applying: "in-progress",
+  applied: "shipped",
+  declined: "declined",
+  outdated: "outdated"
+};
 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 === "suggestion") {
+    const key = SUGGESTION_LINK_STATUS[x.status];
+    return make(key, key === "in-progress" ? [...x.assignees ?? []] : [], "builds");
+  }
   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");
@@ -5063,6 +5149,11 @@ function linkStatus(x) {
   return make("in-review", waiting);
 }
 function libraryPreviewState(x) {
+  if (x.kind === "suggestion") {
+    if (x.lifecycle === "closed") return { key: "declined", sentence: `The library declined this suggestion.${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 applied the suggestion. Switch your branch to the published version.", action: { kind: "switch", label: "Switch to the published version" } };
+    return { key: "nothing-yet", sentence: "Nothing to preview yet: owners review the suggestion, then a developer applies it. Your branch keeps its own value until then.", action: null };
+  }
   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" } };
@@ -5114,129 +5205,1226 @@ function proposedTokenPath(nearest, name, category) {
   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;
+// ../core/src/suggestions.ts
+var SUGGESTION_SCHEMA = "bridge.suggestion/1";
+var SUGGESTION_LABEL = "bridge-suggestion";
+var SUGGESTION_KINDS = ["token-change", "docs", "component-spec", "brand", "revert", "config"];
+var SUGGESTION_STATE_LABELS = {
+  "needs-review": "suggestion: needs review",
+  "changes-requested": "suggestion: changes requested",
+  approved: "suggestion: approved",
+  applying: "suggestion: applying"
+};
+var SUGGESTION_STATUS_LABEL = {
+  "needs-review": "Needs review",
+  "changes-requested": "Changes requested",
+  approved: "Approved, ready to apply",
+  applying: "Being applied",
+  applied: "Applied",
+  declined: "Declined",
+  outdated: "Outdated"
+};
+var SUGGESTION_LIMITS = {
+  body: 65536,
+  /** The readable part of the body (tables are cut with "and N more"). */
+  human: 12e3,
+  /** The JSON block in the body. */
+  inline: 48e3,
+  /** The JSON block of one continuation comment. */
+  part: 6e4,
+  /** Continuation comments at most (about 480 KB of file contents). */
+  maxParts: 8
+};
+var SuggestionError = class extends Error {
+  constructor(code2, message) {
+    super(message);
+    this.code = code2;
+    this.name = "SuggestionError";
+  }
+  code;
+};
+var SUGGESTION_TOO_LARGE = "Too large for a suggestion: split it, or ask a developer to open it directly.";
+var utf8 = (text) => new TextEncoder().encode(text);
+var hex = (words) => words.map((w) => (w >>> 0).toString(16).padStart(8, "0")).join("");
+function padded(bytes) {
+  const len = bytes.length;
+  const total = Math.ceil((len + 9) / 64) * 64;
+  const buf = new Uint8Array(total);
+  buf.set(bytes);
+  buf[len] = 128;
+  const view = new DataView(buf.buffer);
+  view.setUint32(total - 8, Math.floor(len / 536870912), false);
+  view.setUint32(total - 4, len * 8 >>> 0, false);
+  return view;
+}
+var K256 = [
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+];
+function sha256Hex(text) {
+  const view = padded(utf8(text));
+  const h = [1779033703, 3144134277, 1013904242, 2773480762, 1359893119, 2600822924, 528734635, 1541459225];
+  const w = new Array(64);
+  const rotr = (x, n) => x >>> n | x << 32 - n;
+  for (let off = 0; off < view.byteLength; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const a2 = w[i - 15];
+      const b2 = w[i - 2];
+      const s0 = rotr(a2, 7) ^ rotr(a2, 18) ^ a2 >>> 3;
+      const s1 = rotr(b2, 17) ^ rotr(b2, 19) ^ b2 >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 | 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let i = 0; i < 64; i++) {
+      const t1 = hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + (e & f ^ ~e & g) + K256[i] + w[i] | 0;
+      const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) | 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = d + t1 | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 | 0;
+    }
+    h[0] = h[0] + a | 0;
+    h[1] = h[1] + b | 0;
+    h[2] = h[2] + c | 0;
+    h[3] = h[3] + d | 0;
+    h[4] = h[4] + e | 0;
+    h[5] = h[5] + f | 0;
+    h[6] = h[6] + g | 0;
+    h[7] = h[7] + hh | 0;
+  }
+  return hex(h);
+}
+function sha1Bytes(bytes) {
+  const view = padded(bytes);
+  const h = [1732584193, 4023233417, 2562383102, 271733878, 3285377520];
+  const w = new Array(80);
+  const rotl = (x, n) => x << n | x >>> 32 - n;
+  for (let off = 0; off < view.byteLength; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4, false);
+    for (let i = 16; i < 80; i++) w[i] = rotl(w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16], 1);
+    let [a, b, c, d, e] = h;
+    for (let i = 0; i < 80; i++) {
+      const [f, k] = i < 20 ? [b & c | ~b & d, 1518500249] : i < 40 ? [b ^ c ^ d, 1859775393] : i < 60 ? [b & c | b & d | c & d, 2400959708] : [b ^ c ^ d, 3395469782];
+      const t = rotl(a, 5) + f + e + k + w[i] | 0;
+      e = d;
+      d = c;
+      c = rotl(b, 30);
+      b = a;
+      a = t;
+    }
+    h[0] = h[0] + a | 0;
+    h[1] = h[1] + b | 0;
+    h[2] = h[2] + c | 0;
+    h[3] = h[3] + d | 0;
+    h[4] = h[4] + e | 0;
+  }
+  return hex(h);
+}
+function gitBlobSha(text) {
+  const body = utf8(text);
+  const head = utf8(`blob ${body.length}\0`);
+  const all = new Uint8Array(head.length + body.length);
+  all.set(head);
+  all.set(body, head.length);
+  return sha1Bytes(all);
+}
+function canonicalJson(value) {
+  return JSON.stringify(sortKeys(value));
+}
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map((x) => x === void 0 ? null : sortKeys(x));
+  if (v && typeof v === "object" && !(v.toJSON instanceof Function)) {
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      const x = v[k];
+      if (x !== void 0) out[k] = sortKeys(x);
+    }
+    return out;
+  }
+  return v;
 }
-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) };
+function shaForm(p) {
+  if (!p.files) return p;
+  return { ...p, files: p.files.map(({ part: _part, ...f }) => f) };
 }
-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;
+function suggestionPayloadSha(p) {
+  return sha256Hex(canonicalJson(shaForm(p)));
 }
-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;
+var KIND_SUBJECT = {
+  "token-change": "Tokens",
+  docs: "Docs",
+  "component-spec": "Component",
+  brand: "Brand",
+  revert: "Revert",
+  config: "Settings"
+};
+function suggestionSubject(p) {
+  if (p.kind === "component-spec" && p.componentSpec?.component) return p.componentSpec.component;
+  if (p.kind === "docs" && p.docs?.length) {
+    const names3 = [...new Set(p.docs.map((d) => d.component))];
+    return names3.length === 1 ? names3[0] : KIND_SUBJECT.docs;
   }
+  return KIND_SUBJECT[p.kind];
 }
-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 } : {} };
+function suggestionIssueTitle(p) {
+  const t = p.title.trim().replace(/\.$/, "");
+  return `${suggestionSubject(p)}: ${t.charAt(0).toLowerCase()}${t.slice(1)}`;
 }
-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 };
+function suggestionLabels(p, opts = {}) {
+  return [
+    .../* @__PURE__ */ new Set([
+      SUGGESTION_LABEL,
+      `suggestion: ${p.kind}`,
+      `source: ${p.source}`,
+      `tier: ${p.tier.tier}`,
+      SUGGESTION_STATE_LABELS[opts.state ?? "needs-review"],
+      ...p.links?.neededBy ? [NEEDED_BY_LABEL] : [],
+      ...p.links?.figma || p.source === "figma" ? [FROM_FIGMA_LABEL] : [],
+      ...p.links?.exploration ? [EXPLORATION_LABEL] : [],
+      ...opts.labels ?? []
+    ])
+  ];
+}
+function suggestionKindFromLabels(labels) {
+  for (const l of labels) {
+    const m = /^suggestion: (.+)$/.exec(l);
+    if (m && SUGGESTION_KINDS.includes(m[1])) return m[1];
   }
-  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.`);
+  return void 0;
+}
+function suggestionStateFromLabels(labels) {
+  return Object.entries(SUGGESTION_STATE_LABELS).find(([, l]) => labels.includes(l))?.[0];
+}
+function suggestionStatus(i) {
+  const prs = i.linkedPrs ?? [];
+  if (i.state === "closed") return prs.some((p) => p.merged) || i.stateReason === "completed" ? "applied" : "declined";
+  if (prs.some((p) => p.state === "open") || i.applied) return "applying";
+  if (i.outdated) return "outdated";
+  return i.review ?? "needs-review";
+}
+function suggestionStateLabel(status) {
+  return status in SUGGESTION_STATE_LABELS ? SUGGESTION_STATE_LABELS[status] : null;
+}
+var bridgeMcpInstallCommand = (repo) => `claude mcp add bridge -s user -- npx -y @bridge-ds/mcp --repo ${repo?.trim() || "<owner/name>"}`;
+var MARK3 = "bridge-suggestion";
+var PART_SCHEMA = "bridge.suggestion-part/1";
+var cell3 = (s) => s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+var safeText = (s) => s.replace(/<!--/g, "&lt;!--");
+var sourceLabel2 = (s) => s === "figma" ? "Figma" : s === "studio" ? "Bridge Studio" : s === "cli" ? "the CLI" : "Claude (MCP)";
+var show2 = (v) => v === void 0 ? "" : typeof v === "string" ? v : JSON.stringify(v);
+function table(head, rows, max) {
+  if (!rows.length) return [];
+  const shown = rows.slice(0, max);
+  return [
+    `| ${head.join(" | ")} |`,
+    `| ${head.map(() => "---").join(" | ")} |`,
+    ...shown.map((r) => `| ${r.map((c) => cell3(c)).join(" | ")} |`),
+    ...rows.length > max ? ["", `and ${rows.length - max} more`] : []
+  ];
+}
+function changesSection(p, max) {
+  const out = [];
+  if (p.tokens?.changes.length) {
+    const rows = p.tokens.changes.map((c) => [
+      `\`${c.path}\`${c.kind === "renamed" && c.from ? ` (was \`${c.from}\`)` : c.kind === "added" ? " (new)" : c.kind === "removed" ? " (removed)" : ""}`,
+      c.beforeCss ?? show2(c.before),
+      c.afterCss ?? show2(c.after)
+    ]);
+    out.push(...table(["Token", "Now", "Suggested"], rows, max), "");
+  } else if (p.tokens?.edits.length) {
+    const rows = p.tokens.edits.map((e) => [`\`${e.path}\``, e.op === "rename" ? `rename to \`${e.newPath ?? ""}\`` : e.op, show2(e.value)]);
+    out.push(...table(["Token", "Edit", "Value"], rows, max), "");
   }
-  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;
-    });
+  if (p.docs?.length) out.push(...table(["Component", "Docs file"], p.docs.map((d) => [d.component, `\`${d.path}\``]), max), "");
+  if (p.componentSpec) out.push(`**Component spec:** ${p.componentSpec.component} (\`${p.componentSpec.specPath}\`)`, "");
+  if (p.files?.length) {
+    const rows = p.files.map((f) => [`\`${f.path}\``, f.beforeSha === null ? "new" : f.afterSha === null ? "deleted" : "changed"]);
+    out.push(...table(["File", "Change"], rows, max), "");
   }
-  return { status: "opened", plan, link, preview, warnings };
+  return out;
 }
-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);
+function checksSection(p, max) {
+  const c = p.checks;
+  const failing = c.contrast.filter((x) => !x.pass);
+  const rows = [...failing, ...c.contrast.filter((x) => x.pass)].map((x) => [x.pair, x.mode ?? "", x.before.toFixed(2), x.after.toFixed(2), String(x.min), x.pass ? "pass" : "**fails**"]);
+  return [
+    "## Checks when suggested",
+    "",
+    `- Token validation: ${c.newErrors ? `**${c.newErrors} new error(s)**` : "no new errors"}`,
+    `- Contrast: ${c.contrast.length ? failing.length ? `**${failing.length} failing pair(s)**` : `${c.contrast.length} pair(s) checked, all pass` : "no pair affected"}`,
+    `- Risk tier: ${p.tier.tier} (\`${p.tier.bump}\`), ${p.tier.tier === 1 ? "one approval" : "design and tech approval"}`,
+    `- Impact: ${c.impact ? `${c.impact} token(s) resolve to a new value` : "no other token changes value"}`,
+    "",
+    ...rows.length ? [...table(["Pair", "Mode", "Before", "After", "Min", "Result"], rows, max), ""] : []
+  ];
+}
+function linksSection(p) {
+  const l = p.links ?? {};
+  const out = [];
+  if (l.neededBy) out.push(`- Needed by ${l.neededBy.productName}: [#${l.neededBy.pr} ${cell3(l.neededBy.title)}](${l.neededBy.url})`);
+  if (l.figma?.url) out.push(`- Design: [Open in Figma](${l.figma.url})`);
+  if (l.exploration) out.push(`- Exploration: \`${l.exploration}\``);
+  if (l.supersedes) out.push(`- Replaces suggestion #${l.supersedes}`);
+  for (const v of p.previews ?? []) out.push(`- ${cell3(v.label)}: ${v.url}`);
+  return out.length ? ["## Previews and links", "", ...out, ""] : [];
+}
+function humanPart(p, details, max, repo) {
+  return [
+    `## Suggested change: ${safeText(p.title.trim())}`,
+    "",
+    safeText(p.summary.trim()),
+    "",
+    ...changesSection(p, max),
+    ...details?.trim() ? [safeText(details.trim()), ""] : [],
+    ...checksSection(p, max),
+    ...linksSection(p),
+    "## How to apply",
+    "",
+    "- CLI: `bridge apply <this issue number>` (add `--dry-run` to check it first, `--patch` for a patch file)",
+    '- Claude Code with the Bridge MCP server: ask "Apply Bridge suggestion #<this issue number>" (tool `bridge_apply_suggestion`).',
+    `  One-time install: \`${bridgeMcpInstallCommand(repo)}\``,
+    "",
+    "The pull request that applies it must say `Closes #<this issue number>`, so this suggestion closes when it merges.",
+    "",
+    `<sub>Suggested from ${sourceLabel2(p.source)}${p.suggestedBy ? ` by @${p.suggestedBy.replace(/^@/, "")}` : ""} with Bridge.</sub>`
+  ].join("\n");
+}
+function fitHuman(p, details, repo) {
+  for (const max of [50, 20, 8, 3]) {
+    const h2 = humanPart(p, details, max, repo);
+    if (h2.length <= SUGGESTION_LIMITS.human) return h2;
+  }
+  const h = humanPart(p, void 0, 3, repo);
+  if (h.length <= SUGGESTION_LIMITS.human) return h;
+  const note = "\n\n_The description is cut here: the full change is in the machine-readable block below._";
+  return h.slice(0, SUGGESTION_LIMITS.human - note.length) + note;
+}
+var pretty = (v) => JSON.stringify(sortKeys(v), null, 2);
+var fit = (v) => {
+  const p = pretty(v);
+  return p.length <= SUGGESTION_LIMITS.inline ? p : canonicalJson(v);
+};
+var fenced = (json) => ["```json", json, "```"].join("\n");
+function payloadBlock(json, sha, parts) {
+  return [
+    "<details><summary>Machine-readable change (Bridge suggestion v1)</summary>",
+    "",
+    `<!-- ${MARK3}:v1 sha256=${sha}${parts ? ` parts=${parts}` : ""} -->`,
+    fenced(json),
+    "",
+    "</details>"
+  ].join("\n");
+}
+function partComment(i, n, json) {
+  return [
+    `<details><summary>Machine-readable change, part ${i} of ${n} (Bridge suggestion v1)</summary>`,
+    "",
+    `<!-- ${MARK3}:v1 part ${i}/${n} sha256=${sha256Hex(json)} -->`,
+    fenced(json),
+    "",
+    "</details>"
+  ].join("\n");
+}
+function escapedEnd(s, from, budget) {
+  let used = 0;
+  let i = from;
+  while (i < s.length) {
+    const c = s.charCodeAt(i);
+    let w = 1;
+    let len = 1;
+    if (c === 34 || c === 92 || c === 8 || c === 12 || c === 10 || c === 13 || c === 9) len = 2;
+    else if (c < 32) len = 6;
+    else if (c >= 55296 && c <= 56319) {
+      const d = s.charCodeAt(i + 1);
+      if (d >= 56320 && d <= 57343) {
+        w = 2;
+        len = 2;
+      } else len = 6;
+    } else if (c >= 56320 && c <= 57343) len = 6;
+    if (used + len > budget) break;
+    used += len;
+    i += w;
+  }
+  return i;
+}
+function composeSuggestionIssue(payload, opts = {}) {
+  const problems = suggestionShapeProblems(payload);
+  if (problems.length) throw new SuggestionError("invalid", problems.join(" "));
+  if (payload.checks.blocked) throw new SuggestionError("invalid", `This change cannot be suggested: ${payload.checks.blocked}`);
+  const full = shaForm(payload);
+  const sha = suggestionPayloadSha(full);
+  const human = fitHuman(full, opts.details, opts.repo);
+  const base = { title: suggestionIssueTitle(full), labels: suggestionLabels(full, { state: opts.state, labels: opts.labels }), assignees: opts.assignees ?? [], sha };
+  const inline = fit(full);
+  if (inline.length <= SUGGESTION_LIMITS.inline) {
+    return { ...base, body: `${human}
+
+${payloadBlock(inline, sha, 0)}
+`, parts: [] };
+  }
+  const moved = (full.files ?? []).map((f, i) => ({ f, i })).filter(({ f }) => typeof f.content === "string" && f.content.length > 0);
+  const parts = [];
+  const firstPart = /* @__PURE__ */ new Map();
+  const partJson = (chunks, i, n2) => pretty({ schema: PART_SCHEMA, part: i, of: n2, files: chunks });
+  const emptyOverhead = partJson([], 9, 9).length;
+  let cur = [];
+  let room = SUGGESTION_LIMITS.part - emptyOverhead - 64;
+  for (const { f, i } of moved) {
+    const text = f.content;
+    let at = 0;
+    while (at < text.length) {
+      const entryOverhead = partJson([{ i, path: f.path, text: "" }], 9, 9).length - emptyOverhead + 8;
+      if (room - entryOverhead < 256) {
+        parts.push(cur);
+        cur = [];
+        room = SUGGESTION_LIMITS.part - emptyOverhead - 64;
+      }
+      const end = escapedEnd(text, at, room - entryOverhead);
+      if (end === at) throw new SuggestionError("too-large", SUGGESTION_TOO_LARGE);
+      if (!firstPart.has(i)) firstPart.set(i, parts.length + 1);
+      const chunk = { i, path: f.path, text: text.slice(at, end) };
+      cur.push(chunk);
+      room -= partJson([chunk], 9, 9).length - emptyOverhead + 8;
+      at = end;
+    }
+  }
+  if (cur.length) parts.push(cur);
+  if (parts.length > SUGGESTION_LIMITS.maxParts) throw new SuggestionError("too-large", SUGGESTION_TOO_LARGE);
+  const skeleton = {
+    ...full,
+    files: (full.files ?? []).map((f, i) => {
+      if (!firstPart.has(i)) return f;
+      const { content: _content, ...rest } = f;
+      return { ...rest, part: firstPart.get(i) };
+    })
+  };
+  const skeletonJson = fit(skeleton);
+  if (skeletonJson.length > SUGGESTION_LIMITS.inline) throw new SuggestionError("too-large", SUGGESTION_TOO_LARGE);
+  const n = parts.length;
+  const partBodies = parts.map((chunks, k) => {
+    const json = partJson(chunks, k + 1, n);
+    if (json.length > SUGGESTION_LIMITS.part) throw new SuggestionError("too-large", SUGGESTION_TOO_LARGE);
+    return partComment(k + 1, n, json);
+  });
+  const body = `${human}
+
+${payloadBlock(skeletonJson, sha, n)}
+`;
+  if (body.length > SUGGESTION_LIMITS.body || partBodies.some((b) => b.length > SUGGESTION_LIMITS.body)) throw new SuggestionError("too-large", SUGGESTION_TOO_LARGE);
+  return { ...base, body, parts: partBodies };
+}
+function fencedAfter(text, from) {
+  const m = /```json\r?\n([\s\S]*?)\r?\n```/.exec(text.slice(from));
+  return m?.[1];
+}
+var fail = (reason, message) => ({ ok: false, reason, message });
+function parseSuggestionIssue(body, opts = {}) {
+  const text = body ?? "";
+  const markers = [...text.matchAll(new RegExp(`^<!-- ${MARK3}:v(\\d+) sha256=([0-9a-f]{64})(?: parts=(\\d+))? -->$`, "gm"))];
+  const marker = markers[markers.length - 1];
+  if (!marker) return fail("no-block", "This issue has no Bridge suggestion block.");
+  if (marker[1] !== "1") return fail("unsupported-version", `This suggestion uses version ${marker[1]} of the format. Update Bridge to read it.`);
+  const json = fencedAfter(text, marker.index + marker[0].length);
+  if (json === void 0) return fail("invalid", "The suggestion block has no JSON. Someone may have edited it by hand: ask the author to send it again.");
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    return fail("invalid", "The suggestion JSON does not parse. Someone may have edited it by hand: ask the author to send it again.");
+  }
+  const schema = raw?.schema;
+  if (typeof schema === "string" && schema !== SUGGESTION_SCHEMA) {
+    const v = /^bridge\.suggestion\/(\d+)$/.exec(schema);
+    return v ? fail("unsupported-version", `This suggestion uses ${schema}. Update Bridge to read it.`) : fail("invalid", `"${schema}" is not a Bridge suggestion schema.`);
+  }
+  const problems = suggestionShapeProblems(raw);
+  if (problems.length) return fail("invalid", `The suggestion block is not valid: ${problems.join(" ")}`);
+  const payload = raw;
+  const markedSha = marker[2];
+  const expected = marker[3] ? Number(marker[3]) : 0;
+  let edited = false;
+  if (expected > 0 || payload.files?.some((f) => f.part !== void 0)) {
+    const want = Math.max(expected, ...(payload.files ?? []).map((f) => f.part ?? 0));
+    const found = /* @__PURE__ */ new Map();
+    const author = opts.author?.toLowerCase();
+    for (const c of opts.comments ?? []) {
+      if (author && c.author && c.author.toLowerCase() !== author) continue;
+      const m = new RegExp(`^<!-- ${MARK3}:v1 part (\\d+)/(\\d+) sha256=([0-9a-f]{64}) -->$`, "m").exec(c.body);
+      if (!m) continue;
+      const i = Number(m[1]);
+      if (found.has(i)) continue;
+      const pj = fencedAfter(c.body, m.index + m[0].length);
+      if (pj === void 0) continue;
+      if (sha256Hex(pj) !== m[3]) edited = true;
+      try {
+        const part = JSON.parse(pj);
+        if (part.schema !== PART_SCHEMA || !Array.isArray(part.files)) continue;
+        found.set(i, part.files.filter((x) => x && typeof x.i === "number" && typeof x.text === "string"));
+      } catch {
+        continue;
+      }
+    }
+    for (let i = 1; i <= want; i++) {
+      if (!found.has(i)) return fail("missing-part", `This suggestion is incomplete: part ${i} of ${want} is missing. It is still being written, or a comment was deleted: ask the author to send it again.`);
+    }
+    const files = (payload.files ?? []).map((f, idx) => {
+      if (f.part === void 0) return f;
+      let content = "";
+      for (let i = 1; i <= want; i++) for (const ch of found.get(i)) if (ch.i === idx && ch.path === f.path) content += ch.text;
+      const { part: _part, ...rest } = f;
+      return { ...rest, content };
+    });
+    payload.files = files;
+  }
+  const sha = suggestionPayloadSha(payload);
+  return { ok: true, payload, sha, markedSha, edited: edited || sha !== markedSha, parts: expected };
+}
+function suggestionShapeProblems(raw) {
+  const out = [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return ["The payload must be a JSON object."];
+  const p = raw;
+  if (p.schema !== SUGGESTION_SCHEMA) out.push(`"schema" must be "${SUGGESTION_SCHEMA}".`);
+  if (!SUGGESTION_KINDS.includes(p.kind)) out.push(`"kind" must be one of ${SUGGESTION_KINDS.join(", ")}.`);
+  if (typeof p.title !== "string" || !p.title.trim()) out.push('"title" must be a sentence.');
+  if (typeof p.summary !== "string") out.push('"summary" must be text.');
+  if (!["figma", "studio", "cli", "mcp"].includes(p.source)) out.push('"source" must be figma, studio, cli or mcp.');
+  if (typeof p.createdAt !== "string") out.push('"createdAt" must be an ISO date.');
+  const base = p.base;
+  if (!base || typeof base.ref !== "string" || typeof base.sha !== "string" || !/^[0-9a-f]{7,64}$/.test(base.sha)) out.push('"base" must be { "ref", "sha" } with the commit the change was planned on.');
+  const tier = p.tier;
+  if (!tier || ![1, 2, 3].includes(tier.tier) || !["patch", "minor", "major"].includes(tier.bump)) out.push('"tier" must be { "tier": 1, 2 or 3, "bump": patch, minor or major }.');
+  const checks = p.checks;
+  if (!checks || typeof checks.newErrors !== "number" || !Array.isArray(checks.contrast) || typeof checks.impact !== "number" || !(checks.blocked === null || typeof checks.blocked === "string"))
+    out.push('"checks" must be { "newErrors", "contrast", "blocked", "impact" }.');
+  const tokens = p.tokens;
+  if (tokens !== void 0 && (!tokens || !Array.isArray(tokens.edits) || !Array.isArray(tokens.changes))) out.push('"tokens" must be { "edits", "changes" }.');
+  if (p.docs !== void 0 && !(Array.isArray(p.docs) && p.docs.every((d) => d && typeof d.component === "string" && typeof d.path === "string"))) out.push('"docs" must be a list of { "component", "path", "after" }.');
+  const spec = p.componentSpec;
+  if (spec !== void 0 && (!spec || typeof spec.component !== "string" || typeof spec.specPath !== "string" || typeof spec.brief !== "string")) out.push('"componentSpec" must be { "component", "specPath", "spec", "brief" }.');
+  if (p.files !== void 0) {
+    if (!Array.isArray(p.files)) out.push('"files" must be a list.');
+    else {
+      const seen = /* @__PURE__ */ new Set();
+      for (const f of p.files) {
+        const ok2 = f && typeof f.path === "string" && (f.beforeSha === null || typeof f.beforeSha === "string") && (f.afterSha === null || typeof f.afterSha === "string") && (f.content === void 0 || f.content === null || typeof f.content === "string") && (f.part === void 0 || Number.isInteger(f.part) && f.part >= 1 && f.part <= SUGGESTION_LIMITS.maxParts);
+        if (!ok2) {
+          out.push('Each of "files" must be { "path", "beforeSha", "afterSha", "content"? }.');
+          break;
+        }
+        if (seen.has(f.path)) out.push(`"${f.path}" is listed twice in "files".`);
+        seen.add(f.path);
+      }
+    }
+  }
+  return out;
+}
+function unsafePathProblem(path) {
+  if (typeof path !== "string" || !path.length) return "A path is empty.";
+  if (/[\0-\x1f\x7f]/.test(path)) return `"${path.replace(/[\0-\x1f\x7f]/g, "?")}" has control characters.`;
+  if (path.includes("\\")) return `"${path}" uses backslashes: paths use forward slashes.`;
+  if (path.startsWith("/") || /^[A-Za-z]:/.test(path) || path.startsWith("~")) return `"${path}" is absolute: paths are relative to the repository root.`;
+  const segs = path.split("/");
+  if (segs.some((s) => s === "" || s === "." || s === "..")) return `"${path}" has an empty, "." or ".." part: paths stay inside the repository.`;
+  if (segs.some((s) => s.toLowerCase() === ".git")) return `"${path}" is inside .git.`;
+  return null;
+}
+var under = (path, root) => {
+  const r = root.replace(/\/+$/, "");
+  return !r || r === "." || path === r || path.startsWith(`${r}/`);
+};
+function isGuardrailPath(path, guardrails) {
+  return guardrails.some((g) => g.endsWith("/") ? path.startsWith(g) || path === g.slice(0, -1) : path === g);
+}
+function suggestionAllowedRoots(kind, config) {
+  const tokenRoot2 = tokensPath(config) || ".";
+  const changesets = config.changesets?.dir ? [config.changesets.dir] : [];
+  switch (kind) {
+    case "token-change":
+      return [tokenRoot2, ...changesets];
+    case "docs":
+      return [...config.components?.dir ? [config.components.dir] : [], ...changesets];
+    case "component-spec":
+      return [".bridge/figma"];
+    case "brand":
+      return [tokenRoot2, ...changesets, CONFIG_FILE];
+    case "config":
+      return [CONFIG_FILE];
+    case "revert":
+      return void 0;
+  }
+}
+function suggestionPathProblems(p, config) {
+  const out = [];
+  const roots = suggestionAllowedRoots(p.kind, config);
+  const guardrails = config.governance.guardrails;
+  const check = (path) => {
+    const bad = unsafePathProblem(path);
+    if (bad) return out.push(bad);
+    if (roots && !roots.some((r) => under(path, r))) return out.push(`"${path}" is outside what a ${p.kind} suggestion may change (${roots.join(", ")}).`);
+    const configAllowed = path === CONFIG_FILE && (p.kind === "config" || p.kind === "brand");
+    if (!configAllowed && isGuardrailPath(path, guardrails)) return out.push(`"${path}" is a guardrail file: change it in a pull request, not a suggestion.`);
+    return 0;
+  };
+  for (const f of p.files ?? []) check(f.path);
+  for (const d of p.docs ?? []) check(d.path);
+  if (p.componentSpec) check(p.componentSpec.specPath);
+  for (const e of p.tokens?.edits ?? []) {
+    if (e.file === void 0) continue;
+    const bad = unsafePathProblem(e.file);
+    if (bad) out.push(bad);
+  }
+  return [...new Set(out)];
+}
+
+// ../core/src/suggestions-github.ts
+async function createSuggestionOnGitHub(gh, payload, opts = {}) {
+  const issue = composeSuggestionIssue(payload, { repo: gh.fullName, ...opts });
+  const created = await gh.createIssue({ title: issue.title, body: issue.body, labels: issue.labels, assignees: issue.assignees });
+  for (const [i, part] of issue.parts.entries()) {
+    try {
+      await gh.createIssueComment(created.number, part);
+    } catch (err) {
+      const why = err instanceof Error ? err.message : String(err);
+      throw new GitHubError(err instanceof GitHubError ? err.status : 500, `Suggestion #${created.number} is incomplete: part ${i + 1} of ${issue.parts.length} could not be posted (${why}). Send it again, then close #${created.number}.`);
+    }
+  }
+  const warnings = [];
+  const missing = issue.labels.filter((l) => !created.labels.includes(l));
+  if (created.labels.length && missing.length) warnings.push(`GitHub did not keep these labels on #${created.number}: ${missing.join(", ")}.`);
+  return { number: created.number, url: created.url, sha: issue.sha, parts: issue.parts.length, warnings };
+}
+function linkedPullsOf(n, pulls) {
+  return pulls.filter((p) => closingIssueNumbers(p.body).includes(n)).map((p) => ({ number: p.number, url: p.url, state: p.state === "open" ? "open" : "closed", merged: p.state === "merged" }));
+}
+async function listSuggestionsOnGitHub(gh, opts = {}) {
+  const issues = await gh.listIssues({ label: SUGGESTION_LABEL, state: opts.state ?? "open", perPage: opts.perPage ?? 50 });
+  const pulls = opts.pulls ?? (issues.length ? await gh.listPullRequests("all").catch(() => []) : []);
+  return issues.map((i) => listItem(i, pulls));
+}
+function listItem(i, pulls) {
+  const linkedPrs = linkedPullsOf(i.number, pulls);
+  const cached = suggestionStateFromLabels(i.labels);
+  const t = i.labels.map((l) => /^tier: ([123])$/.exec(l)?.[1]).find(Boolean);
+  return {
+    number: i.number,
+    title: i.title,
+    url: i.url,
+    author: i.author,
+    createdAt: i.createdAt,
+    state: i.state,
+    stateReason: i.stateReason,
+    labels: i.labels,
+    kind: suggestionKindFromLabels(i.labels),
+    tier: t ? Number(t) : void 0,
+    linkedPrs,
+    status: suggestionStatus({ state: i.state, stateReason: i.stateReason, linkedPrs, applied: cached === "applying", review: cached === "applying" ? void 0 : cached })
+  };
+}
+async function getSuggestionOnGitHub(gh, n, gov, opts = {}) {
+  const [issue, comments, pulls] = await Promise.all([gh.getIssue(n), gh.listIssueComments(n), opts.pulls ? Promise.resolve(opts.pulls) : gh.listPullRequests("all").catch(() => [])]);
+  const parsed = parseSuggestionIssue(issue.body, { comments, author: issue.author || void 0 });
+  const linkedPrs = linkedPullsOf(n, pulls);
+  const applied = comments.flatMap((c) => parseSuggestionAppliedComment(c.body) ?? []);
+  const approvals = parsed.ok ? summarizeSuggestionApprovals(comments, gov, { payloadSha: parsed.sha, author: issue.author }) : void 0;
+  const status = suggestionStatus({
+    state: issue.state,
+    stateReason: issue.stateReason,
+    linkedPrs,
+    applied: parsed.ok && applied.some((a) => a.payloadSha === parsed.sha),
+    outdated: opts.outdated,
+    review: parsed.ok && approvals ? suggestionReviewState(parsed.payload.tier.tier, approvals) : void 0
+  });
+  return { issue, parsed, comments, approvals, linkedPrs, applied, status };
+}
+async function syncSuggestionStateLabel(gh, n, labels, status) {
+  const want = suggestionStateLabel(status);
+  let ok2 = true;
+  for (const l of Object.values(SUGGESTION_STATE_LABELS)) {
+    if (l === want || !labels.includes(l)) continue;
+    try {
+      await gh.removeLabel(n, l);
+    } catch {
+      ok2 = false;
+    }
+  }
+  if (want && !labels.includes(want)) ok2 = await gh.addLabels(n, [want]) && ok2;
+  return ok2 ? null : `The state label on #${n} could not be updated; the status shown in Bridge is still right.`;
+}
+async function reviewSuggestionOnGitHub(gh, n, input, gov) {
+  if (input.event === "request-changes" && !input.message?.trim()) throw new GitHubError(422, "Say what should change, in a sentence or two: the author reads it.");
+  const before = await getSuggestionOnGitHub(gh, n, gov);
+  if (!before.parsed.ok) throw new GitHubError(422, `#${n} cannot be reviewed: ${before.parsed.message}`);
+  if (before.issue.state === "closed") throw new GitHubError(422, `#${n} is closed. Reopen it on GitHub to review it again.`);
+  const sha = before.parsed.sha;
+  if (input.payloadSha && input.payloadSha !== sha) throw new GitHubError(409, `#${n} changed since you opened it. Reload it and review the new version.`);
+  const by = input.by ?? (await gh.getViewer().catch(() => ({ login: "" }))).login;
+  const body = composeSuggestionReviewComment({ event: input.event, role: input.role, payloadSha: sha, at: (input.at ?? /* @__PURE__ */ new Date()).toISOString(), by: by || void 0, message: input.message });
+  const posted = await gh.createIssueComment(n, body);
+  const after = await getSuggestionOnGitHub(gh, n, gov);
+  const status = after.status;
+  const who = (after.comments.find((c) => c.id === posted.id)?.author ?? by).toLowerCase();
+  const counts = input.event === "comment" || [...after.approvals?.approvers ?? [], ...after.approvals?.changesRequested ?? []].some((l) => l.toLowerCase() === who);
+  const warnings = [];
+  if (!counts) warnings.push("Your review is posted but does not count: only the owners listed in bridge.config.json approve suggestions.");
+  if (before.parsed.edited) warnings.push(`#${n} was edited by hand after Bridge wrote it: check the machine-readable block before applying it.`);
+  const labelWarning = await syncSuggestionStateLabel(gh, n, before.issue.labels, status);
+  if (labelWarning) warnings.push(labelWarning);
+  return { commentUrl: posted.url, payloadSha: sha, status, counts, warnings };
+}
+async function linkSuggestionPrOnGitHub(gh, n, link) {
+  if (!link.pr && !link.branch && !link.commit) throw new GitHubError(422, "Say where it is applied: a pull request number, a branch or a commit.");
+  const issue = await gh.getIssue(n);
+  await gh.addComment(n, composeSuggestionAppliedComment({ by: link.by, branch: link.branch, commit: link.commit, pr: link.pr, payloadSha: link.payloadSha, forced: link.forced, at: (link.at ?? /* @__PURE__ */ new Date()).toISOString() }));
+  const warning = await syncSuggestionStateLabel(gh, n, issue.labels, "applying");
+  return { warnings: warning ? [warning] : [] };
+}
+async function declineSuggestionOnGitHub(gh, n, reason, by) {
+  const issue = await gh.getIssue(n);
+  await declineRequestOnGitHub(gh, n, reason, by);
+  const warning = await syncSuggestionStateLabel(gh, n, issue.labels, "declined");
+  return { warnings: warning ? [warning] : [] };
+}
+
+// ../core/src/docs-proposal.ts
+var DOCS_EDITOR_ORIGIN = {
+  where: "in the Bridge docs editor",
+  footer: "Written by a person in the Bridge docs editor. No AI involved in this text.",
+  label: "source: bridge-web"
+};
+var DOCS_MCP_ORIGIN = {
+  where: "with Claude through the Bridge MCP server",
+  footer: 'Proposed with the Bridge MCP server on behalf of a person. Docs Claude drafted say "draftedBy": "claude" until a reviewer accepts them.',
+  label: "source: mcp"
+};
+var EM_DASH = /\u2014/;
+function validateDocs(d) {
+  const out = [];
+  if (!d.summary.trim()) out.push({ field: "summary", message: "Add a summary: one or two sentences on what it is for." });
+  const lists = ["whenToUse", "whenNotToUse", "accessibility", "contentGuidelines"];
+  for (const k of lists) (d[k] ?? []).forEach((x, i) => !x.trim() && out.push({ field: `${k}.${i}`, message: "Fill or remove the empty item." }));
+  for (const k of ["dos", "donts"]) d[k].forEach((g, i) => (!g.title.trim() || !g.text.trim()) && out.push({ field: `${k}.${i}`, message: "Give every item a title and a sentence." }));
+  const prose = JSON.stringify([d.summary, d.whenToUse, d.whenNotToUse, d.dos, d.donts, d.accessibility, d.contentGuidelines ?? [], d.anatomy ?? {}]);
+  if (EM_DASH.test(prose)) out.push({ field: "voice", message: "Replace the em dashes with a colon, a comma or two sentences." });
+  return out;
+}
+function cleanDocs(d) {
+  const list = (xs) => (xs ?? []).map((x) => x.trim()).filter(Boolean);
+  const guide = (xs) => xs.map((g) => ({ ...g, title: g.title.trim(), text: g.text.trim() })).filter((g) => g.title || g.text);
+  return {
+    ...d,
+    summary: d.summary.trim(),
+    whenToUse: list(d.whenToUse),
+    whenNotToUse: list(d.whenNotToUse),
+    dos: guide(d.dos),
+    donts: guide(d.donts),
+    accessibility: list(d.accessibility),
+    contentGuidelines: list(d.contentGuidelines),
+    anatomy: Object.fromEntries(Object.entries(d.anatomy ?? {}).filter(([k, v]) => k.trim() && v.trim()))
+  };
+}
+var docsFileText = (d, original) => patchDocsJson(original, cleanDocs(d));
+var slugDate = (d) => d.toISOString().slice(0, 10).replace(/-/g, "");
+var docsSlug = (nameOrSlug) => nameOrSlug.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9-]+/g, "-").slice(0, 40);
+function defaultDocsFooter(edits, origin) {
+  if (origin.label !== DOCS_EDITOR_ORIGIN.label) return origin.footer;
+  const claude = edits.some((e) => {
+    try {
+      return JSON.parse(e.after).draftedBy === "claude";
+    } catch {
+      return false;
+    }
+  });
+  return claude ? `Drafted by Claude AI (the docs say "draftedBy": "claude"), sent by a person ${origin.where}.` : origin.footer;
+}
+function withAuthorLine(body, line) {
+  const i = body.lastIndexOf("\n---\n");
+  return i < 0 ? `${body.trimEnd()}
+
+---
+${line}` : `${body.slice(0, i + 5)}${line}`;
+}
+var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function isDocsProposalBranch(branch, component) {
+  const slugs = /* @__PURE__ */ new Set([docsSlug(component.slug ?? component.name), docsSlug(component.name), docsSlug(component.name.toLowerCase())]);
+  return [...slugs].some((s) => new RegExp(`^docs/(?:[A-Z][A-Z0-9]*-\\d+-)?${escapeRe(s)}-\\d{8}-[a-z0-9]+$`).test(branch));
+}
+function findOpenDocsProposal(pulls, component, base) {
+  const hit = pulls.filter((p) => p.state === "open" && isDocsProposalBranch(p.headRef, component) && (!base || !p.baseRef || p.baseRef === base)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+  return hit ? { number: hit.number, url: hit.url, branch: hit.headRef, author: hit.author, title: hit.title, updatedAt: hit.updatedAt } : null;
+}
+async function findOpenDocsProposalOnGitHub(gh, component, base) {
+  return findOpenDocsProposal(await gh.listPullRequests("open"), component, base);
+}
+async function continueDocsProposalOnGitHub(gh, open, edit, opts = {}) {
+  const message = opts.message ?? `docs(${docsSlug(edit.component)}): edit usage guidance in the Bridge docs editor`;
+  const cur = await gh.getFile(edit.path, open.branch);
+  if (cur?.text === edit.after) return "";
+  const sha = await gh.putFile({ path: edit.path, content: edit.after, branch: open.branch, message, sha: cur?.sha });
+  if (opts.authorLine) {
+    const line = opts.authorLine;
+    await gh.getPullRequest(open.number).then((pr) => gh.updatePullRequest(open.number, { body: withAuthorLine(pr.body, line) })).catch(() => void 0);
+  }
+  return sha;
+}
+function docsProposal(edits, opts) {
+  const origin = opts.origin ?? DOCS_EDITOR_ORIGIN;
+  if (!edits.length) throw new Error("No docs edits in the draft.");
+  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";
+  const changeset = `---
+"${pkg}": patch
+---
+
+Usage guidance for ${list}.
+`;
+  const files = [...edits.map((e) => ({ path: e.path, content: e.after })), { path: csPath, content: changeset }];
+  const risk = classifyRisk({ files: files.map((f) => ({ path: f.path, status: "modified" })) });
+  const rows = edits.map((e) => {
+    let state = "edited";
+    try {
+      const d = JSON.parse(e.after);
+      const gaps = missingProse(d);
+      state = gaps.length ? `still missing: ${gaps.join(", ")}` : "every section filled";
+    } catch {
+      state = "not valid JSON";
+    }
+    return `- \`${e.path}\` (${e.before === null ? "new" : "changed"}, ${state})`;
+  });
+  const body = [
+    `## Docs change`,
+    "",
+    `Usage guidance for ${list}, written ${origin.where}.`,
+    "",
+    ...rows,
+    "",
+    `**Risk:** ${risk.label}. Docs only: the published components do not change. Changeset: patch.`,
+    "",
+    opts.notes?.trim() ? `## Notes
+
+${opts.notes.trim()}
+` : "",
+    "---",
+    opts.authorLine?.trim() || defaultDocsFooter(edits, origin)
+  ].filter((x, i, a) => !(x === "" && a[i - 1] === "")).join("\n");
+  return { branch, title, body, files, risk, bump: "patch", labels: ["docs", origin.label, `tier-${risk.tier}`] };
+}
+var docsSource = (origin) => origin.label === DOCS_MCP_ORIGIN.label ? "mcp" : "studio";
+function docsSuggestionPayload(edits, opts) {
+  const origin = opts.origin ?? DOCS_EDITOR_ORIGIN;
+  const date = opts.date ?? /* @__PURE__ */ new Date();
+  const p = docsProposal(edits, { title: opts.title, date, origin, packageName: opts.packageName, changesetDir: opts.changesetDir });
+  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 docs = edits.map((e) => {
+    let after;
+    try {
+      after = JSON.parse(e.after);
+    } catch {
+      throw new Error(`${e.path} is not valid JSON: fix it before sending.`);
+    }
+    return { component: e.component, path: e.path, after: cleanDocs(after) };
+  });
+  const docPaths = new Set(edits.map((e) => e.path));
+  const files = p.files.filter((f) => !docPaths.has(f.path)).map((f) => ({ path: f.path, beforeSha: null, afterSha: gitBlobSha(f.content), content: f.content }));
+  const by = opts.suggestedBy?.replace(/^@/, "");
+  return {
+    schema: SUGGESTION_SCHEMA,
+    kind: "docs",
+    title: opts.title?.trim() || (names3.length === 1 ? "Usage guidance" : `Usage guidance for ${list}`),
+    summary: [`Usage guidance for ${list}, written ${origin.where}.`, opts.notes?.trim() ?? ""].filter(Boolean).join("\n\n"),
+    source: opts.source ?? docsSource(origin),
+    ...by ? { suggestedBy: by } : {},
+    createdAt: date.toISOString(),
+    base: opts.base,
+    tier: { tier: p.risk.tier, bump: "patch" },
+    docs,
+    files,
+    checks: { newErrors: 0, contrast: [], blocked: null, impact: 0 }
+  };
+}
+async function suggestDocsOnGitHub(gh, edits, opts) {
+  if (!edits.length) throw new Error("No docs edits in the draft.");
+  const sha = opts.baseSha ?? await gh.getBranchSha(opts.base);
+  if (!sha) throw new Error(`Branch ${opts.base} not found.`);
+  const origin = opts.origin ?? DOCS_EDITOR_ORIGIN;
+  const payload = docsSuggestionPayload(edits, { base: { ref: opts.base, sha }, title: opts.title, notes: opts.notes, date: opts.date, origin, source: opts.source, suggestedBy: opts.suggestedBy });
+  const p = docsProposal(edits, { date: opts.date ?? /* @__PURE__ */ new Date(), origin });
+  const rows = p.body.split("\n").filter((l) => l.startsWith("- `"));
+  const details = [...rows, "", opts.authorLine?.trim() || defaultDocsFooter(edits, origin)].join("\n");
+  const created = await createSuggestionOnGitHub(gh, payload, { labels: ["docs", ...opts.extraLabels ?? []], details });
+  return { status: "suggested", number: created.number, url: created.url, title: payload.title, sha: created.sha, warnings: created.warnings };
+}
+async function proposeDocsOnGitHub(gh, edits, opts) {
+  if (opts.mode === "suggest") return suggestDocsOnGitHub(gh, edits, opts);
+  if (opts.continueOpen !== false && edits.length === 1) {
+    const e = edits[0];
+    const open = await findOpenDocsProposalOnGitHub(gh, { name: e.component, slug: e.slug }, opts.base).catch(() => null);
+    if (open) {
+      const sha = await continueDocsProposalOnGitHub(gh, open, e, { authorLine: opts.authorLine?.trim() || defaultDocsFooter(edits, opts.origin ?? DOCS_EDITOR_ORIGIN) });
+      return { status: "continued", number: open.number, url: open.url, branch: open.branch, title: open.title, continued: true, unchanged: !sha };
+    }
+  }
+  const p = docsProposal(edits, { title: opts.title, notes: opts.notes, date: opts.date ?? /* @__PURE__ */ new Date(), origin: opts.origin, authorLine: opts.authorLine });
+  const prTitle = titleWithJiraKey(p.title, opts.jira ?? null);
+  const branch = branchWithJiraKey(p.branch, opts.jira ?? null);
+  const mainSha = await gh.getBranchSha(opts.base);
+  if (!mainSha) throw new Error(`Branch ${opts.base} not found.`);
+  const tree = await gh.createTree(await gh.getCommitTree(mainSha), p.files.map((f) => ({ path: f.path, content: f.content })));
+  const commit = await gh.createCommit(`${prTitle}
+
+${opts.commitNote ?? "Proposed with the Bridge docs editor."}`, tree, [mainSha]);
+  await gh.createBranch(branch, commit);
+  const pr = await gh.createPullRequest({ title: prTitle, head: branch, base: opts.base, body: p.body, draft: false });
+  await gh.addLabels(pr.number, [...p.labels, ...opts.extraLabels ?? []]).catch(() => false);
+  return { status: "opened", number: pr.number, url: pr.url, branch, title: prTitle, continued: false, unchanged: false };
+}
+async function commitFileOnGitHub(gh, input) {
+  const cur = await gh.getFile(input.path, input.branch);
+  if (!cur) throw new Error(`${input.path} is not on ${input.branch}. Check the component name and the branch.`);
+  const content = input.next(cur.text);
+  if (content === cur.text) return "";
+  return gh.putFile({ path: input.path, content, branch: input.branch, message: input.message, sha: cur.sha });
+}
+
+// ../core/src/share-branch.ts
+var packageDir = (name) => `packages/${name.replace(/^@[^/]+\//, "")}/`;
+function touchesPackages(files, packages) {
+  const dirs = packages.map(packageDir);
+  return files.some((f) => dirs.some((d) => f.startsWith(d)));
+}
+function shareState(x) {
+  if (!touchesPackages(x.files, x.packages)) return { kind: "no-packages" };
+  const c = readPreviewComment(x.comment);
+  if (x.lifecycle === "merged" || x.lifecycle === "closed") {
+    const kind = x.lifecycle === "merged" ? "shipped" : "closed";
+    if (!c || !c.command || c.source === "none") return { kind, stillWorks: null, command: null };
+    return { kind, stillWorks: c.source === "pkg.pr.new" ? true : c.source === "release" ? false : null, command: c.command };
+  }
+  if (!c) return { kind: "building" };
+  if (c.sha7 && !x.headSha.startsWith(c.sha7)) return { kind: "building" };
+  if (!c.command || c.source === "none") return { kind: "failed" };
+  return { kind: "ready", command: c.command, source: c.source };
+}
+var stableCommand = (packages) => `npm i ${packages.map((p) => `${p}@latest`).join(" ")}`;
+function stateSentence(s) {
+  switch (s.kind) {
+    case "ready":
+      return null;
+    case "building":
+      return "The preview version is being prepared. It is usually ready a couple of minutes after each update to the branch.";
+    case "failed":
+      return "The preview version could not be prepared for the latest update. Update the branch to try again, or ask a developer to run it again on GitHub.";
+    case "no-packages":
+      return "This branch does not touch the library tokens or components, so there is no preview version to install.";
+    case "shipped":
+      return s.stillWorks === true ? "This branch was merged. Its preview version still installs, and products get it with the next library release." : s.stillWorks === false ? "This branch was merged, so its preview version was removed. Products get it with the next library release." : "This branch was merged. Products get it with the next library release.";
+    case "closed":
+      return s.stillWorks === true ? "This branch was closed without merging. Its preview version still installs, but it will not reach the library." : s.stillWorks === false ? "This branch was closed without merging, so its preview version was removed." : "This branch was closed without merging.";
+  }
+}
+var quote = (t) => `"${t.trim().replace(/"/g, "'")}"`;
+function shareMessage(x) {
+  const back = stableCommand(x.packages);
+  const s = x.state;
+  if (s.kind === "ready") {
+    const lasts = s.source === "pkg.pr.new" ? "This preview stays available. Each update to the change makes a new one: ask me for the latest command." : "This preview is replaced on each update to the change and removed when it ships or closes: ask me for the latest command if the install fails.";
+    return {
+      subject: `Try the design system change ${quote(x.title)} before it ships`,
+      body: [
+        "Hi,",
+        "",
+        `Could you try the design system change ${quote(x.title)} in our product before it ships?`,
+        ...x.tryUrl ? ["", `See it in the demo product first: ${x.tryUrl}`] : [],
+        "",
+        "Install the preview version in a staging branch (not production):",
+        s.command,
+        "",
+        lasts,
+        "",
+        "To go back to the stable version:",
+        back,
+        "",
+        `Details for developers: ${x.url}`
+      ].join("\n")
+    };
+  }
+  if ((s.kind === "shipped" || s.kind === "closed") && s.command) {
+    const what = s.kind === "shipped" ? `The design system change ${quote(x.title)} has shipped. You get it with the next library release.` : `The design system change ${quote(x.title)} was closed without shipping.`;
+    const preview = s.stillWorks === false ? "Its preview version was removed, so reinstalling it fails." : s.stillWorks === true ? "Its preview version still installs, but it is not the released version." : "";
+    return {
+      subject: `Design system change ${quote(x.title)} ${s.kind === "shipped" ? "has shipped" : "was closed"}`,
+      body: ["Hi,", "", [what, preview].filter(Boolean).join(" "), "", "If you installed its preview, go back to the stable version:", back, "", `Details for developers: ${x.url}`].join("\n")
+    };
+  }
+  return null;
+}
+
+// ../core/src/try-in-product.ts
+function tryInProductUrl(preview, pr, screen) {
+  const url = new URL(preview);
+  url.pathname = "/";
+  url.search = "";
+  url.searchParams.set("bridge", String(pr));
+  if (screen) {
+    url.searchParams.set("tenant", screen.tenant);
+    url.searchParams.set("theme", screen.theme);
+  }
+  url.hash = screen ? screen.route : "";
+  return url.href;
+}
+
+// ../core/src/combine-branches.ts
+var MIN_TOGETHER = 2;
+var MAX_TOGETHER = 4;
+function onlyTokens(files, tokensRoot) {
+  const root = `${tokensRoot.replace(/^\/+|\/+$/g, "")}/`;
+  return files.length > 0 && files.every((f) => f.startsWith(root) && f.endsWith(".tokens.json") || /contrast\.checks\.json$/.test(f) || f.startsWith(".changeset/"));
+}
+function tokenFilesOf(files, tokensRoot) {
+  const root = `${tokensRoot.replace(/^\/+|\/+$/g, "")}/`;
+  return files.filter((f) => f.startsWith(root) && f.endsWith(".tokens.json")).map((f) => f.slice(root.length));
+}
+var changeList = (numbers) => numbers.join(",");
+function tryTogetherUrl(admin, numbers, picks) {
+  const url = new URL(admin);
+  url.pathname = "/";
+  url.hash = "";
+  const use = encodePicks(picks);
+  url.search = `?bridge=${changeList(numbers)}${use ? `&bridge-use=${encodeURIComponent(use)}` : ""}`;
+  return url.href;
+}
+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 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(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]) };
+  await Promise.all(
+    tokenFiles.map(async (f) => {
+      const rel = tokenFilesOf([f.filename], root)[0];
+      source.base[rel] = f.status === "added" ? void 0 : await gh.readFile(f.previous_filename ?? f.filename, start);
+      source.head[rel] = f.status === "removed" ? void 0 : await gh.readFile(f.filename, pull.headSha);
+    })
+  );
+  return { number: pull.number, title: pull.title, tokens: true, edits: changeEdits(source) };
+}
+
+// ../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 mode = input.mode ?? "direct";
+  const plan = libraryBranchPlan(piece, productBranchRef(pull, product), { source: input.source, requestedBy: input.openedBy, mode });
+  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, mode === "suggest" ? "Suggesting a library change needs a GitHub token (issues: write)." : "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, { mode });
+    link = r.status === "suggested" ? { piece: piece.id, kind: "suggestion", number: r.number, url: r.url, title: plan.title, at, ...who } : { 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" || link.kind === "suggestion") {
+      const issue = await gh.getIssue(link.number);
+      await gh.updateIssue(link.number, { body: withNeededBy(issue.body, plan.neededBy) });
+      if (link.kind === "suggestion" && !issue.labels.includes(NEEDED_BY_LABEL)) await gh.addLabels(link.number, [NEEDED_BY_LABEL]);
+    } 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.`);
+  }
+  try {
+    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) });
+  } catch (err) {
+    if (mode !== "suggest") throw err;
+    warnings.push(`#${input.pr} does not list #${link.number} yet (${err.message}). Add "Library: #${link.number}" to #${input.pr} on GitHub, so this piece is not sent twice.`);
+  }
+  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: link.kind === "suggestion" ? "suggested" : "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 === "suggestion") {
+    const issue = await gh.getIssue(link.number);
+    const cached = suggestionStateFromLabels(issue.labels);
+    const s = suggestionStatus({ state: issue.state, stateReason: issue.stateReason, applied: cached === "applying", review: cached === "applying" ? void 0 : cached });
+    const status2 = linkStatus({ kind: "suggestion", status: s });
+    const lifecycle2 = s === "applied" ? "merged" : issue.state === "closed" ? "closed" : "open";
+    const behindMain2 = lifecycle2 === "merged" ? await gh.compare(product.baseRef, product.headSha).then((c) => c.behindBy, () => null) : null;
+    const preview2 = libraryPreviewState({ kind: "suggestion", lifecycle: lifecycle2, hasChanges: false, missing: null, total: null, behindMain: behindMain2, nearest });
+    return { link, piece, status: status2, preview: preview2, people: status2.people };
+  }
+  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";
@@ -5310,21 +6498,436 @@ function planTokenProposal(input) {
     ...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 };
+  return { title: input.title, summary: summary2, edits: input.edits, 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 = tokenLabels(plan, opts.labels, 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 };
+}
+var tokenLabels = (plan, before = [], after = []) => [
+  .../* @__PURE__ */ new Set([...before, `tier: ${plan.tier.tier}`, ...plan.tier.tier === 3 ? ["tokens"] : [], ...plan.tier.bump === "major" ? ["breaking"] : [], ...after])
+];
+function tokenSuggestionPayload(plan, ctx) {
+  const tokenFiles = new Set(plan.touched);
+  const files = plan.files.filter((f) => !tokenFiles.has(f.path)).map((f) => ({ path: f.path, beforeSha: null, afterSha: f.content === null ? null : gitBlobSha(f.content), content: f.content }));
+  return {
+    schema: SUGGESTION_SCHEMA,
+    kind: "token-change",
+    title: plan.title,
+    summary: plan.summary,
+    source: ctx.source,
+    ...ctx.suggestedBy ? { suggestedBy: ctx.suggestedBy.replace(/^@/, "") } : {},
+    createdAt: ctx.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    base: ctx.base,
+    tier: { tier: plan.tier.tier, bump: plan.tier.bump },
+    tokens: {
+      edits: plan.edits,
+      changes: plan.changes.map((c) => ({ kind: c.kind, path: c.path, from: c.from, file: c.file, before: c.before, after: c.after, beforeCss: c.beforeCss, afterCss: c.afterCss }))
+    },
+    ...files.length ? { files } : {},
+    checks: {
+      newErrors: plan.newErrors.length,
+      contrast: plan.contrast.map((d) => ({ pair: `${d.fg} on ${d.bg}`, mode: d.modes || void 0, before: d.before ?? 0, after: d.after ?? 0, min: d.min, pass: d.passAfter })),
+      blocked: plan.blocked,
+      impact: plan.impact.total
+    },
+    ...ctx.links ? { links: ctx.links } : {},
+    ...ctx.previews?.length ? { previews: ctx.previews } : {}
+  };
+}
+async function suggestTokenProposalOnGitHub(gh, plan, opts) {
+  if (plan.blocked) throw new Error(`Not suggested: ${plan.blocked}. Bridge never suggests a change that breaks the gate.`);
+  const sha = opts.baseSha ?? await gh.getBranchSha(opts.base);
+  if (!sha) throw new Error(`Branch ${opts.base} not found. Check the default branch in bridge.config.json.`);
+  const links = opts.neededBy || opts.links ? { ...opts.links, ...opts.neededBy ? { neededBy: opts.neededBy } : {} } : void 0;
+  const payload = tokenSuggestionPayload(plan, { base: { ref: opts.base, sha }, source: opts.source, suggestedBy: opts.suggestedBy, links, previews: opts.previews });
+  const labels = tokenLabels(plan, opts.labels, opts.labelsAfter);
+  const created = await createSuggestionOnGitHub(gh, payload, { labels, assignees: opts.assignees, details: plan.body });
+  return { status: "suggested", number: created.number, url: created.url, sha: created.sha, labels, warnings: created.warnings };
+}
+
+// ../core/src/figma-push-github.ts
+var pushSource = (d) => ["figma", "studio", "cli", "mcp"].includes(d.source) ? d.source : "figma";
+var specTier = (d) => ({ tier: 2, bump: d.kind === "new-component" || d.kind === "new-variant" || d.kind === "prop-change" ? "minor" : "patch" });
+function componentSpecSuggestionPayload(d, plan, ctx) {
+  const specPath = figmaSpecPath(d);
+  const spec = JSON.parse(formatFigmaSpec(d, plan));
+  const brief = figmaDraftBrief({ ...d, tokenEdits: plan.edits, reasons: plan.reasons }, { suggestion: true, specPath, componentsDir: ctx.componentsDir });
+  const by = (ctx.suggestedBy ?? d.requestedBy)?.replace(/^@/, "");
+  const figma = d.figma?.fileKey || d.figma?.nodeId || d.figma?.url ? { ...d.figma.fileKey ? { fileKey: d.figma.fileKey } : {}, ...d.figma.nodeId ? { nodeId: d.figma.nodeId } : {}, ...d.figma.url ? { url: d.figma.url } : {} } : void 0;
+  return {
+    schema: SUGGESTION_SCHEMA,
+    kind: "component-spec",
+    title: d.title,
+    summary: d.summary.trim() || d.title,
+    source: pushSource(d),
+    ...by ? { suggestedBy: by } : {},
+    createdAt: ctx.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    base: ctx.base,
+    tier: specTier(d),
+    componentSpec: { component: d.component, specPath, spec, brief },
+    checks: { newErrors: 0, contrast: [], blocked: null, impact: 0 },
+    ...figma ? { links: { figma } } : {}
+  };
+}
+async function openComponentPushOnGitHub(gh, input) {
+  const d = input.diff;
+  if (!input.plan && !input.tokens) throw new Error("Route the change first: pass the token facts or the plan.");
+  const plan = input.plan ?? planComponentPush(d, input.tokens);
+  if (plan.route === "manual") return { status: "not-sent", plan, link: null };
+  if (input.dryRun) return { status: "dry-run", plan, link: null };
+  const mode = input.mode ?? "direct";
+  if (!gh.canWrite) throw new GitHubError(401, mode === "suggest" ? "Suggesting a component change needs a GitHub token (issues: write)." : "Sending a component change needs a GitHub token (contents and pull requests: write).");
+  const origin = {
+    component: d.component,
+    figmaName: d.figmaName,
+    route: plan.route,
+    kind: d.kind,
+    ...d.figma?.nodeId ? { nodeId: d.figma.nodeId } : {},
+    ...d.figma?.fileKey ? { fileKey: d.figma.fileKey } : {},
+    ...d.figma?.url ? { url: d.figma.url } : {},
+    ...d.requestedBy ? { requestedBy: d.requestedBy } : {}
+  };
+  if (plan.route === "token-change") {
+    if (!input.writeTokens) throw new GitHubError(422, "This change is a token change: send it where the token files are read (the DS Bridge plugin, bridge_push_figma_component or `bridge figma push`).");
+    const figma = { ...origin.fileKey ? { fileKey: origin.fileKey } : {}, ...origin.nodeId ? { nodeId: origin.nodeId } : {}, ...origin.url ? { url: origin.url } : {} };
+    const r = await input.writeTokens({ edits: plan.edits, title: figmaBranchTitle(d), summary: d.summary.trim() || d.title, bodyExtra: [figmaOriginSection(origin)], mode, figma });
+    await gh.addLabels(r.number, [FROM_FIGMA_LABEL]);
+    if (r.status === "suggested") return { status: "suggested", plan, link: null, suggestion: { route: "token-change", number: r.number, url: r.url } };
+    return { status: "opened", plan, link: { route: "token-change", number: r.number, url: r.url, branch: r.branch } };
+  }
+  if (mode === "suggest") {
+    const sha = input.baseSha ?? await gh.getBranchSha(input.base);
+    if (!sha) throw new GitHubError(404, `Branch ${input.base} not found. Check the default branch in bridge.config.json.`);
+    const payload = componentSpecSuggestionPayload(d, plan, { base: { ref: input.base, sha }, suggestedBy: input.suggestedBy });
+    const created = await createSuggestionOnGitHub(gh, payload, { labels: [...input.labels ?? [], WAITING_FOR_CLAUDE_LABEL] });
+    return { status: "suggested", plan, link: null, suggestion: { route: "claude-draft", number: created.number, url: created.url } };
+  }
+  const spec = figmaSpecPath(d);
+  const o = { ...origin, spec, status: "spec" };
+  let branch = `${input.branchPrefix}figma-${figmaSpecSlug(d)}`;
+  for (let i = 2; await gh.getBranchSha(branch).then(Boolean, () => false); i++) branch = `${input.branchPrefix}figma-${figmaSpecSlug(d)}-${i}`;
+  await gh.commitToNewBranch({
+    base: input.base,
+    branch,
+    message: `chore(figma): spec for ${figmaBranchTitle(d)}
+
+Sent from Figma with ${input.tool ?? "the DS Bridge Figma plugin"}. Claude AI drafts the code on this branch; a person reviews it.`,
+    files: [{ path: spec, content: formatFigmaSpec(d, plan) }]
+  });
+  const pr = await gh.createPullRequest({ base: input.base, head: branch, title: figmaBranchTitle(d), body: figmaDraftBody(d, plan, o), draft: true });
+  await gh.addLabels(pr.number, [.../* @__PURE__ */ new Set([...input.labels ?? [], FROM_FIGMA_LABEL, REQUEST_LABEL, WAITING_FOR_CLAUDE_LABEL])]);
+  return { status: "opened", plan, link: { route: "claude-draft", number: pr.number, url: pr.url, branch } };
+}
+async function listFigmaChangesOnGitHub(gh, opts = {}) {
+  const pulls = await gh.listPullRequests(opts.state ?? "open");
+  const out = [];
+  for (const p of pulls) {
+    if (!p.labels.includes(FROM_FIGMA_LABEL)) continue;
+    const origin = parseFigmaOrigin(p.body);
+    if (!origin) continue;
+    out.push({ number: p.number, title: p.title, url: p.url, branch: p.headRef, origin, status: figmaPushStatus({ state: p.state, draft: p.draft, labels: p.labels, route: origin.route }) });
+  }
+  return out;
+}
+async function figmaChangeOnGitHub(gh, n, opts = {}) {
+  const pull = await gh.getPullRequest(n);
+  const origin = parseFigmaOrigin(pull.body);
+  if (!origin) throw new GitHubError(404, `#${n} was not sent from Figma (no "From Figma" block in its description).`);
+  const status = figmaPushStatus({ state: pull.state, draft: pull.draft, labels: pull.labels, route: origin.route });
+  if (origin.route === "token-change") return { pull, origin, status, spec: void 0, brief: void 0 };
+  const text = origin.spec ? await gh.getFileText(origin.spec, pull.headSha).catch(() => void 0) : void 0;
+  const spec = parseFigmaSpec(text);
+  if (!spec) throw new GitHubError(404, `The spec ${origin.spec ?? FIGMA_SPEC_DIR} is missing from ${pull.headRef}. Send the component from Figma again.`);
+  const brief = figmaDraftBrief(spec, { pr: n, branch: pull.headRef, specPath: origin.spec, componentsDir: opts.componentsDir });
+  return { pull, origin, status, spec, brief };
+}
+async function markFigmaChangeDraftedOnGitHub(gh, n) {
+  if (!gh.canWrite) throw new GitHubError(401, "Marking a branch drafted needs a GitHub token (pull requests: write).");
+  const pull = await gh.getPullRequest(n);
+  const origin = parseFigmaOrigin(pull.body);
+  if (!origin || origin.route !== "claude-draft") throw new GitHubError(422, `#${n} is not a Claude draft branch from Figma.`);
+  if (pull.state !== "open") throw new GitHubError(422, `#${n} is ${pull.state}: only an open branch is marked drafted.`);
+  const files = (await gh.listPullRequestFiles(n)).map((f) => f.filename).filter((f) => !f.startsWith(`${FIGMA_SPEC_DIR}/`));
+  if (!files.length) throw new GitHubError(422, `${pull.headRef} only carries the spec: write the component code there first, push it, then mark it drafted.`);
+  await gh.updatePullRequest(n, { body: withFigmaOrigin(pull.body, { ...origin, status: "drafted" }) });
+  await gh.removeLabel(n, WAITING_FOR_CLAUDE_LABEL).catch(() => void 0);
+  await gh.addLabels(n, [DRAFTED_BY_CLAUDE_LABEL]);
+  const labels = [...pull.labels.filter((l) => l !== WAITING_FOR_CLAUDE_LABEL), DRAFTED_BY_CLAUDE_LABEL];
+  return { status: figmaPushStatus({ state: pull.state, labels, route: origin.route }), files };
+}
+
+// ../core/src/suggestion-apply.ts
+var SUGGESTION_APPLY_EXIT = {
+  ready: 0,
+  "already-applied": 0,
+  conflict: 3,
+  "not-approved": 1,
+  blocked: 1,
+  refused: 1
+};
+var same2 = (a, b) => canonicalJson(a) === canonicalJson(b);
+var show3 = (v) => v === void 0 ? "nothing" : typeof v === "string" ? v : JSON.stringify(v);
+function tokenRoot(config) {
+  const r = config.tokens.root.replace(/\/+$/, "");
+  return r === "." ? "" : r;
+}
+function tokenFileOf(config, path) {
+  const root = tokenRoot(config);
+  if (root && !path.startsWith(`${root}/`)) return null;
+  if (!selectTokenFiles(config, [path]).length) return null;
+  return root ? path.slice(root.length + 1) : path;
+}
+function planTokenEdit(set, e, changes) {
+  const base = { type: "token", path: e.path, edit: e, ...e.file ? { file: e.file } : {} };
+  const defsAt = (path) => set.defs.filter((d) => d.path === path && (!e.file || d.file === e.file));
+  const recorded = (file, path = e.path) => changes.find((c) => c.path === path && c.file === file && (e.op === "rename" ? c.kind === "renamed" : true));
+  const conflict = (detail, extra = {}) => ({ op: { ...base, state: "conflict", detail, ...extra }, notes: [] });
+  const done = (detail) => ({ op: { ...base, state: "already-applied", detail }, notes: [] });
+  let result;
+  try {
+    result = applyTokenEdits(set, [e]);
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    switch (e.op) {
+      case "rename": {
+        const hasOld = defsAt(e.path).length > 0;
+        const hasNew = set.defs.some((d) => d.path === e.newPath);
+        if (!hasOld && hasNew) return done(`Already renamed to ${e.newPath}.`);
+        return conflict(hasOld && hasNew ? `Both ${e.path} and ${e.newPath} exist now: rename it by hand.` : `${e.path} no longer exists: ${why}`);
+      }
+      case "remove":
+        if (!defsAt(e.path).length) return done("Already removed.");
+        return conflict(why);
+      case "add": {
+        const existing = defsAt(e.path);
+        if (!existing.length) return conflict(why);
+        const want = (file) => {
+          const c = recorded(file);
+          if (c && c.after !== void 0) return c.after;
+          return coerceValue(e.value, e.type ?? existing.find((d2) => d2.file === file)?.type);
+        };
+        const all = existing.every((d2) => same2(d2.value, want(d2.file)));
+        if (all) return done("Already added with the suggested value.");
+        const d = existing.find((x) => !same2(x.value, want(x.file)));
+        return conflict(`Someone added ${e.path} with another value since.`, { file: d.file, after: want(d.file), now: d.value });
+      }
+      default:
+        return conflict(defsAt(e.path).length ? why : `${e.path} no longer exists, so its value cannot be set.`);
+    }
+  }
+  if (!result.touched.length) return done("Already has the suggested value.");
+  if (e.op === "set" || e.op === "remove" || e.op === "rename") {
+    for (const d of defsAt(e.path)) {
+      const c = recorded(d.file, e.op === "rename" ? e.newPath ?? e.path : e.path);
+      if (!c) continue;
+      const okNow = same2(d.value, c.before) || e.op === "set" && same2(d.value, c.after);
+      if (!okNow) return conflict(`${e.path} changed since it was suggested (now ${show3(d.value)}, suggested from ${show3(c.before)}).`, { file: d.file, before: c.before, after: c.after, now: d.value });
+    }
+  }
+  const verb = e.op === "set" ? "Set" : e.op === "add" ? "Add" : e.op === "remove" ? "Remove" : `Rename to ${e.newPath ?? ""}`;
+  return { op: { ...base, state: "apply", detail: `${verb} in ${result.touched.join(", ")}.` }, files: result.files, notes: result.notes };
+}
+async function planFile(ws, baseSha, f) {
+  const base = { type: "file", path: f.path };
+  const cur = await ws.read(f.path);
+  const curSha = cur?.sha ?? null;
+  const theirs = f.afterSha === null ? null : f.content ?? null;
+  if (curSha === f.afterSha) return { op: { ...base, state: "already-applied", detail: f.afterSha === null ? "Already deleted." : "Already has the suggested content." } };
+  if (curSha === f.beforeSha) return { op: { ...base, state: "apply", detail: f.afterSha === null ? "Delete it." : f.beforeSha === null ? "Create it." : "Replace it with the suggested content." }, content: theirs };
+  if (f.beforeSha === null) return { op: { ...base, state: "conflict", detail: "The suggestion creates this file, but a different one exists now." } };
+  if (!cur) return { op: { ...base, state: "conflict", detail: "The suggestion changes this file, but it was deleted since." } };
+  if (theirs === null) return { op: { ...base, state: "conflict", detail: "The suggestion deletes this file, but it changed since." } };
+  const original = await ws.readAt(baseSha, f.path);
+  if (original === null || gitBlobSha(original) !== f.beforeSha || !ws.merge) {
+    return { op: { ...base, state: "conflict", detail: original === null ? "The file changed since and its version at the suggestion base cannot be read, so it cannot be merged." : "The file changed since and cannot be merged here." } };
+  }
+  const merged = await ws.merge({ path: f.path, ours: cur.text, base: original, theirs });
+  if (!merged.clean) return { op: { ...base, state: "conflict", detail: `The file changed since and the merge has ${merged.conflicts} conflict(s).`, hunks: merged.conflicts } };
+  if (merged.text === cur.text) return { op: { ...base, state: "already-applied", detail: "Already has the suggested lines." } };
+  return { op: { ...base, state: "apply-merged", detail: "The file changed since: merged with the suggested lines, no conflict." }, content: merged.text };
+}
+async function planSuggestionApply(input) {
+  const { parsed, config, workspace: ws } = input;
+  const payload = parsed.payload;
+  const notes = [];
+  const out = (outcome, message, rest2 = {}) => ({
+    outcome,
+    exitCode: SUGGESTION_APPLY_EXIT[outcome],
+    message,
+    payloadSha: parsed.sha,
+    payload,
+    gate: null,
+    ops: [],
+    writes: [],
+    checks: null,
+    problems: [],
+    notes,
+    ...payload.componentSpec ? { brief: payload.componentSpec.brief } : {},
+    ...rest2
+  });
+  const problems = suggestionPathProblems(payload, config);
+  if (payload.checks.blocked) problems.push(`It was suggested with a failing check (${payload.checks.blocked}): ask the author to fix it and send it again.`);
+  for (const f of payload.files ?? []) {
+    if (f.afterSha !== null && typeof f.content !== "string") problems.push(`"${f.path}" has no content in the suggestion: it is incomplete, ask the author to send it again.`);
+    else if (f.afterSha !== null && gitBlobSha(f.content) !== f.afterSha) problems.push(`"${f.path}" does not match the content it was suggested with: someone edited it by hand.`);
+  }
+  if (problems.length) return out("refused", "Not applied: the suggestion asks for something Bridge never writes.", { problems: [...new Set(problems)] });
+  if (parsed.edited && !input.acceptEdited) {
+    return out("refused", 'Not applied: the suggestion was edited by hand since Bridge wrote it. Read the change, then apply it with "accept edited" if it is right.', {
+      problems: ["The payload no longer matches the sha Bridge recorded."]
+    });
+  }
+  const root = tokenRoot(config);
+  const tokenFiles = selectTokenFiles(config, await ws.list());
+  const targets = [
+    ...(payload.files ?? []).map((f) => f.path),
+    ...(payload.docs ?? []).map((d) => d.path),
+    ...payload.componentSpec ? [payload.componentSpec.specPath] : [],
+    ...payload.tokens?.edits.length ? tokenFiles.map((f) => root ? `${root}/${f}` : f) : []
+  ];
+  if (ws.isSymlink) {
+    const links = [];
+    for (const p of new Set(targets)) if (await ws.isSymlink(p)) links.push(`"${p}" is a symbolic link (or inside one): Bridge never writes through links.`);
+    if (links.length) return out("refused", "Not applied: the suggestion writes through a symbolic link.", { problems: links });
+  }
+  const governance = input.governance ?? { owners: config.governance.owners, rights: config.governance.rights ?? null };
+  const approvals = summarizeSuggestionApprovals(input.comments, governance, { payloadSha: parsed.sha, author: input.author });
+  const review = suggestionReviewState(payload.tier.tier, approvals);
+  const missing = pendingApprovals(payload.tier.tier, approvals);
+  const approved = review === "approved";
+  const gate = { review, missing, approvals, forced: !approved && Boolean(input.forceUnapproved), edited: parsed.edited };
+  const ops = [];
+  const writes = /* @__PURE__ */ new Map();
+  const current = /* @__PURE__ */ new Map();
+  for (const f of tokenFiles) {
+    const r = await ws.read(root ? `${root}/${f}` : f);
+    if (r) current.set(f, r.text);
+  }
+  const before = new LayeredTokenSet(config, current);
+  let set = before;
+  const appliedEdits = [];
+  for (const e of payload.tokens?.edits ?? []) {
+    const r = planTokenEdit(set, e, payload.tokens.changes);
+    ops.push(r.op);
+    notes.push(...r.notes);
+    if (r.op.state === "apply" && r.files) {
+      set = new LayeredTokenSet(config, r.files);
+      appliedEdits.push(e);
+    }
+  }
+  for (const [f, text] of set.files) if (text !== before.files.get(f)) writes.set(set.repoPath(f), text);
+  for (const f of payload.files ?? []) {
+    if (writes.has(f.path)) {
+      notes.push(`${f.path}: the token edits write this file, its copy in the suggestion is not used.`);
+      continue;
+    }
+    const r = await planFile(ws, payload.base.sha, f);
+    ops.push(r.op);
+    if (r.op.state === "apply" || r.op.state === "apply-merged") writes.set(f.path, r.content ?? null);
+  }
+  for (const d of payload.docs ?? []) {
+    const base = { type: "docs", path: d.path };
+    const docs = d.after;
+    let text;
+    try {
+      const issues = validateDocs(docs);
+      if (issues.length) {
+        problems.push(`${d.path}: ${issues.map((i) => i.message).join(" ")}`);
+        continue;
+      }
+      const cur = await ws.read(d.path);
+      text = docsFileText(docs, cur?.text ?? null);
+      if (cur && text === cur.text) {
+        ops.push({ ...base, state: "already-applied", detail: "The docs already say this." });
+        continue;
+      }
+      ops.push({ ...base, state: "apply", detail: cur ? "Update the changed fields; other fields stay as they are now." : "Create the docs file." });
+      writes.set(d.path, text);
+    } catch (err) {
+      problems.push(`${d.path}: the suggested docs are not a docs.json Bridge can read (${err instanceof Error ? err.message : String(err)}).`);
+    }
+  }
+  if (payload.componentSpec) {
+    const s = payload.componentSpec;
+    const text = `${JSON.stringify(s.spec, null, 2)}
+`;
+    const cur = await ws.read(s.specPath);
+    if (cur && cur.text === text) ops.push({ type: "component-spec", path: s.specPath, state: "already-applied", detail: "The spec file is already there." });
+    else {
+      ops.push({ type: "component-spec", path: s.specPath, state: "apply", detail: `Write the spec; the ${s.component} code itself is written from the brief.` });
+      writes.set(s.specPath, text);
+    }
+  }
+  const afterFiles = new Map(set.files);
+  for (const [p, content] of writes) {
+    const tf = tokenFileOf(config, p);
+    if (!tf) continue;
+    if (content === null) afterFiles.delete(tf);
+    else afterFiles.set(tf, content);
+  }
+  const after = new LayeredTokenSet(config, afterFiles);
+  const tokenChanges = diffLayered(before, after);
+  const issueKey4 = (i) => `${i.code}|${i.path ?? ""}|${i.file ?? ""}|${i.message}`;
+  const prevErrors = new Set(validateLayered(before).map(issueKey4));
+  const newErrors = tokenChanges.length ? validateLayered(after).filter((i) => i.level === "error" && !prevErrors.has(issueKey4(i))) : [];
+  let pairs = [];
+  if (config.contrast && tokenChanges.length) {
+    try {
+      pairs = parseContrastChecks((await ws.read(config.contrast.path))?.text);
+    } catch {
+      notes.push(`${config.contrast.path} does not parse: contrast was not checked.`);
+    }
+  }
+  const modes = config.contrast?.modes;
+  const contrast = pairs.length ? contrastDelta(runLayeredContrast(before, pairs, modes), runLayeredContrast(after, pairs, modes)) : [];
+  const newFailures = contrast.filter((d) => d.passBefore && !d.passAfter);
+  const otherFiles = [...writes.keys()].filter((p) => !tokenFileOf(config, p));
+  const tier = classifyRisk({ tokenChanges: tokenChanges.map((c) => ({ kind: c.kind, path: c.path, ...c.kind === "changed" ? { descriptionOnly: c.fields.length > 0 && c.fields.every((x) => x === "description") } : {} })), files: otherFiles.map((path) => ({ path })), config });
+  const tierIncreased = writes.size > 0 && tier.tier > payload.tier.tier;
+  const checks = { tierWhenSuggested: payload.tier.tier, tier, tierIncreased, newErrors, newFailures, contrast, tokenChanges };
+  const rest = { gate, ops, checks, problems };
+  if (problems.length) return out("refused", "Not applied: part of the suggestion is not valid.", rest);
+  const conflicts = ops.filter((o) => o.state === "conflict");
+  if (conflicts.length) {
+    return out("conflict", `Not applied: ${conflicts.length} change(s) conflict with the code now. Ask the author to refresh the suggestion on today's code, or apply those parts by hand.`, rest);
+  }
+  if (!writes.size) return out("already-applied", "Already applied: the code has every change of this suggestion.", rest);
+  if (newErrors.length || newFailures.length) {
+    const why = [newErrors.length ? `${newErrors.length} new validation error(s)` : "", newFailures.length ? `${newFailures.length} contrast pair(s) would fail` : ""].filter(Boolean).join(" and ");
+    return out("blocked", `Not applied: on today's code it would add ${why}. Ask the author to refresh the suggestion.`, rest);
+  }
+  if (tierIncreased && !input.forceUnapproved) {
+    return out("blocked", `Not applied: on today's code it is a tier ${tier.tier} change, it was approved as tier ${payload.tier.tier}. It needs a new approval.`, rest);
+  }
+  if (!approved && !input.forceUnapproved) {
+    const who = review === "changes-requested" ? `changes requested by ${approvals.changesRequested.map((l) => `@${l}`).join(", ")}` : `missing ${missing.map((m) => m === "approval" ? "an approval" : `${m} approval`).join(" and ")}`;
+    return out("not-approved", `Not applied: it is not approved yet (${who}). Ask the owners to review it on the issue.`, rest);
+  }
+  const forced = gate.forced || tierIncreased && Boolean(input.forceUnapproved);
+  return out("ready", `Ready: ${writes.size} file(s) to write${forced ? ", without every approval" : ""}.`, {
+    ...rest,
+    gate: { ...gate, forced },
+    writes: [...writes].map(([path, content]) => ({ path, content })).sort((a, b) => a.path.localeCompare(b.path))
+  });
 }
-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 };
+function suggestionAppliedComment(plan, where2) {
+  return composeSuggestionAppliedComment({ ...where2, payloadSha: plan.payloadSha, ...plan.gate?.forced ? { forced: true } : {} });
+}
+function suggestionApplyTable(plan) {
+  const label = { "already-applied": "already applied", apply: "apply", "apply-merged": "apply (merged)", conflict: "**conflict**" };
+  const cell4 = (s) => s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+  return ["| Change | Result | Detail |", "| --- | --- | --- |", ...plan.ops.map((o) => `| \`${cell4(o.path)}\` | ${label[o.state]} | ${cell4(o.detail)} |`)].join("\n");
 }
 
 // ../core/src/node/git-history.ts
@@ -5333,8 +6936,8 @@ var RS = "";
 function localGitHistoryBackend(root, config) {
   const trees = /* @__PURE__ */ new Map();
   const blobs = /* @__PURE__ */ new Map();
-  const tokenRoot = config.tokens.root.replace(/\/$/, "");
-  const prefix = tokenRoot === "." || !tokenRoot ? "" : `${tokenRoot}/`;
+  const tokenRoot2 = config.tokens.root.replace(/\/$/, "");
+  const prefix = tokenRoot2 === "." || !tokenRoot2 ? "" : `${tokenRoot2}/`;
   const lsTree = (sha, path) => {
     const k = `${sha}:${path}`;
     let t = trees.get(k);
@@ -5371,7 +6974,7 @@ function localGitHistoryBackend(root, config) {
       });
     },
     async tokenFiles(sha) {
-      const entries = await lsTree(sha, tokenRoot === "." ? "" : tokenRoot);
+      const entries = await lsTree(sha, tokenRoot2 === "." ? "" : tokenRoot2);
       const picked = new Set(selectTokenFiles(config, entries.map((e) => e.path)));
       const wanted = entries.filter((e) => picked.has(prefix ? e.path.slice(prefix.length) : e.path));
       return new Map(await Promise.all(wanted.map(async (e) => [prefix ? e.path.slice(prefix.length) : e.path, await blob(e.sha)])));
@@ -6001,14 +7604,14 @@ function scanClassString(text) {
   const out = [];
   for (const m of text.matchAll(/[^\s"'`]+/g)) {
     const raw = m[0];
-    let cut = -1;
+    let cut2 = -1;
     let depth = 0;
     for (let i = 0; i < raw.length; i++) {
       if (raw[i] === "[") depth++;
       else if (raw[i] === "]") depth--;
-      else if (raw[i] === ":" && depth === 0) cut = i;
+      else if (raw[i] === ":" && depth === 0) cut2 = i;
     }
-    const cls = raw.slice(cut + 1).replace(/^!/, "");
+    const cls = raw.slice(cut2 + 1).replace(/^!/, "");
     const index = m.index + raw.length - cls.length;
     const arb = /^-?([a-z][a-z-]*?)-\[(.+)\]$/.exec(cls);
     if (arb) {
@@ -6182,8 +7785,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 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 } : {} });
+    const cap3 = 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", ...cap3 ? { suggestion: cap3 } : {} });
   }
   return { findings, themeRefs };
 }
@@ -6496,16 +8099,16 @@ function applyAllowlist(entries, findings, components) {
   return { findings: keep(findings), components: keep(components), ignored, used };
 }
 function parseAllowlist(json) {
-  const fail2 = (msg) => {
+  const fail3 = (msg) => {
     throw new Error(`allowlist: ${msg}`);
   };
-  if (!json || typeof json !== "object" || !Array.isArray(json.entries)) fail2('expected { "entries": [...] }');
+  if (!json || typeof json !== "object" || !Array.isArray(json.entries)) fail3('expected { "entries": [...] }');
   return json.entries.map((e, i) => {
     const x = e;
-    if (typeof x.file !== "string" || !x.file) fail2(`entry ${i} needs "file"`);
-    if (typeof x.line !== "number" || !Number.isInteger(x.line) || x.line < 1) fail2(`entry ${i} (${x.file}) needs a "line" number`);
-    if (typeof x.reason !== "string" || !x.reason.trim()) fail2(`entry ${i} (${x.file}:${x.line}) needs a "reason"`);
-    if (x.what !== void 0 && typeof x.what !== "string") fail2(`entry ${i} (${x.file}:${x.line}): "what" must be a string`);
+    if (typeof x.file !== "string" || !x.file) fail3(`entry ${i} needs "file"`);
+    if (typeof x.line !== "number" || !Number.isInteger(x.line) || x.line < 1) fail3(`entry ${i} (${x.file}) needs a "line" number`);
+    if (typeof x.reason !== "string" || !x.reason.trim()) fail3(`entry ${i} (${x.file}:${x.line}) needs a "reason"`);
+    if (x.what !== void 0 && typeof x.what !== "string") fail3(`entry ${i} (${x.file}:${x.line}): "what" must be a string`);
     return { file: x.file, line: x.line, ...x.what !== void 0 ? { what: x.what } : {}, reason: x.reason.trim() };
   });
 }
@@ -7191,9 +8794,9 @@ var DesignSystemIndex = class {
         return generic ? this.make(generic, 1, 0.3) : void 0;
       }
       case "shadow": {
-        const norm3 = (s) => s.replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim().toLowerCase();
+        const norm4 = (s) => s.replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim().toLowerCase();
         const cands = this.entries(["shadow"]);
-        const exact = cands.find((e) => norm3(e.css) === norm3(value));
+        const exact = cands.find((e) => norm4(e.css) === norm4(value));
         if (exact) return this.make(exact, 0, 1);
         const t = shadowNums(value);
         const scored = cands.map((e) => {
@@ -7260,6 +8863,194 @@ function loadAllowlist(path) {
   return parseAllowlist(JSON.parse(readFileSync(path, "utf8")));
 }
 
+// ../core/src/node/suggestion-apply-node.ts
+import { execFile } from "node:child_process";
+import { lstat, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname as dirname2, join as join2 } from "node:path";
+function gitCode(root, args) {
+  return new Promise((resolve4) => {
+    execFile("git", args, { cwd: root, maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code2 = err ? typeof err.code === "number" ? err.code : -1 : 0;
+      resolve4({ code: code2, stdout, stderr });
+    });
+  });
+}
+async function treeEntry(root, ref, path) {
+  const r = await gitCode(root, ["ls-tree", ref, "--", path]);
+  const m = /^(\d+) (\w+) ([0-9a-f]+)\t/.exec(r.stdout);
+  return r.code === 0 && m ? { mode: m[1], type: m[2], sha: m[3] } : null;
+}
+var prefixes = (path) => path.split("/").map((_, i, segs) => segs.slice(0, i + 1).join("/"));
+async function mergeText(root, input) {
+  const dir = await mkdtemp(join2(tmpdir(), "bridge-merge-"));
+  try {
+    const [o, b, t] = ["current", "base", "suggested"].map((n) => join2(dir, n));
+    await Promise.all([writeFile(o, input.ours), writeFile(b, input.base), writeFile(t, input.theirs)]);
+    const r = await gitCode(root, ["merge-file", "-p", "-L", "current", "-L", "base", "-L", "suggested", o, b, t]);
+    if (r.code < 0 || r.code > 127) throw new Error(`git merge-file failed: ${r.stderr.trim() || `exit ${r.code}`}`);
+    return { clean: r.code === 0, text: r.stdout, conflicts: r.code };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+async function fileDiff(path, before, after) {
+  if (before === after) return "";
+  const dir = await mkdtemp(join2(tmpdir(), "bridge-diff-"));
+  try {
+    const side = async (name, text) => {
+      if (text === null) return "/dev/null";
+      const p = join2(dir, name, path);
+      await mkdir(dirname2(p), { recursive: true });
+      await writeFile(p, text);
+      return `${name}/${path}`;
+    };
+    const a = await side("a", before);
+    const b = await side("b", after);
+    const r = await new Promise((resolve4) => execFile("git", ["diff", "--no-index", "--no-color", "--src-prefix=", "--dst-prefix=", "--", a, b], { cwd: dir, maxBuffer: 32 * 1024 * 1024 }, (_e, stdout) => resolve4({ stdout })));
+    return r.stdout;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+function gitWorkspace(root, opts = {}) {
+  const { ref } = opts;
+  let fetched = false;
+  return {
+    async read(path) {
+      if (ref) {
+        const e = await treeEntry(root, ref, path);
+        if (!e || e.type !== "blob" || e.mode === "120000") return null;
+        return { text: await git(root, ["cat-file", "blob", e.sha]), sha: e.sha };
+      }
+      try {
+        const st = await lstat(join2(root, path));
+        if (!st.isFile()) return null;
+        const text = await readFile(join2(root, path), "utf8");
+        return { text, sha: gitBlobSha(text) };
+      } catch {
+        return null;
+      }
+    },
+    async readAt(at, path) {
+      if ((await gitCode(root, ["cat-file", "-e", `${at}^{commit}`])).code !== 0 && !fetched) {
+        fetched = true;
+        await gitCode(root, ["fetch", "--no-tags", "--quiet", "origin", at]);
+      }
+      const e = await treeEntry(root, at, path);
+      if (e?.type === "blob") return git(root, ["cat-file", "blob", e.sha]);
+      return opts.readBase ? opts.readBase(path, at) : null;
+    },
+    async list() {
+      if (ref) return listFilesAt(root, ref);
+      const out = await git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]);
+      const all = [...new Set(out.split("\0").filter(Boolean))];
+      const present = await Promise.all(all.map((p) => lstat(join2(root, p)).then((s) => s.isFile(), () => false)));
+      return all.filter((_, i) => present[i]);
+    },
+    async isSymlink(path) {
+      for (const p of prefixes(path)) {
+        if (ref) {
+          const e = await treeEntry(root, ref, p);
+          if (!e) return false;
+          if (e.mode === "120000") return true;
+        } else {
+          try {
+            if ((await lstat(join2(root, p))).isSymbolicLink()) return true;
+          } catch {
+            return false;
+          }
+        }
+      }
+      return false;
+    },
+    merge: (input) => mergeText(root, input)
+  };
+}
+var COMMIT_TYPE = { "token-change": "feat(tokens)", docs: "docs", "component-spec": "feat", brand: "feat(tokens)", revert: "revert", config: "chore(config)" };
+function commitMessage(plan, n) {
+  const p = plan.payload;
+  const type = `${COMMIT_TYPE[p.kind] ?? "chore"}${p.tier.bump === "major" ? "!" : ""}`;
+  return [`${type}: ${p.title.trim()}`, "", p.summary.trim(), "", `Applies Bridge suggestion #${n} (version ${plan.payloadSha.slice(0, 7)}).`].filter((l, i, a) => !(l === "" && a[i - 1] === "")).join("\n");
+}
+async function readConfigAt(ws) {
+  const text = (await ws.read(CONFIG_FILE))?.text;
+  if (!text) throw new Error(`No ${CONFIG_FILE} here: run \`bridge init\` first, or apply from the repository root.`);
+  return loadConfig(text);
+}
+async function applySuggestionLocally(input) {
+  const mode = input.mode ?? "branch";
+  const base = input.base ?? "HEAD";
+  const { root } = input;
+  const wsOpts = { readBase: input.readBase };
+  const ws = gitWorkspace(root, mode === "write" ? wsOpts : { ...wsOpts, ref: base });
+  const config = input.config ?? await readConfigAt(ws);
+  const planFor = (workspace) => planSuggestionApply({ ...input, config, workspace });
+  const plan = await planFor(ws);
+  const at = (input.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
+  const result = (status, rest = {}) => ({ status, exitCode: plan.exitCode, message: plan.message, plan, ...rest });
+  if (plan.outcome !== "ready") return result(plan.outcome);
+  const readNow = async (path) => (await ws.read(path))?.text ?? null;
+  const diffOf = async () => (await Promise.all(plan.writes.map(async (w) => fileDiff(w.path, await readNow(w.path), w.content)))).join("");
+  if (input.dryRun) return result("dry-run", { message: `Dry run: ${plan.message.replace(/^Ready: /, "")} Nothing written.`, diff: await diffOf() });
+  if (mode === "patch") {
+    const { sha } = await commitTree(root, { base, message: commitMessage(plan, input.number), files: plan.writes });
+    const patch = await git(root, ["format-patch", "-1", "--stdout", sha]);
+    return result("patch", { message: "Patch ready: apply it with `git am`.", patch, commit: sha });
+  }
+  if (mode === "write") {
+    const paths = plan.writes.map((w) => w.path);
+    const dirty = (await git(root, ["status", "--porcelain", "-z", "--", ...paths])).split("\0").filter((l) => l.length > 3).map((l) => l.slice(3));
+    if (dirty.length) {
+      return result("refused", {
+        exitCode: 1,
+        message: `Not written: these files have uncommitted changes: ${dirty.join(", ")}. Commit or stash them, or apply on a branch instead.`
+      });
+    }
+    const diff = await diffOf();
+    for (const w of plan.writes) {
+      const full = join2(root, w.path);
+      if (w.content === null) await rm(full, { force: true });
+      else {
+        await mkdir(dirname2(full), { recursive: true });
+        await writeFile(full, w.content);
+      }
+    }
+    return result("written", {
+      message: `Written: ${paths.length} file(s) in the working tree. Review them, commit, and say "Closes #${input.number}" in the pull request.`,
+      written: paths,
+      diff,
+      appliedComment: suggestionAppliedComment(plan, { by: input.by, at })
+    });
+  }
+  const prefix = config.governance.branchPrefix;
+  const wanted = input.branch ?? `${prefix}suggestion-${input.number}-${slugify(plan.payload.title, 40)}`;
+  let branch = wanted;
+  for (let i = 2; await branchExists(root, branch); i++) {
+    const there = await planFor(gitWorkspace(root, { ...wsOpts, ref: branch }));
+    if (there.outcome === "already-applied") {
+      const commit = (await git(root, ["rev-parse", `refs/heads/${branch}`])).trim();
+      return result("branch-exists", {
+        exitCode: 0,
+        message: `Already on ${branch}: that branch has every change of this suggestion. Push it and open a pull request that says "Closes #${input.number}".`,
+        branch,
+        commit,
+        appliedComment: suggestionAppliedComment(plan, { by: input.by, branch, commit, at })
+      });
+    }
+    branch = `${wanted}-${i}`;
+  }
+  const protectedBranches = [.../* @__PURE__ */ new Set([...protectedBranchesOf(config), baseBranchOf(config)])];
+  const res = await commitToNewLocalBranch(root, { base, branch, message: commitMessage(plan, input.number), files: plan.writes, protectedBranches, branchPrefix: prefix });
+  return result("branch-created", {
+    message: `Applied on ${branch}, your working tree is untouched. Push it and open a pull request that says "Closes #${input.number}".`,
+    branch,
+    commit: res.sha,
+    diff: res.diff,
+    appliedComment: suggestionAppliedComment(plan, { by: input.by, branch, commit: res.sha, at })
+  });
+}
+
 // src/config.ts
 var SCHEMA_URL = "https://raw.githubusercontent.com/peterbono/ai-design-system-demo/main/packages/core/bridge.config.schema.json";
 var TIER_NAMES = {
@@ -7419,10 +9210,10 @@ var core = {
 };
 
 // src/source.ts
-import { readdir, readFile } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { readdir, readFile as readFile2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
 var SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", "coverage", "storybook-static", ".turbo", ".next", ".astro"]);
-var under = (prefix) => (f) => !prefix || prefix === "." || f === prefix || f.startsWith(`${prefix.replace(/\/$/, "")}/`);
+var under2 = (prefix) => (f) => !prefix || prefix === "." || f === prefix || f.startsWith(`${prefix.replace(/\/$/, "")}/`);
 var LocalSource = class {
   constructor(root) {
     this.root = root;
@@ -7438,7 +9229,7 @@ var LocalSource = class {
     const walk2 = async (rel) => {
       let entries;
       try {
-        entries = await readdir(join2(this.root, rel), { withFileTypes: true });
+        entries = await readdir(join3(this.root, rel), { withFileTypes: true });
       } catch {
         return;
       }
@@ -7454,7 +9245,7 @@ var LocalSource = class {
   }
   async read(path) {
     try {
-      return await readFile(join2(this.root, path), "utf8");
+      return await readFile2(join3(this.root, path), "utf8");
     } catch {
       return null;
     }
@@ -7474,7 +9265,7 @@ var GitRefSource = class {
   }
   async list(prefix = "") {
     this.files ??= listFilesAt(this.root, this.ref);
-    return (await this.files).filter(under(prefix));
+    return (await this.files).filter(under2(prefix));
   }
   read(path) {
     return showFile(this.root, this.ref, path);
@@ -7495,7 +9286,7 @@ var GitHubSource = class {
   }
   async list(prefix = "") {
     this.tree ??= this.client.listFiles(this.ref);
-    return (await this.tree).filter(under(prefix));
+    return (await this.tree).filter(under2(prefix));
   }
   read(path) {
     let p = this.cache.get(path);
@@ -7517,7 +9308,7 @@ function client(repo, o, rules) {
     ...o.rawUrl ? { rawUrl: o.rawUrl } : {},
     protectedBranches: rules.protectedBranches,
     branchPrefix: rules.branchPrefix,
-    tokenHint: "set GITHUB_TOKEN (or BRIDGE_GITHUB_TOKEN) in the environment of the Bridge MCP server, read access to this repository is enough"
+    tokenHint: "set GITHUB_TOKEN (or BRIDGE_GITHUB_TOKEN) in the environment of the Bridge MCP server: read access to this repository is enough to read, suggestions and requests need Issues: read and write, and direct changes (branches and pull requests) need Contents and Pull requests: read and write"
   });
 }
 var BridgeContext = class _BridgeContext {
@@ -7939,8 +9730,8 @@ __export(ops_exports, {
   visualImpact: () => visualImpact
 });
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-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";
+import { mkdir as mkdir3, writeFile as writeFile3, access } from "node:fs/promises";
+import { dirname as dirname4, isAbsolute, join as join5, resolve as resolve3 } from "node:path";
 
 // ../core/src/audit/missing-pieces.ts
 var lines = (text) => text.split(/\r?\n/);
@@ -8012,7 +9803,7 @@ 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, "");
+var norm3 = (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) };
@@ -8099,7 +9890,7 @@ function missingPieces(input) {
         variants.set(key2, v);
         continue;
       }
-      const key = `${finding.category}|${norm2(finding)}`;
+      const key = `${finding.category}|${norm3(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);
@@ -8117,13 +9908,13 @@ function missingPieces(input) {
       foreign.set(c.name, e);
     }
   }
-  const where = (hits) => hits.slice(0, 5).map((h) => ({ file: h.file, line: h.line }));
+  const where2 = (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);
+      if (!values.some((x) => x.category === pv.category && x.property === pv.property && norm3(x) === norm3(pv))) values.push(pv);
     }
     const aspect = aspectOf(values);
     const bg = v.hits.find((h) => /background/.test(h.finding.property ?? ""))?.finding.suggestion;
@@ -8139,7 +9930,7 @@ function missingPieces(input) {
       aspect,
       values,
       ...nearest ? { nearest } : {},
-      where: where(v.hits)
+      where: where2(v.hits)
     });
   }
   for (const [name, e] of foreign) {
@@ -8151,7 +9942,7 @@ function missingPieces(input) {
       name,
       component: name.split(".").pop(),
       values: [],
-      where: where(e.hits)
+      where: where2(e.hits)
     });
   }
   for (const t of tokens.values()) {
@@ -8168,7 +9959,7 @@ function missingPieces(input) {
       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),
+      where: where2(t.hits),
       token: { path, type: TOKEN_TYPE[t.category] ?? "dimension", value: t.value, files: tokenFiles }
     });
   }
@@ -8319,8 +10110,8 @@ __export(explorations_exports, {
   toExplorationBranch: () => toExplorationBranch,
   writeToExploration: () => writeToExploration
 });
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname as dirname2, join as join3 } from "node:path";
+import { mkdir as mkdir2, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname3, join as join4 } from "node:path";
 
 // src/branches.ts
 var branches_exports = {};
@@ -8476,19 +10267,19 @@ async function whatNeedsMe(ctx, a = {}) {
   const pulls = await gh.listPullRequests("open");
   const queue = reviewQueue(pulls.map((p) => ({ ...p, state: p.state, head: { ref: p.headRef }, user: { login: p.author }, labels: p.labels.map((name) => ({ name })) }))).slice(0, a.limit ?? 20);
   const who = await people(gh, config);
-  const same2 = (x, y) => Boolean(y && x.toLowerCase() === y.toLowerCase());
+  const same3 = (x, y) => Boolean(y && x.toLowerCase() === y.toLowerCase());
   const rows = await Promise.all(
     queue.map(async (p) => {
       const f = await branchFacts(ctx, gh, p.number, viewer).catch(() => null);
-      if (!f) return { pr: p.number, title: p.title, url: p.url, author: p.author, status: "unknown", statusLabel: STATUS_WORDS.unknown, yours: same2(p.author, viewer), needsYou: null };
-      const mine = same2(p.author, viewer);
-      const inDesign = viewer ? who.lists.design.some((x) => same2(x, viewer)) : false;
-      const inTech = viewer ? who.lists.tech.some((x) => same2(x, viewer)) : false;
+      if (!f) return { pr: p.number, title: p.title, url: p.url, author: p.author, status: "unknown", statusLabel: STATUS_WORDS.unknown, yours: same3(p.author, viewer), needsYou: null };
+      const mine = same3(p.author, viewer);
+      const inDesign = viewer ? who.lists.design.some((x) => same3(x, viewer)) : false;
+      const inTech = viewer ? who.lists.tech.some((x) => same3(x, viewer)) : false;
       let needsYou = null;
       if (viewer && !mine) {
         if (f.status === "needs-design" && inDesign) needsYou = "Your design approval";
         else if (f.status === "needs-tech" && inTech) needsYou = "Your tech approval";
-        else if (f.status === "needs-approval" && !f.approvals.approvers.some((x) => same2(x, viewer))) needsYou = "Your approval";
+        else if (f.status === "needs-approval" && !f.approvals.approvers.some((x) => same3(x, viewer))) needsYou = "Your approval";
         else if (f.status === "ready" && f.gate.canShip) needsYou = "Ready for you to merge";
       }
       if (viewer && mine) {
@@ -8945,11 +10736,11 @@ async function writeToExploration(ctx, branch, input) {
     };
   }
   for (const f of input.files) {
-    const abs = join3(ctx.root, f.path);
-    if (f.content === null) await rm(abs, { force: true });
+    const abs = join4(ctx.root, f.path);
+    if (f.content === null) await rm2(abs, { force: true });
     else {
-      await mkdir(dirname2(abs), { recursive: true });
-      await writeFile(abs, f.content);
+      await mkdir2(dirname3(abs), { recursive: true });
+      await writeFile2(abs, f.content);
     }
   }
   const paths = input.files.map((f) => f.path);
@@ -8960,6 +10751,379 @@ async function writeToExploration(ctx, branch, input) {
   };
 }
 
+// src/suggestions.ts
+var suggestions_exports = {};
+__export(suggestions_exports, {
+  SUGGEST_RIGHTS: () => SUGGEST_RIGHTS,
+  appliedNext: () => appliedNext,
+  applySuggestionOp: () => applySuggestionOp,
+  changesFor: () => changesFor,
+  createSuggestionOp: () => createSuggestionOp,
+  fileSuggestion: () => fileSuggestion,
+  filesSuggestionPayload: () => filesSuggestionPayload,
+  getSuggestionOp: () => getSuggestionOp,
+  githubWorkspace: () => githubWorkspace,
+  linkSuggestionOp: () => linkSuggestionOp,
+  listSuggestionsOp: () => listSuggestionsOp,
+  noSuggestionAccess: () => noSuggestionAccess,
+  reviewSuggestionOp: () => reviewSuggestionOp,
+  suggestionBase: () => suggestionBase,
+  suggestionGovernance: () => suggestionGovernance,
+  suggestionNumber: () => suggestionNumber
+});
+var SUGGEST_RIGHTS = "Issues: read and write (Contents: read is enough)";
+async function changesFor(ctx, explicit) {
+  if (explicit === "suggest" || explicit === "direct") return explicit;
+  const { config } = await ctx.config();
+  return changesMode(config);
+}
+var appliedNext = (n) => `The owners review it on the issue (bridge_review_suggestion, or Bridge Studio). Once approved, a developer applies it: \`bridge apply ${n}\` in the repo, or in Claude Code with the Bridge MCP server, "Apply Bridge suggestion #${n}" (bridge_apply_suggestion).`;
+function noSuggestionAccess(ctx, gh) {
+  const local = ctx.mode === "local" && ctx.isGit ? ', or pass changes "direct" (the CLI: --direct) to commit it on a new local branch instead' : "";
+  if (!gh) return `Nothing sent: a suggestion is a GitHub issue and no GitHub repo is known. Set "repo" in ${CONFIG_FILE} or add an origin remote${local}.`;
+  return `Nothing sent: a suggestion is a GitHub issue, which needs a GitHub token with ${SUGGEST_RIGHTS} on ${gh.fullName}. Set GITHUB_TOKEN (or BRIDGE_GITHUB_TOKEN)${local}.`;
+}
+async function suggestionBase(ctx, gh, config) {
+  const ref = ctx.ref ?? baseBranchOf(config);
+  if (ctx.mode === "local" && ctx.isGit && ctx.root) {
+    const sha2 = (await git(ctx.root, ["rev-parse", "HEAD"]).catch(() => "")).trim();
+    if (/^[0-9a-f]{40}$/.test(sha2)) return { ref: baseBranchOf(config), sha: sha2 };
+  }
+  const sha = await gh.getBranchSha(ref);
+  if (!sha) throw new Error(`Branch ${ref} not found on ${gh.fullName}. Check the default branch in ${CONFIG_FILE}.`);
+  return { ref, sha };
+}
+async function filesSuggestionPayload(ctx, input) {
+  const files = await Promise.all(
+    input.files.map(async (f) => {
+      const now = await ctx.source.read(f.path);
+      return { path: f.path, beforeSha: now === null ? null : gitBlobSha(now), afterSha: f.content === null ? null : gitBlobSha(f.content), content: f.content };
+    })
+  );
+  return {
+    schema: SUGGESTION_SCHEMA,
+    kind: input.kind,
+    title: input.title,
+    summary: input.summary.trim() || input.title,
+    source: input.source,
+    ...input.suggestedBy ? { suggestedBy: input.suggestedBy.replace(/^@/, "") } : {},
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    base: input.base,
+    tier: input.tier,
+    files,
+    checks: { newErrors: 0, contrast: [], blocked: null, impact: 0, ...input.checks }
+  };
+}
+async function fileSuggestion(ctx, build, opts = {}) {
+  const { config } = await ctx.config();
+  const gh = await ctx.github();
+  if (opts.dryRun) {
+    const base2 = gh ? await suggestionBase(ctx, gh, config).catch(() => ({ ref: baseBranchOf(config), sha: "0000000" })) : { ref: baseBranchOf(config), sha: "0000000" };
+    const payload2 = await build(base2, null);
+    const issue = composeSuggestionIssue(payload2, { labels: [...config.governance.labels, ...opts.labels ?? []], details: opts.details, repo: gh?.fullName });
+    return { status: "dry-run", suggestion: { title: issue.title, labels: issue.labels, body: issue.body, parts: issue.parts.length } };
+  }
+  if (!gh || !ctx.canWriteRemote) return { status: "preview", message: noSuggestionAccess(ctx, gh) };
+  const base = await suggestionBase(ctx, gh, config);
+  const viewer = await viewerOf(ctx, gh);
+  const payload = await build(base, viewer);
+  const problems = suggestionPathProblems(payload, config);
+  if (problems.length) throw new Error(`Not suggested: ${problems.join(" ")}`);
+  const labels = [.../* @__PURE__ */ new Set([...config.governance.labels, ...opts.labels ?? []])];
+  const created = await createSuggestionOnGitHub(gh, payload, { labels, details: opts.details, assignees: config.integrations?.requests?.assignees ?? [] });
+  return { status: "suggested", number: created.number, url: created.url, sha: created.sha, labels, warnings: created.warnings, next: appliedNext(created.number) };
+}
+function suggestionNumber(input) {
+  if (typeof input === "number" && Number.isInteger(input) && input > 0) return input;
+  const m = /^#?(\d+)$/.exec(String(input).trim()) ?? /\/issues\/(\d+)/.exec(String(input));
+  if (!m) throw new Error(`"${input}" is not a suggestion number. Pass the issue number (42 or "#42") or its link.`);
+  return Number(m[1]);
+}
+async function suggestionGovernance(ctx, gh) {
+  const { config: here } = await ctx.config();
+  let config = here;
+  try {
+    const text = await gh.readFile(CONFIG_FILE, baseBranchOf(here));
+    if (text) config = loadConfig(text);
+  } catch {
+  }
+  const { owners, rights } = config.governance;
+  const hasTeams = [...owners.design, ...owners.tech].some((o) => o.includes("/"));
+  const teams = hasTeams ? await new TeamDirectory(gh).resolve(owners).catch(() => void 0) : void 0;
+  return { config, gov: { owners, rights: rights ?? null, ...teams ? { teams } : {} } };
+}
+var OPEN_STATUSES = ["needs-review", "changes-requested", "approved", "applying", "outdated"];
+async function listSuggestionsOp(ctx, a = {}) {
+  const gh = await reader(ctx);
+  const status = a.status ?? "all";
+  const state = a.state ?? (status === "all" ? "open" : OPEN_STATUSES.includes(status) ? "open" : "closed");
+  let rows = await listSuggestionsOnGitHub(gh, { state, perPage: 100 });
+  if (status !== "all") rows = rows.filter((r) => r.status === status);
+  if (a.kind) rows = rows.filter((r) => r.kind === a.kind);
+  const total = rows.length;
+  rows = rows.slice(0, a.limit ?? 100);
+  const approved = rows.filter((r) => r.status === "approved");
+  return {
+    repo: gh.fullName,
+    label: SUGGESTION_LABEL,
+    state,
+    status,
+    total,
+    suggestions: rows.map((r) => ({
+      number: r.number,
+      title: r.title,
+      kind: r.kind ?? null,
+      tier: r.tier ?? null,
+      status: r.status,
+      said: SUGGESTION_STATUS_LABEL[r.status],
+      author: r.author,
+      url: r.url,
+      linkedPrs: r.linkedPrs
+    })),
+    next: approved.length ? `Ready to apply: ${approved.map((r) => `#${r.number}`).join(", ")}. Apply one with bridge_apply_suggestion { number } (dry run first), or \`bridge apply <n>\`.` : rows.length ? "Read one with bridge_get_suggestion { number }: its change, checks and who still has to approve it. Statuses come from labels here; bridge_get_suggestion counts the approvals." : "No suggestion matches."
+  };
+}
+var roleText = (m) => m === "approval" ? "one approval" : `${m} approval`;
+async function getSuggestionOp(ctx, a) {
+  const n = suggestionNumber(a.number);
+  const gh = await reader(ctx);
+  const { gov } = await suggestionGovernance(ctx, gh);
+  const d = await getSuggestionOnGitHub(gh, n, gov);
+  const base = { number: n, url: d.issue.url, title: d.issue.title, state: d.issue.state, status: d.status, said: SUGGESTION_STATUS_LABEL[d.status], author: d.issue.author, labels: d.issue.labels, linkedPrs: d.linkedPrs };
+  if (!d.parsed.ok) {
+    if (!d.issue.labels.includes(SUGGESTION_LABEL) && d.parsed.reason === "no-block") throw new Error(`Issue #${n} is not a Bridge suggestion: it has no "${SUGGESTION_LABEL}" label and no suggestion block.`);
+    return { ...base, problem: d.parsed.message, next: "Ask the author to send it again from Bridge." };
+  }
+  const p = d.parsed.payload;
+  const approvals = d.approvals;
+  const missing = pendingApprovals(p.tier.tier, approvals);
+  return {
+    ...base,
+    kind: p.kind,
+    summary: p.summary,
+    source: p.source,
+    ...p.suggestedBy ? { suggestedBy: p.suggestedBy } : {},
+    createdAt: p.createdAt,
+    base: p.base,
+    tier: p.tier.tier,
+    bump: p.tier.bump,
+    version: d.parsed.sha.slice(0, 7),
+    payloadSha: d.parsed.sha,
+    ...d.parsed.edited ? { edited: "The machine-readable block was edited by hand after Bridge wrote it. Applying it needs acceptEdited (the CLI: --accept-edited) once you checked it." } : {},
+    change: {
+      ...p.tokens ? { tokens: p.tokens.changes.length ? p.tokens.changes.map((c) => ({ kind: c.kind, path: c.path, ...c.from ? { from: c.from } : {}, file: c.file, before: c.beforeCss ?? c.before, after: c.afterCss ?? c.after })) : p.tokens.edits } : {},
+      ...p.docs ? { docs: p.docs.map((x) => ({ component: x.component, path: x.path })) } : {},
+      ...p.componentSpec ? { componentSpec: { component: p.componentSpec.component, specPath: p.componentSpec.specPath } } : {},
+      ...p.files?.length ? { files: p.files.map((f) => ({ path: f.path, change: f.beforeSha === null ? "new" : f.afterSha === null ? "deleted" : "changed" })) } : {}
+    },
+    checks: p.checks,
+    ...p.links ? { links: p.links } : {},
+    ...p.previews?.length ? { previews: p.previews } : {},
+    approvals: {
+      approvedBy: approvals.approvers,
+      missing: missing.map(roleText),
+      changesRequestedBy: approvals.changesRequested,
+      ...approvals.stale.length ? { staleReviews: approvals.stale } : {},
+      ...approvals.ignored.length ? { notCounted: approvals.ignored } : {}
+    },
+    applied: d.applied,
+    ...p.componentSpec ? { brief: p.componentSpec.brief } : {},
+    next: d.status === "approved" ? `Approved. Apply it: bridge_apply_suggestion { number: ${n}, mode: "dry-run" } first, then mode "branch" (or \`bridge apply ${n}\`). The pull request must say "Closes #${n}".` : d.status === "needs-review" ? `Waiting for ${missing.map(roleText).join(" and ") || "a review"} from the owners in ${CONFIG_FILE}: bridge_review_suggestion { number: ${n}, event: "approve" }.` : d.status === "changes-requested" ? "Changes requested: the author sends a new version (approvals then start again)." : d.status === "applying" ? `Being applied${d.linkedPrs.length ? ` in ${d.linkedPrs.map((x) => `#${x.number}`).join(", ")}` : ""}. It closes when the pull request merges.` : d.status === "outdated" ? "Outdated: the code changed since it was suggested. Ask the author to refresh it." : `${SUGGESTION_STATUS_LABEL[d.status]}: nothing to do.`
+  };
+}
+async function reviewSuggestionOp(ctx, a) {
+  const n = suggestionNumber(a.number);
+  const gh = await writer(ctx, "Reviewing a suggestion", "Issues: read and write");
+  const { gov } = await suggestionGovernance(ctx, gh);
+  const viewer = await viewerOf(ctx, gh);
+  if (a.event === "decline") {
+    if (!a.message?.trim()) throw new Error("Say why it is declined, in a sentence: the author reads it.");
+    if (a.payloadSha) {
+      const d = await getSuggestionOnGitHub(gh, n, gov);
+      if (d.parsed.ok && !d.parsed.sha.startsWith(a.payloadSha)) throw new Error(`#${n} changed since you read it. Read it again (bridge_get_suggestion) before declining.`);
+    }
+    const r2 = await declineSuggestionOnGitHub(gh, n, a.message.trim(), viewer);
+    return { number: n, status: "declined", said: SUGGESTION_STATUS_LABEL.declined, ...r2.warnings.length ? { warnings: r2.warnings } : {}, next: "Closed as not planned, with your reason. Reopen it on GitHub to look at it again." };
+  }
+  if (a.event !== "comment" && viewer) {
+    const lists = approverLists(gov.owners, gov.rights ?? null, gov.teams ?? void 0);
+    const owners = [...lists.design, ...lists.tech].map((l) => l.toLowerCase().replace(/^@/, ""));
+    if (owners.length && !owners.includes(viewer.toLowerCase())) {
+      throw new Error(`Only the owners in ${CONFIG_FILE} approve or request changes on suggestions, and @${viewer} is not one. Comment instead (event "comment"), or ask an owner.`);
+    }
+  }
+  const payloadSha = a.payloadSha && /^[0-9a-f]{64}$/.test(a.payloadSha) ? a.payloadSha : void 0;
+  if (a.payloadSha && !payloadSha) {
+    const d = await getSuggestionOnGitHub(gh, n, gov);
+    if (d.parsed.ok && !d.parsed.sha.startsWith(a.payloadSha)) throw new Error(`#${n} changed since you read it. Read it again (bridge_get_suggestion) and review the new version.`);
+  }
+  const r = await reviewSuggestionOnGitHub(gh, n, { event: a.event, role: a.role, message: a.message, payloadSha, ...viewer ? { by: viewer } : {} }, gov);
+  return {
+    number: n,
+    event: a.event,
+    counts: r.counts,
+    version: r.payloadSha.slice(0, 7),
+    status: r.status,
+    said: SUGGESTION_STATUS_LABEL[r.status],
+    comment: r.commentUrl,
+    ...r.warnings.length ? { warnings: r.warnings } : {},
+    next: r.status === "approved" ? `Approved: a developer applies it with \`bridge apply ${n}\` or bridge_apply_suggestion.` : r.status === "changes-requested" ? "The author sends a new version; approvals start again on it." : "Waiting for the other approvals."
+  };
+}
+function githubWorkspace(gh, ref) {
+  let files;
+  return {
+    read: async (path) => await gh.getFile(path, ref) ?? null,
+    readAt: async (sha, path) => await gh.readFile(path, sha).catch(() => void 0) ?? null,
+    list: () => files ??= gh.listFiles(ref)
+  };
+}
+var MAX_DIFF = 12e3;
+var cut = (s) => s && s.length > MAX_DIFF ? `${s.slice(0, MAX_DIFF)}
+... (truncated)` : s;
+function planFacts(plan) {
+  return {
+    outcome: plan.outcome,
+    exitCode: plan.exitCode,
+    version: plan.payloadSha.slice(0, 7),
+    table: suggestionApplyTable(plan),
+    ...plan.problems.length ? { problems: plan.problems } : {},
+    ...plan.notes.length ? { notes: plan.notes } : {},
+    ...plan.gate ? { approvals: { review: plan.gate.review, missing: plan.gate.missing.map(roleText), forced: plan.gate.forced, edited: plan.gate.edited } } : {},
+    ...plan.checks ? {
+      checks: {
+        tier: plan.checks.tier.tier,
+        tierWhenSuggested: plan.checks.tierWhenSuggested,
+        tierIncreased: plan.checks.tierIncreased,
+        newErrors: plan.checks.newErrors.length,
+        newContrastFailures: plan.checks.newFailures.map((f) => `${f.fg} on ${f.bg}${f.modes ? ` (${f.modes})` : ""}`)
+      }
+    } : {},
+    ...plan.brief ? { brief: plan.brief } : {}
+  };
+}
+async function applySuggestionOp(ctx, a) {
+  const n = suggestionNumber(a.number);
+  const gh = await reader(ctx);
+  const { config, gov } = await suggestionGovernance(ctx, gh);
+  const d = await getSuggestionOnGitHub(gh, n, gov);
+  if (!d.parsed.ok) {
+    if (!d.issue.labels.includes(SUGGESTION_LABEL) && d.parsed.reason === "no-block") throw new Error(`Issue #${n} is not a Bridge suggestion: it has no "${SUGGESTION_LABEL}" label and no suggestion block.`);
+    return { number: n, status: "refused", outcome: "refused", exitCode: 1, message: `Not applied: ${d.parsed.message}` };
+  }
+  if (d.status === "declined") return { number: n, status: "refused", outcome: "refused", exitCode: 1, message: `Not applied: #${n} was declined. Reopen it on GitHub first if it should go in after all.` };
+  const parsed = d.parsed;
+  const dryRun = a.dryRun || a.mode === "dry-run";
+  const mode = a.mode && a.mode !== "dry-run" ? a.mode : "branch";
+  const common = { parsed, comments: d.comments, governance: gov, author: d.issue.author || null, acceptEdited: a.acceptEdited, forceUnapproved: a.forceUnapproved };
+  if (ctx.mode !== "local" || !ctx.isGit || !ctx.root) {
+    const ref = ctx.ref ?? baseBranchOf(config);
+    const plan = await planSuggestionApply({ ...common, config, workspace: githubWorkspace(gh, ref) });
+    return {
+      number: n,
+      status: plan.outcome === "ready" ? "planned" : plan.outcome,
+      message: plan.message,
+      ...planFacts(plan),
+      ...plan.outcome === "ready" ? { files: plan.writes } : {},
+      next: plan.outcome === "ready" ? `Bridge reads ${gh.fullName} over the API and writes nothing here. Write these files on a new branch, commit, push, and open a pull request whose body says "Closes #${n}", then bridge_link_suggestion { number: ${n}, pr }.` : plan.message
+    };
+  }
+  const viewer = await viewerOf(ctx, gh);
+  const r = await applySuggestionLocally({
+    ...common,
+    root: ctx.root,
+    number: n,
+    mode,
+    dryRun,
+    ...a.base ? { base: a.base } : {},
+    ...a.branch ? { branch: a.branch } : {},
+    ...viewer ? { by: viewer } : {},
+    readBase: async (path, sha) => await gh.readFile(path, sha).catch(() => void 0) ?? null
+  });
+  let recorded = false;
+  const warnings = [];
+  if (r.appliedComment && !dryRun && (r.status === "branch-created" || r.status === "written" || r.status === "branch-exists")) {
+    if (ctx.canWriteRemote) {
+      try {
+        await gh.addComment(n, r.appliedComment);
+        recorded = true;
+        const w = await syncSuggestionStateLabel(gh, n, d.issue.labels, "applying");
+        if (w) warnings.push(w);
+      } catch (e) {
+        warnings.push(`#${n} does not say it is being applied yet (${e.message}). It will once the pull request says "Closes #${n}".`);
+      }
+    } else warnings.push(`#${n} does not say it is being applied: that needs a GitHub token with Issues write. It will once the pull request says "Closes #${n}".`);
+  }
+  const next = r.status === "dry-run" ? `Nothing written. Apply it: bridge_apply_suggestion { number: ${n}, mode: "branch" } (or "write" for the working tree, "patch" for a patch).` : r.status === "branch-created" || r.status === "branch-exists" ? `Push ${r.branch} (git push -u origin ${r.branch}) and open a pull request whose body says "Closes #${n}", then bridge_link_suggestion { number: ${n}, pr }.` : r.status === "written" ? `Review the files, commit them on a branch, push, and open a pull request whose body says "Closes #${n}", then bridge_link_suggestion { number: ${n}, pr }.` : r.status === "patch" ? `Apply the patch with \`git am\` on a branch, then open a pull request whose body says "Closes #${n}".` : r.message;
+  return {
+    number: n,
+    status: r.status,
+    mode: dryRun ? "dry-run" : mode,
+    message: r.message,
+    ...planFacts(r.plan),
+    exitCode: r.exitCode,
+    ...r.branch ? { branch: r.branch } : {},
+    ...r.commit ? { commit: r.commit } : {},
+    ...r.written ? { written: r.written } : {},
+    ...r.patch ? { patch: r.patch } : {},
+    ...r.diff ? { diff: cut(r.diff) } : {},
+    recorded,
+    ...warnings.length ? { warnings } : {},
+    next
+  };
+}
+async function linkSuggestionOp(ctx, a) {
+  const n = suggestionNumber(a.number);
+  const gh = await writer(ctx, "Linking a suggestion", "Issues: read and write");
+  if (!a.pr && !a.branch && !a.commit) throw new Error("Say where it is applied: pr (the pull request number), branch or commit.");
+  const { gov } = await suggestionGovernance(ctx, gh);
+  const d = await getSuggestionOnGitHub(gh, n, gov);
+  if (!d.parsed.ok) throw new Error(`#${n} cannot be linked: ${d.parsed.message}`);
+  const warnings = [];
+  let branch = a.branch;
+  if (a.pr) {
+    const pr = await gh.getPullRequest(a.pr);
+    branch ??= pr.headRef;
+    if (!closingIssueNumbers(pr.body).includes(n)) warnings.push(`#${a.pr} does not say "Closes #${n}": add it to the pull request description, so the suggestion closes when it merges.`);
+  }
+  const viewer = await viewerOf(ctx, gh);
+  const r = await linkSuggestionPrOnGitHub(gh, n, { pr: a.pr, branch, commit: a.commit, by: viewer ?? void 0, payloadSha: d.parsed.sha, forced: a.forced });
+  warnings.push(...r.warnings);
+  return { number: n, status: "applying", said: SUGGESTION_STATUS_LABEL.applying, ...a.pr ? { pr: a.pr } : {}, ...branch ? { branch } : {}, ...warnings.length ? { warnings } : {}, next: "It closes when the pull request merges." };
+}
+async function createSuggestionOp(ctx, a) {
+  const { config } = await ctx.config();
+  const gh = await ctx.github();
+  const raw = a.payload ?? {};
+  if (!SUGGESTION_KINDS.includes(raw.kind)) throw new Error(`"kind" must be one of ${SUGGESTION_KINDS.join(", ")}.`);
+  const needsBase = !raw.base;
+  const base = needsBase ? gh ? await suggestionBase(ctx, gh, config).catch(() => null) : null : raw.base;
+  if (!base) throw new Error(`No base commit: pass "base" { "ref", "sha" }, or set "repo" in ${CONFIG_FILE} so Bridge reads it.`);
+  const viewer = gh && !a.dryRun ? await viewerOf(ctx, gh) : null;
+  const payload = {
+    schema: SUGGESTION_SCHEMA,
+    source: a.source ?? "mcp",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    checks: { newErrors: 0, contrast: [], blocked: null, impact: 0 },
+    ...viewer ? { suggestedBy: viewer } : {},
+    ...raw,
+    base
+  };
+  const shape2 = suggestionShapeProblems(payload);
+  if (shape2.length) throw new Error(`The payload is not a suggestion: ${shape2.join(" ")}`);
+  if (payload.checks.blocked) throw new Error(`Not suggested: ${payload.checks.blocked}. Bridge never suggests a change that breaks the gate.`);
+  const paths = suggestionPathProblems(payload, config);
+  if (paths.length) throw new Error(`Not suggested: ${paths.join(" ")}`);
+  const labels = [.../* @__PURE__ */ new Set([...config.governance.labels, ...a.labels ?? []])];
+  if (a.dryRun) {
+    const issue = composeSuggestionIssue(payload, { labels, repo: gh?.fullName });
+    return { status: "dry-run", title: issue.title, labels: issue.labels, body: issue.body, parts: issue.parts.length, version: issue.sha.slice(0, 7) };
+  }
+  if (!gh || !ctx.canWriteRemote) return { status: "preview", message: noSuggestionAccess(ctx, gh), payload };
+  const created = await createSuggestionOnGitHub(gh, payload, { labels, repo: gh.fullName, assignees: config.integrations?.requests?.assignees ?? [] });
+  return { status: "suggested", number: created.number, url: created.url, version: created.sha.slice(0, 7), ...created.warnings.length ? { warnings: created.warnings } : {}, next: appliedNext(created.number) };
+}
+
 // src/ops.ts
 var prefixPath = (set, f) => set.repoPath(f);
 function normalizeTokenPath(set, input) {
@@ -8979,6 +11143,7 @@ async function getConfig(ctx) {
     source: ctx.describe(),
     configOrigin: origin === "file" ? "bridge.config.json" : "detected (no bridge.config.json; run `bridge init` to pin it)",
     write: ctx.mode === "local" ? ctx.isGit ? "local branches only (never pushes)" : "none (not a git repo)" : ctx.canWriteRemote ? "pull requests on new bridge/* branches" : "read-only (set GITHUB_TOKEN to open PRs)",
+    changes: changesMode(config) === "suggest" ? `suggest: token, docs, brand, revert and Figma changes are filed as suggestions (GitHub issues a developer applies with bridge apply or bridge_apply_suggestion)${ctx.canWriteRemote ? "" : "; filing one needs GITHUB_TOKEN with Issues write"}. Pass changes "direct" to a tool to open a branch instead.` : 'direct: changes open branches and pull requests. Pass changes "suggest" to a tool to file a suggestion instead.',
     repo: gh ? gh.fullName : null,
     tokenFiles: set.fileNames.length,
     tokens: set.allPaths().length,
@@ -9306,6 +11471,25 @@ async function proposeTokenChange(ctx, a) {
   if (newErrors.length || newFailures.length) {
     return { status: "blocked", why: [newErrors.length ? `${newErrors.length} new validation error(s)` : "", newFailures.length ? `${newFailures.length} contrast pair(s) would fail` : ""].filter(Boolean).join(" and "), newErrors, ...report, hint: "Fix the edits (or add edits for the aliases they break). Bridge never opens a PR that breaks the gate." };
   }
+  if (!target && await changesFor(ctx, a.changes) === "suggest") {
+    const source = a.source ?? "mcp";
+    const shown = { ...report, changesMode: "suggest", files: files.map((f) => f.path) };
+    const gh2 = await ctx.github();
+    if (a.dryRun) return { status: "dry-run", ...shown, suggestion: { title: suggestionIssueTitle({ kind: "token-change", title: a.title }), body }, fileContents: files };
+    if (!gh2 || !ctx.canWriteRemote) return { status: "preview", message: noSuggestionAccess(ctx, gh2), ...shown, fileContents: files };
+    const base2 = await suggestionBase(ctx, gh2, config);
+    const viewer = await viewerOf(ctx, gh2);
+    const s = await suggestTokenProposalOnGitHub(gh2, plan, {
+      base: base2.ref,
+      baseSha: base2.sha,
+      source,
+      ...viewer ? { suggestedBy: viewer } : {},
+      labels: config.governance.labels,
+      labelsAfter: marks.labels,
+      assignees: config.integrations?.requests?.assignees ?? []
+    });
+    return { status: "suggested", ...shown, number: s.number, url: s.url, version: s.sha.slice(0, 7), labels: s.labels, ...s.warnings.length ? { warnings: s.warnings } : {}, product: product.name, next: appliedNext(s.number) };
+  }
   let branch = target ? target.branch : branchWithJiraKey(`${config.governance.branchPrefix}${slugTitle}`, jira);
   const preview = { ...report, branch, files: files.map((f) => f.path), prBody: body };
   if (a.dryRun) return { status: "dry-run", ...preview, fileContents: files };
@@ -9457,8 +11641,8 @@ async function getReview(ctx, a) {
   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(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"}/`));
+  const tokenRoot2 = config.tokens.root.replace(/\/$/, "");
+  const otherFiles = changedFiles.filter((f) => !f.startsWith(`${tokenRoot2}/`) && !f.startsWith(`${config.changesets?.dir ?? ".changeset"}/`));
   const tier = core.classify(changes, otherFiles, config);
   const imp = core.impact(before, after, changes, 20);
   const labelTier = Array.isArray(meta.labels) ? meta.labels.map((l) => /^tier:\s*(\d)/i.exec(l)?.[1]).find(Boolean) : void 0;
@@ -9515,12 +11699,12 @@ async function scaffoldComponentOp(ctx, a) {
   const write = ctx.mode === "local" && a.write !== false;
   if (write) {
     for (const f of res.files) {
-      const abs = join4(ctx.root, f.path);
+      const abs = join5(ctx.root, f.path);
       if (await access(abs).then(() => true, () => false)) throw new Error(`${f.path} exists; not overwriting.`);
     }
     for (const f of res.files) {
-      await mkdir2(dirname3(join4(ctx.root, f.path)), { recursive: true });
-      await writeFile2(join4(ctx.root, f.path), f.content);
+      await mkdir3(dirname4(join5(ctx.root, f.path)), { recursive: true });
+      await writeFile3(join5(ctx.root, f.path), f.content);
     }
   }
   return { written: write, tier: 2, files: write ? res.files.map((f) => f.path) : res.files, nextSteps: res.notes };
@@ -9532,8 +11716,8 @@ async function auditUi(ctx, code2) {
 async function visualImpact(ctx, a, run2) {
   if (ctx.mode !== "local" || !ctx.root) throw new Error("Visual impact needs a local checkout (start Bridge with --root): it builds Storybook and the app at both refs.");
   if (!ctx.isGit) throw new Error(`${ctx.root} is not a git repository.`);
-  const out = a.out ? resolve3(ctx.root, a.out) : join4(ctx.root, "visual-impact");
-  const runImpact = run2 ?? (await import("./src-DHJOM5PQ.js")).runImpact;
+  const out = a.out ? resolve3(ctx.root, a.out) : join5(ctx.root, "visual-impact");
+  const runImpact = run2 ?? (await import("./src-ABI7LARD.js")).runImpact;
   const r = await runImpact({
     root: ctx.root,
     base: a.base ?? "main",
@@ -9566,7 +11750,7 @@ async function visualImpact(ctx, a, run2) {
       status: s.status,
       percent: s.percent,
       boxes: s.boxes.length,
-      ...s.images.composite ? { composite: join4(r.outDir, s.images.composite) } : {},
+      ...s.images.composite ? { composite: join5(r.outDir, s.images.composite) } : {},
       ...s.error ? { error: s.error } : {}
     })),
     outDir: r.outDir,
@@ -9810,6 +11994,17 @@ async function proposeRevert(ctx, a) {
   const plan = await buildPlan(ctx, a, ctx.mode === "local" ? "the bridge CLI" : "Bridge MCP");
   const report = planReport(plan);
   if (plan.status !== "ready") return { ...report, hint: plan.status === "blocked" ? "Bridge never opens a change that breaks the gate." : "Nothing to propose." };
+  if (await changesFor(ctx, a.changes) === "suggest") {
+    const summary2 = plan.commitMessage.split("\n").slice(1).join("\n").trim() || plan.prTitle;
+    const r = await fileSuggestion(
+      ctx,
+      (base2, by) => filesSuggestionPayload(ctx, { kind: "revert", title: plan.prTitle, summary: summary2, files: plan.files, tier: { tier: plan.tier.tier, bump: plan.tier.bump }, base: base2, source: a.source ?? "mcp", suggestedBy: by, checks: { newErrors: plan.newErrors.length } }),
+      { labels: [plan.kind === "revert" ? "revert" : "restore", ...plan.tier.tier === 3 ? ["tokens"] : [], ...plan.tier.bump === "major" ? ["breaking"] : []], details: plan.prBody, dryRun: a.dryRun }
+    );
+    if (r.status === "dry-run") return { ...report, status: "dry-run", changesMode: "suggest", suggestion: r.suggestion, fileContents: plan.files };
+    if (r.status === "preview") return { ...report, status: "preview", message: r.message, changesMode: "suggest", fileContents: plan.files };
+    return { ...report, status: "suggested", changesMode: "suggest", number: r.number, url: r.url, version: r.sha.slice(0, 7), labels: r.labels, ...r.warnings.length ? { warnings: r.warnings } : {}, next: r.next };
+  }
   if (a.dryRun) return { ...report, status: "dry-run", prBody: plan.prBody, fileContents: plan.files };
   const prefix = config.governance.branchPrefix;
   let branch = plan.branch;
@@ -9929,6 +12124,17 @@ async function proposeBrand(ctx, a) {
   const prefix = config.governance.branchPrefix;
   const stem2 = `${prefix}brand-${plan.slug}`;
   let branch = stem2;
+  if (await changesFor(ctx, a.changes) === "suggest") {
+    const summary2 = a.notes?.trim() || `New brand "${plan.slug}", started from ${plan.from}. ${report.contrast.line} (${plan.contrast.themes.join(" and ")}).`;
+    const r = await fileSuggestion(
+      ctx,
+      (base2, by) => filesSuggestionPayload(ctx, { kind: "brand", title: plan.title, summary: summary2, files, tier: { tier: plan.risk.tier, bump: plan.risk.bump }, base: base2, source: a.source ?? "mcp", suggestedBy: by }),
+      { labels: ["tokens"], details: report.prBody, dryRun: a.dryRun }
+    );
+    if (r.status === "dry-run") return { status: "dry-run", ...report, changesMode: "suggest", suggestion: r.suggestion, fileContents: files };
+    if (r.status === "preview") return { status: "preview", message: r.message, ...report, changesMode: "suggest", fileContents: files };
+    return { status: "suggested", ...report, changesMode: "suggest", number: r.number, url: r.url, version: r.sha.slice(0, 7), labels: r.labels, ...r.warnings.length ? { warnings: r.warnings } : {}, next: r.next };
+  }
   if (a.dryRun) return { status: "dry-run", ...report, branch, fileContents: files };
   const message = `feat(tokens): add the ${plan.name} brand
 
@@ -9996,15 +12202,15 @@ function requestFromIssue(issue) {
   const parsed = parseRequestIssue(issue.body);
   if (parsed) return parsed;
   const m = /^\s*([^:]{1,60}):\s*(.+)$/.exec(issue.title);
-  const kindLabel2 = issue.labels.map((l) => /^request:\s*(.+)$/.exec(l)?.[1]?.trim()).find((k) => k && KINDS2.has(k));
-  const sourceLabel2 = issue.labels.map((l) => /^source:\s*(.+)$/.exec(l)?.[1]?.trim()).find((s) => s === "figma" || s === "studio" || s === "cli" || s === "mcp");
+  const kindLabel3 = issue.labels.map((l) => /^request:\s*(.+)$/.exec(l)?.[1]?.trim()).find((k) => k && KINDS2.has(k));
+  const sourceLabel3 = issue.labels.map((l) => /^source:\s*(.+)$/.exec(l)?.[1]?.trim()).find((s) => s === "figma" || s === "studio" || s === "cli" || s === "mcp");
   return {
     component: m ? m[1].trim() : "Unknown",
-    kind: kindLabel2 ?? "other",
+    kind: kindLabel3 ?? "other",
     title: m ? m[2].trim() : issue.title,
     summary: issue.body.trim() || issue.title,
     changes: [],
-    source: sourceLabel2 ?? "studio"
+    source: sourceLabel3 ?? "studio"
   };
 }
 function statusOf(issue, prs) {
@@ -10092,7 +12298,7 @@ async function createRequest(ctx, a) {
 ${marks.line}`, labels: [...composed.labels, ...marks.labels] } : composed;
   if (a.dryRun) return { status: "dry-run", issue };
   const gh = await requireGitHub2(ctx);
-  if (!ctx.canWriteRemote) throw new Error("Creating a request needs GITHUB_TOKEN (issues: write on this repository). Without it Bridge is read-only.");
+  if (!ctx.canWriteRemote) throw new Error("Creating a request needs GITHUB_TOKEN with Issues: read and write on this repository (Contents: read is enough, like for suggestions). Without it Bridge is read-only.");
   const created = await gh.createIssue(issue);
   return {
     status: "created",
@@ -10200,7 +12406,8 @@ async function saveDocs(ctx, a) {
     return docsFileText(cleanDocs(merged), current);
   };
   const gh = await ctx.github();
-  const open = a.pr === void 0 && gh ? await findOpenDocsProposalOnGitHub(gh, { name, slug: docsSlug(name) }, ctx.ref ?? baseBranchOf(config)).catch(() => null) : null;
+  const mode = a.pr === void 0 ? await changesFor(ctx, a.changes) : "direct";
+  const open = a.pr === void 0 && gh && mode === "direct" ? await findOpenDocsProposalOnGitHub(gh, { name, slug: docsSlug(name) }, ctx.ref ?? baseBranchOf(config)).catch(() => null) : null;
   const target = a.pr ?? open?.number;
   if (target !== void 0) {
     const n = branchNumber(target);
@@ -10236,7 +12443,36 @@ async function saveDocs(ctx, a) {
       path,
       content: text,
       product: product.name,
-      ...a.dryRun ? {} : { said: `Nothing sent: saving docs for review needs a GitHub token with ${RIGHTS.docs}. Set GITHUB_TOKEN, or write the file yourself on a branch.` }
+      changesMode: mode,
+      ...a.dryRun ? {} : { said: mode === "suggest" ? noSuggestionAccess(ctx, gh) : `Nothing sent: saving docs for review needs a GitHub token with ${RIGHTS.docs}. Set GITHUB_TOKEN, or write the file yourself on a branch.` }
+    };
+  }
+  if (mode === "suggest") {
+    const base = await suggestionBase(ctx, gh, config);
+    const viewer = await viewerOf(ctx, gh);
+    const r2 = await proposeDocsOnGitHub(gh, [edit], {
+      base: base.ref,
+      baseSha: base.sha,
+      mode: "suggest",
+      title: a.title,
+      notes,
+      jira,
+      origin: DOCS_MCP_ORIGIN,
+      extraLabels: marks.labels,
+      source: a.source ?? "mcp",
+      ...viewer ? { suggestedBy: viewer } : {}
+    });
+    return {
+      status: "suggested",
+      number: r2.number,
+      url: r2.url,
+      title: r2.title,
+      path,
+      product: product.name,
+      changesMode: mode,
+      ..."warnings" in r2 && r2.warnings.length ? { warnings: r2.warnings } : {},
+      said: `Suggested the ${name} docs as #${r2.number}. Docs only: one approval, then a developer applies it.`,
+      next: appliedNext(r2.number)
     };
   }
   const r = await proposeDocsOnGitHub(gh.withBranchPrefix("docs/"), [edit], {
@@ -10343,13 +12579,18 @@ async function missingPiecesOp(ctx, a) {
     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) => {
+function tokenWriter(ctx, gh, source, viewer) {
+  return async (plan, how) => {
     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).`);
+    if (p.blocked) throw new Error(`The library ${how.mode === "suggest" ? "suggestion was not sent" : "branch was not opened"}: ${p.blocked}. Change the value (bridge_propose_token_change with dryRun shows why).`);
+    if (how.mode === "suggest") {
+      const base = await suggestionBase(ctx, gh, config);
+      const s = await suggestTokenProposalOnGitHub(gh, p, { base: base.ref, baseSha: base.sha, source, ...viewer ? { suggestedBy: viewer } : {}, labels: config.governance.labels, labelsAfter: [NEEDED_BY_LABEL], neededBy: plan.neededBy });
+      return { status: "suggested", number: s.number, url: s.url };
+    }
     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 };
   };
@@ -10357,7 +12598,8 @@ function tokenWriter(ctx, gh, source) {
 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 mode = await changesFor(ctx, a.changes);
+  const gh = a.dryRun ? await reader(ctx) : mode === "suggest" ? await writer(ctx, "Suggesting a library change", SUGGEST_RIGHTS) : await writer(ctx, "Opening a library branch", NEED);
   const { config } = await ctx.config();
   const viewer = await viewerOf(ctx, gh);
   const s = settingsOf(config);
@@ -10367,7 +12609,8 @@ async function openLibraryBranchOp(ctx, a) {
     base: s.base,
     products: productsOf(config),
     exploration: { packages: s.packages, apps: s.apps },
-    writeTokens: tokenWriter(ctx, gh, source),
+    writeTokens: tokenWriter(ctx, gh, source, viewer),
+    mode,
     ...viewer ? { openedBy: viewer } : {},
     ...source === "mcp" ? { agent: "claude" } : {},
     source,
@@ -10375,8 +12618,8 @@ async function openLibraryBranchOp(ctx, a) {
     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.";
+  const what = plan.kind === "token-change" ? mode === "suggest" ? "token suggestion" : "token change" : plan.kind === "exploration" ? "library exploration" : "component request";
+  const next = r.status === "dry-run" ? `Run it without dryRun to open the ${what}.` : r.status === "suggested" && r.link ? appliedNext(r.link.number) : 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,
@@ -10386,6 +12629,7 @@ async function openLibraryBranchOp(ctx, a) {
     ...plan.kind === "token-change" ? { edits: plan.edits } : {},
     ...plan.kind === "exploration" ? { exploration: plan.exploration.name, brief: plan.brief } : {},
     ...plan.kind === "request" ? { request: plan.request.title } : {},
+    changesMode: mode,
     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 } : {},
@@ -10435,15 +12679,118 @@ async function switchToPublishedOp(ctx, a) {
   return { pr: n, ...await switchToPublishedOnGitHub(gh, n) };
 }
 
+// src/figma.ts
+var figma_exports = {};
+__export(figma_exports, {
+  figmaChangesOp: () => figmaChangesOp,
+  getFigmaChangeOp: () => getFigmaChangeOp,
+  markFigmaDraftedOp: () => markFigmaDraftedOp,
+  pushFigmaComponentOp: () => pushFigmaComponentOp
+});
+var NEED2 = "Contents and Pull requests: read and write";
+async function tokenFacts(ctx, set, component) {
+  const { config } = await ctx.config();
+  const text = await ctx.source.read(config.components?.specs ?? DEFAULT_COMPONENT_SPECS_FILE).catch(() => void 0);
+  const usage = text ? specsUsage(parseComponentSpecs(text), component) : () => ({ variants: [], components: [] });
+  return { tierOf: (p) => set.tierOf(p), usedElsewhere: usage };
+}
+async function figmaChangesOp(ctx, a = {}) {
+  const gh = await reader(ctx);
+  const rows = await listFigmaChangesOnGitHub(gh, { state: a.state ?? "open" });
+  return {
+    changes: rows.map((r) => ({ pr: r.number, title: r.title, url: r.url, branch: r.branch, component: r.origin.component, route: r.origin.route === "token-change" ? "exact token change" : "Claude AI drafts", status: r.status.label, said: r.status.sentence })),
+    next: rows.some((r) => r.status.key === "waiting-for-claude") ? "Draft one: bridge_get_figma_change { pr } gives the spec and the steps." : rows.length ? "Owners review them on GitHub or in Bridge Studio." : "Nothing sent from Figma is open."
+  };
+}
+async function getFigmaChangeOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const gh = await reader(ctx);
+  const { config } = await ctx.config();
+  const r = await figmaChangeOnGitHub(gh, n, { componentsDir: config.components?.dir });
+  return {
+    pr: n,
+    title: r.pull.title,
+    url: r.pull.url,
+    branch: r.pull.headRef,
+    component: r.origin.component,
+    route: r.origin.route === "token-change" ? "exact token change" : "Claude AI drafts",
+    status: r.status.label,
+    said: r.status.sentence,
+    ...r.spec ? { spec: { path: r.origin.spec, changes: r.spec.changes, variantAxes: r.spec.variantAxes, properties: r.spec.properties, tokenEdits: r.spec.tokenEdits ?? [], reasons: r.spec.reasons ?? [] } } : {},
+    ...r.brief ? { brief: r.brief } : {},
+    next: r.brief && r.status.key === "waiting-for-claude" ? "Follow the brief, push the code to the branch, then bridge_mark_figma_change_drafted." : r.status.sentence
+  };
+}
+async function markFigmaDraftedOp(ctx, a) {
+  const n = branchNumber(a.pr);
+  const gh = await writer(ctx, "Marking a Figma change drafted", NEED2);
+  const r = await markFigmaChangeDraftedOnGitHub(gh, n);
+  return { pr: n, status: r.status.label, said: r.status.sentence, files: r.files, next: "Send it for review when it is ready (bridge_send_for_review), or tell the designer it is ready to look at." };
+}
+async function pushFigmaComponentOp(ctx, a) {
+  const d = a.diff;
+  if (!d || d.v !== 1 || typeof d.component !== "string" || !Array.isArray(d.changes)) throw new Error("The diff is not a Bridge component diff (v 1): see the spec of a branch from bridge_get_figma_change for its shape.");
+  const source = a.source ?? "mcp";
+  const tool = source === "mcp" ? "Bridge MCP" : "the bridge CLI";
+  const { config } = await ctx.config();
+  const set = await ctx.tokens();
+  const tokens = await tokenFacts(ctx, set, d.component);
+  const mode = await changesFor(ctx, a.changes);
+  const gh = a.dryRun ? await reader(ctx) : mode === "suggest" ? await writer(ctx, "Suggesting a component change from Figma", SUGGEST_RIGHTS) : await writer(ctx, "Sending a component change from Figma", NEED2);
+  const viewer = a.dryRun ? null : await viewerOf(ctx, gh);
+  const base = a.dryRun || mode !== "suggest" ? null : await suggestionBase(ctx, gh, config);
+  const pairs = await core.readContrastPairs(ctx.source, config).catch(() => []);
+  const aliasOfPath = (p) => aliasOf(set.defsOf(p)[0]?.value) ?? void 0;
+  const r = await openComponentPushOnGitHub(gh, {
+    diff: { ...d, source: d.source ?? source },
+    tokens,
+    base: baseBranchOf(config),
+    branchPrefix: config.governance.branchPrefix,
+    labels: [...config.governance.labels, `source: ${source}`],
+    tool,
+    dryRun: a.dryRun,
+    mode,
+    ...viewer ? { suggestedBy: viewer } : {},
+    ...base ? { base: base.ref, baseSha: base.sha } : {},
+    writeTokens: async ({ edits, title, summary: summary2, bodyExtra, mode: how, figma }) => {
+      const all = [...pairs, ...componentContrastPairs(edits, pairs, { aliasOf: aliasOfPath, paths: set.allPaths() })];
+      const p = planTokenProposal({ before: set, pairs: all, edits, title, summary: summary2, config, tool, bodyExtra });
+      if (!p) throw new Error("The library already paints it this way: nothing to send.");
+      if (p.blocked) throw new Error(`Not sent: ${p.blocked}. Pick another variable.`);
+      if (how === "suggest") {
+        const b = base ?? await suggestionBase(ctx, gh, config);
+        const s = await suggestTokenProposalOnGitHub(gh, p, { base: b.ref, baseSha: b.sha, source, ...viewer ? { suggestedBy: viewer } : {}, labels: config.governance.labels, labelsAfter: [`source: ${source}`], links: { figma } });
+        return { status: "suggested", number: s.number, url: s.url };
+      }
+      const opened = await writeTokenProposalOnGitHub(gh, p, { base: baseBranchOf(config), branchPrefix: config.governance.branchPrefix, labels: config.governance.labels, labelsAfter: [`source: ${source}`], tool: `${tool} (source: ${source})` });
+      return { number: opened.pr, url: opened.url, branch: opened.branch };
+    }
+  });
+  const plan = r.plan;
+  return {
+    status: r.status,
+    component: d.component,
+    route: plan.route === "token-change" ? "exact token change" : plan.route === "claude-draft" ? "Claude AI drafts" : "fix in Figma",
+    said: plan.said,
+    ...plan.edits.length ? { edits: plan.edits } : {},
+    ...plan.reasons.length ? { reasons: plan.reasons } : {},
+    ...plan.issues.length ? { fixInFigma: plan.issues } : {},
+    changesMode: mode,
+    ...r.link ? { library: r.link } : {},
+    ...r.suggestion ? { suggestion: r.suggestion } : {},
+    next: r.status === "dry-run" ? `Run it without dryRun to ${mode === "suggest" ? "file the suggestion" : "open the library branch"}.` : r.status === "not-sent" ? "Nothing was sent: fix these in Figma, then push again." : r.suggestion ? `${r.suggestion.route === "claude-draft" ? "A component spec suggestion: Claude AI drafts the code from it once a developer applies it (bridge_apply_suggestion writes the spec file and returns the brief). " : ""}${appliedNext(r.suggestion.number)}` : plan.route === "claude-draft" ? `Draft the code: bridge_get_figma_change { pr: ${r.link.number} }.` : "Design and tech owners review the token change. Once it ships, a pull in the DS Bridge plugin rebuilds the component."
+  };
+}
+
 // src/server.ts
-var VERSION = true ? "0.5.0" : "dev";
+var VERSION = true ? "0.7.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 fail2 = (e) => ({ content: [{ type: "text", text: `Error: ${e.message ?? String(e)}` }], isError: true });
 var run = (fn) => async (a) => {
   try {
     return ok(await fn(a));
   } catch (e) {
-    return fail(e);
+    return fail2(e);
   }
 };
 var ModeArg = z.record(z.string(), z.string()).describe('Mode values, e.g. {"theme":"dark","brand":"ocean"}. Omitted modes use their default. See bridge_get_config for the modes this repo has.');
@@ -10458,6 +12805,7 @@ var EditArg = z.object({
   mode: ModeArg.optional().describe('Pick the file that defines the token for this mode, e.g. {"theme":"dark"}. Alternative to `file`.')
 });
 var RO = { readOnlyHint: true, openWorldHint: false };
+var ChangesArg = z.enum(["suggest", "direct"]).optional().describe('How this change reaches the code: "suggest" files a suggestion (a GitHub issue the owners approve and a developer applies, Issues write only), "direct" opens a branch and a pull request. Default: "changes" in bridge.config.json, else "suggest". Only set it when the person asked.');
 function createServer(ctx) {
   const server = new McpServer(
     { name: "bridge", version: VERSION },
@@ -10465,6 +12813,7 @@ function createServer(ctx) {
       instructions: [
         "Bridge exposes a design system repo (DTCG tokens, components, docs) to you.",
         "Every write goes through a branch and a pull request, never straight to the default branch: the library only changes through reviewed pull requests, and on a protected repo GitHub refuses direct pushes anyway.",
+        'How changes reach the code is the "changes" setting of bridge.config.json (bridge_get_config says which): "suggest" (the default) files token, docs, brand, revert, missing piece and Figma changes as suggestions, GitHub issues with the exact change that the owners approve (bridge_review_suggestion) and a developer applies (bridge_apply_suggestion, or `bridge apply <n>`); "direct" opens branches and pull requests. Writing tools take "changes" to pick one for a call; only pass it when the person asked. When the person says "Apply Bridge suggestion #n", call bridge_apply_suggestion with mode "dry-run" first, show the result, then apply it on a branch.',
         "Read before you write: bridge_get_guidelines for the repo rules, bridge_search_tokens / bridge_get_token before using or proposing a token.",
         "Never hardcode a value in UI code when a token exists; never invent a token name (check it with bridge_get_token).",
         "bridge_audit measures how a product codebase adopts the design system (hardcoded values, foreign UI components) and suggests the tokens and components to use.",
@@ -10477,6 +12826,7 @@ function createServer(ctx) {
         "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.",
+        "Components from Figma: the DS Bridge plugin sends a component changed in Figma to a library branch. Token swaps go as exact token changes; new variants, properties and components go to a branch carrying the spec, waiting for Claude AI. When the person asks you to draft one, bridge_figma_changes lists them and bridge_get_figma_change gives the spec and the steps; write the code on that branch, push it, then bridge_mark_figma_change_drafted. Never claim a branch is drafted before its code is pushed.",
         '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(" ")
     }
@@ -10605,7 +12955,7 @@ function createServer(ctx) {
     "bridge_propose_token_change",
     {
       title: "Propose token change",
-      description: 'Propose token edits as a reviewable change. Applies edits with minimal JSON diffs, validates, runs the contrast gate before/after, computes the risk tier and semver bump, writes a changeset and a designer-friendly PR body. Blocked (nothing written) if it adds validation errors or breaks a contrast pair. Local repo: commits to a new local bridge/* branch without touching your working tree (never pushes). GitHub with token: new branch + draft PR labelled "source: mcp" and its tier. Never writes to main. Use dryRun to preview. Tell the user token changes are Tier 3.',
+      description: 'Propose token edits as a reviewable change. Applies edits with minimal JSON diffs, validates, runs the contrast gate before/after, computes the risk tier and semver bump, writes a changeset and a designer-friendly PR body. Blocked (nothing written) if it adds validation errors or breaks a contrast pair. Suggest mode (the default unless bridge.config.json says "changes": "direct"): files a suggestion, a GitHub issue with the exact edits, the checks and the tier, status "suggested" with its number; owners approve it and a developer applies it (bridge_apply_suggestion). Direct mode: local repo, commits to a new local bridge/* branch without touching your working tree (never pushes); GitHub with token, new branch + draft PR labelled "source: mcp" and its tier. With branch or pr it writes to that branch whatever the mode. Never writes to main. Use dryRun to preview. Tell the user token changes are Tier 3.',
       inputSchema: {
         title: z.string().min(3).describe('Short imperative title, e.g. "Darken muted text in dark theme". Becomes the branch name and PR title.'),
         summary: z.string().optional().describe("Why: the problem and the intent, for the reviewers. Plain sentences, no em dash."),
@@ -10614,11 +12964,12 @@ function createServer(ctx) {
         branch: z.string().optional().describe("Exploration branch (explore/<slug>) to commit the edits to instead of opening a new pull request. GitHub: one commit on that branch. Local: written to the working tree, which must have that branch checked out. Never main."),
         pr: z.union([z.number().int().positive(), z.string().min(1)]).optional().describe('A branch already in review (12 or "#12") to add the edits to, as "Edit tokens in this branch" in Studio: one commit there and a comment for the reviewers. Its author or someone with write access; needs GITHUB_TOKEN.'),
         jira: z.string().optional().describe("Jira key like DS-42, as in Studio's Create branch: first in the branch name and title so Jira links them."),
-        product: z.string().optional().describe("Product key or name (bridge_list_products) the change is for. Default: the product of the current folder or repo. Ask the person when it is not obvious.")
+        product: z.string().optional().describe("Product key or name (bridge_list_products) the change is for. Default: the product of the current folder or repo. Ask the person when it is not obvious."),
+        changes: ChangesArg
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    run((a) => proposeTokenChange(ctx, a))
+    run((a) => proposeTokenChange(ctx, { ...a, source: "mcp" }))
   );
   const Hue = z.union([z.string(), z.number()]);
   const BrandArgs = {
@@ -10652,11 +13003,11 @@ function createServer(ctx) {
     "bridge_propose_brand",
     {
       title: "Propose a new brand",
-      description: 'Propose a new brand as a reviewable change. Same plan as bridge_plan_brand; blocked (nothing written) when an input is invalid or a contrast pair fails. Local repo: commits to a new local bridge/brand-<slug> branch without touching your working tree (never pushes). GitHub with token: new branch + draft PR labelled "source: mcp", "tier: 3" and "tokens". Never writes to main. Tell the user a new brand is Tier 3: it needs design and tech owner approval.',
-      inputSchema: { ...BrandArgs, dryRun: z.boolean().optional().describe("Return the plan and file contents without writing.") },
+      description: 'Propose a new brand as a reviewable change. Same plan as bridge_plan_brand; blocked (nothing written) when an input is invalid or a contrast pair fails. Local repo: commits to a new local bridge/brand-<slug> branch without touching your working tree (never pushes). GitHub with token: new branch + draft PR labelled "source: mcp", "tier: 3" and "tokens". Never writes to main. Suggest mode (the default unless bridge.config.json says "changes": "direct"): one suggestion issue with the brand files instead, applied by a developer once approved. Tell the user a new brand is Tier 3: it needs design and tech owner approval.',
+      inputSchema: { ...BrandArgs, dryRun: z.boolean().optional().describe("Return the plan and file contents without writing."), changes: ChangesArg },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    run((a) => proposeBrand(ctx, a))
+    run((a) => proposeBrand(ctx, { ...a, source: "mcp" }))
   );
   server.registerTool(
     "bridge_list_reviews",
@@ -10748,17 +13099,18 @@ function createServer(ctx) {
     "bridge_propose_revert",
     {
       title: "Propose a revert",
-      description: "Plans the revert (or restore) like bridge_plan_revert, then: local repo, commits to a new local bridge/* branch without touching your working tree (never pushes); GitHub with token, new bridge/* branch and a PR labelled revert and its tier (draft for Tier 2 and 3). Blocked when it would add validation errors or break a contrast pair. Never writes to main. Show the user the plan and its conflicts first.",
+      description: 'Plans the revert (or restore) like bridge_plan_revert, then: local repo, commits to a new local bridge/* branch without touching your working tree (never pushes); GitHub with token, new bridge/* branch and a PR labelled revert and its tier (draft for Tier 2 and 3). Blocked when it would add validation errors or break a contrast pair. Never writes to main. Suggest mode (the default unless bridge.config.json says "changes": "direct"): one suggestion issue with the files instead, applied by a developer once approved. Show the user the plan and its conflicts first.',
       inputSchema: {
         target: z.string().optional(),
         restore: RestoreArg.optional(),
         resolutions: ResolutionsArg.optional(),
         restoreConflicts: z.boolean().optional(),
-        dryRun: z.boolean().optional()
+        dryRun: z.boolean().optional(),
+        changes: ChangesArg
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    run((a) => proposeRevert(ctx, a))
+    run((a) => proposeRevert(ctx, { ...a, source: "mcp" }))
   );
   server.registerTool(
     "bridge_scaffold_component",
@@ -10892,7 +13244,7 @@ function createServer(ctx) {
           ]
         };
       } catch (e) {
-        return fail(e);
+        return fail2(e);
       }
     }
   );
@@ -10989,8 +13341,8 @@ function createServer(ctx) {
     "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() },
+      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. Suggest mode (the default unless bridge.config.json says "changes": "direct"): a token piece becomes a suggestion and a variant a component request, no branch; needs Issues write. Direct mode 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(), changes: ChangesArg },
       annotations: WRITE
     },
     run((a) => openLibraryBranchOp(ctx, { ...a, source: "mcp" }))
@@ -11025,6 +13377,46 @@ function createServer(ctx) {
     },
     run((a) => switchToPublishedOp(ctx, a))
   );
+  server.registerTool(
+    "bridge_figma_changes",
+    {
+      title: "Component changes sent from Figma",
+      description: "The library branches the DS Bridge Figma plugin opened for components changed in Figma (label from-figma), with where each stands: an exact token change (no AI, contrast gated), or a branch carrying the spec, waiting for Claude AI to draft the code, then drafted by Claude AI and reviewed by a person.",
+      inputSchema: { state: z.enum(["open", "closed", "all"]).optional().describe("Default open.") },
+      annotations: READ
+    },
+    run((a) => figmaChangesOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_get_figma_change",
+    {
+      title: "Get a component change from Figma, to draft it",
+      description: "One library branch sent from Figma: its spec (variant matrix, properties, bound variables per variant, layers, what code gave Figma before, the exact token swaps) and the brief to draft the code on that branch. Check out the branch, write the TSX, CSS module, examples, docs and changeset, run npm run specs and the tests, push, then call bridge_mark_figma_change_drafted.",
+      inputSchema: { pr: Pr },
+      annotations: READ
+    },
+    run((a) => getFigmaChangeOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_mark_figma_change_drafted",
+    {
+      title: "Mark a Figma change drafted by Claude AI",
+      description: "After you pushed the code for a component change from Figma to its branch: label it drafted-by-claude (no longer waiting-for-claude) and say so in its description, for a person to review. Refused while the branch only carries the spec. Needs GITHUB_TOKEN (pull requests: write).",
+      inputSchema: { pr: Pr },
+      annotations: WRITE
+    },
+    run((a) => markFigmaDraftedOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_push_figma_component",
+    {
+      title: "Send a component change from Figma",
+      description: 'What the DS Bridge plugin Push tab does, from a structured diff of a Figma component (the v 1 spec shape: component, figmaName, coded, kind, title, summary, changes, rebinds, needsCode, unknown, variantAxes, properties, bindings, anatomy). An exact token swap on a component token used nowhere else opens a token change (contrast gated, reviewed like any token change); anything that needs code opens a draft branch with the spec, waiting for Claude AI; detached layers, raw values and variables the library lacks are listed with what to do and never sent. Suggest mode (the default unless bridge.config.json says "changes": "direct"): a token suggestion or a component spec suggestion instead of a branch, Issues write only. dryRun shows the route. Direct mode needs GITHUB_TOKEN (contents and pull requests: write). Only when the person asked.',
+      inputSchema: { diff: z.record(z.string(), z.unknown()).describe("The structured component diff (v 1)."), dryRun: z.boolean().optional(), changes: ChangesArg },
+      annotations: WRITE
+    },
+    run((a) => pushFigmaComponentOp(ctx, { diff: a.diff, dryRun: a.dryRun, source: "mcp", changes: a.changes }))
+  );
   server.registerTool(
     "bridge_list_products",
     {
@@ -11214,7 +13606,7 @@ function createServer(ctx) {
     "bridge_save_docs",
     {
       title: "Save component docs",
-      description: `Save a component's usage guidance (docs.json sections: summary, whenToUse, whenNotToUse, dos, donts, accessibility, contentGuidelines, anatomy, preview) the way the Library edit mode does: merged into the docs on the branch, cleaned and checked (a summary, no empty items, no em dash). Without pr: a new branch sent for review (docs only: one approval, patch release note), with an optional Jira key and product. With pr: one commit on that open branch. dryRun returns the file. Needs GITHUB_TOKEN (contents and pull requests: write). Prose you drafted carries "draftedBy": "claude" and "needsReview": true so a reviewer accepts it in Studio.`,
+      description: `Save a component's usage guidance (docs.json sections: summary, whenToUse, whenNotToUse, dos, donts, accessibility, contentGuidelines, anatomy, preview) the way the Library edit mode does: merged into the docs on the branch, cleaned and checked (a summary, no empty items, no em dash). Without pr: a new branch sent for review (docs only: one approval, patch release note), with an optional Jira key and product. With pr: one commit on that open branch. Suggest mode (the default unless bridge.config.json says "changes": "direct"), without pr: a docs suggestion issue instead of a branch (Issues write only). dryRun returns the file. Direct mode needs GITHUB_TOKEN (contents and pull requests: write). Prose you drafted carries "draftedBy": "claude" and "needsReview": true so a reviewer accepts it in Studio.`,
       inputSchema: {
         component: z.string().min(1).describe("Component name, e.g. Button."),
         docs: z.record(z.string(), z.unknown()).describe('The sections to set, in docs.json shapes: summary a string; whenToUse, whenNotToUse, accessibility, contentGuidelines lists of strings; dos and donts lists of {"title","text"}.'),
@@ -11223,11 +13615,100 @@ function createServer(ctx) {
         notes: z.string().optional().describe("Why, for the reviewers."),
         jira: z.string().optional().describe("Jira key like DS-42: first in the branch name and title so Jira links them."),
         product: z.string().optional().describe("Product key or name (bridge_list_products). Default: the product of the current folder or repo."),
-        dryRun: z.boolean().optional()
+        dryRun: z.boolean().optional(),
+        changes: ChangesArg
+      },
+      annotations: WRITE
+    },
+    run((a) => saveDocs(ctx, { ...a, source: "mcp" }))
+  );
+  const SuggestionNumber = z.union([z.number().int().positive(), z.string().min(1)]).describe('The suggestion issue number (42 or "#42"), or its link.');
+  server.registerTool(
+    "bridge_list_suggestions",
+    {
+      title: "List suggestions",
+      description: "Suggestions in the repo: GitHub issues labeled bridge-suggestion, each an exact change (tokens, docs, a component spec, a brand, a revert, settings) that the owners approve and a developer applies. Each row has the number, title, kind, tier, status (needs-review, changes-requested, approved, applying, applied, declined, outdated) and linked pull requests. Statuses here come from labels; bridge_get_suggestion counts the approvals.",
+      inputSchema: {
+        status: z.enum(["needs-review", "changes-requested", "approved", "applying", "applied", "declined", "outdated", "all"]).optional().describe("Default all open ones."),
+        state: z.enum(["open", "closed", "all"]).optional().describe("Issue state. Default: open, or closed for applied and declined."),
+        kind: z.enum(["token-change", "docs", "component-spec", "brand", "revert", "config"]).optional(),
+        limit: z.number().int().min(1).max(100).optional().describe("Default 100.")
+      },
+      annotations: READ
+    },
+    run((a) => listSuggestionsOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_get_suggestion",
+    {
+      title: "Get a suggestion",
+      description: "One suggestion: the change (tokens before and after, docs, component spec, files), the checks when suggested, links, its version (payloadSha: what approvals bind to), who approved it, which approvals are missing for its tier, reviews that no longer count (an older version, or not an owner), whether the machine-readable block was edited by hand, linked pull requests, and for a component spec the brief to implement it.",
+      inputSchema: { number: SuggestionNumber },
+      annotations: READ
+    },
+    run((a) => getSuggestionOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_create_suggestion",
+    {
+      title: "Create a suggestion",
+      description: "File any change as a suggestion from its payload (schema bridge.suggestion/1: kind, title, summary, and tokens edits, docs, componentSpec or files). Missing schema, source, date, base commit and checks are filled. The paths are checked against what the kind may change and the guardrail files before anything is sent. For token, docs, brand, revert and Figma changes prefer their own tools, which plan and check the change first. Needs GITHUB_TOKEN with Issues write. dryRun returns the issue. Only when the person asked.",
+      inputSchema: {
+        payload: z.record(z.string(), z.unknown()).describe("The suggestion payload (bridge.suggestion/1)."),
+        labels: z.array(z.string()).optional().describe("More labels for the issue."),
+        dryRun: z.boolean().optional().describe("Return the issue title, body and labels without creating it.")
+      },
+      annotations: WRITE
+    },
+    run((a) => createSuggestionOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_review_suggestion",
+    {
+      title: "Review a suggestion",
+      description: "Approve, request changes on, comment on or decline a suggestion, as the person whose GitHub token the server has. Approvals and requested changes count only from the owners in bridge.config.json (read from the default branch) and only on the version reviewed: pass payloadSha from bridge_get_suggestion so a newer version is never approved by mistake. Request changes and decline need a message. Decline closes the issue as not planned. Needs GITHUB_TOKEN (Issues: read and write). Only when the person asked, with the decision they asked for.",
+      inputSchema: {
+        number: SuggestionNumber,
+        event: z.enum(["approve", "request-changes", "comment", "decline"]),
+        message: z.string().optional().describe("What should change, why it is declined, or the comment. Plain sentences, no em dash."),
+        role: z.enum(["design", "tech", "approval"]).optional().describe("The role you approve for, shown in the comment. Informative: what counts is who you are in the owner lists."),
+        payloadSha: z.string().optional().describe("The version you reviewed (payloadSha or version from bridge_get_suggestion).")
+      },
+      annotations: WRITE
+    },
+    run((a) => reviewSuggestionOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_apply_suggestion",
+    {
+      title: "Apply a suggestion",
+      description: `Apply a Bridge suggestion to today's code ("Apply Bridge suggestion #42"). Bridge checks the paths, the approvals of the owners on its current version, re-applies token edits on the current tokens, merges files, re-runs validation, contrast and the tier, and stops on a conflict, a missing approval or a check that would fail. Local repo: mode "dry-run" (the plan and the diff, nothing written; run it first), "branch" (default: one commit on a new local branch, working tree untouched, never pushes), "write" (into the working tree, refused over uncommitted changes) or "patch" (a git format-patch text). Remote repo: the plan and the files to write yourself. Once a branch or files exist, it records on the issue that it is being applied (needs Issues write). Then push and open a pull request whose body says "Closes #<n>", and call bridge_link_suggestion. acceptEdited and forceUnapproved only when the person asked.`,
+      inputSchema: {
+        number: SuggestionNumber,
+        mode: z.enum(["dry-run", "branch", "write", "patch"]).optional().describe("Default branch. Run dry-run first."),
+        acceptEdited: z.boolean().optional().describe("Apply even though the machine-readable block was edited by hand after Bridge wrote it (check it first)."),
+        forceUnapproved: z.boolean().optional().describe("Apply without every approval, or with a tier that went up. Recorded on the issue."),
+        base: z.string().optional().describe("Local mode, branch and patch: the ref to build on. Default HEAD."),
+        branch: z.string().optional().describe("Local mode, branch: the branch name. Default <branchPrefix>suggestion-<n>-<slug>.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    run((a) => applySuggestionOp(ctx, a))
+  );
+  server.registerTool(
+    "bridge_link_suggestion",
+    {
+      title: "Link the pull request that applies a suggestion",
+      description: 'Record the pull request (or branch, or commit) that applies a suggestion: a comment on the issue and the "suggestion: applying" label. Warns when the pull request does not say "Closes #<n>": add it so the suggestion closes when it merges. Needs GITHUB_TOKEN (Issues: read and write).',
+      inputSchema: {
+        number: SuggestionNumber,
+        pr: z.number().int().positive().optional().describe("The pull request number."),
+        branch: z.string().optional(),
+        commit: z.string().optional()
       },
       annotations: WRITE
     },
-    run((a) => saveDocs(ctx, a))
+    run((a) => linkSuggestionOp(ctx, a))
   );
   server.registerResource("resolved-tokens", "bridge://tokens/resolved", { title: "Resolved tokens", description: "Every token resolved in the default mode, plus only the values that differ in each other mode combination.", mimeType: "application/json" }, async (uri) => {
     const set = await ctx.tokens();
@@ -11444,6 +13925,7 @@ export {
   auditSnippet,
   branches_exports,
   explorations_exports,
+  suggestions_exports,
   ops_exports,
   history_exports,
   brand_exports,
@@ -11451,6 +13933,7 @@ export {
   drafts_exports,
   studio_exports,
   pieces_exports,
+  figma_exports,
   VERSION,
   createServer,
   serveStdio,