@bridge-ds/mcp 0.6.0 → 0.7.1

package/dist/{chunk-M7DUTFIQ.js → chunk-YCKNSKPW.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,
@@ -73,7 +76,7 @@ import {
   validateLayered,
   variantKeyOf,
   whoCanShipSentence
-} from "./chunk-E4D5KPIQ.js";
+} from "./chunk-BZ3KXXMM.js";
 
 // src/lib.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -103,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) {
@@ -122,7 +125,7 @@ function parseJson(text) {
       }
       i++;
     }
-    return fail2("Unterminated string");
+    return fail3("Unterminated string");
   };
   const parseValue = () => {
     skipWs();
@@ -140,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 });
@@ -153,7 +156,7 @@ function parseJson(text) {
             i++;
             break;
           }
-          fail2('Expected "," or "}"');
+          fail3('Expected "," or "}"');
         }
       }
       const raw = text.slice(start, i);
@@ -176,7 +179,7 @@ function parseJson(text) {
             i++;
             break;
           }
-          fail2('Expected "," or "]"');
+          fail3('Expected "," or "]"');
         }
       }
       const raw = text.slice(start, i);
@@ -195,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] };
     }
@@ -211,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) };
 }
@@ -957,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
@@ -2505,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;
@@ -2520,7 +2523,7 @@ ${p.source?.pr ? `Reverts #${p.source.pr.number}. ` : ""}Tier ${tier.tier}. Plan
     tier,
     files,
     ...changeset ? { changeset } : {},
-    commitMessage,
+    commitMessage: commitMessage2,
     prBody,
     notes
   };
@@ -3429,9 +3432,9 @@ 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 "";
@@ -3792,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";
@@ -3928,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();
@@ -4180,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 = [];
@@ -4637,6 +4658,92 @@ function branchWithJiraKey(branch, key) {
   return i < 0 ? `${key}-${branch}` : `${branch.slice(0, i + 1)}${key}-${branch.slice(i + 1)}`;
 }
 
+// ../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 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");
+}
+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 });
+  });
+  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";
+}
+
 // ../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;
@@ -4809,6 +4916,7 @@ function figmaDraftBrief(d, ctx) {
     ...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}`] : [],
+    ...suggested && d.figma?.fileKey && d.figma.nodeId ? [`Read the design straight from Figma: Figma MCP get_design_context { fileKey: "${d.figma.fileKey}", nodeId: "${d.figma.nodeId}" }${d.figma.before?.nodeId ? ` (before: node ${d.figma.before.nodeId})` : ""}, or the REST API GET https://api.figma.com/v1/files/${d.figma.fileKey}/nodes?ids=${encodeURIComponent(d.figma.nodeId)}.`] : [],
     ...d.images?.length ? ["Screenshot:", ...d.images.map((u) => `- ${u}`)] : [],
     "",
     "Steps:",
@@ -5108,6 +5216,16 @@ var SUGGESTION_STATE_LABELS = {
   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 figmaNodeUrl = (fileKey, nodeId) => `https://www.figma.com/design/${fileKey}/?node-id=${encodeURIComponent(nodeId.replace(/:/g, "-"))}`;
 var SUGGESTION_LIMITS = {
   body: 65536,
   /** The readable part of the body (tables are cut with "and N more"). */
@@ -5336,6 +5454,13 @@ function suggestionLabels(p, opts = {}) {
     ])
   ];
 }
+function suggestionKindFromLabels(labels) {
+  for (const l of labels) {
+    const m = /^suggestion: (.+)$/.exec(l);
+    if (m && SUGGESTION_KINDS.includes(m[1])) return m[1];
+  }
+  return void 0;
+}
 function suggestionStateFromLabels(labels) {
   return Object.entries(SUGGESTION_STATE_LABELS).find(([, l]) => labels.includes(l))?.[0];
 }
