@bridge-ds/mcp 0.11.2 → 0.11.3

package/dist/{chunk-P2UU6IKZ.js → chunk-OXK3RUVO.js}

@@ -1212,113 +1212,395 @@ function protectionSentence(state) {
   }
 }
 
-// ../core/src/github-client.ts
-var GitHubError = class extends Error {
-  constructor(status, message, detail, info = {}) {
-    super(message);
-    this.status = status;
-    this.detail = detail;
-    this.name = "GitHubError";
-    this.auth = info.auth;
-    this.permission = info.permission;
-    this.resetsAt = info.resetsAt;
-  }
-  status;
-  detail;
-  /** Set when the failure is about the token: rejected (401) or missing a permission (403). */
-  auth;
-  /** With auth "missing-permission": the permission the call needed, when known. */
-  permission;
-  /** For a rate limit (status 429): when the limit resets, when known. */
-  resetsAt;
-};
-var PERMISSION_LABELS = {
-  issues: "Issues",
-  pull_requests: "Pull requests",
-  contents: "Contents",
-  checks: "Checks",
-  statuses: "Commit statuses",
-  metadata: "Metadata",
-  actions: "Actions",
-  deployments: "Deployments",
-  workflows: "Workflows",
-  administration: "Administration"
+// ../core/src/explorations.ts
+var EXPLORATION_LABEL = "exploration";
+var EXPLORATION_PREFIX = "explore/";
+var EXPLORATION_NOTES_DIR = ".bridge/explorations";
+var EXPLORATION_CHECK = "Exploration not merged as is";
+var EXPLORATION_READY_LABEL = "ready-for-devs";
+var EXPLORATION_ARCHIVED_LABEL = "archived";
+var EXPLORATION_USE_CASES = [
+  { value: "user-test", label: "Prototype for a user test", hint: "A coded prototype in a test version of a product, with the real components and tokens." },
+  { value: "stakeholder-demo", label: "Stakeholder demo", hint: "Show an idea on real screens before anyone signs off on it." },
+  { value: "ab-idea", label: "A/B idea", hint: "Ship a variant to a test version of a product and compare it with what is live." },
+  { value: "terminal", label: "Exploring with Claude Code", hint: "A designer works from the terminal with Claude and the Bridge MCP server inside this exploration, never in the library." },
+  { value: "other", label: "Other", hint: "Anything else worth trying before it becomes a change." }
+];
+var EXPLORATION_STATUS_LABEL = {
+  active: "Running",
+  ready: "Waiting for code",
+  building: "Being built",
+  shipped: "Shipped",
+  promoted: "Promoted to review",
+  closed: "Closed"
 };
-function permissionLabel(permission) {
-  return PERMISSION_LABELS[permission] ?? permission.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+var MARK = "bridge-exploration";
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var EXPLORATION_SLUG_MAX = 60;
+function explorationSlug(name) {
+  const s = name.trim().replace(/^explore\//i, "");
+  if (!/[a-z0-9]/i.test(s)) return "";
+  return slugify(s, EXPLORATION_SLUG_MAX);
 }
-var TOKEN_REJECTED_MESSAGE = "Your GitHub token stopped working. It was revoked, regenerated or has expired: replace it with a new one.";
-function missingPermissionMessage(permission, action) {
-  const what = action ? `This token cannot ${action}.` : "This token is missing a permission for this.";
-  if (!permission) return `${what} Check its repository permissions on GitHub (Contents and Pull requests need Read and write).`;
-  return `${what} Add ${permissionLabel(permission)}: Read and write on GitHub.`;
+function explorationBranch(nameOrBranch) {
+  return `${EXPLORATION_PREFIX}${explorationSlug(nameOrBranch)}`;
 }
-function requiredPermission(path, acceptedHeader) {
-  if (acceptedHeader) {
-    const first2 = acceptedHeader.split(";")[0].split(",").map((p2) => p2.trim().split("=")[0].trim()).filter((p2) => p2 && p2 !== "metadata");
-    if (first2.length) return first2[0];
+function isExplorationBranch(ref) {
+  const r = (ref ?? "").replace(/^refs\/heads\//, "");
+  return r.startsWith(EXPLORATION_PREFIX) && SLUG_RE.test(r.slice(EXPLORATION_PREFIX.length));
+}
+var REPO_NAME = /^[\w.-]+\/[\w.-]+$/;
+var KEY_NAME = /^[a-z0-9][a-z0-9-]*$/i;
+function parseExplorationRef(input) {
+  if (typeof input === "number") return { ref: input };
+  const s = input.trim();
+  const link = /^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/i.exec(s);
+  if (link) return { repo: `${link[1]}/${link[2]}`, ref: Number(link[3]) };
+  if (/^#?\d+$/.test(s)) return { ref: Number(s.replace(/^#/, "")) };
+  const hash = /^(.+)#(\d+)$/.exec(s);
+  if (hash) {
+    const where2 = hash[1].trim();
+    if (REPO_NAME.test(where2)) return { repo: where2, ref: Number(hash[2]) };
+    if (KEY_NAME.test(where2)) return { product: where2.toLowerCase(), ref: Number(hash[2]) };
   }
-  const p = path.replace(/[?#].*$/, "");
-  if (/\/repos\/[^/]+\/[^/]+\/(issues|labels|milestones)(\/|$)/.test(p)) return "issues";
-  if (/\/repos\/[^/]+\/[^/]+\/pulls(\/|$)/.test(p)) return "pull_requests";
-  if (/\/repos\/[^/]+\/[^/]+\/(rulesets(\/|$)|branches\/.+\/protection$)/.test(p)) return "administration";
-  if (/\/repos\/[^/]+\/[^/]+\/(contents|git|commits|branches|merges)(\/|$)/.test(p)) return "contents";
-  if (/\/repos\/[^/]+\/[^/]+\/(check-runs|check-suites)(\/|$)/.test(p)) return "checks";
-  if (/\/repos\/[^/]+\/[^/]+\/statuses(\/|$)/.test(p)) return "statuses";
-  if (/\/repos\/[^/]+\/[^/]+\/deployments(\/|$)/.test(p)) return "deployments";
-  if (/\/repos\/[^/]+\/[^/]+\/actions(\/|$)/.test(p)) return "actions";
-  return void 0;
+  const named = /^([a-z0-9][a-z0-9-]*):(.+)$/i.exec(s);
+  if (named) return { product: named[1].toLowerCase(), ref: /^#?\d+$/.test(named[2].trim()) ? Number(named[2].trim().replace(/^#/, "")) : named[2].trim() };
+  return { ref: s };
 }
-var PERMISSION_DENIED = /not accessible by (personal access token|integration)|must have (admin|push|write) (rights|access)|write access to repository not granted|permission to .* denied/i;
-function classifyAuth(status, detail, opts = {}) {
-  if (status === 401 && opts.withToken !== false) return { auth: "rejected" };
-  if (status !== 403 || /rate limit|archived/i.test(detail)) return {};
-  if (opts.acceptedPermissions || PERMISSION_DENIED.test(detail)) {
-    return { auth: "missing-permission", permission: requiredPermission(opts.path ?? "", opts.acceptedPermissions) };
+var explorationRefLabel = (x) => x.repo && x.product ? `${x.product}#${x.number}` : `#${x.number}`;
+var explorationNotePath = (slug3) => `${EXPLORATION_NOTES_DIR}/${slug3}.md`;
+function explorationProblems(e) {
+  const out = [];
+  const name = e.name.trim();
+  const slug3 = e.slug?.trim() || explorationSlug(name);
+  if (!name) out.push('Name the exploration, for example "Denser data tables".');
+  else if (name.length > 60) out.push("Keep the name under 60 characters: it becomes the exploration's link name.");
+  else if (slug3.length < 2 || !SLUG_RE.test(slug3)) out.push("Use letters or digits in the name: it becomes the exploration's link name.");
+  return out;
+}
+var useCaseLabel = (u) => EXPLORATION_USE_CASES.find((x) => x.value === u)?.label;
+function explorationNote(e) {
+  const slug3 = e.slug || explorationSlug(e.name);
+  const uc = useCaseLabel(e.useCase);
+  return [
+    `# Exploration: ${e.name.trim()}`,
+    "",
+    ...e.purpose?.trim() ? [e.purpose.trim(), ""] : [],
+    `- Branch: \`${EXPLORATION_PREFIX}${slug3}\``,
+    ...uc ? [`- Use case: ${uc}`] : [],
+    ...e.startedAt ? [`- Started: ${e.startedAt.slice(0, 10)}${e.author ? ` by @${e.author}` : ""}`] : [],
+    "",
+    'This file marks the branch as an exploration. It is never merged as is: "Done exploring" removes it before developers take the branch.',
+    ""
+  ].join("\n");
+}
+function explorationPrTitle(e) {
+  const n = e.name.trim().replace(/\.$/, "").replace(/^exploration\s*:\s*/i, "").replace(/\s*:\s+/g, ", ").trim();
+  return `Exploration: ${n}`;
+}
+function explorationPrBody(e, ctx) {
+  const slug3 = e.slug || explorationSlug(e.name);
+  const branch = `${EXPLORATION_PREFIX}${slug3}`;
+  const uc = useCaseLabel(e.useCase);
+  const experimental = (e.experimental ?? []).map((x) => x.trim()).filter(Boolean);
+  const lines2 = [
+    `## Exploration: ${e.name.trim()}`,
+    "",
+    `> Not mergeable as is. This draft pull request is a living prototype on \`${branch}\`: say "Done exploring" when the idea is ready for developers. Keep it open, so its preview link keeps working.`,
+    "",
+    ...e.purpose?.trim() ? [`**Purpose.** ${e.purpose.trim()}`, ""] : [],
+    ...uc ? [`**Use case.** ${uc}`, ""] : [],
+    "### What is experimental",
+    "",
+    ...experimental.length ? experimental.map((x) => `- ${x}`) : [ctx.inProduct ? `- The ${ctx.inProduct.name} screens and flows built on this branch with the library. Nothing here reaches main or production.` : "- Token edits and component work committed to this branch. Nothing here reaches main or production."],
+    ...ctx.requests?.length ? ["", "Requests implemented here:", ...ctx.requests.map((r) => `- #${r.number} ${r.title}`)] : [],
+    ""
+  ];
+  if (ctx.inProduct) {
+    const p = ctx.inProduct;
+    lines2.push(
+      "### Work on it",
+      "",
+      `This exploration lives in the ${p.name} repository, so it runs in your usual environment: \`git fetch origin && git switch ${branch}\`, then start ${p.name} as you always do.`,
+      "",
+      `The library comes from npm, as on main. To try library changes that are not released yet, install the snapshot of their branch in ${p.library} (\`npm i @bridge-ds/react@<snapshot>\`): the command is in its "Try this exploration in your product" comment. Library changes are made in ${p.library}, never on this branch.`,
+      "",
+      "### Previews",
+      ""
+    );
+    const url = p.preview ? previewUrl(p.preview, { branch, ...ctx.pr ? { pr: ctx.pr } : {} }) : null;
+    if (p.preview) lines2.push("| App | Preview |", "| --- | --- |", `| ${p.name} | ${url ?? "Link in the Vercel comment on this pull request"} |`);
+    else lines2.push(`The preview deploys of ${p.name}, if it has them, build this branch like any other.`);
+  } else {
+    lines2.push(
+      "### Try it in a product staging branch",
+      "",
+      'In the product repo, on a branch that deploys to staging (production keeps the released version), install the snapshot with the command in the "Try this exploration in your product" comment below. It appears a few minutes after each push and always matches the latest commit.'
+    );
+    lines2.push("", "### Previews", "");
+    const links = resolveBranchPreviews(ctx.apps, { branch, ...ctx.pr ? { pr: ctx.pr } : {} });
+    if (links.length) lines2.push("| App | Preview |", "| --- | --- |", ...links.map((l) => `| ${l.label} | ${l.url ?? "Link in the Vercel comment on this pull request"} |`));
+    else lines2.push("Preview deploys are not set up: add `previews.apps` to `bridge.config.json` (docs/PREVIEWS.md).");
   }
-  return {};
+  lines2.push(
+    "",
+    "### When it is done",
+    "",
+    `- **Done exploring:** on the exploration's page in Bridge Studio, or \`bridge explore done ${slug3}\`. Bridge removes the \`${EXPLORATION_LABEL}\` label and the exploration note, adds \`${EXPLORATION_READY_LABEL}\`, and sends the pieces the designer picks to the DS lead as requests. Nothing is closed or merged: developers continue on \`${branch}\`.`,
+    `- **Archive:** \`bridge explore archive ${slug3}\` adds the \`${EXPLORATION_ARCHIVED_LABEL}\` label. Keep this pull request open: ${ctx.inProduct ? "Bridge follows open explorations, and its preview link is how people come back to the prototype." : "closing it removes the preview prerelease."}`,
+    "",
+    explorationBlock({ ...e, slug: slug3 })
+  );
+  return lines2.join("\n");
 }
-function memoryEtagStore(max = 500) {
-  const map = /* @__PURE__ */ new Map();
-  return {
-    get(key) {
-      const e = map.get(key);
-      if (e) {
-        map.delete(key);
-        map.set(key, e);
-      }
-      return e;
-    },
-    set(key, entry) {
-      map.delete(key);
-      map.set(key, entry);
-      while (map.size > max) map.delete(map.keys().next().value);
-    },
-    clear: () => map.clear()
+function explorationBlock(e) {
+  const experimental = (e.experimental ?? []).map((x) => x.trim()).filter(Boolean);
+  const data = {
+    name: e.name.trim(),
+    purpose: (e.purpose ?? "").trim(),
+    slug: e.slug || explorationSlug(e.name),
+    ...e.useCase ? { useCase: e.useCase } : {},
+    ...experimental.length ? { experimental } : {},
+    ...e.author ? { author: e.author } : {},
+    ...e.startedAt ? { startedAt: e.startedAt } : {},
+    ...e.source ? { source: e.source } : {},
+    ...e.agent ? { agent: e.agent } : {},
+    ...e.doneAt ? { doneAt: e.doneAt } : {},
+    ...e.doneSha ? { doneSha: e.doneSha } : {}
   };
+  return `<!-- ${MARK} ${JSON.stringify(data).replace(/-->/g, "--\\u003e")} -->`;
 }
-var sharedEtags = memoryEtagStore();
-function tokenFingerprint(token) {
-  if (!token) return "anon";
-  let a = 2166136261;
-  let b = 16777619 ^ token.length;
-  for (let i = 0; i < token.length; i++) {
-    const c = token.charCodeAt(i);
-    a = Math.imul(a ^ c, 16777619) >>> 0;
-    b = Math.imul(b ^ c ^ i & 255, 1540483477) >>> 0;
+function parseExplorationBody(body) {
+  if (!body) return void 0;
+  const m = new RegExp(`<!-- ${MARK} (\\{[\\s\\S]*?\\}) -->`).exec(body);
+  if (!m) return void 0;
+  try {
+    const e = JSON.parse(m[1]);
+    if (!e || typeof e.name !== "string") return void 0;
+    return typeof e.purpose === "string" ? e : e.purpose === void 0 ? { ...e, purpose: "" } : void 0;
+  } catch {
+    return void 0;
   }
-  return a.toString(16).padStart(8, "0") + b.toString(16).padStart(8, "0");
 }
-function installationFor(list, owner) {
-  const inst = list.find((i) => i.account?.login?.toLowerCase() === owner.toLowerCase());
-  if (!inst) return { reach: "no" };
-  const selection = inst.repositorySelection ?? inst.repository_selection;
-  return selection === "all" ? { reach: "yes", id: inst.id } : { reach: "check", id: inst.id };
+var labelNames = (labels) => labels.map((l) => typeof l === "string" ? l : l.name ?? "");
+function isExplorationPull(p) {
+  return isExplorationBranch(p.headRef) || labelNames(p.labels).includes(EXPLORATION_LABEL) || Boolean(parseExplorationBody(p.body));
 }
-var MAX_PAGES = 10;
-function rateLimitMessage(x) {
-  const when = x.resetsAt ? ` It resets at ${x.resetsAt.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}.` : "";
-  if (x.withToken) return `GitHub's hourly request limit for this token is used up.${when} Try again after that.`;
+function isUnlabeledExploration(p) {
+  if (p.state !== "open" || p.draft !== true) return false;
+  const names4 = labelNames(p.labels ?? []);
+  if (names4.includes(EXPLORATION_LABEL) || names4.includes(EXPLORATION_ARCHIVED_LABEL) || names4.includes(EXPLORATION_READY_LABEL)) return false;
+  const block = parseExplorationBody(p.body);
+  if (block?.doneAt) return false;
+  return isExplorationBranch(p.headRef) || Boolean(block);
+}
+function isHandedOff(p) {
+  return labelNames(p.labels).includes(EXPLORATION_READY_LABEL) || Boolean(parseExplorationBody(p.body)?.doneAt);
+}
+function explorationStatus(p) {
+  const merged = Boolean(p.merged || p.merged_at || p.state === "merged");
+  if (p.state !== "open" && !merged) return "closed";
+  if (p.state === "open" && (labelNames(p.labels).includes(EXPLORATION_LABEL) || isUnlabeledExploration(p))) return "active";
+  if (!isHandedOff(p)) return "promoted";
+  if (merged) return "shipped";
+  if (p.draft === false) return "building";
+  const doneSha = parseExplorationBody(p.body)?.doneSha;
+  if (doneSha && p.headSha && p.headSha !== doneSha) return "building";
+  return "ready";
+}
+function isGuardedExploration(p) {
+  if (p.state !== void 0 && p.state !== "open") return false;
+  if (labelNames(p.labels ?? []).includes(EXPLORATION_LABEL)) return true;
+  return isUnlabeledExploration({ state: "open", draft: p.draft, labels: p.labels, headRef: p.headRef ?? p.head?.ref, body: p.body });
+}
+var isExplorationCheck = (name) => (name ?? "").trim() === EXPLORATION_CHECK;
+var isActiveExploration = (labels) => labelNames(labels).includes(EXPLORATION_LABEL);
+var isArchivedExploration = (labels) => labelNames(labels ?? []).includes(EXPLORATION_ARCHIVED_LABEL);
+function isHeldExploration(p) {
+  if (p.state !== void 0 && p.state !== "open") return false;
+  const names4 = labelNames(p.labels ?? []);
+  if (names4.includes(EXPLORATION_LABEL) || names4.includes(EXPLORATION_ARCHIVED_LABEL)) return true;
+  if (isUnlabeledExploration({ state: "open", draft: p.draft, labels: p.labels, headRef: p.headRef ?? p.head?.ref, body: p.body })) return true;
+  return names4.includes(EXPLORATION_READY_LABEL) && p.draft !== false;
+}
+var explorationTakeCommands = (branch) => ["git fetch origin", `git checkout ${branch}`];
+var CONTINUE = "Continue on this branch: its pull request already exists, so Bridge follows your pushes, and the merge reads as shipped.";
+var EXPLORATION_STARTING_POINT = `A starting point, not ready to ship: nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
+function explorationStartingPoint(checks) {
+  switch (checks) {
+    case "success":
+      return `A starting point: its checks pass, but nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
+    case "failure":
+      return `A starting point, not ready to ship: some checks fail on this branch and nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
+    case "pending":
+      return `A starting point, not ready to ship: its checks are still running and nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
+    case "none":
+      return `A starting point, not ready to ship: no checks ran on this branch and nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
+    default:
+      return EXPLORATION_STARTING_POINT;
+  }
+}
+function doneExploringPlan(input) {
+  const removeFiles = input.files.filter((f) => f.path.startsWith(`${EXPLORATION_NOTES_DIR}/`) && f.status !== "removed").map((f) => f.path);
+  return {
+    removeLabels: [EXPLORATION_LABEL],
+    addLabels: [EXPLORATION_READY_LABEL],
+    removeFiles,
+    body: withDoneExploring(input.body, { branch: input.branch, doneAt: (input.date ?? /* @__PURE__ */ new Date()).toISOString() }),
+    take: explorationTakeCommands(input.branch),
+    markReady: false
+  };
+}
+var DEV_SECTION = "### For developers";
+function withDoneExploring(body, done) {
+  const e = parseExplorationBody(body);
+  const [fetch2, checkout] = explorationTakeCommands(done.branch);
+  const section = [
+    DEV_SECTION,
+    "",
+    `**Done exploring on ${done.doneAt.slice(0, 10)}.** ${explorationStartingPoint(done.checks)}`,
+    "",
+    "```sh",
+    fetch2,
+    checkout,
+    "```",
+    "",
+    "Mark this pull request ready for review when the code is yours. Keep it open: its preview link is how designers, the DS lead and stakeholders come back to the prototype."
+  ].join("\n");
+  const block = new RegExp(`<!-- ${MARK} \\{[\\s\\S]*?\\} -->`);
+  const kept = (body ?? "").replace(/^> Not mergeable as is\..*$\n?\n?/m, "").replace(/### When it is done[\s\S]*?(?=<!-- |$)/, "").replace(/### For developers[\s\S]*?(?=### |<!-- |$)/, "");
+  if (!e || !block.test(kept)) return `${kept.trim()}${kept.trim() ? "\n\n" : ""}${section}`;
+  const at = kept.search(block);
+  const nextBlock = explorationBlock({ ...e, doneAt: done.doneAt, ...done.doneSha ? { doneSha: done.doneSha } : {} });
+  const after = kept.slice(at).replace(block, () => nextBlock).trim();
+  return `${kept.slice(0, at).trim()}
+
+${section}
+
+${after}`.trim();
+}
+function explorationTryIt(input) {
+  const c = readPreviewComment(input.comment);
+  if (!c) return { state: "building" };
+  if (input.headSha && c.sha7 && !input.headSha.startsWith(c.sha7)) return { state: "building" };
+  if (!c.command || c.source === "none") return { state: "failed" };
+  return { state: "ready", command: c.command, source: c.source, sha7: c.sha7 };
+}
+function explorationRules(branch) {
+  return [
+    `- Work on the existing branch ${branch} (git fetch origin && git switch ${branch}). Commit there.`,
+    `- Do not open a pull request to main and do not create another branch: the draft pull request of ${branch} is the place. It stays open as a living prototype.`,
+    `- Do not mark the pull request ready for review, do not remove the exploration label and never close it: "Done exploring" is a person's decision, and closing removes its preview.`
+  ];
+}
+
+// ../core/src/github-client.ts
+var GitHubError = class extends Error {
+  constructor(status, message, detail, info = {}) {
+    super(message);
+    this.status = status;
+    this.detail = detail;
+    this.name = "GitHubError";
+    this.auth = info.auth;
+    this.permission = info.permission;
+    this.resetsAt = info.resetsAt;
+  }
+  status;
+  detail;
+  /** Set when the failure is about the token: rejected (401) or missing a permission (403). */
+  auth;
+  /** With auth "missing-permission": the permission the call needed, when known. */
+  permission;
+  /** For a rate limit (status 429): when the limit resets, when known. */
+  resetsAt;
+};
+var PERMISSION_LABELS = {
+  issues: "Issues",
+  pull_requests: "Pull requests",
+  contents: "Contents",
+  checks: "Checks",
+  statuses: "Commit statuses",
+  metadata: "Metadata",
+  actions: "Actions",
+  deployments: "Deployments",
+  workflows: "Workflows",
+  administration: "Administration"
+};
+function permissionLabel(permission) {
+  return PERMISSION_LABELS[permission] ?? permission.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
+var TOKEN_REJECTED_MESSAGE = "Your GitHub token stopped working. It was revoked, regenerated or has expired: replace it with a new one.";
+function missingPermissionMessage(permission, action) {
+  const what = action ? `This token cannot ${action}.` : "This token is missing a permission for this.";
+  if (!permission) return `${what} Check its repository permissions on GitHub (Contents and Pull requests need Read and write).`;
+  return `${what} Add ${permissionLabel(permission)}: Read and write on GitHub.`;
+}
+function requiredPermission(path, acceptedHeader) {
+  if (acceptedHeader) {
+    const first2 = acceptedHeader.split(";")[0].split(",").map((p2) => p2.trim().split("=")[0].trim()).filter((p2) => p2 && p2 !== "metadata");
+    if (first2.length) return first2[0];
+  }
+  const p = path.replace(/[?#].*$/, "");
+  if (/\/repos\/[^/]+\/[^/]+\/(issues|labels|milestones)(\/|$)/.test(p)) return "issues";
+  if (/\/repos\/[^/]+\/[^/]+\/pulls(\/|$)/.test(p)) return "pull_requests";
+  if (/\/repos\/[^/]+\/[^/]+\/(rulesets(\/|$)|branches\/.+\/protection$)/.test(p)) return "administration";
+  if (/\/repos\/[^/]+\/[^/]+\/(contents|git|commits|branches|merges)(\/|$)/.test(p)) return "contents";
+  if (/\/repos\/[^/]+\/[^/]+\/(check-runs|check-suites)(\/|$)/.test(p)) return "checks";
+  if (/\/repos\/[^/]+\/[^/]+\/statuses(\/|$)/.test(p)) return "statuses";
+  if (/\/repos\/[^/]+\/[^/]+\/deployments(\/|$)/.test(p)) return "deployments";
+  if (/\/repos\/[^/]+\/[^/]+\/actions(\/|$)/.test(p)) return "actions";
+  return void 0;
+}
+var PERMISSION_DENIED = /not accessible by (personal access token|integration)|must have (admin|push|write) (rights|access)|write access to repository not granted|permission to .* denied/i;
+function classifyAuth(status, detail, opts = {}) {
+  if (status === 401 && opts.withToken !== false) return { auth: "rejected" };
+  if (status !== 403 || /rate limit|archived/i.test(detail)) return {};
+  if (opts.acceptedPermissions || PERMISSION_DENIED.test(detail)) {
+    return { auth: "missing-permission", permission: requiredPermission(opts.path ?? "", opts.acceptedPermissions) };
+  }
+  return {};
+}
+function memoryEtagStore(max = 500) {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      const e = map.get(key);
+      if (e) {
+        map.delete(key);
+        map.set(key, e);
+      }
+      return e;
+    },
+    set(key, entry) {
+      map.delete(key);
+      map.set(key, entry);
+      while (map.size > max) map.delete(map.keys().next().value);
+    },
+    clear: () => map.clear()
+  };
+}
+var sharedEtags = memoryEtagStore();
+function tokenFingerprint(token) {
+  if (!token) return "anon";
+  let a = 2166136261;
+  let b = 16777619 ^ token.length;
+  for (let i = 0; i < token.length; i++) {
+    const c = token.charCodeAt(i);
+    a = Math.imul(a ^ c, 16777619) >>> 0;
+    b = Math.imul(b ^ c ^ i & 255, 1540483477) >>> 0;
+  }
+  return a.toString(16).padStart(8, "0") + b.toString(16).padStart(8, "0");
+}
+function installationFor(list, owner) {
+  const inst = list.find((i) => i.account?.login?.toLowerCase() === owner.toLowerCase());
+  if (!inst) return { reach: "no" };
+  const selection = inst.repositorySelection ?? inst.repository_selection;
+  return selection === "all" ? { reach: "yes", id: inst.id } : { reach: "check", id: inst.id };
+}
+var MAX_PAGES = 10;
+function rateLimitMessage(x) {
+  const when = x.resetsAt ? ` It resets at ${x.resetsAt.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}.` : "";
+  if (x.withToken) return `GitHub's hourly request limit for this token is used up.${when} Try again after that.`;
   const hint = x.tokenHint ?? "add a GitHub token";
   return `GitHub's hourly limit for requests without a token (60 an hour) is used up.${when} To keep going now, ${hint}: a token gets 5,000 requests an hour.`;
 }
@@ -2020,8 +2302,11 @@ var GitHubClient = class _GitHubClient {
     const r = await this.request("GET", `${this.repoPath}/pulls?state=${state}&per_page=50&sort=updated&direction=desc`);
     return r.map(toSummary);
   }
-  /** Commit statuses and check runs of a commit, folded into one state. */
-  async getChecks(sha) {
+  /**
+   * Commit statuses and check runs of a commit, folded into one state. `exploration`: the commit heads an exploration
+   * (explorations isGuardedExploration), so its guard check, failing by design, is left out (as review-gate summarizeCi).
+   */
+  async getChecks(sha, opts = {}) {
     const [combined, runs] = await Promise.all([
       this.request("GET", `${this.repoPath}/commits/${encodeRef(sha)}/status`).catch(() => ({ statuses: [] })),
       this.listCheckRuns(sha).catch(() => [])
@@ -2029,7 +2314,7 @@ var GitHubClient = class _GitHubClient {
     const checks = [
       ...runs.map((c) => ({ name: c.name, status: c.status, conclusion: c.conclusion })),
       ...combined.statuses.map((s) => ({ name: s.context, status: s.state === "pending" ? "in_progress" : "completed", conclusion: s.state === "pending" ? null : s.state }))
-    ];
+    ].filter((c) => !(opts.exploration && isExplorationCheck(c.name)));
     const failing = checks.some((c) => c.conclusion && !["success", "neutral", "skipped"].includes(c.conclusion));
     const pending = checks.some((c) => c.status !== "completed");
     return { state: !checks.length ? "none" : failing ? "failure" : pending ? "pending" : "success", checks };
@@ -3483,641 +3768,366 @@ function composeNewBrandBody(plan, opts) {
     `- ${code("bridge.config.json")} is a guardrail file`,
     `- Semver bump: ${code(plan.risk.bump)} for ${code("@bridge-ds/tokens")}`,
     "",
-    "## Checks",
-    "",
-    `- Token validation: ${errors.length ? `**${errors.length} error(s)**` : "no errors"} (DTCG shapes, aliases, every mode)${warnings.length ? `, ${warnings.length} warning(s): ${warnings.map((w) => w.message).join(" ")}` : ""}`,
-    `- Contrast gate for ${plan.name}: ${plan.contrast.failing.length ? `**${plan.contrast.failing.length} failing pair(s)**` : `all ${plan.contrast.checks} pairs pass`}`,
-    "",
-    "## Authored by",
-    "",
-    opts.agent ? "- [ ] Human" : "- [x] Human",
-    opts.agent ? "- [x] AI agent (Claude), reviewed by a human before merge" : "- [ ] AI agent",
-    "",
-    "## Design review checklist",
-    "",
-    "- [ ] Checked in light and dark, with real components (Studio preview or Storybook brand switch)",
-    "- [ ] Primary, zone and link colors read as one family",
-    "- [ ] Changeset bump matches the tier",
-    ""
-  ].join("\n");
-}
-
-// ../core/src/docs-draft.ts
-var DOCS_KEYS = ["summary", "preview", "whenToUse", "whenNotToUse", "dos", "donts", "accessibility", "contentGuidelines", "anatomy"];
-var PROSE_KEYS = ["summary", "whenToUse", "whenNotToUse", "dos", "donts", "accessibility", "contentGuidelines"];
-var ACRONYMS = /* @__PURE__ */ new Set(["sm", "md", "lg", "xl", "xs"]);
-function anatomyLabel(className) {
-  if (ACRONYMS.has(className)) return `Size ${className}`;
-  const words = className.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").trim().toLowerCase();
-  if (!words) return className;
-  if (words === "root") return "Container";
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
-function cssModuleClasses(css) {
-  const clean = css.replace(/\/\*[\s\S]*?\*\//g, "").replace(/@keyframes\s+[\w-]+\s*\{(?:[^{}]*\{[^{}]*\})*[^{}]*\}/g, "");
-  const out = [];
-  for (const m of clean.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)) {
-    const before = clean[m.index - 1] ?? " ";
-    if (/[\w)]/.test(before)) continue;
-    if (!out.includes(m[1])) out.push(m[1]);
-  }
-  return out;
-}
-var cell = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
-function propsTable(name, props, inherits) {
-  if (!props.length) return inherits ? `${name} has no props of its own. It accepts every native <${inherits}> attribute.` : "";
-  const rows = props.map((p) => `| \`${p.name}\`${p.required ? " (required)" : ""} | \`${cell(p.type)}\` | ${p.defaultValue ? `\`${cell(p.defaultValue)}\`` : ""} | ${cell(p.description ?? "")} |`);
-  const tail = inherits ? `
-
-Also accepts every native <${inherits}> attribute.` : "";
-  return ["| Prop | Type | Default | Description |", "| --- | --- | --- | --- |", ...rows].join("\n") + tail;
-}
-var isEmpty = (v) => v === void 0 || v === null || typeof v === "string" && !v.trim() || Array.isArray(v) && v.length === 0;
-function missingProse(d) {
-  return PROSE_KEYS.filter((k) => isEmpty(d?.[k]));
-}
-function prefillDocs(input) {
-  const existing = input.existing ?? null;
-  const anatomy = {};
-  for (const c of input.cssClasses) anatomy[c] = existing?.anatomy?.[c] ?? anatomyLabel(c);
-  const contrastNotes = (input.contrast ?? []).slice().sort((a, b) => a.ratio - b.ratio).map((p) => `${p.foreground} on ${p.background}: ${p.ratio.toFixed(2)}:1 at worst over every brand and theme, needs ${p.min}:1 (${p.ratio >= p.min ? "passes" : "fails"}).`);
-  const missing = missingProse(existing);
-  const changelogLine = input.change ? `${input.name}: ${input.change.replace(/\.$/, "")}.` : missing.length === PROSE_KEYS.length ? `${input.name}: usage guidance added.` : `${input.name}: usage guidance updated.`;
-  const draft = {
-    summary: existing?.summary ?? input.description ?? "",
-    ...existing?.category ? { category: existing.category } : {},
-    ...existing?.status ? { status: existing.status } : {},
-    ...existing?.preview ? { preview: existing.preview } : {},
-    whenToUse: existing?.whenToUse ?? [],
-    whenNotToUse: existing?.whenNotToUse ?? [],
-    dos: existing?.dos ?? [],
-    donts: existing?.donts ?? [],
-    accessibility: existing?.accessibility ?? [],
-    contentGuidelines: existing?.contentGuidelines ?? [],
-    anatomy,
-    ...existing?.draftedBy ? { draftedBy: existing.draftedBy } : {},
-    ...existing?.draftedSections?.length ? { draftedSections: existing.draftedSections } : {},
-    ...existing?.needsReview !== void 0 ? { needsReview: existing.needsReview } : {}
-  };
-  return {
-    component: input.name,
-    propsTable: propsTable(input.name, input.props, input.inherits),
-    tokens: [...new Set(input.tokens)].sort(),
-    inheritedTokens: input.inheritedTokens ?? {},
-    anatomy,
-    contrastNotes,
-    changelogLine,
-    missing,
-    draft
-  };
-}
-var SECTION_SHAPE = {
-  summary: '"summary": "one or two sentences"',
-  whenToUse: '"whenToUse": ["..."]',
-  whenNotToUse: '"whenNotToUse": ["..."]',
-  dos: '"dos": [{ "title": "...", "text": "..." }]',
-  donts: '"donts": [{ "title": "...", "text": "..." }]',
-  accessibility: '"accessibility": ["..."]',
-  contentGuidelines: '"contentGuidelines": ["..."]'
-};
-var docsSectionShapes = (keys) => `{ ${keys.map((k) => SECTION_SHAPE[k]).join(", ")} }`;
-function docsPrompt(prefill, conventions = {}, options = {}) {
-  const facts = [
-    `Component: ${prefill.component}`,
-    prefill.propsTable ? `Props (parsed from TypeScript):
-${prefill.propsTable}` : "Props: none of its own.",
-    `Tokens its stylesheet reads: ${prefill.tokens.join(", ") || "none"}`,
-    ...Object.entries(prefill.inheritedTokens).map(([from, list]) => `Tokens it reads through ${from}'s stylesheet: ${list.length}`),
-    `Anatomy (CSS module classes): ${Object.entries(prefill.anatomy).map(([k, v]) => `${k} = ${v}`).join("; ") || "none"}`,
-    prefill.contrastNotes.length ? `Contrast checks:
-- ${prefill.contrastNotes.join("\n- ")}` : "",
-    `Changelog line: ${prefill.changelogLine}`
-  ].filter(Boolean);
-  const block = (title, text) => text?.trim() ? `<${title}>
-${text.trim()}
-</${title}>` : "";
-  const keys = options.keys;
-  const check = keys ? (options.check ?? []).filter((k) => keys.includes(k)) : [];
-  const write = keys ? keys.filter((k) => !check.includes(k)) : [];
-  const task = keys ? [
-    ...write.length ? [`${options.rewrite ? "Rewrite" : "Write"} these sections of ${prefill.component}.docs.json for the Bridge design system: ${write.join(", ")}.`] : [],
-    ...check.length ? [
-      `Check these written sections of ${prefill.component}.docs.json against the current code: ${check.join(", ")}. The code changed after they were written.`,
-      "Return a checked section ONLY when something in it is no longer true for the code (a wrong or removed prop, a removed state or variant, changed behavior). Then return the whole section with only the untrue parts fixed, keeping the writer's wording everywhere else.",
-      "Leave a checked section out of the answer when it is still accurate: a missing key means unchanged. Never return a checked section just to improve its style."
-    ] : [],
-    ...options.rewrite ? ["Rewrite each one from the facts and the source: keep what is true in the current text, drop what the code does not support."] : []
-  ] : [`Write the missing prose of ${prefill.component}.docs.json for the Bridge design system.`];
-  const shape2 = keys ? [
-    `- ${check.length ? "Return" : "Write"} only these keys: ${keys.join(", ")}${check.length ? ` (the checked ones, ${check.join(", ")}, only when they need a fix)` : ""}. Never return anatomy, preview or any other key: code decides them.`,
-    `- Answer with one JSON object holding only those keys, nothing else: ${docsSectionShapes(keys)}.`
-  ] : [
-    `- Fill only these keys: ${prefill.missing.join(", ") || "none (everything is written: improve nothing, return the draft as is)"}. Keep every other key exactly as given.`,
-    "- Answer with the full docs.json as one JSON object, nothing else."
-  ];
-  return [
-    ...task,
-    "",
-    "Rules:",
-    "- Ground every sentence in the facts and the source below. Never invent props, variants, keyboard behavior or tokens that are not there.",
-    "- Bridge voice: sentence case, plain words, verbs first, no em dashes, no marketing words.",
-    '- Keep the keys and shapes of the example docs.json. dos and donts are { "title", "text" } objects; add an "example" only with components and props that exist.',
-    ...shape2,
-    "",
-    "Facts computed from the code:",
-    facts.join("\n\n"),
-    "",
-    `Current draft:
-${JSON.stringify(prefill.draft, null, 2)}`,
-    "",
-    block("source", conventions.source),
-    block("styles", conventions.styles),
-    block("agents-md", conventions.agents),
-    block("voice", conventions.voice),
-    block("example-docs-json", conventions.example)
-  ].filter((x, i, all) => x !== "" || all[i - 1] !== "").join("\n");
-}
-function markClaudeDraft(d, sections2) {
-  if (!sections2) {
-    const { draftedSections: _all, ...rest } = d;
-    return { ...rest, draftedBy: "claude", needsReview: true };
-  }
-  const waiting = d.needsReview === true ? d.draftedSections ?? (d.draftedBy ? [...PROSE_KEYS] : []) : [];
-  const union = PROSE_KEYS.filter((k) => waiting.includes(k) || sections2.includes(k));
-  return { ...d, draftedBy: "claude", needsReview: true, draftedSections: union };
-}
-function formatDocsJson(d) {
-  const order = ["summary", "category", "status", ...DOCS_KEYS.filter((k) => k !== "summary"), "draftedBy", "draftedSections", "needsReview"];
-  const out = {};
-  for (const k of order) if (d[k] !== void 0) out[k] = d[k];
-  for (const [k, v] of Object.entries(d)) if (!(k in out) && v !== void 0) out[k] = v;
-  return `${JSON.stringify(out, null, 2)}
-`;
-}
-function patchNode(old, next) {
-  if (plainEqual(toPlain(old), next)) return old;
-  if (old.kind === "object" && next && typeof next === "object" && !Array.isArray(next)) {
-    const n = next;
-    const kept = old.entries.filter((e) => n[e.key] !== void 0).map((e) => ({ key: e.key, value: patchNode(e.value, n[e.key]) }));
-    const added = Object.keys(n).filter((k) => n[k] !== void 0 && !getEntry(old, k)).map((k) => ({ key: k, value: fromPlain(n[k], void 0, old.inline) }));
-    return { kind: "object", inline: old.inline, entries: [...kept, ...added] };
-  }
-  if (old.kind === "array" && Array.isArray(next)) {
-    return { kind: "array", inline: old.inline, items: next.map((v, i) => old.items[i] ? patchNode(old.items[i], v) : fromPlain(v, old.items[0], old.inline)) };
-  }
-  return fromPlain(next, old);
-}
-function patchDocsJson(original, next) {
-  const plain2 = JSON.parse(formatDocsJson(next));
-  if (!original) return formatDocsJson(next);
-  try {
-    const doc = parseJson(original);
-    if (doc.root.kind !== "object") return formatDocsJson(next);
-    return serializeJson({ ...doc, root: patchNode(doc.root, plain2) });
-  } catch {
-    return formatDocsJson(next);
-  }
-}
-
-// ../core/src/change-drafts.ts
-function cleanDraftText(text) {
-  return text.replace(/\s*\u2014\s*/g, ", ").replace(/,\s*,/g, ",").replace(/^,\s*/, "").replace(/[ \t]+/g, " ").trim();
-}
-var andList = (xs) => xs.length <= 1 ? xs[0] ?? "" : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`;
-var capital = (s) => s.charAt(0).toUpperCase() + s.slice(1);
-var VARIANT_FIRST = ["variant", "tone", "intent", "appearance", "kind", "type", "style"];
-function shortVariant(key) {
-  const pairs = key.split(", ").map((p) => {
-    const at = p.indexOf("=");
-    return at < 0 ? { k: "", v: p.trim() } : { k: p.slice(0, at).trim(), v: p.slice(at + 1).trim() };
-  });
-  const kept = pairs.filter((p) => p.v && !/^default$/i.test(p.v));
-  if (!kept.length) return key;
-  const rank2 = (k) => {
-    const i = VARIANT_FIRST.indexOf(k.toLowerCase());
-    return i < 0 ? VARIANT_FIRST.length : i;
-  };
-  return kept.map((p, i) => ({ ...p, i })).sort((a, b) => rank2(a.k) - rank2(b.k) || a.i - b.i).map((p) => p.v).join(" ");
-}
-var shortVariants = (list) => list ? andList(list.split("; ").map(shortVariant)) : "every variant";
-var DRAFT_LINE_MAX = 120;
-function clipText(text, max) {
-  const t = text.replace(/\s+/g, " ").trim().replace(/\.$/, "");
-  if (t.length <= max) return t;
-  const 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 "";
-  return capital(clipText(cleanDraftText(raw.replace(/[\r\n]+/g, " ")), DRAFT_LINE_MAX));
-}
-
-// ../core/src/docs-ai.ts
-var DOCS_DRAFT_MODEL = "claude-sonnet-5-5";
-var ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
-var DOCS_SELECTION_MODES = {
-  clearer: "Make it clearer: plain words, one idea per sentence, the most useful fact first.",
-  shorter: "Make it shorter: keep every fact, drop filler, aim for half the words or fewer.",
-  voice: "Put it in the Bridge voice: sentence case, verbs first, calm and precise, no marketing words, no em dash."
-};
-var isDocsSelectionMode = (m) => typeof m === "string" && m in DOCS_SELECTION_MODES;
-var isProseKey = (k) => typeof k === "string" && PROSE_KEYS.includes(k);
-function validateDocsTask(x) {
-  if (!x || typeof x !== "object") return ["The docs task is missing."];
-  const t = x;
-  if (t.kind === "sections") {
-    const keys = t.keys;
-    if (!Array.isArray(keys) || !keys.length || !keys.every(isProseKey)) return [`The docs task lists no sections: use ${PROSE_KEYS.join(", ")}.`];
-    if (t.check !== void 0 && (!Array.isArray(t.check) || !t.check.every(isProseKey))) return ["check must list prose sections."];
-    return [];
-  }
-  if (t.kind === "selection") {
-    const out = [];
-    if (!isProseKey(t.key)) out.push(`The selection needs a section: ${PROSE_KEYS.join(", ")}.`);
-    if (typeof t.text !== "string" || !t.text.trim()) out.push("The selection has no text.");
-    if (!isDocsSelectionMode(t.mode)) out.push("The selection mode must be clearer, shorter or voice.");
-    return out;
-  }
-  return ['The docs task kind must be "sections" or "selection".'];
-}
-var docsTaskKeys = (t) => t.kind === "sections" ? t.keys : [t.key];
-function parseDocsReply(text) {
-  const fenced2 = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
-  const body = fenced2 ? fenced2[1] : text;
-  const start = body.indexOf("{");
-  const end = body.lastIndexOf("}");
-  if (start < 0 || end <= start) throw new Error("The reply holds no JSON object.");
-  const json = JSON.parse(body.slice(start, end + 1));
-  if (!json || typeof json !== "object" || Array.isArray(json)) throw new Error("The reply is not a docs.json object.");
-  return json;
-}
-var cleanDocsText = (s) => cleanDraftText(s.replace(/[\r\n]+/g, " "));
-var isExample = (x) => {
-  if (typeof x === "string") return true;
-  if (!x || typeof x !== "object" || Array.isArray(x)) return false;
-  const n = x;
-  if (typeof n.c !== "string" || !n.c) return false;
-  if (n.p !== void 0 && (!n.p || typeof n.p !== "object" || Array.isArray(n.p))) return false;
-  return n.children === void 0 || Array.isArray(n.children) && n.children.every(isExample);
-};
-var textList = (x) => {
-  if (typeof x === "string") x = [x];
-  if (!Array.isArray(x)) return void 0;
-  const out = x.filter((s) => typeof s === "string").map(cleanDocsText).filter(Boolean);
-  return out.length ? out : void 0;
-};
-var guidanceList = (x, examples) => {
-  if (!Array.isArray(x)) return void 0;
-  const out = [];
-  for (const g of x) {
-    if (!g || typeof g !== "object") continue;
-    const r = g;
-    const title = typeof r.title === "string" ? cleanDocsText(r.title) : "";
-    const text = typeof r.text === "string" ? cleanDocsText(r.text) : "";
-    if (!title || !text) continue;
-    out.push({ title, text, ...examples && r.example !== void 0 && isExample(r.example) ? { example: r.example } : {} });
-  }
-  return out.length ? out : void 0;
-};
-function sanitizeDocsSections(raw, keys = PROSE_KEYS, opts = {}) {
-  const out = {};
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
-  const r = raw;
-  for (const k of keys) {
-    const v = r[k];
-    if (k === "summary") {
-      const s = typeof v === "string" ? cleanDocsText(v) : "";
-      if (s) out.summary = s;
-    } else if (k === "dos" || k === "donts") {
-      const g = guidanceList(v, opts.examples ?? false);
-      if (g) out[k] = g;
-    } else {
-      const l = textList(v);
-      if (l) out[k] = l;
-    }
-  }
-  return out;
-}
-function sanitizeDocsReplacement(raw) {
-  if (typeof raw !== "string") return "";
-  return cleanDocsText(raw.trim().replace(/^["'“]+|["'”]+$/g, ""));
-}
-function docsSectionsAnswer(task, raw) {
-  const check = (task.check ?? []).filter((k) => task.keys.includes(k));
-  const sections2 = check.length ? sanitizeDocsSections(raw, task.keys) : docsSectionsResult(task, raw);
-  return { sections: sections2, checked: check.filter((k) => sections2[k] === void 0) };
-}
-function docsSectionsResult(task, raw) {
-  const sections2 = sanitizeDocsSections(raw, task.keys);
-  if (!Object.keys(sections2).length) throw new Error(`Claude's answer holds none of the sections asked for (${task.keys.join(", ")}). Try again.`);
-  return sections2;
-}
-function mergeDocsDraft(prefillDraft, reply) {
-  const empty = PROSE_KEYS.filter((k) => {
-    const v = prefillDraft[k];
-    return v === void 0 || (typeof v === "string" ? !v.trim() : Array.isArray(v) && !v.length);
-  });
-  const sections2 = sanitizeDocsSections(reply, empty, { examples: true });
-  const merged = { ...prefillDraft, ...sections2 };
-  if (reply.preview && !prefillDraft.preview && isExample(reply.preview)) merged.preview = reply.preview;
-  merged.anatomy = prefillDraft.anatomy;
-  const drafted = PROSE_KEYS.filter((k) => sections2[k] !== void 0);
-  return markClaudeDraft(merged, drafted.length && drafted.length < PROSE_KEYS.length ? drafted : void 0);
-}
-function anthropicRequest(input) {
-  const headers = { "x-api-key": input.apiKey, "anthropic-version": "2023-06-01", "content-type": "application/json" };
-  if (input.fallback) headers["anthropic-beta"] = "server-side-fallback-2026-07-01";
-  if (input.browser) headers["anthropic-dangerous-direct-browser-access"] = "true";
-  const body = {
-    model: input.model || DOCS_DRAFT_MODEL,
-    max_tokens: input.maxTokens ?? 16e3,
-    ...input.fallback ? { fallbacks: "default" } : {},
-    ...input.system ? { system: input.system } : {},
-    messages: [{ role: "user", content: input.prompt }]
-  };
-  return { url: ANTHROPIC_MESSAGES_URL, init: { method: "POST", headers, body: JSON.stringify(body) } };
-}
-function anthropicReplyText(msg) {
-  const m = msg ?? {};
-  if (m.stop_reason === "refusal") throw new Error("Claude declined to draft this one.");
-  if (m.stop_reason === "max_tokens") throw new Error("The reply was cut off (max_tokens).");
-  return (m.content ?? []).filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
-}
-
-// ../core/src/explorations.ts
-var EXPLORATION_LABEL = "exploration";
-var EXPLORATION_PREFIX = "explore/";
-var EXPLORATION_NOTES_DIR = ".bridge/explorations";
-var EXPLORATION_READY_LABEL = "ready-for-devs";
-var EXPLORATION_ARCHIVED_LABEL = "archived";
-var EXPLORATION_USE_CASES = [
-  { value: "user-test", label: "Prototype for a user test", hint: "A coded prototype in a test version of a product, with the real components and tokens." },
-  { value: "stakeholder-demo", label: "Stakeholder demo", hint: "Show an idea on real screens before anyone signs off on it." },
-  { value: "ab-idea", label: "A/B idea", hint: "Ship a variant to a test version of a product and compare it with what is live." },
-  { value: "terminal", label: "Exploring with Claude Code", hint: "A designer works from the terminal with Claude and the Bridge MCP server inside this exploration, never in the library." },
-  { value: "other", label: "Other", hint: "Anything else worth trying before it becomes a change." }
-];
-var EXPLORATION_STATUS_LABEL = {
-  active: "Running",
-  ready: "Waiting for code",
-  building: "Being built",
-  shipped: "Shipped",
-  promoted: "Promoted to review",
-  closed: "Closed"
-};
-var MARK = "bridge-exploration";
-var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-var EXPLORATION_SLUG_MAX = 60;
-function explorationSlug(name) {
-  const s = name.trim().replace(/^explore\//i, "");
-  if (!/[a-z0-9]/i.test(s)) return "";
-  return slugify(s, EXPLORATION_SLUG_MAX);
-}
-function explorationBranch(nameOrBranch) {
-  return `${EXPLORATION_PREFIX}${explorationSlug(nameOrBranch)}`;
-}
-function isExplorationBranch(ref) {
-  const r = (ref ?? "").replace(/^refs\/heads\//, "");
-  return r.startsWith(EXPLORATION_PREFIX) && SLUG_RE.test(r.slice(EXPLORATION_PREFIX.length));
-}
-var REPO_NAME = /^[\w.-]+\/[\w.-]+$/;
-var KEY_NAME = /^[a-z0-9][a-z0-9-]*$/i;
-function parseExplorationRef(input) {
-  if (typeof input === "number") return { ref: input };
-  const s = input.trim();
-  const link = /^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/i.exec(s);
-  if (link) return { repo: `${link[1]}/${link[2]}`, ref: Number(link[3]) };
-  if (/^#?\d+$/.test(s)) return { ref: Number(s.replace(/^#/, "")) };
-  const hash = /^(.+)#(\d+)$/.exec(s);
-  if (hash) {
-    const where2 = hash[1].trim();
-    if (REPO_NAME.test(where2)) return { repo: where2, ref: Number(hash[2]) };
-    if (KEY_NAME.test(where2)) return { product: where2.toLowerCase(), ref: Number(hash[2]) };
-  }
-  const named = /^([a-z0-9][a-z0-9-]*):(.+)$/i.exec(s);
-  if (named) return { product: named[1].toLowerCase(), ref: /^#?\d+$/.test(named[2].trim()) ? Number(named[2].trim().replace(/^#/, "")) : named[2].trim() };
-  return { ref: s };
-}
-var explorationRefLabel = (x) => x.repo && x.product ? `${x.product}#${x.number}` : `#${x.number}`;
-var explorationNotePath = (slug3) => `${EXPLORATION_NOTES_DIR}/${slug3}.md`;
-function explorationProblems(e) {
-  const out = [];
-  const name = e.name.trim();
-  const slug3 = e.slug?.trim() || explorationSlug(name);
-  if (!name) out.push('Name the exploration, for example "Denser data tables".');
-  else if (name.length > 60) out.push("Keep the name under 60 characters: it becomes the exploration's link name.");
-  else if (slug3.length < 2 || !SLUG_RE.test(slug3)) out.push("Use letters or digits in the name: it becomes the exploration's link name.");
-  return out;
-}
-var useCaseLabel = (u) => EXPLORATION_USE_CASES.find((x) => x.value === u)?.label;
-function explorationNote(e) {
-  const slug3 = e.slug || explorationSlug(e.name);
-  const uc = useCaseLabel(e.useCase);
-  return [
-    `# Exploration: ${e.name.trim()}`,
+    "## Checks",
     "",
-    ...e.purpose?.trim() ? [e.purpose.trim(), ""] : [],
-    `- Branch: \`${EXPLORATION_PREFIX}${slug3}\``,
-    ...uc ? [`- Use case: ${uc}`] : [],
-    ...e.startedAt ? [`- Started: ${e.startedAt.slice(0, 10)}${e.author ? ` by @${e.author}` : ""}`] : [],
+    `- Token validation: ${errors.length ? `**${errors.length} error(s)**` : "no errors"} (DTCG shapes, aliases, every mode)${warnings.length ? `, ${warnings.length} warning(s): ${warnings.map((w) => w.message).join(" ")}` : ""}`,
+    `- Contrast gate for ${plan.name}: ${plan.contrast.failing.length ? `**${plan.contrast.failing.length} failing pair(s)**` : `all ${plan.contrast.checks} pairs pass`}`,
     "",
-    'This file marks the branch as an exploration. It is never merged as is: "Done exploring" removes it before developers take the branch.',
-    ""
-  ].join("\n");
-}
-function explorationPrTitle(e) {
-  const n = e.name.trim().replace(/\.$/, "").replace(/^exploration\s*:\s*/i, "").replace(/\s*:\s+/g, ", ").trim();
-  return `Exploration: ${n}`;
-}
-function explorationPrBody(e, ctx) {
-  const slug3 = e.slug || explorationSlug(e.name);
-  const branch = `${EXPLORATION_PREFIX}${slug3}`;
-  const uc = useCaseLabel(e.useCase);
-  const experimental = (e.experimental ?? []).map((x) => x.trim()).filter(Boolean);
-  const lines2 = [
-    `## Exploration: ${e.name.trim()}`,
+    "## Authored by",
     "",
-    `> Not mergeable as is. This draft pull request is a living prototype on \`${branch}\`: say "Done exploring" when the idea is ready for developers. Keep it open, so its preview link keeps working.`,
+    opts.agent ? "- [ ] Human" : "- [x] Human",
+    opts.agent ? "- [x] AI agent (Claude), reviewed by a human before merge" : "- [ ] AI agent",
     "",
-    ...e.purpose?.trim() ? [`**Purpose.** ${e.purpose.trim()}`, ""] : [],
-    ...uc ? [`**Use case.** ${uc}`, ""] : [],
-    "### What is experimental",
+    "## Design review checklist",
     "",
-    ...experimental.length ? experimental.map((x) => `- ${x}`) : [ctx.inProduct ? `- The ${ctx.inProduct.name} screens and flows built on this branch with the library. Nothing here reaches main or production.` : "- Token edits and component work committed to this branch. Nothing here reaches main or production."],
-    ...ctx.requests?.length ? ["", "Requests implemented here:", ...ctx.requests.map((r) => `- #${r.number} ${r.title}`)] : [],
+    "- [ ] Checked in light and dark, with real components (Studio preview or Storybook brand switch)",
+    "- [ ] Primary, zone and link colors read as one family",
+    "- [ ] Changeset bump matches the tier",
     ""
-  ];
-  if (ctx.inProduct) {
-    const p = ctx.inProduct;
-    lines2.push(
-      "### Work on it",
-      "",
-      `This exploration lives in the ${p.name} repository, so it runs in your usual environment: \`git fetch origin && git switch ${branch}\`, then start ${p.name} as you always do.`,
-      "",
-      `The library comes from npm, as on main. To try library changes that are not released yet, install the snapshot of their branch in ${p.library} (\`npm i @bridge-ds/react@<snapshot>\`): the command is in its "Try this exploration in your product" comment. Library changes are made in ${p.library}, never on this branch.`,
-      "",
-      "### Previews",
-      ""
-    );
-    const url = p.preview ? previewUrl(p.preview, { branch, ...ctx.pr ? { pr: ctx.pr } : {} }) : null;
-    if (p.preview) lines2.push("| App | Preview |", "| --- | --- |", `| ${p.name} | ${url ?? "Link in the Vercel comment on this pull request"} |`);
-    else lines2.push(`The preview deploys of ${p.name}, if it has them, build this branch like any other.`);
-  } else {
-    lines2.push(
-      "### Try it in a product staging branch",
-      "",
-      'In the product repo, on a branch that deploys to staging (production keeps the released version), install the snapshot with the command in the "Try this exploration in your product" comment below. It appears a few minutes after each push and always matches the latest commit.'
-    );
-    lines2.push("", "### Previews", "");
-    const links = resolveBranchPreviews(ctx.apps, { branch, ...ctx.pr ? { pr: ctx.pr } : {} });
-    if (links.length) lines2.push("| App | Preview |", "| --- | --- |", ...links.map((l) => `| ${l.label} | ${l.url ?? "Link in the Vercel comment on this pull request"} |`));
-    else lines2.push("Preview deploys are not set up: add `previews.apps` to `bridge.config.json` (docs/PREVIEWS.md).");
+  ].join("\n");
+}
+
+// ../core/src/docs-draft.ts
+var DOCS_KEYS = ["summary", "preview", "whenToUse", "whenNotToUse", "dos", "donts", "accessibility", "contentGuidelines", "anatomy"];
+var PROSE_KEYS = ["summary", "whenToUse", "whenNotToUse", "dos", "donts", "accessibility", "contentGuidelines"];
+var ACRONYMS = /* @__PURE__ */ new Set(["sm", "md", "lg", "xl", "xs"]);
+function anatomyLabel(className) {
+  if (ACRONYMS.has(className)) return `Size ${className}`;
+  const words = className.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").trim().toLowerCase();
+  if (!words) return className;
+  if (words === "root") return "Container";
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function cssModuleClasses(css) {
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, "").replace(/@keyframes\s+[\w-]+\s*\{(?:[^{}]*\{[^{}]*\})*[^{}]*\}/g, "");
+  const out = [];
+  for (const m of clean.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)) {
+    const before = clean[m.index - 1] ?? " ";
+    if (/[\w)]/.test(before)) continue;
+    if (!out.includes(m[1])) out.push(m[1]);
   }
-  lines2.push(
+  return out;
+}
+var cell = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+function propsTable(name, props, inherits) {
+  if (!props.length) return inherits ? `${name} has no props of its own. It accepts every native <${inherits}> attribute.` : "";
+  const rows = props.map((p) => `| \`${p.name}\`${p.required ? " (required)" : ""} | \`${cell(p.type)}\` | ${p.defaultValue ? `\`${cell(p.defaultValue)}\`` : ""} | ${cell(p.description ?? "")} |`);
+  const tail = inherits ? `
+
+Also accepts every native <${inherits}> attribute.` : "";
+  return ["| Prop | Type | Default | Description |", "| --- | --- | --- | --- |", ...rows].join("\n") + tail;
+}
+var isEmpty = (v) => v === void 0 || v === null || typeof v === "string" && !v.trim() || Array.isArray(v) && v.length === 0;
+function missingProse(d) {
+  return PROSE_KEYS.filter((k) => isEmpty(d?.[k]));
+}
+function prefillDocs(input) {
+  const existing = input.existing ?? null;
+  const anatomy = {};
+  for (const c of input.cssClasses) anatomy[c] = existing?.anatomy?.[c] ?? anatomyLabel(c);
+  const contrastNotes = (input.contrast ?? []).slice().sort((a, b) => a.ratio - b.ratio).map((p) => `${p.foreground} on ${p.background}: ${p.ratio.toFixed(2)}:1 at worst over every brand and theme, needs ${p.min}:1 (${p.ratio >= p.min ? "passes" : "fails"}).`);
+  const missing = missingProse(existing);
+  const changelogLine = input.change ? `${input.name}: ${input.change.replace(/\.$/, "")}.` : missing.length === PROSE_KEYS.length ? `${input.name}: usage guidance added.` : `${input.name}: usage guidance updated.`;
+  const draft = {
+    summary: existing?.summary ?? input.description ?? "",
+    ...existing?.category ? { category: existing.category } : {},
+    ...existing?.status ? { status: existing.status } : {},
+    ...existing?.preview ? { preview: existing.preview } : {},
+    whenToUse: existing?.whenToUse ?? [],
+    whenNotToUse: existing?.whenNotToUse ?? [],
+    dos: existing?.dos ?? [],
+    donts: existing?.donts ?? [],
+    accessibility: existing?.accessibility ?? [],
+    contentGuidelines: existing?.contentGuidelines ?? [],
+    anatomy,
+    ...existing?.draftedBy ? { draftedBy: existing.draftedBy } : {},
+    ...existing?.draftedSections?.length ? { draftedSections: existing.draftedSections } : {},
+    ...existing?.needsReview !== void 0 ? { needsReview: existing.needsReview } : {}
+  };
+  return {
+    component: input.name,
+    propsTable: propsTable(input.name, input.props, input.inherits),
+    tokens: [...new Set(input.tokens)].sort(),
+    inheritedTokens: input.inheritedTokens ?? {},
+    anatomy,
+    contrastNotes,
+    changelogLine,
+    missing,
+    draft
+  };
+}
+var SECTION_SHAPE = {
+  summary: '"summary": "one or two sentences"',
+  whenToUse: '"whenToUse": ["..."]',
+  whenNotToUse: '"whenNotToUse": ["..."]',
+  dos: '"dos": [{ "title": "...", "text": "..." }]',
+  donts: '"donts": [{ "title": "...", "text": "..." }]',
+  accessibility: '"accessibility": ["..."]',
+  contentGuidelines: '"contentGuidelines": ["..."]'
+};
+var docsSectionShapes = (keys) => `{ ${keys.map((k) => SECTION_SHAPE[k]).join(", ")} }`;
+function docsPrompt(prefill, conventions = {}, options = {}) {
+  const facts = [
+    `Component: ${prefill.component}`,
+    prefill.propsTable ? `Props (parsed from TypeScript):
+${prefill.propsTable}` : "Props: none of its own.",
+    `Tokens its stylesheet reads: ${prefill.tokens.join(", ") || "none"}`,
+    ...Object.entries(prefill.inheritedTokens).map(([from, list]) => `Tokens it reads through ${from}'s stylesheet: ${list.length}`),
+    `Anatomy (CSS module classes): ${Object.entries(prefill.anatomy).map(([k, v]) => `${k} = ${v}`).join("; ") || "none"}`,
+    prefill.contrastNotes.length ? `Contrast checks:
+- ${prefill.contrastNotes.join("\n- ")}` : "",
+    `Changelog line: ${prefill.changelogLine}`
+  ].filter(Boolean);
+  const block = (title, text) => text?.trim() ? `<${title}>
+${text.trim()}
+</${title}>` : "";
+  const keys = options.keys;
+  const check = keys ? (options.check ?? []).filter((k) => keys.includes(k)) : [];
+  const write = keys ? keys.filter((k) => !check.includes(k)) : [];
+  const task = keys ? [
+    ...write.length ? [`${options.rewrite ? "Rewrite" : "Write"} these sections of ${prefill.component}.docs.json for the Bridge design system: ${write.join(", ")}.`] : [],
+    ...check.length ? [
+      `Check these written sections of ${prefill.component}.docs.json against the current code: ${check.join(", ")}. The code changed after they were written.`,
+      "Return a checked section ONLY when something in it is no longer true for the code (a wrong or removed prop, a removed state or variant, changed behavior). Then return the whole section with only the untrue parts fixed, keeping the writer's wording everywhere else.",
+      "Leave a checked section out of the answer when it is still accurate: a missing key means unchanged. Never return a checked section just to improve its style."
+    ] : [],
+    ...options.rewrite ? ["Rewrite each one from the facts and the source: keep what is true in the current text, drop what the code does not support."] : []
+  ] : [`Write the missing prose of ${prefill.component}.docs.json for the Bridge design system.`];
+  const shape2 = keys ? [
+    `- ${check.length ? "Return" : "Write"} only these keys: ${keys.join(", ")}${check.length ? ` (the checked ones, ${check.join(", ")}, only when they need a fix)` : ""}. Never return anatomy, preview or any other key: code decides them.`,
+    `- Answer with one JSON object holding only those keys, nothing else: ${docsSectionShapes(keys)}.`
+  ] : [
+    `- Fill only these keys: ${prefill.missing.join(", ") || "none (everything is written: improve nothing, return the draft as is)"}. Keep every other key exactly as given.`,
+    "- Answer with the full docs.json as one JSON object, nothing else."
+  ];
+  return [
+    ...task,
     "",
-    "### When it is done",
+    "Rules:",
+    "- Ground every sentence in the facts and the source below. Never invent props, variants, keyboard behavior or tokens that are not there.",
+    "- Bridge voice: sentence case, plain words, verbs first, no em dashes, no marketing words.",
+    '- Keep the keys and shapes of the example docs.json. dos and donts are { "title", "text" } objects; add an "example" only with components and props that exist.',
+    ...shape2,
     "",
-    `- **Done exploring:** on the exploration's page in Bridge Studio, or \`bridge explore done ${slug3}\`. Bridge removes the \`${EXPLORATION_LABEL}\` label and the exploration note, adds \`${EXPLORATION_READY_LABEL}\`, and sends the pieces the designer picks to the DS lead as requests. Nothing is closed or merged: developers continue on \`${branch}\`.`,
-    `- **Archive:** \`bridge explore archive ${slug3}\` adds the \`${EXPLORATION_ARCHIVED_LABEL}\` label. Keep this pull request open: ${ctx.inProduct ? "Bridge follows open explorations, and its preview link is how people come back to the prototype." : "closing it removes the preview prerelease."}`,
+    "Facts computed from the code:",
+    facts.join("\n\n"),
     "",
-    explorationBlock({ ...e, slug: slug3 })
-  );
-  return lines2.join("\n");
+    `Current draft:
+${JSON.stringify(prefill.draft, null, 2)}`,
+    "",
+    block("source", conventions.source),
+    block("styles", conventions.styles),
+    block("agents-md", conventions.agents),
+    block("voice", conventions.voice),
+    block("example-docs-json", conventions.example)
+  ].filter((x, i, all) => x !== "" || all[i - 1] !== "").join("\n");
 }
-function explorationBlock(e) {
-  const experimental = (e.experimental ?? []).map((x) => x.trim()).filter(Boolean);
-  const data = {
-    name: e.name.trim(),
-    purpose: (e.purpose ?? "").trim(),
-    slug: e.slug || explorationSlug(e.name),
-    ...e.useCase ? { useCase: e.useCase } : {},
-    ...experimental.length ? { experimental } : {},
-    ...e.author ? { author: e.author } : {},
-    ...e.startedAt ? { startedAt: e.startedAt } : {},
-    ...e.source ? { source: e.source } : {},
-    ...e.agent ? { agent: e.agent } : {},
-    ...e.doneAt ? { doneAt: e.doneAt } : {},
-    ...e.doneSha ? { doneSha: e.doneSha } : {}
-  };
-  return `<!-- ${MARK} ${JSON.stringify(data).replace(/-->/g, "--\\u003e")} -->`;
+function markClaudeDraft(d, sections2) {
+  if (!sections2) {
+    const { draftedSections: _all, ...rest } = d;
+    return { ...rest, draftedBy: "claude", needsReview: true };
+  }
+  const waiting = d.needsReview === true ? d.draftedSections ?? (d.draftedBy ? [...PROSE_KEYS] : []) : [];
+  const union = PROSE_KEYS.filter((k) => waiting.includes(k) || sections2.includes(k));
+  return { ...d, draftedBy: "claude", needsReview: true, draftedSections: union };
 }
-function parseExplorationBody(body) {
-  if (!body) return void 0;
-  const m = new RegExp(`<!-- ${MARK} (\\{[\\s\\S]*?\\}) -->`).exec(body);
-  if (!m) return void 0;
-  try {
-    const e = JSON.parse(m[1]);
-    if (!e || typeof e.name !== "string") return void 0;
-    return typeof e.purpose === "string" ? e : e.purpose === void 0 ? { ...e, purpose: "" } : void 0;
+function formatDocsJson(d) {
+  const order = ["summary", "category", "status", ...DOCS_KEYS.filter((k) => k !== "summary"), "draftedBy", "draftedSections", "needsReview"];
+  const out = {};
+  for (const k of order) if (d[k] !== void 0) out[k] = d[k];
+  for (const [k, v] of Object.entries(d)) if (!(k in out) && v !== void 0) out[k] = v;
+  return `${JSON.stringify(out, null, 2)}
+`;
+}
+function patchNode(old, next) {
+  if (plainEqual(toPlain(old), next)) return old;
+  if (old.kind === "object" && next && typeof next === "object" && !Array.isArray(next)) {
+    const n = next;
+    const kept = old.entries.filter((e) => n[e.key] !== void 0).map((e) => ({ key: e.key, value: patchNode(e.value, n[e.key]) }));
+    const added = Object.keys(n).filter((k) => n[k] !== void 0 && !getEntry(old, k)).map((k) => ({ key: k, value: fromPlain(n[k], void 0, old.inline) }));
+    return { kind: "object", inline: old.inline, entries: [...kept, ...added] };
+  }
+  if (old.kind === "array" && Array.isArray(next)) {
+    return { kind: "array", inline: old.inline, items: next.map((v, i) => old.items[i] ? patchNode(old.items[i], v) : fromPlain(v, old.items[0], old.inline)) };
+  }
+  return fromPlain(next, old);
+}
+function patchDocsJson(original, next) {
+  const plain2 = JSON.parse(formatDocsJson(next));
+  if (!original) return formatDocsJson(next);
+  try {
+    const doc = parseJson(original);
+    if (doc.root.kind !== "object") return formatDocsJson(next);
+    return serializeJson({ ...doc, root: patchNode(doc.root, plain2) });
   } catch {
-    return void 0;
+    return formatDocsJson(next);
   }
 }
-var labelNames = (labels) => labels.map((l) => typeof l === "string" ? l : l.name ?? "");
-function isExplorationPull(p) {
-  return isExplorationBranch(p.headRef) || labelNames(p.labels).includes(EXPLORATION_LABEL) || Boolean(parseExplorationBody(p.body));
+
+// ../core/src/change-drafts.ts
+function cleanDraftText(text) {
+  return text.replace(/\s*\u2014\s*/g, ", ").replace(/,\s*,/g, ",").replace(/^,\s*/, "").replace(/[ \t]+/g, " ").trim();
 }
-function isUnlabeledExploration(p) {
-  if (p.state !== "open" || p.draft !== true) return false;
-  const names4 = labelNames(p.labels ?? []);
-  if (names4.includes(EXPLORATION_LABEL) || names4.includes(EXPLORATION_ARCHIVED_LABEL) || names4.includes(EXPLORATION_READY_LABEL)) return false;
-  const block = parseExplorationBody(p.body);
-  if (block?.doneAt) return false;
-  return isExplorationBranch(p.headRef) || Boolean(block);
+var andList = (xs) => xs.length <= 1 ? xs[0] ?? "" : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`;
+var capital = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+var VARIANT_FIRST = ["variant", "tone", "intent", "appearance", "kind", "type", "style"];
+function shortVariant(key) {
+  const pairs = key.split(", ").map((p) => {
+    const at = p.indexOf("=");
+    return at < 0 ? { k: "", v: p.trim() } : { k: p.slice(0, at).trim(), v: p.slice(at + 1).trim() };
+  });
+  const kept = pairs.filter((p) => p.v && !/^default$/i.test(p.v));
+  if (!kept.length) return key;
+  const rank2 = (k) => {
+    const i = VARIANT_FIRST.indexOf(k.toLowerCase());
+    return i < 0 ? VARIANT_FIRST.length : i;
+  };
+  return kept.map((p, i) => ({ ...p, i })).sort((a, b) => rank2(a.k) - rank2(b.k) || a.i - b.i).map((p) => p.v).join(" ");
 }
-function isHandedOff(p) {
-  return labelNames(p.labels).includes(EXPLORATION_READY_LABEL) || Boolean(parseExplorationBody(p.body)?.doneAt);
+var shortVariants = (list) => list ? andList(list.split("; ").map(shortVariant)) : "every variant";
+var DRAFT_LINE_MAX = 120;
+function clipText(text, max) {
+  const t = text.replace(/\s+/g, " ").trim().replace(/\.$/, "");
+  if (t.length <= max) return t;
+  const 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 explorationStatus(p) {
-  const merged = Boolean(p.merged || p.merged_at || p.state === "merged");
-  if (p.state !== "open" && !merged) return "closed";
-  if (p.state === "open" && (labelNames(p.labels).includes(EXPLORATION_LABEL) || isUnlabeledExploration(p))) return "active";
-  if (!isHandedOff(p)) return "promoted";
-  if (merged) return "shipped";
-  if (p.draft === false) return "building";
-  const doneSha = parseExplorationBody(p.body)?.doneSha;
-  if (doneSha && p.headSha && p.headSha !== doneSha) return "building";
-  return "ready";
+function sanitizeDraftLine(raw) {
+  if (typeof raw !== "string") return "";
+  return capital(clipText(cleanDraftText(raw.replace(/[\r\n]+/g, " ")), DRAFT_LINE_MAX));
 }
-var isActiveExploration = (labels) => labelNames(labels).includes(EXPLORATION_LABEL);
-var isArchivedExploration = (labels) => labelNames(labels ?? []).includes(EXPLORATION_ARCHIVED_LABEL);
-function isHeldExploration(p) {
-  if (p.state !== void 0 && p.state !== "open") return false;
-  const names4 = labelNames(p.labels ?? []);
-  if (names4.includes(EXPLORATION_LABEL) || names4.includes(EXPLORATION_ARCHIVED_LABEL)) return true;
-  if (isUnlabeledExploration({ state: "open", draft: p.draft, labels: p.labels, headRef: p.headRef ?? p.head?.ref, body: p.body })) return true;
-  return names4.includes(EXPLORATION_READY_LABEL) && p.draft !== false;
+
+// ../core/src/docs-ai.ts
+var DOCS_DRAFT_MODEL = "claude-sonnet-5-5";
+var ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+var DOCS_SELECTION_MODES = {
+  clearer: "Make it clearer: plain words, one idea per sentence, the most useful fact first.",
+  shorter: "Make it shorter: keep every fact, drop filler, aim for half the words or fewer.",
+  voice: "Put it in the Bridge voice: sentence case, verbs first, calm and precise, no marketing words, no em dash."
+};
+var isDocsSelectionMode = (m) => typeof m === "string" && m in DOCS_SELECTION_MODES;
+var isProseKey = (k) => typeof k === "string" && PROSE_KEYS.includes(k);
+function validateDocsTask(x) {
+  if (!x || typeof x !== "object") return ["The docs task is missing."];
+  const t = x;
+  if (t.kind === "sections") {
+    const keys = t.keys;
+    if (!Array.isArray(keys) || !keys.length || !keys.every(isProseKey)) return [`The docs task lists no sections: use ${PROSE_KEYS.join(", ")}.`];
+    if (t.check !== void 0 && (!Array.isArray(t.check) || !t.check.every(isProseKey))) return ["check must list prose sections."];
+    return [];
+  }
+  if (t.kind === "selection") {
+    const out = [];
+    if (!isProseKey(t.key)) out.push(`The selection needs a section: ${PROSE_KEYS.join(", ")}.`);
+    if (typeof t.text !== "string" || !t.text.trim()) out.push("The selection has no text.");
+    if (!isDocsSelectionMode(t.mode)) out.push("The selection mode must be clearer, shorter or voice.");
+    return out;
+  }
+  return ['The docs task kind must be "sections" or "selection".'];
 }
-var explorationTakeCommands = (branch) => ["git fetch origin", `git checkout ${branch}`];
-var CONTINUE = "Continue on this branch: its pull request already exists, so Bridge follows your pushes, and the merge reads as shipped.";
-var EXPLORATION_STARTING_POINT = `A starting point, not ready to ship: nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
-function explorationStartingPoint(checks) {
-  switch (checks) {
-    case "success":
-      return `A starting point: its checks pass, but nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
-    case "failure":
-      return `A starting point, not ready to ship: some checks fail on this branch and nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
-    case "pending":
-      return `A starting point, not ready to ship: its checks are still running and nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
-    case "none":
-      return `A starting point, not ready to ship: no checks ran on this branch and nobody has reviewed Claude's prototype code yet. ${CONTINUE}`;
-    default:
-      return EXPLORATION_STARTING_POINT;
+var docsTaskKeys = (t) => t.kind === "sections" ? t.keys : [t.key];
+function parseDocsReply(text) {
+  const fenced2 = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+  const body = fenced2 ? fenced2[1] : text;
+  const start = body.indexOf("{");
+  const end = body.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new Error("The reply holds no JSON object.");
+  const json = JSON.parse(body.slice(start, end + 1));
+  if (!json || typeof json !== "object" || Array.isArray(json)) throw new Error("The reply is not a docs.json object.");
+  return json;
+}
+var cleanDocsText = (s) => cleanDraftText(s.replace(/[\r\n]+/g, " "));
+var isExample = (x) => {
+  if (typeof x === "string") return true;
+  if (!x || typeof x !== "object" || Array.isArray(x)) return false;
+  const n = x;
+  if (typeof n.c !== "string" || !n.c) return false;
+  if (n.p !== void 0 && (!n.p || typeof n.p !== "object" || Array.isArray(n.p))) return false;
+  return n.children === void 0 || Array.isArray(n.children) && n.children.every(isExample);
+};
+var textList = (x) => {
+  if (typeof x === "string") x = [x];
+  if (!Array.isArray(x)) return void 0;
+  const out = x.filter((s) => typeof s === "string").map(cleanDocsText).filter(Boolean);
+  return out.length ? out : void 0;
+};
+var guidanceList = (x, examples) => {
+  if (!Array.isArray(x)) return void 0;
+  const out = [];
+  for (const g of x) {
+    if (!g || typeof g !== "object") continue;
+    const r = g;
+    const title = typeof r.title === "string" ? cleanDocsText(r.title) : "";
+    const text = typeof r.text === "string" ? cleanDocsText(r.text) : "";
+    if (!title || !text) continue;
+    out.push({ title, text, ...examples && r.example !== void 0 && isExample(r.example) ? { example: r.example } : {} });
+  }
+  return out.length ? out : void 0;
+};
+function sanitizeDocsSections(raw, keys = PROSE_KEYS, opts = {}) {
+  const out = {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  const r = raw;
+  for (const k of keys) {
+    const v = r[k];
+    if (k === "summary") {
+      const s = typeof v === "string" ? cleanDocsText(v) : "";
+      if (s) out.summary = s;
+    } else if (k === "dos" || k === "donts") {
+      const g = guidanceList(v, opts.examples ?? false);
+      if (g) out[k] = g;
+    } else {
+      const l = textList(v);
+      if (l) out[k] = l;
+    }
   }
+  return out;
 }
-function doneExploringPlan(input) {
-  const removeFiles = input.files.filter((f) => f.path.startsWith(`${EXPLORATION_NOTES_DIR}/`) && f.status !== "removed").map((f) => f.path);
-  return {
-    removeLabels: [EXPLORATION_LABEL],
-    addLabels: [EXPLORATION_READY_LABEL],
-    removeFiles,
-    body: withDoneExploring(input.body, { branch: input.branch, doneAt: (input.date ?? /* @__PURE__ */ new Date()).toISOString() }),
-    take: explorationTakeCommands(input.branch),
-    markReady: false
-  };
+function sanitizeDocsReplacement(raw) {
+  if (typeof raw !== "string") return "";
+  return cleanDocsText(raw.trim().replace(/^["'“]+|["'”]+$/g, ""));
 }
-var DEV_SECTION = "### For developers";
-function withDoneExploring(body, done) {
-  const e = parseExplorationBody(body);
-  const [fetch2, checkout] = explorationTakeCommands(done.branch);
-  const section = [
-    DEV_SECTION,
-    "",
-    `**Done exploring on ${done.doneAt.slice(0, 10)}.** ${explorationStartingPoint(done.checks)}`,
-    "",
-    "```sh",
-    fetch2,
-    checkout,
-    "```",
-    "",
-    "Mark this pull request ready for review when the code is yours. Keep it open: its preview link is how designers, the DS lead and stakeholders come back to the prototype."
-  ].join("\n");
-  const block = new RegExp(`<!-- ${MARK} \\{[\\s\\S]*?\\} -->`);
-  const kept = (body ?? "").replace(/^> Not mergeable as is\..*$\n?\n?/m, "").replace(/### When it is done[\s\S]*?(?=<!-- |$)/, "").replace(/### For developers[\s\S]*?(?=### |<!-- |$)/, "");
-  if (!e || !block.test(kept)) return `${kept.trim()}${kept.trim() ? "\n\n" : ""}${section}`;
-  const at = kept.search(block);
-  const nextBlock = explorationBlock({ ...e, doneAt: done.doneAt, ...done.doneSha ? { doneSha: done.doneSha } : {} });
-  const after = kept.slice(at).replace(block, () => nextBlock).trim();
-  return `${kept.slice(0, at).trim()}
-
-${section}
-
-${after}`.trim();
+function docsSectionsAnswer(task, raw) {
+  const check = (task.check ?? []).filter((k) => task.keys.includes(k));
+  const sections2 = check.length ? sanitizeDocsSections(raw, task.keys) : docsSectionsResult(task, raw);
+  return { sections: sections2, checked: check.filter((k) => sections2[k] === void 0) };
 }
-function explorationTryIt(input) {
-  const c = readPreviewComment(input.comment);
-  if (!c) return { state: "building" };
-  if (input.headSha && c.sha7 && !input.headSha.startsWith(c.sha7)) return { state: "building" };
-  if (!c.command || c.source === "none") return { state: "failed" };
-  return { state: "ready", command: c.command, source: c.source, sha7: c.sha7 };
+function docsSectionsResult(task, raw) {
+  const sections2 = sanitizeDocsSections(raw, task.keys);
+  if (!Object.keys(sections2).length) throw new Error(`Claude's answer holds none of the sections asked for (${task.keys.join(", ")}). Try again.`);
+  return sections2;
 }
-function explorationRules(branch) {
-  return [
-    `- Work on the existing branch ${branch} (git fetch origin && git switch ${branch}). Commit there.`,
-    `- Do not open a pull request to main and do not create another branch: the draft pull request of ${branch} is the place. It stays open as a living prototype.`,
-    `- Do not mark the pull request ready for review, do not remove the exploration label and never close it: "Done exploring" is a person's decision, and closing removes its preview.`
-  ];
+function mergeDocsDraft(prefillDraft, reply) {
+  const empty = PROSE_KEYS.filter((k) => {
+    const v = prefillDraft[k];
+    return v === void 0 || (typeof v === "string" ? !v.trim() : Array.isArray(v) && !v.length);
+  });
+  const sections2 = sanitizeDocsSections(reply, empty, { examples: true });
+  const merged = { ...prefillDraft, ...sections2 };
+  if (reply.preview && !prefillDraft.preview && isExample(reply.preview)) merged.preview = reply.preview;
+  merged.anatomy = prefillDraft.anatomy;
+  const drafted = PROSE_KEYS.filter((k) => sections2[k] !== void 0);
+  return markClaudeDraft(merged, drafted.length && drafted.length < PROSE_KEYS.length ? drafted : void 0);
+}
+function anthropicRequest(input) {
+  const headers = { "x-api-key": input.apiKey, "anthropic-version": "2023-06-01", "content-type": "application/json" };
+  if (input.fallback) headers["anthropic-beta"] = "server-side-fallback-2026-07-01";
+  if (input.browser) headers["anthropic-dangerous-direct-browser-access"] = "true";
+  const body = {
+    model: input.model || DOCS_DRAFT_MODEL,
+    max_tokens: input.maxTokens ?? 16e3,
+    ...input.fallback ? { fallbacks: "default" } : {},
+    ...input.system ? { system: input.system } : {},
+    messages: [{ role: "user", content: input.prompt }]
+  };
+  return { url: ANTHROPIC_MESSAGES_URL, init: { method: "POST", headers, body: JSON.stringify(body) } };
+}
+function anthropicReplyText(msg) {
+  const m = msg ?? {};
+  if (m.stop_reason === "refusal") throw new Error("Claude declined to draft this one.");
+  if (m.stop_reason === "max_tokens") throw new Error("The reply was cut off (max_tokens).");
+  return (m.content ?? []).filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
 }
 
 // ../core/src/titles.ts
@@ -6089,7 +6099,7 @@ async function doneExploringOnGitHub(gh, ref, input = {}) {
   const files = fresh ? await gh.listPullRequestFiles(p.number) : [];
   const plan = fresh ? doneExploringPlan({ body: p.body, branch: p.headRef, files: files.map((f) => ({ path: f.filename, status: f.status })), date: input.date }) : null;
   const take = plan?.take ?? ["git fetch origin", `git checkout ${p.headRef}`];
-  const checks = p.headSha ? await Promise.resolve(p.headSha).then((sha) => gh.getChecks(sha)).then((c) => c.state, () => null) : null;
+  const checks = p.headSha ? await Promise.resolve(p.headSha).then((sha) => gh.getChecks(sha, { exploration: isGuardedExploration({ state: p.state, draft: p.draft, labels: p.labels, headRef: p.headRef, body: p.body }) })).then((c) => c.state, () => null) : null;
   const out = { number: p.number, url: p.url, branch: p.headRef, status: fresh ? "ready" : status, handedOff: fresh, plan, pieces: { proposed: [], already: [], unknown: [], warnings: [] }, take, checks, note: explorationStartingPoint(checks), warnings: [] };
   const products = input.products ?? [];
   const ask = { pieces: input.pieces ?? [], products, previewUrl: input.previewUrl, openedBy: input.openedBy, agent: input.agent, source: input.source, library: input.library };
@@ -8186,11 +8196,13 @@ function isPlatformRefusal(s) {
   return s.state !== "success" && s.state !== "pending" && /rate.limited/i.test(s.description ?? "");
 }
 var OK = /* @__PURE__ */ new Set(["success", "neutral", "skipped"]);
-function summarizeCi(runs, statuses = []) {
+function summarizeCi(runs, statuses = [], opts = {}) {
   const failed = [];
   const pending = [];
   let passed = 0;
+  const skip = (name) => Boolean(opts.exploration) && isExplorationCheck(name);
   for (const r of runs) {
+    if (skip(r.name)) continue;
     if (r.status !== "completed") pending.push({ name: r.name, url: r.html_url });
     else if (r.conclusion && OK.has(r.conclusion)) passed++;
     else failed.push({ name: r.name, url: r.html_url });
@@ -8199,7 +8211,7 @@ function summarizeCi(runs, statuses = []) {
   for (const s of statuses) {
     if (seen.has(s.context)) continue;
     seen.add(s.context);
-    if (isPlatformRefusal(s)) continue;
+    if (isPlatformRefusal(s) || skip(s.context)) continue;
     if (s.state === "success") passed++;
     else if (s.state === "pending") pending.push({ name: s.context, url: s.target_url ?? void 0 });
     else failed.push({ name: s.context, url: s.target_url ?? void 0 });
@@ -13866,7 +13878,9 @@ async function branchFacts(ctx, gh, n, viewer) {
   const labels = pr.labels.map((name) => ({ name }));
   const ci = summarizeCi(
     runs.map((r) => ({ name: r.name, status: r.status, conclusion: r.conclusion, ...r.url ? { html_url: r.url } : {} })),
-    statuses.map((s) => ({ context: s.context, state: s.state, target_url: s.target_url, description: s.description }))
+    statuses.map((s) => ({ context: s.context, state: s.state, target_url: s.target_url, description: s.description })),
+    // An exploration's guard check fails by design: never a failing test (core isGuardedExploration).
+    { exploration: isGuardedExploration({ state: pr.state, draft: pr.draft, labels: pr.labels, headRef: pr.headRef, body: pr.body }) }
   );
   const reviewLikes = reviews.map((r) => ({ user: r.user ? { login: r.user } : null, state: r.state, submitted_at: r.submittedAt ?? null, commit_id: r.commitId ?? null }));
   const lookAgain = pr.state === "open" ? lookAgainReviewers(reviewLikes, pr.headSha, pr.author) : [];
@@ -15648,7 +15662,7 @@ async function getReview(ctx, a) {
     const gh = await ctx.github();
     if (!gh) throw new Error('No GitHub repo known: set "repo" in bridge.config.json.');
     const pr = await gh.getPullRequest(a.pr);
-    const [files, checks, reviews] = await Promise.all([gh.listPullRequestFiles(a.pr), gh.getChecks(pr.headSha), gh.listReviews(a.pr)]);
+    const [files, checks, reviews] = await Promise.all([gh.listPullRequestFiles(a.pr), gh.getChecks(pr.headSha, { exploration: isGuardedExploration({ state: pr.state, draft: pr.draft, labels: pr.labels, headRef: pr.headRef, body: pr.body }) }), gh.listReviews(a.pr)]);
     baseSrc = new GitHubSource(gh, pr.baseRef);
     headSrc = new GitHubSource(gh, pr.headSha);
     changedFiles = files.map((f) => f.filename);
@@ -17154,7 +17168,7 @@ async function proposeFigmaFixesOp(ctx, a) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.11.2" : "dev";
+var VERSION = true ? "0.11.3" : "dev";
 var BRIDGE_SITE = "https://bridge.floriangouloubi.com";
 var SERVER_INFO = {
   name: "bridge",