@@ -5346,6 +5471,9 @@ function suggestionStatus(i) {
   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";
@@ -5404,6 +5532,19 @@ function linksSection(p) {
   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})`);
+  const key = l.figma?.fileKey;
+  const nodes = (l.figma?.nodes ?? []).filter((n) => n && typeof n.nodeId === "string");
+  for (const n of nodes) {
+    const url = n.url ?? (key ? figmaNodeUrl(key, n.nodeId) : void 0);
+    const what = `${n.state === "before" ? "Before" : n.state === "after" ? "After" : "Node"}${n.name ? ` (${cell3(n.name)})` : ""}`;
+    out.push(`- ${what}: ${url ? `[node ${n.nodeId}](${url})` : `node ${n.nodeId}`}`);
+  }
+  if (key && (nodes.length || l.figma?.nodeId)) {
+    const ids = nodes.length ? nodes.map((n) => n.nodeId) : [l.figma.nodeId];
+    out.push(
+      `- Claude Code reads this design straight from Figma: the Figma MCP server (\`get_design_context\` with file key \`${key}\` and node ${ids.map((i) => `\`${i}\``).join(", ")}) or the REST API (\`GET https://api.figma.com/v1/files/${key}/nodes?ids=${ids.map(encodeURIComponent).join(",")}\`). No image hosting is needed.`
+    );
+  }
   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}`);
@@ -5554,6 +5695,72 @@ ${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."];
@@ -5576,6 +5783,8 @@ function suggestionShapeProblems(raw) {
   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" }.');
+  const nodes = p.links?.figma?.nodes;
+  if (nodes !== void 0 && !(Array.isArray(nodes) && nodes.every((n) => n && typeof n.nodeId === "string"))) out.push('"links.figma.nodes" must be a list of { "nodeId", "url"?, "name"?, "state"? }.');
   if (p.files !== void 0) {
     if (!Array.isArray(p.files)) out.push('"files" must be a list.');
     else {
@@ -5593,6 +5802,63 @@ function suggestionShapeProblems(raw) {
   }
   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 = {}) {
@@ -5611,6 +5877,97 @@ async function createSuggestionOnGitHub(gh, payload, opts = {}) {
   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 = {
@@ -6177,6 +6534,44 @@ Proposed through ${opts.tool ?? "Bridge MCP"}. Tier ${plan.tier.tier}.`, files:
 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";
@@ -6186,7 +6581,8 @@ function componentSpecSuggestionPayload(d, plan, ctx) {
   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;
+  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 } : {}, ...figmaNodes(d) } : void 0;
+  const previews = (d.images ?? []).map((url, i) => ({ label: `${d.component} in Figma${(d.images?.length ?? 0) > 1 ? ` ${i + 1}` : ""}`, url }));
   return {
     schema: SUGGESTION_SCHEMA,
     kind: "component-spec",
@@ -6199,9 +6595,19 @@ function componentSpecSuggestionPayload(d, plan, ctx) {
     tier: specTier(d),
     componentSpec: { component: d.component, specPath, spec, brief },
     checks: { newErrors: 0, contrast: [], blocked: null, impact: 0 },
-    ...figma ? { links: { figma } } : {}
+    ...figma ? { links: { figma } } : {},
+    ...previews.length ? { previews } : {}
   };
 }
+function figmaNodes(d) {
+  const f = d.figma;
+  if (!f) return {};
+  const url = (id, given) => given ?? (f.fileKey ? figmaNodeUrl(f.fileKey, id) : void 0);
+  const nodes = [];
+  if (f.before?.nodeId) nodes.push({ nodeId: f.before.nodeId, state: "before", ...url(f.before.nodeId, f.before.url) ? { url: url(f.before.nodeId, f.before.url) } : {}, ...f.before.nodeName ? { name: f.before.nodeName } : {} });
+  if (f.nodeId) nodes.push({ nodeId: f.nodeId, state: "after", ...url(f.nodeId, f.url) ? { url: url(f.nodeId, f.url) } : {}, ...f.nodeName ? { name: f.nodeName } : {} });
+  return nodes.length ? { nodes } : {};
+}
 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.");
@@ -6222,7 +6628,7 @@ async function openComponentPushOnGitHub(gh, input) {
   };
   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 figma = { ...origin.fileKey ? { fileKey: origin.fileKey } : {}, ...origin.nodeId ? { nodeId: origin.nodeId } : {}, ...origin.url ? { url: origin.url } : {}, ...figmaNodes(d) };
     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 } };
@@ -6289,14 +6695,277 @@ async function markFigmaChangeDraftedOnGitHub(gh, n) {
   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))
+  });
+}
+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
 var US = "";
 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);
@@ -6333,7 +7002,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)])));
@@ -6963,14 +7632,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) {
@@ -7458,16 +8127,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() };
   });
 }
@@ -8153,9 +8822,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) => {
@@ -8222,6 +8891,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 = {
@@ -8381,10 +9238,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;
@@ -8400,7 +9257,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;
       }
@@ -8416,7 +9273,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;
     }
@@ -8436,7 +9293,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);
@@ -8457,7 +9314,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);
@@ -8479,7 +9336,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 {
@@ -8901,8 +9758,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/);
@@ -8974,7 +9831,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) };
@@ -9061,7 +9918,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);
@@ -9085,7 +9942,7 @@ function missingPieces(input) {
     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;
@@ -9281,8 +10138,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 = {};
@@ -9438,19 +10295,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) {
@@ -9907,11 +10764,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);
@@ -9922,6 +10779,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) {
@@ -9941,6 +11171,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,
@@ -10268,6 +11499,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 };
@@ -10419,8 +11669,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;
@@ -10477,12 +11727,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 };
@@ -10494,8 +11744,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-F2PTXW5B.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",
@@ -10528,7 +11778,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,
@@ -10772,6 +12022,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;
@@ -10891,6 +12152,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
 
@@ -11054,7 +12326,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",
@@ -11162,7 +12434,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);
@@ -11198,7 +12471,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], {
@@ -11305,13 +12607,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 };
   };
@@ -11319,7 +12626,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);
@@ -11329,7 +12637,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,
@@ -11337,8 +12646,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,
@@ -11348,6 +12657,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 } : {},
@@ -11453,7 +12763,10 @@ async function pushFigmaComponentOp(ctx, a) {
   const { config } = await ctx.config();
   const set = await ctx.tokens();
   const tokens = await tokenFacts(ctx, set, d.component);
-  const gh = a.dryRun ? await reader(ctx) : await writer(ctx, "Sending a component change from Figma", NEED2);
+  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, {
@@ -11464,11 +12777,19 @@ async function pushFigmaComponentOp(ctx, a) {
     labels: [...config.governance.labels, `source: ${source}`],
     tool,
     dryRun: a.dryRun,
-    writeTokens: async ({ edits, title, summary: summary2, bodyExtra }) => {
+    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 };
     }
@@ -11482,20 +12803,22 @@ async function pushFigmaComponentOp(ctx, a) {
     ...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 } : {},
-    next: r.status === "dry-run" ? "Run it without dryRun to open the library branch." : r.status === "not-sent" ? "Nothing was sent: fix these in Figma, then push again." : 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."
+    ...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.6.0" : "dev";
+var VERSION = true ? "0.7.1" : "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.');
@@ -11510,6 +12833,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 },
@@ -11517,6 +12841,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.",
@@ -11658,7 +12983,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."),
@@ -11667,11 +12992,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 = {
@@ -11705,11 +13031,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",
@@ -11801,17 +13127,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",
@@ -11945,7 +13272,7 @@ function createServer(ctx) {
           ]
         };
       } catch (e) {
-        return fail(e);
+        return fail2(e);
       }
     }
   );
@@ -12042,8 +13369,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" }))
@@ -12112,11 +13439,11 @@ function createServer(ctx) {
     "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. dryRun shows the route. 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() },
+      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" }))
+    run((a) => pushFigmaComponentOp(ctx, { diff: a.diff, dryRun: a.dryRun, source: "mcp", changes: a.changes }))
   );
   server.registerTool(
     "bridge_list_products",
@@ -12307,7 +13634,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"}.'),
@@ -12316,11 +13643,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();
@@ -12537,6 +13953,7 @@ export {
   auditSnippet,
   branches_exports,
   explorations_exports,
+  suggestions_exports,
   ops_exports,
   history_exports,
   brand_exports,